@cocorograph/hub-agent 0.6.86 → 0.6.88

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.6.86",
+  "version": "0.6.88",
   "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの tmux/pty を中継する。",
   "type": "module",
   "license": "UNLICENSED",

package/src/claude-md-sync.mjs

@@ -0,0 +1,356 @@
+/**
+ * Hub 正本 (Project.claude_md) と workspace ローカル CLAUDE.md の双方向同期。
+ *
+ * 方針: 双方向 last-write-wins + 履歴。
+ * - Hub 側更新 → 端末 pull（ローカルを `.bak.<ts>` 退避してから全文上書き）
+ * - 端末側更新 → Hub に PUT（Hub 側は履歴に直前版を積む。directly handled by backend）
+ * - 両方変化（衝突）→ 端末側を勝者にして Hub に PUT、Hub の取り込み内容は
+ *   `.bak.conflict.<ts>` に退避（後で人手マージできるよう保存）
+ * - どちらも変化なし → no-op
+ *
+ * 初回（メタファイル無し）:
+ * - ローカル CLAUDE.md が空 → pull（Hub の正本をそのまま受け取り）
+ * - ローカル非空 + Hub 非空 → 衝突扱い（端末側勝者）
+ * - ローカル非空 + Hub 空 → no-op（Hub に空を上書きしない、Stage 3 で初期化検討）
+ *
+ * 失敗時のポリシー: ローカル CLAUDE.md は触らない（warn ログ + skip）。
+ * session 起動を止めない（ensureClaudeMd と同じく best-effort）。
+ *
+ * 関連: backend Stage 1 / 1.5
+ *   GET /api/admin/project/claude-md-by-dir/?dir_name=...
+ *   PUT /api/admin/project/claude-md-by-dir/?dir_name=...  body: { claude_md }
+ */
+import fs from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import crypto from "node:crypto"
+
+const DEFAULT_HUB_API = "https://api.hub.cocorograph.com"
+const TOKEN_PATH = path.join(os.homedir(), ".claude", ".hub_token.json")
+const META_DIR = ".cockpit-sync"
+const META_FILE = "claude-md.json"
+const BAK_KEEP = 3 // 通常 .bak と衝突 .bak それぞれ直近 3 件まで保持
+
+async function readJsonOrNull(p) {
+  try {
+    const text = await fs.readFile(p, "utf-8")
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}
+
+async function loadAccessToken() {
+  const data = await readJsonOrNull(TOKEN_PATH)
+  return (data && typeof data.access === "string" && data.access) || null
+}
+
+function sha256(s) {
+  return crypto.createHash("sha256").update(s || "", "utf-8").digest("hex")
+}
+
+function nowIso() {
+  return new Date().toISOString()
+}
+
+function makeBakName(prefix) {
+  // ファイル名に使えるよう : を - に置換し、ミリ秒精度を保つ。
+  const ts = nowIso().replace(/[:.]/g, "-")
+  return `${prefix}.${ts}.bak`
+}
+
+/**
+ * Hub から claude-md-by-dir で正本を取得する。
+ *
+ * - 404 = 該当 Project 無し（Domain 型・local_dir 型 workspace）→ null
+ * - その他のエラー → null（warn ログ）
+ *
+ * @returns {Promise<null | {project_id, claude_md, claude_md_hash, claude_md_updated_at}>}
+ */
+async function fetchHubClaudeMd({ hubUrl, accessToken, dirName, fetchImpl, logger }) {
+  const f = fetchImpl || globalThis.fetch
+  if (!f) return null
+  const url =
+    `${hubUrl.replace(/\/+$/, "")}/api/admin/project/claude-md-by-dir/` +
+    `?dir_name=${encodeURIComponent(dirName)}`
+  try {
+    const res = await f(url, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    })
+    if (res.status === 404) return null
+    if (!res.ok) {
+      logger?.warn?.(
+        { dirName, status: res.status },
+        "fetchHubClaudeMd: non-OK response",
+      )
+      return null
+    }
+    return await res.json()
+  } catch (err) {
+    logger?.warn?.(
+      { dirName, err: err?.message || String(err) },
+      "fetchHubClaudeMd: request failed",
+    )
+    return null
+  }
+}
+
+/**
+ * Hub に PUT で本文を上書きする。Hub 側は履歴を積んでから保存する。
+ *
+ * @returns {Promise<boolean>} 成功なら true
+ */
+async function putHubClaudeMd({ hubUrl, accessToken, dirName, body, fetchImpl, logger }) {
+  const f = fetchImpl || globalThis.fetch
+  if (!f) return false
+  const url =
+    `${hubUrl.replace(/\/+$/, "")}/api/admin/project/claude-md-by-dir/` +
+    `?dir_name=${encodeURIComponent(dirName)}`
+  try {
+    const res = await f(url, {
+      method: "PUT",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ claude_md: body }),
+    })
+    if (!res.ok) {
+      logger?.warn?.(
+        { dirName, status: res.status },
+        "putHubClaudeMd: non-OK response",
+      )
+      return false
+    }
+    return true
+  } catch (err) {
+    logger?.warn?.(
+      { dirName, err: err?.message || String(err) },
+      "putHubClaudeMd: request failed",
+    )
+    return false
+  }
+}
+
+async function readLocalClaudeMd(targetDir) {
+  try {
+    return await fs.readFile(path.join(targetDir, "CLAUDE.md"), "utf-8")
+  } catch (err) {
+    if (err?.code === "ENOENT") return null
+    throw err
+  }
+}
+
+async function writeLocalClaudeMd(targetDir, body) {
+  await fs.writeFile(path.join(targetDir, "CLAUDE.md"), body, "utf-8")
+}
+
+async function readMeta(targetDir) {
+  const metaPath = path.join(targetDir, META_DIR, META_FILE)
+  return await readJsonOrNull(metaPath)
+}
+
+async function writeMeta(targetDir, meta) {
+  const metaDir = path.join(targetDir, META_DIR)
+  await fs.mkdir(metaDir, { recursive: true })
+  await fs.writeFile(
+    path.join(metaDir, META_FILE),
+    JSON.stringify(meta, null, 2),
+    "utf-8",
+  )
+}
+
+/**
+ * 既存ローカル CLAUDE.md を .cockpit-sync/CLAUDE.md.<prefix>.<ts>.bak に退避する。
+ * 同 prefix の .bak は新しい順に BAK_KEEP 件保持し、古いものから FIFO 削除する。
+ *
+ * @param {'normal'|'conflict'} kind バックアップ種別（命名 prefix）
+ */
+async function backupLocalClaudeMd(targetDir, body, kind) {
+  if (body == null) return
+  const metaDir = path.join(targetDir, META_DIR)
+  await fs.mkdir(metaDir, { recursive: true })
+  const prefix = kind === "conflict" ? "CLAUDE.md.conflict" : "CLAUDE.md"
+  const bakName = makeBakName(prefix)
+  await fs.writeFile(path.join(metaDir, bakName), body, "utf-8")
+  // 同 prefix の .bak を新しい順に BAK_KEEP 件まで残す。
+  const entries = await fs.readdir(metaDir).catch(() => [])
+  const sameKind = entries
+    .filter((n) => n.startsWith(`${prefix}.`) && n.endsWith(".bak"))
+    .sort() // 名前にタイムスタンプを含むので辞書順 ≒ 時系列順
+    .reverse() // 新しい順
+  const obsolete = sameKind.slice(BAK_KEEP)
+  await Promise.all(
+    obsolete.map((n) =>
+      fs.unlink(path.join(metaDir, n)).catch(() => {}),
+    ),
+  )
+}
+
+/**
+ * `<targetDir>` の CLAUDE.md を Hub 正本と同期する（双方向 last-write-wins）。
+ *
+ * @param {object} args
+ * @param {string} args.targetDir       絶対パス
+ * @param {string} args.dirName         workspace ディレクトリ名（Dxxxxx_... / Pxxxxx）
+ * @param {string} [args.hubUrl]        Hub API base
+ * @param {string} [args.accessToken]   省略時は ~/.claude/.hub_token.json から
+ * @param {object} [args.logger]
+ * @param {Function} [args.fetchImpl]   テスト注入用
+ * @returns {Promise<{ action: 'pull'|'push'|'conflict'|'noop'|'skipped', reason?: string }>}
+ */
+export async function syncClaudeMdWithHub({
+  targetDir,
+  dirName,
+  hubUrl,
+  accessToken,
+  logger,
+  fetchImpl,
+} = {}) {
+  if (!targetDir) throw new Error("syncClaudeMdWithHub requires targetDir")
+  if (!dirName) throw new Error("syncClaudeMdWithHub requires dirName")
+
+  const token =
+    accessToken === undefined ? await loadAccessToken() : accessToken || null
+  if (!token) {
+    logger?.info?.({ dirName }, "syncClaudeMdWithHub: no access token, skip")
+    return { action: "skipped", reason: "no-token" }
+  }
+  const url = hubUrl || DEFAULT_HUB_API
+
+  // 1) Hub の正本を取得
+  const hub = await fetchHubClaudeMd({
+    hubUrl: url,
+    accessToken: token,
+    dirName,
+    fetchImpl,
+    logger,
+  })
+  if (!hub) {
+    return { action: "skipped", reason: "hub-not-resolvable" }
+  }
+  const hubBody = hub.claude_md || ""
+  const hubHash = hub.claude_md_hash || "" // 空文字なら Project.save 未実行 = 空本文
+  const hubUpdatedAt = hub.claude_md_updated_at || null
+
+  // 2) ローカル CLAUDE.md を読み、現在 hash を計算
+  const localBody = await readLocalClaudeMd(targetDir)
+  const localCurrentHash = localBody == null ? null : sha256(localBody)
+
+  // 3) メタファイルを読み、前回 sync の状態を取得
+  const meta = await readMeta(targetDir)
+
+  // Hub が一度も保存されていない（空本文 + updated_at が null）プロジェクトは
+  // 「Hub UI で意図的に未設定にしている」運用（テナント標準 CLAUDE.md に任せる等）の
+  // 可能性がある。端末側に何か書いてあっても push せず noop に倒す。
+  // ユーザー確定方針: 「Hub の claude_md が空のプロジェクトは何もしない」。
+  const hubInitialized = !!hubUpdatedAt
+  if (!hubInitialized) {
+    return { action: "noop", reason: "hub-uninitialized" }
+  }
+
+  // 判定: hubChanged / localChanged を計算する。
+  // - hubChanged: Hub.updated_at が前回 sync 時より進んだ
+  //   updated_at が null（Project.save 未実行で初期空）の場合は変化なし扱い。
+  // - localChanged: 現在の localHash が前回 sync 時の hash と異なる（=端末で編集）
+  //   meta が無くてローカル非空なら、初回参加時のローカル変更扱い（衝突候補）。
+  let hubChanged, localChanged
+  if (!meta) {
+    // 初回 sync。
+    hubChanged = !!hubBody
+    if (localBody == null) {
+      localChanged = false
+    } else {
+      localChanged = !!localBody // 非空なら端末側に何かある＝衝突候補
+    }
+  } else {
+    hubChanged = !!hubUpdatedAt && hubUpdatedAt !== meta.lastSyncedHubUpdatedAt
+    localChanged =
+      localCurrentHash != null && localCurrentHash !== meta.lastSyncedHash
+  }
+
+  // 同じ内容で書き込まれている（hash 一致）なら衝突扱いせず noop に降格。
+  if (hubChanged && localChanged && hubHash && hubHash === localCurrentHash) {
+    hubChanged = false
+    localChanged = false
+  }
+
+  // 4) アクション決定
+  if (!hubChanged && !localChanged) {
+    return { action: "noop" }
+  }
+
+  if (hubChanged && !localChanged) {
+    // pull: ローカルを .bak 退避 → Hub の本文で上書き
+    await backupLocalClaudeMd(targetDir, localBody, "normal")
+    await writeLocalClaudeMd(targetDir, hubBody)
+    await writeMeta(targetDir, {
+      lastSyncedHubUpdatedAt: hubUpdatedAt,
+      lastSyncedHash: hubHash || sha256(hubBody),
+      lastSyncedAt: nowIso(),
+    })
+    logger?.info?.({ dirName }, "syncClaudeMdWithHub: pull")
+    return { action: "pull" }
+  }
+
+  if (!hubChanged && localChanged) {
+    // push: Hub に PUT。成功時にメタ更新。
+    const ok = await putHubClaudeMd({
+      hubUrl: url,
+      accessToken: token,
+      dirName,
+      body: localBody || "",
+      fetchImpl,
+      logger,
+    })
+    if (!ok) {
+      return { action: "skipped", reason: "hub-put-failed" }
+    }
+    await writeMeta(targetDir, {
+      // PUT 後の Hub.updated_at は再度 GET しないと厳密には取れないため、
+      // 「ローカル hash と Hub.updated_at は別途次回 sync で再同期」する設計。
+      // ここでは「今 push したぶんは Hub に反映済み」として、現在のローカル
+      // hash と「今の時刻」をメタに記録する（次回 sync 時に再判定可能）。
+      lastSyncedHubUpdatedAt: nowIso(),
+      lastSyncedHash: localCurrentHash,
+      lastSyncedAt: nowIso(),
+    })
+    logger?.info?.({ dirName }, "syncClaudeMdWithHub: push")
+    return { action: "push" }
+  }
+
+  // hubChanged && localChanged → 衝突。端末側を勝者にして Hub に PUT。
+  // Hub の取り込み内容は .bak.conflict に退避（後で人手マージできるよう）。
+  await backupLocalClaudeMd(targetDir, hubBody, "conflict")
+  const ok = await putHubClaudeMd({
+    hubUrl: url,
+    accessToken: token,
+    dirName,
+    body: localBody || "",
+    fetchImpl,
+    logger,
+  })
+  if (!ok) {
+    // PUT 失敗時はメタを更新しない（次回再試行）。ローカルは無傷。
+    return { action: "skipped", reason: "hub-put-failed-in-conflict" }
+  }
+  await writeMeta(targetDir, {
+    lastSyncedHubUpdatedAt: nowIso(),
+    lastSyncedHash: localCurrentHash,
+    lastSyncedAt: nowIso(),
+  })
+  logger?.warn?.(
+    { dirName },
+    "syncClaudeMdWithHub: conflict (terminal wins); hub body saved to .bak.conflict",
+  )
+  return { action: "conflict" }
+}
+
+// 内部テスト用エクスポート
+export const _internals = {
+  sha256,
+  readMeta,
+  writeMeta,
+  backupLocalClaudeMd,
+  BAK_KEEP,
+}

