Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain trust claim-sources` (#5575, legacy content) and the asks around it.
*
* Protects: the owner claims a source only by typing its id on a terminal
* (--yes never counts; without a terminal the command refuses with an
* tell_user_to_run fix and changes nothing); a claim sets the per-source default
* operator_curated and lifts the source's legacy unknown rows through the
* backfill, never above operator_curated, while rows with a lowering signal
* (mcp:* and capture stamps, transcript imports, clipped pages, connector
* stamps, backstop facts, the lower-only trust_tier marker) keep their lower
* tier; connector sources cannot be claimed; an interrupted lift resumes, and
* until it does the scan refuses and explain shows the rows as owner tier;
* `--dry-run` writes nothing; `sources set-trust` to a lower tier ends a
* claim. Doctor `trust_sources_unclaimed` warns with tell_user_to_run while unclaimed
* legacy rows exist and never on a fresh brain; doctor `trust_scan` leaves the
* scan to the user; post-upgrade and the behavior-change notice name the claim.
* None of these fixes carries consent effects (nothing is destructive).
* Also pins the SQL frontmatter caps to `frontmatterTrustCaps`.
*/
import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { PassThrough } from 'node:stream';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import { renderAction, type Action } from '../src/core/agent-output.ts';
import { __setConfirmationIoForTests } from '../src/core/trust/confirm.ts';
import { frontmatterTrustCaps, frontmatterTrustCapsSql } from '../src/core/trust/channel.ts';
import { claimSourcesFix, hasUnclaimedLegacySources, listClaimSources, liftClaimedSources, recordSourceClaims, readUnclaimedLegacySources } from '../src/core/trust/claim.ts';
import { TRUST_CLAIM_LIFTED_AT_KEY, TRUST_CLAIMED_AT_KEY } from '../src/core/trust/claim-state.ts';
import { trustClaimUpgradeNotice } from '../src/core/trust/claim-notice.ts';
import { runTrustBackfill } from '../src/core/trust/backfill.ts';
import { explainTrust } from '../src/core/trust/review.ts';
import { TRUST_TIER_RANK } from '../src/core/trust/tier.ts';
import { runTrustScan } from '../src/core/eligibility/scan.ts';
import { runTrustClaimSources } from '../src/commands/trust-claim.ts';
import { _resetCliExitVerdictForTests } from '../src/core/cli-force-exit.ts';
import { runSetTrust } from '../src/commands/sources-trust.ts';
import { trustSourcesUnclaimedEntry } from '../src/commands/doctor/checks/trust-sources-unclaimed.ts';
import { trustScanEntry } from '../src/commands/doctor/checks/trust-scan.ts';
import { withTrustClaimAsk } from '../src/core/behavior-change-notice.ts';
import { FACTS_BACKSTOP_SOURCES } from '../src/core/facts/capture-sources.ts';
import { WRITE_GATE_SCAN_BASELINE_KEY } from '../src/core/write-gate-schema.ts';
import type { DoctorContext } from '../src/commands/doctor/context.ts';
import type { Check } from '../src/commands/doctor.ts';
let engine: BrainEngine;
/** A brain nothing seeds: fresh-install expectations. */
let fresh: BrainEngine;
beforeAll(async () => {
const pg = new PGLiteEngine(); await pg.connect({}); await pg.initSchema();
engine = pg;
// Every row the tests seed stands in for content from before trust tiers: the baseline the trust migrations record covers it.
await engine.executeRaw('UPDATE config SET value = $2 WHERE key = $1', [WRITE_GATE_SCAN_BASELINE_KEY,
JSON.stringify({ detector_version: 0, until: { pages: 1e12, facts: 1e12, takes: 1e12, timeline_entries: 1e12 } })]);
const empty = new PGLiteEngine(); await empty.connect({}); await empty.initSchema();
fresh = empty;
}, 120_000);
afterAll(async () => { await engine.disconnect(); await fresh.disconnect(); });
afterEach(() => { __setConfirmationIoForTests(null); process.exitCode = 0; _resetCliExitVerdictForTests(); });
const cli = { transport: 'cli' as const, isCallable: () => false, preapproved: () => true };
const render = (fix: unknown) => renderAction(fix as Action, cli);
const doctor = async (entry: { run: (ctx: DoctorContext) => Promise<unknown> }, db = engine) => (await entry.run({ engine: db } as unknown as DoctorContext) as Check[])[0]!;
function tty(answer: string) {
const input = new PassThrough();
const output = new PassThrough();
let prompt = '';
output.on('data', chunk => { prompt += String(chunk); });
__setConfirmationIoForTests({ probe: { stdinIsTTY: true, stdoutIsTTY: true, env: { GBRAIN_INTERACTIVE: '1' } }, input, output, timeoutMs: 2000 });
input.write(`${answer}\n`);
return { prompt: () => prompt };
}
const nonTty = () => __setConfirmationIoForTests({ probe: { stdinIsTTY: false, stdoutIsTTY: false, env: {} } });
/** Runs the CLI, returning what it printed on stdout (console.log) and stderr. */
async function runCli(args: string[]): Promise<{ out: string; err: string }> {
const out: string[] = [];
const err: string[] = [];
const log = console.log;
const write = process.stderr.write.bind(process.stderr);
console.log = (...a: unknown[]) => { out.push(a.join(' ')); };
process.stderr.write = ((chunk: string | Uint8Array) => { err.push(String(chunk)); return true; }) as typeof process.stderr.write;
try { await runTrustClaimSources(engine, args); } finally { console.log = log; process.stderr.write = write; }
return { out: out.join('\n'), err: err.join('') };
}
/** One owner source with a row per signal class (all `unknown`), plus a github connector source. */
async function seed() {
const tag = randomUUID().slice(0, 8);
const src = `own-${tag}`, gh = `gh-${tag}`;
await engine.executeRaw(`INSERT INTO sources(id,name,local_path) VALUES($1,$1,'/home/alice-example/notes')`, [src]);
await engine.executeRaw(`INSERT INTO sources(id,name,config) VALUES($1,$1,'{"kind":"github"}'::jsonb)`, [gh]);
const pages: Record<string, number> = {};
const page = async (key: string, source: string, sourceKind: string | null, frontmatter: Record<string, unknown> = {}) => {
const [row] = await engine.executeRaw<{ id: number }>(`INSERT INTO pages(slug,type,title,compiled_truth,source_id,source_kind,frontmatter)
VALUES($1,'note','T','Plain notes about acme-example.',$2,$3,$4::text::jsonb) RETURNING id`, [`p/${key}`, source, sourceKind, JSON.stringify(frontmatter)]);
pages[key] = Number(row!.id);
};
await page('plain', src, null);
await page('mcp', src, 'mcp:put_page');
await page('capture', src, null, { captured_via: 'capture' });
await page('own-transcript', src, null, { transcript_import: { harness: 'codex' } });
await page('other-transcript', src, null, { transcript_import: { harness: 'zoom' } });
await page('clipped', src, null, { source_url: 'https://example.com/a', clipped_at: '2026-01-01' });
await page('marker', src, null, { trust_tier: 'agent_written' });
await page('confirmed-marker', src, null, { trust_tier: 'user_confirmed' });
await page('connector-stamp', src, null, { ingested_via: 'connector:gmail' });
await page('atom', src, null, { type: 'atom', extracted_by: 'extract_atoms-v0.41.2.1', source_slug: 'p/plain' });
await page('gh-plain', gh, null);
const fact = async (source: string, fenced: string | null) => {
const [row] = await engine.executeRaw<{ id: number }>(`INSERT INTO facts(source_id,entity_slug,fact,kind,source,source_markdown_slug,row_num)
VALUES($1,'e','claim','fact',$2,$3,$4) RETURNING id`, [src, source, fenced, fenced ? 1 : null]);
return Number(row!.id);
};
const facts = { plain: await fact('manual', null), backstop: await fact(FACTS_BACKSTOP_SOURCES[0]!, null), onPlain: await fact('manual', 'p/plain'), onMcp: await fact('manual', 'p/mcp') };
const [take] = await engine.executeRaw<{ id: number }>(`INSERT INTO takes(page_id,row_num,claim,kind,holder,weight) VALUES($1,1,'A take','take','brain',0.5) RETURNING id`, [pages.plain]);
const [entry] = await engine.executeRaw<{ id: number }>(`INSERT INTO timeline_entries(page_id,date,summary) VALUES($1,'2026-01-01','Clipped event') RETURNING id`, [pages.clipped]);
return { src, gh, pages, facts, take: Number(take!.id), entry: Number(entry!.id) };
}
const tierOf = async (table: string, id: number) => (await engine.executeRaw<{ t: string }>(`SELECT trust_tier AS t FROM ${table} WHERE id=$1`, [id]))[0]!.t;
const configOf = async (id: string) => {
const [row] = await engine.executeRaw<{ config: unknown }>('SELECT config FROM sources WHERE id=$1', [id]);
return (typeof row!.config === 'string' ? JSON.parse(row!.config) : row!.config) as Record<string, unknown>;
};
const snapshot = async (src: string) => JSON.stringify({
pages: await engine.executeRaw(`SELECT id, trust_tier, write_origin FROM pages WHERE source_id=$1 ORDER BY id`, [src]),
facts: await engine.executeRaw(`SELECT id, trust_tier FROM facts WHERE source_id=$1 ORDER BY id`, [src]),
config: await configOf(src),
checkpoints: await engine.executeRaw(`SELECT op, fingerprint FROM op_checkpoints ORDER BY op, fingerprint`),
});
describe('trust claim-sources', () => {
test('the SQL frontmatter caps match frontmatterTrustCaps', async () => {
const samples: Array<Record<string, unknown>> = [
{}, { trust_tier: 'agent_written' }, { trust_tier: 'user_confirmed' }, { trust_tier: 'bogus' }, { trust_tier: 5 },
{ source_kind: 'webhook' }, { source_kind: 'mcp:remember' }, { ingested_via: 'capture-cli' }, { captured_via: ' connector:gmail ' }, { source_kind: 'github' },
{ source_kind: 'sync' }, { transcript_import: { harness: 'Claude-Code' } }, { transcript_import: { harness: 'zoom' } }, { transcript_import: [] },
{ transcript_import: 'yes' }, { source_url: 'https://x', clipped_at: '2026' }, { source_url: 'https://x' }, { source_url: ' ', clipper: 'x' },
{ source_url: 'https://x', captured_via: 'clipper' }, { source_url: 'https://x', type: 'clipping' }, { provenance: 'auto-extracted' },
{ dream_generated: true }, { dream_generated: 'true' }, { dream_generated: false }, { provenance: 'manual', source_kind: 'inbox-folder', trust_tier: 'tool_observed' },
{ extracted_by: 'extract_atoms-v0.41.2.1' }, { extracted_by: ' extract_atoms-v0.42 ' }, { extracted_by: 'extractXatoms-v1' },
{ extracted_by: 'gpt-extractor' }, { extracted_by: 5 }, { extracted_by: 'extract_atoms-v0.41.2.1', trust_tier: 'external_untrusted' },
{ source_kind: '\u00a0webhook\u00a0' }, { captured_via: '\u2003connector:gmail\u000b' }, { ingested_via: 'capture-cli\u3000' },
{ transcript_import: { harness: '\ufeffclaude-code\u2028' } }, { source_url: '\u00a0', clipper: 'x' }, { source_url: 'https://x', clipped_at: '\u000c' },
{ provenance: 'auto-extracted\u00a0' }, { extracted_by: '\u2009extract_atoms-v0.42' },
{ captured_via: 'life-chronicle:auto' }, { captured_via: '\u00a0life-chronicle:auto ' }, { captured_via: 'life-chronicle:manual' },
];
const sql = `SELECT LEAST(${frontmatterTrustCapsSql('v.fm').join(', ')}) AS r FROM (SELECT $1::text::jsonb AS fm) v`;
for (const fm of samples) {
const [row] = await engine.executeRaw<{ r: number | null }>(sql, [JSON.stringify(fm)]);
const caps = frontmatterTrustCaps(fm);
const expected = caps.length ? Math.min(...caps.map(t => TRUST_TIER_RANK[t])) : null;
expect({ fm, rank: row!.r === null ? null : Number(row!.r) }).toEqual({ fm, rank: expected });
}
});
test('--dry-run lists each source with its projection and writes nothing', async () => {
const s = await seed();
const before = await snapshot(s.src);
const listing = await listClaimSources(engine);
const { out } = await runCli(['--dry-run']);
expect(await snapshot(s.src)).toBe(before);
const own = listing.sources.find(x => x.id === s.src)!;
expect(own).toMatchObject({ local_path: '/home/alice-example/notes', pages: 10, claimable: true, claimed: false });
expect(own.current!.unknown).toBe(own.legacy_unknown);
expect(own.projected_if_claimed.user_confirmed).toBe(0);
expect(own.projected_if_claimed.operator_curated).toBe(5);
expect(listing.sources.find(x => x.id === s.gh)).toMatchObject({ claimable: false, blocker: 'connector' });
expect(out).toContain(`${s.src} (/home/alice-example/notes): 10 page(s)`);
expect(out).toContain('github connector: cannot be claimed');
});
test('without a terminal it refuses with a tell_user_to_run fix and changes nothing', async () => {
const s = await seed();
const before = await snapshot(s.src);
nonTty();
const { err } = await runCli(['--source', s.src, '--yes']);
expect(err).toContain('confirmation_required');
expect(await snapshot(s.src)).toBe(before);
const fix = render(claimSourcesFix());
expect(fix.next).toBe('tell_user_to_run');
expect(fix.consent).toEqual([]);
expect(fix.argv).toEqual(['gbrain', 'trust', 'claim-sources']);
expect(fix.user_message).toContain('gbrain trust claim-sources');
expect(fix.user_message).toContain('your notes');
});
test('typing the id claims the source: legacy rows become your notes, lowering signals keep their tier, nothing is confirmed', async () => {
const s = await seed();
const io = tty(s.src);
await runCli(['--source', s.src]);
expect(io.prompt()).toContain(`Type ${s.src} to confirm`);
const config = await configOf(s.src);
expect(config.trust_tier).toBe('operator_curated');
expect(typeof config[TRUST_CLAIMED_AT_KEY]).toBe('string');
expect(typeof config[TRUST_CLAIM_LIFTED_AT_KEY]).toBe('string');
const p = s.pages;
expect({
plain: await tierOf('pages', p.plain!), mcp: await tierOf('pages', p.mcp!), capture: await tierOf('pages', p.capture!),
ownTranscript: await tierOf('pages', p['own-transcript']!), otherTranscript: await tierOf('pages', p['other-transcript']!),
clipped: await tierOf('pages', p.clipped!), marker: await tierOf('pages', p.marker!), confirmedMarker: await tierOf('pages', p['confirmed-marker']!),
connectorStamp: await tierOf('pages', p['connector-stamp']!), atom: await tierOf('pages', p.atom!), gh: await tierOf('pages', p['gh-plain']!),
factPlain: await tierOf('facts', s.facts.plain), factBackstop: await tierOf('facts', s.facts.backstop),
factOnPlain: await tierOf('facts', s.facts.onPlain), factOnMcp: await tierOf('facts', s.facts.onMcp),
take: await tierOf('takes', s.take), entry: await tierOf('timeline_entries', s.entry),
}).toEqual({
plain: 'operator_curated', mcp: 'agent_written', capture: 'agent_written', ownTranscript: 'agent_written', otherTranscript: 'external_untrusted',
clipped: 'external_untrusted', marker: 'agent_written', confirmedMarker: 'operator_curated', connectorStamp: 'external_untrusted', atom: 'agent_written', gh: 'unknown',
factPlain: 'operator_curated', factBackstop: 'agent_written', factOnPlain: 'operator_curated', factOnMcp: 'agent_written',
take: 'operator_curated', entry: 'external_untrusted',
});
const [origin] = await engine.executeRaw<{ c: string }>(`SELECT write_origin->>'channel' AS c FROM pages WHERE id=$1`, [p.plain]);
expect(origin!.c).toBe('trust_claim');
expect((await readUnclaimedLegacySources(engine)).unclaimed.map(u => u.id)).not.toContain(s.src);
});
test('a wrong token declines; --yes never claims', async () => {
const s = await seed();
tty('yes');
const { out } = await runCli(['--source', s.src, '--yes']);
expect(out).toContain('--yes never claims');
expect(out).toContain(`${s.src}: not claimed`);
expect((await configOf(s.src))[TRUST_CLAIMED_AT_KEY]).toBeUndefined();
expect(await tierOf('pages', s.pages.plain!)).toBe('unknown');
});
test('connector sources cannot be claimed', async () => {
const s = await seed();
tty(s.gh);
const { err } = await runCli(['--source', s.gh]);
expect(err).toContain('invalid_params');
expect(err).toContain('connector');
await expect(recordSourceClaims(engine, [s.gh])).rejects.toMatchObject({ code: 'invalid_params' });
expect(await tierOf('pages', s.pages['gh-plain']!)).toBe('unknown');
});
test('an interrupted lift resumes; until then the scan refuses and explain shows owner tier', async () => {
const s = await seed();
await recordSourceClaims(engine, [s.src]);
let batches = 0;
await expect(runTrustBackfill(engine, { sources: [s.src], batchSize: 1, log: () => { if (++batches === 2) throw new Error('interrupted'); } })).rejects.toThrow('interrupted');
const pending = await doctor(trustSourcesUnclaimedEntry);
expect(pending.status).toBe('warn');
expect(render(pending.fix).argv).toEqual(['gbrain', 'trust', 'claim-sources', '--resume']);
await expect(runTrustScan(engine)).rejects.toMatchObject({ code: 'recovery_required' });
const [still] = await engine.executeRaw<{ slug: string }>(`SELECT slug FROM pages WHERE source_id=$1 AND trust_tier='unknown' ORDER BY id LIMIT 1`, [s.src]);
const [explained] = await explainTrust(engine, `p:${s.src}/${still!.slug}`);
expect(explained).toMatchObject({ tier: 'unknown', claimed_source: 'lift_pending' });
expect(explained!.label).toStartWith('your notes');
tty('unused');
await runCli(['--resume']);
expect(await tierOf('pages', s.pages.plain!)).toBe('operator_curated');
expect(await tierOf('pages', s.pages.mcp!)).toBe('agent_written');
expect((await readUnclaimedLegacySources(engine)).pending).not.toContain(s.src);
expect((await liftClaimedSources(engine)).sources).toEqual([]);
});
test('sources set-trust to a lower tier ends the claim', async () => {
const s = await seed();
await recordSourceClaims(engine, [s.src]);
const log = console.log;
console.log = () => {};
try { await runSetTrust(engine, [s.src, 'agent_written']); } finally { console.log = log; }
const config = await configOf(s.src);
expect(config.trust_tier).toBe('agent_written');
expect(config[TRUST_CLAIMED_AT_KEY]).toBeUndefined();
});
});
describe('the asks around claiming', () => {
test('doctor trust_sources_unclaimed: ok on a fresh brain, tell_user_to_run while unclaimed legacy rows exist', async () => {
expect((await doctor(trustSourcesUnclaimedEntry, fresh)).status).toBe('ok');
expect(await trustClaimUpgradeNotice(fresh)).toBeNull();
expect(await withTrustClaimAsk(fresh, { code: 'behavior_changes', kind: 'safety', why: 'w', fix: { argv: ['gbrain', 'doctor', '--only', 'behavior_changes', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: 'x' } }))
.toMatchObject({ fix: { argv: ['gbrain', 'doctor', '--only', 'behavior_changes', '--json'] } });
const s = await seed();
const check = await doctor(trustSourcesUnclaimedEntry);
expect(check.status).toBe('warn');
expect(check.message).toContain(s.src);
expect(check.message).not.toContain(s.gh);
const fix = render(check.fix);
expect(fix.next).toBe('tell_user_to_run');
expect(fix.consent).toEqual([]);
expect(fix.argv).toEqual(['gbrain', 'trust', 'claim-sources']);
});
test('a row stored as unknown after the trust migrations is not legacy: no warning, and a claim never lifts it', async () => {
const [page] = await fresh.executeRaw<{ id: number }>(`INSERT INTO pages(slug,type,title,compiled_truth,source_id) VALUES('p/late','note','T','x','default') RETURNING id`);
expect((await fresh.executeRaw<{ t: string }>('SELECT trust_tier AS t FROM pages WHERE id=$1', [page!.id]))[0]!.t).toBe('unknown');
expect((await doctor(trustSourcesUnclaimedEntry, fresh)).status).toBe('ok');
await recordSourceClaims(fresh, ['default']);
await liftClaimedSources(fresh);
expect((await fresh.executeRaw<{ t: string }>('SELECT trust_tier AS t FROM pages WHERE id=$1', [page!.id]))[0]!.t).toBe('unknown');
});
test('doctor trust_scan leaves the legacy scan to the user', async () => {
await seed();
// These rows stand in for content from before the write gate: no scan baseline bounds them.
await engine.executeRaw('DELETE FROM config WHERE key = $1', [WRITE_GATE_SCAN_BASELINE_KEY]);
const check = await doctor(trustScanEntry);
expect(check.status).toBe('warn');
const fix = render(check.fix);
expect(fix.next).toBe('tell_user_to_run');
expect(fix.consent).toEqual([]);
expect(fix.argv).toEqual(['gbrain', 'trust', 'scan']);
expect(fix.user_message).toContain('claim');
});
test('the claim ask reads row tables only for unclaimed sources, and agrees with the doctor read', async () => {
const s = await seed();
expect(await hasUnclaimedLegacySources(engine)).toBe(true);
expect((await readUnclaimedLegacySources(engine)).unclaimed.map(u => u.id)).toContain(s.src);
const seen: string[] = [];
const allClaimed = { executeRaw: async (sql: string) => { seen.push(sql); return /FROM sources/.test(sql) ? [{ id: 'a', claimed: true, lifted: true }] as never[] : []; } };
expect(await hasUnclaimedLegacySources(allClaimed as never)).toBe(false);
expect(await readUnclaimedLegacySources(allClaimed as never)).toEqual({ unclaimed: [], pending: [] });
expect(seen.length).toBe(2);
expect(seen.some(sql => /\b(pages|facts|takes|timeline_entries)\b/.test(sql))).toBe(false);
});
test('post-upgrade and the behavior-change notice carry the tell_user_to_run block', async () => {
await seed();
const lines = (await trustClaimUpgradeNotice(engine))!.join('\n');
expect(lines).toContain('[AGENT]');
expect(lines).toContain('next: tell_user_to_run: gbrain trust claim-sources');
expect(lines).toContain('[SHOW USER]');
expect(lines).not.toContain('gbrain trust scan --');
const notice = await withTrustClaimAsk(engine, { code: 'behavior_changes', kind: 'safety', why: 'w', fix: { argv: ['gbrain', 'doctor', '--only', 'behavior_changes', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: 'x' } });
expect(render(notice!.fix)).toMatchObject({ next: 'tell_user_to_run', consent: [] });
expect(notice!.user_message).toContain('gbrain trust claim-sources');
});
});