Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain pglite-repair` command surface (#223 WAL-repair wave) — SERIAL:
* the happy path does a real persistent-PGLite cold start (create → corrupt
* pg_wal → repair in place → reconnect), which is too heavy + lock-contended
* for the parallel unit shards.
*
* `runPgliteRepair` is imported directly (no process spawns); stdout/stderr
* are captured by spying console.log/console.error per test and restored in
* finally. Every case uses `--path <hermetic tmpdir>` so the user's real
* brain and config are never touched, and `--json` so assertions parse a
* machine receipt instead of prose.
*
* Refusal-order note (cases 5-7): the fake layout deliberately PASSES
* `validateWalRepairTarget` (PG_VERSION 17 + base/ + 8192-byte pg_control) so
* the command reaches its lock gates; an actual repair on the garbage
* pg_control would fail in resetWal, but all three cases must refuse BEFORE
* repair — asserting the refused_* codes proves the ordering.
*/
import { describe, test, expect } from 'bun:test';
import {
existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, rmSync, writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { basename, join } from 'node:path';
import { PassThrough } from 'node:stream';
import { runPgliteRepair } from '../src/commands/pglite-repair.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { withEnv } from './helpers/with-env.ts';
function tmp(prefix: string): string {
return mkdtempSync(join(tmpdir(), prefix));
}
/** Fake PG17 layout that passes validateWalRepairTarget (see file header). */
function makeFakeLayout(dir: string): void {
mkdirSync(join(dir, 'base'), { recursive: true });
mkdirSync(join(dir, 'global'), { recursive: true });
mkdirSync(join(dir, 'pg_wal'), { recursive: true });
writeFileSync(join(dir, 'PG_VERSION'), '17\n');
writeFileSync(join(dir, 'global', 'pg_control'), Buffer.alloc(8192));
}
/**
* Swap the global `process.stdin` for a fake TTY-flagged PassThrough for the
* duration of `fn`, writing `answer` to it shortly after `fn` starts (so the
* interactive `rl.question` inside `promptYesNo` has already attached its
* listener). Restores the real `process.stdin` in `finally` regardless of
* outcome. Confirmed to work under both node and bun (readline reads
* `process.stdin` at call time, not import time).
*/
async function withInteractiveAnswer<T>(answer: string, fn: () => Promise<T>): Promise<T> {
// Restore the ORIGINAL property descriptor, not just the original value:
// on Node this is a getter, and on Bun a plain data property whose
// writable/enumerable flags must match what we found.
const realStdinDescriptor = Object.getOwnPropertyDescriptor(process, 'stdin')!;
const fake = new PassThrough() as unknown as NodeJS.ReadStream;
(fake as unknown as { isTTY: boolean }).isTTY = true;
Object.defineProperty(process, 'stdin', { value: fake, configurable: true });
try {
const resultPromise = fn();
setTimeout(() => (fake as unknown as PassThrough).write(`${answer}\n`), 20);
return await resultPromise;
} finally {
Object.defineProperty(process, 'stdin', realStdinDescriptor);
}
}
function writeLockFile(dir: string, lock: Record<string, unknown>): string {
const lockDir = join(dir, '.gbrain-lock');
mkdirSync(lockDir, { recursive: true });
writeFileSync(join(lockDir, 'lock'), JSON.stringify(lock), { mode: 0o644 });
return lockDir;
}
interface Captured {
logs: string[];
errors: string[];
restore: () => void;
}
/** Spy console.log/console.error; caller MUST call restore() in finally. */
function captureConsole(): Captured {
const logs: string[] = [];
const errors: string[] = [];
const origLog = console.log;
const origErr = console.error;
console.log = (...args: unknown[]) => { logs.push(args.map(String).join(' ')); };
console.error = (...args: unknown[]) => { errors.push(args.map(String).join(' ')); };
return {
logs,
errors,
restore: () => {
console.log = origLog;
console.error = origErr;
},
};
}
/** Last parseable JSON object line from captured console.log output. */
function parseJsonLine(logs: string[]): Record<string, any> {
for (let i = logs.length - 1; i >= 0; i--) {
const line = logs[i].trim();
if (!line.startsWith('{')) continue;
try {
return JSON.parse(line) as Record<string, any>;
} catch { /* not this line — keep looking */ }
}
throw new Error(`no JSON line in captured output: ${JSON.stringify(logs)}`);
}
/**
* A PID that provably belongs to no live process: spawn a short-lived child,
* wait for it (spawnSync reaps it), then verify kill(pid, 0) throws. Retries
* to dodge instant PID reuse.
*/
function deadPid(): number {
for (let attempt = 0; attempt < 5; attempt++) {
const proc = Bun.spawnSync(['bash', '-c', 'exit 0']);
const pid = proc.pid;
try {
process.kill(pid, 0); // still alive/visible → PID reused, try again
} catch {
return pid;
}
}
throw new Error('could not obtain a provably-dead PID after 5 spawns');
}
/** The plan_hash `--dry-run --json` reports for a data dir (what `--yes --expect` must name). */
async function approvedPlanHash(dir: string): Promise<string> {
const cap = captureConsole();
try {
await runPgliteRepair(['--path', dir, '--dry-run', '--json']);
} finally {
cap.restore();
}
return parseJsonLine(cap.logs).plan_hash as string;
}
const backupDirsBeside = (dir: string): string[] =>
readdirSync(join(dir, '..')).filter((n) => n.startsWith(`${basename(dir)}.wal-repair-backup-`));
describe('gbrain pglite-repair — dry-run is strictly read-only', () => {
test('1. dry-run on a corrupt-ish layout: exit 0, JSON diagnosis, zero mutation', async () => {
const parent = tmp('gbrain-repair-dry-');
const dir = join(parent, 'brain.pglite');
makeFakeLayout(dir);
writeFileSync(join(dir, 'postmaster.pid'), `${deadPid()}\n`); // unclean-shutdown marker from a provably dead PID
const parentBefore = readdirSync(parent).sort();
const dirBefore = readdirSync(dir).sort();
const cap = captureConsole();
let rc: number;
try {
rc = await runPgliteRepair(['--dry-run', '--path', dir, '--json']);
} finally {
cap.restore();
}
expect(rc).toBe(0);
const out = parseJsonLine(cap.logs);
expect(out.status).toBe('ok');
expect(out.action).toBe('dry-run');
expect(out.data_dir).toBe(dir);
expect(out.validation.ok).toBe(true);
expect(out.diagnosis.verdict).toBeDefined();
expect(out.diagnosis.verdict).toBe('wal-corruption-likely');
// Read-only: no backup dirs, no sidecar, nothing added or removed.
expect(backupDirsBeside(dir)).toEqual([]);
expect(existsSync(`${dir}.wal-repair-attempt.json`)).toBe(false);
expect(readdirSync(parent).sort()).toEqual(parentBefore);
expect(readdirSync(dir).sort()).toEqual(dirBefore);
expect(existsSync(join(dir, 'postmaster.pid'))).toBe(true);
});
test('2. dry-run on a missing path: exit 0, validation.ok false, path NOT created', async () => {
const missing = join(tmp('gbrain-repair-dry-missing-'), 'never-created.pglite');
const cap = captureConsole();
let rc: number;
try {
rc = await runPgliteRepair(['--dry-run', '--path', missing, '--json']);
} finally {
cap.restore();
}
expect(rc).toBe(0);
const out = parseJsonLine(cap.logs);
expect(out.status).toBe('ok');
expect(out.action).toBe('dry-run');
expect(out.validation.ok).toBe(false);
expect(out.diagnosis.verdict).toBe('missing');
expect(existsSync(missing)).toBe(false);
});
});
describe('gbrain pglite-repair — refusals (validate before lock, never mkdir a typo)', () => {
test('3. non-dry-run on a missing path: exit 1, refused_missing-dir, path NOT created', async () => {
const missing = join(tmp('gbrain-repair-missing-'), 'typo.pglite');
const cap = captureConsole();
let rc: number;
try {
rc = await runPgliteRepair(['--path', missing, '--yes', '--json']);
} finally {
cap.restore();
}
expect(rc).toBe(1);
const out = parseJsonLine(cap.logs);
expect(out.status).toBe('error');
expect(out.code).toBe('refused_missing-dir');
// validate-before-lock: acquireLock would have mkdir'd the dir.
expect(existsSync(missing)).toBe(false);
});
test('5. live lock holder: exit 1, refused_locked, no repair attempted', async () => {
const dir = join(tmp('gbrain-repair-locked-'), 'brain.pglite');
makeFakeLayout(dir);
const lockDir = writeLockFile(dir, {
pid: process.pid, // this test process — provably alive
acquired_at: Date.now(),
refreshed_at: Date.now(),
command: 'gbrain embed',
subcommand: 'embed',
});
const cap = captureConsole();
let rc: number;
try {
rc = await runPgliteRepair(['--path', dir, '--yes', '--json']);
} finally {
cap.restore();
rmSync(lockDir, { recursive: true, force: true });
}
expect(rc).toBe(1);
const out = parseJsonLine(cap.logs);
expect(out.status).toBe('error');
expect(out.code).toBe('refused_locked');
// Refused BEFORE repair: no backup dir, no sidecar.
expect(backupDirsBeside(dir)).toEqual([]);
expect(existsSync(`${dir}.wal-repair-attempt.json`)).toBe(false);
});
test('6. reaped (dead-PID) lock: exit 1, refused_reaped_lock', async () => {
const dir = join(tmp('gbrain-repair-reaped-'), 'brain.pglite');
makeFakeLayout(dir);
writeLockFile(dir, {
pid: deadPid(), // dead in this exact boot/PID namespace — eligible for migration
pid_ns: process.platform === 'linux' ? readlinkSync('/proc/self/ns/pid') : null,
boot_id: process.platform === 'linux' ? readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim() : null,
acquired_at: Date.now() - 60_000,
refreshed_at: Date.now() - 60_000,
command: 'gbrain embed',
subcommand: 'embed',
});
const cap = captureConsole();
let rc: number;
try {
// Approved for the diagnosed plan, so the refusal under test is the lock gate's.
rc = await runPgliteRepair(['--path', dir, '--yes', '--expect', await approvedPlanHash(dir), '--json']);
} finally {
cap.restore();
}
expect(rc).toBe(1);
const out = parseJsonLine(cap.logs);
expect(out.status).toBe('error');
expect(out.code).toBe('refused_reaped_lock');
// Refused BEFORE repair: no backup dir, no sidecar.
expect(backupDirsBeside(dir)).toEqual([]);
expect(existsSync(`${dir}.wal-repair-attempt.json`)).toBe(false);
}, 30_000);
test('7. live serve holder: exit 1, refused_locked names the PID', async () => {
const dir = join(tmp('gbrain-repair-serve-'), 'brain.pglite');
makeFakeLayout(dir);
const lockDir = writeLockFile(dir, {
pid: process.pid, // alive — the pre-lock diagnosis catches it as 'locked'
acquired_at: Date.now(),
refreshed_at: Date.now(),
command: 'gbrain serve',
subcommand: 'serve',
});
const cap = captureConsole();
let rc: number;
try {
rc = await runPgliteRepair(['--path', dir, '--yes', '--json']);
} finally {
cap.restore();
rmSync(lockDir, { recursive: true, force: true });
}
expect(rc).toBe(1);
const out = parseJsonLine(cap.logs);
expect(out.status).toBe('error');
expect(out.code).toBe('refused_locked');
expect(out.message).toContain(String(process.pid));
expect(backupDirsBeside(dir)).toEqual([]);
});
});
describe('gbrain pglite-repair — TTY + config gates', () => {
test('8. non-TTY without the bound approval refuses: exit 3, consent payload with risk + undo, zero mutation', async () => {
const dir = join(tmp('gbrain-repair-notty-'), 'brain.pglite');
makeFakeLayout(dir);
const cap = captureConsole();
let stdout = '';
const write = process.stdout.write;
process.stdout.write = ((c: string | Uint8Array) => { stdout += String(c); return true; }) as typeof process.stdout.write;
let rc: number;
let bare: number;
try {
rc = await withEnv({ GBRAIN_NON_INTERACTIVE: '1' }, () => runPgliteRepair(['--path', dir, '--json'])); // no --yes
// A bare --yes retry is not the user's approval of this plan.
bare = await withEnv({ GBRAIN_NON_INTERACTIVE: '1' }, () => runPgliteRepair(['--path', dir, '--yes', '--json']));
} finally {
process.stdout.write = write;
cap.restore();
process.exitCode = 0;
}
expect(rc).toBe(3);
expect(bare).toBe(3);
const out = JSON.parse(stdout.slice(0, stdout.indexOf('\n}\n') + 2));
expect(out).toMatchObject({ code: 'confirmation_required', effects: ['destructive'], actor: 'agent' });
expect(out.risk).toContain('may be lost');
expect(out.risk).toContain('Undo, with gbrain stopped: mv');
expect(out.fix.argv).toEqual(['gbrain', 'pglite-repair', '--path', dir, '--json', '--yes', '--expect', out.plan_hash]);
expect(out.user_message).toContain('Reset its write-ahead log now?');
// Refused BEFORE any surgery: no backup dir, no sidecar.
expect(backupDirsBeside(dir)).toEqual([]);
expect(existsSync(`${dir}.wal-repair-attempt.json`)).toBe(false);
});
test('9. interactive "y" answer proceeds with repair (#4318 close-before-resolve race)', async () => {
// Regression for #4318: the old inline promptYesNo in this file called
// rl.close() BEFORE resolving the answer, and its unguarded
// rl.on('close', () => resolve(false)) fired synchronously during that
// close — so a typed "y" still resolved false and the command took the
// "Aborted" branch. This pins that a "y" answer is honored end-to-end
// through the actual interactive confirm gate (not just via the shared
// helper's own unit tests in test/confirm-prompt.test.ts).
const dir = join(tmp('gbrain-repair-interactive-'), 'brain.pglite');
makeFakeLayout(dir);
const cap = captureConsole();
const origOutTty = Object.getOwnPropertyDescriptor(process.stdout, 'isTTY');
Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
try {
await withEnv({ GBRAIN_INTERACTIVE: '1' }, () => withInteractiveAnswer('y', () => runPgliteRepair(['--path', dir, '--json'])));
} finally {
cap.restore();
if (origOutTty) Object.defineProperty(process.stdout, 'isTTY', origOutTty);
else delete (process.stdout as unknown as Record<string, unknown>).isTTY;
}
const out = parseJsonLine(cap.logs);
// The race resolved the confirm to `false` even for a typed "y" — the
// broken behavior always produced this exact receipt. Assert its absence
// rather than a specific return code, since what happens AFTER a
// correctly-honored "y" (repair attempted on this fake layout) is
// covered by other tests in this file.
expect(out).not.toEqual({ status: 'aborted', reason: 'user_declined' });
expect(out.code).not.toBe('confirmation_required');
}, 30_000);
test('10. no --path with a non-pglite configured engine: exit 1, not_pglite', async () => {
// Hermetic GBRAIN_HOME (same convention as apply-migrations-pglite-spawn):
// configDir() appends '.gbrain', so the config lands at <home>/.gbrain/.
const home = tmp('gbrain-repair-home-');
mkdirSync(join(home, '.gbrain'), { recursive: true });
writeFileSync(
join(home, '.gbrain', 'config.json'),
JSON.stringify({ engine: 'postgres', database_url: 'postgresql://localhost:5432/x' }) + '\n',
);
const cap = captureConsole();
let rc: number;
try {
rc = await withEnv({ GBRAIN_HOME: home }, () => runPgliteRepair(['--yes', '--json']));
} finally {
cap.restore();
}
expect(rc).toBe(1);
const out = parseJsonLine(cap.logs);
expect(out.status).toBe('error');
expect(out.code).toBe('not_pglite');
expect(out.message).toContain('--path');
});
});
describe('gbrain pglite-repair — the happy path (real PGLite)', () => {
test('4. corrupt pg_wal → repair in place → data survives, no auto-repair on reconnect', async () => {
const dir = join(tmp('gbrain-repair-happy-'), 'brain.pglite');
// 1) Real brain with a probe row, closed cleanly.
const engine = new PGLiteEngine();
await engine.connect({ database_path: dir });
try {
await engine.executeRaw('CREATE TABLE repair_probe(id int)');
await engine.executeRaw('INSERT INTO repair_probe VALUES (42)');
} finally {
await engine.disconnect();
}
// 2) Corrupt every WAL segment with garbage.
const walDir = join(dir, 'pg_wal');
const segments = readdirSync(walDir).filter((f) => /^[0-9A-F]{24}$/.test(f));
expect(segments.length).toBeGreaterThan(0); // sanity: there IS WAL to corrupt
for (const seg of segments) {
writeFileSync(join(walDir, seg), Buffer.alloc(1024, 0xff));
}
// 3) Repair in place, approved for the diagnosed plan (C2: --yes --expect <plan_hash>).
const dry = captureConsole();
try {
expect(await runPgliteRepair(['--path', dir, '--dry-run', '--json'])).toBe(0);
} finally {
dry.restore();
}
const planHash = parseJsonLine(dry.logs).plan_hash as string;
expect(planHash).toMatch(/^ph_/);
const cap = captureConsole();
let rc: number;
try {
rc = await runPgliteRepair(['--path', dir, '--yes', '--expect', planHash, '--json']);
} finally {
cap.restore();
}
expect(rc).toBe(0);
const receipt = parseJsonLine(cap.logs);
expect(receipt.status).toBe('ok');
expect(receipt.action).toBe('repaired');
expect(receipt.data_dir).toBe(dir);
expect(receipt.reset_segment).toMatch(/^[0-9A-F]{24}$/);
expect(existsSync(receipt.backup_path)).toBe(true);
expect(existsSync(join(receipt.backup_path, 'pg_wal'))).toBe(true);
expect(receipt.restore_command).toContain(`${receipt.backup_path}/pg_wal`);
// 4) The repaired dir opens WITHOUT auto-repair firing, data intact.
const engine2 = new PGLiteEngine();
await engine2.connect({ database_path: dir });
try {
expect(engine2.walRepairReceipt).toBeNull();
const rows = await engine2.executeRaw<{ id: number }>('SELECT id FROM repair_probe');
expect(rows.length).toBe(1);
expect(rows[0].id).toBe(42);
} finally {
await engine2.disconnect();
}
}, 180_000);
});
describe('gbrain pglite-repair — argument + quarantine hardening (adversarial fixes)', () => {
test('unknown flag is rejected (exit 2), not silently ignored on a destructive command', async () => {
const cap = captureConsole();
let rc: number;
try {
rc = await runPgliteRepair(['--dry-rnu', '--yes', '--json']);
} finally {
cap.restore();
}
expect(rc).toBe(2);
expect(parseJsonLine(cap.logs).code).toBe('unknown_flag');
});
test('--path with no value is rejected (does NOT retarget the default brain)', async () => {
const cap = captureConsole();
let rc: number;
try {
rc = await runPgliteRepair(['--yes', '--json', '--path']);
} finally {
cap.restore();
}
expect(rc).toBe(2);
expect(parseJsonLine(cap.logs).code).toBe('unknown_flag');
});
test('the command honors the cross-process reap quarantine (F3: a second --yes cannot bypass it)', async () => {
const dir = join(mkdtempSync(join(tmpdir(), 'pgrepaircmd-')), 'brain.pglite');
makeFakeLayout(dir);
// A fresh corrupt-lock reap marker from a prior run — the possibly-live
// writer it protects must not be repaired under.
writeFileSync(`${dir}.lock-reap.json`, JSON.stringify({ ts: Date.now(), by: 999999 }), { mode: 0o644 });
const cap = captureConsole();
let rc: number;
try {
rc = await runPgliteRepair(['--path', dir, '--yes', '--json']);
} finally {
cap.restore();
}
expect(rc).toBe(1);
expect(parseJsonLine(cap.logs).code).toBe('refused_reap_quarantine');
// No surgery: no backup dir created.
expect(readdirSync(join(dir, '..')).some((f) => f.includes('.wal-repair-backup-'))).toBe(false);
});
});
describe('gbrain pglite-repair — interactive confirm wiring (#4318 residual)', () => {
test('asks through the consent primitive, not a local prompt', () => {
// #4318 class: a local promptYesNo/readline here once read a typed "y" as
// decline. The prompt now lives in requireConsent (interaction.readLine on
// stderr, EOF/timeout = decline); this pins that no local prompt returns.
// test-reads-source-ok[structural]: no injectable seam names the prompt implementation.
const src = readFileSync(join(import.meta.dir, '../src/commands/pglite-repair.ts'), 'utf8');
expect(src).toContain("import { consentGate } from '../core/consent-cli.ts';");
expect(src).not.toMatch(/\bfunction promptYesNo\b/);
expect(src).not.toContain('promptYesNo(');
expect(src).not.toContain("from 'readline'");
expect(src).not.toContain("from 'node:readline'");
});
;
});