Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: instruction-ledger lock and the Codex paired skills opt-out

garrytan9a8ca003a356
diff --git a/docs/architecture/key-files/commands-5.md b/docs/architecture/key-files/commands-5.md
index 8c20b139ef..917c34bc35 100644
--- a/docs/architecture/key-files/commands-5.md
+++ b/docs/architecture/key-files/commands-5.md
@@ -29,7 +29,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/commands/skillify-check.ts` — `gbrain skillpack-check` agent-readable health report. Exit 0/1/2 for CI gating; JSON for debugging. Wraps `check-resolvable --json`, `doctor --json`, and migration ledger into one payload. Required item 12 (`brain_first_compliance`) calls `analyzeSkillBrainFirst()` on the candidate SKILL.md; exits 1 when the verdict is `missing_brain_first` (external-lookup pattern present, no callout, no `brain_first: exempt`). The scaffold path in `src/core/skillify/templates.ts` pre-inserts the canonical Convention callout into new SKILL.md files so freshly-scaffolded skills pass item 12.
- `src/commands/setup.ts` + `src/cli/commands/setup.ts` — `gbrain setup <harness>` (D8), pre-connect and engine-free (`thinClient: 'none'`, `json: 'document'`): an orchestrator over the existing wiring, not a new installation system. Target first: it resolves the brain (`loadConfig`; none → a `gbrain init --pglite --no-embedding --json` child, `--providers` drops `--no-embedding`; setup prints `Brain ready at <path>` and never init's standalone quickstart or `[AGENT]` banners; on the brain it just created it runs the setup migrations init left pending (`finishFreshSetupMigrations`, `src/commands/setup-migrations.ts`: one `apply-migrations --yes --no-autopilot-install --json` child built by `setupMigrationsArgv` in `migrations/fresh-install.ts`, 60 s bound, offline; v0.11.0 is held back when its host phase would edit an existing `~/.claude/AGENTS.md`, `~/.openclaw/AGENTS.md` or OpenClaw cron manifest (`hostRewriteTargets`)) and replaces init's `[init] Migrations:` line with `[setup] Migrations: …` (a failure keeps init's hand-off plus the error code; an existing brain is not touched), and renders a `Memory:` line naming `remember` (#6606: world facts are pushed, private ones are recall-only, capture writes a page) and then `setupFirstRunNotices` once after `Next:` in human output, or under `notices` in `--json`), the source (`--source` > `GBRAIN_SOURCE` > unpinned), the launcher (`--gbrain-bin` > `resolveGbrainBin`), the surface (`--surface` > `GBRAIN_SURFACE` > the receipt's > `REGISTRATION_SURFACE`) and the registration owner, prints them, then refuses before any write with `setup_hosted_connection` (thin-client config, hosted connection receipt or remote entry: never a second, local brain) or `setup_owner_conflict` (`live_serve` from `peekLock` unless the live stdio serve is this registration's own, `unowned_entry`, `other_install` by receipt `gbrain_home`, `harness_lane` for a bootstrap harness receipt that wired the configuration setup would write (a target in that config directory, compared after symlink resolution; project-scoped hooks; or a receipt recording no paths for the host) or another gbrain marker on a wanted event; #7771, `test/setup-harness-lane-scope-7771.test.ts`). Consent is three recorded decisions (`resolveConsent`): wiring scope (`--scope`, `--no-hooks`, `GBRAIN_HOOKS=0`), capture (`--capture`/`--no-capture`; a file-config `memory.auto_writeback: off` wins) and providers; read-context events come from the capability row, capture events only when accepted. Verify reuses `smokeStdioRegistration` from `doctor/checks/harness-wiring.ts`; states are `configured` → `connection-verified` → `native-pending` (`native-verified` is never claimed). `gbrain setup codex` (`runCodexSetup`/`runCodexRemove`, writer in `src/core/setup/codex.ts`) shares the target, consent, refusal and verify steps: user scope only (`--scope project` exits 2), the codex plugin (`codexPluginProvidesName`) skips the MCP table, `harness_lane` also covers a bootstrap harness receipt targeting codex (in the same scoped sense) or a bootstrap-lane group on a wanted event, the dry run adds a `trust` step, and the final state is `native-verified` when the codex row's push is verified and the receipt owns the trusted UserPromptSubmit hook. Unsupported harness ids (`openclaw`, `hermes`, unknown) refuse with `setup_harness_unsupported` naming the row's guide (exit 2). `GBRAIN_SETUP_ABORT_AFTER=receipt|mcp|hooks` is the crash-injection seam. Pinned by `test/setup.test.ts`.
-- `src/core/setup/brain-first.ts` + `src/core/managed-block.ts` — the brain-first instruction block every harness install writes by default (`<!-- gbrain:brain-first:begin/end -->`, `BRAIN_FIRST_VERSION`). `brainFirstTarget` names each harness's own instruction file (Claude Code `~/.claude/CLAUDE.md` or `./CLAUDE.local.md`, Codex `AGENTS.md` or an existing `AGENTS.override.md`, opencode global `AGENTS.md`, OpenClaw `<workspace>/AGENTS.md` from JSON5 `agents.defaults.workspace` (several agents need `--workspace`), Hermes `SOUL.md` after the identity text, Cursor `.cursor/rules/gbrain-brain-first.mdc`); other clients get the block printed to paste. `syncBrainFirst` splices only between the markers (idempotent, upgrades in place, preserves a damaged block and reports it), and the decision (`--no-instructions` / `GBRAIN_AGENT_INSTRUCTIONS=0`, `--instructions`, prior) is remembered in `<configDir>/agent-instructions.json` with the writer, so `--remove` on setup, `connect --install` and `bootstrap harness` (lane in `bootstrap/harness-brain-first.ts`) strips only its own blocks. Text varies by access: MCP search surface, verbs surface, or the thin-client CLI launcher (`GBRAIN-INSTRUCTIONS.md` starts with it). doctor `harness_wiring` reads the ledger plus each registered or plugin-served harness's default file and warns on a missing, stale or damaged block with a fix that rewrites only the block (`instructionBlockViews`, `withInstructionBlocks`); `gbrain post-upgrade` prints the same command (`brain-first-upgrade-notice.ts`, `instructionBlockUpgradeHints`). The Claude Code and Codex plugin manifests declare setup's UserPromptSubmit hook with `GBRAIN_HOOK_LANE=plugin`; it yields when another gbrain lane wires the event (`bootstrap/plugin-lanes.ts` `pluginHookYields`; `test/plugin-turn-hook.test.ts`). `managed-block.ts` is the shared marker splice/probe/remove that `bootstrap/instructions-block.ts` also uses (`test/setup-brain-first.test.ts`).
+- `src/core/setup/brain-first.ts` + `src/core/managed-block.ts` — the brain-first instruction block every harness install writes by default (`<!-- gbrain:brain-first:begin/end -->`, `BRAIN_FIRST_VERSION`). `brainFirstTarget` names each harness's own instruction file (Claude Code `~/.claude/CLAUDE.md` or `./CLAUDE.local.md`, Codex `AGENTS.md` or an existing `AGENTS.override.md`, opencode global `AGENTS.md`, OpenClaw `<workspace>/AGENTS.md` from JSON5 `agents.defaults.workspace` (several agents need `--workspace`), Hermes `SOUL.md` after the identity text, Cursor `.cursor/rules/gbrain-brain-first.mdc`); other clients get the block printed to paste. `syncBrainFirst` splices only between the markers (idempotent, upgrades in place, preserves a damaged block and reports it), and the decision (`--no-instructions` / `GBRAIN_AGENT_INSTRUCTIONS=0`, `--instructions`, prior) is remembered in `<configDir>/agent-instructions.json` with the writer (`underInstructionLedgerLock` holds one lock, `<configDir>/agent-instructions.lock`, shared with `skill-loading.json`, across the ledger read, the file and permission edits and the ledger write, re-reads a recorded decision under it, reports a lock it cannot take within 10 seconds as `preserve`, and a dry run takes none; `test/instruction-ledger-lock.test.ts`, `test/instruction-ledger-lock-timeout.slow.test.ts`), so `--remove` on setup, `connect --install` and `bootstrap harness` (lane in `bootstrap/harness-brain-first.ts`) strips only its own blocks. Text varies by access: MCP search surface, verbs surface, or the thin-client CLI launcher (`GBRAIN-INSTRUCTIONS.md` starts with it). doctor `harness_wiring` reads the ledger plus each registered or plugin-served harness's default file and warns on a missing, stale or damaged block with a fix that rewrites only the block (`instructionBlockViews`, `withInstructionBlocks`); `gbrain post-upgrade` prints the same command (`brain-first-upgrade-notice.ts`, `instructionBlockUpgradeHints`). The Claude Code and Codex plugin manifests declare setup's UserPromptSubmit hook with `GBRAIN_HOOK_LANE=plugin`; it yields when another gbrain lane wires the event (`bootstrap/plugin-lanes.ts` `pluginHookYields`; `test/plugin-turn-hook.test.ts`). `managed-block.ts` is the shared marker splice/probe/remove that `bootstrap/instructions-block.ts` also uses (`test/setup-brain-first.test.ts`).
- `src/core/setup/turn-hook.ts` + `src/core/setup/turn-hook-check.ts` — the per-turn rule hook for installs whose MCP came from a plain `mcp add` or another installer: a `turn-rule-v1` Claude Code UserPromptSubmit entry or a Codex `hooks.json` group plus its `config.toml` trust entry, running `GBRAIN_HOOK_LANE=turn-rule <hook launcher> gbrain hook user-prompt` (rule only, no local context; it yields to setup, bootstrap and plugin lanes). Written by `setup <claude-code|codex> --instructions-only`, `connect --install`, the hosted `harness connect --install` and `bootstrap harness` (not in registrar mode); with no absolute binary the outcome is `print` with the one-line next step. `inspectTurnHook` (files only; it also reads Claude Code's managed `managed-settings.json` and `managed-settings.d/*.json`, and `turnRuleHookYields` counts a managed gbrain hook, #8057) feeds doctor `harness_wiring` (`turnHookViews`, `withTurnHooks`: untrusted, or missing beside a ledger block, warns with code `turn_hook_not_loaded`); `verifyTurnHook` runs the hook (Claude Code, Codex), `openclaw plugins inspect gbrain-turn-rule --runtime --json` or `hermes hooks doctor`, and every install path exits non-zero with `turn_hook_not_loaded` when it fails (`docs/guides/repair.md#turn-hook-not-loaded`). OpenClaw and Hermes rules name the gbrain tools and the `tool_search` route (`renderBrainFirstTurnRule(access, harness)`; `test/brain-first-turn-rule.test.ts`, `test/setup-brain-first.test.ts`).
- `src/core/setup/hook-launcher.ts` + `src/core/setup/hook-launcher-refresh.ts` — the trusted-directory hook launcher (#8424): `<config dir>/hook-launcher/gbrain-hook`, a POSIX sh script that records the session directory in `GBRAIN_HOOK_CWD`, changes into its own directory and execs gbrain there, so a script-mode install never lets the session directory's `bunfig.toml` preload or `.env` load; it refuses (exit 1, one stderr line) when its directory holds anything else. Every setup-lane and turn-rule hook command names it (`buildClaudeHookCommand(…, launcher)`, `codexSetupHookGroup(…, launcher)`, `buildCodexSessionEndCommand(bin, launcher)`); `ensureHookLauncher` writes it before any hook that names it, and `gbrain hook` reads the session directory through `hookSessionCwd()`. `hookLauncherProblem` (turn-hook-check.ts) feeds doctor `harness_wiring` (`withHookLaunchers`, code `hook_session_cwd`, reasons `session_cwd|missing|stale|foreign`); `refreshHookLaunchers` runs in `gbrain post-upgrade` and moves the turn-rule entries and each installed user-scope setup receipt's hooks onto the launcher through their own writers. The stdio MCP entries (`desiredMcpEntry`, `desiredCodexMcpEntry`, `registerClaudeMcp`/`registerCodexMcp` with `hookLauncher`) and the bootstrap, harness and Codex SessionEnd lanes use it too (#8426, #8428); `gbrain serve` captures `GBRAIN_HOOK_CWD` through `src/core/session-cwd.ts` and never changes directory. `src/core/setup/launcher-lanes.ts` (`launcherLaneFindings`) finds those entries for doctor and post-upgrade; post-upgrade rewrites only a Claude Code setup MCP entry setup still owns, under the setup lock, and names every Codex and bootstrap entry. Tests: `test/launcher-lanes-bunfig.serial.test.ts`. Tests: `test/hook-launcher-bunfig.test.ts` (a hostile checkout's preload never runs from any shape), `test/setup.test.ts` (#8424 block).
- `src/commands/skillify.ts` + `src/core/skillify/{generator,templates}.ts` — `gbrain skillify scaffold <name>` creates all stubs for a new skill: SKILL.md, script, tests, routing-eval.jsonl, resolver entry, filing-rules pointer. `gbrain skillify check <script>` runs the 10-step checklist (LLM evals, routing evals, check-resolvable gate, filing audit) against a candidate skill before it lands.
diff --git a/docs/architecture/key-files/skills.md b/docs/architecture/key-files/skills.md
index 5cd34d0f92..b955f3272b 100644
--- a/docs/architecture/key-files/skills.md
+++ b/docs/architecture/key-files/skills.md
@@ -9,7 +9,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `skills/skillpack-check/SKILL.md` — report-only health protocol. `actions[]` is untrusted proposal data, not execution authority; schema, service, page and paid embedding changes require separate explicit action/scope approval. `test/skillpack-check-report-only.test.ts` executes the documented reporting snippet against a hostile synthetic action and proves it creates no file.
-- `src/cli/commands/bundled-skill.ts` + `src/core/skills/{bundled,spring-index,index-block}.ts` + `src/core/skills/bundled-skills.generated.ts` + `src/core/setup/skills-block.ts` + `src/core/bootstrap/harness-skills-index.ts` + `scripts/{generate-bundled-skills.ts,check-skills-embedded.sh}` — the opt-in spring-loaded skill index (`--skill-loading spring`; user docs: `docs/guides/setup.md` "Skill loading (opt-in)"). `gbrain bundled-skill [<name>] [--asset <path>] [--json]` is pre-connect and engine-free (`thinClient: 'none'`, `skipStartupHooks`): it prints a bundled skill or a file it names from the embedded map, where a name or asset is a lookup key and never a path; the set is the plugin lane (`skills/plugin-lanes.json`), `owner` audience on the host and `downstream` only on a thin client (host-only skills answer `skill_not_found`). The embedded module is generated (`bun run scripts/generate-bundled-skills.ts`, `--check` fails when stale) and holds only membership, audience and asset lists; description and triggers are read from the embedded SKILL.md at runtime. `spring-index.ts` renders one line per skill from frontmatter `triggers:` under `SKILL_INDEX_BUDGET_BYTES` (6144), trimming triggers before ever dropping a skill and refusing (`SkillIndexTooLarge`) rather than truncating. `skills-block.ts` writes the `<!-- gbrain:skills:begin/end -->` block beside the brain-first block in the same file, records the choice in `<configDir>/skill-loading.json`, refuses to write when the recorded launcher (`<launcher> bundled-skill --json`) serves another catalog, adds one `Bash(<launcher> bundled-skill:*)` allow rule on Claude Code only when absent and removes it only when it added it, and backs `setup --skills-index-only`; `setup`, `connect --install`, `harness connect --install` and `bootstrap harness` (`harness-skills-index.ts`) share it, and a requested index that cannot be written exits non-zero. doctor `harness_wiring` (`withSkillsIndex`) reports a stale, absent or damaged index as information and warns only when the launcher is gone or the record is unreadable; `check-resolvable` and `skill_currency` read past the block through `skillsIndexedIn`. `check-skills-embedded.sh` compiles a binary and proves it serves every bundled file byte-identical to `skills/` (`test/bundled-skill-cli.test.ts`, `test/spring-skill-index.test.ts`, `test/setup-skill-loading.test.ts`, `test/skill-loading-lanes.test.ts`).
+- `src/cli/commands/bundled-skill.ts` + `src/core/skills/{bundled,spring-index,index-block}.ts` + `src/core/skills/bundled-skills.generated.ts` + `src/core/setup/skills-block.ts` + `src/core/bootstrap/harness-skills-index.ts` + `scripts/{generate-bundled-skills.ts,check-skills-embedded.sh}` — the opt-in spring-loaded skill index (`--skill-loading spring`; user docs: `docs/guides/setup.md` "Skill loading (opt-in)"). `gbrain bundled-skill [<name>] [--asset <path>] [--json]` is pre-connect and engine-free (`thinClient: 'none'`, `skipStartupHooks`): it prints a bundled skill or a file it names from the embedded map, where a name or asset is a lookup key and never a path; the set is the plugin lane (`skills/plugin-lanes.json`), `owner` audience on the host and `downstream` only on a thin client (host-only skills answer `skill_not_found`). The embedded module is generated (`bun run scripts/generate-bundled-skills.ts`, `--check` fails when stale) and holds only membership, audience and asset lists; description and triggers are read from the embedded SKILL.md at runtime. `spring-index.ts` renders one line per skill from frontmatter `triggers:` under `SKILL_INDEX_BUDGET_BYTES` (6144), trimming triggers before ever dropping a skill and refusing (`SkillIndexTooLarge`) rather than truncating. `skills-block.ts` writes the `<!-- gbrain:skills:begin/end -->` block beside the brain-first block in the same file, records the choice in `<configDir>/skill-loading.json`, refuses to write when the recorded launcher (`<launcher> bundled-skill --json`) serves another catalog, adds one `Bash(<launcher> bundled-skill:*)` allow rule on Claude Code only when absent and removes it only when it added it, and backs `setup --skills-index-only`; every sync and removal runs under the instruction-ledger lock of `brain-first.ts` (outcome reason `ledger_locked` when it cannot be taken), and a Codex opt-out (flag, env or declined instructions) also strips the index recorded in the sibling `AGENTS.md`/`AGENTS.override.md` of the same `CODEX_HOME` (`paired` outcome, shown by `skillsOutcomeShown`); `setup`, `connect --install`, `harness connect --install` and `bootstrap harness` (`harness-skills-index.ts`) share it, and a requested index that cannot be written exits non-zero. doctor `harness_wiring` (`withSkillsIndex`) reports a stale, absent or damaged index as information and warns only when the launcher is gone or the record is unreadable; `check-resolvable` and `skill_currency` read past the block through `skillsIndexedIn`. `check-skills-embedded.sh` compiles a binary and proves it serves every bundled file byte-identical to `skills/` (`test/bundled-skill-cli.test.ts`, `test/spring-skill-index.test.ts`, `test/setup-skill-loading.test.ts`, `test/skill-loading-lanes.test.ts`).
- `src/core/audit-skill-brain-first.ts` — snapshot+diff JSONL audit at `~/.gbrain/audit/skill-brain-first-YYYY-Www.jsonl` (ISO-week rotated, honors `GBRAIN_AUDIT_DIR` via shared `resolveAuditDir()`). `recordBrainFirstRun(results)` reads the previous snapshot at `~/.gbrain/audit/skill-brain-first-snapshot.json`, diffs against current results, writes transition events (`detected | resolved | fixed`) one line per change, then atomically overwrites the snapshot via `.tmp + rename`. **Transition-only writes** — a stable brain produces 0 audit lines per doctor run. `readRecentBrainFirstEvents(days)` is the readback path for the future `skill_brain_first_trend` doctor check. Snapshot file is last-writer-wins under concurrent doctor runs; subsequent runs reconcile.
diff --git a/docs/guides/setup.md b/docs/guides/setup.md
index 22b15f54ef..be5f4e0925 100644
--- a/docs/guides/setup.md
+++ b/docs/guides/setup.md
@@ -218,11 +218,11 @@ gbrain. MCP `get_skill` is unchanged.
| Select | `--skill-loading off\|spring` on `gbrain setup <harness>`, `gbrain connect --install`, `gbrain connect --harness … --install` and `gbrain bootstrap harness`; or `GBRAIN_SKILL_LOADING`. Flag, then env, then the recorded choice, then `off`. |
| Default | `off`: no index is written, and `off` removes one an earlier run wrote. |
| Which skills | Host installs (`setup`, `bootstrap harness`) list all bundled skills; hosted and thin-client connections leave out the host-maintenance ones. |
-| Opt out | `--skill-loading off`; `--no-instructions` removes both blocks; `--remove` takes both out and deletes a file only gbrain created once nothing else is in it. |
+| Opt out | `--skill-loading off`; `--no-instructions` removes both blocks; `--remove` takes both out and deletes a file only gbrain created once nothing else is in it. On Codex, `--skill-loading off`, `--no-instructions` and `GBRAIN_SKILL_LOADING=off` also strip an index gbrain recorded in the other global instruction file of the same `CODEX_HOME` (`AGENTS.md` or `AGENTS.override.md`) and print it as a second skills line (`paired` in `--json`, in `--dry-run` too), so the index cannot return when the override file goes. |
| After an upgrade | The block records the skill catalog it indexes. `gbrain doctor` (`harness_wiring`) names a stale index and the refresh command (`gbrain setup <harness> --skills-index-only`, which rewrites only the skills block, keeping its recorded file, launcher and skill set). It never warns on a stale index alone, and nothing rewrites the file during an upgrade. |
| Launcher check | Before writing, setup runs `<launcher> bundled-skill --json` and refuses (nothing written, exit 1) when the launcher is not an absolute path, does not run, or serves other skills than the ones indexed. Pass `--gbrain-bin <absolute path>` to name another gbrain. `gbrain doctor` reports an index whose recorded launcher is gone. |
| Claude Code permission | Claude Code asks before each Bash command it has no rule for (and headless runs deny it), so on Claude Code spring also adds one rule, `Bash(<launcher> bundled-skill:*)`, to `~/.claude/settings.json`. gbrain records that it added it and takes it out with the last index that uses it; a rule you had before is left alone. If you delete the rule, gbrain doesn't add it back until you run with `--skill-loading spring` again. |
-| Choice record | `~/.gbrain/skill-loading.json` (harness, file, mode, launcher, audience, catalog, and the Claude Code rule and whether gbrain added it). |
+| Choice record | `~/.gbrain/skill-loading.json` (harness, file, mode, launcher, audience, catalog, and the Claude Code rule and whether gbrain added it). It and the brain-first record (`agent-instructions.json`) share one lock, `~/.gbrain/agent-instructions.lock`, held for each install step, so two installs at once cannot drop each other's entry. An install that cannot take the lock within 10 seconds changes nothing and says why (`ledger_locked` in `--json`); re-run it once the other install finishes. A dry run takes no lock. |
## Harness capability table