Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
20.9 KB
Raw Blame
/**
 * #6188 (D6, D16, D17, E35, Codex CEO #7, Codex DX #6): what a fence hold
 * tells an agent on every surface.
 *
 * Protects: one hold-repair router: a fence-only source names
 * `gbrain repair fences --source <id>` and never frontmatter, a
 * frontmatter-only source never names the fence repair, a mixed source names
 * both; a single fence hold's fix is that file's preview
 * (`--only <path>`). The fix follows the hold's state: auto-repair pending
 * with an active maintenance run says no action is needed (read-only
 * preview), an inactive run names the preview then the apply, a manual-only
 * reason or gate rejection names the exact edit, a paid wait names the exact
 * config or pricing command with consent `paid` (renders ask_user), the owner
 * state names the owner host; remote callers get `tell_user_to_run` with a
 * user_message saying whether it clears by itself. Hold items carry the D16
 * structured location and holdLine renders it. No claim, holder or kind text
 * reaches any surface.
 * Fails when: a surface keeps the old "edit the fence then sync" next step,
 * routes a fence hold to frontmatter repair, says "no action needed" with no
 * active maintenance run, renders a paid step as `run`, or copies a cell value.
 * Why new: PR1 pinned the edit-and-sync router; PR4 replaces that contract
 * with the repair command and state-dependent fixes.
 * Seams: none (pure functions; the maintenance state is passed in).
 */
import { describe, expect, test } from 'bun:test';
import { gitHoldDocs, gitHoldFix, gitHoldItem, holdRepairSteps, holdRescreenDue, type GitHoldRecord } from '../src/core/persistence/sync-holds.ts';
import { coverageRoute, fileHeldField, heldFilesNotice, hostOperatorFix, recordRoute } from '../src/core/persistence/held-reads.ts';
import { heldFileDiagnostic, heldFileMessage, writeFailureDiagnostic } from '../src/core/persistence/verb-errors.ts';
import { holdLine } from '../src/commands/sync-diagnostics.ts';
import { deriveNext, renderAction, type Action } from '../src/core/agent-output.ts';
import { fenceMessage } from '../src/core/fence-repair/reasons.ts';
import { FENCE_VERSION } from '../src/core/fence-repair/refusal.ts';
import { QUOTE_SCREEN_VERSION } from '../src/core/fence-repair/quote-markers.ts';
import { fenceFileLine, fenceHoldStatus, type FenceAutoRepair } from '../src/core/fence-repair/hold-fix.ts';
import { parseMarkdown, RECOVERY_VERSION } from '../src/core/markdown.ts';

const location = { reason: 'holder_unresolved', fence: 'takes', section: 'body', rows: [3], columns: ['who'], line: 7 } as const;
const fenceHold = (extra: Partial<GitHoldRecord> = {}): GitHoldRecord => ({
  version: 1, source_id: 'notes-example', incarnation: 'inc', path: 'people/alice-example.md', source_path: 'people/alice-example.md', slug: 'people/alice-example', page_id: 12,
  code: 'invalid_fence', message: fenceMessage({ ...location, rows: [...location.rows], columns: [...location.columns] }), upstream_version: 'sha', observed_at: '2026-10-01T00:00:00.000Z',
  held_at: '2026-10-01T00:00:00.000Z', updated_at: '2026-10-01T00:00:00.000Z', run_id: 'run', mode: 'managed',
  meta: { reason: 'holder_unresolved', line: 12, recovery_version: RECOVERY_VERSION, fence: { ...location, rows: [...location.rows], columns: [...location.columns] }, fence_version: FENCE_VERSION, quote_version: QUOTE_SCREEN_VERSION },
  ...extra,
});
const withMeta = (meta: Partial<GitHoldRecord['meta']>) => fenceHold({ meta: { ...fenceHold().meta, ...meta } });
const manualHold = () => withMeta({ reason: 'takes_kind_unsupported', fence: { reason: 'takes_kind_unsupported', fence: 'takes', section: 'body', rows: [2], columns: ['kind'], line: 6 } });
const tier3Hold = () => withMeta({ reason: 'short_row', fence: { reason: 'short_row', fence: 'facts', section: 'body', rows: [4], columns: [], line: 9 } });
const frontmatterHold = (): GitHoldRecord => ({ ...fenceHold(), path: 'notes/broken.md', code: 'invalid_frontmatter',
  message: 'Invalid YAML frontmatter: key "title" at line 2 continues on unquoted lines.', meta: { reason: 'needs_interpretation', key: 'title', line: 2, recovery_version: RECOVERY_VERSION } });
