@cocorograph/hub-agent 0.6.85 → 0.6.87

package/README.md

@@ -86,7 +86,7 @@ hub-agent/
 │   ├── config.mjs             # ~/.hub/agent.json 管理
 │   ├── enroll.mjs             # enrollment フロー
 │   ├── ws-client.mjs          # outbound WSS + reconnect with jitter
-│   ├── pty-bridge.mjs         # node-pty 多重化
+│   ├── pty-bridge.mjs         # @lydell/node-pty 多重化 (fd leak 回避フォーク)
 │   ├── tmux.mjs               # tmux exec/list/create/kill
 │   ├── state.mjs              # session status / context_pct 検知
 │   ├── skills.mjs             # ~/.claude/skills 集計
@@ -98,7 +98,7 @@ hub-agent/
 │   ├── co.cocorograph.hub-agent.plist
 │   └── hub-agent.service
 ├── scripts/
-│   └── fix-node-pty-perms.mjs # node-pty spawn-helper +x 修復 (postinstall)
+│   └── fix-node-pty-perms.mjs # @lydell/node-pty spawn-helper +x 修復 (postinstall)
 └── test/
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.6.85",
+  "version": "0.6.87",
   "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの tmux/pty を中継する。",
   "type": "module",
   "license": "UNLICENSED",
@@ -34,8 +34,8 @@
   ],
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.158",
+    "@lydell/node-pty": "1.2.0-beta.12",
     "commander": "^12.1.0",
-    "node-pty": "^1.0.0",
     "pino": "^9.0.0",
     "ws": "^8.18.0"
   },

package/scripts/fix-node-pty-perms.mjs

@@ -1,12 +1,17 @@
 #!/usr/bin/env node
-// pnpm 経由インストールだと node-pty/prebuilds/*/spawn-helper の実行権限が
-// 剥がれて posix_spawnp が失敗する事象への workaround.
-// postinstall で確実に +x を付与する。
+// pnpm 経由インストールだと prebuilds/*/spawn-helper の実行権限が剥がれて
+// posix_spawnp が失敗する事象への workaround. postinstall で確実に +x を付与する。
+//
+// PTY backend は @lydell/node-pty (Microsoft 公式の fd-leak 修正フォーク) に移行済み。
+// prebuild は @lydell/node-pty-<platform>/prebuilds/<platform>/spawn-helper に入る
+// (npm install では +x 付きで展開されるが、pnpm 等で剥がれるケースに備えて修復する)。
+// 旧 node-pty の配置も後方互換で走査する。
 import { readdirSync, statSync, chmodSync } from "node:fs";
 import { join } from "node:path";
 
 const PNPM_GLOB = "node_modules/.pnpm";
