mulmoterminal 2.1.1 → 2.3.0

package/README.md

@@ -223,6 +223,7 @@ The launcher detects it and prints the exact, OS-appropriate removal command; ru
 - [Session model](#session-model)
 - [Session lifecycle](#session-lifecycle)
 - [Claude hook injection](#claude-hook-injection)
+- [Closing summary](#closing-summary)
 - [Session discovery & titles](#session-discovery--titles)
 - [Project structure](#project-structure)
 - [Testing](#testing)
@@ -287,7 +288,8 @@ today — **Claude Code** (the default) and **Codex**.
 - **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
   file exists, and injects activity hooks + the GUI MCP per spawn (see
-  [Claude hook injection](#claude-hook-injection)).
+  [Claude hook injection](#claude-hook-injection)) plus the
+  [closing summary](#closing-summary) instruction.
 - **Codex** — spawned as `codex` (override with `CODEX_BIN`; `CODEX_MODEL` sets
   `--model`). Codex runs on its own WebSocket (`/ws/codex`) and its sessions appear in the
   sidebar next to Claude's. Because Codex only mints its rollout id **after** the first
@@ -451,7 +453,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. |
@@ -463,7 +467,9 @@ The Settings modal (⚙) persists per-user UI choices to `~/.mulmoterminal/confi
 | `worklogEnabled` | `true` to run the built-in **dev worklog** batch (see below). Off by default (each run spawns an LLM session, so it costs tokens). |
 | `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). |
+| `copyOnSelect` | `true` puts a **mouse selection on the clipboard the moment it settles**, with no key pressed (the PuTTY / iTerm2 behaviour). **Off by default** — it changes the clipboard when you may only have meant to highlight something. No Settings UI: edit the file and reload the tab. Composes with the `copy` keymap action rather than replacing it. Over plain `http://` the browser gives a page no clipboard access, so a fallback asks xterm to copy instead; see the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#copy-on-select). |
 | `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
 
@@ -482,12 +488,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
@@ -541,7 +581,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
 }
 ```
 
@@ -562,12 +605,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.
 
 ---
 
@@ -712,10 +763,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.
 
 ---
 
@@ -849,6 +923,11 @@ Favorited collections get their own toolbar buttons.
   session.
 - **Notifications** (🔔) — a toolbar bell with an unread badge and a dropdown of active
   notifications; click a row to jump to its session.
+- **Star MulmoTerminal** — a star button in the grid toolbar that stars the project on GitHub
+  through your own `gh` login, in one click. It is a one-time ask: once the repo is starred the
+  button is gone for good and stops calling the server at all. It shows **only when `gh` can
+  answer** — with no `gh`, no login, or no network, one click couldn't star anything, so nothing
+  is shown and nothing is recorded. Set `gh` up later and the button appears by itself.
 - **Voice input** — dictate a prompt via on-device Whisper (`POST /api/transcribe`, macOS
   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
@@ -862,6 +941,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.
 
 ---
 
@@ -1026,6 +1110,7 @@ same-origin-guarded.
 | `GET /api/worktrees?cwd=` · `GET /api/worktrees/diff?cwd=` | List managed worktrees / diff one vs its base. |
 | `POST /api/worktrees/create` · `/remove` · `/push` · `/pr` | Create on `agent/<slug>`, remove (managed root only), push, open a PR (`gh`, else compare URL). |
 | `GET /api/prs` · `GET /api/issues` | Open PRs / issues across the configured `prRepos` (via `gh`). |
+| `GET /api/github/star` · `POST /api/github/star` | Whether you have starred MulmoTerminal, and star it (via `gh`). `starred: null` means `gh` could not answer, and hides the button. |
 
 **Workspace views**
 
@@ -1033,7 +1118,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**
@@ -1050,8 +1135,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). |
@@ -1252,6 +1337,30 @@ knows the live session's id — even before the session's `.jsonl` file exists.
 
 ---
 
+## Closing summary
+
+Every Claude session is spawned with `claude --append-system-prompt '<text>'`, asking the
+agent to end a reply with a short summary **when it hands control back** — the work is
+finished, or it is stopping to ask a question. Coming back to a grid cell after a while, the
+standing request and what came of it are otherwise only recoverable by scrolling the whole
+session.
+
+The summary states three things: the request **for the conversation as a whole** (not the
+last message — several turns of refinement do not replace what was asked first), what was
+achieved, and what was not and why. It is written in the language of the conversation, and
+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.
+
+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.
+
+Codex sessions are unaffected — the CLI has no equivalent flag.
+
+---
+
 ## Session discovery & titles
 
 Claude stores each project's sessions as JSONL files under

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/githubRepo.ts

@@ -0,0 +1,22 @@
+// This project's own GitHub repository, and the wire shape of the star endpoints that act on it.
+// Both sides decide from these — the server builds the `gh api` path and types its response,
+// the client parses that response — so they live here rather than as two copies.
+import { isRecord } from "./isRecord.js";
+
+export const GITHUB_REPO = "receptron/mulmoterminal";
+
+// GitHub's "star a repository" endpoint for this repo: GET reports the current state, PUT stars it.
+export const STAR_API_PATH = `/user/starred/${GITHUB_REPO}`;
+
+// GET/POST /api/github/star. `null` means the server could not tell — no `gh`, not logged in,
+// offline. That is a DIFFERENT answer from "not starred": one click cannot star anything in that
+// state, so the client hides the button rather than offering one that would do nothing.
+export interface GithubStarState {
+  starred: boolean | null;
+}
+
+// Read a star state off an untrusted response body. Anything unparseable reads as "cannot tell",
+// which is the same degradation as a failed request, so the caller needs no separate error path.
+export function parseStarState(value: unknown): boolean | null {
+  return isRecord(value) && typeof value.starred === "boolean" ? value.starred : null;
+}

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,71 @@
+// 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;
+}
+
+// Copy-on-select: the text a settled selection should put on the clipboard, or null to leave the
+// clipboard alone. `lastCopied` is what this terminal wrote last, so an unchanged selection is not
+// written twice.
+//
+// Unlike the rules above, this one ends in a clipboard WRITE — no keystroke happened, so nothing in
+// the browser was ever going to copy anything by itself. That is what makes the two skips here
+// matter more than they look:
+//
+//   - Whitespace only. Dragging across empty terminal space selects spaces, and silently replacing
+//     the user's clipboard with a run of them is this feature's worst failure. Anyone who really
+//     wants indentation still has the `copy` keymap action.
+//   - Unchanged text. A second identical write buys nothing and costs a duplicate entry in the OS
+//     clipboard history (Win+V), which is the same reason the caller waits for the selection to
+//     settle instead of writing on every onSelectionChange.
+export function selectionToCopy(enabled: boolean, selection: string, lastCopied: string | null): string | null {
+  if (!enabled || selection.trim() === "" || selection === lastCopied) return null;
+  return selection;
+}