const repaired = (reason: string, next: string | null, extra: Record<string, unknown> = {}) =>
  ({ reason, tier: 'llm', at: '2026-10-05T00:00:00.000Z', next_attempt_after: next, ...extra }) as GitHoldRecord['meta']['fence_repair'];

const ACTIVE: FenceAutoRepair = { enabled: true, llm: true, last_maintenance_at: '2026-10-06T00:00:00.000Z', active: true };
const INACTIVE: FenceAutoRepair = { enabled: true, llm: true, last_maintenance_at: null, active: false };
const PAUSED: FenceAutoRepair = { enabled: false, llm: true, last_maintenance_at: '2026-10-06T00:00:00.000Z', active: false };
const LLM_OFF: FenceAutoRepair = { ...ACTIVE, llm: false };

const cli = { transport: 'cli' as const, isCallable: () => false, preapproved: () => false, routing: {} } as never;
const http = { transport: 'http' as const, isCallable: () => false, preapproved: () => false, routing: {} } as never;
const next = (fix: Action, ctx: never) => renderAction(fix, ctx).next;
const preview = (path?: string) => ['gbrain', 'repair', 'fences', '--source', 'notes-example', ...(path ? ['--only', path] : [])];
// #6377: the source-level route names the content-repair lane; one hold's own fix stays that file's fence preview.
const lane = ['gbrain', 'repair', 'content', '--source', 'notes-example'];

