Skip to content

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.md
index 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 lane
reads `extra.user_message`, `session_id` and `cwd` from the hook's stdin and
answers `{"context": "<block>"}`. Hermes sends the whole conversation history
on every turn, so the lane streams stdin and keeps only those three strings
diff --git a/src/core/skills/resolver/catalog-files.ts b/src/core/skills/resolver/catalog-files.ts
index 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.ts
index 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()): P
await 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.ts
index 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: readonly
try {
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.ts
index 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.ts
index 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', () => {