Skip to content

test: keep update-channel tests off the real state root, and guard it (GST-1659) - #4094

Merged
capy-ai[bot] merged 1 commit into
mainfrom
capy/gst-1659-state-root-isolation
Nov 6, 2026
Merged

capy-ai[bot] merged 1 commit into
mainfrom
capy/gst-1659-state-root-isolation

Conversation

@garrytan

@garrytan garrytan commented Nov 6, 2026 •

Copy link
Copy Markdown
Owner
{
  "schema_version": 1,
  "pr": 4094,
  "head": "ffa7d2e0396734bbe7fca37f6f975c69232ebab6",
  "version": "1.97.0.0",
  "base": "main",
  "gate": {
    "focused": {
      "pass": 23,
      "fail": 0,
      "skip": 0
    }
  },
  "session_kind": "unattended",
  "head_tree": "c6cd363595a4f8372eca493c99532ad61c284dae",
  "product_patch_id": "692e514bbf08069bd3650f8b50a50b69eabbb86f",
  "gstack_version": "1.97.0.0",
  "review_depth": {
    "depth": "full",
    "class": "gate",
    "runtime_lines": 1,
    "rules": "70895942bb8a8ee2",
    "base": "a7585d0e74db25e861a92263fcae7e73a2e4d4ad",
    "registry": "a7585d0e74db25e861a92263fcae7e73a2e4d4ad",
    "gate_scan": {
      "tagged": 0,
      "head": "ffa7d2e0396734bbe7fca37f6f975c69232ebab6"
    },
    "reasons": [
      "gate-class",
      "runtime=1"
    ],
    "risk": [],
    "mode": "panel"
  },
  "pregate": "requires-remote cleared @c6cd363595a4 (8 checks, current for ffa7d2e03967)",
  "requires_remote": [
    "windows-smoke.yml/windows-smoke: https://github.com/garrytan/gstack/actions/runs/42282505157/attempts/1"
  ],
  "issues": {
    "fixes": [],
    "refs": [],
    "flakes": []
  },
  "docs": {
    "status": "current",
    "scope": "docs/, README.md, CLAUDE.md, AGENTS.md, CONTRIBUTING.md (read-only; test-only diff, no public surface change)"
  },
  "review_loop": {
    "passes": 1,
    "blocking_found": 0,
    "deferred": 0,
    "noted": 1,
    "fixed": 0,
    "scope": "frozen",
    "rounds": 1,
    "ledgers_read": 1,
    "dispatches": {
      "specialist": 3,
      "red-team": 1
    }
  }
}

What changed

An exported GSTACK_STATE_ROOT no longer receives the test's gstack-config writes

An exported GSTACK_STATE_ROOT no longer receives the update-channel test's gstack-config writes: on main the sentinel's config.yaml gains update_channel: stable, and on this branch it stays unchanged.

Before/after as text: An exported GSTACK_STATE_ROOT no longer receives the test's gstack-config writes
--- Before · before.txt · captured output
+++ After · after.txt · captured output
+# PR head ffa7d2e: same command
+(pass) gstack-config update_channel > defaults to auto, accepts auto|stable|main, and refuses anything else without changing the stored value [683.72ms]
+ 1 pass
+ 0 fail
-# main a7585d0: GSTACK_STATE_ROOT=<sentinel> bun --config=/dev/null test test/update-channel.test.ts -t 'defaults to auto'
-(fail) gstack-config update_channel > defaults to auto, accepts auto|stable|main, and refuses anything else without changing the stored value [548.86ms]
- 0 pass
- 1 fail
 $ cat $GSTACK_STATE_ROOT/config.yaml   # exported sentinel
 telemetry: off
-update_channel: stable
 

Why

GST-1659: running test/update-channel.test.ts without this repository's bunfig.toml preload (from another directory, or with bun --config=/dev/null test) wrote update_channel into whatever GSTACK_STATE_ROOT the shell exported, which can flip a developer's or crew machine's update channel. Those tests now keep every write in their own temp roots, and a guard test fails if any exported state root or HOME changes. The install fixture also accepts a worktree whose node_modules is a symlink, which broke update-channel-setup.test.ts 4 of 4 in a worktree.

