Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
37.9 KB
Raw Blame
/**
 * bootstrap verify — the D8 check union against a hermetic in-memory PGLite
 * brain (the resolve-ipc-v2 pattern): keyless roundtrip [G1/CX-P0.5],
 * graph floor [CX2-5], magic moment via the ## Facts fence, probe cleanup
 * [G13], failure-shape checks (token sweep / byte floors / secret scan), and
 * snapshot retention [B2].
 */
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { addSource } from '../src/core/sources-ops.ts';
import { readManifest, writeManifest } from '../src/core/bootstrap/format.ts';
import { initState, setAnswer, confirm, readBackHash } from '../src/core/bootstrap/interview.ts';
import { loadQuestionBank } from '../src/core/bootstrap/assets.ts';
import { byteFloors } from '../src/core/bootstrap/render.ts';
import {
  verifyWorkspace,
  resolveVerifySourceId,
  VERIFY_PROBE_SLUG,
  VERIFY_PROBE_ENTITY_SLUG,
  VERIFY_MAGIC_TOKEN,
  VERIFY_SNAPSHOTS_KEPT,
  FIRST_RUN_TOUR,
} from '../src/core/bootstrap/verify.ts';
import { listVerifyRuns } from '../src/core/bootstrap/status.ts';
import type { CapabilityReport } from '../src/core/capability.ts';
import { _resetWriteThroughCacheForTest } from '../src/core/write-through.ts';
import { operations, type OperationContext } from '../src/core/operations.ts';
import { loadCorpusPages, loadCorpusQueries } from './helpers/bootstrap-corpus.ts';
import { claimWorktree } from '../src/core/persistence/ownership.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';

const KEYLESS: CapabilityReport = {
  embeddings: { available: false },
  extraction: { available: false },
  search: 'keyword-only',
  mode: 'keyless',
};

let engine: PGLiteEngine;
let tmpParent: string;
let home: string;
let ws: string;
let prevHome: string | undefined;

function pad(text: string, bytes: number): string {
  let out = text;
  while (Buffer.byteLength(out, 'utf8') < bytes) {
    out += '\nSubstantive identity prose rendered from real interview answers, not filler headers.';
  }
  return out;
}

beforeAll(async () => {
  tmpParent = mkdtempSync(join(tmpdir(), 'gb-verify-'));
  home = join(tmpParent, '.gbrain');
  mkdirSync(join(home, 'bootstrap'), { recursive: true });
  ws = mkdtempSync(join(tmpdir(), 'gb-verify-ws-'));
  prevHome = process.env.GBRAIN_HOME;
  process.env.GBRAIN_HOME = tmpParent;

  // Workspace shape: initialized manifest + interview answers (6 required,
  // confirmed) + identity files above the 6-answer byte floors + brain/.
  writeManifest(ws, {
    format_version: 1,
    initialized: true,
    agent_name: 'Verify Test Agent',
    created_by: 'test',
    created_at: new Date().toISOString(),
    source_id: 'workspace',
  });
  const bank = loadQuestionBank();
  const required = bank.interviewKeys.filter((k) => bank.questions[k]?.required === true);
  expect(initState(ws).ok).toBe(true);
  const answers: Record<string, string> = {
    AGENT_NAME: 'Testa',
    PRINCIPAL_NAME: 'Pat Example',
    AGENT_PURPOSE: 'Maintain the research corpus and draft the weekly memo without re-briefing.',
    AGENT_TOP_JOBS: '- corpus upkeep\n- weekly memo\n- meeting prep',
    PRINCIPAL_CONTEXT: 'Runs a small research group; builds internal tooling; cares about signal over noise.',
    VOICE_REGISTER: 'Direct: three options, the second one wins.',
  };
  for (const key of required) {
    const r = setAnswer(ws, key, answers[key] ?? `a real answer for ${key}`);
    if (!r.ok) throw new Error(`setAnswer(${key}) failed: ${r.message}`);
  }
  const h = readBackHash(ws);
  if (!h.ok) throw new Error(h.message);
  expect(confirm(ws, h.hash).ok).toBe(true);

  const floors = byteFloors(required.length);
  writeFileSync(
    join(ws, 'AGENTS.md'),
    '⛔ **WRITE IT DOWN — SAME TURN, THROUGH THE BRAIN.**\n\n' +
      '**Gate 7 — Write-back.** Before ending the turn, persist durable learning.\n',
  );
  writeFileSync(join(ws, 'SOUL.md'), pad('# Soul\n\nIdentity rendered from answers.\n', floors['SOUL.md'] + 200));
  writeFileSync(join(ws, 'USER.md'), pad('# User\n\nTheir literal words are ground truth.\n', floors['USER.md'] + 100));
  mkdirSync(join(ws, 'brain'), { recursive: true });

  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
  // The workspace source: brain/ registered with its own local_path so the
  // put_page write-through materializes committed files under brain/ [G1].
  await addSource(engine, { id: 'workspace', localPath: join(ws, 'brain'), force: true });
}, 240_000);

