Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Skill resolver: a retargeted SKILL.md symlink makes the index stale; session GC never deletes a file a commit holds
garrytan78b8b5b0063d
diff --git a/docs/guides/skill-resolver.md b/docs/guides/skill-resolver.mdindex fcac3ba4b8..2b2917ad7b 100644--- a/docs/guides/skill-resolver.md+++ b/docs/guides/skill-resolver.md@@ -38,7 +38,7 @@ One catalog per skill set. Names are 1-64 characters of `a-z`, `0-9`, `_` and| Harness | Build | Notes ||---|---|---|| Claude Code | `gbrain skills index build --catalog claude-user --dir ~/.claude/skills --harness claude-code` | Plugin skills get their `<plugin>:` prefix from `.claude-plugin/plugin.json`. |-| Claude Code plugins | `gbrain skills index build --catalog claude-plugins --claude-plugins ~/.claude --harness claude-code` | The enabled user-scope plugins (`enabledPlugins` in `settings.json`, install paths from `plugins/installed_plugins.json`), each skill as `<plugin>:<skill>`. |+| Claude Code plugins | `gbrain skills index build --catalog claude-code-plugins --claude-plugins ~/.claude --harness claude-code` | The enabled user-scope plugins (`enabledPlugins` in `settings.json`, install paths from `plugins/installed_plugins.json`), each skill as `<plugin>:<skill>`. || Codex | `gbrain skills index build --catalog codex-user --dir ~/.codex/skills --harness codex` | Suggestion lines carry the SKILL.md path; Codex opens it. || Hermes, qm | `--dir <skills dir> --harness hermes` (or `qm`) | The id is the name the loader takes. || Pi, Cursor | `--dir <skills dir> --harness pi` (or `cursor`) | Suggestion lines carry the SKILL.md path; the agent reads the file. |@@ -101,9 +101,10 @@ absolute path:`/usr/bin/env GBRAIN_HOOK_LANE=skill-resolver /abs/path/to/gbrain hook user-prompt --harness hermes`.Setup does not wire it yet, so build `hermes-user` yourself(`gbrain skills index build --catalog hermes-user --dir ~/.hermes/skills---harness hermes`) and add `hermes` to `skills.resolver.harnesses` in+--harness hermes`), add `hermes` to `skills.resolver.harnesses` in`~/.gbrain/config.json` by hand (`gbrain config set` refuses that key, which-setup owns). Doctor's `skill_resolver` check does not cover Hermes yet. The lane+setup owns) and set `skills.resolver.enabled` to `true` there; the lane is+off without it. Doctor's `skill_resolver` check does not cover Hermes yet. The lanereads `extra.user_message`, `session_id` and `cwd` from the hook's stdin andanswers `{"context": "<block>"}`. Hermes sends the whole conversation historyon every turn, so the lane streams stdin and keeps only those three stringsdiff --git a/src/core/skills/resolver/catalog-files.ts b/src/core/skills/resolver/catalog-files.tsindex 63aab59c24..93155b6ea4 100644--- a/src/core/skills/resolver/catalog-files.ts+++ b/src/core/skills/resolver/catalog-files.ts@@ -6,7 +6,7 @@* needs; build.ts and sources.ts take these from here.*/import { createHash } from 'node:crypto';-import { existsSync, readdirSync, readFileSync, statSync, type Dirent } from 'node:fs';+import { existsSync, readdirSync, readFileSync, readlinkSync, statSync, type Dirent } from 'node:fs';import { join } from 'node:path';import { readBounded } from './fsutil.ts';import { catalogFile, skillIndexRoot, validCatalogName } from './paths.ts';@@ -33,9 +33,10 @@ export function listCatalogs(home: string): string[] {/** Entries a skills scan never reads: dot-entries (harness-owned state such as Codex's .system/ or Hermes's .usage.json, and .git) and node_modules. */export const skippedEntry = (name: string) => name.startsWith('.') || name === 'node_modules';-/** A hash of the directory entries that can change a catalog: subdirectories, symlinks and SKILL.md, never a skipped entry. */-export function listingKey(entries: readonly Dirent[]): string {- const names = entries.filter(e => !skippedEntry(e.name) && (e.isDirectory() || e.isSymbolicLink() || e.name === 'SKILL.md')).map(e => e.name).sort();+/** A hash of the directory entries that can change a catalog: subdirectories, symlinks (with their targets, so a retarget in place counts) and SKILL.md, never a skipped entry. */+export function listingKey(dir: string, entries: readonly Dirent[]): string {+ const target = (name: string) => { try { return readlinkSync(join(dir, name)); } catch { return ''; } };+ const names = entries.filter(e => !skippedEntry(e.name) && (e.isDirectory() || e.isSymbolicLink() || e.name === 'SKILL.md')).map(e => e.isSymbolicLink() ? `${e.name}\u0001${target(e.name)}` : e.name).sort();return createHash('sha256').update(names.join('\0')).digest('hex').slice(0, 16);}@@ -47,7 +48,7 @@ export function listingKey(entries: readonly Dirent[]): string {*/export function fingerprintChanged(fp: DirFingerprint, routing?: [string, number, number]): boolean {try {- for (const [d, m, key] of fp.dirs) if (statSync(d).mtimeMs !== m && (key === undefined || listingKey(readdirSync(d, { withFileTypes: true })) !== key)) return true;+ for (const [d, m, key] of fp.dirs) if (statSync(d).mtimeMs !== m && (key === undefined || listingKey(d, readdirSync(d, { withFileTypes: true })) !== key)) return true;for (const [f, size, m] of fp.files) { const st = statSync(f); if (st.size !== size || st.mtimeMs !== m) return true; }if (routing) { const st = statSync(routing[0]); if (st.size !== routing[1] || st.mtimeMs !== routing[2]) return true; }return false;diff --git a/src/core/skills/resolver/session.ts b/src/core/skills/resolver/session.tsindex d0dcfe12a9..ff7033bd3f 100644--- a/src/core/skills/resolver/session.ts+++ b/src/core/skills/resolver/session.ts@@ -174,7 +174,12 @@ export function gcSessions(home: string, now: number = Date.now()): number {return removed;}-/** gcSessions with async I/O only; it touches the GC stamp first, so the commit-path pass skips the next interval. */+/**+ * gcSessions with async I/O only; it touches the GC stamp first, so the+ * commit-path pass skips the next interval. An idle session file is deleted+ * only under its commit lease and after a second stat, so a commit landing+ * between the first stat and the unlink keeps its file; a held lease skips it.+ */export async function gcSessionsAsync(home: string, now: number = Date.now()): Promise<number> {const dir = sessionsDir(home);let names: string[];@@ -184,9 +189,16 @@ export async function gcSessionsAsync(home: string, now: number = Date.now()): Pawait writeFile(gcStamp(home), '', { mode: 0o600 });} catch { return 0; }let removed = 0;+ const idle = async (p: string) => now - (await stat(p)).mtimeMs > SESSION_TTL_MS;for (const name of gcSlice(names)) {const p = join(dir, name);- try { if (now - (await stat(p)).mtimeMs > SESSION_TTL_MS) { await unlink(p); removed++; } } catch { /* raced */ }+ try {+ if (!(await idle(p))) continue;+ if (!name.endsWith('.json')) { await unlink(p); removed++; continue; }+ const lease = await tryAcquireLeaseAsync(`${p}.lock`, { purpose: 'session-gc', leaseMs: 2000 });+ if (!lease) continue;+ try { if (await idle(p)) { await unlink(p); removed++; } } finally { await releaseLeaseAsync(lease); }+ } catch { /* raced */ }}return removed;}diff --git a/src/core/skills/resolver/sources.ts b/src/core/skills/resolver/sources.tsindex b1b7314b9a..52d747b8de 100644--- a/src/core/skills/resolver/sources.ts+++ b/src/core/skills/resolver/sources.ts@@ -138,7 +138,7 @@ export function readDirSources(dirs: readonly string[], rootNamespaces: readonlytry {const mtime = statSync(dir).mtimeMs;const listed = readdirSync(dir, { withFileTypes: true });- fp.dirs.push([dir, mtime, listingKey(listed)]);+ fp.dirs.push([dir, mtime, listingKey(dir, listed)]);entries = listed.map(e => e.name).filter(n => !skippedEntry(n)).sort();} catch { skipped.push({ reason: 'unreadable', path: dir }); continue; }for (const name of entries) {diff --git a/test/skill-resolver-catalogs.test.ts b/test/skill-resolver-catalogs.test.tsindex e3652710a9..cbd23c9020 100644--- a/test/skill-resolver-catalogs.test.ts+++ b/test/skill-resolver-catalogs.test.ts@@ -15,7 +15,7 @@* missing plugin indexes, or setup leaves the plugin catalog behind.*/import { afterAll, describe, expect, setDefaultTimeout, test } from 'bun:test';-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';import { runCli } from './helpers/cli-spawn.ts';@@ -232,6 +232,20 @@ describe('harness-owned entries in a skills root (HARN-52)', () => {writeFileSync(join(b.root, 'deploy', 'SKILL.md'), '---\nname: deploy\ndescription: Deploy a service to staging first\n---\nSteps.\n');expect(await stale(b.home)).toBe(true);});++ test('retargeting a SKILL.md symlink in place makes the index stale on the turn path', async () => {+ const home = tmp();+ const root = tmp('skres-symlink-');+ const d = join(root, 'tool');+ mkdirSync(d);+ writeFileSync(join(d, 'a.md'), '---\nname: old-deploy\ndescription: Deploy the widget service\n---\nSteps.\n');+ writeFileSync(join(d, 'b.md'), '---\nname: new-invoice\ndescription: Draft an invoice for a customer\n---\nSteps.\n');+ symlinkSync('a.md', join(d, 'SKILL.md'));+ await buildSkillIndex({ catalog: 'h', dirs: [root] }, { home });+ symlinkSync('b.md', join(d, 'SKILL.md.next'));+ renameSync(join(d, 'SKILL.md.next'), join(d, 'SKILL.md'));+ expect(await stale(home)).toBe(true);+ });});describe('a JSON list equal to a folder builds the same index (HARN-52)', () => {diff --git a/test/skill-resolver.test.ts b/test/skill-resolver.test.tsindex 435ab30707..9669a453c5 100644--- a/test/skill-resolver.test.ts+++ b/test/skill-resolver.test.ts@@ -26,7 +26,7 @@ import { lexTerms } from '../src/core/skills/resolver/tokenize.ts';import { isAcknowledgement, mentionsSkill } from '../src/core/skills/resolver/rank.ts';import { estimateTokens } from '../src/core/skills/resolver/block.ts';import { acquireLease, holdsLease, releaseLease, tryAcquireLease } from '../src/core/skills/resolver/lock.ts';-import { commitSession, commitSessionAsync, gcSessions, loadSession, sessionKey } from '../src/core/skills/resolver/session.ts';+import { commitSession, commitSessionAsync, gcSessions, gcSessionsAsync, loadSession, sessionGcSettled, sessionKey } from '../src/core/skills/resolver/session.ts';import { catalogFile } from '../src/core/skills/resolver/paths.ts';import { appendDailyLog, appendDailyLogSync, DAILY_LOG_DAY_CAP_BYTES, dailyLogFile, LANE_LOG, readRecentDailyLog, RESOLVER_LOG } from '../src/core/skills/resolver/daily-log.ts';import { EXCLUDE_MAX, STAT_CHECK_SLICE } from '../src/core/skills/resolver/resolve.ts';@@ -447,6 +447,21 @@ describe('sessions', () => {expect(gcSessions(home)).toBe(1);expect(existsSync(join(dir, file))).toBe(false);});++ test('async GC never deletes an idle session file while a commit holds its lease; the commit keeps the earlier state', async () => {+ const home = tmp();+ const key = sessionKey('on', undefined, 'gc-race');+ expect(await commitSessionAsync(home, key, { tokens: 100, suggested: ['a'], resuggested: [], reset: false })).toBe(true);+ await sessionGcSettled();+ const file = join(home, 'skill-index', 'sessions', `${key}.json`);+ const old = (Date.now() - 8 * 24 * 3600 * 1000) / 1000;+ utimesSync(file, old, old);+ let removed = -1;+ const ok = await commitSessionAsync(home, key, { tokens: 7, suggested: ['b'], resuggested: [], reset: false }, { at: async (stage) => { if (stage === 'held') removed = await gcSessionsAsync(home); } });+ expect(ok).toBe(true);+ expect(removed).toBe(0);+ expect(loadSession(home, key)).toMatchObject({ turn: 2, spent: 107 });+ });});describe('block', () => {