@cocorograph/hub-agent 0.8.23 → 0.8.25

package/src/main.mjs

@@ -4,9 +4,8 @@
  * - 設定読み込み (~/.hub/agent.json) → WsClient 起動
  * - plugin discovery + onAgentStart broadcast
  * - WS メッセージのディスパッチ:
- *   - pty.attach / pty.data / pty.resize / pty.detach → PtyBridge
- *   - pty 出力 → WsClient で type=pty.data として送信
- *   - tmux.exec は Sprint E で tmux module に渡す
+ *   - claude.* / codex.* → ClaudeStreamBridge / CodexStreamBridge (チャット)
+ *   - tmux.* → tmux module (exec / セッション一覧・作成・削除)
  *
  * 仕様書: ナレッジ/インフラ/cockpit-hub-hosted-integration-spec (id=6080)
  */
@@ -48,10 +47,10 @@ import { loadPlugins, runHookBroadcast, runHookChain } from "./plugin-loader.mjs
 import { WsClient } from "./ws-client.mjs"
 import { DispatchScheduler } from "./dispatch-scheduler.mjs"
 import { AsyncTtlCache } from "./async-ttl-cache.mjs"
-import { PtyBridge } from "./pty-bridge.mjs"
 import { ClaudeStreamBridge } from "./claude-stream-bridge.mjs"
 import { CodexMcpControl } from "./codex-mcp-control.mjs"
 import { CodexStreamBridge, classifyCodexInputError } from "./codex-stream-bridge.mjs"
