Skip to content

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

Rust

fix(coding-agent): stop saved-catalog refreshes from re-parsing the whole catalog (#2273)

Florian Brand27bd07994e3a
diff --git a/packages/coding-agent/.changes/catalog-canonicalization-memo.md b/packages/coding-agent/.changes/catalog-canonicalization-memo.md
new file mode 100644
index 0000000000..7045fe93a9
--- /dev/null
+++ b/packages/coding-agent/.changes/catalog-canonicalization-memo.md
@@ -0,0 +1,4 @@
+- Fixed repeated full transcript scans when refreshing large saved-session catalogs.
+- Fixed repeated filesystem path checks when refreshing RLM session catalogs.
+- Fixed saved-session deletion records when a path alias changes during deletion.
+- Fixed RLM child renames and deletions being ignored after a cached session path becomes a symlink or changes targets.
diff --git a/packages/coding-agent/src/core/session-manager.ts b/packages/coding-agent/src/core/session-manager.ts
index 92b699ea9c..0b6f2b16a7 100644
--- a/packages/coding-agent/src/core/session-manager.ts
+++ b/packages/coding-agent/src/core/session-manager.ts
@@ -1096,9 +1096,9 @@ interface SessionScanState {
const SESSION_SCAN_RESUME_TAIL_BYTES = 16;
const NEWLINE_BUFFER = Buffer.from("\n");
-// Memory bound (~tens of MB): LRU whole-state eviction only while over it, so
-// small states never thrash and an evicted file just pays one full rescan.
-const SESSION_SCAN_MAX_RETAINED_USAGE_ENTRIES = 100_000;
+// Memory/performance budget: whole-state LRU eviction can force a full catalog rescan every refresh.
+// Keep large families (~2k sessions, 150k usage entries) and growth headroom resident.
+const SESSION_SCAN_MAX_RETAINED_USAGE_ENTRIES = 400_000;
// Session files are append-only between whole-file rewrites, so scans resume
// from the last consumed byte offset; rewrites are detected by shrink,
diff --git a/packages/coding-agent/src/modes/daemon/rlm-ledger.ts b/packages/coding-agent/src/modes/daemon/rlm-ledger.ts
index bc9ce07bdc..635d92125c 100644
--- a/packages/coding-agent/src/modes/daemon/rlm-ledger.ts
+++ b/packages/coding-agent/src/modes/daemon/rlm-ledger.ts
@@ -287,7 +287,35 @@ function parseLedgerLine(line: string, index: number): RlmLedgerRecord | RlmLedg
}
}
+const CANONICAL_SESSION_PATH_CACHE_LIMIT = 4096;
+const CANONICAL_SESSION_PATH_CACHE_TTL_MS = 60_000;
+const canonicalSessionPathCache = new Map<string, { value: string; expiresAt: number }>();
+
+// Read-side identities only: cache both realpaths and missing-path fallbacks.
+// Symlinks created or retargeted after a read can change its canonical form;
+// the TTL bounds that drift. Direct append/seed canonicalization and leases stay uncached.
+function cachedCanonicalSessionPath(sessionPath: string): string {
+ const key = resolve(sessionPath);
+ const now = Date.now();
+ const cached = canonicalSessionPathCache.get(key);
+ if (cached) {
+ canonicalSessionPathCache.delete(key);
+ if (cached.expiresAt > now) {
+ canonicalSessionPathCache.set(key, cached);
+ return cached.value;
+ }
+ }
+ const value = canonicalSessionPath(key);
+ if (canonicalSessionPathCache.size >= CANONICAL_SESSION_PATH_CACHE_LIMIT) {
+ const oldestKey = canonicalSessionPathCache.keys().next().value;
+ if (oldestKey !== undefined) canonicalSessionPathCache.delete(oldestKey);
+ }
+ canonicalSessionPathCache.set(key, { value, expiresAt: now + CANONICAL_SESSION_PATH_CACHE_TTL_MS });
+ return value;
+}
+
function edgeKey(childId: string, child: string): string {
+ // Replay is already stat-cached; rebuild keys freshly so aliases match later canonical writes.
return `${childId}\u0000${canonicalSessionPath(child)}`;
}
@@ -403,20 +431,20 @@ export class RlmSpawnLedger {
/** Same-parent rows for a child session path, including the child itself. */
siblings(sessionPath: string): Promise<SessionInfo[]> {
return this.enqueue(async () => {
- const target = canonicalSessionPath(sessionPath);
+ const target = cachedCanonicalSessionPath(sessionPath);
const family = await this.familyUnlocked(await this.liveEdgesUnlocked());
const edges = [...this.replaySyncCached().values()].filter((edge) => !edge.deleted);
const parentByChild = new Map(
- edges.map((edge) => [canonicalSessionPath(edge.child), canonicalSessionPath(edge.parent)]),
+ edges.map((edge) => [cachedCanonicalSessionPath(edge.child), cachedCanonicalSessionPath(edge.parent)]),
);
const parent = parentByChild.get(target);
if (parent !== undefined) {
- const rows = family.filter((row) => parentByChild.get(canonicalSessionPath(row.path)) === parent);
+ const rows = family.filter((row) => parentByChild.get(cachedCanonicalSessionPath(row.path)) === parent);
// The target's edge can be reconciliation-dropped (parent file
// gone) while its own file still exists: fall back to presenting
// the survivor alone rather than an empty set the callers would
// read as "session not found".
- if (!rows.some((row) => canonicalSessionPath(row.path) === target)) {
+ if (!rows.some((row) => cachedCanonicalSessionPath(row.path) === target)) {
try {
if ((await stat(target)).isFile()) {
return [await this.sessionRow(target, 0, undefined, undefined)];
@@ -431,7 +459,7 @@ export class RlmSpawnLedger {
// ledger and the sessions dir is presented alone (matching the
// registry-walking reader's behavior for parentless sessions).
const roots = family.filter((row) => row.rlmDepth === 0);
- if (roots.some((row) => canonicalSessionPath(row.path) === target)) {
+ if (roots.some((row) => cachedCanonicalSessionPath(row.path) === target)) {
return roots;
}
try {
@@ -517,7 +545,10 @@ export class RlmSpawnLedger {
};
const alive: RlmLedgerEdge[] = [];
for (const edge of edges) {
- if ((await exists(canonicalSessionPath(edge.child))) && (await exists(canonicalSessionPath(edge.parent)))) {
+ if (
+ (await exists(cachedCanonicalSessionPath(edge.child))) &&
+ (await exists(cachedCanonicalSessionPath(edge.parent)))
+ ) {
alive.push(edge);
}
}
@@ -529,7 +560,7 @@ export class RlmSpawnLedger {
// so a child whose dead edge was reconciled away degrades to a root row instead of vanishing.
const byChild = new Map<string, RlmLedgerEdge>();
for (const edge of alive) {
- byChild.set(canonicalSessionPath(edge.child), edge);
+ byChild.set(cachedCanonicalSessionPath(edge.child), edge);
}
const rootPaths: string[] = [];
let rootEntries: string[] = [];
@@ -539,7 +570,7 @@ export class RlmSpawnLedger {
rootEntries = [];
}
for (const entry of rootEntries.filter((name) => name.endsWith(".jsonl")).sort()) {
- const path = canonicalSessionPath(join(this.canonicalSessionsDir, entry));
+ const path = cachedCanonicalSessionPath(join(this.canonicalSessionsDir, entry));
// Ledger children that live directly in the sessions dir are not roots.
if (byChild.has(path)) continue;
rootPaths.push(path);
@@ -551,10 +582,10 @@ export class RlmSpawnLedger {
// the whole family.
const depthByPath = new Map<string, number>();
for (const edge of alive) {
- depthByPath.set(canonicalSessionPath(edge.child), edge.depth);
+ depthByPath.set(cachedCanonicalSessionPath(edge.child), edge.depth);
}
alive = alive.filter((edge) => {
- const parentDepth = depthByPath.get(canonicalSessionPath(edge.parent));
+ const parentDepth = depthByPath.get(cachedCanonicalSessionPath(edge.parent));
if (parentDepth !== undefined && edge.depth !== parentDepth + 1) {
this.log(
`RLM ledger: dropped edge ${edge.childId} with contradictory depth (parent ${parentDepth}, child ${edge.depth})`,
@@ -570,9 +601,9 @@ export class RlmSpawnLedger {
for (const edge of alive) {
rows.push(
await this.sessionRow(
- canonicalSessionPath(edge.child),
+ cachedCanonicalSessionPath(edge.child),
edge.depth,
- canonicalSessionPath(edge.parent),
+ cachedCanonicalSessionPath(edge.parent),
edge.name,
metadataArtifact,
),
@@ -819,12 +850,12 @@ export class RlmSpawnLedger {
});
break;
case "rename": {
- const existing = edges.get(key);
+ const existing = this.edgeForKey(edges, key, record.childId);
if (existing) existing.name = record.name;
break;
}
case "delete": {
- const existing = edges.get(key);
+ const existing = this.edgeForKey(edges, key, record.childId);
if (existing) existing.deleted = record.reason;
break;
}
@@ -832,6 +863,27 @@ export class RlmSpawnLedger {
}
return edges;
}
+
+ /**
+ * Resolve a rename/delete record against the replayed edges. The canonical
+ * key joins a record written through an alias while the filesystem still
+ * agrees with its edge. A symlink retargeted after the record was written
+ * moves the spawn's key away from the recorded target; with no path left
+ * to join on, a childId carried by exactly one edge is the last durable
+ * identity the records share (childIds are only unique per parent, so an
+ * ambiguous id strands the record exactly as before).
+ */
+ private edgeForKey(edges: Map<string, RlmLedgerEdge>, key: string, childId: string): RlmLedgerEdge | undefined {
+ const direct = edges.get(key);
+ if (direct !== undefined) return direct;
+ let sole: RlmLedgerEdge | undefined;
+ for (const edge of edges.values()) {
+ if (edge.childId !== childId) continue;
+ if (sole !== undefined) return undefined;
+ sole = edge;
+ }
+ return sole;
+ }
}
// The catalog scan never visits session-artifacts, where RLM children persist:
@@ -843,7 +895,7 @@ export async function withPassiveRlmDescendantInfos(
options: { cwd?: string; onSession?: (info: SessionInfo) => void; log?: (message: string) => void } = {},
): Promise<SessionInfo[]> {
const sessions = [...savedSessions];
- const seen = new Set(savedSessions.map((info) => canonicalSessionPath(info.path)));
+ const seen = new Set(savedSessions.map((info) => cachedCanonicalSessionPath(info.path)));
let edges: RlmLedgerEdge[];
try {
edges = await ledger.liveEdges();
@@ -853,7 +905,7 @@ export async function withPassiveRlmDescendantInfos(
return sessions;
}
for (const edge of edges) {
- const childPath = canonicalSessionPath(edge.child);
+ const childPath = cachedCanonicalSessionPath(edge.child);
if (seen.has(childPath)) continue;
seen.add(childPath);
const info = await readSessionInfo(childPath);
@@ -874,7 +926,7 @@ export async function withPassiveRlmDescendantInfos(
// Shared user-delete policy: only a readable no-parent transcript is positively top-level; children and
// unknown targets tombstone via the ledger BEFORE the file delete (a tombstoned-but-undeleted file is
-// the accepted orphan of a failed delete).
+// the accepted orphan of a failed delete). Destructive matching bypasses the read-side identity cache.
export async function tombstoneSavedSessionDelete(
ledger: RlmSpawnLedger,
sessionPath: string,
@@ -893,7 +945,8 @@ export async function tombstoneSavedSessionDelete(
// live would resurrect a later recreation at that path as a subagent.
const matching = edges.filter((edge) => canonicalSessionPath(edge.child) === deletedPath);
for (const edge of matching) {
- await ledger.appendDelete({ childId: edge.childId, child: sessionPath, reason: "user" });
+ // Keep the matched identity if the requested alias changes before the queued append.
+ await ledger.appendDelete({ childId: edge.childId, child: edge.child, reason: "user" });
}
return { deletedInfo, ledgerEdge: matching[0] };
}
diff --git a/packages/coding-agent/test/rlm-ledger-canonicalization.test.ts b/packages/coding-agent/test/rlm-ledger-canonicalization.test.ts
new file mode 100644
index 0000000000..a0067d1513
--- /dev/null
+++ b/packages/coding-agent/test/rlm-ledger-canonicalization.test.ts
@@ -0,0 +1,523 @@
+import {
+ appendFileSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ realpathSync,
+ rmSync,
+ symlinkSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import * as sessionLease from "../src/core/session-lease.js";
+import { readSessionInfo, type SessionInfo, SessionManager } from "../src/core/session-manager.js";
+import {
+ type RlmLedgerRecord,
+ type RlmLedgerSpawnRecord,
+ RlmSpawnLedger,
+ tombstoneSavedSessionDelete,
+ withPassiveRlmDescendantInfos,
+} from "../src/modes/daemon/rlm-ledger.js";
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ vi.useRealTimers();
+ for (const root of tempDirs.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function fixture() {
+ const root = realpathSync(mkdtempSync(join(tmpdir(), "prime-ledger-canonicalization-")));
+ tempDirs.push(root);
+ const sessionsDir = join(root, "sessions");
+ mkdirSync(sessionsDir);
+ return { root, sessionsDir, ledger: new RlmSpawnLedger(root, sessionsDir) };
+}
+
+function makeSession(root: string, directory: string, name: string, parent?: string): string {
+ const manager = SessionManager.create(root, directory);
+ manager.newSession(parent ? { parentSession: parent, rlmDepth: 1 } : {});
+ manager.appendSessionInfo(name);
+ manager.flushNow();
+ const path = manager.getSessionFile();
+ if (!path) throw new Error("Missing session file");
+ return path;
+}
+
+function savedInfo(path: string): SessionInfo {
+ return {
+ path,
+ id: basename(path, ".jsonl"),
+ cwd: "",
+ rlmDepth: 0,
+ created: new Date(0),
+ modified: new Date(0),
+ messageCount: 0,
+ firstMessage: "",
+ allMessagesText: "",
+ };
+}
+
+function spawn(parent: string, child: string, childId = "sub-worker"): RlmLedgerSpawnRecord {
+ return { v: 1, op: "spawn", at: new Date(0).toISOString(), childId, parent, child, depth: 1, name: childId };
+}
+
+function writeRecords(ledger: RlmSpawnLedger, records: RlmLedgerRecord[]): void {
+ mkdirSync(dirname(ledger.ledgerPath), { recursive: true });
+ writeFileSync(ledger.ledgerPath, records.map((record) => `${JSON.stringify(record)}\n`).join(""));
+}
+
+function lastRecord(ledger: RlmSpawnLedger): RlmLedgerRecord {
+ return JSON.parse(readFileSync(ledger.ledgerPath, "utf8").trim().split("\n").at(-1)!) as RlmLedgerRecord;
+}
+
+describe("RLM ledger read-side canonicalization", () => {
+ it.each(["existing", "missing file", "missing directory", "file symlink", "directory symlink"])(
+ "preserves fresh replay identities and caches %s reads",
+ async (kind) => {
+ const { root, sessionsDir, ledger } = fixture();
+ const parent = join(sessionsDir, "parent.jsonl");
+ const directory = join(root, "real");
+ mkdirSync(directory);
+ writeFileSync(parent, "");
+ const existing = join(directory, "child.jsonl");
+ writeFileSync(existing, "");
+ const directoryAlias = join(root, "directory-alias");
+ symlinkSync(directory, directoryAlias, "dir");
+ const fileAlias = join(root, "file-alias.jsonl");
+ symlinkSync(existing, fileAlias, "file");
+ const paths: Record<string, string> = {
+ existing,
+ "missing file": join(directoryAlias, "missing.jsonl"),
+ "missing directory": join(root, "missing-directory", "child.jsonl"),
+ "file symlink": fileAlias,
+ "directory symlink": join(directoryAlias, "child.jsonl"),
+ };
+ const child = paths[kind];
+ const canonical = sessionLease.canonicalSessionPath(child);
+ expect(canonical).toBe(
+ kind === "missing file"
+ ? join(directory, "missing.jsonl")
+ : kind === "missing directory"
+ ? resolve(child)
+ : existing,
+ );
+ writeRecords(ledger, [
+ spawn(parent, child),
+ { v: 1, op: "rename", at: "renamed", childId: "sub-worker", child: canonical, name: "renamed" },
+ ]);
+ const canonicalize = vi.spyOn(sessionLease, "canonicalSessionPath");
+ const expected = [{ childId: "sub-worker", parent, child, depth: 1, name: "renamed" }];
+ expect(await ledger.edges()).toEqual(expected);
+ expect(canonicalize.mock.calls).toEqual([[child], [canonical]]);
+ const live = kind.startsWith("missing") ? [] : expected;
+ expect(await ledger.liveEdges()).toEqual(live);
+ canonicalize.mockClear();
+ expect(await ledger.edges()).toEqual(expected);
+ expect(await ledger.liveEdges()).toEqual(live);
+ expect(canonicalize).not.toHaveBeenCalled();
+ },
+ );
+
+ it("reuses warm identities across family, siblings, and passive descendant reads", async () => {
+ const { root, sessionsDir, ledger } = fixture();
+ const parent = makeSession(root, sessionsDir, "parent");
+ const first = makeSession(root, join(root, "first"), "first", parent);
+ const second = makeSession(root, join(root, "second"), "second", parent);
+ const parentAlias = join(root, "parent-alias.jsonl");
+ const firstAlias = join(root, "first-alias.jsonl");
+ const secondDirectoryAlias = join(root, "second-alias");
+ symlinkSync(parent, parentAlias, "file");
+ symlinkSync(first, firstAlias, "file");
+ symlinkSync(dirname(second), secondDirectoryAlias, "dir");
+ const secondAlias = join(secondDirectoryAlias, basename(second));
+ writeRecords(ledger, [
+ spawn(parentAlias, firstAlias, "sub-first"),
+ spawn(parentAlias, secondAlias, "sub-second"),
+ spawn(parentAlias, join(root, "missing.jsonl"), "sub-missing-file"),
+ spawn(parentAlias, join(root, "missing-directory", "child.jsonl"), "sub-missing-directory"),
+ ]);
+ const parentInfo = await readSessionInfo(parent);
+ const firstInfo = await readSessionInfo(first);
+ if (!parentInfo || !firstInfo) throw new Error("Missing session info");
+ const saved = [parentInfo, { ...firstInfo, path: firstAlias }];
+ const canonicalize = vi.spyOn(sessionLease, "canonicalSessionPath");
+ const snapshot = async () => ({
+ edges: await ledger.edges(),
+ live: await ledger.liveEdges(),
+ family: await ledger.family(),
+ siblings: await ledger.siblings(firstAlias),
+ roots: await ledger.siblings(parentAlias),
+ passive: await withPassiveRlmDescendantInfos(saved, ledger),
+ });
+ const cold = await snapshot();
+ expect(cold.edges).toHaveLength(4);
+ expect(cold.live).toHaveLength(2);
+ expect(cold.family.map((row) => [row.path, row.rlmDepth, row.parentSessionPath])).toEqual([
+ [parent, 0, undefined],
+ [first, 1, parent],
+ [second, 1, parent],
+ ]);
+ expect(cold.siblings.map((row) => row.path)).toEqual([first, second]);
+ expect(cold.roots.map((row) => row.path)).toEqual([parent]);
+ expect(cold.passive.map((row) => row.path)).toEqual([parent, firstAlias, second]);
+ expect(cold.passive[2]).toMatchObject({ parentSessionPath: parentAlias, rlmDepth: 1 });
+ expect(canonicalize).toHaveBeenCalled();
+ canonicalize.mockClear();
+ expect(await snapshot()).toEqual(cold);
+ expect(canonicalize).not.toHaveBeenCalled();
+ });
+
+ it.each([false, true])("expires a cached identity at 60 seconds without sliding (existing: %s)", async (exists) => {
+ vi.useFakeTimers({ toFake: ["Date"] });
+ const start = Date.UTC(2030, 0, 1);
+ vi.setSystemTime(start);
+ const { root, ledger } = fixture();
+ const original = makeSession(root, join(root, "original"), "original");
+ const replacement = makeSession(root, join(root, "replacement"), "replacement");
+ const alias = join(root, "alias.jsonl");
+ if (exists) symlinkSync(original, alias, "file");
+ const canonicalize = vi.spyOn(sessionLease, "canonicalSessionPath");
+ expect((await ledger.siblings(alias)).map((row) => row.path)).toEqual(exists ? [original] : []);
+ expect(canonicalize).toHaveBeenCalledOnce();
+ if (exists) rmSync(alias);
+ symlinkSync(replacement, alias, "file");
+ for (const elapsed of [30_000, 59_999]) {
+ vi.setSystemTime(start + elapsed);
+ expect((await ledger.siblings(alias)).map((row) => row.path)).toEqual([exists ? original : alias]);
+ }
+ expect(canonicalize).toHaveBeenCalledOnce();
+ vi.setSystemTime(start + 60_000);
+ expect((await ledger.siblings(alias)).map((row) => row.path)).toEqual([replacement]);
+ expect(canonicalize).toHaveBeenCalledTimes(2);
+ });
+
+ it("bounds the cache at 4096 entries and promotes recently read entries", async () => {
+ vi.useFakeTimers({ toFake: ["Date"] });
+ const { root, ledger } = fixture();
+ const rows = Array.from({ length: 4096 }, (_, index) => savedInfo(join(root, `missing-${index}.jsonl`)));
+ const canonicalize = vi.spyOn(sessionLease, "canonicalSessionPath");
+ expect(await withPassiveRlmDescendantInfos(rows, ledger)).toEqual(rows);
+ expect(canonicalize).toHaveBeenCalledTimes(4096);
+ canonicalize.mockClear();
+ await withPassiveRlmDescendantInfos([rows[0]], ledger);
+ expect(canonicalize).not.toHaveBeenCalled();
+ const extra = savedInfo(join(root, "overflow.jsonl"));
+ await withPassiveRlmDescendantInfos([extra], ledger);
+ expect(canonicalize).toHaveBeenCalledExactlyOnceWith(extra.path);
+ canonicalize.mockClear();
+ await withPassiveRlmDescendantInfos([rows[0], rows[2], rows[4095]], ledger);
+ expect(canonicalize).not.toHaveBeenCalled();
+ await withPassiveRlmDescendantInfos([rows[1]], ledger);
+ expect(canonicalize).toHaveBeenCalledExactlyOnceWith(rows[1].path);
+ });
+
+ it("shares resolved keys without conflating relative paths from different working directories", async () => {
+ const { root, ledger } = fixture();
+ const first = makeSession(root, join(root, "first"), "first");
+ const second = makeSession(root, join(root, "second"), "second");
+ const firstAlias = join(dirname(first), "alias.jsonl");
+ const secondAlias = join(dirname(second), "alias.jsonl");
+ symlinkSync(first, firstAlias, "file");
+ symlinkSync(second, secondAlias, "file");
+ const cwd = vi.spyOn(process, "cwd").mockReturnValue(dirname(first));
+ const canonicalize = vi.spyOn(sessionLease, "canonicalSessionPath");
+ expect((await ledger.siblings("alias.jsonl")).map((row) => row.path)).toEqual([first]);
+ expect((await ledger.siblings(firstAlias)).map((row) => row.path)).toEqual([first]);
+ expect((await ledger.siblings("./alias.jsonl")).map((row) => row.path)).toEqual([first]);
+ expect(canonicalize).toHaveBeenCalledExactlyOnceWith(firstAlias);
+ cwd.mockReturnValue(dirname(second));
+ expect((await ledger.siblings("alias.jsonl")).map((row) => row.path)).toEqual([second]);
+ expect(canonicalize).toHaveBeenLastCalledWith(secondAlias);
+ cwd.mockReturnValue(dirname(first));
+ expect((await ledger.siblings("alias.jsonl")).map((row) => row.path)).toEqual([first]);
+ expect(canonicalize).toHaveBeenCalledTimes(2);
+ });
+
+ it("tombstones every matching edge through a warm cached alias", async () => {
+ const { root, sessionsDir, ledger } = fixture();
+ const parent = makeSession(root, sessionsDir, "parent");
+ const child = makeSession(root, join(root, "child"), "child", parent);
+ const alias = join(root, "child-alias.jsonl");
+ symlinkSync(child, alias, "file");
+ writeRecords(ledger, [spawn(parent, alias, "sub-first"), spawn(parent, child, "sub-duplicate")]);
+ await ledger.siblings(alias);
+ const canonicalize = vi.spyOn(sessionLease, "canonicalSessionPath");
+ const result = await tombstoneSavedSessionDelete(ledger, alias, { runtimeKind: "subagent" });
+ expect(result.deletedInfo?.path).toBe(alias);
+ expect(result.ledgerEdge).toMatchObject({ childId: "sub-first", child: alias });
+ // Destructive matching and both appendDelete writes bypass the warm read cache.
+ expect(canonicalize.mock.calls).toEqual([[alias], [alias], [child], [alias], [child]]);
+ expect(await ledger.edges()).toEqual([]);
+ expect(await ledger.edges(true)).toEqual([
+ expect.objectContaining({ childId: "sub-first", deleted: "user" }),
+ expect.objectContaining({ childId: "sub-duplicate", deleted: "user" }),
+ ]);
+ });
+
+ it("matches the current symlink target for deletion despite a warm read identity", async () => {
+ const { root, sessionsDir, ledger } = fixture();
+ const parent = makeSession(root, sessionsDir, "parent");
+ const first = makeSession(root, join(root, "first"), "first", parent);
+ const second = makeSession(root, join(root, "second"), "second", parent);
+ const alias = join(root, "child-alias.jsonl");
+ symlinkSync(first, alias, "file");
+ writeRecords(ledger, [spawn(parent, first, "sub-first"), spawn(parent, second, "sub-second")]);
+ await ledger.siblings(alias);
+ rmSync(alias);
+ symlinkSync(second, alias, "file");
+
+ const result = await tombstoneSavedSessionDelete(ledger, alias, { runtimeKind: "subagent" });
+ expect(result.ledgerEdge).toMatchObject({ childId: "sub-second", child: second });
+ expect(await ledger.edges()).toEqual([
+ { childId: "sub-first", parent, child: first, depth: 1, name: "sub-first" },
+ ]);
+ expect(await ledger.edges(true)).toEqual([
+ { childId: "sub-first", parent, child: first, depth: 1, name: "sub-first" },
+ expect.objectContaining({ childId: "sub-second", child: second, deleted: "user" }),
+ ]);
+ });
+
+ it("tombstones the original canonical path after its warmed alias points elsewhere", async () => {
+ const { root, sessionsDir, ledger } = fixture();
+ const parent = makeSession(root, sessionsDir, "parent");
+ const first = makeSession(root, join(root, "first"), "first", parent);
+ const second = makeSession(root, join(root, "second"), "second", parent);
+ const alias = join(root, "child-alias.jsonl");
+ symlinkSync(first, alias, "file");
+ writeRecords(ledger, [spawn(parent, first, "sub-first"), spawn(parent, second, "sub-second")]);
+ await ledger.siblings(alias);
+ rmSync(alias);
+ symlinkSync(second, alias, "file");
+
+ const result = await tombstoneSavedSessionDelete(ledger, first, { runtimeKind: "subagent" });
+ expect(result.ledgerEdge).toMatchObject({ childId: "sub-first", child: first });
+ expect(await ledger.edges()).toEqual([
+ { childId: "sub-second", parent, child: second, depth: 1, name: "sub-second" },
+ ]);
+ expect(await ledger.edges(true)).toEqual([
+ expect.objectContaining({ childId: "sub-first", child: first, deleted: "user" }),
+ { childId: "sub-second", parent, child: second, depth: 1, name: "sub-second" },
+ ]);
+ });
+
+ it("preserves the matched edge key when an alias changes before the delete append", async () => {
+ const { root, sessionsDir, ledger } = fixture();
+ const parent = makeSession(root, sessionsDir, "parent");
+ const first = makeSession(root, join(root, "first"), "first", parent);
+ const second = makeSession(root, join(root, "second"), "second", parent);
+ const alias = join(root, "child-alias.jsonl");
+ symlinkSync(first, alias, "file");
+ writeRecords(ledger, [spawn(parent, first, "sub-first"), spawn(parent, second, "sub-second")]);
+ await ledger.siblings(alias);
+ const appendDelete = ledger.appendDelete.bind(ledger);
+ const append = vi.spyOn(ledger, "appendDelete").mockImplementation((input) => {
+ rmSync(alias);
+ symlinkSync(second, alias, "file");
+ return appendDelete(input);
+ });
+
+ const result = await tombstoneSavedSessionDelete(ledger, alias, { runtimeKind: "subagent" });
+ expect(result.ledgerEdge).toMatchObject({ childId: "sub-first", child: first });
+ expect(append).toHaveBeenCalledExactlyOnceWith({ childId: "sub-first", child: first, reason: "user" });
+ expect(lastRecord(ledger)).toMatchObject({ op: "delete", childId: "sub-first", child: first, reason: "user" });
+ expect(await ledger.edges()).toEqual([
+ { childId: "sub-second", parent, child: second, depth: 1, name: "sub-second" },
+ ]);
+ expect(await ledger.edges(true)).toEqual([
+ expect.objectContaining({ childId: "sub-first", child: first, deleted: "user" }),
+ { childId: "sub-second", parent, child: second, depth: 1, name: "sub-second" },
+ ]);
+ });
+
+ it.each(["spawn", "rename", "delete", "rename by alias", "rename aliased edge"])(
+ "keeps %s writes fresh after a cached missing path becomes a symlink",
+ async (operation) => {
+ const { root, sessionsDir, ledger } = fixture();
+ const parent = makeSession(root, sessionsDir, "parent");
+ const child = makeSession(root, join(root, "child"), "child", parent);
+ const parentAlias = join(root, "parent-alias.jsonl");
+ const childAlias = join(root, "child-alias.jsonl");
+ if (operation !== "spawn") {
+ writeRecords(ledger, [spawn(parent, operation === "rename aliased edge" ? childAlias : child)]);
+ }
+ await withPassiveRlmDescendantInfos([savedInfo(parentAlias), savedInfo(childAlias)], ledger);
+ symlinkSync(parent, parentAlias, "file");
+ symlinkSync(child, childAlias, "file");
+ switch (operation) {
+ case "spawn":
+ await ledger.appendSpawn({
+ childId: "sub-worker",
+ parent: parentAlias,
+ child: childAlias,
+ depth: 1,
+ name: "fresh",
+ });
+ break;
+ case "rename":
+ await ledger.appendRename({ childId: "sub-worker", child: childAlias, name: "fresh" });
+ break;
+ case "delete":
+ await ledger.appendDelete({ childId: "sub-worker", child: childAlias, reason: "user" });
+ break;
+ default:
+ await ledger.appendRenameByChildPath(operation === "rename by alias" ? childAlias : child, "fresh");
+ }
+ expect(lastRecord(ledger)).toMatchObject({
+ op: operation === "spawn" ? "spawn" : operation === "delete" ? "delete" : "rename",
+ child,
+ ...(operation === "spawn" ? { parent } : {}),
+ });
+ },
+ );
+
+ it.each(
+ ["missing", "retargeted"].flatMap((aliasState) =>
+ ["rename", "rename by path", "delete", "external rename", "external delete"].map((operation) => ({
+ aliasState,
+ operation,
+ })),
+ ),
+ )("replays $operation immediately after a cached $aliasState alias changes", async ({ aliasState, operation }) => {
+ vi.useFakeTimers({ toFake: ["Date"] });
+ const { root, sessionsDir, ledger } = fixture();
+ const parent = makeSession(root, sessionsDir, "parent");
+ const child = makeSession(root, join(root, "child"), "child", parent);
+ const alias = join(root, "child-alias.jsonl");
+ if (aliasState === "retargeted") {
+ const original = makeSession(root, join(root, "original"), "original", parent);
+ symlinkSync(original, alias, "file");
+ }
+ writeRecords(ledger, [spawn(parent, alias)]);
+ await ledger.liveEdges();
+ if (aliasState === "retargeted") rmSync(alias);
+ symlinkSync(child, alias, "file");
+ const deleted = operation.endsWith("delete");
+ if (operation.startsWith("external")) {
+ // Simulate another process appending without touching this reader's caches.
+ const record: RlmLedgerRecord = deleted
+ ? { v: 1, op: "delete", at: "deleted", childId: "sub-worker", child, reason: "user" }
+ : { v: 1, op: "rename", at: "renamed", childId: "sub-worker", child, name: "fresh" };
+ appendFileSync(ledger.ledgerPath, `${JSON.stringify(record)}\n`);
+ } else if (deleted) {
+ await ledger.appendDelete({ childId: "sub-worker", child: alias, reason: "user" });
+ } else if (operation === "rename by path") {
+ await ledger.appendRenameByChildPath(child, "fresh");
+ } else {
+ await ledger.appendRename({ childId: "sub-worker", child: alias, name: "fresh" });
+ }
+ const expected = [
+ {
+ childId: "sub-worker",
+ child: alias,
+ name: deleted ? "sub-worker" : "fresh",
+ ...(deleted ? { deleted: "user" } : {}),
+ },
+ ];
+ expect(await ledger.edges(true)).toMatchObject(expected);
+ vi.advanceTimersByTime(60_001);
+ expect(await ledger.edges(true)).toMatchObject(expected);
+ expect(await ledger.liveEdges()).toHaveLength(deleted ? 0 : 1);
+ const family = await ledger.family();
+ expect(family.map((row) => row.path)).toEqual(deleted ? [parent] : [parent, child]);
+ if (!deleted) expect(family[1].name).toBe("fresh");
+ });
+
+ it.each(["rename", "delete"])(
+ "keeps a recorded $operation applied after a restart under a retargeted alias",
+ async (operation) => {
+ const { root, sessionsDir, ledger } = fixture();
+ const parent = makeSession(root, sessionsDir, "parent");
+ const first = makeSession(root, join(root, "first"), "first", parent);
+ const second = makeSession(root, join(root, "second"), "second", parent);
+ const alias = join(root, "child-alias.jsonl");
+ // The spawn record stores the alias while it is missing; the update
+ // below records its then-canonical target once the symlink exists.
+ writeRecords(ledger, [spawn(parent, alias)]);
+ symlinkSync(first, alias, "file");
+ if (operation === "delete") {
+ await ledger.appendDelete({ childId: "sub-worker", child: alias, reason: "user" });
+ } else {
+ await ledger.appendRename({ childId: "sub-worker", child: alias, name: "fresh" });
+ }
+ const applied = [
+ { childId: "sub-worker", ...(operation === "delete" ? { deleted: "user" } : { name: "fresh" }) },
+ ];
+ expect(await ledger.edges(true)).toMatchObject(applied);
+
+ // Retarget the alias after the update was recorded: the historical
+ // target no longer canonicalizes to the spawn's stored alias. A fresh
+ // replay (restart) must not lose the update or resurrect the edge.
+ rmSync(alias);
+ symlinkSync(second, alias, "file");
+ const restarted = new RlmSpawnLedger(root, sessionsDir);
+ expect(await restarted.edges(true)).toMatchObject(applied);
+ expect(await restarted.edges()).toEqual(
+ operation === "delete" ? [] : [expect.objectContaining({ name: "fresh" })],
+ );
+ expect(await restarted.liveEdges()).toEqual(
+ operation === "delete" ? [] : [expect.objectContaining({ name: "fresh" })],
+ );
+ },
+ );
+
+ it("keeps a recorded delete applied after an unrelated append under a retargeted alias", async () => {
+ const { root, sessionsDir, ledger } = fixture();
+ const parent = makeSession(root, sessionsDir, "parent");
+ const first = makeSession(root, join(root, "first"), "first", parent);
+ const second = makeSession(root, join(root, "second"), "second", parent);
+ const third = makeSession(root, join(root, "third"), "third", parent);
+ const alias = join(root, "child-alias.jsonl");
+ writeRecords(ledger, [spawn(parent, alias)]);
+ symlinkSync(first, alias, "file");
+ await ledger.appendDelete({ childId: "sub-worker", child: alias, reason: "user" });
+ rmSync(alias);
+ symlinkSync(second, alias, "file");
+ // An unrelated append from another process forces a fresh replay of the
+ // same ledger instance under the retargeted filesystem.
+ appendFileSync(ledger.ledgerPath, `${JSON.stringify(spawn(parent, third, "sub-other"))}\n`);
+ expect(await ledger.edges()).toEqual([expect.objectContaining({ childId: "sub-other" })]);
+ expect(await ledger.edges(true)).toMatchObject([
+ { childId: "sub-worker", deleted: "user" },
+ { childId: "sub-other" },
+ ]);
+ });
+
+ it("checks duplicate spawn paths freshly even when the existing edge has a cached missing alias", async () => {
+ const { root, sessionsDir, ledger } = fixture();
+ const parent = makeSession(root, sessionsDir, "parent");
+ const child = makeSession(root, join(root, "child"), "child", parent);
+ const alias = join(root, "child-alias.jsonl");
+ writeRecords(ledger, [spawn(parent, alias)]);
+ await ledger.edges();
+ symlinkSync(child, alias, "file");
+ await expect(
+ ledger.appendSpawn({ childId: "sub-duplicate", parent, child, depth: 1, name: "duplicate" }),
+ ).rejects.toThrow("duplicate child session path");
+ expect(lastRecord(ledger)).toMatchObject({ childId: "sub-worker", child: alias });
+ });
+
+ it("seeds fresh parent, child, and visited identities after warming missing aliases", async () => {
+ const { root, sessionsDir, ledger } = fixture();
+ const parent = makeSession(root, join(root, "parent"), "parent");
+ const child = makeSession(root, join(root, "child"), "child", parent);
+ const parentAlias = join(sessionsDir, "parent-alias.jsonl");
+ const childAlias = join(root, "child-alias.jsonl");
+ await withPassiveRlmDescendantInfos([savedInfo(parentAlias), savedInfo(childAlias)], ledger);
+ symlinkSync(parent, parentAlias, "file");
+ symlinkSync(child, childAlias, "file");
+ const seeded = new RlmSpawnLedger(root, sessionsDir, {
+ readRegistryForSessionFile: async (path) =>
+ path === parentAlias
+ ? [
+ { childId: "sub-cycle", sessionName: "cycle", sessionFile: parent, status: "completed" },
+ { childId: "sub-seeded", sessionName: "seeded", sessionFile: childAlias, status: "completed" },
+ ]
+ : [],
+ });
+ expect(await seeded.edges()).toEqual([{ childId: "sub-seeded", parent, child, depth: 1, name: "seeded" }]);
+ });
+});
diff --git a/packages/coding-agent/test/session-reader-persistence.test.ts b/packages/coding-agent/test/session-reader-persistence.test.ts
index 51ff236e60..76813af92e 100644
--- a/packages/coding-agent/test/session-reader-persistence.test.ts
+++ b/packages/coding-agent/test/session-reader-persistence.test.ts
@@ -63,7 +63,7 @@ describe("session catalog cache and standalone export", () => {
it("evicts an oversized usage map while keeping returned totals correct", async () => {
const path = join(dir, "oversized.jsonl");
- const count = 100_001;
+ const count = 400_001;
const records = [line(header)];
for (let i = 0; i < count; i++)
records.push(
diff --git a/packages/coding-agent/test/session-scan-retention.test.ts b/packages/coding-agent/test/session-scan-retention.test.ts
new file mode 100644
index 0000000000..e8d1315731
--- /dev/null
+++ b/packages/coding-agent/test/session-scan-retention.test.ts
@@ -0,0 +1,134 @@
+import { appendFileSync, mkdirSync, mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { readSessionInfo, SessionManager } from "../src/core/session-manager.js";
+import * as fileLines from "../src/utils/file-lines.js";
+
+const timestamp = "2026-01-01T00:00:00Z";
+const usage = {
+ input: 1,
+ output: 2,
+ cacheRead: 0,
+ cacheWrite: 0,
+ totalTokens: 3,
+ cost: { input: 1, output: 2, cacheRead: 0, cacheWrite: 0, total: 3 },
+};
+
+function assistantLines(count: number, start = 0): string {
+ return Array.from({ length: count }, (_, offset) => {
+ const index = start + offset;
+ return `${JSON.stringify({
+ type: "message",
+ id: `m${index}`,
+ parentId: index === 0 ? null : `m${index - 1}`,
+ timestamp,
+ message: {
+ role: "assistant",
+ content: [{ type: "text", text: "reply" }],
+ api: "anthropic-messages",
+ provider: "anthropic",
+ model: "test",
+ stopReason: "stop",
+ timestamp: 1,
+ usage,
+ },
+ })}\n`;
+ }).join("");
+}
+
+function writeSession(dir: string, id: string, messages: string): string {
+ const path = join(dir, `${id}.jsonl`);
+ writeFileSync(path, `${JSON.stringify({ type: "session", version: 3, id, timestamp, cwd: dir, rlmDepth: 0 })}\n`);
+ appendFileSync(path, messages);
+ return path;
+}
+
+const expectedUsage = (count: number) => ({ inputTokens: count, outputTokens: count * 2, cost: count * 3 });
+
+describe("session scan retention", () => {
+ let dir: string;
+
+ beforeEach(() => {
+ dir = mkdtempSync(join(tmpdir(), "session-scan-retention-"));
+ });
+
+ afterEach(async () => {
+ rmSync(dir, { recursive: true, force: true });
+ await SessionManager.listAll(undefined, dir);
+ vi.restoreAllMocks();
+ });
+
+ it("keeps a 2,000-session catalog with 150,000 usage entries warm across repeated refreshes", async () => {
+ const messages = assistantLines(75);
+ for (let index = 0; index < 2_000; index++) {
+ writeSession(dir, `session-${index.toString().padStart(4, "0")}`, messages);
+ }
+ const reads = vi.spyOn(fileLines, "readLinesAsBuffers");
+ const cold = await SessionManager.listAll(undefined, dir);
+ expect(cold).toHaveLength(2_000);
+ expect(cold.every((session) => session.messageCount === 75)).toBe(true);
+ expect(cold[0]?.usage).toEqual(expectedUsage(75));
+ expect(reads).toHaveBeenCalledTimes(2_000);
+
+ reads.mockClear();
+ for (let pass = 0; pass < 3; pass++) {
+ expect(await SessionManager.listAll(undefined, dir)).toEqual(cold);
+ }
+ expect(reads, "unchanged catalog refreshes must not reopen transcripts").not.toHaveBeenCalled();
+ });
+
+ it("evicts the least recently used state when appended usage exceeds the retained bound", async () => {
+ const count = 100_000;
+ const messages = assistantLines(count);
+ const paths = ["a", "b", "c", "d"].map((id) => writeSession(dir, id, messages));
+ for (const path of paths) {
+ expect((await readSessionInfo(path))?.usage).toEqual(expectedUsage(count));
+ }
+ const [a, b, c, d] = paths;
+ const reads = vi.spyOn(fileLines, "readLinesAsBuffers");
+ await readSessionInfo(a);
+ expect(reads).not.toHaveBeenCalled();
+
+ const start = statSync(a).size;
+ appendFileSync(a, assistantLines(1, count));
+ const appended = await readSessionInfo(a);
+ expect(appended?.messageCount).toBe(count + 1);
+ expect(appended?.usage).toEqual(expectedUsage(count + 1));
+ expect(reads).toHaveBeenCalledExactlyOnceWith(a, { start, end: statSync(a).size - 1 });
+
+ reads.mockClear();
+ for (const path of [c, d, a]) await readSessionInfo(path);
+ expect(reads).not.toHaveBeenCalled();
+ expect((await readSessionInfo(b))?.usage).toEqual(expectedUsage(count));
+ expect(reads).toHaveBeenCalledExactlyOnceWith(b, { start: 0, end: statSync(b).size - 1 });
+ });
+
+ it.each(["missing read", "directory listing", "missing directory"])(
+ "releases usage entries after removal detected by %s",
+ async (mode) => {
+ const messages = assistantLines(100_000);
+ const survivor = writeSession(dir, "a", messages);
+ const others = ["b", "c"].map((id) => writeSession(dir, id, messages));
+ const removedDir = mode === "missing directory" ? join(dir, "removed") : dir;
+ mkdirSync(removedDir, { recursive: true });
+ const removed = writeSession(removedDir, "d", messages);
+ for (const path of [survivor, ...others, removed]) await readSessionInfo(path);
+
+ rmSync(mode === "missing directory" ? removedDir : removed, { recursive: true });
+ if (mode === "missing read") {
+ expect(await readSessionInfo(removed)).toBeNull();
+ } else if (mode === "missing directory") {
+ expect(await SessionManager.listAll(undefined, removedDir)).toEqual([]);
+ } else {
+ expect(await SessionManager.listAll(undefined, dir)).toHaveLength(3);
+ }
+
+ const replacement = writeSession(dir, "e", messages);
+ expect((await readSessionInfo(replacement))?.usage).toEqual(expectedUsage(100_000));
+ const reads = vi.spyOn(fileLines, "readLinesAsBuffers");
+ expect((await readSessionInfo(survivor))?.usage).toEqual(expectedUsage(100_000));
+ expect(reads, "removed states must not consume the surviving catalog's budget").not.toHaveBeenCalled();
+ },
+ );
+});