Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
36.8 KB
Raw Blame
/**
 * The brain-first instruction block (src/core/setup/brain-first.ts): every
 * install lane writes one marked block into the harness's own instruction
 * file by default. Per writable harness this pins:
 *  - preservation: text outside the markers is byte-identical after install,
 *    upgrade and removal; the identity/persona text is never touched;
 *  - idempotence: a second run keeps the file byte-for-byte;
 *  - upgrade in place: a stale block is replaced, never duplicated;
 *  - opt-out: --no-instructions (or GBRAIN_AGENT_INSTRUCTIONS=0) removes the
 *    block and is remembered; --instructions opts back in;
 *  - removal: --remove strips the block and deletes only a file gbrain created;
 *  - dry-run writes nothing.
 * Spawns \`bun src/cli.ts setup\` against a temp HOME / GBRAIN_HOME.
 */
import { afterAll, describe, expect, test } from 'bun:test';
import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
import { load } from 'js-yaml';
import { runCli } from './helpers/cli-spawn.ts';
import { withEnv } from './helpers/with-env.ts';
import {
  BRAIN_FIRST_BEGIN,
  BRAIN_FIRST_END,
  renderBrainFirstBlock,
  renderBrainFirstSnippet,
  renderBrainFirstTurnRule,
} from '../src/core/setup/brain-first.ts';
import { harnessWiringCheck, instructionBlockViews, withInstructionBlocks, withSurfaceNote, type InstructionBlockView } from '../src/commands/doctor/checks/harness-wiring.ts';
import { installHarnessConnection } from '../src/core/harness/install.ts';
import { ensureHookLauncher, hookLauncherPath } from '../src/core/setup/hook-launcher.ts';
import type { HarnessCredentials } from '../src/core/harness/credentials.ts';

const CLI = resolve(import.meta.dir, '..', 'src', 'cli.ts');
const roots: string[] = [];
afterAll(() => { for (const r of roots) rmSync(r, { recursive: true, force: true }); });

interface Box { root: string; home: string; project: string; bin: string; env: Record<string, string | undefined> }

function box(): Box {
  const root = mkdtempSync(join(tmpdir(), 'gbrain-brain-first-'));
  roots.push(root);
  const home = join(root, 'home');
  const project = join(root, 'project');
  mkdirSync(home, { recursive: true });
  mkdirSync(project, { recursive: true });
  const bin = join(root, 'bin', 'gbrain');
  mkdirSync(join(root, 'bin'));
  writeFileSync(bin, `#!/bin/sh\nexec '${process.execPath}' --no-env-file '${CLI}' "$@"\n`);
  chmodSync(bin, 0o755);
  return { root, home, project, bin, env: {
    HOME: home, GBRAIN_HOME: home, CLAUDE_CONFIG_DIR: undefined, CODEX_HOME: undefined, XDG_CONFIG_HOME: undefined,
    OPENCLAW_STATE_DIR: undefined, OPENCLAW_WORKSPACE_DIR: undefined, OPENCLAW_PROFILE: undefined, HERMES_HOME: undefined,
    GBRAIN_AGENT_INSTRUCTIONS: undefined, GBRAIN_SURFACE: undefined, GBRAIN_SOURCE: undefined, GBRAIN_HOOKS: undefined,
  } };
}

async function setup(b: Box, args: string[], env: Record<string, string | undefined> = {}) {
  const r = await runCli(['setup', ...args, '--json'], { env: { ...b.env, ...env }, cwd: b.project });
  let doc: any = null;
  try { doc = JSON.parse(r.stdout); } catch { doc = null; }
  return { ...r, doc };
}

const read = (p: string) => readFileSync(p, 'utf8');
const blocks = (text: string) => text.split('\n').filter((l) => l === BRAIN_FIRST_BEGIN).length;
const ledger = (b: Box) => JSON.parse(read(join(b.home, '.gbrain', 'agent-instructions.json'))).entries as any[];

/** refusesCreate: a missing file is never created (Hermes uses a non-empty SOUL.md instead of its default identity). */
interface Lane { harness: string; file: (b: Box) => string; args?: string[]; prepare?: (b: Box) => void; existing: string; refusesCreate?: boolean }

const LANES: Lane[] = [
  { harness: 'claude-code', file: (b) => join(b.home, '.claude', 'CLAUDE.md'), args: ['--instructions-only'], existing: '# My rules\n\nAlways answer in French.\n' },
  { harness: 'codex', file: (b) => join(b.home, '.codex', 'AGENTS.md'), args: ['--instructions-only'], existing: '# Codex house rules\n- run the tests\n' },
  { harness: 'opencode', file: (b) => join(b.home, '.config', 'opencode', 'AGENTS.md'), existing: 'Prefer small diffs.\n' },
  { harness: 'openclaw', file: (b) => join(b.home, '.openclaw', 'workspace', 'AGENTS.md'), existing: '# AGENTS.md\n\n## Tools\nUse the calendar skill.\n' },
  { harness: 'hermes', file: (b) => join(b.home, '.hermes', 'SOUL.md'), existing: 'You are Hermes, a careful assistant named alice-example.\n', refusesCreate: true },
  { harness: 'cursor', file: (b) => join(b.project, '.cursor', 'rules', 'gbrain-brain-first.mdc'), existing: '---\ndescription: team rule\nalwaysApply: true\n---\nUse tabs.\n' },
];

