@cocorograph/hub-agent 0.8.21 → 0.8.23

package/src/codex-stream-bridge.mjs

@@ -1900,22 +1900,14 @@ export class CodexStreamBridge extends EventEmitter {
    *   busy: boolean, detached: boolean, idle_ms: number}>}
    */
   describeLiveSessions(cwd) {
-    const now = Date.now()
     const out = []
     // 案B: sessions は多対一なので distinct session で走査する（購読端末数ぶん重複させない）。
+    // ⚠️ 記述子の組み立ては **_describe に一本化** する（claude 版が describeLiveSessions →
+    // _describeCandidate へ寄せているのと同じ構造）。ここで別に組み立てると、片方だけ直した
+    // ときに「一覧に出るフィールド」と「配送結果・候補一覧に出るフィールド」が無言でずれる。
     for (const session of this._liveSessions()) {
       if (cwd && session.cwd !== cwd) continue
-      out.push({
-        kind: "codex",
-        cwd: session.cwd,
-        stream_id: session.stream_id,
-        thread_id: session.threadId || null,
-        busy: !!session.activeTurnId,
-        detached: !!session.detachRequested,
-        // idle_ms は「新しさ」の指標（一覧の並び・宛先選定に使う）なので、閲覧 keepalive で
-        // 動く lastActivityMs ではなく **会話ターン境界時刻 lastTurnAtMs** を基準にする。
-        idle_ms: now - (session.lastTurnAtMs ?? session.lastActivityMs ?? now),
-      })
+      out.push(this._describe(session))
     }
     return out
   }