-const FALLBACK = "node_modules/node-pty/prebuilds";
+// prebuilds ディレクトリの候補 (node-pty 旧配置 + @lydell platform パッケージ)。
+const FALLBACK_DIRS = ["node_modules/node-pty/prebuilds"];
 
 function fixDir(dir) {
   let count = 0;
@@ -26,12 +31,39 @@ function fixDir(dir) {
   return count;
 }
 
+// @lydell の platform パッケージ (@lydell/node-pty-darwin-arm64 等) を走査する。
+function findLydellPrebuilds() {
+  const out = [];
+  const scopeDir = "node_modules/@lydell";
+  try {
+    for (const entry of readdirSync(scopeDir)) {
+      if (!entry.startsWith("node-pty-")) continue; // platform バイナリパッケージのみ
+      const p = join(scopeDir, entry, "prebuilds");
+      try {
+        statSync(p);
+        out.push(p);
+      } catch { /* prebuilds 無し */ }
+    }
+  } catch { /* @lydell scope 無し */ }
+  return out;
+}
+
 function findPnpmPrebuilds() {
   const out = [];
   try {
     for (const entry of readdirSync(PNPM_GLOB)) {
-      if (!entry.startsWith("node-pty@")) continue;
-      const p = join(PNPM_GLOB, entry, "node_modules/node-pty/prebuilds");
+      let inner = null;
+      if (entry.startsWith("node-pty@")) {
+        // 旧 node-pty: node_modules/.pnpm/node-pty@x/node_modules/node-pty/prebuilds
+        inner = "node_modules/node-pty/prebuilds";
+      } else if (entry.startsWith("@lydell+node-pty-")) {
+        // @lydell platform: @lydell+node-pty-darwin-arm64@x → pkg 名 = node-pty-darwin-arm64
+        const pkg = entry.slice("@lydell+".length).split("@")[0];
+        inner = join("node_modules/@lydell", pkg, "prebuilds");
+      } else {
+        continue;
+      }
+      const p = join(PNPM_GLOB, entry, inner);
       try {
         statSync(p);
         out.push(p);
@@ -42,13 +74,15 @@ function findPnpmPrebuilds() {
 }
 
 let fixed = 0;
-for (const dir of findPnpmPrebuilds()) {
+for (const dir of [...findPnpmPrebuilds(), ...findLydellPrebuilds()]) {
   fixed += fixDir(dir);
 }
-try {
-  statSync(FALLBACK);
-  fixed += fixDir(FALLBACK);
-} catch { /* not hoisted */ }
+for (const fallback of FALLBACK_DIRS) {
+  try {
+    statSync(fallback);
+    fixed += fixDir(fallback);
+  } catch { /* not hoisted */ }
+}
 
 if (fixed === 0) {
   // 何も修正しなかった = 既に OK or node-pty 未インストール。サイレント終了。

package/scripts/install.sh

@@ -512,10 +512,12 @@ _install_node_lts_linux() {
   color_ok "node $(node --version 2>/dev/null || echo '?') を導入"
 }
 
-# ネイティブアドオン (node-pty 等) のビルドに必要な make / g++ / python3 を導入する。
-# node-pty は prebuild が無いと node-gyp rebuild にフォールバックするが、クリーンな
-# Ubuntu には build-essential が無く `gyp ERR! not found: make` で失敗する
-# (WSL クリーン Ubuntu で発覚)。macOS は Xcode CLT 前提なので何もしない。
+# ネイティブアドオンのビルドに必要な make / g++ / python3 を導入する。
+# PTY backend は @lydell/node-pty に移行済みで全 OS の prebuild を同梱するため通常は
+# native ビルド不要だが、prebuild が当たらない環境では node-gyp rebuild に
+# フォールバックする。クリーンな Ubuntu には build-essential が無く
+# `gyp ERR! not found: make` で失敗する (WSL クリーン Ubuntu で発覚) ため保険で導入する。
+# macOS は Xcode CLT 前提なので何もしない。
 ensure_build_tools() {
   [[ "$(uname)" == "Darwin" ]] && return 0
   if present make && present g++; then

package/src/main.mjs

@@ -383,7 +383,12 @@ export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
 
   await runHookBroadcast(plugins, "onAgentStart", ctx)
 
-  const resolvedPty = ptyModule || (await import("node-pty"))
+  // node-pty (Microsoft 公式) は macOS arm64 で PTY master fd を spawn ごとに leak し
+  // (kill/destroy でも解放されず)、kern.tty.ptmx_max=511 到達で「新規ターミナルが
+  // 開けない」障害を起こした (2026-06-16)。node 20/22/24 全てで再現。API 互換の保守
+  // フォーク @lydell/node-pty は同ケースで leak ゼロ + 全 OS prebuilt 同梱なので
+  // 差し替えた。WHY 詳細: Hub log/2026-06-16/0041_cockpit。
+  const resolvedPty = ptyModule || (await import("@lydell/node-pty"))
   const ptyBridge = new PtyBridge({ ptyModule: resolvedPty, logger, plugins })
 
   // Claude SDK は optional dep 扱い (未インストール時は stream モードのみ無効化)。
@@ -1132,6 +1137,20 @@ export function handleTrackedPtyData(msg, ctx) {
   }
 }
 
+/**
+ * 無印 (input_id 無し / fire-and-forget) pty.data の処理。raw 打鍵 (term.onData) が
+ * これを通る。stream 不在 (reap 済み等) なら pty.error を返して browser を再 attach →
+ * 自己修復させる (T-6)。従来は write の戻り値を見ずに捨てていたため、reap 済み stream
+ * への打鍵が無言ドロップされていた。tracked 経路 (handleTrackedPtyData) と対称。
+ * テストから直接呼べるよう dispatch から切り出して export する。
+ */
+export function handleUntrackedPtyData(msg, ctx) {
+  const { stream_id } = msg
+  if (!ctx.ptyBridge.write({ stream_id, data: msg.data })) {
+    ctx.client.send({ type: "pty.error", stream_id, error: "stream_missing" })
+  }
+}
+
 async function dispatch(msg, ctx) {
   const t = msg?.type || ""
   try {
@@ -1198,7 +1217,7 @@ async function dispatch(msg, ctx) {
           handleTrackedPtyData(msg, ctx)
           return
         }
-        ctx.ptyBridge.write({ stream_id: msg.stream_id, data: msg.data })
+        handleUntrackedPtyData(msg, ctx)
         return
       case "pty.resize":
         ctx.ptyBridge.resize({

package/src/pty-bridge.mjs

@@ -40,6 +40,12 @@ const DEFAULT_COALESCE_MS = 12
 const DEFAULT_GC_INTERVAL_MS = 60_000
 const DEFAULT_GC_STALE_MS = 10 * 60_000
 
+// 安全弁: 同時 attach できる pty の上限本数。万一リークが残っても macOS の
+// `kern.tty.ptmx_max` (=511) に到達する前に最古の stream を強制 reap して枯渇を
+// 防ぐ (504/511 まで溜めて新規ターミナルが開けなくなった 2026-06-16 障害の再発防止)。
+// 0 以下で無効化 (テスト用)。
+const DEFAULT_MAX_STREAMS = 256
+
 function resolveBin(name) {
   try {
     return execFileSync("/usr/bin/which", [name], { encoding: "utf-8" }).trim()
@@ -80,9 +86,11 @@ export class PtyBridge extends EventEmitter {
      * posix_spawnp が `EAGAIN` で失敗する (= "posix_spawnp failed" の真因)。
      *
      * 対処: 各 stream に `lastSeenAt` を持たせ、`attach` / `write` / `resize`
-     * のたびに touch する。`gcIntervalMs` 周期で `gcStaleMs` を超えた stream を
-     * 自動 detach する (= orphan GC)。**アクティブな stream は browser からの
-     * pty.data / pty.resize で常に touch されるため絶対に kill されない**。
+     * および **pty 出力 (onData)** のたびに touch する。`gcIntervalMs` 周期で
+     * `gcStaleMs` を超えた stream を自動 detach する (= orphan GC)。**アクティブな
+     * stream は browser からの pty.data / pty.resize、または claude の出力で常に
+     * touch されるため絶対に kill されない** (生成中で出力は流れるが入力が間遠い
+     * 閲覧中の TUI チャットが reap される A-4 を出力 touch で塞ぐ)。
      * リロード時の短時間切断 (秒〜十数秒) も `gcStaleMs` (デフォルト 10 分)
      * 未満なので無傷。何時間も放置された孤児だけ掃除される。
      *
@@ -90,6 +98,11 @@ export class PtyBridge extends EventEmitter {
      */
     gcIntervalMs,
     gcStaleMs,
+    /**
+     * 同時 attach 上限 (安全弁)。超過すると新規 attach 前に最古の stream を強制
+     * reap する。リーク回帰があっても PTY 枯渇に至らせないためのハードリミット。
+     */
+    maxStreams,
   } = {}) {
     super()
     if (!ptyModule || typeof ptyModule.spawn !== "function") {
@@ -106,10 +119,21 @@ export class PtyBridge extends EventEmitter {
         env: process.env,
       }))
     this.coalesceMs = coalesceMs ?? DEFAULT_COALESCE_MS
+    this.maxStreams = maxStreams ?? DEFAULT_MAX_STREAMS
     /** @type {Map<string, import('node-pty').IPty>} */
     this.streams = new Map()
     /** @type {Map<string, {buf: string, timer: ReturnType<typeof setTimeout>|null}>} */
     this.coalesceState = new Map()
+    /**
+     * stream_id → onData/onExit の IDisposable[]。
+     * reap 時に dispose() しないと listener が IPty を参照し続け、master fd が
+     * close されず leak する (= ユーザー指摘「リスナ経由の参照残り」)。
+     * @type {Map<string, Array<{dispose: () => void}>>}
+     */
+    this.disposables = new Map()
+    // 可観測性: 起動からの累計 spawn / reap 数。差分 (= held) が単調増加したら leak。
+    this._spawnedTotal = 0
+    this._reapedTotal = 0
 
     // orphan GC 設定。デフォルトは 1 分周期で 10 分間 idle の stream を kill。
     this.gcIntervalMs = gcIntervalMs ?? DEFAULT_GC_INTERVAL_MS
@@ -119,7 +143,10 @@ export class PtyBridge extends EventEmitter {
     /** @type {ReturnType<typeof setInterval>|null} */
     this._gcTimer = null
     if (this.gcStaleMs > 0 && this.gcIntervalMs > 0) {
-      this._gcTimer = setInterval(() => this._gcStaleStreams(), this.gcIntervalMs)
+      this._gcTimer = setInterval(() => {
+        this._gcStaleStreams()
+        this._logStats()
+      }, this.gcIntervalMs)
       // unref で Node の event loop を止めない (test 環境で hang しないため)。
       if (typeof this._gcTimer.unref === "function") this._gcTimer.unref()
     }
@@ -143,28 +170,127 @@ export class PtyBridge extends EventEmitter {
   }
 
   /**
-   * `gcStaleMs` を超えて idle な stream を一括 detach する。
+   * `gcStaleMs` を超えて idle な stream を一括 reap する。
    *
    * `_gcTimer` から `gcIntervalMs` 周期で呼ばれる。手動でも呼べる (テスト用)。
-   * @returns {string[]} kill した stream_id 一覧 (debug / test 用)
+   *
+   * ⚠️ 走査対象は `this.streams` (= 実際に fd を保持している正本)。旧実装は
+   * `lastSeenAt` を走査していたが、`detach` が kill 前に `lastSeenAt` を消す一方で
+   * `streams` からの削除を `onExit` 頼みにしていたため、`onExit` が取りこぼされると
+   * 「streams に残る・lastSeenAt は無い」孤児が GC から不可視になり永久 leak した
+   * (2026-06-16 障害の主因)。streams を正本に走査することでこの不可視孤児を根絶する。
+   * @returns {string[]} reap した stream_id 一覧 (debug / test 用)
    */
   _gcStaleStreams() {
     if (!(this.gcStaleMs > 0)) return []
     const cutoff = this._now() - this.gcStaleMs
     const killed = []
-    for (const [stream_id, ts] of this.lastSeenAt) {
-      if (ts < cutoff && this.streams.has(stream_id)) {
+    for (const stream_id of Array.from(this.streams.keys())) {
+      // lastSeenAt 欠落 (= 不可視孤児) は 0 扱い = 即 stale 判定で確実に回収する。
+      const ts = this.lastSeenAt.get(stream_id) ?? 0
+      if (ts < cutoff) {
         this.logger?.warn(
           { stream_id, stale_ms: this._now() - ts, gc_stale_ms: this.gcStaleMs },
           "pty GC: orphaned stream killed",
         )
-        this.detach({ stream_id })
+        this._reap(stream_id, { emitExit: true, code: null })
         killed.push(stream_id)
       }
     }
     return killed
   }
 
+  /**
+   * 1 つの stream の後始末を一元化する (= 全リーク経路の単一出口)。
+   *
+   * 正常終了 (onExit) / browser detach / GC / 上限超過 / shutdown の全経路がここを
+   * 通る。冪等: 既に reap 済みなら何もしない (false を返す)。
+   *
+   * 順序が重要:
+   *  1. `streams` から **最初に** 削除する。`pty.kill()` が onExit を同期発火させる
+   *     実装 (テスト stub / 一部の node-pty 経路) で onExit ハンドラが再入しても、
+   *     その時点で stream が消えているので二重 emit / 二重カウントを防げる。
+   *  2. 残バッファを flush (取りこぼし防止)。
+   *  3. onData/onExit listener を dispose (参照残りによる fd 保持を断つ)。
+   *  4. 補助 Map をクリアし、最後に `pty.kill()` で master fd を解放する。
+   *
+   * @param {string} stream_id
+   * @param {{emitExit?: boolean, code?: number|null}} [opts]
+   * @returns {boolean} 実際に reap したら true
+   */
+  _reap(stream_id, { emitExit = false, code = null } = {}) {
+    const existed = this.streams.has(stream_id)
+    const pty = this.streams.get(stream_id)
+    // (1) streams から最初に外す → 以降の同期 onExit 再入は no-op。
+    this.streams.delete(stream_id)
+    // (2) 残バッファを取りこぼさない。
+    this._flushCoalesce(stream_id)
+    // (3) listener を dispose (node-pty の onData/onExit は IDisposable を返す)。
+    const disps = this.disposables.get(stream_id)
+    if (disps) {
+      for (const d of disps) {
+        try {
+          d?.dispose?.()
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+    this.disposables.delete(stream_id)
+    this.coalesceState.delete(stream_id)
+    this.lastSeenAt.delete(stream_id)
+    // (4) master fd を解放。
+    //   ⚠️ `pty.kill()` は子プロセスに SIGHUP を送るだけで、master fd を握る
+    //   内部 socket を破棄しない。macOS では子終了後に socket の 'close' が
+    //   発火せず fd が残り続ける → これが 2026-06-16 の PTY 枯渇 (504/511) の真因。
+    //   node-pty UnixTerminal の `destroy()` は `_socket.destroy()` で fd を即時
+    //   close してから SIGHUP を送るので、こちらを使う (公開 typings に無い内部 API
+    //   のため feature-detect。Windows 等で未定義なら kill にフォールバック)。
+    if (pty) {
+      try {
+        if (typeof pty.destroy === "function") pty.destroy()
+        else pty.kill()
+      } catch {
+        /* already dead / socket already closed */
+      }
+    }
+    if (existed) {
+      this._reapedTotal += 1
+      if (emitExit) this.emit("exit", { stream_id, code })
+    }
+    return existed
+  }
+
+  /**
+   * 現在保持している pty 本数と累計 spawn/reap をログ出力する (可観測性)。
+   * `leak_delta` は理論上常に 0 (held === spawned - reaped)。非 0 が続いたら異常。
+   */
+  _logStats() {
+    const held = this.streams.size
+    this.logger?.info(
+      {
+        held,
+        spawned_total: this._spawnedTotal,
+        reaped_total: this._reapedTotal,
+        leak_delta: this._spawnedTotal - this._reapedTotal - held,
+        max_streams: this.maxStreams,
+      },
+      "pty stats",
+    )
+  }
+
+  /**
+   * 現在の保持本数・累計カウンタを返す (テスト / debug 用)。
+   * @returns {{held: number, spawnedTotal: number, reapedTotal: number}}
+   */
+  stats() {
+    return {
+      held: this.streams.size,
+      spawnedTotal: this._spawnedTotal,
+      reapedTotal: this._reapedTotal,
+    }
+  }
+
   /**
    * stream の coalesce buffer を即時 flush して emit する。
    * detach / exit / shutdown のタイミングで残バッファの取りこぼしを防ぐ。
@@ -195,6 +321,26 @@ export class PtyBridge extends EventEmitter {
     if (this.streams.has(stream_id)) {
       throw new Error(`stream_id "${stream_id}" は既に attach 済みです`)
     }
+    // 安全弁: 上限到達時は最古 (lastSeenAt 最小) の stream を強制 reap してから
+    // spawn する。リークが残っても PTY 枯渇に至らせないハードリミット。
+    if (this.maxStreams > 0 && this.streams.size >= this.maxStreams) {
+      let oldestId = null
+      let oldestTs = Infinity
+      for (const sid of this.streams.keys()) {
+        const ts = this.lastSeenAt.get(sid) ?? 0
+        if (ts < oldestTs) {
+          oldestTs = ts
+          oldestId = sid
+        }
+      }
+      if (oldestId) {
+        this.logger?.warn(
+          { stream_id, evicted: oldestId, held: this.streams.size, max_streams: this.maxStreams },
+          "pty cap exceeded: reaping oldest stream",
+        )
+        this._reap(oldestId, { emitExit: true, code: null })
+      }
+    }
     const ctx = {
       logger: this.logger,
       sessionName,
@@ -224,40 +370,58 @@ export class PtyBridge extends EventEmitter {
     }
 
     this.streams.set(stream_id, pty)
+    this._spawnedTotal += 1
     this._touch(stream_id)
     this.logger?.info(
       { stream_id, sessionName, command: spec.command, plugin: hookResult?.plugin || null },
       "pty attached",
     )
 
+    // onData/onExit は IDisposable を返す。reap 時に dispose() するため保持する。
+    const disposables = []
     if (this.coalesceMs > 0) {
       const state = { buf: "", timer: null }
       this.coalesceState.set(stream_id, state)
-      pty.onData((data) => {
-        state.buf += data
-        if (!state.timer) {
-          state.timer = setTimeout(() => {
-            state.timer = null
-            const out = state.buf
-            if (!out) return
-            state.buf = ""
-            this.emit("output", { stream_id, data: out })
-          }, this.coalesceMs)
-        }
-      })
+      disposables.push(
+        pty.onData((data) => {
+          // 出力でも lastSeenAt を touch する (A-4 修正)。orphan GC は lastSeenAt が
+          // gcStaleMs 古い stream を reap するが、従来は write/resize/attach でしか
+          // touch していなかったため「生成中で出力は流れているが入力が間遠い閲覧中の
+          // TUI チャット」が 10 分で reap され、以後の送信が stream_missing で落ちていた
+          // (本番 agent.log で reaped_total 多数 + 同 input_id の再送 dedup を観測)。
+          // 出力が流れている = まだ生きて使われている stream なので touch して延命する。
+          // 真にブラウザが去った stream は claude がターン完了後に redraw を止めて出力が
+          // 止まり、gcStaleMs 経過で reap される。万一の runaway 出力 orphan は maxStreams
+          // 上限の最古 reap が backstop になる。
+          this._touch(stream_id)
+          state.buf += data
+          if (!state.timer) {
+            state.timer = setTimeout(() => {
+              state.timer = null
+              const out = state.buf
+              if (!out) return
+              state.buf = ""
+              this.emit("output", { stream_id, data: out })
+            }, this.coalesceMs)
+          }
+        }),
+      )
     } else {
-      pty.onData((data) => {
-        this.emit("output", { stream_id, data })
-      })
+      disposables.push(
+        pty.onData((data) => {
+          // 出力でも touch (A-4 修正)。理由は上の coalesce 経路のコメント参照。
+          this._touch(stream_id)
+          this.emit("output", { stream_id, data })
+        }),
+      )
     }
-    pty.onExit(({ exitCode }) => {
-      // 残バッファを取りこぼさないよう flush してから exit を emit する。
-      this._flushCoalesce(stream_id)
-      this.coalesceState.delete(stream_id)
-      this.streams.delete(stream_id)
-      this.lastSeenAt.delete(stream_id)
-      this.emit("exit", { stream_id, code: exitCode })
-    })
+    // 正常終了経路。全後始末を _reap に一元化 (flush → dispose → fd 解放 → exit emit)。
+    disposables.push(
+      pty.onExit(({ exitCode }) => {
+        this._reap(stream_id, { emitExit: true, code: exitCode })
+      }),
+    )
+    this.disposables.set(stream_id, disposables)
 
     return {
       plugin: hookResult?.plugin || null,
@@ -299,16 +463,20 @@ export class PtyBridge extends EventEmitter {
   detach({ stream_id }) {
     const pty = this.streams.get(stream_id)
     if (!pty) return false
-    // kill 前に残バッファを emit しておく (onExit にも flush はあるが、
-    // detach は browser 側都合なので最新を確実に届けたい)。
+    // kill 前に残バッファを emit しておく (detach は browser 側都合なので最新を
+    // 確実に届けたい)。
     this._flushCoalesce(stream_id)
-    // GC tracking もここでクリア。pty.onExit でも消すが、onExit が来る前に
-    // 同じ stream_id が再 attach されると古い lastSeenAt が残るリスクを避ける。
-    this.lastSeenAt.delete(stream_id)
     try {
       pty.kill()
     } catch {
-      /* ignore — onExit で Map から消える */
+      /* ignore */
+    }
+    // kill が onExit を同期発火する実装 (stub 等) では上の kill 内で _reap 済み。
+    // 実 node-pty は onExit が非同期なので、onExit を待たず即 reap して master fd を
+    // 解放する (= onExit 取りこぼし時の永久 leak を防ぐ核心)。_reap は冪等なので、
+    // 後から非同期 onExit が来ても no-op になる。
+    if (this.streams.has(stream_id)) {
+      this._reap(stream_id, { emitExit: true, code: null })
     }
     return true
   }
@@ -320,7 +488,7 @@ export class PtyBridge extends EventEmitter {
       this._gcTimer = null
     }
     for (const stream_id of Array.from(this.streams.keys())) {
-      this.detach({ stream_id })
+      this._reap(stream_id, { emitExit: true, code: null })
     }
   }
 

package/src/ws-client.mjs

@@ -58,6 +58,31 @@ const PTY_BUFFER_MAX_FRAMES = 500
 // 30 秒以上経過した pty.data は flush 時に破棄する。
 const PTY_BUFFER_MAX_AGE_MS = 30_000
 
+// agent→browser の制御/イベント系メッセージのうち、WS not OPEN 中に捨てると
+// Cockpit の挙動が壊れるものを reconnect 越しに保持する (機構③: 本番 agent.log で
+// `claude.jsonl.event ... "ws send skipped (not open)"` のドロップを観測)。
+//   - pty.input.ack: 喪失すると browser の pendingAcks が永久滞留し「送信待ち(未配信)」が
+//     消えない (S1/S3)。再接続 flush で遅れて届けば即解消する。
+//   - claude.jsonl.event / claude.event / session.event: 喪失すると新規セッションの
+//     楽観バブルが本物へ昇格できず「生成は始まったがバブルが出ない」(S5)。
+//   - pty.exit / pty.ready / pty.error: stream ライフサイクルの節目。落とすと browser の
+//     再 attach/復帰判断が狂う。
+// pty.data とは別バッファにするのは、高頻度な pty.data の洪水で低頻度な ack/event が
+// リング evict されるのを防ぐため (pty.data は冪等で最新フレームだけ届けば良いが、
+// ack/event は 1 件ずつ意味を持つ)。
+const BUFFERED_CTRL_TYPES = new Set([
+  "pty.input.ack",
+  "pty.exit",
+  "pty.ready",
+  "pty.error",
+  "claude.jsonl.event",
+  "claude.event",
+  "session.event",
+])
+// 制御/イベントバッファの上限。低頻度なので frames は小さめ、age は pty と揃える。
+const CTRL_BUFFER_MAX_FRAMES = 200
+const CTRL_BUFFER_MAX_AGE_MS = 30_000
+
 export class WsClient extends EventEmitter {
   /**
    * @param {{ hub_url: string, agent_id: string, agent_token: string }} config
@@ -94,6 +119,9 @@ export class WsClient extends EventEmitter {
     // pty.data の outbound buffer (WS not OPEN 中に積み、open 後 flush)。
     // entry: { obj, ts }
     this.ptyOutboundBuffer = []
+    // 制御/イベント系 (ack / jsonl.event 等) の outbound buffer。pty.data とは別管理で、
+    // 高頻度 pty.data の洪水に evict されないようにする (機構③)。entry: { obj, ts }
+    this.ctrlOutboundBuffer = []
     // 直前の close 原因が CF/origin の 5xx か。次回 backoff の下限を引き上げる。
     this.lastCloseWas5xx = false
     // 接続が STABLE_CONNECTION_MS 維持できたら backoff/5xx フラグをリセットする
@@ -203,23 +231,30 @@ export class WsClient extends EventEmitter {
       request_id: randomUUID(),
     })
     this._flushPtyBuffer()
+    this._flushCtrlBuffer()
     this._startHeartbeat()
     this._startBundleWatcher()
     this.emit("open")
   }
 
-  /** メッセージを送る。未接続時は pty.data だけ buffer に積み、reconnect 後に flush。
+  /** メッセージを送る。未接続時は pty.data と制御/イベント系 (ack / jsonl.event 等) を
+   * buffer に積み、reconnect 後に flush する。
    *
-   * heartbeat / hello / agent.streams.sync.* など制御系は古くなると意味が無いので
-   * buffer しない (warn のみ)。
+   * heartbeat / hello / agent.streams.sync.* など「古くなると意味が無い」制御系は
+   * buffer しない (warn のみ)。ack / event 系は 1 件ずつ意味を持つので別バッファに保持する。
    */
   send(obj) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
-      if (obj?.type === "pty.data") {
+      const type = obj?.type
+      if (type === "pty.data") {
         this._bufferPtyData(obj)
         return false
       }
-      this.logger?.warn({ type: obj?.type }, "ws send skipped (not open)")
+      if (BUFFERED_CTRL_TYPES.has(type)) {
+        this._bufferCtrl(obj)
+        return false
+      }
+      this.logger?.warn({ type }, "ws send skipped (not open)")
       return false
     }
     return this._sendJson(obj)
@@ -269,6 +304,48 @@ export class WsClient extends EventEmitter {
     )
   }
 
+  /** 制御/イベント系 (ack / jsonl.event 等) を outbound buffer に積む。リング (drop oldest)。 */
+  _bufferCtrl(obj) {
+    this.ctrlOutboundBuffer.push({ obj, ts: Date.now() })
+    if (this.ctrlOutboundBuffer.length > CTRL_BUFFER_MAX_FRAMES) {
+      const dropped = this.ctrlOutboundBuffer.length - CTRL_BUFFER_MAX_FRAMES
+      this.ctrlOutboundBuffer.splice(0, dropped)
+      this.logger?.warn(
+        { dropped, kept: this.ctrlOutboundBuffer.length },
+        "ctrl outbound buffer overflow (oldest dropped)"
+      )
+    }
+  }
+
+  /** open 直後に制御/イベントバッファを flush。古すぎる entry は破棄する。
+   * 構造は _flushPtyBuffer と同じ (退避 → 期限切れ skip → 送信失敗で残りを順序保持で戻す)。
+   */
+  _flushCtrlBuffer() {
+    if (this.ctrlOutboundBuffer.length === 0) return
+    const now = Date.now()
+    const buf = this.ctrlOutboundBuffer
+    this.ctrlOutboundBuffer = []
+    let sent = 0
+    let expired = 0
+    for (let i = 0; i < buf.length; i++) {
+      const entry = buf[i]
+      if (now - entry.ts > CTRL_BUFFER_MAX_AGE_MS) {
+        expired += 1
+        continue
+      }
+      const ok = this._sendJson(entry.obj)
+      if (!ok) {
+        this.ctrlOutboundBuffer = buf.slice(i).concat(this.ctrlOutboundBuffer)
+        break
+      }
+      sent += 1
+    }
+    this.logger?.info(
+      { sent, expired, total: buf.length, requeued: this.ctrlOutboundBuffer.length },
+      "ctrl outbound buffer flushed"
+    )
+  }
+
   /** Reconnect を止めて切断する。 */
   stop() {
     this.stopped = true