mulmoclaude 2.9.0 → 2.10.0

package/server/index.ts

@@ -104,7 +104,7 @@ import { initCollectionChangePublisher } from "./events/collection-change.js";
 import { initPhotoLocationsChangePublisher } from "./events/photo-locations-change.js";
 import { getRole, loadAllRoles } from "./workspace/roles.js";
 import { discoverSkills } from "./workspace/skills/index.js";
-import { WORKSPACE_PATHS } from "./workspace/paths.js";
+import { WORKSPACE_DIRS, WORKSPACE_PATHS } from "./workspace/paths.js";
 import { resolveClientDir } from "./utils/clientDir.js";
 import { serverError } from "./utils/httpError.js";
 import { browserVisibleOrigin } from "./utils/forwardedOrigin.js";
@@ -121,7 +121,8 @@ import { buildSandboxStatus } from "./api/sandboxStatus.js";
 import { buildDiagnosticsMarkdown } from "./utils/diagnostics/collect.js";
 import { existsSync, readFileSync } from "fs";
 import { realpath as fsRealpath, stat as fsStat } from "fs/promises";
-import { makeCachedRealpath, resolveArtifactRequestPath } from "./utils/files/safe.js";
+import { makeCachedRealpath } from "./utils/files/safe.js";
+import { artifactMount, sendArtifactFile } from "./utils/files/artifactMount.js";
 import { cpus, loadavg } from "os";
 import { isDockerAvailable, ensureSandboxImage } from "./system/docker.js";
 import { maybeRunJournal } from "./workspace/journal/index.js";
