mulmoterminal 2.5.3 → 2.7.0

package/README.md

@@ -24,7 +24,7 @@ color-coded so you see at a glance which are **working**, which **need you**, an
 ping to your phone when a task finishes. One `npx` command, no Electron, no config.
 
 ```bash
-npx mulmoterminal        # starts on http://localhost:34567 and opens your browser
+npx mulmoterminal@latest        # starts on http://localhost:34567 and opens your browser
 ```
 
 > **Something looks wrong?** Type `/mulmoterminal-bug-report` in any MulmoTerminal session. The
@@ -86,11 +86,20 @@ output you haven't seen) — driven by Claude/Codex activity hooks the server in
 *Besides the grid there's a **single view** for focusing on one agent: the conversation/terminal on the left, and a **GUI panel** ("Canvas") on the right where the agent's tool calls render as documents, forms, charts, images, and HTML — not just printed text. Switch between the two with the chat / grid icons in the toolbar. **The app opens on the grid** (`/`); the single view has its own URL, `/chat`, so you can bookmark either.*
 
 **Inserting a file path** — like a native terminal, you can put a file's absolute path into
-the prompt: **drag a file** onto the terminal (works where the browser exposes the path via
-`file://` — Firefox/Safari), or click the **📎 file button** in the terminal header, which
-asks the local server to open the OS file dialog and inserts the chosen path (works in every
-browser, including Chrome). The path is inserted at the cursor — it is not submitted, so you
-can review it first.
+the prompt: **drag a file** onto the terminal, or click the **file button** in the terminal
+header, which asks the local server to open the OS file dialog and inserts the chosen path. The
+path is inserted at the cursor — it is not submitted, so you can review it first.
+
+A drag inserts the file's **own** path where the browser exposes one via `file://`
+(Firefox/Safari), so editing it afterwards edits the file you dropped. Where the browser
+withholds it — **Chrome**, and every browser when MulmoTerminal is open **from another
+machine**, where a local path would name nothing on the host — the file's bytes are sent
+instead, saved to a private per-session directory under the OS temp dir, and *that* path is
+inserted. The session is granted that directory at launch (Claude Code's `--add-dir`, bind-mounted
+in the sandbox too), so the agent reads it without a permission prompt; the copies are removed
+when the session ends, and any left by a crash are swept at the next start. Up to 110 MiB per
+file — the same ceiling as a phone attachment. **A session already running when you upgrade
+was launched without that grant**, so drops into it still prompt; new sessions don't.
 
 <a id="clicking-a-file-path"></a>
 
@@ -129,6 +138,51 @@ dotfiles are server-only. The 45 extensions both sides agree on live in
 
 ---
 
+## What people say after switching
+
+> These are experiences reported by users who moved over from an IDE or a split terminal —
+> not benchmarks, and not claims we measured. Your setup may differ.
+
+### "It stopped eating my memory"
+
+Keeping several agents apart by opening several IDE windows is expensive: each one brings its own
+editor, language server, extensions and file watchers. One user reported a **64 GB machine
+stuttering** under that load, and running smoothly after moving over — here the agents are PTYs on
+a server and the UI is browser tabs.
+
+### "I stopped answering the wrong agent"
+
+Six panes of scrolling text look identical. Users have described **typing a reply into another
+agent's terminal**, and losing track of what they had asked in the first place. As one put it, the
+windows all look the same, so switching between them costs time just to work out what you are
+looking at.
+
+The problem isn't attention — it's that N identical panes means holding N contexts in your head.
+Colour-coded state, a name badge and a per-directory colour move that onto the screen instead.
+
+### "Watching many and reading one stopped being a trade-off"
+
+Splitting a terminal six ways leaves every pane too small to read a long answer without constant
+scrolling and resizing — one user described exactly that with a 4,000-character reply. So you
+quietly accept worse reading every time you add an agent.
+
+**Grid ↔ enlarge removes that.** Watch all of them, then blow one up and read it properly — the
+cockpit roster keeps the rest in view as text while you do.
+
+### "My existing sessions came with me"
+
+Sessions resume as-is — same `claude --resume`, same transcripts. Point it at a directory you
+already work in and your history is there. Nothing to migrate, nothing to redo. One user said this
+alone made the switch worth it, having previously lost context to killed sessions.
+
+---
+
+**You don't need ten agents for this to pay off.** Users have reported the switch being worth it at
+**one to three** parallel sessions. The wins above are about not losing track, not about running
+more.
+
+---
+
 ## Install & run
 
 Needs **Node ≥ 22.9**, plus these CLIs on your `PATH`:
