Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* bootstrap-harness-writers.test.ts — harness-lane additions to the
* settings writers (#4043: writeClaudeHooksAt/removeClaudeHooksAt marker
* parameterization [C6], permissions.allow writers,
* atomic-write hardening [C10], CODEX_HOME-aware codexConfigPath).
*
* Behavior-preservation for the workspace lane is pinned by the untouched
* test/bootstrap-hooks-writers.test.ts — this file covers only what harness
* mode adds.
*/
import { describe, expect, test } from 'bun:test';
import { mkdtempSync, mkdirSync, readFileSync, statSync, symlinkSync, writeFileSync, lstatSync, realpathSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import {
addPermissionsAllowEntry,
removePermissionsAllowEntry,
removeClaudeHooksAt,
writeClaudeHooksAt,
} from '../src/core/bootstrap/hooks.ts';
import {
CLAUDE_HOOK_EVENTS,
GBRAIN_HARNESS_MARKER_VALUE,
GBRAIN_HOOK_MARKER_KEY,
GBRAIN_HOOK_MARKER_VALUE,
claudeProjectsDir,
codexConfigPath,
mcpPermissionEntry,
} from '../src/core/bootstrap/host-specs.ts';
import {
deleteHarnessReceipt,
guardHarnessReceiptOverwrite,
harnessReceiptPath,
readHarnessReceiptState,
writeHarnessReceipt,
} from '../src/core/bootstrap/format.ts';
import { withEnv } from './helpers/with-env.ts';
const BIN = '/opt/fake/gbrain';
function tmp(): string {
return mkdtempSync(join(tmpdir(), 'gb-harness-writers-'));
}
function readJson(path: string): Record<string, unknown> {
return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
}
function markerEntries(settings: Record<string, unknown>, marker: string): number {
let n = 0;
const hooks = (settings.hooks ?? {}) as Record<string, unknown>;
for (const groups of Object.values(hooks)) {
if (!Array.isArray(groups)) continue;
for (const g of groups) {
const entries = (g as { hooks?: unknown[] }).hooks;
if (!Array.isArray(entries)) continue;
for (const e of entries) {
if ((e as Record<string, unknown>)[GBRAIN_HOOK_MARKER_KEY] === marker) n++;
}
}
}
return n;
}
describe('two-marker coexistence [C6]', () => {
test('harness entries coexist with bootstrap-v1; each removal strips only its own', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
writeClaudeHooksAt(path, { gbrainBin: BIN, env: { GBRAIN_SOURCE: 'ws' } });
writeClaudeHooksAt(path, {
gbrainBin: BIN,
env: { GBRAIN_SOURCE: 'default' },
marker: GBRAIN_HARNESS_MARKER_VALUE,
});
let settings = readJson(path);
expect(markerEntries(settings, GBRAIN_HOOK_MARKER_VALUE)).toBe(CLAUDE_HOOK_EVENTS.length);
expect(markerEntries(settings, GBRAIN_HARNESS_MARKER_VALUE)).toBe(CLAUDE_HOOK_EVENTS.length);
const removed = removeClaudeHooksAt(path, GBRAIN_HARNESS_MARKER_VALUE);
expect(removed.removed).toBe(CLAUDE_HOOK_EVENTS.length);
settings = readJson(path);
expect(markerEntries(settings, GBRAIN_HOOK_MARKER_VALUE)).toBe(CLAUDE_HOOK_EVENTS.length);
expect(markerEntries(settings, GBRAIN_HARNESS_MARKER_VALUE)).toBe(0);
});
test('harness re-run dedupes on the harness marker only', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
const opts = {
gbrainBin: BIN,
env: { GBRAIN_SOURCE: 'default' },
marker: GBRAIN_HARNESS_MARKER_VALUE,
};
writeClaudeHooksAt(path, opts);
const second = writeClaudeHooksAt(path, opts);
expect(second.removedPrior).toBe(CLAUDE_HOOK_EVENTS.length);
expect(markerEntries(readJson(path), GBRAIN_HARNESS_MARKER_VALUE)).toBe(CLAUDE_HOOK_EVENTS.length);
});
test('refuseOnForeignGbrainMarker: refuses when another gbrain marker wires a target event', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
writeClaudeHooksAt(path, { gbrainBin: BIN, env: { GBRAIN_SOURCE: 'ws' } }); // bootstrap-v1
expect(() =>
writeClaudeHooksAt(path, {
gbrainBin: BIN,
env: { GBRAIN_SOURCE: 'default' },
marker: GBRAIN_HARNESS_MARKER_VALUE,
refuseOnForeignGbrainMarker: true,
}),
).toThrow(/already wires hooks\..* under gbrain marker "bootstrap-v1"/);
// untouched: still exactly the bootstrap-v1 entries
expect(markerEntries(readJson(path), GBRAIN_HOOK_MARKER_VALUE)).toBe(CLAUDE_HOOK_EVENTS.length);
expect(markerEntries(readJson(path), GBRAIN_HARNESS_MARKER_VALUE)).toBe(0);
});
test('refuseOnForeignGbrainMarker: foreign UNMARKED hooks never trip the refusal', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
writeFileSync(
path,
JSON.stringify({ hooks: { SessionStart: [{ hooks: [{ type: 'command', command: 'echo hi' }] }] } }),
);
const res = writeClaudeHooksAt(path, {
gbrainBin: BIN,
env: { GBRAIN_SOURCE: 'default' },
marker: GBRAIN_HARNESS_MARKER_VALUE,
refuseOnForeignGbrainMarker: true,
});
expect(res.installed.length).toBe(CLAUDE_HOOK_EVENTS.length);
const groups = (readJson(path).hooks as Record<string, unknown[]>).SessionStart;
const flat = groups.flatMap((g) => ((g as { hooks?: unknown[] }).hooks ?? []) as unknown[]);
expect(flat.some((e) => (e as { command?: string }).command === 'echo hi')).toBe(true);
});
});
describe('broken JSON is fail-closed', () => {
test('write throws and leaves the file untouched (never relocate a config we cannot read)', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
const broken = '{ "hooks": { // JSONC comment\n } }';
writeFileSync(path, broken);
expect(() =>
writeClaudeHooksAt(path, {
gbrainBin: BIN,
env: { GBRAIN_SOURCE: 'default' },
marker: GBRAIN_HARNESS_MARKER_VALUE,
}),
).toThrow(/refusing to rewrite/);
expect(readFileSync(path, 'utf8')).toBe(broken);
});
test('workspace-lane writes are fail-closed too', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
const broken = 'not json at all';
writeFileSync(path, broken);
expect(() => writeClaudeHooksAt(path, { gbrainBin: BIN, env: { GBRAIN_SOURCE: 'ws' } })).toThrow(
/refusing to rewrite/,
);
expect(readFileSync(path, 'utf8')).toBe(broken);
});
});
describe('permissions.allow writers', () => {
test('fresh file: permissions.allow created with exactly our entry', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
const res = addPermissionsAllowEntry(path, mcpPermissionEntry('gbrain'));
expect(res.added).toBe(true);
const settings = readJson(path);
expect((settings.permissions as { allow: string[] }).allow).toEqual(['mcp__gbrain']);
});
test('foreign allow entries + other keys survive; re-add is a no-op', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
writeFileSync(
path,
JSON.stringify({
permissions: { allow: ['Bash(ls:*)'], deny: ['WebFetch'] },
model: 'opus',
}),
);
addPermissionsAllowEntry(path, 'mcp__gbrain');
const again = addPermissionsAllowEntry(path, 'mcp__gbrain');
expect(again.added).toBe(false);
const settings = readJson(path);
expect((settings.permissions as { allow: string[] }).allow).toEqual(['Bash(ls:*)', 'mcp__gbrain']);
expect((settings.permissions as { deny: string[] }).deny).toEqual(['WebFetch']);
expect(settings.model).toBe('opus');
});
test('removal removes exactly our string; foreign entries survive', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
writeFileSync(path, JSON.stringify({ permissions: { allow: ['Bash(ls:*)', 'mcp__gbrain'] } }));
const res = removePermissionsAllowEntry(path, 'mcp__gbrain');
expect(res.removed).toBe(1);
expect((readJson(path).permissions as { allow: string[] }).allow).toEqual(['Bash(ls:*)']);
});
test('removal drops keys only when OUR removal emptied them', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
writeFileSync(path, JSON.stringify({ permissions: { allow: ['mcp__gbrain'] } }));
removePermissionsAllowEntry(path, 'mcp__gbrain');
const settings = readJson(path);
expect(settings.permissions).toBeUndefined();
});
test('removal of a missing entry / missing file is a calm no-op', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
expect(removePermissionsAllowEntry(path, 'mcp__gbrain').removed).toBe(0);
writeFileSync(path, JSON.stringify({ permissions: { allow: ['Bash(ls:*)'] } }));
expect(removePermissionsAllowEntry(path, 'mcp__gbrain').removed).toBe(0);
});
test('broken JSON: add aborts, remove leaves untouched with a note', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
const broken = '{ broken';
writeFileSync(path, broken);
expect(() => addPermissionsAllowEntry(path, 'mcp__gbrain')).toThrow(/refusing to rewrite/);
const res = removePermissionsAllowEntry(path, 'mcp__gbrain');
expect(res.removed).toBe(0);
expect(res.notes.join(' ')).toMatch(/left untouched/);
expect(readFileSync(path, 'utf8')).toBe(broken);
});
test('non-object permissions / non-array allow FAIL CLOSED — security policy is never rewritten', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
const weird = JSON.stringify({ permissions: 'weird' });
writeFileSync(path, weird);
expect(() => addPermissionsAllowEntry(path, 'mcp__gbrain')).toThrow(/refusing to rewrite security policy/);
expect(readFileSync(path, 'utf8')).toBe(weird); // untouched
const badAllow = JSON.stringify({ permissions: { allow: 'not-an-array', deny: ['WebFetch'] } });
writeFileSync(path, badAllow);
expect(() => addPermissionsAllowEntry(path, 'mcp__gbrain')).toThrow(/refusing to rewrite security policy/);
expect(readFileSync(path, 'utf8')).toBe(badAllow);
});
});
describe('atomic-write hardening [C10]', () => {
test('0600 file stays 0600 after write (mode preservation)', () => {
const dir = tmp();
const path = join(dir, 'settings.json');
writeFileSync(path, '{}', { mode: 0o600 });
addPermissionsAllowEntry(path, 'mcp__gbrain');
expect(statSync(path).mode & 0o777).toBe(0o600);
});
test('symlinked settings file survives as a symlink (realpath write)', () => {
const dir = tmp();
const real = join(dir, 'dotfiles', 'claude-settings.json');
mkdirSync(join(dir, 'dotfiles'), { recursive: true });
writeFileSync(real, JSON.stringify({ model: 'opus' }));
const link = join(dir, 'settings.json');
symlinkSync(real, link);
addPermissionsAllowEntry(link, 'mcp__gbrain');
expect(lstatSync(link).isSymbolicLink()).toBe(true);
expect(realpathSync(link)).toBe(realpathSync(real));
expect((readJson(real).permissions as { allow: string[] }).allow).toEqual(['mcp__gbrain']);
expect(readJson(real).model).toBe('opus');
});
test('timestamped backup strategy leaves distinct backups for sequential writes', async () => {
const dir = tmp();
const path = join(dir, 'settings.json');
writeFileSync(path, '{}');
const first = writeClaudeHooksAt(path, {
gbrainBin: BIN,
env: { GBRAIN_SOURCE: 'a' },
marker: GBRAIN_HARNESS_MARKER_VALUE,
backupStrategy: 'timestamped',
});
await new Promise((r) => setTimeout(r, 2));
const second = writeClaudeHooksAt(path, {
gbrainBin: BIN,
env: { GBRAIN_SOURCE: 'b' },
marker: GBRAIN_HARNESS_MARKER_VALUE,
backupStrategy: 'timestamped',
});
expect(first.backupPath).not.toBeNull();
expect(second.backupPath).not.toBeNull();
expect(first.backupPath).not.toBe(second.backupPath);
});
});
describe('harness receipt (format.ts, CX2-12 discipline)', () => {
test('write-ahead round trip: 0600 file, typed read states, guard semantics', () => {
const home = tmp();
const receipt = {
harness_receipt_version: 1 as const,
created_at: '2026-08-12T00:00:00Z',
created_by: 'gbrain@test',
url: 'http://127.0.0.1:3131/mcp',
engine: 'postgres',
serve_version: '0.45.7.0',
source_id: 'default',
token: { name: 'bootstrap-harness', id: '00000000-0000-0000-0000-000000000000', minted: true },
targets: [
{ host: 'claude-code' as const, kind: 'mcp' as const, state: 'pending' as const, scope: 'user', name: 'gbrain' },
],
};
expect(readHarnessReceiptState(home)).toEqual({ state: 'absent' });
writeHarnessReceipt(home, receipt);
expect(statSync(harnessReceiptPath(home)).mode & 0o777).toBe(0o600);
const state = readHarnessReceiptState(home);
expect(state.state).toBe('ok');
expect((state as { receipt: typeof receipt }).receipt.targets[0].state).toBe('pending');
// newer-format refusal (never silently clobber a newer gbrain's receipt)
writeFileSync(harnessReceiptPath(home), JSON.stringify({ harness_receipt_version: 2 }));
expect(readHarnessReceiptState(home).state).toBe('newer');
expect(() => guardHarnessReceiptOverwrite(home)).toThrow(/newer gbrain/);
// broken receipt → backed up aside, never silently discarded
writeFileSync(harnessReceiptPath(home), 'not json');
expect(readHarnessReceiptState(home).state).toBe('invalid');
const guard = guardHarnessReceiptOverwrite(home);
expect(guard.brokenBackupPath).toMatch(/\.broken-/);
expect(readHarnessReceiptState(home)).toEqual({ state: 'absent' });
// consume
writeHarnessReceipt(home, receipt);
deleteHarnessReceipt(home);
expect(readHarnessReceiptState(home)).toEqual({ state: 'absent' });
});
});
describe('codexConfigPath honors CODEX_HOME', () => {
test('CODEX_HOME set → config.toml directly inside it; unset → ~/.codex/config.toml', async () => {
const dir = tmp();
await withEnv({ CODEX_HOME: dir }, async () => {
expect(codexConfigPath()).toBe(join(dir, 'config.toml'));
});
await withEnv({ CODEX_HOME: undefined }, async () => {
expect(codexConfigPath()).toContain(join('.codex', 'config.toml'));
});
await withEnv({ CODEX_HOME: ' ' }, async () => {
expect(codexConfigPath()).toContain(join('.codex', 'config.toml')); // blank trims to falsy
});
});
});
describe('claudeProjectsDir honors CLAUDE_CONFIG_DIR', () => {
test('transcript confinement root follows the configured Claude Code base', async () => {
const configDir = tmp();
await withEnv({ CLAUDE_CONFIG_DIR: configDir, HOME: tmp() }, async () => {
expect(claudeProjectsDir()).toBe(join(configDir, 'projects'));
});
});
});