Skip to content

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

Rust

[RSI, performance] perf(daemon): mtime-guard the cron jobs catalog reads (#2389)

Seth Kartend2cdb4504e7e
diff --git a/packages/coding-agent/.changes/cron-catalog-mtime-snapshot.md b/packages/coding-agent/.changes/cron-catalog-mtime-snapshot.md
new file mode 100644
index 0000000000..d9bb88657b
--- /dev/null
+++ b/packages/coding-agent/.changes/cron-catalog-mtime-snapshot.md
@@ -0,0 +1 @@
+- Reduced daemon disk churn: the scheduled-jobs catalog now re-parses only when its file changes, instead of on every heartbeat and agents-view poll and two to three times per mutation.
diff --git a/packages/coding-agent/src/core/cron-jobs.ts b/packages/coding-agent/src/core/cron-jobs.ts
index 28fa49b139..6ceca4df86 100644
--- a/packages/coding-agent/src/core/cron-jobs.ts
+++ b/packages/coding-agent/src/core/cron-jobs.ts
@@ -1,5 +1,5 @@
import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { lockSync } from "proper-lockfile";
import { writeFileAtomicSync } from "../utils/atomic-file.js";
@@ -101,6 +101,19 @@ interface CronJobsState {
dispatches: AgentCronDispatchRecord[];
}
+/** Stat identity of a jobs file: every writer replaces the inode and bumps the mtime, so equality means a parse is still current. */
+interface CronJobsFileIdentity {
+ dev: number;
+ ino: number;
+ size: number;
+ mtimeMs: number;
+}
+
+interface CronJobsStateSnapshot {
+ identity: CronJobsFileIdentity;
+ state: CronJobsState;
+}
+
export const SESSION_SCHEDULED_JOBS_FILENAME = "scheduled-jobs.json";
const MAX_TIMEOUT_MS = 2_147_483_647;
@@ -161,6 +174,8 @@ function heartbeatCatalogSignature(jobs: readonly AgentCronJob[]): string {
export class AgentCronJobStore {
private readonly sessionArtifactFiles = new Map<string, string>();
private readonly heartbeatChangeListeners = new Set<() => void>();
+ /** Parsed-state snapshot per jobs file, keyed by path; the stat identity decides when a snapshot is still current. */
+ private readonly stateSnapshots = new Map<string, CronJobsStateSnapshot>();
constructor(
private readonly filePath?: string,
@@ -198,11 +213,11 @@ export class AgentCronJobStore {
return [];
}
return withCronJobsStateLocks([path], () => {
- const state = readJobsState(path);
+ const state = roundTripJobsState(this.readState(path));
const recovered: AgentCronJob[] = [];
if (state.dispatches.length > 0) {
recoverInterruptedInState(state, now, recovered);
- writeJobsState(path, state);
+ this.writeState(path, state);
}
return recovered;
});
@@ -779,15 +794,69 @@ export class AgentCronJobStore {
return times[0];
}
+ /**
+ * Read the parsed state, serving the in-memory snapshot while the file's stat
+ * identity is unchanged. Polls (agents view, scheduler) then cost one stat
+ * instead of a full read+parse; a changed identity falls back to the disk.
+ * The snapshot and every returned state are deeply frozen: callers get a
+ * read-only view, so an in-place edit of a listed job can reach neither the
+ * snapshot nor a later publish. Mutators clone before editing.
+ */
+ private readState(path: string): CronJobsState {
+ const identity = statJobsFileIdentity(path);
+ if (!identity) {
+ this.stateSnapshots.delete(path);
+ return EMPTY_JOBS_STATE;
+ }
+ const snapshot = this.stateSnapshots.get(path);
+ if (snapshot && isSameJobsFileIdentity(snapshot.identity, identity)) {
+ return snapshot.state;
+ }
+ const state = deepFreezeJobsState(readJobsState(path));
+ // A concurrent writer can replace the file during the read; cache only a parse bracketed by one file identity.
+ const after = statJobsFileIdentity(path);
+ if (after && isSameJobsFileIdentity(identity, after)) {
+ this.stateSnapshots.set(path, { identity: after, state });
+ } else {
+ this.stateSnapshots.delete(path);
+ }
+ return state;
+ }
+
+ /**
+ * Persist a state and publish it as the frozen snapshot for subsequent reads,
+ * so mutations do not re-read what they just wrote. Runs under the state lock,
+ * where conforming writers cannot replace the file between write and stat.
+ * The snapshot is published only when the post-write stat matches the identity
+ * this write produced; an external replacement landing between write and stat
+ * invalidates the snapshot instead of pairing its identity with stale state.
+ */
+ private writeState(path: string, state: CronJobsState): void {
+ let written: CronJobsFileIdentity | undefined;
+ try {
+ written = writeJobsState(path, state);
+ } catch (error) {
+ // An unpersisted state must not survive in the snapshot.
+ this.stateSnapshots.delete(path);
+ throw error;
+ }
+ const identity = statJobsFileIdentity(path);
+ if (identity && written && isSameJobsFileIdentity(written, identity)) {
+ this.stateSnapshots.set(path, { identity, state: deepFreezeJobsState(roundTripJobsState(state)) });
+ } else {
+ this.stateSnapshots.delete(path);
+ }
+ }
+
private readJobs(): AgentCronJob[] {
return this.readStates().flatMap((state) => state.jobs);
}
private readStates(): CronJobsState[] {
if (this.sessionArtifactMode) {
- return [...this.sessionArtifactFiles.values()].map((path) => readJobsState(path));
+ return [...this.sessionArtifactFiles.values()].map((path) => this.readState(path));
}
- return [readJobsState(this.requireFilePath())];
+ return [this.readState(this.requireFilePath())];
}
private mutateStates(mutator: (state: CronJobsState) => AgentCronDispatch[]): AgentCronDispatch[] {
@@ -797,11 +866,13 @@ export class AgentCronJobStore {
const dispatches = withCronJobsStateLocks(paths, () => {
const dispatches: AgentCronDispatch[] = [];
for (const path of paths) {
- const state = readJobsState(path);
+ // Mutators work on a private clone, so a mid-edit throw or a cached read
+ // never leaks into the published snapshot; the frozen view stays intact.
+ const state = roundTripJobsState(this.readState(path));
const before = JSON.stringify(state);
dispatches.push(...mutator(state));
if (JSON.stringify(state) !== before) {
- writeJobsState(path, state);
+ this.writeState(path, state);
changed = true;
}
}
@@ -824,7 +895,7 @@ export class AgentCronJobStore {
const paths = [...this.sessionArtifactFiles.values()];
withCronJobsStateLocks(paths, () => {
const currentBySessionId = new Map(
- [...this.sessionArtifactFiles].map(([sessionId, path]) => [sessionId, readJobsState(path)]),
+ [...this.sessionArtifactFiles].map(([sessionId, path]) => [sessionId, this.readState(path)]),
);
const incomingById = new Map(jobs.map((job) => [job.id, job]));
const mergedJobsBySessionId = new Map<string, AgentCronJob[]>();
@@ -854,7 +925,7 @@ export class AgentCronJobStore {
dispatches: dispatches.filter((dispatch) => sessionIdByJobId.get(dispatch.jobId) === sessionId),
};
if (JSON.stringify(current) !== JSON.stringify(nextState)) {
- writeJobsState(path, nextState);
+ this.writeState(path, nextState);
}
}
});
@@ -864,7 +935,13 @@ export class AgentCronJobStore {
return;
}
const path = this.requireFilePath();
- withCronJobsStateLocks([path], () => writeJobsFile(path, jobs, true));
+ withCronJobsStateLocks([path], () => {
+ const current = this.readState(path);
+ this.writeState(path, {
+ jobs: mergeFreshJobs(current.jobs, jobs),
+ dispatches: current.dispatches,
+ });
+ });
if (heartbeatCatalogSignature(this.readJobs()) !== previousHeartbeats) {
this.notifyHeartbeatChange();
}
@@ -1530,6 +1607,48 @@ function withCronJobsStateLocks<T>(paths: readonly string[], action: () => T): T
}
}
+/** Stat a jobs file for snapshot identity; a missing file has no identity and no snapshot. */
+function statJobsFileIdentity(path: string): CronJobsFileIdentity | undefined {
+ try {
+ const stats = statSync(path);
+ return { dev: stats.dev, ino: stats.ino, size: stats.size, mtimeMs: stats.mtimeMs };
+ } catch {
+ return undefined;
+ }
+}
+
+function isSameJobsFileIdentity(left: CronJobsFileIdentity, right: CronJobsFileIdentity): boolean {
+ return (
+ left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeMs === right.mtimeMs
+ );
+}
+
+/** The bytes just written parse back to this state; a published snapshot must equal a fresh read of them (undefined-valued keys that serialization drops do not reappear). */
+function roundTripJobsState(state: CronJobsState): CronJobsState {
+ return JSON.parse(JSON.stringify(state)) as CronJobsState;
+}
+
+/**
+ * Freeze a state graph (state, jobs, schedules, dispatches) in place so every
+ * read serves a read-only view: an in-place edit of a returned job throws
+ * instead of reaching the snapshot or a later publish.
+ */
+function deepFreezeJobsState(state: CronJobsState): CronJobsState {
+ for (const job of state.jobs) {
+ Object.freeze(job.schedule);
+ Object.freeze(job);
+ }
+ for (const dispatch of state.dispatches) {
+ Object.freeze(dispatch);
+ }
+ Object.freeze(state.jobs);
+ Object.freeze(state.dispatches);
+ return Object.freeze(state);
+}
+
+/** Served while a jobs file is missing; frozen like every other read view. */
+const EMPTY_JOBS_STATE = deepFreezeJobsState({ jobs: [], dispatches: [] });
+
function readJobsState(path: string): CronJobsState {
if (!existsSync(path)) {
return { jobs: [], dispatches: [] };
@@ -1549,9 +1668,23 @@ function writeJobsFile(path: string, jobs: readonly AgentCronJob[], mergeCurrent
});
}
-function writeJobsState(path: string, state: CronJobsState): void {
+/**
+ * Persist a state atomically and report the stat identity the written file
+ * carries after the rename (the temp file keeps dev/ino/size/mtime across it),
+ * so a caller can verify that a later stat still shows this write's file.
+ */
+function writeJobsState(path: string, state: CronJobsState): CronJobsFileIdentity | undefined {
mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
- writeFileAtomicSync(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600, fsync: true, fsyncDir: true });
+ let written: CronJobsFileIdentity | undefined;
+ writeFileAtomicSync(path, `${JSON.stringify(state, null, 2)}\n`, {
+ mode: 0o600,
+ fsync: true,
+ fsyncDir: true,
+ beforeRename: (tempPath) => {
+ written = statJobsFileIdentity(tempPath);
+ },
+ });
+ return written;
}
function claimDueInState(state: CronJobsState, dueAt: Date, claimedAt: Date): AgentCronDispatch[] {
diff --git a/packages/coding-agent/test/cron-jobs-state-snapshot.test.ts b/packages/coding-agent/test/cron-jobs-state-snapshot.test.ts
new file mode 100644
index 0000000000..928c1d7092
--- /dev/null
+++ b/packages/coding-agent/test/cron-jobs-state-snapshot.test.ts
@@ -0,0 +1,486 @@
+import type * as FsModule from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { type AgentCronJob, AgentCronJobStore, SESSION_SCHEDULED_JOBS_FILENAME } from "../src/core/cron-jobs.js";
+
+const readCounts = vi.hoisted(() => new Map<string, number>());
+const renameFault = vi.hoisted(() => ({ remaining: 0, path: "" }));
+const renameAfterHook = vi.hoisted(() => ({ after: undefined as (() => void) | undefined }));
+vi.mock("node:fs", async (importOriginal) => {
+ const actual = await importOriginal<typeof FsModule>();
+ return {
+ ...actual,
+ readFileSync: ((path, options) => {
+ const key = String(path);
+ readCounts.set(key, (readCounts.get(key) ?? 0) + 1);
+ return actual.readFileSync(path, options);
+ }) as typeof actual.readFileSync,
+ renameSync: ((from, to) => {
+ if (renameFault.remaining > 0 && String(to) === renameFault.path) {
+ renameFault.remaining--;
+ throw Object.assign(new Error("rename blocked"), { code: "EPERM" });
+ }
+ actual.renameSync(from, to);
+ // Fires after an atomic rename lands, so a test can emulate an external
+ // writer replacing the file before the store stats it again.
+ renameAfterHook.after?.();
+ }) as typeof actual.renameSync,
+ };
+});
+
+const start = new Date("2026-01-01T12:34:00.000Z");
+
+function jobsReads(path: string): number {
+ return readCounts.get(path) ?? 0;
+}
+
+/** Rewrite a jobs file the way an external writer would: whole-file replace with an explicit mtime. */
+function writeExternalState(path: string, jobs: readonly AgentCronJob[], mtime: Date): void {
+ writeFileSync(path, `${JSON.stringify({ jobs, dispatches: [] }, null, 2)}\n`);
+ utimesSync(path, mtime, mtime);
+}
+
+function externalJob(input: { id: string; prompt: string; sessionId: string; sessionFile: string }): AgentCronJob {
+ return {
+ id: input.id,
+ status: "active",
+ activeSessionId: `active-${input.sessionId}`,
+ sessionId: input.sessionId,
+ sessionFile: input.sessionFile,
+ cwd: "/tmp/project",
+ prompt: input.prompt,
+ schedule: { kind: "interval", expression: "every 5m", intervalMs: 300_000 },
+ createdAt: "2026-01-01T12:00:00.000Z",
+ updatedAt: "2026-01-01T12:00:00.000Z",
+ nextRunAt: "2026-01-01T12:40:00.000Z",
+ runCount: 0,
+ };
+}
+
+function makeTempDir(tempDirs: string[]): string {
+ const dir = mkdtempSync(join(tmpdir(), "prime-agent-cron-snapshot-"));
+ tempDirs.push(dir);
+ return dir;
+}
+
+describe("AgentCronJobStore state snapshots", () => {
+ const tempDirs: string[] = [];
+
+ afterEach(() => {
+ for (const dir of tempDirs.splice(0)) {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ readCounts.clear();
+ renameFault.remaining = 0;
+ renameFault.path = "";
+ renameAfterHook.after = undefined;
+ });
+
+ it("serves repeated reads of an unchanged file from the in-memory snapshot", () => {
+ const storePath = join(makeTempDir(tempDirs), "cron-jobs.json");
+ const store = new AgentCronJobStore(storePath);
+ store.create({
+ activeSessionId: "active-1",
+ sessionId: "session-1",
+ sessionFile: "/tmp/session-1.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 1h",
+ prompt: "snapshot guard",
+ now: start,
+ });
+ readCounts.clear();
+
+ expect(store.list()).toHaveLength(1);
+ expect(store.due(new Date("2026-01-01T13:35:00.000Z"))).toHaveLength(1);
+ expect(store.getDueJob(store.list()[0]!.id, new Date("2026-01-01T13:35:00.000Z"))).toBeDefined();
+ expect(store.nextActiveRunAt()?.toISOString()).toBe("2026-01-01T13:34:00.000Z");
+ expect(store.list()).toHaveLength(1);
+
+ expect(jobsReads(storePath)).toBe(0);
+ });
+
+ it("publishes the mutated state so the next read does not re-parse the file", () => {
+ const storePath = join(makeTempDir(tempDirs), "cron-jobs.json");
+ const store = new AgentCronJobStore(storePath);
+ const job = store.create({
+ activeSessionId: "active-1",
+ sessionId: "session-1",
+ sessionFile: "/tmp/session-1.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 1h",
+ prompt: "published mutation",
+ now: start,
+ });
+ readCounts.clear();
+
+ expect(store.list().map((candidate) => candidate.id)).toEqual([job.id]);
+ expect(store.getHeartbeat("active-1")).toBeUndefined();
+
+ expect(jobsReads(storePath)).toBe(0);
+ });
+
+ it("re-reads the file when an external writer changes it and caches the new parse", () => {
+ const storePath = join(makeTempDir(tempDirs), "cron-jobs.json");
+ const store = new AgentCronJobStore(storePath);
+ store.create({
+ activeSessionId: "active-1",
+ sessionId: "session-1",
+ sessionFile: "/tmp/session-1.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 1h",
+ prompt: "aaaa",
+ now: start,
+ });
+ // Same byte size, different content: only the mtime moves.
+ writeExternalState(
+ storePath,
+ [
+ externalJob({
+ id: "external-1",
+ prompt: "bbbb",
+ sessionId: "session-1",
+ sessionFile: "/tmp/session-1.jsonl",
+ }),
+ ],
+ new Date("2026-01-02T00:00:00.000Z"),
+ );
+ readCounts.clear();
+
+ expect(store.list().map((candidate) => candidate.prompt)).toEqual(["bbbb"]);
+ expect(jobsReads(storePath)).toBe(1);
+
+ expect(store.list().map((candidate) => candidate.prompt)).toEqual(["bbbb"]);
+ expect(jobsReads(storePath)).toBe(1);
+ });
+
+ it("re-reads when the file is replaced by a fresh inode with the same size and mtime", () => {
+ const storePath = join(makeTempDir(tempDirs), "cron-jobs.json");
+ const store = new AgentCronJobStore(storePath);
+ store.create({
+ activeSessionId: "active-1",
+ sessionId: "session-1",
+ sessionFile: "/tmp/session-1.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 1h",
+ prompt: "inode guard",
+ now: start,
+ });
+ const pinned = new Date("2026-01-03T00:00:00.000Z");
+ utimesSync(storePath, pinned, pinned);
+ expect(store.list()).toHaveLength(1);
+ const bytes = readFileSync(storePath, "utf-8");
+ readCounts.clear();
+
+ rmSync(storePath);
+ writeFileSync(storePath, bytes);
+ utimesSync(storePath, pinned, pinned);
+
+ expect(store.list()).toHaveLength(1);
+ expect(jobsReads(storePath)).toBe(1);
+ });
+
+ it("keeps concurrent store instances on one file consistent", () => {
+ const storePath = join(makeTempDir(tempDirs), "cron-jobs.json");
+ const first = new AgentCronJobStore(storePath);
+ const second = new AgentCronJobStore(storePath);
+ const jobA = first.create({
+ activeSessionId: "active-1",
+ sessionId: "session-1",
+ sessionFile: "/tmp/session-1.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 1h",
+ prompt: "from first",
+ now: start,
+ });
+ expect(second.list().map((candidate) => candidate.id)).toEqual([jobA.id]);
+
+ const jobB = second.create({
+ activeSessionId: "active-2",
+ sessionId: "session-2",
+ sessionFile: "/tmp/session-2.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 2h",
+ prompt: "from second",
+ now: start,
+ });
+ expect(
+ first
+ .list()
+ .map((candidate) => candidate.id)
+ .sort(),
+ ).toEqual([jobA.id, jobB.id].sort());
+
+ writeExternalState(storePath, [], new Date("2026-01-04T00:00:00.000Z"));
+ expect(first.list()).toEqual([]);
+ expect(second.list()).toEqual([]);
+
+ writeExternalState(
+ storePath,
+ [
+ externalJob({
+ id: "external-1",
+ prompt: "external writer",
+ sessionId: "session-1",
+ sessionFile: "/tmp/session-1.jsonl",
+ }),
+ ],
+ new Date("2026-01-05T00:00:00.000Z"),
+ );
+ expect(first.list().map((candidate) => candidate.id)).toEqual(["external-1"]);
+ expect(second.list().map((candidate) => candidate.id)).toEqual(["external-1"]);
+ });
+
+ it("drops the snapshot when a mutation fails to persist and re-reads the disk", () => {
+ const storePath = join(makeTempDir(tempDirs), "cron-jobs.json");
+ const store = new AgentCronJobStore(storePath);
+ const first = store.create({
+ activeSessionId: "active-1",
+ sessionId: "session-1",
+ sessionFile: "/tmp/session-1.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 1h",
+ prompt: "survives",
+ now: start,
+ });
+ readCounts.clear();
+ expect(store.list().map((candidate) => candidate.id)).toEqual([first.id]);
+ expect(jobsReads(storePath)).toBe(0);
+
+ renameFault.remaining = 1;
+ renameFault.path = storePath;
+ expect(() =>
+ store.create({
+ activeSessionId: "active-2",
+ sessionId: "session-2",
+ sessionFile: "/tmp/session-2.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 1h",
+ prompt: "never lands",
+ now: start,
+ }),
+ ).toThrow();
+
+ readCounts.clear();
+ expect(store.list().map((candidate) => candidate.id)).toEqual([first.id]);
+ expect(jobsReads(storePath)).toBe(1);
+ });
+
+ it("serves an empty state while the file is missing and reloads it when it appears", () => {
+ const storePath = join(makeTempDir(tempDirs), "cron-jobs.json");
+ const store = new AgentCronJobStore(storePath);
+ expect(store.list()).toEqual([]);
+ writeExternalState(
+ storePath,
+ [
+ externalJob({
+ id: "external-1",
+ prompt: "appears later",
+ sessionId: "session-1",
+ sessionFile: "/tmp/session-1.jsonl",
+ }),
+ ],
+ new Date("2026-01-06T00:00:00.000Z"),
+ );
+ expect(store.list().map((candidate) => candidate.id)).toEqual(["external-1"]);
+ readCounts.clear();
+ expect(store.list()).toHaveLength(1);
+ expect(jobsReads(storePath)).toBe(0);
+ });
+
+ it("caches per registered session artifact and re-reads only the changed file", () => {
+ const root = makeTempDir(tempDirs);
+ const store = AgentCronJobStore.forSessionArtifacts();
+ const firstDir = join(root, "artifacts-1");
+ const secondDir = join(root, "artifacts-2");
+ store.registerSessionArtifact("session-1", firstDir);
+ store.registerSessionArtifact("session-2", secondDir);
+ store.createHeartbeat({
+ activeSessionId: "active-1",
+ sessionId: "session-1",
+ sessionFile: join(root, "session-1.jsonl"),
+ cwd: root,
+ scheduleText: "every 5m",
+ prompt: "first heartbeat",
+ now: start,
+ });
+ store.createHeartbeat({
+ activeSessionId: "active-2",
+ sessionId: "session-2",
+ sessionFile: join(root, "session-2.jsonl"),
+ cwd: root,
+ scheduleText: "every 5m",
+ prompt: "second heartbeat",
+ now: start,
+ });
+ const firstPath = join(firstDir, SESSION_SCHEDULED_JOBS_FILENAME);
+ const secondPath = join(secondDir, SESSION_SCHEDULED_JOBS_FILENAME);
+ readCounts.clear();
+
+ expect(store.list()).toHaveLength(2);
+ expect(jobsReads(firstPath)).toBe(0);
+ expect(jobsReads(secondPath)).toBe(0);
+
+ writeExternalState(
+ firstPath,
+ [
+ externalJob({
+ id: "external-1",
+ prompt: "rewritten externally",
+ sessionId: "session-1",
+ sessionFile: join(root, "session-1.jsonl"),
+ }),
+ ],
+ new Date("2026-01-07T00:00:00.000Z"),
+ );
+ expect(store.list().map((candidate) => candidate.prompt)).toEqual(
+ expect.arrayContaining(["rewritten externally", "second heartbeat"]),
+ );
+ expect(jobsReads(firstPath)).toBe(1);
+ expect(jobsReads(secondPath)).toBe(0);
+ });
+
+ it("serves read-only views: an in-place edit of a listed job cannot change store behavior or reach disk", () => {
+ const storePath = join(makeTempDir(tempDirs), "cron-jobs.json");
+ const store = new AgentCronJobStore(storePath);
+ const job = store.create({
+ activeSessionId: "active-1",
+ sessionId: "session-1",
+ sessionFile: "/tmp/session-1.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 1h",
+ prompt: "read-only view",
+ now: start,
+ });
+ readCounts.clear();
+
+ const listed = store.list();
+ const dueJob = store.getDueJob(job.id, new Date("2026-01-01T13:35:00.000Z"));
+ expect(listed).toHaveLength(1);
+ expect(dueJob).toBeDefined();
+ expect(Object.isFrozen(listed[0])).toBe(true);
+ expect(Object.isFrozen(dueJob)).toBe(true);
+
+ expect(() => setStatus(listed[0], "cancelled")).toThrow(TypeError);
+ expect(() => setStatus(dueJob, "cancelled")).toThrow(TypeError);
+
+ expect(store.list()[0]?.status).toBe("active");
+ expect(jobsReads(storePath)).toBe(0);
+
+ // An unrelated mutation must persist the true state, not a leaked in-place edit.
+ store.create({
+ activeSessionId: "active-2",
+ sessionId: "session-2",
+ sessionFile: "/tmp/session-2.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 1h",
+ prompt: "unrelated mutation",
+ now: start,
+ });
+ const persisted = JSON.parse(readFileSync(storePath, "utf-8")) as { jobs: AgentCronJob[] };
+ expect(persisted.jobs.find((candidate) => candidate.id === job.id)?.status).toBe("active");
+ expect(store.list()).toHaveLength(2);
+ });
+
+ it("keeps the published snapshot intact when a mutator throws mid-edit", () => {
+ const storePath = join(makeTempDir(tempDirs), "cron-jobs.json");
+ const store = new AgentCronJobStore(storePath);
+ const job = store.create({
+ activeSessionId: "active-1",
+ sessionId: "session-1",
+ sessionFile: "/tmp/session-1.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 1h",
+ prompt: "survives the mutator crash",
+ now: start,
+ });
+ readCounts.clear();
+
+ expect(() =>
+ (
+ store as unknown as { mutateStates: (mutator: (state: MutableJobsState) => unknown[]) => unknown[] }
+ ).mutateStates((state) => {
+ state.jobs = state.jobs.map((candidate) => ({ ...candidate, status: "cancelled" as const }));
+ throw new Error("mutator crashed mid-edit");
+ }),
+ ).toThrow("mutator crashed mid-edit");
+
+ // The unpersisted partial edit never reaches reads...
+ expect(store.list().map((candidate) => candidate.status)).toEqual(["active"]);
+ expect(jobsReads(storePath)).toBe(0);
+ // ...nor does a later unrelated mutation resurrect it.
+ store.create({
+ activeSessionId: "active-2",
+ sessionId: "session-2",
+ sessionFile: "/tmp/session-2.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 1h",
+ prompt: "after the crash",
+ now: start,
+ });
+ const persisted = JSON.parse(readFileSync(storePath, "utf-8")) as { jobs: AgentCronJob[] };
+ expect(persisted.jobs.find((candidate) => candidate.id === job.id)?.status).toBe("active");
+ expect(store.list().map((candidate) => candidate.status)).toEqual(["active", "active"]);
+ });
+
+ it("re-reads instead of caching an external replacement that lands right after our own write", () => {
+ const storePath = join(makeTempDir(tempDirs), "cron-jobs.json");
+ const store = new AgentCronJobStore(storePath);
+ store.create({
+ activeSessionId: "active-1",
+ sessionId: "session-1",
+ sessionFile: "/tmp/session-1.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 1h",
+ prompt: "our job",
+ now: start,
+ });
+ readCounts.clear();
+ // An external writer replaces the file the instant our atomic rename lands:
+ // the post-write stat must not pair the external identity with our state.
+ renameAfterHook.after = () => {
+ renameAfterHook.after = undefined;
+ writeExternalState(
+ storePath,
+ [
+ externalJob({
+ id: "external-raced",
+ prompt: "external wins",
+ sessionId: "session-1",
+ sessionFile: "/tmp/session-1.jsonl",
+ }),
+ ],
+ new Date("2026-01-08T00:00:00.000Z"),
+ );
+ };
+ store.create({
+ activeSessionId: "active-2",
+ sessionId: "session-2",
+ sessionFile: "/tmp/session-2.jsonl",
+ cwd: "/tmp/project",
+ scheduleText: "in 1h",
+ prompt: "raced write",
+ now: start,
+ });
+
+ expect(store.list().map((candidate) => candidate.id)).toEqual(["external-raced"]);
+ expect(jobsReads(storePath)).toBe(1);
+ expect(store.list().map((candidate) => candidate.id)).toEqual(["external-raced"]);
+ expect(jobsReads(storePath)).toBe(1);
+
+ // A later mutation must operate on the external state, not our stale write.
+ const cancelled = store.cancel("external-raced");
+ expect(cancelled?.status).toBe("cancelled");
+ expect(store.list()[0]?.status).toBe("cancelled");
+ });
+});
+
+function setStatus(target: unknown, status: string): void {
+ (target as { status: string }).status = status;
+}
+
+interface MutableJobsState {
+ jobs: AgentCronJob[];
+ dispatches: Array<{ id: string; jobId: string; claimedAt: string; scheduledFor: string }>;
+}