@mulmoclaude/core 4.8.0 → 4.9.1

package/assets/helps/bug-report-faq.md

@@ -56,6 +56,18 @@ settings is the user's opt-in. The RemoteHost channel must also be connected —
 what supplies the Firebase auth, so with the phone link down the send is a no-op by design. A user
 who never connected a phone has nothing to receive the push regardless of the setting.
 
+## MulmoClaude is answering with a different model than I expected
+
+configKey: chatModel
+source: server/agent/config.ts
+
+Read `chatModel` from the live settings. Absent means MulmoClaude passes no `--model` at all and the
+CLI resolves the model from `~/.claude/settings.json` — the same file the VS Code and Cursor Claude
+Code extensions write their `/model` pick to, so a switch made in another editor changes MulmoClaude
+too, with nothing on screen to say so. Setting the key from Settings → Model is what pins MulmoClaude
+independently of that shared file. A session already running keeps its model until the next turn, so
+"it changed partway through a conversation" is the expected shape of this, not a second bug.
+
 ## My chats never get titles or summaries
 
 configKey: chatIndex

package/assets/helps/custom-view.md

@@ -64,7 +64,7 @@ would run ahead of it and see no `__MC_VIEW`; there is no reason to write one.)
 window.__MC_VIEW = {
   slug: "annual-plan", // this collection
   token: "<scoped capability token>", // Authorization bearer
-  dataUrl: "http://localhost:3001/api/collections/annual-plan/view-data",
+  dataUrl: "http://127.0.0.1:<port>/api/collections/annual-plan/view-data", // absolute, filled in by the host
   onChange: (cb) => unsubscribe, // live refresh — see "Staying live" below
   searchQuery: "", // live text in the app's own search box — see "One search box"
   onSearchQueryChange: (cb) => unsubscribe, // fires when the user types there

package/assets/helps/error-recovery.md

@@ -124,11 +124,17 @@ Report body:
 
 ```markdown
 ## What happened
+
 ## What I expected
+
 ## Steps to reproduce
+
 1.
+
 ## Environment
+
 (paste the diagnostics report here)
+
 ## Attachments
 ```
 
@@ -280,7 +286,7 @@ naming the file:
   quotes, unquoted key.
 - `role file does not match the role schema, skipping` — the `issues`
   field names each field, e.g. `icon: Invalid input: expected string,
-  received undefined`. All of `id`, `name`, `icon`, `prompt`,
+received undefined`. All of `id`, `name`, `icon`, `prompt`,
   `availablePlugins` are required; `availablePlugins` must be an array
   even for one entry.
 - `role file is empty, skipping` — zero-length or whitespace only.
@@ -328,7 +334,7 @@ it:
     `my role.json`, rejected as `Invalid role id 'my role'.` Neither name
     reaches the role. Renaming is the only fix.
   - `… the id is not a usable role id` — the reverse, e.g. `"id": "my
-    role"` in `designer.json`. `delete designer` still works, and renaming
+role"` in `designer.json`. `delete designer` still works, and renaming
     to `my role.json` would take that away. Change the `id`.
   - `… neither is a usable role id` — pick one id that matches the pattern
     and use it for the file name and the `id` together.
@@ -926,12 +932,12 @@ They are genuinely different failures — a permanent load failure, a startup ra
 and guessing between them is what makes this expensive. Since #2842 the log answers it directly,
 so read these three before forming a theory:
 
-| Log line | What it tells you |
-|---|---|
-| `spawning agent … broker=tsx` | This install is on the SLOW path: the bundle is missing, so the broker is transcoded from source on every spawn (seconds to tens of seconds over a Windows/macOS bind mount). A `broker bundle missing` warn accompanies it once per process. |
-| `[mcp] broker ready bootMs=… initializeMs=…` | The broker DID connect, and how long it took. `broker cold boot is slow` replaces it past 5 s. |
-| `brokerEverReady=false reason=never-ready` on the retry warn | No beacon arrived for that chat, and the host kept looking until the beacon's own delivery budget was spent — the broker did not come up at all. The turn is NOT replayed: a replay would sit out another full connect wait and end in the same error. |
-| `reason=ready-during-wait` on the retry warn | The beacon arrived while the host waited, so the broker lost the race by a moment and IS connected now. The turn is replayed, which is what fixes this one. |
+| Log line                                                      | What it tells you                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `spawning agent … broker=tsx`                                 | This install is on the SLOW path: the bundle is missing, so the broker is transcoded from source on every spawn (seconds to tens of seconds over a Windows/macOS bind mount). A `broker bundle missing` warn accompanies it once per process.                                                                                                                                                                                                                                                                                                     |
+| `[mcp] broker ready bootMs=… initializeMs=…`                  | The broker DID connect, and how long it took. `broker cold boot is slow` replaces it past 5 s.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `brokerEverReady=false reason=never-ready` on the retry warn  | No beacon arrived for that chat, and the host kept looking until the beacon's own delivery budget was spent — the broker did not come up at all. The turn is NOT replayed: a replay would sit out another full connect wait and end in the same error.                                                                                                                                                                                                                                                                                            |
+| `reason=ready-during-wait` on the retry warn                  | The beacon arrived while the host waited, so the broker lost the race by a moment and IS connected now. The turn is replayed, which is what fixes this one.                                                                                                                                                                                                                                                                                                                                                                                       |
 | `brokerEverStarted=` on the `MCP tools were unavailable` warn | Whether the broker PROCESS ever existed, which is a different question from whether it answered. `true` with `brokerEverReady=false` means it launched and never finished booting — the boot is the problem (the mount, the `tsx` path). `false` means it never launched — the spawn is the problem. Diagnostic only, and not authenticated: under Docker everything needed to forge it sits in the per-session MCP config inside the workspace mount, so read it as evidence about a healthy install rather than as proof against a hostile one. |
 
 ### Fix
@@ -968,7 +974,7 @@ so read these three before forming a theory:
 
 - The `google` tool (or a `google.calendar.*` remote command) fails with **"Google account not linked on this host"**.
 - **"Google sign-in service unreachable"** or **"Google sign-in service returned HTTP …"**.
-- **"multiple client_secret_*.json files found"**.
+- **"multiple client_secret\_*.json files found"**.
 - **"Google Calendar API: HTTP 403"** with a hint about enabling the API.
 - **"Google Calendar API: HTTP 403 — Request had insufficient authentication scopes"** when pushing
   a collection to a calendar that is NOT in the account's own calendar list.
@@ -1121,8 +1127,7 @@ Pass the file instead. `putItems` accepts **`itemsFile`** — an absolute path t
 a JSON file holding the array of record objects, read by the host:
 
 ```jsonc
-{ "action": "putItems", "slug": "slots", "mode": "create",
-  "itemsFile": "/absolute/path/to/generated-slots.json" }
+{ "action": "putItems", "slug": "slots", "mode": "create", "itemsFile": "/absolute/path/to/generated-slots.json" }
 ```
 
 Write the generated file **under the workspace**. Paths outside it are refused:
@@ -1144,17 +1149,17 @@ Rules that make it fail cleanly rather than silently:
 
 Reading the refusal you got:
 
-| Message | What it means |
-| --- | --- |
-| `must be an ABSOLUTE path` | You passed a relative path. Pass the full one. |
-| `must be inside the workspace` | The file is outside the workspace (or a symlink out of it). Regenerate it under the workspace. |
-| `is a symbolic link` | Symlinks are never followed. Pass the real path. |
-| `changed while it was being opened` | The file was replaced mid-call. Finish writing it, then call putItems. |
-| `grew while it was being read` | The file was still being written. Wait for the script to finish, then call putItems. |
-| `could not read \`itemsFile\`` | The host cannot see that path — the usual cause is a file written to a temp dir outside the mount. Write it under the workspace. |
-| `is not a regular file` | The path is a directory, device, or fifo. |
-| `could not be read as JSON` | The file exists and was read, but does not parse. This is YOUR file's shape, not a host problem — check the script that wrote it (a truncated write, a trailing comma, log output mixed into the file). |
-| `must hold a non-empty JSON array of record objects` | It parsed, but is `[]`, an object, or an array of scalars. The file must be `[{…}, {…}]` — the same row objects you would have passed as `items`. |
+| Message                                              | What it means                                                                                                                                                                                           |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `must be an ABSOLUTE path`                           | You passed a relative path. Pass the full one.                                                                                                                                                          |
+| `must be inside the workspace`                       | The file is outside the workspace (or a symlink out of it). Regenerate it under the workspace.                                                                                                          |
+| `is a symbolic link`                                 | Symlinks are never followed. Pass the real path.                                                                                                                                                        |
+| `changed while it was being opened`                  | The file was replaced mid-call. Finish writing it, then call putItems.                                                                                                                                  |
+| `grew while it was being read`                       | The file was still being written. Wait for the script to finish, then call putItems.                                                                                                                    |
+| `could not read \`itemsFile\``                       | The host cannot see that path — the usual cause is a file written to a temp dir outside the mount. Write it under the workspace.                                                                        |
+| `is not a regular file`                              | The path is a directory, device, or fifo.                                                                                                                                                               |
+| `could not be read as JSON`                          | The file exists and was read, but does not parse. This is YOUR file's shape, not a host problem — check the script that wrote it (a truncated write, a trailing comma, log output mixed into the file). |
+| `must hold a non-empty JSON array of record objects` | It parsed, but is `[]`, an object, or an array of scalars. The file must be `[{…}, {…}]` — the same row objects you would have passed as `items`.                                                       |
 
 Do NOT spawn the MCP bridge yourself. A hand-written JSON-RPC client fails
 invisibly and can leave a partially written collection that nothing reports.
@@ -1196,10 +1201,14 @@ the calendar can place. So format the string, never convert it:
 
 ```js
 // WRONG — appends `Z` and shifts the hours by the generating machine's offset
-{ startAt: new Date(`${day}T08:00`).toISOString() }   // "2026-08-17T15:00:00.000Z"
+{
+  startAt: new Date(`${day}T08:00`).toISOString();
+} // "2026-08-17T15:00:00.000Z"
 
 // RIGHT — the clock you meant, written as the clock
-{ startAt: `${day}T08:00` }                            // "2026-08-17T08:00"
+{
+  startAt: `${day}T08:00`;
+} // "2026-08-17T08:00"
 ```
 
 The conversion is the more expensive half: had the format passed, a Tokyo court's
@@ -1249,7 +1258,7 @@ second line, with the plugin-load errors above it, is what a bug report needs.
 ### Symptoms
 
 - Reading or writing a collection fails with `shared collection unavailable:
-  connect remote-host first`.
+connect remote-host first`.
 - A collection whose `schema.json` declares `"storage": { "type": "firestore" }`
   never appears in the list at all.
 - Reads and writes fail with `permission-denied` from Firestore even though the
@@ -1269,7 +1278,7 @@ The backend deliberately fails loudly instead of returning nothing.
 
 2. **The collection never appears** — discovery REFUSED the schema, and the
    reason is in the server log under `collections` (`schema.json rejected after
-   validation, skipping`). For a shared collection the usual reason is the app
+validation, skipping`). For a shared collection the usual reason is the app
    declaration: `apps/{aid}/collections/{cid}/items` needs an `aid`, which comes
    from `app.json` at the repository root, not from the schema.
 
