Skip to content

fix(memory-ingest): refuse to advance state when gbrain imports fewer pages than staged - #2486

Closed
Charles-Grant wants to merge 1 commit into
garrytan:mainfrom
Charles-Grant:fix/memory-ingest-verify-import-landed
Closed

Charles-Grant wants to merge 1 commit into
garrytan:mainfrom
Charles-Grant:fix/memory-ingest-verify-import-landed

Conversation

@Charles-Grant

Copy link
Copy Markdown

Summary

gstack-memory-ingest can report N written while writing nothing to the brain, and mark every one of those sessions as ingested in state — so no later run ever retries them. On the install where I found this, state claimed 1013 sessions ingested while the brain held 391 pages. Transcripts from ~2 days were gone with no error anywhere.

This PR makes that failure loud instead of silent. It does not change the happy path.

The bug

written is counted from the staged set, never reconciled against gbrain's own totals:

for (const p of prep.prepared) {
  if (failedSources.has(p.source_path)) continue;
  state.sessions[p.source_path] = {...};   // marked ingested
  written++;                                // counted as written
}

failedSources comes from readNewFailures(), which reads per-file failures out of sync-failures.jsonl. When gbrain import collects zero files, there are no per-file failures to report — gbrain never saw them — so that set is empty, every prepared file is state-recorded, and the pass reports success.

importJson.imported holds the truth. It's used in exactly one place: the console.error summary a few lines below. It is never compared to anything.

Why it triggers in practice

gbrain import honours .gitignore. bin/gstack-artifacts-init writes .gitignore = "*" into $GSTACK_HOME:

bin/gstack-artifacts-init:21   #   2. Write .gitignore = "*"  (ignore everything; allowlist is explicit)
bin/gstack-artifacts-init:213  cat > "$GSTACK_HOME/.gitignore" <<'EOF'

makeStagingDir() stages into $GSTACK_HOME/.staging-ingest-<pid>-<ts>/. So on any machine that has run artifacts-init, every staged file is invisible to collect_files, forever.

Only affects the local-gbrain path. In remote-http MCP mode the code takes makePersistentTranscriptDir() and never calls gbrain import, so those users don't hit it.

Clean-room reproduction

No reference to my setup — reproducible on a fresh checkout in about two minutes:

export H=$(mktemp -d)
bin/gstack-artifacts-init --remote "file://$(mktemp -d)/remote.git"   # GSTACK_HOME=$H
cat "$H/.gitignore"        # => *

D="$H/.staging-ingest-1-1"; mkdir -p "$D/transcripts/x"
printf -- '---\ntitle: probe\n---\nbody\n' > "$D/transcripts/x/probe.md"

gbrain import "$D" --no-embed        # Found 0 markdown files   <-- silent loss
cp -R "$D" /tmp/control
gbrain import /tmp/control --no-embed # Found 1 markdown files  <-- control

Same bytes, same filenames, same directory shape. The only variable is whether the path sits inside an artifacts-init home.

The fix

Reconcile imported + skipped against prepared - failed (skipped is a content-hash no-op, which is a successful landing). On a shortfall: error, return written: 0, and leave state untouched so the next run re-prepares and gbrain's content_hash dedup short-circuits the re-import.

This mirrors the existing "exited 0 but emitted no parseable --json payload. Refusing to advance state." branch directly above — same intent, one failure mode further along.

The error names the likely cause and the staging path, so the next person sees it in one line rather than bisecting a 70KB file.

Test

test/gstack-memory-ingest.test.ts gains a collectNothing option on the existing installFakeGbrain shim: gbrain exits 0, reports imported=0/total_files=0, and writes no sync-failures.jsonl entry — the exact silent-loss shape.

The test asserts the state file stays empty. It fails without the source change (verified by reverting the fix and re-running).

bun test test/gstack-memory-ingest.test.ts   # 24 pass, 0 fail
bun test                                      # full free suite, exit 0

Notes for the maintainer

  • No VERSION bump or CHANGELOG entry included — those collide with whatever lands first, and your CLAUDE.md scopes them to /ship. Happy to add both at whatever version you want this to land at, just say the word.
  • The deeper fix is arguably to stop staging inside $GSTACK_HOME — ephemeral scratch in a directory that syncs to a GitHub artifacts repo is uncomfortable regardless, since transcripts can carry PII. I left that alone: checkOwnedStagingDir() hard-requires "direct child of $GSTACK_HOME", so moving it means changing that contract and its tests. Reconciling the counts makes the failure visible either way, and seemed like the right smallest first step. Glad to follow up if you'd prefer the relocation.
  • No test asserted that staged pages actually land after import, which is how this shipped. The new one closes that gap narrowly.
  • This comes from a fork, so the eval/E2E CI jobs won't receive base-repo secrets and will fail on empty-env auth. The free suite (bun test) is unaffected and passes. Push the branch to the base repo if you want a full green run.

… pages than staged

`written` was counted from the staged set, never reconciled against gbrain's
own `imported`/`skipped` totals. readNewFailures() only surfaces PER-FILE
failures, so when `gbrain import` collects zero files it writes nothing to
sync-failures.jsonl, failedSources comes back empty, and every prepared file
is state-recorded as ingested. The pass reports "N written" while the brain
gained nothing, and because state now says "done", no later run retries.
Silent, permanent data loss.

This reproduces on any machine that has run `gstack-artifacts-init`: it
writes `.gitignore = "*"` into $GSTACK_HOME, `gbrain import` honours
.gitignore, and makeStagingDir() stages under $GSTACK_HOME — so collect_files
returns 0 for every batch. Observed on a real install: 1013 sessions marked
ingested in state, 391 pages actually in the brain.

Reconcile imported+skipped against prepared-minus-failed. On a shortfall,
error out and return written:0 without touching state, so the next run
re-prepares and gbrain's content_hash dedup short-circuits the re-import.
Mirrors the existing "exited 0 but emitted no parseable --json payload"
branch directly above.

Regression test asserts the state file stays empty when gbrain reports
collecting nothing — it fails without this change.
@trunk-io

trunk-io Bot commented Aug 8, 2026

Copy link
Copy Markdown

Merging to main in this repository is managed by Trunk.

  • To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

