Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import type { BrainEngine } from '../core/engine.ts';
import { setCliExitVerdict, writeJsonDocument } from '../core/cli-force-exit.ts';
import { getIdleBlockers } from '../core/migrate.ts';
import { parseFlags as parseSkillsDirFlags, resolveSkillsDir } from './check-resolvable.ts';
import { createProgress } from '../core/progress.ts';
import { categorizeCheck, type CheckCategory } from '../core/doctor-categories.ts';
import { rankIssues, type RankedIssue } from '../core/doctor-cause-rank.ts';
import { getCliOptions, cliOptsToProgressOptions } from '../core/cli-options.ts';
import type { DbUrlSource } from '../core/config.ts';
import { resolveEnvNumber, resolveHoursEnv } from '../core/env-number.ts';
export { checkPostgresCancellationDriver } from './doctor/checks/postgres-cancellation.ts';
export { checkProjectionReadiness } from './doctor/checks/projection-readiness.ts';
// Peeled doctor modules (containment sprint): each is a verbatim move out of
// this file. doctor.ts re-exports every moved public symbol under its
// original name so existing importers (tests, scripts/live-brain-first-check.ts,
// the run_doctor op's dynamic import of doctorReportRemote) keep working
// unchanged.
import { multiSourceDriftAdvice, multiSourceDriftGitRootSkipNote } from './doctor/schema-pack-checks.ts';
import { bootstrapDoctorChecks } from './doctor/bootstrap-checks.ts';
export { buildMemorableRelayCheck } from './doctor/checks/integrations-memorable.ts';
export { buildHomeDirInWorktreeCheck, isValidGitMarker } from './doctor/checks/home-worktree.ts';
export { buildMemoryWritebackCheck } from './doctor/checks/memory-writeback.ts';
import {
skillConformanceCheck,
skillsManifestIntegrityCheck,
skillCurrencyCheck,
skillPreconditionsCheck,
skillBrainFirstCheck,
} from './doctor/skill-checks.ts';
export {
multiSourceDriftAdvice,
multiSourceDriftGitRootSkipNote,
bootstrapDoctorChecks,
skillConformanceCheck,
skillsManifestIntegrityCheck,
skillCurrencyCheck,
skillPreconditionsCheck,
skillBrainFirstCheck,
};
export { doctorReportRemote } from './doctor/report-remote.ts';
// Peeled check bundles (containment sprint): verbatim moves of the standalone
// check-function library into src/commands/doctor/checks/*. Every exported
// symbol keeps its original name and import path via these re-exports
// (dozens of tests + scripts import checks directly from doctor.ts, and
// report-remote.ts consumes them through this façade).
export {
resolveWhoknowsFixturePath,
whoknowsHealthCheck,
pgvectorCheck,
pagesUpsertArbiterCheck,
linkSourceCheckConstraintCheck,
jsonbIntegrityCheck,
checkVolunteerChannels,
takesWeightGridCheck,
childTableOrphansCheck,
rawProvenanceCheck,
checkSourceConfigShape,
checkPgliteScratchProbe,
} from './doctor/checks/core-health.ts';
export {
checkContextualRetrievalCoverage,
checkHiddenBySearchPolicy,
checkLinkResolutionOpportunity,
checkAbandonedThreads,
checkCalibrationFreshness,
checkGradeConfidenceDrift,
checkSubagentHealth,
checkVoiceGateHealth,
checkRerankerHealth,
} from './doctor/checks/calibration.ts';
export {
computeQueueHealthCheck,
computeWedgedQueueCheck,
computeOrphanedPrivateQueueCheck,
computeAutopilotFanoutConcurrencyCheck,
checkBatchRetryHealth,
} from './doctor/checks/queue-jobs.ts';
export {
checkGraphSignalsCoverage,
checkBrainstormHealth,
checkEmbeddingWidthConsistency,
checkFactsEmbeddingWidthConsistency,
checkJunkEntityHubs,
JUNK_HUB_EDGE_THRESHOLD,
JUNK_HUB_MAX_CHUNKS,
} from './doctor/checks/graph-embedding.ts';
export {
checkSourceRoutingHealth,
checkFederationHealth,
checkOauthConfidentialHealth,
checkOauthClientScopeHealth,
checkAutopilotLockScope,
checkStaleLocks,
checkCyclePhaseScope,
} from './doctor/checks/routing-federation.ts';
export {
checkSearchMode,
checkEvalDrift,
checkEmbeddingEnvOverride,
checkEmbeddingMigrationState,
checkSubagentCapability,
computeConversationParserProbeHealthCheck,
computeNightlyQualityProbeHealthCheck,
computeConversationFactsBacklogCheck,
} from './doctor/checks/search-eval.ts';
export {
EXTRACTION_LAG_WARN_PCT_DEFAULT,
EXTRACTION_LAG_MIN_PAGES,
checkLinksExtractionLag,
checkUnverifiedExtractions,
checkContentHashDuplicates,
checkCodeChunkMetadata,
checkUndeclaredDbOnlyPages,
checkDbOnlyCollectorCollision,
computeExtractAtomsBacklogCheck,
computeAtomProvenanceDriftCheck,
computeExtractHealthCheck,
checkSyncFreshness,
} from './doctor/checks/extraction-sync.ts';
export { computeConversationFormatCoverageCheck } from './doctor/checks/conversation-coverage.ts';
export {
checkSyncConsolidation,
computePoolBudgetCheck,
checkPoolBudget,
checkCycleFreshness,
} from './doctor/checks/consolidation-cycle.ts';
export { dbRepairRecurrenceCheck, pgliteScaleCheck } from './doctor/checks/engine-fit.ts';
export {
computePgliteDataDirCheck,
computeWorkerOomLoopCheck,
computePoolReapHealthCheck,
} from './doctor/checks/pglite-worker.ts';
export {
buildMemoryVerbsCheck,
buildRetrievalReflexCheck,
} from './doctor/checks/verbs-reflex.ts';
import type { DoctorContext, DoctorTier } from './doctor/context.ts';
import { doctorRunSummary, parseDoctorScope, parseDoctorTier, scoredChecks, startDoctorDeadline, tierFields, type DoctorDeadline, type DoctorRunSummary, type ScoreCategory } from './doctor/budget.ts';
export { doctorRunSummary, type DoctorRunSummary } from './doctor/budget.ts';
import { runDoctorRegistry, parseOnlyChecks, doctorRefreshRegistry } from './doctor/registry.ts';
import { finalizeCheckFixes, fixLine, unknownScoreCategories, type CheckAgentFields } from './doctor/check-fix.ts';
import { throttleDoctorHeartbeat } from './doctor/heartbeat.ts';
import { alertRanChecks, computeAlert, printAlertReport, type DoctorAlert } from './doctor/alert.ts';
import type { RenderContext } from '../core/agent-output.ts';
export interface Check extends CheckAgentFields {
name: string;
status: 'ok' | 'warn' | 'fail';
message: string;
/**
* v0.38: optional structured payload for checks that surface data
* meant for programmatic consumption (e.g., cycle_phase_scope's
* `phase_scope_map`). Mirrors `PhaseResult.details`. Most checks pack
* everything into `message`; this is the escape hatch for ones that
* shouldn't.
*/
details?: Record<string, unknown>;
issues?: Array<{ type: string; skill: string; action: string; fix?: any }>;
/**
* v0.36+ brain-health-100: structured remediation jobs per check.
* Populated by the recommendation generator + (v0.40.3.0 T8b) individual
* checks (lint, integrity, sync_failures). Consumed by
* `gbrain doctor --remediation-plan` / `--remediate`. Optional and
* additive — schema_version stays at 2 (D4).
*
* v0.40.3.0 (D6): typed to RemediationStep[] from the canonical
* src/core/remediation-step.ts so check authors can use
* `makeRemediationStep()` factory without hand-rolling the shape.
*/
remediation?: import('../core/remediation-step.ts').RemediationStep[];
/** Top-level triage state per D13. */
remediation_status?: 'remediable' | 'human_only' | 'blocked';
/**
* v0.41.19.0 category tag — assigned by `categorizeCheck(name)` at report
* compute time. Optional + additive so legacy consumers ignore it.
* Source of truth: `src/core/doctor-categories.ts`.
*/
category?: CheckCategory;
/** #6696 B1: wall time of the registry entry that produced this check. */
elapsed_ms?: number;
/** Wave B decision #10: pages stored in segments this whole-body check did not read; only when > 0 (`withSkippedSegmented`). */
skipped_segmented?: number;
}
/**
* Structured doctor report. Stable shape consumed by:
* - gbrain doctor --json (CLI)
* - run_doctor MCP op (remote callers)
* - gbrain remote doctor (renders this from the MCP op response)
*
* schema_version=2 was set when --json output stabilized; bump only for
* breaking field changes.
*/
export interface DoctorReport {
schema_version: 2;
status: 'healthy' | 'warnings' | 'unhealthy';
/**
* Legacy all-checks aggregate. `100 − 20×fails − 5×warns`, floor 0.
*
* Preserved verbatim from pre-v0.41.19.0 for back-compat with `gbrain
* doctor --remediate`, `gbrain remote doctor`, the MCP `run_doctor` op,
* and any external monitor / CI gate that reads this field. NO behavior
* change: a fixed check set produces a byte-identical `health_score`
* before and after the v0.41.19.0 wave.
*/
health_score: number;
/**
* v0.41.19.0 — same penalty math (100 − 20×fails − 5×warns) restricted to
* checks tagged `category: 'brain'` by `categorizeCheck()`. The "is my
* brain's data healthy?" signal, decoupled from skill routing / ops /
* meta. Orthogonal to `BrainHealth.brain_score` (the weighted
* 35/25/15/15/10 composite surfaced by the `brain_score` doctor check) —
* `brain_checks_score` counts brain-category check failures;
* `brain_score` measures brain-data composition. Doctor renders both.
*/
brain_checks_score: number;
/**
* v0.41.19.0 — per-category penalty scores. Same math as `health_score`,
* restricted to each category in turn. An operator reading `score: 15`
* driven by 504 RESOLVER.md warnings now sees `category_scores.brain:
* ~100` and `category_scores.skill: 0` instead of one polluted number.
*/
category_scores: {
brain: number;
skill: number;
ops: number;
meta: number;
};
checks: Check[];
/**
* v0.42.x (#1685 GAP C) — non-ok checks ranked by cause (root before symptom,
* fail before warn). Lets an agent act on the root cause without re-deriving
* the ranking. Additive + optional; schema_version stays at 2.
*/
top_issues?: RankedIssue[];
/** W4: what an agent cron pages on (none / act / unknown, ./doctor/alert.ts); additive, the scores are unchanged. */
alert?: DoctorAlert;
/**
* db-availability loop — which engine this report was measured against and
* where its URL came from. Additive + optional (schema_version stays 2);
* absent on remote/report-only paths that don't know them.
*/
engine?: 'postgres' | 'pglite';
db_url_source?: DbUrlSource | null;
/** E2: capabilities off by choice that bound what this brain can do (e.g. `embeddings_disabled`). Additive. */
capped_by?: string[];
/** E10: category scores that are not evidence because their checks did not run (e.g. `brain` when the DB was unreachable). */
unknown_scores?: ScoreCategory[];
/** #7276: checks not finished within the budget; the scores skip them. */
unknown_count?: number;
/** #6696 B1, only with `--tier` / `--budget-ms`: the tier, whether every check is known, the unknown ones, wall time, budget (null: none). */
tier?: DoctorTier;
complete?: boolean;
unknown_sections?: string[];
/** #7142: checks reported from their last known result (with its age in `details.last_known`), not measured by this run. */
last_known_sections?: string[];
elapsed_ms?: number;
budget_ms?: number | null;
}
function _penaltyScore(checks: Check[]): number {
let score = 100;
for (const c of checks) {
if (c.status === 'fail') score -= 20;
else if (c.status === 'warn') score -= 5;
}
return Math.max(0, score);
}
/**
* Compute the {status, health_score, brain_checks_score, category_scores}
* headline from a list of checks. Mirrors the calculation in outputResults()
* so remote callers and the existing CLI front-end agree on what "healthy"
* means.
*
* **Back-compat invariant:** `health_score` math is byte-identical to
* pre-v0.41.19.0 for any fixed `checks` array. The new fields are additive.
*
* **Categorization:** each check is tagged via `categorizeCheck(name)` at
* report-build time if it doesn't already carry a `category` field. The
* categorizer is the single source of truth in
* `src/core/doctor-categories.ts`.
*/
export function computeDoctorReport(
checks: Check[],
extras?: { engine?: 'postgres' | 'pglite'; db_url_source?: DbUrlSource | null; render?: RenderContext; run?: DoctorRunSummary; alertRan?: ReadonlySet<string> },
): DoctorReport {
const tagged = finalizeCheckFixes(checks, extras?.render).map((c) =>
c.category ? c : { ...c, category: categorizeCheck(c.name) },
);
const capped_by = tagged.some((c) => c.name === 'embeddings' && c.readiness_state === 'disabled_by_choice') ? ['embeddings_disabled'] : [];
const hasFail = tagged.some((c) => c.status === 'fail');
const hasWarn = tagged.some((c) => c.status === 'warn');
const { known, unknown_count, unknown_categories } = scoredChecks(tagged);
const unknown_scores = [...new Set([...unknownScoreCategories(tagged), ...unknown_categories])];
const health_score = _penaltyScore(known);
const brain = known.filter((c) => c.category === 'brain');
const skill = known.filter((c) => c.category === 'skill');
const ops = known.filter((c) => c.category === 'ops');
const meta = known.filter((c) => c.category === 'meta');
const status: DoctorReport['status'] = hasFail ? 'unhealthy' : hasWarn ? 'warnings' : 'healthy';
return {
schema_version: 2,
status,
health_score,
brain_checks_score: _penaltyScore(brain),
category_scores: {
brain: _penaltyScore(brain),
skill: _penaltyScore(skill),
ops: _penaltyScore(ops),
meta: _penaltyScore(meta),
},
checks: tagged,
top_issues: rankIssues(tagged),
alert: computeAlert(tagged, { ran: extras?.alertRan, render: extras?.render }),
...(extras?.engine ? { engine: extras.engine } : {}),
...(extras?.db_url_source !== undefined ? { db_url_source: extras.db_url_source } : {}),
...(capped_by.length ? { capped_by } : {}),
...(unknown_scores.length ? { unknown_scores } : {}),
...(unknown_count ? { unknown_count } : {}),
...(extras?.run ? tierFields(tagged, extras.run) : {}),
};
}
/**
* Focused doctor for `run_doctor` MCP op + `gbrain remote doctor` CLI.
*
* Runs five checks scoped to "what does a remote operator need to know about
* this brain right now?":
* - connection (engine reachable + page count)
* - schema_version (current vs latest)
* - brain_score (the 5-component health composite)
* - sync_failures (unacked parse failures)
* - queue_health (Postgres-only: stalled-forever active jobs)
*
* Deliberately a focused subset of the local doctor surface, NOT a full
* mirror. Generalizing to lint/integrity/orphans is filed as follow-up work
* pending demand. Local doctor is unchanged — operators on the host machine
* still get the full check set.
*/
export { upgradeErrorResolved, checkSelfUpgradeHealth, checkUpgradeErrors } from './doctor/checks/upgrade-health.ts';
/**
* Re-exported from `src/core/env-number.ts`, which now owns the implementation
* AND the warn-once memo. `source-health.ts` needs the hours resolver for the
* staleness ceiling, and doctor already imports from source-health — so the
* helper had to move to core or the import graph would cycle.
*
* The `_resolveEnvNumber` name is kept because `sync.ts:5730` dynamically
* imports it from this module.
*/
export { resolveEnvNumber as _resolveEnvNumber };
/** Local aliases; the shared memo lives in core so it can't fork per module. */
const _resolveEnvNumber = resolveEnvNumber;
const _resolveSyncFreshnessHours = resolveHoursEnv;
/**
* Build the full check list for `gbrain doctor` against an engine + arg vector.
* Filesystem-first, DB-second: filesystem checks (resolver, conformance) run
* without an engine; DB checks run only if one is provided.
*
* `dbSource` is passed only from the `--fast` and DB-unavailable paths in
* cli.ts so we can emit a precise "why no DB check" message. When null, the
* user has no DB configured anywhere; otherwise the caller chose --fast or
* we failed to connect despite a configured URL.
*
* The check-building seam: takes the same args as `runDoctor` minus the
* --locks shortcut (locks-mode is a focused diagnostic the CLI wrapper
* handles separately). Returns a `Check[]` array; the caller renders it
* via `outputResults` and decides exit code. Early-exit cases (no engine,
* connection failure) return a partial check array without calling
* `process.exit` directly — the caller still renders + exits.
*
* v0.39 narrow-seam extract (audit-driven). The 10 `process.exit` sites
* in this file all live in CLI wrappers (`runDoctor`, `runLocksCheck`,
* the remediation subcommands). Behavioral tests drive `buildChecks`
* directly via PGLite; the wrapper-level subprocess smoke in
* `test/doctor-cli-smoke.test.ts` covers the render + exit paths that
* a unit test can't reach in-process.
*
* Refactor wave 1 (W4 doctor): the checks themselves are the ordered
* entries of `DOCTOR_CHECK_REGISTRY` (src/commands/doctor/registry.ts, one
* `{ name, emits, run }` per topic block under src/commands/doctor/checks/).
* buildChecks parses the flags into a `DoctorContext` and runs the registry;
* the two early exits are registry entries returning `STOP_DOCTOR`.
*
* Side effects retained inside the entries (kept for "no behavior change"):
* - `printAutoFixReport` on `--fix` non-JSON path
* - `progress` reporter writes to stderr (heartbeats per check)
* - `engine.executeRaw` / handler-leaf calls (the actual probe work)
*/
export async function buildChecks(
engine: BrainEngine | null,
args: string[],
dbSource?: DbUrlSource,
// db-availability loop (2c-bis): the connect error captured by the CLI's
// dead-DB fallback. Lets the null-engine path synthesize a CLASSIFIED
// `connection` check — without it, a total outage produced NO connection
// entry at all, which is exactly the field smoke-test branches on.
connectError?: unknown,
// #6696: the run's deadline (started by the CLI before connecting) and a remote caller's readable sources.
deadline: DoctorDeadline = startDoctorDeadline(args),
remoteScope: { sourceIds?: string[]; remote?: boolean; lastKnown?: 'cli' | 'refresh'; entryBudgetOverrideMs?: number; refreshOnly?: boolean } = {},
): Promise<Check[]> {
const jsonOutput = args.includes('--json');
const fastMode = args.includes('--fast');
const doFix = args.includes('--fix');
const dryRun = args.includes('--dry-run');
// v0.41.19.0 — `--scope=brain` SKIPS the SKILL check group (which walks the
// filesystem `skills/` tree, the dominant non-DB cost). Defaults to `all`.
// `runResolverChecks`-equivalent invocations are gated below; the same gate
// covers `whoknows_health` (the one DB-dependent skill check) where it's
// invoked later in the function.
const scope = parseDoctorScope(args);
// v0.41.29.0: explicit `--source <id>` scopes the `orphan_ratio` check to one
// source. EXPLICIT-ONLY by design — a raw flag parse, NOT resolveSourceWithTier.
// The tier resolver would pick a default source when `--source` is absent and
// silently scope a bare `gbrain doctor` to one source; we want bare doctor to
// stay brain-wide. Only `orphan_ratio` consumes this for now (other checks
// staying brain-wide is a separate, larger change — see TODOS.md).
let orphanRatioSourceId: string | undefined;
for (let i = 0; i < args.length; i++) {
if (args[i] === '--source' && i + 1 < args.length) {
orphanRatioSourceId = args[++i] || undefined;
}
}
// Progress reporter. `--json` is doctor's machine-readable output, so plain
// progress must not leak to stderr unless the caller explicitly asks for
// structured progress with --progress-json.
const progress = throttleDoctorHeartbeat(createProgress(doctorProgressOptions(jsonOutput)));
// --- Filesystem checks (always run, no DB needed) ---
// 1. Resolver health + 2. Skill conformance + 2b. Skill brain-first.
//
// SKILL check group (gated behind --scope=all).
//
// The resolver walk reads every SKILL.md under the configured skills dir
// (`skills/RESOLVER.md` or workspace-root `AGENTS.md`). On large OpenClaw
// deployments with 200+ skills this is the dominant non-DB cost. The
// v0.41.19.0 `--scope=brain` flag skips this whole block per D9 in the plan.
//
// We also skip `--fix` execution under scope=brain because --fix
// exclusively targets DRY violations inside SKILL.md files. Use the same
// resolution as `check-resolvable` (#4673: flag-first — doctor accepted
// `--skills-dir` and silently ignored it, so every skill check graded the
// auto-detected workspace and `--fix` could write SKILL.md edits into a
// workspace the operator explicitly steered away from). Sharing
// check-resolvable's exported resolveSkillsDir keeps the three skills-dir
// commands (doctor, check-resolvable, routing-eval) on one precedence:
// --skills-dir → $GBRAIN_SKILLS_DIR / $OPENCLAW_WORKSPACE / walk-up →
// install-path read-only fallback. `source: 'explicit'` correctly bypasses
// the install_path --fix refusal below — an explicit flag is exactly the
// operator signal that gate wants.
const detected = scope === 'all' ? resolveSkillsDir(parseSkillsDirFlags(args)) : { dir: null, source: 'none' as const };
const skillsDir = detected.dir;
const ctx: DoctorContext = {
engine,
args,
dbSource,
connectError,
jsonOutput,
fastMode,
doFix,
dryRun,
scope,
orphanRatioSourceId,
progress,
skillsDirResolution: detected,
skillsDir,
autoFixReport: null,
schemaVersion: 0,
connectionFailed: false,
only: parseOnlyChecks(args),
tier: parseDoctorTier(args),
deadline,
...(remoteScope.sourceIds ? { sourceIds: remoteScope.sourceIds } : {}), ...(remoteScope.remote ? { remote: true } : {}),
...(remoteScope.lastKnown ? { lastKnown: remoteScope.lastKnown } : {}),
...(remoteScope.entryBudgetOverrideMs ? { entryBudgetOverrideMs: remoteScope.entryBudgetOverrideMs } : {}),
};
return runDoctorRegistry(ctx, remoteScope.refreshOnly ? doctorRefreshRegistry() : undefined);
}
/**
* CLI entry point for `gbrain doctor`. Thin wrapper around buildChecks +
* computeDoctorReport + render + process.exit.
*
* Concerns kept here (not pushed into buildChecks):
* - --locks shortcut (focused diagnostic; calls runLocksCheck + returns)
* - outputResults render (stdout)
* - features teaser (non-JSON, non-failing only)
* - process.exit (10 sites total across runDoctor + runLocksCheck +
* runRemediationPlan + runRemediate)
*
* v0.39 narrow-seam extract — buildChecks is the unit-testable seam, this
* wrapper is the wallclock + exit-code concerned function. See
* test/doctor-behavioral.test.ts for the in-process seam coverage and
* test/doctor-cli-smoke.test.ts for the subprocess wrapper coverage.
*/
export async function runDoctor(
engine: BrainEngine | null,
args: string[],
dbSource?: DbUrlSource,
// db-availability loop: the connect error from the CLI's dead-DB fallback,
// threaded to buildChecks for the synthesized `connection` check (2c-bis).
connectError?: unknown,
deadline: DoctorDeadline = startDoctorDeadline(args),
) {
const jsonOutput = args.includes('--json');
const locksMode = args.includes('--locks');
// --locks is a focused diagnostic: it runs the same pg_stat_activity
// query that `runMigrations` pre-flight uses, prints any idle-in-tx
// backends, and exits. Referenced from migrate.ts's 57014 diagnostic.
if (locksMode) {
await runLocksCheck(engine, jsonOutput);
return;
}
if (args.includes('--probe') && !(await (await import('./doctor/probe-consent.ts')).authorizeProviderProbe(engine, args, jsonOutput))) return;
const checks = await buildChecks(engine, args, dbSource, connectError, deadline, { lastKnown: 'cli' });
const run = doctorRunSummary(args, deadline);
const extras = { engine: engine?.kind, db_url_source: dbSource ?? null, run, alertRan: alertRanChecks(checks, parseDoctorTier(args), parseOnlyChecks(args)) };
if (args.includes('--alert')) return setCliExitVerdict(printAlertReport(computeDoctorReport(checks, extras), jsonOutput));
const hasFail = outputResults(checks, jsonOutput, extras);
// Features teaser (non-JSON, non-failing only; never under the ops deadline)
if (!jsonOutput && !hasFail && engine && run?.tier !== 'ops') {
try {
const { featuresTeaserForDoctor } = await import('./features.ts');
const teaser = await featuresTeaserForDoctor(engine);
if (teaser) console.log(`\n${teaser}`);
} catch { /* best-effort */ }
}
// Use process.exitCode instead of process.exit() so cleanup handlers
// (e.g. Bun unload events, open database connections) still run before
// the process terminates. process.exit() is a hard kill that bypasses them.
setCliExitVerdict(hasFail ? 1 : 0);
}
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
export function doctorProgressOptions(jsonOutput: boolean) {
const cliOpts = getCliOptions();
if (jsonOutput && !cliOpts.quiet && !cliOpts.progressJson) {
return { mode: 'quiet' as const };
}
return cliOptsToProgressOptions(cliOpts);
}
function outputResults(
checks: Check[],
json: boolean,
extras?: Parameters<typeof computeDoctorReport>[1],
): boolean {
// v0.41.19.0 — render goes through computeDoctorReport so the human
// output, JSON output, and remote MCP envelope all share one shape.
const report = computeDoctorReport(checks, extras);
const hasFail = report.status === 'unhealthy';
const hasWarn = report.status === 'warnings';
const score = report.health_score;
if (json) {
void writeJsonDocument(JSON.stringify(report)); // D2: the one --json document
return hasFail;
}
console.log('\nGBrain Health Check');
console.log('===================');
// #1685 GAP C — cause-ranked summary so the operator reads the root cause
// first instead of scrolling the full list. Caps at 5; clean brains skip it.
const topIssues = report.top_issues ?? [];
if (topIssues.length > 0) {
console.log('');
console.log('Top issues (ranked by cause):');
const shown = topIssues.slice(0, 5);
for (const issue of shown) {
const icon = issue.status === 'fail' ? 'FAIL' : 'WARN';
const dn = issue.downstream_of ? ` (likely downstream of ${issue.downstream_of})` : '';
console.log(` [${icon}] ${issue.name}${dn} → ${fixLine(issue.action) ?? issue.fix}`);
}
if (topIssues.length > shown.length) {
console.log(` +${topIssues.length - shown.length} more — see full list below`);
}
console.log('');
}
for (const c of report.checks) {
const icon = c.status === 'ok' ? (c.severity === 'info' ? 'INFO' : 'OK') : c.status === 'warn' ? 'WARN' : 'FAIL';
console.log(` [${icon}] ${c.name}: ${c.message}`);
const fix = c.status === 'ok' ? null : fixLine(c.fix);
if (fix) console.log(` Fix: ${fix}`);
if (c.issues) {
for (const issue of c.issues) {
console.log(` → ${issue.type.toUpperCase()}: ${issue.skill}`);
console.log(` ACTION: ${issue.action}`);
}
}
}
// v0.41.19.0 — brain-first headline. The user asked "is my brain ok?".
// Lead with the brain-category score; show the legacy aggregate
// alongside as context. The weighted BrainHealth.brain_score (data
// composition) is surfaced separately by the `brain_score` check above —
// it's read out of the check list so we don't duplicate the query.
const brainScoreCheck = report.checks.find((c) => c.name === 'brain_score');
const brainScoreLine = brainScoreCheck
? `Weighted brain score: ${brainScoreCheck.status === 'ok' ? '' : `[${brainScoreCheck.status.toUpperCase()}] `}${brainScoreCheck.message}`
: null;
console.log('');
const catLine = (cat: ScoreCategory, scored: string) => report.unknown_scores?.includes(cat)
? `unknown (${cat === 'brain' && unknownScoreCategories(report.checks).length ? 'database checks did not run' : 'no check finished within the budget'})` : scored;
console.log(`Brain checks: ${catLine('brain', `${report.brain_checks_score}/100 (category penalty)`)}`);
console.log(`Skill checks: ${catLine('skill', `${report.category_scores.skill}/100`)}`);
console.log(`Ops checks: ${catLine('ops', `${report.category_scores.ops}/100`)}`);
console.log(`Meta checks: ${catLine('meta', `${report.category_scores.meta}/100`)}`);
if (report.unknown_count) console.log(`Unknown: ${report.unknown_count} check(s) did not finish within the budget; the scores count only the checks that finished.`);
if (brainScoreLine) console.log(brainScoreLine);
if (report.tier) console.log(`Tier: ${report.tier}, ${report.complete ? 'complete' : `incomplete (${[report.unknown_sections!.length ? `unknown: ${report.unknown_sections!.join(', ')}` : '', report.last_known_sections?.length ? `${report.last_known_sections.length} from last known results` : ''].filter(Boolean).join('; ')})`}, ${report.elapsed_ms} ms${report.budget_ms ? ` of ${report.budget_ms} ms` : ''}`);
console.log('');
if (hasFail) {
console.log(`Overall health score: ${score}/100. Failed checks found.`);
} else if (hasWarn) {
console.log(`Overall health score: ${score}/100. All checks OK (some warnings).`);
} else {
console.log(`Overall health score: ${score}/100. All checks passed.`);
}
return hasFail;
}
/**
* `gbrain doctor --locks` — list idle-in-transaction backends older
* than 5 minutes that could block DDL. Exits 0 on clean, 1 on blockers.
*
* Agents hitting a statement_timeout (SQLSTATE 57014) during migration
* need a one-command path to find and kill the blocker. migrate.ts's
* 57014 diagnostic references this flag by name; keep the two in sync.
*
* Postgres-only. PGLite has no pool, no idle-in-tx concept, so the
* check prints a one-liner and exits 0.
*/
async function runLocksCheck(engine: BrainEngine | null, jsonOutput: boolean): Promise<void> {
if (!engine) {
if (jsonOutput) {
void writeJsonDocument(JSON.stringify({ status: 'unavailable', reason: 'no_engine' }));
} else {
console.log('gbrain doctor --locks requires a database connection. Configure a URL and retry.');
}
process.exit(1);
}
if (engine.kind !== 'postgres') {
if (jsonOutput) {
void writeJsonDocument(JSON.stringify({ status: 'not_applicable', engine: engine.kind }));
} else {
console.log(`gbrain doctor --locks is Postgres-only. Current engine: ${engine.kind}. No blockers possible (no connection pool).`);
}
return;
}
const blockers = await getIdleBlockers(engine);
if (jsonOutput) {
void writeJsonDocument(JSON.stringify({ status: blockers.length === 0 ? 'ok' : 'blockers_found', blockers }, null, 2));
if (blockers.length > 0) process.exit(1);
return;
}
if (blockers.length === 0) {
console.log('✓ No idle-in-transaction backends older than 5 minutes.');
return;
}
console.log(`Found ${blockers.length} idle-in-transaction backend(s) older than 5 minutes:\n`);
for (const b of blockers) {
console.log(` PID ${b.pid} (idle since ${b.query_start})`);
console.log(` Query: ${b.query}`);
console.log(` Kill: SELECT pg_terminate_backend(${b.pid});`);
console.log('');
}
console.log('These connections may block ALTER TABLE DDL during migration.');
console.log('After terminating, retry: gbrain apply-migrations --yes');
process.exit(1);
}
// --remediation-plan + --remediate live in doctor/remediate.ts (re-exported for import-site stability).
export { runRemediationPlan, renderRemediationPlanLines, runRemediate } from './doctor/remediate.ts';