@cocorograph/hub-agent 0.5.26 → 0.5.28

package/package.json

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

package/scripts/install.sh

@@ -21,6 +21,13 @@
 
 set -euo pipefail
 
+# brew の auto-update / hint 出力は初回 install で長時間化する原因の最大要因。
+# 環境変数で抑止して 1 発完走率を上げる。最新 Formula が欲しいときは
+# ユーザーが `brew update` を別途実行する前提。
+export HOMEBREW_NO_AUTO_UPDATE=1
+export HOMEBREW_NO_ENV_HINTS=1
+export HOMEBREW_NO_INSTALL_CLEANUP=1
+
 # Node.js のサポート範囲ポリシー（Active LTS のみ）。
 # - 既存 node のメジャーが [MIN, MAX] に収まっていれば現状維持
 # - 範囲外なら NODE_DEFAULT_BREW_FORMULA (最新 Active LTS) にアップ / ダウングレード
@@ -42,6 +49,42 @@ color_err()  { printf "\033[1;31m✗ %s\033[0m\n" "$1" >&2; }
 
 present() { command -v "$1" >/dev/null 2>&1; }
 
+# step counter (main() で使う)。色は出すが詳細メッセージは関数内に任せる。
+# STEP_TOTAL は main の冒頭で再設定する想定。
+STEP_TOTAL=10
+STEP_NUM=0
+step_header() {
+  STEP_NUM=$((STEP_NUM + 1))
+  printf "\033[1;36m\n━━━ [%d/%d] %s ━━━\033[0m\n" "$STEP_NUM" "$STEP_TOTAL" "$1"
+}
+
+# 指定コマンドを最大 N 回まで指数 backoff で retry する。
+# transient な network / brew / npm 失敗を耐える用途。
+# 使い方: retry 3 brew install foo
+#         retry 3 npm install -g bar
+#
+# 重要: bash の `set -e` 下では `if cmd` パターンは cmd の戻り値で分岐するため、
+#       cmd 失敗時に script が exit しない (`set -e` の標準仕様)。
+#       retry 全体が失敗した時のみ呼び出し元が exit する。
+retry() {
+  local max="$1"; shift
+  local i=1
+  local delay=2
+  while true; do
+    if "$@"; then
+      return 0
+    fi
+    if (( i >= max )); then
+      color_err "コマンドが ${max} 回連続失敗: $*"
+      return 1
+    fi
+    color_warn "失敗 (${i}/${max}) → ${delay}s 後に再試行: $*"
+    sleep "$delay"
+    i=$((i + 1))
+    delay=$((delay * 2))
+  done
+}
+
 # 現在 PATH にある brew が、このユーザーで書き込み可能か判定する。
 # 「brew はあるが Cellar が他ユーザー所有で書き込み不可」というケースを検知して
 # user-local Homebrew にフォールバックするための判定関数。
