Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes (pass 2)

garrytan31f010f10ee5
diff --git a/docs/architecture/key-files/ci-health-and-test-guards.md b/docs/architecture/key-files/ci-health-and-test-guards.md
index 772d74b782..83b4e01261 100644
--- a/docs/architecture/key-files/ci-health-and-test-guards.md
+++ b/docs/architecture/key-files/ci-health-and-test-guards.md
@@ -22,7 +22,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `scripts/check-test-env-opt-ins.ts` + `test/helpers/operator-env-policy.ts` — the opt-in naming rule. The policy (`STRIP_PREFIX`, `KEEP_EXACT`, `KEEP_PREFIX`, `RENAMED`, `isStripped`) is shared by `test/helpers/operator-env-preload.ts`, which deletes stripped `GBRAIN_*` names before any test loads and stops the run with the rename command when an old opt-in name is set, and by the guard (`check:test-env-opt-ins`, in `verify`), which parses test files and fails on a test that gates execution on a stripped name. Test opt-ins are `GBRAIN_TEST_<AREA>_<WHAT>`, paid ones `GBRAIN_TEST_LIVE_<WHAT>`. The same guard fails `test_env_snapshot_module_scope`: a `delete` of or assignment to `process.env.GBRAIN_PGLITE_SNAPSHOT` outside every function body in a file the unit matrix loads (`*.serial.test.ts`, `test/e2e/` and `*-preload.ts` are exempt: own process, or process-wide by design). `scripts/test-shard.sh` runs a whole shard in one bun process, so such a change persists for every later file and each of their PGLite engines cold-boots (~3 s); the accepted shape is save+delete in `beforeAll`, restore in `afterAll`, or `test/helpers/with-snapshot.ts` per test. Tests: `test/scripts/test-env-opt-ins-guard.test.ts`, `test/operator-env-preload.test.ts`.
- `scripts/check-postgres-lane-coverage.ts` — `check:postgres-lanes` (in `verify`). TypeScript-AST scan of every `test/` file outside `test/e2e/` and `test/fixtures/` for a `DATABASE_URL`-gated PostgreSQL arm (zero-argument `testBackends()`, or a `DATABASE_URL` read used as a condition, connection argument or `database_url` value; `withEnv`-supplied URLs excluded) and a lane that runs it (a workflow step with `DATABASE_URL` naming the file, a `test/e2e/` importer, a `tests/heavy/` script, or a `scripts/e2e-backend-matrix.txt` row). `ALLOWLIST` rows name a reason and TODO; stale rows fail. A `test/postgres-unit-arms.txt` row is a lane; a malformed, duplicate, unsorted, missing-file or arm-less row fails (`postgres_arm_list_invalid`, `postgres_arm_list_stale`). `postgresArm`, `postgresLanes` and `armedFiles` are exported for the stress runner. Tests: `test/scripts/postgres-lane-coverage.test.ts`.
- `scripts/check-item-allowlist-catches.ts` + `scripts/item-allowlist-catches-baseline.tsv` — `check:item-allowlist-catches` (in `verify`). TypeScript-AST scan of `src/**/*.ts` (no `*.generated.ts`, `.d.ts`) for catch clauses in a per-item loop (a for/for-of/for-in/while/do-while body, or a `.forEach`/`.map` callback, up to the nearest function boundary) whose block tests the caught error's code against a set, list or literal (direct, cast, aliased or destructured) and rethrows the caught error. Per-file counts only shrink: growth, a new file, a count under its row, a row with no sites or no file, and malformed, duplicate or unsorted rows fail, pointing at `classifyItemFailure` / `ItemRun` (`src/core/item-failure.ts`) and `test/pathological/`. `--update` rewrites the baseline after a shrink. `findAllowlistCatches` and `compareBaseline` are exported for `test/scripts/check-item-allowlist-catches.test.ts`; self-test fixtures under `test/fixtures/guards/check-item-allowlist-catches.ts/`.
-- `test/postgres-unit-arms.txt` + `scripts/postgres-unit-arms.ts` + `scripts/postgres-arm-weights.json` — the one list of unit-lane files whose PostgreSQL arm has no other owner (sorted, one path per line, `#` comments). Read by persistence-validation.yml's `unit-postgres-arms` job (`ARM_SHARDS` = 12 shards, `shard <n> <m>`: LPT over the mined per-file weights, p75 fallback; `run <n> <m> [--postgres-only]`: `ARM_WORKERS` = 2 files at a time, one Bun process per file, each worker on its own URL from `GBRAIN_ARM_DATABASE_URLS`, output buffered per file and printed in queue order in `::group::` blocks ending in an `ARM_FILE … ms=…` line, one receipt triple per file; `--postgres-only` (Bun 1.4.4 cell) sets `GBRAIN_TEST_BACKEND=postgres` and reads `ARM_WEIGHTS_POSTGRES_ONLY` when it exists; each shard's two-worker makespan at most `ARM_SHARD_BUDGET_MS`, 570 s, so twice that still ends a minute inside the 20-minute `ARM_STEP_TIMEOUT_MS` step; no machine-exclusive serial file may be listed), the scheduled race hunt and the lane guard. `mine [--postgres-only] <job.log>…` rewrites the cell's weights from a green run's `ARM_FILE` lines (older logs: `##[group]<file>` to the next group or endgroup). Tests: `test/scripts/postgres-unit-arms.test.ts`.
+- `test/postgres-unit-arms.txt` + `scripts/postgres-unit-arms.ts` + `scripts/postgres-arm-weights.json` — the one list of unit-lane files whose PostgreSQL arm has no other owner (sorted, one path per line, `#` comments). Read by persistence-validation.yml's `unit-postgres-arms` job (`ARM_SHARDS` = 12 shards, `shard <n> <m>`: LPT over the mined per-file weights, p75 fallback; `run <n> <m> [--postgres-only]`: `ARM_WORKERS` = 2 files at a time, one Bun process per file, each worker on its own URL from `GBRAIN_ARM_DATABASE_URLS`, output buffered per file and printed in queue order in `::group::` blocks ending in an `ARM_FILE … ms=…` line, one receipt triple per file; `--postgres-only` (a manual mode; CI runs both arms) sets `GBRAIN_TEST_BACKEND=postgres` and reads `ARM_WEIGHTS_POSTGRES_ONLY` when it exists; each shard's two-worker makespan at most `ARM_SHARD_BUDGET_MS`, 570 s, so twice that still ends a minute inside the 20-minute `ARM_STEP_TIMEOUT_MS` step; no machine-exclusive serial file may be listed), the scheduled race hunt and the lane guard. `mine [--postgres-only] <job.log>…` rewrites the cell's weights from a green run's `ARM_FILE` lines (older logs: `##[group]<file>` to the next group or endgroup). Tests: `test/scripts/postgres-unit-arms.test.ts`.
- `scripts/serial-files.tsv` + `scripts/lib/serial-manifest.ts` — the serial manifest: every `*.serial.test.ts` outside `test/e2e/` with its class (`R1`, `R2`, `global-state`, `exclusive`) and a reason. `checkSerialManifest` (pure) requires the manifest to match the tree exactly, classes to match what the file does (env mutation, `mock.module`, `EXCLUSIVE_FILES`) and reasons to be specific; each failure prints Why/Fix/Docs with `bash scripts/check-test-isolation.sh --as-parallel <file>` as the first step. Tests: `test/scripts/serial-files.test.ts`.
- `test/helpers/brain-template.ts` — disk-backed PGLite brains cloned from one initialized template per process and embedding shape. The template is captured right after `initSchema` with no source, writer or physical-root reservation (asserted); only the data directory is copied; each clone regenerates `brain_id`, the default source incarnation and the shared-skill token secret and serving epoch. Used by `test/helpers/connector-fixture.ts`. Tests: `test/helpers/brain-template.test.ts`.
- `scripts/test-agent-voice.sh` — `bun run test:agent-voice`: the agent-voice recipe's vitest unit suite (`recipes/agent-voice/tests/unit`), with pinned vitest and ws installed into a temporary prefix linked as the recipe's `node_modules`. Needs node, npm and registry access; CI runs it in test.yml's verify job.
diff --git a/scripts/structural-suites.tsv b/scripts/structural-suites.tsv
index fe9b666b3b..60602b4b53 100644
--- a/scripts/structural-suites.tsv
+++ b/scripts/structural-suites.tsv
@@ -285,7 +285,7 @@ test/reranker-default-seam.test.ts DEFAULT_RERANKER_MODEL seam (#3657, flipped v
test/resolver.test.ts RESOLVER.md trigger round-trip (D5/C) 2 readFileSync
test/resolver.test.ts Skill example-name validator (D13) 4 readFileSync
test/retrieval-reflex-recipe-routing.test.ts retrieval-reflex recipe routing is MECE with the query skill (#4292) 5 readFileSync
-test/runtime-version.test.ts stated Bun floor 1 readFileSync
+test/runtime-version.test.ts stated Bun floor 2 readFileSync
test/schema-bootstrap-coverage.test.ts (file-level) 15 source-surface-helper
test/schema-pack-unify-types-handler.test.ts #1575 unify-types worker dry-run default 1 source-surface-helper
test/schema-pack/suggest.test.ts runSuggest — source-text contract (structural) 1 readFileSync
diff --git a/skills/migrations/v0.60.467.0.md b/skills/migrations/v0.60.467.0.md
index 5a9bbcab9c..76c1cc7570 100644
--- a/skills/migrations/v0.60.467.0.md
+++ b/skills/migrations/v0.60.467.0.md
@@ -15,8 +15,10 @@ Fix: run `bun upgrade`, then restart GBrain. If a `gbrain upgrade` stopped here,
`gbrain --version` still answers on an older Bun. Compiled release binaries
carry their own Bun 1.4.4 and need nothing. Code that imports gbrain as a
-library runs on its host's Bun with no startup check, so that host must meet
-`engines.bun` (>=1.4.4) itself. There is no schema change and no config
+library runs on its host's Bun with no startup check, but its guarded outbound
+HTTP calls (URL checks, remote images, HTTP integrations) throw
+`UNSUPPORTED_RUNTIME` on a Bun below 1.4.4, so upgrade that host's Bun before
+upgrading gbrain. There is no schema change and no config
change.
Upgrading Bun changes the user's runtime for every Bun program on the machine,
diff --git a/skills/skills.lock.json b/skills/skills.lock.json
index 0974e388d6..cc6a9ce8be 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": "c01d789196fe9f9a774986de76253589fd139f834d41610741a7b54fb94ea1ee",
+ "migrations/v0.60.467.0.md": "ad441a41d713481bf5d3dc85907cb32e49cd4f428d78da4b81260e5c31216d97",
"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/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 3a69d696ec..fd27aa8b5d 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1309,7 +1309,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.464.0', text: 'A managed sync pass whose process was killed or crashed now reads `resumable` / `pass_interrupted` in `gbrain sync status` (with an `interrupted` block naming the pass and the dead holder) instead of `pass_unfinished`, and a second killed pass reads `blocked` / `pass_abandoned` at once. `gbrain doctor` `managed_sync_blocked` lists both (warn, fail after an hour). A live pass still committing is no longer counted abandoned because its row is old.' },
{ 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.' },
// Bun floor 1.4.4 (#7644, #7596). `since` is stamped at the merge slot.
- { since: 'TBD', 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 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), and doctor\'s `bun_runtime` fails the same way. 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: 'TBD', 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/templates/bootstrap/cloud-setup-script.sh b/templates/bootstrap/cloud-setup-script.sh
index 35a5593d91..a3e9cdb2aa 100644
--- a/templates/bootstrap/cloud-setup-script.sh
+++ b/templates/bootstrap/cloud-setup-script.sh
@@ -14,7 +14,7 @@ if [ -z "$GBRAIN_BUN" ] || ! bun_ok "$GBRAIN_BUN"; then
npm install -g bun
GBRAIN_BUN="$(npm prefix -g)/bin/bun"
# `gbrain --version` below answers on any Bun, so check the floor here.
- bun_ok "$GBRAIN_BUN" || { echo "gbrain: npm installed Bun $("$GBRAIN_BUN" --version), below the 1.4.4 minimum" >&2; exit 1; }
+ bun_ok "$GBRAIN_BUN" || { echo "gbrain: the Bun npm installed ($GBRAIN_BUN) did not report 1.4.4 or newer" >&2; exit 1; }
fi
export PATH="$(dirname "$GBRAIN_BUN"):$PATH"
diff --git a/test/runtime-version.test.ts b/test/runtime-version.test.ts
index a1c971a3bc..6a0161736a 100644
--- a/test/runtime-version.test.ts
+++ b/test/runtime-version.test.ts
@@ -12,7 +12,9 @@
* that a refusal throws, not what it tells the user.
*/
import { describe, expect, spyOn, test } from 'bun:test';
-import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { MINIMUM_BUN_VERSION, SECURE_BUN_VERSION, assertSupportedBun, exitOnUnsupportedBun, unsupportedBunMessage } from '../src/core/runtime-version.ts';
import { checkBunRuntime } from '../src/commands/doctor/checks/upgrade-health.ts';
@@ -125,4 +127,26 @@ describe('stated Bun floor', () => {
const cloud = readFileSync(join(root, 'templates/bootstrap/cloud-setup-script.sh'), 'utf8');
expect(/Bun\.semver\.satisfies\(Bun\.version, ">=([\d.]+)"\)/.exec(cloud)?.[1]).toBe(MINIMUM_BUN_VERSION);
});
+
+ test('the cloud setup script stops before cloning when the Bun npm installed is below the floor', () => {
+ const dir = mkdtempSync(join(tmpdir(), 'gb-cloud-bun-'));
+ try {
+ const bin = join(dir, 'bin');
+ const prefix = join(dir, 'prefix');
+ mkdirSync(join(prefix, 'bin'), { recursive: true });
+ mkdirSync(bin);
+ const tool = (path: string, body: string) => { writeFileSync(path, `#!/bin/sh\n${body}`); chmodSync(path, 0o755); };
+ const oldBun = '[ "$1" = --version ] && echo 1.4.3 && exit 0\nexit 1\n';
+ tool(join(bin, 'bun'), oldBun);
+ tool(join(prefix, 'bin', 'bun'), oldBun);
+ tool(join(bin, 'npm'), `[ "$1 $2" = "prefix -g" ] && echo '${prefix}'\nexit 0\n`);
+ tool(join(bin, 'git'), 'echo fake-git-called >&2\nexit 97\n');
+ const r = spawnSync('bash', [join(root, 'templates/bootstrap/cloud-setup-script.sh')], { env: { PATH: `${bin}:/usr/bin:/bin`, HOME: dir }, encoding: 'utf8' });
+ expect(r.stderr).not.toContain('fake-git-called');
+ expect(r.stderr).toContain('did not report 1.4.4 or newer');
+ expect(r.status).toBe(1);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
});