Skip to content

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.md
index 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.md
index 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 the
global key, and an entry that is not an object counts as unset. Set them with `gbrain config set`; a bad value makes the lane
log `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 hook
output (default 4000, 500 to 10,000); a larger block is dropped whole and
counted 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 still
suggested, 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 in
the turn (`$name`, `@name`, a leading `/name`, "the name skill", or its full
id) ranks first. When the message matches no catalog word (a follow-up such
as "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 was
already suggested in the session), `paced` (past half the budget and the top
match 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 two
harnesses is two sessions, and merged catalogs share one. Session files idle
for 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, or
GBRAIN_HOME is not an absolute path.
### skill_resolver_config_unreadable
diff --git a/scripts/structural-suites.tsv b/scripts/structural-suites.tsv
index 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 catalog
test/skill-resolver-hook-lane.test.ts skill-resolver lane: compiled binaries 1 readFileSync
test/skill-resolver-hook-lane.test.ts skill-resolver lane: delivery per harness 4 readFileSync
test/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 readFileSync
test/skill-resolver-module-graph.test.ts the skill resolver module graph 4 readFileSync
test/skill-resolver-off-pin.test.ts (file-level) 1 readFileSync
test/skill-resolver-packaging.test.ts skill resolver packaging 4 bun-file,readFileSync
diff --git a/test/fixtures/goldens/exports/runtime.json b/test/fixtures/goldens/exports/runtime.json
index 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.json
index 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",