@@ -1297,6 +1306,156 @@ nor remove documents that other members also read, and removing its records
 first does not unlock it. Retiring the whole app is a Firestore project
 administrator's recursive delete, not something this app does.
 
+## A messaging bridge's bot does not reply, and nothing errors
+
+### Symptoms
+
+The user talks to the bot on Telegram / Slack / LINE / Discord / …, and nothing
+comes back. No error in the server log, none from the bridge. Sending again does
+nothing either.
+
+### First, do NOT say "restart the bridge"
+
+That advice is out of date. Since #3078 the shared client re-reads the token and
+the port after **every failed connection** and rebuilds its socket when the
+server has come back as a different generation. A server restart — new token,
+new port, or both — is handled without touching the bridge.
+
+### The bridge tells you where it went — start there
+
+Every bridge prints its target as it starts — the shared client emits it, so
+this holds for all of them, not only the ones with a banner:
+
+```text
+Connecting to http://127.0.0.1:3099
+```
+
+It prints again each time the bridge follows the server to a new address, so a
+bridge that has outlived a restart has several. **Compare the last one** — the
+earlier lines are where it used to be. Against what the server published:
+
+```bash
+cat "${MULMOCLAUDE_WORKSPACE_PATH:-$HOME/mulmoclaude}/.server-port"
+```
+
+- **They agree** → the address is right; the problem is further in (see below).
+- **They disagree**, and the bridge says `http://localhost:3001` → that bridge
+  is an npm build from before the port-following fix. Reinstall it
+  (`npm i -g @mulmobridge/<platform>@latest`, or `npx @mulmobridge/<platform>@latest`).
+  Check the banner rather than a version number: the banner is the behaviour,
+  and a version is one more thing to keep current.
+
+### `The server has not published a port yet` is waiting, not failing
+
+```text
+The server has not published a port yet — waiting for it rather than guessing.
+```
+
+The server writes `.session-token` before it binds its port, and sandbox setup
+sits in between — a cold start that builds the Docker image can hold there for
+minutes. The bridge deliberately refuses to guess `localhost:3001` while holding
+a freshly minted token, and joins on its own once the port appears. Wait, or
+check that the server is actually starting.
+
+### A bridge that cannot see the workspace needs both variables
+
+Running on another machine, or in a container without the workspace mounted,
+means no `.server-port` and no `.session-token`. Such a bridge needs BOTH:
+
+```bash
+MULMOCLAUDE_API_URL=http://127.0.0.1:<port> \
+MULMOCLAUDE_AUTH_TOKEN=<the same value the server was given> \
+  npx @mulmobridge/<platform>
+```
+
+Two things make this narrower than it looks:
+
+- **The server binds the IPv4 loopback only** (`app.listen(port, "127.0.0.1")`),
+  so a bridge on another machine cannot reach it by naming the host. It needs a
+  tunnel — an SSH port-forward is the usual one — and then
+  `MULMOCLAUDE_API_URL` points at the LOCAL end of that tunnel, which is why the
+  recipe above still says `127.0.0.1`. Do not "fix" this by making the server
+  listen on `0.0.0.0`: there is no TLS on that port, and the bearer token would
+  cross the network in the clear.
+- **`MULMOCLAUDE_AUTH_TOKEN` must be set on the SERVER too**, or it regenerates a
+  new token on every start and the pinned one stops matching.
+
+In a container on the same host, `MULMOCLAUDE_HOST=host.docker.internal` is how
+the sandbox's own hooks reach the parent server; a bridge there needs the same
+treatment, and the workspace mounted if you want it to follow the port.
+
+### Only then, the platform side
+
+- The chat ID is not on the bridge's allowlist — the bot answers
+  `"Access denied"` to a stranger, but an allowlist typo simply drops the
+  message.
+- 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
+  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
+  had no handlers at all, so a missed `await` left only a stack trace) or a kill
+  no handler can catch (`kill -9` / SIGKILL, or the OOM killer).
+
+### What to collect if none of it explains the silence
+
+The bridge's first three lines (they name the transport and the resolved URL),
+the server's `[server] listening port=…` line, and whether
+`<workspace>/.server-port` exists. Those three answer "which server, on which
+port, and did the bridge agree" — which is what every one of these turns out to
+be.
+
+## A webhook bridge exits at startup, or never binds its port
+
+### Symptoms
+
+One of the webhook bridges — `line`, `line-works`, `google-chat`, `messenger`,
+`teams`, `twilio-sms`, `viber`, `webhook`, `whatsapp` — exits immediately after
+being started, printing one of:
+
+```text
+Port 3002 is already in use. Set LINE_BRIDGE_PORT to a free port, or LINE_BRIDGE_PORT=0 to let the OS pick one.
+LINE_BRIDGE_PORT="302a" is not a usable port. Set it to an integer from 0 to 65535 (LINE_BRIDGE_PORT=0 asks the OS for a free port), or unset it to use 3002.
+```
+
+Both name the env var to change, and each bridge has its own — `WEBHOOK_PORT`,
+`TWILIO_WEBHOOK_PORT`, `VIBER_WEBHOOK_PORT` and so on. Read the message rather
+than guessing the name.
+
+### "Already in use" is usually the server, not a second bridge
+
+The server's port walk (3002-3021) covers the whole bridge band (3002-3013), so
+a server that found 3001 busy and moved forward can be sitting on a bridge's
+default. Check what the server actually bound before moving the bridge:
+
+```bash
+cat "${MULMOCLAUDE_WORKSPACE_PATH:-$HOME/mulmoclaude}/.server-port"
+lsof -nP -iTCP:3002 -sTCP:LISTEN
+```
+
+Two ways out, both fine:
+
+- Give the bridge a port outside the server's band: `LINE_BRIDGE_PORT=3200`.
+- Let the OS choose: `LINE_BRIDGE_PORT=0`. The startup banner then names the
+  port it actually got — read the banner, not the env var, when tunnelling to it
+  (`Webhook listening on http://localhost:52431/webhook`).
+
+### Before #3084 both of these were silent
+
+A bridge of that vintage reads its port as `Number(process.env.X) || <default>`
+and calls a bare `app.listen`. So a **typo ran on the default without a word**
+(`302a` → `NaN` → falsy → the default), `X=0` was impossible (falsy too), and a
+busy port surfaced as an unhandled `EADDRINUSE` with no mention of which env var
+to change. If neither message above appears and the bridge simply dies, or it is
+answering on a port you did not ask for, that is the old build: reinstall it
+(`npm i -g @mulmobridge/<platform>@latest`).
+
+A bridge that starts but never replies is a different failure — see "A messaging
+bridge's bot does not reply, and nothing errors" above.
+
 ## `renderShapeScript` says Chromium is not installed
 
 `renderShapeScript` rasterises a ShapeScript model by driving Puppeteer's
