Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #8073 (dream reverse-write): the dream reverse-write (`writeDreamPageFile`, `removeDreamPageFile`,
* `reverseWriteDreamRefs`: synthesize, patterns, the cycle summary, generation repair) commits the files it writes into
* a source that is a Git checkout, so the checkout never collects untracked or modified dream files.
*
* Protects: a reverse-write of several pages lands as one commit naming exactly their files; the cycle summary's file and
* a retired dream page's file removal each commit; `git status` stays clean. A commit the checkout refuses (a
* pre-commit hook here) rolls each file back (removed, or its prior bytes) and reports the page with a
* `write_through_failed` hold. A checkout carrying a canonical owner marker commits through commit-push's
* named-paths-only path. A declared `storage.db_only` directory gets no file and no commit; a repo-less source
* (no local_path, no brain directory) gets no file; a directory that is not a Git checkout keeps its files.
* Fails when: a reverse-write leaves its file uncommitted (the pre-fix path) or leaves a file behind after a refused
* commit.
* Seams: none; the dream outputs are imported pages, rendered as the database holds them (serializePageToMarkdown). PGLite always, Postgres when DATABASE_URL is set.
*/
import { describe, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { removeDreamPageFile, reverseWriteDreamRefs, writeDreamPageFile } from '../../src/core/cycle/derived-write-through.ts';
import type { BrainEngine } from '../../src/core/engine.ts';
import { importFromContent } from '../../src/core/import-file.ts';
import { serializePageToMarkdown } from '../../src/core/markdown.ts';
import { managedPersistenceEnabled } from '../../src/core/persistence/ownership.ts';
import { _resetWriteThroughCacheForTest } from '../../src/core/write-through.ts';
import { isolatedSharedSkillsEngine } from '../helpers/shared-skills-engine.ts';
import { withEnv } from '../helpers/with-env.ts';
import { pathologicalArms } from '../pathological/harness.ts';
type Layout = 'git' | 'plain' | 'none';
const SOURCE = 'default';
const IDEA = 'wiki/originals/ideas/alice-example-idea';
const PLAN = 'wiki/originals/ideas/acme-example-plan';
const SUMMARY = 'dream-cycle-summaries/2026-09-07';
const MIRROR = 'source-b';
interface Brain {
engine: BrainEngine;
root: string;
brainDir: string;
git(...args: string[]): string;
path(slug: string): string;
reverseWrite(slugs: string[]): Promise<{ written: number; held: string[] }>;
}
const page = (title: string, body: string) => `---\ntype: note\ntitle: ${title}\n---\n# ${title}\n\n${body}\n`;
async function withBrain(databaseUrl: string | undefined, layout: Layout, run: (b: Brain) => Promise<void>): Promise<void> {
const home = mkdtempSync(join(tmpdir(), 'gbrain-8073-dream-'));
try {
await withEnv({ GBRAIN_HOME: home, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {
_resetWriteThroughCacheForTest();
const { engine, close } = await isolatedSharedSkillsEngine(databaseUrl);
try {
expect(await managedPersistenceEnabled(engine)).toBe(false);
const root = join(home, 'brain');
mkdirSync(root, { recursive: true });
const git = (...args: string[]) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
if (layout === 'git') {
git('init', '-q');
git('config', 'user.name', 'Example Writer');
git('config', 'user.email', '[email protected]');
writeFileSync(join(root, 'README.md'), '# source-a\n');
git('add', 'README.md');
git('commit', '-qm', 'init');
}
if (layout !== 'none') await engine.executeRaw('UPDATE sources SET local_path = $1 WHERE id = $2', [root, SOURCE]);
for (const [slug, title] of [[IDEA, 'Alice Example idea'], [PLAN, 'Acme Example plan'], [SUMMARY, 'Dream cycle summary']] as const) {
await importFromContent(engine, slug, page(title, `${title} body.`), { noEmbed: true, sourceId: SOURCE });
}
const brainDir = layout === 'none' ? '' : root;
await run({
engine, root, brainDir, git,
path: slug => join(root, `${slug}.md`),
async reverseWrite(slugs) {
const held: string[] = [];
const written = await reverseWriteDreamRefs(engine, brainDir, slugs.map(slug => ({ slug, source_id: SOURCE })),
{ phase: 'synthesize', nativeSourceId: SOURCE, render: (p, tags) => serializePageToMarkdown(p, tags), held });
return { written, held };
},
});
} finally { await close(); }
});
} finally { rmSync(home, { recursive: true, force: true }); }
}
const commitCount = (b: Brain) => Number(b.git('rev-list', '--count', 'HEAD'));
const lastCommitPaths = (b: Brain) => b.git('show', '--no-renames', '--name-only', '--format=', 'HEAD').split('\n').filter(Boolean).sort();
const dirty = (b: Brain) => b.git('status', '--porcelain', '--untracked-files=all');
const filesUnder = (dir: string): string[] => !existsSync(dir) ? [] : readdirSync(dir, { recursive: true, withFileTypes: true })
.filter(e => e.isFile() && e.name.endsWith('.md')).map(e => e.name);
const setMirror = (engine: BrainEngine, sourceId: string, readOnly: boolean) =>
engine.executeRaw(`UPDATE sources SET config = $2::text::jsonb WHERE id = $1`, [sourceId, JSON.stringify(readOnly ? { mirror_read_only: true } : {})]);
const failedHolds = (held: string[], slug: string) => held.filter(h => h.startsWith(`${slug} (write_through_failed`));
function refuseCommits(b: Brain): void {
const hook = join(b.root, '.git', 'hooks', 'pre-commit');
writeFileSync(hook, '#!/bin/sh\necho "refused by policy" >&2\nexit 1\n');
chmodSync(hook, 0o755);
}
for (const { backend, databaseUrl } of pathologicalArms()) {
describe(`#8073 dream reverse-write commits its files (${backend})`, () => {
test('a reverse-write of several pages lands as one commit naming exactly their files, and the checkout stays clean', async () => {
await withBrain(databaseUrl, 'git', async b => {
const before = commitCount(b);
const result = await b.reverseWrite([IDEA, PLAN]);
expect({ written: result.written, held: result.held, dirty: dirty(b) }).toEqual({ written: 2, held: [], dirty: '' });
expect({ commits: commitCount(b) - before, paths: lastCommitPaths(b) }).toEqual({ commits: 1, paths: [`${PLAN}.md`, `${IDEA}.md`].sort() });
});
}, 180_000);
test('the cycle summary file write commits, and a retired dream page\'s file removal commits', async () => {
await withBrain(databaseUrl, 'git', async b => {
const summary = await writeDreamPageFile(b.engine, b.brainDir, SUMMARY, SOURCE, { nativeSourceId: SOURCE, markdown: serializePageToMarkdown((await b.engine.getPage(SUMMARY, { sourceId: SOURCE }))!, []) });
expect({ written: summary.written, paths: lastCommitPaths(b), dirty: dirty(b) }).toEqual({ written: true, paths: [`${SUMMARY}.md`], dirty: '' });
await b.reverseWrite([IDEA]);
const before = commitCount(b);
const removed = await removeDreamPageFile(b.engine, b.brainDir, IDEA, SOURCE, SOURCE);
expect({ removed: removed.removed, file: existsSync(b.path(IDEA)), dirty: dirty(b), commits: commitCount(b) - before, tracked: b.git('ls-files', '--', `${IDEA}.md`) })
.toEqual({ removed: true, file: false, dirty: '', commits: 1, tracked: '' });
});
}, 180_000);
test('a refused commit rolls every file back and holds each page with write_through_failed', async () => {
await withBrain(databaseUrl, 'git', async b => {
await b.reverseWrite([PLAN]);
const planBefore = readFileSync(b.path(PLAN), 'utf8');
await importFromContent(b.engine, PLAN, page('Acme Example plan', 'Acme Example plan body, revised by the dream.'), { noEmbed: true, sourceId: SOURCE });
refuseCommits(b);
const head = b.git('rev-parse', 'HEAD');
const result = await b.reverseWrite([IDEA, PLAN]);
expect({ written: result.written, idea: failedHolds(result.held, IDEA).length, plan: failedHolds(result.held, PLAN).length })
.toEqual({ written: 0, idea: 1, plan: 1 });
expect({ head: b.git('rev-parse', 'HEAD'), dirty: dirty(b), idea: existsSync(b.path(IDEA)), plan: readFileSync(b.path(PLAN), 'utf8') === planBefore })
.toEqual({ head, dirty: '', idea: false, plan: true });
const summary = await writeDreamPageFile(b.engine, b.brainDir, SUMMARY, SOURCE, { nativeSourceId: SOURCE, markdown: 'summary' });
expect({ written: summary.written, held: failedHolds(!summary.written && summary.held ? [summary.held] : [], SUMMARY).length, file: existsSync(b.path(SUMMARY)), dirty: dirty(b) })
.toEqual({ written: false, held: 1, file: false, dirty: '' });
});
}, 180_000);
// Value: protects=#8087's root match in reverseWriteDreamRefs (a refused commit holds only the pages of the checkout that refused it);
// fails_when=the failure is matched to changes by relative path alone, so the same slug in another source's checkout is held and taken off
// the written count too; why_new=every other case here has one checkout (#8094); seam=none (two real checkouts, a pre-commit hook in one);
// no_claim=the hold token's text, which names the slug only.
test('a refused commit in one source\'s checkout holds only that source\'s page; the same slug in another checkout commits', async () => {
await withBrain(databaseUrl, 'git', async b => {
const other = `${b.root}-b`;
mkdirSync(other, { recursive: true });
const gitB = (...args: string[]) => execFileSync('git', ['-C', other, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
gitB('init', '-q');
gitB('config', 'user.name', 'Example Writer');
gitB('config', 'user.email', '[email protected]');
writeFileSync(join(other, 'README.md'), '# source-b\n');
gitB('add', 'README.md');
gitB('commit', '-qm', 'init');
await b.engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', ['source-b', other]);
await importFromContent(b.engine, IDEA, page('Alice Example idea', 'The source-b copy of the idea.'), { noEmbed: true, sourceId: 'source-b' });
refuseCommits(b);
const headA = b.git('rev-parse', 'HEAD'), commitsB = Number(gitB('rev-list', '--count', 'HEAD'));
const held: string[] = [];
const written = await reverseWriteDreamRefs(b.engine, b.brainDir, [{ slug: IDEA, source_id: SOURCE }, { slug: IDEA, source_id: 'source-b' }],
{ phase: 'synthesize', nativeSourceId: SOURCE, render: (p, tags) => serializePageToMarkdown(p, tags), held });
expect({ written, held: failedHolds(held, IDEA).length }).toEqual({ written: 1, held: 1 });
expect({ headA: b.git('rev-parse', 'HEAD'), dirtyA: dirty(b), fileA: existsSync(b.path(IDEA)) }).toEqual({ headA, dirtyA: '', fileA: false });
expect({ commitsB: Number(gitB('rev-list', '--count', 'HEAD')) - commitsB, pathsB: gitB('show', '--name-only', '--format=', 'HEAD'),
dirtyB: gitB('status', '--porcelain', '--untracked-files=all') }).toEqual({ commitsB: 1, pathsB: `${IDEA}.md`, dirtyB: '' });
});
}, 180_000);
test('a checkout carrying a canonical owner marker commits through the named-paths-only path', async () => {
await withBrain(databaseUrl, 'git', async b => {
appendFileSync(join(b.root, '.git', 'info', 'exclude'), '.gbrain-owner.json\n');
writeFileSync(join(b.root, '.gbrain-owner.json'), '{}\n');
const before = commitCount(b);
const result = await b.reverseWrite([IDEA]);
expect({ written: result.written, held: result.held, dirty: dirty(b), commits: commitCount(b) - before, paths: lastCommitPaths(b) })
.toEqual({ written: 1, held: [], dirty: '', commits: 1, paths: [`${IDEA}.md`] });
});
}, 180_000);
test('storage.db_only: no file and no commit', async () => {
await withBrain(databaseUrl, 'git', async b => {
writeFileSync(join(b.root, 'gbrain.yml'), 'storage:\n db_only:\n - wiki/originals\n');
b.git('add', 'gbrain.yml');
b.git('commit', '-qm', 'storage tiers');
const head = b.git('rev-parse', 'HEAD');
const result = await b.reverseWrite([IDEA]);
expect({ written: result.written, head: b.git('rev-parse', 'HEAD'), dirty: dirty(b), file: existsSync(b.path(IDEA)) })
.toEqual({ written: 0, head, dirty: '', file: false });
});
}, 180_000);
test('repo-less source (no local_path, no brain directory): no file anywhere, the database stays the record', async () => {
await withBrain(databaseUrl, 'none', async b => {
const result = await b.reverseWrite([IDEA, PLAN]);
expect({ written: result.written, held: result.held, files: filesUnder(b.root), page: (await b.engine.getPage(IDEA, { sourceId: SOURCE }))?.slug })
.toEqual({ written: 0, held: [], files: [], page: IDEA });
});
}, 180_000);
test('a local_path that is not a Git checkout keeps its files (there is no commit to make)', async () => {
await withBrain(databaseUrl, 'plain', async b => {
const result = await b.reverseWrite([IDEA]);
expect({ written: result.written, held: result.held, file: existsSync(b.path(IDEA)) }).toEqual({ written: 1, held: [], file: true });
});
}, 180_000);
test('#8935: a read-only mirror gets no dream file and no commit, and the pages stay in the database', async () => {
await withBrain(databaseUrl, 'git', async b => {
await setMirror(b.engine, SOURCE, true);
const head = b.git('rev-parse', 'HEAD');
const result = await b.reverseWrite([IDEA, PLAN]);
const summary = await writeDreamPageFile(b.engine, b.brainDir, SUMMARY, SOURCE,
{ nativeSourceId: SOURCE, markdown: serializePageToMarkdown((await b.engine.getPage(SUMMARY, { sourceId: SOURCE }))!, []) });
expect({ written: result.written, held: result.held, summary: summary.written, files: filesUnder(b.root), head: b.git('rev-parse', 'HEAD'), dirty: dirty(b) })
.toEqual({ written: 0, held: [], summary: false, files: ['README.md'], head, dirty: '' });
expect((await b.engine.getPage(PLAN, { sourceId: SOURCE }))?.title).toBe('Acme Example plan');
});
}, 180_000);
test('#8935: a read-only mirror keeps a tracked dream file as it is (no rewrite, no removal) until the source is writable again', async () => {
await withBrain(databaseUrl, 'git', async b => {
await b.reverseWrite([IDEA]);
const tracked = readFileSync(b.path(IDEA), 'utf8');
await importFromContent(b.engine, IDEA, page('Alice Example idea', 'A revision the dream made in the database.'), { noEmbed: true, sourceId: SOURCE });
await setMirror(b.engine, SOURCE, true);
const head = b.git('rev-parse', 'HEAD');
const rewrite = await b.reverseWrite([IDEA]);
const removal = await removeDreamPageFile(b.engine, b.brainDir, IDEA, SOURCE, SOURCE);
expect({ written: rewrite.written, held: rewrite.held, removed: removal.removed, bytes: existsSync(b.path(IDEA)) ? readFileSync(b.path(IDEA), 'utf8') : null, head: b.git('rev-parse', 'HEAD'), dirty: dirty(b) })
.toEqual({ written: 0, held: [], removed: false, bytes: tracked, head, dirty: '' });
await setMirror(b.engine, SOURCE, false);
expect({ written: (await b.reverseWrite([IDEA])).written, revised: readFileSync(b.path(IDEA), 'utf8').includes('A revision the dream made in the database.'), dirty: dirty(b) })
.toEqual({ written: 1, revised: true, dirty: '' });
});
}, 180_000);
test('#8935: a read-only mirror with no checkout gets nothing in the brain directory fallback, while a writable source in the same pass publishes', async () => {
await withBrain(databaseUrl, 'git', async b => {
await b.engine.executeRaw(`INSERT INTO sources (id, name, config) VALUES ($1, $1, '{"mirror_read_only": true}'::jsonb)`, [MIRROR]);
await importFromContent(b.engine, IDEA, page('Alice Example mirror idea', 'Kept in the database only.'), { noEmbed: true, sourceId: MIRROR });
const held: string[] = [];
const written = await reverseWriteDreamRefs(b.engine, b.brainDir, [{ slug: IDEA, source_id: MIRROR }, { slug: PLAN, source_id: SOURCE }],
{ phase: 'synthesize', nativeSourceId: SOURCE, render: (p, tags) => serializePageToMarkdown(p, tags), held });
expect({ written, held, fallback: existsSync(join(b.root, '.sources', MIRROR)), plan: existsSync(b.path(PLAN)), dirty: dirty(b) })
.toEqual({ written: 1, held: [], fallback: false, plan: true, dirty: '' });
expect((await b.engine.getPage(IDEA, { sourceId: MIRROR }))?.title).toBe('Alice Example mirror idea');
});
}, 180_000);
test('#8935: a writable source with no checkout gets no brain directory fallback file when that directory is a read-only mirror', async () => {
await withBrain(databaseUrl, 'git', async b => {
await setMirror(b.engine, SOURCE, true);
await b.engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1)', [MIRROR]);
await importFromContent(b.engine, IDEA, page('Alice Example other idea', 'Kept in the database only.'), { noEmbed: true, sourceId: MIRROR });
const head = b.git('rev-parse', 'HEAD');
const held: string[] = [];
const written = await reverseWriteDreamRefs(b.engine, b.brainDir, [{ slug: IDEA, source_id: MIRROR }],
{ phase: 'synthesize', nativeSourceId: SOURCE, render: (p, tags) => serializePageToMarkdown(p, tags), held });
const removal = await removeDreamPageFile(b.engine, b.brainDir, IDEA, MIRROR, SOURCE);
expect({ written, held, removed: removal.removed, fallback: existsSync(join(b.root, '.sources', MIRROR)), head: b.git('rev-parse', 'HEAD'), dirty: dirty(b) })
.toEqual({ written: 0, held: [], removed: false, fallback: false, head, dirty: '' });
expect((await b.engine.getPage(IDEA, { sourceId: MIRROR }))?.title).toBe('Alice Example other idea');
});
}, 180_000);
});
}