Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
32.1 KB
Raw Blame
/**
 * #5988 Lane 3: `gbrain repair frontmatter`. One previewed, hash-bound repair
 * per file: safe quoting by default, interpretations only with
 * --include-ambiguous, --only/--skip bound into the hash, needs_review never
 * written, and managed publication through `managed_file_repair` (exact
 * bytes, import, hold clear and Git effect in one coordinated write).
 */
import { afterAll, beforeAll, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { OperationError, type OperationContext } from '../src/core/ops/contract.ts';
import { claimWorktree } from '../src/core/persistence/ownership.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { performManagedSync } from '../src/core/persistence/sync-run.ts';
import { sha256 } from '../src/core/persistence/digest.ts';
import { localHostId } from '../src/core/persistence/identity.ts';
import { runPersistenceEffects } from '../src/core/persistence/effects.ts';
import { readGitSourceHolds, writeGitHold } from '../src/core/persistence/sync-holds.ts';
import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';
import { confinedRepairTarget, submitManagedFileRepair } from '../src/core/persistence/file-repair.ts';
import { resolveRepairScope, type RepairResult } from '../src/core/repair/core.ts';
import { repairRunner } from '../src/core/repair/registry.ts';
import type { FrontmatterPreviewDetails } from '../src/core/repair/frontmatter.ts';
import { runRepairCommand } from '../src/commands/repair.ts';
import { _resetCliExitVerdictForTests, currentExitCode } from '../src/core/cli-force-exit.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { testBackends } from './helpers/test-backends.ts';
import { withEnv } from './helpers/with-env.ts';

const backends = testBackends();
const home = mkdtempSync(join(tmpdir(), 'gbrain-repair-frontmatter-'));
const engines: BrainEngine[] = [];
/** A brain whose persistence was never activated: legacy (unmanaged) writes. */
let legacyEngine: PGLiteEngine;
let closePostgres: (() => Promise<void>) | undefined;
const env = { GBRAIN_HOME: home, GBRAIN_SYNC_FAILURES_DIR: home, OPENAI_API_KEY: undefined, VOYAGE_API_KEY: undefined, ANTHROPIC_API_KEY: undefined };
const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
const commit = (root: string, message = 'content') => { git(root, 'add', '-A'); git(root, '-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-qm', message); return git(root, 'rev-parse', 'HEAD'); };
const note = (title: string, body = 'A synthetic observation.') => `---\ntitle: ${title}\n---\n${body}\n`;
/** Imports today only after quoting: the safe class. */
const QUOTABLE = '---\ntitle: Payments roundup\nauthor: alice-example (citing acme-example) (original: https://example.invalid/a)\n---\nA synthetic roundup.\n';
/** Unquoted continuation lines: held as needs_interpretation, folded only under --include-ambiguous. */
const folded = (n: number) => `---\ntitle: alice-example post ${n}\nsecond line of post ${n}\n---\nA synthetic post.\n`;
/** Mis-indented mapping entry: no rule, so needs_review. */
const UNFIXABLE = '---\ntitle: Broken\n  author: nobody\n tags: [a\n---\nBody.\n';
const LONG = Array.from({ length: 40 }, (_, i) => `Line ${i} of a long synthetic observation that keeps Git rename detection certain.`).join('\n');
const long = (title: string) => `---\ntitle: ${title}\n---\n${LONG}\n`;
/** #6729: an explicit slug: line that an exact move (R100) leaves pointing at the old path, so the moved file is held with the old page's identity. */
const pinned = (title: string, slug: string) => `---\ntitle: ${title}\nslug: ${slug}\n---\n${LONG}\n`;

beforeAll(async () => {
  if (backends.includes('pglite')) { const engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema(); engines.push(engine); }
  if (backends.includes('postgres')) { const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!); engines.push(pg.engine); closePostgres = pg.close; }
  legacyEngine = new PGLiteEngine(); await legacyEngine.connect({}); await legacyEngine.initSchema();
}, 120_000);

afterAll(async () => {
  await withEnv(env, async () => { for (const engine of engines) { await disposePersistenceConsumer(engine); await engine.disconnect(); } });
  await legacyEngine.disconnect();
  await closePostgres?.(); rmSync(home, { recursive: true, force: true });
});

