mulmoclaude 0.3.0 → 0.5.0

package/server/api/routes/files.ts

@@ -1,18 +1,26 @@
 import { Router, Request, Response } from "express";
-import fs from "fs";
+import { ReadStream, Stats, createReadStream, readFileSync, realpathSync } from "fs";
 import path from "path";
 import { workspacePath } from "../../workspace/workspace.js";
 import { statSafe, statSafeAsync, readDirSafeAsync, resolveWithinRoot, writeFileAtomic } from "../../utils/files/index.js";
 import { errorMessage } from "../../utils/errors.js";
 import { badRequest, notFound, sendError, serverError } from "../../utils/httpError.js";
+import { getOptionalStringQuery } from "../../utils/request.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
 import { GitignoreFilter } from "../../utils/gitignore.js";
 import { getCachedReferenceDirs } from "../../workspace/reference-dirs.js";
+import { log } from "../../system/logger/index.js";
+import { previewSnippet } from "../../utils/logPreview.js";
 
 const router = Router();
 
 const MAX_PREVIEW_BYTES = 1024 * 1024; // 1 MB — text content embedded in JSON
-const MAX_RAW_BYTES = 50 * 1024 * 1024; // 50 MB — cap for binary streaming
+const MAX_RAW_BYTES = 50 * 1024 * 1024; // 50 MB — cap for non-media streaming (images/pdf/binary load whole into the browser)
+// Audio/video are streamed via HTTP Range requests (see GET /raw),
+// so the browser never buffers the whole file. Podcasts commonly
+// run 100–300 MB and recorded video can run multi-GB; cap at 4 GB
+// just to keep an obviously-pathological file from being served.
+const MAX_MEDIA_BYTES = 4 * 1024 * 1024 * 1024;
 const HIDDEN_DIRS = new Set([".git"]);
 
 // Files whose basename exactly matches one of these is refused by
