docs+test: 对齐等待 banner 的注释/设计口径并钉住 skip-wait 的 404 契约

v0.19.0 发版前 review 发现两处「文档与实现互相矛盾」（均不改运行时行为）：

- use-host-feeds.ts 的 effect 注释仍写「terminal tab 类型禁用时 pushes are
  ignored」，而 mirrorAgentWaits 恰恰改成了不忽略（只跳过 tab 增删 reconcile）。
  注释改为如实描述；
- 设计文档 §1 写「轮询每圈优先检查 skipped」，实现是 aborted → exited →
  skipped。维持实现现状（pty 已死是客观事实，两种顺序下用户可见结果——banner
  消失 / skipWait 归零 / 等待结束——完全相同，只有 kind 文案不同），设计原文
  同步为「退出优先」，并在实施偏差记录写清未采纳「用户意图优先」的理由与日后
  改动点；
- src/index.ts 的 agent-pty.skip-wait 注释把「无活动等待 → 0」泛化成了
  「幂等」，收窄为「无活动等待返回 {skipped:0}；未知 uuid 走 expect → 404，
  客户端 .catch 容忍并等下一次推送收敛」。

另把 skipWait 未知 uuid 的既有断言从「只校验 /not found/ 文案」升级为
「SidebarError + status 404 + code not-found」——HTTP 层 writeError 直接把
status 映射成响应码，此前这条契约没有测试守护（把 404 改成 410 时新断言即
失败，已验证）。

验证：pnpm test 126 files / 1312 passed / 0 failed，tsc --noEmit 与 eslint
均 exit 0；改动面仅 5 个文件，src/client/service.ts、builtins/ 与
external-plugin-guide.md 继续零改动。

src/agent-pty.ts

@@ -569,6 +569,13 @@ export class AgentPtyRegistry {
     handle.waits.push(record)
     this.notify()
     try {
+      // Exit outranks a skip in the same tick: `skipWait` flips `record.skipped`
+      // and the next poll observes it, but a pty that died first is the
+      // objective fact (a skip is moot once the process is gone). The user
+      // sees the same three things either way — the banner clears, `skipWait`
+      // reports 0 for the resolved wait, and the tool result says the wait
+      // ended — only the reported `kind` differs (see the design doc's
+      // implementation-deviation record).
       while (true) {
         if (signal?.aborted) signal.throwIfAborted()
         if (handle.exited) {

src/client/sidebar/use-host-feeds.ts

@@ -94,8 +94,9 @@ export function useHostFeeds(feeds: {
    * the same shell without losing the agent's work — capped like the
    * terminal view's own reconnect loop, so a refused endpoint never spins
    * forever (the next session switch restarts the loop).
-   * While the terminal tab type is disabled in settings, pushes are
-   * ignored (no auto-added tabs); re-enabling makes the next push converge.
+   * While the terminal tab type is disabled in settings, pushes add / remove
+   * no tabs — but the authoritative wait map is STILL mirrored (see the
+   * branch below); re-enabling makes the next push converge on both.
    */
   useEffect(() => {
     if (sessionId === undefined) return

src/index.ts

@@ -547,8 +547,10 @@ function buildApi(
       return { ok: true }
     },
     // The sidebar wait banner's skip button: abort every active
-    // terminal_wait_for on one agent terminal. Idempotent — 0 when nothing
-    // is waiting (a stale banner racing a wait that already resolved).
+    // terminal_wait_for on one agent terminal. An unknown uuid (a terminal
+    // already closed / reaped) goes through `expect` and surfaces as 404
+    // not-found; the client tolerates that and lets the next push converge.
+    // Nothing waiting on a live terminal is not an error: 0 skipped.
     // Degraded mode (node-pty unavailable) has no registry and no waits: an
     // honest ok.
     'agent-pty.skip-wait': (payload) => {