const quiet = { info() {}, warn() {}, error() {} };

async function managed(engine: BrainEngine, files: Record<string, string>) {
  const id = `fm-${randomUUID().replace(/-/g, '').slice(0, 20)}`, root = join(home, id);
  mkdirSync(root, { recursive: true }); git(root, 'init', '-q');
  git(root, 'config', 'user.name', 'Example'); git(root, 'config', 'user.email', '[email protected]');
  // Git target effects commit only in a durability-hardened checkout.
  writeFileSync(join(root, '.git', 'hooks', 'post-commit'), '#!/bin/sh\n# gbrain brain-durability post-commit hook (v0.42.44+)\n'); chmodSync(join(root, '.git', 'hooks', 'post-commit'), 0o755);
  const write = (path: string, content: string) => { mkdirSync(join(root, path, '..'), { recursive: true }); writeFileSync(join(root, path), content); };
  for (const [path, content] of Object.entries(files)) write(path, content);
  commit(root, 'fixture');
  await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
  await engine.executeRaw("INSERT INTO sources(id,name,local_path,config) VALUES($1,$1,$2,'{}')", [id, root]);
  await claimWorktree(engine, id, root);
  await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
  return fixture(engine, id, root, write);
}

function fixture(engine: BrainEngine, id: string, root: string, write: (path: string, content: string) => void) {
  const sync = () => performManagedSync(engine, { sourceId: id, noPull: true, noEmbed: true, noExtract: true });
  const holds = async () => (await readGitSourceHolds(engine, { sourceIds: [id] }))[0]?.holds ?? [];
  const run = async (opts: { apply?: boolean; expect?: string; includeAmbiguous?: boolean; only?: string[]; skip?: string[] } = {}) => {
    const runner = await repairRunner(engine, { apply: opts.apply === true, noEmbed: true, logger: quiet });
    return runner.run('frontmatter', await resolveRepairScope(engine, id), { explicit: true, sourceFlag: id, expect: opts.expect,
      includeAmbiguous: opts.includeAmbiguous, only: opts.only, skip: opts.skip });
  };
  const read = (path: string) => readFileSync(join(root, path), 'utf8');
  return { id, root, sync, holds, run, read, write };
}

/** Runs queued effects here and waits for the consumer's, until no Git effect of the source is open. */
async function gitEffectsSettled(engine: BrainEngine, sourceId: string) {
  for (let i = 0; i < 100; i++) {
    await runPersistenceEffects(engine, { engine: engine.kind }, { hostId: localHostId(), limit: 10 });
    const open = await engine.executeRaw("SELECT 1 FROM persistence_effects WHERE source_id=$1 AND kind='git' AND state<>'committed'", [sourceId]);
    if (!open.length) return engine.executeRaw<{ outcome: Record<string, unknown> }>("SELECT outcome FROM persistence_effects WHERE source_id=$1 AND kind='git' ORDER BY id", [sourceId]);
    await Bun.sleep(100);
  }
  throw new Error('git effects did not settle');
}

const details = (result: RepairResult) => result.details as unknown as FrontmatterPreviewDetails;

async function each(run: (engine: BrainEngine) => Promise<void>) {
  await withEnv(env, async () => {
    for (const engine of engines) {
      try { await run(engine); } finally { await disposePersistenceConsumer(engine); }
    }
  });
}

async function refusal(run: () => Promise<unknown>): Promise<OperationError> {
  try { await run(); } catch (error) { if (error instanceof OperationError) return error; throw error; }
  throw new Error('expected a refusal');
}