for (const lane of LANES) {
  describe(`brain-first block: ${lane.harness}`, () => {
    const run = (b: Box, extra: string[] = [], env: Record<string, string | undefined> = {}) => setup(b, [lane.harness, ...(lane.args ?? []), ...extra], env);

    test('default install appends the block after the existing text, which stays byte-identical; a re-run keeps the file', async () => {
      const b = box();
      const path = lane.file(b);
      mkdirSync(dirname(path), { recursive: true });
      writeFileSync(path, lane.existing);
      const first = await run(b);
      expect(first.exitCode).toBe(0);
      expect(first.doc.instructions).toMatchObject({ action: 'write', path, decision: { value: 'accepted', source: 'default' } });
      const text = read(path);
      expect(text.startsWith(lane.existing)).toBe(true);
      expect(blocks(text)).toBe(1);
      expect(text).toContain('Before answering any turn, check GBrain first, before files, mail or other sources');
      expect(text).toContain('apply your own access rules');
      expect(text).toContain('finish the whole task');
      expect(ledger(b)).toEqual([expect.objectContaining({ harness: lane.harness, path, status: 'installed', created_file: false })]);

      const second = await run(b);
      expect(second.doc.instructions.action).toBe('keep');
      expect(read(path)).toBe(text);
    });

    test('a stale block is upgraded in place: one block, outside text untouched before and after it', async () => {
      const b = box();
      const path = lane.file(b);
      mkdirSync(dirname(path), { recursive: true });
      const tail = '\n## Notes after the block\nkeep me\n';
      writeFileSync(path, `${lane.existing}${BRAIN_FIRST_BEGIN}\n<!-- gbrain brain-first v0 -->\nold advice\n${BRAIN_FIRST_END}\n${tail}`);
      const r = await run(b);
      expect(r.doc.instructions).toMatchObject({ action: 'write', state_before: 'stale' });
      const text = read(path);
      expect(blocks(text)).toBe(1);
      expect(text).not.toContain('old advice');
      expect(text.startsWith(lane.existing)).toBe(true);
      expect(text.endsWith(tail)).toBe(true);
    });

    test('--no-instructions removes the block and is remembered; GBRAIN_AGENT_INSTRUCTIONS=0 never writes; --instructions opts back in', async () => {
      const b = box();
      const path = lane.file(b);
      mkdirSync(dirname(path), { recursive: true });
      writeFileSync(path, lane.existing);
      await run(b);
      const out = await run(b, ['--no-instructions']);
      expect(out.doc.instructions).toMatchObject({ action: 'remove', decision: { value: 'declined', source: 'flag' } });
      expect(read(path)).toBe(lane.existing);
      expect(ledger(b)[0]).toMatchObject({ status: 'declined' });
      const again = await run(b);
      expect(again.doc.instructions).toMatchObject({ action: 'skip', decision: { value: 'declined', source: 'prior' } });
      expect(read(path)).toBe(lane.existing);
      const back = await run(b, ['--instructions']);
      expect(back.doc.instructions).toMatchObject({ action: 'write', decision: { value: 'accepted', source: 'flag' } });

      const fresh = box();
      const env = await run(fresh, [], { GBRAIN_AGENT_INSTRUCTIONS: '0' });
      expect(env.doc.instructions).toMatchObject({ action: 'skip', decision: { value: 'declined', source: 'opt_out' } });
      expect(existsSync(lane.file(fresh))).toBe(false);
    });

    test('--remove strips the block, leaves the user text exactly as it was, and deletes only a file gbrain created', async () => {
      const b = box();
      const path = lane.file(b);
      mkdirSync(dirname(path), { recursive: true });
      writeFileSync(path, lane.existing);
      await run(b);
      const rm = await run(b, ['--remove']);
      expect(rm.doc.instructions.action).toBe('remove');
      expect(read(path)).toBe(lane.existing);

      const created = box();
      const write = await run(created);
      if (lane.refusesCreate) {
        expect(write.doc.instructions.action).toBe('skip');
        expect(existsSync(lane.file(created))).toBe(false);
        return;
      }
      expect(write.doc.instructions.detail).toContain('new file');
      expect(existsSync(lane.file(created))).toBe(true);
      await run(created, ['--remove']);
      expect(existsSync(lane.file(created))).toBe(false);
    });

    test('--dry-run reports the write and changes nothing', async () => {
      const b = box();
      const r = await run(b, ['--dry-run']);
      expect(r.exitCode).toBe(0);
      expect(r.doc.instructions).toMatchObject({ action: lane.refusesCreate ? 'skip' : 'write', state_before: 'no_file' });
      expect(existsSync(lane.file(b))).toBe(false);
      expect(existsSync(join(b.home, '.gbrain', 'agent-instructions.json'))).toBe(false);
    });
  });
}