describe('one fence hold: the fix by state (D17, E35)', () => {
  test('auto-repair pending with an active maintenance run: no action needed, the read-only preview of that file', () => {
    const fix = gitHoldFix(fenceHold({ meta: { ...fenceHold().meta, fence_repair: repaired('llm_unavailable', '2026-10-06T09:00:00.000Z') } }), ACTIVE);
    expect(fix.argv).toEqual(preview('people/alice-example.md'));
    expect(fix.then).toBeUndefined();
    expect(fix.why).toContain('No action is needed: the next maintenance run repairs it automatically (next attempt after 2026-10-06T09:00:00.000Z)');
    expect([next(fix, cli), next(fix, http)]).toEqual(['run', 'tell_user_to_run']);
  });

  test('maintenance inactive or paused: the preview, then the apply; never "no action needed"', () => {
    for (const auto of [INACTIVE, PAUSED, undefined]) {
      const fix = gitHoldFix(fenceHold(), auto);
      expect(fix.argv).toEqual(preview('people/alice-example.md'));
      expect(fix.then?.argv).toEqual([...preview('people/alice-example.md'), '--apply']);
      expect(fix.why).toContain('--expect <hash>');
      expect(fix.why).not.toContain('No action is needed');
      expect(next(fix, cli)).toBe('run');
    }
    expect(gitHoldFix(fenceHold(), INACTIVE).why).toContain('No maintenance run is active');
    expect(gitHoldFix(fenceHold(), PAUSED).why).toContain('fences.repair.enabled false');
  });

  test('manual-only reasons, gate rejections and model failures name the exact edit through the preview, then the sync', () => {
    const manual = gitHoldFix(manualHold(), ACTIVE);
    expect(manual.argv).toEqual(preview('people/alice-example.md'));
    expect(manual.why).toContain('gbrain will not guess this repair');
    expect(manual.why).toContain('Column `kind` of row(s) 2 in the takes fence');
    expect(manual.then?.argv).toEqual(['gbrain', 'sync', '--source', 'notes-example', '--no-pull']);
    expect(next(manual, cli)).toBe('run');
    const gate = gitHoldFix(withMeta({ fence_repair: repaired('cell_changed', null, { gate: 'f', rows: [3] }) }), ACTIVE);
    expect(fenceHoldStatus(withMeta({ fence_repair: repaired('cell_changed', null, { gate: 'f', rows: [3] }) }).meta, ACTIVE)).toMatchObject({ state: 'manual', reason: 'cell_changed' });
    expect(gate.why).toContain('The proposed repair failed gate f');
    expect(fenceHoldStatus(withMeta({ fence_repair: repaired('llm_malformed', null) }).meta, ACTIVE).state).toBe('manual');
  });

  test('budget, model switch and pricing waits: the exact command with consent paid, which renders ask_user', () => {
    const cases: Array<[string, Partial<GitHoldRecord['meta']>, FenceAutoRepair, string[]]> = [
      ['budget_exhausted', { fence_repair: repaired('budget_exhausted', '2026-10-07T00:00:00.000Z') }, ACTIVE, ['gbrain', 'config', 'set', 'fences.repair.max_usd_per_day', '<usd>']],
      ['llm_disabled', {}, LLM_OFF, ['gbrain', 'config', 'set', 'fences.repair.llm', 'true']],
      ['no_pricing', { fence_repair: repaired('no_pricing', null) }, ACTIVE, ['gbrain', 'pricing', 'set', '<model>', '--input', '<usd>', '--output', '<usd>']],
    ];
    for (const [reason, meta, auto, argv] of cases) {
      const record = reason === 'llm_disabled' ? tier3Hold() : withMeta(meta);
      const fix = gitHoldFix(record, auto);
      expect([reason, fenceHoldStatus(record.meta, auto).state]).toEqual([reason, 'paid']);
      expect(fix).toMatchObject({ argv, consent: ['paid'], actor: 'agent', preview_argv: reason === 'llm_disabled' ? preview('people/alice-example.md') : preview('people/alice-example.md') });
      expect(next(fix, cli)).toBe('ask_user');
      expect(fix.why).toContain("the user's call");
      expect(fix.user_message).toContain(argv.join(' '));
    }
    // With the model on, the same Tier 3 hold is ordinary auto-repair work.
    expect(fenceHoldStatus(tier3Hold().meta, ACTIVE).state).toBe('auto');
  });

  test('owner_unavailable names the owner-host command for the host operator', () => {
    const fix = gitHoldFix(withMeta({ fence_repair: repaired('owner_unavailable', '2026-10-06T09:00:00.000Z') }), ACTIVE);
    expect(fix).toMatchObject({ argv: preview('people/alice-example.md'), actor: 'host_admin' });
    expect(fix.why).toContain('owner host');
    expect(next(fix, cli)).toBe('tell_user_to_run');
  });

  test('a prepare-time hold reads its receipt reason; a stored-row collision is a manual edit', () => {
    const hold = withMeta({ reason: 'prepare_time', fence: { reason: 'stored_row_collision', fence: 'takes', section: 'body', rows: [2], columns: [], line: null } });
    expect(fenceHoldStatus(hold.meta, ACTIVE).state).toBe('manual');
    expect(gitHoldFix(hold, ACTIVE).why).toContain('was refused against the stored page (stored_row_collision)');
  });
});

