mulmoterminal 2.1.0 → 2.2.0

package/README.md

@@ -111,11 +111,23 @@ dotfiles are server-only. The 45 extensions both sides agree on live in
 
 ## Install & run
 
-Requires the [`claude`](https://claude.com/claude-code) CLI on your `PATH` and
-**Node ≥ 22.9**. Optional but recommended: **`tmux`** so terminals survive a server
-restart (see [Session persistence (tmux)](#session-persistence-tmux)), the **`gh`** CLI
-logged in for the PRs/Issues view and one-click PR creation, and — for Codex sessions —
-the **`codex`** CLI on your `PATH`.
+Needs **Node ≥ 22.9**, plus these CLIs on your `PATH`:
+
+| | Tool | What it gives you | Install |
+| --- | --- | --- | --- |
+| **Required** | [`claude`](https://claude.com/claude-code) | every Claude session — this app is a cockpit for it | `npm i -g @anthropic-ai/claude-code`, then run `claude` once to log in |
+| **Required** | `git` | [worktree isolation](#git-worktrees--pull-requests), each cell's branch / unsaved-dot / diff readout, the PR footer | `brew install git` · `sudo apt install git` · `sudo dnf install git` · Windows: [git-scm.com](https://git-scm.com/download/win) |
+| **Required** | `gh` | the cross-repo **PRs & Issues** view and one-click PR creation — it uses your `gh` login, so no token is stored | [cli.github.com](https://cli.github.com), then `gh auth login` |
+| Recommended | `tmux` | [session persistence](#session-persistence-tmux) — terminals survive a server restart | `brew install tmux` · `sudo apt install tmux` · `sudo dnf install tmux` · no native Windows build (falls back to plain PTYs) |
+| Optional | `codex` | [Codex sessions](#agents-claude--codex) in a cell, alongside Claude | `npm i -g @openai/codex` |
+| Optional | `docker` | the experimental [Docker sandbox](#docker-sandbox-experimental-single-view) | [docs.docker.com](https://docs.docker.com/get-started/get-docker/) |
+| Optional | `ffmpeg` | video rendering from the [mulmo-script panel](#wiki-collections--the-gui-panel) (its plugin ships enabled) | `brew install ffmpeg` · `sudo apt install ffmpeg` · `sudo dnf install ffmpeg` |
+| Optional | `ollama` | [`claude-ollama`](https://receptron.github.io/mulmoterminal/guide/en/claude-ollama.html) — Claude Code against a fully local model | [ollama.com/download](https://ollama.com/download) |
+
+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
+these it can find.
 
 ```bash
 npx mulmoterminal           # start on http://localhost:34567 and open the browser
@@ -124,8 +136,8 @@ npm install -g mulmoterminal
 mulmoterminal
 ```
 
-**First-run setup (optional).** `npx mulmoterminal init` checks your environment (Node ≥ 22.9,
-the `claude` CLI, plus optional `tmux` / `gh` / `codex`), seeds the launcher's **directory
+**First-run setup (optional).** `npx mulmoterminal 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
 and keeps your other settings. When `claude` is installed it can hand off to the
@@ -439,7 +451,9 @@ The Settings modal (⚙) persists per-user UI choices to `~/.mulmoterminal/confi
 | Field        | Meaning |
 | ------------ | ------- |
 | `cwdPresets` | Quick-pick directories offered when launching a terminal. |
-| `soundFile`  | Absolute path to a custom **attention sound** (played when a session needs attention). Empty/unset uses the built-in synthesized chime. |
+| `soundFile`  | Absolute path to a custom **attention sound**, the fallback for every kind. Empty/unset uses the built-in synthesized chime. |
+| `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. |
 | `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. |
@@ -452,6 +466,7 @@ The Settings modal (⚙) persists per-user UI choices to `~/.mulmoterminal/confi
 | `worklogIntervalHours` | Worklog cadence in hours (default `6`, clamped to `1`–`168`). |
 | `terminalSubmit` | Which bytes Claude reads as **submit** vs **newline**: `"cr"` (default — Enter submits, Shift+Enter makes a newline) or `"esc-cr"` (for a Claude Code rebound the other way). Applies to the keyboard **and** the phone remote-view submit, for **Claude sessions only** (shell/codex keep plain Enter). See the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#terminal-submit). |
 | `prWorkdirFooter` | Ends the body of a PR **⧉ Open PR** creates 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. **On by default**; set `false` to opt out — read from the file per PR, so no restart is needed (there is no Settings control for it). Only applied to PRs this app creates (pressing the button again on an existing PR never re-appends). |
+| `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). |
 
 #### Header buttons
 
@@ -470,12 +485,46 @@ there's no open PR) / `pickFile: true` (OS file dialog → insert the path).
 visibility. The `/mulmoterminal-config` skill writes a valid config interactively; per-dir buttons
 merge over the global ones by `id`.
 
-**Attention sound.** The default chime is generated with the Web Audio API — **no
-audio file is bundled**, so the npm package stays light and has no media-licensing
-concerns. To use your own sound, set `soundFile` in Settings (Browse / Test / Use
-chime) or in the config file; the server streams that file at `GET /api/sound` and
-the client decodes it (falling back to the chime if it's missing or not audio). It's
-your own local file referenced by absolute path — nothing is added to the package.
+### Notification sounds
+
+Six moments can beep, each with its own sound and its own on/off switch. Running many
+agents at once is what turns notifications into noise, so **only the first two are on by
+default** — the rest are opt-in from Settings.
+
+| Kind | When | Default |
+| --- | --- | --- |
+| `finished` | the turn ended and the output is unread | **on** |
+| `waiting` | it stopped to ask — a permission prompt or a question | **on** |
+| `command-done` | a **Run cell's** command exited 0 | off |
+| `command-failed` | a **Run cell's** command exited non-zero, or never started | off |
+| `session-exited` | a session's terminal ended — **including when you close the cell yourself** | off |
+| `pr-ci-failed` | a directory's PR went red. Only seen **while the roster is on screen**, since that is what polls the phase | off |
+
+A **Run cell** is the one-shot cell a `script.json` entry or a `run:"shell"` header button
+opens — not a shell launcher cell. A launcher runs an interactive shell that stays alive, so
+nothing marks where one command inside it ended; only the one-shot cell reports an exit code.
+
+`finished` and `waiting` reach the phone too (`pushKinds`); the other four are seen only in
+the browser — a Run PTY never enters the session registry, and a PR phase is something the
+page polls — so Web Push cannot raise them.
+
+**What each one plays.** The default chime is generated with the Web Audio API — **no audio
+file is bundled**, so the npm package stays light and has no media-licensing concerns. Beyond
+it there are two options:
+
+- **Presets** — seven sounds hosted in the [ownplate](https://github.com/Nakajima-Foundation/ownplate)
+  repo (MIT), referenced as `preset:<id>`: `chime` `coin` `cheep` `door` `gong` `magic` `meow`.
+  The first play downloads one into `~/.mulmoterminal/sounds/`; every later play reads that
+  file, so a preset keeps working offline. A failed download is not remembered as one — you get
+  the chime that time and the next play retries. That holds on both sides: the server caches no
+  failure, and it answers **503** (not 404) for a preset it could not fetch, because the browser
+  remembers a 404 for the life of the page and only retries a 5xx.
+- **Your own file** — an absolute path, per kind in `sounds` or as the all-kind `soundFile`.
+
+Resolution per kind, nearest first: the session directory's `sounds[kind]`, its `sound`, your
+`sounds[kind]`, your `soundFile`, then the chime. The server streams whichever applies at
+`GET /api/sound?kind=` / `GET /api/dir-sound?cwd=&kind=`, and the client falls back to the
+chime if it's missing or not audio.
 
 **Web Push on task finish.** Enable `pushEnabled` in Settings to have the server send a
 push (title = the project dir, body = the last prompt) to your registered devices each
@@ -529,7 +578,10 @@ malformed file is ignored.
   "theme": "nord",                      // terminal palette: midnight | nord | daylight | solarized
   "colors": { "background": "#190a23", "cursor": "#ff2e63" }, // per-key palette overrides
   "fontSize": 16,                       // terminal font size in px (8–32); overrides Settings
-  "sound": "./.mulmoterminal/alert.mp3" // attention sound, RELATIVE to this directory
+  "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
 }
 ```
 
@@ -550,12 +602,20 @@ 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. |
-| `sound`      | Attention sound for this directory's sessions, a path **relative to the directory** (served at `GET /api/dir-sound`). |
-
-**Security.** `sound` is a directory-relative path only — absolute paths and any
-`../` that escapes the directory are rejected, and the path is never taken from the
+| `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. |
+| `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. |
+| `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.
-Changes take effect when the terminal is next opened (no live file watch).
+**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
+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.
 
 ---
 
@@ -700,10 +760,33 @@ tree; clicking a file opens it in a **CodeMirror** editor (Markdown / JS-TS / JS
 highlighting, everything else as plain text). Markdown files get a **Preview** toggle
 that renders via the server's sandboxed `…/md` HTML. **Save** (or ⌘/Ctrl-S) writes back.
 
+**Beside an enlarged terminal, not only full-screen.** Expand a grid cell (**⤢**) and its
+header gains a **folder** toggle that splits the enlarged area in two: terminal on the left,
+the same explorer + editor on the right, rooted at that cell's directory. Drag the divider
+(or focus it and use ←/→, Home, End) to resize — the terminal keeps a floor, so a squeeze
+shrinks the pane rather than reflowing xterm into garbage. It works in both zoomed layouts
+(cockpit roster and thumbnail filmstrip), the pane re-roots as you walk the zoom between
+terminals, and whether it's open plus how wide it is are remembered per browser.
+
 All reads and writes go through `GET/PUT /api/files/browse/*?cwd=&path=`, and every
 `path` is **contained within the project root** (server-side) — `..`/absolute escapes
 are rejected for reads and writes alike, so editing can't reach outside the directory
-the terminal is pointed at.
+the terminal is pointed at. A save sends the version the file had when it was opened, so
+it is **refused (409) rather than silently overwriting** an agent that edited the same
+file meanwhile; the editor then offers to reload or to overwrite deliberately.
+
+You usually hear about it before that. An open file that changes on disk is picked up from
+Claude's own write hook (immediately) and from a 30-second version check (which catches Codex,
+git, builds and other editors too). A **clean** buffer just takes the new content — the pane
+reads as a live view — while a **dirty** one raises the same banner rather than choosing for you.
+
+**Leaving an open file saves it** — switching files, moving the enlargement to another
+terminal, closing the pane, navigating away. No dialog interrupts you mid-flow, because
+opening a file, and replacing one, keep a copy under `~/.mulmoterminal/backups/` — **three
+generations per file**, outside the project so they never reach `git status` or the agent's
+view of its own repo. A parting save that loses the version race banks your version there
+instead of overwriting the other writer. Re-opening unchanged content doesn't rotate one in, and a backup that
+can't be written never blocks the read or the save it was taken for.
 
 ---
 
@@ -838,7 +921,10 @@ Favorited collections get their own toolbar buttons.
 - **Notifications** (🔔) — a toolbar bell with an unread badge and a dropdown of active
   notifications; click a row to jump to its session.
 - **Voice input** — dictate a prompt via on-device Whisper (`POST /api/transcribe`, macOS
-  only; the model downloads on first use).
+  only; the model downloads on first use). Settings picks **the language you dictate in**
+  (per browser): your browser's, whisper's own per-clip detection, or a fixed one. Worth
+  setting — speech in a language the mic is not expecting comes back *translated* into the
+  one it is, so an English browser silently turned Japanese dictation into English.
 - **Remote host** — link MulmoTerminal to the companion phone client (Google sign-in) to
   watch and start sessions from your phone.
 - **Themes** — four terminal palettes (midnight / nord / daylight / solarized), your pick
@@ -847,6 +933,11 @@ Favorited collections get their own toolbar buttons.
   **Option** is treated as Meta so Claude's Alt-key bindings work. If your Claude Code is
   rebound so Enter and Shift+Enter behave backwards, flip them with
   [`terminalSubmit`](https://receptron.github.io/mulmoterminal/guide/en/config.html#terminal-submit).
+- **No accidental page zoom** — `Ctrl`+wheel and a trackpad pinch would rescale the whole
+  page and drag the layout and the terminal's fit along with it, so both are ignored.
+  Keyboard zoom (`Cmd`/`Ctrl` `+` / `-`) still works when you mean it, and a phone's finger
+  pinch is untouched. To make terminal text bigger for real, use the font size in Settings
+  (or a directory's `fontSize`) — that re-fits the PTY instead of leaving it disagreeing.
 
 ---
 
@@ -1018,7 +1109,7 @@ same-origin-guarded.
 | -------- | ------- |
 | `GET /api/wiki` (`?slug=`) · `/api/wiki/graph` · `/api/wiki/lint` | Read-only wiki index / page / graph / lint. |
 | `GET /api/collections/…` · `/api/feeds` · `GET\|PUT /api/shortcuts` | Collections browser, feeds, favorites (see `docs/collection-plugin-integration.md`). |
-| `GET /api/files/browse/{list,text,md}` · `PUT /api/files/browse/write` | File tree / read / Markdown-render / write (contained within the project root). |
+| `GET /api/files/browse/{list,text,version,md}` · `PUT /api/files/browse/{write,backup}` | File tree / read / Markdown-render / write (contained within the project root). `text` answers `{ text, version }`; `write` takes `{ text, baseVersion }` (`null` = expecting to create it) and answers **409** with the version now on disk if the file changed since — so a save can't silently overwrite the agent that edits the same files. `version` answers that token alone, for the editor's periodic check. `backup` banks a buffer the editor is about to discard. |
 | `GET /api/files/raw?path=` | Raw asset bytes (workspace-rooted). |
 
 **GUI panel / plugins / MCP**
@@ -1035,8 +1126,8 @@ same-origin-guarded.
 
 | Endpoint | Purpose |
 | -------- | ------- |
-| `GET\|POST /api/config` | User UI config (`cwdPresets`, `soundFile`, `prRepos`, `launchers`, `quickCommands`, `userMcpServers`, `providers`). |
-| `GET /api/sound` · `/api/dir-sound?cwd=` · `/api/dir-config?cwd=` | Custom / per-directory attention sound + per-dir config. |
+| `GET\|POST /api/config` | User UI config (`cwdPresets`, `soundFile`, `soundKinds`, `sounds`, `prRepos`, `launchers`, `quickCommands`, `userMcpServers`, `providers`). |
+| `GET /api/sound?kind=` · `/api/dir-sound?cwd=&kind=` · `/api/sound-preset/:id` · `/api/dir-config?cwd=` | Custom / per-directory / preset attention sound + per-dir config. `kind` selects a config entry, never a path. |
 | `GET /api/launch-options` | The Anthropic-compatible backends this server can reach, each with its models and — when it can't — the reason. Reports the **name** of the env var a key is read from, never the key. |
 | `GET /api/notifications`(`/history`) · `POST /api/notifications/:id/clear` | Notification feed. |
 | `POST /api/transcribe`(`/model`…) | Voice-input transcription (Whisper, macOS). |

package/bin/mulmoterminal.js

@@ -76,6 +76,31 @@ function claudeInstalled() {
   return hasCommand("claude");
 }
 
+// PATH tools the app shells out to; mirrors the requirements table in README.md. `required`
+// ones back the core grid — without them a developer loses whole views rather than one
+// feature — so a miss is an ✗, not an ○.
+const PATH_TOOLS = [
+  { cmd: "git", versionArg: "--version", required: true, why: "worktrees, per-cell branch/diff, PR footer", hint: "brew install git  ·  apt install git" },
+  { cmd: "gh", versionArg: "--version", required: true, why: "PRs & Issues view + one-click PRs", hint: "https://cli.github.com  (then: gh auth login)" },
+  { cmd: "tmux", versionArg: "-V", required: false, why: "sessions survive a restart", hint: "brew install tmux  ·  apt install tmux" },
+  { cmd: "codex", versionArg: "--version", required: false, why: "run OpenAI Codex as an agent", hint: "npm install -g @openai/codex" },
+  { cmd: "docker", versionArg: "--version", required: false, why: "the experimental Docker sandbox", hint: "https://docs.docker.com/get-started/get-docker/" },
+  {
+    cmd: "ffmpeg",
+    versionArg: "-version",
+    required: false,
+    why: "video rendering in the mulmo-script panel",
+    hint: "brew install ffmpeg  ·  apt install ffmpeg",
+  },
+  { cmd: "ollama", versionArg: "--version", required: false, why: "a fully local model via claude-ollama", hint: "https://ollama.com/download" },
+];
+
+function toolCheckLine({ cmd, versionArg, required, why, hint }) {
+  if (hasCommand(cmd, versionArg)) return `  ✓ ${cmd} — ${why}`;
+  const head = required ? `  ✗ ${cmd} — not found, needed for ${why}` : `  ○ ${cmd} — optional (${why})`;
+  return `${head}\n      → ${hint}`;
+}
+
 function promptYesNo(question) {
   return new Promise((res) => {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -103,13 +128,7 @@ async function runInit(initArgs) {
     console.log("      → npm install -g @anthropic-ai/claude-code   (then run `claude` and log in)");
   }
 
-  for (const [cmd, versionArg, why, hint] of [
-    ["tmux", "-V", "sessions survive a restart", "brew install tmux  ·  apt install tmux"],
-    ["gh", "--version", "PRs & Issues view + one-click PRs", "https://cli.github.com  (then: gh auth login)"],
-    ["codex", "--version", "run OpenAI Codex as an agent", "npm install -g @openai/codex"],
-  ]) {
-    console.log(hasCommand(cmd, versionArg) ? `  ✓ ${cmd} — ${why}` : `  ○ ${cmd} — optional (${why})\n      → ${hint}`);
-  }
+  PATH_TOOLS.forEach((tool) => console.log(toolCheckLine(tool)));
 
   // Config half: derive working-dir presets from Claude history + write config.json.
   console.log("");

package/common/collectionPush.ts

@@ -0,0 +1,26 @@
+// The `POST /api/collections/:slug/calendar-push` response. The server builds it from the
+// engine's outcome; the collection view reads it to say what the click did — both sides
+// decide from it, so it lives here.
+//
+// The shape (and the route's path) mirrors MulmoClaude's `CollectionPushBody`
+// (server/api/routes/collectionCalendarPush.ts) so the two hosts over the shared workspace
+// answer the same plugin identically. Re-stated rather than imported: the plugin ships its
+// `CollectionPushResult` from `@mulmoclaude/collection-plugin/vue`, and the server has no
+// business pulling a Vue package in to describe its own response.
+
+export interface CollectionPushResult {
+  /** Always true — "the push ran", not "records moved". The plugin's own type widens this
+   *  to `boolean` but never reads it, and MulmoClaude pins it to `true`; a refusal is told
+   *  through `errors`, so the two hosts stay identical on a field neither of them uses. */
+  pushed: true;
+  created: number;
+  updated: number;
+  /** Edited on both sides; skipped so neither version is destroyed. */
+  conflicts: number;
+  /** Deleted locally. Reported only — a push never deletes in Google. */
+  localDeletes: number;
+  /** Records that could not be pushed as they stand, each with its reason. */
+  skipped: string[];
+  /** Why the push as a whole did not do what was asked. */
+  errors: string[];
+}

package/common/dirChrome.ts

@@ -21,6 +21,14 @@ export interface DirChrome {
   // Unlike the colors above, this changes the cell metrics — every path that applies it has
   // to re-fit and push the new cols/rows to the PTY, or the grid drifts from the canvas.
   fontSize: number | null;
+  // The CSS font-family stack for terminals opened here, or null to use the global setting.
+  // Changes the cell metrics for the same reason `fontSize` does — a different face has a
+  // different advance width — so it re-fits on the same path.
+  fontFamily: string | null;
+  // Where this directory's cells sit in the grid's "priority" sort order — ascending, and
+  // null (unset) sorts last so adding it to one directory doesn't displace every other cell.
+  // Only that one sort mode reads it; "auto" and "manual" ignore it entirely.
+  orderPriority: number | null;
 }
 
 // "Nothing configured" — the base every DirConfig/PublicDirConfig empty spreads, so adding
@@ -37,4 +45,6 @@ export const EMPTY_DIR_CHROME: Readonly<DirChrome> = {
   dotColor: null,
   buttonColor: null,
   fontSize: null,
+  fontFamily: null,
+  orderPriority: null,
 };

package/common/fileWriteChannel.ts

@@ -0,0 +1,9 @@
+// The pub/sub channel carrying "an agent just wrote this file". Both sides decide from it —
+// the server publishes, the editor listens to know its open file moved under it — so the name
+// and the payload shape live here rather than as a string literal on each side.
+export const FILE_WRITE_CHANNEL = "file-write";
+
+/** Absolute path, as the server resolved it. */
+export interface FileWriteEvent {
+  file: string;
+}

package/common/keymap.ts

@@ -10,12 +10,33 @@
 //   "keymap": { "zoom-next": "PageDown", "zoom-prev": "Shift+PageUp" }
 
 // Actions a key can be bound to. Adding one here is all it takes for the config to accept it.
-export const KEYMAP_ACTIONS = ["zoom-toggle", "zoom-next", "zoom-prev", "next-attention", "terminal-new", "terminal-new-adjacent", "terminal-close"] as const;
+export const KEYMAP_ACTIONS = [
+  "zoom-toggle",
+  "zoom-next",
+  "zoom-prev",
+  "next-attention",
+  "terminal-new",
+  "terminal-new-adjacent",
+  "terminal-close",
+  "copy",
+  "paste",
+] as const;
 export type KeymapAction = (typeof KEYMAP_ACTIONS)[number];
 
 export const isKeymapAction = (value: unknown): value is KeymapAction => typeof value === "string" && (KEYMAP_ACTIONS as readonly string[]).includes(value);
 
 // action -> binding string. Absent action = unbound = that shortcut does nothing.
+// Actions the GRID's key handler must never claim, because they are decided inside the terminal
+// instead (see terminalClipboard.ts). One `keymap` block stays the user's single place to bind a
+// key; only the dispatch differs, and it has to:
+//
+//   - The grid handler ends every match with preventDefault(). For `paste` that is fatal — the
+//     browser's own paste is what actually inserts the text, and cancelling the keydown cancels
+//     it. xterm implements paste as a `paste` DOM listener, not a key binding.
+//   - `copy` must fall through to the terminal when there is NO selection, so Ctrl+C still sends
+//     ^C. A handler that has already swallowed the key cannot change its mind.
+export const TERMINAL_SCOPED_ACTIONS: readonly KeymapAction[] = ["copy", "paste"];
+
 export type Keymap = Partial<Record<KeymapAction, string>>;
 
 // A parsed binding. `key` is matched against `KeyboardEvent.key` exactly as the browser

package/common/notifyKinds.ts

@@ -0,0 +1,26 @@
+// The moments MulmoTerminal can notify you about. The attention sound reads this whole
+// list; Web Push reads the PUSH_KINDS subset in pushKinds.ts, because a phone can only be
+// told about what the SERVER observes — the four kinds added below are seen in the browser.
+
+// Every kind that exists.
+//   finished       — the turn ended, output is waiting to be reviewed.
+//   waiting        — the agent is blocked on input (a permission prompt or a question).
+//   command-done   — a Run cell's command exited 0.
+//   command-failed — a Run cell's command exited non-zero.
+//   session-exited — a session's PTY ended. Closing a cell yourself goes through the same
+//                    path, so this one fires on a deliberate close too.
+//   pr-ci-failed   — a directory's PR phase became ci-failing. The phase poll runs only
+//                    while the roster is on screen, so a failure that lands while you are
+//                    in another view is not seen.
+export const NOTIFY_KINDS = ["finished", "waiting", "command-done", "command-failed", "session-exited", "pr-ci-failed"] as const;
+
+export type NotifyKind = (typeof NOTIFY_KINDS)[number];
+
+// What a config with no `soundKinds` gets. Deliberately a SEPARATE list from NOTIFY_KINDS,
+// not a copy of it: a kind added later must NOT start beeping at people who never asked for
+// it — the same rule DEFAULT_PUSH_KINDS documents, and the reason the four kinds above are
+// absent here. Add a kind to NOTIFY_KINDS so it can be switched on, and leave it out of
+// here so it stays opt-in.
+export const DEFAULT_SOUND_KINDS: NotifyKind[] = ["finished", "waiting"];
+
+export const isNotifyKind = (value: unknown): value is NotifyKind => NOTIFY_KINDS.some((kind) => kind === value);

package/common/notifySounds.ts

@@ -0,0 +1,44 @@
+// The preset attention sounds, and how a configured sound names one.
+//
+// The audio lives in the ownplate repo (MIT, same org) rather than in this package, so an
+// install doesn't carry ~380 KB of audio nobody may play. The server fetches a preset once
+// into ~/.mulmoterminal/sounds/ and serves it from there afterwards, so it keeps working
+// offline — see server/config/sound-presets.ts.
+
+// Pinned to the commit that last touched these files (2022-03-30) rather than to a branch:
+// a branch ref would let the bytes behind a cached preset change, and a user who picked
+// "coin" would silently get something else on a machine that hadn't cached it yet.
+export const SOUND_PRESET_COMMIT = "fb36eb8748b7f3d181d7fc0e366e01971a56ad2f";
+export const SOUND_PRESET_BASE_URL = `https://raw.githubusercontent.com/Nakajima-Foundation/ownplate/${SOUND_PRESET_COMMIT}/public/`;
+
+export interface SoundPreset {
+  id: string;
+  file: string;
+  label: string;
+}
+
+export const SOUND_PRESETS: readonly SoundPreset[] = [
+  { id: "chime", file: "sound_default.mp3", label: "Chime" },
+  { id: "coin", file: "sound_coin.mp3", label: "Coin" },
+  { id: "cheep", file: "sound_cheep_cheep.mp3", label: "Cheep" },
+  { id: "door", file: "sound_door_chime.mp3", label: "Door chime" },
+  { id: "gong", file: "sound_gong.mp3", label: "Gong" },
+  { id: "magic", file: "sound_magic.mp3", label: "Magic" },
+  { id: "meow", file: "sound_meow.mp3", label: "Meow" },
+];
+
+// A sound value is either a preset reference or a path to the user's own file. The prefix is
+// what tells them apart, and it can't collide with a path: an absolute path starts with "/"
+// (or a drive letter), and a relative one is rejected before it gets here.
+const PRESET_PREFIX = "preset:";
+
+export const presetRef = (id: string): string => `${PRESET_PREFIX}${id}`;
+
+export const soundPresetById = (id: string): SoundPreset | null => SOUND_PRESETS.find((preset) => preset.id === id) ?? null;
+
+/** The preset id in a `preset:<id>` value, or null when it names a file path or an unknown preset. */
+export function parsePresetRef(value: string): string | null {
+  if (!value.startsWith(PRESET_PREFIX)) return null;
+  const id = value.slice(PRESET_PREFIX.length);
+  return soundPresetById(id) ? id : null;
+}

package/common/orderPriority.ts

@@ -0,0 +1,20 @@
+// A directory's rank in the grid's "priority" sort order. Shared so the two boundaries that
+// validate it — the server reading .mulmoterminal.json, and the client reading /api/dir-config —
+// cannot disagree about what counts as a rank. They did briefly: one accepted any finite number
+// while the other required an integer, so a fractional value would have sorted on one side and
+// read as unset on the other.
+//
+// Integers only: a rank is an ordering, so 1.5 buys nothing and invites float-comparison
+// surprises. Not range-limited, unlike a font size — every integer is a usable rank, and
+// negatives are how a project sorts ahead of everything at 0.
+//
+// SAFE integers, because the strict half of the pair is `z.number().int()` and zod@4 reads that
+// as safe-only. `Number.isInteger` alone accepts 2^53+1 and 1e300, which this would have taken
+// while writableDirConfigSchema rejected them — the exact disagreement the paragraph above says
+// this module exists to prevent, one boundary over. Past 2^53 an integer is not distinct from its
+// neighbours anyway, so it cannot express a rank.
+//
+// null means "unset", which the sort reads as "after everything that declares a rank".
+export function normalizeOrderPriority(input: unknown): number | null {
+  return typeof input === "number" && Number.isSafeInteger(input) ? input : null;
+}

package/common/pushKinds.ts

@@ -1,12 +1,16 @@
 // The kinds of Web Push a session can raise. The server decides which one a hook warrants and
 // the settings UI offers them as checkboxes, so the list is a value both sides read.
 
-// Every kind that exists.
+import type { NotifyKind } from "./notifyKinds.js";
+
+// Every kind that exists — a SUBSET of NOTIFY_KINDS, since a push can only report what the
+// server itself observes. The rest of the notify kinds are browser-side signals (a Run cell's
+// exit, a PR phase poll) that never reach the process holding the Firebase auth.
 //   finished — the turn ended, output is waiting to be reviewed.
 //   waiting  — the agent is blocked on input (a permission prompt or a question), so answering
 //              from the phone unblocks real work. Fires once per prompt, which on a long task
 //              that asks repeatedly is what makes pushes feel frequent (#850).
-export const PUSH_KINDS = ["finished", "waiting"] as const;
+export const PUSH_KINDS = ["finished", "waiting"] as const satisfies readonly NotifyKind[];
 
 export type PushKind = (typeof PUSH_KINDS)[number];
 

package/common/terminalClipboard.ts

@@ -0,0 +1,52 @@
+// Whether a keystroke should hand the terminal's clipboard work to the BROWSER, decided without
+// touching the DOM so the rules are unit-testable on their own (same shape as `enterKeyOverride`
+// in terminalSubmit.ts).
+//
+// The thing to understand before changing any of this: xterm already implements copy and paste.
+// It listens for the `copy` and `paste` DOM events on its own element and textarea, writes the
+// selection out, and brackets pasted text. Nothing here reads or writes a clipboard — which is
+// also why no clipboard PERMISSION is involved, unlike `navigator.clipboard.readText()`.
+//
+// What is missing is only that the browser never fires those events: xterm's key handling turns
+// Ctrl+C into ^C and cancels the keydown, so the platform's copy shortcut never happens. The one
+// decision this module makes is when to stand back and let it.
+import { actionForKey, type Keymap, type KeymapAction } from "./keymap.js";
+
+// The structural shape of a keydown these rules need; a real KeyboardEvent satisfies it and so
+// does a plain test object.
+export interface ClipboardKeyEvent {
+  type: string;
+  key: string;
+  shiftKey: boolean;
+  altKey: boolean;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  isComposing?: boolean;
+}
+
+export type ClipboardAction = Extract<KeymapAction, "copy" | "paste">;
+
+// `hasSelection` is the terminal's own answer, passed in rather than read here so this stays
+// DOM-free.
+//
+// Returning an action means ONE thing to the caller: return false from xterm's custom key
+// handler. xterm then skips its own translation and — critically — does NOT preventDefault, so
+// the browser performs the copy or paste it was always going to, and xterm's own listeners see
+// it. Verified in @xterm/xterm 6.0.0:
+//
+//   if (this._customKeyEventHandler && false === this._customKeyEventHandler(e)) return false;
+//
+// null means "not ours" — the key goes to the terminal exactly as before.
+export function clipboardActionFor(keymap: Keymap, e: ClipboardKeyEvent, hasSelection: boolean): ClipboardAction | null {
+  if (e.type !== "keydown") return null;
+  // An IME candidate list drives itself with ordinary keys; that keystroke belongs to the
+  // composition, never to us.
+  if (e.isComposing) return null;
+  const action = actionForKey(keymap, e);
+  if (action !== "copy" && action !== "paste") return null;
+  // Copy only when there is something to copy. This is what keeps Ctrl+C usable as INTERRUPT:
+  // with no selection the key is not ours, so the terminal sends ^C exactly as it always did.
+  // Deciding up front — rather than copying and undoing it on failure — is why nothing here has
+  // to be reversed.
+  return action === "copy" && !hasSelection ? null : action;
+}