Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* bootstrap lifecycle e2e [A7]: temp workspace + sandboxed GBRAIN_HOME +
* PATH-shimmed fake gh/claude (argv recorders) driving the REAL dispatcher:
*
* status (subprocess CLI smoke) → interview (scripted answers, read-back
* hash, dispatcher render gate) → render → hooks (consents from answers)
* → repo (fake gh, privacy verified) → verify (real PGLite engine,
* keyless) → idempotent re-runs → GBRAIN_BOOTSTRAP_ABORT_AFTER kill-mid-
* phase → status resumes → lock collision refusal.
*
* Serial: PGLite cold starts + a bun subprocess spawn would starve parallel
* siblings. Every test carries an explicit timeout.
*/
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { spawnSync, execFileSync } from 'node:child_process';
import {
chmodSync,
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
rmSync,
writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { runBootstrap } from '../../src/commands/bootstrap.ts';
import type { ExecRunner } from '../../src/core/bootstrap/repo.ts';
import { readManifest, readReceipt } from '../../src/core/bootstrap/format.ts';
import { initState, setAnswer, confirm, readBackHash } from '../../src/core/bootstrap/interview.ts';
import { acquireBootstrapLock } from '../../src/core/bootstrap/lock.ts';
import { statusReport, readInstallLog, BOOTSTRAP_PHASE_IDS } from '../../src/core/bootstrap/status.ts';
import { createEngine } from '../../src/core/engine-factory.ts';
import { addSource } from '../../src/core/sources-ops.ts';
const REPO_ROOT = resolve(import.meta.dir, '..', '..');
let tmpParent: string; // GBRAIN_HOME parent (short prefix — unix socket path budget)
let home: string;
let dbDir: string;
let ws: string;
let shimDir: string;
let recordFile: string;
const SAVED_ENV: Record<string, string | undefined> = {};
const ENV_KEYS = [
'GBRAIN_HOME', 'PATH', 'GB_FAKE_RECORD', 'GBRAIN_DATABASE_URL', 'DATABASE_URL',
'GBRAIN_BRAIN_ID', 'GBRAIN_SOURCE', 'GBRAIN_HOOKS', 'GBRAIN_BOOTSTRAP_ABORT_AFTER',
'CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT', 'CODEX_HOME', 'CODEX_SANDBOX', 'CODEX_CI',
];
const REQUIRED_ANSWERS: Record<string, string> = {
AGENT_NAME: 'Lifeboat',
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; values signal over noise.',
VOICE_REGISTER: 'Direct: three options, the second one wins.',
};
function record(): string {
try {
return readFileSync(recordFile, 'utf8');
} catch {
return '';
}
}
/**
* Env-pinned exec runner. Bun.spawn WITHOUT an explicit env uses Bun's
* STARTUP env snapshot — the shimmed PATH / GB_FAKE_RECORD mutated in
* beforeAll would be invisible and the test would exec the REAL gh/claude
* (verified the hard way). Every runBootstrap call that spawns goes through
* this runner seam.
*/
const testRunner: ExecRunner = async (argv: string[]) => {
try {
const proc = Bun.spawn(argv, {
stdout: 'pipe',
stderr: 'pipe',
stdin: 'ignore',
env: { ...process.env } as Record<string, string>,
});
const [stdout, stderr, code] = await Promise.all([
new Response(proc.stdout).text(),
new Response(proc.stderr).text(),
proc.exited,
]);
return { code, stdout, stderr };
} catch (e) {
return { code: 127, stdout: '', stderr: (e as Error).message };
}
};
/** Capture console.log output (stdout data) around an async call. */
async function captureStdout<T>(fn: () => Promise<T>): Promise<{ result: T; out: string }> {
const orig = console.log;
let out = '';
console.log = (...args: unknown[]) => {
out += args.map(String).join(' ') + '\n';
};
try {
const result = await fn();
return { result, out };
} finally {
console.log = orig;
}
}
beforeAll(() => {
for (const k of ENV_KEYS) SAVED_ENV[k] = process.env[k];
// Ambient-state strip (the install-gbrain.mjs guard, plan resolved D2):
// a dev/CI DATABASE_URL must not flip the sandboxed brain to Postgres.
delete process.env.GBRAIN_DATABASE_URL;
delete process.env.DATABASE_URL;
delete process.env.GBRAIN_BRAIN_ID;
delete process.env.GBRAIN_SOURCE;
delete process.env.GBRAIN_HOOKS;
delete process.env.GBRAIN_BOOTSTRAP_ABORT_AFTER;
delete process.env.CLAUDECODE;
delete process.env.CLAUDE_CODE_ENTRYPOINT;
delete process.env.CODEX_HOME;
delete process.env.CODEX_SANDBOX;
delete process.env.CODEX_CI;
// Short prefix: the IPC socket lives under database_path and unix socket
// paths cap out around 104 bytes on macOS.
tmpParent = mkdtempSync(join(tmpdir(), 'gb-e2e-'));
home = join(tmpParent, '.gbrain');
mkdirSync(home, { recursive: true });
dbDir = join(tmpParent, 'db');
process.env.GBRAIN_HOME = tmpParent;
// CODEX_HOME must be SET (not just deleted): the codex hooks lane writes
// hooks.json + a config.toml trust block, and the homedir fallback would
// land them in the operator's REAL ~/.codex on a dev machine.
process.env.CODEX_HOME = join(tmpParent, 'codex-home');
mkdirSync(process.env.CODEX_HOME, { recursive: true });
// Engine phase artifact: the config `gbrain init --pglite` would write.
writeFileSync(join(home, 'config.json'), JSON.stringify({ engine: 'pglite', database_path: dbDir }, null, 2));
// Workspace: a fresh git repo (the cwd the human pasted in).
ws = mkdtempSync(join(tmpdir(), 'gb-e2e-ws-'));
execFileSync('git', ['init', '-q', '-b', 'main'], { cwd: ws });
execFileSync('git', ['config', 'user.email', '[email protected]'], { cwd: ws });
execFileSync('git', ['config', 'user.name', 'Test'], { cwd: ws });
mkdirSync(join(ws, 'brain'), { recursive: true });
// PATH shims: fake gh + fake claude, both recording argv [A7].
shimDir = mkdtempSync(join(tmpdir(), 'gb-e2e-bin-'));
recordFile = join(shimDir, 'record.log');
process.env.GB_FAKE_RECORD = recordFile;
writeFileSync(
join(shimDir, 'gh'),
`#!/bin/sh
echo "gh $*" >> "$GB_FAKE_RECORD"
case "$1" in
--version) echo "gh version 2.40.0"; exit 0 ;;
auth) exit 0 ;;
api)
case "$2" in
user) echo '{"login":"tester","id":42}'; exit 0 ;;
repos/*) echo "true"; exit 0 ;;
esac
exit 1 ;;
repo)
case "$2" in
view)
case "$*" in
*--json*) echo "true"; exit 0 ;;
esac
exit 1 ;;
create)
name="$3"
src=""
prev=""
for a in "$@"; do
if [ "$prev" = "--source" ]; then src="$a"; fi
prev="$a"
done
if [ -n "$src" ]; then
git -C "$src" remote add origin "https://github.com/tester/$name.git" >/dev/null 2>&1 || true
fi
exit 0 ;;
esac
exit 1 ;;
esac
exit 0
`,
);
chmodSync(join(shimDir, 'gh'), 0o755);
writeFileSync(
join(shimDir, 'claude'),
`#!/bin/sh
echo "claude $*" >> "$GB_FAKE_RECORD"
case "$1 $2" in
"mcp add") exit 0 ;;
"mcp list") echo "gbrain: stdio serve"; exit 0 ;;
"mcp remove") exit 0 ;;
esac
exit 0
`,
);
chmodSync(join(shimDir, 'claude'), 0o755);
// STATEFUL codex shim: `mcp add` records the exact command+env line, `mcp
// get` echoes it back, `mcp list`/`remove` reflect real state. This is what
// lets verifyMcpTargetsWorkspace ([FIX7]) actually pass/fail — an inert shim
// that always printed "gbrain" made the mismatch detector unfalsifiable.
// State lives next to the argv record so it's cleaned up with shimDir.
writeFileSync(
join(shimDir, 'codex'),
`#!/bin/sh
echo "codex $*" >> "$GB_FAKE_RECORD"
STATE="$(dirname "$GB_FAKE_RECORD")/codex-mcp.state"
case "$1 $2" in
"mcp add") printf '%s\\n' "$*" > "$STATE"; exit 0 ;;
"mcp get")
[ -f "$STATE" ] || { echo "no such MCP server: $3" >&2; exit 1; }
cat "$STATE"; exit 0 ;;
"mcp list") [ -f "$STATE" ] && echo "gbrain: stdio serve"; exit 0 ;;
"mcp remove") rm -f "$STATE"; exit 0 ;;
esac
exit 0
`,
);
chmodSync(join(shimDir, 'codex'), 0o755);
// A dummy absolute gbrain binary for registrations/hook command strings
// (never executed by this test — hooks fire in-process).
writeFileSync(join(shimDir, 'gbrain'), '#!/bin/sh\nexit 0\n');
chmodSync(join(shimDir, 'gbrain'), 0o755);
// git shim: intercept `push` (recorded, succeeds — the fake origin is an
// https URL no real push could reach) and `ls-remote` (reports the branch
// exists, so the FIX3 adoption re-run sees a genuinely-pushed remote instead
// of trying to reach github.com). Everything else delegates to real git —
// so repo.ts's create → privacy-verify → ensure-commit → FIRST-push ordering
// [G8] and the real add/commit run without network.
const realGit = Bun.which('git');
if (!realGit) throw new Error('git not on PATH — the e2e needs a real git to delegate to');
writeFileSync(
join(shimDir, 'git'),
`#!/bin/sh
for a in "$@"; do
if [ "$a" = "push" ]; then
echo "git $*" >> "$GB_FAKE_RECORD"
exit 0
fi
if [ "$a" = "ls-remote" ]; then
echo "git $*" >> "$GB_FAKE_RECORD"
echo "0000000000000000000000000000000000000000 refs/heads/main"
exit 0
fi
done
exec "${realGit}" "$@"
`,
);
chmodSync(join(shimDir, 'git'), 0o755);
process.env.PATH = `${shimDir}:${process.env.PATH ?? ''}`;
}, 60_000);
afterAll(() => {
for (const k of ENV_KEYS) {
if (SAVED_ENV[k] === undefined) delete process.env[k];
else process.env[k] = SAVED_ENV[k];
}
for (const dir of [tmpParent, ws, shimDir]) {
try {
rmSync(dir, { recursive: true, force: true });
} catch {
/* best effort */
}
}
});
describe('bootstrap lifecycle (serial e2e)', () => {
test('CLI wiring smoke: `gbrain bootstrap status --json` reaches the dispatcher as a subprocess', () => {
const res = spawnSync('bun', ['run', join(REPO_ROOT, 'src', 'cli.ts'), 'bootstrap', 'status', '--json'], {
cwd: ws,
env: { ...process.env },
encoding: 'utf8',
timeout: 60_000,
});
expect(res.status).toBe(0);
const parsed = JSON.parse(res.stdout) as { phases: Array<{ id: string }>; support: { binary_version: string } };
expect(parsed.phases.map((p) => p.id)).toEqual([...BOOTSTRAP_PHASE_IDS]);
expect(parsed.support.binary_version.length).toBeGreaterThan(0);
}, 90_000);
test('interview: scripted answers, render refuses before confirm, read-back hash confirms', async () => {
expect(await runBootstrap(['interview', '--init', '--workspace', ws])).toBe(0);
for (const [key, value] of Object.entries(REQUIRED_ANSWERS)) {
expect(await runBootstrap(['interview', '--set', key, value, '--workspace', ws])).toBe(0);
}
// Consents ride the same state file (wire/repo phases read them later).
expect(await runBootstrap(['interview', '--set', 'MCP_SCOPE', 'project', '--workspace', ws])).toBe(0);
expect(await runBootstrap(['interview', '--set', 'HOOKS_CONSENT', 'yes', '--workspace', ws])).toBe(0);
expect(await runBootstrap(['interview', '--set', 'PERSIST_CRON', 'no', '--workspace', ws])).toBe(0);
// Dispatcher-level render gate [A8]: complete but UNCONFIRMED → refuse.
expect(await runBootstrap(['render', '--workspace', ws])).toBe(1);
const h = readBackHash(ws);
if (!h.ok) throw new Error(h.message);
// A wrong hash must not confirm.
expect(await runBootstrap(['interview', '--confirm', 'deadbeef', '--workspace', ws])).toBe(1);
expect(await runBootstrap(['interview', '--confirm', h.hash, '--workspace', ws])).toBe(0);
expect(await runBootstrap(['interview', '--status', '--workspace', ws])).toBe(0);
}, 60_000);
test('render: identity files + initialized manifest + machine receipt; idempotent re-run keeps files', async () => {
expect(await runBootstrap(['render', '--workspace', ws])).toBe(0);
expect(existsSync(join(ws, 'SOUL.md'))).toBe(true);
expect(existsSync(join(ws, 'AGENTS.md'))).toBe(true);
expect(existsSync(join(ws, '.gitignore'))).toBe(true);
const manifest = readManifest(ws);
expect(manifest.state).toBe('initialized');
const receipt = readReceipt(home);
expect(receipt?.workspace_dir).toBeTruthy();
expect(receipt?.agent_name).toBe('Lifeboat');
// Idempotent re-run: nothing clobbered, exit 0.
const soulBefore = readFileSync(join(ws, 'SOUL.md'), 'utf8');
expect(await runBootstrap(['render', '--workspace', ws])).toBe(0);
expect(readFileSync(join(ws, 'SOUL.md'), 'utf8')).toBe(soulBefore);
// Interview answers rendered verbatim (identity from the human's words).
expect(soulBefore).toContain('Lifeboat');
}, 60_000);
test('hooks: MCP argv recorded with GBRAIN_SOURCE binding [G1], hooks written under consent, receipt updated', async () => {
const gbrainBin = join(shimDir, 'gbrain');
expect(
await runBootstrap(['hooks', '--workspace', ws, '--harness', 'claude-code', '--gbrain-bin', gbrainBin], {
runner: testRunner,
}),
).toBe(0);
const rec = record();
expect(rec).toContain('claude mcp add gbrain --scope project -e GBRAIN_SOURCE=workspace');
expect(rec).toContain('claude mcp list');
const settingsPath = join(ws, '.claude', 'settings.local.json');
expect(existsSync(settingsPath)).toBe(true);
const settings = JSON.parse(readFileSync(settingsPath, 'utf8')) as { hooks: Record<string, unknown> };
expect(Object.keys(settings.hooks)).toEqual(
expect.arrayContaining(['SessionStart', 'UserPromptSubmit', 'Stop', 'SessionEnd']),
);
expect(readFileSync(settingsPath, 'utf8')).toContain('"_gbrain"');
const receipt = readReceipt(home);
expect(receipt?.registrations).toEqual([
{ host: 'claude-code', scope: 'project', detail: 'mcp+hooks' },
]);
}, 60_000);
test('repo: private repo created via fake gh, privacy verified BEFORE first push, URL recorded; re-run reuses', async () => {
expect(await runBootstrap(['repo', '--workspace', ws], { runner: testRunner })).toBe(0);
const rec = record();
// Create runs WITHOUT --push; the first push happens only AFTER the
// privacy bit verified true [G8] (create → verify → push).
expect(rec).toContain('gh repo create lifeboat-workspace --private --source');
expect(rec).not.toContain('--push');
expect(rec).toContain('gh api repos/tester/lifeboat-workspace --jq .private');
const verifyIdx = rec.indexOf('gh api repos/tester/lifeboat-workspace --jq .private');
const pushIdx = rec.indexOf(`git -C ${ws} push -u origin`);
expect(pushIdx).toBeGreaterThan(verifyIdx);
const origin = execFileSync('git', ['-C', ws, 'remote', 'get-url', 'origin']).toString().trim();
expect(origin).toBe('https://github.com/tester/lifeboat-workspace.git');
const receipt = readReceipt(home) as (ReturnType<typeof readReceipt> & { repo_url?: string }) | null;
expect(receipt?.repo_url).toBe(origin);
expect(readFileSync(join(ws, 'GITHUB.md'), 'utf8')).toContain(origin);
// Idempotent re-run: adopts our own origin, re-verifies privacy.
expect(await runBootstrap(['repo', '--workspace', ws], { runner: testRunner })).toBe(0);
}, 60_000);
test('verify: real PGLite engine, keyless — exit 0 with magic moment + committed brain/ write-through', async () => {
// Pre-init the brain the way `gbrain init --pglite` + `sources add` would.
const engineConfig = { engine: 'pglite' as const, database_path: dbDir };
const engine = await createEngine(engineConfig);
await engine.connect(engineConfig);
await engine.initSchema();
await addSource(engine, { id: 'workspace', localPath: join(ws, 'brain'), force: true });
await engine.disconnect();
const { result: code, out } = await captureStdout(() => runBootstrap(['verify', '--workspace', ws, '--json']));
expect(code).toBe(0);
const payload = JSON.parse(out) as {
ok: boolean;
checks: Array<{ id: string; ok: boolean; warn?: boolean; detail: string }>;
tour: string[];
};
expect(payload.ok).toBe(true);
const byId = (id: string) => payload.checks.filter((c) => c.id === id);
for (const c of byId('roundtrip')) expect(c.ok).toBe(true);
expect(byId('graph_floor')[0].ok).toBe(true);
expect(byId('magic_moment')[0].ok).toBe(true);
expect(byId('repo_privacy')[0].ok).toBe(true); // fake gh answered true
expect(byId('hooks_smoke')[0].ok).toBe(true); // hooks installed → smoke ran (ok or documented warn)
expect(payload.tour.length).toBe(3);
// The probe cleaned itself up [G13]; brain/ dir exists for real writes.
expect(existsSync(join(ws, 'brain', 'wiki', 'bootstrap-verify-probe.md'))).toBe(false);
// Verify snapshot persisted → status flips the verify phase to done [B2].
const report = await statusReport(ws, { gbrainHomeDir: home });
const verifyPhase = report.phases.find((p) => p.id === 'verify')!;
expect(verifyPhase.state).toBe('done');
// Only skills stays pending (this e2e never scaffolds the skillpack) —
// and `next` points exactly at that phase's resume hint.
const notDone = report.phases.filter((p) => p.state !== 'done' && p.state !== 'skipped');
expect(notDone.map((p) => p.id)).toEqual(['skills']);
expect(report.next).toBe(notDone[0].resume_hint);
}, 300_000);
test('kill-mid-phase [A7]: GBRAIN_BOOTSTRAP_ABORT_AFTER=render aborts after artifacts; status resumes; re-run no-ops', async () => {
const ws2 = mkdtempSync(join(tmpdir(), 'gb-e2e-ws2-'));
try {
expect(initState(ws2).ok).toBe(true);
for (const [key, value] of Object.entries(REQUIRED_ANSWERS)) {
const r = setAnswer(ws2, key, value);
if (!r.ok) throw new Error(r.message);
}
const h = readBackHash(ws2);
if (!h.ok) throw new Error(h.message);
expect(confirm(ws2, h.hash).ok).toBe(true);
process.env.GBRAIN_BOOTSTRAP_ABORT_AFTER = 'render';
const code = await runBootstrap(['render', '--workspace', ws2]);
expect(code).toBe(130);
delete process.env.GBRAIN_BOOTSTRAP_ABORT_AFTER;
// Artifacts exist (the abort fired AFTER the phase's mutation)…
expect(readManifest(ws2).state).toBe('initialized');
// …and the log recorded the abort, not a green 'ok' [B1].
const entries = readInstallLog(home).filter((e) => e.workspace === ws2 && e.phase === 'render');
expect(entries[entries.length - 1]?.outcome).toBe('aborted');
// status resumes: render detected done from artifacts, next points onward.
const report = await statusReport(ws2, { gbrainHomeDir: home });
const byId = new Map(report.phases.map((p) => [p.id, p]));
expect(byId.get('render')!.state).toBe('done');
expect(report.next).not.toBe(byId.get('render')!.resume_hint);
// Re-run converges: exit 0, files kept.
expect(await runBootstrap(['render', '--workspace', ws2])).toBe(0);
// Codex door: MCP registered via `codex mcp add` (user-global, env
// binding [G1]) — and since the Memorable wave, a consent-gated
// SessionEnd hook pair (hooks.json + config.toml trust block) lands in
// CODEX_HOME too, so the receipt reads mcp+hooks. Per-turn context
// stays the pull protocol (codex hooks are SessionEnd-only).
const gbrainBin = join(shimDir, 'gbrain');
const { result: hooksCode, out: hooksOut } = await captureStdout(() =>
runBootstrap(['hooks', '--workspace', ws2, '--harness', 'codex', '--gbrain-bin', gbrainBin], {
runner: testRunner,
}),
);
expect(hooksCode).toBe(0);
expect(record()).toContain('codex mcp add gbrain --env GBRAIN_SOURCE=workspace');
// [FIX7] the stateful shim echoes the recorded reg on `mcp get`, so the
// registration smoke VERIFIES it targets THIS workspace (binary + source)
// rather than falling back to the substring probe. A regressed
// verifyMcpTargetsWorkspace (mismatch/unknown) would change this line.
expect(hooksOut).toContain('MCP registered with codex (scope: user-global) — verified targeting this workspace.');
expect(existsSync(join(ws2, '.claude', 'settings.local.json'))).toBe(false);
const receipt = readReceipt(home);
// Receipt is machine-scoped last-attach-wins: ws2's registration replaced ws's record.
expect(receipt?.registrations).toEqual([{ host: 'codex', scope: 'user', detail: 'mcp+hooks' }]);
// The hook pair landed in the ISOLATED CODEX_HOME, never the real one.
expect(existsSync(join(process.env.CODEX_HOME!, 'hooks.json'))).toBe(true);
expect(readFileSync(join(process.env.CODEX_HOME!, 'config.toml'), 'utf8')).toContain('gbrain:codex-hooks-trust');
} finally {
delete process.env.GBRAIN_BOOTSTRAP_ABORT_AFTER;
rmSync(ws2, { recursive: true, force: true });
}
}, 120_000);
test('lock collision [G9]: a held bootstrap lock refuses a second mutating run, politely', async () => {
const handle = await acquireBootstrapLock(ws);
try {
const code = await runBootstrap(['render', '--workspace', ws]);
expect(code).toBe(1); // BOOTSTRAP_IN_PROGRESS → typed refusal, exit 1
} finally {
handle.release();
}
// Lock released → the same command succeeds again (idempotent render).
expect(await runBootstrap(['render', '--workspace', ws])).toBe(0);
}, 60_000);
});