mulmoterminal 7.0.0 → 7.2.0

package/README.md

@@ -176,15 +176,25 @@ than as bytes (files within the session's working directory only):
 | `.json` | **indented** in a new tab (Chrome and Safari otherwise show one long line) |
 | `.csv` `.tsv` | a **table** in a new tab, with a sticky header that scrolls inside its own box |
 | source, config, logs, and `.txt` — 46 extensions | the app's own **Files** view (`/files?path=`), where CodeMirror highlights it, the tree is right there, and it can be edited |
-| images, PDF, SVG, HTML, video | raw bytes in a new tab, which the browser renders better than an editor would |
+| `.html` `.htm` | the **rendered page** in a new tab, under the same sandboxed policy as the Files pane's Preview: its scripts run at an opaque origin with no fetch or XHR (so they cannot reach the app or its API), and an image beside it loads by its relative path (a relative stylesheet or script does not). The raw route answers `.html` as plain text, so opening one there showed its source |
+| images, PDF, SVG, video, audio | raw bytes in a new tab, which the browser renders better than an editor would |
 | everything else — `.xlsx`, `.docx`, `.zip`, a `Makefile` | the app's own **Files** view. A tab cannot display these, so opening one there is not a view — it is a download starting with no warning. The pane names the file and offers **Open in OS**, which hands it to the application that owns it (Excel for an `.xlsx`) |
 
+**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`,
+`.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 the last one, since the pane is the same editor plus a Markdown preview. 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 the raw-bytes
-row, where it would only show an empty editor.
+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
+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.
 
 Highlighting in the Files view covers the JS/TS family, JSON and Markdown (the modes
 `cmEditor.ts` bundles); other languages open as plain text.
@@ -298,7 +308,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.
 
@@ -624,6 +635,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
@@ -767,7 +789,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 |
 | ------------ | ------- |
@@ -789,7 +811,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). |
@@ -801,6 +823,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`**; 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
@@ -819,9 +842,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).
@@ -881,7 +909,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.
@@ -1244,7 +1272,12 @@ rooted at **that terminal's project directory** — so after Claude says "wrote
 you can jump straight there to read or edit it. The left pane is a lazy-loaded directory
 tree; clicking a file opens it in a **CodeMirror** editor (Markdown / JS-TS / JSON
 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.
+that renders via the server's sandboxed `…/md` HTML; a `.csv` / `.tsv` previews as a table (the
+same `…/table` document a clicked path opens, in the app's colours), and an `.html` / `.svg` as the
+page or picture it is. **Save** (or ⌘/Ctrl-S) writes back. **History** lists the versions the pane
+kept of the file (in `~/.mulmoterminal/backups`, taken when it is opened or reloaded here and before a save
+here replaces it — the newest few), to compare with the buffer or restore as an undoable edit (unsaved edits
+are kept as a version first).
 
 **The open view follows the file on disk.** When an agent in another cell — or any editor —
 rewrites what you are looking at, the editor and the preview catch up on their own; there is
@@ -1266,11 +1299,11 @@ shrinks the pane rather than reflowing xterm into garbage. It works in both zoom
 terminals, and whether it's open plus how wide it is are remembered per browser.
 
 **Coming back looks the way you left it.** The pane remembers the open file, the directories
-you had expanded, and — for a Markdown file — whether you were reading it in **Preview** or
+you had expanded, and — for a file with a Preview — whether you were reading it in **Preview** or
 editing it: per cell while the session lasts, and per directory across a browser reload (the
 first pane to open on that directory claims it, so a second terminal in the same repository
 starts on its own empty tree). A remembered Preview only comes back over that same file while
-it is still Markdown the server can render; anything else opens in the editor.
+it is still a file the pane can preview; anything else opens in the editor.
 
 It comes back to **where** you were, too: the line at the top of the editor, the line the caret was
 on, and how far down the tree was scrolled. The top line matters on its own — scrolling moves

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/checks/replies.mjs

@@ -9,7 +9,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { fromBase } from "./base.mjs";
 const { fail, quotationProblems, readJson } = await import(fromBase("chaff.mjs"));
 const { digest, documentSource, documentsNamed, fingerprint } = await import(fromBase("documents.mjs"));
-const { headingsOf, namesPlace } = await import(fromBase("places.mjs"));
+const { headingsIn, namesPlace, placeNamesIn, treeOf } = await import(fromBase("places.mjs"));
 
 const REPLIES = ".blueprint/replies.json";
 const REPLIES_PAGE = ".blueprint/replies.md";
@@ -30,13 +30,25 @@ if (answers?.keep === KEEP && documents.includes(FAQ)) fail(`${FAQ} is one of th
 const indented = (line) => "  " + line;
 const nonEmpty = (value) => typeof value === "string" && value.trim() !== "";
 
