Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Lane H1a (Tier 1): the deterministic keyless agent journey, end to end.
*
* An agent with no provider keys, no TTY, and stdin either closed
* (`</dev/null`) or an open pipe that never writes, drives the real CLI and
* real stdio MCP sessions under hard timeouts:
*
* init --pglite --no-embedding --json one document carrying the first-run decision bundle
* doctor --json day zero: 0 WARN/FAIL, health >= 90, capped_by
* import <dir> --no-embed --json 3 pages, one document
* doctor --remediate (no authorization) exit 3, consent payload, nothing mutated
* (also on a pending-migration brain: schema version unchanged)
* the user agrees → the fix argv verbatim → remediation runs, migrations apply after consent
* serve --surface verbs remember/recall, degraded notice as a separate prefixed
* block + _meta.gbrain_notices, caller mistake → one-block
* envelope whose fix runs; a second serve on the locked brain
* completes the handshake in status-only mode naming the owner
* serve --surface full search with the degraded notice, list_pages caller mistake → fix
* doctor --json health >= 90 with capped_by
*
* Machine timings (init, initialize, first remember, first recall) are printed
* and written to .context/agent-journey-timings.json for Lane I.
*
* Existing lane tests cover the pieces in isolation (cli-json-guard D2 init,
* doctor-day-zero E2, doctor-remediate-consent C1, observational-startup A4,
* mcp-notice-channels F3, serve-status-mode F4); this file proves they compose
* into one working journey through the real binary. Wire goldens:
* test/fixtures/agent-contract/v1/journey/ (transcripts in AGENT_OPERATOR_v1.md).
*
* Serial: real subprocesses and PGLite datastores in temp homes.
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { LATEST_VERSION, hasPendingMigrations } from '../src/core/migrate.ts';
import { withCoordinatedWrite } from '../src/core/persistence/context.ts';
import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';
import { snapshotBrain, type BrainSnapshot } from './helpers/fresh-brain-snapshot.ts';
import {
REPO, body, call, expectOneBlockError, gb, journeyGolden, mcp, noticeBlocks, oneDocument, NOTICE_PREFIX,
type McpSession, type StdinMode,
} from './helpers/agent-journey.ts';
const MARKER = 'quokka-journey-marker';
const PAGES = 3;
const timings: Record<string, number> = {};
/** The background onboarding refresh races these calls; test/mcp-onboarding.test.ts owns those notices, this journey pins the degraded one. */
const QUIET_ONBOARDING = { GBRAIN_NO_ONBOARD_NUDGE: '1' };
function brainPath(home: string): string { return join(home, '.gbrain', 'brain.pglite'); }
async function withBrain<T>(home: string, fn: (engine: PGLiteEngine) => Promise<T>): Promise<T> {
const engine = new PGLiteEngine();
await engine.connect({ engine: 'pglite', database_path: brainPath(home) });
try { return await fn(engine); } finally { await engine.disconnect(); }
}
/** Brain state an unauthorized run must leave alone. The agent-contract event log (E11) and audit trail record the refusal by design. */
async function brainState(home: string): Promise<BrainSnapshot> {
const snap = await snapshotBrain(home, brainPath(home));
for (const key of Object.keys(snap.files)) {
if (/(^|\/)\.gbrain\/(agent-contract|audit)(\/|$)/.test(key)) delete snap.files[key];
}
return snap;
}
function writeNotes(home: string): string {
const dir = join(home, 'notes');
mkdirSync(dir, { recursive: true });
for (let i = 1; i <= PAGES; i++) {
writeFileSync(join(dir, `journey-note-${i}.md`), `---\ntitle: Journey note ${i}\n---\n\n# Journey note ${i}\n\nThe ${MARKER} ${i} lives in note ${i}.\n`);
}
return dir;
}
/** A repairable finding a real legacy brain carries: a timeline row that exists only in the database. */
async function seedRepairableFinding(home: string): Promise<void> {
await withBrain(home, engine => engine.transaction(tx => withCoordinatedWrite(tx, ['default'], () => tx.executeRaw(
`INSERT INTO timeline_entries(page_id,date,source,summary,detail)
SELECT id,'2026-07-01','legacy','A database-only event','' FROM pages WHERE source_id='default' AND slug='journey-note-1'`),
TEST_WRITE_ATTRIBUTION)));
}
interface DoctorReport { status: string; health_score: number; capped_by?: string[]; checks: Array<{ name: string; status: string; message: string; fix?: { argv?: string[]; next?: string }; fix_unavailable_reason?: string }> }
function expectHealthy(report: DoctorReport, label: string): void {
expect(report.health_score, `${label}: health_score`).toBeGreaterThanOrEqual(90);
expect(report.capped_by, `${label}: capped_by names the keyless choice`).toEqual(['embeddings_disabled']);
const fails = report.checks.filter(c => c.status === 'fail').map(c => `${c.name}: ${c.message}`);
expect(fails, `${label}: no FAIL`).toEqual([]);
const unfixable = report.checks.filter(c => c.status === 'warn' && !c.fix?.argv).map(c => `${c.name}: ${c.message} (${c.fix_unavailable_reason})`);
expect(unfixable, `${label}: every WARN carries an executable fix`).toEqual([]);
}
for (const stdin of ['devnull', 'silent'] as StdinMode[]) {
describe(`H1a keyless CLI journey, stdin ${stdin === 'devnull' ? '</dev/null' : 'an open silent pipe'}`, () => {
let home = '';
const cli = (args: string[], timeoutMs = 120_000) => gb(home, args, { stdin, timeoutMs });
beforeAll(() => { home = mkdtempSync(join(tmpdir(), `gbrain-journey-${stdin}-`)); });
afterAll(() => { rmSync(home, { recursive: true, force: true }); });
test('init --pglite --no-embedding --json: one document with the first-run decision bundle', async () => {
const r = await cli(['init', '--pglite', '--no-embedding', '--json']);
expect(r.exitCode, r.stderr).toBe(0);
if (stdin === 'devnull') timings.init_ms = r.ms;
const doc = oneDocument(r, 'init --json');
expect(doc).toMatchObject({ status: 'success', engine: 'pglite', contract_version: 1 });
const bundles = (doc.notices as Array<Record<string, any>>).filter(n => n.code === 'first_run_decisions');
expect(bundles).toHaveLength(1);
const bundle = bundles[0]!;
expect(bundle).toMatchObject({ kind: 'ask', contract_version: 1 });
expect(bundle.user_message).toContain('Nothing needs an answer now');
expect(bundle.decisions.map((d: { id: string }) => d.id)).toContain('search_mode');
expect(bundle.decisions.map((d: { id: string }) => d.id)).not.toContain('harness_wiring');
expect((doc.notices as Array<Record<string, any>>).find(n => n.code === 'harness_wiring')).toMatchObject({ kind: 'info', fix: { actor: 'user', next: 'report' } });
for (const d of bundle.decisions) {
expect(d.options.map((o: { id: string }) => o.id), `${d.id}: default is an option`).toContain(d.default);
expect(d.default_reason, `${d.id}: default_reason`).toBeTruthy();
}
// No fabricated user fact: the brain holds no pages and no facts after init.
await withBrain(home, async engine => {
expect((await engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM pages'))[0]!.n).toBe(0);
expect((await engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM facts'))[0]!.n).toBe(0);
});
if (stdin === 'devnull') journeyGolden('init-first-run.json', doc, { home });
}, 150_000);
test('day-zero doctor --json: 0 WARN, 0 FAIL, health >= 90, capped_by', async () => {
const r = await cli(['doctor', '--json']);
expect(r.exitCode, r.stderr).toBe(0);
const report = oneDocument(r, 'doctor --json') as DoctorReport;
expect(report.checks.filter(c => c.status !== 'ok').map(c => `${c.status} ${c.name}: ${c.message}`)).toEqual([]);
expectHealthy(report, 'day zero');
}, 150_000);
test('day-zero doctor --remediate: nothing to do, nothing changed', async () => {
const before = await brainState(home);
const r = await cli(['doctor', '--remediate', '--json']);
expect(r.exitCode, r.stderr).toBe(0);
expect(oneDocument(r, 'doctor --remediate --json')).toMatchObject({ healthy: true, submitted: [], repairs_completed: 0 });
expect(await brainState(home)).toEqual(before);
}, 150_000);
test(`import ${PAGES} pages --no-embed --json: one document`, async () => {
const r = await cli(['import', writeNotes(home), '--no-embed', '--json']);
expect(r.exitCode, r.stderr).toBe(0);
expect(oneDocument(r, 'import --json')).toMatchObject({ status: 'success', imported: PAGES, errors: 0 });
}, 150_000);
test('doctor --remediate without authorization: exit 3, the consent payload, nothing mutated', async () => {
await seedRepairableFinding(home);
const before = await brainState(home);
const r = await cli(['doctor', '--remediate', '--include-repairs', '--json']);
expect(r.exitCode, r.stderr).toBe(3);
const payload = oneDocument(r, 'doctor --remediate --json (refused)');
expect(payload).toMatchObject({
status: 'confirmation_required', error: 'confirmation_required', code: 'confirmation_required',
effects: ['paid', 'destructive'], actor: 'agent', contract_version: 1,
});
expect(payload.fix.next).toBe('ask_user');
expect(payload.fix.argv.slice(0, 3)).toEqual(['gbrain', 'doctor', '--remediate']);
expect(payload.fix.argv).toEqual(expect.arrayContaining(['--yes', '--expect', payload.plan_hash]));
expect(payload.user_message).toBeTruthy();
expect(await brainState(home)).toEqual(before);
// Human output on a non-TTY: the [AGENT] block with a fenced [SHOW USER] relay, still nothing changed.
const human = await cli(['doctor', '--remediate', '--include-repairs']);
expect(human.exitCode).toBe(3);
expect(human.stdout).toContain('[AGENT]');
expect(human.stdout).toContain('[SHOW USER]');
expect(await brainState(home)).toEqual(before);
}, 200_000);
test('pending-migration brain: the refusal leaves the schema version unchanged; the approved fix migrates after consent', async () => {
const pending = String(LATEST_VERSION - 1);
await withBrain(home, engine => engine.setConfig('version', pending));
const r = await cli(['doctor', '--remediate', '--include-repairs', '--json']);
expect(r.exitCode, r.stderr).toBe(3);
const payload = oneDocument(r, 'doctor --remediate --json (pending migration)');
expect(payload.code).toBe('confirmation_required');
await withBrain(home, async engine => {
expect(await engine.getConfig('version')).toBe(pending);
expect(await hasPendingMigrations(engine)).toBe(true);
});
// The user agreed: the agent runs fix.argv exactly as given.
const fixArgv = payload.fix.argv as string[];
expect(fixArgv[0]).toBe('gbrain');
const approved = await cli(fixArgv.slice(1), 240_000);
expect(approved.exitCode, approved.stderr.slice(-3000)).toBe(0);
const result = oneDocument(approved, 'approved doctor --remediate');
expect(result.repairs_completed).toBe(1);
await withBrain(home, async engine => {
expect(await engine.getConfig('version')).toBe(String(LATEST_VERSION));
});
const verify = await cli(['doctor', '--only', 'timeline_history', '--json']);
expect(verify.exitCode, verify.stderr).toBe(0);
const check = (oneDocument(verify, 'doctor --only timeline_history').checks as DoctorReport['checks']).find(c => c.name === 'timeline_history');
expect(check?.status).toBe('ok');
}, 300_000);
test('after import and remediation: doctor --json health >= 90 with capped_by; every WARN has a fix', async () => {
const r = await cli(['doctor', '--json']);
expect(r.exitCode, r.stderr).toBe(0);
expectHealthy(oneDocument(r, 'doctor --json (after import)') as DoctorReport, 'after import');
}, 150_000);
});
}
describe('H1a keyless MCP journey (stdio)', () => {
let home = '';
const open: McpSession[] = [];
beforeAll(async () => {
home = mkdtempSync(join(tmpdir(), 'gbrain-journey-mcp-'));
expect((await gb(home, ['init', '--pglite', '--no-embedding', '--json'], { timeoutMs: 120_000 })).exitCode).toBe(0);
expect((await gb(home, ['import', writeNotes(home), '--no-embed', '--json'], { timeoutMs: 120_000 })).exitCode).toBe(0);
}, 300_000);
afterAll(async () => {
for (const s of open) await s.close();
rmSync(home, { recursive: true, force: true });
try {
mkdirSync(join(REPO, '.context'), { recursive: true });
writeFileSync(join(REPO, '.context', 'agent-journey-timings.json'), `${JSON.stringify({ recorded_at: new Date().toISOString(), ...timings }, null, 2)}\n`);
} catch { /* timings are informational */ }
console.log(`[agent-journey] machine timings (ms): ${JSON.stringify(timings)}`);
});
test('surface verbs: remember/recall, the degraded notice block, a caller mistake with a runnable fix, status-only second serve', async () => {
const verbs = await mcp(home, ['--surface', 'verbs'], { env: QUIET_ONBOARDING });
open.push(verbs);
timings.initialize_ms = verbs.initMs;
const tools = (await verbs.client.listTools()).tools.map(t => t.name);
expect(tools).toEqual(expect.arrayContaining(['remember', 'recall', 'forget']));
expect(tools).not.toContain('get_health');
expect(verbs.client.getInstructions()).toContain('recall');
let t0 = performance.now();
const remembered = await call(verbs, 'remember', { fact: `${MARKER} is the install-check fact`, provenance: 'install-check' });
timings.first_remember_ms = Math.round(performance.now() - t0);
expect(remembered.isError, JSON.stringify(remembered).slice(0, 1000)).toBeFalsy();
t0 = performance.now();
const recalled = await call(verbs, 'recall', { query: MARKER });
timings.first_recall_ms = Math.round(performance.now() - t0);
expect(recalled.isError).toBeFalsy();
const text0 = recalled.content[0].text;
expect(text0.startsWith(NOTICE_PREFIX)).toBe(false);
const result = body(recalled);
expect(JSON.stringify(result)).toContain(MARKER);
// The imported pages, plus memory/unattributed: a fact remembered without an entity is a row of its fence (GBRA-190 G4).
expect(result.results.length).toBe(PAGES + 1);
// The degraded notice is its own prefixed block (the model sees it) and mirrored in _meta.
// A recall that passes only `query` also carries the recall_hint (TC7) naming `question`.
const blocks = noticeBlocks(recalled);
expect(blocks.map(b => b.split('\n')[0])).toEqual(['[gbrain notice degraded_recall kind=degraded]', '[gbrain notice recall_hint kind=info]']);
expect(blocks[0]).toContain('never as "the brain has nothing on this"');
expect(recalled._meta?.gbrain_notices?.map((n: { code: string }) => n.code)).toEqual(['degraded_recall', 'recall_hint']);
expect(result.facts_order).toBe('newest');
journeyGolden('recall-degraded.json', recalled, { home });
// Caller mistake: one block, an envelope with a fix the agent runs as given.
const mistake = await call(verbs, 'recall', { query: MARKER, limit: 'abc' });
const env = expectOneBlockError(mistake, 'recall limit:"abc"');
expect(env).toMatchObject({ error: 'invalid_params', code: 'invalid_params', class: 'caller', retryable: false });
expect(env.fix.next).toBe('run');
expect(env.fix.mcp).toEqual({ tool: 'recall', arguments: { query: MARKER, limit: 10 } });
expect(env.suggestion).toContain('recall');
journeyGolden('caller-mistake.json', mistake, { home });
const fixed = await call(verbs, env.fix.mcp.tool, env.fix.mcp.arguments);
expect(fixed.isError).toBeFalsy();
expect(JSON.stringify(body(fixed))).toContain(MARKER);
// F4: a second serve on the locked brain completes the handshake with gbrain_status naming the owner.
const second = await mcp(home, []);
open.push(second);
expect(second.client.getInstructions()).toContain('STATUS-ONLY MODE');
expect((await second.client.listTools()).tools.map(t => t.name)).toEqual(['gbrain_status']);
const statusResult = await call(second, 'gbrain_status');
const status = body(statusResult);
expect(status).toMatchObject({ status: 'unavailable', reason: 'lock_held' });
expect(status.lock_owner).toMatchObject({ pid: verbs.pid, transport: 'stdio' });
expect(status.why).toContain(`PID ${verbs.pid}`);
expect(status.fix.next).toBe('tell_user_to_run');
expect(status.user_message).toBeTruthy();
journeyGolden('status-only-lock-held.json', statusResult, { home, pids: [verbs.pid] });
const refused = await call(second, 'recall', { query: MARKER });
expect(expectOneBlockError(refused, 'recall on a status-only serve').code).toBe('serve_status_only');
await second.close();
await verbs.close();
}, 240_000);
test('surface full: search carries the degraded notice; a list_pages caller mistake carries a fix that runs', async () => {
const full = await mcp(home, ['--surface', 'full'], { env: QUIET_ONBOARDING });
open.push(full);
const tools = (await full.client.listTools()).tools.map(t => t.name);
expect(tools).toEqual(expect.arrayContaining(['search', 'query', 'list_pages', 'get_page', 'recall']));
const found = await call(full, 'search', { query: MARKER });
expect(found.isError).toBeFalsy();
expect(Array.isArray(body(found))).toBe(true);
expect(JSON.stringify(body(found))).toContain(MARKER);
expect(noticeBlocks(found).map(b => b.split('\n')[0])).toEqual(['[gbrain notice degraded_recall kind=degraded]']);
expect(found._meta?.gbrain_notices?.[0]?.code).toBe('degraded_recall');
const mistake = await call(full, 'list_pages', { sort: 'bogus', limit: 2 });
const env = expectOneBlockError(mistake, 'list_pages sort:"bogus"');
expect(env.code).toBe('invalid_params');
expect(env.fix).toMatchObject({ next: 'run', mcp: { tool: 'list_pages', arguments: { limit: 2 } } });
const listed = await call(full, env.fix.mcp.tool, env.fix.mcp.arguments);
expect(listed.isError).toBeFalsy();
// A missing required param names the param; there is no value to invent, so no fix.
const missing = expectOneBlockError(await call(full, 'get_page', {}), 'get_page {}');
expect(missing.code).toBe('invalid_params');
expect(missing.message).toContain('slug');
await full.close();
}, 240_000);
test('the brain stays healthy after the MCP session: health >= 90 with capped_by', async () => {
const r = await gb(home, ['doctor', '--json'], { timeoutMs: 120_000 });
expect(r.exitCode).toBe(0);
expectHealthy(oneDocument(r, 'doctor --json (after MCP)') as DoctorReport, 'after MCP');
expect(timings.initialize_ms).toBeLessThan(30_000);
expect(timings.first_recall_ms).toBeLessThan(30_000);
}, 150_000);
});
describe('H2 missing_brain: the configured brain is on a drive that is not mounted', () => {
let home = '';
beforeAll(() => { home = mkdtempSync(join(tmpdir(), 'gbrain-journey-missing-')); });
afterAll(() => { rmSync(home, { recursive: true, force: true }); });
test('serve completes the handshake in status-only mode naming the path; nothing is created there; mounting it recovers in place', async () => {
expect((await gb(home, ['init', '--pglite', '--no-embedding', '--json'])).exitCode).toBe(0);
const offline = join(home, 'offline', 'brain.pglite');
const mounted = join(home, 'mnt', 'external', 'gbrain', 'brain.pglite');
mkdirSync(join(home, 'offline'), { recursive: true });
renameSync(brainPath(home), offline);
const cfgPath = join(home, '.gbrain', 'config.json');
writeFileSync(cfgPath, JSON.stringify({ ...JSON.parse(readFileSync(cfgPath, 'utf8')), database_path: mounted }, null, 2));
const session = await mcp(home, ['--surface', 'verbs']);
try {
expect(session.client.getInstructions()).toContain('STATUS-ONLY MODE');
expect((await session.client.listTools()).tools.map(t => t.name)).toEqual(['gbrain_status']);
const statusResult = await call(session, 'gbrain_status');
const status = body(statusResult);
expect(status).toMatchObject({ status: 'unavailable', reason: 'missing_brain', brain_path: mounted });
expect(status.why).toContain(mounted);
expect(status.fix.next).toBe('tell_user_to_run');
expect(status.decisions[0].options.map((o: { id: string }) => o.id)).toEqual(['reconnect', 'new_brain']);
expect(status.decisions[0].options[1].argv).toEqual(['gbrain', 'init', '--pglite', '--no-embedding', '--path', mounted]);
journeyGolden('status-only-missing-brain.json', statusResult, { home });
expect(existsSync(join(home, 'mnt'))).toBe(false);
// The drive comes back: the next gbrain_status call opens the brain in place.
mkdirSync(join(home, 'mnt', 'external', 'gbrain'), { recursive: true });
renameSync(offline, mounted);
let recovered = false;
for (let i = 0; i < 40 && !recovered; i++) {
recovered = body(await call(session, 'gbrain_status')).status === 'recovered';
if (!recovered) await new Promise(r => setTimeout(r, 500));
}
expect(recovered).toBe(true);
} finally {
await session.close();
}
}, 180_000);
});