mulmoclaude 0.3.0 → 0.4.0

package/server/api/routes/todosItemsHandlers.ts

@@ -281,10 +281,10 @@ function applyCompletedPatch(updated: TodoItem, items: TodoItem[], columns: Stat
   }
 }
 
-export function handlePatch(items: TodoItem[], columns: StatusColumn[], id: string, input: PatchInput): ItemsActionResult {
-  const target = items.find((i) => i.id === id);
+export function handlePatch(items: TodoItem[], columns: StatusColumn[], itemId: string, input: PatchInput): ItemsActionResult {
+  const target = items.find((item) => item.id === itemId);
   if (!target) {
-    return { kind: "error", status: 404, error: `item not found: ${id}` };
+    return { kind: "error", status: 404, error: `item not found: ${itemId}` };
   }
   const updated: TodoItem = { ...target };
 
@@ -305,7 +305,7 @@ export function handlePatch(items: TodoItem[], columns: StatusColumn[], id: stri
     if (err) return err;
   }
 
-  const next = items.map((item) => (item.id === id ? updated : item));
+  const next = items.map((item) => (item.id === itemId ? updated : item));
   return { kind: "success", items: next, item: updated };
 }
 
@@ -323,10 +323,10 @@ export interface MoveInput {
   position?: number;
 }
 
-export function handleMove(items: TodoItem[], columns: StatusColumn[], id: string, input: MoveInput): ItemsActionResult {
-  const target = items.find((i) => i.id === id);
+export function handleMove(items: TodoItem[], columns: StatusColumn[], itemId: string, input: MoveInput): ItemsActionResult {
+  const target = items.find((item) => item.id === itemId);
   if (!target) {
-    return { kind: "error", status: 404, error: `item not found: ${id}` };
+    return { kind: "error", status: 404, error: `item not found: ${itemId}` };
   }
   const validStatusIds = new Set(columns.map((column) => column.id));
   const newStatus = input.status ?? target.status ?? defaultStatusId(columns);
@@ -345,7 +345,7 @@ export function handleMove(items: TodoItem[], columns: StatusColumn[], id: strin
   };
   // Re-collect the items in the target column with the moving item
   // pulled out, then splice item back in at `position`.
-  const others = items.filter((item) => item.id !== id && item.status === newStatus).sort((left, right) => (left.order ?? 0) - (right.order ?? 0));
+  const others = items.filter((item) => item.id !== itemId && item.status === newStatus).sort((left, right) => (left.order ?? 0) - (right.order ?? 0));
   const insertAt = clampPosition(input.position, others.length);
   const reordered = [...others];
   reordered.splice(insertAt, 0, updatedSelf);
@@ -354,7 +354,7 @@ export function handleMove(items: TodoItem[], columns: StatusColumn[], id: strin
   reordered.forEach((item, i) => reorderedById.set(item.id, (i + 1) * ORDER_STEP));
   const nextItems = items.map((item): TodoItem => {
     const newOrder = reorderedById.get(item.id);
-    if (item.id === id) {
+    if (item.id === itemId) {
       const out: TodoItem = {
         ...updatedSelf,
         order: newOrder ?? updatedSelf.order ?? ORDER_STEP,
@@ -364,7 +364,7 @@ export function handleMove(items: TodoItem[], columns: StatusColumn[], id: strin
     if (newOrder !== undefined) return { ...item, order: newOrder };
     return item;
   });
-  const finalSelf = nextItems.find((item) => item.id === id)!;
+  const finalSelf = nextItems.find((item) => item.id === itemId)!;
   return { kind: "success", items: nextItems, item: finalSelf };
 }
 
@@ -377,10 +377,10 @@ function clampPosition(raw: number | undefined, max: number): number {
 
 // ── Delete ────────────────────────────────────────────────────────
 
-export function handleDeleteItem(items: TodoItem[], id: string): ItemsActionResult {
-  const target = items.find((i) => i.id === id);
+export function handleDeleteItem(items: TodoItem[], itemId: string): ItemsActionResult {
+  const target = items.find((item) => item.id === itemId);
   if (!target) {
-    return { kind: "error", status: 404, error: `item not found: ${id}` };
+    return { kind: "error", status: 404, error: `item not found: ${itemId}` };
   }
-  return { kind: "success", items: items.filter((item) => item.id !== id) };
+  return { kind: "success", items: items.filter((item) => item.id !== itemId) };
 }

package/server/api/routes/wiki.ts

@@ -4,6 +4,7 @@ import { WORKSPACE_PATHS } from "../../workspace/paths.js";
 import { readTextSafeSync, readTextSafe } from "../../utils/files/safe.js";
 import { getPageIndex } from "./wiki/pageIndex.js";
 import { badRequest } from "../../utils/httpError.js";
+import { getOptionalStringQuery } from "../../utils/request.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
 
 const router = Router();
@@ -132,21 +133,34 @@ async function resolvePagePath(pageName: string): Promise<string | null> {
 
   const slug = wikiSlugify(pageName);
 
-  const exact = slugs.get(slug);
-  if (exact) return path.join(dir, exact);
+  if (slug.length > 0) {
+    const exact = slugs.get(slug);
+    if (exact) return path.join(dir, exact);
 
-  // Fuzzy: same `includes` semantics as the old sync path — iterate
-  // the index's keys, no filesystem access.
-  for (const [key, file] of slugs) {
-    if (slug.includes(key) || key.includes(slug)) {
-      return path.join(dir, file);
+    // Fuzzy: same `includes` semantics as the old sync path — iterate
+    // the index's keys, no filesystem access.
+    for (const [key, file] of slugs) {
+      if (slug.includes(key) || key.includes(slug)) {
+        return path.join(dir, file);
+      }
     }
   }
+
+  // Non-ASCII page names (e.g. Japanese [[wiki links]]) produce empty
+  // slugs after slugification. Fall back to matching by title in the
+  // wiki index so the link resolves to its page file.
+  const indexContent = readFileOrEmpty(indexFile());
+  const entries = parseIndexEntries(indexContent);
+  const titleMatch = entries.find((entry) => entry.title === pageName);
+  if (titleMatch && slugs.has(titleMatch.slug)) {
+    return path.join(dir, slugs.get(titleMatch.slug)!);
+  }
+
   return null;
 }
 
 router.get(API_ROUTES.wiki.base, async (req: Request, res: Response<WikiResponse | ErrorResponse>) => {
-  const slug = typeof req.query.slug === "string" ? req.query.slug : undefined;
+  const slug = getOptionalStringQuery(req, "slug");
   if (slug) {
     const filePath = await resolvePagePath(slug);
     const content = filePath ? readFileOrEmpty(filePath) : "";

package/server/api/sandboxStatus.ts

@@ -59,6 +59,6 @@ export function buildSandboxStatus(params: BuildSandboxStatusParams): SandboxSta
 
   return {
     sshAgent,
-    mounts: parsed.resolved.map((m) => m.name),
+    mounts: parsed.resolved.map((mount) => mount.name),
   };
 }

package/server/events/notifications.ts

@@ -32,8 +32,8 @@ export interface NotificationDeps {
 
 let deps: NotificationDeps | null = null;
 
-export function initNotifications(d: NotificationDeps): void {
-  deps = d;
+export function initNotifications(injected: NotificationDeps): void {
+  deps = injected;
 }
 
 // ── In-memory store ─────────────────────────────────────────────
@@ -97,10 +97,10 @@ export function publishNotification(opts: PublishNotificationOpts): void {
   }
 }
 
-function formatBridgeMessage(p: NotificationPayload): string {
-  const icon = p.kind === NOTIFICATION_KINDS.agent ? "\u2705" : "\u{1F514}";
-  const parts = [icon, p.title];
-  if (p.body) parts.push(p.body);
+function formatBridgeMessage(payload: NotificationPayload): string {
+  const icon = payload.kind === NOTIFICATION_KINDS.agent ? "\u2705" : "\u{1F514}";
+  const parts = [icon, payload.title];
+  if (payload.body) parts.push(payload.body);
   return parts.join(" ");
 }
 

package/server/events/pub-sub/index.ts

@@ -13,7 +13,7 @@ export interface IPubSub {
 // itself, which is why we switched off raw ws.
 
 export function createPubSub(server: http.Server): IPubSub {
-  const io = new IOServer(server, {
+  const ioServer = new IOServer(server, {
     path: "/ws/pubsub",
     // Server binds to 127.0.0.1 only, so CORS is moot — but
     // socket.io defaults to rejecting cross-origin upgrade
@@ -28,7 +28,7 @@ export function createPubSub(server: http.Server): IPubSub {
     transports: ["websocket"],
   });
 
-  io.on("connection", (socket) => {
+  ioServer.on("connection", (socket) => {
     socket.on("subscribe", (channel: unknown) => {
       if (typeof channel === "string") socket.join(channel);
     });
@@ -39,7 +39,7 @@ export function createPubSub(server: http.Server): IPubSub {
 
   return {
     publish(channel: string, data: unknown): void {
-      io.to(channel).emit("data", { channel, data });
+      ioServer.to(channel).emit("data", { channel, data });
     },
   };
 }

package/server/events/relay-client.ts

@@ -6,12 +6,13 @@
 //
 // NOTE: packages/relay/src/client.ts is a parallel implementation
 // for browser/edge environments using the global WebSocket API.
-// This module uses the `ws` npm package for Node.js. If you change
+// This module uses the `socket` npm package for Node.js. If you change
 // reconnection logic or URL handling here, check the other file too.
 
 import WebSocket from "ws";
 import type { ChatService } from "@mulmobridge/chat-service";
 import { ONE_SECOND_MS } from "../utils/time.js";
+import { errorMessage } from "../utils/errors.js";
 
 type RelayFn = ChatService["relay"];
 
@@ -87,7 +88,7 @@ function isRelayMessage(value: unknown): value is RelayMessage {
 export function connectRelay(deps: RelayClientDeps): RelayClientHandle {
   const { relayUrl, relayToken, relay, logger } = deps;
 
-  let ws: WebSocket | null = null;
+  let socket: WebSocket | null = null;
   let reconnectMs = MIN_RECONNECT_MS;
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   let stopped = false;
@@ -103,27 +104,27 @@ export function connectRelay(deps: RelayClientDeps): RelayClientHandle {
     if (stopped) return;
 
     try {
-      ws = new WebSocket(buildUrl());
+      socket = new WebSocket(buildUrl());
     } catch (err) {
       logger.error(LOG_PREFIX, "failed to create WebSocket", {
-        error: err instanceof Error ? err.message : String(err),
+        error: errorMessage(err),
       });
       scheduleReconnect();
       return;
     }
 
-    ws.on("open", () => {
+    socket.on("open", () => {
       logger.info(LOG_PREFIX, "connected", { url: relayUrl });
       reconnectMs = MIN_RECONNECT_MS;
       flushResponseQueue();
     });
 
-    ws.on("message", (data) => {
+    socket.on("message", (data) => {
       handleMessage(String(data));
     });
 
-    ws.on("close", (code, reason) => {
-      ws = null;
+    socket.on("close", (code, reason) => {
+      socket = null;
       if (TERMINAL_CLOSE_CODES.has(code)) {
         logger.error(LOG_PREFIX, "terminal close, not reconnecting", {
           code,
@@ -138,7 +139,7 @@ export function connectRelay(deps: RelayClientDeps): RelayClientHandle {
       scheduleReconnect();
     });
 
-    ws.on("error", (err) => {
+    socket.on("error", (err) => {
       logger.warn(LOG_PREFIX, "connection error", {
         error: err.message,
       });
@@ -204,7 +205,7 @@ export function connectRelay(deps: RelayClientDeps): RelayClientHandle {
     } catch (err) {
       logger.error(LOG_PREFIX, "relay processing failed", {
         id: msg.id,
-        error: err instanceof Error ? err.message : String(err),
+        error: errorMessage(err),
       });
       sendResponse({
         platform: msg.platform,
@@ -227,9 +228,9 @@ export function connectRelay(deps: RelayClientDeps): RelayClientHandle {
   }
 
   function trySend(response: RelayResponse): boolean {
-    if (!ws || ws.readyState !== WebSocket.OPEN) return false;
+    if (!socket || socket.readyState !== WebSocket.OPEN) return false;
     try {
-      ws.send(JSON.stringify(response), (err) => {
+      socket.send(JSON.stringify(response), (err) => {
         if (err && !stopped) {
           logger.warn(LOG_PREFIX, "send failed, requeueing", {
             platform: response.platform,
@@ -261,7 +262,7 @@ export function connectRelay(deps: RelayClientDeps): RelayClientHandle {
       count: responseQueue.length,
     });
     while (responseQueue.length > 0) {
-      if (!ws || ws.readyState !== WebSocket.OPEN) break;
+      if (!socket || socket.readyState !== WebSocket.OPEN) break;
       const response = responseQueue[0]!;
       if (!trySend(response)) break;
       responseQueue.shift();
@@ -274,9 +275,9 @@ export function connectRelay(deps: RelayClientDeps): RelayClientHandle {
       clearTimeout(reconnectTimer);
       reconnectTimer = null;
     }
-    if (ws) {
-      ws.close(1000, "shutdown");
-      ws = null;
+    if (socket) {
+      socket.close(1000, "shutdown");
+      socket = null;
     }
     logger.info(LOG_PREFIX, "stopped");
   }

package/server/index.ts

@@ -1,6 +1,5 @@
 import "dotenv/config";
 import express, { Request, Response, NextFunction } from "express";
-import net from "net";
 import path from "path";
 import { fileURLToPath } from "url";
 import agentRoutes from "./api/routes/agent.js";
@@ -34,8 +33,8 @@ import { mcpToolsRouter, mcpTools, isMcpToolEnabled } from "./agent/mcp-tools/in
 import { initWorkspace, workspacePath } from "./workspace/workspace.js";
 import { env, isGeminiAvailable } from "./system/env.js";
 import { buildSandboxStatus } from "./api/sandboxStatus.js";
-import fs from "fs";
-import os from "os";
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
 import { isDockerAvailable, ensureSandboxImage } from "./system/docker.js";
 import { maybeRunJournal } from "./workspace/journal/index.js";
 import { backfillAllSessions } from "./workspace/chat-index/index.js";
@@ -53,6 +52,7 @@ import { requireSameOrigin } from "./api/csrfGuard.js";
 import { bearerAuth } from "./api/auth/bearerAuth.js";
 import { deleteTokenFile, generateAndWriteToken, getCurrentToken } from "./api/auth/token.js";
 import { log } from "./system/logger/index.js";
+import { logBackgroundError } from "./utils/logBackgroundError.js";
 import { startChat } from "./api/routes/agent.js";
 import { registerScheduledSkills } from "./workspace/skills/scheduler.js";
 import { registerUserTasks } from "./workspace/skills/user-tasks.js";
@@ -60,6 +60,7 @@ import { API_ROUTES } from "../src/config/apiRoutes.js";
 import { EVENT_TYPES } from "../src/types/events.js";
 import { SESSION_ORIGINS } from "../src/types/session.js";
 import { ONE_SECOND_MS, ONE_MINUTE_MS, ONE_HOUR_MS } from "./utils/time.js";
+import { isPortFree, findAvailablePort, MAX_PORT_PROBES } from "./utils/port.mjs";
 import { SCHEDULE_TYPES, MISSED_RUN_POLICIES } from "@receptron/task-scheduler";
 
 const HTML_TOKEN_PLACEHOLDER = "__MULMOCLAUDE_AUTH_TOKEN__";
@@ -74,7 +75,6 @@ initWorkspace();
 let sandboxEnabled = false;
 
 const app = express();
-const PORT = env.port;
 
 app.disable("x-powered-by");
 // No `cors()` middleware. The Vite dev proxy forwards `/api/*`
@@ -234,7 +234,7 @@ if (env.isProduction) {
   app.get("/{*splat}", (_req: Request, res: Response) => {
     let html: string;
     try {
-      html = fs.readFileSync(indexHtmlPath, "utf-8");
+      html = readFileSync(indexHtmlPath, "utf-8");
     } catch (err) {
       log.error("server", "failed to read index.html", { error: String(err) });
       serverError(res, "Internal Server Error");
@@ -255,23 +255,35 @@ app.use((err: Error, _req: Request, res: Response, __next: NextFunction) => {
   serverError(res, "Internal Server Error");
 });
 
-function isPortFree(port: number): Promise<boolean> {
-  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");
-  });
+// True iff the user set `PORT` explicitly; empty string counts as "not
+// set". We use this to decide between "walk forward when busy" (friendly
+// dev behaviour) and "fail loudly" (respect the user's choice).
+const portExplicit = typeof process.env.PORT === "string" && process.env.PORT.trim() !== "";
+
+// Resolve the port we'll actually bind to. Default PORT (3001) + busy
+// walks forward so a stale `yarn dev` or a parallel test run doesn't
+// crash the launch. Explicit PORT + busy exits — matches the launcher's
+// `--port` semantics so `PORT=3099 yarn dev` behaves the same as
+// `npx mulmoclaude --port 3099`.
+async function resolvePort(): Promise<number> {
+  const requested = env.port;
+  if (await isPortFree(requested)) return requested;
+  if (portExplicit) {
+    log.error("server", `Port ${requested} is already in use. Stop the other process or pick a different PORT.`);
+    process.exit(1);
+  }
+  const fallback = await findAvailablePort(requested + 1);
+  if (fallback === null) {
+    log.error("server", `Port ${requested} is in use and no free port found in ${requested}..${requested + MAX_PORT_PROBES - 1}.`);
+    process.exit(1);
+  }
+  log.info("server", `Port ${requested} busy → using ${fallback} instead`);
+  return fallback;
 }
 
 async function ensureCredentialsAvailable(): Promise<void> {
-  const credentialsPath = path.join(os.homedir(), ".claude", ".credentials.json");
-  if (fs.existsSync(credentialsPath)) return;
+  const credentialsPath = path.join(homedir(), ".claude", ".credentials.json");
+  if (existsSync(credentialsPath)) return;
 
   if (process.platform === "darwin") {
     const { refreshCredentials } = await import("./system/credentials.js");
@@ -329,9 +341,7 @@ function maybeForceJournalRun(): void {
   // propagate out of maybeRunJournal.
   if (!env.journalForceRunOnStartup) return;
   log.info("journal", "JOURNAL_FORCE_RUN_ON_STARTUP=1 — running now");
-  maybeRunJournal({ force: true }).catch((err) => {
-    log.warn("journal", "forced startup run failed", { error: String(err) });
-  });
+  maybeRunJournal({ force: true }).catch(logBackgroundError("journal", "forced startup run failed"));
 }
 
 function maybeForceChatIndexBackfill(): void {
@@ -349,15 +359,11 @@ function maybeForceChatIndexBackfill(): void {
         skipped: result.skipped,
       });
     })
-    .catch((err) => {
-      log.warn("chat-index", "forced startup backfill failed", {
-        error: String(err),
-      });
-    });
+    .catch(logBackgroundError("chat-index", "forced startup backfill failed"));
 }
 
-function startRuntimeServices(httpServer: ReturnType<typeof app.listen>): void {
-  log.info("server", "listening", { port: PORT });
+function startRuntimeServices(httpServer: ReturnType<typeof app.listen>, port: number): void {
+  log.info("server", "listening", { port });
 
   // --- Pub/Sub ---
   const pubsub = createPubSub(httpServer);
@@ -464,11 +470,7 @@ function startRuntimeServices(httpServer: ReturnType<typeof app.listen>): void {
         log.info("skills", "scheduled skills registered", { count });
       }
     })
-    .catch((err) => {
-      log.warn("skills", "failed to register scheduled skills", {
-        error: String(err),
-      });
-    });
+    .catch(logBackgroundError("skills", "failed to register scheduled skills"));
 
   // Register user-created scheduled tasks from tasks.json.
   registerUserTasks({ taskManager, startChat })
@@ -477,11 +479,7 @@ function startRuntimeServices(httpServer: ReturnType<typeof app.listen>): void {
         log.info("user-tasks", "user tasks registered", { count });
       }
     })
-    .catch((err) => {
-      log.warn("user-tasks", "failed to register user tasks", {
-        error: String(err),
-      });
-    });
+    .catch(logBackgroundError("user-tasks", "failed to register user tasks"));
 
   taskManager.start();
 
@@ -510,11 +508,7 @@ process.on("SIGTERM", () => {
 });
 
 (async () => {
-  const portFree = await isPortFree(PORT);
-  if (!portFree) {
-    log.error("server", `Port ${PORT} is already in use. Stop the other process and try again.`);
-    process.exit(1);
-  }
+  const port = await resolvePort();
 
   // Generate the bearer token before `app.listen` so the first
   // request cannot race an uninitialised `getCurrentToken()`. The
@@ -535,8 +529,8 @@ process.on("SIGTERM", () => {
   // `http://<laptop-ip>:3001/api/*`), which combined with the
   // workspace file API is a credential-theft risk. Personal dev
   // tool — localhost is the right default.
-  const httpServer = app.listen(PORT, "127.0.0.1", () => {
-    startRuntimeServices(httpServer);
+  const httpServer = app.listen(port, "127.0.0.1", () => {
+    startRuntimeServices(httpServer, port);
   });
 })();
 

package/server/system/config.ts

@@ -9,7 +9,7 @@
 // defaults. Writers perform an atomic replace (tmp + rename) so a
 // reader never observes a half-written file.
 
-import fs from "fs";
+import { mkdirSync } from "fs";
 import path from "path";
 import { log } from "./logger/index.js";
 import { WORKSPACE_PATHS } from "../workspace/paths.js";
@@ -44,7 +44,7 @@ export function mcpConfigPath(): string {
 }
 
 export function ensureConfigsDir(): void {
-  fs.mkdirSync(configsDir(), { recursive: true });
+  mkdirSync(configsDir(), { recursive: true });
 }
 
 export function isAppSettings(value: unknown): value is AppSettings {
@@ -181,8 +181,8 @@ export function isMcpConfigFile(value: unknown): value is McpConfigFile {
 
   const servers = value.mcpServers;
   if (!isRecord(servers)) return false;
-  for (const [id, spec] of Object.entries(servers)) {
-    if (!isMcpServerId(id)) return false;
+  for (const [serverId, spec] of Object.entries(servers)) {
+    if (!isMcpServerId(serverId)) return false;
     if (!isMcpServerSpec(spec)) return false;
   }
   return true;
@@ -220,7 +220,7 @@ export function saveMcpConfig(cfg: McpConfigFile): void {
 
 // Flatten storage form to UI-friendly array.
 export function toMcpEntries(cfg: McpConfigFile): McpServerEntry[] {
-  return Object.entries(cfg.mcpServers).map(([id, spec]) => ({ id, spec }));
+  return Object.entries(cfg.mcpServers).map(([serverId, spec]) => ({ id: serverId, spec }));
 }
 
 // Re-inflate UI-friendly array to storage form. Duplicate ids are

package/server/system/credentials.ts

@@ -1,10 +1,10 @@
 import { execFile } from "child_process";
-import { writeFile } from "fs/promises";
 import { homedir } from "os";
 import { join } from "path";
 import { promisify } from "util";
 import { log } from "./logger/index.js";
 import { ONE_SECOND_MS, ONE_MINUTE_MS } from "../utils/time.js";
+import { writeFileAtomic } from "../utils/files/atomic.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -121,13 +121,13 @@ async function renewTokenViaPty(): Promise<boolean> {
       buffer += data;
 
       if (!responded) {
-        const m = ECHO_RE.exec(buffer);
-        if (m) {
+        const match = ECHO_RE.exec(buffer);
+        if (match) {
           // Claude echoed our "hi" — remember where the response
           // window starts so the success check looks only at bytes
           // that arrived AFTER the echo.
           responded = true;
-          echoEndIdx = m.index + m[0].length;
+          echoEndIdx = match.index + match[0].length;
         }
         return;
       }
@@ -208,7 +208,9 @@ export async function refreshCredentials(): Promise<boolean> {
       }
     }
 
-    await writeFile(CREDENTIALS_PATH, credentials + "\n", { mode: 0o600 });
+    // Atomic so a readers mid-refresh can't see a truncated creds
+    // file; mode preserves the 0o600 we always set on this file.
+    await writeFileAtomic(CREDENTIALS_PATH, credentials + "\n", { mode: 0o600 });
     log.info("credentials", "Fresh credentials written to ~/.claude/.credentials.json");
     return true;
   } catch (err) {

package/server/system/env.ts

@@ -19,11 +19,11 @@
 
 function asInt(value: string | undefined, fallback: number, opts: { min?: number; max?: number } = {}): number {
   if (value === undefined || value === "") return fallback;
-  const n = Number(value);
-  if (!Number.isInteger(n)) return fallback;
-  if (opts.min !== undefined && n < opts.min) return fallback;
-  if (opts.max !== undefined && n > opts.max) return fallback;
-  return n;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) return fallback;
+  if (opts.min !== undefined && parsed < opts.min) return fallback;
+  if (opts.max !== undefined && parsed > opts.max) return fallback;
+  return parsed;
 }
 
 function asFlag(value: string | undefined): boolean {

package/server/utils/files/atomic.ts

@@ -6,7 +6,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, renameSync, unlinkSync, writeFileSync } from "fs";
 import path from "path";
 import { randomUUID } from "crypto";
 
@@ -50,7 +50,7 @@ function isTransientRenameError(err: unknown): boolean {
 async function renameWithWindowsRetry(fromPath: string, toPath: string): Promise<void> {
   for (const delayMs of RENAME_RETRY_DELAYS_MS) {
     try {
-      await fs.promises.rename(fromPath, toPath);
+      await promises.rename(fromPath, toPath);
       return;
     } catch (err) {
       if (!isTransientRenameError(err)) throw err;
@@ -58,7 +58,7 @@ async function renameWithWindowsRetry(fromPath: string, toPath: string): Promise
     }
   }
   // Final attempt — let any error propagate.
-  await fs.promises.rename(fromPath, toPath);
+  await promises.rename(fromPath, toPath);
 }
 
 // Sync sleep that parks the thread instead of burning CPU. Only
@@ -73,14 +73,14 @@ function sleepSync(millis: number): void {
 function renameSyncWithWindowsRetry(fromPath: string, toPath: string): void {
   for (const delayMs of RENAME_RETRY_DELAYS_MS) {
     try {
-      fs.renameSync(fromPath, toPath);
+      renameSync(fromPath, toPath);
       return;
     } catch (err) {
       if (!isTransientRenameError(err)) throw err;
       sleepSync(delayMs);
     }
   }
-  fs.renameSync(fromPath, toPath);
+  renameSync(fromPath, toPath);
 }
 
 /**
@@ -90,15 +90,15 @@ function renameSyncWithWindowsRetry(fromPath: string, toPath: string): void {
  */
 export async function writeFileAtomic(filePath: string, content: string, opts: WriteAtomicOptions = {}): Promise<void> {
   const tmp = opts.uniqueTmp ? `${filePath}.${randomUUID()}.tmp` : `${filePath}.tmp`;
-  await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+  await promises.mkdir(path.dirname(filePath), { recursive: true });
   try {
-    await fs.promises.writeFile(tmp, content, {
+    await promises.writeFile(tmp, content, {
       encoding: "utf-8",
       mode: opts.mode,
     });
     await renameWithWindowsRetry(tmp, filePath);
   } catch (err) {
-    await fs.promises.unlink(tmp).catch(() => {});
+    await promises.unlink(tmp).catch(() => {});
     throw err;
   }
 }
@@ -110,13 +110,13 @@ export async function writeFileAtomic(filePath: string, content: string, opts: W
  */
 export function writeFileAtomicSync(filePath: string, content: string, opts: WriteAtomicOptions = {}): void {
   const tmp = opts.uniqueTmp ? `${filePath}.${randomUUID()}.tmp` : `${filePath}.tmp`;
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  mkdirSync(path.dirname(filePath), { recursive: true });
   try {
-    fs.writeFileSync(tmp, content, { encoding: "utf-8", mode: opts.mode });
+    writeFileSync(tmp, content, { encoding: "utf-8", mode: opts.mode });
     renameSyncWithWindowsRetry(tmp, filePath);
   } catch (err) {
     try {
-      fs.unlinkSync(tmp);
+      unlinkSync(tmp);
     } catch {
       // best-effort cleanup
     }