v1.68.0.0 fix: next tracker wave — 16 verified fixes in, 90 stale PRs and 21 issues closed with receipts (#2632)

* fix(plan-tune): reject never-ask on one-way ids at --write

--check already ignored those prefs; --write still stored them and
--stats counted them as a working NEVER_ASK. Refuse the write and
count leftover on-disk prefs as INERT_ONE_WAY.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix: gstack-config get returns "" with exit 0 for keys that have no default

Skill preambles read configuration with

    VAR=$(gstack-config get <key> 2>/dev/null || echo "<default>")

and that fallback only fires on a non-zero exit. lookup_default ended in a
catch-all that echoed "" and returned 0, so for any key missing from the table
VAR came back empty and the default written right there in the preamble was
unreachable. The skill then branched on a value it never specified: "skip
entirely if QUESTION_TUNING is false", reached with QUESTION_TUNING="".

Four keys that skills actually read had no entry and took that path:

    question_tuning         -> callers assume "false"
    repo_mode               -> callers assume "unknown"
    team_mode               -> callers assume "false"
    transcript_ingest_mode  -> callers assume "off"

Each default above is the value the call sites already substitute in their own
`|| echo` fallback, so this only makes reachable what was already intended.

The catch-all now returns non-zero. That is deliberately scoped to the
unknown-key arm alone: keys whose default is intentionally empty still exit 0,
because "" is their real answer and their callers depend on it --
cross_project_learnings ("unset triggers the first-time prompt"),
redact_repo_visibility ("empty falls through to gh/glab detection"),
salience_allowlist, user_slug_at_*. Making every empty answer an error would
have broken those.

test/gstack-config-defaults.test.ts pins the class rather than the four
instances: it parses the case arms and asserts every `gstack-config get <key>`
site in the tree is covered, so adding a read without a default fails CI. It
also pins the exit-code contract in both directions. Verified failing against
the pre-fix script, where it names exactly those four keys.

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

* fix(redact): a typo'd subcommand no longer exits 0 having done nothing

main() recognised exactly two subcommands and let everything else fall through
to the stdin scan. On empty stdin that prints "(no findings)" and exits 0, so:

    $ gstack-redact install-prepush-hooks    # plural typo
    gstack-redact scan — repo UNKNOWN
      (no findings)
    $ echo $?
    0

No hook was installed, and the operator has every reason to believe the
credential guard is armed. A guard that silently no-ops must never exit 0.

Two smaller faults in the same dispatch, both of which lead people here:

- There was no --help handler, so `gstack-redact --help` fell through to the
  scanner. Piping a credential to it scanned the secret and exited 3.
- With no piped input and no --from-file, readInput() blocks on readSync(fd 0)
  until an EOF that an interactive terminal never sends. That prints nothing
  at all, so it reads as a hang rather than as "this is a filter, feed it".

Now: --help/-h/help prints usage and exits 0; an unrecognised positional
prints the offender and exits 1; a TTY with nothing piped in prints usage
instead of blocking. "scan" stays accepted, because the human output header
reads "gstack-redact scan — repo …" and that is what people type.

Usage errors exit 1, deliberately not 2 or 3. Those mean MEDIUM and HIGH
findings and callers gate dispatch on them, so a usage error exiting 2 would
be read as "medium findings — prompt the user". A test pins that.

Tests: 4 written failing first, then fixed. Full suite 7,722 pass / 0 fail.

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

* fix(browse): one ambiguous ref no longer kills the whole annotated screenshot

`snapshot -a` exits 1 with "Selector matched multiple elements" on most real
pages, so /qa, /canary and /land-and-deploy silently produce reports whose
screenshots do not exist. Plain `screenshot <path>` is unaffected.

Refs are built as getByRole(role, {name}) and disambiguated with .nth() when
role+name repeats. That disambiguation cannot fire for a node with NO accessible
name: the locator degrades to getByRole(role) with no name filter, and the count
driving .nth() is taken from the FILTERED aria snapshot while getByRole matches
the unfiltered DOM. Measured on a live page: the tree surfaced 2 unnamed
paragraphs, the DOM had 9. Landmarks (banner/main/contentinfo) and paragraphs are
correctly unnamed per ARIA, so this is the common case rather than an edge case.

boundingBox() then hits Playwright strict mode, and the catch allowlisted only
timeout/closed/Target/Execution-context messages — so the strict-mode error was
re-thrown and aborted every remaining annotation.

Two changes:

- `.first()` before boundingBox(), so an ambiguous ref draws a box on its first
  match instead of aborting. The heatmap path below has always tolerated this via
  a bare `catch {}`; annotate was the only path that could be killed outright.
- the catch no longer re-throws on unrecognised messages. A box we cannot measure
  is a box we do not draw, never a reason to lose the rest of the page. Set
  BROWSE_DEBUG to see what was skipped.

Also: `-o` passed without `-a`/`-H` was silently ignored (exit 0, no file), which
reads as "screenshots are broken" rather than "you forgot a flag". It now warns
and points at `browse screenshot <path>`.

Verified by rebuilding both ways against the same page with 51 refs present:
  before — "Selector matched multiple elements", no file written
  after  — exit 0, 229KB PNG

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

* fix(version-bump): missing or empty VERSION no longer repairs a fabricated 0.0.0.0 into package.json

repair now fails with exit 2 when the VERSION file is absent or empty
instead of folding to DEFAULT ("0.0.0.0") — which passed VERSION_RE and
regressed package.json below where it started. classify gains an additive
versionFileExists field so /ship can tell a real 0.0.0.0 from a fabricated
one. Re-derived from PR #2612 under the generated-file screening rule.

Fixes #2600 (repair half; the path-configurability half landed in v1.67 via #2531).
Contributed by @Lockyer228

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

* fix(memory-ingest): --probe counts post-attribution, through the same gate --bulk uses

probeMode previously stat'd every walked file, so setup-gbrain gated its
silent bulk ingest on pre-filter counts that the write path would never
ingest (#2394). The attribution decision now lives in ONE shared gate
(sessionIsAttributable — cheap-parse: cwd extraction + memoized
resolveGitRemote, never a full page build) used by BOTH probeMode and
preparePages, so the two stages' post-attribution counts are structurally
identical. ProbeReport gains skipped_unattributed; the probe prints what it
excluded and --include-unattributed restores raw counts. The parity is
pinned at the prepare stage (probe post-attribution == transcripts reaching
import), deliberately NOT == final written.

Re-derived from PR #2612 under the generated-file screening rule; the
shared-gate design and the remote memo are additions from the plan review.

Fixes #2394.
Contributed by @Lockyer228

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

* feat(browse): allow CPU and network throttling for performance measurement

Adds Emulation.setCPUThrottlingRate and Network.emulateNetworkConditions to
CDP_ALLOWLIST.

Motivation: diagnosing a real "uploads take 1-2 minutes" report, the only
machine available was a fast developer workstation. Client-side processing
measured 1.4s where the user experienced minutes, so the conclusion had to be
reached arithmetically rather than observed. Throttling would have let the
measurement reproduce the reporter's conditions directly.

Both fit the existing posture rather than widening it:
  - Emulation already allows setDeviceMetricsOverride, clearDeviceMetricsOverride
    and setUserAgentOverride, which are equally mutating and scoped to the tab.
  - Neither method reads page content. setCPUThrottlingRate affects only timing;
    emulateNetworkConditions constrains traffic rather than inspecting it, so no
    request bodies, headers or cookies are exposed. Both are output: 'trusted'
    because they return no page-derived data.

scope 'tab' for both, matching the surrounding Emulation entries.

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

* fix(session-update): lock pidfile records the live holder; hard TTL bounds every wedge (#2613)

echo $$ inside the backgrounded subshell recorded the PARENT hook's PID —
which exits immediately — so every subsequent session judged the lock stale
and rm -rf'd a LIVE holder's lock, letting concurrent updaters run over each
other. The pidfile now records ${BASHPID:-$(sh -c 'echo $PPID')} (macOS
bash 3.2 has no BASHPID; the sh child's PPID is exactly this subshell).

Staleness is now two independent detectors: PID liveness (as before, but
against the real holder), and a 30-minute hard TTL on the heartbeat mtime —
reclaimed regardless of kill -0, so a recycled PID or hung holder can't wedge
the lock forever. The holder touches the pidfile after the pull and after
setup, so a legitimately-slow run keeps itself alive. Empty and missing
pidfiles are respected inside the TTL window (the mkdir→echo race) and
reclaimed past it.

Fixes #2613.

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

* chore(browse): explicit windowsHide on every Bun.spawn site + census tripwire (#2575 residual)

Bun.spawn sites were structurally outside the windowsHide census (it swept
child_process bindings only). The runtime was already safe — native Bun hides
consoles by default and bun-polyfill.cjs defaults windowsHide !== false since
#2523/#2539 — but implicit defaults are exactly what regress silently. Every
Bun.spawn/spawnSync in browse/src now carries the explicit flag (harmless on
unix-only sites like Xvfb/xattr/open), and a second SWEEP in
windows-spawn-hide.test.ts fails CI on any new flagless Bun.spawn site.

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

* fix(gbrain): brain worktree advances on the daily sync — no more silently stale brains (#2516)

The daily pull refreshed only ~/.gstack itself, never the detached worktree
at ~/.gstack-brain-worktree that gbrain actually indexes — so after setup the
brain served stale pages forever unless setup-gbrain/sync-gbrain happened to
run. brain-sync --once now advances the worktree once per 24h behind an
ATTEMPT stamp (.brain-worktree-last-advance — a persistently-failing advance
warns once a day, not at every skill boundary), inside the existing run lock
and before any ingest step touches the worktree.

The new gstack-gbrain-source-wireup --advance-only is built for the
unattended cadence: git-only (no gbrain prereqs), pins every operation to the
managed worktree (refuses paths that are not worktrees of the artifacts
repo), refuses dirty worktrees, and never runs the force-remove recovery — a
cron path must not be able to delete local changes. A static pin keeps the
force-remove out. docs/gbrain-sync.md stops overclaiming the old cadence.

Fixes #2516.

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

* feat(memory-ingest): honor the per-remote deny/read-only trust policy (#2392)

Transcript ingest now respects the same trust store as code import — the gate
existed only in gstack-gbrain-sync's runCodeImport, so memory-ingest happily
ingested transcripts from deny-listed repos. preparePages filters prepared
transcript pages through ONE batch policy lookup (new 'get --batch' verb on
bin/gstack-gbrain-repo-policy — the script owns URL normalization; the client
adds repoPolicyTierBatch, one spawn for all distinct remotes, so large corpora
never pay a 10s-timeout subprocess per remote).

Outcomes match code-import semantics: read-only → clean skip
(skipped_policy_readonly), deny → counted refusal (skipped_policy_deny),
corrupted/unreadable store → HARD ERROR before any write (state, staging,
egress receipt, and import all untouched) with the recovery command named —
policy corruption must never read as successful ingestion. Artifacts are
never policy-filtered (their git_remote is a project slug, not a remote).

Fixes #2392.

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

* fix(config): repo_mode keeps its empty no-default semantics (#2611 follow-up)

The ported defaults table synthesized repo_mode → "unknown", but EMPTY is
load-bearing for that key: gstack-repo-mode treats any non-empty answer as a
user override and skips its own repo classification — the synthesized default
turned the classifier into dead code (REPO_MODE=unknown everywhere; caught by
test/gstack-repo-mode.test.ts via the wave's cross-agent blame protocol).
repo_mode joins the empty-is-real carve-outs (empty output, exit 0).

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

* fix(pair-agent): consent before killing a healthy headless daemon

The pair-agent headed switch spawned 'connect --force-restart'
unconditionally — auto-killing a live headless daemon (open tabs, cookies,
logins) in direct contradiction of the iron rule it sits beside ('only an
explicit --force-restart may kill a live daemon'). The CLI now captures
daemon liveness BEFORE ensureServer (which can itself boot a fresh daemon)
and relaunches only when the user passed --force-restart to pair-agent;
otherwise it prints the tab count and continues against the existing daemon.
The /pair-agent skill gains a matching one-way-door consent question
(template half rides the wave's template block).

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

* fix(gbrain-status): MCP scoping is per-project, and project-local beats user scope

hasRemoteOnlyGbrainMcp scanned EVERY project's mcpServers in ~/.claude.json,
so one project's remote gbrain registration reclassified broken local engines
as thin-client machine-wide. It now reads user scope plus only the cwd's
nearest-ancestor project key.

The precedence itself was verified empirically and hermetically (fake HOME +
CLAUDE_CONFIG_DIR fixtures, claude 2.1.233): with both scopes defining
gbrain, 'claude mcp get gbrain' reports Scope: Local config — PROJECT-LOCAL
WINS. Both in-repo consumers assumed the opposite; brain-cache's endpoint
resolution flips to nearest-ancestor-project-first, and the stale user-first
pin in brain-cache-roundtrip now pins the verified precedence. (The user-first
jq in the brain-sync preamble resolver gets the same swap in the template
block.)

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

* fix(slug): gstack-slug matches remote-slug's owner-repo canonical form (live misfile bug)

Found live during this wave's CEO review: bin/gstack-slug emitted
SLUG=garrytan for this garrytan/gstack worktree while remote-slug correctly
gave garrytan-gstack — decisions, timeline, ceo-plans, and learnings were
filing into the wrong project store (observed polluting Context Recovery with
another repo's decisions). Root cause: a stray empty ~/.git directory made
the walk-up crown $HOME as the outermost project root; the remote lookup ran
only against that root, failed silently, and the basename fallback cached
'garrytan' sticky. NOT worktree-specific — any strong marker on a non-repo
ancestor triggered it.

Fix: the walk now finds the outermost ancestor whose .git actually resolves
an origin remote and derives owner-repo with remote-slug's byte-identical
parse; marker-only ancestors keep anchoring the basename fallback but can no
longer shadow a real remote. A new cache self-heal recomputes the poisoned
shape (cached == basename of a marker root while a remote-bearing repo exists
below), preserving legit #2212 stickiness. Nested-repo walk-up, no-remote and
non-git fallbacks, and the SLUG=/BRANCH= eval contract are unchanged, pinned
by a 10-case parity suite. Store migration for pre-fix data is tracked in
TODOS.md.

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

* fix(brain-sync): per-record spool dir — the enqueue/drain race dies structurally

Producers appended lines to .brain-queue.jsonl while the drain re-read and
os.replace'd it; the in-code comment admitted a lockless append between the
re-read and the replace was lost. Locks and rename-rotation designs were both
reviewed and rejected (each retained a tail race); the shipped design is a
maildir-style spool: one FILE per record in .brain-queue.d/ (tmp + atomic
rename), the drain snapshots filenames, processes, and deletes exactly what
it snapshotted. Writer and drainer never share an inode — nothing to race.

Semantics: at-least-once (a crash between process and unlink re-drains;
downstream content-hash dedup absorbs duplicates); retained (privacy-held)
records keep their files; unparseable records are kept + warned, never
destroyed. Legacy .brain-queue.jsonl migrates atomically on the next drain
(crash-leftover .migrating files recovered too); status/drop-queue count both
surfaces; discover-new writes spool records and advances its cursor
per-record-written. The preamble's queue-depth line switches to spool count
in this wave's template block.

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

* fix(bin-context): native slug fallback walks up like bash gstack-slug

slugFromEnvironment derived the slug from the INNERMOST repo's origin while
bash gstack-slug walks to the outermost project root — nested/vendored repos
split their stores across the bash/native boundary (win32 hits the native
path constantly). The native fallback now ports _outermost_project_root
faithfully (strong/weak markers, outermost-strong-wins, 64-depth cap,
fixed-point termination) plus the full resolution order: env override →
walk-up → sticky cache with the #1125 self-heal → remote get-url → basename.
Twelve mirrored scenarios drive BOTH implementations against the same
fixtures and pin identical slugs.

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

* fix(next-version): git fallback queries the live remote, never mutates, and keeps 3-digit width

The degraded path counted every remote-tracking ref on every remote — stale
experiment branches and second remotes inflated version allocation, and a
failed base read flipped 3-digit repos to 4-digit slots. Now: ls-remote
--heads origin first (GIT_TERMINAL_PROMPT=0, 5s timeout, zero local ref
mutation); on failure, local refs/remotes/origin ONLY with an explicit
stale-refs warning; a failed base read zeroes at the LOCAL version file's
width so a 3-digit repo allocates 0.0.1, not 0.0.1.0.

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

* fix(setup): hooks register the global-install path and re-point stale ones

Registering hooks from a dev worktree baked that worktree's absolute path
into settings.json — deleting the worktree left a dead hook erroring on
every session stop, and the presence-only dedup (list-sources | grep) could
never re-point it. setup's hook paths now route through _hook_install_path
(global install preferred, source dir fallback), and the new ensure-event
verb on gstack-settings-hook compares the registered command payload against
canonical: identical → no write, different → single atomic replacement
(never zero or two registrations). The plan-tune hooks had the same stale
pattern and get the same fix without re-triggering their consent prompt.

Also hardened: bun 1.3.13 turns an uncaught sync fs error in bun -e into a
SILENT exit 0 — the registrar's write path now catches, prints, and exits 1,
so a failed update can never report fake-green.

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

* fix(preamble): learnings capture is unconditional at completion (#2402)

43 of 44 learnings entries came from explicit /learn — the completion-status
prose read 'if you discovered a durable project quirk... log it', which
models treated as optional. The step now ALWAYS runs: review the session for
durable learnings, log each one, and state 'No durable learnings this
session' explicitly when the review comes up empty — an empty result, never
a skipped step. Re-derived from PR #2612 under the generated-file screening
rule.

Fixes #2402.
Contributed by @Lockyer228

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

* feat(scrape): untrusted-content warning on the page-fetching skills (#2441)

/scrape and /skillify consumed page content with zero injection guidance —
the CHANGELOG claimed coverage the skills didn't have. The warning now lives
in ONE exported const (UNTRUSTED_CONTENT_WARNING in resolvers/browse.ts),
embedded in the browse COMMAND_REFERENCE as before AND injected standalone
into both skills via the new {{UNTRUSTED_CONTENT_WARNING}} token — single
source, wording can never drift between surfaces. Re-derived from PR #2612
under the generated-file screening rule. (Structural isolation for
skillify-generated code is tracked as its own TODO.)

Fixes #2441.
Contributed by @Lockyer228

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

* fix(review): checklist paths resolve from the installed skill root (#2518)

/review Step 2 read .claude/skills/review/checklist.md — a path relative to
the TARGET repo, which only resolves in gstack's own checkout. Every
checklist/greptile-triage/TODOS-format reference (six across five templates —
two more than the issue named, same class) now uses the installed-root form
~/.claude/skills/gstack/review/... that the templates' other references
already use. The install-root class itself (non-default install dirs) is
#1882, deliberately its own PR.

Fixes #2518.

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

* fix(pair-agent): one-way-door consent question before a daemon relaunch (template half)

The skill flow now checks daemon liveness before Step 4 and asks an explicit
one-way-door question (tabs/cookies/logins are lost) before passing
--force-restart — never proceeding on a vague reply. Pairs with the CLI-half
commit that stopped pair-agent auto-killing live daemons.

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

* docs(codex): resume does not amortize the ~21K session prelude (#2387)

Measured (#2387): every codex exec call pays Codex's session prelude, and a
resumed call came in slightly ABOVE a fresh one — resume buys continuity,
never token savings. The skill now says so where the resume flow lives:
prefer one codex call per skill, batch questions into it.

Fixes #2387.

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

* fix(upgrade): fast-forward first; reset --hard only behind a proved-safe gate (#2517)

/gstack-upgrade went straight to stash + reset --hard origin/main. Now it
tries git pull --ff-only --autostash first (the same policy session-update's
auto-upgrade uses). The destructive fallback runs unprompted ONLY when both
git status --porcelain AND git rev-list origin/main..HEAD are empty — a
clean tree with unpushed local commits is NOT safe, reset destroys them.
Anything else requires an explicit one-way-door confirmation that lists every
dirty file and unpushed commit being discarded.

Fixes #2517.

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

* fix(preamble): brain-sync block counts the spool queue and resolves MCP project-first

Two resolver halves deferred from earlier wave commits: the queue-depth line
counts .brain-queue.d/*.json spool records (plus legacy lines until the
drain migrates them), and GBRAIN_MCP_ENTRY_JQ swaps its operands to
nearest-ancestor-project-first — matching the empirically verified Claude
Code precedence (project-local beats user scope) instead of the backwards
user-first assumption.

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

* chore: regenerate SKILL.md docs + golden fixtures (single regen for the template block)

Pure generator output for the six template/resolver commits above (learnings
capture, untrusted-content warning, review paths, pair-agent consent, codex
resume note, upgrade ff-only, brain-sync block) — bun run gen:skill-docs +
--host codex + --host factory, with the three ship golden fixtures refreshed
per the documented procedure. The three sidecar-path pins in
gen-skill-docs.test.ts move to the new installed-root/$GSTACK_ROOT contract
(#2518). Restores template freshness; full suite green from here.

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

* chore: TODOS.md — strike the six wave-fixed residuals, add two follow-ups

The v1.67 adversarial-review residuals section shrinks to the one item the
wave couldn't reach (iOS tap routing — needs real-device verification). New
entries: skillify structural isolation (a prose warning is not a boundary for
page-derived generated code) and the slug store migration (pre-fix sessions
on stray-marker machines filed data under the degraded slug; post-fix reads
go to the correct store, so history needs a merge/alias).

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

* test: align cross-cutting pins with the wave's contracts

Three suites pinned pre-wave behavior: browse's gstack-config test asserted
the old unknown-key ''/exit-0 shape (#2611 made it exit 1); the Windows-paths
suite pinned O_APPEND enqueue atomicity (the spool design satisfies the same
invariant via tmp + os.replace, one file per record — pinned in its new
form); and nine carve-guard skeleton ceilings absorbed the #2402
unconditional-learnings prose (~450B per skill), bumped with measured values
per the guard's own protocol.

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

* test: re-anchor the referenced-path scanner self-check to the gstack-rooted review refs

The self-check pinned the review checklist as a class-1 alias-relative ref;
#2518 moved those refs to the installed gstack root (class 2). The guard now
proves the scanner sees them in their new class, so the class-2 assertion
can't go vacuous.

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

* test: pin the wave's prose-tier behaviors (ship coverage-audit gap closure)

The coverage audit found one regression-shaped gap: nothing pinned that the
upgrade template's ff-only pull precedes the gated reset --hard (#2517) — a
future template edit reverting to reset-first would fail nothing. Pinned:
the ordering, the FF_OK gate, and the unpushed-commits check. Also pinned
the two minor gaps: the {{UNTRUSTED_CONTENT_WARNING}} injection points in
scrape/skillify (#2441) and brain-uninstall's spool-dir cleanup.

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

* fix: pre-landing review round — 8 auto-fixes + 8 accepted findings hardened

The ship review army (4 specialists + red-team + checklist, 29 findings)
produced 8 mechanical auto-fixes and 11 decisions; the accepted set:

- win32 slug parity completed: lib/bin-context.ts gains the remote-first
  outermost walk + degraded-cache self-heal the bash side got this wave —
  the two implementations now agree on the stray-marker live-bug shape,
  pinned by shared fixtures (multi-specialist 9/10 finding).
- probe honors the plan's bounded-read decision: 256KB prefix, extraction
  semantics mirrored from parseTranscriptJsonl so probe/prepare can never
  diverge on the same file (>1MB transcript test).
- policy normalize parity: bash normalize() now matches canonicalizeRemote
  on .git/-trailing and uppercase-.GIT shapes (7-shape corpus pinned two
  ways) — a deny for those shapes could previously slip the transcript gate.
- session-update reclaim is TOCTOU-safe (atomic mv-aside on both branches).
- settings-hook: unparseable settings.json errors instead of being replaced
  with {}; ensure-event keys on (event, source) so matcher changes update
  in place — never zero or two registrations.
- dot-only slug guard at both parse sites (hostile 'url = ..' can't escape
  projects/); enqueue tmp-file janitor (1h TTL, inside the drain lock);
  brain-sync .migrating never clobbered; drop-queue/status count .migrating;
  snapshot -o warning correct + surfaced in diff mode; version-bump test
  order-dependence removed; uninstall clears the advance stamp.

Deferred with record: slug heal-probe cost sentinel (P3 TODO), FF_OK
conflation (noted, misdiagnosis-only).

270 pass / 0 fail across the 10 touched suites.

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

* fix: adversarial round — the P0 finalize fail-safe and 12 hardened findings

Three adversarial passes (Claude fresh-context, Codex chaos, Codex structured
with P1 gate) on the full wave diff. Multi-source findings, all fixed:

- P0: finalize_queue is now explicit-delete-only — a record is unlinked ONLY
  when classification proves it staged or dropped; a classifier crash, a
  missing class file, or a malformed pulled .brain-privacy-map.json (which
  previously nuked the whole snapshotted queue, remotely triggerable) now
  retains everything, warns, and re-drains next run. load_privacy_map treats
  corrupt maps as retain-all, never as empty.
- next-version cannot silently drop a live claim: unreadable advertised refs
  get a targeted --depth=1 fetch + retry; still-unreadable claims surface as
  UNKNOWN warnings instead of duplicate-version silence.
- session-update lock: ownership-checked EXIT trap (a TTL-reclaimed holder
  can no longer delete the new holder's lock) + a 5-min background heartbeat
  so a legitimately-slow pull/setup is never reclaimed while alive.
- ensure-event collapses ALL same-(event,source) duplicates to one canonical
  entry; unique per-process tmp path; setup call sites surface (not swallow)
  the hardened refusals.
- memory-ingest: --limit counts only policy-permitted pages (denied records
  no longer starve permitted ones); --probe applies the same policy filter as
  --bulk (skipped_policy_* fields on the report).
- version-bump repair accepts a genuine literal 0.0.0.0 VERSION file.
- slug heal restricted to the stray-.git shape — package.json-anchored
  wrapper roots keep their legit sticky identity (#2212 preserved).
- brain-sync: idle fast path sees leftover .migrating records; unparseable
  spool records quarantine instead of warning forever; migration comment
  stops overclaiming the transition-window race.
- CDP throttling justifications document override persistence (callers own
  restoration), pinned in the allowlist test.

Deferred with record: deny retroactivity for already-ingested pages (P2 TODO,
same semantics as the code-import gate); legacy-migration tail race
(transition-window, requires pre-spool writers).

288 pass / 0 fail across the 10 touched suites.

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

* chore: regenerate SKILL.md docs + goldens (Windows-separator jq fix)

Pure generator output for the brain-sync block's jq ancestor match now
accepting backslash-formed Windows project keys — previously project-scoped
brains were invisible on Windows while the TS scope resolvers saw them.
Golden ship fixtures refreshed per the documented procedure.

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

* fix: codex verify-pass residuals — chunked cwd read, post-filter partial count, migrating depth

The verify re-review passed the P1 gate (0 P1s) and left three residuals,
all applied: transcriptCwdFromPrefix reads in chunks until one complete
record (4MB cap) so a giant first prompt can't truncate mid-JSON and break
probe/bulk parity; partial_pages derives from the FINAL prepared set instead
of the whole scanned corpus; the preamble queue-depth line counts leftover
.brain-queue.jsonl.migrating records like the status path does (regen + goldens included).

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

* chore: bump version and changelog (v1.68.0.0)

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

* docs: update project documentation for v1.68.0.0

BROWSER.md: fix the $B cdp example (positional JSON params, not --json;
depth is the real CDP param) and add the new perf-throttling examples
(Emulation.setCPUThrottlingRate, Network.emulateNetworkConditions) with
their clear-override counterparts. USING_GBRAIN_WITH_GSTACK.md: the
state-files table row for the sync queue now names the maildir-style
spool dir .brain-queue.d/ that replaced .brain-queue.jsonl this release.

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

* test: align memory-pipeline probe pins with the #2394 stage-count contract

The paid-tier E2E pinned the pre-fix contract (probe headline = raw
discovered). Probe now counts post-attribution — the same gate --bulk
uses — with an explicit unattributed-skip line. Adds the
--include-unattributed companion pin so all 9 fixtures stay accounted for.

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

* fix(next-version): batch missing-tip fetches — one bounded round trip, never a per-branch crawl

The targeted-fetch retry for branches whose advertised tip has no local
object ran ONE git fetch per branch (10s cap each). On a shallow clone
against a busy remote that crawls the network for minutes — CI's shard
deadline killed the free suite mid-file. Missing tips now collect into a
single batched shallow fetch (15s cap); refs still missing after the
batch (one unservable ref fails the whole transfer) get a capped
per-branch retry, and anything past the cap warns as an UNKNOWN claim
instead of fetching.

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

* test(next-version): pin the batched fetch + make the offline-contract tests hermetic

Two new G2 pins: N unfetched claim branches resolve with exactly ONE
fetch spawn (PATH-shimmed git counts invocations), and one unservable
ref no longer poisons the batch — live claims resolve via the bounded
retry while only the ghost warns UNKNOWN.

The #2545 offline-contract tests now run the CLI in a local fixture repo
instead of the repo's own checkout: the checkout path did a live
ls-remote against the real origin (operator-network-dependent, and the
CI shard-deadline hang). The online-contract test gains a succeeding gh
stub, so fallback:null is asserted deterministically instead of only
when the operator happens to be authed.

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

* test(redact-cli): derive the synthetic AWS-key fixture — no contiguous credential literal in source

The CI quality gate scans every ADDED diff line with the redact engine,
so the #2610 port's raw fixture literals failed the very gate they
exist to test. The fixture is now assembled at runtime; the scanner
still receives the identical bytes.

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

* test(next-version): pin the fixture's host via origin-URL sniff — kills the last environment dependence

The hermetic offline-contract fixture had no origin remote, so
detectHost() fell through to auth probes: a machine with glab authed
passed via the gitlab path while a bare CI runner read host:unknown
(offline stays false there) and failed. The fixture now pushes to a
local bare origin at a path containing github.com — the URL sniff pins
host:github identically everywhere, asserted explicitly in both tests,
with every git call still local.

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

---------

Co-authored-by: y$un_ <forrest.sun527@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: benjamin beres <benjamin.beres@bienpreter.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Ricky <ricky@kinokostudio.com.hk>
Co-authored-by: Connex Client Access <paul@paulkortman.com>
Co-authored-by: henbima <henbima@gmail.com>

bin/gstack-brain-sync

@@ -20,6 +20,13 @@
 set -uo pipefail
 
 GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+# Maildir-style spool: one FILE per record, <epoch>-<pid>-<uniq>.json.
+# Writers (gstack-brain-enqueue, --discover-new) create records via tmp-file
+# + atomic rename; the drain deletes exactly the files it snapshotted. No
+# shared inode between writer and drainer → no append/rewrite race.
+QUEUE_DIR="$GSTACK_HOME/.brain-queue.d"
+# Legacy single-file queue: kept ONLY for migration. Pre-spool writers
+# appended lines here; migrate_legacy_queue converts them to spool files.
 QUEUE="$GSTACK_HOME/.brain-queue.jsonl"
 ALLOWLIST="$GSTACK_HOME/.brain-allowlist"
 PRIVACY_MAP="$GSTACK_HOME/.brain-privacy-map.json"
@@ -120,7 +127,91 @@ sys.exit(0)
 "
 }
 
-# Compute matched allowlisted, privacy-filtered path set from queue.
+# True (0) if the spool holds at least one record file.
+spool_has_records() {
+  local f
+  for f in "$QUEUE_DIR"/*.json; do
+    [ -e "$f" ] && return 0
+  done
+  return 1
+}
+
+# Convert one legacy queue file's lines into spool record files (tmp +
+# os.replace, one file per line). Reads the file TWICE before unlinking: a
+# pre-rename writer can still append through its already-open fd after our
+# rename, and those appends land in the renamed file — the second pass
+# NARROWS the tail-race window (transition-only: it applies to pre-spool
+# writers, and a writer that appends after the second read but before the
+# unlink can still lose that line; spool-native writers are immune).
+# Unparseable lines migrate as-is; finalize_queue quarantines + warns on them.
+convert_legacy_file() {
+  local legacy="$1"
+  python3 - "$legacy" "$QUEUE_DIR" <<'PYEOF' 2>/dev/null || true
+import os, sys, time
+
+legacy, spool = sys.argv[1:3]
+
+def read_lines(path):
+    try:
+        with open(path) as f:
+            return [l.rstrip("\r\n") for l in f if l.strip()]
+    except (FileNotFoundError, OSError):
+        return []
+
+seq = 0
+def write_spool(line):
+    global seq
+    seq += 1
+    tmp = os.path.join(spool, f".tmp-{os.getpid()}-m{seq}")
+    with open(tmp, "w") as f:
+        f.write(line + "\n")
+    os.replace(tmp, os.path.join(spool, f"{int(time.time())}-{os.getpid()}-m{seq}.json"))
+
+written = set()
+for _pass in (1, 2):   # second read closes the pre-rename-fd tail race
+    for line in read_lines(legacy):
+        if line not in written:   # identical duplicates collapse, as the old rewrite did
+            write_spool(line)
+            written.add(line)
+os.unlink(legacy)
+PYEOF
+}
+
+# Legacy migration (transition window only). If the single-file queue holds
+# records, atomically rename it aside and convert each line to a spool file.
+# A concurrent OLD writer that recreates a fresh legacy file after the rename
+# simply gets migrated on the NEXT drain — nothing is lost, only deferred one
+# boundary. Runs inside the run lock, before the drain reads the spool.
+migrate_legacy_queue() {
+  local migrating="$QUEUE.migrating"
+  # Crash leftover: a prior migration renamed but died before unlink. Some of
+  # its lines may already exist as spool files — re-converting duplicates is
+  # safe (at-least-once; the drain dedups paths per snapshot and downstream
+  # content-hash dedup absorbs re-syncs). Losing the file would not be. If
+  # the conversion itself fails, the file stays for the next run (never rm a
+  # non-empty .migrating file outside convert_legacy_file's own unlink).
+  if [ -f "$migrating" ]; then
+    if [ -s "$migrating" ]; then
+      mkdir -p "$QUEUE_DIR" 2>/dev/null || return 0
+      convert_legacy_file "$migrating"
+    else
+      rm -f "$migrating" 2>/dev/null || true
+    fi
+  fi
+  # If the leftover STILL holds records, the conversion failed (e.g. python3
+  # unavailable). The mv below would overwrite it and destroy those records —
+  # exactly the never-destroy invariant above. Defer this run's migration;
+  # the next run retries both files.
+  [ -s "$migrating" ] && return 0
+  if [ -s "$QUEUE" ]; then
+    mkdir -p "$QUEUE_DIR" 2>/dev/null || return 0
+    mv -f "$QUEUE" "$migrating" 2>/dev/null || return 0
+    convert_legacy_file "$migrating"
+  fi
+  return 0
+}
+
+# Compute matched allowlisted, privacy-filtered path set from the spool.
 # Output: newline-delimited relative paths that should be staged.
 #
 # #2549: every non-staged queue entry is CLASSIFIED, never silently discarded.
@@ -132,13 +223,20 @@ sys.exit(0)
 # attempt, no allowlist glob, not on disk) and are removed WITH a counted
 # status — the old behavior truncated the whole queue and reported every one
 # of these, including privacy holds, as "no allowlisted changes".
+#
+# Spool snapshot ($3): the sorted list of spool record filenames read here is
+# written to the snapshot manifest, one filename per line. finalize_queue
+# deletes exactly the manifest's files and never touches records created
+# after this listing — a concurrent enqueue is a separate file by
+# construction, so it simply rides to the next drain.
 compute_paths_to_stage() {
   local mode="$1"
   local class_file="${2:-}"
-  python3 - "$GSTACK_HOME" "$QUEUE" "$ALLOWLIST" "$PRIVACY_MAP" "$SKIP_FILE" "$mode" "$class_file" <<'PYEOF'
+  local snapshot_file="${3:-}"
+  python3 - "$GSTACK_HOME" "$QUEUE_DIR" "$ALLOWLIST" "$PRIVACY_MAP" "$SKIP_FILE" "$mode" "$class_file" "$snapshot_file" <<'PYEOF'
 import sys, json, os, fnmatch, glob
 
-gstack_home, queue, allowlist_path, privacy_path, skip_path, mode, class_file = sys.argv[1:8]
+gstack_home, spool_dir, allowlist_path, privacy_path, skip_path, mode, class_file, snapshot_file = sys.argv[1:9]
 
 def load_lines(path):
     try:
@@ -148,39 +246,67 @@ def load_lines(path):
         return []
 
 def load_privacy_map(path):
+    # Returns (entries, corrupt). Non-dict entries are filtered out
+    # defensively — the map may be PULLED from the artifacts remote, so a
+    # malformed entry like ["bad"] is remotely triggerable and used to raise
+    # mid-classification (after the snapshot manifest was written), which the
+    # old finalize turned into a full queue wipe. Any malformed shape also
+    # marks the map CORRUPT: privacy classification cannot be trusted, so the
+    # caller holds every queued record instead of guessing (a corrupt privacy
+    # map silently treated as empty would over-share behavioral data).
     try:
         with open(path) as f:
             data = json.load(f)
-        # Expected: [{"pattern": "glob", "class": "artifact" | "behavioral"}]
-        return data if isinstance(data, list) else []
-    except (FileNotFoundError, json.JSONDecodeError):
-        return []
+    except FileNotFoundError:
+        return [], False
+    except json.JSONDecodeError:
+        return [], True
+    if not isinstance(data, list):
+        return [], True
+    # Expected: [{"pattern": "glob", "class": "artifact" | "behavioral"}]
+    entries = [e for e in data if isinstance(e, dict)]
+    return entries, len(entries) != len(data)
 
 allowlist_globs = load_lines(allowlist_path)
-privacy_map = load_privacy_map(privacy_path)
+privacy_map, privacy_corrupt = load_privacy_map(privacy_path)
 # Normalize skip entries to the POSIX form queued paths use, so a backslash
 # entry in .brain-skip.txt still matches on Windows. The drain is the safety
 # boundary that actually stages files, so it must normalize identically to
 # discover_new — otherwise an explicitly-skipped file gets committed.
 skip_lines = {s.replace(os.sep, "/") for s in load_lines(skip_path)}
 
-# Read queue; collect unique file paths.
-queue_paths = set()
+# Snapshot the spool: sorted (= chronological, filenames are epoch-first)
+# list of record files at read time. Records that appear after this listing
+# belong to the NEXT drain. Files we cannot read stay OUT of the manifest so
+# finalize never deletes a record this drain didn't actually consume.
 try:
-    with open(queue) as f:
-        for line in f:
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                obj = json.loads(line)
-                p = obj.get("file")
-                if isinstance(p, str):
-                    queue_paths.add(p)
-            except json.JSONDecodeError:
-                continue
-except FileNotFoundError:
-    pass
+    snapshot = sorted(n for n in os.listdir(spool_dir) if n.endswith(".json"))
+except (FileNotFoundError, NotADirectoryError):
+    snapshot = []
+
+queue_paths = set()
+consumed = []
+for name in snapshot:
+    try:
+        with open(os.path.join(spool_dir, name)) as f:
+            line = f.readline().strip()
+    except OSError:
+        continue
+    consumed.append(name)
+    if not line:
+        continue
+    try:
+        obj = json.loads(line)
+        p = obj.get("file")
+        if isinstance(p, str):
+            queue_paths.add(p)
+    except json.JSONDecodeError:
+        continue   # unparseable record: finalize keeps + warns
+
+if snapshot_file:
+    with open(snapshot_file, "w") as f:
+        for name in consumed:
+            f.write(name + "\n")
 
 def path_matches_any(path, globs):
     for pattern in globs:
@@ -207,6 +333,14 @@ def mode_allows(cls, mode):
 
 final = []
 classified = {"retained": [], "dropped": {"skipped": [], "invalid": [], "unmatched": [], "missing": []}}
+if privacy_corrupt:
+    # Fail-safe: with an untrustworthy privacy map, stage NOTHING and drop
+    # NOTHING — retain every queued record until the map is fixed. The next
+    # drain re-classifies from scratch.
+    print("BRAIN_SYNC: warning: privacy map at " + privacy_path +
+          " is malformed — holding all queued records until it is fixed", file=sys.stderr)
+    classified["retained"] = sorted(queue_paths)
+    queue_paths = set()
 for p in sorted(queue_paths):
     if p in skip_lines:
         classified["dropped"]["skipped"].append(p)
@@ -241,22 +375,35 @@ for p in final:
 PYEOF
 }
 
-# #2549: surgical queue rewrite — replaces every whole-queue truncation
-# (`: > "$QUEUE"`). Re-reads the LIVE queue at rewrite time (a writer may have
-# enqueued while we were staging/pushing — those entries must survive; the old
-# truncation destroyed them) and keeps every line whose file is either
-# retained (privacy/mode-held) or not part of this drain at all. Atomic
-# tmp+mv in the same directory. Dropped-path detail goes to a 0600 sidecar so
-# the status line can stay content-free (counts only).
-rewrite_queue() {
-  local paths_file="$1"   # staged (drained) paths, one per line
-  local class_file="$2"   # classification JSON from compute_paths_to_stage
-  # Fail-open by design (a failed rewrite self-corrects next run: re-stage →
+# Finalize the drain: delete exactly the spool record files this drain
+# consumed (per the snapshot manifest) AND positively classified. Deletion is
+# EXPLICIT-DELETE-ONLY: a record is unlinked only when its path appears in
+# (staged paths ∪ classified dropped). The old polarity ("delete unless
+# retained") turned a missing/unparseable classification into retained=∅ and
+# wiped every snapshotted record — remotely triggerable via a malformed
+# pulled privacy map that raised AFTER the manifest write. Now a
+# missing/unparseable class_file or paths_file deletes NOTHING (warn +
+# return), and a path the classification never mentions stays queued.
+# The predecessor (a shared-file queue rewrite) had a lockless-append race
+# between its live re-read and the os.replace; with one file per record that
+# race class is structurally gone — a concurrent enqueue is a separate file
+# the snapshot never listed, so finalize cannot touch it. Crash semantics are
+# at-least-once: a drain that dies before finalize leaves its spool files in
+# place and the next run re-drains them; downstream content-hash dedup
+# absorbs the duplicates. Unparseable records move to $QUEUE_DIR/quarantine/
+# (never deleted) so they stop re-warning at every boundary. Dropped-path
+# detail goes to a 0600 sidecar so the status line can stay content-free
+# (counts only).
+finalize_queue() {
+  local snapshot_file="$1"  # spool filenames this drain consumed, one per line
+  local class_file="$2"     # classification JSON from compute_paths_to_stage
+  local paths_file="$3"     # staged paths (compute_paths_to_stage stdout), one per line
+  # Fail-open by design (a failed finalize self-corrects next run: re-stage →
   # nothing-to-commit), but say so — a silent failure here would let the
   # subsequent "ok/idle" status claim a drain that did not happen.
-  python3 - "$QUEUE" "$paths_file" "$class_file" "$GSTACK_HOME/.brain-sync-drops.json" <<'PYEOF' || echo "BRAIN_SYNC: warning: queue rewrite failed — entries retained; next run re-drains" >&2
+  python3 - "$QUEUE_DIR" "$snapshot_file" "$class_file" "$paths_file" "$GSTACK_HOME/.brain-sync-drops.json" <<'PYEOF' || echo "BRAIN_SYNC: warning: queue finalize failed — entries retained; next run re-drains" >&2
 import json, os, sys, time
-queue, paths_file, class_file, drops_file = sys.argv[1:5]
+spool_dir, snapshot_file, class_file, paths_file, drops_file = sys.argv[1:6]
 
 def lines(path):
     try:
@@ -265,46 +412,59 @@ def lines(path):
     except FileNotFoundError:
         return []
 
-staged = set(lines(paths_file))
+# Explicit-delete-only inputs. Either input unreadable → delete NOTHING.
 try:
     with open(class_file) as f:
         classified = json.load(f)
+    if not isinstance(classified, dict):
+        raise ValueError("classification is not an object")
 except Exception:
-    classified = {"retained": [], "dropped": {}}
-retained = set(classified.get("retained", []))
+    print("BRAIN_SYNC: warning: classification unreadable — no queue records deleted; next run re-drains", file=sys.stderr)
+    sys.exit(0)
+try:
+    with open(paths_file) as f:
+        staged = {l.strip() for l in f if l.strip()}
+except Exception:
+    print("BRAIN_SYNC: warning: staged-paths file unreadable — no queue records deleted; next run re-drains", file=sys.stderr)
+    sys.exit(0)
+
 dropped = set()
 for group in (classified.get("dropped", {}) or {}).values():
     dropped.update(group)
-processed = staged | dropped
+deletable = staged | dropped
 
-kept = []
-seen_lines = set()
 unparseable = 0
-# LIVE re-read narrows (not fully closes) the concurrent-append window: the
-# lockless enqueue can still land on the old inode between this read and the
-# os.replace below. Vastly better than the old whole-queue truncation.
-for line in lines(queue):
-    if line in seen_lines:
-        continue            # identical duplicate lines collapse on rewrite
+for name in lines(snapshot_file):
+    full = os.path.join(spool_dir, name)
     try:
-        p = json.loads(line).get("file")
+        with open(full) as f:
+            rec = f.readline().strip()
+    except OSError:
+        continue                 # unreadable now: leave it for the next drain
+    p = None
+    try:
+        p = json.loads(rec).get("file")
     except Exception:
+        pass
+    if not isinstance(p, str):
+        # Never destroy what we can't read — but don't leave it re-warning at
+        # every boundary either: move it aside for inspection.
         unparseable += 1
-        kept.append(line)   # unparseable line: keep, never destroy
-        seen_lines.add(line)
+        try:
+            qdir = os.path.join(spool_dir, "quarantine")
+            os.makedirs(qdir, exist_ok=True)
+            os.replace(full, os.path.join(qdir, name))
+        except OSError:
+            pass                 # quarantine move failed — leave in place; next run retries
         continue
-    if not isinstance(p, str) or p in retained or p not in processed:
-        kept.append(line)
-        seen_lines.add(line)
+    if p not in deletable:
+        continue                 # retained / unclassified: stays queued (explicit-delete-only)
+    try:
+        os.unlink(full)          # staged or dropped: fully processed
+    except FileNotFoundError:
+        pass
 if unparseable:
-    import sys as _sys
-    print(f"BRAIN_SYNC: {unparseable} unparseable queue line(s) held (inspect {queue})", file=_sys.stderr)
-
-tmp = queue + ".tmp." + str(os.getpid())
-with open(tmp, "w") as f:
-    for l in kept:
-        f.write(l + "\n")
-os.replace(tmp, queue)
+    print(f"BRAIN_SYNC: {unparseable} unparseable spool record(s) moved to quarantine (inspect {os.path.join(spool_dir, 'quarantine')})", file=sys.stderr)
 
 if dropped:
     fd = os.open(drops_file, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
@@ -374,9 +534,43 @@ subcmd_once() {
   # the lock removal.
   trap 'rm -rf "$lock_dir" 2>/dev/null || true' EXIT INT TERM
 
+  # Convert any legacy single-file queue lines into spool records before the
+  # drain reads the spool (transition window for pre-spool writers).
+  migrate_legacy_queue
+
+  # Janitor: reap orphaned enqueue temp files. A writer killed between its
+  # tmp write and the atomic rename leaves `.tmp-*` behind forever — it never
+  # becomes a record and nothing else touches it. One hour is far beyond any
+  # live writer's write→rename window, so a fresh tmp (an in-flight enqueue)
+  # is never touched. Runs inside the run lock, so it can't race the drain.
+  find "$QUEUE_DIR" -maxdepth 1 -type f -name '.tmp-*' -mmin +60 -delete 2>/dev/null || true
+
   local mode
   mode=$("$CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
 
+  # #2516: advance the brain worktree gbrain indexes to the artifacts repo's
+  # HEAD once a day — previously it only moved when setup-gbrain / sync-gbrain
+  # / brain-restore ran, so brains silently served stale code forever. Runs
+  # inside THIS run lock (never concurrent with the ingest steps below) and
+  # before they touch the worktree. Attempt-throttled: the stamp is written on
+  # ATTEMPT, so a persistently-failing advance warns once per 24h, not at
+  # every skill boundary. The advance itself refuses dirty or unmanaged
+  # worktrees and never force-removes (see gstack-gbrain-source-wireup).
+  if [ -e "${GSTACK_BRAIN_WORKTREE:-$HOME/.gstack-brain-worktree}" ]; then
+    local adv_stamp adv_now adv_last adv_age
+    adv_stamp="$GSTACK_HOME/.brain-worktree-last-advance"
+    adv_now=$(date +%s)
+    adv_last=$(cat "$adv_stamp" 2>/dev/null || echo 0)
+    case "$adv_last" in ''|*[!0-9]*) adv_last=0 ;; esac
+    adv_age=$(( adv_now - adv_last ))
+    if [ "$adv_age" -ge 86400 ]; then
+      echo "$adv_now" > "$adv_stamp" 2>/dev/null || true
+      if ! "$SCRIPT_DIR/gstack-gbrain-source-wireup" --advance-only 1>&2; then
+        echo "BRAIN_SYNC: warning: brain worktree advance failed — gbrain may be indexing stale code (run gstack-gbrain-source-wireup to repair)" >&2
+      fi
+    fi
+  fi
+
   # #2549 unpushed-commit detector: a prior drain may have COMMITTED but
   # failed to push (auth blip, offline). The data was never lost — it sits in
   # a local commit — but nothing re-pushed it until NEW changes arrived.
@@ -426,27 +620,42 @@ subcmd_once() {
   fi
 
   # Empty-queue fast path: this is the steady state at every skill boundary.
-  # Skipping compute/rewrite here is safe — with zero queue lines there is
-  # nothing to classify, retain, or drop, and a concurrent append after this
-  # check simply waits for the next boundary. (The detector above already ran:
-  # its whole point is re-pushing stranded commits when the queue is empty.)
-  # The lock-release trap installed at acquisition covers this exit.
-  if [ ! -s "$QUEUE" ]; then
+  # Skipping compute/finalize here is safe — with zero spool records there is
+  # nothing to classify, retain, or drop, and a record created after this
+  # check simply waits for the next boundary. The legacy file is checked too:
+  # an OLD writer may have recreated it after the migration above (it gets
+  # migrated next run, but the depth is honest now) — and so is a leftover
+  # .migrating file: if its conversion failed above (e.g. python3 missing),
+  # records are still pending, so "idle" would be dishonest. (The detector
+  # above already ran: its whole point is re-pushing stranded commits when
+  # the queue is empty.) The lock-release trap installed at acquisition
+  # covers this exit.
+  if ! spool_has_records && [ ! -s "$QUEUE" ] && [ ! -s "$QUEUE.migrating" ]; then
     write_status "idle" "queue empty"
     exit 0
   fi
 
-  local paths_file class_file
+  local paths_file class_file snapshot_file
   paths_file=$(mktemp /tmp/brain-sync-paths.XXXXXX) || { rm -rf "$lock_dir" 2>/dev/null; write_status "error" "mktemp failed"; exit 1; }
   class_file=$(mktemp /tmp/brain-sync-class.XXXXXX) || { rm -f "$paths_file"; rm -rf "$lock_dir" 2>/dev/null; write_status "error" "mktemp failed"; exit 1; }
+  snapshot_file=$(mktemp /tmp/brain-sync-snapshot.XXXXXX) || { rm -f "$paths_file" "$class_file"; rm -rf "$lock_dir" 2>/dev/null; write_status "error" "mktemp failed"; exit 1; }
   # Single trap covers all: lock cleanup AND tempfile cleanup.
-  trap 'rm -f "$paths_file" "$class_file" 2>/dev/null; rm -rf "$lock_dir" 2>/dev/null || true' EXIT INT TERM
+  trap 'rm -f "$paths_file" "$class_file" "$snapshot_file" 2>/dev/null; rm -rf "$lock_dir" 2>/dev/null || true' EXIT INT TERM
 
-  compute_paths_to_stage "$mode" "$class_file" > "$paths_file"
+  # Fail-safe (G1): a classifier that dies mid-run (ENOSPC/OOM/SIGKILL, or a
+  # shape the defensive filters don't cover) may have already written the
+  # snapshot manifest but no classification. Finalizing on that state is what
+  # used to wipe the queue — so on a nonzero exit, warn loudly, do NOT call
+  # finalize_queue, and leave everything queued for the next drain.
+  if ! compute_paths_to_stage "$mode" "$class_file" "$snapshot_file" > "$paths_file"; then
+    echo "BRAIN_SYNC: warning: queue classification failed — no records consumed; next run re-drains" >&2
+    write_status "error" "classification failed; queue preserved (next run retries)"
+    exit 0
+  fi
   if [ ! -s "$paths_file" ]; then
-    # Nothing stageable. Rewrite the queue (retained entries + concurrent
-    # appends survive; classified drops removed) instead of truncating it.
-    rewrite_queue "$paths_file" "$class_file"
+    # Nothing stageable. Finalize the snapshot (retained entries survive;
+    # classified drops removed; records created after the snapshot untouched).
+    finalize_queue "$snapshot_file" "$class_file" "$paths_file"
     local summary
     summary=$(queue_summary "$class_file")
     write_status "idle" "no stageable changes${summary:+ ($summary)}"
@@ -497,8 +706,8 @@ subcmd_once() {
   git -C "$GSTACK_HOME" -c user.email="gstack@localhost" -c user.name="gstack-brain-sync" \
     commit -q -m "$msg" 2>/dev/null || {
       # Nothing to commit (e.g. all files already committed). The drained
-      # paths leave the queue; retained + concurrent entries survive (#2549).
-      rewrite_queue "$paths_file" "$class_file"
+      # records leave the spool; retained + post-snapshot records survive.
+      finalize_queue "$snapshot_file" "$class_file" "$paths_file"
       write_status "idle" "queue drained but no new changes to commit"
       exit 0
     }
@@ -512,10 +721,10 @@ subcmd_once() {
       hint=$(remote_auth_hint)
       write_status "push_failed" "push failed: auth error; commit retained locally, will retry next run. fix: $hint"
       echo "BRAIN_SYNC: push failed: auth. fix: $hint" >&2
-      # Drained paths leave the queue — they live in the local commit, which
+      # Drained records leave the spool — they live in the local commit, which
       # the run-start detector re-pushes next time (#2549). Retained +
-      # concurrent entries survive the rewrite.
-      rewrite_queue "$paths_file" "$class_file"
+      # post-snapshot records survive the finalize.
+      finalize_queue "$snapshot_file" "$class_file" "$paths_file"
       exit 0
     fi
 
@@ -529,7 +738,7 @@ subcmd_once() {
       if git -C "$GSTACK_HOME" merge --no-edit "origin/$branch" >/dev/null 2>&1; then
         if GSTACK_HOME="$GSTACK_HOME" _receipted_git closed brain-sync "$push_host" curated-memory-git-push "artifacts_sync_mode!=off" \
             bash -c 'git -C "$1" push origin HEAD 2>/dev/null' _ "$GSTACK_HOME"; then
-          rewrite_queue "$paths_file" "$class_file"
+          finalize_queue "$snapshot_file" "$class_file" "$paths_file"
           date -u +%Y-%m-%dT%H:%M:%SZ > "$LAST_PUSH_FILE"
           write_status "ok" "pushed $n file(s) after rebase"
           exit 0
@@ -538,12 +747,12 @@ subcmd_once() {
     fi
     # Commit exists locally; the run-start detector re-pushes it next time.
     write_status "push_failed" "push failed: $(printf '%s' "$push_err" | head -1); commit retained locally, will retry next run"
-    rewrite_queue "$paths_file" "$class_file"
+    finalize_queue "$snapshot_file" "$class_file" "$paths_file"
     exit 0
   }
 
-  # Success: drained paths leave the queue (retained + concurrent survive).
-  rewrite_queue "$paths_file" "$class_file"
+  # Success: drained records leave the spool (retained + post-snapshot survive).
+  finalize_queue "$snapshot_file" "$class_file" "$paths_file"
   date -u +%Y-%m-%dT%H:%M:%SZ > "$LAST_PUSH_FILE"
   write_status "ok" "pushed $n file(s)"
   exit 0
@@ -555,9 +764,15 @@ subcmd_status() {
   else
     echo '{"status":"unknown","message":"no status file yet"}'
   fi
-  # Supplemental info (not in status file).
-  local queue_depth=0
-  [ -f "$QUEUE" ] && queue_depth=$(wc -l < "$QUEUE" | tr -d ' ')
+  # Supplemental info (not in status file). Depth = spool record files plus
+  # any not-yet-migrated legacy queue lines (transition window), including a
+  # crash-leftover .migrating file — its records are still pending too.
+  local queue_depth spool_depth legacy_depth
+  spool_depth=$(ls "$QUEUE_DIR"/*.json 2>/dev/null | wc -l | tr -d ' ')
+  legacy_depth=0
+  [ -f "$QUEUE" ] && legacy_depth=$(wc -l < "$QUEUE" | tr -d ' ')
+  [ -f "$QUEUE.migrating" ] && legacy_depth=$(( legacy_depth + $(wc -l < "$QUEUE.migrating" | tr -d ' ') ))
+  queue_depth=$(( spool_depth + legacy_depth ))
   local last_push="never"
   [ -f "$LAST_PUSH_FILE" ] && last_push=$(cat "$LAST_PUSH_FILE" 2>/dev/null || echo never)
   local mode
@@ -588,13 +803,31 @@ subcmd_drop_queue() {
     echo "Refusing: --drop-queue discards pending syncs. Pass --yes to confirm." >&2
     exit 1
   fi
-  if [ ! -f "$QUEUE" ]; then
+  # Remove spool record files, then truncate any legacy queue remnant —
+  # including a crash-leftover .migrating file, whose records would otherwise
+  # resurrect on the next drain via migrate_legacy_queue after the user
+  # explicitly discarded the queue.
+  local n=0 f
+  for f in "$QUEUE_DIR"/*.json; do
+    [ -e "$f" ] || continue
+    rm -f "$f" 2>/dev/null && n=$(( n + 1 ))
+  done
+  if [ -f "$QUEUE" ]; then
+    local legacy_n
+    legacy_n=$(wc -l < "$QUEUE" | tr -d ' ')
+    n=$(( n + legacy_n ))
+    : > "$QUEUE"
+  fi
+  if [ -f "$QUEUE.migrating" ]; then
+    local mig_n
+    mig_n=$(wc -l < "$QUEUE.migrating" | tr -d ' ')
+    n=$(( n + mig_n ))
+    rm -f "$QUEUE.migrating" 2>/dev/null || true
+  fi
+  if [ "$n" -eq 0 ]; then
     echo "queue already empty"
     exit 0
   fi
-  local n
-  n=$(wc -l < "$QUEUE" | tr -d ' ')
-  : > "$QUEUE"
   echo "dropped $n queue entries"
 }
 
@@ -604,11 +837,11 @@ subcmd_discover_new() {
   fi
   # Walk allowlist globs; enqueue any file where mtime+size differs from cursor.
   python3 - "$GSTACK_HOME" "$ALLOWLIST" "$DISCOVER_CURSOR" <<'PYEOF' 2>/dev/null || true
-import sys, os, json, fnmatch
+import sys, os, json, fnmatch, time
 from datetime import datetime, timezone
 
 gstack_home, allowlist_path, cursor_path = sys.argv[1:4]
-queue_path = os.path.join(gstack_home, ".brain-queue.jsonl")
+spool_dir = os.path.join(gstack_home, ".brain-queue.d")
 skip_path = os.path.join(gstack_home, ".brain-skip.txt")
 
 def load_lines(path):
@@ -666,34 +899,36 @@ for root, dirs, files in os.walk(gstack_home):
         if cursor.get(rel) != key:
             to_enqueue.append((rel, key))
 
-# Append to the queue directly. The previous implementation shelled out to
+# Write spool records directly. The previous implementation shelled out to
 # gstack-brain-enqueue once per file, but Windows Python cannot exec a
 # bash-shebang script (the spawn fails with a fork error), so discovery
 # enqueued nothing on Windows even after the path-match fix above.
-# Writing the queue line here is platform-agnostic; the drain step
+# Writing the record here is platform-agnostic; the drain step
 # (compute_paths_to_stage) still re-applies the skip-list + privacy filters.
 if to_enqueue:
     ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    written = []
     try:
-        # One atomic append per record (O_APPEND, each line < PIPE_BUF), matching
-        # gstack-brain-enqueue's concurrency contract so a writer-shim append
-        # running in parallel can't interleave mid-record. Buffered text writes
-        # don't guarantee that. Compact separators match the shim's JSON shape.
-        fd = os.open(queue_path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
-        try:
-            for rel, key in to_enqueue:
-                rec = json.dumps({"file": rel, "ts": ts}, separators=(",", ":"))
-                os.write(fd, (rec + "\n").encode("utf-8"))
-        finally:
-            os.close(fd)
+        # One spool FILE per record (tmp write + atomic os.replace), matching
+        # gstack-brain-enqueue's maildir contract: writers and the drain never
+        # share an inode, so a parallel writer or drain can't race this.
+        # Compact separators match the shim's JSON shape.
+        os.makedirs(spool_dir, exist_ok=True)
+        for i, (rel, key) in enumerate(to_enqueue):
+            rec = json.dumps({"file": rel, "ts": ts}, separators=(",", ":"))
+            tmp = os.path.join(spool_dir, f".tmp-{os.getpid()}-d{i}")
+            with open(tmp, "w") as f:
+                f.write(rec + "\n")
+            os.replace(tmp, os.path.join(spool_dir, f"{int(time.time())}-{os.getpid()}-d{i}.json"))
+            written.append((rel, key))
     except OSError:
-        # Queue write failed (disk full, AV file lock). Leave the cursor
-        # unadvanced so these files are retried on the next discover instead of
-        # being silently recorded as synced (which loses the change until the
-        # file next changes).
-        to_enqueue = []
+        # Spool write failed (disk full, AV file lock). Leave the cursor
+        # unadvanced for unwritten records so they are retried on the next
+        # discover instead of being silently recorded as synced (which loses
+        # the change until the file next changes).
+        pass
     # Advance the cursor only for records actually written.
-    for rel, key in to_enqueue:
+    for rel, key in written:
         new_cursor[rel] = key
 
 save_cursor(cursor_path, new_cursor)