@cocorograph/hub-agent 0.8.65 → 0.8.67

package/bin/hub-agent.mjs

@@ -38,6 +38,7 @@ import { loadPlugins } from "../src/plugin-loader.mjs"
 import { uninstallPlugin } from "../src/plugin-uninstall.mjs"
 import {
   canSuggestForcedRestart,
+  formatInstallServiceReport,
   installService,
   restartService,
   restartWithPolicy,
@@ -215,16 +216,12 @@ program
   .action(async (opts) => {
     try {
       const r = await installService({ bin: opts.bin })
-      console.log(`installed: ${r.platform} ${r.path}`)
-      console.log(`bin: ${r.bin}`)
-      if (r.platform === "darwin") {
-        console.log(`label: ${r.label}`)
-        console.log("確認: launchctl list | grep co.cocorograph.hub-agent")
-      } else {
-        console.log(`unit: ${r.unit}`)
-        console.log("確認: systemctl --user status hub-agent.service")
+      // 表示と警告の判断は formatInstallServiceReport (テスト可能な純関数) が持つ。
+      // 順序を崩さないよう、種別つきの 1 本の配列をそのまま流す。
+      for (const { stream, text } of formatInstallServiceReport(r)) {
+        if (stream === "warn") console.warn(text)
+        else console.log(text)
       }
-      console.log("ログ: ~/.hub/agent.log")
     } catch (err) {
       console.error(`install-service failed: ${err.message}`)
       process.exit(1)

package/package.json

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

package/scripts/install.sh

@@ -45,6 +45,13 @@ NODE_DEFAULT_BREW_FORMULA="node@24"
 PACKAGE_NAME="@cocorograph/hub-agent"
 CLAUDE_CODE_PACKAGE="@anthropic-ai/claude-code"
 CODEX_PACKAGE="@openai/codex"
+UV_VERSION="0.12.8"
+HUB_PYTHON_MINOR="3.13"
+HUB_VENV_DIR="$HOME/.local/share/hub-venv"
+# Hub Python の依存バージョンを更新するときは、この配列を変更する。
+HUB_PYTHON_PACKAGES=("PyYAML==6.0.3" "Pillow==12.3.0" "openpyxl==3.1.5")
+# HUB_PYTHON_PACKAGES と同じ 3 件を指す。依存を増やすときは両方を更新する。
+HUB_PYTHON_IMPORTS=("yaml" "PIL" "openpyxl")
 
 color_step() { printf "\033[1;34m==> %s\033[0m\n" "$1"; }
 color_ok()   { printf "\033[1;32m✓ %s\033[0m\n" "$1"; }
@@ -598,6 +605,7 @@ ensure_build_tools() {
 ensure_python3() {
   if python3 --version >/dev/null 2>&1; then
     color_ok "$(python3 --version 2>&1)"
+    _check_python3_version
     return 0
   fi
 
@@ -615,12 +623,355 @@ ensure_python3() {
 
   if python3 --version >/dev/null 2>&1; then
     color_ok "$(python3 --version 2>&1)"
+    _check_python3_version
   else
     color_err "python3 の導入後も実行できません"
     exit 1
   fi
 }
 
+_check_python3_version() {
+  local version
+  version="$(python3 -c 'import platform; print(platform.python_version())')" || {
+    color_err "python3 のバージョンを確認できません"
+    exit 1
+  }
+  if python3 -c 'import sys; raise SystemExit(0 if sys.version_info < (3, 9) else 1)'; then
+    color_err "hub の配布物は Python 3.9 以上が必要です（現在: $version）"
+    exit 1
+  fi
+  if python3 -c 'import sys; raise SystemExit(0 if sys.version_info < (3, 11) else 1)'; then
+    color_warn "Python 3.11 未満では一部機能が無効になります（Codex の MCP 承認チェック）。現在: $version"
+  fi
+}
+
+_hub_uv_triple() {
+  local os arch libc="gnu"
+  os="$(uname -s)"
+  arch="$(uname -m)"
+  if [[ "$os" == "Linux" ]] && ldd --version 2>&1 | grep -qi musl; then
+    libc="musl"
+  fi
+  case "$os:$arch" in
+    Darwin:arm64) printf '%s\n' "aarch64-apple-darwin" ;;
+    Darwin:x86_64) printf '%s\n' "x86_64-apple-darwin" ;;
+    Linux:x86_64) printf '%s\n' "x86_64-unknown-linux-$libc" ;;
+    Linux:aarch64|Linux:arm64) printf '%s\n' "aarch64-unknown-linux-$libc" ;;
+    *) color_err "uv が対応していないプラットフォームです: $os $arch"; return 1 ;;
+  esac
+}
+
+_install_hub_uv() (
+  set -e
+  local triple url tmp expected actual uv_src local_bin destination staged=""
+  triple="$(_hub_uv_triple)" || exit 1
+  local_bin="$HOME/.local/bin"
+  destination="$local_bin/uv"
+  mkdir -p "$local_bin"
+  if [[ -e "$destination" || -L "$destination" ]]; then
+    color_err "$destination は uv と名前衝突しています。既存ファイルを退避するか PATH を修正してください"
+    exit 1
+  fi
+  url="https://github.com/astral-sh/uv/releases/download/${UV_VERSION}/uv-${triple}.tar.gz"
+  tmp="$(mktemp -d)"
+  trap 'rm -rf "$tmp"' EXIT
+  staged="$(mktemp "$local_bin/.uv.tmp.XXXXXX")"
+  trap 'rm -rf "$tmp"; if [[ -n "$staged" ]]; then rm -f "$staged"; fi' EXIT
+  trap 'exit 130' INT
+  trap 'exit 143' TERM
+  retry 3 curl -fsSL "$url" -o "$tmp/uv.tar.gz" || exit 1
+  retry 3 curl -fsSL "$url.sha256" -o "$tmp/uv.tar.gz.sha256" || exit 1
+  expected="$(head -1 "$tmp/uv.tar.gz.sha256")"
+  expected="${expected%%[[:space:]]*}"
+  if present shasum; then
+    actual="$(shasum -a 256 "$tmp/uv.tar.gz")"
+  elif present sha256sum; then
+    actual="$(sha256sum "$tmp/uv.tar.gz")"
+  else
+    color_err "sha256 検算コマンド (shasum / sha256sum) がありません"
+    exit 1
+  fi
+  actual="${actual%%[[:space:]]*}"
+  if [[ -z "$expected" || "$actual" != "$expected" ]]; then
+    color_err "uv tarball の sha256 が一致しません"
+    exit 1
+  fi
+  tar -xzf "$tmp/uv.tar.gz" -C "$tmp"
+  uv_src="$(find "$tmp" -type f -name uv | head -1)"
+  [[ -n "$uv_src" ]] || { color_err "uv tarball に uv がありません"; exit 1; }
+  mv "$uv_src" "$staged"
+  chmod +x "$staged"
+  "$staged" --version >/dev/null 2>&1 || { color_err "取得した uv を実行できません"; exit 1; }
+  if [[ -e "$destination" || -L "$destination" ]]; then
+    color_err "$destination は uv と名前衝突しています。既存ファイルを退避するか PATH を修正してください"
+    exit 1
+  fi
+  mv "$staged" "$destination"
+)
+
+_hub_venv_usable() {
+  local venv_dir="${1:-$HUB_VENV_DIR}" python base_prefix version package spec distribution expected
+  python="$venv_dir/bin/python3"
+  [[ -x "$python" ]] || return 1
+  base_prefix="$($python -c 'import sys; print(sys.base_prefix)' 2>/dev/null)" || return 1
+  [[ -e "$base_prefix/bin/python3" ]] || return 1
+  version="$($python -c 'import sys; print(f"{sys.version_info[0]}.{sys.version_info[1]}")' 2>/dev/null)" || return 1
+  [[ "$version" == "$HUB_PYTHON_MINOR" ]] || return 1
+  for package in "${HUB_PYTHON_PACKAGES[@]}"; do
+    distribution="${package%%==*}"
+    expected="${package#*==}"
+    "$python" -c 'import importlib.metadata, sys; raise SystemExit(0 if importlib.metadata.version(sys.argv[1]) == sys.argv[2] else 1)' \
+      "$distribution" "$expected" >/dev/null 2>&1 || return 1
+  done
+  for spec in "${HUB_PYTHON_IMPORTS[@]}"; do
+    "$python" -c 'import importlib, sys; importlib.import_module(sys.argv[1])' "$spec" >/dev/null 2>&1 || return 1
+  done
+}
+
+_build_hub_venv() (
+  set -e
+  local new_dir="$1" built=0
+  trap '(( built == 1 )) || rm -rf "$new_dir"' EXIT
+  trap 'exit 130' INT
+  trap 'exit 143' TERM
+  rm -rf "$new_dir"
+  uv venv --python "$HUB_PYTHON_MINOR" "$new_dir" || exit 1
+  uv pip install --python "$new_dir/bin/python3" --only-binary :all: "${HUB_PYTHON_PACKAGES[@]}" || exit 1
+  _hub_venv_usable "$new_dir" || { color_err "構築した Hub Python venv の検証に失敗しました"; exit 1; }
+  built=1
+)
+
+_acquire_hub_python_lock() {
+  local lock_dir="$1" attempts=0 owner_file token owner_pid
+  owner_file="$lock_dir/owner"
+  # ⚠️ ここで時刻を採らない。`printf -v t '%(%s)T'` は bash 4.2 以降の機能で、macOS 標準の
+  # bash 3.2 では「invalid format character」で失敗する。`set -euo pipefail` の下なので
+  # インストーラ自体がここで止まる（実測。テストの bash は Homebrew の 5.x なので緑になってしまう）。
+  # mkdir lock では「観測 → 回収 → 再取得」の間に別プロセスが取り直した lock を、遅れて来た
+  # 回収者が持ち去れる。回収の rename が保証するのは、同時に回収する複数の勝者が 1 つになる
+  # ことまでで、破壊的操作の直前に所有を再確認しても TOCTOU の窓は消えない。
+  # そのため自動回収は行わず、異常終了後は表示されたディレクトリを人が削除して再実行する。
+  token="$$-${RANDOM:-0}-${RANDOM:-0}"
+  while ! mkdir "$lock_dir" 2>/dev/null; do
+    attempts=$((attempts + 1))
+    if (( attempts >= 50 )); then
+      owner_pid=""
+      if [[ -f "$owner_file" ]]; then
+        {
+          read -r _ || true
+          read -r owner_pid || true
+        } < "$owner_file"
+      fi
+      if [[ "$owner_pid" =~ ^[0-9]+$ ]]; then
+        color_err "Hub Python lock を取得できませんでした: $lock_dir。保持しているプロセス (PID $owner_pid) が動いているか ps -p $owner_pid で確かめ、動いていなければこのディレクトリを削除して再実行してください"
+      else
+        color_err "Hub Python lock を取得できませんでした: $lock_dir。インストーラが走っていないならこのディレクトリを削除して再実行してください"
+      fi
+      return 1
+    fi
+    sleep 0.1
+  done
+  if ! printf '%s\n%s\n' "$token" "$$" > "$owner_file"; then
+    rm -rf "$lock_dir" 2>/dev/null || true
+    return 1
+  fi
+  HUB_PYTHON_LOCK_TOKEN="$token"
+}
+
+_replace_hub_venv() (
+  local new_dir="$1" old_dir="$2" moved_old=0 installed=0
+  cleanup_replacement() {
+    if (( moved_old == 1 && installed == 0 )) && [[ -e "$old_dir" ]] && [[ ! -e "$HUB_VENV_DIR" ]]; then
+      mv "$old_dir" "$HUB_VENV_DIR"
+    fi
+  }
+  trap cleanup_replacement EXIT
+  if [[ -e "$HUB_VENV_DIR" || -L "$HUB_VENV_DIR" ]]; then
+    mv "$HUB_VENV_DIR" "$old_dir" || return 1
+    moved_old=1
+  fi
+  mv "$new_dir" "$HUB_VENV_DIR" || return 1
+  installed=1
+)
+
+_publish_hub_python_wrapper() (
+  local local_bin="$HOME/.local/bin" wrapper="$HOME/.local/bin/hub-python3"
+  local staged content wrapper_content
+  local marker='# hub-agent managed: hub-python3 (hub-agent のインストーラが生成・更新します。手で編集しないでください)'
+  local managed_line="exec \"$HUB_VENV_DIR/bin/python3\" \"\$@\""
+  mkdir -p "$local_bin"
+  if [[ -L "$wrapper" ]]; then
+    color_err "$wrapper は名前衝突しています。既存 symlink を退避するか PATH を修正してください"
+    return 1
+  fi
+  staged="$(mktemp "$local_bin/.hub-python3.tmp.XXXXXX")" || return 1
+  trap 'rm -f "$staged"' EXIT
+  printf '%s\n' '#!/usr/bin/env sh' "$marker" "$managed_line" > "$staged" || return 1
+  chmod +x "$staged" || return 1
+  # ⚠️ `$(<file)` は末尾の改行を落とすので、この比較は「末尾改行の数の違い」と「最終行の改行の
+  # 有無」を区別しない。内容のある行が 1 行でも違えば不一致になり、末尾改行だけが違う wrapper を
+  # 上書きしても失われる情報は無いので許容する。サンドボックスに cat / stat / wc / cmp が無く、
+  # バイト単位の比較には別の機構が要るため、そのために機構を足すことはしない。
+  # 以前付けていた sentinel の "x" は末尾改行の差を捉えているように見えて実際は効いていなかった
+  # （実測: `$(<a)x` は "a\n" と "a\n\n\n" と "a" のすべてで同じ値になる）ので外した。
+  content="$(<"$staged")"
+  [[ "$content" == $'#!/usr/bin/env sh\n'"$marker"$'\n'"$managed_line" ]] || return 1
+  _hub_python_wrapper_is_managed() {
+    [[ -f "$wrapper" && ! -L "$wrapper" ]] || return 1
+    wrapper_content="$(<"$wrapper")"
+    [[ "$wrapper_content" == "$content" ]] || return 1
+    # 未公開ブランチにしか存在しなかった marker なしの旧形は受け入れない。将来内容を変える版では
+    # marker で識別し、既知の旧内容を完全一致で列挙する。パスのワイルドカード許可には戻さない。
+    # marker をコピーした同一ユーザーの別 wrapper も管理物とみなす。脅威モデルは攻撃者ではなく、
+    # 同一ユーザーによる並行実行と中断であるため、このなりすまし耐性は担保しない。
+  }
+  if [[ -e "$wrapper" ]] && ! _hub_python_wrapper_is_managed; then
+    color_err "$wrapper は名前衝突しています。既存ファイルを退避するか PATH を修正してください"
+    return 1
+  fi
+  if [[ -L "$wrapper" ]] || { [[ -e "$wrapper" ]] && ! _hub_python_wrapper_is_managed; }; then
+    color_err "$wrapper は公開直前に名前衝突しました。既存ファイルを退避するか PATH を修正してください"
+    return 1
+  fi
+  mv "$staged" "$wrapper" || return 1
+)
+
+# lock がまだ自分のものかを確かめる。これは相互排除ではなく best-effort の検出であり、確認と
+# 操作の間の TOCTOU の窓は残る。自動回収の削除後に自分の lock を失うのは、人が lock
+# ディレクトリを削除して別のインストーラを起動した場合だけなので、そのとき黙って並行実行しない
+# ために破壊的操作の直前で検出する。
+_hub_python_lock_is_mine() {
+  local lock_dir="$1" want="$2" owner_token=""
+  [[ -n "$want" && -f "$lock_dir/owner" ]] || return 1
+  read -r owner_token < "$lock_dir/owner" || true
+  [[ "$owner_token" == "$want" ]]
+}
+
+_hub_python_wrapper_verified() {
+  # ⚠️ realpath(sys.executable) で比較しないこと。venv の bin/python3 は土台 interpreter への
+  # symlink なので、realpath は venv でも素の土台でも同じ値に解決される（実測）。それでは
+  # 「site-packages を持たない素の uv interpreter を指す wrapper」を成功扱いにしてしまう。
+  # 識別に使えるのは sys.prefix（venv 自身のパス）。
+  local expected_prefix actual_prefix spec
+  expected_prefix="$(cd "$HUB_VENV_DIR" 2>/dev/null && pwd -P)" || expected_prefix=""
+  actual_prefix="$(hub-python3 -c 'import os, sys; print(os.path.realpath(sys.prefix))' 2>/dev/null)" || actual_prefix=""
+  if [[ -z "$expected_prefix" || "$actual_prefix" != "$expected_prefix" ]]; then
+    color_err "hub-python3 が Hub Python venv を指していません (expected prefix: ${expected_prefix:-unknown}, actual: ${actual_prefix:-unknown})"
+    return 1
+  fi
+  # 版一致だけでは wheel の破損を見逃すため、wrapper 経由で実際に import できることまで確認する。
+  # ⚠️ この import 検査は `_hub_venv_usable` の import 検査と同じ interpreter を通るため重複しており、
+  # 独立した回帰テストは無い（wrapper 側だけを失敗させる状態を作れない）。担保は上の prefix 比較で、
+  # ここは公開後の wrapper 経路を一度通す念のための確認だと理解して読むこと。
+  for spec in "${HUB_PYTHON_IMPORTS[@]}"; do
+    if ! hub-python3 -c 'import importlib, sys; importlib.import_module(sys.argv[1])' "$spec" >/dev/null 2>&1; then
+      color_err "hub-python3 経由で $spec を import できません"
+      return 1
+    fi
+  done
+  color_ok "hub-python3 が Hub Python venv を指すことを確認"
+}
+
+_finalize_hub_python() (
+  # 退避先は lock token ごとの実行固有名にし、他実行の退避物と削除対象を分離する。
+  local new_dir="$1" old_dir="" leftover="" found_leftover=0
+  local lock_dir="${HUB_VENV_DIR}.lock" lock_token="" owner_token=""
+  trap 'rm -rf "$new_dir"; owner_token=""; if [[ -f "$lock_dir/owner" ]]; then read -r owner_token < "$lock_dir/owner" || true; fi; if [[ -n "$lock_token" && "$owner_token" == "$lock_token" ]]; then rm -rf "$lock_dir"; fi' EXIT
+  trap 'exit 130' INT
+  trap 'exit 143' TERM
+  _acquire_hub_python_lock "$lock_dir" || exit 1
+  lock_token="$HUB_PYTHON_LOCK_TOKEN"
+  old_dir="${HUB_VENV_DIR}.old.${lock_token}"
+  if _hub_venv_usable; then
+    color_ok "Hub Python venv は利用可能 ($HUB_VENV_DIR)"
+  elif [[ -n "$new_dir" ]]; then
+    if ! _hub_python_lock_is_mine "$lock_dir" "$lock_token"; then
+      color_err "Hub Python lock を他のインストーラに引き継がれたため差し替えを中止しました: $lock_dir"
+      exit 1
+    fi
+    # 残骸を別名で溜めず、stale lock と同様に手動復旧へ統一する。
+    # ⚠️ ここへ来るのは公開先が使えないと判定した場合なので、残骸は「直前まで使えていた venv」で
+    # ある可能性が高い。削除だけを案内せず、戻す選択肢を先に示す。
+    for leftover in "${HUB_VENV_DIR}".old*; do
+      if [[ -e "$leftover" || -L "$leftover" ]]; then
+        color_err "退避先が既に存在します: $leftover"
+        found_leftover=1
+      fi
+    done
+    if (( found_leftover == 1 )); then
+      color_err "前回の中断が残っている可能性があります。直前まで使えていた venv かもしれません。中身を確認して $HUB_VENV_DIR へ手で入れ替えるか、不要なら削除してから再実行してください"
+      exit 1
+    fi
+    _replace_hub_venv "$new_dir" "$old_dir" || exit 1
+    color_ok "Hub Python venv を構築 ($HUB_VENV_DIR)"
+  else
+    color_err "Hub Python venv の再構築結果がありません"
+    exit 1
+  fi
+  if ! _hub_python_lock_is_mine "$lock_dir" "$lock_token"; then
+    color_err "Hub Python lock を他のインストーラに引き継がれたため wrapper の公開を中止しました: $lock_dir"
+    exit 1
+  fi
+  _publish_hub_python_wrapper || exit 1
+  if ! _hub_python_wrapper_verified; then
+    if [[ -e "$old_dir" || -L "$old_dir" ]]; then
+      color_err "公開後の検証に失敗しました。公開先 $HUB_VENV_DIR は変更していません。直前まで使えていた venv は $old_dir にあります。中身を確認して手で入れ替えるか、$old_dir を削除してから再実行してください"
+    else
+      color_err "公開後の検証に失敗しました。公開先 $HUB_VENV_DIR は変更していません。手で確認してください"
+    fi
+    exit 1
+  fi
+  # 公開後の最終検証に成功してから、lock を保持したまま実行固有名の退避物を削除する。
+  # 差し替えを行わなかった実行ではこのパスは存在せず、他実行が残した退避物は削除しない。
+  if ! rm -rf "$old_dir" 2>/dev/null; then
+    color_warn "元の venv を削除できませんでした: $old_dir。中身を確認して手動で削除してください"
+  fi
+)
+
+ensure_hub_python() {
+  local local_bin="$HOME/.local/bin" uv_path
+  export PATH="$PATH:$local_bin"
+  hash -r 2>/dev/null || true
+  if present uv; then
+    uv_path="$(command -v uv)"
+    uv_path="$(cd "$(dirname "$uv_path")" && pwd -P)/$(basename "$uv_path")"
+    if ! uv --version >/dev/null 2>&1 || ! uv venv --help >/dev/null 2>&1 \
+      || ! uv pip --help >/dev/null 2>&1 || ! uv python --help >/dev/null 2>&1; then
+      color_err "発見した uv を利用できません: $uv_path（上書きせず停止します）"
+      exit 1
+    fi
+    color_ok "uv already installed ($uv_path)"
+  else
+    _install_hub_uv || exit 1
+    color_ok "uv $UV_VERSION を $local_bin に導入"
+  fi
+  persist_profile_snippet 'export PATH="$PATH:$HOME/.local/bin"' "~/.local/bin PATH" \
+    "# >>> hub-agent: local-bin PATH (Hub Python) >>>" "# <<< hub-agent: local-bin PATH <<<" \
+    "$HOME/.zprofile" "$(bash_login_profile)" || exit 1
+
+  retry 3 uv python install "$HUB_PYTHON_MINOR" || exit 1
+  if _hub_venv_usable; then
+    _finalize_hub_python "" || exit 1
+  else
+    # ⚠️ 構築成功から finalize の trap 設置までの中断で未公開の .new が残らないよう、
+    # 構築と finalize を同じ cleanup スコープに入れる。差し替え成功後は .new のパスが
+    # 消えているので、この trap の rm は no-op になる。
+    (
+      new_dir="${HUB_VENV_DIR}.new.$$"
+      trap 'rm -rf "$new_dir"' EXIT
+      trap 'exit 130' INT
+      trap 'exit 143' TERM
+      _build_hub_venv "$new_dir" || exit 1
+      _finalize_hub_python "$new_dir" || exit 1
+    ) || exit 1
+  fi
+  # 公開後の検証成功後にだけ、Hub Python を指す profile を更新する。
+  export HUB_AI_PYTHON="$HUB_VENV_DIR/bin/python3"
+  persist_profile_snippet "export HUB_AI_PYTHON=\"$HUB_VENV_DIR/bin/python3\"" "HUB_AI_PYTHON" \
+    "# >>> hub-agent: HUB_AI_PYTHON >>>" "# <<< hub-agent: HUB_AI_PYTHON <<<" \
+    "$HOME/.zprofile" "$(bash_login_profile)" || exit 1
+}
+
 # timeout を保証する（補助コマンド。AI セッションの Bash やスクリプトが使うが、
 # hub-agent の常駐動作には必須ではないため、導入失敗は警告して継続する。
 # 必須ランタイムの python3 とは契約を分けている）。
@@ -996,8 +1347,11 @@ verify_setup() {
   done < <(_hub_target_clis)
 
   # 4. OS サービス起動 (Darwin 限定の確認。Linux は systemctl --user で別途)
+  # ⚠️ 判定は `launchctl print` で行う。install-service 側が登録の出現を待つのに使う
+  # 道具と揃えるため (src/service-install.mjs の waitUntilBootedIn)。`launchctl list | grep`
+  # に戻すと、待つ側と確認する側で別の状態を見ることになり誤検知が復活する。
   if [[ "$(uname)" == "Darwin" ]]; then
-    if launchctl list 2>/dev/null | grep -q "co.cocorograph.hub-agent"; then
+    if launchctl print "gui/$(id -u)/co.cocorograph.hub-agent" >/dev/null 2>&1; then
       color_ok "launchd service 起動中 (co.cocorograph.hub-agent)"
     else
       color_warn "launchd service が見つかりません"
@@ -1042,7 +1396,7 @@ EOF
 
 main() {
   color_step "hub-agent ワンライナーセットアップを開始"
-  STEP_TOTAL=15
+  STEP_TOTAL=16
   STEP_NUM=0
 
   step_header "Homebrew"
@@ -1055,6 +1409,8 @@ main() {
   ensure_build_tools
   step_header "Python 3"
   ensure_python3
+  step_header "Hub Python (uv / shared venv)"
+  ensure_hub_python
   step_header "GNU coreutils (timeout)"
   ensure_timeout
   step_header "npm global prefix"

package/src/service-install.mjs

@@ -154,6 +154,29 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
  * @returns {Promise<boolean>} 消えたら true / timeout なら false
  */
 async function waitUntilBootedOut(uid, opts = {}) {
+  // 非 0 = 登録に存在しない = bootout 完了
+  return waitForRegistration(uid, false, opts)
+}
+
+/**
+ * launchd の登録状態が `want` になるまで polling する。`waitUntilBootedOut` /
+ * `waitUntilBootedIn` の共通実装。
+ *
+ * ⚠️ 判定は `launchctl print` の終了コードで行う。`launchctl list | grep` は同じ状態を
+ * 別の道具で見ることになり、待つ側と確認する側がずれると誤検知が復活するため、
+ * hub-agent 側と `scripts/install.sh` の verify_setup で道具を揃えている。
+ *
+ * ⚠️ 成功条件は `(status === 0) === want` の 1 箇所だけで表す。`status` は spawn 自体が
+ * 失敗すると `null` になり得るので、「0 か否か」に正規化してから比較する
+ * (bootout 待ちでは null は「登録に存在しない」＝完了、bootin 待ちでは「まだ現れない」
+ *  ＝継続、という従来の挙動がそのまま保たれる)。
+ *
+ * @param {number} uid
+ * @param {boolean} want true = 登録に現れるまで待つ / false = 消えるまで待つ
+ * @param {{ timeoutMs?: number, intervalMs?: number, spawn?: Function, sleep?: Function, now?: Function }} [opts]
+ * @returns {Promise<boolean>} 期待状態になったら true / timeout なら false
+ */
+async function waitForRegistration(uid, want, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 5000
   const intervalMs = opts.intervalMs ?? 200
   const spawn = opts.spawn ?? spawnSync
@@ -164,13 +187,33 @@ async function waitUntilBootedOut(uid, opts = {}) {
     const r = spawn("launchctl", ["print", `gui/${uid}/${PLIST_LABEL}`], {
       stdio: "ignore",
     })
-    // 非 0 = 登録に存在しない = bootout 完了
-    if (r.status !== 0) return true
+    if ((r.status === 0) === want) return true
     await sleepFn(intervalMs)
   }
   return false
 }
 
+/**
+ * `launchctl bootstrap` / `kickstart -k` の直後は、launchd 側の登録が見えるまでに
+ * わずかな遅れがある。install-service がそこで返ってしまうと、直後に登録を確認する
+ * 呼び出し側 (`scripts/install.sh` の verify_setup 等) が「サービスが見つからない」と
+ * 誤検知する。本関数は対象 service が launchd の登録に現れるまで polling して待つ。
+ * `waitUntilBootedOut` の対称形。
+ *
+ * 判定手段の統一 (`launchctl print`) は `waitForRegistration` の注意書きを参照。
+ *
+ * (2026-09-09: ワンライナー完走時に毎回「launchd service が見つかりません」が出ていた
+ *  誤検知の修正。install-service は成功しており、agent も起動していた)
+ *
+ * @param {number} uid
+ * @param {{ timeoutMs?: number, intervalMs?: number }} [opts]
+ * @returns {Promise<boolean>} 現れたら true / timeout なら false
+ */
+async function waitUntilBootedIn(uid, opts = {}) {
+  // 0 = 登録に存在する
+  return waitForRegistration(uid, true, opts)
+}
+
 /**
  * bootout 後の bootstrap を、過渡的失敗 (旧サービスの抜け残り等) に対して
  * リトライする。`run` と違い最終的に失敗したときだけ throw する。
@@ -257,7 +300,52 @@ function detectHubAgentBin() {
   return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "bin", "hub-agent.mjs")
 }
 
-export async function installService({ bin } = {}) {
+/**
+ * darwin の launchd 登録シーケンス:
+ * bootout → (登録が消えるまで待機) → bootstrap (リトライ) → kickstart → (登録が現れるまで待機)。
+ *
+ * - bootout は非同期なので、待たずに bootstrap するとレースで失敗し offline 化する
+ *   (2026-05-30 の事故)。`waitUntilBootedOut` で確実に抜けてから bootstrap する。
+ * - kickstart は「既に走っている daemon を再起動」する用途。bootstrap + RunAtLoad で
+ *   既に起動済みのことがあり、その場合 kickstart 失敗は致命的でないので throw しない。
+ * - kickstart もまた launchd 側の登録が見えるまで待たない。ここで待たずに返すと、直後に
+ *   登録を確認する呼び出し側 (`scripts/install.sh` の verify_setup 等) が誤検知する
+ *   (2026-09-09 の誤検知)。現れなかった場合も throw しない: bootstrap は成功しているので
+ *   致命ではなく、判断は呼び出し側の確認へ委ねる。
+ *   ⚠️ ただし「確認できなかった」事実は捨てない。非 0 で終わると `scripts/install.sh` の
+ *   `retry 2 hub-agent install-service` が再インストール + 再起動を走らせてしまうので、
+ *   exit code は変えず `registered` で返し、CLI 側は警告だけ出す。
+ *
+ * ⚠️ この順序をソース文字列の走査で固定するのは**やめた** (2026-09-09 cross-review 3 巡目)。
+ * コメント化・別オブジェクトへの退避など、文字列一致では追い切れない後退が巡ごとに出たため、
+ * 依存を差し替えて**実際に順序と返り値を確認できる**形へ切り出してある。同ファイルの
+ * `restartWithPolicy` と同じ考え方。`deps` は本番では既定値のまま使う。
+ *
+ * @param {{uid: number, dest: string, bin: string}} target
+ * @param {{spawn?: Function, bootedOut?: Function, bootstrap?: Function, bootedIn?: Function}} [deps]
+ */
+export async function activateDarwinService({ uid, dest, bin }, deps = {}) {
+  const spawn = deps.spawn ?? spawnSync
+  const bootedOut = deps.bootedOut ?? waitUntilBootedOut
+  const bootstrap = deps.bootstrap ?? bootstrapWithRetry
+  const bootedIn = deps.bootedIn ?? waitUntilBootedIn
+
+  spawn("launchctl", ["bootout", `gui/${uid}`, dest], { stdio: "ignore" })
+  await bootedOut(uid)
+  await bootstrap(uid, dest)
+  spawn("launchctl", ["kickstart", "-k", `gui/${uid}/${PLIST_LABEL}`], {
+    stdio: "ignore",
+  })
+  const registered = await bootedIn(uid)
+  return { platform: "darwin", path: dest, label: PLIST_LABEL, bin, registered }
+}
+
+/**
+ * @param {{bin?: string, activate?: Function}} [opts]
+ *   `activate` は darwin の launchd 登録シーケンス。テストから差し替えるための口で、
+ *   本番では既定 (`activateDarwinService`) のまま使う。
+ */
+export async function installService({ bin, activate = activateDarwinService } = {}) {
   const hubAgentBin = bin || detectHubAgentBin()
   await ensureLogFile()
 
@@ -269,18 +357,7 @@ export async function installService({ bin } = {}) {
     await fs.writeFile(dest, expanded, { mode: 0o644 })
 
     const uid = ensureUnixUid()
-    // 既存ロード解除 → (登録が消えるまで待機) → bootstrap (リトライ) → kickstart。
-    // bootout は非同期なので待たずに bootstrap するとレースで失敗し offline 化する
-    // (2026-05-30 の事故)。waitUntilBootedOut で確実に抜けてから bootstrap する。
-    spawnSync("launchctl", ["bootout", `gui/${uid}`, dest], { stdio: "ignore" })
-    await waitUntilBootedOut(uid)
-    await bootstrapWithRetry(uid, dest)
-    // kickstart は「既に走っている daemon を再起動」する用途。bootstrap + RunAtLoad で
-    // 既に起動済みのことがあり、その場合 kickstart 失敗は致命的でないので throw しない。
-    spawnSync("launchctl", ["kickstart", "-k", `gui/${uid}/${PLIST_LABEL}`], {
-      stdio: "ignore",
-    })
-    return { platform: "darwin", path: dest, label: PLIST_LABEL, bin: hubAgentBin }
+    return activate({ uid, dest, bin: hubAgentBin })
   }
 
   if (process.platform === "linux") {
@@ -389,6 +466,50 @@ export async function restartWithPolicy({
   return { mode: "deferred", result: await deferredRestart(), service }
 }
 
+/**
+ * install-service の結果を CLI 表示へ変換する。`restartWithPolicy` と同じく、
+ * CLI 側の判断をテスト可能な純関数へ切り出したもの (bin/hub-agent.mjs から使う)。
+ *
+ * ⚠️ 確認コマンドは launchd の登録を待つ側 (`waitForRegistration`) と
+ * `scripts/install.sh` の verify_setup に揃える。`launchctl list | grep` へ戻すと、
+ * 同じ状態を 3 箇所が別々の道具で見ることになり、誤検知が復活する。
+ *
+ * ⚠️ 警告は `registered === false` のときだけ。bootstrap 自体は成功しているので
+ * exit code は変えない (非 0 にすると `scripts/install.sh` の `retry 2` が
+ * 再インストール + 再起動を走らせてしまう)。linux は登録待ちを持たず `registered` を
+ * 返さないので、`undefined` で警告しないこと。
+ *
+ * @param {{platform: string, path: string, bin: string, label?: string, unit?: string, registered?: boolean}} result
+ * @returns {{stream: 'log'|'warn', text: string}[]} 出力すべき行を順序どおりに
+ */
+export function formatInstallServiceReport(result) {
+  const out = [
+    { stream: "log", text: `installed: ${result.platform} ${result.path}` },
+    { stream: "log", text: `bin: ${result.bin}` },
+  ]
+  if (result.platform === "darwin") {
+    out.push({ stream: "log", text: `label: ${result.label}` })
+    out.push({
+      stream: "log",
+      text: "確認: launchctl print gui/$(id -u)/co.cocorograph.hub-agent",
+    })
+    if (result.registered === false) {
+      // ⚠️ 警告は確認コマンドの直後に置く (読む人が対処法とセットで見るため)。
+      // 種別つきの 1 本の配列で返すのは、この順序を stdout / stderr の分離と
+      // 両立させるため。呼び出し側で 2 本のリストへ分けると順序が崩れる。
+      out.push({
+        stream: "warn",
+        text: "warn: launchd への登録を確認できませんでした (待機 timeout)。上のコマンドで確認してください",
+      })
+    }
+  } else {
+    out.push({ stream: "log", text: `unit: ${result.unit}` })
+    out.push({ stream: "log", text: "確認: systemctl --user status hub-agent.service" })
+  }
+  out.push({ stream: "log", text: "ログ: ~/.hub/agent.log" })
+  return out
+}
+
 export async function uninstallService() {
   if (process.platform === "darwin") {
     const uid = ensureUnixUid()
@@ -498,6 +619,10 @@ export const _internal = {
   linuxUnitPath,
   repoTemplatesDir,
   waitUntilBootedOut,
+  waitUntilBootedIn,
+  waitForRegistration,
+  formatInstallServiceReport,
+  activateDarwinService,
   bootstrapWithRetry,
   currentUsername,
   enableLinger,