mulmoterminal 7.1.0 → 7.3.0

package/README.md

@@ -183,18 +183,19 @@ than as bytes (files within the session's working directory only):
 **A line after the path is followed.** `src/a.ts:42`, `src/a.ts:42:7` (gcc, clang, `eslint -f unix`,
 stack traces) and `src/a.ts(12,5)` (tsc) are one link. In the pane, and in the Files view, the file
 opens as text with the caret on that line and column — an HTML page, an SVG or a table included, and a
-tab reading in Preview switches to Edit. A route that renders the file in a new tab (`.md`, `.json`,
+tab reading in Preview switches to Edit. An image, a PDF, a video or an audio file has no line to go
+to and simply opens as itself. A route that renders the file in a new tab (`.md`, `.json`,
 `.csv`, `.html` with no cell enlarged) ignores the line. When the pane beside an enlarged cell takes
 the click, the keyboard stays in the terminal; the full-screen Files view, with no terminal beside it,
 puts it in the editor. (ESLint's default output puts the path on a line of its own, with no line number to follow.)
 
 **While a grid cell is enlarged, the [Files pane](#files-view-browse--edit) takes the click first** — every
-row above except PDF, video and audio, since the pane is the same editor with a Preview for
-Markdown, HTML and SVG, and shows an image as a picture. The file opens *beside* the terminal
+row above, since the pane is the same editor with a Preview for Markdown, HTML and SVG, shows an
+image as a picture and a PDF in a frame, and plays a video or an audio file with the browser's own
+controls (seeking included, whatever the file's size). The file opens *beside* the terminal
 that printed it, and the pane opens itself if it was closed. It declines, leaving the routing
-above untouched, when nothing is enlarged, when the path is not under that cell's own directory
-(the pane cannot walk above its root), or for a PDF, a video or an audio file, which only a
-browser tab can play.
+above untouched, when nothing is enlarged, or when the path is not under that cell's own directory
+(the pane cannot walk above its root). A file too large to edit as text still offers **Open in OS**.
 
 Highlighting in the Files view covers the JS/TS family, JSON and Markdown (the modes
 `cmEditor.ts` bundles); other languages open as plain text.
@@ -308,7 +309,8 @@ mulmoterminal
 
 **Stopping it.** `Ctrl+C` in the terminal that started it — or, if you can no longer find that
 terminal, **Settings → Quit MulmoTerminal** in the browser, or **`npx mulmoterminal@latest stop`**
-from any terminal (installed globally, just `mulmoterminal stop`). All three run the same shutdown:
+from any terminal (installed globally, just `mulmoterminal stop`; it stops every server running on
+this machine, and `--port <port>` stops only that one). All three run the same shutdown:
 with `tmux` installed the agent sessions survive and come back under **Settings → Sessions that
 survived a restart**; without it they end with the server.
 
@@ -634,6 +636,17 @@ up for Codex, loaded by description.
 
 ---
 
+## Running the server on another machine
+
+The server can live on a Linux box, a VPS or a container while your browser stays on your laptop:
+start it there over SSH (`npx mulmoterminal`), and reach it through an SSH tunnel
+(`ssh -N -L 34567:127.0.0.1:34567 you@server`, then open `http://localhost:34567`). Started over
+SSH, the launcher opens no browser on the server and prints that command. It still listens on
+loopback only — nothing is opened to the network. Logging the agents in on the server, Docker, and
+the few actions that act on the server's machine: [Run the server on another machine](https://receptron.github.io/mulmoterminal/guide/en/remote.html).
+
+---
+
 ## Session persistence (tmux)
 
 If **`tmux` is installed**, MulmoTerminal runs each Claude session and launcher inside
@@ -777,7 +790,7 @@ The Settings modal (the gear button) persists per-user UI choices to `~/.mulmote
 
 ![The Settings modal — a sidebar of grouped sections beside the one being edited](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/settings-tabs.png)
 
-*Open it from the gear button in the toolbar. The **sidebar** groups the sections — Appearance, Projects, Header & launch, Input, Models & servers, Notifications, Integrations, Sessions, Help — and one is on screen at a time; on a phone the sidebar becomes a picker above the section. The interface is available in **English, 日本語, 简体中文, 繁體中文 and 한국어**: it follows your browser's language unless you pick one under **Language** (per browser, like the theme). Translated so far: this modal, the grid's status words, and every button's hover tip and screen-reader label; the rest of the app's words are still English. Under the title, a **Version** row shows what is running: the version from the shipped `package.json`, plus a `commit <sha>` chip on a git checkout — there the version is only whatever was last released, so the commit is what identifies the build. When something newer exists, the row is followed by the header badge's update notice, command included. Pick a **theme**, set the **terminal font size**, **font** and **scroll speed** (and whether sending **returns to the latest output**), set a custom **attention sound**, list the repos the cross-repo **PRs & Issues** view should aggregate, add **launch commands** for grid cells, register your own **MCP servers**, and turn on the switches for what this app writes on your behalf — **issue work comments**, the **PR clone footer**, the **closing summary**, the **decision digest**, the **dev worklog** — no need to hand-edit the config file. Four settings stay with their skill because a form would be the wrong tool for them (`keymap`, `themes`, `providers`, `buttons`/`chips`); Settings shows what each is doing now and launches that skill. Note that **theme, font size, scroll speed and the return-to-latest switch are stored per browser** (they're display preferences, so a phone and a desktop keep their own); the rest live in `~/.mulmoterminal/config.json` and are shared by every client.*
+*Open it from the gear button in the toolbar. The **sidebar** groups the sections — Appearance, Projects, Header & launch, Input, Models & servers, Notifications, Integrations, Sessions, Help — and one is on screen at a time; on a phone the sidebar becomes a picker above the section. The interface is available in **English, 日本語, 简体中文, 繁體中文 and 한국어**: it follows your browser's language unless you pick one under **Language** (per browser, like the theme). Translated so far: this modal, the grid's status words, and every button's hover tip and screen-reader label; the rest of the app's words are still English. Under the title, a **Version** row shows what is running: the version from the shipped `package.json`, plus a `commit <sha>` chip on a git checkout — there the version is only whatever was last released, so the commit is what identifies the build. When something newer exists, the row is followed by the header badge's update notice, command included. Pick a **theme**, set the **terminal font size**, **font** and **scroll speed** (and whether sending **returns to the latest output**), set a custom **attention sound**, list the repos the cross-repo **PRs & Issues** view should aggregate, add **launch commands** for grid cells, register your own **MCP servers**, and turn on the switches for what this app writes on your behalf — **issue work comments**, the **PR clone footer**, the **closing summary**, the **decision digest**, the **dev worklog** — no need to hand-edit the config file. Three settings stay with their skill because a form would be the wrong tool for them (`keymap`, `themes`, `buttons`/`chips`); Settings shows what each is doing now and launches that skill. Backends (`providers`), custom agents and accounts are added and removed in **Models and backends**. Note that **theme, font size, scroll speed and the return-to-latest switch are stored per browser** (they're display preferences, so a phone and a desktop keep their own); the rest live in `~/.mulmoterminal/config.json` and are shared by every client.*
 
 | Field        | Meaning |
 | ------------ | ------- |
@@ -799,7 +812,7 @@ The Settings modal (the gear button) persists per-user UI choices to `~/.mulmote
 | `pushKinds` | Which moments push: `"finished"` (a turn ended, ✅) and/or `"waiting"` (the agent stopped to ask — a permission prompt or a question, ❓, **once per prompt**). Omit to keep both; `[]` for none. A kind added in a later version stays off until you tick it. |
 | `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). Editable in Settings → **Sessions and background tasks**. |
 | `worklogIntervalHours` | Worklog cadence in hours (default `6`, clamped to `1`–`168`). A stepper in the same Settings section covers the range. |
-| `feedRefreshEnabled` | `false` stops the hourly **collection/feed refresh** (one scheduled task per root — the workspace and every saved project directory). **On by default**; only an explicit `false` turns it off, so an existing config keeps the behaviour it has. Takes effect at the next server start — the scheduler registers once at boot. Feeds still refresh on demand. Checkbox in Settings → **Sessions**. |
+| `feedRefreshEnabled` | `false` stops the hourly **collection/feed refresh** (one scheduled task per root — the workspace and every saved project directory). **On by default**; only an explicit `false` turns it off, so an existing config keeps the behaviour it has. Saved from Settings (or any `POST /api/config`), it applies at once — the running scheduler rebuilds its built-in tasks; a hand-edit applies after **Settings → Reload config file** (or a restart). Feeds still refresh on demand. Checkbox in Settings → **Sessions**. |
 | `calendarSyncEnabled` | `false` stops the hourly **Google Calendar sync** (pulls changed events into collections that declare a calendar). Same default and the same restart rule as `feedRefreshEnabled`; calendar collections still sync on demand. Checkbox in the same Settings section. With both off and `worklogEnabled` off, no **built-in** task is registered. Your own tasks in `config/scheduler/tasks.json` are unaffected — these switches do not touch them, and an enabled one still registers and still runs the tick loop. Only when there is no enabled user task either does the scheduler stop writing its state file and run logs. |
 | `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). Settings → **Terminal keys** offers both, worded as behaviour. |
 | `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. There is a checkbox in Settings → **Terminal keys**, applied at once; a hand edit of the file needs a **server restart, then a tab reload** (the server reads this file once at startup, and the browser reads the value from it on load). 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). |
@@ -811,6 +824,7 @@ The Settings modal (the gear button) persists per-user UI choices to `~/.mulmote
 | `autoDirIcon` | Whether a project that sets no `icon` shows the favicon its repository already ships (`public/favicon.svg`, `apple-touch-icon.png`, a web manifest — first hit wins, ordered by how the image survives at 14px). **On by default**; Settings → **Directory appearance** has the switch. A single project opts out with `"icon": false` in its own `.mulmoterminal.json`, which this does not override. A key that was written and got it wrong shows nothing rather than falling back — a broken setting has to look broken. `true` / `false` only. |
 | `cockpitLines` | `{ summary, prompt, response }` — how many lines each **cockpit-roster** row shows before it clamps (default `2` / `2` / `3`, each clamped to `1`–`20`). Raising them trades how many sessions fit on screen for reading a long one in place. Three steppers in Settings → **Waiting rows**. |
 | `showLoadAverage` | Whether the grid header draws this machine's **load average** beside the 5h / 7d usage windows, as a percentage of its cores (`load 334%` = a 20-core machine with 66.8 runnable processes). **On by default**; amber at 100%, red at 200%, hover for the raw 1 / 5 / 15-minute figures. Settings → **Grid header read-outs** has the switch. A host that keeps no load average (Windows) shows nothing rather than `0%`, whatever this says. `true` / `false` only. |
+| `remoteServer` | **Experimental.** The server runs on another machine than your browser (an SSH tunnel — [guide](https://receptron.github.io/mulmoterminal/guide/en/remote.html)): the actions that would act on the server's screen (the file dialog, the file manager, the OS app) are hidden or say why, and a dropped file is always uploaded. **Off unless `true`**; Settings → **Sessions and background tasks** has the box (or set it in the server's config). |
 | `fontFamily` | The **terminal font** every session renders in — a CSS font-family stack, e.g. `"'Cica', 'MS Gothic', monospace"`. Set it in Settings → **Terminal font**, applied at once; editing the file instead needs a **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
@@ -829,9 +843,14 @@ are items in the **path menu** (click the directory path on the terminal header)
 set** with your list (it is not merged on top), so listing your own — even a **shorter** one — is how
 you drop, reorder, or swap them.
 A button has an `id`, `label`, and a `run` of `"shell"` (run a command), `"input"` (send text to the
-agent), `"open"`, or `"action"` (act on the cell itself — `action: "restart"` ends the agent and
-starts it again in the same cell on the same conversation, which is how an MCP / config / plugin
-change takes effect; it costs a resume and asks nothing first). An `open` button targets one of `url` / `reveal` (OS file manager) / `files`
+agent), `"open"`, or `"action"` (act on the cell itself, named like the `keymap` actions so one operation is
+a button, a key and a command-palette entry — `action: "terminal-restart"` ends the agent and starts
+it again in the same cell on the same conversation, which is how an MCP / config / plugin change
+takes effect; it costs a resume and asks nothing first. `"terminal-new-here"` opens the launch panel
+on the cell's directory, and `"pane-files"` / `"pane-prompts"` / … / `"terminal-timeline"` /
+`"terminal-talk"` / `"terminal-park"` / `"terminal-copy-code"` / `"terminal-insert-path"` / `"terminal-reveal"` /
+`"terminal-voice"` / `"terminal-diff"` / `"terminal-note"` do what the cell's menus and buttons do, and `"screen-*"` / `"settings-open"` /
+`"sound-toggle"` / `"view-toggle"` / `"order-*"` / `"page-next"` / `"page-prev"` do what the toolbar and the page tabs do; the old name `"restart"` still works). An `open` button targets one of `url` / `reveal` (OS file manager) / `files`
 (in-app explorer) / `view` (a built-in overlay) / `terminal` (a dir → a new cell running `$SHELL`,
 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).
@@ -891,7 +910,7 @@ channel is connected (its Google sign-in supplies the notification auth). With R
 disconnected, or with no device registered, the toggle is a no-op.
 
 **Dev worklog (cross-clone).** Set `worklogEnabled: true` in
-`~/.mulmoterminal/config.json` (and **restart** — the scheduler reads its tasks at boot)
+`~/.mulmoterminal/config.json` (or switch it on in Settings, which applies at once; after a hand-edit use Settings → **Reload config file**)
 to register a built-in scheduled task. Every `worklogIntervalHours` (default 6) it spawns
 a Claude session that reviews the work you did across **all your saved working dirs**
 (`cwdPresets`) since it last ran, and writes it up as a short manager-style report.
@@ -1324,11 +1343,13 @@ or changed (amber), and a notch where lines were removed, as VS Code's gutter sh
 to date as you type. **Changes** in the header also shows the removed lines in place, as a unified
 diff. Nothing is marked for a file outside git or one not yet committed.
 
-**HTML pages and images show in the pane too.** An `.html` file has a **Preview** like a Markdown
+**HTML pages, images, PDFs, video and audio show in the pane too.** An `.html` file has a **Preview** like a Markdown
 file: the page itself, sandboxed as presentHtml pages are — its scripts run on an opaque origin with
 no fetch/XHR; images and the curated CDN list still load, and so does an image it links beside it,
-while a relative stylesheet or script does not. An `.svg` previews as the picture it draws, and a PNG, JPEG, GIF or WebP opens as the image
-rather than as "not text". A path to any of these clicked in terminal output opens in the pane when
+while a relative stylesheet or script does not. An `.svg` previews as the picture it draws, a PNG, JPEG, GIF or WebP opens as the image
+rather than as "not text", a PDF opens in a frame, and a video or audio file plays with the
+browser's controls, seeking by range rather than fetching the whole file. A text file too large to edit
+says so and still offers **Open in OS**. A path to any of these clicked in terminal output opens in the pane when
 it is up, so a chart an agent just wrote stays in the grid. They are served only under the workspace
 or a terminal's directory, like every other file the app hands to the browser.
 

package/bin/cli-args.d.ts

@@ -25,4 +25,5 @@ export interface RunningInstance {
   port: number | null;
 }
 export declare function stopCommandFor(pkgDir: string): string;
+export declare function stopCommandForThis(stopCommand: string, port: number, instances: readonly { port: number | null }[]): string;
 export declare function runningInstancesPrompt(instances: readonly RunningInstance[], stopCommand?: string): string;

package/bin/cli-args.js

@@ -366,6 +366,11 @@ export function saysYes(answer) {
 // they are: npx unpacks into `<cache>/_npx/<hash>/node_modules/mulmoterminal`.
 const NPX_INSTALL = /[/\\]_npx[/\\]/;
 
+/** The stop command the ready banner shows for the server on `port`: the plain one while it is the
+ *  only server, and one narrowed to its port once another is running, which the plain one would stop
+ *  too (#2683). `instances` is the registry, this server included. */
+export const stopCommandForThis = (stopCommand, port, instances) => (instances.some((i) => i.port !== port) ? `${stopCommand} --port ${port}` : stopCommand);
+
 export const stopCommandFor = (pkgDir) => (NPX_INSTALL.test(String(pkgDir)) ? "npx mulmoterminal@latest stop" : "mulmoterminal stop");
 
 export function runningInstancesPrompt(instances, stopCommand = "mulmoterminal stop") {

package/bin/mulmoterminal.js

@@ -14,6 +14,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { computeUpdateNotice, isUpdateCheckDisabled } from "./update-check.js";
 import { detectNpxCacheDir, npxCacheHintLines } from "./npx-cache-hint.js";
+import { configuredRemoteServer, sshTunnelHintLines } from "./ssh-hint.js";
 import { planAfterServerExit } from "./server-supervision.js";
 import { waitUntilReady } from "./wait-ready.js";
 import {
@@ -29,6 +30,7 @@ import {
   secondInstancePrompt,
   runningInstancesPrompt,
   stopCommandFor,
+  stopCommandForThis,
   SECOND_INSTANCE_NOTE,
   nodeMeetsMinimum,
   unsupportedNodeMessage,
@@ -109,6 +111,17 @@ function readConfiguredDefaultAgent() {
   }
 }
 
+// The experimental `remoteServer` (#2669): the browser is on another machine, so the launcher opens
+// none here even when started without SSH (a service, a remote desktop). A missing or unreadable
+// file is simply "not set".
+function readRemoteServer() {
+  try {
+    return configuredRemoteServer(JSON.parse(readFileSync(CONFIG_FILE, "utf8")));
+  } catch {
+    return false;
+  }
+}
+
 // The command for `agent`, honouring its `<AGENT>_BIN` override.
 //
 // The override is the point rather than a detail: the gate used to look for the literal word
@@ -478,11 +491,16 @@ async function choosePort(requested, explicit) {
 //
 // `url` is where the BROWSER goes and `note` is what launchTarget wants said about that choice —
 // two different facts since #1889, and the note is null whenever the URL already covers it.
-function announceReady(url, note, noOpen) {
-  printReadyBanner(url, STOP_COMMAND);
+function announceReady(url, note, noOpen, sshHint, port) {
+  printReadyBanner(url, stopCommandForThis(STOP_COMMAND, port, liveInstances()));
   // Either the address a widened bind serves other machines on, or why the browser was NOT sent
   // to `localhost`. Null whenever the URL above already said everything.
   if (note) log(note);
+  // Over SSH the browser is on the other machine (see ssh-hint.js): say how to reach it, open nothing.
+  if (sshHint) {
+    sshHint.forEach((line) => log(line));
+    return;
+  }
   if (noOpen) return;
   try {
     // The command is a hardcoded literal; url is built by browserUrl from a numeric port, so it
@@ -549,7 +567,9 @@ function runServer({ port, probedAddress, localhostIsUnambiguous, noOpen, launch
       readyStarted = true;
       const localhostIsOurs = localhostIsUnambiguous && serverSaysLocalhostIsOurs !== false;
       const { url, note } = launchTarget(reachHost, port, localhostIsOurs);
-      cancelReady = waitUntilReady(port, () => announceReady(url, note, noOpen), { host: reachHost });
+      cancelReady = waitUntilReady(port, () => announceReady(url, note, noOpen, sshTunnelHintLines(process.env, port, readRemoteServer()), port), {
+        host: reachHost,
+      });
     };
     // The same message answers a second question now: whether this lifetime ever bound at all,
     // which is what a restart is allowed to depend on. Recorded BEFORE the address is looked at —

package/bin/ssh-hint.d.ts

@@ -0,0 +1,3 @@
+export declare function inSshSession(env: Record<string, string | undefined>): boolean;
+export declare const configuredRemoteServer: (config: unknown) => boolean;
+export declare function sshTunnelHintLines(env: Record<string, string | undefined>, port: number, remoteServer?: boolean): string[] | null;

package/bin/ssh-hint.js

@@ -0,0 +1,32 @@
+// A launcher started over SSH is on a machine whose screen nobody is looking at: the browser that
+// should open this is on the other end of the connection. So it does not try to open one here — on
+// a remote Mac that would put a window on a display no one sees — and it says how to reach the
+// server from there instead: an SSH port forward, the route the FAQ recommends. Nothing here reads
+// the process; the caller passes its environment.
+
+/** Whether this process runs inside an SSH login. sshd sets both variables; either is enough. */
+export function inSshSession(env) {
+  return Boolean(env.SSH_CONNECTION || env.SSH_CLIENT);
+}
+
+/** The experimental `remoteServer` out of a parsed `~/.mulmoterminal/config.json`: true only for a
+ *  literal `true`, like the server's own reading of it (common/remoteServer.ts). */
+export const configuredRemoteServer = (config) => config !== null && typeof config === "object" && config.remoteServer === true;
+
+/**
+ * The lines that tell someone on another machine how to open this server, or null when the browser
+ * is expected here: not an SSH login, and `remoteServer` not set. The host is left for them to fill
+ * in: SSH_CONNECTION names the address THIS side answered on, which behind NAT or a container is not
+ * one their machine can reach.
+ */
+export function sshTunnelHintLines(env, port, remoteServer = false) {
+  const ssh = inSshSession(env);
+  if (!ssh && !remoteServer) return null;
+  const user = env.USER || env.LOGNAME || "<user>";
+  const why = ssh ? "Started over SSH" : "remoteServer is set in config.json";
+  return [
+    `${why}, so no browser is opened here. On your own machine, run:`,
+    `  ssh -N -L ${port}:127.0.0.1:${port} ${user}@<this-host>`,
+    `then open http://localhost:${port} there.`,
+  ];
+}

package/bin/stop.d.ts

@@ -16,10 +16,12 @@ export interface StopResult {
   stubborn: StubbornInstance[];
   unconfirmed: InstanceEntry[];
 }
-export type StopArgs = { help: true } | { error: string } | { force: boolean };
+export type StopArgs = { help: true } | { error: string } | { force: boolean; port: number | null };
 
 export declare const STOP_USAGE: string;
 export declare function parseStopArgs(args: readonly string[]): StopArgs;
+export declare function selectByPort(instances: readonly InstanceEntry[], port: number | null): InstanceEntry[];
+export declare function noServerOnPortReport(port: number, instances: readonly InstanceEntry[]): string[];
 export interface ConfirmDeps {
   owners?: (port: number) => Promise<number[] | null>;
 }

package/bin/stop.js

@@ -14,7 +14,7 @@
 // Windows user find or kill anything.
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { stopCommandFor } from "./cli-args.js";
+import { parsePortArg, stopCommandFor } from "./cli-args.js";
 import { isProcessAlive, liveInstances } from "./instances.js";
 import { portOwners } from "./port-owner.js";
 
@@ -140,10 +140,11 @@ export function stopReport({ stopped, stubborn, unconfirmed }, platform = proces
 export const stopExitCode = ({ stubborn, unconfirmed }) => (stubborn.length + unconfirmed.length ? 1 : 0);
 
 export const STOP_USAGE = [
-  "Usage: mulmoterminal stop [--force]",
+  "Usage: mulmoterminal stop [--port <port>] [--force]",
   "",
   "Stops every running MulmoTerminal server on this machine, from any terminal.",
   "",
+  "  --port    Stop only the server on that port (the one at http://localhost:<port>).",
   "  --force   Also stop a registered server that is no longer answering. Off by default:",
   "            a server that crashed leaves its entry behind, and that pid may since have",
   "            been given to an unrelated program.",
@@ -153,9 +154,26 @@ export const STOP_USAGE = [
  *  argument handling is testable — and so `stop --help` can never be read as "stop everything". */
 export function parseStopArgs(args) {
   if (args.includes("--help") || args.includes("-h")) return { help: true };
-  const unknown = args.filter((a) => a !== "--force");
+  const portAt = args.indexOf("--port");
+  const portArgs = portAt === -1 ? [] : [portAt, portAt + 1];
+  const unknown = args.filter((a, i) => a !== "--force" && !portArgs.includes(i));
   if (unknown.length) return { error: `Unknown argument for stop: ${unknown.join(" ")}` };
-  return { force: args.includes("--force") };
+  const force = args.includes("--force");
+  if (portAt === -1) return { force, port: null };
+  // The launcher's own reading of --port, so the two accept the same values. The environment's
+  // PORT is not consulted: a `stop` narrowed by a variable nobody typed here would surprise.
+  const parsed = parsePortArg(args, {}, null);
+  return "error" in parsed ? { error: parsed.error } : { force, port: parsed.port };
+}
+
+/** The servers a `stop` is about: all of them, or only the one on `port` (#2683). */
+export const selectByPort = (instances, port) => (port === null ? instances : instances.filter((i) => i.port === port));
+
+/** What `stop --port` says when nothing is registered there — and what IS running, since a wrong
+ *  port is the likeliest reason. */
+export function noServerOnPortReport(port, instances) {
+  const running = instances.map(describeInstance);
+  return [`No MulmoTerminal server is running on port ${port}.`, running.length ? `Running: ${running.join(", ")}` : "MulmoTerminal is not running."];
 }
 
 export async function runStop(args = []) {
@@ -169,7 +187,16 @@ export async function runStop(args = []) {
     console.error(STOP_USAGE);
     process.exit(2);
   }
-  const result = await stopInstances(liveInstances(), { force: parsed.force });
-  stopReport(result).forEach((line) => console.log(line));
+  const all = liveInstances();
+  const targets = selectByPort(all, parsed.port);
+  // Nothing on that port is the state asked for, like "nothing was running": not a failure.
+  if (parsed.port !== null && !targets.length) {
+    noServerOnPortReport(parsed.port, all).forEach((line) => console.log(line));
+    process.exit(0);
+  }
+  const result = await stopInstances(targets, { force: parsed.force });
+  // A retry must name the same server, or `--force` would stop every one.
+  const stopCommand = parsed.port === null ? selfStopCommand() : `${selfStopCommand()} --port ${parsed.port}`;
+  stopReport(result, process.platform, stopCommand).forEach((line) => console.log(line));
   process.exit(stopExitCode(result));
 }

package/blueprints/ask/skills/keep/SKILL.md

@@ -18,7 +18,7 @@ Otherwise add to `FAQ.md` in this folder (create it if there is none). **Add aft
 never edit or reorder what is there** — the check compares the beginning of the file with what it held
 before. For each question: the question as a `##` heading, word for word; the answer; and where it is
 written (the document, and the place named as in the answer: 第4条第2項, or a section's heading in 「」 —
-never chaff's `h1.3`). For a question the documents do not answer, say so — that is worth keeping
+in an English FAQ, in "…" — never chaff's `h1.3`). For a question the documents do not answer, say so — that is worth keeping
 too.
 
 ## Done when

package/blueprints/cloudflare/checks/page-renders.sh

@@ -15,12 +15,23 @@ RENDER_LIMIT_SECONDS=60
 work=$(mktemp -d)
 "$chrome" --headless=new --disable-gpu --no-first-run --user-data-dir="$work/profile" --virtual-time-budget=15000 --dump-dom "$url" >"$work/dom.html" 2>/dev/null &
 pid=$!
-trap 'kill "$pid" 2>/dev/null || true; rm -rf "$work"' EXIT
+# Chrome can still be writing its profile when it is stopped, and under set -e a failed rm in this trap would turn a page
+# that rendered into a failed check; the scratch folder is left behind instead.
+trap 'kill "$pid" 2>/dev/null || true; rm -rf "$work" 2>/dev/null || true' EXIT
 waited=0
 until grep -q "</html>" "$work/dom.html" 2>/dev/null || [ "$waited" -ge "$RENDER_LIMIT_SECONDS" ] || ! kill -0 "$pid" 2>/dev/null; do
   sleep 1
   waited=$((waited + 1))
 done
+# A Chrome that crashed before printing the page says nothing about the app: like no Chrome, it cannot judge.
+if ! grep -q "</html>" "$work/dom.html" 2>/dev/null && ! kill -0 "$pid" 2>/dev/null; then
+  status=0
+  wait "$pid" || status=$?
+  if [ "$status" -ne 0 ]; then
+    echo "Chrome ($chrome) exited with status $status before printing the page; could not confirm that $url renders" >&2
+    exit 0
+  fi
+fi
 node -e 'let s="";process.stdin.on("data",(c)=>s+=c).on("end",()=>{
   const body = (s.match(/<body[^>]*>([\s\S]*)<\/body>/i) || [, ""])[1];
   const text = body.replace(/<(script|style|noscript)[\s\S]*?<\/\1>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();

package/blueprints/cloudflare/skills/spec/SKILL.md

@@ -17,7 +17,7 @@ The answers are in `.blueprint/answers.json`; the prompt names both pack directo
 4. Something the answers do not settle is not guessed: write "未定" and add a line to
    `.blueprint/open-questions.md` saying what is needed and why it matters.
 5. Append both packs' `security/` checklists under a heading "必ず詰める点", unchanged.
-6. Write in the language the user answered in. Nothing is built in this step; the next step stops for the user
+6. Write in the language the build's prompt says the user reads (without one, the language the user answered in). Nothing is built in this step; the next step stops for the user
    to read this spec.
 
 Done when the check passes: `.blueprint/spec.md` exists and no `{{` placeholder is left in it.

package/blueprints/compare/checks/articles.d.mts

@@ -0,0 +1,8 @@
+// Types for articles.mjs, which the pack runs with plain node and the specs import.
+export type Article = { readonly address: string; readonly label: string; readonly body: string };
+export type Row = { readonly old?: string | null; readonly new?: string | null; readonly change: string; readonly what?: string };
+
+export declare const CHANGES: readonly string[];
+export declare const articlesIn: (tree: unknown, text: string) => Article[];
+export declare const mentions: (text: string, name: string) => boolean;
+export declare const comparisonProblems: (rows: unknown, olds: readonly Article[], news: readonly Article[]) => string[];

package/blueprints/compare/checks/articles.mjs

@@ -0,0 +1,109 @@
+// Two versions of a document, article by article: each article's body as chaff's tree spans it, and whether the
+// pairing an agent wrote says the truth about them. What changed is read by the agent; whether anything changed
+// at all is decided here, by comparing text, so "unchanged" cannot be written over a changed article or the
+// other way round.
+
+export const CHANGES = ["same", "changed", "added", "removed"];
+
+// Spacing aside: a reflowed line is not a change to what an article says.
+const squash = (text) => String(text).replace(/\s+/gu, "");
+
+const articleNodes = (node) => [
+  ...(node?.kind === "article" && typeof node.address === "string" && node.address !== "" ? [node] : []),
+  ...(Array.isArray(node?.children) ? node.children.flatMap(articleNodes) : []),
+];
+
+// The article's own number (第4条, Article 4) is where it sits, not what it says: a renumbered article is the same.
+const withoutLabel = (text, label) => {
+  const trimmed = text.trimStart();
+  return typeof label === "string" && label !== "" && trimmed.startsWith(label) ? trimmed.slice(label.length) : trimmed;
+};
+
+/** Each article of `text` as `tree` (chaff tree --format json) reads it: its address, label and body. */
+export const articlesIn = (tree, text) =>
+  articleNodes(tree).map((node) => {
+    const whole = String(text).slice(node.span?.start ?? 0, node.span?.end ?? 0);
+    return { address: node.address, label: node.attrs?.label ?? node.address, body: squash(withoutLabel(whole, node.attrs?.label)) };
+  });
+
+const rowShape = (row, index) => {
+  if (row === null || typeof row !== "object") return `row ${index + 1} is not an object`;
+  if (!CHANGES.includes(row.change)) return `row ${index + 1}: "change" must be one of ${CHANGES.join(", ")}`;
+  const has = (side) => typeof row[side] === "string" && row[side] !== "";
+  const wanted = { same: [true, true], changed: [true, true], added: [false, true], removed: [true, false] }[row.change];
+  if (has("old") !== wanted[0] || has("new") !== wanted[1])
+    return `row ${index + 1}: a "${row.change}" row has ${wanted[0] ? "an" : "no"} "old" and ${wanted[1] ? "a" : "no"} "new"`;
+  if (row.change === "changed" && !(typeof row.what === "string" && row.what.trim() !== "")) return `row ${index + 1}: say in "what" what changed`;
+  return null;
+};
+
+// Every article of a version in exactly one row, and no row naming one that is not there.
+const coverage = (rows, articles, side, version) => {
+  const named = rows.map((row) => row[side]).filter((address) => typeof address === "string" && address !== "");
+  const known = articles.map((article) => article.address);
+  return [
+    ...known.filter((address) => !named.includes(address)).map((address) => `${version} ${labelOf(articles, address)}: in no row`),
+    ...[...new Set(named.filter((address, index) => named.indexOf(address) !== index))].map(
+      (address) => `${version} ${labelOf(articles, address)}: in more than one row`,
+    ),
+    ...named.filter((address) => !known.includes(address)).map((address) => `${version} has no article at ${address}`),
+  ];
+};
+
+const labelOf = (articles, address) => articles.find((article) => article.address === address)?.label ?? address;
+
+// A pair said to be the same must read the same, and one said to have changed must not.
+const truth = (row, olds, news) => {
+  if (row.change !== "same" && row.change !== "changed") return null;
+  const [was, now] = [olds.find((article) => article.address === row.old), news.find((article) => article.address === row.new)];
+  if (!was || !now) return null;
+  const pair = `${labelOf(olds, row.old)} → ${labelOf(news, row.new)}`;
+  if (row.change === "same" && was.body !== now.body) return `${pair}: written "same", but the text differs`;
+  if (row.change === "changed" && was.body === now.body) return `${pair}: written "changed", but the text is the same`;
+  return null;
+};
+
+// A provision removed from the old version and added to the new one word for word is one that moved: a pair missed.
+const missedPairs = (rows, olds, news) => {
+  const bodyOf = (articles, address) => articles.find((article) => article.address === address)?.body;
+  const added = rows.filter((row) => row.change === "added").map((row) => row.new);
+  return rows
+    .filter((row) => row.change === "removed")
+    .flatMap((row) => {
+      const body = bodyOf(olds, row.old);
+      const twin = added.find((address) => body !== undefined && bodyOf(news, address) === body);
+      return twin === undefined ? [] : [`${labelOf(olds, row.old)} (removed) and ${labelOf(news, twin)} (added) read the same: pair them as "same"`];
+    });
+};
+
+/** What is wrong with `rows` (the pairing) for the articles `olds` and `news`. */
+export const comparisonProblems = (rows, olds, news) => {
+  if (!Array.isArray(rows)) return ['the pairing needs a "rows" list'];
+  const shapes = rows.map(rowShape).filter((problem) => problem !== null);
+  if (shapes.length > 0) return shapes;
+  return [
+    ...coverage(rows, olds, "old", "the old version"),
+    ...coverage(rows, news, "new", "the new version"),
+    ...rows.map((row) => truth(row, olds, news)).filter((problem) => problem !== null),
+    ...missedPairs(rows, olds, news),
+  ];
+};
+
+// Where a name stops and another article's number would go on. A name ending in a letter or digit ("Article 1")
+// stops at a word boundary, so "Article 12", "Article 1bis" and "Article 1-2" are other words. A name ending in any
+// other character (第1条) goes on only into a branch number: a digit, or の/之/ノ with a numeral (第1条の2,
+// 第二十一条の二) — 「第1条の委託料」 still names 第1条, and so does 「第1条第2項」.
+// Letters of the Latin script (full-width ones too) and decimal digits of any width: kana and kanji end the word.
+const WORD_END = /[\p{Script=Latin}\p{Nd}]$/u;
+// A dash of any kind, a point or a slash between two word characters joins them into one number (1-2, 1–2, 1.2, 1/2).
+const WORD_GOES_ON = /^(?:[\p{Script=Latin}\p{Nd}]|[\p{Pd}.．/／][\p{Script=Latin}\p{Nd}])/u;
+const BRANCH_GOES_ON = /^(?:[0-9０-９]|[の之ノ][0-9０-９一二三四五六七八九十百千])/u;
+
+/** Whether `text` names the article `name`: a match that goes on into a longer number names another article. */
+export const mentions = (text, name) => {
+  const goesOn = WORD_END.test(name) ? WORD_GOES_ON : BRANCH_GOES_ON;
+  const source = String(text);
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  const hits = [...source.matchAll(new RegExp(escaped, "gu"))].map((match) => match.index ?? 0);
+  return hits.some((index) => !goesOn.test(source.slice(index + name.length)));
+};

package/blueprints/compare/checks/base.mjs

@@ -0,0 +1,12 @@
+// The docs base holds the helpers every usecase on it shares (running chaff, reading Markdown sections).
+// A usecase loads them from BLUEPRINT_BASE, which the executor sets for every check.
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+if (!process.env.BLUEPRINT_BASE) {
+  console.error("BLUEPRINT_BASE is not set: run this check through the blueprint executor");
+  process.exit(1);
+}
+
+/** The URL of a module in the docs base's checks/, for `await import(...)`. */
+export const fromBase = (file) => pathToFileURL(join(process.env.BLUEPRINT_BASE, "checks", file)).href;

package/blueprints/compare/checks/comparison.mjs

@@ -0,0 +1,22 @@
+// The pair step's check: .blueprint/comparison.json pairs every article of the old version with its article in the
+// new one, and says truly whether each changed. Writes the pairing as a person reads it at the gate, and records
+// what was checked so the report can tell the documents and the pairing were not touched since.
+import { writeFileSync } from "node:fs";
+import { fromBase } from "./base.mjs";
+import { comparisonProblems } from "./articles.mjs";
+import { comparisonText } from "./comparisonView.mjs";
+import { readVersions } from "./versions.mjs";
+const { fail, readJson } = await import(fromBase("chaff.mjs"));
+const { fingerprint } = await import(fromBase("documents.mjs"));
+
+const PAIRING = ".blueprint/comparison.json";
+const READABLE = ".blueprint/comparison.txt";
+const CHECKED = ".blueprint/.comparison-checked";
+
+const versions = readVersions();
+const rows = readJson(PAIRING, '{ "rows": [{ "old", "new", "change", "what" }] }')?.rows;
+const problems = comparisonProblems(rows, versions.old.articles, versions.new.articles);
+if (problems.length > 0) fail(`${PAIRING}:\n  ${problems.join("\n  ")}`);
+writeFileSync(READABLE, comparisonText(rows, versions.old.articles, versions.new.articles));
+writeFileSync(CHECKED, JSON.stringify({ old: versions.old.print, new: versions.new.print, pairing: fingerprint(PAIRING) }) + "\n");
+console.log(`${rows.length} pair(s): every article accounted for`);

package/blueprints/compare/checks/comparisonView.d.mts

@@ -0,0 +1,4 @@
+// Types for comparisonView.mjs, which the pack runs with plain node and the specs import.
+import type { Article, Row } from "./articles.mjs";
+
+export declare const comparisonText: (rows: readonly Row[], olds: readonly Article[], news: readonly Article[]) => string;

package/blueprints/compare/checks/comparisonView.mjs

@@ -0,0 +1,14 @@
+// The pairing as plain text a person reads at the gate: one line a pair, the old article first. The marks are the
+// ones a diff uses, so they read the same in any language: "=" unchanged, "~" changed, "+" added, "-" removed.
+
+const MARKS = { same: "=", changed: "~", added: "+", removed: "-" };
+
+const labelOf = (articles, address) => (typeof address === "string" ? (articles.find((article) => article.address === address)?.label ?? address) : "");
+
+const lineOf = (row, olds, news) => {
+  const pair = `${labelOf(olds, row.old)} → ${labelOf(news, row.new)}`.trim();
+  const what = typeof row.what === "string" && row.what.trim() !== "" ? `  ${row.what.split("\n").join(" ").trim()}` : "";
+  return `${MARKS[row.change] ?? "?"} ${pair}${what}`;
+};
+
+export const comparisonText = (rows, olds, news) => [...rows.map((row) => lineOf(row, olds, news)), ""].join("\n");