Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
25.3 KB
Raw Blame
/**
 * backup-cli.serial.test.ts — pins src/commands/backup.ts runBackupCli:
 * usage surface (--help / unknown subcommand), the status cache policy
 * (fresh ok cache never touches the engine; a fresh warn cache forces a
 * recompute), check's always-compute + --quiet contract, the PGLite-lock
 * fallback (cache-derived exit, fail-open with no cache) including a
 * source-text contract pin on the lock-error literal, non-lock engine
 * failures (reject with no cache, cache fallback otherwise), the
 * GBRAIN_BACKUP_CHECK=0 off switch (check refuses; status is a cache-only
 * reader), the --json recovery/degraded payload, and the warn-path
 * 'status' nag impression.
 *
 * Engine is driven through a stub connect thunk (async () => engineStub)
 * with the executeRaw idiom from test/backup-coverage.serial.test.ts —
 * no real PGLite, no real engine lock.
 */
import { describe, test, expect, beforeEach, afterEach, spyOn } from 'bun:test';
import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

import type { BrainEngine } from '../src/core/engine.ts';
import { runBackupCli } from '../src/commands/backup.ts';
import { DEFAULT_CLI_OPTIONS, setCliOptions, _resetCliOptionsForTest } from '../src/core/cli-options.ts';
import { __resetBackupRefreshForTests } from '../src/core/backup/coverage.ts';
import {
  BACKUP_STATUS_SCHEMA_VERSION,
  __setBackupIntervalForTests,
  __setBackupNagStatePathForTests,
  __setBackupStatusPathForTests,
  loadBackupStatus,
  saveBackupStatus,
  type BackupStatus,
} from '../src/core/backup/status-file.ts';
import { surfaceSource } from './helpers/source-surface.ts';
import * as snapshot from '../src/core/backup/snapshot.ts';
import { pgliteBackupPreflight } from '../src/core/backup/preflight.ts';
import * as fs from 'node:fs';

/** The exact literal thrown by src/core/pglite-engine.ts on lock contention.
 * isLockError in src/commands/backup.ts matches on the leading substring —
 * the source-text contract pin below fails the suite if either side drifts. */
const LOCK_SUBSTRING = 'Could not acquire PGLite lock';
const LOCK_MESSAGE = 'Could not acquire PGLite lock. Another gbrain process is using the database.';

const ENV_KEYS = [
  'GBRAIN_HOME',
  'GBRAIN_BACKUP_CHECK',
  'GBRAIN_BACKUP_CHECK_DAYS',
  'DATABASE_URL',
  'GBRAIN_DATABASE_URL',
  'GBRAIN_SOURCE',
  'GBRAIN_SKIP_STARTUP_HOOKS',
] as const;

let tmp: string;
let saved: Record<string, string | undefined>;
let statusPath: string;
let nagPath: string;

const home = () => join(tmp, '.gbrain');

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), 'gb-bkcli-'));
  saved = {};
  for (const k of ENV_KEYS) {
    saved[k] = process.env[k];
    delete process.env[k];
  }
  process.env.GBRAIN_HOME = tmp; // configDir() === tmp/.gbrain
  statusPath = join(home(), 'backup-status.json');
  nagPath = join(home(), 'backup-nag-state.json');
  __setBackupStatusPathForTests(statusPath);
  __setBackupNagStatePathForTests(nagPath);
  __resetBackupRefreshForTests();
  _resetCliOptionsForTest();
});

afterEach(() => {
  __setBackupStatusPathForTests(null);
  __setBackupNagStatePathForTests(null);
  __setBackupIntervalForTests(null);
  __resetBackupRefreshForTests();
  _resetCliOptionsForTest();
  for (const k of ENV_KEYS) {
    if (saved[k] === undefined) delete process.env[k];
    else process.env[k] = saved[k];
  }
  rmSync(tmp, { recursive: true, force: true });
});

// ── Fixtures ─────────────────────────────────────────────────────────────────

function stubEngine(opts: {
  kind?: 'pglite' | 'postgres';
  sources?: unknown[];
  pages?: number;
  sourcesThrow?: boolean;
} = {}): BrainEngine {
  return {
    kind: opts.kind ?? 'pglite',
    executeRaw: async (sql: string) => {
      if (sql.includes('FROM pages')) return [{ n: opts.pages ?? 0 }];
      if (sql.includes('FROM sources')) {
        if (opts.sourcesThrow) throw new Error('sources unreadable');
        return opts.sources ?? [];
      }
      return [];
    },
    disconnect: async () => {},
  } as unknown as BrainEngine;
}

