Skip to content

v0.41.20.0 feat: gbrain status + doctor --scope=brain (fix wave 2: items #6 + #7)#1544

Merged
garrytan merged 6 commits into
masterfrom
garrytan/freetown-v1
May 27, 2026
Merged

v0.41.20.0 feat: gbrain status + doctor --scope=brain (fix wave 2: items #6 + #7)#1544
garrytan merged 6 commits into
masterfrom
garrytan/freetown-v1

Conversation

@garrytan

@garrytan garrytan commented May 27, 2026

Copy link
Copy Markdown
Owner

Summary

Two friction items, both about restoring signal-to-noise for the operator's "is this working?" question.

New gbrain status command — single-screen brain health dashboard. Per-source sync freshness, last full cycle vs last targeted run (TWO rows per the v0.36.4.0 health-aware autopilot reality), active locks, supervisor health, live queue depth (NO time-window — old stuck jobs are exactly what status surfaces), autopilot daemon liveness. Stable --json envelope (schema_version: 1). Exit codes: 0 = ok, 1 = snapshot failed, 2 = usage error. Thin-client mode routes Sync + Cycle through new admin-scope get_status_snapshot MCP op; local-only sections render "N/A on remote brain" honestly.

Doctor categorization fix — gbrain doctor no longer says your brain is broken when it's actually your skills folder. Every check gets a category: brain|skill|ops|meta tag from new src/core/doctor-categories.ts (76 checks audited including helper-function const name forms). DoctorReport adds brain_checks_score + category_scores additively (legacy health_score byte-identical for back-compat). --scope=brain flag SKIPS computation of the SKILL group entirely (resolver walk, skill_conformance, skill_brain_first, whoknows_health) — real skip per D9, not just output filter. Sub-second on brains with thousands of skills.

gbrain doctor --remediate deliberately UNCHANGED — codex's outside-voice review caught my pre-implementation that I was about to "fix" the wrong thing. Remediation already reads engine.getHealth().brain_score (the weighted 35/25/15/15/10 composite). Switching it would have replaced a weighted metric with a coarser category counter.

Test Coverage

7 new test files, all passing:

  • test/doctor-categories.test.ts — drift guard catches both inline name: 'foo' and helper const name = 'foo' forms (caught stub_guard_24h, nightly_quality_probe_health, conversation_facts_backlog, and the post-merge batch_retry_health from the Supavisor wave).
  • test/doctor-brain-checks-score.test.ts — back-compat byte-identity on health_score; new field math; renaming regression (asserts NO brain_health_score field ships).
  • test/doctor-scope-filter.test.ts — observable absence of SKILL checks under --scope=brain.
  • test/status-sections.test.ts — parseSectionFlag + exit-code policy.
  • test/get-status-snapshot-op.test.ts — op shape + admin-scope pins.
  • test/e2e/status-pglite.test.ts — full PGLite E2E with fake minion_jobs + supervisor audit. Dual cycle rows + result.report.totals read path pinned.
  • test/doctor-home-dir-in-worktree.test.ts — UPDATED to anchor on {"schema_version" envelope prefix (the pre-existing fragile parser broke once category_scores introduced a nested object).

bun run verify clean (28/28 checks). Doctor surface: 117 pass / 0 fail across the touched files.

Pre-Landing Review

Plan + reviews persisted at ~/.claude/plans/system-instruction-you-are-working-abstract-bengio.md. Walked through /plan-eng-review with 4 architecture decisions (D1-D4) + an outside-voice codex pass that caught 3 BLOCKERS + 5 MAJORS. The codex pass overturned two of my interactive decisions before any code was written:

  • D7 reverted D1 (--remediate already correctly reads BrainHealth.brain_score).
  • D8 renamed brain_health_score → brain_checks_score to avoid the two-disagreeing-brain-scores footgun.
  • D9 promoted scope filter from post-hoc tag to early-skip gates.

Plan Completion

All 9 plan tasks DONE. T9 (gbrain doctor --remediate change) explicitly reverted per D7 — the right answer, not a missed item.

TODOS

TODOS.md gains 5 new follow-up entries under ## v0.41.20.0 status + doctor-categories wave follow-ups (v0.42+):

  • V19-A: persistent cycle_runs table
  • V19-B: atoms_inserted / concepts_inserted in CycleReport.totals top-level
  • V19-C: check-registry refactor (option for future scope dimensions)
  • V19-D: cross-OS scheduler-probe for real "next tick" timestamp
  • V19-E: category-aware doctor exit codes

Documentation

CLAUDE.md not directly edited in this branch (the v0.41.20.0 entries live in CHANGELOG). llms.txt and llms-full.txt regenerated post-merge.

Test plan

  • bun run verify 28/28 green
  • bun run typecheck clean
  • Touched + neighbor doctor/status tests: 117 pass / 0 fail
  • Manual smoke: gbrain status against fresh PGLite tempdir (sync/cycle/locks/workers/queue/autopilot all render; --json + --section work)
  • Manual smoke: gbrain doctor --scope=brain against same tempdir (skips resolver walk; brain_checks_score + category_scores in JSON)

🤖 Generated with Claude Code

garrytan and others added 6 commits May 26, 2026 23:38
@garrytan @claude
feat(doctor): doctor-categories foundation — BRAIN/SKILL/OPS/META set…
0a3c780 
…s + drift guard

Categorizes every doctor check name into exactly one of four categories. Exported
constants + categorizeCheck(name) helper are the single source of truth for the
v0.41.20.0 brain_checks_score + category_scores + --scope=brain wave. Drift guard
test parses doctor.ts source for both inline {name: 'foo'} and helper
const name = 'foo' patterns; CI fires if any check name lacks a category.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@garrytan @claude
feat(doctor): brain_checks_score + category_scores + --scope=brain sk…
e6c557c 
…ip-computation

Extends Check with optional category and DoctorReport with brain_checks_score +
category_scores (additive — schema_version stays at 2; back-compat health_score
math byte-identical). buildChecks gains --scope=brain with explicit early-skip
gates around the SKILL check group (resolver_health + skill_conformance +
skill_brain_first + whoknows_health). Sub-second doctor on a brain with thousands
of skills. computeDoctorReport tags every check via categorizeCheck() at compute
time. Human output leads with the brain figure and renders the weighted
BrainHealth.brain_score alongside.

Test seam fix in test/doctor-home-dir-in-worktree.test.ts: the pre-existing
fragile JSON parser walked back from "checks" to find the envelope's outer
brace; v0.41.20.0's new nested category_scores object broke that heuristic.
Anchored on the canonical {"schema_version" envelope prefix instead.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@garrytan @claude
feat(status): gbrain status — single-screen brain health dashboard + …
14650b0 
…get_status_snapshot MCP op

NEW gbrain status command (src/commands/status.ts) composes 6 sections:
sync (per-source last_sync_at + staleness via buildSyncStatusReport),
cycle (TWO rows: last autopilot-cycle + last autopilot-* of any kind —
reflects v0.36.4.0 health-aware autopilot's targeted handler routing;
totals read from result.report.totals per the canonical handler shape),
locks (gbrain_cycle_locks active rows), workers (readSupervisorEvents +
summarizeCrashes), queue (LIVE counts NO time-window — old stuck jobs
are exactly what status surfaces), autopilot (PID liveness via kill -0).

Stable --json envelope (schema_version: 1). Exit codes 0=ok / 1=snapshot
failed / 2=usage. --section filter.

Thin-client mode routes Sync + Cycle through NEW get_status_snapshot MCP
op (admin scope, NOT localOnly; payload deliberately omits Locks /
Workers / Queue / Autopilot so feature creep can't quietly widen the
admin-scoped data exposure). Local-only sections render "local-only —
N/A on remote brain" honestly instead of pretending the local install's
empty state is the remote brain's.

CLI dispatch: pre-engine-bind branch for thin-client (no PGLite needed)
+ engine-connected dispatch case for local mode. CLI-only architecture
per codex MAJOR-4 (status owns its own thin-client branch inside
runStatus, not routed through op dispatch).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@garrytan @claude
chore: bump version to v0.41.20.0 + CHANGELOG + TODOS + llms regen
87579da 
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@garrytan
Merge remote-tracking branch 'origin/master' into garrytan/gbrain-sta…
895bf2a 
…tus-doctor-scope

# Conflicts:
#	CHANGELOG.md
#	VERSION
#	package.json
@garrytan @claude
fix(doctor-categories): categorize batch_retry_health from v0.41.19.0…
7ce1b79 
… Supavisor wave

The drift guard correctly caught a new check introduced by master's v0.41.19.0
Supavisor Retry Cathedral (PR #1537). batch_retry_health surfaces batch-write
retry events from the new src/core/audit/batch-retry-audit.ts module — OPS
category (infrastructure liveness).

This is exactly why the drift guard exists: any future check added to doctor.ts
without a category entry fails CI immediately instead of silently degrading
to 'meta'.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@garrytan garrytan merged commit a74e5d9 into master May 27, 2026
20 checks passed
garrytan added a commit that referenced this pull request May 27, 2026
@garrytan
Merge branch 'master' into garrytan/type-taxonomy-unification
92ad12f 
Resolve VERSION, package.json, CHANGELOG conflicts. v0.41.22.0 stays
on top (higher than master's v0.41.20.0); master's v0.41.20.0 entry
preserved below in CHANGELOG order. Brought in master's gbrain status
+ doctor --scope=brain (PR #1544) and the v0.41.19.0 Supavisor Retry
Cathedral (PR #1537) cleanly via auto-merge.

Typecheck clean. bun run verify: 28/28 checks pass.
mgunnin added a commit to mgunnin/gbrain that referenced this pull request May 28, 2026
@mgunnin
Merge remote-tracking branch 'upstream/master'
6404926 
* upstream/master:
  v0.41.26.1 fix: lock-renewal cathedral — closes ~39 worker crashes/day (supersedes garrytan#1567) (garrytan#1572)
  v0.41.26.0 fix: dream --source + ingest junk titles + emoji-crash (supersedes garrytan#1559, garrytan#1561) (garrytan#1571)
  v0.41.25.0 perf(sync): batched deletes + global page-generation clock (supersedes garrytan#1538) (garrytan#1566)
  v0.41.24.0 fix(conversation-parser): threshold gates + bold-paren-time pattern — 20,167 Circleback messages unblocked (closes garrytan#1533) (garrytan#1543)
  v0.41.23.0 feat: extract operator surfaces + pack-driven extractables (garrytan#1541)
  v0.41.22.1 feat: brainstorm/lsd judge fixes (closes garrytan#1540 end-to-end) (garrytan#1562)
  v0.41.22.0 feat: type-unification cathedral — 94 types → 15 canonical (closes garrytan#1479) (garrytan#1542)
  v0.41.21.0 feat(ops): 5 daily-driver pains fixed in one wave (garrytan#1545)
  v0.41.20.0 feat: gbrain status + doctor --scope=brain (fix wave 2: items garrytan#6 + garrytan#7) (garrytan#1544)
  feat: v0.41.19.0 Supavisor Retry Cathedral (garrytan#1537)
  v0.41.18.0: gbrain onboard — the activation surface gbrain didn't have before (garrytan#1521)
  v0.41.17.0 feat: --workers N on every bulk command + facts dim doctor parity (garrytan#1519)
  v0.41.16.0 feat: conversation parser cathedral + progressive-batch primitive (closes garrytan#1461) (garrytan#1510)
  v0.41.15.0 feat(sync): --timeout + --max-age + partial status (closes garrytan#1472 RFC) (garrytan#1506)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@garrytan