v1.80.0.0 fix: setup survives a failed Chromium install, hooks share one state root, gstack never clobbers a skill it did not create

[garrytan]

Summary

Fork-port Wave A from the time-attack/gstack residual evaluation: three defects in upstream's own tree that the fork surfaced, fixed at the source, plus the ownership model the pre-landing review demanded.

• ./setup never aborts at the Chromium bootstrap. The Playwright install is best-effort and bounded (600s default, GSTACK_PLAYWRIGHT_INSTALL_TIMEOUT, GSTACK_SKIP_PLAYWRIGHT=1), every failure is a reason code in the final summary, and skills always register. Stale-lock reclaim is atomic and pid-validated; a lock with no recorded holder expires; a wedged installer is killed with its child tree even where pgrep is missing.
• /freeze and /careful resolve the same state root the writers use (gstack_hook_state_root mirrors bin/gstack-paths). Under GSTACK_HOME the freeze boundary denies instead of allowing everything; a helper from an older install, a newline-terminated root, or an unexpected set -e death all fail closed.
• gstack never deletes or links over a skill it did not create (fix(relink): don't clobber foreign skills that share a gstack name #2119). Ownership proof has two strengths. Strong (the .gstack-owned marker gstack writes for directories it creates, or a directory holding nothing but symlinks) may remove a directory whole. Weak (byte-identity or the two-line generated banner on a real file) covers only that SKILL.md and our asset links, and a customized file is moved to ~/.gstack/backups/skills/<ts>/ before we link over it. Foreign entries are reported by name. Applies to setup's linker, alias installer, both prefix-flip cleanups, and gstack-relink.
• Setup's one-shot telemetry events use --no-sweep so they never finalize other sessions' in-flight markers.
• The evaluation evidence lives under docs/designs/fork-port-residual-2026-09/.

Closes #1900, #1901, #1902, #913, #2233, #1459, #1509, #2119.

Design notes

• Lock contention is a reason code by design. Another setup holding the lock means this run registers skills and re-probes next time; it does not wait. The plan's "lock held by a live pid exits 1" verification bullet predates that CEO-review decision.
• Provenance rule. Symlink into gstack (install dir, render dir, any path with a gstack segment, or a tree carrying setup + VERSION + bin/) or the marker = strong. Byte-identity or the two-line banner within the first 8 KB = weak. A directory with no SKILL.md is unclaimed: the link pass may add ours, the cleanup pass leaves it alone. Accepted residuals: the gstack path-segment convention (needed for sibling worktrees and moved checkouts), and a gstack fork that renders the same banner (weak proof only, so the worst case is one backed-up file).
• Windows legacy installs. Pre-marker copies refresh in place via weak proof; on a prefix flip their copied asset directories stay behind in a SKILL.md-less directory (harmless, reported).

Test plan

• bun run test (strict sharded runner, six shards, under xvfb-run on this VM): 8,772 tests across 528 files, all six shards green, recorded by gstack-evidence (label tests, exit 0). Seven earlier full runs on this VM each lost exactly one Chromium/PTY/daemon-bound test to shard load or, in single-process mode, to cross-file interference (design/test/feedback-roundtrip, browse/test/terminal-agent-integration, browse/test/handoff, make-pdf/test/e2e/format-gate, browse/test/watchdog, design/test/daemon*); every one of those files is untouched by this branch and passes alone.
• 103 net new free tests across 10 files: static invariants plus bash harnesses for the bootstrap block (probe/installer stubs, timeout, lock, kill tree without pgrep), the ownership gates (setup linker, alias installer, both flip cleanups, relink), backups, markers, the hook state root (parity with gstack-paths, plugin/GSTACK_HOME precedence, stale helper, backstop), and --no-sweep.
• Anchor-sliced harnesses fail loudly on command not found instead of degrading into "foreign, skipped".
• Windows lane (CI): windows-free-tests green on the final head. The first push failed there in test/setup-alias-name-uniqueness.test.ts: the harness passed its assembled script as one bash -c argv element, and MSYS2's runtime inside bash.exe silently truncates any glob-character-bearing argument at 8186 characters (a fixed 8192-byte glob buffer), so the 15.7 KB script was cut mid-token. Every setup harness now runs its script from a temp file via test/helpers/bash-script.ts; the Windows-curated file list is byte-identical before and after.

Plan Completion

Plan file: 31 items in Wave A. 24 DONE, 6 CHANGED (implementation differs from the plan text by design: lock contention is a reason code, not an exit; shared gstack_hook_state_root instead of a per-hook chain; ownership proof has two strengths instead of one gate; markers on every platform; banner match by bytes; tree heuristic), 1 UNVERIFIABLE (issue closing happens on merge via the Closes lines above). Waves B through E2 are scheduled follow-ups, not part of this PR.

TODOS

• Marked the setup Playwright bootstrap coverage gap as pinned except _clear_playwright_quarantine.
• Filed the fork-port residual wave deferrals (shared ownership helper, marker-path load-bearing, extractFn dedup, sleep granularity, 600s default) and updated the PR fix(memory): enforce transcript trust, scope, and source isolation #2232/fix(setup): bound Playwright bootstrap and preserve skill registration #2233 entries.

Documentation

Doc diff preview (commit 23fccb98):

• README.md: new troubleshooting entry for the Not registered (a skill you own already uses the name; left untouched) setup summary: what proves gstack owns a skill entry (symlink into gstack, .gstack-owned marker, byte-identical or generated-banner SKILL.md), how to resolve a name collision (rename/move, or ./setup --prefix / --no-prefix), and where a customized generated SKILL.md is moved (~/.gstack/backups/skills/<timestamp>/<skill>/SKILL.md). Manual-uninstall snippet now removes .gstack-owned-marked directories (the only signal on Windows copy installs).
• CLAUDE.md: "Ownership gate (fix(relink): don't clobber foreign skills that share a gstack name #2119)" paragraph in Dev symlink awareness: strong vs. weak proof, backups path, the two-copy rule (setup + bin/gstack-relink), pinning tests.
• CONTRIBUTING.md: two new "Things to know" invariants (never delete/link over an entry setup cannot prove is gstack's, naming the helper functions in both scripts; ./setup never fails on Chromium, with all seven reason codes and GSTACK_PLAYWRIGHT_INSTALL_TIMEOUT / GSTACK_SKIP_PLAYWRIGHT=1). "Switching prefix mode" notes only gstack-created entries are removed.
• docs/PROJECT_STRUCTURE.md: added careful/ (check-careful.sh + hook-extract.sh with gstack_hook_state_root), freeze/ (check-freeze.sh, fails closed), guard/, unfreeze/, gstack-upgrade/; gstack-relink in bin list; setup-*/relink/hook-scripts test line; setup entry mentions the best-effort Chromium bootstrap and ownership gate; docs/designs/ names fork-port-residual-2026-09/.
• docs/TESTING_INTERNALS.md: new "Anchor-sliced setup harnesses" paragraph (extractFn/block anchors, function not found / anchor not found failures, the command not found drift check, how relink.test.ts and hook-scripts.test.ts exercise the real scripts).

CHANGELOG.md, VERSION, TODOS.md untouched by the doc sync. The doc sync flagged that setup's own linker backed up customized files silently; the summary now reports them (commit e64bab7a).

Documentation Debt

• gstack-telemetry-log --no-sweep: reference only (CHANGELOG + script header); no contributor how-to.
• gstack_hook_state_root (careful/bin/hook-extract.sh): the writer/reader state-root parity rule is explained in code comments and CHANGELOG only.
• GSTACK_PLAYWRIGHT_INSTALL_TIMEOUT / GSTACK_SKIP_PLAYWRIGHT: reference + how-to in README; no getting-started walkthrough for a no-browser/CI install.

Review coverage

Review army (Testing, Maintainability, Security, Performance, Data-Migration, API-Contract, Claude Red Team) ran three cycles; every CRITICAL/HIGH/MEDIUM finding was fixed with a regression test. Cycle 1 (pre-landing): the linker and prefix-flip cleanup clobbered same-name skills, the trap left an orphaned installer, the npm chain masked failures, GSTACK_SKIP_PLAYWRIGHT read as a failure, TIMEOUT=0 killed on the first poll, the careful hook read a different state root, and the README fence swallowed the troubleshooting note. Cycle 2: relink's flip cleanup rm -rf'd a real-file directory on Linux/macOS on weak proof (HIGH, fixed by the two-strength model), banner-only proof overwrote a customized file (fixed by backups), relink's fast path drifted from setup (removed), the banner check read 40 lines while four skills carry it past line 40 (bytes now), a worktree named without a gstack segment was foreign (tree heuristic), _kill_tree needed pgrep (/proc fallback), a lock with no pid never expired, and freeze had no backstop for set -e deaths. Cycle 3: runtime assets in an unclaimed or weakly-owned directory were still replaced, the flip cleanup deleted a customized file the link pass would have backed up, a failed backup fell through to an overwrite, a foreign directory symlink slipped through as unclaimed, alias installers stamped markers into pre-existing directories, the lock hand-back missed a fresh lock without a pid, and the /proc parser stopped at the first paren. All fixed, each with a regression test. Accepted and documented: the gstack path-segment convention, a fork rendering the same banner (weak proof only), and Windows legacy asset copies left behind in a SKILL.md-less directory after a flip.

Codex outside voice (two passes, codex exec, sandbox danger-full-access because bwrap is unavailable on this VM)

Pass 1, adversarial (5 findings, all fixed):

1. P1 "a colliding skill can forge the AUTO-GENERATED comment and trigger recursive deletion" — accepted. Superseded by the two-strength model: banner or byte-identity is now WEAK proof that covers one file and never deletes a directory; only the .gstack-owned marker (we created the dir) or an all-symlinks directory authorizes rm -rf.
2. P1 "any path segment named gstack bypasses provenance; the fast path judges /x/gstack/../foreign before canonicalizing" — accepted. relink's fast path is removed; both files canonicalize first. The segment convention itself stays (sibling worktrees, moved checkouts) and is documented as accepted.
3. P1 "the synthetic session id does not prevent sweeping other sessions' pending markers" — accepted and verified against bin/gstack-telemetry-log. New --no-sweep flag; both setup one-shot events use it.
4. P2 "timeout validation accepts 000 and values bash cannot compare" — accepted. Normalized to a positive integer, nine-digit cap, default on anything else.
5. P2 "check-careful calls the new helper without an existence check" — accepted. Falls back to ${GSTACK_HOME:-$HOME/.gstack}; freeze already denied.

Pass 2, review (2 findings, both fixed):

1. P2 relink's _gstack-command alias was written without the ownership gate — gated, and alias copies are stamped with the marker.
2. P3 the failure summary listed browser skills as if exhaustive — reworded as examples.

Codex's "request changes" verdicts were both acted on; every finding closed with a regression test.

🤖 Generated with Claude Code

---

Open workspace in Conductor

[trunk-io]

😎 This pull request was merged.

[github-actions]

E2E Evals: ✅ PASS

0/0 tests passed | $0 total cost | reconcile exit: 0

Shard	Result	Status	Cost

Fail-closed reconciliation

[test:paid] report: 6/6 slices, 4 planned shards, tier=gate
  slice 1  passed              0s  test/llm-judge-recommendation.test.ts
  slice 2  passed              0s  test/skill-llm-eval-spec.test.ts
  slice 3  passed              0s  test/skill-llm-eval.test.ts
  slice 4  passed              0s  test/skill-routing-e2e.test.ts
[test:paid] report: ⚠ 3 shard(s) passed with EVERY test skipped — they verified nothing:
  ⚠ test/llm-judge-recommendation.test.ts (1 skipped — external service missing or tier mismatch)
  ⚠ test/skill-llm-eval.test.ts (25 skipped — external service missing or tier mismatch)
  ⚠ test/skill-routing-e2e.test.ts (10 skipped — external service missing or tier mismatch)
[test:paid] report: every planned shard accounted and passed

---

Sliced lane: diff-selected gate census via scripts/test-paid-shards.ts (planner → 6 executors → fail-closed report)