describe('brain-first block: placement rules', () => {
  test('codex: AGENTS.override.md wins when it exists (Codex ignores AGENTS.md then)', async () => {
    const b = box();
    mkdirSync(join(b.home, '.codex'), { recursive: true });
    writeFileSync(join(b.home, '.codex', 'AGENTS.override.md'), 'override rules\n');
    const r = await setup(b, ['codex', '--instructions-only']);
    expect(r.doc.instructions.path).toBe(join(b.home, '.codex', 'AGENTS.override.md'));
    expect(existsSync(join(b.home, '.codex', 'AGENTS.md'))).toBe(false);
  });

  test('codex: an empty AGENTS.override.md is skipped, as Codex skips it, so the block lands in AGENTS.md', async () => {
    const b = box();
    mkdirSync(join(b.home, '.codex'), { recursive: true });
    writeFileSync(join(b.home, '.codex', 'AGENTS.override.md'), '\n');
    const r = await setup(b, ['codex', '--instructions-only']);
    expect(r.doc.instructions.path).toBe(join(b.home, '.codex', 'AGENTS.md'));
    expect(read(join(b.home, '.codex', 'AGENTS.override.md'))).toBe('\n');
  });

  test('openclaw: OPENCLAW_CONFIG_PATH is read, a sole agent\'s own workspace wins, single-quoted JSON5 parses', async () => {
    const b = box();
    const cfg = join(b.root, 'custom', 'openclaw.json');
    mkdirSync(dirname(cfg), { recursive: true });
    writeFileSync(cfg, "{ agents: { defaults: { workspace: '~/default-ws' }, list: [{ id: 'main', workspace: '~/main-ws' }] } }\n");
    const r = await setup(b, ['openclaw'], { OPENCLAW_CONFIG_PATH: cfg });
    expect(r.doc.instructions.path).toBe(join(b.home, 'main-ws', 'AGENTS.md'));
  });

  test('claude-code --scope project writes CLAUDE.local.md and keeps it out of git', async () => {
    const b = box();
    const git = Bun.spawnSync(['git', 'init', '-q', b.project]);
    expect(git.exitCode).toBe(0);
    const r = await setup(b, ['claude-code', '--instructions-only', '--scope', 'project']);
    expect(r.doc.instructions.path).toBe(join(b.project, 'CLAUDE.local.md'));
    expect(read(join(b.project, '.git', 'info', 'exclude'))).toContain('/CLAUDE.local.md');
  });

  test('openclaw: agents.defaults.workspace in JSON5 config is honored; a multi-agent roster needs --workspace', async () => {
    const b = box();
    mkdirSync(join(b.home, '.openclaw'), { recursive: true });
    writeFileSync(join(b.home, '.openclaw', 'openclaw.json'), '{ agents: { defaults: { workspace: "~/agent-ws" } } }\n');
    const r = await setup(b, ['openclaw']);
    expect(r.doc.instructions.path).toBe(join(b.home, 'agent-ws', 'AGENTS.md'));
    writeFileSync(join(b.home, '.openclaw', 'openclaw.json'), '{ agents: { list: [{ id: "a" }, { id: "b" }] } }\n');
    const multi = await setup(b, ['openclaw']);
    expect(multi.exitCode).toBe(2);
    expect(multi.doc.code).toBe('invalid_params');
    const named = await setup(b, ['openclaw', '--workspace', join(b.home, 'ws-b')]);
    expect(named.doc.instructions.path).toBe(join(b.home, 'ws-b', 'AGENTS.md'));
  });

  test('hermes: the identity text in SOUL.md stays first and unchanged', async () => {
    const b = box();
    mkdirSync(join(b.home, '.hermes'), { recursive: true });
    const soul = 'You are Hermes.\nTone: dry.\n';
    writeFileSync(join(b.home, '.hermes', 'SOUL.md'), soul);
    await setup(b, ['hermes']);
    expect(read(join(b.home, '.hermes', 'SOUL.md')).startsWith(soul)).toBe(true);
  });

  test('hermes: setup adds the pre_llm_call hook that carries the rule on every turn; the opt-out and --remove take it out', async () => {
    const b = box();
    mkdirSync(join(b.home, '.hermes'), { recursive: true });
    writeFileSync(join(b.home, '.hermes', 'SOUL.md'), 'You are Hermes.\n');
    writeFileSync(join(b.home, '.hermes', 'config.yaml'), 'model:\n  default: x\n');
    const config = () => read(join(b.home, '.hermes', 'config.yaml'));
    const first = await setup(b, ['hermes', '--gbrain-bin', b.bin]);
    expect(first.doc.turn_hook).toMatchObject({ action: 'write', path: join(b.home, '.hermes', 'config.yaml') });
    const hook = (load(config()) as any).hooks.pre_llm_call[0];
    expect(hook.command.startsWith("/bin/echo '")).toBe(true);
    expect(JSON.parse(hook.command.slice("/bin/echo '".length, -1)).context).toContain('check GBrain first');
    expect(read(join(b.home, '.hermes', 'SOUL.md'))).toContain(BRAIN_FIRST_BEGIN);
    const declined = await setup(b, ['hermes', '--no-instructions']);
    expect(declined.doc.turn_hook.action).toBe('remove');
    expect(config()).toBe('model:\n  default: x\n');
    await setup(b, ['hermes', '--instructions', '--gbrain-bin', b.bin]);
    expect(config()).toContain('pre_llm_call');
    expect((await setup(b, ['hermes', '--remove'])).doc.turn_hook.action).toBe('remove');
    expect(config()).toBe('model:\n  default: x\n');
  });

  test('openclaw: setup writes the before_prompt_build plugin and installs it with the openclaw CLI; the opt-out and --remove uninstall it', async () => {
    const b = box();
    mkdirSync(join(b.home, '.openclaw', 'workspace'), { recursive: true });
    const log = join(b.root, 'openclaw.log');
    writeFileSync(join(b.root, 'bin', 'openclaw'), `#!/bin/sh\necho "$*" >> '${log}'\n`);
    chmodSync(join(b.root, 'bin', 'openclaw'), 0o755);
    const path = { PATH: `${join(b.root, 'bin')}:${process.env.PATH ?? ''}` };
    const dir = join(b.home, '.openclaw', 'gbrain', 'gbrain-turn-rule');
    const first = await setup(b, ['openclaw'], path);
    expect(first.doc.turn_hook).toMatchObject({ action: 'write', path: dir });
    expect(read(join(dir, 'index.js'))).toContain('before_prompt_build');
    expect(read(log).trim().split('\n')).toEqual([
      `plugins install --link ${dir} --force --accept-capabilities`,
      'plugins enable gbrain-turn-rule',
      'config set plugins.entries.gbrain-turn-rule.hooks.allowConversationAccess true',
    ]);
    const declined = await setup(b, ['openclaw', '--no-instructions'], path);
    expect(declined.doc.turn_hook.action).toBe('remove');
    expect(existsSync(dir)).toBe(false);
    expect(read(log).trim().split('\n').at(-1)).toBe('plugins uninstall gbrain-turn-rule --force');
    await setup(b, ['openclaw', '--instructions'], path);
    expect(existsSync(dir)).toBe(true);
    expect((await setup(b, ['openclaw', '--remove'], path)).doc.turn_hook.action).toBe('remove');
    expect(existsSync(join(b.home, '.openclaw', 'gbrain'))).toBe(false);
  });

  /** A fake openclaw CLI: `config set` enables the plugin in openclaw.json (as enable + config set do), `plugins inspect` reports it loaded. */
  function fakeOpenclaw(b: Box): Record<string, string> {
    const cfg = join(b.home, '.openclaw', 'openclaw.json');
    const enabled = JSON.stringify({ plugins: { entries: { 'gbrain-turn-rule': { enabled: true, hooks: { allowConversationAccess: true } } } } });
    writeFileSync(join(b.root, 'bin', 'openclaw'), [
      '#!/bin/sh',
      `case "$*" in "config set"*) printf '%s' '${enabled}' > '${cfg}';; "plugins inspect"*) echo '{"id":"gbrain-turn-rule","status":"loaded","imported":true,"hooks":["before_prompt_build"]}';; esac`,
      'exit 0',
      '',
    ].join('\n'));
    chmodSync(join(b.root, 'bin', 'openclaw'), 0o755);
    return { PATH: `${join(b.root, 'bin')}:${process.env.PATH ?? ''}` };
  }

  test('openclaw --workspace: the gateway-shared plugin is not rewritten for another server name or removed by one workspace opting out', async () => {
    const b = box();
    mkdirSync(join(b.home, '.openclaw', 'workspace'), { recursive: true });
    const path = fakeOpenclaw(b);
    const dir = join(b.home, '.openclaw', 'gbrain', 'gbrain-turn-rule');
    const first = await setup(b, ['openclaw'], path);
    expect(first.exitCode).toBe(0);
    expect(first.doc.turn_hook_check.ok).toBe(true);
    const index = read(join(dir, 'index.js'));
    const ws = join(b.home, 'ws-a');
    mkdirSync(ws);
    const renamed = await setup(b, ['openclaw', '--workspace', ws, '--name', 'gbrain-a', '--instructions-only'], path);
    expect(renamed.exitCode).toBe(0);
    expect(renamed.doc.turn_hook.action).toBe('print');
    expect(renamed.doc.turn_hook.commands).toEqual([`gbrain setup openclaw --remove --workspace ${ws}`]);
    expect(read(join(dir, 'index.js'))).toBe(index);
    const declined = await setup(b, ['openclaw', '--workspace', ws, '--no-instructions'], path);
    expect(declined.exitCode).toBe(0);
    expect(declined.doc.instructions.action).toBe('remove');
    expect(declined.doc.turn_hook.action).toBe('skip');
    expect(read(join(dir, 'index.js'))).toBe(index);
    expect(read(join(b.home, '.openclaw', 'workspace', 'AGENTS.md'))).toContain(BRAIN_FIRST_BEGIN);
  });

  test('openclaw --workspace on a disabled plugin an older gbrain wrote: another server exits 0 with the way out, the same server rewrites and enables it', async () => {
    const b = box();
    mkdirSync(join(b.home, '.openclaw', 'workspace'), { recursive: true });
    const path = fakeOpenclaw(b);
    const dir = join(b.home, '.openclaw', 'gbrain', 'gbrain-turn-rule');
    mkdirSync(dir, { recursive: true });
    writeFileSync(join(dir, 'package.json'), `${JSON.stringify({ name: 'gbrain-turn-rule', version: '1.0.0', private: true, type: 'module', openclaw: { extensions: ['./index.js'] } }, null, 2)}\n`);
    writeFileSync(join(dir, 'index.js'), [`const RULE = ${JSON.stringify(renderBrainFirstTurnRule({ kind: 'mcp', server: 'gbrain' }, 'openclaw'))};`, 'export default {', "  id: 'gbrain-turn-rule',", '  register(api) {', "    api.on('before_prompt_build', () => ({ prependContext: RULE }));", '  },', '};', ''].join('\n'));
    writeFileSync(join(b.home, '.openclaw', 'openclaw.json'), JSON.stringify({ plugins: { entries: { 'gbrain-turn-rule': { enabled: false } } } }));
    const ws = join(b.home, 'ws-a');
    mkdirSync(ws);
    for (let i = 0; i < 2; i++) {
      const other = await setup(b, ['openclaw', '--workspace', ws, '--name', 'gbrain-a', '--instructions-only'], path);
      expect(other.exitCode).toBe(0);
      expect(other.doc.turn_hook.action).toBe('print');
    }
    const same = await setup(b, ['openclaw', '--workspace', ws, '--instructions-only'], path);
    expect(same.exitCode).toBe(0);
    expect(same.doc.turn_hook.action).toBe('write');
    expect(same.doc.turn_hook_check.ok).toBe(true);
    expect(JSON.parse(read(join(dir, 'package.json'))).gbrain).toEqual({ access: { kind: 'mcp', server: 'gbrain' } });
  });

  test('a damaged block is preserved and reported, never guessed through', async () => {
    const b = box();
    const path = join(b.home, '.claude', 'CLAUDE.md');
    mkdirSync(dirname(path), { recursive: true });
    const damaged = `mine\n${BRAIN_FIRST_BEGIN}\nhalf a block\n`;
    writeFileSync(path, damaged);
    const r = await setup(b, ['claude-code', '--instructions-only']);
    expect(r.exitCode).toBe(1);
    expect(r.doc.instructions).toMatchObject({ action: 'preserve', state_before: 'damaged' });
    expect(read(path)).toBe(damaged);
  });

  test('a client with no writable instruction file gets the block printed to paste', async () => {
    const b = box();
    const r = await setup(b, ['chatgpt', '--instructions-only']);
    expect(r.exitCode).toBe(0);
    expect(r.doc.instructions.action).toBe('print');
    // Nothing on disk to remove, so the opt-out is deleting the pasted block.
    expect(r.doc.instructions.snippet).toBe(renderBrainFirstSnippet('chatgpt', { kind: 'mcp', server: 'gbrain' }, 'delete this block'));
    // A thin-CLI client gets the CLI-flavored block with the launcher it calls.
    const bot = await setup(b, ['grok-bot', '--instructions-only', '--gbrain-bin', '/opt/example/bin/gbrain']);
    expect(bot.exitCode).toBe(0);
    expect(bot.doc.instructions.snippet).toBe(renderBrainFirstSnippet('grok-bot', { kind: 'cli', launcher: '/opt/example/bin/gbrain' }, 'delete this block'));
  });
});