/** Connect thunk that counts calls and resolves the given engine. */
function thunkFor(engine: BrainEngine): { connect: () => Promise<BrainEngine>; calls: () => number } {
  let n = 0;
  return {
    connect: async () => {
      n++;
      return engine;
    },
    calls: () => n,
  };
}

function throwingThunk(err: Error): { connect: () => Promise<BrainEngine>; calls: () => number } {
  let n = 0;
  return {
    connect: async () => {
      n++;
      throw err;
    },
    calls: () => n,
  };
}

/** Hand-built cache verdict that passes loadBackupStatus validation. */
function mkStatus(overall: 'ok' | 'warn', checkedAt: string): BackupStatus {
  const noRemote = overall === 'warn' ? 1 : 0;
  return {
    schema_version: BACKUP_STATUS_SCHEMA_VERSION,
    checked_at: checkedAt,
    gbrain_version: '0.0.0-test',
    interval_days: 30,
    computed_by: 'cli',
    overall,
    totals: {
      assets: noRemote,
      no_remote: noRemote,
      unpushed: 0,
      failing: 0,
      recoverable_repos: 0,
      pages_at_risk: 0,
    },
    assets:
      overall === 'warn'
        ? [{ kind: 'source_repo', id: 'stale-example', state: 'no_remote', fix_argv: null }]
        : [],
  };
}

/** Run runBackupCli with stdout/console.log/console.error captured. */
async function run(
  args: string[],
  connect: () => Promise<BrainEngine>,
): Promise<{ exitCode: 0 | 1 | 2; stdout: string; log: string; stderr: string }> {
  const out: string[] = [];
  const log: string[] = [];
  const errs: string[] = [];
  const origWrite = process.stdout.write;
  const origLog = console.log;
  const origErr = console.error;
  (process.stdout as { write: unknown }).write = (chunk: unknown) => {
    out.push(String(chunk));
    return true;
  };
  console.log = (...a: unknown[]) => {
    log.push(a.map(String).join(' '));
  };
  console.error = (...a: unknown[]) => {
    errs.push(a.map(String).join(' '));
  };
  try {
    const res = await runBackupCli(args, connect);
    return { exitCode: res.exitCode, stdout: out.join(''), log: log.join('\n'), stderr: errs.join('\n') };
  } finally {
    (process.stdout as { write: unknown }).write = origWrite;
    console.log = origLog;
    console.error = origErr;
  }
}

// ── Usage surface ────────────────────────────────────────────────────────────

describe('runBackupCli — usage', () => {
  test('--help → exit 0 with the help text', async () => {
    const { connect, calls } = thunkFor(stubEngine({}));
    const r = await run(['--help'], connect);
    expect(r.exitCode).toBe(0);
    expect(r.log).toContain('gbrain backup <status|check|create|restore>');
    expect(calls()).toBe(0);
  });

  test('no args → exit 0 with the help text', async () => {
    const { connect, calls } = thunkFor(stubEngine({}));
    const r = await run([], connect);
    expect(r.exitCode).toBe(0);
    expect(r.log).toContain('gbrain backup <status|check|create|restore>');
    expect(calls()).toBe(0);
  });

  test('unknown subcommand → exit 2 on stderr', async () => {
    const { connect, calls } = thunkFor(stubEngine({}));
    const r = await run(['bogus'], connect);
    expect(r.exitCode).toBe(2);
    expect(r.stderr).toContain('Unknown backup subcommand: bogus');
    expect(calls()).toBe(0);
  });
});

// ── status cache policy ──────────────────────────────────────────────────────