test('safe preview quotes only, hashes its set, and the apply writes exactly the previewed bytes', () => each(async engine => {
  const s = await managed(engine, { 'notes/roundup.md': QUOTABLE, 'notes/ok.md': note('Ok') });
  await s.sync();
  const before = await engine.getPage('notes/roundup', { sourceId: s.id });
  expect(before?.frontmatter.author).toBe('alice-example (citing acme-example) (original: https://example.invalid/a)');
  const preview = await s.run();
  expect(preview).toMatchObject({ mode: 'dry_run', affected: 1 });
  expect(details(preview).counts).toMatchObject({ safe: 1, interpretive: 0, needs_review: 0 });
  expect(details(preview).samples.safe!.diff).toContain('+author: "alice-example (citing acme-example) (original: https://example.invalid/a)"');
  const hash = preview.apply_command.split('--expect ')[1]!.split(' ')[0]!;
  expect(preview.apply_command).toBe(`gbrain repair frontmatter --source ${s.id} --apply --expect ${hash} --yes`);
  expect((await s.run()).apply_command).toBe(preview.apply_command);
  expect(s.read('notes/roundup.md')).toBe(QUOTABLE);
  expect((await refusal(() => s.run({ apply: true, expect: 'f'.repeat(64) }))).code).toBe('preview_changed');
  const applied = await s.run({ apply: true, expect: hash });
  expect(applied).toMatchObject({ applied: 1, outcomes: { repaired: 1 } });
  const expected = QUOTABLE.replace('author: alice-example (citing acme-example) (original: https://example.invalid/a)',
    'author: "alice-example (citing acme-example) (original: https://example.invalid/a)"');
  expect(s.read('notes/roundup.md')).toBe(expected);
  expect(applied.outcome_items![0]!.detail).toMatchObject({ path: 'notes/roundup.md', written: true, committed: 'queued' });
  const page = await engine.getPage('notes/roundup', { sourceId: s.id });
  expect(page?.id).toBe(before!.id);
  expect(page?.frontmatter.author).toBe(before!.frontmatter.author);
  // The Git target effect commits the repaired file like any coordinated page write.
  await gitEffectsSettled(engine, s.id);
  expect(git(s.root, 'status', '--porcelain', '--', 'notes/roundup.md')).toBe('');
  expect(git(s.root, 'show', 'HEAD:notes/roundup.md')).toBe(expected.trimEnd());
}), 180_000);

test('interpretations wait for --include-ambiguous (two-pass next_action), which changes the hash; --only approves one file and leaves the other held', () => each(async engine => {
  const s = await managed(engine, { 'notes/a.md': folded(1), 'notes/b.md': folded(2), 'notes/roundup.md': QUOTABLE });
  expect((await s.sync()).held_count).toBe(2);
  const safe = await s.run();
  expect(details(safe).counts).toMatchObject({ safe: 1, interpretive: 0, interpretive_pending: 2 });
  const safeHash = safe.apply_command.split('--expect ')[1]!.split(' ')[0]!;
  expect(details(safe).next_actions.map(action => action.argv)).toEqual([
    ['gbrain', 'repair', 'frontmatter', '--source', s.id, '--apply', '--expect', safeHash, '--yes'],
    ['gbrain', 'repair', 'frontmatter', '--source', s.id, '--include-ambiguous'],
  ]);
  expect(details(safe).next_actions[0]).toMatchObject({ consent: ['destructive'], plan_hash: safeHash });
  const wide = await s.run({ includeAmbiguous: true });
  expect(details(wide).counts).toMatchObject({ safe: 1, interpretive: 2, interpretive_pending: 0 });
  expect(wide.apply_command).not.toContain(safeHash);
  expect(details(wide).diffs.find(diff => diff.path === 'notes/a.md')!.diff).toContain('+title: "alice-example post 1\\nsecond line of post 1"');
  // The safe apply never writes an interpretive change.
  expect(await s.run({ apply: true, expect: safeHash })).toMatchObject({ applied: 1 });
  expect(s.read('notes/a.md')).toBe(folded(1));
  const one = await s.run({ includeAmbiguous: true, only: ['notes/a.md'] });
  expect(details(one).counts).toMatchObject({ interpretive: 1 });
  const oneHash = one.apply_command.split('--expect ')[1]!.split(' ')[0]!;
  expect(one.apply_command).toBe(`gbrain repair frontmatter --source ${s.id} --only notes/a.md --include-ambiguous --apply --expect ${oneHash} --yes`);
  expect((await refusal(() => s.run({ apply: true, expect: oneHash, includeAmbiguous: true }))).code).toBe('preview_changed');
  const applied = await s.run({ apply: true, expect: oneHash, includeAmbiguous: true, only: ['notes/a.md'] });
  expect(applied.outcome_items?.[0]?.detail).toMatchObject({ path: 'notes/a.md', imported: 'created', hold_cleared: true });
  expect((await engine.getPage('notes/a', { sourceId: s.id }))?.title).toBe('alice-example post 1\nsecond line of post 1');
  expect(s.read('notes/b.md')).toBe(folded(2));
  expect((await s.holds()).map(hold => hold.path)).toEqual(['notes/b.md']);
  expect(await engine.getPage('notes/b', { sourceId: s.id })).toBeNull();
}), 180_000);

