Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain db-repair` — engine-free Postgres-access repair. In-process tests
* against runDbRepair via the exported DbRepairDeps seam: probes are queued
* fake diagnoses (built with the real classifier so shapes never drift),
* docker is absent, sleep is a no-op, now is frozen. GBRAIN_HOME points at a
* fresh temp dir per test so config/receipts/undo/lock files stay hermetic.
*
* Pins the consent ladder end to end:
* - flag gating (--apply-rewrites/--undo-last-rewrite require --yes)
* - refusal paths (no config, pglite redirect, thin client, env-source URL)
* - diagnose-only default mutates nothing
* - auto tier (bounded reconnect), manual tier (recipe only, no writes)
* - rewrite tier: gating, candidate-probe-before-persist, undo file (0600),
* 24h cooldown on applied rows only, --force bypass, --undo-last-rewrite
* - receipts cap + advisory lock liveness
*/
import { describe, test, expect, beforeEach, afterEach, spyOn } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { spawnSync } from 'node:child_process';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { runDbRepair, type DbRepairDeps } from '../src/commands/db-repair.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import { classifyPgAccessError, type PgAccessDiagnosis } from '../src/core/pg-access-classify.ts';
import { RECEIPTS_CAP, readReceipts, receiptsPath, rewriteCooldownBlocked, writeReceipt, type RepairReceipt } from '../src/core/db-repair-receipts.ts';
import { deriveSessionPoolerUrl } from '../src/core/connection-manager.ts';
// ---------------------------------------------------------------------------
// Fixtures
// ---------------------------------------------------------------------------
const FIXED_NOW = Date.now();
const HOUR = 3600_000;
const PLAIN_PG_URL = 'postgresql://u:pw@localhost:5432/gbrain';
const POOLER_URL = 'postgresql://postgres.abc123:[email protected]:6543/postgres';
const SESSION_URL = deriveSessionPoolerUrl(POOLER_URL)!;
function errWith(code: string, message: string): Error {
const e = new Error(message) as Error & { code: string };
e.code = code;
return e;
}
const connRefusedDiag = (url: string = PLAIN_PG_URL): PgAccessDiagnosis =>
classifyPgAccessError(errWith('ECONNREFUSED', 'connect ECONNREFUSED 127.0.0.1:5432'), { url, source: 'config-file' });
const sslRequiredDiag = (url: string = PLAIN_PG_URL): PgAccessDiagnosis =>
classifyPgAccessError(
new Error('no pg_hba.conf entry for host "1.2.3.4", user "u", database "d", no encryption'),
{ url, source: 'config-file' },
);
const connDroppedDiag = (): PgAccessDiagnosis =>
classifyPgAccessError(errWith('CONNECTION_ENDED', 'CONNECTION_ENDED: the connection was ended'), { url: PLAIN_PG_URL, source: 'config-file' });
const authFailedDiag = (): PgAccessDiagnosis =>
classifyPgAccessError(errWith('28P01', 'password authentication failed for user "postgres"'), { url: PLAIN_PG_URL, source: 'config-file' });
const netUnreachDiag = (url: string = POOLER_URL): PgAccessDiagnosis =>
classifyPgAccessError(errWith('ETIMEDOUT', 'connect ETIMEDOUT 1.2.3.4:5432'), { url, source: 'config-file' });
interface FakeDeps {
deps: DbRepairDeps;
accessCalls: Array<{ url: string | null | undefined; attempts: number | undefined }>;
}
/** Queued-diagnosis deps: probes shift their queue; exhausted queue = healthy.
* `docker`/`withEngine` are injectable for the docker arm + healthy-path
* bonus-report tests; the defaults keep every other test's guarantees
* (docker absent, withEngine unreachable). */
function makeDeps(
opts: {
access?: Array<PgAccessDiagnosis | null>;
schema?: Array<PgAccessDiagnosis | null>;
now?: number;
docker?: DbRepairDeps['docker'];
withEngine?: DbRepairDeps['withEngine'];
} = {},
): FakeDeps {
const accessQueue = [...(opts.access ?? [])];
const schemaQueue = [...(opts.schema ?? [])];
const accessCalls: FakeDeps['accessCalls'] = [];
const deps: DbRepairDeps = {
async probeAccess(config, attempts) {
accessCalls.push({ url: config.database_url, attempts });
return accessQueue.length > 0 ? accessQueue.shift()! : null;
},
async probeSchema() {
return schemaQueue.length > 0 ? schemaQueue.shift()! : null;
},
withEngine:
opts.withEngine ??
(async () => {
throw new Error('withEngine must not be reached in these tests');
}),
docker: opts.docker ?? { available: () => false, state: () => 'absent' as const, start: () => false },
sleep: async () => {},
now: () => opts.now ?? FIXED_NOW,
};
return { deps, accessCalls };
}
// ---------------------------------------------------------------------------
// Hermetic home + console capture
// ---------------------------------------------------------------------------
const ENV_KEYS = ['GBRAIN_HOME', 'GBRAIN_DATABASE_URL', 'DATABASE_URL', 'GBRAIN_BRAIN_ID', 'GBRAIN_MOUNTS_PATH'] as const;
const envSnapshot: Record<string, string | undefined> = {};
let home: string;
let logs: string[];
let errs: string[];
let logSpy: ReturnType<typeof spyOn>;
let errSpy: ReturnType<typeof spyOn>;
beforeEach(() => {
for (const k of ENV_KEYS) envSnapshot[k] = process.env[k];
home = mkdtempSync(join(tmpdir(), 'gbrain-db-repair-'));
process.env.GBRAIN_HOME = home;
delete process.env.GBRAIN_DATABASE_URL;
delete process.env.DATABASE_URL;
delete process.env.GBRAIN_BRAIN_ID;
delete process.env.GBRAIN_MOUNTS_PATH;
mkdirSync(join(home, '.gbrain'), { recursive: true });
logs = [];
errs = [];
logSpy = spyOn(console, 'log').mockImplementation((...a: unknown[]) => { logs.push(a.map(String).join(' ')); });
errSpy = spyOn(console, 'error').mockImplementation((...a: unknown[]) => { errs.push(a.map(String).join(' ')); });
});
afterEach(() => {
logSpy.mockRestore();
errSpy.mockRestore();
for (const k of ENV_KEYS) {
if (envSnapshot[k] === undefined) delete process.env[k];
else process.env[k] = envSnapshot[k];
}
rmSync(home, { recursive: true, force: true });
});
function configPath(): string {
return join(home, '.gbrain', 'config.json');
}
function writeConfig(cfg: Record<string, unknown>): void {
writeFileSync(configPath(), JSON.stringify(cfg, null, 2) + '\n');
}
function readConfig(): Record<string, unknown> {
return JSON.parse(readFileSync(configPath(), 'utf-8'));
}
function undoFile(): string {
return join(home, '.gbrain', 'db-repair-undo.json');
}
function lockFile(): string {
return join(home, '.gbrain', 'db-repair.lock');
}
function receipt(overrides: Partial<RepairReceipt>): RepairReceipt {
return { ts: FIXED_NOW, brain_id: 'host', reason: 'network_unreachable', action: 'rewrite_to_session_pooler', outcome: 'applied', ...overrides };
}
// ---------------------------------------------------------------------------
describe('db-repair flag gating', () => {
test('unknown flag → exit 2', async () => {
expect(await runDbRepair(['--wat'], makeDeps().deps)).toBe(2);
expect(errs.join('\n')).toContain('Unknown flag for db-repair');
});
test('--apply-rewrites without --yes → exit 2', async () => {
expect(await runDbRepair(['--apply-rewrites'], makeDeps().deps)).toBe(2);
expect(errs.join('\n')).toContain('--apply-rewrites requires --yes');
});
test('--undo-last-rewrite without --yes → exit 2', async () => {
expect(await runDbRepair(['--undo-last-rewrite'], makeDeps().deps)).toBe(2);
expect(errs.join('\n')).toContain('--undo-last-rewrite requires --yes');
});
test('--help → exit 0', async () => {
expect(await runDbRepair(['--help'], makeDeps().deps)).toBe(0);
expect(logs.join('\n')).toContain('gbrain db-repair');
});
});
describe('db-repair refusal paths', () => {
test('no config → exit 1 with the manual no_url path + diagnose receipt', async () => {
const { deps } = makeDeps();
expect(await runDbRepair([], deps)).toBe(1);
const rows = readReceipts();
expect(rows.length).toBe(1);
expect(rows[0].reason).toBe('no_url');
expect(rows[0].outcome).toBe('diagnose');
});
test('pglite config → exit 1 with the pglite-repair redirect', async () => {
writeConfig({ engine: 'pglite', database_path: join(home, '.gbrain', 'brain.pglite') });
expect(await runDbRepair([], makeDeps().deps)).toBe(1);
expect(errs.join('\n')).toContain('pglite-repair');
});
test('thin-client config → exit 1 (no local database to repair)', async () => {
writeConfig({ remote_mcp: { url: 'https://brain.example.com/mcp' } });
expect(await runDbRepair([], makeDeps().deps)).toBe(1);
expect(errs.join('\n')).toContain('thin client');
});
});
describe('db-repair diagnose + auto/manual tiers', () => {
test('healthy probes → exit 0, diagnose receipt', async () => {
writeConfig({ engine: 'postgres', database_url: PLAIN_PG_URL });
const { deps } = makeDeps({ access: [null], schema: [null] });
expect(await runDbRepair([], deps)).toBe(0);
const rows = readReceipts();
expect(rows.length).toBe(1);
expect(rows[0].outcome).toBe('diagnose');
expect(rows[0].action).toBe('diagnose_healthy');
});
test('diagnose-only default: conn_refused, no --yes → exit 1, config byte-unchanged', async () => {
writeConfig({ engine: 'postgres', database_url: PLAIN_PG_URL });
const before = readFileSync(configPath(), 'utf-8');
const d = connRefusedDiag();
expect(d.reason).toBe('conn_refused');
const { deps, accessCalls } = makeDeps({ access: [d] });
expect(await runDbRepair([], deps)).toBe(1);
expect(accessCalls.length).toBe(1); // diagnose only — no repair probes
const rows = readReceipts();
expect(rows.length).toBe(1);
expect(rows[0].outcome).toBe('diagnose');
expect(rows[0].reason).toBe('conn_refused');
expect(readFileSync(configPath(), 'utf-8')).toBe(before);
expect(existsSync(undoFile())).toBe(false);
});
test('auto tier: conn_dropped + --yes, retry probe (attempts=3) heals → exit 0, bounded_reconnect applied', async () => {
writeConfig({ engine: 'postgres', database_url: PLAIN_PG_URL });
const d = connDroppedDiag();
expect(d.reason).toBe('conn_dropped');
const { deps, accessCalls } = makeDeps({ access: [d, null] });
expect(await runDbRepair(['--yes'], deps)).toBe(0);
expect(accessCalls[1].attempts).toBe(3); // the bounded reconnect ladder
const applied = readReceipts().filter((r) => r.outcome === 'applied');
expect(applied.length).toBe(1);
expect(applied[0].action).toBe('bounded_reconnect');
expect(applied[0].reason).toBe('conn_dropped');
});
test('manual tier: auth_failed + --yes → exit 1, no applied receipts, config unchanged', async () => {
writeConfig({ engine: 'postgres', database_url: PLAIN_PG_URL });
const before = readFileSync(configPath(), 'utf-8');
const d = authFailedDiag();
expect(d.reason).toBe('auth_failed');
const { deps } = makeDeps({ access: [d] });
expect(await runDbRepair(['--yes'], deps)).toBe(1);
expect(readReceipts().filter((r) => r.outcome === 'applied').length).toBe(0);
expect(readFileSync(configPath(), 'utf-8')).toBe(before);
expect(logs.join('\n')).toContain('Manual fix required');
});
});
describe('db-repair rewrite tier', () => {
test('network_unreachable + --yes WITHOUT --apply-rewrites → refused, exit 1, config unchanged', async () => {
writeConfig({ engine: 'postgres', database_url: POOLER_URL });
const before = readFileSync(configPath(), 'utf-8');
const d = netUnreachDiag();
expect(d.reason).toBe('network_unreachable');
const { deps } = makeDeps({ access: [d] });
expect(await runDbRepair(['--yes'], deps)).toBe(1);
const rows = readReceipts();
expect(rows.length).toBe(1);
expect(rows[0].outcome).toBe('refused');
expect(rows[0].action).toBe('rewrite_to_session_pooler');
expect(readFileSync(configPath(), 'utf-8')).toBe(before);
expect(existsSync(undoFile())).toBe(false);
expect(logs.join('\n')).toContain('--apply-rewrites');
});
test('--yes --apply-rewrites: candidate probes healthy → session-pooler rewrite persisted + 0600 undo file', async () => {
writeConfig({ engine: 'postgres', database_url: POOLER_URL });
// Probe order: initial access (fails) → candidate probe → post-persist re-probe.
const { deps, accessCalls } = makeDeps({ access: [netUnreachDiag(), null, null] });
expect(await runDbRepair(['--yes', '--apply-rewrites'], deps)).toBe(0);
// Config now carries the session-pooler form: same host, port 5432.
const cfg = readConfig();
expect(cfg.database_url).toBe(SESSION_URL);
expect(String(cfg.database_url)).toContain('aws-0-us-east-1.pooler.supabase.com:5432');
expect(cfg.engine).toBe('postgres');
// Candidate was probed BEFORE persisting, against the new URL.
expect(accessCalls[1].url).toBe(SESSION_URL);
expect(accessCalls[2].url).toBe(SESSION_URL);
// Undo file holds the PRIOR (secret) url at mode 0600.
expect(existsSync(undoFile())).toBe(true);
const undo = JSON.parse(readFileSync(undoFile(), 'utf-8'));
expect(undo.prior_url).toBe(POOLER_URL);
expect(statSync(undoFile()).mode & 0o777).toBe(0o600);
const applied = readReceipts().filter((r) => r.outcome === 'applied');
expect(applied.length).toBe(1);
expect(applied[0].action).toBe('rewrite_to_session_pooler');
});
test('candidate probe fails → rewrite refused, config unchanged', async () => {
writeConfig({ engine: 'postgres', database_url: POOLER_URL });
const before = readFileSync(configPath(), 'utf-8');
const { deps } = makeDeps({ access: [netUnreachDiag(), netUnreachDiag(SESSION_URL)] });
expect(await runDbRepair(['--yes', '--apply-rewrites'], deps)).toBe(1);
expect(readFileSync(configPath(), 'utf-8')).toBe(before);
expect(existsSync(undoFile())).toBe(false);
const rows = readReceipts();
expect(rows.filter((r) => r.outcome === 'applied').length).toBe(0);
expect(rows.filter((r) => r.outcome === 'refused').length).toBe(1);
});
test('cooldown: applied same (reason, action) 1h ago → refused; --force bypasses', async () => {
writeConfig({ engine: 'postgres', database_url: POOLER_URL });
writeReceipt(receipt({ ts: FIXED_NOW - HOUR }));
const first = makeDeps({ access: [netUnreachDiag()] });
expect(await runDbRepair(['--yes', '--apply-rewrites'], first.deps)).toBe(1);
expect(readConfig().database_url).toBe(POOLER_URL); // unchanged
const refusedRows = readReceipts().filter((r) => r.outcome === 'refused');
expect(refusedRows.length).toBe(1);
expect(errs.concat(logs).join('\n')).toContain('cooldown');
const forced = makeDeps({ access: [netUnreachDiag(), null, null] });
expect(await runDbRepair(['--yes', '--apply-rewrites', '--force'], forced.deps)).toBe(0);
expect(readConfig().database_url).toBe(SESSION_URL);
});
test("cooldown: 'refused'/'diagnose' rows never block a rewrite", async () => {
writeConfig({ engine: 'postgres', database_url: POOLER_URL });
writeReceipt(receipt({ ts: FIXED_NOW - 1000, outcome: 'refused' }));
writeReceipt(receipt({ ts: FIXED_NOW - 1000, outcome: 'diagnose' }));
const { deps } = makeDeps({ access: [netUnreachDiag(), null, null] });
expect(await runDbRepair(['--yes', '--apply-rewrites'], deps)).toBe(0);
expect(readConfig().database_url).toBe(SESSION_URL);
});
test('undo: --yes --undo-last-rewrite restores the prior url; the undo file now points back at the rewrite', async () => {
writeConfig({ engine: 'postgres', database_url: POOLER_URL });
const rewrite = makeDeps({ access: [netUnreachDiag(), null, null] });
expect(await runDbRepair(['--yes', '--apply-rewrites'], rewrite.deps)).toBe(0);
expect(readConfig().database_url).toBe(SESSION_URL);
const undo = makeDeps({ access: [null] });
expect(await runDbRepair(['--yes', '--undo-last-rewrite'], undo.deps)).toBe(0);
expect(readConfig().database_url).toBe(POOLER_URL);
// Undo is itself reversible: the outgoing (rewritten) URL becomes the
// new undo record so an accidental undo can't destroy a probed fix.
expect(existsSync(undoFile())).toBe(true);
expect(JSON.parse(readFileSync(undoFile(), 'utf-8')).prior_url).toBe(SESSION_URL);
expect(undo.accessCalls[0].url).toBe(POOLER_URL); // re-probed against the restored url
const undoRows = readReceipts().filter((r) => r.reason === 'undo');
expect(undoRows.length).toBe(1);
expect(undoRows[0].action).toBe('undo_last_rewrite');
expect(undoRows[0].outcome).toBe('applied');
});
test('undo with no undo record → exit 1', async () => {
writeConfig({ engine: 'postgres', database_url: POOLER_URL });
expect(await runDbRepair(['--yes', '--undo-last-rewrite'], makeDeps().deps)).toBe(1);
expect(errs.join('\n')).toContain('No rewrite to undo');
});
test('env-source URL: rewrite REFUSED (an env var cannot be rewritten), exit 1', async () => {
// No config file — the URL comes from GBRAIN_DATABASE_URL alone.
process.env.GBRAIN_DATABASE_URL = POOLER_URL;
const { deps } = makeDeps({ access: [netUnreachDiag()] });
expect(await runDbRepair(['--yes', '--apply-rewrites'], deps)).toBe(1);
expect(existsSync(configPath())).toBe(false); // nothing persisted
expect(existsSync(undoFile())).toBe(false);
const rows = readReceipts();
expect(rows.filter((r) => r.outcome === 'applied').length).toBe(0);
const refused = rows.filter((r) => r.outcome === 'refused');
expect(refused.length).toBe(1);
expect(refused[0].action).toBe('rewrite_to_session_pooler');
expect(logs.join('\n')).toContain('env:GBRAIN_DATABASE_URL');
});
});
describe('db-repair receipts + advisory lock', () => {
test('receipts cap: 205 seeded diagnose rows + one write → file capped at 200, newest kept', async () => {
const seeded: string[] = [];
for (let i = 0; i < 205; i++) {
seeded.push(JSON.stringify(receipt({ ts: FIXED_NOW - (205 - i) * 1000, action: `seed-${i}`, outcome: 'diagnose' })));
}
writeFileSync(receiptsPath(), seeded.join('\n') + '\n');
writeReceipt(receipt({ ts: FIXED_NOW, action: 'cap-probe', outcome: 'diagnose' }));
const rows = readReceipts();
expect(rows.length).toBe(RECEIPTS_CAP);
expect(rows[rows.length - 1].action).toBe('cap-probe');
// Oldest rows fell off the front.
expect(rows[0].action).toBe('seed-6');
});
test('receipts cap: a recent APPLIED row survives a 300-row diagnose flood (cooldown memory is never evicted)', async () => {
// The exact eviction that would disarm the 24h rewrite cooldown: one
// applied rewrite receipt, then an agent loop writing diagnose rows
// every few minutes. The applied row must outlive the flat cap.
writeFileSync(
receiptsPath(),
JSON.stringify(receipt({ ts: FIXED_NOW - 60_000, action: 'rewrite_to_session_pooler', outcome: 'applied' })) + '\n',
);
for (let i = 0; i < 300; i++) {
writeReceipt(receipt({ ts: FIXED_NOW + i * 1000, action: `flood-${i}`, outcome: 'diagnose' }));
}
const rows = readReceipts();
const applied = rows.filter((r) => r.outcome === 'applied');
expect(applied.length).toBe(1);
expect(applied[0].action).toBe('rewrite_to_session_pooler');
// Diagnose rows still flat-capped.
expect(rows.filter((r) => r.outcome === 'diagnose').length).toBe(RECEIPTS_CAP);
// And the cooldown still fires off that surviving row.
expect(rewriteCooldownBlocked('network_unreachable', 'rewrite_to_session_pooler', FIXED_NOW + 300_000)).toBe(true);
});
test('receipts cap: applied rows OLDER than the retention window are evicted normally', async () => {
const stale = FIXED_NOW - 30 * 24 * 60 * 60 * 1000; // 30 days — past the window
const seeded: string[] = [];
for (let i = 0; i < 205; i++) {
seeded.push(JSON.stringify(receipt({ ts: stale + i * 1000, action: `old-applied-${i}`, outcome: 'applied' })));
}
writeFileSync(receiptsPath(), seeded.join('\n') + '\n');
writeReceipt(receipt({ ts: FIXED_NOW, action: 'cap-probe', outcome: 'diagnose' }));
expect(readReceipts().length).toBe(RECEIPTS_CAP);
});
test('advisory lock held by a LIVE pid → exit 1 repair in progress', async () => {
writeConfig({ engine: 'postgres', database_url: PLAIN_PG_URL });
writeFileSync(lockFile(), JSON.stringify({ pid: process.pid, ts: FIXED_NOW }));
expect(await runDbRepair([], makeDeps().deps)).toBe(1);
expect(errs.join('\n')).toContain('repair in progress');
});
test('advisory lock held by a DEAD pid → repair proceeds', async () => {
writeConfig({ engine: 'postgres', database_url: PLAIN_PG_URL });
// A just-reaped child pid is affirmatively dead (ESRCH), unlike a made-up
// number that could theoretically be recycled.
const child = spawnSync('true');
const deadPid = child.pid && child.pid > 0 ? child.pid : 999_999;
writeFileSync(lockFile(), JSON.stringify({ pid: deadPid, ts: FIXED_NOW }));
expect(await runDbRepair([], makeDeps({ access: [null], schema: [null] }).deps)).toBe(0);
// Lock was taken over and released on the way out.
expect(existsSync(lockFile())).toBe(false);
});
test('readReceipts: a torn line (kill mid-append) is skipped, valid rows on BOTH sides survive', () => {
const lines = [
JSON.stringify(receipt({ action: 'kept-1' })),
JSON.stringify(receipt({ action: 'kept-2' })),
'{"ts":123,', // torn mid-append — must not discard every OTHER receipt
JSON.stringify(receipt({ action: 'kept-3' })),
];
writeFileSync(receiptsPath(), lines.join('\n') + '\n');
const rows = readReceipts();
expect(rows.length).toBe(3);
expect(rows.map((r) => r.action)).toEqual(['kept-1', 'kept-2', 'kept-3']);
});
});
describe('db-repair undo — JSON envelope, reversibility, lock', () => {
function seedUndoRecord(priorUrl: string): void {
writeFileSync(undoFile(), JSON.stringify({ prior_url: priorUrl, ts: FIXED_NOW - HOUR, reason: 'network_unreachable' }));
}
test('--json undo emits ONE parseable envelope: applied includes undo_last_rewrite, fixed true, exit 0', async () => {
writeConfig({ engine: 'postgres', database_url: SESSION_URL }); // the rewritten URL currently live
seedUndoRecord(POOLER_URL);
const { deps } = makeDeps(); // exhausted queue = restored URL probes healthy
expect(await runDbRepair(['--yes', '--undo-last-rewrite', '--json'], deps)).toBe(0);
const payload = JSON.parse(logs.join('\n'));
expect(payload.schema_version).toBe(1);
expect(payload.reason).toBe('undo');
expect(payload.applied).toContain('undo_last_rewrite');
expect(payload.fixed).toBe(true);
expect(payload.remaining).toBeNull();
// The envelope is redacted like every other surface.
expect(logs.join('\n')).not.toContain(':pw@');
});
test('undo is reversible: the undo file now holds the URL config held BEFORE the undo, reason undo', async () => {
writeConfig({ engine: 'postgres', database_url: SESSION_URL });
seedUndoRecord(POOLER_URL);
expect(await runDbRepair(['--yes', '--undo-last-rewrite'], makeDeps().deps)).toBe(0);
expect(readConfig().database_url).toBe(POOLER_URL); // restored
const undo = JSON.parse(readFileSync(undoFile(), 'utf-8'));
expect(undo.prior_url).toBe(SESSION_URL); // the previously-rewritten URL
expect(undo.reason).toBe('undo');
});
test('undo runs INSIDE the advisory lock: a live holder blocks it (exit 1, config untouched)', async () => {
writeConfig({ engine: 'postgres', database_url: SESSION_URL });
seedUndoRecord(POOLER_URL);
writeFileSync(lockFile(), JSON.stringify({ pid: process.pid, ts: FIXED_NOW }));
expect(await runDbRepair(['--yes', '--undo-last-rewrite'], makeDeps().deps)).toBe(1);
expect(errs.join('\n')).toContain('repair in progress');
expect(readConfig().database_url).toBe(SESSION_URL); // no rewrite happened
expect(JSON.parse(readFileSync(undoFile(), 'utf-8')).prior_url).toBe(POOLER_URL); // record untouched
});
});
describe('db-repair docker arm + healthy-path bonus + rewrite restart note', () => {
test('conn_refused: the docker arm matches the container REAL port via deps.docker.hostPort', async () => {
// Port drifted from the 5434 default (init reuse path) — isGbrainDockerUrl
// is false, so only the hostPort probe can match it.
const url = 'postgresql://postgres:x@localhost:59999/postgres';
writeConfig({ engine: 'postgres', database_url: url });
const { deps } = makeDeps({
access: [connRefusedDiag(url)], // then healthy after docker start
docker: {
available: () => true,
state: () => 'stopped' as const,
start: () => true,
hostPort: () => 59999,
},
});
expect(await runDbRepair(['--yes'], deps)).toBe(0);
const applied = readReceipts().filter((r) => r.outcome === 'applied');
expect(applied.map((r) => r.action)).toContain('docker_start_gbrain-postgres');
expect(applied[0].reason).toBe('conn_refused');
});
test('healthy path reports stale DB-plane config rows (report-only, still exit 0)', async () => {
writeConfig({ engine: 'postgres', database_url: PLAIN_PG_URL });
const executed: string[] = [];
const fakeEngine = {
executeRaw: async (sql: string) => {
executed.push(sql);
return [{ key: 'engine' }];
},
} as unknown as BrainEngine;
const { deps } = makeDeps({
withEngine: async (_config, fn) => fn(fakeEngine),
});
expect(await runDbRepair([], deps)).toBe(0);
expect(logs.join('\n')).toContain('stale DB-plane config row');
expect(logs.join('\n')).toContain('gbrain config unset');
expect(executed.some((s) => s.includes('FROM config'))).toBe(true);
});
test('rewrite success prints the honest-scope restart note (long-lived pools keep the old URL)', async () => {
writeConfig({ engine: 'postgres', database_url: PLAIN_PG_URL });
// ssl_required → append ?sslmode=require (rewrite tier). Probe order:
// initial (fails ssl) → candidate probe → post-persist re-probe.
const { deps } = makeDeps({ access: [sslRequiredDiag(), null, null] });
expect(await runDbRepair(['--yes', '--apply-rewrites'], deps)).toBe(0);
expect(String(readConfig().database_url)).toBe(`${PLAIN_PG_URL}?sslmode=require`);
expect(logs.join('\n')).toContain('restart them to pick up the new URL');
});
});
describe('db-repair --yes that could not fix the access failure (#7137)', () => {
// Value: protects=an agent following the operator contract stops after one failed --yes instead of looping on it;
// fails_when=an exhausted conn_refused --yes run hands back fix argv [gbrain, db-repair, --yes] with next run;
// why_new=no test read the --json fix of an unfixed --yes run; seam=runDbRepair deps in a child process (the
// envelope is written to fd 1); no_claim=diagnosing why the local server refuses connections.
function runJson(args: string[], probes: number): { status: number | null; doc: Record<string, any>; accessCalls: number } {
const repo = join(import.meta.dir, '..');
const script = `
import { runDbRepair } from ${JSON.stringify(join(repo, 'src/commands/db-repair.ts'))};
import { classifyPgAccessError } from ${JSON.stringify(join(repo, 'src/core/pg-access-classify.ts'))};
const e = Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:5432'), { code: 'ECONNREFUSED' });
const d = classifyPgAccessError(e, { url: ${JSON.stringify(PLAIN_PG_URL)}, source: 'config-file' });
let calls = 0;
const code = await runDbRepair(${JSON.stringify(args)}, {
probeAccess: async () => (++calls <= ${probes} ? d : null),
probeSchema: async () => null,
withEngine: async () => { throw new Error('unexpected database access'); },
docker: { available: () => false, state: () => 'absent', start: () => { throw new Error('unexpected service start'); } },
sleep: async () => {},
now: () => ${FIXED_NOW},
});
process.stderr.write('ACCESS_CALLS=' + calls + '\\n');
process.exitCode = code;
`;
const env: Record<string, string | undefined> = { ...process.env, GBRAIN_HOME: home };
for (const k of ['GBRAIN_DATABASE_URL', 'DATABASE_URL', 'GBRAIN_BRAIN_ID', 'GBRAIN_MOUNTS_PATH']) delete env[k];
const r = spawnSync(process.execPath, ['--no-env-file', '-e', script], { cwd: repo, env, encoding: 'utf-8' });
const calls = Number(/ACCESS_CALLS=(\d+)/.exec(r.stderr)?.[1] ?? -1);
return { status: r.status, doc: JSON.parse(r.stdout), accessCalls: calls };
}
test('an exhausted bounded retry escalates to the user instead of prescribing db-repair --yes again', () => {
writeConfig({ engine: 'postgres', database_url: PLAIN_PG_URL });
const { status, doc, accessCalls } = runJson(['--yes', '--json'], 99);
expect(status).toBe(1);
expect(accessCalls).toBe(2);
expect(doc.reason).toBe('conn_refused');
expect(doc.fixed).toBe(false);
expect(doc.applied).toEqual([]);
expect(doc.fix.argv).toBeUndefined();
expect(doc.fix.next).toBe('report');
expect(doc.fix.user_message).toContain('status and its startup log');
expect(doc.fix.verify.argv).toEqual(['gbrain', 'doctor', '--json']);
expect(readReceipts().filter((r) => r.outcome === 'applied').length).toBe(0);
});
test('without --yes the auto tier is still the next step, and a transient refusal still heals under --yes', () => {
writeConfig({ engine: 'postgres', database_url: PLAIN_PG_URL });
const diagnose = runJson(['--json'], 99);
expect(diagnose.status).toBe(1);
expect(diagnose.doc.fix.argv).toEqual(['gbrain', 'db-repair', '--yes']);
expect(diagnose.doc.fix.next).toBe('run');
const healed = runJson(['--yes', '--json'], 1);
expect(healed.status).toBe(0);
expect(healed.doc.fixed).toBe(true);
expect(healed.doc.applied).toEqual(['bounded_reconnect']);
});
});