@cocorograph/hub-agent 0.6.85 → 0.6.86

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.86",
   "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 モードのみ無効化)。

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()
@@ -90,6 +96,11 @@ export class PtyBridge extends EventEmitter {
      */
     gcIntervalMs,
     gcStaleMs,
+    /**
+     * 同時 attach 上限 (安全弁)。超過すると新規 attach 前に最古の stream を強制
+     * reap する。リーク回帰があっても PTY 枯渇に至らせないためのハードリミット。
+     */
+    maxStreams,
   } = {}) {
     super()
     if (!ptyModule || typeof ptyModule.spawn !== "function") {
@@ -106,10 +117,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 +141,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 +168,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 +319,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 +368,46 @@ 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) => {
+          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) => {
+          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 +449,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 +474,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 })
     }
   }