mulmoclaude 0.5.2 → 0.6.0

package/server/services/translation/index.ts

@@ -0,0 +1,106 @@
+// Translation service factory. Reads the on-disk cache, routes
+// only the missing sentences through an injected `translateBatch`,
+// merges new translations back, and returns the assembled result
+// in the caller's input order.
+//
+// The injection seam is deliberate: production wires
+// `defaultTranslateBatch` from `./llm.ts` (which spawns the
+// `claude` CLI), unit tests pass a deterministic fake.
+
+import { loadDictionary, saveDictionary } from "../../utils/files/translation-io.js";
+import { assembleResult, mergeTranslations, splitHitMiss } from "./cache.js";
+import type { TranslateRequest, TranslateResponse, TranslationService, TranslationServiceDeps } from "./types.js";
+
+const NAMESPACE_RE = /^[a-zA-Z0-9_-]+$/;
+// Fixed-length alternation, no nested quantifiers — safe from ReDoS.
+// eslint-disable-next-line security/detect-unsafe-regex -- single-pass match against a 2- or 5-char locale code, no backtracking.
+const LANGUAGE_RE = /^[a-z]{2}(?:-[A-Z]{2})?$/;
+
+// Bound the request shape so a single call cannot blow past the
+// `claude -p <json>` argv limit (POSIX `E2BIG`, typically ~128 KiB)
+// or balloon the per-call cost. UI-string callers stay well inside
+// these — Role suggested queries are ~5 strings × ~50 chars.
+const MAX_SENTENCES = 256;
+const MAX_SENTENCE_CHARS = 1024;
+const MAX_TOTAL_CHARS = 32 * 1024;
+
+export class TranslationInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TranslationInputError";
+  }
+}
+
+function validateRequest(req: TranslateRequest): void {
+  if (typeof req.namespace !== "string" || !NAMESPACE_RE.test(req.namespace)) {
+    throw new TranslationInputError(`invalid namespace: ${JSON.stringify(req.namespace)}`);
+  }
+  if (typeof req.targetLanguage !== "string" || !LANGUAGE_RE.test(req.targetLanguage)) {
+    throw new TranslationInputError(`invalid targetLanguage: ${JSON.stringify(req.targetLanguage)}`);
+  }
+  if (!Array.isArray(req.sentences) || req.sentences.length === 0) {
+    throw new TranslationInputError("sentences must be a non-empty array");
+  }
+  if (req.sentences.length > MAX_SENTENCES) {
+    throw new TranslationInputError(`sentences exceeds ${MAX_SENTENCES} entries`);
+  }
+  let totalChars = 0;
+  for (const sentence of req.sentences) {
+    if (typeof sentence !== "string" || sentence.length === 0) {
+      throw new TranslationInputError("sentences must contain non-empty strings");
+    }
+    if (sentence.length > MAX_SENTENCE_CHARS) {
+      throw new TranslationInputError(`sentence exceeds ${MAX_SENTENCE_CHARS} characters`);
+    }
+    totalChars += sentence.length;
+    if (totalChars > MAX_TOTAL_CHARS) {
+      throw new TranslationInputError(`total sentence length exceeds ${MAX_TOTAL_CHARS} characters`);
+    }
+  }
+}
+
+export function createTranslationService(deps: TranslationServiceDeps): TranslationService {
+  const { translateBatch, workspaceRoot } = deps;
+  // Per-namespace serialization chain. Two concurrent translate() calls
+  // on the same namespace would otherwise race the read-merge-write
+  // step; chaining ensures the second sees the first's persisted output.
+  const chains = new Map<string, Promise<unknown>>();
+
+  async function runOnce(req: TranslateRequest): Promise<TranslateResponse> {
+    const dict = loadDictionary(req.namespace, workspaceRoot);
+    const { cached, misses } = splitHitMiss(dict, req.sentences, req.targetLanguage);
+    if (misses.length === 0) {
+      return { translations: assembleResult(req.sentences, cached, new Map()) };
+    }
+    const translated = await translateBatch({ targetLanguage: req.targetLanguage, sentences: misses });
+    if (translated.length !== misses.length) {
+      throw new Error(`[translation] translateBatch returned ${translated.length} translations for ${misses.length} sentences`);
+    }
+    const fresh = new Map<string, string>();
+    misses.forEach((sentence, index) => fresh.set(sentence, translated[index]));
+    const next = mergeTranslations(dict, req.targetLanguage, fresh);
+    await saveDictionary(req.namespace, next, workspaceRoot);
+    return { translations: assembleResult(req.sentences, cached, fresh) };
+  }
+
+  function serialize<T>(namespace: string, runner: () => Promise<T>): Promise<T> {
+    const prev = chains.get(namespace) ?? Promise.resolve();
+    const next = prev.catch(() => undefined).then(runner);
+    const tracked = next.catch(() => undefined);
+    chains.set(namespace, tracked);
+    tracked.then(() => {
+      if (chains.get(namespace) === tracked) chains.delete(namespace);
+    });
+    return next;
+  }
+
+  async function translate(req: TranslateRequest): Promise<TranslateResponse> {
+    validateRequest(req);
+    if (req.targetLanguage === "en") {
+      return { translations: [...req.sentences] };
+    }
+    return serialize(req.namespace, () => runOnce(req));
+  }
+
+  return { translate };
+}

