@mulmoclaude/core 4.9.1 → 4.9.3

package/assets/helps/error-recovery.md

@@ -549,9 +549,10 @@ user's file by re-encoding it.
 A collection whose schema declares `storage: { type: "sqlite", path: … }`
 keeps its records in a single SQLite database file, read/written through
 Node's BUILT-IN `node:sqlite` module — no npm dependency. That module
-exists only in **Node.js >= 22.5**, while the app itself runs on >= 20.12,
-so on an older runtime ONLY sqlite-backed collections break (file and
-dataSource collections keep working) and every operation fails with
+exists only in **Node.js >= 22.5**. The app's own floor is >= 22.19, so a
+supported runtime always has it and this failure means a Node built without
+the module. Only sqlite-backed collections break (file and dataSource
+collections keep working); every operation fails with
 `sqlite storage needs the node:sqlite module (Node.js >= 22.5) — this
 runtime cannot load it`.
 
@@ -1392,8 +1393,8 @@ treatment, and the workspace mounted if you want it to follow the port.
 - The platform token (bot token, app token) was revoked or regenerated.
 - The bridge process is not running at all. Check before assuming anything above.
   Since #3084 a bridge that died says why on its last line — `[<transport>]
-  unhandled rejection — exiting: …` or `[<transport>] uncaught exception —
-  exiting: …`, naming the transport. A bridge stopped on purpose names the
+unhandled rejection — exiting: …` or `[<transport>] uncaught exception —
+exiting: …`, naming the transport. A bridge stopped on purpose names the
   signal: Ctrl-C prints `[<transport>] SIGINT — shutting down`, while a plain
   `kill <pid>` sends SIGTERM and prints `[<transport>] SIGTERM — shutting down`.
   **No such line and the process gone** means either an older npm build (they
@@ -1497,7 +1498,7 @@ install hint alone.
 ### Why
 
 Two servers over one workspace overwrite each other's `.session-token`. After
-that a stateless plugin dispatch authenticates cleanly against the *wrong*
+that a stateless plugin dispatch authenticates cleanly against the _wrong_
 server, while the session-scoped `/api/internal/tool-result` push lands where
 the session does not exist and is dropped — so plugin views simply never render
 on one of the two and nothing reports an error. The guard refuses that setup
@@ -1527,10 +1528,51 @@ means a real instance answered.
 To share one workspace between two servers anyway — accepting the token stomping:
 
 ```bash
-MULMOCLAUDE_ALLOW_MULTIPLE_INSTANCES=1 yarn dev
+yarn dev --allow-multiple-instances        # or MULMOCLAUDE_ALLOW_MULTIPLE_INSTANCES=1
 ```
 
-Use the env var for `yarn dev`. The `--allow-multiple-instances` flag works on
-`npx mulmoclaude` and `yarn server`, but **not** on `yarn dev`: that is a compound
-`a && b && c` script, yarn appends extra args to the last command only, and the
-guard that stops the launch runs in the first one.
+The flag and the env var are equivalent on `yarn dev`, `yarn server` and
+`npx mulmoclaude` alike. (Before #3113 the flag was silently dropped by `yarn dev`,
+so an older build needs the env var there.)
+
+## A bridge enabled in `config/bridges.json` is not running
+
+### Symptoms
+
+The workspace has `config/bridges.json` with a bridge switched on, the server
+started fine, and no messages arrive from that platform.
+
+### Cause
+
+An in-process bridge (#3080) never blocks server startup — a failure costs that
+one bridge and goes to the log. So the server looking healthy says nothing about
+the bridge. The log line names which of the three happened:
+
+```
+bridges  bridge failed to start — the server continues without it
+         { transportId: 'telegram', error: 'TELEGRAM_BOT_TOKEN is required. …' }
+
+bridges  enabled bridge cannot run in-process yet — start it with its CLI instead
+         { transportId: 'slack' }
+
+bridges  ignoring a malformed entry in config/bridges.json
+         { key: 'telegram', reason: '`enabled` must be true or false' }
+```
+
+### Fix
+
+1. `grep bridges <the server log>` and read which of the three it is.
+2. **Credentials missing** — they live in `.env`, not in `config/bridges.json`.
+   The error text names the variable (`TELEGRAM_BOT_TOKEN`, …).
+3. **Not converted yet** — only `telegram` runs in-process today; the other 24
+   still need `yarn <name>`. See `docs/in-process-bridges.md`.
+4. **Malformed entry** — the shape is `{ "bridges": { "<id>": { "enabled": true } } }`.
+   A transport id is lowercase letters, digits and dashes.
+
+Confirm with the startup line that lists what did start:
+
+```
+bridges  in-process bridges running  { transports: [ 'telegram' ] }
+```
+
+Absence of that line means nothing started.

package/assets/helps/sandbox.md

@@ -23,11 +23,11 @@ The container runs with `--cap-drop ALL` and as the host user's UID/GID, so it h
 
 ## Disabling the Sandbox
 
-Set the environment variable `DISABLE_SANDBOX=1` to always run the agent directly on the host, even when Docker is available. Equivalently, pass the `--disable-sandbox` CLI flag — `npx mulmoclaude --disable-sandbox` or `yarn server --disable-sandbox` (**not** `yarn dev`, whose compound script drops trailing args; use the env var there). The flag form is handy on Windows PowerShell (no inline `VAR=value` syntax), in IDE / launcher run configs, and for quick ad-hoc debugging. Both set the same internal switch; the env var stays supported in parallel.
+Set the environment variable `DISABLE_SANDBOX=1` to always run the agent directly on the host, even when Docker is available. Equivalently, pass the `--disable-sandbox` CLI flag — `yarn dev --disable-sandbox`, `yarn server --disable-sandbox` or `npx mulmoclaude --disable-sandbox`. The flag form is handy on Windows PowerShell (no inline `VAR=value` syntax), in IDE / launcher run configs, and for quick ad-hoc debugging. Both set the same internal switch; the env var stays supported in parallel.
 
 ## Debug aids (opt-in env vars)
 
-These flags exist for development / debugging only. Off by default so production runs aren't surprised. Each has an equivalent `--flag` CLI form (drop the `=1`, kebab-case the name) accepted by `npx mulmoclaude` and `yarn server` — but **not** `yarn dev`, which drops trailing args — e.g. `DISABLE_SANDBOX=1` ≡ `--disable-sandbox`, `PERSIST_TOOL_CALLS=1` ≡ `--persist-tool-calls`, `DISABLE_MACOS_REMINDER_NOTIFICATIONS=1` ≡ `--disable-macos-reminders`, `JOURNAL_FORCE_RUN_ON_STARTUP=1` ≡ `--journal-force-run`, `CHAT_INDEX_FORCE_RUN_ON_STARTUP=1` ≡ `--chat-index-force-run`. Secret-bearing vars (auth token, API keys) have no flag form on purpose — argv is visible via `ps` / shell history.
+These flags exist for development / debugging only. Off by default so production runs aren't surprised. Each has an equivalent `--flag` CLI form (drop the `=1`, kebab-case the name) accepted by `yarn dev`, `yarn server` and `npx mulmoclaude` — e.g. `DISABLE_SANDBOX=1` ≡ `--disable-sandbox`, `PERSIST_TOOL_CALLS=1` ≡ `--persist-tool-calls`, `DISABLE_MACOS_REMINDER_NOTIFICATIONS=1` ≡ `--disable-macos-reminders`, `JOURNAL_FORCE_RUN_ON_STARTUP=1` ≡ `--journal-force-run`, `CHAT_INDEX_FORCE_RUN_ON_STARTUP=1` ≡ `--chat-index-force-run`. Secret-bearing vars (auth token, API keys) have no flag form on purpose — argv is visible via `ps` / shell history.
 
 - `DISABLE_SANDBOX=1` — see above. Bypasses the Docker sandbox.
 - `PERSIST_TOOL_CALLS=1` — also persist `tool_call` events to the session jsonl alongside `tool_result`. Useful for reading the args sent to a tool after the run is over (page refresh / server restart). Off by default because args can be large and may carry payload bytes (inline images, full MulmoScript JSON) you didn't expect to land in the jsonl. See [issue #1096](https://github.com/receptron/mulmoclaude/issues/1096) for the rationale.