admin/gbrain
1
0
Fork 0
mirror of https://github.com/garrytan/gbrain.git synced 2026-07-30 11:22:34 +00:00
Code Issues Packages Projects Releases Wiki Activity
371 Commits 567 Branches 1 Tag
6abab9d58438a79852e3f0715dfd909fb2b25bb7
Commit Graph
2 Commits
Author SHA1 Message Date
Garry TanGitHubClaude Fable 5
 		4ee530f3c5 v0.42.42.0 fix(cli): bounded teardown + explicit exit — kill the 10s force-exit tax on txn-mode poolers (#2084) (#2141) 
* feat(core): finishCliTeardown + flushThenExit — bounded teardown, owned exit verdict (#2084)

cli-force-exit.ts becomes the single owner of one-shot CLI exit + teardown:
- finishCliTeardown: bounded sink drain -> bounded disconnect under a backstop
  whose deadline is COMPUTED from the bounds it guards (floor 10s;
  GBRAIN_TEARDOWN_DEADLINE_MS env override). Arms at teardown start, never
  before the op handler.
- flushThenExit: stdio write-fence (unref'd guard, EPIPE-safe) + REF'D
  aliveness grace for non-TTY stdio — Bun only delivers queued pipe writes
  while the process is alive (no flush API reaches the native queue).
- setCliExitVerdict/currentExitCode: the exit verdict lives in a gbrain-owned
  channel, never read back from process.exitCode (PGLite's Emscripten runtime
  scribbles its own status there mid-run).
- background-work.ts exports backgroundWorkSinkCount() for the deadline formula.

Unit tests + a spawned-Bun harness proving byte-complete piped output.

* fix(cli): route all nine disconnect sites through finishCliTeardown; one exit seam (#2084)

Deletes the pre-handler 10s force-exit timer (it measured handler + teardown
combined: PgBouncer txn-mode deployments paid a flat 10s banner tax on every
query, and any >10s op was killed mid-run with exit 0 and truncated output).
Sweeps op-dispatch, CLI_ONLY fall-through, search dashboard, read-only timeout
path, dream, doctor x3 (fixing a pre-existing pool leak when DB checks throw),
and ze-switch. The ONE process exit lives in main().then/catch via
flushThenExit(currentExitCode()), gated by shouldForceExitAfterMain().
Exit-code writers (op-dispatch catch, reindex, transcripts, brainstorm,
autopilot, frontmatter) now set the verdict through setCliExitVerdict.

* fix(pglite): contain Emscripten's process.exitCode writes at PGlite.create (#2084)

PGLite's WASM runtime writes its own status into process.exitCode (99 at
create; in-memory brains run initdb whose status lands on a later tick; the
exit status at close) — on PGLite every error exit was silently clobbered.
preservingProcessExitCode wraps create() to keep the global tidy; db.close()
stays unwrapped (its 0-write is baseline behavior test runners depend on).
The CLI verdict itself is immune: it lives in the owned channel.

* test: e2e + structural pins for the #2084 teardown contract

E2E: failed op exits 1; every swept command spawned (brain-copy isolation for
mutators, no-network); slow-handler regression via the deadline env knob;
piped --json parses complete; teardown banner absent on every happy path;
daemon survival untouched. Structural: no bare awaited engine disconnects in
cli.ts; DISCONNECT_HARD_DEADLINE_MS gone; >=9 helper call sites; verdict
channel + create-wrap pins.

* test: fix R1 env-isolation violations in retrieval-reflex tests

Pre-existing on master: both files mutated GBRAIN_RETRIEVAL_REFLEX directly,
failing scripts/check-test-isolation.sh (bun run verify). Converted to the
canonical withEnv() pattern; the reflex describe's beforeEach also never
restored the flag, leaking it across the shard.

* docs: KEY_FILES entries for the teardown contract; close + file TODOS (#2084)

KEY_FILES.md: current-state entry for cli-force-exit.ts (helper + central exit
seam pair, verdict channel, cli.ts-scoped claim); background-work.ts and
pglite-engine.ts entries updated. TODOS.md: the drain-before-owner-disconnect
P3 (filed from #1972) is done by this wave; files the trigger-gated
GBRAIN_COMMAND_DEADLINE_MS follow-up (eng-review D2/D14).

* fix: pre-landing review fixes (#2084)

Review army (testing/maintainability/security/performance, 0 critical):
- drain defense-in-depth: a throwing drain warns and still disconnects
  (cannot escape a caller's finally or skip the engine teardown)
- behavioral tests for preservingProcessExitCode (connect pins 0; create-throw
  restores the pre-call verdict)
- D9 widening test (live-registry sink count feeds the deadline formula),
  env 0/negative boundary cases, verdict mirror-write assertion
- stale comments: header diagram backstop line, structural-test 'both
  lifecycle calls' contradiction, KEY_FILES 10s-force-exit clauses, e2e D11
  falsification story corrected
- named the formula's pool-end literals

* fix: adversarial-review hardening — daemon-safe command resolution, flush knob, ref'd backstop (#2084)

Cross-model adversarial review (Claude subagent + Codex, both P1'd it):
- shouldForceExitAfterMain now resolves the command through parseGlobalFlags —
  the old first-non-dash heuristic read `gbrain --timeout 30s serve` as
  command "30s" and the new exit seam would have killed the daemon ~250ms
  after boot with exit 0 (unit-pinned)
- GBRAIN_FLUSH_GRACE_MS env override for the non-TTY aliveness grace (batch
  consumers piping large payloads to slow readers can raise it; agent loops
  can lower it)
- backstop timer is now REF'D: a hung teardown on an otherwise-empty event
  loop previously exited naturally — skipping the flush and surfacing
  PGLite's scribbled process.exitCode
- flushThenExit: real process.exit latched once per process
- doctor-site comment corrected; in-command process.exit teardown-bypass
  class (pre-existing) filed as a P2 TODO

* chore: bump version and changelog (v0.42.42.0)

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

* test: move #2084 exitCode-containment lifecycle tests to the serial quarantine (R3)

* docs: update project documentation for v0.42.42.0

- docs/TESTING.md: replace the stale 4-file serial-quarantine enumeration
  with a current-state description (the quarantine is glob-discovered, now
  several dozen files incl. the #2084 exitCode-containment suite); add unit
  inventory entries for test/cli-finish-teardown.test.ts and
  test/flush-then-exit-harness.test.ts.
- docs/architecture/KEY_FILES.md: rephrase the pglite-engine exitCode
  containment note to current-state wording (clears the
  check-key-files-current-state prose-history warning).

llms bundles regenerated (byte-identical: both docs are link-only).

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

* docs: apply cross-model doc-review findings for v0.42.42.0

Codex review of docs-vs-shipped-code found 9 gaps; all verified against
the code before fixing:

- CHANGELOG.md (0.42.42.0 entry, precision narrowing only — no entries
  touched): "every CLI exit path" -> "every cli.ts disconnect site";
  "on every path" -> "on every routed exit path"; dream/doctor/ze-switch
  claim scoped to dispatcher teardown (command-internal process.exit
  sites are tracked in TODOS as the open P2).
- docs/architecture/KEY_FILES.md: the teardown backstop is REF'D, not
  unref'd (matches the F3 adversarial-review decision in the code).
- src/core/cli-force-exit.ts: header diagram comment had the same stale
  unref'd claim + `process.exitCode ?? 0`; now matches the implementation
  (ref'd timer, `currentExitCode()`). Comment-only change.
- docs/TESTING.md: verify is the 30-check parallel battery via
  run-verify-parallel.sh (was described as 4 checks); CI is 10 weighted
  LPT shards + dedicated verify/serial/slow jobs (was "4-way FNV on
  shard 1"); test:serial runs one bun process per file (not
  --max-concurrency=1); dead "cap: 10" line rewritten as debt guidance;
  inventory entries added for test/cli-should-force-exit.test.ts and
  test/e2e/pglite-cli-exit.serial.test.ts.

bun run verify green (30/30); #2084 test files green; llms bundles
regenerated (byte-identical — reference docs are link-only).

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

* fix: route v0.42.41.0's raw exitCode writers through the verdict channel; reconcile merged structural pins (#2084)

CI fallout from merging the v0.42.41.0 triage wave into the #2084 exit-seam
design — both waves fixed the same timer-placement bug independently:

- doctor.ts + extract.ts set failure exit codes via raw `process.exitCode =`
  writes (v0.42.41.0's process.exit -> exitCode conversion); the #2084 exit
  seam reads only the gbrain-owned verdict channel, so doctor FAILs exited 0
  (Tier 1 RLS e2e + half-migrated-Minions tests). Converted to
  setCliExitVerdict, same as the wallclock-124 site in the merge commit.
- cli-force-exit-teardown-arming.test.ts pinned v0.42.41.0's inline
  finally-armed timer, which the merge replaced with finishCliTeardown;
  rewritten to pin the merged invariant (no pre-try arming in cli.ts; the
  backstop arms inside the helper before the drain).
- eval-capture drain timing bound 1s -> 2s: flaked at 1023ms under CI shard
  load after the new test files shifted LPT shard packing (13x budget slack
  still proves bounded-not-hung).

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
 2026-06-12 07:28:13 -07:00
Garry TanGitHubClaude Opus 4.7Park Je HoonMatt Dean
 		27b0e14af7 v0.41.8.0 fix(pglite): search/query/get exit cleanly + #1340 hint + #1342 breadcrumbs (#1405) 
* fix(pglite): drain fire-and-forget last_retrieved_at writes before disconnect

Closes the structural bug class behind #1247, #1269, #1290: PGLite CLI
search/query/get_page commands printed results then hung at ~95-98% CPU
until SIGKILL. Root cause: bumpLastRetrievedAt's IIFE races
engine.disconnect() — PGLite's WASM runtime keeps Bun's event loop alive
while the dangling UPDATE settles.

Mirrors the existing awaitPendingSearchCacheWrites precedent landed in
v0.36.1.x for #1090. Tracks every IIFE promise in a module-scoped Set,
exposes awaitPendingLastRetrievedWrites(timeoutMs) that resolves once
all settle. Bounded with a 5s default timeout via Promise.race so a
future fire-and-forget that hangs forever can't recreate the bug class
at this layer — instead, the drain stderr-warns with a pending count
and returns timeout outcome so the caller can decide its fallback.

Test coverage: 6 unit cases covering empty drain, single + multi-pending
settle, throw-in-IIFE still settles, permanently-pending hits timeout
within bound, empty pageIds does not track.

This commit ships the helper + tracking + tests with NO consumer.
The cli.ts wiring lands in a follow-up commit (atomic bisect units).

Co-Authored-By: Park Je Hoon <jehoon@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(pglite): snapshot+early-null disconnect + try/finally lock-leak guard

Refactor PGLiteEngine.disconnect() with two structural fixes:

(1) Snapshot + early-null pattern: capture db/lock refs and null the
    instance fields BEFORE any await. A concurrent connect() can no
    longer observe `_db` pointing at a handle that's mid-close. This
    is PR #1337's load-bearing contribution that we DID take.

(2) Wrap close + release in try/finally. Without this guard, a thrown
    db.close() would leak the file lock and wedge every next gbrain
    invocation on the stale lock. Codex outside-voice review (eng
    review finding #7) caught this gap when reviewing the snapshot
    refactor.

KEEP the original close-then-release order. PR #1337's diff swapped
this to release-then-close, which we explicitly REJECTED — releasing
the lock before close lets a sibling process try to connect to a
still-closing brain. The new lifecycle test file pins this ordering
so a future maintainer reading PR #1337's diff cannot accidentally
flip it.

Test coverage in test/pglite-engine-disconnect.serial.test.ts: 5
cases — close-before-release ordering, early-null observable inside
close, lock-still-releases on close-throw, double-disconnect
idempotency, reconnect-after-disconnect clean state. `.serial`
because each test creates a fresh PGLite engine (WASM cold-start
cost) — running in parallel shards would starve other tests.

Existing test/pglite-engine.test.ts: 100/100 still green.

Co-Authored-By: Matt Dean <matt-dean-git@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(pglite): classify WASM init errors so #1340 gets the right hint (#1340)

Closes the user-facing half of #1340: on macOS 12.7.6 + Bun 1.3.14, the
PGLite connect() catch block hardcoded the macOS 26.3 hint (#223). The
actual root cause for #1340 is Bun's vfs: `/$$bunfs/root` is read-only
on older macOS, so PGLite cannot extract its pglite.data WASM payload.

Adds two exported helpers in pglite-engine.ts:

  classifyPgliteInitError(message): 'bunfs' | 'macos-26-3' | 'unknown'
  buildPgliteInitErrorMessage(verdict, original): string

Connect catch block now routes the hint by verdict. The bunfs hint
names `bun upgrade` + Node fallback. The macOS 26.3 hint keeps the
existing #223 link. Unknown falls through to a generic doctor + #223
fallback.

Per Codex eng-review finding #9, the bunfs regex is tightened to match
either the literal `$$bunfs` marker OR ENOENT+pglite.data
co-occurrence — NOT generic `pglite.data` substring (would fire on
unrelated errors). Negative test pinned.

Root fix is upstream Bun; this PR just stops misclassifying the
failure class so support traffic doesn't conflate two unrelated bugs.

Test coverage: 12 pure-function unit cases including the #1340
reporter's exact error string round-trip, the negative case Codex
caught, and all three verdicts × all three message contents.

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

* fix(cli): await last-retrieved drain + narrow timeout-only force-exit (#1247, #1269, #1290)

Wires the v0.40.10.0 drain helper into cli.ts and adds the IRON-RULE
behavioral regression test for the search-hang class. The drain is
called unconditionally for every op (not per-op-name gated — that was
the original PR #1259 mistake that left search and get_page exposed).

The narrow force-exit synthesis (decision D7 from the eng review,
informed by Codex outside-voice findings #1+#2+#8): when the drain
returns outcome:'timeout', AFTER engine.disconnect() resolves AND
the command is NOT a daemon, fire process.exit(0). The drain helper
already stderr-warned with the pending count, so the diagnostic
signal is preserved. Without this guard, a hung underlying promise
could still keep Bun's event loop alive past disconnect.

CRITICALLY narrower than PR #1337's blanket force-exit: the timeout
path is the only trigger. In the common case (drain settles cleanly
under 5s), no force-exit fires and the behavioral subprocess test
still catches future regressions. The shouldForceExitAfterMain guard
excludes 'serve' so the stdio + HTTP daemons stay alive past main().

e2e/pglite-cli-exit.serial.test.ts (NEW, IRON RULE):
  - gbrain search "foxtrot" → exits 0 within 15s
  - gbrain get alpha → exits 0 within 15s with foxtrot in stdout
  - gbrain query "foxtrot" --no-expand → exits within 15s (no-API-key
    graceful)
  - gbrain serve --http → stays alive 3+ seconds (daemon-survival
    regression guard)

fix-wave-structural.test.ts:
  - import assertion for awaitPendingLastRetrievedWrites
  - last-retrieved.ts exports + Set tracking + Promise.race + timeout
  - BEHAVIORAL positioning assertion: drain `await` appears textually
    BEFORE engine.disconnect `await` in the op-dispatch local-engine
    path. Survives variable-rename refactors; catches any new
    disconnect path that bypasses the drain.
  - shouldForceExitAfterMain excludes 'serve' AND the gate is
    conditioned on drainResult.outcome==='timeout'

Per D8 (Codex finding #5), explicitly do NOT add a drift-guard
counting bumpLastRetrievedAt callers — would block harmless
refactors and miss aliases.

Co-Authored-By: Park Je Hoon <jehoon@users.noreply.github.com>
Co-Authored-By: Matt Dean <matt-dean-git@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(sync): add phase breadcrumbs to performSyncInner for #1342 triage

The #1342 reporter saw ZERO stderr output before their PGLite sync
hang, which made the bug impossible to triage from a community report
alone. Mirrors the pre-existing `[gbrain phase] sync.git_pull start/done`
pattern at the major pre-pull phase boundaries so the next #1342-shaped
report names WHICH phase spun.

Four new breadcrumbs at:
  - sync.resolve_repo (top of performSyncInner)
  - sync.load_active_pack (before the v0.39 T1.5 pack load)
  - sync.validate_repo_state (only when opts.sourceId is set —
    the re-clone branch)
  - sync.detect_head (before the isDetachedHead probe)

No behavior change — pure stderr instrumentation. Doesn't fix #1342
(which still needs investigation per the TODOS entry filed in this
wave), but converts "hung with no output" into actionable diagnostic
data the next time the bug shape is reported.

Per D9 in the eng review + Codex outside-voice finding #14.

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

* docs: annotate v0.40.10.0 PGLite hang wave in CLAUDE.md + regen llms

Key Files entries updated:

- src/core/pglite-engine.ts: documents the v0.40.10.0 disconnect
  refactor (snapshot+early-null + try/finally lock-leak guard, KEEPS
  close-then-release order), and the new classifyPgliteInitError /
  buildPgliteInitErrorMessage helpers for #1340 hint routing. Pins
  PR #1337's accepted-but-narrowed contribution and the rejected
  release-then-close ordering swap.

- src/core/last-retrieved.ts (within the brainstorm entry): documents
  the new awaitPendingLastRetrievedWrites drain, the Set tracking
  pattern, the 5s bounded timeout, the cli.ts narrow timeout-only
  force-exit synthesis with the serve-daemon guard, and the three
  community-validated reports (#1247/#1269/#1290) the fix closes.
  Credits PR #1259 (drain pattern) and PR #1337 (snapshot pattern +
  force-exit guard idea).

Regenerated llms.txt + llms-full.txt — build-llms.test.ts gates the
drift, all 7 cases green.

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

* docs(todos): file v0.40.10.0 PGLite hang follow-ups

Three deferred items from the v0.40.10.0 fix wave:

1. #1342 sync-hang investigation. Single-reporter, JS-tight-loop
   shape, needs reproducer before any fix. Documents the ruled-out
   hypotheses (lock-refresh heartbeat, v91 trigger, while-true loops)
   and three concrete diagnostic next steps. The v0.40.10.0 sync
   phase breadcrumbs make the next report actionable.

2. awaitPendingSearchCacheWrites timeout-symmetry retrofit. The #1090
   drain shipped without a timeout; the v0.40.10.0 #1247 drain ships
   with one. Apply the same Promise.race + stderr warn pattern for
   symmetry.

3. Drain-helper extraction. Per D4 in the eng review: two surfaces is
   the threshold for noticing, three for extracting. Pair with the
   symmetry retrofit above as one focused refactor when a third
   fire-and-forget surface appears.

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

* v0.40.10.0 fix(pglite): search/query/get exit cleanly + #1340 hint + #1342 breadcrumbs

Closes #1247, #1269, #1290 (PGLite CLI search/query/get hang at ~95-98%
CPU after printing results — three community-validated reports). Also
fixes #1340 (WASM init misroutes to macOS 26.3 hint when real cause is
Bun vfs read-only mount) and adds diagnostic phase breadcrumbs for the
single-reporter #1342 sync-hang investigation.

Core fix: track every fire-and-forget bumpLastRetrievedAt IIFE in a
module-scoped Set; cli.ts awaits the drain before engine.disconnect()
in the op-dispatch finally block; narrow process.exit(0) fires ONLY
when the drain times out AND the command isn't a daemon. Snapshot+
early-null disconnect pattern + try/finally lock-leak guard close the
partial-state race PR #1337 originally surfaced.

Co-Authored-By: Park Je Hoon <jehoon@users.noreply.github.com>
Co-Authored-By: Matt Dean <matt-dean-git@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: extract shouldForceExitAfterMain to its own module + add unit cases

Gap-audit follow-up: cli.ts is a script entrypoint (top-level main()
side effect), so importing it from a test fires the help output as a
side effect. Move shouldForceExitAfterMain into src/core/cli-force-exit.ts
so it can be unit-tested in isolation without the cli.ts script tail
running.

Adds test/cli-should-force-exit.test.ts (9 cases): bare serve, serve
with flags after, global flags BEFORE the command (the load-bearing
case for `gbrain --quiet serve`), op commands return true, non-daemon
CLI commands return true, empty argv defaults to true, flag-only argv,
default-arg fallback to process.argv.slice(2), substring-match
avoidance (`serves` is NOT `serve` — strict equality via Set, not
startsWith/includes).

The daemon command set is now an explicit ReadonlySet — future
daemons (a hypothetical `gbrain watch` or `gbrain daemon`) just add
their name to DAEMON_COMMANDS rather than chaining ||.

Updates fix-wave-structural.test.ts to look for the import + the
new DAEMON_COMMANDS shape.

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

* chore(version): rebase v0.40.10.0 → v0.41.6.0 (slot collision after v0.41.0.0+ landed)

origin/master moved from v0.40.8.1 → v0.41.0.0 while this wave was in
flight (PR #1367 minions cathedral). v0.41.1-v0.41.5 are claimed by
other in-flight branches, so v0.41.6.0 is the next available slot.

Bulk-renamed v0.40.10.0 → v0.41.6.0 across:
- VERSION + package.json (trio audit clean: 0.41.6.0 / 0.41.6.0 / 0.41.6.0)
- CHANGELOG.md (header + 3 prose references)
- CLAUDE.md (Key Files annotations)
- TODOS.md (follow-up entry header)
- src/cli.ts + src/core/cli-force-exit.ts + src/core/last-retrieved.ts
  + src/core/pglite-engine.ts + src/commands/sync.ts (inline comments)
- test/* (describe blocks + test file headers)
- llms-full.txt (regenerated via `bun run build:llms`)

bun.lock unchanged (version-only bump, no dep churn) per Codex #12.

Verify: 52/52 wave tests pass after rename, typecheck clean.

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

* test: quarantine seed-pglite to .serial.test.ts (parallel WASM cold-start flake)

The full-suite run during the v0.41.6.0 fix wave ship hit a 30s timeout
in test/seed-pglite.test.ts under heavy 4-shard parallel contention
(4972/4973 passed before SIGKILL). The test passes 11/11 in isolation.

Root cause: each test instantiates a fresh PGLiteEngine (5 instances
across the file, one per test) because each case writes to a different
mkdtemp-ed dbPath. Under parallel shard load, multiple shards each
cold-starting PGLite WASM simultaneously stretches the per-instance
init from ~5s to 30s+. The shared-engine pattern (canonical PGLite
block in CLAUDE.md R3+R4) doesn't apply here — different dbPaths
require different engines.

Fix per CLAUDE.md test-isolation quarantine rules: rename to
`.serial.test.ts` so the file runs in the post-parallel serial pass
with full WASM init capacity. Same pattern as
test/pglite-engine-disconnect.serial.test.ts (added in this wave) and
test/brain-registry.serial.test.ts (pre-existing).

Removes test/seed-pglite.test.ts from check-test-isolation.allowlist
since the .serial.test.ts rename auto-exempts it from the R3+R4 lint
(scan skips *.serial.test.ts). 641 non-serial unit files scanned,
lint clean.

Verify:
- bun test test/seed-pglite.serial.test.ts → 11/11 pass in 4.19s
- scripts/check-test-isolation.sh → OK
- bun run verify → all gates pass

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

* fix: pre-landing review fixes (C13 disconnect-hang, C1 set leak, C9 catch drain, M1 type drift)

Adversarial review + maintainability specialist surfaced four real
issues in the v0.41.8.0 wave. All four fixed in this commit; one
deferred to TODOS.md as a v0.41+ follow-up (unusual caller pattern).

**C13 [load-bearing, defense-in-depth for the wave's stated goal]:**
`await engine.disconnect()` inside the op-dispatch finally can ITSELF
hang on PGLite (db.close() racing OS-level FS state). When that
happens, the entire wave's force-exit guard never runs — we recreate
the original hang at a new layer. Fix: install an unref'd setTimeout
hard-exit fallback BEFORE entering the try/catch/finally. The timer
fires after DISCONNECT_HARD_DEADLINE_MS=10s with a stderr warn and
process.exit(0). unref ensures it doesn't keep the loop alive on a
healthy exit. Daemons (`serve`) are excluded by reusing the
shouldForceExitAfterMain guard.

**C9 [data freshness gap, narrow but real]:**
The drain ran ONLY in the success branch of try. If
`bumpLastRetrievedAt` fired (handler succeeded) but
`JSON.parse(JSON.stringify(...))` or `formatResult` then threw,
process.exit(1) killed the process and the in-flight UPDATE was
discarded. Fix: drain in the catch path too before process.exit(1)
(best-effort, bounded by the drain's own 5s timeout).

**C1 [daemon leak]:**
A timed-out IIFE used to stay in the pending-writes Set forever
because its `.finally` never fires. Long-lived `gbrain serve` would
accumulate references without bound across repeated timeouts. Fix:
explicitly `delete` the snapshot's tracked promises from the Set
after a timeout outcome. The IIFEs keep running (orphaned), but the
Set no longer leaks references. Pinned by a new unit test that
asserts the second drain after a timeout returns immediately with
empty pending count.

**M1 [silent type drift]:**
`cli.ts` duplicated the `{outcome, pending}` literal shape instead of
importing the `DrainOutcome` type that `last-retrieved.ts` exports
exactly for this purpose. Two-line fix: add `type DrainOutcome` to
the import and use it for `let drainResult`. Future changes to the
return shape now propagate through TypeScript.

**Deferred to TODOS.md (C6 — unusual caller pattern):**
Concurrent connect/disconnect on the same `PGLiteEngine` instance can
strand: disconnect snapshots+nulls the lock while connect is still
in-flight, leaving the resolved engine with no file lock held. Fix
requires an instance-level mutex; not worth the complexity for a
caller pattern that doesn't appear in production (single instance per
process, sequential lifecycle).

Also broadened `test/fix-wave-structural.test.ts` regex to accept
additional type-imports from `last-retrieved.ts` (e.g. the new
`type DrainOutcome` import that M1 added).

Test coverage: 53/53 wave tests pass (added C1-followup case to
last-retrieved.test.ts). The C1 fix is also pinned by tightening the
existing permanent-pending test's post-timeout assertion to expect
empty pending count rather than the prior (stale) "stays in set" note.

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

* docs: post-ship documentation sync for v0.41.8.0

Consolidate the duplicate 'take advantage of v0.41.8.0' sections in
the CHANGELOG entry into a single canonical block per the CLAUDE.md
template. The wave originally landed with both '### How to take
advantage' (line 13) and '### To take advantage' (line 57) as h3
headings. CLAUDE.md mandates one '## To take advantage of v[version]'
h2 block per release entry, with verify steps + an issue-filing
fallback for users hitting upgrade failures.

Promoted the second block to h2, added the issue-filing step, and
removed the redundant first block (the upgrade command is already
covered in the verify steps). Itemized changes section was unchanged.

llms.txt + llms-full.txt regenerated; structurally identical so no
content changes shipped.

* fix(test): find-experts-op queries schema dim instead of hardcoding 1536 (CI shard 1)

CI shard 1 failed on this branch with: \"expected 1280 dimensions, not 1536\"
from pgvector's CheckExpectedDim. Root cause: master's v0.36.0 changed
DEFAULT_EMBEDDING_DIMENSIONS from OpenAI's 1536d to ZeroEntropy's 1280d
(src/core/ai/defaults.ts:21). The test's basisEmbedding helper hardcoded
dim=1536, so beforeAll's upsertChunks failed when the schema column was
created at 1280d.

Latent on master: the weight-aware LPT bin-packing in
scripts/sharding.ts assigns files to shards deterministically based on
the COMPLETE file set. My branch adds 5 new test files, which shifted
find-experts-op.test.ts into shard 1. Master's shard 1 doesn't run this
file (it lands in a different shard there), so the bug never surfaced
in master's CI.

Fix: query the actual column dim via
SELECT atttypmod FROM pg_attribute after initSchema, then seed the
embedding at that width. This handles both paths (no-env CI → 1280;
env-configured local → 1536) without hardcoding either default.

Verify:
- bun test test/find-experts-op.test.ts → 11/11 pass with provider env
- env -i bun test test/find-experts-op.test.ts → 11/11 pass without
- bun run verify → all 21 parallel checks clean
- bun run typecheck → clean

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

* fix(lint): robust pure-bash allowlist match in check-test-isolation (CI verify)

CI verify failed on PR #1405 with check:test-isolation flagging
test/scripts/check-test-isolation.test.ts even though that file is
on line 22 of the allowlist (and has been since v0.26.7 as a permanent
exemption — its body contains process.env mutation fixtures that the
lint legitimately matches).

Could not reproduce locally on macOS bash 3.2 + BSD grep across any
locale (C, C.UTF-8, POSIX). Suspect a subtle interaction between the
prior `echo "$ALLOWLIST" | grep -qxF "$f"` form and one of:
Ubuntu 24.04's bash 5 set-e/pipefail semantics, GNU grep edge case on
the first-line entry, or `bun run` + GNU timeout subshell interaction.
Diagnostic value of chasing further is low — the fix is to drop the
grep+pipe form entirely.

Switch is_allowlisted() to pure-bash `case $'\n'"$ALLOWLIST"$'\n' in
*$'\n'"$f"$'\n'*) return 0 ;; esac` whole-line matching:
- Locale-free (no character-class interaction)
- Pipe-free (no pipefail / SIGPIPE / buffering)
- Subshell-free (no env or exit-code propagation gotchas)
- set-e-quirk-free (no left-side compound failure)
- ~100x faster (no fork+exec per call across 689 files)

Verified locally: lint OK (689 files), case-match returns true for the
allowlisted file and false for a non-allowlisted file. bun run verify
clean (21/21 parallel checks pass).

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

---------

Co-authored-by: Park Je Hoon <jehoon@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Matt Dean <matt-dean-git@users.noreply.github.com>
 2026-05-25 14:20:19 -07:00