handmux 0.26.0 → 0.27.2

package/README.md

@@ -8,12 +8,12 @@
   <a href="https://www.npmjs.com/package/handmux"><img src="https://img.shields.io/npm/v/handmux?color=cb3837&logo=npm" alt="npm"></a>
   <a href="https://github.com/handmux/handmux/actions/workflows/test.yml"><img src="https://github.com/handmux/handmux/actions/workflows/test.yml/badge.svg" alt="CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="license: AGPL-3.0"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white" alt="node"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A522.16-339933?logo=node.js&logoColor=white" alt="node"></a>
 </p>
 
 > **One phone, a whole mobile vibe-coding cockpit.** Built on tmux — one command on your computer, scan a QR, and your live session, Claude Code, Codex, git, previews and docs are all in your hand, creativity ready wherever you are.
 
-handmux is more than a terminal on your phone. It puts the *same* live **tmux** session running on your computer into your phone's browser (real panes, not a read-only mirror), then builds a whole **mobile vibe-coding cockpit** around it: **Claude Code / Codex** push you the moment a pane needs a decision — approve with your thumb, or fire off a new instruction by voice; browse a full-screen colored **git** diff; **preview** a running site in one tap; hear a **doc** read aloud line by line; move files both ways. Nothing to install on the phone — open a link and you're in; "Add to Home Screen" and it runs full-screen as a **PWA**, basically a native app. Curl up on the couch or squeeze onto the train — the vibe coding never stops, your creativity stays in hand.
+handmux puts the *same live tmux workspace* from your computer in any phone or desktop browser. Keep coding with Claude Code, Codex, Pi, or any terminal tool; review changes, answer prompts, preview apps, and move files without starting a separate remote session. It is self-hosted, open-source, and needs no phone app or handmux account.
 
 <p align="center">
   <img src="assets/handmux-run.gif" alt="handmux: say what you need, Claude Code writes it, then tap the filename to preview the result" width="280">
@@ -59,113 +59,40 @@ handmux start --tunnel cloudflare   # instant public URL (cloudflared auto-insta
 
 ## Why handmux
 
-- **🧰 More than a terminal — a whole mobile vibe-coding cockpit in your pocket.** Full-screen colored git diffs, one-tap preview of a running site, docs read aloud line by line, files moved both ways — a whole dev kit in hand, no hopping between apps.
-- **🚀 One minute from zero to coding on your phone.** One `handmux start`, one scan, done — no sign-up, no App Store, no app to sideload; just a link. "Add to Home Screen" and it's a full-screen **PWA**, as smooth as a native app.
-- **🧶 Walk away, keep working.** Your phone drives the *one* live tmux pane on your desk (not a new shell, not a screenshot). Close the laptop and keep watching from your thumb — exact same state.
-- **🔔 When it needs you, your phone rings.** Claude Code / Codex push the moment they need a decision; add it to your home screen and they come through as system notifications. An inbox tags each pane working / needs-you / done / error — many projects at a glance — while the host keeps terminal-result reads consistent across refreshes and devices. Open a completed item to start at the final completed AI answer in the authoritative latest tail. Claude Hook outcomes queue locally while the Server is offline and replay in session order after it returns. Approve permissions and plans with a tap, so you stop babysitting the screen.
-- **🔒 Your code goes through no middleman.** Free and fully open-source; we run no server in the middle — your data travels straight between your computer and your phone, so it stays secure.
+- **🧶 One workspace, everywhere.** Your phone drives the real tmux panes already running on your computer—not a screenshot or a separate cloud session.
+- **🔔 Stop babysitting agents.** See which panes are working or waiting, get notified when you are needed, and approve from your phone.
+- **🧰 A complete coding cockpit.** Terminal, Agent conversations, Git, previews, docs, files, usage, and idea capture stay together.
+- **🔒 Self-hosted by design.** Your browser connects to your computer; handmux runs no account service or relay in between.
 
 ## Features
 
