@cocorograph/hub-agent 0.5.31 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.5.31",
+  "version": "0.6.0",
   "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの tmux/pty を中継する。",
   "type": "module",
   "license": "UNLICENSED",
@@ -32,6 +32,7 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.152",
     "commander": "^12.1.0",
     "node-pty": "^1.0.0",
     "pino": "^9.0.0",

package/src/claude-stream-bridge.mjs

@@ -0,0 +1,363 @@
+/**
+ * Claude Code stream-json モードのブリッジ (Sprint G: Web UI 対応)。
+ *
+ * - 1 stream = 1 Claude セッション。`Map<stream_id, ClaudeStreamSession>` で多重管理
+ * - 公式 `@anthropic-ai/claude-agent-sdk` の `query()` を async iterable で駆動
+ * - `attach({ stream_id, cwd, model, permissionMode, resumeSessionId? })` でセッション起動
+ * - `input({ stream_id, message })` で stdin 相当のユーザーメッセージを push
+ * - `permissionReply({ stream_id, request_id, allow, updatedInput?, denyMessage? })` で
+ *   `canUseTool` callback への応答を browser から返す
+ * - `interrupt({ stream_id })` / `detach({ stream_id })` で中断・停止
+ * - 出力イベントは `'event'`（SDK message）/ `'permission'`（canUseTool）/
+ *   `'exit'` / `'error'` で emit。EventEmitter 経由
+ *
+ * PtyBridge と並走させる設計。`pty.*` 系メッセージは無傷で、新規 `claude.*` のみ
+ * 受け持つ。テスト時は SDK を `{ query }` shape で stub 注入する。
+ */
+import { EventEmitter } from "node:events"
+import { randomUUID } from "node:crypto"
+
+/**
+ * 1 stream に対応する Claude セッション。
+ *
+ * SDK の `query()` は prompt を AsyncIterable として受け取り、ユーザーメッセージを
+ * 流し続ける限り interactive multi-turn として動作する。pushInput / endInput で
+ * iterator の挙動を制御する。
+ */
+class ClaudeStreamSession {
+  /**
+   * @param {object} args
+   * @param {string} args.stream_id
+   * @param {string} args.cwd
+   * @param {string|null} args.model
+   * @param {string|null} args.permissionMode
+   * @param {string|null} args.resumeSessionId
+   * @param {{ query: Function }} args.sdk
+   * @param {import('pino').Logger} [args.logger]
+   * @param {(event: object) => void} [args.onEvent]
+   * @param {(req: {tool_name: string, input: object, request_id: string}) => void} [args.onPermission]
+   * @param {(info: {code: number, reason?: string, session_id: string|null}) => void} [args.onExit]
+   * @param {(err: Error) => void} [args.onError]
+   */
+  constructor({
+    stream_id,
+    cwd,
+    model,
+    permissionMode,
+    resumeSessionId,
+    sdk,
+    logger,
+    onEvent,
+    onPermission,
+    onExit,
+    onError,
+  }) {
+    this.stream_id = stream_id
+    this.cwd = cwd
+    this.model = model || null
+    this.permissionMode = permissionMode || null
+    this.resumeSessionId = resumeSessionId || null
+    this.sdk = sdk
+    this.logger = logger
+    this.onEvent = onEvent
+    this.onPermission = onPermission
+    this.onExit = onExit
+    this.onError = onError
+
+    /** Claude が `system/init` イベントで返してくる session_id を保持する。
+     *  resume 時はその値で上書きされる。frontend が「現在のセッション」を識別する用。 */
+    this.sessionId = resumeSessionId || null
+
+    /** @type {Array<{__end?: true, type?: string, message?: object}>} pending stdin queue */
+    this._pendingInputs = []
+    /** @type {Array<(v: {value: any, done: boolean}) => void>} 待機中の iterator resolvers */
+    this._inputResolvers = []
+    /** @type {Map<string, {resolve: (decision: object) => void}>} request_id 別の permission 応答待ち */
+    this._permissionResolvers = new Map()
+
+    this._aborted = false
+    this._finished = false
+    this._abortController = new AbortController()
+  }
+
+  /** browser → claude へ user メッセージを push。
+   *  message: `{ role: 'user', content: string | Array }` を期待 (SDK の SDKUserMessage 形式)。 */
+  pushInput(message) {
+    if (this._finished) return
+    const wrapped = { type: "user", message }
+    if (this._inputResolvers.length > 0) {
+      const resolver = this._inputResolvers.shift()
+      resolver({ value: wrapped, done: false })
+    } else {
+      this._pendingInputs.push(wrapped)
+    }
+  }
+
+  /** stdin EOF 相当: prompt iterator を終了させる。 */
+  endInput() {
+    if (this._inputResolvers.length > 0) {
+      const resolver = this._inputResolvers.shift()
+      resolver({ value: undefined, done: true })
+    } else {
+      this._pendingInputs.push({ __end: true })
+    }
+  }
+
+  /** AbortController で実行中の turn を即時中断する。SDK 側は AbortError を投げる。 */
+  abort() {
+    this._aborted = true
+    try {
+      this._abortController.abort()
+    } catch {
+      /* ignore */
+    }
+    // 未解決の permission 応答も deny で閉じる (SDK 側のループを早期解放するため)
+    for (const [, resolver] of this._permissionResolvers) {
+      try {
+        resolver.resolve({ behavior: "deny", message: "aborted" })
+      } catch {
+        /* ignore */
+      }
+    }
+    this._permissionResolvers.clear()
+    this.endInput()
+  }
+
+  /** browser からの permission 応答を該当 request_id の Promise に渡す。 */
+  resolvePermission(request_id, decision) {
+    const r = this._permissionResolvers.get(request_id)
+    if (!r) return false
+    this._permissionResolvers.delete(request_id)
+    r.resolve(decision)
+    return true
+  }
+
+  /** SDK の query() に渡す async iterable。pushInput で入ってきたメッセージを yield する。 */
+  async *_promptIterator() {
+    while (true) {
+      if (this._pendingInputs.length > 0) {
+        const next = this._pendingInputs.shift()
+        if (next && next.__end) return
+        yield next
+        continue
+      }
+      const next = await new Promise((resolve) => {
+        this._inputResolvers.push(resolve)
+      })
+      if (next.done) return
+      yield next.value
+    }
+  }
+
+  /** SDK options.canUseTool: tool 起動を許可するかを browser に問い合わせる。 */
+  async _canUseTool(toolName, input, _extra) {
+    if (!this.onPermission) return { behavior: "allow", updatedInput: input }
+    const request_id = randomUUID()
+    return await new Promise((resolve) => {
+      this._permissionResolvers.set(request_id, { resolve })
+      try {
+        this.onPermission({ tool_name: toolName, input, request_id })
+      } catch (err) {
+        this.logger?.warn(
+          { err: err.message, stream_id: this.stream_id, tool: toolName },
+          "onPermission callback threw",
+        )
+        this._permissionResolvers.delete(request_id)
+        resolve({ behavior: "deny", message: "permission callback failed" })
+      }
+    })
+  }
+
+  /** 非同期で SDK を駆動。エラーは onError + onExit に流す。 */
+  async run() {
+    let code = 0
+    let reason
+    try {
+      const options = {
+        cwd: this.cwd,
+        canUseTool: (toolName, input, extra) => this._canUseTool(toolName, input, extra),
+        includePartialMessages: true,
+        abortController: this._abortController,
+      }
+      if (this.model) options.model = this.model
+      if (this.permissionMode) options.permissionMode = this.permissionMode
+      if (this.resumeSessionId) options.resume = this.resumeSessionId
+
+      const generator = this.sdk.query({
+        prompt: this._promptIterator(),
+        options,
+      })
+
+      for await (const msg of generator) {
+        // system/init で session_id が確定する。resume 用に保持。
+        if (msg?.type === "system" && msg?.subtype === "init" && typeof msg.session_id === "string") {
+          this.sessionId = msg.session_id
+        }
+        try {
+          this.onEvent?.(msg)
+        } catch (err) {
+          this.logger?.warn(
+            { err: err.message, stream_id: this.stream_id },
+            "onEvent callback threw",
+          )
+        }
+      }
+    } catch (err) {
+      if (this._aborted) {
+        code = 130
+        reason = "aborted"
+      } else {
+        code = 1
+        reason = err?.message || String(err)
+        try {
+          this.onError?.(err)
+        } catch {
+          /* ignore */
+        }
+      }
+    } finally {
+      this._finished = true
+      try {
+        this.onExit?.({ code, reason, session_id: this.sessionId })
+      } catch (err) {
+        this.logger?.warn(
+          { err: err.message, stream_id: this.stream_id },
+          "onExit callback threw",
+        )
+      }
+    }
+  }
+}
+
+export class ClaudeStreamBridge extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {{ query: Function }} opts.sdk - `@anthropic-ai/claude-agent-sdk` の named import 結果
+   *   (テストでは `{ query: stubQuery }` を渡す)
+   * @param {import('pino').Logger} [opts.logger]
+   */
+  constructor({ sdk, logger } = {}) {
+    super()
+    if (!sdk || typeof sdk.query !== "function") {
+      throw new TypeError("ClaudeStreamBridge requires { sdk: { query } }")
+    }
+    this.sdk = sdk
+    this.logger = logger
+    /** @type {Map<string, ClaudeStreamSession>} */
+    this.sessions = new Map()
+  }
+
+  /**
+   * 新しい Claude セッションを開始する。
+   *
+   * @param {{
+   *   stream_id: string,
+   *   cwd?: string,
+   *   model?: string|null,
+   *   permissionMode?: string|null,
+   *   resumeSessionId?: string|null,
+   * }} args
+   * @returns {{ stream_id: string, resuming: boolean }}
+   */
+  attach({ stream_id, cwd, model, permissionMode, resumeSessionId }) {
+    if (!stream_id) throw new TypeError("attach requires stream_id")
+    if (this.sessions.has(stream_id)) {
+      throw new Error(`stream_id "${stream_id}" は既に attach 済みです`)
+    }
+    const session = new ClaudeStreamSession({
+      stream_id,
+      cwd: cwd || process.env.HOME || process.cwd(),
+      model: model || null,
+      permissionMode: permissionMode || null,
+      resumeSessionId: resumeSessionId || null,
+      sdk: this.sdk,
+      logger: this.logger,
+      onEvent: (event) => {
+        this.emit("event", { stream_id, session_id: session.sessionId, event })
+      },
+      onPermission: ({ tool_name, input, request_id }) => {
+        this.emit("permission", { stream_id, request_id, tool_name, input })
+      },
+      onExit: ({ code, reason, session_id }) => {
+        this.sessions.delete(stream_id)
+        this.emit("exit", { stream_id, code, reason, session_id })
+      },
+      onError: (err) => {
+        this.emit("error", { stream_id, error: err?.message || String(err) })
+      },
+    })
+    this.sessions.set(stream_id, session)
+    this.logger?.info(
+      { stream_id, cwd: session.cwd, model: session.model, resume: !!resumeSessionId },
+      "claude stream attached",
+    )
+    // 非同期で run。run 内で onExit → sessions から自動削除。
+    session.run().catch((err) => {
+      this.logger?.error(
+        { stream_id, err: err?.message },
+        "claude stream run threw unexpectedly",
+      )
+    })
+    return { stream_id, resuming: !!resumeSessionId }
+  }
+
+  /** browser → claude の user メッセージ。message は SDKUserMessage の message フィールド (`{ role, content }`)。 */
+  input({ stream_id, message }) {
+    const s = this.sessions.get(stream_id)
+    if (!s) {
+      this.logger?.warn({ stream_id }, "claude.input but stream missing")
+      return false
+    }
+    s.pushInput(message)
+    return true
+  }
+
+  /** browser → claude の permission 応答。allow/deny + 加工された input を SDK に返す。 */
+  permissionReply({ stream_id, request_id, allow, updatedInput, denyMessage }) {
+    const s = this.sessions.get(stream_id)
+    if (!s) {
+      this.logger?.warn({ stream_id, request_id }, "claude.permission.reply but stream missing")
+      return false
+    }
+    const decision = allow
+      ? { behavior: "allow", updatedInput: updatedInput || {} }
+      : { behavior: "deny", message: denyMessage || "denied by user" }
+    return s.resolvePermission(request_id, decision)
+  }
+
+  /** turn 中断 (AbortController)。セッションは exit に到達する。 */
+  interrupt({ stream_id }) {
+    const s = this.sessions.get(stream_id)
+    if (!s) return false
+    s.abort()
+    return true
+  }
+
+  /** セッション停止。Map から即時削除し、abort で SDK ループを解放する。 */
+  detach({ stream_id }) {
+    const s = this.sessions.get(stream_id)
+    if (!s) return false
+    s.abort()
+    // onExit を待たずに Map から外す (再 attach を即座に許可するため)
+    this.sessions.delete(stream_id)
+    return true
+  }
+
+  /** 全セッションを停止 (agent shutdown 用)。 */
+  shutdown() {
+    for (const stream_id of Array.from(this.sessions.keys())) {
+      this.detach({ stream_id })
+    }
+  }
+
+  /** 現在 attach 中の stream_id 一覧 (debug 用)。 */
+  list() {
+    return Array.from(this.sessions.keys())
+  }
+
+  /** 該当 stream の session_id (Claude SDK 由来) を返す。resume 用。 */
+  getSessionId(stream_id) {
+    const s = this.sessions.get(stream_id)
+    return s ? s.sessionId : null
+  }
+}

