lawrencecchen · Aug 26, 2026 · Aug 26, 2026 · Aug 27, 2026 · Aug 27, 2026 · Aug 27, 2026
@@ -136,6 +136,9 @@ jobs:
       - name: Test TUI npm artifact transfer contract
         run: python3 tests/test_tui_npm_package_artifact.py
 
+      - name: Test TUI npm launcher behavior
+        run: python3 tests/test_tui_npm_launcher.py
+
       - name: Check package versions
         run: python3 cmux-tui/bindings/check-versions.py --published-only
 

diff --git a/cmux-tui/README.ja.md b/cmux-tui/README.ja.md
@@ -0,0 +1,26 @@
+# cmux-tui
+
+tmux 風のターミナル TUI です。詳細な英語ドキュメントは
+[README.md](README.md) を参照してください。
+
+## npm パッケージのインストールと更新
+
+`cmux` npm パッケージは依存関係を持たない小さなランチャーです。初回起動時に
+現在のプラットフォーム用の `cmux-tui-<platform>` パッケージを npm レジストリから
+ダウンロードし、sha512 整合性を確認してランチャー専用キャッシュに保存します。
-`cmux` npm パッケージは依存関係を持たない小さなランチャーです。初回起動時に
-現在のプラットフォーム用の `cmux-tui-<platform>` パッケージを npm レジストリから
-ダウンロードし、sha512 整合性を確認してランチャー専用キャッシュに保存します。
+`cmux` npm パッケージは依存関係を持たない小さなランチャーです。一致するインストール済み
+パッケージまたはキャッシュ済みバイナリがない場合、現在のプラットフォーム用の
+`cmux-tui-<platform>` パッケージを npm レジストリからダウンロードし、sha512 整合性を
+確認してランチャー専用キャッシュに保存します。
-`cmux` npm パッケージは依存関係を持たない小さなランチャーです。初回起動時に
-現在のプラットフォーム用の `cmux-tui-<platform>` パッケージを npm レジストリから
-ダウンロードし、sha512 整合性を確認してランチャー専用キャッシュに保存します。
+`cmux` npm パッケージは依存関係を持たない小さなランチャーです。一致するインストール済み
+パッケージまたはキャッシュ済みバイナリがない場合、現在のプラットフォーム用の
+`cmux-tui-<platform>` パッケージを npm レジストリからダウンロードし、sha512 整合性を
+確認してランチャー専用キャッシュに保存します。
+
+書き込み可能なランチャーキャッシュは起動前に認証済みパッケージメタデータを取得し、
+公開元のバイナリダイジェストと照合します。レジストリがダイジェストを提供しない場合は、
+書き込み可能なキャッシュヒットごとに tarball 全体を検証します。管理者が用意した完全な読み取り専用
+キャッシュは、バイナリとマニフェストを検証済みならオフラインで起動できます。
+
+```bash
+npx cmux update
+npx cmux update --check
+```
+
+`cmux update` はプラットフォーム用バイナリの通常更新に使います。npm ランチャー自体を
+更新する場合は `npx cmux@latest` を使います。`npx` は cmux の起動前に npm の `_npx`
+キャッシュへアクセスすることがあり、古いキャッシュでは `ENOTEMPTY` が発生する場合が
+あります。詳しい復旧手順は
+[パッケージのインストールと更新](docs/getting-started.ja.md) を参照してください。
diff --git a/cmux-tui/README.md b/cmux-tui/README.md
@@ -90,6 +90,8 @@ ssh -T dev@buildbox cmux relay --session agents
 
 The Unix-only `machine-agent` shares an existing local session through one outbound SSH registration with cmux.cloud. It prints a one-time pairing code and opens no listener. The final command is a low-level raw JSON-lines diagnostic. Use the machine rail or `cmux ssh` for the managed remote lifecycle.
 
+Upgrade a packaged install with `npx cmux update`; it downloads the latest verified binary without rewriting npm's caches. Writable launcher-cache hits fetch fresh authenticated package metadata and compare the publisher's binary digest before launch. A registry without that digest falls back to full tarball verification for each writable hit. A fully read-only provisioned cache can run offline after its binary and manifest have been verified. `npx` can still touch, or fail while touching, npm's `_npx` cache before cmux starts. Use `npx cmux update` for routine platform-binary upgrades and `npx cmux@latest` when updating the npm launcher. If the latter fails with `ENOTEMPTY: directory not empty, rename`, see [Packaged installs and updates](docs/getting-started.md#packaged-installs-and-updates). Japanese: [npm パッケージ](README.ja.md).
+
 Use `--term <value>` to set `TERM` for child PTYs. Without it, children get `xterm-256color`; `CMUX_TUI_TERM` can override the terminal runtime default, with `CMUX_MUX_TERM` retained as a legacy fallback.
 
 ## Browser ownership