mulmoterminal 2.6.0 → 2.8.0

package/README.md

@@ -1,6 +1,6 @@
 # mulmoterminal
 
-**Run a whole team of coding agents from your browser — and actually keep up with them.**
+**Run multiple Claude Code and Codex sessions in parallel — and see which one needs you.**
 
 A **browser terminal** for **parallel AI coding agents**: several **Claude Code** and **Codex**
 sessions side by side, each in its own cell, with the one that needs you marked in colour. Vibe
@@ -14,6 +14,9 @@ and a **phone push** reaches you when a turn finishes.
   view, everyday workflows, the full feature list, configuration, and mobile push notifications.
 - **ユーザーガイド:** [日本語](https://receptron.github.io/mulmoterminal/guide/ja/) —
   グリッドの使い方・日々のワークフロー・機能一覧・設定・スマホ通知の設定はこちら。
+- **Updates / アップデート情報:** new releases and features are announced **in Japanese** on X —
+  新バージョンや新機能のお知らせは X の
+  [Singularity Society (@SingularitySoci)](https://x.com/SingularitySoci) で。
 
 ![MulmoTerminal — a grid of live Claude Code sessions, each color-coded by state, updating in real time](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/hero.gif)
 
@@ -86,11 +89,31 @@ 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.
+
+**Pasting a screenshot** — take a screenshot and paste it straight into the terminal
+(`Cmd`/`Ctrl`+`V`). The image is saved to the session's own drop directory — the same place a
+dropped file goes, with the same grant, the same 110 MiB ceiling and the same cleanup when the
+session ends — and its **absolute path** is inserted at the cursor, so the agent can read it.
+Unlike a drop, this does not need the browser to expose a path — the bytes are on the
+clipboard — so it also covers Chrome, where dropping a file cannot insert a path. It works
+wherever the browser puts the image on the clipboard as `image/png`, `image/jpeg`,
+`image/gif`, or `image/webp`. Anything else is left to the terminal's own paste handling,
+exactly as before — including a paste that carries **plain text** next to the image, which
+copying from a web page usually does, so that pasting text keeps working.
 
 <a id="clicking-a-file-path"></a>
 
@@ -129,6 +152,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`:
@@ -161,7 +229,10 @@ 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
 and keeps your other settings. When `claude` is installed it can hand off to the
-`/mulmoterminal-config` skill for interactive tweaks.
+`/mulmoterminal-config` skill for interactive tweaks — it routes to the one that owns what you
+want to change. Once the app is up you can also reach them from **Settings**: each section that a
+skill can write ends in a button that starts that skill in a new session, which is how the settings
+with no UI (a theme of your own, `keymap`) get written without hand-editing JSON.
 
 **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),
@@ -298,12 +369,12 @@ SDK; we drive the real interactive CLI and relay its TTY over the WebSocket.
 
 ---
 
-## Agents: Claude & Codex
+## Agents: Claude, Codex & Antigravity
 
 MulmoTerminal drives **interactive coding-agent CLIs**, not just Claude. An
 `AgentAdapter` seam abstracts the per-agent bits (which binary to spawn, how it resumes)
-so the PTY, grid, persistence, and GUI-panel plumbing stay shared. Two adapters ship
-today — **Claude Code** (the default) and **Codex**.
+so the PTY, grid, persistence, and GUI-panel plumbing stay shared. Three adapters ship
+today — **Claude Code** (the default), **Codex**, and **Antigravity** (`agy`).
 
 - **Claude** — spawned as `claude` (override with `CLAUDE_BIN`). The server passes
   `--session-id <uuid>`, so it knows the live session's id even before its transcript
@@ -317,10 +388,34 @@ today — **Claude Code** (the default) and **Codex**.
   `CODEX_HOME`) and maps the new rollout to the session — attributed only when it's
   unambiguous, never by "newest wins". Resume reattaches a live PTY, adopts a surviving
   tmux session, or cold-resumes the rollout id.
+- **Antigravity** — spawned as `agy` (override with `ANTIGRAVITY_BIN`; `ANTIGRAVITY_MODEL` sets
+  `--model`). Antigravity runs on its own WebSocket (`/ws/antigravity`). Like Codex it mints its
+  own conversation id, so the server watches `~/.gemini/antigravity-cli/brain/` (home overridable
+  via `ANTIGRAVITY_HOME`) for the directory the new conversation creates — attributed only when
+  unambiguous — and cold-resumes it with `--conversation <id>`.
+
+  Its **GUI tools work differently**, because `agy` takes no MCP flag: it reads its servers from
+  `.agents/mcp_config.json` in the working directory. MulmoTerminal writes that file from the
+  directory's [Canvas switches](#wiki-collections--the-gui-panel) — the same switches Claude's cells read — so
+  one switch serves every agent, and rewrites it whenever a switch flips or an agy session starts.
+  Servers in it that MulmoTerminal did not write are left alone, the file is removed once no group
+  is on, and it is kept out of your `git status` through `.git/info/exclude` — a local switch on a
+  local machine, so it never reaches a diff or your team. The entry runs `server/mcp/bridge.mjs`, a stdio-to-HTTP shim onto the same in-process
+  GUI MCP server the other agents call. The **session id is never written into that file** — it is
+  per directory and shared by every session running there — and reaches the bridge through the agy
+  process's own environment instead.
+
+  The Docker sandbox does NOT cover agy: it stays claude-only until `buildDockerRunArgs` is
+  generalized (see `plans/feat-multi-agent-support.md`, PR#5). `agy` also ships as a standalone
+  binary rather than an npm package, so the sandbox image has nothing to install.
 
 **Choosing an agent.** The single view has a **New Codex session** button; each grid
-cell's launch form and the Collections browser carry a **Claude / Codex** toggle (your
-choice is remembered).
+cell's launch form carries a **Claude / Codex / Antigravity / Shell** toggle, and the
+Collections browser a **Claude / Codex / Antigravity** one (your choice is remembered).
+**Shell** is not an agent: it runs your OS default shell (`$SHELL`, or `/bin/sh`) in the
+chosen directory, with nothing to install and nothing to configure. It starts a launcher
+cell, so it has no model, no MCP registration, and no worktree — those rows disappear
+while it is picked.
 
 **Other models.**
 Claude Code can run against any **Anthropic-compatible** backend (OpenRouter, Moonshot, a
@@ -447,7 +542,14 @@ the `claude` / `codex` sessions themselves.
 | `CODEX_BIN`  | `codex`        | The Codex CLI binary to spawn. |
 | `CODEX_MODEL`| codex default  | Model passed to Codex as `--model` (unset = Codex's own default). |
 | `CODEX_HOME` | `~/.codex`     | Codex home — where its session rollouts and MulmoTerminal-mirrored skills live. |
+| `ANTIGRAVITY_BIN` | `agy`     | The Antigravity CLI binary to spawn. |
+| `ANTIGRAVITY_MODEL` | agy default | Model passed to Antigravity as `--model` (unset = agy's own default). |
+| `ANTIGRAVITY_HOME` | `~/.gemini/antigravity-cli` | Antigravity home directory containing session brain storage. |
 | `MULMOTERMINAL_HOME` | `~/.mulmoterminal` | Root for managed **git worktrees**. |
+| `CLAUDE_CONFIG_DIR` | `~` | Claude Code's own config directory. `.claude.json` lives **inside** it, so relocating your Claude Code config moves that file too — MulmoTerminal reads it to tell whether the per-project GUI MCP server is registered (`server/infra/gui-mcp-registration.ts`). Leave it unset and `~/.claude.json` is used. |
+| `MULMOCLAUDE_WORKSPACE_PATH` | `~/mulmoclaude` | Where the managed MulmoClaude workspace lives. MulmoTerminal seeds presets/helps **only** into this directory, so launching in an arbitrary project never writes them there (`server/backends/workspaceSetup.ts`). Set it to the same value MulmoClaude uses. |
+| `MULMOTERMINAL_NO_SKILL_INSTALL` | unset | Set to any value to skip installing the bundled skills (`mulmoterminal-config` and the `-dirs` / `-theme` / `-header` / `-keys` / `-model` / `-notify` / `-bug-report` / `-decisions` family) into `~/.claude/skills/` and the Codex skills root on startup. |
+| `GEMINI_IMAGE_MODEL` | `gemini-3.1-flash-image-preview` | Model used for image generation (needs `GEMINI_API_KEY`). The default is a **preview** model Google schedules for retirement around mid-2026, so pin a stable one here (e.g. `gemini-2.5-flash-image`) rather than waiting for a code change. |
 | `WAIT_REAP_GRACE_MS` | `1800000` | How long a **waiting** background session is kept before it's auto-reaped (`0` or negative = never). |
 
 The Docker-sandbox variables (`MULMOTERMINAL_SANDBOX`, `MULMOTERMINAL_SANDBOX_IMAGE`,
@@ -477,7 +579,7 @@ The Settings modal (⚙) persists per-user UI choices to `~/.mulmoterminal/confi
 | `soundKinds` | Which moments beep — see [Notification sounds](#notification-sounds). Defaults to `["finished","waiting"]`; the other kinds are opt-in. |
 | `sounds`     | Per-kind sound: `{ "waiting": "preset:coin" }`. A `preset:<id>` reference or an absolute path; a kind with no entry falls back to `soundFile`. |
 | `prRepos`    | `owner/repo` entries whose open PRs/issues the cross-repo **PRs & Issues** view aggregates (via your `gh` login). |
-| `launchers`  | `{ label, command }` entries offered in a grid cell's launcher besides Claude — a plain shell, `codex`, any interactive command. |
+| `launchers`  | `{ label, command }` entries offered in a grid cell's launcher besides the agents — any interactive command. A plain shell needs no entry: the launch form's **Shell** toggle opens `$SHELL` unconfigured. |
 | `quickCommands` | `{ label, text, agents? }` phrases the **phone** offers as chips on a session's terminal view. Tapping one puts `text` in the input box; it is not sent until you press send. `agents` (`"claude"` / `"codex"` / `"shell"`) scopes a chip to session kinds — omit it to offer the chip everywhere. Empty by default. |
 | `userMcpServers` | `{ id, url }` HTTP MCP servers merged into the **single-view** Claude session's `--mcp-config` (a `localhost` URL is reached over `host.docker.internal` in the Docker sandbox). Takes effect on the next session. |
 | `buttons`    | Header action buttons — see [Header buttons](#header-buttons). Omit to keep the defaults; set to replace them. |
@@ -491,6 +593,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
@@ -514,8 +617,8 @@ agent), or `"open"`. An `open` button targets one of `url` / `reveal` (OS file m
 opened next to the current one) / `pr: true` (open the current branch's PR — the button is hidden when
 there's no open PR) / `pickFile: true` (OS file dialog → insert the path).
 `${dir}`, `${branch}`, `${repo}`, … substitute live context, and `when` (e.g. `"isGitRepo"`) gates
-visibility. The `/mulmoterminal-config` skill writes a valid config interactively; per-dir buttons
-merge over the global ones by `id`.
+visibility. The `/mulmoterminal-header` skill writes a valid config interactively; per-dir buttons
+merge over the global ones by `id`, while `chips` replace the global list wholesale.
 
 ### Notification sounds
 
@@ -611,9 +714,10 @@ malformed file is ignored.
   "colors": { "background": "#190a23", "cursor": "#ff2e63" }, // per-key palette overrides
   "fontSize": 16,                       // terminal font size in px (8–32); overrides Settings
   "fontFamily": "'Cica', monospace",    // terminal font stack; overrides the global config
-  "orderPriority": 10,                  // rank in the grid's "priority" ordering (lowest first)
+  "orderPriority": 10,                  // rank in the grid's "priority" order and the launcher chips (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
 }
 ```
 
@@ -634,17 +738,18 @@ malformed file is ignored.
 | `theme`      | xterm palette for terminals in this directory (one of the built-in theme ids). |
 | `colors`     | Per-key xterm palette overrides applied on top of `theme` (or the app theme when `theme` is unset). Keys are xterm `ITheme` names (`background`, `foreground`, `cursor`, `selectionBackground`, the 16 ANSI colors, …); values are hex (`#rgb` / `#rrggbb` / `#rrggbbaa`). Unknown keys / bad values are dropped. |
 | `fontSize`   | Terminal font size in px for this directory (8–32), overriding the Settings value. A size outside the range is clamped; a non-number is ignored. Changing it re-fits the terminal, so the PTY learns the new width — unlike browser zoom, which leaves the two disagreeing. |
-| `orderPriority` | This directory's rank in the grid's **priority** ordering — the third mode on the toolbar's ordering button, next to auto (attention-first) and manual (the move buttons). Any integer, **lowest first**; negatives are allowed. Directories that set nothing sort last, keeping their existing order, so adding the key to one project doesn't shuffle the rest. Only the priority mode reads it. |
+| `orderPriority` | This directory's rank in the grid's **priority** ordering — the third mode on the toolbar's ordering button, next to auto (attention-first) and manual (the move buttons). Any integer, **lowest first**; negatives are allowed. Directories that set nothing sort last, keeping their existing order, so adding the key to one project doesn't shuffle the rest. The grid reads it in **priority** mode only; the launcher's directory chips always sort by it, so a project sits in the same place on both. |
 | `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
 paths and any `../` that escapes the directory are rejected, and the path is never taken from the
 HTTP request, so an opened project can't point the player at arbitrary files.
 **When changes take effect.** A write made *through Claude's tools* — which includes the
-`mulmoterminal-config` skill — applies **live**: the tool hook that reports the write doubles
+`mulmoterminal-dirs` skill — applies **live**: the tool hook that reports the write doubles
 as the reload signal, so colors, palette, font size and grid order update without reopening
 anything. There is no filesystem watcher, so an edit made **outside** a session (your own
 editor) is picked up when the terminal is next opened.
@@ -702,8 +807,9 @@ alongside the Claude sessions. Scripts are **per-directory**: the cell reads the
 different projects' scripts.
 
 The same launcher also has an **or launch** row for your configured **launch commands**
-— a plain interactive shell, `codex`, any command — set in Settings (⚙) → **Launch
-commands** as `{ label, command }` (e.g. `Shell` → `$SHELL`, `Codex` → `codex`). Unlike
+— any interactive command — set in Settings (⚙) → **Launch commands** as
+`{ label, command }` (e.g. `htop` → `htop`, `Codex` → `codex`). A plain shell needs no
+entry here: the launch form's **Shell** toggle already opens `$SHELL`. Unlike
 a one-shot script, a launcher runs as a **persistent terminal in the cell's directory**:
 it survives grid page switches and reconnects, and its dot shows running vs. exited (it
 has no Claude hooks, so no blocked/done states).
@@ -848,7 +954,7 @@ repo without colliding. Worktrees live under `~/.mulmoterminal/worktrees/` (over
 
 ![An empty cell's launch form — choose the agent, working directory, or a worktree](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/grid-launch-form.png)
 
-*Every empty grid cell shows this launch form: toggle **Claude / Codex**, type a **working directory** (frequent ones autocomplete from your presets), or — in a git repo — name a task under **OR ISOLATE IN A WORKTREE** and hit **＋ New worktree** to start the agent on its own isolated branch. **OR LAUNCH** starts a plain shell or any launch command instead.*
+*Every empty grid cell shows this launch form: toggle **Claude / Codex / Antigravity / Shell**, type a **working directory** (frequent ones autocomplete from your presets), or — in a git repo — name a task under **OR ISOLATE IN A WORKTREE** and hit **＋ New worktree** to start the agent on its own isolated branch. **Shell** runs your OS default shell there instead of an agent; **OR LAUNCH** runs one of your configured launch commands.*
 
 A worktree cell's header carries a **diff badge** (`+<commits> ●<dirty>`); click it for a
 **Changes vs `<base>`** panel (file list + patch) with actions:
@@ -1191,6 +1297,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 +1466,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 +1517,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 +1546,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 +1572,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
@@ -1471,7 +1616,8 @@ server/
   mcp/            per-session MCP broker
   backends/       wiki, collections, feeds, accounting, notifier,
                   translation, whisper, remote-host, html, files
-  skills/         bundled skills (mulmoterminal-config, mulmoterminal-bug-report, mulmoterminal-decisions)
+  skills/         bundled skills: mulmoterminal-config (entry point + audit), -dirs, -theme,
+                  -header, -keys, -model, -notify, -bug-report, -decisions
   fix-pty-perms.js              postinstall: fixes node-pty binary permissions
 src/
   App.vue                       Layout; owns the active session + single/grid view

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, "..");
@@ -243,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
@@ -322,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)
@@ -396,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/bundledSkills.ts

@@ -0,0 +1,31 @@
+// The skills MulmoTerminal ships, named once for both sides.
+//
+// Shared rather than mirrored because BOTH sides decide from these: the server COPIES these
+// directories into the user's skills roots at boot, and the client LAUNCHES one by name from the
+// Settings section that owns it. A name that lives in two places is a name that can drift, and it
+// did — the grid view and the single view each spelled the appearance skill out, a rename updated
+// one of them, and the same button then launched a different skill depending on which view you
+// pressed it from. Each half was self-consistent, so nothing failed (Codex review on #1103).
+// `BundledSkillName` is what keeps the Settings buttons honest now: a slug naming no shipped skill
+// is a type error rather than an agent replying that it can't find one.
+
+/** Every skill directory under `server/skills/`, in the order the installer walks them. A spec
+ *  pins this list against what is actually on disk: adding a directory is not what ships it, and
+ *  one nobody lists is copied nowhere with no error at any point. */
+export const BUNDLED_SKILL_NAMES = [
+  "mulmoterminal-config",
+  "mulmoterminal-dirs",
+  "mulmoterminal-theme",
+  "mulmoterminal-header",
+  "mulmoterminal-keys",
+  "mulmoterminal-model",
+  "mulmoterminal-notify",
+  "mulmoterminal-bug-report",
+  "mulmoterminal-decisions",
+] as const;
+
+export type BundledSkillName = (typeof BUNDLED_SKILL_NAMES)[number];
+
+/** The skill that owns `<project>/.mulmoterminal.json` — the one the generated JSON Schema ships
+ *  beside, so the schema sits with the skill that actually writes that file. */
+export const DIR_CONFIG_SKILL = "mulmoterminal-dirs";