-- **Claude Code / Codex, deeply** — an inbox status ledger, thumb-approve permissions & plans, and stable host-wide subscription usage shared by every connected device; each visible provider can refresh its latest limits from the card action menu, while keeping the previous values visible if that provider cannot be reached. Codex also shows the current account and plan, separate account/model limits, remaining rate-limit resets, and each provided expiry. The same Usage screen can save multiple DeepSeek and Moonshot (Kimi) API accounts encrypted at rest within the Handmux computer's local trust boundary; full API Keys never return to browsers.
-- **Chat view** — drive Codex CLI through App Server with streaming Markdown bubbles, tool cards, native Goal lifecycle cards, and session status; the context-ring details show the absolute Git worktree root path and branch that contain the thread `cwd`. Setting or restarting a Goal creates a fresh active native Goal, immediately shows its user-side card on the right, and starts Codex's built-in continuation. An active or paused Goal stays beneath the live read-only turn task list, Codex terminal feedback stays with its originating turn on the left, and every entry opens the same Bottom Sheet. The current Goal uses one equal-width iOS-style action row; clearing it removes the resident Goal and closes the sheet, while its historical chat card remains. The current terminal Goal can be edited before restarting. Long replies hold at their beginning for reading, with an explicit jump back to the latest output. Existing panes can switch in place. Every sendable Agent uses the same persistent server queue: queued messages can be viewed, edited or deleted and are delivered automatically; Guide now appears only when that Agent supports steering. Failed sends stay visible and retry under the same request ID. If delivery remains unknown after reconciliation, the message returns to the conversation and you choose whether to send it again as new, with a clear duplicate-delivery warning. On desktop, <kbd>Shift</kbd>+<kbd>Enter</kbd> focuses the composer or inserts a newline when already focused, <kbd>Enter</kbd> sends, and <kbd>Esc</kbd> releases focus without stopping the Agent. Codex chat is stable; Claude Code and Pi chat are independently enabled experimental options.
-- **Real-time terminal + desktop keyboard** — stream the same tmux pane on phone and desktop with scrollback, weak-network fallback, direct physical-keyboard input, and native copy/paste.
-- **Command & chat modes** — switch between direct terminal input and natural-language agent chat, with direct Alt and Space keys on the mobile command keyboard and a customizable quick bar that stays in sync across devices.
-- **Client reload after updates** — once the server update has finished, use Settings → Reload app to load the new client without quitting and reopening the home-screen app.
-- **Script push** — notify your phone from any script or CI step with `handmux push`; target all devices, a named session, or a specific device.
-- **Workspace recovery** — handmux keeps the metadata needed to restore your latest tmux workspace after a computer or tmux-server restart, without replacing existing sessions.
-- **Git viewer** — changes / commit history / any branch / full-screen colored diff, multi-repo tabs, read-only, never touches your tree.
-- **Web Preview for URLs and static folders** — preview URLs by phone or computer proxy, or open an isolated static folder, with narrow/wide page widths and zoom; computer proxy can also request a mobile or desktop site version. It embeds pages rather than replacing a full browser.
-- **Docs** — tap recognized text-file paths in the terminal or Agent tool input/output to open them, regardless of extension; user-home paths appear as `~/…`, while ordinary slash-separated prose stays plain. Markdown rendered, font zoom, sentence-by-sentence read-aloud. Binary files stay download-only.
-- **Mobile select & copy** — long-press text in either the terminal or an Agent conversation, drag iOS-style handles to fine-tune, then copy the exact selection, its rendered line, or its semantic paragraph.
-- **Files both ways** — multi-select upload from the chat box (including ZIP archives), download, share in, copy any absolute path.
-- **Ideas — catch every one** — a thought the moment it strikes: a per-window idea/to-do list, jot one by voice and drop it straight into the prompt.
-- **Built for flaky networks** — backoff reconnect, connection-lost banner, offline page, polling that pauses in the background; a reflow-safe cursor.
-- **Zero-install PWA** — runs full-screen from your home screen, with English, 简体 / 繁體中文, 日本語, and 한국어.
+- **Live terminal** — use the same tmux pane from phone and desktop, with history, physical-keyboard input, and native copy/paste.
+- **Agent conversations** — work with Codex in a streaming chat view; optional Claude Code and Pi integrations bring the same workspace into their supported conversation flows.
+- **Inbox and approvals** — follow multiple panes, receive push notifications, and answer permission or plan prompts remotely.
+- **Git and previews** — review repositories and open running sites, intranet pages, or static folders from the browser.
+- **Docs and files** — open readable files, listen to documents, and upload, download, or share files in either direction.
+- **Ideas and voice** — keep notes per window and dictate text through supported iFlytek or Tencent recognition modes.
+- **Usage at a glance** — view supported Agent subscription limits and configured API-provider balances without exposing full keys to the browser.
+- **Resilient sessions** — reconnect across weak networks and restore saved tmux workspace structure after a restart.
+- **Script push** — send a notification to your phone from local scripts or CI with `handmux push`.
+- **Zero-install PWA** — add it to your home screen for a full-screen experience in English, Chinese, Japanese, or Korean.
 
 ## Agent integration
 
