mulmoclaude 0.1.2 → 0.4.0

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/events/scheduler-adapter.ts

@@ -52,16 +52,16 @@ function logsDir(root = workspacePath): string {
 // ── I/O deps (real filesystem) ───────────────────────────────────
 
 const stateDeps: StateDeps = {
-  readFile: (p: string) => readFile(p, "utf-8"),
-  writeFileAtomic: (p: string, content: string) => writeFileAtomic(p, content),
+  readFile: (filePath: string) => readFile(filePath, "utf-8"),
+  writeFileAtomic: (filePath: string, content: string) => writeFileAtomic(filePath, content),
   exists: existsSync,
 };
 
 const logDeps: LogDeps = {
-  appendFile: (p: string, content: string) => appendFile(p, content),
-  readFile: (p: string) => readFile(p, "utf-8"),
+  appendFile: (filePath: string, content: string) => appendFile(filePath, content),
+  readFile: (filePath: string) => readFile(filePath, "utf-8"),
   exists: existsSync,
-  ensureDir: (p: string) => mkdir(p, { recursive: true }).then(() => {}),
+  ensureDir: (directoryPath: string) => mkdir(directoryPath, { recursive: true }).then(() => {}),
 };
 
 // ── System task registry ─────────────────────────────────────────
@@ -95,11 +95,11 @@ export async function initScheduler(taskManager: ITaskManager, tasks: SystemTask
   taskManagerRef = taskManager;
 
   // Run catch-up
-  const catchUpTasks: CatchUpTask[] = tasks.map((t) => ({
-    id: t.id,
-    name: t.name,
-    schedule: toCoreSchedule(t.schedule),
-    missedRunPolicy: t.missedRunPolicy,
+  const catchUpTasks: CatchUpTask[] = tasks.map((taskDef) => ({
+    id: taskDef.id,
+    name: taskDef.name,
+    schedule: toCoreSchedule(taskDef.schedule),
+    missedRunPolicy: taskDef.missedRunPolicy,
     enabled: true,
   }));
   const plan = computeCatchUpPlan(catchUpTasks, stateMap, Date.now());
@@ -117,7 +117,7 @@ export async function initScheduler(taskManager: ITaskManager, tasks: SystemTask
       runs: plan.runs.length,
     });
     for (const run of plan.runs) {
-      const task = tasks.find((t) => t.id === run.taskId);
+      const task = tasks.find((taskDef) => taskDef.id === run.taskId);
       if (!task) continue;
       await executeAndLog(task, run.context.scheduledFor, TASK_TRIGGERS.catchUp);
     }
@@ -137,7 +137,7 @@ export async function initScheduler(taskManager: ITaskManager, tasks: SystemTask
   }
 
   log.info("scheduler", "initialized", {
-    tasks: tasks.map((t) => t.id),
+    tasks: tasks.map((taskDef) => taskDef.id),
     stateEntries: stateMap.size,
   });
 }
@@ -146,7 +146,7 @@ export async function initScheduler(taskManager: ITaskManager, tasks: SystemTask
  *  Updates the in-memory task definition, the task-manager, and
  *  recalculates nextScheduledAt in persisted state. */
 export async function applyScheduleOverride(taskId: string, schedule: SystemTaskDef["schedule"]): Promise<boolean> {
-  const task = systemTasks.find((t) => t.id === taskId);
+  const task = systemTasks.find((taskDef) => taskDef.id === taskId);
   if (!task || !taskManagerRef) return false;
   if (!taskManagerRef.updateSchedule(taskId, schedule)) return false;
   task.schedule = schedule;
@@ -172,13 +172,13 @@ export function getSchedulerTasks(): Array<{
   missedRunPolicy: string;
   state: TaskExecutionState;
 }> {
-  return systemTasks.map((t) => ({
-    id: t.id,
-    name: t.name,
-    description: t.description,
-    schedule: t.schedule,
-    missedRunPolicy: t.missedRunPolicy,
-    state: stateMap.get(t.id) ?? emptyState(t.id),
+  return systemTasks.map((taskDef) => ({
+    id: taskDef.id,
+    name: taskDef.name,
+    description: taskDef.description,
+    schedule: taskDef.schedule,
+    missedRunPolicy: taskDef.missedRunPolicy,
+    state: stateMap.get(taskDef.id) ?? emptyState(taskDef.id),
   }));
 }
 

package/server/events/session-store/index.ts

@@ -65,8 +65,8 @@ const storelessPending = new Map<string, Set<string>>();
 let pubsub: IPubSub | null = null;
 let evictionTimer: ReturnType<typeof setInterval> | null = null;
 
-export function initSessionStore(ps: IPubSub): void {
-  pubsub = ps;
+export function initSessionStore(pubSubInstance: IPubSub): void {
+  pubsub = pubSubInstance;
   if (evictionTimer) clearInterval(evictionTimer);
   evictionTimer = setInterval(evictIdleSessions, EVICTION_CHECK_INTERVAL_MS);
 }
@@ -288,8 +288,8 @@ interface GenerationPayload {
 
 const GENERATION_KIND_VALUES: ReadonlySet<string> = new Set(Object.values(GENERATION_KINDS));
 
-function isGenerationKind(v: unknown): v is GenerationKind {
-  return typeof v === "string" && GENERATION_KIND_VALUES.has(v);
+function isGenerationKind(value: unknown): value is GenerationKind {
+  return typeof value === "string" && GENERATION_KIND_VALUES.has(value);
 }
 
 /**
@@ -314,7 +314,7 @@ function applyEventToSession(session: ServerSession, type: string, event: Record
       timestamp: Date.now(),
     });
   } else if (type === EVENT_TYPES.toolCallResult) {
-    const entry = session.toolCallHistory.find((e) => e.toolUseId === event.toolUseId);
+    const entry = session.toolCallHistory.find((historyEntry) => historyEntry.toolUseId === event.toolUseId);
     if (entry) entry.result = event.content as string;
   } else if (type === EVENT_TYPES.status) {
     session.statusMessage = event.message as string;
@@ -404,8 +404,8 @@ export function getSessionImageData(chatSessionId: string): string | undefined {
 
 export function getActiveSessionIds(): Set<string> {
   const ids = new Set<string>();
-  for (const [id, session] of store) {
-    if (session.isRunning) ids.add(id);
+  for (const [chatSessionId, session] of store) {
+    if (session.isRunning) ids.add(chatSessionId);
   }
   return ids;
 }
@@ -465,14 +465,14 @@ function notifySessionsChanged(): void {
 
 function evictIdleSessions(): void {
   const now = Date.now();
-  for (const [id, session] of store) {
+  for (const [chatSessionId, session] of store) {
     if (session.isRunning) continue;
     const age = now - new Date(session.updatedAt).getTime();
     if (age > IDLE_EVICTION_MS) {
       log.info("session-store", "evicting idle session", {
-        chatSessionId: id,
+        chatSessionId,
       });
-      removeSession(id);
+      removeSession(chatSessionId);
     }
   }
 }

package/server/events/task-manager/index.ts

@@ -52,8 +52,8 @@ function isDue(now: Date, schedule: TaskSchedule, tickMs: number): boolean {
   }
 
   if (schedule.type === SCHEDULE_TYPES.daily) {
-    const [hh, mm] = schedule.time.split(":").map(Number);
-    const targetMs = hh * ONE_HOUR_MS + mm * ONE_MINUTE_MS;
+    const [hours, minutes] = schedule.time.split(":").map(Number);
+    const targetMs = hours * ONE_HOUR_MS + minutes * ONE_MINUTE_MS;
     const msSinceMidnight = now.getUTCHours() * ONE_HOUR_MS + now.getUTCMinutes() * ONE_MINUTE_MS + now.getUTCSeconds() * ONE_SECOND_MS;
     const rounded = Math.floor(msSinceMidnight / tickMs) * tickMs;
     return rounded === targetMs;
@@ -170,11 +170,11 @@ export function createTaskManager(options?: TaskManagerOptions): ITaskManager {
     },
 
     listTasks() {
-      return [...registry.values()].map((d) => ({
-        id: d.id,
-        description: d.description,
-        schedule: d.schedule,
-        dependsOn: d.dependsOn,
+      return [...registry.values()].map((taskDef) => ({
+        id: taskDef.id,
+        description: taskDef.description,
+        schedule: taskDef.schedule,
+        dependsOn: taskDef.dependsOn,
       }));
     },
   };

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/*`
@@ -157,13 +157,13 @@ app.use(configRoutes);
 app.use(skillsRoutes);
 async function listSessionsForBridge(opts: { limit: number; offset: number }) {
   const rows = await loadAllSessions();
-  const sorted = rows.sort((a, b) => b.changeMs - a.changeMs);
+  const sorted = rows.sort((leftSession, rightSession) => rightSession.changeMs - leftSession.changeMs);
   const total = sorted.length;
-  const sessions = sorted.slice(opts.offset, opts.offset + opts.limit).map((r) => ({
-    id: r.summary.id,
-    roleId: r.summary.roleId,
-    preview: r.summary.preview,
-    updatedAt: r.summary.updatedAt,
+  const sessions = sorted.slice(opts.offset, opts.offset + opts.limit).map((row) => ({
+    id: row.summary.id,
+    roleId: row.summary.roleId,
+    preview: row.summary.preview,
+    updatedAt: row.summary.updatedAt,
   }));
   return { sessions, total };
 }
@@ -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,28 +255,40 @@ 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");
-    const ok = await refreshCredentials();
-    if (ok) return;
+    const refreshSucceeded = await refreshCredentials();
+    if (refreshSucceeded) return;
     log.error("sandbox", "Failed to export credentials from macOS Keychain. Run `npm run sandbox:login` manually.");
     process.exit(1);
   }
@@ -310,14 +322,14 @@ async function setupSandbox(): Promise<boolean> {
 
 function logMcpStatus(): void {
   const enabledMcpTools = mcpTools.filter(isMcpToolEnabled);
-  const disabledMcpTools = mcpTools.filter((t) => !isMcpToolEnabled(t));
+  const disabledMcpTools = mcpTools.filter((toolDef) => !isMcpToolEnabled(toolDef));
   if (enabledMcpTools.length > 0) {
     log.info("mcp", "Available", {
-      tools: enabledMcpTools.map((t) => t.definition.name).join(", "),
+      tools: enabledMcpTools.map((toolDef) => toolDef.definition.name).join(", "),
     });
   }
   if (disabledMcpTools.length > 0) {
-    const names = disabledMcpTools.map((t) => t.definition.name + " (" + (t.requiredEnv ?? []).join(", ") + ")").join(", ");
+    const names = disabledMcpTools.map((toolDef) => toolDef.definition.name + " (" + (toolDef.requiredEnv ?? []).join(", ") + ")").join(", ");
     log.info("mcp", "Unavailable (missing env)", { tools: names });
   }
 }
@@ -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);
@@ -424,24 +430,24 @@ function startRuntimeServices(httpServer: ReturnType<typeof app.listen>): void {
   // are silently ignored — the hardcoded defaults above remain.
   const overrides = loadSchedulerOverrides();
   for (const task of systemTasks) {
-    const ovr = overrides[task.id];
-    if (!ovr) continue;
-    if (task.schedule.type === SCHEDULE_TYPES.interval && typeof ovr.intervalMs === "number" && ovr.intervalMs > 0) {
+    const override = overrides[task.id];
+    if (!override) continue;
+    if (task.schedule.type === SCHEDULE_TYPES.interval && typeof override.intervalMs === "number" && override.intervalMs > 0) {
       log.info("scheduler", "applying override", {
         id: task.id,
-        intervalMs: ovr.intervalMs,
+        intervalMs: override.intervalMs,
       });
       task.schedule = {
         type: SCHEDULE_TYPES.interval,
-        intervalMs: ovr.intervalMs,
+        intervalMs: override.intervalMs,
       };
     }
-    if (task.schedule.type === SCHEDULE_TYPES.daily && typeof ovr.time === "string" && UTC_HH_MM_RE.test(ovr.time)) {
+    if (task.schedule.type === SCHEDULE_TYPES.daily && typeof override.time === "string" && UTC_HH_MM_RE.test(override.time)) {
       log.info("scheduler", "applying override", {
         id: task.id,
-        time: ovr.time,
+        time: override.time,
       });
-      task.schedule = { type: SCHEDULE_TYPES.daily, time: ovr.time };
+      task.schedule = { type: SCHEDULE_TYPES.daily, time: override.time };
     }
   }
 
@@ -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 {