describe('brain-first block: hardening', () => {
  test('a CRLF or BOM file keeps one block: upgraded in place, then removed by the opt-out', async () => {
    const b = box();
    const path = join(b.home, '.claude', 'CLAUDE.md');
    mkdirSync(dirname(path), { recursive: true });
    const stale = renderBrainFirstSnippet('claude-code', { kind: 'mcp', server: 'gbrain' }).replace('finish the whole task', 'stop');
    writeFileSync(path, `\uFEFFrules\r\n${stale.replace(/\n/g, '\r\n')}tail\r\n`);
    const up = await setup(b, ['claude-code', '--instructions-only']);
    expect(up.doc.instructions).toMatchObject({ action: 'write', state_before: 'stale' });
    expect(read(path).split('\n').filter((l) => l.replace(/\r$/, '') === BRAIN_FIRST_BEGIN)).toHaveLength(1);
    expect(read(path).startsWith('\uFEFFrules\r\n')).toBe(true);
    expect(read(path).endsWith('tail\r\n')).toBe(true);
    const off = await setup(b, ['claude-code', '--instructions-only', '--no-instructions']);
    expect(off.doc.instructions.action).toBe('remove');
    expect(read(path)).toBe('\uFEFFrules\r\ntail\r\n');
  });

  test('a dangling symlink is followed and never deleted on removal', async () => {
    const b = box();
    const real = join(b.root, 'dotfiles', 'CLAUDE.md');
    mkdirSync(dirname(real), { recursive: true });
    mkdirSync(join(b.home, '.claude'), { recursive: true });
    symlinkSync(real, join(b.home, '.claude', 'CLAUDE.md'));
    await setup(b, ['claude-code', '--instructions-only']);
    expect(blocks(read(real))).toBe(1);
    expect(ledger(b)[0].created_file).toBe(false);
    await setup(b, ['claude-code', '--instructions-only', '--remove']);
    expect(lstatSync(join(b.home, '.claude', 'CLAUDE.md')).isSymbolicLink()).toBe(true);
    expect(read(real)).toBe('');
  });

  test('an opt-out survives the Codex target moving to a non-empty AGENTS.override.md; doctor follows the move', async () => {
    const b = box();
    await setup(b, ['codex', '--instructions-only']);
    writeFileSync(join(b.home, '.codex', 'AGENTS.override.md'), 'override rules\n');
    await withEnv({ ...b.env, CODEX_HOME: join(b.home, '.codex') }, async () => {
      expect(instructionBlockViews([])).toEqual([expect.objectContaining({ harness: 'codex', path: join(b.home, '.codex', 'AGENTS.override.md'), state: 'missing' })]);
    });
    await setup(b, ['codex', '--instructions-only', '--no-instructions']);
    writeFileSync(join(b.home, '.codex', 'AGENTS.override.md'), 'new override\n');
    rmSync(join(b.home, '.codex', 'AGENTS.md'), { force: true });
    writeFileSync(join(b.home, '.codex', 'AGENTS.override.md'), 'newer override\n');
    const again = await setup(b, ['codex', '--instructions-only']);
    expect(again.doc.instructions.decision.value).toBe('declined');
    expect(read(join(b.home, '.codex', 'AGENTS.override.md'))).toBe('newer override\n');
  });

  test('doctor\'s repair names the recorded connection and surface; a project file is the user\'s to run in place', () => {
    const views: InstructionBlockView[] = [{ harness: 'codex', path: '/x/.codex/AGENTS.md', state: 'stale', from: 'ledger', access: { kind: 'mcp', server: 'work-brain', surface: 'verbs' } }];
    const c = withInstructionBlocks({ name: 'harness_wiring', status: 'ok', message: 'wired.' }, views);
    expect(c.fix?.argv).toEqual(['gbrain', 'setup', 'codex', '--instructions-only', '--name', 'work-brain', '--surface', 'verbs']);
    const project = withInstructionBlocks({ name: 'harness_wiring', status: 'ok', message: 'wired.' }, [{ harness: 'cursor', path: '/repo/.cursor/rules/gbrain-brain-first.mdc', state: 'missing', from: 'ledger' }]);
    expect(project.fix?.argv).toBeUndefined();
    expect(project.fix?.user_message).toContain('From /repo, run: gbrain setup cursor --instructions-only');
  });
});

