mulmoclaude 0.6.2 → 0.6.4

package/server/system/appVersion.ts

@@ -0,0 +1,34 @@
+// The running app's version, read once from the nearest package.json.
+//
+// Layout is the same shape in both modes, so `../../package.json`
+// relative to this file resolves correctly without a workspace walk:
+//   - dev (`yarn dev`):  <repo>/server/system/appVersion.ts        → <repo>/package.json
+//   - tarball (`npx`):   <pkgDir>/server/system/appVersion.ts      → <pkgDir>/package.json
+// The launcher keeps `packages/mulmoclaude/package.json` in lockstep
+// with the root version at publish time, so either resolution yields
+// the same user-facing app version.
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { errorMessage } from "../utils/errors.js";
+import { log } from "./logger/index.js";
+
+function readAppVersion(): string {
+  const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(pkgPath, "utf8"));
+    if (typeof parsed === "object" && parsed !== null && "version" in parsed) {
+      const { version } = parsed as { version: unknown };
+      if (typeof version === "string" && version.length > 0) return version;
+    }
+    log.warn("appVersion", "package.json has no usable version field", { pkgPath });
+  } catch (err) {
+    log.warn("appVersion", "failed to read package.json", { pkgPath, error: errorMessage(err) });
+  }
+  return "unknown";
+}
+
+/** Frozen at module load — package.json never changes mid-process. */
+export const APP_VERSION: string = readAppVersion();

package/server/system/config.ts

@@ -229,6 +229,14 @@ export interface McpStdioSpec {
   args?: string[];
   env?: Record<string, string>;
   enabled?: boolean;
+  /** Opt-in (#1421 Phase B): when true AND the agent runs in Docker
+   *  sandbox mode, this stdio server is NOT dropped — instead it is
+   *  spawned on the HOST behind a stdio↔HTTP gateway and the
+   *  sandboxed agent reaches it over `host.docker.internal`. This
+   *  DELIBERATELY escapes the sandbox for this one server; the
+   *  Settings UI requires an explicit risk acknowledgment to set
+   *  it. Unset / false → default behavior (dropped + warned). */
+  hostExecInDocker?: boolean;
 }
 
 export type McpServerSpec = McpHttpSpec | McpStdioSpec;
@@ -283,6 +291,7 @@ export function isMcpStdioSpec(value: unknown): value is McpStdioSpec {
   if (value.args !== undefined && !isStringArray(value.args)) return false;
   if (value.env !== undefined && !isStringRecord(value.env)) return false;
   if (value.enabled !== undefined && typeof value.enabled !== "boolean") return false;
+  if (value.hostExecInDocker !== undefined && typeof value.hostExecInDocker !== "boolean") return false;
   return true;
 }
 