package/src/main.mjs

@@ -1137,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 {
@@ -1203,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

@@ -86,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 分)
      * 未満なので無傷。何時間も放置された孤児だけ掃除される。
      *
@@ -382,6 +384,16 @@ export class PtyBridge extends EventEmitter {
       this.coalesceState.set(stream_id, state)
       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(() => {
@@ -397,6 +409,8 @@ export class PtyBridge extends EventEmitter {
     } else {
       disposables.push(
         pty.onData((data) => {
+          // 出力でも touch (A-4 修正)。理由は上の coalesce 経路のコメント参照。
+          this._touch(stream_id)
           this.emit("output", { stream_id, data })
         }),
       )

package/src/tmux.mjs

@@ -20,6 +20,7 @@ import path from "node:path"
 import { promisify } from "node:util"
 
 import { ensureClaudeMd } from "./claude-md.mjs"
+import { syncClaudeMdWithHub } from "./claude-md-sync.mjs"
 import {
   capturePane,
   detectInputBoxText,
@@ -657,14 +658,22 @@ export async function createSession(name, cwd, opts = {}) {
       throw new Error(`cwd stat failed: ${err?.message || String(err)}`)
     }
   }
-  // HUB_PROJECTS_BASE 配下の workspace の場合は CLAUDE.md を必要なら生成する。
-  // Hub director があれば frontmatter 連動の構造化版、無ければ最小プレースホルダ。
-  // 既存 CLAUDE.md は触らない。失敗しても session 起動自体は止めない (warn のみ)。
+  // HUB_PROJECTS_BASE 配下の workspace の場合は CLAUDE.md を必要なら生成し、
+  // Hub の正本（Project.claude_md）と双方向同期する。
+  // - ensureClaudeMd: 既存 CLAUDE.md は触らない。無ければ director frontmatter
+  //   または placeholder を生成する。
+  // - syncClaudeMdWithHub: Hub 正本と双方向 last-write-wins 同期。Hub 側更新は
+  //   ローカルへ pull（.bak 退避してから上書き）、端末側更新は Hub へ push、
+  //   両方変化は端末側を勝者にして Hub へ push（Hub の取り込み内容は
+  //   .bak.conflict に退避）。Hub が一度も保存されていないプロジェクトでは
+  //   何もしない（テナント標準 CLAUDE.md の運用を尊重する）。
+  // どちらも失敗しても session 起動自体は止めない (warn のみ)。
   if (isUnderHubProjectsBase(resolvedCwd)) {
+    const dirName = path.basename(resolvedCwd)
     try {
       await ensureClaudeMd({
         targetDir: resolvedCwd,
-        dirName: path.basename(resolvedCwd),
+        dirName,
         hubUrl: opts.hubUrl,
         accessToken: opts.hubAccessToken,
         logger: opts.logger,
@@ -676,6 +685,25 @@ export async function createSession(name, cwd, opts = {}) {
         "ensureClaudeMd failed (workspace dir is usable, but no CLAUDE.md)",
       )
     }
+    try {
+      const syncResult = await syncClaudeMdWithHub({
+        targetDir: resolvedCwd,
+        dirName,
+        hubUrl: opts.hubUrl,
+        accessToken: opts.hubAccessToken,
+        logger: opts.logger,
+        fetchImpl: opts.fetchImpl,
+      })
+      opts.logger?.debug?.(
+        { session: name, dirName, sync: syncResult },
+        "syncClaudeMdWithHub completed",
+      )
+    } catch (err) {
+      opts.logger?.warn?.(
+        { session: name, cwd: resolvedCwd, err: err?.message || String(err) },
+        "syncClaudeMdWithHub failed (session starts anyway)",
+      )
+    }
   }
   // 既存チェック
   try {

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