Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

fix(coding-agent): cache spawn-ledger replays behind a stat guard (#2229)

Seth Kartena487fa419135
diff --git a/packages/coding-agent/.changes/eng-6093-rlm-ledger-edge-cache.md b/packages/coding-agent/.changes/eng-6093-rlm-ledger-edge-cache.md
new file mode 100644
index 0000000000..7558c9039c
--- /dev/null
+++ b/packages/coding-agent/.changes/eng-6093-rlm-ledger-edge-cache.md
@@ -0,0 +1 @@
+- Sped up roster and family resolution by caching the RLM spawn ledger's replayed edges behind a file-stat guard: unchanged files reuse the cached edges instead of re-reading and re-parsing the whole ledger, while any writer's append (this process or another daemon) still forces a fresh replay.
diff --git a/packages/coding-agent/src/modes/daemon/rlm-ledger.ts b/packages/coding-agent/src/modes/daemon/rlm-ledger.ts
index f8900ae23d..dcad64224a 100644
--- a/packages/coding-agent/src/modes/daemon/rlm-ledger.ts
+++ b/packages/coding-agent/src/modes/daemon/rlm-ledger.ts
@@ -8,6 +8,7 @@ import {
openSync,
realpathSync,
rmSync,
+ statSync,
writeSync,
} from "node:fs";
import { readdir, readFile, stat } from "node:fs/promises";
@@ -301,6 +302,11 @@ export class RlmSpawnLedger {
private readonly canonicalSessionsDir: string;
private queue: Promise<unknown> = Promise.resolve();
private seedAttempted = false;
+ /** Last replay guarded by a file stat snapshot; see replaySyncCached(). */
+ private edgeCache?: {
+ stat: { size: number; mtimeMs: number; ino: number };
+ edges: Map<string, RlmLedgerEdge>;
+ };
constructor(
agentDir: string,
@@ -342,7 +348,7 @@ export class RlmSpawnLedger {
appendRenameByChildPath(child: string, name: string): Promise<void> {
return this.enqueue(() => {
const target = canonicalSessionPath(child);
- for (const edge of this.replaySync().values()) {
+ for (const edge of this.replaySyncCached().values()) {
if (!edge.deleted && canonicalSessionPath(edge.child) === target) {
this.appendRecord({ v: 1, op: "rename", at: nowIso(), childId: edge.childId, child: target, name });
}
@@ -375,7 +381,9 @@ export class RlmSpawnLedger {
* as cleanup retries.
*/
edges(includeDeleted = false): Promise<RlmLedgerEdge[]> {
- return this.enqueue(() => [...this.replaySync().values()].filter((edge) => includeDeleted || !edge.deleted));
+ return this.enqueue(() =>
+ [...this.replaySyncCached().values()].filter((edge) => includeDeleted || !edge.deleted),
+ );
}
/**
@@ -394,7 +402,7 @@ export class RlmSpawnLedger {
return this.enqueue(async () => {
const target = canonicalSessionPath(sessionPath);
const family = await this.familyUnlocked();
- const edges = [...this.replaySync().values()].filter((edge) => !edge.deleted);
+ const edges = [...this.replaySyncCached().values()].filter((edge) => !edge.deleted);
const parentByChild = new Map(
edges.map((edge) => [canonicalSessionPath(edge.child), canonicalSessionPath(edge.parent)]),
);
@@ -466,7 +474,7 @@ export class RlmSpawnLedger {
// Advisory, per-process: catches double-admission mistakes inside this
// daemon. It is NOT a global uniqueness guarantee — other processes
// append to the same file between our read and write.
- for (const edge of this.replaySync().values()) {
+ for (const edge of this.replaySyncCached().values()) {
if (!edge.deleted && canonicalSessionPath(edge.child) === childPath && edge.childId !== input.childId) {
throw new Error(`RLM ledger: duplicate child session path ${childPath} (already ${edge.childId})`);
}
@@ -489,7 +497,7 @@ export class RlmSpawnLedger {
}
private async liveEdgesUnlocked(
- edges = [...this.replaySync().values()].filter((edge) => !edge.deleted),
+ edges = [...this.replaySyncCached().values()].filter((edge) => !edge.deleted),
): Promise<RlmLedgerEdge[]> {
const statCache = new Map<string, boolean>();
const exists = async (path: string): Promise<boolean> => {
@@ -517,7 +525,7 @@ export class RlmSpawnLedger {
// One replay, one stat snapshot: byChild comes from the same alive set that emits child rows,
// so a child whose dead edge was reconciled away degrades to a root row instead of vanishing.
let alive: RlmLedgerEdge[] = await this.liveEdgesUnlocked(
- [...this.replaySync().values()].filter((candidate) => !candidate.deleted),
+ [...this.replaySyncCached().values()].filter((candidate) => !candidate.deleted),
);
const byChild = new Map<string, RlmLedgerEdge>();
for (const edge of alive) {
@@ -718,6 +726,42 @@ export class RlmSpawnLedger {
{ v: 1, op: "meta", at: nowIso(), sessionsDir: this.canonicalSessionsDir } satisfies RlmLedgerMetaRecord,
],
});
+ // Our own writes must not be served stale from the stat-guarded cache;
+ // other processes' appends are caught by the stat guard itself.
+ this.edgeCache = undefined;
+ }
+
+ /**
+ * Replay the ledger behind a stat-guarded edge cache: a file whose size,
+ * mtime, and inode are unchanged reuses the cached edges instead of
+ * re-parsing. Any append forces a fresh replay - appendRecord drops the
+ * cache for our own writes, and another process's append changes the
+ * stat - so staleness stays bounded to in-flight appends. A missing file
+ * bypasses the cache and replays to an empty edge set.
+ */
+ private replaySyncCached(): Map<string, RlmLedgerEdge> {
+ let snapshot: { size: number; mtimeMs: number; ino: number } | undefined;
+ try {
+ const current = statSync(this.path);
+ snapshot = { size: current.size, mtimeMs: current.mtimeMs, ino: current.ino };
+ } catch {
+ snapshot = undefined;
+ }
+ const cache = this.edgeCache;
+ if (
+ snapshot !== undefined &&
+ cache !== undefined &&
+ cache.stat.size === snapshot.size &&
+ cache.stat.mtimeMs === snapshot.mtimeMs &&
+ cache.stat.ino === snapshot.ino
+ ) {
+ return cache.edges;
+ }
+ const edges = this.replaySync();
+ if (snapshot !== undefined) {
+ this.edgeCache = { stat: snapshot, edges };
+ }
+ return edges;
}
private replaySync(): Map<string, RlmLedgerEdge> {
diff --git a/packages/coding-agent/test/rlm-ledger.test.ts b/packages/coding-agent/test/rlm-ledger.test.ts
index ca8f077049..3112a3744a 100644
--- a/packages/coding-agent/test/rlm-ledger.test.ts
+++ b/packages/coding-agent/test/rlm-ledger.test.ts
@@ -108,6 +108,48 @@ describe("rlm spawn ledger", () => {
}
});
+ it("serves repeated reads through the stat-guarded cache without missing a rival writer's append", async () => {
+ const root = mkdtempSync(join(tmpdir(), "prime-rlm-ledger-"));
+ try {
+ const { sessionsDir, parentFile } = makeRoots(root);
+ const ledger = new RlmSpawnLedger(root, sessionsDir);
+ await ledger.appendSpawn({
+ childId: "sub-11111111",
+ parent: parentFile,
+ child: join(root, "a.jsonl"),
+ depth: 1,
+ name: "worker-a",
+ });
+
+ // Prime the cache: a read, then an unchanged-file read.
+ const first = await ledger.edges();
+ expect(first).toHaveLength(1);
+ const cached = await ledger.edges();
+ expect(cached).toHaveLength(1);
+
+ // A rival daemon process appends to the same file directly; the
+ // stat guard must notice and force a fresh replay.
+ const rivalLine = `${JSON.stringify({
+ v: 1,
+ op: "spawn",
+ at: new Date().toISOString(),
+ childId: "sub-22222222",
+ parent: parentFile,
+ child: join(root, "b.jsonl"),
+ depth: 1,
+ name: "worker-b",
+ })}\n`;
+ const { appendFileSync } = await import("node:fs");
+ appendFileSync(ledger.ledgerPath, rivalLine, "utf8");
+
+ const afterRival = await ledger.edges();
+ expect(afterRival).toHaveLength(2);
+ expect(afterRival.map((edge) => edge.childId).sort()).toEqual(["sub-11111111", "sub-22222222"]);
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+ });
+
it("rejects a duplicate canonical child path at append", async () => {
const root = mkdtempSync(join(tmpdir(), "prime-rlm-ledger-dup-"));
try {