@@ -1326,3 +1485,52 @@ The same message with `(launch failed: …)` appended means the browser is
 installed but would not start — usually a sandbox with no permission to
 spawn it. Report the parenthesised reason to the user rather than the
 install hint alone.
+
+## The server refuses to start — "MulmoClaude is already running against this workspace"
+
+### Symptoms
+
+- `yarn dev`, `yarn server` or `npx mulmoclaude` exits immediately with:
+  `MulmoClaude is already running against this workspace at http://localhost:<port>`
+- It happens even with a free port named explicitly (`PORT=3100 yarn dev`).
+
+### Why
+
+Two servers over one workspace overwrite each other's `.session-token`. After
+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
+rather than letting it happen quietly (#3079).
+
+The check reads `<workspace>/.server-port` and probes the port it names, so it
+is about the WORKSPACE, not the port: a busy 3001 held by some other program
+still walks forward as before.
+
+### Fix
+
+Usually the message is right and there is already a server to use — open the URL
+it printed.
+
+To run a genuinely separate second instance, give it its own workspace (no flag
+needed, this is the supported shape):
+
+```bash
+MULMOCLAUDE_WORKSPACE_PATH=~/mulmoclaude-scratch PORT=3100 yarn dev
+```
+
+If the first server was killed hard (`kill -9`, a crashed container) the sidecar
+can name a port something else has since taken; the probe treats a non-MulmoClaude
+answer as "nobody there", so that case does not stop a launch. A stop therefore
+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
+```
+
+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.

package/assets/helps/index.md

@@ -67,7 +67,7 @@ See [Wiki](config/helps/wiki.md) for details on how it works.
 - [Spreadsheet](config/helps/spreadsheet.md) — cell format, formulas, date handling, and format codes for the presentSpreadsheet plugin
 - [presentHtml](config/helps/presenthtml.md) — self-contained HTML rules and the three-`../` relative-path convention used by the presentHtml plugin to keep generated files portable under `file://`
 - [Sandbox](config/helps/sandbox.md) — how the Docker sandbox isolates the agent, what it can access, and how to disable it
-- [Error recovery](config/helps/error-recovery.md) — the lookup the agent reads on tool failures (gh/git/SSH in the sandbox, Marp PDF, registry import, build/workspace, plugin runtime), plus the four-step triage for when a user reports something broken
+- [Error recovery](config/helps/error-recovery.md) — the lookup the agent reads on tool failures (sandbox gh/git/SSH, Marp PDF, registry import, build/workspace, plugin runtime, a bridge gone quiet), plus the triage for a “broken” report
 - [Bug-report FAQ](config/helps/bug-report-faq.md) — symptoms that turn out to be configuration or by design (voice input, push, chat titles, journal, connector tools, preset skills, custom views); says where to read the live value, never what it is
 - [Telegram Bridge](config/helps/telegram.md) — how to talk to MulmoClaude from the Telegram app: creating a bot, starting the bridge, allowlisting chat IDs, commands, and troubleshooting
 - [Remote host](config/helps/remote-host.md) — drive MulmoClaude from a phone at mulmoserver.web.app: Google sign-in connect, host online vs. offline (queued chats, 7-day expiry), photo attachments, and the security model

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 — `yarn dev --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.
+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.
 
 ## 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 both `yarn dev` 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.
+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.
 
 - `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.

package/assets/helps/telegram.md

@@ -7,7 +7,7 @@ This is useful when you want to reach your MulmoClaude away from your computer
 ## How It Works
 
 - You create a **bot** with Telegram's BotFather; it gives you a token.
-- You run a **bridge process** (`yarn telegram`) on the same machine as the MulmoClaude server. The bridge uses your bot token to receive messages from Telegram, forwards them to MulmoClaude over `localhost:3001`, and sends the replies back to the Telegram user.
+- You run a **bridge process** (`yarn telegram`) on the same machine as the MulmoClaude server. The bridge uses your bot token to receive messages from Telegram, forwards them to MulmoClaude over the loopback port the server actually bound, and sends the replies back to the Telegram user. It finds that port itself, and follows it when the server restarts.
 - A short **allowlist** of Telegram chat IDs controls who can talk to the bot. Everyone else gets `"Access denied"`.
 
 Your computer has to be on and connected to the internet for the bot to respond. Close the laptop → the bot goes silent.
@@ -41,7 +41,7 @@ In terminal A, start MulmoClaude:
 yarn dev
 ```
 
-Wait until you see `[server] listening port=3001`.
+Wait until you see `[server] listening port=…`. The number is whatever the server bound: it honours `PORT`, and an implicit default that is already busy walks forward. You do not need to note it — the bridge reads it from the workspace.
 
 In terminal B, start the bridge. Leave the allowlist **empty on purpose** for the first run — you will need to discover your own chat ID before you can add it.
 
@@ -56,9 +56,15 @@ Expected output:
 ```
 MulmoClaude Telegram bridge
 Allowlist: (empty — all chats will be denied)
+Connecting to http://127.0.0.1:<port>
 Connected (<socket id>).
 ```
 
+That third line is the bridge telling you which server it found. If it ever says
+`http://localhost:3001` while `.server-port` says something else, that bridge is
+an old build — see "a messaging bridge's bot does not reply" in the error
+recovery help.
+
 ## Step 3 — Find Your Chat ID and Allowlist It
 
 1. In Telegram, open your new bot (search the username you picked) and send it any message — `hi` works.
@@ -114,7 +120,7 @@ Any other text is treated as a message to the assistant.
 
 ## Troubleshooting
 
-**`Connect error: bearer token rejected`** — MulmoClaude was restarted, so its bearer token changed. Restart `yarn telegram` to pick up the new one. To avoid this, pin `MULMOCLAUDE_AUTH_TOKEN` to the same value on both sides (see `docs/developer.md` §Auth).
+**`Connect error: bearer token rejected`** — MulmoClaude restarted and its bearer token changed. **Do not restart the bridge**: it re-reads the token and the port after a failed connection and reconnects on its own, usually within a second or two. If it is still saying this after that, the server has not finished starting (it writes the token before it binds its port, and a cold start builds the sandbox image in between) — wait for `[server] listening port=…`. Pinning `MULMOCLAUDE_AUTH_TOKEN` on both sides is for a bridge that cannot read the workspace at all, not for this.
 
 **`TELEGRAM_ALLOWED_CHAT_IDS: "foo" is not an integer chat id`** — typo in the allowlist. Chat IDs are plain integers only — no spaces, quotes, or `#` prefix. Negative integers (for group chats) are allowed.
 
@@ -129,7 +135,7 @@ Any other text is treated as a message to the assistant.
 - The bot token is a password. If it leaks, regenerate it via BotFather's `/revoke`.
 - The allowlist is the only thing standing between "my friends" and "every Telegram user on Earth". Keep it current — remove chat IDs when you no longer want that person to have access, and restart the bridge.
 - The bridge logs chat IDs, usernames, and message lengths, but **not** message contents or the bot token. If you need a full audit trail, record it separately.
-- The MulmoClaude bearer token never leaves your machine. The bridge only talks to `localhost:3001`; your friends talk to Telegram's servers, which then talk to your bridge.
+- The MulmoClaude bearer token never leaves your machine. The bridge only ever talks to the IPv4 loopback (`127.0.0.1`), whatever port the server bound; your friends talk to Telegram's servers, which then talk to your bridge.
 
 ## Full Operator Guide
 

package/dist/collection/index.cjs

@@ -1,9 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_dist = require("../dist-CsgSfWwR.cjs");
+const require_dist = require("../dist-Gj7ygaW2.cjs");
 const require_itemId = require("../itemId-CGT2J7YK.cjs");
-const require_promptSafety = require("../promptSafety-Cv-SoTd4.cjs");
+const require_promptSafety = require("../promptSafety-caJWd1ZQ.cjs");
 const require_project = require("../project-C1ep9pvo.cjs");
 const require_iconGlyph = require("../iconGlyph-fSBp6k4J.cjs");
+require("../errorMessage-CT-va_Pv.cjs");
 //#region src/collection/core/presentCollection.ts
 var TOOL_NAME = "presentCollection";
 /** Stamp a host's opaque project scope onto a card payload. The ONLY way a