v1.16.0.0 feat: gstack-build CLI orchestrator#1
Merged
Conversation
Adds gstack-build CLI skeleton with a robust plan parser. The CLI accepts a plan file path, parses ### Phase N headings + Implementation/Review checkboxes, and prints a status table. Execution loop is stubbed; later phases will add state persistence, sub-agent invocation, and plan mutation. Files: - build/orchestrator/types.ts shared Phase, PhaseState, BuildState types - build/orchestrator/parser.ts markdown parser, fence-aware - build/orchestrator/cli.ts entry point, --print-only / --dry-run flags - build/orchestrator/__tests__/parser.test.ts 12 tests covering edge cases Verified end-to-end against this build's own plan file (8 phases parsed) and the real AGNT2 week-11 plan (9 phases, status correctly inferred). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
State store under ~/.gstack/build-state/<slug>.json with: - atomic writes via temp-file + rename (no half-written state on crash) - O_EXCL-based lock at ~/.gstack/build-state/<slug>.lock for concurrency - corrupt state raises a hard error; user inspects or deletes - freshState seeds runtime state from parsed phases, marks pre-checked phases as already-committed and points currentPhaseIndex at the first unchecked one (resume on first run is essentially free) gbrain integration is deliberately deferred to Phase 6 — JSON path is the source of truth and stays the fallback. 16 unit tests covering: slug derivation, fresh-state seeding, save/load round-trip, corrupt-state error path, lastUpdatedAt mutation, no temp files left behind, lock acquire/release, lock contention, lock-info read. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Three callable wrappers around the gemini, codex, and claude binaries: - runGemini(opts) implements a phase via `gemini -p ... --yolo` - runCodexReview(opts) reviews via `codex exec /gstack-review -s read-only` - runShip(opts) final `claude --model sonnet -p '/ship && /land-and-deploy'` Each invocation captures stdout+stderr to a per-phase log file under ~/.gstack/build-state/<slug>/, returns a SubAgentResult with timing, exit code, timeout flag, and retry count. Single retry on timeout only. Idioms borrowed verbatim from ~/mcp-llm-bridge/src/server.ts: - Codex needs stdin closed or `codex exec` hangs forever (closeStdin: true) - 20MB max buffer for stdout - --yolo on Gemini for autonomous file edits parseVerdict() inspects Codex stdout for GATE PASS / GATE FAIL and returns the LAST verdict (so a fix-pass overrides an earlier fail). ANSI escapes stripped before matching. Case-sensitive on the keyword. Timeouts configurable via env (GSTACK_BUILD_GEMINI_TIMEOUT etc.) with sensible defaults: gemini 10min, codex 15min, ship 30min. 9 unit tests covering ANSI stripping and verdict parsing across edge cases (last-wins, missing keyword, case-sensitivity). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds phase-runner.ts: the pure decide+apply state machine that drives a
single phase through gemini → codex review → mark complete. No I/O, no
spawning — driver in cli.ts owns those side-effects. Pure means trivially
unit-testable: every state transition is one expect() call.
State graph:
pending ──RUN_GEMINI──▶ gemini_done ──RUN_CODEX_REVIEW──▶
if pass: ─▶ review_clean ──MARK_COMPLETE──▶ committed ──DONE
if fail: ─▶ codex_running ──RUN_CODEX_REVIEW (iter+1)──▶ ...
(or ──FAIL when iter > GSTACK_BUILD_CODEX_MAX_ITER)
if unclear / timeout / nonzero exit: ─▶ failed ──FAIL
Plus a small fix to state.freshState(): partial-checked phases
(impl=[x], review=[ ]) now correctly seed as `gemini_done` so the
orchestrator skips Gemini and resumes at Codex review. Previously they
were treated as `pending` and would re-run Gemini unnecessarily.
24 phase-runner tests covering: every state transition, retry/timeout
behavior, immutability of input PhaseState, multi-iteration Codex review
loop with log path accumulation, end-to-end happy path. Test totals now
61 pass / 0 fail across 4 files.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds plan-mutator.ts: flip [ ] → [x] for one or both phase checkboxes, atomically. Read-modify-write the whole plan file via temp + rename (rename is atomic on POSIX, so a crash mid-write can never corrupt the plan). Idempotent — flipping an already-checked box is a no-op, not an error. Verification: before flipping, re-check the target line still contains the expected marker (e.g. "**Implementation"). If the user manually edited the plan between parse and mutate, the flip refuses with a clear "plan was edited externally — re-parse and try again" error rather than silently overwriting. Preserves CRLF line endings if the plan uses them. Cleans up temp file on both success and failure. 11 unit tests covering: basic flip, idempotency, external-edit detection, out-of-range line, non-checkbox line, CRLF preservation, no leakage to sibling checkboxes, no .tmp.* stragglers. Test totals: 72 pass / 0 fail across 5 files. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Wires gbrain into state.ts as a best-effort cross-machine mirror:
- Local JSON at ~/.gstack/build-state/<slug>.json is the source of
truth and the always-write path. Atomic temp+rename, mode 0600.
- gbrain put/get is the secondary mirror. Failures (CLI absent, network
blip, db unavailable) log a warning and DO NOT throw — the orchestrator
must keep running on a single machine even if the cross-machine layer
is down.
- loadState() prefers JSON; if missing AND gbrain available, pulls from
gbrain (resume on a fresh machine). On a successful gbrain pull, the
state is mirrored back to local JSON so the next read is fast.
Idiomatic CLI shape from `gbrain --help`:
- `gbrain put <slug>` reads stdin and wraps content in YAML frontmatter
- `gbrain get <slug>` outputs frontmatter+body; we strip the frontmatter
- `gbrain --version` is a fast availability check (we cache the result
for the session — gbrain doesn't appear/disappear mid-run)
Tests:
- gbrain.ts: 4 unit tests for stripFrontmatter (covers the gbrain banner
prefix, plain content, JSON body, no-frontmatter passthrough). The
subprocess wrappers are exercised in the smoke path of integration —
unit-mocking shell calls is mostly testing the mocks.
- state tests: pass `{ noGbrain: true }` to skip the gbrain mirror in
unit tests so they don't depend on the live db.
- Real round-trip verified manually: saveState → gbrain has the page,
loadState returns matching state.
Test totals: 76 pass / 0 fail across 6 files.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…recovery Wires every previous module into a working CLI. The driver loop: 1. Parse plan → load state (or freshState if --no-resume) → acquire lock 2. SIGINT/SIGTERM handler: save state + release lock + exit 130 3. Per phase: decide action → execute (Gemini or Codex) with state machine transitions persisted after every step → flip checkboxes on completion 4. Final ship: spawn `claude --model sonnet -p '/ship && /land-and-deploy'` unless --skip-ship; the orchestrator delegates to gstack ship skill so CI/CD safety gates still run 5. Activity log appended to ~/.gstack/analytics/build-runs.jsonl New CLI flags: --dry-run walk state machine without spawning sub-agents --no-resume ignore existing state, start fresh --no-gbrain local JSON only --skip-ship stop after final phase, don't ship --max-codex-iter N cap recursive review (default 5) Two contract changes for fix-mode: - Codex sandbox flipped from `read-only` to `workspace-write` (default). The recursive review loop expects review-AND-fix per iteration, not pure reporting. The /gstack-review skill itself decides what to do inside the sandbox; we just give it write permission. Configurable via the new `sandbox` option on runCodexReview. - ship.ts is a tiny façade over runShip — kept separate so future ship variants (skip-deploy, dry-run-ship) live in one place. Verified manually: - Dry-run on the plan-of-this-build (8 phases) advances through every phase without invoking sub-agents and exits clean. - Real run with mocked gemini/codex binaries on a 2-phase tmp plan flips both [ ] → [x] in the plan file, populates the state JSON with timestamps + log paths + verdicts, and exits 0. - Lock contention: second concurrent instance refuses to start, prints pid + timestamp + remediation hint, exits 3. - Activity log: lines appended to ~/.gstack/analytics/build-runs.jsonl on every start and outcome. Open question deferred to manual validation: whether codex review with workspace-write sandbox actually fixes bugs as the loop expects. We'll know on the first real run; the GSTACK_BUILD_CODEX_MAX_ITER cap means we can never hang. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ote (v1.11.0) Final phase. Wires the orchestrator into the gstack install surface. - bin/gstack-build: bash wrapper invoking build/orchestrator/cli.ts via bun run. Tried `bun build --compile` first; the resulting binary got SIGKILL'd by macOS Gatekeeper (exit 137) on this host. Bash wrapper matches the convention used by every other bin/ script in this repo (gstack-config, gstack-slug, gstack-update-check, etc). - package.json: added gstack-build to the bin map. Skipped adding it to the `build` script's bun-compile pipeline because the wrapper doesn't need compilation; it'll just work after `bun install`. - build/orchestrator/README.md: usage, env vars, file layout, failure modes table, exit codes, architecture diagram. Honest about when to use the CLI (5+ phase plans, walk-away workflows) vs. the LLM-driven /build skill (short, exploratory). - build/SKILL.md.tmpl: added an upfront "LLM-driven loop vs. code-driven CLI" note that points users to gstack-build for long plans. Bumped version 1.10.0 → 1.11.0. Regen'd via `bun run gen:skill-docs --host claude`. Verified: ./bin/gstack-build --help works, --print-only on the actual plan-of-this-build correctly identifies 7/8 phases as done (this phase 8 still pending mid-commit). All 76 unit tests still green. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Two findings from /review on this branch:
1. P1 correctness: runShip() was passing `'/ship && /land-and-deploy'`
as a SINGLE -p argument to ONE claude invocation. The `&&` is shell
syntax that claude doesn't interpret inside a prompt — so /ship would
run (or fail) and /land-and-deploy would never fire. The original
/build SKILL.md spec is two separate claude invocations chained by
shell &&, not one. Fix: spawn claude twice in TS, await /ship, bail
if it failed, then await /land-and-deploy. Each gets its own log
file (ship.log, land-and-deploy.log).
Verified end-to-end with mocked claude binary: ship.log shows
`--model sonnet -p /ship` and land-and-deploy.log shows
`--model sonnet -p /land-and-deploy` — two clean invocations.
2. Maintainability: cli.ts had `require('node:child_process').spawnSync`
inside getCurrentBranch() while every other module uses ESM imports.
Promoted to a top-of-file `import { spawnSync } from 'node:child_process'`.
All 76 tests still pass.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds gstack-build CLI orchestrator. New code-driven phase runner that replaces the LLM-orchestrated /build loop for long plans. See full CHANGELOG entry for the module breakdown. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
anbangr
added a commit
that referenced
this pull request
Apr 28, 2026
…(gstack-build v1.15.0)
* feat(dual-impl): Phase 1 — types, worktree, parser dualImpl stamp
- types.ts: 6 new PhaseStatus values (dual_impl_running → dual_winner_pending);
DualImplState + DualImplTestResult interfaces; dualImpl? on Phase + PhaseState
- parser.ts: accepts ParseOpts { dualImpl? }; stamps dualImpl=true on all phases
when flag is set; backward compat — defaults to false
- worktree.ts: createWorktrees (two isolated git worktrees + branches),
teardownWorktrees (idempotent git worktree remove + branch -D),
applyWinner (cherry-pick with patch fallback)
- __tests__/worktree.test.ts: 3 tests against real temp git repo (green)
- __tests__/parser.test.ts: 2 new dualImpl stamping tests (green)
110 tests pass, 0 fail.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(dual-impl): Phase 1 post-review fixes — align WorktreePair field names + os.tmpdir + commit exit codes
- WorktreePair: geminiPath→geminiWorktreePath, codexPath→codexWorktreePath
(aligns with DualImplState so callers can spread directly)
- worktree.ts: use os.tmpdir() instead of hardcoded /tmp
- applyWinner patch fallback: check exit codes of git add + git commit;
return { ok: false } instead of silently returning ok:true on commit failure
- worktree.test.ts: update all field references to new names
110 tests pass, 0 fail.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(dual-impl): Phase 2 — phase-runner state machine + ApplyResultExtra
- 4 new Action types: RUN_DUAL_IMPL, RUN_DUAL_TESTS, RUN_JUDGE_OPUS, APPLY_WINNER
- decideNextAction:
* tests_red + phase.dualImpl=true → RUN_DUAL_IMPL (single-impl unchanged otherwise)
* dual_impl_running → RUN_DUAL_IMPL (crash recovery)
* dual_impl_done → RUN_DUAL_TESTS
* dual_tests_running → RUN_DUAL_TESTS (crash recovery)
* dual_judge_pending / dual_judge_running → RUN_JUDGE_OPUS
* dual_winner_pending → APPLY_WINNER (winner from selectedImplementor)
- applyResult: new optional 4th param ApplyResultExtra carries dual-impl
data (worktree init, test results, judge verdict) that won't fit a
single SubAgentResult
- applyResult handlers:
* RUN_DUAL_IMPL → dual_impl_done (stamps worktree paths/branches)
* RUN_DUAL_TESTS → dual_judge_pending (both pass) | dual_winner_pending
with auto-select (one passes / both fail → fewer-failures winner)
* RUN_JUDGE_OPUS → dual_winner_pending with selectedBy='judge'
* APPLY_WINNER → gemini_done (handoff to existing pipeline)
- 8 new state-machine tests covering all dual-impl transitions
- Existing tddPhase/legacyPhase fixtures updated with dualImpl: false
118 tests pass, 0 fail. Exhaustiveness guard preserved.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(dual-impl): Phase 2 post-review HIGH fixes — fail-closed on missing signal
Three fail-closed paths added (Codex review HIGH findings):
1. dual_winner_pending without selectedImplementor → FAIL
Was silently defaulting to 'gemini' which could apply unverified code if
state was corrupted between persistence and resume.
2. RUN_DUAL_IMPL without dualImplInit in extra → status failed
Was silently transitioning to dual_impl_done without recording worktree
paths, making downstream tests/judge/apply impossible.
3. Both dual-impl test runs timed out → status failed
Was selecting 'gemini' via the both-fail/MAX_SAFE_INTEGER tie path —
applying unverified code with no test evidence at all.
4. Both dual-impl tests failed with missing failureCount on both → failed
Same rationale as (3): no signal to choose a winner.
4 new tests cover the fail-closed paths. 122 tests pass, 0 fail.
CRITICAL finding (cli.ts not handling dual actions) is BY-DESIGN — Phase 4
of the plan wires up the CLI dispatch. Phase 2 scope is the pure state machine.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* v1.16.0.0 feat: tunnel allowlist 17→26 + canDispatchOverTunnel pure function (garrytan#1253)
* feat: extend tunnel allowlist to 26 commands + extract canDispatchOverTunnel
Adds newtab, tabs, back, forward, reload, snapshot, fill, url, closetab to
TUNNEL_COMMANDS (matching what cli.ts and REMOTE_BROWSER_ACCESS.md already
documented). Each new command is bounded by the existing per-tab ownership
check at server.ts:613-624 — scoped tokens default to tabPolicy: 'own-only'
so paired agents still can't operate on tabs they don't own.
Refactors the inline gate check at server.ts:1771-1783 into a pure exported
function canDispatchOverTunnel(command). Same behavior as the inline check;
the difference is unit-testability without HTTP.
Adds BROWSE_TUNNEL_LOCAL_ONLY=1 test-mode flag that binds the second Bun.serve
listener with makeFetchHandler('tunnel') on 127.0.0.1 — no ngrok needed.
Production tunnel still requires BROWSE_TUNNEL=1 + valid NGROK_AUTHTOKEN.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test: source-level guards + pure-function unit test + dual-listener behavioral eval
Three layers of regression coverage for the tunnel allowlist:
1. dual-listener.test.ts: replaces must-include/must-exclude with exact-set
equality on the 26-command literal (the prior intersection-only style let
new commands sneak into the source without test updates). Adds a regex
assertion that the `command !== 'newtab'` ownership exemption at
server.ts:613 still exists — catches refactors that re-introduce the
catch-22 from the other side. Updates the /command handler test to look
for canDispatchOverTunnel(body?.command) instead of the inline check.
2. tunnel-gate-unit.test.ts (new): 53 expects covering all 26 allowed,
20 blocked, null/undefined/empty/non-string defensive handling, and alias
canonicalization (e.g. 'set-content' resolves to 'load-html' which is
correctly rejected since 'load-html' isn't tunnel-allowed).
3. pair-agent-tunnel-eval.test.ts (new): 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 /pair → /connect, and
assert: (a) newtab over tunnel passes the gate; (b) pair over tunnel
403s with disallowed_command:pair AND writes a denial-log entry;
(c) pair over local does NOT trigger the tunnel gate (proves the gate
is surface-scoped); (d) regression for the catch-22 — newtab + goto on
the resulting tab does not 403 with "Tab not owned by your agent".
All four tests run free under bun test (no API spend, no ngrok).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: bump tunnel allowlist count 17 -> 26 in CLAUDE.md and REMOTE_BROWSER_ACCESS.md
Both docs already named the 9 new commands as remote-accessible (the operator
guide's per-command sections at lines 86-119 and 168, plus cli.ts:546-586's
instruction blocks). The allowlist count was the only place the drift was
visible. Also corrected REMOTE_BROWSER_ACCESS.md's denied-commands list:
'eval' is in the allowlist, not the denied list — prior doc was wrong.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore: bump version and changelog (v1.21.0.0)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore: re-version v1.21.0.0 -> v1.16.0.0 (lowest unclaimed slot)
The previous bump landed at v1.21.0.0 because gstack-next-version
advances past the highest claimed slot (v1.20.0.0 from garrytan#1252) rather
than picking the lowest unclaimed. v1.16-v1.18 are unclaimed and
v1.16.0.0 preserves monotonic version ordering on main once garrytan#1234
(v1.17), garrytan#1233 (v1.19), and garrytan#1252 (v1.20) merge after us.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(ci): version-gate enforces collisions, allows lower-but-unclaimed slots
The gate was rejecting any PR VERSION below the util's next-slot
recommendation, even when the lower slot was unclaimed. This blocked
PRs that legitimately want to land at an unclaimed slot below the queue
max — which is what /ship should pick when the goal is monotonic version
ordering on main (lower-numbered PRs landing first preserves order; the
util's "advance past max claimed" semantics only optimizes for fresh
runs picking unique slots, not for queue ordering on merge).
New gate logic:
1. Hard-fail if PR VERSION <= base VERSION (no actual bump).
2. Hard-fail if PR VERSION exactly matches another open PR's VERSION
(real collision).
3. Pass otherwise. If the PR is below the util's suggestion, emit an
informational ::notice:: explaining the slot is unclaimed.
The util's output stays informational — it tells fresh /ship runs what
the next-up slot should be, but the gate only blocks actual conflicts.
This is a strict relaxation: every PR that passed the old gate also
passes the new one.
Confirmed by dry-run against the current queue (4 open PRs claiming
1.17.0.0, 1.19.0.0, 1.21.1.0, 1.22.0.0):
- v1.16.0.0 → pass with informational notice (unclaimed)
- v1.17.0.0 → fail (collision with garrytan#1234)
- v1.15.0.0 → fail (no bump from base)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* v1.17.0.0: setup-gbrain wireup ships the gbrain federation surface (garrytan#1234)
* feat: gstack-gbrain-source-wireup helper + 13 unit tests
The new bin/gstack-gbrain-source-wireup is the single helper that registers
the gstack brain repo as a gbrain federated source via `git worktree`, runs
incremental sync, and supports --uninstall + --probe + --strict modes.
Replaces the dead `consumers.json + ingest_url + /ingest-repo` HTTP wireup
introduced in v1.12.0.0 — that endpoint never shipped on the gbrain side.
The federation surface (`gbrain sources` / `gbrain sync`) shipped in gbrain
v0.18.0; this helper adapts to its actual semantics (no `sources update`, so
path drift recovery is `remove + re-add`; no `--install-cron` either, so
freshness rides on the existing skill-end push hook).
Source-id derivation is multi-fallback: ~/.gstack/.git origin URL →
~/.gstack-brain-remote.txt → --source-id flag. This makes `--uninstall`
work even after `~/.gstack/.git` is destroyed by the parent uninstall script.
Worktree is `--detach`ed at $GSTACK_HOME's HEAD because main is already
checked out there; advance is a re-checkout of the parent's current HEAD,
not a `git pull`. Divergence recovery removes + re-adds the worktree.
Test suite covers 13 cases: fresh-state registration, idempotent re-runs,
drift recovery, --strict failure modes, source-id fallback chain, --probe
non-mutation, sync errors, and --uninstall. Fake gbrain on $PATH, real git
ops at GSTACK_HOME tmp dir.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat: wire setup-gbrain + brain-restore + brain-uninstall to use the helper
setup-gbrain Step 7 now invokes gstack-gbrain-source-wireup --strict after
gstack-brain-init + gbrain_sync_mode is set. Strict mode means the user sees
the failure rather than silently ending up with an unwired brain.
bin/gstack-brain-init drops 60 lines of dead code: the HTTP POST to
${GBRAIN_URL}/ingest-repo, the GBRAIN_URL_VAL/GBRAIN_TOKEN_VAL probes, the
consumers.json writer, and the chore commit step. CONSUMERS_FILE variable
declaration removed. The closing message no longer points at the dead
gstack-brain-consumer add path.
bin/gstack-brain-restore drops the 18-line consumers.json token-rehydration
block (was a no-op for the only consumer that ever existed). Adds a
best-effort wireup invocation after the brain-repo clone so 2nd-Mac restore
gets gbrain federation automatically. Failure prints a stderr WARNING but
does not abort the restore — restore's primary job is the git clone.
bin/gstack-brain-uninstall calls the helper's --uninstall mode (which
removes the gbrain source registration, the git worktree, and the
future-launchd-plist stub) before the existing legacy consumers.json
removal. Ordering is fragile-by-design: helper derives source-id via
multi-fallback so it works even after .git is destroyed.
bin/gstack-brain-consumer gets a DEPRECATED header note. Stays in the tree
for one cycle of grace; removal in v1.13.0.0.
setup-gbrain/SKILL.md is regenerated from the .tmpl via gen:skill-docs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat: v1.12.3.0 migration — wire existing brain-sync repos into gbrain
Idempotent migration script. For users who already opted into brain-sync
before this release (gbrain_sync_mode != off, ~/.gstack/.git exists), runs
the new gstack-gbrain-source-wireup helper so their existing brain repo
becomes searchable via gbrain immediately on /gstack-upgrade.
Skip conditions (each ends with exit 0):
- HOME unset or empty (defensive)
- gbrain_sync_mode = off or empty (user opted out)
- no ~/.gstack/.git (brain-init never ran)
- helper missing on disk (broken install)
No --strict on the helper invocation: missing or old gbrain is a benign
skip during a batch upgrade rather than a blocker.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* v1.12.3.0: setup-gbrain wireup ships the gbrain federation surface
Bumps VERSION 1.12.2.0 → 1.12.3.0 with a release-notes-format entry in
CHANGELOG.md. After upgrade, the placeholder consumers.json wireup is gone,
gbrain sources + sync + skill-end hook is the new path, your gstack memory
is actually searchable in gbrain.
The CHANGELOG entry follows the release-summary format from CLAUDE.md:
two-line bold headline, lead paragraph naming what shipped, "verify after
upgrade" command block readers can run on their own brain to see the
delta, then the standard Itemized changes / What this means / For
contributors sections.
Three pre-existing test failures on this branch are flagged in the
contributor section: the GSTACK_HOME isolation test (reads Garry's actual
~/.gstack/config.yaml), the 2MB tracked-binary test (security-bench
fixtures > 2MB), and the Opus 4.7 pacing-directive test (overlay text
drifted). All three were verified to fail on the base branch too — out
of scope for this PR, follow-up needed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat: helper locks GBRAIN_DATABASE_URL at startup, defends against config rewrites
The wireup helper previously read ~/.gbrain/config.json on every gbrain
subprocess invocation. On Garry's Mac, multiple concurrent test runs and
agent integrations were rewriting that file mid-sync, redirecting the
wireup at the wrong brain partway through a 4-min initial import.
This commit adds a `--database-url <url>` flag to the helper and locks
the URL at startup. Precedence:
1. --database-url flag (explicit caller intent)
2. GBRAIN_DATABASE_URL / DATABASE_URL env (CI / manual override)
3. read once from ~/.gbrain/config.json (default)
Whichever wins gets exported as GBRAIN_DATABASE_URL for every child
`gbrain` invocation. Per gbrain's loadConfig at src/core/config.ts:53,
env-var URLs override the file URL — so a process that flips config.json
between two of our gbrain calls can't redirect us. Defense-in-depth:
once the URL is locked, the wireup completes against the original brain
even under hostile filesystem conditions.
setup-gbrain/SKILL.md.tmpl Step 7 now reads the URL out of config.json
once (via python3 inline) and passes it explicitly with --database-url,
so even the very first wireup call is decoupled from config.json mutability.
Three new test cases cover the lock behavior:
- --database-url flag is exported to child gbrain calls
- falls back to ~/.gbrain/config.json when no flag and no env
- flag overrides env GBRAIN_DATABASE_URL and config.json values
The fake gbrain in the test suite now records GBRAIN_DATABASE_URL alongside
each call so tests can assert the helper exported the locked URL.
Total test count: 13 → 16 passing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore: bump v1.12.3.0 references to v1.15.1.0 to match merged-with-main release
Internal-only renames after merging origin/main bumped this branch's release
target from v1.12.3.0 → v1.15.1.0:
- gstack-upgrade/migrations/v1.12.3.0.sh → v1.15.1.0.sh (rename + log-prefix
bump from "[v1.12.3.0]" to "[v1.15.1.0]")
- bin/gstack-brain-consumer header: "DEPRECATED in v1.12.3.0" → "DEPRECATED in
v1.15.1.0"; removal target bumped from v1.13.0.0 → v1.16.0.0 (next minor
after v1.15.1.0).
- bin/gstack-brain-uninstall: "no longer written ... since v1.12.3.0" →
"since v1.15.1.0".
No behavior change. Test suite still 16/16 passing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test: 10 new cases close coverage gaps (helper defensive paths + migration)
/ship Step 7 coverage audit reported 48% (22/46 branches). Added 10 cases
covering the highest-impact gaps:
Helper (test/gstack-gbrain-source-wireup.test.ts, +3 cases → 19 total):
- --uninstall when gbrain is missing: best-effort exit 0, worktree still cleaned
- --no-pull skips HEAD advance on existing worktree (was untested)
- Stray non-git directory at worktree path is cleaned up + worktree created
Migration (test/gstack-upgrade-migration-v1_15_1_0.test.ts, NEW, 7 cases):
- HOME unset → defensive exit 0
- gbrain_sync_mode=off → exit 0 silently
- gbrain_sync_mode unset → exit 0 silently
- no ~/.gstack/.git → exit 0 silently
- helper missing on PATH → warning + exit 0
- happy path → invokes helper without --strict
- helper exits non-zero → migration prints retry hint, still exits 0 (non-blocking)
Also syncs package.json version from 1.15.0.0 → 1.15.1.0 to match VERSION
file (DRIFT_STALE_PKG repair from /ship Step 12 idempotency check; was a
manual-edit-bypass artifact from the merge step).
Coverage estimate: 48% → ~75%. Mainline + migration script + key defensive
paths all exercised. 26 tests total covering the new code surface.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: pre-landing review auto-fixes (5 correctness + observability)
/ship Step 9 review surfaced 9 INFORMATIONAL findings on the new helper +
migration. Five auto-fixed with no behavior regression (26/26 tests pass):
bin/gstack-gbrain-source-wireup:
- Version compare: put floor "0.18.0" first in `sort -V` stdin so equal-or-
greater $v always sorts to position 2. Stable across sort implementations.
- _worktree_add_detached: drop `2>/dev/null` on the `worktree add`, surface
git's stderr through `prefix` so users see WHY adds fail (disk, perms).
- ensure_worktree: same observability fix on the `git checkout --detach` path
during HEAD-advance, so users see the actual git error before recovery.
- do_probe: replace `[ -d X ] || [ -f X ] && set=present` (precedence trap —
the `&&` short-circuits when the dir branch fails) with explicit if-block.
- do_probe: capture `check_source_state`'s return code explicitly via
`set +e; ...; rc=$?; set -e`. `$?` after an `if`/`elif` chain is fragile
under set -e and may not reach the elif under some shell versions.
- do_wireup: same explicit return-code capture for `ensure_worktree`. The
prior `ensure_worktree || { if [ $? = 2 ]; ...` pattern relied on `$?`
reflecting the function's return after `||`, which is implementation-defined.
gstack-upgrade/migrations/v1.15.1.0.sh:
- Trim whitespace from `gstack-config get gbrain_sync_mode` output via
`tr -d '[:space:]'`. Trailing newlines would mis-classify "off\n" as a
non-empty non-off mode and incorrectly invoke the helper.
Skipped findings (cosmetic / out of scope):
- `python3 -c` reads `~/.gbrain/config.json` via `expanduser` instead of
the helper's `$GBRAIN_CONFIG` variable (cosmetic; HONORS HOME override).
- Long sync-failure error message could truncate to last N lines (cosmetic
log readability).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: adversarial review hardening (rm safety, jq probe, secret redaction, multi-Mac)
/ship Step 11 adversarial review surfaced 7 CRITICAL issues. Five fixed
inline (no behavior regression, 26/26 tests still pass):
bin/gstack-gbrain-source-wireup:
1. **rm -rf path validation** (was: F-c-CRITICAL 9/10).
Added `safe_rm_worktree` helper that refuses any path not strictly under
$HOME/, plus dangerous-path allowlist for /, /Users, $HOME root. Replaces
raw `rm -rf "$WORKTREE"` calls (lines 161, 169 originally). If user sets
GSTACK_BRAIN_WORKTREE="" or "/", the helper now dies cleanly instead of
nuking the home dir or root.
2. **jq dependency probe** (was: F-c-CRITICAL 9/10).
`check_source_state` now hard-fails with a clear message if jq is missing,
instead of silently returning "absent" → re-add → die-on-duplicate. Plus
trims whitespace from jq output (`tr -d '[:space:]'`) to defend against
gbrain emitting `\n` for missing fields. Header comment claimed jq was a
transitive dep; now we enforce it.
3. **Python heredoc warns on JSON parse failure** (was: F-c-CRITICAL 8/10).
Previously `except Exception: pass` silently swallowed malformed JSON,
leaving _locked_url empty and defeating the URL-lock defense. Now writes
the parse error to a temp file and warns the user that the URL was not
locked. Also passes the config path via env var (GBRAIN_CONFIG_PATH)
instead of hardcoded `~/.gbrain/config.json`, respecting any HOME override.
4. **Multi-Mac source-id collision fix** (was: F-c-CRITICAL 9/10).
When `check_source_state` returns 1 (source exists at different path), the
helper used to remove + re-add. Two Macs sharing one Supabase brain would
ping-pong the local_path metadata on every sync. Now: if the existing
path's basename matches the local worktree's basename (likely another
machine's local copy of the SAME brain repo), skip re-registration and
sync against the local worktree. gbrain stores pages by content; metadata
is informational. No more ping-pong.
5. **Redact DB URL from sync-failure error message** (was: F-c-CRITICAL 7/10).
`gbrain sync` failures used to echo the full stderr (which can contain
the postgres connection string with password) into the user's terminal
and any log redirect. Now we sed-replace any `postgres://...` with
`postgres://***REDACTED***` before the die() call, and only show the
last 10 lines.
Bonus minor fix: `die()` now uses `$1` instead of `$*` for the warn
message, so the exit-code arg ($2) doesn't get appended to the warning text.
Acknowledged-but-deferred:
- GBRAIN_DATABASE_URL env exposure on Linux via /proc/$PID/environ. This is
a Linux-only concern; gstack is Mac-targeted today and macOS restricts
process env reads. Document as a follow-up if Linux support lands.
- gbrain version parser brittleness if gbrain switches to "v0.18.0" prefix.
Defensive only; current gbrain output matches `gbrain X.Y.Z` exactly.
- bash 3.2 PIPESTATUS reliability. Tests pass on the host bash version (3.2+
via macOS); modern bash 5.x is widely available.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: sync gbrain-source-wireup helper into USING_GBRAIN + gbrain-sync
USING_GBRAIN_WITH_GSTACK.md: add gstack-gbrain-source-wireup row to the bin
helpers table — describes federation registration via `gbrain sources add` +
worktree, lists flags, calls out it replaces the dead consumers.json/ingest-repo
HTTP wireup.
docs/gbrain-sync.md: replace the `gstack-brain-reader add --ingest-url` step
in gstack-brain-init's flow (which targeted the never-shipped /ingest-repo
endpoint) with the real flow — federate via gbrain sources + worktree, point
to bin/gstack-gbrain-source-wireup.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* v1.16.1.0: rebump after queue-collision (PR garrytan#1233 took v1.16.0.0)
CI's "Check VERSION is not stale vs queue" job (job 73105686380) failed
with: "VERSION drift: PR garrytan#1234 claims v1.15.1.0 but the queue has moved —
next free slot is v1.16.1.0." PR garrytan#1233 (garrytan/browserharness) entered
the queue claiming v1.16.0.0 between when this branch's prior /ship ran
and when CI evaluated, so v1.15.1.0 is stale. Rebumping on top.
Files updated:
- VERSION 1.15.1.0 → 1.16.1.0
- package.json 1.15.1.0 → 1.16.1.0
- CHANGELOG.md heading + Before/After columns 1.15.1.0 → 1.16.1.0
- CHANGELOG removal target (consumers.json + config keys) 1.16.0.0 → 1.17.0.0
- gstack-upgrade/migrations/v1.15.1.0.sh → renamed v1.16.1.0.sh + log prefix
- bin/gstack-brain-consumer "DEPRECATED in" + "removal in" 1.15.1.0/1.16.0.0 → 1.16.1.0/1.17.0.0
- bin/gstack-brain-uninstall "since vX.Y.Z.W" 1.15.1.0 → 1.16.1.0
- test/gstack-upgrade-migration-v1_15_1_0.test.ts → renamed v1_16_1_0.test.ts
No behavior change. 26/26 wireup + migration tests still pass on the rename.
Full bun test suite: exit 0, 0 failures.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* v1.17.0.0: rebump again — bump-detection now classifies branch as MINOR
CI's version-stale check (job 73106360896) failed: PR garrytan#1234 claims v1.16.1.0
but the queue moved to v1.17.0.0. Root cause: bumping 1.15.1.0 → 1.16.1.0
to dodge the prior collision turned the branch's diff classification from
PATCH (1.15.0 → 1.15.1) into MINOR (1.15.0 → 1.16.x). detect-bump.ts now
sees MINOR, gstack-next-version walks the MINOR lane past garrytan#1233's
v1.16.0.0 claim, and the next free slot is v1.17.0.0.
Honestly accurate per CLAUDE.md scale-aware bumps: this branch IS a
MINOR ("substantial new capability shipped — skill, harness, command,
big refactor"). The new helper + migration + integration totals ~1200
lines added across 11 files with 26 new tests. PATCH was always the
wrong honest classification; the queue collision forced the right
answer.
Files updated:
- VERSION 1.16.1.0 → 1.17.0.0
- package.json 1.16.1.0 → 1.17.0.0
- CHANGELOG.md heading + After column 1.16.1.0 → 1.17.0.0
- CHANGELOG removal targets 1.17.0.0 → 1.18.0.0
- gstack-upgrade/migrations/v1.16.1.0.sh → renamed v1.17.0.0.sh + log prefix
- bin/gstack-brain-consumer "DEPRECATED in" + "removal in" 1.16.1.0/1.17.0.0 → 1.17.0.0/1.18.0.0
- bin/gstack-brain-uninstall "since vX.Y.Z.W" 1.16.1.0 → 1.17.0.0
- test/gstack-upgrade-migration-v1_16_1_0.test.ts → renamed v1_17_0_0.test.ts
26/26 tests still pass. No behavior change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(dual-impl): /review pass — maxBuffer 50MB + cleaner squashed-commit message
Two informational findings from /review pre-landing pass:
1. spawnSync default maxBuffer is 1MB. A large cumulative diff (e.g., 10k+
line refactor squashed across multiple commits) would silently truncate
when piped to `git apply -3 -` in the cherry-pick fallback path. Set
maxBuffer to 50 MB on every git invocation in worktree.ts.
2. Patch-fallback commit message used `git log --format=%s` across N commits,
producing N subject lines in one ugly -m string. Now: single-commit case
uses the original subject; multi-commit case uses
"Apply <winner> implementation (N commits squashed)".
Both BY-DESIGN risk (latent dualImpl undefined spread) and repo hygiene
(untracked junk files predating this branch) deferred — not actionable here.
122 tests pass, 0 fail.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(dual-impl): Phase 3 — sub-agents.ts (runCodexImpl, runJudgeOpus, parseFailureCount)
Four new exports for the dual-implementor tournament:
- parseFailureCount(output): counts ✗ markers (bun) or ^FAIL lines (jest/pytest);
returns max of the two so different runners report comparable signal.
- parseJudgeVerdict(output): extracts WINNER: gemini|codex + REASONING from
Opus output. Falls back to verdict='gemini' with explanatory reasoning if
WINNER line is missing — better to ship one impl than fail on a parse quirk.
- buildCodexImplArgv(opts): pure helper exposing the codex exec argv shape
(exec + danger-full-access + -C cwd + reasoning=high). Extracted so tests
can assert the invocation without spawning the binary.
- runCodexImpl(opts): mirrors runGemini structure — file-path I/O, captured
output, single retry on timeout. Operates inside an isolated worktree so
danger-full-access is safe (no leakage to main cwd).
- runJudgeOpus(opts): spawns claude --model claude-opus-4-7 -p with file-path
I/O. Caller invokes parseJudgeVerdict on result.stdout to extract verdict.
GSTACK_BUILD_JUDGE_TIMEOUT env var (default 10 min).
12 new tests cover parseFailureCount (5), parseJudgeVerdict (5), and
buildCodexImplArgv (2). 134 tests pass, 0 fail.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(dual-impl): Phase 3 post-review HIGH+MEDIUM+LOW fixes
Codex review surfaced four issues. All fixed:
1. HIGH — parseJudgeVerdict silently fell back to 'gemini' when WINNER line
was missing. That defeats Phase 2's fail-closed semantics (dual_winner_pending
without selectedImplementor → FAIL). Now returns verdict=null on malformed
output; Phase 4 caller MUST treat null as hard failure. WINNER pattern is
also now anchored to ^ so it doesn't match prose like "the WINNER: gemini
is better here".
2. HIGH — runCodexImpl defaulted to 'danger-full-access', which is unsafe in
linked git worktrees (shared .git, remotes, credentials with main cwd).
A bad command could push --delete origin main from inside the worktree.
Default is now 'workspace-write'; opts.sandbox or
GSTACK_BUILD_CODEX_IMPL_SANDBOX env var allows opt-in to looser sandboxes.
3. MEDIUM — parseFailureCount returned 0 when no signal was detectable,
making "could not parse failures" beat "1 real failure" in tie-breaking.
Now returns `number | undefined`; phase-runner already fails closed when
both impls have undefined failureCount. Also added priority-1 summary-line
parsing ("3 failed" anchored to ^) for better cross-runner accuracy.
4. LOW — judge model was hardcoded 'claude-opus-4-7'. Now overridable via
GSTACK_BUILD_JUDGE_MODEL env var.
Tests updated accordingly: parseJudgeVerdict tests now check null fallback +
mid-sentence rejection; parseFailureCount tests check undefined + summary-line
priority; buildCodexImplArgv tests check workspace-write default + sandbox
override.
137 tests pass, 0 fail.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(dual-impl): Phase 4 — cli.ts dispatch handlers + --dual-impl flag
- Args.dualImpl: boolean field; --dual-impl CLI flag wired through parseArgs
(now exported); HELP_TEXT exported and documents the flag.
- parsePlan(content, { dualImpl }) stamps dualImpl=true on every parsed phase
when the flag is set — single-impl plans are unchanged.
- buildCodexImplPromptBody(phase, planFile): tournament-mode Codex prompt
("competing against Gemini, do NOT change test assertions, write minimal
correct code").
- buildJudgePrompt({ phase, geminiDiff, codexDiff, geminiTestResult,
codexTestResult }): Opus judge prompt with anchored WINNER:/REASONING:
format and 5KB-trimmed diffs.
- runPhase handlers for the 4 new actions:
* RUN_DUAL_IMPL — createWorktrees + Promise.all([runGemini, runCodexImpl]);
teardown + fail-closed if either impl crashes.
* RUN_DUAL_TESTS — Promise.all([runTests(gemini), runTests(codex)]);
parses failureCount from each; passes both into ApplyResultExtra.
* RUN_JUDGE_OPUS — reads worktree diffs, runJudgeOpus with file-path I/O;
parseJudgeVerdict; null verdict → fail-closed + teardown.
* APPLY_WINNER — applyWinner cherry-pick; ALWAYS tears down worktrees
(even on cherry-pick failure — Phase 4 invariant).
- readWorktreeDiff helper: git diff baseCommit..HEAD with 50MB maxBuffer.
- Exhaustiveness guard preserved (no _never violation on new actions).
- 9 new tests cover --help text, parseArgs flag, and both new prompt bodies.
146 tests pass, 0 fail.
bun build build/orchestrator/cli.ts → clean.
gstack-build --help shows --dual-impl.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(dual-impl): Phase 4 post-review HIGH+MEDIUM fixes
Codex review surfaced four issues. All fixed:
1. HIGH — readWorktreeDiff returned '' on git failure, letting the judge see
empty evidence and pick arbitrarily. Now returns string|null; RUN_JUDGE_OPUS
handler fails closed (teardown + status=failed) when either diff is null.
2. HIGH — implementations could pass tests with uncommitted edits, but
applyWinner has nothing to cherry-pick. New countCommitsSinceBase helper +
RUN_DUAL_IMPL now treats "neither implementor committed anything" as a
catastrophic failure alongside timeouts and double-non-zero-exits.
Single-implementor commit failures still let the test phase auto-select.
3. MEDIUM — RUN_DUAL_IMPL post-createWorktrees block had no cleanup guard.
A throw from writeFileSync or unexpected Promise.all rejection would leak
worktrees + branches. Now wrapped in try/catch/finally with teardown on
any failure path; dualImplOk flag suppresses teardown on the success path
(downstream phases own cleanup).
4. MEDIUM — APPLY_WINNER unconditionally tore down worktrees, including on
apply failure — destroying the only copy of the winner's code. Now
preserves worktrees on cherry-pick failure and surfaces paths/branches +
manual-cleanup commands in the error message. Teardown only happens after
a successful apply.
146 tests pass, 0 fail. bun build clean.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(dual-impl): Phase 5 — README + SKILL.md.tmpl v1.15.0 + integration test
- README: new "Dual Implementor Mode" section (workflow, auto-select rules,
worktree isolation, recovery semantics, env vars).
- SKILL.md.tmpl: version 1.14.0 → 1.15.0 in frontmatter + announce-version line.
- bun run gen:skill-docs --host claude → regenerated build/SKILL.md.
- skill-md.test.ts pinned to v1.15.0.
- integration.test.ts adds a second dry-run that asserts --dual-impl announces
"Dual Impl", "Dual Tests", "Judge Opus", and "Apply Winner" — and that the
TDD steps (Test Specification, Verify Red) still run after handoff.
- CHANGELOG: full Unreleased entry covering new flag, state machine extension,
fail-closed paths, recovery semantics, and 42-test coverage delta (105→147).
Verified:
- 147 tests pass, 0 fail.
- bun build build/orchestrator/cli.ts → clean.
- gstack-build --help shows --dual-impl.
- bun run gen:skill-docs regen → SKILL.md frontmatter version: 1.15.0.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(dual-impl): Phase 5 post-review LOW + MEDIUM fixes
- Clarify "each TDD phase" upfront (legacy 2-checkbox plans skip dual-impl
silently — Phase 5 review LOW).
- Document required CLIs (gemini, codex, claude) for --dual-impl with explicit
note that orchestrator does NOT preflight check; missing Codex degrades into
one-sided tournament. (Phase 5 review MEDIUM.)
- Update stale "105 tests across 9 files" to "147 tests across 10 files" with
full coverage breakdown including dual-impl primitives and integration tests.
DEFERRED (Phase 5 review MEDIUM #1): hermetic non-dry-run integration test
with fake GEMINI_BIN/CODEX_BIN/CLAUDE_BIN. Real handler paths (createWorktrees,
Promise.all dispatch, applyWinner cherry-pick, teardown invariants) are exercised
only through unit tests, not end-to-end. Acceptable for v1; landed feature is
opt-in and small-blast-radius.
147 tests pass, 0 fail.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(dual-impl): Codex /review pass — 3 P2/P3 findings fixed
Codex structured review (gpt-5.5, --base main, full diff) surfaced 3 valid
correctness issues in the dual-implementor flow. All fixed; no P1 findings.
GATE: PASS.
[P2] cli.ts:739-741 — Zero-commit implementor still advanced to test/judge
Old logic: only fail if BOTH sides committed nothing. If gemini committed
but codex didn't (or vice versa), the no-commit side could pass tests on
uncommitted edits and win auto-select, then applyWinner would fail with
"No commits found".
Fix: when EXACTLY ONE side committed, short-circuit dual-impl: skip
RUN_DUAL_TESTS + RUN_JUDGE_OPUS, auto-select the committed side, jump
straight to dual_winner_pending. Logs the warning so the user sees which
implementor failed to commit. Both-failed and neither-committed paths
unchanged (still fail-closed).
[P2] sub-agents.ts parseFailureCount — pytest summary not matched
Old regex: `^\s*(\d+)\s+fail` failed on pytest's `===== 2 failed in 0.10s =====`
because of the leading `=====` decoration. Pytest projects would return
undefined → fail-closed even when signal was present.
Fix: priority-1 pytest pattern `^=+\s*(\d+)\s+failed\b` matches the
decorated summary; priority-2 keeps the bare-line pattern for bun/jest/cargo;
priority-3 marker count fixed from `^FAILED?\b` (which matched FAILE/FAILED)
to `^FAIL(?:ED)?\b` (matches both FAIL and FAILED). 3 new pytest tests added.
[P3] cli.ts:806-808 — Parallel dual-test logs collide
Both runTests calls used `iteration: 1`, racing for the same log file
`phase-N-tests-1.log`. testLogPath fields would point to one overwritten log.
Fix: extended runTests with optional `logSuffix` param ('gemini'/'codex' for
dual mode); resulting logs are `phase-N-tests-1-gemini.log` and
`phase-N-tests-1-codex.log`. Default behavior unchanged when suffix omitted.
150 tests pass, 0 fail. bun build clean.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(sub-agents): mergeOutputFile empty-fallback — preserve verdict stream when output file is empty
When Codex applies edits inline but skips writing the report file, the output
file is left empty. Without this fix mergeOutputFile replaces stdout with ''
and parseVerdict returns 'unclear' — the review loop never converges.
Fix: detect empty fileContent and fall through to merging stderr+stdout so the
GATE PASS / GATE FAIL signal is preserved for the verdict scan.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Garry Tan <garrytan@gmail.com>
anbangr
pushed a commit
that referenced
this pull request
Apr 29, 2026
…rrytan#1233) * feat(gbrain-sync): queue primitives + writer shims Adds bin/gstack-brain-enqueue (atomic append to sync queue) and bin/gstack-jsonl-merge (git merge driver, ts-sort with SHA-256 fallback). Wires one backgrounded enqueue call into learnings-log, timeline-log, review-log, and developer-profile --migrate. question-log and question-preferences stay local per Codex v2 decision. gstack-config gains gbrain_sync_mode (off/artifacts-only/full) and gbrain_sync_mode_prompted keys, plus GSTACK_HOME env alignment so tests don't leak into real ~/.gstack/config.yaml. * feat(gbrain-sync): --once drain + secret scan + push bin/gstack-brain-sync is the core sync binary. Subcommands: --once (drain queue, allowlist-filter, privacy-class-filter, secret-scan staged diff, commit with template, push with fetch+merge retry), --status, --skip-file <path>, --drop-queue --yes, --discover-new (cursor-based detection of artifact writes that skip the shim). Secret regex families: AWS keys, GitHub tokens (ghp_/gho_/ghu_/ghs_/ ghr_/github_pat_), OpenAI sk-, PEM blocks, JWTs, bearer-token-in-JSON. On hit: unstage, preserve queue, print remediation hint (--skip-file or edit), exit clean. No daemon — invoked by preamble at skill boundaries. * feat(gbrain-sync): init, restore, uninstall, consumer registry bin/gstack-brain-init: idempotent first-run. git init ~/.gstack/, .gitignore=*, canonical .brain-allowlist + .brain-privacy-map.json, pre-commit secret-scan hook (defense-in-depth), merge driver registration via git config, gh repo create --private OR arbitrary --remote <url>, initial push, ~/.gstack-brain-remote.txt for new-machine discovery, GBrain consumer registration via HTTP POST. bin/gstack-brain-restore: safe new-machine bootstrap. Refuses clobber of existing allowlisted files, clones to staging, rsync-copies tracked files, re-registers merge drivers (required — not cloned from remote), rehydrates consumers.json, prompts for per-consumer tokens. bin/gstack-brain-uninstall: clean off-ramp. Removes .git + .brain-* files + consumers.json + config keys. Preserves user data (learnings, plans, retros, profile). Optional --delete-remote for GitHub repos. bin/gstack-brain-consumer + bin/gstack-brain-reader (symlink alias): registry management. Internal 'consumer' term; user-facing 'reader' per DX review decision. * feat(gbrain-sync): preamble block — privacy gate + boundary sync scripts/resolvers/preamble/generate-brain-sync-block.ts emits bash that runs at every skill invocation: - Detects ~/.gstack-brain-remote.txt on machines without local .git and surfaces a restore-available hint (does NOT auto-run restore). - Runs gstack-brain-sync --once at skill start to drain any pending writes (and at skill end via prose instruction). - Once-per-day auto-pull (cached via .brain-last-pull) for append-only JSONL files. - Emits BRAIN_SYNC: status line every skill run. Also emits prose for the host LLM to fire the one-time privacy stop-gate (full / artifacts-only / off) when gbrain is detected and gbrain_sync_mode_prompted is false. Wired into preamble.ts composition. * test(gbrain-sync): 27-test consolidated suite test/brain-sync.test.ts covers: - Config: validation, defaults, GSTACK_HOME env isolation - Enqueue: no-op gates, skip list, concurrent atomicity, JSON escape - JSONL merge driver: 3-way + ts-sort + SHA-256 fallback - Init + sync: canonical file creation, merge driver registration, push-reject + fetch+merge retry path - Init refuses different remote (idempotency) - Cross-machine restore round-trip (machine A write → machine B sees) - Secret scan across all 6 regex families (AWS, GH, OpenAI, PEM, JWT, bearer-JSON). --skip-file unblock remediation - Uninstall removes sync config, preserves user data - --discover-new idempotence via mtime+size cursor Behaviors verified via integration smokes during implementation. Known follow-up: bun-test 5s default timeout needs 30s wrapper for spawnSync-heavy tests. * docs(gbrain-sync): user guide + error lookup + README section docs/gbrain-sync.md: setup walkthrough, privacy modes, cross-machine workflow, secret protection, two-machine conflict handling, uninstall, troubleshooting reference. docs/gbrain-sync-errors.md: problem/cause/fix index for every user-visible error. Patterned on Rust's error docs + Stripe's API error reference. README.md: 'Cross-machine memory with GBrain sync' section near the top (discovery moment), plus docs-table entry. * chore: bump version and changelog (v1.7.0.0) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * chore: regenerate SKILL.md files for gbrain-sync preamble block Re-runs bun run gen:skill-docs after adding generateBrainSyncBlock to scripts/resolvers/preamble.ts in a2aa8a0. CI check-freshness caught the drift. All 36 SKILL.md files regenerated with the new skill-start bash block + privacy-gate prose + skill-end sync instructions baked in. * fix(test): session-awareness reads AskUserQuestion Format from a Tier 2+ SKILL.md The test was reading ROOT/SKILL.md (browse skill, Tier 1) which never contained '## AskUserQuestion Format' — that section is only emitted for Tier 2+ skills by scripts/resolvers/preamble.ts. As a result the agent was prompted with an empty format guide and only emitted 'RECOMMENDATION' intermittently, making the test flaky. Pre-existing on main (same ROOT/SKILL.md shape there) — surfaced now because the agent run didn't hit the RECOMMENDATION/recommend/option a fallback strings in this particular attempt. Fix: read from office-hours/SKILL.md (Tier 3, always has the section) with a fallback that scans for the first top-level skill dir whose SKILL.md contains the header. Future template moves won't break this test again. * feat(browse): domain-skills storage + state machine New module browse/src/domain-skills.ts implements the per-site notes the agent writes for itself, persisted as type:"domain" rows alongside /learn's per-project learnings. Three scopes layered: per-project default, global by explicit promotion. Project-active shadows global for the same host. State machine (T6 — codex outside-voice): quarantined --3 uses w/o flag--> active(project) --promote--> global ^ | +----- classifier flag during use - Append-only JSONL with O_APPEND for atomic small writes - Tolerant parser drops partial trailing line on read - Tombstone for deletes (compactor cleans up later) - Version log per (host, scope) enables rollback - Hostname derived from active tab top-level origin (T3 confused-deputy fix) - writeSkill rejects classifier_score >= 0.85 with structured error Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(browse): domain-skills storage + state machine 14 tests covering: - T3 hostname normalization (lowercase, www. strip, port/path/query strip, subdomain-exact preserved) - T4 scope shadowing (per-project active shadows global for same host) - T5 persistence (version monotonicity, tolerant parser drops partial line) - T6 state machine (quarantined → active after N=3 uses, classifier-flag blocks promotion, save-time score >= 0.85 rejected) - Rollback by version log (restore prior body, advance version counter) - Tombstone deletion (read returns null after delete) All 14 pass in 27ms via bun test. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(browse): $B domain-skill subcommands Wire the domain-skills storage layer into the browse CLI as a META command: $B domain-skill save save body from stdin or --from-file (host derived from active tab — T3) $B domain-skill list list all skills visible to current project $B domain-skill show <host> print skill body $B domain-skill edit <host> open in $EDITOR $B domain-skill promote-to-global <host> cross-project promotion (T4) $B domain-skill rollback <host> [--global] restore prior version $B domain-skill rm <host> [--global] tombstone Save path runs L1-L3 content filters from content-security.ts (importable in compiled binary, unlike L4 ML classifier — see CLAUDE.md). The L4 classifier scan happens in sidebar-agent at prompt-injection load time. Output is structured (problem + cause + suggested-action) per DX D7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(browse): $B cdp escape hatch — deny-default allowlist + two-tier mutex Codex T2: flip CDP posture to deny-default. Allowed methods enumerated in cdp-allowlist.ts with (scope: tab|browser, output: trusted|untrusted, justification) per entry. Initial allowlist (~25 methods) covers: - Accessibility tree extraction (read-only) - DOM/CSS inspection (read-only) - Performance metrics - Tracing - Emulation viewport/UA override - Page screenshot/PDF capture (output is binary, no marker injection vector) - Network.enable/disable (no bodies/cookies — those are exfil surfaces) - Runtime.getProperties (NO evaluate/callFunctionOn — those would be RCE) Page.navigate is INTENTIONALLY NOT allowed; agents use $B goto which goes through the URL blocklist. Codex T7: two-tier mutex. tab-scoped methods take per-tab lock; browser- scoped take global lock that blocks all tab locks. 5s acquire timeout yields CDPMutexAcquireTimeout (no silent hangs). All lock acquires use try/finally so errors don't leak the lock. Path A from spike: uses Playwright's newCDPSession() per page. No second WebSocket, no need for --remote-debugging-port. CDPSession is cached per page in a WeakMap and cleared on page close. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(browse): CDP allowlist + two-tier mutex 13 tests: - Allowlist linter: every entry has 4 required fields, no duplicates, justification length > 20 chars - Deny-list verification: dangerous methods (Runtime.evaluate, Page.navigate, Network.getResponseBody, Browser.close, Target.attachToTarget, etc.) are NOT allowed (Codex T2 categories 4-7) - Per-tab mutex serializes ops on same tab - Per-tab mutex allows parallel ops across different tabs - Global lock blocks tab locks; tab locks block global lock - Acquire timeout yields CDPMutexAcquireTimeout (no silent hang) - Timeout error names the tab id and the timeout budget Also extends Network.disable justification to satisfy linter. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(browse): telemetry signals + project-slug helper Lightweight telemetry per DX D9: piggybacks on ~/.gstack/analytics/ pattern. Hostname + aggregate counters only, no body content. GSTACK_TELEMETRY_OFF=1 silences. Fire-and-forget — never blocks calling path. Signals fired so far: - domain_skill_saved {host, scope, state, bytes} - domain_skill_save_blocked {host, reason} (domain_skill_fired and cdp_method_* fired in subsequent commits.) Also extracts project-slug resolution into project-slug.ts so server.ts and domain-skill-commands.ts share one cached lookup. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(browse): sidebar prompt-context injection + CDP telemetry server.ts spawnClaude now: - Imports per-project domain skill matching the active tab's hostname via readDomainSkill() - Wraps the body in UNTRUSTED EXTERNAL CONTENT envelope (so the L4 classifier in sidebar-agent sees it at load time per Eng D4) - Appends as <domain-skill source="..." host="..." version="..."> block - Fires domain_skill_fired telemetry (host, source, version) - Calls recordSkillUse fire-and-forget so the auto-promote-after-N=3 state machine advances on each successful prompt injection System prompt also gets a one-liner introducing $B domain-skill commands to agents (DX D4 start-of-task discoverability hint). cdp-bridge.ts fires: - cdp_method_denied (drives next allow-list growth) - cdp_method_lock_acquire_ms (P50/P99 quantile observability) - cdp_method_called (allowed methods) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(browse): telemetry module 3 tests covering: - logTelemetry writes JSONL with ts injected - GSTACK_TELEMETRY_OFF=1 silences all events - logTelemetry never throws on disk failures Uses GSTACK_HOME env var to redirect writes to a tmp dir; the telemetry module reads HOME lazily so test mutations take effect. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: domain-skills reference + error lookup table docs/domain-skills.md mirrors the layered shape of docs/gbrain-sync.md (DX D8): how agents use it, state machine, storage layout, security model (L1-L3 + L4 layered defense), error reference table. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(readme): browser-harness-js plug + domain-skills section New "Domain skills + raw CDP escape hatch" section under "The sprint" covering both v1.8.0.0 features. Plugs browser-use/browser-harness-js as the no-rails alternative for users who want raw CDP without gstack's security stack. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump version and changelog (v1.8.0.0) Branch-scoped bump on top of merged 1.7.0.0 base. CHANGELOG entry covers the full v1.8.0.0 scope: $B domain-skill, $B cdp escape hatch, two-tier mutex, telemetry signals, sidebar prompt-context injection. Includes Codex outside-voice trail (7 of 20 findings resolved, 12 mooted by T1 scope drop). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * todos: 7 follow-ups from v1.8.0.0 review trail P1: Self-authoring $B commands with out-of-process worker isolation (Codex T1 deferred from v1.8.0.0 — needs real isolation design) P2: Migrate /learn to SQLite (Codex T5 long-term primitive fix) P2: Remove plan-mode handshake from /plan-devex-review (skill bug) P3: GBrain skillpack publishing for domain-skills P3: Replay/record demonstrated flows to domain-skills P3: $B commands review batch-mode UX (alternative to inline approval) P3: Heuristic command-gap watcher (DX D4 alternative C) Each entry has the standard What/Why/Pros/Cons/Context/Effort/Priority/ Depends-on shape so anyone picking these up later has full context. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(browse): lazy GSTACK_HOME resolution in domain-skills Module-level constants (GLOBAL_FILE, derived path) were evaluated at module-load and cached. When E2E and unit tests run in the same Bun test pass and set GSTACK_HOME differently, the second test sees the first test's path. Switch to lazy gstackHome() / globalFile() / projectFile() helpers so process.env mutations take effect. Mirrors the pattern already used in telemetry.ts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(browse): E2E gate-tier tests for domain-skills + CDP domain-skills-e2e.test.ts (4 tests): - save derives host from active tab top-level origin (T3) - save lands quarantined; list surfaces it - readSkill returns null until 3 uses without flag promote to active (T6) - save without an active page errors with structured guidance cdp-e2e.test.ts (8 tests): - Accessibility.getFullAXTree returns wrapped JSON (allowed, untrusted-output) - Performance.getMetrics returns plain JSON (allowed, trusted-output) - Runtime.evaluate DENIED with structured guidance (T2 RCE block) - Page.navigate DENIED (must use $B goto for blocklist routing) - Network.getResponseBody DENIED (exfil block) - malformed JSON params surfaces clear error - non Domain.method format surfaces clear error - $B cdp help returns help text Both files boot a real Chromium via BrowserManager.launch() and exercise the dispatch handlers end-to-end. Total 12 E2E tests in <2s. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: regenerate SKILL.md files with new $B commands bun run gen:skill-docs picks up the domain-skill and cdp META_COMMANDS entries added in commands.ts. Both top-level SKILL.md and browse/SKILL.md now list the new commands in their Meta and Inspection tables. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(fixtures): regenerate ship SKILL.md golden baselines for v1.7.0.0 Pre-existing failures inherited from garrytan/gbrain-support: the GBrain Sync preamble block (added in v1.7.0.0) appears in regenerated SKILL.md output but the golden baselines in test/fixtures/golden/ were never updated. Three failures fixed: golden-file regression > Claude ship skill matches golden baseline golden-file regression > Codex ship skill matches golden baseline golden-file regression > Factory ship skill matches golden baseline Goldens regenerated by copying the current ship/SKILL.md, codex .agents/skills/gstack-ship/SKILL.md, and .factory/skills/gstack-ship/SKILL.md files. Diff is the v1.7.0.0 GBrain Sync preamble block + privacy stop-gate (no behavioral changes — just preamble text). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(brain-sync): bearer-token regex catches values with leading space Pre-existing bug from v1.7.0.0: the bearer-token-json secret pattern required values matching [A-Za-z0-9_./+=-]{16,}, which rejected the "Bearer <token>" form because the literal space after "Bearer" wasn't in the character class. Real Authorization headers use "Bearer <token>" syntax, and the test fixture '"authorization":"Bearer abcdef1234567890abcdef1234567890"' sat unscanned despite being a leak-class secret. One-character fix: add space to the value character class. Test 'gstack-brain-sync secret scan > blocks bearer-json' now passes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(brain-sync): GSTACK_HOME isolation test compares mtime, not content Pre-existing flaky test: the GSTACK_HOME-overrides-real-config test asserted the real ~/.gstack/config.yaml does NOT contain "gbrain_sync_mode: full" after the test. That fails for any user whose real config legitimately has that key set from prior usage — the test's invariant is "the command did not modify the real file," not "the real file lacks any specific value." Switch to mtime + content snapshot: capture both BEFORE running the command, then verify both are unchanged after. Also add a positive assertion that the tmpHome config DID get the new key. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(skill-validation): exempt deliberate large fixtures from 2MB limit Pre-existing failure: the "git tracks no files larger than 2MB" test caught browse/test/fixtures/security-bench-haiku-responses.json (28.8MB of replay data committed in v1.6.4.0 for security benchmark gate tests). The test exists to catch accidentally-committed binaries (Mach-O dist binaries, etc), not to forbid all large files. Add an explicit LARGE_FIXTURE_EXEMPTIONS allowlist so deliberate replay fixtures pass the gate while accidental binaries still fail. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(skill-token): mint scoped tokens per skill spawn Wraps token-registry.createToken/revokeToken with skill-specific clientId encoding (skill:<name>:<spawn-id>) and read+write defaults. Skill scripts get a per-spawn capability token bound to browser-driving commands; the daemon root token never leaves the harness. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(browse-client): SDK for browser-skill scripts Thin wrapper over POST /command with bearer auth. Resolves daemon port + token from GSTACK_PORT + GSTACK_SKILL_TOKEN env vars first (set by $B skill run when spawning), falls back to .gstack/browse.json for standalone debug runs. Convenience methods cover the read+write surface skills typically need: goto, click, fill, text, html, snapshot, links, forms, accessibility, attrs, media, data, scroll, press, type, select, wait, hover, screenshot. Low-level command(cmd, args) escape hatch for anything else. This is the canonical SDK source. Each browser-skill ships a sibling copy at <skill>/_lib/browse-client.ts so each skill is fully portable and version-pinned. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(browser-skills): 3-tier storage helpers listBrowserSkills() walks project > global > bundled (first-wins), parses SKILL.md frontmatter, no INDEX.json. readBrowserSkill() does the same for a single name. tombstoneBrowserSkill() moves a skill into .tombstones/<name>-<ts>/ for recoverability. Frontmatter parser handles the subset browser-skills need: scalars (host, description, trusted, version, source), string lists (triggers), and arg-mapping lists ([{name, description}, ...]). Quoted values handle colons; trusted defaults to false. Bundled tier path is auto-detected from the binary install location; project tier comes from git rev-parse; global is ~/.gstack/. All tier paths are overridable for hermetic tests. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(browser-skills): \$B skill list/show/run/test/rm subcommands handleSkillCommand dispatches to per-subcommand handlers; spawnSkill is the load-bearing function that: 1. Mints a per-spawn scoped token (read+write only) bound to the skill name + spawn-id. 2. Builds the spawn env: - trusted: passes process.env minus GSTACK_TOKEN (defense in depth). - untrusted: minimal allowlist (LANG, LC_ALL, TERM, TZ) + locked PATH; explicitly drops anything matching TOKEN/KEY/SECRET/etc. Also drops AWS_/AZURE_/GCP_/GOOGLE_APPLICATION_/ANTHROPIC_/OPENAI_/ GITHUB_/GH_/SSH_/GPG_/NPM_TOKEN/PYPI_ patterns. 3. Always injects GSTACK_PORT + GSTACK_SKILL_TOKEN last (cannot be overridden by parent env). 4. Spawns bun run script.ts -- <args> with cwd=skillDir, captures stdout (1MB cap), stderr, and timeout-kills past the deadline. 5. Revokes the token in finally{}, always. list output prints the resolved tier inline so "why did it run that one?" never becomes a debugging mystery (Codex finding #4 mitigation). server.ts threads the listen port to meta-commands via MetaCommandOpts.daemonPort. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(browser-skills): bundled hackernews-frontpage reference skill Smallest interesting browser-skill: scrapes HN front page, returns 30 stories as JSON. No auth, stable HTML, fully fixture-tested. Files: SKILL.md frontmatter + prose script.ts exports parseStoriesFromHtml(html) main: goto + html + parse + JSON.stringify _lib/browse-client.ts vendored copy of the SDK fixtures/hn-2026-04-26.html captured front page (5 stories) script.test.ts 13 assertions against the fixture The parser is a pure function over HTML so script.test.ts runs without a daemon (just imports parseStoriesFromHtml and asserts). This exercises every Phase 1 component end-to-end: - browse-client SDK (script imports browse from ./_lib/) - 3-tier lookup (hackernews-frontpage lives in the bundled tier) - scoped tokens (read+write is enough for goto + html) - spawn lifecycle (\$B skill run hackernews-frontpage) - file-fixture testing (\$B skill test hackernews-frontpage) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(skill-validation): cover bundled browser-skills Adds 7 assertions per bundled skill at <root>/browser-skills/<name>/: - SKILL.md exists - frontmatter parses with required fields (name/host/triggers/args) - script.ts exists - _lib/browse-client.ts exists and matches the canonical SDK byte-for-byte - script.test.ts exists - script.ts imports browse from ./_lib/browse-client The byte-identical SDK check enforces the version-pinning contract: when the canonical SDK at browse/src/browse-client.ts changes, every bundled skill's _lib/ copy must be re-synced or this test fails. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(designs): add BROWSER_SKILLS_V1 design doc Captures the 13 locked decisions, two-axis trust model (daemon-side scoped tokens + process-side env access), 3-tier lookup, file layout, and full responses to all 8 Codex outside-voice findings. Includes Phase 2-4 sketches for future branches. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(todos): replace self-authoring-\$B P1 with browser-skills phases Phase 1 of the browser-skills design shipped on this branch (sidesteps the in-daemon isolation problem the original P1 was blocked on). The new entries enumerate the work that remains: P1: Phase 2 (/scrape + /automate skill templates) P2: Phase 3 (resolver injection at session start) P2: Phase 4 (eval infra + fixture staleness + OS sandbox) Cross-references docs/designs/BROWSER_SKILLS_V1.md for the full architecture and the 8 Codex review findings + responses. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * release: v1.9.0.0 — browser-skills runtime VERSION 1.8.0.0 → 1.9.0.0. CHANGELOG entry leads with what humans can do today (hand-write deterministic browser scripts, run them in 200ms via \$B skill run). Notes explicitly that agent authoring lands in next release; no fabricated perf numbers. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(browser-skills-e2e): exercise dispatch with bundled hackernews-frontpage Covers the full \$B skill list/show/test pipeline against the real bundled reference skill (defaultTierPaths picks up <repo>/browser-skills/). Verifies frontmatter shape, the three-tier walk surfaces the bundled entry, and \$B skill test successfully runs the bundled script.test.ts in a child bun process. \$B skill run end-to-end against the live network is intentionally NOT covered here (would be flaky against news.ycombinator.com); the spawn lifecycle is exercised in browser-skill-commands.test.ts using inline synthetic skills. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: regen SKILL.md to surface the skill META command bun run gen:skill-docs picked up the new \`skill\` command from COMMAND_DESCRIPTIONS in browse/src/commands.ts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * release: bump v1.9.0.0 → v1.13.0.0 Main shipped through v1.11.1.0 while this branch was in flight; v1.12.x is presumed claimed by another in-flight branch. Use v1.13.0.0 as the next available slot. Updated VERSION, package.json, and the CHANGELOG header. Entry body unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * release: bump v1.13.0.0 → v1.16.0.0 Main shipped v1.13.0.0 (claude outside-voice skill), v1.14.0.0 (sidebar REPL), and v1.15.0.0 (slim preamble + plan-mode E2E) while this branch was in flight. Use v1.16.0.0 as the next available slot. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(browse-skills): atomic write helper for /skillify (D3) stageSkill writes a candidate skill into ~/.gstack/.tmp/skillify-<spawnId>/ with restrictive perms. commitSkill does an atomic fs.renameSync into the final tier path with realpath/lstat discipline (refuses symlinked staging dirs, refuses to clobber existing skills). discardStaged is the cleanup path for test failures and approval rejections, idempotent and bounded to the per-spawn wrapper. validateSkillName enforces lowercase/digits/ dashes only, no path-escape characters. Implements the D3 contract from the v1.19.0.0 plan review: never a half-written skill on disk. Test fail or approval reject = rm -rf the temp dir, no tombstone for never-approved skills. Closes Codex finding garrytan#5 (atomic skill packaging) for Phase 2a. 34 unit assertions covering: stage validation, file-path escape rejection, permission check, atomic rename, clobber refusal, symlink refusal, project tier unresolved, idempotent discard, end-to-end happy + simulated test failure + approval reject paths. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(scrape): /scrape <intent> skill template One entry point for pulling page data. Three paths under the hood: 1. Match — agent reads $B skill list, semantically matches the user's intent against each skill's triggers + description + host. Confident match = $B skill run <name> in ~200ms. 2. Prototype — no match, drive the page with $B goto/text/html/links etc. Return JSON, append a one-line "say /skillify" nudge. 3. Mutating refusal — verbs like submit/click/fill route to /automate (Phase 2b P0); /scrape is read-only by contract. Match decision lives in the agent, not the daemon. No new code in browse/src/, no expanded daemon command surface, no new prompt-injection blast radius. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(skillify): /skillify codifies last /scrape into permanent skill The productivity multiplier. /scrape discovers the flow; /skillify writes it as deterministic Playwright-via-browse-client code so the next /scrape on the same intent runs in ~200ms. 11-step flow with three locked contracts from the v1.19.0.0 plan review: D1 — Provenance guard. Walk back ≤10 agent turns for a clearly-bounded /scrape result. Refuse with one specific message if cold. No silent synthesis from chat fragments. D2 — Synthesis input slice. Extract ONLY the final-attempt $B calls that produced the JSON the user accepted, plus the user's intent string. Drop failed selectors, drop unrelated chat, drop earlier-session content. Closes Codex finding garrytan#6 by picking option (b) from the design doc: re-prompt from agent's own context, not a structured recorder. D3 — Atomic write. Stage to ~/.gstack/.tmp/skillify-<spawnId>/, run $B skill test against the temp dir, only rename into the final tier path on test pass + user approval. Test fail or approval reject = rm -rf the temp dir entirely. Default tier: global (~/.gstack/browser-skills/<name>/). --project flag overrides to per-project. Generated test must include at least one ★★ assertion (parsed JSON has expected shape + non-empty key fields), not a smoke ★ assertion. Bun runtime distribution (Codex finding garrytan#7) carries over to Phase 4. Documented in the skill's Limits section. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(browser-skills): gate-tier E2E for /scrape + /skillify (D4) Five scenarios cover the productivity loop and the contracts locked during the v1.19.0.0 plan review: scrape-match-path — intent matching bundled hackernews-frontpage routes via $B skill run, no prototype phase scrape-prototype-path — no matching skill, drives $B against a local file:// fixture, returns JSON, suggests /skillify skillify-happy-path — /scrape then /skillify; skill written to ~/.gstack/browser-skills/<name>/ with the full file tree; SKILL.md prose body must not contain conversation fragments (D2) skillify-provenance-refusal — cold /skillify with no prior /scrape refuses with the D1 message; nothing on disk (D1) skillify-approval-reject — /scrape then /skillify but reject in the approval gate; temp dir is removed, nothing at the final tier path (D3) All five gate-tier (~$0.50-$1.50 each, ~$5 total per CI run). Set EVALS=1 to enable. Uses local file:// fixtures so prototype + skillify scenarios run deterministically without network. Touchfiles registers all 5 entries with proper deps on scrape/**, skillify/**, browse/src/browser-skill-write.ts, and the Phase 1 runtime modules. The match-path test depends on the bundled hackernews-frontpage skill so its touchfile includes browser-skills/hackernews-frontpage/**. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(browser-skills): TODOS Phase 2a + design doc D1-D4 decisions TODOS.md: - Narrows existing P1 (was "/scrape and /automate") to "/scrape and /skillify" — the /scrape + /skillify wedge ships in this branch. Codex finding garrytan#6 (synthesis) removed from Cons (resolved by D2); finding garrytan#7 (Bun runtime) stays as the open carry-over. - Adds new ## P0 above PACING_UPDATES_V0 for the /automate follow-up. Same skillify pattern as /scrape, different trust profile (per-step confirmation gate when running non-codified). Reuses /skillify and the D3 helper as-is. Effort M. BROWSER_SKILLS_V1.md: - Phase table re-organized into 1, 2a, 2b, 3, 4. Phase 1 + Phase 2a consolidate into v1.19.0.0 ship (the v1.16.0.0 branch-internal bump never landed on main). - New "Phase 2a" sub-section captures the four decisions locked during /plan-eng-review: D1 — provenance guard (≤10 turn walk-back, refuse if cold) D2 — synthesis input slice (final-attempt $B calls only, closes Codex finding garrytan#6) D3 — atomic write discipline (temp-dir-then-rename via new browse/src/browser-skill-write.ts helper) D4 — full test scope (5 gate E2E + 1 unit + smoke) - New "Phase 2b" sketch for /automate: same skillify machinery, per-mutating-step confirmation gate, deferred to next branch. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * release: v1.16.0.0 -> v1.19.0.0 — browser-skills Phase 1 + 2a Consolidates the v1.16.0.0 branch-internal bump (Phase 1 runtime, never landed on main) with Phase 2a (/scrape + /skillify + atomic-write helper) into one v1.19.0.0 ship per CLAUDE.md "Never orphan branch-internal versions" rule. Headline: Browser-skills land end-to-end. /scrape <intent> first call drives the page; second call runs the codified script in 200ms. The unified CHANGELOG entry covers: - Phase 1 runtime: $B skill list/show/run/test/rm, scoped tokens, 3-tier storage, bundled hackernews-frontpage reference. - Phase 2a: /scrape + /skillify gstack skills, browser-skill-write.ts atomic helper, 5 gate-tier E2E + 34 unit assertions. Numbers table updated: 5 new modules (+browser-skill-write), 2 new gstack skills, 6 of 8 Codex outside-voice findings resolved (synthesis garrytan#6 closed by D2; Bun runtime garrytan#7 + OS sandbox #1 stay deferred to Phase 4). /automate (Phase 2b) is split out as P0 in TODOS for the next branch. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(commands): tighten descriptions for LLM-judge baseline pinning The skill-llm-eval test "baseline score pinning" failed CI on three retry attempts: judge gave command_reference.actionability=3, baseline demands ≥4. Judge cited 8 specific gaps in COMMAND_DESCRIPTIONS. This commit closes 7 of 8 by tightening the descriptions: - press: documents that key names are case-sensitive Playwright keys, shows modifier syntax (Shift+Enter, Control+A), links the full key list. Removes the "is this case-sensitive?" guesswork. - is: documents that <sel> accepts either a CSS selector OR an @ref token from a prior snapshot, and that property values are case- sensitive. - scroll: documents that there is no --by/--to amount option, points at `js window.scrollTo(0, N)` for pixel-precise scrolling. - js / eval: clarifies that both run in the same JS sandbox, the difference is just inline expr (js) vs file (eval). - storage: clarifies sessionStorage is read-only via this command, points at `js sessionStorage.setItem(...)` for the write path. - chain: walks through how to invoke (pipe a JSON array of arrays to $B chain), confirms it stops at the first error. - cdp: explains how to discover allowed methods (read cdp-allowlist.ts) + shows a concrete example invocation. - domain-skill: explains that the "classifier flag" is set automatically by the L4 prompt-injection scan (agents do not set it manually); enumerates the full lifecycle verbs. The 8th gap (storage set syntax conflict) is also resolved as part of the storage rewrite. Two pipe-character bugs caught by the existing `no command description contains pipe character` guard at `test/gen-skill-docs.test.ts:595`: the chain example originally used `echo '[...]' | $B chain` (literal pipe) and the cdp description used `tab|browser` / `trusted|untrusted` (also literal pipes). Both rewritten to keep markdown table cells intact. Verification: 696/0 pass on skill-validation + gen-skill-docs after regen across all hosts. The CI llm-judge eval will re-run against the new SKILL.md and should hit actionability ≥4 reliably. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(browser): rewrite BROWSER.md as complete reference Full rewrite covering the gstack browser surface as of v1.19.0.0. Up from 488 to 1,299 lines, 26 top-level sections. Adds previously-undocumented subsystems: - The productivity loop: /scrape + /skillify with D1 (provenance guard), D2 (final-attempt-only synthesis), D3 (atomic-write discipline) contracts. - Browser-skills runtime: anatomy, three-tier storage, scoped tokens, trust model (capability + env axes), sibling SDK distribution, atomic-write helper, bundled hackernews-frontpage reference. - Domain-skills: per-site agent notes with quarantined → active → global state machine and the L4-classifier auto-promotion gate. - Pair-agent: dual-listener architecture, 26-command tunnel allowlist, canDispatchOverTunnel pure gate, three token types (root, setup key, scoped), denial log path + salt model. - Security stack L1-L6: layer table, thresholds (BLOCK/WARN/LOG_ONLY/ SOLO_CONTENT_BLOCK), ensemble rule, classifier model paths, env knobs. - Side Panel deep dive: Terminal pane (Claude PTY) as the primary surface with Activity/Refs/Inspector as debug overlays, WS auth via Sec-WebSocket-Protocol, gstackInjectToTerminal cross-pane plumbing. - CDP escape hatch: $B cdp deny-default allowlist, $B inspect CSS inspector, $B ux-audit page structure extraction. - Meta commands previously undocumented: tabs/frames/state/watch/inbox/ tab-each, with usage and storage paths. - Authentication: three token types with lifetimes, SSE session cookie, PTY session cookie, token registry behavior. - Full source map: 30+ file inventory of browse/src/ vs the old 11-file list. Preserves from before: architecture diagram, daemon lifecycle, snapshot ref staleness, screenshot modes, goto file:// vs load-html semantics, batch endpoint, JS await wrapping, env vars, performance numbers vs MCP, Playwright acknowledgments, dev guide. Cross-links to ARCHITECTURE.md, CLAUDE.md, docs/REMOTE_BROWSER_ACCESS.md, docs/designs/BROWSER_SKILLS_V1.md, scrape/SKILL.md, skillify/SKILL.md, TODOS.md so anyone landing on BROWSER.md can navigate to the load-bearing companion docs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(server): tab-ownership gate keys on tabPolicy, not isWrite Browser-skill spawns hit `403: Tab not owned by your agent` on every first run because the gate at server.ts:639 fired for any non-root write, regardless of the token's tabPolicy. The bundled hackernews-frontpage reference skill failed identically. Every /skillify-generated skill failed identically. The user's natural tabs have no claimed owner — by design — so any skill driving them via `goto` (a write) was 403'd. The intent in skill-token.ts:79 was always correct: `tabPolicy: 'shared'` with the comment "skill scripts may switch tabs as needed." The enforcement just ignored it. Two surgical changes: browser-manager.ts:checkTabAccess — gate now keys on options.ownOnly only. Shared-policy tokens (skill spawns, default scoped clients) get permissive access — root-equivalent for the tab gate. Own-only tokens (pair-agent over the ngrok tunnel) still require ownership for every read and write. isWrite stays in the signature for callers that want to log or branch elsewhere; it no longer gates the decision. server.ts:639 — gate predicate narrowed from (WRITE_COMMANDS.has(command) || tokenInfo.tabPolicy === 'own-only') to just tokenInfo.tabPolicy === 'own-only' The 'newtab' exemption stays. Shared tokens skip the gate entirely; own-only tokens still hit it. Comment block above the gate updated to document the new predicate intent. Pair-agent isolation is intact. Tunnel tokens still default to tabPolicy: 'own-only', still must `newtab` first to get a tab they can drive, still can't dispatch any of the 23 commands outside the tunnel allowlist. The capability gate (scope checks) and rate limits already constrain what local scoped clients can do; tab ownership was never a security boundary for them — only for pair-agent. This release makes the enforcement match the original design intent. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(server): lock the shared-vs-own-only tab gate contract The pre-fix tests at tab-isolation.test.ts:43,57 encoded the broken behavior as the contract — they specifically asserted "scoped agent cannot write to unowned tab," which was the exact failure mode that broke browser-skills. They passed because they tested the wrong invariant. This commit replaces those tests with explicit shared-vs-own-only coverage that documents what each policy actually means: - Shared scoped agents (skill spawns, default scoped clients) can read AND write any tab — unowned, their own, or another agent's. The capability is gated by scope checks + rate limits, not by tab ownership. - Own-only scoped agents (pair-agent over tunnel) cannot read OR write any tab they don't own. Pre-fix this case was conflated with shared writes; now it's explicit. 9 unit assertions on checkTabAccess, up from 6. Each test names the policy axis it's covering so a future refactor can't quietly flip the contract. Adds source-shape regression test 10a in server-auth.test.ts: "tab gate predicate is own-only-scoped, not write-scoped." The gate's `if (...)` line MUST contain `tabPolicy === 'own-only'` and MUST NOT contain `WRITE_COMMANDS.has(command) ||`. If a future refactor re-introduces the write-scoped gate, this fails immediately in free-tier `bun test`. Updates the marker for the existing newtab-excluded test to match the new comment block ("Tab ownership check (own-only tokens / pair-agent isolation)"). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * release: v1.19.0.0 -> v1.20.0.0 — fix tab-ownership footgun Patch release on top of v1.19.0.0. The shipping headline of v1.19.0.0 (/scrape + /skillify productivity loop) was broken on first run in any session where the daemon already had a tab. Bundled hackernews-frontpage failed identically. Every /skillify-generated skill failed identically. The fix narrows the tab-ownership gate from "any non-root write" to "tabPolicy === 'own-only' only." Pair-agent isolation (the v1.6.0.0 threat model) is intact; local skill spawns get their original behavior back. VERSION: 1.19.0.0 -> 1.20.0.0 package.json version: synced. CHANGELOG entry leads with the user-visible impact: the productivity loop works again, no half-second-stalls of confused 403s. Includes before/after metrics on the bundled reference skill and the broken- contract pre-fix tests that hid the regression. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(claude): sharpen CHANGELOG rule — diff between main and ship Codifies what was already implicit in the existing "Never orphan branch-internal versions" + "Only document what shipped between main and this change" sections, but with sharper language and concrete NEVER examples. The rule: a CHANGELOG entry is the diff between main and the shipping branch — what users get when they upgrade. NOT how the branch got there. Branch-internal version bumps, mid-branch bug fixes, plan review outcomes, and patch narratives all belong in PR descriptions and commit messages, not in CHANGELOG. Adds explicit examples of phrasing to NEVER use: - "v1.X had a bug that v1.Y fixes" (mentions a branch-internal version) - "The shipping headline of v1.X was broken because..." (apologizes for never-released state) - "Pre-fix tests encoded the broken behavior" (contributor's victory lap, not user benefit) - "Two surgical edits, both in the dispatch path" (micro-narrative of the patch) The constructive replacement: describe the released system as a property, not as a fix. "Browser-skills run end-to-end with the expected tab-access semantics." If a property is worth calling out, document it in the trust-model section, not as a "we fixed X" callout. Pairs with feedback_no_shame_changelog and feedback_changelog_harden_against_critics memories — entries should read as a flex even to a hostile screenshotter, never admit prior breakage. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(changelog): consolidate v1.20.0.0 as the diff vs main Rewrites the v1.20.0.0 entry to describe what users get when they upgrade from main (v1.17.0.0) to this release: browser-skills end-to-end. Drops all branch-internal narrative — Phase 1 / Phase 2a labels, the v1.8.0.0 P1 history paragraph, the test-counts-by-phase split, and the patch micro-narrative for the tab-policy semantics. The previously-separate v1.19.0.0 entry (a branch-internal version that never landed on main) collapses into v1.20.0.0 per the "Never orphan branch-internal versions" rule. Tab-access policies are now documented as a property of the trust model: `'shared'` (skill spawns) is permissive, `'own-only'` (pair-agent over the tunnel) is strict. No "fix" framing, no mention of an intermediate state where it was broken. Adds the BROWSER.md rewrite and the new tab-isolation + server-auth source-shape regression tests to the itemized changes. The reverse-chronological order remains: v1.20.0.0 → v1.17.0.0 → v1.16.0.0 → v1.15.0.0 → ... Gaps (v1.18, v1.19) are fine — those were branch-internal version numbers that never landed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ships
gstack-build, a code-driven phase orchestrator for the/buildskill. The current/buildskill drives multi-phase builds via the LLM; in practice the orchestrator stalls between phases ("Standing by, let me know what's next") even with explicit "don't stop" rules, and context compaction loses awareness of "I'm in the middle of a 12-week build." The new CLI drives the loop in code while still spawning fresh Gemini and Codex subprocesses per phase. Code = state machine + persistence + retry. LLM = per-phase brain with a clean context window.New components
bin/gstack-build— bash wrapper invokingbuild/orchestrator/cli.tsvia bun. Exposed inpackage.jsonbinmap.build/orchestrator/— 9 TypeScript modules (cli, parser, phase-runner, sub-agents, plan-mutator, state, gbrain, ship, types) totaling ~1,800 lines.build/orchestrator/README.md— usage, env vars, file layout, failure modes, exit codes, architecture diagram.Skill changes
build/SKILL.md.tmpl(and regeneratedbuild/SKILL.md) v1.10.0 → v1.11.0: added "LLM-driven loop vs. code-driven CLI" note recommendinggstack-buildfor long plans (5+ phases).Pre-Landing Review
/reviewran on the branch. 4 issues found, all actioned:runShip()was passing'/ship && /land-and-deploy'as ONE prompt to ONE claude invocation. Shell&&doesn't get interpreted inside a-pargument, so/land-and-deploywould never have fired. Fixed: spawn claude twice, sequentially, with separate log files. Verified end-to-end with mocked claude.cli.ts:451hadrequire('node:child_process').spawnSyncmixed with ESM imports. Promoted to top-of-fileimport { spawnSync } from 'node:child_process'.PR Quality Score: 9.0/10. Status: clean.
Plan Completion
Plan:
~/.claude/plans/c-and-use-plan-eng-review-expressive-panda.md. All 8 phases checked off. The orchestrator can read its own implementation plan and reports 8/8 done — meta-correct.Test plan
bun testexits 0gstack-build --helpworks via bash wrappergstack-build <plan-file> --print-onlycorrectly shows phase status--dry-runwalks state machine without spawning sub-agents🤖 Generated with Claude Code