Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* E2E: `gbrain bootstrap harness` lifecycle against a REAL `serve --http` on
* a hermetic PGLite brain (#4043).
*
* The real seams the unit suite injects away: an actual /health probe, the
* actual StreamableHTTP + bearer smoke (probeBrainIdentity), the PGLite
* single-writer reality (mint refused under a live serve → the --token lane
* is the documented escape), and the dispatcher path (runBootstrap →
* home-lock → apply/status/remove) with real receipt/install-log files.
*
* The claude CLI is a recording fake (runBootstrap's runner seam); the codex
* lane writes the real managed TOML block into a temp CODEX_HOME; HOME is
* remapped so user-scope writes land in the sandbox.
*
* Serial: env remapping (HOME / CODEX_HOME / GBRAIN_HOME) + a spawned serve.
*
* Lane: serial. Run: `bash scripts/run-serial-tests.sh test/bootstrap-harness-lifecycle.serial.test.ts`. Moved from test/e2e/
* by the 2026-09 lane-move pilot (PGLite-only, no DATABASE_URL); see
* docs/test-audit/2026-09-29/implementation/lane-pilot.md.
*/
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { spawn, execFileSync, type ChildProcess } from 'child_process';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { runBootstrap } from '../src/commands/bootstrap.ts';
import type { ExecRunner } from '../src/core/bootstrap/repo.ts';
import { readHarnessReceiptState, writeHarnessReceipt } from '../src/core/bootstrap/format.ts';
import { CODEX_TOML_BLOCK_BEGIN } from '../src/core/bootstrap/host-specs.ts';
import { withEnv } from './helpers/with-env.ts';
const PORT = 19741; // unique to this suite (19735 = connect-bearer, 19131 = oauth)
const BASE = `http://127.0.0.1:${PORT}`;
describe('bootstrap harness lifecycle E2E (PGLite + real serve --http)', () => {
let parent: string; // GBRAIN_HOME parent for the brain
let sandboxHome: string; // HOME for user-scope writes
let codexHome: string;
let stubBin: string; // sandbox bin dir carrying a no-op `claude` (#4325)
let server: ChildProcess | null = null;
let token = '';
let serverReady = false;
const userSettings = () => join(sandboxHome, '.claude', 'settings.json');
const codexConfig = () => join(codexHome, 'config.toml');
const claudeRegistrations = new Map<string, { url: string; token: string }>();
function makeClaudeRunner(): { runner: ExecRunner; calls: string[][] } {
const calls: string[][] = [];
const runner: ExecRunner = async (argv: string[]) => {
calls.push(argv);
if (argv[0] === 'claude' && argv[2] === 'get') {
const registration = claudeRegistrations.get(argv[3]);
return registration
? { code: 0, stdout: `Scope: User\nType: http\nURL: ${registration.url}\nAuthorization: Bearer ${registration.token}`, stderr: '' }
: { code: 1, stdout: '', stderr: 'No MCP server found' };
}
if (argv[0] === 'claude' && argv[2] === 'add') {
const url = argv.find(value => /^https?:\/\//.test(value));
const header = argv.find(value => value.startsWith('Authorization: Bearer '));
if (!url || !header) throw new Error('Incomplete fixture registration');
claudeRegistrations.set(argv[3], { url, token: header.slice('Authorization: Bearer '.length) });
}
if (argv[0] === 'claude' && argv[2] === 'remove') claudeRegistrations.delete(argv[3]);
return { code: 0, stdout: '', stderr: '' };
};
return { runner, calls };
}
// Harness detection MUST be pinned, not inherited from the host. The
// production default is Bun.which(), which reads the real password-database
// HOME and ignores this test's remapped HOME/PATH — so without this seam the
// suite silently asserts different things depending on which agent CLIs the
// machine happens to have installed. Concretely: `claude` is on a developer
// laptop's PATH but absent on a GitHub runner, so the claude lane never ran
// in CI, no `claude mcp add` was exec'd, and no user-scope settings file was
// written — failing at lines 175 and 220 every night since 2026-08-17 while
// passing locally. Both harnesses are declared present here because that is
// the scenario these assertions describe.
const HARNESS_DETECT = {
claude: () => true,
codex: () => true,
opencode: () => false,
} as const;
async function capture<T>(fn: () => Promise<T>): Promise<{ result: T; out: string; err: string }> {
const origLog = console.log;
const origErr = console.error;
let out = '';
let err = '';
console.log = (...a: unknown[]) => { out += a.map(String).join(' ') + '\n'; };
console.error = (...a: unknown[]) => { err += a.map(String).join(' ') + '\n'; };
try {
return { result: await fn(), out, err };
} finally {
console.log = origLog;
console.error = origErr;
}
}
// CLAUDE_CONFIG_DIR is the load-bearing override: Bun's homedir() ignores a
// remapped HOME (it reads the password database), so HOME alone does NOT
// sandbox user-scope writes — that leak is exactly why claudeUserSettingsPath
// honors CLAUDE_CONFIG_DIR/HOME explicitly now.
const envFor = () => ({
GBRAIN_HOME: parent,
HOME: sandboxHome,
CLAUDE_CONFIG_DIR: join(sandboxHome, '.claude'),
CODEX_HOME: codexHome,
// #4325: detectClaude() probes PATH via Bun.which('claude'); CI runners
// don't ship the claude CLI, so the claude lane silently un-wires and the
// apply test's `claude add` assertions fail. Prepend a sandbox bin dir
// carrying an executable no-op `claude` stub — the recording runner seam
// intercepts every real exec, so the stub only ever satisfies detection.
PATH: `${stubBin}:${process.env.PATH ?? ''}`,
// With an ambient DATABASE_URL, the IN-PROCESS runBootstrap calls
// (unlike the spawned children scrubbed in beforeAll) would otherwise
// resolve it via loadConfig's env>file precedence and mint tokens
// against Postgres while the live serve is PGLite-backed — turning the
// expected refusal into an invalid_token rollback. withEnv treats
// undefined as delete-with-restore.
DATABASE_URL: undefined,
GBRAIN_DATABASE_URL: undefined,
});
// #6661: started once in beforeAll and again by the pre-mint sequence test (which stops it first).
async function startServe(env: Record<string, string | undefined>): Promise<void> {
serverReady = false;
server = spawn('bun', [
'run', 'src/cli.ts', 'serve', '--http',
'--bind', '127.0.0.1', '--port', String(PORT),
'--public-url', BASE,
], { cwd: process.cwd(), env, stdio: ['ignore', 'pipe', 'pipe'] });
let serr = '';
server.stderr?.on('data', (d: Buffer) => { serr += d.toString(); });
for (let i = 0; i < 60; i++) {
try {
const res = await fetch(`${BASE}/health`);
if (res.ok) { serverReady = true; break; }
} catch { /* not up yet */ }
await new Promise((r) => setTimeout(r, 500));
}
if (!serverReady) throw new Error(`serve --http did not become ready:\n${serr}`);
}
async function stopServe(): Promise<void> {
const proc = server;
server = null;
serverReady = false;
if (!proc || proc.exitCode !== null) return;
const exited = new Promise<void>((r) => proc.once('exit', () => r()));
proc.kill('SIGTERM');
await exited;
}
beforeAll(async () => {
parent = mkdtempSync(join(tmpdir(), 'gb-harness-e2e-'));
sandboxHome = mkdtempSync(join(tmpdir(), 'gb-harness-home-'));
codexHome = mkdtempSync(join(tmpdir(), 'gb-harness-codex-'));
// codex "installed" for detection purposes: the config file exists.
writeFileSync(codexConfig(), '# preexisting codex config\nmodel = "o5"\n');
// #4325: claude "installed" for detection purposes — executable no-op
// stub on a sandbox PATH entry (see envFor). Never actually executed.
stubBin = mkdtempSync(join(tmpdir(), 'gb-harness-bin-'));
writeFileSync(join(stubBin, 'claude'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
const env: Record<string, string | undefined> = { ...process.env, GBRAIN_HOME: parent };
delete env.DATABASE_URL;
delete env.GBRAIN_DATABASE_URL;
execFileSync('bun', ['run', 'src/cli.ts', 'init', '--pglite', '--no-embedding', '--non-interactive'], {
cwd: process.cwd(), env, stdio: 'ignore',
});
// Pre-mint the scoped token BEFORE serve starts — PGLite is single-writer,
// which is exactly the documented reason the --token lane exists.
const authOut = execFileSync(
'bun',
['run', 'src/cli.ts', 'auth', 'create', 'bootstrap-harness', '--scopes', 'read,write'],
{ cwd: process.cwd(), env, encoding: 'utf8' },
);
token = (authOut.match(/gbrain_[a-f0-9]{64}/) ?? [''])[0];
if (!token) throw new Error(`auth create did not yield a token:\n${authOut}`);
expect(authOut).toContain('scopes=["read","write"]');
await startServe(env);
}, 90_000);
afterAll(() => {
if (server) { try { server.kill('SIGTERM'); } catch { /* best-effort */ } }
for (const d of [parent, sandboxHome, codexHome, stubBin]) {
try { rmSync(d, { recursive: true, force: true }); } catch { /* best-effort */ }
}
});
test('mint under the live PGLite serve refuses with the two escape hatches', async () => {
expect(serverReady).toBe(true);
const { runner } = makeClaudeRunner();
const { result, err } = await withEnv(envFor(), () =>
capture(() =>
runBootstrap(['harness', '--yes', '--port', String(PORT), '--harness', 'codex'], { runner, harnessDetect: HARNESS_DETECT }),
),
);
expect(result).toBe(1);
expect(err).toMatch(/pre-mint|--token/);
expect(err).toMatch(/stop the serve/);
}, 60_000);
// #6661 (D25): the refusal's printed sequence, run for real: stop the serve, pre-mint with the harness grant, restart.
test('the refusal\'s stop/mint/rescope/start sequence yields a token with the harness grant', async () => {
expect(serverReady).toBe(true);
const { runner } = makeClaudeRunner();
const { result, err } = await withEnv(envFor(), () =>
capture(() => runBootstrap(['harness', '--yes', '--port', String(PORT), '--harness', 'codex', '--token-name', 'harness-e2e'], { runner, harnessDetect: HARNESS_DETECT })),
);
expect(result).toBe(1);
const steps = [...err.matchAll(/^\s+\d\. (.*)$/gm)].map((m) => m[1]!);
expect(steps).toHaveLength(5);
expect(steps[0]).toMatch(/stop the serve/);
expect(steps[1]).toBe('gbrain auth create harness-e2e --scopes read,write,skills_member_self');
expect(steps[2]).toMatch(/^gbrain auth rescope --token harness-e2e --operations \S*join_brain\S*$/);
expect(steps[3]).toMatch(/gbrain serve --http/);
expect(steps[4]).toMatch(/--token/);
const env: Record<string, string | undefined> = { ...process.env, GBRAIN_HOME: parent };
delete env.DATABASE_URL;
delete env.GBRAIN_DATABASE_URL;
const gbrain = (argv: string[]) => execFileSync('bun', ['run', 'src/cli.ts', ...argv], { cwd: process.cwd(), env, encoding: 'utf8' });
await stopServe();
const created = gbrain(steps[1]!.split(' ').slice(1));
const premint = (created.match(/gbrain_[a-f0-9]{64}/) ?? [''])[0];
expect(premint).not.toBe('');
gbrain(steps[2]!.split(' ').slice(1));
const grants = gbrain(['auth', 'rescope', '--token', 'harness-e2e']);
const stored = (grants.match(/^\s+Operations: (.*)$/m) ?? ['', ''])[1]!.split(', ');
expect(stored).toEqual(steps[2]!.split(' ')[6]!.split(','));
await startServe(env);
const joinBrain = async (bearer: string) => (await fetch(`${BASE}/mcp`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream', Authorization: `Bearer ${bearer}` },
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'join_brain', arguments: {} } }),
})).text();
// The printed grant reaches join_brain (refused only for its missing argument); the bare read,write pre-mint the
// old refusal suggested is refused for scope, which is what the reporter hit.
const viaPremint = await joinBrain(premint);
expect(viaPremint).toContain('Missing required parameter: adapter');
expect(viaPremint).not.toContain('insufficient_scope');
expect(await joinBrain(token)).toContain('insufficient_scope');
}, 120_000);
test('apply with --token: real health + real bearer smoke; both harnesses wired; receipt + install log', async () => {
expect(serverReady).toBe(true);
const { runner, calls } = makeClaudeRunner();
const { result, out } = await withEnv(envFor(), () =>
capture(() =>
runBootstrap(
[
'harness', '--yes',
'--port', String(PORT),
'--token', token,
'--gbrain-bin', '/opt/fake/gbrain',
],
{ runner, harnessDetect: HARNESS_DETECT },
),
),
);
expect(result).toBe(0);
// real smoke against the live serve — identity round-tripped over bearer
expect(out).toMatch(/smoke test:/);
expect(out).toMatch(/"engine":"pglite"/); // C2: tool results are compact JSON
// the sandbox held: nothing touched the operator's real user scope
expect(out).not.toContain(`${process.env.HOME}/.claude/settings.json`);
// claude lane: exec'd through the runner with user scope + our token
const add = calls.find((c) => c[0] === 'claude' && c[2] === 'add');
expect(add).toBeDefined();
expect(add!.join(' ')).toContain('--scope user');
expect(add!.join(' ')).toContain(`Bearer ${token}`);
// user-scope sandbox writes
const settings = JSON.parse(readFileSync(userSettings(), 'utf8')) as Record<string, unknown>;
expect((settings.permissions as { allow: string[] }).allow).toContain('mcp__gbrain');
expect(Object.keys(settings.hooks as object).length).toBe(5);
// codex lane: managed block with the inline http_headers credential
// (#4574 — never bearer_token); preexisting content intact
const toml = readFileSync(codexConfig(), 'utf8');
expect(toml).toContain('# preexisting codex config');
expect(toml).toContain(CODEX_TOML_BLOCK_BEGIN);
expect(toml).toContain(`http_headers = { Authorization = "Bearer ${token}" }`);
expect(toml).not.toContain('bearer_token');
// receipt: all confirmed; supplied token → minted:false
const home = join(parent, '.gbrain');
const state = readHarnessReceiptState(home);
expect(state.state).toBe('ok');
const receipt = (state as { receipt: { targets: Array<{ state: string }>; token: { minted: boolean } } }).receipt;
expect(receipt.targets.every((t) => t.state === 'confirmed')).toBe(true);
expect(receipt.token.minted).toBe(false);
// install log carries the harness phase
const log = readFileSync(join(home, 'bootstrap', 'install.jsonl'), 'utf8');
expect(log).toMatch(/"phase":"harness".*"outcome":"ok"/);
}, 60_000);
test('--status: live probes, token recovered from the codex block, exit 0', async () => {
const { runner } = makeClaudeRunner();
const all = await withEnv(envFor(), () => capture(() => runBootstrap(['harness', '--status', '--json'], { runner, harnessDetect: HARNESS_DETECT })));
expect(all.result).toBe(0);
expect(JSON.parse(all.out).harness_tokens).toEqual([{ host: 'claude-code', verified: true }, { host: 'codex', verified: true }]);
const home = join(parent, '.gbrain');
const state = readHarnessReceiptState(home);
expect(state.state).toBe('ok');
if (state.state !== 'ok') throw new Error('expected the installed receipt');
writeHarnessReceipt(home, { ...state.receipt, targets: state.receipt.targets.filter(target => target.host === 'codex'),
harness_tokens: { codex: state.receipt.harness_tokens!.codex } });
try {
const { result, out } = await withEnv(envFor(), () =>
capture(() => runBootstrap(['harness', '--status'], { runner, harnessDetect: HARNESS_DETECT })),
);
expect(result).toBe(0);
expect(out).toMatch(/serve: OK/);
expect(out).toMatch(/token: OK .*codex config block/);
} finally { writeHarnessReceipt(home, state.receipt); }
}, 60_000);
test('--remove: host wiring cleared, codex config byte-identical to pre-apply, receipt consumed', async () => {
const { runner } = makeClaudeRunner();
const { result } = await withEnv(envFor(), () =>
capture(() => runBootstrap(['harness', '--remove', '--yes'], { runner, harnessDetect: HARNESS_DETECT })),
);
expect(result).toBe(0);
expect(readFileSync(codexConfig(), 'utf8')).toBe('# preexisting codex config\nmodel = "o5"\n');
const settings = JSON.parse(readFileSync(userSettings(), 'utf8')) as Record<string, unknown>;
expect(settings.permissions).toBeUndefined();
expect(settings.hooks).toBeUndefined();
expect(readHarnessReceiptState(join(parent, '.gbrain'))).toEqual({ state: 'absent' });
}, 60_000);
test('scoped token is honored end-to-end: an admin-scope op is refused over MCP', async () => {
// The minted token carries scopes {read,write}; get_stats is an
// admin-scope MCP op — the per-op hasScope gate must refuse it while
// read/write ops keep working (proven by the smoke above).
const res = await fetch(`${BASE}/mcp`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'application/json, text/event-stream',
Authorization: `Bearer ${token}`,
},
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'tools/call',
params: { name: 'get_stats', arguments: {} },
}),
});
const text = await res.text();
expect(text).toMatch(/insufficient_scope|requires .*admin|not permitted|scope/i);
}, 30_000);
// #6661 option B, run for real: with the serve stopped a --token run wires and ends pending_verify (exit 13);
// --status stays partial until the fix's re-run, which runs while the live serve holds the PGLite brain.
test('--token with the serve stopped ends pending_verify; the printed re-run completes it under the live serve', async () => {
const env: Record<string, string | undefined> = { ...process.env, GBRAIN_HOME: parent };
delete env.DATABASE_URL;
delete env.GBRAIN_DATABASE_URL;
await stopServe();
const { runner } = makeClaudeRunner();
const run = (argv: string[]) => withEnv(envFor(), () => capture(() => runBootstrap(argv, { runner, harnessDetect: HARNESS_DETECT })));
const pending = await run(['harness', '--yes', '--port', String(PORT), '--harness', 'codex', '--skills', 'memory-only', '--token', token, '--json']);
expect(pending.result).toBe(13);
const doc = JSON.parse(pending.out) as { status: string; fix: { argv: string[] } };
expect(doc.status).toBe('pending_verify');
expect(pending.out).not.toContain(token);
expect(readFileSync(codexConfig(), 'utf8')).toContain(`http_headers = { Authorization = "Bearer ${token}" }`);
expect((await run(['harness', '--status', '--json'])).result).toBe(1);
await startServe(env);
const partial = await run(['harness', '--status', '--json']);
expect(partial.result).toBe(1);
expect(JSON.parse(partial.out)).toMatchObject({ status: 'partial', serve_ok: true, engine: 'pglite' });
const completed = await run(doc.fix.argv.slice(2).map(a => (a === '<TOKEN>' ? token : a)));
expect(completed.result).toBe(0);
// The re-run could not open the brain (the live serve holds it) and verified over HTTP instead.
expect(completed.err).toMatch(/could not verify --source 'default' against the brain/);
expect(completed.out).toMatch(/smoke test:/);
const done = await run(['harness', '--status', '--json']);
expect(done.result).toBe(0);
expect(JSON.parse(done.out).verify_pending).toBeUndefined();
expect((await run(['harness', '--remove', '--yes'])).result).toBe(0);
}, 120_000);
});