afterAll(async () => {
  try {
    await engine.disconnect();
  } catch {
    /* noop */
  }
  if (prevHome === undefined) delete process.env.GBRAIN_HOME;
  else process.env.GBRAIN_HOME = prevHome;
  rmSync(tmpParent, { recursive: true, force: true });
  rmSync(ws, { recursive: true, force: true });
});

function check(checks: Array<{ id: string; ok: boolean; warn?: boolean; detail: string }>, id: string) {
  const found = checks.filter((c) => c.id === id);
  expect(found.length).toBeGreaterThan(0);
  return found;
}

describe('verifyWorkspace — keyless pass', () => {
  test('roundtrip + graph floor + magic moment pass with ZERO api keys; probes cleaned up', async () => {
    // Snapshot-retention setup [B2]: pre-seed old snapshots so the prune path runs.
    for (let i = 0; i < VERIFY_SNAPSHOTS_KEPT; i++) {
      writeFileSync(
        join(home, 'bootstrap', `verify-2020-01-0${i + 1}T00-00-00-000Z.json`),
        JSON.stringify({ ts: `2020-01-0${i + 1}T00:00:00.000Z`, ok: true, checks: [] }),
      );
    }

    const res = await verifyWorkspace(engine, ws, {
      sourceId: 'workspace',
      gbrainHomeDir: home,
      capabilities: KEYLESS,
    });

    // Individual checks.
    expect(check(res.checks, 'doctor_green')[0].ok).toBe(true);
    expect(check(res.checks, 'token_sweep')[0].ok).toBe(true);
    expect(check(res.checks, 'byte_floors')[0].ok).toBe(true);
    expect(check(res.checks, 'writeback_contract')[0].ok).toBe(true);
    expect(check(res.checks, 'secret_scan')[0].ok).toBe(true);
    expect(check(res.checks, 'deny_globs')[0].ok).toBe(true);
    expect(check(res.checks, 'repo_privacy')[0].ok).toBe(true); // local-only
    // execution_env is informational and NEVER gates [D-cloud].
    expect(check(res.checks, 'execution_env')[0].ok).toBe(true);
    for (const c of check(res.checks, 'roundtrip')) expect(c.ok).toBe(true);
    // #4287 wiring: the active-plane probe runs on every verify; keyless
    // installs pass it (no active plane exists to split).
    expect(check(res.checks, 'embedding_plane')[0].ok).toBe(true);
    expect(check(res.checks, 'embedding_plane')[0].detail).toContain('keyless');
    expect(check(res.checks, 'graph_floor')[0].ok).toBe(true);
    expect(check(res.checks, 'magic_moment')[0].ok).toBe(true);
    expect(check(res.checks, 'capability_report')[0].detail).toContain('keyless');
    expect(check(res.checks, 'hooks_smoke')[0].ok).toBe(true); // not installed → not applicable
    expect(check(res.checks, 'first_run_tour')[0].ok).toBe(true);
    expect(res.ok).toBe(true);

    // The report embeds the capability block + the three scripted prompts [D3.6/A4].
    expect(res.report).toContain('keyless mode');
    for (const prompt of FIRST_RUN_TOUR) {
      expect(res.report).toContain(prompt);
    }
    expect(res.tour).toEqual([...FIRST_RUN_TOUR]);

    // The OOBE hand-off block prints after the tour on PASS: ownership (this
    // ws has no origin remote → the local-only variant with the repo upgrade
    // path) and the ONE next action (the cold-start skill via ClawVisor).
    expect(res.report).toContain('What you own');
    expect(res.report).toContain('gbrain bootstrap repo');
    expect(res.report).toContain('cold-start');
    expect(res.report).toContain('ClawVisor');
    expect(res.handoff.length).toBeGreaterThan(0);

    // Probe cleanup [G13]: pages, files, and the reconciled fact are gone.
    expect(existsSync(join(ws, 'brain', `${VERIFY_PROBE_SLUG}.md`))).toBe(false);
    expect(existsSync(join(ws, 'brain', `${VERIFY_PROBE_ENTITY_SLUG}.md`))).toBe(false);
    // Tombstone-proof: the cleanup HARD-deletes via engine.deletePage — a
    // soft delete (deleted_at tombstone) would leave these rows countable.
    const probeRows = await engine.executeRaw<{ n: string }>(
      `SELECT count(*)::text AS n FROM pages WHERE slug = ANY($1::text[])`,
      [[VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG]],
    );
    expect(probeRows[0].n).toBe('0');
    const facts = await engine.executeRaw<{ fact: string }>(
      `SELECT fact FROM facts WHERE source_id = $1 AND fact LIKE $2`,
      ['workspace', `%${VERIFY_MAGIC_TOKEN}%`],
    );
    expect(facts.length).toBe(0);

    // Snapshot persisted + retention holds at VERIFY_SNAPSHOTS_KEPT [B2].
    const runs = listVerifyRuns(home);
    expect(runs.length).toBeLessThanOrEqual(VERIFY_SNAPSHOTS_KEPT);
    expect(runs[0].ok).toBe(true); // newest = this run
  }, 240_000);

  test('a user fact that merely CONTAINS the magic-token substring survives verify [8b]', async () => {
    // A real user fact from a different page, plus a legacy NULL-slug fact,
    // both mentioning the token STRING. The probe cleanup must scope to the
    // probe page's source_markdown_slug, never a `fact LIKE %token%` match, so
    // neither of these is swept.
    await engine.executeRaw(
      `INSERT INTO facts (source_id, fact, source, source_markdown_slug, visibility)
       VALUES ($1, $2, 'user', $3, 'world')`,
      ['workspace', `a real note that mentions ${VERIFY_MAGIC_TOKEN} in passing`, 'wiki/real-user-note'],
    );
    await engine.executeRaw(
      `INSERT INTO facts (source_id, fact, source, visibility)
       VALUES ($1, $2, 'user', 'world')`,
      ['workspace', `a legacy NULL-slug fact mentioning ${VERIFY_MAGIC_TOKEN}`],
    );

    const res = await verifyWorkspace(engine, ws, {
      sourceId: 'workspace',
      gbrainHomeDir: home,
      capabilities: KEYLESS,
    });
    expect(res.ok).toBe(true);

    // The probe fact (source_markdown_slug = probe slug) IS cleaned up …
    const probeFacts = await engine.executeRaw<{ id: number }>(
      `SELECT id FROM facts WHERE source_id = $1 AND source_markdown_slug = $2`,
      ['workspace', VERIFY_PROBE_SLUG],
    );
    expect(probeFacts.length).toBe(0);

    // … but BOTH user facts that merely mention the token string survive.
    const survivors = await engine.executeRaw<{ fact: string }>(
      `SELECT fact FROM facts WHERE source_id = $1 AND fact LIKE $2`,
      ['workspace', `%${VERIFY_MAGIC_TOKEN}%`],
    );
    expect(survivors.length).toBe(2);

    // Cleanup so later tests start from a clean facts table.
    await engine.executeRaw(`DELETE FROM facts WHERE source_id = $1 AND fact LIKE $2`, [
      'workspace', `%${VERIFY_MAGIC_TOKEN}%`,
    ]);
  }, 240_000);

  test('failure shapes: unresolved token + under-floor USER.md + planted secret all surface', async () => {
    const soulPath = join(ws, 'SOUL.md');
    const userPath = join(ws, 'USER.md');
    const githubPath = join(ws, 'GITHUB.md');
    const soulOriginal = readFileSync(soulPath, 'utf8');
    const userOriginal = readFileSync(userPath, 'utf8');
    try {
      writeFileSync(githubPath, '# GitHub\n\nRepo: {{GITHUB_REPO_URL}}\n');
      writeFileSync(userPath, '# tiny\n');
      writeFileSync(soulPath, soulOriginal + '\napi dump: sk-AAAAAAAAAAAAAAAAAAAAAAAA\n');

      const res = await verifyWorkspace(engine, ws, {
        sourceId: 'workspace',
        gbrainHomeDir: home,
        capabilities: KEYLESS,
      });

      const token = check(res.checks, 'token_sweep')[0];
      expect(token.ok).toBe(false);
      expect(token.detail).toContain('GITHUB.md');
      expect(token.detail).toContain('GITHUB_REPO_URL');

      const floors = check(res.checks, 'byte_floors')[0];
      expect(floors.ok).toBe(false);
      expect(floors.detail).toContain('USER.md');

      const scan = check(res.checks, 'secret_scan')[0];
      expect(scan.ok).toBe(false);
      expect(scan.detail).toContain('openai');
      expect(scan.detail).toContain(`allowlist only a reviewed false positive by appending its fingerprint to ${join(ws, '.gbrain-scan-allow')}`);
      expect(scan.detail).toContain('write-refusals.md#secret-scan-refusals-and-redaction');
      // Redaction discipline: the finding detail NEVER carries the secret value.
      expect(scan.detail).not.toContain('sk-AAAAAAAAAAAAAAAAAAAAAAAA');

      expect(res.ok).toBe(false);

      // Tour gating on FAIL: the report says fix-first and withholds the
      // celebration prompts ("broken, but go enjoy it" is a mixed signal) …
      expect(res.report).toContain('Fix the FAIL checks above');
      expect(res.report).not.toContain('Who am I to you?');
      // … the hand-off block is withheld with the tour (celebrating ownership
      // of a FAILED install is the same mixed signal) …
      expect(res.report).not.toContain('What you own');
      expect(res.report).not.toContain('cold-start');
      // … while the returned tour + handoff arrays stay unconditional so
      // machine consumers (--json) keep a stable shape, and the check names
      // the gate.
      expect(res.tour).toEqual([...FIRST_RUN_TOUR]);
      expect(res.handoff.length).toBeGreaterThan(0);
      expect(check(res.checks, 'first_run_tour')[0].detail).toContain('withheld');
    } finally {
      rmSync(githubPath, { force: true });
      writeFileSync(userPath, userOriginal);
      writeFileSync(soulPath, soulOriginal);
    }
  }, 240_000);
});

