Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: the opencode door's gating SMOKE is paid T5; CONTRIBUTING names run_profiles and min_gstack_version 1.91.377.0

garrytan71000e045593
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f815f2baea..0af8edd8e6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -706,7 +706,7 @@ accepted contribution is credited in `CHANGELOG.md`.
### gstack repo config (`.gstack/`)
-Two committed files tell gstack (1.91.98.0 or later) about gbrain's own gates;
+Two committed files tell gstack (1.91.377.0 or later) about gbrain's own gates;
gstack reads both from master, so a branch's edits take effect after it merges.
- `.gstack/pregate.json`: `gstack-pregate run --allow-repo-commands` runs a
@@ -725,10 +725,15 @@ gstack reads both from master, so a branch's edits take effect after it merges.
`PREGATE_REMOTE: tree=… tests=… failed=…` line. On a clean tree whose Test and
E2E full runs already passed on GitHub, the line comes from those runs and no
VM starts ([remote-gate reuse](docs/ci-event-parity.md#remote-gate-reuse)).
+ `run_profiles` and `remote_gate_runs` let `gstack-pregate clear --run <Test run>
+ --run <E2E run>` clear that obligation from a slot's passed full-ci runs of
+ the same tree, checked against the inventory `bash scripts/pregate-remote-gate.sh
+ --list` prints ([run evidence](docs/ci-event-parity.md#run-evidence-for-gstack-gstack-pregate-clear---run)).
- `.gstack/ship-policy.json`: the stamp rule (the release stamp files and
version patterns) and the migration numbering `gstack-pregate regate` and
`gstack-tree-receipt` use to decide whether a restamped head is the same tree
- that passed the gate.
+ that passed the gate, plus `min_gstack_version` (1.91.377.0, the first gstack
+ that reads `run_profiles`; an older one refuses with an upgrade fix).
### How a contributor PR lands
diff --git a/docs/architecture/key-files/commands-1.md b/docs/architecture/key-files/commands-1.md
index 9a6af8e8b5..b3ef3ebc8b 100644
--- a/docs/architecture/key-files/commands-1.md
+++ b/docs/architecture/key-files/commands-1.md
@@ -34,7 +34,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/commands/check-resolvable.ts` — Standalone CLI wrapper over `checkResolvable()`. Exports `parseFlags`, `resolveSkillsDir`, `DEFERRED`, `runCheckResolvable`. Exit rule: **1 on any issue (warnings OR errors)**, stricter than doctor's `ok` flag. Stable JSON envelope `{ok, skillsDir, report, autoFix, deferred, error, message}` — same shape on success and error. `--fix` runs `autoFixDryViolations` BEFORE `checkResolvable` (same ordering as doctor). `scripts/skillify-check.ts` subprocess-calls `gbrain check-resolvable --json` (cached per process) and fails loud on binary-missing. AGENTS.md workspaces resolve natively (see `src/core/resolver-filenames.ts`). `DEFERRED[]` is empty. Resolver lookup is the multi-file merge in `src/core/check-resolvable.ts` — entries collected from every `RESOLVER.md`/`AGENTS.md` across the skills dir AND its parent, deduped by `skillPath` (first occurrence wins). Uses `autoDetectSkillsDirReadOnly` so `cd ~ && gbrain check-resolvable` finds bundled skills via the install-path fallback; `--fix` carries the same install-path safety gate (refuses to write when `detected.source === 'install_path'`).
-- `src/commands/claw-test.ts` + `src/core/claw-test/` — `gbrain claw-test [--scenario <name>] [--live --agent <name>]`. End-to-end "fresh user" friction harness. Two modes: scripted (CI gate, agent-free) and live (real agent subprocess, $1–2 in tokens). Sets `GBRAIN_HOME=<tempdir>` for hermeticity and captures gbrain's `--progress-json` events from each child's stderr to verify expected phases ran (`import.files`, `extract.links_fs`, `doctor.db_checks`). Scripted phases: setup → install_brain (`gbrain init --pglite`) → import (`--no-embed`) → query → extract → verify (`gbrain doctor --json`; top-level status is `healthy|warnings|unhealthy`) → render. Live mode STAGES the scenario before the agent turn (fresh-install: brain pages + AGENTS.md stub + init; upgrade: seed-first via `seed-pglite.ts`, NO init — the migration is the scenario under test), prepends a per-run `gbrain` PATH shim so the BRIEF's bare `gbrain` runs this checkout, hands `BRIEF.md` to the agent runner, then verifies a scenario-declared success ORACLE (`oracle: {query, min_results, files_exist}` in scenario.json; upgrade uses a non-mutating schema-version probe via `readPgliteSchemaVersion` — doctor would auto-migrate and pass a do-nothing agent). Child-side friction merges into the parent's friction file before tempdir cleanup. Four runners ship (`src/core/claw-test/runners/{openclaw,hermes,grok,opencode}.ts`; shared `detectBinary`/`filterAllowlistEnv` live in `agent-runner.ts`): openclaw invokes `openclaw agent --local --agent <name> --message <brief>`; hermes invokes `hermes -z <brief>` (`$HERMES_BIN` > `which hermes`; `HERMES_HOME` passthrough is the env-allowlist delta; shared `BASE_ENV_ALLOWLIST` + `validateBinPathEnv` live in `agent-runner.ts`); grok (xAI Grok Build, observed shapes in `docs/mcp/GROK-CLI-PIN.md`) invokes `grok -p <brief> --output-format plain` (`$GROK_BIN` > `which grok`; delta `GROK_HOME` + `XAI_API_KEY`; writes a version preamble into the transcript and warns loudly when the operator's `~/.claude.json` registers gbrain — grok reads vendor MCP configs for trusted folders); opencode (SST, observed shapes in `docs/mcp/OPENCODE-CLI-PIN.md`) invokes `opencode run <brief> --format default` (`$OPENCODE_BIN` > `which opencode`; delta = the EXPLICIT multi-provider keys XAI/Google/Gemini/OpenRouter — BASE carries only Anthropic+OpenAI — plus XDG dirs, OPENCODE_CONFIG(_DIR), and OPENCODE_DISABLE_AUTOUPDATE; OPENCODE_CONFIG_CONTENT deliberately absent, it is a config-shadow channel; no `--auto` — MCP tools fire without it; bare-semver version preamble is the SST-vs-claimant discriminator; warns loudly when the user-global opencode config carries mcp.gbrain). Live-lane posture: the OPERATOR's configured agent + hermetic brain; the fully hermetic lanes are `test/e2e/install-real-hermes.serial.test.ts`, `test/e2e/install-real-grok.serial.test.ts`, and `test/e2e/install-real-opencode.serial.test.ts` (split-gated a step past grok: opencode's anonymous free tier drives MCP tool calls keyless, so even the nonce SMOKE — with a STRUCTURAL `gbrain_*` tool_use assert via `parseOpencodeJsonl` — runs in the keyless tier; the paid anthropic leg self-validates its pinned model id against the authed `opencode models` list before any spend) (grok door is split-gated: keyless compat tier needs only the binary — `mcp doctor` is grok's honest discriminator, proving the seven-verb surface keyless; paid SMOKE additionally needs `XAI_API_KEY` and asserts a per-run nonce fact, never the committed one). Transcript capture (`transcript-capture.ts`) uses `fs.createWriteStream` with `'drain'`-event backpressure (so a 256KB burst cannot stall the child). Env knobs (harness escape hatches, all optional): `GBRAIN_BIN_OVERRIDE` (child gbrain binary; validated absolute/no-dotdot/no-metacharacter because it's interpolated into the PATH shim — under the bun runtime the harness otherwise synthesizes a launcher so children never exec bun itself), `GBRAIN_CLAW_PHASE_TIMEOUT_MS` (per-phase child wall clock, default 5 min; each phase child leads its own process group on POSIX, so the timeout's SIGTERM→SIGKILL, a relayed SIGINT (second SIGINT kills), the process-cleanup pass on SIGTERM/SIGHUP and the phase's settle all signal the whole group (#6775)), `GBRAIN_CLAW_AGENT_TIMEOUT_MS` (live agent turn wall clock, default 10 min).
+- `src/commands/claw-test.ts` + `src/core/claw-test/` — `gbrain claw-test [--scenario <name>] [--live --agent <name>]`. End-to-end "fresh user" friction harness. Two modes: scripted (CI gate, agent-free) and live (real agent subprocess, $1–2 in tokens). Sets `GBRAIN_HOME=<tempdir>` for hermeticity and captures gbrain's `--progress-json` events from each child's stderr to verify expected phases ran (`import.files`, `extract.links_fs`, `doctor.db_checks`). Scripted phases: setup → install_brain (`gbrain init --pglite`) → import (`--no-embed`) → query → extract → verify (`gbrain doctor --json`; top-level status is `healthy|warnings|unhealthy`) → render. Live mode STAGES the scenario before the agent turn (fresh-install: brain pages + AGENTS.md stub + init; upgrade: seed-first via `seed-pglite.ts`, NO init — the migration is the scenario under test), prepends a per-run `gbrain` PATH shim so the BRIEF's bare `gbrain` runs this checkout, hands `BRIEF.md` to the agent runner, then verifies a scenario-declared success ORACLE (`oracle: {query, min_results, files_exist}` in scenario.json; upgrade uses a non-mutating schema-version probe via `readPgliteSchemaVersion` — doctor would auto-migrate and pass a do-nothing agent). Child-side friction merges into the parent's friction file before tempdir cleanup. Four runners ship (`src/core/claw-test/runners/{openclaw,hermes,grok,opencode}.ts`; shared `detectBinary`/`filterAllowlistEnv` live in `agent-runner.ts`): openclaw invokes `openclaw agent --local --agent <name> --message <brief>`; hermes invokes `hermes -z <brief>` (`$HERMES_BIN` > `which hermes`; `HERMES_HOME` passthrough is the env-allowlist delta; shared `BASE_ENV_ALLOWLIST` + `validateBinPathEnv` live in `agent-runner.ts`); grok (xAI Grok Build, observed shapes in `docs/mcp/GROK-CLI-PIN.md`) invokes `grok -p <brief> --output-format plain` (`$GROK_BIN` > `which grok`; delta `GROK_HOME` + `XAI_API_KEY`; writes a version preamble into the transcript and warns loudly when the operator's `~/.claude.json` registers gbrain — grok reads vendor MCP configs for trusted folders); opencode (SST, observed shapes in `docs/mcp/OPENCODE-CLI-PIN.md`) invokes `opencode run <brief> --format default` (`$OPENCODE_BIN` > `which opencode`; delta = the EXPLICIT multi-provider keys XAI/Google/Gemini/OpenRouter — BASE carries only Anthropic+OpenAI — plus XDG dirs, OPENCODE_CONFIG(_DIR), and OPENCODE_DISABLE_AUTOUPDATE; OPENCODE_CONFIG_CONTENT deliberately absent, it is a config-shadow channel; no `--auto` — MCP tools fire without it; bare-semver version preamble is the SST-vs-claimant discriminator; warns loudly when the user-global opencode config carries mcp.gbrain). Live-lane posture: the OPERATOR's configured agent + hermetic brain; the fully hermetic lanes are `test/e2e/install-real-hermes.serial.test.ts`, `test/e2e/install-real-grok.serial.test.ts`, and `test/e2e/install-real-opencode.serial.test.ts` (keyless tier: registration only; the free-tier nonce SMOKE T4 runs only in the canary, the free tier being capped per IP (#6049); the gating SMOKE is paid T5, a Haiku turn whose model id is checked against `opencode models --refresh` before spend, asserting a STRUCTURAL `gbrain_*` tool_use event via `parseOpencodeJsonl` as T4 does) (grok door is split-gated: keyless compat tier needs only the binary — `mcp doctor` is grok's honest discriminator, proving the seven-verb surface keyless; paid SMOKE additionally needs `XAI_API_KEY` and asserts a per-run nonce fact, never the committed one). Transcript capture (`transcript-capture.ts`) uses `fs.createWriteStream` with `'drain'`-event backpressure (so a 256KB burst cannot stall the child). Env knobs (harness escape hatches, all optional): `GBRAIN_BIN_OVERRIDE` (child gbrain binary; validated absolute/no-dotdot/no-metacharacter because it's interpolated into the PATH shim — under the bun runtime the harness otherwise synthesizes a launcher so children never exec bun itself), `GBRAIN_CLAW_PHASE_TIMEOUT_MS` (per-phase child wall clock, default 5 min; each phase child leads its own process group on POSIX, so the timeout's SIGTERM→SIGKILL, a relayed SIGINT (second SIGINT kills), the process-cleanup pass on SIGTERM/SIGHUP and the phase's settle all signal the whole group (#6775)), `GBRAIN_CLAW_AGENT_TIMEOUT_MS` (live agent turn wall clock, default 10 min).
- `src/commands/code-def.ts` + `src/commands/code-refs.ts` — symbol definition + references lookup. Query `content_chunks.symbol_name` or chunk_text ILIKE with `page_kind='code'` filter. Auto-JSON when stdout is not a TTY (gh-CLI convention). Bypass the standard `searchKeyword` `DISTINCT ON (slug)` collapse so multiple call-sites from the same file surface. The JSON envelope (CLI + the `code_def`/`code_refs` MCP ops) carries `status` + `ready` from `src/core/code-graph-readiness.ts` so a `count:0` result is distinguishable as `not_built` (no code indexed) vs `ready` (genuinely no match); human output prints a one-line hint when not ready. Both commands resolve `--source <id>` (space or inline `=` spelling) and the ambient source scope through the shared `code-scope.ts` resolver, matching `code-callers`/`code-callees`; `--all-sources` restores the brain-wide read. `code-intel/read-scope.ts` applies the same source, live-page, visibility and current-projection policy to result queries and filtered-type diagnostics. Result identity includes source_id. Partial as well as empty results carry readiness; trusted-local operation wrappers retain their documented brain-wide behavior.