Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Skill resolver hook lane: run the session GC pass before the process exits

garrytane19961a0c4da
diff --git a/src/core/skills/resolver/hook-lane.ts b/src/core/skills/resolver/hook-lane.ts
index 9e9c99f764..6df603a684 100644
--- a/src/core/skills/resolver/hook-lane.ts
+++ b/src/core/skills/resolver/hook-lane.ts
@@ -29,7 +29,9 @@
* that ends before the worker is needed terminates it. At the
* deadline the main thread prints nothing and exits the process at once,
* abandoning the worker, and commits no dedupe state: a commit starts only
- * after the block was written, on the main thread, before the deadline.
+ * after the block was written, on the main thread, before the deadline. The
+ * commit's session GC pass is awaited before the lane returns, bounded by
+ * LANE_GC_FILES files and by the time left before the deadline.
*
* One owner per event: like the harness, plugin and turn-rule lanes, it parses
* the carriers the harness merges (Claude Code: managed settings, the
@@ -54,9 +56,10 @@
* minute per catalog, unless skills.resolver.auto_rebuild is false or
* GBRAIN_SKILLS_NO_AUTOREBUILD=1.
*
- * Turn settings: skills.resolver.top_k, min_match, pinned (sent as exclude)
- * and per_harness.<harness>.{top_k,min_match} (config.ts laneTurnSettings);
- * unset, a turn is top_k 5 with every match and nothing excluded.
+ * Turn settings: skills.resolver.top_k, min_match, top_gate, pinned (sent as
+ * exclude) and per_harness.<harness>.{top_k,min_match,top_gate} (config.ts
+ * laneTurnSettings); unset, a turn is top_k 5 with every match, no gate and
+ * nothing excluded.
*
* Payload: the lane's own budget (skills.resolver.lane_payload_chars, default
* 4000 characters of hook JSON, Hermes's included); a block that does not fit
@@ -81,7 +84,7 @@ import { laneTurnSettings, type LaneTurnSettings } from './config.ts';
import { appendDailyLog, LANE_LOG } from './daily-log.ts';
import { HOOK_FIELD_CAP, readJsonFields } from './hook-input.ts';
import { assertCatalogName, catalogFile, CLAUDE_PLUGINS_CATALOG, logsDir, resolverHome } from './paths.ts';
-import { type CommitHold, commitSessionAsync, sessionKey, type TurnDelta } from './session.ts';
+import { type CommitHold, commitSessionAsync, LANE_GC_FILES, sessionGcSettled, sessionKey, type TurnDelta } from './session.ts';
import type { TurnOutput } from './resolve.ts';
import type { LaneWorkerTurn } from './hook-worker.ts';
import { laneWorkerFailed, startLaneWorker } from './lane-worker.ts';
@@ -98,6 +101,8 @@ const CONFIG_CAP_BYTES = 1024 * 1024;
const SPAWN_INTERVAL_MS = 60_000;
/** Time kept back from the worker's own deadline for delivery and the commit. */
const COMMIT_RESERVE_MS = 10;
+/** Time kept back from the deadline after the session GC pass, for the lane log and the exit. */
+const GC_RESERVE_MS = 5;
export type LaneHarness = 'claude-code' | 'codex' | 'hermes';
export { CLAUDE_PLUGINS_CATALOG };
@@ -358,7 +363,11 @@ async function laneTurn(event: 'user-prompt' | 'session-start', harness: LaneHar
}
const stall = env.GBRAIN_TEST_SKILL_LANE_STALL;
if (stall === 'commit-held' || stall === 'commit-written') ctl.commit.at = (stage) => (`commit-${stage}` === stall ? new Promise(() => {}) : Promise.resolve());
- if (posted.pending && !ctl.expired) await commitSessionAsync(home, posted.pending.key, posted.pending.delta, ctl.commit);
+ if (posted.pending && !ctl.expired) {
+ const gc = { files: LANE_GC_FILES, until: performance.now() + deadlineMs - elapsed() - GC_RESERVE_MS };
+ await commitSessionAsync(home, posted.pending.key, posted.pending.delta, ctl.commit, gc);
+ await sessionGcSettled();
+ }
return { outcome, catalogs };
}
diff --git a/src/core/skills/resolver/session.ts b/src/core/skills/resolver/session.ts
index ff7033bd3f..d4c67ca899 100644
--- a/src/core/skills/resolver/session.ts
+++ b/src/core/skills/resolver/session.ts
@@ -13,9 +13,13 @@
* a lost commit only means a skill may be suggested again.
*
* Every commit (either kind) then starts a session GC pass, at most once per
- * GC_INTERVAL_MS per home (the mtime of logs/session-gc.stamp), after the commit
- * has settled and with async I/O only, so it never costs a turn's deadline;
- * without it, past MAX_SESSION_FILES new sessions would never dedupe.
+ * GC_INTERVAL_MS per home (the mtime of logs/session-gc.stamp, touched when a
+ * pass finishes its slice), after the commit has settled and with async I/O
+ * only, so it never costs a turn's deadline; without it, past
+ * MAX_SESSION_FILES new sessions would never dedupe. A short-lived process
+ * (the hook lane) passes a GcBound and awaits sessionGcSettled() before it
+ * exits: at most LANE_GC_FILES files, stopping at its deadline, and a pass the
+ * deadline cut leaves no stamp, so the next turn tries again.
*/
import { createHash } from 'node:crypto';
import { promises, readdirSync, readFileSync, statSync, unlinkSync } from 'node:fs';
@@ -31,6 +35,10 @@ export const MAX_SESSION_IDS = 10_000;
export const SESSION_TTL_MS = 7 * 24 * 3600 * 1000;
export const GC_WORK_BOUND = 1000;
export const GC_INTERVAL_MS = 10 * 60 * 1000;
+export const LANE_GC_FILES = 64;
+
+/** A GC pass for a short-lived process: at most `files` files, none started after `until` (performance.now()). */
+export interface GcBound { files: number; until: number }
const gcStamp = (home: string) => join(logsDir(home), 'session-gc.stamp');
const STATE_CAP_BYTES = 2 * 1024 * 1024;
@@ -106,8 +114,8 @@ function applyDelta(s: SessionState, delta: TurnDelta): SessionState {
*/
export interface CommitHold { lease?: Lease | null; tmp?: string | null; at?: (stage: 'held' | 'written') => Promise<void> }
-export async function commitSessionAsync(home: string, key: string, delta: TurnDelta, hold: CommitHold = {}): Promise<boolean> {
- try { return await commitAsync(home, key, delta, hold); } finally { scheduleSessionGc(home); }
+export async function commitSessionAsync(home: string, key: string, delta: TurnDelta, hold: CommitHold = {}, gc?: GcBound): Promise<boolean> {
+ try { return await commitAsync(home, key, delta, hold); } finally { scheduleSessionGc(home, gc); }
}
async function commitAsync(home: string, key: string, delta: TurnDelta, hold: CommitHold): Promise<boolean> {
@@ -156,10 +164,10 @@ export async function resetSession(home: string, key: string): Promise<void> {
try { await unlink(statePath(home, key)); } catch { /* none */ }
}
-/** At most GC_WORK_BOUND of a directory's names, from a random start once there are more. */
-function gcSlice(names: string[]): string[] {
- const start = names.length > GC_WORK_BOUND ? Math.floor(Math.random() * names.length) : 0;
- return Array.from({ length: Math.min(names.length, GC_WORK_BOUND) }, (_, i) => names[(start + i) % names.length]!);
+/** At most `bound` of a directory's names, from a random start once there are more. */
+function gcSlice(names: string[], bound = GC_WORK_BOUND): string[] {
+ const start = names.length > bound ? Math.floor(Math.random() * names.length) : 0;
+ return Array.from({ length: Math.min(names.length, bound) }, (_, i) => names[(start + i) % names.length]!);
}
/** Delete session files idle for 7 days, examining at most GC_WORK_BOUND files per run. */
@@ -175,22 +183,20 @@ export function gcSessions(home: string, now: number = Date.now()): number {
}
/**
- * 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.
+ * gcSessions with async I/O only. 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. A pass
+ * that finishes its slice touches the GC stamp, so the commit-path pass skips
+ * the next interval; a bounded pass its deadline cut does not.
*/
-export async function gcSessionsAsync(home: string, now: number = Date.now()): Promise<number> {
+export async function gcSessionsAsync(home: string, now: number = Date.now(), bound?: GcBound): Promise<number> {
const dir = sessionsDir(home);
let names: string[];
- try {
- names = await readdir(dir);
- await mkdir(logsDir(home), { recursive: true, mode: 0o700 });
- await writeFile(gcStamp(home), '', { mode: 0o600 });
- } catch { return 0; }
+ try { names = await readdir(dir); } 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)) {
+ for (const name of gcSlice(names, bound?.files)) {
+ if (bound && performance.now() > bound.until) return removed;
const p = join(dir, name);
try {
if (!(await idle(p))) continue;
@@ -200,20 +206,24 @@ export async function gcSessionsAsync(home: string, now: number = Date.now()): P
try { if (await idle(p)) { await unlink(p); removed++; } } finally { await releaseLeaseAsync(lease); }
} catch { /* raced */ }
}
+ try {
+ await mkdir(logsDir(home), { recursive: true, mode: 0o700 });
+ await writeFile(gcStamp(home), '', { mode: 0o600 });
+ } catch { /* unwritable: the next commit tries again */ }
return removed;
}
let gcPass: Promise<number> | null = null;
-/** Start a GC pass once the current task ends, unless one ran in this home within GC_INTERVAL_MS. Never throws, never waited on. */
-export function scheduleSessionGc(home: string): void {
+/** Start a GC pass once the current task ends, unless one finished in this home within GC_INTERVAL_MS. Never throws; a long-lived host never waits on it. */
+export function scheduleSessionGc(home: string, bound?: GcBound): void {
const prev = gcPass;
gcPass = new Promise<void>(r => setImmediate(r)).then(async () => {
await prev;
try { if (Date.now() - (await stat(gcStamp(home))).mtimeMs < GC_INTERVAL_MS) return 0; } catch { /* none yet */ }
- return gcSessionsAsync(home);
+ return gcSessionsAsync(home, Date.now(), bound);
}).catch(() => 0);
}
-/** Resolves once the GC passes started so far have finished (tests). */
+/** Resolves once the GC passes started so far have finished (tests, and the hook lane before it exits). */
export const sessionGcSettled = async (): Promise<void> => { await gcPass; };
diff --git a/test/skill-resolver-hook-lane.test.ts b/test/skill-resolver-hook-lane.test.ts
index d501480123..f505166385 100644
--- a/test/skill-resolver-hook-lane.test.ts
+++ b/test/skill-resolver-hook-lane.test.ts
@@ -17,7 +17,7 @@
* and answers {"context"}; with the lane off it prints and writes nothing.
*/
import { afterAll, describe, expect, setDefaultTimeout, test } from 'bun:test';
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { Readable } from 'node:stream';
@@ -255,6 +255,27 @@ describe('skill-resolver lane: turn settings from config', () => {
});
});
+describe('skill-resolver lane: session GC before the process exits', () => {
+ test('a delivered turn deletes idle session files and stamps the pass; a turn within the interval leaves new ones', async () => {
+ const b = box();
+ seedSkills(claudeSkills(b));
+ await setup(b, 'claude-code');
+ const cmd = wired(b, 'claude-code');
+ const dir = join(b.home, '.gbrain', 'skill-index', 'sessions');
+ mkdirSync(dir, { recursive: true });
+ const old = (Date.now() - 8 * 86_400_000) / 1000;
+ const plant = (prefix: string, n: number) => Array.from({ length: n }, (_, i) => { const p = join(dir, `${prefix}${String(i).padStart(63, '0')}.json`); writeFileSync(p, '{}'); utimesSync(p, old, old); return p; });
+ const idle = plant('a', 40);
+ const r = await hook(b, cmd, { prompt: 'please deploy the widget to staging', session_id: 'gc-a' }, WIDE);
+ expect(contextOf(r)).toContain('deploy-widget');
+ expect(idle.filter((p) => existsSync(p))).toEqual([]);
+ expect(existsSync(join(b.home, '.gbrain', 'skill-index', 'logs', 'session-gc.stamp'))).toBe(true);
+ const later = plant('b', 3);
+ await hook(b, cmd, { prompt: 'write a changelog entry for the release', session_id: 'gc-b' }, WIDE);
+ expect(later.filter((p) => existsSync(p))).toHaveLength(3);
+ });
+});
+
describe('skill-resolver lane: a deadline during the dedupe commit', () => {
for (const stall of ['commit-held', 'commit-written'] as const) {
test(`${stall}: the exit releases the session lease and removes the temp file, so the next turn commits`, async () => {
diff --git a/test/skill-resolver.test.ts b/test/skill-resolver.test.ts
index 9669a453c5..4ad9e9d8f5 100644
--- a/test/skill-resolver.test.ts
+++ b/test/skill-resolver.test.ts
@@ -448,6 +448,20 @@ describe('sessions', () => {
expect(existsSync(join(dir, file))).toBe(false);
});
+ test('a bounded async GC pass examines at most its file budget and stamps; one past its deadline deletes nothing and leaves no stamp', async () => {
+ const home = tmp();
+ const dir = join(home, 'skill-index', 'sessions');
+ mkdirSync(dir, { recursive: true });
+ const old = (Date.now() - 8 * 24 * 3600 * 1000) / 1000;
+ for (let i = 0; i < 10; i++) { const p = join(dir, `${String(i).repeat(64)}.json`); writeFileSync(p, '{}'); utimesSync(p, old, old); }
+ const stamp = join(home, 'skill-index', 'logs', 'session-gc.stamp');
+ expect(await gcSessionsAsync(home, Date.now(), { files: 3, until: performance.now() - 1 })).toBe(0);
+ expect(existsSync(stamp)).toBe(false);
+ expect(await gcSessionsAsync(home, Date.now(), { files: 3, until: performance.now() + 60_000 })).toBe(3);
+ expect(readdirSync(dir)).toHaveLength(7);
+ expect(existsSync(stamp)).toBe(true);
+ });
+
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');