describe('verifyWorkspace — write-through disabled by config', () => {
  test('sync.write_through=false → roundtrip WARNs naming the config key; the rest of the family still runs', async () => {
    await engine.setConfig('sync.write_through', 'false');
    _resetWriteThroughCacheForTest(); // prior verify runs primed the ~30s per-engine cache
    try {
      const res = await verifyWorkspace(engine, ws, {
        sourceId: 'workspace',
        gbrainHomeDir: home,
        capabilities: KEYLESS,
      });
      const wtWarn = check(res.checks, 'roundtrip').find((c) => c.detail.includes('sync.write_through'));
      expect(wtWarn).toBeDefined();
      expect(wtWarn!.ok).toBe(true);
      expect(wtWarn!.warn).toBe(true);
      // The remaining roundtrip-family checks still ran off the DB row.
      expect(check(res.checks, 'graph_floor')[0].ok).toBe(true);
      expect(check(res.checks, 'magic_moment')[0].ok).toBe(true);
      expect(res.ok).toBe(true);
      // No file materialized under brain/ (DB-only by operator choice).
      expect(existsSync(join(ws, 'brain', `${VERIFY_PROBE_SLUG}.md`))).toBe(false);
    } finally {
      await engine.unsetConfig('sync.write_through');
      _resetWriteThroughCacheForTest();
    }
  }, 240_000);
});