@@ -146,17 +200,17 @@ Needs **Node ≥ 22.9**, plus these CLIs on your `PATH`:
 
 The server starts without any of the non-required rows; you just lose that row's feature,
 and the header/panel for it says so. `git` and `gh` are marked required because losing them
-costs whole views rather than one button. `npx mulmoterminal init` (below) reports which of
+costs whole views rather than one button. `npx mulmoterminal@latest init` (below) reports which of
 these it can find.
 
 ```bash
-npx mulmoterminal           # start on http://localhost:34567 and open the browser
+npx mulmoterminal@latest           # start on http://localhost:34567 and open the browser
 # or install globally:
 npm install -g mulmoterminal
 mulmoterminal
 ```
 
-**First-run setup (optional).** `npx mulmoterminal init` checks your environment (Node ≥ 22.9
+**First-run setup (optional).** `npx mulmoterminal@latest init` checks your environment (Node ≥ 22.9
 and every CLI in the table above), seeds the launcher's **directory
 presets** from the projects in your Claude Code history, and writes `~/.mulmoterminal/config.json`.
 It's **idempotent** — re-run it any time to refresh the presets; it overwrites the managed parts
@@ -166,7 +220,7 @@ and keeps your other settings. When `claude` is installed it can hand off to the
 **Google account (optional).** Link a Google account to enable the chat's `google` tool and the
 phone's `google.calendar.*` commands: read/create events on any calendar (not just your primary),
 list the calendars you've subscribed to, and read the colour palettes. Sign in from
-**Settings → Google account**, or run `npx mulmoterminal google login` — the CLI is the fallback
+**Settings → Google account**, or run `npx mulmoterminal@latest google login` — the CLI is the fallback
 for when you're driving MulmoTerminal from another machine, since consent finishes on a loopback
 listener and needs a browser **on the host**. Either way it needs a Desktop OAuth client JSON saved
 as `~/.secrets/client_secret_*.json`; the refresh token lands in `~/.config/mulmo/google-token.json`
@@ -200,11 +254,11 @@ directory you run the command from), `--port <n>` (default 34567), `--no-open`,
 `--version`, `--help`.
 
 ```bash
-npx mulmoterminal --cwd ./my-project   # work in a specific directory
+npx mulmoterminal@latest --cwd ./my-project   # work in a specific directory
 ```
 
 The published package ships the server (run via `tsx`) plus the pre-built web UI;
