mulmoclaude 0.3.0 → 0.4.0

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

@@ -1,4 +1,4 @@
-import fs from "fs/promises";
+import { mkdir, readFile, realpath, writeFile } from "fs/promises";
 import path from "path";
 import crypto from "crypto";
 import { WORKSPACE_DIRS, WORKSPACE_PATHS } from "../../workspace/paths.js";
@@ -12,8 +12,8 @@ let imagesDirReal: string | null = null;
 
 async function ensureImagesDir(): Promise<string> {
   if (imagesDirReal) return imagesDirReal;
-  await fs.mkdir(IMAGES_DIR, { recursive: true });
-  imagesDirReal = await fs.realpath(IMAGES_DIR);
+  await mkdir(IMAGES_DIR, { recursive: true });
+  imagesDirReal = await realpath(IMAGES_DIR);
   return imagesDirReal;
 }
 
@@ -38,20 +38,20 @@ export async function saveImage(base64Data: string): Promise<string> {
   const imageId = crypto.randomUUID().replace(/-/g, "").slice(0, 16);
   const filename = `${imageId}.png`;
   const absPath = path.join(IMAGES_DIR, filename);
-  await fs.writeFile(absPath, Buffer.from(base64Data, "base64"));
+  await writeFile(absPath, Buffer.from(base64Data, "base64"));
   return path.posix.join(WORKSPACE_DIRS.images, filename);
 }
 
 /** Overwrite an existing image file. The relativePath must start with "images/". */
 export async function overwriteImage(relativePath: string, base64Data: string): Promise<void> {
   const absPath = await safeResolve(relativePath);
-  await fs.writeFile(absPath, Buffer.from(base64Data, "base64"));
+  await writeFile(absPath, Buffer.from(base64Data, "base64"));
 }
 
 /** Read an image file and return raw base64 (no data URI prefix). */
 export async function loadImageBase64(relativePath: string): Promise<string> {
   const absPath = await safeResolve(relativePath);
-  const buf = await fs.readFile(absPath);
+  const buf = await readFile(absPath);
   return buf.toString("base64");
 }
 