describe('verifyWorkspace — pending corpus transcripts (#6786)', () => {
  test('a keyed report in a process that cannot serve the extraction model leaves pending transcripts pending', async () => {
    const corpusDir = mkdtempSync(join(tmpdir(), 'gb-verify-corpus-'));
    const spool = join(corpusDir, 'sourced');
    mkdirSync(spool, { recursive: true });
    const transcript = join(spool, 'sess-verify-example.src-workspace.txt');
    writeFileSync(transcript, '[user]\nI keep a written log of every product decision.\n\n[assistant]\nNoted.\n');
    const KEYED: CapabilityReport = { embeddings: { available: false }, extraction: { available: true, provider: 'anthropic' }, search: 'keyword-only', mode: 'keyed' };
    await engine.setConfig('dream.synthesize.session_corpus_dir', corpusDir);
    try {
      // verify's engine never configures the gateway, so no extraction model is servable.
      const res = await verifyWorkspace(engine, ws, { sourceId: 'workspace', gbrainHomeDir: home, capabilities: KEYED });
      expect(check(res.checks, 'graph_floor')[0].ok).toBe(true);
      expect(existsSync(`${transcript}.ingested`)).toBe(false);
      expect(existsSync(`${transcript}.progress`)).toBe(false);
    } finally {
      await engine.unsetConfig('dream.synthesize.session_corpus_dir');
      rmSync(corpusDir, { recursive: true, force: true });
    }
  }, 240_000);
});

describe('verifyWorkspace — probe cleanup on an early roundtrip exit (#6001)', () => {
  test('a roundtrip that fails before its cleanup step still removes both probe pages', async () => {
    // A DIRECTORY where the second probe's file must go: the entity probe lands (row + file), the
    // probe page's put_page throws, the roundtrip FAILS at step 1 and returns early, which used to
    // skip removeProbes and leave the entity probe behind.
    const inTheWay = join(ws, 'brain', `${VERIFY_PROBE_SLUG}.md`);
    mkdirSync(inTheWay, { recursive: true });
    try {
      const res = await verifyWorkspace(engine, ws, { sourceId: 'workspace', gbrainHomeDir: home, capabilities: KEYLESS, skipHooksSmoke: true });
      const rt = check(res.checks, 'roundtrip');
      expect(rt.some((c) => !c.ok && c.detail.includes('put_page failed'))).toBe(true);
      expect(res.checks.filter((c) => c.id === 'graph_floor')).toEqual([]);
      expect(res.checks.filter((c) => c.id === 'probe_cleanup')).toEqual([]);
      const probeRows = await engine.executeRaw<{ n: string }>(
        `SELECT count(*)::text AS n FROM pages WHERE source_id = 'workspace' AND slug = ANY($1::text[])`,
        [[VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG]],
      );
      expect(probeRows[0].n).toBe('0');
      expect(existsSync(join(ws, 'brain', `${VERIFY_PROBE_ENTITY_SLUG}.md`))).toBe(false);
    } finally {
      rmSync(inTheWay, { recursive: true, force: true });
    }
  }, 240_000);
});