+import { enforceTotalLiveBound } from "./warm-bounds-total.mjs"
 import { UploadManager } from "./claude-upload.mjs"
 import { requestSelfUninstall } from "./service-install.mjs"
 import {
@@ -101,7 +100,6 @@ import {
   listWorktreeStubs,
   paneClaudeAliveOrUnknown,
   removeWorktree as removeWorktreeDir,
-  setSessionMouse,
   setTmuxGlobalEnv,
 } from "./tmux.mjs"
 import { SiblingInjectBridge } from "./sibling-inject.mjs"
@@ -278,7 +276,7 @@ function readBundleVersionSync() {
 /**
  * `@anthropic-ai/claude-agent-sdk` を lazy import する。テストでは sdk arg で差し替え。
  *
- * SDK 未インストール (旧 hub-agent インストール) 環境でも pty モードは動くべきなので、
+ * SDK 未インストール (旧 hub-agent インストール) 環境でも agent 自体は起動すべきなので、
  * import 失敗を warn に留めて null を返す。stream モードを使う attach が来たら
  * その時点で error を browser に返す設計。
  */
@@ -332,22 +330,16 @@ export function withDeadline(promise, timeoutMs, onTimeout) {
 }
 
 /**
- * B7: 直列 dispatchChain をバイパスして即時処理してよい高頻度・低レイテンシ経路かを判定する。
- * - pty 出力データ (pty.data) と resize (pty.resize): 高頻度・順序保証不要。
+ * B7: 直列 dispatchChain をバイパスして即時処理してよい低レイテンシ経路かを判定する。
  * - claude.interrupt / codex.interrupt (2026-07-02): 停止指示。前段に重い dispatch
- *   (tmux.exec 等) が滞留していると停止が遅延するため直列キューをバイパスする。
- *   中断は「現ターンを止める」冪等な制御で、入力系のような順序依存が無い (むしろ
- *   キュー内の後続入力より先に届くべき)。
- * 入力系 (claude.input)・他の制御系 (tmux.exec / permission / cancel→paste 等) は
+ *   (tmux.exec / tmux セッション操作等) が滞留していると停止が遅延するため直列キューを
+ *   バイパスする。中断は「現ターンを止める」冪等な制御で、入力系のような順序依存が無い
+ *   (むしろキュー内の後続入力より先に届くべき)。
+ * 入力系 (claude.input)・他の制御系 (permission / tmux.exec / tmux セッション操作等) は
  * WS 受信順 = pane 反映順を守るため false (= 直列キューに残す)。
  */
 export function isFastPathMessage(type) {
-  return (
-    type === "pty.data" ||
-    type === "pty.resize" ||
-    type === "claude.interrupt" ||
-    type === "codex.interrupt"
-  )
+  return type === "claude.interrupt" || type === "codex.interrupt"
 }
 
 /**
@@ -710,7 +702,7 @@ export async function handleBundleSyncRequest(msg, ctx, opts = {}) {
   }
 }
 
-export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
+export async function startDaemon({ version, claudeSdk } = {}) {
   const config = await readConfig()
   if (!config) {
     throw new Error(
@@ -764,14 +756,6 @@ export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
   // 2026-07-15: Claude 固定から **検出された Claude/Codex 双方** の kick へ拡張。
   await kickSetupHubAiForDetectedClis({ logger })
 
-  // 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 })
-
   // ホストで起動可能な CLI (claude / codex) を 1 回検出する。hello で広告する用途に
   // 加え、codex app-server ベースの chat ブリッジ (codexBridge) を構築するかどうかの
   // gate にも使う (claudeBridge は npm optional dep の有無で判定するのに対し、codex は
@@ -865,13 +849,6 @@ export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
     logger.warn({ err: err.message }, "ws client error (will retry via close handler)")
   })
 
-  ptyBridge.on("output", ({ stream_id, data }) => {
-    client.send({ type: "pty.data", stream_id, data })
-  })
-  ptyBridge.on("exit", ({ stream_id, code }) => {
-    client.send({ type: "pty.exit", stream_id, code })
-  })
-
   // stream-json モード (Sprint G): Claude Code を SDK 経由で起動し、stream イベントを
   // そのまま browser に転送する。SDK 未インストール時は claudeBridge=null で全 attach が
   // claude.error を返す経路に分岐 (dispatch 側で判定)。
@@ -1140,16 +1117,9 @@ export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
   //
   // `EventEmitter.emit` は async リスナーの完了を待たないため、`async (msg) =>
   // await dispatch(msg, ...)` の形だと複数 WS メッセージが連続して届いたとき
-  // それぞれの dispatch が並列実行される。`tmux.exec` の `await execTmux`
-  // (subprocess 待ち) 中に後続 `pty.data` の同期 `ptyBridge.write` が先行する
-  // と、ブラウザ→Hub では順序が保証されていても agent 内部で逆転する。
-  //
-  // 典型的な被害: cockpit ChatInput の `await onCancelTmuxMode()` → paste
-  // の流れで、ブラウザ側が cancel の応答を待ってから paste を送っても、
-  // 別経路の `tmux.exec` (state loop の polling 等) で agent が busy だと、
-  // cancel の execTmux が完了する前に paste が ptyBridge.write される。
-  // 結果として paste が tmux 内部状態 (copy mode 等) を抜ける前に届き、
-  // claude TUI に正しく入らない事象が散発する。
+  // それぞれの dispatch が並列実行される。tmux セッション操作のような subprocess
+  // 待ちの最中に後続の同期処理が先行すると、ブラウザ→Hub では順序が保証されて
+  // いても agent 内部で逆転する。
   //
   // 旧来の global Promise chain は、ある cwd の tmux/codex 処理が別 cwd の
   // claude.attach と reconnect ready/sync まで 60〜203 秒止める HoL blocking を
@@ -1158,7 +1128,6 @@ export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
   const dispatchCtx = {
     ...ctx,
     client,
-    ptyBridge,
     claudeBridge,
     codexBridge,
     codexMcpControl,
@@ -1167,7 +1136,7 @@ export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
   const dispatchScheduler = new DispatchScheduler({
     logger,
     run: (msg) => dispatch(msg, dispatchCtx),
-    // pty fast-path / read-only RPC は従来どおり即時実行。接続 lifecycle は
+    // fast-path (interrupt) / read-only RPC は従来どおり即時実行。接続 lifecycle は
     // scheduler 自身が常に priority 扱いする。
     shouldBypass: (type) => isFastPathMessage(type) || isReadOnlyRpc(type),
   })
@@ -1179,7 +1148,7 @@ export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
 
   // 0.6.2 fix: event loop を ref されたまま生かしておく watchdog。
   // hub-agent の他の background task (heartbeat / reconnect / state loop / fs.watch)
-  // は全て .unref() / persistent:false なので、長時間アイドル + WS 切断 + pty 全 GC
+  // は全て .unref() / persistent:false なので、長時間アイドル + WS 切断
   // が同時発生すると Node が「やることなし」と判断して exit(0) で silent 終了する
   // 既存バグがあった。watchdog を 1 つ ref のまま持つことで exit を防ぐ。
   // shutdown 時に clearInterval して正常終了を許可する。
@@ -1276,7 +1245,6 @@ export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
     sessionEventLoop?.stop?.()
     readinessLoop?.stop?.()
     siblingInjectBridge.stop()
-    ptyBridge.shutdown()
     claudeBridge?.shutdown?.()
     codexBridge?.shutdown?.()
     client.stop()
@@ -1306,7 +1274,7 @@ export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
     )
   })
 
-  return { client, plugins, ptyBridge, claudeBridge, codexBridge, codexMcpControl, uploadManager }
+  return { client, plugins, claudeBridge, codexBridge, codexMcpControl, uploadManager }
 }
 
 const SESSION_EVENTS_DIR =
@@ -1960,8 +1928,8 @@ function startReadinessLoop({ tracker, logger, intervalMs = 700, onReady }) {
  * 全 tmux session の状態を定期 capture し、変化したものだけ Hub に push する。
  *
  * - 前回値との比較で status / context_pct のどちらかが変化したら送る
- * - 新規 session は無条件 push、消えた session は無視 (browser 側で
- *   pty.exit 受信時に処理する)
+ * - 新規 session は無条件 push、消えた session は無視 (browser 側は
+ *   セッション一覧の更新で消滅を検知する)
  * - tmux 自体が動いてない場合 (listSessionStates → []) は何も push しない
  */
 // (i) 出力フロー検知の有効窓。ペイン出力領域の署名 (output_sig) が直近この時間内に変化して
@@ -2239,6 +2207,11 @@ export function startStateLoop({ client, plugins, logger, intervalMs, claudeBrid
   // 権威的 stall 判定 (arm 非依存・cap 非依存)。state loop が観測する signal だけで turn の開閉と
   // 無進捗を判定する。旧 lastProgressAtByName + armed ゲートの「フック依存 + cap 140s で消える」死角を解消。
   const stallTracker = new StallTracker({ stallWarnMs: STALL_WARN_MS })
+  // 総 live 上限 M のログ抑制状態。⚠️ **この state loop インスタンスが所有する**（module-global に
+  // 置くと、複数インスタンスや並行テストが互いのログを抑制してしまう）。「超過しているが全部
+  // 保護されていて刈れない」tick は 5 秒ごとに同じ行を出し続けるので、状態が変わったときと
+  // 一定間隔でだけ記録する（warm-bounds-total.mjs の _shouldLog）。
+  const warmBoundsLogState = { lastUnresolved: 0, lastLoggedAtMs: 0 }
   let stopped = false
 
   // RC-8: WS 再接続のたびに差分送信の基準 (lastByName) をクリアし、次 tick で全 session.state を
@@ -2263,8 +2236,10 @@ export function startStateLoop({ client, plugins, logger, intervalMs, claudeBrid
       } catch (err) {
         logger?.warn({ err: err?.message }, "gcDeadTerminals failed")
       }
-      // 子⑤ (T06544): claude 側 warm 境界（per-cwd=1 / N-cwd LRU）。従来 claude は per-session の
-      // softDetach タイマー（7 日）だけで件数上限が無かったため、多数の cwd を渡り歩くと warm な
+      // 子⑤ (T06544): claude 側 warm 境界（per-cwd=K / N-cwd LRU）。K は現行の既定 3
+      // （**旧仕様**は per-cwd=1 で「各 cwd 1 本」だった。1 cwd で複数会話を同時に生かすため
+      // 一般化し、総量は下の総 live 上限 M で押さえる）。従来 claude は per-session の softDetach
+      // タイマー（7 日）だけで件数上限が無かったため、多数の cwd を渡り歩くと warm な
       // SDK 常駐 query が蓄積し得た。codex の reconcileSessions と対で cwd 単位に有界化する。
       try {
         claudeBridge?.reconcileWarmBounds?.()
@@ -2279,6 +2254,18 @@ export function startStateLoop({ client, plugins, logger, intervalMs, claudeBrid
       } catch (err) {
         logger?.warn({ err: err?.message }, "gcAbandonedSessions failed")
       }
+      // 総 live 上限 M（claude + codex 合算、既定 20）。per-cwd を 1 → K（既定 3）へ緩めたぶん、
+      // cwd 単位の境界だけでは総量が膨らむため、cwd をまたいだ天井をここで適用する。
+      // ⚠️ 両 CLI の reconcile が **終わった後**に呼ぶ（cwd 単位で畳んだ結果の生存数で判定する）。
+      try {
+        enforceTotalLiveBound({
+          bridges: [claudeBridge, codexBridge].filter(Boolean),
+          logger,
+          logState: warmBoundsLogState,
+        })
+      } catch (err) {
+        logger?.warn({ err: err?.message }, "enforceTotalLiveBound failed")
+      }
       // 実コンテキスト窓サイズ (1M ベータ等) を反映。contextPctFromUsage の分母を
       // 5s ごとに最新化し、ドーナツが 200k 固定で振り切れるのを防ぐ。
       await refreshContextWindow()
@@ -2644,12 +2631,6 @@ export function startStateLoop({ client, plugins, logger, intervalMs, claudeBrid
   }
 }
 
-/**
- * Hub からのメッセージを type で分岐する。
- *
- * `pty.*` は PtyBridge にそのまま流す。`tmux.exec` は Sprint E で tmux 抽象に
- * 渡す予定なので、現状は plugin hook chain だけ走らせて log に残す。
- */
 /**
  * Hub から `ready` / `ack` で配信された Claude/Codex CLI 設定を agent.json と
  * in-memory config に反映する (Phase 3 live-sync)。
@@ -2724,12 +2705,11 @@ const STREAMS_SYNC_GRACE_MS = 45_000
  * Plan ε: `agent.streams.sync.response` を受けて backend ↔ agent の現存
  * stream_id を能動同期する。
  *
- * - PTY: local にあって backend にない → ptyBridge.detach、逆差分 → pty.error
  * - Claude/Codex: mode 別 snapshot から外れた古い subscriber を grace 付きで掃除
  *
- * active_stream_ids だけを全件 PTY とみなすと、正常な Claude/Codex に
- * pty.error(stream_not_found_on_agent) を返して再 attach storm を誘発するため、
- * 新 backend の active_streams を優先する。
+ * mode 別 snapshot (active_streams) が active_stream_ids と完全に一致するときだけ
+ * authoritative とみなす。Blue-Green ローリング中の mode 無し応答や未知 mode が
+ * 混ざった場合は掃除を一切行わない (誤って現役 subscriber を切らないための fail-safe)。
  *
  * dispatch から呼ぶ用のヘルパーだが、テストから直接叩けるよう export している。
  */
@@ -2737,7 +2717,7 @@ export function handleStreamsSyncResponse(msg, ctx) {
   const activeIds = new Set(
     Array.isArray(msg?.active_stream_ids) ? msg.active_stream_ids : [],
   )
-  const activeByMode = { pty: new Set(), claude: new Set(), codex: new Set() }
+  const activeByMode = { claude: new Set(), codex: new Set() }
   const classifiedIds = new Set()
   if (Array.isArray(msg?.active_streams)) {
     for (const item of msg.active_streams) {
@@ -2750,62 +2730,11 @@ export function handleStreamsSyncResponse(msg, ctx) {
     }
   }
   // Blue-Green ローリング中に旧 BrowserConsumer の mode 無し応答が混ざった場合は
-  // typed snapshot を authoritative とみなさない。既知 chat stream だけ除外して
-  // legacy 互換を維持し、正常な Claude/Codex に ghost PTY error を返さない。
+  // typed snapshot を authoritative とみなさず、掃除を一切行わない (legacy 互換)。
   const haveCompleteModeSnapshot =
     Array.isArray(msg?.active_streams)
     && classifiedIds.size === activeIds.size
     && Array.from(classifiedIds).every((id) => activeIds.has(id))
-  const knownChatIds = new Set([
-    ...Array.from(ctx.claudeBridge?.sessions?.keys?.() ?? []),
-    ...Array.from(ctx.codexBridge?.sessions?.keys?.() ?? []),
-  ])
-  const activePtyIds = haveCompleteModeSnapshot
-    ? activeByMode.pty
-    : new Set(Array.from(activeIds).filter((id) => !knownChatIds.has(id)))
-  const localIds = new Set(ctx.ptyBridge.list())
-  // churn 退化スナップショット保護 (ack_lost 根治 / 2026-06-17 根因 rank3)。
-  // backend は browser 群へ _STREAMS_SYNC_TIMEOUT_S(0.5s) だけ問い合わせて active set を
-  // 集める。再接続バースト中 (本番 ~20s 間隔・code 1006) は browser がまだ再 attach できて
-  // おらず空/部分的な set が返り、その一瞬を authoritative とみなして「ローカル全 stream が
-  // 孤児」と誤判定し、生きている PTY を皆殺しにしていた (再 attach 直後の stream を 1 秒後に
-  // 殺し、以後の入力が stream_missing → 数分単位の「送信待ち」固着。0.6.89 ログ最多 churn 源)。
-  // 空 set は信用せず kill を一切行わない (真の孤児は 10min GC + maxStreams 上限が回収する)。
-  const haveAuthoritativeActiveSet = activeIds.size > 0
-  for (const sid of localIds) {
-    if (activePtyIds.has(sid)) continue
-    if (!haveAuthoritativeActiveSet) continue
-    // grace guard: 直近 STREAMS_SYNC_GRACE_MS 以内に touch (attach/write/resize/pty 出力) された
-    // stream は「browser が再接続中で 0.5s 集計に間に合わなかっただけ」の可能性が高い。猶予内は
-    // 殺さず延命する。真に放置された孤児は猶予超過で従来どおり detach され、10min GC も backstop。
-    const lastSeen = ctx.ptyBridge.getLastSeen?.(sid) ?? 0
-    const idleMs = Date.now() - lastSeen
-    if (lastSeen > 0 && idleMs < STREAMS_SYNC_GRACE_MS) {
-      ctx.logger?.info?.(
-        { stream_id: sid, idle_ms: idleMs, request_id: msg?.request_id },
-        "Plan ε: skip detach (within grace, browser likely re-attaching)",
-      )
-      continue
-    }
-    ctx.logger?.warn?.(
-      { stream_id: sid, request_id: msg?.request_id },
-      "Plan ε: orphan stream detected, detaching",
-    )
-    ctx.ptyBridge.detach({ stream_id: sid })
-  }
-  for (const sid of activePtyIds) {
-    if (!localIds.has(sid)) {
-      ctx.logger?.warn?.(
-        { stream_id: sid, request_id: msg?.request_id },
-        "Plan ε: stream missing on agent, notifying backend (pty.error)",
-      )
-      ctx.client.send({
-        type: "pty.error",
-        stream_id: sid,
-        error: "stream_not_found_on_agent",
-      })
-    }
-  }
 
   if (haveCompleteModeSnapshot) {
     // reconnect 集計は browser ごとの復帰順で一時的に部分集合になり得る。
@@ -2853,34 +2782,16 @@ export function pruneInactiveChatSubscribers(bridge, activeIds, mode, logger, no
   return removed
 }
 
-/**
- * end-to-end 配達確認 (tracked pty.data) の冪等化レジストリ。
- *
- * browser はチャット送信 (paste / 確定 CR) に input_id を付け、agent からの
- * pty.input.ack が来ない限り再送する (zombie WS / 切断窓 / backend group_send の
- * 無言喪失への対策)。「実際は届いていたが ack 側が消えた」再送で同じ本文が
- * 二重 paste されないよう、処理済み input_id を記憶して 2 回目以降は write せず
- * ack だけ返す。Set は挿入順 iterate できるので最古から間引く。
- */
-const SEEN_INPUT_IDS_MAX = 1_000
-const seenInputIds = new Set()
-function rememberInputId(input_id) {
-  seenInputIds.add(input_id)
-  while (seenInputIds.size > SEEN_INPUT_IDS_MAX) {
-    seenInputIds.delete(seenInputIds.values().next().value)
-  }
-}
-
 /**
  * SDK チャット配達保証 (S2, 2026-07-05) 用の冪等化レジストリ。
  *
  * `claude.input` / `codex.input` に browser が付与する `input_id` を記憶し、ack
  * ウォッチドッグ再送 (browser 側が 5s 以内に ack/nack を受け取れず再送するケース) で
- * 同じメッセージが 2 回ターン実行されないようにする。tracked pty.data
- * (`seenInputIds` 上) と同じ設計だが、チャンネル別に Set を分ける
- * (input_id の採番元は browser 側で共通の可能性があるが、pty と chat で
- * 意味論が異なる衝突を避けるため)。
+ * 同じメッセージが 2 回ターン実行されないようにする。Set は挿入順 iterate できるので
+ * 最古から間引く。claude / codex でチャンネル別に Set を分ける (input_id の採番元は
+ * browser 側で共通の可能性があるため、意味論が異なる衝突を避ける)。
  */
+const SEEN_INPUT_IDS_MAX = 1_000
 function makeSeenInputIdRegistry(max = SEEN_INPUT_IDS_MAX) {
   const seen = new Set()
   return {
@@ -2910,49 +2821,6 @@ const codexInflightByInputId = new Map()
 // 同一 input_id がキューに 2 件積まれて drain 後も 1 件残る (送信待ちチップが消えない)。
 const claudeInflightByInputId = new Map()
 
-/**
- * input_id 付き pty.data (tracked 入力) の処理。write 成功で pty.input.ack を返し、
- * stream 不在なら pty.error を返して browser の再 attach → 再送に繋げる。
- * テストから直接呼べるよう dispatch から切り出して export する。
- */
-export function handleTrackedPtyData(msg, ctx) {
-  const { stream_id, input_id } = msg
-  if (seenInputIds.has(input_id)) {
-    // 再送 (ack 喪失 or 再接続 flush)。書き込み済みなので ack だけ返す。
-    ctx.logger?.info({ stream_id, input_id }, "tracked pty.data dedup (ack only)")
-    ctx.client.send({ type: "pty.input.ack", stream_id, input_id })
-    return
-  }
-  const ok = ctx.ptyBridge.write({ stream_id, data: msg.data })
-  if (ok) {
-    rememberInputId(input_id)
-    ctx.client.send({ type: "pty.input.ack", stream_id, input_id })
-  } else {
-    // stream 不在 (reap 済み等)。browser は pty.error で再 attach し、未 ack の
-    // tracked 入力は ack ウォッチドッグが再送する。
-    ctx.client.send({
-      type: "pty.error",
-      stream_id,
-      error: "stream_missing",
-      input_id,
-    })
-  }
-}
-
-/**
- * 無印 (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" })
-  }
-}
-
 /**
  * SDK チャット配達保証 (S2, 2026-07-05): `claude.input` を処理し、browser が付与した
  * `input_id` があれば `claude.input.ack` / `claude.input.nack` を返す。無ければ従来
@@ -2960,8 +2828,7 @@ export function handleUntrackedPtyData(msg, ctx) {
  *
  * `ClaudeStreamBridge.input()` の戻り値 `{ ok, reason? }` は「ターン完走」ではなく
  * 「キュー/常駐 query への投入が完了したか」を表す (ack を素早く返すため)。
- * テストから直接呼べるよう dispatch から切り出して export する
- * (handleTrackedPtyData と同じ設計)。
+ * テストから直接呼べるよう dispatch から切り出して export する。
  */
 export function handleClaudeChatInput(msg, ctx) {
   const stream_id = msg.stream_id
@@ -2979,7 +2846,7 @@ export function handleClaudeChatInput(msg, ctx) {
   }
   if (input_id && seenClaudeChatInputIds.has(input_id)) {
     // 再送 (ack 喪失想定)。同じターンを 2 回実行しないよう sendMessage を
-    // 呼び直さず ack のみ返す (tracked pty.data の dedup と同じ考え方)。
+    // 呼び直さず ack のみ返す。
     ctx.logger?.info?.({ stream_id, input_id }, "claude.input dedup (ack only)")
     ctx.client.send({ type: "claude.input.ack", stream_id, input_id })
     return undefined
@@ -3045,6 +2912,62 @@ export function handleClaudeChatInput(msg, ctx) {
   return p
 }
 
+/**
+ * `tmux.exec` を処理し、`tmux.result` を返す。
+ *
+ * plugin の `interceptTmuxExec` hook が `{ command, args, env }` を返したときは、その
+ * command を代わりに spawn する (例: remote-ops プラグインで ssh 越しに実行)。hook が
+ * 何も返さなければ既定のローカル `execTmux` へ落ちる。どちらの経路でも
+ * `request_id` / `stdout` / `stderr` / `exit_code` / `plugin` の 5 フィールドを揃えて返す。
+ *
+ * dispatch から呼ぶ用のヘルパーだが、テストから直接叩けるよう export している
+ * (handleStreamsSyncResponse / handleClaudeChatInput と同じ扱い)。
+ *
+ * @param {{request_id?:string, args?:string[]}} msg
+ * @param {{plugins:any[], logger:object, client:{send:Function}}} ctx
+ * @param {{execTmux?:Function}} [deps] 既定実装の差し替え口 (テスト専用)。
+ */
+export async function handleTmuxExec(msg, ctx, deps = {}) {
+  const execTmuxImpl = deps.execTmux || execTmux
+  const args = Array.isArray(msg.args) ? msg.args : []
+  const hookResult = await runHookChain(ctx.plugins, "interceptTmuxExec", {
+    logger: ctx.logger,
+    args,
+    env: process.env,
+  })
+  let result
+  if (hookResult?.result?.command) {
+    // plugin が独自 command で差し替え (例: remote-ops プラグインで ssh 越し)
+    const { command, args: spawnArgs, env } = hookResult.result
+    try {
+      const { execFile } = await import("node:child_process")
+      const { promisify } = await import("node:util")
+      const execFileP = promisify(execFile)
+      const { stdout, stderr } = await execFileP(command, spawnArgs, {
+        env: env || process.env,
+        maxBuffer: 4 * 1024 * 1024,
+      })
+      result = { stdout, stderr, exit_code: 0 }
+    } catch (err) {
+      result = {
+        stdout: err.stdout || "",
+        stderr: err.stderr || err.message || "",
+        exit_code: typeof err.code === "number" ? err.code : 1,
+      }
+    }
+  } else {
+    result = await execTmuxImpl(args)
+  }
+  ctx.client.send({
+    type: "tmux.result",
+    request_id: msg.request_id,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exit_code: result.exit_code,
+    plugin: hookResult?.plugin || null,
+  })
+}
+
 /**
  * claude.attach の ready 直後にpushする履歴を組み立てる。
  * Browserからの claude.history.request 往復を省くため、resume時だけ先回りして読む。
@@ -3719,74 +3642,6 @@ async function dispatch(msg, ctx) {
         await ctx.requestShutdown?.("agent.shutdown")
         return
       }
-      case "pty.attach": {
-        const stream_id = msg.stream_id
-        try {
-          const info = await ctx.ptyBridge.attach({
-            stream_id,
-            sessionName: msg.session_name || "",
-            cols: msg.cols,
-            rows: msg.rows,
-          })
-          // 接続端末の種別に応じて tmux mouse mode を出し分ける (スマホ=on /
-          // デスクトップ=off)。boolean のときだけ上書きし、未指定 (旧フロント) は
-          // createSession の既定値 (on) を尊重する。fire-and-forget で pty.ready を
-          // 妨げない (失敗は setSessionMouse 内で warn 済み)。
-          if (typeof msg.mouse === "boolean" && msg.session_name) {
-            setSessionMouse(msg.session_name, msg.mouse, { logger: ctx.logger })
-          }
-          ctx.client.send({
-            type: "pty.ready",
-            stream_id,
-            session_name: msg.session_name || "",
-            plugin: info.plugin,
-            // end-to-end 配達確認 (input_id 付き pty.data → pty.input.ack) に対応
-            // していることを browser へ通知する capability フラグ。旧 agent には
-            // このフラグが無く、browser 側は tracked 送信を自動で無効化する。
-            supports_input_ack: true,
-          })
-        } catch (err) {
-          ctx.client.send({
-            type: "pty.exit",
-            stream_id,
-            code: -1,
-            error: err.message,
-          })
-        }
-        return
-      }
-      case "pty.data":
-        // input_id 付き = tracked 入力 (チャット送信)。冪等化 + ack 返却で
-        // end-to-end 配達確認に応える。無印は従来どおり fire-and-forget。
-        if (typeof msg.input_id === "string" && msg.input_id) {
-          handleTrackedPtyData(msg, ctx)
-          return
-        }
-        handleUntrackedPtyData(msg, ctx)
-        return
-      case "pty.resize": {
-        const resized = ctx.ptyBridge.resize({
-          stream_id: msg.stream_id,
-          cols: msg.cols,
-          rows: msg.rows,
-        })
-        // 自己修復 (perf監査 Phase3): stream 不在で resize できなかった (reap 済み等) ときは
-        // pty.error(stream_missing) を返し browser を再 attach させる。keepalive resize が dead
-        // stream を即検知して 4 分単位の「pty.resize but stream missing」churn を自己修復する
-        // (handleTrackedPtyData/handleUntrackedPtyData と同じパターン)。resize 例外 (pty 存在) も
-        // false だが、その場合の再 attach は既存 stream への無害な再接続。
-        if (!resized && msg.stream_id) {
-          ctx.client.send({
-            type: "pty.error",
-            stream_id: msg.stream_id,
-            error: "stream_missing",
-          })
-        }
-        return
-      }
-      case "pty.detach":
-        ctx.ptyBridge.detach({ stream_id: msg.stream_id })
-        return
       case "agent.streams.sync.response":
         // Plan ε: backend ↔ agent の現存 stream_id 能動同期 (WS reconnect 直後に
         // ws-client が agent.streams.sync.request を送って取得した結果)。
@@ -3795,13 +3650,13 @@ async function dispatch(msg, ctx) {
         // 5s タイムアウトのような明示的な timer は持たず、再接続時に再度 request
         // が飛ぶので無害。
         handleStreamsSyncResponse(msg, ctx)
-        // buffered pty/control event は browser の購読集合が確定してから再送する。
+        // buffered control event は browser の購読集合が確定してから再送する。
         // request_id は WsClient 側で現 reconnect 世代と照合され、古い応答は無視される。
         ctx.client.completeStreamsSync?.(msg)
         return
       case "claude.attach": {
         // Sprint G: stream-json モードで Claude Code を起動。
-        // browser 採番の stream_id をそのまま使う (pty.attach と同じ流儀)。
+        // stream_id は browser 採番のものをそのまま使う。
         const stream_id = msg.stream_id
         if (!ctx.claudeBridge) {
           // SDK 未インストール時はその旨を即時 error で返す。browser 側は
@@ -4460,8 +4315,8 @@ async function dispatch(msg, ctx) {
         ctx.codexBridge.detach({ stream_id: msg.stream_id })
         return
       case "codex.keepalive":
-        // ブラウザが Codex チャットを開いている間の生存シグナル (CockpitTerminal.tsx の
-        // PTY keepalive と同じ構造)。閲覧中に gcAbandonedSessions (既定 1h 無通信) が
+        // ブラウザが Codex チャットを開いている間の生存シグナル。
+        // 閲覧中に gcAbandonedSessions (既定 1h 無通信) が
         // 誤爆するのを防ぐ。未知 stream_id は false が返るだけ (無害な no-op)。
         if (!ctx.codexBridge) return
         ctx.codexBridge.keepalive({ stream_id: msg.stream_id })
@@ -4884,43 +4739,8 @@ async function dispatch(msg, ctx) {
         return
       }
       case "tmux.exec": {
-        const args = Array.isArray(msg.args) ? msg.args : []
-        const hookResult = await runHookChain(ctx.plugins, "interceptTmuxExec", {
-          logger: ctx.logger,
-          args,
-          env: process.env,
-        })
-        let result
-        if (hookResult?.result?.command) {
-          // plugin が独自 command で差し替え (例: remote-ops プラグインで ssh 越し)
-          const { command, args: spawnArgs, env } = hookResult.result
-          try {
-            const { execFile } = await import("node:child_process")
-            const { promisify } = await import("node:util")
-            const execFileP = promisify(execFile)
-            const { stdout, stderr } = await execFileP(command, spawnArgs, {
-              env: env || process.env,
-              maxBuffer: 4 * 1024 * 1024,
-            })
-            result = { stdout, stderr, exit_code: 0 }
-          } catch (err) {
-            result = {
-              stdout: err.stdout || "",
-              stderr: err.stderr || err.message || "",
-              exit_code: typeof err.code === "number" ? err.code : 1,
-            }
-          }
-        } else {
-          result = await execTmux(args)
-        }
-        ctx.client.send({
-          type: "tmux.result",
-          request_id: msg.request_id,
-          stdout: result.stdout,
-          stderr: result.stderr,
-          exit_code: result.exit_code,
-          plugin: hookResult?.plugin || null,
-        })
+        // ロジックは handleTmuxExec へ抽出 (テストから直接呼べる)。
+        await handleTmuxExec(msg, ctx)
         return
       }
       case "tmux.list_sessions": {