fix(server): retain restart-safe images with async processing

Integrate current main while preserving stable attachment storage, async materialization, bounded decoding and atomic publication. Adapt the restart regression and private-storage tests to the asynchronous API and isolate all materialization tests from the real home.

packages/server/src/server/agent/providers/provider-image-output.posix.test.ts

@@ -1,24 +1,46 @@
-import { existsSync, rmSync, statSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
-import { describe, expect, test } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
-import { materializeProviderImage } from "./provider-image-output.js";
+let materializeProviderImage: typeof import("./provider-image-output.js").materializeProviderImage;
 
 describe.skipIf(process.platform === "win32")("materializeProviderImage", () => {
-  test("writes image attachments under a private temp directory", async () => {
+  const originalPaseoHome = process.env.PASEO_HOME;
+  let testHome: string | null = null;
+
+  beforeEach(async () => {
+    testHome = mkdtempSync(path.join(os.tmpdir(), "paseo-provider-images-posix-"));
+    process.env.PASEO_HOME = testHome;
+    vi.resetModules();
+    ({ materializeProviderImage } = await import("./provider-image-output.js"));
+  });
+
+  afterEach(() => {
+    if (originalPaseoHome === undefined) {
+      delete process.env.PASEO_HOME;
+    } else {
+      process.env.PASEO_HOME = originalPaseoHome;
+    }
+    if (testHome) {
+      rmSync(testHome, { recursive: true, force: true });
+      testHome = null;
+    }
+  });
+
+  test("writes image attachments under a private directory in the paseo home", async () => {
     const materialized = await materializeProviderImage({
       data: "YWJjMTIz",
       mimeType: "image/png",
     });
     const attachmentDir = path.dirname(materialized.path);
 
-    try {
-      expect(path.basename(attachmentDir)).toMatch(/^paseo-attachments-/);
-      expect(existsSync(materialized.path)).toBe(true);
-      expect(statSync(attachmentDir).mode & 0o777).toBe(0o700);
-      expect(statSync(materialized.path).mode & 0o777).toBe(0o600);
-    } finally {
-      rmSync(attachmentDir, { recursive: true, force: true });
-    }
+    // Exactly "paseo-attachments" — no mkdtemp suffix. The old per-process temp
+    // directory is what let the OS reap these images out from under the app.
+    expect(path.basename(attachmentDir)).toBe("paseo-attachments");
+    expect(attachmentDir).toBe(path.join(testHome as string, "paseo-attachments"));
+    expect(existsSync(materialized.path)).toBe(true);
+    expect(statSync(attachmentDir).mode & 0o777).toBe(0o700);
+    expect(statSync(materialized.path).mode & 0o777).toBe(0o600);
   });
 });

packages/server/src/server/agent/providers/provider-image-output.test.ts

@@ -1,18 +1,45 @@
-import { existsSync, rmSync, statSync, readFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  utimesSync,
+  statSync,
+  readFileSync,
+} from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import MarkdownIt from "markdown-it";
 import { projectTimelineRows } from "../timeline-projection.js";
-import { describe, expect, test } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
 import {
   MAX_PROVIDER_IMAGE_BYTES,
   isProviderImageMarkdown,
-  materializeProviderImage,
   renderProviderImageOutputAsAssistantMarkdown,
 } from "./provider-image-output.js";
 
 const HASH = "a".repeat(64);
 
+// Materialized images live under the paseo home now, so without this every test
+// run would read and delete the developer's real provider images.
+const originalPaseoHome = process.env.PASEO_HOME;
+let testHome: string | null = null;
+let materializeProviderImage: typeof import("./provider-image-output.js").materializeProviderImage;
+
+function useTempPaseoHome(): string {
+  testHome = mkdtempSync(path.join(os.tmpdir(), "paseo-provider-images-"));
+  process.env.PASEO_HOME = testHome;
+  return testHome;
+}
+
+function attachmentsDir(): string {
+  if (!testHome) {
+    throw new Error("useTempPaseoHome() must run before reading the attachments dir.");
+  }
+  return path.join(testHome, "paseo-attachments");
+}
+
 async function renderImageMarkdown(imagePath: string): Promise<string> {
   const item = await renderProviderImageOutputAsAssistantMarkdown({ path: imagePath });
   if (!item || item.type !== "assistant_message") {
@@ -94,28 +121,95 @@ describe("isProviderImageMarkdown", () => {
   });
 });
 
+beforeEach(async () => {
+  useTempPaseoHome();
+  vi.resetModules();
+  ({ materializeProviderImage } = await import("./provider-image-output.js"));
+});
+
+afterEach(() => {
+  if (originalPaseoHome === undefined) {
+    delete process.env.PASEO_HOME;
+  } else {
+    process.env.PASEO_HOME = originalPaseoHome;
+  }
+  if (testHome) {
+    rmSync(testHome, { recursive: true, force: true });
+    testHome = null;
+  }
+});
+
 describe("materializeProviderImage", () => {
-  test("recreates the private temp directory if the cached directory is removed", async () => {
+  test("recreates the private directory if the cached directory is removed", async () => {
     const first = await materializeProviderImage({
       data: "YWJjMTIz",
       mimeType: "image/png",
     });
-    const firstDir = path.dirname(first.path);
     expect(existsSync(first.path)).toBe(true);
 
-    rmSync(firstDir, { recursive: true, force: true });
+    rmSync(path.dirname(first.path), { recursive: true, force: true });
 
     const second = await materializeProviderImage({
       data: "ZGVmNDU2",
       mimeType: "image/png",
     });
-    const secondDir = path.dirname(second.path);
 
-    try {
-      expect(existsSync(second.path)).toBe(true);
-    } finally {
-      rmSync(secondDir, { recursive: true, force: true });
+    expect(existsSync(second.path)).toBe(true);
+  });
+
+  test("stores images in a stable directory under the paseo home", async () => {
+    const result = await materializeProviderImage({ data: "YWJjMTIz", mimeType: "image/png" });
+
+    // A fixed directory, not a per-process mkdtemp one — the old shape is what
+    // let the OS reap these images out from under the app after ~3 days.
+    expect(path.dirname(result.path)).toBe(attachmentsDir());
+    expect(path.basename(path.dirname(result.path))).toBe("paseo-attachments");
+    // Mode assertions live in the .posix suite: Windows ignores mkdir/writeFile
+    // modes and reports 0o666, so asserting them here fails on that runner.
+  });
+
+  test("is idempotent for the same bytes across daemon restarts", async () => {
+    const first = await materializeProviderImage({ data: "YWJjMTIz", mimeType: "image/png" });
+
+    // Reload the module while retaining the files from the previous instance.
+    vi.resetModules();
+    const restarted = await import("./provider-image-output.js");
+    const second = await restarted.materializeProviderImage({
+      data: "YWJjMTIz",
+      mimeType: "image/png",
+    });
+
+    expect(second.path).toBe(first.path);
+    expect(readdirSync(attachmentsDir())).toHaveLength(1);
+  });
+
+  test("emits markdown that isProviderImageMarkdown still recognizes", async () => {
+    const item = await renderProviderImageOutputAsAssistantMarkdown(
+      { data: "YWJjMTIz", mimeType: "image/png" },
+      { materialize: materializeProviderImage },
+    );
+
+    if (!item || item.type !== "assistant_message") {
+      throw new Error("Expected provider image output to render as assistant markdown.");
     }
+    expect(isProviderImageMarkdown(item.text)).toBe(true);
+  });
+
+  // The whole point of moving out of the temp dir is that nothing deletes these
+  // behind the user's back. An age-based sweep would reintroduce that on a
+  // longer fuse, because mtime cannot tell a referenced image from an abandoned
+  // one and reading a transcript never touches the file.
+  test("keeps images no matter how old they are", async () => {
+    const image = await materializeProviderImage({ data: "YWJjMTIz", mimeType: "image/png" });
+    const longAgoSeconds = Date.now() / 1000 - 365 * 24 * 60 * 60;
+    utimesSync(image.path, longAgoSeconds, longAgoSeconds);
+
+    // Reloading the module must not sweep images referenced by older transcripts.
+    vi.resetModules();
+    const restarted = await import("./provider-image-output.js");
+    await restarted.materializeProviderImage({ data: "Z2hpNzg5", mimeType: "image/png" });
+
+    expect(existsSync(image.path)).toBe(true);
   });
 });
 

packages/server/src/server/agent/providers/provider-image-output.ts

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import { setImmediate } from "node:timers/promises";
-import os from "node:os";
 import path from "node:path";
 
 import type { AgentTimelineItem } from "../agent-sdk-types.js";
+import { resolvePaseoHome } from "../../paseo-home.js";
 
 export interface ProviderImageOutput {
   path?: string | null;
@@ -18,11 +18,13 @@ export interface MaterializedProviderImage {
   path: string;
 }
 
+// Keep this basename compatible with provider-image Markdown in existing timelines.
 const PROVIDER_IMAGE_ATTACHMENT_DIR = "paseo-attachments";
-const PROVIDER_IMAGE_ATTACHMENT_DIR_PREFIX = `${PROVIDER_IMAGE_ATTACHMENT_DIR}-`;
 const PRIVATE_ATTACHMENT_DIR_MODE = 0o700;
 const MATERIALIZED_IMAGE_FILE_MODE = 0o600;
 
+// Persist images across process lifetimes. Age-based cleanup would delete files
+// still referenced by transcripts; any future cleanup must account for references.
 let materializedImageAttachmentDir: string | null = null;
 // Serialize materializations: one decoder and one file operation at a time, including
 // concurrent history replay and live turns. A rejected operation must not poison the queue.
@@ -37,14 +39,14 @@ async function getMaterializedImageAttachmentDir(): Promise<string> {
         return materializedImageAttachmentDir;
       }
     } catch {
-      /* Temp storage may have been removed between turns. */
+      /* Attachment storage may have been removed between turns. */
     }
   }
-  materializedImageAttachmentDir = await fs.mkdtemp(
-    path.join(os.tmpdir(), PROVIDER_IMAGE_ATTACHMENT_DIR_PREFIX),
-  );
-  await fs.chmod(materializedImageAttachmentDir, PRIVATE_ATTACHMENT_DIR_MODE);
-  return materializedImageAttachmentDir;
+  const dir = path.join(resolvePaseoHome(), PROVIDER_IMAGE_ATTACHMENT_DIR);
+  await fs.mkdir(dir, { recursive: true, mode: PRIVATE_ATTACHMENT_DIR_MODE });
+  await fs.chmod(dir, PRIVATE_ATTACHMENT_DIR_MODE);
+  materializedImageAttachmentDir = dir;
+  return dir;
 }
 
 function getImageExtension(mimeType: string): string {
@@ -71,6 +73,7 @@ function getImageExtension(mimeType: string): string {
 export const MAX_PROVIDER_IMAGE_BYTES = 128 * 1024 * 1024;
 const BASE64_CHUNK_CHARACTERS = 256 * 1024; // Multiple of four; decode units stay aligned.
 
+// Content-addressed filenames deduplicate repeated image bytes across restarts.
 export function materializeProviderImage(image: {
   data: string;
   mimeType: string | null;