garrytan added a commit that referenced this pull request Aug 15, 2026
…~50 community PRs absorbed (#2571)

* fix(hooks): nest freeze/careful permissionDecision under hookSpecificOutput

Claude Code ignores a top-level permissionDecision, so the /freeze deny and
/careful ask guards silently allowed everything. Nest both under
hookSpecificOutput with permissionDecisionReason, update the shape-blind
tests to pin the nested form, and document the constraint in both skill
templates (regen included).

Closes half of #1459 (freeze enforcement chain).

Contributed by @jawadakram20 (PR #2331; team-init hunk deferred to the
dedicated team-init fix).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(team-init): required-mode hook blocks with nested schema + exit 2

The generated check-gstack.sh emitted a flat permissionDecision payload and
exited 0, which Claude Code ignores — required mode enforced nothing. The
generated hook now nests the deny under hookSpecificOutput and exits 2 so
the block holds even if the JSON schema drifts again. Adds a temp-repo
regression test that runs the generated hook under both installed and
missing-gstack homes.

Fixes #2413, #2296.

Contributed by @Masashi-Ono0611 (PR #2423).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(careful): close three check-careful bypasses via real JSON extraction

The grep-based command extractor stopped at the first escaped quote, so any
quoted argument truncated the command before the pattern checks ran —
`git commit -m "wip" && rm -rf /` was silently allowed. Replace it with a
python3/node JSON parse that fails CLOSED on unreadable payloads, add an
IFS/base64-to-shell obfuscation tripwire, and stop multi-line commands from
riding the single-line safe-exception whitelist (line-based grep would have
approved `rm -rf /` when a later line matched node_modules — a hazard the
real newline decoding exposed).

Contributed by @wtamminga (PR #2426; the -R hunk was dropped — it landed in
v1.61.0.0 — and output shapes updated to the nested hookSpecificOutput form).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(review,autoplan): require explicit run_in_background: false on specialist agents

Claude Code v2.1.198 made subagents run in the background by default, which
inverted the old "do not use the flag" guidance: review-army specialists and
autoplan dual voices silently launched in the background and the merge step
could proceed before they completed — regressing the #497 fix. The generated
guidance now instructs an explicit run_in_background: false, and a static
tripwire fails the free suite if the inert inverted phrasing ever returns to
any generated SKILL.md.

Fixes #2440.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(investigate): anchor the scope-lock freeze hook on $HOME, not CLAUDE_SKILL_DIR

The investigate skill's PreToolUse hooks and Scope Lock probe resolved
check-freeze.sh via ${CLAUDE_SKILL_DIR}, which does not exist when
frontmatter hooks run — the || exit 0 tail then failed open, so the debug
scope boundary silently never engaged (#1871 follow-up). Anchor all four
sites on $HOME/.claude/skills/gstack/ like careful/freeze, and add a static
test asserting no frontmatter command: line in the guard-family skills ever
references CLAUDE_SKILL_DIR again.

Fixes #2469; closes the last live half of #1459 together with the
freeze/careful hookSpecificOutput fix. The broader portable-install-root
rewrite stays #1882 (its own focused PR per the TODOS.md decision).

Reported with a fix by @maxpetrusenkoagent (PR #1873; absorbed narrowly —
the cwd-walk rewrite belongs to #1882).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(redact): scan large diffs in line-aligned slices; stop digit-UUIDs matching as cards/phones

The prepush guard blocked any push whose added lines exceeded the engine's
1 MiB cap with engine.input_too_large — a size error naming no credential —
which trains people onto GSTACK_REDACT_PREPUSH=skip. Scan in 768 KiB
line-aligned slices instead (no pattern is multi-line, so a boundary cannot
bisect a secret); a single oversized line still goes to the engine intact and
fails closed. Also suppress card/phone matches whose span sits ENTIRELY
inside a UUID — digit-only UUID fixtures were 14 of 21 MEDIUM findings on an
ordinary branch, the noise level that stops people reading MEDIUM at all.

Fixes #2304.

Contributed by @luckywenapere (PR #2543).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(redact): block Google OAuth client secrets and Telegram bot tokens at HIGH

GOCSPX-prefixed client secrets and <bot_id>:<35-char> Telegram tokens are
never-publishable credential shapes with unambiguous formats — both now
block at HIGH like the other live-format credentials.

Contributed by @francis-eye (PR #2357).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(redact-prepush): resolve the real push base instead of EMPTY_TREE whole-repo scans

When the remote default branch is not main/master (or origin/HEAD is unset),
the merge-base guess failed and the hook fell back to scanning the ENTIRE
repository as added lines — re-attributing long-pushed secrets to the
current push and, on any real repo, tripping the engine byte cap so the push
blocked having scanned nothing. Derive the base from commits reachable from
no remote-tracking branch, keep the empty-tree path only for genuinely fresh
repos, and split the block message so an unscannable diff is reported as
"could not scan (fail closed)" rather than "credential found — rotate it".

Contributed by @stormeoio (PR #2398).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(redact-prepush): preserve the trailing newline handed to chained pre-push.local

The chaining wrapper captured stdin with $(cat), which strips the trailing
newline — a chained shell hook built on `while read` then never entered its
loop for the final (usually only) ref line and exited 0, failing OPEN. Use
the printf-x sentinel so the byte-exact input reaches the chained hook, with
tests covering both the pass-through and the short-circuit paths.

Contributed by @francis-eye (PR #2358).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(redact-prepush): close the ext-diff, header-lookalike, and ref-parse bypasses

Three ways the pushed diff escaped scanning: (1) a user-level diff.external
or textconv driver replaced the diff with its own output — zero '+' lines,
so the scan saw nothing (now --no-ext-diff --no-textconv); (2) an added
content line whose text begins with "++" renders as "+++…" and the blanket
header skip dropped it (now hunk-aware header detection); (3) a pre-push
ref line that failed to parse was silently skipped, leaving that ref
unscanned (now fails closed with the offending line named).

Minimal reimplementation of the two confirmed bypasses from PR #2498 by
@lubosxyz (the full PR overlaps the chunked-scan work absorbed separately),
plus the unparseable-ref hardening.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(pair-agent): keep the ngrok authtoken out of the transcript and shell argv

The not-authed flow told the user to paste their ngrok authtoken into the
chat so the agent could run `ngrok config add-authtoken` — putting a live
credential in the transcript, tool-call argv, and anything the transcript
syncs to. The user now runs the auth command in their own terminal; the
agent only verifies via `ngrok config check`, and a pasted token triggers a
rotate-and-reauth instruction. A static test pins that no agent-run bash
fence ever contains add-authtoken again.

Fixes #2335.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(update-check): crash emits CHECK_FAILED instead of reading as up-to-date

gstack-update-check signals "up to date" with SILENCE, and it runs under
set -e — so any unguarded mid-script failure exited quietly and was
indistinguishable from a current install. Observed live as a 45-release
silent-staleness incident. An ERR trap (with -E so it propagates into
functions) now emits a CHECK_FAILED sentinel naming the line and status,
and exits 0 so caller `|| true` guards can't eat it. Behavioral tests cover
both the crash and the healthy-silent paths; egress-receipt wiring is
untouched and still pinned by test/egress-receipt-wiring.test.ts.

Fixes #1974. (#2378's HEAD-SHA staleness half was already fixed on main by
the ls-remote + SHA-pinned VERSION resolution — close as already-fixed.)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(deps): bump diff 7.0.0 → 9.0.0 (GHSA-73rr-hh4g-fpgx parsePatch DoS)

The advisory affects diff 6.x–8.0.2. The only API this repo uses is
Diff.diffLines (browse/src/snapshot.ts:571, browse/src/meta-commands.ts:728),
which is unchanged across the major hop; snapshot tests pass against 9.0.0.

Closes #1588.

Contributed by @genisis0x (PR #1599; VERSION collateral stripped, lockfile
regenerated fresh).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci(evals): skip eval jobs deterministically on fork PRs

Fork PRs never receive repository secrets, so every API-calling eval failed
at SDK auth — but only when Docker-cache luck let the jobs start at all,
making fork PRs randomly red or grey. Skip the eval and report jobs
explicitly for fork-origin PRs, keep the image BUILD (validates
Dockerfile.ci changes) without the push a fork token can't perform, and
leave full coverage for same-repo PRs, pushes, and dispatches.

Contributed by @andrey-esipov (PR #2345).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(extension): deny token/port reads to content-script and foreign senders

background.js answered getPort — port, connected state, AND the browse
server auth token — to any sender that passed the type allowlist,
including content scripts running in web-page context and, behind only
the sender.id check, anything without extension-page provenance. The
getToken sender.tab restriction covered getToken alone, and only after
getPort had already handed out the token.

Single decision point now: extension/sender-auth.js classifies each
message type; the eight privileged types (getPort, setPort, getServerUrl,
getToken, fetchRefs, command, sidebar-command, getTabState) require an
own-extension-page sender (chrome-extension://<own id>/ URL, no
sender.tab, own sender.id). Denied senders get { error: 'unauthorized' }
and nothing else — never the token, never the port. Content-script flows
(elementPicked, pickerCancelled, inspectResult, openSidePanel) are
untouched, and the sidepanel/popup keep the getPort token field their
connect path reads. The policy mirrors the v1.63 server-side model:
AUTH_TOKEN is released only to the pinned extension Origin via
POST /extension-token, so the extension must not re-leak it to contexts
the server would never have trusted.

browse/test/extension-sender-auth.test.ts drives the real background.js
onMessage listener under a chrome stub with four sender shapes (own
extension page, own content script, foreign extension id, missing
sender.url) and pins that denied responses carry no token/port fields,
that a denied setPort never persists, that a denied command never
reaches the network, and that the inspector + tab-state flows keep
working. The helper is loaded via importScripts in the classic service
worker and require()-able from bun tests.

Contributed by @punksterlabs (PR #1822; reimplemented against the v1.63 POST /extension-token pinned-origin model).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(update-check): fixture links gstack-egress-lib.sh — all 38 tests failed on main

v1.63.0.0 made bin/gstack-update-check source bin/gstack-egress-lib.sh
unconditionally, but the test fixture's GSTACK_DIR only linked gstack-config
— every test died at the source line (0/38 pass on pristine main,
verified). The suite-truncation bug hid it: the runner was killed by an
earlier file's delayed process.exit before this file ran. Link the lib like
the real install layout the script assumes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(browse): capture active-tab state before close() — last-tab auto-create raced the close event

closeTab checked `tabId === this.activeTabId` AFTER awaiting page.close(),
but the page 'close' event handler can fire during that await and reassign
activeTabId — losing the race meant the last-tab auto-create never ran,
leaving the manager with zero tabs. Capture wasActive before closing, and
only reassign activeTabId when it no longer points at a live tab.

Part of the test-integrity repairs unmasked by the suite-truncation fix.

Contributed by @time-attack (PR #2230, browser-manager hunk).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(browse): delete the orphaned sidebar chat-queue suite; align sidebar-ux/tabs with the PTY-only sidebar

browse/test/sidebar-integration.test.ts tested the /sidebar-command queue
path ripped in v1.14 (34 references to removed endpoints — 11 permanent
failures masked by suite truncation). sidebar-ux.test.ts carried 73 failures
pinning the same dead surface (pickSidebarModel, ANALYSIS_WORDS); the trim
keeps its 108 live tests, including the background.js token/allowlist gates.
sidebar-tabs gets the two matching expectation updates.

Closes #2420, #1980.

Contributed by @time-attack (PR #2230, sidebar hunks; the
security-sidepanel-dom deletion was NOT taken — that suite pins the live
sidepanel DOM surface and passes).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(browse): align dual-listener and terminal-agent static guards with the current source

Two static-grep guards pinned superseded source shapes and failed once the
suite actually ran them: the tunnel dispatch gate is args-aware since the
--out disk-write ban (canDispatchOverTunnel takes command AND args), and
lazy PTY spawn routes through the maybeSpawnPty helper since v1.44. The
updated assertions pin the current, stricter shapes (open() never spawns;
the helper is the only spawnClaude caller).

Contributed by @time-attack (PR #2230, dual-listener + terminal-agent hunks).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(test): remove all 8 delayed process.exit teardown bombs — the tier-1 gate can finally fail

bun test runs every file in ONE process, so a 500ms setTimeout(process.exit(0))
armed in afterAll fired mid-way through a LATER file and killed the entire
suite with exit 0 and no summary — only ~16 of 434 files ran, and every
downstream failure was invisible (observed live throughout this wave's
enumeration). Changes, all guarded by fault injection:

- Replace every delayed-exit teardown with a time-boxed close of the file's
  own browser (8 files across browse/ and design/); stub the daemon
  /shutdown timer instead of letting its unconditional process.exit tear
  the runner down.
- test/no-suicide-exit.test.ts: static tripwire — no *.test.ts may schedule
  a delayed process.exit again.
- test/exit-propagation.test.ts + fixtures: fault injection with REAL bun
  output proves the truncation shape (exit 0, no summary) and that
  scripts/test-free-shards.ts now detects it: a shard exiting 0 WITHOUT
  bun's final summary line is treated as FAILED (exit code alone is not
  evidence of completion).
- handoff: the three headed-mode integration tests are darwin-skipped with
  a pointer to the known macOS headed-launch breakage (#2242/#2554); they
  keep running on Linux CI. Un-skip in the browse-daemon wave.
- feedback-roundtrip: repair the handler call sites unmasked by the fix —
  handlers take (command, args, session, bm); passing the manager where a
  session belongs broke all six tests.
- user-slug-fallback: HOME isolation makes endpoint_hash deterministic.

Fixes #2421, #2435.

Contributed by @sneakygriff (PR #2172) with repairs from @time-attack
(PR #2230 feedback-roundtrip hunks); supersedes PR #2252 by @whd4 (same
defect, credited).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: include design/test/ in the free suite and the sharded runner

design/test was absent from both the package.json test globs and TEST_ROOTS
in scripts/test-free-shards.ts — its tests (including one of the teardown
bombs removed in the previous commit) never ran in any CI or local free
run, so design fixes could ship without their unit tests executing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(make-pdf): reject directories when resolving the browse binary

access(X_OK) is true for directories (they carry the execute/traverse
bit on POSIX and pass the Windows existence check too), so cwd-dependent
resolution could pick the ~/.claude/skills/browse alias DIRECTORY as the
browse binary. Every browse call then exited 4 with empty stderr, which
make-pdf surfaced as "Chromium failed to launch" against a perfectly
healthy Chromium (#2156). Guard isExecutable with statSync().isFile()
so only regular files qualify.

Contributed by @jwilk-hrep (PR #2538).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(make-pdf): write browse-bound temp files under the safe-dirs allowlist

os.tmpdir() on macOS resolves to /var/folders/..., which fails browse's
safe-dirs validation ([/tmp, cwd]) since the v1.6.0.0 --from-file
tightening. Default PDF output (generate with no -o), the preview HTML,
tmpFile() scratch files, and setup's smoke-test fixture/output all wrote
there, so browse rejected the paths it was asked to read or write.
Export PAYLOAD_TMP_DIR from browseClient (the existing TEMP_DIR
convention: os.tmpdir() on Windows, /tmp elsewhere) and route
orchestrator.ts and setup.ts temp files through it.

Contributed by @lvthewah (PR #2505; the browse-binary directory guard
from that PR landed separately via PR #2538).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(make-pdf): stop URLs swallowing smartypants placeholders

A bare autolinked URL (<a href="X">X</a>) has zero whitespace between
the URL text and its own closing tag. TAG_RE carves that </a> into a
NUL-delimited SMARTPANTS_PRESERVED placeholder BEFORE the URL pass
runs, and URL_RE's \S+ swallowed the adjacent placeholder into the URL
match. The restore pass is single-shot, so the inner placeholder never
restored: raw "SMARTPANTS_PRESERVED_N" text leaked into the rendered
link, the </a> vanished, and link-blue styling bled into the rest of
the document (#2084). Excluding the NUL sentinel (\u0000) from the URL
character class stops the match from crossing into an already-carved
zone.

Contributed by @marshaung (PR #2280; PR #2339 by @BrendaB24 covered the
same smartypants defect).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(make-pdf): no blank first page when content precedes the first H1

Two paths put invisible content ahead of the first H1 and cost users a
blank page 1 (#1904):

- A visually-empty preamble (leading <style> block, HTML comment)
  became its own .chapter. That section took the `.chapter:first-of-type
  { break-before: auto }` exception, so the first real chapter inherited
  `break-before: page` and started on page 2. Non-rendering preambles
  now fold into the first real chapter (markup preserved, no page
  break); real text preambles keep their own chapter.
- Leading YAML frontmatter rendered as a literal paragraph of body text
  on its own first page (marked has no frontmatter awareness). It is
  now stripped before parsing; a `---` thematic break elsewhere is
  untouched.

Contributed by @jbetala7 (PR #1913).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(browse): allow about:blank so a restarted daemon can initialise

The daemon opens its own first tab on about:blank, so blocking it in
validateNavigationUrl meant a restarted daemon could never recreate the
blank tab it starts from — and `browse newtab about:blank`, which
`make-pdf setup` runs as its Chromium smoke test, failed and surfaced
as "Chromium failed to launch" against a healthy browser.

Allow about:blank ONLY, never the about: scheme: about:blank has no
origin, loads nothing and runs nothing, while about:config and friends
are real surfaces. Exact href match (lower-cased, since the URL parser
normalises the protocol but not the opaque part), so about:blankfoo
stays blocked.

Contributed by @jwilk-hrep (PR #2537).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(design): drop gpt-image-2 tool model that 400s under the gpt-4o orchestrator

The Responses API rejects pairing a gpt-4o orchestrator with an
image_generation tool spec'd as model: "gpt-image-2" (400
invalid_request_error), which took every design image call offline —
generate, variants, iterate (both threaded and fresh paths), evolve,
and /design-shotgun (#1771). gpt-image-2 is only valid under a gpt-5
orchestrator; with gpt-4o the tool must omit the model field (defaults
to gpt-image-1).

Remove the model field at all five call sites and add a static-grep
tripwire test (design/test/image-gen-pairing.test.ts) that fails CI if
any design/src module reintroduces the gpt-4o + gpt-image-2 pairing.
Re-enabling gpt-image-2 later requires bumping the orchestrator off
gpt-4o in the same diff, which the tripwire permits.

Contributed by @Pablosinyores (PR #1773).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(design): variants AbortError message reports the real 240s timeout

generateVariant arms its abort at 240_000 ms but the AbortError branch
returned "Timeout (120s)" — off by 2x, so a user staring at the failure
could not tell whether to bump the timeout, retry, or drop the call.
Report the actual configured bound, and pin it with a test that forces
the abort path (fast-forwarding only the 240_000 ms timer) and asserts
the surfaced string matches.

Contributed by @vryahn (PR #1774).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(memory-ingest): stop silently ingesting 0 pages — include gitignored staging, reconcile counts

Pages stage into ~/.gstack/.staging-ingest-*/ inside a repo whose .gitignore
is `*`, and gbrain import honours .gitignore — so it collected 0 files,
imported nothing, and the ingest still reported "written: N" from the STAGED
count while advancing state, meaning no future run ever retried. Three
layers now: (1) pass --include-gitignored (root cause); (2) if the installed
gbrain predates the flag, retry without it (subcommand --help is generic, so
the attempt is the only probe) with an upgrade pointer; (3) reconcile
gbrain's imported+unchanged accounting against the staged count and REFUSE
to advance state on a shortfall, naming the gitignore collision.

Fixes #2144, #2104.

Contributed by @gawievanblerk (PR #2560) and @Charles-Grant (PR #2486).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(autoplan): task aggregator returned zero tasks on every run — jq scope bug

Inside ($commits | split("|") | ...) the "." context is the split ARRAY, so
the filter's bare .commit raised "Cannot index array with string" on every
record — and the 2>/dev/null swallowed it, so aggregation silently produced
zero tasks no matter how many the reviews emitted. Bind .commit to $c before
the pipe. Reproduced live before the fix; regenerated autoplan/SKILL.md.

Fixes #2018.

Contributed by @kkroo (PR #2416; regenerated against the current template).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(session-update): un-wedge auto-upgrade — autostash over local patches, log the pull's real reason

On a normal install the tracked files ARE locally patched (skill-prefix
name rewrites, gbrain-refresh blocks), so the bare `git pull --ff-only`
refused on every run and auto-upgrade froze forever — observed as 308
consecutive PULL_FAILED entries with the reason discarded by 2>/dev/null.
Pull now runs --autostash (local patches ride over the update and pop back),
stderr is captured into the log so a genuine failure names its cause, an
autostash pop conflict recovers to a clean tree and re-renders the patches
(gstack-patch-names + gbrain-refresh, both idempotent), and a successful
pull re-renders them as a self-heal. Behavioral tests cover the wedge shape
and the reason logging.

Fixes #2566.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: raise the free-suite per-test timeout to 30s

bun's 5s default is fine for a file run solo, but the monolithic free suite
shares one process across 100+ files whose browser instances contend for
launch slots — Playwright tests that pass in isolation time out mid-suite.
30s matches the ceiling the enumeration runs used; the sharded runner
(test:free) is unaffected.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(question-log): parse native AskUserQuestion answers — every native answer logged as __unknown__

Current Claude Code returns AskUserQuestion results as an OBJECT map keyed
by question text ({answers: {question: label}}); the hook only handled the
legacy array shapes, so 86% of live records carried user_choice __unknown__
— and the bin then scored every one as followed_recommendation false,
silently poisoning plan-tune metrics. Adds the object-map extraction (exact
+ whitespace-normalized + single-question pairing, multiSelect joins,
annotations as free_text), strips the (Recommended) suffix from BOTH sides
of the comparison, skips the computation entirely on extraction failure,
and logs unrecognized shapes to hook-errors.log instead of embedding them
in the record.

Fixes #2336, #2206.

Based on the working patch in #2336 by @yijisoo; suffix comparison fix
contributed by @chuchu2781 (PR #2400).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(slug): canonicalize slash branches to dash form — review history stops splitting

Branch-name sanitization disagreed across gstack (four incompatible rules),
so reviews for the same slash-named branch landed in multiple files and the
ship dashboard missed entries. gstack-slug now canonicalizes / to - in one
place, and ship's review lookup routes through it; goldens regenerated
against the current templates.

Fixes #1127, #2550.

Contributed by @ShuratCode (PR #2465; duplicate fixes by @xrfael-dev and
two others in PRs #1851/#1699/#1621, credited).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(slug): resolve the project root by marker walk-up — subdirectory sessions stop misfiling state

gstack-slug derived everything from pwd, so a session in a subdirectory got
the subdir's basename as its slug (or an outer monorepo's remote), misfiling
reviews/decisions/learnings under a phantom project — and the per-pwd cache
made the wrong answer permanent. The resolver now walks up from pwd:
outermost STRONG marker wins (.git, package.json, pyproject.toml, Cargo.toml,
Gemfile, go.mod, .project.yaml), weak content markers (README, LICENSE) catch
non-code project folders, deploy artifacts are deliberately not markers, and
GSTACK_PROJECT_SLUG remains the escape hatch. The cache self-heals on
mismatch. Main-side invariants preserved on top: the unconditional
[a-zA-Z0-9._-] re-sanitize before echo and slash→dash branch canonicalization.

Fixes #1125.

Contributed by @ajeenkya (PR #1702; rebased over the sanitize and
branch-canonicalization work that landed after it).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(hooks): shared spawn-bin helper — all three AskUserQuestion hooks were inert on Windows

The plan-tune hooks resolved bin scripts via new URL(import.meta.url).pathname
(which doubles the drive letter on Windows: /C:/C:/...) and spawnSync'd
extensionless bash scripts directly (unrunnable without a shell association)
— so question logging, preferences, and the error fallback all silently
no-op'd on Windows, and /plan-tune collected no data. A single spawn-bin.ts
helper now owns bin resolution (fileURLToPath) and win32 bash routing for
every hook, with static tripwires so a future hook can't reintroduce the
raw pattern. This is the one Windows-spawn idiom for hook code.

Fixes #2356.

Contributed by @rafassousa (PR #2504; supersedes PR #2399 by @chuchu2781).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(model-overlays): add fable-5, opus-4-8, and sonnet-5 overlays + resolver mappings

model-overlays/ had no entry for the current Claude generation, so every
session on a Claude 5 family or Opus 4.8 model fell through to the generic
claude.md nudges. Adds the three overlays with resolver mappings and
per-overlay tests; generated output for the default host is unchanged
(overlays activate by detected model).

Closes #2509.

Contributed by @chrisquorum (PRs #2246, #2243, #2247).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(windows): grant icacls ACEs by *SID, not unqualified username

An unqualified username handed to icacls is ambiguous: on a machine whose
hostname equals the username (a common Windows setup), it resolves to the
MACHINE account instead of the user. Combined with /inheritance:r, that
leaves ~/.gstack with a single ACE matching nobody — the process that just
"secured" the directory locks itself out, and icacls still reports success.

Both icacls sites in the repo (restrictFilePermissions and
restrictDirectoryPermissions in browse/src/file-permissions.ts — the only
icacls call sites; setup has none) now grant via icacls' literal-SID form
`*<SID>`, resolved once per process from System32\whoami.exe (pinned to
System32 because a bare `whoami` under a bash-flavoured PATH picks up the
MSYS build, which rejects /user). Fallback when the SID can't be resolved
is the domain-qualified `USERDOMAIN\username` name, which is unambiguous
where the bare username was not.

Windows-only regression tests assert the hardened directory stays usable
by the calling process (readdir + write), which is exactly the check that
a not-toThrow assertion sailed past before.

Contributed by @asizux2 (PR #2479); the same defect was independently fixed by @Icandi40, @chiragborse1, @IntegriGit and @voltapix26.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(windows): forward windowsHide through the bun-polyfill spawn shims

windowsHide is the one spawn option where Node's default is the opposite
of Bun's: Node shows the child's console window, Bun.spawn hides it.
The polyfill's spawn and spawnSync shims dropped the option entirely, so
the Node fallback path (dist/bun-polyfill.cjs) silently inverted the
behavior on the one platform the shim exists to serve — every watchdog
respawn of the terminal agent popped a visible bun.exe console window.

Three sites fixed:
- Bun.spawnSync shim: forwards windowsHide with Bun-matching default true
- Bun.spawn shim: same (stdio:'ignore' silences output but does NOT
  suppress the console window on Windows)
- spawnTerminalAgent in terminal-agent-control.ts: explicit
  windowsHide: true, so the Node fallback path behaves like Bun-native

An explicit windowsHide: false is honored at both shims. Three focused
tests pin the default-true, default-true-sync, and explicit-false paths
by intercepting child_process in a subprocess; the test file's require
path now uses forward slashes so it survives interpolation into a JS
string literal on Windows.

Supersedes PRs #2523, #2294 and #2290, which each covered a subset of
these sites.

Contributed by @jerrynicholsai (PR #2539); earlier fixes by @jwilk-hrep, @rroojrooj and @WimvandenHeijkant covered subsets of the same sites.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(watchdog): signal-0 liveness, tick-scaled respawn guard, windowsHide

Three-bug chain behind the Windows terminal-agent leak (console window
strobing every 60s, one orphaned agent per watchdog tick until the box
ran out of committable memory):

1. isProcessAlive shelled out to `tasklist /FI "PID eq <pid>"` on Windows
   with a 3s timeout. A Bun.spawnSync that hits its timeout still RETURNS
   with partial stdout, so the `.includes()` PID match read a LIVE agent
   as dead — killAgentByRecord skipped the kill, the watchdog respawned
   around the survivor, and every orphan slowed the next tasklist enough
   to produce the next false negative. Now: `process.kill(pid, 0)` on
   every platform (Node and Bun both map signal 0 to an OpenProcess
   existence check on Windows), with EPERM counted as alive. No
   subprocess, no timeout, no console window.

2. The respawn circuit-breaker was mathematically unreachable — verified
   in this tree: RESPAWN_GUARD_WINDOW_MS was a fixed 60_000 against a
   60_000ms default tick, and each tick pushes at most one respawn
   timestamp, so three pushes span ~120s and can never coexist inside a
   60s window (eviction is strict `>`, and setInterval drift plus
   per-tick work always ages the prior entry past the boundary). The
   guard could not fire at the default tick rate and a steady
   one-per-tick leak ran unbounded. The window now scales with the tick:
   max(60_000, tick * (RESPAWN_GUARD_MAX + 2)), so "3 crashes in quick
   succession → stop" holds at any tick value.

3. The tasklist probe popped a visible console per tick (no windowsHide).
   Removing the shell-out kills that site; the agent-spawn site itself
   already passes windowsHide: true (landed with the bun-polyfill
   windowsHide commit — PR #2414's terminal-agent-control.ts hunk is
   reconciled there rather than duplicated).

New browse/test/process-liveness-windows.test.ts pins all three: no
subprocess from the probe, a static tripwire against reintroducing
`tasklist` + `PID eq` liveness checks in src/, the spawnTerminalAgent
windowsHide + stdio contract, and the window-derived-from-tick
arithmetic. terminal-agent-watchdog.test.ts test 4 now pins the
window/tick relationship instead of the fixed literal that let this
ship. Also converts `new URL(import.meta.url).pathname` to
`import.meta.path` across the static-grep tests it touches — the
pathname form yields /C:/... on Windows and breaks path.resolve.

Contributed by @SYKhayyat (PR #2414).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(terminal-agent): tie agent lifetime to its owning browse server PID

The terminal agent is intentionally detached so it survives the
short-lived CLI launcher, but its real owner is the persistent browse
server. If that server crashed or was killed before running normal
shutdown, the agent was adopted by PID 1 and lived forever (#2019).

spawnTerminalAgent now requires an ownerPid and exports it to the agent
as BROWSE_OWNER_PID; all three spawn sites pass the server PID (cli.ts
cold-start, cli.ts supervisor respawn, server.ts watchdog). The agent
polls the owner with signal 0 every 15s (GSTACK_TERMINAL_OWNER_WATCHDOG_MS
to tune) on an unref'd timer and, when the owner disappears, exits
through the SAME cleanup path as an intentional SIGTERM shutdown — now
re-entrancy-guarded and also removing the terminal-internal-token file
alongside the port file and agent record.

Runtime test spawns a real agent tied to a throwaway owner process,
kills the owner, and asserts the agent exits and its discovery files
(terminal-agent-pid, terminal-port) are gone.

Reconciled with the watchdog commit's spawnTerminalAgent contract test
(process-liveness-windows.test.ts now passes ownerPid and pins the
BROWSE_OWNER_PID env forwarding).

Closes #2019.

Contributed by @csarigoz (PR #2530).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(windows): give the bun-polyfill spawn shim a real `exited` promise

Bun.spawn exposes `proc.exited` as a Promise resolving to the exit code.
The Node fallback shim (dist/bun-polyfill.cjs) returned no such field, so
every `await proc.exited` on the Windows path resolved instantly to
undefined — the Windows cookie picker (cookie-import-browser.ts races
proc.exited at three sites) read stdout before the child produced it and
silent-failed; browser-skill-commands and terminal-agent hit the same
class.

The shim now:
- drains stdout/stderr eagerly into capped in-memory buffers (Node's
  Readables are pull-based; without draining, a child writing past the
  OS pipe buffer blocks in write() and 'exit' never fires), replaying
  them as fresh single-shot Web ReadableStreams so reads work before or
  after awaiting exit;
- caps the buffer at 16 MB (GSTACK_SPAWN_MAX_BUFFER to override), still
  draining past the cap so a runaway child can't wedge or OOM;
- resolves `exited` with Bun-matching codes (exit code, 128+signal, 1 on
  spawn error) after both pipes finish, and resolves on 'error' too —
  Node fires 'error' without 'exit' when the binary is missing, which
  otherwise hangs the await forever.

Six tests pin exit codes, the read-after-exit ordering, spawn-failure
resolution, the buffer cap, and the large-output drain. Adapted to the
current test file (require path goes through the requirePath variable
from the windowsHide commit), and the 1 MB drain test's child now exits
in the write callback — on modern Node a pipe write past the OS buffer
is async and process.exit() straight after write() truncates at ~64 KB
even with a live reader, which fails the test for reasons unrelated to
the shim.

Contributed by @punksterlabs (PR #1743).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(setup): BROWSE_BIN carries the .exe suffix on Windows

On Windows, `bun build --compile` emits browse.exe, but setup's
BROWSE_BIN pointed at the suffixless path — so the post-build gate
(`[ ! -x "$BROWSE_BIN" ]` → "browse binary missing") could never pass on
Windows even after a fully successful build, while the build step itself
reported success. Closes #2291.

Applied the PR's override after the IS_WINDOWS detection, and also to
the second BROWSE_BIN assignment the PR predates: the direct-Codex-
install migration path re-derives BROWSE_BIN from the migrated dir and
would otherwise drop the suffix again on Windows.

Contributed by @rroojrooj (PR #1714).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(setup): link lib/ beside bin/ at all five host-install sites

bin/ scripts import shared modules via ../lib (gstack-learnings-log →
lib/jsonl-store.ts is the reported case), so any runtime root that
exposes bin/ without lib/ breaks 13 bin/ commands — learnings-log,
decision-log, telemetry and friends fail with "Cannot find module
.../lib/jsonl-store.ts" on every non-Claude install, silently from the
skills' perspective.

All five host-install sites now carry lib/ next to bin/, each through
the existing _link_or_copy helper (never raw ln — the static invariant
in test/setup-windows-fallback.test.ts enforces this):

- .agents sidecar (create_agents_sidecar asset loop)
- Codex runtime root (create_codex_runtime_root)
- Factory runtime root (create_factory_runtime_root)
- OpenCode runtime root (create_opencode_runtime_root)
- Kiro install block

New test/setup-runtime-lib-command.test.ts executes the real setup shell
for each root in a sandbox (both the symlink branch and the Windows copy
branch of _link_or_copy) and runs gstack-learnings-log end-to-end from
the installed root, asserting the learning lands in
~/.gstack/projects/<slug>/learnings.jsonl — plus a negative control
proving a bin-without-lib root fails exactly the way the bug report did.
gen-skill-docs.test.ts's setup-validation block pins the lib link at
every site. Cross-checked against PRs #2433, #2410 and #2198: all three
cover subsets of these sites; nothing they fix is missing here.

Contributed by @fedster99 (PR #2262); overlapping fixes by @gregario, @lsendel and @netkurt.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(setup): ship supabase/config.sh with every host runtime root

Distinct from the lib/-beside-bin/ defect: gstack-telemetry-sync,
gstack-update-check, gstack-security-dashboard and
gstack-community-dashboard all source $GSTACK_DIR/supabase/config.sh to
resolve GSTACK_SUPABASE_URL, where GSTACK_DIR is the installed root
(parent of bin/). The [ -f ... ] guard means a root without the file
degrades SILENTLY — telemetry and update checks just stop resolving the
project URL on non-Claude installs. Closes #2215.

setup now links supabase/config.sh (file-level on purpose — migrations/
and functions/ are dev-only) via _link_or_copy at all five host-install
sites: the PR's four (Codex, Factory, OpenCode runtime roots + the Kiro
block) plus the .agents sidecar, whose bin/ resolves the same relative
path and which the PR predates covering.

The runtime-root test now asserts supabase/config.sh is present in
every built root, on both the symlink and Windows-copy branches.

Contributed by @jizusun (PR #2216).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci(windows): curate the fix-wave regression tests into the windows-latest run

The windows-free-tests curated set is derived (POSIX-fragility regex scan
+ explicit deny list), and two of this wave's Windows regression files
were auto-excluded on false-positive pattern hits:

- browse/test/file-permissions.test.ts tripped the POSIX-mode-bitmask
  pattern, but every `mode & 0o777` assertion is platform-guarded — and
  the file carries the win32-only icacls-by-SID regression tests, which
  can only ever execute on windows-latest.
- browse/test/terminal-agent-owner-watchdog.test.ts tripped the
  spawn(['bun','run',...]) pattern whose reason is the Playwright-bound
  browse server; it actually spawns terminal-agent.ts (fs/path/crypto +
  local helpers only, no Playwright at module scope), and the owner-PID
  orphan leak it pins was reported on Windows (#2019).

Adds a KNOWN_WINDOWS_SAFE force-include list (mirror of
KNOWN_WINDOWS_INCOMPATIBLE, each entry carrying its false-positive
rationale) consulted before the pattern scan, and makes the
owner-watchdog test's throwaway owner process Windows-portable
(process.execPath instead of `sleep`, which a bare runner may not have).

The wave's other new files need no wiring: process-liveness-windows and
the bun-polyfill windowsHide/exited tests pass curation automatically;
setup-runtime-lib-command self-skips on win32 by design (its Windows
branch is exercised by simulating IS_WINDOWS=1 under bash), so
force-including it would add a permanently-skipped file.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(setup): register the SessionStart hook with a bash prefix on Windows

Windows can't execute an extensionless bash script directly — registering
the bare gstack-session-update path made the hook pop the "Select an app"
dialog on every session start (or silently never run), so team-mode
auto-upgrade was dead on Windows installs. Companion to the hooks'
spawn-bin routing: same defect class at the registration site.

Contributed by @NikhileshNanduri (PR #1813; VERSION/CHANGELOG collateral
stripped).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(setup): stop piping gen:skill-docs through tail — generator failures were masked

setup piped doc generation through `tail -3`, so a generator crash kept the
pipe's exit 0 and installs completed "successfully" with broken or missing
SKILL.md files. Capture the real exit status at BOTH sites (the main
gen:skill-docs step and the gbrain-detected gen:skill-docs:user regen —
the second drifted in after the PR and its own test caught it), print the
tail for UX, and fail loudly.

Contributed by @DavidMiserak (PR #1898; VERSION/CHANGELOG collateral
stripped; extended to the second pipe site).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(mktemp): move the X-run to the end of every temp-file template (BSD/busybox safe)

BSD mktemp (macOS) does not substitute an X-run that has a suffix after it:
`mktemp "$TMP_ROOT/codex-err-XXXXXX.txt"` creates a LITERAL
codex-err-XXXXXX.txt on the first call (exit 0) and every later call fails
with `mkstemp failed: File exists` — so /codex breaks from the SECOND run on
every Mac, masquerading as a model stall. busybox mktemp (Alpine) rejects the
template on the first run. Fixes #2091, #2370.

Union of both community fixes, compared at the diff level:
- PR #2372: all 11 source sites with a suffix after the X-run — codex
  SKILL.md.tmpl (5), claude SKILL.md.tmpl (3), bin/gstack-developer-profile
  (2, suffix folded into the prefix: .json.tmp.XXXXXX), and the office-hours
  codex pass in scripts/resolvers/review.ts (1).
- PR #2103: the second half of #2091 — bin/gstack-paths now strips the
  trailing slash from TMP_ROOT at the source (macOS $TMPDIR ends in `/`),
  plus runtime tests pinning that normalization.

New repo-wide tripwire in test/regression-issue2091-bsd-mktemp.test.ts:
every .tmpl, every SKILL.md, and every scripts/resolvers/*.ts is swept —
no mktemp template may carry a suffix after the X-run, with a self-test so
the detector can't be quietly blinded. Generated SKILL.md files regenerated
via gen:skill-docs in this commit.

Contributed by @ShuratCode (PR #2103) and @noron12234 (PR #2372); PR #2285 by @cathrynlavery covered a subset.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(codex,review,ship): scope codex review with an explicit --base flag, never prompt text

`codex review` takes its scope ONLY from --base/--commit/--uncommitted. The
positional [PROMPT] is mutually exclusive with all three, and a prompt-only
`codex review "<text>"` silently falls back to the uncommitted working-tree
scope (verified on 0.144.1: it runs `git status --short; git diff` and
reviews that) — so the previous prompt-based scoping produced a
confidently-worded review of the WRONG changes and read "no changes" on a
clean tree. Every diff pass now invokes `codex review --base <base>` with no
prompt argument: /codex Step 2A default path, the /review structured pass,
and the /ship adversarial-section pass (all via scripts/resolvers/review.ts).

Custom review instructions keep their own `codex exec` path (the CLI rejects
prompt + scope flag together), with the filesystem boundary preserved there.
Two new Error Handling entries teach the failure shapes: the argv-parse
error, and the "review says no changes on a branch full of changes" symptom.

Tests updated to pin the new invariant instead of banning the fix: the old
assertions required the diff range in prompt text and banned the
`--base <base> -c '...'` substring, which the correct scoped form contains.
Also deletes test/fixtures/golden-ship-claude.md — a 2,565-line orphaned
fixture referenced by zero tests (the live goldens are in
test/fixtures/golden/, compared by test/host-config.test.ts); the factory
golden is refreshed from the regenerated output. Generated SKILL.md files
regenerated via gen:skill-docs in this commit.

Contributed by @fangearhq-boop (PR #2513).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(review,ship): run the codex diff passes under the timeout wrapper (#1036)

The `_gstack_codex_timeout_wrapper` added in #1056 was wired into
codex/SKILL.md but never into the /review and /ship diff passes, which kept
running under a bare 5-minute Bash gate. An unwrapped stall returns no exit
code and no output, which downstream reads as "Codex reviewed and found
nothing" — a truncated pass silently became a clean bill. Measured on
codex-cli 0.145.0: a pass was killed at 287s of a 300s budget mid-tool-call,
and the same prompt completed in 336s.

Both passes in scripts/resolvers/review.ts (adversarial `codex exec` and the
structured `codex review --base` pass) now re-source gstack-codex-probe and
run under `_gstack_codex_timeout_wrapper 540`, with the Bash tool gate raised
to 600000 ms so the wrapper fires FIRST and a stall surfaces as a diagnosable
exit 124. The timeout guidance now says a timed-out pass is MISSING COVERAGE,
not a clean result, and points at the run's rollout log under
~/.codex/sessions/ for partial output. The stale "timeout doesn't exist on
macOS" claim is gone — the wrapper resolves gtimeout, then timeout, then runs
unwrapped, so it is safe without coreutils.

Static guards in test/codex-hardening.test.ts pin all three sites (resolver,
review/SKILL.md, ship/sections/adversarial.md): both calls wrapped, wrapper
budget strictly under the Bash gate, and no reappearance of the macOS claim
that steered these call sites away from the wrapper in the first place. The
Claude-output path guard in test/gen-skill-docs.test.ts now scrubs
~/.codex/sessions/ (a user-facing Codex CLI path, same class as the
~/.codex/logs/ exemption) before banning Codex host paths. Generated files
regenerated via gen:skill-docs; factory golden refreshed.

Contributed by @aegixx (PR #2379).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(codex): sandbox the review path, fail the gate closed, order timeouts wrapper-first

Closes #2496, #2524, #2477 — three defects in the class "a guard that
reports success while doing nothing", all in codex/SKILL.md.tmpl:

(a) Review sandbox. The default `codex review` path was the only codex call
with no sandbox override, inheriting ~/.codex/config.toml's default — write
access on a trusted project — while Important Rules claimed read-only.
Top-level `codex review` has no -s/--sandbox flag (verified on 0.147.0), so
the invocation now pins `-c 'sandbox_mode="read-only"'`, the same form the
consult-resume path already uses.

(b) Fail-closed verdict gate. The old rule ("no [P1] found → PASS") could
not fail on the default path: native `codex review` output carries no
bracketed tags, and a non-zero exit, expired auth, timeout, or empty result
also contains no [P1] — all read as PASS. The gate is now an ordered,
fail-closed check: non-zero exit → FAIL; empty output → FAIL; [P0]/[P1]
(bracketed or codex's native labels) → FAIL with count; NO severity tags at
all → FAIL requiring a human read; PASS is only reachable through the
explicit tagged-advisory-only branch. [P0] is recognized as blocking, and
the review-log findings count includes it.

(c) Bash gate above the wrapper. Step 2A instructed `timeout: 300000` under
a 330s wrapper, and Challenge's 300s gate sat under a 600s wrapper — the
harness killed the call before the wrapper could emit its diagnosable
exit-124 message. Every Bash gate now sits strictly ABOVE its wrapper:
360000 over the 330s review wrapper, 660000 over the 600s challenge/consult
wrappers, with the ordering rationale stated at each site.

Also from #2477/#2524: a new Error Handling entry for the model-entitlement
400 ("The '<model>' model is not supported...") pointing at the `model =`
pin and `[notice.model_migrations]` in ~/.codex/config.toml and saying
exactly which override to retry with (-m for exec-based modes,
`-c model="..."` for review mode, which rejects -m); the Model & Reasoning
section no longer documents `-m` for `/codex review`.

Static assertions in test/codex-hardening.test.ts pin (a)-(c) across both
the .tmpl and the generated SKILL.md: every scoped review invocation carries
sandbox_mode="read-only" and never -s; the default-PASS sentence is banned
and the fail-closed branches are present; and per-section, every Bash
`timeout: N` is strictly greater than every wrapper budget, with 2A/2B/2C
all required to be inspected. Generated SKILL.md regenerated via
gen:skill-docs in this commit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(preamble): quoted tilde made Artifacts Sync and telemetry-finalize dead code in 49 skills

A tilde inside double quotes never expands, so the generated
`_BRAIN_SYNC_BIN="~/..."` assignments resolved to a literal ./~ path and
the Artifacts Sync + telemetry-finalize blocks silently no-op'd in every
skill that carried them (regression of #785). The preamble resolvers now
emit $HOME-based paths; all generated SKILL.md files regenerate identically
from the fixed templates, and a static tripwire fails the suite if a
quoted-tilde assignment ever reappears in generated output.

Fixes #1656, #1715.

Contributed by @jawadakram20 (PR #2333).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(gen-skill-docs): stop the catalog trim chopping descriptions at embedded periods

The description-trim regex treated the first period as end-of-sentence, so
skill descriptions with embedded periods (e.g. file extensions, version
numbers) truncated mid-thought in the generated catalog — the discovery
surface every host loads. Trim now respects the full first sentence;
diagram's description regenerates to its intended text.

Contributed by @sneakygriff (PR #2171).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(preamble): update_check:false gates the prose, not just the binary

Setting update_check:false stopped the update-check BINARY from running,
but every skill preamble still shipped the upgrade-handling instruction
prose unconditionally — burning tokens on instructions that could never
fire and confusing agents into probing for upgrades anyway. The resolver
now suppresses the upgrade-flow prose when the config disables checks.

Fixes #2001.

Contributed by @jc0d35 (PR #2022).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(browse): sidebar Terminal — drop the duplicate WS subprotocol header, stop doubling CJK IME input

The terminal client passed the auth token as the WS subprotocol AND echoed
it in a second header, which some Chromium builds reject; and composition
events double-sent CJK input (each IME commit arrived once from the
composition handler and once from the data handler). One auth path, one
input path; also fixes the terminal-agent test that failed on clean main.

Contributed by @mindsurf0176 (PR #2515).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(setup): -h/--help prints usage instead of running the installer

Asking setup for help RAN the full installer — Playwright download and all.
Standard help flags now short-circuit to usage.

Contributed by @saen-ai (PR #1219).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(hosts): Codex-generated skills reference AGENTS.md, not CLAUDE.md

Codex reads AGENTS.md, but its generated skills still told agents to read
CLAUDE.md in 8 places — instructions Codex hosts cannot follow. The host
config now maps the memory-file name per host; all three ship goldens
refreshed from the regenerated output.

Contributed by @exGeni (PR #1996).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(retro,ship): count tracked files for the test-file metric, not the working tree

The test-file count ran find over the working tree, sweeping untracked
build output — a Rails repo reported 623 test files when git tracks 17
(37x), skewing retro narratives and ship dashboards. Count via git ls-files
instead; includes the one-line Python-glob widening so non-JS repos stop
undercounting.

Fixes #2307, #1999.

Contributed by @joshRpowell (PR #2308).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(land-and-deploy,gen): auto-merge diagnosis + CRLF-stable generation

Two small hardenings: land-and-deploy Step 4 no longer misdiagnoses a
failed `gh pr merge --auto` as a permissions problem when the real cause is
the merge-method mismatch the command names; and gen-skill-docs normalizes
CRLF at the template entry point so Windows checkouts with autocrlf produce
byte-identical generated output to CI instead of silently skipping the
\n-anchored transforms.

Contributed by @Jmeg8r (PR #2437) and @1ncludeSteven (PR #1051).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(land-and-deploy): stop greedy sed from eating the URL scheme in deploy-config parsing

The deploy-config bootstrap parsed "Production URL: https://x.com" with
sed 's/.*: *//', which cuts at the LAST colon — the one in "https:" —
yielding "//x.com". Cut at the first ": " instead (s/^[^:]*: *//).

Resolver only; the generated land-and-deploy/SKILL.md regenerates from
this source in the docs lane.

Contributed by @briascoi (PRs #2555/#2493).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(artifacts-init): honor the provider CLI's git_protocol instead of forcing SSH

gstack-artifacts-init unconditionally rewrote the push remote to SSH and
hard-failed setup for users whose gh/glab auth is HTTPS-only. Now:

- provider-created remotes follow `gh config get git_protocol` /
  `glab config get git_protocol` (HTTPS when unset — the gh default)
- explicit/existing/manual remotes keep their given protocol; unknown
  URL forms (local bare paths, file://, self-hosted) pass through
- new --push-protocol auto|https|ssh flag overrides the inference
- the unreachable-remote error names the actual protocol and points at
  --push-protocol instead of assuming a missing SSH key

Closes #1348.

Contributed by @time-attack (PR #2225).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(browse): skip the .gitignore append when git already ignores .gstack/

ensureStateDir appended ".gstack/" to a tracked .gitignore even when git
already ignored the directory via global excludes, .git/info/exclude, or a
parent .gitignore — dirtying the working tree on every daemon start. Run
`git check-ignore -q -- .gstack/` first and return early when git says it's
covered; git-missing/not-a-repo/timeout all fall through to the existing
text-check append (the safe default).

Closes #2385.

Contributed by @gregario (PR #2430).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(browse): guard browser.process() in resolveDisconnectCause

`.process()` only exists on browsers Playwright launched itself; a browser
from connectOverCDP() (or a test stub) has no such method, so the blind call
threw "browser?.process is not a function" inside the disconnect handler and
took down the daemon. Type-check the method before calling it and treat the
no-method case as no process handle.

Closes #2085.

Contributed by @elan2002 (PR #2434).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(lib): narrow the override injection denylist to instruction-shaped phrases

The /override[:\s]/i pattern flagged any prose containing "override " or
"override:" — CLI flags (--port-override -1), tfvars notes, and plain
"you can override the default region" all tripped the injection guard.
Require an instruction-shaped continuation: "override (all)? previous |
prior | above | the rules/instructions/system prompt". Genuine attempts
like "Override: ignore all previous instructions" still block via the
ignore-previous pattern.

Closes #2401, #1934.

Contributed by @Masashi-Ono0611 (PR #2424); same fix independently by
@JonasFocus (PR #1940).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(redact): stop the E.164 phone pattern flagging compact timestamps

Bare 14-digit runs like 20260727202423 (YYYYMMDDHHMMSS backup/log stamps)
matched the phone regex and produced MEDIUM PII findings. Reject a
separator-free 14-digit span whose fields parse as a plausible date-time;
real numbers carry a + or spacing, so phone coverage is unchanged.

Contributed by @abkrim (PR #2428).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(design): create the OpenAI key file owner-only, closing the write-then-chmod race

saveApiKey wrote ~/.gstack/openai.json at the default umask and tightened to
0600 afterwards, leaving the API key briefly world-readable between write and
chmod (CWE-377/367). Pass mode 0o600 at create; the trailing chmodSync stays
as a backstop to tighten a pre-existing loose file.

Contributed by @bunlongheng (PR #2468).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(config): make gstack-config key validation locale-independent

POSIX bracket ranges like a-z follow the active collation order; under GNU
grep with tr_TR.UTF-8 the range excludes the ASCII letter i, so every key
containing i (skill_prefix, explain_level, ...) was rejected as invalid.
Pin both get/set validators to LC_ALL=C, with a source-level tripwire test
since macOS BSD grep doesn't reproduce the bug.

Closes #2494.

Contributed by @Math1987 (PR #2506).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(resolvers): stop env-var hosts from doubling $HOME in the binary fallback path

The browse/design/make-pdf setup resolvers built the fallback binary path as
"$HOME" + dir.replace(/^~/, ''), which is only correct for ~-rooted dirs.
Env-var hosts carry an absolute $GSTACK_* dir, so the generated fallback
became $HOME$GSTACK_.../browse — a path that never exists. New toShellPath()
in scripts/resolvers/types.ts expands ~ to $HOME and passes absolute
env-var dirs through untouched; all five call sites route through it.

Claude-host generated output is byte-identical, so no SKILL.md regeneration
is needed here.

Closes #2055.

Contributed by @simjak (PR #2056).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(settings-hook): respect CLAUDE_CONFIG_DIR when resolving settings.json

gstack-settings-hook hardcoded $HOME/.claude/settings.json, so users running
Claude Code with a relocated CLAUDE_CONFIG_DIR had hooks written to a config
file Claude never reads. Resolve ${CLAUDE_CONFIG_DIR:-$HOME/.claude} first;
the explicit GSTACK_SETTINGS_FILE override still wins.

Partial #349.

Contributed by @andrefogelman (PR #2239).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(browse): dispatch a change event after fill for change-only validators

Playwright's Locator.fill() dispatches `input` but never `change`, so
frameworks that validate on change (AngularJS ng-change, debounced
strength/match checks) never saw the filled value — correct in the DOM,
failing the framework's own validation. `browse fill` now dispatches
`change` after the fill. Failing-first regression test with a
change-only password-match fixture included.

Contributed by @intelliot (PR #2475).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(safety): unknown question-preference source exits the documented 2, not 1

The --write user-origin gate documents exit 2 as "rejected, do not retry"
(profile poisoning defense), but a source outside both the allowed and the
explicitly-rejected lists fell through to exit 1 — the generic validation
code callers treat as retryable. Unknown sources now exit 2 with the same
do-not-retry rejection message as the known non-user-originated ones.

Closes #2390.

Contributed by @gregario (PR #2429).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(pr-title): stop duplicating the version prefix on bare-version titles

A title that was nothing but a version ("v1.2.3" — the form ship uses for
version-only bumps) matched neither the "v<NEW_VERSION> " literal case nor
the trailing-space strip regex, fell through to the prepend path, and came
out as "v1.2.3.4 v1.2.3" — which pr-title-sync.yml then wrote back via
gh pr edit. Handle the bare form in both the no-change case and the
prefix-strip regex, and emit a bare new version when nothing follows.

Closes #1886.

Contributed by @jbetala7 (PR #1887).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(build): escape literal braces in the bun:sqlite stub regex

Perl >= 5.26 treats an unescaped literal `{` in a pattern as fatal
("Unescaped left brace in regex is illegal"), so build-node-server.sh
died at the bun:sqlite stub substitution on modern perl. Escape both
braces; the replacement output is unchanged.

Closes #2300.

Contributed by @nuga0718 (PR #2111).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(config): preserve spaces in gstack-config values

get/list read values with awk '{print $2}' | tr -d '[:space:]', which
truncated any value containing spaces ("/Users/x/Conductor Workspaces"
came back as "/Users/x/Conductor") and set wrote the unfiltered raw value
on the append path. New read_config_value() strips only the "key:" prefix
and trailing whitespace (cut-style parse), and set appends the same
newline-stripped value the in-place edit path uses.

Closes #1782.

Contributed by @jbetala7 (PR #1783).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(browse): recover a late-healthy detached daemon instead of a false "Server failed to start"

startServer spawns the daemon detached + unref'd, then polls health for a
fixed budget. On a loaded machine the budget can elapse in the gap between
the loop's last tick and the daemon becoming ready — the CLI reported
"Server failed to start within Ns" while the very next `browse status`
showed a healthy server. Add a final readState()+isServerHealthy() re-check
before the timeout throw, and make the budget env-overridable via
BROWSE_START_TIMEOUT (BROWSE_* tunable convention). Structural + behavioral
tests pin both invariants.

Closes #1846.

Contributed by @harjothkhara (PR #1847).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(browse): daemon resilience on loaded machines — Bun conn errors, stop/restart flush, startup + git-root budgets

Four load-sensitivity fixes in the daemon lifecycle:

- sendCommand only recognized Node's ECONNREFUSED/ECONNRESET; the compiled
  CLI runs on Bun, which reports 'ConnectionRefused'/'ConnectionClosed'
  ("Unable to connect..."), so daemon crashes leaked the raw error and
  exited 1 instead of entering the busy-check/restart path. Match both.
- stop/restart called shutdown() inline, which exits before the HTTP
  response flushes — the CLI saw a dropped socket (and would now
  crash-retry a fresh daemon just to stop it). Defer shutdown ~100ms so
  the 200 lands first.
- Non-CI POSIX startup budget raised 8s -> 15s (cold C…
garrytan added a commit that referenced this pull request Aug 17, 2026
…ls, brain-sync integrity, 31 community PRs credited (#2604)

* fix(test): host-config goldens self-provision .agents/.factory artifacts

Fixes #2532. The codex/factory golden tests read gitignored artifacts that
only gen-skill-docs.test.ts (serial tree-mutating phase) produces, so the
file failed in isolation and on clean clones (the #2536 "3 failures then 0"
symptom). beforeAll now generates a host's artifacts iff its ship SKILL.md
is missing — never overwriting existing ones, so stale artifacts still fail
the golden. The file is also classified TREE_MUTATING so its provisioning
runs in the serial window, not racing parallel readers.

Verified: full pass with .agents/ and .factory/ deleted (74/74 in isolation).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(test): exempt the live repo tree from hermetic-wiring's operator-~/.claude ban

The skill-seeding tripwire asserted every seeded symlink target must NOT
start with ~/.claude — but on the default global-git install the repo
itself lives at ~/.claude/skills/gstack, so every CORRECT symlink (which
must resolve into the live repo tree, as the very next assertion requires)
carried the banned prefix. The test could never pass on a default install:
pristine v1.64.1.0 (c118e240) fails it in any worktree under
~/.claude/skills/ and passes elsewhere (verified 2026-08-15).

Exempt targets that realpath into the resolved repo ROOT before applying
the operatorClaude ban — realpath both sides so a symlinked HOME can't
dodge the tripwire. Genuine escapes (a target under ~/.claude but outside
the repo) still fail with the escape message.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(gen-skill-docs): quote YAML inline scalars containing '...' (Bun strict parser breaks on bare ellipsis)

A bare ... inside a plain YAML scalar is a document-end marker that strict
YAML parsers (Bun.YAML among them) reject mid-scalar. catalog-trim truncation
appends '...' to any description whose lead exceeds 200 chars, so any
truncated description would generate a SKILL.md with unparseable frontmatter.
Add the ellipsis test to toYamlInlineScalar's needsQuote so such scalars are
emitted double-quoted, plus unit coverage for the quoting rules.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(gen-skill-docs): throw when a template contains {{PREAMBLE}} twice

Hardens the #2508/#2362 class: a second {{PREAMBLE}} occurrence — even a
prose mention, which is exactly how spec/SKILL.md.tmpl re-expanded the full
~12K-token preamble mid-document — now fails generation with the template
path instead of silently shipping a doubled preamble. Pure exported guard
(assertSinglePreamble) called from resolvePlaceholders, unit-tested with the
original prose-mention shape.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(test): classify catalog-trim.test.ts as tree-mutating

Discovered while landing the duplicate-{{PREAMBLE}} guard: importing
scripts/gen-skill-docs.ts executes its top-level body, which regenerates the
entire claude host (71 GENERATED files) at import time. catalog-trim.test.ts
does that import from a PARALLEL shard — the same read-during-regeneration
hazard class as #2532, invisible only because the regen is byte-identical on
a fresh tree. Move it to the serial tree-mutating window.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(test): prepush hook test builds PATH with a POSIX-only separator

`test/redact-prepush-hook.test.ts` shadows `git` with a stub by prepending a
temp dir to PATH, built as `${stubDir}:${process.env.PATH}`. On Windows the
separator is `;`, so that produces one unparseable entry, the stub is never
found, and the REAL git runs — the diff succeeds, `gitStrict` never throws, and
the hook exits 0 where the test expects 1. It fails as a wrong assertion rather
than as a portability problem, which is what made it hard to place.

Replace it with a `prependPath` helper mirroring the one already in
test/gstack-brain-context-load.test.ts, which handles both platform details:
`path.delimiter`, and a case-insensitive lookup of the existing env key —
Windows commonly spells it `Path`, and adding a second `PATH` alongside an
inherited `Path` leaves the winner up to the spawn implementation.

On POSIX the helper resolves to `{ PATH: binDir + ":" + process.env.PATH }`,
byte-identical to the expression it replaces, so behaviour there is unchanged.

Fixing the separator alone does not make the test pass on Windows, and it
cannot: the premise is that a signal-killed child yields `spawnSync`
status === null, and Windows has no equivalent (a force-killed process reports
a non-zero exit code). The stub is also a `#!/bin/sh` file named `git`, which
Windows will not execute, since process creation resolves through PATHEXT and
ignores the shebang. A Windows variant would assert the non-zero-exit branch
instead — a different branch than the test name claims — so the test is gated
with test.skipIf(process.platform === "win32"), matching
test/session-runner-timeout.test.ts and test/setup-emoji-font.test.ts.

Windows before: 14 pass, 1 fail. After: 14 pass, 1 skip, 0 fail (3 consecutive
runs). Unchanged on POSIX, where it should still run and pass — worth
confirming in CI, since I can only verify the Windows half here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(artifacts): sync the decision store, which no allowlist glob matched

gstack-decision-log enqueues projects/<slug>/decisions.jsonl after every write,
but none of the 16 managed globs matched it, so compute_paths_to_stage rejected
every one at its "must match at least one allowlist glob" check.

The writer and the syncer disagreed silently: enabling artifacts sync backed up
learnings, plans, designs and timelines -- everything except the durable decision
ledger -- and nothing reported a miss, because a dropped path prints exactly what
a synced one does when the queue is otherwise empty.

Add the three decisions.* globs and class them artifact so they also sync in
artifacts-only mode.

The test reads the heredocs out of the script rather than executing it:
gstack-artifacts-init.test.ts drives the real script through #!/bin/bash shims and
a colon-separated PATH, so it cannot run on Windows -- the platform where the
companion slug bug bit.

* fix(windows): resolve the project slug natively when gstack-slug cannot spawn

bin/gstack-slug is a `#!/usr/bin/env bash` script with no file extension. Windows
honors neither the shebang nor PATHEXT for an explicit path, so spawnSync fails
ENOENT and resolveSlug returned its literal fallback, "unknown".

Every decision on the machine was therefore filed under
~/.gstack/projects/unknown/ -- one bucket shared by every project -- while the
bash-side Context Recovery preamble resolved the real slug, found no
decisions.active.json there, and skipped through a bare `if [ -f ... ]` with no
else.

Nothing failed. Both decision bins (log and search) missed identically, so writes
and searches stayed consistent with each other, and the only component that
resolved correctly was silent by design. Measured on one machine: 62 decisions
accumulated over 10 days and 170 skill runs, surfaced zero times.

shell:true is not the fix here, unlike #1731 -- cmd.exe cannot run a bash script
either. Nor is re-spawning through `bash`: on Windows that frequently resolves to
WSL, whose $HOME and /mnt/c paths yield a different slug AND a different cache
directory, trading one split store for another.

Instead, port gstack-slug's own three steps (cache -> git remote -> basename),
keeping its alphabet and its MSYS-form cache key so both paths agree. The
fallback is win32-gated, so POSIX behaviour is byte-identical.

Tests exercise the fallback on every platform (only the gating is win32-specific),
so POSIX CI catches a regression that would otherwise surface only on a Windows
user's disk, plus a static gate pinning the platform check.

* fix(security): guard brain-sync arithmetic against injected .brain-last-pull; sanitize _GBRAIN_HOST

Re-derived from PR #2588 under the generated-file screening rule (resolver
hunks taken; SKILL.md files regenerated, not accepted). A poisoned
.brain-last-pull could reach bash arithmetic ($(( ))) — a code-execution
vector from a writable state file; the timestamp is now validated numeric
before use. _GBRAIN_HOST from ~/.claude.json is clamped to hostname-safe
characters before echo. Ship goldens refreshed to the regenerated output.

Co-authored-by: sneakygriff <89592870+sneakygriff@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(sync): run gstack-brain-sync through bash, not cmd.exe, on Windows

The brain-sync stage failed on EVERY Windows run with "is not
recognized as an internal or external command", so /sync-gbrain always
reported ERR brain-sync among otherwise green stages.

#1731 gave these spawns shell: NEEDS_SHELL_ON_WINDOWS. That is correct
for the gbrain.cmd shim and does nothing here: shell:true routes through
cmd.exe, which resolves .cmd/.bat via PATHEXT but has no concept of a
shebang, so an extension-less bash script is rejected outright. A .cmd
shim needs a shell; a shebang script needs an interpreter. The two cases
look identical and are not.

The failure was quiet rather than loud. artifacts_sync_mode defaults to
pushing curated artifacts to git, so a Windows user's learnings piled up
uncommitted in ~/.gstack indefinitely while the sync report showed one
red line out of four.

New bashScriptInvocation() resolves Git for Windows' bash explicitly and
passes the script as argv[0]. It prefers Git bash over a bare `bash` on
PATH because WindowsApps ships a bash.exe that is the WSL launcher, which
would read C:\... as a Linux path; GSTACK_BASH overrides for unusual
installs; forward slashes because bash treats backslashes as escapes; and
it returns null when no bash exists so the stage says so plainly instead
of surfacing an unactionable spawn error.

The #1731 tripwire asserted the shape that does not work, so it now
asserts the opposite (never a raw spawnSync(brainSyncPath, ...)) and six
unit tests cover the resolver.

Verified on Windows: the stage now reports "OK brain-sync curated
artifacts pushed (4.2s)" and the artifacts repo committed + pushed on its
own. Affected-test set unchanged at 14 pre-existing failures before and
after, with 6 new passing tests.

* fix(gbrain): quote cmd.exe arguments at a single gbrain invocation seam

Fixes #2471. With shell:true on Windows, node/bun join argv into one cmd.exe
string without quoting, so a repo path with a space — the default
C:\Users\First Last\ layout — split into two arguments and every gbrain call
carrying a path silently targeted the wrong location (worst: `sources add
--path`). All gbrain CLI invocations now build their (cmd, argv, shell)
triple through gbrainInvocation(), which quotes risky arguments for cmd.exe's
re-parse (embedded quotes doubled). The four direct spawn sites in
lib/gbrain-sources.ts route through the seam; the #1731 static invariant is
upgraded for seamed files (any direct "gbrain" opener is the violation) and
kept as-is for lib/gbrain-local-status.ts. POSIX behavior unchanged
(shell:false, passthrough argv).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(brain-sync): classify queue entries, rewrite surgically, re-push stranded commits

Fixes #2549 (P0 data loss). Every drain exit previously truncated the WHOLE
queue (six `: > "$QUEUE"` sites), which (a) destroyed privacy/mode-held
entries while misattributing them as "no allowlisted changes", (b) destroyed
entries enqueued concurrently during the drain, and (c) left push-failed
commits stranded locally with nothing ever re-pushing them until unrelated
new work arrived.

Now: compute_paths_to_stage classifies every entry (stageable / retained
privacy-held / dropped skipped-invalid-unmatched-missing); rewrite_queue
re-reads the LIVE queue at mv time and removes only this drain's processed
paths (retained + concurrent appends + unparseable lines survive; atomic
tmp+mv); an unpushed-commit detector at run start re-pushes stranded local
commits (receipted fail-closed; a receipt refusal skips the retry rather
than wedging the drain; guards missing origin/<branch>; runs inside the
existing lock). Status lines carry counts; full drop paths go to a 0600
sidecar (.brain-sync-drops.json) so filenames stay out of transcripts.
--drop-queue remains the one intentional truncation.

Matrix added: privacy retention, unmatched/missing counted drops + sidecar
mode, unparseable-line preservation, surgical same-drain retention, push-fail
commit retention + detector re-delivery on an EMPTY queue, receipt-refusal
skip. 35/35 in test/brain-sync.test.ts.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(gbrain): make --full do a full code walk, not a delta one

`runCodeImport()` walked with a bare `gbrain sync --strategy code --source X`.
The strategy is right, but that walk is incremental: it only revisits files
changed since the source's checkpoint. A file missed at the ORIGINAL import is
therefore never revisited and stays out of the index indefinitely.

The reindex-code pass below cannot rescue it. It re-chunks pages that already
exist and never walks the filesystem — the same property the comment directly
above already relies on when explaining why the walk has to run first. That fix
landed one flag short: it made a fresh source get pages at all, but left
`--full` unable to discover a file the first walk skipped.

Net effect: `/sync-gbrain --full` did not perform a full walk, and re-running it
never re-detected the gap.

The failure is silent, which is what makes it expensive. Nothing errors, nothing
warns, and the verdict block still reports OK while `gbrain search` and
`gbrain code-def` answer out of a partial index. It reads as "gbrain is weak at
code questions" rather than "the index is incomplete".

Measured on two local code sources before and after this change, counting
exported functions resolvable via `gbrain code-def`: one went from 61/201 (30%)
to 180/201 (89%), importing 79 files that had no page at all; the other had
whole source files missing entirely and reached 93%. Both had been serving
search from a partial index for weeks.

Scoped to `--full` so incremental runs stay fast. `--yes` because this spawns
non-interactively and a full walk otherwise prompts to confirm import cost.

Anyone can check their own brain without applying this:

    gbrain sync --source <id> --strategy code --full --dry-run

and compare "N file(s) would be imported" against that source's page_count.
Worth knowing while doing so: the default strategy is markdown and --strategy
is per-invocation, never persisted on the source, so dropping the flag reports
strategy=markdown and a handful of files.

* fix(brain-cache): honest 'missing' instead of fabricated-empty digests on gbrain failure

A gbrain-unreachable failure in fetchRecentDecisions and fetchSalience
used to be converted into a cached 'successful' empty digest ("_No prior
skill runs recorded._" / "_No salient pages in last 14d._") that
refreshEntity stamped with last_refresh. The false negative then
survived every subsequent TTL cycle, indistinguishable from a genuine
zero-rows result. Now failure returns null, so cmdGet's existing
missing/stale-fallback machinery reports the true state — matching what
fetchGoals and fetchSimplePage already do on failure.

Also adds an Array.isArray guard in fetchRecentDecisions so a malformed
payload ({pages: {}} etc.) classifies as failure instead of crashing
refreshEntity mid-refresh; a genuinely empty pages array still renders
the honest empty digest.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(test): give the schema-mismatch rebuild test a load-proof budget

The rebuild path refreshes every per-project entity against the real gbrain
CLI; with an unreachable brain each spawn runs to its own timeout, and under
machine load the stack exceeds bun's 5s default (observed 5.2-5.4s,
identically on pre-#2587 binaries — a load flake, not a regression). 30s
budget matches the sibling brain-sync suite's convention.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(memory-ingest): parse the current Codex response_item rollout shape

Fixes #2105. Codex rollout JSONL moved to
{ type: 'response_item', payload: { type: 'message', role, content: [...] } };
the parser's legacy payload.message branch never fired on it, so every Codex
session imported as an empty shell (message_count: 0 — 243/243 sessions on
the reporting machine). Both shapes now parse; non-message response_items
(reasoning etc.) are ignored. parseTranscriptJsonl exported for direct unit
tests (CLI path unchanged — import.meta.main guard).

Note: #2104's staging-in-gitignored-tree half is already defended on main
(--include-gitignored + GIT_CEILING_DIRECTORIES, #2144, plus the #2486
reconcile guard) — verified, no change needed; it moves to the close-only
roster.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(test): refresh codex/factory ship goldens from post-#2588 regeneration

The #2588 absorb refreshed all three ship goldens, but `bun run
gen:skill-docs` regenerates the CLAUDE host only — the codex/factory goldens
were copied from artifacts rendered before the resolver change and failed
against a fresh external-host regen in the serial test phase. Re-rendered
with --host codex / --host factory and re-copied.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(make-pdf): boolean flags no longer swallow the next positional argument

Fixes #2514. The parser treated any non-flag token after a flag as its value,
so `$P generate --toc essay.md` ate essay.md as --toc's value and failed with
"missing input" — the skill's own documented usage only worked when two
boolean flags happened to be adjacent. BOOLEAN_FLAGS enumerates the no-value
flags; value flags (--watermark, --to, --title, ...) are unchanged. main()
now runs behind import.meta.main so tests import the parser directly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(repo-mode): probe GNU stat before BSD so Git Bash stops crashing

Fixes #2195. On GNU coreutils `stat -f` SUCCEEDS (filesystem status, not a
format string), so the BSD-first fallback chain never fell over — it fed
multi-word filesystem output into the cache-age arithmetic and crashed under
set -u on Windows Git Bash. GNU `stat -c` fails cleanly on BSD/macOS, making
GNU-first deterministic on both; the mtime is numeric-validated before
arithmetic as a last line of defense.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(retro): point the prior-retros context query at files /retro actually writes

Fixes #2552's live half. The gbrain context-query glob targeted
~/.gstack/projects/<slug>/retros/*.md — a directory and extension nothing
writes — so prior-retro recall was dead on every brain-aware run. /retro
saves to .context/retros/*.json (repo-local); the query now reads that. The
issue's second defect (quoted-tilde orphan sweep) is already fixed on main —
the preamble sweeps with "$HOME/..." — verified, no change needed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(sync-gbrain): remove the capability-check page file left in the user's repo

Fixes #2503. On worktree-pinned brains `gbrain put` materializes the checked
page as _capability_check_<pid>.md in the current directory (the user's
repo), and `gbrain delete` removes the page but not the file — every
/sync-gbrain run left a stray file in the repo root. The check now deletes
the materialized file explicitly after the page delete.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(browse): warn that hover scrolls and the daemon tab persists across sessions

Fixes #2445. Both behaviors are by design but produced confidently wrong
verification output: hovering a below-the-fold element scrolls the page
before a "rest state" screenshot (exit 0, wrong section), and the daemon's
tab survives sessions so a bare `reload` can act on whatever earlier work
left open. The screenshot-evidence section now names both traps with the
concrete guards (assert window.scrollY; always goto before verifying).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(gitattributes): pin *.txt to LF

.gitattributes pins LF for every other text format in the repo (*.md,
*.tmpl, *.yml, *.yaml, *.json, *.toml, *.sh, *.ts, extensionless scripts,
even the hash-pinned diagram-render dist files). *.txt is the one text
format left unpinned.

On Windows with core.autocrlf=true, that means the two tracked .txt files
are rewritten to CRLF at checkout and then read as permanently modified:

  gstack/llms.txt                                   +174 bytes
  make-pdf/test/fixtures/combined-gate.expected.txt  +20 bytes

git status is never clean, and /gstack-upgrade's 'git stash' step saves a
phantom stash on every upgrade — one that pops back to an empty diff.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(setup): install every skill runtime asset for the Claude host

On a fresh Claude install, link_claude_skill_dirs installed only SKILL.md
(+ sections/) per skill. Every skill that reads a sibling runtime file at
.claude/skills/<name>/<file> was broken out of the box: /review stopped at
'Read .claude/skills/review/checklist.md' (file never installed), and qa's
templates/references, plan-devex-review's dx-hall-of-fame.md,
gstack-upgrade's migrations/, and careful/freeze's bin/ hooks were all
silently missing. Codex/Factory/OpenCode/Kiro installers already copied
these; the primary host never did.

Fix: a shared _link_skill_runtime_assets helper installs EVERYTHING a skill
ships next to its SKILL.md, with an explicit exclusion list (F7):
node_modules, dist, test, *.tmpl, hidden files. Exclusion-list polarity
means a newly added asset installs by default instead of being silently
dropped. Assets refresh unconditionally on re-run (rm + relink/copy), so
Windows real-dir copies pick up changes after git pull.

New free test runs the real installer functions against the live repo into
a temp skills dir with a TWO-CLASS referenced-paths assertion (ENG-OV7):
alias-relative refs (.claude/skills/<name>/<path>) must exist under the
install; repo-anchored refs (~/.claude/skills/gstack/<path>) must exist in
the tree modulo an explicit built-artifact allowlist (browse/design/
make-pdf dist + the compiled gstack-global-discover). Known-broken class-2
refs (#2250 bare bin names) are ratcheted: the test fails if they quietly
start existing without the entry being removed.

Fixes #2317
Fixes #2454

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(setup): alias skills install as rewritten copies, never symlinks

The two back-compat alias dirs — _gstack-command (root router) and
connect-chrome (→ open-gstack-browser) — symlinked the canonical SKILL.md
verbatim, so each alias re-served the canonical frontmatter name:. Claude
Code keys skills on that name and requires global uniqueness: the
connect-chrome duplicate silently shadowed /open-gstack-browser (whichever
readdir returned first won), and the _gstack-command duplicate could drop
the ENTIRE personal-skills set — every /gstack command vanished until the
user hand-deleted the alias dirs, and the next setup re-broke it.

Fix: copy-then-rewrite. A shared _install_alias_skill_md helper reads the
SOURCE SKILL.md and writes a fresh copy with name: rewritten to the alias
dir's own name (_gstack-command / connect-chrome / gstack-connect-chrome).
sed never edits in place: on Unix the old install was a symlink into the
repo, and an in-place rewrite through it would have corrupted the generated
source (eng review E2). bin/gstack-relink gets the same treatment for its
root-alias helper, and its discovery loop now skips symlinked source dirs
so the connect-chrome repo symlink can't re-mint the duplicate.

Tests assert: installed aliases are NOT symlinks, carry their own unique
names, all installed frontmatter names are globally unique, re-runs refresh
cleanly, legacy symlinked aliases are replaced not written through, and the
source files stay byte-intact.

Fixes #2511
Fixes #2201

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(setup): Windows re-runs refresh installed skills for codex/factory/opencode hosts

On Windows (Git Bash / MSYS2, no Developer Mode), _link_or_copy installs
REAL directory copies. The install guards in link_codex_skill_dirs,
link_factory_skill_dirs, link_opencode_skill_dirs, and create_agents_sidecar
only ran the copy when the target was a symlink or missing — true on the
first install, never again. Every subsequent ./setup after a git pull
reported 'gstack ready (codex).' and exited 0 while silently refreshing
nothing: users ran stale SKILL.md forever. (link_claude_skill_dirs already
handled this; the other hosts never got the treatment.)

Fix: all five guard sites bypass the symlink-or-missing check when
IS_WINDOWS=1 — _link_or_copy rm -rf's the destination first, so the real-dir
copy refreshes in place. Unix behavior is unchanged (symlinks still pass the
guard via -L and serve updates without re-copying).

The new bash-fixture test drives the REAL extracted functions through the
install → upstream change → re-run cycle under IS_WINDOWS=1 (v1 must become
v2), pins the sidecar-skip behavior, checks the Unix path stayed a symlink,
and statically asserts the bypass at all five sites so factory/opencode
can't regress. Registered in the Windows-safe curated list
(KNOWN_WINDOWS_SAFE) so it actually runs on the windows-latest CI lane —
the 'bin/' pattern hit is a fixture path segment, not a shebang spawn.

Fixes #2444

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(uninstall): remove real-directory skill installs, gated on provenance

On Windows, setup installs skills as REAL directory copies (cp -R via
_link_or_copy). gstack-uninstall's per-skill loop filtered on [ -L ], so
every copy was skipped: --force exited 0 and printed 'gstack uninstalled.'
while leaving ~52 gstack-* directories plus _gstack-command/ behind in
~/.claude/skills. The same filter also missed the standard Unix shape (real
dir + symlinked SKILL.md), which was left as a dangling-symlink husk.

Fix: the loop now handles all three install shapes. Symlink entries keep
the existing readlink check. Real dirs with a SYMLINKED SKILL.md are removed
when the link points into gstack (same semantics as setup's cleanup
helpers). Real dirs with a REAL-FILE SKILL.md — the Windows copy shape — are
removed ONLY when both provenance gates pass (F8): (a) the directory name is
in gstack's skill inventory (source dir names, frontmatter names, gstack-
prefixed variants, and the alias dirs), and (b) the SKILL.md carries the
existing generated banner '<!-- AUTO-GENERATED from' (ENG-OV10: every
pre-v1.67 copy already carries it; a NEW marker would refuse to delete
legitimate old installs, recreating the bug). Anything failing a gate is
listed to stderr and never deleted — a user's own skill that happens to
share a name with a gstack skill survives.

Tests: a fake-tree fixture covers removed/kept/listed for every shape
(including the F8 name-collision row), and a census test asserts every
installable skill's generated SKILL.md carries the banner so the gate can't
strand a bannerless skill. Registered in the Windows-safe curated list —
the copy shape is exactly what windows-latest exercises.

Fixes #2563

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(setup): wire --host cursor through the full install path

'./setup --host cursor' was accepted by the flag parser and then did
nothing: no INSTALL_CURSOR branch existed, so the script built binaries,
printed no 'ready' line, and installed zero skills — Cursor users had no
way to install gstack at all.

Full install slice, re-derived from PR #2547 by @szsunyuan onto the
current installers: generate .cursor/ skill docs (host config already
existed), create a minimal ~/.cursor/skills/gstack runtime root (root
SKILL.md + bin/lib/browse assets + review checklist pair + ETHOS.md +
supabase config — bin and lib travel together because bin scripts import
../lib), link the generated gstack-* skills, and plant the repo-local
.cursor/skills/gstack sidecar WITHOUT ever wiping the generated SKILL.md
files it shares a directory with (link-before-sidecar ordering keeps the
generation fallback alive). Auto mode detects Cursor via the cursor
binary or the ~/.cursor footprint. gstack-uninstall removes
~/.cursor/skills/gstack* and per-project .cursor/skills/gstack* — and
never rmdir's .cursor itself, where Cursor stores user rules.

Re-derivation deltas from the PR: the link guards carry the #2444
IS_WINDOWS bypass (re-runs refresh real-dir copies), lib/ and
supabase/config.sh ride along like every other runtime root, and the
hosts/cursor.ts sidecar field is omitted (HostConfig no longer carries
one — sidecar behavior lives in setup).

Fixes #1358

Co-authored-by: Yuan Sun <forrest.sun527@gmail.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(settings): include command in add-event dedup key (#2382)

Fixes #2382.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(setup): render the gbrain :user variant to an out-dir — global installs stay git-clean

On a global-git install with gbrain, ./setup and 'gstack-config
gbrain-refresh' ran gen:skill-docs:user IN PLACE inside the install
checkout, rewriting ~16 TRACKED SKILL.md files. The checkout stayed
permanently dirty, every /gstack-upgrade 'git stash' saved a redundant
snapshot of generated content, and the growing stash list invited a 'git
stash pop' that would lay stale instruction markdown from an older gstack
over the current version — a quiet wrong-rules failure mode.

Fix, wired through machinery that already existed (gen-skill-docs
--out-dir + the symlink install layer): brain-aware SKILL.md now renders
into the untracked ~/.gstack/render/claude, and both Claude installers
serve the render when present — setup's link_claude_skill_dirs prefers
$GSTACK_HOME/render/claude/<skill>/SKILL.md, and bin/gstack-relink does
the same so a later config change can't silently flip skills back to the
blockless canonical source. setup wipes and rebuilds the render each run,
repoints installed skills after a successful render, and removes a stale
render (re-linking canonical) when gbrain is gone. gbrain-refresh renders
to the out-dir and repoints via relink; its 'this dirties the install's
git tree' caveat is retired because it no longer does.

A one-time upgrade migration (gstack-upgrade/migrations/v1.67.0.0.sh, F12)
restores the legacy dirt: unstaged modifications to SKILL.md / sections/
*.md files in the install checkout are git-checkout'd back to canonical;
anything outside that footprint (user edits, untracked files, staged work)
is left alone and reported. Idempotent, non-fatal, symlinked installs
skipped.

Tests: render-preference behavior for both installers, static pins that
every executable :user invocation carries --out-dir and the caveat text is
gone, migration fixture (restore/leave/idempotent/no-op matrix), and the
existing out-dir render test now asserts 'git status --porcelain' gains
zero new entries across a full :user render.

Fixes #2569

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(redact): close the remaining #1946 fail-opens — detection coverage + one-time consent

Two of #1946's reported gaps were still open after the v1.64 fail-closed
work (the git-error and oversized-diff paths in bin/gstack-redact-prepush
are already strict, chunked, and pinned by tests):

1. Detection fail-open: env.kv required an UPPERCASE name with an '='
   assignment, so 'api_key=…', 'apiKey: "…"', and 'password: …' — the
   most common real config shapes — produced NO finding at all. The pattern
   is now case-insensitive, accepts ':' (YAML/JSON) as well as '='
   assignment, and handles quoted JSON keys. It stays MEDIUM and
   entropy-gated per the calibration rule (a generic net that cries wolf
   gets bypassed), with pinned cases for each closed shape plus the
   placeholder/entropy negatives.

2. Install fail-open: nothing ever offered the guard, so a plain 'git
   push' scanned nothing and users believing themselves protected weren't.
   setup now asks ONCE for consent on a real interactive terminal
   (maintainer decision 6): an explicit answer is recorded to the existing
   redact_prepush_hook key and never re-asked; a timeout or non-interactive
   run changes nothing and keeps the hint-only posture. Default stays
   FALSE, and setup still never installs the hook itself — /ship owns the
   per-repo install (the wrong-repo invariant is pinned by the existing
   'setup carries the hint only' test).

Tests: per-shape pattern cases, prompt gating statics (key-absence + TTY +
timed default-N read), timeout-persists-nothing, non-interactive stays
hint-only with no key write, and recorded-answer-is-silent behavior runs.

Contributes to #1946 (the pre-push guard's fail-closed scan paths landed
in earlier releases; this closes the coverage and consent gaps it names).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(hooks): Stop hook closes dangling timeline entries — fail-open

The preamble writes event:'started' to the project timeline at every skill
start, but the matching 'completed' write lives in prose at the END of the
skill workflow — unenforceable. An interrupted session, a context blowout,
or an agent that simply stops leaked started > completed forever, and the
leak was unrepairable after the fact (observed live in #2553).

New hosts/claude/hooks/timeline-stop-hook (+ .ts, question-log-hook shim
pattern): on Claude Code's Stop event it appends event:'completed' with
outcome 'unknown' and source 'stop-hook' for every 'started' entry in the
project timeline that has no matching completion. setup registers it via
gstack-settings-hook add-event (Stop was already an accepted event) under
its own source tag, idempotently; --no-team and gstack-uninstall remove it.

FAIL-OPEN contract (F5), pinned by tests: ALWAYS exits 0 — corrupt
timeline (bad lines skipped individually, valid ones still repaired),
missing timeline, garbage/empty stdin, bun missing from PATH (the shim
'|| true's), and an over-cap timeline (10MB skip) all repair nothing and
block nothing; errors land in ~/.gstack/hook-errors.log best-effort. The
write path is append-only with a ~2s internal budget, and a second Stop is
a no-op (already-closed entries never re-close). Correlation is
project-scoped by design — the preamble's session id is shell-local, so a
concurrent same-project session's entry may close early as a traceable
source:'stop-hook' row rather than a silent leak; the header documents the
trade-off.

Fixes #2553

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ios-qa: guard DebugBridgeTouch.m on DEBUG, not just TARGET_OS_IOS

DebugBridgeTouch.m and its header both promise the code is DEBUG-only and
never shipped:

    "Uses these private UIKit selectors (DEBUG-only; never shipped to App Store)"
    "DEBUG-only — never link in Release."

Nothing enforced it. The only guard was `#if TARGET_OS_IOS`, so a Release build
for iOS compiled the entire implementation in, private API and all.

Measured on a real app (an iOS Release build, `nm -j` on the app binary):

    DebugBridge symbols            15
    IOHIDEventCreateDigitizer       2
    AXSSetAutomationEnabled         1 symbol, 2 strings
    IOKit.framework                 4 strings

including +[DebugBridgeTouch sendTapAtPoint:inWindow:] and
_OBJC_CLASS_$_DebugBridgeTouch. That is a Guideline 2.5.1 private-API exposure
in a shippable binary, and it fails Package.swift's own stated CI invariant:

    nm -j build/Release/<binary> | grep -q DebugBridge && exit 1

WHY THE EXISTING GUARD DOES NOT COVER THIS

Package.swift documents the protection as `.when(configuration: .debug)` on the
consuming target's dependency. That works for SwiftPM consumers. It cannot be
expressed by an app that integrates DebugBridge as a local package inside an
.xcodeproj: Xcode's Filters column under Frameworks, Libraries, and Embedded
Content offers platform conditions only — iOS, macOS, visionOS — never build
configuration. So for xcodeproj consumers the documented guard silently does
nothing, which is precisely the case that was measured.

The Swift targets were already safe: all four .swift files are `#if DEBUG`
guarded and Package.swift defines DEBUG for them via swiftSettings. Only the
Objective-C target, the one that actually links private API, was unguarded.

THE FIX

1. DebugBridgeTouch.m.template now branches `#if !defined(DEBUG)` first and
   emits nothing at all in Release, falling through to the existing iOS and
   non-iOS branches only in Debug.

2. Package.swift.template declares DEBUG explicitly for the ObjC target:

       cSettings: [.define("DEBUG", .when(configuration: .debug))]

   The two Swift targets already did this. Relying on SwiftPM's implicit DEBUG
   for C-family targets is not worth betting a private-API exposure on.

VERIFIED, by compiling the generated file for iOS both ways:

    xcrun -sdk iphoneos clang -c DebugBridgeTouch.m -arch arm64 ...

    Release (no -DDEBUG)   0 DebugBridge symbols, 0 private-API symbols,   448 B
    Debug   (-DDEBUG=1)    7 DebugBridge symbols, 6 private-API symbols, 13104 B

The harness is unchanged in Debug. Release now emits an empty translation unit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(ios-qa): bridges search front-most presented content first

A presented sheet sits AFTER the screen it covers in window.subviews, so
the elements walk emitted the covered screen first — a client taking the
first match for a label activated a control the user cannot reach, and
the agent saw a success (measured on a real app: the sheet's 'Create'
button ranked 210th behind 35+ covered-screen entries). Menus, alerts and
action sheets were worse: each gets its OWN UIWindow, so keying off
isKeyWindow missed them entirely — absent from /elements, dropped from
/screenshot, untappable via /tap.

Re-derived from PR #2397 by @IDSTUK onto the current bridge templates
(the SwiftUI tap-reliability rework had moved underneath the PR):
ScreenshotBridgeImpl gains orderedWindows(in:) (visible windows front-most
first by windowLevel then insertion order, PassThroughWindow overlays
still filtered), frontmostWindow(), and searchRoots() (per window, the
top-most presented view controller's view before the window itself).
/elements walks those roots in order through the existing shared
visited-set + budget, so overlapping roots emit each view once at its
front-most position; /tap targets frontmostWindow() for both the
accessibility-activation and synthesized-touch paths; /type and /swipe
search the roots in order; /screenshot composites every window
back-to-front at the existing 1x scale. The two now-dead private
activeScene/activeKeyWindow copies in ElementsBridgeImpl and
MutationBridgeImpl are removed.

Fixture mirror synced byte-for-byte; verified with a full
'xcodebuild build -scheme FixtureApp-Package -destination
generic/platform=iOS Simulator' (BUILD SUCCEEDED, DEBUG guard from the
previous commit included).

Co-authored-by: IDST UK <IDSTUK@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(setup-gbrain): invoke gstack-memory-ingest/gstack-gbrain-sync via bun run + .ts

/setup-gbrain's transcript-ingest steps told the agent to run
bin/gstack-memory-ingest and bin/gstack-gbrain-sync by BARE name. Neither
exists — only the .ts files ship (mode 644, no bin alias) — so the agent
dutifully reported 'script missing at install root' and the ingest/full-
sync steps dead-ended on every host (hit live under Codex; the Claude
render carries the same text).

All four template sites (probe, silent-bulk, post-answer full sync, the
preamble-hook incremental mention) and the four memory.md reference-doc
sites now use the repo's established form: 'bun run <path>/gstack-memory-
ingest.ts …' / 'bun run <path>/gstack-gbrain-sync.ts …' — matching what
sync-gbrain already does. Generated SKILL.md regenerated from the template
in the same commit.

Re-derived from PR #2409 by @SomSamantray per the wave's screening rule
(the PR edited the generated SKILL.md directly; the generated file must
come from gen:skill-docs). The contributor's structural test rides along
as-is: bare-invocation regexes with negative .ts lookahead and backslash-
continuation coverage pin every site, so the drift can't return. The
referenced-paths ratchet in test/setup-claude-skill-assets.test.ts drops
its two #2250 known-broken entries — the class-2 assertion now guards
these paths again.

Verified against #2250's site list (template lines 690/735/784-area, all
covered) plus a fresh grep: zero bare invocations remain in the template
or memory.md; the one prose mention ('gstack-memory-ingest now persists…')
is not an invocation and stays.

Fixes #2250
Fixes #2393

Co-authored-by: SomSamantray <SomSamantray@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(test): update four main-side assertions to the T3 installer contracts

Integration drift from the T3 lane: three static assertions pinned the OLD
implementation shapes that T3 legitimately replaced — the gbrain-refresh
branch no longer self-documents a reset --hard cycle (#2569 renders to an
untracked out-dir instead; the test now pins THAT), setup's regen block
renamed to the render form (re-anchored, same exit-code-propagation
invariant), and sections/ linking generalized into _link_skill_runtime_assets
(the _link_or_copy routing assertion moved into the helper). Fourth: the
uninstall neutral-target test asserted against os.tmpdir(), which reads
$TMPDIR at call time — a shard neighbor can leave it gstack-containing,
making the "neutral" symlink target match the provenance substring; the test
now falls back to a fixed neutral root and asserts neutrality explicitly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: whitelist engine-locked at all three gbrain-usable gates (#2456)

#2194 taught the classifier to report a PGLite lock held by a live
\`gbrain serve\` as engine-locked instead of broken-config, but none of the
three "is gbrain usable?" gates accepted the new status — so the symptom
moved from a wrong error to a quieter wrong suppression: gbrain-refresh
stripped GBRAIN_CONTEXT_LOAD / GBRAIN_SAVE_RESULTS blocks out of every
generated SKILL.md after every upgrade, on the RECOMMENDED /setup-gbrain
default (PGLite + local-stdio MCP spawns gbrain serve at session start).

engine-locked is the same class as timeout (#1964): the engine is
installed and healthy, a legitimate holder has the lock. All three gates
now agree:

- bin/gstack-gbrain-detect --is-ok exits 0 on engine-locked
- bin/gstack-config gbrain-refresh case arm renders instead of suppressing
- scripts/gen-skill-docs.ts --respect-detection treats it as detected

Test mirrors the existing timeout case in
test/gbrain-detection-override.test.ts (engine-locked renders brain
blocks; the sibling no-cli case still proves suppression works).

Applies the reporter's patch + test from the issue.

Fixes #2456

Co-authored-by: Mateus Moraes <mmoraes@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: detect bearer-token thin clients via host MCP registration (#2520)

The #2051 thin-client fix keys detection on the remote_mcp marker in
~/.gbrain/config.json — but that marker is only written by the OAuth path
(gbrain init --mcp-only). Bearer-token installs (gbrain connect <url>
--token, gbrain's own recommended default for local/personal use) never
touch config.json, so they fell through to the local probe, failed against
the dead-or-absent local engine, and landed on missing-config / broken-db /
broken-config / engine-locked — silently suppressing brain blocks for a
fully-working remote brain.

New evidence source: hasRemoteOnlyGbrainMcp() reads ~/.claude.json MCP
registrations (user scope AND project scope) with the same classification
rules as gstack-gbrain-detect's tier-3 fallback. File-read only — no
subprocess, no network (a classifier network probe is the #1964 pathology).
Wired at two sites in freshClassify:

- missing-config branch: a bearer thin client may never have run a local
  init; if the host's only gbrain registration is remote-HTTP, that
  registration IS the brain → thin-client.
- post-probe-failure demotion: broken-db / broken-config / engine-locked
  reclassify to thin-client when the only gbrain registration is remote.
  A local-stdio sibling registration blocks the demotion (federation
  guard: a user running a local engine plus a remote team brain keeps
  precise local statuses). "timeout" is excluded — already usable, and
  may be a genuinely healthy slow local engine.

7 new unit tests in test/gbrain-local-status.test.ts: user-scope, project-
scope, engine-locked/broken-db demotion, federation guard, no-registration
discriminator, end-to-end --is-ok gate (35 pass total in the file).

Root-cause analysis by @d-danielsun in #2520.

Fixes #2520

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: resolve GBRAIN_HOME with gbrain's parent-dir semantics (#2521)

gstack treated GBRAIN_HOME as the config directory; gbrain's configDir()
treats it as the PARENT and always appends `.gbrain` itself (the contract
is explicit in gbrain's source: GBRAIN_HOME=/tmp/x → /tmp/x/.gbrain/
config.json). With GBRAIN_HOME set, gstack classified engine status from
a file gbrain never reads — the probe's two halves (file checks vs the
spawned `gbrain sources list`) looked at DIFFERENT installs, so any
resulting status was arbitrary: missing-config/broken-config against
healthy installs, or a thin-client marker gstack saw that gbrain itself
reported as "No brain configured".

New shared resolver `gbrainConfigDir()` in lib/gbrain-exec.ts is the
single source of truth. All seven gstack sites route through the contract:

- lib/gbrain-local-status.ts gbrainConfigPath (the classifier's file half)
- bin/gstack-gbrain-detect GBRAIN_CONFIG + readRemoteMcpUrl
- lib/gbrain-exec.ts buildGbrainEnv (the probe's DATABASE_URL seed —
  fixing only the classifier would have left the split-brain in the
  spawn half, flagged by the reporter)
- lib/gbrain-guards.ts gbrainHome (clones-dir + autopilot-lock paths)
- lib/gstack-memory-helpers.ts gbrainConfigPath (engine-tier fallback)
- bin/gstack-gbrain-install pre-doctor config check (shell)

Unit tests cover GBRAIN_HOME set (config found at $GBRAIN_HOME/.gbrain),
the old flat layout explicitly NOT read (both classifier and
buildGbrainEnv), and unset (~/.gbrain unchanged). Existing fixtures that
encoded the deviant flat layout are updated to gbrain's contract.

Root-cause analysis by @d-danielsun in #2521.

Deviation from the 3-site plan spec: the same deviant resolution existed
in four more sites (buildGbrainEnv, gbrain-guards, memory-helpers,
gbrain-install); fixing only three would have left gstack disagreeing
with itself as well as with gbrain, so the whole class moved to the
shared resolver in one change.

Fixes #2521

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: read project-scoped MCP registrations in gbrain detection (#2499)

Claude Code registers MCP servers at two scopes in ~/.claude.json: user
scope (.mcpServers) and project scope (.projects["/abs/path"].mcpServers
— what `claude mcp add` WITHOUT --scope user writes). Every gbrain
detection site read only user scope, so a correctly configured
project-scoped brain was invisible: brain-aware blocks suppressed,
remote-mode artifacts sync never recognised, and detectEndpointHash fell
through to the 'local' literal — two different project-scoped brains
hashed identically, so switching between them never invalidated the
cache, the exact scenario the function's docstring says it exists to
catch. Nothing errored; the features just quietly were not there.

Two sites fixed:

- scripts/resolvers/preamble/generate-brain-sync-block.ts: the shared
  detection block (rendered into every tier-2+ SKILL.md) now resolves the
  gbrain entry ONCE into _GBRAIN_MCP_ENTRY — user scope first, then the
  nearest-ancestor project entry for $PWD that actually carries a gbrain
  server (longest matching key with a path-boundary check: /a/repo never
  matches /a/repo2; a nested project WITHOUT gbrain doesn't shadow its
  parent's registration). _GBRAIN_MCP_TYPE and _GBRAIN_HOST extract from
  the resolved entry, so claude.json is parsed once per skill start. All
  SKILL.md files regenerated in this commit; the ship golden fixtures and
  three carve-guard skeleton caps (plan-eng-review, plan-devex-review,
  office-hours; ~1.5KB rendered growth per skill) are refreshed with
  measured values.
- bin/gstack-brain-cache detectEndpointHash: same resolution order in TS
  (user scope, else nearest-ancestor project entry by cwd, both path
  separators for Windows keys).

Tests: rendered-output tests in test/gen-skill-docs.test.ts pin the
regenerated block (static markers + a FUNCTIONAL run of the exact
rendered lines against a fixture ~/.claude.json with only a
project-scoped registration, plus an outside-cwd discriminator);
detectEndpointHash unit tests in test/brain-cache-roundtrip.test.ts cover
project-scope resolve, path-boundary, nearest-ancestor distinct hashes,
and user-scope precedence.

Root-cause analysis by @samporter-31 in #2499.

Fixes #2499

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: /sync-gbrain respects an existing valid .gbrain-source pin (#2417)

/sync-gbrain always derived a new worktree-scoped source ID, even when
the repository already carried a valid .gbrain-source pin created through
the native GBrain source workflow — silently bypassing the selected
source boundary, registering a duplicate federated source, and routing
later dream/cycle checks to the wrong source.

Now a local pin is reused when it passes the fail-closed identity checks:
the ID is syntactically valid, the source is registered, and the
registered path realpath-resolves to the current checkout (so a stale or
copied dotfile can't redirect a sync into another repo's source). A
confirmed pin is treated as user-managed — synced and attached without
add/remove, legacy migration, or federation changes. Dry-run stays
spawn-free (reads only the local marker for previews). Missing, invalid,
stale, or unreadable pins fall back to the existing generated source ID.

Absorbs PR #2417 by @exGeni (applied via git am -3; 42 tests pass in
test/gstack-gbrain-sync.test.ts including the new pin-respecting
coverage: spawn-free dry-run, symlink-equivalent registered paths,
non-dry-run sync/attach with no add/remove, dream routing, unreadable
markers, config-backed env use).

Co-authored-by: Evgenii Lopatin <e75533@gmail.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: gstack-gbrain-install --dry-run no longer requires the network (#2540)

The GitHub reachability probe (curl --head, 10s max) was gated only on
--validate-only, so a --dry-run — which prints a plan and exits without
ever cloning — could fail with exit 3 "cannot reach https://github.com"
whenever the curl lost a race for sockets/DNS. Reproducible at ~15% by
running 60 dry-runs concurrently, and the cause of intermittent red in
the D5 detect-first tests, which call this exact path.

The probe now also skips under --dry-run: requiring the network for a
plan-print buys nothing and costs a real failure mode. Real installs
still fail fast when offline rather than hanging git clone.

Absorbs PR #2540 by @CarringtonCreative (applied via git am -3;
26 tests pass across test/gbrain-detect-install.test.ts +
test/egress-receipt-wiring.test.ts).

Fixes the offline/flake half of #2536.

Co-authored-by: Carrington Dennis <carrdenn3@gmail.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat: accept 3-digit semver + package.json version sources (#2501)

Two version-source shapes failed CLOSED in a way that silently disabled
/ship's queue-collision check:

1. A --version-path / .gstack/version-path target that is a package.json
   was read as raw text: the whitespace strip turned the JSON into
   '{"name":"frontend",... which parseVersion rejected, so every read —
   local, `git show`, and rival PRs' claims through the GitHub/GitLab
   Contents APIs — fell back to 0.0.0.0 and competing claims were dropped
   as "malformed".
2. parseVersion required exactly four components, so gstack-next-version
   exited 2 on EVERY invocation in a 3-digit repo. That CLI IS the
   queue-collision check; /ship then took its documented offline path of
   naive local arithmetic, two branches cut from the same base picked the
   same version, and git merged the duplicate without a conflict.

New lib/version-source.ts holds the shared semantics so both CLIs agree
by construction: parseVersion accepts 3- or 4-digit (3 pads the micro
slot for uniform comparison), versionWidth/fmtVersion keep a 3-digit repo
3-digit through bumping and formatting, micro coerces to patch on 3-digit
repos (with a warning in the output), and extractVersion reads a .json
version-path as JSON (.version) from any byte source. gstack-version-bump
treats a package.json version-path as that repo's single source of truth
(written in place, DRIFT_* states can't arise — no second file to drift
from). Detection is by shape, not new configuration.

Scope per the wave plan's version-tooling end-state spec (decision 11,
ENG-OV1): this is the READING capability + 3-digit acceptance ONLY.
gstack's own VERSION file stays the 4-digit source of truth; nothing here
flips authority to package.json. The PR's bundled fix for the
.gstack/version-path pin being ignored by classify's base read lands
separately (#2462) — these tests drive the JSON version-path through the
explicit --version-path flag.

Re-derived from PR #2501 by @YiftahR (73 tests pass across
test/gstack-version-bump.test.ts, test/gstack-next-version.test.ts,
test/ship-version-sync.test.ts).

Fixes #2501

Co-authored-by: YR <work.yiftah.rottem@gmail.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: write/repair sync npm lockfiles' version fields (#2567)

npm records the package version twice in its lockfiles — top-level
`version` and, in lockfileVersion >= 2, `packages[""].version` (the entry
describing the root package itself) — and `npm install` keeps both in
step. gstack-version-bump write/repair updated VERSION + package.json but
left the lockfile behind, so every /ship bump in an npm repo drifted one
field per release until someone ran npm, dirtying the tree on the next
`npm install` far from the cause.

write and repair now mirror the version into package-lock.json AND
npm-shrinkwrap.json (which shares the format and, when present, is what
npm actually honors) as a pure JSON edit — no npm spawn, no
dependency-tree churn, dependency entries untouched. Per the wave plan's
version-tooling end-state spec (decision 11): synced ONLY when the file
already exists, never created (gstack itself is bun-only). A failed
manifest/lockfile write keeps the existing exit-3 half-write semantics so
classify reports DRIFT_STALE_PKG on re-run instead of hiding the drift.

Tests: 5 new cases in test/gstack-version-bump.test.ts — both lockfile
version fields synced with deps untouched, repair heals a stale lockfile,
lockfileVersion 1 (no packages map) doesn't crash, npm-shrinkwrap.json
synced without inventing a package-lock.json, malformed lockfile exits 3
loudly (26 pass total in the file).

Re-derived from PR #2568 by @ortonom under decision 11.

Fixes #2567

Co-authored-by: ortonom <3261546+ortonom@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat: subdirectory manifests + npm-valid version mirror (#2531)

Two gaps in gstack-version-bump's manifest handling, resolved to the wave
plan's version-tooling end-state spec (decision 11):

1. Subdirectory manifests. A repo whose only Node package lives in web/,
   app/, or frontend/ has no ROOT package.json, so join(cwd,
   "package.json") reported pkgExists:false and every bump silently wrote
   VERSION alone — leaving the manifest to be bumped by hand, which is
   exactly the drift this tool exists to prevent, in the one layout where
   it silently did nothing. All three subcommands now resolve the
   manifest as --package-json-path → .gstack/package-json-path →
   ./package.json (mirroring resolveVersionPath).

2. npm-valid mirror. VERSION is 4-digit MAJOR.MINOR.PATCH.MICRO; npm's
   semver is 3-component and rejects a fourth, so mirroring the raw form
   breaks `npm ci` in any repo npm actually manages. The manifest and its
   lockfiles now carry the npm-valid 3-digit translation (1.67.0.0 →
   1.67.0) via npmVersion() in lib/version-source.ts. VERSION stays the
   4-digit source of truth. classify judges drift against the TRANSLATED
   form — a correctly-synced `0.1.25` no longer reads as eternal drift
   against `0.1.25.0` — and grandfathers the pre-v1.67 1:1 four-digit
   mirror as in-sync (flagging it DRIFT_UNEXPECTED would hard-stop /ship
   on every existing repo on upgrade day; the next write migrates the
   manifest to the translated form). Lockfiles are synced beside the
   resolved manifest — including beside a pinned JSON version-path — and
   only when they already exist.

classify output gains pkgPath and expectedPkgVersion for observability;
write/repair report packageJsonPath + packageJsonVersion. The /ship Step
12 prose (ship/SKILL.md.tmpl) documents the resolution chain and the
translation; SKILL.md files regenerated and ship golden fixtures
refreshed in this commit.

Tests: subdirectory pin + --package-json-path override, translated-form
classify (FRESH/ALREADY_BUMPED, no false drift), grandfathered 1:1
mirror, genuine divergence still drifts, repair to the npm-valid form
(33 pass in test/gstack-version-bump.test.ts; 526 pass across the five
affected files including goldens and parity).

Re-derived from PR #2531 by @CarringtonCreative on top of the 3-digit/
JSON version-source work, under decision 11 (which resolves the PR's
lockfile-gated translation in favor of an unconditional npm-valid
mirror).

Co-authored-by: Carrington Dennis <carrdenn3@gmail.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat: git-based version allocator when the PR queue is unreachable (#2545)

When the host query (gh/glab) failed, gstack-next-version returned
offline:true with an EMPTY claim set, and /ship's documented fallback was
local BUMP_LEVEL arithmetic. Local arithmetic cannot see a sibling's
claim, so the fallback allocated a version another open PR already held —
observed in a downstream repo where two merged PRs both read v0.1.57.0
(and an audit found four such duplicate pairs over three weeks).

New fetchGitClaimed() degrades the QUEUE VIEW without degrading the
ALLOCATION: git already knows what the API was asked for. It reads every
remote-tracking branch's pinned version file (through extractVersion, so
JSON version-paths resolve on remote refs too and each branch's own digit
width is preserved) plus the versions already shipped in the base's last
400 commit subjects (3- or 4-digit; the cap announces itself in warnings
when it truncates). The fallback runs only when the host told us nothing
— the online path is untouched — and the output gains a load-bearing
`fallback: "git" | null` field that /ship can branch on, plus explicit
warnings for both the recovered-from-git and the nothing-found cases.

Tests: end-to-end stub-gh offline contract (fallback:'git' + a valid
version + the warning), sibling-claim discovery from remote-tracking
refs, the pick advancing past the sibling's claim, shipped-subject
scanning, JSON version-path claims on remote refs, and non-repo
degradation to a warning (45 pass in test/gstack-next-version.test.ts).

Re-derived from PR #2545 by @CarringtonCreative under the wave plan's
version-tooling end-state spec; the PR's own VERSION/CHANGELOG stamping
is stripped (release stamping happens at /ship time, not per commit).

Co-authored-by: Carrington Dennis <carrdenn3@gmail.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: version-bump honors the .gstack/version-path pin in versionRel (#2462)

cmdClassify's current-version read already resolved the
.gstack/version-path pin, but versionRel — the repo-relative path fed to
`git show origin/<base>:<path>` — was derived from the CLI flag alone
(`argVal(args, "--version-path") ?? "VERSION"`). In a pinned repo with no
explicit flag, base and current therefore read DIFFERENT files: current
from the pinned file, base from the root VERSION. On a repo with no root
VERSION, the base always read 0.0.0.0 — and the pinned-JSON handling
never engaged, so a pinned package.json was read as raw text
(currentVersion 0.0.0.0) and `write` would have overwritten the manifest
with a bare version string.

New resolveVersionRel() resolves the pin's REPO-RELATIVE form once
(flag → .gstack/version-path first line → "VERSION"); classify, write,
and repair all derive both the relative and absolute paths from it, so
base and current reads can no longer diverge. The old resolveVersionPath
(which returned an absolute path `git show` cannot use) is folded in.

Unit tests (the ENG-OV6 spec case plus write/repair coverage): pin set +
no flag → classify reads base AND current from the SAME pinned file
(plain-text sub/VERSION and pinned frontend/package.json, both against a
real git base with NO root VERSION anywhere), write updates the pinned
manifest in place without inventing a root VERSION, repair treats the
pinned JSON as single-source, and the explicit flag still overrides the
pin (38 pass in test/gstack-version-bump.test.ts).

Re-spec'd per ENG-OV6 from the report in #2462 (the originally-filed
classify-read hypothesis was already handled; the live bug was the :138
versionRel derivation). Same fix shape independently identified in
PR #2501 by @YiftahR.

Fixes #2462

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: diff-scope glob coverage, honest exit contract, dirty-tree visibility (#2526, #2455, #2299)

Three silent-skip classes in bin/gstack-diff-scope, each of which quietly
disabled scope-gated reviewers in /ship and /review:

1. Pattern gaps (#2526, #2455). `*/api/*` required a path segment BEFORE
   api/, so a root-level api/ layout (Vercel serverless, Next.js pages/api
   at root) never set SCOPE_API — 63 serverless functions in the
   reporter's payments repo, none ever classified, the API-contract
   specialist silently skipped on every payment PR (it found a CRITICAL
   when run by hand). Same for root-level migrations/. And the Rails
   data_migrate gem's db/data/ data migrations — arbitrary Ruby run
   unattended against production data — fell through to plain BACKEND, so
   the [NEVER_GATE] data-migration specialist never got the chance to
   run. Added: api/*, migrations/*, db/data/*, data_migrations/*.

2. All-false was indistinguishable from "could not look" (#2526). New
   contract: empty change set → all false exit 0; >=1 match → flags
   exit 0; changed files with ZERO matches → SCOPE_ERROR=unmatched + the
   unmatched paths as comment lines + exit 2 (a new top-level layout now
   trips loudly instead of invisibly disabling reviewers); unresolvable
   base ref (shallow CI checkout) → SCOPE_ERROR=no_base + exit 2 instead
   of a green that means "we could not look". Every output line stays a
   shell-safe assignment or comment for sourcing consumers, which
   tolerate the nonzero exit today (source ... || true / eval).

3. Uncommitted work was invisible (#2299). /ship detects scope in Step 9,
   BEFORE it commits in Step 15, so the common start-work-then-ship flow
   ran the classifier against an empty diff and skipped every reviewer.
   The change set is now the UNION of committed diff + working tree +
   untracked files. Also from #2299: the single first-match-wins case
   made the nine flags mutually exclusive (Button.test.jsx set FRONTEND
   but not TESTS; util.test.ts the opposite) — each category now gets its
   own case, with BACKEND deliberately still excluding frontend
   component/view files. And file listing is NUL-safe (git diff -z), so
   non-ASCII paths no longer defeat extension globs via octal quoting.

Deliberate behavior change (flagged in #2299): with independent flags, a
backend test file sets BACKEND and TESTS, which can trip the security
specialist's SCOPE_BACKEND gate on test-only PRs — errs toward more
review, not less.

Table-driven tests cover every glob class (root api/, nested api/,
controllers, openapi, root/nested/prisma/db-migrate/db-data migrations,
dual-category test files, auth, prompts, docs, plain classes), the
four-state exit contract, dirty-tree + untracked visibility, and the
non-ASCII path case (39 pass in test/diff-scope.test.ts).

Fixes shaped by the reporters' patches: @grant-ship-it (#2526),…
@garrytan

Copy link
Copy Markdown
Owner

Closing: this was absorbed or superseded on main by v1.67.0.0 or earlier (see the v1.67 tracker-wave receipts in PR #2604). Thank you!

@garrytan garrytan closed this Aug 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants