Skip to content

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.ts
index 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.ts
index 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.ts
index 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 BlockLin
import { 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: boole
else 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.ts
index 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');