@cocorograph/hub-agent 0.8.21 → 0.8.22

package/src/hub-request-deadline.mjs

@@ -0,0 +1,273 @@
+/**
+ * Hub API 呼び出しの期限（1 往復ごと）と、セッション起動あたりの全体予算。
+ *
+ * ⚠️ ここが保証するのは次の 3 つ **だけ**。これを超える断定（「同期全体が N 秒以内」
+ * 「セッション起動が必ず N 秒で終わる」等）を書かないこと:
+ *   1. 各 HTTP 往復（headers 受信 〜 body 消費）は `HUB_REQUEST_TIMEOUT_MS` で打ち切る
+ *   2. `ensureClaudeMd` + `syncClaudeMdWithHub` は、**予算の生成時から数えた経過時間**が
+ *      `SESSION_BUDGET_MS` を超えたら打ち切る（セッション起動あたり 1 本の予算）
+ *   3. 予算は **wall-clock の期限**であり、通信の待ち時間を積み上げた総量ではない。
+ *      ファイル I/O・レンダリング・イベントループの停止も残量を減らす。ただし
+ *      **打ち切る対象は Hub 往復と、その後に続く同期の処理**であって、それ以外の
+ *      処理を中断はしない
+ *
+ * ⚠️ 3 を「通信の待ち時間だけを積算する」実装に変えないこと。director と
+ * repositories は 1 本の deadline を共有して**並列**に待つので待ち時間が二重計上され、
+ * かつ CPU が詰まっている間・スリープ中は残量が減らないので **上限が事実上無制限**に
+ * なる。wall-clock 上限のままにしておくことが「セッション起動を有限にする」の根拠。
+ *
+ * `src/claude-md.mjs`（初期化）と `src/claude-md-sync.mjs`（双方向同期）の両方から
+ * 使うため独立モジュールにしてある。**2 系統に複製しないこと**（片方だけ直して
+ * ドリフトする）。
+ */
+
+/**
+ * Hub API **1 往復あたり**（headers 受信 〜 body 消費）に掛ける既定の期限 (ms)。
+ *
+ * 15 秒とした根拠: 短くしたい誘惑があるが、低速回線・スリープ復帰直後の**正常な**
+ * 往復を恒常的に失敗させる方が害が大きい（同期が毎回諦めると正本がドリフトし続ける）。
+ * 健全な回線での往復は 1 秒程度で完了するので、15 秒は「遅いが正常」を通しつつ
+ * 「返ってこない」を切るための余裕として置いている。
+ * ⚠️ **本文サイズを根拠に書かないこと。** CLAUDE.md 正本の大きさは案件ごとに違い、
+ * 運用のなかで増減する。具体値を書くと必ず陳腐化する（旧コメントに残っていた
+ * 「往復は本文が小さいから速い」という断定は、実データの正本サイズと矛盾していた）。
+ * ⚠️ 導入前は **無制限**（body を閉じないレスポンスで往復が永久に返らない）だった。
+ */
+export const HUB_REQUEST_TIMEOUT_MS = 15_000
+
+/**
+ * セッション起動 1 回あたりの **wall-clock 予算** (ms)。予算の生成時から数えた
+ * 残り時間で、通信の待ち時間を積み上げた総量ではない。
+ *
+ * 1 往復に期限があっても、初期化と同期は **複数往復**を行うため、その本数だけ
+ * 足し算されて `createSession` が止まる時間の上限が決まらない。そこで「起動 1 回で
+ * 使ってよい wall-clock」をここで決め、超えたら **何も書かずに次回へ持ち越す**
+ * （不確定な状態で fallback 本文を書かない）。
+ * ⚠️ 打ち切る対象は **Hub 往復と、それに続く同期の処理**だけ。ファイル I/O・CPU 待ち・
+ * スリープも残量を減らすが、それらを直接中断はしない（「セッション起動全体が N 秒
+ * 以内」を保証するものではない。このモジュール冒頭の 3 が正本）。
+ * ⚠️ 往復の本数を具体的に列挙しないこと。経路が増減するたびにコメントだけが
+ * 古くなり、実在しない往復を数え続ける（過去に実際そうなった）。
+ */
+export const SESSION_BUDGET_MS = 30_000
+
+/**
+ * 1 往復ぶんの期限とキャンセル手段をまとめたもの。
+ *
+ * ⚠️ `Promise.race` だけでは**負けた側（`fetch` / `res.json()` / body 読み）が裏で
+ * 走り続ける**ため、期限超過時は必ず `AbortController.abort()`（+ 呼び出し側での
+ * `reader.cancel()`）を行い、正常終了時は `clear()` でタイマーを解除すること。
+ * タイマーは `unref()` して、これだけでプロセスが生き残らないようにする。
+ *
+ * @param {number} ms 期限。**0 以下なら生成時点で期限切れ**（＝ `guard` は即
+ *   `{timedOut:true}`）。予算を使い切った後に「まだ少し待てる」と誤認しないため。
+ * @param {object} [opts]
+ * @param {AbortSignal} [opts.parentSignal] 親（＝セッション全体予算）の signal。
+ *   親が abort したら子も abort し、`guard` を待っている呼び出しも解ける。
+ */
+export function createDeadline(ms, { parentSignal = null } = {}) {
+  const controller = new AbortController()
+  let fire = null
+  const expiredPromise = new Promise((resolve) => {
+    fire = resolve
+  })
+  let fired = false
+  const expire = () => {
+    if (fired) return
+    fired = true
+    try {
+      controller.abort()
+    } catch {
+      /* noop */
+    }
+    fire()
+  }
+
+  // ⚠️ `AbortSignal.any` は Node 20.3+。engines は ">=20" なので **存在確認してから**
+  // 使い、無い環境では親 signal のリスナーで子 controller を abort する。
+  const hasAbortSignalAny = typeof AbortSignal !== "undefined" && typeof AbortSignal.any === "function"
+  let signal = controller.signal
+  let detachParent = () => {}
+  if (parentSignal) {
+    if (hasAbortSignalAny) {
+      // 合成 signal を fetch に渡す（親・子どちらの abort でも中断される）。
+      try {
+        signal = AbortSignal.any([controller.signal, parentSignal])
+      } catch {
+        signal = controller.signal
+      }
+    }
+    if (parentSignal.aborted) {
+      // 親が既に切れている＝残り 0。生成時点で期限切れにする。
+      if (!hasAbortSignalAny) expire()
+      else {
+        fired = true
+        fire()
+      }
+    } else if (typeof parentSignal.addEventListener === "function") {
+      const onParentAbort = () => {
+        // any が使える環境では合成 signal 側が既に abort 済みなので、ここでは
+        // 「待っている guard を解く」ことだけを行えばよい。使えない環境では
+        // 子 controller を abort して signal を伝播させる。
+        if (hasAbortSignalAny) {
+          if (!fired) {
+            fired = true
+            fire()
+          }
+        } else {
+          expire()
+        }
+      }
+      parentSignal.addEventListener("abort", onParentAbort, { once: true })
+      detachParent = () => {
+        try {
+          parentSignal.removeEventListener("abort", onParentAbort)
+        } catch {
+          /* noop */
+        }
+      }
+    }
+  }
+
+  let timer = null
+  if (ms > 0) {
+    timer = setTimeout(expire, ms)
+    if (typeof timer.unref === "function") timer.unref()
+  } else {
+    // 0 以下 = 生成時点で期限切れ。タイマーを 1 tick 待たせない。
+    expire()
+  }
+
+  return {
+    get signal() {
+      return signal
+    },
+    /** 期限切れ済みか（`clear()` 後も状態は変わらない）。 */
+    expired() {
+      return fired
+    },
+    abort() {
+      try {
+        controller.abort()
+      } catch {
+        /* noop */
+      }
+    },
+    clear() {
+      if (timer) clearTimeout(timer)
+      detachParent()
+    },
+    /**
+     * `promise` を期限付きで待つ。
+     * @returns {Promise<{timedOut: boolean, value?: any, error?: any}>}
+     *   期限超過なら `{timedOut:true}`。負けた promise には必ずハンドラを付けて
+     *   unhandled rejection にしない。
+     */
+    async guard(promise) {
+      return await Promise.race([
+        promise.then(
+          (value) => ({ timedOut: false, value }),
+          (error) => ({ timedOut: false, error }),
+        ),
+        expiredPromise.then(() => ({ timedOut: true })),
+      ])
+    },
+  }
+}
+
+/**
+ * セッション起動 1 回ぶんの **全体予算**（生成時からの wall-clock 期限）。
+ *
+ * ⚠️ 「通信の待ち時間の累積」ではない。`createSessionBudget(20)` を作って HTTP を
+ * 一度も呼ばずに 20ms 超待つと `expired()` は `true` になる。ファイル I/O・呼び出し元の
+ * 処理時間も残量を減らす（このモジュール冒頭の 3 を参照）。
+ *
+ * 使い方（呼び出し元は 1 本だけ作り、`finally` で必ず `clear()` する）:
+ *   const budget = createSessionBudget()
+ *   try { await ensureClaudeMd({ ..., budget }); await syncClaudeMdWithHub({ ..., budget }) }
+ *   finally { budget.clear() }
+ *
+ * 予算が尽きたら **書き込みを行わずに諦める**（`ensureClaudeMd` は `deferred`、
+ * `syncClaudeMdWithHub` は `skipped`）。どちらもセッション起動は止めない。
+ */
+export function createSessionBudget(ms = SESSION_BUDGET_MS) {
+  const controller = new AbortController()
+  const budgetMs = Math.max(0, ms)
+  const deadlineAt = Date.now() + budgetMs
+  const children = new Set()
+
+  const abortAll = () => {
+    try {
+      controller.abort()
+    } catch {
+      /* noop */
+    }
+  }
+  let timer = null
+  if (budgetMs > 0) {
+    timer = setTimeout(abortAll, budgetMs)
+    if (typeof timer.unref === "function") timer.unref()
+  } else {
+    abortAll()
+  }
+
+  const remainingMs = () => Math.max(0, deadlineAt - Date.now())
+  const expired = () => controller.signal.aborted || remainingMs() <= 0
+
+  return {
+    signal: controller.signal,
+    remainingMs,
+    expired,
+    /**
+     * 1 往復ぶんの子 deadline を作る。期限は「1 往復の上限」と「予算の残り」の小さい方。
+     * 残りが 0 なら **生成時点で期限切れ** の子を返す（待たせない）。
+     */
+    childDeadline(perRequestMs = HUB_REQUEST_TIMEOUT_MS) {
+      const remaining = remainingMs()
+      const child = createDeadline(
+        expired() ? 0 : Math.min(perRequestMs, remaining),
+        { parentSignal: controller.signal },
+      )
+      children.add(child)
+      return child
+    },
+    /**
+     * 予算の後片付け。
+     *
+     * ⚠️ **子 deadline を abort してから** タイマーを外すこと。`clear()` は
+     * タイマーとリスナーを外すだけで signal を abort しないため、先に clear だけ
+     * すると「非 OK で早期 return したが body を閉じない応答」のように、まだ
+     * 生きているソケットを解放する手段が誰にも残らない（実測で、`ensureClaudeMd`
+     * が返った後も 3 本のソケットが接続中のままになった）。
+     *
+     * 呼び出し元（`src/tmux.mjs`）は初期化と同期の await が両方終わった後の
+     * `finally` で呼ぶので、ここで abort しても正常な往復は殺さない。
+     */
+    clear() {
+      if (timer) clearTimeout(timer)
+      for (const child of children) {
+        try {
+          child.abort()
+        } catch {
+          /* noop */
+        }
+        try {
+          child.clear()
+        } catch {
+          /* noop */
+        }
+      }
+      children.clear()
+    },
+  }
+}
+
+/**
+ * budget があれば子 deadline を、無ければ単独 deadline を作る。
+ *
+ * 「budget 省略時も従来どおり 1 往復の期限だけは掛かる」を 1 箇所に集約する
+ * （呼び出し側に三項演算子を散らすと、片方だけ budget を渡し忘れる）。
+ */
+export function acquireDeadline(budget, perRequestMs = HUB_REQUEST_TIMEOUT_MS) {
+  return budget ? budget.childDeadline(perRequestMs) : createDeadline(perRequestMs)
+}

