feat(ui): a way to stop the server from the browser

[ystknsh]

背景

MulmoTerminal をユーザー操作で止める経路は、現状「起動したターミナルで Ctrl+C」だけです。起動時のバナー（bin/mulmoterminal.js の printReadyBanner が出す Press Ctrl+C to stop.）と getting-started ガイド（日英）には書いてありますが、それが読めるのは起動した瞬間のそのターミナルだけです。

npx mulmoterminal@latest はブラウザを自動で開くので、起動後のユーザーの視界はブラウザ側にあります。ターミナルを見失う（タブが多い、ウィンドウを閉じた等）と、一般のユーザーが止めるための導線が無くなります。

• ブラウザ側に終了の導線がありません。タブを閉じてもサーバは動き続けます。ユーザー操作で止まる経路は SIGINT / SIGTERM だけで（server/index.ts の signal handler）、クライアント切断やアイドルでの自動終了はありません。タブを閉じるときに出るのは src/composables/useUnloadGuard.ts によるブラウザ固定文面の確認だけで、「サーバはまだ動いている」は伝わりません
• プロセス一覧で探しても node としか出ません。bin/mulmoterminal.js が #!/usr/bin/env node のスクリプトなので、npx でもグローバルインストールでも同じです。Activity Monitor で mulmoterminal を検索しても何も出ません。ps の COMMAND 列にはフルパスが出るので ps や lsof -i:34567 から辿ることはできますが、それを知っている人向けの経路です
• Settings の Stop ボタン（SurvivingSessionsSection）は再起動を生き延びたセッションを止めるもので、アプリの終了ではありません

報告例: npx mulmoterminal@latest で使っていたユーザー（ターミナルのタブを常時多数開いて作業するスタイル）が、新版への更新のために古いサーバを止めようとしたところ、起動したターミナルのタブが他の多数のタブに紛れて見つからず、プロセスを探して kill することになりました（Windows / PowerShell。不慣れな環境でコマンドを調べて対処。本人は npx がプロセスをバックグラウンドに回したと感じていた）。更新に限らず「今日はもう使わない」「ポートを空けたい」「挙動がおかしいので入れ直したい」でも同じ壁に当たります。

観察環境: コードは main faeae7de（4.10.1）。プロセス名の観察は macOS で npx mulmoterminal@latest（4.10.1）を起動した状態で ps と Activity Monitor を確認しました。ps の STAT は S+（起動したターミナルのフォアグラウンドプロセスグループ）で、バックグラウンドには行っていません。Windows 側は報告のみで、こちらでは未検証です。

考えられるアプローチ

独立した 2 つで、(1) が本体、(2) は保険です。

1. ブラウザから止められるようにする — UI に終了の導線を置き、サーバに終了を頼む POST ルートを 1 本足すのはどうでしょうか。やることは Ctrl+C と同じで、SIGINT handler と同じ経路（whisper sidecar を止めて process.exit(0)）を通します。セッションの扱いも Ctrl+C と同じ（tmux があれば中のセッションは生き残って次回起動時の Surviving sessions に出る、無ければエージェントのセッションも終わる）で、それ以上の後片付けを新たに設計する必要は無いと思います。ランチャは子の終了で自分も終わる（bin/mulmoterminal.js の runServer の close ハンドラ）ので、npx のラッパーまで含めて畳めます。
   • 押した瞬間に全セルの表示が消える操作なので、事前確認（yes/no）は必須だと思います。確認文には上のセッションの扱い（tmux の有無で変わる）を書くのが良さそうです
   • 悪意ある Web ページからの cross-site POST で手元のサーバが落ちる、は防ぐ必要がありますが、state-changing なルートは server/routes/same-origin-guard.ts の中央ゲート（server/routes/app-routes.ts で全ルートの前に app.use）が既定で覆うので、POST にする限り追加の防御は要らないはずです。ルートの置き場所は他のローカル操作ルートと同じ server/routes/ 配下で、mount は app-routes.ts から
   • UI の置き場所は Settings 内が自然だと思います（どの節に置くかは実装判断。バージョン表示の AppVersionLine はモーダルのヘッダにあるので、その近くか、セッション系の節か）。ヘッダのツールバーに置くと誤クリックの被害が大きい
2. プロセスに名前を付ける（保険） — サーバ起動時に process.title = "mulmoterminal" を設定するのはどうでしょうか。ps の COMM / COMMAND が mulmoterminal になることは手元で確認済みです。Activity Monitor の名前欄に反映されるかは未確認。(1) があっても見失う人は出るので、pkill mulmoterminal で止められる状態にしておく価値はあります

関連

• feat(update-check): re-check while the server runs — a server started with npx @latest is never told a newer version shipped #1821: npx mulmoterminal@latest のユーザーに新版を知らせる再チェック。両方揃うと「badge → 確認 → 新版で再起動」を一本道にできます（(1) の終了を「終了＋再起動」に広げるだけ）。本 issue はそれに依存しません
• feat: git 版と npm 版それぞれの更新をユーザに知らせる #654 / feat: 更新があるとき Web ヘッダにバッジを出す（コンソールだけでなく） #677: 更新チェックと badge の経緯

