Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Skill resolver: close the same-tick freshness gap and keep fsync off the turn path
garrytan988fd57e323f
diff --git a/src/core/skills/resolver/build.ts b/src/core/skills/resolver/build.tsindex c3b37499f8..48ed8b468b 100644--- a/src/core/skills/resolver/build.ts+++ b/src/core/skills/resolver/build.ts@@ -144,9 +144,33 @@ async function readSource(input: BuildInput): Promise<SourceRead> {interface Prepared { records: SkillRecord[]; skipped: SkippedSkill[]; source: SourceRead; routing: BuildReceipt['catalog']['routing']; catalog_hash: string }+/**+ * File mtimes come from a coarse clock (one kernel tick, 4 ms on most Linux+ * hosts), so an edit in the tick a build stats an entry keeps that entry's+ * mtime and the stat tier never sees it. A build whose newest stat is under+ * this old waits it out and reads the source again, so every published stat+ * predates the tick any later edit lands in.+ */+export const RACY_MTIME_MS = 25;+const RACY_REREADS = 2;++function newestStat(source: SourceRead, routing: [string, number, number] | undefined): number {+ let newest = routing?.[2] ?? -Infinity;+ for (const [, m] of source.fingerprint?.dirs ?? []) if (m > newest) newest = m;+ for (const [, , m] of source.fingerprint?.files ?? []) if (m > newest) newest = m;+ return newest;+}+async function prepare(input: BuildInput): Promise<Prepared> {- const source = await readSource(input);- const routingInfo = input.routing ? applyRouting(source.skills, input.routing) : null;+ let source = await readSource(input);+ let routingInfo = input.routing ? applyRouting(source.skills, input.routing) : null;+ for (let reread = 0; source.fingerprint && reread < RACY_REREADS; reread++) {+ const wait = newestStat(source, routingInfo?.stat) + RACY_MTIME_MS - Date.now();+ if (wait <= 0) break;+ await new Promise(r => setTimeout(r, wait));+ source = await readSource(input);+ routingInfo = input.routing ? applyRouting(source.skills, input.routing) : null;+ }const records = [...source.skills].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));const scope = input.scope ?? 'user';return {diff --git a/src/core/skills/resolver/fsutil.ts b/src/core/skills/resolver/fsutil.tsindex cf6b3cfd2c..87210d4212 100644--- a/src/core/skills/resolver/fsutil.ts+++ b/src/core/skills/resolver/fsutil.ts@@ -15,6 +15,19 @@ export function ensureDir(dir: string): void {}export function writeFileDurable(path: string, data: string | Uint8Array, mode = 0o600): void {+ replaceFile(path, data, mode, true);+}++/**+ * The same atomic replace without the fsyncs, for a hint a reader can lose:+ * the turn path's last-check stamp. A cloud disk's fsync can stall for tens+ * of milliseconds, which a 50 ms hook deadline cannot absorb every turn.+ */+export function writeFileAtomic(path: string, data: string | Uint8Array, mode = 0o600): void {+ replaceFile(path, data, mode, false);+}++function replaceFile(path: string, data: string | Uint8Array, mode: number, sync: boolean): void {const dir = dirname(path);const tmp = join(dir, `.${basename(path)}.tmp-${randomBytes(6).toString('hex')}`);const fd = openSync(tmp, 'wx', mode);@@ -22,7 +35,7 @@ export function writeFileDurable(path: string, data: string | Uint8Array, mode =const buf = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;let off = 0;while (off < buf.length) off += writeSync(fd, buf, off, buf.length - off);- fsyncSync(fd);+ if (sync) fsyncSync(fd);} catch (e) {closeSync(fd);try { unlinkSync(tmp); } catch { /* gone */ }@@ -35,7 +48,7 @@ export function writeFileDurable(path: string, data: string | Uint8Array, mode =try { unlinkSync(tmp); } catch { /* gone */ }throw e;}- flushDirectory(dir, { bestEffort: true });+ if (sync) flushDirectory(dir, { bestEffort: true });}/** The first `max` bytes of a file, plus its full size. */diff --git a/src/core/skills/resolver/resolve.ts b/src/core/skills/resolver/resolve.tsindex e8cc156925..e1fbe0c5be 100644--- a/src/core/skills/resolver/resolve.ts+++ b/src/core/skills/resolver/resolve.ts@@ -26,7 +26,7 @@ import { BLOCK_TOKEN_CAP, BLOCK_TOKENIZER, HARNESSES, renderBlock, type BlockLinimport { dirFingerprintSlice, listCatalogs, readReceipt, type BuildReceipt } from './build.ts';import { readResolverSettings, validateSessionTokenBudget } from './config.ts';import { ResolverError } from './errors.ts';-import { ensureDir, writeFileDurable } from './fsutil.ts';+import { ensureDir, writeFileAtomic, writeFileDurable } from './fsutil.ts';import { IndexReader, RANKER_ID, RANKER_VERSION } from './index-format.ts';import { assertCatalogName, catalogFile, logsDir, resolverHome } from './paths.ts';import { isAcknowledgement, mentionsSkill, rankIndex, reasonText, type RankResult } from './rank.ts';@@ -193,7 +193,7 @@ function loadCatalog(home: string, name: string, now: number, autoRebuild: booleelse if (!(last?.verdict === 'fresh' && last.cursor === 0 && age < STAT_CHECK_INTERVAL_MS)) {const slice = dirFingerprintSlice(home, name, last?.verdict === 'fresh' ? last.cursor : 0, STAT_CHECK_SLICE);stale = slice.changed ? 'source_changed' : null;- try { writeFileDurable(stamp, JSON.stringify({ verdict: slice.changed ? 'stale' : 'fresh', cursor: slice.changed ? 0 : slice.next })); } catch { /* read-only home: check again next turn */ }+ try { writeFileAtomic(stamp, JSON.stringify({ verdict: slice.changed ? 'stale' : 'fresh', cursor: slice.changed ? 0 : slice.next })); } catch { /* read-only home: check again next turn */ }}}if (stale && autoRebuild) { try { writeFileDurable(catalogFile(home, name, 'stale.stamp'), `${JSON.stringify({ reason: stale })}\n`); } catch { /* best effort */ } }diff --git a/test/skill-resolver.test.ts b/test/skill-resolver.test.tsindex 2f2da8e636..9847ded5f9 100644--- a/test/skill-resolver.test.ts+++ b/test/skill-resolver.test.ts@@ -29,6 +29,7 @@ import { acquireLease, holdsLease, releaseLease, tryAcquireLease } from '../src/import { commitSession, gcSessions, loadSession, sessionKey } from '../src/core/skills/resolver/session.ts';import { catalogFile } from '../src/core/skills/resolver/paths.ts';import { STAT_CHECK_SLICE } from '../src/core/skills/resolver/resolve.ts';+import { RACY_MTIME_MS } from '../src/core/skills/resolver/build.ts';const scratch: string[] = [];afterAll(() => { for (const d of scratch) rmSync(d, { recursive: true, force: true }); });@@ -656,6 +657,22 @@ describe('freshness and errors', () => {expect(existsSync(catalogFile(home, 'c', 'stale.stamp'))).toBe(false);});+ test('a build publishes no stat from the current mtime tick, so a skill added right after it is still caught', async () => {+ const home = tmp();+ const root = tmp('skres-dir-');+ const file = skillDir(root, 'deploy', { name: 'deploy', description: 'Ship it' });+ const tick = Date.now() / 1000;+ utimesSync(root, tick, tick);+ utimesSync(file, tick, tick);+ await buildSkillIndex({ catalog: 'c', dirs: [root] }, { home });+ const done = Date.now();+ const fp = JSON.parse(readFileSync(catalogFile(home, 'c', 'fingerprint.json'), 'utf8')) as { fingerprint: { dirs: [string, number][]; files: [string, number, number][] } };+ const stats = [...fp.fingerprint.dirs.map(d => d[1]), ...fp.fingerprint.files.map(f => f[2])];+ for (const m of stats) expect(done - m).toBeGreaterThanOrEqual(RACY_MTIME_MS);+ skillDir(root, 'reports', { name: 'reports', description: 'Write reports' });+ expect((await resolveSkills({ message: 'deploy' }, { home })).output.meta.index_stale).toBe(true);+ });+test('a gbrain upgrade marks the index stale; a newer receipt schema or a corrupt index refuses with the rebuild command', async () => {const home = tmp();const f = join(tmp(), 'cat.json');