Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

fix(daemon): bound context timeline storage

Gusa279fe082db6
diff --git a/src/daemon/src/daemon/createDaemon.test.ts b/src/daemon/src/daemon/createDaemon.test.ts
index 2856a1e6b..74206b314 100644
--- a/src/daemon/src/daemon/createDaemon.test.ts
+++ b/src/daemon/src/daemon/createDaemon.test.ts
@@ -13,6 +13,40 @@ import {
import type { Driver } from "../types";
import type { Logger } from "../logger";
+const timelineSweepHarness = vi.hoisted(() => {
+ let implementation: (workingDirectoryBase: string) => Promise<unknown> =
+ () => new Promise(() => {});
+ const calls: string[] = [];
+ return {
+ calls,
+ run: (workingDirectoryBase: string) => {
+ calls.push(workingDirectoryBase);
+ return implementation(workingDirectoryBase);
+ },
+ setImplementation: (next: (workingDirectoryBase: string) => Promise<unknown>) => {
+ implementation = next;
+ },
+ reset: () => {
+ calls.splice(0);
+ implementation = () => new Promise(() => {});
+ },
+ };
+});
+
+vi.mock("../timeline/index.js", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("../timeline/index.js")>();
+ return {
+ ...actual,
+ sweepTimelineHistory: (workingDirectoryBase: string) => timelineSweepHarness.run(workingDirectoryBase),
+ };
+});
+
+const startupSweepDirs: string[] = [];
+afterEach(() => {
+ timelineSweepHarness.reset();
+ for (const dir of startupSweepDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
/** Stub logger — records calls per level, and hands out tagged children that report into the same store. */
function stubLogger(): Logger & { calls: Record<"debug" | "info" | "warn" | "error", Array<[string, string, unknown[]]>> } {
const calls: Record<"debug" | "info" | "warn" | "error", Array<[string, string, unknown[]]>> = {
@@ -161,6 +195,64 @@ describe("createDaemon", () => {
expect(daemon.proxyUrl).toMatch(/^http:\/\/127\.0\.0\.1:\d+/);
await daemon.stop();
});
+
+ it("starts the timeline sweep immediately without awaiting its completion", async () => {
+ const sockets: FakeSocket[] = [];
+ const workingDirectoryBase = mkdtempSync(join(tmpdir(), "timeline-startup-"));
+ startupSweepDirs.push(workingDirectoryBase);
+ let resolveSweep!: () => void;
+ timelineSweepHarness.setImplementation(() => new Promise<void>((resolve) => { resolveSweep = resolve; }));
+
+ const daemonPromise = createDaemon({
+ machineKey: "cmk_sweep",
+ serverUrl: "http://localhost:9999",
+ serverWsUrl: "ws://x",
+ webSocketFactory: factory(sockets) as any,
+ runtimeReport: [],
+ driverFor: () => fakeDriver,
+ capabilities: [],
+ workingDirectoryBase,
+ });
+
+ expect(timelineSweepHarness.calls).toEqual([workingDirectoryBase]);
+ const daemon = await daemonPromise;
+ expect(timelineSweepHarness.calls).toEqual([workingDirectoryBase]);
+ resolveSweep();
+ await daemon.stop();
+ });
+
+ it("observes a rejected timeline sweep with one static safe warning and still becomes ready", async () => {
+ const sockets: FakeSocket[] = [];
+ const workingDirectoryBase = mkdtempSync(join(tmpdir(), "timeline-startup-"));
+ startupSweepDirs.push(workingDirectoryBase);
+ const logger = stubLogger();
+ timelineSweepHarness.setImplementation(() => Promise.reject(
+ new Error(`private failure at ${workingDirectoryBase}/agent-secret`),
+ ));
+
+ const daemon = await createDaemon({
+ machineKey: "cmk_sweep_reject",
+ serverUrl: "http://localhost:9999",
+ serverWsUrl: "ws://x",
+ webSocketFactory: factory(sockets) as any,
+ runtimeReport: [],
+ driverFor: () => fakeDriver,
+ capabilities: [],
+ workingDirectoryBase,
+ logger,
+ });
+ await vi.waitFor(() => {
+ expect(logger.calls.warn.filter(([, message]) => message === "timeline startup sweep failed")).toHaveLength(1);
+ });
+ const warning = logger.calls.warn.find(([, message]) => message === "timeline startup sweep failed");
+ expect(warning).toEqual(["root", "timeline startup sweep failed", []]);
+ expect(JSON.stringify(warning)).not.toContain(workingDirectoryBase);
+ expect(JSON.stringify(warning)).not.toContain("private failure");
+
+ sockets[0].emit("open");
+ expect(sockets[0].sent.map((frame) => JSON.parse(frame)).some((frame) => frame.type === "ready")).toBe(true);
+ await daemon.stop();
+ });
});
describe("createDaemon — opt-in raw runtime trace (P0-1)", () => {
diff --git a/src/daemon/src/daemon/createDaemon.ts b/src/daemon/src/daemon/createDaemon.ts
index f250b94cc..ea5de1e26 100644
--- a/src/daemon/src/daemon/createDaemon.ts
+++ b/src/daemon/src/daemon/createDaemon.ts
@@ -32,7 +32,7 @@ import { CredentialBroker, startCredentialProxy } from "../credentials/index.js"
import { AgentProcessManager, AgentRouter, createTypingScopeTracker } from "../manager/index.js";
import type { TypingScopeTracker } from "../manager/index.js";
import { UnknownBotError, BotEnrollFailedError, UnknownRuntimeError } from "../manager/agentRouter.js";
-import { createTimelineRecorder } from "../timeline/index.js";
+import { createTimelineRecorder, sweepTimelineHistory } from "../timeline/index.js";
import { resolveAlookCliPathWithFallback } from "../discovery.js";
import { createPiSdkDriverDeps } from "../drivers/piSdkDeps.js";
import { createLogger, type Logger } from "../logger.js";
@@ -321,7 +321,11 @@ export interface RunningDaemon {
export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDaemon> {
const log = opts.logger ?? createLogger({ header: "@alook/daemon" });
const fallbackBase = (process.env.ALOOK_PROJECT_ROOT || `${homedir()}/.alook`) + "/daemon";
- const workdirFor = (agentId: string) => `${opts.workingDirectoryBase ?? fallbackBase}/${agentId}`;
+ const workingDirectoryBase = opts.workingDirectoryBase ?? fallbackBase;
+ const workdirFor = (agentId: string) => `${workingDirectoryBase}/${agentId}`;
+ void sweepTimelineHistory(workingDirectoryBase).catch(() => {
+ log.warn("timeline startup sweep failed");
+ });
// Self-healing: resolve CLI path with fallback if primary is missing
const resolvedCliPath = resolveAlookCliPathWithFallback(opts.agentCliPath);
diff --git a/src/daemon/src/timeline/recorder.test.ts b/src/daemon/src/timeline/recorder.test.ts
index 9420c6e8d..243d6c19b 100644
--- a/src/daemon/src/timeline/recorder.test.ts
+++ b/src/daemon/src/timeline/recorder.test.ts
@@ -3,12 +3,13 @@ import * as fs from "fs";
import * as os from "os";
import * as path from "path";
import { createTimelineRecorder } from "./recorder";
-import { readRecentEntries } from "./timeline";
+import { createTimelineEntry, filenameForDate, readRecentEntries } from "./timeline";
+import { acquireLock, lockPathFor, releaseLock } from "./filelock";
import type { Message } from "../server/contract";
const tmpDirs: string[] = [];
function mkDir(): string {
- const d = fs.mkdtempSync(path.join(os.tmpdir(), "recorder-"));
+ const d = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), "recorder-"));
tmpDirs.push(d);
return d;
}
@@ -211,6 +212,98 @@ describe("appendResponseToLatest — text-before-first-pull fallback", () => {
expect(rows[0].agent_responses).toEqual(["hello"]);
expect(rows[0].messages).toEqual([]);
});
+
+ it("keeps only the latest five normal responses in FIFO order", () => {
+ const dir = mkDir();
+ const rec = createTimelineRecorder({ timelineDirFor: () => dir, providerFor: () => "claude", now: NOW });
+ rec.appendEntryForAgent("a", [msg("#1", "hello")]);
+ for (let index = 1; index <= 6; index++) rec.appendResponseToLatest("a", `r${index}`);
+ expect(readRecentEntries(dir, { now: NOW() })[0].agent_responses).toEqual(["r2", "r3", "r4", "r5", "r6"]);
+ });
+
+ it("keeps only the latest five text-before-first-pull fallback responses", () => {
+ const dir = mkDir();
+ const rec = createTimelineRecorder({ timelineDirFor: () => dir, providerFor: () => "claude", now: NOW });
+ rec.setSession("a", "sess-1");
+ for (let index = 1; index <= 6; index++) rec.appendResponseToLatest("a", `r${index}`);
+ const rows = readRecentEntries(dir, { now: NOW() });
+ expect(rows).toHaveLength(1);
+ expect(rows[0].agent_responses).toEqual(["r2", "r3", "r4", "r5", "r6"]);
+ });
+
+ it("does not create a fallback row when the latest-day lock is busy", () => {
+ const dir = mkDir();
+ const rec = createTimelineRecorder({ timelineDirFor: () => dir, providerFor: () => "claude", now: NOW });
+ rec.appendEntryForAgent("a", [msg("#1", "hello")]);
+ const filename = filenameForDate(NOW());
+ const file = path.join(dir, filename);
+ const before = fs.readFileSync(file);
+ const lock = lockPathFor(dir, filename);
+ expect(acquireLock(lock)).toBe(true);
+ try {
+ rec.appendResponseToLatest("a", "must not fall back");
+ } finally {
+ releaseLock(lock);
+ }
+
+ expect(fs.readFileSync(file)).toEqual(before);
+ expect(readRecentEntries(dir, { now: NOW() })).toHaveLength(1);
+ expect(readRecentEntries(dir, { now: NOW() })[0].agent_responses).toEqual([]);
+ });
+});
+
+describe("recorder timeline directory safety", () => {
+ it("does not create an outside timeline through an agent-directory symlink", () => {
+ if (process.platform === "win32") return;
+ const base = mkDir();
+ const outsideAgent = mkDir();
+ const agentLink = path.join(base, "agent-link");
+ fs.symlinkSync(outsideAgent, agentLink);
+ const linkedTimeline = path.join(agentLink, ".context_timeline");
+ const rec = createTimelineRecorder({
+ timelineDirFor: () => linkedTimeline,
+ providerFor: () => "claude",
+ now: NOW,
+ });
+
+ rec.setSession("a", "outside-session");
+ rec.appendEntryForAgent("a", [msg("#1", "blocked")]);
+ rec.appendResponseToLatest("a", "blocked");
+ rec.forgetSession("a");
+
+ expect(fs.readdirSync(outsideAgent)).toEqual([]);
+ });
+
+ it("does not read or modify an existing outside timeline through an agent-directory symlink", () => {
+ if (process.platform === "win32") return;
+ const base = mkDir();
+ const outsideAgent = mkDir();
+ const outsideTimeline = path.join(outsideAgent, ".context_timeline");
+ fs.mkdirSync(outsideTimeline);
+ const file = path.join(outsideTimeline, filenameForDate(NOW()));
+ fs.writeFileSync(file, `${JSON.stringify(createTimelineEntry({
+ messages: [msg("#1", "outside")],
+ sessionId: "outside-session",
+ provider: "claude",
+ }))}\n`);
+ const before = fs.readFileSync(file);
+ const agentLink = path.join(base, "agent-link");
+ fs.symlinkSync(outsideAgent, agentLink);
+ const linkedTimeline = path.join(agentLink, ".context_timeline");
+ const rec = createTimelineRecorder({
+ timelineDirFor: () => linkedTimeline,
+ providerFor: () => "claude",
+ now: NOW,
+ });
+
+ expect(rec.resumeSessionId("a", "claude")).toBeNull();
+ rec.appendEntryForAgent("a", [msg("#1", "blocked")]);
+ rec.appendResponseToLatest("a", "blocked");
+ rec.forgetSession("a");
+
+ expect(fs.readdirSync(outsideTimeline)).toEqual([filenameForDate(NOW())]);
+ expect(fs.readFileSync(file)).toEqual(before);
+ });
});
describe("resumeSessionId honors the reset_session barrier", () => {
diff --git a/src/daemon/src/timeline/recorder.ts b/src/daemon/src/timeline/recorder.ts
index 42d37dbaf..fc6405bc1 100644
--- a/src/daemon/src/timeline/recorder.ts
+++ b/src/daemon/src/timeline/recorder.ts
@@ -20,19 +20,27 @@
* Final schema (gustavo): an entry is exactly `{session_id, messages,
* agent_responses, provider}` — no task id / datetime / status / pid.
*/
-import { mkdirSync } from "fs";
import {
appendOrMergeEntry,
- updateLatestEntry,
+ updateLatestEntryResult,
readRecentEntries,
createTimelineEntry,
createSystemEntry,
findResumableSession,
appendEntry,
+ prepareTimelineDirectory,
} from "./timeline.js";
import type { Message } from "../server/contract.js";
import type { SystemEntryType } from "./types.js";
+const MAX_AGENT_RESPONSES = 5;
+
+function appendAgentResponse(entry: { agent_responses: string[] }, text: string): void {
+ entry.agent_responses.push(text);
+ if (entry.agent_responses.length > MAX_AGENT_RESPONSES) {
+ entry.agent_responses.splice(0, entry.agent_responses.length - MAX_AGENT_RESPONSES);
+ }
+}
/** Manager/daemon-facing recorder interface (structural, avoids a cyclic import). */
export interface TimelineRecorderLike {
@@ -78,11 +86,7 @@ export function createTimelineRecorder(opts: TimelineRecorderOptions): TimelineR
},
appendEntryForAgent(agentId, messages) {
const dir = dirFor(agentId);
- try {
- mkdirSync(dir, { recursive: true });
- } catch {
- /* best-effort; appendEntry no-ops on a missing dir */
- }
+ if (!prepareTimelineDirectory(dir)) return;
appendOrMergeEntry(
dir,
createTimelineEntry({
@@ -95,8 +99,9 @@ export function createTimelineRecorder(opts: TimelineRecorderOptions): TimelineR
},
appendResponseToLatest(agentId, text) {
const dir = dirFor(agentId);
- const updated = updateLatestEntry(dir, (e) => e.agent_responses.push(text), { now: now() });
- if (updated) return;
+ if (!prepareTimelineDirectory(dir)) return;
+ const result = updateLatestEntryResult(dir, (entry) => appendAgentResponse(entry, text), { now: now() });
+ if (result === "updated" || result === "rejected") return;
// No turn row exists yet (or the newest row is a system barrier) — open
// a fresh, empty-messages turn row carrying the current session/provider
// and stamp this response onto it. Happens whenever a `text` event
@@ -105,17 +110,12 @@ export function createTimelineRecorder(opts: TimelineRecorderOptions): TimelineR
// line and the rewake prompt makes the agent talk before pulling. A
// later inbox pull with real messages appends its own row (since this
// one already has a response, `appendOrMergeEntry` won't merge into it).
- try {
- mkdirSync(dir, { recursive: true });
- } catch {
- /* best-effort */
- }
const entry = createTimelineEntry({
messages: [],
sessionId: sessionByAgent.get(agentId) ?? null,
provider: opts.providerFor?.(agentId) ?? null,
});
- entry.agent_responses.push(text);
+ appendAgentResponse(entry, text);
appendEntry(dir, entry, now());
},
resumeSessionId(agentId, provider) {
@@ -124,17 +124,13 @@ export function createTimelineRecorder(opts: TimelineRecorderOptions): TimelineR
},
forgetSession(agentId, barrierType = "reset_session") {
const dir = dirFor(agentId);
- try {
- mkdirSync(dir, { recursive: true });
- } catch {
- /* best-effort — appendEntry handles a missing dir by returning false */
- }
// Kill happens BEFORE this call (see `AgentProcessManager.resetSession`),
// so no race — clear the in-memory session map and append the barrier.
// One `now()` sample so the system-row `time` and the day-file the row
// is written into can't disagree on the boundary between two consecutive
// clock reads.
sessionByAgent.delete(agentId);
+ if (!prepareTimelineDirectory(dir)) return;
const stamp = now();
appendEntry(dir, createSystemEntry(barrierType, stamp.toISOString()), stamp);
},
diff --git a/src/daemon/src/timeline/timeline.test.ts b/src/daemon/src/timeline/timeline.test.ts
index c2e96019a..199c444b8 100644
--- a/src/daemon/src/timeline/timeline.test.ts
+++ b/src/daemon/src/timeline/timeline.test.ts
@@ -6,18 +6,22 @@ import {
appendEntry,
appendOrMergeEntry,
updateLatestEntry,
+ updateLatestEntryResult,
readRecentEntries,
createTimelineEntry,
createSystemEntry,
findResumableSession,
filenameForDate,
localISOString,
+ sweepTimelineHistory,
+ TIMELINE_MAX_BYTES,
} from "./timeline";
+import { acquireLock, lockPathFor, releaseLock } from "./filelock";
import type { Message } from "../server/contract";
const tmpDirs: string[] = [];
function mkDir(): string {
- const d = fs.mkdtempSync(path.join(os.tmpdir(), "timeline-"));
+ const d = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), "timeline-"));
tmpDirs.push(d);
return d;
}
@@ -34,6 +38,27 @@ const msg = (text: string): Message => ({
time: "2026-06-25T12:00:00+00:00",
});
+function entryWithPayloadBytes(payloadBytes: number, sessionId: string | null = "s1", provider = "claude") {
+ return createTimelineEntry({ messages: [msg("x".repeat(payloadBytes))], sessionId, provider });
+}
+
+function entryAtExactBytes(bytes: number) {
+ const empty = entryWithPayloadBytes(0);
+ const overhead = Buffer.byteLength(JSON.stringify(empty), "utf8") + 1;
+ return entryWithPayloadBytes(bytes - overhead);
+}
+
+function entryAtExactBytesWithMultibyte(bytes: number) {
+ const multibyte = "界".repeat(64);
+ const base = createTimelineEntry({ messages: [msg(multibyte)], sessionId: "utf8", provider: "claude" });
+ const baseBytes = Buffer.byteLength(JSON.stringify(base), "utf8") + 1;
+ return createTimelineEntry({
+ messages: [msg(multibyte + "x".repeat(bytes - baseBytes))],
+ sessionId: "utf8",
+ provider: "claude",
+ });
+}
+
describe("timeline append / read (4-field schema)", () => {
it("appends entries and reads them back in append (time) order", () => {
const dir = mkDir();
@@ -81,6 +106,38 @@ describe("appendOrMergeEntry", () => {
appendOrMergeEntry(dir, createTimelineEntry({ messages: [msg("b")], sessionId: "s2", provider: "claude" }), NOW);
expect(readRecentEntries(dir, { now: NOW })).toHaveLength(2);
});
+
+ it("rejects an over-cap merge and leaves the source bytes unchanged", () => {
+ const dir = mkDir();
+ const original = createTimelineEntry({ messages: [msg("original")], sessionId: "s1", provider: "claude" });
+ expect(appendOrMergeEntry(dir, original, NOW)).toBe(true);
+ const file = path.join(dir, filenameForDate(NOW));
+ const before = fs.readFileSync(file);
+ const oversized = createTimelineEntry({
+ messages: [msg("界".repeat(TIMELINE_MAX_BYTES))],
+ sessionId: "s1",
+ provider: "claude",
+ });
+
+ expect(appendOrMergeEntry(dir, oversized, NOW)).toBe(false);
+ expect(fs.readFileSync(file)).toEqual(before);
+ });
+
+ it("converges an oversized historical file after a successful merge", () => {
+ const dir = mkDir();
+ const file = path.join(dir, filenameForDate(NOW));
+ const rows = Array.from({ length: 5 }, (_, index) =>
+ entryWithPayloadBytes(240_000, index === 4 ? "merge" : `s${index}`));
+ fs.writeFileSync(file, rows.map((row) => JSON.stringify(row)).join("\n") + "\n");
+
+ expect(appendOrMergeEntry(
+ dir,
+ createTimelineEntry({ messages: [msg("merged")], sessionId: "merge", provider: "claude" }),
+ NOW,
+ )).toBe(true);
+ expect(fs.statSync(file).size).toBeLessThanOrEqual(TIMELINE_MAX_BYTES);
+ expect(readRecentEntries(dir, { now: NOW }).at(-1)?.messages.at(-1)?.content.text).toBe("merged");
+ });
});
describe("updateLatestEntry", () => {
@@ -120,6 +177,372 @@ describe("updateLatestEntry", () => {
appendEntry(dir, createSystemEntry("reset_session", "2026-06-25T12:00:00Z"), NOW);
expect(updateLatestEntry(dir, () => {}, { now: NOW })).toBe(false);
});
+
+ it("rejects an over-cap update and leaves the source bytes unchanged", () => {
+ const dir = mkDir();
+ expect(appendEntry(dir, createTimelineEntry({ messages: [msg("original")] }), NOW)).toBe(true);
+ const file = path.join(dir, filenameForDate(NOW));
+ const before = fs.readFileSync(file);
+
+ expect(updateLatestEntry(
+ dir,
+ (entry) => entry.agent_responses.push("界".repeat(TIMELINE_MAX_BYTES)),
+ { now: NOW },
+ )).toBe(false);
+ expect(fs.readFileSync(file)).toEqual(before);
+ });
+
+ it("does not fall back to an older day after the latest-day update is rejected", () => {
+ const dir = mkDir();
+ const yesterday = new Date(NOW);
+ yesterday.setDate(yesterday.getDate() - 1);
+ expect(appendEntry(dir, createTimelineEntry({ messages: [msg("yesterday")] }), yesterday)).toBe(true);
+ expect(appendEntry(dir, createTimelineEntry({ messages: [msg("today")] }), NOW)).toBe(true);
+ const yesterdayFile = path.join(dir, filenameForDate(yesterday));
+ const todayFile = path.join(dir, filenameForDate(NOW));
+ const beforeYesterday = fs.readFileSync(yesterdayFile);
+ const beforeToday = fs.readFileSync(todayFile);
+ let updateCalls = 0;
+
+ expect(updateLatestEntry(dir, (entry) => {
+ updateCalls++;
+ entry.agent_responses.push("界".repeat(TIMELINE_MAX_BYTES));
+ }, { now: NOW })).toBe(false);
+ expect(updateCalls).toBe(1);
+ expect(fs.readFileSync(todayFile)).toEqual(beforeToday);
+ expect(fs.readFileSync(yesterdayFile)).toEqual(beforeYesterday);
+ });
+
+ it("rejects a busy latest-day lock without updating or falling back to yesterday", () => {
+ const dir = mkDir();
+ const yesterday = new Date(NOW);
+ yesterday.setDate(yesterday.getDate() - 1);
+ expect(appendEntry(dir, createTimelineEntry({ messages: [msg("yesterday")] }), yesterday)).toBe(true);
+ expect(appendEntry(dir, createTimelineEntry({ messages: [msg("today")] }), NOW)).toBe(true);
+ const yesterdayFile = path.join(dir, filenameForDate(yesterday));
+ const todayFilename = filenameForDate(NOW);
+ const todayFile = path.join(dir, todayFilename);
+ const beforeYesterday = fs.readFileSync(yesterdayFile);
+ const beforeToday = fs.readFileSync(todayFile);
+ const lock = lockPathFor(dir, todayFilename);
+ let updateCalls = 0;
+ expect(acquireLock(lock)).toBe(true);
+ try {
+ expect(updateLatestEntryResult(dir, () => { updateCalls++; }, { now: NOW })).toBe("rejected");
+ } finally {
+ releaseLock(lock);
+ }
+
+ expect(updateCalls).toBe(0);
+ expect(fs.readFileSync(todayFile)).toEqual(beforeToday);
+ expect(fs.readFileSync(yesterdayFile)).toEqual(beforeYesterday);
+ });
+
+ it("converges an oversized historical file after a successful update", () => {
+ const dir = mkDir();
+ const file = path.join(dir, filenameForDate(NOW));
+ const rows = Array.from({ length: 5 }, (_, index) => entryWithPayloadBytes(240_000, `s${index}`));
+ fs.writeFileSync(file, rows.map((row) => JSON.stringify(row)).join("\n") + "\n");
+
+ expect(updateLatestEntry(dir, (entry) => entry.agent_responses.push("updated"), { now: NOW })).toBe(true);
+ expect(fs.statSync(file).size).toBeLessThanOrEqual(TIMELINE_MAX_BYTES);
+ expect(readRecentEntries(dir, { now: NOW }).at(-1)?.agent_responses).toEqual(["updated"]);
+ });
+});
+
+describe("daily timeline hard cap", () => {
+ it("evicts oldest complete rows and keeps valid ordered JSONL at or below exactly 1 MiB", () => {
+ const dir = mkDir();
+ for (let index = 0; index < 6; index++) {
+ expect(appendEntry(dir, entryWithPayloadBytes(240_000, `s${index}`), NOW)).toBe(true);
+ }
+ const file = path.join(dir, filenameForDate(NOW));
+ expect(fs.statSync(file).size).toBeLessThanOrEqual(TIMELINE_MAX_BYTES);
+ const physical = fs.readFileSync(file, "utf8").trimEnd().split("\n");
+ expect(() => physical.map((line) => JSON.parse(line))).not.toThrow();
+ const rows = readRecentEntries(dir, { now: NOW });
+ expect(rows.map((row) => row.session_id)).toEqual(["s2", "s3", "s4", "s5"]);
+ });
+
+ it("rejects an over-cap prospective row and leaves the original bytes unchanged", () => {
+ const dir = mkDir();
+ expect(appendEntry(dir, createTimelineEntry({ messages: [msg("original")] }), NOW)).toBe(true);
+ const file = path.join(dir, filenameForDate(NOW));
+ const before = fs.readFileSync(file);
+ expect(appendEntry(dir, entryWithPayloadBytes(TIMELINE_MAX_BYTES), NOW)).toBe(false);
+ expect(fs.readFileSync(file)).toEqual(before);
+ });
+
+ it("uses UTF-8 byte length at the exact cap and rejects a multibyte overflow", () => {
+ const dir = mkDir();
+ const exact = entryAtExactBytesWithMultibyte(TIMELINE_MAX_BYTES);
+ expect(Buffer.byteLength(JSON.stringify(exact), "utf8") + 1).toBe(TIMELINE_MAX_BYTES);
+ expect(appendEntry(dir, exact, NOW)).toBe(true);
+ const file = path.join(dir, filenameForDate(NOW));
+ expect(fs.statSync(file).size).toBe(TIMELINE_MAX_BYTES);
+ const before = fs.readFileSync(file);
+ const overflow = createTimelineEntry({
+ messages: [msg(`${exact.messages[0].content.text}界`)],
+ sessionId: "utf8",
+ provider: "claude",
+ });
+
+ expect(Buffer.byteLength(JSON.stringify(overflow), "utf8") + 1).toBe(TIMELINE_MAX_BYTES + 3);
+ expect(appendEntry(dir, overflow, NOW)).toBe(false);
+ expect(fs.readFileSync(file)).toEqual(before);
+ });
+
+ it("rejects a newest row that fits alone but cannot coexist with the required barrier sentinel", () => {
+ const dir = mkDir();
+ const barrier = createSystemEntry("reset_session", "2026-06-25T12:00:00Z");
+ expect(appendEntry(dir, barrier, NOW)).toBe(true);
+ const file = path.join(dir, filenameForDate(NOW));
+ const before = fs.readFileSync(file);
+ const candidate = entryAtExactBytes(TIMELINE_MAX_BYTES);
+ expect(Buffer.byteLength(JSON.stringify(candidate), "utf8") + 1).toBe(TIMELINE_MAX_BYTES);
+ expect(appendEntry(dir, candidate, NOW)).toBe(false);
+ expect(fs.readFileSync(file)).toEqual(before);
+ });
+
+ it("historical convergence keeps the barrier and drops an ordinary row that cannot coexist", async () => {
+ const base = mkDir();
+ const dir = path.join(base, "agent-a", ".context_timeline");
+ fs.mkdirSync(dir, { recursive: true });
+ const file = path.join(dir, filenameForDate(NOW));
+ const barrier = createSystemEntry("nap", "2026-06-25T12:00:00Z");
+ const ordinary = entryAtExactBytes(TIMELINE_MAX_BYTES);
+ fs.writeFileSync(file, `${JSON.stringify(barrier)}\n${JSON.stringify(ordinary)}\n`);
+
+ await sweepTimelineHistory(base, { yieldAfterFile: async () => {} });
+
+ expect(fs.statSync(file).size).toBeLessThanOrEqual(TIMELINE_MAX_BYTES);
+ const rows = readRecentEntries(dir, { now: NOW });
+ expect(rows).toHaveLength(1);
+ expect(rows[0].system?.type).toBe("nap");
+ });
+
+ it("discards a complete historical row that alone exceeds the cap", async () => {
+ const base = mkDir();
+ const dir = path.join(base, "agent-a", ".context_timeline");
+ fs.mkdirSync(dir, { recursive: true });
+ const file = path.join(dir, filenameForDate(NOW));
+ const oversized = entryWithPayloadBytes(TIMELINE_MAX_BYTES + 1);
+ fs.writeFileSync(file, `${JSON.stringify(oversized)}\n`);
+ expect(fs.statSync(file).size).toBeGreaterThan(TIMELINE_MAX_BYTES);
+
+ await sweepTimelineHistory(base, { yieldAfterFile: async () => {} });
+
+ expect(fs.statSync(file).size).toBeLessThanOrEqual(TIMELINE_MAX_BYTES);
+ expect(readRecentEntries(dir, { now: NOW })).toEqual([]);
+ });
+
+ it("keeps only the latest barrier from an evicted prefix", async () => {
+ const base = mkDir();
+ const dir = path.join(base, "agent-a", ".context_timeline");
+ fs.mkdirSync(dir, { recursive: true });
+ const file = path.join(dir, filenameForDate(NOW));
+ const rows = [
+ createSystemEntry("reset_session", "2026-06-25T10:00:00Z"),
+ entryWithPayloadBytes(300_000, "between"),
+ createSystemEntry("nap", "2026-06-25T11:00:00Z"),
+ ...Array.from({ length: 5 }, (_, index) => entryWithPayloadBytes(240_000, `new-${index}`)),
+ ];
+ fs.writeFileSync(file, rows.map((row) => JSON.stringify(row)).join("\n") + "\n");
+
+ await sweepTimelineHistory(base, { yieldAfterFile: async () => {} });
+
+ const retained = readRecentEntries(dir, { now: NOW });
+ expect(retained.filter((row) => row.system).map((row) => row.system?.type)).toEqual(["nap"]);
+ expect(retained[0].system?.time).toBe("2026-06-25T11:00:00Z");
+ });
+
+ it("does not copy an evicted barrier when the retained suffix has a newer one", async () => {
+ const base = mkDir();
+ const dir = path.join(base, "agent-a", ".context_timeline");
+ fs.mkdirSync(dir, { recursive: true });
+ const file = path.join(dir, filenameForDate(NOW));
+ const rows = [
+ createSystemEntry("reset_session", "2026-06-25T10:00:00Z"),
+ ...Array.from({ length: 5 }, (_, index) => entryWithPayloadBytes(240_000, `middle-${index}`)),
+ createSystemEntry("nap", "2026-06-25T11:00:00Z"),
+ entryWithPayloadBytes(100_000, "newest"),
+ ];
+ fs.writeFileSync(file, rows.map((row) => JSON.stringify(row)).join("\n") + "\n");
+
+ await sweepTimelineHistory(base, { yieldAfterFile: async () => {} });
+
+ const retained = readRecentEntries(dir, { now: NOW });
+ expect(retained.filter((row) => row.system).map((row) => row.system?.type)).toEqual(["nap"]);
+ expect(retained.find((row) => row.system)?.system?.time).toBe("2026-06-25T11:00:00Z");
+ });
+
+ it("keeps the latest evicted barrier across days and resumes only a newer matching-provider session", () => {
+ const dir = mkDir();
+ const yesterday = new Date(NOW);
+ yesterday.setDate(yesterday.getDate() - 1);
+ expect(appendEntry(dir, createTimelineEntry({ messages: [msg("old")], sessionId: "s-old", provider: "claude" }), yesterday)).toBe(true);
+ expect(appendEntry(dir, createSystemEntry("reset_session", "2026-06-25T10:00:00Z"), NOW)).toBe(true);
+ for (let index = 0; index < 6; index++) {
+ expect(appendEntry(dir, entryWithPayloadBytes(220_000, null, "codex"), NOW)).toBe(true);
+ }
+ expect(findResumableSession(readRecentEntries(dir, { maxDays: 2, now: NOW }), "claude")).toBeNull();
+
+ expect(appendEntry(dir, createTimelineEntry({ messages: [msg("new")], sessionId: "s-new", provider: "codex" }), NOW)).toBe(true);
+ const rows = readRecentEntries(dir, { maxDays: 2, now: NOW });
+ expect(findResumableSession(rows, "codex")).toBe("s-new");
+ expect(findResumableSession(rows, "claude")).toBeNull();
+ });
+});
+
+describe("timeline convergence filesystem boundaries", () => {
+ it("rejects reads and writes through an intermediate agent-directory symlink", () => {
+ if (process.platform === "win32") return;
+ const base = mkDir();
+ const outsideAgent = mkDir();
+ const outsideTimeline = path.join(outsideAgent, ".context_timeline");
+ fs.mkdirSync(outsideTimeline);
+ const file = path.join(outsideTimeline, filenameForDate(NOW));
+ fs.writeFileSync(file, `${JSON.stringify(createTimelineEntry({
+ messages: [msg("outside")],
+ sessionId: "outside-session",
+ provider: "claude",
+ }))}\n`);
+ const before = fs.readFileSync(file);
+ const agentLink = path.join(base, "agent-link");
+ fs.symlinkSync(outsideAgent, agentLink);
+ const linkedTimeline = path.join(agentLink, ".context_timeline");
+
+ expect(readRecentEntries(linkedTimeline, { now: NOW })).toEqual([]);
+ expect(appendEntry(linkedTimeline, createTimelineEntry({ messages: [msg("blocked")] }), NOW)).toBe(false);
+ expect(fs.readFileSync(file)).toEqual(before);
+ });
+
+ it("rejects normal appends through a timeline directory symlink or daily file symlink", () => {
+ if (process.platform === "win32") return;
+ const base = mkDir();
+ const outside = mkDir();
+ const filename = filenameForDate(NOW);
+ const outsideTimelineFile = path.join(outside, filename);
+ fs.writeFileSync(outsideTimelineFile, "outside timeline unchanged\n");
+ const timelineLink = path.join(base, "timeline-link");
+ fs.symlinkSync(outside, timelineLink);
+ const beforeTimelineTarget = fs.readFileSync(outsideTimelineFile);
+
+ expect(appendEntry(timelineLink, createTimelineEntry({ messages: [msg("blocked-dir-link")] }), NOW)).toBe(false);
+ expect(fs.readFileSync(outsideTimelineFile)).toEqual(beforeTimelineTarget);
+
+ const realTimeline = path.join(base, "real-timeline");
+ fs.mkdirSync(realTimeline);
+ const outsideDailyTarget = path.join(outside, "daily-target.jsonl");
+ fs.writeFileSync(outsideDailyTarget, "outside daily unchanged\n");
+ fs.symlinkSync(outsideDailyTarget, path.join(realTimeline, filename));
+ const beforeDailyTarget = fs.readFileSync(outsideDailyTarget);
+
+ expect(appendEntry(realTimeline, createTimelineEntry({ messages: [msg("blocked-file-link")] }), NOW)).toBe(false);
+ expect(fs.readFileSync(outsideDailyTarget)).toEqual(beforeDailyTarget);
+ });
+
+ it("ignores a pre-existing fixed-temp symlink and atomically replaces through a random 0600 temp", () => {
+ if (process.platform === "win32") return;
+ const dir = mkDir();
+ const outside = mkDir();
+ const filename = filenameForDate(NOW);
+ const file = path.join(dir, filename);
+ const fixedTemp = path.join(dir, `.${filename}.tmp`);
+ const outsideTarget = path.join(outside, "target.txt");
+ fs.writeFileSync(outsideTarget, "outside unchanged\n");
+ fs.symlinkSync(outsideTarget, fixedTemp);
+ expect(appendEntry(
+ dir,
+ createTimelineEntry({ messages: [msg("first")], sessionId: "s1", provider: "claude" }),
+ NOW,
+ )).toBe(true);
+
+ expect(appendOrMergeEntry(
+ dir,
+ createTimelineEntry({ messages: [msg("second")], sessionId: "s1", provider: "claude" }),
+ NOW,
+ )).toBe(true);
+
+ expect(fs.readFileSync(outsideTarget, "utf8")).toBe("outside unchanged\n");
+ expect(fs.lstatSync(file).isFile()).toBe(true);
+ expect(fs.statSync(file).mode & 0o777).toBe(0o600);
+ expect(fs.lstatSync(fixedTemp).isSymbolicLink()).toBe(true);
+ expect(fs.readdirSync(dir).filter((name) => name.startsWith(`.${filename}.`) && name !== `.${filename}.tmp`)).toEqual([]);
+ });
+
+ it("drops malformed rows and an incomplete tail, then writes only parseable lines", async () => {
+ const base = mkDir();
+ const dir = path.join(base, "agent-a", ".context_timeline");
+ fs.mkdirSync(dir, { recursive: true });
+ const file = path.join(dir, filenameForDate(NOW));
+ fs.writeFileSync(
+ file,
+ `${JSON.stringify(createTimelineEntry({ messages: [msg("old")] }))}\n{bad json}\n${JSON.stringify(createTimelineEntry({ messages: [msg("new")] }))}\n${JSON.stringify(createTimelineEntry({ messages: [msg("incomplete")] }))}`,
+ );
+
+ await sweepTimelineHistory(base, { yieldAfterFile: async () => {} });
+
+ const physical = fs.readFileSync(file, "utf8").trimEnd().split("\n");
+ expect(physical.map((line) => JSON.parse(line)).map((row) => row.messages[0].content.text)).toEqual(["old", "new"]);
+ });
+
+ it("skips a held lock and the next normal write converges the file", async () => {
+ const base = mkDir();
+ const dir = path.join(base, "agent-a", ".context_timeline");
+ fs.mkdirSync(dir, { recursive: true });
+ const filename = filenameForDate(NOW);
+ const file = path.join(dir, filename);
+ fs.writeFileSync(file, Array.from({ length: 6 }, (_, index) => JSON.stringify(entryWithPayloadBytes(240_000, `s${index}`))).join("\n") + "\n");
+ const lock = lockPathFor(dir, filename);
+ const yielded: string[] = [];
+ expect(acquireLock(lock)).toBe(true);
+ try {
+ await sweepTimelineHistory(base, { yieldAfterFile: async (filePath) => { yielded.push(filePath); } });
+ expect(fs.statSync(file).size).toBeGreaterThan(TIMELINE_MAX_BYTES);
+ } finally {
+ releaseLock(lock);
+ }
+ expect(yielded).toEqual([file]);
+
+ expect(appendEntry(dir, createTimelineEntry({ messages: [msg("latest")], sessionId: "latest" }), NOW)).toBe(true);
+ expect(fs.statSync(file).size).toBeLessThanOrEqual(TIMELINE_MAX_BYTES);
+ expect(readRecentEntries(dir, { now: NOW }).at(-1)?.session_id).toBe("latest");
+ });
+
+ it("sorts every exact immediate-child file and rejects directory/file symlinks", async () => {
+ if (process.platform === "win32") return;
+ const base = mkDir();
+ const outside = mkDir();
+ const outsideFile = path.join(outside, filenameForDate(NOW));
+ fs.writeFileSync(outsideFile, `${JSON.stringify(createTimelineEntry({ messages: [msg("outside")] }))}\n`);
+ fs.symlinkSync(outside, path.join(base, "agent-link"));
+ fs.mkdirSync(path.join(base, "agent-timeline-link"));
+ fs.symlinkSync(outside, path.join(base, "agent-timeline-link", ".context_timeline"));
+
+ for (const agent of ["agent-b", "agent-a"]) {
+ const dir = path.join(base, agent, ".context_timeline");
+ fs.mkdirSync(dir, { recursive: true });
+ fs.writeFileSync(path.join(dir, "2026-06-24.jsonl"), `${JSON.stringify(createTimelineEntry({ messages: [msg(agent)] }))}\n`);
+ }
+ const dateNamedDirectory = path.join(base, "agent-b", ".context_timeline", filenameForDate(NOW));
+ fs.mkdirSync(dateNamedDirectory);
+ const dailyTarget = path.join(outside, "daily-target.jsonl");
+ fs.writeFileSync(dailyTarget, "target unchanged\n");
+ fs.symlinkSync(dailyTarget, path.join(base, "agent-a", ".context_timeline", filenameForDate(NOW)));
+ fs.writeFileSync(path.join(base, "agent-a", ".context_timeline", "not-a-date.jsonl"), "ignored\n");
+ const yielded: string[] = [];
+
+ await sweepTimelineHistory(base, { yieldAfterFile: async (filePath) => { yielded.push(filePath); } });
+
+ expect(yielded.map((filePath) => path.relative(base, filePath))).toEqual([
+ path.join("agent-a", ".context_timeline", "2026-06-24.jsonl"),
+ path.join("agent-b", ".context_timeline", "2026-06-24.jsonl"),
+ ]);
+ expect(fs.readFileSync(outsideFile, "utf8")).toContain("outside");
+ expect(fs.readFileSync(dailyTarget, "utf8")).toBe("target unchanged\n");
+ expect(fs.lstatSync(dateNamedDirectory).isDirectory()).toBe(true);
+ });
});
describe("findResumableSession", () => {
diff --git a/src/daemon/src/timeline/timeline.ts b/src/daemon/src/timeline/timeline.ts
index 2b02ce9fe..ad42dfbd3 100644
--- a/src/daemon/src/timeline/timeline.ts
+++ b/src/daemon/src/timeline/timeline.ts
@@ -11,8 +11,9 @@
* deterministic — this module never calls `Date.now()`/`new Date()` implicitly
* except behind the default param.
*/
-import { appendFileSync, readFileSync, writeFileSync, renameSync, existsSync } from "fs";
-import { join } from "path";
+import * as fs from "node:fs";
+import { randomBytes } from "node:crypto";
+import { basename, dirname, join } from "node:path";
import { acquireLock, releaseLock, lockPathFor } from "./filelock.js";
import type { ContextTimelineEntry, SystemEntryType } from "./types.js";
import type { Message } from "../server/contract.js";
@@ -20,6 +21,270 @@ import { localISOString } from "../util/localTime.js";
export { localISOString };
+export const TIMELINE_MAX_BYTES = 1_048_576;
+export const TIMELINE_READ_CHUNK_BYTES = 65_536;
+const DATE_FILENAME_PATTERN = /^\d{4}-\d{2}-\d{2}\.jsonl$/;
+
+interface TimelineLine {
+ text: string;
+ bytes: number;
+ entry: ContextTimelineEntry;
+ barrier: boolean;
+}
+
+function isBarrier(entry: ContextTimelineEntry): boolean {
+ return entry.system?.type === "reset_session" || entry.system?.type === "nap";
+}
+
+function canonicalTimelineEntry(value: unknown): ContextTimelineEntry | null {
+ if (!value || typeof value !== "object") return null;
+ const entry = value as Partial<ContextTimelineEntry>;
+ if (entry.system) {
+ if (
+ (entry.system.type !== "reset_session" && entry.system.type !== "nap") ||
+ typeof entry.system.time !== "string"
+ ) return null;
+ return createSystemEntry(entry.system.type, entry.system.time);
+ }
+ if (entry.session_id !== null && typeof entry.session_id !== "string") return null;
+ if (entry.provider !== null && typeof entry.provider !== "string") return null;
+ if (!Array.isArray(entry.messages) || !Array.isArray(entry.agent_responses)) return null;
+ if (!entry.agent_responses.every((response) => typeof response === "string")) return null;
+ return {
+ session_id: entry.session_id,
+ messages: entry.messages,
+ agent_responses: entry.agent_responses.slice(-5),
+ provider: entry.provider,
+ };
+}
+
+function timelineLine(entry: ContextTimelineEntry): TimelineLine | null {
+ const boundedEntry = entry.system
+ ? createSystemEntry(entry.system.type, entry.system.time)
+ : { ...entry, agent_responses: entry.agent_responses.slice(-5) };
+ const text = JSON.stringify(boundedEntry);
+ const bytes = Buffer.byteLength(text, "utf8") + 1;
+ if (bytes > TIMELINE_MAX_BYTES) return null;
+ return { text, bytes, entry: boundedEntry, barrier: isBarrier(boundedEntry) };
+}
+
+function compactLines(input: readonly TimelineLine[]): TimelineLine[] {
+ let head = 0;
+ let bytes = input.reduce((total, line) => total + line.bytes, 0);
+ let latestEvictedBarrier: TimelineLine | null = null;
+ while (bytes > TIMELINE_MAX_BYTES && head < input.length) {
+ const removed = input[head++]!;
+ bytes -= removed.bytes;
+ if (removed.barrier) latestEvictedBarrier = removed;
+ }
+ let suffix = input.slice(head);
+ if (!suffix.some((line) => line.barrier) && latestEvictedBarrier) {
+ let suffixHead = 0;
+ while (latestEvictedBarrier.bytes + bytes > TIMELINE_MAX_BYTES && suffixHead < suffix.length) {
+ bytes -= suffix[suffixHead++]!.bytes;
+ }
+ suffix = [latestEvictedBarrier, ...suffix.slice(suffixHead)];
+ }
+ return suffix;
+}
+
+function isRealDirectory(path: string): boolean {
+ try {
+ return fs.lstatSync(path).isDirectory();
+ } catch {
+ return false;
+ }
+}
+
+type TimelineDirectoryState = "safe" | "missing" | "unsafe";
+
+function timelineDirectoryState(timelineDir: string): TimelineDirectoryState {
+ if (!isRealDirectory(dirname(timelineDir))) return "unsafe";
+ try {
+ return fs.lstatSync(timelineDir).isDirectory() ? "safe" : "unsafe";
+ } catch (error) {
+ return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "unsafe";
+ }
+}
+
+export function prepareTimelineDirectory(timelineDir: string): boolean {
+ const state = timelineDirectoryState(timelineDir);
+ if (state === "safe") return true;
+ if (state === "unsafe") return false;
+ try {
+ fs.mkdirSync(timelineDir);
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== "EEXIST") return false;
+ }
+ return timelineDirectoryState(timelineDir) === "safe";
+}
+
+function scanTimelineFile(filePath: string): TimelineLine[] | null {
+ let source: fs.Stats;
+ try {
+ source = fs.lstatSync(filePath);
+ } catch (error) {
+ return (error as NodeJS.ErrnoException).code === "ENOENT" ? [] : null;
+ }
+ if (!source.isFile()) return null;
+
+ let fd: number | null = null;
+ try {
+ fd = fs.openSync(filePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+ const stat = fs.fstatSync(fd);
+ if (!stat.isFile()) return null;
+
+ const chunk = Buffer.allocUnsafe(TIMELINE_READ_CHUNK_BYTES);
+ const newest: TimelineLine[] = [];
+ let retainedBytes = 0;
+ let overflowed = false;
+ let suffixHasBarrier = false;
+ let latestEvictedBarrier: TimelineLine | null = null;
+ let parts: Buffer[] = [];
+ let partBytes = 0;
+ let oversized = false;
+ let stop = false;
+ let discardIncompleteTail = false;
+
+ if (stat.size > 0) {
+ const last = Buffer.allocUnsafe(1);
+ fs.readSync(fd, last, 0, 1, stat.size - 1);
+ discardIncompleteTail = last[0] !== 10;
+ }
+
+ const resetPhysicalLine = (): void => {
+ parts = [];
+ partBytes = 0;
+ oversized = false;
+ };
+ const addPart = (part: Buffer): void => {
+ if (oversized) return;
+ if (partBytes + part.length > TIMELINE_MAX_BYTES) {
+ parts = [];
+ partBytes = 0;
+ oversized = true;
+ return;
+ }
+ if (part.length > 0) parts.push(Buffer.from(part));
+ partBytes += part.length;
+ };
+ const retain = (line: TimelineLine): void => {
+ if (!overflowed && retainedBytes + line.bytes <= TIMELINE_MAX_BYTES) {
+ newest.push(line);
+ retainedBytes += line.bytes;
+ if (line.barrier) suffixHasBarrier = true;
+ return;
+ }
+ overflowed = true;
+ if (suffixHasBarrier) {
+ stop = true;
+ } else if (line.barrier) {
+ latestEvictedBarrier = line;
+ stop = true;
+ }
+ };
+ const finishPhysicalLine = (part: Buffer): void => {
+ addPart(part);
+ if (discardIncompleteTail) {
+ discardIncompleteTail = false;
+ resetPhysicalLine();
+ return;
+ }
+ if (!oversized && partBytes > 0) {
+ let physical = Buffer.concat([...parts].reverse(), partBytes);
+ if (physical[physical.length - 1] === 13) physical = physical.subarray(0, -1);
+ if (physical.length > 0) {
+ try {
+ const entry = canonicalTimelineEntry(JSON.parse(physical.toString("utf8")));
+ const line = entry ? timelineLine(entry) : null;
+ if (line) retain(line);
+ } catch {
+ /* malformed historical row */
+ }
+ }
+ }
+ resetPhysicalLine();
+ };
+
+ let position = stat.size;
+ while (position > 0 && !stop) {
+ const start = Math.max(0, position - chunk.length);
+ const requested = position - start;
+ let count = 0;
+ while (count < requested) {
+ const read = fs.readSync(fd, chunk, count, requested - count, start + count);
+ if (read <= 0) break;
+ count += read;
+ }
+ if (count !== requested) return null;
+ let segmentEnd = count;
+ for (let index = count - 1; index >= 0; index--) {
+ if (chunk[index] !== 10) continue;
+ finishPhysicalLine(chunk.subarray(index + 1, segmentEnd));
+ segmentEnd = index;
+ if (stop) break;
+ }
+ if (!stop && segmentEnd > 0) addPart(chunk.subarray(0, segmentEnd));
+ position = start;
+ }
+ if (!stop && position === 0 && (parts.length > 0 || oversized) && !discardIncompleteTail) {
+ finishPhysicalLine(Buffer.alloc(0));
+ }
+
+ const sentinel = latestEvictedBarrier as TimelineLine | null;
+ if (sentinel && !suffixHasBarrier) {
+ while (newest.length > 0 && sentinel.bytes + retainedBytes > TIMELINE_MAX_BYTES) {
+ retainedBytes -= newest.pop()!.bytes;
+ }
+ }
+ const chronological = newest.reverse();
+ return sentinel && !suffixHasBarrier
+ ? [sentinel, ...chronological]
+ : chronological;
+ } catch {
+ return null;
+ } finally {
+ if (fd !== null) {
+ try { fs.closeSync(fd); } catch { /* best effort */ }
+ }
+ }
+}
+
+function atomicReplaceTimeline(filePath: string, lines: readonly TimelineLine[]): boolean {
+ const tempPath = join(
+ dirname(filePath),
+ `.${basename(filePath)}.${process.pid}.${randomBytes(12).toString("hex")}.tmp`,
+ );
+ let fd: number | null = null;
+ try {
+ fd = fs.openSync(tempPath, "wx", 0o600);
+ const body = lines.map((line) => line.text).join("\n") + (lines.length > 0 ? "\n" : "");
+ fs.writeFileSync(fd, body, "utf8");
+ fs.fsyncSync(fd);
+ fs.closeSync(fd);
+ fd = null;
+ fs.renameSync(tempPath, filePath);
+ return true;
+ } catch {
+ return false;
+ } finally {
+ if (fd !== null) {
+ try { fs.closeSync(fd); } catch { /* best effort */ }
+ }
+ try { fs.unlinkSync(tempPath); } catch { /* best effort */ }
+ }
+}
+
+function writeRequiredTimeline(
+ filePath: string,
+ input: readonly TimelineLine[],
+ required: TimelineLine,
+): boolean {
+ const compacted = compactLines(input);
+ if (!compacted.includes(required)) return false;
+ return atomicReplaceTimeline(filePath, compacted);
+}
+
/* ------------------------------------------------------------------ */
/* Date / filename helpers (injectable clock) */
/* ------------------------------------------------------------------ */
@@ -47,22 +312,7 @@ export function recentFilenames(maxDays: number, now: Date): string[] {
/* ------------------------------------------------------------------ */
function readJsonl(filePath: string): ContextTimelineEntry[] {
- let content: string;
- try {
- content = readFileSync(filePath, "utf-8");
- } catch {
- return [];
- }
- const entries: ContextTimelineEntry[] = [];
- for (const line of content.trimEnd().split("\n")) {
- if (!line) continue;
- try {
- entries.push(JSON.parse(line) as ContextTimelineEntry);
- } catch {
- /* skip malformed line */
- }
- }
- return entries;
+ return scanTimelineFile(filePath)?.map((line) => line.entry) ?? [];
}
export interface ReadRecentOptions {
@@ -79,6 +329,7 @@ export interface ReadRecentOptions {
* resume helper consumes; it does NOT read files itself.
*/
export function readRecentEntries(timelineDir: string, opts: ReadRecentOptions = {}): ContextTimelineEntry[] {
+ if (timelineDirectoryState(timelineDir) !== "safe") return [];
const now = opts.now ?? new Date();
const maxDays = opts.maxDays ?? 7;
// recentFilenames is today-first; reverse to oldest-first for ascending time.
@@ -96,13 +347,16 @@ export function readRecentEntries(timelineDir: string, opts: ReadRecentOptions =
/** Append a new entry to today's file. Best-effort: logs nothing, swallows lock miss. */
export function appendEntry(timelineDir: string, entry: ContextTimelineEntry, now: Date = new Date()): boolean {
+ if (timelineDirectoryState(timelineDir) !== "safe") return false;
const filename = filenameForDate(now);
const filePath = join(timelineDir, filename);
const lockPath = lockPathFor(timelineDir, filename);
if (!acquireLock(lockPath)) return false;
try {
- appendFileSync(filePath, JSON.stringify(entry) + "\n");
- return true;
+ const existing = scanTimelineFile(filePath);
+ const required = timelineLine(entry);
+ if (!existing || !required) return false;
+ return writeRequiredTimeline(filePath, [...existing, required], required);
} catch {
return false;
} finally {
@@ -124,17 +378,16 @@ export function appendEntry(timelineDir: string, entry: ContextTimelineEntry, no
* critical section. Best-effort (swallows lock miss / errors).
*/
export function appendOrMergeEntry(timelineDir: string, entry: ContextTimelineEntry, now: Date = new Date()): boolean {
+ if (timelineDirectoryState(timelineDir) !== "safe") return false;
const filename = filenameForDate(now);
const filePath = join(timelineDir, filename);
const lockPath = lockPathFor(timelineDir, filename);
if (!acquireLock(lockPath)) return false;
try {
- let lines: string[] = [];
- if (existsSync(filePath)) {
- lines = readFileSync(filePath, "utf-8").trimEnd().split("\n").filter(Boolean);
- }
- if (lines.length > 0) {
- const latest = JSON.parse(lines[lines.length - 1]) as ContextTimelineEntry;
+ const existing = scanTimelineFile(filePath);
+ if (!existing) return false;
+ if (existing.length > 0) {
+ const latest = existing[existing.length - 1]!.entry;
const mergeable =
!latest.system &&
!entry.system &&
@@ -142,16 +395,19 @@ export function appendOrMergeEntry(timelineDir: string, entry: ContextTimelineEn
latest.provider === entry.provider &&
latest.agent_responses.length === 0;
if (mergeable) {
- latest.messages = [...latest.messages, ...entry.messages];
- lines[lines.length - 1] = JSON.stringify(latest);
- const tmpPath = join(timelineDir, `.${filename}.tmp`);
- writeFileSync(tmpPath, lines.join("\n") + "\n");
- renameSync(tmpPath, filePath);
- return true;
+ const merged: ContextTimelineEntry = {
+ ...latest,
+ messages: [...latest.messages, ...entry.messages],
+ agent_responses: [...latest.agent_responses],
+ };
+ const required = timelineLine(merged);
+ if (!required) return false;
+ return writeRequiredTimeline(filePath, [...existing.slice(0, -1), required], required);
}
}
- appendFileSync(filePath, JSON.stringify(entry) + "\n");
- return true;
+ const required = timelineLine(entry);
+ if (!required) return false;
+ return writeRequiredTimeline(filePath, [...existing, required], required);
} catch {
return false;
} finally {
@@ -182,6 +438,18 @@ export function updateLatestEntry(
updater: (entry: ContextTimelineEntry) => void,
opts: { maxDays?: number; now?: Date } = {},
): boolean {
+ return updateLatestEntryResult(timelineDir, updater, opts) === "updated";
+}
+
+export type UpdateLatestEntryResult = "updated" | "missing" | "rejected";
+
+export function updateLatestEntryResult(
+ timelineDir: string,
+ updater: (entry: ContextTimelineEntry) => void,
+ opts: { maxDays?: number; now?: Date } = {},
+): UpdateLatestEntryResult {
+ const directoryState = timelineDirectoryState(timelineDir);
+ if (directoryState !== "safe") return directoryState === "missing" ? "missing" : "rejected";
const now = opts.now ?? new Date();
const maxDays = opts.maxDays ?? 7;
for (const filename of recentFilenames(maxDays, now)) {
@@ -190,36 +458,111 @@ export function updateLatestEntry(
// never try to mkdir a lock dir under a timelineDir that doesn't exist (the
// common case: a runtime event arrives before the first inbox-pull opened any
// entry). Avoids an ENOENT from the lock's non-recursive mkdir.
- if (!existsSync(filePath)) continue;
+ let source: fs.Stats;
+ try {
+ source = fs.lstatSync(filePath);
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+ return "rejected";
+ }
+ if (!source.isFile()) return "rejected";
const lockPath = lockPathFor(timelineDir, filename);
- if (!acquireLock(lockPath)) continue;
+ if (!acquireLock(lockPath)) return "rejected";
try {
- let content: string;
- try {
- content = readFileSync(filePath, "utf-8");
- } catch {
- continue; // no file for this day → look at an older day
- }
- const lines = content.trimEnd().split("\n").filter(Boolean);
+ const lines = scanTimelineFile(filePath);
+ if (!lines) return "rejected";
if (lines.length === 0) continue;
- const entries = lines.map((l) => JSON.parse(l) as ContextTimelineEntry);
// The newest row of the newest day file is authoritative: if it's a
// system barrier, we must NOT walk past it into a pre-barrier turn.
// Return false and let the caller open a fresh post-barrier turn row.
- const latest = entries[entries.length - 1];
- if (latest.system) return false;
- updater(latest);
- const tmpPath = join(timelineDir, `.${filename}.tmp`);
- writeFileSync(tmpPath, entries.map((e) => JSON.stringify(e)).join("\n") + "\n");
- renameSync(tmpPath, filePath);
- return true;
+ const latest = lines[lines.length - 1]!.entry;
+ if (latest.system) return "missing";
+ const updated: ContextTimelineEntry = {
+ ...latest,
+ messages: [...latest.messages],
+ agent_responses: [...latest.agent_responses],
+ };
+ try {
+ updater(updated);
+ } catch {
+ return "rejected";
+ }
+ const required = timelineLine(updated);
+ if (!required) return "rejected";
+ return writeRequiredTimeline(filePath, [...lines.slice(0, -1), required], required)
+ ? "updated"
+ : "rejected";
} catch {
- /* try an older day file */
+ return "rejected";
} finally {
releaseLock(lockPath);
}
}
- return false;
+ return "missing";
+}
+
+export interface TimelineSweepOptions {
+ yieldAfterFile?: (filePath: string) => Promise<void>;
+}
+
+function yieldToEventLoop(): Promise<void> {
+ return new Promise((resolve) => setImmediate(resolve));
+}
+
+export async function sweepTimelineHistory(
+ workingDirectoryBase: string,
+ opts: TimelineSweepOptions = {},
+): Promise<void> {
+ const yieldAfterFile = opts.yieldAfterFile ?? (() => yieldToEventLoop());
+ if (!opts.yieldAfterFile) await yieldToEventLoop();
+ if (!isRealDirectory(workingDirectoryBase)) return;
+
+ let agentNames: string[];
+ try {
+ agentNames = fs.readdirSync(workingDirectoryBase).sort();
+ } catch {
+ return;
+ }
+ for (const agentName of agentNames) {
+ const agentDir = join(workingDirectoryBase, agentName);
+ if (!isRealDirectory(agentDir)) continue;
+ const timelineDir = join(agentDir, ".context_timeline");
+ if (!isRealDirectory(timelineDir)) continue;
+
+ let filenames: string[];
+ try {
+ filenames = fs.readdirSync(timelineDir)
+ .filter((name) => DATE_FILENAME_PATTERN.test(name))
+ .sort();
+ } catch {
+ continue;
+ }
+ for (const filename of filenames) {
+ const filePath = join(timelineDir, filename);
+ let source: fs.Stats;
+ try {
+ source = fs.lstatSync(filePath);
+ } catch {
+ continue;
+ }
+ if (!source.isFile()) continue;
+
+ try {
+ const lockPath = lockPathFor(timelineDir, filename);
+ if (acquireLock(lockPath)) {
+ try {
+ const lines = scanTimelineFile(filePath);
+ if (lines) atomicReplaceTimeline(filePath, lines);
+ } finally {
+ releaseLock(lockPath);
+ }
+ }
+ } catch {
+ /* best-effort per file */
+ }
+ await yieldAfterFile(filePath);
+ }
+ }
}
/* ------------------------------------------------------------------ */