describe('runBackupCli status — cache policy', () => {
  test('fresh ok cache → exit 0 and the connect thunk is NEVER called', async () => {
    saveBackupStatus(mkStatus('ok', new Date().toISOString()));
    const { connect, calls } = thunkFor(stubEngine({}));

    const r = await run(['status'], connect);

    expect(r.exitCode).toBe(0);
    expect(calls()).toBe(0); // no lock risk: fresh ok cache answers alone
    expect(r.stdout).toContain('backup coverage — ok');
  });

  test('fresh warn cache → recomputes (forceRefresh), exit reflects the NEW verdict', async () => {
    const oldIso = new Date(Date.now() - 60_000).toISOString();
    saveBackupStatus(mkStatus('warn', oldIso));
    // Recompute against an empty brain (no sources, 0 pages) → verdict ok.
    const { connect, calls } = thunkFor(stubEngine({}));

    const r = await run(['status'], connect);

    expect(calls()).toBe(1);
    expect(r.exitCode).toBe(0); // NEW verdict, not the stale warn
    expect(r.stdout).toContain('backup coverage — ok');
    const persisted = loadBackupStatus();
    expect(persisted?.overall).toBe('ok');
    expect(persisted?.checked_at).not.toBe(oldIso);
  });
});

// ── check always computes + --quiet ─────────────────────────────────────────

describe('runBackupCli check', () => {
  test('check always computes, even over a fresh ok cache; exit 0 when ok', async () => {
    const oldIso = new Date(Date.now() - 60_000).toISOString();
    saveBackupStatus(mkStatus('ok', oldIso));
    const { connect, calls } = thunkFor(stubEngine({}));

    const r = await run(['check'], connect);

    expect(calls()).toBe(1);
    expect(r.exitCode).toBe(0);
    expect(loadBackupStatus()?.checked_at).not.toBe(oldIso); // re-persisted
  });

  test('check exits 1 on a warn compute (pglite pages-only brain)', async () => {
    const { connect, calls } = thunkFor(stubEngine({ kind: 'pglite', pages: 42 }));

    const r = await run(['check'], connect);

    expect(calls()).toBe(1);
    expect(r.exitCode).toBe(1);
    expect(r.stdout).toContain('WARN');
    expect(loadBackupStatus()?.overall).toBe('warn');
  });

  test('--quiet → exit 0 and no stdout (detached-spawn mode)', async () => {
    setCliOptions({ ...DEFAULT_CLI_OPTIONS, quiet: true });
    const { connect, calls } = thunkFor(stubEngine({ kind: 'pglite', pages: 42 }));

    const r = await run(['check'], connect);

    expect(calls()).toBe(1); // still computes + caches
    expect(r.exitCode).toBe(0); // always 0 in quiet mode, even on warn
    expect(r.stdout).toBe('');
    expect(r.log).toBe('');
    const persisted = loadBackupStatus();
    expect(persisted?.overall).toBe('warn');
    expect(persisted?.computed_by).toBe('spawn'); // quiet stamps spawn
  });
});

// ── PGLite-lock fallback contract ────────────────────────────────────────────

describe('runBackupCli — PGLite lock fallback', () => {
  test('lock error + warn cache → exit 1 with the DB-locked note', async () => {
    saveBackupStatus(mkStatus('warn', new Date(Date.now() - 60_000).toISOString()));
    const { connect, calls } = throwingThunk(new Error(LOCK_MESSAGE));

    const r = await run(['status'], connect);

    expect(calls()).toBe(1);
    expect(r.exitCode).toBe(1); // cache-derived exit, never a crash
    expect(r.stdout).toContain('DB locked by serve');
    expect(r.stdout).toContain('backup coverage — WARN');
  });

  test('lock error + NO cache → exit 0 (unknown, fail-open)', async () => {
    const { connect, calls } = throwingThunk(new Error(LOCK_MESSAGE));

    const r = await run(['status'], connect);

    expect(calls()).toBe(1);
    expect(r.exitCode).toBe(1);
    expect(r.log).toContain('no cached verdict; DB locked by serve');
    expect(existsSync(statusPath)).toBe(false);
  });

  test('source-text contract pin: pglite-engine still throws the literal isLockError matches', () => {
    const engineSrc = surfaceSource('pglite-engine');
    expect(engineSrc).toContain(LOCK_SUBSTRING);
    // And backup.ts matches on exactly that substring — drift on either side
    // silently breaks the serve-cohort fallback, so pin both.
    const backupSrc = readFileSync(join(import.meta.dir, '..', 'src', 'commands', 'backup.ts'), 'utf-8');
    expect(backupSrc).toContain(`includes('${LOCK_SUBSTRING}')`);
  });
});

// ── Non-lock engine failures ─────────────────────────────────────────────────