-`npx mulmoterminal` checks for the `claude` CLI, picks a free port, starts the
+`npx mulmoterminal@latest` checks for the `claude` CLI, picks a free port, starts the
 server, and opens the browser. For local development from a clone, see
 [Running](#running).
 
@@ -426,7 +480,7 @@ Requires **Node ≥ 22.9** (uses `node --env-file-if-exists`) and the `claude` C
 ## Configuration
 
 The server is configured entirely through environment variables, optionally
-loaded from a `.env` file. `npx mulmoterminal` reads the `.env` **in the
+loaded from a `.env` file. `npx mulmoterminal@latest` reads the `.env` **in the
 directory you run it from**; the npm scripts read the one in the repo root. The
 `.env` is optional — every variable below has a default, so the server runs
 without one.
@@ -441,7 +495,7 @@ the `claude` / `codex` sessions themselves.
 | `PORT`        | `34567`        | Backend HTTP/WebSocket port (prod: the URL you open). |
 | `CLIENT_PORT` | `6856`         | Vite dev-server port (dev only: the URL you open with `yarn dev`). |
 | `CLAUDE_BIN` | `claude`       | The Claude Code binary to spawn. On Windows a bare name is resolved on `PATH` before it reaches the PTY layer (which matches file names exactly): to the `.exe` when there is one, otherwise to the `.cmd` shim an npm-global install leaves, run through `cmd.exe`. |
-| `CLAUDE_CWD` | current dir    | Working directory each `claude` PTY runs in; determines which project's sessions the sidebar lists. Via `npx mulmoterminal` it defaults to the directory you ran the command from (override with `--cwd <dir>`, relative allowed); when the server is run directly it falls back to `~/mulmoclaude`. A value read from `.env` must be an absolute path (`~` is not expanded). |
+| `CLAUDE_CWD` | current dir    | Working directory each `claude` PTY runs in; determines which project's sessions the sidebar lists. Via `npx mulmoterminal@latest` it defaults to the directory you ran the command from (override with `--cwd <dir>`, relative allowed); when the server is run directly it falls back to `~/mulmoclaude`. A value read from `.env` must be an absolute path (`~` is not expanded). |
 | `CLAUDE_PERMISSION_MODE` | `auto` | Permission mode passed to each `claude` spawn. |
 | `MT_TITLE_MODEL` | `haiku` | Model used for the cell header's AI title (a cheap/fast model summarizing the recent turns). Accepts a `--model` alias or a full model id. |
 | `CODEX_BIN`  | `codex`        | The Codex CLI binary to spawn. |
@@ -491,6 +545,7 @@ The Settings modal (⚙) persists per-user UI choices to `~/.mulmoterminal/confi
 | `decisionDigest` | Keep a **Markdown digest of the decisions this project's sessions asked for**, refreshed at startup and every few hours, so an agent can read what has already been decided before asking something similar. Written to `~/.mulmoterminal/decisions/<project>.md` (never into your repository) and served to agents by the bundled `mulmoterminal-decisions` skill. **Off by default** — it is a vision-stage idea, and it writes a file that would otherwise not exist. The digest holds dated facts, never inferred rules. |
 | `issueWorkComments` | Let a cell **comment on the issue it is working on**: once when it starts, and again when its PR merges (closing the issue if GitHub has not already). The comment names the working **directory** it happened in — the folder name only, never the path — so a reader can tell which clone. **Off by default**; it writes to GitHub, often on somebody else's issue. Needs `gh` logged in. See the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#issue-work-comments). |
 | `prWorkdirFooter` | Ends a PR body with `work in <clone>` — the directory name of the clone the work happened in, so a PR says which of several side-by-side checkouts produced it. Applies to **both** paths that open PRs here: **⧉ Open PR** appends it to the PR it creates, and every Claude session is told to end the bodies it writes with the same line (the name is resolved by the server, so a session inside a managed worktree still names the main checkout). **On by default**; set `false` to opt out — read per PR and per session spawn, so no restart is needed (there is no Settings control for it). Appending is idempotent: an existing PR never gets a second copy. |
+| `appendSystemPrompt` | Whether a spawned Claude session is asked to end a reply with a **closing summary** — what was asked, what was achieved, what was not (see [Closing summary](#closing-summary)). **On by default**; set `false` to opt out, and a directory's `.mulmoterminal.json` outranks this. Read per spawn, so no restart is needed (there is no Settings control for it), though a session already running keeps what it was launched with. `true` / `false` only. |
 | `fontFamily` | The **terminal font** every session renders in — a CSS font-family stack, e.g. `"'Cica', 'MS Gothic', monospace"`. No Settings UI: edit the file, then **restart** (this config is read once at startup). Unset uses the built-in stack (JetBrains Mono / Fira Code / Menlo / Consolas, then CJK faces for Japanese, Korean and Chinese). Unlike the per-browser font **size**, this is one value for the whole host — it names fonts, and which fonts exist is a property of the machine. A directory can override it. See the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#font-family). |
 
 Every MulmoTerminal on the machine shares this one file, so an older build could save over a key a
@@ -613,7 +668,8 @@ malformed file is ignored.
   "fontFamily": "'Cica', monospace",    // terminal font stack; overrides the global config
   "orderPriority": 10,                  // rank in the grid's "priority" ordering (lowest first)
   "sound": "./.mulmoterminal/alert.mp3", // attention sound, RELATIVE to this directory
-  "sounds": { "command-failed": "preset:gong" } // per-notification-kind override
+  "sounds": { "command-failed": "preset:gong" }, // per-notification-kind override
+  "appendSystemPrompt": false           // no closing summary here; omit to follow the global setting
 }
 ```
 
@@ -638,6 +694,7 @@ malformed file is ignored.
 | `fontFamily` | CSS font-family stack for this directory's terminals, overriding the global `fontFamily`. Use the names as your OS lists them (`"'Cica', 'MS Gothic', monospace"`). An unusable stack is ignored whole rather than half-applied; `monospace` is appended if you name no generic family. Prefer fonts whose fullwidth glyphs are exactly twice the Latin width, or box-drawing frames tear. |
 | `sound`      | Attention sound for this directory's sessions, a path **relative to the directory** (served at `GET /api/dir-sound`). The fallback for every kind. |
 | `sounds`     | Per-kind override of `sound`: `{ "command-failed": "preset:gong" }`. Each value is a `preset:<id>` or a directory-relative path, under the same confinement. |
+| `appendSystemPrompt` | Whether this directory's Claude sessions are asked to end a reply with a **closing summary** (see [Closing summary](#closing-summary)). Omit to follow the global `appendSystemPrompt`, which is on; `true` / `false` here outranks it. Read per spawn, so a new session in this directory picks up an edit without a restart. |
 | `addDirs`    | Extra directories this project's Claude sessions may read and edit — the terminal-side equivalent of opening several folders in one VS Code workspace, via Claude Code's `--add-dir`. Relative entries resolve against **this file's directory** (`"../shared-lib"`), a path that doesn't exist is dropped, max 16. In the Docker sandbox each one is bind-mounted too, so the grant is real inside the container — which widens the sandbox on purpose. Claude only: codex has no equivalent flag and ignores the key. |
 
 **Security.** `sound` and every `sounds` entry are directory-relative paths only — absolute
@@ -1191,6 +1248,7 @@ same-origin-guarded.
 | `POST /api/translation` | Runtime UI-string translation. |
 | `GET /api/remote-host/status` · `POST /api/remote-host/{connect,disconnect}` | Companion phone-client link. Each response carries the command channel's `health` (`online` / `reconnecting` / `offline`, plus the last listener error), so the toolbar shows a dropped channel instead of the last state it happened to fetch. |
 | `POST /api/open-dir` · `POST /api/pick-file` | Reveal a dir in Finder/Explorer; OS file-picker → path (`{ directory: true }` opens the folder picker — used by the launcher's Working-directory 📁 button). |
+| `POST /api/session/:id/drop` | A dropped file whose path the browser withheld. **Raw bytes**, not JSON, under the file's own content type (base64 in JSON would cap real files near 18 MB, and a dropped `.json` would be parsed as a document); the original name rides percent-encoded in `x-drop-filename` and is used for its **suffix only**. Answers `{ path }` — absolute, inside the private per-session directory the session was granted at launch. 110 MiB cap; 404 for a session this server isn't running. |
 
 The phone itself uses **none** of these routes — it reaches the host over Firestore command
 docs, not HTTP. Every command it can send, and the shapes it gets back, are in
@@ -1359,6 +1417,16 @@ Key rules:
 - Brand-new sessions appear in the sidebar **immediately** (before their `.jsonl`
   exists) via the in-memory `knownSessions` registry + a `created` push; an
   unused one disappears when its PTY is reaped.
+- **Background workers get their own filter.** A session nobody started by hand —
+  a collection's scheduled refresh, or a plugin's `spawnBackgroundChat`
+  `hidden: true` — is listed under the **Background** chip instead of among the
+  chats, so a refresh schedule doesn't fill the history. It stays openable (a
+  MulmoTerminal session is a live terminal, so a row you can't reach is a process
+  you can't stop), and it is put on the same count+age retention as the
+  scheduler's own sessions. The chip appears only when there is one to show. A
+  **manual** collection Refresh is a normal visible session — unchanged. The
+  marking is persisted (`~/.mulmoterminal/background-sessions.json`), so a worker
+  stays out of the chat list after it finishes and after a restart.
 
 ---
 
@@ -1400,7 +1468,17 @@ placed last with nothing after it.
 
 It is deliberately **not** written on every turn: mid-work replies and short factual answers
 carry no standing request, and a summary that always appears stops being read. The wording
-lives in `server/agents/session-summary-prompt.ts`; there is no setting to turn it off.
+lives in `server/agents/session-summary-prompt.ts`.
+
+**On by default, and switchable off** with `appendSystemPrompt: false` — in
+`~/.mulmoterminal/config.json`, or in a directory's `.mulmoterminal.json`, which outranks the
+global value. Read per spawn, so no restart is needed; a session already running keeps what it
+was launched with. Nothing in the app parses what the summary says, so turning it off costs no
+feature — the roster and push notifications simply show the raw tail of the reply.
+
+Which sections `--append-system-prompt` ends up carrying is decided in
+`server/agents/appended-prompt.ts`: this one and the `prWorkdirFooter` clone line are separate
+settings on the same flag, and with both off the flag is not passed at all.
 
 Passed inline rather than as `--append-system-prompt-file` for the same reason `--settings`
 is: the sandbox spawn runs in a container that cannot read a host path.
@@ -1419,12 +1497,13 @@ has its `/` and `.` characters replaced with `-` (e.g.
 A session's display **title** is derived by scanning its JSONL for, in order of
 preference:
 
-1. a live **AI title** the server generated for the session this run (see below),
-2. else the latest `ai-title` record's `aiTitle` (e.g. written by MulmoClaude),
-3. else the latest `last-prompt` record's `lastPrompt`,
-4. else the first real user message (slash/local-command wrappers like
+1. the **session note** the user wrote (see below),
+2. else a live **AI title** the server generated for the session this run (see below),
+3. else the latest `ai-title` record's `aiTitle` (e.g. written by MulmoClaude),
+4. else the latest `last-prompt` record's `lastPrompt`,
+5. else the first real user message (slash/local-command wrappers like
    `<local-command-…>` are skipped),
-5. else `"(untitled session)"`.
+6. else `"(untitled session)"`.
 
 In-memory sessions not yet persisted show as `"New session"` until their file
 appears, at which point the on-disk title takes over.
@@ -1444,6 +1523,23 @@ ack (so the raw last prompt would be stale), or every few turns to keep a long s
 title current. The title lives in memory (never written into Claude's own transcript); a
 resumed session falls back to any on-disk `ai-title`.
 
+### Session note
+
+Every tier above says what the **agent** said, which stops answering "which cell is this?"
+once several sessions are open. So a cell header also takes a **note you write yourself**: the
+pencil button beside the header text opens a one-line box (Enter saves, Esc cancels, clicking
+away saves). While a note is set it *replaces* the header line — the title it displaced stays in
+the tooltip — and it becomes the session's title in the sidebar list and on the phone's roster
+too, so one session goes by one name everywhere.
+
+Notes are capped at 200 characters and folded to a single line. They are stored per **session
+id** in `~/.mulmoterminal/session-memos.jsonl` and survive both the session being reaped and a
+server restart: resume the session and the note comes back. Saving one publishes it on the
+`sessions` channel, so every other open tab and the phone update without asking.
+
+`POST /api/session/:id/memo` with `{ "text": "…" }` writes one; an empty `text` erases it. The
+route answers with the **stored** text, which is what a reload will show.
+
 ---
 
 ## Project structure

package/bin/cli-args.d.ts

@@ -11,3 +11,8 @@ export declare const MIN_NODE_LABEL: string;
 export declare function nodeMeetsMinimum(version: string): boolean;
 export declare function serverNodeArgs(serverEntry: string, launchDir: string): string[];
 export declare function serverSpawnEnv(env: Record<string, string | undefined>, port: number, cwd: string): Record<string, string | undefined>;
+export interface RunningInstance {
+  pid: number;
+  port: number | null;
+}
+export declare function runningInstancesPrompt(instances: readonly RunningInstance[]): string;

package/bin/cli-args.js

@@ -108,6 +108,26 @@ export function saysYes(answer) {
  * updates never cross — so the instance that did not start a session shows a frozen history
  * for it (#611).
  */
+/**
+ * The question asked when another server is ALREADY RUNNING, whatever port this one was told to
+ * use (#1061).
+ *
+ * `secondInstancePrompt` below only fires when the wanted port is taken, so `--port <free>`
+ * started a second instance in silence — which is how eight live sessions had their settings
+ * deleted by a peer's boot. The clash is a symptom; the shared `~/.mulmoterminal` is the thing
+ * that is not supported, and that is true at any port.
+ */
+export function runningInstancesPrompt(instances) {
+  const where = instances.map((i) => (i.port === null ? `pid ${i.pid}` : `http://localhost:${i.port}`)).join(", ");
+  const subject = instances.length === 1 ? "MulmoTerminal is already running" : `${instances.length} MulmoTerminal servers are already running`;
+  return [
+    `${subject} (${where}).`,
+    "  Running more than one is NOT a supported setup: they share ~/.mulmoterminal,",
+    "  so they can overwrite each other's session state.",
+    "Start another one anyway? [y/N] ",
+  ].join("\n");
+}
+
 export const SECOND_INSTANCE_NOTE = [
   "  Note: both share ~/.mulmoterminal. A session's tool history does not live-update",
   "  in the instance that did not start it.",

package/bin/instances.d.ts

@@ -0,0 +1,10 @@
+export interface InstanceEntry {
+  pid: number;
+  port: number | null;
+  startedAt: number | null;
+}
+export declare function instancesDir(): string;
+export declare function isProcessAlive(pid: number): boolean;
+export declare function registerInstance(port: number, pid?: number, startedAt?: number): () => void;
+export declare function liveInstances(excludePid?: number): InstanceEntry[];
+export declare function earliestStartedAt(instances: readonly InstanceEntry[]): number | null;

package/bin/instances.js

@@ -0,0 +1,115 @@
+// Which MulmoTerminal servers are running right now (#1061).
+//
+// Two things need this answer and neither could get it before. The launcher asks so it can say
+// "one is already running" no matter which port the new one was told to use — the port probe only
+// notices a clash on the SAME port, so `--port <free>` started a second instance in silence. And
+// the server asks before deleting orphaned session settings: without tmux, "nothing survived the
+// last lifetime" is only true for the process that OWNED that lifetime, so a second instance was
+// reading a peer's live files as leftovers and removing them.
+//
+// Shared as plain JS rather than through common/ because the launcher runs on bare node before
+// any TypeScript exists — the same reason bin/update-check.js is shaped this way, and the server
+// imports it the same way.
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+export const instancesDir = () => path.join(homedir(), ".mulmoterminal", "instances");
+
+const entryFile = (pid) => path.join(instancesDir(), `${pid}.json`);
+
+/** Whether a pid belongs to a process that still exists. Signal 0 performs the permission and
+ *  existence checks without delivering anything; EPERM means it IS there, just not ours. */
+export function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === "EPERM";
+  }
+}
+
+/** Announce this process, and hand back the removal. Best-effort throughout: not being able to
+ *  say hello is not a reason to fail a boot, and a crash simply leaves an entry whose pid no
+ *  longer resolves — which every reader already has to handle. */
+export function registerInstance(port, pid = process.pid, startedAt = Date.now()) {
+  const file = entryFile(pid);
+  try {
+    mkdirSync(instancesDir(), { recursive: true, mode: 0o700 });
+    // Written elsewhere and renamed into place: a reader that catches us mid-write would see a
+    // truncated entry, and "I could not parse it" must never be how a LIVE peer disappears from
+    // the registry (Codex review). rename is atomic for a reader on the same directory.
+    const tmp = `${file}.${startedAt}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ pid, port, startedAt }), { encoding: "utf8", mode: 0o600 });
+    renameSync(tmp, file);
+  } catch {
+    return () => {};
+  }
+  return () => {
+    try {
+      rmSync(file, { force: true });
+    } catch {
+      // Left behind; the next reader drops it as stale.
+    }
+  };
+}
+
+const parseEntry = (raw) => {
+  try {
+    const entry = JSON.parse(raw);
+    if (!entry || typeof entry !== "object") return null;
+    const { pid, port, startedAt } = entry;
+    if (!Number.isInteger(pid) || pid <= 0) return null;
+    return { pid, port: Number.isInteger(port) ? port : null, startedAt: Number.isFinite(startedAt) ? startedAt : null };
+  } catch {
+    return null;
+  }
+};
+
+/** Every OTHER running server, newest entry first. Entries whose process is gone are deleted as
+ *  they are found: a crash cannot clean up after itself, and leaving them would make a lone
+ *  instance believe it has company forever. */
+export function liveInstances(excludePid = process.pid) {
+  let names;
+  try {
+    names = readdirSync(instancesDir());
+  } catch {
+    return []; // never registered on this machine
+  }
+  const live = [];
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    const file = path.join(instancesDir(), name);
+    let entry;
+    try {
+      entry = parseEntry(readFileSync(file, "utf8"));
+    } catch {
+      continue; // being written right now, or unreadable — say nothing about it
+    }
+    // Only a positively-identified dead owner earns removal. An entry we could not parse is one
+    // we know nothing about — deleting it on that basis is how a live peer gets erased, which is
+    // the very failure this registry exists to prevent (Codex review).
+    if (entry === null) continue;
+    if (!isProcessAlive(entry.pid)) {
+      try {
+        rmSync(file, { force: true });
+      } catch {
+        // not ours to remove; harmless
+      }
+      continue;
+    }
+    if (entry.pid !== excludePid) live.push(entry);
+  }
+  return live.sort((a, b) => (b.startedAt ?? 0) - (a.startedAt ?? 0));
+}
+
+/** When the EARLIEST of the given instances started, or null when there are none.
+ *
+ *  This is the cutoff the settings prune needs: a file written before every live peer began
+ *  cannot belong to one of them, so it is safe to treat as a leftover. A file written after that
+ *  moment might be a peer's, and a maybe is not good enough to delete somebody's live state. */
+export function earliestStartedAt(instances) {
+  const times = instances.map((i) => i.startedAt).filter((t) => typeof t === "number");
+  return times.length ? Math.min(...times) : null;
+}

package/bin/mulmoterminal.js

@@ -22,12 +22,14 @@ import {
   portInUseMessage,
   saysYes,
   secondInstancePrompt,
+  runningInstancesPrompt,
   SECOND_INSTANCE_NOTE,
   nodeMeetsMinimum,
   MIN_NODE_LABEL,
   serverNodeArgs,
   serverSpawnEnv,
 } from "./cli-args.js";
+import { liveInstances } from "./instances.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_DIR = join(__dirname, "..");
@@ -155,7 +157,10 @@ async function runInit(initArgs) {
     return;
   }
   if (hasClaude) log("Later: run `claude` in any project and use  /mulmoterminal-config");
-  log("Setup done. Start MulmoTerminal:  npx mulmoterminal");
+  // Pinned to @latest: an unpinned `npx` reuses whatever it already has cached, so the very
+  // command printed for someone to type next would start an older version than the one they
+  // just set up with.
+  log("Setup done. Start MulmoTerminal:  npx mulmoterminal@latest");
 }
 
 // `npx mulmoterminal google <command>` — Google account linking. Consent needs a
@@ -240,6 +245,20 @@ function findEphemeralPort() {
   });
 }
 
+// Ask about an ALREADY-RUNNING server, whatever port this one will use. Declining exits 0: the
+// user answered the question that was asked, which is not a failure.
+async function confirmNoRunningInstance() {
+  const running = liveInstances();
+  if (running.length === 0) return;
+  if (!process.stdin.isTTY) {
+    log(runningInstancesPrompt(running).replace(/\nStart another one anyway\? \[y\/N\] $/, ""));
+    log(SECOND_INSTANCE_NOTE);
+    return;
+  }
+  if (!(await promptYesNo(runningInstancesPrompt(running)))) process.exit(0);
+  log(SECOND_INSTANCE_NOTE);
+}
+
 async function choosePort(requested, explicit) {
   if (await isPortFree(requested)) return requested;
   // No SILENT fallback: starting a second server on another port without saying so is how
@@ -319,7 +338,7 @@ function runServer(port, noOpen, cwd, onChild) {
 
 function printHelp() {
   console.log(`
-Usage: npx mulmoterminal [command] [options]
+Usage: npx mulmoterminal@latest [command] [options]
 
 Commands:
   (none)            Start the server (default)
@@ -393,6 +412,12 @@ async function main() {
   // The probe above can still lose to something binding the port in the same instant, in
   // which case the server exits 75 and runServer returns. Same answer as the probe: say who
   // has it rather than moving to a port nobody asked for.
+  // Before anything about PORTS: is one already running at all? A clash on the same port is only
+  // the visible half — `--port <free>` used to start a second instance in silence, and the two
+  // then share ~/.mulmoterminal (#1061). Non-TTY says it and carries on rather than hanging on a
+  // prompt nobody can answer: a script that asked for a server should still get one.
+  await confirmNoRunningInstance();
+
   const port = await choosePort(requestedPort, portExplicit);
   await runServer(port, noOpen, cwd, (c) => {
     child = c;

package/common/dirConfigSource.ts

@@ -30,6 +30,7 @@ export const DIR_CONFIG_KEYS = [
   "provider",
   "model",
   "addDirs",
+  "appendSystemPrompt",
 ] as const;
 
 export interface DirConfigSource {
@@ -58,6 +59,10 @@ export interface DirConfigExtras {
   model: string | null;
   skills: string[] | null;
   addDirs: string[] | null;
+  // Tri-state on purpose: `false` is a setting this file made, and the preview has to show it as
+  // one. Carried here because a boolean cannot be read back off the per-cell config the way a
+  // colour can — without it the panel reports the file as setting nothing at all.
+  appendSystemPrompt: boolean | null;
   buttonLabels: string[];
   chipLabels: string[];
 }
@@ -67,6 +72,7 @@ export const EMPTY_DIR_CONFIG_EXTRAS: DirConfigExtras = {
   model: null,
   skills: null,
   addDirs: null,
+  appendSystemPrompt: null,
   buttonLabels: [],
   chipLabels: [],
 };

package/common/dropUpload.ts

@@ -0,0 +1,16 @@
+// The wire contract for sending a dropped file's bytes to the host, when the browser withheld
+// its path. Both sides decide from these: the server enforces the cap and the browser refuses
+// early rather than spending a long upload on bytes that will be rejected at the end.
+
+// Matches the phone's attachment ingest, so the same file is accepted whichever way it arrives.
+export const MAX_DROP_BYTES = 110 * 1024 * 1024;
+
+// A header, not a body field, because the body IS the file. Percent-encoded by the sender: a
+// header is latin-1 and real filenames are not, so a Japanese name sent raw arrives mangled.
+export const DROP_FILENAME_HEADER = "x-drop-filename";
+
+// What POST /api/session/:id/drop answers with on success. `path` is absolute, inside the
+// directory that session was granted at spawn time.
+export interface DropUploadResponse {
+  path: string;
+}

package/common/finiteNumber.ts

@@ -0,0 +1,9 @@
+/** The guard both sides use before reading a NUMBER off parsed JSON. Null — never 0 — for
+ *  anything that is not a real number, because the callers are gauges and costs where a missing
+ *  value and a zero mean opposite things (see common/rateLimits.ts).
+ *
+ *  `Number.isFinite` rather than a bare typeof: `JSON.parse` cannot produce NaN or Infinity, but
+ *  these values also arrive from arithmetic on parsed fields, and NaN reaching a gauge renders as
+ *  an empty bar rather than as an error. Sibling of common/isRecord.ts, which exists because the
+ *  same one-liner had been hand-copied into 29 files. */
+export const finiteNumber = (value: unknown): number | null => (typeof value === "number" && Number.isFinite(value) ? value : null);

package/common/quickCommands.ts

@@ -9,5 +9,7 @@ import type { SessionAgent } from "./sessionAgent.js";
 export interface QuickCommand {
   label: string;
   text: string;
-  agents?: SessionAgent[];
+  // `| undefined` because quickCommandSchema `satisfies z.ZodType<QuickCommand>`, and
+  // Zod's `.optional()` produces `T | undefined`, not "key may be absent".
+  agents?: SessionAgent[] | undefined;
 }

package/common/rateLimits.ts

@@ -8,6 +8,8 @@
 // because the plan is API-key billed, because no session has answered yet, or because upstream
 // dropped the field (anthropics/claude-code#40094). None of those are zero, and a gauge reading
 // 0% when the truth is 83% is the worst thing this data can do.
+import { isRecord } from "./isRecord.js";
+import { finiteNumber } from "./finiteNumber.js";
 
 export interface RateLimitWindow {
   usedPercentage: number; // 0-100, fractional
@@ -19,9 +21,6 @@ export interface RateLimits {
   sevenDay: RateLimitWindow | null;
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null;
-const finiteNumber = (value: unknown): number | null => (typeof value === "number" && Number.isFinite(value) ? value : null);
-
 export function parseRateLimitWindow(raw: unknown): RateLimitWindow | null {
   if (!isRecord(raw)) return null;
   const used = finiteNumber(raw.usedPercentage);

package/common/remoteHostHealth.ts

@@ -6,6 +6,12 @@
 //   reconnecting — it died and is being re-subscribed with backoff (self-healing)
 //   offline      — re-subscribing stopped helping, or nothing is connected at all;
 //                  recovering needs a re-auth from the browser's parked session
+//
+// @mulmoclaude/core declares the same three fields, and the server hands this straight to core's
+// resilient runner — structurally, so the two cannot disagree without a type error. Kept here
+// anyway because the BROWSER renders it: core exposes the type only from `remote-host`, whose
+// entry imports firebase/firestore, and pulling that into the Vue bundle to describe three fields
+// is the wrong trade. If core ever gives the health type its own subpath, delete this and import.
 
 import { isRecord } from "./isRecord.js";
 export const RUNNER_HEALTH_STATES = ["online", "reconnecting", "offline"] as const;

package/common/sessionMemo.ts

@@ -0,0 +1,44 @@
+// The user's own one-line note on a session, as BOTH sides agree it should look.
+//
+// Shared because two layers decide from it and must not drift: the input box caps what can be
+// typed, and the server caps what it stores. A client-only cap is no cap at all — the route is
+// reachable directly — and a server-only one silently truncates what the user was shown typing.
+
+export const MEMO_MAX_LENGTH = 200;
+
+// `Cc` is the C0/C1 control block exactly: the newlines, tabs and terminal escapes a paste can
+// carry, and nothing else. `\p{C}` would also take the format category, which is where the
+// zero-width joiner holding a multi-part emoji together lives.
+const CONTROL_CHARS = /\p{Cc}/gu;
+
+/**
+ * A memo as it is stored and shown, or "" for "there is none".
+ *
+ * "" is the ERASE value, not a memo that happens to be empty: the store deletes on it and the
+ * header falls back to the AI title. That is why whitespace-only input normalizes to "" — a
+ * user who selects all and types a space means to clear the note.
+ */
+export function normalizeMemo(raw: unknown): string {
+  if (typeof raw !== "string") return "";
+  const oneLine = raw.replace(CONTROL_CHARS, " ").replace(/\s+/gu, " ").trim();
+  // By code point, so the cap never lands between the halves of a surrogate pair and leaves a
+  // lone half in a JSON line that every later reader has to carry.
+  return [...oneLine].slice(0, MEMO_MAX_LENGTH).join("");
+}
+
+/**
+ * The name a session goes by: the user's memo when there is one, else the best generated title
+ * on offer, else "" for the caller's own sentinel.
+ *
+ * Shared because THREE surfaces answer this question — the grid cell's header, the sidebar row
+ * and the phone's roster — and a session that goes by two different names depending on where it
+ * is looked at is worse than one with no name at all. Each caller passes its own tiers, in its
+ * own order; what lives here is the one rule they agree on, that the line the USER wrote outranks
+ * everything the agent said.
+ *
+ * Truthiness, not nullishness: an empty tier means "nothing usable here, keep looking", never
+ * "show blank".
+ */
+export function sessionDisplayName(memo: string | null | undefined, ...generated: (string | null | undefined)[]): string {
+  return [memo, ...generated].find((candidate) => !!candidate) ?? "";
+}