Skip to content

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

Rust

[RSI, performance] Append catalog metadata without full transcript parses (#2433)

Seth Kartenc37f5eb39fa4
diff --git a/packages/coding-agent/.changes/catalog-metadata-append-without-full-parse.md b/packages/coding-agent/.changes/catalog-metadata-append-without-full-parse.md
new file mode 100644
index 0000000000..01ed649906
--- /dev/null
+++ b/packages/coding-agent/.changes/catalog-metadata-append-without-full-parse.md
@@ -0,0 +1 @@
+- Catalog metadata updates (renaming a saved session, archiving a stopped worker, marking a recovered session interrupted) no longer parse the whole transcript: each appends a single line after validating the session header, so routine actions on multi-MB sessions avoid the full-load stall and memory spike. A missing or header-invalid session file now fails the update with a clear error instead of being recreated or silently rewritten as a fresh session. The interruption notice stays advisory during worker recovery: a notice that cannot be written is logged, and recovery still reaps orphaned processes and resolves its journal.
diff --git a/packages/coding-agent/src/core/session-manager.ts b/packages/coding-agent/src/core/session-manager.ts
index 07d2c54201..87711854c5 100644
--- a/packages/coding-agent/src/core/session-manager.ts
+++ b/packages/coding-agent/src/core/session-manager.ts
@@ -765,6 +765,213 @@ export async function loadEntriesFromFileAsync(
return finalizeLoadedEntries(entries);
}
+// --- Append-only metadata writes for closed sessions -------------------------
+//
+// Catalog metadata operations (rename, archive, mark_interrupted) append a
+// single entry to a file no live session holds. Opening a SessionManager for
+// that parses and indexes the entire transcript — an O(session) stall and a
+// memory spike proportional to session size for every routine UI action. The
+// fast path below reads only a leading header window and a bounded tail window
+// instead, and falls back to a full open whenever those two windows cannot place
+// the entry (a file version this build does not write, a header beyond the
+// window, or a tail too large to resolve the leaf).
+
+const APPEND_HEADER_WINDOW_BYTES = 64 * 1024;
+const APPEND_TAIL_WINDOW_BYTES = 256 * 1024;
+
+/** Ids and timestamps shared by live appends and the append-only fast path. */
+interface AppendEntrySeed {
+ leafId: string | null;
+ newId(): string;
+ timestamp: string;
+}
+
+function buildSessionInfoEntry(name: string, seed: AppendEntrySeed): SessionInfoEntry {
+ return {
+ type: "session_info",
+ id: seed.newId(),
+ parentId: seed.leafId,
+ timestamp: seed.timestamp,
+ name: name.trim(),
+ };
+}
+
+function buildSessionStateEntry(state: SessionState, seed: AppendEntrySeed): SessionStateEntry {
+ return {
+ type: "session_state",
+ id: seed.newId(),
+ parentId: seed.leafId,
+ timestamp: seed.timestamp,
+ state: { status: state.status },
+ };
+}
+
+function buildCustomMessageEntry<T>(
+ customType: string,
+ content: string | (TextContent | ImageContent)[],
+ display: boolean,
+ details: T | undefined,
+ seed: AppendEntrySeed,
+): CustomMessageEntry<T> {
+ return {
+ type: "custom_message",
+ customType,
+ content,
+ display,
+ details,
+ id: seed.newId(),
+ parentId: seed.leafId,
+ timestamp: seed.timestamp,
+ };
+}
+
+/**
+ * First line that parses as JSON in the leading window, mirroring how the
+ * loader skips malformed or blank leading lines. Returns "window-truncated"
+ * when the window held no parseable line but stopped before the end of the
+ * file: a longer leading line may hide the header past it, and only a full
+ * load can tell.
+ */
+function readFirstParseableLine(
+ filePath: string,
+): { type?: unknown; id?: unknown; version?: unknown } | "window-truncated" | undefined {
+ const buffer = readBytesSync(filePath, 0, APPEND_HEADER_WINDOW_BYTES);
+ let start = 0;
+ while (start < buffer.length) {
+ let end = buffer.indexOf(0x0a, start);
+ if (end === -1) end = buffer.length;
+ const line = buffer.subarray(start, end);
+ if (line.length > 0) {
+ try {
+ return JSON.parse(line.toString("utf8")) as { type?: unknown; id?: unknown; version?: unknown };
+ } catch {
+ // Skip malformed or blank lines like appendEntryFromBuffer.
+ }
+ }
+ start = end + 1;
+ }
+ // A window shorter than the cap means the read reached EOF, so the file
+ // really has no parseable leading line.
+ return buffer.length < APPEND_HEADER_WINDOW_BYTES ? undefined : "window-truncated";
+}
+
+/**
+ * Reads a bounded tail window and returns the id of the file's current leaf
+ * entry: the last line that parses as a non-session entry, like _buildIndex
+ * computes on a full load. Returns null for a legacy leaf without an id or a
+ * file without entries, and undefined when the window is too small to decide —
+ * the caller then falls back to a full load.
+ */
+function readTailLeafId(filePath: string, fileSize: number): string | null | undefined {
+ const windowBytes = Math.min(fileSize, APPEND_TAIL_WINDOW_BYTES);
+ const buffer = readBytesSync(filePath, fileSize - windowBytes, fileSize);
+ const lines: Buffer[] = [];
+ let start = 0;
+ while (start < buffer.length) {
+ let end = buffer.indexOf(0x0a, start);
+ if (end === -1) end = buffer.length;
+ lines.push(buffer.subarray(start, end));
+ start = end + 1;
+ }
+ for (let i = lines.length - 1; i >= 0; i--) {
+ const line = lines[i]!;
+ if (line.length === 0) continue;
+ let parsed: { type?: unknown; id?: unknown };
+ try {
+ parsed = JSON.parse(line.toString("utf8")) as { type?: unknown; id?: unknown };
+ } catch {
+ continue;
+ }
+ if (parsed.type === "session") continue;
+ return typeof parsed.id === "string" ? parsed.id : null;
+ }
+ return windowBytes === fileSize ? null : undefined;
+}
+
+/**
+ * Appends one metadata entry to an existing session file without parsing the
+ * transcript. Repairs crash damage like a full open would, validates the
+ * session header, then appends the entry in one line. Throws when the file is
+ * missing or its header is invalid; returns undefined whenever only a full open
+ * can place the entry (an older or newer version, a header beyond the window,
+ * or a tail too large to resolve the leaf), so the caller can fall back.
+ */
+function appendEntryToExistingFile(
+ sessionFile: string,
+ buildEntry: (seed: AppendEntrySeed) => SessionEntry,
+): string | undefined {
+ const targetPath = resolve(sessionFile);
+ if (!existsSync(targetPath)) {
+ throw new Error(`Cannot append to missing session file: ${sessionFile}`);
+ }
+ repairJsonlDamage(targetPath);
+ const header = readFirstParseableLine(targetPath);
+ if (header === "window-truncated") {
+ return undefined;
+ }
+ if (!header || header.type !== "session" || typeof header.id !== "string") {
+ throw new Error(`Session file has no valid session header: ${sessionFile}`);
+ }
+ // Append directly only to a file this build writes: a v1/v2 file needs the
+ // migration a full open performs and may not carry the ids an appended
+ // parentId chains to, and a future version may change the entry shape.
+ if (header.version !== CURRENT_SESSION_VERSION) {
+ return undefined;
+ }
+ const leafId = readTailLeafId(targetPath, statSync(targetPath).size);
+ if (leafId === undefined) {
+ return undefined;
+ }
+ // generateId checks the in-memory entry index, which only a full parse can
+ // build; without it, take generateId's guaranteed-unique fallback form. A
+ // duplicate short id would cycle the leaf-to-root walk in buildSessionContext.
+ const entry = buildEntry({ leafId, newId: () => randomUUID(), timestamp: new Date().toISOString() });
+ mkdirSync(dirname(targetPath), { recursive: true });
+ appendFileSync(targetPath, `${JSON.stringify(entry)}\n`);
+ return entry.id;
+}
+
+/**
+ * Appends a rename (session_info) entry to a closed session file without a
+ * full transcript parse; falls back to opening a SessionManager when only a
+ * full open can place the entry.
+ */
+export function appendSessionInfoToExistingFile(sessionFile: string, name: string): string {
+ const fastId = appendEntryToExistingFile(sessionFile, (seed) => buildSessionInfoEntry(name, seed));
+ return fastId ?? SessionManager.open(sessionFile).appendSessionInfo(name);
+}
+
+/**
+ * Appends a lifecycle (session_state) entry to a closed session file without a
+ * full transcript parse; falls back like appendSessionInfoToExistingFile.
+ */
+export function appendSessionStateToExistingFile(sessionFile: string, state: SessionState): string {
+ const fastId = appendEntryToExistingFile(sessionFile, (seed) => buildSessionStateEntry(state, seed));
+ return fastId ?? SessionManager.open(sessionFile).appendSessionState(state);
+}
+
+/**
+ * Appends a custom message entry to a closed session file without a full
+ * transcript parse; falls back like appendSessionInfoToExistingFile. Unlike a
+ * live append, this writes even when the file has no assistant entry yet:
+ * SessionManager._persist suppresses custom entries until then, which would
+ * drop the notice on the floor for a session whose first reply never landed.
+ * A session that falls back to a full open keeps the full-open behavior: with
+ * no assistant entry, _persist drops the entry and nothing is appended.
+ */
+export function appendCustomMessageToExistingFile<T = unknown>(
+ sessionFile: string,
+ customType: string,
+ content: string | (TextContent | ImageContent)[],
+ display: boolean,
+ details?: T,
+): string {
+ const fastId = appendEntryToExistingFile(sessionFile, (seed) =>
+ buildCustomMessageEntry(customType, content, display, details, seed),
+ );
+ return fastId ?? SessionManager.open(sessionFile).appendCustomMessageEntry(customType, content, display, details);
+}
+
function readSessionHeader(filePath: string): Partial<SessionHeader> | undefined {
const firstLine = readFirstLineSync(filePath);
if (!firstLine) {
@@ -1798,6 +2005,14 @@ export class SessionManager {
}
}
+ private appendEntrySeed(): AppendEntrySeed {
+ return {
+ leafId: this.leafId,
+ newId: () => generateId(this.byId),
+ timestamp: new Date().toISOString(),
+ };
+ }
+
private _appendEntry(entry: SessionEntry): void {
this.fileEntries.push(entry);
if (entry.type === "message" && entry.message.role === "assistant") {
@@ -1931,25 +2146,13 @@ export class SessionManager {
}
appendSessionInfo(name: string): string {
- const entry: SessionInfoEntry = {
- type: "session_info",
- id: generateId(this.byId),
- parentId: this.leafId,
- timestamp: new Date().toISOString(),
- name: name.trim(),
- };
+ const entry = buildSessionInfoEntry(name, this.appendEntrySeed());
this._appendEntry(entry);
return entry.id;
}
appendSessionState(state: SessionState): string {
- const entry: SessionStateEntry = {
- type: "session_state",
- id: generateId(this.byId),
- parentId: this.leafId,
- timestamp: new Date().toISOString(),
- state: { status: state.status },
- };
+ const entry = buildSessionStateEntry(state, this.appendEntrySeed());
this._appendEntry(entry);
return entry.id;
}
@@ -2071,16 +2274,13 @@ export class SessionManager {
display: boolean,
details?: T,
): string {
- const entry: CustomMessageEntry<T> = {
- type: "custom_message",
+ const entry: CustomMessageEntry<T> = buildCustomMessageEntry(
customType,
content,
display,
details,
- id: generateId(this.byId),
- parentId: this.leafId,
- timestamp: new Date().toISOString(),
- };
+ this.appendEntrySeed(),
+ );
this._appendEntry(entry);
return entry.id;
}
diff --git a/packages/coding-agent/src/modes/daemon/daemon-catalog-process.ts b/packages/coding-agent/src/modes/daemon/daemon-catalog-process.ts
index b8fc6e89b8..a549dfafd5 100644
--- a/packages/coding-agent/src/modes/daemon/daemon-catalog-process.ts
+++ b/packages/coding-agent/src/modes/daemon/daemon-catalog-process.ts
@@ -8,7 +8,14 @@ import { createCliSubprocessEnv, createCliSubprocessLaunchSpec } from "../../cli
import { getPackageDir, isBunBinary } from "../../config.js";
import type { DeleteSessionFileResult } from "../../core/session-file-actions.js";
import { deleteSessionFile } from "../../core/session-file-actions.js";
-import { readSessionInfo, type SessionInfo, SessionManager } from "../../core/session-manager.js";
+import {
+ appendCustomMessageToExistingFile,
+ appendSessionInfoToExistingFile,
+ appendSessionStateToExistingFile,
+ readSessionInfo,
+ type SessionInfo,
+ SessionManager,
+} from "../../core/session-manager.js";
import { spawnHidden } from "../../utils/child-process.js";
export const DAEMON_CATALOG_ROLE_ENV = "PRIME_AGENT_INTERNAL_DAEMON_CATALOG";
@@ -194,7 +201,7 @@ async function handleCatalogRequest(request: CatalogRequest): Promise<void> {
throw new Error(`No session found matching '${request.selector}'`);
}
case "rename":
- SessionManager.open(request.sessionPath).appendSessionInfo(request.name.trim());
+ appendSessionInfoToExistingFile(request.sessionPath, request.name.trim());
sendCatalogMessage({ type: "response", id: request.id, success: true });
return;
case "delete":
@@ -217,7 +224,7 @@ async function handleCatalogRequest(request: CatalogRequest): Promise<void> {
return;
}
if (session.state?.status !== "archived") {
- SessionManager.open(request.sessionPath).appendSessionState({ status: "archived" });
+ appendSessionStateToExistingFile(request.sessionPath, { status: "archived" });
}
sendCatalogMessage({
type: "response",
@@ -228,7 +235,8 @@ async function handleCatalogRequest(request: CatalogRequest): Promise<void> {
return;
}
case "mark_interrupted":
- SessionManager.open(request.sessionPath).appendCustomMessageEntry(
+ appendCustomMessageToExistingFile(
+ request.sessionPath,
"prime-agent.worker_recovery",
"<prime_agent_worker_interrupted>\nThe isolated session worker stopped during in-flight work. The saved transcript was recovered, but uncertain model, tool, bash, or child-agent work was not replayed. Inspect external side effects before continuing.\n</prime_agent_worker_interrupted>",
false,
diff --git a/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts b/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts
index 6f506571ea..03923f64e8 100644
--- a/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts
+++ b/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts
@@ -4287,11 +4287,19 @@ export class DaemonSupervisor {
throw new SupervisorRecoveryCancelledError("Worker recovery was cancelled before interruption was recorded");
}
await Promise.all(
- [...interruptedSessions.values()].map((interrupted) =>
- this.catalog.markInterrupted(interrupted.sessionFile, interrupted.activeSessionId, [
- ...interrupted.operations,
- ]),
- ),
+ [...interruptedSessions.values()].map(async (interrupted) => {
+ try {
+ await this.catalog.markInterrupted(interrupted.sessionFile, interrupted.activeSessionId, [
+ ...interrupted.operations,
+ ]);
+ } catch (error) {
+ // The notice is advisory: an unwritable session file must not abort
+ // the orphan reap, the journal resolution, or the recovery retry.
+ this.log(
+ `Could not record the interrupted session notice for ${interrupted.sessionFile}: ${String(error)}`,
+ );
+ }
+ }),
);
await this.assertRecoveryAllowed();
if (this.isWorkerCleanupCancelled(worker)) {
diff --git a/packages/coding-agent/test/daemon-supervisor-monitor.test.ts b/packages/coding-agent/test/daemon-supervisor-monitor.test.ts
index be84102de7..a368442214 100644
--- a/packages/coding-agent/test/daemon-supervisor-monitor.test.ts
+++ b/packages/coding-agent/test/daemon-supervisor-monitor.test.ts
@@ -4161,65 +4161,90 @@ describe("daemon worker supervisor monitoring", () => {
expect(client.attachedActiveSessionIds).toEqual(new Set());
});
- it("marks each busy worker session interrupted independently", async () => {
- type RecoveryWorker = {
- descriptor: {
- workerId: string;
- pid: number;
- rootActiveSessionId: string;
- recoveryJournalPath: string;
- orphanProcessJournalPath: string;
- };
+ /** Shared recovery fixture inputs for the tests below. */
+ type RecoveryWorker = {
+ descriptor: {
+ workerId: string;
+ pid: number;
+ rootActiveSessionId: string;
+ recoveryJournalPath: string;
+ orphanProcessJournalPath: string;
};
+ };
+
+ function recoveryFixture(options: {
+ sessions?: Array<{ activeSessionId: string; sessionFile: string; operation: string }>;
+ workerPid?: number;
+ orphan?: { pid: number; processStartId?: string };
+ }): { root: string; worker: RecoveryWorker; recoveryJournalPath: string; orphanJournalPath: string } {
const root = mkdtempSync(join(tmpdir(), "prime-supervisor-recovery-test-"));
- const journalPath = join(root, "worker.recovery.jsonl");
+ const workerPid = options.workerPid ?? process.pid;
const orphanJournalPath = join(root, "worker.orphans.jsonl");
- writeFileSync(
+ if (options.orphan)
+ writeFileSync(
+ orphanJournalPath,
+ `${JSON.stringify({ version: 1, pid: options.orphan.pid, ownerPid: workerPid, ...(options.orphan.processStartId && { processStartId: options.orphan.processStartId }), active: true, recordedAt: new Date().toISOString() })}\n`,
+ );
+ const recoveryJournalPath = join(root, "worker.recovery.jsonl");
+ const journal = new WorkerRecoveryJournal(recoveryJournalPath);
+ for (const session of options.sessions ?? []) {
+ journal.record({
+ activeSessionId: session.activeSessionId,
+ sessionId: `${session.activeSessionId}-session`,
+ sessionFile: session.sessionFile,
+ busy: true,
+ operation: session.operation,
+ });
+ }
+ return {
+ root,
+ recoveryJournalPath,
orphanJournalPath,
- `${JSON.stringify({
- version: 1,
- pid: 987_654,
- ownerPid: process.pid,
- processStartId: "reused-process",
- active: true,
- recordedAt: new Date().toISOString(),
- })}\n`,
- );
- const journal = new WorkerRecoveryJournal(journalPath);
- journal.record({
- activeSessionId: "root-active",
- sessionId: "root-session",
- sessionFile: "/tmp/root.jsonl",
- busy: true,
- operation: "model_stream",
- });
- journal.record({
- activeSessionId: "child-active",
- sessionId: "child-session",
- sessionFile: "/tmp/child.jsonl",
- busy: true,
- operation: "tool_execution",
- });
- const worker: RecoveryWorker = {
- descriptor: {
- workerId: "worker-1",
- pid: process.pid,
- rootActiveSessionId: "root-active",
- recoveryJournalPath: journalPath,
- orphanProcessJournalPath: orphanJournalPath,
+ worker: {
+ descriptor: {
+ workerId: "worker-recovery",
+ pid: workerPid,
+ rootActiveSessionId: options.sessions?.[0]?.activeSessionId ?? "root-active",
+ recoveryJournalPath,
+ orphanProcessJournalPath: orphanJournalPath,
+ },
},
};
- const markInterrupted = vi.fn(async () => undefined);
- const kill = vi.spyOn(process, "kill").mockReturnValue(true);
+ }
+
+ function recoverySupervisor(
+ worker: RecoveryWorker,
+ catalog: { start?: () => Promise<void>; markInterrupted?: () => Promise<void> } = {},
+ ): {
+ supervisor: { recoverUncertainWorkerOperations(target: RecoveryWorker): Promise<void> };
+ log: ReturnType<typeof vi.fn>;
+ } {
+ const log = vi.fn();
const supervisor = Object.assign(Object.create(DaemonSupervisor.prototype), {
workers: new Map([[worker.descriptor.workerId, worker]]),
shuttingDown: false,
- catalog: { start: vi.fn(async () => undefined), markInterrupted },
- log: vi.fn(),
- assertRecoveryAllowed: vi.fn(async () => {}),
- }) as {
- recoverUncertainWorkerOperations(worker: RecoveryWorker): Promise<void>;
- };
+ catalog: {
+ start: catalog.start ?? vi.fn(async () => undefined),
+ markInterrupted: catalog.markInterrupted ?? vi.fn(async () => undefined),
+ },
+ log,
+ assertRecoveryAllowed: vi.fn(async () => undefined),
+ }) as { recoverUncertainWorkerOperations(target: RecoveryWorker): Promise<void> };
+ return { supervisor, log };
+ }
+
+ it("marks each busy worker session interrupted independently", async () => {
+ // A stale pid whose journaled start id no longer matches is left alone.
+ const { root, worker } = recoveryFixture({
+ sessions: [
+ { activeSessionId: "root-active", sessionFile: "/tmp/root.jsonl", operation: "model_stream" },
+ { activeSessionId: "child-active", sessionFile: "/tmp/child.jsonl", operation: "tool_execution" },
+ ],
+ orphan: { pid: 987_654, processStartId: "reused-process" },
+ });
+ const markInterrupted = vi.fn(async () => undefined);
+ const kill = vi.spyOn(process, "kill").mockReturnValue(true);
+ const { supervisor } = recoverySupervisor(worker, { markInterrupted });
try {
await supervisor.recoverUncertainWorkerOperations(worker);
@@ -4291,26 +4316,11 @@ describe("daemon worker supervisor monitoring", () => {
});
it("skips catalog startup when recovery has no interrupted operations", async () => {
- const root = mkdtempSync(join(tmpdir(), "prime-supervisor-empty-recovery-test-"));
- const worker = {
- descriptor: {
- workerId: "worker-empty-recovery",
- pid: 987_654,
- rootActiveSessionId: "root-active",
- recoveryJournalPath: join(root, "worker.recovery.jsonl"),
- },
- };
+ const { root, worker } = recoveryFixture({});
const catalogStart = vi.fn(async () => {
throw new Error("catalog unavailable");
});
- const supervisor = Object.assign(Object.create(DaemonSupervisor.prototype), {
- workers: new Map([[worker.descriptor.workerId, worker]]),
- shuttingDown: false,
- catalog: { start: catalogStart, markInterrupted: vi.fn() },
- assertRecoveryAllowed: vi.fn(async () => undefined),
- }) as {
- recoverUncertainWorkerOperations(target: typeof worker): Promise<void>;
- };
+ const { supervisor } = recoverySupervisor(worker, { start: catalogStart });
try {
await expect(supervisor.recoverUncertainWorkerOperations(worker)).resolves.toBeUndefined();
@@ -4321,54 +4331,18 @@ describe("daemon worker supervisor monitoring", () => {
});
it("does not reap interrupted worker resources before the catalog is ready", async () => {
- const root = mkdtempSync(join(tmpdir(), "prime-supervisor-catalog-readiness-test-"));
- const recoveryJournalPath = join(root, "worker.recovery.jsonl");
- const orphanJournalPath = join(root, "worker.orphans.jsonl");
- const workerPid = 987_654;
- new WorkerRecoveryJournal(recoveryJournalPath).record({
- activeSessionId: "root-active",
- sessionId: "root-session",
- sessionFile: "/tmp/root.jsonl",
- busy: true,
- operation: "model_stream",
+ const { root, worker, orphanJournalPath } = recoveryFixture({
+ sessions: [{ activeSessionId: "root-active", sessionFile: "/tmp/root.jsonl", operation: "model_stream" }],
+ workerPid: 987_654,
+ orphan: { pid: process.pid, processStartId: getProcessStartId(process.pid) },
});
- writeFileSync(
- orphanJournalPath,
- `${JSON.stringify({
- version: 1,
- pid: process.pid,
- ownerPid: workerPid,
- processStartId: getProcessStartId(process.pid),
- active: true,
- recordedAt: new Date().toISOString(),
- })}
-`,
- );
- const worker = {
- descriptor: {
- workerId: "worker-catalog-blocked",
- pid: workerPid,
- rootActiveSessionId: "root-active",
- recoveryJournalPath,
- orphanProcessJournalPath: orphanJournalPath,
- },
- intentionalStop: false,
- };
const catalogError = new Error("Timed out starting daemon catalog");
const kill = vi.spyOn(orphanProcessModule, "killOrphanProcess").mockReturnValue(true);
- const supervisor = Object.assign(Object.create(DaemonSupervisor.prototype), {
- workers: new Map([[worker.descriptor.workerId, worker]]),
- shuttingDown: false,
- catalog: {
- start: vi.fn(async () => {
- throw catalogError;
- }),
- markInterrupted: vi.fn(),
- },
- assertRecoveryAllowed: vi.fn(async () => {}),
- }) as {
- recoverUncertainWorkerOperations(target: typeof worker): Promise<void>;
- };
+ const { supervisor } = recoverySupervisor(worker, {
+ start: vi.fn(async () => {
+ throw catalogError;
+ }),
+ });
try {
await expect(supervisor.recoverUncertainWorkerOperations(worker)).rejects.toThrow(catalogError);
diff --git a/packages/coding-agent/test/session-manager/append-to-existing-file.test.ts b/packages/coding-agent/test/session-manager/append-to-existing-file.test.ts
new file mode 100644
index 0000000000..0375121f9e
--- /dev/null
+++ b/packages/coding-agent/test/session-manager/append-to-existing-file.test.ts
@@ -0,0 +1,148 @@
+import { type appendFileSync, mkdtempSync, type readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+type AppendFileSync = typeof appendFileSync;
+type ReadFileSync = typeof readFileSync;
+
+const fsMocks = vi.hoisted(() => ({ appendFileSync: vi.fn<AppendFileSync>(), readFileSync: vi.fn<ReadFileSync>() }));
+
+// Passthrough spies: real fs behavior everywhere, with call counts on the two calls that tell a full parse (readFileSync) from an append.
+vi.mock("node:fs", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("node:fs")>();
+ fsMocks.appendFileSync.mockImplementation(actual.appendFileSync);
+ fsMocks.readFileSync.mockImplementation(actual.readFileSync);
+ return { ...actual, appendFileSync: fsMocks.appendFileSync, readFileSync: fsMocks.readFileSync };
+});
+
+import { appendCustomMessageToExistingFile, appendSessionInfoToExistingFile } from "../../src/core/session-manager.js";
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+ while (tempDirs.length > 0) rmSync(tempDirs.pop()!, { recursive: true, force: true });
+});
+
+function tempDir(prefix = "pi-session-append-"): string {
+ const dir = mkdtempSync(join(tmpdir(), prefix));
+ tempDirs.push(dir);
+ return dir;
+}
+
+/** Header plus a chained user-message transcript, shaped like a real session file. */
+function sessionLines(dir: string, options: { entries?: number; textBytes?: number } = {}): string[] {
+ const count = options.entries ?? 4;
+ const lines = [
+ JSON.stringify({
+ type: "session",
+ version: 3,
+ id: "fixture-session",
+ timestamp: "2026-01-01T00:00:00.000Z",
+ cwd: dir,
+ }),
+ ];
+ let parentId: string | null = null;
+ for (let i = 0; i < count; i++) {
+ const id = `e${i}`;
+ const timestamp = 1_767_225_600_000 + i;
+ const text = options.textBytes !== undefined && i === count - 1 ? "x".repeat(options.textBytes) : `payload ${i}`;
+ lines.push(
+ JSON.stringify({
+ type: "message",
+ id,
+ parentId,
+ timestamp: new Date(timestamp).toISOString(),
+ message: { role: "user", content: text, timestamp },
+ }),
+ );
+ parentId = id;
+ }
+ return lines;
+}
+
+function writeSession(dir: string, name: string, lines: string[], terminate = true): string {
+ const file = join(dir, name);
+ writeFileSync(file, lines.join("\n") + (terminate ? "\n" : ""));
+ return file;
+}
+
+function resetIo(): void {
+ fsMocks.appendFileSync.mockClear();
+ fsMocks.readFileSync.mockClear();
+}
+
+function rawFile(file: string): Buffer {
+ return fsMocks.readFileSync(file) as unknown as Buffer;
+}
+
+/** The bytes appended to `file` since `before`, parsed as JSON. */
+function appended(before: Buffer, file: string): Record<string, unknown> {
+ const bytes = rawFile(file).subarray(before.length).toString("utf8");
+ expect(bytes.endsWith("\n")).toBe(true);
+ return JSON.parse(bytes.trim());
+}
+
+describe("append metadata to an existing session file", () => {
+ it("appends a rename line without reading or parsing the whole transcript", () => {
+ const dir = tempDir();
+ const file = writeSession(dir, "rename-fast.jsonl", sessionLines(dir, { entries: 18_000 }));
+ const before = rawFile(file);
+ expect(before.length).toBeGreaterThan(1_000_000); // big enough that a full parse would show
+
+ resetIo();
+ appendSessionInfoToExistingFile(file, " Renamed ");
+
+ expect(fsMocks.readFileSync).not.toHaveBeenCalled(); // no full-file read or parse
+ expect(fsMocks.appendFileSync).toHaveBeenCalledTimes(1); // exactly one appended line
+ expect(appended(before, file)).toMatchObject({ type: "session_info", name: "Renamed", parentId: "e17999" });
+ });
+
+ it("falls back to a full open whenever only a full open can place the entry", () => {
+ // A v1 file: the open migrates it and assigns the ids an appended parentId chains to.
+ const dir = tempDir();
+ const file = writeSession(dir, "v1.jsonl", [
+ JSON.stringify({ type: "session", id: "legacy", timestamp: "2026-01-01T00:00:00.000Z", cwd: dir }),
+ ...sessionLines(dir, { entries: 2 }),
+ ]);
+ resetIo();
+ appendSessionInfoToExistingFile(file, "Renamed");
+ expect(fsMocks.readFileSync).toHaveBeenCalled(); // the full open parsed the transcript
+ const lines = rawFile(file).toString("utf8").trimEnd().split("\n");
+ expect(JSON.parse(lines.at(-1)!)).toMatchObject({ type: "session_info", name: "Renamed" });
+ expect(JSON.parse(lines[0]!).version).toBe(3); // the migration rewrote what it read
+
+ // An oversized tail with no assistant entry: the window cannot resolve the leaf, and the fallback's live manager suppresses the notice.
+ const noticeFile = writeSession(
+ dir,
+ "fallback-notice.jsonl",
+ sessionLines(dir, { entries: 3, textBytes: 300_000 }),
+ );
+ const noticeBefore = rawFile(noticeFile);
+ resetIo();
+ appendCustomMessageToExistingFile(noticeFile, "prime-agent.worker_recovery", "worker interrupted", false, {
+ activeSessionId: "active-1",
+ });
+ expect(fsMocks.readFileSync).toHaveBeenCalled(); // the tail window could not resolve the leaf
+ expect(fsMocks.appendFileSync).not.toHaveBeenCalled();
+ expect(rawFile(noticeFile).equals(noticeBefore)).toBe(true);
+ });
+
+ it("fails cleanly instead of recreating a missing or header-invalid session file", () => {
+ const dir = tempDir();
+ // No session header at all: the leading line is malformed and the rest are entries.
+ const invalid = writeSession(dir, "invalid.jsonl", [
+ "not json at all",
+ ...sessionLines(dir, { entries: 2 }).slice(1),
+ ]);
+ const contents = rawFile(invalid).toString("utf8");
+
+ resetIo();
+ expect(() => appendSessionInfoToExistingFile(join(dir, "missing.jsonl"), "Renamed")).toThrow(
+ /missing session file/,
+ );
+ expect(() => appendSessionInfoToExistingFile(invalid, "Renamed")).toThrow(/no valid session header/);
+ expect(fsMocks.appendFileSync).not.toHaveBeenCalled(); // nothing created, appended, or rewritten
+ expect(rawFile(invalid).toString("utf8")).toBe(contents);
+ });
+});