package/src/main.mjs

@@ -21,6 +21,7 @@ import { readConfig, writeConfig } from "./config.mjs"
 import { loadPlugins, runHookBroadcast, runHookChain } from "./plugin-loader.mjs"
 import { WsClient } from "./ws-client.mjs"
 import { PtyBridge } from "./pty-bridge.mjs"
+import { ClaudeStreamBridge } from "./claude-stream-bridge.mjs"
 import { listAgents } from "./agents.mjs"
 import { listSkills } from "./skills.mjs"
 import { listSessionStates } from "./state.mjs"
@@ -97,7 +98,33 @@ function readBundleVersionSync() {
   }
 }
 
-export async function startDaemon({ version, ptyModule } = {}) {
+/**
+ * `@anthropic-ai/claude-agent-sdk` を lazy import する。テストでは sdk arg で差し替え。
+ *
+ * SDK 未インストール (旧 hub-agent インストール) 環境でも pty モードは動くべきなので、
+ * import 失敗を warn に留めて null を返す。stream モードを使う attach が来たら
+ * その時点で error を browser に返す設計。
+ */
+async function loadClaudeSdk(logger) {
+  try {
+    const mod = await import("@anthropic-ai/claude-agent-sdk")
+    if (typeof mod?.query !== "function") {
+      logger?.warn(
+        "@anthropic-ai/claude-agent-sdk loaded but no query export; stream mode disabled",
+      )
+      return null
+    }
+    return mod
+  } catch (err) {
+    logger?.warn(
+      { err: err.message },
+      "@anthropic-ai/claude-agent-sdk not installed; stream mode disabled",
+    )
+    return null
+  }
+}
+
+export async function startDaemon({ version, ptyModule, claudeSdk } = {}) {
   const config = await readConfig()
   if (!config) {
     throw new Error(
@@ -113,6 +140,13 @@ export async function startDaemon({ version, ptyModule } = {}) {
   const resolvedPty = ptyModule || (await import("node-pty"))
   const ptyBridge = new PtyBridge({ ptyModule: resolvedPty, logger, plugins })
 
+  // Claude SDK は optional dep 扱い (未インストール時は stream モードのみ無効化)。
+  // テストでは引数で stub を差し込める。
+  const resolvedSdk = claudeSdk !== undefined ? claudeSdk : await loadClaudeSdk(logger)
+  const claudeBridge = resolvedSdk
+    ? new ClaudeStreamBridge({ sdk: resolvedSdk, logger })
+    : null
+
   const bundleVersion = await readBundleVersion()
   if (bundleVersion) {
     logger.info({ bundleVersion }, "hub bundle version detected")
@@ -139,6 +173,30 @@ export async function startDaemon({ version, ptyModule } = {}) {
     client.send({ type: "pty.exit", stream_id, code })
   })
 
+  // stream-json モード (Sprint G): Claude Code を SDK 経由で起動し、stream イベントを
+  // そのまま browser に転送する。SDK 未インストール時は claudeBridge=null で全 attach が
+  // claude.error を返す経路に分岐 (dispatch 側で判定)。
+  if (claudeBridge) {
+    claudeBridge.on("event", ({ stream_id, session_id, event }) => {
+      client.send({ type: "claude.event", stream_id, session_id, event })
+    })
+    claudeBridge.on("permission", ({ stream_id, request_id, tool_name, input }) => {
+      client.send({
+        type: "claude.permission.request",
+        stream_id,
+        request_id,
+        tool_name,
+        input,
+      })
+    })
+    claudeBridge.on("exit", ({ stream_id, code, reason, session_id }) => {
+      client.send({ type: "claude.exit", stream_id, code, reason, session_id })
+    })
+    claudeBridge.on("error", ({ stream_id, error }) => {
+      client.send({ type: "claude.error", stream_id, error })
+    })
+  }
+
   // Hub からのメッセージ dispatch は **直列実行** する。
   //
   // `EventEmitter.emit` は async リスナーの完了を待たないため、`async (msg) =>
@@ -160,7 +218,7 @@ export async function startDaemon({ version, ptyModule } = {}) {
   let dispatchChain = Promise.resolve()
   client.on("message", (msg) => {
     dispatchChain = dispatchChain
-      .then(() => dispatch(msg, { ...ctx, client, ptyBridge }))
+      .then(() => dispatch(msg, { ...ctx, client, ptyBridge, claudeBridge }))
       .catch((err) => {
         logger.error(
           { err: err.message, type: msg?.type },
@@ -185,13 +243,14 @@ export async function startDaemon({ version, ptyModule } = {}) {
     stateLoop.stop()
     sessionEventLoop?.stop?.()
     ptyBridge.shutdown()
+    claudeBridge?.shutdown?.()
     client.stop()
     process.exit(0)
   }
   process.on("SIGINT", () => shutdown("SIGINT"))
   process.on("SIGTERM", () => shutdown("SIGTERM"))
 
-  return { client, plugins, ptyBridge }
+  return { client, plugins, ptyBridge, claudeBridge }
 }
 
 const SESSION_EVENTS_DIR =
@@ -504,6 +563,74 @@ async function dispatch(msg, ctx) {
         // が飛ぶので無害。
         handleStreamsSyncResponse(msg, ctx)
         return
+      case "claude.attach": {
+        // Sprint G: stream-json モードで Claude Code を起動。
+        // browser 採番の stream_id をそのまま使う (pty.attach と同じ流儀)。
+        const stream_id = msg.stream_id
+        if (!ctx.claudeBridge) {
+          // SDK 未インストール時はその旨を即時 error で返す。browser 側は
+          // 「ターミナルモードで開いてください」と表示するなどの fallback を想定。
+          ctx.client.send({
+            type: "claude.error",
+            stream_id,
+            error: "stream_mode_unavailable: @anthropic-ai/claude-agent-sdk が agent にインストールされていません",
+          })
+          return
+        }
+        try {
+          // cwd は明示指定が無ければ agent.json の cwd → HOME の順で fallback
+          // (将来 cockpit から worktree path を指定する用)。
+          // model / permissionMode は agent.json の値も使えるよう fallback。
+          const info = ctx.claudeBridge.attach({
+            stream_id,
+            cwd: msg.cwd || ctx.config?.claude_cwd || undefined,
+            model: msg.model || ctx.config?.claude_model || null,
+            permissionMode:
+              msg.permission_mode ||
+              ctx.config?.claude_permission_mode ||
+              null,
+            resumeSessionId: msg.resume_session_id || null,
+          })
+          ctx.client.send({
+            type: "claude.ready",
+            stream_id,
+            resuming: info.resuming,
+          })
+        } catch (err) {
+          ctx.client.send({
+            type: "claude.error",
+            stream_id,
+            error: err.message,
+          })
+        }
+        return
+      }
+      case "claude.input":
+        // message: { role: 'user', content: string | Array } を期待
+        if (!ctx.claudeBridge) return
+        ctx.claudeBridge.input({
+          stream_id: msg.stream_id,
+          message: msg.message,
+        })
+        return
+      case "claude.permission.reply":
+        if (!ctx.claudeBridge) return
+        ctx.claudeBridge.permissionReply({
+          stream_id: msg.stream_id,
+          request_id: msg.request_id,
+          allow: !!msg.allow,
+          updatedInput: msg.updated_input,
+          denyMessage: msg.deny_message,
+        })
+        return
+      case "claude.interrupt":
+        if (!ctx.claudeBridge) return
+        ctx.claudeBridge.interrupt({ stream_id: msg.stream_id })
+        return
+      case "claude.detach":
+        if (!ctx.claudeBridge) return
+        ctx.claudeBridge.detach({ stream_id: msg.stream_id })
+        return
       case "tmux.exec": {
         const args = Array.isArray(msg.args) ? msg.args : []
         const hookResult = await runHookChain(ctx.plugins, "interceptTmuxExec", {

package/src/ws-client.mjs

@@ -23,6 +23,22 @@ const MIN_BACKOFF_MS = 1_000
 const MAX_BACKOFF_MS = 30_000
 const BUNDLE_WATCH_DEBOUNCE_MS = 500
 
+// CF / origin が 5xx を返した直後の再接続は短い backoff だと 5xx キャッシュに
+// 当たって連発失敗するため、最低 5s 待つ。30s リトライまで段階的に伸びる。
+const MIN_BACKOFF_AFTER_5XX_MS = 5_000
+
+// outbound pty.data buffer のサイズ上限。
+// WS not OPEN 中に pty.data を捨てると Cockpit 上のターミナル描画が欠落して
+// 「動かない / 一部だけ表示される」体感を生むため、reconnect 後に flush する。
+// pty.data は冪等で順序維持できれば xterm 側で正しく再現できる。
+// 1 frame は典型的に 数十〜数百 bytes (claude TUI の partial redraw)。
+// 500 frame ≒ 数十KB を 1 切断あたりの上限とする。
+const PTY_BUFFER_MAX_FRAMES = 500
+// outbound buffer に残った pty.data が古すぎると、ターミナルの履歴として
+// 再生する意味が薄れる (ユーザーが視覚的に「過去のもの」として無視する範囲)。
+// 30 秒以上経過した pty.data は flush 時に破棄する。
+const PTY_BUFFER_MAX_AGE_MS = 30_000
+
 export class WsClient extends EventEmitter {
   /**
    * @param {{ hub_url: string, agent_id: string, agent_token: string }} config
@@ -55,6 +71,11 @@ export class WsClient extends EventEmitter {
     this.backoff = MIN_BACKOFF_MS
     this.stopped = false
     this.startedAt = Date.now()
+    // pty.data の outbound buffer (WS not OPEN 中に積み、open 後 flush)。
+    // entry: { obj, ts }
+    this.ptyOutboundBuffer = []
+    // 直前の close 原因が CF/origin の 5xx か。次回 backoff の下限を引き上げる。
+    this.lastCloseWas5xx = false
   }
 
   /** WSS 接続を開始する。`stop()` まで自動で reconnect 続行。 */
@@ -92,6 +113,12 @@ export class WsClient extends EventEmitter {
 
     ws.on("error", (err) => {
       this.logger?.warn({ err: err.message }, "ws error")
+      // Upgrade で CF/origin が 5xx を返した場合 (典型: "Unexpected server
+      // response: 502") は、次回 reconnect の最低 backoff を引き上げる。
+      // CF が 5xx を short-cache するため、1s 連発リトライは逆に詰まる。
+      if (/Unexpected server response: 5\d\d/.test(err?.message || "")) {
+        this.lastCloseWas5xx = true
+      }
       this.emit("error", err)
       // close もほぼ続けて飛ぶので reconnect 予約は close 側に任せる
     })
@@ -110,7 +137,13 @@ export class WsClient extends EventEmitter {
    */
   _onOpen() {
     this.backoff = MIN_BACKOFF_MS
+    this.lastCloseWas5xx = false
     this.logger?.info("ws open")
+    // 切断中に積んだ pty.data を flush。hello より先に送ると backend で stream
+    // 未登録のため unknown_stream error になる可能性があるが、hello の応答待ち
+    // 同期は backend が承認するため hello 送信後の同期 send_json で問題ない。
+    // ただし flush は hello 直後ではなく streams.sync.request の後に置く方が
+    // 安全 (sync 完了で stream_id がサーバに復元される想定)。
     // hello 前に最新の bundle version を読み直す (再接続時の鮮度確保)
     this._refreshBundleVersion()
     this._sendJson({
@@ -129,20 +162,65 @@ export class WsClient extends EventEmitter {
       type: "agent.streams.sync.request",
       request_id: randomUUID(),
     })
+    this._flushPtyBuffer()
     this._startHeartbeat()
     this._startBundleWatcher()
     this.emit("open")
   }
 
-  /** メッセージを送る。未接続なら no-op (logger.warn)。 */
+  /** メッセージを送る。未接続時は pty.data だけ buffer に積み、reconnect 後に flush。
+   *
+   * heartbeat / hello / agent.streams.sync.* など制御系は古くなると意味が無いので
+   * buffer しない (warn のみ)。
+   */
   send(obj) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      if (obj?.type === "pty.data") {
+        this._bufferPtyData(obj)
+        return false
+      }
       this.logger?.warn({ type: obj?.type }, "ws send skipped (not open)")
       return false
     }
     return this._sendJson(obj)
   }
 
+  /** pty.data を outbound buffer に積む。リング (drop oldest on overflow)。 */
+  _bufferPtyData(obj) {
+    this.ptyOutboundBuffer.push({ obj, ts: Date.now() })
+    if (this.ptyOutboundBuffer.length > PTY_BUFFER_MAX_FRAMES) {
+      const dropped = this.ptyOutboundBuffer.length - PTY_BUFFER_MAX_FRAMES
+      this.ptyOutboundBuffer.splice(0, dropped)
+      this.logger?.warn(
+        { dropped, kept: this.ptyOutboundBuffer.length },
+        "pty outbound buffer overflow (oldest dropped)"
+      )
+    }
+  }
+
+  /** open 直後に buffer を flush。古すぎる entry は破棄する。 */
+  _flushPtyBuffer() {
+    if (this.ptyOutboundBuffer.length === 0) return
+    const now = Date.now()
+    const buf = this.ptyOutboundBuffer
+    this.ptyOutboundBuffer = []
+    let sent = 0
+    let expired = 0
+    for (const entry of buf) {
+      if (now - entry.ts > PTY_BUFFER_MAX_AGE_MS) {
+        expired += 1
+        continue
+      }
+      const ok = this._sendJson(entry.obj)
+      if (!ok) break
+      sent += 1
+    }
+    this.logger?.info(
+      { sent, expired, total: buf.length },
+      "pty outbound buffer flushed"
+    )
+  }
+
   /** Reconnect を止めて切断する。 */
   stop() {
     this.stopped = true
@@ -326,11 +404,16 @@ export class WsClient extends EventEmitter {
 
   _scheduleReconnect() {
     // exponential backoff + ±20% jitter で同時接続が同期しないようにする。
-    const base = this.backoff
+    // 直前が 5xx だった場合は CF キャッシュ回避のため最低 5s を確保する。
+    const minFloor = this.lastCloseWas5xx ? MIN_BACKOFF_AFTER_5XX_MS : MIN_BACKOFF_MS
+    const base = Math.max(this.backoff, minFloor)
     const jitter = base * 0.2 * (Math.random() * 2 - 1)
-    const delay = Math.max(MIN_BACKOFF_MS, Math.round(base + jitter))
-    this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS)
-    this.logger?.info({ delayMs: delay, nextBaseMs: this.backoff }, "ws reconnect scheduled")
+    const delay = Math.max(minFloor, Math.round(base + jitter))
+    this.backoff = Math.min(Math.max(this.backoff, minFloor) * 2, MAX_BACKOFF_MS)
+    this.logger?.info(
+      { delayMs: delay, nextBaseMs: this.backoff, after5xx: this.lastCloseWas5xx },
+      "ws reconnect scheduled"
+    )
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = null
       this.connect()