update docs

Author: finch-xu

CHANGELOG.md

@@ -11,6 +11,14 @@ Release history prior to `v0.5.0` is available via [Git tags](https://github.com
 
 ## [Unreleased]
 
+### Changed
+- **macOS app: Stop menu item is now always visible and always enabled.** Previously the Stop item was hidden whenever the app believed no agent was running — which also hid it during `.starting` and `.restarting` transitions, leaving users unable to interrupt a restart loop. Start is now disabled during every active state (`.starting`, `.running`, `.restarting`) instead of only `.running`.
+- **macOS app: menu bar glyph and About window logo** now use the bundled rttys-agent artwork (`MenuBarIcon`, `AppLogo` asset sets) instead of system symbols and the generic application icon.
+
+### Fixed
+- **macOS app: orphan agent daemon left behind after an abnormal app exit.** When the Swift app crashes or is force-killed, the embedded Go `rttys-agent` child is reparented to launchd and keeps running. On next launch the user had no way to clean it up short of killing it by hand. Clicking Stop now shells out to the bundled `rttys-agent stop` CLI, which reaps any orphan via `~/.rttys/agent.pid`. The CLI call is gated to run only when the app has no tracked child process, so normal Stop clicks pay zero extra cost.
+- **macOS app: menu UI freeze up to 2 seconds on Quit/Stop.** The orphan-cleanup subprocess was previously awaited with a synchronous `Process.waitUntilExit()` on the `@MainActor`, stalling menu animations and the app's response to `NSApp.terminate(nil)`. It now uses `terminationHandler` + `withCheckedContinuation` so the main actor stays responsive while the CLI runs.
+
 ### Documentation
 - README: list `RttysAgent.zip` as the recommended macOS agent, document the first-run macOS TCC prompts (`~/Documents`, `~/Desktop`, `~/Downloads`, iCloud Drive) and point to **Full Disk Access** as a one-shot alternative, and add `agent-mac/` to the project structure.
 

CHANGELOG.zh-CN.md

@@ -11,6 +11,14 @@ RemoteTTYs 的所有重要变更都会记录在本文件中。
 
 ## [Unreleased]
 
+### 变更
+- **macOS 应用：Stop 菜单项现在始终显示且始终可点。** 此前 Stop 仅在应用认为 agent 正在运行时才显示——也就是说在 `.starting` 和 `.restarting` 过渡态下 Stop 消失，用户无法中断无限重启循环。Start 现在在所有活跃态（`.starting`、`.running`、`.restarting`）下都置灰，而不再仅限 `.running`。
+- **macOS 应用：菜单栏图标与 About 窗口 logo** 改用项目自带的 rttys-agent 美术资源（`MenuBarIcon`、`AppLogo` 资源集），不再使用系统符号和通用应用图标。
+
+### 修复
+- **macOS 应用：异常退出后残留的孤儿 agent 守护进程。** 当 Swift 应用崩溃或被强制结束时，内嵌的 Go `rttys-agent` 子进程会被 launchd 收养并继续运行。下次打开应用时用户除了手动 kill 别无他法。现在点击 Stop 会调用内嵌的 `rttys-agent stop` CLI 通过 `~/.rttys/agent.pid` 回收孤儿进程。该调用仅在应用没有追踪任何子进程时触发，因此日常点击 Stop 零额外开销。
+- **macOS 应用：Quit/Stop 时菜单冻结最长 2 秒。** 此前孤儿清理子进程使用 `Process.waitUntilExit()` 在 `@MainActor` 上同步等待，阻塞菜单动画以及 `NSApp.terminate(nil)` 的响应。现已改用 `terminationHandler` + `withCheckedContinuation`，CLI 执行期间主 actor 保持响应。
+
 ### 文档
 - README：将 `RttysAgent.zip` 列为 macOS 推荐方案；补充首次使用时 macOS TCC 权限弹窗（`~/Documents`、`~/Desktop`、`~/Downloads`、iCloud Drive）的说明，并指出 **完全磁盘访问权限** 可作为一次性授权的替代方案；将 `agent-mac/` 加入项目结构说明。