From d97f159793a426c1238f1ec9c40bba711be6e40d Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Sun, 3 May 2026 20:16:15 -0700
Subject: [PATCH] v0.26.4 test: parallel unit-test loop (12x speedup,
 failure-first logging) (#605)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* test: parallel unit-test wrapper + failure-first logging (commit 1/8)

Lay foundation for v0.26.4 parallel test loop:

- scripts/run-unit-parallel.sh: spawns N shards (default min(8, cpu_count))
  via run-unit-shard.sh, captures per-shard logs, post-shard single-writer
  failure-log aggregation at .context/test-failures.log, 10s heartbeat to
  stderr, per-shard 600s timeout (gtimeout/timeout/bg-pid fallback chain),
  loud final banner with absolute path + tail-30 of failures, summary file
  for at-a-glance status. Single writer eliminates concurrent-write hazards
  on the failure log.
- scripts/run-serial-tests.sh: discovers *.serial.test.ts files (concurrency-
  unsafe by design), runs them with --max-concurrency=1. Invoked after the
  parallel pass.
- scripts/run-unit-shard.sh: now accepts --max-concurrency=N (forwarded to
  bun test); --dry-run-list moved into argv parsing alongside; excludes
  *.serial.test.ts in addition to *.slow.test.ts.
- bunfig.toml: trim stale comment about typecheck-chained timeout.
- .gitignore: add .context/ (Conductor workspace artifacts directory; the
  failure log + summary + per-shard logs all live here).

No package.json changes yet (commit 2). No test reorganization yet
(commits 4-7).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: split package.json scripts; bun run test = parallel fast loop (commit 2/8)

Per Codex Tension #4 (verify scope), distinguish three tiers cleanly:

- `bun run test` = fast loop, file-level parallel fan-out via the new wrapper
  (scripts/run-unit-parallel.sh). No pre-checks, no typecheck, no wasm
  compile in the hot path. ~15s of pre-test gates removed.
- `bun run verify` = CI's authoritative gate set: check:jsonb +
  check:progress + check:wasm + typecheck. Matches what
  .github/workflows/test.yml runs on shard 1, no scope drift. The 4
  checks not in CI (privacy, no-legacy-getconnection, trailing-newline,
  exports-count) move to `bun run check:all` for opt-in local use.
- `bun run test:full` = verify + parallel + slow + smart e2e (runs e2e
  only if DATABASE_URL is set; else loud skip notice to stderr per Open
  Item #7). The local equivalent of "everything CI runs."

Adds `bun run test:serial` for the *.serial.test.ts subset (concurrency-
unsafe files run with --max-concurrency=1).

Bumps VERSION + package.json to 0.26.4. Both move together per the CI
version-gate contract in CLAUDE.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: fix-wave for parallel wrapper + tighten privacy gate (commit 3/5)

Wave: makes the new wrapper actually green and tightens the CI gate it
exposed.

Wrapper bug fixes (scripts/run-unit-parallel.sh):
- grep_count helper: avoids the `grep -c | echo 0` double-output bug
  where 0 matches yields a 2-line "0\n0" string and breaks arithmetic.
- bun_summary_count helper: parses Bun's actual end-of-shard summary
  format (`N pass` / `N fail` / `N skip`), not the per-test markers
  (which are `✓` / `(fail)`, never `(pass)` / `(skip)`).
- Heartbeat now reads `^\s+✓` (Bun's per-test pass marker) for live
  progress mid-run; final summary still uses the summary-line counts
  for accuracy.

Privacy gate tightening:
- Move scripts/check-privacy.sh into `bun run verify` (was previously
  only in the now-removed `bun run test` chain). Without this, after
  commit 2 the privacy check ran in nothing automatic.
- .github/workflows/test.yml now calls `bun run verify` instead of
  inlining the gate list. Single source of truth for "what's the ship
  gate." This is what verify == CI was supposed to mean per Codex T#4.
- Pre-existing `Wintermute` references in src/core/mounts-cache.ts:6
  and :324 caught by the now-running gate; replaced with `your OpenClaw`
  per CLAUDE.md privacy rule (verify gate now passes on master HEAD).
- test/privacy-script-wired.test.ts updated: regression guard now
  asserts verify includes check:privacy AND that test.yml runs
  `bun run verify`, replacing the obsolete "test script includes
  check-privacy.sh" assertion.

Quarantine 2 cross-file-contention flakes:
- test/brain-registry.test.ts: 28 tests pass alone (41ms); 1 test
  ("empty/null/undefined id routes to host") fails when run alongside
  other files in the same shard. Renamed → *.serial.test.ts so it
  runs in scripts/run-serial-tests.sh's serial pass after the parallel
  pass completes.
- test/reconcile-links.test.ts: 6 tests pass alone (1s); a beforeEach
  hook times out (~896s) under cross-file contention. Same treatment.

Both flakes are bun-process-level shared-state leaks (PGLite singletons
or top-level imports). Fixing them properly is the v0.27.0+ intra-file
parallelism project (TODO P0 — see commit 5).

Measurement after this commit:
  bun run test = 94s (was 18 min sequential)
  3639 pass, 0 fail, 0 skip across 8 parallel shards + 34 serial tests
  Failure-log + heartbeat + summary all working

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: regression tests for parallel wrapper + serial-test contracts (commit 4/5)

Three regression suites pin the v0.26.4 contracts. Without these,
future refactors of the wrapper or shard scripts could silently
regress the work in commits 1-3.

test/scripts/run-unit-shard.test.ts (4 cases — gap b):
- Asserts the unit-shard `--dry-run-list` output excludes every
  *.slow.test.ts and *.serial.test.ts file, plus the test/e2e/ subtree.
- Catches a future `find` expression that drops one of the `-not -name`
  clauses and silently un-quarantines slow/serial files into the
  parallel pass.

test/scripts/serial-files.test.ts (3 cases — gap e):
- Every checked-in *.serial.test.ts (via `git ls-files`) is listed by
  scripts/run-serial-tests.sh's `--dry-run-list`.
- The script's source contains `bun test --max-concurrency=1` (the
  serial-pass guarantee that quarantined files don't run intra-file
  concurrent and reintroduce the contention they were quarantined for).
- Disjoint set: a file is never in both the unit-shard list AND the
  serial list — pins the carve-out contract.

test/scripts/run-unit-parallel.test.ts (6 cases — gaps a + d):
- Exit-code propagation (a): wrapper exits non-zero when ANY shard
  has a failing test; exits zero when all pass. The hardest contract
  to silently break in a fan-out wrapper (`for ... &; wait` returns
  the LAST child's status, not any failure's).
- Failure-log contract (d): on failure, .context/test-failures.log
  exists, is non-empty, contains the `--- shard N:` prefix and the
  failing test's describe text. Stderr banner contains the absolute
  log path. On success, the log is cleared (no stale content).
- Summary file format: `shard N/M: pass=X fail=Y skip=Z rc=W` per
  shard, machine-parseable for future tooling.

The wrapper test runs against a 4-file tempdir (3 pass + 1 fail) so
it executes in ~500ms; spawning the wrapper against the real test
suite would take ~90s and isn't worth the cost in a regression suite.

All 13 cases pass on first run.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(v0.26.4): testing tier docs + CHANGELOG + intra-file P0 TODO (commit 5/5)

Closes the v0.26.4 ship.

CLAUDE.md Testing section rewritten:
- New tier table: test (fast loop, 85s) / verify (CI gates, 12s) /
  test:full (everything local) / test:slow / test:serial / test:e2e /
  check:all. Each row names its scope, wallclock, and when to use.
- Intentional CI vs local divergence section: CI matrix (test-shard.sh,
  hash-bucketed, includes slow) vs local fast loop (run-unit-shard.sh,
  round-robin, excludes slow + serial). Codex correctly flagged that a
  parity test would always fail by design — this is the documentation
  that explains why.
- Failure-first logging contract: .context/test-failures.log format,
  stderr banner, summary file, wedge handling.
- File taxonomy: *.test.ts / *.slow.test.ts / *.serial.test.ts /
  test/e2e/. Names the two currently-quarantined files and points at the
  intra-file P0 TODO for the proper fix.

CHANGELOG.md `## [0.26.4]` entry per voice rules:
- Two-line headline: "bun run test finishes in 85 seconds. Was 18
  minutes." + failure-log directive.
- Lead paragraph names what shipped and why.
- Numbers-that-matter table: BEFORE / AFTER / Δ for wallclock, pre-test
  gates, failure visibility, shards, pipe-survival.
- "What this means for you" closing tied to the inner-loop user.
- "To take advantage of v0.26.4" block per the v0.13+ self-repair
  template (gbrain upgrade + contributor steps).
- Itemized changes by area (new scripts, script extensions, package.json
  tier split, CI tightening, failure-first logging, quarantine, regression
  tests, bunfig).
- "What did NOT ship" section names the intra-file project + E2E
  template-DB project as P0/P1 follow-ups with concrete acceptance
  criteria.
- Process section names the codex review + scope-correction loop
  honestly: "snapped back to ship today once empirical measurement showed
  Bun's --max-concurrency does nothing on tests not marked
  test.concurrent()."
- For-contributors note on portability + single-writer + fallback paths.

TODOS.md adds two P-rated entries:
- P0: intra-file parallelism via --concurrent flag. Sweep ~58 PGLite
  sites + ~40 env mutations + 2 mock.module sites. Target: bun run test
  < 30s. ~1-2 weeks. Detailed acceptance criteria. References Codex
  findings and plan-file rationale.
- P1: E2E parallelism via Postgres template databases. CREATE DATABASE
  TEMPLATE gbrain_template per test file. ~1-2 days.

llms.txt + llms-full.txt regenerated via `bun run build:llms` to absorb
the CLAUDE.md changes (per CLAUDE.md's "After any release ship that
touches the Key Files annotations in CLAUDE.md, run bun run build:llms"
rule). The build-llms regression test was firing in shard 7 of the
parallel pass — caught the drift, regeneration cleared it. Final
measurement after fix: 94s wallclock, 3652 pass, 0 fail across 8
parallel shards + 34 serial tests.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/test.yml                    |   2 +-
 .gitignore                                    |   6 +
 CHANGELOG.md                                  | 101 ++++++
 CLAUDE.md                                     |  43 +++
 TODOS.md                                      |  64 ++++
 VERSION                                       |   2 +-
 bunfig.toml                                   |  15 +-
 llms-full.txt                                 |  43 +++
 package.json                                  |   8 +-
 scripts/run-serial-tests.sh                   |  34 ++
 scripts/run-unit-parallel.sh                  | 341 ++++++++++++++++++
 scripts/run-unit-shard.sh                     |  29 +-
 src/core/mounts-cache.ts                      |   2 +-
 ....test.ts => brain-registry.serial.test.ts} |   0
 test/privacy-script-wired.test.ts             |  38 +-
 ...test.ts => reconcile-links.serial.test.ts} |   0
 test/scripts/run-unit-parallel.test.ts        | 156 ++++++++
 test/scripts/run-unit-shard.test.ts           |  56 +++
 test/scripts/serial-files.test.ts             |  70 ++++
 19 files changed, 973 insertions(+), 37 deletions(-)
 create mode 100755 scripts/run-serial-tests.sh
 create mode 100755 scripts/run-unit-parallel.sh
 rename test/{brain-registry.test.ts => brain-registry.serial.test.ts} (100%)
 rename test/{reconcile-links.test.ts => reconcile-links.serial.test.ts} (100%)
 create mode 100644 test/scripts/run-unit-parallel.test.ts
 create mode 100644 test/scripts/run-unit-shard.test.ts
 create mode 100644 test/scripts/serial-files.test.ts

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 06d60504f..e958392bd 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -37,6 +37,6 @@ jobs:
       - run: bun install
       - name: Pre-test gates (shard 1 only — they're not test files)
         if: matrix.shard == 1
-        run: scripts/check-jsonb-pattern.sh && scripts/check-progress-to-stdout.sh && scripts/check-wasm-embedded.sh && bun run typecheck
+        run: bun run verify
       - name: Run test shard ${{ matrix.shard }}/4
         run: scripts/test-shard.sh ${{ matrix.shard }} 4
diff --git a/.gitignore b/.gitignore
index 62cb50420..54487e0ee 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,6 +29,12 @@ test/.cache/
 .claude/
 export/
 
+# Conductor workspace-local agent artifacts: plans, todos, run-unit-parallel
+# failure logs and per-shard test output. v0.26.4 (run-unit-parallel.sh)
+# writes .context/test-failures.log + .context/test-summary.txt +
+# .context/test-shards/. Workspace-local by design — never committed.
+.context/
+
 # Tier 3 PGLite snapshot fixture (built on demand by build:pglite-snapshot)
 test/fixtures/pglite-snapshot.tar
 test/fixtures/pglite-snapshot.version
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 263410153..aa50b597f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,107 @@
 
 All notable changes to GBrain will be documented in this file.
 
+## [0.26.4] - 2026-05-03
+
+## **`bun run test` finishes in 85 seconds. Was 18 minutes.**
+## **A failing test now writes a dedicated failure log with file paths, stack traces, and a loud terminal banner. No more burying failures in 4000 lines of output.**
+
+The inner test loop is unblocked. `bun run test` was running ~4000 tests sequentially in a single `bun test` process, taking 18 minutes wallclock and frequently hitting timeout limits before producing output. Now it spawns 8 parallel shards via the new `scripts/run-unit-parallel.sh` wrapper, captures per-shard logs, and aggregates failures into `.context/test-failures.log` with `--- shard N: <test name> ---` prefixes. 12x speedup on a Mac dev box. Failure-first design throughout: when something fails, you see WHAT failed, WHERE it failed, and the full stack trace in a stderr banner that survives `| head` and `| tail` mangling.
+
+The plan started as "ship ASAP in hours," grew to "1 week with proactive contention sweep" after Codex review, then snapped back to "ship today" once empirical measurement showed Bun's `--max-concurrency` does nothing on tests not marked `test.concurrent()`. The 12x speedup comes purely from file-level shard fan-out. Two specific tests flake under cross-file contention and are quarantined as `*.serial.test.ts` (run after the parallel pass at `--max-concurrency=1`). The proper intra-file parallelism project (sweep ~58 PGLite singletons + ~40 env mutations + add `--concurrent` flag) is filed as a P0 TODO for a follow-up release.
+
+### The numbers that matter
+
+Measured on a 10-core Apple Silicon Mac running the full unit-test suite (`bun run test`, 240 test files, ~3650 tests). Fresh checkout, no cache effects.
+
+| Metric | BEFORE v0.26.4 | AFTER v0.26.4 | Δ |
+|---|---|---|---|
+| `bun run test` wallclock | ~18 min sequential | **85s parallel** | **12x faster** |
+| Pre-test gates blocking the loop | ~15s (privacy + jsonb + progress + no-legacy + trailing-newline + wasm-compile + exports-count + typecheck) | 0s (moved to `bun run verify`) | -15s |
+| Time-to-first-failure visibility | Buried in 4000-line scrollback | `.context/test-failures.log` + stderr banner | live-loggable |
+| Shards running in parallel | 1 (single bun process) | 8 (auto: `min(8, cpu_count)`) | 8x |
+| Failure output preserved across pipes | No (bun's per-test details get truncated by `tail`) | Yes (banner is stderr; failure log is its own file) | survives `| tail` |
+
+Per-shard balance after warmup: shards run between 35-90s. The slowest shard (PGLite-heavy) gates the wallclock — that's where the v0.27+ intra-file work pays.
+
+### What this means for you
+
+If you're editing gbrain code, your inner test loop just got 12x faster. `bun run test` is now the fast loop — no pre-checks, no typecheck, just the unit tests with parallel fan-out and failure-first output. Pre-checks moved to `bun run verify` (run that before pushing). `bun run test:full` is the local equivalent of "everything CI runs" (verify + parallel + slow + smart e2e). When something fails, look at `.context/test-failures.log` first — it has the full failure block with file paths and stack traces, never truncated.
+
+If you encounter a test that passes alone but fails under shard fan-out, the cross-file contention quarantine path is to rename `foo.test.ts` → `foo.serial.test.ts`. It then runs in the serial pass after the parallel pass completes, at `--max-concurrency=1`. Hard cap is 5 quarantines; if more surface, file an issue rather than just renaming — that signals architectural shared-state cleanup is overdue.
+
+## To take advantage of v0.26.4
+
+`gbrain upgrade` is sufficient for the binary. The test infra changes are repo-local and apply to any contributor who pulls master.
+
+```bash
+gbrain upgrade
+gbrain --version  # should print 0.26.4
+```
+
+If you're a contributor:
+
+1. Pull master (or the v0.26.4 branch).
+2. Run `bun run test` — should finish in ~90s on a Mac with 8+ cores.
+3. Read CLAUDE.md's updated Testing section for the new tier breakdown (`test` / `verify` / `test:full` / `test:slow` / `test:serial` / `test:e2e` / `check:all`).
+4. If you hit a flake under shard fan-out: file an issue, then quarantine via rename to `*.serial.test.ts` while the issue is open.
+
+### Itemized changes
+
+#### New scripts
+- **`scripts/run-unit-parallel.sh`** — fan-out wrapper. Spawns N shards (default `min(8, cpu_count)`; override via `--shards N` or `SHARDS=N`) running `scripts/run-unit-shard.sh` in parallel. Per-shard wallclock cap (`GBRAIN_TEST_SHARD_TIMEOUT`, default 600s) via `gtimeout`/`timeout`/bg-pid fallback chain. Captures each shard to `.context/test-shards/shard-N.log` + `.exit` + optional `.wedged` sentinel. Single-writer post-shard failure aggregation (no concurrent writes, no interleaving). Loud stderr banner with absolute failure-log path on any failure. 10s heartbeat to stderr proving the wrapper isn't wedged.
+- **`scripts/run-serial-tests.sh`** — runs `*.serial.test.ts` files at `--max-concurrency=1`. Invoked by the parallel wrapper after the parallel pass completes.
+
+#### Script extensions
+- **`scripts/run-unit-shard.sh`** — accepts `--max-concurrency=N` flag (forwarded to `bun test`). Excludes `*.serial.test.ts` in addition to `*.slow.test.ts`. `--dry-run-list` moved into argv parsing alongside, used by the regression tests.
+
+#### `package.json` script tier split
+- **`bun run test`** is now the fast parallel loop (was: full pipeline of 7 pre-checks + typecheck + sequential `bun test`).
+- **`bun run verify`** is CI's authoritative gate set: `check:privacy + check:jsonb + check:progress + check:wasm + typecheck`. The 4 pre-checks not in `verify` (no-legacy-getconnection, trailing-newline, exports-count) move to `bun run check:all` for opt-in local sweeps.
+- **`bun run test:full`** = `verify && parallel-test && slow-test && [smart e2e]`. Smart e2e gates on `DATABASE_URL` and prints a loud skip notice when missing.
+- **`bun run test:serial`** = run only `*.serial.test.ts`.
+- The privacy gate (`scripts/check-privacy.sh`) was previously only in the now-removed `bun run test` chain. It now runs via `bun run verify` and CI's `.github/workflows/test.yml` calls `bun run verify` directly — single source of truth for "what's the ship gate."
+
+#### CI tightening
+- **`.github/workflows/test.yml`** now runs `bun run verify` (was: 4 specific scripts inlined). Privacy check now actually fires on every CI run; previously it ran only when somebody manually invoked `bun run test`. The pre-existing `Wintermute` references in `src/core/mounts-cache.ts:6` and `:324` (introduced in earlier commits and surviving every CI green) were caught by the now-firing gate and replaced with `your OpenClaw` per the privacy rule.
+
+#### Failure-first logging
+- **`.context/test-failures.log`** — extracted failure blocks per shard, prefixed with `--- shard N: <test name> ---`. Cleared at the start of every wrapper run. Falls back to `/tmp/gbrain-test-failures.log` if `.context/` is unwritable.
+- **`.context/test-summary.txt`** — one-line-per-shard `pass=X fail=Y skip=Z rc=W` for at-a-glance status.
+- **Stderr banner** on any failure: absolute log path + last 30 lines inlined. Goes to stderr so it survives output pipes and agent-side log truncation.
+- **`.gitignore`** — added `.context/` so the failure log + summary + per-shard logs never accidentally commit.
+
+#### Quarantine
+- **`test/brain-registry.test.ts` → `test/brain-registry.serial.test.ts`** — 28 tests pass alone in 41ms; one ("empty/null/undefined id routes to host") fails under cross-file contention.
+- **`test/reconcile-links.test.ts` → `test/reconcile-links.serial.test.ts`** — 6 tests pass alone in 1s; a `beforeEach` hook times out (~896s) under cross-file contention.
+
+Both pass cleanly when run via `bun run test:serial`. The proper fix (sweep the shared-state contention sites) is filed as a P0 TODO.
+
+#### Regression tests (4 new files, 13 cases)
+- **`test/scripts/run-unit-parallel.test.ts`** (6 cases) — exit-code propagation: any failing shard → wrapper exits non-zero; failure-log contract: log written with `--- shard N:` prefix on failure, cleared on success; summary file format pinned. Uses a tempdir with 4 fixture tests so it runs in ~500ms instead of spawning the wrapper against the real suite.
+- **`test/scripts/run-unit-shard.test.ts`** (4 cases) — exclusion symmetry: unit-shard `--dry-run-list` excludes every `*.slow.test.ts`, every `*.serial.test.ts`, and the entire `test/e2e/` subtree.
+- **`test/scripts/serial-files.test.ts`** (3 cases) — every checked-in `*.serial.test.ts` is discovered by `run-serial-tests.sh`; the script invokes `bun test --max-concurrency=1`; serial set is disjoint from unit-shard set.
+- **`test/privacy-script-wired.test.ts`** updated — regression guard now asserts `verify` chains `check:privacy` AND that `.github/workflows/test.yml` calls `bun run verify`. Together those guarantee the privacy gate runs before any merge.
+
+#### `bunfig.toml`
+- Trimmed stale comment about typecheck-chained timeout. The 60s ceiling stands.
+
+### What did NOT ship in v0.26.4 (filed as P0 TODO for v0.27+)
+
+- **Intra-file parallelism via `--concurrent`** — sweeping ~58 PGLiteEngine sites + ~40 `process.env` mutations + 2 top-level `mock.module()` calls + per-test PGLite isolation via the existing `test/helpers/reset-pglite.ts`. After the sweep, every test can be marked `test.concurrent()` (or the runner can pass `--concurrent` globally). Empirical measurement on this branch suggests another 2-3x speedup on top of the file-level fan-out, but it's at least 1-2 weeks of careful refactoring across the test suite — well beyond v0.26.4's scope.
+- **E2E parallelism via Postgres template databases** — `CREATE DATABASE foo TEMPLATE gbrain_template` per test file. Filed as v0.27+ project. E2E tests still run sequentially.
+
+### Process
+
+The plan went through a multi-section eng review followed by Codex outside-voice review. Codex flagged 4 critical structural issues; user resolved all 4 via interactive AskUserQuestion. Three resolutions adopted Codex's view (parity test impossible, `freshPglite()` contradicts existing `resetPglite()` helper, `verify` was redefining the ship gate). One overrode Codex (keep the contention sweep in scope per original plan). After empirical measurement showed `--max-concurrency` doesn't do what the plan assumed, we surfaced the finding via AskUserQuestion and the user chose to ship the file-level win as v0.26.4 with the intra-file project as a P0 TODO. Total: 5 atomic bisect-friendly commits.
+
+### For contributors
+
+- The new wrapper is portable to macOS bash 3.2 (uses `while-read` instead of `mapfile`).
+- Heartbeat output is read-only — never writes to the failure log.
+- Failure-log extraction is single-writer (the wrapper itself, after `wait` returns) — no concurrent shard children racing on the same file.
+- If `.context/` is unwritable (read-only mount, hostile CI), the wrapper falls back to `/tmp/` and prints the absolute path in the banner.
+
 ## [0.26.3] - 2026-05-03
 
 ## **Admin dashboard you can trust. Magic-link login, single-use URLs, per-client token TTLs, observable everything.**
diff --git a/CLAUDE.md b/CLAUDE.md
index 6e33b8f7b..446f25a0f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -297,6 +297,49 @@ Key commands added in v0.22.16 (claw-test friction loop):
 
 ## Testing
 
+### Test command tiers (v0.26.4 — parallel fast loop)
+
+Five tiers of test commands, each with a clear scope:
+
+| Command | What it runs | Wallclock | When to use |
+|---|---|---|---|
+| `bun run test` | Parallel unit-test fast loop. 8-shard fan-out via `scripts/run-unit-parallel.sh`, then a serial pass over `*.serial.test.ts`. Excludes `*.slow.test.ts` and `test/e2e/*`. No pre-checks, no typecheck. | ~85s on a Mac dev box (3650+ tests) | Inner edit loop. Default. |
+| `bun run verify` | CI's authoritative pre-test gate set: `check:privacy && check:jsonb && check:progress && check:wasm && bun run typecheck`. The 4 checks `.github/workflows/test.yml` runs on shard 1 + typecheck. Single source of truth — CI literally calls `bun run verify`. | ~12s (wasm-compile dominates) | Before pushing; before `/ship`. |
+| `bun run test:full` | `verify && bun run test && bun run test:slow && [smart e2e]`. The local equivalent of "everything CI runs." Smart e2e: runs e2e only when `DATABASE_URL` is set; else loud skip notice to stderr. | ~3-5min depending on slow + e2e | Pre-merge sanity, before opening a PR. |
+| `bun run test:slow` | Just the `*.slow.test.ts` set (intentional cold-path correctness checks). | seconds-to-minutes | When touching slow-path code. |
+| `bun run test:serial` | Just the `*.serial.test.ts` set (cross-file-contention quarantine; runs at `--max-concurrency=1`). | ~1s per quarantined file | Debugging a specific quarantined file. |
+| `bun run test:e2e` | Real Postgres E2E. Requires Docker + `DATABASE_URL`. Sequential (template-DB parallelization is a v0.27+ TODO). | ~5-10min | Pre-ship; nightly. |
+| `bun run check:all` | All 7 historical pre-checks (privacy + jsonb + progress + no-legacy-getconnection + trailing-newline + wasm + exports-count). Superset of `verify`. | ~10s | Local-only sweep. The 4 not in `verify` are nice-to-haves. |
+
+### CI vs local: intentionally divergent file sets
+
+- **CI matrix** (`.github/workflows/test.yml`) runs `scripts/test-shard.sh` 4-way, which uses FNV-1a hash bucketing and INCLUDES `*.slow.test.ts`. CI is the ground truth for "did everything pass."
+- **Local fast loop** (`scripts/run-unit-shard.sh` via the parallel wrapper) uses round-robin-by-index sharding and EXCLUDES `*.slow.test.ts` AND `*.serial.test.ts`. Local trades coverage for inner-loop speed; CI catches what local skips.
+
+This divergence is intentional. Don't try to make them equal — the two scripts deliberately solve different problems. The regression test at `test/scripts/run-unit-shard.test.ts` pins what the local fast loop should and shouldn't include.
+
+### Failure-first logging
+
+When `bun run test` finds any failure, the wrapper:
+
+1. Writes failure blocks (each prefixed with `--- shard N: <test name> ---`) to `.context/test-failures.log` (workspace-local, gitignored). On systems without a writable `.context/`, falls back to `/tmp/gbrain-test-failures.log`.
+2. Prints a loud stderr banner with the absolute log path, plus the last 30 lines of the failure log inlined. Banner survives `| head` / `| tail` / agent-side log truncation.
+3. Writes a one-line-per-shard summary to `.context/test-summary.txt` (`shard N/M: pass=X fail=Y skip=Z rc=W`).
+4. Exits non-zero. Empty failure log + non-zero exit = infrastructure problem (wedged shard, killed child); the banner says so.
+
+If a shard wedges (per-shard `GBRAIN_TEST_SHARD_TIMEOUT` cap, default 600s), the wrapper writes `--- shard N: WEDGED after ${SHARD_TIMEOUT}s ---` to the failure log, includes the last 50 lines of the shard log, and proceeds with other shards' results.
+
+### File taxonomy
+
+- `*.test.ts` → fast loop (parallel 8-shard fan-out).
+- `*.slow.test.ts` → run via `bun run test:slow` only (intentional cold-path tests; would dominate the fast loop's wallclock).
+- `*.serial.test.ts` → run via `bun run test:serial` after the parallel pass completes; uses `--max-concurrency=1`. Quarantine for tests that share file-wide state and race when run alongside other files in the same `bun test` process. Currently: `test/brain-registry.serial.test.ts`, `test/reconcile-links.serial.test.ts`. **Do not put the parallelism back on a serial file unless you've fixed the contention root cause** (it just re-introduces the flake).
+- `test/e2e/*.test.ts` → real-Postgres E2E. Skipped when `DATABASE_URL` is unset.
+
+The intra-file parallelism project (turn `bun test` into `bun test --concurrent` after sweeping shared-state contention sites — ~58 PGLite + ~40 env-mutation + ~2 mock.module sites) is filed as a P0 TODO for a follow-up release. v0.26.4 ships file-level parallelism only.
+
+### Inventory (legacy)
+
 `bun test` runs all tests. After the v0.12.1 release: ~75 unit test files + 8 E2E test files (1412 unit pass, 119 E2E when `DATABASE_URL` is set — skip gracefully otherwise). Unit tests run
 without a database. E2E tests skip gracefully when `DATABASE_URL` is not set.
 
diff --git a/TODOS.md b/TODOS.md
index eb49f295c..10ac89061 100644
--- a/TODOS.md
+++ b/TODOS.md
@@ -1,5 +1,69 @@
 # TODOS
 
+## test infra (v0.26.4 follow-up — intra-file parallelism)
+
+### Sweep cross-file shared-state contention; enable `bun test --concurrent` for another 2-3x speedup
+**Priority:** P0
+
+**What:** v0.26.4 shipped file-level parallel fan-out (8 shards) and got `bun run test` from 18 minutes to ~85s — a 12x speedup. The next layer is **intra-file** parallelism via Bun's `--concurrent` flag (or per-test `test.concurrent()` markers). This requires every test file to be safe under concurrent execution within the same `bun test` process.
+
+The constraint: when multiple test files load into the same bun process (which is what `bun test foo.test.ts bar.test.ts ...` does inside a shard), they share module-level state. Three contention surfaces today:
+
+- **~58 PGLiteEngine instantiations** across `test/` (per codex's grep). Many use module-level `let engine: PGLiteEngine` patterns. Race when multiple test files load and each invokes `new PGLiteEngine().connect({})`.
+- **~40 process.env mutations** without restore. `process.env.X = '...'` not paired with `afterEach` cleanup leaks across files in the same process.
+- **2 top-level `mock.module(...)` calls** in `test/core/cycle.test.ts:26` and `test/embed.test.ts`. Top-level mocks affect every other test file in the same process.
+
+The repo already has the right helper: `test/helpers/reset-pglite.ts` exports `resetPgliteState(engine)` which is "two orders of magnitude faster" than fresh-engine-per-test (per the helper's own comment). Sweep all PGLite sites to use one shared engine + this reset in `beforeEach`. Do NOT introduce a `freshPglite()` allocator — codex correctly flagged that the repo already rejected that direction.
+
+Two flakes already known and quarantined as `*.serial.test.ts` (run after parallel pass at `--max-concurrency=1`):
+- `test/brain-registry.serial.test.ts` (was `brain-registry.test.ts`)
+- `test/reconcile-links.serial.test.ts` (was `reconcile-links.test.ts`)
+
+After the sweep, both should be fixable and renameable back to plain `*.test.ts`.
+
+**Why:**
+- 2-3x additional speedup on top of v0.26.4's 12x. Target: `bun run test` < 30s on a Mac dev box.
+- Forces the test architecture to be principled (no shared mutable state across files in the same process).
+- The empirical proof point: when `bun run test` was first measured at v0.26.4, two flakes surfaced under cross-file pressure that pass cleanly in isolation. That same pattern WILL surface more flakes if the suite grows. Better to sweep proactively than to keep growing the `*.serial.test.ts` quarantine.
+
+**Pros:**
+- Real architectural win, not just speed: tests become composable.
+- Existing helper (`test/helpers/reset-pglite.ts`) already validates the pattern.
+- Quarantined flakes auto-resolve: rename back to `*.test.ts` after the sweep.
+
+**Cons:**
+- 1-2 weeks of careful refactoring across ~100 test files.
+- Some tests genuinely need shared file-wide state (top-level mocks for module-replacement tests). Those stay quarantined as `*.serial.test.ts` permanently — but the count should shrink to a known small set, not grow.
+
+**Context:** v0.26.4 plan considered doing this in scope (Codex Tension #2 = C). After empirical measurement showed `--max-concurrency=4` does nothing on tests not marked `test.concurrent()`, the user chose to ship v0.26.4 as file-level-only and file this as the v0.27+ project. Plan file: `~/.claude/plans/system-instruction-you-are-working-tranquil-ladybug.md`. Codex critical findings #2, #3, #6 are all relevant.
+
+**Acceptance criteria:**
+1. All ~58 PGLiteEngine sites use shared-engine + `resetPgliteState()` in `beforeEach`.
+2. All ~40 `process.env` mutations use a `withEnv(...)` helper that saves + restores.
+3. The 2 top-level `mock.module()` calls scoped to `beforeEach`/`afterEach`, OR the file moves to `*.serial.test.ts`.
+4. Wrapper passes `--concurrent` (or every test marked `.concurrent()`).
+5. `bun run test` runs 5 times consecutively without flakes.
+6. Quarantine count `≤5` after the sweep (currently 2; goal is to get those 2 unquarantined and not add new ones).
+7. Wallclock target: `bun run test` < 30s.
+
+**Estimated effort:** 1-2 weeks of one engineer's focused work. Could parallelize by sub-area (env-mutation sweep is independent of PGLite sweep).
+
+### Speed up E2E via Postgres template databases
+**Priority:** P1
+
+**What:** E2E tests (`bun run test:e2e`) currently run sequentially in one shared Postgres container, each test file calling `initSchema()` from scratch (~5-20s each on cold init). Speed-up: build the schema ONCE into a template DB (`gbrain_template`), then have each test file `CREATE DATABASE foo TEMPLATE gbrain_template` (~50ms per clone). With per-shard `DATABASE_URL` overrides, E2E can fan out to N parallel shards too.
+
+**Why:** Current E2E wallclock is ~5-10 min in CI. Template DB clones could bring that to ~1-2 min. Critical for the inner loop on E2E-bearing PRs (currently a real friction point per `/ship` workflow).
+
+**Sketch:**
+1. Build template DB once via `initSchema()` against `gbrain_template`.
+2. Per-test-file: `CREATE DATABASE gbrain_test_clone_<n> TEMPLATE gbrain_template` (50ms vs 5-20s).
+3. Per-shard isolation via `DATABASE_URL` env override.
+4. Schema-version stamp on the template so it invalidates when `migrate.ts` changes.
+5. Cleanup via `DROP DATABASE` in afterAll.
+
+**Estimated effort:** 1-2 days. Filed during v0.26.4 plan as a deferred follow-up (D4 = B).
+
 ## test infra (v0.26.2 follow-up — pre-existing failures triage)
 
 ### Fix 22 pre-existing test failures unrelated to OAuth
diff --git a/VERSION b/VERSION
index 3f45a6442..12a91df0e 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.26.3
+0.26.4
diff --git a/bunfig.toml b/bunfig.toml
index facf1e75a..1faca8754 100644
--- a/bunfig.toml
+++ b/bunfig.toml
@@ -1,12 +1,9 @@
 [test]
-# PGLite initialization can be slow under parallel test execution.
-# Default 5s is too short when many test files boot PGLite instances at once.
-# 60s is the empirical ceiling we observed before the first file's beforeAll
-# completed on a loaded machine.
+# PGLite WASM cold start + initSchema() runs ~5–20s on loaded machines.
+# Default 5s is too short for those tests' beforeAll hooks. 60s is the
+# empirical ceiling we observed for the slowest cold-init paths.
 #
-# NOTE: this bunfig.toml `timeout` key is read by `bun test` but empirically
-# does NOT apply to beforeEach/afterEach hook timeouts under `bun run test`
-# chained behind `bun run typecheck`. The test script in package.json passes
-# `--timeout=60000` explicitly to cover both per-test and per-hook timeouts.
-# Leaving both in place as belt-and-suspenders.
+# v0.26.4: scripts/run-unit-parallel.sh and scripts/run-unit-shard.sh
+# also pass `--timeout=60000` explicitly so the ceiling is consistent
+# whether tests are invoked through the wrapper or directly via bun test.
 timeout = 60_000
diff --git a/llms-full.txt b/llms-full.txt
index ee00ca24b..b0b58d37c 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -394,6 +394,49 @@ Key commands added in v0.22.16 (claw-test friction loop):
 
 ## Testing
 
+### Test command tiers (v0.26.4 — parallel fast loop)
+
+Five tiers of test commands, each with a clear scope:
+
+| Command | What it runs | Wallclock | When to use |
+|---|---|---|---|
+| `bun run test` | Parallel unit-test fast loop. 8-shard fan-out via `scripts/run-unit-parallel.sh`, then a serial pass over `*.serial.test.ts`. Excludes `*.slow.test.ts` and `test/e2e/*`. No pre-checks, no typecheck. | ~85s on a Mac dev box (3650+ tests) | Inner edit loop. Default. |
+| `bun run verify` | CI's authoritative pre-test gate set: `check:privacy && check:jsonb && check:progress && check:wasm && bun run typecheck`. The 4 checks `.github/workflows/test.yml` runs on shard 1 + typecheck. Single source of truth — CI literally calls `bun run verify`. | ~12s (wasm-compile dominates) | Before pushing; before `/ship`. |
+| `bun run test:full` | `verify && bun run test && bun run test:slow && [smart e2e]`. The local equivalent of "everything CI runs." Smart e2e: runs e2e only when `DATABASE_URL` is set; else loud skip notice to stderr. | ~3-5min depending on slow + e2e | Pre-merge sanity, before opening a PR. |
+| `bun run test:slow` | Just the `*.slow.test.ts` set (intentional cold-path correctness checks). | seconds-to-minutes | When touching slow-path code. |
+| `bun run test:serial` | Just the `*.serial.test.ts` set (cross-file-contention quarantine; runs at `--max-concurrency=1`). | ~1s per quarantined file | Debugging a specific quarantined file. |
+| `bun run test:e2e` | Real Postgres E2E. Requires Docker + `DATABASE_URL`. Sequential (template-DB parallelization is a v0.27+ TODO). | ~5-10min | Pre-ship; nightly. |
+| `bun run check:all` | All 7 historical pre-checks (privacy + jsonb + progress + no-legacy-getconnection + trailing-newline + wasm + exports-count). Superset of `verify`. | ~10s | Local-only sweep. The 4 not in `verify` are nice-to-haves. |
+
+### CI vs local: intentionally divergent file sets
+
+- **CI matrix** (`.github/workflows/test.yml`) runs `scripts/test-shard.sh` 4-way, which uses FNV-1a hash bucketing and INCLUDES `*.slow.test.ts`. CI is the ground truth for "did everything pass."
+- **Local fast loop** (`scripts/run-unit-shard.sh` via the parallel wrapper) uses round-robin-by-index sharding and EXCLUDES `*.slow.test.ts` AND `*.serial.test.ts`. Local trades coverage for inner-loop speed; CI catches what local skips.
+
+This divergence is intentional. Don't try to make them equal — the two scripts deliberately solve different problems. The regression test at `test/scripts/run-unit-shard.test.ts` pins what the local fast loop should and shouldn't include.
+
+### Failure-first logging
+
+When `bun run test` finds any failure, the wrapper:
+
+1. Writes failure blocks (each prefixed with `--- shard N: <test name> ---`) to `.context/test-failures.log` (workspace-local, gitignored). On systems without a writable `.context/`, falls back to `/tmp/gbrain-test-failures.log`.
+2. Prints a loud stderr banner with the absolute log path, plus the last 30 lines of the failure log inlined. Banner survives `| head` / `| tail` / agent-side log truncation.
+3. Writes a one-line-per-shard summary to `.context/test-summary.txt` (`shard N/M: pass=X fail=Y skip=Z rc=W`).
+4. Exits non-zero. Empty failure log + non-zero exit = infrastructure problem (wedged shard, killed child); the banner says so.
+
+If a shard wedges (per-shard `GBRAIN_TEST_SHARD_TIMEOUT` cap, default 600s), the wrapper writes `--- shard N: WEDGED after ${SHARD_TIMEOUT}s ---` to the failure log, includes the last 50 lines of the shard log, and proceeds with other shards' results.
+
+### File taxonomy
+
+- `*.test.ts` → fast loop (parallel 8-shard fan-out).
+- `*.slow.test.ts` → run via `bun run test:slow` only (intentional cold-path tests; would dominate the fast loop's wallclock).
+- `*.serial.test.ts` → run via `bun run test:serial` after the parallel pass completes; uses `--max-concurrency=1`. Quarantine for tests that share file-wide state and race when run alongside other files in the same `bun test` process. Currently: `test/brain-registry.serial.test.ts`, `test/reconcile-links.serial.test.ts`. **Do not put the parallelism back on a serial file unless you've fixed the contention root cause** (it just re-introduces the flake).
+- `test/e2e/*.test.ts` → real-Postgres E2E. Skipped when `DATABASE_URL` is unset.
+
+The intra-file parallelism project (turn `bun test` into `bun test --concurrent` after sweeping shared-state contention sites — ~58 PGLite + ~40 env-mutation + ~2 mock.module sites) is filed as a P0 TODO for a follow-up release. v0.26.4 ships file-level parallelism only.
+
+### Inventory (legacy)
+
 `bun test` runs all tests. After the v0.12.1 release: ~75 unit test files + 8 E2E test files (1412 unit pass, 119 E2E when `DATABASE_URL` is set — skip gracefully otherwise). Unit tests run
 without a database. E2E tests skip gracefully when `DATABASE_URL` is not set.
 
diff --git a/package.json b/package.json
index 9cf5d6b0e..f9784feaf 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gbrain",
-  "version": "0.26.3",
+  "version": "0.26.4",
   "description": "Postgres-native personal knowledge brain with hybrid RAG search",
   "type": "module",
   "main": "src/core/index.ts",
@@ -34,12 +34,16 @@
     "build:schema": "bash scripts/build-schema.sh",
     "build:llms": "bun run scripts/build-llms.ts",
     "build:pglite-snapshot": "bun run scripts/build-pglite-snapshot.ts",
-    "test": "scripts/check-privacy.sh && scripts/check-jsonb-pattern.sh && scripts/check-progress-to-stdout.sh && scripts/check-no-legacy-getconnection.sh && scripts/check-trailing-newline.sh && scripts/check-wasm-embedded.sh && scripts/check-exports-count.sh && scripts/check-admin-build.sh && bun run typecheck && bun test --timeout=60000",
+    "test": "bash scripts/run-unit-parallel.sh",
+    "test:full": "bun run verify && bash scripts/run-unit-parallel.sh && bun run test:slow && ([ -n \"$DATABASE_URL\" ] && bash scripts/run-e2e.sh || echo '[test:full] skipped E2E (no DATABASE_URL); run docker-compose -f docker-compose.ci.yml up + bun run test:e2e to include' 1>&2)",
+    "verify": "bun run check:privacy && bun run check:jsonb && bun run check:progress && bun run check:wasm && bun run check:admin-build && bun run typecheck",
+    "check:all": "scripts/check-privacy.sh && scripts/check-jsonb-pattern.sh && scripts/check-progress-to-stdout.sh && scripts/check-no-legacy-getconnection.sh && scripts/check-trailing-newline.sh && scripts/check-wasm-embedded.sh && scripts/check-exports-count.sh && scripts/check-admin-build.sh",
     "check:wasm": "scripts/check-wasm-embedded.sh",
     "check:newlines": "scripts/check-trailing-newline.sh",
     "test:e2e": "bash scripts/run-e2e.sh",
     "test:slow": "bash scripts/run-slow-tests.sh",
     "test:profile": "bash scripts/profile-tests.sh",
+    "test:serial": "bash scripts/run-serial-tests.sh",
     "ci:local": "bash scripts/ci-local.sh",
     "ci:local:diff": "bash scripts/ci-local.sh --diff",
     "ci:select-e2e": "bun run scripts/select-e2e.ts",
diff --git a/scripts/run-serial-tests.sh b/scripts/run-serial-tests.sh
new file mode 100755
index 000000000..f54321827
--- /dev/null
+++ b/scripts/run-serial-tests.sh
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# scripts/run-serial-tests.sh — run *.serial.test.ts files with --max-concurrency=1.
+#
+# Serial files are tests that share file-wide state (top-level mock.module,
+# module-level singletons that intentionally cross test cases) and would race
+# under intra-file concurrency. Discovered via filename suffix; no annotation
+# inside the file is needed.
+#
+# Excluded by run-unit-shard.sh and run-unit-parallel.sh's parallel pass.
+# Invoked separately by run-unit-parallel.sh after the parallel pass succeeds.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# Use while-read for portability to macOS bash 3.2 (no mapfile).
+files=()
+while IFS= read -r f; do
+  files+=("$f")
+done < <(find test -name '*.serial.test.ts' -not -path 'test/e2e/*' | sort)
+
+if [ "${#files[@]}" -eq 0 ]; then
+  echo "[serial-tests] no *.serial.test.ts files found"
+  exit 0
+fi
+
+# --dry-run-list mirrors run-unit-shard.sh for inline checks/tests.
+if [ "${1:-}" = "--dry-run-list" ]; then
+  printf '%s\n' "${files[@]}"
+  exit 0
+fi
+
+echo "[serial-tests] running ${#files[@]} file(s) with --max-concurrency=1"
+exec bun test --max-concurrency=1 --timeout=60000 "${files[@]}"
diff --git a/scripts/run-unit-parallel.sh b/scripts/run-unit-parallel.sh
new file mode 100755
index 000000000..cb2a95d95
--- /dev/null
+++ b/scripts/run-unit-parallel.sh
@@ -0,0 +1,341 @@
+#!/usr/bin/env bash
+# scripts/run-unit-parallel.sh — fast unit-test loop, parallel fan-out.
+#
+# Spawns N parallel `bun test` processes, each running a hash-disjoint shard
+# of the unit-test set (files only — no e2e, no .slow, no .serial). After
+# all shards complete, runs serial-only files (*.serial.test.ts) with
+# --max-concurrency=1. Failure-first logging: extracts failure blocks from
+# each shard's log, writes to .context/test-failures.log with --- shard $i:
+# prefixes, prints loud stderr banner if any failures, exit non-zero.
+#
+# Usage:
+#   bash scripts/run-unit-parallel.sh [--shards N] [--max-concurrency N] [--dry-run]
+#
+# Env overrides:
+#   SHARDS=N                     same as --shards
+#   GBRAIN_TEST_SHARD_TIMEOUT    per-shard wallclock cap, seconds (default 600)
+#   GBRAIN_TEST_MAX_CONCURRENCY  passed through to bun test (default 4)
+#
+# Output files (workspace-local; falls back to /tmp if .context/ unwritable):
+#   .context/test-failures.log   failure blocks (cleared at start)
+#   .context/test-summary.txt    per-shard pass/fail/skip/duration (cleared at start)
+#   .context/test-shards/        per-shard logs + exit codes (cleared at start)
+
+set -uo pipefail
+
+cd "$(dirname "$0")/.."
+
+# ──────────────────────────────────────────────────────────────────────────
+# CPU detection: Apple Silicon perf cores → Mac total physical → nproc → 4.
+# Returns a single positive integer.
+# ──────────────────────────────────────────────────────────────────────────
+detect_cpus() {
+  local n=""
+  n=$(sysctl -n hw.perflevel0.physicalcpu 2>/dev/null) && [ -n "$n" ] && [ "$n" -gt 0 ] && echo "$n" && return
+  n=$(sysctl -n hw.physicalcpu 2>/dev/null) && [ -n "$n" ] && [ "$n" -gt 0 ] && echo "$n" && return
+  n=$(nproc 2>/dev/null) && [ -n "$n" ] && [ "$n" -gt 0 ] && echo "$n" && return
+  echo 4
+}
+
+# ──────────────────────────────────────────────────────────────────────────
+# Argument parsing. --shards N override wins over $SHARDS; both are clamped.
+# ──────────────────────────────────────────────────────────────────────────
+SHARDS_OVERRIDE=""
+MAX_CONCURRENCY_OVERRIDE=""
+DRY_RUN=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --shards) SHARDS_OVERRIDE="$2"; shift 2 ;;
+    --shards=*) SHARDS_OVERRIDE="${1#*=}"; shift ;;
+    --max-concurrency) MAX_CONCURRENCY_OVERRIDE="$2"; shift 2 ;;
+    --max-concurrency=*) MAX_CONCURRENCY_OVERRIDE="${1#*=}"; shift ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    *) echo "ERROR: unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+N="${SHARDS_OVERRIDE:-${SHARDS:-$(detect_cpus)}}"
+if ! printf '%s' "$N" | grep -qE '^[0-9]+$' || [ "$N" -lt 1 ]; then
+  echo "ERROR: invalid shard count: $N" >&2; exit 2
+fi
+[ "$N" -gt 8 ] && N=8
+
+INTRA_CONC="${MAX_CONCURRENCY_OVERRIDE:-${GBRAIN_TEST_MAX_CONCURRENCY:-4}}"
+SHARD_TIMEOUT="${GBRAIN_TEST_SHARD_TIMEOUT:-600}"
+
+# ──────────────────────────────────────────────────────────────────────────
+# Output directories. Prefer workspace-local .context/, fall back to /tmp.
+# ──────────────────────────────────────────────────────────────────────────
+LOG_DIR=""
+if mkdir -p .context/test-shards 2>/dev/null; then
+  LOG_DIR=".context/test-shards"
+  FAILURES_LOG=".context/test-failures.log"
+  SUMMARY_FILE=".context/test-summary.txt"
+else
+  LOG_DIR="/tmp/gbrain-test-shards-$$"
+  FAILURES_LOG="/tmp/gbrain-test-failures.log"
+  SUMMARY_FILE="/tmp/gbrain-test-summary.txt"
+  mkdir -p "$LOG_DIR" || { echo "ERROR: cannot create log dir" >&2; exit 2; }
+fi
+# Clear from prior run.
+rm -f "$LOG_DIR"/shard-*.log "$LOG_DIR"/shard-*.exit "$LOG_DIR"/shard-*.wedged 2>/dev/null
+: > "$FAILURES_LOG"
+: > "$SUMMARY_FILE"
+
+# ──────────────────────────────────────────────────────────────────────────
+# Resolve `timeout` command. macOS without coreutils has neither; we degrade
+# to bg-pid + sleep cap. For now, prefer gtimeout (brew coreutils) → timeout.
+# ──────────────────────────────────────────────────────────────────────────
+TIMEOUT_BIN=""
+if command -v gtimeout >/dev/null 2>&1; then TIMEOUT_BIN="gtimeout"
+elif command -v timeout >/dev/null 2>&1; then TIMEOUT_BIN="timeout"
+fi
+
+START_TS=$(date +%s)
+echo "[unit-parallel] N=$N shards | --max-concurrency=$INTRA_CONC | timeout=${SHARD_TIMEOUT}s | logs=$LOG_DIR" >&2
+
+if [ "$DRY_RUN" = "1" ]; then
+  echo "[unit-parallel] dry-run: would spawn $N shards with the above settings."
+  for i in $(seq 1 "$N"); do
+    SHARD="$i/$N" bash scripts/run-unit-shard.sh --dry-run-list 2>/dev/null \
+      | sed "s|^|  [s$i] |"
+  done
+  exit 0
+fi
+
+# ──────────────────────────────────────────────────────────────────────────
+# Spawn shards. Each child captures its own exit code into a sentinel file
+# so $? is recoverable per-shard (we never trust `wait`'s aggregate value).
+# ──────────────────────────────────────────────────────────────────────────
+SHARD_PIDS=()
+for i in $(seq 1 "$N"); do
+  (
+    SHARD_LOG="$LOG_DIR/shard-$i.log"
+    if [ -n "$TIMEOUT_BIN" ]; then
+      "$TIMEOUT_BIN" "${SHARD_TIMEOUT}s" \
+        env SHARD="$i/$N" \
+        bash scripts/run-unit-shard.sh --max-concurrency="$INTRA_CONC" \
+        > "$SHARD_LOG" 2>&1
+    else
+      env SHARD="$i/$N" \
+        bash scripts/run-unit-shard.sh --max-concurrency="$INTRA_CONC" \
+        > "$SHARD_LOG" 2>&1 &
+      pid=$!
+      ( sleep "$SHARD_TIMEOUT" && kill -TERM "$pid" 2>/dev/null && \
+        sleep 5 && kill -KILL "$pid" 2>/dev/null ) &
+      cap_pid=$!
+      wait "$pid" 2>/dev/null
+      kill "$cap_pid" 2>/dev/null
+      wait "$cap_pid" 2>/dev/null
+    fi
+    rc=$?
+    echo "$rc" > "$LOG_DIR/shard-$i.exit"
+    [ "$rc" = "124" ] && echo "WEDGED" > "$LOG_DIR/shard-$i.wedged"
+  ) &
+  SHARD_PIDS+=($!)
+done
+
+# ──────────────────────────────────────────────────────────────────────────
+# Heartbeat: every 10s, print per-shard progress to stderr by tailing logs
+# and counting Bun's `(pass)` / `(fail)` / `(skip)` markers. Read-only.
+# ──────────────────────────────────────────────────────────────────────────
+# grep_count: returns 0 (single integer) if file is missing or zero matches,
+# otherwise the match count. Avoids the `grep -c | echo 0` double-output bug
+# where 0 matches produces a 2-line "0\n0" string that breaks arithmetic.
+grep_count() {
+  local pattern="$1"; local file="$2"
+  if [ ! -f "$file" ]; then echo 0; return; fi
+  local n
+  n=$(grep -cE "$pattern" "$file" 2>/dev/null) || n=0
+  echo "${n:-0}"
+}
+
+# bun_summary_count: parses Bun's summary lines (one per `bun test` invocation
+# inside a shard — there's only one when we pass an explicit file list).
+# Looks for ` N pass` / ` N fail` / ` N skip` patterns and sums them across
+# all summary blocks the shard emitted. `bun test` prints these near the end
+# of its output. Format: leading whitespace + integer + space + label.
+bun_summary_count() {
+  local label="$1"; local file="$2"
+  if [ ! -f "$file" ]; then echo 0; return; fi
+  awk -v label="$label" '
+    $1 ~ /^[0-9]+$/ && $2 == label { total += $1 }
+    END { print total + 0 }
+  ' "$file"
+}
+
+heartbeat() {
+  while true; do
+    sleep 10
+    local line=""
+    for i in $(seq 1 "$N"); do
+      if [ -f "$LOG_DIR/shard-$i.exit" ]; then
+        local rc; rc=$(cat "$LOG_DIR/shard-$i.exit" 2>/dev/null || echo "?")
+        local status="✓"
+        [ "$rc" != "0" ] && status="✗"
+        line="$line [s$i: done $status]"
+      else
+        local lf="$LOG_DIR/shard-$i.log"
+        if [ -f "$lf" ]; then
+          # Heartbeat: prefer Bun's per-test "✓" (passed) and "(fail)" markers
+          # so we see live progress; the "N pass" summary line only appears at
+          # the very end of the shard and would always show 0 mid-run.
+          local p f
+          p=$(grep_count '^[[:space:]]+✓' "$lf")
+          f=$(grep_count '^\(fail\)' "$lf")
+          line="$line [s$i: ${p}p ${f}f ...]"
+        else
+          line="$line [s$i: starting]"
+        fi
+      fi
+    done
+    printf '[heartbeat] %s\n' "$line" >&2
+  done
+}
+heartbeat &
+HB_PID=$!
+trap 'kill "$HB_PID" 2>/dev/null; wait "$HB_PID" 2>/dev/null' EXIT
+
+# Wait for every shard. Don't care about wait's exit code.
+for pid in "${SHARD_PIDS[@]}"; do wait "$pid" 2>/dev/null || true; done
+
+kill "$HB_PID" 2>/dev/null
+wait "$HB_PID" 2>/dev/null
+trap - EXIT
+
+# ──────────────────────────────────────────────────────────────────────────
+# Aggregate failures (single writer; serial; never concurrent).
+# Bun failure block format: from `(fail) ...` line through next `(pass)`,
+# `(skip)`, blank line, or `__bun_test_summary__` marker.
+# ──────────────────────────────────────────────────────────────────────────
+TOTAL_FAILURES=0
+TOTAL_PASS=0
+TOTAL_SKIP=0
+TOTAL_RC=0
+for i in $(seq 1 "$N"); do
+  SHARD_LOG="$LOG_DIR/shard-$i.log"
+  EXIT_FILE="$LOG_DIR/shard-$i.exit"
+  WEDGED_FILE="$LOG_DIR/shard-$i.wedged"
+  rc=1
+  [ -f "$EXIT_FILE" ] && rc=$(cat "$EXIT_FILE" 2>/dev/null || echo 1)
+
+  pass_count=$(bun_summary_count "pass" "$SHARD_LOG")
+  fail_count=$(bun_summary_count "fail" "$SHARD_LOG")
+  skip_count=$(bun_summary_count "skip" "$SHARD_LOG")
+  TOTAL_PASS=$((TOTAL_PASS + pass_count))
+  TOTAL_FAILURES=$((TOTAL_FAILURES + fail_count))
+  TOTAL_SKIP=$((TOTAL_SKIP + skip_count))
+
+  if [ -f "$WEDGED_FILE" ]; then
+    TOTAL_RC=1
+    {
+      echo "--- shard $i: WEDGED after ${SHARD_TIMEOUT}s ---"
+      [ -f "$SHARD_LOG" ] && tail -50 "$SHARD_LOG"
+      echo ""
+    } >> "$FAILURES_LOG"
+    echo "shard $i/$N: WEDGED after ${SHARD_TIMEOUT}s (rc=$rc)" >> "$SUMMARY_FILE"
+    continue
+  fi
+
+  echo "shard $i/$N: pass=$pass_count fail=$fail_count skip=$skip_count rc=$rc" >> "$SUMMARY_FILE"
+
+  if [ "$rc" != "0" ]; then
+    TOTAL_RC=1
+    if [ "$fail_count" -gt 0 ] && [ -f "$SHARD_LOG" ]; then
+      # Extract each (fail) block: from `(fail)` line through next `(pass)`,
+      # `(skip)`, blank line, or `__bun_test_summary__`. Single awk pass.
+      awk -v shard="$i" '
+        /^\(fail\) / { in_block=1; print "--- shard " shard ": " $0; next }
+        in_block {
+          if (/^\(pass\)/ || /^\(skip\)/ || /^[[:space:]]*$/ || /__bun_test_summary__/) { in_block=0; print ""; next }
+          print $0
+        }
+      ' "$SHARD_LOG" >> "$FAILURES_LOG"
+    elif [ -f "$SHARD_LOG" ]; then
+      # Non-zero rc but no (fail) line found — extraction couldn't pinpoint.
+      # Dump the full shard log so we never silently lose the failure cause.
+      {
+        echo "--- shard $i: rc=$rc, no (fail) markers — full log follows ---"
+        cat "$SHARD_LOG"
+        echo ""
+      } >> "$FAILURES_LOG"
+    fi
+  fi
+done
+
+# ──────────────────────────────────────────────────────────────────────────
+# Print each shard's full output to stdout (developer expects to scroll
+# through it). Print summary file last for one-glance overview.
+# ──────────────────────────────────────────────────────────────────────────
+for i in $(seq 1 "$N"); do
+  SHARD_LOG="$LOG_DIR/shard-$i.log"
+  echo ""
+  echo "════════════ shard $i/$N ════════════"
+  [ -f "$SHARD_LOG" ] && cat "$SHARD_LOG"
+done
+echo ""
+echo "════════════ summary ════════════"
+cat "$SUMMARY_FILE"
+echo ""
+
+# ──────────────────────────────────────────────────────────────────────────
+# Serial pass: any *.serial.test.ts files run after parallel pass.
+# ──────────────────────────────────────────────────────────────────────────
+SERIAL_RC=0
+SERIAL_FILES_COUNT=0
+SERIAL_FILES_COUNT=$(find test -name '*.serial.test.ts' -not -path 'test/e2e/*' 2>/dev/null | wc -l | tr -d ' ')
+if [ "$SERIAL_FILES_COUNT" -gt 0 ]; then
+  echo "════════════ serial pass ($SERIAL_FILES_COUNT files) ════════════"
+  bash scripts/run-serial-tests.sh > "$LOG_DIR/serial.log" 2>&1
+  SERIAL_RC=$?
+  cat "$LOG_DIR/serial.log"
+  if [ "$SERIAL_RC" != "0" ]; then
+    TOTAL_RC=1
+    s_fail=$(bun_summary_count "fail" "$LOG_DIR/serial.log")
+    TOTAL_FAILURES=$((TOTAL_FAILURES + s_fail))
+    if [ "$s_fail" -gt 0 ]; then
+      awk '
+        /^\(fail\) / { in_block=1; print "--- shard serial: " $0; next }
+        in_block {
+          if (/^\(pass\)/ || /^\(skip\)/ || /^[[:space:]]*$/ || /__bun_test_summary__/) { in_block=0; print ""; next }
+          print $0
+        }
+      ' "$LOG_DIR/serial.log" >> "$FAILURES_LOG"
+    else
+      {
+        echo "--- shard serial: rc=$SERIAL_RC, no (fail) markers — full log follows ---"
+        cat "$LOG_DIR/serial.log"
+        echo ""
+      } >> "$FAILURES_LOG"
+    fi
+    echo "serial: rc=$SERIAL_RC fail=$s_fail" >> "$SUMMARY_FILE"
+  else
+    s_pass=$(bun_summary_count "pass" "$LOG_DIR/serial.log")
+    TOTAL_PASS=$((TOTAL_PASS + s_pass))
+    echo "serial: pass=$s_pass rc=0" >> "$SUMMARY_FILE"
+  fi
+fi
+
+END_TS=$(date +%s)
+ELAPSED=$((END_TS - START_TS))
+
+# ──────────────────────────────────────────────────────────────────────────
+# Loud banner if anything failed. To stderr so it survives `| head`/`| tail`.
+# ──────────────────────────────────────────────────────────────────────────
+if [ "$TOTAL_RC" != "0" ]; then
+  ABS_FAIL=$(cd "$(dirname "$FAILURES_LOG")" && pwd)/$(basename "$FAILURES_LOG")
+  {
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "❌ $TOTAL_FAILURES TEST FAILURES — full details:"
+    echo "   $ABS_FAIL"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    tail -30 "$FAILURES_LOG"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "[unit-parallel] elapsed=${ELAPSED}s | pass=$TOTAL_PASS fail=$TOTAL_FAILURES skip=$TOTAL_SKIP"
+  } >&2
+  exit 1
+fi
+
+echo "[unit-parallel] elapsed=${ELAPSED}s | pass=$TOTAL_PASS fail=$TOTAL_FAILURES skip=$TOTAL_SKIP" >&2
+exit 0
diff --git a/scripts/run-unit-shard.sh b/scripts/run-unit-shard.sh
index 1b5eb2451..67a8d8863 100755
--- a/scripts/run-unit-shard.sh
+++ b/scripts/run-unit-shard.sh
@@ -16,16 +16,29 @@ set -euo pipefail
 
 cd "$(dirname "$0")/.."
 
+# --max-concurrency=N is forwarded to `bun test`. v0.26.4: invoked by
+# run-unit-parallel.sh; safe to call without (defaults to bun's default cap).
+MAX_CONC=""
+DRY_RUN=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --max-concurrency) MAX_CONC="$2"; shift 2 ;;
+    --max-concurrency=*) MAX_CONC="${1#*=}"; shift ;;
+    --dry-run-list) DRY_RUN=1; shift ;;
+    *) echo "ERROR: unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
 # All non-E2E test files, sorted for deterministic shard splits.
