mulmoclaude 0.5.2 → 0.6.0

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

@@ -1,12 +1,6 @@
-// Domain I/O: custom roles
-//   config/roles/<id>.json
-//
-// Optional `root` for test DI.
-
 import path from "node:path";
 import { mkdirSync, statSync, unlinkSync } from "node:fs";
-import { WORKSPACE_DIRS } from "../../workspace/paths.js";
-import { workspacePath } from "../../workspace/paths.js";
+import { WORKSPACE_DIRS, workspacePath } from "../../workspace/paths.js";
 import { writeFileAtomicSync } from "./atomic.js";
 import { isEnoent } from "./safe.js";
 
@@ -16,7 +10,6 @@ function roleFilePath(roleId: string, workspaceRoot?: string): string {
   return path.join(root(workspaceRoot), WORKSPACE_DIRS.roles, `${roleId}.json`);
 }
 
-/** Check if a custom role file exists. */
 export function roleExists(roleId: string, workspaceRoot?: string): boolean {
   try {
     statSync(roleFilePath(roleId, workspaceRoot));
@@ -26,7 +19,7 @@ export function roleExists(roleId: string, workspaceRoot?: string): boolean {
   }
 }
 
-/** Delete a custom role file. Returns false if not found. */
+// Returns false if not found.
 export function deleteRole(roleId: string, workspaceRoot?: string): boolean {
   try {
     unlinkSync(roleFilePath(roleId, workspaceRoot));
@@ -37,7 +30,6 @@ export function deleteRole(roleId: string, workspaceRoot?: string): boolean {
   }
 }
 
-/** Save (create or overwrite) a custom role file atomically. */
 export function saveRole(roleId: string, data: unknown, workspaceRoot?: string): void {
   const dir = path.join(root(workspaceRoot), WORKSPACE_DIRS.roles);
   mkdirSync(dir, { recursive: true });

package/server/utils/files/safe.ts

@@ -1,22 +1,14 @@
-// Safe filesystem wrappers that swallow ENOENT / EACCES so callers
-// can do `if (result === null)` instead of try/catch boilerplate.
-//
-// `resolveWithinRoot` is the realpath-based path-traversal check
-// that underpins every endpoint serving files out of the workspace.
-//
-// Moved from server/utils/fs.ts (issue #366 Phase 1). The old
-// file re-exports these for backwards compat.
+// Wrappers that swallow ENOENT/EACCES so callers branch on `result === null` instead of try/catch.
+// resolveWithinRoot is the realpath-based traversal check used by every endpoint serving workspace files.
 
 import { Dirent, Stats, promises, readFileSync, readdirSync, realpathSync, statSync } from "fs";
 import path from "path";
 import { isErrorWithCode } from "../types.js";
 
-/** Check if an error is ENOENT (file/dir not found). */
 export function isEnoent(err: unknown): boolean {
   return isErrorWithCode(err) && err.code === "ENOENT";
 }
 
-/** Read a binary file by absolute path. Null on ENOENT. */
 export function readBinarySafeSync(absPath: string): Buffer | null {
   try {
     return readFileSync(absPath);
@@ -25,7 +17,6 @@ export function readBinarySafeSync(absPath: string): Buffer | null {
   }
 }
 
-/** Read a text file by absolute path (async). Null on ENOENT. */
 export async function readTextSafe(absPath: string): Promise<string | null> {
   try {
     return await promises.readFile(absPath, "utf-8");
@@ -34,7 +25,6 @@ export async function readTextSafe(absPath: string): Promise<string | null> {
   }
 }
 
-/** Read a text file by absolute path (sync). Null on ENOENT. */
 export function readTextSafeSync(absPath: string): string | null {
   try {
     return readFileSync(absPath, "utf-8");
@@ -83,13 +73,21 @@ export async function readTextOrNull(file: string): Promise<string | null> {
   }
 }
 
-/**
- * Resolve a relative path against a root, ensuring the result stays
- * inside the root after symlink resolution. Returns null on traversal
- * or if either path doesn't exist on disk.
- *
- * `rootReal` MUST already be a realpath.
- */
+// True if any segment of `relPath` (split on either `/` or `\`)
+// starts with a dot — the same policy `express.static({ dotfiles:
+// "deny" })` applies. Splits on both separators because
+// `decodeURIComponent` of `%5C` produces a literal `\`, and on
+// Windows `path.normalize` (used downstream by `resolveWithinRoot`)
+// treats `\` as a separator. Without the dual split, a request like
+// `/dir%5C.hidden.html` decodes to `dir\.hidden.html` → splits on
+// `/` as one segment `dir\.hidden.html` (no leading dot) → bypasses
+// the guard on Windows even though `path.normalize` later resolves
+// it to `dir/.hidden.html`. (Codex review on PR #1082.)
+export function containsDotfileSegment(relPath: string): boolean {
+  return relPath.split(/[/\\]/).some((segment) => segment.startsWith("."));
+}
+
+// `rootReal` MUST already be a realpath. Returns null on traversal or if either path doesn't exist on disk.
 export function resolveWithinRoot(rootReal: string, relPath: string): string | null {
   const normalized = path.normalize(relPath || "");
   const resolved = path.resolve(rootReal, normalized);

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

@@ -1,10 +1,4 @@
-// Domain I/O: scheduler items
-//   data/scheduler/items.json
-//
-// Sync API. Optional `root` for test DI.
-
-import { WORKSPACE_FILES } from "../../workspace/paths.js";
-import { workspacePath } from "../../workspace/paths.js";
+import { WORKSPACE_FILES, workspacePath } from "../../workspace/paths.js";
 import { resolvePath } from "./workspace-io.js";
 import { loadJsonFile } from "./json.js";
 import { writeFileAtomicSync } from "./atomic.js";

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

@@ -1,9 +1,3 @@
-// Domain I/O for scheduler override config.
-//
-// Reads/writes config/scheduler/overrides.json. Each key is a
-// system task ID (e.g. "system:journal"), value overrides the
-// default schedule.
-
 import { mkdirSync } from "fs";
 import path from "path";
 import { workspacePath } from "../../workspace/paths.js";
@@ -14,15 +8,14 @@ import { log } from "../../system/logger/index.js";
 import { isRecord } from "../types.js";
 
 export interface ScheduleOverride {
-  /** Override interval in milliseconds (for interval-type schedules). */
   intervalMs?: number;
-  /** Override time "HH:MM" in UTC (for daily-type schedules). */
+  // "HH:MM" in UTC for daily schedules.
   time?: string;
 }
 
 export type ScheduleOverrides = Record<string, ScheduleOverride>;
 
-/** Strict HH:MM validation — rejects 99:99 etc. */
+// Strict HH:MM — rejects 99:99 etc.
 export const UTC_HH_MM_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
 
 function isScheduleOverride(value: unknown): value is ScheduleOverride {
@@ -30,7 +23,6 @@ function isScheduleOverride(value: unknown): value is ScheduleOverride {
   const obj = value;
   const hasInterval = "intervalMs" in obj && typeof obj.intervalMs === "number" && obj.intervalMs > 0;
   const hasTime = "time" in obj && typeof obj.time === "string" && UTC_HH_MM_RE.test(obj.time);
-  // At least one valid field required
   return hasInterval || hasTime;
 }
 
@@ -38,7 +30,7 @@ function overridesPath(root?: string): string {
   return path.join(root ?? workspacePath, WORKSPACE_FILES.schedulerOverrides);
 }
 
-/** Load schedule overrides. Filters out invalid entries with a warning. */
+// Filters out invalid entries with a warning.
 export function loadSchedulerOverrides(root?: string): ScheduleOverrides {
   const raw = loadJsonFile<unknown>(overridesPath(root), {});
   if (!isRecord(raw)) {
@@ -56,7 +48,6 @@ export function loadSchedulerOverrides(root?: string): ScheduleOverrides {
   return result;
 }
 
-/** Save schedule overrides atomically. Creates directory if needed. */
 export function saveSchedulerOverrides(overrides: ScheduleOverrides, root?: string): void {
   const filePath = overridesPath(root);
   mkdirSync(path.dirname(filePath), { recursive: true });

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

@@ -1,19 +1,12 @@
-// Domain I/O: chat sessions
-//   conversations/chat/<id>.json   — metadata
-//   conversations/chat/<id>.jsonl  — event log
-//
-// All functions take optional `root` for test DI.
-
-import { appendFile } from "fs/promises";
+import { appendFile, rm } from "fs/promises";
 import path from "node:path";
-import { WORKSPACE_DIRS } from "../../workspace/paths.js";
-import { workspacePath } from "../../workspace/paths.js";
+import { WORKSPACE_DIRS, workspacePath } from "../../workspace/paths.js";
 import { readTextUnder, writeTextUnder, resolvePath, ensureWorkspaceDir } from "./workspace-io.js";
+import type { SessionOrigin } from "../../../src/types/session.js";
 
 const CHAT = WORKSPACE_DIRS.chat;
 const root = (rootOverride?: string) => rootOverride ?? workspacePath;
 
-/** Ensure the chat directory exists. Called once at session start. */
 export function ensureChatDir(): void {
   ensureWorkspaceDir(CHAT);
 }
@@ -26,21 +19,19 @@ function jsonlRel(sessionId: string): string {
   return path.posix.join(CHAT, `${sessionId}.jsonl`);
 }
 
-// ── Meta ────────────────────────────────────────────────────────
-
 export interface SessionMeta {
   roleId?: string;
   startedAt?: string;
   firstUserMessage?: string;
   claudeSessionId?: string;
   hasUnread?: boolean;
-  origin?: "human" | "scheduler" | "skill" | "bridge";
+  isBookmarked?: boolean;
+  origin?: SessionOrigin;
   [key: string]: unknown;
 }
 
 export type ReadMetaResult = { kind: "missing" } | { kind: "ok"; meta: SessionMeta } | { kind: "corrupt"; raw: string };
 
-/** Read session metadata with full outcome discrimination. */
 export async function readSessionMetaFull(sessionId: string, rootOverride?: string): Promise<ReadMetaResult> {
   const raw = await readTextUnder(root(rootOverride), metaRel(sessionId));
   if (raw === null) return { kind: "missing" };
@@ -51,8 +42,7 @@ export async function readSessionMetaFull(sessionId: string, rootOverride?: stri
   }
 }
 
-/** Convenience: returns the meta or null. Treats corrupt as null
- *  (callers that need to distinguish use readSessionMetaFull). */
+// Treats corrupt as null — callers that need to distinguish use readSessionMetaFull.
 export async function readSessionMeta(sessionId: string, rootOverride?: string): Promise<SessionMeta | null> {
   const result = await readSessionMetaFull(sessionId, rootOverride);
   return result.kind === "ok" ? result.meta : null;
@@ -103,18 +93,25 @@ export async function updateHasUnread(sessionId: string, hasUnread: boolean, roo
   await writeSessionMeta(sessionId, { ...meta, hasUnread }, rootOverride);
 }
 
-// ── Jsonl ───────────────────────────────────────────────────────
+export async function updateIsBookmarked(sessionId: string, isBookmarked: boolean, rootOverride?: string): Promise<void> {
+  const meta = await readSessionMeta(sessionId, rootOverride);
+  if (!meta) return;
+  await writeSessionMeta(sessionId, { ...meta, isBookmarked }, rootOverride);
+}
+
+// Hard-deletes the session's .jsonl event log and .json meta sidecar.
+// Missing files are tolerated — callers may invoke this for sessions
+// whose meta or jsonl was never written (e.g. a crash mid-create).
+export async function deleteSessionFiles(sessionId: string, rootOverride?: string): Promise<void> {
+  await rm(sessionJsonlAbsPath(sessionId, rootOverride), { force: true });
+  await rm(sessionMetaAbsPath(sessionId, rootOverride), { force: true });
+}
 
 export function sessionJsonlAbsPath(sessionId: string, rootOverride?: string): string {
   return resolvePath(root(rootOverride), jsonlRel(sessionId));
 }
 
-/**
- * Resolve the absolute path of a session's metadata JSON file. The
- * jsonl variant is the event log; this one is the sidecar that holds
- * `hasUnread`, `roleId`, `startedAt`, `origin`, etc. Its mtime bumps
- * whenever any of those fields change via `writeSessionMeta`.
- */
+// .json sidecar to the event-log jsonl. mtime bumps on every writeSessionMeta — used as a "session changed" signal.
 export function sessionMetaAbsPath(sessionId: string, rootOverride?: string): string {
   return resolvePath(root(rootOverride), metaRel(sessionId));
 }
@@ -123,13 +120,7 @@ export async function readSessionJsonl(sessionId: string, rootOverride?: string)
   return readTextUnder(root(rootOverride), jsonlRel(sessionId));
 }
 
-/**
- * Append a single line to the session event log (JSONL format).
- *
- * The function **ensures a trailing `\n`** — callers pass the raw
- * content and don't need to worry about line termination. This
- * prevents JSONL parse failures from missing newlines.
- */
+// Always ends with `\n` to prevent JSONL parse failures from a missing terminator.
 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(sessionId)), normalized);

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

@@ -1,15 +1,14 @@
-import { mkdir, realpath, writeFile } from "fs/promises";
+import { mkdir, realpath } from "fs/promises";
 import path from "path";
 import { WORKSPACE_DIRS, WORKSPACE_PATHS } from "../../workspace/paths.js";
 import { shortId } from "../id.js";
+import { writeFileAtomic } from "./atomic.js";
 import { yearMonthUtc } from "./naming.js";
 import { resolveWithinRoot } from "./safe.js";
 
 const SPREADSHEETS_DIR = WORKSPACE_PATHS.spreadsheets;
 
-// Cached realpath of the spreadsheets directory. resolveWithinRoot
-// requires its root argument to be a realpath so symlinks are handled
-// correctly. Matches the pattern used in image-store.ts.
+// resolveWithinRoot needs a realpath as its root so symlinks resolve correctly (same pattern as image-store).
 let spreadsheetsDirReal: string | null = null;
 
 async function ensureSpreadsheetsDir(): Promise<string> {
@@ -19,13 +18,9 @@ async function ensureSpreadsheetsDir(): Promise<string> {
   return spreadsheetsDirReal;
 }
 
-// Resolve a workspace-relative spreadsheet path (e.g. "spreadsheets/abc.json")
-// into an absolute path guaranteed to be inside the spreadsheets directory.
-// Throws on traversal attempts.
+// Throws on traversal. Strips a leading "spreadsheets/" so callers can pass either the stored form or bare filename.
 async function safeResolve(relativePath: string): Promise<string> {
   const root = await ensureSpreadsheetsDir();
-  // Strip the leading "spreadsheets/" prefix so callers can pass either
-  // the stored form or just the filename.
   const name = relativePath.replace(new RegExp(`^${WORKSPACE_DIRS.spreadsheets}/`), "");
   const result = resolveWithinRoot(root, name);
   if (!result) {
@@ -34,33 +29,25 @@ async function safeResolve(relativePath: string): Promise<string> {
   return result;
 }
 
-/** Save sheets array as a JSON file. New files land under
- *  `spreadsheets/YYYY/MM/` (UTC) so the dir doesn't accumulate
- *  unbounded — see #764. Returns the workspace-relative path. */
+// #764 sharded under spreadsheets/YYYY/MM/ (UTC) so the dir doesn't grow unbounded; #881 atomic.
 export async function saveSpreadsheet(sheets: unknown[]): Promise<string> {
   await ensureSpreadsheetsDir();
   const partition = yearMonthUtc();
-  const parentAbs = path.join(SPREADSHEETS_DIR, partition);
-  await mkdir(parentAbs, { recursive: true });
   const filename = `${shortId()}.json`;
-  await writeFile(path.join(parentAbs, filename), JSON.stringify(sheets), "utf-8");
+  const absPath = path.join(SPREADSHEETS_DIR, partition, filename);
+  await writeFileAtomic(absPath, JSON.stringify(sheets));
   return path.posix.join(WORKSPACE_DIRS.spreadsheets, partition, filename);
 }
 
-/** Overwrite an existing spreadsheet file. */
 export async function overwriteSpreadsheet(relativePath: string, sheets: unknown[]): Promise<void> {
   const absPath = await safeResolve(relativePath);
-  await writeFile(absPath, JSON.stringify(sheets), "utf-8");
+  await writeFileAtomic(absPath, JSON.stringify(sheets));
 }
 
-/** Check if a string is a spreadsheet file path (not inline data).
- *  Rejects traversal attempts like "spreadsheets/../outside.json"
- *  so the caller can't rely on the prefix/suffix alone. */
+// Reject "spreadsheets/../outside.json" early; realpath check still runs server-side, but catch obvious cases here.
 export function isSpreadsheetPath(value: string): boolean {
   if (!value.startsWith(`${WORKSPACE_DIRS.spreadsheets}/`)) return false;
   if (!value.endsWith(".json")) return false;
-  // Forbid .. segments anywhere in the path — a realpath check still
-  // happens server-side, but this catches obvious cases early.
   const normalized = path.posix.normalize(value);
   if (normalized !== value) return false;
   if (normalized.includes("..")) return false;

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

@@ -0,0 +1,46 @@
+// Domain file I/O for the translation cache. One JSON file per
+// namespace under `data/translation/`. All writes go through the
+// atomic helper per project rule.
+
+import path from "node:path";
+import { WORKSPACE_DIRS, workspacePath } from "../../workspace/paths.js";
+import { loadJsonFile, writeJsonAtomic } from "./json.js";
+import { emptyDictionary } from "../../services/translation/cache.js";
+import type { DictionaryFile } from "../../services/translation/types.js";
+
+function root(workspaceRoot?: string): string {
+  return workspaceRoot ?? workspacePath;
+}
+
+export function dictionaryPath(namespace: string, workspaceRoot?: string): string {
+  return path.join(root(workspaceRoot), WORKSPACE_DIRS.translation, `${namespace}.json`);
+}
+
+// Cache files live under the user's workspace and can be hand-edited
+// or corrupted; treat the disk shape as untrusted and fall back to
+// an empty dictionary on anything we can't recognize. Without this
+// guard a `{}` or `{ sentences: null }` file would crash later at
+// `dict.sentences[sentence]` and turn every request for the namespace
+// into a 500 until the file was repaired.
+function isValidDictionary(value: unknown): value is DictionaryFile {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const { sentences } = value as { sentences?: unknown };
+  if (typeof sentences !== "object" || sentences === null || Array.isArray(sentences)) return false;
+  for (const inner of Object.values(sentences)) {
+    if (typeof inner !== "object" || inner === null || Array.isArray(inner)) return false;
+    for (const translated of Object.values(inner as Record<string, unknown>)) {
+      if (typeof translated !== "string") return false;
+    }
+  }
+  return true;
+}
+
+export function loadDictionary(namespace: string, workspaceRoot?: string): DictionaryFile {
+  const raw = loadJsonFile<unknown>(dictionaryPath(namespace, workspaceRoot), null);
+  if (!isValidDictionary(raw)) return emptyDictionary();
+  return raw;
+}
+
+export async function saveDictionary(namespace: string, dict: DictionaryFile, workspaceRoot?: string): Promise<void> {
+  await writeJsonAtomic(dictionaryPath(namespace, workspaceRoot), dict);
+}

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

@@ -1,12 +1,6 @@
-// Domain I/O: user-created scheduled tasks
-//   config/scheduler/tasks.json
-//
-// Optional `root` parameter for test DI (defaults to workspacePath).
-
 import path from "path";
 import { mkdir } from "fs/promises";
-import { WORKSPACE_FILES } from "../../workspace/paths.js";
-import { workspacePath } from "../../workspace/paths.js";
+import { WORKSPACE_FILES, workspacePath } from "../../workspace/paths.js";
 import { resolvePath } from "./workspace-io.js";
 import { loadJsonFile } from "./json.js";
 import { writeFileAtomic } from "./atomic.js";

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

@@ -1,15 +1,5 @@
-// Workspace-aware file I/O — the single place implementation code
-// should reach for when reading/writing files under ~/mulmoclaude/.
-//
-// Combines WORKSPACE_PATHS (path resolution) with the atomic/safe
-// helpers (I/O primitives) so call sites never need raw `path.join`
-// + raw `fs.*` for workspace files.
-//
-// All writes go through writeFileAtomic so concurrent readers always
-// see a consistent file — never a half-written one.
-//
-// All reads swallow ENOENT and return null / fallback so callers can
-// do `if (!content)` instead of try/catch.
+// All writes go through writeFileAtomic so concurrent readers never see a half-written file. All reads swallow ENOENT
+// and return null/fallback so callers can branch on `!content` instead of try/catch.
 
 import { Stats, mkdirSync, promises, readFileSync, readdirSync, statSync } from "fs";
 import path from "path";
@@ -24,24 +14,10 @@ function rethrowUnexpected(err: unknown, context: string): null {
   throw err;
 }
 
-// ── Path resolution ─────────────────────────────────────────────
-
-/**
- * Resolve a workspace-relative path to an absolute path.
- * Use this instead of `path.join(workspacePath, rel)` in
- * implementation code — keeps the workspace root reference in
- * one place.
- */
 export function resolveWorkspacePath(relPath: string): string {
   return path.join(workspacePath, relPath);
 }
 
-// ── Read ────────────────────────────────────────────────────────
-
-/**
- * Read a text file under the workspace. Returns null on ENOENT;
- * logs and re-throws unexpected errors (EACCES, EPERM, etc.).
- */
 export async function readWorkspaceText(relPath: string): Promise<string | null> {
   try {
     return await promises.readFile(resolveWorkspacePath(relPath), "utf-8");
@@ -50,7 +26,6 @@ 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 readFileSync(resolveWorkspacePath(relPath), "utf-8");
@@ -59,10 +34,6 @@ export function readWorkspaceTextSync(relPath: string): string | null {
   }
 }
 
-/**
- * Read and parse a JSON file under the workspace. Returns
- * `fallback` if the file is missing, unreadable, or malformed.
- */
 export async function readWorkspaceJson<T>(relPath: string, fallback: T): Promise<T> {
   const text = await readWorkspaceText(relPath);
   if (text === null) return fallback;
@@ -73,7 +44,6 @@ export async function readWorkspaceJson<T>(relPath: string, fallback: T): Promis
   }
 }
 
-/** Sync variant of `readWorkspaceJson`. */
 export function readWorkspaceJsonSync<T>(relPath: string, fallback: T): T {
   const text = readWorkspaceTextSync(relPath);
   if (text === null) return fallback;
@@ -84,53 +54,23 @@ export function readWorkspaceJsonSync<T>(relPath: string, fallback: T): T {
   }
 }
 
-// ── Write ───────────────────────────────────────────────────────
-
-/**
- * Write a text file under the workspace atomically.
- * Parent directories are created if missing.
- */
 export async function writeWorkspaceText(relPath: string, content: string, opts?: { mode?: number }): Promise<void> {
   await writeFileAtomic(resolveWorkspacePath(relPath), content, opts);
 }
 
-/** Sync variant for startup / init paths. */
 export function writeWorkspaceTextSync(relPath: string, content: string, opts?: { mode?: number }): void {
   writeFileAtomicSync(resolveWorkspacePath(relPath), content, opts);
 }
 
-/**
- * Write a JSON value under the workspace atomically.
- * Pretty-printed with 2-space indent.
- */
 export async function writeWorkspaceJson(relPath: string, data: unknown, opts?: { mode?: number }): Promise<void> {
   await writeFileAtomic(resolveWorkspacePath(relPath), JSON.stringify(data, null, 2), opts);
 }
 
-// ── Rooted variants (for DI / testable modules) ────────────────
-//
-// Modules that take `root` as a parameter (journal, sources, etc.)
-// use these instead of raw path.join + fs.*. Same contract as the
-// workspace-* helpers, but root is caller-supplied.
-//
-// **IMPORTANT — internal paths only.** These helpers do NOT guard
-// against `..` traversal. They are designed for domain I/O modules
-// that pass compile-time-fixed relative paths like
-// `${WORKSPACE_DIRS.chat}/${id}.json`. User-supplied or HTTP-body
-// paths MUST go through `resolveWithinRoot()` in `safe.ts` instead.
-
-/**
- * Resolve root + relPath. Replaces raw `path.join(root, rel)`.
- *
- * For **internal fixed paths only** — never pass user input as
- * `relPath`. Use `resolveWithinRoot()` for user-supplied paths.
- */
+// **Internal fixed paths only.** No `..` traversal guard — user-supplied paths MUST go through resolveWithinRoot() in safe.ts.
 export function resolvePath(root: string, relPath: string): string {
   return path.join(root, relPath);
 }
 
-/** Read text under an arbitrary root. Null on ENOENT; rethrows
- *  unexpected errors. */
 export async function readTextUnder(root: string, relPath: string): Promise<string | null> {
   try {
     return await promises.readFile(path.join(root, relPath), "utf-8");
@@ -139,12 +79,10 @@ export async function readTextUnder(root: string, relPath: string): Promise<stri
   }
 }
 
-/** Write atomically under an arbitrary root. */
 export async function writeTextUnder(root: string, relPath: string, content: string): Promise<void> {
   await writeFileAtomic(path.join(root, relPath), content);
 }
 
-/** Sync read text under a root. Null on ENOENT. */
 export function readTextUnderSync(root: string, relPath: string): string | null {
   try {
     return readFileSync(path.join(root, relPath), "utf-8");
@@ -153,7 +91,6 @@ 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 readdirSync(path.join(root, relPath));
@@ -166,7 +103,6 @@ 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 promises.readdir(path.join(root, relPath));
@@ -179,7 +115,6 @@ 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<Stats | null> {
   try {
     return await promises.stat(path.join(root, relPath));
@@ -188,17 +123,10 @@ export async function statUnder(root: string, relPath: string): Promise<Stats |
   }
 }
 
-/** Ensure a directory exists under a root. */
 export async function ensureDirUnder(root: string, relPath: string): Promise<void> {
   await promises.mkdir(path.join(root, relPath), { recursive: true });
 }
 
-// ── Existence ───────────────────────────────────────────────────
-
-/**
- * Check whether a workspace-relative path exists on disk.
- * Returns false on ENOENT; rethrows unexpected errors.
- */
 export function existsInWorkspace(relPath: string): boolean {
   try {
     statSync(resolveWorkspacePath(relPath));
@@ -212,10 +140,6 @@ export function existsInWorkspace(relPath: string): boolean {
   }
 }
 
-/**
- * Ensure a workspace-relative directory exists. Creates it
- * (including parents) if missing. Idempotent.
- */
 export function ensureWorkspaceDir(relPath: string): void {
   mkdirSync(resolveWorkspacePath(relPath), { recursive: true });
 }