test('a file edited after the preview is changed_since_preview and keeps its new bytes; needs_review files are listed with the manual fix and never written', () => each(async engine => {
  const s = await managed(engine, { 'notes/roundup.md': QUOTABLE, 'notes/broken.md': UNFIXABLE });
  await s.sync();
  const preview = await s.run({ includeAmbiguous: true });
  expect(details(preview).needs_review).toEqual([expect.objectContaining({ path: 'notes/broken.md', code: 'invalid_frontmatter' })]);
  expect(details(preview).needs_review[0]!.resolution).toContain('notes/broken.md');
  expect(preview.affected).toBe(1);
  const edited = QUOTABLE.replace('A synthetic roundup.', 'An edited roundup.');
  s.write('notes/roundup.md', edited);
  const hash = preview.apply_command.split('--expect ')[1]!.split(' ')[0]!;
  const applied = await s.run({ apply: true, expect: hash, includeAmbiguous: true });
  expect(applied).toMatchObject({ applied: 0, outcomes: { changed_since_preview: 1 } });
  expect(s.read('notes/roundup.md')).toBe(edited);
  expect(s.read('notes/broken.md')).toBe(UNFIXABLE);
}), 180_000);

const localCtx = (engine: BrainEngine, sourceId: string, remote = false) =>
  ({ engine, config: { engine: engine.kind }, logger: quiet, dryRun: false, remote, sourceId }) as unknown as OperationContext;

test('a held modified file: put_page stays refused for drift, the repair writes the exact bytes under its hash and updates the page', () => each(async engine => {
  const s = await managed(engine, { 'notes/post.md': note('Original') });
  await s.sync();
  const page = (await engine.getPage('notes/post', { sourceId: s.id }))!;
  s.write('notes/post.md', folded(7)); commit(s.root, 'broken edit');
  expect((await s.sync()).held?.[0]).toMatchObject({ path: 'notes/post.md', stale: true });
  const revision = (await engine.readPageSnapshot('notes/post', { sourceId: s.id }))!.revision;
  const drift = await refusal(() => submitPageMutation(localCtx(engine, s.id), { operation: 'put_page',
    params: { slug: 'notes/post', content: note('Agent write'), source_id: s.id, expected_revision: revision } }));
  expect(drift.detail).toBe('file_database_drift');
  const preview = await s.run({ includeAmbiguous: true });
  const hash = preview.apply_command.split('--expect ')[1]!.split(' ')[0]!;
  const proposed = details(preview).diffs[0]!;
  expect(proposed).toMatchObject({ path: 'notes/post.md', class: 'interpretive', selected: true });
  const applied = await s.run({ apply: true, expect: hash, includeAmbiguous: true });
  expect(applied.outcome_items?.[0]?.detail).toMatchObject({ imported: 'updated', hold_cleared: true, written: true });
  expect(s.read('notes/post.md')).toBe('---\ntitle: "alice-example post 7\\nsecond line of post 7"\n---\nA synthetic post.\n');
  const after = (await engine.getPage('notes/post', { sourceId: s.id }))!;
  expect(after.id).toBe(page.id);
  expect(after.title).toBe('alice-example post 7\nsecond line of post 7');
  expect(await s.holds()).toEqual([]);
  // A later sync of the committed repair imports nothing new and holds nothing.
  await gitEffectsSettled(engine, s.id);
  expect((await s.sync()).held_count ?? 0).toBe(0);
}), 180_000);