describe('doctor harness_wiring: a full registration is information only', () => {
  test('a stdio registration pinned to --surface full gets a note; status and fix are unchanged; starter or a GBRAIN_SURFACE override gets none', () => {
    const ok = { name: 'harness_wiring', status: 'ok' as const, message: 'wired.' };
    const full = withSurfaceNote(ok, [{ harness: 'codex', source: '/x/config.toml', kind: 'stdio', command: '/bin/gbrain', args: ['serve', '--surface', 'full'] }]);
    expect(full.status).toBe('ok');
    expect(full.fix).toBeUndefined();
    expect(String(full.details?.surface_note)).toContain('Codex registered with --surface full, which stays supported');
    expect(withSurfaceNote(ok, [{ harness: 'codex', source: '/x', kind: 'stdio', args: ['serve', '--surface', 'starter'] }])).toEqual(ok);
    expect(withSurfaceNote(ok, [{ harness: 'codex', source: '/x', kind: 'stdio', args: ['serve', '--surface', 'full'], env: { GBRAIN_SURFACE: 'starter' } }])).toEqual(ok);
  });
});

describe('brain-first block: text', () => {
  test('names the tools the surface lists: search/query/get_page, recall/entity on verbs, the CLI on a thin client', () => {
    const full = renderBrainFirstBlock('codex', { kind: 'mcp', server: 'gbrain', surface: 'full' });
    expect(full).toContain('`search`');
    expect(full).toContain('`get_page`');
    const verbs = renderBrainFirstBlock('codex', { kind: 'mcp', server: 'gbrain', surface: 'verbs' });
    expect(verbs).toContain('`recall`');
    expect(verbs).not.toContain('get_page');
    const cli = renderBrainFirstBlock('openclaw', { kind: 'cli', launcher: '/opt/agent/bin/gbrain' });
    expect(cli).toContain('`/opt/agent/bin/gbrain search');
    expect(cli).toContain('`/opt/agent/bin/gbrain get <slug>`');
  });

  test('stays short: it loads into every turn', () => {
    const words = renderBrainFirstBlock('claude-code', { kind: 'mcp', server: 'gbrain', surface: 'full' }).split(/\s+/).length;
    expect(words).toBeLessThan(160);
  });
});