package/server/services/translation/llm.ts

@@ -0,0 +1,140 @@
+// Production `translateBatch`: spawns the `claude` CLI in print
+// mode with a JSON schema so the response array length is
+// guaranteed to match the request. Same auth model as the rest of
+// the server (no API key required).
+//
+// Patterned after `server/workspace/chat-index/summarizer.ts`.
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { tmpdir } from "node:os";
+import { CLI_SUBPROCESS_TIMEOUT_MS } from "../../utils/time.js";
+import { errorMessage } from "../../utils/errors.js";
+import { formatSpawnFailure } from "../../utils/spawn.js";
+import { isRecord } from "../../utils/types.js";
+import { ClaudeCliNotFoundError } from "../../workspace/journal/archivist-cli.js";
+import type { TranslateBatchFn } from "./types.js";
+
+const SYSTEM_PROMPT =
+  "You are a translation engine. The user input is a JSON object with `targetLanguage` (BCP-47) " +
+  "and `sentences` (an array of English source strings). Translate each sentence into the target " +
+  "language and return strict JSON matching the provided schema. The output `translations` array " +
+  "MUST have the same length and order as the input `sentences` array. Preserve placeholders " +
+  "such as `{name}`, `{count}`, `%s`, and HTML tags verbatim.";
+
+const SCHEMA = {
+  type: "object",
+  properties: {
+    translations: {
+      type: "array",
+      items: { type: "string" },
+    },
+  },
+  required: ["translations"],
+};
+
+// Small per-call cap. A few dozen short UI strings on haiku costs
+// fractions of a cent; this guards against runaway prompts only.
+const MAX_BUDGET_USD = 0.5;
+
+interface ClaudeJsonEnvelope {
+  is_error?: boolean;
+  result?: string;
+  structured_output?: unknown;
+}
+
+export function parseTranslations(stdout: string): string[] {
+  let parsed: ClaudeJsonEnvelope;
+  try {
+    parsed = JSON.parse(stdout.trim());
+  } catch (err) {
+    throw new Error(`[translation] failed to parse claude json output: ${errorMessage(err)}`);
+  }
+  if (parsed.is_error) {
+    throw new Error(`[translation] claude returned error: ${parsed.result ?? "unknown"}`);
+  }
+  if (!isRecord(parsed.structured_output)) {
+    throw new Error("[translation] structured_output missing or not an object");
+  }
+  const { translations } = parsed.structured_output as Record<string, unknown>;
+  if (!Array.isArray(translations) || !translations.every((value): value is string => typeof value === "string")) {
+    throw new Error("[translation] translations is not a string array");
+  }
+  return translations;
+}
+
+function buildArgs(promptInput: string): string[] {
+  return [
+    "--print",
+    "--no-session-persistence",
+    "--output-format",
+    "json",
+    "--model",
+    "haiku",
+    "--max-budget-usd",
+    String(MAX_BUDGET_USD),
+    "--json-schema",
+    JSON.stringify(SCHEMA),
+    "--system-prompt",
+    SYSTEM_PROMPT,
+    "-p",
+    promptInput,
+  ];
+}
+
+interface SpawnState {
+  stdout: string;
+  stderr: string;
+  settled: boolean;
+}
+
+type RejectFn = (err: Error) => void;
+type ResolveFn = (value: string) => void;
+
+function onTimeout(state: SpawnState, proc: ChildProcess, reject: RejectFn, timeoutMs: number): void {
+  if (state.settled) return;
+  state.settled = true;
+  proc.kill("SIGKILL");
+  reject(new Error(`[translation] claude translate timed out after ${timeoutMs}ms`));
+}
+
+function onError(state: SpawnState, timer: ReturnType<typeof setTimeout>, err: Error & { code?: string }, reject: RejectFn): void {
+  if (state.settled) return;
+  state.settled = true;
+  clearTimeout(timer);
+  reject(err.code === "ENOENT" ? new ClaudeCliNotFoundError() : err);
+}
+
+function onClose(state: SpawnState, timer: ReturnType<typeof setTimeout>, code: number | null, resolve: ResolveFn, reject: RejectFn): void {
+  if (state.settled) return;
+  state.settled = true;
+  clearTimeout(timer);
+  if (code !== 0) {
+    reject(new Error(formatSpawnFailure("[translation]", code, state.stdout, state.stderr)));
+    return;
+  }
+  resolve(state.stdout);
+}
+
+function spawnClaudeTranslate(promptInput: string, timeoutMs: number): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    // Run from tmpdir so claude does not load the project's
+    // CLAUDE.md / plugins / memory and inflate the context.
+    const proc = spawn("claude", buildArgs(promptInput), { cwd: tmpdir(), stdio: ["ignore", "pipe", "pipe"] });
+    const state: SpawnState = { stdout: "", stderr: "", settled: false };
+    const timer = setTimeout(() => onTimeout(state, proc, reject, timeoutMs), timeoutMs);
+    proc.stdout.on("data", (chunk: Buffer) => {
+      state.stdout += chunk.toString();
+    });
+    proc.stderr.on("data", (chunk: Buffer) => {
+      state.stderr += chunk.toString();
+    });
+    proc.on("error", (err: Error & { code?: string }) => onError(state, timer, err, reject));
+    proc.on("close", (code) => onClose(state, timer, code, resolve, reject));
+  });
+}
+
+export const defaultTranslateBatch: TranslateBatchFn = async ({ targetLanguage, sentences }) => {
+  const promptInput = JSON.stringify({ targetLanguage, sentences });
+  const stdout = await spawnClaudeTranslate(promptInput, CLI_SUBPROCESS_TIMEOUT_MS);
+  return parseTranslations(stdout);
+};