test('#6188: a held fence file is never rewritten by frontmatter repair; its resolution defers to that file\'s gbrain repair fences preview', () => each(async engine => {
  const takes = '<!--- gbrain:takes:begin -->\n| # | claim | kind | who | weight | since | source |\n|---|---|---|---|---|---|---|\n'
    + '| 1 | Sentinelclaimq93 renews | take | Sentinelholderq93 Example | 0.7 | 2026-01 | chat |\n<!--- gbrain:takes:end -->';
  const s = await managed(engine, { 'notes/a.md': note('A'), 'people/fenced.md': note('Fenced', `A synthetic page.\n\n${takes}`) });
  await s.sync();
  expect((await s.holds()).map(hold => [hold.path, hold.code])).toEqual([['people/fenced.md', 'invalid_fence']]);
  const before = s.read('people/fenced.md');
  const review = details(await s.run()).needs_review.find(entry => entry.path === 'people/fenced.md');
  expect(review).toMatchObject({ code: 'invalid_fence' });
  expect(review!.resolution).toContain(`gbrain repair fences --source ${s.id} --only people/fenced.md`);
  expect(review!.resolution).toContain('frontmatter repair does not change fences');
  for (const secret of ['Sentinelclaimq93', 'Sentinelholderq93']) expect(JSON.stringify(review)).not.toContain(secret);
  expect(s.read('people/fenced.md')).toBe(before);
}), 180_000);

test('a repaired file whose import would keep a database-only tag is needs_review (canonical overlay), never written', () => each(async engine => {
  const s = await managed(engine, { 'notes/post.md': note('Original') });
  await s.sync();
  await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
  await engine.addTag('notes/post', 'kept-in-db', { sourceId: s.id });
  await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
  s.write('notes/post.md', folded(3)); commit(s.root, 'broken edit');
  await s.sync();
  const preview = await s.run({ includeAmbiguous: true });
  expect(preview.affected).toBe(0);
  expect(details(preview).needs_review).toEqual([expect.objectContaining({ path: 'notes/post.md', code: 'canonical_overlay' })]);
  expect(s.read('notes/post.md')).toBe(folded(3));
}), 180_000);