@@ -89,7 +132,9 @@ ensure_brew() {
     _install_user_local_brew
   else
     color_step "Homebrew をシステムインストール"
-    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+    # Homebrew 公式 install.sh をダウンロードして実行。
+    # curl は GitHub raw のレート制限や transient 502 を retry でカバーする。
+    retry 3 bash -c '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'
     # Apple Silicon の brew はデフォルト PATH に入らないので追加
     if [[ -d /opt/homebrew/bin ]]; then
       export PATH="/opt/homebrew/bin:$PATH"
@@ -107,7 +152,9 @@ _install_user_local_brew() {
   else
     color_step "Homebrew をユーザーローカルインストール (\$HOME/homebrew)"
     mkdir -p "$HOME/homebrew"
-    curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C "$HOME/homebrew"
+    # GitHub tarball ダウンロード + tar 展開を 1 つの bash -c に包んで retry にかける。
+    # pipe 途中の curl 失敗を retry のスコープに収めるため。
+    retry 3 bash -c 'curl -fsSL https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C "$HOME/homebrew"'
   fi
   # PATH を user-local 優先で並べる（既存 /usr/local/bin/brew より先）
   export PATH="$HOME/homebrew/bin:$PATH"
@@ -398,14 +445,15 @@ ensure_pkg() {
   if present "$cmd"; then color_ok "$cmd already installed"; return 0; fi
   color_step "$cmd をインストール"
   if [[ "$(uname)" == "Darwin" ]]; then
-    brew install "$brew_pkg"
+    # brew install は transient (network / hash mismatch / pour 失敗) を retry で吸収
+    retry 3 brew install "$brew_pkg"
   elif present apt-get; then
-    sudo apt-get update -y
-    sudo apt-get install -y "$apt_pkg"
+    retry 3 sudo apt-get update -y
+    retry 3 sudo apt-get install -y "$apt_pkg"
   elif present dnf; then
-    sudo dnf install -y "$apt_pkg"
+    retry 3 sudo dnf install -y "$apt_pkg"
   elif present pacman; then
-    sudo pacman -S --noconfirm "$apt_pkg"
+    retry 3 sudo pacman -S --noconfirm "$apt_pkg"
   else
     color_err "対応するパッケージマネージャ (brew/apt/dnf/pacman) が見つかりません。$cmd を手動で install してください"
     exit 1
@@ -417,7 +465,7 @@ ensure_pkg() {
 _install_node_lts_brew() {
   local formula="$NODE_DEFAULT_BREW_FORMULA"
   color_step "$formula (Active LTS) を install"
-  brew install "$formula"
+  retry 3 brew install "$formula"
   # 既存無印 node が link されていれば外す（v26 current 等を退かす）
   if brew list node >/dev/null 2>&1; then
     color_step "既存 'node' formula を unlink ($formula を優先するため)"
@@ -465,15 +513,19 @@ ensure_node_version() {
 }
 
 ensure_global_install() {
+  # @latest 明示 + --force で npm cache stale 起因の「同 version 判定 skip」を回避。
+  # 過去事例: 0.5.24 が既に入っているマシンで `npm i -g xxx` が 0.5.26 に更新
+  # しない事象があった (npm の "no changes needed" 誤発火)。--force でこの判定を
+  # 飛ばし、@latest で確実に最新版を解決する。
   if present hub-agent; then
     local cur
     cur=$(hub-agent --version 2>/dev/null || echo "unknown")
     color_step "hub-agent (現在 $cur) を最新版にアップデート"
-    npm install -g "$PACKAGE_NAME"
   else
     color_step "$PACKAGE_NAME を install"
-    npm install -g "$PACKAGE_NAME"
   fi
+  retry 3 npm install -g "${PACKAGE_NAME}@latest" --force
+  hash -r 2>/dev/null || true
   color_ok "hub-agent $(hub-agent --version)"
 }
 
@@ -485,11 +537,14 @@ ensure_claude_code() {
     local cur
     cur=$(claude --version 2>/dev/null || echo "unknown")
     color_step "Claude Code (現在 $cur) を最新版にアップデート"
-    npm install -g "$CLAUDE_CODE_PACKAGE" || color_warn "Claude Code upgrade に失敗 (既存版で継続)"
+    # claude は Anthropic 配信。失敗しても既存版で継続 (warning のみ)。
+    retry 2 npm install -g "${CLAUDE_CODE_PACKAGE}@latest" --force \
+      || color_warn "Claude Code upgrade に失敗 (既存版で継続)"
   else
     color_step "$CLAUDE_CODE_PACKAGE を install"
-    npm install -g "$CLAUDE_CODE_PACKAGE"
+    retry 3 npm install -g "${CLAUDE_CODE_PACKAGE}@latest" --force
   fi
+  hash -r 2>/dev/null || true
   if present claude; then
     color_ok "claude $(claude --version 2>/dev/null || echo 'installed')"
   else
@@ -503,20 +558,88 @@ do_enroll() {
     color_warn "  手動で実行: hub-agent enroll <token> --hub-url ${HUB_AGENT_URL:-https://api.hub.cocorograph.com}"
     return 0
   fi
+  local hub_url="${HUB_AGENT_URL:-https://api.hub.cocorograph.com}"
+  # enroll は token が短命の可能性があるため retry は 1 回のみ。
+  # (transient network なら retry が効くが、token 期限切れだと回数を増やしても無駄)
   if [[ -f "$HOME/.hub/agent.json" ]]; then
     color_warn "~/.hub/agent.json が既にあります。--force で上書きします"
-    hub-agent enroll "$HUB_AGENT_TOKEN" --hub-url "${HUB_AGENT_URL:-https://api.hub.cocorograph.com}" --force
+    retry 2 hub-agent enroll "$HUB_AGENT_TOKEN" --hub-url "$hub_url" --force
   else
-    hub-agent enroll "$HUB_AGENT_TOKEN" --hub-url "${HUB_AGENT_URL:-https://api.hub.cocorograph.com}"
+    retry 2 hub-agent enroll "$HUB_AGENT_TOKEN" --hub-url "$hub_url"
+  fi
+
+  # enroll 内部の syncBundle 失敗は warning だけで握りつぶされる (enroll 自体は
+  # success 扱い) ため、ここで bundle 展開状況を verify する。
+  # CLAUDE.md の HUB-AI-RULES マーカーが入っていれば bundle 反映済みと判定。
+  if [[ ! -f "$HOME/.claude/CLAUDE.md" ]] \
+    || ! grep -q "BEGIN HUB-AI-RULES" "$HOME/.claude/CLAUDE.md" 2>/dev/null; then
+    color_warn "Hub AI bundle が ~/.claude に展開されていない可能性。sync-bundle を再試行"
+    if ! retry 2 hub-agent sync-bundle; then
+      color_warn "hub-agent sync-bundle が継続失敗。あとで手動実行してください:"
+      color_warn "  hub-agent sync-bundle"
+    fi
   fi
 }
 
 do_install_service() {
   color_step "OS サービスとして自動起動を登録"
-  hub-agent install-service
+  # install-service は launchctl bootout/bootstrap の transient で初回失敗する
+  # ことがある (既存 unit の残骸 + 同名 bootstrap 競合 等)。retry でカバー。
+  retry 2 hub-agent install-service
   color_ok "install-service 完了。ログ: ~/.hub/agent.log"
 }
 
+# セットアップ最終検証。
+# 「online には見えるがバンドル未配信」「サービス起動失敗」等の半完了状態を
+# 検知してユーザーに次の手を案内する。返り値は 0 (errors > 0 でも継続)。
+verify_setup() {
+  local errors=0
+
+  # 1. hub-agent CLI
+  if present hub-agent; then
+    color_ok "hub-agent CLI: $(hub-agent --version 2>/dev/null || echo 'installed')"
+  else
+    color_err "hub-agent コマンドが PATH に見つかりません"
+    errors=$((errors + 1))
+  fi
+
+  # 2. Claude Code (任意なので warn のみ)
+  if present claude; then
+    color_ok "Claude Code: $(claude --version 2>/dev/null || echo 'installed')"
+  else
+    color_warn "Claude Code (claude) コマンドが見つかりません (cockpit から claude を呼ぶ場合は必要)"
+  fi
+
+  # 3. Hub AI bundle 展開
+  if [[ -f "$HOME/.claude/CLAUDE.md" ]] \
+    && grep -q "BEGIN HUB-AI-RULES" "$HOME/.claude/CLAUDE.md" 2>/dev/null; then
+    color_ok "Hub AI bundle 展開済み (~/.claude/CLAUDE.md)"
+  else
+    color_warn "Hub AI bundle が ~/.claude に展開されていません"
+    color_warn "  手動再同期: hub-agent sync-bundle"
+    errors=$((errors + 1))
+  fi
+
+  # 4. OS サービス起動 (Darwin 限定の確認。Linux は systemctl --user で別途)
+  if [[ "$(uname)" == "Darwin" ]]; then
+    if launchctl list 2>/dev/null | grep -q "co.cocorograph.hub-agent"; then
+      color_ok "launchd service 起動中 (co.cocorograph.hub-agent)"
+    else
+      color_warn "launchd service が見つかりません"
+      color_warn "  手動起動: hub-agent install-service"
+      errors=$((errors + 1))
+    fi
+  fi
+
+  if (( errors > 0 )); then
+    color_warn ""
+    color_warn "${errors} 件の不整合を検出。Hub UI で agent が online でない場合は以下を試してください:"
+    color_warn "  hub-agent restart           # サービス再起動"
+    color_warn "  hub-agent sync-bundle       # bundle 再配信"
+    color_warn "  tail -20 ~/.hub/agent.log   # 詳細ログ"
+  fi
+}
+
 macos_perm_guidance() {
   [[ "$(uname)" != "Darwin" ]] && return 0
   # 現在 PATH 上の node 実体パスを案内に埋め込む（フルディスクアクセス登録時に役立つ）
@@ -544,19 +667,34 @@ EOF
 
 main() {
   color_step "hub-agent ワンライナーセットアップを開始"
+  STEP_TOTAL=10
+  STEP_NUM=0
+
+  step_header "Homebrew"
   ensure_brew
+  step_header "tmux"
   ensure_pkg tmux tmux tmux
+  step_header "Node.js (Active LTS)"
   ensure_node_version
+  step_header "npm global prefix"
   ensure_npm_user_prefix
   # ensure_node_version 直後だと brew link でシェルの command hash がズレている
   # 場合があるため、prefix 設定後にまとめて TLS pre-flight check + 自動 fallback
   # を行う。失敗時はガイダンス付きで exit するので、後段の npm install で TLS
   # エラーを再度浴びる経路はカットされる。
+  step_header "Node TLS pre-flight"
   ensure_node_tls_works
+  step_header "hub-agent install"
   ensure_global_install
+  step_header "Claude Code install"
   ensure_claude_code
+  step_header "enroll + bundle 同期"
   do_enroll
+  step_header "OS サービス化"
   do_install_service
+  step_header "最終検証"
+  verify_setup
+
   echo ""
   color_ok "セットアップ完了。Hub UI で online 表示を確認してください"
   echo "    https://hub.cocorograph.com/user/cockpit/agents"

package/src/pty-bridge.mjs

@@ -28,6 +28,18 @@ const DEFAULT_ROWS = 32
 // に見える (1 フレーム 16.7ms より短いので体感レイテンシは増えない)。
 const DEFAULT_COALESCE_MS = 12
 
+// orphan stream GC 設定。
+// - DEFAULT_GC_INTERVAL_MS: GC スキャン周期 (60s)。短すぎても CPU 負担、長すぎても
+//   pty 枯渇に到達してから掃除されるまでに時間がかかる。1 分は妥当な balance。
+// - DEFAULT_GC_STALE_MS: stream idle 判定の閾値 (10 min)。Cockpit window が
+//   通常使用中は 5s 周期で session.state 等で touch されるので絶対に達しない。
+//   リロード時の切断 (秒〜十数秒) も無傷。何時間も放置された孤児だけ掃除される。
+//   ※ アクティブ stream が「10 分間まったく操作されない」= ユーザー席離れ等。
+//      その場合のみ kill されるが、tmux session 自体は別 process なので作業内容
+//      は無傷、リロードで再 attach できる。
+const DEFAULT_GC_INTERVAL_MS = 60_000
+const DEFAULT_GC_STALE_MS = 10 * 60_000
+
 function resolveBin(name) {
   try {
     return execFileSync("/usr/bin/which", [name], { encoding: "utf-8" }).trim()
@@ -53,7 +65,32 @@ export class PtyBridge extends EventEmitter {
    *     `/bin/sh -c "exec tmux attach -t <sessionName>"`
    * @param {number} [opts.coalesceMs] - pty 出力を coalesce する間隔 (ms)。0 で無効。
    */
-  constructor({ ptyModule, logger, plugins = [], defaultSpawnCommand, coalesceMs } = {}) {
+  constructor({
+    ptyModule,
+    logger,
+    plugins = [],
+    defaultSpawnCommand,
+    coalesceMs,
+    /**
+     * 孤児 stream の GC 設定。
+     *
+     * 背景: 旧設計では WS reconnect / Cockpit window リロード / タブ閉じ等で
+     * `pty.detach` が agent に届かないケースがあり、pty fd が leak していた。
+     * macOS の `kern.tty.ptmx_max` は 511 個でその上限に到達すると新規
+     * 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 されない**。
+     * リロード時の短時間切断 (秒〜十数秒) も `gcStaleMs` (デフォルト 10 分)
+     * 未満なので無傷。何時間も放置された孤児だけ掃除される。
+     *
+     * gcStaleMs を 0 以下にすると GC を無効化する (旧挙動)。テスト・特殊用途向け。
+     */
+    gcIntervalMs,
+    gcStaleMs,
+  } = {}) {
     super()
     if (!ptyModule || typeof ptyModule.spawn !== "function") {
       throw new TypeError("PtyBridge requires { ptyModule: { spawn } }")
@@ -73,6 +110,59 @@ export class PtyBridge extends EventEmitter {
     this.streams = new Map()
     /** @type {Map<string, {buf: string, timer: ReturnType<typeof setTimeout>|null}>} */
     this.coalesceState = new Map()
+
+    // orphan GC 設定。デフォルトは 1 分周期で 10 分間 idle の stream を kill。
+    this.gcIntervalMs = gcIntervalMs ?? DEFAULT_GC_INTERVAL_MS
+    this.gcStaleMs = gcStaleMs ?? DEFAULT_GC_STALE_MS
+    /** @type {Map<string, number>} stream_id → lastSeenAt (ms epoch) */
+    this.lastSeenAt = new Map()
+    /** @type {ReturnType<typeof setInterval>|null} */
+    this._gcTimer = null
+    if (this.gcStaleMs > 0 && this.gcIntervalMs > 0) {
+      this._gcTimer = setInterval(() => this._gcStaleStreams(), this.gcIntervalMs)
+      // unref で Node の event loop を止めない (test 環境で hang しないため)。
+      if (typeof this._gcTimer.unref === "function") this._gcTimer.unref()
+    }
+  }
+
+  /**
+   * 現在時刻を ms epoch で返す。テストで now を差し替えるため override 可能に。
+   * @returns {number}
+   */
+  _now() {
+    return Date.now()
+  }
+
+  /**
+   * stream_id を「最近 browser からアクセスがあった」と record する。
+   * attach / write / resize の各 entry point から呼ぶ。
+   * @param {string} stream_id
+   */
+  _touch(stream_id) {
+    this.lastSeenAt.set(stream_id, this._now())
+  }
+
+  /**
+   * `gcStaleMs` を超えて idle な stream を一括 detach する。
+   *
+   * `_gcTimer` から `gcIntervalMs` 周期で呼ばれる。手動でも呼べる (テスト用)。
+   * @returns {string[]} kill した stream_id 一覧 (debug / test 用)
+   */
+  _gcStaleStreams() {
+    if (!(this.gcStaleMs > 0)) return []
+    const cutoff = this._now() - this.gcStaleMs
+    const killed = []
+    for (const [stream_id, ts] of this.lastSeenAt) {
+      if (ts < cutoff && this.streams.has(stream_id)) {
+        this.logger?.warn(
+          { stream_id, stale_ms: this._now() - ts, gc_stale_ms: this.gcStaleMs },
+          "pty GC: orphaned stream killed",
+        )
+        this.detach({ stream_id })
+        killed.push(stream_id)
+      }
+    }
+    return killed
   }
 
   /**
@@ -134,6 +224,7 @@ export class PtyBridge extends EventEmitter {
     }
 
     this.streams.set(stream_id, pty)
+    this._touch(stream_id)
     this.logger?.info(
       { stream_id, sessionName, command: spec.command, plugin: hookResult?.plugin || null },
       "pty attached",
@@ -164,6 +255,7 @@ export class PtyBridge extends EventEmitter {
       this._flushCoalesce(stream_id)
       this.coalesceState.delete(stream_id)
       this.streams.delete(stream_id)
+      this.lastSeenAt.delete(stream_id)
       this.emit("exit", { stream_id, code: exitCode })
     })
 
@@ -181,6 +273,7 @@ export class PtyBridge extends EventEmitter {
       this.logger?.warn({ stream_id }, "pty.write but stream missing")
       return false
     }
+    this._touch(stream_id)
     pty.write(data)
     return true
   }
@@ -192,6 +285,7 @@ export class PtyBridge extends EventEmitter {
       this.logger?.warn({ stream_id }, "pty.resize but stream missing")
       return false
     }
+    this._touch(stream_id)
     try {
       pty.resize(cols, rows)
       return true
@@ -208,6 +302,9 @@ export class PtyBridge extends EventEmitter {
     // kill 前に残バッファを emit しておく (onExit にも flush はあるが、
     // detach は browser 側都合なので最新を確実に届けたい)。
     this._flushCoalesce(stream_id)
+    // GC tracking もここでクリア。pty.onExit でも消すが、onExit が来る前に
+    // 同じ stream_id が再 attach されると古い lastSeenAt が残るリスクを避ける。
+    this.lastSeenAt.delete(stream_id)
     try {
       pty.kill()
     } catch {
@@ -218,6 +315,10 @@ export class PtyBridge extends EventEmitter {
 
   /** 全 pty を即時 kill (agent shutdown 用)。 */
   shutdown() {
+    if (this._gcTimer) {
+      clearInterval(this._gcTimer)
+      this._gcTimer = null
+    }
     for (const stream_id of Array.from(this.streams.keys())) {
       this.detach({ stream_id })
     }