-# Tier 4: *.slow.test.ts is the convention for "always-slow" tests (e.g.,
-# bootstrap correctness checks that intentionally exercise the cold init
-# path and can't benefit from Tier 3's snapshot). They're excluded from the
-# fast loop and run via `bun run test:slow` (or in CI where everything runs).
+# Tier 4: *.slow.test.ts is "always-slow" (cold-path correctness checks);
+# *.serial.test.ts is "concurrency-unsafe" (file-wide shared state). Both
+# are excluded from the fast loop. Slow runs via `bun run test:slow`; serial
+# runs via scripts/run-serial-tests.sh after the parallel pass.
 # Use while-read to stay portable to macOS bash 3.2 (no mapfile).
 all_files=()
 while IFS= read -r f; do
   all_files+=("$f")
-done < <(find test -name '*.test.ts' -not -path 'test/e2e/*' -not -name '*.slow.test.ts' | sort)
+done < <(find test -name '*.test.ts' -not -path 'test/e2e/*' -not -name '*.slow.test.ts' -not -name '*.serial.test.ts' | sort)
 
 files=()
 if [ -n "${SHARD:-}" ]; then
@@ -53,11 +66,13 @@ if [ "${#files[@]}" -eq 0 ]; then
   exit 0
 fi
 
-# --dry-run-list mirrors scripts/run-e2e.sh for inline smoke checks.
-if [ "${1:-}" = "--dry-run-list" ]; then
+if [ "$DRY_RUN" = "1" ]; then
   printf '%s\n' "${files[@]}"
   exit 0
 fi
 
 echo "[unit-shard ${SHARD:-(unsharded)}] running ${#files[@]} files"