describe('runBackupCli — non-lock connect errors', () => {
  test('no cache → runBackupCli rejects (the failure propagates)', async () => {
    const { connect } = throwingThunk(new Error('engine exploded'));
    await expect(runBackupCli(['check'], connect)).rejects.toThrow('engine exploded');
  });

  test('with cache → falls back to the cached verdict + note', async () => {
    saveBackupStatus(mkStatus('warn', new Date(Date.now() - 60_000).toISOString()));
    const { connect, calls } = throwingThunk(new Error('engine exploded'));

    const r = await run(['status'], connect);

    expect(calls()).toBe(1);
    expect(r.exitCode).toBe(1); // exit from cache
    expect(r.stdout).toContain('engine unavailable — verdict from cache');
  });
});

// ── Off switch (GBRAIN_BACKUP_CHECK=0) ───────────────────────────────────────

describe('runBackupCli — disabled', () => {
  test('check → exit 0 + refusal on stderr, no compute', async () => {
    process.env.GBRAIN_BACKUP_CHECK = '0';
    const { connect, calls } = thunkFor(stubEngine({ kind: 'pglite', pages: 42 }));

    const r = await run(['check'], connect);

    expect(r.exitCode).toBe(0);
    expect(r.stderr).toContain('backup check is disabled');
    expect(calls()).toBe(0);
    expect(existsSync(statusPath)).toBe(false);
  });

  test('status with warn cache → cache-only reader (thunk never called), exit 0 (cron-safe), no impression', async () => {
    process.env.GBRAIN_BACKUP_CHECK = '0';
    saveBackupStatus(mkStatus('warn', new Date(Date.now() - 60_000).toISOString()));
    const { connect, calls } = thunkFor(stubEngine({}));

    const r = await run(['status'], connect);

    expect(calls()).toBe(0); // disabled silences COMPUTE — no engine touch
    // Disabled means silent for automation too: a stale warn cache that can
    // never refresh must not fail crons with exit 1.
    expect(r.exitCode).toBe(0);
    // The verdict + note text still render unchanged for the human reader…
    expect(r.stdout).toContain('backup coverage — WARN');
    expect(r.stdout).toContain('backup check disabled — verdict from cache only');
    // …but no 'status' nag impression is recorded while disabled.
    expect(existsSync(nagPath)).toBe(false);
  });
});

// #5505: rows coverage leaves without fix_argv still get a command.
describe('runBackupCli status: fix commands for dirty and unverified rows', () => {
  test('dirty repo, deduped dirty root, dirty workspace and unverified repo each name a fix', async () => {
    process.env.GBRAIN_BACKUP_CHECK = '0'; // cache-only render, no compute
    saveBackupStatus({
      ...mkStatus('warn', new Date(Date.now() - 60_000).toISOString()),
      assets: [
        { kind: 'source_repo', id: 'dirty-src', state: 'dirty', detail: 'uncommitted changes', fix_argv: null },
        { kind: 'source_repo', id: 'root-a, root-b', state: 'dirty', detail: 'uncommitted changes', fix_argv: null },
        { kind: 'bootstrap_workspace', id: '/ws/example', state: 'dirty', detail: 'uncommitted changes', fix_argv: null },
        { kind: 'source_repo', id: 'unverified-src', state: 'ok', configured_remote: true, fix_argv: null },
      ],
    });

    const r = await run(['status'], thunkFor(stubEngine({})).connect);

    expect(r.stdout).toContain('fix: gbrain sources push dirty-src');
    expect(r.stdout).toContain('fix: gbrain sources push root-a\n');
    expect(r.stdout).toContain('fix: gbrain sources push --path /ws/example');
    expect(r.stdout).toContain('fix: gbrain backup check');
    expect(r.stdout).toContain('Fix the ✗ and ⚠ rows above, then run: gbrain backup check');
  });
});

// ── --json payload ───────────────────────────────────────────────────────────

describe('runBackupCli --json', () => {
  test('recovery field carries recoverable_repos / pages_at_risk / statement', async () => {
    const { connect } = thunkFor(stubEngine({}));

    const r = await run(['check', '--json'], connect);

    expect(r.exitCode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      overall: string;
      recovery: { recoverable_repos: number; pages_at_risk: number; statement: string };
    };
    expect(payload.overall).toBe('ok');
    expect(payload.recovery.recoverable_repos).toBe(0);
    expect(payload.recovery.pages_at_risk).toBe(0);
    expect(payload.recovery.statement).toContain('recently verified remote commits');
    expect(payload.recovery.statement).toContain('not a full database backup');
  });

  test('degraded compute passes degraded:true through and is never persisted', async () => {
    // sources query throws, pages query works → computeBackupCoverage marks
    // the verdict degraded; with no prior cache it is returned but NOT cached.
    const { connect, calls } = thunkFor(stubEngine({ sourcesThrow: true, pages: 5 }));

    const r = await run(['check', '--json'], connect);

    expect(calls()).toBe(1);
    const payload = JSON.parse(r.stdout) as { degraded?: boolean };
    expect(payload.degraded).toBe(true);
    expect(existsSync(statusPath)).toBe(false); // degraded verdicts never persist
    expect(r.exitCode).toBe(1);
  });
});

