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.mdnew file mode 100644index 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.tsindex 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.tsindex 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 "../../cliimport { 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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);+ });+});