v0.31.3 fix: stdio MCP graceful cleanup + engine-aware auth/admin SQL (closes #413, #446)

[garrytan]

Summary

Two community PRs landed as one focused PR with two atomic bisect-friendly commits:

stdio MCP graceful cleanup (#676 successor): stdio EOF, SIGTERM, SIGINT, SIGHUP, parent-process death (every reparent case — PID 1, launchd subreaper, systemd, tmux, parent shell with PR_SET_CHILD_SUBREAPER), and an optional --stdio-idle-timeout all funnel into one idempotent shutdown that releases the engine and the PGLite write lock within 5 seconds. ps-unavailable stripped containers log loudly and skip the watchdog rather than silently fall back to process.ppid (Bun caches it). Closes #413, #446. Supersedes #591. Credit @Aragorn2046, @seungsu-kr.

Engine-aware auth/admin SQL (#681 successor): gbrain auth, OAuth 2.1 (register-client / token mint / revoke), the admin SPA, file uploads, and the legacy bearer-auth HTTP transport all run through the active engine via a deliberately-narrow SqlQuery adapter (src/core/sql-query.ts) calling engine.executeRaw. JSONB writes route through a separate executeRawJsonb(engine, sql, scalarParams, jsonbParams) helper that emits explicit $N::jsonb casts. Migration v46 normalizes pre-v0.31.3 string-shaped mcp_request_log.params rows up to real JSONB objects. Credit codex-bot.

Decision log: ~/.claude/plans/system-instruction-you-are-working-peppy-moore.md (5 eng-review decisions + 8 codex outside-voice decisions; 3 of the eng-review decisions reversed by codex including the SqlQuery.json() extension which was rejected in favor of the separate executeRawJsonb helper).

Test Coverage

COMMIT 1 — stdio cleanup (src/commands/serve.ts +270 / -4)
[+] installStdioLifecycle()
  ├── [★★★] SIGTERM/SIGINT/SIGHUP — 3 cases
  ├── [★★★] stdin 'end' / 'close' — 2 cases
  ├── [★★★] TTY stdin skips watcher — 1 case
  ├── [★★★] idempotent shutdown under race — 1 case
  ├── [★★★] 5s cleanup deadline when disconnect() rejects — 1 case
  ├── [★★★] watchdog reparent-to-1 (init) — 1 case
  ├── [★★★] watchdog reparent-to-PID-N (subreaper) — 1 case (NEW per codex #3)
  ├── [★★★] watchdog NOT installed when initial ppid = 1 — 1 case
  ├── [★★★] ps-unavailable startup probe disables watchdog + loud log — 1 case (NEW per codex #4)
  ├── [★★★] watchdog tick with unchanged ppid is no-op — 1 case
  └── [★★★] --stdio-idle-timeout (9 cases incl. strict parse rejects)

COMMIT 2 — SqlQuery routing
[+] src/core/sql-query.ts (NEW)
  ├── [★★★] scalar binds round-trip — 1 case
  ├── [★★★] rejects array/promise/object — 1 case
  ├── [★★★] executeRawJsonb({k:v}) round-trip with jsonb_typeof = 'object' — 1 case
  ├── [★★★] takes-holders v0.12.0 double-encode regression guard — 1 case
  ├── [★★★] null JSONB handling — 1 case
  ├── [★★★] mixed scalar+jsonb call shape — 1 case
  └── [★★★] non-scalar in scalarParams rejected — 1 case
[+] test/e2e/auth-takes-holders-pglite.test.ts (NEW, in-memory PGLite, no DATABASE_URL gate)
  ├── [★★★] access_tokens.permissions create + read returns object — 1 case
  ├── [★★★] access_tokens.permissions UPDATE preserves shape — 1 case
  ├── [★★★] mcp_request_log.params object writes round-trip — 1 case
  ├── [★★★] mcp_request_log.params NULL writes — 1 case
  ├── [★★★] migration v46 normalizer lifts string-shaped rows — 1 case
  └── [★★★] migration v46 idempotent (second run no-op) — 1 case
[+] test/config-env.test.ts (NEW, withEnv() helper per CLAUDE.md R1)
  └── [★★★] DATABASE_URL/GBRAIN_DATABASE_URL precedence — 5 cases
[+] test/http-transport.test.ts (mock updated to intercept engine.executeRaw)
  └── [★★★] all 24 cases pass post-migration

COVERAGE: 64 tested paths across 5 test files (PGLite + Postgres parity)
QUALITY: ★★★ 64/64 — all behavioral, none smoke
GAPS: 0

Tests: 4786 pass / 1 pre-existing fail (brain-registry.serial, reproduces on master pre-branch — not introduced by this PR).

Pre-Landing Review

Already ran via /plan-eng-review (5 issues found, all addressed) + /codex outside-voice consult-mode plan review (10 findings, 9 closed by re-design + 1 wording fix). Both reviews logged CLEAR before commits landed. Implementation matches the reviewed plan; no new findings during the merge.

Plan Completion

11/11 plan tasks DONE — see commit messages and ~/.claude/plans/system-instruction-you-are-working-peppy-moore.md. Decisions D1, D2, D5 were reversed by Codex's outside-voice review (recorded in the plan's decision log) before implementation started, so the shipped code matches the post-review consensus, not the original plan.

TODOS

No TODOS.md items completed by this PR. The PR closes GitHub issues #413 and #446 (which aren't tracked in TODOS.md).

Documentation

CLAUDE.md updated with v0.31.3 annotations in the Key Files section: new entries for src/core/sql-query.ts and src/commands/serve.ts, amended notes on auth.ts, serve-http.ts, and migrate.ts (v46). README, CHANGELOG, TODOS, and VERSION required no changes (CHANGELOG already shipped via the merge commit).

Test plan

• bun run typecheck — clean
• bash scripts/check-jsonb-pattern.sh — clean
• bash scripts/check-test-isolation.sh — clean (299 non-serial unit files)
• bun test test/serve-stdio-lifecycle.test.ts — 22/22 pass
• bun test test/sql-query.test.ts — 7/7 pass
• bun test test/config-env.test.ts — 5/5 pass
• bun test test/http-transport.test.ts — 24/24 pass (mock updated to intercept engine.executeRaw)
• bun test test/e2e/auth-takes-holders-pglite.test.ts — 6/6 pass
• bun run test (full unit fast loop) — 4786 pass / 1 pre-existing fail
• bun run verify — typecheck + 4 pre-checks all clean
• Bisect smoke: git bisect start HEAD~3; git bisect bad HEAD; git bisect good HEAD~3 — verified before merge that commit 1 (stdio) typechecks + tests pass independently
• Real-Postgres E2E (bun run test:e2e) — not run locally; CI will run on PR

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith with what you need.}

• Let Codesmith autofix CI failures and bot reviews