// ── Nag impression on warn ───────────────────────────────────────────────────

describe('runBackupCli — nag impression', () => {
  test("a warn verdict records a 'status' impression in backup-nag-state.json", async () => {
    const { connect } = thunkFor(stubEngine({ kind: 'pglite', pages: 42 }));

    const r = await run(['check'], connect);
    expect(r.exitCode).toBe(1);

    expect(existsSync(nagPath)).toBe(true);
    const nag = JSON.parse(readFileSync(nagPath, 'utf-8')) as {
      schema_version: string;
      entries: Array<{ pack_name: string; source_id: string }>;
      last_shown_at?: string;
      global_shown_count?: number;
    };
    expect(nag.schema_version).toBe('gbrain-backup-nag-v1');
    expect(nag.entries.some((e) => e.pack_name === 'status' && e.source_id === 'backup')).toBe(true);
    expect(nag.last_shown_at).toBeDefined();
    expect(nag.global_shown_count).toBe(1);
  });

  test('an ok verdict records nothing', async () => {
    const { connect } = thunkFor(stubEngine({}));
    const r = await run(['check'], connect);
    expect(r.exitCode).toBe(0);
    expect(existsSync(nagPath)).toBe(false);
  });
});

// ── create/restore failure diagnostic (#5312) ────────────────────────────────

const REAL_CREATE = Symbol('real createPgliteBackup');

