Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
#!/usr/bin/env bun
/**
* Upgrade matrix (GBRA-224 W2): install published old releases, upgrade each
* through its own updater to one candidate, and check the candidate on the
* upgraded brain. Workflow: .github/workflows/upgrade-matrix.yml. Docs:
* docs/ci-upgrade-matrix.md.
*
* bun scripts/upgrade-matrix.ts plan --candidate <vX.Y.Z.W | sha | ''> [--profile full|pr] [--from v1,v2] --out plan.json
* bun scripts/upgrade-matrix.ts cell --plan plan.json --from <tag> --engine pglite|postgres --keys keyless|keyed
* [--brain repo-less|repo|both] [--postgres-url <superuser url>] [--fault corrupt-after-upgrade] --out-dir <dir>
* bun scripts/upgrade-matrix.ts summarize --plan plan.json --receipts <dir> --out summary.json
* bun scripts/upgrade-matrix.ts issue --summary summary.json [--dry-run]
*
* The plan resolves the candidate (tag, commit, tree) and the from-versions
* once and records them with the harness commit; cells and the summary read
* only the plan, so every job of a run agrees on what it tested.
*/
import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
import { execFileSync, spawnSync } from 'node:child_process';
import { join, resolve } from 'node:path';
import { fetchReleases, hasEnoughHistory, RELEASE_TAG, resolveFromVersions, stableWindow, type Candidate, type FromVersion, type Profile, type Release, type StableRecordTag } from './upgrade-matrix/versions.ts';
import { failingFrom, ISSUE_LABEL, ISSUE_MARKER, renderRedFrom } from './upgrade-matrix/marker.ts';
import { cellId, runCell, type BrainShape, type Engine, type Fault, type Keys } from './upgrade-matrix/cell.ts';
import { CHECKS, loadKnownExceptions, summarize, type CellSummary } from './upgrade-matrix/verdict.ts';
import { AGENT_FILED_LABEL } from './lib/gh-issue.ts';
const REPO = 'garrytan/gbrain';
const ROOT = resolve(import.meta.dir, '..');
const BT = '\x60';
export { ISSUE_LABEL, ISSUE_MARKER };
const argv = process.argv.slice(2);
const flag = (name: string, fallback?: string) => { const i = argv.indexOf(name); return i >= 0 && i + 1 < argv.length ? argv[i + 1]! : fallback; };
const git = (...args: string[]) => execFileSync('git', ['-C', ROOT, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
function ensureCommit(ref: string): string {
const has = spawnSync('git', ['-C', ROOT, 'rev-parse', '--verify', '--quiet', ref + '^{commit}'], { encoding: 'utf8' });
if (has.status === 0) return has.stdout.trim();
const fetch = RELEASE_TAG.test(ref) || ref === 'stable'
? ['fetch', '--quiet', '--no-tags', 'origin', '+refs/tags/' + ref + ':refs/tags/' + ref]
: ['fetch', '--quiet', '--no-tags', 'origin', ref];
execFileSync('git', ['-C', ROOT, ...fetch], { stdio: ['ignore', 'pipe', 'pipe'] });
return git('rev-parse', ref + '^{commit}');
}
const commitVersion = (sha: string) => git('show', sha + ':VERSION').split('\n')[0]!.trim();
const commitTime = (sha: string) => new Date(Number(git('log', '-1', '--format=%ct', sha)) * 1000).toISOString();
export interface Plan {
schema: 'gbrain-upgrade-matrix-plan/1';
harness: { sha: string; dirty: boolean; workflow_ref: string | null; workflow_sha: string | null; event: string | null; run_url: string | null };
candidate: Candidate;
profile: Profile | 'explicit';
from: Array<FromVersion & { sha: string }>;
skipped: Array<{ role: string; reason: string }>;
jobs: Array<{ from: string; engine: Engine; keys: Keys; brain: BrainShape | 'both' }>;
cells: string[];
}
async function plan(): Promise<void> {
const profile = flag('--profile', 'full') as Profile;
if (profile !== 'full' && profile !== 'pr') throw new Error('--profile takes full or pr');
const input = (flag('--candidate', '') ?? '').trim();
const stableRecords = profile === 'full' ? stableRecordTags() : [];
const releases = await fetchReleases(REPO, rs => {
const newest = rs[0];
if (!newest) return false;
const hint = candidateHint(rs, input) ?? newest;
return hasEnoughHistory(rs, hint) && stableWindow(stableRecords, hint).every(v => rs.some(r => r.version === v));
});
if (!releases.length) throw new Error('no published releases found');
let candidate: Candidate;
if (!input || RELEASE_TAG.test(input)) {
const rel = input ? releases.find(r => r.tag === input) : [...releases].sort((a, b) => Date.parse(b.published_at) - Date.parse(a.published_at))[0];
if (!rel) throw new Error('candidate ' + input + ' is not a published release');
const sha = ensureCommit(rel.tag);
candidate = { tag: rel.tag, sha, tree: git('rev-parse', sha + '^{tree}'), version: rel.version, published_at: rel.published_at };
} else {
const sha = ensureCommit(input);
candidate = { tag: null, sha, tree: git('rev-parse', sha + '^{tree}'), version: commitVersion(sha), published_at: commitTime(sha) };
}
const explicit = flag('--from');
let from: FromVersion[];
let skipped: Plan['skipped'] = [];
if (explicit) {
from = explicit.split(',').map(t => t.trim()).filter(Boolean).map(tag => {
const m = RELEASE_TAG.exec(tag);
if (!m) throw new Error('--from takes release tags: ' + tag);
return { tag, version: m[1]!, published_at: releases.find(r => r.tag === tag)?.published_at ?? '', roles: ['explicit' as never] };
});
} else {
const resolved = resolveFromVersions(releases, candidate, { profile, stableVersion: stableVersion(), stableRecords });
from = resolved.from;
skipped = resolved.skipped;
}
const withSha = from.map(f => ({ ...f, sha: ensureCommit(f.tag) }));
const reduced = profile === 'pr' && !explicit;
const keys: Keys[] = reduced ? ['keyless'] : ['keyless', 'keyed'];
const brain: BrainShape | 'both' = reduced ? 'repo-less' : 'both';
const jobs = withSha.flatMap(f => (['pglite', 'postgres'] as Engine[]).flatMap(engine => keys.map(k => ({ from: f.tag, engine, keys: k, brain }))));
const cells = jobs.flatMap(j => (j.brain === 'both' ? ['repo-less', 'repo'] : [j.brain]).map(b => cellId({ from: { tag: j.from }, engine: j.engine, keys: j.keys, brain: b })));
const out: Plan = {
schema: 'gbrain-upgrade-matrix-plan/1',
harness: {
sha: git('rev-parse', 'HEAD'), dirty: git('status', '--porcelain', '--untracked-files=no').length > 0,
workflow_ref: process.env.GITHUB_WORKFLOW_REF ?? null, workflow_sha: process.env.GITHUB_WORKFLOW_SHA ?? null, event: process.env.GITHUB_EVENT_NAME ?? null,
run_url: process.env.GITHUB_RUN_ID ? (process.env.GITHUB_SERVER_URL ?? 'https://github.com') + '/' + (process.env.GITHUB_REPOSITORY ?? REPO) + '/actions/runs/' + process.env.GITHUB_RUN_ID : null,
},
candidate, profile: explicit ? 'explicit' : profile, from: withSha, skipped, jobs, cells,
};
writeFileSync(flag('--out', 'upgrade-matrix-plan.json')!, JSON.stringify(out, null, 2) + '\n');
if (process.env.GITHUB_OUTPUT) appendFileSync(process.env.GITHUB_OUTPUT, 'matrix=' + JSON.stringify({ include: jobs }) + '\ncandidate_sha=' + candidate.sha + '\n');
console.log('candidate ' + (candidate.tag ?? '(commit)') + ' ' + candidate.sha.slice(0, 12) + ' v' + candidate.version + '; from ' + withSha.map(f => f.tag + ' [' + f.roles.join(',') + ']').join(', ')
+ (skipped.length ? '; skipped ' + skipped.map(s => s.role + ': ' + s.reason).join('; ') : '') + '; ' + cells.length + ' cells in ' + jobs.length + ' jobs');
}
/** The stable tag's release version, or null when the tag does not exist or cannot be read. */
function stableVersion(): string | null {
const ls = spawnSync('git', ['-C', ROOT, 'ls-remote', '--tags', 'origin', 'refs/tags/stable'], { encoding: 'utf8' });
if (ls.status !== 0 || !ls.stdout.trim()) return null;
try { return commitVersion(ensureCommit('stable')); } catch { return null; }
}
/** Every stable-v<version> record tag on origin with its creation time (the promotion), fetched first. */
function stableRecordTags(): StableRecordTag[] {
execFileSync('git', ['-C', ROOT, 'fetch', '--quiet', '--no-tags', '--force', 'origin', '+refs/tags/stable-v*:refs/tags/stable-v*'], { stdio: ['ignore', 'pipe', 'pipe'] });
const out = git('for-each-ref', '--format=%(refname:strip=2)%09%(creatordate:iso-strict)', 'refs/tags/stable-v*');
return out.split('\n').filter(Boolean).flatMap(line => {
const [name, date] = line.split('\t');
const m = /^stable-v(\d+\.\d+\.\d+(?:\.\d+)?)$/.exec(name ?? '');
return m && date ? [{ version: m[1]!, promoted_at: new Date(date).toISOString() }] : [];
});
}
function candidateHint(releases: Release[], input: string): { version: string; published_at: string } | null {
if (!input) return null;
const rel = releases.find(r => r.tag === input);
if (rel) return rel;
try { const sha = ensureCommit(input); return { version: commitVersion(sha), published_at: commitTime(sha) }; } catch { return null; }
}
async function cell(): Promise<void> {
const p = JSON.parse(readFileSync(flag('--plan', 'upgrade-matrix-plan.json')!, 'utf8')) as Plan;
const tag = flag('--from');
const from = p.from.find(f => f.tag === tag);
if (!from) throw new Error('--from ' + tag + ' is not in the plan (' + p.from.map(f => f.tag).join(', ') + ')');
const engine = flag('--engine') as Engine, keys = flag('--keys') as Keys, brainFlag = flag('--brain', 'both')!;
if (!['pglite', 'postgres'].includes(engine) || !['keyless', 'keyed'].includes(keys)) throw new Error('--engine pglite|postgres and --keys keyless|keyed are required');
const brains: BrainShape[] = brainFlag === 'both' ? ['repo-less', 'repo'] : [brainFlag as BrainShape];
const outDir = resolve(flag('--out-dir', 'upgrade-matrix-out')!);
mkdirSync(outDir, { recursive: true });
ensureCommit(from.sha);
ensureCommit(p.candidate.sha);
const exceptions = loadKnownExceptions();
let red = false;
for (const brain of brains) {
const receipt = await runCell({
from: { tag: from.tag, version: from.version, sha: from.sha, roles: from.roles }, candidate: p.candidate, engine, keys, brain,
harnessRoot: ROOT, harnessSha: git('rev-parse', 'HEAD'), workDir: join(outDir, 'cells'), cacheDir: resolve(flag('--cache-dir', join(outDir, 'cache'))!),
postgresUrl: flag('--postgres-url') ?? process.env.UPGRADE_MATRIX_POSTGRES_URL, fault: (flag('--fault') as Fault | undefined) ?? null, exceptions,
});
writeFileSync(join(outDir, 'receipt-' + receipt.id + '.json'), JSON.stringify(receipt, null, 2) + '\n');
const failures = receipt.failures as Array<{ check: string; detail: string }>;
console.log(String(receipt.verdict).toUpperCase() + ' ' + receipt.id + ' (' + receipt.elapsed_s + ' s)' + failures.map(f => '\n - ' + f.check + ': ' + f.detail.split('\n')[0]).join(''));
if (receipt.verdict !== 'pass' && receipt.verdict !== 'known_exception') red = true;
}
if (red) process.exitCode = 1;
}
function loadReceipts(dir: string): any[] {
const out: any[] = [];
const walk = (d: string) => {
for (const e of readdirSync(d, { withFileTypes: true })) {
const p = join(d, e.name);
if (e.isDirectory()) walk(p);
else if (/^(receipt|door)-.*\.json$/.test(e.name)) out.push(JSON.parse(readFileSync(p, 'utf8')));
}
};
if (existsSync(dir)) walk(dir);
return out;
}
export function buildSummary(p: Plan, receipts: any[]): any {
const doors = receipts.filter(r => r.schema === 'gbrain-upgrade-matrix-door/1');
const cellReceipts = receipts.filter(r => r.schema === 'gbrain-upgrade-matrix-cell/1');
const foreign = [...cellReceipts, ...doors].filter(r => r.candidate?.sha !== p.candidate.sha || r.harness_sha !== p.harness.sha);
const cells: CellSummary[] = cellReceipts.filter(r => !foreign.includes(r)).map(r => ({
id: r.id, from: r.from.tag, roles: r.from.roles, shape: [r.shape.engine, r.shape.keys, r.shape.brain].join(' '), verdict: r.verdict,
open: r.failures ?? [], excepted: (r.known_exceptions ?? []).map((e: any) => ({ check: e.check, issue: e.issue })), fault: r.fault,
}));
const s = summarize(p.cells, cells);
const doorRed = doors.filter(d => !foreign.includes(d) && d.verdict === 'fail');
const doorHold = doors.filter(d => !foreign.includes(d) && d.verdict === 'hold');
return {
schema: 'gbrain-upgrade-matrix-run/1', harness: p.harness, candidate: p.candidate, profile: p.profile, from: p.from, skipped: p.skipped,
status: s.red.length || foreign.length || doorRed.length ? 'red' : s.holds.length || doorHold.length ? 'hold' : 'green',
cells, red: [...s.red.map(c => c.id), ...doorRed.map(d => 'door:' + d.door)], holds: [...s.holds.map(c => c.id), ...doorHold.map(d => 'door:' + d.door)], foreign_receipts: foreign.map(r => r.id ?? r.door),
doors: doors.map(d => ({ door: d.door, verdict: d.verdict, reason: d.reason ?? null })),
};
}
function summarizeRun(): void {
const p = JSON.parse(readFileSync(flag('--plan', 'upgrade-matrix-plan.json')!, 'utf8')) as Plan;
const summary = buildSummary(p, loadReceipts(flag('--receipts', 'receipts')!));
writeFileSync(flag('--out', 'upgrade-matrix-summary.json')!, JSON.stringify(summary, null, 2) + '\n');
const md = renderSummary(summary);
console.log(md);
if (process.env.GITHUB_STEP_SUMMARY) appendFileSync(process.env.GITHUB_STEP_SUMMARY, md + '\n');
if (summary.status === 'red') process.exitCode = 1;
}
export function renderSummary(s: any): string {
const cellRow = (c: any) => '| ' + c.from + ' ' + c.shape + ' | ' + c.verdict + (c.fault ? ' (fault ' + c.fault + ')' : '') + ' | '
+ [...c.open.map((f: any) => f.check + ': ' + String(f.detail).split('\n')[0]!.replace(/\|/g, '/').slice(0, 160)), ...c.excepted.map((e: any) => e.check + ' (known: ' + e.issue + ')')].join('<br>') + ' |';
const lines = [
'## Upgrade matrix: ' + String(s.status).toUpperCase(),
'',
'Candidate ' + (s.candidate.tag ?? '(unreleased commit)') + ' ' + BT + s.candidate.sha + BT + ' (v' + s.candidate.version + ', tree ' + BT + s.candidate.tree.slice(0, 12) + BT + '); harness ' + BT + s.harness.sha.slice(0, 12) + BT + ' (' + (s.harness.workflow_ref ?? 'local') + ').',
'From: ' + s.from.map((f: any) => f.tag + ' (' + f.roles.join(', ') + ')').join(', ') + (s.skipped.length ? '. Skipped: ' + s.skipped.map((k: any) => k.role + ' (' + k.reason + ')').join('; ') : '') + '.',
'',
'| Cell | Verdict | Failures |',
'| --- | --- | --- |',
...s.cells.map(cellRow),
];
const missing = s.red.filter((id: string) => !id.startsWith('door:') && !s.cells.some((c: any) => c.id === id));
if (missing.length) lines.push('', 'No receipt: ' + missing.join(', '));
if (s.foreign_receipts.length) lines.push('', 'Receipts from another candidate or harness (ignored; the run is red): ' + s.foreign_receipts.join(', '));
for (const d of s.doors ?? []) lines.push('', 'Door ' + d.door + ': ' + String(d.verdict).toUpperCase() + (d.reason ? ' (' + d.reason + ')' : ''));
lines.push('', 'Checks: ' + Object.keys(CHECKS).map(k => BT + k + BT).join(', ') + '. Docs: docs/ci-upgrade-matrix.md');
return lines.join('\n');
}
async function issue(): Promise<void> {
const s = JSON.parse(readFileSync(flag('--summary', 'upgrade-matrix-summary.json')!, 'utf8'));
const dry = argv.includes('--dry-run');
const auth = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
const api = async (method: string, path: string, body?: unknown) => {
const res = await fetch('https://api.github.com/repos/' + (process.env.GITHUB_REPOSITORY ?? REPO) + path, {
method, headers: { accept: 'application/vnd.github+json', 'user-agent': 'gbrain-upgrade-matrix', ...(auth ? { authorization: 'Bearer ' + auth } : {}) }, body: body ? JSON.stringify(body) : undefined,
});
if (!res.ok) throw new Error(method + ' ' + path + ' returned HTTP ' + res.status + ': ' + (await res.text()).slice(0, 300));
return res.status === 204 ? null : res.json();
};
const existing = (await api('GET', '/issues?state=all&labels=' + ISSUE_LABEL + '&per_page=100') as any[]).find(i => !i.pull_request && String(i.body ?? '').includes(ISSUE_MARKER));
const body = ISSUE_MARKER + '\n' + renderRedFrom(failingFrom(s).from) + '\n' + renderSummary(s) + '\n\nRun: ' + (s.harness.run_url ?? '(local)')
+ '\n\nWhile this issue is open the daily stable check holds stable (docs/RELEASING.md#daily-stable-check); only a security or data-loss fix that is green on every from-version this issue does not name may pass it. The nightly matrix closes it when a later run is green.';
if (s.status === 'red') {
const title = 'Upgrade matrix red: upgrading to ' + (s.candidate.tag ?? s.candidate.sha.slice(0, 12)) + ' fails ' + s.red.length + ' cell(s)';
if (dry) { console.log((existing ? 'update #' + existing.number : 'create') + ': ' + title + '\n' + body); return; }
if (existing) {
await api('PATCH', '/issues/' + existing.number, { title, body, state: 'open' });
await api('POST', '/issues/' + existing.number + '/comments', { body: 'Still red on ' + (s.candidate.tag ?? s.candidate.sha) + ': ' + s.red.join(', ') + '. ' + (s.harness.run_url ?? '') });
console.log('updated #' + existing.number);
} else {
const created = await api('POST', '/issues', { title, body, labels: [ISSUE_LABEL, AGENT_FILED_LABEL] }) as any;
console.log('created #' + created.number);
}
} else if (s.status === 'green' && existing?.state === 'open') {
if (dry) { console.log('close #' + existing.number); return; }
await api('POST', '/issues/' + existing.number + '/comments', { body: 'Green on ' + (s.candidate.tag ?? s.candidate.sha) + ': every planned cell passed. ' + (s.harness.run_url ?? '') });
await api('PATCH', '/issues/' + existing.number, { state: 'closed', state_reason: 'completed' });
console.log('closed #' + existing.number);
} else console.log('no issue change (status ' + s.status + (existing ? ', issue #' + existing.number + ' ' + existing.state : '') + ')');
}
if (import.meta.main) {
const cmd = argv[0];
const run = cmd === 'plan' ? plan : cmd === 'cell' ? cell : cmd === 'summarize' ? async () => summarizeRun() : cmd === 'issue' ? issue : null;
if (!run) { console.error('usage: bun scripts/upgrade-matrix.ts plan|cell|summarize|issue (see the header)'); process.exit(2); }
await run();
}