mulmoclaude 0.6.2 → 0.6.3

package/server/events/notifications.ts

@@ -2,7 +2,7 @@
 // wrapper over the new notifier engine (PR 4 of feat-encore).
 //
 // The signature is preserved so the existing host call sites
-// (`server/agent/mcp-tools/notify.ts`, `server/api/routes/notifications.ts`,
+// (`server/agent/mcp-tools/notify.ts`,
 // `server/workspace/sources/pipeline/notify.ts`,
 // `server/plugins/diagnostics.ts`) keep working without source changes.
 // Internally it now:
@@ -16,14 +16,17 @@
 //      legacy entries publish with `lifecycle: "fyi"`, so the
 //      `action`-lifecycle rules don't apply and clicking still routes).
 //   4. Stashes the legacy fields (`kind`, `priority`, `action`,
-//      `i18n`, `transportId`, `sessionId`, the caller-supplied dedup
-//      `id`) on `pluginData` so the bell can preserve icon, i18n
-//      localization, and transport routing.
+//      `i18n`, `sessionId`, the caller-supplied dedup `id`) on
+//      `pluginData` so the bell can preserve icon, i18n localization,
+//      and dedup.
 //
-// Bridge push (`chat-service.pushToBridge`) and macOS Reminder push
-// no longer happen inline here — they're owned by adapters that
-// subscribe to the `notifier` pubsub channel. See
-// `server/notifier/legacy-adapters.ts`.
+// macOS Reminder push happens via the `macosReminderAdapter` listener
+// subscribed to the notifier pubsub channel. The previous bridge
+// fan-out path was removed (#1351 follow-up): the only callers
+// setting `transportId` were the PoC `/api/notifications/test` route
+// and `scheduleTestNotification`, both deleted in the same change.
+// Production callers never set `transportId`, so the entire bridge
+// side-channel was dead code.
 
 import { PAGE_ROUTES } from "../../src/router/pageRoutes.js";
 import {
@@ -38,7 +41,6 @@ import {
 } from "../../src/types/notification.js";
 import { publish as notifierPublish } from "../notifier/engine.js";
 import type { NotifierSeverity } from "../notifier/types.js";
-import { ONE_SECOND_MS, MAX_NOTIFICATION_DELAY_SEC } from "../utils/time.js";
 import { log } from "../system/logger/index.js";
 import { makeUuid } from "../utils/id.js";
 
@@ -51,7 +53,6 @@ export interface PublishNotificationOpts {
   action?: NotificationAction;
   priority?: NotificationPriority;
   sessionId?: string;
-  transportId?: string;
   /** Override the auto-generated UUID with a caller-supplied stable
    *  id. Used by the plugin-meta diagnostics: the same diagnostic
    *  id is returned from `/api/plugins/diagnostics`, and `pluginData`
@@ -60,7 +61,7 @@ export interface PublishNotificationOpts {
   id?: string;
   /** vue-i18n keys + params for clients to localize the title/body.
    *  Server-side `title` / `body` stay set as English fallbacks for
-   *  logs, macOS Reminder push, and bridge push paths. */
+   *  logs and the macOS Reminder push. */
   i18n?: NotificationI18n;
 }
 
@@ -79,7 +80,6 @@ export interface LegacyNotifierPluginData {
   priority: NotificationPriority;
   action: NotificationAction;
   i18n?: NotificationI18n;
-  transportId?: string;
   sessionId?: string;
 }
 
@@ -155,9 +155,7 @@ function buildChatTarget(target: Extract<NavigateTarget, { view: typeof NOTIFICA
   // redirect is worse UX than a non-clickable entry. Dot-segment
   // sessionId would normalize off /chat, so drop too.
   if (!target.sessionId || !isSafePathComponent(target.sessionId)) return undefined;
-  const sessionPath = `/${PAGE_ROUTES.chat}/${encodeURIComponent(target.sessionId)}`;
-  if (target.resultUuid) return `${sessionPath}?result=${encodeURIComponent(target.resultUuid)}`;
-  return sessionPath;
+  return `/${PAGE_ROUTES.chat}/${encodeURIComponent(target.sessionId)}`;
 }
 
 function buildFilesTarget(target: Extract<NavigateTarget, { view: typeof NOTIFICATION_VIEWS.files }>): string {
@@ -233,12 +231,12 @@ export function legacyActionToNavigateTarget(action: NotificationAction | undefi
  * to the calling plugin so plugins cannot impersonate each other.
  *
  * This wrapper exists for host-side callers (`server/agent/`,
- * `server/api/routes/`, `server/workspace/`, `server/plugins/diagnostics.ts`)
- * that don't have a `PluginRuntime` to hand. It forwards into
- * `notifier.publish` with `lifecycle: "fyi"` and stashes legacy fields
- * on `pluginData` so the bell can preserve icon / i18n / transport
- * semantics. Bridge + macOS push are owned by separate adapters
- * subscribed to the `notifier` pubsub channel, not by this function.
+ * `server/workspace/`, `server/plugins/diagnostics.ts`) that don't
+ * have a `PluginRuntime` to hand. It forwards into `notifier.publish`
+ * with `lifecycle: "fyi"` and stashes legacy fields on `pluginData`
+ * so the bell can preserve icon / i18n / dedup semantics. macOS
+ * Reminder push is owned by the adapter subscribed to the notifier
+ * pubsub channel, not by this function.
  */
 export function publishNotification(opts: PublishNotificationOpts): void {
   const legacyId = opts.id ?? makeUuid();
@@ -250,7 +248,6 @@ export function publishNotification(opts: PublishNotificationOpts): void {
     priority: opts.priority ?? NOTIFICATION_PRIORITIES.normal,
     action,
     i18n: opts.i18n,
-    transportId: opts.transportId,
     sessionId: opts.sessionId,
   };
   // Fire-and-forget — the engine queues writes through its own
@@ -269,72 +266,3 @@ export function publishNotification(opts: PublishNotificationOpts): void {
     log.warn("notifications", "publish failed", { error: String(err), legacyId, kind: opts.kind });
   });
 }
-
-// ── Legacy test notification (kept for PoC endpoint) ────────────
-
-export const DEFAULT_NOTIFICATION_MESSAGE = "Test notification";
-export const DEFAULT_NOTIFICATION_TRANSPORT_ID = "cli";
-
-export interface ScheduleNotificationOptions {
-  message?: string;
-  body?: string;
-  delaySeconds?: number;
-  transportId?: string;
-  // Optional deep-link action — lets dev-side callers fire a
-  // notification that navigates to a specific permalink when
-  // clicked. Without this the fired notification has no click
-  // behaviour (same as before #762).
-  action?: NotificationAction;
-  // Optional kind override — lets the manual-test helper fire a
-  // representative notification for every NotificationKind (todo,
-  // scheduler, agent, …) so the bell's icons can be eyeballed.
-  kind?: NotificationKind;
-}
-
-export interface ScheduledNotification {
-  firesAt: string;
-  delaySeconds: number;
-  cancel: () => void;
-}
-
-/** PoC: schedules one `publishNotification` after a delay. Bridge
- *  push is no longer sent inline here — the bridge adapter (subscribed
- *  to the notifier channel) fans out to bridges based on the entry's
- *  `pluginData.transportId`. */
-export function scheduleTestNotification(opts: ScheduleNotificationOptions): ScheduledNotification {
-  const message = opts.message ?? DEFAULT_NOTIFICATION_MESSAGE;
-  const transportId = opts.transportId ?? DEFAULT_NOTIFICATION_TRANSPORT_ID;
-  const delaySeconds = clampDelay(opts.delaySeconds);
-  const delayMs = delaySeconds * ONE_SECOND_MS;
-  const kind = opts.kind ?? NOTIFICATION_KINDS.push;
-
-  const firesAt = new Date(Date.now() + delayMs).toISOString();
-
-  const timer = setTimeout(() => {
-    publishNotification({
-      kind,
-      title: message,
-      body: opts.body,
-      priority: NOTIFICATION_PRIORITIES.normal,
-      action: opts.action,
-      transportId,
-    });
-  }, delayMs);
-
-  return {
-    firesAt,
-    delaySeconds,
-    cancel: () => clearTimeout(timer),
-  };
-}
-
-const DEFAULT_DELAY_SECONDS = 60;
-
-function clampDelay(raw: number | undefined): number {
-  if (typeof raw !== "number" || !Number.isFinite(raw)) {
-    return DEFAULT_DELAY_SECONDS;
-  }
-  if (raw < 0) return 0;
-  if (raw > MAX_NOTIFICATION_DELAY_SEC) return MAX_NOTIFICATION_DELAY_SEC;
-  return Math.floor(raw);
-}

package/server/index.ts

@@ -36,8 +36,9 @@ import { loadPresetPlugins } from "./plugins/preset-loader.js";
 import { registerRuntimePlugins } from "./plugins/runtime-registry.js";
 import { makePluginRuntime } from "./plugins/runtime.js";
 import { MCP_PLUGIN_NAMES } from "./agent/plugin-names.js";
-import { createNotificationsRouter } from "./api/routes/notifications.js";
-import { startLegacyAdapters } from "./notifier/legacy-adapters.js";
+import { setActiveBackend } from "./agent/backend/index.js";
+import { fakeEchoBackend } from "./agent/backend/fake-echo.js";
+import { startMacosReminderAdapter } from "./notifier/macosReminderAdapter.js";
 import notifierRoutes from "./api/routes/notifier.js";
 import { initNotifier } from "./notifier/engine.js";
 import { registerSaveAttachmentHook } from "./utils/files/attachment-store.js";
@@ -45,6 +46,7 @@ import { capturePhotoLocation } from "./workspace/photo-locations/index.js";
 import { createJournalRouter } from "./api/routes/journal.js";
 import { createTranslationRouter } from "./api/routes/translation.js";
 import { announcePluginMetaDiagnostics } from "./plugins/diagnostics.js";
+import { announceOptionalDeps } from "./system/announceOptionalDeps.js";
 import { createChatService } from "@mulmobridge/chat-service";
 import { readSessionJsonl } from "./utils/files/session-io.js";
 import { onSessionEvent, initSessionStore } from "./events/session-store/index.js";
@@ -56,6 +58,8 @@ import { WORKSPACE_PATHS } from "./workspace/paths.js";
 import { serverError } from "./utils/httpError.js";
 import { makeUuid } from "./utils/id.js";
 import { mcpToolsRouter, mcpTools, isMcpToolEnabled } from "./agent/mcp-tools/index.js";
+import { preflightUserServers, logPreflightResult } from "./agent/mcpPreflight.js";
+import { loadMcpConfig } from "./system/config.js";
 import { initWorkspace, workspacePath } from "./workspace/workspace.js";
 import { runMemoryMigrationOnce } from "./workspace/memory/run.js";
 import { runTopicMigrationOnce } from "./workspace/memory/topic-run.js";
@@ -91,7 +95,7 @@ import { EVENT_TYPES } from "../src/types/events.js";
 import { SESSION_ORIGINS } from "../src/types/session.js";
 import { buildHtmlPreviewCsp } from "../src/utils/html/previewCsp.js";
 import { readAndInjectHtmlArtifact } from "./utils/html/htmlArtifactSplicer.js";
-import { ONE_SECOND_MS, ONE_MINUTE_MS, ONE_HOUR_MS, STARTUP_FAILURE_FORCE_EXIT_MS } from "./utils/time.js";
+import { ONE_SECOND_MS, ONE_MINUTE_MS, ONE_HOUR_MS, STARTUP_FAILURE_FORCE_EXIT_MS, FATAL_LOG_FLUSH_MS } from "./utils/time.js";
 import { isPortFree, findAvailablePort, MAX_PORT_PROBES } from "./utils/port.mjs";
 import { SCHEDULE_TYPES, MISSED_RUN_POLICIES } from "@receptron/task-scheduler";
 
@@ -102,6 +106,46 @@ const __dirname = path.dirname(__filename);
 
 const debugMode = process.argv.includes("--debug");
 
+// Global crash diagnostics (#1364). These handlers log loudly so a
+// fatal failure is triagable, then EXIT — keeping the loop running
+// after an uncaught exception is process-unsafe per the Node docs
+// (invariants may already be broken). The launcher / supervisor
+// (Electron wrapper, systemd, etc.) is responsible for restart.
+//
+// The canonical failure this PR set out to fix — missing `claude`
+// on PATH crashing the server via spawn's `error` event — is now
+// caught at the local boundary in `server/agent/backend/claude-code.ts`
+// (an explicit `error` listener turns ENOENT into an AgentEvent).
+// These handlers are the BACKSTOP for anything we missed, not a
+// substitute for local error handling. (Codex review on #1364.)
+//
+// `process.exit(1)` is non-zero so supervisors that branch on exit
+// code treat the bounce as an error condition.
+process.on("uncaughtException", (err) => {
+  log.error("uncaughtException", err instanceof Error ? err.message : String(err), {
+    stack: err instanceof Error ? err.stack : undefined,
+  });
+  // Tiny grace so the log line flushes to disk before we exit.
+  setTimeout(() => process.exit(1), FATAL_LOG_FLUSH_MS);
+});
+process.on("unhandledRejection", (reason) => {
+  log.error("unhandledRejection", reason instanceof Error ? reason.message : String(reason), {
+    stack: reason instanceof Error ? reason.stack : undefined,
+  });
+  setTimeout(() => process.exit(1), FATAL_LOG_FLUSH_MS);
+});
+
+// Test-seam: CI runs without a Claude CLI / API key set the
+// MULMOCLAUDE_FAKE_AGENT env var, which swaps in an echo-stub
+// backend so the chat flow still completes. Decided once at boot;
+// the orchestrator reads the active backend with zero per-call
+// overhead. Production callers never trip this branch (no runtime
+// import-time cost beyond the small fake-echo module itself).
+if (process.env.MULMOCLAUDE_FAKE_AGENT === "1") {
+  setActiveBackend(fakeEchoBackend);
+  log.info("agent", "MULMOCLAUDE_FAKE_AGENT=1 — active backend = fake-echo");
+}
+
 initWorkspace();
 
 // Fire-and-forget memory migrations: legacy `memory.md` → atomic
@@ -653,7 +697,6 @@ app.use(chatService.router);
 // `startRuntimeServices` has it. Calls that arrive before fill-in
 // (impossible in practice — the HTTP server isn't listening yet)
 // would no-op on publish but still queue the bridge push.
-app.use(createNotificationsRouter());
 app.use(notifierRoutes);
 app.use(createJournalRouter());
 app.use(createTranslationRouter());
@@ -768,6 +811,29 @@ function logMcpStatus(): void {
     const names = disabledMcpTools.map((toolDef) => `${toolDef.definition.name} (${(toolDef.requiredEnv ?? []).join(", ")})`).join(", ");
     log.info("mcp", "Unavailable (missing env)", { tools: names });
   }
+  logExternalMcpPreflight();
+}
+
+// External MCP servers (the `mcp.json` ones — Notion / GitHub /…)
+// get a separate preflight pass that mirrors the built-in
+// `Available / Unavailable` summary above. Servers with catalog
+// entries whose `required: true` fields are unset are excluded from
+// the config handed to Claude Code (filtered inside
+// `prepareUserServers`); this boot-time log gives the operator one
+// clear startup signal (#1352).
+function logExternalMcpPreflight(): void {
+  try {
+    const userMcpRaw = loadMcpConfig().mcpServers;
+    const preflight = preflightUserServers(userMcpRaw);
+    logPreflightResult(preflight, "boot");
+  } catch (err) {
+    // Best-effort: a broken mcp.json shouldn't take down boot. The
+    // per-agent-run path will still attempt the preflight and surface
+    // any genuine issue when the user actually starts a chat.
+    log.warn("mcp", "preflight at boot failed; will retry per-agent-run", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
 }
 
 function maybeForceJournalRun(): void {
@@ -807,11 +873,9 @@ async function startRuntimeServices(httpServer: ReturnType<typeof app.listen>, p
   // is forwarded in here so the rest of `startRuntimeServices` can
   // share the same instance.
 
-  // --- Legacy adapters (bridge + macOS Reminder push) ---
-  // Subscribe in-process to the engine so any `notifier.publish` —
-  // legacy wrapper or plugin-runtime — triggers the same fan-out the
-  // legacy `publishNotification()` did inline before PR 4.
-  startLegacyAdapters({ pushToBridge: chatService.pushToBridge });
+  // macOS Reminder adapter wiring lives in the `app.listen` callback,
+  // alongside `initNotifier`, so it's subscribed before the first
+  // await opens a publish-can-fire-but-no-one's-listening window.
 
   // --- Plugin META aggregator diagnostics ---
   // After the notifier engine is initialized so the wrapper has a
@@ -820,6 +884,12 @@ async function startRuntimeServices(httpServer: ReturnType<typeof app.listen>, p
   // notification.
   await announcePluginMetaDiagnostics();
 
+  // --- Optional host-dependency probe (#1385) ---
+  // Probes docker / ffmpeg / … once, warns (log + bell) for any
+  // missing one so a feature degrading is visible instead of a
+  // later opaque crash. Never throws.
+  await announceOptionalDeps();
+
   // --- Chat socket transport (Phase A of #268) ---
   chatService.attachSocket(httpServer);
 
@@ -1123,6 +1193,14 @@ process.on("SIGTERM", () => {
     initNotifier({
       publish: (channel, payload) => earlyPubsub.publish(channel, payload),
     });
+    // Subscribe the macOS Reminder side-channel BEFORE the first
+    // await below — `initNotifier` opens the engine to publishes,
+    // and any boot-time diagnostic that lands during the
+    // `.server-port` write / `startRuntimeServices` setup would
+    // otherwise miss the Reminder fan-out (CodeRabbit review on
+    // PR #1358). The adapter is sync + no-op outside darwin, so
+    // wiring it here costs nothing.
+    startMacosReminderAdapter();
 
     // Publish the actually-bound port so the hook script can
     // address us — the requested PORT may have walked forward

package/server/notifier/macosReminderAdapter.ts

@@ -0,0 +1,30 @@
+// macOS Reminder side-channel adapter for the notifier engine.
+//
+// Subscribes to the engine's `published` events and fires
+// `pushToMacosReminder` for each one — that helper is itself a no-op
+// outside darwin / when `DISABLE_MACOS_REMINDER_NOTIFICATIONS=1`, so
+// the adapter is safe to start unconditionally.
+//
+// History: this file used to be `legacy-adapters.ts` and carried a
+// second branch that fanned out to chat-service bridges based on a
+// `transportId` field on `pluginData`. That branch was dead code —
+// the only callers setting `transportId` were the PoC
+// `/api/notifications/test` route and `scheduleTestNotification`,
+// both removed in the same change. Real production publishers
+// (mcp-tools/notify, sources/pipeline/notify, plugins/diagnostics,
+// mcpFailureMonitor) never set the field, so no behaviour changed.
+// If a future use case wants bridge fan-out it should arrive with a
+// concrete caller and a designed API, not as latent scaffolding.
+
+import { onEvent } from "./engine.js";
+import { pushToMacosReminder } from "../system/macosNotify.js";
+
+/** Wire the macOS Reminder sink as an in-process listener on the
+ *  notifier engine. Returns an unsubscribe function for tests /
+ *  teardown. */
+export function startMacosReminderAdapter(): () => void {
+  return onEvent((event) => {
+    if (event.type !== "published") return;
+    void pushToMacosReminder(event.entry.title, event.entry.body);
+  });
+}

package/server/system/announceOptionalDeps.ts

@@ -0,0 +1,50 @@
+// Boot-time graceful-degradation announcement for missing optional
+// host binaries (#1385). Probes the registry, then for each missing
+// dependency emits one structured log.warn plus a deduped bell
+// notification naming the affected feature/plugins. Never throws —
+// degradation is the whole point.
+
+import { BUILT_IN_PLUGIN_METAS } from "../../src/plugins/metas.js";
+import type { PluginMeta } from "../../src/plugins/meta-types.js";
+import { NOTIFICATION_PRIORITIES } from "../../src/types/notification.js";
+import { log } from "./logger/index.js";
+import { publishNotification } from "../events/notifications.js";
+import { probeOptionalDeps, optionalDeps } from "./optionalDeps.js";
+
+function pluginsRequiring(depId: string): string[] {
+  const metas: readonly PluginMeta[] = Object.values(BUILT_IN_PLUGIN_METAS);
+  return metas.filter((meta) => meta.requires?.includes(depId)).map((meta) => meta.toolName);
+}
+
+export async function announceOptionalDeps(): Promise<void> {
+  const statuses = await probeOptionalDeps();
+  for (const dep of optionalDeps()) {
+    const status = statuses[dep.id];
+    if (!status || status.available) continue;
+    const affectedPlugins = pluginsRequiring(dep.id);
+    // `not-on-path` → install it; `probe-failed` → it's installed
+    // but not responding (e.g. the docker daemon is down). The
+    // remediation differs, so the copy must be reason-aware rather
+    // than always saying "not found" (Codex review).
+    const notFound = status.reason === "not-on-path";
+    log.warn("deps", `optional dependency '${dep.command}' unavailable — ${dep.enables} degraded`, {
+      depId: dep.id,
+      reason: status.reason,
+      affectedPlugins,
+    });
+    publishNotification({
+      id: `optional-dep-missing:${dep.id}`,
+      kind: "system",
+      priority: NOTIFICATION_PRIORITIES.normal,
+      title: "Optional dependency unavailable",
+      body: notFound
+        ? `${dep.command} not found — some features are disabled. Install it and restart.`
+        : `${dep.command} is installed but not responding — some features are disabled. Start it and restart.`,
+      i18n: {
+        titleKey: "optionalDeps.title",
+        bodyKey: notFound ? "optionalDeps.notFound" : "optionalDeps.notResponding",
+        bodyParams: { command: dep.command },
+      },
+    });
+  }
+}

package/server/system/config.ts

@@ -292,10 +292,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.