Evidence

  • Repro on main (a7585d0): GSTACK_STATE_ROOT=<sentinel> … bun --config=/dev/null test test/update-channel.test.ts ran 15 pass and 1 fail, and the sentinel's config.yaml gained update_channel: stable.
  • The guard on the unfixed test and helper fails with state-root/config.yaml changed. With the fix it runs 3 pass in about 43 s.
  • In a worktree with node_modules -> /workspace/gstack/node_modules, update-channel-setup.test.ts failed 0/4 before the fix and passes 4/4 after it.
  • All 41 test files that use gstackHome ran 1211 pass and 8 fail. The 8 failures are all in gbrain-sync-skip.test.ts and fail the same way without this change, because the machine-local bun shim does not find bun on that test's scrubbed PATH.
  • bun run typecheck and typecheck:test report no new diagnostics. The state-root ratchet, bun-entry isolation, spawnSync tripwire, module-size ratchet and install-fixture tests all pass.

Blast radius

Test code only, with no product change. runBin's gstackHome option now sets GSTACK_STATE_ROOT too, which reaches its 59 callers; under the normal preload GSTACK_STATE_ROOT is absent, so they resolve the same directory as before, and CI's free suite passed at this head (run 42282505151, 36060 tests carried). The guard adds about 43 s to the free suite, seeded in scripts/free-test-durations.json.

Approvals

No approvals recorded for branch capy/gst-1659-state-root-isolation.

Summary

The runBin helper set GSTACK_HOME and GSTACK_STATE_DIR but not GSTACK_STATE_ROOT, which outranks both, and test-setup.ts strips that variable only when Bun loads this repository's bunfig.toml. Now gstackHome sets all three state-root variables, every spawn in update-channel.test.ts starts from isolatedEnv() (the state-root chain removed and HOME in a temp dir), and test/state-root-isolation.test.ts runs both update-channel test files with the whole chain and HOME pointed at sentinel directories. A planted test that calls gstack-config set on the inherited environment is the negative control, and the guard catches it writing state-root/config.yaml.

Test Coverage

All new code paths have test coverage: the change is test code, and the new guard carries its own negative control.

Tests ran: focused 23 (bun test --timeout=30000 test/update-channel.test.ts test/state-root-isolation.test.ts test/update-channel-setup.test.ts, Capy git guard directory removed from PATH; see Review notes)

Pre-Landing Review

No blocking issues found. Readers: batched specialist (testing, security, state-machines), red team, native adversarial (Opus 5.5) and outside voice (GPT-6.1 Sol, medium). Specialists, red team and outside voice reported no findings; the adversarial reader and the lead review raised 5 low-severity notes, listed under Review notes, none fixed (below the crew blocking floor).

REVIEW_LOOP: passes=1 blocking_found=0 deferred=0 noted=1 fixed=0 scope=frozen ledgers_read=1 dispatches=4

Gate edits: none detected (19 listed, 16 read; patterns: RH-1,RH-3,RH-4,RH-12,RH-13,RH-14,RH-15,RH-16; unlisted idioms: none)

Outside review: completed, GPT-6.1 Sol via a host subagent, recommendation approve, no findings.