@@ -187,7 +195,7 @@ export function classify(filename: string): ContentKind {
 // Cached realpath of the workspace. Computed once at module load so
 // every request avoids the syscall. resolveWithinRoot needs an
 // already-realpath'd root.
-const workspaceReal = fs.realpathSync(workspacePath);
+const workspaceReal = realpathSync(workspacePath);
 
 // Wraps the shared resolveWithinRoot helper with the additional
 // hidden-dir traversal check (e.g. `.git/config`). `buildTreeAsync`
@@ -235,7 +243,7 @@ function resolveRefPath(prefixedPath: string): string | null {
 
   let rootReal: string;
   try {
-    rootReal = fs.realpathSync(entry.hostPath);
+    rootReal = realpathSync(entry.hostPath);
   } catch {
     return null;
   }
@@ -276,7 +284,7 @@ export function parseRange(header: string, size: number): ByteRange | null {
   // RFC 7233 §2.1: "A Range request on a representation whose current
   // length is 0 cannot be satisfied". We also need this guard at the
   // top because the naive suffix-range math below produces `end = -1`
-  // for zero-byte files, which then crashes `fs.createReadStream`
+  // for zero-byte files, which then crashes `createReadStream`
   // with `ERR_OUT_OF_RANGE`.
   if (size <= 0) return null;
   const match = /^bytes=(\d*)-(\d*)$/i.exec(header.trim());
@@ -325,7 +333,7 @@ function applyRawSecurityHeaders(res: Response): void {
 // If the read stream errors mid-flight (file deleted, disk error,
 // permissions changed), surface a clean failure to the client instead
 // of leaving the connection hanging.
-function pipeWithErrorHandling(stream: fs.ReadStream, res: Response<ErrorResponse>): void {
+function pipeWithErrorHandling(stream: ReadStream, res: Response<ErrorResponse>): void {
   stream.on("error", (err) => {
     if (res.headersSent) {
       res.destroy(err);
@@ -340,7 +348,7 @@ function pipeWithErrorHandling(stream: fs.ReadStream, res: Response<ErrorRespons
 // the same security filters as the original sync implementation
 // (hidden dirs, sensitive files, symlinks all rejected) and the same
 // ordering (dirs before files, alphabetical within type). Uses
-// `fs.promises` throughout so the walk never blocks the event loop,
+// `promises` throughout so the walk never blocks the event loop,
 // and fans out each directory's children in parallel via
 // `Promise.all`.
 //
@@ -475,6 +483,7 @@ export async function listDirShallow(absPath: string, relPath: string, gitFilter
 }
 
 router.get(API_ROUTES.files.tree, async (_req: Request<object, unknown, unknown, object>, res: Response<TreeNode | ErrorResponse>) => {
+  log.info("files", "GET tree: start");
   try {
     // Start with an empty filter — the workspace root's .gitignore
     // is for git (excluding github/ from commits), NOT for the
@@ -485,7 +494,8 @@ router.get(API_ROUTES.files.tree, async (_req: Request<object, unknown, unknown,
     const tree = await buildTreeAsync(workspaceReal, "");
     res.json(tree);
   } catch (err) {
-    res.status(500).json({ error: `Failed to read workspace: ${errorMessage(err)}` });
+    log.error("files", "GET tree: threw", { error: errorMessage(err) });
+    serverError(res, `Failed to read workspace: ${errorMessage(err)}`);
   }
 });
 
@@ -493,17 +503,20 @@ router.get(API_ROUTES.files.tree, async (_req: Request<object, unknown, unknown,
 // (no recursion) so the client can render the tree incrementally.
 // `path` is optional; empty / missing = workspace root.
 router.get(API_ROUTES.files.dir, async (req: Request<object, unknown, unknown, PathQuery>, res: Response<TreeNode | ErrorResponse>) => {
-  const relPath = typeof req.query.path === "string" ? req.query.path : "";
+  const relPath = getOptionalStringQuery(req, "path") ?? "";
+  log.info("files", "GET dir: start", { pathPreview: previewSnippet(relPath) });
 
   // Reference directory branch — resolve against the registered ref dir
   if (isRefPath(relPath)) {
     const absPath = resolveRefPath(relPath);
     if (!absPath) {
+      log.warn("files", "GET dir: ref dir not found", { pathPreview: previewSnippet(relPath) });
       notFound(res, "Not found");
       return;
     }
     const stat = await statSafeAsync(absPath);
     if (!stat || !stat.isDirectory()) {
+      log.warn("files", "GET dir: ref path missing or not a dir", { pathPreview: previewSnippet(relPath) });
       notFound(res, "Not found");
       return;
     }
@@ -515,15 +528,18 @@ router.get(API_ROUTES.files.dir, async (req: Request<object, unknown, unknown, P
   // Workspace path — existing logic
   const absPath = resolveSafe(relPath);
   if (!absPath) {
+    log.warn("files", "GET dir: path outside workspace", { pathPreview: previewSnippet(relPath) });
     notFound(res, "Not found");
     return;
   }
   const stat = await statSafeAsync(absPath);
   if (!stat) {
+    log.warn("files", "GET dir: not found", { pathPreview: previewSnippet(relPath) });
     notFound(res, "Not found");
     return;
   }
   if (!stat.isDirectory()) {
+    log.warn("files", "GET dir: not a directory", { pathPreview: previewSnippet(relPath) });
     badRequest(res, "path is not a directory");
     return;
   }
@@ -541,6 +557,7 @@ router.get(API_ROUTES.files.dir, async (req: Request<object, unknown, unknown, P
     const listing = await listDirShallow(absPath, path.relative(workspaceReal, absPath), filter);
     res.json(listing);
   } catch (err) {
+    log.error("files", "GET dir: threw", { pathPreview: previewSnippet(relPath), error: errorMessage(err) });
     serverError(res, `Failed to read directory: ${errorMessage(err)}`);
   }
 });
@@ -567,8 +584,8 @@ interface PathQuery {
 function resolveAndStatFile<T>(
   req: Request<object, unknown, unknown, PathQuery>,
   res: Response<T | ErrorResponse>,
-): { relPath: string; absPath: string; stat: fs.Stats } | null {
-  const relPath = typeof req.query.path === "string" ? req.query.path : "";
+): { relPath: string; absPath: string; stat: Stats } | null {
+  const relPath = getOptionalStringQuery(req, "path") ?? "";
   if (!relPath) {
     badRequest(res, "path required");
     return null;
@@ -623,8 +640,16 @@ function resolveAndStatFile<T>(
 }
 
 router.get(API_ROUTES.files.content, (req: Request<object, unknown, unknown, PathQuery>, res: Response<FileContentResponse | ErrorResponse>) => {
+  const requestedPath = getOptionalStringQuery(req, "path") ?? "";
+  log.info("files", "GET content: start", { pathPreview: previewSnippet(requestedPath) });
   const ctx = resolveAndStatFile(req, res);
-  if (!ctx) return;
+  if (!ctx) {
+    // resolveAndStatFile already wrote the 4xx; surface the gate
+    // miss so the operator can correlate the user-visible error
+    // with a concrete reason in the log without re-running.
+    log.warn("files", "GET content: gated by resolve/stat", { pathPreview: previewSnippet(requestedPath) });
+    return;
+  }
   const { relPath, absPath, stat } = ctx;
 
   const meta = {
@@ -633,10 +658,13 @@ router.get(API_ROUTES.files.content, (req: Request<object, unknown, unknown, Pat
     modifiedMs: stat.mtimeMs,
   };
 
-  // Anything past the binary stream cap is "too-large" regardless of
-  // type — even images/PDFs, since the client would have to fetch
-  // them via /files/raw which enforces the same limit.
-  if (stat.size > MAX_RAW_BYTES) {
+  const kind = classify(absPath);
+  // Audio/video stream via Range requests, so they get the looser
+  // MAX_MEDIA_BYTES cap. Everything else (images/PDFs/binary) is
+  // loaded whole by the browser and stays at MAX_RAW_BYTES.
+  const isStreamingMedia = kind === "audio" || kind === "video";
+  const sizeCap = isStreamingMedia ? MAX_MEDIA_BYTES : MAX_RAW_BYTES;
+  if (stat.size > sizeCap) {
     res.json({
       kind: "too-large",
       ...meta,
@@ -645,7 +673,6 @@ router.get(API_ROUTES.files.content, (req: Request<object, unknown, unknown, Pat
     return;
   }
 
-  const kind = classify(absPath);
   if (kind === "image" || kind === "pdf" || kind === "audio" || kind === "video") {
     res.json({ kind, ...meta });
     return;
@@ -668,11 +695,13 @@ router.get(API_ROUTES.files.content, (req: Request<object, unknown, unknown, Pat
   }
   let content: string;
   try {
-    content = fs.readFileSync(absPath, "utf-8");
+    content = readFileSync(absPath, "utf-8");
   } catch (err) {
-    res.status(500).json({ error: `Failed to read file: ${errorMessage(err)}` });
+    log.error("files", "GET content: read threw", { pathPreview: previewSnippet(relPath), error: errorMessage(err) });
+    serverError(res, `Failed to read file: ${errorMessage(err)}`);
     return;
   }
+  log.info("files", "GET content: ok", { pathPreview: previewSnippet(relPath), bytes: stat.size });
   res.json({ kind: "text", ...meta, content });
 });
 
@@ -682,15 +711,22 @@ router.get(API_ROUTES.files.content, (req: Request<object, unknown, unknown, Pat
 // The file must already exist; creating new files is out of scope.
 router.put(API_ROUTES.files.content, async (req: Request<object, unknown, WriteContentRequest>, res: Response<WriteContentResponse | ErrorResponse>) => {
   const { path: relPathRaw, content: contentRaw } = req.body ?? {};
+  log.info("files", "PUT content: start", {
+    pathPreview: typeof relPathRaw === "string" ? previewSnippet(relPathRaw) : undefined,
+    bytes: typeof contentRaw === "string" ? Buffer.byteLength(contentRaw, "utf-8") : undefined,
+  });
   if (typeof relPathRaw !== "string" || relPathRaw.length === 0) {
+    log.warn("files", "PUT content: missing path");
     badRequest(res, "path required");
     return;
   }
   if (typeof contentRaw !== "string") {
+    log.warn("files", "PUT content: missing content", { pathPreview: previewSnippet(relPathRaw) });
     badRequest(res, "content required");
     return;
   }
   if (Buffer.byteLength(contentRaw, "utf-8") > MAX_PREVIEW_BYTES) {
+    log.warn("files", "PUT content: too large", { pathPreview: previewSnippet(relPathRaw), bytes: Buffer.byteLength(contentRaw, "utf-8") });
     badRequest(res, `content exceeds ${MAX_PREVIEW_BYTES} byte limit`);
     return;
   }
@@ -729,10 +765,15 @@ router.put(API_ROUTES.files.content, async (req: Request<object, unknown, WriteC
     // other's staging file and race through the rename.
     await writeFileAtomic(absPath, contentRaw, { uniqueTmp: true });
   } catch (err) {
+    log.error("files", "PUT content: write threw", { pathPreview: previewSnippet(relPathRaw), error: errorMessage(err) });
     serverError(res, `Failed to write file: ${errorMessage(err)}`);
     return;
   }
   const fresh = await statSafeAsync(absPath);
+  log.info("files", "PUT content: ok", {
+    pathPreview: previewSnippet(relPathRaw),
+    bytes: fresh?.size ?? Buffer.byteLength(contentRaw, "utf-8"),
+  });
   res.json({
     path: relPathRaw,
     size: fresh?.size ?? Buffer.byteLength(contentRaw, "utf-8"),
@@ -741,12 +782,20 @@ router.put(API_ROUTES.files.content, async (req: Request<object, unknown, WriteC
 });
 
 router.get(API_ROUTES.files.raw, (req: Request<object, unknown, unknown, PathQuery>, res: Response<ErrorResponse>) => {
+  const requestedPath = getOptionalStringQuery(req, "path") ?? "";
+  log.info("files", "GET raw: start", { pathPreview: previewSnippet(requestedPath) });
   const ctx = resolveAndStatFile(req, res);
-  if (!ctx) return;
+  if (!ctx) {
+    log.warn("files", "GET raw: gated by resolve/stat", { pathPreview: previewSnippet(requestedPath) });
+    return;
+  }
   const { absPath, stat } = ctx;
 
-  if (stat.size > MAX_RAW_BYTES) {
-    sendError(res, 413, `File too large to stream (${stat.size} bytes, limit ${MAX_RAW_BYTES})`);
+  const rawKind = classify(absPath);
+  const rawSizeCap = rawKind === "audio" || rawKind === "video" ? MAX_MEDIA_BYTES : MAX_RAW_BYTES;
+  if (stat.size > rawSizeCap) {
+    log.warn("files", "GET raw: too large", { pathPreview: previewSnippet(requestedPath), bytes: stat.size, cap: rawSizeCap });
+    sendError(res, 413, `File too large to stream (${stat.size} bytes, limit ${rawSizeCap})`);
     return;
   }
   const ext = path.extname(absPath).toLowerCase();
@@ -779,12 +828,12 @@ router.get(API_ROUTES.files.raw, (req: Request<object, unknown, unknown, PathQue
     res.status(206);
     res.setHeader("Content-Range", `bytes ${range.start}-${range.end}/${stat.size}`);
     res.setHeader("Content-Length", String(range.end - range.start + 1));
-    pipeWithErrorHandling(fs.createReadStream(absPath, { start: range.start, end: range.end }), res);
+    pipeWithErrorHandling(createReadStream(absPath, { start: range.start, end: range.end }), res);
     return;
   }
 
   res.setHeader("Content-Length", String(stat.size));
-  pipeWithErrorHandling(fs.createReadStream(absPath), res);
+  pipeWithErrorHandling(createReadStream(absPath), res);
 });
 
 // ── Reference directory roots ───────────────────────────────────
@@ -794,6 +843,7 @@ router.get(API_ROUTES.files.raw, (req: Request<object, unknown, unknown, PathQue
 // prefix so subsequent /dir and /content requests route correctly.
 
 router.get(API_ROUTES.files.refRoots, async (_req: Request, res: Response<TreeNode[]>) => {
+  log.info("files", "GET ref-roots: start");
   const entries = getCachedReferenceDirs();
   const nodes: TreeNode[] = [];
   for (const entry of entries) {
@@ -806,6 +856,7 @@ router.get(API_ROUTES.files.refRoots, async (_req: Request, res: Response<TreeNo
       modifiedMs: stat.mtimeMs,
     });
   }
+  log.info("files", "GET ref-roots: ok", { configured: entries.length, mounted: nodes.length });
   res.json(nodes);
 });
 

package/server/api/routes/html.ts

@@ -3,12 +3,14 @@ import { readCurrentHtml, writeCurrentHtml } from "../../utils/files/html-io.js"
 import { getGeminiClient, isGeminiAvailable } from "../../utils/gemini.js";
 import { errorMessage } from "../../utils/errors.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+import { log } from "../../system/logger/index.js";
+import { promptMeta } from "../../utils/promptMeta.js";
 
 const router = Router();
 
 async function callGemini(prompt: string): Promise<string> {
-  const ai = getGeminiClient();
-  const response = await ai.models.generateContent({
+  const client = getGeminiClient();
+  const response = await client.models.generateContent({
     model: "gemini-2.0-flash",
     contents: [{ text: prompt }],
   });
@@ -41,11 +43,14 @@ type HtmlResponse = HtmlSuccessResponse | HtmlErrorResponse;
 
 router.post(API_ROUTES.html.generate, async (req: Request<object, unknown, HtmlPromptBody>, res: Response<HtmlResponse>) => {
   const { prompt } = req.body;
+  log.info("html", "generate: start", { prompt: typeof prompt === "string" ? promptMeta(prompt) : undefined });
   if (!prompt) {
+    log.warn("html", "generate: missing prompt");
     res.status(400).json({ message: "prompt is required" });
     return;
   }
   if (!isGeminiAvailable()) {
+    log.warn("html", "generate: GEMINI_API_KEY not set");
     res.status(500).json({ message: "GEMINI_API_KEY is not set" });
     return;
   }
@@ -54,6 +59,7 @@ router.post(API_ROUTES.html.generate, async (req: Request<object, unknown, HtmlP
     const html = await callGemini(fullPrompt);
 
     await writeCurrentHtml(html);
+    log.info("html", "generate: ok", { bytes: html.length });
     res.json({
       message: "HTML generation succeeded",
       instructions: "Acknowledge that the HTML was generated and has been presented to the user.",
@@ -61,23 +67,28 @@ router.post(API_ROUTES.html.generate, async (req: Request<object, unknown, HtmlP
       data: { html, type: "tailwind" },
     });
   } catch (err) {
+    log.error("html", "generate: threw", { error: errorMessage(err), prompt: promptMeta(prompt) });
     res.status(500).json({ message: errorMessage(err) });
   }
 });
 
 router.post(API_ROUTES.html.edit, async (req: Request<object, unknown, HtmlPromptBody>, res: Response<HtmlResponse>) => {
   const { prompt } = req.body;
+  log.info("html", "edit: start", { prompt: typeof prompt === "string" ? promptMeta(prompt) : undefined });
   if (!prompt) {
+    log.warn("html", "edit: missing prompt");
     res.status(400).json({ message: "prompt is required" });
     return;
   }
   if (!isGeminiAvailable()) {
+    log.warn("html", "edit: GEMINI_API_KEY not set");
     res.status(500).json({ message: "GEMINI_API_KEY is not set" });
     return;
   }
   try {
     const existingHtml = await readCurrentHtml();
     if (!existingHtml?.trim()) {
+      log.warn("html", "edit: no existing HTML to modify");
       res.status(400).json({
         message: "No HTML page has been generated yet. Use generateHtml first.",
       });
@@ -86,6 +97,7 @@ router.post(API_ROUTES.html.edit, async (req: Request<object, unknown, HtmlPromp
     const fullPrompt = `Modify the following HTML page based on this instruction: ${prompt}\n\nExisting HTML:\n${existingHtml}\n\nRequirements:\n- Return only the complete modified HTML, no explanation`;
     const html = await callGemini(fullPrompt);
     await writeCurrentHtml(html);
+    log.info("html", "edit: ok", { bytes: html.length });
     res.json({
       message: "HTML editing succeeded",
       instructions: "Acknowledge that the HTML was modified and has been presented to the user.",
@@ -94,6 +106,7 @@ router.post(API_ROUTES.html.edit, async (req: Request<object, unknown, HtmlPromp
       updating: true,
     });
   } catch (err) {
+    log.error("html", "edit: threw", { error: errorMessage(err), prompt: promptMeta(prompt) });
     res.status(500).json({ message: errorMessage(err) });
   }
 });

package/server/api/routes/image.ts

@@ -5,7 +5,15 @@ import { generateGeminiImageContent, generateGeminiImageFromPrompt } from "../..
 import { errorMessage } from "../../utils/errors.js";
 import { badRequest, serverError } from "../../utils/httpError.js";
 import { saveImage, overwriteImage, loadImageBase64, stripDataUri, isImagePath } from "../../utils/files/image-store.js";
+import { promptMeta } from "../../utils/promptMeta.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+import { log } from "../../system/logger/index.js";
+
+// Image-generation routes were silent on success and on failure. When
+// the canvas showed "missing image" with no server-side trace, there
+// was nothing to grep. Log lines now carry a prompt fingerprint
+// (`{ length, sha256 }`) via `promptMeta()` instead of the raw text —
+// see `server/utils/promptMeta.ts` for why.
 
 const router = Router();
 
@@ -37,6 +45,17 @@ async function respondWithImage(
   kind: "generation" | "edit",
 ): Promise<void> {
   if (!imageData) {
+    // Gemini returned text-only / no image — typically a refusal,
+    // safety filter, or a quota miss. Codex flagged this branch
+    // (review of #780) for treating refusals as success; switching
+    // it to a 502 is the obvious fix, but `apiPost.extractError`
+    // only extracts `body.error` and image responses use
+    // `{ success: false, message }`, so the agent would lose the
+    // Gemini-side message and see only "Bad Gateway". Leaving
+    // behavior unchanged here until the shared error-shape
+    // (`extractError` accepting `message`, or all image responses
+    // adopting `error`) lands in a separate PR — see #783 review
+    // history.
     res.json({ message: fallbackMessage ?? "no image data in response" });
     return;
   }
@@ -87,13 +106,27 @@ interface GenerateImageBody {
 router.post(API_ROUTES.image.generate, async (req: Request<object, unknown, GenerateImageBody>, res: Response<ImageResponse>) => {
   const { prompt, model } = req.body;
   if (!prompt) {
+    log.warn("image", "generate: missing prompt");
     res.status(400).json({ success: false, message: "prompt is required" });
     return;
   }
+  log.info("image", "generate: start", { prompt: promptMeta(prompt), model: model ?? "(default)" });
   try {
     const { imageData, message } = await generateGeminiImageFromPrompt(prompt, model);
+    if (!imageData) {
+      log.warn("image", "generate: gemini returned no image data", {
+        prompt: promptMeta(prompt),
+        fallbackMessage: message,
+      });
+    } else {
+      log.info("image", "generate: ok", { prompt: promptMeta(prompt), bytes: imageData.length });
+    }
     await respondWithImage(res, imageData, message, prompt, "generation");
   } catch (err) {
+    log.error("image", "generate: gemini call threw", {
+      prompt: promptMeta(prompt),
+      error: errorMessage(err),
+    });
     res.status(500).json({ success: false, message: errorMessage(err) });
   }
 });
@@ -106,17 +139,20 @@ router.post(API_ROUTES.image.edit, async (req: Request<object, unknown, EditImag
   const { prompt } = req.body;
   const session = getOptionalStringQuery(req, "session");
   if (!prompt) {
+    log.warn("image", "edit: missing prompt", { session });
     res.status(400).json({ success: false, message: "prompt is required" });
     return;
   }
   const currentImageData = session ? getSessionImageData(session) : undefined;
   if (!currentImageData) {
+    log.warn("image", "edit: no source image selected", { session });
     res.status(400).json({
       success: false,
       message: "No image is selected. Please click an image in the sidebar first, then ask me to edit it.",
     });
     return;
   }
+  log.info("image", "edit: start", { prompt: promptMeta(prompt), session, sourceKind: isImagePath(currentImageData) ? "path" : "dataUri" });
   try {
     // Resolve input image to raw base64 — supports both file paths and legacy data URIs
     const base64Data = isImagePath(currentImageData) ? await loadImageBase64(currentImageData) : stripDataUri(currentImageData);
@@ -127,8 +163,22 @@ router.post(API_ROUTES.image.edit, async (req: Request<object, unknown, EditImag
         parts: [{ inlineData: { mimeType: "image/png", data: base64Data } }, { text: prompt }],
       },
     ]);
+    if (!imageData) {
+      log.warn("image", "edit: gemini returned no image data", {
+        prompt: promptMeta(prompt),
+        session,
+        fallbackMessage: message,
+      });
+    } else {
+      log.info("image", "edit: ok", { prompt: promptMeta(prompt), session, bytes: imageData.length });
+    }
     await respondWithImage(res, imageData, message, prompt, "edit");
   } catch (err) {
+    log.error("image", "edit: gemini call threw", {
+      prompt: promptMeta(prompt),
+      session,
+      error: errorMessage(err),
+    });
     res.status(500).json({ success: false, message: errorMessage(err) });
   }
 });
@@ -145,25 +195,30 @@ router.post(API_ROUTES.image.upload, async (req: Request<object, unknown, Canvas
   await saveCanvasImage(res, base64, async (b64) => saveImage(b64));
 });
 
-router.put(
-  API_ROUTES.image.update,
-  async (req: Request<{ filename: string }, unknown, CanvasImageBody>, res: Response<CanvasImageResponse | CanvasImageError>) => {
-    const relativePath = `images/${req.params.filename}`;
-    const { imageData } = req.body;
-    if (!imageData || !relativePath) {
-      badRequest(res, "imageData and path are required");
-      return;
-    }
-    if (!isImagePath(relativePath)) {
-      badRequest(res, "invalid image path");
-      return;
-    }
-    const base64 = stripDataUri(imageData);
-    await saveCanvasImage(res, base64, async (b64) => {
-      await overwriteImage(relativePath, b64);
-      return relativePath;
-    });
-  },
-);
+interface UpdateImageBody extends CanvasImageBody {
+  relativePath: string;
+}
+
+// Canvas saves come in with the workspace-relative path the file
+// already lives at (returned at canvas creation), so the client never
+// has to know how `saveImage` shards by YYYY/MM. The server validates
+// the prefix + extension via `isImagePath`; `safeResolve` inside
+// `overwriteImage` blocks any traversal.
+router.put(API_ROUTES.image.update, async (req: Request<object, unknown, UpdateImageBody>, res: Response<CanvasImageResponse | CanvasImageError>) => {
+  const { relativePath, imageData } = req.body;
+  if (!relativePath || !isImagePath(relativePath)) {
+    badRequest(res, "invalid image relativePath");
+    return;
+  }
+  if (!imageData) {
+    badRequest(res, "imageData is required");
+    return;
+  }
+  const base64 = stripDataUri(imageData);
+  await saveCanvasImage(res, base64, async (b64) => {
+    await overwriteImage(relativePath, b64);
+    return relativePath;
+  });
+});
 
 export default router;