describe('verifyWorkspace — engine-plane side effects', () => {
  test('[CX-P1.1] facts.default_visibility: unset → set to world; explicit private → untouched', async () => {
    const e2 = new PGLiteEngine();
    await e2.connect({});
    await e2.initSchema();
    const ws2 = mkdtempSync(join(tmpdir(), 'gb-verify-vis-'));
    try {
      mkdirSync(join(ws2, 'brain'), { recursive: true });
      expect(await e2.getConfig('facts.default_visibility')).toBeNull();

      const res = await verifyWorkspace(e2, ws2, {
        sourceId: 'workspace',
        gbrainHomeDir: home,
        capabilities: KEYLESS,
        skipHooksSmoke: true,
        sweepBudgetMs: 5_000,
      });
      // Fresh engine: posture set to world through the engine config plane…
      expect(await e2.getConfig('facts.default_visibility')).toBe('world');
      // …and the report names the posture + where to flip it, in one line.
      const check = res.checks.find((c) => c.id === 'facts_visibility')!;
      expect(check.ok).toBe(true);
      expect(check.detail).toContain('world');
      expect(check.detail).toContain('facts.default_visibility');
      expect(check.detail).toContain('gbrain config set');
      // The key governs extraction-path writes only; `remember` hard-defaults
      // to 'world' — the message must disclose that carve-out (#5605).
      expect(check.detail).toContain('`remember`');
      expect(check.detail).toContain('extraction-path');

      // Pre-set explicit value survives verify (set-if-unset, never override).
      await e2.setConfig('facts.default_visibility', 'private');
      const res2 = await verifyWorkspace(e2, ws2, {
        sourceId: 'workspace',
        gbrainHomeDir: home,
        capabilities: KEYLESS,
        skipHooksSmoke: true,
        sweepBudgetMs: 5_000,
      });
      expect(await e2.getConfig('facts.default_visibility')).toBe('private');
      const check2 = res2.checks.find((c) => c.id === 'facts_visibility')!;
      expect(check2.detail).toContain('private');
      expect(check2.detail).toContain('untouched');
      expect(check2.detail).toContain('`remember`');
    } finally {
      await e2.disconnect();
      rmSync(ws2, { recursive: true, force: true });
    }
  }, 240_000);

  test('mcp_surface=verbs in config → loud WARN naming the --surface full fix', async () => {
    const cfgPath = join(home, 'config.json');
    writeFileSync(cfgPath, JSON.stringify({ engine: 'pglite', mcp_surface: 'verbs' }), 'utf8');
    try {
      const res = await verifyWorkspace(engine, ws, {
        sourceId: 'workspace',
        gbrainHomeDir: home,
        capabilities: KEYLESS,
        skipHooksSmoke: true,
      });
      const check = res.checks.find((c) => c.id === 'mcp_surface')!;
      expect(check.ok).toBe(true);
      expect(check.warn).toBe(true);
      expect(check.detail).toContain('verbs');
      expect(check.detail).toContain('--surface full');
    } finally {
      rmSync(cfgPath, { force: true });
    }
  }, 240_000);
});

describe('verifyWorkspace — source_id collision resolution', () => {
  test('single workspace: id registered to THIS checkout stays unchanged (no collision check emitted)', async () => {
    const res = await verifyWorkspace(engine, ws, {
      sourceId: 'workspace',
      gbrainHomeDir: home,
      capabilities: KEYLESS,
      skipHooksSmoke: true,
    });
    const m = readManifest(ws);
    expect(m.state).toBe('initialized');
    if (m.state === 'initialized') expect(m.manifest.source_id).toBe('workspace');
    expect(res.checks.find((c) => c.id === 'source_id')).toBeUndefined();
  }, 240_000);

  test("second workspace claiming a taken 'workspace' id derives workspace-<8char-hash> and persists it", async () => {
    const e2 = new PGLiteEngine();
    await e2.connect({});
    await e2.initSchema();
    const firstBrain = mkdtempSync(join(tmpdir(), 'gb-verify-first-brain-'));
    const ws2 = mkdtempSync(join(tmpdir(), 'gb-verify-second-ws-'));
    try {
      // The brain already has 'workspace' registered to ANOTHER checkout.
      await addSource(e2, { id: 'workspace', localPath: firstBrain, force: true });
      mkdirSync(join(ws2, 'brain'), { recursive: true });
      writeManifest(ws2, {
        format_version: 1,
        initialized: true,
        agent_name: 'Second',
        created_by: 'test',
        created_at: new Date().toISOString(),
        source_id: 'workspace',
      });

      const res = await verifyWorkspace(e2, ws2, {
        sourceId: 'workspace',
        gbrainHomeDir: home,
        capabilities: KEYLESS,
        skipHooksSmoke: true,
        sweepBudgetMs: 5_000,
      });
      const m = readManifest(ws2);
      expect(m.state).toBe('initialized');
      if (m.state !== 'initialized') throw new Error('unreachable');
      const derived = m.manifest.source_id;
      expect(derived).toMatch(/^workspace-[0-9a-f]{8}$/);
      const check = res.checks.find((c) => c.id === 'source_id')!;
      expect(check.warn).toBe(true);
      expect(check.detail).toContain(derived);
      expect(check.detail).toContain(`gbrain sources add ${derived}`);
      expect(check.detail).toContain('hooks --repair');

      // Re-run is stable: the derived id is not itself in collision.
      const res2 = await verifyWorkspace(e2, ws2, {
        sourceId: derived,
        gbrainHomeDir: home,
        capabilities: KEYLESS,
        skipHooksSmoke: true,
        sweepBudgetMs: 5_000,
      });
      const m2 = readManifest(ws2);
      if (m2.state !== 'initialized') throw new Error('unreachable');
      expect(m2.manifest.source_id).toBe(derived);
      expect(res2.checks.find((c) => c.id === 'source_id')).toBeUndefined();
    } finally {
      await e2.disconnect();
      rmSync(firstBrain, { recursive: true, force: true });
      rmSync(ws2, { recursive: true, force: true });
    }
  }, 240_000);
});

