mulmoclaude 0.1.2 → 0.4.0

package/server/agent/prompt.ts

@@ -7,6 +7,8 @@ import { WORKSPACE_DIRS, WORKSPACE_FILES } from "../workspace/paths.js";
 import { getCachedCustomDirs, buildCustomDirsPrompt } from "../workspace/custom-dirs.js";
 import { TOOL_NAMES } from "../../src/config/toolNames.js";
 import { getCachedReferenceDirs, buildReferenceDirsPrompt } from "../workspace/reference-dirs.js";
+import { log } from "../system/logger/index.js";
+import { toLocalIsoDate } from "../utils/date.js";
 
 export const SYSTEM_PROMPT = `You are MulmoClaude, a versatile assistant app with rich visual output.
 
@@ -242,6 +244,35 @@ export function buildNewsConciergeContext(role: Role): string | null {
   return NEWS_CONCIERGE_PROMPT;
 }
 
+// Single-paragraph prompts up to this length collapse into a compact
+// `- **name**: body` bullet instead of the old `### name\n\n body`
+// heading. Saves ~25 chars of heading overhead per plugin and keeps the
+// whole "Plugin Instructions" block scannable. Multi-paragraph or
+// longer prompts keep the heading form so the structure is preserved.
+const PLUGIN_COMPACT_MAX_CHARS = 400;
+
+export function formatPluginSection(name: string, prompt: string): string {
+  // Normalize CRLF → LF first: a prompt authored on Windows would
+  // otherwise hide its paragraph break inside `\r\n\r\n` and the
+  // `includes("\n\n")` check would falsely classify it as single-paragraph,
+  // collapsing a multi-paragraph prompt into one bullet.
+  const normalized = prompt.replace(/\r\n/g, "\n");
+  const trimmed = normalized.trim();
+  const isSingleParagraph = !trimmed.includes("\n\n");
+  if (isSingleParagraph && trimmed.length <= PLUGIN_COMPACT_MAX_CHARS) {
+    // Flatten any single newlines inside the paragraph so the bullet
+    // stays on one visual line. Split-join avoids the super-linear
+    // backtracking that `\s*\n\s*` would bring (sonarjs/slow-regex).
+    const oneLine = trimmed
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+      .join(" ");
+    return `- **${name}**: ${oneLine}`;
+  }
+  return `### ${name}\n\n${trimmed}`;
+}
+
 export function buildPluginPromptSections(role: Role): string[] {
   // Widen to Set<string> so the `.has()` checks accept arbitrary
   // definition names (PLUGIN_DEFS entries and MCP tool names are
@@ -253,17 +284,22 @@ export function buildPluginPromptSections(role: Role): string[] {
   // Some package plugins use an older gui-chat-protocol without the `prompt`
   // field, so access it via `in` check to keep TypeScript happy.
   const defPrompts = Object.fromEntries(
-    PLUGIN_DEFS.filter((d) => "prompt" in d && d.prompt && allowedPlugins.has(d.name)).map((d) => [d.name, (d as unknown as { prompt: string }).prompt]),
+    PLUGIN_DEFS.filter((definition) => "prompt" in definition && definition.prompt && allowedPlugins.has(definition.name)).map((definition) => [
+      definition.name,
+      (definition as unknown as { prompt: string }).prompt,
+    ]),
   );
 
   // Collect prompts from MCP tools
   const mcpToolPrompts = Object.fromEntries(
-    mcpTools.filter((t) => t.prompt && allowedPlugins.has(t.definition.name) && isMcpToolEnabled(t)).map((t) => [t.definition.name, t.prompt as string]),
+    mcpTools
+      .filter((toolDef) => toolDef.prompt && allowedPlugins.has(toolDef.definition.name) && isMcpToolEnabled(toolDef))
+      .map((toolDef) => [toolDef.definition.name, toolDef.prompt as string]),
   );
 
   // MCP tool prompts override definition prompts if both exist
   const merged = { ...defPrompts, ...mcpToolPrompts };
-  return Object.entries(merged).map(([name, prompt]) => `### ${name}\n\n${prompt}`);
+  return Object.entries(merged).map(([name, prompt]) => formatPluginSection(name, prompt));
 }
 
 export interface SystemPromptParams {
@@ -274,6 +310,61 @@ export interface SystemPromptParams {
    *  environment has no such guarantees, so without Docker we stay
    *  silent. */
   useDocker: boolean;
+  /** IANA timezone from the user's browser (e.g. "Asia/Tokyo"). When
+   *  present, drives the time-section instruction that tells the
+   *  agent to interpret bare times in that zone without asking the
+   *  user every turn. Missing or invalid values fall back to
+   *  server-local date only. */
+  userTimezone?: string;
+}
+
+// Accept IANA-looking strings only. Anything else (including
+// line-break injection attempts from a malicious client) is rejected
+// and the prompt falls back to the server-local form.
+const IANA_TZ_RE = /^[A-Za-z][A-Za-z0-9_+/-]{0,63}$/;
+function sanitizeUserTimezone(zoneId: string | undefined): string | undefined {
+  if (typeof zoneId !== "string") return undefined;
+  if (!IANA_TZ_RE.test(zoneId)) return undefined;
+  try {
+    // Throws a RangeError if the zone isn't recognized by the ICU
+    // data on this runtime.
+    new Intl.DateTimeFormat("en-US", { timeZone: zoneId });
+    return zoneId;
+  } catch {
+    return undefined;
+  }
+}
+
+function formatDateInTimezone(date: Date, zoneId: string): string | null {
+  try {
+    // en-CA gives us YYYY-MM-DD directly, matching the rest of the
+    // workspace's date convention.
+    return new Intl.DateTimeFormat("en-CA", {
+      timeZone: zoneId,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+    }).format(date);
+  } catch {
+    return null;
+  }
+}
+
+// Compact prompt section that tells the agent (a) today's date in the
+// user's zone and (b) not to pester the user about timezones for every
+// bare time expression. Falls back to server-local date (previous
+// behaviour) when the browser didn't give us a valid zone.
+export function buildTimeSection(now: Date, userTimezone: string | undefined): string {
+  const sanitized = sanitizeUserTimezone(userTimezone);
+  if (!sanitized) {
+    return `Today's date: ${toLocalIsoDate(now)}`;
+  }
+  const today = formatDateInTimezone(now, sanitized) ?? toLocalIsoDate(now);
+  return `## Time & Timezone
+
+The user's browser timezone is ${sanitized}. Today's date in that timezone is ${today}.
+
+When the user mentions a time without explicitly naming a city or timezone, assume their local timezone (${sanitized}) and proceed — do NOT ask for clarification. Only confirm when the user explicitly mentions another location or timezone (e.g. "3pm in New York", "JST", "UTC+5").`;
 }
 
 // Mirror the tool set installed by Dockerfile.sandbox. Kept here so a
@@ -290,7 +381,47 @@ The bash tool runs inside a Docker sandbox. The following tools are guaranteed p
 
 Runtime \`pip install\` / \`apt install\` are not available (no network-installed deps by design). Work within the list above; if something is missing, say so rather than attempting to install it.`;
 
-function buildInlinedHelpFiles(rolePrompt: string, workspacePath: string): string[] {
+// Files ≤ this threshold stay inlined verbatim; above it, only a short
+// summary + pointer reaches the system prompt and the full content is
+// fetched on demand via the Read tool. 2000 chars keeps today's small
+// helps (github.md ~1.2K, spreadsheet.md ~1.4K) inline, while wiki.md /
+// mulmoscript.md / telegram.md (4–7K each) switch to summary mode. See
+// plans/feat-help-pointer-threshold.md and issue #487.
+const HELP_INLINE_THRESHOLD_CHARS = 2000;
+const HELP_SUMMARY_PARAGRAPH_CAP = 200;
+
+// Pull a short, prompt-friendly summary from a help file:
+// - first H1 heading (identifies the file)
+// - first non-empty, non-heading paragraph, truncated to ~200 chars
+// No frontmatter required — the goal is zero ceremony for help authors.
+export function summarizeHelpContent(content: string): string {
+  const lines = content.split("\n");
+  const heading = lines
+    .find((line) => /^#\s+\S/.test(line))
+    ?.replace(/^#\s+/, "")
+    .trim();
+
+  let paragraph = "";
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      if (paragraph) break;
+      continue;
+    }
+    paragraph = paragraph ? `${paragraph} ${trimmed}` : trimmed;
+    if (paragraph.length >= HELP_SUMMARY_PARAGRAPH_CAP) break;
+  }
+  if (paragraph.length > HELP_SUMMARY_PARAGRAPH_CAP) {
+    paragraph = paragraph.slice(0, HELP_SUMMARY_PARAGRAPH_CAP).trimEnd() + "…";
+  }
+
+  const parts: string[] = [];
+  if (heading) parts.push(heading);
+  if (paragraph) parts.push(paragraph);
+  return parts.join(" — ");
+}
+
+export function buildInlinedHelpFiles(rolePrompt: string, workspacePath: string): string[] {
   // Match either legacy `helps/<name>.md` or post-#284
   // `config/helps/<name>.md` references in role prompts. Both
   // resolve to the same on-disk file under `config/helps/`.
@@ -305,12 +436,19 @@ function buildInlinedHelpFiles(rolePrompt: string, workspacePath: string): strin
       const fullPath = join(workspacePath, WORKSPACE_DIRS.helps, name);
       if (!existsSync(fullPath)) return null;
       const content = readFileSync(fullPath, "utf-8").trim();
-      // Keep the heading anchored to the canonical post-#284 path
-      // so the LLM reading the inlined block can't accidentally
-      // Read() the stale legacy location.
-      return content ? `### ${WORKSPACE_DIRS.helps}/${name}\n\n${content}` : null;
+      if (!content) return null;
+      // Keep the heading anchored to the canonical post-#284 path so
+      // the LLM can't accidentally Read() the stale legacy location.
+      const canonicalPath = `${WORKSPACE_DIRS.helps}/${name}`;
+      const header = `### ${canonicalPath}`;
+      if (content.length <= HELP_INLINE_THRESHOLD_CHARS) {
+        return `${header}\n\n${content}`;
+      }
+      const summary = summarizeHelpContent(content);
+      const pointer = `Detailed reference: use Read on \`${canonicalPath}\` when you need the full content.`;
+      return summary ? `${header}\n\n${summary}\n\n${pointer}` : `${header}\n\n${pointer}`;
     })
-    .filter((s): s is string => s !== null);
+    .filter((section): section is string => section !== null);
 }
 
 // Wrap a list of sub-entries under a single markdown heading, or
@@ -323,27 +461,55 @@ export function headingSection(heading: string, items: string[]): string | null
   return `## ${heading}\n\n${items.join("\n\n")}`;
 }
 
