@cocorograph/hub-agent 0.8.58 → 0.8.60

package/README.md

@@ -17,8 +17,10 @@ curl -fsSL https://api.hub.cocorograph.com/api/cockpit/agents/install-script | b
 
 このスクリプトは以下を **全自動** で実行します:
 - Homebrew (macOS で無ければ install)
-- tmux + node 20+ (無ければ install)
+- tmux + node (Active LTS) + python3 (無ければ install)
+- GNU coreutils の `timeout` (補助コマンド。macOS では brew で導入して `gtimeout` への symlink を `~/.local/bin` に作成、Linux は存在確認のみで不在なら手動導入を案内。無くてもセットアップは続行)
 - `npm i -g @cocorograph/hub-agent`
+- `npm i -g @anthropic-ai/claude-code` / `npm i -g @openai/codex` (Claude Code / Codex CLI。既存なら更新)
 - `hub-agent enroll <token>` (token は Hub session 経由で埋め込み済、5 分有効)
 - `hub-agent install-service` で OS サービス登録
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.8.58",
+  "version": "0.8.60",
   "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの Claude / Codex チャットと tmux セッションを中継する。",
   "type": "module",
   "license": "UNLICENSED",

package/scripts/install.sh

@@ -12,11 +12,14 @@
 #   1. macOS なら Homebrew (なければ install)
 #      - 管理者権限が無い環境では自動で $HOME/homebrew にユーザーローカル
 #        インストールに切り替わる (HUB_AGENT_USER_BREW=1 で強制も可)
-#   2. tmux + node (なければ install via brew / apt)
-#   3. npm i -g @cocorograph/hub-agent
-#   4. npm i -g @anthropic-ai/claude-code (既存があれば upgrade のみ)
-#   5. HUB_AGENT_TOKEN が設定されていれば hub-agent enroll を自動実行
-#   6. hub-agent install-service で OS サービス化
+#   2. tmux + node + python3 (なければ install via brew / apt 等)
+#   3. GNU coreutils の timeout (補助コマンド。macOS では brew で入れて gtimeout への
+#      symlink を ~/.local/bin に作成。Linux は存在確認のみで、不在なら手動導入を案内)
+#   4. npm i -g @cocorograph/hub-agent
+#   5. npm i -g @anthropic-ai/claude-code (既存があれば upgrade のみ)
+#   6. npm i -g @openai/codex (常に install / upgrade)
+#   7. HUB_AGENT_TOKEN が設定されていれば hub-agent enroll を自動実行
+#   8. hub-agent install-service で OS サービス化
 # =============================================================================
 
 set -euo pipefail
@@ -41,6 +44,7 @@ NODE_DEFAULT_BREW_FORMULA="node@24"
 
 PACKAGE_NAME="@cocorograph/hub-agent"
 CLAUDE_CODE_PACKAGE="@anthropic-ai/claude-code"
+CODEX_PACKAGE="@openai/codex"
 
 color_step() { printf "\033[1;34m==> %s\033[0m\n" "$1"; }
 color_ok()   { printf "\033[1;32m✓ %s\033[0m\n" "$1"; }
@@ -223,6 +227,49 @@ persist_user_brew_shellenv() {
   done
 }
 
+# snippet をマーカーで囲んで各 profile に冪等追記する。
+# 使い方: persist_profile_snippet '<snippet>' '<label>' '<marker>' '<end_marker>' <profile>...
+# 既に「snippet と完全一致する行」があれば skip する（部分一致だとコメントアウトされた
+# `#export PATH=...` を既存扱いにして追記を飛ばす。マーカーの有無は見ない——マーカーだけ
+# 残って snippet が欠けた部分書込みを再実行で補完できるようにするため）。
+# 追記できない profile（root 所有・読み取り専用）は警告して次へ進み、最後に 1 を返す。
+# 呼び出し側が失敗を致命にするか警告に留めるかを決める（set -e 下で裸で呼べば致命）。
+persist_profile_snippet() {
+  local snippet="$1" label="$2" marker="$3" end_marker="$4"
+  shift 4
+  local target rc=0
+  for target in "$@"; do
+    if [[ -f "$target" ]] && grep -Fxq "$snippet" "$target"; then
+      continue
+    fi
+    if {
+      printf '\n%s\n' "$marker"
+      printf '%s\n' "$snippet"
+      printf '%s\n' "$end_marker"
+    } >> "$target" 2>/dev/null; then
+      color_ok "$target に $label を追記 (新規シェルから有効)"
+    else
+      color_warn "$target に $label を追記できません (書き込み権限を確認してください)"
+      rc=1
+    fi
+  done
+  return "$rc"
+}
+
+# bash の login profile を 1 つ選ぶ。bash は ~/.bash_profile → ~/.bash_login → ~/.profile の
+# うち最初に存在するものだけを読むため、~/.profile しか無い環境で ~/.bash_profile を
+# 新規作成すると ~/.profile が読まれなくなる。既存のものを優先し、無ければ ~/.bash_profile。
+bash_login_profile() {
+  local f
+  for f in "$HOME/.bash_profile" "$HOME/.bash_login" "$HOME/.profile"; do
+    if [[ -f "$f" ]]; then
+      printf '%s\n' "$f"
+      return 0
+    fi
+  done
+  printf '%s\n' "$HOME/.bash_profile"
+}
+
 # user-mode の場合、npm の global prefix を $HOME/.npm-global に切り替える。
 # brew が $HOME/homebrew にいるとき、その prefix への書き込み権限はあるものの、
 # 後で system 版 node / npm に切り替わる可能性も考えて user 領域に逃がしておく。
