Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
docs: explain top_gate, per-harness skill dirs and lane session cleanup in the resolver guide
garrytan91ca02d7a0b2
diff --git a/docs/architecture/key-files/skills.md b/docs/architecture/key-files/skills.mdindex 2e03303791..0cdddebb8b 100644--- a/docs/architecture/key-files/skills.md+++ b/docs/architecture/key-files/skills.md@@ -46,21 +46,21 @@ Contract schemas: `docs/schemas/skill-resolver.v1.*.json`. Every module under`skill-catalog.ts` import, static or dynamic (`test/skill-resolver-module-graph.test.ts`).- `src/core/skills/resolver/index.ts` — the library entry (`gbrain/skill-resolver` export, and the entry of the Node bundle `gbrain-skill-resolver.mjs`). Re-exports build, status, remove, resolve, `openCatalog`, `buildSkillIndexOffThread`, `ResolverError`, `resolverHome`; `resetSkillSession` deletes one session's state; `gcSkillSessions` runs one bounded async GC pass; `RESOLVER_FEATURES` names what an adapter may rely on.-- `src/core/skills/resolver/resolve.ts` — one turn: `normalizeTurnInput` (the turn-input schema, unknown fields refused, message capped at 8 KB), catalog loading through a `TurnSource` (`openCatalogIndex`: receipt and ranker identity, index size; then per turn the gbrain version and, for `dir` and `claude_plugins` catalogs, the sliced stat freshness check: at most `STAT_CHECK_SLICE` entries per turn, a full sweep at most once per `STAT_CHECK_INTERVAL_MS`, cursor in `stat-check`; `stale.stamp` is written without fsync, only when absent and only for a catalog with `rebuild_argv`, never an adapter-owned stdin one), ack and no_match, explicit mentions first, merged-catalog interleave, the `min_match_strength` floor before the cut to k, `previous_user_message` as the no-match fallback, the session rules (k 5/3/1 at 50%/80% of the budget, strong-match pacing, no-repeat, one re-suggestion after 10 turns, a named skill past a spent budget, `budget_exhausted` kept on ack and no-match turns), the block and its `block_reason`, `explain`, `failOpen`, `deadlineMs`. Returns `commit()`; session state changes only through it. Pinned by `test/skill-resolver.test.ts` and `test/skill-resolver-contract.test.ts`.-- `src/core/skills/resolver/rank.ts` — the A5 BM25F ranker over an `IndexReader` (scores summed in the prototype's order, ranked by score over summed idf, ties by name then id), the multilingual acknowledgement list, `mentionsSkill` (a `/name` counts only as a leading slash command) and `reasonText`. `test/skill-resolver-reproduction.test.ts` pins top-5 equality with the Step 1 prototype.+- `src/core/skills/resolver/resolve.ts` — one turn: `normalizeTurnInput` (the turn-input schema, unknown fields refused, message capped at 8 KB), catalog loading through a `TurnSource` (`openCatalogIndex`: receipt and ranker identity, index size; then per turn the gbrain version and, for `dir` and `claude_plugins` catalogs, the sliced stat freshness check: at most `STAT_CHECK_SLICE` entries per turn, a full sweep at most once per `STAT_CHECK_INTERVAL_MS`, cursor in `stat-check`; `stale.stamp` is written without fsync, only when absent and only for a catalog with `rebuild_argv`, never an adapter-owned stdin one), ack and no_match, explicit mentions first, merged-catalog interleave, the `min_match_strength` floor before the cut to k, the off-by-default `top_gate` (best score over `maxIdf(n)` of its catalog, highest across catalogs, below the threshold empties the block as `weak_top_match`; an explicit mention bypasses it), `previous_user_message` as the no-match fallback, the session rules (k 5/3/1 at 50%/80% of the budget, strong-match pacing, no-repeat, one re-suggestion after 10 turns, a named skill past a spent budget, `budget_exhausted` kept on ack and no-match turns), the block and its `block_reason`, `explain`, `failOpen`, `deadlineMs`. Returns `commit()`; session state changes only through it. Pinned by `test/skill-resolver.test.ts` and `test/skill-resolver-contract.test.ts`.+- `src/core/skills/resolver/rank.ts` — the A5 BM25F ranker over an `IndexReader` (scores summed in the prototype's order, ranked by score over summed idf, ties by name then id), `maxIdf(n)` (the BM25 idf of a term in one of `n` skills, the `top_gate` divisor), the multilingual acknowledgement list, `mentionsSkill` (a `/name` counts only as a leading slash command) and `reasonText`. `test/skill-resolver-reproduction.test.ts` pins top-5 equality with the Step 1 prototype.- `src/core/skills/resolver/tokenize.ts` — `splitWords` (shared with `scoreSkillMatch` in `skill-catalog.ts`) and `lexTerms`, the frozen Step 1 term rule (stopwords, light stemming); CJK runs become overlapping bigrams. Vectors: `test/fixtures/skill-resolver/tokenizer-vectors.json`.- `src/core/skills/resolver/index-format.ts` — `index.bin` (magic `GBSKIDX1`, JSON header, field-length averages, per-skill lengths, sorted term dictionary, flat postings with per-field tf, per-skill meta), byte-identical for identical records; `VARIANT_PARAMS` (D and T constants), `fieldText`, `summaryOf` (the description cut at 120 characters), `IndexReader` (lazy postings and meta reads).- `src/core/skills/resolver/build.ts` — `buildSkillIndex` under the catalog lease (variant choice: T at a 25% trigger-or-routing share, kept down to 20%; publication only while the lease is held and the directory exists, receipt written last), `catalogStatus` (content tier: re-reads the source and re-hashes the index), `removeSkillIndex` (rename then delete, so a concurrent build fails `skill_index_removed`), `listCatalogs`, `sessionStatus`, `dirFingerprintSlice`, `catalogHash`.- `src/core/skills/resolver/sources.ts` — the four sources: `--dir` (real paths only, symlinks out of the root skipped, breadth-first, dot-entries and `node_modules` never read, a per-directory `listingKey` so a harness writing its own dot-files leaves the index fresh, first id wins, plugin namespace from `.claude-plugin/plugin.json`, stat fingerprint), `--bundled` (dynamic import of `src/core/skills/bundled.ts`, never the operations table), `--from-json` (`JSON_INPUT_CAP_BYTES` 64 MB, 10,000 entries, bodies trimmed to 4 KB, a snapshot over `JSON_SOURCE_CAP_BYTES` kept trimmed; an adapter list or OpenClaw's `skills list --json` as is, name as id; with `--dir`, `mergeSkillFolders` takes bodies, paths and triggers by name) and `--claude-plugins` (`readClaudePluginSources`: enabled user-scope plugins from `installed_plugins.json` and `settings.json`, as `<plugin>:<skill>`); `applyRouting`; bounds (`MAX_SKILLS`, `MAX_DIRS_VISITED`, `MAX_DEPTH`).- `src/core/skills/resolver/frontmatter.ts` — bounded SKILL.md reader (64 KB file, 4 KB body): name, description, `when_to_use`, triggers, `disable-model-invocation`.- `src/core/skills/resolver/routing.ts` — one RESOLVER-style routing file's table and compact-list rows, skipping the generated skills block.-- `src/core/skills/resolver/session.ts` — session state (`sessions/<sha256(scope, harness, id)>.json`: ids and counters only), `commitSession` under a short lease, file and id caps, 7-day GC with a per-run work bound; every commit (sync or async) then starts an async GC pass after it settles, at most once per `GC_INTERVAL_MS` (10 min) per home by the mtime of `logs/session-gc.stamp`, so new sessions keep deduping past `MAX_SESSION_FILES`.+- `src/core/skills/resolver/session.ts` — session state (`sessions/<sha256(scope, harness, id)>.json`: ids and counters only), `commitSession` under a short lease, file and id caps, 7-day GC with a per-run work bound; every commit (sync or async) then starts an async GC pass after it settles, at most once per `GC_INTERVAL_MS` (10 min) per home by the mtime of `logs/session-gc.stamp`, so new sessions keep deduping past `MAX_SESSION_FILES`. A pass may take a `GcBound` (`files`, `until`): the hook lane passes `LANE_GC_FILES` (64) and its deadline less `GC_RESERVE_MS` and awaits `sessionGcSettled()` before exit; the stamp is written only when a pass finishes, so a pass its deadline cut retries on the next turn.- `src/core/skills/resolver/handle.ts` — `openCatalog(catalogs, opts)`, the warm handle for long-lived hosts: keeps each catalog's receipt and open `IndexReader` and the settings, re-stats `receipt.json`, `index.bin` and `config.json` once per turn and reloads only what changed; turns run `resolve.ts` `runTurn`, so output, `pending`, `commit()` and errors equal `resolveSkills` apart from `meta.timing_ms` (`test/skill-resolver-runtime.test.ts`).- `src/core/skills/resolver/build-thread.ts` — `buildSkillIndexOffThread`: `buildSkillIndex` in a `node:worker_threads` Worker whose entry is the module's own URL (in the Node bundle, the bundle), run by a top-level guard keyed on `BUILD_THREAD_MARKER` in `workerData`; no worker file ships; a `ResolverError` comes back with its code, message, fix and context. The hook lane never reaches it (`test/skill-resolver-module-graph.test.ts`).- `src/core/skills/resolver/block.ts` — the `<relevant_skills>` block: header, one JSON-quoted line per suggestion (id, name, path for codex, openclaw, pi and cursor, summary unless names-only), one load line per harness or `--load-hint`, cut at whole lines to 400 tokens by `estimateTokens`.- `src/core/skills/resolver/lock.ts` — ownership leases (O_EXCL create, random token, expiry; reclaimed only after expiry; release and renewal check the token).-- `src/core/skills/resolver/config.ts` — `skills.resolver.session_token_budget` (0 or 100-50,000, default 2,000) and `auto_rebuild` / `GBRAIN_SKILLS_NO_AUTOREBUILD=1`, read straight from `config.json`; the lane's turn settings `top_k` (1-8, default 5), `min_match`, `pinned` (sent to resolve as exclude) and `per_harness.<harness>.{top_k,min_match}` (falling back to the global keys) through `laneTurnSettings` and the validators `validateTopK`, `validateMinMatch` and `validatePinned` (a bad value anywhere in the section is `skill_resolver_config_invalid`).-- `src/core/skills/resolver/limits.ts` — the shared limits and names: `TOP_K_DEFAULT` (5), `TOP_K_MAX` (8), `EXCLUDE_MAX` (1,024) and `MATCH_STRENGTHS` (`named`, then the field strengths from `name` to `body`), exported from the library.+- `src/core/skills/resolver/config.ts` — `skills.resolver.session_token_budget` (0 or 100-50,000, default 2,000) and `auto_rebuild` / `GBRAIN_SKILLS_NO_AUTOREBUILD=1`, read straight from `config.json`; the lane's turn settings `top_k` (1-8, default 5), `min_match`, `top_gate` (0-`TOP_GATE_MAX`, 0 or unset off), `pinned` (sent to resolve as exclude) and `per_harness.<harness>.{top_k,min_match,top_gate}` (falling back to the global keys) through `laneTurnSettings` and the validators `validateTopK`, `validateMinMatch`, `validateTopGate` and `validatePinned`; `per_harness.<claude-code|codex>.dirs` (at most `SKILL_DIRS_MAX` absolute paths, no `..`) through `configuredSkillDirs`, read by setup (a bad value anywhere in the section is `skill_resolver_config_invalid`).+- `src/core/skills/resolver/limits.ts` — the shared limits and names: `TOP_K_DEFAULT` (5), `TOP_K_MAX` (8), `TOP_GATE_MAX` (100), `EXCLUDE_MAX` (1,024) and `MATCH_STRENGTHS` (`named`, then the field strengths from `name` to `body`), exported from the library.- `src/core/skills/resolver/daily-log.ts` — the lane and resolver logs under `skill-index/logs/`: one file per UTC day (`lane-<day>.jsonl`, `resolver-<day>.log`), kept 14 days, capped at 2 MB a day; the first write of a day deletes older files and the undated legacy file. Never turn text.- `src/core/skills/resolver/paths.ts` — `resolverHome` (GBRAIN_HOME convention), catalog-name rule and confinement under `skill-index/`, the fixed file names.- `src/core/skills/resolver/errors.ts` — `ResolverError` codes (rows in `src/core/error-registry.ts`), `USAGE_CODES` (exit 2).@@ -68,8 +68,8 @@ Contract schemas: `docs/schemas/skill-resolver.v1.*.json`. Every module under- `src/core/skill-description.ts` — `oneLineDescription` (frontmatter description, block scalars folded, else the first body paragraph), shared by `skill-catalog.ts`, `bundled.ts` and the bundled source.- `src/core/skills/resolver/lane-worker.ts` — starts the hook lane's worker thread (`hook-worker.ts`) once per process; the CLI's lane fast path (`src/cli.ts`) calls it before loading the lane so the worker starts beside the CLI, and the lane takes that worker. Imports only `worker_threads`; in a compiled binary the worker path comes from the binary's `import.meta.url`. Null when the worker cannot start (the lane then reports `skill_resolver_internal`).- `src/core/skills/resolver/catalog-files.ts` — the catalog files the turn path reads: a catalog's receipt, the list of built catalogs and the sliced stat freshness check (`listingKey`, which also hashes each symlink's target) over a directory catalog's fingerprint. No source parser, so the hook worker loads only what a turn needs; `build.ts` and `sources.ts` import it.-- `src/core/skills/resolver/hook-lane.ts` + `hook-worker.ts` + `hook-input.ts` — the hook lane (`GBRAIN_HOOK_LANE=skill-resolver`, dispatched first in `src/commands/hook.ts` after the `GBRAIN_HOOKS=0` check; `--harness claude-code|codex|hermes`): per-harness wire shapes in `LANE_IO` (Claude Code and Codex: top-level `prompt` in, `hookSpecificOutput.additionalContext` out; Hermes `pre_llm_call`: `extra.user_message` in through `readJsonFields`, the streaming reader over `Bun.stdin` that keeps only the named string paths and skips any history size unbuffered, `{"context"}` out; Hermes has no owner carrier and no compaction event), 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 catalogs (each only once its receipt exists, else outcome `no_catalog`: `<harness>-user`, `claude-code-plugins`, then the project catalog: `claude-code-project-<root hash>` over `.claude/skills`, or `codex-project-<dir-list hash>` over each `.agents/skills` from the `.git` root down to cwd, root first, without `~/.agents/skills`; built by a detached `skills index build`, stamp-limited to once a minute) and the daily lane log (`daily-log.ts`: `skill-index/logs/lane-<date>.jsonl`, kept 14 days). 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 UserPromptSubmit and SessionStart groups, each trusted in `config.toml` (`inspectSkillResolverHook`: absent, wired, untrusted, or outdated when UserPromptSubmit lacks its SessionStart entry; sync rewrites it), the file-plane keys (`skills.resolver.*`, engine-free in `gbrain config`; an unreadable file is never rewritten; a non-object `per_harness` entry reads as unset and set/unset replace it), and the build-then-write order (≥1 skill or `skill_resolver_setup_incomplete`). Pinned by `test/setup-skill-resolver.test.ts`.+- `src/core/skills/resolver/hook-lane.ts` + `hook-worker.ts` + `hook-input.ts` — the hook lane (`GBRAIN_HOOK_LANE=skill-resolver`, dispatched first in `src/commands/hook.ts` after the `GBRAIN_HOOKS=0` check; `--harness claude-code|codex|hermes`): per-harness wire shapes in `LANE_IO` (Claude Code and Codex: top-level `prompt` in, `hookSpecificOutput.additionalContext` out; Hermes `pre_llm_call`: `extra.user_message` in through `readJsonFields`, the streaming reader over `Bun.stdin` that keeps only the named string paths and skips any history size unbuffered, `{"context"}` out; Hermes has no owner carrier and no compaction event), 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, then one bounded session GC pass awaited before exit, 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 catalogs (each only once its receipt exists, else outcome `no_catalog`: `<harness>-user`, `claude-code-plugins`, then the project catalog: `claude-code-project-<root hash>` over `.claude/skills`, or `codex-project-<dir-list hash>` over each `.agents/skills` from the `.git` root down to cwd, root first, without `~/.agents/skills`; built by a detached `skills index build`, stamp-limited to once a minute) and the daily lane log (`daily-log.ts`: `skill-index/logs/lane-<date>.jsonl`, kept 14 days). 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 UserPromptSubmit and SessionStart groups, each trusted in `config.toml` (`inspectSkillResolverHook`: absent, wired, untrusted, or outdated when UserPromptSubmit lacks its SessionStart entry; sync rewrites it), the file-plane keys (`skills.resolver.*`, engine-free in `gbrain config`; an unreadable file is never rewritten; a non-object `per_harness` entry reads as unset and set/unset replace it), the user catalog's extra directories from `per_harness.<harness>.dirs` (missing ones skipped, kept in `rebuild_argv`; an invalid value stops setup before any write), 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 (an `outdated` hook warns with `gbrain setup <harness> --skill-loading resolve`), 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`, `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.diff --git a/docs/guides/skill-resolver.md b/docs/guides/skill-resolver.mdindex 6db5004b36..275e360603 100644--- a/docs/guides/skill-resolver.md+++ b/docs/guides/skill-resolver.md@@ -119,11 +119,22 @@ The lane always exits 0 and prints nothing when it cannot deliver:deadline the process prints nothing, exits and commits no session state.- **Turn settings:** `skills.resolver.top_k` (1-8, default 5),`skills.resolver.min_match` (the weakest `match_strength` to suggest;- default every match) and `skills.resolver.pinned` (skill ids the harness- always loads itself, never suggested). `skills.resolver.per_harness.<harness>.top_k`- and `.min_match` override one harness; what it leaves out falls back to the+ default every match), `skills.resolver.top_gate` (off unless set; see+ [the gate](#top_gate-an-experimental-gate-off-by-default)) and+ `skills.resolver.pinned` (skill ids the harness always loads itself, never+ suggested). `skills.resolver.per_harness.<harness>.top_k`, `.min_match`+ and `.top_gate` override one harness; what it leaves out falls back to theglobal key, and an entry that is not an object counts as unset. Set them with `gbrain config set`; a bad value makes the lanelog `skill_resolver_config_invalid` and deliver nothing.+- **Extra skill directories:** `gbrain config set+ skills.resolver.per_harness.claude-code.dirs /abs/dir,/abs/other` (or+ `.codex.dirs`; at most 32 absolute paths) adds directories to that+ harness's user catalog. Setup builds the catalog from the default directory+ plus every listed one that exists, records them in the catalog's rebuild+ command (so the auto-rebuild keeps them), and keeps them on every later+ setup run; unset the key and run setup again to drop them.+- **Session cleanup:** after the dedupe commit the lane runs one session GC+ pass before it exits, at most 64 files and never past the deadline.- **Payload:** at most `skills.resolver.lane_payload_chars` characters of hookoutput (default 4000, 500 to 10,000); a larger block is dropped whole andcounted as `payload_dropped`.@@ -169,7 +180,7 @@ The JSON Schemas are checked in under `docs/schemas/`:- `skill-resolver.v1.turn-input.json`: `{message, previous_user_message?,session_id?, harness?, top_k (1-8, default 5), exclude? (up to 1,024 ids),- min_match_strength?, shadow?, expected_catalog_hash?, reset_session?}` for+ min_match_strength?, top_gate?, shadow?, expected_catalog_hash?, reset_session?}` for`--input-json -` or the library.- `skill-resolver.v1.turn-output.json`: the `--json` result. Everything outside`meta` is byte-identical for the same index, input and session state.@@ -188,15 +199,44 @@ Within v1, changes are additive only.(`"no_match"`). There is no score threshold: a weak match is stillsuggested, and each suggestion's `match_strength` says how it matched(`named` in the turn, else the first of `name`, `triggers`, `routing`,-`description`, `body`). `min_match_strength` (`--min-match`) sets a floor:-weaker matches are dropped before the cut to `top_k`, so `description` drops-body-only matches and the stronger ones still fill the block. A skill named in+`description`, `body`). `min_match_strength` (`--min-match`) filters+candidates: weaker matches are dropped before the cut to `top_k` and the+stronger ones still fill the block, so `description` drops body-only matches.+It is not a gate: in a large catalog some skill almost always matches a+message on its name somewhere in the ranking, so even `name` rarely empties+the block and instead swaps good description hits for weaker name hits. A+skill named inthe turn (`$name`, `@name`, a leading `/name`, "the name skill", or its fullid) ranks first. When the message matches no catalog word (a follow-up suchas "do it again"), `previous_user_message` (`--previous`) is ranked instead.+### top_gate: an experimental gate, off by default++`top_gate` (`--top-gate`, `skills.resolver.top_gate`) empties the block+when the best-ranked skill's score divided by its catalog's maximum idf,+`ln(1 + (n - 0.5) / 1.5)` for a catalog of `n` skills, is below the+threshold (0 to 100; unset or 0 is off). With merged catalogs it takes the+highest of each catalog's best. A skill named in the turn bypasses it. The+division keeps the number comparable across catalog sizes; it does not undo+message length, so long messages still score higher.++It stays off by default because no threshold has yet shown that it removes+suggestions on no-skill turns without hiding many right ones. Two offline+measurements disagree:++| Source | Turns | Gate fitted on | False suggestions on no-skill turns | hit@5 on skill turns, gated (ungated) |+|---|---|---|---|---|+| gbrain-evals `2026-11-07-skill-ranker-offline`, scored with `scripts/gate-probe.ts` | 320 test and gate-stress turns (terse skill requests, long no-skill messages), 250 / 750 / 1,500 skills | dev and stress-dev, at threshold 1.33 | 0.19 / 0.17 / 0.19 | 0.26 / 0.27 / 0.28 (0.52 / 0.56 / 0.61) |+| harness-evals set P dev half, HARN-52 (descriptive) | 146 turns, one 349-skill catalog | the same rows it is scored on, as a raw score of 4.16 (top_gate 0.76 on that catalog) | 0.03 | 0.71 (0.78) |++The first is a held-out score on turns written to break length-based gates;+the second is fitted and scored on the same rows. Treat `top_gate` as a+setting to measure, not one to turn on: the threshold that fits one catalog+and one kind of turn is not known to fit another.+An empty block carries `block_reason`: `ack`, `no_match`, `filtered` (every-match was excluded or below `min_match_strength`), `deduped` (every match was+match was excluded or below `min_match_strength`), `weak_top_match` (the best+skill scored below `top_gate`), `deduped` (every match wasalready suggested in the session), `paced` (past half the budget and the topmatch is not on a name, trigger or routing row), `budget_exhausted`, `shadow`(the live output of a `--shadow` turn) or `error`. It is null when the block@@ -242,8 +282,9 @@ With `--session <id>` the resolver remembers which skills it suggested:The key is `sha256(on|shadow, harness, session id)`: the same id under twoharnesses is two sessions, and merged catalogs share one. Session files idlefor 7 days are deleted: after a commit (at most once every 10 minutes per-home, at most 1,000 files a pass, with async I/O after the commit settles),-and on each build and status.+home, at most 1,000 files a pass, with async I/O after the commit settles;+the hook lane awaits a 64-file pass before it exits), and on each build and+status.Measured block size at k=5 over the Step 1 test turns on gbrain's own skills:median 267 tokens (Claude Code), 268 (Hermes), 270 (qm), 334 (Codex) and 339@@ -422,7 +463,9 @@ The `--from-json` catalog or routing file is malformed or over its size bound### skill_resolver_config_invalid`skills.resolver.session_token_budget` is not 0 or 100-50,000, a lane turn-setting (`top_k`, `min_match`, `pinned`, `per_harness`) is out of range, or+setting (`top_k`, `min_match`, `top_gate`, `pinned`, `per_harness`, including a+`dirs` list that is not absolute paths or names a harness other than+`claude-code` or `codex`) is out of range, orGBRAIN_HOME is not an absolute path.### skill_resolver_config_unreadablediff --git a/scripts/structural-suites.tsv b/scripts/structural-suites.tsvindex 9cf86dd56c..c3aed935ef 100644--- a/scripts/structural-suites.tsv+++ b/scripts/structural-suites.tsv@@ -389,6 +389,7 @@ test/skill-resolver-hook-lane.test.ts skill-resolver lane: codex project catalogtest/skill-resolver-hook-lane.test.ts skill-resolver lane: compiled binaries 1 readFileSynctest/skill-resolver-hook-lane.test.ts skill-resolver lane: delivery per harness 4 readFileSynctest/skill-resolver-hook-lane.test.ts skill-resolver lane: fail open 6 readFileSync+test/skill-resolver-hook-lane.test.ts skill-resolver lane: session GC before the process exits 1 readFileSynctest/skill-resolver-module-graph.test.ts the skill resolver module graph 4 readFileSynctest/skill-resolver-off-pin.test.ts (file-level) 1 readFileSynctest/skill-resolver-packaging.test.ts skill resolver packaging 4 bun-file,readFileSyncdiff --git a/test/fixtures/goldens/exports/runtime.json b/test/fixtures/goldens/exports/runtime.jsonindex 05f3dee335..3b0c7ec13e 100644--- a/test/fixtures/goldens/exports/runtime.json+++ b/test/fixtures/goldens/exports/runtime.json@@ -997,16 +997,22 @@],"./skill-resolver": ["BLOCK_TOKEN_CAP",+ "EXCLUDE_MAX","GBRAIN_VERSION","HARNESSES",+ "MATCH_STRENGTHS",+ "RESOLVER_FEATURES","ResolverError","SCHEMA_VERSION","buildSkillIndex",+ "buildSkillIndexOffThread","catalogStatus","commitSessionAsync","errorTurnOutput",+ "gcSkillSessions","listCatalogs","normalizeTurnInput",+ "openCatalog","removeSkillIndex","resetSkillSession","resolveSkills",diff --git a/test/fixtures/goldens/exports/types.json b/test/fixtures/goldens/exports/types.jsonindex 5216e93a68..0948085c9d 100644--- a/test/fixtures/goldens/exports/types.json+++ b/test/fixtures/goldens/exports/types.json@@ -8717,6 +8717,7 @@"members": ["bundled?: boolean | undefined","catalog: string",+ "claudePlugins?: string | undefined","dirs?: string[] | undefined","fromJson?: string | undefined","fromJsonStdin?: boolean | undefined",@@ -8731,7 +8732,7 @@"members": ["block: { token_cap: number; tokenizer: string; }","build: { args: string[]; rebuild_argv: string[] | null; ms: number; built_at: string; generation: number; }",- "catalog: { name: string; catalog_hash: string; source: { kind: \"dir\" | \"bundled\" | \"json\"; dirs?: string[]; stdin?: boolean; file?: string; snapshot?: \"source.json\"; bundled_skills?: number; }; fingerprint_sha256: string | null; skill_count: number; skipped: SkippedSkill[]; scope: \"user\" | \"project\"; hints: \"shown\" | \"names_only\"; harness: string | null; routing: { file: string; rows: number; unmatched: number; stat: [string, number, number]; } | null; }",+ "catalog: { name: string; catalog_hash: string; source: { kind: \"dir\" | \"bundled\" | \"json\" | \"claude_plugins\"; dirs?: string[]; stdin?: boolean; file?: string; snapshot?: \"source.json\"; bundled_skills?: number; claude_dir?: string; }; fingerprint_sha256: string | null; skill_count: number; skipped: SkippedSkill[]; scope: \"user\" | \"project\"; hints: \"shown\" | \"names_only\"; harness: string | null; routing: { file: string; rows: number; unmatched: number; stat: [string, number, number]; } | null; }","gbrain_commit: string | null","gbrain_version: string","index: { file: \"index.bin\"; index_hash: string; size: number; n_terms: number; n_postings: number; truncated_skills: number; }",@@ -8740,6 +8741,21 @@],"name": "BuildReceipt"},+ {+ "kind": "interface",+ "members": [+ "close: () => void",+ "resolve: (input: TurnInput | unknown, turn?: CatalogTurnOptions) => Promise<ResolveResult>"+ ],+ "name": "CatalogHandle"+ },+ {+ "kind": "type",+ "name": "CatalogHandleOptions",+ "signature": [+ "{ home?: string | undefined; failOpen?: boolean | undefined; deadlineMs?: number | undefined; sessionTokenBudget?: number | undefined; loadHint?: string | undefined; namesOnly?: boolean | undefined; explainTarget?: string | undefined; env?: NodeJS.ProcessEnv | undefined; now?: (() => number) | undefined; }"+ ]+ },{"kind": "interface","members": [@@ -8753,6 +8769,20 @@],"name": "CatalogStatus"},+ {+ "kind": "type",+ "name": "CatalogTurnOptions",+ "signature": [+ "{ failOpen?: boolean | undefined; deadlineMs?: number | undefined; sessionTokenBudget?: number | undefined; loadHint?: string | undefined; namesOnly?: boolean | undefined; explainTarget?: string | undefined; now?: (() => number) | undefined; }"+ ]+ },+ {+ "kind": "variable",+ "name": "EXCLUDE_MAX",+ "signature": [+ "1024"+ ]+ },{"kind": "interface","members": [@@ -8781,7 +8811,14 @@"kind": "variable","name": "HARNESSES","signature": [- "readonly [\"openclaw\", \"claude-code\", \"codex\", \"hermes\", \"qm\"]"+ "readonly [\"openclaw\", \"claude-code\", \"codex\", \"hermes\", \"qm\", \"pi\", \"cursor\"]"+ ]+ },+ {+ "kind": "variable",+ "name": "MATCH_STRENGTHS",+ "signature": [+ "readonly MatchStrength[]"]},{@@ -8791,6 +8828,13 @@"\"body\" | \"name\" | \"description\" | \"named\" | \"triggers\" | \"routing\""]},+ {+ "kind": "variable",+ "name": "RESOLVER_FEATURES",+ "signature": [+ "readonly string[]"+ ]+ },{"kind": "interface","members": [@@ -8888,10 +8932,12 @@"expected_catalog_hash?: string | undefined","harness?: string | undefined","message: string",+ "min_match_strength?: MatchStrength | undefined","previous_user_message?: string | undefined","reset_session?: boolean | undefined","session_id?: string | undefined","shadow?: boolean | undefined",+ "top_gate?: number | undefined","top_k?: number | undefined"],"name": "TurnInput"@@ -8900,6 +8946,7 @@"kind": "interface","members": ["block: string",+ "block_reason: BlockReason | null","block_tokens: number","budget_exhausted: boolean","catalog: string | null",@@ -8926,6 +8973,13 @@"(input: BuildInput, opts?: { home?: string; now?: () => number; }) => Promise<BuildReceipt>"]},+ {+ "kind": "function",+ "name": "buildSkillIndexOffThread",+ "signature": [+ "(input: BuildInput, opts?: { home?: string; }) => Promise<BuildReceipt>"+ ]+ },{"kind": "function","name": "catalogStatus",@@ -8937,7 +8991,7 @@"kind": "function","name": "commitSessionAsync","signature": [- "(home: string, key: string, delta: TurnDelta) => Promise<boolean>"+ "(home: string, key: string, delta: TurnDelta, hold?: CommitHold, gc?: GcBound) => Promise<boolean>"]},{@@ -8947,6 +9001,13 @@"(err: ResolverError, opts?: { shadow?: boolean; catalog?: string | null; }) => TurnOutput"]},+ {+ "kind": "function",+ "name": "gcSkillSessions",+ "signature": [+ "(opts?: { home?: string; now?: number; }) => Promise<number>"+ ]+ },{"kind": "function","name": "listCatalogs",@@ -8961,6 +9022,13 @@"(raw: unknown) => Required<Pick<TurnInput, \"message\" | \"top_k\" | \"exclude\" | \"shadow\" | \"reset_session\">> & TurnInput"]},+ {+ "kind": "function",+ "name": "openCatalog",+ "signature": [+ "(catalogs: string[], opts?: CatalogHandleOptions) => CatalogHandle"+ ]+ },{"kind": "function","name": "removeSkillIndex",