-// Read once per document, and only for one of the documents: a source that is not is refused by the quotation check.
-const headingCache = new Map();
-const headingAt = (source, address) => {
+// Each document's tree is read once, and only for one of the documents: a source that is not is refused by the
+// quotation check. From it come a section's heading and a place's name (第4条第2項), either of which names the place.
+const placeCache = new Map();
+const placeAt = (source, address) => {
   const resolved = documentSource(documents)(source);
-  if (!resolved.path) return undefined;
-  if (!headingCache.has(resolved.path)) headingCache.set(resolved.path, headingsOf(resolved.path));
-  return headingCache.get(resolved.path).get(address.trim());
+  if (!resolved.path) return {};
+  if (!placeCache.has(resolved.path)) {
+    const tree = treeOf(resolved.path);
+    placeCache.set(resolved.path, { headings: headingsIn(tree), names: placeNamesIn(tree) });
+  }
+  const { headings, names } = placeCache.get(resolved.path);
+  return { heading: headings.get(address.trim()), name: names.get(address.trim()) };
+};
+
+// The address as written needs no tree; otherwise the heading or the place's name, from the document's tree.
+const answerNames = (answer, citation) => {
+  if (answer.includes(citation.address.trim())) return true;
+  const { heading, name } = placeAt(String(citation.source), citation.address);
+  return namesPlace(answer, citation.address, heading, name);
 };
 
 const replyProblem = (reply) => {
@@ -49,10 +61,7 @@ const replyProblem = (reply) => {
   if (!Array.isArray(citations)) return `${which}: citations must be an array`;
   if (reply.found && citations.length === 0) return `${which}: an answer found in the documents quotes them`;
   if (!citations.every((citation) => nonEmpty(citation?.address))) return `${which}: every quotation needs an "address"`;
-  const unnamed = citations.filter(
-    (citation) =>
-      !reply.answer.includes(citation.address.trim()) && !namesPlace(reply.answer, citation.address, headingAt(String(citation.source), citation.address)),
-  );
+  const unnamed = citations.filter((citation) => !answerNames(reply.answer, citation));
   if (unnamed.length > 0) return `${which}: the answer does not name ${unnamed.map((citation) => citation.address).join(", ")}, which it quotes`;
   if (!reply.found && (!Array.isArray(reply.searched) || !reply.searched.some(nonEmpty))) return `${which}: say what was searched ("searched")`;
   return null;

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/deploy-check.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+# The published Worker serves the build this deploy made: the deploy writes a fresh id to .blueprint/build-id and ships
+# the same id as /blueprint-build.txt, and records the URL it published to in .blueprint/deploy-url. The published app
+# answers /api/health, sends the security headers, and its page renders.
+set -eu
+[ -s .blueprint/deploy-url ] || { echo "missing .blueprint/deploy-url; the deploy step writes the URL it published to" >&2; exit 1; }
+url=$(tr -d ' \n\r' < .blueprint/deploy-url)
+url=${url%/}
+case "$url" in https://*) ;; *) echo ".blueprint/deploy-url is not an https URL: $url" >&2; exit 1 ;; esac
+[ -s .blueprint/build-id ] || { echo "missing .blueprint/build-id; the deploy step writes it before deploying" >&2; exit 1; }
+expected=$(cat .blueprint/build-id)
+served=$(curl -fsS --max-time 20 "$url/blueprint-build.txt")
+[ "$served" = "$expected" ] || { echo "$url serves build $served, this deploy made $expected" >&2; exit 1; }
+curl -fsS --max-time 20 "$url/api/health" | grep -q '"ok":true' || { echo "$url/api/health does not answer {\"ok\":true}" >&2; exit 1; }
+curl -s -D - -o /dev/null --max-time 20 "$url/" | tr -d '\r' | grep -qi '^content-security-policy:' || { echo "$url/ is published without a Content-Security-Policy" >&2; exit 1; }
+sh "$(dirname "$0")/page-renders.sh" "$url/"

package/blueprints/cloudflare/checks/handover.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+# The README tells a non-engineer how to run the app on this computer, how to publish a change, and how to back up the
+# data; the first page the finished build shows says where the published app is and what to try to see it works.
+set -eu
+[ -s README.md ] || { echo "missing README.md" >&2; exit 1; }
+grep -q "yarn start" README.md || { echo "README.md does not say how to run it on this computer (yarn start)" >&2; exit 1; }
+grep -q "wrangler deploy\|yarn deploy" README.md || { echo "README.md does not say how to publish a change (yarn deploy)" >&2; exit 1; }
+grep -q "d1 export" README.md || { echo "README.md does not say how to back up the data (wrangler d1 export)" >&2; exit 1; }
+start=.blueprint/start-here.md
+[ -s "$start" ] || { echo "missing $start" >&2; exit 1; }
+[ -s .blueprint/deploy-url ] || { echo "missing .blueprint/deploy-url" >&2; exit 1; }
+url=$(tr -d ' \n\r' < .blueprint/deploy-url)
+grep -qF "${url%/}" "$start" || { echo "$start does not name the published URL (${url%/})" >&2; exit 1; }
+grep -q '^- \[ \] ' "$start" || { echo "$start has no checklist of what to try (- [ ] …)" >&2; exit 1; }

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

@@ -0,0 +1,39 @@
+#!/bin/sh
+# The served page actually starts: a build can deploy, report its id and answer 200, and still be a
+# blank page because the app threw on load (a missing config does exactly that). Rendered in headless
+# Chrome, the page must show some text. Without a Chrome this cannot be judged, and says so.
+set -eu
+url="$1"
+chrome=""
+for candidate in "${CHROME:-}" "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" google-chrome chromium chromium-browser; do
+  [ -n "$candidate" ] || continue
+  if [ -x "$candidate" ] || command -v "$candidate" >/dev/null 2>&1; then chrome="$candidate"; break; fi
+done
+[ -n "$chrome" ] || { echo "no Chrome found (set CHROME=...); could not confirm that $url renders" >&2; exit 0; }
+# Headless Chrome can print the DOM and then not exit, so it is waited on for the DOM, not for exit.
+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=$!
+# 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();
+  if (!text) { console.error(process.argv[1] + " renders a blank page: the app failed to start. Open it in a browser and read the console error."); process.exit(1); }
+})' "$url" <"$work/dom.html"

package/blueprints/cloudflare/checks/prerequisites.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+# Node is new enough for wrangler, and yarn answers. wrangler itself is a dev dependency of the project.
+set -eu
+node -e 'process.exit(Number(process.versions.node.split(".")[0]) >= 22 ? 0 : 1)' ||
+  { echo "Node.js 22 or later is needed (wrangler requires it); this is $(node -v)" >&2; exit 1; }
+yarn --version >/dev/null 2>&1 || { echo "yarn is missing (corepack enable)" >&2; exit 1; }

package/blueprints/cloudflare/checks/scaffold.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+# The layout the later checks rely on exists, and the skeleton builds and its tests pass inside the Workers runtime.
+set -eu
+for f in package.json wrangler.jsonc src/worker/index.ts index.html vitest.config.ts; do
+  [ -f "$f" ] || { echo "missing $f" >&2; exit 1; }
+done
+for d in migrations test; do
+  [ -d "$d" ] || { echo "missing $d/" >&2; exit 1; }
+done
+grep -q '"start"' package.json || { echo "package.json has no start script" >&2; exit 1; }
+grep -q '"d1_databases"' wrangler.jsonc || { echo "wrangler.jsonc binds no D1 database" >&2; exit 1; }
+grep -q '"assets"' wrangler.jsonc || { echo "wrangler.jsonc serves no assets" >&2; exit 1; }
+yarn build
+yarn test

package/blueprints/cloudflare/checks/security-report.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+# The security review's report exists, walks every OWASP Top 10:2025 category, and leaves no HIGH or
+# MEDIUM finding open or merely accepted. A finding is one line: `- <HIGH|MEDIUM|LOW> <fixed|open|accepted>: …`.
+set -eu
+report=.blueprint/security-review.md
+[ -s "$report" ] || { echo "missing $report" >&2; exit 1; }
+for category in A01 A02 A03 A04 A05 A06 A07 A08 A09 A10; do
+  grep -q "^#.*$category" "$report" || { echo "$report has no section for $category (OWASP Top 10:2025)" >&2; exit 1; }
+done
+open=$(grep -nE '^- (HIGH|MEDIUM) (open|accepted)' "$report" || true)
+[ -z "$open" ] || { printf 'HIGH / MEDIUM findings must be fixed, but are open or accepted in %s:\n%s\n' "$report" "$open" >&2; exit 1; }

package/blueprints/cloudflare/checks/security.sh

@@ -0,0 +1,52 @@
+#!/bin/sh
+# The security review is proven by the running Worker, not by the review's word: the app started with wrangler dev is
+# sent the requests an attack would send (a cross-site state change, a malformed body) and must refuse them, its pages
+# and its API carry the headers a browser needs, its secrets stay out of any repository, its dependencies have no known
+# high-severity hole, and the review's own report and tests are in place.
+set -eu
+sh "$(dirname "$0")/security-report.sh"
+[ -f test/security.test.ts ] || { echo "missing test/security.test.ts" >&2; exit 1; }
+# Local secrets live in .dev.vars (or .env); the folder becomes a repository whenever its person adds git.
+for secrets in .dev.vars .env; do
+  if [ -f "$secrets" ] && ! grep -qxE "/?$(printf '%s' "$secrets" | sed 's/\./\\./g')(\\*)?" .gitignore 2>/dev/null; then
+    echo "$secrets exists and .gitignore does not ignore it; add a line $secrets to .gitignore" >&2
+    exit 1
+  fi
+done
+yarn test >/dev/null || { echo "yarn test fails" >&2; yarn test >&2 || true; exit 1; }
+# Read from the summary, not the exit code: an audit that could not reach the registry must not pass.
+yarn audit --groups dependencies --json 2>/dev/null | node -e 'let s="";process.stdin.on("data",(c)=>s+=c).on("end",()=>{
+  const summary = s.split("\n").filter(Boolean).map((line) => JSON.parse(line)).find((entry) => entry.type === "auditSummary");
+  if (!summary) { console.error("yarn audit did not report a summary (is the registry reachable?)"); process.exit(1); }
+  const { high = 0, critical = 0 } = summary.data.vulnerabilities;
+  if (high + critical > 0) { console.error(`yarn audit: ${high} high and ${critical} critical vulnerabilities in dependencies; run yarn audit --groups dependencies`); process.exit(1); }
+})'
+
+. "$(dirname "$0")/serve.sh"
+base="http://127.0.0.1:$port"
+status() { curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$@"; }
+fail() { echo "$1" >&2; exit 1; }
+
+# A state change sent from another site's page.
+code=$(status -X POST -H "Origin: https://attacker.example" -H "Content-Type: application/json" -d '{}' "$base/api/blueprint-security-probe")
+[ "$code" = 403 ] || fail "POST /api/… from Origin https://attacker.example answered $code; a state change from another origin must be refused with 403 before routing and sign-in"
+
+# The page is served as a static asset, which does not go through the Worker: its headers come from public/_headers.
+for target in / /api/health; do
+  headers=$(curl -s -D - -o /dev/null --max-time 5 "$base$target" | tr -d '\r')
+  has() { printf '%s' "$headers" | grep -qiE "$1"; }
+  has '^x-content-type-options: *nosniff' || fail "$target is served without X-Content-Type-Options: nosniff"
+  has '^content-security-policy:' || fail "$target is served without a Content-Security-Policy"
+  has "^content-security-policy:.*frame-ancestors|^x-frame-options: *(deny|sameorigin)" || fail "$target can be framed by another site (no frame-ancestors in the CSP, no X-Frame-Options)"
+  ! has '^x-powered-by:' || fail "$target carries X-Powered-By"
+done
+
+# A malformed body is refused at the entry, before routing — a Worker reads JSON per route, so a check against a path no
+# route handles proves nothing unless the body is read once, up front — and is answered without the Worker's insides.
+response=$(curl -s --max-time 5 -w '\n%{http_code}' -X POST -H "Origin: $base" -H "Content-Type: application/json" --data '{"broken' "$base/api/blueprint-security-probe")
+code=$(printf '%s' "$response" | tail -n 1)
+body=$(printf '%s' "$response" | sed '$d')
+[ "$code" = 400 ] || fail "a malformed JSON body to /api/… answered $code; it must be refused with 400 where the Worker reads JSON bodies, before routing"
+if printf '%s' "$body" | grep -qE 'node_modules|at [^ ]+ \(|SyntaxError: |src/worker/'; then
+  fail "a malformed JSON body is answered with a stack trace or the parser's error: $(printf '%s' "$body" | head -c 300)"
+fi