mulmoclaude 0.1.2 → 0.4.0

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

@@ -18,12 +18,12 @@ export function ensureChatDir(): void {
   ensureWorkspaceDir(CHAT);
 }
 
-function metaRel(id: string): string {
-  return path.posix.join(CHAT, `${id}.json`);
+function metaRel(sessionId: string): string {
+  return path.posix.join(CHAT, `${sessionId}.json`);
 }
 
-function jsonlRel(id: string): string {
-  return path.posix.join(CHAT, `${id}.jsonl`);
+function jsonlRel(sessionId: string): string {
+  return path.posix.join(CHAT, `${sessionId}.jsonl`);
 }
 
 // ── Meta ────────────────────────────────────────────────────────
@@ -41,8 +41,8 @@ export interface SessionMeta {
 export type ReadMetaResult = { kind: "missing" } | { kind: "ok"; meta: SessionMeta } | { kind: "corrupt"; raw: string };
 
 /** Read session metadata with full outcome discrimination. */
-export async function readSessionMetaFull(id: string, rootOverride?: string): Promise<ReadMetaResult> {
-  const raw = await readTextUnder(root(rootOverride), metaRel(id));
+export async function readSessionMetaFull(sessionId: string, rootOverride?: string): Promise<ReadMetaResult> {
+  const raw = await readTextUnder(root(rootOverride), metaRel(sessionId));
   if (raw === null) return { kind: "missing" };
   try {
     return { kind: "ok", meta: JSON.parse(raw) as SessionMeta };
@@ -53,60 +53,60 @@ export async function readSessionMetaFull(id: string, rootOverride?: string): Pr
 
 /** Convenience: returns the meta or null. Treats corrupt as null
  *  (callers that need to distinguish use readSessionMetaFull). */
-export async function readSessionMeta(id: string, rootOverride?: string): Promise<SessionMeta | null> {
-  const result = await readSessionMetaFull(id, rootOverride);
+export async function readSessionMeta(sessionId: string, rootOverride?: string): Promise<SessionMeta | null> {
+  const result = await readSessionMetaFull(sessionId, rootOverride);
   return result.kind === "ok" ? result.meta : null;
 }
 
-export async function writeSessionMeta(id: string, meta: SessionMeta, rootOverride?: string): Promise<void> {
-  await writeTextUnder(root(rootOverride), metaRel(id), JSON.stringify(meta, null, 2));
+export async function writeSessionMeta(sessionId: string, meta: SessionMeta, rootOverride?: string): Promise<void> {
+  await writeTextUnder(root(rootOverride), metaRel(sessionId), JSON.stringify(meta, null, 2));
 }
 
-export async function createSessionMeta(id: string, roleId: string, firstUserMessage: string, rootOverride?: string, origin?: string): Promise<void> {
+export async function createSessionMeta(sessionId: string, roleId: string, firstUserMessage: string, rootOverride?: string, origin?: string): Promise<void> {
   const meta: Record<string, unknown> = {
     roleId,
     startedAt: new Date().toISOString(),
     firstUserMessage,
   };
   if (origin) meta.origin = origin;
-  await writeSessionMeta(id, meta, rootOverride);
+  await writeSessionMeta(sessionId, meta, rootOverride);
 }
 
-export async function backfillOrigin(id: string, origin: SessionMeta["origin"], rootOverride?: string): Promise<void> {
-  const meta = await readSessionMeta(id, rootOverride);
+export async function backfillOrigin(sessionId: string, origin: SessionMeta["origin"], rootOverride?: string): Promise<void> {
+  const meta = await readSessionMeta(sessionId, rootOverride);
   if (!meta || meta.origin) return; // already set
-  await writeSessionMeta(id, { ...meta, origin }, rootOverride);
+  await writeSessionMeta(sessionId, { ...meta, origin }, rootOverride);
 }
 
-export async function backfillFirstUserMessage(id: string, message: string, rootOverride?: string): Promise<void> {
-  const meta = await readSessionMeta(id, rootOverride);
+export async function backfillFirstUserMessage(sessionId: string, message: string, rootOverride?: string): Promise<void> {
+  const meta = await readSessionMeta(sessionId, rootOverride);
   if (!meta || meta.firstUserMessage) return;
-  await writeSessionMeta(id, { ...meta, firstUserMessage: message }, rootOverride);
+  await writeSessionMeta(sessionId, { ...meta, firstUserMessage: message }, rootOverride);
 }
 
-export async function setClaudeSessionId(id: string, claudeSessionId: string, rootOverride?: string): Promise<void> {
-  const meta = await readSessionMeta(id, rootOverride);
+export async function setClaudeSessionId(sessionId: string, claudeSessionId: string, rootOverride?: string): Promise<void> {
+  const meta = await readSessionMeta(sessionId, rootOverride);
   if (!meta) return;
-  await writeSessionMeta(id, { ...meta, claudeSessionId }, rootOverride);
+  await writeSessionMeta(sessionId, { ...meta, claudeSessionId }, rootOverride);
 }
 
-export async function clearClaudeSessionId(id: string, rootOverride?: string): Promise<void> {
-  const meta = await readSessionMeta(id, rootOverride);
+export async function clearClaudeSessionId(sessionId: string, rootOverride?: string): Promise<void> {
+  const meta = await readSessionMeta(sessionId, rootOverride);
   if (!meta) return;
   const { claudeSessionId: __removed, ...rest } = meta;
-  await writeSessionMeta(id, rest, rootOverride);
+  await writeSessionMeta(sessionId, rest, rootOverride);
 }
 
-export async function updateHasUnread(id: string, hasUnread: boolean, rootOverride?: string): Promise<void> {
-  const meta = await readSessionMeta(id, rootOverride);
+export async function updateHasUnread(sessionId: string, hasUnread: boolean, rootOverride?: string): Promise<void> {
+  const meta = await readSessionMeta(sessionId, rootOverride);
   if (!meta) return;
-  await writeSessionMeta(id, { ...meta, hasUnread }, rootOverride);
+  await writeSessionMeta(sessionId, { ...meta, hasUnread }, rootOverride);
 }
 
 // ── Jsonl ───────────────────────────────────────────────────────
 
-export function sessionJsonlAbsPath(id: string, rootOverride?: string): string {
-  return resolvePath(root(rootOverride), jsonlRel(id));
+export function sessionJsonlAbsPath(sessionId: string, rootOverride?: string): string {
+  return resolvePath(root(rootOverride), jsonlRel(sessionId));
 }
 
 /**
@@ -115,12 +115,12 @@ export function sessionJsonlAbsPath(id: string, rootOverride?: string): string {
  * `hasUnread`, `roleId`, `startedAt`, `origin`, etc. Its mtime bumps
  * whenever any of those fields change via `writeSessionMeta`.
  */
-export function sessionMetaAbsPath(id: string, rootOverride?: string): string {
-  return resolvePath(root(rootOverride), metaRel(id));
+export function sessionMetaAbsPath(sessionId: string, rootOverride?: string): string {
+  return resolvePath(root(rootOverride), metaRel(sessionId));
 }
 
-export async function readSessionJsonl(id: string, rootOverride?: string): Promise<string | null> {
-  return readTextUnder(root(rootOverride), jsonlRel(id));
+export async function readSessionJsonl(sessionId: string, rootOverride?: string): Promise<string | null> {
+  return readTextUnder(root(rootOverride), jsonlRel(sessionId));
 }
 
 /**
@@ -130,7 +130,7 @@ export async function readSessionJsonl(id: string, rootOverride?: string): Promi
  * content and don't need to worry about line termination. This
  * prevents JSONL parse failures from missing newlines.
  */
-export async function appendSessionLine(id: string, line: string, rootOverride?: string): Promise<void> {
+export async function appendSessionLine(sessionId: string, line: string, rootOverride?: string): Promise<void> {
   const normalized = line.endsWith("\n") ? line : `${line}\n`;
-  await appendFile(resolvePath(root(rootOverride), jsonlRel(id)), normalized);
+  await appendFile(resolvePath(root(rootOverride), jsonlRel(sessionId)), normalized);
 }

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;
 }
 
@@ -36,16 +36,16 @@ async function safeResolve(relativePath: string): Promise<string> {
 /** Save sheets array as a JSON file. Returns the workspace-relative path. */
 export async function saveSpreadsheet(sheets: unknown[]): Promise<string> {
   await ensureSpreadsheetsDir();
-  const id = crypto.randomUUID().replace(/-/g, "").slice(0, 16);
-  const filename = `${id}.json`;
-  await fs.writeFile(path.join(SPREADSHEETS_DIR, filename), JSON.stringify(sheets), "utf-8");
+  const sheetId = crypto.randomUUID().replace(/-/g, "").slice(0, 16);
+  const filename = `${sheetId}.json`;
+  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/todos-io.ts

@@ -10,20 +10,20 @@ import { resolvePath } from "./workspace-io.js";
 import { loadJsonFile } from "./json.js";
 import { writeFileAtomicSync } from "./atomic.js";
 
-const root = (r?: string) => r ?? workspacePath;
+const root = (workspaceRoot?: string) => workspaceRoot ?? workspacePath;
 
-export function loadTodos<T>(fallback: T, r?: string): T {
-  return loadJsonFile(resolvePath(root(r), WORKSPACE_FILES.todosItems), fallback);
+export function loadTodos<T>(fallback: T, workspaceRoot?: string): T {
+  return loadJsonFile(resolvePath(root(workspaceRoot), WORKSPACE_FILES.todosItems), fallback);
 }
 
-export function saveTodos(items: unknown, r?: string): void {
-  writeFileAtomicSync(resolvePath(root(r), WORKSPACE_FILES.todosItems), JSON.stringify(items, null, 2));
+export function saveTodos(items: unknown, workspaceRoot?: string): void {
+  writeFileAtomicSync(resolvePath(root(workspaceRoot), WORKSPACE_FILES.todosItems), JSON.stringify(items, null, 2));
 }
 
-export function loadColumns<T>(fallback: T, r?: string): T {
-  return loadJsonFile(resolvePath(root(r), WORKSPACE_FILES.todosColumns), fallback);
+export function loadColumns<T>(fallback: T, workspaceRoot?: string): T {
+  return loadJsonFile(resolvePath(root(workspaceRoot), WORKSPACE_FILES.todosColumns), fallback);
 }
 
-export function saveColumns(columns: unknown, r?: string): void {
-  writeFileAtomicSync(resolvePath(root(r), WORKSPACE_FILES.todosColumns), JSON.stringify(columns, null, 2));
+export function saveColumns(columns: unknown, workspaceRoot?: string): void {
+  writeFileAtomicSync(resolvePath(root(workspaceRoot), WORKSPACE_FILES.todosColumns), JSON.stringify(columns, null, 2));
 }

package/server/utils/files/user-tasks-io.ts

@@ -11,15 +11,15 @@ import { resolvePath } from "./workspace-io.js";
 import { loadJsonFile } from "./json.js";
 import { writeFileAtomic } from "./atomic.js";
 
-const root = (r?: string) => r ?? workspacePath;
+const root = (workspaceRoot?: string) => workspaceRoot ?? workspacePath;
 
-export function loadUserTasks<T>(r?: string): T[] {
-  const tasks = loadJsonFile<T[]>(resolvePath(root(r), WORKSPACE_FILES.schedulerUserTasks), []);
+export function loadUserTasks<T>(workspaceRoot?: string): T[] {
+  const tasks = loadJsonFile<T[]>(resolvePath(root(workspaceRoot), WORKSPACE_FILES.schedulerUserTasks), []);
   return Array.isArray(tasks) ? tasks : [];
 }
 
-export async function saveUserTasks<T>(tasks: T[], r?: string): Promise<void> {
-  const filePath = resolvePath(root(r), WORKSPACE_FILES.schedulerUserTasks);
+export async function saveUserTasks<T>(tasks: T[], workspaceRoot?: string): Promise<void> {
+  const filePath = resolvePath(root(workspaceRoot), WORKSPACE_FILES.schedulerUserTasks);
   await mkdir(path.dirname(filePath), { recursive: true });
   await writeFileAtomic(filePath, JSON.stringify(tasks, null, 2));
 }

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;
+}

package/server/utils/request.ts

@@ -3,11 +3,17 @@
 // Centralizes patterns that were duplicated across route handlers
 // (3+ different ways to read `req.query.session`).
 
-// Use a minimal interface so the helpers work with any Express
-// Request generic (Request<object, ...>, Request<Params, ...>, etc.)
-// without type incompatibility.
+// `query: object` so the helpers work with any Express Request
+// generic — `Request<Params, ResBody, ReqBody, Query>`. A narrow
+// `Query` generic like `{ path?: string }` isn't assignable to
+// `Record<string, unknown>` (no index signature), so we widen to
+// `object` and cast internally when reading a key.
 interface HasQuery {
-  query: Record<string, unknown>;
+  query: object;
+}
+
+function readQueryKey(queryObj: object, key: string): unknown {
+  return (queryObj as Record<string, unknown>)[key];
 }
 
 /**
@@ -15,7 +21,7 @@ interface HasQuery {
  * Returns the string value, or "" if missing/non-string.
  */
 export function getSessionQuery(req: HasQuery): string {
-  const raw = req.query.session;
+  const raw = readQueryKey(req.query, "session");
   return typeof raw === "string" ? raw : "";
 }
 
@@ -24,6 +30,6 @@ export function getSessionQuery(req: HasQuery): string {
  * Returns the string value, or undefined if missing/non-string.
  */
 export function getOptionalStringQuery(req: HasQuery, key: string): string | undefined {
-  const raw = req.query[key];
+  const raw = readQueryKey(req.query, key);
   return typeof raw === "string" ? raw : undefined;
 }

package/server/utils/spawn.ts

@@ -28,7 +28,7 @@ export function extractClaudeErrorMessage(stdout: string): string | null {
   if (!isRecord(parsed)) return null;
   if (parsed.is_error !== true) return null;
   if (Array.isArray(parsed.errors) && parsed.errors.length > 0) {
-    const joined = parsed.errors.filter((e): e is string => typeof e === "string").join("; ");
+    const joined = parsed.errors.filter((err): err is string => typeof err === "string").join("; ");
     if (joined.length > 0) return joined;
   }
   const subtype = typeof parsed.subtype === "string" ? parsed.subtype : "";

package/server/utils/types.ts

@@ -23,12 +23,12 @@ export function isNonEmptyString(value: unknown): value is string {
 /** Record whose values are all strings. */
 export function isStringRecord(value: unknown): value is Record<string, string> {
   if (!isRecord(value)) return false;
-  return Object.values(value).every((v) => typeof v === "string");
+  return Object.values(value).every((val) => typeof val === "string");
 }
 
 /** String array (every element is a string). */
 export function isStringArray(value: unknown): value is string[] {
-  return Array.isArray(value) && value.every((v) => typeof v === "string");
+  return Array.isArray(value) && value.every((val) => typeof val === "string");
 }
 
 /** Error-like object with a `code` property (e.g. Node.js fs errors). */