describe('structured location (D16)', () => {
  test('items carry fence, section, rows, columns, classes, tier, auto_retry, next_attempt_after and the file line; holdLine renders it', () => {
    const record = withMeta({ fence_repair: repaired('llm_unavailable', '2026-10-06T09:00:00.000Z', { tier: 'resolver' }) });
    const item = gitHoldItem(record, ACTIVE);
    expect(item).toMatchObject({ code: 'invalid_fence', reason: 'holder_unresolved', line: 12, docs: 'docs/guides/write-refusals.md#fence-holder_unresolved',
      fence: { reason: 'holder_unresolved', fence: 'takes', section: 'body', rows: [3], columns: ['who'], line: 7, classes: ['holder_unresolved'], tier: 'resolver',
        auto_retry: true, next_attempt_after: '2026-10-06T09:00:00.000Z' } });
    expect(holdLine(item, 'Held')).toBe('  Held people/alice-example.md: invalid_fence (holder_unresolved) in the takes fence (body), row 3, column who, at line 12; '
      + 'its page keeps its last good revision and is read-only for put_page until the file is repaired. No action needed: the next maintenance run repairs it. '
      + 'Preview: gbrain repair fences --source notes-example --only people/alice-example.md (docs/guides/write-refusals.md#fence-holder_unresolved)');
    expect(holdLine(gitHoldItem(fenceHold(), INACTIVE), 'Held')).toContain('Next: gbrain repair fences --source notes-example --only people/alice-example.md, '
      + 'then gbrain repair fences --source notes-example --only people/alice-example.md --apply');
    expect(holdLine(gitHoldItem(tier3Hold(), LLM_OFF), 'Held')).toContain('Ask the user first, then: gbrain config set fences.repair.llm true');
    expect(gitHoldItem(fenceHold(), INACTIVE).fence).toMatchObject({ auto_retry: false, next_attempt_after: null });
    expect(gitHoldDocs('invalid_fence', 'prepare_time')).toBe('docs/guides/write-refusals.md#fence-prepare_time');
    expect(gitHoldDocs('invalid_frontmatter', 'yaml_parse')).toBe('docs/guides/write-refusals.md#invalid_frontmatter-yaml_parse');
  });

  test('fenceFileLine adds the section start to the section line, for the body and the timeline', () => {
    const content = '---\ntitle: Example\n---\n\n# Example\n\nIntro.\n\n<!--- gbrain:takes:begin -->\n| # | claim |\n<!--- gbrain:takes:end -->\n\n<!-- timeline -->\n\n- 2026-01-01: an event\n';
    const page = parseMarkdown(content, 'people/example.md');
    const lines = content.split('\n');
    const bodyLine = page.compiled_truth.split('\n').indexOf('| # | claim |') + 1;
    expect(lines[fenceFileLine(content, page, { section: 'body', line: bodyLine })! - 1]).toBe('| # | claim |');
    const timelineLine = page.timeline.split('\n').indexOf('- 2026-01-01: an event') + 1;
    expect(lines[fenceFileLine(content, page, { section: 'timeline', line: timelineLine })! - 1]).toBe('- 2026-01-01: an event');
    expect(fenceFileLine(content, page, { section: 'body', line: null })).toBeNull();
  });

  test('a fence hold an older fence screen wrote is re-screened; a current one only when retried or its bytes change', () => {
    expect(holdRescreenDue(fenceHold(), false)).toBe(false);
    expect(holdRescreenDue(fenceHold(), true)).toBe(true);
    expect(holdRescreenDue(withMeta({ fence_version: FENCE_VERSION - 1 }), false)).toBe(true);
    expect(holdRescreenDue(withMeta({ fence_version: undefined }), false)).toBe(true);
    expect(holdRescreenDue(withMeta({ quote_version: undefined }), false)).toBe(true);
    expect(holdRescreenDue({ ...frontmatterHold(), code: 'frontmatter_slug_conflict' }, false)).toBe(true);
  });
});