test('apply refuses while an unfinished managed sync cursor still names a selected file, and names the sync to finish', () => each(async engine => {
  const s = await managed(engine, { 'notes/roundup.md': QUOTABLE });
  await s.sync();
  const preview = await s.run();
  const hash = preview.apply_command.split('--expect ')[1]!.split(' ')[0]!;
  const runId = randomUUID();
  await engine.executeRaw(`INSERT INTO op_checkpoints(op,fingerprint,completed_keys) VALUES('managed-sync',$1,$2::text::jsonb)`,
    [`fixture-${runId}`, JSON.stringify([{ sourceId: s.id, incarnation: (await engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text AS incarnation FROM sources WHERE id=$1', [s.id]))[0]!.incarnation, runId, index: 0, total: 1 }])]);
  await engine.executeRaw(`INSERT INTO op_checkpoints(op,fingerprint,completed_keys) VALUES('managed-sync-manifest',$1,$2::text::jsonb)`,
    [runId, JSON.stringify([{ path: 'notes/roundup.md', sourcePath: 'notes/roundup.md', action: 'import', working: false }])]);
  try {
    const error = await refusal(() => s.run({ apply: true, expect: hash }));
    expect(error.code).toBe('sync_in_progress');
    expect(error.suggestion).toContain(`gbrain sync --source ${s.id} --no-pull`);
    expect(s.read('notes/roundup.md')).toBe(QUOTABLE);
  } finally {
    await engine.executeRaw("DELETE FROM op_checkpoints WHERE (op='managed-sync' AND fingerprint=$1) OR (op='managed-sync-manifest' AND fingerprint=$2)", [`fixture-${runId}`, runId]);
  }
}), 180_000);

test('managed_file_repair is trusted-local only: MCP put_page cannot name it and a remote caller is refused before admission', () => each(async engine => {
  const s = await managed(engine, { 'notes/roundup.md': QUOTABLE });
  await s.sync();
  const params = { slug: 'notes/roundup', source_id: s.id, kind: 'managed_file_repair', content: note('Injected'), path: 'notes/roundup.md', sourcePath: 'notes/roundup.md' };
  const viaMcp = await refusal(() => submitPageMutation(localCtx(engine, s.id, true), { operation: 'put_page', params }));
  expect(viaMcp.code).toBe('invalid_params');
  const viaLocalPut = await refusal(() => submitPageMutation(localCtx(engine, s.id), { operation: 'put_page', params }));
  expect(viaLocalPut.code).toBe('invalid_params');
  const remote = await refusal(() => submitManagedFileRepair(localCtx(engine, s.id, true), { sourceId: s.id, requestId: randomUUID(), slug: 'notes/roundup',
    path: 'notes/roundup.md', sourcePath: 'notes/roundup.md', content: note('Injected'), beforeHash: sha256(QUOTABLE), resultDigest: 'x', noEmbed: true }));
  expect(remote).toMatchObject({ code: 'permission_denied', reason: 'trusted_cli_required' });
  expect(s.read('notes/roundup.md')).toBe(QUOTABLE);
}), 180_000);

test('repair paths are confined: climbing, absolute and symlinked paths are refused before anything is written', () => {
  const root = mkdtempSync(join(home, 'confine-'));
  const outside = mkdtempSync(join(home, 'outside-'));
  writeFileSync(join(outside, 'secret.md'), note('Outside'));
  mkdirSync(join(root, 'notes'));
  writeFileSync(join(root, 'notes', 'ok.md'), note('Ok'));
  symlinkSync(outside, join(root, 'linked'));
  symlinkSync(join(outside, 'secret.md'), join(root, 'notes', 'link.md'));
  expect(confinedRepairTarget(root, 'notes/ok.md', 'src')).toBe(join(root, 'notes', 'ok.md'));
  for (const path of ['../outside/secret.md', join(outside, 'secret.md'), 'linked/secret.md', 'notes/link.md', 'notes/missing.md']) {
    let error: unknown;
    try { confinedRepairTarget(root, path, 'src'); } catch (caught) { error = caught; }
    expect(error).toBeInstanceOf(OperationError);
    expect((error as OperationError).code).toBe('source_changed');
  }
});

test('a held renamed file: the repair moves the old page with its id instead of creating a second page', () => each(async engine => {
  const s = await managed(engine, { 'notes/old.md': pinned('Old', 'notes/old') });
  await s.sync();
  const page = (await engine.getPage('notes/old', { sourceId: s.id }))!;
  git(s.root, 'mv', 'notes/old.md', 'notes/new.md'); commit(s.root, 'exact move onto a stale slug: line');
  expect(git(s.root, 'diff', '--name-status', '-M', 'HEAD~1', 'HEAD')).toMatch(/^R100\t/);
  await s.sync();
  expect((await s.holds())[0]).toMatchObject({ path: 'notes/new.md', meta: { rename_from: { slug: 'notes/old', pageId: page.id } } });
  const preview = await s.run({ includeAmbiguous: true });
  const hash = preview.apply_command.split('--expect ')[1]!.split(' ')[0]!;
  const applied = await s.run({ apply: true, expect: hash, includeAmbiguous: true });
  expect(applied.outcome_items?.[0]?.detail).toMatchObject({ imported: 'renamed', hold_cleared: true });
  expect((await engine.getPage('notes/new', { sourceId: s.id }))?.id).toBe(page.id);
  expect(await engine.getPage('notes/old', { sourceId: s.id })).toBeNull();
  const [{ count }] = await engine.executeRaw<{ count: number }>('SELECT count(*)::int AS count FROM pages WHERE source_id=$1 AND deleted_at IS NULL', [s.id]);
  expect(Number(count)).toBe(1);
}), 180_000);

test('a rename held because the old page changed is re-bound to its current revision only under --include-ambiguous', () => each(async engine => {
  const s = await managed(engine, { 'notes/x.md': pinned('X', 'notes/x') });
  await s.sync();
  const x = (await engine.getPage('notes/x', { sourceId: s.id }))!;
  git(s.root, 'mv', 'notes/x.md', 'notes/y.md'); commit(s.root, 'x to y, held');
  await s.sync();
  await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
  await engine.executeRaw('UPDATE pages SET knowledge_revision=gen_random_uuid() WHERE id=$1', [x.id]);
  await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
  s.write('notes/y.md', long('Y')); commit(s.root, 'fix y');
  await s.sync();
  expect((await s.holds())[0]).toMatchObject({ path: 'notes/y.md', code: 'rename_held' });
  const safe = await s.run();
  expect(details(safe).counts).toMatchObject({ safe: 0, interpretive_pending: 1 });
  const preview = await s.run({ includeAmbiguous: true });
  expect(details(preview).diffs[0]!.fixes.join(' ')).toContain('Re-bind the rename of notes/y.md to page notes/x');
  const hash = preview.apply_command.split('--expect ')[1]!.split(' ')[0]!;
  const applied = await s.run({ apply: true, expect: hash, includeAmbiguous: true });
  expect(applied.outcome_items?.[0]?.detail).toMatchObject({ imported: 'renamed', hold_cleared: true, written: false });
  expect((await engine.getPage('notes/y', { sourceId: s.id }))).toMatchObject({ id: x.id, title: 'Y' });
  expect(await s.holds()).toEqual([]);
}), 180_000);

test('database side: a page whose body begins with its own frontmatter block is re-imported from its clean file under --include-ambiguous', () => each(async engine => {
  const s = await managed(engine, { 'notes/fact.md': note('Real title', 'The real body.'), 'notes/twice.md': `---\ntitle: Outer\n---\n---\ntitle: Inner\n---\nBody.\n` });
  await s.sync();
  await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
  await engine.executeRaw("UPDATE pages SET compiled_truth=$2, title='Fact' WHERE source_id=$1 AND slug='notes/fact'", [s.id, '---\ntitle: Real title\n---\nThe real body.']);
  await engine.executeRaw("UPDATE pages SET title='Twice' WHERE source_id=$1 AND slug='notes/twice'", [s.id]);
  await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
  const safe = await s.run();
  expect(details(safe).counts.interpretive_pending).toBe(1);
  const preview = await s.run({ includeAmbiguous: true });
  expect(details(preview).diffs).toEqual([expect.objectContaining({ path: 'notes/fact.md', class: 'interpretive' })]);
  expect(details(preview).needs_review).toEqual([expect.objectContaining({ path: 'notes/twice.md', code: 'embedded_frontmatter' })]);
  const hash = preview.apply_command.split('--expect ')[1]!.split(' ')[0]!;
  const applied = await s.run({ apply: true, expect: hash, includeAmbiguous: true });
  expect(applied.outcome_items?.[0]?.detail).toMatchObject({ imported: 'updated', written: false });
  const fixed = (await engine.getPage('notes/fact', { sourceId: s.id }))!;
  expect(fixed.title).toBe('Real title');
  expect(fixed.compiled_truth.trim()).toBe('The real body.');
  expect(s.read('notes/fact.md')).toBe(note('Real title', 'The real body.'));
}), 180_000);

test('legacy brain: the apply backs the file up, writes it, imports it, clears its hold and prints the commit step', async () => {
  const engine = legacyEngine;
  await withEnv(env, async () => {
    await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    const id = 'legacy-fm', root = join(home, id);
    mkdirSync(join(root, 'notes'), { recursive: true });
    writeFileSync(join(root, 'notes', 'roundup.md'), QUOTABLE);
    writeFileSync(join(root, 'notes', 'post.md'), folded(4));
    await engine.executeRaw("INSERT INTO sources(id,name,local_path,config) VALUES($1,$1,$2,'{}')", [id, root]);
    const [{ incarnation }] = await engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text AS incarnation FROM sources WHERE id=$1', [id]);
    // The hold legacy sync records for the folded file.
    await writeGitHold(engine, { source_id: id, incarnation, path: 'notes/post.md', source_path: 'notes/post.md', slug: 'notes/post', page_id: null,
      code: 'invalid_frontmatter', message: 'Invalid YAML frontmatter: key "title" at line 2 continues on unquoted lines.', upstream_version: sha256(folded(4)),
      observed_at: new Date().toISOString(), run_id: 'legacy-fixture', mode: 'legacy', meta: { reason: 'needs_interpretation', key: 'title', line: 2, recovery_version: 1 } });
    const s = fixture(engine, id, root, (path, content) => writeFileSync(join(root, path), content));
    const preview = await s.run({ includeAmbiguous: true });
    expect(details(preview).counts).toMatchObject({ safe: 1, interpretive: 1 });
    const hash = preview.apply_command.split('--expect ')[1]!.split(' ')[0]!;
    const applied = await s.run({ apply: true, expect: hash, includeAmbiguous: true });
    expect(applied.outcome_items!.find(o => o.detail?.path === 'notes/post.md')!.detail).toMatchObject({ written: true, hold_cleared: true });
    expect(await s.holds()).toEqual([]);
    expect((await engine.getPage('notes/post', { sourceId: id }))?.title).toBe('alice-example post 4\nsecond line of post 4');
    const detail = applied.outcome_items!.find(o => o.detail?.path === 'notes/roundup.md')!.detail!;
    expect(detail).toMatchObject({ path: 'notes/roundup.md', written: true, imported: 'imported', committed: 'commit_step' });
    expect(detail.commit_step).toBe(`gbrain git commit-push --path ${root} -m 'fix(frontmatter): repair notes/roundup.md' -- notes/roundup.md`);
    expect(readFileSync(String(detail.backup), 'utf8')).toBe(QUOTABLE);
    expect(s.read('notes/roundup.md')).toContain('author: "alice-example');
    expect((await engine.getPage('notes/roundup', { sourceId: id }))?.frontmatter.author).toBe('alice-example (citing acme-example) (original: https://example.invalid/a)');
  });
}, 120_000);

test('the CLI apply asks for destructive consent: without --yes a non-interactive run exits 3 and writes nothing', () => each(async engine => {
  const s = await managed(engine, { 'notes/roundup.md': QUOTABLE });
  await s.sync();
  const hash = (await s.run()).apply_command.split('--expect ')[1]!.split(' ')[0]!;
  _resetCliExitVerdictForTests();
  let printed = '';
  const original = console.log, write = process.stdout.write;
  console.log = (...parts: unknown[]) => { printed += parts.map(String).join(' '); };
  process.stdout.write = ((chunk: string | Uint8Array) => { printed += String(chunk); return true; }) as typeof process.stdout.write;
  try { await withEnv({ GBRAIN_INTERACTIVE: '0', CI: '1' }, () => runRepairCommand(engine, ['frontmatter', '--source', s.id, '--apply', '--expect', hash, '--json'])); }
  finally { console.log = original; process.stdout.write = write; }
  expect(currentExitCode()).toBe(3);
  expect(JSON.parse(printed)).toMatchObject({ code: 'confirmation_required', effects: ['destructive'] });
  expect(s.read('notes/roundup.md')).toBe(QUOTABLE);
  _resetCliExitVerdictForTests();
  console.log = () => {};
  try { await runRepairCommand(engine, ['frontmatter', '--source', s.id, '--apply', '--expect', hash, '--yes', '--json']); } finally { console.log = original; }
  expect(currentExitCode()).toBe(0);
  expect(s.read('notes/roundup.md')).toContain('author: "alice-example');
}), 180_000);

test('database side: a slug-derived title under a file that names one is re-imported; a page whose file now holds a protected key is flagged', () => each(async engine => {
  const s = await managed(engine, { 'notes/launch-plan.md': note('The real launch plan'), 'notes/private.md': note('Private') });
  await s.sync();
  await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
  await engine.executeRaw("UPDATE pages SET title='Launch Plan' WHERE source_id=$1 AND slug='notes/launch-plan'", [s.id]);
  await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
  s.write('notes/private.md', '---\ntitle: Private\nvisibility: private # note: x\n---\nBody.\n'); commit(s.root, 'protected key');
  expect((await s.sync()).held?.[0]).toMatchObject({ path: 'notes/private.md', reason: 'ambiguous_protected_key', stale: true });
  const preview = await s.run({ includeAmbiguous: true });
  expect(details(preview).diffs).toEqual([expect.objectContaining({ path: 'notes/launch-plan.md', class: 'interpretive' })]);
  expect(details(preview).diffs[0]!.fixes[0]).toContain('title was derived from the slug');
  expect(details(preview).needs_review).toEqual([expect.objectContaining({ path: 'notes/private.md', reason: 'ambiguous_protected_key', key: 'visibility', flag: 'imported_before_hold' })]);
  const hash = preview.apply_command.split('--expect ')[1]!.split(' ')[0]!;
  await s.run({ apply: true, expect: hash, includeAmbiguous: true });
  expect((await engine.getPage('notes/launch-plan', { sourceId: s.id }))?.title).toBe('The real launch plan');
}), 180_000);