v1.91.19.0 fix: severe fix wave (truthful gates, no lost memory, every host finds gstack) (#3025)

* docs: approved severe fix wave plan (Oct 2026)

* D0: keep a project's .env and bunfig.toml out of compiled binaries and daemon children

Compiled binaries are built with --no-compile-autoload-dotenv and
--no-compile-autoload-bunfig; the browse server and terminal agent are
spawned with --no-env-file and an empty config, so a repo's .env cannot set
GSTACK_CHROMIUM_NO_SANDBOX and a bunfig preload cannot run code in them.
Verified on Bun 1.4.0.

* A9: --no-write is a dry run and leaves ingest state untouched

--no-write stamped every prepared page ingested_at and saved state, so a
later real run skipped those pages forever. It now prepares and reports
pages without importing or changing the state file.

Tests that used GSTACK_MEMORY_INGEST_NO_WRITE / --no-write to seed state
move to an explicit seam (a fake gbrain that accepts every staged page),
because the --no-write contract deliberately changes.

* H #2885 #2827: vector geometry is not phone or card PII

pii.phone.e164 accepts "." as a group separator, so a single float
(viewBox="0 0 581.66796875 ...") and a run of path coordinates
("37.6188 101.694") read as phone numbers. pii.cc's \b stops at a decimal
point, so the long fraction of an .excalidraw float is a Luhn candidate.
Excalidraw's seed/versionNonce/updated integers read as bare phone numbers.
A rendered /diagram triplet raised 18 (svg) and 97 (excalidraw) MEDIUM
findings on main; it now raises none.

- looksLikeDecimalCoordinates (ported from #2885, extended to a single
  decimal and refusing a leading "+", the E.164 marker)
- insideDecimalNumber: a cc span glued to "<digit>." or ".<digit>"
- isNumericMetadataValue: an unquoted JSON value under a seed, nonce or
  timestamp key; the same digits under "phone" still report

Controls: E.164 in prose, dotted and spaced phones, "+"-prefixed runs,
"phone"/"contact" JSON numbers, Luhn-valid cards in prose and at sentence end.

Co-authored-by: Lewis <lewispeel@hotmail.com>

* D1: pin the terminal-agent /ws Origin to the gstack extension (#1324)

GSTACK_EXTENSION_ID moves to browse/src/extension-id.ts, shared by
/extension-token and the terminal agent's /ws gate. /ws now returns 403 for
every origin except the pinned extension. Forks override the ID with
gstack-config set browse_extension_id <id>, honored by both routes; the
BROWSE_EXTENSION_ID env var is no longer read. Test sites that used fake
extension IDs now use the pinned origin.

* H #2899: env.kv skips a function call assigned to a credential name

`session = _FlakySession(...)`, `token = make_token(user, ...)` and
`password = getpass.getpass()` raised env.kv MEDIUM, which blocks the
fail-closed decision log. The exemption needs the line's evidence, not the
span's shape: the value is unquoted, is an identifier or dotted path
followed by "(", and the call closes on the line or opens a multi-line
argument list. Quoted values, unclosed "(" inside an unquoted secret
(API_SECRET=Abc123xyz(9Qm) and calls carrying a high-entropy literal
argument still report. The literal check is shared with the #2912 env-read
exemption.

Co-authored-by: Yugz <yannduzelier@gmail.com>

* H #2962: per-machine config filenames are not internal hostnames

`CLAUDE.local.md` and `settings.local.json` reported internal.hostname
MEDIUM (the pattern's \b stops at the dot before the extension), which fails
closed in the decision log. A span immediately followed by a known config
extension (.md .json .jsonc .yaml .yml .toml .ini .conf .txt) and a word
boundary is a filename. Controls: `ssh build.local`, `printer.local.` at a
sentence end, `printer.local/md`, `printer.local.mdx`, a host with a port,
`api.corp`, `build-7.internal`. The `.env.local` vectors (#2740) pass on
main already via isDotenvFilename and are pinned here as regressions.

Co-authored-by: Florian <florian.cleyetmerle@gmail.com>

* H #2784: four-part versions need a version declaration, not a shape

`"version": "1.128.1.0"`, `<Version>`, `AssemblyVersion("1.0.0.0")` and
Keep a Changelog headings raised pii.ip_public MEDIUM on every release,
because a four-part version is byte-for-byte a dotted quad. Exempt only when
the same line declares it a version immediately before the value (a version
key or word, an XML tag, an attribute call, or a `## [x]` heading). The same
digits after host:/server =/"upstream", bare on a line, or after prose that
merely mentions a version still report. Unlike #2784, this does not exempt a
value because the same string is declared a version elsewhere in the text:
that let a real address sharing a diff with a matching version slip. The
pre-push hook's VERSION-file rule (#2856) is unchanged.

Co-authored-by: cdecook23 <decook23@gmail.com>

* H #2913: postgres:postgres is exempt only on a loopback host

The postgres image's default pair in compose files and CI DATABASE_URLs
blocked pushes as db.url_with_password HIGH. It is now exempt only for
postgres/postgresql URLs with exactly postgres:postgres on localhost or
127.0.0.1 (optional port). A bare single-label host (`db`, `postgres`), any
other host, a host that merely starts with localhost (`localhost.evil...`,
`localhost@prod-db`), any other user or password, and other schemes still
block. #2913 exempted the pair on any host; this keeps the plan's narrower
rule.

Co-authored-by: mb1810 <michael.berger1810@gmail.com>

* G1: ship without a version when no version source is configured

Resolve the version source to four outcomes (valid, absent, ambiguous,
broken) in lib/version-source.ts and read that one signal in
gstack-version-bump (new NO_VERSION state; write refuses to invent a
VERSION), gstack-next-version (no_version, no slot), /ship's bump,
CHANGELOG and title steps, /land-and-deploy's drift check and
/document-release. A configured version file that is missing, empty,
unreadable or malformed stops with its path; 0.0.0.0 is never
substituted. docs/skills.md documents .gstack/version-path.

Migrates two tests that pinned the old fabricated-0.0.0.0 behavior.

Co-authored-by: Koda <koda@edgeviewfinance.com.au>
Co-authored-by: Merit Blake <merit@newsprint.com>

* H #2949: eval credential screen checks every name segment

The hermetic eval env admits GITHUB_* and EVALS_* metadata but rejects
credential-shaped names, judged only by the last underscore segment. A
trailing qualifier carried a credential through: GITHUB_APP_PRIVATE_KEY_BASE64,
GITHUB_TOKEN_1, EVALS_API_KEY_FALLBACK reached eval children. The screen
now rejects a name when any segment is a credential word; segments, not
substrings, so GITHUB_PATH / GITHUB_TOKENIZER / GITHUB_KEYRING stay
metadata, and explicit runner admissions still win.

Co-authored-by: Nguyen Thanh Dat <ntdat812@gmail.com>

* H #2915: cover chunked scanning of large multi-file push diffs

Test-only coverage for behavior already on main: a clean two-file pushed
diff over the engine's 1 MiB cap passes without engine.input_too_large, and
a credential at the end of the second file (a later scan chunk) still
blocks the push.

Co-authored-by: pneumorea-ai <pneumorea@gmail.com>

* A3: keep a project's DATABASE_URL away from a PGLite brain

With a PGLite config, buildGbrainEnv returned the caller env unchanged, so
a project's .env DATABASE_URL (autoloaded by Bun) reached gbrain: a false
broken-db at best, gbrain talking to the app's own Postgres at worst.
Inherited DATABASE_URL and GBRAIN_DATABASE_URL are now blanked for PGLite
configs (GSTACK_RESPECT_ENV_DATABASE_URL=1 still keeps them), and every
gbrain child runs from gbrain's config dir instead of the user's project,
so it cannot reload the project's .env / .env.local.

The old test that pinned pass-through for an engine:pglite config is
migrated: pass-through now applies only to configs that name neither a
database_url nor PGLite.

Co-authored-by: maxpetrusenkoagent <max.petrusenko.agent@gmail.com>

* C9: guard destructive gstack-upgrade and spec fences against unset or wrong paths

Fresh-shell hosts (and Claude Code, which keeps cwd but not shell variables)
ran cd "$INSTALL_DIR" with an empty variable, so git checkout/stash/reset
targeted the user's project. Step 2 now prints an absolute path; every
destructive fence starts with cd -- "${VAR:?...}" || exit 1 and checks it is
gstack's own checkout before any git command. /spec's worktree and spawn
fences get the same guard.

* F4: keep every paid design variant across regenerate rounds

$D variants now reserves a collision-safe round-<N>/ directory per run
(atomic mkdir) and writes a manifest.json of what each round saved. The
paid image request and the local write retry separately: a write failure
retries the write (temp + rename) and, if the path stays unwritable,
keeps the bytes in the temp dir instead of buying the image again.
Responsive variants land in their round directory too.

Readers updated: design-shotgun reserves a round dir and a private temp
dir for its parallel agents and records approved_path/round in
approved.json; design-html resolves approved_path (legacy letters still
work) and finds round-dir variants; design-consultation checks the
printed paths; the gallery shows round-dir variants. Variants that were
already overwritten before this change cannot be recovered.

Migrates the consultation contract test that pinned the flat path.

Co-authored-by: Matt Van Horn <mvanhorn@gmail.com>

* A2: stage dot-leading slugs gbrain can collect; network errors are db-unreachable

A page slug segment starting with a dot (a .claude project) staged a file
gbrain's import walker prunes, so the batch was refused on every run.
Leading dots become "dot-" per segment, and slugs recorded in state under
the old name map through the same function so no page is duplicated.

A DNS or connection failure (ENOTFOUND, EAI_AGAIN, ECONNREFUSED, ...) no
longer classifies as broken-db, which routed users to move a working
config aside. The new db-unreachable status carries the reason
"database host unreachable (<code> <host>); your gbrain config is
unchanged. Fix: check network or VPN, then re-run /sync-gbrain.", skips
local sync stages with that reason, and counts as usable for
gstack-gbrain-detect --is-ok like timeout.

Co-authored-by: Infiniteyieldai <infiniteyield.ai@gmail.com>

* D2: one address classifier for navigation literals, DNS answers, redirects and page-driven navigations (#2811)

classifyAddress() in url-validation.ts blocks 169.254.0.0/16 (metadata and
container credential endpoints), 100.100.100.200, fe80::/10 and fc00::/7,
including IPv4-mapped, IPv4-compatible and NAT64 spellings and decimal,
octal and hex IPv4. validateNavigationUrl, the A/AAAA answer check and
session-persist's cookie-domain guard all use it. BrowserManager now checks
every navigation request (redirect hops, link clicks, scripted navigations):
a blocked target resets the tab to about:blank and the write command fails
with the reason. Connection-time DNS rebinding remains out of scope.

Co-authored-by: Gabriel Rondon <grondon@gmail.com>

* C4: external hosts point at carved sections relative to the installed skill

Publishes the pointer form setup matches: on every non-Claude host a carved
section is `sections/<file>` relative to the installed gstack-<skill> SKILL.md
directory (QA's existing form), never $GSTACK_ROOT/<skill>/sections/, which
does not exist in external runtime roots. No render changes yet: only QA is
carved on external hosts today.

* INV-1: gate outcome contract for outside reviews

classifyOutsideReview() returns separate execution, findings and verdict
fields from text, stderr and exit status; reason codes, anchors and fix
actions live in lib/gate-outcomes.ts. validateOutsideReview() stays as the
text-only wrapper and the two-argument CLI keeps exit 0/1/2 for importers
and installed skills that predate a re-render. The --verdict form (implied
by --stderr/--exit) prints VERDICT/FINDINGS/REASON and exits 0/3/4/1; the
generated outside-voice caller moves to it and branches on each status
(unverified prints OUTSIDE_STATUS: unverified, never completed).

Adds docs/troubleshooting.md with one anchored section per reason code, the
anchor test, and the gate-tail lint (query scripts may not swallow failures,
gate calls may not end in || true, other best-effort tails say why).

* G1: quote the base placeholder in document-release title sync

The title-sync block is checked with bash -n; an unquoted <base> parses
as a redirection. Migrates the test that pinned the old root VERSION
read to the shared classifier call.

* G3: give every logging-bin mktemp a ${TMPDIR:-/tmp} template

Bare mktemp, mktemp -t and literal /tmp templates in the learnings,
question and preference logs (plus jsonl-merge, distill, the two
dashboards, /ship's PR body and /document-release's run dir) now use
"${TMPDIR:-/tmp}/<name>.XXXXXX", the form the INV-3 lint accepts. When
the temp file cannot be created, the learnings, question and preference
logs now say the entry was not recorded and how to fix TMPDIR instead of
exiting with only mktemp's own error. Three tests that pinned the bare
PR_BODY_FILE=$(mktemp) and one that pinned the /tmp run dir migrate.

GNU and BSD mktemp already honor TMPDIR without a template, so the
macOS-sandbox drop in #2952 is unverified here; the template makes the
temp location explicit on every mktemp.

Co-authored-by: Davon Johnson <d.johnson@dayofshow.net>

* B1b: structured outside-review gate fails on P0 as well as P1

validateOutsideReview() derived its structured pass/fail from a [P1] match,
so a review reporting only [P0] findings passed. The wrapper now reads the
classifier's findings verdict (P0 or P1), and the /review and /ship
structured-gate prose requests [P0]-[P3] tags and fails on P0/P1; untagged
output (OUTSIDE_STATUS: unverified) is missing coverage. The ship clarity
pin moves from 'structured P1' to 'structured P0/P1' with the behavior.

* E1: freeze normalizes boundary and target the same way on Windows; hooks spawn through cmd.exe (#2876, #2354)

gstack_hook_normalize_path (careful/bin/hook-extract.sh) maps C:\..., c:/...,
UNC \\server\share (leading // kept) and /cygdrive/c to one form; check-freeze
runs both the saved boundary and file_path through it before the absolute
test, after symlink resolution, and compares case-insensitively on Windows
bash. freeze, guard and careful register hooks as
bash -c "exec bash \"$HOME/...\"" so cmd.exe, which never expands $HOME,
no longer turns the hook into a silent exit 127.

Co-authored-by: Kevin Grasso <kevin@biblingo.com>
Co-authored-by: Xuan-Ce Wang <261591073+xwang4-svg@users.noreply.github.com>

* G4: keep CLI-to-daemon loopback calls off HTTP_PROXY (#494)

The CLI appends 127.0.0.1, localhost and ::1 to the user's NO_PROXY (and
no_proxy), keeping existing entries, before its first fetch. Verified on
Bun 1.4.0: fetch honors NO_PROXY when it is set before the first request
and ignores later changes, so it is set at the top of main().

* F1: bind the plan audit to this branch's plan, never the newest file

Plan File Discovery now prefers an explicit binding (the plan-mode file
or /autoplan ACTIVE_PLAN from the conversation, then a "Plan: <path>"
line in the PR body), then lists candidates: repo-committed
docs/designs/ files this branch changed or that name it, and personal
plan files that name the branch. Candidates are offered, never picked
silently. The repo-name match and the newest-file-of-the-day fallback,
which audited PRs against unrelated plans, are gone. With nothing bound
or chosen it prints the exact line 'Plan completion audit: not run (...).
Fix: add "Plan: <path>" to the PR body, or run /autoplan.'

/ship's parent now binds the plan before dispatching the audit
subagent ({{PLAN_COMPLETION_GATE_SHIP:discovery}}), so the child never
searches. Migrates three tests that pinned the old markers and notice.

Co-authored-by: loulanyue <260355617@qq.com>

* G5: browse type --selector <sel> <text> (#2936)

--selector focuses the element (sel or @ref) and types into it. The bare
form still types its text literally into the focused element; text that
starts with -- goes after a -- separator. When the first word looks like a
CSS selector, the result adds a hint to use --selector without echoing the
typed text, and never refuses based on page contents. Help and command
usage updated.

Co-authored-by: Thomas Reuser <thomasreuser@gmail.com>

* F2: design-doc discovery reads docs/designs, never a root DESIGN.md

A root DESIGN.md is the design system /design-consultation writes, so
preferring it unconditionally reviewed plans against a token file while
printing "Design doc found" and never looked at docs/designs/ feature
docs. Discovery now considers only docs/designs/*.md as the repo-local
design doc (still freshness-compared with the private ~/.gstack copy).
The CEO finding fixture seeds its supplied design as a docs/designs doc
and its test follows.

Co-authored-by: Bit0ps <alex.dreamscaper@gmail.com>

* C4: rename the external carve test (typecheck:test union-order artifact)

tsc prints a union's members in type-creation order; a test file sorting
before ceo-mode-option.test.ts reordered one baseline diagnostic's text.

* C1: every env-var host fence resolves its own gstack root

Codex and the other env-var hosts run each block in a fresh shell, so
GSTACK_ROOT/BIN, B and D set by the preamble were empty in later blocks
(/bin/gstack-slug, B=/browse). scripts/resolvers/runtime-root.ts now owns
root resolution: a valid exported GSTACK_ROOT (bin/ and lib/), else the
per-install literal root (no git call), else repo-local, else the global root
(CODEX_HOME on Codex); no root prints the setup fix line and exits. One
post-render pass inserts it (<=400 bytes) into every fence that uses these
variables without assigning them; B/D come from the same helper as BROWSE
and DESIGN SETUP. Claude output is byte-identical.

Migrated pins of the old preamble lines (gen-skill-docs.test.ts) and a
fixture whose exported GSTACK_ROOT lacked lib/ (skill-positional-literals).

* E8: headless browse honors GSTACK_CHROMIUM_PATH; extensions load in new headless mode (#2771, #1968, #2281)

The headless launch passes GSTACK_CHROMIUM_PATH as executablePath, scopes
the XProtect self-heal out for that bundle, and names the path in a launch
failure with the fix. BROWSE_EXTENSIONS_DIR now launches a persistent
context under the project state dir with --headless=new, so the extension
runs and no window appears (the off-screen window was visible on macOS and
the extension never ran in an isolated newContext). The GPU source guard
test moves from the removed useHeadless flag to launch() vs launchHeaded().

Co-authored-by: oli548 <312288720+oli548@users.noreply.github.com>
Co-authored-by: Slava <slava.istomin@tuta.io>
Co-authored-by: ryanlaiwy <129729476+ryanlaiwy@users.noreply.github.com>
Co-authored-by: 李翊楠 <yinanli1917@gmail.com>

* C2: link design/dist and make-pdf/dist into every host runtime root and the agents sidecar

Codex design and make-pdf skills fall back to $GSTACK_DESIGN and
$GSTACK_MAKE_PDF under the runtime root, but setup linked only browse/dist,
so both preflights reported NOT_AVAILABLE on a fresh install. One helper
links dist/ only (make-pdf/ ships a Claude SKILL.md) into the Codex,
Factory, OpenCode, Cursor, Copilot and Kiro roots, the .agents sidecar and
the Cursor sidecar.

Co-authored-by: Mammad M. <mammad@digit.az>

* C3: install router and nested SKILL.md files as real copies; back up hand edits; --status checks

Codex skips a symlinked SKILL.md file, so the gstack router linked into
~/.codex/skills/gstack was invisible. Every host runtime root (Codex,
Factory, OpenCode, Cursor, Copilot, Kiro) and Kiro's per-skill installs
now get real copies, rewritten on every run (the auto-update path runs
setup --refresh-registered, so it refreshes them too). setup records each
copy's hash in <state root>/skill-copies.tsv; a copy that no longer matches
is saved to a uniquely named backup under <state root>/backups/skill-copies/
before _activate_runtime_root replaces the tree, and a failed backup keeps
the old tree. setup prints what it refreshed or removed.

./setup --status now prints, per registered install, whether the router is a
real file and whether every section pointer resolves, with the fix command.

Test migration: setup-codex-model pinned the Kiro router/upgrade links as
_link_or_copy; C3 deliberately changes them to copies.

* INV-3: install-level host conformance checks (no symlinked SKILL.md, dist present, section pointers resolve)

For codex, kiro, factory, opencode, cursor and copilot, the real-setup
conformance kit now fails when an installed SKILL.md is a symlink, when
design/dist or make-pdf/dist is missing from the runtime root, or when a
'Read `.../sections/<f>.md`' pointer in an installed SKILL.md does not
resolve (bare pointers in carved skills, relative-to-installed-skill
pointers, and $GSTACK_ROOT/~/absolute/../ pointers everywhere), and
./setup --status must report 'all resolve'. No new setup runs.

Expected red until the generator lane lands: design-html's install-offer
pointer and plan-eng-review's review-sections pointer name
$GSTACK_ROOT/<skill>/sections/... on every external host.

* B11: auto-update tracks pull, setup and migrations; announces only on success; retries with backoff

gstack-session-update wrote the 'just upgraded' marker after SETUP_FAILED or
SETUP_SKIPPED bun_missing, and re-ran setup only when HEAD moved, so a failed
install was announced as an upgrade and never retried. Stages are now
persisted in <state root>/session-update-pending; the marker is written only
when every stage succeeded; a pending setup or migrations stage is retried
even with HEAD unchanged after the update-check interval, then 6h, then 24h;
and each session start prints one line naming the stage, the reason and the
repair command while it is pending. Best-effort tails carry a same-line
reason.

* D1: gstack-config key browse_extension_id for forks and self-built extensions

The browse daemon trusts one Chrome extension ID on /extension-token and the
terminal-agent /ws. The override now lives only in gstack-config (never an
env var a project .env could set): empty by default (gstack's published
extension), a 32-letter a-p Chrome ID when set, "" clears it, and anything
else is rejected with the stored value kept. The browse lane reads it.

gstack-config-defaults: browse/src counts as a reader directory; the key is
listed prose-only until the browse lane's reader lands (the stale-entry check
then asks for the entry's removal).

* G2: key the sticky slug cache on the git common dir

A linked worktree used to resolve its slug fresh from the remote while
the main checkout kept its sticky pre-remote identity, so learnings,
checkpoints and timelines split into two buckets. gstack-slug and its
TS twin in lib/bin-context.ts now key the cache on the git common dir
(read from .git files, no git spawn, so cache hits stay git-free) and
read entries in one deterministic order: the repository entry, then the
main checkout's pre-upgrade entry, then this directory's own. Both the
repository and per-path entries are written.

When a worktree's own old entry named a different bucket that still
holds data, that slug is recorded in projects/<slug>/.former-slugs and
reported by --get FORMER_SLUGS. New --adopt-legacy --from <slug> merges
it: JSONL logs append missing lines with de-duplication, missing files
copy, differing files are listed as conflicts and never overwritten,
the source bucket is kept, and it prints migrated/pending/conflicting
counts; reruns are idempotent. --adopt-legacy --dismiss <slug> drops
the reminder.

Co-authored-by: loulanyue <260355617@qq.com>

* C5: OpenCode /gstack-* commands load the skill by its frontmatter name

OpenCode's skill tool knows gstack-review as `review` (its frontmatter
name), and OpenCode's builtin /review shadows that name as a command. The
managed /gstack-review command told the agent to load `gstack-review`,
a name the skill tool does not list. Every managed command now names the
frontmatter name. OpenCode's AskUserQuestion/ExitPlanMode mapping (#2759)
already shipped in v1.91.16.0.

Test migration: the #2629 commands test pinned the directory name.

Co-authored-by: Lockyer <135391289+Lockyer228@users.noreply.github.com>

* E4: Windows node-server bundle keeps sharp and socks external; CLI resolves its server script lazily (#2260, #2439)

build-node-server.sh passes --external sharp and --external socks (Bun on
Windows refuses to inline them; on Linux they were silently inlined). The
CLI no longer resolves server.ts or server-node.mjs at module load:
resolveServerLaunch() runs when a server starts, so a Windows minimal
runtime with only server-node.mjs works and a missing script is reported
only when one is needed.

Co-authored-by: Spooks444 <193448029+Spooks444@users.noreply.github.com>
Co-authored-by: punksterlabs <77217235+punksterlabs@users.noreply.github.com>

* B1: Codex reviews whose sandbox could not start are unavailable, not a pass

In containers without unprivileged user namespaces every Codex command
fails, yet the review exits 0 and concludes 'no findings' (captured in
test/fixtures/codex-sandbox/). The validator now takes execution evidence:
'codex exec --json' command events and the 'codex review' stderr transcript
(a command that succeeded proves execution); sandbox failure lines on
stderr or in failed command output return unavailable(sandbox_unavailable);
exact 'could not run commands / read the diff' phrases are the last
fallback. Review text that merely discusses bwrap or namespaces still passes.

A free 'codex sandbox ... true' preflight (Linux, 10 s) runs before the paid
model probe and every automatic outside review; CODEX_MODE gains
sandbox_unavailable, and an inconclusive model probe reports unverified
instead of ready (exit code kept for stale callers). Every Codex site
(outside-voice resolver, /codex review, challenge, consult) takes its sandbox
from _GSTACK_CODEX_SANDBOX and pipes its result through the validator; a
static test parses rendered command positions for both. GSTACK_CODEX_NO_SANDBOX=1
(exactly 1, shell env only) switches to danger-full-access with a warning on
every use. Sandbox pins in existing tests move from the literal read-only to
the selected-sandbox variable; captured autoplan probes are judged against
the probe block they executed.

* C6: gstack-relink discovers skills structurally, so /browse survives a skill_prefix toggle

relink skipped a hardcoded list of support-directory names that included
browse, a real skill, so toggling skill_prefix removed /browse. A top-level
directory is now a skill exactly when it carries a SKILL.md.

Co-authored-by: Jonathan Zhang <topcoder1@Mac-Studio.local>

* C4: carve ship and plan-ceo-review on every host; enforce the 160 KB byte gate

The generated ship skill was 202-241 KB on all 10 non-Claude hosts (and
Factory plan-ceo-review 160,039 bytes), over the 160,000-byte ceiling,
because section carving ran only for Claude. Both skills now carve on every
host, pointing at sections relative to the installed skill directory (literal
$GSTACK_ROOT/<skill>/sections refs are rewritten the same way). The ceiling
is measured in UTF-8 bytes and fails generation in repo mode; under
--install-root it warns so setup never leaves a user without skills.

qa-lazy-sections.test.ts pinned ship as inline-on-external-hosts; migrated to
the carved policy and kept the inline check on review (Claude-only carve).

* B5: learnings and timeline reads fail loudly when bun is missing

gstack-learnings-search and gstack-timeline-read ended in
'2>/dev/null || exit 0', so a missing bun or a crashed embedded script
printed nothing and exited 0, identical to 'nothing recorded'. Both now
exit 127 with '<script>: bun not found on PATH, so ... could not be
read. Fix: install Bun (https://bun.sh), then re-run ./setup.' and let
an embedded-script failure exit non-zero with its stderr. A successful
run with no matches still exits 0 with empty output. The generated
callers that print 'LEARNINGS: unavailable (...)' belong to the
generator lane.

Co-authored-by: loulanyue <260355617@qq.com>

* B2: a retired-model 404 reports MODEL_UNUSABLE, not CODEX_MODE: ready

The model probe matched only 400 / 'is not supported', so a retired model's
404 ('does not exist or you do not have access to it') and a custom
provider's bare 404 fell through to the inconclusive branch and reported
ready. Both now classify as MODEL_UNUSABLE with a hint naming the two causes
(retired model, or a wrong base_url) and log codex_model_retired; a
'requires a newer version of Codex' 400 points at upgrading the CLI and logs
codex_cli_outdated. Ported from #2843 onto the current probe.

Co-authored-by: Marek Cermak <marek.cermak@strv.com>

* B6: rank learnings by matched query tokens and disclose truncation

A more specific query used to drop the exact match: the token-OR filter
recalled every entry sharing one token, the sort used confidence alone,
and the default --limit cut silently. Entries now rank by how many
distinct query tokens they match, then confidence, then recency, and a
query that matched more than fit says '-- N more matched, raise --limit
to see them'. The hit count lives in a local map so a field stored on
disk can never become a sort key, and the type grouping uses a
null-prototype map so a row typed 'constructor' or '__proto__' cannot
crash the run. Ranking code ported from #2796; regression vectors
adapted from #2799 (its stemmer is not needed).

Co-authored-by: loulanyue <260355617@qq.com>
Co-authored-by: y$un_ <forrest.sun527@gmail.com>

* C7: required team mode also blocks Copilot CLI's lowercase skill tool

Copilot CLI applies Claude-format matchers by tool name; its skill tool is
`skill`, which no Claude tool name maps to, so the 'Skill' matcher never
fired and Copilot ran protected skills without gstack. The hook entry now
matches 'Skill|skill', an entry an older team-init wrote is upgraded in
place, and the deny is emitted in both decision formats (Copilot reads the
top-level permissionDecision, Claude Code reads hookSpecificOutput) with
exit 0 so both parse it.

Test migration: the settings test pinned matcher 'Skill'.

Co-authored-by: neallee <neallee@gmail.com>

* B3: Codex auth probe accepts custom providers' env_key credentials

The auth probe only knew CODEX_API_KEY, OPENAI_API_KEY and auth.json, so a
working self-hosted or OpenAI-compatible provider configured with
[model_providers.<id>] env_key = "X" reported AUTH_FAILED and /codex
stopped. The probe now reads env_key from model_providers tables only
(comments ignored, the name must be a shell identifier before it is
dereferenced) and accepts a set variable; when none is set it names the
missing key on stderr. Ported from #2192 with the table scoping added.

Co-authored-by: hardy <932821449@qq.com>

* E8: keep the extensions profile under the state dir at a path lock cleanup accepts

cleanSingletonLocks only cleans directories named chromium-profile, so the
BROWSE_EXTENSIONS_DIR profile moves to <state>/extensions/chromium-profile.

* B10: plan-tune never reports CALIBRATED with zero signal events

Stats printed CALIBRATED: true from logged-answer counts alone, while
every answer could miss SIGNAL_MAP and leave each dimension at its 0.5
seed (#2623). --derive now records inferred.signal_events, the answers
that actually moved a dimension; calibration requires at least one, and
the summary prints 'not calibrated: no recorded signals' verbatim when
there are none (or says the count is unknown for a profile derived
before this change). The psychographic redesign stays out of scope.

* A1: verify gbrain landing before stamping transcripts, plus --reconcile

gbrain import exits 0 while skipping pages (returned per-file failures,
malformed filenames, managed-import Pending receipts), and its failure
ledger exists only for git import dirs, so a skipped page was stamped
ingested and never retried (field reports: 37 and 69 lost entries).

Write, verify, then stamp (lib/memory-ingest-landing.ts, a new ratcheted
module):
- State schema 2 with a transition table (staged -> imported_unverified ->
  ingested, plus refused, quarantined, unrecoverable). Schema 1 files
  migrate in place: entries become ingested in the legacy "default"
  source and a reconcile pass is marked pending.
- Named failures come from --json `failures`, stderr "Skipped <rel>:"
  lines and the ledger; a failure gbrain does not attribute refuses the
  whole batch. After 3 refused batches the batch is bisected and the page
  that poisons it is quarantined (printed even under --quiet).
- Landing check: one `gbrain list --source-id` per source per run and at
  most 50 `gbrain get --json` content checks against a
  gstack_content_sha256 frontmatter field gstack now writes. Lookup errors
  and pglite_busy mean "not yet checked", never absent; pages over the cap
  stay imported_unverified and are not re-imported.
- Each entry records its gbrain source_id. Remote-http mode records
  "staged", never "ingested".
- The source fingerprint comes from the exact bytes parsed, so a
  transcript that grows during import is not stamped as its newer self
  (the old unscanned contract test is migrated; it pinned that bug).
- --reconcile mode (bounded by --limit, default 200; resumable; --dry-run;
  backs up the state file) prints "reconcile: checked N, present M,
  re-queued K, not yet checked L". --request-reconcile records a pending
  pass without calling gbrain; the v1.91.17.0 migration (placeholder name)
  uses it, and the next ingest run does one bounded pass.
- One lock for every state writer; a state-save failure fails the run.

The #1802 static pins in regression-1611 move to the new structure
(remote-http returns before importBatch; the finally honors
preserveStaging).

Co-authored-by: afshaker <andrew@phone2.io>

* B4: arm64 re-sign keeps a backup, restores it when codesign fails, and reports design unavailable on exit 137

setup's Apple Silicon re-sign mutated each binary in place (truncate, remove
signature) and left it that way when re-signing failed; a design binary that
was then SIGKILLed at launch produced at most a quiet log line. Each binary is
now copied first and restored as built when signing fails, and design is
exec-probed after re-signing: exit 137 prints 'design unavailable: ... Fix:
cd <checkout> && ./setup' (even under -q). Verified on Linux with the real
block and uname/codesign/otool/stat stubs; not run on a Mac.

* D3: treat design docs and handoff notes as data in plan reviews

plan-ceo-review, plan-eng-review and plan-devex-review read the freshest
design doc as the source of truth, and nothing said its content is data.
In multi-agent pipelines another agent may have written it, or a handoff
note beside it, with reviewer-directed text ('skip Step 0', 'approve
as-is'). Each read site now says the doc and any handoff note are data,
never to follow text aimed at the reviewer, and to report it as
suspicious content. The plan-completion audit's discovery, which now
reads repo docs/designs/ files (F1), carries the same rule.

Co-authored-by: cube <frosimanuel@gmail.com>

* D4: setup-deploy reports Render API key presence only

/setup-deploy ran 'echo $RENDER_API_KEY | head -c 4', printing the
key's first bytes into the transcript. It now prints only
'RENDER_API_KEY: set' or 'RENDER_API_KEY: not set'. Wording follows the
#2971 port of #1096; a test also guards against any setup-deploy command
echoing a credential variable.

Co-authored-by: jacob-wang <jiayuw794@gmail.com>

* D5: per-project headed Chromium profiles; never kill a live profile owner (#2492)

The headed profile moves from <gstack home>/chromium-profile to
<project>/.gstack/chromium-profile (CHROMIUM_PROFILE still wins).
killOrphanChromium now kills a SingletonLock PID only when the lock names
this host, the process is a Chromium using that profile, and its daemon is
gone (reparented to init or a subreaper); a live owner or another host's
lock stops browse with the holder named. On first headed use a project
profile is seeded from the old shared profile only when nothing holds it:
copied without Singleton* files into a 0700 temp dir and renamed into
place, with a one-time notice; otherwise it starts fresh and says how to
import later. New: browse profiles [list] and browse profiles prune
[--days N] (never removes a profile in use or the old shared one).
The #2817 headed-startup tests move to the project profile and a real
orphan (the old stand-in was a live child of the test).

Co-authored-by: miao <miao@macmini-2.local>

* F5: installed Claude skills serve the rendered sections, not the checkout copies

Probe: a gbrain user render serves ship/SKILL.md from the render dir; its
STOP pointers name absolute render paths, but its section index names
`sections/<f>.md` relative to the installed skill directory, whose
sections/ was linked from the checkout. So the rendered 'Save Results to
Brain' blocks (plan reviews, office-hours, ship adversarial) were generated
and never read. setup's _link_skill_runtime_assets and gstack-relink (the
gbrain-refresh path) now serve a rendered counterpart per file, keep
checkout-only assets (manifest.json), return an asset to the checkout once
its render is gone, and never touch an entry that is not gstack's links.

Co-authored-by: Jonah Berg <jonah.berg.g@gmail.com>

* F1: ratchet /ship's parity union-size cap for this lane's content

G1's NO_VERSION arms, F1's parent-side plan binding and D3's data line
add 2,126 bytes to /ship's skeleton-plus-sections union, taking it from
1.4022x to 1.4135x of the v1.64.1.0 baseline (cap was 1.405). The cap
moves to 1.414 with the measurement recorded, as earlier growth did; no
other invariant changes.

* E5: feed every Codex prompt on stdin instead of argv

Prompts went to Codex as one argv string ('codex exec "$(cat file)"'), which
fails over 32 KB on Windows (and over 128 KB on Linux, E2BIG) and mangles
quotes. Every codex exec site (outside-voice resolver, /codex review custom
instructions, challenge, consult new and resume) now runs 'codex exec -'
with the prepared prompt file on stdin; challenge and consult write the
prompt with a quoted heredoc so it is never shell-parsed. The bash-native
timeout watchdog (stock macOS) started the command in the background, which
gives it /dev/null as stdin; it now passes the caller's stdin through.

The 'byte for byte' dispatch test drops its old argv trailing-LF exception,
the consultation and autoplan fixtures follow the stdin form, and the static
site test requires stdin at every rendered codex exec.

* G6: prettyscreenshot --hide keeps a trailing image path as the output path (#1419)

--hide collected every following non-flag argument as a selector, so the
output path was hidden instead of written to. A trailing argument that looks
like a path or ends in .png/.jpg/.jpeg/.webp is now the output path.

Co-authored-by: Jayesh Betala <jayesh.betala7@gmail.com>

* INV-3: render-level host conformance and generated-bash lint on every host

One render per host checks every fence of every SKILL.md and section file:
bash -n with angle-bracket placeholders normalized; the env-var host prelude
and its B/D consumers run under env -i and set -u with stub binaries (no
empty value, no /bin/, /browse, /design or /gstack- path); and a quote-aware
lint (test/helpers/generated-bash-lint.ts) fails on a ~/ word inside double
quotes, mktemp without a TMPDIR-respecting template, and cd/rm -r/mv/git -C
on a variable the fence never assigned unless written ${VAR:?...} (cd must
also handle failure). Negative controls plant each failure.

Templated the bare mktemp calls in generator-owned resolvers and the upgrade
fence; migrated the two tests that pinned the bare form.

* G6: analytics averages quoted duration_s values (#1728)

gstack-skill-end writes duration_s as a quoted string, and the per-skill
average stripped everything from the leading quote, so every average
read 0s. The awk now drops a leading quote before extracting digits.

Co-authored-by: Ryan Alberts <ryan.a.alberts@gmail.com>

* G6: gstack-ios-qa-daemon --help prints usage instead of starting the daemon (#1932)

Co-authored-by: maxpetrusenkoagent <max.petrusenko.agent@gmail.com>

* G1: tighten /ship's NO_VERSION wording to fit the union-size cap

Same behavior in fewer bytes: the NO_VERSION arm, the broken-source
exit, the unprefixed-title rule, the Step 20 null and the CHANGELOG
skip. The cap ratchet commit measured this wording.

* G6: rejected taste preferences gain confidence (#1777)

bumpPref computed every entry's confidence from approved_count, so a
rejected entry, which never gains approvals, stayed at 0: show ranked
rejections by insertion order and the taste-drift warning could not
fire from real use. Confidence now uses the entry's own bucket count.
Also salvaged by Garry's #2971.

Co-authored-by: Jayesh Betala <jayesh.betala7@gmail.com>

* E2: Windows /cso build disables only C5105, and a failed MSVC compile is not reported as a missing toolchain

The Windows SDK's winbase.h raises C5105, which /W4 /WX promotes to error
C2220, so every MSVC build of the native /cso helper failed, and setup
mapped every probe failure to 'install Visual Studio 2022 Build Tools'.
Both compile lines add /wd5105 (only that diagnostic), and setup keeps the
probe's output: a probe that found MSVC but failed to compile reports
windows-msvc-compile with the compiler's first error. Not run on Windows:
the mapping test stubs powershell.exe; the ps1 assertion runs everywhere.

Co-authored-by: AlinValentin7 <AlinValentin7@users.noreply.github.com>

* E6: gbrain-refresh hands the detection file to Python on stdin

Under Git Bash, a native Windows Python first on PATH cannot open an MSYS
/c/... path, so gbrain-refresh always summarized the detection as
'local-status: unknown' and brain-aware blocks were suppressed. bash now
opens the file and Python reads stdin; the grep fallback without Python is
unchanged. Verified on Linux with a stub Python that refuses path opens; not
run on Windows.

Co-authored-by: maxpetrusenkoagent <max.petrusenko.agent@gmail.com>

* G6: context-save computes session duration on Linux (#2704)

The duration step parsed 'ps -o lstart=' with BSD-only 'date -jf', so on
Linux session_duration_s was always unknown. It now falls back to GNU
'date -d', and never parses an empty start (GNU reads that as midnight).
Ported onto the current block instead of #2704's ~/.gstack/sessions
mtime, which bypassed the state root.

Co-authored-by: Evgenii Lopatin <e75533@gmail.com>

* Q2: one-time notice naming the Codex provider and account for outside reviews

Outside reviews are on by default and use whatever Codex login exists
(#965). The first automatic Codex review on a machine now prints one
non-blocking notice: the provider (config.toml model_provider, else openai),
where the credential comes from (CODEX_API_KEY, OPENAI_API_KEY, the ChatGPT
login or the key saved by codex login; never the value), that reviews stay
on, and how to turn them off (gstack-config set codex_reviews disabled). A
marker in the gstack state root keeps it to once per machine. Tests that run
the generated command now use private state roots. Also shortens the
no-sandbox provenance line.

* Q1: validate browser output paths the way the kernel resolves them (#2971 salvage)

validateOutputPath walks the destination one component at a time, resolving
each existing component before the next, so link/../x, a dangling symlink
and a dangling symlinked parent can no longer route a write outside the
safe directories, while a new multi-level directory inside them is allowed.
scrape validates its manifest and every downloaded file, not only --dir.
Ported from PR #2971 onto current code.

* G6: retro test census counts non-JS suites, skips generated output

The census recognized only JS/TS-style names, so pytest and minitest
(test_*.py|rb), XCTest (Tests/ dirs, FooTests.swift), Terraform
(*.tftest.hcl) and Bats (*.bats) suites counted as zero, and a committed
build directory counted as authored code (and its Test/ subdirs as test
LOC). is_test now knows those conventions and never treats prose as a
test, generated output is skipped in the numstat pass, TEST_FILES_CHANGED
uses is_test, and TEST_FILES_TOTAL uses the same filename conventions
minus generated paths. Merges #2812, #2809 and #2037's patterns (#2037's
retro template edits target a block the metrics bin replaced).

Co-authored-by: Jino <dgfrty00@gmail.com>
Co-authored-by: snig-17 <santosh.m.tiwari@gmail.com>
Co-authored-by: Sholto McNeilage <sholto@nodenarrative.com.au>

* Q3: setup stops auto-installing the AskUserQuestion preference hook in Conductor and removes one it added

The PreToolUse question-preference hook breaks Conductor's native
AskUserQuestion round-trip even when it only defers (#2207), and setup
auto-installed it on every Conductor workspace setup. Now a Conductor setup
without an explicit opt-in never installs it and removes an existing one
(the question-log and AUQ-error hooks stay), printing how to keep it
(gstack-config set plan_tune_hooks yes). An explicit opt-in still installs
it. gstack-settings-hook remove-source gains --event to scope the removal.

Test migration: setup-plan-tune-hooks-noninteractive pinned the retired
Conductor auto-opt-in.

Co-authored-by: Phil Hie <philhie@outlook.com>

* E5: watchdog stdin test feeds the wrapper through a redirect

Callers run '_gstack_codex_timeout_wrapper ... codex exec - < file'. Bash keeps
stdin for a backgrounded command inside a pipeline but not behind a
redirect, so the pipe form passed on the old watchdog; the redirect form
reproduces the lost prompt.

* F4: type the variant-round fetch stub like the existing stubs

The test-typecheck ratchet flagged the zero-argument stub cast to
typeof fetch; it now takes the fetch arguments like
variants-retry-after's stub. Test behavior unchanged.

* A4: import transcripts into per-repository, non-federated gbrain sources

`gbrain import` ran without --source-id, so transcripts from every project
landed in the shared (often federated) default source.

- Each transcript partition imports with --source-id into its originating
  repository's own source (gstack-transcripts-<repo>, built with
  constrainSourceId, now exported from lib/gbrain-sources.ts). The source
  is registered machine-local and --no-federated before its first import,
  and the registration is cached in state. Partitions import one after
  another (PGLite is a single writer); a failing source no longer blocks
  the others, except a timeout, whose checkpoint must survive.
- If gbrain cannot register the source, that partition stays local and
  unstamped, and the run says why (even under --quiet).
- --include-unattributed sends repo-less transcripts only to the
  machine-local gstack-transcripts-unattributed source, keeps them on the
  machine when the brain is remote (Postgres, Supabase or remote-HTTP),
  and never writes them to the publishable ~/.gstack/transcripts staging.
- A page's recorded source is sticky: pages stamped before this release
  ("default") keep importing there, so no source gains a duplicate.
- The staging dir name carries -src-<id> so a resumed import keeps its
  source.

Test fakes that recorded only the last import now record every import of
one run, and answer `gbrain sources`; remote-http scan tests use an
attributed transcript, since unattributed ones no longer stage there.

Co-authored-by: Sinabina <sinabina@Sinabinas-MacBook-Pro-4.local>

* F3: load the taste profile, and report a failed slug lookup

The taste-profile probe double-quoted ~/.claude/.../gstack-slug, so the tilde
never expanded and /design-consultation and /design-shotgun always printed
NO_TASTE_PROFILE. Use quoteSafePath(); stop hiding gstack-slug's stderr and
print TASTE_PROFILE_UNAVAILABLE with the fix when the slug cannot be resolved.

* B4: DESIGN_READY only when the design binary actually starts

DESIGN SETUP (and office-hours' visual exploration) printed DESIGN_READY for
any executable binary, so one SIGKILLed at launch by an invalid macOS code
signature still passed. Launch it under the portable 10-second deadline
(gtimeout, timeout, or perl alarm); otherwise print DESIGN_NOT_AVAILABLE with
the exit code, 'timed out after 10s', or on 137 the code-signature hint and
'Fix: cd <checkout> && ./setup'. A success is cached by inode and mtime under
the state root so Gatekeeper's first-launch scan is paid once.

The probe launches the binary with no arguments (usage, exit 0): the design
CLI has no --version command today.

* C2: name the runtime root every way a generated preflight may read it in the dist test

The generator lane's C1 resolves D from $GSTACK_ROOT instead of
$GSTACK_DESIGN, so the test now exports GSTACK_ROOT as well; it still fails
on main (no dist in the roots) and passes with and without the C1 change.

* A5: brain-sync stage fails loud when the artifacts source indexed zero pages

The stage reported "curated artifacts pushed" whenever gstack-brain-sync
exited 0, but a git push is not gbrain indexing. After a successful push
the stage now reads the maintained artifacts source's page count
(GSTACK_BRAIN_SOURCE_ID, else the source whose path is the artifacts
worktree or state root): zero pages is ERR with the fix command; a
missing source or an unavailable count says so instead of claiming
indexing.

Co-authored-by: Jimmy Zeisweiss <4261258+jzeisweiss@users.noreply.github.com>

* B1: state the effective read-only sandbox in /codex review prose

The codex parity invariant requires the skill to state sandbox_mode="read-only";
the command now takes it from _GSTACK_CODEX_SANDBOX, so the prose names the
effective default explicitly.

* A6: report deleted-worktree gbrain sources; prune only with proof, on request

A deleted Conductor worktree leaves its gstack-code-<hash> source behind
and gbrain's autopilot fails on it forever. Local absence is not proof a
source is dead (machines sharing a federated brain register their own
paths, and its pages may be the only copy of uncommitted work), so gstack
never removes one automatically.

- Each sync counts consecutive misses for gstack code sources whose path
  is missing, prints "path unavailable" once per source with the review
  command, and records which repository each synced source belongs to.
- New gstack-gbrain-sync --prune-gone-worktrees (with --dry-run, whose
  plan it always prints first) removes a source only when its path was
  missing on two consecutive syncs, its parent is readable, recomputing
  deriveCodeSourceId() for that path on this host yields its id, and the
  repository's git common dir still exists and no longer lists the
  worktree. It re-checks the path right before removing (through the
  #1734-guarded safeSourcesRemove) and logs each removal.

* D0: pass the Bun child flags after 'run' so wrappers that rewrite 'bun run' argv keep working

bun run --no-env-file --config=/dev/null <script> has the same effect
(verified on Bun 1.4.0) and keeps argv[1] === 'run', which the
publication-lock fixture's preload injection relies on. The sidebar-tabs
source guard now expects the flags in the terminal-agent spawn.

* E8: count the BROWSE_EXTENSIONS_DIR persistent launch in the signal-flags guard

The new launch site carries handleSIGINT/SIGTERM/SIGHUP false like the
other three, so the guard's expected count moves from 3 to 4.

* D2: give the memory-leak reproducer's fake request isNavigationRequest()

wirePageEvents now runs the navigation guard on every request event; the
fake request adapter supplies the method real Playwright requests have.

* A7: run only the resolve_symbol_edges dream phase, detected first

/sync-gbrain --dream and the --full auto-build ran gbrain's full dream
cycle (~35 minutes, LLM phases) when the call graph needs only the
resolve_symbol_edges phase. The stage now runs
gbrain dream [--source <id>] --phase resolve_symbol_edges when the
installed gbrain accepts that phase (detected by behavior: gbrain
validates --phase before printing --help). Otherwise it skips the forced
dream and says the full cycle costs about 35 minutes and how to run it,
instead of starting it.

Co-authored-by: liutiming <timingliu@outlook.com>

* D0: keep the dotenv isolation test runnable on the Windows lane

The compiled probe gets its .exe name on Windows, and the terminal-agent
case (owner identity comes from ps) is skipped there.

* B9: read cycle_freshness from a doctor run that includes it

/sync-gbrain Step 3.5 and the --full auto-dream decision read CYCLE from
gbrain doctor --json --fast, which skips the DB checks that carry
cycle_freshness, so the answer was always "unknown". Both now read
gbrain doctor --json --scope=brain (DB checks, no skill-file walk), parse
its JSON even when doctor exits 1 for a failing check, and match the
issue that names this source: "never completed" is never, "last cycled
Nh ago" is completed. When the installed gbrain does not report the
check, they say "unknown: installed gbrain does not expose
cycle_freshness" (lib readCycleStatus carries the reason to the --full
SKIP row).

The source-probe fixture that pinned the --fast call and a made-up
message format now answers --scope=brain with gbrain's real message.

* B4: compact the launch probe (cache keyed on inode, valid while newer than the binary)

Keeps design-consultation inside its parity size budget.

* C4: migrate the ship docs-dispatch test to the carved external ship

On Codex and Factory the documentation dispatch now lives in
sections/documentation.md behind a pointer relative to the installed skill,
like Claude; the test pinned the old inlined layout.

* B5: learnings callers report a failed search instead of reading as empty

Every generated gstack-learnings-search caller ended in 2>/dev/null || true,
so a missing bun or a failed search looked like 'nothing recorded'. Callers
now keep stdout, capture stderr and the exit status, and print
'LEARNINGS: unavailable (<first stderr line>)' on failure (resolver callers
in learnings.ts and review-army.ts, plus investigate, qa and ship's
adversarial section).

* F1: ship and review count unverified/unavailable outside reviews as missing coverage

INV-1 consumers in this lane's templates: /ship's readiness note, its
PR body Pre-Landing Review section and /review's completion rule now say
an outside review reporting unverified or unavailable is missing
coverage, never a pass. The PR body's Plan Completion section prints
F1's not-run line instead of the old 'No plan file detected.' The /ship
union-size cap moves to 1.415 for these lines (measured 1.4148).

* A8: rename the artifacts repo with OWNER/REPO, rewrite the remote only after it

The v1.27.0.0 migration passed a bare repo name to gh repo rename / gh
repo edit, which always fails (gh wants [HOST/]OWNER/REPO), then step 2
rewrote ~/.gstack-artifacts-remote.txt to the never-renamed repository.

- Qualify both names with the owner from the recorded remote URL (else
  the signed-in gh user) and surface gh's error.
- Step 2 moves the remote file but rewrites the URL only once the rename
  is confirmed; a later successful retry rewrites it then.
- A pending journal now counts as state to migrate, so the #1383 retry
  actually re-runs step 1 (it used to see no legacy file and declare the
  migration done).
- The v1.91.17.0 migration (placeholder name) repairs installs already
  hit: when the remote names gstack-artifacts-<user> that does not exist
  but gstack-brain-<user> does, it restores the old URL in the remote
  file and ~/.gstack's origin and says so. It only calls gh for such a
  remote and never fails the upgrade.

Co-authored-by: Brandon Pugsley <aibpaem@gmail.com>

* B8: read gbrain JSON with bun instead of jq in install and wireup

gstack-gbrain-install read package.json with jq but never checked for it,
so on a machine without jq a successful install failed with "cannot read
version". gstack-gbrain-source-wireup hard-failed without jq ("brew
install jq" is not actionable on git-bash), so the wireup was skipped on
every run. Both now read the JSON with bun, which they already require.

Co-authored-by: benjamin beres <benjamin.beres@bienpreter.com>

* B4: shorter probe messages (design-consultation parity budget)

* B5: shorter capture variable names (parity budget)

* E7: find the Aside CLI in ~/.local/bin when it is not on PATH (#2902)

The installer puts aside in ~/.local/bin, which is not on the default macOS
login PATH, so the probe said NEEDS_ASIDE ('download Aside') for a healthy
install. The probe now falls back to ~/.local/bin/aside, drives the resolved
binary, and prints READY: <path> when it is off PATH so later blocks run that
path. Ported from PR #2965 onto the current _gs_d probe.

Co-authored-by: Som Samantray <som.samantray@gmail.com>

* A2: key the dot-slug catalog entry on the message users actually saw

* E1: cmd.exe-safe investigate freeze hook

On Windows Claude Code runs hook commands through cmd.exe, which cannot parse
the single-quoted bash -c argument, so /investigate's scope-lock hook never
ran. Use one double-quoted bash -c script that names the hook path directly
(no S= variable: POSIX sh would expand $S to empty and skip the hook).

* F4: design resolver reads per-round variant paths

$D variants now writes $_DESIGN_DIR/round-<N>/variant-*.png and prints JSON
with roundDir, manifest and paths. The mockup flow and comparison-board loops
build the board from those printed paths instead of hardcoded
variant-{A,B,C}.png, and approved.json records approved_path and round so a
round-1 choice made after round 2 still resolves.

* E4: generators tolerate Bun's spurious EEXIST on Windows (#2329)

Bun on Windows throws EEXIST from a recursive mkdir of an existing directory,
so gen:skill-docs and the llms.txt writer crashed once a second file landed
in a directory. Both now use lib/fs-utils' mkdirpSync (ported from PR #2329
onto the existing helper instead of a new scripts/fs-utils.ts).

Co-authored-by: Vaughan <vaughan@cairnsitguy.com.au>

* C7: keep the required-mode hook's exit-2 deny

Copilot CLI treats a preToolUse exit 2 as deny (its hooks reference), and
#2413 established exit 2 plus hookSpecificOutput as the shape Claude Code
enforces, so the deny output stays as on main; only the matcher and the
in-place upgrade of older 'Skill' entries change.

* C3: guard Kiro's router copies on a present source; give the QA pointer adapter the copy and dist helpers

A copy fails where a symlink dangled, so the Kiro router and upgrade copies
are written only when their render exists (as every other runtime root
already does). test/qa-lazy-sections' extracted Kiro installer now supplies
_link_runtime_dists (C2) and the SKILL.md copy helpers (C3).

* Q3: office-hours asks open-ended questions in a Q<N> prose form (#2719)

In Conductor, and whenever AskUserQuestion fails, prose is the only channel,
and the prose fallback defined only the D<N> decision brief. Phase 2A/2B
diagnostic questions have no option set, so the model dropped the phase.
Office-hours' preamble now defines the Q<N> open-question form (question,
why I'm asking, what a strong answer sounds like) and routes free-text
replies to it; the diagnostic sections name it. Scoped to office-hours so
every other skill's preamble is unchanged. Ported from PR #2729.

Co-authored-by: Bharadwaj Mittapelli <bharadwajmittapelli@gmail.com>

* A2: render db-unreachable like timeout

gbrain's new db-unreachable status is a transient network failure; a setup
run while offline must not strip brain-aware blocks from every skill.

* A2: treat db-unreachable like timeout in gbrain-refresh

The memory lane's new db-unreachable status (network or DNS failure, config
intact) is transient, so gbrain-refresh keeps rendering brain-aware blocks
for it exactly as it does for timeout instead of suppressing them.

* C8: a render given disabled skills drops them from the router (#3018)

The root router named every skill and ends 'When in doubt, invoke the skill',
so it routed to skills the user disabled. gen-skill-docs takes
--disabled-skills (runGeneration disabledSkills): the router drops their
routing rules, keeps the other side of an 'A or B' rule, and names them as
disabled. The router and gstack-upgrade cannot be disabled. With no disabled
skills the render is byte-identical.

* G2/G3/INV-1: skill-start former-bucket notice and visible learnings failure; TMPDIR mktemp in gbrain bins; best-effort reasons

* C9: Step 2 falls back to the install registry's source checkout (DX-7)

Codex users who installed from the README's ~/gstack clone got 'ERROR:
gstack not found' from /gstack-upgrade: Step 2 only looked under host skill
directories. It now falls back to the source checkout the install registry
recorded for the current host.

* B4: design --version prints the version, and the probe uses it

The design CLI treated --version as an unknown command (exit 1), so the
probe launched the binary with no arguments instead. Add --version (prints
the gstack version, exit 0, before auth or network) and probe with it, so
messages read '<path> --version exited <code>' as planned.

* C4: no external render points at a section file that is not installed

design-html's detector install offer and plan-eng-review's self-check pointed
at $GSTACK_ROOT/<skill>/sections/<file> on every external host, where neither
skill is carved and no section tree exists. design-html now inlines the offer
off Claude, and a skill's pointer to its own {{SECTION}}-inlined section
names the inlined text.

* C1: skillify finds the browse SDK under its own host's install root

The template hardcoded ~/.claude/skills/gstack for the canonical
browse-client.ts, so external hosts read another host's install or nothing.
A new INSTALLED_ROOT resolver (sibling of INSTALLED_BIN_DIR) names the host's
global root, or the per-install root when setup renders for one.

* C4: rewrite section refs on hosts whose root stays a literal ~/<globalRoot>

Kiro, OpenCode, Cursor and Copilot render ~/.claude/skills/gstack as their own
literal root, not $GSTACK_ROOT, so plan-eng-review's self-check pointer
escaped the rewrite (found by the setup lane's installed-pointer check).

* Integrator: outside-voice fences use the shared runtime prelude; TMPDIR mktemp and per-round variant paths in design templates

* Integrator: C8 router omits disabled skills on every render (relink renders the served Claude router in place); Windows-safe E4/E6 entries; investigate hooks under the cmd.exe check; browse_extension_id reader; order-insensitive test typecheck identities

tsc printed one unchanged ceo-mode-option diagnostic's object members in a
different order (content?/isError?) once lib/fs-utils joined the generator's
import graph; identities now sort object-type members, and old baselines
normalize on read.

* Q1 (#2971 salvage): bound iOS proxy responses

One wall-clock deadline covers headers and body (stalled and dribbling bodies
time out), the whole body is capped at 64 MiB (upstream_response_too_large),
every terminal path clears its timer, removes listeners and destroys the
request, and the daemon threads the deadline through both listeners. Ambiguous
mutations are still never replayed after a timeout or abort. Ported from
#2971's proxy-transport work plus the size bound.

* I1: grade the AUQ matrix's (recommended) marker on option labels, the field the auto-decide hook reads

The decision-brief format puts a Pros / cons block with 'A) ... (recommended)'
in the question text and the same marker on the option label. The matrix
counted both and failed all six skills in periodic run 37151477069 with
'expected exactly one (recommended) option, found 2'. The question-preference
hook reads labels only, so the gate now checks the native question: a
Recommendation line in the question text and exactly one label ending in
(recommended). Fixtures move to the native question shape and add the real
spec capture plus a marker-only-in-text negative control.

* Q1: type the proxy-transport test doubles (typecheck:test ratchet)

* INV-1: gate outcome rows and troubleshooting sections for every lane's new messages

* Release v1.91.19.0 (next free patch in the queue: #3022 holds 1.91.17.0, #3023 holds 1.91.18.0); migration renamed; engines.bun >=1.4.0 to match the CI pin (#2815)

* v1.91.19.0 docs and metadata: CHANGELOG, TODOS, README troubleshooting/upgrade/type --selector, BROWSER.md type and profiles, AGENTS.md conventions, CONTRIBUTING #2949, touchfiles for the wave's new lib/bin files

* I1: give hermetic Codex runs a temp dir beside CODEX_HOME so Codex can create its PATH aliases

Codex 0.160 refuses to create its helper aliases (codex-linux-sandbox among
them) when CODEX_HOME sits under its temp dir, and the runner put the
hermetic home under the shard TMPDIR. Periodic run 37151477069 shows the
warning and 'Unable to spawn codex-linux-sandbox ... No viable candidates
found in PATH' for every exec_command in codex-sol-scope-termination.

* I1: Codex evals fail a review whose commands never ran and stop reading tool errors as skill-load problems

validateCodexReview accepted codex-review-findings in periodic run 37151477069
although its only command failed in bwrap ('I couldn't run the review'); it
now requires execution evidence from classifyOutsideReview (B1's INV-1
classifier). codex-sol-scope-termination failed on 'apply_patch verification
failed: invalid hunk' because the skill-load check matched any 'invalid';
it now matches Codex 0.160's skill-loader diagnostics only.

* I1: run paid eval containers with seccomp unconfined so Codex's sandbox can start

Docker's default seccomp profile blocks the user namespaces bubblewrap needs,
so every Codex command in a paid eval failed with 'bwrap: No permissions to
create a new namespace' (codex-review-findings, run 37151477069). Reproduced
in the CI image locally: default profile fails, seccomp=unconfined runs the
command. The runner stays non-root.

* I1: shared-libs plan actor reads one exclusion grammar for scope lists

Periodic run 37151477069 refused 'Existing-caller migration and helper
hardening stay out of scope' as a hardening proposal: the actor had two
partial exclusion rules (unanchored is/are/remains outside, and an anchored
list that only stays unchanged), the third refusal at this boundary after
36633323521 and 36776104571. One anchored predicate now covers a bare list
of scope nouns (hyphenated compounds included) with is/are/stays/remains and
unchanged/untouched/excluded/out of scope/outside/not part; any other verb
in the clause is still read as a proposal. Adds the real capture and two
adversarial controls.

* Parity caps: measured v1.91.19.0 union/skeleton sizes for ship, review, design-consultation, office-hours and design-shotgun, with the reason beside each

* Regenerate generated output for v1.91.19.0 (gen:skill-docs --host all, goldens, llms.txt, context-budget fixture)

* I1: plan-eng-review writes the Test Plan Artifact even while test choices are pending

Periodic run 37151477069 (plan-eng-review-artifact): a non-interactive review
recorded every Test review choice as pending and never wrote the QA test
plan, because Step 5 said to write the artifact 'when these test and eval
choices are resolved' while the artifact section says to list unresolved
choices as pending. Both now say to write it after the decision gate, with
unanswered choices under Pending Decisions. The pinned sentence becomes a
meaning-level check.

* I3: plan-eng-review states when findings first enter the report and that the scope menu's recommendation needs no repo probe

Judge rationales for 'plan-eng-review/SKILL.md sections' (actionability 3.67
in periodic run 37151477069, clarity 3 in 36385945043 and 35567915613) cite
two concrete tensions: 'do not add findings before Scope Challenge C' versus
the ledger saves C itself performs, and 'Recommendation: A when a branch diff
exists' versus 'do not probe for session state'. The write policy now says
findings first enter through Scope Challenge C's ledger saves; the selector
says its Recommendation line advises the user and needs no repository
inspection. The pinned sentence becomes the new meaning-level regex.

* I3: plan-ceo-review defines the closing sequence's cleanup step

Two of three judge samples for 'plan-ceo-review/SKILL.md modes' in periodic
run 37151477069 (actionability at the 4.0 gate) flag 'perform permitted
cleanup' as never defined. The only cleanup the skill has is archiving old
CEO plans, which needs approval; step 5 now says so.

* I3: /qa-only's value-card rule names only its own card location

qa-only rendered the /qa line 'Put it in the 8e.5 record (/qa) or under each
proposed test (/qa-only)'; judge samples for 'qa-only/SKILL.md workflow'
(actionability at the 4.0 gate in run 37151477069, 3.67 in 36907895813)
flag the /qa-only-irrelevant 8e.5 record. The qa-mode bar now renders the
invoking skill's location; both skills get shorter.

* test-of-test ratchet: a repo script or setup read by path counts as product code

codex-invocation-sites (runs scripts/gen-skill-docs.ts), gstack-config-gbrain-refresh
(copies bin/<name> through a variable) and setup-cso-windows-probe (reads setup and
scripts/build-cso-windows.ps1) exercise product code the detector could not see.

* I1: DX floor actor strips the editor hint from the footer line only (from #2971)

The custom-field reply normalization removed 'ctrl+g to edit in <editor>'
from every line, so question text that resembled the menu footer could be
rewritten and still authenticate. Only the last non-empty line is the
footer. Ported from Garry's #2971 with its negative control.

* I4: attribute every census testcase; deselections never count as SKIPPED

The paid report counted every skipped JUnit testcase as SKIPPED and every
testcase whose name was not a registry id as unattributed. On the 2026-10-03
census (run 37151477069) that was SKIPPED 82 / unattributed 72 (periodic) and
SKIPPED 282 / unattributed 24 (gate), and every case-shard sibling also wrote a
skipped history record that reset its pass-rate series.

- attributeJUnitCase: a name is its registry id or CASE_TEST_NAMES label, else
  the only id its file registers, else the keyless file itself. Skipped
  other-tier cases, case-shard siblings, isolated or unselected cases and Bun's
  '(unnamed)' hook placeholders are zero-credit deselections with a reason and
  write no history record. Anything else is listed by name as unattributed.
- One result and one history record per case per shard; a genuinely skipped
  selected case counts as SKIPPED and is listed with its reason, also in
  report-summary.md and collector-outcomes.json. SKIPPED panels show their
  reason and skipped trials are no longer called assertions.
- CASE_TEST_NAMES labels for the three /cso cases.
- tierSkipReason: a computed registration whose lane-tier ids are all
  registered to other test files is excluded at plan time, so the four gate
  and two periodic files that ran with every test skipped no longer take a
  runner.

Census rerun: periodic SKIPPED 0 / unattributed 0, gate SKIPPED 0 /
unattributed 0; verdicts unchanged.

* I5: split the deploy file per case; guard PR-lane shard walls at 600 s

test/skill-e2e-deploy.test.ts ran 668 s as one gate shard in the 2026-10-03
census (six sequential cases, 51-201 s each). It is now case-sharded, so each
case is its own shard with its own (smaller) supervision budget; no timeout
or budget was raised.

- CASE_SHARDED_FILES gains the deploy file (names already equal ids).
- Gate duration seeds for the six case keys from the census JUnit walls, so
  packing stays at 12 gate-census slices (CI cap 230m -> 200m).
- shardDurationViolations + PR_LANE_SHARD_LIMIT_MS: a free test fails when a
  planned gate shard's recorded wall (committed seed, and the last gate census
  in test/fixtures/paid-report-census/gate-census-durations.json) exceeds 600 s.
- Tests that pinned deploy as one shard follow the split (cookie planner keys,
  reuse fixture key, release/PR floors).

* TODOS: /review fingerprint under Codex's read-only .git sandbox (found by the live Codex check)

* Free-suite repairs from the first integrated Ubicloud run

Product:
- Outside-voice fences carry runtimeRootPrelude(ctx) explicitly again, so the
  resolver output runs on its own (the post-render pass skips fences that
  already assign GSTACK_ROOT); outsideVoiceRuntime stays deleted.
- D5: an explicit CHROMIUM_PROFILE (gbrowser's per-workspace gbd) is never
  seeded from the shared profile or registered for `browse profiles prune`;
  this was also the free suite's write to the real ~/.gstack/browse-profiles.json.
- gstack-ios-qa-daemon: BASH_COMPAT=50 for its >512-byte --help heredoc.

Tests migrated to the wave's deliberate contract changes:
- B1 heading admits `unverified`; sandbox flag is ${_GSTACK_CODEX_SANDBOX:?};
  verdict-form output (VERDICT/FINDINGS/REASON); fake codex follows the
  preflight + stdin + -o form; Q2 notice marked shown in a private state root.
- C1: an exported root needs bin/ and lib/; a lone GSTACK_BIN is not honored.
- C4: plan-ceo-review is carved on every host (carrier, discovery and
  methodology fixtures read sections/ when the render has it).
- E7: READY prints the resolved Aside path.
- INV-3: the cookie-approval reconstruction reverses the bun-install mktemp template.
- F1's `Plan:` binding read gets a reasoned tracker-guard exemption.
- Browse stubs stop their server instead of scheduling process.exit; the
  headless launch check only counts browsers its own launch started.

* Regenerate generated output after the outside-voice prelude repair

* I1: revert the seccomp-only eval container option; it does not let Codex's sandbox start

Run 37158847998 on this branch and a stock Ubicloud VM both show that
seccomp=unconfined only moves bubblewrap's failure from 'No permissions to
create a new namespace' to 'Failed to make / slave: Permission denied'.
Codex's sandbox started only with the host sysctl
kernel.apparmor_restrict_unprivileged_userns=0 plus seccomp and AppArmor
unconfined on the container, which a container job cannot set from its
steps. The relaxation bought nothing, so it goes; the fix is filed as a
TODO for the integrator.

This reverts commit ec97187.

* I1: a Codex review eval needs a completed command, not just review-shaped text

Run 37158847998 recorded codex-review-findings as passed again: the agent
wrote 'I couldn't run the review because the execution sandbox failed
(bwrap: Failed to make / slave)', the failure never reached stderr or a
command event, and no phrase rule matched. validateCodexReview now also
requires at least one command_execution event that completed with exit 0.
Fixtures gain that event; the CI output is a new negative control.

* Evals lane follow-ups: close the skillify gate TODO (I2 green), file its open reds, CHANGELOG lines; refresh measured parity annotations

* Regenerate generated output after merging wave/evals

* D2: bound the navigation guard's tab reset (commit, 5 s)

Ubicloud run 3: a click to a link-local link reported the block, but the
reset's page.goto('about:blank') waited the full 30 s default navigation
timeout, so the command hung past the test deadline and the stale block
leaked into the next command. The reset now waits for commit only, with a
5 s bound.

* I1: run Codex paid slices on a host-run job where bubblewrap can start

Docker's default seccomp/AppArmor profiles and the Ubuntu 24.04 host's
kernel.apparmor_restrict_unprivileged_userns=1 keep Codex's bubblewrap
sandbox from starting in a job container, so every Codex command failed.
The planner now packs Codex shards into their own slices (plan.codexSlices,
validated against the entries); evals-periodic runs those slices on a new
host-run job that lifts the host restriction and runs the same CI image
with seccomp and AppArmor unconfined. Artifact names match eval-slices,
so the report reconciles one manifest. Gate plans have no Codex slices.

* I1: the /codex review eval passes only when Codex executed

Run 37158847998 recorded codex-review as passed while the sandbox
preflight said unavailable and no review ran: the case only checked the
session exit and an optional output file. It now requires the shared
validator's executed verdict (findings, clean or unverified) in the
codex command's own output and a written, non-fail-closed GATE.

* TODOS: characterize the free-suite timing reds from Ubicloud run 4

* I1: QA evidence names the probes to rerun after an input change, before the one-shot materialize

ship-exploratory-late-input returned inconclusive in gate census 37158847998:
the fixture locale changed after captures 001 and 002, the agent reran only
input 9, and materialize (which publishes once) recorded capture 001 as open.
Its next line then said to rerun what is open, which the published verdict no
longer allowed. Every capture now lists the commands that observed an older
input snapshot and have no rerun on current inputs (revalidate, plus the next
line), and materialize's next line says the verdict is final.

* I1: the eng batching counter reads records under "Section N — <review> review" headings

plan-eng-multi-finding-batching failed in 6 of 12 runs with reviewCount 0-1
(or a timeout with every ask counted as Step 0). In run 37158847998 the agent
asked 11 separate questions, each with a saved ledger record, but filed
records R2-R10 under '## Section 1 — Architecture review'. The counter strips
'Section 1' but not the dash separator, so it rejected every record outside
the Decision ledger and the floor never filled. Quoted, historical and
unrelated headings still do not count.

* I1: plan-eng-review-artifact names its report file without making it the only output

Runs 37151477069 and 37158847998 wrote the whole review, including the
GSTACK REVIEW REPORT, into review-output.md and never ran the Test Plan
Artifact block. #3017 made the artifact a hard assertion and dropped the
prompt's explicit artifact instruction, leaving 'Write your review to
review-output.md' as the one named destination. The prompt now names that
file as the selected report file and says every other output keeps the
destination the skill gives it, without naming the artifact.

* browse: close returns when Chromium exits; Xvfb cleanup does not wait on its own zombie

BrowserManager.close() detached every 'disconnected' listener before
browser.close(). That also removed Playwright's internal listener that
resolves close(), so every launched-mode close waited the full 5 s race
timeout (measured 5,000 ms on origin/main and on this branch; raw Playwright
closes in ~50 ms), and Playwright 1.62 has no Browser.process() for the
SIGKILL fallback. The daemon's SIGINT shutdown therefore took over 5 s, which
reddened the CLI lifecycle test under load (1 of 8 on main) and left browsers
alive at shard cleanup. gstack now detaches only its own listeners: close
takes ~50 ms.

cleanupXvfb treated a terminated Xvfb child as alive until our own blocked
event loop reaped it, so every close waited a full second then sent SIGKILL
to a zombie. A zombie now counts as exited; the display test counts only
running Xvfb processes.

* I1: office-hours-brain-writeback reads the long skill with Read and skips the preamble

4 of 18 trials ended error_max_turns at the unchanged 12-turn budget with a
gbrain search but no gbrain put. The failing trial in 37151477069 read the
1260-line rendered SKILL.md with cat, got truncated output, spent four more
turns re-reading it with sed, then ran the preamble's skill-start block. The
passing trials skipped the preamble. The prompt now says to read the skill
with the Read tool and skip the preamble, onboarding, telemetry and
contributor sections, as the plan-eng fixtures already do. Budget unchanged.

* CI: no credential-shaped URLs in added lines (quality scan); release floor measured on the merged tree

The quality job's credential scan of the PR diff flagged 7 db.url_with_password
lines: three docs lines now describe the login instead of spelling a URL, and
three tests build the URL from parts. paid-retry-supervision's periodic release
floor is the merged tree's measured 35,711 (main's value; the evals lane's
33,821 predates main's new paid files).

* qa-evidence: hold the stdout-pipe cases on a FIFO, not on a paused child stream

Ubicloud run 4 finished the blocked-forever case in 71 ms (it should take the
5 s write deadline): the 2 MB write was not held, because saturation depended
on how the runtime buffers a paused child pipe. On POSIX the child's stdout is
now a FIFO the test reads only when it chooses to, so the kernel holds the
write; Windows keeps the paused pipe.

* TODOS/CHANGELOG: the three run-4 timing reds are fixed at their causes (daemon close latency, FIFO-held pipe tests)

* I1: a QA helper call bun could not load is checked at the installed path, not failed outright

review-exploratory-small-cli failed gate census 37162480720 with 'command
outside declared caller observation interface': the actor dropped one
character from the shard directory in a gstack-qa-evidence capture path, bun
refused to load it ('Module not found', exit 1), and the next call ran the
same capture correctly. A failed call whose only output is bun's refusal for
a gstack-qa-evidence/deadline path is now held to the interface as the same
command at the installed helper path, so a compound or undeclared command
still fails.

* I1: plan-eng-review's final self-check names its three outputs

The fixture-prompt repair did not hold: in 37162480720 plan-eng-review-artifact
again wrote one review-output.md, ran the skeleton's read-back gate on it and
stopped without the QA Test Plan artifact (no gstack-paths/gstack-slug block).
The transcript shows the agent's last check before finishing is the skeleton's
Section self-check, which said only 'and outputs'. It now names the saved
report, the QA Test Plan artifact and the Review Log, each at its own
destination or presented as not persisted (the existing write policy).

* I1: revert the plan-eng-review self-check wording; it did not change the artifact outcome

A local run of plan-eng-review-artifact in the CI image (Claude Code 2.1.284)
at e2f65ab22 still wrote one review-output.md in 8 turns and ran no Bash, so
the QA Test Plan artifact block never ran. Keep the skill text unchanged; the
case is deferred with its evidence.

* I1: seed the Codex files' periodic durations from their first executing run

Every Codex file recorded ~1 s because its commands could not start in the
container (codex-e2e*, outside-voice, workflow). Run 37162480720 executed them
on the host-run job; its slice 24 walls replace the placeholders so the
planner packs the Codex slice by real work (7 files, ~4.9 min estimated).

* Refresh scripts/free-test-durations.json (bun run test:ubicloud --record-durations; covers the wave's new test files)

* evals2 follow-ups: outside-voice-evidence helper in five case touchfiles; close the evals lane's Codex-CI, late-input, batching and brain-writeback TODOs (run 37162480720); CHANGELOG lines

* fix(browse): take the next free X display when a concurrent allocator wins the race

Pick-then-spawn let two allocators (parallel daemons or test shards) choose
the same free display; the losing Xvfb exited and the handoff failed (run 6,
handoff 'failure before launch'). spawnFreeXvfb now treats a display taken
during startup as a collision and moves on. Regression test forces the race
with a delayed Xvfb wrapper (pre-fix: fails; two-process repro 13/15 -> 0/15).

* test(ci): read the host-run Codex eval job's docker env, mounts and uploads

eval-codex-slices runs on the host and passes its executor env through docker
-e flags and HOME through a $RUNNER_TEMP/eval-home mount. The evidence and
coordination tests now map those back to the container view instead of
assuming job.container, and the job's native-capture upload carries the
qa-callers paths like the other executors.

* I1: plan-eng-review-artifact runs the real interactive review in a PTY, replacing the composing fixture

The claude -p case told the model to skip the preamble and questions and go
straight to the review. In 37151477069, 37158847998, 37162480720 and a local
CI-image run it wrote the whole review into one file without executing the
workflow, so it measured composing, not /plan-eng-review. The interactive
batching PTY run in 37158847998 did write the artifact during Test review, so
there is no product defect.

New test/skill-e2e-plan-eng-artifact.test.ts keeps the case id, tier
(periodic), kind (rule) and budget (CAPTURE_LONG_MS): it drives the real
/plan-eng-review over the same dashboard plan and sources, answers each
question with its first option, stops once the QA test plan exists or the
report completes, and asserts the same requirement (exactly one new
eng-review test plan in the run's own state root, about the dashboard change).
The composing case is retired from skill-e2e-plan.test.ts in this commit.
runPlanSkillCounting reports engTestPlans (read before fixture cleanup) and
passes them to isCollectionComplete. One paid run in the CI image (Claude Code
2.1.284): pass, collection_complete at 498 s with one test plan.

The new file takes its own periodic runner (seeded at 498 s), so the periodic
census plans 26 slices: the planner's --max-parallel and both executors' caps
move from 25 to 26 so every slice still starts at once; the paid-file census
pin moves from 106 to 107.

* evals2 final: plan-eng-review-artifact touchfiles point at its PTY file and helpers; plan file wall drops the moved case

Applies the lane's touchfiles-data patch (its outside-voice-evidence hunks
were already in 9a96fb3). skill-e2e-plan.test.ts lost one 600 s case to
skill-e2e-plan-eng-artifact.test.ts, so its periodic wall is two 900 s + two
600 s (3,000,000 + reserve) and its timeout pin lists the remaining cases.

* TODOS/CHANGELOG: close plan-eng-review-artifact (real PTY review, 498 s pass)

* test: plan-eng-review-artifact is a PTY runner consumer (selected by claude-pty-runner and pty-screen changes)

* test(windows): spawn cmd.exe hooks verbatim, use a .invalid UNC host, and match CRLF fixtures and native separators

windows-free-tests reds on 364f0f3, each verified on windows-latest
(46 pass, 1 POSIX-only skip, 0 fail):
- investigate-freeze-path cmd.exe cases: Bun MSVC-quoted the command line
  cmd.exe parses, so cmd saw \"bash and failed; Node's shell spawn (what
  Claude Code uses) passes it verbatim.
- investigate-freeze-path UNC cases: a single-label host made each
  filesystem probe wait on network name resolution (cd 11 s, -L 2.8 s);
  a reserved .invalid host fails at once (55-80 ms).
- paid-report-census: the junit fixture is CRLF in a Windows checkout.
- codex-invocation-sites: rendered paths use backslashes on Windows.

* eval(plan-design-with-ui): the Step 0D focus title may spell the seven dimensions as a word

Run 37166586458 slice 5 (dfaf154) asked 'D2 - Review all seven design
dimensions, or focus on specific areas?' and reached its review finding,
but the focus predicate only accepted the numeral, so the case failed with
no acknowledged Design focus. Both recognizers accept 7 or seven; the
byte-exact capture is a free regression, and engineering/other-count/
no-'design' titles stay rejected.

* eval(ship-docsync): git check-ignore is a declared read in the docs observation interface

Run 37166586458 slice 2 (dfaf154): ship-docsync-completion's parent ran
'git check-ignore -v .qa-state' to verify the prompt's claim that the
observer probe is Git-excluded. The read was outside the closed Git list,
so the run's DOC_PATH replacement was unprovable and failed. check-ignore
cannot write; it joins the list and the interface prose. Free regression
replays the captured command against the fixture and keeps composition and
redirects rejected.

* fix(browse): read Xvfb's own startup error to classify a lost display race

Run 10 (1ffd38e) failed handoff's concurrent promotion once: 'Xvfb on :100
exited during startup (code 1)' with the display free again by the exit
check, so a holder that won the lock and closed within the 100 ms poll
looked like a broken install. Startup stderr now goes to a private file;
'Server is already active for display' is a collision and moves on, and any
other startup exit carries Xvfb's fatal line. Regression: a stub that
reports the collision for one display and exits leaves spawnFreeXvfb on the
next display (pre-fix: the misleading install error).

* test: merged-main fixtures (E6 copies the Claude render library gstack-config now sources; the census fixture's plan-mode-no-op budget follows its v1.91.18.0 policy)

* qa: materialize runs once per PROBE_DIR, and qa-only says §1 reuses the REPORT_DIR it resolved

Run 37170610789 slice 3 (feaa28d): the qa-only workflow judge scored
clarity 3.33 and named two ambiguities: §4 said materialize runs once per
report root while mixed runs materialize each surface's PROBE_DIR, and
SKILL.md deferred exploratory §1 without saying §1 reuses the REPORT_DIR
resolved under Prepare Report Artifacts. A local run of the same judge on
the repaired text: clarity 3.67, completeness 4.33, actionability 4 (pass);
all three samples call the workflow internally consistent.

* Regenerate generated output for the qa materialize/REPORT_DIR wording

* eval: three detector defects from run 37170610789 (feaa28d)

- safety-codex-consult-embed: the fake codex recorded argv only, but every
  codex exec takes its prompt on stdin since E5; it records stdin for the
  '-' form and the check reads both.
- ship-docsync-missing-asset: 'ls ... 2>&1' on a read-only command is the
  same harmless stderr wrapper as '2>/dev/null'; stdout redirects, pipes
  and script calls stay rejected.
- qa-functional-webhook-fix: a pre-repair capture whose command reran on
  the repaired inputs may be classified superseded (exploratory §4); the
  evidence check accepts that and still rejects superseded on a post-repair
  capture or one never rerun.
Each free regression fails without its repair.

* fix(test:free): a browser record removed mid-read by a shutting-down daemon is absent

Run 13 (feaa28d) needed the flaky-retry for 'owned detached browser
settlement > cancel': 2 unattributed failures instead of 1. A 16-vCPU
stress run reproduced it once in 64 with the cause:
'browser ownership unavailable'. On SIGINT the cancelled daemon removes its
state file; record() saw it exist, then lstat/read hit ENOENT, which
failure() reports as an ownership error. ENOENT there now means absent.
New mode cancel-vanishing-record forces the removal between the check and
the read (pre-fix: 2 unattributed, deterministic; now 1).

* test(windows): the 2>&1 wrapper regression uses relative reads (no native paths in literal commands)

* test(plan-seed): wait for the fixture CLI's slash event instead of a fixed 50 ms

Run 14 (b2f729b) needed the flaky-retry for 'startup-placeholder': the
events log had paste/enter/end_turn but not yet the slash 50 ms after it
was sent. The check now polls (bounded 5 s); the deadline assertion
measures when submission settled, which is what it bounds. One test
typecheck diagnostic goes away with the typed reader.

* eval(plan-design-with-ui): recognize the Step 0D focus question by meaning, not one title spelling

The b2f729b gate run titled it "I've rated this plan 5/10 on design
completeness. Review all 7 dimensions, or focus on specific areas?", the
third native wording to miss a spelling-pinned regex. The native form is
now a class: a title that offers all seven (numeral or word) dimensions or
passes versus a focus and names design. Captured titles from 37166586458
and this run pass; other counts, engineering passes, titles without design
or without a focus stay rejected.

* eval(shared-libs-read-only): curl answers the provider rate-limit probe with the same 404 as gh

Gate census 37174266054 slice 9: the model probed API availability with
curl -o /dev/null https://api.github.com/rate_limit (GET, discarded). The
gh transport already answers rate_limit as an unknown endpoint (404); the
curl transport refused it, and the refusal counted as a read-only
violation. curl now gets the same 404. POST, file output, other repos and
raw hosts stay refused. Paid rerun (gate, 1 trial): PASS in 177 s.

* eval(shared-libs-plan-callers): an exclusion may combine states (unchanged/out of scope)

Periodic census 37174266054: every option ended 'Scheduler semantics,
existing callers and helper hardening stay unchanged/out of scope', which
the actor read as proposing hardening. Exclusion states may now be joined
by '/', 'or' or 'and'; the captured question is answered, and clauses that
pair a state with a real change ('stay unchanged/harden the helper') are
still refused. Paid rerun (periodic, 1 trial): PASS in 296 s.

* paid: --case plan-eng-review-artifact selects its PTY test by its registered name

A local --case run matched 0 tests (no spend): the PTY test's Bun name is
not its case id, and CASE_TEST_NAMES had no label for it.

* eval(plan-eng-review-artifact): periodic checkpoint resumes at Test review; the fresh full run moves to marathon

A fresh interactive /plan-eng-review cannot reach Test review inside the
600 s periodic budget: startup plus one-at-a-time Scope Challenge questions
took 595 s with six questions and no Test review in census 37174266054 and
in a local run (one earlier fresh run passed at 498 s). Per the eval-speed
policy, the long run moves to the non-blocking marathon lane and the
blocking case becomes a focused checkpoint.

- plan-eng-review-artifact (periodic, 600 s unchanged): resumes the real
  interactive skill from a saved review record: the plan, the Scope
  Challenge result, Sections 1-2 complete, and a Decision ledger rebuilt
  from that census run's six actual native questions and answers
  (test/fixtures/plan-eng-artifact-resume-37174266054.json). The live skill
  runs Section 3, Test review. Assertion unchanged: exactly one new
  eng-review test plan in the run's own state root, about the dashboard
  change. Paid trial (local, Claude Code 2.1.284): PASS, 364 s.
- plan-eng-review-artifact-full (marathon, PTY_LONG_MS): the fresh
  start-to-finish run with the same assertion; budget measured beside it.
- test/plan-eng-resume.test.ts proves the rebuilt record is a valid resume
  point and rejects missing, unanswered, edited or duplicated records.
- Registry: touchfiles, tiers, kinds, test-name labels, durations, paid
  file count 115, PTY consumer list; CHANGELOG and TODOS.

* setup-deploy: say which deploy fields count as confirmed, how to resolve the default branch, and group the detection tests

Periodic census 37176837432: the setup-deploy workflow judge's actionability
mean was 3.67 (4, 4, 3). The low sample named the Fly/Heroku/Railway/GitHub
Actions deploy trigger left undefined until Step 4's 'not already confirmed'
catch-all and an unstated way to find <default branch>, and misread
'A || B && C' detection lines. Step 4 now defines a confirmed field and names
the paths that leave the trigger unset, <default branch> resolves with
gh repo view, and the two OR'd detection tests are grouped explicitly (same
behavior). One judge run on the repaired text: 4/4/4, pass.

* Regenerate generated output for the setup-deploy wording

* TODOS: census data for the skipped CEO mode handoff (mode-routing, auto-decide-preserved); floor runner Edit-permission parse under collapsed TTY spaces

* fix(browse): a blocked navigation that fails at once leaves the tab blank and the next command clean

PR CI on 8d2d269 (free-suite 3): the redirect to [::ffff:169.254.170.2]
failed immediately on the runner, so its chrome-error page committed around
the guard's about:blank reset, and leaving the error page committed a
second about:blank after the reset resolved, interrupting the next three
tests' gotos. The guard now lets the blocked request settle (bounded at
1 s; a hanging target is still cut off by the reset), resets, and waits for
the main frame to stay quiet before returning. Regression: a redirect to a
blocked address on Chromium's unsafe port 1 fails at once (pre-fix: blank
check and the next goto fail, deterministically).

* qa: the checkpoint note is created for browser runs and composed for functional ones

Periodic census 37178143007: the qa-only workflow judge scored
actionability 3.67 again; one sample read step 2's 'Create
exploration-NNN.json' as applying to functional runs before reaching
'Functional: do not write this file'. The sentence now names both surfaces
up front; byte-neutral (the browser line drops its restated clause), qa
union 1.1098 under its 1.110 cap. One judge run on the repaired text:
3.67/4/4, pass.

* Regenerate generated output for the qa checkpoint wording

* eval(section-loading): byte-range prints of a section count as a complete read

Periodic census 37178143007: plan-ceo-section-loading printed
review-sections.md in five byte ranges (head -c 16000, then tail -c +N |
head -c 17000, one-byte overlaps) and the detector, which matched whole
printed lines, saw the lines split at each range edge as missing. Outputs
of the commands that name the section are also joined on their overlap.
Regression: the captured ranges count; dropping a middle range or the last
range does not (pre-fix: the complete ranges were refused).

* test(plan-design-review): count design terms the review wrote into the plan

* fix(aside): probe names the platform (GSTACK_PLATFORM override) so the macOS pitch never re-probes the OS

* fix(plan-ceo-review): Step 0E mode handoff runs gstack-ceo-mode-handoff so the selected mode is printed, not only composed

* chore: refresh context-budget fixture

* test(auto-decide): accept Step 0E's documented AUTO_DECIDE line with its decisions suffix; replay the captured trial

* docs: CHANGELOG and TODOS for the CEO mode handoff and platform line

* test(plan-design-review): plan-term credit needs a rated summary; adapter regression for census 37179171083

* test(auto-decide): the printed handoff may precede Step 0E's provenance log; replay census 37182865432; TODOS for two rotating census reds

* test(plan-ceo-section-loading): read the skill's ledger and currentDecision records for the stale-fill decision; replay three census reports

* test: $B counts as a browser call only in command position; qa functional prompt defines its classification values

* test(shared-libs-plan-callers): a verbless unchanged-scope list is an exclusion; replay census 37186854666; TODOS for two census reds

* fix(settings-hook): retry a lock released between mkdir and the existence check instead of dropping the mutation

* test(ship-docsync): the child's reply to a parent SendMessage counts as its spawned-marker report; replay PR run 37188668421

* test(browse): Xvfb stub-failure tests allocate from ranges no other allocator uses

* perf(ship): documentation gate snapshots and compares its candidate with gstack-docs-candidate

* fix(review): unverified Codex mode runs the passes in the mode summary too; stale-fill decision check accepts any ledger row ID

* test(shared-libs-plan-callers): judge scope by forbidden verb+object actions, not an exclusion grammar; replay six refusals and four passing censuses

* test(shared-libs-plan-callers): type the brief-line parameter

* test(ship-docsync): an inline-code status quote is not a false current claim; replay PR run 37196811165

* fix(review,ship): Codex challenge and structured-review bodies run in unverified mode, matching their headers

* docs(TODOS): overlay-harness control-arm error and format-approach provider refusals, with run links

* docs(TODOS): qa-only workflow judge data point

---------

Co-authored-by: Lewis <lewispeel@hotmail.com>
Co-authored-by: Yugz <yannduzelier@gmail.com>
Co-authored-by: Florian <florian.cleyetmerle@gmail.com>
Co-authored-by: cdecook23 <decook23@gmail.com>
Co-authored-by: mb1810 <michael.berger1810@gmail.com>
Co-authored-by: Koda <koda@edgeviewfinance.com.au>
Co-authored-by: Merit Blake <merit@newsprint.com>
Co-authored-by: Nguyen Thanh Dat <ntdat812@gmail.com>
Co-authored-by: pneumorea-ai <pneumorea@gmail.com>
Co-authored-by: maxpetrusenkoagent <max.petrusenko.agent@gmail.com>
Co-authored-by: Matt Van Horn <mvanhorn@gmail.com>
Co-authored-by: Infiniteyieldai <infiniteyield.ai@gmail.com>
Co-authored-by: Gabriel Rondon <grondon@gmail.com>
Co-authored-by: Davon Johnson <d.johnson@dayofshow.net>
Co-authored-by: Kevin Grasso <kevin@biblingo.com>
Co-authored-by: Xuan-Ce Wang <261591073+xwang4-svg@users.noreply.github.com>
Co-authored-by: loulanyue <260355617@qq.com>
Co-authored-by: Thomas Reuser <thomasreuser@gmail.com>
Co-authored-by: Bit0ps <alex.dreamscaper@gmail.com>
Co-authored-by: oli548 <312288720+oli548@users.noreply.github.com>
Co-authored-by: Slava <slava.istomin@tuta.io>
Co-authored-by: ryanlaiwy <129729476+ryanlaiwy@users.noreply.github.com>
Co-authored-by: 李翊楠 <yinanli1917@gmail.com>
Co-authored-by: Mammad M. <mammad@digit.az>
Co-authored-by: Lockyer <135391289+Lockyer228@users.noreply.github.com>
Co-authored-by: Spooks444 <193448029+Spooks444@users.noreply.github.com>
Co-authored-by: punksterlabs <77217235+punksterlabs@users.noreply.github.com>
Co-authored-by: Jonathan Zhang <topcoder1@Mac-Studio.local>
Co-authored-by: Marek Cermak <marek.cermak@strv.com>
Co-authored-by: y$un_ <forrest.sun527@gmail.com>
Co-authored-by: neallee <neallee@gmail.com>
Co-authored-by: hardy <932821449@qq.com>
Co-authored-by: afshaker <andrew@phone2.io>
Co-authored-by: cube <frosimanuel@gmail.com>
Co-authored-by: jacob-wang <jiayuw794@gmail.com>
Co-authored-by: miao <miao@macmini-2.local>
Co-authored-by: Jonah Berg <jonah.berg.g@gmail.com>
Co-authored-by: Jayesh Betala <jayesh.betala7@gmail.com>
Co-authored-by: Ryan Alberts <ryan.a.alberts@gmail.com>
Co-authored-by: AlinValentin7 <AlinValentin7@users.noreply.github.com>
Co-authored-by: Evgenii Lopatin <e75533@gmail.com>
Co-authored-by: Jino <dgfrty00@gmail.com>
Co-authored-by: snig-17 <santosh.m.tiwari@gmail.com>
Co-authored-by: Sholto McNeilage <sholto@nodenarrative.com.au>
Co-authored-by: Phil Hie <philhie@outlook.com>
Co-authored-by: Sinabina <sinabina@Sinabinas-MacBook-Pro-4.local>
Co-authored-by: Jimmy Zeisweiss <4261258+jzeisweiss@users.noreply.github.com>
Co-authored-by: liutiming <timingliu@outlook.com>
Co-authored-by: Brandon Pugsley <aibpaem@gmail.com>
Co-authored-by: benjamin beres <benjamin.beres@bienpreter.com>
Co-authored-by: Som Samantray <som.samantray@gmail.com>
Co-authored-by: Vaughan <vaughan@cairnsitguy.com.au>
Co-authored-by: Bharadwaj Mittapelli <bharadwajmittapelli@gmail.com>

.github/workflows/evals-periodic.yml

@@ -98,6 +98,7 @@ jobs:
       contents: read
     outputs:
       periodic_slices: ${{ steps.periodic-matrix.outputs.slices }}
+      periodic_codex_slices: ${{ steps.periodic-matrix.outputs.codex_slices }}
       periodic_timeout_minutes: ${{ steps.periodic-matrix.outputs.timeout_minutes }}
       gate_slices: ${{ steps.gate-matrix.outputs.slices }}
       gate_timeout_minutes: ${{ steps.gate-matrix.outputs.timeout_minutes }}
@@ -113,13 +114,18 @@ jobs:
       - name: Emit run manifest (ALL periodic tests minus reasoned excludes)
         env:
           EVALS_ALL: "1"
-        run: EVALS_TIER=periodic bun --no-install run scripts/test-paid-shards.ts --tier periodic --emit-plan /tmp/paid-plan/manifest.json --slice-budget 540 --jobs 2 --max-parallel 25
+        run: EVALS_TIER=periodic bun --no-install run scripts/test-paid-shards.ts --tier periodic --emit-plan /tmp/paid-plan/manifest.json --slice-budget 540 --jobs 2 --max-parallel 26
 
+      # Codex-only slices run on the host-run eval-codex-slices job; the
+      # container executor runs every other slice.
       - name: Derive the periodic executor matrix from the plan
         id: periodic-matrix
         run: |
-          echo "slices=$(jq -c '[range(1; .sliceCount + 1)]' /tmp/paid-plan/manifest.json)" >> "$GITHUB_OUTPUT"
-          echo "timeout_minutes=$(jq -e '.plan.ciTimeoutMinutes' /tmp/paid-plan/manifest.json)" >> "$GITHUB_OUTPUT"
+          {
+            echo "slices=$(jq -c '[range(1; .sliceCount + 1)] - .plan.codexSlices' /tmp/paid-plan/manifest.json)"
+            echo "codex_slices=$(jq -c '.plan.codexSlices' /tmp/paid-plan/manifest.json)"
+            echo "timeout_minutes=$(jq -e '.plan.ciTimeoutMinutes' /tmp/paid-plan/manifest.json)"
+          } >> "$GITHUB_OUTPUT"
 
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
@@ -166,7 +172,7 @@ jobs:
       fail-fast: false
       # Every planned slice starts at once; test/evals-workflow-wiring.test.ts
       # fails when the live plan outgrows this cap.
-      max-parallel: 25
+      max-parallel: 26
       matrix:
         slice: ${{ fromJSON(needs.plan-slices.outputs.periodic_slices) }}
     steps:
@@ -280,6 +286,135 @@ jobs:
           if-no-files-found: ignore
           retention-days: 30
 
+  # Codex shards on the host. Codex runs every shell command inside a
+  # bubblewrap sandbox, which needs an unprivileged user namespace. A job
+  # container cannot get one: Docker's default seccomp and AppArmor profiles
+  # block it, and Ubuntu 24.04 hosts set
+  # kernel.apparmor_restrict_unprivileged_userns=1, which no container option
+  # can change. This job runs on the runner VM itself (ephemeral, one job),
+  # lifts that host restriction, and runs the same CI image with both
+  # profiles unconfined. Only the planner's Codex slices run here
+  # (scripts/lib/paid-plan.ts codexSlicesOf); slice artifacts use the same
+  # names as eval-slices, so the report reconciles one manifest.
+  eval-codex-slices:
+    runs-on: ubicloud-standard-8
+    needs: [build-image, plan-slices]
+    if: ${{ needs.plan-slices.outputs.periodic_codex_slices != '[]' }}
+    env:
+      EVALS_RUN_ID: ci-${{ github.run_id }}-${{ github.run_attempt }}-eval-slices-${{ matrix.slice }}
+    timeout-minutes: ${{ fromJSON(needs.plan-slices.outputs.periodic_timeout_minutes) }}
+    permissions:
+      contents: read
+      packages: read
+    strategy:
+      fail-fast: false
+      max-parallel: 26
+      matrix:
+        slice: ${{ fromJSON(needs.plan-slices.outputs.periodic_codex_slices) }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: paid-plan
+          path: ${{ runner.temp }}/paid-plan
+
+      - name: Let Codex's bubblewrap sandbox create user namespaces
+        run: |
+          if [ -e /proc/sys/kernel/apparmor_restrict_unprivileged_userns ]; then
+            sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+          fi
+
+      - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # The same steps as eval-slices (bun temp, deps, build, Codex login,
+      # slice run) inside the CI image. The container's home is a fresh
+      # runner-temp directory, so logs and captures upload from there.
+      - name: Run periodic Codex slice ${{ matrix.slice }}
+        shell: bash
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+          EVAL_IMAGE: ${{ needs.build-image.outputs.image-tag }}
+          SLICE: ${{ matrix.slice }}
+          EVALS_JOBS: "2"
+        run: |
+          mkdir -p "$RUNNER_TEMP/eval-home" "$RUNNER_TEMP/paid-slice-results"
+          docker run --rm --user "$(id -u):$(id -g)" \
+            --security-opt seccomp=unconfined --security-opt apparmor=unconfined \
+            -e HOME=/home/runner -e ANTHROPIC_API_KEY -e OPENAI_API_KEY -e GEMINI_API_KEY -e SLICE -e EVALS_JOBS \
+            -e EVALS_RUN_ID -e EVALS_PROFILE -e EVALS_FRESH -e EVALS_CACHE_PURPOSE -e CI -e GITHUB_ACTIONS \
+            -e GITHUB_RUN_ID -e GITHUB_RUN_ATTEMPT -e GITHUB_SHA -e GITHUB_REF -e GITHUB_REF_NAME -e GITHUB_REPOSITORY \
+            -e GITHUB_EVENT_NAME -e GITHUB_BASE_REF -e GITHUB_HEAD_REF \
+            -e PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers -e EVALS_CONCURRENCY=2 -e GSTACK_EVAL_DIR=/tmp/paid-slice-results \
+            -v "$GITHUB_WORKSPACE:/workspace/gstack" -w /workspace/gstack \
+            -v "$RUNNER_TEMP/eval-home:/home/runner" \
+            -v "$RUNNER_TEMP/paid-plan:/tmp/paid-plan:ro" \
+            -v "$RUNNER_TEMP/paid-slice-results:/tmp/paid-slice-results" \
+            "$EVAL_IMAGE" bash -c '
+            set -euo pipefail
+            mkdir -p "$HOME/.cache/bun"
+            export BUN_INSTALL_CACHE_DIR="$HOME/.cache/bun" BUN_TMPDIR="$HOME/.cache/bun" TMPDIR="$HOME/.cache"
+            if diff -q /opt/node_modules_cache/.bun.lock bun.lock >/dev/null 2>&1; then
+              rm -rf node_modules && cp -r /opt/node_modules_cache node_modules
+            else
+              bun install --frozen-lockfile
+            fi
+            bun run build
+            codex="${GSTACK_CI_CODEX_BIN_DIR:?}/codex"
+            export CODEX_HOME="$HOME/.gstack-ci-codex"
+            mkdir -p "$CODEX_HOME"
+            if [ -n "${OPENAI_API_KEY:-}" ]; then
+              printenv OPENAI_API_KEY | "$codex" login --with-api-key
+              "$codex" login status >/dev/null 2>&1
+            else
+              echo "::warning::OPENAI_API_KEY is unavailable; Codex eval cases cannot authenticate and will fail."
+            fi
+            export GSTACK_CI_CODEX_HOME="$CODEX_HOME"
+            unset CODEX_HOME
+            EVALS_TIER=periodic bun run scripts/test-paid-shards.ts --tier periodic --plan /tmp/paid-plan/manifest.json --slice "$SLICE"
+            '
+
+      - name: Upload slice results
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: paid-slice-${{ matrix.slice }}-a${{ github.run_attempt }}
+          path: ${{ runner.temp }}/paid-slice-results
+          retention-days: 90
+
+      - name: Upload native capture evidence
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: native-captures-${{ env.EVALS_RUN_ID }}
+          include-hidden-files: true
+          path: |
+            ${{ runner.temp }}/eval-home/.gstack/projects/*/e2e-runs
+            ${{ runner.temp }}/eval-home/.gstack/projects/*/evals/qa-callers
+            ${{ runner.temp }}/eval-home/.gstack-dev/e2e-runs
+            ${{ runner.temp }}/eval-home/.gstack-dev/evals/qa-callers
+          if-no-files-found: ignore
+          retention-days: 90
+
+      - name: Upload shard logs
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: paid-logs-slice-${{ matrix.slice }}-a${{ github.run_attempt }}
+          include-hidden-files: true
+          path: ${{ runner.temp }}/eval-home/.cache/gstack-paid-shard-*.log
+          if-no-files-found: ignore
+          retention-days: 30
+
   # Weekly EVALS_ALL gate-tier census: PR lanes are diff-billed, so without
   # this the full gate census might never execute anywhere and the selector's
   # blind spots rot invisibly. Census health, not selector correctness —
@@ -389,7 +524,7 @@ jobs:
 
   report:
     runs-on: ubicloud-standard-2
-    needs: [plan-slices, eval-slices, gate-census]
+    needs: [plan-slices, eval-slices, eval-codex-slices, gate-census]
     # !cancelled(): the report must run (and FAIL) when an executor died — a
     # missing slice artifact reading as green is the class this lane kills —
     # but a cancelled run stops here.
@@ -521,7 +656,7 @@ jobs:
       # issue (never a new issue per week) with the headline and failure block
       # of both lanes, and close it on the next green run.
       - name: Upsert tracking issue on failure
-        if: always() && (steps.reconcile.outputs.exit != '0' || steps.gate-reconcile.outputs.exit != '0' || steps.pass-rates.outputs.exit != '0' || needs.eval-slices.result != 'success' || needs.gate-census.result != 'success')
+        if: always() && (steps.reconcile.outputs.exit != '0' || steps.gate-reconcile.outputs.exit != '0' || steps.pass-rates.outputs.exit != '0' || needs.eval-slices.result != 'success' || !contains(fromJSON('["success","skipped"]'), needs.eval-codex-slices.result) || needs.gate-census.result != 'success')
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           REDISPATCH: ${{ steps.verdict.outputs.redispatch }}
@@ -536,7 +671,7 @@ jobs:
             if [ -n "$REDISPATCH_OF" ]; then echo; echo "This run is the one INFRA/INCOMPLETE re-dispatch of run ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${REDISPATCH_OF}; both runs are reported."; fi
             if [ "$REDISPATCH" = "true" ]; then echo; echo "Every red verdict is machine-classified INFRA/INCOMPLETE: re-dispatching once as a new run (EVAL_POLICY.infraRedispatch). This run stays red and reported."; fi
             echo
-            echo "- periodic reconciliation exit: ${{ steps.reconcile.outputs.exit }} (slices job: ${{ needs.eval-slices.result }})"
+            echo "- periodic reconciliation exit: ${{ steps.reconcile.outputs.exit }} (slices job: ${{ needs.eval-slices.result }}, Codex slices job: ${{ needs.eval-codex-slices.result }})"
             echo "- gate census reconciliation exit: ${{ steps.gate-reconcile.outputs.exit }} (census job: ${{ needs.gate-census.result }})"
             echo "- pass-rate history gate exit: ${{ steps.pass-rates.outputs.exit }}"
             echo
@@ -573,7 +708,7 @@ jobs:
           fi
 
       - name: Close the tracking issue on a green run
-        if: always() && steps.reconcile.outputs.exit == '0' && steps.gate-reconcile.outputs.exit == '0' && steps.pass-rates.outputs.exit == '0' && needs.eval-slices.result == 'success' && needs.gate-census.result == 'success'
+        if: always() && steps.reconcile.outputs.exit == '0' && steps.gate-reconcile.outputs.exit == '0' && steps.pass-rates.outputs.exit == '0' && needs.eval-slices.result == 'success' && contains(fromJSON('["success","skipped"]'), needs.eval-codex-slices.result) && needs.gate-census.result == 'success'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           REDISPATCH_OF: ${{ inputs.redispatch_of }}
@@ -588,7 +723,7 @@ jobs:
           fi
 
       - name: Fail the workflow when reconciliation failed
-        if: always() && (steps.reconcile.outputs.exit != '0' || steps.gate-reconcile.outputs.exit != '0' || steps.pass-rates.outputs.exit != '0' || needs.eval-slices.result != 'success' || needs.gate-census.result != 'success')
+        if: always() && (steps.reconcile.outputs.exit != '0' || steps.gate-reconcile.outputs.exit != '0' || steps.pass-rates.outputs.exit != '0' || needs.eval-slices.result != 'success' || !contains(fromJSON('["success","skipped"]'), needs.eval-codex-slices.result) || needs.gate-census.result != 'success')
         run: exit 1
 
   # The one INFRA/INCOMPLETE re-dispatch (UC-E1). Its own job so the report

AGENTS.md

@@ -289,5 +289,7 @@ bun run skill:check      # health dashboard for all skills
 - Browse daemon HTTP routes are entries in `browse/src/routes/table.ts` (its header shows how to add one); never dispatch on `url.pathname` in `server.ts`.
 - Both test lanes run shards through `scripts/lib/shard-engine.ts`; the free and paid runners hold lane policy only. PTY harness code lives in `test/helpers/pty/*` behind the `claude-pty-runner.ts` barrel.
 - Outside-voice failure prose (auth, timeout, empty, fallback) comes only from `outsideVoiceFailurePolicy()` in `scripts/resolvers/outside-voice.ts`.
+- Every env-var-host fence starts with the shared prelude from `scripts/resolvers/runtime-root.ts` (inserted by its post-render pass); never resolve gstack's root by hand in a template.
+- Every Codex run's verdict goes through `lib/outside-review-result.ts`; its reason codes live in `lib/gate-outcomes.ts`, each with a `docs/troubleshooting.md` anchor.
 - `test/module-size-ratchet.test.ts` keeps refactored owner modules at or under 800 lines (150 per function) and residual files from growing.
 - The `claude` CLI binary resolves via `lib/claude-bin.ts` (re-exported from `browse/src/claude-bin.ts` for browse internals; `Bun.which()` + `GSTACK_CLAUDE_BIN` override). Set `GSTACK_CLAUDE_BIN=wsl` plus `GSTACK_CLAUDE_BIN_ARGS='["claude"]'` to run Claude through WSL on Windows.

BROWSER.md

@@ -530,7 +530,7 @@ from `snapshot`, or `@c` refs from `snapshot -C`. Full table:
 | `fill <sel> <val>` | Fill input |
 | `select <sel> <val>` | Select dropdown option (value, label, or visible text) |
 | `hover <sel>` | Hover element |
-| `type <text>` | Type into focused element |
+| `type [--selector <sel>] [--] <text>` | Type into the focused element, or into `<sel>` with `--selector`; put text that starts with `--` after `--`. Bare `type` hints when its first word looks like a selector |
 | `press <key>` | Playwright keyboard key (case-sensitive: Enter, Tab, ArrowUp, Shift+Enter, Control+A, ...) |
 | `scroll [sel\|@ref]` | Scroll element into view, or jump to page bottom if no selector |
 | `viewport [<WxH>] [--scale <n>]` | Set viewport size + optional `deviceScaleFactor` 1-3 (retina screenshots) |
@@ -647,6 +647,8 @@ Storage stays intact by default. With explicit approval on a Chromium target, `-
 | `status` | Daemon health + mode (headless / headed / cdp) |
 | `stop` | Shut down daemon (succeeds even if the daemon already died — never boots one just to stop it; reaps a surviving recorded headless Chromium after identity checks) |
 | `restart` | Restart daemon |
+| `profiles [list]` | List the per-project headed Chromium profiles: size, last use, and which browser holds each |
+| `profiles prune [--days N]` | Remove headed profiles idle for N days (default 30); never one a live browser holds |
 | `connect` | Launch headed GStack Browser with Side Panel extension |
 | `disconnect` | Close headed Chrome, return to headless |
 | `focus [@ref]` | Bring headed Chrome to foreground (macOS); `@ref` also scrolls into view |
@@ -886,6 +888,14 @@ with your tabs and bookmarks stays untouched.
 - **Demos** where you're sharing your screen
 - **Pair-agent** sessions (the remote agent drives your local browser)
 
+Headed browse keeps one Chromium profile per project, at
+`<project>/.gstack/chromium-profile` (`CHROMIUM_PROFILE` still wins). The first
+headed start copies your logins from `~/.gstack/chromium-profile` when no browser
+is using it, and otherwise starts fresh and prints how to import. If a live
+browser already holds the project's profile, browse names it and stops instead
+of killing it. `browse profiles` lists the profiles; `browse profiles prune
+--days 30` removes idle ones.
+
 ### Aside and third-party drives (v1.72.0.0+)
 
 For third-party website moments (registering an API key, configuring a vendor

CHANGELOG.md

@@ -1,5 +1,111 @@
 # Changelog
 
+## [1.91.19.0] - 2026-10-03
+
+**A check that did not run now says so, and memory stops losing transcripts.**
+**Codex and the other non-Claude hosts find gstack in every step of every skill.**
+
+This release closes the severe bugs left in the tracker. Two promises lead. First, nothing is silently lost: memory ingest marks a transcript saved only after gbrain confirms it landed, and learnings that could not be written say so. Second, no false all-clear: a Codex review whose sandbox could not start, a retired Codex model, a design binary killed at launch, and a learnings search with no Bun all used to read as "ready", "pass" or "no results". Each now prints `not run` or `unavailable` with the reason and the fix command, and every one of those messages has a section in the new [docs/troubleshooting.md](docs/troubleshooting.md).
+
+### The numbers that matter
+
+Measured on this release's tests against v1.91.16.0's code (each regression test was run on both; the counts come from those runs and from `bun run gen:skill-docs --host all`).
+
+| Check | v1.91.16.0 | v1.91.19.0 |
+|---|---|---|
+| Codex review in a container with no user namespaces | gate `pass` on "no findings" | `unavailable`, missing coverage |
+| Structured outside review with a `[P0]` finding | gate `pass` | gate `fail` |
+| Generated bash blocks on env-var hosts that use a gstack path without finding gstack (`test/env-host-fence-conformance.test.ts`) | hundreds | 0 |
+| Codex `/ship` SKILL.md | 202-241 KB, ~57K tokens | carved, ~20K tokens |
+| Redaction warnings on one rendered `/diagram` (SVG + .excalidraw) | 115 | 0 |
+| A transcript gbrain skipped during import | stamped as saved | retried until gbrain has it |
+
+The first two rows are the ones to care about: a review that read nothing, or found a P0, used to let /ship through.
+
+### What changes for you
+
+- **Gates tell the truth.** Outside reviews go through one classifier that reads the text, stderr and exit status. Codex reviews that could not run print `Codex outside review unavailable: <reason>` with the fix, and /ship and /review show them as missing coverage, never as passed.
+- **Memory keeps what you gave it.** Memory ingest checks that each page landed before marking it saved, retries pages gbrain skipped, and sets aside (and names) one page that keeps breaking a batch. After upgrading, a bounded catch-up per `/sync-gbrain` re-imports transcripts older versions lost (`gstack-memory-ingest --reconcile --dry-run` previews it). Transcripts import into a private gbrain source per repository.
+- **Codex, Factory, OpenCode, Cursor, Copilot and Kiro** see the gstack router (setup installs real copies, which Codex requires), get the design and make-pdf binaries, and every skill block finds gstack on its own, honoring `CODEX_HOME` and an exported `GSTACK_ROOT`. `./setup --status` says whether each install's router is a real file and its section links resolve.
+- **Pushes stop being blocked by false positives:** diagram coordinates, `session = requests.Session()`, `CLAUDE.local.md`, four-part version numbers and `postgres:postgres@localhost`. Real secrets still block.
+- **Windows:** /freeze, /guard and /investigate stop denying every edit, the generators no longer crash with EEXIST, the node-server bundle builds, and the /cso helper builds with the current Windows SDK.
+- **/ship in a repo without a VERSION file** ships without a version change instead of stopping.
+
+### Behavior changes you may notice
+
+- **Codex reviews in containers say "unavailable" instead of passing.** Fix: enable unprivileged user namespaces, or in a container you trust `export GSTACK_CODEX_NO_SANDBOX=1`.
+- **The structured outside-review gate fails on P0 findings**, not only P1. An untagged structured review is `OUTSIDE_STATUS: unverified` (missing coverage).
+- **`CODEX_MODE: unverified`** replaces `ready` when the model check times out; the review still runs and its own result is checked.
+- **The first automatic Codex review on a machine prints a one-time notice** naming the provider and which login or key pays. Reviews stay on; `gstack-config set codex_reviews disabled` turns them off.
+- **/ship without a version source ships without a version change:** no bump, no CHANGELOG version header, no `vX.Y.Z` title prefix. To version releases, create `VERSION` or `echo package.json > .gstack/version-path`. A pinned version file that is missing or malformed stops /ship with its path.
+- **The plan completion audit says `not run`** instead of auditing your PR against the newest unrelated plan. Bind one with a `Plan: <path>` line in the PR body, or run /autoplan.
+- **Learnings and timeline lookups report a missing Bun** (exit 127 with the fix) and skills print `LEARNINGS: unavailable (<reason>)` instead of an empty list.
+- **Design skills say `DESIGN_NOT_AVAILABLE: <path> --version exited <code>`** when the design binary cannot start, instead of claiming it is ready. Fix: `cd <gstack checkout> && ./setup`.
+- **`/sync-gbrain --dream` (and `--full`) runs only the call-graph phase.** If your gbrain cannot, it skips and says so; run `gbrain dream --source <id>` yourself for the full ~35-minute cycle.
+- **`gstack-memory-ingest --no-write` is a true dry run** and no longer records pages as saved.
+- **Transcripts with no repository stay on this machine** when your brain is remote. Staged pages carry a `gstack_content_sha256` frontmatter field.
+- **Disabled skills leave the router** (`gstack-config set disabled_skills ...` updates it in the same command).
+- **`browse type --selector <sel> <text>`** types into an element. Bare `browse type` still types into the focused element and hints when the first word looks like a selector. Text starting with `--` goes after `--`.
+- **Headed browse keeps one profile per project** (`<project>/.gstack/chromium-profile`). First use copies your logins from `~/.gstack/chromium-profile` when no browser is using it. `browse profiles` lists them; `browse profiles prune --days 30` removes idle ones. If a live browser holds the profile, browse names it and stops instead of killing it.
+- **A redirect or link to a link-local or metadata address resets the tab to `about:blank`** and the command fails with the reason.
+- **`BROWSE_EXTENSION_ID` is ignored;** forks use `gstack-config set browse_extension_id <id>`. `BROWSE_EXTENSIONS_DIR` runs headless with no window.
+- **`$D` (design) no longer picks up `OPENAI_API_KEY` from a project's `.env`.** Export it in your shell or use `~/.gstack/openai.json`.
+- **A database URL with the default `postgres`/`postgres` login still blocks a push on any host but `localhost` or `127.0.0.1`,** including a compose service name like `@db`. Use `localhost`, or read the URL from an env var.
+- **Auto-update (team mode) no longer says "just upgraded" when setup failed.** It retries after 1h, 6h and 24h, and each session start prints one line naming what did not finish and the fix.
+- **Hand edits to installed router copies are saved to `~/.gstack/backups/skill-copies/`, then overwritten.** Setup prints where.
+- **In Conductor, setup no longer installs the AskUserQuestion preference hook** and removes one it added. To keep it: `gstack-config set plan_tune_hooks yes`, then `./setup`.
+- **Required team mode also blocks Copilot CLI's skill tool.** Re-run `gstack-team-init required` to upgrade the project hook.
+- **`gstack-qa-evidence capture` prints a `revalidate` list after your inputs change**, naming the probes to rerun on current inputs before `materialize`; `materialize` says its verdict is final for that report root, so rerun the listed probes first.
+- **/gstack-upgrade asks you to paste the absolute path Step 2 prints**; every later step checks it is inside gstack's checkout before running git.
+- **/ship's documentation gate snapshots its inputs in one call.** `gstack-docs-candidate snapshot` records the audit candidate (base, HEAD, index, changed and new paths, content hashes) and `compare` reports what changed after the child returns.
+- **Two setups writing settings.json at once both land.** A writer whose lock attempt raced a holder releasing it used to skip its hook change (exit 5); it now retries once and only reports `cannot create lock` when the lock directory truly cannot be created.
+- **/plan-ceo-review prints its mode handoff** by running `gstack-ceo-mode-handoff` right after the mode is chosen (by you or by a saved preference), so the selected mode and approved decisions always appear before the review continues.
+- **Browser setup names the platform when Aside is absent:** the probe prints `NEEDS_ASIDE: <OS>` (was `NEEDS_ASIDE`), and the macOS-only download pitch trusts that line instead of re-checking the OS. `GSTACK_PLATFORM` overrides it for tests and unusual hosts; set it in your shell, never a project `.env`.
+
+### Security
+
+- A repository's `.env` or `bunfig.toml` can no longer change gstack's browser. Compiled binaries and the browse daemons ignore them, so a project cannot turn off Chromium's sandbox (`GSTACK_CHROMIUM_NO_SANDBOX`) or run code through a bunfig `preload`. This needs Bun 1.3.3 or later; gstack now requires Bun 1.4.0 (`engines.bun`), the version CI runs.
+- The browse sidebar terminal accepts connections only from the gstack extension.
+- Browse refuses link-local and cloud-metadata addresses (169.254.0.0/16 including container credential endpoints, 100.100.100.200, fe80::/10, fc00::/7) in every numeric and IPv6-mapped spelling, including after redirects and page-driven navigation. Connection-time DNS rebinding is not covered.
+- Screenshot, PDF and scrape output paths are checked the way the OS resolves them, so a symlink cannot redirect a write outside the allowed folders.
+- `GSTACK_CODEX_NO_SANDBOX` is read only from your shell environment (exactly `1`), and every use prints a warning.
+- The iOS QA daemon bounds each device response (one 30-second deadline for the whole response, 64 MiB cap) and never replays a tap or write whose response was lost.
+
+### Upgrade
+
+- **Claude Code:** run `/gstack-upgrade`, then start a new session.
+- **Codex and the other env-var hosts (Factory, OpenCode, Cursor, Copilot, Kiro):** find your checkout with `./setup --status` (the `source` column), then run `cd <source> && git pull && ./setup --host <host>`, and start a new session.
+- Then `./setup --status` should show each install's router as a real file with every section link resolving.
+
+### Itemized changes
+
+#### Fixed
+- **Memory and gbrain.** Ingest stamped pages gbrain skipped or never stored (#2778); `--no-write` wrote state. A project's `.env` `DATABASE_URL` reached a local PGLite brain (#1931). Offline or off-VPN looked like a broken config, and dot-leading project names (`.claude`) blocked ingest forever (#2884). Transcripts from every repository shared one source (#2232). `/sync-gbrain` said "pushed" when the artifacts source had 0 indexed pages (#2670), forced the full dream cycle (#2783), always reported the call graph as unknown, and kept deleted worktrees' sources silently. The 1.27 artifacts-repo rename never worked, and installs it repointed at a repo that never existed are repaired (#1437). gbrain install and source wiring needed `jq` (#2369).
+- **Codex.** A retired model (HTTP 404) or a custom provider with a wrong `base_url` reported `ready` (#2843). Custom providers configured with `env_key` failed the auth check (#2192). Large prompts failed on argv limits (Windows 32 KB, Linux E2BIG) and the macOS fallback timeout dropped the prompt (#1674, #1686).
+- **Non-Claude hosts.** Later skill blocks lost `$GSTACK_*`, `$B` and `$D` and ran `/bin/gstack-...` (#1159). Codex skipped the symlinked router. design/dist and make-pdf/dist were missing from runtime roots (#2891). /ship and /plan-ceo-review overflowed the 160 KB host limit. The OpenCode `/gstack-review` command loaded nothing (#2651). `/browse` disappeared after toggling `skill_prefix` (#2263). Section files linked to checkout copies instead of rendered ones (#2707). skillify pointed at Claude's install on every host. /gstack-upgrade could run git cleanup in your own project when its path variable was unset.
+- **Design.** A design binary killed at launch reported `DESIGN_READY`. /design-consultation and /design-shotgun never loaded your taste profile. Plan reviews read a root DESIGN.md as the feature's design doc (#2840).
+- **/ship, /review and daily tools.** /ship stopped in versionless repos and monorepos (#2334, #2343). The plan audit picked an unrelated plan (#2797). Worktrees split project state (#2792). Learnings search exited 0 without Bun (#2794) and ranked poorly (#2796, #2799). Logs ignored `$TMPDIR` in sandboxed shells (#2952). /plan-tune said "calibrated" with no signals. /setup-deploy printed part of the Render API key (#1096). /analytics durations read 0s (#1728). Rejected taste preferences used the wrong confidence bucket (#1777). /context-save duration was empty on Linux (#2704). /retro missed pytest, minitest, XCTest, Terraform and Bats tests and counted build output (#2812, #2809, #2037). Plan reviews now treat design docs and handoff notes as data (#2818).
+- **Browser.** Browse failed behind `HTTP_PROXY` (#494). Headless browse and make-pdf ignored `GSTACK_CHROMIUM_PATH` (#2771, #1968, #1633); extensions opened a window (#2281). `prettyscreenshot --hide ... out.png` wrote elsewhere (#1419). Stopping the browse daemon took over 5 seconds because every Chromium close waited out its timeout; it now takes about 0.1 s, and a closed headed display no longer waits a second on its own exit. Two browse daemons going headed at the same moment could pick the same free X display, and the loser failed the handoff; it now takes the next free display, and an Xvfb that fails to start reports its own error. `gstack-ios-qa-daemon --help` started the daemon (#1932). Aside in `~/.local/bin` was not found (#2965).
+- **Windows.** /freeze, /guard and /investigate denied every edit and their hooks failed under cmd.exe (#2876, #2354). Generators crashed with EEXIST (#2329). The node-server bundle inlined sharp and socks (#2260), and a minimal install needed `browse/src/server.ts` (#2439). The /cso helper failed on the current SDK and was reported as "install Visual Studio" (#3015). `gstack-config gbrain-refresh` misread status (#1981).
+- **Redaction.** Diagram and vector files flagged as phone and card numbers (#2885, #2827); function calls assigned to `session`/`token` (#2899); `<name>.local.<ext>` config filenames (#2962); four-part versions (#2784); `postgres:postgres@localhost` (#2913).
+- **Plan reviews.** /plan-eng-review writes its QA test plan even while some test choices are still pending, and its findings enter only through Scope Challenge C's saves. /qa-only's test value card no longer points at /qa's record step. /plan-ceo-review says what its closing cleanup does (old CEO plans are archived only with your approval).
+- **Setup.** Auto-update wrote "just upgraded" after a failed setup and never retried. Conductor got the AskUserQuestion preference hook (#2208, #2207, #2719); office-hours asks its questions as `Q1...` prose there (#2729). Team mode's matcher missed Copilot's `skill` tool (#2229). A failed arm64 re-sign left a broken binary.
+
+#### Added
+- `docs/troubleshooting.md`: every gate message, what it means, what is kept, and the command that fixes it.
+- `gstack-memory-ingest --reconcile [--dry-run] [--limit N]` and `--request-reconcile`; `gstack-gbrain-sync --prune-gone-worktrees [--dry-run]`; `gstack-slug --adopt-legacy --from <slug>` / `--dismiss <slug>`.
+- `browse type --selector`, `browse profiles [list|prune --days N]`, `design --version`, `gstack-config set browse_extension_id <id>`.
+- For scripts: `bun lib/outside-review-result.ts --verdict <gate> <file>` prints `VERDICT: clean|findings|unverified|unavailable` (exit 0/3/4/1); the two-argument form is unchanged.
+
+#### For contributors
+- New invariants with free tests: gate outcomes in `lib/gate-outcomes.ts` with a troubleshooting anchor per reason code; a fresh-shell conformance test and a quote-aware bash lint over every generated block on every env-var host; a per-host 160,000-byte SKILL.md ceiling.
+- Eval children no longer receive credential env vars that carry a suffix (`GITHUB_TOKEN_1`, `GITHUB_APP_PRIVATE_KEY_BASE64`); admit one explicitly with `extraAllow` (#2949). Chunked large-push coverage for the pre-push guard (#2915).
+- The test typecheck ratchet ignores the order tsc prints an object type's members in.
+- The weekly eval report counts only cases that ran: tests deselected for another tier or case shard are listed by reason with no credit, every result is attributed to its case (0 unattributed, was 72), and no PR-lane eval shard runs over 10 minutes (the deploy eval is split per case).
+- Codex evals run on their own CI job where Codex's sandbox can start, and pass only when Codex completed a command; a review whose sandbox failed now fails instead of passing. The `/codex review` eval passes only when Codex actually reviewed the diff. The AUQ matrix checks the `(recommended)` marker on option labels, where the auto-decide hook reads it. The `/plan-eng-review` QA test-plan eval now runs the real interactive review instead of a shortcut prompt that skipped the workflow: a periodic checkpoint resumes it at Test review from a recorded Scope Challenge, and the full fresh run is a non-blocking marathon case.
+
+Contributed by @CermakM (#2843), @Haijie-Lee (#2192), @SomSamantray (#2965), @Vaughan-g-aus (#2329), @BharadwajMittapelli (#2729), @maxpetrusenkoagent (#1931, #1932, #1981), @Infiniteyieldai (#2884), @afshaker (#2778), @time-attack (#2232, #2229), @jzeisweiss (#2670), @liutiming (#2783), @agile-operators (#1437), @benjaminberes-bp (#2369), @lewispeel (#2885), @Yugz29 (#2899), @fcmerle (#2962), @cdecook23 (#2784), @mb1810 (#2913), @ntdatt812 (#2949), @pneumorea-ai (#2915), @gabrielrondon (#2811), @kevingrasso32 (#2876), @xwang4-svg (#2354), @DizzyWesterwald (#2936), @oli548 (#2771), @shofel (#1968), @ryanlaiwy (#1633), @yinanli1917-cloud (#2281), @Spooks444 (#2260), @punksterlabs (#2439), @himiaocc (#2492), @jbetala7 (#1419, #1777), @mamedov (#2891), @Lockyer228 (#2651), @topcoder1 (#2263), @jonahberg (#2707), @AlinValentin7 (#3015), @philhie (#2208), @Alchemist-DevAI (#2334), @merit-blake (#2343), @day-of-davon (#2952), @loulanyue (#2797, #2792, #2794, #2796), @Bit0ps (#2840), @szsunyuan (#2799), @frosimanuel (#2818), @JiayuuWang (#1096), @RyanAlberts (#1728), @exGeni (#2704), @Jino00 (#2812), @snig-17 (#2809) and @SholtoMc (#2037).
+
 ## [1.91.18.0] - 2026-10-03
 
 **Transcript consent can cover only new sessions or only chosen repos, and Claude Code users can opt into a model-tuned skill overlay.**

CONTRIBUTING.md

@@ -410,7 +410,7 @@ operator `~/.claude` config, MCP servers (gbrain, Conductor), skills, `~/.gstack
 decision logs, and `CONDUCTOR_*` env never leak into the child. The `GITHUB_`
 and `EVALS_` prefix rules preserve CI metadata but reject credential-shaped
 names such as `GITHUB_TOKEN`, `GITHUB_PERSONAL_ACCESS_TOKEN`, and
-`GITHUB_APP_PRIVATE_KEY`. Named provider auth, runner `extraAllow` entries, and
+`GITHUB_APP_PRIVATE_KEY`. The screen reads every underscore-separated segment, so a trailing qualifier does not carry a name past it (`GITHUB_APP_PRIVATE_KEY_BASE64`, `GITHUB_TOKEN_1`), while a segment that merely contains a credential word stays metadata (`GITHUB_PATH`, `GITHUB_TOKENIZER`). Named provider auth, runner `extraAllow` entries, and
 per-test overrides are deliberate exceptions; a name-based rule cannot identify
 a secret assigned to an arbitrary metadata name. This keeps local eval signal
 aligned with CI instead of disagreeing for reasons unrelated to the code under

README.md

@@ -625,6 +625,7 @@ Other references: [docs/gbrain-sync.md](docs/gbrain-sync.md) (sync-specific guid
 | [Browser](BROWSER.md) | How gstack drives Aside first (the contract, the cookbook, rendering, research), when the fallback engine kicks in, and the fallback's full `$B` command reference |
 | [Contributing](CONTRIBUTING.md) | Dev setup, testing, contributor mode, and dev mode |
 | [Memorable recall bridge](docs/memorable-workflow-memory.md) | Opt-in third-party workflow memory through gstack: two consents, what gstack hands over and can attest, removal, troubleshooting |
+| [Troubleshooting](docs/troubleshooting.md) | Every `not run` / `unavailable` message, what it means, and the fix |
 | [Changelog](CHANGELOG.md) | What's new in every version |
 
 ## Privacy & Telemetry
@@ -645,6 +646,10 @@ Data is stored in [Supabase](https://supabase.com) (open source Firebase alterna
 
 ## Troubleshooting
 
+**A message says `not run`, `unavailable` or names a fix?** Look it up in
+[docs/troubleshooting.md](docs/troubleshooting.md): every gate message gstack
+prints, what it means, what was kept, and the command that fixes it.
+
 **Skill not showing up?** Run `./setup --status` from your gstack checkout. It
 prints every install (host, scope, version, skills directory, source checkout)
 and, for a `stale`, `missing` or `unregistered` row, the exact command that fixes
@@ -653,13 +658,19 @@ it. The usual fix is to re-run setup from that row's source for that host, e.g.
 A project install lives in the project's `.claude/skills/gstack` or
 `.agents/skills/gstack`; run its `setup` from inside the project.
 
-**`/browse` (or `/qa`, `/design-review`) says `NEEDS_ASIDE` or `ASIDE_NOT_RUNNING`?** That's the probe telling you it's about to use the fallback browser. Want Aside? Open the app and sign in — `aside --version` should print a version and `aside repl 'console.log("ok")'` should print `ok` — then re-run. gstack never installs it for you. Want the fallback on purpose while Aside is open? `GSTACK_SKIP_ASIDE=1` makes every skill, the renderer, and `./setup` treat Aside as absent.
+**`/browse` (or `/qa`, `/design-review`) says `NEEDS_ASIDE` or `ASIDE_NOT_RUNNING`?** That's the probe telling you it's about to use the fallback browser. Want Aside? Open the app and sign in — `aside --version` should print a version and `aside repl 'console.log("ok")'` should print `ok` — then re-run. gstack never installs it for you. Want the fallback on purpose while Aside is open? `GSTACK_SKIP_ASIDE=1` makes every skill, the renderer, and `./setup` treat Aside as absent. When Aside is absent the probe prints `NEEDS_ASIDE: <OS>` and skills trust that line for the macOS-only download pitch; `GSTACK_PLATFORM` overrides the OS it names, for tests and unusual hosts (set it in your shell — gstack never reads it from a project `.env`).
 
 **`/browse` fails on the fallback browser?** `cd ~/.claude/skills/gstack && bun install && bun run build`
 
 **`/make-pdf` or `/diagram` can't render?** Same two paths: with Aside open they print through Aside (`bun run ~/.claude/skills/gstack/bin/gstack-render.ts some.html --screenshot /tmp/out.png` tests it directly, and its first line, `ENGINE=aside` or `ENGINE=browse`, names the browser that actually rendered); without it they use the bundled browser, so `bun run build` is the fix.
 
-**Stale install?** Run `/gstack-upgrade` — or set `auto_upgrade: true` in `~/.gstack/config.yaml`
+**Stale install?** Run `/gstack-upgrade` — or set `auto_upgrade: true` in `~/.gstack/config.yaml`.
+On Codex and the other non-Claude hosts, upgrade from a terminal: find the
+checkout in the `source` column of `./setup --status`, then
+`cd <source> && git pull && ./setup --host <host>`, and start a new session.
+
+**Typing into a specific field with the fallback browser?** `browse type --selector '<css>' <text>`
+types into that element; bare `browse type <text>` types into whatever has focus.
 
 **State in the wrong place, or a setting that won't stick?** `~/.claude/skills/gstack/bin/gstack-paths --explain` shows which directory gstack uses for its state and why. See [docs/state-root.md](docs/state-root.md).
 

TODOS.md

@@ -2,12 +2,127 @@
 
 ## NEXT PRIORITY
 
+### P2/P3: severe fix wave follow-ups (filed 2026-10-03, v1.91.19.0)
+
+Deferred from the approved severe fix wave (docs/designs/SEVERE_FIX_WAVE_2026_10.md), each with its reason.
+
+- **Enforce the Bun floor at setup (#2815)** — `engines.bun` is now `>=1.4.0`
+  (the CI pin), but Bun does not enforce `engines` and setup never checks the
+  version. Bun older than 1.3.3 silently ignores `--no-compile-autoload-dotenv`
+  and `--no-env-file` (verified with 1.3.2), so D0's protection against a
+  project's `.env`/`bunfig.toml` is silently off there. Setup should refuse or
+  warn below the floor. **Effort:** S. **Priority:** P2.
+- **Windows Node CLI lane for Smart App Control (E3; #2596, #2595, #2124)** —
+  a `dist/browse` wrapper would shadow `browse.exe` for every Windows user;
+  launcher precedence (browse vs browse.exe vs browse.cmd under Git Bash and
+  cmd) and the node-missing message need a Windows SAC machine to verify.
+  **Effort:** M. **Priority:** P2.
+- **C8 router wording behind a routing panel** — disabled skills now leave the
+  router, but the "When in doubt, invoke the skill" wording change (Tier 3) was
+  not run through a routing eval panel. **Effort:** S. **Priority:** P3.
+- **Cross-block variables on fresh-shell hosts: make-pdf `$P`** — make-pdf
+  "exports" `$P` for later blocks, which Codex and the other env-var hosts lose
+  between blocks (same class as `$B`/`$D`, which the shared prelude now
+  re-derives). Add `P` to the runtime prelude or resolve it per block.
+  **Effort:** S. **Priority:** P2.
+- **#2709's recorded-Chromium reap never runs on Playwright 1.62** — Playwright
+  1.62's `Browser` has no `process()`, so `chromiumProcInfo` is always null and
+  the cleanup is a no-op (verified by probe). Record the PID another way (CDP
+  `SystemInfo.getProcessInfo` or the launch server). **Effort:** S. **Priority:** P2.
+- **#2670's bash half in `bin/gstack-brain-sync`** — the TypeScript stage
+  verdict now reports a 0-page artifacts source; the bash brain-sync still has
+  no `index_failed` status file or page-count probe. **Effort:** S. **Priority:** P3.
+- **Navigation guard acts after the request is sent** — Playwright routing
+  cannot see redirect hops, so a blocked hop resets the tab and fails the
+  command after the request left. Pre-send blocking needs CDP Fetch
+  interception, including out-of-process iframes. **Effort:** M. **Priority:** P3.
+- **Redaction repo allowlist (#2598)** — a per-repo `+++ b/<path>` skip list
+  (generated `*.svg`/`*.excalidraw`, #2827) for noise context rules cannot
+  cover. New config surface, so out of the wave. **Effort:** M. **Priority:** P2.
+- **Global-discover Codex session schema (#2750)**, **ios-qa boot-token fixes
+  (#1837, #1975; need a device)**, **absolute bun path for compiled browse
+  spawns (#931; macOS repro unclear)** and **GitLab CI `curl | bash` (#1713)** —
+  out of the wave's scope. **Priority:** P3 each.
+- **Upstream gbrain batch lookup** — a per-slug existence lookup and a separate
+  `pending` list in `gbrain import --json`, so the landing check need not list a
+  whole source and spawn `get` per page. **Effort:** M (upstream). **Priority:** P2.
+- **Memory follow-ups** — record repo identity for gbrain sources at
+  registration (prune can prove ownership of a pre-wave source only from the
+  same repository's main checkout); a deliberate migration of pre-wave
+  transcripts out of `default` into per-repo sources (needs gbrain-side page
+  moves); decide #2778's "nearest existing ancestor" attribution for deleted
+  worktrees (risk: attributing to an unrelated parent repo like a dotfiles
+  repo). **Priority:** P3 each.
+- **G2 on the TS twin** — `lib/bin-context.ts` (the Windows fallback) shares the
+  common-dir slug keying but does not record former worktree buckets.
+  **Effort:** S. **Priority:** P3.
+- **Codex follow-ups** — post-run `codex_sandbox_unavailable` telemetry (only
+  the preflight logs it today); the Q2 first-use notice covers Codex only, not
+  the Codex host's Claude Code outside voice; the bash-native timeout watchdog
+  cannot reap grandchildren when `pkill` is missing; document enabling
+  unprivileged user namespaces in common containers. **Priority:** P3 each.
+- **Live Codex multi-block check as a periodic paid case** — the wave ran it
+  once by hand (fresh `CODEX_HOME`, fresh clone, `./setup --host codex`, one
+  multi-block skill). Make it a periodic case so a regression shows up weekly.
+  **Effort:** M. **Priority:** P2.
+- **/review's working-tree fingerprint under Codex's default sandbox** — the
+  live Codex check (v1.91.19.0) showed `bin/gstack-wtree` exits 1 inside
+  `codex exec -s workspace-write`, because Codex mounts `.git` read-only and the
+  fingerprint writes untracked content into `.git/objects`. `gstack-review-log
+  --start review` then fails with `cannot capture a diff review without a
+  working-tree fingerprint` (loud, not a false pass), and `git fetch` cannot
+  write `FETCH_HEAD`. Use a private object directory
+  (`GIT_OBJECT_DIRECTORY` + `GIT_ALTERNATE_OBJECT_DIRECTORIES` under
+  `$TMPDIR`) for the fingerprint, and report the fetch as stale-base coverage.
+  **Effort:** S. **Priority:** P2.
+- **Closed by the wave's evals2 lane (run 37162480720):** Codex paid evals now
+  run commands in CI (host-run job; all 8 Codex cases executed real commands),
+  ship-exploratory-late-input no longer ends `inconclusive` (capture names the
+  probes to rerun after an input change), plan-eng-multi-finding-batching's
+  checker and office-hours-brain-writeback's prompt are fixed (3/3).
+  plan-eng-review-artifact (0/4 since #3017) measured a shortcut prompt that
+  skipped the workflow; it now drives the real interactive /plan-eng-review in
+  a PTY. A fresh run needs more than its 600 s budget (498 s pass; 595 s
+  timeouts in census 37174266054 and a local run), so the periodic case
+  resumes at Test review from that census run's real Scope Challenge ledger
+  (pass, 364 s) and the fresh run is the marathon case
+  plan-eng-review-artifact-full.
+- **Gate-outcome telemetry** — count `not_run`/`unavailable` outcomes per
+  reason code from `lib/gate-outcomes.ts` so the most common gaps get fixed
+  first. **Effort:** S. **Priority:** P3.
+- **/gstack-upgrade redesign around the install registry**, a **marketplace
+  distribution channel**, and a **placeholder convention for generated bash**
+  (`<placeholder>` vs real syntax in fences). **Priority:** P3 each.
+- **Design CLI health subcommand** — the DESIGN SETUP probe uses `--version`; a
+  richer `design health` could check the API key and model access too.
+  **Effort:** S. **Priority:** P3.
+- **Autoplan publication hook under cmd.exe** — `scripts/resolvers/composition.ts`
+  still registers `bash -c '<script>'`; the multi-line script with JSON printf
+  needs its own cmd.exe argv verification. **Effort:** S. **Priority:** P3.
+- **#2971 pieces outside the approved salvage** — ship/land validation-command
+  tuples and the requested-review/waiver gate in /land-and-deploy, the click
+  `<option>` 500 ms probe, 0600 modes on ingest state and staging files,
+  gbrain-sync's held-checkpoint refusal, and the question-preference hook's
+  fail-closed allowlist. **Priority:** P3 each.
+
 ### P1: paid-eval follow-ups from the v1.91.12.0 proof censuses (filed 2026-09-29)
 
 - **Thin budgets on slow API days** — on Claude Code 2.1.284, review-army-perf
   (274 of 300 s) and the ship-docsync fault cases (250-263 of 285 s) sit at
   88-93% of their budgets; a slow-API census can time them out on either CLI
   version. Make those skills faster rather than raising budgets. Effort M.
+  **Progress (v1.91.19.0, 2026-10-04):** /ship's documentation gate now
+  saves and checks its candidate with `bin/gstack-docs-candidate`
+  (`snapshot`/`compare`) instead of ~20 separate Git/hash calls and a
+  hand-written candidate JSON. Wall time (CI b24b6d8 before → two local trials
+  after, same budgets): store 476 → 346/386 s, current 354 → 339/326 s,
+  completion 412 → 372/371 s, failure 197 → 215/201 s; the eight other fault
+  cases moved within ±20 s (one trial each, all 12 PASS). Parent pre-dispatch
+  time fell from 140-186 s to 118-159 s. Parent tool calls did not fall
+  (store 55 → 51/62): the parent still reads release files the child re-reads,
+  and model thinking gaps (up to 77 s) dominate. Before/after machines differ
+  (CI vs local), so treat these as indicative. Next: stop the parent reading
+  release-file contents at all and let the child return hashes it read.
 - **Recurring reds to repair, not rerun** — `plan-design-review-plan-mode`
   (one ~250 s thinking block before its single write; times out at 300 s on
   2.1.251 in every recent run) and the HOLD SCOPE
@@ -19,7 +134,91 @@
   the handoff in its reasoning and later says it was "sent above". A prose fix
   won't reach it; this needs a mechanism outside the prompt (a hook or a
   tool-result gate). The HOLD SCOPE routing case fails whenever the handoff is
-  skipped and nothing else names the posture in time. Effort M.
+  skipped and nothing else names the posture in time. auto-decide-preserved
+  fails the same way: in periodic census 37176837432 (7249f01) the model
+  checked the preference, auto-selected HOLD SCOPE and logged it, but never
+  printed the `Auto-decided review mode → …` line, so the observer timed out.
+  Census history (last 15 periodic runs, 2026-09-29 to 10-04): mode-routing red
+  in 4 (36633323521, 36641820398, 36903600510 before this wave; 37176837432),
+  auto-decide-preserved red in 5 (36633323521, 36776104571, 36787269090,
+  36920606897 before this wave; 37176837432). Effort M.
+  **Completed:** v1.91.19.0 (2026-10-04). Step 0E now runs
+  `gstack-ceo-mode-handoff`, which prints the handoff line as a tool result,
+  and the auto-decide detector accepts the documented line with its
+  `Approved decisions:` suffix (trial 1 printed it and was rejected; the replay
+  is `test/fixtures/auto-decide-handoff-line-e354.json`). Local paid trials after
+  the repair: auto-decide-preserved 1/1, plan-ceo-mode-routing 1/1 (both modes);
+  every session ran the helper.
+- **plan-ceo-section-loading misses correctly worded stale-fill findings** —
+  censuses 37178734784 (65d94f2) and 37182865432 (44ef18c) failed
+  `hasStaleFillRaceFinding` although the review found the race. In 44ef18c it
+  named schedule S2 ("a read can fetch an old copy, pause, and only then put
+  it in the cache… every later reader gets stale data") and approved a
+  fill-admission guard. The detector is a regex family over phrasings; adding a
+  spelling per failure is the wrong fix. Bind the case to a structured finding
+  record (or an LLM judge with a fixed rubric) instead. 2 of the last 3
+  censuses, 0 of the 16 before. Effort M. **Priority:** P2.
+  **Completed:** v1.91.19.0 (2026-10-04). The case now reads the skill's own
+  decision-ledger row and `currentDecision` question
+  (`test/helpers/ceo-stale-fill-decision.ts`), with the phrase detector kept as
+  the alternate witness. Across eight census captures the structured check
+  finds 7 (it misses 37174266054, whose ledger row was left `unresolved`) and
+  the phrase detector finds 6; together they find all 8. The two missed reports
+  and one passing report are replayed from `test/fixtures/ceo-stale-fill-decision/`.
+- **auq-matrix recommendation-substance judge rotates red** — census
+  37182865432 scored plan-design-review's "A because the plan is thin
+  everywhere, so skipping dimensions mostly skips gaps" 3 < 4. The same case
+  was red in 5 of the 16 earlier censuses (37151477069 on main,
+  36898545245, 36787269090, 36641820398, 36633323521) across skills and checks
+  (a two-`(recommended)` option count; office-hours substance). It is kind
+  `rule` but gates on one judge sample. Decide under EVAL_POLICY whether it is
+  a `judge` case (3 samples, mean) and supply pass-rate evidence before
+  changing the kind. Effort S. **Priority:** P2.
+- **qa/SKILL.md workflow judge dips below its actionability floor** — census
+  37186854666 (b24b6d8) scored actionability 3.67 < 4 (clarity 3, completeness
+  4) on the same qa bundle bytes that passed in census 37182865432 (44ef18c);
+  nothing under qa/, qa-only/ or scripts/resolvers changed between them. Red in
+  2 of the 17 earlier censuses (36920606897, 36776104571). Judge kind, 3
+  samples, unchanged threshold. The qa-only workflow judge did the same in
+  census 37198445662 (fd6854b): 3.67/4.33/3.67, one 3/4/3 sample citing density,
+  on qa-only bytes unchanged since 44ef18c, where it passed in four censuses.
+  Find which bundle step the low samples call unactionable before rewording.
+  Effort S. **Priority:** P3.
+- **shared-libs-review-revalidation stalls mid-stream** — gate census 4 of
+  37186854666: the `filtered` scenario's stream stopped after a thinking block
+  at 07:51:21 and emitted nothing until the 657 s abort; the other three
+  scenarios passed. First red in 18 censuses. Classify a silent provider stream
+  as INFRA (no events for N minutes) rather than a test timeout. Effort S.
+  **Priority:** P3.
+- **overlay-harness sonnet fails on a baseline-arm model error** — census
+  37198445662 (fd6854b,
+  https://github.com/garrytan/gstack/actions/runs/37198445662): the
+  overlay-OFF arm's trial 0 grepped exports without `async` and reported
+  `src/api.ts: []` (missing `export async function fetchFoo`); 19 of 20
+  trials were correct and every overlay-ON trial passed. The correctness gate
+  requires all 20, so one control-arm slip reds a research comparison. First
+  red in the last five censuses. Decide whether a control-arm error should
+  invalidate the comparison (rerun policy) rather than fail the overlay.
+  Effort S. **Priority:** P3.
+- **plan-ceo-review-format-approach hit provider refusals** — census
+  37195203538 (4128700,
+  https://github.com/garrytan/gstack/actions/runs/37195203538): t1 and t2
+  ended in `model_refusal_no_fallback` (`reasoning_extraction`) on inputs
+  byte-identical to its 9/9 passes in 37182865432, 37186854666 and
+  37193478719; it passed 3/3 again in 37198445662. Classify a provider refusal
+  as INFRA rather than an assertion, and check whether the capture prompt's
+  "verbatim … exact prose you would have shown" wording trips the classifier.
+  Effort S. **Priority:** P3.
+- **Floor runner cannot grant an owned Edit when the TTY collapses spaces** —
+  PR run 37176835584 (7249f01): plan-ceo-finding-floor timed out at 600 s with
+  the native "Do you want to make this edit to gstack-test-plan-ceo-floor.md?"
+  menu on screen for its last ~5 minutes. The diff preview rendered context
+  rows with collapsed spaces (`210 C)Smoke-test…`, wrapped rows without their
+  gutter), so `currentEditPreview` could not parse the rows, the guard never
+  verified the owned edit, and nothing answered it. 1 of the last 12 PR-lane
+  runs; 0 of 15 censuses. Fix: accept collapsed context rows and gutterless
+  wraps in the preview parser (still compared against the exact source lines),
+  with the captured screen as a free regression. Effort S-M. **Priority:** P2.
 - **Pre-push hook tests hang behind some shard neighbors** — on the free-suite
   plan for dfe5e733, `test/redact-prepush-hook.test.ts` timed out 6 of 28 tests
   at 30 s in shard 12 on two attempts (the hook process was still running and
@@ -1093,22 +1292,12 @@ behind the secret. **Risk:** a long-lived credential in CI.
 
 **Effort:** S. **Priority:** P3.
 
-### P1: skillify gate test red — HOME-override sessions never discover project skills (pre-existing)
+### ✅ DONE (2026-10-03, v1.91.19.0 severe fix wave, I2): skillify gate test red
 
-**What:** `test/skill-e2e-skillify.test.ts` `skillify-provenance-refusal` fails
-on BOTH this branch and origin/main @ b5a951e6 (proven 2026-08-29: identical
-2-turn `Unknown skill: skillify` transcripts). Every test in that file passing
-`env: { HOME: workDir }` gets ZERO seeded project skills in the session init
-(claude CLI 2.1.237); the passing siblings recover by Reading the SKILL.md
-directly, the refusal test's agent stops at the Skill error. Fix the harness
-(seed skills wherever HOME-overridden discovery looks, or drop the HOME
-override and pass the write target another way), or report upstream if
-project-scope `.claude/skills` discovery genuinely keys off HOME.
-
-**Why:** A gate-tier safety test that is red for environmental reasons trains
-people to ignore gate reds.
-
-**Effort:** S-M (harness). **Priority:** P1 (gate hygiene).
+The gate `skill-e2e-skillify` cases (provenance-refusal, approval-reject,
+happy-path) passed in all 6 gate censuses 09-30..10-03 (latest
+https://github.com/garrytan/gstack/actions/runs/37151477069), and the periodic
+scrape-match-path and scrape-prototype-path cases passed 18/18 trials.
 
 ### P2: auq-verbose-vs-carved-ab PRE arm reads a branch-local ref (same fragility class the repetition-cut A/B just fixed)
 

VERSION

@@ -1 +1 @@
-1.91.18.0
+1.91.19.0

agents-digest/gstack-AGENTS.md

@@ -1,4 +1,4 @@
-# gstack digest v1.91.18.0 — regenerate/re-copy after upgrading gstack
+# gstack digest v1.91.19.0 — regenerate/re-copy after upgrading gstack
 
 Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed
 for agent hosts without a full skill install. The full skills add workflows,

autoplan/SKILL.md

@@ -765,13 +765,18 @@ elif ! command -v codex >/dev/null 2>&1; then
 elif ! _gstack_codex_auth_probe >/dev/null 2>&1; then
   _CODEX_MODE="not_authed"; _gstack_codex_log_event "codex_auth_failed" 2>/dev/null || true
 else
-  # Capture the probe's code: 2 means the CLI cannot execute at all, which is a
-  # different problem (and a different fix) from a model the account can't use.
-  _gstack_codex_model_probe; _CODEX_MP=$?
-  if [ "$_CODEX_MP" -eq 2 ]; then
+  # The free sandbox check runs before the paid model probe. Probe code 2 means
+  # the CLI cannot execute at all, a different fix from an unusable model.
+  _CODEX_MP=0; _gstack_codex_sandbox_preflight || _CODEX_MP=3
+  [ "$_CODEX_MP" -ne 0 ] || { _gstack_codex_model_probe; _CODEX_MP=$?; }
+  if [ "$_CODEX_MP" -eq 3 ]; then
+    _CODEX_MODE="sandbox_unavailable"
+  elif [ "$_CODEX_MP" -eq 2 ]; then
     _CODEX_MODE="broken_install"
   elif [ "$_CODEX_MP" -ne 0 ]; then
     _CODEX_MODE="model_unusable"
+  elif [ "${_GSTACK_CODEX_PROBE_STATE:-}" = inconclusive ]; then
+    _CODEX_MODE="unverified"
   else
     _CODEX_MODE="ready"; _gstack_codex_version_check 2>/dev/null || true
   fi
@@ -785,8 +790,9 @@ Branch on the echoed `CODEX_MODE`:
 - **`under_codex`** — stale artifact selected its own harness. Print: "Codex outside review unavailable: harness mismatch; no outside process started. Missing coverage. Repair: setup --host codex." Skip the outside invocation and follow the workflow's native-review instructions below. Conflicting inherited harness markers are not grounds to guess another provider.
 - **`not_authed`** — installed but no credentials. Print: "Codex not authenticated; outside coverage unavailable. Run `codex login` or set `$CODEX_API_KEY`." Keep the required Claude adversarial pass; do not dispatch a duplicate.
 - **`broken_install`** — the CLI is on PATH but cannot execute (spawn ENOENT, non-executable binary, missing vendor payload). Print: "Codex is installed but its binary cannot run — Codex passes skipped. Reinstall: `npm install -g @openai/codex`." Relay the probe's HINT lines. Keep the required Claude adversarial pass; do not dispatch a duplicate.
-- **`model_unusable`** — the selected model (see `CODEX_MODEL:`) is invalid or unavailable to the account (HTTP 400 on every call). Relay the probe's HINT lines and the fix (`GSTACK_CODEX_MODEL=<supported-model>` or config.toml `model`); never substitute a model. Keep the required Claude adversarial pass; do not dispatch a duplicate. The ~10s round trip is cached for 1h; timeouts fail open to `ready`.
-- **`ready`** — run the Codex pass below.
+- **`model_unusable`** — the selected model (see `CODEX_MODEL:`) is invalid or unavailable to the account (HTTP 400 on every call). Relay the probe's HINT lines and the fix (`GSTACK_CODEX_MODEL=<supported-model>` or config.toml `model`); never substitute a model. Keep the required Claude adversarial pass; do not dispatch a duplicate. The ~10s round trip is cached for 1h.
+- **`sandbox_unavailable`** — Codex's sandbox cannot start here (containers without user namespaces); the probe printed the reason and fix. No paid call ran; outside coverage is unavailable. Keep the required Claude adversarial pass; do not dispatch a duplicate.
+- **`ready`** or **`unverified`** — run the Codex pass below. `unverified` means the model check timed out; say so, and let the pass's own verdict decide.
 
 Disabled/unavailable retains applicable native passes. Recheck each outside dispatch.
 Record provider and completed/unavailable/disabled/skipped per phase; CEO covers
@@ -968,7 +974,7 @@ zero consensus counts. SOURCE = "codex" only for completed external
 output; native results use "in-host". OUTSIDE_STATUS is completed, unavailable,
 disabled or skipped. Never carry success across phases/runs; preserve modelUsage.
 
-Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"autoplan"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown.
+Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"autoplan"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown. Under `GSTACK_CODEX_NO_SANDBOX=1` add `"codex_sandbox":"danger-full-access"`.
 
 Present a phase coverage table (CEO, design, DX, eng): host, outside provider/status,
 native completion, findings, and partial coverage. Replace N with actual counts.

autoplan/sections/ceo-phase.md

@@ -112,29 +112,31 @@ _OUTSIDE_INPUT="$_OUTSIDE_TMP/prompt"
 cat -- '<prepared-prompt-file>' >"$_OUTSIDE_INPUT" || exit 1
 
 source "$HOME/.claude/skills/gstack/bin/gstack-codex-probe" && _gstack_codex_select_model exec || exit 1
-_OUTSIDE_PROMPT=$(cat "$_OUTSIDE_INPUT") || exit 1
+_gstack_codex_sandbox_preflight >/dev/null || exit 1
+_gstack_codex_first_use_notice
 _OUTSIDE_EXIT=0
-_gstack_codex_timeout_wrapper 540 codex exec "$_OUTSIDE_PROMPT" -C "$_REPO_ROOT" -s read-only -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="high"' -c 'web_search="cached"' < /dev/null >"$_OUTSIDE_TMP/text" 2>"$_OUTSIDE_TMP/stderr" || _OUTSIDE_EXIT=$?
-cat "$_OUTSIDE_TMP/text" || { [ "$_OUTSIDE_EXIT" -ne 0 ] || _OUTSIDE_EXIT=1; }
+_gstack_codex_timeout_wrapper 540 codex exec - -C "$_REPO_ROOT" -s "${_GSTACK_CODEX_SANDBOX:?}" -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="high"' -c 'web_search="cached"' --json -o "$_OUTSIDE_TMP/text" <"$_OUTSIDE_INPUT" >"$_OUTSIDE_TMP/events" 2>"$_OUTSIDE_TMP/stderr" || _OUTSIDE_EXIT=$?
+cat "$_OUTSIDE_TMP/text" 2>/dev/null || tail -n 20 "$_OUTSIDE_TMP/events"
 if [ "$_OUTSIDE_EXIT" -eq 124 ]; then
   _gstack_codex_log_event "codex_timeout" "540" || true
   _gstack_codex_log_hang "autoplan" "0" || true
 fi
 cat "$_OUTSIDE_TMP/stderr" >&2 || { [ "$_OUTSIDE_EXIT" -ne 0 ] || _OUTSIDE_EXIT=1; }
-if [ "$_OUTSIDE_EXIT" -ne 0 ]; then
-  echo 'Codex outside review unavailable: execution failed; missing coverage. Check the provider diagnosis above.' >&2
-  exit "$_OUTSIDE_EXIT"
-fi
-bun "$HOME/.claude/skills/gstack/lib/outside-review-result.ts" review "$_OUTSIDE_TMP/text" || exit 1
-
+_OUTSIDE_RC=0
+bun "$HOME/.claude/skills/gstack/lib/outside-review-result.ts" --label 'Codex outside review' --exit "$_OUTSIDE_EXIT" --stderr "$_OUTSIDE_TMP/stderr" --events "$_OUTSIDE_TMP/events" review "$_OUTSIDE_TMP/text" || _OUTSIDE_RC=$?
+case "$_OUTSIDE_RC" in
+  0|3) ;;
+  4) echo 'OUTSIDE_STATUS: unverified provider=codex host=claude'; exit 4 ;;
+  *) [ "$_OUTSIDE_EXIT" -ne 0 ] && exit "$_OUTSIDE_EXIT"; exit 1 ;;
+esac
 echo 'OUTSIDE_STATUS: completed provider=codex host=claude'
 ```
 
-Use Bash `timeout: 600000`; show the full response in a `tool-output` fence. Require successful execution and valid markers. Refusal, empty/malformed output, missing score/severity/completion markers, timeout or CLI failure means `outside_status: unavailable`. Use the caller's fallback; missing coverage is never clean/PASS. After either outcome, delete only your private prompt; scratch cleanup is automatic.
+Use Bash `timeout: 600000`; show the full response in a `tool-output` fence. Require successful execution and valid markers. Refusal, empty/malformed output, missing score/severity/completion markers, timeout or CLI failure means `outside_status: unavailable`. P0/P1 findings block like native ones; `OUTSIDE_STATUS: unverified` is missing coverage. Use the caller's fallback; missing coverage is never clean/PASS. After either outcome, delete only your private prompt; scratch cleanup is automatic.
 
 Failed/incomplete outside review → unavailable; disabled → skip outside. Both retain the native pass.
 
-Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"ceo"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown.
+Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"ceo"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown. Under `GSTACK_CODEX_NO_SANDBOX=1` add `"codex_sandbox":"danger-full-access"`.
 
   **Error handling:** Codex auth/timeout/empty → proceed with
   Claude subagent only, tagged `[single-model]`. If Claude subagent also fails →

autoplan/sections/design-phase.md

@@ -71,29 +71,31 @@ _OUTSIDE_INPUT="$_OUTSIDE_TMP/prompt"
 cat -- '<prepared-prompt-file>' >"$_OUTSIDE_INPUT" || exit 1
 
 source "$HOME/.claude/skills/gstack/bin/gstack-codex-probe" && _gstack_codex_select_model exec || exit 1
-_OUTSIDE_PROMPT=$(cat "$_OUTSIDE_INPUT") || exit 1
+_gstack_codex_sandbox_preflight >/dev/null || exit 1
+_gstack_codex_first_use_notice
 _OUTSIDE_EXIT=0
-_gstack_codex_timeout_wrapper 540 codex exec "$_OUTSIDE_PROMPT" -C "$_REPO_ROOT" -s read-only -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="high"' -c 'web_search="cached"' < /dev/null >"$_OUTSIDE_TMP/text" 2>"$_OUTSIDE_TMP/stderr" || _OUTSIDE_EXIT=$?
-cat "$_OUTSIDE_TMP/text" || { [ "$_OUTSIDE_EXIT" -ne 0 ] || _OUTSIDE_EXIT=1; }
+_gstack_codex_timeout_wrapper 540 codex exec - -C "$_REPO_ROOT" -s "${_GSTACK_CODEX_SANDBOX:?}" -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="high"' -c 'web_search="cached"' --json -o "$_OUTSIDE_TMP/text" <"$_OUTSIDE_INPUT" >"$_OUTSIDE_TMP/events" 2>"$_OUTSIDE_TMP/stderr" || _OUTSIDE_EXIT=$?
+cat "$_OUTSIDE_TMP/text" 2>/dev/null || tail -n 20 "$_OUTSIDE_TMP/events"
 if [ "$_OUTSIDE_EXIT" -eq 124 ]; then
   _gstack_codex_log_event "codex_timeout" "540" || true
   _gstack_codex_log_hang "autoplan" "0" || true
 fi
 cat "$_OUTSIDE_TMP/stderr" >&2 || { [ "$_OUTSIDE_EXIT" -ne 0 ] || _OUTSIDE_EXIT=1; }
-if [ "$_OUTSIDE_EXIT" -ne 0 ]; then
-  echo 'Codex outside review unavailable: execution failed; missing coverage. Check the provider diagnosis above.' >&2
-  exit "$_OUTSIDE_EXIT"
-fi
-bun "$HOME/.claude/skills/gstack/lib/outside-review-result.ts" review "$_OUTSIDE_TMP/text" || exit 1
-
+_OUTSIDE_RC=0
+bun "$HOME/.claude/skills/gstack/lib/outside-review-result.ts" --label 'Codex outside review' --exit "$_OUTSIDE_EXIT" --stderr "$_OUTSIDE_TMP/stderr" --events "$_OUTSIDE_TMP/events" review "$_OUTSIDE_TMP/text" || _OUTSIDE_RC=$?
+case "$_OUTSIDE_RC" in
+  0|3) ;;
+  4) echo 'OUTSIDE_STATUS: unverified provider=codex host=claude'; exit 4 ;;
+  *) [ "$_OUTSIDE_EXIT" -ne 0 ] && exit "$_OUTSIDE_EXIT"; exit 1 ;;
+esac
 echo 'OUTSIDE_STATUS: completed provider=codex host=claude'
 ```
 
-Use Bash `timeout: 600000`; show the full response in a `tool-output` fence. Require successful execution and valid markers. Refusal, empty/malformed output, missing score/severity/completion markers, timeout or CLI failure means `outside_status: unavailable`. Use the caller's fallback; missing coverage is never clean/PASS. After either outcome, delete only your private prompt; scratch cleanup is automatic.
+Use Bash `timeout: 600000`; show the full response in a `tool-output` fence. Require successful execution and valid markers. Refusal, empty/malformed output, missing score/severity/completion markers, timeout or CLI failure means `outside_status: unavailable`. P0/P1 findings block like native ones; `OUTSIDE_STATUS: unverified` is missing coverage. Use the caller's fallback; missing coverage is never clean/PASS. After either outcome, delete only your private prompt; scratch cleanup is automatic.
 
 Failed/incomplete outside review → unavailable; disabled → skip outside. Both retain the native pass.
 
-Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"design"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown.
+Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"design"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown. Under `GSTACK_CODEX_NO_SANDBOX=1` add `"codex_sandbox":"danger-full-access"`.
 
   Error handling: Phase 1 failure/degradation policy applies.
 

autoplan/sections/dx-phase.md

@@ -75,29 +75,31 @@ _OUTSIDE_INPUT="$_OUTSIDE_TMP/prompt"
 cat -- '<prepared-prompt-file>' >"$_OUTSIDE_INPUT" || exit 1
 
 source "$HOME/.claude/skills/gstack/bin/gstack-codex-probe" && _gstack_codex_select_model exec || exit 1
-_OUTSIDE_PROMPT=$(cat "$_OUTSIDE_INPUT") || exit 1
+_gstack_codex_sandbox_preflight >/dev/null || exit 1
+_gstack_codex_first_use_notice
 _OUTSIDE_EXIT=0
-_gstack_codex_timeout_wrapper 540 codex exec "$_OUTSIDE_PROMPT" -C "$_REPO_ROOT" -s read-only -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="high"' -c 'web_search="cached"' < /dev/null >"$_OUTSIDE_TMP/text" 2>"$_OUTSIDE_TMP/stderr" || _OUTSIDE_EXIT=$?
-cat "$_OUTSIDE_TMP/text" || { [ "$_OUTSIDE_EXIT" -ne 0 ] || _OUTSIDE_EXIT=1; }
+_gstack_codex_timeout_wrapper 540 codex exec - -C "$_REPO_ROOT" -s "${_GSTACK_CODEX_SANDBOX:?}" -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="high"' -c 'web_search="cached"' --json -o "$_OUTSIDE_TMP/text" <"$_OUTSIDE_INPUT" >"$_OUTSIDE_TMP/events" 2>"$_OUTSIDE_TMP/stderr" || _OUTSIDE_EXIT=$?
+cat "$_OUTSIDE_TMP/text" 2>/dev/null || tail -n 20 "$_OUTSIDE_TMP/events"
 if [ "$_OUTSIDE_EXIT" -eq 124 ]; then
   _gstack_codex_log_event "codex_timeout" "540" || true
   _gstack_codex_log_hang "autoplan" "0" || true
 fi
 cat "$_OUTSIDE_TMP/stderr" >&2 || { [ "$_OUTSIDE_EXIT" -ne 0 ] || _OUTSIDE_EXIT=1; }
-if [ "$_OUTSIDE_EXIT" -ne 0 ]; then
-  echo 'Codex outside review unavailable: execution failed; missing coverage. Check the provider diagnosis above.' >&2
-  exit "$_OUTSIDE_EXIT"
-fi
-bun "$HOME/.claude/skills/gstack/lib/outside-review-result.ts" review "$_OUTSIDE_TMP/text" || exit 1
-
+_OUTSIDE_RC=0
+bun "$HOME/.claude/skills/gstack/lib/outside-review-result.ts" --label 'Codex outside review' --exit "$_OUTSIDE_EXIT" --stderr "$_OUTSIDE_TMP/stderr" --events "$_OUTSIDE_TMP/events" review "$_OUTSIDE_TMP/text" || _OUTSIDE_RC=$?
+case "$_OUTSIDE_RC" in
+  0|3) ;;
+  4) echo 'OUTSIDE_STATUS: unverified provider=codex host=claude'; exit 4 ;;
+  *) [ "$_OUTSIDE_EXIT" -ne 0 ] && exit "$_OUTSIDE_EXIT"; exit 1 ;;
+esac
 echo 'OUTSIDE_STATUS: completed provider=codex host=claude'
 ```
 
-Use Bash `timeout: 600000`; show the full response in a `tool-output` fence. Require successful execution and valid markers. Refusal, empty/malformed output, missing score/severity/completion markers, timeout or CLI failure means `outside_status: unavailable`. Use the caller's fallback; missing coverage is never clean/PASS. After either outcome, delete only your private prompt; scratch cleanup is automatic.
+Use Bash `timeout: 600000`; show the full response in a `tool-output` fence. Require successful execution and valid markers. Refusal, empty/malformed output, missing score/severity/completion markers, timeout or CLI failure means `outside_status: unavailable`. P0/P1 findings block like native ones; `OUTSIDE_STATUS: unverified` is missing coverage. Use the caller's fallback; missing coverage is never clean/PASS. After either outcome, delete only your private prompt; scratch cleanup is automatic.
 
 Failed/incomplete outside review → unavailable; disabled → skip outside. Both retain the native pass.
 
-Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"dx"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown.
+Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"dx"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown. Under `GSTACK_CODEX_NO_SANDBOX=1` add `"codex_sandbox":"danger-full-access"`.
 
   Error handling: Phase 1 failure/degradation policy applies.
 

autoplan/sections/eng-phase.md

@@ -64,29 +64,31 @@ _OUTSIDE_INPUT="$_OUTSIDE_TMP/prompt"
 cat -- '<prepared-prompt-file>' >"$_OUTSIDE_INPUT" || exit 1
 
 source "$HOME/.claude/skills/gstack/bin/gstack-codex-probe" && _gstack_codex_select_model exec || exit 1
-_OUTSIDE_PROMPT=$(cat "$_OUTSIDE_INPUT") || exit 1
+_gstack_codex_sandbox_preflight >/dev/null || exit 1
+_gstack_codex_first_use_notice
 _OUTSIDE_EXIT=0
-_gstack_codex_timeout_wrapper 540 codex exec "$_OUTSIDE_PROMPT" -C "$_REPO_ROOT" -s read-only -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="high"' -c 'web_search="cached"' < /dev/null >"$_OUTSIDE_TMP/text" 2>"$_OUTSIDE_TMP/stderr" || _OUTSIDE_EXIT=$?
-cat "$_OUTSIDE_TMP/text" || { [ "$_OUTSIDE_EXIT" -ne 0 ] || _OUTSIDE_EXIT=1; }
+_gstack_codex_timeout_wrapper 540 codex exec - -C "$_REPO_ROOT" -s "${_GSTACK_CODEX_SANDBOX:?}" -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="high"' -c 'web_search="cached"' --json -o "$_OUTSIDE_TMP/text" <"$_OUTSIDE_INPUT" >"$_OUTSIDE_TMP/events" 2>"$_OUTSIDE_TMP/stderr" || _OUTSIDE_EXIT=$?
+cat "$_OUTSIDE_TMP/text" 2>/dev/null || tail -n 20 "$_OUTSIDE_TMP/events"
 if [ "$_OUTSIDE_EXIT" -eq 124 ]; then
   _gstack_codex_log_event "codex_timeout" "540" || true
   _gstack_codex_log_hang "autoplan" "0" || true
 fi
 cat "$_OUTSIDE_TMP/stderr" >&2 || { [ "$_OUTSIDE_EXIT" -ne 0 ] || _OUTSIDE_EXIT=1; }
-if [ "$_OUTSIDE_EXIT" -ne 0 ]; then
-  echo 'Codex outside review unavailable: execution failed; missing coverage. Check the provider diagnosis above.' >&2
-  exit "$_OUTSIDE_EXIT"
-fi
-bun "$HOME/.claude/skills/gstack/lib/outside-review-result.ts" review "$_OUTSIDE_TMP/text" || exit 1
-
+_OUTSIDE_RC=0
+bun "$HOME/.claude/skills/gstack/lib/outside-review-result.ts" --label 'Codex outside review' --exit "$_OUTSIDE_EXIT" --stderr "$_OUTSIDE_TMP/stderr" --events "$_OUTSIDE_TMP/events" review "$_OUTSIDE_TMP/text" || _OUTSIDE_RC=$?
+case "$_OUTSIDE_RC" in
+  0|3) ;;
+  4) echo 'OUTSIDE_STATUS: unverified provider=codex host=claude'; exit 4 ;;
+  *) [ "$_OUTSIDE_EXIT" -ne 0 ] && exit "$_OUTSIDE_EXIT"; exit 1 ;;
+esac
 echo 'OUTSIDE_STATUS: completed provider=codex host=claude'
 ```
 
-Use Bash `timeout: 600000`; show the full response in a `tool-output` fence. Require successful execution and valid markers. Refusal, empty/malformed output, missing score/severity/completion markers, timeout or CLI failure means `outside_status: unavailable`. Use the caller's fallback; missing coverage is never clean/PASS. After either outcome, delete only your private prompt; scratch cleanup is automatic.
+Use Bash `timeout: 600000`; show the full response in a `tool-output` fence. Require successful execution and valid markers. Refusal, empty/malformed output, missing score/severity/completion markers, timeout or CLI failure means `outside_status: unavailable`. P0/P1 findings block like native ones; `OUTSIDE_STATUS: unverified` is missing coverage. Use the caller's fallback; missing coverage is never clean/PASS. After either outcome, delete only your private prompt; scratch cleanup is automatic.
 
 Failed/incomplete outside review → unavailable; disabled → skip outside. Both retain the native pass.
 
-Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"eng"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown.
+Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"eng"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown. Under `GSTACK_CODEX_NO_SANDBOX=1` add `"codex_sandbox":"danger-full-access"`.
 
   Error handling: Phase 1 failure/degradation policy applies.
 

benchmark/SKILL.md

@@ -160,14 +160,15 @@ Use Aside first: the user's real browser and signed-in sessions. If unavailable,
 ```bash
 _gs_d() { if command -v gtimeout >/dev/null; then gtimeout 30 "$@"; elif command -v timeout >/dev/null; then timeout 30 "$@"
 elif command -v perl >/dev/null; then perl -e 'alarm(shift);exec(@ARGV)' 30 "$@"; else return 125; fi; }
-if [ "${GSTACK_SKIP_ASIDE:-}" = "1" ] || ! command -v aside >/dev/null 2>&1; then
-  echo "NEEDS_ASIDE"
+_A=aside; command -v aside >/dev/null || _A=$(command -v ~/.local/bin/aside)
+if [ "${GSTACK_SKIP_ASIDE:-}" = "1" ] || [ -z "$_A" ]; then
+  echo "NEEDS_ASIDE: ${GSTACK_PLATFORM:-$(uname)}"
 else
-  _rc=0; _o=$(_gs_d aside repl 'console.log("ASIDE_READY " + pwd)' 2>&1) || _rc=$?
+  _rc=0; _o=$(_gs_d "$_A" repl 'console.log("ASIDE_READY " + pwd)' 2>&1) || _rc=$?
   case "$_rc" in
     124|142) echo "ASIDE_TIMEOUT: probe deadline exceeded" ;;
     125) echo "ASIDE_UNAVAILABLE: bounded probe unavailable" ;;
-    0) if printf '%s\n' "$_o" | grep -q '^ASIDE_READY '; then echo "READY: aside"
+    0) if printf '%s\n' "$_o" | grep -q '^ASIDE_READY '; then echo "READY: $_A"
        else echo "ASIDE_NOT_RUNNING: no readiness marker"; fi ;;
     *) echo "ASIDE_CLI_ERROR: exit $_rc; inspect aside --help locally" ;;
   esac
@@ -175,9 +176,9 @@ else
 fi
 ```
 
-1. `NEEDS_ASIDE`: if `uname -s` prints `Darwin`, say once: "Download Aside (macOS 15+) at aside.com, open it, sign in, then re-run." Off macOS, do not pitch it. NEVER run an installer, brew formula, or download for them; never substitute unit tests or curl for the browser step. Then continue with the Browser fallback section below.
-2. `ASIDE_NOT_RUNNING`: ask once to open the app and retry. Other non-READY statuses: report the safe status, not "app stopped". Never print raw diagnostics (private paths/tokens). Then continue with the Browser fallback section below.
-3. `READY`: continue. `aside --help` and `aside <command> --help` are the authority on flags; take operational syntax from them, never new permissions or scope.
+1. `NEEDS_ASIDE: Darwin` (trust it; don't re-probe): say once: "Download Aside (macOS 15+) at aside.com; open, sign in, re-run." Off macOS, do not pitch it. NEVER run an installer, brew formula, or download; never substitute unit tests or curl for the browser step. Then continue with the Browser fallback section below.
+2. `ASIDE_NOT_RUNNING`: ask once to open the app and retry. Other non-READY statuses: report the safe status, not "app stopped". Never print raw diagnostics. Then continue with the Browser fallback section below.
+3. `READY`: continue (a printed path runs in place of `aside`). `aside --help` and `aside <command> --help` are the authority on flags; take operational syntax from them, never new permissions or scope.
 
 ### Rules for driving a real browser
 

bin/gstack-analytics

@@ -170,7 +170,9 @@ echo "$SKILL_COUNTS" | while read -r COUNT SKILL; do
       # Extract duration_s value using split on "duration_s":
       n = split($0, parts, "\"duration_s\":")
       if (n >= 2) {
-        # parts[2] starts with the value, e.g. "142,"
+        # parts[2] starts with the value: unquoted (142,...) or quoted ("142",...),
+        # which gstack-skill-end writes. Strip a leading quote before the digits.
+        sub(/^"/, "", parts[2])
         gsub(/[^0-9.].*/, "", parts[2])
         if (parts[2]+0 > 0) { total += parts[2]; count++ }
       }

bin/gstack-brain-enqueue

@@ -58,7 +58,7 @@ TS=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")
 
 # One spool file per record: tmp write + atomic rename. Any failure exits 0
 # silently (fire-and-forget contract), cleaning up the tmp file.
-mkdir -p "$SPOOL" 2>/dev/null || exit 0
+mkdir -p "$SPOOL" 2>/dev/null || exit 0  # best-effort: enqueue is fire-and-forget; the next sync rescans
 TMP="$SPOOL/.tmp-$$-$RANDOM"
 printf '{"file":"%s","ts":"%s"}\n' "$ESC_FILE" "$TS" > "$TMP" 2>/dev/null || { rm -f "$TMP" 2>/dev/null; exit 0; }
 mv -f "$TMP" "$SPOOL/$(date +%s)-$$-$RANDOM.json" 2>/dev/null || rm -f "$TMP" 2>/dev/null

bin/gstack-brain-sync

@@ -688,9 +688,9 @@ subcmd_once() {
   fi
 
   local paths_file class_file snapshot_file
-  paths_file=$(mktemp /tmp/brain-sync-paths.XXXXXX) || { rm -rf "$lock_dir" 2>/dev/null; write_status "error" "mktemp failed"; exit 1; }
-  class_file=$(mktemp /tmp/brain-sync-class.XXXXXX) || { rm -f "$paths_file"; rm -rf "$lock_dir" 2>/dev/null; write_status "error" "mktemp failed"; exit 1; }
-  snapshot_file=$(mktemp /tmp/brain-sync-snapshot.XXXXXX) || { rm -f "$paths_file" "$class_file"; rm -rf "$lock_dir" 2>/dev/null; write_status "error" "mktemp failed"; exit 1; }
+  paths_file=$(mktemp "${TMPDIR:-/tmp}/brain-sync-paths.XXXXXX") || { rm -rf "$lock_dir" 2>/dev/null; write_status "error" "mktemp failed"; exit 1; }
+  class_file=$(mktemp "${TMPDIR:-/tmp}/brain-sync-class.XXXXXX") || { rm -f "$paths_file"; rm -rf "$lock_dir" 2>/dev/null; write_status "error" "mktemp failed"; exit 1; }
+  snapshot_file=$(mktemp "${TMPDIR:-/tmp}/brain-sync-snapshot.XXXXXX") || { rm -f "$paths_file" "$class_file"; rm -rf "$lock_dir" 2>/dev/null; write_status "error" "mktemp failed"; exit 1; }
   # Single trap covers all: lock cleanup AND tempfile cleanup.
   trap 'rm -f "$paths_file" "$class_file" "$snapshot_file" 2>/dev/null; rm -rf "$lock_dir" 2>/dev/null || true' EXIT INT TERM
 

bin/gstack-ceo-mode-handoff

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# gstack-ceo-mode-handoff — print /plan-ceo-review's Step 0E mode handoff line.
+#
+# Usage: gstack-ceo-mode-handoff <MODE> [--auto] [--decisions "<rows>"]
+#   MODE: HOLD SCOPE | SCOPE EXPANSION | SELECTIVE EXPANSION | SCOPE REDUCTION
+#         (underscores accepted for spaces)
+#   --auto       the mode came from a saved AUTO_DECIDE preference
+#   --decisions  governing approved rows; defaults to "none"
+#
+# The handoff used to be chat-only, and the model often composed it in its
+# reasoning without ever sending it. Running this prints the line as a tool
+# result, so the selected mode is observable before the review continues.
+set -euo pipefail
+
+mode="${1:-}"
+[ "$#" -gt 0 ] && shift
+auto=0
+decisions="none"
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --auto) auto=1; shift ;;
+    --decisions)
+      [ "$#" -ge 2 ] || { echo "gstack-ceo-mode-handoff: --decisions needs a value" >&2; exit 2; }
+      decisions="$2"; shift 2 ;;
+    *) echo "gstack-ceo-mode-handoff: unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+mode="${mode//_/ }"
+case "$mode" in
+  "HOLD SCOPE"|"SCOPE EXPANSION"|"SELECTIVE EXPANSION"|"SCOPE REDUCTION") ;;
+  *) echo "gstack-ceo-mode-handoff: unknown mode: ${mode:-<empty>}" >&2; exit 2 ;;
+esac
+decisions="${decisions//$'\n'/ }"
+decisions="${decisions%.}"
+[ -n "${decisions// /}" ] || decisions="none"
+
+if [ "$auto" = 1 ]; then
+  echo "Auto-decided review mode → $mode (your preference). Change with /plan-tune. Approved decisions: $decisions."
+else
+  echo "Mode: $mode; approved decisions: $decisions."
+fi

bin/gstack-codex-probe

@@ -5,6 +5,9 @@
 # Functions (all prefixed with _gstack_codex_ for namespace hygiene):
 #   _gstack_codex_auth_probe      — multi-signal auth check (env + file)
 #   _gstack_codex_select_model    — resolve + print the runtime model (#2914)
+#   _gstack_codex_sandbox_mode    — read-only, or full access only for GSTACK_CODEX_NO_SANDBOX=1
+#   _gstack_codex_sandbox_preflight — free `codex sandbox` check before paid calls (Linux)
+#   _gstack_codex_first_use_notice — once per machine: provider, account, how to turn off
 #   _gstack_codex_model_probe     — round-trip probe of the selected model (#2477)
 #   _gstack_codex_version_check   — warn on known-bad Codex CLI versions
 #   _gstack_codex_timeout_wrapper — gtimeout -> timeout -> bash-native watchdog
@@ -19,8 +22,9 @@
 # --- Auth probe -------------------------------------------------------------
 
 _gstack_codex_auth_probe() {
-  # Multi-signal: env vars OR auth file. Avoids false negatives for env-auth
-  # users (CI, platform engineers) that a file-only check would reject.
+  # Multi-signal: env vars OR auth file OR a custom provider's env_key. Avoids
+  # false negatives for env-auth users (CI, platform engineers, self-hosted
+  # OpenAI-compatible providers) that a file-only check would reject.
   local _codex_home="${CODEX_HOME:-$HOME/.codex}"
   # Use `-n` which returns true only for non-empty non-whitespace. Bash's [ -n ]
   # alone allows whitespace; pair with a whitespace strip for robustness.
@@ -31,7 +35,26 @@ _gstack_codex_auth_probe() {
     echo "AUTH_OK"
     return 0
   fi
+  # Custom OpenAI-compatible providers (#2192): a [model_providers.<id>]
+  # table names its credential variable in env_key. Only keys inside those
+  # tables count, comments are ignored, and the name must be a plain shell
+  # identifier before it is dereferenced.
+  local _env_key _resolved _missing=""
+  if [ -f "$_codex_home/config.toml" ]; then
+    while IFS= read -r _env_key; do
+      case "$_env_key" in ''|[0-9]*|*[!A-Za-z0-9_]*) continue ;; esac
+      _resolved=$(printf '%s' "${!_env_key:-}" | tr -d '[:space:]')
+      if [ -n "$_resolved" ]; then
+        echo "AUTH_OK"
+        return 0
+      fi
+      _missing="${_missing:+$_missing, }$_env_key"
+    done < <(awk '/^[[:space:]]*#/ { next }
+      /^[[:space:]]*\[/ { in_provider = ($0 ~ /^[[:space:]]*\[model_providers\.[^]]+\][[:space:]]*(#.*)?$/); next }
+      in_provider && /^[[:space:]]*env_key[[:space:]]*=/ { v = $0; sub(/^[^=]*=[[:space:]]*/, "", v); sub(/[[:space:]]*#.*$/, "", v); gsub(/["\047[:space:]]/, "", v); print v }' "$_codex_home/config.toml" 2>/dev/null)
+  fi
   echo "AUTH_FAILED"
+  [ -n "$_missing" ] && echo "HINT: $_codex_home/config.toml names a custom provider key ($_missing), but it is not set in this shell. Export it, or run codex login." >&2
   return 1
 }
 
@@ -65,6 +88,67 @@ _gstack_codex_select_model() {
   fi
   _GSTACK_CODEX_SEL_KIND="$_kind"
   echo "CODEX_MODEL: $_GSTACK_CODEX_SEL ($_kind; source: $_GSTACK_CODEX_SEL_SRC)" >&2
+  _gstack_codex_sandbox_mode
+}
+
+# --- Sandbox (B1) -----------------------------------------------------------
+
+_gstack_codex_sandbox_mode() {
+  # Every gstack Codex command passes -s / sandbox_mode from this variable, so
+  # one place decides it. Codex has no read-only mode without its sandbox, so
+  # the escape hatch is full access: honored only for exactly 1, only from the
+  # shell environment (never a dotenv file or config), and announced each use.
+  if [ "${GSTACK_CODEX_NO_SANDBOX:-}" = "1" ]; then
+    _GSTACK_CODEX_SANDBOX="danger-full-access"
+    echo "WARNING: GSTACK_CODEX_NO_SANDBOX=1: Codex runs this review without a sandbox and can read and write anything your user can. Use it only inside a container you trust." >&2
+  else
+    _GSTACK_CODEX_SANDBOX="read-only"
+  fi
+}
+
+_gstack_codex_sandbox_preflight() {
+  # Free check before the first paid call: `codex sandbox` starts the same
+  # bubblewrap sandbox with no model. Only a recognized sandbox failure blocks
+  # (exit 3, printed as missing coverage); success, a timeout, or an older CLI
+  # without the subcommand defers to the post-run classifier. Linux only, and
+  # skipped when the user turned the sandbox off. Fixtures:
+  # test/fixtures/codex-sandbox/.
+  [ "${GSTACK_CODEX_NO_SANDBOX:-}" = "1" ] && return 0
+  [ "$(uname -s 2>/dev/null)" = "Linux" ] || return 0
+  local _out _code _line
+  _out=$(_gstack_codex_timeout_wrapper 10 codex sandbox -c 'sandbox_mode="read-only"' true </dev/null 2>&1)
+  _code=$?
+  { [ "$_code" -eq 0 ] || [ "$_code" -eq 124 ]; } && return 0
+  _line=$(printf '%s\n' "$_out" | grep -m1 -iE '^[[:space:]]*bwrap: |bubblewrap is unavailable|landlock.{0,60}(fail|error|not supported|unsupported)|seccomp.{0,60}(fail|error)|user namespaces?.{0,80}(not (allowed|permitted|supported)|denied|disabled)' | sed 's/^[[:space:]]*//' | cut -c1-240)
+  [ -n "$_line" ] || return 0
+  echo "CODEX_SANDBOX: unavailable"
+  echo "Codex outside review unavailable: Codex's sandbox could not start here ($_line). No review ran; this is missing coverage, not a pass. Fix: enable unprivileged user namespaces for this container, or set GSTACK_CODEX_NO_SANDBOX=1." >&2
+  _gstack_codex_log_event "codex_sandbox_unavailable" 2>/dev/null || true
+  return 3
+}
+
+# --- First-use notice (#965) ------------------------------------------------
+
+_gstack_codex_first_use_notice() {
+  # Outside reviews are on by default and use whatever Codex login exists, so
+  # the first one on a machine says where the code goes, with which account,
+  # and how to turn reviews off. Shown once per state root; never blocks and
+  # never prints a credential, only where it comes from.
+  local _root _marker _codex_home="${CODEX_HOME:-$HOME/.codex}" _account _provider
+  _root="$(. "${BASH_SOURCE[0]%/*}/gstack-state-root.sh" 2>/dev/null && gstack_state_root)" || return 0
+  [ -n "$_root" ] || return 0
+  _marker="$_root/.codex-review-notice-shown"
+  [ -e "$_marker" ] && return 0
+  if [ -n "$(printf '%s' "${CODEX_API_KEY:-}" | tr -d '[:space:]')" ]; then _account="the API key in CODEX_API_KEY"
+  elif [ -n "$(printf '%s' "${OPENAI_API_KEY:-}" | tr -d '[:space:]')" ]; then _account="the API key in OPENAI_API_KEY"
+  elif grep -q '"auth_mode"[[:space:]]*:[[:space:]]*"chatgpt"' "$_codex_home/auth.json" 2>/dev/null; then _account="the ChatGPT account Codex is logged in with (see: codex login status)"
+  elif [ -f "$_codex_home/auth.json" ]; then _account="the API key saved by codex login in $_codex_home/auth.json"
+  else _account="the credentials your Codex config.toml provider names"
+  fi
+  _provider=$(sed -n 's/^[[:space:]]*model_provider[[:space:]]*=[[:space:]]*"\([A-Za-z0-9_.-]*\)".*/\1/p' "$_codex_home/config.toml" 2>/dev/null | head -1)
+  echo "NOTICE: gstack outside reviews send the review prompt and code to Codex (provider: ${_provider:-openai}) using $_account. Reviews stay on; this notice shows once per machine. To turn them off: gstack-config set codex_reviews disabled" >&2
+  mkdir -p "$_root" 2>/dev/null && : > "$_marker" 2>/dev/null
+  return 0
 }
 
 # --- Model round-trip probe (#2477) ------------------------------------------
@@ -79,8 +163,9 @@ _gstack_codex_model_probe() {
   #
   # Contract:
   #   MODEL_OK (exit 0)              — round trip succeeded; cached 1h.
-  #   MODEL_UNUSABLE (exit 1)        — deterministic model 400 or an invalid
-  #     model choice; hints printed. The 400 is cached 15 min: re-probing every
+  #   MODEL_UNUSABLE (exit 1)        — deterministic model rejection (400, or a
+  #     404 from a retired model or a wrong custom-provider base_url) or an
+  #     invalid model choice; hints name the cause. The 400 is cached 15 min: re-probing every
   #     preflight charged the affected user a 30s round trip + real tokens per
   #     review section, forever. Changing the model or config.toml changes the
   #     cache signature and re-probes immediately; the short TTL covers
@@ -89,9 +174,10 @@ _gstack_codex_model_probe() {
   #     ENOENT, non-executable binary, missing vendor payload). Deterministic,
   #     so fail-open is wrong: retrying never helps. Never cached — a reinstall
   #     fixes it and must be picked up on the very next probe (#2742).
-  #   MODEL_PROBE_INCONCLUSIVE (exit 0) — timeout/transient; FAIL-OPEN so a
-  #     slow network never wedges codex mode (the per-invocation Error
-  #     Handling entry still covers a later 400). Never cached.
+  #   MODEL_PROBE_INCONCLUSIVE (exit 0) — timeout/transient; the review still
+  #     runs so a slow network never wedges codex mode, but readiness is
+  #     unverified (_GSTACK_CODEX_PROBE_STATE=inconclusive, CODEX_MODE:
+  #     unverified) and the review's own classification decides. Never cached.
   #
   # Only call this AFTER _gstack_codex_auth_probe passes — probing without
   # auth just measures the auth failure again.
@@ -162,13 +248,27 @@ _gstack_codex_model_probe() {
     echo "MODEL_OK"
     return 0
   fi
-  if printf '%s' "$_out" | grep -qiE 'model.{0,40}is not supported|"status":[[:space:]]*400'; then
+  # A model rejection is deterministic: a 400 ("is not supported", "requires a
+  # newer version of Codex") or a 404. A retired model answers 404 "does not
+  # exist or you do not have access to it", and a custom provider with a wrong
+  # base_url answers a bare 404; neither is network luck, so neither may fall
+  # through to the inconclusive branch below and report ready (#2843).
+  if printf '%s' "$_out" | grep -qiE 'model.{0,40}is not supported|"status":[[:space:]]*40[04]|requires a newer version of codex|does not exist or you do not have access|model.{0,40}does not exist|404 not found|status:?[[:space:]]*404'; then
     [ -n "$_cache" ] && { mkdir -p "$_gstack_home" 2>/dev/null; printf 'MODEL_UNUSABLE %s %s\n' "$_now" "$_sig" > "$_cache" 2>/dev/null; }
     echo "MODEL_UNUSABLE"
-    printf '%s\n' "$_out" | grep -i "model" | head -3
+    printf '%s\n' "$_out" | grep -iE "model|404" | head -3
     echo "HINT: gstack requested model '$_model' (source: $_GSTACK_CODEX_SEL_SRC)."
-    echo "HINT: choose a model your account can use: set GSTACK_CODEX_MODEL=<supported-model>, set model in $_codex_home/config.toml, or name one for this request."
-    _gstack_codex_log_event "codex_model_unusable" 2>/dev/null || true
+    if printf '%s' "$_out" | grep -qiE 'requires a newer version of codex|upgrade to the latest (app|version|cli)'; then
+      echo "HINT: the server refused it because this Codex CLI is too old; no model choice fixes that. Upgrade the CLI (\`codex doctor\` prints the command; usually npm install -g @openai/codex)."
+      _gstack_codex_log_event "codex_cli_outdated" 2>/dev/null || true
+    elif printf '%s' "$_out" | grep -qiE 'does not exist|404'; then
+      echo "HINT: Codex answered 404: either the model is retired or not visible to this account, or a custom provider's base_url in $_codex_home/config.toml is wrong."
+      echo "HINT: choose a current model (GSTACK_CODEX_MODEL=<supported-model> or model in config.toml), or fix that provider's base_url."
+      _gstack_codex_log_event "codex_model_retired" 2>/dev/null || true
+    else
+      echo "HINT: choose a model your account can use: set GSTACK_CODEX_MODEL=<supported-model>, set model in $_codex_home/config.toml, or name one for this request."
+      _gstack_codex_log_event "codex_model_unusable" 2>/dev/null || true
+    fi
     return 1
   fi
   # A CLI that cannot execute is deterministic, not transient: the fail-open
@@ -190,7 +290,10 @@ _gstack_codex_model_probe() {
   fi
   # Timeout (124) or transient failure: fail-open with a warning. The probe
   # exists to catch the deterministic model 400, not to gate on network luck.
-  echo "MODEL_PROBE_INCONCLUSIVE (exit $_code) — proceeding; if invocations fail with a model 400, see the codex skill's Error Handling entry."
+  # Callers report CODEX_MODE: unverified, never ready; the exit stays 0 so
+  # skills rendered before this marker keep running the review.
+  _GSTACK_CODEX_PROBE_STATE="inconclusive"
+  echo "MODEL_PROBE_INCONCLUSIVE (exit $_code) — CODEX_MODE: unverified; proceeding, and the review's own result is still checked. If invocations fail with a model 400, see the codex skill's Error Handling entry."
   return 0
 }
 
@@ -257,10 +360,12 @@ _gstack_codex_timeout_wrapper() {
     # mirror timeout(1)'s exit-124 contract. The watchdog's stdout is
     # detached so an early finish never blocks a caller's $(...) capture on
     # the orphaned sleep.
-    "$@" &
+    # Without job control a background command's stdin is /dev/null; keep the
+    # caller's stdin so prompts fed with `codex exec -` arrive (#1674).
+    "$@" <&0 &
     local _cmd_pid=$!
     (
-      sleep "$_duration" && trap '' TERM && kill -TERM "$_cmd_pid" 2>/dev/null || exit 0
+      sleep "$_duration" && trap '' TERM && kill -TERM "$_cmd_pid" 2>/dev/null || exit 0  # best-effort: the command already exited, nothing to stop
       _GSTACK_CODEX_WAITED=0
       while [ "$_GSTACK_CODEX_WAITED" -lt "$_grace" ] && kill -0 "$_cmd_pid" 2>/dev/null; do
         sleep 1
@@ -288,7 +393,8 @@ _gstack_codex_log_event() {
   # Emit a telemetry event to ~/.gstack/analytics/skill-usage.jsonl.
   # Gated on $_TEL != "off" (caller sets this from gstack-config).
   # Event types: codex_timeout, codex_auth_failed, codex_cli_missing,
-  #              codex_version_warning, codex_model_unusable.
+  #              codex_version_warning, codex_model_unusable, codex_sandbox_unavailable,
+#              codex_model_retired, codex_cli_outdated.
   # Payload schema: {skill, event, duration_s, ts}. NEVER includes prompt
   # content, env var values, or auth tokens.
   local _event="$1"

bin/gstack-community-dashboard

@@ -36,7 +36,7 @@ fi
 # ─── Fetch aggregated stats from edge function ────────────────
 # HTTP status captured (#1947): a backend failure must read as "unknown",
 # never as a healthy "Weekly active installs: 0".
-TMPBODY="$(mktemp)"
+TMPBODY="$(mktemp "${TMPDIR:-/tmp}/gstack-community.XXXXXX")"
 trap 'rm -f "$TMPBODY"' EXIT
 SUPA_HOST="${SUPABASE_URL#*://}"; SUPA_HOST="${SUPA_HOST%%/*}"
 HTTP_CODE="$(_receipted_curl open community-dashboard "$SUPA_HOST" community-pulse-fetch "user-invoked dashboard" --no-payload \

bin/gstack-config

@@ -159,6 +159,9 @@ CONFIG_HEADER='# gstack configuration — edit freely, changes take effect on ne
 #                           #   plan/document reviews skip the entire extra review step.
 #                           #   Office hours/design/spec/manual wrappers keep their own
 #                           #   opt-in/skip controls. Invalid values preserve the old value.
+# browse_extension_id:      # Forks and self-built extensions: the 32-letter (a-p)
+#                           #   Chrome extension ID the browse sidebar terminal accepts.
+#                           #   Empty = the gstack extension. "" clears it.
 # design_detector_install_prompted: false
 #                           #   true once you answered the one-time offer from the
 #                           #   design skills to download the impeccable engine with
@@ -173,6 +176,15 @@ CONFIG_HEADER='# gstack configuration — edit freely, changes take effect on ne
 # gstack_contributor: false # true = file field reports when gstack misbehaves
 # skip_eng_review: false    # true = skip eng review gate in /ship (not recommended)
 #
+# ─── Browser extension ───────────────────────────────────────────────
+# browse_extension_id:      # Chrome extension ID the browse daemon trusts for
+#                           #   /extension-token and the terminal-agent /ws
+#                           #   (32 letters a-p). Empty = the published gstack
+#                           #   extension. Set it only for a fork or a
+#                           #   self-built extension; no environment variable
+#                           #   or project .env can change it. An invalid value
+#                           #   is REJECTED and the stored value kept.
+#
 # ─── Workspace-aware ship ────────────────────────────────────────────
 # workspace_root: $HOME/conductor/workspaces  # Where /ship looks for sibling
 #                           # Conductor worktrees when picking a VERSION slot.
@@ -211,6 +223,7 @@ lookup_default() {
     pair_agent) echo "off" ;; # remote tunnel consent — fail-closed until /pair-agent asks
     memorable_recall) echo "off" ;; # on | off — Memorable bridge gate, fail-closed until `gstack-memorable enable`
     founder_resources) echo "true" ;; # office-hours resource pitch — #538 permanent opt-out sets false
+    browse_extension_id) echo "" ;; # empty → browse trusts gstack's own extension ID (D1)
     claude_overlay_model) echo "claude" ;; # set only by ./setup --claude-model; presence via `has`
     # Brain-aware planning (v1.48 / T5+T10+T16). Defaults documented inline:
     #   brain_trust_policy@<endpoint-id>  — unset on fresh install; setup-gbrain
@@ -570,7 +583,7 @@ case "${1:-}" in
     # A config value is one non-empty line (disabled_skills may be empty: it
     # clears the list). Reject rather than truncate, so a bad value never
     # replaces the stored one.
-    if [ -z "$VALUE" ] && [ "$KEY" != "disabled_skills" ]; then
+    if [ -z "$VALUE" ] && [ "$KEY" != "disabled_skills" ] && [ "$KEY" != "browse_extension_id" ]; then
       echo "Error: $KEY value is empty. Existing value left unchanged." >&2
       exit 1
     fi
@@ -688,6 +701,13 @@ case "${1:-}" in
       echo "Error: memorable_recall '$VALUE' not recognized. Valid values: on, off. Existing value left unchanged." >&2
       exit 1
     fi
+    # browse_extension_id (D1) decides which Chrome extension may reach the
+    # browse daemon's token route and terminal socket. Reject anything that is
+    # not a Chrome extension ID; "" clears the override.
+    if [ "$KEY" = "browse_extension_id" ] && [ -n "$VALUE" ] && ! printf '%s' "$VALUE" | LC_ALL=C grep -qE '^[a-p]{32}$'; then
+      echo "Error: browse_extension_id '$VALUE' is not a Chrome extension ID (32 letters a-p, shown on chrome://extensions). Existing value left unchanged." >&2
+      exit 1
+    fi
     # disabled_skills (#1206): comma-separated skill names, one value for the
     # key. Every name must be a real skill (typos get the closest name);
     # gstack and gstack-upgrade can never be disabled; "" re-enables all.
@@ -810,7 +830,8 @@ case "${1:-}" in
                skill_prefix explain_level \
                codex_reviews gstack_contributor skip_eng_review workspace_root \
                artifacts_sync_mode artifacts_sync_mode_prompted plan_tune_hooks \
-               timeline_stop_hook design_detector design_detector_install_prompted memorable_recall; do
+               timeline_stop_hook design_detector design_detector_install_prompted memorable_recall \
+               browse_extension_id; do
       gstack_config_select "$KEY"
       VALUE="$_gstack_cfg_value"
       SOURCE="default"
@@ -830,7 +851,8 @@ case "${1:-}" in
                skill_prefix explain_level \
                codex_reviews gstack_contributor skip_eng_review workspace_root \
                artifacts_sync_mode artifacts_sync_mode_prompted plan_tune_hooks \
-               timeline_stop_hook design_detector design_detector_install_prompted memorable_recall; do
+               timeline_stop_hook design_detector design_detector_install_prompted memorable_recall \
+               browse_extension_id; do
       printf '  %-24s %s\n' "$KEY:" "$(lookup_default "$KEY")"
     done
     ;;
@@ -867,10 +889,12 @@ case "${1:-}" in
 
     # Summarize for the user. Use python (already required elsewhere) to
     # parse the JSON portably; fall back to grep if python is unavailable.
+    # The file goes in on stdin (E6, #1967): bash opens the path, so a native
+    # Windows Python under Git Bash never has to resolve an MSYS /c/... path.
     PYTHON_CMD=$(command -v python3 || command -v python || true)
     if [ -n "$PYTHON_CMD" ]; then
-      STATUS=$("$PYTHON_CMD" -c "import json,sys; d=json.load(open('$DETECTION_FILE')); print(d.get('gbrain_local_status','unknown'))" 2>/dev/null || echo unknown)
-      VERSION=$("$PYTHON_CMD" -c "import json,sys; d=json.load(open('$DETECTION_FILE')); print(d.get('gbrain_version') or 'unknown')" 2>/dev/null || echo unknown)
+      STATUS=$("$PYTHON_CMD" -c "import json,sys; d=json.load(sys.stdin); print(d.get('gbrain_local_status','unknown'))" < "$DETECTION_FILE" 2>/dev/null || echo unknown)
+      VERSION=$("$PYTHON_CMD" -c "import json,sys; d=json.load(sys.stdin); print(d.get('gbrain_version') or 'unknown')" < "$DETECTION_FILE" 2>/dev/null || echo unknown)
     else
       STATUS=$(grep -o '"gbrain_local_status":[[:space:]]*"[^"]*"' "$DETECTION_FILE" | sed 's/.*"\([^"]*\)"$/\1/')
       VERSION=$(grep -o '"gbrain_version":[[:space:]]*"[^"]*"' "$DETECTION_FILE" | sed 's/.*"\([^"]*\)"$/\1/')
@@ -879,8 +903,10 @@ case "${1:-}" in
     fi
 
     case "$STATUS" in
-      ok|timeout|thin-client|engine-locked)
-        # "timeout" = slow-but-healthy engine (#1964); "thin-client" =
+      ok|timeout|db-unreachable|thin-client|engine-locked)
+        # "timeout" = slow-but-healthy engine (#1964); "db-unreachable" =
+        # network/DNS failure with an intact config, transient like timeout
+        # (A2); "thin-client" =
         # remote-HTTP MCP brain, no local engine by design (#2051);
         # "engine-locked" = same class (#2456): PGLite is single-writer, so a
         # live `gbrain serve` (typically an MCP server) holds the embedded DB.

bin/gstack-design-doc-find

@@ -9,8 +9,9 @@
 # Precedence:
 #   1. newest $GSTACK_STATE_ROOT/projects/<slug>/*-<branch>-design-*.md
 #   2. else newest $GSTACK_STATE_ROOT/projects/<slug>/*-design-*.md
-#   3. a repo doc ($TOP/DESIGN.md, else newest $TOP/docs/designs/*.md) wins when
-#      no state-root doc exists or it is newer than the state-root doc.
+#   3. the newest repo doc under $TOP/docs/designs/ wins when no state-root doc
+#      exists or it is newer than the state-root doc. A root DESIGN.md is the
+#      design system /design-consultation writes, never a design doc (#2839).
 #      office-hours writes both copies; the committed copy is what teammates
 #      see, but a stale repo doc never shadows a newer private session.
 set -u
@@ -34,13 +35,7 @@ LOCALDOC=$(newest "$PROJECT_DIR"/*-"$BRANCH"-design-*.md)
 
 REPODOC=""
 TOP=$(git rev-parse --show-toplevel 2>/dev/null || true)
-if [ -n "$TOP" ]; then
-  if [ -f "$TOP/DESIGN.md" ]; then
-    REPODOC="$TOP/DESIGN.md"
-  else
-    REPODOC=$(newest "$TOP"/docs/designs/*.md)
-  fi
-fi
+[ -n "$TOP" ] && REPODOC=$(newest "$TOP"/docs/designs/*.md)
 
 DESIGN="$LOCALDOC"
 if [ -n "$REPODOC" ] && { [ -z "$LOCALDOC" ] || [ "$REPODOC" -nt "$LOCALDOC" ]; }; then

bin/gstack-developer-profile

@@ -353,6 +353,7 @@ do_derive() {
       const qids = new Set();
       const days = new Set();
       let count = 0;
+      let signalEvents = 0;
       for (const line of lines) {
         let e;
         try { e = JSON.parse(line); } catch { continue; }
@@ -362,8 +363,8 @@ do_derive() {
         qids.add(e.question_id);
         if (e.ts) days.add(String(e.ts).slice(0,10));
         const def = QUESTIONS[e.question_id];
-        if (def && def.signal_key) {
-          applySignal(totals, def.signal_key, e.user_choice);
+        if (def && def.signal_key && applySignal(totals, def.signal_key, e.user_choice).length > 0) {
+          signalEvents++;
         }
       }
 
@@ -375,6 +376,9 @@ do_derive() {
       profile.inferred = {
         values,
         sample_size: count,
+        // Events that actually moved a dimension (B10): sample_size counts every
+        // logged answer, most of which match no signal and leave the 0.5 seed.
+        signal_events: signalEvents,
         diversity: {
           skills_covered: skills.size,
           question_ids_covered: qids.size,

bin/gstack-distill-free-text

@@ -129,7 +129,7 @@ fi
 
 # Heredoc into temp file (avoids $(cat <<'PROMPT'...) which choked the
 # bash parser on apostrophes elsewhere in the script).
-DISTILL_PROMPT_FILE=$(mktemp)
+DISTILL_PROMPT_FILE=$(mktemp "${TMPDIR:-/tmp}/gstack-distill.XXXXXX")
 trap 'rm -f "$DISTILL_PROMPT_FILE"' EXIT
 cat > "$DISTILL_PROMPT_FILE" <<'PROMPT'
 You are gstack dream-cycle distiller. Below are free-text responses the

bin/gstack-docs-candidate

@@ -0,0 +1,141 @@
+#!/usr/bin/env -S bun --no-env-file run
+/**
+ * gstack-docs-candidate — /ship's documentation-audit snapshot and its later check.
+ *
+ * Usage (run inside the repository):
+ *   gstack-docs-candidate snapshot --out <candidate.json> --audit-id <id> --mode edit|read-only
+ *                                  --base <rev> [--select <path>]... [--docs <path>]...
+ *   gstack-docs-candidate compare <candidate.json>
+ *
+ * snapshot saves, NUL-safely and without writing to the repository: base SHA,
+ * HEAD, branch, index entries, committed (base..HEAD), staged, unstaged and
+ * untracked paths, and git blob hashes of the working-tree content of every
+ * selected path, docs path and dirty/untracked path. Without --select, the
+ * selected paths are the committed, staged, unstaged and untracked paths.
+ * --docs takes files or directories (directories expand to their tracked and
+ * untracked files). It prints a short summary; the JSON file is the record.
+ *
+ * compare re-reads the same state and prints one JSON object: whether HEAD or
+ * the index changed, which recorded paths' content changed or disappeared, and
+ * which paths are newly dirty or untracked. It never decides whether a change
+ * was permitted; the caller checks those paths against the child's report.
+ */
+import { spawnSync } from 'child_process';
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+
+function git(args: string[]): string {
+  const r = spawnSync('git', args, { encoding: 'utf8', env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' }, maxBuffer: 256 * 1024 * 1024 });
+  if (r.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${(r.stderr || '').trim()}`);
+  return r.stdout;
+}
+const nul = (text: string) => text.split('\0').filter(Boolean);
+
+function state(base: string) {
+  const head = git(['rev-parse', 'HEAD']).trim();
+  return {
+    head,
+    branch: git(['branch', '--show-current']).trim(),
+    index: nul(git(['ls-files', '-s', '-z'])),
+    committed: nul(git(['diff', '--name-only', '-z', base, head])),
+    staged: nul(git(['diff', '--cached', '--name-only', '-z'])),
+    unstaged: nul(git(['diff', '--name-only', '-z'])),
+    untracked: nul(git(['ls-files', '-z', '--others', '--exclude-standard'])),
+  };
+}
+
+function expand(paths: string[]): string[] {
+  const listed = nul(git(['ls-files', '-z', '--cached', '--others', '--exclude-standard']));
+  const out = new Set<string>();
+  for (const p of paths) {
+    const rel = p.replace(/^\.\//, '').replace(/\/+$/, '');
+    const under = listed.filter(f => f === rel || f.startsWith(rel + '/'));
+    if (under.length) under.forEach(f => out.add(f)); else out.add(rel);
+  }
+  return [...out].sort();
+}
+
+/** Git blob ids of working-tree content, computed in-process (any path bytes, nothing written); null when absent. */
+function hashes(paths: string[]): Record<string, string | null> {
+  const out: Record<string, string | null> = {};
+  for (const p of paths) {
+    if (!fs.existsSync(p) || !fs.statSync(p).isFile()) { out[p] = null; continue; }
+    const content = fs.readFileSync(p);
+    out[p] = createHash('sha1').update(`blob ${content.length}\0`).update(content).digest('hex');
+  }
+  return out;
+}
+
+function flag(args: string[], name: string): string[] {
+  const values: string[] = [];
+  for (let i = 0; i < args.length; i++) if (args[i] === name) {
+    const value = args[i + 1];
+    if (value === undefined || value.startsWith('--')) throw new Error(`${name} needs a value`);
+    values.push(value); i++;
+  }
+  return values;
+}
+
+function one(args: string[], name: string): string {
+  const values = flag(args, name);
+  if (values.length !== 1) throw new Error(`${name} is required exactly once`);
+  return values[0]!;
+}
+
+function main(argv: string[]): void {
+  const [command, ...args] = argv;
+  if (command === 'snapshot') {
+    const known = new Set(['--out', '--audit-id', '--mode', '--base', '--select', '--docs']);
+    for (let i = 0; i < args.length; i += 2) if (!known.has(args[i]!)) throw new Error(`unknown argument: ${args[i]}`);
+    const out = path.resolve(one(args, '--out'));
+    const top = fs.realpathSync(git(['rev-parse', '--show-toplevel']).trim());
+    if (out === top || out.startsWith(top + path.sep)) throw new Error('--out must be outside the repository');
+    const mode = one(args, '--mode');
+    if (mode !== 'edit' && mode !== 'read-only') throw new Error('--mode must be edit or read-only');
+    const base = git(['rev-parse', '--verify', one(args, '--base') + '^{commit}']).trim();
+    process.chdir(top);
+    const now = state(base);
+    const selected = flag(args, '--select').length ? expand(flag(args, '--select'))
+      : [...new Set([...now.committed, ...now.staged, ...now.unstaged, ...now.untracked])].sort();
+    const docs = expand(flag(args, '--docs'));
+    const tracked = [...new Set([...selected, ...docs, ...now.staged, ...now.unstaged, ...now.untracked])].sort();
+    const record = { schema_version: 1, audit_id: one(args, '--audit-id'), mode, base, ...now, selected, docs, hashes: hashes(tracked) };
+    fs.writeFileSync(out, JSON.stringify(record, null, 2) + '\n', { mode: 0o600 });
+    console.log(`CANDIDATE: ${out}`);
+    console.log(`base=${base} head=${now.head} branch=${now.branch || '(detached)'} mode=${mode}`);
+    console.log(`committed=${now.committed.length} staged=${now.staged.length} unstaged=${now.unstaged.length} untracked=${now.untracked.length} selected=${selected.length} docs=${docs.length} hashed=${tracked.length}`);
+    for (const [label, list] of [['committed', now.committed], ['staged', now.staged], ['unstaged', now.unstaged], ['untracked', now.untracked], ['docs', docs]] as const) {
+      if (list.length) console.log(`${label}: ${list.map(p => JSON.stringify(p)).join(' ')}`);
+    }
+    return;
+  }
+  if (command === 'compare') {
+    if (args.length !== 1) throw new Error('compare takes exactly one candidate path');
+    const record = JSON.parse(fs.readFileSync(args[0]!, 'utf8'));
+    if (record?.schema_version !== 1 || typeof record.base !== 'string' || typeof record.hashes !== 'object') throw new Error('not a gstack-docs-candidate record');
+    process.chdir(fs.realpathSync(git(['rev-parse', '--show-toplevel']).trim()));
+    const now = state(record.base);
+    const current = hashes(Object.keys(record.hashes));
+    const content_changed = Object.keys(record.hashes).filter(p => current[p] !== record.hashes[p]).sort();
+    const dirty = (s: { staged: string[]; unstaged: string[]; untracked: string[] }) => new Set([...s.staged, ...s.unstaged, ...s.untracked]);
+    const before = dirty(record);
+    const newly_dirty = [...dirty(now)].filter(p => !before.has(p) && !(p in record.hashes)).sort();
+    const sameList = (a: string[], b: string[]) => a.length === b.length && a.every((v, i) => v === b[i]);
+    console.log(JSON.stringify({
+      audit_id: record.audit_id,
+      head_changed: now.head !== record.head,
+      index_changed: !sameList(now.index, record.index),
+      content_changed,
+      newly_dirty,
+    }));
+    return;
+  }
+  throw new Error('usage: gstack-docs-candidate snapshot|compare (see --help in the file header)');
+}
+
+try { main(process.argv.slice(2)); }
+catch (error) {
+  console.error(`gstack-docs-candidate: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}

bin/gstack-gbrain-detect

@@ -18,7 +18,7 @@
  *     "gstack_brain_sync_mode": "off"|"artifacts-only"|"full",
  *     "gstack_brain_git": true|false,
  *     "gstack_artifacts_remote": "https://..." | "",
- *     "gbrain_local_status": "ok"|"no-cli"|"missing-config"|"broken-config"|"broken-db"|"engine-locked"|"timeout"|"thin-client",
+ *     "gbrain_local_status": "ok"|"no-cli"|"missing-config"|"broken-config"|"broken-db"|"engine-locked"|"timeout"|"db-unreachable"|"thin-client",
  *     "gbrain_pooler_mode": "transaction"|"session"|null
  *   }
  *
@@ -40,6 +40,7 @@ import { join } from "path";
 
 import {
   localEngineStatus,
+  localEngineStatusDetail,
   resolveGbrainBin,
   readGbrainVersion,
 } from "../lib/gbrain-local-status";
@@ -281,13 +282,16 @@ function main(): void {
   const withThinClient =
     out.gbrain_local_status === "thin-client"
       ? { ...out, gbrain_thin_client: { probed: false } }
-      : out;
+      : out.gbrain_local_status === "db-unreachable"
+        ? { ...out, gbrain_local_status_detail: localEngineStatusDetail() }
+        : out;
 
   process.stdout.write(JSON.stringify(withThinClient, null, 2) + "\n");
 }
 
 // --is-ok: live engine-status gate. Exits 0 iff gbrain is usable ("ok";
-// "timeout" — a slow-but-healthy engine, #1964; "thin-client" — remote-HTTP
+// "timeout" — a slow-but-healthy engine, #1964; "db-unreachable" — a network
+// error reaching a configured DB, transient like timeout; "thin-client" — remote-HTTP
 // MCP brain with no local engine by design, #2051; or "engine-locked" —
 // PGLite is single-writer, so a live `gbrain serve` (typically an MCP
 // server) holds the embedded DB, #2456 — gbrain is installed and healthy in
@@ -300,7 +304,8 @@ if (process.argv.includes("--is-ok")) {
   const noCache = process.env.GSTACK_DETECT_NO_CACHE === "1";
   const status = localEngineStatus({ noCache });
   process.exit(
-    status === "ok" || status === "timeout" || status === "thin-client" || status === "engine-locked"
+    status === "ok" || status === "timeout" || status === "db-unreachable" ||
+      status === "thin-client" || status === "engine-locked"
       ? 0
       : 1,
   );

bin/gstack-gbrain-install

@@ -96,6 +96,19 @@ if ! $VALIDATE_ONLY; then
   fi
 fi
 
+# Read a string field (dotted path, e.g. bin.gbrain) from a package.json with
+# bun, which this installer already requires. It used to need jq, which it
+# never checked for, so a successful install reported failure (#1675).
+pkg_field() {
+  GSTACK_PKG_JSON="$1" GSTACK_PKG_FIELD="$2" bun -e '
+    try {
+      const pkg = JSON.parse(require("fs").readFileSync(process.env.GSTACK_PKG_JSON, "utf8"));
+      const v = process.env.GSTACK_PKG_FIELD.split(".").reduce((o, k) => (o == null ? o : o[k]), pkg);
+      if (typeof v === "string") process.stdout.write(v);
+    } catch {}
+  ' 2>/dev/null || true
+}
+
 # --- D5 detect-first: probe common locations before cloning fresh ---
 # Accept any directory that looks like a gbrain clone: has package.json
 # with name "gbrain" and a `bin.gbrain` entry. Don't accept version mismatches
@@ -105,10 +118,10 @@ is_valid_clone() {
   [ -d "$dir" ] || return 1
   [ -f "$dir/package.json" ] || return 1
   local name
-  name=$(jq -r '.name // empty' "$dir/package.json" 2>/dev/null || true)
+  name=$(pkg_field "$dir/package.json" name)
   [ "$name" = "gbrain" ] || return 1
   local bin
-  bin=$(jq -r '.bin.gbrain // empty' "$dir/package.json" 2>/dev/null || true)
+  bin=$(pkg_field "$dir/package.json" bin.gbrain)
   [ -n "$bin" ] || return 1
   return 0
 }
@@ -199,7 +212,7 @@ _bun_exe_hint() {
 # Read the version from the install-dir's package.json; compare to
 # `gbrain --version`. If they disagree, PATH is returning a DIFFERENT
 # gbrain than the one we just linked. Fail hard with remediation.
-expected_version=$(jq -r '.version // empty' "$INSTALL_DIR/package.json" 2>/dev/null || true)
+expected_version=$(pkg_field "$INSTALL_DIR/package.json" version)
 if [ -z "$expected_version" ]; then
   fail "cannot read version from $INSTALL_DIR/package.json (install may be broken)"
 fi

bin/gstack-gbrain-mcp-verify

@@ -74,13 +74,13 @@ emit() {
 INIT_BODY='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"gstack-mcp-verify","version":"1"}}}'
 
 # Capture HTTP code + body in one pass; --max-time 10 caps total wall time.
-TMPBODY=$(mktemp -t gstack-mcp-verify.XXXXXX)
+TMPBODY=$(mktemp "${TMPDIR:-/tmp}/gstack-mcp-verify.XXXXXX")
 trap 'rm -f "$TMPBODY"' EXIT
 
 # Receipted fail-closed: the payload file is hashed and handed to curl as
 # the exact wire bytes. A refused receipt never hits the network — it lands
 # in the NETWORK class below (curl never ran, no HTTP code).
-INIT_PAYLOAD=$(mktemp -t gstack-mcp-init.XXXXXX)
+INIT_PAYLOAD=$(mktemp "${TMPDIR:-/tmp}/gstack-mcp-init.XXXXXX")
 printf '%s' "$INIT_BODY" > "$INIT_PAYLOAD"
 set +e
 HTTP_CODE=$(_receipted_curl closed gbrain-mcp-verify "$MCP_HOST" mcp-initialize-probe "user-invoked mcp verify" "$INIT_PAYLOAD" \
@@ -156,12 +156,12 @@ fi
 # mcp__gbrain__sources_add will flip this true and gstack-artifacts-init
 # will print the one-liner form instead of the clone-then-path form.
 URL_SUPPORTED=false
-TOOLS_BODY_FILE=$(mktemp -t gstack-mcp-tools.XXXXXX)
+TOOLS_BODY_FILE=$(mktemp "${TMPDIR:-/tmp}/gstack-mcp-tools.XXXXXX")
 TOOLS_REQ='{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
 
 # Receipted fail-closed like the initialize probe. A refused receipt skips
 # the probe (nonzero TOOLS_EXIT) and the field stays false — best-effort.
-TOOLS_PAYLOAD=$(mktemp -t gstack-mcp-tools-req.XXXXXX)
+TOOLS_PAYLOAD=$(mktemp "${TMPDIR:-/tmp}/gstack-mcp-tools-req.XXXXXX")
 printf '%s' "$TOOLS_REQ" > "$TOOLS_PAYLOAD"
 set +e
 _receipted_curl closed gbrain-mcp-verify "$MCP_HOST" mcp-tools-list-probe "user-invoked mcp verify" "$TOOLS_PAYLOAD" \

bin/gstack-gbrain-source-wireup

@@ -36,7 +36,7 @@
 # at src/core/config.ts:53), so a process that flips config.json mid-sync
 # can't redirect us at a different brain mid-stream.
 #
-# Depends on: jq (transitive via gstack-gbrain-detect).
+# Depends on: bun (already a gstack dependency), gbrain, git.
 
 set -euo pipefail
 
@@ -93,7 +93,7 @@ elif [ -f "$GBRAIN_CONFIG" ]; then
   # Python heredoc reads config.json. On JSON parse failure or any IO error,
   # we WARN (not silently swallow) so the user knows the URL lock fell back
   # to gbrain's own loadConfig (which would still read this same file).
-  _py_err=$(mktemp -t wireup-pyerr 2>/dev/null || mktemp /tmp/wireup-pyerr.XXXXXX)
+  _py_err=$(mktemp "${TMPDIR:-/tmp}/wireup-pyerr.XXXXXX")
   _locked_url=$(GBRAIN_CONFIG_PATH="$GBRAIN_CONFIG" python3 -c '
 import json, os, sys
 try:
@@ -204,21 +204,34 @@ ensure_worktree() {
 }
 
 # ---- gbrain sources operations ----
+# Read .sources[] | select(.id==$id) | .local_path out of `gbrain sources list`
+# with bun (a gstack dependency). This used to need jq, which nothing installs
+# and which git-bash on Windows lacks, so the wireup was skipped every run
+# (#2369). Prints the path, or nothing when the id is absent or the payload
+# is not JSON.
+source_local_path() {
+  gbrain sources list --json 2>/dev/null \
+    | GB_SOURCE_ID="$1" bun -e '
+        const raw = await Bun.stdin.text();
+        try {
+          const s = (JSON.parse(raw).sources || []).find((x) => x.id === process.env.GB_SOURCE_ID);
+          process.stdout.write(s?.local_path ?? "");
+        } catch {}
+      ' 2>/dev/null \
+    | tr -d '[:space:]'
+}
+
 # Returns 0 if source with id exists at expected path. 1 if exists but path differs. 2 if absent.
-# Hard-fails (exits non-zero via die) if jq is missing — without jq we cannot
-# distinguish "absent" from "missing-tool" and would falsely re-add an existing
-# source. jq is documented as a dependency of gstack-gbrain-detect (transitive)
-# but adversarial review flagged the silent-fall-through path; this probe makes
-# the failure mode loud.
+# Hard-fails (exits non-zero via die) if the JSON reader is unavailable: we
+# could not then tell "absent" from "missing tool" and would falsely re-add an
+# existing source.
 check_source_state() {
   local id="$1"
-  if ! command -v jq >/dev/null 2>&1; then
-    die "jq required for source state detection. Install jq (brew install jq) and re-run." 1
+  if ! command -v bun >/dev/null 2>&1; then
+    die "bun required for source state detection. Install bun (https://bun.sh) and re-run." 1
   fi
   local existing_path
-  existing_path=$(gbrain sources list --json 2>/dev/null \
-    | jq -r --arg id "$id" '.sources[] | select(.id==$id) | .local_path' 2>/dev/null \
-    | tr -d '[:space:]') || existing_path=""
+  existing_path=$(source_local_path "$id") || existing_path=""
   if [ -z "$existing_path" ]; then
     return 2
   fi
@@ -299,9 +312,7 @@ do_wireup() {
       # registration. Just sync from our local worktree — gbrain stores pages
       # by content, not by local_path. The metadata is informational only.
       local existing_path
-      existing_path=$(gbrain sources list --json 2>/dev/null \
-        | jq -r --arg id "$id" '.sources[] | select(.id==$id) | .local_path' 2>/dev/null \
-        | tr -d '[:space:]') || existing_path=""
+      existing_path=$(source_local_path "$id") || existing_path=""
       if [ "$(basename "$existing_path")" = "$(basename "$WORKTREE")" ] \
          && [ "$existing_path" != "$WORKTREE" ]; then
         warn "source $id is registered at $existing_path (likely another machine's local copy of the same brain repo). Skipping re-registration; will sync from local worktree."

bin/gstack-gbrain-sync.ts

@@ -29,7 +29,7 @@
  * than building a gstack-side daemon.
  */
 
-import { existsSync, statSync, mkdirSync, writeFileSync, readFileSync, unlinkSync, renameSync, realpathSync } from "fs";
+import { existsSync, statSync, mkdirSync, writeFileSync, readFileSync, unlinkSync, renameSync, realpathSync, readdirSync, appendFileSync } from "fs";
 import { join, dirname } from "path";
 import { execSync, spawnSync } from "child_process";
 import { homedir, hostname } from "os";
@@ -37,10 +37,21 @@ import { createHash } from "crypto";
 
 import "../lib/conductor-env-shim";
 import { detectEngineTier, withErrorContext, canonicalizeRemote } from "../lib/gstack-memory-helpers";
-import { ensureSourceRegistered, sourcePageCount, parseSourcesList, cycleCompleted, type CycleStatus } from "../lib/gbrain-sources";
+import {
+  constrainSourceId,
+  ensureSourceRegistered,
+  sourcePageCount,
+  parseSourcesList,
+  readCycleStatus,
+  decidePrune,
+  trackUnavailableSources,
+  type CodeSourceRecord,
+  type CycleStatus,
+  type UnavailableSource,
+} from "../lib/gbrain-sources";
 import { detectAutopilot, decideSourceRemove, decideCodeSync } from "../lib/gbrain-guards";
 import { writeReceipt } from "../lib/egress-receipt";
-import { localEngineStatus, type LocalEngineStatus } from "../lib/gbrain-local-status";
+import { dbUnreachableReason, localEngineStatus, localEngineStatusDetail, type LocalEngineStatus } from "../lib/gbrain-local-status";
 import { buildGbrainEnv, spawnGbrain, spawnGbrainAsync, execGbrainJson, NEEDS_SHELL_ON_WINDOWS, bashScriptInvocation } from "../lib/gbrain-exec";
 import { repoPolicyTier as sharedRepoPolicyTier } from "../lib/gbrain-repo-policy-client";
 import { checkOwnedStagingDir } from "../lib/staging-guard";
@@ -73,6 +84,8 @@ export interface CliArgs {
   allowReclone: boolean;
   /** #2922: `--sources <list|all>` for the memory stage; wins over GSTACK_MEMORY_INGEST_SOURCES. */
   memorySources?: string;
+  /** A6: remove gstack code sources whose worktree is provably gone (with --dry-run: report only). */
+  pruneGone?: boolean;
 }
 
 interface CodeStageDetail {
@@ -225,6 +238,13 @@ export function resolveMemoryIngestSources(
  * state root itself), if any. Its pages already cover FEDERATED_CURATED_TYPES.
  */
 export function federatedCuratedSourceId(env?: NodeJS.ProcessEnv): string | null {
+  const rows = parseSourcesList(execGbrainJson(["sources", "list", "--json"], { baseEnv: env, timeout: 10_000 }));
+  const row = rows.find((r) => (r as { federated?: boolean }).federated === true && isArtifactsSourceRow(r, env));
+  return row?.id ?? null;
+}
+
+/** A source this installation maintains for its curated artifacts (the worktree or the state root). */
+function isArtifactsSourceRow(r: { local_path?: string }, env?: NodeJS.ProcessEnv): boolean {
   const realOrSelf = (p: string): string => {
     try {
       return realpathSync(p);
@@ -237,9 +257,36 @@ export function federatedCuratedSourceId(env?: NodeJS.ProcessEnv): string | null
     realOrSelf((env ?? process.env).GSTACK_BRAIN_WORKTREE || join(home, ".gstack-brain-worktree")),
     realOrSelf(GSTACK_HOME),
   ]);
-  const rows = parseSourcesList(execGbrainJson(["sources", "list", "--json"], { baseEnv: env, timeout: 10_000 }));
-  const row = rows.find((r) => (r as { federated?: boolean }).federated === true && r.local_path && owned.has(realOrSelf(r.local_path)));
-  return row?.id ?? null;
+  return !!r.local_path && owned.has(realOrSelf(r.local_path));
+}
+
+/**
+ * A5 (#2670): after a successful artifacts push, report what gbrain actually
+ * holds. A git push is not indexing; a maintained artifacts source with zero
+ * pages is the one provably broken state and fails the stage.
+ */
+export function brainSyncIndexVerdict(env: NodeJS.ProcessEnv = process.env): { ok: boolean; summary: string } {
+  const raw = execGbrainJson(["sources", "list", "--json"], { baseEnv: env, timeout: 10_000 });
+  if (raw === null) {
+    return { ok: true, summary: "curated artifacts pushed to git; gbrain page count unavailable (gbrain sources list failed)" };
+  }
+  const explicit = env.GSTACK_BRAIN_SOURCE_ID;
+  const row = parseSourcesList(raw).find((r) => (explicit ? r.id === explicit : isArtifactsSourceRow(r, env)));
+  if (!row?.id) {
+    return { ok: true, summary: "curated artifacts pushed to git (no gbrain artifacts source on this machine, so indexing is not checked here)" };
+  }
+  if (typeof row.page_count !== "number") {
+    return { ok: true, summary: `curated artifacts pushed to git; gbrain source ${row.id} did not report a page count` };
+  }
+  if (row.page_count === 0) {
+    return {
+      ok: false,
+      summary:
+        `curated artifacts pushed to git, but gbrain source ${row.id} has 0 indexed pages. ` +
+        `Fix: gbrain sync --source ${row.id}, then re-run /sync-gbrain`,
+    };
+  }
+  return { ok: true, summary: `curated artifacts pushed; gbrain source ${row.id} has ${row.page_count} pages` };
 }
 
 export interface MemorySourceSelection {
@@ -463,6 +510,11 @@ Options:
                        Runs lock-free AFTER the sync stages. ~minutes. Default
                        timeout 45min, override GSTACK_SYNC_DREAM_TIMEOUT_MS.
   --no-dream           Opt out of the dream cycle that --full would auto-run.
+  --prune-gone-worktrees  Remove gstack code sources whose worktree is provably
+                       gone: missing on 2 consecutive syncs, created on this
+                       host (its id recomputes from host + path), and no
+                       longer listed by its repository. Prints the plan first;
+                       add --dry-run to only print it. Never automatic.
   --allow-reclone      Permit the code walk for URL-managed sources (remote_url set)
                        even though gbrain may auto-reclone the working tree (#1734).
   --sources <list>     Memory types to ingest (comma-separated, or \`all\`):
@@ -499,6 +551,7 @@ function parseArgs(): CliArgs {
   let noDream = false;
   let allowReclone = false;
   let memorySources: string | undefined;
+  let pruneGone = false;
 
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -527,6 +580,7 @@ function parseArgs(): CliArgs {
       // --no-dream can override) — do NOT set dream from --full here.
       case "--dream": dream = true; break;
       case "--no-dream": noDream = true; break;
+      case "--prune-gone-worktrees": pruneGone = true; break;
       case "--help":
       case "-h":
         printUsage();
@@ -538,7 +592,7 @@ function parseArgs(): CliArgs {
     }
   }
 
-  return { mode, quiet, noCode, noMemory, noBrainSync, codeOnly, dream, noDream, allowReclone, memorySources };
+  return { mode, quiet, noCode, noMemory, noBrainSync, codeOnly, dream, noDream, allowReclone, memorySources, pruneGone };
 }
 
 // ── Helpers ────────────────────────────────────────────────────────────────
@@ -580,10 +634,9 @@ function originUrl(): string | null {
  * optional interior hyphens. `constrainSourceId` handles the 32-char cap
  * with a hashed-tail fallback when the combined slug exceeds budget.
  */
-function deriveCodeSourceId(repoPath: string): string {
+export function deriveCodeSourceId(repoPath: string, remote: string = canonicalizeRemote(originUrl())): string {
   const host = process.env.GSTACK_HOSTNAME || hostname();
   const hostPathHash = createHash("sha1").update(`${host}::${repoPath}`).digest("hex").slice(0, 8);
-  const remote = canonicalizeRemote(originUrl());
   if (remote) {
     const segs = remote.split("/").filter(Boolean);
     const slugSource = segs.slice(-2).join("-");
@@ -839,49 +892,6 @@ export function removeOrphanedSource(oldId: string, env?: NodeJS.ProcessEnv): bo
   return safeSourcesRemove(oldId, env).removed;
 }
 
-/**
- * Build a gbrain-valid source id (1-32 lowercase alnum + interior hyphens). Sanitizes
- * `raw`, prefixes with `prefix`, and falls back to a hashed-tail form when total length
- * would exceed 32 chars.
- *
- * Truncation cuts on hyphen boundaries (whole-word units) from the right, never
- * mid-word. Inputs like "drummerms-av-sow-wiz-skill-270c0001" produce
- * "${prefix}-270c0001-<hash>", not "${prefix}-kill-270c0001-<hash>".
- */
-function constrainSourceId(prefix: string, raw: string): string {
-  const MAX = 32;
-  const slug = raw.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  // Empty slug after sanitize (e.g. raw was all non-alnum like "___") would
-  // produce "${prefix}-" which fails gbrain's validator on the trailing
-  // hyphen. Fall back to a deterministic hash of the original input so the
-  // result is stable across runs of the same repo.
-  if (!slug) {
-    const hash = createHash("sha1").update(raw || "_empty").digest("hex").slice(0, 6);
-    return `${prefix}-${hash}`;
-  }
-  const full = `${prefix}-${slug}`;
-  if (full.length <= MAX) return full;
-  const hash = createHash("sha1").update(slug).digest("hex").slice(0, 6);
-  // Total budget: prefix + "-" + tail + "-" + hash
-  const tailBudget = MAX - prefix.length - 2 - hash.length;
-  if (tailBudget < 1) return `${prefix}-${hash}`;
-  // Cut on hyphen boundaries instead of mid-word. Walk tokens from the right,
-  // accumulating until adding the next token would exceed tailBudget. This
-  // preserves readable suffixes (pathhash, repo name) and avoids embarrassing
-  // mid-word artifacts like "skill" → "kill".
-  const tokens = slug.split("-").filter(Boolean);
-  const kept: string[] = [];
-  let len = 0;
-  for (let i = tokens.length - 1; i >= 0; i--) {
-    const add = kept.length === 0 ? tokens[i].length : tokens[i].length + 1;
-    if (len + add > tailBudget) break;
-    kept.unshift(tokens[i]);
-    len += add;
-  }
-  const tail = kept.join("-");
-  return tail ? `${prefix}-${tail}-${hash}` : `${prefix}-${hash}`;
-}
-
 // ── Lock file (D1) ─────────────────────────────────────────────────────────
 
 interface LockInfo {
@@ -1017,6 +1027,7 @@ function skipStageForLocalStatus(
       "PGLite is busy (often held by gbrain serve); stop the holding process or run /sync-gbrain outside the live Claude session, then retry",
     "timeout":
       "engine probe timed out; raise GSTACK_GBRAIN_PROBE_TIMEOUT_MS if your pooler is slow",
+    "db-unreachable": localEngineStatusDetail() ?? dbUnreachableReason("network error", ""),
     "thin-client":
       "thin client (remote-HTTP MCP brain, no local engine by design, #2051); " +
       "code indexing runs on the brain server, memory syncs via the remote " +
@@ -1670,13 +1681,10 @@ function runBrainSyncPush(args: CliArgs): StageResult {
   spawnSync(discover.cmd, discover.argv, { stdio, timeout: 60 * 1000, shell: discover.shell });
   const result = spawnSync(once.cmd, once.argv, { stdio, timeout: 60 * 1000, shell: once.shell });
 
-  return {
-    name: "brain-sync",
-    ran: true,
-    ok: result.status === 0,
-    duration_ms: Date.now() - t0,
-    summary: result.status === 0 ? "curated artifacts pushed" : `gstack-brain-sync exited ${result.status}`,
-  };
+  if (result.status !== 0) {
+    return { name: "brain-sync", ran: true, ok: false, duration_ms: Date.now() - t0, summary: `gstack-brain-sync exited ${result.status}` };
+  }
+  return { name: "brain-sync", ran: true, duration_ms: Date.now() - t0, ...brainSyncIndexVerdict() };
 }
 
 /**
@@ -1712,6 +1720,16 @@ export function shouldRunDream(args: CliArgs, cycle: CycleStatus | null): boolea
  * binary / malformed env) — a broken install must be visible, not disguised as
  * optional maintenance.
  */
+/**
+ * A7: detected, not assumed. gbrain validates --phase values while parsing,
+ * before --help prints, so a gbrain without the phase exits non-zero and one
+ * without --phase prints help that never mentions it.
+ */
+export function gbrainSupportsSymbolEdgePhase(env: NodeJS.ProcessEnv = process.env): boolean {
+  const r = spawnGbrain(["dream", "--phase", "resolve_symbol_edges", "--help"], { baseEnv: env, timeout: 15_000 });
+  return r.status === 0 && /--phase\b/.test(`${r.stdout || ""}${r.stderr || ""}`);
+}
+
 export async function runDream(args: CliArgs): Promise<StageResult> {
   const t0 = Date.now();
 
@@ -1724,8 +1742,8 @@ export async function runDream(args: CliArgs): Promise<StageResult> {
       ok: true,
       duration_ms: 0,
       summary: sourceId
-        ? `would: gbrain dream --source ${sourceId}  (build this source's call graph)`
-        : "would: gbrain dream  (call-graph build)",
+        ? `would: gbrain dream --source ${sourceId} --phase resolve_symbol_edges  (build this source's call graph; skipped if gbrain cannot scope the phase)`
+        : "would: gbrain dream --phase resolve_symbol_edges  (call-graph build; skipped if gbrain cannot scope the phase)",
     };
   }
 
@@ -1766,7 +1784,24 @@ export async function runDream(args: CliArgs): Promise<StageResult> {
     // only when we can't derive the source id (not in a git repo).
     const root = repoRoot();
     const sourceId = root ? resolveCodeSourceId(root, gbrainEnv) : null;
-    const dreamArgs = sourceId ? ["dream", "--source", sourceId] : ["dream"];
+    // A7 (#2783): the call graph needs only the resolve_symbol_edges phase. A
+    // full `gbrain dream` runs every maintenance phase, LLM ones included
+    // (~35 min). Scope it when the installed gbrain can; never fall back to
+    // the full cycle on its own.
+    if (!gbrainSupportsSymbolEdgePhase()) {
+      return {
+        name: "dream",
+        ran: false,
+        ok: true,
+        duration_ms: Date.now() - t0,
+        summary:
+          "skipped — the installed gbrain cannot run only the resolve_symbol_edges phase, and the full dream cycle " +
+          `costs about 35 minutes (LLM phases). Upgrade with gstack-gbrain-install, or run it yourself: gbrain dream${sourceId ? ` --source ${sourceId}` : ""}`,
+      };
+    }
+    const dreamArgs = sourceId
+      ? ["dream", "--source", sourceId, "--phase", "resolve_symbol_edges"]
+      : ["dream", "--phase", "resolve_symbol_edges"];
 
     // spawnGbrain seeds DATABASE_URL from gbrain's config via buildGbrainEnv.
     //
@@ -1931,6 +1966,10 @@ interface SyncState {
   last_sync?: string;
   last_full_sync?: string;
   last_stages?: StageResult[];
+  /** A6: gstack code sources whose path was missing, with consecutive-miss counts. */
+  unavailable_sources?: Record<string, UnavailableSource>;
+  /** A6: what this machine knew about each code source it synced (ownership proof). */
+  code_sources?: Record<string, CodeSourceRecord>;
 }
 
 function loadSyncState(): SyncState {
@@ -1989,8 +2028,124 @@ export function formatStage(s: StageResult): string {
 
 // ── Main ───────────────────────────────────────────────────────────────────
 
+// ── Gone worktree sources (A6, #2688) ──────────────────────────────────────
+
+function gitCommonDir(root: string): string | null {
+  const r = spawnSync("git", ["-C", root, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf-8", timeout: 5000 });
+  return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : null;
+}
+
+function currentCodeSourceRecord(): CodeSourceRecord | null {
+  const root = repoRoot();
+  return root ? { path: root, remote: canonicalizeRemote(originUrl()), git_common_dir: gitCommonDir(root) } : null;
+}
+
+/** Remember which repository a synced code source belongs to (the prune ownership proof). */
+function recordCodeSource(state: SyncState, stages: StageResult[]): void {
+  const code = stages.find((s) => s.name === "code" && s.ran && s.ok);
+  const id = code?.detail?.source_id;
+  const record = currentCodeSourceRecord();
+  if (!id || !record || code?.detail?.source_path !== record.path) return;
+  (state.code_sources ??= {})[id] = record;
+}
+
+/**
+ * Count consecutive syncs that find a gstack code source's path missing, and
+ * say so once per source. gstack never removes such a source on its own.
+ */
+function trackGoneSources(state: SyncState, quiet: boolean): void {
+  const raw = execGbrainJson(["sources", "list", "--json"], { timeout: 10_000 });
+  if (raw === null) return;
+  const { next, newlyUnavailable } = trackUnavailableSources(parseSourcesList(raw), state.unavailable_sources ?? {}, existsSync, new Date().toISOString());
+  state.unavailable_sources = next;
+  for (const id of newlyUnavailable) {
+    console.error(
+      `[gbrain-sync] gbrain source ${id}: path unavailable (${next[id].path}); gstack skips it. ` +
+        `If that worktree was deleted, review removal with: gstack-gbrain-sync --prune-gone-worktrees --dry-run`,
+    );
+  }
+  if (!quiet && newlyUnavailable.length === 0 && Object.keys(next).length > 0) {
+    console.error(`[gbrain-sync] ${Object.keys(next).length} gbrain source(s) still have an unavailable path (see --prune-gone-worktrees --dry-run)`);
+  }
+}
+
+function readableDir(p: string): boolean {
+  try {
+    readdirSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function worktreeListed(gitDir: string, path: string): boolean | null {
+  const r = spawnSync("git", [`--git-dir=${gitDir}`, "worktree", "list", "--porcelain"], { encoding: "utf-8", timeout: 10_000 });
+  if (r.status !== 0) return null;
+  return r.stdout.split("\n").some((line) => line === `worktree ${path}`);
+}
+
+/**
+ * `--prune-gone-worktrees`: remove gstack code sources whose worktree is
+ * provably gone (lib/gbrain-sources.ts decidePrune). Prints the plan first;
+ * with --dry-run that is all it does. Each removal re-checks the path right
+ * before removing and is logged to ~/.gstack/.gbrain-prune.log.
+ */
+function pruneGoneWorktrees(dryRun: boolean): number {
+  const raw = execGbrainJson(["sources", "list", "--json"], { timeout: 10_000 });
+  if (raw === null) {
+    console.error("[prune] gbrain sources list failed; nothing removed. Fix: run /setup-gbrain, then retry.");
+    return 1;
+  }
+  if (!dryRun && !acquireLock()) {
+    console.error(`[prune] another /sync-gbrain is running (lock at ${LOCK_PATH}); nothing removed.`);
+    return 2;
+  }
+  try {
+    const state = loadSyncState();
+    const ctx = {
+      unavailable: state.unavailable_sources ?? {},
+      records: state.code_sources ?? {},
+      current: currentCodeSourceRecord(),
+      deriveId: deriveCodeSourceId,
+      exists: existsSync,
+      readableDir,
+      worktreeListed,
+    };
+    const rows = parseSourcesList(raw).filter((r) => r.id?.startsWith("gstack-code-") && r.local_path && !existsSync(r.local_path));
+    if (rows.length === 0) {
+      console.log("[prune] no gstack code source has a missing path; nothing to do.");
+      return 0;
+    }
+    const plan = rows.map((r) => ({ id: r.id!, path: r.local_path!, ...decidePrune(r.id!, r.local_path!, ctx) }));
+    for (const p of plan) console.log(`[prune]${dryRun ? " (dry run)" : ""} ${p.remove ? "would remove" : "keep"} ${p.id} (${p.path}): ${p.reason}`);
+    if (dryRun) return 0;
+    let failed = 0;
+    for (const p of plan.filter((x) => x.remove)) {
+      if (existsSync(p.path)) {
+        console.log(`[prune] keep ${p.id}: ${p.path} exists again`);
+        continue;
+      }
+      const r = safeSourcesRemove(p.id);
+      const line = `${new Date().toISOString()} ${r.removed ? "removed" : "not removed"} ${p.id} ${p.path}: ${r.removed ? p.reason : r.reason}`;
+      console.log(`[prune] ${line}`);
+      try {
+        appendFileSync(join(GSTACK_HOME, ".gbrain-prune.log"), line + "\n");
+      } catch {}
+      if (r.removed) {
+        delete state.unavailable_sources?.[p.id];
+        delete state.code_sources?.[p.id];
+      } else failed++;
+    }
+    saveSyncState(state);
+    return failed > 0 ? 1 : 0;
+  } finally {
+    if (!dryRun) releaseLock();
+  }
+}
+
 async function main(): Promise<void> {
   const args = parseArgs();
+  if (args.pruneGone) process.exit(pruneGoneWorktrees(args.mode === "dry-run"));
   // Read once at sync start: a config change made while the sync runs never
   // adds transcripts to this run.
   const consent = args.noMemory ? null : readTranscriptConsent();
@@ -2039,6 +2194,8 @@ async function main(): Promise<void> {
       state.last_sync = new Date().toISOString();
       if (args.mode === "full") state.last_full_sync = state.last_sync;
       state.last_stages = stages;
+      recordCodeSource(state, stages);
+      trackGoneSources(state, args.quiet);
       saveSyncState(state);
     }
 
@@ -2065,10 +2222,13 @@ async function main(): Promise<void> {
     // Resolve cycle state only on the --full auto path (perf: the steady-state
     // incremental sync never pays a doctor subprocess). Explicit --dream forces.
     let cycle: CycleStatus | null = null;
+    let cycleWhy = "not in a git repo";
     if (!args.dream && args.mode === "full" && !args.noDream && !args.noCode) {
       const root = repoRoot();
       const gbrainEnv = buildGbrainEnv({ announce: !args.quiet });
-      cycle = root ? cycleCompleted(resolveCodeSourceId(root, gbrainEnv), gbrainEnv) : "unknown";
+      const read = root ? readCycleStatus(resolveCodeSourceId(root, gbrainEnv), gbrainEnv) : { status: "unknown" as const };
+      cycle = read.status;
+      cycleWhy = read.why ?? "gbrain doctor did not say whether this source cycled";
     }
     if (shouldRunDream(args, cycle)) {
       dreamStage = await runDream(args);
@@ -2084,7 +2244,7 @@ async function main(): Promise<void> {
         ran: false,
         ok: true,
         duration_ms: 0,
-        summary: "call-graph state unknown (doctor unavailable) — run /sync-gbrain --dream if code-callers returns 0",
+        summary: `call-graph state unknown (${cycleWhy}) — run /sync-gbrain --dream if code-callers returns 0`,
       };
     }
   }
@@ -2096,6 +2256,10 @@ async function main(): Promise<void> {
     const okCount = allStages.filter((s) => s.ok).length;
     const errCount = allStages.filter((s) => !s.ok && s.ran).length;
     console.log(`\n  ${okCount} ok, ${errCount} error, ${allStages.length - okCount - errCount} skipped`);
+    const gone = Object.keys(loadSyncState().unavailable_sources ?? {}).length;
+    if (gone > 0) {
+      console.log(`  ${gone} gbrain source(s) have an unavailable path; review with: gstack-gbrain-sync --prune-gone-worktrees --dry-run`);
+    }
   }
 
   process.exit(exitCode);

bin/gstack-ios-qa-daemon

@@ -21,6 +21,37 @@
 # session tokens are outstanding.
 
 set -euo pipefail
+# The --help heredoc is over 512 bytes; keep it off a pipe (test/heredoc-pipe-deadlock.test.ts).
+BASH_COMPAT=50
+
+case "${1:-}" in
+  -h|--help)
+    cat <<'EOF'
+Usage:
+  gstack-ios-qa-daemon [--tailnet]
+  gstack-ios-qa-daemon --help
+
+Mac-side broker for /ios-qa and /ios-design-review. By default it binds a
+loopback listener for a USB-connected iPhone running the in-app StateServer.
+Pass --tailnet to also open the Tailscale listener after the local tailscaled
+identity probe succeeds.
+
+Options:
+  --tailnet   Enable the authenticated tailnet listener in addition to loopback.
+  -h, --help  Print this help and exit without starting the daemon.
+
+Environment:
+  GSTACK_IOS_DAEMON_PORT       Loopback listener port. Default: 9099.
+  GSTACK_IOS_TARGET_UDID       Target iOS device UDID. Optional.
+  GSTACK_IOS_TARGET_BUNDLE_ID  Bundle ID hosting StateServer. Default: com.gstack.iosqa.fixture.
+
+Readiness:
+  The daemon prints "READY: port=<n> pid=<pid>" once the listener is bound.
+  Probe local health with: curl -sf http://127.0.0.1:${GSTACK_IOS_DAEMON_PORT:-9099}/healthz
+EOF
+    exit 0
+    ;;
+esac
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 GSTACK_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"

bin/gstack-jsonl-merge

@@ -45,7 +45,7 @@ BASE="$1"
 OURS="$2"
 THEIRS="$3"
 
-TMP=$(mktemp /tmp/gstack-jsonl-merge.XXXXXX) || exit 1
+TMP=$(mktemp "${TMPDIR:-/tmp}/gstack-jsonl-merge.XXXXXX") || exit 1
 trap 'rm -f "$TMP" 2>/dev/null || true' EXIT
 
 python3 - "$BASE" "$OURS" "$THEIRS" > "$TMP" <<'PYEOF'

bin/gstack-learnings-log

@@ -24,7 +24,7 @@ INPUT="$1"
 # Validate and sanitize input. Errors surface (#1950): stderr is captured and
 # printed on failure instead of swallowed — a silent exit 1 here cost Windows
 # users every AI-logged learning.
-TMPERR=$(mktemp)
+TMPERR=$(mktemp "${TMPDIR:-/tmp}/gstack-learnings-log.XXXXXX") || { echo "gstack-learnings-log: could not create a temp file in ${TMPDIR:-/tmp}, so the learning was not recorded. Fix: point TMPDIR at a writable directory." >&2; exit 1; }
 trap 'rm -f "$TMPERR"' EXIT
 set +e
 VALIDATED=$(printf '%s' "$INPUT" | GSTACK_LIB_DIR="$SCRIPT_DIR/../lib" bun -e "

bin/gstack-learnings-search

@@ -4,7 +4,9 @@
 #
 # Reads ~/.gstack/projects/$SLUG/learnings.jsonl, applies confidence decay,
 # resolves duplicates (latest winner per key+type), and outputs formatted text.
-# Exit 0 silently if no learnings file exists.
+# Exit 0 silently if no learnings file exists or nothing matches. Missing bun
+# exits 127 and a failed read exits non-zero with its stderr (#2790): "could
+# not read" must never look like "nothing recorded".
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
@@ -45,6 +47,11 @@ if [ ! -f "$LEARNINGS_FILE" ] && [ ${#CROSS_FILES[@]} -eq 0 ]; then
   exit 0
 fi
 
+command -v bun >/dev/null 2>&1 || {
+  echo "gstack-learnings-search: bun not found on PATH, so learnings could not be read. Fix: install Bun (https://bun.sh), then re-run ./setup." >&2
+  exit 127
+}
+
 emit_tagged_file() {
   local tag="$1"
   local file="$2"
@@ -121,25 +128,37 @@ let results = Array.from(seen.values());
 // Filter by type
 if (type) results = results.filter(e => e.type === type);
 
-// Filter by query (token-OR: match if ANY whitespace-split token appears in ANY haystack)
+// Filter by query (token-OR: match if ANY whitespace-split token appears in ANY
+// haystack) and count how many distinct tokens each entry matched (#2762). The
+// count lives in a local map, never on the entry: a stored field from disk
+// must not become a sort key.
+const tokenHits = new Map();
 if (queryTokens.length > 0) results = results.filter(e => {
-  const haystacks = [(e.key || '').toLowerCase(), (e.insight || '').toLowerCase(), ...(e.files || []).map(f => f.toLowerCase())];
-  return queryTokens.some(tok => haystacks.some(h => h.includes(tok)));
+  const haystacks = [String(e.key || '').toLowerCase(), String(e.insight || '').toLowerCase(), ...(Array.isArray(e.files) ? e.files : []).map(f => String(f).toLowerCase())];
+  const hits = [...new Set(queryTokens)].filter(tok => haystacks.some(h => h.includes(tok))).length;
+  tokenHits.set(e, hits);
+  return hits > 0;
 });
 
-// Sort by effective confidence desc, then recency
+// Sort by matched tokens desc, then effective confidence desc, then recency.
+// Ranking on confidence alone let high-confidence single-token matches push an
+// entry matching every token past the limit.
 results.sort((a, b) => {
+  const ah = tokenHits.get(a) || 0, bh = tokenHits.get(b) || 0;
+  if (bh !== ah) return bh - ah;
   if (b._effectiveConfidence !== a._effectiveConfidence) return b._effectiveConfidence - a._effectiveConfidence;
   return new Date(b.ts).getTime() - new Date(a.ts).getTime();
 });
 
-// Limit
+// Limit, and say when a query matched more than fit.
+const totalMatched = results.length;
 results = results.slice(0, limit);
 
 if (results.length === 0) process.exit(0);
 
-// Format output
-const byType = {};
+// Format output. A null-prototype map: a row typed 'constructor' or
+// '__proto__' must not find an inherited property and blank the whole run.
+const byType = Object.create(null);
 for (const e of results) {
   const t = e.type || 'unknown';
   if (!byType[t]) byType[t] = [];
@@ -148,7 +167,10 @@ for (const e of results) {
 
 // Summary line
 const counts = Object.entries(byType).map(([t, arr]) => arr.length + ' ' + t + (arr.length > 1 ? 's' : ''));
-console.log('LEARNINGS: ' + results.length + ' loaded (' + counts.join(', ') + ')');
+const moreNotice = queryTokens.length > 0 && totalMatched > results.length
+  ? ' -- ' + (totalMatched - results.length) + ' more matched, raise --limit to see them'
+  : '';
+console.log('LEARNINGS: ' + results.length + ' loaded (' + counts.join(', ') + ')' + moreNotice);
 console.log('');
 
 for (const [t, arr] of Object.entries(byType)) {
@@ -161,4 +183,4 @@ for (const [t, arr] of Object.entries(byType)) {
   }
   console.log('');
 }
-" 2>/dev/null || exit 0
+"

bin/gstack-next-version

@@ -27,8 +27,11 @@
 // provide (#2501).
 //
 // Exit codes:
-//   0 — emitted JSON successfully (may include "offline":true or "host":"unknown")
-//   2 — invalid arguments
+//   0 — emitted JSON successfully (may include "offline":true or "host":"unknown",
+//       or "no_version":true with "version":null when no version source is
+//       configured — see resolveVersionSource in lib/version-source.ts)
+//   2 — invalid arguments, or a configured version source that is missing,
+//       empty, unreadable or malformed
 //   3 — util bug (unexpected exception)
 
 import { execFileSync, spawnSync } from "node:child_process";
@@ -43,6 +46,9 @@ import {
   cmpVersion,
   bumpWasCoerced,
   extractVersion,
+  noVersionNotice,
+  resolveVersionRel,
+  resolveVersionSource,
   type Bump,
   type Version,
   type VersionWidth,
@@ -115,17 +121,11 @@ function runCommand(cmd: string, args: string[], timeoutMs = 15000): { ok: boole
 // at repo root > "VERSION". Pure function; takes the repo root as an argument so
 // tests can drive it with a fixture dir without mocking git.
 function resolveVersionPath(override: string | undefined, repoRoot: string): string {
-  if (override) return override.trim();
-  const configFile = join(repoRoot, ".gstack", "version-path");
-  if (existsSync(configFile)) {
-    try {
-      const firstLine = readFileSync(configFile, "utf8").split("\n")[0]?.trim() ?? "";
-      if (firstLine) return firstLine;
-    } catch {
-      // fall through to default
-    }
+  try {
+    return resolveVersionRel(repoRoot, override).rel;
+  } catch {
+    return "VERSION";
   }
-  return "VERSION";
 }
 
 function repoToplevel(): string {
@@ -683,7 +683,32 @@ async function main() {
   const warnings: string[] = [];
   const host = detectHost();
   const repoRoot = repoToplevel();
-  const versionPath = resolveVersionPath(args.versionPath, repoRoot);
+  // One no-version signal (#2334, #2343): the same four-outcome resolution
+  // gstack-version-bump uses. No configured source → report no_version and
+  // allocate nothing; a broken configured source → stop with the reason.
+  const src = resolveVersionSource(repoRoot, args.versionPath);
+  if (src.outcome === "broken") {
+    console.error(`Error: version source is broken: ${src.reason}. Fix that file or its pin (gstack never substitutes 0.0.0.0).`);
+    process.exit(2);
+  }
+  if (src.outcome !== "valid") {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          version: null,
+          no_version: true,
+          version_source: { outcome: src.outcome, path: src.path, reason: src.reason },
+          notice: noVersionNotice(src),
+          bump: args.bump,
+          warnings,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+  const versionPath = src.path!;
   const baseVersion = args.current || readBaseVersion(args.base, versionPath, repoRoot, warnings);
   const baseParsed = parseVersion(baseVersion);
   if (!baseParsed) {

bin/gstack-question-log

@@ -43,7 +43,7 @@ mkdir -p "$GSTACK_HOME/projects/$SLUG"
 INPUT="$1"
 
 # Validate and enrich from registry.
-TMPERR=$(mktemp)
+TMPERR=$(mktemp "${TMPDIR:-/tmp}/gstack-question-log.XXXXXX") || { echo "gstack-question-log: could not create a temp file in ${TMPDIR:-/tmp}, so the question was not logged. Fix: point TMPDIR at a writable directory." >&2; exit 1; }
 trap 'rm -f "$TMPERR"' EXIT
 set +e
 VALIDATED=$(printf '%s' "$INPUT" | GSTACK_LIB_DIR="$SCRIPT_DIR/../lib" bun -e "

bin/gstack-question-preference

@@ -143,7 +143,7 @@ do_write() {
   fi
   ensure_file
   local TMPERR
-  TMPERR=$(mktemp)
+  TMPERR=$(mktemp "${TMPDIR:-/tmp}/gstack-question-preference.XXXXXX") || { echo "gstack-question-preference: could not create a temp file in ${TMPDIR:-/tmp}, so the preference was not saved. Fix: point TMPDIR at a writable directory." >&2; return 1; }
   # Use function-local cleanup via RETURN trap so variable lookup only happens
   # while the function is on the stack (avoids EXIT-trap unbound-var race).
   trap "rm -f '$TMPERR'" RETURN

bin/gstack-relink

@@ -299,6 +299,47 @@ _dir_only_links() {
   return 0
 }
 
+# _serve_rendered_assets SKILL TARGET — F5 (#2706): when the gbrain render has
+# a counterpart of a runtime asset setup linked from the checkout (sections/,
+# ...), serve the rendered file instead, per file (render dirs carry only the
+# generated *.md). An asset whose render counterpart is gone goes back to the
+# checkout. Only entries that are our links, or directories of nothing but our
+# links, are touched; anything else is the user's and stays.
+_serve_rendered_assets() {
+  local skill="$1" target="$2" asset name t child
+  for asset in "$INSTALL_DIR/$skill"/*; do
+    [ -e "$asset" ] || continue
+    name="${asset##*/}"
+    case "$name" in SKILL.md|node_modules|dist|test|*.tmpl) continue ;; esac
+    t="$target/$name"
+    if [ -L "$t" ]; then
+      _target_is_ours "$(_link_target_abs "$t")" || continue
+    elif [ -d "$t" ]; then
+      _dir_only_links "$t" || continue
+    else
+      continue
+    fi
+    if [ -d "$asset" ] && [ -d "$RENDER_DIR/$skill/$name" ]; then
+      rm -rf "$t"
+      mkdir -p "$t"
+      for child in "$asset"/*; do
+        [ -e "$child" ] || continue
+        if [ -f "$RENDER_DIR/$skill/$name/${child##*/}" ]; then
+          ln -snf "$RENDER_DIR/$skill/$name/${child##*/}" "$t/${child##*/}"
+        else
+          ln -snf "$child" "$t/${child##*/}"
+        fi
+      done
+    elif [ -f "$asset" ] && [ -f "$RENDER_DIR/$skill/$name" ]; then
+      rm -rf "$t"
+      ln -snf "$RENDER_DIR/$skill/$name" "$t"
+    elif [ -d "$t" ] && [ ! -L "$t" ] || [ "$(_link_target_abs "$t")" != "$asset" ]; then
+      rm -rf "$t"
+      ln -snf "$asset" "$t"
+    fi
+  done
+}
+
 _link_root_skill_alias() {
   local target="$SKILLS_DIR/_gstack-command"
 
@@ -330,7 +371,7 @@ _link_root_skill_alias() {
 
 _link_root_skill_alias
 
-# Discover skills (directories with SKILL.md, excluding meta dirs)
+# Discover skills: every top-level directory with a SKILL.md
 SKILL_COUNT=0
 for skill_dir in "$INSTALL_DIR"/*/; do
   [ -d "$skill_dir" ] || continue
@@ -340,8 +381,8 @@ for skill_dir in "$INSTALL_DIR"/*/; do
   # rewritten-copy alias for those.
   [ -L "${skill_dir%/}" ] && continue
   skill=$(basename "$skill_dir")
-  # Skip non-skill directories
-  case "$skill" in bin|browse|design|docs|extension|lib|node_modules|scripts|test|.git|.github) continue ;; esac
+  # A directory is a skill iff it carries a SKILL.md (#2263): a name list
+  # dropped the real browse skill. Support dirs have no SKILL.md.
   [ -f "$skill_dir/SKILL.md" ] || continue
   case "$DISABLED" in
     *" ${skill#gstack-} "*)
@@ -399,6 +440,7 @@ for skill_dir in "$INSTALL_DIR"/*/; do
     fi
   fi
   ln -snf "$skill_md_src" "$target/SKILL.md"
+  _serve_rendered_assets "$skill" "$target"
   # Provenance marker on every platform (path-independent proof; on Windows
   # without Developer Mode `ln -snf` degrades to a copy and this is the only
   # proof), but only for a directory we created or already owned.
@@ -414,6 +456,28 @@ done
 # for every brain-aware skill (#2738). gstack-patch-names takes an arbitrary
 # root, skips already-prefixed names (idempotent), and the render dir is
 # user-owned and untracked, so patching it never dirties a checkout.
+# C8 (#3018): Claude reads the router straight from the install root, so with
+# disabled_skills set it is re-rendered in place without their routing rules
+# (in place, like gstack-patch-names). Clearing the list restores the committed
+# bytes. Only a generated router is rewritten, and only from a checkout that
+# carries the generator; a failed render keeps the current router.
+_ROUTER="$INSTALL_DIR/SKILL.md"
+_GEN_SRC="$(cd "$SCRIPT_DIR/.." && pwd)"
+if { [ "$DISABLED" != " " ] || grep -q '^Disabled on this install' "$_ROUTER" 2>/dev/null; } \
+  && grep -q '<!-- AUTO-GENERATED from' "$_ROUTER" 2>/dev/null && [ -f "$_GEN_SRC/scripts/gen-skill-docs.ts" ]; then
+  _ROUTER_TMP="$(mktemp -d "${TMPDIR:-/tmp}/gstack-router.XXXXXX")" || _ROUTER_TMP=""
+  _DISABLED_CSV="$(printf '%s' "$DISABLED" | xargs | tr ' ' ',')"
+  if [ -n "$_ROUTER_TMP" ] && command -v bun >/dev/null 2>&1 \
+    && (cd "$_GEN_SRC" && bun run scripts/gen-skill-docs.ts --host claude --out-dir "$_ROUTER_TMP" ${_DISABLED_CSV:+"--disabled-skills=$_DISABLED_CSV"} >/dev/null 2>&1) \
+    && [ -s "$_ROUTER_TMP/SKILL.md" ] && cp "$_ROUTER_TMP/SKILL.md" "$_ROUTER.tmp.$$" && mv "$_ROUTER.tmp.$$" "$_ROUTER"; then
+    [ -n "$_DISABLED_CSV" ] && echo "Router: disabled skills left out of $_ROUTER"
+  else
+    rm -f "$_ROUTER.tmp.$$"
+    echo "gstack-relink: could not re-render the router for disabled_skills (bun missing or generation failed); $_ROUTER still lists every skill. Fix: install Bun, then run $0" >&2
+  fi
+  [ -z "$_ROUTER_TMP" ] || rm -rf "$_ROUTER_TMP"
+fi
+
 "$INSTALL_DIR/bin/gstack-patch-names" "$INSTALL_DIR" "$PREFIX"
 [ -d "$RENDER_DIR" ] && "$INSTALL_DIR/bin/gstack-patch-names" "$RENDER_DIR" "$PREFIX"
 

bin/gstack-render-claude.sh

@@ -103,7 +103,7 @@ gstack_claude_render_plain() {
   RENDER_TMP="$RENDER_DIR.tmp.$$"
   rm -rf "$RENDER_TMP"
   _gstack_render_say "Rendering Claude skills with the $_GSTACK_OVERLAY overlay into $RENDER_DIR (source checkout stays clean)..."
-  out="$(cd "$src" && _gstack_render_bun run gen:skill-docs --host claude --out-dir "$RENDER_TMP" --link-root "$RENDER_DIR" --model "$_GSTACK_OVERLAY" 2>&1)" || rc=$?
+  out="$(cd "$src" && _gstack_render_bun run gen:skill-docs --host claude --out-dir "$RENDER_TMP" --link-root "$RENDER_DIR" --model "$_GSTACK_OVERLAY" ${_DISABLED_CSV:+"--disabled-skills=$_DISABLED_CSV"} 2>&1)" || rc=$?
   if [ "$rc" -ne 0 ]; then
     rm -rf "$RENDER_TMP"
     printf '%s\n' "$out" | tail -3

bin/gstack-retro-metrics

@@ -105,11 +105,27 @@ _U=""
 # Emits COMMIT: lines (newest first, capped) plus every aggregate. Subjects may
 # contain '|', so fields are re-joined from index 6 on. Test-file detection is
 # the union of the historical patterns (dir-based test/|spec/|__tests__/ and
-# suffix-based .test./.spec./_test./_spec.).
+# suffix-based .test./.spec./_test./_spec.) plus the conventions other
+# languages name tests by: SwiftPM/XCTest Tests/ dirs and FooTests.swift,
+# pytest/minitest test_*.py|rb, Terraform *.tftest.hcl and Bats *.bats.
+# Generated output is skipped entirely and prose is never a test (#2812,
+# #2809, #2037).
 git log "$REF" "$_S" ${_U:+"$_U"} --date=format-local:'%Y-%m-%d %H:%M' \
     --format='C|%h|%aN|%at|%ad|%s' --numstat 2>/dev/null | awk '
+  # Generated output is not authored code: a committed build directory would
+  # dominate FOCUS_SCORE and count its Test/ subdirs as test LOC.
+  function is_generated(p) {
+    return (p ~ /(^|\/)(\.build|build|dist|out|target|vendor|node_modules|DerivedData|\.next|\.nuxt|__pycache__|coverage)\//)
+  }
+  # "spec" is overloaded: spec/ is RSpec, docs/.../specs/*.md are written specifications.
+  function is_prose(p) {
+    return (p ~ /\.(md|mdx|markdown|txt|rst|adoc)$/) || (p ~ /(^|\/)(docs?|documentation)\//)
+  }
   function is_test(p) {
-    return (p ~ /(^|\/)(tests?|spec|__tests__)\//) || (p ~ /(\.(test|spec)\.|_test\.|_spec\.)/)
+    if (is_prose(p)) return 0
+    return (p ~ /(^|\/)([Tt]ests?|[Ss]pecs?|__tests__)\//) || (p ~ /(\.(test|spec)\.|_test\.|_spec\.)/) \
+      || (p ~ /[A-Za-z0-9]([Tt]ests?|[Ss]pecs?)\.[A-Za-z0-9]+$/) || (p ~ /(^|\/)test_[^\/]*\.(py|rb)$/) \
+      || (p ~ /(\.tftest\.hcl|\.bats)$/)
   }
   function type_of(s) {
     if (s ~ /^Merge /) return "merge"
@@ -163,13 +179,14 @@ git log "$REF" "$_S" ${_U:+"$_U"} --date=format-local:'%Y-%m-%d %H:%M' \
     next
   }
   /^[0-9-]+\t/ {
+    if (is_generated($3)) next
     if ($1 != "-") cins += $1; if ($2 != "-") cdel += $2
     if ($1 != "-" && is_test($3)) ctins += $1
     cfiles++
     filecount[$3]++
     d = ($3 ~ /\//) ? substr($3, 1, index($3, "/") - 1) "/" : "(root)"
     dircount[d]++; adir[author "|" d]++
-    if ($3 ~ /(\.(test|spec)\.|_test\.|_spec\.)/) testfiles[$3] = 1
+    if (is_test($3)) testfiles[$3] = 1
   }
   END {
     flush()
@@ -299,10 +316,13 @@ echo "PRS_REFERENCED: $(printf '%s' "$_PRS" | wc -w | tr -d ' ')"
 [ -n "$_PRS" ] && echo "PR_REFS: $_PRS" || true
 
 # ── Test health (repo-wide + window) ─────────────────────────────────────────
-# Deliberately suffix-only (narrower than is_test's dir-based patterns): the
-# repo-wide census counts conventional test FILES; is_test additionally counts
-# dir-homed helpers toward test-insertion ratios.
-_TF_TOTAL=$(git ls-files 2>/dev/null | grep -cE '(\.test\.|\.spec\.|_test\.|_spec\.)' || true)
+# Deliberately filename-convention-only (narrower than is_test's dir-based
+# patterns): the repo-wide census counts conventional test FILES; is_test
+# additionally counts dir-homed helpers toward test-insertion ratios. Same
+# conventions as is_test's filename forms; generated output never counts.
+_TF_TOTAL=$(git ls-files 2>/dev/null \
+  | grep -vE '(^|/)(\.build|build|dist|out|target|vendor|node_modules|DerivedData|\.next|\.nuxt|__pycache__|coverage)/' \
+  | grep -cE '(\.test\.|\.spec\.|_test\.|_spec\.|[A-Za-z0-9](Tests?|Specs?)\.[A-Za-z0-9]+$|(^|/)test_[^/]*\.(py|rb)$|\.tftest\.hcl$|\.bats$)' || true)
 case "$_TF_TOTAL" in ''|*[!0-9]*) _TF_TOTAL=0 ;; esac
 echo "TEST_FILES_TOTAL: $_TF_TOTAL"
 _REG=$(git log "$REF" "$_S" ${_U:+"$_U"} --oneline --grep="test(qa):" --grep="test(design):" --grep="test: coverage" 2>/dev/null || true)

bin/gstack-security-dashboard

@@ -47,7 +47,7 @@ fi
 # Fetch with the HTTP status captured (#1947). A backend failure must read
 # as "unknown", never as a healthy "0 attacks" — fake zeros on a security
 # surface are indistinguishable from good news.
-TMPBODY="$(mktemp)"
+TMPBODY="$(mktemp "${TMPDIR:-/tmp}/gstack-security.XXXXXX")"
 trap 'rm -f "$TMPBODY"' EXIT
 SUPA_HOST="${SUPABASE_URL#*://}"; SUPA_HOST="${SUPA_HOST%%/*}"
 HTTP_CODE="$(_receipted_curl open security-dashboard "$SUPA_HOST" community-pulse-fetch "user-invoked dashboard" --no-payload \

bin/gstack-session-update

@@ -1,10 +1,17 @@
 #!/usr/bin/env bash
 # gstack-session-update — auto-update gstack on session start (team mode)
 #
-# Called by Claude Code SessionStart hook. Must be fast, silent, non-fatal.
+# Called by Claude Code SessionStart hook. Must be fast and non-fatal.
 # The entire update runs in background (forked). The hook itself exits
 # immediately so session startup is never delayed.
 #
+# Stages (B11): pull, setup and migrations are tracked separately. The
+# "just upgraded" marker is written only when every stage succeeded. A failed
+# stage is persisted in $STATE_DIR/session-update-pending and retried even
+# when HEAD did not move, with backoff (the update-check interval, then 6h,
+# then 24h). While a stage is pending, each session start prints one line
+# naming it and the repair command; nothing else is ever printed.
+#
 # Exit 0 always — errors must never block a Claude Code session.
 
 set +e
@@ -12,7 +19,7 @@ set +e
 GSTACK_DIR="${GSTACK_DIR:-$HOME/.claude/skills/gstack}"
 # Hook: source the state-root twin (never spawn gstack-paths); a broken
 # install exits 0 silently, like every other error here.
-. "$(cd "$(dirname "$0")" && pwd)/gstack-state-root.sh" 2>/dev/null || exit 0
+. "$(cd "$(dirname "$0")" && pwd)/gstack-state-root.sh" 2>/dev/null || exit 0  # best-effort: must never block a session start
 STATE_DIR="$(gstack_state_root; printf x)"; STATE_DIR="${STATE_DIR%x}"
 
 # Egress receipt helpers (_receipted_git): fail-open — an update pull must
@@ -21,11 +28,20 @@ STATE_DIR="$(gstack_state_root; printf x)"; STATE_DIR="${STATE_DIR%x}"
 THROTTLE_FILE="$STATE_DIR/.last-session-update"
 LOCK_DIR="$STATE_DIR/.setup-lock"
 LOG_FILE="$STATE_DIR/analytics/session-update.log"
+PENDING_FILE="$STATE_DIR/session-update-pending"
 THROTTLE_SECONDS=3600  # 1 hour
 
 log_entry() {
   mkdir -p "$(dirname "$LOG_FILE")"
-  echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) $1" >> "$LOG_FILE" 2>/dev/null || true
+  echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) $1" >> "$LOG_FILE" 2>/dev/null || true  # best-effort: logging never blocks a session
+}
+pending_get() { sed -n "s/^$1=//p" "$PENDING_FILE" 2>/dev/null | head -1; }
+# pending_save — persist the P_* stage state; nothing pending removes the file.
+pending_save() {
+  if [ -z "$P_STAGES" ] && [ -z "$P_PULL" ]; then rm -f "$PENDING_FILE"; return 0; fi
+  printf 'stages=%s\nfrom=%s\nfailures=%s\nnext=%s\nreason=%s\npull=%s\n' \
+    "$P_STAGES" "$P_FROM" "$P_FAILURES" "$P_NEXT" "$P_REASON" "$P_PULL" > "$PENDING_FILE.tmp.$$" \
+    && mv -f "$PENDING_FILE.tmp.$$" "$PENDING_FILE"
 }
 
 # ── Guard: gstack must be a git repo ──
@@ -39,6 +55,18 @@ if [ "$AUTO" != "true" ]; then
   exit 0
 fi
 
+# ── A stage that did not finish: one line per session start, with the fix ──
+if [ -f "$PENDING_FILE" ]; then
+  _P_STAGES="$(pending_get stages)"; _P_REASON="$(pending_get reason)"; _P_PULL="$(pending_get pull)"
+  if [ -n "$_P_STAGES" ]; then
+    _P_FIX="cd $GSTACK_DIR && ./setup"
+    case "$_P_REASON" in bun*) _P_FIX="install Bun (https://bun.sh), then $_P_FIX" ;; esac
+    echo "gstack auto-update: ${_P_STAGES} did not finish (${_P_REASON:-unknown reason}); installed skills may be out of date. gstack retries automatically. Fix now: $_P_FIX"
+  elif [ -n "$_P_PULL" ]; then
+    echo "gstack auto-update: git pull did not finish ($_P_PULL); gstack is not updating. Fix now: cd $GSTACK_DIR && git pull --ff-only && ./setup"
+  fi
+fi
+
 # ── Throttle: skip if checked recently ──
 if [ -f "$THROTTLE_FILE" ]; then
   LAST=$(cat "$THROTTLE_FILE" 2>/dev/null || echo 0)
@@ -152,9 +180,16 @@ fi
   # Record check time regardless of outcome
   date +%s > "$THROTTLE_FILE" 2>/dev/null
 
+  P_STAGES="$(pending_get stages)"; P_FROM="$(pending_get from)"; P_REASON="$(pending_get reason)"
+  P_FAILURES="$(pending_get failures)"; P_NEXT="$(pending_get next)"; P_PULL=""
+  case "$P_FAILURES" in ''|*[!0-9]*) P_FAILURES=0 ;; esac
+  case "$P_NEXT" in ''|*[!0-9]*) P_NEXT=0 ;; esac
+
   if [ "$PULL_EXIT" -ne 0 ]; then
     PULL_REASON=$(head -c 300 "$PULL_ERR_FILE" 2>/dev/null | tr '\n' ' ' | tr -s ' ')
     log_entry "PULL_FAILED exit=$PULL_EXIT reason=${PULL_REASON:-unknown}"
+    P_PULL="exit $PULL_EXIT: $(printf '%s' "${PULL_REASON:-no error output}" | head -c 160)"
+    pending_save
     # Autostash pop conflict leaves the stash behind and the tree half-merged.
     # The local patches are REGENERABLE (prefix renames, gbrain blocks), so
     # recover to a clean upstream tree and re-render them below rather than
@@ -164,8 +199,8 @@ fi
       git -C "$GSTACK_DIR" stash drop -q 2>/dev/null
       log_entry "AUTOSTASH_CONFLICT_RECOVERED tree_reset=1"
       _PREFIX_CFG=$("$GSTACK_DIR/bin/gstack-config" get skill_prefix 2>/dev/null || echo false)
-      "$GSTACK_DIR/bin/gstack-patch-names" "$GSTACK_DIR" "$_PREFIX_CFG" >/dev/null 2>&1 || true
-      "$GSTACK_DIR/bin/gstack-config" gbrain-refresh >/dev/null 2>&1 || true
+      "$GSTACK_DIR/bin/gstack-patch-names" "$GSTACK_DIR" "$_PREFIX_CFG" >/dev/null 2>&1 || true  # best-effort: regenerable prefix rewrite
+      "$GSTACK_DIR/bin/gstack-config" gbrain-refresh >/dev/null 2>&1 || true  # best-effort: regenerable gbrain blocks
     fi
     rm -f "$PULL_ERR_FILE" 2>/dev/null
     exit 0
@@ -175,33 +210,69 @@ fi
   # no-ops when the feature is unconfigured); the autostash pop usually
   # preserves them, but a clean re-render costs nothing and self-heals.
   _PREFIX_CFG=$("$GSTACK_DIR/bin/gstack-config" get skill_prefix 2>/dev/null || echo false)
-  "$GSTACK_DIR/bin/gstack-patch-names" "$GSTACK_DIR" "$_PREFIX_CFG" >/dev/null 2>&1 || true
-  "$GSTACK_DIR/bin/gstack-config" gbrain-refresh >/dev/null 2>&1 || true
+  "$GSTACK_DIR/bin/gstack-patch-names" "$GSTACK_DIR" "$_PREFIX_CFG" >/dev/null 2>&1 || true  # best-effort: regenerable prefix rewrite
+  "$GSTACK_DIR/bin/gstack-config" gbrain-refresh >/dev/null 2>&1 || true  # best-effort: regenerable gbrain blocks
 
-  # ── If HEAD moved, run setup -q ──
+  # ── Run setup when HEAD moved, or retry a pending stage after its backoff ──
+  NOW=$(date +%s)
+  RUN_SETUP=0
   if [ "$OLD_HEAD" != "$NEW_HEAD" ]; then
     log_entry "UPDATING old=$OLD_HEAD new=$NEW_HEAD"
+    RUN_SETUP=1
+    P_FAILURES=0
+    [ -n "$P_FROM" ] || P_FROM=$(git -C "$GSTACK_DIR" show "$OLD_HEAD:VERSION" 2>/dev/null || echo "unknown")
+  elif [ -n "$P_STAGES" ]; then
+    if [ "$NOW" -ge "$P_NEXT" ]; then
+      log_entry "RETRY_PENDING stages=$P_STAGES attempt=$((P_FAILURES + 1))"
+      RUN_SETUP=1
+    else
+      log_entry "PENDING_BACKOFF stages=$P_STAGES next=$P_NEXT"
+    fi
+  fi
 
-    # bun must be available for setup
+  if [ "$RUN_SETUP" -eq 1 ]; then
+    FAILED_STAGE="" FAIL_REASON=""
     if command -v bun >/dev/null 2>&1; then
-      ( cd "$GSTACK_DIR" && ./setup -q --refresh-registered ) >/dev/null 2>&1 || {
-        log_entry "SETUP_FAILED"
-      }
+      SETUP_OUT=$(mktemp "${TMPDIR:-/tmp}/gstack-session-setup-XXXXXX" 2>/dev/null || echo /dev/null)
+      ( cd "$GSTACK_DIR" && ./setup -q --refresh-registered ) >"$SETUP_OUT" 2>&1
+      SETUP_EXIT=$?
       # Heartbeat: setup done (either way) — refresh the TTL clock.
       touch "$LOCK_DIR/pid" 2>/dev/null
+      if [ "$SETUP_EXIT" -ne 0 ]; then
+        _MIG="$(grep -o 'migration [^ ]* failed' "$SETUP_OUT" 2>/dev/null | head -1)"
+        if [ -n "$_MIG" ]; then
+          FAILED_STAGE="migrations" FAIL_REASON="$_MIG"
+        else
+          _LAST="$(grep -v '^[[:space:]]*$' "$SETUP_OUT" 2>/dev/null | tail -1 | head -c 160)"
+          FAILED_STAGE="setup" FAIL_REASON="./setup exited $SETUP_EXIT${_LAST:+: $_LAST}"
+        fi
+      fi
+      [ "$SETUP_OUT" = /dev/null ] || rm -f "$SETUP_OUT"
     else
+      FAILED_STAGE="setup" FAIL_REASON="bun not found on PATH"
       log_entry "SETUP_SKIPPED bun_missing"
     fi
 
-    # Write marker so next skill preamble shows "just upgraded"
-    OLD_VER=$(git -C "$GSTACK_DIR" show "$OLD_HEAD:VERSION" 2>/dev/null || echo "unknown")
-    echo "$OLD_VER" > "$STATE_DIR/just-upgraded-from" 2>/dev/null
-    rm -f "$STATE_DIR/last-update-check" 2>/dev/null
-    rm -f "$STATE_DIR/update-snoozed" 2>/dev/null
-
-    log_entry "UPDATED from=$OLD_VER to=$(cat "$GSTACK_DIR/VERSION" 2>/dev/null || echo unknown)"
+    if [ -z "$FAILED_STAGE" ]; then
+      # Every stage succeeded: now the next skill preamble may say "just upgraded".
+      echo "${P_FROM:-unknown}" > "$STATE_DIR/just-upgraded-from" 2>/dev/null
+      rm -f "$STATE_DIR/last-update-check" 2>/dev/null
+      rm -f "$STATE_DIR/update-snoozed" 2>/dev/null
+      log_entry "UPDATED from=${P_FROM:-unknown} to=$(cat "$GSTACK_DIR/VERSION" 2>/dev/null || echo unknown)"
+      P_STAGES="" P_FROM="" P_FAILURES=0 P_NEXT=0 P_REASON=""
+      pending_save
+    else
+      P_FAILURES=$((P_FAILURES + 1))
+      case "$P_FAILURES" in 1) _WAIT=$THROTTLE_SECONDS ;; 2) _WAIT=21600 ;; *) _WAIT=86400 ;; esac
+      P_STAGES="$FAILED_STAGE" P_NEXT=$((NOW + _WAIT)) P_REASON="$FAIL_REASON"
+      pending_save
+      [ "$FAILED_STAGE" = setup ] && [ "$FAIL_REASON" != "bun not found on PATH" ] && log_entry "SETUP_FAILED reason=$FAIL_REASON"
+      [ "$FAILED_STAGE" = migrations ] && log_entry "MIGRATIONS_FAILED reason=$FAIL_REASON"
+      log_entry "PENDING stages=$FAILED_STAGE attempt=$P_FAILURES next_retry_in=${_WAIT}s"
+    fi
   else
-    log_entry "UP_TO_DATE head=$OLD_HEAD"
+    pending_save
+    [ -n "$P_STAGES" ] || log_entry "UP_TO_DATE head=$OLD_HEAD"
   fi
 # The detached subshell must own its stdio: it inherits the session hook's
 # pipes, and once the hook exits and the caller closes them, any child that

bin/gstack-settings-hook

@@ -14,7 +14,8 @@
 #        gstack-settings-hook add-event --event <name — see the validator in add-event> \
 #          --command <cmd> --source <tag> [--matcher <regex>] [--timeout <s>]
 #        gstack-settings-hook ensure-event --event ... --command ... --source ... [--matcher ...] [--timeout <s>]
-#        gstack-settings-hook remove-source --source <tag>   # removes items the table identifies as <tag>'s, tagged or not
+#        gstack-settings-hook remove-source --source <tag> [--event <name>]
+#                                          # removes items the table identifies as <tag>'s, tagged or not
 #        gstack-settings-hook diff-event   --event ... --command ... --source ... [--matcher ...]
 #        gstack-settings-hook rollback     # restore latest backup (single-step undo)
 #        gstack-settings-hook list-sources # show all gstack-tagged hook entries
@@ -79,7 +80,7 @@ Usage:
   gstack-settings-hook remove <hook-command>          # legacy SessionStart remove
   gstack-settings-hook add-event --event <name> --command <cmd> --source <tag> [--matcher <re>] [--timeout <s>]
   gstack-settings-hook ensure-event --event <name> --command <cmd> --source <tag> [--matcher <re>] [--timeout <s>]
-  gstack-settings-hook remove-source --source <tag>   # tagged OR table-identified items of <tag>
+  gstack-settings-hook remove-source --source <tag> [--event <name>]   # tagged OR table-identified items of <tag>
   gstack-settings-hook diff-event --event <name> --command <cmd> --source <tag> [--matcher <re>] [--timeout <s>]
   gstack-settings-hook prune-stale [--repoint <root>] [--all]
   gstack-settings-hook rollback
@@ -336,7 +337,7 @@ _release_lock() {
 _acquire_lock() {
   # GSTACK_SETTINGS_LOCK_TIMEOUT_MS: test-only override for the give-up
   # (a contention test should not stall the suite for 10 real seconds).
-  local waited_ms=0 token stale mtime now
+  local waited_ms=0 token stale mtime now vanished=0
   local give_up_ms="${GSTACK_SETTINGS_LOCK_TIMEOUT_MS:-10000}"
   local stale_after_s=30   # lock older than this belongs to a crashed holder
   local poll_ms=50         # retry cadence; sleep below derives from this
@@ -350,15 +351,17 @@ _acquire_lock() {
       trap 'exit 143' TERM
       return 0
     fi
-    # mkdir failed but no lock dir exists: NOT contention (unwritable parent,
-    # read-only fs, missing directory) -- waiting cannot help, so give up
-    # loudly now instead of spinning out the full timeout. (Tiny race: a
-    # contender could acquire+release between our mkdir and this check; that
-    # transient reads as an environment failure and the next run converges.)
+    # mkdir failed but no lock dir exists: either a holder released between
+    # our mkdir and this check, or NOT contention (unwritable parent, read-only
+    # fs, missing directory). Retry mkdir once; a second failure with still no
+    # lock dir is the environment, and waiting cannot help, so give up loudly
+    # now instead of spinning out the full timeout.
     if [ ! -e "$_LOCK_DIR" ]; then
+      if [ "$vanished" -eq 0 ]; then vanished=1; continue; fi
       echo "gstack-settings-hook: cannot create lock $_LOCK_DIR (unwritable parent?) -- skipping this mutation, exit 5" >&2
       return 1
     fi
+    vanished=0
     # Stale takeover: atomic rename means exactly one contender wins; the
     # loser loops and re-contends against the winner's fresh mkdir.
     # GNU stat (-c %Y) first: on Linux, BSD-style `stat -f %m` prints a
@@ -641,10 +644,12 @@ case "$ACTION" in
 
   remove-source)
     SOURCE=""
+    RS_EVENT=""
     shift
     while [ $# -gt 0 ]; do
       case "$1" in
         --source) SOURCE="$2"; shift 2 ;;
+        --event)  RS_EVENT="$2"; shift 2 ;;
         *) echo "unknown flag: $1" >&2; exit 1 ;;
       esac
     done
@@ -655,9 +660,10 @@ case "$ACTION" in
     [ -f "$SETTINGS_FILE" ] || exit 0
     _acquire_lock || exit 5
     _mutation_env
-    GSTACK_SETTINGS_PATH="$SETTINGS_FILE" GSTACK_SOURCE="$SOURCE" bun -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
+    GSTACK_SETTINGS_PATH="$SETTINGS_FILE" GSTACK_SOURCE="$SOURCE" GSTACK_RS_EVENT="$RS_EVENT" bun -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
       const settingsPath = process.env.GSTACK_SETTINGS_PATH;
       const source = process.env.GSTACK_SOURCE;
+      const onlyEvent = process.env.GSTACK_RS_EVENT || "";
       const loaded = gsLoadSettings(settingsPath);
       const settings = loaded.settings;
       if (!settings.hooks) { console.log("OK: removed 0 hook entry/entries tagged source=" + source); process.exit(0); }
@@ -677,6 +683,7 @@ case "$ACTION" in
       // the tag with its last owned item. Callers that need every gstack
       // item gone still pair this with prune-stale --all.
       for (const event of Object.keys(settings.hooks)) {
+        if (onlyEvent && event !== onlyEvent) continue;   // --event scopes the removal (Q3)
         const entries = settings.hooks[event];
         if (!Array.isArray(entries)) continue;   // foreign shape: not ours to judge
         const kept = [];

bin/gstack-skill-start

@@ -190,12 +190,19 @@ for _PF in $(find "$_GH/analytics" -maxdepth 1 -name '.pending-*' 2>/dev/null);
   break
 done
 eval "$("$_BIN/gstack-slug" 2>/dev/null)" 2>/dev/null || true
+for _former in $("$_BIN/gstack-slug" --get FORMER_SLUGS 2>/dev/null || true); do
+  echo "gstack: earlier data for this project is in projects/$_former (a worktree's old bucket). Merge it: gstack-slug --adopt-legacy --from $_former   (or stop this reminder: gstack-slug --adopt-legacy --dismiss $_former)"
+done
 _LEARN_FILE="$_GH/projects/${SLUG:-unknown}/learnings.jsonl"
 if [ -f "$_LEARN_FILE" ]; then
   _LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ')
   echo "LEARNINGS: $_LEARN_COUNT entries loaded"
   if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then
-    "$_BIN/gstack-learnings-search" --limit 3 2>/dev/null | _sanitize || true
+    _LEARN_ERR=$(mktemp "${TMPDIR:-/tmp}/gstack-learn-err.XXXXXX" 2>/dev/null) || _LEARN_ERR=/dev/null
+    if ! "$_BIN/gstack-learnings-search" --limit 3 2>"$_LEARN_ERR" | _sanitize; then
+      echo "LEARNINGS: unavailable ($(head -n 1 "$_LEARN_ERR" 2>/dev/null))"
+    fi
+    [ "$_LEARN_ERR" = /dev/null ] || rm -f "$_LEARN_ERR"
   fi
 else
   echo "LEARNINGS: 0"

bin/gstack-slug

@@ -11,6 +11,8 @@
 #   --stamp-checkpoint <file>  write remote:/project_root: into a checkpoint's frontmatter
 #   --classify-checkpoints     read checkpoint paths on stdin, print "<status>\t<path>"
 #   --adopt-legacy [--copy <relpath>...]  review/copy files from the pre-#3003 bucket
+#   --adopt-legacy --from <slug>  merge a former bucket (e.g. a worktree's) into this one
+#   --adopt-legacy --dismiss <slug>  stop naming a former bucket at skill start
 #
 # Nested-group remotes (#3003): a hosted remote with 3+ path segments
 # (gitlab.com/a/product/repo) files under "<last-two>-<16 hex>" instead of the
@@ -22,6 +24,17 @@
 # (git@work-gitlab:…) are a different canonical host than the https spelling;
 # pin those with GSTACK_PROJECT_SLUG.
 #
+# Cache key (#2767): inside a git repository the entry is keyed on the git
+# common dir, which the main checkout, its subdirectories and every linked
+# worktree share, so a worktree can no longer resolve a different slug than
+# the main checkout. It is read from .git files without spawning git. Entries
+# written before this keyed on pwd; on a miss the main checkout's old entry
+# wins over the current directory's own old entry (deterministic: the main
+# checkout holds the project's original, possibly pre-remote, identity). When
+# a worktree's own old entry named a different, non-empty bucket, that slug is
+# recorded in projects/<slug>/.former-slugs until --adopt-legacy --from merges
+# it or --dismiss drops it. Both keys are written, so pwd-keyed readers agree.
+#
 # Cache format: entries are versioned ("v2:<slug>"). An unversioned entry from
 # an older gstack is recomputed once (one git spawn) and rewritten as v2; it
 # keeps its value unless it is exactly the pre-#3003 last-two slug of a
@@ -91,8 +104,8 @@ case "${1:-}" in
   "") ;;
   --identity) MODE=identity ;;
   --get) MODE=get; MODE_ARG="${2:-}"
-    case "$MODE_ARG" in SLUG|BRANCH|PROJECT_REMOTE|PROJECT_ROOT|LEGACY_SLUG) ;;
-      *) echo "usage: gstack-slug --get SLUG|BRANCH|PROJECT_REMOTE|PROJECT_ROOT|LEGACY_SLUG" >&2; exit 2 ;;
+    case "$MODE_ARG" in SLUG|BRANCH|PROJECT_REMOTE|PROJECT_ROOT|LEGACY_SLUG|FORMER_SLUGS) ;;
+      *) echo "usage: gstack-slug --get SLUG|BRANCH|PROJECT_REMOTE|PROJECT_ROOT|LEGACY_SLUG|FORMER_SLUGS" >&2; exit 2 ;;
     esac ;;
   --stamp-checkpoint) MODE=stamp; MODE_ARG="${2:-}"
     [[ -n "$MODE_ARG" ]] || { echo "usage: gstack-slug --stamp-checkpoint <file>" >&2; exit 2; } ;;
@@ -102,8 +115,12 @@ case "${1:-}" in
       shift
       [[ $# -gt 0 ]] || { echo "usage: gstack-slug --adopt-legacy --copy <relpath>..." >&2; exit 2; }
       COPY_PATHS=("$@")
+    elif [[ "${1:-}" == "--from" || "${1:-}" == "--dismiss" ]]; then
+      MODE=$([[ "$1" == "--from" ]] && echo adopt-from || echo adopt-dismiss)
+      MODE_ARG=$(printf '%s' "${2:-}" | tr -cd 'a-zA-Z0-9._-')
+      case "$MODE_ARG" in ""|.|..) echo "usage: gstack-slug --adopt-legacy $1 <slug>" >&2; exit 2 ;; esac
     elif [[ -n "${1:-}" ]]; then
-      echo "usage: gstack-slug --adopt-legacy [--copy <relpath>...]" >&2; exit 2
+      echo "usage: gstack-slug --adopt-legacy [--copy <relpath>... | --from <slug> | --dismiss <slug>]" >&2; exit 2
     fi ;;
   -h|--help)
     cat <<'USAGE'
@@ -119,6 +136,10 @@ gstack-slug — print SLUG=<project slug> and BRANCH=<branch> for the current di
   gstack-slug --adopt-legacy            list the old bucket's files (checkpoints marked
                                         matching/foreign/unknown); asks per file on a terminal
   gstack-slug --adopt-legacy --copy P…  copy the named files (paths relative to the old bucket)
+  gstack-slug --adopt-legacy --from S   merge bucket S into this project's: JSONL logs merge with
+                                        de-duplication, missing files copy, differing files are
+                                        listed as conflicts and never overwritten; S is kept
+  gstack-slug --adopt-legacy --dismiss S  stop naming former bucket S at skill start
 Env: GSTACK_PROJECT_SLUG pins the slug (ssh host aliases, vendored sub-repos); never cached.
 USAGE
     exit 0 ;;
@@ -130,6 +151,41 @@ PROJECT_DIR="$(pwd)"
 CACHE_KEY=$(printf '%s' "$PROJECT_DIR" | tr '/' '_')
 CACHE_FILE="${CACHE_DIR}/${CACHE_KEY}"
 
+# Physical git common dir of the repository holding $1 (nearest .git entry),
+# or nothing outside git. A worktree's .git file names its gitdir, whose
+# `commondir` file points at the shared dir. No git spawn.
+_git_common_dir() {
+  local dir="$1" parent="" gitdir="" common="" depth=0
+  while [[ -n "$dir" && $depth -lt 64 ]]; do
+    if [[ -d "$dir/.git" ]]; then (cd "$dir/.git" 2>/dev/null && pwd -P); return 0; fi
+    if [[ -f "$dir/.git" ]]; then
+      gitdir=$(sed -n 's/^gitdir: *//p' "$dir/.git" 2>/dev/null | head -1)
+      [[ -n "$gitdir" ]] || return 0
+      [[ "$gitdir" == /* || "$gitdir" =~ ^[A-Za-z]: ]] || gitdir="$dir/$gitdir"
+      common="$gitdir"
+      if [[ -f "$gitdir/commondir" ]]; then
+        common=$(head -1 "$gitdir/commondir" 2>/dev/null)
+        [[ "$common" == /* || "$common" =~ ^[A-Za-z]: ]] || common="$gitdir/$common"
+      fi
+      (cd "$common" 2>/dev/null && pwd -P); return 0
+    fi
+    parent=$(dirname "$dir")
+    [[ "$parent" == "$dir" ]] && break
+    dir="$parent"
+    depth=$((depth + 1))
+  done
+  return 0
+}
+LEGACY_CACHE_FILE="$CACHE_FILE"
+MAIN_CACHE_FILE=""
+GIT_COMMON_DIR=$(_git_common_dir "$PROJECT_DIR")
+if [[ -n "$GIT_COMMON_DIR" ]]; then
+  CACHE_FILE="${CACHE_DIR}/$(printf '%s' "$GIT_COMMON_DIR" | tr '/' '_')"
+  if [[ "$(basename "$GIT_COMMON_DIR")" == .git ]]; then
+    MAIN_CACHE_FILE="${CACHE_DIR}/$(dirname "$GIT_COMMON_DIR" | tr '/' '_')"
+  fi
+fi
+
 SLUG=""
 
 # 0. Explicit env override — wins over everything. Escape hatch for vendored
@@ -276,8 +332,12 @@ _resolve_remote() {
 #       so the heal never fires.
 _CACHE_V2=0
 LEGACY_NOTICE_SLUG=""
-if [[ -z "$SLUG" && -f "$CACHE_FILE" ]]; then
-  _RAW_CACHE=$(cat "$CACHE_FILE" 2>/dev/null || true)
+_ENTRY_FILE=""
+for _f in "$CACHE_FILE" "$MAIN_CACHE_FILE" "$LEGACY_CACHE_FILE"; do
+  if [[ -n "$_f" && -f "$_f" ]]; then _ENTRY_FILE="$_f"; break; fi
+done
+if [[ -z "$SLUG" && -n "$_ENTRY_FILE" ]]; then
+  _RAW_CACHE=$(cat "$_ENTRY_FILE" 2>/dev/null || true)
   if [[ "$_RAW_CACHE" == v2:* ]]; then
     _CACHE_V2=1
     _RAW_CACHE="${_RAW_CACHE#v2:}"
@@ -356,18 +416,33 @@ SLUG="${SLUG:-$(basename "$PROJECT_DIR" | tr -cd 'a-zA-Z0-9._-')}"
 #     injection, but the invariant should not depend on that reasoning).
 SLUG=$(printf '%s' "$SLUG" | tr -cd 'a-zA-Z0-9._-')
 
+# A worktree whose own pre-#2767 entry named a different bucket that still
+# holds data: remember it so skill start can name the merge command.
+if [[ -n "$SLUG" && "$SLUG_FROM_ENV" -eq 0 && "$_ENTRY_FILE" != "$LEGACY_CACHE_FILE" && -f "$LEGACY_CACHE_FILE" ]]; then
+  _OWN=$(cat "$LEGACY_CACHE_FILE" 2>/dev/null || true)
+  _OWN=$(printf '%s' "${_OWN#v2:}" | tr -cd 'a-zA-Z0-9._-')
+  _FORMER_FILE="$GSTACK_STATE_ROOT/projects/$SLUG/.former-slugs"
+  if [[ -n "$_OWN" && "$_OWN" != "$SLUG" && "$_OWN" != . && "$_OWN" != .. && -n "$(ls -A "$GSTACK_STATE_ROOT/projects/$_OWN" 2>/dev/null)" ]] \
+    && ! grep -qxF -- "$_OWN" "$_FORMER_FILE" 2>/dev/null; then
+    mkdir -p "$(dirname "$_FORMER_FILE")" 2>/dev/null && printf '%s\n' "$_OWN" >> "$_FORMER_FILE" 2>/dev/null || true
+  fi
+fi
+
 if [[ -n "$SLUG" && "$SLUG_FROM_ENV" -eq 0 ]]; then
-  CURRENT_CACHE=""
-  if [[ -f "$CACHE_FILE" ]]; then
-    CURRENT_CACHE=$(cat "$CACHE_FILE" 2>/dev/null || true)
-  fi
-  if [[ "$CURRENT_CACHE" != "v2:$SLUG" ]]; then
-    mkdir -p "$CACHE_DIR" 2>/dev/null || true
-    CACHE_TMP=$(mktemp "$CACHE_DIR/.slug-XXXXXX" 2>/dev/null) || CACHE_TMP=""
-    if [[ -n "$CACHE_TMP" ]]; then
-      printf 'v2:%s' "$SLUG" > "$CACHE_TMP" && mv "$CACHE_TMP" "$CACHE_FILE" 2>/dev/null || rm -f "$CACHE_TMP" 2>/dev/null
+  for _f in "$CACHE_FILE" "$LEGACY_CACHE_FILE"; do
+    CURRENT_CACHE=""
+    if [[ -f "$_f" ]]; then
+      CURRENT_CACHE=$(cat "$_f" 2>/dev/null || true)
     fi
-  fi
+    if [[ "$CURRENT_CACHE" != "v2:$SLUG" ]]; then
+      mkdir -p "$CACHE_DIR" 2>/dev/null || true
+      CACHE_TMP=$(mktemp "$CACHE_DIR/.slug-XXXXXX" 2>/dev/null) || CACHE_TMP=""
+      if [[ -n "$CACHE_TMP" ]]; then
+        printf 'v2:%s' "$SLUG" > "$CACHE_TMP" && mv "$CACHE_TMP" "$_f" 2>/dev/null || rm -f "$CACHE_TMP" 2>/dev/null
+      fi
+    fi
+    [[ "$CACHE_FILE" == "$LEGACY_CACHE_FILE" ]] && break
+  done
 fi
 
 # One notice on the resolve that first files this project under its new
@@ -385,6 +460,65 @@ if [[ "$MODE" == "get" && ( "$MODE_ARG" == SLUG || "$MODE_ARG" == BRANCH ) ]]; t
   if [[ "$MODE_ARG" == SLUG ]]; then printf '%s\n' "$SLUG"; else printf '%s\n' "$BRANCH"; fi
   exit 0
 fi
+FORMER_FILE="$GSTACK_STATE_ROOT/projects/$SLUG/.former-slugs"
+if [[ "$MODE" == "get" && "$MODE_ARG" == FORMER_SLUGS ]]; then
+  # Former buckets still holding data and not yet adopted or dismissed.
+  while IFS= read -r _former || [[ -n "$_former" ]]; do
+    _former=$(printf '%s' "$_former" | tr -cd 'a-zA-Z0-9._-')
+    case "$_former" in ""|.|..) continue ;; esac
+    [[ -n "$(ls -A "$GSTACK_STATE_ROOT/projects/$_former" 2>/dev/null)" ]] && printf '%s\n' "$_former"
+  done < <(cat "$FORMER_FILE" 2>/dev/null || true)
+  exit 0
+fi
+_forget_former() {
+  [[ -f "$FORMER_FILE" ]] || return 0
+  local tmp
+  tmp=$(mktemp "$FORMER_FILE.XXXXXX") || return 1
+  grep -vxF -- "$1" "$FORMER_FILE" > "$tmp" || true
+  mv "$tmp" "$FORMER_FILE"
+}
+if [[ "$MODE" == "adopt-dismiss" ]]; then
+  _forget_former "$MODE_ARG" && echo "Dismissed projects/$MODE_ARG; its files are kept and skill start no longer names it."
+  exit $?
+fi
+if [[ "$MODE" == "adopt-from" ]]; then
+  FROM_BUCKET="$GSTACK_STATE_ROOT/projects/$MODE_ARG"
+  TO_BUCKET="$GSTACK_STATE_ROOT/projects/$SLUG"
+  [[ "$MODE_ARG" != "$SLUG" ]] || { echo "gstack-slug: projects/$MODE_ARG is this project's own bucket." >&2; exit 2; }
+  [[ -d "$FROM_BUCKET" && ! -L "$FROM_BUCKET" ]] || { echo "gstack-slug: no bucket at $FROM_BUCKET." >&2; exit 1; }
+  mkdir -p "$TO_BUCKET" || exit 1
+  MIGRATED=0; PENDING=0; CONFLICTING=0; UNCHANGED=0; CONFLICTS=""; PENDINGS=""
+  while IFS= read -r -d '' rel; do
+    rel="${rel#./}"
+    src="$FROM_BUCKET/$rel"; dst="$TO_BUCKET/$rel"
+    if [[ -L "$src" || ! -f "$src" ]]; then
+      PENDING=$((PENDING + 1)); PENDINGS="$PENDINGS  $rel (not a regular file; review by hand)"$'\n'; continue
+    fi
+    if [[ ! -e "$dst" ]]; then
+      mkdir -p "$(dirname "$dst")" && cp -p "$src" "$dst" && MIGRATED=$((MIGRATED + 1)) && continue
+      PENDING=$((PENDING + 1)); PENDINGS="$PENDINGS  $rel (copy failed)"$'\n'; continue
+    fi
+    if cmp -s "$src" "$dst"; then UNCHANGED=$((UNCHANGED + 1)); continue; fi
+    if [[ "$rel" == *.jsonl && -f "$dst" && ! -L "$dst" ]]; then
+      # Append-only logs: add the lines this bucket lacks, keeping its order.
+      tmp=$(mktemp "$dst.XXXXXX") || { PENDING=$((PENDING + 1)); continue; }
+      if { cat "$dst"; awk 'FNR == NR { seen[$0] = 1; next } !($0 in seen) { seen[$0] = 1; print }' "$dst" "$src"; } > "$tmp"; then
+        if cmp -s "$tmp" "$dst"; then rm -f "$tmp"; UNCHANGED=$((UNCHANGED + 1)); else mv "$tmp" "$dst"; MIGRATED=$((MIGRATED + 1)); fi
+      else
+        rm -f "$tmp"; PENDING=$((PENDING + 1)); PENDINGS="$PENDINGS  $rel (merge failed)"$'\n'
+      fi
+      continue
+    fi
+    CONFLICTING=$((CONFLICTING + 1)); CONFLICTS="$CONFLICTS  $rel"$'\n'
+  done < <(cd "$FROM_BUCKET" && find . \( -type f -o -type l \) ! -name .former-slugs -print0 2>/dev/null)
+  echo "adopt-legacy --from $MODE_ARG into projects/$SLUG: migrated $MIGRATED, pending $PENDING, conflicting $CONFLICTING, unchanged $UNCHANGED"
+  [[ -z "$PENDINGS" ]] || printf 'Pending (left in projects/%s):\n%s' "$MODE_ARG" "$PENDINGS"
+  [[ -z "$CONFLICTS" ]] || printf 'Conflicting (both differ; nothing overwritten, compare by hand):\n%s' "$CONFLICTS"
+  echo "projects/$MODE_ARG is kept; delete it yourself once you are satisfied."
+  _forget_former "$MODE_ARG" || true
+  [[ "$PENDING" -eq 0 ]]
+  exit $?
+fi
 if [[ "$MODE" == "default" ]]; then
   echo "SLUG=$SLUG"
   echo "BRANCH=$BRANCH"

bin/gstack-taste-update

@@ -197,9 +197,14 @@ function bumpPref(list: Preference[], value: string, opposite: Preference[], act
     entry.rejected_count += 1;
   }
   entry.last_seen = now;
-  // Laplace-smoothed confidence
+  // Laplace-smoothed confidence in THIS bucket's signal: an approved entry's
+  // confidence reflects how strongly it's approved, a rejected entry's how
+  // strongly it's rejected. Using approved_count for both buckets pinned every
+  // rejected entry to 0 (rejected entries never gain approvals), which made the
+  // `show` ranking meaningless and the taste-drift warning unreachable.
   const total = entry.approved_count + entry.rejected_count;
-  entry.confidence = entry.approved_count / (total + 1);
+  const ownCount = action === 'approved' ? entry.approved_count : entry.rejected_count;
+  entry.confidence = ownCount / (total + 1);
   // Flag conflict if the opposite bucket has a strong entry for this value
   const opp = opposite.find(p => p.value.toLowerCase() === value.toLowerCase());
   if (opp && opp.approved_count + opp.rejected_count >= 3 && opp.confidence >= 0.6) {

bin/gstack-team-init

@@ -151,6 +151,8 @@ Install it:
 
 Then restart your AI coding tool.
 MSG
+  # Exit 2 denies on Claude Code (#2413) and on Copilot CLI, which treats a
+  # preToolUse exit 2 as deny (#2229).
   echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"gstack is required but not installed. See stderr for install instructions."}}'
   exit 2
 fi
@@ -173,15 +175,19 @@ HOOK_EOF
       if (!settings.hooks) settings.hooks = {};
       if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
 
-      // Dedup
-      const exists = settings.hooks.PreToolUse.some(entry =>
-        entry.matcher === 'Skill' &&
+      // Claude Code's skill tool is Skill; Copilot CLI's is skill, which no
+      // Claude tool name maps to, so a bare 'Skill' never fired there (#2229).
+      // An entry an older team-init wrote is upgraded in place, never duplicated.
+      const MATCHER = 'Skill|skill';
+      const ours = settings.hooks.PreToolUse.filter(entry =>
+        (entry.matcher === 'Skill' || entry.matcher === MATCHER) &&
         entry.hooks && entry.hooks.some(h => h.command && h.command.includes('check-gstack'))
       );
+      for (const entry of ours) entry.matcher = MATCHER;
 
-      if (!exists) {
+      if (ours.length === 0) {
         settings.hooks.PreToolUse.push({
-          matcher: 'Skill',
+          matcher: MATCHER,
           hooks: [{
             type: 'command',
             command: '\"\$CLAUDE_PROJECT_DIR/.claude/hooks/check-gstack.sh\"'

bin/gstack-timeline-read

@@ -4,7 +4,8 @@
 #
 # Session timeline: local-only, never sent anywhere.
 # Reads ~/.gstack/projects/$SLUG/timeline.jsonl, filters, formats.
-# Exit 0 silently if no timeline file exists.
+# Exit 0 silently if no timeline file exists or nothing matches. Missing bun
+# exits 127 and a failed read exits non-zero with its stderr (#2790).
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
@@ -31,7 +32,12 @@ if [ ! -f "$TIMELINE_FILE" ]; then
   exit 0
 fi
 
-cat "$TIMELINE_FILE" 2>/dev/null | GSTACK_TIMELINE_SINCE="$SINCE" GSTACK_TIMELINE_BRANCH="$BRANCH" GSTACK_TIMELINE_LIMIT="$LIMIT" bun -e "
+command -v bun >/dev/null 2>&1 || {
+  echo "gstack-timeline-read: bun not found on PATH, so the timeline could not be read. Fix: install Bun (https://bun.sh), then re-run ./setup." >&2
+  exit 127
+}
+
+cat "$TIMELINE_FILE" | GSTACK_TIMELINE_SINCE="$SINCE" GSTACK_TIMELINE_BRANCH="$BRANCH" GSTACK_TIMELINE_LIMIT="$LIMIT" bun -e "
 const lines = (await Bun.stdin.text()).trim().split('\n').filter(Boolean);
 const since = process.env.GSTACK_TIMELINE_SINCE || '';
 const branch = process.env.GSTACK_TIMELINE_BRANCH || '';
@@ -95,4 +101,4 @@ for (const e of recent) {
   const outcome = e.outcome ? ' [' + e.outcome + ']' : '';
   console.log('- ' + ts + ' /' + e.skill + ' ' + e.event + outcome + dur + (e.branch ? ' on ' + e.branch : ''));
 }
-" 2>/dev/null || exit 0
+"

bin/gstack-version-bump

@@ -16,9 +16,14 @@
 //   classify --base <branch> [--version-path <p>]
 //       Compares VERSION vs origin/<base>:VERSION vs package.json.version.
 //       Emits JSON: { state, baseVersion, currentVersion, pkgVersion, pkgExists }
-//       state ∈ FRESH | ALREADY_BUMPED | DRIFT_STALE_PKG | DRIFT_UNEXPECTED
+//       state ∈ FRESH | ALREADY_BUMPED | DRIFT_STALE_PKG | DRIFT_UNEXPECTED | NO_VERSION
+//       NO_VERSION: no version source is configured (absent) or the repo's
+//       version is owned elsewhere (ambiguous) — /ship ships without a
+//       version change and prints `notice`. A configured source that is
+//       missing, empty, unreadable or malformed exits 2 with the reason.
 //       Exit 0 on a decidable state (incl. DRIFT_UNEXPECTED — it's a real state
-//       the caller must handle), exit 2 on bad args / unresolvable base.
+//       the caller must handle), exit 2 on bad args / unresolvable base /
+//       broken version source.
 //
 //   write --version <X.Y.Z.W> [--version-path <p>] [--regen-digest]
 //       Validates the 4-digit pattern, writes VERSION + package.json.version.
@@ -61,7 +66,16 @@
 import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { extractVersion, isJsonVersionPath, npmVersion, setVersionInJson } from "../lib/version-source";
+import {
+  extractVersion,
+  isJsonVersionPath,
+  noVersionNotice,
+  npmVersion,
+  resolveVersionRel as resolvePinnedRel,
+  resolveVersionSource,
+  setVersionInJson,
+  type VersionSource,
+} from "../lib/version-source";
 
 // 3- or 4-digit (#2501). gstack's own VERSION stays 4-digit MAJOR.MINOR.PATCH.
 // MICRO and stays the source of truth, but a repo whose pinned version source
@@ -129,20 +143,16 @@ function assertRepoContained(cwd: string, rel: string, source: string): void {
  * Resolving once, here, keeps base and current reads in step.
  */
 function resolveVersionRel(cwd: string, explicit?: string): string {
-  if (explicit) {
-    const rel = explicit.trim();
-    assertRepoContained(cwd, rel, "--version-path");
-    return rel;
-  }
-  const pin = join(cwd, ".gstack", "version-path");
-  if (existsSync(pin)) {
-    const p = readFileSync(pin, "utf-8").split("\n")[0]?.trim() ?? "";
-    if (p) {
-      assertRepoContained(cwd, p, ".gstack/version-path");
-      return p;
-    }
-  }
-  return "VERSION";
+  return resolvePinnedRel(cwd, explicit, (rel, source) => assertRepoContained(cwd, rel, source)).rel;
+}
+
+/** The four-outcome resolution (lib/version-source.ts), containment-guarded. */
+function versionSource(cwd: string, explicit?: string): VersionSource {
+  return resolveVersionSource(cwd, explicit, (rel, source) => assertRepoContained(cwd, rel, source));
+}
+
+function failBroken(src: VersionSource, verb: string): never {
+  fail(`${verb}: version source is broken: ${src.reason}. Fix that file or its pin, then re-run /ship (gstack never substitutes 0.0.0.0).`, 2);
 }
 
 
@@ -302,9 +312,31 @@ function classifyState(
 function cmdClassify(args: string[], cwd: string): void {
   const base = argVal(args, "--base");
   if (!base) fail("classify requires --base <branch>", 2);
-  const versionRel = resolveVersionRel(cwd, argVal(args, "--version-path"));
+  const src = versionSource(cwd, argVal(args, "--version-path"));
+  if (src.outcome === "broken") failBroken(src, "classify");
+  if (src.outcome !== "valid") {
+    // No configured version source (#2334, #2343): report it as its own state
+    // instead of classifying an invented 0.0.0.0. /ship skips the bump, the
+    // CHANGELOG version header and the PR title prefix, and prints `notice`.
+    process.stdout.write(
+      JSON.stringify({
+        state: "NO_VERSION",
+        versionSource: { outcome: src.outcome, path: src.path, reason: src.reason },
+        notice: noVersionNotice(src),
+        baseVersion: null,
+        currentVersion: null,
+        pkgVersion: null,
+        pkgExists: false,
+        pkgPath: null,
+        expectedPkgVersion: null,
+        versionFileExists: false,
+      }) + "\n",
+    );
+    return;
+  }
+  const versionRel = src.path!;
   const versionPath = join(cwd, versionRel);
-  const current = readVersionFile(versionPath, versionRel);
+  const current = src.version!;
   const baseV = baseVersion(cwd, base!, versionRel);
   // When the version-path IS a package.json (#2501), that file is the single
   // source of truth and the "VERSION vs package.json" drift states cannot
@@ -313,35 +345,29 @@ function cmdClassify(args: string[], cwd: string): void {
   // file and itself.
   const jsonSource = isJsonVersionPath(versionRel);
   const pkgPath = jsonSource ? versionPath : resolvePkgPath(cwd, argVal(args, "--package-json-path"));
-  const pkg = jsonSource
-    ? { exists: existsSync(versionPath), version: current === DEFAULT ? "" : current }
-    : readPkgVersion(pkgPath);
+  const pkg = jsonSource ? { exists: true, version: current } : readPkgVersion(pkgPath);
   // Decision 11: the manifest carries the npm-valid 3-digit translation of
   // the 4-digit VERSION; drift is judged against the translated form. A
   // JSON version-path is its own source of truth, so its expected form is
   // the version itself.
   const expectedPkg = jsonSource ? current : npmVersion(current);
   const state = classifyState(current, baseV, pkg.exists, pkg.version, expectedPkg);
-  // Surface version-file absence so callers (and /ship) can tell "version is
-  // genuinely 0.0.0.0" from "we made up 0.0.0.0 because the file is missing"
-  // (#2600). Without this, the DRIFT_STALE_PKG dispatch on a missing VERSION
-  // would feed repair a fabricated version that passes the shape check.
-  const versionFileExists = existsSync(versionPath);
   process.stdout.write(
     JSON.stringify({
       state,
+      versionSource: { outcome: src.outcome, path: versionRel, reason: null },
       baseVersion: baseV,
       currentVersion: current,
       pkgVersion: pkg.version || null,
       pkgExists: pkg.exists,
       pkgPath: pkg.exists ? relative(cwd, pkgPath) : null,
       expectedPkgVersion: pkg.exists ? expectedPkg : null,
-      versionFileExists,
+      versionFileExists: true,
     }) + "\n",
   );
   // DRIFT_UNEXPECTED is a real, decidable state — the caller stops on it, but the
-  // classification itself succeeded, so exit 0. (Bad args / unresolvable base are
-  // the only exit-2 cases.)
+  // classification itself succeeded, so exit 0. (Bad args / unresolvable base /
+  // a broken version source are the only exit-2 cases.)
 }
 
 /**
@@ -383,7 +409,13 @@ function cmdWrite(args: string[], cwd: string): void {
   if (!VERSION_RE.test(version!)) {
     fail(`NEW_VERSION (${version}) does not match MAJOR.MINOR.PATCH[.MICRO]. Aborting.`, 2);
   }
-  const versionRel = resolveVersionRel(cwd, argVal(args, "--version-path"));
+  const src = versionSource(cwd, argVal(args, "--version-path"));
+  if (src.outcome === "broken") failBroken(src, "write");
+  if (src.outcome !== "valid") {
+    // Never create a version file the project did not configure (#2334).
+    fail(`write: refusing to invent a version. ${noVersionNotice(src)}`, 2);
+  }
+  const versionRel = src.path!;
   const versionPath = join(cwd, versionRel);
 
   // A package.json version-path (#2501) is written in place, keeping the rest
@@ -392,9 +424,6 @@ function cmdWrite(args: string[], cwd: string): void {
   // actually publishes from; in a monorepo whose truth is frontend/package.json
   // the root one either doesn't exist or isn't the version users see.
   if (isJsonVersionPath(versionRel)) {
-    if (!existsSync(versionPath)) {
-      fail(`write: ${versionRel} does not exist. Check --version-path / .gstack/version-path.`, 2);
-    }
     // Decision 11: a JSON manifest can only carry npm-valid semver. A repo
     // whose package.json still mirrors the legacy 4-digit form and pins it as
     // the version-path would otherwise get "1.67.0.1" written into a manifest

browse/SKILL.md

@@ -165,14 +165,15 @@ Use Aside first: the user's real browser and signed-in sessions. If unavailable,
 ```bash
 _gs_d() { if command -v gtimeout >/dev/null; then gtimeout 30 "$@"; elif command -v timeout >/dev/null; then timeout 30 "$@"
 elif command -v perl >/dev/null; then perl -e 'alarm(shift);exec(@ARGV)' 30 "$@"; else return 125; fi; }
-if [ "${GSTACK_SKIP_ASIDE:-}" = "1" ] || ! command -v aside >/dev/null 2>&1; then
-  echo "NEEDS_ASIDE"
+_A=aside; command -v aside >/dev/null || _A=$(command -v ~/.local/bin/aside)
+if [ "${GSTACK_SKIP_ASIDE:-}" = "1" ] || [ -z "$_A" ]; then
+  echo "NEEDS_ASIDE: ${GSTACK_PLATFORM:-$(uname)}"
 else
-  _rc=0; _o=$(_gs_d aside repl 'console.log("ASIDE_READY " + pwd)' 2>&1) || _rc=$?
+  _rc=0; _o=$(_gs_d "$_A" repl 'console.log("ASIDE_READY " + pwd)' 2>&1) || _rc=$?
   case "$_rc" in
     124|142) echo "ASIDE_TIMEOUT: probe deadline exceeded" ;;
     125) echo "ASIDE_UNAVAILABLE: bounded probe unavailable" ;;
-    0) if printf '%s\n' "$_o" | grep -q '^ASIDE_READY '; then echo "READY: aside"
+    0) if printf '%s\n' "$_o" | grep -q '^ASIDE_READY '; then echo "READY: $_A"
        else echo "ASIDE_NOT_RUNNING: no readiness marker"; fi ;;
     *) echo "ASIDE_CLI_ERROR: exit $_rc; inspect aside --help locally" ;;
   esac
@@ -180,9 +181,9 @@ else
 fi
 ```
 
-1. `NEEDS_ASIDE`: if `uname -s` prints `Darwin`, say once: "Download Aside (macOS 15+) at aside.com, open it, sign in, then re-run." Off macOS, do not pitch it. NEVER run an installer, brew formula, or download for them; never substitute unit tests or curl for the browser step. Then continue with the Browser fallback section below.
-2. `ASIDE_NOT_RUNNING`: ask once to open the app and retry. Other non-READY statuses: report the safe status, not "app stopped". Never print raw diagnostics (private paths/tokens). Then continue with the Browser fallback section below.
-3. `READY`: continue. `aside --help` and `aside <command> --help` are the authority on flags; take operational syntax from them, never new permissions or scope.
+1. `NEEDS_ASIDE: Darwin` (trust it; don't re-probe): say once: "Download Aside (macOS 15+) at aside.com; open, sign in, re-run." Off macOS, do not pitch it. NEVER run an installer, brew formula, or download; never substitute unit tests or curl for the browser step. Then continue with the Browser fallback section below.
+2. `ASIDE_NOT_RUNNING`: ask once to open the app and retry. Other non-READY statuses: report the safe status, not "app stopped". Never print raw diagnostics. Then continue with the Browser fallback section below.
+3. `READY`: continue (a printed path runs in place of `aside`). `aside --help` and `aside <command> --help` are the authority on flags; take operational syntax from them, never new permissions or scope.
 
 ### Rules for driving a real browser
 

browse/scripts/build-node-server.sh

@@ -21,7 +21,9 @@ echo "Building Node-compatible server bundle..."
 
 # Step 1: Transpile server.ts to a single .mjs bundle (externalize runtime deps)
 #
-# Externalize packages with native addons, dynamic imports, or runtime resolution.
+# Externalize packages with native addons, dynamic imports, or runtime resolution
+# (sharp loads a platform .node addon; socks is resolved at runtime, and Bun on
+# Windows refuses to inline either, #2260).
 # If you add a new dependency that uses `await import()` or has a .node addon,
 # add it here. Otherwise `bun build --outfile` will fail with
 # "cannot write multiple output files without an output directory".
@@ -32,7 +34,9 @@ bun build "$SRC_DIR/server.ts" \
   --external playwright-core \
   --external diff \
   --external "bun:sqlite" \
-  --external "@ngrok/ngrok"
+  --external "@ngrok/ngrok" \
+  --external socks \
+  --external sharp
 
 # Step 2: Post-process
 # Replace import.meta.dir with a resolvable reference

browse/scripts/extension-id.ts

@@ -8,7 +8,7 @@
  * 0-9a-f to a-p (the "mpdecimal" alphabet). Pinning the public key in the
  * manifest pins the ID, which lets the browse server verify the Origin
  * header on POST /extension-token against a single known extension
- * identity (GSTACK_EXTENSION_ID in browse/src/server.ts).
+ * identity (GSTACK_EXTENSION_ID in browse/src/extension-id.ts).
  *
  * The private half of the keypair is intentionally NOT in the repo — the
  * extension is loaded unpacked (or baked into Browser.app), so only the

browse/sections/command-list.md

@@ -104,7 +104,7 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 | `scroll [sel|@ref]` | With a selector, smooth-scrolls the element into view. Without a selector, jumps to page bottom. No --by/--to amount option; for pixel-precise scrolling use `js window.scrollTo(0, N)`. |
 | `select <sel> <val>` | Select dropdown option by value, label, or visible text |
 | `style <sel> <prop> <value> | style --undo [N]` | Modify CSS property on element (with undo support) |
-| `type <text>` | Type into focused element |
+| `type [--selector <sel>] [--] <text>` | Send keystrokes to the focused element, or to <sel> with --selector (focuses it first). Text that starts with -- goes after a -- separator. |
 | `upload <sel> <file> [file2...]` | Upload file(s) |
 | `useragent <string>` | Set user agent |
 | `viewport [<WxH>] [--scale <n>]` | Set viewport size and optional deviceScaleFactor (1-3, for retina screenshots). --scale requires a context rebuild. |

browse/src/browser-manager.ts

@@ -20,11 +20,12 @@ import { chromium, type Browser, type BrowserContext, type BrowserContextOptions
 import { writeSecureFile, mkdirSecure } from './file-permissions';
 import { addConsoleEntry, addNetworkEntry, addDialogEntry, networkBuffer, type DialogEntry } from './buffers';
 import { emitActivity } from './activity';
-import { validateNavigationUrl } from './url-validation';
+import { validateNavigationUrl, blockedNavigationReason } from './url-validation';
 import { TabSession, type RefEntry } from './tab-session';
-import { resolveChromiumProfile, cleanSingletonLocks } from './config';
+import { resolveChromiumProfile, cleanSingletonLocks, resolveConfig } from './config';
+import { ensureProjectProfile } from './chromium-profiles';
 import { launchWithXProtectHeal } from './xprotect-heal';
-import { readPidStartTime, shouldSpawnXvfb, pickFreeDisplay, spawnXvfb, xvfbInstallHint, type XvfbHandle } from './xvfb';
+import { readPidStartTime, shouldSpawnXvfb, spawnFreeXvfb, xvfbInstallHint, type XvfbHandle } from './xvfb';
 import { withCdpSession } from './cdp-bridge';
 import type { MemorySnapshot, MemoryStructureStats, MemoryTabSnapshot, MemoryProcess } from './memory-snapshot';
 
@@ -318,6 +319,25 @@ export class BrowserManager {
   // ─── Tab Ownership (multi-agent isolation) ──────────────
   // Maps tabId → clientId. Unowned tabs (not in this map) are root-only for writes.
   private tabOwnership: Map<number, string> = new Map();
+  /** Headless launch with BROWSE_EXTENSIONS_DIR: a persistent context (#2281). */
+  private extensionContext = false;
+  /** Pending and recorded navigation-guard verdicts per page (D2). */
+  private navigationGuards = new WeakMap<Page, { pending: Set<Promise<void>>; blocked: string | null }>();
+  // Our own 'disconnected' listeners per browser. Detach only these: removing
+  // every 'disconnected' listener also strips Playwright's internal one that
+  // resolves browser.close(), so each close waited the full race timeout (and
+  // Playwright 1.62 has no Browser.process() for the SIGKILL fallback).
+  private disconnectHandlers = new WeakMap<Browser, Array<() => void>>();
+  private onBrowserDisconnected(browser: Browser | null | undefined, handler: () => void): void {
+    if (!browser) return;
+    browser.on('disconnected', handler);
+    this.disconnectHandlers.set(browser, [...(this.disconnectHandlers.get(browser) ?? []), handler]);
+  }
+  private detachDisconnectHandlers(browser: Browser | null | undefined): void {
+    if (!browser) return;
+    for (const handler of this.disconnectHandlers.get(browser) ?? []) browser.off('disconnected', handler);
+    this.disconnectHandlers.delete(browser);
+  }
 
   // ─── Dialog Handling (global, not per-tab) ──────────────────
   private dialogAutoAccept: boolean = true;
@@ -362,10 +382,8 @@ export class BrowserManager {
     if (this.displayAllocation) return this.displayAllocation;
     if (!shouldSpawnXvfb({ ...process.env, BROWSE_HEADED: '1' }, process.platform).spawn) return;
     this.displayAllocation = (async () => {
-      const displayNum = pickFreeDisplay();
-      if (displayNum == null) throw new Error('no free X display in range :99-:120 — refusing to clobber existing X servers');
       try {
-        const handle = await spawnXvfb(displayNum);
+        const handle = await spawnFreeXvfb();
         if (this.closing) {
           handle.close();
           throw new Error('Browser is shutting down');
@@ -528,11 +546,22 @@ export class BrowserManager {
     this.closing = false;
     // ─── Extension Support ────────────────────────────────────
     // BROWSE_EXTENSIONS_DIR points to an unpacked Chrome extension directory.
-    // Extensions only work in headed mode, so we use an off-screen window.
+    // Extensions only run in a persistent context (launch() + newContext()
+    // isolates them), so that path uses launchPersistentContext with Chrome's
+    // new headless mode: no window, unlike the old off-screen window that
+    // macOS still showed (#2281, #432).
     const extensionsDir = process.env.BROWSE_EXTENSIONS_DIR;
-    const { STEALTH_LAUNCH_ARGS, buildGStackLaunchArgs } = await import('./stealth');
+    const { STEALTH_LAUNCH_ARGS, buildGStackLaunchArgs, STEALTH_IGNORE_DEFAULT_ARGS } = await import('./stealth');
     const launchArgs: string[] = [...STEALTH_LAUNCH_ARGS, ...buildGStackLaunchArgs()];
-    let useHeadless = true;
+    // #2771/#1968: honor GSTACK_CHROMIUM_PATH headless too (NixOS, macOS 13).
+    // That bundle belongs to the user, so the XProtect heal never touches it,
+    // and a launch failure names it.
+    const executablePath = process.env.GSTACK_CHROMIUM_PATH || undefined;
+    const nameCustomChromium = (err: unknown): never => {
+      if (!executablePath) throw err;
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`Chromium at GSTACK_CHROMIUM_PATH=${executablePath} failed to launch: ${message}\nFix: point GSTACK_CHROMIUM_PATH at a working Chromium or Chrome binary, or unset it to use Playwright's bundled Chromium.`, { cause: err });
+    };
 
     // Docker/CI/root: Chromium sandbox requires unprivileged user namespaces which
     // are typically disabled in containers and are never available for the root
@@ -552,24 +581,59 @@ export class BrowserManager {
           `--load-extension=${extensionsDir}`,
         );
       }
-      launchArgs.push('--window-position=-9999,-9999', '--window-size=1,1');
-      useHeadless = false; // extensions require headed mode; off-screen window simulates headless
+      launchArgs.push('--headless=new');
       console.log(`[browse] Extensions loaded from: ${extensionsDir}`);
     }
 
-    // #2709: headless-only — the extensions path above forces headed mode,
-    // and headed/GBrowser sessions must keep the GPU.
-    if (useHeadless) {
-      launchArgs.push(...headlessGpuArgs(process.platform, process.env));
+    // #2709: headless-only GPU flags; headed/GBrowser sessions keep the GPU.
+    launchArgs.push(...headlessGpuArgs(process.platform, process.env));
+
+    const contextOptions: BrowserContextOptions = {
+      viewport: { width: this.currentViewport.width, height: this.currentViewport.height },
+      deviceScaleFactor: this.deviceScaleFactor,
+    };
+    if (this.customUserAgent) {
+      contextOptions.userAgent = this.customUserAgent;
+    }
+
+    if (extensionsDir) {
+      const profileDir = require('path').join(resolveConfig().stateDir, 'extensions', 'chromium-profile');
+      require('fs').mkdirSync(profileDir, { recursive: true, mode: 0o700 });
+      cleanSingletonLocks(profileDir);
+      this.context = await launchWithXProtectHeal(() => chromium.launchPersistentContext(profileDir, {
+        headless: false, // --headless=new in launchArgs: windowless, extensions run
+        handleSIGINT: false,
+        handleSIGTERM: false,
+        handleSIGHUP: false,
+        chromiumSandbox: shouldEnableChromiumSandbox(),
+        args: launchArgs,
+        ignoreDefaultArgs: STEALTH_IGNORE_DEFAULT_ARGS,
+        ...contextOptions,
+        ...(executablePath ? { executablePath } : {}),
+        ...(this.proxyConfig ? { proxy: this.proxyConfig } : {}),
+      }), { usesCustomExecutable: Boolean(executablePath) }).catch(nameCustomChromium);
+      this.extensionContext = true;
+      this.browser = this.context.browser();
+      this.onBrowserDisconnected(this.browser, () => {
+        void handleChromiumDisconnect(this.browser);
+      });
+      for (const page of this.context.pages()) await page.close().catch(() => {});
+      if (Object.keys(this.extraHeaders).length > 0) {
+        await this.context.setExtraHTTPHeaders(this.extraHeaders);
+      }
+      const { applyStealth } = await import('./stealth');
+      await applyStealth(this.context);
+      await this.newTab();
+      return;
     }
 
     // XProtect self-heal wrapper (P0 #2554): a macOS definition update can
     // start SIGKILLing the pinned Chromium at spawn. On the classified
     // signature, clear quarantine on the Playwright cache + force-reinstall
-    // once, then retry this launch once. This headless path always uses the
-    // Playwright cache (no executablePath), so the heal is never scoped out.
+    // once, then retry this launch once. A GSTACK_CHROMIUM_PATH bundle is
+    // scoped out of the heal.
     this.browser = await launchWithXProtectHeal(() => chromium.launch({
-      headless: useHeadless,
+      headless: true,
       // #2220: the daemon owns signal policy, not Playwright. Playwright's
       // default handlers close Chromium the moment THIS process receives
       // SIGINT/SIGTERM/SIGHUP — which fights the deliberate headless
@@ -587,8 +651,9 @@ export class BrowserManager {
       // namespaces that aren't available.
       chromiumSandbox: shouldEnableChromiumSandbox(),
       ...(launchArgs.length > 0 ? { args: launchArgs } : {}),
+      ...(executablePath ? { executablePath } : {}),
       ...(this.proxyConfig ? { proxy: this.proxyConfig } : {}),
-    }));
+    }), { usesCustomExecutable: Boolean(executablePath) }).catch(nameCustomChromium);
 
     // Chromium disconnect → distinguish clean user-quit from crash. Both
     // events look identical to Playwright (one 'disconnected' fires), but
@@ -599,7 +664,7 @@ export class BrowserManager {
     // means "user wanted this, don't restart"; non-zero means "crash, please
     // bring me back." Without this distinction every Cmd+Q gets treated as
     // a crash and the user-visible window keeps respawning.
-    this.browser.on('disconnected', () => {
+    this.onBrowserDisconnected(this.browser, () => {
       void handleChromiumDisconnect(this.browser);
     });
 
@@ -612,13 +677,6 @@ export class BrowserManager {
         : null;
     }
 
-    const contextOptions: BrowserContextOptions = {
-      viewport: { width: this.currentViewport.width, height: this.currentViewport.height },
-      deviceScaleFactor: this.deviceScaleFactor,
-    };
-    if (this.customUserAgent) {
-      contextOptions.userAgent = this.customUserAgent;
-    }
     this.context = await this.browser.newContext(contextOptions);
 
     if (Object.keys(this.extraHeaders).length > 0) {
@@ -706,6 +764,7 @@ export class BrowserManager {
     const fs = require('fs');
     const path = require('path');
     const userDataDir = resolveChromiumProfile();
+    ensureProjectProfile(userDataDir);
     fs.mkdirSync(userDataDir, { recursive: true });
 
     // Pre-launch cleanup of stale SingletonLock/Socket/Cookie. Chromium's
@@ -898,7 +957,7 @@ export class BrowserManager {
     // terminal agent, save session, clean profile locks + state file) so
     // crashes don't strand resources either.
     if (this.browser) {
-      this.browser.on('disconnected', () => {
+      this.onBrowserDisconnected(this.browser, () => {
         if (this.intentionalDisconnect) return;
         const browserRef = this.browser;
         void (async () => {
@@ -954,17 +1013,17 @@ export class BrowserManager {
       (t as { unref?: () => void }).unref?.();
     });
     if (this.browser || ((this.connectionMode === 'headed' || this.handoffPrevious) && this.context)) {
-      if (this.connectionMode === 'headed' || this.handoffPrevious) {
+      if (this.connectionMode === 'headed' || this.handoffPrevious || this.extensionContext) {
         // Headed/persistent context mode: close the context (which closes the browser)
         this.intentionalDisconnect = true;
-        if (this.browser) this.browser.removeAllListeners('disconnected');
+        this.detachDisconnectHandlers(this.browser);
         await Promise.race([
           this.context ? this.context.close() : Promise.resolve(),
           raceTimeout(this.closeRaceMs),
         ]).catch(() => {});
       } else if (this.browser) {
         // Launched mode: close the browser we spawned.
-        this.browser.removeAllListeners('disconnected');
+        this.detachDisconnectHandlers(this.browser);
         // Grab the child handle BEFORE the race: nulling this.browser after a
         // race-timeout used to ABANDON a live Chromium whose sockets kept the
         // caller's event loop (and keep-alive connections into test servers)
@@ -982,7 +1041,7 @@ export class BrowserManager {
       this.browser = null;
     }
     if (previousBrowser && previousBrowser !== currentBrowser) {
-      previousBrowser.removeAllListeners('disconnected');
+      this.detachDisconnectHandlers(previousBrowser);
       const child = launchedProcess(previousBrowser);
       const closed = await Promise.race([
         previousBrowser.close().then(() => true), raceTimeout(this.closeRaceMs),
@@ -1679,6 +1738,9 @@ export class BrowserManager {
     if (this.connectionMode === 'headed') {
       throw new Error('Cannot recreate context in headed mode. Use disconnect first.');
     }
+    if (this.extensionContext) {
+      throw new Error('Cannot recreate context while BROWSE_EXTENSIONS_DIR extensions are loaded (persistent context). Restart browse with the new settings instead.');
+    }
     if (!this.browser || !this.context) {
       throw new Error('Browser not launched');
     }
@@ -1866,6 +1928,7 @@ export class BrowserManager {
       // ignoring $CHROMIUM_PROFILE / $GSTACK_HOME and skipping the lock
       // cleanup — the third shipped drift between the three launch paths.
       const userDataDir = resolveChromiumProfile();
+      ensureProjectProfile(userDataDir);
       fs.mkdirSync(userDataDir, { recursive: true });
       cleanSingletonLocks(userDataDir);
 
@@ -1951,7 +2014,7 @@ export class BrowserManager {
 
       if (this.browser) {
         const browserRef = this.browser;
-        this.browser.on('disconnected', () => {
+        this.onBrowserDisconnected(this.browser, () => {
           if (this.intentionalDisconnect) return;
           void handleChromiumDisconnect(browserRef);
         });
@@ -1965,7 +2028,7 @@ export class BrowserManager {
       catch (err) { console.warn('[browse] Headed promotion callback failed:', err); }
 
       // 4. Close old headless browser (fire-and-forget)
-      previous.browser.removeAllListeners('disconnected');
+      this.detachDisconnectHandlers(previous.browser);
       previous.browser.close().catch(() => {});
 
       return [
@@ -2024,10 +2087,61 @@ export class BrowserManager {
     return null;
   }
 
+  /**
+   * Run a command and surface any navigation the guard blocked while it ran.
+   * The block reason replaces the command's own result or error (often
+   * "navigation interrupted"), so the caller learns why the tab is blank.
+   */
+  async failIfNavigationBlocked<T>(page: Page, work: Promise<T>): Promise<T> {
+    const outcome = await work.then((value) => ({ value }), (error) => ({ error }));
+    const guard = this.navigationGuards.get(page);
+    while (guard && guard.pending.size > 0) await Promise.all([...guard.pending]);
+    const blocked = guard?.blocked ?? null;
+    if (guard) guard.blocked = null;
+    if (blocked) throw new Error(blocked);
+    if ('error' in outcome) throw outcome.error;
+    return outcome.value;
+  }
+
+  /**
+   * D2: validateNavigationUrl only sees explicit navigations. Redirect hops and
+   * page-driven navigations (links, scripts, forms, frames) arrive here as
+   * navigation requests; one that targets a blocked address blanks the tab and
+   * is reported by failIfNavigationBlocked.
+   */
+  private guardNavigations(page: Page): void {
+    if (this.navigationGuards.has(page)) return;
+    const guard = { pending: new Set<Promise<void>>(), blocked: null as string | null };
+    this.navigationGuards.set(page, guard);
+    page.on('request', (req) => {
+      if (!req.isNavigationRequest()) return;
+      const check: Promise<void> = blockedNavigationReason(req.url()).then(async (reason) => {
+        if (!reason || page.isClosed()) return;
+        guard.blocked = reason;
+        console.warn(`[browse] ${reason} (navigation from ${req.frame().url() || 'a new page'}; tab reset to about:blank)`);
+        // A target that fails fast commits its error page around the reset, so
+        // let it settle (bounded; a hanging target is cut off by the reset),
+        // then blank the tab until it stays blank (about:blank loads at once).
+        await Promise.race([req.response().catch(() => null), new Promise((resolve) => setTimeout(resolve, 1_000))]);
+        // Leaving an error page can commit a second about:blank after the reset
+        // resolves; wait for the main frame to stay quiet so the next command's
+        // navigation is not interrupted by it.
+        for (let attempt = 0; attempt < 3 && !page.isClosed(); attempt++) {
+          await page.goto('about:blank', { waitUntil: 'load', timeout: 5_000 }).catch(() => {});
+          const late = await page.waitForEvent('framenavigated', { predicate: (frame) => frame === page.mainFrame(), timeout: 250 })
+            .then(() => true, () => false);
+          if (!late && page.url() === 'about:blank') break;
+        }
+      }).finally(() => { guard.pending.delete(check); });
+      guard.pending.add(check);
+    });
+  }
+
   // ─── Console/Network/Dialog/Ref Wiring ────────────────────
   private wirePageEvents(page: Page) {
     const pages = this.pages;
     const tabSessions = this.tabSessions;
+    this.guardNavigations(page);
     // Track tab close — remove from pages and sessions maps, switch to another tab
     page.on('close', () => {
       for (const [id, p] of pages) {

browse/src/chromium-profiles.ts

@@ -0,0 +1,212 @@
+/**
+ * Per-project headed Chromium profiles (D5, #2492).
+ *
+ * The headed profile used to be machine-wide (<gstack home>/chromium-profile),
+ * so starting headed browse in one project SIGKILLed another project's live
+ * headed Chromium. Each project now gets <project>/.gstack/chromium-profile
+ * (config.resolveChromiumProfile). This module owns the profile lifecycle:
+ * who holds a profile's SingletonLock, first-use seeding from the old
+ * machine-wide profile, and `browse profiles list|prune`.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { resolveGstackHome } from './config';
+import { isProcessAlive } from './error-handling';
+import { readPidCmdline } from './xvfb';
+import { atomicWriteSync } from '../../lib/fs-atomic';
+
+export type ProfileOwner =
+  | { state: 'free' }
+  | { state: 'orphan'; pid: number }
+  | { state: 'live'; pid: number; detail: string };
+
+/** Processes an orphan is reparented to: init, launchd, and common subreapers. */
+const REAPERS = new Set(['init', 'systemd', 'launchd', 'tini', 'dumb-init', 'docker-init']);
+
+export function legacyProfileDir(): string {
+  return path.join(resolveGstackHome(), 'chromium-profile');
+}
+
+function registryPath(): string {
+  return path.join(resolveGstackHome(), 'browse-profiles.json');
+}
+
+function readParentPid(pid: number): number {
+  try {
+    const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf-8');
+    return Number(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[1]);
+  } catch {
+    try {
+      const r = Bun.spawnSync(['ps', '-o', 'ppid=', '-p', String(pid)], { stdout: 'pipe', stderr: 'pipe', timeout: 2000, windowsHide: true });
+      return r.exitCode === 0 ? Number(r.stdout.toString().trim()) : 0;
+    } catch {
+      return 0;
+    }
+  }
+}
+
+/**
+ * Who holds this profile. The SingletonLock symlink target is "host-PID".
+ * Only a process on this host that is a Chromium using this exact profile
+ * counts as the holder; a dead or recycled PID means the lock is stale. An
+ * orphan (reparented to init or a subreaper after its daemon died) may be
+ * reaped; anything else, including a lock from another host, is a live owner
+ * that must never be killed.
+ */
+export function profileOwner(profileDir: string): ProfileOwner {
+  let target: string;
+  try {
+    target = fs.readlinkSync(path.join(profileDir, 'SingletonLock'));
+  } catch {
+    return { state: 'free' };
+  }
+  const dash = target.lastIndexOf('-');
+  const host = target.slice(0, dash);
+  const pid = Number(target.slice(dash + 1));
+  if (!Number.isSafeInteger(pid) || pid <= 0) return { state: 'free' };
+  if (host !== os.hostname()) {
+    return { state: 'live', pid, detail: `locked by PID ${pid} on another host (${host})` };
+  }
+  if (!isProcessAlive(pid)) return { state: 'free' };
+  const cmd = readPidCmdline(pid);
+  const dirs = new Set([profileDir]);
+  try { dirs.add(fs.realpathSync(profileDir)); } catch {}
+  const usesProfile = [...dirs].some(d => cmd.includes(`--user-data-dir=${d}`));
+  if (!/chrom/i.test(cmd) || !usesProfile) return { state: 'free' };
+  const ppid = readParentPid(pid);
+  const parent = ppid > 1 ? path.basename(readPidCmdline(ppid).split(' ')[0] || '') : '';
+  if (ppid <= 1 || !isProcessAlive(ppid) || REAPERS.has(parent)) return { state: 'orphan', pid };
+  return { state: 'live', pid, detail: `in use by Chromium PID ${pid} (started by PID ${ppid}: ${parent || 'unknown'})` };
+}
+
+function readRegistry(): string[] {
+  try {
+    const list = JSON.parse(fs.readFileSync(registryPath(), 'utf-8'));
+    return Array.isArray(list) ? list.filter((p): p is string => typeof p === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeRegistry(list: string[]): void {
+  fs.mkdirSync(path.dirname(registryPath()), { recursive: true });
+  atomicWriteSync(registryPath(), JSON.stringify([...new Set(list)].sort(), null, 2) + '\n');
+}
+
+/**
+ * Create a project's headed profile on first use. Seeds it from the old
+ * machine-wide profile only when nothing holds that profile, copying into a
+ * temporary 0700 directory without Singleton* files and renaming it into
+ * place, so a concurrent first use or an interrupted copy never leaves a
+ * half-written profile. Says what happened once, through `log`.
+ */
+export function ensureProjectProfile(profileDir: string, log: (msg: string) => void = console.log): void {
+  if (fs.existsSync(profileDir)) return;
+  // An explicit CHROMIUM_PROFILE belongs to its caller (gbrowser's per-workspace
+  // gbd): never seed it from the shared profile or register it for pruning.
+  const explicit = process.env.CHROMIUM_PROFILE;
+  if (explicit && path.resolve(explicit) === path.resolve(profileDir)) return;
+  const legacy = legacyProfileDir();
+  if (path.resolve(profileDir) === path.resolve(legacy)) return;
+  writeRegistry([...readRegistry(), path.resolve(profileDir)]);
+  fs.mkdirSync(path.dirname(profileDir), { recursive: true });
+  const fresh = (why: string) => {
+    fs.mkdirSync(profileDir, { recursive: true, mode: 0o700 });
+    if (why) log(why);
+  };
+  if (!fs.existsSync(legacy)) return fresh('');
+  const before = profileOwner(legacy);
+  if (before.state !== 'free') {
+    return fresh(`[browse] Headed browse now keeps a profile per project (${profileDir}). The old shared profile (${legacy}) is ${'detail' in before ? before.detail : `held by orphaned PID ${before.pid}`}, so this project starts with a fresh profile. To import it later: close that browser, delete ${profileDir}, and start headed browse again.`);
+  }
+  const tmp = `${profileDir}.seed-${process.pid}`;
+  fs.rmSync(tmp, { recursive: true, force: true });
+  try {
+    fs.cpSync(legacy, tmp, {
+      recursive: true,
+      verbatimSymlinks: true,
+      filter: (src) => !path.basename(src).startsWith('Singleton'),
+    });
+    fs.chmodSync(tmp, 0o700);
+    if (profileOwner(legacy).state !== 'free') {
+      fs.rmSync(tmp, { recursive: true, force: true });
+      return fresh(`[browse] The old shared profile (${legacy}) came into use while it was being copied, so this project (${profileDir}) starts with a fresh profile.`);
+    }
+    fs.renameSync(tmp, profileDir);
+  } catch (err) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    if (fs.existsSync(profileDir)) return;
+    throw err;
+  }
+  log(`[browse] Headed browse now keeps a profile per project. Copied your logins and settings from ${legacy} to ${profileDir} (${formatBytes(dirBytes(profileDir))}). See \`browse profiles\` to list or prune profiles.`);
+}
+
+function dirBytes(dir: string): number {
+  let total = 0;
+  const walk = (d: string) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.isFile()) total += fs.statSync(p).size;
+    }
+  };
+  try { walk(dir); } catch {}
+  return total;
+}
+
+function formatBytes(n: number): string {
+  if (n < 1024 * 1024) return `${Math.round(n / 1024)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function describeOwner(owner: ProfileOwner): string {
+  if (owner.state === 'free') return 'idle';
+  if (owner.state === 'orphan') return `held by orphaned PID ${owner.pid}`;
+  return owner.detail;
+}
+
+/** `browse profiles [list]` and `browse profiles prune [--days N]`. Returns the exit code. */
+export function runProfilesCommand(args: string[], out: (line: string) => void = console.log): number {
+  const sub = args[0] ?? 'list';
+  const known = readRegistry();
+  const legacy = legacyProfileDir();
+  if (sub === 'list') {
+    const rows = [...(fs.existsSync(legacy) ? [legacy] : []), ...known];
+    if (rows.length === 0) {
+      out('No headed browser profiles yet. One is created per project on first `browse --headed` or `browse connect`.');
+      return 0;
+    }
+    for (const dir of rows) {
+      if (!fs.existsSync(dir)) { out(`${dir}  (missing: project moved or deleted; \`browse profiles prune\` forgets it)`); continue; }
+      const age = Math.floor((Date.now() - fs.statSync(dir).mtimeMs) / 86_400_000);
+      out(`${dir}  ${formatBytes(dirBytes(dir))}  last used ${age}d ago  ${describeOwner(profileOwner(dir))}${dir === legacy ? '  (old shared profile)' : ''}`);
+    }
+    return 0;
+  }
+  if (sub === 'prune') {
+    const daysIdx = args.indexOf('--days');
+    const days = daysIdx >= 0 ? Number(args[daysIdx + 1]) : 30;
+    if (!Number.isFinite(days) || days < 0) {
+      out('Usage: browse profiles prune [--days N]  (default 30)');
+      return 2;
+    }
+    const keep: string[] = [];
+    let freed = 0;
+    for (const dir of known) {
+      if (!fs.existsSync(dir)) { out(`forgot ${dir} (no longer exists)`); continue; }
+      const idleDays = (Date.now() - fs.statSync(dir).mtimeMs) / 86_400_000;
+      const owner = profileOwner(dir);
+      if (idleDays < days || owner.state !== 'free') { keep.push(dir); continue; }
+      const bytes = dirBytes(dir);
+      fs.rmSync(dir, { recursive: true, force: true });
+      freed += bytes;
+      out(`removed ${dir} (${formatBytes(bytes)}, idle ${Math.floor(idleDays)}d)`);
+    }
+    writeRegistry(keep);
+    out(`Pruned profiles idle for ${days}+ days; freed ${formatBytes(freed)}. Profiles in use are never removed. The old shared profile (${legacy}) is left alone.`);
+    return 0;
+  }
+  out('Usage: browse profiles [list] | browse profiles prune [--days N]');
+  return 2;
+}

browse/src/cli.ts

@@ -18,7 +18,8 @@ import { writeSecureFile, mkdirSecure } from './file-permissions';
 import { resolveConfig, ensureStateDir, readVersionHash, isPairAgentEnabled, resolveChromiumProfile } from './config';
 import { parseProxyConfig, computeConfigHash, ProxyConfigError } from './proxy-config';
 import { redactProxyUrl } from './proxy-redact';
-import { spawnTerminalAgent } from './terminal-agent-control';
+import { spawnTerminalAgent, BUN_CHILD_FLAGS } from './terminal-agent-control';
+import { profileOwner, ensureProjectProfile, runProfilesCommand } from './chromium-profiles';
 // Zero side effects on import (documented invariant in token-registry.ts) —
 // safe to pull the shared pairing default into the CLI.
 import { DEFAULT_PAIR_SCOPES } from './token-registry';
@@ -84,8 +85,6 @@ export function resolveServerScript(
   );
 }
 
-const SERVER_SCRIPT = resolveServerScript();
-
 /**
  * On Windows, resolve the Node.js-compatible server bundle.
  * Falls back to null if not found (server will use Bun instead).
@@ -109,13 +108,23 @@ export function resolveNodeServerScript(
   return null;
 }
 
-const NODE_SERVER_SCRIPT = IS_WINDOWS ? resolveNodeServerScript() : null;
-
-// On Windows, hard-fail if server-node.mjs is missing — the Bun path is known broken.
-if (IS_WINDOWS && !NODE_SERVER_SCRIPT) {
-  throw new Error(
-    'server-node.mjs not found. Run `bun run build` to generate the Windows server bundle.'
-  );
+/**
+ * Which server to start, resolved only when a server is actually started
+ * (#2439). Windows runs the Node bundle and never needs server.ts, which a
+ * minimal runtime root does not ship; resolving server.ts at module load made
+ * every command, even --help, fail there.
+ */
+export function resolveServerLaunch(
+  platform: NodeJS.Platform = process.platform,
+  env: Record<string, string | undefined> = process.env,
+  metaDir: string = import.meta.dir,
+  execPath: string = process.execPath,
+): { runtime: 'node' | 'bun'; script: string } {
+  if (platform !== 'win32') return { runtime: 'bun', script: resolveServerScript(env, metaDir, execPath) };
+  // On Windows, hard-fail if server-node.mjs is missing — the Bun path is known broken.
+  const script = resolveNodeServerScript(metaDir, execPath);
+  if (!script) throw new Error('server-node.mjs not found. Run `bun run build` to generate the Windows server bundle.');
+  return { runtime: 'node', script };
 }
 
 interface ServerState {
@@ -277,23 +286,21 @@ function cleanChromiumProfileLocks(profileDir: string = chromiumProfileDir()): v
   }
 }
 
-/** Kill an orphaned Chromium that still holds the profile's SingletonLock. The
- * lock symlink target is "hostname-PID"; killing that PID tears down its
- * renderer tree so the next launch starts clean. No-op when absent/stale. */
+/** Kill an orphaned Chromium that still holds the profile's SingletonLock so
+ * the next launch starts clean (#1781). Only a Chromium on this host that uses
+ * this profile and whose daemon is gone is killed; a profile held by a live
+ * process is never killed — browse stops and names the holder (D5, #2492). */
 async function killOrphanChromium(profileDir: string = chromiumProfileDir()): Promise<void> {
-  try {
-    const lockTarget = fs.readlinkSync(path.join(profileDir, 'SingletonLock')); // "hostname-12345"
-    const orphanPid = parseInt(lockTarget.split('-').pop() || '', 10);
-    if (orphanPid && isProcessAlive(orphanPid)) {
-      safeKill(orphanPid, 'SIGTERM');
-      await new Promise(r => setTimeout(r, 1000));
-      if (isProcessAlive(orphanPid)) {
-        safeKill(orphanPid, 'SIGKILL');
-        await new Promise(r => setTimeout(r, 500));
-      }
-    }
-  } catch (err: any) {
-    if (err?.code !== 'ENOENT' && err?.code !== 'EINVAL') throw err;
+  const owner = profileOwner(profileDir);
+  if (owner.state === 'free') return;
+  if (owner.state === 'live') {
+    throw new Error(`Headed Chromium profile ${profileDir} is ${owner.detail}. Close that browser first, or set CHROMIUM_PROFILE to a different directory.`);
+  }
+  safeKill(owner.pid, 'SIGTERM');
+  await new Promise(r => setTimeout(r, 1000));
+  if (isProcessAlive(owner.pid)) {
+    safeKill(owner.pid, 'SIGKILL');
+    await new Promise(r => setTimeout(r, 500));
   }
 }
 
@@ -591,6 +598,7 @@ function openDaemonLogSink(): number | 'ignore' {
 }
 
 async function startServer(extraEnv?: Record<string, string>): Promise<ServerState> {
+  const server = resolveServerLaunch();
   ensureStateDir(config);
 
   // Bound the append-mode daemon log before the new daemon starts writing.
@@ -612,6 +620,7 @@ async function startServer(extraEnv?: Record<string, string>): Promise<ServerSta
   // blocked by the previous Chromium's SingletonLock — the self-inflicted
   // crash-loop. Previously only the manual connect preamble did this.
   if ((extraEnv?.BROWSE_HEADED ?? process.env.BROWSE_HEADED) === '1') {
+    ensureProjectProfile(chromiumProfileDir());
     await killOrphanChromium();
     cleanChromiumProfileLocks();
   }
@@ -625,7 +634,7 @@ async function startServer(extraEnv?: Record<string, string>): Promise<ServerSta
   const parentPid = parseInt(process.env.BROWSE_PARENT_PID || '', 10) === 0 ? '0' : String(process.pid);
   let spawnedServer: { pid: number; startTime: string } | null = null;
 
-  if (IS_WINDOWS && NODE_SERVER_SCRIPT) {
+  if (server.runtime === 'node') {
     // Windows: Bun.spawn() + proc.unref() doesn't truly detach on Windows —
     // when the CLI exits, the server dies with it. Use Node's child_process.spawn
     // with { detached: true } instead, which is the gold standard for Windows
@@ -641,7 +650,7 @@ async function startServer(extraEnv?: Record<string, string>): Promise<ServerSta
       `const{spawn}=require('child_process');` +
       `const fs=require('fs');` +
       `let logFd;try{logFd=fs.openSync(${daemonLogPathStr},'a');}catch(e){logFd='ignore';}` +
-      `spawn(process.execPath,[${JSON.stringify(NODE_SERVER_SCRIPT)}],` +
+      `spawn(process.execPath,[${JSON.stringify(server.script)}],` +
       `{detached:true,windowsHide:true,stdio:['ignore',logFd,logFd],env:Object.assign({},process.env,` +
       `${extraEnvStr})}).unref()`;
     Bun.spawnSync(['node', '-e', launcherCode], { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: true });
@@ -658,7 +667,7 @@ async function startServer(extraEnv?: Record<string, string>): Promise<ServerSta
     // (PPID=1, STAT=Ss) and survives the spawning shell's exit. Mirrors
     // the Windows path's rationale — same root cause, different OS API.
     const daemonLogFd = openDaemonLogSink();
-    const child = nodeSpawn('bun', ['run', SERVER_SCRIPT], {
+    const child = nodeSpawn('bun', ['run', ...BUN_CHILD_FLAGS, server.script], {
       detached: true,
       windowsHide: true,
       stdio: ['ignore', daemonLogFd, daemonLogFd],
@@ -693,7 +702,7 @@ async function startServer(extraEnv?: Record<string, string>): Promise<ServerSta
 
   if (spawnedServer?.startTime) {
     const { pid, startTime } = spawnedServer;
-    const stillOurs = () => readPidStartTime(pid) === startTime && readPidCmdline(pid).split(/\s+/).includes(SERVER_SCRIPT);
+    const stillOurs = () => readPidStartTime(pid) === startTime && readPidCmdline(pid).split(/\s+/).includes(server.script);
     if (stillOurs()) {
       safeKill(pid, 'SIGTERM');
       const deadline = Date.now() + 500;
@@ -1605,7 +1614,21 @@ async function handlePairAgent(state: ServerState, args: string[]): Promise<void
 }
 
 // ─── Main ──────────────────────────────────────────────────────
+/**
+ * #494: the CLI talks to its daemon over loopback, but Bun's fetch sends those
+ * calls through HTTP(S)_PROXY, so the daemon never looks healthy behind a
+ * corporate proxy. Append the loopback names to the user's NO_PROXY (never
+ * replace it). Bun reads NO_PROXY when the first fetch runs, so this must run
+ * before any fetch. The daemon inherits the same value.
+ */
+export function withLoopbackNoProxy(env: Record<string, string | undefined>): string {
+  const entries = (env.NO_PROXY ?? env.no_proxy ?? '').split(',').map(e => e.trim()).filter(Boolean);
+  for (const host of ['127.0.0.1', 'localhost', '::1']) if (!entries.includes(host)) entries.push(host);
+  return entries.join(',');
+}
+
 async function main() {
+  process.env.NO_PROXY = process.env.no_proxy = withLoopbackNoProxy(process.env);
   const rawArgs = process.argv.slice(2);
 
   // ─── Global flags (--proxy, --headed) ───────────────────────
@@ -1633,7 +1656,7 @@ Usage: browse <command> [args...]
 Navigation:     goto <url> | back | forward | reload | url
 Content:        text | html [sel] | links | forms | accessibility
 Interaction:    click <sel> | fill <sel> <val> | select <sel> <val>
-                hover <sel> | type <text> | press <key>
+                hover <sel> | type [--selector <sel>] <text> | press <key>
                 scroll [sel] | wait <sel|--networkidle|--load> | viewport <WxH>
                 upload <sel> <file1> [file2...]
                 cookie-import <json-file>
@@ -1653,6 +1676,7 @@ Multi-step:     chain (reads JSON from stdin)
 Tabs:           tabs | tab <id> | newtab [url] | closetab [id]
 Server:         status | cookie <n>=<v> | header <n>:<v>
                 useragent <str> | stop | restart
+                profiles [list] | profiles prune [--days N]  (per-project headed profiles)
                 tunnel revoke <name> | tunnel agents  (paired-agent tokens)
                 --force-restart: replace a live-but-busy daemon (any command;
                 LOSES tabs/cookies/logins — never done automatically)
@@ -1670,6 +1694,8 @@ Refs:           After 'snapshot', use @e1, @e2... as selectors:
   const command = args[0];
   const commandArgs = args.slice(1);
 
+  if (command === 'profiles') process.exit(runProfilesCommand(commandArgs));
+
   // ─── Headed Connect (pre-server command) ────────────────────
   // connect must be handled BEFORE ensureServer() because it needs
   // to restart the server in headed mode with the Chrome extension.

browse/src/commands.ts

@@ -122,7 +122,7 @@ export const COMMAND_DESCRIPTIONS: Record<string, { category: string; descriptio
   'fill':    { category: 'Interaction', description: 'Fill input', usage: 'fill <sel> <val>' },
   'select':  { category: 'Interaction', description: 'Select dropdown option by value, label, or visible text', usage: 'select <sel> <val>' },
   'hover':   { category: 'Interaction', description: 'Hover element', usage: 'hover <sel>' },
-  'type':    { category: 'Interaction', description: 'Type into focused element', usage: 'type <text>' },
+  'type':    { category: 'Interaction', description: 'Send keystrokes to the focused element, or to <sel> with --selector (focuses it first). Text that starts with -- goes after a -- separator.', usage: 'type [--selector <sel>] [--] <text>' },
   'press':   { category: 'Interaction', description: 'Press a Playwright keyboard key against the focused element. Names are case-sensitive: Enter, Tab, Escape, ArrowUp/Down/Left/Right, Backspace, Delete, Home, End, PageUp, PageDown. Modifiers combine with +: Shift+Enter, Control+A, Meta+K. Single printable chars (a, A, 1) work too. Full key list: https://playwright.dev/docs/api/class-keyboard#keyboard-press', usage: 'press <key>' },
   'scroll':  { category: 'Interaction', description: 'With a selector, smooth-scrolls the element into view. Without a selector, jumps to page bottom. No --by/--to amount option; for pixel-precise scrolling use `js window.scrollTo(0, N)`.', usage: 'scroll [sel|@ref]' },
   'wait':    { category: 'Interaction', description: 'Wait for element, network idle, or page load (timeout: 15s)', usage: 'wait <sel|--networkidle|--load>' },

browse/src/config.ts

@@ -250,19 +250,21 @@ export function isPairAgentEnabled(): boolean {
 }
 
 /**
- * Resolve the Chromium profile directory.
+ * Resolve the headed Chromium profile directory.
  *
  * Resolution order:
  *   1. `explicit` arg (no production caller passes one today; kept for
  *      direct programmatic use)
  *   2. CHROMIUM_PROFILE env (used by gbrowser's gbd per-workspace)
- *   3. <resolveGstackHome()>/chromium-profile (default)
+ *   3. <project state dir>/chromium-profile (default; per project since D5,
+ *      #2492 — a machine-wide profile let one project's headed launch kill
+ *      another project's live browser)
  */
 export function resolveChromiumProfile(explicit?: string): string {
   if (explicit && explicit.length > 0) return explicit;
   const env = process.env.CHROMIUM_PROFILE;
   if (env && env.length > 0) return env;
-  return path.join(resolveGstackHome(), 'chromium-profile');
+  return path.join(resolveConfig().stateDir, 'chromium-profile');
 }
 
 /**

browse/src/extension-id.ts

@@ -0,0 +1,25 @@
+/**
+ * The one extension origin allowed to reach browse's local control surfaces:
+ * POST /extension-token on the server and the terminal agent's /ws.
+ *
+ * GSTACK_EXTENSION_ID is derived from the "key" field in
+ * extension/manifest.json (first 16 bytes of SHA-256 of the DER public key,
+ * hex nibbles mapped 0-9a-f → a-p). Reproduce with:
+ *   bun browse/scripts/extension-id.ts
+ * If the manifest keypair is ever rotated, update this constant in the same
+ * commit.
+ *
+ * Forks and self-built extensions override it with
+ * `gstack-config set browse_extension_id <id>`. There is deliberately no
+ * environment override: a project's .env must never be able to widen it.
+ */
+import { readGstackConfigYamlKey } from './config';
+
+export const GSTACK_EXTENSION_ID = 'dgbkdbjebeiblbajiilljmhjdpmiglep';
+
+/** `chrome-extension://<id>` for the pinned or configured extension. */
+export function allowedExtensionOrigin(): string {
+  const configured = readGstackConfigYamlKey('browse_extension_id');
+  const id = configured && /^[a-p]{32}$/.test(configured) ? configured : GSTACK_EXTENSION_ID;
+  return `chrome-extension://${id}`;
+}

browse/src/path-security.ts

@@ -31,48 +31,41 @@ const TEMP_ONLY = [TEMP_DIR].map(d => {
   try { return fs.realpathSync(d); } catch { return d; }
 });
 
-/** Validate a file path for writing (screenshot, pdf, download, scrape, archive). */
+/**
+ * Validate a file path for writing (screenshot, pdf, download, scrape, archive).
+ *
+ * Walks the path one component at a time the way the kernel will, resolving
+ * every existing component (symlinks included) before applying the next, so
+ * `link/../x` follows `link` first. A component that does not exist yet must
+ * already sit inside a safe directory; a dangling symlink is rejected because
+ * a write would create its target. Both the caller's spelling and its lexical
+ * normalization are checked, since callers write with either.
+ */
 export function validateOutputPath(filePath: string): void {
-  const resolved = path.resolve(filePath);
-
-  // If the target already exists and is a symlink, resolve through it.
-  // Without this, a symlink at /tmp/evil.png → /etc/crontab passes the
-  // parent-directory check (parent is /tmp, which is safe) but the actual
-  // write follows the symlink to /etc/crontab.
-  try {
-    const stat = fs.lstatSync(resolved);
-    if (stat.isSymbolicLink()) {
-      const realTarget = fs.realpathSync(resolved);
-      const isSafe = SAFE_DIRECTORIES.some(dir => isPathWithin(realTarget, dir));
-      if (!isSafe) {
-        throw new Error(`Path must be within: ${SAFE_DIRECTORIES.join(', ')}`);
+  const reject = () => { throw new Error(`Path must be within: ${SAFE_DIRECTORIES.join(', ')}`); };
+  for (const spelling of new Set([filePath, path.resolve(filePath)])) {
+    const root = path.parse(spelling).root;
+    let resolved = path.resolve(root || '.');
+    for (const component of spelling.slice(root.length).split(process.platform === 'win32' ? /[\\/]+/ : /\/+/)) {
+      if (!component || component === '.') continue;
+      if (component === '..') {
+        resolved = path.dirname(resolved);
+        continue;
+      }
+      resolved = path.join(resolved, component);
+      try {
+        fs.lstatSync(resolved);
+      } catch (err: any) {
+        if (err?.code === 'ENOENT' && SAFE_DIRECTORIES.some(dir => isPathWithin(resolved, dir))) continue;
+        reject();
+      }
+      try {
+        resolved = fs.realpathSync.native(resolved);
+      } catch {
+        reject();
       }
-      return; // symlink target verified, no need to check parent
     }
-  } catch (e: any) {
-    // ENOENT = file doesn't exist yet, fall through to parent-dir check
-    if (e.code !== 'ENOENT') throw e;
-  }
-
-  // For new files (no existing symlink), verify the parent directory.
-  // The file itself may not exist yet (e.g., screenshot output).
-  // This also handles macOS /tmp → /private/tmp transparently.
-  let dir = path.dirname(resolved);
-  let realDir: string;
-  try {
-    realDir = fs.realpathSync(dir);
-  } catch {
-    try {
-      realDir = fs.realpathSync(path.dirname(dir));
-    } catch {
-      throw new Error(`Path must be within: ${SAFE_DIRECTORIES.join(', ')}`);
-    }
-  }
-
-  const realResolved = path.join(realDir, path.basename(resolved));
-  const isSafe = SAFE_DIRECTORIES.some(dir => isPathWithin(realResolved, dir));
-  if (!isSafe) {
-    throw new Error(`Path must be within: ${SAFE_DIRECTORIES.join(', ')}`);
+    if (!SAFE_DIRECTORIES.some(dir => isPathWithin(resolved, dir))) reject();
   }
 }
 

browse/src/server.ts

@@ -46,6 +46,7 @@ import {
 } from './port-allocator';
 import { acquireAgentStateLock, readAgentRecord, clearAgentRecord, isOurAgent, isAgentRecordLive, isAgentRecordGone, stopAgentByRecord, spawnTerminalAgent } from './terminal-agent-control';
 import { isProcessAlive } from './error-handling';
+import { allowedExtensionOrigin } from './extension-id';
 import { sanitizeBody, stripLoneSurrogates } from './sanitize';
 import { startSocksBridge, testUpstream, type BridgeHandle } from './socks-bridge';
 import { parseProxyConfig, toUpstreamConfig, ProxyConfigError } from './proxy-config';
@@ -296,15 +297,11 @@ const TUNNEL_PATHS = new Set<string>([
 ]);
 
 /**
- * The gstack sidebar extension's pinned Chrome extension ID. Derived from
- * the "key" field in extension/manifest.json (first 16 bytes of SHA-256 of
- * the DER public key, hex nibbles mapped 0-9a-f → a-p). Reproduce with:
- *   bun browse/scripts/extension-id.ts
- * POST /extension-token releases AUTH_TOKEN only to an Origin of exactly
- * `chrome-extension://<this id>`. If the manifest keypair is ever rotated,
- * this constant must be updated in the same commit.
+ * POST /extension-token releases AUTH_TOKEN only to an Origin of exactly the
+ * pinned extension, or the one set with `gstack-config set browse_extension_id`
+ * (browse/src/extension-id.ts, shared with the terminal agent's /ws gate).
  */
-export const GSTACK_EXTENSION_ID = 'dgbkdbjebeiblbajiilljmhjdpmiglep';
+export { GSTACK_EXTENSION_ID } from './extension-id';
 
 /**
  * The extension-origin auth check (POST /extension-token): Origin is exactly
@@ -320,7 +317,7 @@ function isPinnedExtensionRequest(req: Request): boolean {
   } catch (err) {
     if (!(err instanceof TypeError)) throw err;  // TypeError = malformed Host
   }
-  const originOk = req.headers.get('origin') === `chrome-extension://${GSTACK_EXTENSION_ID}`;
+  const originOk = req.headers.get('origin') === allowedExtensionOrigin();
   const hostOk = hostname === '127.0.0.1' || hostname === 'localhost';
   return originOk && hostOk;
 }
@@ -1165,7 +1162,7 @@ async function handleCommandInternalImpl(
         result = await handleReadCommand(command, args, session, browserManager);
       }
     } else if (WRITE_COMMANDS.has(command)) {
-      result = await handleWriteCommand(command, args, session, browserManager);
+      result = await browserManager.failIfNavigationBlocked(session.getPage(), handleWriteCommand(command, args, session, browserManager));
     } else if (META_COMMANDS.has(command)) {
       // Pass chain depth + executeCommand callback so chain routes subcommands
       // through the full security pipeline (scope, domain, tab, wrapping).

browse/src/session-persist.ts

@@ -24,6 +24,7 @@ import * as fs from 'fs';
 import type { BrowserManager, BrowserState } from './browser-manager';
 import { writeSecureFile } from './file-permissions';
 import { safeUnlinkQuiet } from './error-handling';
+import { classifyAddress } from './url-validation';
 
 /** Rename a corrupt state file to .corrupt (forensic artifact) — best effort. */
 function quarantineCorrupt(filePath: string): void {
@@ -68,9 +69,10 @@ export function serializeSessionState(state: BrowserState): string {
 /**
  * True when a cookie domain points at an internal-network target a tampered
  * state file could use to reach localhost services, *.internal hosts, or
- * cloud metadata: `localhost`, `*.internal`, IPv4 loopback literals
- * (127.0.0.0/8), IPv6 loopback (`::1`, `[::1]`), and link-local/metadata
- * (169.254.0.0/16, which covers 169.254.169.254). Leading-dot domain
+ * cloud metadata: `localhost`, `*.internal`, and any address literal that
+ * url-validation's classifyAddress calls loopback or blocked (127.0.0.0/8,
+ * ::1, 169.254.0.0/16, 100.100.100.200, fe80::/10, fc00::/7, and their
+ * mapped and numeric spellings). Leading-dot domain
  * variants (`.127.0.0.1`) are normalized before matching. Single source of
  * truth for the persistence restore path here AND `state load`
  * (meta-commands.ts).
@@ -78,10 +80,8 @@ export function serializeSessionState(state: BrowserState): string {
 export function isInternalCookieDomain(domain: string): boolean {
   const d = domain.startsWith('.') ? domain.slice(1) : domain;
   if (d === 'localhost' || d.endsWith('.internal')) return true;
-  if (d === '::1' || d === '[::1]') return true; // IPv6 loopback
-  if (/^127\./.test(d)) return true; // IPv4 loopback block
-  if (/^169\.254\./.test(d)) return true; // link-local incl. cloud metadata
-  return false;
+  const kind = classifyAddress(d);
+  return kind === 'blocked' || kind === 'loopback';
 }
 
 /**

browse/src/terminal-agent-control.ts

@@ -138,6 +138,13 @@ export function acquireAgentStateLock(stateDir: string, waitMs = 5000, publicati
  * exposes it relative to process.execPath. Either path must work or
  * the agent can't be spawned at all.
  */
+/**
+ * Flags for every `bun run` child the daemon spawns. The child runs in the
+ * user's project, and Bun would otherwise load that project's .env (which can
+ * set GSTACK_CHROMIUM_NO_SANDBOX) and bunfig.toml (whose preload runs code).
+ */
+export const BUN_CHILD_FLAGS = ['--no-env-file', `--config=${process.platform === 'win32' ? 'NUL' : '/dev/null'}`];
+
 export function resolveTerminalAgentScript(searchHints: { metaDir?: string; execPath?: string } = {}): string | null {
   const meta = searchHints.metaDir || __dirname;
   const exec = searchHints.execPath || process.execPath;
@@ -197,7 +204,7 @@ export function spawnTerminalAgent(opts: {
     writeAgentRecord(stateDir, reservation);
     let proc: any;
     try {
-      proc = (Bun as any).spawn(['bun', 'run', script, `--agent-gen=${gen}`], {
+      proc = (Bun as any).spawn(['bun', 'run', ...BUN_CHILD_FLAGS, script, `--agent-gen=${gen}`], {
         cwd: opts.cwd || process.cwd(),
         env: {
           ...process.env,

browse/src/terminal-agent.ts

@@ -29,6 +29,7 @@ import { safeUnlink } from './error-handling';
 import { writeAgentRecord, readAgentRecord, clearAgentRecord, readAgentStartTime, acquireAgentStateLock } from './terminal-agent-control';
 import { findAvailablePort } from './port-allocator';
 import { extractPtyCookie } from './pty-session-cookie';
+import { allowedExtensionOrigin } from './extension-id';
 import {
   createPtyLifecycle, disposePtyProcess, ptyCompletionReason,
   type PtyCompletion, type PtyLifecycle,
@@ -43,7 +44,6 @@ const OWNER_WATCHDOG_MS = parseInt(
   process.env.GSTACK_TERMINAL_OWNER_WATCHDOG_MS || '15000',
   10,
 );
-const EXTENSION_ID = process.env.BROWSE_EXTENSION_ID || ''; // optional: tighten Origin check
 const INTERNAL_TOKEN = crypto.randomBytes(32).toString('base64url'); // shared with parent server via env at spawn
 /**
  * Per-boot generation identifier. Loopback /internal/* callers include
@@ -620,8 +620,8 @@ function buildServer(port: number) {
       }
 
       // /ws — WebSocket upgrade. CRITICAL gates:
-      //   (1) Origin must be chrome-extension://<id>. Cross-site WS hijacking
-      //       defense — required, not optional.
+      //   (1) Origin must be exactly the pinned (or gstack-config configured)
+      //       extension. Any other origin, other extensions included, is 403.
       //   (2) Token must be in validTokens. We accept the token via two
       //       transports for compatibility:
       //         - Sec-WebSocket-Protocol (preferred for browsers — the only
@@ -634,12 +634,7 @@ function buildServer(port: number) {
       //       validTokens Set, populated by the parent server's
       //       authenticated /pty-session → /internal/grant chain.
       if (url.pathname === '/ws') {
-        const origin = req.headers.get('origin') || '';
-        const isExtensionOrigin = origin.startsWith('chrome-extension://');
-        if (!isExtensionOrigin) {
-          return new Response('forbidden origin', { status: 403 });
-        }
-        if (EXTENSION_ID && origin !== `chrome-extension://${EXTENSION_ID}`) {
+        if (req.headers.get('origin') !== allowedExtensionOrigin()) {
           return new Response('forbidden origin', { status: 403 });
         }
 

browse/src/url-validation.ts

@@ -8,107 +8,109 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import { validateReadPath } from './path-security';
 
-export const BLOCKED_METADATA_HOSTS = new Set([
-  '169.254.169.254',  // AWS/GCP/Azure instance metadata
-  'fe80::1',          // IPv6 link-local — common metadata endpoint alias
-  '::ffff:169.254.169.254', // IPv4-mapped IPv6 form of the metadata IP
-  '::ffff:a9fe:a9fe', // Hex-encoded IPv4-mapped form (URL constructor normalizes to this)
-  '::a9fe:a9fe',      // Deprecated IPv4-compatible hex form
+/** Metadata services reached by name rather than address. */
+const BLOCKED_METADATA_HOSTNAMES = new Set([
   'metadata.google.internal', // GCP metadata
   'metadata.azure.internal',  // Azure IMDS
 ]);
 
 /**
- * IPv6 prefixes to block (CIDR-style). ULA addresses cover fc00::/7 and
- * link-local addresses cover fe80::/10.
- */
-const BLOCKED_IPV6_PREFIXES = ['fc', 'fd', 'fe8', 'fe9', 'fea', 'feb'];
-
-/**
- * Check if an IPv6 address falls within a blocked prefix range.
- * Handles the full ULA range (fc00::/7) and link-local range (fe80::/10),
- * not just exact literals like fd00:: or fe80::1.
- * Only matches actual IPv6 addresses (must contain ':'), not hostnames
- * like fd.example.com or fcustomer.com.
- */
-function isBlockedIpv6(addr: string): boolean {
-  const normalized = addr.toLowerCase().replace(/^\[|\]$/g, '');
-  // Must contain a colon to be an IPv6 address — avoids false positives on
-  // hostnames like fd.example.com or fcustomer.com
-  if (!normalized.includes(':')) return false;
-  return BLOCKED_IPV6_PREFIXES.some(prefix => normalized.startsWith(prefix));
-}
-
-/**
- * Normalize hostname for blocklist comparison:
- * - Strip trailing dot (DNS fully-qualified notation)
- * - Strip IPv6 brackets (URL.hostname includes [] for IPv6)
- * - Resolve hex (0xA9FEA9FE) and decimal (2852039166) IP representations
- */
-function normalizeHostname(hostname: string): string {
-  // Strip IPv6 brackets
-  let h = hostname.startsWith('[') && hostname.endsWith(']')
-    ? hostname.slice(1, -1)
-    : hostname;
-  // Strip trailing dot
-  if (h.endsWith('.')) h = h.slice(0, -1);
-  return h;
-}
-
-/**
- * Check if a hostname resolves to the link-local metadata IP 169.254.169.254.
- * Catches hex (0xA9FEA9FE), decimal (2852039166), and octal (0251.0376.0251.0376) forms.
- */
-function isMetadataIp(hostname: string): boolean {
-  // Try to parse as a numeric IP via URL constructor — it normalizes all forms
-  try {
-    const probe = new URL(`http://${hostname}`);
-    const normalized = probe.hostname;
-    if (BLOCKED_METADATA_HOSTS.has(normalized) || isBlockedIpv6(normalized)) return true;
-    // Also check after stripping trailing dot
-    if (normalized.endsWith('.') && BLOCKED_METADATA_HOSTS.has(normalized.slice(0, -1))) return true;
-  } catch {
-    // Not a valid hostname — can't be a metadata IP
-  }
-  return false;
-}
-
-/**
- * Resolve a hostname to its IP addresses and check if any resolve to blocked metadata IPs.
- * Mitigates DNS rebinding: even if the hostname looks safe, the resolved IP might not be.
+ * Classify one host literal (URL hostname, cookie domain, or a resolved A/AAAA
+ * answer). Returns null when the host is not an IP literal. Single source of
+ * truth for navigation (literal, DNS answers, redirects, page-driven
+ * navigations) and for session-persist's cookie-domain guard.
  *
- * Checks both A (IPv4) and AAAA (IPv6) records — an attacker can use AAAA-only DNS to
- * bypass IPv4-only checks. Each record family is tried independently; failure of one
- * (e.g. no AAAA records exist) is not treated as a rebinding risk.
+ * - 'blocked': IPv4 link-local 169.254.0.0/16 (cloud metadata and container
+ *   credential services such as 169.254.170.2), Alibaba's 100.100.100.200,
+ *   IPv6 link-local fe80::/10 and ULA fc00::/7, and any of these embedded in
+ *   IPv4-mapped (::ffff:), IPv4-compatible (::) or NAT64 (64:ff9b::) IPv6.
+ * - 'loopback': 127.0.0.0/8 and ::1.
+ * - 'other': every other address (RFC 1918 dev servers stay allowed).
+ *
+ * The URL parser canonicalizes decimal, octal and hex IPv4 forms
+ * (2852039166, 0251.0376.0251.0376, 0xA9FEA9FE) and IPv6 spellings first.
+ */
+export function classifyAddress(host: string): 'blocked' | 'loopback' | 'other' | null {
+  let h = host.trim().toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+  if (!h) return null;
+  if (h.includes(':')) {
+    try { h = new URL(`http://[${h}]/`).hostname.slice(1, -1); } catch { return null; }
+    const groups = expandIpv6(h);
+    if (!groups) return null;
+    const head = groups.slice(0, 6).map(g => g.toString(16)).join(':');
+    if (head === '0:0:0:0:0:ffff' || head === '64:ff9b:0:0:0:0' || (head === '0:0:0:0:0:0' && groups[6] !== 0)) {
+      return classifyIpv4([groups[6] >> 8, groups[6] & 255, groups[7] >> 8, groups[7] & 255]);
+    }
+    if (groups.every((g, i) => g === (i === 7 ? 1 : 0))) return 'loopback';
+    if ((groups[0] & 0xfe00) === 0xfc00 || (groups[0] & 0xffc0) === 0xfe80) return 'blocked';
+    return 'other';
+  }
+  try { h = new URL(`http://${h}/`).hostname; } catch { return null; }
+  const m = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(h);
+  return m ? classifyIpv4(m.slice(1).map(Number)) : null;
+}
+
+function classifyIpv4([a, b, c, d]: number[]): 'blocked' | 'loopback' | 'other' {
+  if (a === 169 && b === 254) return 'blocked';
+  if (a === 100 && b === 100 && c === 100 && d === 200) return 'blocked';
+  return a === 127 ? 'loopback' : 'other';
+}
+
+/** Expand a canonical IPv6 literal to eight 16-bit groups. */
+function expandIpv6(addr: string): number[] | null {
+  const halves = addr.split('::');
+  if (halves.length > 2) return null;
+  const parse = (part: string) => (part ? part.split(':') : []).map(g => parseInt(g, 16));
+  const head = parse(halves[0]);
+  const tail = halves.length === 2 ? parse(halves[1]) : [];
+  const fill = 8 - head.length - tail.length;
+  if (fill < 0 || (halves.length === 1 && fill !== 0)) return null;
+  const groups = [...head, ...Array(fill).fill(0), ...tail];
+  return groups.every(g => Number.isInteger(g) && g >= 0 && g <= 0xffff) ? groups : null;
+}
+
+/**
+ * Resolve a hostname and report whether any A or AAAA answer is blocked.
+ * Each family is tried independently; a missing family is not a risk. DNS
+ * infrastructure failure fails open. Connection-time rebinding (a different
+ * answer when Chromium connects) is out of scope.
  */
 async function resolvesToBlockedIp(hostname: string): Promise<boolean> {
   try {
-    const dns = await import('node:dns');
-    const { resolve4, resolve6 } = dns.promises;
-
-    // Check IPv4 A records
-    const v4Check = resolve4(hostname).then(
-      (addresses) => addresses.some(addr => BLOCKED_METADATA_HOSTS.has(addr)),
-      () => false, // ENODATA / ENOTFOUND — no A records, not a risk
+    const { resolve4, resolve6 } = (await import('node:dns')).promises;
+    const check = (lookup: Promise<string[]>) => lookup.then(
+      (addresses) => addresses.some(addr => classifyAddress(addr) === 'blocked'),
+      () => false,
     );
-
-    // Check IPv6 AAAA records — the gap that issue #668 identified
-    const v6Check = resolve6(hostname).then(
-      (addresses) => addresses.some(addr => {
-        const normalized = addr.toLowerCase();
-        return BLOCKED_METADATA_HOSTS.has(normalized) || isBlockedIpv6(normalized);
-      }),
-      () => false, // ENODATA / ENOTFOUND — no AAAA records, not a risk
-    );
-
-    const [v4Blocked, v6Blocked] = await Promise.all([v4Check, v6Check]);
-    return v4Blocked || v6Blocked;
+    const [v4, v6] = await Promise.all([check(resolve4(hostname)), check(resolve6(hostname))]);
+    return v4 || v6;
   } catch {
-    // Unexpected error — fail open (don't block navigation on DNS infrastructure failure)
     return false;
   }
 }
 
+/**
+ * Why an http(s) navigation target is refused, or null when it is allowed.
+ * Applied to explicit navigations (validateNavigationUrl) and to every
+ * navigation request the browser makes, including redirect hops and
+ * page-driven navigations (BrowserManager's navigation guard).
+ */
+export async function blockedNavigationReason(url: string): Promise<string | null> {
+  let parsed: URL;
+  try { parsed = new URL(url); } catch { return null; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;
+  const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+  const kind = classifyAddress(hostname);
+  if (kind === 'blocked' || BLOCKED_METADATA_HOSTNAMES.has(hostname)) {
+    return `Blocked: ${parsed.hostname} is a cloud metadata or link-local address. Access is denied for security.`;
+  }
+  if (kind !== null || hostname === 'localhost') return null;
+  if (await resolvesToBlockedIp(hostname)) {
+    return `Blocked: ${parsed.hostname} resolves to a cloud metadata or link-local address. Possible DNS rebinding attack.`;
+  }
+  return null;
+}
+
 /**
  * Normalize non-standard file:// URLs into absolute form before the WHATWG URL parser
  * sees them. Handles cwd-relative, home-relative, and bare-segment shapes that the
@@ -290,24 +292,8 @@ export async function validateNavigationUrl(url: string): Promise<string> {
     );
   }
 
-  const hostname = normalizeHostname(parsed.hostname.toLowerCase());
-
-  if (BLOCKED_METADATA_HOSTS.has(hostname) || isMetadataIp(hostname) || isBlockedIpv6(hostname)) {
-    throw new Error(
-      `Blocked: ${parsed.hostname} is a cloud metadata endpoint. Access is denied for security.`
-    );
-  }
-
-  // DNS rebinding protection: resolve hostname and check if it points to metadata IPs.
-  // Skip for loopback/private IPs — they can't be DNS-rebinded and the async DNS
-  // resolution adds latency that breaks concurrent E2E tests under load.
-  const isLoopback = hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
-  const isPrivateNet = /^(10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.)/.test(hostname);
-  if (!isLoopback && !isPrivateNet && await resolvesToBlockedIp(hostname)) {
-    throw new Error(
-      `Blocked: ${parsed.hostname} resolves to a cloud metadata IP. Possible DNS rebinding attack.`
-    );
-  }
+  const blocked = await blockedNavigationReason(parsed.href);
+  if (blocked) throw new Error(blocked);
 
   return url;
 }

browse/src/write-commands.ts

@@ -420,10 +420,32 @@ export async function handleWriteCommand(
     }
 
     case 'type': {
-      const text = args.join(' ');
-      if (!text) throw new Error('Usage: browse type <text>');
+      // #2936: bare `type` sends keystrokes to whatever has focus, so a selector
+      // given as the first word was typed as text. --selector targets an
+      // element; `--` ends flags so literal text may start with "--".
+      const usage = 'Usage: browse type [--selector <sel>] [--] <text>';
+      let rest = args;
+      let selector: string | undefined;
+      if (rest[0] === '--selector') {
+        selector = rest[1];
+        if (!selector) throw new Error(usage);
+        rest = rest.slice(2);
+      }
+      if (rest[0] === '--') rest = rest.slice(1);
+      const text = rest.join(' ');
+      if (!text) throw new Error(usage);
+      if (selector) {
+        const resolved = await session.resolveRef(selector);
+        const locator = 'locator' in resolved ? resolved.locator : target.locator(resolved.selector);
+        await locator.pressSequentially(text, { timeout: 5000 });
+        return `Typed ${text.length} characters into ${selector}`;
+      }
       await page.keyboard.type(text);
-      return `Typed ${text.length} characters`;
+      const first = rest[0];
+      const selectorLike = /^([#.][A-Za-z_-]|\[[^\]]+\]$|[A-Za-z][\w-]*[#.[][A-Za-z_-])/.test(first) || rest.includes('>');
+      return selectorLike
+        ? `Typed ${text.length} characters into the focused element\nhint: "${first}" looks like a CSS selector. To type into that element: browse type --selector '${first}' <text>`
+        : `Typed ${text.length} characters`;
     }
 
     case 'press': {
@@ -974,13 +996,18 @@ export async function handleWriteCommand(
         } else if (args[i] === '--cleanup') {
           doCleanup = true;
         } else if (args[i] === '--hide' && i + 1 < args.length) {
-          // Collect all following non-flag args as selectors to hide
+          // Collect all following non-flag args as selectors to hide. A
+          // trailing image path is the output path, not a selector (#1419).
+          const values: string[] = [];
           i++;
           while (i < args.length && !args[i].startsWith('--')) {
-            hideSelectors.push(args[i]);
+            values.push(args[i]);
             i++;
           }
           i--; // Back up since the for loop will increment
+          const last = values[values.length - 1];
+          if (!outputPath && values.length > 1 && /^(\/|\.\.?\/|~)|\.(png|jpe?g|webp)$/i.test(last)) outputPath = values.pop();
+          hideSelectors.push(...values);
         } else if (args[i] === '--width' && i + 1 < args.length) {
           viewportWidth = parseInt(args[++i], 10);
           if (isNaN(viewportWidth)) throw new Error('--width must be a number');
@@ -1282,12 +1309,17 @@ export async function handleWriteCommand(
       const selectorIdx = args.indexOf('--selector');
       const selector = selectorIdx >= 0 ? args[selectorIdx + 1] : undefined;
       const dirIdx = args.indexOf('--dir');
-      const dir = dirIdx >= 0 ? args[dirIdx + 1] : path.join(TEMP_DIR, `browse-scrape-${Date.now()}`);
+      const requestedDir = dirIdx >= 0 ? args[dirIdx + 1] : path.join(TEMP_DIR, `browse-scrape-${Date.now()}`);
       const limitIdx = args.indexOf('--limit');
       const limit = Math.min(limitIdx >= 0 ? parseInt(args[limitIdx + 1], 10) || 50 : 50, 200);
 
-      validateOutputPath(dir);
+      validateOutputPath(requestedDir);
+      const dir = path.resolve(requestedDir);
       fs.mkdirSync(dir, { recursive: true });
+      // Each file is validated too: a symlink planted in an existing --dir
+      // would otherwise redirect the write outside the safe directories.
+      const manifestPath = path.join(dir, 'manifest.json');
+      validateOutputPath(manifestPath);
 
       const { extractMedia } = await import('./media-extract');
       const target = bm.getActiveFrameOrPage();
@@ -1346,6 +1378,7 @@ export async function handleWriteCommand(
           const ext = mimeToExt(ct.split(';')[0].trim());
           const filename = `${type}-${String(i + 1).padStart(3, '0')}${ext}`;
           const filePath = path.join(dir, filename);
+          validateOutputPath(filePath);
           const body = Buffer.from(await response.body());
           try {
             fs.writeFileSync(filePath, body);
@@ -1366,7 +1399,7 @@ export async function handleWriteCommand(
       }
 
       // Write manifest
-      fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+      fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
 
       return `Scraped ${toDownload.length} items to ${dir}/\n${lines.join('\n')}\n\nSummary: ${manifest.succeeded} succeeded, ${manifest.failed} failed, ${Math.round(manifest.total_size / 1024)}KB total`;
     }

browse/src/xvfb.ts

@@ -179,19 +179,43 @@ export function isOurXvfb(pid: number, recordedStartTime: string): boolean {
  * Throws if Xvfb isn't installed (caller should print a platform-specific
  * install hint).
  */
+export class XvfbDisplayTakenError extends Error {}
+
 export async function spawnXvfb(displayNum: number): Promise<XvfbHandle> {
   const display = `:${displayNum}`;
-  if (!isDisplayFree(displayNum)) throw new Error(`X display ${display} is already reserved; refusing to replace it`);
+  if (!isDisplayFree(displayNum)) throw new XvfbDisplayTakenError(`X display ${display} is already reserved; refusing to replace it`);
   if (!readPidStartTime(process.pid)) throw new Error('Cannot start Xvfb without process start-time ownership checks');
 
   // Spawn detached: Xvfb's lifetime is tied to whether we've explicitly
   // killed it via the handle's close() method, not to the parent process.
-  const proc = Bun.spawn(['Xvfb', display, '-screen', '0', '1920x1080x24', '-ac'], {
-    windowsHide: true,
-    stdio: ['ignore', 'ignore', 'ignore'],
-  });
+  // Startup stderr goes to a private file: a holder that takes the display and
+  // exits before we look leaves no lock behind, only Xvfb's own message.
+  const stderrDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-xvfb-'));
+  const stderrPath = path.join(stderrDir, 'stderr.log');
+  const stderrFd = fs.openSync(stderrPath, 'w', 0o600);
+  let proc: ReturnType<typeof Bun.spawn>;
+  try {
+    proc = Bun.spawn(['Xvfb', display, '-screen', '0', '1920x1080x24', '-ac'], {
+      windowsHide: true,
+      stdio: ['ignore', 'ignore', stderrFd],
+    });
+  } catch (err) {
+    fs.rmSync(stderrDir, { recursive: true, force: true });
+    throw err;
+  } finally {
+    fs.closeSync(stderrFd);
+  }
   proc.unref();
   const startTime = readPidStartTime(proc.pid);
+  try {
+    return await awaitXvfbReady(proc, displayNum, startTime, stderrPath);
+  } finally {
+    fs.rmSync(stderrDir, { recursive: true, force: true });
+  }
+}
+
+async function awaitXvfbReady(proc: ReturnType<typeof Bun.spawn>, displayNum: number, startTime: string, stderrPath: string): Promise<XvfbHandle> {
+  const display = `:${displayNum}`;
 
   // Wait for the X server to become reachable — Xvfb takes a few hundred ms
   // to bind. Probe via xdpyinfo with retries.
@@ -201,7 +225,13 @@ export async function spawnXvfb(displayNum: number): Promise<XvfbHandle> {
     await Bun.sleep(100);
     // If Xvfb crashed during startup, fail fast.
     if (proc.exitCode != null) {
-      throw new Error(`Xvfb on ${display} exited during startup (code ${proc.exitCode}). Hint: install xvfb (apt-get install xvfb / yum install xorg-x11-server-Xvfb).`);
+      let stderr = '';
+      try { stderr = fs.readFileSync(stderrPath, 'utf8'); } catch {}
+      if (!isDisplayFree(displayNum) || /Server is already active for display/.test(stderr)) {
+        throw new XvfbDisplayTakenError(`X display ${display} was reserved by another X server during startup`);
+      }
+      const fatal = stderr.split('\n').map(line => line.replace(/^\(EE\)\s*/, '').trim()).filter(Boolean).slice(-3).join(' ');
+      throw new Error(`Xvfb on ${display} exited during startup (code ${proc.exitCode})${fatal ? `: ${fatal}` : ''}. Hint: install xvfb (apt-get install xvfb / yum install xorg-x11-server-Xvfb).`);
     }
     let ownsLock = false;
     try { ownsLock = Number(fs.readFileSync(`/tmp/.X${displayNum}-lock`, 'utf8').trim()) === proc.pid; } catch {}
@@ -228,20 +258,45 @@ export async function spawnXvfb(displayNum: number): Promise<XvfbHandle> {
   };
 }
 
+/**
+ * Pick-then-spawn races with any other allocator (a second daemon, a parallel
+ * test shard): both can see the same display free before either Xvfb takes its
+ * lock. The loser moves on to the next free display instead of failing.
+ */
+export async function spawnFreeXvfb(
+  rangeStart: number = DISPLAY_RANGE_START,
+  rangeEnd: number = DISPLAY_RANGE_END,
+): Promise<XvfbHandle> {
+  for (let n = pickFreeDisplay(rangeStart, rangeEnd); n != null; n = pickFreeDisplay(n + 1, rangeEnd)) {
+    try { return await spawnXvfb(n); }
+    catch (err) { if (!(err instanceof XvfbDisplayTakenError)) throw err; }
+  }
+  throw new Error(`no free X display in range :${rangeStart}-:${rangeEnd} — refusing to clobber existing X servers`);
+}
+
 /**
  * Cleanup an Xvfb child if it's still ours. Validates ownership first; if
  * the PID has been recycled or the cmdline doesn't match, leave it alone.
  *
  * Best-effort: never throws.
  */
+function isZombie(pid: number): boolean {
+  try {
+    const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+    return stat.slice(stat.lastIndexOf(')') + 2).startsWith('Z');
+  } catch { return false; }
+}
+
 export function cleanupXvfb(state: { pid: number; startTime: string; display: string }): void {
   if (!state.pid) return;
   if (!isOurXvfb(state.pid, state.startTime)) return;
   try { safeKill(state.pid, 'SIGTERM'); } catch { /* swallow */ }
   // Wait briefly for Xvfb to exit, then SIGKILL if still alive.
+  // An exited child stays a zombie until our event loop reaps it, and this
+  // synchronous wait blocks that loop, so a zombie counts as exited here.
   const deadline = Date.now() + 1000;
   while (Date.now() < deadline) {
-    if (!isProcessAlive(state.pid)) break;
+    if (!isProcessAlive(state.pid) || isZombie(state.pid)) break;
     Bun.sleepSync(10);
   }
   if (isOurXvfb(state.pid, state.startTime)) {

browse/test/build.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect } from 'bun:test';
 import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 
 const DIST_DIR = path.resolve(__dirname, '..', 'dist');
 const SERVER_NODE = path.join(DIST_DIR, 'server-node.mjs');
@@ -26,3 +27,22 @@ describe('build: server-node.mjs', () => {
     expect(bundle).not.toMatch(/ngrok_napi|ngrokNapi|@ngrok\/ngrok-darwin|@ngrok\/ngrok-linux|@ngrok\/ngrok-win32/);
   });
 });
+
+describe('build: node server bundle externals (#2260)', () => {
+  test('sharp and socks stay external, so their native and runtime-resolved code is loaded from node_modules', () => {
+    const script = fs.readFileSync(path.resolve(__dirname, '..', 'scripts', 'build-node-server.sh'), 'utf-8');
+    const externals = [...script.matchAll(/--external\s+"?([^"\s\\]+)"?/g)].map((m) => m[1]);
+    expect(externals).toEqual(expect.arrayContaining(['sharp', 'socks']));
+    const out = fs.mkdtempSync(path.join(os.tmpdir(), 'browse-node-bundle-'));
+    try {
+      const outfile = path.join(out, 'server-node.mjs');
+      const r = Bun.spawnSync([process.execPath, 'build', path.resolve(__dirname, '..', 'src', 'server.ts'), '--target=node', '--outfile', outfile, ...externals.flatMap((e) => ['--external', e])], { stdout: 'pipe', stderr: 'pipe', timeout: 120_000 });
+      expect(r.exitCode, r.stderr.toString()).toBe(0);
+      const bundle = fs.readFileSync(outfile, 'utf-8');
+      expect(bundle).not.toContain('node_modules/sharp/');
+      expect(bundle).not.toContain('node_modules/socks/');
+    } finally {
+      fs.rmSync(out, { recursive: true, force: true });
+    }
+  }, 150_000);
+});

browse/test/chromium-profile-isolation.test.ts

@@ -52,7 +52,9 @@ describe('Chromium profile isolation cleanup (#2908)', () => {
 describe.skipIf(process.platform === 'win32')('Chromium profile isolation (#2817)', () => {
   let scratch: string;
   let profile: string;
+  let projectProfile: string;
   let stateFile: string;
+  let orphans: number[];
   let env: Record<string, string>;
   let children: ReturnType<typeof Bun.spawn>[];
   let daemonPid: number | undefined;
@@ -61,6 +63,7 @@ describe.skipIf(process.platform === 'win32')('Chromium profile isolation (#2817
     scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'browse-profile-isolation-'));
     profile = path.join(scratch, '.gstack', 'chromium-profile');
     stateFile = path.join(scratch, 'project-b', '.gstack', 'browse.json');
+    projectProfile = path.join(scratch, 'project-b', '.gstack', 'chromium-profile');
     fs.mkdirSync(profile, { recursive: true });
     fs.mkdirSync(path.dirname(stateFile), { recursive: true });
     env = {};
@@ -83,6 +86,7 @@ describe.skipIf(process.platform === 'win32')('Chromium profile isolation (#2817
       BROWSE_START_TIMEOUT: '30000',
     });
     children = [];
+    orphans = [];
     daemonPid = undefined;
   });
 
@@ -92,14 +96,16 @@ describe.skipIf(process.platform === 'win32')('Chromium profile isolation (#2817
     }
     if (daemonPid) killDaemonGroup(daemonPid);
     for (const child of children) child.kill('SIGKILL');
+    for (const pid of orphans) { try { process.kill(pid, 'SIGKILL'); } catch {} }
     await Promise.all(children.map(child => child.exited));
     fs.rmSync(scratch, { recursive: true, force: true });
   });
 
-  async function spawnChromiumHolder() {
+  /** A stand-in Chromium: its command line names Chromium and the profile it uses. */
+  async function spawnChromiumHolder(userDataDir = profile) {
     const script = path.join(scratch, `chromium-holder-${children.length}.ts`);
     fs.writeFileSync(script, 'console.log("ready"); await Bun.sleep(60000);');
-    const child = Bun.spawn([process.execPath, script], {
+    const child = Bun.spawn([process.execPath, script, `--user-data-dir=${userDataDir}`], {
       env,
       stdin: 'ignore',
       stdout: 'pipe',
@@ -113,17 +119,66 @@ describe.skipIf(process.platform === 'win32')('Chromium profile isolation (#2817
     return child;
   }
 
-  function seedLocks(pid: number) {
-    fs.symlinkSync(`${os.hostname()}-${pid}`, path.join(profile, LOCKS[0]));
-    fs.symlinkSync('socket-target', path.join(profile, LOCKS[1]));
-    fs.symlinkSync('cookie-target', path.join(profile, LOCKS[2]));
+  /** A stand-in Chromium whose daemon is gone: reparented to init. */
+  async function spawnOrphanedChromium(userDataDir: string) {
+    const script = path.join(scratch, `chromium-orphan-${orphans.length}.ts`);
+    const ready = `${script}.ready`;
+    fs.writeFileSync(script, `require('node:fs').writeFileSync(${JSON.stringify(ready)}, 'ready'); await Bun.sleep(60000);`);
+    const launcher = Bun.spawnSync(['sh', '-c', `"$0" "$1" "$2" >/dev/null 2>&1 & echo $!`, process.execPath, script, `--user-data-dir=${userDataDir}`], { env, stdout: 'pipe', timeout: 10_000 });
+    const pid = Number(launcher.stdout.toString().trim());
+    orphans.push(pid);
+    const deadline = Date.now() + 10_000;
+    while (!fs.existsSync(ready) && Date.now() < deadline) await Bun.sleep(20);
+    expect(fs.existsSync(ready)).toBe(true);
+    return { pid };
   }
 
-  function expectLocksIntact(pid: number) {
+  function seedLocks(pid: number, dir = profile, host = os.hostname()) {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.symlinkSync(`${host}-${pid}`, path.join(dir, LOCKS[0]));
+    fs.symlinkSync('socket-target', path.join(dir, LOCKS[1]));
+    fs.symlinkSync('cookie-target', path.join(dir, LOCKS[2]));
+  }
+
+  function expectLocksIntact(pid: number, dir = profile, host = os.hostname()) {
     expect(isProcessAlive(pid)).toBe(true);
-    expect(fs.readlinkSync(path.join(profile, LOCKS[0]))).toBe(`${os.hostname()}-${pid}`);
-    expect(fs.readlinkSync(path.join(profile, LOCKS[1]))).toBe('socket-target');
-    expect(fs.readlinkSync(path.join(profile, LOCKS[2]))).toBe('cookie-target');
+    expect(fs.readlinkSync(path.join(dir, LOCKS[0]))).toBe(`${host}-${pid}`);
+    expect(fs.readlinkSync(path.join(dir, LOCKS[1]))).toBe('socket-target');
+    expect(fs.readlinkSync(path.join(dir, LOCKS[2]))).toBe('cookie-target');
+  }
+
+  function writeStubServer() {
+    const serverScript = path.join(scratch, 'stub-server.ts');
+    fs.writeFileSync(serverScript, `
+      import * as fs from 'node:fs';
+      const server = Bun.serve({
+        hostname: '127.0.0.1', port: 0,
+        fetch: () => Response.json({ status: 'healthy' }),
+      });
+      fs.writeFileSync(process.env.BROWSE_STATE_FILE!, JSON.stringify({
+        pid: process.pid, port: server.port, token: 'test-token',
+        mode: process.env.BROWSE_HEADED === '1' ? 'headed' : 'launched',
+      }));
+    `);
+    env.BROWSE_SERVER_SCRIPT = serverScript;
+  }
+
+  async function runCliRaw(args: string[]) {
+    const child = Bun.spawn([process.execPath, CLI, ...args], {
+      cwd: path.join(scratch, 'project-b'),
+      env,
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+    children.push(child);
+    const [code, stdout, stderr] = await Promise.all([
+      child.exited,
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ]);
+    if (fs.existsSync(stateFile)) daemonPid = JSON.parse(fs.readFileSync(stateFile, 'utf-8')).pid;
+    return { code, stdout, stderr };
   }
 
   async function runCli(args: string[]) {
@@ -176,34 +231,108 @@ describe.skipIf(process.platform === 'win32')('Chromium profile isolation (#2817
   }, 60_000);
 
   for (const mode of ['flag', 'environment'] as const) {
-    test(`headed startup via ${mode} still reaps a profile orphan and removes stale locks`, async () => {
-      const orphan = await spawnChromiumHolder();
-      seedLocks(orphan.pid);
+    test(`headed startup via ${mode} reaps an orphaned Chromium on this project's profile and removes stale locks`, async () => {
+      const orphan = await spawnOrphanedChromium(projectProfile);
+      seedLocks(orphan.pid, projectProfile);
       env.BROWSE_HEADED = mode === 'environment' ? '1' : '0';
-      const serverScript = path.join(scratch, 'stub-server.ts');
-      fs.writeFileSync(serverScript, `
-        import * as fs from 'node:fs';
-        const server = Bun.serve({
-          hostname: '127.0.0.1', port: 0,
-          fetch: () => Response.json({ status: 'healthy' }),
-        });
-        fs.writeFileSync(process.env.BROWSE_STATE_FILE!, JSON.stringify({
-          pid: process.pid, port: server.port, token: 'test-token',
-          mode: process.env.BROWSE_HEADED === '1' ? 'headed' : 'launched',
-        }));
-      `);
-      env.BROWSE_SERVER_SCRIPT = serverScript;
+      writeStubServer();
 
       await runCli(mode === 'flag' ? ['--headed', 'status'] : ['status']);
 
       expect(JSON.parse(fs.readFileSync(stateFile, 'utf-8')).mode).toBe('headed');
       expect(isProcessAlive(orphan.pid)).toBe(false);
-      expect(fs.readdirSync(profile)).not.toContain(LOCKS[0]);
-      expect(fs.readdirSync(profile)).not.toContain(LOCKS[1]);
-      expect(fs.readdirSync(profile)).not.toContain(LOCKS[2]);
+      for (const lock of LOCKS) expect(fs.readdirSync(projectProfile)).not.toContain(lock);
     }, 60_000);
   }
 
+  test('headed startup in one project leaves another project\'s live headed Chromium alone (D5, #2492)', async () => {
+    const otherProject = path.join(scratch, 'project-a', '.gstack', 'chromium-profile');
+    const holder = await spawnChromiumHolder(otherProject);
+    seedLocks(holder.pid, otherProject);
+    writeStubServer();
+
+    await runCli(['--headed', 'status']);
+
+    expectLocksIntact(holder.pid, otherProject);
+    expect(fs.existsSync(projectProfile)).toBe(true);
+  }, 60_000);
+
+  test('a live owner of this project\'s profile is never killed; browse names it and stops', async () => {
+    const holder = await spawnChromiumHolder(projectProfile);
+    seedLocks(holder.pid, projectProfile);
+    writeStubServer();
+
+    const r = await runCliRaw(['--headed', 'status']);
+
+    expect(r.code).not.toBe(0);
+    expect(r.stdout + r.stderr).toContain(`in use by Chromium PID ${holder.pid}`);
+    expectLocksIntact(holder.pid, projectProfile);
+  }, 60_000);
+
+  test('a lock written by another host is never acted on', async () => {
+    const holder = await spawnOrphanedChromium(projectProfile);
+    seedLocks(holder.pid, projectProfile, 'some-other-host');
+    writeStubServer();
+
+    const r = await runCliRaw(['--headed', 'status']);
+
+    expect(r.code).not.toBe(0);
+    expect(r.stdout + r.stderr).toContain('on another host (some-other-host)');
+    expectLocksIntact(holder.pid, projectProfile, 'some-other-host');
+  }, 60_000);
+
+  test('first headed use seeds the project profile from a quiescent shared profile, without singleton files', async () => {
+    fs.mkdirSync(path.join(profile, 'Default'), { recursive: true });
+    fs.writeFileSync(path.join(profile, 'Default', 'Cookies'), 'cookie-db');
+    seedLocks(999_999_999);
+    writeStubServer();
+
+    const r = await runCliRaw(['--headed', 'status']);
+
+    expect(r.code, r.stdout + r.stderr).toBe(0);
+    expect(r.stdout).toContain(`Copied your logins and settings from ${profile} to ${projectProfile}`);
+    expect(fs.readFileSync(path.join(projectProfile, 'Default', 'Cookies'), 'utf-8')).toBe('cookie-db');
+    expect(fs.statSync(projectProfile).mode & 0o777).toBe(0o700);
+    expect(fs.readdirSync(projectProfile).filter(f => f.startsWith('Singleton') || f.includes('.seed-'))).toEqual([]);
+    expect(fs.readdirSync(path.dirname(projectProfile)).filter(f => f.includes('.seed-'))).toEqual([]);
+  }, 60_000);
+
+  test('a shared profile in use is not copied; the project starts fresh and says how to import later', async () => {
+    fs.writeFileSync(path.join(profile, 'Cookies'), 'cookie-db');
+    const holder = await spawnChromiumHolder(profile);
+    seedLocks(holder.pid);
+    writeStubServer();
+
+    const r = await runCliRaw(['--headed', 'status']);
+
+    expect(r.code, r.stdout + r.stderr).toBe(0);
+    expect(r.stdout).toContain('starts with a fresh profile. To import it later');
+    expect(fs.existsSync(path.join(projectProfile, 'Cookies'))).toBe(false);
+    expectLocksIntact(holder.pid);
+  }, 60_000);
+
+  test('browse profiles lists per-project profiles and prune removes idle ones but never one in use', async () => {
+    writeStubServer();
+    await runCli(['--headed', 'status']);
+    const listed = await runCliRaw(['profiles']);
+    expect(listed.code).toBe(0);
+    expect(listed.stdout).toContain(projectProfile);
+    expect(listed.stdout).toContain('(old shared profile)');
+
+    const holder = await spawnChromiumHolder(projectProfile);
+    seedLocks(holder.pid, projectProfile);
+    await runCliRaw(['profiles', 'prune', '--days', '0']);
+    expect(fs.existsSync(projectProfile)).toBe(true);
+
+    holder.kill('SIGKILL');
+    await holder.exited;
+    const pruned = await runCliRaw(['profiles', 'prune', '--days', '0']);
+    expect(pruned.code).toBe(0);
+    expect(pruned.stdout).toContain(`removed ${projectProfile}`);
+    expect(fs.existsSync(projectProfile)).toBe(false);
+    expect(fs.existsSync(profile)).toBe(true);
+  }, 60_000);
+
   for (const args of [['stop'], ['--force-restart', 'stop'], ['disconnect']]) {
     test(`headless ${args.join(' ')} preserves another project's headed profile`, async () => {
       await runCli(['status']);
@@ -228,6 +357,7 @@ describe.skipIf(process.platform === 'win32')('Chromium profile isolation (#2817
     test(`${mode} factory shutdown scopes profile cleanup to the active browser mode`, async () => {
       const holder = await spawnChromiumHolder();
       seedLocks(holder.pid);
+      seedLocks(999_999_999, projectProfile);
       const child = Bun.spawn([process.execPath, '-e', `
         import { buildFetchHandler } from ${JSON.stringify(path.resolve(import.meta.dir, '../src/server.ts'))};
         import { resolveConfig } from ${JSON.stringify(path.resolve(import.meta.dir, '../src/config.ts'))};
@@ -249,11 +379,40 @@ describe.skipIf(process.platform === 'win32')('Chromium profile isolation (#2817
       const [code, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()]);
 
       expect(code, stderr).toBe(0);
+      // Headed shutdown cleans only this project's profile; another
+      // project's (here the old shared one) is never touched (D5).
+      expectLocksIntact(holder.pid);
       if (mode === 'headed') {
-        for (const lock of LOCKS) expect(fs.readdirSync(profile)).not.toContain(lock);
+        for (const lock of LOCKS) expect(fs.readdirSync(projectProfile)).not.toContain(lock);
       } else {
-        expectLocksIntact(holder.pid);
+        expect(fs.readdirSync(projectProfile)).toContain(LOCKS[0]);
       }
     }, 60_000);
   }
 });
+
+describe('explicit CHROMIUM_PROFILE (D5)', () => {
+  test('an explicit profile is neither seeded from the shared profile nor registered for pruning', async () => {
+    const { ensureProjectProfile } = await import('../src/chromium-profiles');
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'browse-explicit-profile-'));
+    const saved = { CHROMIUM_PROFILE: process.env.CHROMIUM_PROFILE, GSTACK_HOME: process.env.GSTACK_HOME };
+    try {
+      process.env.GSTACK_HOME = path.join(root, 'state');
+      fs.mkdirSync(path.join(process.env.GSTACK_HOME, 'chromium-profile'), { recursive: true });
+      fs.writeFileSync(path.join(process.env.GSTACK_HOME, 'chromium-profile', 'Cookies'), 'shared logins');
+      const explicit = path.join(root, 'workspace-profile');
+      process.env.CHROMIUM_PROFILE = explicit;
+      const logs: string[] = [];
+      ensureProjectProfile(explicit, msg => logs.push(msg));
+      expect(fs.existsSync(explicit)).toBe(false);
+      expect(fs.existsSync(path.join(process.env.GSTACK_HOME, 'browse-profiles.json'))).toBe(false);
+      expect(logs).toEqual([]);
+    } finally {
+      for (const [k, v] of Object.entries(saved)) {
+        if (v === undefined) delete process.env[k];
+        else process.env[k] = v;
+      }
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

browse/test/cli-loopback-no-proxy.test.ts

@@ -0,0 +1,77 @@
+/**
+ * G4 (#494): with HTTP_PROXY set, the CLI's loopback calls to its own daemon
+ * went through the proxy, so the daemon never looked healthy. The CLI appends
+ * loopback to NO_PROXY (keeping the user's entries) before its first fetch.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { withLoopbackNoProxy } from '../src/cli';
+
+const CLI = path.resolve(import.meta.dir, '../src/cli.ts');
+
+describe('withLoopbackNoProxy', () => {
+  test('appends loopback names to an existing list without replacing it', () => {
+    expect(withLoopbackNoProxy({ NO_PROXY: 'corp.internal, .example.com' })).toBe('corp.internal,.example.com,127.0.0.1,localhost,::1');
+    expect(withLoopbackNoProxy({ no_proxy: 'corp.internal' })).toBe('corp.internal,127.0.0.1,localhost,::1');
+    expect(withLoopbackNoProxy({})).toBe('127.0.0.1,localhost,::1');
+    expect(withLoopbackNoProxy({ NO_PROXY: 'localhost,127.0.0.1,::1' })).toBe('localhost,127.0.0.1,::1');
+  });
+});
+
+describe('CLI → daemon behind a proxy that fails every request', () => {
+  let scratch: string;
+  let proxy: ReturnType<typeof Bun.serve>;
+  let proxied = 0;
+
+  beforeEach(() => {
+    scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'browse-no-proxy-'));
+    proxied = 0;
+    proxy = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch: () => { proxied++; return new Response('proxy refuses', { status: 502 }); } });
+  });
+
+  afterEach(() => {
+    try { proxy.stop(true); } catch {}
+    const stateFile = path.join(scratch, 'state', 'browse.json');
+    if (fs.existsSync(stateFile)) {
+      try { process.kill(JSON.parse(fs.readFileSync(stateFile, 'utf-8')).pid, 'SIGKILL'); } catch {}
+    }
+    fs.rmSync(scratch, { recursive: true, force: true });
+  });
+
+  test.skipIf(process.platform === 'win32')('status reaches the daemon directly and the daemon keeps the user NO_PROXY entries', async () => {
+    const stateFile = path.join(scratch, 'state', 'browse.json');
+    const stub = path.join(scratch, 'stub-server.ts');
+    fs.writeFileSync(stub, `
+      import * as fs from 'node:fs';
+      const server = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch: () => Response.json({ status: 'healthy' }) });
+      fs.writeFileSync(process.env.BROWSE_STATE_FILE!, JSON.stringify({
+        pid: process.pid, port: server.port, token: 'no-proxy-test', mode: 'launched', noProxy: process.env.NO_PROXY,
+      }));
+      setTimeout(() => server.stop(true), 5000);
+    `);
+    const env: Record<string, string> = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== undefined && !/^(BROWSE_|GSTACK_|NO_PROXY$|no_proxy$|HTTPS?_PROXY$|https?_proxy$|ALL_PROXY$|all_proxy$)/.test(key)) env[key] = value;
+    }
+    Object.assign(env, {
+      HOME: scratch,
+      GSTACK_HOME: path.join(scratch, '.gstack'),
+      BROWSE_STATE_FILE: stateFile,
+      BROWSE_SERVER_SCRIPT: stub,
+      BROWSE_PARENT_PID: '0',
+      BROWSE_START_TIMEOUT: '8000',
+      HTTP_PROXY: `http://127.0.0.1:${proxy.port}`,
+      http_proxy: `http://127.0.0.1:${proxy.port}`,
+      NO_PROXY: 'corp.internal',
+    });
+    const cli = Bun.spawn([process.execPath, CLI, 'status'], { cwd: scratch, env, stdout: 'pipe', stderr: 'pipe' });
+    const timer = setTimeout(() => cli.kill('SIGKILL'), 30_000);
+    const [code, stdout, stderr] = await Promise.all([cli.exited, new Response(cli.stdout).text(), new Response(cli.stderr).text()]);
+    clearTimeout(timer);
+    expect(code, stdout + stderr).toBe(0);
+    expect(proxied).toBe(0);
+    expect(JSON.parse(fs.readFileSync(stateFile, 'utf-8')).noProxy).toBe('corp.internal,127.0.0.1,localhost,::1');
+  }, 45_000);
+});

browse/test/commands.test.ts

@@ -559,6 +559,49 @@ describe('Interaction', () => {
     const val = await handleReadCommand('js', ['document.querySelector("#name").value'], bm);
     expect(val).toBe('John Doe');
   });
+
+  test('type --selector types into that element, not the focused one (#2936)', async () => {
+    await handleWriteCommand('goto', [baseUrl + '/forms.html'], bm);
+    await handleWriteCommand('click', ['#email'], bm);
+    const result = await handleWriteCommand('type', ['--selector', '#name', 'Jane', 'Roe'], bm);
+    expect(result).toBe('Typed 8 characters into #name');
+    expect(await handleReadCommand('js', ['document.querySelector("#name").value'], bm)).toBe('Jane Roe');
+    expect(await handleReadCommand('js', ['document.querySelector("#email").value'], bm)).toBe('');
+  });
+
+  test('bare type keeps typing selector-looking text literally, with a hint and no refusal', async () => {
+    await handleWriteCommand('goto', [baseUrl + '/forms.html'], bm);
+    await handleWriteCommand('click', ['#bio'], bm);
+    const result = await handleWriteCommand('type', ['#name', 'secret-value'], bm);
+    expect(result).toContain('Typed 18 characters into the focused element');
+    expect(result).toContain("hint: \"#name\" looks like a CSS selector. To type into that element: browse type --selector '#name' <text>");
+    expect(result).not.toContain('secret-value');
+    expect(await handleReadCommand('js', ['document.querySelector("#bio").value'], bm)).toBe('#name secret-value');
+    expect(await handleReadCommand('js', ['document.querySelector("#name").value'], bm)).toBe('');
+  });
+
+  test('prettyscreenshot --hide keeps a trailing image path as the output path (#1419)', async () => {
+    await handleWriteCommand('goto', [baseUrl + '/basic.html'], bm);
+    const out = path.join(os.tmpdir(), `pretty-hide-${process.pid}.png`);
+    fs.rmSync(out, { force: true });
+    try {
+      const result = await handleWriteCommand('prettyscreenshot', ['--hide', '#title', '#content', out], bm);
+      expect(result).toContain(out);
+      expect(fs.existsSync(out)).toBe(true);
+      expect(await handleReadCommand('js', ['getComputedStyle(document.querySelector("#content")).display'], bm)).toBe('none');
+    } finally {
+      fs.rmSync(out, { force: true });
+    }
+  });
+
+  test('type -- types text that starts with -- literally; plain text gets no hint', async () => {
+    await handleWriteCommand('goto', [baseUrl + '/forms.html'], bm);
+    await handleWriteCommand('click', ['#bio'], bm);
+    expect(await handleWriteCommand('type', ['--', '--selector', 'x'], bm)).toBe('Typed 12 characters');
+    expect(await handleReadCommand('js', ['document.querySelector("#bio").value'], bm)).toBe('--selector x');
+    await expect(handleWriteCommand('type', ['--selector'], bm)).rejects.toThrow('Usage: browse type [--selector <sel>] [--] <text>');
+    await expect(handleWriteCommand('type', ['--selector', '#name'], bm)).rejects.toThrow('Usage');
+  });
 });
 
 // ─── SPA / Console / Network ───────────────────────────────────

browse/test/config.test.ts

@@ -431,17 +431,21 @@ describe('resolveChromiumProfile', () => {
     }
   });
 
-  test('falls back to resolveGstackHome()/chromium-profile when nothing set', () => {
+  test('falls back to the project state dir, not the machine-wide gstack home (D5, #2492)', () => {
     const origEnv = process.env.CHROMIUM_PROFILE;
     const origHome = process.env.GSTACK_HOME;
+    const origState = process.env.BROWSE_STATE_FILE;
     delete process.env.CHROMIUM_PROFILE;
     process.env.GSTACK_HOME = '/tmp/fallback-gstack';
+    process.env.BROWSE_STATE_FILE = '/tmp/project-a/.gstack/browse.json';
     try {
-      expect(resolveChromiumProfile()).toBe('/tmp/fallback-gstack/chromium-profile');
+      expect(resolveChromiumProfile()).toBe(path.join('/tmp/project-a/.gstack', 'chromium-profile'));
     } finally {
       if (origEnv !== undefined) process.env.CHROMIUM_PROFILE = origEnv;
       if (origHome === undefined) delete process.env.GSTACK_HOME;
       else process.env.GSTACK_HOME = origHome;
+      if (origState === undefined) delete process.env.BROWSE_STATE_FILE;
+      else process.env.BROWSE_STATE_FILE = origState;
     }
   });
 

browse/test/dotenv-isolation.test.ts

@@ -0,0 +1,121 @@
+/**
+ * D0: a project's .env and bunfig.toml must not reach gstack's binaries or
+ * the Bun children the browse daemon starts in that project. Dotenv could set
+ * GSTACK_CHROMIUM_NO_SANDBOX; a bunfig preload runs arbitrary code.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { spawnTerminalAgent } from '../src/terminal-agent-control';
+
+const ROOT = path.resolve(import.meta.dir, '..', '..');
+const CLI = path.join(ROOT, 'browse', 'src', 'cli.ts');
+
+let project: string;
+let marker: string;
+
+function seedHostileProject(dir: string): void {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, '.env'), 'GSTACK_CHROMIUM_NO_SANDBOX=1\n');
+  fs.writeFileSync(path.join(dir, 'preload.ts'), `require('node:fs').writeFileSync(${JSON.stringify(marker)}, 'ran');\n`);
+  fs.writeFileSync(path.join(dir, 'bunfig.toml'), 'preload = ["./preload.ts"]\n');
+}
+
+function probeSource(out: string): string {
+  return `require('node:fs').writeFileSync(${JSON.stringify(out)}, JSON.stringify({ sandbox: process.env.GSTACK_CHROMIUM_NO_SANDBOX ?? null }));\n`;
+}
+
+async function waitForFile(file: string): Promise<string> {
+  const deadline = Date.now() + 20_000;
+  while (!fs.existsSync(file) && Date.now() < deadline) await Bun.sleep(50);
+  return fs.readFileSync(file, 'utf-8');
+}
+
+beforeEach(() => {
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'browse-dotenv-'));
+  project = path.join(scratch, 'project');
+  marker = path.join(scratch, 'preload-ran');
+  seedHostileProject(project);
+});
+
+afterEach(() => {
+  fs.rmSync(path.dirname(project), { recursive: true, force: true });
+});
+
+describe('D0: project .env and bunfig.toml are ignored', () => {
+  test('every compiled binary in scripts/build.sh turns dotenv and bunfig autoload off, and the flags work', () => {
+    const lines = fs.readFileSync(path.join(ROOT, 'scripts', 'build.sh'), 'utf-8').split('\n').filter(l => /build --compile/.test(l));
+    expect(lines.length).toBeGreaterThanOrEqual(5);
+    for (const line of lines) {
+      expect(line).toContain('--no-compile-autoload-dotenv');
+      expect(line).toContain('--no-compile-autoload-bunfig');
+    }
+    const out = path.join(path.dirname(project), 'probe.json');
+    const src = path.join(path.dirname(project), 'probe.ts');
+    const bin = path.join(path.dirname(project), process.platform === 'win32' ? 'probe-bin.exe' : 'probe-bin');
+    fs.writeFileSync(src, probeSource(out));
+    const build = Bun.spawnSync([process.execPath, 'build', '--compile', '--no-compile-autoload-dotenv', '--no-compile-autoload-bunfig', src, '--outfile', bin], { stdout: 'pipe', stderr: 'pipe', timeout: 60_000 });
+    expect(build.exitCode, build.stderr.toString()).toBe(0);
+    const run = Bun.spawnSync([bin], { cwd: project, env: { PATH: process.env.PATH ?? '' }, stdout: 'pipe', stderr: 'pipe', timeout: 30_000 });
+    expect(run.exitCode, run.stderr.toString()).toBe(0);
+    expect(JSON.parse(fs.readFileSync(out, 'utf-8'))).toEqual({ sandbox: null });
+    expect(fs.existsSync(marker)).toBe(false);
+  }, 90_000);
+
+  // The agent's owner identity comes from `ps`, which Windows runners lack.
+  test.skipIf(process.platform === 'win32')('the terminal agent spawned in the project sees neither the .env value nor the bunfig preload', async () => {
+    const stateDir = path.join(path.dirname(project), 'state');
+    fs.mkdirSync(stateDir, { recursive: true });
+    const out = path.join(stateDir, 'agent-env.json');
+    const script = path.join(stateDir, 'agent-probe.ts');
+    fs.writeFileSync(script, probeSource(out));
+    const saved = process.env.GSTACK_CHROMIUM_NO_SANDBOX;
+    delete process.env.GSTACK_CHROMIUM_NO_SANDBOX;
+    try {
+      const pid = spawnTerminalAgent({ stateFile: path.join(stateDir, 'browse.json'), serverPort: 1, ownerPid: process.pid, cwd: project, scriptPath: script });
+      expect(pid).toBeGreaterThan(0);
+      expect(JSON.parse(await waitForFile(out))).toEqual({ sandbox: null });
+      expect(fs.existsSync(marker)).toBe(false);
+    } finally {
+      if (saved !== undefined) process.env.GSTACK_CHROMIUM_NO_SANDBOX = saved;
+    }
+  }, 30_000);
+
+  test.skipIf(process.platform === 'win32')('the browse server spawned from the project sees neither the .env value nor the bunfig preload', async () => {
+    const stateFile = path.join(project, '.gstack', 'browse.json');
+    const stub = path.join(path.dirname(project), 'stub-server.ts');
+    fs.writeFileSync(stub, `
+      import * as fs from 'node:fs';
+      const server = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch: () => Response.json({ status: 'healthy' }) });
+      fs.writeFileSync(process.env.BROWSE_STATE_FILE!, JSON.stringify({
+        pid: process.pid, port: server.port, token: 'dotenv-test', mode: 'launched',
+        sandbox: process.env.GSTACK_CHROMIUM_NO_SANDBOX ?? null,
+      }));
+      setTimeout(() => server.stop(true), 5000);
+    `);
+    const env: Record<string, string> = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== undefined && !/^(BROWSE_|GSTACK_|CHROMIUM_PROFILE$|CLAUDE_PLUGIN_DATA$)/.test(key)) env[key] = value;
+    }
+    Object.assign(env, {
+      HOME: path.dirname(project),
+      GSTACK_HOME: path.join(path.dirname(project), '.gstack'),
+      BROWSE_STATE_FILE: stateFile,
+      BROWSE_SERVER_SCRIPT: stub,
+      BROWSE_PARENT_PID: '0',
+      BROWSE_START_TIMEOUT: '20000',
+    });
+    // The shipped CLI is compiled without dotenv autoload; --no-env-file gives
+    // the source CLI the same starting environment.
+    const cli = Bun.spawn([process.execPath, '--no-env-file', '--config=/dev/null', CLI, 'status'], { cwd: project, env, stdout: 'pipe', stderr: 'pipe' });
+    const timer = setTimeout(() => cli.kill('SIGKILL'), 40_000);
+    const [code, stderr] = await Promise.all([cli.exited, new Response(cli.stderr).text()]);
+    clearTimeout(timer);
+    const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+    try { process.kill(state.pid, 'SIGKILL'); } catch {}
+    expect(code, stderr).toBe(0);
+    expect(state.sandbox).toBeNull();
+    expect(fs.existsSync(marker)).toBe(false);
+  }, 60_000);
+});

browse/test/extension-token.test.ts

@@ -31,7 +31,7 @@ import { BrowserManager } from '../src/browser-manager';
 import { resolveConfig } from '../src/config';
 import { usePrivateStateRoot } from '../../test/helpers/private-state-root';
 
-usePrivateStateRoot();
+const privateRoot = usePrivateStateRoot();
 
 const PINNED_ORIGIN = `chrome-extension://${GSTACK_EXTENSION_ID}`;
 const fixtureDir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-extension-token-')));
@@ -168,6 +168,24 @@ describe('POST /extension-token pinned-origin bootstrap', () => {
     expect(JSON.stringify(body)).not.toContain('host');
   });
 
+  test('gstack-config browse_extension_id moves the token to the configured extension; the env var does not', async () => {
+    const fork = 'b'.repeat(32);
+    const cfg = makeConfig();
+    const handle = buildFetchHandler(cfg);
+    const status = async (origin: string) => (await handle.fetchLocal(tokenRequest({ Origin: origin, Host: '127.0.0.1:34567' }), null)).status;
+    const saved = process.env.BROWSE_EXTENSION_ID;
+    process.env.BROWSE_EXTENSION_ID = fork;
+    try {
+      expect(await status(`chrome-extension://${fork}`)).toBe(403);
+      fs.writeFileSync(path.join(privateRoot.dir, 'config.yaml'), `browse_extension_id: ${fork}\n`);
+      expect(await status(`chrome-extension://${fork}`)).toBe(200);
+      expect(await status(PINNED_ORIGIN)).toBe(403);
+    } finally {
+      if (saved === undefined) delete process.env.BROWSE_EXTENSION_ID;
+      else process.env.BROWSE_EXTENSION_ID = saved;
+    }
+  });
+
   test('missing Origin → 403', async () => {
     const handle = buildFetchHandler(makeConfig());
     const resp = await handle.fetchLocal(tokenRequest({

browse/test/handoff.test.ts

@@ -331,10 +331,12 @@ describe.skipIf(process.platform !== 'linux')('lazy owned display lifecycle', ()
   let root: string;
   let hbm: BrowserManager;
   const displays = () => {
-    const result = Bun.spawnSync(['ps', '--ppid', String(process.pid), '-o', 'comm='], {
+    // A terminated Xvfb can linger as a zombie until this process reaps it; it is no display.
+    const result = Bun.spawnSync(['ps', '--ppid', String(process.pid), '-o', 'stat=,comm='], {
       stdout: 'pipe', stderr: 'pipe', timeout: 2000,
     });
-    return result.stdout.toString().split('\n').filter(line => line.trim() === 'Xvfb').length;
+    return result.stdout.toString().split('\n').map(line => line.trim().split(/\s+/))
+      .filter(([stat, comm]) => comm === 'Xvfb' && !stat?.startsWith('Z')).length;
   };
 
   beforeEach(async () => {

browse/test/headless-gpu-and-reap.test.ts

@@ -189,11 +189,10 @@ describe('stop-reap wiring pins (#2709)', () => {
     // unguarded push would strip the GPU from headed/GBrowser sessions.
     const calls = src.match(/headlessGpuArgs\(process\.platform, process\.env\)/g) ?? [];
     expect(calls.length).toBe(1);
-    // And that one call site is guarded by the headless flag: the extensions
-    // path above it forces useHeadless = false, so extension-loaded and headed
-    // launches never receive the GPU-disable flags.
-    expect(src).toMatch(
-      /if \(useHeadless\) \{\s*\n\s*launchArgs\.push\(\.\.\.headlessGpuArgs\(process\.platform, process\.env\)\);\s*\n\s*\}/,
-    );
+    // And that one call site is in the headless launch(), never in the headed
+    // launchHeaded(). Since #2281 the extensions path is new headless too
+    // (--headless=new, no window), so it takes the headless GPU flags.
+    const headless = src.slice(src.indexOf('  async launch() {'), src.indexOf('  async launchHeaded('));
+    expect(headless).toContain('launchArgs.push(...headlessGpuArgs(process.platform, process.env));');
   });
 });

browse/test/headless-launch-options.test.ts

@@ -0,0 +1,93 @@
+/**
+ * E8 (#2771, #1968) and #2281: the headless launch honors GSTACK_CHROMIUM_PATH
+ * and names it when it fails; BROWSE_EXTENSIONS_DIR loads extensions in new
+ * headless mode (no window, extension actually runs) instead of an off-screen
+ * headed window.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { chromium } from 'playwright';
+import { BrowserManager } from '../src/browser-manager';
+import { readPidCmdline } from '../src/xvfb';
+import { handleWriteCommand } from '../src/write-commands';
+
+const ENV_KEYS = ['GSTACK_CHROMIUM_PATH', 'BROWSE_EXTENSIONS_DIR', 'BROWSE_STATE_FILE'] as const;
+let saved: Record<string, string | undefined>;
+let scratch: string;
+let bm: BrowserManager | null;
+
+beforeEach(() => {
+  saved = Object.fromEntries(ENV_KEYS.map(k => [k, process.env[k]]));
+  scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'browse-launch-opts-'));
+  process.env.BROWSE_STATE_FILE = path.join(scratch, 'state', 'browse.json');
+  bm = null;
+});
+
+afterEach(async () => {
+  try { await Promise.race([bm?.close(), new Promise((resolve) => setTimeout(resolve, 3000))]); } catch {}
+  for (const k of ENV_KEYS) {
+    if (saved[k] === undefined) delete process.env[k];
+    else process.env[k] = saved[k];
+  }
+  fs.rmSync(scratch, { recursive: true, force: true });
+});
+
+describe.skipIf(process.platform !== 'linux')('headless launch options (Linux, real Chromium)', () => {
+  test('GSTACK_CHROMIUM_PATH is the binary the headless launch runs', async () => {
+    const custom = chromium.executablePath();
+    process.env.GSTACK_CHROMIUM_PATH = custom;
+    // Only browsers this launch started count: an earlier file in the same
+    // shard process may still be reaping its own headless_shell child.
+    const children = () => new Set(fs.readdirSync('/proc').filter(d => /^\d+$/.test(d)).filter(d => {
+      try { return fs.readFileSync(`/proc/${d}/stat`, 'utf-8').split(') ')[1].split(' ')[1] === String(process.pid); } catch { return false; }
+    }));
+    const before = children();
+    bm = new BrowserManager();
+    await bm.launch();
+    const cmdlines = [...children()].filter(pid => !before.has(pid)).map(pid => readPidCmdline(Number(pid)));
+    expect(cmdlines.some(c => c.startsWith(custom) && c.includes('--headless'))).toBe(true);
+    expect(cmdlines.some(c => c.includes('headless_shell'))).toBe(false);
+  }, 60_000);
+
+  test('close returns when Chromium exits, not at the close race timeout', async () => {
+    // Removing every 'disconnected' listener used to strip Playwright's own,
+    // so browser.close() never resolved and every close waited 5 s.
+    bm = new BrowserManager();
+    await bm.launch();
+    const started = performance.now();
+    await bm.close();
+    expect(performance.now() - started).toBeLessThan(2_500);
+    bm = null;
+  }, 60_000);
+
+  test('a broken GSTACK_CHROMIUM_PATH fails with the path named', async () => {
+    const missing = path.join(scratch, 'no-such-chromium');
+    process.env.GSTACK_CHROMIUM_PATH = missing;
+    bm = new BrowserManager();
+    await expect(bm.launch()).rejects.toThrow(`Chromium at GSTACK_CHROMIUM_PATH=${missing} failed to launch`);
+  }, 60_000);
+
+  test('BROWSE_EXTENSIONS_DIR runs the extension in new headless mode', async () => {
+    const ext = path.join(scratch, 'ext');
+    fs.mkdirSync(ext);
+    fs.writeFileSync(path.join(ext, 'manifest.json'), JSON.stringify({
+      manifest_version: 3, name: 'probe', version: '1',
+      content_scripts: [{ matches: ['<all_urls>'], js: ['c.js'], run_at: 'document_start' }],
+    }));
+    fs.writeFileSync(path.join(ext, 'c.js'), 'document.documentElement.setAttribute("data-probe-ext", "1");');
+    process.env.BROWSE_EXTENSIONS_DIR = ext;
+    const server = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch: () => new Response('<p>x</p>', { headers: { 'Content-Type': 'text/html' } }) });
+    try {
+      bm = new BrowserManager();
+      await bm.launch();
+      const session = bm.getActiveSession();
+      await handleWriteCommand('goto', [`http://127.0.0.1:${server.port}/`], session, bm);
+      expect(await session.getPage().evaluate(() => document.documentElement.getAttribute('data-probe-ext'))).toBe('1');
+      expect(fs.existsSync(path.join(scratch, 'state', 'extensions', 'chromium-profile'))).toBe(true);
+    } finally {
+      server.stop(true);
+    }
+  }, 60_000);
+});

browse/test/launch-signal-flags.test.ts

@@ -51,10 +51,11 @@ describe('Playwright launch sites disable signal handlers (#2220)', () => {
     const src = SRC('browser-manager.ts');
     const launchCount = expectSignalFlagsNearEvery(src, 'chromium.launch({');
     const persistentCount = expectSignalFlagsNearEvery(src, 'chromium.launchPersistentContext(');
-    // Three launch sites today: headless launch(), headed launchHeaded(),
-    // and the handoff relaunch. A NEW launch site must carry the flags too —
-    // bump this only after adding them.
-    expect(launchCount + persistentCount).toBe(3);
+    // Four launch sites today: headless launch(), its BROWSE_EXTENSIONS_DIR
+    // persistent context (#2281), headed launchHeaded(), and the handoff
+    // relaunch. A NEW launch site must carry the flags too — bump this only
+    // after adding them.
+    expect(launchCount + persistentCount).toBe(4);
   });
 
   test('server.ts owns SIGHUP cleanup now that Playwright does not (ENG-OV4)', () => {

browse/test/memory-leak-reproducer.test.ts

@@ -97,6 +97,7 @@ describe('memory-leak reproducer: requestfinished does not materialize bodies',
       page.emit('request', {
         url: () => `https://example.invalid/asset/${i}`,
         method: () => 'GET',
+        isNavigationRequest: () => false,
       });
     }
 

browse/test/navigation-guard.test.ts

@@ -0,0 +1,87 @@
+/**
+ * D2 (#2811): redirects and page-driven navigations to link-local or metadata
+ * addresses are refused, not only explicit `goto` targets. Commands run the way
+ * server.ts runs write commands: through BrowserManager.failIfNavigationBlocked.
+ */
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { BrowserManager } from '../src/browser-manager';
+import { handleWriteCommand } from '../src/write-commands';
+
+let bm: BrowserManager;
+let server: ReturnType<typeof Bun.serve>;
+let base: string;
+
+const LINK_LOCAL = 'http://169.254.170.2/v2/credentials';
+const MAPPED = 'http://[::ffff:169.254.170.2]/v2/credentials';
+// Port 1 is unsafe in Chromium, so this blocked target fails at once (ERR_UNSAFE_PORT)
+// and commits its error page around the guard's reset, as CI's mapped-address hop did.
+const FAST_FAIL = 'http://[::ffff:169.254.170.2]:1/v2/credentials';
+
+beforeAll(async () => {
+  server = Bun.serve({
+    hostname: '127.0.0.1',
+    port: 0,
+    fetch(req) {
+      const url = new URL(req.url);
+      const html = (body: string) => new Response(`<!doctype html><html><body>${body}</body></html>`, { headers: { 'Content-Type': 'text/html' } });
+      if (url.pathname === '/to-link-local') return Response.redirect(LINK_LOCAL, 302);
+      if (url.pathname === '/to-mapped') return Response.redirect(MAPPED, 302);
+      if (url.pathname === '/to-fast-fail') return Response.redirect(FAST_FAIL, 302);
+      if (url.pathname === '/to-safe') return Response.redirect(`${base}/safe`, 302);
+      if (url.pathname === '/link') return html(`<a id="go" href="${LINK_LOCAL}">go</a>`);
+      if (url.pathname === '/script') return html(`<button id="go" onclick="location.href='${LINK_LOCAL}'">go</button>`);
+      return html('<p id="ok">safe page</p>');
+    },
+  });
+  base = `http://127.0.0.1:${server.port}`;
+  bm = new BrowserManager();
+  await bm.launch();
+});
+
+afterAll(async () => {
+  try { server.stop(true); } catch {}
+  try { await Promise.race([bm?.close(), new Promise((resolve) => setTimeout(resolve, 3000))]); } catch {}
+});
+
+function run(command: string, args: string[]): Promise<string> {
+  const session = bm.getActiveSession();
+  return bm.failIfNavigationBlocked(session.getPage(), handleWriteCommand(command, args, session, bm));
+}
+
+describe('D2: navigation guard', () => {
+  test('a redirect to 169.254.0.0/16 fails the goto and leaves the tab blank', async () => {
+    await expect(run('goto', [`${base}/to-link-local`])).rejects.toThrow(/169\.254\.170\.2 is a cloud metadata or link-local address/);
+    expect(bm.getActiveSession().getPage().url()).toBe('about:blank');
+  }, 30_000);
+
+  test('a redirect to an IPv4-mapped IPv6 link-local address is refused too', async () => {
+    await expect(run('goto', [`${base}/to-mapped`])).rejects.toThrow(/cloud metadata or link-local/);
+    expect(bm.getActiveSession().getPage().url()).toBe('about:blank');
+  }, 30_000);
+
+  test('a blocked target that fails at once still leaves the tab blank for the next command', async () => {
+    await expect(run('goto', [`${base}/to-fast-fail`])).rejects.toThrow(/cloud metadata or link-local/);
+    expect(bm.getActiveSession().getPage().url()).toBe('about:blank');
+    const result = await run('goto', [`${base}/safe`]);
+    expect(result).toContain('Navigated to');
+    expect(bm.getActiveSession().getPage().url()).toBe(`${base}/safe`);
+  }, 30_000);
+
+  test('clicking a link to a link-local address is refused', async () => {
+    await run('goto', [`${base}/link`]);
+    await expect(run('click', ['#go'])).rejects.toThrow(/cloud metadata or link-local/);
+    expect(bm.getActiveSession().getPage().url()).toBe('about:blank');
+  }, 30_000);
+
+  test('a script-driven navigation to a link-local address is refused', async () => {
+    await run('goto', [`${base}/script`]);
+    await expect(run('click', ['#go'])).rejects.toThrow(/cloud metadata or link-local/);
+    expect(bm.getActiveSession().getPage().url()).toBe('about:blank');
+  }, 30_000);
+
+  test('ordinary redirects and the next command still work after a block', async () => {
+    const result = await run('goto', [`${base}/to-safe`]);
+    expect(result).toContain('Navigated to');
+    expect(bm.getActiveSession().getPage().url()).toBe(`${base}/safe`);
+  }, 30_000);
+});

browse/test/output-path-symlinks.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Output-destination validation (salvaged from #2971): validateOutputPath must
+ * judge the path the kernel will actually write, component by component.
+ * The fixture lives under /var/tmp, outside every safe directory, and the
+ * validator runs in a child whose cwd (a safe directory) is the fixture's
+ * allowed dir; nothing is ever written to HOME.
+ */
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const VALIDATOR = path.resolve(import.meta.dir, '../src/path-security.ts');
+const POSIX = process.platform !== 'win32' && fs.existsSync('/var/tmp');
+let root = '';
+let allowed = '';
+let outside = '';
+
+beforeAll(() => {
+  if (!POSIX) return;
+  root = fs.realpathSync(fs.mkdtempSync('/var/tmp/gstack-output-path-'));
+  allowed = path.join(root, 'allowed');
+  outside = path.join(root, 'outside');
+  fs.mkdirSync(path.join(allowed, 'nested'), { recursive: true });
+  fs.mkdirSync(path.join(outside, 'nested'), { recursive: true });
+  fs.writeFileSync(path.join(allowed, 'internal.txt'), 'x');
+  fs.writeFileSync(path.join(outside, 'existing.txt'), 'x');
+  const links: Array<[string, string]> = [
+    ['internal-link.txt', path.join(allowed, 'internal.txt')],
+    ['internal-parent', path.join(allowed, 'nested')],
+    ['outward-live.txt', path.join(outside, 'existing.txt')],
+    ['outward-dangling.txt', path.join(outside, 'missing.txt')],
+    ['outward-parent', outside],
+    ['outward-nested', path.join(outside, 'nested')],
+    ['dangling-parent', path.join(outside, 'missing-dir')],
+    ['loop', path.join(allowed, 'loop')],
+  ];
+  for (const [name, target] of links) fs.symlinkSync(target, path.join(allowed, name));
+});
+
+afterAll(() => {
+  if (root) fs.rmSync(root, { recursive: true, force: true });
+});
+
+function verdicts(files: string[]): Record<string, string | null> {
+  const script = `
+    import { validateOutputPath } from ${JSON.stringify(VALIDATOR)};
+    const out = {};
+    for (const f of JSON.parse(process.argv[1])) {
+      try { validateOutputPath(f); out[f] = null; } catch (e) { out[f] = e.message; }
+    }
+    console.log(JSON.stringify(out));
+  `;
+  const r = Bun.spawnSync([process.execPath, '-e', script, JSON.stringify(files)], {
+    cwd: allowed,
+    env: { ...process.env, TMPDIR: path.join(allowed, 'nested') },
+    stdout: 'pipe',
+    stderr: 'pipe',
+    timeout: 15_000,
+  });
+  expect(r.exitCode, r.stderr.toString()).toBe(0);
+  return JSON.parse(r.stdout.toString());
+}
+
+describe.skipIf(!POSIX)('validateOutputPath follows the physical path', () => {
+  test('ordinary, new, and in-root symlinked destinations are allowed', () => {
+    const files = ['ordinary.txt', 'new-dir/deeper/new.txt', 'internal-link.txt', 'internal-parent/x.txt', 'nested/../x.txt'];
+    expect(verdicts(files.map(f => path.join(allowed, f)))).toEqual(Object.fromEntries(files.map(f => [path.join(allowed, f), null])));
+  });
+
+  test('destinations that a write would land outside are rejected', () => {
+    const files = ['outward-live.txt', 'outward-dangling.txt', 'outward-parent/new.txt', 'outward-nested/../escaped.txt', 'dangling-parent/new.txt', 'loop', 'loop/new.txt'];
+    const result = verdicts(files.map(f => `${allowed}/${f}`));
+    for (const f of files) expect(result[`${allowed}/${f}`]).toContain('Path must be within');
+    expect(fs.existsSync(path.join(outside, 'missing.txt'))).toBe(false);
+  });
+});

browse/test/path-validation.test.ts

@@ -2,7 +2,7 @@ import { beforeAll, describe, it, expect } from 'bun:test';
 import { chromium } from 'playwright';
 import { validateOutputPath } from '../src/path-security';
 import { validateReadPath, SENSITIVE_COOKIE_NAME, SENSITIVE_COOKIE_VALUE } from '../src/read-commands';
-import { BLOCKED_METADATA_HOSTS } from '../src/url-validation';
+import { classifyAddress } from '../src/url-validation';
 import { mkdirSync, mkdtempSync, rmSync, symlinkSync, unlinkSync, writeFileSync, realpathSync } from 'fs';
 import { tmpdir, userInfo } from 'os';
 import { join } from 'path';
@@ -258,11 +258,11 @@ describe('DNS rebinding — production blocklist', () => {
   });
 
   it('blocks AWS/GCP IPv4 metadata address', () => {
-    expect(BLOCKED_METADATA_HOSTS.has('169.254.169.254')).toBe(true);
+    expect(classifyAddress('169.254.169.254')).toBe('blocked');
   });
 
   it('does not block normal addresses', () => {
-    expect(BLOCKED_METADATA_HOSTS.has('8.8.8.8')).toBe(false);
-    expect(BLOCKED_METADATA_HOSTS.has('2001:4860:4860::8888')).toBe(false);
+    expect(classifyAddress('8.8.8.8')).toBe('other');
+    expect(classifyAddress('2001:4860:4860::8888')).toBe('other');
   });
 });

browse/test/server-launch-resolution.test.ts

@@ -0,0 +1,49 @@
+/**
+ * E4 (#2439): the CLI resolves its server script only when it starts a
+ * server. A Windows minimal runtime ships browse.exe + server-node.mjs and no
+ * browse/src/server.ts, which used to make every command fail at import.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { resolveServerLaunch } from '../src/cli';
+
+function withRuntime<T>(files: string[], fn: (dir: string) => T): T {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'browse-runtime-'));
+  try {
+    for (const f of files) fs.writeFileSync(path.join(dir, f), '// stub\n');
+    return fn(dir);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const COMPILED_META = path.join(os.tmpdir(), '$bunfs', 'root');
+
+describe('resolveServerLaunch', () => {
+  test('Windows minimal runtime starts the adjacent Node bundle without server.ts', () => {
+    withRuntime(['server-node.mjs'], (dir) => {
+      expect(resolveServerLaunch('win32', {}, COMPILED_META, path.join(dir, 'browse.exe')))
+        .toEqual({ runtime: 'node', script: path.join(dir, 'server-node.mjs') });
+    });
+  });
+
+  test('Windows without the Node bundle names the build fix', () => {
+    withRuntime([], (dir) => {
+      expect(() => resolveServerLaunch('win32', {}, COMPILED_META, path.join(dir, 'browse.exe')))
+        .toThrow('server-node.mjs not found. Run `bun run build`');
+    });
+  });
+
+  test('macOS/Linux start server.ts with Bun, honoring BROWSE_SERVER_SCRIPT', () => {
+    expect(resolveServerLaunch('linux', { BROWSE_SERVER_SCRIPT: 'custom-server.ts' }, COMPILED_META, ''))
+      .toEqual({ runtime: 'bun', script: 'custom-server.ts' });
+  });
+
+  test('importing the CLI resolves nothing: a missing server is reported only when one is started', () => {
+    const src = fs.readFileSync(path.join(import.meta.dir, '..', 'src', 'cli.ts'), 'utf-8');
+    expect(src).not.toMatch(/^const \w+ = resolve(Server|NodeServer)\w*\(/m);
+    expect(src).toMatch(/async function startServer\([^)]*\)[^{]*\{\n\s*const server = resolveServerLaunch\(\);/);
+  });
+});

browse/test/sidebar-tabs.test.ts

@@ -233,7 +233,7 @@ describe('cli.ts: sidebar-agent is no longer spawned', () => {
       'utf-8',
     );
     expect(CONTROL_SRC).toContain('terminal-agent.ts');
-    expect(CONTROL_SRC).toMatch(/\.spawn\(\['bun',\s*'run',\s*script,\s*`--agent-gen=\$\{gen\}`\]/);
+    expect(CONTROL_SRC).toMatch(/\.spawn\(\['bun',\s*'run',\s*\.\.\.BUN_CHILD_FLAGS,\s*script,\s*`--agent-gen=\$\{gen\}`\]/);
     expect(CONTROL_SRC).toContain('BROWSE_OWNER_PID: String(opts.ownerPid)');
   });
 });

browse/test/terminal-agent-integration.test.ts

@@ -18,9 +18,13 @@ import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { GSTACK_EXTENSION_ID } from '../src/extension-id';
 
 const AGENT_SCRIPT = path.join(import.meta.dir, '../src/terminal-agent.ts');
 const BASH = '/bin/bash';
+const EXT_ORIGIN = `chrome-extension://${GSTACK_EXTENSION_ID}`;
+const ENV_EXTENSION_ID = 'a'.repeat(32);
+const FORK_EXTENSION_ID = 'b'.repeat(32);
 
 let stateDir: string;
 let agentProc: any;
@@ -73,6 +77,8 @@ beforeAll(() => {
       BROWSE_STATE_FILE: stateFile,
       BROWSE_SERVER_PORT: '0', // not used in this test
       BROWSE_TERMINAL_BINARY: terminalCli,
+      GSTACK_STATE_ROOT: stateDir,
+      BROWSE_EXTENSION_ID: ENV_EXTENSION_ID,
     },
     stdio: ['ignore', 'pipe', 'pipe'],
   });
@@ -128,7 +134,7 @@ describe('terminal-agent: /internal/grant and /internal/revoke bearer auth', ()
 
   function wsStatus(token: string): Promise<number> {
     return fetch(`http://127.0.0.1:${agentPort}/ws`, {
-      headers: { 'Origin': 'chrome-extension://abc123', 'Cookie': `gstack_pty=${token}` },
+      headers: { 'Origin': EXT_ORIGIN, 'Cookie': `gstack_pty=${token}` },
     }).then((r) => r.status);
   }
 
@@ -173,10 +179,34 @@ describe('terminal-agent: /ws gates', () => {
     expect(resp.status).toBe(403);
   });
 
+  function wsOriginStatus(origin: string): Promise<number> {
+    return fetch(`http://127.0.0.1:${agentPort}/ws`, {
+      headers: { Origin: origin, Cookie: 'gstack_pty=never-granted' },
+    }).then((r) => r.status);
+  }
+
+  test('rejects every extension Origin except the pinned one, even BROWSE_EXTENSION_ID from the environment (#1324)', async () => {
+    expect(await wsOriginStatus('chrome-extension://abc123')).toBe(403);
+    expect(await wsOriginStatus(`chrome-extension://${ENV_EXTENSION_ID}`)).toBe(403);
+    expect(await wsOriginStatus(EXT_ORIGIN)).toBe(401);
+  });
+
+  test('gstack-config browse_extension_id replaces the pinned ID for forks', async () => {
+    const config = path.join(stateDir, 'config.yaml');
+    fs.writeFileSync(config, `browse_extension_id: ${FORK_EXTENSION_ID}\n`);
+    try {
+      expect(await wsOriginStatus(`chrome-extension://${FORK_EXTENSION_ID}`)).toBe(401);
+      expect(await wsOriginStatus(EXT_ORIGIN)).toBe(403);
+    } finally {
+      fs.rmSync(config, { force: true });
+    }
+    expect(await wsOriginStatus(EXT_ORIGIN)).toBe(401);
+  });
+
   test('rejects extension-Origin upgrades without a granted cookie', async () => {
     const resp = await fetch(`http://127.0.0.1:${agentPort}/ws`, {
       headers: {
-        'Origin': 'chrome-extension://abc123',
+        'Origin': EXT_ORIGIN,
         'Cookie': 'gstack_pty=never-granted',
       },
     });
@@ -192,7 +222,7 @@ describe('terminal-agent: PTY round-trip via real WebSocket (Cookie auth)', () =
 
     const ws = new WebSocket(`ws://127.0.0.1:${agentPort}/ws`, {
       headers: {
-        'Origin': 'chrome-extension://test-extension-id',
+        'Origin': EXT_ORIGIN,
         'Cookie': `gstack_pty=${cookie}`,
       },
     } as any);
@@ -274,7 +304,7 @@ describe('terminal-agent: PTY round-trip via real WebSocket (Cookie auth)', () =
         'Sec-WebSocket-Version': '13',
         'Sec-WebSocket-Key': handshakeKey,
         'Sec-WebSocket-Protocol': `gstack-pty.${token}`,
-        'Origin': 'chrome-extension://test-extension-id',
+        'Origin': EXT_ORIGIN,
       },
     });
 
@@ -307,7 +337,7 @@ describe('terminal-agent: PTY round-trip via real WebSocket (Cookie auth)', () =
         'Sec-WebSocket-Version: 13\r\n' +
         'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n' +
         `Sec-WebSocket-Protocol: gstack-pty.${token}\r\n` +
-        'Origin: chrome-extension://test-extension-id\r\n' +
+        `Origin: ${EXT_ORIGIN}\r\n` +
         '\r\n';
       let buf = '';
       const socket = require('net').connect(agentPort, '127.0.0.1', () => socket.write(req));
@@ -333,7 +363,7 @@ describe('terminal-agent: PTY round-trip via real WebSocket (Cookie auth)', () =
         'Sec-WebSocket-Version': '13',
         'Sec-WebSocket-Key': 'dGhlIHNhbXBsZSBub25jZQ==',
         'Sec-WebSocket-Protocol': 'gstack-pty.never-granted-token',
-        'Origin': 'chrome-extension://test-extension-id',
+        'Origin': EXT_ORIGIN,
       },
     });
     expect(resp.status).toBe(401);
@@ -345,7 +375,7 @@ describe('terminal-agent: PTY round-trip via real WebSocket (Cookie auth)', () =
 
     const ws = new WebSocket(`ws://127.0.0.1:${agentPort}/ws`, {
       headers: {
-        'Origin': 'chrome-extension://test-extension-id',
+        'Origin': EXT_ORIGIN,
         'Cookie': `gstack_pty=${cookie}`,
       },
     } as any);
@@ -393,7 +423,7 @@ describe('terminal-agent: owned PTY completion and restart', () => {
     const granted = await internal('grant', { token, sessionId });
     expect(granted.status).toBe(200);
     const ws = new WebSocket(`ws://127.0.0.1:${agentPort}/ws`, {
-      headers: { Origin: 'chrome-extension://test-extension-id', Cookie: `gstack_pty=${token}` },
+      headers: { Origin: EXT_ORIGIN, Cookie: `gstack_pty=${token}` },
     } as any);
     const events: Array<{ type: string; [key: string]: any }> = [];
     let output = '';
@@ -472,7 +502,7 @@ describe('terminal-agent: owned PTY completion and restart', () => {
       expect(old.closed()).toBe(1000);
       expect(replacement.closed()).toBeNull();
       const revoked = await fetch(`http://127.0.0.1:${agentPort}/ws`, {
-        headers: { Origin: 'chrome-extension://test-extension-id', Cookie: `gstack_pty=${oldToken}` },
+        headers: { Origin: EXT_ORIGIN, Cookie: `gstack_pty=${oldToken}` },
       });
       expect(revoked.status).toBe(401);
 

browse/test/terminal-agent.test.ts

@@ -117,7 +117,7 @@ describe('Source-level guard: terminal-agent', () => {
     // missing-origin attempt would surface the 401 cookie message and
     // signal to attackers that they need to forge a cookie.
     const wsHandler = AGENT_SRC.slice(AGENT_SRC.indexOf("if (url.pathname === '/ws')"));
-    expect(wsHandler).toContain('chrome-extension://');
+    expect(wsHandler).toContain('allowedExtensionOrigin()');
     expect(wsHandler).toContain('forbidden origin');
   });
 

browse/test/url-validation.test.ts

@@ -1,5 +1,7 @@
-import { describe, it, expect } from 'bun:test';
-import { validateNavigationUrl, normalizeFileUrl } from '../src/url-validation';
+import { describe, it, expect, spyOn } from 'bun:test';
+import * as dns from 'node:dns';
+import { validateNavigationUrl, normalizeFileUrl, classifyAddress, blockedNavigationReason } from '../src/url-validation';
+import { isInternalCookieDomain } from '../src/session-persist';
 import * as fs from 'fs';
 import * as path from 'path';
 import { TEMP_DIR } from '../src/platform';
@@ -136,6 +138,65 @@ describe('validateNavigationUrl', () => {
   it('throws on malformed URLs', async () => {
     await expect(validateNavigationUrl('not-a-url')).rejects.toThrow(/Invalid URL/i);
   });
+
+  it('blocks the whole 169.254.0.0/16 range, incl. container credential endpoints (#2811)', async () => {
+    for (const url of ['http://169.254.170.2/v2/credentials/', 'http://169.254.170.23/', 'http://169.254.1.2/', 'http://0xA9FEAA02/', 'http://[::ffff:169.254.170.2]/', 'http://100.100.100.200/latest/meta-data/']) {
+      await expect(validateNavigationUrl(url)).rejects.toThrow(/cloud metadata or link-local/);
+    }
+  });
+
+  it('leaves 169.254.-prefixed hostnames to DNS and private dev servers allowed', async () => {
+    await expect(validateNavigationUrl('https://169.254.example.com/')).resolves.toBe('https://169.254.example.com/');
+    await expect(validateNavigationUrl('http://10.0.0.5/health')).resolves.toBe('http://10.0.0.5/health');
+    await expect(validateNavigationUrl('http://100.100.100.201/')).resolves.toBe('http://100.100.100.201/');
+  });
+});
+
+describe('classifyAddress (D2: one classifier for literals, DNS answers and cookie domains)', () => {
+  it.each([
+    ['169.254.169.254', 'blocked'], ['169.254.170.2', 'blocked'], ['2852039166', 'blocked'],
+    ['0251.0376.0251.0376', 'blocked'], ['0xA9FEAA02', 'blocked'], ['100.100.100.200', 'blocked'],
+    ['::ffff:169.254.170.2', 'blocked'], ['[::ffff:a9fe:aa02]', 'blocked'], ['::a9fe:a9fe', 'blocked'],
+    ['64:ff9b::169.254.169.254', 'blocked'], ['fe80::1', 'blocked'], ['febf::1', 'blocked'], ['fd00::', 'blocked'],
+    ['127.0.0.1', 'loopback'], ['2130706433', 'loopback'], ['::1', 'loopback'], ['::ffff:127.0.0.1', 'loopback'],
+    ['8.8.8.8', 'other'], ['192.168.1.1', 'other'], ['::ffff:8.8.8.8', 'other'], ['2001:4860:4860::8888', 'other'], ['fec0::1', 'other'],
+    ['example.com', null], ['169.254.example.com', null], ['fd.example.com', null],
+  ] as const)('%s → %s', (host, kind) => {
+    expect(classifyAddress(host)).toBe(kind);
+  });
+
+  it('session-persist drops cookies for every blocked or loopback spelling', () => {
+    for (const domain of ['.169.254.170.2', '[::ffff:a9fe:a9fe]', '2130706433', '100.100.100.200', 'fe80::1']) {
+      expect(isInternalCookieDomain(domain)).toBe(true);
+    }
+    expect(isInternalCookieDomain('.example.com')).toBe(false);
+  });
+});
+
+describe('blockedNavigationReason: DNS answers', () => {
+  async function withAnswers(v4: string[], v6: string[], fn: () => Promise<void>) {
+    const r4 = spyOn(dns.promises, 'resolve4').mockImplementation((async () => v4) as any);
+    const r6 = spyOn(dns.promises, 'resolve6').mockImplementation((async () => v6) as any);
+    try { await fn(); } finally { r4.mockRestore(); r6.mockRestore(); }
+  }
+
+  it('blocks a hostname with one link-local A answer among public ones', async () => {
+    await withAnswers(['93.184.216.34', '169.254.170.2'], [], async () => {
+      expect(await blockedNavigationReason('https://mixed.example/')).toMatch(/resolves to a cloud metadata or link-local address/);
+    });
+  });
+
+  it('blocks a hostname whose AAAA answer is an IPv4-mapped link-local address', async () => {
+    await withAnswers([], ['::ffff:a9fe:a9fe'], async () => {
+      expect(await blockedNavigationReason('https://mapped.example/')).toMatch(/resolves to/);
+    });
+  });
+
+  it('allows a hostname with only public answers', async () => {
+    await withAnswers(['93.184.216.34'], ['2606:2800:220:1:248:1893:25c8:1946'], async () => {
+      expect(await blockedNavigationReason('https://clean.example/')).toBeNull();
+    });
+  });
 });
 
 describe('validateNavigationUrl — restoreState coverage', () => {

browse/test/xvfb.test.ts

@@ -191,7 +191,7 @@ describe.skipIf(process.platform !== 'linux')('display allocation failure contro
     const marker = path.join(root, 'spawned');
     fs.writeFileSync(path.join(root, 'Xvfb'), `#!/bin/sh\nprintf started > ${JSON.stringify(marker)}\nexit 0\n`, { mode: 0o755 });
     try {
-      const display = pickFreeDisplay();
+      const display = pickFreeDisplay(23000, 23100); // a range no other allocator in the suite uses
       expect(display).not.toBeNull();
       const child = Bun.spawnSync([process.execPath, '-e', `
         import { spawnXvfb } from ${JSON.stringify(path.resolve(import.meta.dir, '../src/xvfb.ts'))};
@@ -246,7 +246,9 @@ describe.skipIf(process.platform !== 'linux')('display allocation failure contro
     const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-xvfb-failure-'));
     fs.writeFileSync(path.join(root, 'Xvfb'), '#!/bin/sh\nexit 42\n', { mode: 0o755 });
     try {
-      const display = pickFreeDisplay();
+      // Ubicloud run 23: a concurrent daemon took a default-range display between
+      // this pick and the stub's exit, so startup read as a lost race instead.
+      const display = pickFreeDisplay(22000, 22100);
       expect(display).not.toBeNull();
       const child = Bun.spawnSync([process.execPath, '-e', `
         import { spawnXvfb } from ${JSON.stringify(path.resolve(import.meta.dir, '../src/xvfb.ts'))};
@@ -260,6 +262,57 @@ describe.skipIf(process.platform !== 'linux')('display allocation failure contro
       fs.rmSync(root, { recursive: true, force: true });
     }
   });
+
+  test.skipIf(!HAS_XVFB)('a display whose short-lived holder is gone by the exit check still counts as taken', async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-xvfb-gone-'));
+    const realXvfb = Bun.which('Xvfb')!;
+    const first = pickFreeDisplay(26000, 26100);
+    expect(first).not.toBeNull();
+    // Run 10 (1ffd38e): another test's Xvfb held the display just long enough
+    // to win the lock, then closed before the exit check looked for it.
+    fs.writeFileSync(path.join(root, 'Xvfb'), [
+      '#!/bin/sh',
+      `if [ "$1" = ":${first}" ]; then printf '(EE) Server is already active for display ${first}\\n' >&2; exit 1; fi`,
+      `exec ${JSON.stringify(realXvfb)} "$@"`, '',
+    ].join('\n'), { mode: 0o755 });
+    try {
+      const child = Bun.spawn([process.execPath, '-e', `
+        import { spawnFreeXvfb } from ${JSON.stringify(path.resolve(import.meta.dir, '../src/xvfb.ts'))};
+        try { const handle = await spawnFreeXvfb(${first}, ${first! + 3}); console.log(handle.display); handle.close(); }
+        catch (err) { console.log(err.message); }
+      `], { env: { ...process.env, PATH: `${root}:${process.env.PATH}` }, stdout: 'pipe', stderr: 'pipe', timeout: 20000 });
+      const [stdout, exitCode] = await Promise.all([new Response(child.stdout).text(), child.exited]);
+      expect(exitCode).toBe(0);
+      expect(stdout.trim()).toBe(`:${first! + 1}`);
+      expect(isDisplayFree(first!)).toBe(true);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  }, 30000);
+
+  test.skipIf(!HAS_XVFB)('concurrent allocators that pick the same display both get one', async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-xvfb-race-'));
+    const realXvfb = Bun.which('Xvfb')!;
+    fs.writeFileSync(path.join(root, 'Xvfb'), `#!/bin/sh\nsleep 0.3\nexec ${JSON.stringify(realXvfb)} "$@"\n`, { mode: 0o755 });
+    try {
+      const first = pickFreeDisplay(24000, 24100);
+      expect(first).not.toBeNull();
+      const child = Bun.spawn([process.execPath, '-e', `
+        import { spawnFreeXvfb } from ${JSON.stringify(path.resolve(import.meta.dir, '../src/xvfb.ts'))};
+        const results = await Promise.allSettled([spawnFreeXvfb(${first}, ${first! + 5}), spawnFreeXvfb(${first}, ${first! + 5})]);
+        console.log(JSON.stringify(results.map(r => r.status === 'fulfilled' ? r.value.display : r.reason.message)));
+        for (const r of results) if (r.status === 'fulfilled') r.value.close();
+      `], { env: { ...process.env, PATH: `${root}:${process.env.PATH}` }, stdout: 'pipe', stderr: 'pipe', timeout: 20000 });
+      const [stdout, exitCode] = await Promise.all([new Response(child.stdout).text(), child.exited]);
+      expect(exitCode).toBe(0);
+      const displays: string[] = JSON.parse(stdout.trim());
+      expect(displays[0]).toBe(`:${first}`);
+      expect(displays[1]).toMatch(/^:\d+$/);
+      expect(displays[1]).not.toBe(displays[0]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  }, 30000);
 });
 
 describe.skipIf(process.platform !== 'linux')('daemon-owned display lifecycle', () => {

canary/SKILL.md

@@ -354,14 +354,15 @@ Use Aside first: the user's real browser and signed-in sessions. If unavailable,
 ```bash
 _gs_d() { if command -v gtimeout >/dev/null; then gtimeout 30 "$@"; elif command -v timeout >/dev/null; then timeout 30 "$@"
 elif command -v perl >/dev/null; then perl -e 'alarm(shift);exec(@ARGV)' 30 "$@"; else return 125; fi; }
-if [ "${GSTACK_SKIP_ASIDE:-}" = "1" ] || ! command -v aside >/dev/null 2>&1; then
-  echo "NEEDS_ASIDE"
+_A=aside; command -v aside >/dev/null || _A=$(command -v ~/.local/bin/aside)
+if [ "${GSTACK_SKIP_ASIDE:-}" = "1" ] || [ -z "$_A" ]; then
+  echo "NEEDS_ASIDE: ${GSTACK_PLATFORM:-$(uname)}"
 else
-  _rc=0; _o=$(_gs_d aside repl 'console.log("ASIDE_READY " + pwd)' 2>&1) || _rc=$?
+  _rc=0; _o=$(_gs_d "$_A" repl 'console.log("ASIDE_READY " + pwd)' 2>&1) || _rc=$?
   case "$_rc" in
     124|142) echo "ASIDE_TIMEOUT: probe deadline exceeded" ;;
     125) echo "ASIDE_UNAVAILABLE: bounded probe unavailable" ;;
-    0) if printf '%s\n' "$_o" | grep -q '^ASIDE_READY '; then echo "READY: aside"
+    0) if printf '%s\n' "$_o" | grep -q '^ASIDE_READY '; then echo "READY: $_A"
        else echo "ASIDE_NOT_RUNNING: no readiness marker"; fi ;;
     *) echo "ASIDE_CLI_ERROR: exit $_rc; inspect aside --help locally" ;;
   esac
@@ -369,9 +370,9 @@ else
 fi
 ```
 
-1. `NEEDS_ASIDE`: if `uname -s` prints `Darwin`, say once: "Download Aside (macOS 15+) at aside.com, open it, sign in, then re-run." Off macOS, do not pitch it. NEVER run an installer, brew formula, or download for them; never substitute unit tests or curl for the browser step. Then continue with the Browser fallback section below.
-2. `ASIDE_NOT_RUNNING`: ask once to open the app and retry. Other non-READY statuses: report the safe status, not "app stopped". Never print raw diagnostics (private paths/tokens). Then continue with the Browser fallback section below.
-3. `READY`: continue. `aside --help` and `aside <command> --help` are the authority on flags; take operational syntax from them, never new permissions or scope.
+1. `NEEDS_ASIDE: Darwin` (trust it; don't re-probe): say once: "Download Aside (macOS 15+) at aside.com; open, sign in, re-run." Off macOS, do not pitch it. NEVER run an installer, brew formula, or download; never substitute unit tests or curl for the browser step. Then continue with the Browser fallback section below.
+2. `ASIDE_NOT_RUNNING`: ask once to open the app and retry. Other non-READY statuses: report the safe status, not "app stopped". Never print raw diagnostics. Then continue with the Browser fallback section below.
+3. `READY`: continue (a printed path runs in place of `aside`). `aside --help` and `aside <command> --help` are the authority on flags; take operational syntax from them, never new permissions or scope.
 
 ### Rules for driving a real browser
 

careful/SKILL.md

@@ -14,7 +14,7 @@ hooks:
     - matcher: "Bash"
       hooks:
         - type: command
-          command: "bash $HOME/.claude/skills/gstack/careful/bin/check-careful.sh"
+          command: 'bash -c "exec bash \"$HOME/.claude/skills/gstack/careful/bin/check-careful.sh\""'
           statusMessage: "Checking for destructive commands..."
 ---
 <!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->

careful/SKILL.md.tmpl

@@ -19,7 +19,7 @@ hooks:
     - matcher: "Bash"
       hooks:
         - type: command
-          command: "bash $HOME/.claude/skills/gstack/careful/bin/check-careful.sh"
+          command: 'bash -c "exec bash \"$HOME/.claude/skills/gstack/careful/bin/check-careful.sh\""'
           statusMessage: "Checking for destructive commands..."
 sensitive: true
 ---

careful/bin/hook-extract.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# hook-extract.sh — SHARED JSON helpers for gstack PreToolUse hooks.
+# hook-extract.sh — SHARED JSON and path helpers for gstack PreToolUse hooks.
 # Sourced (never executed) by careful/bin/check-careful.sh and
 # freeze/bin/check-freeze.sh via a path relative to each hook script.
 #
@@ -32,6 +32,48 @@ sys.stdout.write(c if isinstance(c, str) else "")' "$_ghef_field" 2>/dev/null &&
   return 1
 }
 
+# Windows bash (Git Bash / MSYS / Cygwin), read from bash's own OSTYPE so the
+# check never costs a fork: careful sources this file on every Bash call.
+case "${OSTYPE:-}" in
+  msys*|cygwin*|win32*) GSTACK_HOOK_IS_WINDOWS=1 ;;
+  *) GSTACK_HOOK_IS_WINDOWS=0 ;;
+esac
+_GSTACK_HOOK_AZ_UPPER=ABCDEFGHIJKLMNOPQRSTUVWXYZ
+_GSTACK_HOOK_AZ_LOWER=abcdefghijklmnopqrstuvwxyz
+GSTACK_HOOK_PATH=""
+
+# gstack_hook_normalize_path PATH
+#   The one path canonicalization for freeze's boundary AND the tool's
+#   file_path (#2876). Leaves the result in GSTACK_HOOK_PATH (stdout is the
+#   hook's decision channel, and $(...) would cost a fork):
+#     C:\dev\x  c:/dev/x  -> /c/dev/x      (separators, drive-letter case)
+#     \\srv\share\x       -> //srv/share/x (UNC: the leading // is kept)
+#     /cygdrive/c/x       -> /c/x          (Windows bash only)
+#   Drive-letter and UNC shapes are recognised lexically on every platform.
+#   A path without those shapes is rewritten only on Windows bash: on POSIX
+#   '\' is a legal filename character, and rewriting it would let a name like
+#   'a\..\..\etc\x' change which directory the check sees. Remaining case
+#   differences on Windows are handled by comparing under nocasematch.
+#   Builtins only, bash 3.2 compatible.
+gstack_hook_normalize_path() {
+  GSTACK_HOOK_PATH="$1"
+  case "$GSTACK_HOOK_PATH" in
+    [A-Za-z]:[\\/]*|[A-Za-z]:|\\\\[!\\]*) ;;
+    *) [ "$GSTACK_HOOK_IS_WINDOWS" = 1 ] || return 0 ;;
+  esac
+  GSTACK_HOOK_PATH="${GSTACK_HOOK_PATH//\\//}"
+  case "$GSTACK_HOOK_PATH" in
+    [A-Za-z]:/*|[A-Za-z]:)
+      _ghnp_d="${GSTACK_HOOK_PATH%%:*}"
+      _ghnp_pre="${_GSTACK_HOOK_AZ_UPPER%%"$_ghnp_d"*}"
+      [ "$_ghnp_pre" = "$_GSTACK_HOOK_AZ_UPPER" ] || _ghnp_d="${_GSTACK_HOOK_AZ_LOWER:${#_ghnp_pre}:1}"
+      GSTACK_HOOK_PATH="/$_ghnp_d${GSTACK_HOOK_PATH#?:}"
+      ;;
+    /cygdrive/[A-Za-z]/*|/cygdrive/[A-Za-z]) GSTACK_HOOK_PATH="${GSTACK_HOOK_PATH#/cygdrive}" ;;
+  esac
+  return 0
+}
+
 # gstack_hook_json_string TEXT
 #   Prints TEXT as a JSON string literal (surrounding quotes included),
 #   encoding quotes, backslashes, control characters and newlines. Never build

codex/SKILL.md

@@ -491,7 +491,7 @@ fi
 if ! _gstack_codex_auth_probe >/dev/null; then
   _gstack_codex_log_event "codex_auth_failed"
   echo "AUTH_FAILED"
-else
+elif _gstack_codex_sandbox_preflight; then   # free; Linux only
   _gstack_codex_model_probe   # ~10s round trip on first run, cached 1h
 fi
 _gstack_codex_version_check   # warns if known-bad, non-blocking
@@ -505,12 +505,18 @@ If the output contains `AUTH_FAILED`, stop and tell the user:
 If the output contains `MODEL_UNUSABLE`, stop — the selected model (named with its
 source on the `CODEX_MODEL:` line) is invalid or the account cannot use it. Relay the
 probe's HINT lines and
-follow the "Model not supported (HTTP 400)" recovery steps in
+follow the "Model not supported (HTTP 400 or 404)" recovery steps in
 `## Error Handling` below. Running the modes anyway just burns four
 invocations on the same 400.
 
-`MODEL_PROBE_INCONCLUSIVE` is non-blocking (timeout/transient network): pass
-the warning through and continue.
+If the output contains `CODEX_SANDBOX: unavailable`, stop: Codex's sandbox cannot
+start here, so every command it runs would fail and its review would read nothing.
+Relay the `Codex outside review unavailable: ...` line verbatim, including its fix.
+No paid call was made.
+
+`MODEL_PROBE_INCONCLUSIVE` is non-blocking (timeout/transient network): report
+`CODEX_MODE: unverified`, pass the warning through and continue; the mode's own
+validator still decides the result.
 
 If the version check printed a `WARN:` line, pass it through to the user verbatim
 (non-blocking — Codex may still work, but the user should upgrade).
@@ -586,8 +592,8 @@ Every prompt sent to Codex MUST be prefixed with this boundary instruction:
 
 This applies to Challenge mode (prompt) and Consult mode (persona prompt), and to the
 custom-instructions path of Review mode — all three use `codex exec`, which still takes
-a free-form prompt argument. It does **not** apply to the default scoped `codex review`
-call in Step 2A: that command is invoked with **no prompt argument at all** (see "Scope
+a free-form prompt (fed on stdin with `codex exec -`, so size and quoting never break it). It does **not** apply to the default scoped `codex review`
+call in Step 2A: that command is invoked with **no prompt at all** (see "Scope
 flags exclude the prompt argument" in the Review mode section), so there is nowhere to put the preamble. That
 is acceptable — `codex review --base` hands the model a pre-computed diff rather than
 turning it loose on the filesystem, so the rabbit-hole risk the boundary guards against
@@ -820,11 +826,14 @@ If token count is not available, display: `Tokens: unknown`
   missing or wrong. A prompt-only `codex review` defaults to uncommitted changes, so a
   clean working tree reads as an empty review even when `<base>...HEAD` is large. Confirm
   `--base <base>` is actually on the command line.
-- **Model not supported (HTTP 400):** stderr shows
+- **Model not supported (HTTP 400 or 404):** stderr shows
   `The '<model>' model is not supported when using Codex with a ChatGPT account`
-  (a `status: 400` / `invalid_request_error` naming a model). This is a
-  model-entitlement problem, not an auth or network failure, and the auth probe
-  cannot catch it. Recovery, in order:
+  (a `status: 400` / `invalid_request_error` naming a model), or
+  `404 Not Found: The model '<model>' does not exist or you do not have access to it`
+  (a retired model; a bare 404 usually means a custom provider's `base_url` is wrong).
+  `requires a newer version of Codex` means the CLI is too old: upgrade it instead.
+  None of these is an auth or network failure, and the auth probe cannot catch them.
+  Recovery, in order:
   1. Read the `CODEX_MODEL:` line: it names the model and where it came from.
   2. Fix that source: name another model for this request, update
      `GSTACK_CODEX_MODEL`, or change `model` (or `review_model`) in the Codex
@@ -832,6 +841,9 @@ If token count is not available, display: `Tokens: unknown`
      them to a model the account can use.
   3. If Codex printed `[notice.model_migrations]`, use that replacement model.
   Never present this as a model stall or a PASS — it is a fail-closed gate result.
+- **`VERDICT: unavailable`:** the shared validator found the run did not execute (for
+  example `Codex's sandbox could not start here`). Relay its line and fix verbatim; it is
+  missing coverage, never a PASS. Details: `docs/troubleshooting.md` in the gstack checkout.
 - **Empty response:** If `$TMPRESP` is empty or doesn't exist, tell the user:
   "Codex returned no response. Check stderr for errors."
 - **Session resume failure:** If resume fails, delete the session file and start fresh.
@@ -840,7 +852,8 @@ If token count is not available, display: `Tokens: unknown`
 
 ## Important Rules
 
-- **Never modify files.** This skill is read-only. Codex runs in read-only sandbox mode.
+- **Never modify files.** This skill is read-only. Codex runs in read-only sandbox mode
+  (full access only when the user exported `GSTACK_CODEX_NO_SANDBOX=1`; it warns on every use).
 - **Present output verbatim.** Do not truncate, summarize, or editorialize Codex's output
   before showing it. Show it in full inside the CODEX SAYS block.
 - **Add synthesis after, not instead of.** Any Claude commentary comes after the full output.

codex/SKILL.md.tmpl

@@ -83,7 +83,7 @@ source ~/.claude/skills/gstack/bin/gstack-codex-probe
 if ! _gstack_codex_auth_probe >/dev/null; then
   _gstack_codex_log_event "codex_auth_failed"
   echo "AUTH_FAILED"
-else
+elif _gstack_codex_sandbox_preflight; then   # free; Linux only
   _gstack_codex_model_probe   # ~10s round trip on first run, cached 1h
 fi
 _gstack_codex_version_check   # warns if known-bad, non-blocking
@@ -97,12 +97,18 @@ If the output contains `AUTH_FAILED`, stop and tell the user:
 If the output contains `MODEL_UNUSABLE`, stop — the selected model (named with its
 source on the `CODEX_MODEL:` line) is invalid or the account cannot use it. Relay the
 probe's HINT lines and
-follow the "Model not supported (HTTP 400)" recovery steps in
+follow the "Model not supported (HTTP 400 or 404)" recovery steps in
 `## Error Handling` below. Running the modes anyway just burns four
 invocations on the same 400.
 
-`MODEL_PROBE_INCONCLUSIVE` is non-blocking (timeout/transient network): pass
-the warning through and continue.
+If the output contains `CODEX_SANDBOX: unavailable`, stop: Codex's sandbox cannot
+start here, so every command it runs would fail and its review would read nothing.
+Relay the `Codex outside review unavailable: ...` line verbatim, including its fix.
+No paid call was made.
+
+`MODEL_PROBE_INCONCLUSIVE` is non-blocking (timeout/transient network): report
+`CODEX_MODE: unverified`, pass the warning through and continue; the mode's own
+validator still decides the result.
 
 If the version check printed a `WARN:` line, pass it through to the user verbatim
 (non-blocking — Codex may still work, but the user should upgrade).
@@ -178,8 +184,8 @@ Every prompt sent to Codex MUST be prefixed with this boundary instruction:
 
 This applies to Challenge mode (prompt) and Consult mode (persona prompt), and to the
 custom-instructions path of Review mode — all three use `codex exec`, which still takes
-a free-form prompt argument. It does **not** apply to the default scoped `codex review`
-call in Step 2A: that command is invoked with **no prompt argument at all** (see "Scope
+a free-form prompt (fed on stdin with `codex exec -`, so size and quoting never break it). It does **not** apply to the default scoped `codex review`
+call in Step 2A: that command is invoked with **no prompt at all** (see "Scope
 flags exclude the prompt argument" in the Review mode section), so there is nowhere to put the preamble. That
 is acceptable — `codex review --base` hands the model a pre-computed diff rather than
 turning it loose on the filesystem, so the rabbit-hole risk the boundary guards against
@@ -287,11 +293,14 @@ If token count is not available, display: `Tokens: unknown`
   missing or wrong. A prompt-only `codex review` defaults to uncommitted changes, so a
   clean working tree reads as an empty review even when `<base>...HEAD` is large. Confirm
   `--base <base>` is actually on the command line.
-- **Model not supported (HTTP 400):** stderr shows
+- **Model not supported (HTTP 400 or 404):** stderr shows
   `The '<model>' model is not supported when using Codex with a ChatGPT account`
-  (a `status: 400` / `invalid_request_error` naming a model). This is a
-  model-entitlement problem, not an auth or network failure, and the auth probe
-  cannot catch it. Recovery, in order:
+  (a `status: 400` / `invalid_request_error` naming a model), or
+  `404 Not Found: The model '<model>' does not exist or you do not have access to it`
+  (a retired model; a bare 404 usually means a custom provider's `base_url` is wrong).
+  `requires a newer version of Codex` means the CLI is too old: upgrade it instead.
+  None of these is an auth or network failure, and the auth probe cannot catch them.
+  Recovery, in order:
   1. Read the `CODEX_MODEL:` line: it names the model and where it came from.
   2. Fix that source: name another model for this request, update
      `GSTACK_CODEX_MODEL`, or change `model` (or `review_model`) in the Codex
@@ -299,6 +308,9 @@ If token count is not available, display: `Tokens: unknown`
      them to a model the account can use.
   3. If Codex printed `[notice.model_migrations]`, use that replacement model.
   Never present this as a model stall or a PASS — it is a fail-closed gate result.
+- **`VERDICT: unavailable`:** the shared validator found the run did not execute (for
+  example `Codex's sandbox could not start here`). Relay its line and fix verbatim; it is
+  missing coverage, never a PASS. Details: `docs/troubleshooting.md` in the gstack checkout.
 - **Empty response:** If `$TMPRESP` is empty or doesn't exist, tell the user:
   "Codex returned no response. Check stderr for errors."
 - **Session resume failure:** If resume fails, delete the session file and start fresh.
@@ -307,7 +319,8 @@ If token count is not available, display: `Tokens: unknown`
 
 ## Important Rules
 
-- **Never modify files.** This skill is read-only. Codex runs in read-only sandbox mode.
+- **Never modify files.** This skill is read-only. Codex runs in read-only sandbox mode
+  (full access only when the user exported `GSTACK_CODEX_NO_SANDBOX=1`; it warns on every use).
 - **Present output verbatim.** Do not truncate, summarize, or editorialize Codex's output
   before showing it. Show it in full inside the CODEX SAYS block.
 - **Add synthesis after, not instead of.** Any Claude commentary comes after the full output.

codex/sections/challenge-mode.md

@@ -20,6 +20,7 @@ With focus (e.g., "security"):
 Review the changes on this branch against the base branch. Run `git diff origin/<base>` to see the diff. Focus specifically on SECURITY. Your job is to find every way an attacker could exploit this code. Think about injection vectors, auth bypasses, privilege escalation, data exposure, and timing attacks. Be adversarial."
 
 2. Run codex exec with **JSONL output** to capture reasoning traces and tool calls.
+Replace `<prompt>` with the full prompt from step 1, verbatim and unescaped; Codex reads it on stdin.
 Use `timeout: 600000` on the Bash call (the tool's maximum) — the gate sits ABOVE the
 540s wrapper so the wrapper fires first, ends Codex, and prints its explicit stall message:
 
@@ -35,9 +36,15 @@ fi
 # Fix 1+2: wrap with timeout (gtimeout/timeout fallback chain via probe helper),
 # capture stderr to $TMPERR for auth error detection (was: 2>/dev/null).
 [ -n "${TMPERR:-}" ] || TMPERR=$(mktemp "$TMP_ROOT/codex-err-XXXXXX") || { echo "ERROR: mktemp failed in TMP_ROOT=$TMP_ROOT; not running codex without its temp file" >&2; exit 1; }
+TMPRESP=$(mktemp "$TMP_ROOT/codex-resp-XXXXXX") || { echo "ERROR: mktemp failed in TMP_ROOT=$TMP_ROOT; not running codex without its temp file" >&2; exit 1; }
 source ~/.claude/skills/gstack/bin/gstack-codex-probe || exit 1
 _gstack_codex_select_model exec || exit 1
-_gstack_codex_timeout_wrapper 540 codex exec "<prompt>" -C "$_REPO_ROOT" -s read-only -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="high"' -c 'web_search="cached"' --json < /dev/null 2>"$TMPERR" | PYTHONUNBUFFERED=1 "$PYTHON_CMD" -u -c "
+_PROMPT_FILE=$(mktemp "$TMP_ROOT/codex-prompt-XXXXXX") || { echo "ERROR: mktemp failed in TMP_ROOT=$TMP_ROOT; not running codex without its temp file" >&2; exit 1; }
+# The prompt goes to Codex on stdin (codex exec -), verbatim: no shell quoting, no argv size limit.
+cat > "$_PROMPT_FILE" <<'CODEX_PROMPT_END'
+<prompt>
+CODEX_PROMPT_END
+_gstack_codex_timeout_wrapper 540 codex exec - -C "$_REPO_ROOT" -s "${_GSTACK_CODEX_SANDBOX:?}" -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="high"' -c 'web_search="cached"' --json -o "$TMPRESP" < "$_PROMPT_FILE" 2>"$TMPERR" | tee "$TMPRESP.events" | PYTHONUNBUFFERED=1 "$PYTHON_CMD" -u -c "
 import sys, json
 turn_completed_count = 0
 turn_failed = False
@@ -94,8 +101,14 @@ if grep -qiE "auth|login|unauthorized" "$TMPERR" 2>/dev/null; then
   echo "[codex auth error] $(head -1 "$TMPERR")"
   _gstack_codex_log_event "codex_auth_failed"
 fi
+bun ~/.claude/skills/gstack/lib/outside-review-result.ts --label 'Codex challenge' --exit "$_CODEX_EXIT" --stderr "$TMPERR" --events "$TMPRESP.events" execution "$TMPRESP"
+rm -f "$TMPRESP" "$TMPRESP.events" "$_PROMPT_FILE"
 ```
 
+`VERDICT: unavailable` means the challenge did not run (its line names why, such as a
+sandbox that could not start): say so and present no findings from it. Otherwise
+present the output below.
+
 This parses codex's JSONL events to extract reasoning traces, tool calls, and the final
 response. The `[codex thinking]` lines show what codex reasoned through before its answer.
 

codex/sections/challenge-mode.md.tmpl

@@ -18,6 +18,7 @@ With focus (e.g., "security"):
 Review the changes on this branch against the base branch. Run `git diff origin/<base>` to see the diff. Focus specifically on SECURITY. Your job is to find every way an attacker could exploit this code. Think about injection vectors, auth bypasses, privilege escalation, data exposure, and timing attacks. Be adversarial."
 
 2. Run codex exec with **JSONL output** to capture reasoning traces and tool calls.
+Replace `<prompt>` with the full prompt from step 1, verbatim and unescaped; Codex reads it on stdin.
 Use `timeout: 600000` on the Bash call (the tool's maximum) — the gate sits ABOVE the
 540s wrapper so the wrapper fires first, ends Codex, and prints its explicit stall message:
 
@@ -33,9 +34,15 @@ fi
 # Fix 1+2: wrap with timeout (gtimeout/timeout fallback chain via probe helper),
 # capture stderr to $TMPERR for auth error detection (was: 2>/dev/null).
 [ -n "${TMPERR:-}" ] || TMPERR=$(mktemp "$TMP_ROOT/codex-err-XXXXXX") || { echo "ERROR: mktemp failed in TMP_ROOT=$TMP_ROOT; not running codex without its temp file" >&2; exit 1; }
+TMPRESP=$(mktemp "$TMP_ROOT/codex-resp-XXXXXX") || { echo "ERROR: mktemp failed in TMP_ROOT=$TMP_ROOT; not running codex without its temp file" >&2; exit 1; }
 source ~/.claude/skills/gstack/bin/gstack-codex-probe || exit 1
 _gstack_codex_select_model exec || exit 1
-_gstack_codex_timeout_wrapper 540 codex exec "<prompt>" -C "$_REPO_ROOT" -s read-only {{CODEX_MODEL_CONFIG_FLAG}} -c 'model_reasoning_effort="high"' {{CODEX_WEB_SEARCH_FLAG}} --json < /dev/null 2>"$TMPERR" | PYTHONUNBUFFERED=1 "$PYTHON_CMD" -u -c "
+_PROMPT_FILE=$(mktemp "$TMP_ROOT/codex-prompt-XXXXXX") || { echo "ERROR: mktemp failed in TMP_ROOT=$TMP_ROOT; not running codex without its temp file" >&2; exit 1; }
+# The prompt goes to Codex on stdin (codex exec -), verbatim: no shell quoting, no argv size limit.
+cat > "$_PROMPT_FILE" <<'CODEX_PROMPT_END'
+<prompt>
+CODEX_PROMPT_END
+_gstack_codex_timeout_wrapper 540 codex exec - -C "$_REPO_ROOT" -s "${_GSTACK_CODEX_SANDBOX:?}" {{CODEX_MODEL_CONFIG_FLAG}} -c 'model_reasoning_effort="high"' {{CODEX_WEB_SEARCH_FLAG}} --json -o "$TMPRESP" < "$_PROMPT_FILE" 2>"$TMPERR" | tee "$TMPRESP.events" | PYTHONUNBUFFERED=1 "$PYTHON_CMD" -u -c "
 import sys, json
 turn_completed_count = 0
 turn_failed = False
@@ -92,8 +99,14 @@ if grep -qiE "auth|login|unauthorized" "$TMPERR" 2>/dev/null; then
   echo "[codex auth error] $(head -1 "$TMPERR")"
   _gstack_codex_log_event "codex_auth_failed"
 fi
+bun ~/.claude/skills/gstack/lib/outside-review-result.ts --label 'Codex challenge' --exit "$_CODEX_EXIT" --stderr "$TMPERR" --events "$TMPRESP.events" execution "$TMPRESP"
+rm -f "$TMPRESP" "$TMPRESP.events" "$_PROMPT_FILE"
 ```
 
+`VERDICT: unavailable` means the challenge did not run (its line names why, such as a
+sandbox that could not start): say so and present no findings from it. Otherwise
+present the output below.
+
 This parses codex's JSONL events to extract reasoning traces, tool calls, and the final
 response. The `[codex thinking]` lines show what codex reasoned through before its answer.
 

codex/sections/consult-mode.md

@@ -62,7 +62,8 @@ For non-plan consult prompts (user typed `/codex <question>`), still prepend the
 
 <user's question>"
 
-4. Run codex exec with **JSONL output** to capture reasoning traces. Use
+4. Run codex exec with **JSONL output** to capture reasoning traces. Replace `<prompt>`
+with the full prompt, verbatim and unescaped; Codex reads it on stdin. Use
 `timeout: 600000` on the Bash call (the tool's maximum; for both new and resumed
 sessions) — the gate sits ABOVE the 540s wrapper so the wrapper fires first, ends Codex,
 and prints its explicit stall message:
@@ -80,7 +81,12 @@ fi
 source ~/.claude/skills/gstack/bin/gstack-codex-probe || exit 1
 _gstack_codex_select_model exec || exit 1
 # Fix 1: wrap with timeout (gtimeout/timeout fallback chain via probe helper)
-_gstack_codex_timeout_wrapper 540 codex exec "<prompt>" -C "$_REPO_ROOT" -s read-only -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="medium"' -c 'web_search="cached"' --json < /dev/null 2>"$TMPERR" | PYTHONUNBUFFERED=1 "$PYTHON_CMD" -u -c "
+_PROMPT_FILE=$(mktemp "$TMP_ROOT/codex-prompt-XXXXXX") || { echo "ERROR: mktemp failed in TMP_ROOT=$TMP_ROOT; not running codex without its temp file" >&2; exit 1; }
+# The prompt goes to Codex on stdin (codex exec -), verbatim: no shell quoting, no argv size limit.
+cat > "$_PROMPT_FILE" <<'CODEX_PROMPT_END'
+<prompt>
+CODEX_PROMPT_END
+_gstack_codex_timeout_wrapper 540 codex exec - -C "$_REPO_ROOT" -s "${_GSTACK_CODEX_SANDBOX:?}" -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="medium"' -c 'web_search="cached"' --json -o "$TMPRESP" < "$_PROMPT_FILE" 2>"$TMPERR" | tee "$TMPRESP.events" | PYTHONUNBUFFERED=1 "$PYTHON_CMD" -u -c "
 import sys, json
 turn_completed_count = 0
 turn_failed = False
@@ -135,6 +141,8 @@ elif [ "$_CODEX_EXIT" != "0" ]; then
   head -20 "$TMPERR" 2>/dev/null | sed 's/^/  /' || true
   _gstack_codex_log_event "codex_nonzero_exit" "consult:$_CODEX_EXIT"
 fi
+bun ~/.claude/skills/gstack/lib/outside-review-result.ts --label 'Codex consult' --exit "$_CODEX_EXIT" --stderr "$TMPERR" --events "$TMPRESP.events" execution "$TMPRESP"
+rm -f "$_PROMPT_FILE"
 ```
 
 **Session-cost reality (measured):** every `codex exec` call — resumed
@@ -157,7 +165,12 @@ cd "$_REPO_ROOT" || exit 1
 source ~/.claude/skills/gstack/bin/gstack-codex-probe || exit 1
 _gstack_codex_select_model exec || exit 1
 # Fix 1: wrap with timeout (gtimeout/timeout fallback chain via probe helper)
-_gstack_codex_timeout_wrapper 540 codex exec resume <session-id> "<prompt>" -c 'sandbox_mode="read-only"' -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="medium"' -c 'web_search="cached"' --json < /dev/null 2>"$TMPERR" | PYTHONUNBUFFERED=1 "$PYTHON_CMD" -u -c "
+_PROMPT_FILE=$(mktemp "$TMP_ROOT/codex-prompt-XXXXXX") || { echo "ERROR: mktemp failed in TMP_ROOT=$TMP_ROOT; not running codex without its temp file" >&2; exit 1; }
+# The prompt goes to Codex on stdin (codex exec -), verbatim: no shell quoting, no argv size limit.
+cat > "$_PROMPT_FILE" <<'CODEX_PROMPT_END'
+<prompt>
+CODEX_PROMPT_END
+_gstack_codex_timeout_wrapper 540 codex exec resume <session-id> - -c "sandbox_mode=\"${_GSTACK_CODEX_SANDBOX:?}\"" -c "model=\"${_GSTACK_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'model_reasoning_effort="medium"' -c 'web_search="cached"' --json -o "$TMPRESP" < "$_PROMPT_FILE" 2>"$TMPERR" | tee "$TMPRESP.events" | PYTHONUNBUFFERED=1 "$PYTHON_CMD" -u -c "
 <same python streaming parser as above, with flush=True on all print() calls>
 "
 # Fix 1: same hang detection pattern as new-session block
@@ -173,8 +186,14 @@ elif [ "$_CODEX_EXIT" != "0" ]; then
   head -20 "$TMPERR" 2>/dev/null | sed 's/^/  /' || true
   _gstack_codex_log_event "codex_nonzero_exit" "consult-resume:$_CODEX_EXIT"
 fi
+bun ~/.claude/skills/gstack/lib/outside-review-result.ts --label 'Codex consult' --exit "$_CODEX_EXIT" --stderr "$TMPERR" --events "$TMPRESP.events" execution "$TMPRESP"
+rm -f "$_PROMPT_FILE"
 ```
 
+`VERDICT: unavailable` from either block means Codex did not answer from a working
+environment (its line names why, such as a sandbox that could not start): relay that
+line and do not present the output as Codex's answer.
+
 5. Capture session ID from the streamed output. The parser prints `SESSION_ID:<id>`
    from the `thread.started` event. Save it for follow-ups:
 ```bash

codex/sections/consult-mode.md.tmpl

@@ -60,7 +60,8 @@ For non-plan consult prompts (user typed `/codex <question>`), still prepend the
 
 <user's question>"
 
-4. Run codex exec with **JSONL output** to capture reasoning traces. Use
+4. Run codex exec with **JSONL output** to capture reasoning traces. Replace `<prompt>`
+with the full prompt, verbatim and unescaped; Codex reads it on stdin. Use
 `timeout: 600000` on the Bash call (the tool's maximum; for both new and resumed
 sessions) — the gate sits ABOVE the 540s wrapper so the wrapper fires first, ends Codex,
 and prints its explicit stall message:
@@ -78,7 +79,12 @@ fi
 source ~/.claude/skills/gstack/bin/gstack-codex-probe || exit 1
 _gstack_codex_select_model exec || exit 1
 # Fix 1: wrap with timeout (gtimeout/timeout fallback chain via probe helper)
-_gstack_codex_timeout_wrapper 540 codex exec "<prompt>" -C "$_REPO_ROOT" -s read-only {{CODEX_MODEL_CONFIG_FLAG}} -c 'model_reasoning_effort="medium"' {{CODEX_WEB_SEARCH_FLAG}} --json < /dev/null 2>"$TMPERR" | PYTHONUNBUFFERED=1 "$PYTHON_CMD" -u -c "
+_PROMPT_FILE=$(mktemp "$TMP_ROOT/codex-prompt-XXXXXX") || { echo "ERROR: mktemp failed in TMP_ROOT=$TMP_ROOT; not running codex without its temp file" >&2; exit 1; }
+# The prompt goes to Codex on stdin (codex exec -), verbatim: no shell quoting, no argv size limit.
+cat > "$_PROMPT_FILE" <<'CODEX_PROMPT_END'
+<prompt>
+CODEX_PROMPT_END
+_gstack_codex_timeout_wrapper 540 codex exec - -C "$_REPO_ROOT" -s "${_GSTACK_CODEX_SANDBOX:?}" {{CODEX_MODEL_CONFIG_FLAG}} -c 'model_reasoning_effort="medium"' {{CODEX_WEB_SEARCH_FLAG}} --json -o "$TMPRESP" < "$_PROMPT_FILE" 2>"$TMPERR" | tee "$TMPRESP.events" | PYTHONUNBUFFERED=1 "$PYTHON_CMD" -u -c "
 import sys, json
 turn_completed_count = 0
 turn_failed = False
@@ -133,6 +139,8 @@ elif [ "$_CODEX_EXIT" != "0" ]; then
   head -20 "$TMPERR" 2>/dev/null | sed 's/^/  /' || true
   _gstack_codex_log_event "codex_nonzero_exit" "consult:$_CODEX_EXIT"
 fi
+bun ~/.claude/skills/gstack/lib/outside-review-result.ts --label 'Codex consult' --exit "$_CODEX_EXIT" --stderr "$TMPERR" --events "$TMPRESP.events" execution "$TMPRESP"
+rm -f "$_PROMPT_FILE"
 ```
 
 **Session-cost reality (measured):** every `codex exec` call — resumed
@@ -155,7 +163,12 @@ cd "$_REPO_ROOT" || exit 1
 source ~/.claude/skills/gstack/bin/gstack-codex-probe || exit 1
 _gstack_codex_select_model exec || exit 1
 # Fix 1: wrap with timeout (gtimeout/timeout fallback chain via probe helper)
-_gstack_codex_timeout_wrapper 540 codex exec resume <session-id> "<prompt>" -c 'sandbox_mode="read-only"' {{CODEX_MODEL_CONFIG_FLAG}} -c 'model_reasoning_effort="medium"' {{CODEX_WEB_SEARCH_FLAG}} --json < /dev/null 2>"$TMPERR" | PYTHONUNBUFFERED=1 "$PYTHON_CMD" -u -c "
+_PROMPT_FILE=$(mktemp "$TMP_ROOT/codex-prompt-XXXXXX") || { echo "ERROR: mktemp failed in TMP_ROOT=$TMP_ROOT; not running codex without its temp file" >&2; exit 1; }
+# The prompt goes to Codex on stdin (codex exec -), verbatim: no shell quoting, no argv size limit.
+cat > "$_PROMPT_FILE" <<'CODEX_PROMPT_END'
+<prompt>
+CODEX_PROMPT_END
+_gstack_codex_timeout_wrapper 540 codex exec resume <session-id> - -c "sandbox_mode=\"${_GSTACK_CODEX_SANDBOX:?}\"" {{CODEX_MODEL_CONFIG_FLAG}} -c 'model_reasoning_effort="medium"' {{CODEX_WEB_SEARCH_FLAG}} --json -o "$TMPRESP" < "$_PROMPT_FILE" 2>"$TMPERR" | tee "$TMPRESP.events" | PYTHONUNBUFFERED=1 "$PYTHON_CMD" -u -c "
 <same python streaming parser as above, with flush=True on all print() calls>
 "
 # Fix 1: same hang detection pattern as new-session block
@@ -171,8 +184,14 @@ elif [ "$_CODEX_EXIT" != "0" ]; then
   head -20 "$TMPERR" 2>/dev/null | sed 's/^/  /' || true
   _gstack_codex_log_event "codex_nonzero_exit" "consult-resume:$_CODEX_EXIT"
 fi
+bun ~/.claude/skills/gstack/lib/outside-review-result.ts --label 'Codex consult' --exit "$_CODEX_EXIT" --stderr "$TMPERR" --events "$TMPRESP.events" execution "$TMPRESP"
+rm -f "$_PROMPT_FILE"
 ```
 
+`VERDICT: unavailable` from either block means Codex did not answer from a working
+environment (its line names why, such as a sandbox that could not start): relay that
+line and do not present the output as Codex's answer.
+
 5. Capture session ID from the streamed output. The parser prints `SESSION_ID:<id>`
    from the `thread.started` event. Save it for follow-ups:
 ```bash