Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* memory_writeback doctor check (WP6): quiet-ok when off (opt-in convention),
* full resolution report when on (mode/TTL/both visibilities/audience),
* receipt-vs-probe-vs-drift for the harness instruction blocks (OV-A3),
* override-file detection (OV-A4), and honest counter labels (OV-A11).
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { buildMemoryWritebackCheck } from '../src/commands/doctor/checks/memory-writeback.ts';
import {
installAmbientWritebackBlockAt,
renderAmbientInstructionBlock,
} from '../src/core/bootstrap/instructions-block.ts';
import { withEnv } from './helpers/with-env.ts';
import { writeHeartbeat, type HookHeartbeatEntry } from '../src/core/context/hook-heartbeat.ts';
let engine: PGLiteEngine;
let tmp: string;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
}, 120_000);
afterAll(async () => {
await engine.disconnect();
});
beforeEach(async () => {
tmp = mkdtempSync(join(tmpdir(), 'gb-docwb-'));
await engine.unsetConfig('memory.auto_writeback');
await engine.unsetConfig('memory.auto_writeback_transient_ttl');
await engine.unsetConfig('facts.default_visibility');
await engine.unsetConfig('brain.audience');
});
/** The realistic post-CLI state: `gbrain config set memory.*` dual-writes
* DB + file mirror. Tests that set the DB plane directly must mirror it, or
* the check's plane-drift compare (correctly) warns. */
function writeFileMirror(home: string, memory: Record<string, string>): void {
const dir = join(home, '.gbrain');
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, 'config.json'), JSON.stringify({ engine: 'pglite', memory }) + '\n');
}
function writeReceipt(home: string, targetPath: string, url = 'http://127.0.0.1:19999'): void {
const dir = join(home, '.gbrain', 'bootstrap');
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, 'harness.json'), JSON.stringify({
harness_receipt_version: 1,
created_at: new Date().toISOString(),
created_by: 'test',
url,
source_id: 'default',
token: { name: 'test-token', minted: false },
targets: [
{ host: 'codex', kind: 'instructions', state: 'confirmed', scope: 'user', path: targetPath, mechanism: 'managed-block' },
],
}) + '\n');
}
describe('memory_writeback doctor check', () => {
test('off (default) → quiet ok naming the enable command; audience and postures still reported', async () => {
await withEnv({ GBRAIN_HOME: tmp }, async () => {
const c = await buildMemoryWritebackCheck(engine);
expect(c.status).toBe('ok');
expect(c.message).toContain('off (default)');
expect(c.message).toContain('gbrain config set memory.auto_writeback salient');
expect(c.details).toMatchObject({
mode: 'off', mode_valid: true, instruction_visibility: 'world', backstop_visibility: 'private',
});
});
});
test('unrecognized mode → warn with the fix; garbage never enables', async () => {
await engine.setConfig('memory.auto_writeback', 'always');
await withEnv({ GBRAIN_HOME: tmp }, async () => {
const c = await buildMemoryWritebackCheck(engine);
expect(c.status).toBe('warn');
expect(c.message).toContain("'always' is unrecognized");
});
});
test('enabled → ok with resolved bundle + BOTH visibility postures + audience reasons + counter honesty note', async () => {
await engine.setConfig('memory.auto_writeback', 'salient');
await engine.setConfig('memory.auto_writeback_transient_ttl', '12h');
await engine.setConfig('facts.default_visibility', 'private');
writeFileMirror(tmp, { auto_writeback: 'salient', auto_writeback_transient_ttl: '12h' });
await withEnv({ GBRAIN_HOME: tmp }, async () => {
const c = await buildMemoryWritebackCheck(engine);
expect(c.status).toBe('ok');
expect(c.details).toMatchObject({
mode: 'salient',
transient_ttl: '12h',
instruction_visibility: 'private',
backstop_visibility: 'private',
audience: 'personal',
});
expect(String(c.details?.counters_note)).toContain('never a source of truth');
expect(Array.isArray(c.details?.audience_reasons)).toBe(true);
});
});
test('#5671 explicit private default + HTTP harness receipt → warn naming the remote read-back consequence (on and off)', async () => {
await engine.setConfig('facts.default_visibility', 'private');
const agents = join(tmp, 'codex-home', 'AGENTS.md');
writeReceipt(tmp, agents);
await withEnv({ GBRAIN_HOME: tmp, CODEX_HOME: join(tmp, 'codex-home') }, async () => {
const off = await buildMemoryWritebackCheck(engine);
expect(off.status).toBe('warn');
expect(off.message).toContain('facts.default_visibility is private but this brain is read remotely');
expect(off.message).toContain('bootstrap harness (HTTP MCP at http://127.0.0.1:19999)');
expect(off.message).toContain('gbrain config set facts.default_visibility world');
expect(off.details?.private_default_remote_readers).toEqual(['bootstrap harness (HTTP MCP at http://127.0.0.1:19999)']);
await engine.setConfig('memory.auto_writeback', 'salient');
writeFileMirror(tmp, { auto_writeback: 'salient', visibility_posture: 'private' });
const on = await buildMemoryWritebackCheck(engine);
expect(on.status).toBe('warn');
expect(on.message).toContain('facts.default_visibility is private but this brain is read remotely');
});
});
test('#5671 a declared shared brain keeps private-for-remote quietly (intended posture); world never warns', async () => {
await engine.setConfig('facts.default_visibility', 'private');
await engine.setConfig('brain.audience', 'shared');
writeReceipt(tmp, join(tmp, 'codex-home', 'AGENTS.md'));
await withEnv({ GBRAIN_HOME: tmp, CODEX_HOME: join(tmp, 'codex-home') }, async () => {
const shared = await buildMemoryWritebackCheck(engine);
expect(shared.status).toBe('ok');
await engine.unsetConfig('brain.audience');
await engine.setConfig('facts.default_visibility', 'world');
const world = await buildMemoryWritebackCheck(engine);
expect(world.status).toBe('ok');
expect(world.message).not.toContain('read remotely');
});
});
test('instruction block: current → ok probe; config change → drift warn naming the re-run (OV-A3)', async () => {
await engine.setConfig('memory.auto_writeback', 'salient');
writeFileMirror(tmp, { auto_writeback: 'salient' });
const agents = join(tmp, 'codex-home', 'AGENTS.md');
mkdirSync(join(tmp, 'codex-home'), { recursive: true });
const url = 'http://127.0.0.1:19999';
writeReceipt(tmp, agents, url);
installAmbientWritebackBlockAt(agents, renderAmbientInstructionBlock({
mode: 'salient', transientTtl: '3d', visibility: 'world', serveUrl: url,
}));
await withEnv({ GBRAIN_HOME: tmp, CODEX_HOME: join(tmp, 'codex-home') }, async () => {
const current = await buildMemoryWritebackCheck(engine);
expect(current.status).toBe('ok');
const blocks = current.details?.instruction_blocks as Array<{ probe: string }>;
expect(blocks?.[0]?.probe).toBe('current');
// Flip the TTL → the installed block is stale → drift warn.
await engine.setConfig('memory.auto_writeback_transient_ttl', '12h');
const drifted = await buildMemoryWritebackCheck(engine);
expect(drifted.status).toBe('warn');
expect(drifted.message).toContain('stale');
expect(drifted.message).toContain('bootstrap harness');
});
});
test('AGENTS.override.md present → warn: the codex block is dead (OV-A4)', async () => {
await engine.setConfig('memory.auto_writeback', 'salient');
const codexHome = join(tmp, 'codex-home');
mkdirSync(codexHome, { recursive: true });
const agents = join(codexHome, 'AGENTS.md');
const url = 'http://127.0.0.1:19999';
writeReceipt(tmp, agents, url);
installAmbientWritebackBlockAt(agents, renderAmbientInstructionBlock({
mode: 'salient', transientTtl: '3d', visibility: 'world', serveUrl: url,
}));
writeFileSync(join(codexHome, 'AGENTS.override.md'), '# my override\n');
await withEnv({ GBRAIN_HOME: tmp, CODEX_HOME: codexHome }, async () => {
const c = await buildMemoryWritebackCheck(engine);
expect(c.status).toBe('warn');
expect(c.message).toContain('AGENTS.override.md');
});
});
test('engine-free run (null engine) → honest file-mirror report, never a throw', async () => {
await withEnv({ GBRAIN_HOME: tmp }, async () => {
const c = await buildMemoryWritebackCheck(null);
expect(c.status).toBe('ok');
expect(c.details?.plane).toBe('file-mirror-only');
});
});
test('plane drift (DB on, file mirror silent) → warn naming the re-sync — the Stop hook reads the wrong truth', async () => {
await engine.setConfig('memory.auto_writeback', 'salient');
// No file mirror written: the state a failed dual-write (or a `config
// set` on ANOTHER machine of a shared Postgres brain) leaves behind.
await withEnv({ GBRAIN_HOME: tmp }, async () => {
const c = await buildMemoryWritebackCheck(engine);
expect(c.status).toBe('warn');
expect(c.message).toContain('file mirror');
expect(c.message).toContain('gbrain config set memory.auto_writeback salient');
expect(c.details?.file_mirror_mode).toBe('(unset)');
});
});
test('a FAILED receipt target warns even when the live probe looks current — the smoke-rollback strip-failure survivor (codex re-review)', async () => {
await engine.setConfig('memory.auto_writeback', 'salient');
writeFileMirror(tmp, { auto_writeback: 'salient' });
const codexHome = join(tmp, 'codex-home');
mkdirSync(codexHome, { recursive: true });
const agents = join(codexHome, 'AGENTS.md');
const url = 'http://127.0.0.1:19999';
// Receipt records the target FAILED (strip threw during smoke rollback)
// while the block itself still sits on disk looking perfectly current.
const dir = join(tmp, '.gbrain', 'bootstrap');
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, 'harness.json'), JSON.stringify({
harness_receipt_version: 1,
created_at: new Date().toISOString(),
created_by: 'test',
url,
source_id: 'default',
token: { name: 'test-token', minted: false },
targets: [
{ host: 'codex', kind: 'instructions', state: 'failed', scope: 'user', path: agents, mechanism: 'managed-block', error: 'smoke failed and the instruction block could not be removed — run `gbrain bootstrap harness --remove` to converge' },
],
}) + '\n');
installAmbientWritebackBlockAt(agents, renderAmbientInstructionBlock({
mode: 'salient', transientTtl: '3d', visibility: 'world', serveUrl: url,
}));
await withEnv({ GBRAIN_HOME: tmp, CODEX_HOME: codexHome }, async () => {
const c = await buildMemoryWritebackCheck(engine);
expect(c.status).toBe('warn');
expect(c.message).toContain('previously FAILED');
expect(c.message).toContain('bootstrap harness');
});
});
test('off but an instruction block is still installed → warn naming the converge command (red-team review)', async () => {
// memory.auto_writeback unset everywhere = off. The lingering block means
// every NEW session is still instructed to save via remember — the off
// switch is incomplete until converged, and doctor must say so instead of
// early-returning a healthy "off (default)".
const codexHome = join(tmp, 'codex-home');
mkdirSync(codexHome, { recursive: true });
const agents = join(codexHome, 'AGENTS.md');
const url = 'http://127.0.0.1:19999';
writeReceipt(tmp, agents, url);
installAmbientWritebackBlockAt(agents, renderAmbientInstructionBlock({
mode: 'salient', transientTtl: '3d', visibility: 'world', serveUrl: url,
}));
await withEnv({ GBRAIN_HOME: tmp, CODEX_HOME: codexHome, CLAUDE_CONFIG_DIR: join(tmp, 'claude-cfg') }, async () => {
const c = await buildMemoryWritebackCheck(engine);
expect(c.status).toBe('warn');
expect(c.message).toContain('still installed');
expect(c.message).toContain('bootstrap harness --yes');
expect(Array.isArray(c.details?.lingering_instruction_blocks)).toBe(true);
});
});
// #5557: a share of failed serve-side harvests is visible, not a silent counter.
const harvestCases: Array<{ name: string; ok: number; errors: string[]; requeued: number; warn: string | null }> = [
{
name: 'mostly failed harvests warn with the top error reason',
ok: 8,
errors: [...Array(10).fill('operationerror:writer_lock_unavailable'), 'aitransienterror', 'aitransienterror'],
requeued: 3,
warn: '12/20 writeback harvests failed in 7d (top: operationerror:writer_lock_unavailable x10)',
},
{ name: 'a small failure share stays ok', ok: 18, errors: ['operationerror:writer_lock_unavailable', 'aborterror'], requeued: 5, warn: null },
{ name: 'exactly 20% failed stays ok', ok: 8, errors: ['operationerror:writer_lock_unavailable', 'aborterror'], requeued: 0, warn: null },
{
name: 'exactly 10 finished harvests is enough to judge',
ok: 7,
errors: ['operationerror:writer_lock_unavailable', 'operationerror:writer_lock_unavailable', 'aborterror'],
requeued: 0,
warn: '3/10 writeback harvests failed in 7d (top: operationerror:writer_lock_unavailable x2)',
},
{ name: 'too few harvests to judge stays ok', ok: 1, errors: ['operationerror:writer_lock_unavailable', 'aborterror'], requeued: 0, warn: null },
];
for (const c of harvestCases) {
test(`#5557 harvest failures: ${c.name}`, async () => {
await engine.setConfig('memory.auto_writeback', 'salient');
writeFileMirror(tmp, { auto_writeback: 'salient' });
await withEnv({ GBRAIN_HOME: tmp }, async () => {
const ts = new Date().toISOString();
const entries: HookHeartbeatEntry[] = [
...Array.from({ length: c.ok }, (): HookHeartbeatEntry => ({ ts, event: 'writeback', outcome: 'ok', duration_ms: 5000, inserted: 1 })),
...c.errors.map((reason): HookHeartbeatEntry => ({ ts, event: 'writeback', outcome: 'error', reason, duration_ms: 1000 })),
...Array.from({ length: c.requeued }, (): HookHeartbeatEntry => ({ ts, event: 'writeback', outcome: 'degraded', reason: 'writer_busy_requeued', duration_ms: 1000 })),
];
for (const entry of entries) await writeHeartbeat(entry, { trim: false });
const check = await buildMemoryWritebackCheck(engine);
expect(check.details?.backstop_7d).toMatchObject({ failed: c.errors.length, last_ok_at: ts });
if (c.warn) {
expect(check.status).toBe('warn');
expect(check.message).toContain(c.warn);
expect(check.message).toContain('gbrain sweep --once');
} else {
expect(check.status).toBe('ok');
}
});
});
}
});
describe('memory_writeback doctor check: capture-lane notices (#6268, #6316)', () => {
test('#6268 a held session file (source never resolved) → warn naming --assign-corpus preview then --apply; the default-off path reports it too', async () => {
const spool = join(tmp, '.gbrain', 'transcripts', 'corpus', 'sourced');
mkdirSync(spool, { recursive: true });
writeFileSync(join(spool, 'sess-held.src-_unresolved.txt'), 'USER: hi\n');
await withEnv({ GBRAIN_HOME: tmp }, async () => {
const off = await buildMemoryWritebackCheck(engine);
expect(off.status).toBe('warn');
expect(off.details?.corpus_source_holds).toEqual({ legacy_unstamped: 0, unresolved: 1, sessions: 1 });
expect(off.message).toContain('gbrain sweep --assign-corpus <source>');
expect(off.message).toContain('--apply');
await engine.setConfig('memory.auto_writeback', 'off');
writeFileMirror(tmp, { auto_writeback: 'off' });
expect((await buildMemoryWritebackCheck(engine)).message).not.toContain('--assign-corpus');
});
});
test('#6316 OpenClaw compactions that never banked → warn with the top skip; one banked compaction clears it', async () => {
await engine.setConfig('memory.auto_writeback', 'salient');
writeFileMirror(tmp, { auto_writeback: 'salient' });
await withEnv({ GBRAIN_HOME: tmp }, async () => {
const ts = new Date().toISOString();
for (let i = 0; i < 2; i++) await writeHeartbeat({ ts, event: 'openclaw-compact', outcome: 'degraded', reason: 'no_session', segment: 'skipped', duration_ms: 1 }, { trim: false });
const dead = await buildMemoryWritebackCheck(engine);
expect(dead.status).toBe('warn');
expect(dead.details?.openclaw_compactions_7d).toEqual({ total: 2, banked: 0, skipped: { no_session: 2 } });
expect(dead.message).toContain('banked none (top skip: no_session x2)');
await writeHeartbeat({ ts, event: 'openclaw-compact', outcome: 'ok', segment: 'banked', duration_ms: 1 }, { trim: false });
const live = await buildMemoryWritebackCheck(engine);
expect(live.message).not.toContain('banked none');
expect(live.details?.openclaw_compactions_7d).toMatchObject({ total: 3, banked: 1 });
});
});
});