describe('brain-first block: full setup and the installer lanes', () => {
  test('gbrain setup claude-code writes the block by default; --remove takes it out with the MCP entry', async () => {
    const b = box();
    const first = await runCli(['setup', 'claude-code', '--json', '--gbrain-bin', b.bin], { env: b.env });
    expect(first.exitCode).toBe(0);
    const doc = JSON.parse(first.stdout);
    expect(doc.instructions).toMatchObject({ action: 'write', path: join(b.home, '.claude', 'CLAUDE.md') });
    expect(read(join(b.home, '.claude', 'CLAUDE.md'))).toContain('the `gbrain` MCP server');
    expect(read(join(b.home, '.claude', 'CLAUDE.md'))).toContain('`recall` for what was said or decided');
    const second = JSON.parse((await runCli(['setup', 'claude-code', '--json', '--gbrain-bin', b.bin], { env: b.env })).stdout);
    expect(second.steps.map((s: any) => s.action)).toEqual(['keep', 'keep', 'keep']);
    expect(second.instructions.action).toBe('keep');
    const rm = JSON.parse((await runCli(['setup', 'claude-code', '--remove', '--json', '--gbrain-bin', b.bin], { env: b.env })).stdout);
    expect(rm.instructions.action).toBe('remove');
    expect(existsSync(join(b.home, '.claude', 'CLAUDE.md'))).toBe(false);
  });

  test('the block names the tools the registration lists: recall on the default verbs listing, search on an explicit --surface full', async () => {
    const b = box();
    expect((await runCli(['setup', 'codex', '--json', '--gbrain-bin', b.bin], { env: b.env })).exitCode).toBe(0);
    expect(read(join(b.home, '.codex', 'AGENTS.md'))).toContain('`recall` for what was said or decided');
    const c = box();
    expect((await runCli(['setup', 'codex', '--surface', 'full', '--json', '--gbrain-bin', c.bin], { env: c.env })).exitCode).toBe(0);
    expect(read(join(c.home, '.codex', 'AGENTS.md'))).toContain('`search` for names and phrases');
  });

  test('gbrain setup codex --no-instructions wires MCP and hooks but no block', async () => {
    const b = box();
    const r = await runCli(['setup', 'codex', '--no-instructions', '--json', '--gbrain-bin', b.bin], { env: b.env });
    expect(r.exitCode).toBe(0);
    expect(JSON.parse(r.stdout).instructions).toMatchObject({ action: 'skip', decision: { value: 'declined' } });
    expect(existsSync(join(b.home, '.codex', 'AGENTS.md'))).toBe(false);
  });

  const credentials: HarnessCredentials = { version: 1, mcp_url: 'https://brain.example.com/mcp', issuer_url: 'https://brain.example.com', client_id: 'gbrain_cl_fixture', client_secret: 'fixture-secret-not-real', access_token: 'fixture-token-not-real' };

  for (const [harness, config, instructions] of [
    ['claude-code', '.claude.json', join('.claude', 'CLAUDE.md')],
    ['codex', join('.codex', 'config.toml'), join('.codex', 'AGENTS.md')],
    ['opencode', join('.config', 'opencode', 'opencode.jsonc'), join('.config', 'opencode', 'AGENTS.md')],
  ] as const) {
    test(`connect --install (${harness}) writes the block beside its config; --remove and instructions:false take it out`, async () => {
      const b = box();
      await withEnv(b.env, async () => {
        const configPath = join(b.home, config);
        const instructionPath = join(b.home, instructions);
        mkdirSync(dirname(instructionPath), { recursive: true });
        writeFileSync(instructionPath, 'house rules\n');
        const installed = await installHarnessConnection(credentials, { harness, configPath });
        expect((installed as any).instructions).toMatchObject({ action: 'write', path: instructionPath });
        expect(blocks(read(instructionPath))).toBe(1);
        const again = await installHarnessConnection(credentials, { harness, configPath });
        expect((again as any).instructions.action).toBe('keep');
        const optedOut = await installHarnessConnection(credentials, { harness, configPath, instructions: false });
        expect((optedOut as any).instructions.action).toBe('remove');
        expect(read(instructionPath)).toBe('house rules\n');
        await installHarnessConnection(credentials, { harness, configPath, instructions: true });
        const removed = await installHarnessConnection(credentials, { harness, configPath, remove: true });
        expect((removed as any).instructions.action).toBe('remove');
        expect(read(instructionPath)).toBe('house rules\n');
      });
    });
  }

  test('removing one connection leaves the block another connection last wrote', async () => {
    const b = box();
    await withEnv(b.env, async () => {
      const configPath = join(b.home, '.claude.json');
      const instructionPath = join(b.home, '.claude', 'CLAUDE.md');
      await installHarnessConnection(credentials, { harness: 'claude-code', configPath, name: 'alpha' });
      await installHarnessConnection({ ...credentials, client_id: 'client-beta' }, { harness: 'claude-code', configPath, name: 'beta' });
      expect(read(instructionPath)).toContain('`beta` MCP server');
      const removed = await installHarnessConnection(credentials, { harness: 'claude-code', configPath, name: 'alpha', remove: true });
      expect((removed as any).instructions.action).toBe('skip');
      expect(read(instructionPath)).toContain('`beta` MCP server');
    });
  });

  test('thin-client opt-out: GBRAIN_AGENT_INSTRUCTIONS=0 writes no block, and --no-instructions is kept on the next install', async () => {
    const b = box();
    const envRoot = join(b.root, 'thin-env');
    await withEnv({ ...b.env, GBRAIN_AGENT_INSTRUCTIONS: '0' }, async () => {
      await installHarnessConnection(credentials, { harness: 'openclaw', root: envRoot });
    });
    expect(read(join(envRoot, 'GBRAIN-INSTRUCTIONS.md'))).not.toContain(BRAIN_FIRST_BEGIN);
    const root = join(b.root, 'thin-flag');
    await withEnv(b.env, async () => {
      await installHarnessConnection(credentials, { harness: 'openclaw', root, instructions: false });
      await installHarnessConnection(credentials, { harness: 'openclaw', root });
    });
    expect(read(join(root, 'GBRAIN-INSTRUCTIONS.md'))).not.toContain(BRAIN_FIRST_BEGIN);
  });

  test('thin-client install (OpenClaw) puts the CLI-flavored block first in GBRAIN-INSTRUCTIONS.md', async () => {
    const b = box();
    const root = join(b.root, 'thin');
    await withEnv(b.env, async () => {
      await installHarnessConnection(credentials, { harness: 'openclaw', root });
    });
    const text = read(join(root, 'GBRAIN-INSTRUCTIONS.md'));
    expect(text.startsWith(BRAIN_FIRST_BEGIN)).toBe(true);
    expect(text).toContain(`\`${join(root, 'bin', 'gbrain')} search`);
  });
});