describe('verifyWorkspace — workspace source registration (#4328)', () => {
  test("uninitialized workspace resolves through the source resolver to 'default' and verify passes", async () => {
    const e2 = new PGLiteEngine();
    await e2.connect({});
    await e2.initSchema();
    const ws2 = mkdtempSync(join(tmpdir(), 'gb-verify-uninit-'));
    try {
      mkdirSync(join(ws2, 'brain'), { recursive: true });
      // Identity files above the 0-answer floors (uninit ws — no interview ran).
      const floors0 = byteFloors(0);
      writeFileSync(join(ws2, 'SOUL.md'), pad('# Soul\n\nMinimal identity.\n', floors0['SOUL.md'] + 200));
      writeFileSync(join(ws2, 'USER.md'), pad('# User\n\nMinimal user notes.\n', floors0['USER.md'] + 100));
      // The writeback_contract check requires the integrated gate; this test
      // exercises source resolution, not the contract audit.
      writeFileSync(
        join(ws2, 'AGENTS.md'),
        '⛔ **WRITE IT DOWN — SAME TURN, THROUGH THE BRAIN.**\n\n' +
          '**Gate 7 — Write-back.** Before ending the turn, persist durable learning.\n',
      );
      // No manifest at all — the pre-fix hardcoded 'workspace' fallback made
      // put_page fail its sources FK on any brain that never registered it.
      const resolved = await resolveVerifySourceId(e2, ws2);
      expect(resolved).toBe('default');
      // The shape `gbrain sources add` leaves behind: the resolved source's
      // local_path is the workspace brain/ so write-through materializes.
      // (Direct UPDATE — 'default' is seeded by migration, so add would collide.)
      await e2.executeRaw(`UPDATE sources SET local_path = $1 WHERE id = 'default'`, [join(ws2, 'brain')]);
      const res = await verifyWorkspace(e2, ws2, {
        sourceId: resolved,
        gbrainHomeDir: home,
        capabilities: KEYLESS,
        skipHooksSmoke: true,
        sweepBudgetMs: 5_000,
      });
      if (!res.ok) console.error(res.report);
      expect(res.ok).toBe(true);
      for (const c of res.checks) expect(c.detail).not.toContain('foreign key');
    } finally {
      await e2.disconnect();
      rmSync(ws2, { recursive: true, force: true });
    }
  }, 240_000);

  test('unregistered workspace source → named actionable FAIL, probe writes + hooks smoke skipped, no raw FK error', async () => {
    const e2 = new PGLiteEngine();
    await e2.connect({});
    await e2.initSchema();
    const ws2 = mkdtempSync(join(tmpdir(), 'gb-verify-unreg-'));
    try {
      mkdirSync(join(ws2, 'brain'), { recursive: true });
      writeManifest(ws2, {
        format_version: 1,
        initialized: true,
        agent_name: 'Unregistered',
        created_by: 'test',
        created_at: new Date().toISOString(),
        source_id: 'workspace',
      });
      // Initialized manifest wins resolution — but 'workspace' was never
      // `gbrain sources add`-ed on this brain.
      expect(await resolveVerifySourceId(e2, ws2)).toBe('workspace');
      const res = await verifyWorkspace(e2, ws2, {
        sourceId: 'workspace',
        gbrainHomeDir: home,
        capabilities: KEYLESS,
        sweepBudgetMs: 5_000,
      });
      expect(res.ok).toBe(false);
      const rt = check(res.checks, 'roundtrip');
      expect(rt.length).toBe(1);
      expect(rt[0].ok).toBe(false);
      expect(rt[0].detail).toContain(`gbrain sources add workspace --path ${join(ws2, 'brain')}`);
      // The named FAIL replaces the raw FK violation the put used to surface.
      for (const c of res.checks) expect(c.detail).not.toContain('foreign key');
      // put_page was SKIPPED (not attempted-and-failed): zero probe rows.
      const rows = await e2.executeRaw<{ n: string }>(
        `SELECT count(*)::text AS n FROM pages WHERE slug = ANY($1::text[])`,
        [[VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG]],
      );
      expect(rows[0].n).toBe('0');
      // The hooks smoke binds the workspace source id — skipped with the same pointer.
      const hooks = check(res.checks, 'hooks_smoke')[0];
      expect(hooks.ok).toBe(true);
      expect(hooks.detail).toContain('not registered');
    } finally {
      await e2.disconnect();
      rmSync(ws2, { recursive: true, force: true });
    }
  }, 240_000);
});

