mulmoclaude 0.3.0 → 0.4.0

package/server/api/routes/files.ts

@@ -1,10 +1,11 @@
 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";
@@ -187,7 +188,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 +236,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 +277,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 +326,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 +341,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`.
 //
@@ -493,7 +494,7 @@ 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") ?? "";
 
   // Reference directory branch — resolve against the registered ref dir
   if (isRefPath(relPath)) {
@@ -567,8 +568,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;
@@ -668,7 +669,7 @@ 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)}` });
     return;
@@ -779,12 +780,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 ───────────────────────────────────

package/server/api/routes/html.ts

@@ -7,8 +7,8 @@ import { API_ROUTES } from "../../../src/config/apiRoutes.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 }],
   });

package/server/api/routes/image.ts

@@ -4,7 +4,7 @@ import { getSessionImageData } from "../../events/session-store/index.js";
 import { generateGeminiImageContent, generateGeminiImageFromPrompt } from "../../utils/gemini.js";
 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 { saveImage, overwriteImage, loadImageBase64, stripDataUri, isImagePath, imagePathFromFilename } from "../../utils/files/image-store.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
 
 const router = Router();
@@ -148,14 +148,14 @@ router.post(API_ROUTES.image.upload, async (req: Request<object, unknown, Canvas
 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");
+    const relativePath = imagePathFromFilename(req.params.filename);
+    if (!relativePath) {
+      badRequest(res, "invalid image filename");
       return;
     }
-    if (!isImagePath(relativePath)) {
-      badRequest(res, "invalid image path");
+    const { imageData } = req.body;
+    if (!imageData) {
+      badRequest(res, "imageData is required");
       return;
     }
     const base64 = stripDataUri(imageData);

package/server/api/routes/mulmo-script.ts

@@ -1,8 +1,9 @@
 import { Router, Request, Response } from "express";
-import fs from "fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "fs";
 import path from "path";
 import { WORKSPACE_PATHS } from "../../workspace/paths.js";
 import { stripDataUri } from "../../utils/files/image-store.js";
+import { writeJsonAtomic } from "../../utils/files/json.js";
 import {
   getFileObject,
   initializeContextFromFiles,
@@ -26,6 +27,7 @@ import { slugify } from "../../utils/slug.js";
 import { resolveWithinRoot } from "../../utils/files/safe.js";
 import { errorMessage } from "../../utils/errors.js";
 import { badRequest, notFound, serverError } from "../../utils/httpError.js";
+import { getOptionalStringQuery } from "../../utils/request.js";
 import { log } from "../../system/logger/index.js";
 import { validateUpdateBeatBody, validateUpdateScriptBody } from "./mulmoScriptValidate.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
@@ -54,8 +56,8 @@ let storiesRealCache: string | null = null;
 function ensureStoriesReal(): string | null {
   if (storiesRealCache) return storiesRealCache;
   try {
-    fs.mkdirSync(storiesDir, { recursive: true });
-    storiesRealCache = fs.realpathSync(storiesDir);
+    mkdirSync(storiesDir, { recursive: true });
+    storiesRealCache = realpathSync(storiesDir);
     return storiesRealCache;
   } catch {
     return null;
@@ -96,7 +98,7 @@ interface FilePathQuery {
   filePath?: string;
 }
 
-router.post(API_ROUTES.mulmoScript.save, (req: Request<object, object, SaveMulmoScriptBody>, res: Response) => {
+router.post(API_ROUTES.mulmoScript.save, async (req: Request<object, object, SaveMulmoScriptBody>, res: Response) => {
   const { script, filename } = req.body;
 
   if (!script || !Array.isArray(script.beats)) {
@@ -104,14 +106,14 @@ router.post(API_ROUTES.mulmoScript.save, (req: Request<object, object, SaveMulmo
     return;
   }
 
-  fs.mkdirSync(storiesDir, { recursive: true });
+  mkdirSync(storiesDir, { recursive: true });
 
   const title = script.title || "untitled";
   const slug = filename ? filename.replace(/\.json$/, "") : slugify(title);
   const fname = `${slug}-${Date.now()}.json`;
   const filePath = path.join(storiesDir, fname);
 
-  fs.writeFileSync(filePath, JSON.stringify(script, null, 2));
+  await writeJsonAtomic(filePath, script);
 
   res.json({
     data: { script, filePath: `stories/${fname}` },
@@ -120,7 +122,7 @@ router.post(API_ROUTES.mulmoScript.save, (req: Request<object, object, SaveMulmo
   });
 });
 
-router.post(API_ROUTES.mulmoScript.updateBeat, (req: Request<object, object, unknown>, res: Response) => {
+router.post(API_ROUTES.mulmoScript.updateBeat, async (req: Request<object, object, unknown>, res: Response) => {
   const validation = validateUpdateBeatBody(req.body);
   if (!validation.ok) {
     badRequest(res, validation.error);
@@ -131,7 +133,7 @@ router.post(API_ROUTES.mulmoScript.updateBeat, (req: Request<object, object, unk
   const absoluteFilePath = resolveStoryPath(filePath, res);
   if (!absoluteFilePath) return;
 
-  const script: MulmoScript = JSON.parse(fs.readFileSync(absoluteFilePath, "utf-8"));
+  const script: MulmoScript = JSON.parse(readFileSync(absoluteFilePath, "utf-8"));
 
   if (!Array.isArray(script.beats) || beatIndex >= script.beats.length) {
     badRequest(res, "Invalid beatIndex");
@@ -139,12 +141,12 @@ router.post(API_ROUTES.mulmoScript.updateBeat, (req: Request<object, object, unk
   }
 
   script.beats[beatIndex] = beat as MulmoBeat;
-  fs.writeFileSync(absoluteFilePath, JSON.stringify(script, null, 2));
+  await writeJsonAtomic(absoluteFilePath, script);
 
   res.json({ ok: true });
 });
 
-router.post(API_ROUTES.mulmoScript.updateScript, (req: Request<object, object, unknown>, res: Response) => {
+router.post(API_ROUTES.mulmoScript.updateScript, async (req: Request<object, object, unknown>, res: Response) => {
   const validation = validateUpdateScriptBody(req.body);
   if (!validation.ok) {
     badRequest(res, validation.error);
@@ -155,7 +157,7 @@ router.post(API_ROUTES.mulmoScript.updateScript, (req: Request<object, object, u
   const absoluteFilePath = resolveStoryPath(filePath, res);
   if (!absoluteFilePath) return;
 
-  fs.writeFileSync(absoluteFilePath, JSON.stringify(updatedScript, null, 2));
+  await writeJsonAtomic(absoluteFilePath, updatedScript);
   res.json({ ok: true });
 });
 
@@ -170,7 +172,7 @@ router.get(API_ROUTES.mulmoScript.beatImage, async (req: Request<object, BeatIma
 
   await withStoryContext(res, filePath, {}, async ({ context }) => {
     const { imagePath } = getBeatPngImagePath(context, beatIndex);
-    if (!fs.existsSync(imagePath)) {
+    if (!existsSync(imagePath)) {
       res.json({ image: null });
       return;
     }
@@ -197,13 +199,13 @@ router.get(API_ROUTES.mulmoScript.movieStatus, async (req: Request<object, Movie
     }
 
     const outputPath = movieFilePath(context);
-    if (!fs.existsSync(outputPath)) {
+    if (!existsSync(outputPath)) {
       res.json({ moviePath: null });
       return;
     }
 
-    const movieMtime = fs.statSync(outputPath).mtimeMs;
-    const sourceMtime = fs.statSync(absoluteFilePath).mtimeMs;
+    const movieMtime = statSync(outputPath).mtimeMs;
+    const sourceMtime = statSync(absoluteFilePath).mtimeMs;
     if (movieMtime < sourceMtime) {
       res.json({ moviePath: null });
       return;
@@ -216,7 +218,7 @@ router.get(API_ROUTES.mulmoScript.movieStatus, async (req: Request<object, Movie
 });
 
 function fileToDataUri(filePath: string, mimeType: string): string {
-  const data = fs.readFileSync(filePath);
+  const data = readFileSync(filePath);
   return `data:${mimeType};base64,${data.toString("base64")}`;
 }
 
@@ -257,7 +259,7 @@ function resolveStoryPath(filePath: string, res: Response): string | null {
   const resolved = resolveWithinRoot(storiesReal, relFromStories);
   if (!resolved) {
     const candidate = path.resolve(storiesReal, relFromStories);
-    if (!fs.existsSync(candidate)) {
+    if (!existsSync(candidate)) {
       notFound(res, `File not found: ${filePath}`);
     } else {
       badRequest(res, "Invalid filePath");
@@ -373,12 +375,12 @@ router.get(API_ROUTES.mulmoScript.beatAudio, async (req: Request<object, BeatAud
     filePath,
     {
       operation: "beat-audio",
-      onContextMissing: (r) => r.json({ audio: null }),
+      onContextMissing: (response) => response.json({ audio: null }),
     },
     async ({ context }) => {
       const beat = context.studio.script.beats[beatIndex];
       const audioPath = getBeatAudioPathOrUrl(beat.text ?? "", context, beat, context.lang);
-      if (!audioPath || !fs.existsSync(audioPath)) {
+      if (!audioPath || !existsSync(audioPath)) {
         res.json({ audio: null });
         return;
       }
@@ -422,7 +424,7 @@ router.post(
           const beat = context.studio.script.beats[beatIndex];
           const audioPath = context.studio.beats[beatIndex]?.audioFile ?? getBeatAudioPathOrUrl(beat.text ?? "", context, beat, context.lang);
 
-          if (!audioPath || !fs.existsSync(audioPath)) {
+          if (!audioPath || !existsSync(audioPath)) {
             // Logic-flow failure (not an exception) — emit a targeted
             // log. Don't write raw `beat.text` into persistent logs —
             // it's free-form user content and can contain sensitive
@@ -430,7 +432,7 @@ router.post(
             log.error("generate-beat-audio", "audio was not generated", {
               beatIndex,
               audioPath,
-              exists: audioPath ? fs.existsSync(audioPath) : false,
+              exists: audioPath ? existsSync(audioPath) : false,
               beatTextLength: typeof beat?.text === "string" ? beat.text.length : 0,
               audioFilePresent: Boolean(context.studio.beats[beatIndex]?.audioFile),
             });
@@ -475,7 +477,7 @@ router.post(API_ROUTES.mulmoScript.renderBeat, async (req: Request<object, objec
         });
 
         const { imagePath } = getBeatPngImagePath(context, beatIndex);
-        if (!fs.existsSync(imagePath)) {
+        if (!existsSync(imagePath)) {
           genError = "Image was not generated";
           serverError(res, genError);
           return;
@@ -542,7 +544,7 @@ router.post(API_ROUTES.mulmoScript.generateMovie, async (req: Request<object, ob
       await movie(audioContext);
 
       const outputPath = movieFilePath(audioContext);
-      if (!fs.existsSync(outputPath)) {
+      if (!existsSync(outputPath)) {
         genError = "Movie was not generated";
         send({ type: "error", message: genError });
         res.end();
@@ -594,7 +596,7 @@ router.get(
 
     await withStoryContext(res, filePath, {}, async ({ context }) => {
       const imagePath = getReferenceImagePath(context, key, "png");
-      if (!fs.existsSync(imagePath)) {
+      if (!existsSync(imagePath)) {
         res.json({ image: null });
         return;
       }
@@ -613,10 +615,10 @@ router.post(API_ROUTES.mulmoScript.uploadBeatImage, async (req: Request<object,
 
   await withStoryContext(res, filePath, {}, async ({ context }) => {
     const { imagePath } = getBeatPngImagePath(context, beatIndex);
-    fs.mkdirSync(path.dirname(imagePath), { recursive: true });
+    mkdirSync(path.dirname(imagePath), { recursive: true });
 
     const base64 = stripDataUri(imageData);
-    fs.writeFileSync(imagePath, Buffer.from(base64, "base64"));
+    writeFileSync(imagePath, Buffer.from(base64, "base64"));
 
     res.json({ image: fileToDataUri(imagePath, "image/png") });
   });
@@ -647,7 +649,7 @@ router.post(
 
           const index = Object.keys(images).indexOf(key);
           const imagePath = getReferenceImagePath(context, key, "png");
-          fs.mkdirSync(path.dirname(imagePath), { recursive: true });
+          mkdirSync(path.dirname(imagePath), { recursive: true });
 
           await generateReferenceImage({
             context,
@@ -656,7 +658,7 @@ router.post(
             image: imageEntry as MulmoImagePromptMedia,
             force,
           });
-          if (!fs.existsSync(imagePath)) {
+          if (!existsSync(imagePath)) {
             genError = "Character image was not generated";
             serverError(res, genError);
             return;
@@ -685,10 +687,10 @@ router.post(
 
     await withStoryContext(res, filePath, {}, async ({ context }) => {
       const imagePath = getReferenceImagePath(context, key, "png");
-      fs.mkdirSync(path.dirname(imagePath), { recursive: true });
+      mkdirSync(path.dirname(imagePath), { recursive: true });
 
       const base64 = stripDataUri(imageData);
-      fs.writeFileSync(imagePath, Buffer.from(base64, "base64"));
+      writeFileSync(imagePath, Buffer.from(base64, "base64"));
 
       res.json({ image: fileToDataUri(imagePath, "image/png") });
     });
@@ -696,7 +698,7 @@ router.post(
 );
 
 router.get(API_ROUTES.mulmoScript.downloadMovie, (req: Request, res: Response) => {
-  const moviePath = typeof req.query.moviePath === "string" ? req.query.moviePath : undefined;
+  const moviePath = getOptionalStringQuery(req, "moviePath");
 
   if (!moviePath) {
     badRequest(res, "moviePath is required");

package/server/api/routes/pdf.ts

@@ -1,4 +1,4 @@
-import fs from "fs";
+import { realpathSync } from "fs";
 import path from "path";
 import { Router, Request, Response } from "express";
 import { marked } from "marked";
@@ -56,7 +56,7 @@ const MIME_BY_EXT: Record<string, string> = {
 // Realpath of the workspace, resolved once at module load. Used to
 // validate that image paths resolved relative to markdowns/ stay
 // inside the workspace after symlink resolution.
-const workspaceReal = fs.realpathSync(resolveWorkspacePath(""));
+const workspaceReal = realpathSync(resolveWorkspacePath(""));
 
 /**
  * Inline local images as base64 data URIs so Puppeteer can render them.

package/server/api/routes/plugins.ts

@@ -80,10 +80,10 @@ async function fillImagePlaceholders(markdown: string): Promise<string> {
   }
 
   const results = await Promise.all(
-    matches.map(async (m) => ({
-      full: m[0],
-      prompt: m[1],
-      url: geminiOk ? await generateImageFile(m[1]) : null,
+    matches.map(async (match) => ({
+      full: match[0],
+      prompt: match[1],
+      url: geminiOk ? await generateImageFile(match[1]) : null,
     })),
   );
 
@@ -91,7 +91,7 @@ async function fillImagePlaceholders(markdown: string): Promise<string> {
   // success rate even when most calls go through. The per-call
   // error already lands at warn from generateImageFile's catch.
   if (geminiOk) {
-    const failed = results.filter((r) => !r.url).length;
+    const failed = results.filter((result) => !result.url).length;
     if (failed > 0) {
       log.warn("present-document", "image generation had failures", {
         failed,
@@ -261,10 +261,20 @@ router.post(
   wrapPluginExecute((req) => executeForm(null as never, req.body)),
 );
 
+// 1×1 transparent PNG. Used as a placeholder so the canvas tool
+// result can carry a stable file path from the moment the canvas
+// is opened — client autosaves PUT-overwrite this same file, so the
+// drawing survives page reload with zero client→server sync.
+const BLANK_PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkAAIAAAoAAv/lxKUAAAAASUVORK5CYII=";
+
 // openCanvas — drawing canvas
 router.post(
   API_ROUTES.plugins.canvas,
-  wrapPluginExecute(() => executeOpenCanvas()),
+  wrapPluginExecute(async () => {
+    const imagePath = await saveImage(BLANK_PNG_BASE64);
+    const base = await executeOpenCanvas();
+    return { ...base, data: { imageData: imagePath, prompt: "" } };
+  }),
 );
 
 // present3d — 3D visualization

package/server/api/routes/roles.ts

@@ -7,7 +7,7 @@ import { API_ROUTES } from "../../../src/config/apiRoutes.js";
 import { EVENT_TYPES } from "../../../src/types/events.js";
 import { roleExists, deleteRole, saveRole } from "../../utils/files/roles-io.js";
 
-const BUILTIN_IDS = new Set(BUILTIN_ROLES.map((r) => r.id));
+const BUILTIN_IDS = new Set(BUILTIN_ROLES.map((role) => role.id));
 
 const router = Router();
 
@@ -98,7 +98,7 @@ function saveRoleResult(input: ManageRolesInput, sessionId: string): Record<stri
   const pluginsToSave = role.availablePlugins ?? [];
   const roleToSave = {
     ...role,
-    availablePlugins: pluginsToSave.filter((p) => p !== "switchRole"),
+    availablePlugins: pluginsToSave.filter((plugin) => plugin !== "switchRole"),
   };
 
   saveRole(role.id, roleToSave);

package/server/api/routes/scheduler.ts

@@ -9,6 +9,8 @@ import { saveUserTasks } from "../../utils/files/user-tasks-io.js";
 import { startChat } from "./agent.js";
 import { log } from "../../system/logger/index.js";
 import { SCHEDULER_ACTIONS, TASK_ACTIONS } from "../../../src/config/schedulerActions.js";
+import { badRequest, notFound, serverError } from "../../utils/httpError.js";
+import { errorMessage } from "../../utils/errors.js";
 
 const router = Router();
 
@@ -77,7 +79,7 @@ async function handleTaskAction(action: string, input: Record<string, unknown>,
     if (action === SCHEDULER_ACTIONS.createTask) {
       const result = validateAndCreate(input);
       if (result.kind === "error") {
-        res.status(400).json({ error: result.error });
+        badRequest(res, result.error);
         return;
       }
       const tasks = loadUserTasks();
@@ -97,7 +99,7 @@ async function handleTaskAction(action: string, input: Record<string, unknown>,
       const tasks = loadUserTasks();
       const idx = tasks.findIndex((task) => task.id === taskId);
       if (idx === -1) {
-        res.status(404).json({ error: `task not found: ${taskId}` });
+        notFound(res, `task not found: ${taskId}`);
         return;
       }
       const name = tasks[idx].name;
@@ -117,7 +119,7 @@ async function handleTaskAction(action: string, input: Record<string, unknown>,
       const tasks = loadUserTasks();
       const task = tasks.find((candidate) => candidate.id === taskId);
       if (!task) {
-        res.status(404).json({ error: `task not found: ${taskId}` });
+        notFound(res, `task not found: ${taskId}`);
         return;
       }
       const chatSessionId = crypto.randomUUID();
@@ -143,10 +145,10 @@ async function handleTaskAction(action: string, input: Record<string, unknown>,
       return;
     }
 
-    res.status(400).json({ error: `unknown task action: ${action}` });
+    badRequest(res, `unknown task action: ${action}`);
   } catch (err) {
-    log.error("scheduler", "task action failed", { error: String(err) });
-    res.status(500).json({ error: "Internal server error" });
+    log.error("scheduler", "task action failed", { error: errorMessage(err) });
+    serverError(res, "Internal server error");
   }
 }
 

package/server/api/routes/schedulerTasks.ts

@@ -15,6 +15,7 @@ import { SESSION_ORIGINS } from "../../../src/types/session.js";
 import { loadUserTasks, validateAndCreate, applyUpdate, withUserTaskLock } from "../../workspace/skills/user-tasks.js";
 import { badRequest, notFound, serverError } from "../../utils/httpError.js";
 import { errorMessage } from "../../utils/errors.js";
+import { getOptionalStringQuery } from "../../utils/request.js";
 import { log } from "../../system/logger/index.js";
 import { startChat } from "./agent.js";
 
@@ -150,11 +151,12 @@ interface LogQuery {
 
 router.get(API_ROUTES.scheduler.logs, async (req: Request<object, unknown, object, LogQuery>, res: Response<{ logs: TaskLogEntry[] }>) => {
   const MAX_LIMIT = 500;
-  const rawLimit = typeof req.query.limit === "string" ? parseInt(req.query.limit, 10) : undefined;
+  const rawLimitStr = getOptionalStringQuery(req, "limit");
+  const rawLimit = rawLimitStr ? parseInt(rawLimitStr, 10) : undefined;
   const limit = Number.isFinite(rawLimit) && rawLimit! > 0 ? Math.min(rawLimit!, MAX_LIMIT) : undefined;
   const logs = await getSchedulerLogs({
-    since: typeof req.query.since === "string" ? req.query.since : undefined,
-    taskId: typeof req.query.taskId === "string" ? req.query.taskId : undefined,
+    since: getOptionalStringQuery(req, "since"),
+    taskId: getOptionalStringQuery(req, "taskId"),
     limit,
   });
   res.json({ logs });

package/server/api/routes/sessions.ts

@@ -1,5 +1,5 @@
 import { Router, Request, Response } from "express";
-import fs from "fs";
+import { realpathSync } from "fs";
 import { readdir, stat } from "fs/promises";
 import { readTextSafe } from "../../utils/files/safe.js";
 import path from "path";
@@ -242,7 +242,7 @@ router.get(API_ROUTES.sessions.detail, async (req: Request<SessionIdParams>, res
                   const storiesDir = path.resolve(WORKSPACE_PATHS.stories);
                   let storiesReal: string;
                   try {
-                    storiesReal = fs.realpathSync(storiesDir);
+                    storiesReal = realpathSync(storiesDir);
                   } catch {
                     return entry;
                   }

package/server/api/routes/sessionsCursor.ts

@@ -21,8 +21,8 @@ const CURSOR_PREFIX = "v1:";
  * fall back to when an incoming cursor is malformed.
  */
 export function encodeCursor(changeMs: number): string {
-  const ms = Number.isFinite(changeMs) && changeMs > 0 ? Math.floor(changeMs) : 0;
-  return `${CURSOR_PREFIX}${ms}`;
+  const floored = Number.isFinite(changeMs) && changeMs > 0 ? Math.floor(changeMs) : 0;
+  return `${CURSOR_PREFIX}${floored}`;
 }
 
 /**
@@ -36,8 +36,8 @@ export function encodeCursor(changeMs: number): string {
 export function parseCursor(raw: unknown): number {
   if (typeof raw !== "string") return 0;
   if (!raw.startsWith(CURSOR_PREFIX)) return 0;
-  const n = Number(raw.slice(CURSOR_PREFIX.length));
-  return Number.isFinite(n) && n > 0 ? n : 0;
+  const parsed = Number(raw.slice(CURSOR_PREFIX.length));
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
 }
 
 /**

package/server/api/routes/skills.ts

@@ -55,17 +55,17 @@ interface DeleteSkillResponse {
 router.get(API_ROUTES.skills.list, async (_req: Request, res: Response<SkillsListResponse>) => {
   const skills = await discoverSkills({ workspaceRoot: workspacePath });
   res.json({
-    skills: skills.map((s) => ({
-      name: s.name,
-      description: s.description,
-      source: s.source,
+    skills: skills.map((skill) => ({
+      name: skill.name,
+      description: skill.description,
+      source: skill.source,
     })),
   });
 });
 
 router.get(API_ROUTES.skills.detail, async (req: Request<{ name: string }>, res: Response<SkillDetailResponse | ErrorResponse>) => {
   const skills = await discoverSkills({ workspaceRoot: workspacePath });
-  const skill = skills.find((s) => s.name === req.params.name);
+  const skill = skills.find((candidate) => candidate.name === req.params.name);
   if (!skill) {
     notFound(res, `skill not found: ${req.params.name}`);
     return;

package/server/api/routes/sources.ts

@@ -312,7 +312,7 @@ async function handleRegister(body: ManageSourceBody, res: Response<ManageSource
 async function handleRemove(body: ManageSourceBody, res: Response<ManageSourceSuccess | ErrorResponse>): Promise<void> {
   const slug = typeof body.slug === "string" ? body.slug.trim() : "";
   if (!isValidSlug(slug)) {
-    res.status(400).json({ error: "slug is required and must be a valid slug" });
+    badRequest(res, "slug is required and must be a valid slug");
     return;
   }
   const removed = await deleteSource(workspacePath, slug);
@@ -525,8 +525,8 @@ async function resolveCategories(parsed: ParsedRegisterBody): Promise<{ categori
 
 function isHttpUrl(raw: string): boolean {
   try {
-    const u = new URL(raw);
-    return u.protocol === "http:" || u.protocol === "https:";
+    const url = new URL(raw);
+    return url.protocol === "http:" || url.protocol === "https:";
   } catch {
     return false;
   }

package/server/api/routes/todosHandlers.ts

@@ -242,7 +242,7 @@ export function handleRemoveLabel(items: TodoItem[], input: TodosActionInput): T
 
 export function handleListLabels(items: TodoItem[]): TodosActionResult {
   const inventory = listLabelsWithCount(items);
-  const summary = inventory.map((l) => `${l.label} (${l.count})`).join(", ");
+  const summary = inventory.map((entry) => `${entry.label} (${entry.count})`).join(", ");
   const message = inventory.length === 0 ? "No labels in use" : `${inventory.length} label(s) in use: ${summary}`;
   return {
     kind: "success",