@@ -64,3 +64,14 @@ export function stripDataUri(dataUri: string): string {
 export function isImagePath(value: string): boolean {
   return value.startsWith(`${WORKSPACE_DIRS.images}/`) && value.endsWith(".png");
 }
+
+/** Build the workspace-relative image path for a filename, or null
+ *  if the derived path wouldn't satisfy `isImagePath` (e.g. empty
+ *  name, wrong extension). Keeps route handlers from reaching for
+ *  `WORKSPACE_DIRS.images` directly — the images/ convention lives
+ *  in exactly one place. */
+export function imagePathFromFilename(filename: string): string | null {
+  if (!filename) return null;
+  const relativePath = path.posix.join(WORKSPACE_DIRS.images, filename);
+  return isImagePath(relativePath) ? relativePath : null;
+}

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

@@ -17,7 +17,7 @@ import { isEnoent } from "./safe.js";
 import { log } from "../../system/logger/index.js";
 import { summariesRoot, dailyPathFor, topicPathFor, TOPICS_DIR, INDEX_FILE, STATE_FILE, DAILY_DIR, ARCHIVE_DIR } from "../../workspace/journal/paths.js";
 
-import fs from "node:fs";
+import { statSync } from "node:fs";
 
 const root = (rootOverride?: string) => rootOverride ?? workspacePath;
 
@@ -26,7 +26,7 @@ const root = (rootOverride?: string) => rootOverride ?? workspacePath;
 export function journalStateExists(rootOverride?: string): boolean {
   const filePath = path.join(summariesRoot(root(rootOverride)), STATE_FILE);
   try {
-    fs.statSync(filePath);
+    statSync(filePath);
     return true;
   } catch {
     return false;

package/server/utils/files/json.ts

@@ -3,7 +3,7 @@
 // Moved from server/utils/file.ts (issue #366 Phase 1). The old
 // file re-exports these for backwards compat.
 
-import fs from "fs";
+import { mkdirSync, promises, readFileSync, writeFileSync } from "fs";
 import path from "path";
 import { writeFileAtomic } from "./atomic.js";
 import { isEnoent } from "./safe.js";
@@ -20,7 +20,7 @@ import { log } from "../../system/logger/index.js";
 export function loadJsonFile<T>(filePath: string, defaultValue: T): T {
   let raw: string;
   try {
-    raw = fs.readFileSync(filePath, "utf-8");
+    raw = readFileSync(filePath, "utf-8");
   } catch (err) {
     if (isEnoent(err)) return defaultValue;
     log.error("json", "loadJsonFile read failed", {
@@ -41,8 +41,8 @@ export function loadJsonFile<T>(filePath: string, defaultValue: T): T {
 }
 
 export function saveJsonFile(filePath: string, data: unknown): void {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(data, null, 2));
 }
 
 // ── Async ───────────────────────────────────────────────────────
@@ -60,7 +60,7 @@ export async function writeJsonAtomic(filePath: string, data: unknown, opts: Par
  */
 export async function readJsonOrNull<T>(filePath: string): Promise<T | null> {
   try {
-    const content = await fs.promises.readFile(filePath, "utf-8");
+    const content = await promises.readFile(filePath, "utf-8");
     const parsed: T = JSON.parse(content);
     return parsed;
   } catch {

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

@@ -1,4 +1,4 @@
-import fs from "fs/promises";
+import { readFile, writeFile } from "fs/promises";
 import path from "path";
 import { workspacePath } from "../../workspace/workspace.js";
 import { WORKSPACE_DIRS } from "../../workspace/paths.js";
@@ -11,20 +11,20 @@ import { buildArtifactPathRandom } from "./naming.js";
  */
 export async function saveMarkdown(content: string, prefix: string): Promise<string> {
   const relPath = buildArtifactPathRandom(WORKSPACE_DIRS.markdowns, prefix, ".md", "document");
-  await fs.writeFile(path.join(workspacePath, relPath), content, "utf-8");
+  await writeFile(path.join(workspacePath, relPath), content, "utf-8");
   return relPath;
 }
 
 /** Read a markdown file and return its content. */
 export async function loadMarkdown(relativePath: string): Promise<string> {
   const absPath = path.join(workspacePath, relativePath);
-  return fs.readFile(absPath, "utf-8");
+  return readFile(absPath, "utf-8");
 }
 
 /** Overwrite an existing markdown file. */
 export async function overwriteMarkdown(relativePath: string, content: string): Promise<void> {
   const absPath = path.join(workspacePath, relativePath);
-  await fs.writeFile(absPath, content, "utf-8");
+  await writeFile(absPath, content, "utf-8");
 }
 
 /** Check if a string is a markdown file path (not inline content). */

package/server/utils/files/reference-dirs-io.ts

@@ -4,7 +4,7 @@
 // All fs access is funneled through shared helpers so path changes
 // propagate from a single constant.
 
-import fs from "fs";
+import { mkdirSync, statSync } from "fs";
 import path from "path";
 import { WORKSPACE_DIRS, workspacePath } from "../../workspace/paths.js";
 import { loadJsonFile } from "./json.js";
@@ -31,14 +31,14 @@ export function readReferenceDirsJson(root?: string): unknown[] {
 /** Write reference-dirs.json atomically. Creates config/ if needed. */
 export function writeReferenceDirsJson(entries: readonly unknown[], root?: string): void {
   const filePath = configPath(root ?? workspacePath);
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  mkdirSync(path.dirname(filePath), { recursive: true });
   writeFileAtomicSync(filePath, JSON.stringify(entries, null, 2));
 }
 
 /** Check whether a host path exists and is a directory. */
 export function isExistingDirectory(hostPath: string): boolean {
   try {
-    return fs.statSync(hostPath).isDirectory();
+    return statSync(hostPath).isDirectory();
   } catch {
     return false;
   }

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

@@ -4,7 +4,7 @@
 // Optional `root` for test DI.
 
 import path from "node:path";
-import fs from "node:fs";
+import { mkdirSync, statSync, unlinkSync } from "node:fs";
 import { WORKSPACE_DIRS } from "../../workspace/paths.js";
 import { workspacePath } from "../../workspace/paths.js";
 import { writeFileAtomicSync } from "./atomic.js";
@@ -19,7 +19,7 @@ function roleFilePath(roleId: string, workspaceRoot?: string): string {
 /** Check if a custom role file exists. */
 export function roleExists(roleId: string, workspaceRoot?: string): boolean {
   try {
-    fs.statSync(roleFilePath(roleId, workspaceRoot));
+    statSync(roleFilePath(roleId, workspaceRoot));
     return true;
   } catch {
     return false;
@@ -29,7 +29,7 @@ export function roleExists(roleId: string, workspaceRoot?: string): boolean {
 /** Delete a custom role file. Returns false if not found. */
 export function deleteRole(roleId: string, workspaceRoot?: string): boolean {
   try {
-    fs.unlinkSync(roleFilePath(roleId, workspaceRoot));
+    unlinkSync(roleFilePath(roleId, workspaceRoot));
     return true;
   } catch (err) {
     if (isEnoent(err)) return false;
@@ -40,6 +40,6 @@ export function deleteRole(roleId: string, workspaceRoot?: string): boolean {
 /** Save (create or overwrite) a custom role file atomically. */
 export function saveRole(roleId: string, data: unknown, workspaceRoot?: string): void {
   const dir = path.join(root(workspaceRoot), WORKSPACE_DIRS.roles);
-  fs.mkdirSync(dir, { recursive: true });
+  mkdirSync(dir, { recursive: true });
   writeFileAtomicSync(roleFilePath(roleId, workspaceRoot), JSON.stringify(data, null, 2));
 }

package/server/utils/files/safe.ts

@@ -7,7 +7,7 @@
 // Moved from server/utils/fs.ts (issue #366 Phase 1). The old
 // file re-exports these for backwards compat.
 
-import fs from "fs";
+import { Dirent, Stats, promises, readFileSync, readdirSync, realpathSync, statSync } from "fs";
 import path from "path";
 import { isErrorWithCode } from "../types.js";
 
@@ -19,7 +19,7 @@ export function isEnoent(err: unknown): boolean {
 /** Read a binary file by absolute path. Null on ENOENT. */
 export function readBinarySafeSync(absPath: string): Buffer | null {
   try {
-    return fs.readFileSync(absPath);
+    return readFileSync(absPath);
   } catch {
     return null;
   }
@@ -28,7 +28,7 @@ export function readBinarySafeSync(absPath: string): Buffer | null {
 /** Read a text file by absolute path (async). Null on ENOENT. */
 export async function readTextSafe(absPath: string): Promise<string | null> {
   try {
-    return await fs.promises.readFile(absPath, "utf-8");
+    return await promises.readFile(absPath, "utf-8");
   } catch {
     return null;
   }
@@ -37,39 +37,39 @@ export async function readTextSafe(absPath: string): Promise<string | null> {
 /** Read a text file by absolute path (sync). Null on ENOENT. */
 export function readTextSafeSync(absPath: string): string | null {
   try {
-    return fs.readFileSync(absPath, "utf-8");
+    return readFileSync(absPath, "utf-8");
   } catch {
     return null;
   }
 }
 
-export function statSafe(absPath: string): fs.Stats | null {
+export function statSafe(absPath: string): Stats | null {
   try {
-    return fs.statSync(absPath);
+    return statSync(absPath);
   } catch {
     return null;
   }
 }
 
-export async function statSafeAsync(absPath: string): Promise<fs.Stats | null> {
+export async function statSafeAsync(absPath: string): Promise<Stats | null> {
   try {
-    return await fs.promises.stat(absPath);
+    return await promises.stat(absPath);
   } catch {
     return null;
   }
 }
 
-export function readDirSafe(absPath: string): fs.Dirent[] {
+export function readDirSafe(absPath: string): Dirent[] {
   try {
-    return fs.readdirSync(absPath, { withFileTypes: true });
+    return readdirSync(absPath, { withFileTypes: true });
   } catch {
     return [];
   }
 }
 
-export async function readDirSafeAsync(absPath: string): Promise<fs.Dirent[]> {
+export async function readDirSafeAsync(absPath: string): Promise<Dirent[]> {
   try {
-    return await fs.promises.readdir(absPath, { withFileTypes: true });
+    return await promises.readdir(absPath, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -77,7 +77,7 @@ export async function readDirSafeAsync(absPath: string): Promise<fs.Dirent[]> {
 
 export async function readTextOrNull(file: string): Promise<string | null> {
   try {
-    return await fs.promises.readFile(file, "utf-8");
+    return await promises.readFile(file, "utf-8");
   } catch {
     return null;
   }
@@ -95,7 +95,7 @@ export function resolveWithinRoot(rootReal: string, relPath: string): string | n
   const resolved = path.resolve(rootReal, normalized);
   let resolvedReal: string;
   try {
-    resolvedReal = fs.realpathSync(resolved);
+    resolvedReal = realpathSync(resolved);
   } catch {
     return null;
   }

package/server/utils/files/scheduler-overrides-io.ts

@@ -4,7 +4,7 @@
 // system task ID (e.g. "system:journal"), value overrides the
 // default schedule.
 
-import fs from "fs";
+import { mkdirSync } from "fs";
 import path from "path";
 import { workspacePath } from "../../workspace/paths.js";
 import { WORKSPACE_FILES } from "../../../src/config/workspacePaths.js";
@@ -59,6 +59,6 @@ export function loadSchedulerOverrides(root?: string): ScheduleOverrides {
 /** Save schedule overrides atomically. Creates directory if needed. */
 export function saveSchedulerOverrides(overrides: ScheduleOverrides, root?: string): void {
   const filePath = overridesPath(root);
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  mkdirSync(path.dirname(filePath), { recursive: true });
   writeFileAtomicSync(filePath, JSON.stringify(overrides, null, 2));
 }

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

@@ -1,4 +1,4 @@
-import fs from "fs/promises";
+import { mkdir, realpath, writeFile } from "fs/promises";
 import path from "path";
 import crypto from "crypto";
 import { WORKSPACE_DIRS, WORKSPACE_PATHS } from "../../workspace/paths.js";
@@ -13,8 +13,8 @@ let spreadsheetsDirReal: string | null = null;
 
 async function ensureSpreadsheetsDir(): Promise<string> {
   if (spreadsheetsDirReal) return spreadsheetsDirReal;
-  await fs.mkdir(SPREADSHEETS_DIR, { recursive: true });
-  spreadsheetsDirReal = await fs.realpath(SPREADSHEETS_DIR);
+  await mkdir(SPREADSHEETS_DIR, { recursive: true });
+  spreadsheetsDirReal = await realpath(SPREADSHEETS_DIR);
   return spreadsheetsDirReal;
 }
 
@@ -38,14 +38,14 @@ export async function saveSpreadsheet(sheets: unknown[]): Promise<string> {
   await ensureSpreadsheetsDir();
   const sheetId = crypto.randomUUID().replace(/-/g, "").slice(0, 16);
   const filename = `${sheetId}.json`;
-  await fs.writeFile(path.join(SPREADSHEETS_DIR, filename), JSON.stringify(sheets), "utf-8");
+  await writeFile(path.join(SPREADSHEETS_DIR, filename), JSON.stringify(sheets), "utf-8");
   return path.posix.join(WORKSPACE_DIRS.spreadsheets, filename);
 }
 
 /** Overwrite an existing spreadsheet file. */
 export async function overwriteSpreadsheet(relativePath: string, sheets: unknown[]): Promise<void> {
   const absPath = await safeResolve(relativePath);
-  await fs.writeFile(absPath, JSON.stringify(sheets), "utf-8");
+  await writeFile(absPath, JSON.stringify(sheets), "utf-8");
 }
 
 /** Check if a string is a spreadsheet file path (not inline data).

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

@@ -11,7 +11,7 @@
 // All reads swallow ENOENT and return null / fallback so callers can
 // do `if (!content)` instead of try/catch.
 
-import fs from "fs";
+import { Stats, mkdirSync, promises, readFileSync, readdirSync, statSync } from "fs";
 import path from "path";
 import { workspacePath } from "../../workspace/paths.js";
 import { writeFileAtomic, writeFileAtomicSync } from "./atomic.js";
@@ -44,7 +44,7 @@ export function resolveWorkspacePath(relPath: string): string {
  */
 export async function readWorkspaceText(relPath: string): Promise<string | null> {
   try {
-    return await fs.promises.readFile(resolveWorkspacePath(relPath), "utf-8");
+    return await promises.readFile(resolveWorkspacePath(relPath), "utf-8");
   } catch (err) {
     return rethrowUnexpected(err, `readWorkspaceText(${relPath})`);
   }
@@ -53,7 +53,7 @@ export async function readWorkspaceText(relPath: string): Promise<string | null>
 /** Sync variant. Same ENOENT-only swallow contract. */
 export function readWorkspaceTextSync(relPath: string): string | null {
   try {
-    return fs.readFileSync(resolveWorkspacePath(relPath), "utf-8");
+    return readFileSync(resolveWorkspacePath(relPath), "utf-8");
   } catch (err) {
     return rethrowUnexpected(err, `readWorkspaceTextSync(${relPath})`);
   }
@@ -133,7 +133,7 @@ export function resolvePath(root: string, relPath: string): string {
  *  unexpected errors. */
 export async function readTextUnder(root: string, relPath: string): Promise<string | null> {
   try {
-    return await fs.promises.readFile(path.join(root, relPath), "utf-8");
+    return await promises.readFile(path.join(root, relPath), "utf-8");
   } catch (err) {
     return rethrowUnexpected(err, `readTextUnder(${relPath})`);
   }
@@ -147,7 +147,7 @@ export async function writeTextUnder(root: string, relPath: string, content: str
 /** Sync read text under a root. Null on ENOENT. */
 export function readTextUnderSync(root: string, relPath: string): string | null {
   try {
-    return fs.readFileSync(path.join(root, relPath), "utf-8");
+    return readFileSync(path.join(root, relPath), "utf-8");
   } catch (err) {
     return rethrowUnexpected(err, `readTextUnderSync(${relPath})`);
   }
@@ -156,7 +156,7 @@ export function readTextUnderSync(root: string, relPath: string): string | null
 /** Sync readdir under a root. Empty on ENOENT. */
 export function readdirUnderSync(root: string, relPath: string): string[] {
   try {
-    return fs.readdirSync(path.join(root, relPath));
+    return readdirSync(path.join(root, relPath));
   } catch (err) {
     if (isEnoent(err)) return [];
     log.error("workspace-io", `readdirUnderSync(${relPath})`, {
@@ -169,7 +169,7 @@ export function readdirUnderSync(root: string, relPath: string): string[] {
 /** Readdir under a root. Empty on ENOENT; rethrows unexpected. */
 export async function readdirUnder(root: string, relPath: string): Promise<string[]> {
   try {
-    return await fs.promises.readdir(path.join(root, relPath));
+    return await promises.readdir(path.join(root, relPath));
   } catch (err) {
     if (isEnoent(err)) return [];
     log.error("workspace-io", `readdirUnder(${relPath})`, {
@@ -180,9 +180,9 @@ export async function readdirUnder(root: string, relPath: string): Promise<strin
 }
 
 /** Stat under a root. Null on ENOENT; rethrows unexpected. */
-export async function statUnder(root: string, relPath: string): Promise<fs.Stats | null> {
+export async function statUnder(root: string, relPath: string): Promise<Stats | null> {
   try {
-    return await fs.promises.stat(path.join(root, relPath));
+    return await promises.stat(path.join(root, relPath));
   } catch (err) {
     return rethrowUnexpected(err, `statUnder(${relPath})`);
   }
@@ -190,7 +190,7 @@ export async function statUnder(root: string, relPath: string): Promise<fs.Stats
 
 /** Ensure a directory exists under a root. */
 export async function ensureDirUnder(root: string, relPath: string): Promise<void> {
-  await fs.promises.mkdir(path.join(root, relPath), { recursive: true });
+  await promises.mkdir(path.join(root, relPath), { recursive: true });
 }
 
 // ── Existence ───────────────────────────────────────────────────
@@ -201,7 +201,7 @@ export async function ensureDirUnder(root: string, relPath: string): Promise<voi
  */
 export function existsInWorkspace(relPath: string): boolean {
   try {
-    fs.statSync(resolveWorkspacePath(relPath));
+    statSync(resolveWorkspacePath(relPath));
     return true;
   } catch (err) {
     if (isEnoent(err)) return false;
@@ -217,5 +217,5 @@ export function existsInWorkspace(relPath: string): boolean {
  * (including parents) if missing. Idempotent.
  */
 export function ensureWorkspaceDir(relPath: string): void {
-  fs.mkdirSync(resolveWorkspacePath(relPath), { recursive: true });
+  mkdirSync(resolveWorkspacePath(relPath), { recursive: true });
 }

package/server/utils/gemini.ts

@@ -37,8 +37,8 @@ export async function generateGeminiImageContent(
   config?: GenerateContentParameters["config"],
   model: string = DEFAULT_IMAGE_MODEL,
 ): Promise<GeminiImageResult> {
-  const ai = getGeminiClient();
-  const response = await ai.models.generateContent({
+  const client = getGeminiClient();
+  const response = await client.models.generateContent({
     model,
     contents,
     ...(config && { config }),

package/server/utils/gitignore.ts

@@ -15,24 +15,24 @@
 // the workspace scale (~hundreds of dirs) this is negligible. If
 // profiling shows otherwise, cache the parsed ignore instances.
 
-import fs from "fs";
+import { readFileSync } from "fs";
 import path from "path";
 import ignore, { type Ignore } from "ignore";
 
 export class GitignoreFilter {
-  private ig: Ignore;
+  private rules: Ignore;
 
   constructor(rules?: string) {
-    this.ig = ignore();
+    this.rules = ignore();
     if (rules) {
-      this.ig.add(rules);
+      this.rules.add(rules);
     }
   }
 
   /** Test whether a workspace-relative path should be hidden. */
   ignores(relPath: string): boolean {
     if (!relPath) return false;
-    return this.ig.ignores(relPath);
+    return this.rules.ignores(relPath);
   }
 
   /** Create a child filter that inherits this filter's rules and
@@ -40,12 +40,12 @@ export class GitignoreFilter {
   childForDir(dirAbsPath: string): GitignoreFilter {
     const child = new GitignoreFilter();
     // Inherit parent rules
-    child.ig = ignore().add(this.ig);
+    child.rules = ignore().add(this.rules);
     // Add local .gitignore if present
     const gitignorePath = path.join(dirAbsPath, ".gitignore");
     try {
-      const content = fs.readFileSync(gitignorePath, "utf-8");
-      child.ig.add(content);
+      const content = readFileSync(gitignorePath, "utf-8");
+      child.rules.add(content);
     } catch {
       // No .gitignore in this directory — just inherit parent
     }
@@ -61,7 +61,7 @@ export class GitignoreFilter {
 export function createRootFilter(workspaceRoot: string): GitignoreFilter {
   const gitignorePath = path.join(workspaceRoot, ".gitignore");
   try {
-    const content = fs.readFileSync(gitignorePath, "utf-8");
+    const content = readFileSync(gitignorePath, "utf-8");
     return new GitignoreFilter(content);
   } catch {
     return new GitignoreFilter();

package/server/utils/json.ts

@@ -44,22 +44,22 @@ export function findBalancedBraceBlock(raw: string): string | null {
   let inString = false;
   let escape = false;
   for (let i = start; i < raw.length; i++) {
-    const ch = raw[i];
+    const char = raw[i];
     if (escape) {
       escape = false;
       continue;
     }
-    if (ch === "\\") {
+    if (char === "\\") {
       escape = true;
       continue;
     }
-    if (ch === '"') {
+    if (char === '"') {
       inString = !inString;
       continue;
     }
     if (inString) continue;
-    if (ch === "{") depth++;
-    if (ch === "}" && --depth === 0) return raw.slice(start, i + 1);
+    if (char === "{") depth++;
+    if (char === "}" && --depth === 0) return raw.slice(start, i + 1);
   }
   return null;
 }

package/server/utils/logBackgroundError.ts

@@ -1,4 +1,5 @@
 import { log } from "../system/logger/index.js";
+import { errorMessage } from "./errors.js";
 
 /**
  * Build a `.catch` handler for a fire-and-forget background job that
@@ -8,15 +9,23 @@ import { log } from "../system/logger/index.js";
  *
  * Usage:
  *
+ *   // Default message — good for generic background scans.
  *   maybeRunJournal({ ... }).catch(logBackgroundError("journal"));
  *
+ *   // Custom message — pass context when the failure mode is
+ *   // worth surfacing distinctly (e.g. "failed to register
+ *   // scheduled skills" vs other `skills` warnings).
+ *   registerScheduledSkills(...).catch(
+ *     logBackgroundError("skills", "failed to register scheduled skills"),
+ *   );
+ *
  * The handler never rethrows — the caller's promise chain is
  * terminated cleanly so nothing propagates into the request path.
  */
-export function logBackgroundError(prefix: string): (err: unknown) => void {
+export function logBackgroundError(prefix: string, message = "unexpected error in background"): (err: unknown) => void {
   return (err) => {
-    log.warn(prefix, "unexpected error in background", {
-      error: String(err),
+    log.warn(prefix, message, {
+      error: errorMessage(err),
     });
   };
 }

package/server/utils/markdown.ts

@@ -68,15 +68,15 @@ export function rewriteMarkdownLinks(input: string, rewrite: (href: string) => s
  * Split a trailing `#fragment` or `?query` off a path so the caller
  * can rewrite the path portion and concatenate the suffix back.
  */
-export function splitFragmentAndQuery(s: string): {
+export function splitFragmentAndQuery(href: string): {
   pathPart: string;
   suffix: string;
 } {
-  const hashIdx = s.indexOf("#");
-  const queryIdx = s.indexOf("?");
+  const hashIdx = href.indexOf("#");
+  const queryIdx = href.indexOf("?");
   let cut = -1;
   if (hashIdx !== -1) cut = hashIdx;
   if (queryIdx !== -1 && (cut === -1 || queryIdx < cut)) cut = queryIdx;
-  if (cut === -1) return { pathPart: s, suffix: "" };
-  return { pathPart: s.slice(0, cut), suffix: s.slice(cut) };
+  if (cut === -1) return { pathPart: href, suffix: "" };
+  return { pathPart: href.slice(0, cut), suffix: href.slice(cut) };
 }

package/server/utils/port.d.mts

@@ -0,0 +1,6 @@
+// Type declarations for port.mjs. See port.mjs for rationale on why
+// the shared helper lives in plain JS.
+
+export const MAX_PORT_PROBES: number;
+export function isPortFree(port: number): Promise<boolean>;
+export function findAvailablePort(start: number): Promise<number | null>;

package/server/utils/port.mjs

@@ -0,0 +1,48 @@
+// Shared port-resolution helpers for the dev server and the npm
+// launcher (`packages/mulmoclaude/bin/mulmoclaude.js`).
+//
+// Kept as plain `.mjs` (no TypeScript) because the launcher runs
+// directly under Node — it boots BEFORE tsx is wired up, so it can't
+// import from a `.ts` file. The server-side TypeScript imports this
+// through Node's ESM resolution; `moduleResolution: "bundler"` + the
+// sibling `port.d.mts` declarations give us the type coverage without
+// turning the whole `server/` tree into mixed JS/TS.
+
+import net from "node:net";
+
+// Scan cap: 20 slots is enough to step around the occasional stale
+// server on `localhost` without spinning forever on a pathologically
+// saturated machine.
+export const MAX_PORT_PROBES = 20;
+
+/**
+ * Returns true iff binding `127.0.0.1:port` would succeed right now.
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+export function isPortFree(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+    // Probe the same interface we'll actually bind to so a port
+    // held by a different process on a different interface doesn't
+    // give us a false "free" reading.
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+/**
+ * Walk forward from `start` until we find a free port. Returns `null`
+ * if every slot in `[start, start + MAX_PORT_PROBES)` is busy.
+ * @param {number} start
+ * @returns {Promise<number | null>}
+ */
+export async function findAvailablePort(start) {
+  for (let candidate = start; candidate < start + MAX_PORT_PROBES; candidate++) {
+    if (await isPortFree(candidate)) return candidate;
+  }
+  return null;
+}