describe('verifyWorkspace — real corpus graph floor + qrels recall', () => {
  test('auto-link builds real multi-entity edges; verify passes on the populated brain; gold queries recall the expected pages', async () => {
    // Seed the synthetic world into the SAME workspace source verify checks,
    // through the real put_page handler so auto-link builds REAL edges — a
    // 12-page graph, not the 2-node self-planted probe pair verify writes.
    const loaded = await loadCorpusPages(engine, { sourceId: 'workspace' });
    expect(loaded).toContain('people/alice-example');
    expect(loaded).toContain('companies/ridge-platform');

    // Real edges exist from the wikilinks in the page bodies (not the probe):
    // alice-example → ridge-platform, with multiple outbound edges on a real
    // entity, and the reverse edge answers through the backlink table.
    const aliceLinks = await engine.getLinks('people/alice-example', { sourceId: 'workspace' });
    const aliceTargets = aliceLinks.map((l) => l.to_slug);
    expect(aliceTargets).toContain('companies/ridge-platform');
    expect(aliceTargets.length).toBeGreaterThanOrEqual(2);
    const ridgeBacklinks = await engine.getBacklinks('companies/ridge-platform', { sourceId: 'workspace' });
    expect(ridgeBacklinks.map((l) => l.from_slug)).toContain('people/alice-example');

    // verify still runs green end-to-end on the now-populated brain, and its
    // graph_floor / roundtrip checks pass alongside the real corpus graph.
    const res = await verifyWorkspace(engine, ws, {
      sourceId: 'workspace',
      gbrainHomeDir: home,
      capabilities: KEYLESS,
      skipHooksSmoke: true,
    });
    if (!res.ok) console.error(res.report);
    expect(res.ok).toBe(true);
    expect(check(res.checks, 'graph_floor')[0].ok).toBe(true);
    for (const c of check(res.checks, 'roundtrip')) expect(c.ok).toBe(true);

    // qrels: each gold page-recall case returns its expected slug through the
    // REAL keyword-search query op (keyless), over the multi-page corpus.
    const queryOp = operations.find((o) => o.name === 'query')!;
    const ctx: OperationContext = {
      engine,
      config: { engine: 'pglite' } as never,
      logger: { info: () => {}, warn: () => {}, error: () => {} },
      dryRun: false,
      remote: false,
      sourceId: 'workspace',
    };
    const goldPageCases = loadCorpusQueries().filter((q) => q.kind === 'page');
    expect(goldPageCases.length).toBeGreaterThan(0);
    const misses: string[] = [];
    for (const q of goldPageCases) {
      const result = await queryOp.handler(ctx, { query: q.query, limit: 10, expand: false });
      if (!JSON.stringify(result).includes(q.expect_slug!)) {
        misses.push(`${q.id}: "${q.query}" did not recall ${q.expect_slug}`);
      }
    }
    expect(misses).toEqual([]);
  }, 240_000);
});

describe('verifyWorkspace — managed brain (#5280)', () => {
  test('verify runs on a managed brain and purges its probes through the coordinator', async () => {
    await claimWorktree(engine, 'workspace', join(ws, 'brain'));
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    try {
      const res = await verifyWorkspace(engine, ws, { sourceId: 'workspace', gbrainHomeDir: home, capabilities: KEYLESS, skipHooksSmoke: true });
      for (const c of check(res.checks, 'roundtrip')) expect(c.ok).toBe(true);
      expect(res.checks.filter((c) => c.id === 'probe_cleanup')).toEqual([]);
      const probeRows = await engine.executeRaw<{ n: string }>(
        `SELECT count(*)::text AS n FROM pages WHERE source_id = 'workspace' AND slug = ANY($1::text[])`,
        [[VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG]],
      );
      expect(probeRows[0].n).toBe('0');
      expect(existsSync(join(ws, 'brain', `${VERIFY_PROBE_SLUG}.md`))).toBe(false);
      const purged = await engine.executeRaw<{ slug: string }>(
        `SELECT slug FROM persistence_requests WHERE source_id = 'workspace' AND operation = 'delete_page' AND state = 'committed'
            AND outcome->>'status' = 'purged' AND slug = ANY($1::text[]) ORDER BY slug`,
        [[VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG]],
      );
      expect(new Set(purged.map((r) => r.slug))).toEqual(new Set([VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG]));
      expect(await engine.executeRaw(`SELECT id FROM facts WHERE source_id = 'workspace' AND source_markdown_slug = ANY($1::text[])`,
        [[VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG]])).toEqual([]);
    } finally {
      await disposePersistenceConsumer(engine);
      await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    }
  }, 240_000);
});