+// Named sections so buildSystemPrompt can log a size breakdown
+// without inventing labels at the call site.
+interface NamedSection {
+  name: string;
+  content: string | null;
+}
+
+// System prompt above this total size gets a warning in the log —
+// 20K chars is ~5K tokens, a noticeable slice of the context budget
+// and a useful early-warning threshold. Doesn't block, just flags.
+const SYSTEM_PROMPT_WARN_THRESHOLD_CHARS = 20000;
+
 export function buildSystemPrompt(params: SystemPromptParams): string {
-  const { role, workspacePath, useDocker } = params;
-
-  // Every section builder returns either its content or null. The
-  // orchestrator just filters out nulls and joins — no per-section
-  // `...(cond ? [x] : [])` ceremony at the bottom.
-  const sections: Array<string | null> = [
-    SYSTEM_PROMPT,
-    role.prompt,
-    `Workspace directory: ${workspacePath}`,
-    `Today's date: ${new Date().toISOString().split("T")[0]}`,
-    buildMemoryContext(workspacePath),
-    useDocker ? SANDBOX_TOOLS_HINT : null,
-    buildWikiContext(workspacePath),
-    buildSourcesContext(workspacePath),
-    buildNewsConciergeContext(role),
-    buildCustomDirsPrompt(getCachedCustomDirs()),
-    buildReferenceDirsPrompt(getCachedReferenceDirs(), useDocker),
-    headingSection("Reference Files", buildInlinedHelpFiles(role.prompt, workspacePath)),
-    headingSection("Plugin Instructions", buildPluginPromptSections(role)),
+  const { role, workspacePath, useDocker, userTimezone } = params;
+
+  const sections: NamedSection[] = [
+    { name: "base", content: SYSTEM_PROMPT },
+    { name: "role", content: role.prompt },
+    { name: "workspace", content: `Workspace directory: ${workspacePath}` },
+    { name: "time", content: buildTimeSection(new Date(), userTimezone) },
+    { name: "memory", content: buildMemoryContext(workspacePath) },
+    { name: "sandbox", content: useDocker ? SANDBOX_TOOLS_HINT : null },
+    { name: "wiki", content: buildWikiContext(workspacePath) },
+    { name: "sources", content: buildSourcesContext(workspacePath) },
+    { name: "news-concierge", content: buildNewsConciergeContext(role) },
+    { name: "custom-dirs", content: buildCustomDirsPrompt(getCachedCustomDirs()) },
+    { name: "reference-dirs", content: buildReferenceDirsPrompt(getCachedReferenceDirs(), useDocker) },
+    { name: "helps", content: headingSection("Reference Files", buildInlinedHelpFiles(role.prompt, workspacePath)) },
+    { name: "plugins", content: headingSection("Plugin Instructions", buildPluginPromptSections(role)) },
   ];
 
-  return sections.filter((s): s is string => s !== null).join("\n\n");
+  const kept = sections.filter((section): section is NamedSection & { content: string } => section.content !== null);
+  const result = kept.map((section) => section.content).join("\n\n");
+
+  // Log a size breakdown so prompt-bloat regressions show up in
+  // normal run logs. Warn tier fires for outright large prompts;
+  // the debug tier gives the per-section counts for when the
+  // warning hits (or just when someone wants a baseline).
+  const breakdown = kept.map((section) => `${section.name}=${section.content.length}`).join(" ");
+  const total = result.length;
+  log.debug("prompt", "system-prompt size", { total, breakdown, roleId: role.id });
+  if (total >= SYSTEM_PROMPT_WARN_THRESHOLD_CHARS) {
+    log.warn("prompt", "system-prompt exceeds warn threshold", {
+      total,
+      threshold: SYSTEM_PROMPT_WARN_THRESHOLD_CHARS,
+      breakdown,
+      roleId: role.id,
+    });
+  }
+
+  return result;
 }

package/server/agent/resumeFailover.ts

@@ -77,12 +77,12 @@ function parseTranscriptEntries(jsonlContent: string): TranscriptEntry[] {
       continue;
     }
     if (!isRecord(entry)) continue;
-    const o = entry;
-    if (o.type !== EVENT_TYPES.text) continue;
-    if (o.source !== "user" && o.source !== "assistant") continue;
-    const message = o.message;
+    const record = entry;
+    if (record.type !== EVENT_TYPES.text) continue;
+    if (record.source !== "user" && record.source !== "assistant") continue;
+    const message = record.message;
     if (typeof message !== "string" || message.length === 0) continue;
-    out.push({ source: o.source, text: message });
+    out.push({ source: record.source, text: message });
   }
   return out;
 }