@@ -256,8 +303,6 @@ ensure_npm_user_prefix() {
   export PATH="$HOME/.npm-global/bin:$PATH"
 
   local snippet='export PATH="$HOME/.npm-global/bin:$PATH"'
-  local marker="# >>> hub-agent: npm-global PATH (user-mode) >>>"
-  local end_marker="# <<< hub-agent: npm-global PATH <<<"
   # 永続先は OS で出し分け。Linux の hub-agent は systemd --user 起動時や
   # `$SHELL -lic` 経由の env 注入で PATH を解決するため、login(.profile) と
   # interactive(.bashrc) の双方に通す。macOS は従来どおり zsh/bash の profile。
@@ -267,18 +312,9 @@ ensure_npm_user_prefix() {
   else
     targets=("$HOME/.bashrc" "$HOME/.profile")
   fi
-  local target
-  for target in "${targets[@]}"; do
-    if [[ -f "$target" ]] && grep -Fq "$snippet" "$target"; then
-      continue
-    fi
-    {
-      printf '\n%s\n' "$marker"
-      printf '%s\n' "$snippet"
-      printf '%s\n' "$end_marker"
-    } >> "$target"
-    color_ok "$target に npm-global PATH を追記"
-  done
+  persist_profile_snippet "$snippet" "npm-global PATH" \
+    "# >>> hub-agent: npm-global PATH (user-mode) >>>" "# <<< hub-agent: npm-global PATH <<<" \
+    "${targets[@]}"
 }
 
 # =============================================================================
@@ -458,28 +494,40 @@ ensure_node_tls_works() {
   exit 1
 }
 
-ensure_pkg() {
-  local cmd="$1"
-  local brew_pkg="$2"
-  local apt_pkg="${3:-$brew_pkg}"
-  if present "$cmd"; then color_ok "$cmd already installed"; return 0; fi
-  color_step "$cmd をインストール"
+# パッケージマネージャ分岐の共通処理。失敗は戻り値で返し、exit するかは呼び出し側が決める。
+#   1 … 導入コマンドが失敗した / 2 … 対応するパッケージマネージャが無い
+# ⚠️ display_cmd は復旧案内に出す「入れたい実行コマンド」。パッケージ名と一致しない
+#    ことがある (pacman の python パッケージ / 検証対象は python3 コマンド)。
+_pm_install() {
+  local brew_pkg="$1"
+  local apt_pkg="$2"
+  local pacman_pkg="${3:-$apt_pkg}"
+  local display_cmd="${4:-$brew_pkg}"
   if [[ "$(uname)" == "Darwin" ]]; then
     # brew install は transient (network / hash mismatch / pour 失敗) を retry で吸収
-    retry 3 brew install "$brew_pkg"
+    retry 3 brew install "$brew_pkg" || return 1
   elif present apt-get; then
-    retry 3 sudo apt-get update -y
-    retry 3 sudo apt-get install -y "$apt_pkg"
+    retry 3 sudo apt-get update -y || return 1
+    retry 3 sudo apt-get install -y "$apt_pkg" || return 1
   elif present dnf; then
-    retry 3 sudo dnf install -y "$apt_pkg"
+    retry 3 sudo dnf install -y "$apt_pkg" || return 1
   elif present pacman; then
-    retry 3 sudo pacman -S --noconfirm "$apt_pkg"
+    retry 3 sudo pacman -S --noconfirm "$pacman_pkg" || return 1
   else
-    color_err "対応するパッケージマネージャ (brew/apt/dnf/pacman) が見つかりません。$cmd を手動で install してください"
-    exit 1
+    color_err "対応するパッケージマネージャ (brew/apt/dnf/pacman) が見つかりません。$display_cmd を手動で install してください"
+    return 2
   fi
 }
 
+ensure_pkg() {
+  local cmd="$1"
+  local brew_pkg="$2"
+  local apt_pkg="${3:-$brew_pkg}"
+  if present "$cmd"; then color_ok "$cmd already installed"; return 0; fi
+  color_step "$cmd をインストール"
+  _pm_install "$brew_pkg" "$apt_pkg" "" "$cmd" || exit 1
+}
+
 # macOS で brew 経由で Active LTS の node (NODE_DEFAULT_BREW_FORMULA) を導入/切替する。
 # 既存の無印 node が link されていれば unlink してから新 formula を link --overwrite --force。
 _install_node_lts_brew() {
@@ -544,6 +592,111 @@ ensure_build_tools() {
   fi
 }
 
+# Hub AI bundle のフック・helper と hub-agent bootstrap が使う python3 を保証する。
+# macOS の /usr/bin/python3 は Xcode CLT 未導入時にスタブの場合があるため、
+# command の存在ではなく実際の version コマンドが成功するかで判定する。
+ensure_python3() {
+  if python3 --version >/dev/null 2>&1; then
+    color_ok "$(python3 --version 2>&1)"
+    return 0
+  fi
+
+  color_step "python3 をインストール"
+  # macOS で python3 が動かないのは、ほぼ Xcode CLT 未導入（/usr/bin/python3 がスタブ）。
+  # brew 経路が失敗したら、set -e で黙って落ちる前に実際の復旧手順を出す。
+  # pacman のパッケージ名は python3 でなく python。案内に出すコマンド名は python3。
+  if ! _pm_install python python3 python python3; then
+    if [[ "$(uname)" == "Darwin" ]]; then
+      color_err "python3 を導入できません。\`xcode-select --install\` を実行してから再実行してください"
+    fi
+    exit 1
+  fi
+  hash -r 2>/dev/null || true
+
+  if python3 --version >/dev/null 2>&1; then
+    color_ok "$(python3 --version 2>&1)"
+  else
+    color_err "python3 の導入後も実行できません"
+    exit 1
+  fi
+}
+
+# timeout を保証する（補助コマンド。AI セッションの Bash やスクリプトが使うが、
+# hub-agent の常駐動作には必須ではないため、導入失敗は警告して継続する。
+# 必須ランタイムの python3 とは契約を分けている）。
+# macOS の coreutils は gtimeout 名で入るため、timeout だけを ~/.local/bin に公開する。
+# coreutils の gnubin 全体を PATH に足すと sed / date 等まで GNU 版へ置き換わり、
+# 既存スクリプトの挙動が変わるため採用しない。
+_report_timeout() {
+  if present timeout; then
+    color_ok "timeout $(timeout --version 2>/dev/null </dev/null | head -1 || echo 'installed')"
+  else
+    color_warn "timeout コマンドが PATH に見つかりません (補助コマンドのため継続。新規シェルで再確認してください)"
+  fi
+}
+
+ensure_timeout() {
+  if [[ "$(uname)" != "Darwin" ]]; then
+    # Linux の timeout は coreutils (Debian の essential / busybox にも同梱) なので
+    # 通常は存在する。無い環境はインストーラが推測で入れず、警告に留める。
+    if ! present timeout; then
+      color_warn "timeout が見つかりません (coreutils を手動で導入してください。補助コマンドのため継続)"
+    fi
+    _report_timeout
+    return 0
+  fi
+
+  local local_bin="$HOME/.local/bin"
+  local link="$local_bin/timeout"
+  local found
+  found="$(command -v timeout 2>/dev/null || true)"
+  # このインストーラ管理の symlink 以外の timeout が既に見えていれば、それを尊重する
+  if [[ -n "$found" && "$found" != "$link" ]]; then
+    color_ok "timeout already installed ($found)"
+    return 0
+  fi
+
+  if [[ -e "$link" && ! -L "$link" ]]; then
+    # ユーザーが自前で置いた実体は上書きしない（PATH 永続化だけ揃える）
+    color_ok "$link は手動管理のため変更しません"
+  else
+    local gtimeout
+    gtimeout="$(command -v gtimeout 2>/dev/null || true)"
+    if [[ -z "$gtimeout" ]]; then
+      color_step "GNU coreutils (timeout) をインストール"
+      if ! retry 3 brew install coreutils; then
+        color_warn "coreutils の導入に失敗しました (timeout は補助コマンドのため継続)"
+        return 0
+      fi
+      hash -r 2>/dev/null || true
+      gtimeout="$(command -v gtimeout 2>/dev/null || true)"
+    fi
+    if [[ -z "$gtimeout" ]]; then
+      color_warn "gtimeout が PATH に見つかりません (timeout は補助コマンドのため継続)"
+      return 0
+    fi
+    if ! mkdir -p "$local_bin" 2>/dev/null || ! ln -sfn "$gtimeout" "$link" 2>/dev/null; then
+      color_warn "$link を作成できません (書き込み権限を確認してください。補助コマンドのため継続)"
+      return 0
+    fi
+  fi
+
+  # symlink の有無と PATH 永続化は別々に収束させる。再実行時に片方だけ欠けていても
+  # ここで補完される（早期 return で profile の修復を飛ばさない）。
+  # ~/.local/bin は PATH の「末尾」に足す。先頭に置くと pipx / pyenv 等が置いた
+  # ~/.local/bin/python3 や node のシムが brew / system のものを隠してしまう。
+  # timeout を見つけるだけなら末尾で足りる（別の timeout があれば上で return 済み）。
+  # PATH 代入で bash の command hash は全消去されるので、この後の hash -r は不要。
+  export PATH="$PATH:$local_bin"
+  # npm prefix と同じく zsh / bash 双方の login profile へ永続化する。
+  # 追記失敗（root 所有の profile 等）はこの補助コマンドの契約に合わせて警告に留める。
+  persist_profile_snippet 'export PATH="$PATH:$HOME/.local/bin"' "~/.local/bin PATH" \
+    "# >>> hub-agent: local-bin PATH (timeout) >>>" "# <<< hub-agent: local-bin PATH <<<" \
+    "$HOME/.zprofile" "$(bash_login_profile)" \
+    || color_warn "PATH の永続化に失敗した profile があります (timeout は補助コマンドのため継続)"
+  _report_timeout
+}
+
 # Node.js のサポート範囲ポリシー判定。
 # - 未インストール → LTS を install
 # - [MIN, MAX] 範囲内 → 現状維持（ユーザーの環境を尊重）
@@ -599,29 +752,69 @@ ensure_global_install() {
   color_ok "hub-agent $(hub-agent --version)"
 }
 
-# Claude Code CLI を同梱でセットアップ。Cockpit 側から claude を呼び出すので、
-# 同じ npm-global prefix に入れておくとパス解決が一貫する。
-# 既存があれば upgrade のみ（破壊しない）。
-ensure_claude_code() {
-  if present claude; then
+# npm 配信の CLI を導入/upgrade する共通処理。
+#   required=1 … 新規導入の失敗を非 0 で呼び出し側へ返す。main から素の
+#                コマンドとして呼べば set -e でセットアップ全体が止まる
+#                (この関数自身は exit しないので、条件式から呼べば拾える)
+#   required=0 … 新規導入が失敗しても警告のみでセットアップを継続する
+#   上記以外   … 契約違反として 2 を返す (タイプミスを optional へ倒さない)
+# ⚠️ fail_hint は「導入できなかったとき何が使えなくなるか」を呼び出し側が渡す。
+#    この関数に CLI 固有の文言を書かないこと (次の CLI を足したとき嘘になる)。
+_ensure_npm_cli() {
+  local cmd="$1"
+  local package="$2"
+  local label="$3"
+  local required="$4"
+  local fail_hint="${5:-}"
+  # ⚠️ required は 0/1 のみ受け付ける。"true" 等のタイプミスを optional 扱いへ
+  #    黙って倒すと、必須 CLI が入らないままセットアップが完了する。
+  case "$required" in
+    0|1) ;;
+    *)
+      color_err "_ensure_npm_cli: required は 0/1 のみです (受け取った値: '${required}')"
+      return 2
+      ;;
+  esac
+  if present "$cmd"; then
     local cur
-    cur=$(claude --version 2>/dev/null || echo "unknown")
-    color_step "Claude Code (現在 $cur) を最新版にアップデート"
+    cur=$("$cmd" --version 2>/dev/null </dev/null || echo "unknown")
+    color_step "$label (現在 $cur) を最新版にアップデート"
     # claude は Anthropic 配信。失敗しても既存版で継続 (warning のみ)。
-    retry 2 npm install -g "${CLAUDE_CODE_PACKAGE}@latest" --force \
-      || color_warn "Claude Code upgrade に失敗 (既存版で継続)"
+    retry 2 npm install -g "${package}@latest" --force \
+      || color_warn "$label upgrade に失敗 (既存版で継続)"
   else
-    color_step "$CLAUDE_CODE_PACKAGE を install"
-    retry 3 npm install -g "${CLAUDE_CODE_PACKAGE}@latest" --force
+    color_step "$package を install"
+    if [[ "$required" == "1" ]]; then
+      # ⚠️ 明示的に return する。条件式 (`if f; then`) の中では関数内の errexit が
+      #    抑止されるため、暗黙の set -e に頼ると必須契約が呼び出し方で消える。
+      retry 3 npm install -g "${package}@latest" --force || return 1
+    elif ! retry 3 npm install -g "${package}@latest" --force; then
+      color_warn "$label の導入に失敗しました。${fail_hint:-セットアップは継続します}"
+      color_warn "  手動で実行: npm install -g ${package}@latest"
+    fi
   fi
   hash -r 2>/dev/null || true
-  if present claude; then
-    color_ok "claude $(claude --version 2>/dev/null || echo 'installed')"
+  if present "$cmd"; then
+    color_ok "$cmd $("$cmd" --version 2>/dev/null </dev/null || echo 'installed')"
   else
-    color_warn "claude コマンドが PATH に見つかりません。新規シェルで再確認してください"
+    color_warn "$cmd コマンドが PATH に見つかりません。新規シェルで再確認してください"
   fi
 }
 
+# Claude Code CLI を同梱でセットアップ。Cockpit 側から claude を呼び出すので、
+# 同じ npm-global prefix に入れておくとパス解決が一貫する。
+# 既存があれば upgrade のみ（破壊しない）。hub-agent のチャットに必須なので required=1。
+ensure_claude_code() {
+  _ensure_npm_cli claude "$CLAUDE_CODE_PACKAGE" "Claude Code" 1
+}
+
+# Codex CLI を同梱でセットアップ。hub-agent 自体の動作には必須ではないため、
+# 新規導入・upgrade とも失敗時は警告してセットアップを継続する。
+ensure_codex() {
+  _ensure_npm_cli codex "$CODEX_PACKAGE" "Codex CLI" 0 \
+    "Codex チャット / 委譲 / 画像生成は使えません"
+}
+
 do_enroll() {
   if [[ -z "${HUB_AGENT_TOKEN:-}" ]]; then
     color_warn "HUB_AGENT_TOKEN が未設定。enroll は skip します"
@@ -767,6 +960,24 @@ verify_setup() {
     color_warn "Claude Code (claude) コマンドが見つかりません (cockpit から claude を呼ぶ場合は必要)"
   fi
 
+  # Codex CLI (任意なので warn のみ)
+  if present codex; then
+    color_ok "Codex CLI: $(codex --version 2>/dev/null </dev/null || echo 'installed')"
+  else
+    color_warn "Codex CLI (codex) コマンドが見つかりません (Codex チャット / 委譲 / 画像生成には必要)"
+  fi
+
+  # python3 (Hub AI bundle と hub-agent bootstrap に必須)
+  if python3 --version >/dev/null 2>&1; then
+    color_ok "Python 3: $(python3 --version 2>&1)"
+  else
+    color_err "python3 コマンドが実行できません"
+    errors=$((errors + 1))
+  fi
+
+  # timeout は補助コマンド (ensure_timeout と同じ契約) なので warn のみ
+  _report_timeout
+
   # 3. Hub AI bundle 展開を **CLI 別** に検証（manifest / CONFIG_MD マーカー /
   #    hooks の Hub SessionStart hook / 正規 .hub_token.json）。Codex 未インストールなら
   #    codex は検証しない（2026-07-15）。
@@ -831,7 +1042,7 @@ EOF
 
 main() {
   color_step "hub-agent ワンライナーセットアップを開始"
-  STEP_TOTAL=11
+  STEP_TOTAL=15
   STEP_NUM=0
 
   step_header "Homebrew"
@@ -842,6 +1053,10 @@ main() {
   ensure_node_version
   step_header "Build tools (native addons)"
   ensure_build_tools
+  step_header "Python 3"
+  ensure_python3
+  step_header "GNU coreutils (timeout)"
+  ensure_timeout
   step_header "npm global prefix"
   ensure_npm_user_prefix
   # ensure_node_version 直後だと brew link でシェルの command hash がズレている
@@ -854,6 +1069,8 @@ main() {
   ensure_global_install
   step_header "Claude Code install"
   ensure_claude_code
+  step_header "Codex CLI install"
+  ensure_codex
   step_header "enroll + bundle 同期"
   do_enroll
   step_header "Hub AI bootstrap (CLAUDE.md / hooks 初期化)"
@@ -869,4 +1086,15 @@ main() {
   macos_perm_guidance
 }
 
-main "$@"
+# このファイルが source されたか（実行されたか）を判定する。
+#   - `bash -c "$(curl ...)"` / `curl ... | bash` : BASH_SOURCE が空 → 実行
+#   - `bash install.sh` / `./install.sh`          : BASH_SOURCE[0] == $0 → 実行
+#   - `source install.sh`（test/install-sh.test.mjs）: BASH_SOURCE[0] != $0 → source
+# 環境変数で切り替えると、変数が残ったシェルや CI でワンライナーが無言の no-op になるため使わない。
+_install_sh_is_sourced() {
+  [[ -n "${BASH_SOURCE[0]:-}" && "${BASH_SOURCE[0]}" != "$0" ]]
+}
+
+if ! _install_sh_is_sourced; then
+  main "$@"
+fi

package/src/claude-history.mjs

@@ -169,10 +169,209 @@ async function getLastTurnAtMsCached(fileMap, filePath, mtimeMs, size) {
   // round2 minor 対応)。前回値も無ければ最後の手段として mtime。
   const extracted = await extractLastTurnAtMs(filePath, null)
   const lastTurnAtMs = extracted ?? entry?.lastTurnAtMs ?? mtimeMs
-  fileMap.set(filePath, { mtimeMs, size, lastTurnAtMs })
+  fileMap.set(filePath, { ...entry, mtimeMs, size, lastTurnAtMs })
   return lastTurnAtMs
 }
 
+const TITLE_SCAN_CHUNK_SIZE = 64 * 1024
+const TITLE_FINGERPRINT_SIZE = 256
+let titleScanBytesForTest = 0
+let titleMaxCarryBytesForTest = 0
+export function getTitleScanBytesForTest() {
+  return titleScanBytesForTest
+}
+export function resetTitleScanBytesForTest() {
+  titleScanBytesForTest = 0
+}
+export function getTitleMaxCarryBytesForTest() {
+  return titleMaxCarryBytesForTest
+}
+export function resetTitleMaxCarryBytesForTest() {
+  titleMaxCarryBytesForTest = 0
+}
+
+function takeTitleFromLine(line, entry) {
+  if (!line.includes('"custom-title"') && !line.includes('"ai-title"')) return
+  let obj
+  try {
+    obj = JSON.parse(line)
+  } catch {
+    return
+  }
+  if (obj?.type === "custom-title" && typeof obj.customTitle === "string") {
+    entry.customTitle = obj.customTitle
+  } else if (obj?.type === "ai-title" && typeof obj.aiTitle === "string") {
+    entry.aiTitle = obj.aiTitle
+  }
+}
+
+function titleFromEntry(entry) {
+  const customTitle = entry.customTitle?.trim().replace(/\s+/g, " ")
+  const aiTitle = entry.aiTitle?.trim().replace(/\s+/g, " ")
+  const title = customTitle || aiTitle
+  return title ? (MASK_ENABLED ? redactSecrets(title) : title) : undefined
+}
+
+/** jsonl の前回処理済み改行以降だけを読み、表示名を返す。
+ *
+ *  呼び出し側の stat (size / mtimeMs) は「走査が要るか」の判定にだけ使い、走査範囲と commit 値は
+ *  open 後の fstat で取り直す (cross-review round2 F2: 古い stat を持った呼び出しが新しい走査の
+ *  後に到着すると、古い size まで再走査してキャッシュを巻き戻していた)。進行中の走査を待った
+ *  呼び出しは、その走査が fstat 時点の最新を commit しているので再走査せず commit 値を返す。
+ *
+ *  書き換え検知は「size 減少」と「scannedBytes 直前 256 バイトの fingerprint 不一致」で行う。
+ *  ⚠️ 既知の限界 (round2 F1 で指摘・意図的に採らない): 末尾 256 バイトを保ったまま前方だけを
+ *  書き換える置換は検出できない。jsonl を書くのは Claude CLI だけで、title の変更は新しい
+ *  custom-title / ai-title 行の追記 (last-wins) として現れ、既存行の置換は行わない。完全検知には
+ *  変更のたびに処理済み領域全体の再読込が要り、ハートビート経路の差分キャッシュが成立しなくなる。 */
+async function extractTitleCached(fileMap, filePath, size, mtimeMs) {
+  let entry = fileMap.get(filePath)
+  if (!entry) {
+    entry = { scannedBytes: 0 }
+    fileMap.set(filePath, entry)
+  }
+
+  if (entry.titleScanPromise) {
+    // 進行中の走査は fstat 時点の最新状態を commit する。待った側の stat が新しくても古くても、
+    // ここで再走査すると (古い stat なら) 巻き戻し、(新しい stat なら) 二重走査になるだけなので
+    // commit 値をそのまま返す。走査後に追記された分は次回の listSessions で拾う。
+    await entry.titleScanPromise
+    return titleFromEntry(fileMap.get(filePath) || entry)
+  }
+
+  if (size === entry.scannedBytes && mtimeMs === entry.titleMtimeMs) {
+    return titleFromEntry(entry)
+  }
+
+  const scanPromise = (async () => {
+    const previousScannedBytes = typeof entry.scannedBytes === "number" ? entry.scannedBytes : 0
+    let scanFrom = previousScannedBytes
+    let customTitle = entry.customTitle
+    let aiTitle = entry.aiTitle
+    let fingerprint = Buffer.isBuffer(entry.titleFingerprint) ? entry.titleFingerprint : Buffer.alloc(0)
+    let skippingHugeLine = entry.titleSkippingHugeLine === true
+    let handle
+    try {
+      handle = await open(filePath, "r")
+      // 走査範囲と commit 値は呼び出し側の snapshot ではなく open した実体の fstat を使う。
+      const actualStat = await handle.stat()
+      size = actualStat.size
+      mtimeMs = actualStat.mtimeMs
+      let reset = size < previousScannedBytes
+      if (!reset && previousScannedBytes > 0) {
+        const fingerprintStart = Math.max(0, previousScannedBytes - TITLE_FINGERPRINT_SIZE)
+        const expectedLength = previousScannedBytes - fingerprintStart
+        const actual = Buffer.allocUnsafe(expectedLength)
+        const { bytesRead } = await handle.read(actual, 0, expectedLength, fingerprintStart)
+        titleScanBytesForTest += bytesRead
+        reset = bytesRead !== fingerprint.length
+          || !actual.subarray(0, bytesRead).equals(fingerprint)
+      }
+      if (reset) {
+        scanFrom = 0
+        customTitle = undefined
+        aiTitle = undefined
+        fingerprint = Buffer.alloc(0)
+        skippingHugeLine = false
+      }
+
+      let position = scanFrom
+      let scannedBytes = scanFrom
+      let fingerprintTail = fingerprint
+      let carry = Buffer.alloc(0)
+      while (position < size) {
+        const length = Math.min(TITLE_SCAN_CHUNK_SIZE, size - position)
+        const chunk = Buffer.allocUnsafe(length)
+        const { bytesRead } = await handle.read(chunk, 0, length, position)
+        if (bytesRead === 0) break
+        titleScanBytesForTest += bytesRead
+        position += bytesRead
+        let incoming = chunk.subarray(0, bytesRead)
+        if (skippingHugeLine) {
+          const newline = incoming.indexOf(NEWLINE_BYTE)
+          if (newline < 0) {
+            scannedBytes = position
+            fingerprintTail = Buffer.concat([fingerprintTail, incoming]).subarray(
+              Math.max(0, fingerprintTail.length + incoming.length - TITLE_FINGERPRINT_SIZE),
+            )
+            continue
+          }
+          const skippedThroughNewline = incoming.subarray(0, newline + 1)
+          fingerprintTail = Buffer.concat([fingerprintTail, skippedThroughNewline]).subarray(
+            Math.max(
+              0,
+              fingerprintTail.length + skippedThroughNewline.length - TITLE_FINGERPRINT_SIZE,
+            ),
+          )
+          incoming = incoming.subarray(newline + 1)
+          skippingHugeLine = false
+          scannedBytes = position - incoming.length
+        }
+        const region = carry.length
+          ? Buffer.concat([carry, incoming])
+          : incoming
+        const lastNewline = region.lastIndexOf(0x0a)
+        if (lastNewline < 0) {
+          if (region.length > LAST_TURN_MAX_LINE) {
+            carry = Buffer.alloc(0)
+            skippingHugeLine = true
+            scannedBytes = position
+            fingerprintTail = region.subarray(Math.max(0, region.length - TITLE_FINGERPRINT_SIZE))
+          } else {
+            carry = region
+            titleMaxCarryBytesForTest = Math.max(titleMaxCarryBytesForTest, carry.length)
+          }
+          continue
+        }
+        const complete = region.subarray(0, lastNewline)
+        for (const lineBuf of splitLinesBuf(complete)) {
+          if (lineBuf.length > LAST_TURN_MAX_LINE) continue
+          const titleState = { customTitle, aiTitle }
+          takeTitleFromLine(lineBuf.toString("utf-8"), titleState)
+          customTitle = titleState.customTitle
+          aiTitle = titleState.aiTitle
+        }
+        carry = region.subarray(lastNewline + 1)
+        titleMaxCarryBytesForTest = Math.max(titleMaxCarryBytesForTest, carry.length)
+        scannedBytes = position - carry.length
+        const consumed = region.subarray(0, lastNewline + 1)
+        fingerprintTail = Buffer.concat([fingerprintTail, consumed]).subarray(
+          Math.max(0, fingerprintTail.length + consumed.length - TITLE_FINGERPRINT_SIZE),
+        )
+      }
+
+      const current = fileMap.get(filePath) || {}
+      fileMap.set(filePath, {
+        ...current,
+        customTitle,
+        aiTitle,
+        scannedBytes,
+        titleFingerprint: Buffer.from(fingerprintTail),
+        titleMtimeMs: mtimeMs,
+        titleSkippingHugeLine: skippingHugeLine,
+        titleScanPromise: scanPromise,
+      })
+    } catch {
+      // 個別ファイルの read エラーでは一覧自体を失敗させず、前回値を維持する。
+    } finally {
+      await handle?.close()
+    }
+  })()
+  entry.titleScanPromise = scanPromise
+  try {
+    await scanPromise
+  } finally {
+    const current = fileMap.get(filePath)
+    if (current?.titleScanPromise === scanPromise) delete current.titleScanPromise
+  }
+  return titleFromEntry(fileMap.get(filePath) || entry)
+}
+
+/** テスト用: 呼び出し側 snapshot を偽装して extractTitleCached を直接叩く (round2 F2 の逆順再現)。 */
+export function extractTitleCachedForTest(filePath, size, mtimeMs) {
+  return extractTitleCached(getLastTurnDirMap(path.dirname(filePath)), filePath, size, mtimeMs)
+}
+
 /** テスト用: last_turn_at_ms キャッシュを全消去する。 */
 export function clearLastTurnCacheForTest() {
   lastTurnDirCache.clear()
@@ -968,7 +1167,8 @@ export async function listSessions({ cwd, projectsRoot, limit = 30, logger }) {
   const sessions = []
   for (const s of top) {
     const preview = await extractPreview(s.file_path)
-    sessions.push({ ...s, preview })
+    const title = await extractTitleCached(fileMap, s.file_path, s.size_bytes, s.mtime)
+    sessions.push({ ...s, preview, ...(title === undefined ? {} : { title }) })
   }
   return { sessions }
 }

package/src/claude-stream-bridge.mjs

@@ -422,6 +422,9 @@ function isSessionRunningEvent(msg) {
  *  正しく終端として扱う (ガードが固着して _busy が永久 true になる = T06052 の再発を防ぐ安全弁)。 */
 const STALE_IDLE_GUARD_MS = 5000
 
+/** per-message の title control request を待って InputQueue を閉じる上限。 */
+const SESSION_TITLE_CLOSE_WAIT_MS = 15_000
+
 /**
  * 1 stream に対応する Claude セッション (per-message query モデル)。
  */
@@ -498,6 +501,12 @@ export class ClaudeStreamSession {
 
     /** 次の query() で resume に使う session_id。各ターンの system/init で更新。 */
     this.sessionId = resumeSessionId || null
+    /** fresh resident query の初回プロンプト。query 起動時に一度だけ消費する。 */
+    this._pendingTitleSeed = null
+    /** 同じ session_id への title control request の二重送信を防ぐ。 */
+    this._titleRequestedFor = null
+    /** テストで timeout 経路を短縮可能にするが、実運用値は常に 15 秒。 */
+    this._sessionTitleCloseWaitMs = SESSION_TITLE_CLOSE_WAIT_MS
 
     /** browser 切断中フラグ。true でも query は中断せず継続する (絶対に落とさない)。 */
     this._detached = false
@@ -1356,6 +1365,7 @@ export class ClaudeStreamSession {
         // Phase 2 (major#1): resident fresh start は started を出さないため、注入なら source 付きで
         // 昇格バブルを作るよう started を先出しする (通常メッセージは no-op)。
         this._maybeEmitInjectStarted(prompt)
+        this._pendingTitleSeed = prompt
         this._startResidentTurnWithInput(toSDKUserMessage(prompt), ultracode)
         return { accepted: true }
       }
@@ -1445,6 +1455,20 @@ export class ClaudeStreamSession {
     }
     // 直前ターンまでの session_id があれば resume チェーン
     if (this.sessionId) options.resume = this.sessionId
+    const isFreshStart = !options.resume
+    // title 待ちの後始末 (timer / abort listener / InputQueue close) は try の外に持ち、
+    // 正常完走・init 未到達の異常終端・abort のどの経路でも finally で 1 回だけ冪等に行う
+    // (cross-review F4: init 前に generator が return/reject すると timer と listener が残っていた)。
+    const abortSignal = this._abortController.signal
+    let titleWait = null
+    const finishTitleWait = () => {
+      if (!titleWait) return
+      const { inputQueue, timer } = titleWait
+      titleWait = null
+      if (timer) clearTimeout(timer)
+      abortSignal.removeEventListener("abort", finishTitleWait)
+      inputQueue.close()
+    }
 
     try {
       // 改修4 (A): canUseTool は streaming input (AsyncIterable prompt) でのみ確実に機能する。
@@ -1452,9 +1476,20 @@ export class ClaudeStreamSession {
       // resume チェーン挙動は維持しつつ、文字列 prompt + canUseTool の SDK 制約リスクを回避する。
       const inputQueue = new InputQueue()
       inputQueue.push(toSDKUserMessage(prompt))
-      inputQueue.close()
-      const generator = this.sdk.query({ prompt: inputQueue, options })
-      for await (const msg of generator) {
+      const q = this.sdk.query({ prompt: inputQueue, options })
+      const shouldWaitForTitle =
+        isFreshStart && this._canGenerateSessionTitle(q, prompt)
+      if (shouldWaitForTitle) {
+        // 入力を即 close すると title control request が "Query closed before response
+        // received" で失敗する (実測) ため、title settle か上限時間まで close を遅らせる。
+        const timer = setTimeout(finishTitleWait, this._sessionTitleCloseWaitMs)
+        timer.unref?.()
+        titleWait = { inputQueue, timer }
+        abortSignal.addEventListener("abort", finishTitleWait, { once: true })
+      } else {
+        inputQueue.close()
+      }
+      for await (const msg of q) {
         if (
           msg?.type === "system" &&
           msg?.subtype === "init" &&
@@ -1463,6 +1498,9 @@ export class ClaudeStreamSession {
           this.sessionId = msg.session_id
           // session_id が確定/変化したら watch をその jsonl に張り替える
           this._ensureWatch()
+          if (shouldWaitForTitle) {
+            this._requestSessionTitle(q, prompt, msg.session_id).finally(finishTitleWait)
+          }
         }
         // result イベントでも session_id が来ることがある (念のため拾う)
         if (msg?.type === "result") {
@@ -1490,6 +1528,8 @@ export class ClaudeStreamSession {
         }
       }
     } finally {
+      // init 未到達で generator が終端した場合も title 待ちの timer / listener を残さない。
+      finishTitleWait()
       this._abortController = null
       // 未解決 permission は閉じ、browser の孤児カードも撤去する
       this._denyAllPendingPermissions("turn ended")
@@ -1575,6 +1615,40 @@ export class ClaudeStreamSession {
     }
   }
 
+  /** title 生成の静的条件。session_id 単位のガードは init 受信後に別途判定する。 */
+  _canGenerateSessionTitle(q, seedText) {
+    const trimmed = seedText.trim()
+    return (
+      process.env.HUB_AGENT_SESSION_TITLE !== "0" &&
+      trimmed.length >= 10 &&
+      !trimmed.startsWith("/") &&
+      typeof q?.generateSessionTitle === "function"
+    )
+  }
+
+  /** title control request。失敗を通常ターンへ伝播させない。 */
+  async _requestSessionTitle(q, seedText, sessionId) {
+    if (
+      this._titleRequestedFor === sessionId ||
+      !this._canGenerateSessionTitle(q, seedText)
+    ) {
+      return
+    }
+    this._titleRequestedFor = sessionId
+    try {
+      const result = await q.generateSessionTitle(seedText, { persist: true })
+      this.logger?.info(
+        { title: result?.title, stream_id: this.stream_id },
+        "session title generated",
+      )
+    } catch (err) {
+      this.logger?.warn(
+        { err: err.message, stream_id: this.stream_id },
+        "session title generation failed",
+      )
+    }
+  }
+
   /** 改修3: pending キューの先頭を取り出して次の per-message ターンを発火する。
    *  各ターンの finally から呼ばれ、キューが空になるまで resume チェーンが続く。 */
   _drainPending() {
@@ -2042,6 +2116,8 @@ export class ClaudeStreamSession {
     // 改修4: 起動時に sessionId (= resumeSessionId) があれば resume チェーンで文脈を引き継ぐ。
     // query 起動時点の値のみ有効 (起動後に確定/変化する session_id は同一 query 内で継続される)。
     if (this.sessionId) options.resume = this.sessionId
+    const titleSeed = options.resume ? null : this._pendingTitleSeed
+    this._pendingTitleSeed = null
     // 空 InputQueue 窓封鎖 (T06118): fresh start の初回ターンが ultracode を要求していれば、
     // per-message と同じく起動時 options.settings に焼き込む。こうすることで「query を空 queue
     // で先に起動 → applyFlagSettings を await → push」という空窓経路を踏まずに済む。初回だけ
@@ -2068,6 +2144,9 @@ export class ClaudeStreamSession {
           typeof msg.session_id === "string"
         ) {
           this.sessionId = msg.session_id
+          if (titleSeed != null) {
+            void this._requestSessionTitle(q, titleSeed, msg.session_id)
+          }
         }
         if (msg?.type === "result") {
           if (typeof msg.session_id === "string") this.sessionId = msg.session_id