Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
31.3 KB
Raw Blame
/** Real setup + finite CLI + complete PGLite recovery, entirely within temporary roots. */
import { afterAll, beforeAll, expect, spyOn, test } from 'bun:test';
import * as fs from 'node:fs';
import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { setupInAgent } from '../src/core/agent-install/setup.ts';
import { runAgentSetupCli } from '../src/core/agent-install/entry.ts';
import { acquireBootstrapLock } from '../src/core/bootstrap/lock.ts';
import { readInstallReceipt, writeInstallReceipt } from '../src/core/agent-install/state.ts';
import { createPgliteBackup, rebaseManagedConfig, restorePgliteBackup } from '../src/core/backup/snapshot.ts';
import { writeBackupArchive } from '../src/core/backup/archive.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import { withCoordinatedWrite } from '../src/core/persistence/context.ts';
import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';
import { MinionQueue } from '../src/core/minions/queue.ts';
import { acquireLock, releaseLock, PgliteBusyError } from '../src/core/pglite-lock.ts';
import { withEnv } from './helpers/with-env.ts';

let temporary: string;
let root: string;
let bundle: string;
let archive: string;
const sourceRef = 'a'.repeat(40);
const repo = resolve(import.meta.dir, '..');

async function withBrain<T>(at: string, fn: (engine: PGLiteEngine) => Promise<T>): Promise<T> {
  const engine = new PGLiteEngine();
  await engine.connect({ engine: 'pglite', database_path: join(at, '.gbrain', 'brain.pglite') });
  try { return await fn(engine); } finally { await engine.disconnect(); }
}

async function withFixtureWrite<T>(at: string, sourceIds: string[], fn: (engine: BrainEngine) => Promise<T>): Promise<T> {
  return withBrain(at, engine => engine.transaction(tx => withCoordinatedWrite(tx, sourceIds, () => fn(tx), TEST_WRITE_ATTRIBUTION)));
}

