Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBRA-224 W1: stable and alpha channels with stable as the default (client side).
*
* Covers: the evidence record and its generations, the typed stable codes in the background check (report only, never
* an alpha fallback), the update cache partitioned by channel and evidence policy (legacy entries never read, the
* warm-cache default flip, reversed refresh completion), never downgrading and the known_bad move, the per-channel
* time-based snooze across alpha releases and a stable rollback, the one-time channel notice, and the check-only and
* doctor surfaces. Every flow runs on a repo-less brain and on a repo brain: channel state is file-plane under
* GBRAIN_HOME and never reads the repository.
*
* Serial: stubs globalThis.fetch and process-global env.
*/
import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { spawnSync } from 'node:child_process';
import { VERSION } from '../src/version.ts';
import { parseSemver } from '../src/core/semver.ts';
import {
STABLE_EVIDENCE_POLICY,
isCacheFresh,
offeredVersion,
parseMarker,
pendingUpgradeVersion,
readSnooze,
readUpdateCache,
snoozeHolds,
writeSnooze,
writeUpdateCache,
} from '../src/core/self-upgrade.ts';
import { STABLE_RECORD_URL, fetchStableRecord, parseStableRecord, requiredEvidenceKeys, sanitizeCause } from '../src/core/stable-channel.ts';
import { refreshUpdateCache } from '../src/commands/check-update.ts';
import { runSelfUpgrade } from '../src/commands/self-upgrade.ts';
import { CHANNEL_NOTICE_TEXT, maybeEmitChannelNotice } from '../src/core/release-channel-notice.ts';
import { checkSelfUpgradeHealth } from '../src/commands/doctor/checks/upgrade-health.ts';
const v = parseSemver(VERSION)!;
const AHEAD = `${v[0]}.${v[1]}.${v[2] + 5}.0`;
const AHEAD2 = `${v[0]}.${v[1]}.${v[2] + 9}.0`;
const BEHIND = `${v[0]}.${v[1]}.${Math.max(0, v[2] - 5)}.0`;
const SOAK = 'https://github.com/garrytan/gbrain/actions/runs/42';
const MATRIX = 'https://github.com/garrytan/gbrain/actions/runs/43';
const record = (version: string, over: Record<string, unknown> = {}) => JSON.stringify({ schema: 1, channel: 'stable', version, commit: 'a'.repeat(40), tree: 'b'.repeat(40), soak_run: SOAK, known_bad: [], ...over });
const realFetch = globalThis.fetch;
const realLog = console.log;
let home: string;
let saved: Record<string, string | undefined>;
let fetched: string[];
function serve(routes: { record?: string | null; recordStatus?: number; version?: string }): void {
fetched = [];
globalThis.fetch = (async (url: unknown) => {
const u = String(url);
fetched.push(u);
if (u === STABLE_RECORD_URL) {
if (routes.record === null) throw new Error('getaddrinfo ENOTFOUND raw.githubusercontent.com');
return new Response(routes.record ?? 'Not Found', { status: routes.record === undefined ? 404 : routes.recordStatus ?? 200 });
}
if (u.endsWith('/latest-stable/VERSION')) return new Response(`${routes.version ?? AHEAD2}\n`);
return new Response('', { status: 200 });
}) as typeof fetch;
}
const dotG = () => join(home, '.gbrain');
function writeConfig(extra: Record<string, unknown> = {}, brain: 'repo-less' | 'repo' = 'repo-less'): void {
mkdirSync(dotG(), { recursive: true });
const base: Record<string, unknown> = { engine: 'pglite', database_path: join(home, 'brain.pglite') };
if (brain === 'repo') {
const repo = join(home, 'brain-repo');
mkdirSync(repo, { recursive: true });
spawnSync('git', ['init', '-q', repo]);
base.sync = { repo_path: repo };
}
writeFileSync(join(dotG(), 'config.json'), JSON.stringify({ ...base, ...extra }));
}
beforeEach(() => {
saved = { GBRAIN_HOME: process.env.GBRAIN_HOME, GBRAIN_RELEASE_CHANNEL: process.env.GBRAIN_RELEASE_CHANNEL, GBRAIN_SELF_UPGRADE_MODE: process.env.GBRAIN_SELF_UPGRADE_MODE };
home = mkdtempSync(join(tmpdir(), 'gbrain-w1-'));
process.env.GBRAIN_HOME = home;
delete process.env.GBRAIN_RELEASE_CHANNEL;
delete process.env.GBRAIN_SELF_UPGRADE_MODE;
});
afterEach(() => {
globalThis.fetch = realFetch;
console.log = realLog;
for (const [k, val] of Object.entries(saved)) { if (val === undefined) delete process.env[k]; else process.env[k] = val; }
rmSync(home, { recursive: true, force: true });
});
describe('evidence record generations', () => {
test('generation 1 (soak only) is valid until the matrix cutover; from the cutover on matrix_run is required', () => {
expect(STABLE_EVIDENCE_POLICY).toBe('stable-record-v1;matrix-from=none');
expect(requiredEvidenceKeys('0.60.900.0')).toEqual(['soak_run']);
expect(parseStableRecord(record('0.60.900.0'))).toMatchObject({ ok: true });
const cut = '0.60.500.0';
expect(requiredEvidenceKeys('0.60.499.0', cut)).toEqual(['soak_run']);
expect(requiredEvidenceKeys('0.60.500.0', cut)).toEqual(['soak_run', 'matrix_run']);
expect(parseStableRecord(record('0.60.499.0'), cut)).toMatchObject({ ok: true, record: { matrix_run: null } });
expect(parseStableRecord(record('0.60.500.0'), cut)).toEqual({ ok: false, cause: 'the record for 0.60.500.0 lacks the evidence key matrix_run (a run of garrytan/gbrain)' });
expect(parseStableRecord(record('0.60.501.0', { matrix_run: MATRIX }), cut)).toMatchObject({ ok: true, record: { matrix_run: MATRIX } });
});
test('a record is rejected for a missing or foreign soak run, bad commit or tree, bad known_bad, or listing itself as known_bad', () => {
for (const over of [{ soak_run: undefined }, { soak_run: 'https://github.com/acme-example/gbrain/actions/runs/1' }, { commit: 'abc' }, { tree: undefined }, { known_bad: 'x' }, { known_bad: ['0.60.900.0'] }, { schema: 2 }]) {
expect(parseStableRecord(record('0.60.900.0', over)).ok).toBe(false);
}
expect(parseStableRecord('not json')).toEqual({ ok: false, cause: 'the record is not JSON' });
});
test('fetch: 404 is stable_missing, other statuses and network failures stable_unreadable, a bad body stable_invalid; causes are sanitized', async () => {
serve({});
expect(await fetchStableRecord()).toMatchObject({ ok: false, code: 'stable_missing' });
serve({ record: 'x', recordStatus: 500 });
expect(await fetchStableRecord()).toMatchObject({ ok: false, code: 'stable_unreadable', cause: 'the stable record answered HTTP 500' });
serve({ record: null });
expect(await fetchStableRecord()).toMatchObject({ ok: false, code: 'stable_unreadable' });
serve({ record: '{"schema":1}' });
expect(await fetchStableRecord()).toMatchObject({ ok: false, code: 'stable_invalid' });
const userinfo = ['user', 'hunter2'].join(':');
expect(sanitizeCause(`fetch https://${userinfo}@example.com/x failed\n token ghp_ABCDEFGHIJKLMNOP`)).toBe('fetch https://example.com/x failed token [redacted]');
expect(sanitizeCause('x'.repeat(500))).toHaveLength(200);
});
});
for (const brain of ['repo-less', 'repo'] as const) {
describe(`background check and cache (${brain} brain)`, () => {
test('the default is stable: the check reads only the evidence record and writes the stable partition', async () => {
writeConfig({}, brain);
serve({ record: record(AHEAD) });
await refreshUpdateCache();
expect(fetched).toEqual([STABLE_RECORD_URL]);
expect(readUpdateCache('stable')).toMatchObject({ channel: 'stable', policy: STABLE_EVIDENCE_POLICY, latest: AHEAD, marker: { kind: 'upgrade_available', latest: AHEAD }, error: null });
expect(readUpdateCache('alpha')).toBeNull();
expect(pendingUpgradeVersion(VERSION)).toBe(AHEAD);
});
test('missing, invalid and unreadable stable are recorded and reported, never offered and never replaced by alpha', async () => {
writeConfig({}, brain);
serve({ record: record(AHEAD) });
await refreshUpdateCache();
serve({ record: null });
await refreshUpdateCache();
expect(readUpdateCache('stable')).toMatchObject({ error: { code: 'stable_unreadable' }, marker: { latest: AHEAD } });
serve({});
await refreshUpdateCache();
expect(readUpdateCache('stable')).toMatchObject({ error: { code: 'stable_missing' }, marker: null, latest: null });
expect(pendingUpgradeVersion(VERSION)).toBeNull();
serve({ record: record(AHEAD, { soak_run: undefined }) });
await refreshUpdateCache();
expect(readUpdateCache('stable')).toMatchObject({ error: { code: 'stable_invalid', cause: expect.stringContaining('soak_run') } });
expect(fetched.some(u => u.includes('latest-stable'))).toBe(false);
expect(readUpdateCache('alpha')).toBeNull();
});
test('warm-cache default flip: a legacy unpartitioned cache from the old latest default is never read', async () => {
writeConfig({}, brain);
writeFileSync(join(dotG(), 'last-update-check'), `UPGRADE_AVAILABLE ${VERSION} ${AHEAD2}\n`);
writeFileSync(join(dotG(), 'update-snoozed'), `${AHEAD2} 1 ${Date.now()}\n`);
expect(readUpdateCache()).toBeNull();
expect(pendingUpgradeVersion(VERSION)).toBeNull();
serve({ record: record(AHEAD) });
await refreshUpdateCache();
expect(pendingUpgradeVersion(VERSION)).toBe(AHEAD);
expect(existsSync(join(dotG(), 'last-update-check'))).toBe(false);
});
test('partitions: switching channel reads that channel\'s answer; another policy\'s entry is invalid; an older refresh never overwrites a newer one', async () => {
writeConfig({}, brain);
writeUpdateCache({ kind: 'upgrade_available', current: VERSION, latest: AHEAD }, { channel: 'stable', checkedAt: 2_000 });
writeUpdateCache({ kind: 'upgrade_available', current: VERSION, latest: AHEAD2 }, { channel: 'alpha', checkedAt: 2_000 });
expect(pendingUpgradeVersion(VERSION)).toBe(AHEAD);
process.env.GBRAIN_RELEASE_CHANNEL = 'latest';
expect(pendingUpgradeVersion(VERSION)).toBe(AHEAD2);
delete process.env.GBRAIN_RELEASE_CHANNEL;
writeConfig({ self_upgrade: { channel: 'alpha' } }, brain);
expect(pendingUpgradeVersion(VERSION)).toBe(AHEAD2);
writeUpdateCache({ kind: 'up_to_date', current: VERSION }, { channel: 'alpha', checkedAt: 1_000 });
expect(readUpdateCache('alpha')?.latest).toBe(AHEAD2);
const path = join(dotG(), 'update-check.stable.json');
writeFileSync(path, readFileSync(path, 'utf8').replace(STABLE_EVIDENCE_POLICY, 'stable-record-v1;matrix-from=0.60.1.0'));
expect(readUpdateCache('stable')).toBeNull();
});
for (const [shape, mtimeOffset] of [['only checked_at is ahead', -2 * 3600_000], ['the file was written while the clock was ahead', 24 * 3600_000]] as const) {
test(`#8795: a cache stamped a day in the future (${shape}) is stale, and the next check replaces it with the withdrawal`, async () => {
writeConfig({}, brain);
const path = join(dotG(), 'update-check.stable.json');
writeUpdateCache({ kind: 'up_to_date', current: VERSION }, { channel: 'stable', checkedAt: Date.now() + 24 * 3600_000, latest: VERSION });
const mtime = (Date.now() + mtimeOffset) / 1000;
utimesSync(path, mtime, mtime);
expect(isCacheFresh(readUpdateCache('stable')!, Date.now())).toBe(false);
serve({ record: record(BEHIND, { known_bad: [VERSION] }) });
await refreshUpdateCache();
expect(readUpdateCache('stable')).toMatchObject({ latest: BEHIND, knownBad: [VERSION], error: null, marker: { kind: 'upgrade_available', latest: BEHIND } });
expect(isCacheFresh(readUpdateCache('stable')!, Date.now())).toBe(true);
expect(pendingUpgradeVersion(VERSION)).toBe(BEHIND);
});
}
test('#8795: a stored check a few seconds ahead still wins over an older refresh', () => {
writeConfig({}, brain);
const now = Date.now();
writeUpdateCache({ kind: 'upgrade_available', current: VERSION, latest: AHEAD2 }, { channel: 'stable', checkedAt: now + 30_000 });
expect(isCacheFresh(readUpdateCache('stable')!, now)).toBe(true);
writeUpdateCache({ kind: 'up_to_date', current: VERSION }, { channel: 'stable', checkedAt: now });
expect(readUpdateCache('stable')?.latest).toBe(AHEAD2);
});
test('#8795: a cache file a network home\'s file server stamped ahead, checked by this clock, stays fresh', () => {
writeConfig({}, brain);
const path = join(dotG(), 'update-check.stable.json');
writeUpdateCache({ kind: 'upgrade_available', current: VERSION, latest: AHEAD }, { channel: 'stable' });
const mtime = (Date.now() + 10 * 60_000) / 1000;
utimesSync(path, mtime, mtime);
expect(isCacheFresh(readUpdateCache('stable')!, Date.now())).toBe(true);
expect(pendingUpgradeVersion(VERSION)).toBe(AHEAD);
});
test('an invalid configured channel checks and offers nothing', async () => {
writeConfig({ self_upgrade: { channel: 'nightly' } }, brain);
writeUpdateCache({ kind: 'upgrade_available', current: VERSION, latest: AHEAD }, { channel: 'stable' });
serve({ record: record(AHEAD2) });
await refreshUpdateCache();
expect(fetched).toEqual([]);
expect(pendingUpgradeVersion(VERSION)).toBeNull();
});
test('never downgrade: an install ahead of stable is offered nothing until stable passes it; a withdrawn install is offered stable', async () => {
writeConfig({}, brain);
expect(offeredVersion(VERSION, BEHIND, [])).toBeNull();
expect(offeredVersion(VERSION, VERSION, [VERSION])).toBeNull();
expect(offeredVersion(VERSION, BEHIND, [VERSION])).toBe(BEHIND);
serve({ record: record(BEHIND) });
await refreshUpdateCache();
expect(pendingUpgradeVersion(VERSION)).toBeNull();
serve({ record: record(BEHIND, { known_bad: [VERSION] }) });
await refreshUpdateCache();
expect(readUpdateCache('stable')).toMatchObject({ latest: BEHIND, knownBad: [VERSION], marker: { kind: 'upgrade_available', latest: BEHIND } });
expect(pendingUpgradeVersion(VERSION)).toBe(BEHIND);
});
test('snooze holds its full window across any number of alpha releases; a stable rollback below the snoozed version clears it', () => {
writeConfig({}, brain);
const now = Date.now();
writeSnooze(AHEAD, now, 'alpha');
for (let i = 1; i <= 30; i++) expect(snoozeHolds(`${v[0]}.${v[1]}.${v[2] + 5 + i}.0`, now + i * 3_600_000 * 0.7, 'alpha')).toBe(true);
expect(snoozeHolds(AHEAD2, now + 25 * 3_600_000, 'alpha')).toBe(false);
writeSnooze(AHEAD2, now, 'stable');
expect(snoozeHolds(AHEAD2, now + 1000, 'stable')).toBe(true);
expect(snoozeHolds(AHEAD, now + 2000, 'stable')).toBe(false);
expect(readSnooze('stable')).toBeNull();
expect(readSnooze('alpha')).not.toBeNull();
});
test('the one-time notice prints once per GBRAIN_HOME on stderr, never as a marker, never under --json or MCP, and not when a channel was chosen', () => {
writeConfig({}, brain);
const lines: string[] = [];
const write = (l: string) => { lines.push(l); };
expect(maybeEmitChannelNotice({ command: 'search', args: ['search', 'x', '--json'], cfg: null, write })).toBe(false);
expect(maybeEmitChannelNotice({ command: 'serve', args: ['serve'], cfg: null, write })).toBe(false);
expect(maybeEmitChannelNotice({ command: 'mcp', args: ['mcp'], cfg: null, write })).toBe(false);
expect(maybeEmitChannelNotice({ command: 'search', args: ['search'], cfg: { self_upgrade: { channel: 'stable' } }, write })).toBe(false);
expect(maybeEmitChannelNotice({ command: 'search', args: ['search'], cfg: null, env: 'alpha', write })).toBe(false);
expect(lines).toEqual([]);
expect(maybeEmitChannelNotice({ command: 'search', args: ['search'], cfg: null, write })).toBe(true);
expect(maybeEmitChannelNotice({ command: 'query', args: ['query'], cfg: null, write })).toBe(false);
expect(lines).toEqual([`${CHANNEL_NOTICE_TEXT}\n`]);
expect(lines[0]).toStartWith('[gbrain notice release_channel] ');
expect(lines[0]).toContain('stable channel');
expect(lines[0]).toContain('gbrain config set self_upgrade.channel alpha');
expect(parseMarker(lines[0]!)).toBeNull();
expect(lines[0]).not.toContain('UPGRADE_AVAILABLE');
});
test('self-upgrade --check-only --json names the channel, its source and the typed error; --snooze writes the channel snooze', async () => {
writeConfig({}, brain);
const out: string[] = [];
console.log = (...a: unknown[]) => { out.push(a.join(' ')); };
serve({});
await runSelfUpgrade(['--check-only', '--json']);
expect(JSON.parse(out.pop()!)).toMatchObject({ channel: 'stable', channel_source: 'default', update_available: false, error: { code: 'stable_missing', fix: expect.stringContaining('gbrain config set self_upgrade.channel alpha') } });
serve({ record: record(BEHIND, { known_bad: [VERSION] }) });
await runSelfUpgrade(['--check-only', '--json']);
expect(JSON.parse(out.pop()!)).toMatchObject({ channel: 'stable', update_available: true, latest_version: BEHIND, withdrawn: true });
serve({ record: record(AHEAD) });
await runSelfUpgrade(['--check-only', '--json', '--channel', 'latest']);
expect(JSON.parse(out.pop()!)).toMatchObject({ channel: 'alpha', channel_source: 'flag', latest_version: AHEAD2 });
serve({ record: record(AHEAD) });
await runSelfUpgrade(['--check-only', '--json']);
await runSelfUpgrade(['--snooze', '--json']);
expect(JSON.parse(out.pop()!)).toMatchObject({ snoozed: true, channel: 'stable', version: AHEAD, level: 1 });
expect(readSnooze('stable')).toMatchObject({ version: AHEAD, level: 1 });
});
test('self-upgrade --check-only keeps the verified answer on stable_unreadable and drops it on stable_missing', async () => {
writeConfig({}, brain);
console.log = () => {};
serve({ record: record(AHEAD) });
await refreshUpdateCache();
serve({ record: null });
await runSelfUpgrade(['--check-only', '--json']);
expect(readUpdateCache('stable')).toMatchObject({ error: { code: 'stable_unreadable' }, marker: { kind: 'upgrade_available', latest: AHEAD } });
serve({});
await runSelfUpgrade(['--check-only', '--json']);
expect(readUpdateCache('stable')).toMatchObject({ error: { code: 'stable_missing' }, marker: null });
});
test('doctor names a channel that was set and its source (the default stays mode=notify), and warns with the code when stable failed', async () => {
writeConfig({}, brain);
expect(checkSelfUpgradeHealth().message).toBe('mode=notify');
process.env.GBRAIN_RELEASE_CHANNEL = 'latest';
expect(checkSelfUpgradeHealth().message).toContain('channel=alpha (env)');
delete process.env.GBRAIN_RELEASE_CHANNEL;
serve({});
await refreshUpdateCache();
const failing = checkSelfUpgradeHealth();
expect(failing.status).toBe('warn');
expect(failing.message).toContain('stable_missing');
expect(failing.message).toContain('gbrain config set self_upgrade.channel alpha');
writeConfig({ self_upgrade: { channel: 'nightly' } }, brain);
expect(checkSelfUpgradeHealth()).toMatchObject({ status: 'warn', message: expect.stringContaining("self_upgrade.channel is 'nightly'") });
});
});
}