package/src/tmux.mjs

@@ -22,6 +22,7 @@ import { promisify } from "node:util"
 
 import { ensureClaudeMd } from "./claude-md.mjs"
 import { syncClaudeMdWithHub } from "./claude-md-sync.mjs"
+import { createSessionBudget } from "./hub-request-deadline.mjs"
 import { detectSessionState, getSessionCwd } from "./state.mjs"
 import { shouldLaunchPaneCli } from "./pane-cli-flag.mjs"
 import { baseSessionName, sessionNameFor } from "./session-names.mjs"
@@ -836,45 +837,65 @@ export async function createSession(name, cwd, opts = {}) {
   //   .bak.conflict に退避）。Hub が一度も保存されていないプロジェクトでは
   //   何もしない（テナント標準 CLAUDE.md の運用を尊重する）。
   // どちらも失敗しても session 起動自体は止めない (warn のみ)。
+  // ⚠️ 2 つの呼び出しで **1 本の budget を共有**する。1 往復ごとの期限だけでは
+  //   往復の本数ぶん足し算されてセッション起動が長時間止まりうるため、Hub 処理に
+  //   割り当てた wall-clock 予算（予算の生成時からの経過時間で、通信の待ち時間の
+  //   累積ではない）で全体を打ち切る。予算切れなら「何も書かずに次回へ持ち越す」。
   if (isUnderHubProjectsBase(resolvedCwd)) {
     const instructionDir = projectInstructionDir(resolvedCwd)
     const dirName = path.basename(instructionDir)
     const configFilename = opts.cliKind === "codex" ? "AGENTS.md" : "CLAUDE.md"
+    const budget = createSessionBudget()
+    // ⚠️ `ensureClaudeMd` の戻り値を捨てない。`source === 'existing'` は
+    // 「このセッションより前からローカルにファイルがあった」＝ **初回登録**
+    // （Hub に無くローカルにあるものを 1 度だけ Hub へ取り込む）の唯一の根拠で、
+    // ディスクに残さずここから同期へ手渡す。例外時は **undefined のまま渡さない**
+    // （＝登録しない。何が起きたか分からない回に Hub を触らせない安全側）。
+    let localFilePreexisted
     try {
-      await ensureClaudeMd({
-        targetDir: instructionDir,
-        dirName,
-        hubUrl: opts.hubUrl,
-        accessToken: opts.hubAccessToken,
-        logger: opts.logger,
-        fetchImpl: opts.fetchImpl,
-        configFilename,
-      })
-    } catch (err) {
-      opts.logger?.warn?.(
-        { session: name, cwd: resolvedCwd, err: err?.message || String(err) },
-        "ensureClaudeMd failed (workspace dir is usable, but no CLAUDE.md)",
-      )
-    }
-    try {
-      const syncResult = await syncClaudeMdWithHub({
-        targetDir: instructionDir,
-        dirName,
-        hubUrl: opts.hubUrl,
-        accessToken: opts.hubAccessToken,
-        logger: opts.logger,
-        fetchImpl: opts.fetchImpl,
-        configFilename,
-      })
-      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 {
+        const ensure = await ensureClaudeMd({
+          targetDir: instructionDir,
+          dirName,
+          hubUrl: opts.hubUrl,
+          accessToken: opts.hubAccessToken,
+          logger: opts.logger,
+          fetchImpl: opts.fetchImpl,
+          configFilename,
+          budget,
+        })
+        localFilePreexisted = ensure?.source === "existing"
+      } catch (err) {
+        opts.logger?.warn?.(
+          { session: name, cwd: resolvedCwd, err: err?.message || String(err) },
+          "ensureClaudeMd failed (workspace dir is usable, but no CLAUDE.md)",
+        )
+      }
+      try {
+        const syncResult = await syncClaudeMdWithHub({
+          targetDir: instructionDir,
+          dirName,
+          hubUrl: opts.hubUrl,
+          accessToken: opts.hubAccessToken,
+          logger: opts.logger,
+          fetchImpl: opts.fetchImpl,
+          configFilename,
+          budget,
+          // undefined のときはキーごと渡さない（呼び出し側の意図を明示する）。
+          ...(localFilePreexisted === undefined ? {} : { localFilePreexisted }),
+        })
+        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)",
+        )
+      }
+    } finally {
+      budget.clear()
     }
   }
   // 既存チェック