describe('verifyWorkspace — managed brain, repeated runs (#6634)', () => {
  // Adapted from PR #6634 (@Masashi-Ono0611). The probe bodies stay constant; verify clears its own purge tombstones
  // instead of carrying a per-run nonce, so page_purges does not grow by a row per probe per run.
  test('verify can roundtrip twice after purging both probe pages, leaving no probe tombstones', async () => {
    await claimWorktree(engine, 'workspace', join(ws, 'brain'));
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    const probeTombstones = async () => ({
      pages: (await engine.executeRaw<{ n: number }>(`SELECT count(*)::int AS n FROM page_purges WHERE source_id = 'workspace' AND slug = ANY($1::text[])`,
        [[VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG]]))[0]!.n,
      facts: (await engine.executeRaw<{ n: number }>(`SELECT count(*)::int AS n FROM fact_purges WHERE source_id = 'workspace' AND request_id IN (
        SELECT request_id FROM persistence_requests WHERE source_id = 'workspace' AND operation = 'delete_page' AND slug = ANY($1::text[]))`,
        [[VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG]]))[0]!.n,
    });
    try {
      const opts = { sourceId: 'workspace', gbrainHomeDir: home, capabilities: KEYLESS, skipHooksSmoke: true };
      const first = await verifyWorkspace(engine, ws, opts);
      expect(check(first.checks, 'roundtrip').filter((c) => !c.ok)).toEqual([]);
      expect(await probeTombstones()).toEqual({ pages: 0, facts: 0 });

      const second = await verifyWorkspace(engine, ws, opts);
      const secondRoundtrip = check(second.checks, 'roundtrip');
      expect(secondRoundtrip.length).toBeGreaterThan(0);
      expect(secondRoundtrip.filter((c) => !c.ok)).toEqual([]);
      expect(await probeTombstones()).toEqual({ pages: 0, facts: 0 });
      const refused = await engine.executeRaw(`SELECT 1 FROM persistence_requests WHERE source_id = 'workspace' AND error_code = 'purged_content'
          AND slug = ANY($1::text[])`, [[VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG]]);
      expect(refused).toEqual([]);
    } finally {
      await disposePersistenceConsumer(engine);
      await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    }
  }, 240_000);

  test('probe tombstones an earlier verify left behind are swept before the probes are written', async () => {
    await claimWorktree(engine, 'workspace', join(ws, 'brain'));
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    // Keep a copy of every tombstone verify clears, so the test can put back exactly what an older verify left.
    await engine.executeRaw(`CREATE TABLE w6634_kept (LIKE page_purges)`);
    await engine.executeRaw(`CREATE FUNCTION w6634_keep() RETURNS trigger LANGUAGE plpgsql AS $$
      BEGIN INSERT INTO w6634_kept SELECT OLD.*; RETURN OLD; END $$`);
    await engine.executeRaw(`CREATE TRIGGER w6634_keep BEFORE DELETE ON page_purges FOR EACH ROW EXECUTE FUNCTION w6634_keep()`);
    try {
      const opts = { sourceId: 'workspace', gbrainHomeDir: home, capabilities: KEYLESS, skipHooksSmoke: true };
      expect(check((await verifyWorkspace(engine, ws, opts)).checks, 'roundtrip').filter((c) => !c.ok)).toEqual([]);
      await engine.executeRaw(`DROP TRIGGER w6634_keep ON page_purges`);
      await engine.executeRaw(`INSERT INTO page_purges SELECT * FROM w6634_kept`);
      const left = await engine.executeRaw<{ slug: string }>(`SELECT slug FROM page_purges WHERE source_id = 'workspace' AND slug = ANY($1::text[])`,
        [[VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG]]);
      expect(new Set(left.map((r) => r.slug))).toEqual(new Set([VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG]));
      const second = await verifyWorkspace(engine, ws, opts);
      expect(check(second.checks, 'roundtrip').filter((c) => !c.ok)).toEqual([]);
    } finally {
      await engine.executeRaw(`DROP TRIGGER IF EXISTS w6634_keep ON page_purges`);
      await engine.executeRaw(`DROP FUNCTION IF EXISTS w6634_keep()`);
      await engine.executeRaw(`DROP TABLE IF EXISTS w6634_kept`);
      await disposePersistenceConsumer(engine);
      await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    }
  }, 240_000);
});

describe('bootstrap verify write wait (#6356)', () => {
  test('the probe ctx waits as long as a CLI write: 30 s by default, GBRAIN_WRITE_WAIT_MS when set', async () => {
    const verify = await import('../src/core/bootstrap/verify.ts') as Record<string, unknown>;
    const localCtx = verify.localCtx as (engine: unknown, sourceId: string) => OperationContext;
    expect(typeof localCtx).toBe('function');
    const saved = process.env.GBRAIN_WRITE_WAIT_MS;
    try {
      delete process.env.GBRAIN_WRITE_WAIT_MS;
      expect(localCtx({}, 'default').writeWaitMs).toBe(30_000);
      process.env.GBRAIN_WRITE_WAIT_MS = '45000';
      expect(localCtx({}, 'default').writeWaitMs).toBe(45_000);
    } finally {
      if (saved === undefined) delete process.env.GBRAIN_WRITE_WAIT_MS; else process.env.GBRAIN_WRITE_WAIT_MS = saved;
    }
  });

  test('an admitted, still-pending probe write names its request and the poll command', async () => {
    const verify = await import('../src/core/bootstrap/verify.ts') as Record<string, unknown>;
    const detail = verify.putPageFailureDetail as (e: unknown, waitMs: number | undefined) => string;
    expect(typeof detail).toBe('function');
    const pending = { message: 'write pending', toJSON: () => ({ error: 'write_pending', write_request: { request_id: '0b6f6f0e-2c1a-4d8e-9f3a-5e2b7c9d1a44', state: 'queued', retry_after_ms: 1000 } }) };
    const text = detail(pending, 30_000);
    expect(text).toContain('still pending after 30s');
    expect(text).toContain('0b6f6f0e-2c1a-4d8e-9f3a-5e2b7c9d1a44');
    expect(text).toContain('gbrain write-request -- 0b6f6f0e-2c1a-4d8e-9f3a-5e2b7c9d1a44');
    expect(text).toContain('GBRAIN_WRITE_WAIT_MS');
    expect(detail(new Error('boom'), 30_000)).toBe('put_page failed: boom');
  });
});