package/server/agent/sandboxMounts.ts

@@ -15,7 +15,7 @@
 // See docs/sandbox-credentials.md for the user-facing contract.
 
 import path from "node:path";
-import fs from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { log } from "../system/logger/index.js";
@@ -48,7 +48,7 @@ export interface SandboxMountSpec {
  */
 export function buildAllowedConfigMounts(home: string = homedir()): Record<string, SandboxMountSpec> {
   return {
-    gh: {
+    ["gh"]: {
       name: "gh",
       hostPath: path.join(home, ".config", "gh"),
       containerPath: "/home/node/.config/gh",
@@ -105,7 +105,7 @@ export function resolveMountNames(names: readonly string[], allowed: Record<stri
 
 function hostPathExists(spec: SandboxMountSpec): boolean {
   try {
-    const stat = fs.statSync(spec.hostPath);
+    const stat = statSync(spec.hostPath);
     return spec.kind === "dir" ? stat.isDirectory() : stat.isFile();
   } catch {
     return false;
@@ -181,7 +181,7 @@ export function sshAgentForwardArgs(
       skippedReason: "SSH_AUTH_SOCK not set on host",
     };
   }
-  if (!fs.existsSync(sshAuthSock)) {
+  if (!existsSync(sshAuthSock)) {
     return {
       args: [],
       skippedReason: `SSH_AUTH_SOCK=${sshAuthSock} not found on host`,
@@ -261,7 +261,7 @@ export function resolveSandboxAuth(params: ResolveSandboxAuthParams): ResolvedSa
   const args = [...configMountArgs(parsed.resolved), ...sshResult.args, ...sshAllowedHostsArgs, ...ghTokenArgs.args];
   const allowedHostsSuffix = sshResult.args.length > 0 && params.sshAllowedHosts ? ` → hosts: ${params.sshAllowedHosts}` : "";
   const appliedDescriptions = [
-    ...parsed.resolved.map((s) => `${s.name} (${s.description})`),
+    ...parsed.resolved.map((spec) => `${spec.name} (${spec.description})`),
     ...(sshResult.args.length > 0 ? [`ssh-agent forward${allowedHostsSuffix}`] : []),
     ...(ghTokenArgs.args.length > 0 ? ["gh CLI (GH_TOKEN fallback)"] : []),
   ];
@@ -284,7 +284,7 @@ export function resolveSandboxAuth(params: ResolveSandboxAuthParams): ResolvedSa
 // GH_TOKEN env var. This only runs when "gh" was explicitly
 // requested (#259 opt-in principle).
 function resolveGhTokenFallback(requestedNames: readonly string[], parsed: ParsedMountList): { args: string[] } {
-  const ghRequested = requestedNames.some((n) => n.trim() === "gh");
+  const ghRequested = requestedNames.some((name) => name.trim() === "gh");
   if (!ghRequested) return { args: [] };
 
   // If an explicit GH_TOKEN is already in the environment, pass it.
@@ -295,8 +295,8 @@ function resolveGhTokenFallback(requestedNames: readonly string[], parsed: Parse
   // If the file mount resolved (hosts.yml exists), the token might
   // be in the file. Check if it's keyring-based by looking for
   // "oauth_token" in the hosts.yml — if missing, fall back.
-  const ghResolved = parsed.resolved.some((s) => s.name === "gh");
-  const ghMissing = parsed.missing.some((s) => s.name === "gh");
+  const ghResolved = parsed.resolved.some((spec) => spec.name === "gh");
+  const ghMissing = parsed.missing.some((spec) => spec.name === "gh");
 
   // gh dir doesn't exist at all → try extracting from keyring
   // gh dir exists (mounted) → still try, since keyring auth leaves
@@ -324,6 +324,6 @@ function resolveGhTokenFallback(requestedNames: readonly string[], parsed: Parse
 // Docker accepts POSIX-style paths even on Windows when using
 // Docker Desktop, and the rest of the codebase already uses this
 // helper in buildDockerSpawnArgs.
-function toDockerPath(p: string): string {
-  return p.replace(/\\/g, "/");
+function toDockerPath(hostPath: string): string {
+  return hostPath.replace(/\\/g, "/");
 }

package/server/agent/stream.ts

@@ -98,7 +98,7 @@ function extractTextDelta(event: RawStreamEvent): string | null {
 // Filter assistant block events: when deltas already streamed the
 // text, remove text-type events to prevent duplication.
 function filterAssistantBlocks(blockEvents: AgentEvent[], deltaStreamed: boolean): AgentEvent[] {
-  return deltaStreamed ? blockEvents.filter((e) => e.type !== EVENT_TYPES.text) : blockEvents;
+  return deltaStreamed ? blockEvents.filter((agentEvent) => agentEvent.type !== EVENT_TYPES.text) : blockEvents;
 }
 
 // Stateful parser that deduplicates text across the three stages
@@ -151,11 +151,11 @@ export function createStreamParser(): {
     }
 
     const content = event.message?.content;
-    const blockEvents = Array.isArray(content) ? content.map(blockToEvent).filter((e): e is AgentEvent => e !== null) : [];
+    const blockEvents = Array.isArray(content) ? content.map(blockToEvent).filter((agentEvent): agentEvent is AgentEvent => agentEvent !== null) : [];
 
     if (event.type === "assistant") {
       const filtered = filterAssistantBlocks(blockEvents, textStreamedFromDeltas);
-      if (filtered.some((e) => e.type === EVENT_TYPES.text)) {
+      if (filtered.some((agentEvent) => agentEvent.type === EVENT_TYPES.text)) {
         textEmitted = true;
       }
       return [{ type: EVENT_TYPES.status, message: "Thinking..." }, ...filtered];
@@ -185,7 +185,7 @@ export function parseStreamEvent(event: RawStreamEvent): AgentEvent[] {
   }
 
   const content = event.message?.content;
-  const blockEvents = Array.isArray(content) ? content.map(blockToEvent).filter((e): e is AgentEvent => e !== null) : [];
+  const blockEvents = Array.isArray(content) ? content.map(blockToEvent).filter((agentEvent): agentEvent is AgentEvent => agentEvent !== null) : [];
 
   if (event.type === "assistant") {
     return [{ type: EVENT_TYPES.status, message: "Thinking..." }, ...blockEvents];

package/server/api/auth/bearerAuth.ts

@@ -1,8 +1,8 @@
 import { timingSafeEqual } from "crypto";
 
-function safeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+function safeEqual(left: string, right: string): boolean {
+  if (left.length !== right.length) return false;
+  return timingSafeEqual(Buffer.from(left), Buffer.from(right));
 }
 
 // Bearer token middleware (#272). Reject any `/api/*` request whose

package/server/api/auth/token.ts

@@ -21,7 +21,7 @@
 // setting it once on both sides survives restarts.
 
 import { randomBytes } from "crypto";
-import fs from "fs";
+import { promises } from "fs";
 import { writeFileAtomic } from "../../utils/files/index.js";
 import { log } from "../../system/logger/index.js";
 import { isNonEmptyString } from "../../utils/types.js";
@@ -83,7 +83,7 @@ function resolveToken(override: string | undefined): string {
  */
 export async function deleteTokenFile(tokenPath: string = WORKSPACE_PATHS.sessionToken): Promise<void> {
   try {
-    await fs.promises.unlink(tokenPath);
+    await promises.unlink(tokenPath);
   } catch {
     /* already gone — nothing to do */
   }

package/server/api/routes/agent.ts

@@ -105,12 +105,16 @@ export interface StartChatParams {
   /** Where this session originates (#486). Accepts string for
    *  cross-package compatibility (chat-service passes string). */
   origin?: string;
+  /** IANA timezone the user's browser resolved (e.g. "Asia/Tokyo").
+   *  Validated server-side before it reaches the system prompt — an
+   *  invalid or missing value falls back to server-local time. */
+  userTimezone?: string;
 }
 
 export type StartChatResult = { kind: "started"; chatSessionId: string } | { kind: "error"; error: string; status?: number };
 
 export async function startChat(params: StartChatParams): Promise<StartChatResult> {
-  const { message, roleId, chatSessionId, selectedImageData, attachments } = params;
+  const { message, roleId, chatSessionId, selectedImageData, attachments, userTimezone } = params;
 
   if (!message || !roleId || !chatSessionId) {
     return {
@@ -203,6 +207,7 @@ export async function startChat(params: StartChatParams): Promise<StartChatResul
     requestStartedAt,
     toolArgsCache: createArgsCache(),
     attachments: mergeAttachments(selectedImageData, attachments),
+    userTimezone,
   });
 
   return { kind: "started", chatSessionId };
@@ -239,6 +244,7 @@ interface AgentBody {
   roleId: string;
   chatSessionId: string;
   selectedImageData?: string;
+  userTimezone?: string;
 }
 
 interface ErrorResponse {
@@ -271,6 +277,7 @@ interface BackgroundRunParams {
   requestStartedAt: number;
   toolArgsCache: ReturnType<typeof createArgsCache>;
   attachments: Attachment[] | undefined;
+  userTimezone: string | undefined;
 }
 
 // Per-event side-effect context passed to `handleAgentEvent`.
@@ -358,7 +365,8 @@ async function flushTextAccumulator(ctx: EventContext): Promise<void> {
 }
 
 async function runAgentInBackground(params: BackgroundRunParams): Promise<void> {
-  const { decoratedMessage, role, chatSessionId, claudeSessionId, abortSignal, resultsFilePath, requestStartedAt, toolArgsCache, attachments } = params;
+  const { decoratedMessage, role, chatSessionId, claudeSessionId, abortSignal, resultsFilePath, requestStartedAt, toolArgsCache, attachments, userTimezone } =
+    params;
 
   const eventCtx: EventContext = {
     chatSessionId,
@@ -378,7 +386,17 @@ async function runAgentInBackground(params: BackgroundRunParams): Promise<void>
   try {
     while (true) {
       let staleSessionDetected = false;
-      for await (const event of runAgent(currentMessage, role, workspacePath, chatSessionId, PORT, currentClaudeSessionId, abortSignal, attachments)) {
+      for await (const event of runAgent(
+        currentMessage,
+        role,
+        workspacePath,
+        chatSessionId,
+        PORT,
+        currentClaudeSessionId,
+        abortSignal,
+        attachments,
+        userTimezone,
+      )) {
         if (failoverAttemptsRemaining > 0 && event.type === EVENT_TYPES.error && typeof event.message === "string" && isStaleSessionError(event.message)) {
           // Swallow the error — we're about to recover. `break`
           // abandons the current generator; since the event is only

package/server/api/routes/config.ts

@@ -43,7 +43,7 @@ function isMcpPutBody(value: unknown): value is { servers: McpServerEntry[] } {
   if (!Array.isArray(value.servers)) return false;
   // Full shape validation happens inside fromMcpEntries (throws on
   // anything malformed). Here we just confirm the envelope.
-  return value.servers.every((e) => isRecord(e) && "id" in e && "spec" in e);
+  return value.servers.every((entry) => isRecord(entry) && "id" in entry && "spec" in entry);
 }
 
 // Parse an MCP payload through `fromMcpEntries` (which does the full

package/server/api/routes/files.ts

@@ -1,10 +1,11 @@
 import { Router, Request, Response } from "express";
-import fs from "fs";
+import { ReadStream, Stats, createReadStream, readFileSync, realpathSync } from "fs";
 import path from "path";
 import { workspacePath } from "../../workspace/workspace.js";
 import { statSafe, statSafeAsync, readDirSafeAsync, resolveWithinRoot, writeFileAtomic } from "../../utils/files/index.js";
 import { errorMessage } from "../../utils/errors.js";
 import { badRequest, notFound, sendError, serverError } from "../../utils/httpError.js";
+import { getOptionalStringQuery } from "../../utils/request.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
 import { GitignoreFilter } from "../../utils/gitignore.js";
 import { getCachedReferenceDirs } from "../../workspace/reference-dirs.js";
@@ -187,7 +188,7 @@ export function classify(filename: string): ContentKind {
 // Cached realpath of the workspace. Computed once at module load so
 // every request avoids the syscall. resolveWithinRoot needs an
 // already-realpath'd root.
-const workspaceReal = fs.realpathSync(workspacePath);
+const workspaceReal = realpathSync(workspacePath);
 
 // Wraps the shared resolveWithinRoot helper with the additional
 // hidden-dir traversal check (e.g. `.git/config`). `buildTreeAsync`
@@ -230,12 +231,12 @@ function resolveRefPath(prefixedPath: string): string | null {
   const remainder = slashIdx >= 0 ? afterPrefix.slice(slashIdx + 1) : "";
 
   const entries = getCachedReferenceDirs();
-  const entry = entries.find((e) => e.label === label);
+  const entry = entries.find((refEntry) => refEntry.label === label);
   if (!entry) return null;
 
   let rootReal: string;
   try {
-    rootReal = fs.realpathSync(entry.hostPath);
+    rootReal = realpathSync(entry.hostPath);
   } catch {
     return null;
   }
@@ -276,7 +277,7 @@ export function parseRange(header: string, size: number): ByteRange | null {
   // RFC 7233 §2.1: "A Range request on a representation whose current
   // length is 0 cannot be satisfied". We also need this guard at the
   // top because the naive suffix-range math below produces `end = -1`
-  // for zero-byte files, which then crashes `fs.createReadStream`
+  // for zero-byte files, which then crashes `createReadStream`
   // with `ERR_OUT_OF_RANGE`.
   if (size <= 0) return null;
   const match = /^bytes=(\d*)-(\d*)$/i.exec(header.trim());
@@ -325,7 +326,7 @@ function applyRawSecurityHeaders(res: Response): void {
 // If the read stream errors mid-flight (file deleted, disk error,
 // permissions changed), surface a clean failure to the client instead
 // of leaving the connection hanging.
-function pipeWithErrorHandling(stream: fs.ReadStream, res: Response<ErrorResponse>): void {
+function pipeWithErrorHandling(stream: ReadStream, res: Response<ErrorResponse>): void {
   stream.on("error", (err) => {
     if (res.headersSent) {
       res.destroy(err);
@@ -340,7 +341,7 @@ function pipeWithErrorHandling(stream: fs.ReadStream, res: Response<ErrorRespons
 // the same security filters as the original sync implementation
 // (hidden dirs, sensitive files, symlinks all rejected) and the same
 // ordering (dirs before files, alphabetical within type). Uses
-// `fs.promises` throughout so the walk never blocks the event loop,
+// `promises` throughout so the walk never blocks the event loop,
 // and fans out each directory's children in parallel via
 // `Promise.all`.
 //
@@ -393,10 +394,10 @@ export async function buildTreeAsync(absPath: string, relPath: string, gitFilter
     return buildTreeAsync(childAbs, childRel, localFilter);
   });
   const resolved = await Promise.all(childPromises);
-  const children = resolved.filter((c): c is TreeNode => c !== null);
-  children.sort((a, b) => {
-    if (a.type !== b.type) return a.type === "dir" ? -1 : 1;
-    return a.name.localeCompare(b.name);
+  const children = resolved.filter((childNode): childNode is TreeNode => childNode !== null);
+  children.sort((leftChild, rightChild) => {
+    if (leftChild.type !== rightChild.type) return leftChild.type === "dir" ? -1 : 1;
+    return leftChild.name.localeCompare(rightChild.name);
   });
   return {
     name: relPath ? path.basename(relPath) : "",
@@ -460,10 +461,10 @@ export async function listDirShallow(absPath: string, relPath: string, gitFilter
     };
   });
   const resolved = await Promise.all(childPromises);
-  const children = resolved.filter((c): c is TreeNode => c !== null);
-  children.sort((a, b) => {
-    if (a.type !== b.type) return a.type === "dir" ? -1 : 1;
-    return a.name.localeCompare(b.name);
+  const children = resolved.filter((childNode): childNode is TreeNode => childNode !== null);
+  children.sort((leftChild, rightChild) => {
+    if (leftChild.type !== rightChild.type) return leftChild.type === "dir" ? -1 : 1;
+    return leftChild.name.localeCompare(rightChild.name);
   });
   return {
     name: relPath ? path.basename(relPath) : "",
@@ -493,7 +494,7 @@ router.get(API_ROUTES.files.tree, async (_req: Request<object, unknown, unknown,
 // (no recursion) so the client can render the tree incrementally.
 // `path` is optional; empty / missing = workspace root.
 router.get(API_ROUTES.files.dir, async (req: Request<object, unknown, unknown, PathQuery>, res: Response<TreeNode | ErrorResponse>) => {
-  const relPath = typeof req.query.path === "string" ? req.query.path : "";
+  const relPath = getOptionalStringQuery(req, "path") ?? "";
 
   // Reference directory branch — resolve against the registered ref dir
   if (isRefPath(relPath)) {
@@ -567,8 +568,8 @@ interface PathQuery {
 function resolveAndStatFile<T>(
   req: Request<object, unknown, unknown, PathQuery>,
   res: Response<T | ErrorResponse>,
-): { relPath: string; absPath: string; stat: fs.Stats } | null {
-  const relPath = typeof req.query.path === "string" ? req.query.path : "";
+): { relPath: string; absPath: string; stat: Stats } | null {
+  const relPath = getOptionalStringQuery(req, "path") ?? "";
   if (!relPath) {
     badRequest(res, "path required");
     return null;
@@ -668,7 +669,7 @@ router.get(API_ROUTES.files.content, (req: Request<object, unknown, unknown, Pat
   }
   let content: string;
   try {
-    content = fs.readFileSync(absPath, "utf-8");
+    content = readFileSync(absPath, "utf-8");
   } catch (err) {
     res.status(500).json({ error: `Failed to read file: ${errorMessage(err)}` });
     return;
@@ -779,12 +780,12 @@ router.get(API_ROUTES.files.raw, (req: Request<object, unknown, unknown, PathQue
     res.status(206);
     res.setHeader("Content-Range", `bytes ${range.start}-${range.end}/${stat.size}`);
     res.setHeader("Content-Length", String(range.end - range.start + 1));
-    pipeWithErrorHandling(fs.createReadStream(absPath, { start: range.start, end: range.end }), res);
+    pipeWithErrorHandling(createReadStream(absPath, { start: range.start, end: range.end }), res);
     return;
   }
 
   res.setHeader("Content-Length", String(stat.size));
-  pipeWithErrorHandling(fs.createReadStream(absPath), res);
+  pipeWithErrorHandling(createReadStream(absPath), res);
 });
 
 // ── Reference directory roots ───────────────────────────────────