[isamu]

Working on this in mulmoterminal3.

• started — 2026-08-21 03:51 UTC
• PR feat: プロセスに mulmoterminal と名乗らせる (#1820) #1823 — 2026-08-21 04:05 UTC

_{posted by MulmoTerminal}

[isamu]

実装前に (2) の前提を測ったところ、2 点、この issue の想定と違いました。どちらも設計が変わる話なので先に記録します。

1. process.title は「どの OS でも付く」ものではない

libuv の uv_set_process_title は OS ごとに別実装です。

OS	実際に起きること	pkill mulmoterminal
macOS	argv を上書き。ps の COMMAND / COMM が変わる	効く（実測）
Linux	argv 上書き + prctl(PR_SET_NAME) で comm も変わる（先頭 15 文字まで。mulmoterminal は 13 文字で収まる）	効く
Windows	SetConsoleTitleW を呼ぶだけ。イメージ名は node.exe のまま	効かない

根拠: libuv v1.x の src/win/util.c:344 は SetConsoleTitleW のみ、src/unix/linux.c:2046 は prctl(PR_SET_NAME)。macOS は手元で実測しました。

つまり、報告が来た Windows は、プロセスに名前を付けても助からない OS です。 Task Manager も Get-Process も taskkill /IM も node.exe のままです。

ただし逆に、Windows で変わるのはコンソール窓のタイトルで、Windows Terminal は既定でタブ名がそれに追従します。「多数のタブに紛れて起動タブが見つからない」という報告そのものの症状には、むしろこちらが直接効く可能性があります（Windows 実機は未検証）。代償は、終了後もタイトルが戻らないことです。

macOS の Activity Monitor は変わらない見込みです（この issue で「未確認」とされていた点）。top -stats command で確認したところ node のままでした。Activity Monitor は top と同じ proc 情報を読むので、名前欄も node のままと思われます（GUI 自体は未検証）。

副作用の監査結果:

• リポジトリ内にプロセス名へ依存するコードはゼロ。 ps/pgrep/pkill の呼び出しは無く、唯一プロセスを覗く server/infra/process-tree.ts:15 は pid 基準
• 例外を投げません。 Node は uv_set_process_title の戻り値を捨てています（node_process_object.cc:47）
• コスト: macOS で初回 14.6ms、2 回目以降も約 7ms（libuv が毎回 ApplicationServices を dlopen するため）。一度しか代入しない理由です
• 唯一の実害は argv 上書きで ps から --port と実行パスが消えること。名前を mulmoterminal :34567 にして相殺しました

2. pid は既に記録されていた — だから「3 OS で効く経路」が安く作れる

サーバは既に ~/.mulmoterminal/instances/<pid>.json に {pid, port, startedAt} を書いています（#1061）。launcher が起動時に「すでに動いています」と言えるのはそのおかげです。

そして報告のシナリオ（新版に更新したい）では、ユーザーは既にこのプロンプトで「動いている」と告げられています。足りなかったのは止め方だけでした:

MulmoTerminal is already running (http://localhost:34567).
  ...
Start another one anyway? [y/N]

なので mulmoterminal stop を足し、このプロンプトと ready バナーにもコマンドを書きました。Windows で process.title が役に立たない以上、本当の保険は (2) ではなくこれです。

3. (1) について確認できたこと

• sameOriginGuard は app-routes.ts:143 で全ルートの前に mount されており、POST なら追加防御は不要 — 実測でも cross-origin POST は 403 で、サーバは落ちませんでした
• MulmoClaude が同じ機能を既に持っていました（#2616、POST /api/shutdown）。CLAUDE.md の規約どおりあちらを命名の権威として、パス・ボディ・猶予時間・UI の 2 段階確認まで合わせています。当初案の /api/app/quit は使っていません

PR

3 経路を独立した PR に分けました。相互に依存せず、それぞれ単独でマージできます。

• feat: プロセスに mulmoterminal と名乗らせる (#1820) #1823 — process.title（ps と Windows のタブ）
• feat: mulmoterminal stop — どのターミナルからでも止められるようにする (#1820) #1824 — mulmoterminal stop（3 OS すべてで効く）
• feat: ブラウザから MulmoTerminal を止められるようにする (#1820) #1825 — ブラウザの Quit ボタン（本 issue の本体）

設計は plans/feat-1820-stopping-the-server.md（#1823 で追加）にあります。

[ystknsh]

報告者から追加情報です。Windows / PowerShell では次のコマンドでサーバを止められたとのことです（ポート 34567 を持つプロセスを探して強制終了する）:

Get-NetTCPConnection -LocalPort 34567 -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }

本 issue の「ターミナルを見失った後に一般ユーザーが止める手段が無い」に対する、Windows での実際の回避策です。

#1824（mulmoterminal stop）との関係で 2 点:

• Windows で Stop-Process -Force（強制終了）を当てただけで止まり、その後新版を起動して使えたという実例です。feat: mulmoterminal stop — どのターミナルからでも止められるようにする (#1820) #1824 の「Windows では本物のシグナルが無いが、失われるものは無い」の判断と整合します（報告者の環境での 1 回の観察）
• 発見経路が pid レジストリではなく「ポート → OwningProcess」です。レジストリが古い／壊れているときの参考情報として

[isamu]

情報ありがとうございます。この 2 点目（発見経路がポート → OwningProcess）が、#1824 の未解決だったレビュー指摘を解いてくれました。 実装を差し替えたので報告します。

何が問題だったか

mulmoterminal stop はレジストリの pid にシグナルを送りますが、生きている pid は同一性ではありません。強制終了されたサーバはエントリを残し、OS はその pid を後で別のプロセスに渡し得ます。レビュー（CodeRabbit / Codex）でこれを指摘され、2 段階で直そうとして 2 回とも不十分でした:

1. ポートが応答するか見る → クラッシュ後に同じポートで再起動していれば元気に応答するので、pid の証明にならない
2. サーバに自分の pid を名乗らせる（GET /api/instance）→ 認証が無いので、loopback に居るものなら何でも偽装できる

報告者の回避策が答えでした

Get-NetTCPConnection -LocalPort 34567 | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }

OS に「このポートを握っているのは誰か」を訊いているのがポイントです。エントリは pid とポートの対を記録しているので、確認すべきはまさにその対であり、それを知っていてソケット越しに嘘をつかれ得ない唯一の相手がカーネルでした。

POSIX は lsof -nP -ti tcp:<port> -sTCP:LISTEN、Windows は上のコマンドと同じ Get-NetTCPConnection の OwningProcess を使うようにしました。

おまけがもう 1 つありました。 ソケットを握っていることと応答することは別なので、応答しなくなったサーバでもカーネルは答え続けます。実測（サーバを SIGSTOP で凍らせた状態）:

HTTP /api/instance                    -> 無応答
lsof -nP -ti tcp:34660 -sTCP:LISTEN   -> 46386   <- 正しく答える

--force が必要だった主な理由（ハングしたサーバ）が、これで消えました。

Windows の 1 点目について

Stop-Process -Force（ハンドラを走らせない強制終了）で止まり、その後新版を起動して使えた、という実例も有用でした。#1824 では「Windows には本物のシグナルが無いので process.kill は強制終了になるが、失われるものは無い（あの終了処理が後始末するのは macOS 専用の whisper サイドカーだけ）」と判断していて、それを実環境で裏付けてもらえた形です。こちらでは Windows を検証できないので助かりました。

現状

• feat: プロセスに mulmoterminal と名乗らせる (#1820) #1823（process.title）— マージ済み
• feat: ブラウザから MulmoTerminal を止められるようにする (#1820) #1825（ブラウザの Quit ボタン）— マージ済み
• feat: mulmoterminal stop — どのターミナルからでも止められるようにする (#1820) #1824（mulmoterminal stop）— 上記の差し替えを入れて CI 待ち

[isamu]

3 経路とも main に入りました。

PR	内容	効く OS
#1823	process.title を mulmoterminal :<port> に	ps/pkill: mac・Linux / タブ名: Windows
#1824	mulmoterminal stop（起動プロンプトと ready バナーにも案内）	3 OS すべて
#1825	Settings → Quit MulmoTerminal（POST /api/shutdown）	すべて

マージ後の main で 3 経路を通しで確認しました（3 つが同時に入った状態は誰も実行していないため）:

経路1  ps: 26369 / 26385  mulmoterminal :34690      <- launcher とサーバの両方
経路3  cross-origin POST -> 403、サーバは 200 のまま  <- same-origin gate
       same-origin POST  -> {"stopping":true} -> ポート解放
経路2  mulmoterminal stop -> Stopped ... -> 残プロセスなし

yarn typecheck / lint / build / test（10930 passed）も main で緑です。

レビューで設計が変わった点（記録）

stop の pid 確認は 4 段階で厳しくなりました。最後の 2 つは、この issue に寄せていただいた Windows の回避策が起点です:

1. レジストリの pid をそのまま信じる → 不可（クラッシュ後に pid が再利用され得る）
2. ポートが HTTP に応答するか → 不可（同じポートで再起動していれば別サーバでも応答する）
3. サーバに自分の pid を名乗らせる → 不可（認証が無く偽装できる）
4. カーネルにポートの所有者を訊く → 採用（lsof / Get-NetTCPConnection）。訊けなければ確認せず --force を促す（fail closed）

3 を撤回したことで GET /api/instance の存在理由が消えたため、エンドポイントごと取り下げています。結果として #1824 は新しい API 面をひとつも足していません。

残っているのは「確認とシグナルの間の 208ns」という TOCTOU の窓だけで、これは pkill でも報告者の PowerShell ワンライナーでも同じく存在し、Node からは（pidfd のバインドが無いため）塞げません。詳細は #1824 のコメントに残しました。

クローズは @isamu の判断でお願いします。