Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { afterAll, beforeAll, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { claimWorktree, acquireWorktree, type WorktreeBinding } from '../src/core/persistence/ownership.ts';
import { registerLocalWriter } from '../src/core/persistence/identity.ts';
import { inspectLockHolder } from '../src/core/pglite-lock.ts';
import { persistenceSocketPathForConfig, requestPersistenceCapabilities, requestPersistenceAdministration } from '../src/core/persistence/ipc.ts';
import { readPersistenceCliRegistration } from '../src/core/persistence/local-client.ts';
import { parsePersistenceSyncArgs } from '../src/commands/sync-persistence-delegate.ts';
import { importCodeFile } from '../src/core/import-file.ts';
import { parseReindexCodeDelegateArgs } from '../src/commands/reindex-code-delegate.ts';
import { withEnv } from './helpers/with-env.ts';
const home=mkdtempSync(join(tmpdir(),'gbrain-stdio-sync-'));
const root=join(home,'repo'), databasePath=join(home,'db');
const config={engine:'pglite' as const,database_path:databasePath};
const env={...process.env,GBRAIN_HOME:home,DATABASE_URL:undefined,GBRAIN_DATABASE_URL:undefined,GBRAIN_BRAIN_ID:'host',
GBRAIN_SOURCE:'workspace',GBRAIN_NO_BANNER:'1',GBRAIN_BACKUP_CHECK:'0',GBRAIN_SWEEP:'0',GBRAIN_SKIP_STARTUP_HOOKS:'1',GBRAIN_SYNC_FAILURES_DIR:home};
let setup:PGLiteEngine;
let sourceBinding:WorktreeBinding;
let owner:ReturnType<typeof Bun.spawn>|undefined;
let stdout='',stderr='';
const readers:Promise<void>[]=[];
async function read(stream:ReadableStream<Uint8Array>,append:(text:string)=>void) {
const decoder=new TextDecoder(),reader=stream.getReader();
try{for(;;){const next=await reader.read();if(next.done)return;append(decoder.decode(next.value));}}finally{reader.releaseLock();}
}
async function until(check:()=>boolean|Promise<boolean>,ms=60000) {
const deadline=performance.now()+ms;
while(performance.now()<deadline){if(await check())return;if(owner?.exitCode!==null&&owner?.exitCode!==undefined)throw new Error(`Owner exited: ${stderr}`);await new Promise(r=>setTimeout(r,50));}
throw new Error(`Owner did not become ready: ${stderr}`);
}
async function cli(args:string[],childHome=home,extraEnv:Record<string,string>={},killMs=45000) {
const child=Bun.spawn([process.execPath,join(import.meta.dir,'../src/cli.ts'),...args],{cwd:childHome,env:{...env,GBRAIN_HOME:childHome,...extraEnv},stdin:'ignore',stdout:'pipe',stderr:'pipe'});
const timer=setTimeout(()=>child.kill('SIGKILL'),killMs);
try {const [out,err,code]=await Promise.all([new Response(child.stdout).text(),new Response(child.stderr).text(),child.exited]);return{out,err,code};}
finally{clearTimeout(timer);}
}
beforeAll(async()=>{
mkdirSync(join(home,'.gbrain'),{recursive:true});mkdirSync(root);
writeFileSync(join(home,'.gbrain','config.json'),JSON.stringify(config));
writeFileSync(join(root,'a.md'),'A durable source observation imported through the resident owner.\n');
writeFileSync(join(root,'excluded.md'),'An intentionally excluded observation.\n');
execFileSync('git',['init','-q',root]);execFileSync('git',['-C',root,'add','.']);
execFileSync('git',['-C',root,'-c','user.name=Example','-c','[email protected]','commit','-qm','source content']);
setup=new PGLiteEngine();
await withEnv(env,async()=>{
await setup.connect(config);await setup.initSchema();
await setup.setConfig('search.mcp_keyword_only','true');
// #6340 holds a pinned-worktree conflict when holds are on; `sync.holds=fail` keeps the failure receipt the diagnostics test below is about.
await setup.setConfig('sync.holds','fail');
// #6712 PR 4b (design §6): a selection flag scopes a pass, which never stamps last_commit; the configured exclusion keeps the first sync a first_sync.
await setup.setConfig('sync.exclude','excluded.md');
await setup.executeRaw("INSERT INTO sources(id,name,local_path,config) VALUES('workspace','workspace',$1,'{}')",[root]);
const code = 'export function residentExample() { return 4; }\n';
writeFileSync(join(root,'example.ts'),code);
await importCodeFile(setup,'example.ts',code,{sourceId:'workspace',noEmbed:true});
sourceBinding=await claimWorktree(setup,'workspace',root);await registerLocalWriter(setup,'cli');await registerLocalWriter(setup,'stdio');
await setup.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');await setup.disconnect();
});
owner=Bun.spawn([process.execPath,join(import.meta.dir,'fixtures/persistence-stdio-owner.ts')],{cwd:home,env,stdin:'pipe',stdout:'pipe',stderr:'pipe'});
readers.push(read(owner.stdout as ReadableStream<Uint8Array>,s=>{stdout+=s;}),read(owner.stderr as ReadableStream<Uint8Array>,s=>{stderr+=s;}));
await until(async()=>{try{await requestPersistenceCapabilities(persistenceSocketPathForConfig(config)!,250);return true;}catch{return false;}});
(owner.stdin as {write:(value:string)=>unknown}).write(JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'example-test',version:'1'}}})+'\n');
await until(()=>stdout.split('\n').some(line=>{try{return JSON.parse(line).id===1;}catch{return false;}}));
},120000);
afterAll(async()=>{
if(owner){owner.kill('SIGTERM');const timer=setTimeout(()=>owner?.kill('SIGKILL'),10000);await owner.exited;clearTimeout(timer);}
await Promise.allSettled(readers);await setup?.disconnect();rmSync(home,{recursive:true,force:true});
},30000);
test('actual CLI sync and page reads delegate to a real non-serve stdio owner before opening PGLite',async()=>{
expect(inspectLockHolder(databasePath)).toMatchObject({held:true,serve:false});
const synced=await cli(['sync','--source','workspace','--no-pull','--json','--no-hard-deadline']);
expect({code:synced.code,err:synced.err}).toMatchObject({code:0});
expect(JSON.parse(synced.out)).toMatchObject({schema_version:1,source_id:'workspace',sync_status:'first_sync',added:1});
expect(synced.err).toContain('registered PGLite owner');
const page=await cli(['call','get_page',JSON.stringify({slug:'a',source_id:'workspace'})]);
expect({code:page.code,err:page.err}).toMatchObject({code:0});
expect(JSON.parse(page.out).compiled_truth).toContain('resident owner');
const status=await cli(['sources','writer','status','--json']);
expect({code:status.code,err:status.err}).toMatchObject({code:0});
expect(inspectLockHolder(databasePath).pid).toBe(owner!.pid);
},90000);
test('extract --stale delegates to the resident owner, and the delegated sync already stamped its pages',async()=>{
const preview=await cli(['extract','--stale','--source-id','workspace','--dry-run','--json']);
expect({code:preview.code,err:preview.err}).toMatchObject({code:0});
expect(JSON.parse(preview.out)).toMatchObject({action:'extract_stale_dry_run',stale_pages:0});
const extracted=await cli(['extract','--stale','--json']);
expect({code:extracted.code,err:extracted.err}).toMatchObject({code:0});
const report=JSON.parse(extracted.out);
expect(report).toMatchObject({action:'extract_stale_done',stale_remaining:0});
expect(report.skipped_changed).toBeUndefined();
expect(extracted.err).not.toContain('writer_coordinator_required');
expect(inspectLockHolder(databasePath).pid).toBe(owner!.pid);
},90000);
test('remote stdio credentials cannot request trusted stale extraction',async()=>{
const socket=persistenceSocketPathForConfig(config)!,cap=await requestPersistenceCapabilities(socket);
expect(cap.administration).toContain('writer_extract_stale');
const registration=JSON.parse(readFileSync(join(home,'.gbrain','persistence',`${cap.brain_id}.stdio.json`),'utf8'));
await expect(requestPersistenceAdministration(socket,{version:1,kind:'administration',brain_id:cap.brain_id,
operation:'writer_extract_stale',params:{source_id:'workspace'},registration:{...registration,lane:'cli'}}))
.rejects.toMatchObject({code:'permission_denied'});
});
test('resident-owner failure JSON retains safe scoped diagnostics and the frozen receipt without a local ledger',async()=>{
const path=join(root,'a.md');
const current=await cli(['call','get_page',JSON.stringify({slug:'a',source_id:'workspace'})]);
expect(current.code).toBe(0);
const updated=await cli(['call','put_page',JSON.stringify({slug:'a',source_id:'workspace',
expected_revision:JSON.parse(current.out).revision,content:'A newer coordinated database observation.\n'})]);
expect(updated.code).toBe(0);
expect(JSON.parse(updated.out).state).toBe('committed');
// #6712 PR 4b: the pass imports only a committed change it has not recorded (design §2.3); an uncommitted edit over a
// recorded blob (the coordinated write's included) settles as `dirty`. So another checkout's change is committed and an
// uncommitted edit sits over that new pin: the import the pass owes refuses against the working file.
writeFileSync(path,'A committed observation from another checkout.\n');
execFileSync('git',['-C',root,'-c','user.name=Example','-c','[email protected]','commit','-qm','another checkout','--','a.md']);
const pinned=execFileSync('git',['-C',root,'show','HEAD:a.md'],{encoding:'utf8'});
writeFileSync(path,'PRIVATE_RESIDENT_DIAGNOSTIC_CONTENT_CANARY\n');
const args=['sync','--source','workspace','--full','--no-pull','--no-embed','--exclude','excluded.md','--exclude','example.ts','--json','--no-hard-deadline'];
const blocked=await cli(args);
expect(blocked.code).toBe(1);
const body=JSON.parse(blocked.out);
expect(body).toMatchObject({sync_status:'blocked_by_failures',managed_write:{source_id:'workspace',slug:'a',path:'a.md',
write_error:'source_changed',reason:'pinned_git_worktree_conflict',write_request:{state:'conflict',retry_after_ms:null}}});
const id=body.managed_write.write_request.request_id;
expect(id).toMatch(/^[0-9a-f-]{36}$/);
expect(blocked.err).toContain(id);
expect(blocked.err).toContain('source_changed');
expect(blocked.out+blocked.err).not.toContain('PRIVATE_RESIDENT_DIAGNOSTIC_CONTENT_CANARY');
expect(blocked.out+blocked.err).not.toContain(root);
// #6712 PR 3 (L7): while the file keeps the bytes that refused, every sync replays the receipt; the fix below retries it.
rmSync(join(home,'sync-failures.jsonl'),{force:true});
const replay=await cli(args);
expect(replay.code).toBe(1);
expect(JSON.parse(replay.out).managed_write.write_request).toEqual(body.managed_write.write_request);
writeFileSync(path,pinned);
const corrected=await cli([...args,'--retry-failed']);
expect(corrected.code).toBe(0);
expect(JSON.parse(corrected.out).sync_status).toBe('synced');
const original=await cli(['call','get_write_request',JSON.stringify({request_id:id})]);
expect(original.code).toBe(0);
expect(JSON.parse(original.out)).toMatchObject({request_id:id,state:'conflict'});
expect(inspectLockHolder(databasePath).pid).toBe(owner!.pid);
},90000);
test('resident-owner pending timeout is resumable (exit 0, #5984) and resumes the same durable request after lock release',async()=>{
const path=join(root,'a.md');
const content='A resident source observation waiting for the held worktree lock.\n';
writeFileSync(path,content);
const lock=await acquireWorktree(sourceBinding);
expect(lock).not.toBeNull();
let id:string;
const args=['sync','--source','workspace','--full','--working-tree','--no-pull','--no-embed','--exclude','excluded.md','--exclude','example.ts','--json','--no-hard-deadline'];
try {
const pending=await cli([...args,'--timeout','1']);
expect(pending.code).toBe(0);
const body=JSON.parse(pending.out);
expect(body).toMatchObject({sync_status:'partial',reason:'timeout',added:0,modified:0,outcome:'resumable',next:{safe_to_loop:true},
managed_write:{source_id:'workspace',slug:'a',path:'a.md',write_error:'write_pending'}});
id=body.managed_write.write_request.request_id;
expect(body.managed_write.write_request.state).not.toBe('committed');
expect(body.managed_write.write_request).not.toHaveProperty('revision');
expect(pending.err).toContain(id);
expect(pending.err).toContain('not committed');
const before=await cli(['call','get_page',JSON.stringify({slug:'a',source_id:'workspace'})]);
expect(before.code).toBe(0);
expect(JSON.parse(before.out).compiled_truth).not.toContain('held worktree lock');
} finally {await lock?.release();}
const resumed=await cli(args);
expect(resumed.code).toBe(0);
expect(JSON.parse(resumed.out).sync_status).toBe('synced');
const receipt=await cli(['call','get_write_request',JSON.stringify({request_id:id!})]);
expect(receipt.code).toBe(0);
expect(JSON.parse(receipt.out)).toMatchObject({request_id:id!,state:'committed'});
expect(inspectLockHolder(databasePath).pid).toBe(owner!.pid);
},90000);
// F4d for delegated syncs: the env and default deadlines extend while the owner keeps committing pages,
// as a local sync's do; before, the client stopped the drain at the wall-clock deadline with pages left.
test('a delegated sync past its progress-aware deadline keeps going while the owner commits pages',async()=>{
for(let i=0;i<300;i++)writeFileSync(join(root,`bulk-${String(i).padStart(3,'0')}.md`),`Bulk delegated observation ${i} about the resident owner.\n`);
execFileSync('git',['-C',root,'add','.']);
execFileSync('git',['-C',root,'-c','user.name=Example','-c','[email protected]','commit','-qm','bulk content']);
const synced=await cli(['sync','--source','workspace','--no-pull','--no-embed','--exclude','excluded.md','--json'],home,
{GBRAIN_SYNC_MAX_RUNTIME_SECONDS:'1',GBRAIN_SYNC_STALL_ABORT_SECONDS:'60'},170000);
expect({code:synced.code,err:synced.err.slice(-2000)}).toMatchObject({code:0});
expect(synced.err).toContain('past the delegated deadline and still progressing');
expect(JSON.parse(synced.out)).toMatchObject({outcome:'synced'});
const page=await cli(['call','get_page',JSON.stringify({slug:'bulk-299',source_id:'workspace'})]);
expect(JSON.parse(page.out).compiled_truth).toContain('Bulk delegated observation 299');
},180000);
// gbrain sources refresh needs the writer lock the resident owner holds; it runs inside the owner over the persistence socket.
test('sources refresh delegates to the resident owner, fast-forwards the checkout and syncs the new page',async()=>{
const remote=join(home,'origin.git'),pusher=join(home,'pusher');
const g=(cwd:string,...args:string[])=>execFileSync('git',['-C',cwd,'-c','user.name=Example','-c','[email protected]',...args],{stdio:'pipe'}).toString().trim();
execFileSync('git',['init','-q','--bare',remote]);
const branch=g(root,'rev-parse','--abbrev-ref','HEAD');
g(root,'remote','add','origin',remote);g(root,'push','-q','-u','origin',branch);
execFileSync('git',['clone','-q',remote,pusher],{stdio:'ignore'});
writeFileSync(join(pusher,'upstream-note.md'),'A zebracorn observation pushed upstream for the resident owner.\n');
g(pusher,'add','.');g(pusher,'commit','-qm','upstream note');g(pusher,'push','-q','origin',`HEAD:${branch}`);
const target=g(pusher,'rev-parse','HEAD');
const refreshed=await cli(['sources','refresh','workspace','--json'],home,{},120000);
expect({code:refreshed.code,err:refreshed.err.slice(-2000)}).toMatchObject({code:0});
expect(JSON.parse(refreshed.out)).toMatchObject({status:'completed',target_head:target});
expect(inspectLockHolder(databasePath).pid).toBe(owner!.pid);
const page=await cli(['call','get_page',JSON.stringify({slug:'upstream-note',source_id:'workspace'})]);
expect(JSON.parse(page.out).compiled_truth).toContain('zebracorn');
},150000);
test('strict sync parsing retains filtering options and rejects runtime authority fields',async()=>{
await withEnv(env,async()=>{
expect((await parsePersistenceSyncArgs(['--source','workspace','--no-pull','--working-tree','--exclude','draft/**','--include-hidden','.notes/**','--no-hard-deadline'],home)).options)
.toMatchObject({sourceId:'workspace',noPull:true,workingTree:true,exclude:['draft/**'],includeHidden:['.notes/**']});
expect((await parsePersistenceSyncArgs(['--timeout','2','--no-hard-deadline'],home)).timeoutSeconds).toBe(2);
expect((await parsePersistenceSyncArgs(['--timeout','2','--hard-deadline','30'],home)).timeoutSeconds).toBe(2);
expect((await parsePersistenceSyncArgs(['--timeout','30','--hard-deadline','2'],home)).timeoutSeconds).toBe(2);
expect((await parsePersistenceSyncArgs(['--no-hard-deadline'],home)).timeoutSeconds).toBe(0);
await expect(parsePersistenceSyncArgs(['--skipLock','--no-hard-deadline'],home)).rejects.toMatchObject({code:'invalid_params'});
});
});
test('actual code recovery CLI delegates to the resident owner without a legacy writer or paid provider',async()=>{
const before=await cli(['call','get_page',JSON.stringify({slug:'example-ts',source_id:'workspace'})]);
const current=JSON.parse(before.out);
for(const args of [['reindex-code','--force'],['reindex-code','--force']]) {
const result=await cli([...args,'--source','workspace','--no-embed','--json']);
expect({code:result.code,err:result.err}).toMatchObject({code:0});
expect(JSON.parse(result.out)).toMatchObject({reindexed:1,failed:0});
expect(result.err).not.toContain('writer_coordinator_required');
}
const after=await cli(['call','get_page',JSON.stringify({slug:'example-ts',source_id:'workspace'})]);
expect(JSON.parse(after.out).revision).toBe(current.revision);
expect(JSON.parse(after.out).compiled_truth).toBe(current.compiled_truth);
(owner!.stdin as {write:(value:string)=>unknown}).write(JSON.stringify({jsonrpc:'2.0',id:2,method:'tools/call',params:{name:'search',arguments:{query:'residentExample',source_id:'workspace'}}})+'\n');
await until(()=>stdout.split('\n').some(line=>{try{return JSON.parse(line).id===2;}catch{return false;}}));
const search=stdout.split('\n').map(line=>{try{return JSON.parse(line);}catch{return null;}}).find(value=>value?.id===2);
expect(search.result.isError).not.toBe(true);
expect(JSON.stringify(search.result)).toContain('residentExample');
expect(inspectLockHolder(databasePath).pid).toBe(owner!.pid);
expect(parseReindexCodeDelegateArgs(['--force','--no-embed','--source','workspace'])).toEqual({force:true,noEmbed:true,sourceId:'workspace'});
expect(()=>parseReindexCodeDelegateArgs(['--remote','false'])).toThrow();
},90000);
test('remote stdio credentials cannot request trusted code reindex',async()=>{
const socket=persistenceSocketPathForConfig(config)!,cap=await requestPersistenceCapabilities(socket);
const registration=JSON.parse(readFileSync(join(home,'.gbrain','persistence',`${cap.brain_id}.stdio.json`),'utf8'));
await expect(requestPersistenceAdministration(socket,{version:1,kind:'administration',brain_id:cap.brain_id,
operation:'writer_reindex_code',params:{options:{sourceId:'workspace',force:true,noEmbed:true}},registration:{...registration,lane:'cli'}}))
.rejects.toMatchObject({code:'permission_denied'});
});
test('the remote stdio credential cannot enter the trusted CLI sync lane',async()=>{
const socket=persistenceSocketPathForConfig(config)!,cap=await requestPersistenceCapabilities(socket);
const registration=JSON.parse(readFileSync(join(home,'.gbrain','persistence',`${cap.brain_id}.stdio.json`),'utf8'));
await expect(requestPersistenceAdministration(socket,{version:1,kind:'administration',brain_id:cap.brain_id,
operation:'writer_sync',params:{options:{sourceId:'workspace',noPull:true},cwd:home,timeoutSeconds:30},registration:{...registration,lane:'cli'}}))
.rejects.toMatchObject({code:'permission_denied'});
});
test('a separate user home cannot borrow the resident owner registration',async()=>{
const otherHome=join(home,'other-user');mkdirSync(join(otherHome,'.gbrain'),{recursive:true});
writeFileSync(join(otherHome,'.gbrain','config.json'),JSON.stringify(config));
const denied=await cli(['sync','--source','workspace','--no-pull','--json','--no-hard-deadline'],otherHome);
expect(denied.code).toBe(1);expect(denied.err).toContain('permission_denied');
expect(denied.err).toContain('registration');expect(denied.err).not.toContain('LockTimeout');
expect(inspectLockHolder(databasePath).pid).toBe(owner!.pid);
},60000);
test('a revoked CLI cannot fall through to a competing database open',async()=>{
await withEnv(env,async()=>{
const socket=persistenceSocketPathForConfig(config)!,cap=await requestPersistenceCapabilities(socket),registration=readPersistenceCliRegistration(cap.brain_id);
await requestPersistenceAdministration(socket,{version:1,kind:'administration',brain_id:cap.brain_id,operation:'local_writer_revoke',params:{id:registration.id},registration});
});
const denied=await cli(['sync','--source','workspace','--no-pull','--json','--no-hard-deadline']);
expect(denied.code).toBe(1);expect(denied.err).toContain('permission_denied');expect(denied.err).not.toContain('LockTimeout');
expect(inspectLockHolder(databasePath).pid).toBe(owner!.pid);
},60000);
test('the recovered code remains searchable from the CLI after resident shutdown',async()=>{
owner!.kill('SIGTERM');await owner!.exited;
const result=await cli(['search','residentExample','--source','workspace','--json']);
expect({code:result.code,err:result.err}).toMatchObject({code:0});
expect(result.out).toContain('example-ts');
},60000);