Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #5455/#5628: `gbrain sources writer deactivate` converts a managed brain back
* to classic mode. Markers come from a real claim and activation. Each blocker
* refuses with its exit; success retires worktrees (receipts keep their
* foreign keys), bumps mode_epoch and records a committed writer_deactivate
* change; local markers of the retired epoch are removed on this host and, on
* connect, on any other host; newer or unknown markers are kept and reported.
*/
import { describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { execFileSync } from 'node:child_process';
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { configDir } from '../src/core/config.ts';
import { runPersistenceAdministration } from '../src/core/persistence/administration.ts';
import { writerAdminState } from '../src/core/persistence/admin-intent.ts';
import { cleanupRetiredManagedMarkers } from '../src/core/persistence/deactivation.ts';
import { assertManagedFilesystemWrite } from '../src/core/persistence/filesystem-guard.ts';
import { claimWorktree, getWorktreeBinding } from '../src/core/persistence/ownership.ts';
import { activateSharedSkillPersistence } from '../src/core/persistence/skill-activation.ts';
import { registerLocalWriter, withVerifiedLocalRegistration, localHostId } from '../src/core/persistence/identity.ts';
import { submissionAuthority } from '../src/core/persistence/authority.ts';
import { admitWrite } from '../src/core/persistence/journal.ts';
import { performSync } from '../src/commands/sync.ts';
import type { OperationContext } from '../src/core/ops/contract.ts';
import { managedBrain } from './helpers/managed-brain.ts';
import { declarePersistenceProtocol } from '../src/core/persistence/protocol.ts';
import { put } from './helpers/wave-fixture.ts';
import { waitFor } from './helpers/wait-for.ts';
const admin = (engine: BrainEngine, operation: string, params: Record<string, unknown> = {}) =>
runPersistenceAdministration(engine, operation as never, params) as Promise<Record<string, any>>;
const deactivate = async (engine: BrainEngine, extra: Record<string, unknown> = {}) =>
admin(engine, 'writer_deactivate', { admin_intent: 'writer_deactivate', expected_state: await writerAdminState(engine), ...extra });
const protocol = (engine: BrainEngine, sql: string, params: unknown[] = []) =>
engine.transaction(async tx => { await declarePersistenceProtocol(tx); await tx.executeRaw(sql, params); });
// The consumer started by put keeps running its effects. Rewriting effect rows
// while one is in flight lets its completion overwrite the rewrite (a requeued
// embedding effect read back as committed), so settle the source first.
const settleEffects = (engine: BrainEngine) => waitFor(async () => (await engine.executeRaw(
"SELECT 1 FROM persistence_effects e JOIN persistence_requests r ON r.id=e.request_id WHERE r.source_id='default' AND e.state IN ('queued','running')")).length === 0,
{ label: `${engine.kind}: default source effects settled` });
const registry = () => { const dir = join(configDir(), 'persistence', 'managed-roots'); return existsSync(dir) ? readdirSync(dir).map(f => join(dir, f)) : []; };
const brainRow = async (engine: BrainEngine) => (await engine.executeRaw<{ brain_id: string; enabled: boolean; mode_epoch: string }>(
'SELECT brain_id, enabled, mode_epoch::text FROM persistence_brain WHERE singleton=1'))[0];
for (const databaseUrl of process.env.DATABASE_URL ? [undefined, process.env.DATABASE_URL] : [undefined]) describe(`#5455 sources writer deactivate (${databaseUrl ? 'postgres' : 'pglite'})`, () => {
test('dry run lists every blocker and changes nothing; each blocker refuses with its exit', () => managedBrain(async ({ engine, ctx }) => {
await put(ctx, 'notes/one', 'Body.');
await settleEffects(engine);
const [request] = await engine.executeRaw<{ request_id: string; id: string }>("SELECT request_id::text, id::text FROM persistence_requests WHERE slug='notes/one'");
await protocol(engine, "UPDATE persistence_effects SET state='committed'");
await protocol(engine, "UPDATE persistence_effects SET state='queued', next_attempt_at=now()+interval '1 day' WHERE request_id=$1::uuid AND kind='embedding'", [request.id]);
await admin(engine, 'writer_lock');
const before = await writerAdminState(engine);
const dry = await admin(engine, 'writer_deactivate', { dry_run: true });
expect(dry.mode).toBe('managed');
expect(dry.dry_run).toBe(true);
expect(dry.blockers.map((b: { kind: string }) => b.kind)).toEqual(['writer_admin_lock', 'effect']);
expect(dry.blockers.find((b: { kind: string }) => b.kind === 'effect').exit)
.toBe('wait for the owner to drain it, then rerun deactivate; one still queued after an hour is re-queued by gbrain repair embedding-effects --source default');
expect(dry.retired_worktrees.length).toBe(1);
expect(dry.kept).toMatchObject({ skill_bundles_enabled: true, writer_protocol_floor: 2 });
expect(await writerAdminState(engine)).toBe(before);
expect((await brainRow(engine)).enabled).toBe(true);
await expect(deactivate(engine)).rejects.toMatchObject({ code: 'writer_admin_locked' });
await admin(engine, 'writer_unlock');
await expect(deactivate(engine)).rejects.toMatchObject({ code: 'writer_not_quiesced',
suggestion: expect.stringContaining('gbrain repair embedding-effects --source default') });
await protocol(engine, "UPDATE persistence_effects SET state='committed' WHERE request_id=$1::uuid", [request.id]);
await protocol(engine, "UPDATE persistence_requests SET state='queued' WHERE id=$1::uuid", [request.id]);
await expect(deactivate(engine)).rejects.toMatchObject({ code: 'writer_not_quiesced',
suggestion: expect.stringContaining(`gbrain cancel-write-request ${request.request_id}`) });
await protocol(engine, "UPDATE persistence_requests SET state='committed' WHERE id=$1::uuid", [request.id]);
const current = await writerAdminState(engine);
await expect(admin(engine, 'writer_deactivate', { admin_intent: 'writer_deactivate', expected_state: 'f'.repeat(64) }))
.rejects.toMatchObject({ code: 'writer_admin_state_changed', suggestion: expect.stringContaining(`The current admin_state is ${current}`) });
await expect(admin(engine, 'writer_deactivate', { source_id: 'default', dry_run: true })).rejects.toMatchObject({ code: 'invalid_params',
message: expect.stringContaining('brain-wide') });
const stdio = await registerLocalWriter(engine, 'stdio');
await expect(withVerifiedLocalRegistration(engine, stdio, () => deactivate(engine))).rejects.toMatchObject({ code: 'permission_denied' });
expect((await brainRow(engine)).enabled).toBe(true);
}, { databaseUrl }));
test('success: classic mode, retired worktrees keep receipts, markers from the real activation are removed, content unchanged; rerun is a no-op', () => managedBrain(async ({ engine, ctx, root }) => {
await put(ctx, 'notes/one', 'Body one.');
await settleEffects(engine);
await protocol(engine, "UPDATE persistence_effects SET state='committed'");
const file = readFileSync(join(root, 'notes', 'one.md'), 'utf8');
const page = await engine.getPage('notes/one', { sourceId: 'default' });
const brain = await brainRow(engine);
const binding = (await getWorktreeBinding(engine, 'default', localHostId()))!;
const markers = [join(root, '.gbrain-owner.json'), join(root, '.gbrain-managed')];
for (const marker of markers) expect(existsSync(marker)).toBe(true);
expect(registry().length).toBeGreaterThan(0);
expect(() => assertManagedFilesystemWrite(join(root, 'notes', 'two.md'))).toThrow();
const done = await deactivate(engine);
expect(done).toMatchObject({ mode: 'classic', deactivated: true, retired_mode_epoch: Number(brain.mode_epoch), mode_epoch: Number(brain.mode_epoch) + 1,
local_markers: { state: 'cleared' } });
expect(done.retired_worktrees).toEqual([{ id: binding.worktree_id, roots: [binding.local_path] }]);
for (const marker of markers) expect(existsSync(marker)).toBe(false);
expect(registry().filter(path => path.includes(brain.brain_id))).toEqual([]);
expect(() => assertManagedFilesystemWrite(join(root, 'notes', 'two.md'))).not.toThrow();
expect(await engine.executeRaw('SELECT 1 FROM persistence_source_bindings')).toEqual([]);
expect(await engine.executeRaw('SELECT 1 FROM persistence_host_bindings')).toEqual([]);
expect((await engine.executeRaw<{ state: string }>('SELECT state FROM persistence_worktrees WHERE id=$1::uuid', [binding.worktree_id]))[0].state).toBe('retired');
expect((await engine.executeRaw('SELECT 1 FROM persistence_requests WHERE worktree_id=$1::uuid', [binding.worktree_id])).length).toBeGreaterThan(0);
const [change] = await engine.executeRaw<{ state: string; outcome: Record<string, unknown> }>("SELECT state, outcome FROM persistence_topology_changes WHERE operation='writer_deactivate'");
expect(change).toMatchObject({ state: 'committed', outcome: { brain_id: brain.brain_id, retired_mode_epoch: Number(brain.mode_epoch) } });
expect(readFileSync(join(root, 'notes', 'one.md'), 'utf8')).toBe(file);
expect((await engine.getPage('notes/one', { sourceId: 'default' }))?.compiled_truth).toBe(page?.compiled_truth);
const status = await admin(engine, 'writer_status');
expect(status).toMatchObject({ mode: 'classic', local_markers: { state: 'cleared' } });
const again = await deactivate(engine);
expect(again).toMatchObject({ mode: 'classic', deactivated: false, local_markers: { state: 'cleared' } });
expect((await engine.executeRaw("SELECT 1 FROM persistence_topology_changes WHERE operation='writer_deactivate'")).length).toBe(1);
// A classic sync of the former managed checkout imports a new file.
execFileSync('git', ['-C', root, 'init', '-q']);
writeFileSync(join(root, 'notes', 'two.md'), '---\ntype: note\ntitle: Two\n---\n\nClassic write.\n');
execFileSync('git', ['-C', root, 'add', '.']);
execFileSync('git', ['-C', root, '-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-qm', 'two']);
await performSync(engine, { repoPath: root, sourceId: 'default', noPull: true, noEmbed: true, noExtract: true } as never);
expect((await engine.getPage('notes/two', { sourceId: 'default' }))?.compiled_truth).toContain('Classic write.');
// A live owner's stale binding can no longer admit.
const authority = await submissionAuthority({ ...ctx } as OperationContext, 'put_page', 'default', binding.source_incarnation, 'notes/three');
await expect(admitWrite(engine, { principal: authority.principal, authority, operation: 'put_page', sourceId: 'default',
sourceIncarnation: binding.source_incarnation, slug: 'notes/three', requestId: randomUUID(), callerIntent: {}, intent: {},
worktreeId: binding.worktree_id, topologyGeneration: binding.topology_generation })).rejects.toMatchObject({ code: 'source_changed' });
}, { databaseUrl }));
test('another host: retired and pre-wave markers are removed on connect; a restored-backup marker is kept and reported', () => managedBrain(async ({ engine, root }) => {
const brain = await brainRow(engine);
const binding = (await getWorktreeBinding(engine, 'default', localHostId()))!;
await deactivate(engine);
// What another host still has on disk: a pre-wave registry record and marker (no epoch) and one from a restored newer backup.
const dir = join(configDir(), 'persistence', 'managed-roots'); mkdirSync(dir, { recursive: true });
const preWave = join(dir, `${brain.brain_id}.aaaa.json`);
writeFileSync(preWave, JSON.stringify({ version: 1, brain_id: brain.brain_id, root, local_path: root, worktree_id: binding.worktree_id }), { mode: 0o600 });
writeFileSync(join(root, '.gbrain-managed'), JSON.stringify({ version: 1, managed: true, brain_id: brain.brain_id }), { mode: 0o600 });
writeFileSync(join(root, '.gbrain-owner.json'), JSON.stringify({ version: 1, token: randomUUID(), brainId: brain.brain_id, worktreeId: binding.worktree_id }), { mode: 0o600 });
const otherBrain = join(dir, `${randomUUID()}.bbbb.json`);
writeFileSync(otherBrain, JSON.stringify({ version: 1, brain_id: 'other', root: '/elsewhere', local_path: '/elsewhere' }), { mode: 0o600 });
const newer = join(dir, `${brain.brain_id}.cccc.json`);
writeFileSync(newer, JSON.stringify({ version: 1, brain_id: brain.brain_id, root: join(root, 'x'), local_path: join(root, 'x'), mode_epoch: 99 }), { mode: 0o600 });
expect(() => assertManagedFilesystemWrite(join(root, 'notes', 'a.md'))).toThrow();
const report = await cleanupRetiredManagedMarkers(engine);
expect(report.removed.sort()).toEqual([preWave, join(root, '.gbrain-managed'), join(root, '.gbrain-owner.json')].sort());
expect(report).toMatchObject({ state: 'pending', pending: [{ path: newer, reason: 'newer_mode_epoch' }] });
expect(existsSync(otherBrain)).toBe(true);
expect(existsSync(newer)).toBe(true);
expect(() => assertManagedFilesystemWrite(join(root, 'notes', 'a.md'))).not.toThrow();
// A retired reservation beside a checkout that no longer exists is removed too.
const gone = join(dirname(root), 'gone-checkout');
const { physicalRootReservationPath } = await import('../src/core/persistence/physical-root-record.ts');
await engine.executeRaw("UPDATE persistence_topology_changes SET outcome=jsonb_set(outcome,'{source_roots}',to_jsonb(ARRAY[$1::text])) WHERE operation='writer_deactivate'", [gone]);
const reservation = physicalRootReservationPath(gone);
writeFileSync(reservation, JSON.stringify({ version: 1, token: randomUUID(), brainId: brain.brain_id, worktreeId: binding.worktree_id }), { mode: 0o600 });
expect((await cleanupRetiredManagedMarkers(engine)).removed).toContain(reservation);
expect(existsSync(reservation)).toBe(false);
expect((await admin(engine, 'writer_status')).local_markers).toMatchObject({ state: 'pending', pending: [{ path: newer }] });
}, { databaseUrl }));
test('a host offline across deactivate and reactivation removes only the retired markers', () => managedBrain(async ({ engine, root }) => {
const brain = await brainRow(engine);
const old = (await getWorktreeBinding(engine, 'default', localHostId()))!;
await deactivate(engine);
await claimWorktree(engine, 'default', root);
await activateSharedSkillPersistence(engine, { confirmQuiesced: true });
const fresh = (await getWorktreeBinding(engine, 'default', localHostId()))!;
expect(fresh.worktree_id).not.toBe(old.worktree_id);
const current = await brainRow(engine);
expect(Number(current.mode_epoch)).toBe(Number(brain.mode_epoch) + 2);
const dir = join(configDir(), 'persistence', 'managed-roots');
const stale = join(dir, `${brain.brain_id}.dddd.json`);
writeFileSync(stale, JSON.stringify({ version: 1, brain_id: brain.brain_id, root: '/offline/old', local_path: '/offline/old', mode_epoch: Number(brain.mode_epoch) }), { mode: 0o600 });
const kept = registry().filter(path => path !== stale);
expect(kept.length).toBeGreaterThan(0);
const report = await cleanupRetiredManagedMarkers(engine);
expect(report).toMatchObject({ state: 'cleared', removed: [stale] });
for (const path of kept) expect(existsSync(path)).toBe(true);
expect(existsSync(join(root, '.gbrain-owner.json'))).toBe(true);
expect(() => assertManagedFilesystemWrite(join(root, 'notes', 'a.md'))).toThrow();
}, { databaseUrl }));
});