Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #6693 (D7): a remember onto a page whose canonical file holds a committed Git change managed sync has not imported
* yet (another agent's commit) is refused `pending_import`, kept, and replayed once by the sync that imports the file.
* Managed PGLite brain with a durable Git repo, no providers.
*/
import { describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import type { OperationContext } from '../src/core/ops/contract.ts';
import { performSync } from '../src/commands/sync.ts';
import { parseFactsFence } from '../src/core/facts-fence.ts';
import { readWriterDiagnostics } from '../src/core/persistence/diagnostics.ts';
import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';
import { submitRememberMutation } from '../src/core/persistence/memory-mutations.ts';
import { lostCallerWrites, replayImportedRemembers } from '../src/core/repair/failed-writes.ts';
import { pendingImportRefusal } from '../src/core/persistence/pending-import.ts';
import { readDrainHolder, withDrainLease } from '../src/core/persistence/sync-lease.ts';
import { PENDING_IMPORT_MESSAGE, runMemoryWrite, writeFailureDiagnostic } from '../src/core/persistence/verb-errors.ts';
import type { SyncResult } from '../src/commands/sync.ts';
import { managedBrain } from './helpers/managed-brain.ts';
import { durableGitRepo, git } from './helpers/git-publication.ts';
const slug = 'people/owner-example';
const setup = ({ root }: { root: string }) => { writeFileSync(join(root, '.gitignore'), '\n'); durableGitRepo(root, ['.gitignore']); };
const file = (root: string) => join(root, `${slug}.md`);
const edit = (root: string, line: string) => writeFileSync(file(root), readFileSync(file(root), 'utf8').replace('Body.', `Body.\n\n${line}`));
async function seed(ctx: OperationContext) {
await submitPageMutation(ctx, { operation: 'put_page', params: { slug, request_id: randomUUID(),
content: '---\ntype: person\ntitle: Owner\n---\n\nBody.\n' } });
}
async function refused(run: () => Promise<unknown>) {
try { await run(); } catch (error) { return error as { code?: string; reason?: string; message?: string; fix?: { actor?: string; argv?: string[] } }; }
throw new Error('the write was expected to be refused');
}
const lastReceipt = async (engine: BrainEngine, operation: string) => (await engine.executeRaw<{ state: string; error_code: string; error_detail: { origin?: string } | null }>(
'SELECT state,error_code,error_detail FROM persistence_requests WHERE operation=$1 ORDER BY sequence DESC LIMIT 1', [operation]))[0];
const sync = (engine: BrainEngine, root: string) => performSync(engine, { repoPath: root, sourceId: 'default', noPull: true, noEmbed: true, noExtract: true, concurrency: 1 });
const claims = async (engine: BrainEngine) => (await engine.executeRaw<{ fact: string; row_num: number | null }>(
"SELECT fact,row_num FROM facts WHERE source_id='default' AND entity_slug=$1 AND expired_at IS NULL ORDER BY id", [slug]));
describe('#6693 remember onto a page whose file awaits import', () => {
test('is refused pending_import, kept, and replayed once by the sync that imports the file', () => managedBrain(async ({ engine, ctx, root }) => {
await seed(ctx);
edit(root, 'Another agent added this line through Git.');
git(root, 'add', '--', `${slug}.md`); git(root, 'commit', '-q', '-m', 'agent commit not yet imported');
const error = await refused(() => submitRememberMutation(ctx, { fact: 'Owner prefers async updates', entity: slug, provenance: 'test', visibility: 'world',
valid_from: '2026-09-01T00:00:00.000Z' }));
expect(error.code).toBe('source_changed');
expect(error.reason).toBe('pending_import');
expect(error.message).toBe('The canonical file holds a committed Git change that sync has not imported yet.');
// A remember waits for its replay: a status read under a provider actor renders `next: wait`.
expect(error.fix?.actor).toBe('provider');
expect(error.fix?.argv).toEqual(['gbrain', 'sync', 'status', '--source', 'default', '--json']);
const receipt = await lastReceipt(engine, 'remember');
expect(receipt.state).toBe('conflict');
expect(receipt.error_detail?.origin).toBe('pending_import');
// Before the import, a direct pass replays nothing and admits nothing.
expect(await replayImportedRemembers(ctx, 'default')).toMatchObject({ examined: 1, replayed: 0, waiting: 1 });
expect((await engine.executeRaw('SELECT 1 FROM persistence_requests WHERE operation=$1', ['remember'])).length).toBe(1);
const result = await sync(engine, root);
expect(result.replayedRemembers).toMatchObject({ examined: 1, replayed: 1, waiting: 0 });
const content = readFileSync(file(root), 'utf8');
expect(content).toContain('Another agent added this line through Git.');
expect(parseFactsFence(content).facts.map(f => [f.claim, f.validFrom])).toEqual([['Owner prefers async updates', '2026-09-01']]);
expect((await claims(engine)).map(row => [row.fact, Number(row.row_num)])).toEqual([['Owner prefers async updates', 1]]);
expect((await lostCallerWrites(engine, ['default'])).lost).toEqual([]);
// The next sync finds the receipt settled and replays nothing again.
expect((await sync(engine, root)).replayedRemembers).toBeUndefined();
expect(await claims(engine)).toHaveLength(1);
}, { setup }), 120_000);
test('two concurrent passes admit one replay', () => managedBrain(async ({ engine, ctx, root }) => {
await seed(ctx);
const original = readFileSync(file(root), 'utf8');
edit(root, 'Committed elsewhere.');
git(root, 'add', '--', `${slug}.md`); git(root, 'commit', '-q', '-m', 'agent commit');
await refused(() => submitRememberMutation(ctx, { fact: 'Owner reads email at noon', entity: slug, provenance: 'test', visibility: 'world' }));
// The other agent takes its change back: the file matches the page again without a sync, so both passes see a replayable write.
writeFileSync(file(root), original);
git(root, 'add', '--', `${slug}.md`); git(root, 'commit', '-q', '-m', 'agent takes it back');
const reports = await Promise.all([replayImportedRemembers(ctx, 'default'), replayImportedRemembers(ctx, 'default')]);
expect(reports.reduce((sum, r) => sum + r.replayed, 0)).toBeGreaterThanOrEqual(1);
expect((await claims(engine)).map(row => row.fact)).toEqual(['Owner reads email at noon']);
expect((await engine.executeRaw("SELECT 1 FROM persistence_requests WHERE operation='remember' AND state='committed'")).length).toBe(1);
}, { setup }), 120_000);
test('a remember refused by a sync-held file is replayed after the repaired file is imported', () => managedBrain(async ({ engine, ctx, root }) => {
await seed(ctx);
writeFileSync(file(root), '---\ntype: person\ntitle: [unclosed\n---\n\nBody.\n');
git(root, 'add', '--', `${slug}.md`); git(root, 'commit', '-q', '-m', 'broken frontmatter');
await sync(engine, root);
const error = await refused(() => submitRememberMutation(ctx, { fact: 'Owner prefers mornings', entity: slug, provenance: 'test', visibility: 'world' }));
expect(error.code).toBe('source_changed');
expect((await lastReceipt(engine, 'remember')).error_detail?.origin).toBe('sync_held');
writeFileSync(file(root), '---\ntype: person\ntitle: Owner\n---\n\nBody.\n\nRepaired.\n');
git(root, 'add', '--', `${slug}.md`); git(root, 'commit', '-q', '-m', 'repair frontmatter');
expect((await sync(engine, root)).replayedRemembers).toMatchObject({ replayed: 1 });
expect((await claims(engine)).map(row => row.fact)).toEqual(['Owner prefers mornings']);
expect(readFileSync(file(root), 'utf8')).toContain('Repaired.');
}, { setup }), 120_000);
test('an uncommitted hand edit keeps the reconcile refusal and is never replayed', () => managedBrain(async ({ engine, ctx, root }) => {
await seed(ctx);
edit(root, 'A hand edit nobody committed.');
const error = await refused(() => submitRememberMutation(ctx, { fact: 'Owner likes tea', entity: slug, provenance: 'test', visibility: 'world' }));
expect(error.code).toBe('source_changed');
expect(error.reason).toBeUndefined();
expect(error.message).toBe('The canonical file contains an uncoordinated local edit.');
expect((await lastReceipt(engine, 'remember')).error_detail?.origin).toBe('file_database_drift');
git(root, 'add', '--', `${slug}.md`); git(root, 'commit', '-q', '-m', 'commit the hand edit later');
expect((await sync(engine, root)).replayedRemembers).toBeUndefined();
expect(await claims(engine)).toEqual([]);
}, { setup }), 120_000);
test('GST-1601: a put_page onto an uncoordinated local edit, or onto a path an unindexed file occupies, records the cause on its receipt', () => managedBrain(async ({ engine, ctx, root }) => {
await seed(ctx);
edit(root, 'A hand edit nobody committed.');
const revision = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!.revision;
const drift = await refused(() => submitPageMutation(ctx, { operation: 'put_page', params: { slug, request_id: randomUUID(), expected_revision: revision,
content: '---\ntype: person\ntitle: Owner\n---\n\nReplaced body.\n' } }));
expect(drift.code).toBe('source_changed');
expect((await lastReceipt(engine, 'put_page')).error_detail?.origin).toBe('file_database_drift');
writeFileSync(join(root, 'people', 'unindexed-example.md'), '---\ntype: person\ntitle: Unindexed\n---\n\nNever imported.\n');
const occupied = await refused(() => submitPageMutation(ctx, { operation: 'put_page', params: { slug: 'people/unindexed-example', request_id: randomUUID(),
content: '---\ntype: person\ntitle: Unindexed\n---\n\nNew page.\n' } }));
expect(occupied.code).toBe('source_changed');
expect((await lastReceipt(engine, 'put_page')).error_detail?.origin).toBe('canonical_path_occupied');
expect(readFileSync(file(root), 'utf8')).toContain('A hand edit nobody committed.');
expect(readFileSync(join(root, 'people', 'unindexed-example.md'), 'utf8')).toContain('Never imported.');
// Routine drift refusals keep out of writer status's recent database refusals.
expect((await readWriterDiagnostics(engine)).recent_failures.map(row => row.error_detail?.origin)).not.toContain('file_database_drift');
}, { setup }), 120_000);
test('a put_page refused the same way is classified but not replayed', () => managedBrain(async ({ engine, ctx, root }) => {
await seed(ctx);
edit(root, 'Committed by another agent.');
git(root, 'add', '--', `${slug}.md`); git(root, 'commit', '-q', '-m', 'agent commit');
const revision = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!.revision;
const error = await refused(() => submitPageMutation(ctx, { operation: 'put_page', params: { slug, request_id: randomUUID(), expected_revision: revision,
content: '---\ntype: person\ntitle: Owner\n---\n\nReplaced body.\n' } }));
expect(error.reason).toBe('pending_import');
expect(error.fix?.argv).toEqual(['gbrain', 'sync', 'status', '--source', 'default', '--json']);
expect((await lastReceipt(engine, 'put_page')).error_detail?.origin).toBe('pending_import');
expect((await sync(engine, root)).replayedRemembers).toBeUndefined();
expect(readFileSync(file(root), 'utf8')).toContain('Committed by another agent.');
expect(readFileSync(file(root), 'utf8')).not.toContain('Replaced body.');
}, { setup }), 120_000);
// GBRA-133: an agent followed a refusal that named `gbrain sync --source <source> --no-pull` while serve was running and put a
// second sync owner beside it. With a serve holding the source's drain lease, no pending-import surface names a sync to start.
test('while a serve owns the source, no pending-import refusal tells the caller to start a sync', () => managedBrain(async ({ engine, ctx, root }) => {
await seed(ctx);
edit(root, 'The cron writer committed this line.');
git(root, 'add', '--', `${slug}.md`); git(root, 'commit', '-q', '-m', 'cron writer commit');
const revision = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!.revision;
const startsSync = (surface: unknown) => JSON.stringify(surface).match(/gbrain sync(?! status)\b|"gbrain","sync","(?!status")/g) ?? [];
const view = (error: unknown) => { const e = error as { message?: string; suggestion?: string; why?: string; fix?: unknown; reason?: string; detail?: string };
return { message: e.message, suggestion: e.suggestion, why: e.why, fix: e.fix }; };
await withDrainLease(engine, 'default', { holder: { kind: 'serve', id: 'serve-example' } }, async () => {
expect((await readDrainHolder(engine, 'default'))?.kind).toBe('serve');
const remember = { fact: 'Owner prefers written updates', entity: slug, provenance: 'test', visibility: 'world' as const };
const cli = await refused(() => runMemoryWrite(() => submitRememberMutation(ctx, remember))) as { detail?: string; fix?: { argv?: string[] } };
expect(cli.detail).toBe('pending_import');
expect(cli.fix?.argv).toEqual(['gbrain', 'sync', 'status', '--source', 'default', '--json']);
const direct = await refused(() => submitRememberMutation(ctx, remember));
const put = await refused(() => submitPageMutation(ctx, { operation: 'put_page', params: { slug, request_id: randomUUID(), expected_revision: revision,
content: '---\ntype: person\ntitle: Owner\n---\n\nReplaced body.\n' } }));
expect([direct.reason, put.reason]).toEqual(['pending_import', 'pending_import']);
const surfaces = [view(cli), view(direct), view(put), writeFailureDiagnostic('source_changed', PENDING_IMPORT_MESSAGE),
...[false, true].flatMap(remote => ['remember', 'put_page'].map(operation => view(pendingImportRefusal({ source_id: 'default', slug, operation }, remote))))];
for (const surface of surfaces) expect(startsSync(surface)).toEqual([]);
return {} as SyncResult;
});
}, { setup }), 120_000);
});