Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
35.8 KB
Raw Blame
/**
 * #5988 Lane B item 5: Git holds outside sync itself. `sources status <id>`
 * filters to the source and lists its held files (X2 fields, text and JSON);
 * `sources retry-held` schedules a re-screen of a Git source's held files;
 * `sync --retry-held` refuses with the pointer; Git holds never block writer
 * deactivation or activation (X14); a put_page refused over a held file names
 * the hold instead of reconciliation (E26).
 *
 * #6188 PR4 (D6, D16, D17, E35, Codex CEO #7): for a fence-only, a
 * frontmatter-only and a mixed source, every DB-backed surface (sources
 * status JSON and text, retry-held, doctor git_held_files and its banner
 * line, the sync hold report, get_page file_held, the held_files notice, the
 * held-file write refusal) names the right repair command and a fence-only
 * source never mentions frontmatter; a fence hold's rendered next follows its
 * state on the CLI and HTTP transports with the maintenance run active and
 * inactive; a remote status read returns the owner handoff; no claim, holder
 * or kind text reaches any of them.
 */
import { afterAll, beforeAll, describe, expect, spyOn, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { serializePageToMarkdown } from '../src/core/markdown.ts';
import { runSources } from '../src/commands/sources.ts';
import { retryHeld, runRetryHeld } from '../src/commands/sources-retry-held.ts';
import { parseSyncFlags } from '../src/commands/sync/args.ts';
import { CLI_FLAG_REGISTRY } from '../src/core/cli-flag-registry.generated.ts';
import { claimWorktree } from '../src/core/persistence/ownership.ts';
import { prepareFileTarget } from '../src/core/persistence/page-prepare.ts';
import { heldFileMessage, writeFailureDiagnostic } from '../src/core/persistence/verb-errors.ts';
import { readGitHold, readGitHoldListing, readGitHoldRetryPaths, writeGitHold, type GitHoldRecord } from '../src/core/persistence/sync-holds.ts';
import { runPersistenceAdministration } from '../src/core/persistence/administration.ts';
import { writerAdminState } from '../src/core/persistence/admin-intent.ts';
import { carryLegacyFailCounts } from '../src/core/connectors/item-holds.ts';
import { connectorCheckpointKey, connectorIdentity } from '../src/core/persistence/connector-identity.ts';
import { managedBrain } from './helpers/managed-brain.ts';
import { waitFor } from './helpers/wait-for.ts';
import { put } from './helpers/wave-fixture.ts';
import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';
import { buildHoldReport, readSyncHoldPolicy } from '../src/core/persistence/sync-holds.ts';
import { heldFilesNotice, readHeldCoverage } from '../src/core/persistence/held-reads.ts';
import { heldFileDiagnostic } from '../src/core/persistence/verb-errors.ts';
import { gitHeldFilesCheck } from '../src/commands/doctor/checks/git-holds.ts';
import { WAVE_CHECKS } from '../src/commands/doctor/wave-checks.ts';
import { bannerFindingLine } from '../src/commands/doctor/upgrade-banner.ts';
import { operations, type OperationContext } from '../src/core/operations.ts';
import { cliRenderContext, renderAction, type Action } from '../src/core/agent-output.ts';
import { fenceMessage } from '../src/core/fence-repair/reasons.ts';
import { RECOVERY_VERSION } from '../src/core/markdown.ts';
import { withEnv } from './helpers/with-env.ts';

type HoldInput = Omit<GitHoldRecord, 'version' | 'held_at' | 'updated_at'>;

const incarnationOf = async (engine: BrainEngine, sourceId: string) =>
  (await engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text AS incarnation FROM sources WHERE id=$1', [sourceId]))[0].incarnation;

const hold = (sourceId: string, incarnation: string, path: string, extra: Partial<HoldInput> = {}): HoldInput => ({
  source_id: sourceId, incarnation, path, source_path: path, slug: path.replace(/\.md$/, ''), page_id: null, code: 'invalid_frontmatter',
  message: 'Invalid YAML frontmatter: key "title" at line 2 continues on unquoted lines.', upstream_version: `sha-${path}`,
  observed_at: '2026-10-01T00:00:00.000Z', run_id: 'run-1', mode: 'managed',
  meta: { reason: 'needs_interpretation', key: 'title', line: 2, recovery_version: 1 }, ...extra,
});

async function captured(run: () => Promise<void>): Promise<string> {
  const lines: string[] = [];
  const log = spyOn(console, 'log').mockImplementation((...args: unknown[]) => { lines.push(args.map(String).join(' ')); });
  const warn = spyOn(console, 'warn').mockImplementation(() => {});
  try { await run(); } finally { log.mockRestore(); warn.mockRestore(); }
  return lines.join('\n');
}

describe('sources status and retry-held on Git sources', () => {
  let engine: PGLiteEngine;
  let home: string;

  beforeAll(async () => {
    engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema();
    home = mkdtempSync(join(tmpdir(), 'gbrain-hold-surfaces-'));
    for (const id of ['notes-git', 'other-git']) {
      mkdirSync(join(home, id));
      await engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', [id, join(home, id)]);
    }
    await engine.putPage('notes/stale', { type: 'note', title: 'Stale', compiled_truth: 'Old body.' }, { sourceId: 'notes-git' });
    const [page] = await engine.executeRaw<{ id: number }>("SELECT id FROM pages WHERE source_id='notes-git' AND slug='notes/stale'");
    const notes = await incarnationOf(engine, 'notes-git');
    await writeGitHold(engine, hold('notes-git', notes, 'notes/stale.md', { page_id: Number(page.id) }));
    await writeGitHold(engine, hold('notes-git', notes, 'notes/huge.md', { code: 'file_too_large', message: 'File too large (12 MB).', upstream_version: null,
      meta: { recovery_version: 1 } }));
    await writeGitHold(engine, hold('other-git', await incarnationOf(engine, 'other-git'), 'other/a.md'));
  }, 120_000);

  afterAll(async () => { await engine.disconnect(); rmSync(home, { recursive: true, force: true }); }, 60_000);

  test('sources status <id> --json lists only that source, with its held files and their X2 fields', async () => {
    const doc = JSON.parse(await captured(() => runSources(engine, ['status', 'notes-git', '--json'])));
    expect(doc.sources.map((s: { source_id: string }) => s.source_id)).toEqual(['notes-git']);
    const holds = doc.sources[0].git_holds;
    expect(holds).toMatchObject({ count: 2, sync_argv: ['gbrain', 'sync', '--source', 'notes-git'] });
    expect(holds.truncated).toBeUndefined();
    const byPath = Object.fromEntries(holds.items.map((item: { path: string }) => [item.path, item]));
    expect(byPath['notes/stale.md']).toMatchObject({ code: 'invalid_frontmatter', reason: 'needs_interpretation', key: 'title', line: 2, stale: true,
      docs: 'docs/guides/write-refusals.md#invalid_frontmatter-needs_interpretation',
      fix: { argv: ['gbrain', 'repair', 'frontmatter', '--source', 'notes-git', '--include-ambiguous'] } });
    expect(typeof byPath['notes/stale.md'].held_since).toBe('string');
    expect(byPath['notes/huge.md']).toMatchObject({ code: 'file_too_large', stale: false, docs: 'docs/guides/write-refusals.md#file_too_large' });
    expect(byPath['notes/huge.md'].fix.why).toContain('size limit is fixed');

    const all = JSON.parse(await captured(() => runSources(engine, ['status', '--json'])));
    expect(all.sources.find((s: { source_id: string }) => s.source_id === 'other-git').git_holds.count).toBe(1);
    expect(all.sources.find((s: { source_id: string }) => s.source_id === 'default').git_holds).toBeUndefined();
  });

  test('sources status <id> text names each held file, its next step and the re-screen commands; other sources are not listed', async () => {
    const text = await captured(() => runSources(engine, ['status', 'notes-git']));
    expect(text).toContain('notes-git: 2 held file(s): not imported, and they do not block sync.');
    expect(text).toContain('read-only for put_page until the file is repaired');
    expect(text).toMatch(/Held notes\/stale\.md: invalid_frontmatter \(needs_interpretation\) at line 2, key "title"; .* Next: gbrain repair frontmatter --source notes-git --include-ambiguous/);
    expect(text).toMatch(/Held notes\/huge\.md: file_too_large; its page is missing until the file imports\. Next: gbrain config get sync\.exclude/);
    expect(text).toContain('Most holds re-screen on the next sync by themselves');
    expect(text).toContain('gbrain sync --source notes-git');
    expect(text).toContain('gbrain sources retry-held notes-git');
    expect(text).not.toContain('other-git');
  });

  test('sources status lists at most GBRAIN_SYNC_HOLD_CAP holds per source, limited in SQL, with the outstanding count from the summary row', async () => {
    const listing = await readGitHoldListing(engine, ['notes-git', 'other-git', 'default'], 1);
    expect(listing.map(source => [source.sourceId, source.count, source.holds.map(record => record.path)])).toEqual([
      ['notes-git', 2, ['notes/huge.md']], ['other-git', 1, ['other/a.md']]]);
    await withEnv({ GBRAIN_SYNC_HOLD_CAP: '1' }, async () => {
      const doc = JSON.parse(await captured(() => runSources(engine, ['status', 'notes-git', '--json'])));
      expect(doc.sources[0].git_holds).toMatchObject({ count: 2, truncated: true });
      expect(doc.sources[0].git_holds.items.map((item: { path: string }) => item.path)).toEqual(['notes/huge.md']);
      const text = await captured(() => runSources(engine, ['status', 'notes-git']));
      expect(text).toContain('notes-git: 2 held file(s)');
    });
  });

  test('#7326: sources status --limit / --cursor page the held files of one source by path; --cursor needs the source and --limit is never read as a source id', async () => {
    const first = JSON.parse(await captured(() => runSources(engine, ['status', 'notes-git', '--json', '--limit', '1']))).sources[0].git_holds;
    expect(first).toMatchObject({ count: 2, returned: 1, limit: 1, complete: false });
    expect(first.by_code.map((group: { code: string }) => group.code).sort()).toEqual(['file_too_large', 'invalid_frontmatter']);
    expect(first.next_command).toEqual(['gbrain', 'sources', 'status', 'notes-git', '--json', '--limit', '1', '--cursor', first.next_cursor]);
    const second = JSON.parse(await captured(() => runSources(engine, ['status', 'notes-git', '--json', '--limit', '1', '--cursor', first.next_cursor]))).sources[0].git_holds;
    expect(second).toMatchObject({ returned: 1, complete: true, next_cursor: null });
    expect([...first.items, ...second.items].map((item: { path: string }) => item.path)).toEqual(['notes/huge.md', 'notes/stale.md']);
    const unnamed = JSON.parse(await captured(() => runSources(engine, ['status', '--json', '--limit', '5'])));
    expect(unnamed.sources.find((s: { source_id: string }) => s.source_id === 'notes-git').git_holds.returned).toBe(2);
    await expect(runSources(engine, ['status', '--json', '--cursor', first.next_cursor])).rejects.toThrow(/one source/);
  });

  test('sources status <unknown id> refuses with not_found and the list command', async () => {
    await expect(runSources(engine, ['status', 'missing-src'])).rejects.toMatchObject({ code: 'not_found',
      fix: { argv: ['gbrain', 'sources', 'list', '--json'] } });
  });

  test('retry-held on a Git source: --dry-run changes nothing; the real run records a re-screen of every held path', async () => {
    const dry = await retryHeld(engine, 'notes-git', { dryRun: true });
    expect(dry).toMatchObject({ kind: 'git', dry_run: true, scheduled: 0, fix: { argv: ['gbrain', 'sources', 'retry-held', 'notes-git'] } });
    expect(dry.items.map(item => [item.key, item.action])).toEqual([['notes/huge.md', 'would_retry'], ['notes/stale.md', 'would_retry']]);
    expect(await readGitHoldRetryPaths(engine, 'notes-git', await incarnationOf(engine, 'notes-git'))).toEqual([]);

    const text = await captured(() => runRetryHeld(engine, ['notes-git']));
    expect(text).toContain('notes/stale.md (invalid_frontmatter, needs_interpretation): retry_scheduled');
    expect(text).toContain('2 held file(s) scheduled for a re-screen; none has run yet.');
    expect(text).toContain('Most holds re-screen on the next sync by themselves');
    expect(text).toContain('Run it now with: gbrain sync --source notes-git,');
    expect(text).toContain('gbrain repair frontmatter --source notes-git');
    expect((await readGitHoldRetryPaths(engine, 'notes-git', await incarnationOf(engine, 'notes-git'))).sort()).toEqual(['notes/huge.md', 'notes/stale.md']);

    const json = JSON.parse(await captured(() => runRetryHeld(engine, ['notes-git', '--json'])));
    expect(json).toMatchObject({ source_id: 'notes-git', kind: 'git', scheduled: 2, fix: { argv: ['gbrain', 'sync', '--source', 'notes-git'] } });
    expect((await retryHeld(engine, 'notes-git', { dryRun: true })).items.every(item => item.action === 'retry_scheduled')).toBe(true);
    expect((await retryHeld(engine, 'default')).next_action).toBe('No held files for default.');
  });
});

describe('gbrain sync --retry-held', () => {
  test('is refused with a typed error pointing at sources retry-held', () => {
    expect(CLI_FLAG_REGISTRY.sync).toContain('--retry-held');
    let error: any;
    try { parseSyncFlags(['--retry-held', '--source', 'notes-git']); } catch (e) { error = e; }
    expect(error).toMatchObject({ code: 'invalid_params', fix: { argv: ['gbrain', 'sources', 'retry-held', 'notes-git'],
      verify: { argv: ['gbrain', 'sources', 'status', 'notes-git', '--json'] } } });
    expect(error.message).toContain('no --retry-held flag');
    expect(error.suggestion).toContain('gbrain sources retry-held notes-git');
    try { parseSyncFlags(['--retry-held']); } catch (e) { error = e; }
    expect(error.fix.argv).toEqual(['gbrain', 'sources', 'retry-held', '<source-id>']);
    expect(error.fix.inputs).toEqual([expect.objectContaining({ name: 'source-id' })]);
  });
});

describe('a page whose file is held refuses put_page naming the hold', () => {
  let engine: PGLiteEngine;
  let home: string;
  let root: string;
  let worktreeId: string;
  const sourceId = 'held-drift';

  beforeAll(async () => {
    engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema();
    home = mkdtempSync(join(tmpdir(), 'gbrain-held-drift-'));
    root = join(home, 'source'); mkdirSync(root);
    await engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', [sourceId, root]);
    worktreeId = (await claimWorktree(engine, sourceId, root)).worktree_id;
  }, 60_000);
  afterAll(async () => { await engine.disconnect(); rmSync(home, { recursive: true, force: true }); }, 60_000);

  async function seed(slug: string) {
    await engine.putPage(slug, { type: 'note', title: 'Held', compiled_truth: 'Last good body' }, { sourceId });
    await engine.executeRaw('UPDATE pages SET source_path=$1 WHERE source_id=$2 AND slug=$3', [`${slug}.md`, sourceId, slug]);
    const snapshot = (await engine.readPageSnapshot(slug, { sourceId }))!;
    const file = join(root, `${slug}.md`);
    mkdirSync(dirname(file), { recursive: true });
    writeFileSync(file, serializePageToMarkdown(snapshot.page, snapshot.tags));
    return { snapshot, file, row: { source_id: sourceId, worktree_id: worktreeId, slug } };
  }

  test('drift over a held file names the hold, keeps file_database_drift, and points at repair instead of reconcile', async () => {
    const { snapshot, file, row } = await seed('notes/held');
    writeFileSync(file, readFileSync(file, 'utf8').replace(/^title:.*$/m, 'title: Broken\n  continued tweet text'));
    await expect(prepareFileTarget(engine, row, snapshot, 'Replacement')).rejects.toMatchObject({ detail: 'file_database_drift',
      suggestion: expect.stringContaining('gbrain sources reconcile') });
    await writeGitHold(engine, hold(sourceId, await incarnationOf(engine, sourceId), 'notes/held.md', { page_id: Number(snapshot.page.id) }));
    let error: any;
    try { await prepareFileTarget(engine, row, snapshot, 'Replacement'); } catch (e) { error = e; }
    expect(error).toMatchObject({ code: 'source_changed', detail: 'file_database_drift', message: heldFileMessage('drift', 'invalid_frontmatter', { sourceId, incarnation: await incarnationOf(engine, sourceId) }),
      fix: { argv: ['gbrain', 'repair', 'frontmatter', '--source', sourceId, '--include-ambiguous'] } });
    expect(error.suggestion).toContain('Sync holds notes/held.md in source held-drift (invalid_frontmatter, needs_interpretation at line 2, key "title")');
    expect(error.suggestion).toContain('read-only for put_page until the file is repaired');
    expect(error.suggestion).not.toContain('sources reconcile');
    expect(error.message).not.toContain('continued tweet text');
  });

  test('a remote caller hitting a held file gets the code and the host operator command, never the path or key', async () => {
    const { snapshot, file, row } = await seed('notes/held-remote');
    writeFileSync(file, readFileSync(file, 'utf8').replace(/^title:.*$/m, 'title: Broken\n  continued tweet text'));
    await writeGitHold(engine, hold(sourceId, await incarnationOf(engine, sourceId), 'notes/held-remote.md', { page_id: Number(snapshot.page.id) }));
    let error: any;
    try { await prepareFileTarget(engine, row, snapshot, 'Replacement', undefined, { remote: true }); } catch (e) { error = e; }
    expect(error).toMatchObject({ code: 'source_changed', detail: 'file_database_drift', message: heldFileMessage('drift', 'invalid_frontmatter', { sourceId, incarnation: await incarnationOf(engine, sourceId) }),
      fix: { actor: 'host_admin', argv: ['gbrain', 'repair', 'frontmatter', '--source', sourceId] } });
    const text = JSON.stringify({ message: error.message, suggestion: error.suggestion, fix: error.fix });
    expect(text).toContain('read-only for put_page until the brain host operator repairs the file');
    for (const hidden of ['held-remote.md', '"title"', root, 'continued tweet text']) expect(text).not.toContain(hidden);
  });

  test('an unindexed held file occupying a new page path names the hold', async () => {
    const file = join(root, 'notes', 'new-held.md');
    mkdirSync(dirname(file), { recursive: true });
    writeFileSync(file, '---\ntitle: Broken\n  continued\n---\nBody\n');
    const row = { source_id: sourceId, worktree_id: worktreeId, slug: 'notes/new-held' };
    await expect(prepareFileTarget(engine, row, null, 'Rendered')).rejects.toMatchObject({ message: 'An unindexed file already occupies the canonical page path.' });
    await writeGitHold(engine, hold(sourceId, await incarnationOf(engine, sourceId), 'notes/new-held.md'));
    await expect(prepareFileTarget(engine, row, null, 'Rendered')).rejects.toMatchObject({ code: 'source_changed',
      message: heldFileMessage('occupied', 'invalid_frontmatter', { sourceId, incarnation: await incarnationOf(engine, sourceId) }), suggestion: expect.stringContaining('does not exist yet') });
  });

  test('receipts keep only the location-free message; the diagnostic maps it to the same reasons with the repair command', () => {
    expect(writeFailureDiagnostic('source_changed', heldFileMessage('drift', 'invalid_frontmatter'))).toMatchObject({ reason: 'file_database_drift',
      message: heldFileMessage('drift', 'invalid_frontmatter'), suggestion: expect.stringContaining('gbrain repair frontmatter --source <source>') });
    const occupied = writeFailureDiagnostic('source_changed', heldFileMessage('occupied', 'file_too_large'));
    expect(occupied.reason).toBe('canonical_path_occupied');
    expect(occupied.suggestion).toContain('refuses put_page until the file is repaired');
    expect(writeFailureDiagnostic('source_changed', 'The canonical file contains an uncoordinated local edit.').suggestion).toContain('gbrain sources reconcile');
  });
});

describe('Git holds and writer mode changes (X14)', () => {
  const gmailConfig = { kind: 'google', g_account: '[email protected]', g_services: 'gmail', g_access: 'env', g_token_env: 'CONNECTOR_TEST_TOKEN' };
  const admin = (engine: BrainEngine, operation: string, params: Record<string, unknown> = {}) =>
    runPersistenceAdministration(engine, operation as never, params) as Promise<Record<string, any>>;

  test('holds survive activation, never block deactivation, and survive it unchanged; uncarriable connector holds still block', () => managedBrain(async ({ engine, ctx, root }) => {
    const incarnation = await incarnationOf(engine, 'default');
    const before = await readGitHold(engine, 'default', incarnation, 'notes/held.md');
    expect(before).toMatchObject({ path: 'notes/held.md', code: 'invalid_frontmatter' });

    // A managed brain re-screens with --no-pull.
    expect((await retryHeld(engine, 'default', { dryRun: true })).fix?.argv).toEqual(['gbrain', 'sources', 'retry-held', 'default']);
    expect((await retryHeld(engine, 'default')).fix?.argv).toEqual(['gbrain', 'sync', '--source', 'default', '--no-pull']);

    // A held page refuses put_page through the coordinated write path with the hold named.
    await put(ctx, 'notes/held', 'Last good body.');
    writeFileSync(join(root, 'notes', 'held.md'), '---\ntitle: Broken\n  continued tweet text\n---\n\nNewer body.\n');
    const current = (await engine.readPageSnapshot('notes/held', { sourceId: 'default' }))!;
    const refused = await submitPageMutation(ctx, { operation: 'put_page', params: { slug: 'notes/held', request_id: randomUUID(), expected_revision: current.revision,
      content: '---\ntype: note\ntitle: notes/held\n---\n\nAgent edit.\n' } }).then(() => null, (e: unknown) => e as Record<string, any>);
    expect(refused).not.toBeNull();
    const suggestion = String(refused!.suggestion);
    expect(suggestion).toContain('gbrain repair frontmatter --source default');
    expect(suggestion).toContain('retrying this write refuses the same way');
    expect(refused).toMatchObject({ code: 'source_changed', detail: 'file_database_drift', message: heldFileMessage('drift', 'invalid_frontmatter', { sourceId: 'default', incarnation }) });
    expect(JSON.stringify(refused)).not.toContain('sources reconcile');

    const gmailIncarnation = await incarnationOf(engine, 'gmail-x');
    const key = connectorCheckpointKey('gmail-x', gmailIncarnation, connectorIdentity('google', gmailConfig, null));
    await engine.executeRaw(`INSERT INTO op_checkpoints(op,fingerprint,completed_keys) VALUES('managed-connector',$1,$2::text::jsonb)`,
      [key, JSON.stringify([{ state: { history_id: 'h1', item_holds: carryLegacyFailCounts(undefined, { 'thread-1': 3 }, id => id, '2026-10-01T00:00:00.000Z') } }])]);

    // The put_page above returns at publication; its Git effect finishes in the background before the writer is quiet.
    await waitFor(async () => (await engine.executeRaw("SELECT 1 FROM persistence_effects WHERE state IN ('queued','running') LIMIT 1")).length === 0,
      { timeoutMs: 15_000, label: 'put_page effects settled' });
    const dry = await admin(engine, 'writer_deactivate', { dry_run: true });
    expect(dry.blockers.map((b: { kind: string; source_id?: string }) => `${b.kind}:${b.source_id ?? ''}`)).toEqual(['connector_holds:gmail-x']);
    await expect(admin(engine, 'writer_deactivate', { admin_intent: 'writer_deactivate', expected_state: await writerAdminState(engine) }))
      .rejects.toMatchObject({ code: 'writer_not_quiesced' });

    await engine.executeRaw("DELETE FROM op_checkpoints WHERE op='managed-connector' AND fingerprint=$1", [key]);
    const done = await admin(engine, 'writer_deactivate', { admin_intent: 'writer_deactivate', expected_state: await writerAdminState(engine) });
    expect(done).toMatchObject({ mode: 'classic', deactivated: true, blockers: [] });
    expect(await readGitHold(engine, 'default', incarnation, 'notes/held.md')).toEqual(before);
    expect((await readGitHoldRetryPaths(engine, 'default', incarnation))).toEqual(['notes/held.md']);
    // Classic mode re-screens with plain sync.
    expect((await retryHeld(engine, 'default')).fix?.argv).toEqual(['gbrain', 'sync', '--source', 'default']);
  }, { setup: async ({ engine }) => {
    await engine.executeRaw('INSERT INTO sources (id, name, config) VALUES ($1, $1, $2::text::jsonb)', ['gmail-x', JSON.stringify(gmailConfig)]);
    await writeGitHold(engine, hold('default', await incarnationOf(engine, 'default'), 'notes/held.md', { run_id: randomUUID() }));
  } }), 180_000);
});

describe('#6188 fence holds on every DB-backed surface: the router and the fix by state', () => {
  let engine: PGLiteEngine;
  let home: string;
  const SECRETS = ['Sentinelclaimq92 renews yearly', 'Sentinelholderq92 Example', 'sentinelkindq92'];
  const http = { transport: 'http' as const, isCallable: () => false, preapproved: () => false, routing: {} } as never;
  const cli = cliRenderContext();
  const getPage = operations.find(op => op.name === 'get_page')!;
  const fenceAt = { reason: 'holder_unresolved' as const, fence: 'takes' as const, section: 'body' as const, rows: [3], columns: ['who'], line: 7 };
  const fenceHold = (sourceId: string, incarnation: string, path: string, pageId: number | null, extra: Partial<HoldInput['meta']> = {}): HoldInput => hold(sourceId, incarnation, path, {
    code: 'invalid_fence', page_id: pageId, message: fenceMessage(fenceAt),
    meta: { reason: 'holder_unresolved', line: 12, recovery_version: RECOVERY_VERSION, fence: fenceAt, fence_version: 1, ...extra } });
  const ctx = (sourceId: string, remote: boolean) => ({ engine, config: { engine: 'pglite', embedding_disabled: true }, logger: { info() {}, warn() {}, error() {} },
    dryRun: false, remote, sourceId, emitNotice() {}, emitResponseMeta() {} }) as unknown as OperationContext;
  const pageId = async (sourceId: string, slug: string) => {
    await engine.putPage(slug, { type: 'note', title: 'Held page', compiled_truth: 'Last good body.' }, { sourceId });
    return Number((await engine.executeRaw<{ id: number }>('SELECT id FROM pages WHERE source_id=$1 AND slug=$2', [sourceId, slug]))[0]!.id);
  };

  beforeAll(async () => {
    engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema();
    home = mkdtempSync(join(tmpdir(), 'gbrain-fence-surfaces-'));
    for (const id of ['fences-only', 'frontmatter-only', 'mixed-holds']) {
      mkdirSync(join(home, id));
      await engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', [id, join(home, id)]);
    }
    const fenceInc = await incarnationOf(engine, 'fences-only');
    await writeGitHold(engine, fenceHold('fences-only', fenceInc, 'people/held-a.md', await pageId('fences-only', 'people/held-a')));
    await writeGitHold(engine, fenceHold('fences-only', fenceInc, 'people/held-b.md', null, {
      reason: 'takes_kind_unsupported', fence: { reason: 'takes_kind_unsupported', fence: 'takes', section: 'body', rows: [2], columns: ['kind'], line: 6 } }));
    await writeGitHold(engine, hold('frontmatter-only', await incarnationOf(engine, 'frontmatter-only'), 'notes/broken.md'));
    const mixedInc = await incarnationOf(engine, 'mixed-holds');
    await writeGitHold(engine, hold('mixed-holds', mixedInc, 'notes/broken.md'));
    await writeGitHold(engine, fenceHold('mixed-holds', mixedInc, 'people/held-c.md', null));
  }, 120_000);

  afterAll(async () => { await engine.disconnect(); rmSync(home, { recursive: true, force: true }); }, 60_000);

  const expectRoute = (text: string, kind: 'fences' | 'frontmatter' | 'mixed', sourceId: string) => {
    // #6377: the source-level route for fence (and slug-conflict) holds is the content lane; a fence hold's own fix still names `repair fences --only`.
    if (kind !== 'frontmatter') expect(text).toContain(`gbrain repair content --source ${sourceId}`);
    if (kind !== 'fences') expect(text).toContain(`gbrain repair frontmatter --source ${sourceId}`);
    if (kind === 'fences') expect(text).not.toContain('repair frontmatter');
    if (kind === 'frontmatter') expect(text).not.toContain('repair content');
    for (const secret of SECRETS) expect(text).not.toContain(secret);
  };
  const SOURCES = [['fences-only', 'fences'], ['frontmatter-only', 'frontmatter'], ['mixed-holds', 'mixed']] as const;

  test('every surface names the right repair command for fence-only, frontmatter-only and mixed sources (D6)', async () => {
    for (const [sourceId, kind] of SOURCES) {
      const status = JSON.parse(await captured(() => runSources(engine, ['status', sourceId, '--json']))).sources[0].git_holds;
      for (const item of status.items) {
        if (item.code === 'invalid_fence') expect(item.fix.argv).toEqual(['gbrain', 'repair', 'fences', '--source', sourceId, '--only', item.path]);
        else expect(item.fix.argv.slice(0, 3)).toEqual(['gbrain', 'repair', 'frontmatter']);
      }
      const text = await captured(() => runSources(engine, ['status', sourceId]));
      if (kind !== 'frontmatter') expect(text).toContain(`gbrain repair fences --source ${sourceId} --only`);
      if (kind === 'fences') expect(text).not.toContain('repair frontmatter');
      expectRoute((await retryHeld(engine, sourceId, { dryRun: false })).next_action, kind, sourceId);
      const doctor = await gitHeldFilesCheck(engine, [sourceId]);
      expectRoute(doctor.message, kind, sourceId);
      expect(doctor.fix!.argv).toEqual(kind === 'fences' ? ['gbrain', 'repair', 'content', '--source', sourceId] : ['gbrain', 'repair', 'frontmatter', '--source', sourceId]);
      const banner = bannerFindingLine({ spec: WAVE_CHECKS.find(spec => spec.id === 'git_held_files')!, check: doctor, state: 'finding' });
      expectRoute(banner, kind, sourceId);
      const report = await buildHoldReport(engine, { sourceId, incarnation: await incarnationOf(engine, sourceId), runId: 'none', remote: false,
        policy: await readSyncHoldPolicy(engine), screened: 0 });
      expectRoute(`${report.holds_fix!.argv!.join(' ')} ${report.holds_fix!.why}`, kind, sourceId);
      const remote = await buildHoldReport(engine, { sourceId, incarnation: await incarnationOf(engine, sourceId), runId: 'none', remote: true,
        policy: await readSyncHoldPolicy(engine), screened: 0 });
      expect(remote.holds_fix!.actor).toBe('host_admin');
      expectRoute(remote.holds_fix!.user_message!, kind, sourceId);
      const coverage = await readHeldCoverage(engine, { sourceId });
      const notice = heldFilesNotice(coverage, false)!.fix!;
      expectRoute(`${notice.argv!.join(' ')} ${notice.why}`, kind, sourceId);
      expectRoute(heldFilesNotice(coverage, true)!.fix!.user_message!, kind, sourceId);
    }
    expect(heldFileDiagnostic(heldFileMessage('drift', 'invalid_fence'), 'fences-only')!.suggestion).toContain('gbrain repair fences --source fences-only');
  });

  test('a fence hold\'s rendered next follows its state on CLI and HTTP, with the maintenance run inactive and active (D17, E35)', async () => {
    const items = async () => {
      const status = JSON.parse(await captured(() => runSources(engine, ['status', 'fences-only', '--json']))).sources[0].git_holds.items as Array<{ path: string; fix: Action; fence: Record<string, unknown> }>;
      return Object.fromEntries(status.map(item => [item.path, item]));
    };
    const inactive = await items();
    // Inactive: the auto-retry hold is the preview, then the apply; the manual one is the preview, then the sync. Never "no action needed".
    expect(renderAction(inactive['people/held-a.md']!.fix, cli)).toMatchObject({ next: 'run', then: { argv: ['gbrain', 'repair', 'fences', '--source', 'fences-only', '--only', 'people/held-a.md', '--apply'] } });
    expect(inactive['people/held-a.md']!.fix.why).not.toContain('No action is needed');
    expect(inactive['people/held-a.md']!.fence).toMatchObject({ tier: 'resolver', auto_retry: false, classes: ['holder_unresolved'] });
    expect(renderAction(inactive['people/held-b.md']!.fix, cli)).toMatchObject({ next: 'run', then: { argv: ['gbrain', 'sync', '--source', 'fences-only', '--no-pull'] } });
    for (const item of Object.values(inactive)) expect(renderAction(item.fix, http).next).toBe('tell_user_to_run');

    // A completed brain-wide maintenance job is the evidence that the maintenance run is active.
    await engine.executeRaw(`INSERT INTO minion_jobs (submission_authority, name, status, data, queue, priority, created_at, finished_at)
      VALUES ('{"version":1,"kind":"application"}'::jsonb, 'autopilot-global-maintenance', 'completed', '{}'::jsonb, 'default', 0, now(), now())`);
    try {
      const active = await items();
      expect(active['people/held-a.md']!.fix.why).toContain('No action is needed: the next maintenance run repairs it automatically');
      expect(active['people/held-a.md']!.fix.then).toBeUndefined();
      expect(active['people/held-a.md']!.fence).toMatchObject({ auto_retry: true });
      expect(renderAction(active['people/held-a.md']!.fix, cli).next).toBe('run');
      expect(active['people/held-b.md']!.fix.why).toContain('gbrain will not guess this repair');
      // Model repair off: a Tier 3 hold waits on a paid setting, which the CLI renders as ask_user.
      await engine.setConfig('fences.repair.llm', 'false');
      await writeGitHold(engine, fenceHold('fences-only', await incarnationOf(engine, 'fences-only'), 'people/held-d.md', null, {
        reason: 'short_row', fence: { reason: 'short_row', fence: 'facts', section: 'body', rows: [4], columns: [], line: 9 } }));
      const paid = (await items())['people/held-d.md']!;
      expect(renderAction(paid.fix, cli)).toMatchObject({ next: 'ask_user', consent: ['paid'], argv: ['gbrain', 'config', 'set', 'fences.repair.llm', 'true'] });
      expect(renderAction(paid.fix, http).next).toBe('tell_user_to_run');
      const text = await captured(() => runSources(engine, ['status', 'fences-only']));
      expect(text).toContain('No action needed: the next maintenance run repairs it.');
      expect(text).toContain('Ask the user first, then: gbrain config set fences.repair.llm true');
    } finally {
      await engine.executeRaw("DELETE FROM minion_jobs WHERE name='autopilot-global-maintenance'");
      await engine.unsetConfig('fences.repair.llm');
      await clearHold('fences-only', 'people/held-d.md');
    }
  });

  test('a remote status read of a held fence returns the owner handoff, saying whether it clears by itself, with no path (Codex CEO #7)', async () => {
    const local = await getPage.handler(ctx('fences-only', false), { slug: 'people/held-a' }) as Record<string, any>;
    expect(local.file_held).toMatchObject({ code: 'invalid_fence', path: 'people/held-a.md', line: 12,
      fence: { fence: 'takes', section: 'body', rows: [3], columns: ['who'], classes: ['holder_unresolved'] },
      fix: { argv: ['gbrain', 'repair', 'fences', '--source', 'fences-only', '--only', 'people/held-a.md'] } });
    const remote = await getPage.handler(ctx('fences-only', true), { slug: 'people/held-a' }) as Record<string, any>;
    expect(remote.file_held.path).toBeUndefined();
    expect(remote.file_held.fence.rows).toEqual([]);
    expect(remote.file_held.fix).toMatchObject({ actor: 'host_admin', argv: ['gbrain', 'repair', 'fences', '--source', 'fences-only'] });
    expect(renderAction(remote.file_held.fix, http).next).toBe('tell_user_to_run');
    expect(remote.file_held.fix.user_message).toContain('It does not clear by itself because no maintenance run is active on the brain host');
    await engine.setConfig('autopilot.last_global_at', new Date().toISOString());
    try {
      const active = await getPage.handler(ctx('fences-only', true), { slug: 'people/held-a' }) as Record<string, any>;
      expect(active.file_held.fix.user_message).toContain('It clears by itself');
      expect(active.file_held.fence.auto_retry).toBe(true);
    } finally { await engine.unsetConfig('autopilot.last_global_at'); }
    const text = JSON.stringify(remote.file_held);
    for (const hidden of ['people/held-a.md', home, ...SECRETS]) expect(text).not.toContain(hidden);
  });

  async function clearHold(sourceId: string, path: string) {
    const { clearGitHold } = await import('../src/core/persistence/sync-holds.ts');
    await clearGitHold(engine, { sourceId, incarnation: await incarnationOf(engine, sourceId), path, observedAt: '2999-01-01T00:00:00.000Z' });
  }
});