Review notes

  • test/state-root-isolation.test.ts:44 (lead review): the guard's child bun test runs with Bun's default 5 s per-test timeout, while the free suite uses 30 s. The slowest guarded test took 1.8 to 2.8 s on a 2-core machine, so only a heavily loaded runner could fail the guard while the file passes. Passing --timeout=30000 to the child would match the suite.
  • Adversarial docs: add README and CLAUDE.md #1: the sentinel diff ignores empty directories and entries named .capy (tree() in install-fixture.ts skips them), so a leak that only creates a directory or writes under HOME/.capy would pass the guard.
  • Adversarial refactor: reorganize codebase into modular structure #2: runBin's gstackHome now overrides a caller's explicit env.GSTACK_STATE_ROOT. The one caller passing both (test/gate-diff-cli.test.ts:41, which unsets it) still passes.
  • Adversarial Project-local .claude/skills/gstack install breaks /browse and setup can report false success #3: the guard's BUN_RUNTIME_TRANSPILER_CACHE_PATH is a fixed shared path under the temp dir and is never cleaned; a per-run path under the sentinel base would avoid sharing.
  • Adversarial Fix project-local /browse installs and harden setup #4: the changelog fragment says every spawn in update-channel.test.ts starts from the isolated environment, but the runBin call still inherits CLAUDE_PLUGIN_DATA; it is safe because GSTACK_STATE_ROOT outranks it.
  • Environment, not this diff: on a machine whose first git on PATH is a PATH-searching wrapper (Capy's shared-tree git guard), the gstack-update-check test's git shim and the wrapper exec each other until the 30 s timeout. It fails identically on main a7585d0, and CI does not have the wrapper.

Exploratory QA

Smoke: the focused lane (23 pass), update-channel.test.ts under --config=/dev/null (16 pass, slowest 1.8 s), the guard's planted-leak negative control (passes inside the guard), and the before/after repro above (main writes update_channel: stable to the exported sentinel; this head writes nothing). QA method files were not read for this test-only diff.

Design Review

No frontend files changed — design review skipped.

Eval Results

No prompt-related files changed — evals skipped.

Review bot comments

No review bot comments.

Scope Drift

Scope Check: CLEAN

Plan Completion

Plan completion audit: not run (no plan is bound to this branch and no docs/designs/ file matches). This is a bug fix with a repro on main, so it skips plan review.

Verification Results

No Step 8.1 obligations (no plan bound).

TODOS

No TODO items completed in this PR.

Documentation

Status: current. This was a read-only audit, and no documentation changes are needed.

Audited scope: 7 committed files from a7585d0 to ffa7d2e, with no staged, unstaged or new files. The branch changes only test infrastructure: runBin's gstackHome option now sets all three state-root variables, update-channel tests spawn from an isolated environment, the new guard test/state-root-isolation.test.ts and its helper test/helpers/state-root-isolation.ts were added, the install fixture no longer treats a node_modules symlink as source, there is a new test-durations entry, and there is a changelog.d fragment. I checked these against the state-root, testing, contributor and entry-point docs.

Documentation health:
  README.md                 Current (no user-facing surface changed)
  ARCHITECTURE.md           Current (no state-root or test-helper content, no diagram entities changed)
  CONTRIBUTING.md           Current (nothing contradicted)
  CLAUDE.md                 Current (nothing contradicted)
  AGENTS.md                 Current (state-root chain convention unchanged)
  docs/state-root.md        Current (chain order matches lib/state-root.ts STATE_ROOT_VARS)
  docs/TESTING_INTERNALS.md Current (install-fixture section still accurate)
  CHANGELOG.md              Not edited (top entry 1.97.0.0 matches VERSION; owned by the parent)
  changelog.d fragment      Reviewed (claims match the diff; not edited)
  TODOS.md                  Skipped (outside ship-owned scope)

Coverage: All shipped features have adequate documentation. No public surface changed, so there are no critical or common gaps and no diagram drift.

Low-priority debt (optional): The new state-root isolation guard (test/state-root-isolation.test.ts) and its isolatedEnv helper are explained only in source comments. A one-line how-to pointer in the docs/TESTING_INTERNALS.md fixtures section would make them easier to find.

Test plan

  • bun test --timeout=30000 test/update-channel.test.ts test/state-root-isolation.test.ts test/update-channel-setup.test.ts (Capy git guard directory removed from PATH): 23 pass, 0 fail
  • CI free suite at ffa7d2e (run 42282505151): green, carried by the pregate for 68 of 68 selected test files
  • windows-smoke at ffa7d2e (run 42282505157): success
  • Pregate guards: typecheck, module-size and conflict-markers pass

🤖 Generated with Claude Code

Open in Capy

…T-1659)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@trunk-io

trunk-io Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

@capy-ai
capy-ai Bot merged commit 6782763 into main Nov 6, 2026
43 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant