Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* bootstrapDoctorChecks — verbatim peel from src/commands/doctor.ts
* (containment sprint). No behavior change; doctor.ts re-exports the symbol
* and buildChecks consumes it.
*/
import { join } from 'path';
import { existsSync } from 'fs';
import { localProbe } from './local-probe.ts';
import type { BrainEngine } from '../../core/engine.ts';
import { LATEST_VERSION } from '../../core/migrate.ts';
// Agent-bootstrap doctor group (plan B2/B4/ENG-4 + one-live-serve note).
import { readHarnessReceiptState, readReceipt, type HarnessReceipt } from '../../core/bootstrap/format.ts';
import { probeLivePgliteHolder, resolveBrainDataDir } from '../../core/bootstrap/uninstall.ts';
import { readRunbookStamp, hooksInstalled, listVerifyRuns } from '../../core/bootstrap/status.ts';
import { resolveGbrainHome } from '../../core/gbrain-home.ts';
import { isManagedFilesystemPath } from '../../core/persistence/filesystem-guard.ts';
import { withoutPhysicalRootMetadata } from '../../core/persistence/root-metadata.ts';
import { agentFix } from './check-fix.ts';
import type { PushStatusEntry } from '../../core/workspace-push.ts';
import { VERSION as GBRAIN_BINARY_VERSION } from '../../version.ts';
import type { Check } from '../doctor.ts';
/**
* Agent-bootstrap check group (plan B2, B4, ENG-4, one-live-serve, C1 skew).
*
* Gated on bootstrap state actually existing on this machine (install
* receipt, hook heartbeat, or push-status) — machines that never ran
* `gbrain bootstrap` get ZERO checks from this group. Every probe is
* fail-soft: a broken telemetry file degrades to a warn, never a throw.
*/
/** #5878: warn when a shared-skills receipt epoch differs from this brain's membership row; true when it pushed. */
async function pushSupersededEnrollmentCheck(checks: Check[], engine: BrainEngine | null, hr: HarnessReceipt): Promise<boolean> {
if (!engine) return false;
const { supersededEnrollments, SKILLS_REFRESH_COMMAND, SKILLS_EPOCH_DOCS } = await import('../../core/bootstrap/harness-skills.ts');
const superseded = await supersededEnrollments(engine, hr).catch(() => []);
if (superseded.length === 0) return false;
checks.push({
name: 'bootstrap_harness_health',
status: 'warn',
message: `shared skills enrollment superseded: ${superseded.map(e => `${e.host} receipt epoch ${e.local_epoch}, server epoch ${e.server_epoch}${e.active ? '' : ' (inactive)'}`).join('; ')} ` +
`— sessions get membership_inactive. Fix: ${SKILLS_REFRESH_COMMAND} (${SKILLS_EPOCH_DOCS}).`,
details: { code: 'shared_skills_epoch_superseded', fix: SKILLS_REFRESH_COMMAND, docs: SKILLS_EPOCH_DOCS, enrollments: superseded },
});
return true;
}
/** #8990: `git -C <cwd> ...` stdout, or null on failure or past its 10 s bound (clipped to the entry deadline). */
type GitProbe = (cwd: string, ...args: string[]) => Promise<string | null>;
function gitProbe(entryDeadlineAt: number | undefined): GitProbe {
return (cwd, ...args) => localProbe(entryDeadlineAt, 'git', ['-C', cwd, ...args], { ownTimeoutMs: 10_000, windowsShell: false });
}
/** #5063: commits on the workspace's named branch that origin/<branch> lacks, counted whatever the push age (0 when unknown). */
async function commitsAheadOfOrigin(git: GitProbe, ws: string, branch: string): Promise<number> {
if (!branch) return 0;
return parseInt((await git(ws, 'rev-list', '--count', `origin/${branch}..HEAD`))?.trim() ?? '', 10) || 0;
}
/**
* #5371: one bootstrap_push_health finding. A managed canonical worktree
* refuses legacy bulk push, so there the remedy is the managed writer's
* read-only status probe; severity never changes, and an unmanaged root keeps
* `unmanagedRemedy`.
*/
function pushHealthCheck(root: string | null | undefined, status: 'warn' | 'fail', finding: string, unmanagedRemedy: string): Check {
if (!root || !isManagedFilesystemPath(root)) return { name: 'bootstrap_push_health', status, message: `${finding}${unmanagedRemedy}` };
return {
name: 'bootstrap_push_health', status,
message: `${finding} — ${root} is a managed canonical worktree, where legacy bulk push is not available. Inspect the managed writer with \`gbrain sources writer status --probe --json\`; changes must be written through gbrain (put_page or capture), direct file edits here are not published.`,
fix: agentFix(['gbrain', 'sources', 'writer', 'status', '--probe', '--json'],
'A managed canonical worktree is published by its persistence owner, not by a workspace push; the probe shows whether that owner is running and publishing, and changes nothing.',
'bootstrap_push_health'),
};
}
/** #6083: a tree with nothing uncommitted (ownership metadata aside) on a named branch, 0 commits ahead of a configured origin. */
async function treeMatchesOrigin(git: GitProbe, root: string): Promise<boolean> {
if ((await git(root, 'remote', 'get-url', 'origin')) === null) return false;
const branch = (await git(root, 'branch', '--show-current'))?.trim();
if (!branch) return false;
const status = await git(root, 'status', '--porcelain');
if (status === null || withoutPhysicalRootMetadata(status.trim()) !== '') return false;
return (await git(root, 'rev-list', '--count', `origin/${branch}..HEAD`))?.trim() === '0';
}
/**
* #6083: the recorded push failure finding. A failure whose tree now matches
* its origin is superseded (nothing is unpushed, and on a managed worktree
* nothing ever clears a refusal record); the first live failure decides.
*/
async function recordedPushFailureCheck(git: GitProbe, failing: PushStatusEntry[], ws: string | null): Promise<Check> {
const live: PushStatusEntry[] = [];
for (const s of failing) if (!s.repoRoot || !(await treeMatchesOrigin(git, s.repoRoot))) live.push(s);
if (live.length === 0) {
return { name: 'bootstrap_push_health', status: 'ok',
message: `last recorded push failed for ${failing.map((s) => s.repoRoot).join(', ')} (${failing[0]!.ts ?? 'unknown'}), but the tree matches its origin branch with nothing uncommitted; nothing to push` };
}
const s = live[0]!;
const target = s.repoRoot ?? ws ?? undefined;
const rest = live.length > 1 ? ` [+${live.length - 1} more workspace(s)]` : '';
return pushHealthCheck(target, 'warn', `last workspace push FAILED${target ? ` for ${target}` : ''} (${s.ts ?? 'unknown'}): ${s.reason ?? 'unknown'}${rest}`,
` — run \`gbrain sources push${target ? ` --path ${target}` : ''}\``);
}
export async function bootstrapDoctorChecks(engine: BrainEngine | null, entryDeadlineAt?: number): Promise<Check[]> {
const checks: Check[] = [];
const git = gitProbe(entryDeadlineAt);
let home: string;
try {
home = resolveGbrainHome();
} catch {
return [];
}
// 00. Plugin-lane coexistence. Runs BEFORE the bootstrap-state gate: a
// hand-wired registration can coexist with a plugin on machines that never
// ran `gbrain bootstrap`. Emits rows ONLY when a gbrain plugin is ENABLED
// in a harness config (machines without the plugin get zero noise):
// warn = a hand-wired registration also exists (duplicate tool
// registration; which server wins is host-defined), ok = the plugin is the
// sole owner. "Enabled" is a CONFIG signal, not a health signal — the row
// says so. Fail-soft like every probe in this group.
try {
const { enabledPluginLanes, codexAnyRegistrationExists, claudeAnyRegistrationExists } = await import('../../core/bootstrap/plugin-lanes.ts');
const { codexConfigPath, claudeUserMcpConfigPath } = await import('../../core/bootstrap/host-specs.ts');
const lanes = enabledPluginLanes('gbrain').map((lane) => lane.harness === 'codex'
? { ...lane, dup: codexAnyRegistrationExists(codexConfigPath(), 'gbrain'),
disambiguate: 'keep one owner: `codex mcp remove gbrain` (drop the hand-wired entry) or `codex plugin remove gbrain@gbrain` (drop the plugin)' }
: { ...lane, dup: claudeAnyRegistrationExists(claudeUserMcpConfigPath(), 'gbrain', process.cwd()),
disambiguate: 'keep one owner: `claude mcp remove gbrain` (drop the hand-wired entry) or disable the plugin in Claude Code' });
for (const lane of lanes) {
checks.push(
lane.dup
? {
name: 'plugin_lane_collision',
status: 'warn',
message:
`${lane.harness}: the '${lane.plugin}' plugin AND a hand-wired gbrain MCP registration both exist — ` +
`duplicate tool registration is host-defined behavior; ${lane.disambiguate}. ` +
'(Plugin enabled is a config signal, not a health signal.)',
}
: {
name: 'plugin_lane_collision',
status: 'ok',
message: `${lane.harness}: the '${lane.plugin}' plugin provides gbrain and no hand-wired registration was found in the scanned configs (user scope + this directory).`,
},
);
}
} catch {
/* fail-soft: a broken harness config never breaks doctor */
}
const receipt = readReceipt(home);
// One reader for every push-status surface [D8]; per-root files [D13].
const { readPushStatuses, pushStatusFilesExist, pushStatusForWorkspace, pushStatusRecordCounts } = await import('../../core/workspace-push.ts');
const pushStatuses = readPushStatuses();
const statusFilesOnDisk = pushStatusFilesExist();
const heartbeatFile = join(home, 'integrations', 'hooks', 'heartbeat.jsonl');
// #4043: a harness-only box (bootstrap harness, no workspace install) is
// bootstrap state too — without this, such a machine gets ZERO checks.
const harnessState = readHarnessReceiptState(home);
const hasBootstrapState =
receipt !== null || statusFilesOnDisk || existsSync(heartbeatFile) || harnessState.state !== 'absent';
// Return the pre-gate rows (plugin-lane coexistence) even on machines with
// no bootstrap state — the plugin lane needs no bootstrap to exist.
if (!hasBootstrapState) return checks;
const ws = receipt?.workspace_dir ?? null;
// 0. Harness registration health (#4043): three states so it neither cries
// wolf nor goes silent — skip (not a harness box) / warn (serve unreachable,
// a normal transient; or receipt unreadable) / fail (a target failed, or a
// prior rotation never converged). Token liveness needs the bearer (only
// recoverable from host config) — that's `gbrain bootstrap harness
// --status`'s job; doctor stays offline-cheap.
if (harnessState.state === 'ok') {
const hr = harnessState.receipt;
const { cleanupDoctorMessage, harnessCleanupReport, tokenStatesWith } = await import('../../core/bootstrap/harness-cleanup.ts');
let cleanup: Awaited<ReturnType<typeof harnessCleanupReport>> = [];
const failed = hr.targets.filter((t) => t.state === 'failed');
const pending = hr.targets.filter((t) => t.state === 'pending');
if (failed.length > 0 || pending.length > 0) {
checks.push({
name: 'bootstrap_harness_health',
status: 'fail',
message:
`harness wiring incomplete: ${failed.length} failed / ${pending.length} pending target(s)` +
` — re-run \`gbrain bootstrap harness\` to converge (details: gbrain bootstrap harness --status).`,
});
} else if ((cleanup = await harnessCleanupReport(hr, ids => engine ? tokenStatesWith(engine, ids) : Promise.resolve({}))).length > 0) {
// #6743: per id, a revoked credential awaiting enrollment cleanup reads apart from an active one (leave before revoke).
checks.push({
name: 'bootstrap_harness_health',
status: 'fail',
message: cleanupDoctorMessage(cleanup),
details: { code: 'bootstrap_cleanup_pending', cleanup },
});
} else if (hr.targets.length === 0 && hr.token.minted && hr.token.id !== undefined) {
// Half-removed state: a remove under a live PGLite serve strips every
// host target but defers the revoke — the wiring is gone yet the minted
// token stays ACTIVE. A vacuous all-confirmed must not read green.
// (Flag names spelled without dashes here: the flag-registry generator
// harvests bare flag tokens from comments one import level deep.)
checks.push({
name: 'bootstrap_harness_health',
status: 'fail',
message: `harness removal pending: host wiring removed but the minted token (id ${hr.token.id}) is not yet revoked — stop the serve and re-run \`gbrain bootstrap harness\` with the remove flag, or run \`gbrain auth revoke\` with the id flag.`,
});
} else if (!(await pushSupersededEnrollmentCheck(checks, engine, hr))) {
try {
const base = hr.url.replace(/\/mcp$/, '');
const res = await fetch(`${base}/health`, { signal: AbortSignal.timeout(3000) });
const body = res.ok ? ((await res.json()) as { status?: string }) : null;
if (body?.status === 'ok') {
checks.push({
name: 'bootstrap_harness_health',
status: 'ok',
message: `harness wired to ${hr.url} (serve healthy; token check: gbrain bootstrap harness --status)`,
});
} else {
checks.push({
name: 'bootstrap_harness_health',
status: 'warn',
message: `harness wired to ${hr.url} but the serve is not answering /health — start \`gbrain serve\` in http mode (a down serve is a normal transient, sessions just lose brain access until it returns).`,
});
}
} catch {
checks.push({
name: 'bootstrap_harness_health',
status: 'warn',
message: `harness wired to ${hr.url} but the serve is unreachable — start \`gbrain serve\` in http mode.`,
});
}
}
const { harnessHookCarrierChecks } = await import('./harness-hook-checks.ts');
checks.push(...harnessHookCarrierChecks(hr));
} else if (harnessState.state !== 'absent') {
checks.push({
name: 'bootstrap_harness_health',
status: 'warn',
message: `the harness receipt is unreadable (${harnessState.state}) — see \`gbrain bootstrap harness --status\`.`,
});
}
// 1. Hook heartbeat failure rate [B3 read side]. Hard errors only —
// degraded entries are DESIGNED fallbacks (pull-mode, no serve).
let hooksSeen = false;
try {
const { readHeartbeatTail, HEARTBEAT_FAILURE_WINDOW, HEARTBEAT_FAILURE_RATE_THRESHOLD } =
await import('../hook.ts');
const tail = await readHeartbeatTail(HEARTBEAT_FAILURE_WINDOW);
if (tail.length > 0) {
hooksSeen = true;
const failures = tail.filter((e) => e.outcome === 'error').length;
const rate = failures / tail.length;
if (rate > HEARTBEAT_FAILURE_RATE_THRESHOLD) {
checks.push({
name: 'bootstrap_hooks_heartbeat',
status: 'fail',
message: `${failures}/${tail.length} recent hook invocations hard-failed — brain context is not reaching the session. Check \`gbrain bootstrap verify\` and the serve process.`,
});
} else if (rate > 0.2) {
checks.push({
name: 'bootstrap_hooks_heartbeat',
status: 'warn',
message: `${failures}/${tail.length} recent hook invocations hard-failed. Watch it; hooks fail open so sessions still work.`,
});
} else {
// Degraded entries are designed fallbacks, but a window that is
// MOSTLY one degrade reason is a standing misconfiguration hiding
// behind "healthy" — name the top reason so it is at least visible.
const degradedReasons = tail.filter((e) => e.outcome === 'degraded' && e.reason).map((e) => e.reason as string);
let topClause = '';
if (degradedReasons.length > 0) {
const counts = new Map<string, number>();
for (const r of degradedReasons) counts.set(r, (counts.get(r) ?? 0) + 1);
const [topReason, topN] = [...counts.entries()].sort((a, b) => b[1] - a[1])[0]!;
topClause = `; ${degradedReasons.length}/${tail.length} degraded (top: ${topReason} x${topN})`;
}
checks.push({
name: 'bootstrap_hooks_heartbeat',
status: 'ok',
message: `hook heartbeat healthy (${failures}/${tail.length} hard failures in the trailing window${topClause})`,
});
}
}
} catch {
checks.push({ name: 'bootstrap_hooks_heartbeat', status: 'warn', message: 'hook heartbeat unreadable' });
}
// 2. Push staleness [B4]: fail when the last successful push is >48h old
// AND the workspace tree is dirty (recent work provably unpushed). Per-root
// status files [D13]: the WORST entry decides, so one workspace's success
// can never mask another's failure.
try {
if (pushStatuses.length > 0) {
const { PUSH_STALE_MS } = await import('../hook.ts'); // hook.ts owns the threshold (single source)
const failing = pushStatuses.filter((s) => s.ok === false);
if (failing.length > 0) {
checks.push(await recordedPushFailureCheck(git, failing, ws));
} else {
const stamps = pushStatuses.map((s) => Date.parse(s.ts ?? '')).filter((t) => Number.isFinite(t));
const stalest = stamps.length > 0 ? Math.min(...stamps) : NaN;
const staleIso = Number.isFinite(stalest) ? new Date(stalest).toISOString() : 'unknown';
const stale = Number.isFinite(stalest) && Date.now() - stalest > PUSH_STALE_MS;
// Can the staleness verdict be safely attributed to `ws` — the only
// workspace this check actually probes? Only when there's exactly
// ONE tracked push-status target, and it's either legacy-shaped (no
// repoRoot field) or explicitly `ws` itself. With multiple targets,
// "clean" on `ws` says nothing about whichever OTHER root is
// actually the stale one — per-root files [D13]: the WORST entry
// decides, so an ambiguous multi-root stale must never be
// downgraded to ok on the strength of a different root's clean tree.
const targetMatchesWs =
pushStatuses.length === 1 && (pushStatuses[0]!.repoRoot === undefined || pushStatuses[0]!.repoRoot === ws);
// `dirty` also covers commits ahead of origin (a clean working tree
// with committed-but-unpushed commits is still unpushed work) — the
// same two-dimensional definition `treeNeedsPush` uses for the
// per-turn push [hook.ts]. `known` distinguishes "verified clean"
// from "couldn't verify" (no receipt/workspace, or the git probe
// itself failed): unverified must NOT be treated as clean below.
let dirty = false, known = false, ahead = 0;
if (ws) {
const statusRaw = await git(ws, 'status', '--porcelain');
const branch = statusRaw === null ? null : (await git(ws, 'branch', '--show-current'))?.trim() ?? null;
if (statusRaw !== null && branch !== null) {
const statusOut = withoutPhysicalRootMetadata(statusRaw);
ahead = await commitsAheadOfOrigin(git, ws, branch);
if (statusOut.trim() !== '') {
dirty = true;
known = true;
} else if (branch) {
// origin/<branch> doesn't resolve — e.g. never pushed. Any
// local commit on top of an empty tree still counts as
// needing a push (this fallback only applies to a NAMED
// branch with no upstream; see the detached-HEAD branch
// below for why the same trick is unsafe there). Mirrors
// treeNeedsPush's [hook.ts] existing "never pushed" fallback
// as-is: a topic branch already fully contained in another
// remote branch (e.g. origin/main) but never itself fetched
// as origin/<branch> can over-report as dirty here — an
// inherited, pre-existing edge case, left as a false FAIL
// rather than a false OK, which is the safer direction for
// this specific check.
const countOut = (await git(ws, 'rev-list', '--count', `origin/${branch}..HEAD`)) ?? (await git(ws, 'rev-list', '--count', 'HEAD'));
if (countOut !== null) {
dirty = (parseInt(countOut.trim(), 10) || 0) > 0;
known = true;
}
} else {
// Detached HEAD: `rev-list --count HEAD` counts ALL history
// reachable from HEAD, not just unpushed commits, so it is
// NOT a safe "never pushed" fallback here (unlike the named-
// branch case above) — it would flag any non-trivial repo as
// dirty even when HEAD is already contained by origin. If
// `@{u}` doesn't resolve, tree state is simply unverifiable.
const aheadOut = await git(ws, 'rev-list', '--count', '@{u}..HEAD');
if (aheadOut !== null) {
dirty = (parseInt(aheadOut.trim(), 10) || 0) > 0;
known = true;
}
}
}
}
if (dirty && ws && Date.now() - Date.parse(pushStatusForWorkspace(pushStatuses, ws)?.ts ?? '') > PUSH_STALE_MS) { // #5432: this root's own receipt
checks.push(pushHealthCheck(ws, 'fail', `last successful push ${pushStatusForWorkspace(pushStatuses, ws)?.ts} (>48h) with a DIRTY workspace tree — recent agent memory is unpushed [B4]`,
`. Run \`gbrain sources push --path ${ws}\`.`));
} else if (stale && !targetMatchesWs) {
// Multiple tracked push targets (or the one target names a
// different repoRoot than `ws`) — the stale entry can't be
// attributed to the workspace just probed, so a clean `ws` proves
// nothing about the actually-stale root. Stay warn, same as the
// pre-this-fix behavior for every stale case.
checks.push({
name: 'bootstrap_push_health',
status: 'warn',
message: `last successful push ${staleIso} (>48h ago) across ${pushStatuses.length} tracked workspace(s) — can't attribute the stale entry to a single tree; check each with \`gbrain sources status\``,
});
} else if (stale && known) {
// Stale push + VERIFIED clean tree (no local changes, not ahead of
// origin) is benign: nothing to push, no action needed. The dirty
// case above (fail) and the unverified/ambiguous cases (warn) are
// the states that name a real fix.
checks.push({ name: 'bootstrap_push_health', status: 'ok', message: `no push activity since ${staleIso}; tree confirmed clean, nothing to push` });
} else if (stale) {
checks.push(ws
? pushHealthCheck(ws, 'warn', `last successful push ${staleIso} (>48h ago); workspace tree state unverified (the git probe failed)`,
` — check ${ws} manually, or run \`gbrain sources push --path ${ws}\` to be safe`)
: { name: 'bootstrap_push_health', status: 'warn', message: `last successful push ${staleIso} (>48h ago); workspace tree state unverified (no bootstrap receipt on this machine names a workspace to check) — check the workspace manually` });
} else {
// #5063: a recent successful push of something never certifies a tree that is still ahead.
checks.push(ahead > 0 ? pushHealthCheck(ws, 'warn', `last push ok (${staleIso}), but ${ws} has ${ahead} commit(s) not on origin — recent agent memory is unpushed`, `. Run \`gbrain sources push --path ${ws}\`.`)
: { name: 'bootstrap_push_health', status: 'ok', message: `last push ok (${staleIso})` });
}
}
} else if (statusFilesOnDisk) {
// Files exist but none parsed — the tolerant reader skips corrupt
// records; doctor must not let that read as "no news is good news".
// #7377: records kept for workspaces that no longer exist are history.
const counts = pushStatusRecordCounts();
checks.push(counts.unreadable === 0 && counts.gone > 0
? { name: 'bootstrap_push_health', status: 'ok', message: `push status is kept only for ${counts.gone} workspace(s) that no longer exist; no tracked workspace to check` }
: { name: 'bootstrap_push_health', status: 'warn', message: 'push status unreadable' });
}
} catch {
checks.push({ name: 'bootstrap_push_health', status: 'warn', message: 'push status unreadable' });
}
// 2b. Durability job [B7/D7]: presence + LIVENESS. A presence-only check
// certifies dead jobs as healthy (the autopilot-status failure mode), so
// this warns on plist-present-but-unloaded and stale pull logs. Only warns
// when the user actually consented to the job; containers/cloud sandboxes
// are expected to have none.
try {
if (ws !== null && receipt !== null) {
const { detectExecutionEnvironment } = await import('../../core/execution-env.ts');
const envKind = detectExecutionEnvironment();
if (envKind !== 'local') {
// Answered BEFORE the subprocess probes — cloud/container doctor
// runs must not pay launchctl/crontab spawns for an answer that is
// discarded (no scheduler exists there by design).
checks.push({
name: 'bootstrap_durability_job',
status: 'ok',
message: `no scheduler in this environment (${envKind}) — expected; per-turn and session-end pushes cover persistence`,
});
} else {
const { durabilityJobStatus } = await import('../../core/brain-repo-durability.ts');
const { readInterviewState } = await import('../../core/bootstrap/interview.ts');
const sourceId = receipt.source_id ?? 'workspace';
const js = durabilityJobStatus(sourceId);
let consented = false;
try {
const iv = readInterviewState(ws);
consented = iv.ok && (iv.state.answers['PERSIST_CRON']?.value ?? '').toLowerCase() === 'yes';
} catch { consented = false; }
if (!consented) {
if (js.kind !== 'none') {
checks.push({ name: 'bootstrap_durability_job', status: 'ok', message: `${js.kind} pull job present (not required by consent — fine)` });
}
// no consent + no job → nothing to check; stay silent
} else if (js.kind === 'none') {
checks.push({
name: 'bootstrap_durability_job',
status: 'warn',
message: `background persistence was consented (PERSIST_CRON=yes) but no scheduled job exists — run \`gbrain sources harden ${sourceId}\``,
});
} else if (js.live === false) {
checks.push({
name: 'bootstrap_durability_job',
status: 'warn',
message: `${js.kind} job is on disk but NOT loaded — a dead job looks healthy to presence checks. Re-run \`gbrain sources harden ${sourceId}\` to reload it.`,
});
} else if (!js.wrapperPresent) {
checks.push({
name: 'bootstrap_durability_job',
status: 'warn',
message: `${js.kind} job exists but its wrapper script is missing — re-run \`gbrain sources harden ${sourceId}\``,
});
} else if (js.logFresh === false) {
checks.push({
name: 'bootstrap_durability_job',
status: 'warn',
message: `${js.kind} job present but the pull log is stale (no run within 2× the interval) — the job may be dead; re-run \`gbrain sources harden ${sourceId}\``,
});
} else if (js.kind === 'crontab' && js.logFresh === undefined) {
// The crontab LINE existing proves installation, not that the cron
// daemon runs it — with no pull log yet we can't claim liveness.
checks.push({ name: 'bootstrap_durability_job', status: 'ok', message: 'crontab pull job installed (no run logged yet — liveness confirmed once it first fires)' });
} else {
checks.push({ name: 'bootstrap_durability_job', status: 'ok', message: `${js.kind} pull job present and live` });
}
}
}
} catch { /* best-effort — durability probing never fails doctor */ }
// 3. One-live-serve / lock collision note. A live serve is the healthy
// shape (it provides hook IPC); the note names the v1 contract.
try {
const dataDir = resolveBrainDataDir(home);
const holder = probeLivePgliteHolder(dataDir);
if (holder && !holder.isSelf) {
checks.push({
name: 'bootstrap_serve_lock',
status: holder.serve ? 'ok' : 'warn',
message: holder.serve
? `live serve (pid ${holder.pid}) owns the brain — hook IPC available. One live serve per brain is the v1 contract; a second simultaneous session collides politely.`
: `a non-serve gbrain process (pid ${holder.pid}) holds the PGLite lock — hook IPC and new sessions will fail until it exits.`,
});
}
} catch { /* probe is best-effort */ }
// 4. [ENG-4] Hooks-in-use + unmigrated brain: the direct-engine hook paths
// swallow missing-table errors on pre-v110/v117 schemas, so context
// degrades SILENTLY. Pair the two signals into a named warning.
const hooksActive = hooksSeen || (ws !== null && hooksInstalled(ws));
if (hooksActive && engine) {
try {
const versionStr = await engine.getConfig('version');
const version = parseInt(versionStr || '0', 10);
if (version < LATEST_VERSION) {
checks.push({
name: 'bootstrap_hook_schema_pairing',
status: 'warn',
message: `hooks are in use but the brain schema is v${version} (< v${LATEST_VERSION}) — hook context can degrade silently on missing tables [ENG-4]. Run \`gbrain apply-migrations --yes\`.`,
});
}
} catch { /* schema_version check above already covers unreadable version */ }
}
// 5. Runbook skew [C1]: the fetched runbook's stamp vs this binary.
if (ws) {
try {
const stamp = readRunbookStamp(ws);
if (stamp !== null && stamp !== GBRAIN_BINARY_VERSION) {
checks.push({
name: 'bootstrap_runbook_skew',
status: 'warn',
message: `BOOTSTRAP_FOR_AGENTS.md stamp ${stamp} != installed binary ${GBRAIN_BINARY_VERSION} — prefer the binary's instructions; re-fetch the runbook.`,
});
}
} catch { /* best effort */ }
}
// 6. Last verify freshness [B2 read side] — surfaced so "verify weekly"
// has a nag with teeth.
try {
const runs = listVerifyRuns(home);
if (runs.length > 0) {
const last = runs[0];
const t = Date.parse(last.ts);
const ageDays = Number.isFinite(t) ? (Date.now() - t) / 86_400_000 : NaN;
if (!last.ok) {
checks.push({ name: 'bootstrap_last_verify', status: 'warn', message: `last bootstrap verify FAILED (${last.ts}): ${last.checks_failed.join(', ') || 'see snapshot'} — re-run \`gbrain bootstrap verify\`` });
} else if (Number.isFinite(ageDays) && ageDays > 14) {
checks.push({ name: 'bootstrap_last_verify', status: 'warn', message: `last bootstrap verify passed ${Math.floor(ageDays)}d ago — re-run it as the workspace rot self-check` });
} else {
checks.push({ name: 'bootstrap_last_verify', status: 'ok', message: `last verify passed (${last.ts})` });
}
}
} catch { /* best effort */ }
return checks;
}