package/server/services/translation/types.ts

@@ -0,0 +1,35 @@
+// Public types for the translation service. The on-disk dictionary
+// shape is the authoritative cache format — see plans/done/feat-translation-service.md.
+
+export interface TranslateRequest {
+  /** Dictionary namespace; also the cache filename. */
+  readonly namespace: string;
+  /** BCP-47 short code, e.g. `ja`, `pt-BR`. */
+  readonly targetLanguage: string;
+  /** English source sentences in the order the caller wants them returned. */
+  readonly sentences: readonly string[];
+}
+
+export interface TranslateResponse {
+  readonly translations: readonly string[];
+}
+
+export interface DictionaryFile {
+  readonly sentences: Record<string, Record<string, string>>;
+}
+
+export interface TranslateBatchInput {
+  readonly targetLanguage: string;
+  readonly sentences: readonly string[];
+}
+
+export type TranslateBatchFn = (input: TranslateBatchInput) => Promise<string[]>;
+
+export interface TranslationServiceDeps {
+  readonly translateBatch: TranslateBatchFn;
+  readonly workspaceRoot?: string;
+}
+
+export interface TranslationService {
+  readonly translate: (req: TranslateRequest) => Promise<TranslateResponse>;
+}

package/server/system/credentials.ts

@@ -85,6 +85,17 @@ async function renewTokenViaPty(): Promise<boolean> {
     let responded = false;
     let buffer = "";
     let settled = false;
+    // Mutual reference: `finish`'s body needs `timeout` (clearTimeout)
+    // and `timeout`'s callback needs `finish`. Predeclared with `let`
+    // and assigned exactly once below. `prefer-const` would prefer a
+    // direct `const timeout = setTimeout(...)` form, but that needs
+    // `finish` already in scope inside the callback, which then
+    // forces `clearTimeout(timeout)` inside `finish`'s body to
+    // reference an undefined-at-textual-position const — i.e. the
+    // chicken-and-egg pair has no const-only spelling. The actual
+    // value is single-write at runtime; lint heuristic disagrees.
+    // eslint-disable-next-line prefer-const -- mutual-reference pair, see comment above
+    let timeout: ReturnType<typeof setTimeout>;
 
     const finish = (success: boolean) => {
       if (settled) return;
@@ -94,7 +105,7 @@ async function renewTokenViaPty(): Promise<boolean> {
       resolve(success);
     };
 
-    const timeout = setTimeout(() => {
+    timeout = setTimeout(() => {
       log.error("credentials", `Token renewal timed out after ${PTY_TIMEOUT_MS / ONE_SECOND_MS}s`);
       finish(false);
     }, PTY_TIMEOUT_MS);
@@ -210,7 +221,7 @@ export async function refreshCredentials(): Promise<boolean> {
 
     // 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 });
+    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

@@ -58,6 +58,12 @@ export const env = Object.freeze({
 
   // Sandbox / Docker
   disableSandbox: asFlag(process.env.DISABLE_SANDBOX),
+  // Debug aid: also persist `tool_call` events to the session
+  // jsonl (the `tool_result` side already lands on disk). Off by
+  // default because args can be large and may carry payload bytes
+  // the user didn't expect to land in this exact form. See
+  // plans/done/feat-persist-tool-calls.md / issue #1096.
+  persistToolCalls: asFlag(process.env.PERSIST_TOOL_CALLS),
   // Host-credential opt-ins for the Docker sandbox (#259). Both off
   // by default. See docs/sandbox-credentials.md for the contract.
   sandboxSshAgentForward: asFlag(process.env.SANDBOX_SSH_AGENT_FORWARD),
@@ -107,7 +113,6 @@ export const env = Object.freeze({
   mcpSessionId: process.env.SESSION_ID ?? "",
   mcpHost: process.env.MCP_HOST ?? "localhost",
   mcpPluginNames: asCsv(process.env.PLUGIN_NAMES),
-  mcpRoleIds: asCsv(process.env.ROLE_IDS),
 });
 
 // ── Derived helpers ─────────────────────────────────────────────────

package/server/system/logger/formatters.ts

@@ -1,4 +1,4 @@
-import type { Formatter, LogRecord } from "./types.js";
+import type { Formatter, LogLevel, LogRecord } from "./types.js";
 
 function formatData(data: Record<string, unknown> | undefined): string {
   if (!data) return "";
@@ -23,11 +23,53 @@ function stringifyScalar(value: unknown): string {
   }
 }
 
-export const formatText: Formatter = (record: LogRecord): string => {
-  const level = record.level.toUpperCase().padEnd(5);
-  return `${record.time} ${level} [${record.prefix}] ${record.message}${formatData(record.data)}`;
+// ANSI escape codes — small enough to inline rather than pull a dep.
+// `1m` adds bold so the level word reads at a glance even on busy
+// terminals. The level field stays width-padded with `.padEnd(5)` so
+// the colour escape doesn't push subsequent columns out of alignment.
+const ANSI_RESET = "\x1b[0m";
+const LEVEL_COLOR: Record<LogLevel, string> = {
+  error: "\x1b[1;31m", // bold red
+  warn: "\x1b[1;33m", // bold yellow
+  info: "\x1b[1;36m", // bold cyan
+  debug: "\x1b[2;37m", // dim white (close to gray)
 };
 
+// Levels for which the colour wraps the entire log line, not just the
+// level word. The intent is that a `tail -f` reader can spot warnings
+// and errors without parsing — the whole row glows red / yellow.
+// Info / debug stay quiet so a chatty server doesn't fill the terminal
+// with cyan or grey.
+const WHOLE_LINE_COLOR: ReadonlySet<LogLevel> = new Set(["error", "warn"]);
+
+export const formatText: Formatter = (record: LogRecord): string => formatTextLine(record, false);
+
+/**
+ * Same shape as {@link formatText} but wraps the output in ANSI colour
+ * escapes per level. Console sinks select this variant only when
+ * stdout/stderr is a real TTY (or `FORCE_COLOR` is set) and `NO_COLOR`
+ * is unset — file sinks and CI logs always get the plain
+ * {@link formatText}.
+ *
+ * - `error` / `warn`: the whole line is wrapped (bold red / bold yellow)
+ *   so the row stands out at a glance.
+ * - `info` / `debug`: only the level word is coloured, keeping the
+ *   chatty levels visually quiet.
+ */
+export const formatTextColor: Formatter = (record: LogRecord): string => formatTextLine(record, true);
+
+function formatTextLine(record: LogRecord, color: boolean): string {
+  const levelText = record.level.toUpperCase().padEnd(5);
+  const colorCode = LEVEL_COLOR[record.level];
+  if (color && WHOLE_LINE_COLOR.has(record.level)) {
+    // Whole-row wrap. Avoid double-wrapping the level slot — one
+    // colour code at the start + reset at the end is enough.
+    return `${colorCode}${record.time} ${levelText} [${record.prefix}] ${record.message}${formatData(record.data)}${ANSI_RESET}`;
+  }
+  const level = color ? `${colorCode}${levelText}${ANSI_RESET}` : levelText;
+  return `${record.time} ${level} [${record.prefix}] ${record.message}${formatData(record.data)}`;
+}
+
 export const formatJson: Formatter = (record: LogRecord): string => {
   const payload: Record<string, unknown> = {
     time: record.time,

package/server/system/logger/index.ts

@@ -9,10 +9,10 @@ export type { LoggerConfig } from "./config.js";
 export { resolveConfig, DEFAULT_CONFIG } from "./config.js";
 
 export interface Logger {
-  error(prefix: string, message: string, data?: Record<string, unknown>): void;
-  warn(prefix: string, message: string, data?: Record<string, unknown>): void;
-  info(prefix: string, message: string, data?: Record<string, unknown>): void;
-  debug(prefix: string, message: string, data?: Record<string, unknown>): void;
+  error: (prefix: string, message: string, data?: Record<string, unknown>) => void;
+  warn: (prefix: string, message: string, data?: Record<string, unknown>) => void;
+  info: (prefix: string, message: string, data?: Record<string, unknown>) => void;
+  debug: (prefix: string, message: string, data?: Record<string, unknown>) => void;
 }
 
 export function createLogger(config: LoggerConfig): Logger {

package/server/system/logger/sinks.ts

@@ -1,7 +1,7 @@
 import { appendFile } from "fs/promises";
 import path from "path";
 import type { ConsoleSinkConfig, FileSinkConfig, TelemetrySinkConfig } from "./config.js";
-import { formatJson, formatText } from "./formatters.js";
+import { formatJson, formatText, formatTextColor } from "./formatters.js";
 import { dailyFileName, enforceMaxFiles, ensureDir } from "./rotation.js";
 import type { Formatter, LogRecord, Sink } from "./types.js";
 
@@ -9,15 +9,36 @@ function pickFormatter(kind: "text" | "json"): Formatter {
   return kind === "json" ? formatJson : formatText;
 }
 
+// Decide whether to emit ANSI escapes on this stream:
+//   1. `NO_COLOR=<anything>` → off, always (https://no-color.org/).
+//   2. `FORCE_COLOR=<non-zero>` → on, even when the stream isn't a
+//      TTY. Concurrently / yarn / npm scripts set this on child
+//      processes by default, so `yarn dev` piped output keeps colour.
+//      `FORCE_COLOR=0` is treated as "explicitly off".
+//   3. Otherwise: on iff the stream itself is a real TTY.
+function colorEnabled(stream: { isTTY?: boolean }): boolean {
+  if (process.env.NO_COLOR && process.env.NO_COLOR.length > 0) return false;
+  const force = process.env.FORCE_COLOR;
+  if (force !== undefined && force !== "" && force !== "0" && force !== "false") return true;
+  if (force === "0" || force === "false") return false;
+  return stream.isTTY === true;
+}
+
 export function createConsoleSink(config: ConsoleSinkConfig): Sink {
-  const fmt = pickFormatter(config.format);
+  // Pre-resolve a (plain, colour) pair once. `text` may upgrade to the
+  // ANSI variant per record based on which stream the record will hit;
+  // `json` stays uncoloured so structured-log consumers get a clean
+  // stream regardless of the terminal.
+  const plain = pickFormatter(config.format);
+  const colored: Formatter = config.format === "text" ? formatTextColor : plain;
+
   return {
     name: "console",
     level: config.level,
     write(record: LogRecord) {
-      const line = fmt(record) + "\n";
       const stream = record.level === "error" || record.level === "warn" ? process.stderr : process.stdout;
-      stream.write(line);
+      const fmt = colorEnabled(stream) ? colored : plain;
+      stream.write(`${fmt(record)}\n`);
     },
   };
 }
@@ -72,7 +93,7 @@ export function createFileSink(config: FileSinkConfig, deps: FileSinkDeps = {}):
     write(record: LogRecord) {
       const nowDate = now();
       const rotated = maybeRotate(nowDate);
-      const line = fmt(record) + "\n";
+      const line = `${fmt(record)}\n`;
       const filePath = currentPath;
       enqueue(() => writeLine(filePath, line));
       // Enforce retention AFTER the write so maxFiles counts include

package/server/system/logger/types.ts

@@ -21,9 +21,9 @@ export interface LogRecord {
 export interface Sink {
   name: string;
   level: LogLevel;
-  write(record: LogRecord): void;
+  write: (record: LogRecord) => void;
   // Drains any pending async I/O. Tests call this; production can ignore.
-  flush?(): Promise<void>;
+  flush?: () => Promise<void>;
 }
 
 export type Formatter = (record: LogRecord) => string;

package/server/utils/dev-plugin-args.d.mts

@@ -0,0 +1,11 @@
+// Type declarations for dev-plugin-args.mjs. See the .mjs file for
+// rationale on why the shared helper lives in plain JS.
+
+export interface DevPluginArg {
+  rawInput: string;
+  absPath: string;
+}
+
+export type ParseDevPluginArgsResult = { ok: true; resolved: DevPluginArg[] } | { ok: false; reason: string };
+
+export function parseDevPluginArgs(argv: readonly string[], cwd: string): ParseDevPluginArgsResult;

package/server/utils/dev-plugin-args.mjs

@@ -0,0 +1,43 @@
+// Shared `--dev-plugin` argv parser for the npm launcher
+// (`packages/mulmoclaude/bin/mulmoclaude.js`) and any other Node entry
+// point that needs to interpret the same flags.
+//
+// Kept as plain `.mjs` for the same reason as `port.mjs`: the launcher
+// runs BEFORE tsx is wired up, so it can't import from a `.ts` file.
+// Sibling `dev-plugin-args.d.mts` carries the type declarations.
+//
+// The parser is pure — no `process.cwd()`, no `console.*`, no
+// `process.exit()`. The caller passes argv + cwd in, and decides what
+// to log and when to exit. That keeps it unit-testable from
+// node:test without spawning subprocesses.
+
+import path from "node:path";
+
+/** Parse repeated `--dev-plugin <path>` flags out of argv.
+ *
+ *  Returns one of:
+ *    { ok: true, resolved: [{ rawInput, absPath }] }
+ *    { ok: false, reason }
+ *
+ *  Errors are surfaced as a single human-readable string so the caller
+ *  can write it to stderr. The launcher's invariants are:
+ *    - missing argument value (`--dev-plugin` at end of argv, or
+ *      followed by another `-`-prefixed flag) → reject
+ *    - relative paths resolve against `cwd`
+ *    - duplicate flags are accumulated in argv order; the caller
+ *      detects same-name collisions later, against the resolved package
+ *      names from disk.
+ */
+export function parseDevPluginArgs(argv, cwd) {
+  const resolved = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] !== "--dev-plugin") continue;
+    const raw = argv[i + 1];
+    if (raw === undefined || raw.startsWith("-")) {
+      return { ok: false, reason: "--dev-plugin requires a path argument" };
+    }
+    resolved.push({ rawInput: raw, absPath: path.resolve(cwd, raw) });
+    i++;
+  }
+  return { ok: true, resolved };
+}

package/server/utils/errors.ts

@@ -2,15 +2,24 @@
 // `err instanceof Error ? err.message : String(err)` — searching for
 // one canonical helper is easier than grepping for the inline form.
 //
+// Non-Error objects with a `details` (gRPC convention) or `message`
+// string field have that field surfaced — without this, gRPC errors
+// like `{ code, details, metadata }` show up to users as
+// `[object Object]`.
+//
 // The optional `fallback` covers the common route-handler idiom where
 // a throw of a plain non-Error value should surface as a descriptive
-// message ("rebuild failed") rather than `String(err)` noise like
-// `[object Object]`. Prefer passing a fallback at error-response
-// boundaries — omit it for logging contexts where `String(err)` is
-// fine.
+// message ("rebuild failed") rather than `String(err)` noise. Prefer
+// passing a fallback at error-response boundaries — omit it for
+// logging contexts where `String(err)` is fine.
 
 export function errorMessage(err: unknown, fallback?: string): string {
   if (err instanceof Error) return err.message;
+  if (err !== null && typeof err === "object") {
+    const obj = err as { details?: unknown; message?: unknown };
+    if (typeof obj.details === "string" && obj.details) return obj.details;
+    if (typeof obj.message === "string" && obj.message) return obj.message;
+  }
   if (fallback !== undefined) return fallback;
   return String(err);
 }