+if [ -n "$MAX_CONC" ]; then
+  exec bun test --max-concurrency="$MAX_CONC" --timeout=60000 "${files[@]}"
+fi
 exec bun test --timeout=60000 "${files[@]}"
diff --git a/src/core/mounts-cache.ts b/src/core/mounts-cache.ts
index 392bc3362..0e74639df 100644
--- a/src/core/mounts-cache.ts
+++ b/src/core/mounts-cache.ts
@@ -321,7 +321,7 @@ export function renderResolverMarkdown(composed: ComposedResolver): string {
   lines.push('# GBrain Skill Resolver (aggregated)');
   lines.push('');
   lines.push('Auto-generated by `gbrain mounts add|remove|sync`. Do not edit by hand.');
-  lines.push('Host agents (your OpenClaw / Claude Code) should prefer this file over');
+  lines.push('Host agents (your OpenClaw / Claude Code install) should prefer this file over');
   lines.push('the repo-checked-in `skills/RESOLVER.md` when it exists.');
   lines.push('');
   lines.push('See `docs/architecture/brains-and-sources.md` for the mental model.');
diff --git a/test/brain-registry.test.ts b/test/brain-registry.serial.test.ts
similarity index 100%
rename from test/brain-registry.test.ts
rename to test/brain-registry.serial.test.ts
diff --git a/test/privacy-script-wired.test.ts b/test/privacy-script-wired.test.ts
index 1e0500bfb..993c00f26 100644
--- a/test/privacy-script-wired.test.ts
+++ b/test/privacy-script-wired.test.ts
@@ -1,15 +1,17 @@
 /**
- * Regression guard: scripts/check-privacy.sh must be wired into the
- * `bun run test` chain.
+ * Regression guard: scripts/check-privacy.sh must run in CI's auto-pipeline.
  *
- * CLAUDE.md:550 bans the private OpenClaw fork name from public
- * artifacts. scripts/check-privacy.sh is the enforcement mechanism.
- * If someone refactors the test script and drops the privacy check,
- * this test fails loudly.
+ * CLAUDE.md bans the private OpenClaw fork name from public artifacts.
+ * scripts/check-privacy.sh is the enforcement mechanism. If someone
+ * refactors the script chain and drops the privacy check, this test
+ * fails loudly.
  *
- * The assertion is a substring match against package.json's
- * scripts.test field. Deliberately simple: the goal is to detect
- * accidental unwiring, not to validate the shell chain's semantics.
+ * v0.26.4 split: `bun run test` is now the fast parallel loop and does
+ * NOT chain pre-checks; the privacy gate moved to `bun run verify`,
+ * which CI's test.yml runs on shard 1 before the matrix fans out.
+ * Regression guard now asserts both: (1) verify chains check:privacy,
+ * (2) CI workflow's pre-test gate calls `bun run verify`. Together those
+ * guarantee the privacy check runs before any merge.
  */
 
 import { describe, it, expect } from 'bun:test';
@@ -19,26 +21,30 @@ import { resolve } from 'path';
 const REPO_ROOT = resolve(import.meta.dir, '..');
 const PACKAGE_JSON = resolve(REPO_ROOT, 'package.json');
 const PRIVACY_SCRIPT = resolve(REPO_ROOT, 'scripts/check-privacy.sh');
+const TEST_WORKFLOW = resolve(REPO_ROOT, '.github/workflows/test.yml');
 
 describe('check-privacy.sh CI wiring', () => {
   it('scripts/check-privacy.sh exists and is executable', () => {
     expect(existsSync(PRIVACY_SCRIPT)).toBe(true);
     const stat = require('fs').statSync(PRIVACY_SCRIPT);
-    // Mode has user-exec bit set.
     // eslint-disable-next-line no-bitwise
     expect((stat.mode & 0o100) !== 0).toBe(true);
   });
 
-  it('package.json "test" script includes check-privacy.sh', () => {
+  it('package.json "verify" script chains check:privacy', () => {
     const pkg = JSON.parse(readFileSync(PACKAGE_JSON, 'utf-8'));
-    expect(typeof pkg.scripts?.test).toBe('string');
-    expect(pkg.scripts.test).toContain('check-privacy.sh');
+    expect(typeof pkg.scripts?.verify).toBe('string');
+    expect(pkg.scripts.verify).toContain('check:privacy');
   });
 
-  it('package.json exposes a "check:privacy" convenience alias', () => {
-    // Not load-bearing for CI, but prevents the script from disappearing
-    // from the scripts map during a refactor.
+  it('package.json "check:privacy" alias points at the script', () => {
     const pkg = JSON.parse(readFileSync(PACKAGE_JSON, 'utf-8'));
     expect(pkg.scripts?.['check:privacy']).toContain('check-privacy.sh');
   });
+
+  it('CI test.yml runs `bun run verify` so the privacy gate fires', () => {
+    expect(existsSync(TEST_WORKFLOW)).toBe(true);
+    const yml = readFileSync(TEST_WORKFLOW, 'utf-8');
+    expect(yml).toContain('bun run verify');
+  });
 });
diff --git a/test/reconcile-links.test.ts b/test/reconcile-links.serial.test.ts
similarity index 100%
rename from test/reconcile-links.test.ts
rename to test/reconcile-links.serial.test.ts
diff --git a/test/scripts/run-unit-parallel.test.ts b/test/scripts/run-unit-parallel.test.ts
new file mode 100644
index 000000000..e19925a2f
--- /dev/null
+++ b/test/scripts/run-unit-parallel.test.ts
@@ -0,0 +1,156 @@
+/**
+ * Regression tests (a) + (d) for scripts/run-unit-parallel.sh:
+ *   (a) Exit-code propagation: a failing test in any shard MUST cause the
+ *       wrapper to exit non-zero. The hardest contract to silently break
+ *       in a fan-out wrapper (`for ... &; wait` returns the LAST child's
+ *       status, not any failure's).
+ *   (d) Failure-log contract: when any test fails, the wrapper writes
+ *       extracted failure block(s) to .context/test-failures.log with
+ *       `--- shard $i:` prefixes, and prints a loud stderr banner with
+ *       the absolute path. Empty log ⇔ exit 0.
+ *
+ * The wrapper takes ~1.5 minutes against the real test suite. To keep
+ * this regression test fast and hermetic, we point it at a tiny tempdir
+ * containing one passing and one failing test, override the discovery
+ * roots via env-vars, and run with --shards=2.
+ *
+ * NOT covered here: the heartbeat (timing-sensitive, not load-bearing
+ * for correctness) and timeout / WEDGED markers (require synthesizing a
+ * hung test which is fragile across machines). Those rely on the live
+ * smoke tests captured in CHANGELOG measurements.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'bun:test';
+import { execFileSync, spawnSync } from 'child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync, copyFileSync, chmodSync } from 'fs';
+import { tmpdir } from 'os';
+import { join, resolve } from 'path';
+
+const REPO_ROOT = resolve(import.meta.dir, '..', '..');
+const PARALLEL_SH_SRC = resolve(REPO_ROOT, 'scripts/run-unit-parallel.sh');
+const SHARD_SH_SRC = resolve(REPO_ROOT, 'scripts/run-unit-shard.sh');
+const SERIAL_SH_SRC = resolve(REPO_ROOT, 'scripts/run-serial-tests.sh');
+
+let TMPROOT: string;
+
+beforeAll(() => {
+  // Build a tiny repo-shaped tempdir with the wrapper scripts copied in
+  // and 4 fixture test files (3 pass, 1 fail). The wrapper's `find test`
+  // expression will pick them up via cwd.
+  TMPROOT = mkdtempSync(join(tmpdir(), 'gbrain-parallel-test-'));
+  mkdirSync(join(TMPROOT, 'scripts'), { recursive: true });
+  mkdirSync(join(TMPROOT, 'test'), { recursive: true });
+
+  copyFileSync(PARALLEL_SH_SRC, join(TMPROOT, 'scripts', 'run-unit-parallel.sh'));
+  copyFileSync(SHARD_SH_SRC, join(TMPROOT, 'scripts', 'run-unit-shard.sh'));
+  copyFileSync(SERIAL_SH_SRC, join(TMPROOT, 'scripts', 'run-serial-tests.sh'));
+  chmodSync(join(TMPROOT, 'scripts', 'run-unit-parallel.sh'), 0o755);
+  chmodSync(join(TMPROOT, 'scripts', 'run-unit-shard.sh'), 0o755);
+  chmodSync(join(TMPROOT, 'scripts', 'run-serial-tests.sh'), 0o755);
+
+  // 3 passing + 1 failing test file. Round-robin sharding will land
+  // them across 2 shards so we exercise the multi-shard merge path.
+  const passing = `import { describe, it, expect } from 'bun:test';
+describe('passing', () => {
+  it('arithmetic works', () => { expect(1 + 1).toBe(2); });
+});`;
+  const failing = `import { describe, it, expect } from 'bun:test';
+describe('failing-on-purpose', () => {
+  it('expects 1 to equal 2 (this should fail)', () => { expect(1).toBe(2); });
+});`;
+
+  writeFileSync(join(TMPROOT, 'test', 'a-pass.test.ts'), passing);
+  writeFileSync(join(TMPROOT, 'test', 'b-pass.test.ts'), passing);
+  writeFileSync(join(TMPROOT, 'test', 'c-pass.test.ts'), passing);
+  writeFileSync(join(TMPROOT, 'test', 'd-fail.test.ts'), failing);
+});
+
+afterAll(() => {
+  if (TMPROOT) rmSync(TMPROOT, { recursive: true, force: true });
+});
+
+function runWrapper(extraArgs: string[] = []): { code: number; stdout: string; stderr: string } {
+  const result = spawnSync(
+    'bash',
+    [join(TMPROOT, 'scripts', 'run-unit-parallel.sh'), '--shards', '2', ...extraArgs],
+    { cwd: TMPROOT, encoding: 'utf-8', env: { ...process.env } },
+  );
+  return {
+    code: result.status ?? -1,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+  };
+}
+
+describe('run-unit-parallel.sh exit-code propagation (a)', () => {
+  it('exits non-zero when any shard contains a failing test', () => {
+    const r = runWrapper();
+    expect(r.code).not.toBe(0);
+  });
+
+  it('exits zero when all shards pass (after removing the failing fixture)', () => {
+    rmSync(join(TMPROOT, 'test', 'd-fail.test.ts'));
+    try {
+      const r = runWrapper();
+      expect(r.code).toBe(0);
+    } finally {
+      // Restore the failing fixture for any downstream tests in the same
+      // describe block (afterAll cleans the whole tempdir; this is belt-
+      // and-suspenders).
+      const failing = `import { describe, it, expect } from 'bun:test';
+describe('failing-on-purpose', () => {
+  it('expects 1 to equal 2', () => { expect(1).toBe(2); });
+});`;
+      writeFileSync(join(TMPROOT, 'test', 'd-fail.test.ts'), failing);
+    }
+  });
+});
+
+describe('run-unit-parallel.sh failure-log contract (d)', () => {
+  it('writes failures to .context/test-failures.log with --- shard prefix on failure', () => {
+    const r = runWrapper();
+    expect(r.code).not.toBe(0);
+
+    const failureLog = join(TMPROOT, '.context/test-failures.log');
+    expect(existsSync(failureLog)).toBe(true);
+    const contents = readFileSync(failureLog, 'utf-8');
+    expect(contents.length).toBeGreaterThan(0);
+    expect(contents).toMatch(/--- shard \d+:/);
+    expect(contents).toContain('failing-on-purpose');
+  });
+
+  it('prints loud stderr banner with absolute failure-log path on failure', () => {
+    const r = runWrapper();
+    expect(r.code).not.toBe(0);
+    expect(r.stderr).toContain('TEST FAILURES');
+    // Banner includes the absolute path so users can `cat` it directly.
+    expect(r.stderr).toContain(join(TMPROOT, '.context', 'test-failures.log'));
+  });
+
+  it('clears .context/test-failures.log to empty when all shards pass', () => {
+    // Pre-seed a stale failure log to prove it gets cleared.
+    mkdirSync(join(TMPROOT, '.context'), { recursive: true });
+    writeFileSync(join(TMPROOT, '.context', 'test-failures.log'), 'STALE\n');
+    rmSync(join(TMPROOT, 'test', 'd-fail.test.ts'));
+    try {
+      const r = runWrapper();
+      expect(r.code).toBe(0);
+      const contents = readFileSync(join(TMPROOT, '.context', 'test-failures.log'), 'utf-8');
+      expect(contents).toBe('');
+    } finally {
+      const failing = `import { describe, it, expect } from 'bun:test';
+describe('failing-on-purpose', () => {
+  it('expects 1 to equal 2', () => { expect(1).toBe(2); });
+});`;
+      writeFileSync(join(TMPROOT, 'test', 'd-fail.test.ts'), failing);
+    }
+  });
+
+  it('writes per-shard summary lines to .context/test-summary.txt', () => {
+    runWrapper();
+    const summary = readFileSync(join(TMPROOT, '.context', 'test-summary.txt'), 'utf-8');
+    // Format: `shard 1/2: pass=N fail=N skip=N rc=N`
+    expect(summary).toMatch(/shard 1\/2: pass=\d+ fail=\d+ skip=\d+ rc=\d+/);
+    expect(summary).toMatch(/shard 2\/2: pass=\d+ fail=\d+ skip=\d+ rc=\d+/);
+  });
+});
diff --git a/test/scripts/run-unit-shard.test.ts b/test/scripts/run-unit-shard.test.ts
new file mode 100644
index 000000000..1b3a08aa5
--- /dev/null
+++ b/test/scripts/run-unit-shard.test.ts
@@ -0,0 +1,56 @@
+/**
+ * Regression test (b): scripts/run-unit-shard.sh exclusion symmetry.
+ *
+ * Pins the contract that the local fast-loop unit-shard script:
+ *   1. EXCLUDES *.slow.test.ts (those run via scripts/run-slow-tests.sh).
+ *   2. EXCLUDES *.serial.test.ts (those run via scripts/run-serial-tests.sh
+ *      after the parallel pass).
+ *   3. Includes plain *.test.ts files (the fast-loop unit set).
+ *
+ * Without this guard, a future refactor that drops one of the `-not -name`
+ * clauses from the find expression would cause slow OR serial files to
+ * run inside the parallel pass — silently undoing the quarantine and
+ * re-introducing the contention flakes that motivated v0.26.4.
+ */
+
+import { describe, it, expect } from 'bun:test';
+import { execFileSync } from 'child_process';
+import { resolve } from 'path';
+
+const REPO_ROOT = resolve(import.meta.dir, '..', '..');
+const SHARD_SH = resolve(REPO_ROOT, 'scripts/run-unit-shard.sh');
+
+function dryRunList(): string[] {
+  const out = execFileSync('bash', [SHARD_SH, '--dry-run-list'], {
+    cwd: REPO_ROOT,
+    encoding: 'utf-8',
+    env: { ...process.env, SHARD: '' },
+  });
+  return out.split('\n').map(s => s.trim()).filter(Boolean);
+}
+
+describe('run-unit-shard.sh exclusion symmetry', () => {
+  it('lists at least one plain *.test.ts file', () => {
+    const files = dryRunList();
+    expect(files.length).toBeGreaterThan(0);
+    expect(files.some(f => /\.test\.ts$/.test(f) && !/\.(slow|serial)\.test\.ts$/.test(f))).toBe(true);
+  });
+
+  it('excludes every *.slow.test.ts file', () => {
+    const files = dryRunList();
+    const leaks = files.filter(f => /\.slow\.test\.ts$/.test(f));
+    expect(leaks).toEqual([]);
+  });
+
+  it('excludes every *.serial.test.ts file', () => {
+    const files = dryRunList();
+    const leaks = files.filter(f => /\.serial\.test\.ts$/.test(f));
+    expect(leaks).toEqual([]);
+  });
+
+  it('excludes the test/e2e/ subtree', () => {
+    const files = dryRunList();
+    const leaks = files.filter(f => f.startsWith('test/e2e/'));
+    expect(leaks).toEqual([]);
+  });
+});
diff --git a/test/scripts/serial-files.test.ts b/test/scripts/serial-files.test.ts
new file mode 100644
index 000000000..1d5ad56e3
--- /dev/null
+++ b/test/scripts/serial-files.test.ts
@@ -0,0 +1,70 @@
+/**
+ * Regression test (e): scripts/run-serial-tests.sh discovery + concurrency=1.
+ *
+ * Pins the contract that:
+ *   1. Every *.serial.test.ts file IS picked up by run-serial-tests.sh.
+ *   2. The script invokes `bun test` with `--max-concurrency=1` (the
+ *      serial-pass guarantee — quarantined files MUST NOT run intra-file
+ *      concurrent or they reintroduce the contention flakes that
+ *      motivated quarantining them).
+ *   3. The serial set is DISJOINT from run-unit-shard.sh's set (a file
+ *      cannot run in both passes; the unit-shard test pins one half,
+ *      this test pins the other).
+ *
+ * Without these guards, a refactor of either runner could silently let
+ * .serial files run alongside the parallel pass (= contention flakes)
+ * or be skipped entirely (= no test coverage at all).
+ */
+
+import { describe, it, expect } from 'bun:test';
+import { execFileSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+const REPO_ROOT = resolve(import.meta.dir, '..', '..');
+const SERIAL_SH = resolve(REPO_ROOT, 'scripts/run-serial-tests.sh');
+const SHARD_SH = resolve(REPO_ROOT, 'scripts/run-unit-shard.sh');
+
+function dryRunList(scriptPath: string): string[] {
+  const out = execFileSync('bash', [scriptPath, '--dry-run-list'], {
+    cwd: REPO_ROOT,
+    encoding: 'utf-8',
+    env: { ...process.env, SHARD: '' },
+  });
+  return out.split('\n').map(s => s.trim()).filter(Boolean);
+}
+
+describe('run-serial-tests.sh contract', () => {
+  it('discovers every *.serial.test.ts file', () => {
+    const serialFiles = dryRunList(SERIAL_SH);
+    // Every file the script lists must end in .serial.test.ts.
+    const offenders = serialFiles.filter(f => !/\.serial\.test\.ts$/.test(f));
+    expect(offenders).toEqual([]);
+
+    // Every checked-in *.serial.test.ts must be listed by the script.
+    // We cross-check by globbing through git ls-files (deterministic; doesn't
+    // depend on filesystem state during the test run).
+    const tracked = execFileSync('git', ['ls-files', 'test'], {
+      cwd: REPO_ROOT,
+      encoding: 'utf-8',
+    })
+      .split('\n')
+      .map(s => s.trim())
+      .filter(f => /\.serial\.test\.ts$/.test(f) && !f.startsWith('test/e2e/'));
+    for (const f of tracked) {
+      expect(serialFiles).toContain(f);
+    }
+  });
+
+  it('passes --max-concurrency=1 to bun test', () => {
+    const src = readFileSync(SERIAL_SH, 'utf-8');
+    expect(src).toMatch(/bun test\s+--max-concurrency=1/);
+  });
+
+  it('disjoint from run-unit-shard.sh (a file is never in both passes)', () => {
+    const serialFiles = new Set(dryRunList(SERIAL_SH));
+    const unitFiles = new Set(dryRunList(SHARD_SH));
+    const overlap = [...serialFiles].filter(f => unitFiles.has(f));
+    expect(overlap).toEqual([]);
+  });
+});