Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
skill resolver: clear master's stacked guards (env-name census, remediation commands, key-files index)
garrytan2dcac734a135
diff --git a/docs/architecture/KEY_FILES.md b/docs/architecture/KEY_FILES.mdindex f7714f548d..e431ef64f8 100644--- a/docs/architecture/KEY_FILES.md+++ b/docs/architecture/KEY_FILES.md@@ -75,6 +75,7 @@ link it here; never raise the cap.| [Runtime](key-files/runtime.md) | `src/core/abort-check.ts` through `src/core/zombie-reap.ts` || [Security](key-files/security.md) | `src/core/destructive-guard.ts` through `src/core/write-gate-scan.ts`; [purge](key-files/memory-purge.md) || [Shared brain skills](key-files/shared-skills.md) | Canonical catalog, enrollment, migration, publication and harness integration |+| [Skill resolver](key-files/skill-resolver.md) | `src/core/skills/resolver/`, `gbrain skills index/resolve/library`, the hook lane and the Node bundle || [Skills](key-files/skills.md) | `src/core/audit-skill-brain-first.ts` through `src/core/skills-integrity.ts` || [Tooling And Tests](key-files/tooling-and-tests.md) | `.github/workflows/test.yml` through `test/remote-privacy-sweep.test.ts` || [CI Health And Test Guards](key-files/ci-health-and-test-guards.md) | `nightly-watch.yml` through `check-image-decoders-embedded.sh`, contributor audit, fix-wave gate |diff --git a/docs/architecture/key-files/skill-resolver.md b/docs/architecture/key-files/skill-resolver.mdindex 34e833e04d..9081a738a7 100644--- a/docs/architecture/key-files/skill-resolver.md+++ b/docs/architecture/key-files/skill-resolver.md@@ -26,6 +26,7 @@ Contract schemas: `docs/schemas/skill-resolver.v1.*.json`. Every module under- `src/core/skills/resolver/hook-lane.ts` + `hook-worker.ts` — the hook lane (`GBRAIN_HOOK_LANE=skill-resolver`, dispatched first in `src/commands/hook.ts` after the `GBRAIN_HOOKS=0` check): async config/stdin/carrier reads on the main thread, ranking in a worker (source: `hook-worker.ts` beside it; compiled binary: the second build entrypoint at `WORKER_SRC_PATH`, so every `bun build --compile` that ships a binary lists it), a 50 ms deadline that exits the process with no output and no commit, the commit (`commitSessionAsync`) on the main thread after delivery, the payload budget (`skills.resolver.lane_payload_chars`, dropped whole as `payload_dropped`), the one-owner rule (first carrier entry whose home has the lane on), the SessionStart compaction reset, the Claude Code project catalog (`claude-code-project-<root hash>`, built by a detached `skills index build`, stamp-limited to once a minute) and `skill-index/logs/lane.jsonl`. Test seams: `GBRAIN_TEST_SKILL_LANE_STALL`, `GBRAIN_TEST_SKILL_LANE_DEADLINE_MS`. Pinned by `test/skill-resolver-hook-lane.test.ts`.- `src/core/setup/skill-resolver-{lane,hook,config,setup}.ts` — `setup <claude-code|codex> --skill-loading resolve|off` and `--remove`: the lane identity leaf (marker `skill-resolver-v1`, which every other lane's ownership and yield test excludes), the Claude Code entries and the Codex group plus its `config.toml` trust, the file-plane keys (`skills.resolver.*`, engine-free in `gbrain config`; an unreadable file is never rewritten), and the build-then-write order (≥1 skill or `skill_resolver_setup_incomplete`). Pinned by `test/setup-skill-resolver.test.ts`.- `src/commands/doctor/checks/skill-resolver.ts` — doctor `skill_resolver` (emitted by the `harness_wiring` entry, whose details carry the same view): hook state, each catalog's content-tier freshness, recent lane outcomes and error codes; silent when nothing of the resolver exists.-- `src/commands/skill-resolver.ts` — the CLI (`src/cli/commands/skill-resolver.ts` dispatches; `src/cli/command-route.ts` routes only `skills index` and `skills resolve` here, so plain `gbrain skills` stays `list_skills`). Exit 0, 1 (runtime error), 0 with `--fail-open`, 2 (usage); commits a session turn only after stdout is written. Pinned by `test/skill-resolver-cli.test.ts` and `test/skill-resolver-guide.test.ts`.+- `src/commands/skill-resolver.ts` — the CLI (`src/cli/commands/skill-resolver.ts` dispatches; `src/cli/command-route.ts` routes only `skills index`, `skills resolve` and `skills library` here, so plain `gbrain skills` stays `list_skills`). Exit 0, 1 (runtime error), 0 with `--fail-open`, 2 (usage); commits a session turn only after stdout is written. Pinned by `test/skill-resolver-cli.test.ts` and `test/skill-resolver-guide.test.ts`.- `scripts/bench-skill-resolver.ts` — the latency bars (cold turn p95: 10 ms at 1,000 skills, 40 ms at 7,500), enforced by `.github/workflows/skill-resolver-bench.yml` on a 2-vCPU runner.-- `scripts/build-skill-resolver-bundle.ts` — builds and Node-smoke-tests `gbrain-skill-resolver.mjs`; the release job `skill-resolver-bundle` attaches it.+- `src/commands/skill-resolver-library.ts` — the one Node-bundle builder (Bun.build of the library entry, written atomically, sha256 returned) behind `gbrain skills library` (default `GBRAIN_HOME/.gbrain/lib/gbrain-skill-resolver.mjs`) and the release script; a compiled binary has no source and refuses with `skill_source_unreadable`. Pinned by `test/skill-resolver-packaging.test.ts`.+- `scripts/build-skill-resolver-bundle.ts` — builds and Node-smoke-tests `gbrain-skill-resolver.mjs` and writes its `.sha256`; the release job `skill-resolver-bundle` attaches both and checks the sum before publishing.diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.mdindex e963974813..2b41300bf5 100644--- a/docs/guides/error-codes.md+++ b/docs/guides/error-codes.md@@ -4654,7 +4654,7 @@ More: [docs/guides/skill-resolver.md#skill_resolver_config_invalid](../../docs/g| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable ||---|---|---|---|---|---|---|-| config.json exists but cannot be read or parsed, so the skill resolver lane stays silent and setup writes none of its keys (the file is never rewritten). | The request itself was wrong or no longer matches the brain; nothing was changed. | Fix or move <gbrain home>/config.json (it must be a JSON object), then run gbrain doctor --only skill_resolver. Run: gbrain doctor --only skill_resolver --json | agent | `repeat the read that failed` | 1 | no |+| config.json exists but cannot be read or parsed, so the skill resolver lane stays silent and setup writes none of its keys (the file is never rewritten). | The request itself was wrong or no longer matches the brain; nothing was changed. | Fix or move config.json in the gbrain config directory (GBRAIN_HOME/.gbrain, else ~/.gbrain; it must be a JSON object), then run gbrain doctor --only skill_resolver. Run: gbrain doctor --only skill_resolver --json | agent | `repeat the read that failed` | 1 | no |More: [docs/guides/skill-resolver.md#skill_resolver_config_unreadable](../../docs/guides/skill-resolver.md#skill_resolver_config_unreadable)diff --git a/src/core/error-registry.ts b/src/core/error-registry.tsindex bf077a3753..902eb0be6b 100644--- a/src/core/error-registry.ts+++ b/src/core/error-registry.ts@@ -739,7 +739,7 @@ export const CODES = {skill_resolve_no_input: { class: 'caller', exit: 2, summary: 'gbrain skills resolve got no message: no --text, and stdin was a terminal or empty.', docs: 'docs/guides/skill-resolver.md#skill_resolve_no_input', suggestion: 'Pass --text "<message>", or pipe turn JSON to gbrain skills resolve --input-json -.' },skill_resolve_timeout: { class: 'retryable', summary: 'The skill resolver ran past its deadline, so the turn got no block and no session state was committed.', docs: 'docs/guides/skill-resolver.md#skill_resolve_timeout', suggestion: 'The turn proceeds without a block; check the catalog size with gbrain skills index status.' },skill_resolver_config_invalid: { class: 'caller', summary: 'A skill resolver setting is out of range (skills.resolver.session_token_budget must be 0 or 100-50000) or GBRAIN_HOME is not an absolute path.', docs: 'docs/guides/skill-resolver.md#skill_resolver_config_invalid', suggestion: 'Fix the value in config.json under skills.resolver (default budget 2000), or GBRAIN_HOME.' },- skill_resolver_config_unreadable: { class: 'caller', summary: 'config.json exists but cannot be read or parsed, so the skill resolver lane stays silent and setup writes none of its keys (the file is never rewritten).', docs: 'docs/guides/skill-resolver.md#skill_resolver_config_unreadable', suggestion: 'Fix or move <gbrain home>/config.json (it must be a JSON object), then run gbrain doctor --only skill_resolver.', fix: { argv: ['gbrain', 'doctor', '--only', 'skill_resolver', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Shows the resolver lane state and the config problem; changes nothing.' } },+ skill_resolver_config_unreadable: { class: 'caller', summary: 'config.json exists but cannot be read or parsed, so the skill resolver lane stays silent and setup writes none of its keys (the file is never rewritten).', docs: 'docs/guides/skill-resolver.md#skill_resolver_config_unreadable', suggestion: 'Fix or move config.json in the gbrain config directory (GBRAIN_HOME/.gbrain, else ~/.gbrain; it must be a JSON object), then run gbrain doctor --only skill_resolver.', fix: { argv: ['gbrain', 'doctor', '--only', 'skill_resolver', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Shows the resolver lane state and the config problem; changes nothing.' } },skill_resolver_setup_incomplete: { class: 'caller', summary: 'gbrain setup --skill-loading resolve found no skill to index (or could not build the catalog or wire the hook), so it wrote no config keys and no hook.', docs: 'docs/guides/skill-resolver.md#skill_resolver_setup_incomplete', suggestion: 'Add a skill to one of the scanned directories (the message names them), then run setup again.' },skill_resolver_internal: { class: 'server', summary: 'The skill resolver failed unexpectedly; a scrubbed trace (no turn text) was written under skill-index/logs/.', docs: 'docs/guides/skill-resolver.md#skill_resolver_internal', suggestion: 'Run gbrain skills index status and report the trace if it repeats.', fix: { argv: ['gbrain', 'skills', 'index', 'status', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Shows each catalog and its last build error; changes nothing.' } },skill_source_invalid: { class: 'caller', exit: 2, summary: 'The --from-json catalog or --routing file is not valid (not JSON, a malformed entry, over 10,000 skills or 8 MB, or a routing file over 1 MB), so nothing was built.', docs: 'docs/guides/skill-resolver.md#skill_source_invalid', suggestion: 'Pass a JSON array of {id, name, description, triggers?, routing?, body?, path?, eligible?} objects.' },diff --git a/test/cli-socket.test.ts b/test/cli-socket.test.tsindex 5483e63dd8..b9e6642d0b 100644--- a/test/cli-socket.test.ts+++ b/test/cli-socket.test.ts@@ -113,6 +113,7 @@ const NOT_READ_BEHAVIOR = new Set(['GBRAIN_SELF_UPGRADE_MODE', 'GBRAIN_RELEASE_CHANNEL', 'GBRAIN_SWAP_RECEIPT', 'GBRAIN_POST_UPGRADE_TIMEOUT_MS', 'GBRAIN_PROBE_PROMPT_GRACE_SECONDS', 'GBRAIN_BANNER','GBRAIN_BIN', 'GBRAIN_BIN_OVERRIDE', 'GBRAIN_BINARY_VERSION', 'GBRAIN_ROOT', 'GBRAIN_VERIFY', 'GBRAIN_FRICTION_RUN_ID', 'GBRAIN_NOTABILITY_EVAL_REAL','GBRAIN_WHOKNOWS_FIXTURE_PATH', 'GBRAIN_PACK_STAT_TTL_MS', 'GBRAIN_EMBEDDING', 'GBRAIN_BASE_PATH_PREFIXES', 'GBRAIN_RECOVERED_RETRY',+ 'GBRAIN_SKILLS_NO_AUTOREBUILD', 'GBRAIN_TEST_SKILL_LANE_DEADLINE_MS', 'GBRAIN_TEST_SKILL_LANE_STALL', 'GBRAIN_VERSION',]);describe('identity', () => {