describe('source-level routing on every surface (D6)', () => {
  test('fence-only, frontmatter-only and mixed sources name the right repair commands', () => {
    const fences = holdRepairSteps('notes-example', { fences: 2, others: 0 });
    expect(fences.argv).toEqual(lane);
    expect(fences.commands).toEqual(['gbrain repair content --source notes-example']);
    expect(fences.text).not.toContain('frontmatter');
    const frontmatter = holdRepairSteps('notes-example', { fences: 0, others: 2 });
    expect(frontmatter.argv).toEqual(['gbrain', 'repair', 'frontmatter', '--source', 'notes-example']);
    expect(frontmatter.text).not.toContain('fence');
    const mixed = holdRepairSteps('notes-example', { fences: 1, others: 1 });
    expect(mixed.commands).toEqual(['gbrain repair frontmatter --source notes-example', 'gbrain repair content --source notes-example']);
    // #6377: slug-conflict holds take the same lane route as fence holds.
    const slugs = holdRepairSteps('notes-example', { fences: 0, others: 0, slug_conflicts: 1 });
    expect(slugs.argv).toEqual(lane);
    expect(slugs.text).not.toContain('frontmatter');
    expect(holdRepairSteps('notes-example', { fences: 1, others: 0 }, ACTIVE).text).toContain('the next maintenance run repairs the fence and slug-conflict holds it can by itself');
    expect(holdRepairSteps('notes-example', { fences: 1, others: 0 }, INACTIVE).text).toContain('nothing repairs the fence and slug-conflict holds by itself (no maintenance run is active)');
    expect(holdRepairSteps('notes-example', { fences: 1, others: 0 }, INACTIVE).text).toContain('then run the apply command it prints');
  });

  test('the held_files notice routes each kind; a remote caller gets the owner handoff with no path', () => {
    const fenceOnly = [{ source_id: 'notes-example', missing: 0, stale: 2, fences: 2 }];
    expect(coverageRoute(fenceOnly[0]!)).toEqual({ fences: 2, others: 0 });
    const local = heldFilesNotice(fenceOnly, false)!;
    expect(local.fix!.argv).toEqual(lane);
    expect(local.fix!.why).not.toContain('frontmatter');
    const remote = heldFilesNotice(fenceOnly, true)!;
    expect(remote.fix).toMatchObject({ actor: 'host_admin', argv: lane });
    expect(remote.fix!.user_message).toContain("'gbrain repair content --source notes-example'");
    expect(remote.fix!.user_message).not.toContain('frontmatter');
    expect(deriveNext(remote.fix!, http)).toBe('tell_user_to_run');
    expect(heldFilesNotice([{ source_id: 'notes-example', missing: 1, stale: 0 }], false)!.fix!.argv).toEqual(['gbrain', 'repair', 'frontmatter', '--source', 'notes-example']);
    const mixed = hostOperatorFix([{ source_id: 'notes-example', route: { fences: 1, others: 1 } }], 'Held.');
    expect(mixed.user_message).toContain("'gbrain repair frontmatter --source notes-example'");
    expect(mixed.user_message).toContain("'gbrain repair content --source notes-example'");
    const frontmatter = hostOperatorFix([{ source_id: 'notes-example' }], 'Held.');
    expect(frontmatter.user_message).toContain("'gbrain repair frontmatter --source notes-example' on the brain host");
    expect(frontmatter.user_message).not.toContain('repair content');
    expect(recordRoute(fenceHold())).toEqual({ fences: 1, others: 0 });
    expect(recordRoute({ code: 'frontmatter_slug_conflict' })).toEqual({ fences: 0, others: 0, slug_conflicts: 1 });
    expect(hostOperatorFix([{ source_id: 'notes-example', route: recordRoute({ code: 'frontmatter_slug_conflict' }) }], 'Held.').user_message).toContain("'gbrain repair content --source notes-example'");
  });

  test('get_page file_held: the local fix is that file\'s preview; the remote read gets tell_user_to_run saying whether it clears by itself (Codex CEO #7)', () => {
    expect(fileHeldField({ record: fenceHold(), revision: 'r1', fenceAuto: ACTIVE }, false)).toMatchObject({ path: 'people/alice-example.md',
      fence: { rows: [3], auto_retry: true }, fix: { argv: preview('people/alice-example.md') } });
    const auto = fileHeldField({ record: fenceHold(), revision: 'r1', fenceAuto: ACTIVE }, true);
    expect(auto.path).toBeUndefined();
    expect(auto.fence).toMatchObject({ rows: [], fence: 'takes', section: 'body' });
    expect(auto.fix).toMatchObject({ actor: 'host_admin', argv: preview() });
    expect(next(auto.fix, http)).toBe('tell_user_to_run');
    expect(auto.fix.user_message).toContain('It clears by itself');
    const inactive = fileHeldField({ record: fenceHold(), revision: 'r1', fenceAuto: INACTIVE }, true);
    expect(inactive.fix.user_message).toContain('It does not clear by itself because no maintenance run is active on the brain host');
    const manual = fileHeldField({ record: manualHold(), revision: 'r1', fenceAuto: ACTIVE }, true);
    expect(manual.fix.user_message).toContain('needs an edit gbrain will not guess');
    const paid = fileHeldField({ record: tier3Hold(), revision: 'r1', fenceAuto: LLM_OFF }, true);
    expect(paid.fix).toMatchObject({ argv: ['gbrain', 'config', 'set', 'fences.repair.llm', 'true'], consent: ['paid'], actor: 'host_admin' });
    expect(next(paid.fix, http)).toBe('tell_user_to_run');
    expect(paid.fix.user_message).toContain('your call');
    for (const field of [auto, inactive, manual, paid]) expect(JSON.stringify(field)).not.toContain('alice-example.md');
  });

  test('write refusals over a held fence file name the fence repair, never frontmatter; a blocked fence receipt names both the edit and the preview', () => {
    const held = heldFileDiagnostic(heldFileMessage('drift', 'invalid_fence'), 'notes-example')!;
    expect(held.suggestion).toContain('gbrain repair fences --source notes-example');
    expect(held.suggestion).not.toContain('repair frontmatter');
    expect(heldFileDiagnostic(heldFileMessage('drift', 'invalid_frontmatter'), 'notes-example')!.suggestion).toContain('gbrain repair frontmatter --source notes-example');
    expect(heldFileDiagnostic(heldFileMessage('drift', 'invalid_frontmatter'), 'notes-example')!.suggestion).not.toContain('repair fences');
    const blocked = writeFailureDiagnostic('invalid_params', fenceHold().message);
    expect(blocked).toMatchObject({ reason: 'invalid_fence', message: fenceHold().message });
    expect(blocked.suggestion).toContain('the takes fence (body), row 3');
    expect(blocked.suggestion).toContain('gbrain repair fences');
    expect(writeFailureDiagnostic('invalid_params', 'The value is invalid.').reason).toBe('invalid_params');
  });
});

describe('location-only privacy (sentinel)', () => {
  test('no claim, holder or kind text reaches a hold item, fix, line, file_held or relay in any state', () => {
    const SECRETS = ['Sentinelclaimq81 renews', 'Sentinelholderq81 Example', 'sentinelkindq81'];
    const records = [fenceHold(), manualHold(), tier3Hold(), withMeta({ fence_repair: repaired('cell_changed', null, { gate: 'f', rows: [3] }) }),
      withMeta({ fence_repair: repaired('budget_exhausted', '2026-10-07T00:00:00.000Z') }), withMeta({ fence_repair: repaired('owner_unavailable', null) })];
    for (const record of records) {
      for (const auto of [ACTIVE, INACTIVE, LLM_OFF, undefined]) {
        const item = gitHoldItem(record, auto);
        const text = JSON.stringify([item, holdLine(item, 'Held'), renderAction(item.fix, cli), renderAction(item.fix, http),
          fileHeldField({ record, revision: 'r1', fenceAuto: auto }, true), fileHeldField({ record, revision: 'r1', fenceAuto: auto }, false)]);
        for (const secret of SECRETS) expect(text).not.toContain(secret);
        expect(text).not.toContain('repair frontmatter');
      }
    }
  });
});