describe('doctor harness_wiring reports the block', () => {
  /** A current stdio registration: serve behind gbrain's hook launcher, the shape setup writes (#8426). */
  function stdioRegistration(b: Box): void {
    const launcher = ensureHookLauncher(hookLauncherPath(join(b.home, '.gbrain')));
    writeFileSync(join(b.home, '.claude.json'), JSON.stringify({ mcpServers: { gbrain: { type: 'stdio', command: launcher, args: [b.bin, 'serve'] } } }));
  }
  const env = (b: Box) => ({ ...b.env, CLAUDECODE: undefined, CLAUDE_CODE_ENTRYPOINT: undefined, CODEX_SANDBOX: undefined, CODEX_CI: undefined, OPENCODE: undefined, OPENCODE_PID: undefined });

  test('a registration without the block warns, with a fix that writes only the block; current reads ok', async () => {
    const b = box();
    stdioRegistration(b);
    await withEnv(env(b), async () => {
      const missing = await harnessWiringCheck({ smoke: false });
      expect(missing.status).toBe('warn');
      expect(missing.details?.instructions).toEqual([{ harness: 'claude-code', path: join(b.home, '.claude', 'CLAUDE.md'), state: 'missing', from: 'default_path' }]);
      expect(missing.fix?.argv).toEqual(['gbrain', 'setup', 'claude-code', '--instructions-only']);
    });
    await setup(b, ['claude-code', '--instructions-only', '--gbrain-bin', b.bin]);
    await withEnv(env(b), async () => {
      const current = await harnessWiringCheck({ smoke: false });
      expect(current.status).toBe('ok');
      expect(current.message).toContain('Brain-first instructions current for claude-code.');
      expect(current.details?.instructions).toEqual([expect.objectContaining({ state: 'current', from: 'ledger' })]);
    });
  });

  test('a recorded block whose per-turn hook is missing warns turn_hook_not_loaded, naming the native check; the re-run clears it', async () => {
    const b = box();
    stdioRegistration(b);
    await setup(b, ['claude-code', '--instructions-only']);
    await withEnv(env(b), async () => {
      const c = await harnessWiringCheck({ smoke: false });
      expect(c.status).toBe('warn');
      expect(c.details).toMatchObject({ code: 'turn_hook_not_loaded', turn_hook_reason: 'missing' });
      expect(c.message).toContain('/hooks (inside a Claude Code session)');
      expect(c.fix?.argv).toEqual(['gbrain', 'setup', 'claude-code', '--instructions-only']);
      expect(c.fix?.verify).toEqual({ argv: ['gbrain', 'doctor', '--only', 'harness_wiring', '--json'] });
    });
    await setup(b, ['claude-code', '--instructions-only', '--gbrain-bin', b.bin]);
    await withEnv(env(b), async () => {
      const c = await harnessWiringCheck({ smoke: false });
      expect(c.status).toBe('ok');
      expect(c.details?.turn_hooks).toEqual([expect.objectContaining({ harness: 'claude-code', state: 'wired', via: 'turn-rule' })]);
    });
  });

  test('a hand-edited (stale) block warns; an opt-out is reported, never warned on', async () => {
    const b = box();
    stdioRegistration(b);
    await setup(b, ['claude-code', '--instructions-only']);
    const path = join(b.home, '.claude', 'CLAUDE.md');
    writeFileSync(path, read(path).replace('finish the whole task', 'stop after the lookup'));
    await withEnv(env(b), async () => {
      const stale = await harnessWiringCheck({ smoke: false });
      expect(stale.status).toBe('warn');
      expect(stale.message).toContain('is out of date');
    });
    await setup(b, ['claude-code', '--instructions-only', '--no-instructions']);
    await withEnv(env(b), async () => {
      const opted = await harnessWiringCheck({ smoke: false });
      expect(opted.status).toBe('ok');
      expect(opted.details?.instructions).toEqual([expect.objectContaining({ state: 'opted_out' })]);
    });
  });
});