@@ -387,7 +388,7 @@ app.use("/api", (req, res, next) => {
 // requireSameOrigin guard above still applies; the listener also
 // stays loopback-only.
 //
-// Three-layer guard:
+// Guard:
 //  1. Extension allowlist — reject anything that isn't an image,
 //     video, or audio extension. `saveImage` currently writes `.png`
 //     only, but Stage B (#1011) extends the markdown / wiki rewriter
@@ -396,36 +397,14 @@ app.use("/api", (req, res, next) => {
 //     `artifacts/images/<id>.mp4` (or any user-dropped media file
 //     under that dir) needs to round-trip through this mount the
 //     same way image refs do — otherwise the rewritten URL hits this
-//     mount and 404s before `express.static` gets a chance.
-//  2. realpath-based traversal check via `resolveWithinRoot` — same
-//     guard `/api/files/raw` uses. Catches symlinks pointing outside
-//     the images dir, which `express.static` would otherwise follow.
-//  3. `dotfiles: deny` + `fallthrough: false` on `express.static`
-//     itself, plus its built-in `..` normalize for path traversal.
+//     mount and 404s.
+//  2. `artifactMount` (server/utils/files/artifactMount.ts): the mount
+//     folder must resolve inside the workspace on every request,
+//     dotfile / traversal segments are refused, and the file is served
+//     from a handle verified to be the in-folder file — never re-opened
+//     by path, so a symlink swapped in mid-request is not followed.
 const IMAGE_EXT_RE = /\.(png|jpe?g|webp|gif|svg|mp4|webm|mov|m4v|ogv|mp3|ogg|oga|wav|m4a|aac)$/i;
-const getImagesDirReal = makeCachedRealpath(WORKSPACE_PATHS.images);
-app.use(
-  "/artifacts/images",
-  async (req, res, next) => {
-    if (!IMAGE_EXT_RE.test(req.path)) {
-      res.status(404).end();
-      return;
-    }
-    const root = await getImagesDirReal();
-    if (!root) {
-      res.status(404).end();
-      return;
-    }
-    // No explicit dotfile check here: this mount never short-circuits,
-    // so `express.static`'s `dotfiles: "deny"` below is the authority.
-    if (resolveArtifactRequestPath(root, req.path, false) === null) {
-      res.status(404).end();
-      return;
-    }
-    next();
-  },
-  express.static(WORKSPACE_PATHS.images, { dotfiles: "deny", fallthrough: false }),
-);
+app.use("/artifacts/images", artifactMount(workspacePath, WORKSPACE_DIRS.images, IMAGE_EXT_RE));
 
 // Static mount for HTML artifacts. The Files-view preview iframe
 // switched from `srcdoc` to `src=/artifacts/html/<name>.html` so the
@@ -444,10 +423,7 @@ app.use(
 // (`previewCsp.ts`) so allowing those extensions would only delivery-
 // vector for blocked resources.
 //
-// Same three-layer guard as `/artifacts/images`:
-//  1. extension allowlist (`.html` / `.htm` plus image types).
-//  2. `resolveWithinRoot` symlink-aware traversal check.
-//  3. `dotfiles: deny` + `fallthrough: false` on `express.static`.
+// Same guard as `/artifacts/images` (extension allowlist + `artifactMount`).
 //
 // Bearer auth skipped for the same reason as /artifacts/images and
 // /api/files/*: an iframe `src` request can't carry an Authorization
@@ -474,47 +450,23 @@ app.use(
 // eslint-disable-next-line sonarjs/regex-complexity -- flat extension allowlist with no nested quantifiers, ReDoS-safe; complexity is just the disjunction count
 const HTML_PREVIEW_EXT_RE = /\.(html?|png|jpe?g|webp|gif|svg|ico|mp4|webm|mov|m4v|ogv|mp3|ogg|oga|wav|m4a|aac)$/i;
 const HTML_DOCUMENT_EXT_RE = /\.html?$/i;
-const getHtmlsDirReal = makeCachedRealpath(WORKSPACE_PATHS.htmls);
-
 app.use(
   "/artifacts/html",
-  async (req, res, next) => {
-    if (!HTML_PREVIEW_EXT_RE.test(req.path)) {
-      res.status(404).end();
-      return;
-    }
-    const root = await getHtmlsDirReal();
-    if (!root) {
-      res.status(404).end();
+  artifactMount(workspacePath, WORKSPACE_DIRS.htmls, HTML_PREVIEW_EXT_RE, async (req, res, scope, relPath) => {
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    if (!HTML_DOCUMENT_EXT_RE.test(req.path)) {
+      await sendArtifactFile(req, res, scope, relPath);
       return;
     }
-    // denyDotfiles: the HTML short-circuit below serves the file itself
-    // (bypassing `express.static`'s `dotfiles: "deny"`), so this mount
-    // must reject dotfile segments in the guard — without it,
-    // `/artifacts/html/.hidden.html` would be served (Codex review on
-    // #1056).
-    const relPath = resolveArtifactRequestPath(root, req.path, true);
-    if (relPath === null) {
+    res.setHeader("Content-Security-Policy", buildHtmlPreviewCsp(browserVisibleOrigin(req), undefined, readCspExtraSync()));
+    const spliced = await readAndInjectHtmlArtifact(scope, relPath);
+    if (spliced === null) {
       res.status(404).end();
       return;
     }
-    if (HTML_DOCUMENT_EXT_RE.test(req.path)) {
-      const origin = browserVisibleOrigin(req);
-      res.setHeader("Content-Security-Policy", buildHtmlPreviewCsp(origin, undefined, readCspExtraSync()));
-      res.setHeader("X-Content-Type-Options", "nosniff");
-      const spliced = await readAndInjectHtmlArtifact(root, relPath);
-      if (spliced === null) {
-        res.status(404).end();
-        return;
-      }
-      res.setHeader("Content-Type", "text/html; charset=utf-8");
-      res.send(spliced);
-      return;
-    }
-    res.setHeader("X-Content-Type-Options", "nosniff");
-    next();
-  },
-  express.static(WORKSPACE_PATHS.htmls, { dotfiles: "deny", fallthrough: false }),
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.send(spliced);
+  }),
 );
 
 // Mount for HTML pages OUTSIDE `artifacts/html/` — presentHtml's `path` form
@@ -601,39 +553,20 @@ app.use(HTML_FILE_MOUNT, htmlFileRateLimit, async (req, res, next) => {
 // header doesn't interfere with the normal View / Preview path.
 const SVG_RESPONSE_CSP = "default-src 'none'; style-src 'unsafe-inline'; img-src 'self' data:; sandbox";
 
-// Strict three-layer guard mirroring the `/artifacts/images` mount:
-// extension allowlist, realpath traversal check, dotfiles deny +
-// fallthrough false on `express.static`. Bearer auth bypassed for the
+// Same guard as `/artifacts/images` (extension allowlist + `artifactMount`).
+// Bearer auth bypassed for the
 // same reason as `/artifacts/images` / `/artifacts/html`: an
 // `<img src>` request can't carry an Authorization header. Loopback-
 // only listener + `requireSameOrigin` remain the trust boundary.
 const SVG_EXT_RE = /\.svg$/i;
-const getSvgsDirReal = makeCachedRealpath(WORKSPACE_PATHS.svgs);
 app.use(
   "/artifacts/svg",
-  async (req, res, next) => {
-    if (!SVG_EXT_RE.test(req.path)) {
-      res.status(404).end();
-      return;
-    }
-    const root = await getSvgsDirReal();
-    if (!root) {
-      res.status(404).end();
-      return;
-    }
-    // denyDotfiles for the same reason as the html mount: this handler
-    // sets headers and serves via a bearer-bypassed <img> path, so the
-    // dotfile guard can't be left solely to `express.static`.
-    if (resolveArtifactRequestPath(root, req.path, true) === null) {
-      res.status(404).end();
-      return;
-    }
+  artifactMount(workspacePath, WORKSPACE_DIRS.svgs, SVG_EXT_RE, async (req, res, scope, relPath) => {
     res.setHeader("X-Content-Type-Options", "nosniff");
     res.setHeader("Content-Type", "image/svg+xml; charset=utf-8");
     res.setHeader("Content-Security-Policy", SVG_RESPONSE_CSP);
-    next();
-  },
-  express.static(WORKSPACE_PATHS.svgs, { dotfiles: "deny", fallthrough: false }),
+    await sendArtifactFile(req, res, scope, relPath);
+  }),
 );
 
 app.get(API_ROUTES.health, (_req: Request, res: Response) => {

package/server/plugins/confined-file-ops.ts

@@ -22,8 +22,8 @@ import { ensureInsideBase } from "./runtime-loader.js";
 //
 //   1. Replace `\` with `/` (Windows path.join leak repair).
 //   2. `path.posix.normalize` (folds `..`, `.`, `//`).
-//   3. Reject if the normalised form starts with `..` or `/`
-//      (would escape the scope root or be absolute).
+//   3. Reject if the normalised form starts with `..`, `/` or a
+//      drive letter (would escape the scope root or be absolute).
 //   4. `path.join(scopeRoot, ...segments)` — platform-aware join so
 //      the returned absolute path uses the host OS separator
 //      (backslashes on Windows, forward slashes on POSIX). Critical
@@ -36,11 +36,13 @@ import { ensureInsideBase } from "./runtime-loader.js";
 /** Resolve a plugin-supplied path to an absolute path inside the
  *  plugin's scope root. Throws on traversal. Lexical only — symlinks
  *  are checked by the FileOps below. Exported for tests. */
+const WINDOWS_DRIVE_RE = /^[a-zA-Z]:/;
+
 export function normalizePluginPath(scopeRoot: string, rel: string): string {
   const slashed = rel.replace(/\\/g, "/");
   const normalised = path.posix.normalize(slashed);
   // `path.posix.normalize` produces `..` alone if the input is `..` itself, hence the equality branch.
-  if (normalised === ".." || normalised.startsWith("../") || normalised.startsWith("/")) {
+  if (normalised === ".." || normalised.startsWith("../") || normalised.startsWith("/") || WINDOWS_DRIVE_RE.test(normalised)) {
     throw new Error(`path escapes plugin scope: ${rel}`);
   }
   const segments = normalised === "." ? [] : normalised.split("/");

package/server/system/config.ts

@@ -55,7 +55,7 @@ export interface AppSettings {
 
   // Photo-EXIF auto-capture (#1222 PR-A). When `autoCapture` is true
   // (the default), every saved attachment with an image MIME runs
-  // through `readPhotoExif` and a sidecar JSON lands at
+  // through `parsePhotoExif` and a sidecar JSON lands at
   // `data/locations/<YYYY>/<MM>/<id>.json`. Users opt out via
   // Settings → Privacy when they don't want GPS metadata captured
   // automatically (the future `manageMap` `extractExif` tool can

package/server/utils/exif.ts

@@ -15,7 +15,6 @@
 // extracted coords straight to the Google Map plugin without a
 // reshape (#1227).
 
-import { readFile } from "fs/promises";
 import exifr from "exifr";
 import { isRecord } from "./types.js";
 
@@ -159,17 +158,15 @@ export type ExifParser = (buf: Buffer) => Promise<unknown>;
 
 const defaultParser: ExifParser = (buf) => exifr.parse(buf, PARSE_OPTIONS);
 
-/** Parse a photo file and project the fields we care about. Returns
- *  `null` when the file has no parseable EXIF (screenshots, scrubbed
+/** Parse a photo's bytes and project the fields we care about. Returns
+ *  `null` when they hold no parseable EXIF (screenshots, scrubbed
  *  uploads, non-image MIME types, malformed JPEG). Never throws. */
-export async function readPhotoExif(absPath: string, parser: ExifParser = defaultParser): Promise<PhotoExif | null> {
+export async function parsePhotoExif(buf: Buffer, parser: ExifParser = defaultParser): Promise<PhotoExif | null> {
   let raw: unknown;
   try {
-    const buf = await readFile(absPath);
     raw = await parser(buf);
   } catch {
-    // Includes both fs errors (handler should have ensured the file
-    // exists) and exifr "couldn't find any EXIF data" rejections.
+    // exifr rejects with "couldn't find any EXIF data" on photos without it.
     return null;
   }
   if (!isRecord(raw)) return null;

package/server/utils/files/artifactMount.ts

@@ -0,0 +1,89 @@
+// The `/artifacts/*` mounts serve a file only while it sits inside the workspace: the mount folder is
+// re-resolved under the workspace on every request, so a folder replaced by a link out is a 404
+// rather than the new root, and the file is served from a handle proven to be the in-scope file
+// (plans/fix-3573-artifact-mounts.md).
+
+import path from "node:path";
+import type { FileHandle } from "node:fs/promises";
+import type { Request, RequestHandler, Response } from "express";
+import { openVerifiedWithinScope, realpathIfPresent, scopeRealpath, type VerifiedScope } from "@mulmoclaude/core/files";
+import { log } from "../../system/logger/index.js";
+import { resolveArtifactRequestPath } from "./safe.js";
+import { sendFileHandle } from "./sendFileHandle.js";
+
+/** `mountDir` is the mount folder relative to the workspace, e.g. `artifacts/images`; `""` is the workspace itself. */
+export async function artifactScope(workspaceRoot: string, mountDir: string): Promise<VerifiedScope | null> {
+  const trustedReal = await realpathIfPresent(workspaceRoot);
+  return trustedReal === null ? null : { trustedReal, scopeWithinTrusted: mountDir };
+}
+
+/** The decoded in-scope path of a request, or null when the mount folder is absent or leads out of the
+ *  workspace, or the URL is malformed, escapes, or touches a dotfile. */
+export async function artifactRequestPath(scope: VerifiedScope, reqPath: string): Promise<string | null> {
+  const scopeReal = await scopeRealpath(scope);
+  const decoded = scopeReal === null ? null : resolveArtifactRequestPath(scopeReal, reqPath, true);
+  return scopeReal === null || decoded === null ? null : lexicallyInside(scopeReal, decoded);
+}
+
+// The `path.relative` form is the containment check CodeQL recognises before the path reaches realpath.
+export function lexicallyInside(scopeReal: string, relPath: string): string | null {
+  const inside = path.relative(scopeReal, path.resolve(scopeReal, relPath));
+  return inside === "" || inside.startsWith("..") || path.isAbsolute(inside) ? null : inside;
+}
+
+/** A verified handle on a regular file of the scope; null for anything else. The caller closes it. */
+export async function openArtifactFile(scope: VerifiedScope, relPath: string): Promise<FileHandle | null> {
+  const handle = await openVerifiedWithinScope(scope, relPath);
+  if (handle === null) return null;
+  const isFile = await handle.stat().then(
+    (stats) => stats.isFile(),
+    () => false,
+  );
+  if (isFile) return handle;
+  await handle.close();
+  return null;
+}
+
+/** Bytes of a regular file of the scope, read through the verified handle; null for anything else or on any error. */
+export async function readArtifactFile(scope: VerifiedScope, relPath: string): Promise<Buffer | null> {
+  try {
+    const handle = await openArtifactFile(scope, relPath);
+    if (handle === null) return null;
+    try {
+      return await handle.readFile();
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    return null;
+  }
+}
+
+export type ArtifactResponder = (req: Request, res: Response, scope: VerifiedScope, relPath: string) => Promise<void>;
+
+export const sendArtifactFile: ArtifactResponder = async (req, res, scope, relPath) => {
+  const handle = await openArtifactFile(scope, relPath);
+  if (handle === null) {
+    res.status(404).end();
+    return;
+  }
+  await sendFileHandle(req, res, handle, relPath);
+};
+
+/** A mount over `workspaceRoot/mountDir` that answers requests matching `extension`; everything else is a 404. */
+export function artifactMount(workspaceRoot: string, mountDir: string, extension: RegExp, respond: ArtifactResponder = sendArtifactFile): RequestHandler {
+  return async (req, res) => {
+    try {
+      const scope = extension.test(req.path) ? await artifactScope(workspaceRoot, mountDir) : null;
+      const relPath = scope === null ? null : await artifactRequestPath(scope, req.path);
+      if (scope === null || relPath === null) {
+        res.status(404).end();
+        return;
+      }
+      await respond(req, res, scope, relPath);
+    } catch (err) {
+      log.warn("artifacts", "could not serve an artifact", { mountDir, path: req.path, error: String(err) });
+      if (!res.headersSent) res.status(404).end();
+    }
+  };
+}

package/server/utils/files/attachment-store.ts

@@ -10,17 +10,15 @@
 //   data/attachments/YYYY/MM/<id>.<ext>            (original, always)
 //   data/attachments/YYYY/MM/<id>.pdf              (companion, PPTX only — same <id>)
 
-import { readFile, stat } from "fs/promises";
 import path from "path";
 import { WORKSPACE_DIRS, WORKSPACE_PATHS } from "../../workspace/paths.js";
 import { shortId } from "../id.js";
-import { writeFileAtomic } from "./atomic.js";
 import { yearMonthUtc } from "@mulmoclaude/core/artifacts";
 import { makePathValidator } from "./path-validator.js";
-import { makeStoreResolvers } from "./store-resolvers.js";
+import { makeStoreFiles } from "./store-files.js";
 import { storedExtensionFor } from "./attachment-mime.js";
 
-const resolvers = makeStoreResolvers(() => WORKSPACE_PATHS.attachments, WORKSPACE_DIRS.attachments);
+const store = makeStoreFiles(() => WORKSPACE_PATHS.attachments, WORKSPACE_DIRS.attachments);
 
 export interface SavedAttachment {
   /** Workspace-relative path of the file written to disk. */
@@ -31,14 +29,15 @@ export interface SavedAttachment {
 }
 
 /** Post-save hook fired after every successful `saveAttachment`.
- *  Receives the absolute on-disk path, the workspace-relative path
- *  (the same one returned to the caller), and the MIME type the
- *  bytes were saved with. Hooks must NEVER throw — the upload is
- *  already on disk by the time the hook runs, so a failure should
+ *  Receives the workspace-relative path (the same one returned to the
+ *  caller) and the MIME type the bytes were saved with — no absolute
+ *  path, so a hook reads the bytes back through the store. Hooks must
+ *  NEVER throw — the upload is already on disk by the time the hook
+ *  runs, so a failure should
  *  log and return, not propagate. Multiple hooks fan out via
  *  `Promise.allSettled` so one slow / failing hook can't block or
  *  break the others. (#1222 PR-A.) */
-export type SaveAttachmentHook = (absPath: string, relativePath: string, mimeType: string) => Promise<void>;
+export type SaveAttachmentHook = (relativePath: string, mimeType: string) => Promise<void>;
 
 const saveAttachmentHooks: SaveAttachmentHook[] = [];
 
@@ -54,14 +53,14 @@ export function registerSaveAttachmentHook(hook: SaveAttachmentHook): () => void
   };
 }
 
-async function runSaveAttachmentHooks(absPath: string, relativePath: string, mimeType: string): Promise<void> {
+async function runSaveAttachmentHooks(relativePath: string, mimeType: string): Promise<void> {
   if (saveAttachmentHooks.length === 0) return;
   // Snapshot the array so a hook that calls `registerSaveAttachmentHook`
   // (or its unregister fn) during this loop doesn't mutate the
   // iteration order. `allSettled` so one failing hook doesn't stop
   // the others — failures are the hook's responsibility to log.
   const snapshot = [...saveAttachmentHooks];
-  await Promise.allSettled(snapshot.map((hook) => hook(absPath, relativePath, mimeType)));
+  await Promise.allSettled(snapshot.map((hook) => hook(relativePath, mimeType)));
 }
 
 /** Save a single attachment under data/attachments/YYYY/MM/. The
@@ -70,15 +69,13 @@ async function runSaveAttachmentHooks(absPath: string, relativePath: string, mim
 export async function saveAttachment(base64Data: string, mimeType: string, originalFilename?: string): Promise<SavedAttachment> {
   const partition = yearMonthUtc();
   const ext = storedExtensionFor(mimeType, originalFilename);
-  const filename = `${shortId()}${ext}`;
-  const absPath = path.join(WORKSPACE_PATHS.attachments, partition, filename);
-  await writeFileAtomic(absPath, Buffer.from(base64Data, "base64"));
-  const relativePath = path.posix.join(WORKSPACE_DIRS.attachments, partition, filename);
+  const relativePath = path.posix.join(WORKSPACE_DIRS.attachments, partition, `${shortId()}${ext}`);
+  await store.write(relativePath, Buffer.from(base64Data, "base64"));
   // Hooks (e.g. photo-EXIF capture) are awaited so callers can rely
   // on the sidecar existing by the time `saveAttachment` resolves —
   // simplifies test assertions and removes a class of race conditions
   // for downstream tools that read sidecars right after upload.
-  await runSaveAttachmentHooks(absPath, relativePath, mimeType);
+  await runSaveAttachmentHooks(relativePath, mimeType);
   return { relativePath, mimeType };
 }
 
@@ -92,30 +89,21 @@ export async function saveCompanion(originalRelativePath: string, buf: Buffer, e
   const dir = path.posix.dirname(originalRelativePath);
   const base = path.posix.basename(originalRelativePath, path.posix.extname(originalRelativePath));
   const relativePath = path.posix.join(dir, `${base}${ext}`);
-  const absPath = await resolvers.forWrite(relativePath);
-  await writeFileAtomic(absPath, buf);
+  await store.write(relativePath, buf);
   return relativePath;
 }
 
 export async function loadAttachmentBase64(relativePath: string): Promise<string> {
-  const absPath = await resolvers.forRead(relativePath);
-  const buf = await readFile(absPath);
-  return buf.toString("base64");
+  return (await store.read(relativePath)).toString("base64");
 }
 
 export async function loadAttachmentBytes(relativePath: string): Promise<Buffer> {
-  const absPath = await resolvers.forRead(relativePath);
-  return readFile(absPath);
+  return store.read(relativePath);
 }
 
 /** True when `relativePath` names a regular file inside the attachment store. */
 export async function attachmentExists(relativePath: string): Promise<boolean> {
-  try {
-    const absPath = await resolvers.forRead(relativePath);
-    return (await stat(absPath)).isFile();
-  } catch {
-    return false;
-  }
+  return store.isFile(relativePath);
 }
 
 export const isAttachmentPath = makePathValidator({ prefix: WORKSPACE_DIRS.attachments });

package/server/utils/files/image-store.ts

@@ -1,32 +1,26 @@
-import { readFile } from "fs/promises";
 import path from "path";
 import { WORKSPACE_DIRS, WORKSPACE_PATHS } from "../../workspace/paths.js";
 import { shortId } from "../id.js";
-import { writeFileAtomic } from "./atomic.js";
 import { yearMonthUtc } from "@mulmoclaude/core/artifacts";
 import { makePathValidator } from "./path-validator.js";
-import { makeStoreResolvers } from "./store-resolvers.js";
+import { makeStoreFiles } from "./store-files.js";
 
-const resolvers = makeStoreResolvers(() => WORKSPACE_PATHS.images, WORKSPACE_DIRS.images);
+const store = makeStoreFiles(() => WORKSPACE_PATHS.images, WORKSPACE_DIRS.images);
 
 // #764 sharded under images/YYYY/MM/ (UTC). Buffer pass-through avoids re-encoding the PNG bytes.
 export async function saveImage(base64Data: string): Promise<string> {
   const partition = yearMonthUtc();
-  const filename = `${shortId()}.png`;
-  const absPath = path.join(WORKSPACE_PATHS.images, partition, filename);
-  await writeFileAtomic(absPath, Buffer.from(base64Data, "base64"));
-  return path.posix.join(WORKSPACE_DIRS.images, partition, filename);
+  const relativePath = path.posix.join(WORKSPACE_DIRS.images, partition, `${shortId()}.png`);
+  await store.write(relativePath, Buffer.from(base64Data, "base64"));
+  return relativePath;
 }
 
 export async function overwriteImage(relativePath: string, base64Data: string): Promise<void> {
-  const absPath = await resolvers.forWrite(relativePath);
-  await writeFileAtomic(absPath, Buffer.from(base64Data, "base64"));
+  await store.write(relativePath, Buffer.from(base64Data, "base64"));
 }
 
 export async function loadImageBase64(relativePath: string): Promise<string> {
-  const absPath = await resolvers.forRead(relativePath);
-  const buf = await readFile(absPath);
-  return buf.toString("base64");
+  return (await store.read(relativePath)).toString("base64");
 }
 
 export function stripDataUri(dataUri: string): string {

package/server/utils/files/plugins-io.ts

@@ -15,8 +15,9 @@
 // written ledger never bricks server boot. Writes go through the
 // atomic helper, so a crashed install can't leave a corrupt file.
 
-import { readFile } from "node:fs/promises";
 import path from "node:path";
+import type { VerifiedScope } from "@mulmoclaude/core/files";
+import { openArtifactFile } from "./artifactMount.js";
 import { loadJsonFile } from "./json.js";
 import { hasStringProp } from "../types.js";
 import { WORKSPACE_PATHS } from "../../workspace/paths.js";
@@ -57,10 +58,17 @@ export interface PluginAsset {
   contentType: string;
 }
 
-export async function readPluginAsset(absPath: string): Promise<PluginAsset> {
-  const data = await readFile(absPath);
-  const ext = path.extname(absPath).toLowerCase();
-  return { data, contentType: pluginAssetContentType(ext) };
+/** Null for a path that is missing, not a regular file, or outside the scope (also when swapped mid-read); other
+ *  read errors propagate. The bytes come from the verified handle (#3573). */
+export async function readPluginAsset(scope: VerifiedScope, relPath: string): Promise<PluginAsset | null> {
+  const handle = await openArtifactFile(scope, relPath);
+  if (handle === null) return null;
+  try {
+    const data = await handle.readFile();
+    return { data, contentType: pluginAssetContentType(path.extname(relPath).toLowerCase()) };
+  } finally {
+    await handle.close();
+  }
 }
 
 // Lookup table over a switch — flat data structure stays under

package/server/utils/files/safe.ts

@@ -14,14 +14,6 @@ export function isEnoent(err: unknown): boolean {
   return isErrorWithCode(err) && err.code === "ENOENT";
 }
 
-export function readBinarySafeSync(absPath: string): Buffer | null {
-  try {
-    return readFileSync(absPath);
-  } catch {
-    return null;
-  }
-}
-
 export async function readTextSafe(absPath: string): Promise<string | null> {
   try {
     return await promises.readFile(absPath, "utf-8");