async function launched(args: string[], at = root): Promise<string> {
  const child = Bun.spawn([join(at, 'bin', 'gbrain'), ...args], {
    cwd: '/', env: { ...process.env, DATABASE_URL: 'postgres://foreign.invalid/wrong', GBRAIN_HOME: join(temporary, 'wrong-home'), GBRAIN_SOURCE: 'wrong-source' }, stdout: 'pipe', stderr: 'pipe',
  });
  const timer = setTimeout(() => child.kill('SIGKILL'), 45_000);
  try {
    const [output, errors, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
    if (code !== 0) throw new Error(`Installed command failed (${code}): ${errors}`);
    return output;
  } finally { clearTimeout(timer); }
}

beforeAll(async () => {
  temporary = mkdtempSync(join(tmpdir(), 'gbrain-agent-recovery-'));
  root = join(temporary, 'brain'); bundle = join(temporary, 'bundle'); archive = join(temporary, 'brain.gbrain-backup');
  const pkg = join(bundle, 'app', 'node_modules', 'gbrain');
  mkdirSync(join(pkg, 'src', 'core', 'agent-install'), { recursive: true });
  mkdirSync(join(pkg, 'scripts'));
  // A tiny bundle forwards to the REAL CLI under the test checkout. It tests
  // installed executable handoff without copying the whole checkout/deps.
  copyFileSync(process.execPath, join(bundle, 'bun')); chmodSync(join(bundle, 'bun'), 0o700);
  writeFileSync(join(pkg, 'package.json'), JSON.stringify({ name: 'gbrain', version: '0.0.0-test' }));
  writeFileSync(join(pkg, 'src', 'cli.ts'), `const c=Bun.spawn([process.execPath,'--no-env-file',${JSON.stringify(join(repo, 'src', 'cli.ts'))},...process.argv.slice(2)],{stdin:'inherit',stdout:'inherit',stderr:'inherit'});process.exit(await c.exited);\n`);
  writeFileSync(join(pkg, 'src', 'core', 'agent-install', 'entry.ts'), '// Fixture entrypoint; service is exercised directly.\n');
  copyFileSync(join(repo, 'scripts', 'setup-in-agent.sh'), join(pkg, 'scripts', 'setup-in-agent.sh'));
  await withEnv({ DATABASE_URL: 'postgres://wrong.invalid/foreign', GBRAIN_DATABASE_URL: 'postgres://wrong.invalid/foreign', OPENAI_API_KEY: 'must-not-persist', GBRAIN_BRAIN_ID: 'foreign', GBRAIN_SOURCE: 'foreign' }, () => setupInAgent({ root, harness: 'grok-bot', bundle, sourceRef }));
  await withFixtureWrite(root, ['default', 'external'], async engine => {
    await engine.executeRaw(`INSERT INTO facts (fact, source, source_id) VALUES ($1, 'fixture', 'default')`, ['unique DB-only durable fact']);
    const queue = new MinionQueue(engine);
    for (const status of ['waiting', 'active', 'delayed', 'waiting-children', 'paused', 'completed']) {
      // Current application submission stamps durable authority. Model each
      // lifecycle state without executing work; active represents one claim.
      const job = await queue.add('subagent', {}, {}, { allowProtectedSubmit: true });
      if (status !== 'waiting') await engine.executeRaw(
        "UPDATE minion_jobs SET status=$1, claim_generation=claim_generation+CASE WHEN $1='active' THEN 1 ELSE 0 END WHERE id=$2",
        [status, job.id],
      );
    }
    await engine.executeRaw("SELECT set_config('gbrain.topology_change','on',true)");
    await engine.executeRaw(`INSERT INTO sources (id, name, local_path) VALUES ('external', 'External fixture', $1)`, [join(temporary, 'outside')]);
    await engine.executeRaw(`INSERT INTO pages (slug, type, title, compiled_truth, timeline, frontmatter, content_hash, source_id, source_path) VALUES ('recovery-note', 'note', 'Recovery fixture', '', '', '{}', 'fixture', 'default', $1)`, [join(root, 'memory', 'note.md')]);
  });
  writeFileSync(join(root, 'memory', 'note.md'), '# Local note\nA source file that must survive.\n');
});

afterAll(() => { if (temporary) rmSync(temporary, { recursive: true, force: true }); });

test('restored configuration never traverses or copies inherited path fields', () => {
  const inheritedContainer = { skills_dir: join(root, 'instructions') };
  const prototype = Object.prototype;
  const priorContainer = Object.getOwnPropertyDescriptor(prototype, 'mcp');
  const priorLeaf = Object.getOwnPropertyDescriptor(prototype, 'session_corpus_dir');
  try {
    Object.defineProperty(prototype, 'mcp', { value: inheritedContainer, configurable: true, writable: true });
    Object.defineProperty(prototype, 'session_corpus_dir', { value: join(root, 'memory'), configurable: true, writable: true });
    const detached: string[] = [];
    const restored = rebaseManagedConfig({ engine: 'pglite', dream: { synthesize: {} } }, root, join(temporary, 'new-root'), ['memory', 'instructions'], detached);
    expect(inheritedContainer.skills_dir).toBe(join(root, 'instructions'));
    expect(Object.hasOwn(restored, 'mcp')).toBe(false);
    expect(Object.hasOwn(restored.dream!.synthesize!, 'session_corpus_dir')).toBe(false);
    expect(detached).toEqual([]);
  } finally {
    if (priorContainer) Object.defineProperty(prototype, 'mcp', priorContainer);
    else Reflect.deleteProperty(prototype, 'mcp');
    if (priorLeaf) Object.defineProperty(prototype, 'session_corpus_dir', priorLeaf);
    else Reflect.deleteProperty(prototype, 'session_corpus_dir');
  }
});

test('real keyless initialization stays local, and repair preserves facts/configuration', async () => {
  const configPath = join(root, '.gbrain', 'config.json');
  const config = JSON.parse(readFileSync(configPath, 'utf8'));
  expect(config.engine).toBe('pglite'); expect(config.database_path).toBe(join(root, '.gbrain', 'brain.pglite'));
  expect(config.openai_api_key).toBeUndefined(); expect(config.database_url).toBeUndefined();
  config.embedding_disabled = false; config.schema_pack = 'gbrain-base';
  writeFileSync(configPath, JSON.stringify(config));
  const before = readFileSync(configPath, 'utf8');
  const first = readInstallReceipt(root)!;
  rmSync(join(root, first.artifact!.directory, 'bun'));
  const result = await setupInAgent({ root, harness: 'grok-bot', bundle, sourceRef });
  expect(result.status).toBe('repaired');
  expect(readFileSync(configPath, 'utf8')).toBe(before);
  expect(readInstallReceipt(root)!.installation_id).toBe(first.installation_id);
  expect(readInstallReceipt(root)!.native.routine_id).toBe(first.native.routine_id);
  expect(await withBrain(root, e => e.executeRaw('SELECT fact FROM facts'))).toContainEqual({ fact: 'unique DB-only durable fact' });
});

test('a failed upgrade resumes its migration before reporting the existing brain ready', async () => {
  const upgradingRoot = join(temporary, 'upgrade-root');
  const upgradingBundle = join(temporary, 'upgrade-bundle');
  const failure = join(temporary, 'migration-failure');
  const attempts = join(temporary, 'migration-attempts');
  cpSync(bundle, upgradingBundle, { recursive: true });
  writeFileSync(join(upgradingBundle, 'app', 'node_modules', 'gbrain', 'src', 'cli.ts'), `
import { appendFileSync, existsSync } from 'node:fs';
if (process.argv.includes('--migrate-only')) {
  appendFileSync(${JSON.stringify(attempts)}, 'attempt\\n');
  if (existsSync(${JSON.stringify(failure)})) process.exit(43);
}
const child = Bun.spawn([process.execPath, '--no-env-file', ${JSON.stringify(join(repo, 'src', 'cli.ts'))}, ...process.argv.slice(2)], { stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' });
process.exit(await child.exited);
`);
  await setupInAgent({ root: upgradingRoot, harness: 'muse', bundle: upgradingBundle, sourceRef });
  await withFixtureWrite(upgradingRoot, ['default'], e => e.executeRaw(`INSERT INTO facts (fact, source, source_id) VALUES ('upgrade recovery fixture', 'fixture', 'default')`));
  const original = readInstallReceipt(upgradingRoot)!;
  const configBefore = readFileSync(join(upgradingRoot, '.gbrain', 'config.json'), 'utf8');
  writeFileSync(failure, 'fail once');
  const upgradedRef = 'b'.repeat(40);
  await expect(setupInAgent({ root: upgradingRoot, harness: 'muse', bundle: upgradingBundle, sourceRef: upgradedRef, upgrade: true })).rejects.toThrow('exit 43');
  const pending = readInstallReceipt(upgradingRoot)!;
  expect(pending.artifact!.source_ref).toBe(upgradedRef);
  expect(pending.pending_runtime_migration).toBe(true);
  expect(pending.state).toBe('installing');
  expect(pending.last_failure?.code).toBe('setup_command_failed');
  expect(pending.recovery?.command).toContain(join(upgradingRoot, 'bin', 'gbrain-setup'));
  expect(pending.pending_steps).toContain('migrate_database');
  rmSync(failure);
  const repaired = await setupInAgent({ root: upgradingRoot, harness: 'muse', bundle: upgradingBundle, sourceRef: upgradedRef });
  expect(repaired.status).toBe('repaired');
  expect(readFileSync(attempts, 'utf8')).toBe('attempt\nattempt\n');
  const complete = readInstallReceipt(upgradingRoot)!;
  expect(complete.pending_runtime_migration).toBe(false);
  expect(complete.state).toBe('ready');
  expect(complete.last_failure).toBeUndefined();
  expect(complete.pending_steps).not.toContain('migrate_database');
  expect(complete.pending_steps).toContain('confirm_search_mode');
  expect(complete.pending_steps).toContain('enable_native_skill');
  expect(complete.pending_steps).toContain('verify_new_conversation');
  expect(complete.installation_id).toBe(original.installation_id);
  expect(complete.native).toEqual(original.native);
  expect(readFileSync(join(upgradingRoot, '.gbrain', 'config.json'), 'utf8')).toBe(configBefore);
  expect(await withBrain(upgradingRoot, e => e.executeRaw('SELECT fact FROM facts'))).toContainEqual({ fact: 'upgrade recovery fixture' });
});

test('existing database files after an interrupted init do not certify unfinished schema migrations', async () => {
  // This setup recovery has no running work. The separate backup fixture keeps
  // its active jobs for the restore-quarantine assertions below.
  const interruptedRoot = join(temporary, 'interrupted-root');
  await setupInAgent({ root: interruptedRoot, harness: 'grok-bot', bundle, sourceRef });
  const receipt = readInstallReceipt(interruptedRoot)!;
  const schema = await withFixtureWrite(interruptedRoot, ['default'], async engine => {
    await engine.executeRaw("INSERT INTO facts (fact, source, source_id) VALUES ('interrupted init durable fact', 'fixture', 'default')");
    const current = Number(await engine.getConfig('version'));
    await engine.setConfig('version', String(current - 1));
    return current;
  });
  receipt.initialized = false; receipt.state = 'installing';
  writeInstallReceipt(receipt);
  const repaired = await setupInAgent({ root: interruptedRoot, harness: 'grok-bot', bundle, sourceRef });
  expect(repaired.status).toBe('repaired');
  expect(readInstallReceipt(interruptedRoot)!.schema_version).toBe(schema);
  expect(readInstallReceipt(interruptedRoot)!.pending_runtime_migration).toBe(false);
  expect(await withBrain(interruptedRoot, e => e.executeRaw('SELECT fact FROM facts'))).toContainEqual({ fact: 'interrupted init durable fact' });
});

test('separate installed CLI processes remember, recall and forget despite hostile routing', async () => {
  const unique = `installation-canary-${crypto.randomUUID()}`;
  const remembered = JSON.parse(await launched(['remember', unique, '--provenance', 'hermetic setup test', '--entity', 'projects/setup-test', '--json']));
  expect(remembered.status).toBe('inserted');
  expect(await launched(['recall', '--grep', unique, '--json'])).toContain(unique);
  await launched(['forget', String(remembered.id), '--reason', 'setup test complete']);
  expect(await launched(['recall', '--grep', unique, '--json'])).not.toContain(unique);
  expect(existsSync(join(temporary, 'wrong-home'))).toBe(false);
});

test('user-modified instructions and unowned roots are never overwritten', async () => {
  const path = join(root, 'instructions', 'gbrain-skill.md'); const original = readFileSync(path, 'utf8');
  writeFileSync(path, 'My personal edits');
  await expect(setupInAgent({ root, harness: 'grok-bot', bundle, sourceRef })).rejects.toThrow('will not be overwritten');
  expect(readFileSync(path, 'utf8')).toBe('My personal edits');
  writeFileSync(path, original);
  const foreign = join(temporary, 'foreign'); mkdirSync(foreign); writeFileSync(join(foreign, 'note'), 'keep');
  await expect(setupInAgent({ root: foreign, harness: 'muse', bundle, sourceRef })).rejects.toThrow('unowned state');
  expect(readdirSync(foreign)).toEqual(['note']);
});

test('write-ahead generated-file state resumes across a killed write', async () => {
  const receipt = readInstallReceipt(root)!;
  const path = 'instructions/gbrain-skill.md';
  receipt.pending_files = { [path]: { before: receipt.owned_files[path], after: receipt.owned_files[path] } };
  writeInstallReceipt(receipt);
  await setupInAgent({ root, harness: 'grok-bot', bundle, sourceRef });
  expect(readInstallReceipt(root)!.pending_files?.[path]).toBeUndefined();
});

test('full backup restores DB-only facts/files, rebases sources, quarantines all unfinished jobs', async () => {
  const cfgPath = join(root, '.gbrain', 'config.json');
  const cfg = JSON.parse(readFileSync(cfgPath, 'utf8')); cfg.openai_api_key = 'fixture-private';
  cfg.storage = { backend: 'local', bucket: 'fixture', localPath: join(root, 'memory', 'attachments') };
  cfg.mcp = { skills_dir: join(temporary, 'external-skills') };
  cfg.autopilot = { nightly_quality_probe: { enabled: true } };
  writeFileSync(cfgPath, JSON.stringify(cfg));
  mkdirSync(join(root, 'memory', 'attachments'));
  writeFileSync(join(root, 'memory', 'attachments', 'fixture.txt'), 'managed attachment');
  mkdirSync(join(root, '.gbrain', 'credential-deliveries'));
  writeFileSync(join(root, '.gbrain', 'credential-deliveries', 'fixture.json'), '{"client_secret":"excluded-file"}');
  const excludedManaged = ['memory/credentials.json', 'memory/auth.json', 'memory/token.txt', 'instructions/.env.local',
    'memory/cache/cache.json', 'memory/browser-profile/Cookies', 'memory/backups/old.gbrain-backup',
    'memory/prior.gbrain-backup', 'memory/renamed-prior-snapshot'];
  for (const path of excludedManaged) {
    mkdirSync(join(root, path, '..'), { recursive: true });
    writeFileSync(join(root, path), 'sensitive-excluded-fixture');
  }
  // Backups can be copied into a managed source or renamed without a suffix.
  // Neither may recursively include an older installation's private payload.
  const renamedArchive = join(root, 'memory', 'renamed-prior-snapshot');
  rmSync(renamedArchive);
  await writeBackupArchive(renamedArchive, {}, [{ path: 'private-record', file: join(root, 'memory', 'prior.gbrain-backup') }]);
  writeFileSync(join(root, 'memory', 'credentials.md'), '# Remembered credential rotation procedure\nNo actual credential.\n');
  const connectorCommandMarker = join(temporary, 'connector-command-ran');
  const webhookSecret = `whsec-sentinel-${crypto.randomUUID()}`;
  await withFixtureWrite(root, ['google-fixture'], async engine => {
    await engine.executeRaw("SELECT set_config('gbrain.topology_change','on',true)");
    await engine.executeRaw('INSERT INTO sources (id, name, local_path, config) VALUES ($1, $2, $3, $4::text::jsonb)', [
      'google-fixture', 'Google fixture', join(root, 'memory', 'google'),
      JSON.stringify({ kind: 'google', federated: true, g_account: 'fixture-account', g_services: 'gmail', g_access: 'command', g_token_command: `touch '${connectorCommandMarker}'`, syncEnabled: true, webhook_secret: webhookSecret }),
    ]);
    await engine.setConfig('connectors.chatgpt.auto_sync', 'true');
    await engine.setConfig('autopilot.auto_drain.enabled', 'true');
    await engine.setConfig('sync.repo_path', join(root, 'memory'));
    await engine.setConfig('dream.synthesize.session_corpus_dir', join(temporary, 'external-sessions'));
  });
  const created = await createPgliteBackup({ root, output: archive });
  expect(created.manifest.classification).toBe('sensitive-full-database-state');
  // Source-config secrets stay inside the documented full-database payload,
  // never in backup metadata or the restore log.
  expect(JSON.stringify(created.manifest)).not.toContain(webhookSecret);
  expect(statSync(archive).mode & 0o777).toBe(0o600);
  expect(created.manifest.entries.some(e => e.path.includes('credential-deliveries'))).toBe(false);
  for (const path of excludedManaged) expect(created.manifest.entries.some(e => e.path === `files/${path}`)).toBe(false);
  expect(created.manifest.entries.some(e => e.path === 'files/memory/credentials.md')).toBe(true);
  expect((created.manifest.omitted as string[]).some(line => line.includes('instructions/.env.local'))).toBe(true);
  expect((created.manifest.omitted as string[]).some(line => line.includes('memory/browser-profile'))).toBe(true);
  for (const path of ['memory/prior.gbrain-backup', 'memory/renamed-prior-snapshot']) {
    expect(created.manifest.omitted).toContain(`Excluded managed path ${path}: previous GBrain backup archive.`);
  }
  const restored = join(temporary, 'restored');
  const result = await restorePgliteBackup({ archive, into: restored });
  expect(result.quarantined_jobs).toBe(5);
  expect(result.reconnect_required.join('\n')).not.toContain(webhookSecret);
  expect(readFileSync(join(restored, 'restore-receipt.json'), 'utf8')).not.toContain(webhookSecret);
  expect(readFileSync(join(restored, 'memory', 'note.md'), 'utf8')).toContain('must survive');
  for (const path of excludedManaged) expect(existsSync(join(restored, path))).toBe(false);
  expect(readFileSync(join(restored, 'memory', 'credentials.md'), 'utf8')).toContain('Remembered credential rotation');
  const restoredCfg = JSON.parse(readFileSync(join(restored, '.gbrain', 'config.json'), 'utf8'));
  expect(restoredCfg.database_path).toBe(join(restored, '.gbrain', 'brain.pglite'));
  expect(restoredCfg.openai_api_key).toBeUndefined();
  expect(restoredCfg.storage.localPath).toBe(join(restored, 'memory', 'attachments'));
  expect(restoredCfg.mcp.skills_dir).toBeUndefined();
  expect(restoredCfg.autopilot.nightly_quality_probe.enabled).toBe(false);
  expect(readFileSync(join(restoredCfg.storage.localPath, 'fixture.txt'), 'utf8')).toBe('managed attachment');
  await withBrain(restored, async e => {
    expect(await e.executeRaw('SELECT fact FROM facts')).toContainEqual({ fact: 'unique DB-only durable fact' });
    expect(await e.executeRaw(`SELECT local_path FROM sources WHERE id = 'default'`)).toEqual([{ local_path: join(restored, 'memory') }]);
    expect(await e.executeRaw(`SELECT local_path FROM sources WHERE id = 'external'`)).toEqual([{ local_path: null }]);
    expect(await e.executeRaw(`SELECT source_path FROM pages WHERE slug = 'recovery-note'`)).toEqual([{ source_path: join(restored, 'memory', 'note.md') }]);
    expect(await e.executeRaw(`SELECT count(*)::int AS n FROM minion_jobs WHERE status = 'cancelled' AND data->>'__restore_previous_status' IS NOT NULL`)).toEqual([{ n: 5 }]);
    expect(await e.executeRaw(`SELECT count(*)::int AS n FROM minion_jobs WHERE status = 'completed'`)).toEqual([{ n: 1 }]);
    const [connector] = await e.executeRaw<{ local_path: string | null; config: Record<string, unknown> }>(`SELECT local_path, config FROM sources WHERE id = 'google-fixture'`);
    expect(connector.local_path).toBeNull();
    expect(connector.config).toMatchObject({ federated: true, syncEnabled: false });
    expect(connector.config.kind).toBeUndefined();
    expect(connector.config.g_token_command).toBeUndefined();
    expect(await e.getConfig('connectors.chatgpt.auto_sync')).toBe('false');
    expect(await e.getConfig('autopilot.auto_drain.enabled')).toBe('false');
    expect(await e.getConfig('sync.repo_path')).toBe(join(restored, 'memory'));
    expect(await e.getConfig('dream.synthesize.session_corpus_dir')).toBeNull();
    const { performSync } = await import('../src/commands/sync.ts');
    await expect(performSync(e, { sourceId: 'google-fixture', noPull: true })).rejects.toMatchObject({ code: 'owner_unavailable' });
    // An explicit repo override must not revive the archived API kind or its
    // credential command. The restored source still has no canonical owner.
    await expect(performSync(e, { sourceId: 'google-fixture', repoPath: join(restored, 'memory'), noPull: true })).rejects.toMatchObject({ code: 'owner_unavailable' });
    expect(existsSync(connectorCommandMarker)).toBe(false);
  });
  const detached = JSON.parse(readFileSync(join(restored, '.gbrain', 'restore-detached.json'), 'utf8'));
  expect(detached.sources.find((s: { id: string }) => s.id === 'google-fixture').config.g_account).toBe('fixture-account');
  expect(statSync(join(restored, '.gbrain', 'restore-detached.json')).mode & 0o777).toBe(0o600);
  expect(readFileSync(join(restored, '.gbrain', 'autopilot-paused'), 'utf8')).toContain('backup restore');
  expect(existsSync(join(restored, 'bin', 'gbrain'))).toBe(false);
  await setupInAgent({ root: restored, harness: 'grok-bot', bundle, sourceRef });
  expect(readFileSync(join(restored, 'instructions', 'gbrain-skill.md'), 'utf8')).toContain(join(restored, 'bin', 'gbrain'));
  expect(readInstallReceipt(restored)!.native.verification).toBe('unverified');
  const restoredCanary = `restored-installation-canary-${crypto.randomUUID()}`;
  const written = JSON.parse(await launched(['remember', restoredCanary, '--provenance', 'explicit restore verification', '--entity', 'projects/restore-test', '--json'], restored));
  expect(written.status).toBe('inserted');
  expect(await launched(['recall', '--grep', restoredCanary, '--json'], restored)).toContain(restoredCanary);
  expect(await withBrain(root, e => e.executeRaw('SELECT id FROM facts WHERE fact = $1', [restoredCanary]))).toEqual([]);
  expect(await launched(['recall', '--grep', restoredCanary, '--json'])).not.toContain(restoredCanary);
  expect(await withBrain(root, e => e.executeRaw(`SELECT count(*)::int AS n FROM minion_jobs WHERE status = 'waiting'`))).toEqual([{ n: 1 }]);
});

test('restore rejects existing targets and corrupt archives without touching the original brain', async () => {
  await expect(restorePgliteBackup({ archive, into: root })).rejects.toThrow('never overwritten');
  const corrupt = join(temporary, 'corrupt'); writeFileSync(corrupt, 'not a backup');
  const into = join(temporary, 'failed-restore');
  await expect(restorePgliteBackup({ archive: corrupt, into })).rejects.toThrow();
  expect(JSON.parse(readFileSync(join(into, 'restore-receipt.json'), 'utf8')).state).toBe('failed');
  await expect(setupInAgent({ root: into, harness: 'grok-bot', bundle, sourceRef, adopt: true })).rejects.toThrow('incomplete restore');
  expect(existsSync(join(into, '.gbrain', 'config.json'))).toBe(false);
  expect(await withBrain(root, e => e.executeRaw('SELECT fact FROM facts'))).toContainEqual({ fact: 'unique DB-only durable fact' });
});

test('restore rejects a valid payload with a false schema version in its archive inventory', async () => {
  const bytes = readFileSync(archive);
  const prefixSize = bytes.indexOf('\n') + 1;
  const manifestSize = bytes.readUInt32BE(prefixSize);
  const metadata = JSON.parse(bytes.subarray(prefixSize + 4, prefixSize + 4 + manifestSize).toString());
  metadata.schema_version -= 1;
  const changed = Buffer.from(JSON.stringify(metadata));
  const length = Buffer.alloc(4); length.writeUInt32BE(changed.length);
  const alteredArchive = join(temporary, 'false-schema.gbrain-backup');
  writeFileSync(alteredArchive, Buffer.concat([bytes.subarray(0, prefixSize), length, changed, bytes.subarray(prefixSize + 4 + manifestSize)]));
  const into = join(temporary, 'false-schema-restore');
  await expect(restorePgliteBackup({ archive: alteredArchive, into })).rejects.toMatchObject({ code: 'backup_schema_mismatch' });
  expect(JSON.parse(readFileSync(join(into, 'restore-receipt.json'), 'utf8')).state).toBe('failed');
  expect(existsSync(join(into, '.gbrain', 'config.json'))).toBe(false);
  expect(await withBrain(root, e => e.executeRaw('SELECT fact FROM facts'))).toContainEqual({ fact: 'unique DB-only durable fact' });
});

test('interrupted publication preserves private recovery staging and refuses an incomplete destination', async () => {
  const into = join(temporary, 'interrupted-publication');
  const originalState = () => withBrain(root, async engine => ({
    facts: await engine.executeRaw('SELECT id, fact, expired_at FROM facts ORDER BY id'),
    jobs: await engine.executeRaw('SELECT id, status, data FROM minion_jobs ORDER BY id'),
  }));
  const before = await originalState();
  const moved: string[] = [];
  const rename = fs.renameSync;
  const publication = spyOn(fs, 'renameSync').mockImplementation((from, to) => {
    const source = String(from); const destination = String(to);
    const child = ['.gbrain', 'instructions', 'memory'].find(name => destination === join(into, name)
      && source.startsWith(join(into, '.restore-')) && source.endsWith(`/restored/${name}`));
    if (child && moved.length === 1) throw new Error('injected restore publication interruption');
    rename(from, to);
    if (child) moved.push(child);
  });
  try { await expect(restorePgliteBackup({ archive, into })).rejects.toThrow('injected restore publication interruption'); }
  finally { publication.mockRestore(); }
  expect(moved).toHaveLength(1);
  expect(existsSync(join(into, moved[0]))).toBe(true);
  expect(JSON.parse(readFileSync(join(into, 'restore-receipt.json'), 'utf8'))).toMatchObject({ state: 'failed', original_preserved: true });
  expect(statSync(into).mode & 0o777).toBe(0o700);
  const staging = readdirSync(into).filter(name => name.startsWith('.restore-'));
  expect(staging).toHaveLength(1);
  expect(statSync(join(into, staging[0])).mode & 0o777).toBe(0o700);
  expect(existsSync(join(into, staging[0], 'payload', 'database.tar'))).toBe(true);
  expect(readdirSync(join(into, staging[0], 'restored')).length).toBeGreaterThan(0);
  await expect(setupInAgent({ root: into, harness: 'grok-bot', bundle, sourceRef })).rejects.toThrow('incomplete restore');
  await expect(restorePgliteBackup({ archive, into })).rejects.toMatchObject({ code: 'restore_target_exists' });
  expect(await originalState()).toEqual(before);
});

test('a changing managed file inventory prevents backup publication and preserves the brain', async () => {
  const output = join(temporary, 'changing-files.gbrain-backup');
  const added = join(root, 'memory', 'concurrent-writer.md');
  const connect = PGLiteEngine.prototype.connect;
  const probe = spyOn(PGLiteEngine.prototype, 'connect').mockImplementation(async function (this: PGLiteEngine, config) {
    await connect.call(this, config);
    const dump = this.db.dumpDataDir.bind(this.db);
    this.db.dumpDataDir = async (...args) => {
      const result = await dump(...args);
      writeFileSync(added, '# A source file added during the database snapshot\n');
      return result;
    };
  });
  try { await expect(createPgliteBackup({ root, output })).rejects.toMatchObject({ code: 'writers_active' }); }
  finally { probe.mockRestore(); rmSync(added, { force: true }); }
  expect(existsSync(output)).toBe(false);
  expect(await withBrain(root, e => e.executeRaw('SELECT fact FROM facts'))).toContainEqual({ fact: 'unique DB-only durable fact' });
});

test('PGLite busy failures are typed and preserve the live lock', async () => {
  const dir = join(temporary, 'locked'); const lock = await acquireLock(dir);
  try {
    try { await acquireLock(dir, { timeoutMs: 20 }); throw new Error('unexpected lock acquisition'); }
    catch (error) { expect(error).toBeInstanceOf(PgliteBusyError); expect((error as PgliteBusyError).code).toBe('pglite_busy'); }
    expect(existsSync(join(dir, '.gbrain-lock', 'lock'))).toBe(true);
  } finally { await releaseLock(lock); }
});

test('setup JSON preserves retryable busy classification and never recommends deleting a live lock', async () => {
  const setupLock = await acquireBootstrapLock(root);
  const calls: string[] = [];
  const output = spyOn(console, 'log').mockImplementation(value => { calls.push(String(value)); });
  const args = ['--root', root, '--harness', 'grok-bot', '--bundle', bundle, '--source-ref', sourceRef, '--json'];
  try {
    const before = readFileSync(join(setupLock.dir, 'meta.json'), 'utf8');
    expect(await runAgentSetupCli(args)).toBe(1);
    expect(JSON.parse(calls.pop()!)).toMatchObject({ ok: false, reason: 'setup_busy', retryable: true });
    expect(readFileSync(join(setupLock.dir, 'meta.json'), 'utf8')).toBe(before);
  } finally { setupLock.release(); output.mockRestore(); }

  const lock = await acquireLock(join(root, '.gbrain', 'brain.pglite'));
  const lockPath = join(lock.lockDir!, 'lock');
  const prior = JSON.parse(readFileSync(lockPath, 'utf8'));
  writeFileSync(lockPath, JSON.stringify({ ...prior, subcommand: 'serve' }));
  const databaseOutput = spyOn(console, 'log').mockImplementation(value => { calls.push(String(value)); });
  try {
    expect(await runAgentSetupCli(args)).toBe(1);
    const busy = JSON.parse(calls.pop()!);
    expect(busy).toMatchObject({ ok: false, reason: 'pglite_busy', retryable: true });
    expect(busy.recovery_action).toContain('Do not remove its lock');
    expect(JSON.parse(readFileSync(lockPath, 'utf8')).pid).toBe(process.pid);
    // A runtime upgrade reaches the same lock through a separate migration
    // CLI process; that boundary must preserve the retryable result too.
    const pending = readInstallReceipt(root)!;
    pending.pending_runtime_migration = true; pending.state = 'installing';
    writeInstallReceipt(pending);
    expect(await runAgentSetupCli(args)).toBe(1);
    expect(JSON.parse(calls.pop()!)).toMatchObject({ ok: false, reason: 'pglite_busy', retryable: true });
    expect(readInstallReceipt(root)!.pending_runtime_migration).toBe(true);
    expect(JSON.parse(readFileSync(lockPath, 'utf8')).pid).toBe(process.pid);
  } finally { databaseOutput.mockRestore(); await releaseLock(lock); }
  await setupInAgent({ root, harness: 'grok-bot', bundle, sourceRef });
  expect(readInstallReceipt(root)!.pending_runtime_migration).toBe(false);
});