describe('runBackupCli create — failure diagnostic for message-less errors (#5312)', () => {
  /** `thrown === REAL_CREATE` runs the real createPgliteBackup against the test home's config. */
  async function failCreate(thrown: unknown, json: boolean) {
    const spy = thrown === REAL_CREATE ? null : spyOn(snapshot, 'createPgliteBackup').mockImplementation(async () => { throw thrown; });
    const fd1: string[] = [];
    const realWriteSync = fs.writeSync;
    const fdSpy = spyOn(fs, 'writeSync').mockImplementation(((fd: number, buf: Buffer, off = 0, len?: number) => {
      if (fd !== 1) return (realWriteSync as (...a: unknown[]) => number)(fd, buf, off, len);
      const end = len === undefined ? buf.length : off + len;
      fd1.push(Buffer.from(buf).subarray(off, end).toString('utf8'));
      return end - off;
    }) as never);
    const stderrChunks: string[] = [];
    const origStderr = process.stderr.write;
    (process.stderr as { write: unknown }).write = (chunk: unknown) => { stderrChunks.push(String(chunk)); return true; };
    try {
      const args = ['create', '--output', join(tmp, 'out.gbrain-backup'), ...(json ? ['--json'] : [])];
      const r = await run(args, async () => { throw new Error('create never connects'); });
      return { ...r, stdout: `${r.stdout}${fd1.join('')}`, stderr: `${r.stderr}${stderrChunks.join('')}` };
    } finally {
      (process.stderr as { write: unknown }).write = origStderr;
      fdSpy.mockRestore();
      spy?.mockRestore();
    }
  }

  test('--json: a thrown {code:"EPERM"} gets a nonempty message, its legacy keys and the v1 contract', async () => {
    const r = await failCreate({ code: 'EPERM' }, true);
    expect(r.exitCode).toBe(1);
    const doc = JSON.parse(r.stdout.trim());
    expect(doc).toMatchObject({ ok: false, reason: 'EPERM', code: 'storage_error' });
    expect(doc.message).toBe('Backup failed with no error message (code EPERM).');
    expect(doc.why).toContain('gbrain backup create stopped');
    expect(doc.fix).toMatchObject({ argv: ['gbrain', 'doctor', '--json'], next: 'run', verify: { argv: ['gbrain', 'doctor', '--json'] } });
    expect(doc.retryable).toBe(false);
  });

  test('human: the same error renders code, message, fix and why, never undefined or [object Object]', async () => {
    const r = await failCreate({ code: 'EPERM', errno: -1 }, false);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toContain('Error [storage_error]: Backup failed with no error message (code EPERM, errno -1).');
    expect(r.stderr).toContain('Fix: gbrain doctor --json');
    expect(r.stderr).toContain('Why: gbrain backup create stopped');
    expect(r.stderr).not.toContain('undefined');
    expect(r.stderr).not.toContain('[object Object]');
  });

  test('a secret-bearing message-less object is described by safe fields only', async () => {
    const secret = 'postgres://alice-example:[email protected]/brain';
    const thrown = { name: 'ErrnoError', code: 'EIO', connection: secret, toString: () => secret };
    for (const json of [true, false]) {
      const r = await failCreate(thrown, json);
      const out = `${r.stdout}${r.log}${r.stderr}`;
      expect(out).toContain('Backup failed with no error message (ErrnoError, code EIO).');
      expect(out).not.toContain('hunter2-secret');
    }
  });

  test('#6649: a preflight refusal keeps its own code, fix and legacy reason instead of becoming storage_error', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'g6649-cli-'));
    try {
      const refusal = pgliteBackupPreflight(dir, join(dir, 'elsewhere', 'brain.pglite'), () => 0)!;
      for (const json of [true, false]) {
        const r = await failCreate(refusal, json);
        expect(r.exitCode).toBe(1);
        if (json) {
          const doc = JSON.parse(r.stdout.trim());
          expect(doc).toMatchObject({ ok: false, reason: 'unmanaged_database_path', code: 'unmanaged_database_path', class: 'host_only' });
          expect(doc.fix).toMatchObject({ next: 'ask_user', verify: { argv: ['gbrain', 'doctor', '--json'] } });
          expect(doc.fix.user_message).toContain('stop every gbrain writer');
        } else {
          expect(r.stderr).toContain('Error [unmanaged_database_path]');
        }
      }
    } finally { rmSync(dir, { recursive: true, force: true }); }
  });

  test('GBRA-585: on a Postgres brain the refusal names a pg_dump/pg_restore database dump, not doctor', async () => {
    fs.mkdirSync(home(), { recursive: true });
    fs.writeFileSync(join(home(), 'config.json'), JSON.stringify({ engine: 'postgres', database_url: ['postgresql://alice-example', '[email protected]/brain'].join(':') }));
    for (const json of [true, false]) {
      const r = await failCreate(REAL_CREATE, json);
      expect(r.exitCode).toBe(1);
      const out = `${r.stdout}${r.log}${r.stderr}`;
      expect(out).not.toContain('hunter2-secret');
      if (json) {
        const doc = JSON.parse(r.stdout.trim());
        expect(doc).toMatchObject({ ok: false, reason: 'pglite_required', code: 'storage_error' });
        expect(doc.message).toContain('pg_dump');
        expect(doc.message).toContain('pg_restore');
        expect(doc.fix).toMatchObject({ next: 'tell_user_to_run', actor: 'host_admin' });
        expect(doc.fix.argv[0]).toBe('pg_dump');
        expect(doc.fix.verify).toBeUndefined();
        expect(doc.message).toContain('`pg_restore --list <DUMP_FILE>` reads it back');
      } else {
        expect(r.stderr).toContain('pg_dump');
        expect(r.stderr).not.toContain('gbrain doctor --json');
      }
    }
  });

  test('an error message keeps its text with URL credentials redacted; retryable is preserved', async () => {
    const err = Object.assign(new Error('dump failed for postgres://alice-example:[email protected]/brain'), { code: 'writers_active', retryable: true });
    const r = await failCreate(err, true);
    const doc = JSON.parse(r.stdout.trim());
    expect(doc).toMatchObject({ ok: false, reason: 'writers_active', retryable: true });
    expect(doc.message).toContain('dump failed for');
    expect(JSON.stringify(doc)).not.toContain('hunter2-secret');
  });

  test('null and an empty object still produce a nonempty message', async () => {
    for (const thrown of [null, {}]) {
      const r = await failCreate(thrown, true);
      const doc = JSON.parse(r.stdout.trim());
      expect(doc).toMatchObject({ ok: false, reason: 'backup_failed', message: 'Backup failed with no error message.' });
    }
  });
});