Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Explicit-only repair kinds (fix wave 5, ENG-O1(a) / DX-O4 / ENG-O13):
* `stale-atoms` and `extractor-facts` are registered with `explicit_only`.
* They run only when named; `gbrain repair --all`, the no-kind preview, the
* remediation plan and the post-upgrade banner list them with their preview
* command instead, and the runner refuses one that reaches it unnamed, so a
* supplied remediation step cannot run it.
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { OperationError, type OperationContext } from '../src/core/ops/contract.ts';
import { resolveRepairScope, runRepair, type RepairKind } from '../src/core/repair/core.ts';
import { AUTO_REPAIR_REGISTRY, EXPLICIT_REPAIR_REGISTRY, REPAIR_REGISTRY, repairRunner, repairSpec } from '../src/core/repair/registry.ts';
import { staleAtomsRepair } from '../src/core/repair/stale-atoms.ts';
import { planRepairSteps, runRepairSteps, type RepairPlanStep } from '../src/core/remediation/repairs.ts';
import { computeRemediationPlan } from '../src/core/remediation/index.ts';
import { classifyWaveFindings, renderRemediationPlanLines } from '../src/commands/doctor/remediate.ts';
import { bannerFindingLine } from '../src/commands/doctor/upgrade-banner.ts';
import type { WaveCheckSpec, WaveFinding } from '../src/commands/doctor/wave-checks.ts';
import { REPAIR_HELP, parseRepairArgs, runRepairCommand } from '../src/commands/repair.ts';
import { _resetCliExitVerdictForTests, currentExitCode } from '../src/core/cli-force-exit.ts';
import { withEnv } from './helpers/with-env.ts';
const EXPLICIT: RepairKind[] = ['accepted-takes', 'google-file-modes', 'stale-atoms', 'atoms-restore', 'atom-fence-rows', 'extractor-facts', 'unwithdrawn-facts', 'purged-page-facts', 'purged-change-reasons', 'conversation-labels', 'captured-facts', 'agent-session-facts', 'redacted-facts', 'loop-facts', 'ontology-facts', 'facts-rehome', 'consolidate-ties', 'duplicate-facts', 'orphan-children', 'failed-writes', 'split-facts', 'frontmatter', 'timeline-comments', 'timeline-order', 'contact-rows', 'managed-sync-orphans', 'content-receipt-root', 'frontmatter-keys', 'file-drift', 'stuck-recovery', 'ghost-pages', 'origin-twins', 'moved-pages', 'receipt-compaction', 'aliases', 'rename-identity', 'overwritten-edits', 'legacy-twins', 'missing-tables', 'url-clone-fences', 'segmented-mirror', 'segmented-tiling', 'uncommitted-deletions', 'generations', 'lost-fence-rows', 'fact-claim-dates', 'provenance', 'secret-spans', 'rows-behind', 'facts-home', 'private-labels', 'open-facts'];
// GBRA-161: the generations preview carries its ledger kind and the restore window, so the printed command runs as is.
// open-facts (#8194) needs --source and --created-before, which only the operator can name, so no surface lists it.
const LISTED = EXPLICIT.filter(kind => kind !== 'open-facts');
const PREVIEW = (kind: RepairKind): string => kind === 'generations' ? 'gbrain repair generations --kind atom --since 30d' : `gbrain repair ${kind}`;
let engine: PGLiteEngine;
const home = mkdtempSync(join(tmpdir(), 'gbrain-repair-explicit-'));
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
}, 60_000);
afterAll(async () => {
await engine.disconnect();
rmSync(home, { recursive: true, force: true });
});
async function refusal(run: () => Promise<unknown>): Promise<OperationError> {
try { await run(); } catch (error) { if (error instanceof OperationError) return error; throw error; }
throw new Error('expected a refusal');
}
async function captured(args: string[]): Promise<string> {
const lines: string[] = [];
const original = console.log;
console.log = (...parts: unknown[]) => { lines.push(parts.map(String).join(' ')); };
try { await withEnv({ GBRAIN_HOME: home }, () => runRepairCommand(engine, args)); } finally { console.log = original; }
return lines.join('\n');
}
/** A wave check whose findings an explicit-only kind clears (the lanes add the real check ids). */
function withExplicitCheck<T>(run: (spec: WaveCheckSpec) => T): T {
const checks = repairSpec('stale-atoms').checks;
checks.push('fixture_stale_atoms');
const spec: WaveCheckSpec = { id: 'fixture_stale_atoms', resolution: 'repair', registration: 'wave', impact: 'fixture', count: d => Number(d.count ?? 0),
run: async () => ({ name: 'fixture_stale_atoms', status: 'warn', message: 'stale atoms' }) };
try { return run(spec); } finally { checks.pop(); }
}
describe('registry', () => {
test('google-file-modes, stale-atoms, extractor-facts and loop-facts are registered explicit-only and excluded from the --all set', () => {
expect(EXPLICIT_REPAIR_REGISTRY.map(spec => spec.kind)).toEqual(EXPLICIT);
for (const kind of EXPLICIT) expect(REPAIR_REGISTRY.map(spec => spec.kind)).toContain(kind);
expect(AUTO_REPAIR_REGISTRY.some(spec => spec.explicit_only)).toBe(false);
expect(AUTO_REPAIR_REGISTRY.length + EXPLICIT_REPAIR_REGISTRY.length).toBe(REPAIR_REGISTRY.length);
});
});
describe('execution-time enforcement', () => {
test('runRepair refuses an explicit-only handler that was not named, then previews it when named', async () => {
const scope = await resolveRepairScope(engine);
const ctx = { engine, config: { engine: 'pglite' }, logger: { info() {}, warn() {}, error() {} }, dryRun: true, remote: false } as unknown as OperationContext;
const unnamed = await refusal(() => runRepair(ctx, staleAtomsRepair, scope, { apply: false }));
expect(unnamed.toJSON()).toMatchObject({ error: 'explicit_kind_required', suggestion: 'Preview it on the brain host: gbrain repair stale-atoms',
docs: 'docs/guides/repair.md#explicit-only-repair-kinds' });
const named = await runRepair(ctx, staleAtomsRepair, scope, { apply: false, explicit: true });
expect(named).toMatchObject({ kind: 'stale-atoms', mode: 'dry_run', affected: 0 });
});
test('the shared runner refuses an unnamed explicit-only kind', async () => {
const runner = await repairRunner(engine, { apply: true, logger: { info() {}, warn() {}, error() {} } });
const scope = await resolveRepairScope(engine);
expect((await refusal(() => runner.run('extractor-facts', scope))).code).toBe('explicit_kind_required');
});
test('a supplied remediation step naming an explicit-only kind refuses the whole run before any step starts', async () => {
const step = (kind: RepairPlanStep['kind'], n: number): RepairPlanStep => ({ step: n, id: `repair:${kind}`, kind, affected: 1, command: `gbrain repair ${kind} --apply`,
requires_user_agreement: true, protected: true, paid: false, embeds: 'none', est_usd_cost: 0, lifetime_ids: 0, checks: [], rationale: 'supplied' });
const started: string[] = [];
for (const kind of EXPLICIT) {
const error = await refusal(() => withEnv({ GBRAIN_HOME: home }, () => runRepairSteps(engine, [step('connector-checkpoints', 1), step(kind, 2)],
{ remote: false, remainingUsd: () => undefined, onStep: s => { started.push(s.kind); } })));
expect(error.code).toBe('explicit_kind_required');
expect(error.message).toContain(kind);
}
expect(started).toEqual([]);
});
});
describe('surfaces that list instead of run', () => {
test('gbrain repair --all and the no-kind preview never run explicit kinds and list their preview commands', async () => {
for (const args of [['--all', '--json'], ['--json']]) {
const out = JSON.parse(await captured(args)) as { results: Array<{ kind: string }>; explicit_kinds: Array<{ kind: string; code: string; preview_command: string }> };
expect(out.results.map(r => r.kind)).toEqual(AUTO_REPAIR_REGISTRY.map(spec => spec.kind));
expect(out.explicit_kinds).toEqual(LISTED.map(kind => ({ kind, code: 'explicit_kind_required', preview_command: PREVIEW(kind),
docs: 'docs/guides/repair.md#explicit-only-repair-kinds' })));
}
expect(await captured(['--all'])).toContain('Explicit-only kinds (not run without their name; preview each): gbrain repair accepted-takes; gbrain repair google-file-modes; gbrain repair stale-atoms; gbrain repair atoms-restore; gbrain repair atom-fence-rows; gbrain repair extractor-facts; gbrain repair unwithdrawn-facts; gbrain repair purged-page-facts; gbrain repair purged-change-reasons; gbrain repair conversation-labels; gbrain repair captured-facts; gbrain repair agent-session-facts; gbrain repair redacted-facts; gbrain repair loop-facts');
});
test('gbrain repair --all --apply exits 0 when explicit kinds are the only ones left', async () => {
_resetCliExitVerdictForTests();
const out = JSON.parse(await captured(['--all', '--apply', '--json'])) as { results: Array<{ kind: string; stopped?: unknown }> };
expect(out.results.some(r => EXPLICIT.includes(r.kind as RepairKind))).toBe(false);
expect(out.results.every(r => !r.stopped)).toBe(true);
expect(currentExitCode()).toBe(0);
});
test('naming an explicit kind runs it (here: the extractor-facts preview) instead of explicit_kind_required', async () => {
const out = JSON.parse(await captured(['extractor-facts', '--json'])) as { results: Array<{ kind: string; mode: string; affected: number }>; explicit_kinds?: unknown };
expect(out.results).toMatchObject([{ kind: 'extractor-facts', mode: 'dry_run', affected: 0 }]);
expect(out.explicit_kinds).toBeUndefined();
});
test('help marks explicit kinds with their preview and keeps them out of the --all list; --expect is accepted only for them', () => {
expect(REPAIR_HELP).toContain('[explicit-only; preview: gbrain repair stale-atoms]');
const allLine = REPAIR_HELP.split('\n').find(line => line.trimStart().startsWith('--all'))!;
for (const kind of EXPLICIT) expect(allLine).not.toContain(kind);
expect(parseRepairArgs(['stale-atoms', '--apply', '--expect', 'abc'])).toMatchObject({ kind: 'stale-atoms', apply: true, expect: 'abc' });
expect(parseRepairArgs(['extractor-facts', '--include-ambiguous'])).toMatchObject({ includeAmbiguous: true });
// #6188 (D8): a preview-bound kind that is not explicit-only (fences) accepts --expect, never --include-ambiguous.
expect(parseRepairArgs(['fences', '--apply', '--expect', 'abc'])).toMatchObject({ kind: 'fences', apply: true, expect: 'abc' });
for (const args of [['timeline', '--expect', 'abc'], ['--all', '--expect', 'abc']]) {
expect(() => parseRepairArgs(args)).toThrow(/--expect applies only to an explicit-only or preview-bound kind/);
}
for (const args of [['visibility', '--include-ambiguous'], ['fences', '--include-ambiguous']]) {
expect(() => parseRepairArgs(args)).toThrow(/--include-ambiguous applies only to an explicit-only kind/);
}
});
test('the remediation plan never plans explicit kinds and lists each with its preview command', async () => {
expect((await planRepairSteps(engine)).some(step => EXPLICIT.includes(step.kind))).toBe(false);
const plan = await withEnv({ GBRAIN_HOME: home }, () => computeRemediationPlan(engine, { repairs: {} }));
expect(plan.repair_steps!.some(step => EXPLICIT.includes(step.kind))).toBe(false);
expect(plan.explicit_repairs!.map(n => [n.kind, n.code, n.preview_command])).toEqual(LISTED.map(kind => [kind, 'explicit_kind_required', PREVIEW(kind)]));
const text = renderRemediationPlanLines(plan, 90).join('\n');
expect(text).toContain('Explicit-only repairs');
expect(text).toContain(' stale-atoms: gbrain repair stale-atoms');
expect(text).not.toContain('gbrain repair stale-atoms --apply');
});
test('the banner and the remediation classification report explicit_kind_required with the preview, never an apply', () => withExplicitCheck(spec => {
const finding: WaveFinding = { spec, check: { name: spec.id, status: 'warn', message: 'stale atoms', details: { count: 3 } }, state: 'finding' };
const line = bannerFindingLine(finding);
expect(line).toBe('[AGENT] fixture_stale_atoms: 3 (explicit_kind_required; preview with: gbrain repair stale-atoms)');
expect(line).not.toContain('--apply');
expect(classifyWaveFindings([finding], [finding], {})).toEqual([{ check_id: spec.id, message: 'stale atoms', class: 'explicit_kind_required',
repair_kind: 'stale-atoms', command: 'gbrain repair stale-atoms' }]);
}));
});