Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

test(cycle): #8073 dream reverse-write commits and crash-left batches are swept (red)

garrytanadf9324c9524
diff --git a/src/core/cycle/derived-write-through.ts b/src/core/cycle/derived-write-through.ts
index 5e316c1e30..aa55d2ad69 100644
--- a/src/core/cycle/derived-write-through.ts
+++ b/src/core/cycle/derived-write-through.ts
@@ -91,6 +91,9 @@ interface DerivedFileChange { slug: string; sourceId: string; filePath: string;
/** A batch commit the checkout refused: the door's code and message, the batch's files (root-relative) and those left as they were. */
export interface DerivedCommitFailure { code: string; message: string; paths: string[]; kept: string[] }
+/** Test seam: runs after a batch's files are written and before its commit; a throw stands in for a crash (no rollback). */
+export const derivedWriteSeams: { beforeCommit?: (root: string) => void } = {};
+
/** How long a batch waits for the checkout's commit lock before it rolls back. */
const DERIVED_COMMIT_LOCK_WAIT_MS = 30_000;
@@ -162,6 +165,7 @@ async function commitDerivedChanges(engine: BrainEngine, phase: keyof typeof DER
for (const root of new Set(changes.map(c => c.writeRoot))) {
const batch = changes.filter(c => c.writeRoot === root);
if (classifyGitCheckout(root) === 'not_git') continue;
+ derivedWriteSeams.beforeCommit?.(root);
try {
await withSourceFilesystemLock(engine, root, async () => {
const rels = batch.map(c => relative(root, c.filePath));
diff --git a/test/cycle/derived-write-through-commit.test.ts b/test/cycle/derived-write-through-commit.test.ts
index 4ecb2dcb5a..36ffe2093a 100644
--- a/test/cycle/derived-write-through-commit.test.ts
+++ b/test/cycle/derived-write-through-commit.test.ts
@@ -18,8 +18,9 @@
* reports nothing; a local_path that is not a Git checkout keeps its files.
* Fails when: the hook writes files and leaves them uncommitted (the pre-fix
* path), commits one file at a time, or leaves files behind after a refused
- * commit.
- * Seams: the phases' `_transcripts` / `_chat` / `_atoms` test inputs (no paid
+ * commit. A crash between a batch's file writes and its commit (the `derivedWriteSeams.beforeCommit` fault point)
+ * leaves the files on disk, and the next run's batch commit sweeps them in through the door's pending ledger.
+ * Seams: `derivedWriteSeams.beforeCommit` (a throw there stands in for a process crash: no rollback runs), the phases' `_transcripts` / `_chat` / `_atoms` test inputs (no paid
* call). PGLite always, Postgres when DATABASE_URL is set.
*/
import { describe, expect, test } from 'bun:test';
@@ -28,6 +29,7 @@ import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, wri
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { ChatOpts, ChatResult } from '../../src/core/ai/gateway.ts';
+import { derivedWriteSeams } from '../../src/core/cycle/derived-write-through.ts';
import { runPhaseExtractAtoms } from '../../src/core/cycle/extract-atoms.ts';
import { runPhaseSynthesizeConcepts } from '../../src/core/cycle/synthesize-concepts.ts';
import type { BrainEngine } from '../../src/core/engine.ts';
@@ -45,7 +47,7 @@ interface Brain {
git(...args: string[]): string;
path(slug: string): string;
atoms(live?: boolean): Promise<Array<{ slug: string; source_path: string | null }>>;
- extract(titles: string[], hash: string | null): Promise<{ status: string; failed: Array<{ code: string; paths: string[] }> }>;
+ extract(titles: string[], hash: string | null, filePath?: string): Promise<{ status: string; failed: Array<{ code: string; paths: string[] }> }>;
}
const chat = (titles: string[]) => async (_o: ChatOpts): Promise<ChatResult> => {
@@ -83,9 +85,9 @@ async function withBrain(databaseUrl: string | undefined, layout: Layout, run: (
path: slug => join(root, `${slug}.md`),
atoms: async (live = true) => engine.executeRaw<{ slug: string; source_path: string | null }>(
"SELECT slug, source_path FROM pages WHERE type = 'atom' AND (deleted_at IS NULL) = $1 ORDER BY slug", [live]),
- async extract(titles, hash) {
+ async extract(titles, hash, filePath = '/fake/2026-09-07-meeting.txt') {
const result = await runPhaseExtractAtoms(engine, {
- _transcripts: hash ? [{ filePath: '/fake/2026-09-07-meeting.txt', content: 'content', contentHash: hash }] : [], _pages: [], _chat: chat(titles),
+ _transcripts: hash ? [{ filePath, content: 'content', contentHash: hash }] : [], _pages: [], _chat: chat(titles),
});
const failed = (result.details as { write_through_failed?: Array<{ code: string; paths: string[] }> }).write_through_failed ?? [];
return { status: result.status, failed };
@@ -180,6 +182,23 @@ for (const { backend, databaseUrl } of pathologicalArms()) {
});
}, 180_000);
+ test('a crash between the file writes and the commit: the next run\'s batch commit sweeps the files it left', async () => {
+ await withBrain(databaseUrl, 'git', async b => {
+ derivedWriteSeams.beforeCommit = () => { throw new Error('simulated crash before the batch commit'); };
+ try {
+ await b.extract(['Renders vs proof'], 'hash-one').catch(() => undefined);
+ } finally {
+ delete derivedWriteSeams.beforeCommit;
+ }
+ const [crashed] = (await b.atoms()).map(a => a.slug);
+ expect({ file: existsSync(b.path(crashed!)), dirty: dirty(b) }).toEqual({ file: true, dirty: `?? ${relOf(crashed!)}` });
+ await b.extract(['Founder lesson'], 'hash-two', '/fake/2026-09-08-meeting.txt');
+ const slugs = (await b.atoms()).map(a => a.slug);
+ expect(slugs).toContain(crashed!);
+ expect({ dirty: dirty(b), paths: lastCommitPaths(b) }).toEqual({ dirty: '', paths: slugs.map(relOf).sort() });
+ });
+ }, 180_000);
+
test('storage.db_only: atoms stay database-only and nothing is committed', async () => {
await withBrain(databaseUrl, 'git', async b => {
writeFileSync(join(b.root, 'gbrain.yml'), 'storage:\n db_only:\n - atoms/\n');
diff --git a/test/cycle/dream-reverse-write-commit.test.ts b/test/cycle/dream-reverse-write-commit.test.ts
new file mode 100644
index 0000000000..ca5b7c7cf0
--- /dev/null
+++ b/test/cycle/dream-reverse-write-commit.test.ts
@@ -0,0 +1,179 @@
+/**
+ * #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. 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 { renderPageToMarkdown } from '../../src/core/cycle/synthesize.ts';
+import type { BrainEngine } from '../../src/core/engine.ts';
+import { importFromContent } from '../../src/core/import-file.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';
+
+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: renderPageToMarkdown, 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 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: renderPageToMarkdown((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);
+
+ 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);
+ });
+}