Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: gate in-agent setup on the bundle's Bun, with an exact rerun command

garrytan6e5b590c5d62
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7eeadc1394..7137770dca 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,7 @@ On Bun 1.4.0 to 1.4.2 a postgres.js connection over TLS keeps every chunk it rec
| `gbrain upgrade` or autopilot on a source install whose host Bun is below 1.4.4 | upgraded | stops before swapping (autopilot holds) with the same fix |
| Code importing gbrain as a library on an older Bun | ran | guarded outbound HTTP calls (URL checks, remote images, HTTP integrations) throw `UNSUPPORTED_RUNTIME` |
| Cloud sandbox setup with a preinstalled older Bun | used it | installs a current Bun with npm and stops before cloning if that Bun is still below 1.4.4 |
+| In-agent setup (Grok Bot, Muse) from a helper that stages Bun below 1.4.4 | installed a runtime the CLI then refused | stops with `runtime_below_floor` before writing anything and prints the exact command to fetch the current helper and rerun |
### What to watch for after you upgrade
@@ -36,6 +37,7 @@ On Bun 1.4.0 to 1.4.2 a postgres.js connection over TLS keeps every chunk it rec
- `src/core/runtime-version.ts`, `package.json` `engines.bun`: `MINIMUM_BUN_VERSION` and `SECURE_BUN_VERSION` are both 1.4.4; the CLI gate, doctor's `bun_runtime`, the guarded-HTTP check and the upgrade floor gate read them.
- `src/core/behavior-change-notice.ts`: a `bun_floor_1_4_4` row tells existing installs about the new floor.
+- `src/core/agent-install/setup.ts`: in-agent setup checks the Bun in its bundle (the runtime the launcher is pinned to) against the floor before it writes anything (`test/agent-install-bun-floor.test.ts`).
- `templates/bootstrap/cloud-setup-script.sh`: the preinstalled-Bun check uses the 1.4.4 floor and checks the npm-installed Bun before cloning.
- CI: the Bun 1.4.0 matrix cells are gone from `test.yml`, `native-locks.yml`, `persistence-validation.yml`, `convergence-nightly.yml` and `promote-stable.yml`. The remaining `unit-postgres-arms` cell runs both the PGLite and Postgres arms, so the PGLite side of the `*.slow.test.ts` suites still runs on GitHub CI (guarded by `test/scripts/postgres-unit-arms.test.ts`). `docs/test-audit/2026-10-04/expected-deltas.tsv` records the moved receipt lane.
- Bench and VM setup scripts, the System One Ubicloud runner and the stable-promotion workflow pin Bun 1.4.4.
diff --git a/skills/migrations/v0.60.467.0.md b/skills/migrations/v0.60.467.0.md
index f3911e235f..4efcaaf720 100644
--- a/skills/migrations/v0.60.467.0.md
+++ b/skills/migrations/v0.60.467.0.md
@@ -57,9 +57,11 @@ so ask before running `bun upgrade` on their behalf.
environment's setup script again. An in-agent install (Grok Bot, Muse)
upgrades with a freshly fetched helper: a `bin/gbrain-setup` written
before v0.60.379.0 stages Bun 1.4.3, and setup then stops with
- `runtime_below_floor` without changing the install. Fetch the current
- `setup-in-agent.sh` (see `docs/guides/in-agent-setup.md`) and run it with
- `--upgrade`.
+ `runtime_below_floor` without changing the install. Its message ends with
+ the exact command to run: it fetches the current `setup-in-agent.sh` and
+ reruns it with the install's `--root`, `--harness` and flags. Before an
+ `--upgrade`, make the verified backup `docs/guides/in-agent-setup.md`
+ describes.
5. **Verify.**
```bash
diff --git a/skills/skills.lock.json b/skills/skills.lock.json
index 394f4ad094..0ccb1ff0e9 100644
--- a/skills/skills.lock.json
+++ b/skills/skills.lock.json
@@ -170,7 +170,7 @@
"migrations/v0.60.37.0.md": "e0e9d8ab0adb14cfb55d67f821614f25e0ab2f6281a1a1bfc10faefc95312015",
"migrations/v0.60.44.0.md": "415d05b4587e49c7bdad40b55878b0b50f5330915a5e49065638fb6680ced3fe",
"migrations/v0.60.45.0.md": "ed92f7b642f1e84e6381ef9e7e855db1ac7d20abd9b79a7bb359c707a04b8b9d",
- "migrations/v0.60.467.0.md": "0e7b362ff68e320dfa782fcc53a476a9ad0a6d24ea124387825d6f041b332f11",
+ "migrations/v0.60.467.0.md": "43311f26404d41af924d27a867e13c0683fe302b1a2c0ba4a7c99a8388db2baf",
"migrations/v0.60.47.0.md": "91a6015e3b85c6f2c8048680ee5873895ae2b1948bad8ba6cebce679c3ec7085",
"migrations/v0.60.5.0.md": "0d3ee19359a2740de08ac9ec388ddc15e7c72d663afe33832e1e54170528acab",
"migrations/v0.60.52.0.md": "ae49b2f51ba6288e4883d8bfda9f494f821e160e227164aa065a645d4e9ae87b",
diff --git a/src/core/agent-install/entry.ts b/src/core/agent-install/entry.ts
index 8cf993c52a..35d032b140 100644
--- a/src/core/agent-install/entry.ts
+++ b/src/core/agent-install/entry.ts
@@ -2,9 +2,8 @@ import { setupInAgent, type AgentSetupOptions } from './setup.ts';
import { AgentInstallError } from './state.ts';
import { BootstrapError } from '../bootstrap/lock.ts';
import { PgliteBusyError } from '../pglite-lock.ts';
-import { MINIMUM_BUN_VERSION, bunVersionMeets } from '../runtime-version.ts';
-export async function runAgentSetupCli(args: string[], bunVersion = Bun.version): Promise<number> {
+export async function runAgentSetupCli(args: string[]): Promise<number> {
const json = args.includes('--json');
if (args.includes('--help') || args.includes('-h')) {
console.log('setup-in-agent.sh --root ABS --harness grok-bot|muse [--adopt] [--upgrade] [--skills follow|memory-only] [--json]\nFresh installs follow the shared catalog with manual native loading; existing/adopted roots need explicit approval. Existing memory is never reset.');
@@ -20,7 +19,6 @@ export async function runAgentSetupCli(args: string[], bunVersion = Bun.version)
values[args[i]] = args[++i];
}
if (!values['--root'] || !values['--harness'] || !values['--bundle'] || !values['--source-ref']) throw new AgentInstallError('usage', 'Use the package-shipped setup-in-agent.sh helper with an absolute --root and --harness.');
- if (!bunVersionMeets(bunVersion, MINIMUM_BUN_VERSION)) throw new AgentInstallError('runtime_below_floor', `This GBrain release needs Bun ${MINIMUM_BUN_VERSION} or newer, but the setup helper staged Bun ${bunVersion}. Nothing was changed. Fetch the current helper from https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/scripts/setup-in-agent.sh and rerun it with --upgrade.`);
const result = await setupInAgent({ root: values['--root'], harness: values['--harness'] as AgentSetupOptions['harness'], bundle: values['--bundle'], sourceRef: values['--source-ref'], adopt: args.includes('--adopt'), upgrade: args.includes('--upgrade'), skills: values['--skills'] as AgentSetupOptions['skills'] });
if (json) console.log(JSON.stringify({ ok: true, ...result }));
else console.log(`${result.status}: ${result.launcher}\nInstructions: ${result.instructions}\nMaintenance: ${result.maintenance}\nShared skills: ${result.shared_skills.status} (${result.shared_skills.reason}). ${result.shared_skills.next_action}\nNative harness integration is unverified; enable the skill and test a new conversation.${result.search_mode_confirmation_required ? '\nRelay the init search-mode matrix and confirm the user’s choice before optional provider setup.' : ''}`);
diff --git a/src/core/agent-install/setup.ts b/src/core/agent-install/setup.ts
index 197bdd730d..c8c5c1331e 100644
--- a/src/core/agent-install/setup.ts
+++ b/src/core/agent-install/setup.ts
@@ -16,6 +16,7 @@ import {
type AgentHarness, type AgentInstallReceipt, type InstallArtifact,
} from './state.ts';
import { bunSpawn, bunSpawnSync } from '../spawn.ts';
+import { MINIMUM_BUN_VERSION, bunVersionMeets } from '../runtime-version.ts';
export interface AgentSetupOptions {
root: string;
@@ -183,6 +184,11 @@ export async function setupInAgent(options: AgentSetupOptions): Promise<AgentSet
const root = checkedRoot(options.root);
const adapter = harnessAdapter(options.harness);
if (!['grok-bot', 'muse'].includes(adapter.id) || !adapter.modes.includes('local-cli')) throw new AgentInstallError('unsupported_harness', 'This local setup supports Grok Bot and Muse personal agents.');
+ const identity = artifactFromBundle(options.bundle, options.sourceRef);
+ if (!bunVersionMeets(identity.bun_version, MINIMUM_BUN_VERSION)) {
+ const rerun = ['--root', root, '--harness', options.harness, ...(options.adopt ? ['--adopt'] : []), ...(options.upgrade ? ['--upgrade'] : []), ...(options.skills ? ['--skills', options.skills] : [])].map(shellQuote).join(' ');
+ throw new AgentInstallError('runtime_below_floor', `This GBrain release needs Bun ${MINIMUM_BUN_VERSION} or newer, but the setup bundle carries Bun ${identity.bun_version || 'of unknown version'}, so the helper that staged it is out of date. Nothing was changed. ${options.upgrade ? 'Make a verified backup first (docs/guides/in-agent-setup.md), then fetch' : 'Fetch'} the current helper and rerun setup: curl --fail --silent --show-error --location https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/scripts/setup-in-agent.sh --output /tmp/gbrain-setup.sh && bash /tmp/gbrain-setup.sh ${rerun}`);
+ }
if (!existsSync(dirname(root))) throw new AgentInstallError('parent_missing', 'Create and verify the persistent parent directory first.');
const existed = existsSync(root);
if (!existed) mkdirSync(root, { mode: 0o700 });
@@ -239,7 +245,6 @@ export async function setupInAgent(options: AgentSetupOptions): Promise<AgentSet
writeInstallReceipt(receipt);
delete receipt.last_failure;
let changed = false;
- const identity = artifactFromBundle(options.bundle, options.sourceRef);
if (receipt.artifact && !options.upgrade && identity.source_ref !== receipt.artifact.source_ref) throw new AgentInstallError('artifact_version_mismatch', 'Repair must use the recorded source commit; use --upgrade to explicitly change versions.');
const upgrade = !!options.upgrade && receipt.artifact?.source_ref !== identity.source_ref;
if (!receipt.artifact || upgrade || !artifactUsable(root, receipt.artifact)) {
diff --git a/test/agent-install-bun-floor.test.ts b/test/agent-install-bun-floor.test.ts
index d0ed12cda7..2762b139d1 100644
--- a/test/agent-install-bun-floor.test.ts
+++ b/test/agent-install-bun-floor.test.ts
@@ -1,31 +1,86 @@
/**
* An in-agent helper written before Bun 1.4.4 became the floor stages Bun 1.4.3
- * for --upgrade. The new package's setup entry must refuse that runtime before
- * it commits an artifact the CLI then refuses to start (#7674).
+ * for --upgrade. Setup must refuse the bundle's own runtime (the binary the
+ * launcher is pinned to) before it writes anything, and say exactly how to
+ * rerun (#7674).
*/
import { afterEach, expect, spyOn, test } from 'bun:test';
-import { existsSync, mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { runAgentSetupCli } from '../src/core/agent-install/entry.ts';
import { MINIMUM_BUN_VERSION } from '../src/core/runtime-version.ts';
-const roots: string[] = [];
-afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+const HELPER_URL = 'https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/scripts/setup-in-agent.sh';
+const temporaries: string[] = [];
+afterEach(() => { for (const dir of temporaries.splice(0)) rmSync(dir, { recursive: true, force: true }); });
-test('setup refuses a staged Bun below the floor before touching the install root', async () => {
- const root = mkdtempSync(join(tmpdir(), 'gbrain-agent-floor-'));
- roots.push(root);
- const calls: string[] = [];
- const output = spyOn(console, 'log').mockImplementation((line: string) => { calls.push(line); });
+function fixture(stagedBunVersion: string) {
+ const temporary = mkdtempSync(join(tmpdir(), 'gbrain-agent-floor-'));
+ temporaries.push(temporary);
+ const bundle = join(temporary, 'bundle');
+ const pkg = join(bundle, 'app', 'node_modules', 'gbrain');
+ mkdirSync(join(pkg, 'src'), { recursive: true });
+ mkdirSync(join(pkg, 'scripts'), { recursive: true });
+ writeFileSync(join(pkg, 'package.json'), JSON.stringify({ name: 'gbrain', version: '0.0.0-floor-test' }));
+ writeFileSync(join(pkg, 'src', 'cli.ts'), '');
+ writeFileSync(join(pkg, 'scripts', 'setup-in-agent.sh'), '');
+ writeFileSync(join(bundle, 'bun'), `#!/bin/sh\nif [ "$1" = --version ]; then echo '${stagedBunVersion}'; exit 0; fi\nexit 7\n`);
+ chmodSync(join(bundle, 'bun'), 0o700);
+ return { root: join(temporary, 'brain dir'), bundle };
+}
+
+async function run(args: string[]): Promise<{ exit: number; result: Record<string, unknown> }> {
+ const lines: string[] = [];
+ const log = spyOn(console, 'log').mockImplementation((line: string) => { lines.push(line); });
+ const error = spyOn(console, 'error').mockImplementation(() => {});
+ const stderr = spyOn(process.stderr, 'write').mockImplementation(() => true);
try {
- const args = ['--root', root, '--harness', 'grok-bot', '--bundle', join(root, 'bundle'), '--source-ref', 'a'.repeat(40), '--json'];
- expect(await runAgentSetupCli(args, '1.4.3')).toBe(1);
- } finally { output.mockRestore(); }
- const result = JSON.parse(calls.pop()!);
+ const exit = await runAgentSetupCli(args);
+ return { exit, result: JSON.parse(lines.pop() ?? '{}') };
+ } finally { log.mockRestore(); error.mockRestore(); stderr.mockRestore(); }
+}
+
+const setupArgs = (root: string, bundle: string, extra: string[] = []) =>
+ ['--root', root, '--harness', 'grok-bot', '--bundle', bundle, '--source-ref', 'a'.repeat(40), ...extra, '--json'];
+
+test('setup refuses a bundle carrying Bun below the floor before writing anything', async () => {
+ const { root, bundle } = fixture('1.4.3');
+ const { exit, result } = await run(setupArgs(root, bundle, ['--upgrade', '--skills', 'memory-only']));
+ expect(exit).toBe(1);
expect(result).toMatchObject({ ok: false, reason: 'runtime_below_floor' });
- expect(result.message).toContain(`needs Bun ${MINIMUM_BUN_VERSION} or newer, but the setup helper staged Bun 1.4.3`);
- expect(result.message).toContain('--upgrade');
- expect(readdirSync(root)).toEqual([]);
- expect(existsSync(join(root, '.gbrain'))).toBe(false);
+ expect(result.message).toContain(`needs Bun ${MINIMUM_BUN_VERSION} or newer, but the setup bundle carries Bun 1.4.3`);
+ expect(result.message).toContain('Make a verified backup first');
+ expect(result.message).toContain(`curl --fail --silent --show-error --location ${HELPER_URL} --output /tmp/gbrain-setup.sh && bash /tmp/gbrain-setup.sh --root '${root}' --harness grok-bot --upgrade --skills memory-only`);
+ expect(existsSync(root)).toBe(false);
+});
+
+test('a prerelease of the floor and an unparseable version are refused too', async () => {
+ for (const staged of [`${MINIMUM_BUN_VERSION}-canary.1`, '']) {
+ const { root, bundle } = fixture(staged);
+ const { exit, result } = await run(setupArgs(root, bundle));
+ expect(exit).toBe(1);
+ expect(result.reason).toBe('runtime_below_floor');
+ expect(result.message).not.toContain('backup');
+ expect(existsSync(root)).toBe(false);
+ }
+});
+
+test('a bundle carrying the floor itself passes the gate', async () => {
+ const { root, bundle } = fixture(MINIMUM_BUN_VERSION);
+ const { exit, result } = await run(setupArgs(root, bundle));
+ expect(exit).toBe(1);
+ expect(result.reason).not.toBe('runtime_below_floor');
+ expect(existsSync(root)).toBe(true);
+});
+
+test('missing arguments still answer usage (exit 2) before the floor check', async () => {
+ const { bundle } = fixture('1.4.3');
+ const { exit, result } = await run(['--harness', 'grok-bot', '--bundle', bundle, '--source-ref', 'a'.repeat(40), '--json']);
+ expect(exit).toBe(2);
+ expect(result.reason).toBe('usage');
+});
+
+test('the documented helper URL matches the one the refusal names', () => {
+ expect(readFileSync(join(import.meta.dir, '..', 'docs', 'guides', 'in-agent-setup.md'), 'utf8')).toContain(HELPER_URL);
});