@@ -1923,7 +1915,9 @@ export class CodexStreamBridge extends EventEmitter {
   /**
    * 指定 cwd の「権威セッション」を返す（T06407 増分2, axis2 の単一正本）。同一 cwd に複数
    * ライブ codex セッションがあるとき、**最終活性が最新のもの**（＝いまユーザーが使っている
-   * 会話）を選ぶ。sendToCwd の宛先選定と同じ規則に揃える。
+   * 会話）を選ぶ。⚠️ 表示系（context% の収束）専用の規則であり、**配送（sendToCwd）はこの
+   * 推測を使わない**（曖昧なら配送せず ambiguous を返す）。誤った表示は次 tick で直るが、
+   * 誤配送は取り返しがつかないため、両者の判定を意図的に分けてある。
    *
    * ⚠️ context%（ドーナツ）は thread 固有の値なので「どのセッションから読んでも同じ」という
    * 旧 rate-limit 前提（先着 1 件で十分）は成り立たない。state loop（threadIdForCwd 経由）と
@@ -1975,19 +1969,15 @@ export class CodexStreamBridge extends EventEmitter {
    * 指定 cwd でライブなセッションへメッセージを直接注入する (sibling-inject 用、
    * 2026-07-04)。Claude 版 `sendToCwd` の対。
    *
-   * ⚠️ 同一 cwd に複数ライブセッションがあるとき (ブラウザの WS 再接続ごとに新しい
-   * stream_id でセッションが増えるため頻繁に起きる) は **最終活性が最新のもの** を
-   * 選ぶ。旧実装は Map の挿入順 = 最古を選んでいたため、ブラウザが既に居ない
-   * ゾンビセッションへ注入して「ok なのに画面に出ない」事故が起きた (2026-07-17)。
-   * claude-stream-bridge.mjs の同名メソッドと同じ選択規則に揃えてある。
+   * ⚠️ 宛先解決: 候補を **attached (前面=detach 未要求) 優先** の層に分け、層内が 1 本のときだけ
+   * 配送する。層内が 2 本以上なら推測せず `{status:"ambiguous", candidates}` を返して配送しない
+   * (fail-safe)。claude-stream-bridge.mjs の同名メソッドと同じ判定規則である。
    *
    * ⚠️ このメソッド自体は認証を行わない (呼び出し元の sibling-inject.mjs が
    * src/sibling-token.mjs の capability トークンで入力元を検証する前提)。
    *
    * ⚠️ 返り値 (2026-07-23, 統一再設計 1-1): claude 版と契約を揃えるため boolean から status
-   * オブジェクトへ変更した。codex は計数(describeLiveSessions)と配送が同一集合 (_liveSessions())
-   * を見るため claude のような undercount 由来のサイレント誤配送は構造的に起きず、宛先選定は
-   * 従来どおり「会話ターン境界時刻が最新」のヒューリスティックを維持する (挙動不変)。
+   * オブジェクトへ変更した。
    *
    * @param {string} cwd
    * @param {string} text
@@ -1995,6 +1985,7 @@ export class CodexStreamBridge extends EventEmitter {
    *   {status:"delivered", session:object, delivery_id:string, accepted_via:string}
    *   | {status:"delivery_unconfirmed", session:object, delivery_id:string, accepted_via:string, reason:string}
    *   | {status:"delivery_failed", session:object, delivery_id:string, reason:string}
+   *   | {status:"ambiguous", candidates:object[]}
    *   | {status:"not_found"}
    * >}
    */
@@ -2005,27 +1996,30 @@ export class CodexStreamBridge extends EventEmitter {
     // attached (前面=detach 未要求) 優先 (2026-07-23 統一再設計 1-1, cross-review 指摘4):
     // detach 済み warm セッションが lastTurnAtMs 上たまたま新しくても、attached な現行セッションが
     // あればそちらへ配送する (browser を離れた/畳まれかけの旧会話 ghost への誤配送を防ぐ)。
-    // claude と違い codex は同一 cwd に複数 attached が併存し得る (別スレッドの新会話 / ターン
-    // 実行中) ため fail-safe ambiguous にはせず、tier 内は会話ターン境界時刻が最新のものを選ぶ
-    // (閲覧 keepalive で動く lastActivityMs は使わない = 見ているだけの古い会話が本命を追い越さない)。
     const attached = cands.filter((s) => !s.detachRequested)
     const tier = attached.length ? attached : cands
-    let best = null
-    let bestAt = -1
-    for (const session of tier) {
-      const at = session.lastTurnAtMs ?? session.lastActivityMs ?? 0
-      if (at >= bestAt) {
-        bestAt = at
-        best = session
-      }
-    }
-    if (!best) {
+    if (!tier.length) {
       this.logger?.warn?.(
         { cwd, live_sessions: this.describeLiveSessions() },
         "codex sendToCwd: no live session for cwd (ask-sibling will fail)",
       )
       return { status: "not_found" }
     }
+    // 層内が 2 本以上なら **推測せず配送しない** (fail-safe。claude 版 sendToCwd と同じ判定):
+    // 旧実装は tier 内で「会話ターン境界時刻 lastTurnAtMs が最新のもの」を選んでいたが、これは
+    // 「同一 cwd の live は実質 1 本 (2 本目は transient)」という前提の上に成り立つ推測だった。
+    // 同一 cwd に複数 live を常態として許す方針へ変わった以上、この推測は誤配送の温床になる
+    // (別スレッドの新会話へ配ってしまう / 見た目は ok なのに本命の画面には出ない)。曖昧なときは
+    // 候補を返して呼び出し側に stream_id / thread_id で名指しさせる (sendToStream)。
+    if (tier.length > 1) {
+      const candidates = tier.map((s) => this._describe(s))
+      this.logger?.warn?.(
+        { cwd, candidates },
+        "codex sendToCwd: ambiguous target (multiple live sessions for cwd; not delivering)",
+      )
+      return { status: "ambiguous", candidates }
+    }
+    const best = tier[0]
     // detach 済み warm セッションでも、ask-sibling が使うなら「新しい持ち主が付いた」とみなして
     // detachRequested を解除し touch する（LRU 先頭へ）。this.input が改めて _touch するが、注入前に
     // 明示しておく。ターン実行中は healthy busy = protected なので reconcile で kill されない。
@@ -2033,17 +2027,16 @@ export class CodexStreamBridge extends EventEmitter {
     this._touch(best)
     return this._deliverInjection(best, text, source, {
       cwd,
-      selection: "most-recently-active",
+      selection: "sole-candidate",
       candidates: this.describeLiveSessions(cwd).length,
     })
   }
 
   /**
    * 指定した id (stream_id もしくは thread_id) のライブセッションへ直接注入する
-   * (sibling-inject の **明示宛先指定** 用、2026-07-19 / T06271)。sendToCwd は cwd 内で
-   * 最終活性が最新のものを選ぶヒューリスティックのため、同一 cwd に複数の生きた codex
-   * セッションが同居すると誤爆する。呼び出し側が describeLiveSessions で得た id を明示
-   * すれば曖昧さを回避できる。
+   * (sibling-inject の **明示宛先指定** 用、2026-07-19 / T06271)。sendToCwd は同一 cwd に
+   * 複数の生きた codex セッションが同居すると (推測配送せず) ambiguous を返して止まる。
+   * 呼び出し側が describeLiveSessions で得た id を明示すれば、その曖昧さを解消して配送できる。
    *
    * stream_id は WS 再接続 / in-memory reattach で付け替わる (不安定) 一方、thread_id は
    * 会話に固定 (安定) なので、**両方を受け付け** どちらで指定しても解決できるようにする。
@@ -2257,14 +2250,30 @@ export class CodexStreamBridge extends EventEmitter {
     }
   }
 
-  /** describeLiveSessions と同形の 1 セッション記述子 (sendToStream の結果整形に共用)。 */
+  /**
+   * セッション記述子の **単一定義** (describeLiveSessions / sendToCwd / sendToStream の
+   * 結果整形が全てここを通る)。claude 版 `_describeCandidate` の対。
+   *
+   * ⚠️ なぜ 1 箇所に集約するか (2026-08-02): 同じ「セッションの記述子」が describeLiveSessions と
+   * _describe の 2 か所で別々に定義されていると、片方だけ直したときに無言でずれる。実際
+   * `detached` / `idle_ms` は一覧側にしか無く、sendToCwd の ambiguous 候補一覧 (= 利用者が
+   * 宛先を選ぶために読むもの) には落ちていなかった。`idle_ms` は「どれが最近動いた会話か」を
+   * 示す唯一の手がかりなので、候補一覧に無いと利用者は宛先を選べない。
+   *
+   * `idle_ms` は「新しさ」の指標（一覧の並び・宛先選定に使う）なので、閲覧 keepalive で動く
+   * lastActivityMs ではなく **会話ターン境界時刻 lastTurnAtMs** を基準にする（見ているだけの
+   * 古い会話が本命を追い越さないように）。
+   */
   _describe(session) {
+    const now = Date.now()
     return {
       kind: "codex",
       cwd: session.cwd,
       stream_id: session.stream_id,
       thread_id: session.threadId || null,
       busy: !!session.activeTurnId,
+      detached: !!session.detachRequested,
+      idle_ms: now - (session.lastTurnAtMs ?? session.lastActivityMs ?? now),
     }
   }
 

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/sibling-inject.mjs

@@ -33,7 +33,20 @@
  *   - 全一覧: `{op:"list-all", token}` → `{ok, live_sessions}` (全 cwd・両 CLI。クロス cwd
  *       宛先探索用、2026-07-23。cwd/target_cli_kind 不要、token のみ必須)。
  * 処理後は必ず削除し (成否問わず)、呼び出し側が待ち受けられるよう
- * `<request_id>.result.json` = `{ok, error?, delivered_to?, candidates?, live_sessions?, hint?}` を書く。
+ * `<request_id>.result.json` = `{ok, error?, delivered_to?, candidates?, live_sessions?, hint?,
+ * candidates_nameable?}` を書く (`candidates_nameable` は曖昧系エラーのときのみ。CLI が
+ * 「候補を実行可能な `--to` として並べてよいか」を hint の文言に依存せず判定するための boolean)。
+ *
+ * ⚠️ 曖昧系のエラーコードは 2 つある (2026-08-02 クロスレビュー round2 major):
+ *   - `ambiguous_target`            … 候補を `--to` で名指しできる (解消手段がある)
+ *   - `ambiguous_target_unnameable` … 名指しでは解消できない (session_id 未確定 / resume 競合)
+ * 分けている理由は **版ずれが片方向にしか効かない**のを塞ぐため。`candidates_nameable` を足す
+ * だけだと、**新しい hub-agent × 旧 CLI** の組み合わせで旧 CLI が boolean を無視し、従来の
+ * `ambiguous_target` 分岐に入って**無効な `--to` を並べる** (同一 session_id の候補 2 件に対し
+ * 同じアドレスを 2 回案内する。旧 CLI 実物へ新応答を渡して再現済み)。エラーコードを変えると
+ * 旧 CLI は未知エラーとして generic 分岐へ落ち、`--to` を出さず診断 (hint / live_sessions) だけを
+ * 表示する (実測で確認済み)。`candidates_nameable` は新 CLI が両コードを共通処理するための
+ * 判断材料として **外部契約に残す**。
  */
 
 import { watch } from "node:fs"
@@ -52,6 +65,128 @@ const DELIVERY_UNCONFIRMED_HINT =
 const DELIVERY_FAILED_HINT =
   "turn RPC の受付前または受付中に失敗しました。対象セッションを確認して再送してください。"
 
+/** 曖昧だが `--to` で名指しして解消できる (候補を実行可能な宛先として案内してよい)。 */
+export const AMBIGUOUS_TARGET_ERROR = "ambiguous_target"
+/** 曖昧で、かつ `--to` では解消できない (名指ししても一意にならない)。 */
+export const AMBIGUOUS_TARGET_UNNAMEABLE_ERROR = "ambiguous_target_unnameable"
+
+/**
+ * claude の曖昧候補が `--to <session_id>` で名指しできるか、できないなら**なぜか** (2026-08-02)。
+ *
+ * 名指しできる条件は「**候補の session_id が全て非 null かつ相異なる**」こと。破れるのは 2 つで、
+ * **待てば解決するか否かが正反対**なので理由まで返す (2026-08-02 クロスレビュー round2 minor:
+ * 両方に「Cockpit で 1 本に整理」と案内していたため、待てば直る状況で不要な操作を誘発していた):
+ *   - `"unresolved"` (**null が混ざる**): `sendToCwd` は `_liveCandidatesForCwd(cwd, false)` で
+ *     候補を集めるため、session_id 未確定の fresh セッション (attach 直後〜SDK の system/init
+ *     到達前) が候補に入る。実測: `attach({cwd})` 直後の `describeLiveSessions` / `sendToCwd` の
+ *     候補は `session_id: null` を返す。null は宛先として書けないが、**初期化が終われば確定する**
+ *     ので「待って `--list` で再確認」が正しい案内。
+ *   - `"duplicate"` (**重複する**): 同一 session_id の別 session が併存する resume 競合
+ *     (`sendToStream` が ambiguous を返す状況)。id を書いても再び複数一致し、**待っても解決しない**
+ *     ので「1 本に整理してから再送」が正しい案内。
+ *
+ * ⚠️ 両方が同時に起きたら `"duplicate"` を優先する。待てば null は確定するが重複は残るため、
+ * 「待て」と案内すると手詰まりになる (保守的に整理へ倒す)。
+ * ⚠️ 理由は **hint の文面を決めるためだけ**に使い、外部契約 (`candidates_nameable`) は boolean の
+ * ままにする。CLI 側に原因判定を持ち込むと名指し可否の判定が 2 リポジトリへ二重化する。
+ *
+ * @param {object[]} [candidates] `{session_id}` を持つ候補記述子の配列
+ * @returns {"nameable"|"unresolved"|"duplicate"|"unknown"} `unknown` = 候補が空 (理由を特定できない)
+ */
+function claudeCandidatesNameability(candidates) {
+  if (!Array.isArray(candidates) || candidates.length === 0) return "unknown"
+  const seen = new Set()
+  let hasUnresolved = false
+  for (const c of candidates) {
+    const id = c?.session_id
+    if (!id) hasUnresolved = true // fresh (session_id 未確定) は宛先に書けない
+    else if (seen.has(id)) return "duplicate" // resume 競合は待っても解決しない (優先)
+    else seen.add(id)
+  }
+  return hasUnresolved ? "unresolved" : "nameable"
+}
+
+/**
+ * 曖昧エラーの **エラーコード・案内文・機械可読な判定を 1 回の呼び出しで一緒に返す** 単一定義。
+ *
+ * ⚠️ なぜ 1 箇所に集約するか (2026-08-02): 案内文は当初「明示宛先 (sendToStream) が曖昧」の
+ * 分岐にしか無く、**宛先省略 (sendToCwd) が曖昧なとき**は候補一覧だけ返して解消手段を返して
+ * いなかった。今後「1 つの作業ディレクトリに複数の会話を同時に生かす」方針へ変わり、曖昧に
+ * なる状況は今より起こりやすくなるため、利用者が手詰まりにならない案内を両分岐で共有する。
+ * ここを 2 か所に書くと、CLI 種別や解消手段が変わったときに片方だけ古くなる。
+ *
+ * ⚠️ 解消手段は **CLI 種別ではなく「候補が名指し可能か」** で決める (2026-08-02 訂正)。旧実装は
+ * 「claude は一意な宛先指定子が無いので --to では解消不能」と CLI 種別だけで断定していたが、
+ * これは claude の 2 つの曖昧を混同していた:
+ *   - **明示宛先の曖昧** (`sendToStream`): 同一 session_id の別 session が複数 = resume 競合。
+ *     候補の session_id は全て同じなので、確かに --to では解消できない → Cockpit で整理する案内。
+ *   - **宛先省略の曖昧** (`sendToCwd`): 同一 cwd に**別々の会話**が 2 本以上。候補の session_id は
+ *     互いに異なるので **`--to <session_id>` で名指しできる** → 名指しを案内する。ここを「解消
+ *     不能」と案内すると、実際には解決できる状況で利用者が手詰まりになる (1 つの作業ディレクトリ
+ *     に複数の会話を同時に生かす方針では、これが通常起こりうる状況になる)。
+ * 例外として、宛先省略でも候補に session_id 未確定の fresh が混ざると名指しできないため、その
+ * ときは名指し以外の案内へ落とす (判定は claudeCandidatesNameability)。
+ * codex は stream_id が常に一意なので、従来どおり stream_id での名指しを案内する。
+ *
+ * ⚠️ 名指しできない理由が 2 つあり、**案内が正反対になる** (2026-08-02 round2 minor):
+ *   - 未確定 (`unresolved`) → 待てば session_id が確定する → 「初期化を待って --list で再確認」
+ *   - 重複 (`duplicate`)   → 待っても解決しない            → 「1 本に整理してから再送」
+ * 両方に「整理」と案内すると、待てば直る状況で不要な操作 (チャットの開き直し) を誘発する。
+ *
+ * ⚠️ error / hint / `candidates_nameable` を **必ず同じ呼び出しで一緒に返す** (2026-08-02 クロス
+ * レビュー major / round2 major): 呼び出し側 (配布中の `cockpit_orch.py`) は「候補を実行可能な
+ * `--to` として並べてよいか」をこの機械可読な boolean だけで分岐し、**旧 CLI** はエラーコードだけで
+ * 分岐する。**hint の日本語を CLI にパースさせない** (文言を変えた瞬間に壊れるため)。判定を
+ * 「hint 用」「フィールド用」「エラーコード用」と 3 回呼ぶ形にすると将来ずれるので、1 つの判定から
+ * 全部を組み立てて構造的に食い違えないようにしている。
+ *
+ * @param {string} cliKind 宛先 CLI ("codex" | "claude")
+ * @param {string} [targetSessionId] 明示宛先で指定された id (省略 = 宛先省略の曖昧)
+ * @param {object[]} [candidates] 曖昧になった候補一覧 (claude の名指し可否判定に使う)
+ * @returns {{error: string, hint: string, candidates_nameable: boolean}}
+ *   エラーコードと、空にならない案内文と、機械可読な判定
+ */
+function ambiguousTargetOutcome(cliKind, targetSessionId, candidates) {
+  // 名指し可否の判定はここ 1 回だけ。error も hint もこの値から導くので三者は原理的に一致する。
+  // codex は stream_id が常に一意なので候補を見るまでもなく名指しできる。
+  const nameability = cliKind === "codex" ? "nameable" : claudeCandidatesNameability(candidates)
+  const nameable = nameability === "nameable"
+  const lead = targetSessionId
+    ? cliKind === "codex"
+      ? `指定した id (${targetSessionId}) はこの cwd で複数の live セッションに一致します。`
+      : `指定した session_id (${targetSessionId}) がこの cwd で複数の live セッションに一致します。`
+    : `この cwd には live な ${cliKind} セッションが複数あるため、宛先を省略すると一意に定まりません。`
+  let remedy
+  if (cliKind === "codex") {
+    remedy = `stream_id で名指ししてください (--list で確認)。`
+  } else if (nameability === "nameable") {
+    remedy =
+      `候補はそれぞれ別の会話で session_id が異なるため、session_id で名指しできます ` +
+      `(--list が表示する --to の宛先をそのまま使ってください)。`
+  } else if (nameability === "unresolved") {
+    // 待てば確定する。ここで「1 本に整理」を案内すると不要な開き直しを誘発する。
+    remedy =
+      `候補に session_id が未確定のセッション (開始直後で初期化が完了していないもの) が含まれるため、` +
+      `いま --to には書けません。初期化の完了を待ってから --list で最新の宛先を確認して再送してください。`
+  } else if (nameability === "duplicate") {
+    // 待っても解決しない。Cockpit 側で 1 本に減らす操作が要る。
+    remedy =
+      `候補の session_id が重複している (同じ会話を複数 resume した競合) ため、--to で書き直しても` +
+      `再び複数一致します。Cockpit で対象 cwd の Claude チャットを開き直して1本に整理してから` +
+      `再送してください。`
+  } else {
+    // 候補が空 = 理由を特定できない。待って直るとは断定できないので保守的に整理側へ倒す。
+    remedy =
+      `候補を特定できないため --to では一意に定まりません。--list で最新の宛先を確認し、` +
+      `解消しなければ Cockpit で対象 cwd の Claude チャットを1本に整理してから再送してください。`
+  }
+  return {
+    error: nameable ? AMBIGUOUS_TARGET_ERROR : AMBIGUOUS_TARGET_UNNAMEABLE_ERROR,
+    hint: lead + remedy,
+    candidates_nameable: nameable,
+  }
+}
+
 function deliveredStateFor(kind) {
   return kind === "codex" ? "delivered" : "dispatched"
 }
@@ -238,23 +373,17 @@ export class SiblingInjectBridge {
           }
         } else if (r.status === "ambiguous") {
           // 宛先 id が同一 cwd の複数 live セッションに一致し一意に定まらない。
-          // ⚠️ 解消手段は CLI で異なる (T06271 レビュー4 minor):
-          //   - codex: stream_id は一意なので stream_id で名指しできる
-          //   - claude: 一意な宛先指定子が無い (session_id は重複、stream_id は非公開) ため
-          //     --to では解消不能。Cockpit で該当チャットを開き直す / 再一覧を案内する
+          // 解消手段の案内は ambiguousTargetOutcome に集約 (宛先省略側の分岐と共有する)。候補を
+          // 渡して「その id で名指しできるか」を判定させる (claude の resume 競合はできない)。
+          // ⚠️ error もこの単一判定から来る (名指し不能なら ambiguous_target_unnameable)。ここに
+          //    error をベタ書きすると、判定と食い違ったコードを返して旧 CLI の分岐を誤らせる。
+          //    candidates / live_sessions / hint / candidates_nameable は**落とさない** (旧 CLI が
+          //    未知エラーとして generic 分岐に落ちたとき、診断だけは読めるようにするため)。
           result = {
             ok: false,
-            error: "ambiguous_target",
             candidates: r.candidates,
             live_sessions: r.candidates,
-            hint:
-              target_cli_kind === "codex"
-                ? `指定した id (${target_session_id}) はこの cwd で複数の live セッションに一致します。` +
-                  `stream_id で名指ししてください (--list で確認)。`
-                : `指定した session_id (${target_session_id}) がこの cwd で複数の live セッションに ` +
-                  `一致します。Claude は一意な宛先指定子が無いため --to では解消できません。Cockpit で` +
-                  `対象 cwd の Claude チャットを開き直して1本に整理してから再送してください` +
-                  `(通常は attach 時の重複解消で発生しません)。`,
+            ...ambiguousTargetOutcome(target_cli_kind, target_session_id, r.candidates),
           }
         } else {
           result = {
@@ -309,11 +438,16 @@ export class SiblingInjectBridge {
                 : DELIVERY_FAILED_HINT,
           }
         } else if (r.status === "ambiguous") {
+          // 宛先省略でも「候補一覧だけ返して終わり」にせず、明示宛先側と同じ案内を返す
+          // (CLI 種別で案内の有無が変わるのは不整合)。ここの候補は **別々の会話** なので、
+          // claude でも session_id が相異なれば --to で名指しできる (candidates を渡して判定)。
+          // error / hint / candidates_nameable は同じ判定から一緒に返る (新 CLI はこの boolean で
+          // 表示分岐し、旧 CLI は error だけを見る)。診断フィールドは落とさない。
           result = {
             ok: false,
-            error: "ambiguous_target",
             candidates: r.candidates,
             live_sessions: r.candidates,
+            ...ambiguousTargetOutcome(target_cli_kind, undefined, r.candidates),
           }
         } else {
           result = { ok: false, error: "no_live_session_for_cwd", ...this._diagnose(cwd, target_cli_kind) }