@@ -292,10 +301,17 @@ export function isMcpServerSpec(value: unknown): value is McpServerSpec {
 
 // Workspace id must be slug-shaped so it survives being used as the
 // mcpServers map key and in the `mcp__<id>__<tool>` tool naming.
+//
+// Consecutive `__` is forbidden inside the id because `__` is the
+// delimiter in the tool-name encoding — a server id like `foo__bar`
+// produces `mcp__foo__bar__tool`, which is ambiguous between server
+// `foo` (tool `bar__tool`) and server `foo__bar` (tool `tool`).
+// Forbidding `__` in the id keeps the convention unambiguous
+// everywhere (Codex review on #1356).
 const MCP_ID_RE = /^[a-z][a-z0-9_-]{0,63}$/;
 
 export function isMcpServerId(value: unknown): value is string {
-  return typeof value === "string" && MCP_ID_RE.test(value);
+  return typeof value === "string" && MCP_ID_RE.test(value) && !value.includes("__");
 }
 
 export function isMcpConfigFile(value: unknown): value is McpConfigFile {

package/server/system/docker.ts

@@ -41,18 +41,26 @@ function assertClaudeFiles(): void {
   }
 }
 
-export async function isDockerAvailable(): Promise<boolean> {
-  if (env.disableSandbox) return false;
-  if (_dockerEnabled !== null) return _dockerEnabled;
-  assertClaudeFiles();
+/** Pure daemon-liveness probe: `docker ps -q` succeeds only when the
+ *  client is installed AND the daemon is reachable. No config or
+ *  caching concerns — the optional-deps registry owns the PATH check
+ *  and caching; this is just the liveness half. */
+export async function isDockerLive(): Promise<boolean> {
   try {
     await execFileAsync("docker", ["ps", "-q"], {
       timeout: SUBPROCESS_PROBE_TIMEOUT_MS,
     });
-    _dockerEnabled = true;
+    return true;
   } catch {
-    _dockerEnabled = false;
+    return false;
   }
+}
+
+export async function isDockerAvailable(): Promise<boolean> {
+  if (env.disableSandbox) return false;
+  if (_dockerEnabled !== null) return _dockerEnabled;
+  assertClaudeFiles();
+  _dockerEnabled = await isDockerLive();
   return _dockerEnabled;
 }
 

package/server/system/env.ts

@@ -15,6 +15,8 @@
 // `docs/developer.md` lists every env var and what it does; this
 // module is the runtime side of that table.
 
+import { CLI_FLAGS } from "../utils/cli-flags.mjs";
+
 // ── Type coercion helpers ───────────────────────────────────────────
 
 function asInt(value: string | undefined, fallback: number, opts: { min?: number; max?: number } = {}): number {
@@ -33,6 +35,17 @@ function asFlag(value: string | undefined): boolean {
   return value === "1";
 }
 
+// Env vars also switched on by a CLI flag on this process's argv.
+// The npx launcher injects the env var into the spawned server, so
+// its path doesn't rely on this; this covers a direct
+// `tsx server/index.ts` / `yarn dev --<flag>` run. Computed once at
+// module load — same lifetime as the env snapshot below. (#1089.)
+const argvEnabledEnv = new Set<string>(CLI_FLAGS.filter(({ flag }) => process.argv.includes(flag)).map(({ env: envName }) => envName));
+
+function flagOf(envName: string): boolean {
+  return asFlag(process.env[envName]) || argvEnabledEnv.has(envName);
+}
+
 function asCsv(value: string | undefined): readonly string[] {
   return Object.freeze(
     (value ?? "")
@@ -57,13 +70,13 @@ export const env = Object.freeze({
   isProduction: process.env.NODE_ENV === "production",
 
   // Sandbox / Docker
-  disableSandbox: asFlag(process.env.DISABLE_SANDBOX),
+  disableSandbox: flagOf("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),
+  persistToolCalls: flagOf("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),
@@ -89,8 +102,8 @@ export const env = Object.freeze({
   // Debug-only force-run flags. Off by default; `=1` triggers an
   // immediate run on startup instead of waiting for the scheduled
   // interval.
-  journalForceRunOnStartup: asFlag(process.env.JOURNAL_FORCE_RUN_ON_STARTUP),
-  chatIndexForceRunOnStartup: asFlag(process.env.CHAT_INDEX_FORCE_RUN_ON_STARTUP),
+  journalForceRunOnStartup: flagOf("JOURNAL_FORCE_RUN_ON_STARTUP"),
+  chatIndexForceRunOnStartup: flagOf("CHAT_INDEX_FORCE_RUN_ON_STARTUP"),
 
   // macOS Reminder notification sink (#789). Darwin-only; iCloud
   // Reminders sync mirrors the entry to the user's iPhone, which
@@ -100,7 +113,7 @@ export const env = Object.freeze({
   // `DISABLE_MACOS_REMINDER_NOTIFICATIONS=1` to opt out (e.g. for
   // a shared dev box where the iPhone owner shouldn't get pinged).
   // Mirrors the `DISABLE_SANDBOX` convention.
-  disableMacosReminderNotifications: asFlag(process.env.DISABLE_MACOS_REMINDER_NOTIFICATIONS),
+  disableMacosReminderNotifications: flagOf("DISABLE_MACOS_REMINDER_NOTIFICATIONS"),
 
   // MulmoBridge Relay (#520). Optional — when both are set the server
   // connects to the Relay via WebSocket and forwards bridge messages.

package/server/system/optionalDeps.ts

@@ -0,0 +1,129 @@
+// Optional host-binary registry + graceful-degradation probe (#1385).
+//
+// A missing optional binary must never crash the app: the feature
+// that needs it disables itself, the user is warned once, and the
+// rest keeps working. This module centralises the "is <binary>
+// available?" question so we don't re-implement the lazy-cached
+// probe per dependency (docker's ad-hoc check was the only one
+// before this).
+
+import which from "which";
+import { isDockerLive } from "./docker.js";
+
+/** A single optional host dependency the app can run without. */
+export interface OptionalDep {
+  /** Stable id used by `depStatus()` lookups and notification ids. */
+  readonly id: string;
+  /** Binary name passed to `which` for the default presence probe. */
+  readonly command: string;
+  /** i18n key fragment naming what stops working when absent. */
+  readonly enables: string;
+  /** Override when "on PATH" is insufficient (e.g. docker client
+   *  exists but the daemon is down). Returning false means the
+   *  dependency is treated as unavailable even if `which` found it. */
+  readonly probe?: () => Promise<boolean>;
+}
+
+export type DepReason = "ok" | "not-on-path" | "probe-failed";
+
+export interface DepStatus {
+  readonly id: string;
+  readonly available: boolean;
+  readonly reason: DepReason;
+}
+
+const REGISTRY: readonly OptionalDep[] = [
+  { id: "docker", command: "docker", enables: "dockerSandbox", probe: isDockerLive },
+  { id: "ffmpeg", command: "ffmpeg", enables: "mulmocast" },
+];
+
+async function onPath(command: string): Promise<boolean> {
+  try {
+    const resolved = await which(command, { nothrow: true });
+    return resolved !== null;
+  } catch {
+    // `which` shouldn't throw with nothrow, but a corrupt PATH or
+    // an fs error must degrade to "absent", never bubble up.
+    return false;
+  }
+}
+
+// Never throws — a missing optional dep degrades, it does not crash
+// startup. A throwing PATH check or liveness `probe` is treated as
+// "unavailable" rather than propagating into the boot sequence.
+// `pathCheck` is injectable so unit tests exercise the reason
+// mapping + override precedence without depending on the host's
+// real PATH.
+export async function probeOne(dep: OptionalDep, pathCheck: (command: string) => Promise<boolean> = onPath): Promise<DepStatus> {
+  try {
+    if (!(await pathCheck(dep.command))) {
+      return { id: dep.id, available: false, reason: "not-on-path" };
+    }
+    if (dep.probe && !(await dep.probe())) {
+      return { id: dep.id, available: false, reason: "probe-failed" };
+    }
+    return { id: dep.id, available: true, reason: "ok" };
+  } catch {
+    return { id: dep.id, available: false, reason: "probe-failed" };
+  }
+}
+
+let cache: Record<string, DepStatus> | null = null;
+let inFlight: Promise<Record<string, DepStatus>> | null = null;
+
+/** Probe every registered dependency in parallel. Cached for the
+ *  process lifetime; concurrent callers share one in-flight run so
+ *  `which` / the daemon probe fire once each. */
+export async function probeOptionalDeps(): Promise<Record<string, DepStatus>> {
+  if (cache) return cache;
+  if (inFlight) return inFlight;
+  inFlight = (async () => {
+    try {
+      const statuses = await Promise.all(REGISTRY.map((dep) => probeOne(dep)));
+      cache = Object.fromEntries(statuses.map((status) => [status.id, status]));
+      return cache;
+    } catch {
+      // probeOne never rejects, so this is unreachable in practice —
+      // but if it ever did, returning an empty map keeps boot alive
+      // (callers treat "no status" as "assume available"). Do NOT
+      // poison `cache` so a later call can retry.
+      return {};
+    } finally {
+      // Always clear so a rejected/failed run can't permanently
+      // poison the cache (Codex review).
+      inFlight = null;
+    }
+  })();
+  return inFlight;
+}
+
+/** Synchronous read of a previously-probed dependency. Returns
+ *  undefined if `probeOptionalDeps()` has not completed yet — callers
+ *  on the request path should treat that as "assume available" so a
+ *  not-yet-probed boot window never blocks a feature. */
+export function depStatus(depId: string): DepStatus | undefined {
+  return cache?.[depId];
+}
+
+/** The registry, for callers that need the human-facing `enables`
+ *  label (boot warning composition). */
+export function optionalDeps(): readonly OptionalDep[] {
+  return REGISTRY;
+}
+
+/** Test-only: drop the cache so a fresh probe runs next call. */
+export function _resetOptionalDepsCacheForTest(): void {
+  cache = null;
+  inFlight = null;
+}
+
+/** Test-only: seed the probe cache directly so route guards and
+ *  `announceOptionalDeps` behave deterministically without invoking
+ *  the real `which` / daemon probe (CI has no control over whether
+ *  ffmpeg/docker are installed on the runner). `probeOptionalDeps()`
+ *  returns this seeded cache untouched (its first line is
+ *  `if (cache) return cache;`). */
+export function _setOptionalDepsCacheForTest(seed: Record<string, DepStatus>): void {
+  cache = seed;
+  inFlight = null;
+}

package/server/utils/cli-flags.d.mts

@@ -0,0 +1,14 @@
+// Type declarations for cli-flags.mjs. See the .mjs file for rationale
+// on why the shared registry lives in plain JS.
+
+export interface CliFlag {
+  flag: string;
+  env: string;
+  help: string;
+}
+
+export const CLI_FLAGS: readonly CliFlag[];
+
+export function flagEnvOverrides(argv: readonly string[]): Record<string, "1">;
+
+export function cliFlagHelpLines(): string;

package/server/utils/cli-flags.mjs

@@ -0,0 +1,53 @@
+// Shared registry of the boolean CLI flags that mirror an env var.
+// Single source of truth for: the launcher's argv→env injection
+// (`packages/mulmoclaude/bin/mulmoclaude.js`), the launcher `--help`
+// text, and the server-side argv awareness in `server/system/env.ts`.
+//
+// Kept as plain `.mjs` for the same reason as `dev-plugin-args.mjs` /
+// `port.mjs`: the launcher runs BEFORE tsx is wired up, so it can't
+// import from a `.ts` file. Sibling `cli-flags.d.mts` carries the
+// type declarations.
+//
+// Each flag is a launch-time boolean toggle that was previously only
+// reachable via a `VAR=1` env-var prefix — awkward on Windows
+// PowerShell `npx`, in IDE/launcher run configs, and for quick ad-hoc
+// debugging. Setting `<flag>` is equivalent to exporting `<env>=1`;
+// the env var stays supported in parallel (CI scripts / existing docs
+// rely on it). Secret-bearing vars (auth token, API keys) are
+// deliberately NOT here — argv is visible via `ps` and shell history,
+// so those stay env-only. (#1089 + bundle.)
+
+/** @type {ReadonlyArray<{ flag: string, env: string, help: string }>} */
+export const CLI_FLAGS = Object.freeze([
+  { flag: "--disable-sandbox", env: "DISABLE_SANDBOX", help: "Run without the Docker sandbox (= DISABLE_SANDBOX=1)" },
+  {
+    flag: "--disable-macos-reminders",
+    env: "DISABLE_MACOS_REMINDER_NOTIFICATIONS",
+    help: "Disable the macOS Reminder notification sink (= DISABLE_MACOS_REMINDER_NOTIFICATIONS=1)",
+  },
+  { flag: "--persist-tool-calls", env: "PERSIST_TOOL_CALLS", help: "Also persist tool_call events to the session jsonl (= PERSIST_TOOL_CALLS=1)" },
+  { flag: "--journal-force-run", env: "JOURNAL_FORCE_RUN_ON_STARTUP", help: "Run the journal pass immediately on startup (= JOURNAL_FORCE_RUN_ON_STARTUP=1)" },
+  {
+    flag: "--chat-index-force-run",
+    env: "CHAT_INDEX_FORCE_RUN_ON_STARTUP",
+    help: "Run the chat-index pass immediately on startup (= CHAT_INDEX_FORCE_RUN_ON_STARTUP=1)",
+  },
+]);
+
+/**
+ * Map present CLI flags to the `{ ENV: "1" }` overrides the launcher
+ * merges into the spawned server's env. Pure — caller passes argv in.
+ */
+export function flagEnvOverrides(argv) {
+  const overrides = {};
+  for (const { flag, env } of CLI_FLAGS) {
+    if (argv.includes(flag)) overrides[env] = "1";
+  }
+  return overrides;
+}
+
+/** Render the aligned `--help` lines for the flag block. */
+export function cliFlagHelpLines() {
+  const width = Math.max(...CLI_FLAGS.map(({ flag }) => flag.length));
+  return CLI_FLAGS.map(({ flag, help }) => `  ${flag.padEnd(width)}  ${help}`).join("\n");
+}

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

@@ -0,0 +1,111 @@
+// Single fs gateway for the Encore plugin. All reads / writes
+// against `data/plugins/encore/...` route through here so callers
+// don't sprinkle raw fs / path joins around (CLAUDE.md rule). All
+// writes use `writeFileAtomic` so partial writes can't corrupt the
+// on-disk DSL or cycle state.
+//
+// Domain-agnostic helpers only (read text, write text, read dir,
+// exists, unlink). Markdown frontmatter parsing / serialization
+// lives next to the consumers in src/plugins/encore/.
+
+import { promises as fsPromises } from "node:fs";
+import path from "node:path";
+
+import { WORKSPACE_DIRS, WORKSPACE_PATHS } from "../../workspace/paths.js";
+import { writeFileAtomic } from "./atomic.js";
+import { isEnoent } from "./safe.js";
+
+/** Absolute path to the Encore plugin's data directory. Reads
+ *  `WORKSPACE_PATHS.encore` so tests can override the absolute
+ *  location via Object.defineProperty (same pattern bookmarks
+ *  integration tests use for `pluginsData`). The optional
+ *  `workspaceRoot` is a one-off override for callers that want to
+ *  point at a custom directory without touching the global. */
+export function encoreRoot(workspaceRoot?: string): string {
+  if (workspaceRoot !== undefined) return path.join(workspaceRoot, WORKSPACE_DIRS.encore);
+  return WORKSPACE_PATHS.encore;
+}
+
+/** Join a workspace-relative encore path (from paths.ts) to the
+ *  absolute on-disk location. Validates that the resolved path is
+ *  still inside the Encore root — `path.join` alone happily
+ *  resolves `../../..` and escapes the plugin tree if a caller
+ *  ever passes a traversal-laden segment. paths.ts validates
+ *  segments at the source, but defense in depth is cheap. */
+function abs(rel: string, workspaceRoot?: string): string {
+  const root = encoreRoot(workspaceRoot);
+  const resolved = path.resolve(root, rel);
+  const normalisedRoot = path.resolve(root);
+  if (resolved !== normalisedRoot && !resolved.startsWith(`${normalisedRoot}${path.sep}`)) {
+    throw new Error(`encore: path ${JSON.stringify(rel)} escapes the plugin root`);
+  }
+  return resolved;
+}
+
+/** Read a text file under the Encore tree. Returns `null` if the
+ *  file doesn't exist (vs. throwing on ENOENT) — callers usually
+ *  want the missing-file case as "no such obligation" rather than
+ *  an error. */
+export async function readTextOrNull(rel: string, workspaceRoot?: string): Promise<string | null> {
+  try {
+    return await fsPromises.readFile(abs(rel, workspaceRoot), "utf8");
+  } catch (err) {
+    if (isEnoent(err)) return null;
+    throw err;
+  }
+}
+
+/** Write text atomically; creates parent directories as needed. */
+export async function writeText(rel: string, content: string, workspaceRoot?: string): Promise<void> {
+  const target = abs(rel, workspaceRoot);
+  await fsPromises.mkdir(path.dirname(target), { recursive: true });
+  await writeFileAtomic(target, content);
+}
+
+/** True iff the path exists (file or dir). */
+export async function exists(rel: string, workspaceRoot?: string): Promise<boolean> {
+  try {
+    await fsPromises.stat(abs(rel, workspaceRoot));
+    return true;
+  } catch (err) {
+    if (isEnoent(err)) return false;
+    throw err;
+  }
+}
+
+/** List directory entries (basenames only). Empty array if the
+ *  directory doesn't exist — easier than threading ENOENT through
+ *  every list call. */
+export async function readDir(rel: string, workspaceRoot?: string): Promise<string[]> {
+  try {
+    return await fsPromises.readdir(abs(rel, workspaceRoot));
+  } catch (err) {
+    if (isEnoent(err)) return [];
+    throw err;
+  }
+}
+
+/** Like `readDir`, but returns only entries that are themselves
+ *  directories. Used to enumerate obligation IDs without tripping
+ *  over `.DS_Store` and other stray non-directory entries that
+ *  macOS and editors drop into the tree. */
+export async function readDirSubdirs(rel: string, workspaceRoot?: string): Promise<string[]> {
+  try {
+    const entries = await fsPromises.readdir(abs(rel, workspaceRoot), { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch (err) {
+    if (isEnoent(err)) return [];
+    throw err;
+  }
+}
+
+/** Remove a file. No-op if it doesn't exist (matches the semantics
+ *  callers want when sweeping orphan tickets). */
+export async function unlink(rel: string, workspaceRoot?: string): Promise<void> {
+  try {
+    await fsPromises.unlink(abs(rel, workspaceRoot));
+  } catch (err) {
+    if (isEnoent(err)) return;
+    throw err;
+  }
+}

package/server/utils/time.ts

@@ -36,6 +36,12 @@ export const DEV_PLUGIN_WATCH_DEBOUNCE_MS = 300;
  *  a fail-fast guarantee. */
 export const STARTUP_FAILURE_FORCE_EXIT_MS = 5 * ONE_SECOND_MS;
 
+/** Tiny grace after an uncaught exception / unhandled rejection so
+ *  the final `log.error` line flushes to disk before the process
+ *  bounces. Long enough for a synchronous append, short enough not
+ *  to delay a crash-restart loop. */
+export const FATAL_LOG_FLUSH_MS = 100;
+
 /** Heavy subprocess work (libreoffice conversion, etc.) */
 export const SUBPROCESS_WORK_TIMEOUT_MS = ONE_MINUTE_MS;
 

package/server/workspace/helps/business.md

@@ -37,8 +37,8 @@ Reach for `presentMulmoScript` when the user asks for a presentation, slideshow,
       }
     }
   },
-  "imageParams": { "provider": "google", "model": "gemini-2.5-flash-image" },
-  "movieParams": { "provider": "google", "model": "veo-2.0-generate-001" },
+  "imageParams": { "provider": "google", "model": "gemini-3.1-flash-image-preview" },
+  "movieParams": { "provider": "google", "model": "veo-3.1-generate" },
   "textSlideParams": { "cssStyles": "body { background-color: white; }" },
   "beats": [
     {