-Use `handmux <agent> [args...]` to start a supported Agent; every argument after the Agent name is passed through unchanged. Use the separate `handmux agent` namespace to enable or inspect Handmux integration. Codex support is built in, while Pi and Claude Code are explicitly enabled:
+Codex integration is built in. Pi and Claude Code integration are optional:
 
 ```bash
 handmux codex [args...]
 handmux pi [args...]
-
-handmux agent                 # list Agent integration status
 handmux agent enable pi
-handmux agent status pi
-handmux agent disable pi
-
 handmux agent enable claude
-handmux agent status claude
-handmux agent disable claude
-handmux agent status codex    # ready (built-in) when Codex is installed
 ```
 
-The legacy `handmux hooks install|uninstall` commands remain compatibility aliases for Claude Code. Pi integration uses a trusted Handmux-owned Extension wrapper for the same native Pi TUI process; enabling it writes only that wrapper under Pi's documented global extension directory and never scans projects or loads third-party extensions. Open a new Pi session, or run `/reload` in Pi, after enabling or disabling it. The wrapper is refreshed automatically across Handmux upgrades and gives each Connector build a content-fingerprinted import URL, so `/reload` cannot reuse the previous build from the module cache; a file not marked as Handmux-owned is never overwritten or deleted. Pi keeps working normally when the Handmux server is offline; terminal outcomes are queued locally and delivered after it returns. In Pi chat, the shared context ring reads Pi's live context-window usage, activity and working directory; reload an already-running Pi session after upgrading Handmux to expose newly added Connector capabilities.
-
-The capability-driven Agent chat downloads attachments only after a tap. Providers register an opaque, session-bound resource ID; the app never receives a local path, and potentially active content such as HTML or SVG is always downloaded rather than rendered inline.
-
-## Workspace recovery
-
-handmux continuously maintains two redundant copies of the latest workspace metadata. They are not browsing history: ordinary changes and deletions handmux can confirm simply update the current state. A selectable checkpoint is archived only when the computer or tmux environment changes. If the final tmux session disappears outside handmux, tmux cannot distinguish an intentional deletion from a crash, so handmux retains the last state and can offer recovery immediately, without waiting for a new tmux server or session. Every checkpoint from the latest 24 hours is kept; older history is then trimmed to the newest 10, while the latest valid checkpoint never expires just because of age.
-
-After such a restart, the phone shows **Restore last workspace** for one hour when a checkpoint has work left to restore; if tmux has no sessions it opens the confirmation directly. Choosing **Ignore this backup** suppresses that checkpoint only on that phone; an ordinary close does not. When recovery finishes, the phone reports the actual sessions, windows, and panes restored, but does not automatically open or bind them; choose **Bind restored sessions** if you want them on that phone. The CLI remains available after the phone prompt expires:
-
-```bash
-handmux restore --dry-run                         # preview the latest plan
-handmux restore                                  # restore; TTY picker, otherwise latest
-handmux restore --list                           # list retained checkpoints
-handmux restore --checkpoint <id> --session api  # select history / restore one session
-```
-
-Restore is additive and idempotent. It never stops, renames, replaces, or changes the topology of a current session; a name collision becomes `name-restored`, then `name-restored-2`. Windows, panes, working directories and layouts are rebuilt where safe. Only verified Claude Code/Codex sessions are resumed from their persisted session IDs; ordinary panes reopen as shells in their saved directories, without replaying commands or scrollback. Metadata lives under `~/.handmux/workspaces/`; it can include paths, tmux names/layout and agent session IDs, but not pane output.
-
-## Script push
-
-Send a push notification to your phone from any script, CI step, or build hook:
-
-```bash
-handmux push "Build done" "Took 3m12s"
-```
-
-Runs **on your computer** against the already-running `handmux` server (loopback + local server token — no config, no remote endpoint). Web Push must be enabled first (`handmux setup`).
-
-**Syntax**
-
-```
-handmux push <title> <body> [options]
-```
-
-| Flag | Description |
-|---|---|
-| `--session <name>` | Target all devices subscribed to this tmux session (repeatable; comma-separated values OK) |
-| `--device <key>` | Target a specific device by its key (repeatable; comma-separated values OK) |
-| `--tag <T>` | Notification tag (collapses duplicates) |
-| `--url <U>` | HTTP(S) URL or same-origin relative path to open when the notification is tapped |
-
-**Scopes — pick at most one:**
-
-- _(default)_ — all subscribed devices
-- `--session` — only devices subscribed to the named session(s)
-- `--device` — only the specified device(s) by key
-
-`--session` and `--device` are mutually exclusive.
-
-The **device key** is shown in the phone app under Settings → Script push. It is an addressing identifier, not a secret — the security boundary is the local server token.
-
-> **Reliability:** Web Push is best-effort. For delivery-critical alerts use a dedicated messaging app (WeChat, Slack, etc.).
-
-## Networking: one decision
-
-No tunnel by default — the phone connects **straight to your own computer**, nothing exposed and no middleman. To reach it from outside, just ask: **does your machine already have a public address?**
-
-- **Yes** (cloud box / public IP / forwarded port) — no tunnel needed, connect directly; fastest and most private.
-- **No** — open a tunnel. Each runs on **your own free third-party account** — handmux just wires it up and operates no relay of its own: `cloudflare` (zero-config, up in seconds, but its public edge can be slow or unreliable in some regions) · `cloudflare-named` (your own domain, steadier) · `natapp` / `cpolar` (domestic providers that stay reachable inside mainland China) · `ssh` self-hosted (through your own server).
+See the **[Agent integration guide](https://handmux.com/docs#cmd-agent)** for status, disable, compatibility, and reload behavior.
 
-> Tunnel config, Web Preview, autostart, and voice/push credentials → see the **[docs](https://handmux.com/docs)**.
+## Connectivity
 
-Once autostart is installed, `handmux start` / `stop` / `restart` coordinate with that same launchd/systemd service (including after an upgrade). A lifecycle lock prevents concurrent launches; `status` shows the running version and warns with PIDs if stale/duplicate supervisors exist, while `stop` reaps every copy.
+The default is a direct connection to your own computer. For access away from home or work, use a public address or a tunnel on your own Cloudflare, natapp, cpolar, or SSH setup. See the **[connectivity guide](https://handmux.com/docs#tunnels)**.
 
 ## Requirements
 

package/README.zh-CN.md

@@ -8,12 +8,12 @@
   <a href="https://www.npmjs.com/package/handmux"><img src="https://img.shields.io/npm/v/handmux?color=cb3837&logo=npm" alt="npm"></a>
   <a href="https://github.com/handmux/handmux/actions/workflows/test.yml"><img src="https://github.com/handmux/handmux/actions/workflows/test.yml/badge.svg" alt="CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="license: AGPL-3.0"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white" alt="node"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A522.16-339933?logo=node.js&logoColor=white" alt="node"></a>
 </p>
 
 > **一部手机,一整套移动 Vibe Coding 驾驶舱。** 基于 tmux——电脑上一行命令、手机扫码,你正跑着的会话、Claude Code、Codex、git、预览、文档全到手里,创造力随时随地都在你手上。
 
-handmux 不只是把终端搬上手机。它把你电脑上**正跑着的 tmux 会话**原样搬进手机浏览器(同一个真实 pane,不是只读镜像),再围着它搭起一整套**移动 Vibe Coding 驾驶舱**:**Claude Code / Codex** 要你拍板时推到手机、拇指一点就批,动动嘴就发新指令;**git** 全屏看彩色 diff;一键**预览**正跑着的网站;**文档**逐句朗读;文件随手双向传。手机端**零安装**——点开链接就进去,"添加到主屏"即成全屏 **PWA**,和原生 App 基本无异。窝在沙发、挤在地铁,Vibe Coding 不停,创造力随时在你手里。
+handmux 把电脑上的**同一个实时 tmux 工作区**带到手机或桌面浏览器。你可以继续使用 Claude Code、Codex、Pi 或任何终端工具，查看改动、处理确认、预览应用和传输文件，而不用另开一套远程会话。它完全开源、自托管，手机无需安装 App，也无需注册 handmux 账号。
 
 <p align="center">
   <img src="assets/handmux-run.gif" alt="handmux:说出需求,Claude Code 写好,点文件名即可预览结果" width="280">
@@ -59,113 +59,40 @@ handmux start --tunnel cloudflare   # 即时公网地址(自动装 cloudflared)
 
 ## 为什么是 handmux
 
-- **🧰 不只是终端——一整套装进口袋的移动 Vibe Coding 驾驶舱。** git 全屏看彩色 diff、一键预览正跑着的网站、文档逐句朗读、文件随手双向传——一整套开发能力,此刻全套在手,不用在几个 App 间来回切。
-- **🚀 一分钟从零到手机上敲代码。** 一条 `handmux start`、扫个码,完事——不注册、不上应用商店、不装 App,一个链接就进去。"添加到主屏"后即为全屏 **PWA**,和原生 App 一样顺手。
-- **🧶 人走,活不停。** 手机连的是你工位上**那一个**正跑着的 tmux pane(不是新 shell、不是截图)。合上电脑,拇指接着盯,状态一点不差。
-- **🔔 需要你时,手机会响。** Claude Code / Codex 一到要你拍板就推送;添加到主屏后直接走系统通知。收件箱标「进行中 / 需要你 / 已完成 / 出错」,多项目并行状态一览无余;终态结果的已读状态由电脑端统一记录,刷新或换设备也不会重复提醒。打开“已完成”会刷新权威最新尾部，并直接从最后一条已完成 AI 回复开头开始阅读。Server 离线时 Claude Hook 结果先在本机排队,恢复后按会话顺序补交。拇指一点批授权批计划,别再守着屏幕等它。
-- **🔒 你的代码,不经过任何中转。** 免费、完全开源;我们没有中转服务器,数据只在你的电脑和手机之间直接走,确保安全。
+- **🧶 同一个工作区，到处继续。** 手机操控的是电脑上正在运行的真实 tmux pane，不是截图，也不是另一套云端会话。
+- **🔔 不必守着 Agent。** 随时查看哪些 pane 正在工作或等你处理，需要时收到通知并在手机上确认。
+- **🧰 完整的移动开发驾驶舱。** 终端、Agent 对话、Git、预览、文档、文件、用量和想法收集集中在一起。
+- **🔒 天生自托管。** 浏览器连接你自己的电脑，中间没有 handmux 账号服务或中转服务器。
 
 ## 功能一览
 
-- **Claude Code / Codex 深度**——收件箱状态台账、拇指批授权批计划，以及所有设备共享的本机最新订阅用量；每个已开启显示的 Provider 都可从卡片操作菜单单独刷新最新额度，厂家暂时不可达时仍保留上一份数值。Codex 还会显示当前账号与套餐、主账号和特定模型的独立额度，以及剩余重置次数与官方提供的各次到期时间。同一个用量页还能在 Handmux 电脑的本机信任边界内静态加密保存多个 DeepSeek 和 Moonshot (Kimi) API 账户，完整 API Key 不会返回浏览器。
-- **对话视图**——通过 App Server 用流式 Markdown 气泡、工具卡、原生 Goal 生命周期卡片和实时状态操作 Codex CLI；上下文圆环详情直接显示 thread `cwd` 所属 Git worktree 的绝对根路径与分支。设置或重新开始会创建全新的 active 原生 Goal，立即在右侧显示用户侧卡片并启动 Codex 自带的自动续跑。进行中或暂停的 Goal 常驻在实时任务列表下方，Codex 终态反馈留在对应回合并靠左，所有入口统一打开同一个 Bottom Sheet；当前 Goal 使用 iOS 风格单行等分操作，清除后会移除常驻目标并关闭详情，已经发生的历史卡片仍保留；当前终态 Goal 可修改内容后重新开始。长回答会稳定在开头供阅读，用户可随时回到最新内容；现有 pane 可原位接入。所有可发送 Agent 共用同一套持久服务端队列：待发消息可查看、编辑、删除并自动发送，只有 Agent 支持 steer 时才显示“立刻引导”。发送失败的消息会保留，并沿用同一个请求 ID 重试；若对账后仍无法确认是否送达，消息会回到对话中，由你决定是否作为新消息再次发送，同时明确提示可能重复送达。电脑端可用 <kbd>Shift</kbd>+<kbd>Enter</kbd> 聚焦输入框，聚焦后该组合键换行，<kbd>Enter</kbd> 发送，<kbd>Esc</kbd> 只取消聚焦而不会停止 Agent。Codex 对话为稳定功能；Claude Code 与 Pi 对话均需独立开启，且仍为实验性功能。
-- **实时终端 + 电脑键盘**——在手机和电脑上实时操控同一个 tmux pane，支持历史滚动、弱网回退、物理键盘直输和原生复制粘贴。
-- **命令 / 聊天双模式**——在终端直输与自然语言对话间切换；手机命令键盘提供直接可用的 Alt 与空格键，并可用跨设备同步的快捷栏快速操作。
-- **更新后重新加载客户端**——服务端更新完成后，在设置里点「重新加载应用」即可载入新版客户端，无需退出主屏应用再重新打开。
-- **脚本推送**——用 `handmux push` 从脚本或 CI 步骤推消息到手机,可指定全部设备、某个会话或某台设备。
-- **工作区恢复**——handmux 静默保存必要元数据，在电脑或 tmux server 重启后恢复最新工作区，绝不替换现有会话。
-- **Git 查看器**——改动 / 提交历史 / 任意分支 / 全屏彩色 diff,多仓库分页,只读不动工作区。
-- **网页预览器**——用手机直连或电脑代理预览网址，也可隔离打开静态目录，支持窄屏 / 宽屏和缩放；电脑代理还可向网站请求手机版或电脑版。它只嵌入网页，不替代完整浏览器。
-- **文档**——终端里明确识别出的文本文件路径不分扩展名均可点开，普通斜杠文字保持纯文本；支持 Markdown 排版、字号缩放、逐句高亮朗读，二进制文件仍只下载。
-- **选中 · 拷贝**——终端和 Agent 对话都可长按文字、拖动 iOS 式首尾手柄精调，再拷贝指定内容、屏幕整行或语义整段。
-- **文件双向传**——聊天框多选上传（含 ZIP 压缩包）、下载、系统分享进来、复制绝对路径。
-- **想法 · 随想随记**——不错过任何点子:每窗口一份想法清单,灵感一冒就记(能语音速记),一点填进输入框。
-- **专治弱网**——退避重连、掉线横幅、离线兜底页、后台暂停轮询;光标不乱跳。
-- **零安装 PWA**——添加到主屏即可全屏运行，支持 English、简体 / 繁體中文、日本語和 한국어。
+- **实时终端**——手机和电脑操控同一个 tmux pane，支持历史记录、物理键盘输入和原生复制粘贴。
+- **Agent 对话**——以流式对话操作 Codex；可选的 Claude Code 与 Pi 接入也能在支持的对话流程里使用同一个工作区。
+- **收件箱与确认**——集中查看多个 pane、接收推送，并远程处理权限或计划确认。
+- **Git 与预览**——查看仓库，并从浏览器打开运行中的网站、内网页面或静态目录。
+- **文档与文件**——打开可读文件、听文档朗读，并双向上传、下载或分享文件。
+- **想法与语音**——按窗口保存想法，并通过支持的讯飞或腾讯识别模式输入文字。
+- **用量概览**——查看支持的 Agent 订阅额度和已配置 API 服务商余额，完整密钥不会返回浏览器。
+- **会话韧性**——弱网下自动恢复连接，电脑重启后可恢复已保存的 tmux 工作区结构。
+- **脚本推送**——通过 `handmux push` 从本地脚本或 CI 向手机发送通知。
+- **零安装 PWA**——添加到主屏即可全屏使用，支持中文、English、日本語和 한국어。
 
 ## Agent 接入
 
-用 `handmux <Agent> [args...]` 启动受支持的 Agent，Agent 名后的参数会原样透传；用独立的 `handmux agent` 命名空间启用或检查 Handmux 接入。Codex 接入已内置，Pi 和 Claude Code 需要显式启用：
+Codex 接入已内置；Pi 和 Claude Code 接入可按需开启：
 
 ```bash
 handmux codex [args...]
 handmux pi [args...]
-
-handmux agent                 # 列出 Agent 接入状态
 handmux agent enable pi
-handmux agent status pi
-handmux agent disable pi
-
 handmux agent enable claude
-handmux agent status claude
-handmux agent disable claude
-handmux agent status codex    # 已安装 Codex 时就绪（接入已内置）
 ```
 
-旧的 `handmux hooks install|uninstall` 暂作 Claude Code 兼容别名。Pi 接入使用受信任的 Handmux 自有 Extension wrapper，连接的仍是电脑上同一个原生 Pi TUI 进程；启用时只在 Pi 官方全局 Extension 目录写入这一个 wrapper，不扫描项目，也不加载第三方扩展。启用或禁用后，新开 Pi 会话，或在 Pi 中运行 `/reload`。Handmux 升级后会自动刷新已启用的自有 wrapper，并为每份 Connector 内容生成带指纹的 import URL，避免 `/reload` 复用模块缓存里的旧版本；没有 Handmux 所有权标记的文件绝不会被覆盖或删除。Handmux Server 离线时 Pi 仍可正常使用，终态结果会先在本机排队，Server 恢复后再补交。Pi 对话使用通用上下文圆环显示 Pi 的实时上下文用量、运行状态和工作目录；Handmux 升级后，已在运行的 Pi 会话需执行 `/reload` 才能获得新增的 Connector 能力。
-
-通用 Agent 对话中的附件只在用户点按后下载。Provider 只注册与会话绑定的 opaque resource ID，手机不会收到本机路径；HTML、SVG 等潜在主动内容始终作为附件下载，不在页面内直接渲染。
-
-## 工作区恢复
-
-handmux 会持续维护最新工作区元数据的两份容灾副本。它们不是操作历史:日常变动和 handmux 能确认的主动删除只会更新当前状态。只有电脑或 tmux 环境换代时才归档可选择的 checkpoint。若最后一个 tmux 会话在 handmux 外消失，tmux 无法区分主动删除与崩溃；为保留崩溃恢复能力，handmux 会保留最后状态，并立即提供恢复，无需等待新 tmux server 或 session 出现。最近 24 小时内的全部保留;更早历史再裁到最新 10 份,最新有效 checkpoint 不会只因过期而消失。
-
-重启后若 checkpoint 里还有内容待恢复,手机会在一小时内显示「恢复上次工作区」;若 tmux 当前没有任何会话,则直接打开确认弹窗。在手机上忽略后,该 checkpoint 只在这台手机上不再提示。恢复完成后会汇总实际恢复的会话、窗口和窗格,但不会自动打开或绑定;需要时可点「重新绑定会话」选择要显示在这台手机上的会话。手机提示过期后,CLI 仍一直可用:
-
-```bash
-handmux restore --dry-run                         # 预览最新恢复计划
-handmux restore                                  # 恢复;TTY 交互选择,非 TTY 用最新
-handmux restore --list                           # 列出保留的 checkpoint
-handmux restore --checkpoint <id> --session api  # 选历史 / 只恢复一个会话
-```
-
-恢复是只新增、可重复执行的:不会停止、改名、替换或改变当前会话的拓扑;同名时依次改为 `name-restored`、`name-restored-2`。在安全可表达的范围内重建窗口、窗格、工作目录和布局。只有经过验证的 Claude Code / Codex 会话会用已持久化的 session ID 续接;普通 pane 只在原目录打开 shell,不会重放命令或保存的终端输出。元数据位于 `~/.handmux/workspaces/`,可能包含路径、tmux 名称/布局和 agent session ID,但不包含 pane 输出。
-
-## 脚本推送
-
-在电脑上运行任意脚本、CI 步骤或构建钩子时,推送通知到手机:
-
-```bash
-handmux push "构建完成" "耗时 3m12s"
-```
-
-在**你的电脑上**直接对正在运行的 `handmux` 服务器执行(回环 + 本地服务器 token——无需配置,无远端端点)。需先通过 `handmux setup` 启用 Web Push。
-
-**语法**
-
-```
-handmux push <title> <body> [选项]
-```
-
-| 参数 | 说明 |
-|---|---|
-| `--session <name>` | 仅推送到订阅了该 tmux 会话的设备(可重复使用,支持逗号分隔) |
-| `--device <key>` | 仅推送到指定 key 的设备(可重复使用,支持逗号分隔) |
-| `--tag <T>` | 通知标签(合并同类通知) |
-| `--url <U>` | 点通知后打开的 HTTP(S) URL 或站内相对路径 |
-
-**推送范围——三选一:**
-
-- _(默认)_ — 全部已订阅设备
-- `--session` — 仅订阅了指定会话的设备
-- `--device` — 仅指定 key 的设备
-
-`--session` 与 `--device` 互斥。
-
-**设备 key** 在手机 App 的设置 → 脚本推送中查看。它是寻址标识符,不是密钥——安全边界是本地服务器 token。
-
-> **可靠性说明:** Web Push 属于尽力投递,不保证实时送达。有投递强要求的告警请使用专用 IM(微信、钉钉等)。
-
-## 联网:一句话决策
-
-默认不开隧道——手机**直连你自己的电脑**,什么都不暴露、也没有中间人。想从外面连,只问一句:**电脑有没有公网地址?**
-
-- **有**(云主机 / 公网 IP / 已端口转发)—— 不用隧道,直接连,最快也最私密。
-- **没有** —— 开一条隧道。每条都跑在**你自己的免费第三方账号**上,handmux 只负责接通、自身不设中转:`cloudflare`(零配置秒通,但公共边缘在国内常不稳)· `cloudflare-named`(你的域名,更稳)· `natapp` / `cpolar`(国内厂商,大陆境内可达)· `ssh` 自建(接你自己的服务器)。
+状态、关闭、兼容和 reload 行为见 **[Agent 接入文档](https://handmux.com/docs#cmd-agent)**。
 
-> 隧道配置、网页预览器、开机自启、语音 / 推送凭证等细节 → 见 **[文档](https://handmux.com/docs)**。
+## 连接方式
 
-安装开机自启后，`handmux start` / `stop` / `restart` 会始终与同一个 launchd/systemd 服务协同（升级后也一样）。生命周期锁会阻止并发启动；`status` 显示实际运行版本，并列出未登记/重复 supervisor 的 PID；`stop` 会回收全部副本。
+默认由浏览器直连你自己的电脑。离开家庭或办公网络时，可使用公网地址，或通过自己的 Cloudflare、natapp、cpolar、SSH 配置建立隧道。详见 **[连接文档](https://handmux.com/docs#tunnels)**。
 
 ## 环境要求
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handmux",
-  "version": "0.26.0",
+  "version": "0.27.2",
   "description": "A mobile vibe-coding cockpit — built on tmux: drive your live session, Claude Code / Codex — anything a terminal can run — from your phone.",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -75,6 +75,24 @@
     "vitest": "^2.0.0"
   },
   "whatsNew": [
+    {
+      "version": "0.27.2",
+      "date": "2026-09-08",
+      "zh": "修复多标签页偶发鉴权弹窗",
+      "en": "Fix intermittent authentication prompts across tabs"
+    },
+    {
+      "version": "0.27.1",
+      "date": "2026-09-08",
+      "zh": "腾讯语音 · 终端光标修复 · Codex 对话恢复",
+      "en": "Tencent voice · terminal cursor fixes · Codex chat recovery"
+    },
+    {
+      "version": "0.27.0",
+      "date": "2026-09-05",
+      "zh": "腾讯语音输入 · 终端输入更准确",
+      "en": "Tencent voice input · more accurate terminal typing"
+    },
     {
       "version": "0.26.0",
       "date": "2026-09-04",
@@ -104,24 +122,6 @@
       "date": "2026-08-11",
       "zh": "Codex 任务进度与 Goal 原生上线",
       "en": "Native Codex task progress and Goals"
-    },
-    {
-      "version": "0.23.0",
-      "date": "2026-08-09",
-      "zh": "Codex 托管对话正式上线",
-      "en": "Managed Codex chat is here"
-    },
-    {
-      "version": "0.22.1",
-      "date": "2026-08-04",
-      "zh": "网页宽度与网站版本分开控制",
-      "en": "Separate page width and site-version controls"
-    },
-    {
-      "version": "0.22.0",
-      "date": "2026-08-03",
-      "zh": "全屏设置 · 窗口与分屏管理更清晰",
-      "en": "Full-screen Settings · clearer window and pane management"
     }
   ]
 }