Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes (third /ship invocation, pass 1)

garrytan70ce87afb50b
diff --git a/docs/guides/in-agent-setup.md b/docs/guides/in-agent-setup.md
index cc5269a85f..5529e1551b 100644
--- a/docs/guides/in-agent-setup.md
+++ b/docs/guides/in-agent-setup.md
@@ -354,6 +354,18 @@ bash /workspace/gbrain/bin/gbrain-setup --upgrade
Upgrade installs the currently stable package and applies its migrations.
Repair is not an upgrade, and neither operation resets the brain.
+A helper written before v0.60.379.0 stages a Bun below 1.4.4 (1.4.2 or 1.4.3),
+which current releases refuse: setup stops with `runtime_below_floor` before it
+changes anything and prints the command to run instead. It fetches the current
+helper and reruns setup with the same root, harness and flags:
+
+```bash
+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 --root /workspace/gbrain --harness grok-bot --upgrade
+```
+
To stop using GBrain, pause its native routine and disable its saved skill.
Keep the root and a protected backup until you deliberately choose to remove
the data. No daemon or system-level installation needs uninstalling. If using
@@ -367,6 +379,7 @@ hosted access, also revoke that installation's grant on the host.
| --- | --- | --- | --- | --- |
| Setup reports unowned state | Choose an empty root; use `--adopt` only after reviewing a compatible existing local brain | agent, after the user agrees | none | the setup receipt |
| Runtime executable disappeared | Run the retained helper or fetch it again with the same root | agent | none | the setup receipt |
+| `runtime_below_floor` | The helper is older than the Bun floor; make a verified backup, then run the fetch-and-rerun command the refusal prints | agent, after the user agrees to the upgrade | none | the setup receipt |
| Config is malformed or initialized memory is missing | Preserve the root; recover config or restore a full backup into a new root | agent, after the user agrees | `destructive` when restoring | the setup receipt |
| Generated instructions were edited | Preserve your edited file under a different name, then rerun repair and reattach your additions separately | agent | none | the setup receipt |
| `pglite_busy` | Wait for the active command to finish and retry; stop a long-lived server through its owning process before using finite CLI mode | agent | none | retry the read-only command |
diff --git a/skills/migrations/v0.60.467.0.md b/skills/migrations/v0.60.467.0.md
index 4efcaaf720..9c4850a401 100644
--- a/skills/migrations/v0.60.467.0.md
+++ b/skills/migrations/v0.60.467.0.md
@@ -56,7 +56,7 @@ so ask before running `bun upgrade` on their behalf.
the current script (`gbrain bootstrap cloud-setup-script`) into the
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
+ before v0.60.379.0 stages a Bun below 1.4.4 (1.4.2 or 1.4.3), and setup then stops with
`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
diff --git a/skills/skills.lock.json b/skills/skills.lock.json
index 0ccb1ff0e9..923c3a09d1 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": "43311f26404d41af924d27a867e13c0683fe302b1a2c0ba4a7c99a8388db2baf",
+ "migrations/v0.60.467.0.md": "a952646e4789afa6dfa3958772ee41781da12774e6f78b2ec89dd0fb19da5e56",
"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 35d032b140..d78e13555c 100644
--- a/src/core/agent-install/entry.ts
+++ b/src/core/agent-install/entry.ts
@@ -19,7 +19,7 @@ export async function runAgentSetupCli(args: string[]): Promise<number> {
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.');
- 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'] });
+ 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'], json });
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.' : ''}`);
return 0;
diff --git a/src/core/agent-install/setup.ts b/src/core/agent-install/setup.ts
index c8c5c1331e..d228621c52 100644
--- a/src/core/agent-install/setup.ts
+++ b/src/core/agent-install/setup.ts
@@ -18,6 +18,8 @@ import {
import { bunSpawn, bunSpawnSync } from '../spawn.ts';
import { MINIMUM_BUN_VERSION, bunVersionMeets } from '../runtime-version.ts';
+const SETUP_HELPER_URL = 'https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/scripts/setup-in-agent.sh';
+
export interface AgentSetupOptions {
root: string;
harness: AgentHarness;
@@ -27,6 +29,8 @@ export interface AgentSetupOptions {
adopt?: boolean;
upgrade?: boolean;
skills?: 'follow' | 'memory-only';
+ /** The caller reads JSON output; a refusal's rerun command keeps `--json`. */
+ json?: boolean;
}
export interface AgentSetupResult {
status: 'installed' | 'repaired' | 'unchanged';
@@ -184,10 +188,15 @@ 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}`);
+ // A bundle that cannot be read is reported inside the install below, where the receipt journals it.
+ let identity: ReturnType<typeof artifactFromBundle> | undefined;
+ try { identity = artifactFromBundle(options.bundle, options.sourceRef); } catch { identity = undefined; }
+ if (identity && !bunVersionMeets(identity.bun_version, MINIMUM_BUN_VERSION)) {
+ const rerunArgs = ['--root', root, '--harness', options.harness, ...(options.adopt ? ['--adopt'] : []), ...(options.upgrade ? ['--upgrade'] : []),
+ ...(options.skills ? ['--skills', options.skills] : []), ...(options.json ? ['--json'] : [])];
+ const rerun = `curl --fail --silent --show-error --location ${SETUP_HELPER_URL} --output /tmp/gbrain-setup.sh && bash /tmp/gbrain-setup.sh ${rerunArgs.map(shellQuote).join(' ')}`;
+ const next = options.upgrade ? 'Make a verified backup first (docs/guides/in-agent-setup.md), then fetch' : 'Fetch';
+ 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. ${next} the current helper and rerun setup: ${rerun}`);
}
if (!existsSync(dirname(root))) throw new AgentInstallError('parent_missing', 'Create and verify the persistent parent directory first.');
const existed = existsSync(root);
@@ -245,6 +254,7 @@ export async function setupInAgent(options: AgentSetupOptions): Promise<AgentSet
writeInstallReceipt(receipt);
delete receipt.last_failure;
let changed = false;
+ 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/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index d5c5d5e5d6..b17494c993 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1310,7 +1310,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.465.0', text: 'On a managed brain, `gbrain trust release h<id>` of a held fact whose entity page exists now writes the fact into that page\'s `## Facts` fence through the page-write door (a `trust_release` page write) and flips the hold in the same publication, so the released fact lives in the page\'s file and a re-import keeps it. Before, the release inserted a database-only row the file never held; a fence-guard hold that names an existing fence row created a database-only twin of it, and now indexes that row and leaves the file unchanged. The row is stamped `user_confirmed` with origin `trust_release` and the page keeps its trust tier. A hold decided after the release was accepted fails `preview_changed` and writes nothing; a remote request, or a deleted or private entity page, refuses and the fact stays held. A hold with no entity page, and unmanaged brains, release database-only as before.' },
{ since: '0.60.467.0', id: 'cli_flag_equals', text: 'A CLI flag value written with `=` that a command used to ignore now exits 2 (`invalid_params`) and names the two-argument spelling the command reads: `gbrain auth create --scopes=read` minted a full-access token. A switch never takes a value (`--yes=n`, `--dry-run=true`, `--apply=false` and `-y=n` exit 2 instead of being ignored). The `=` spellings a command reads on every path keep working, and so do the spending cap and plan hash the consent check of a command reads; a few that only some paths read now exit 2 with the two-argument fix, among them the source id given that way to `gbrain extract` for stale extraction, the checkout path given that way to the database-free `gbrain sources pull`, and the values given that way to the managed `gbrain sources` lifecycle subcommands (add, remove, archive, restore, purge, set-path, reclone). A value written with `=` on a flag that the help of the command declares used to be ignored and now applies, so check scripts that pass these that way: an all-interfaces bind address given to `gbrain serve` bound loopback and now listens on every interface; a public URL given to `gbrain serve` now sets the OAuth issuer and resource, so clients authorized under the old localhost issuer must reconnect, and admin cookies become Secure on https; the serve port, token lifetime and stdio idle timeout, the sync interval, source and repository, the import worker count, the autopilot install repository and supervisor, and the target engine and URL the legacy `gbrain migrate` copier reads take effect the same way; a spend cap given to `gbrain onboard` (off included) now applies, and one given to a resumed `gbrain doctor` remediation overrides the cap its checkpoint recorded; and `gbrain apply-migrations` now honors an accepted reviewed inventory and a forced retry of a wedged migration. An upgrade restart of a `gbrain jobs supervisor` started with values written that way (which it ignored) starts it again without them. A script that passes a value with `=` to a command that does not read that form now stops with the fix instead of running without the value.' },
// Bun floor 1.4.4 (#7644, #7596). `since` is stamped at the merge slot.
- { since: '0.60.468.0', id: 'bun_floor_1_4_4', text: 'GBrain now requires Bun 1.4.4 or newer (previously 1.4.0). On Bun 1.4.0 to 1.4.3 every command except `gbrain --version` exits 1 before it starts with `GBrain requires Bun 1.4.4 or newer (found Bun <version>)` and the fix (`bun upgrade`, then restart GBrain; `gbrain post-upgrade` finishes an interrupted upgrade); `--version` prints the same refusal and exits 0. On Bun 1.4.0 to 1.4.2 a postgres.js connection over TLS keeps every chunk it receives, so a full sync or conversion pass over a TLS Postgres or pooler grew by about the bytes it read until memory guards killed it (#7644, #7596); 1.4.4 also carries the Brotli fix for CVE-2026-111497. Standalone gbrain binaries already embed Bun 1.4.4; a source or `bun install` install runs `bun upgrade` first, and `gbrain upgrade` on an older host Bun stops (autopilot holds) with the same fix.' },
+ { since: '0.60.467.0', id: 'bun_floor_1_4_4', text: 'GBrain now requires Bun 1.4.4 or newer (previously 1.4.0). On Bun 1.4.0 to 1.4.3 every command except `gbrain --version` exits 1 before it starts with `GBrain requires Bun 1.4.4 or newer (found Bun <version>)` and the fix (`bun upgrade`, then restart GBrain; `gbrain post-upgrade` finishes an interrupted upgrade); `--version` prints the same refusal and exits 0. On Bun 1.4.0 to 1.4.2 a postgres.js connection over TLS keeps every chunk it receives, so a full sync or conversion pass over a TLS Postgres or pooler grew by about the bytes it read until memory guards killed it (#7644, #7596); 1.4.4 also carries the Brotli fix for CVE-2026-111497. Standalone gbrain binaries already embed Bun 1.4.4; a source or `bun install` install runs `bun upgrade` first, and `gbrain upgrade` on an older host Bun stops (autopilot holds) with the same fix.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/test/agent-install-bun-floor.test.ts b/test/agent-install-bun-floor.test.ts
index ffa3f25def..1053696ea9 100644
--- a/test/agent-install-bun-floor.test.ts
+++ b/test/agent-install-bun-floor.test.ts
@@ -51,7 +51,7 @@ test('setup refuses a bundle carrying Bun below the floor before writing anythin
expect(result).toMatchObject({ ok: false, reason: 'runtime_below_floor' });
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(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 --json`);
expect(existsSync(root)).toBe(false);
});
@@ -106,6 +106,24 @@ test('a bundle carrying the floor itself passes the gate', async () => {
expect(existsSync(root)).toBe(true);
});
+test('a human-mode refusal reruns without --json', async () => {
+ const { root, bundle } = fixture('1.4.3');
+ const lines: string[] = [];
+ const error = spyOn(console, 'error').mockImplementation((line: string) => { lines.push(line); });
+ try { expect(await runAgentSetupCli(setupArgs(root, bundle).filter(arg => arg !== '--json'))).toBe(1); } finally { error.mockRestore(); }
+ expect(lines.join('\n')).toEndWith(`bash /tmp/gbrain-setup.sh --root '${root}' --harness grok-bot`);
+});
+
+test('an unreadable bundle is still journaled on the install receipt', async () => {
+ const { root, bundle } = fixture(MINIMUM_BUN_VERSION);
+ rmSync(join(bundle, 'app', 'node_modules', 'gbrain', 'src', 'cli.ts'));
+ const { exit, result } = await run(setupArgs(root, bundle));
+ expect(exit).toBe(1);
+ expect(result.reason).toBe('invalid_artifact');
+ const receipt = JSON.parse(readFileSync(join(root, '.gbrain', 'agent-install', 'receipt.json'), 'utf8'));
+ expect(receipt.last_failure?.code).toBe('invalid_artifact');
+});
+
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']);