@cocorograph/hub-agent 0.8.57 → 0.8.59

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.57",
+  "version": "0.8.59",
   "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[@]}"
 }
 
 # =============================================================================
@@ -544,6 +580,120 @@ 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 をインストール"
+  if [[ "$(uname)" == "Darwin" ]]; then
+    # macOS で python3 が動かないのは、ほぼ Xcode CLT 未導入（/usr/bin/python3 がスタブ）。
+    # brew 経路が失敗したら、set -e で黙って落ちる前に実際の復旧手順を出す。
+    if ! retry 3 brew install python; then
+      color_err "python3 を導入できません。\`xcode-select --install\` を実行してから再実行してください"
+      exit 1
+    fi
+  elif present apt-get; then
+    retry 3 sudo apt-get update -y
+    retry 3 sudo apt-get install -y python3
+  elif present dnf; then
+    retry 3 sudo dnf install -y python3
+  elif present pacman; then
+    retry 3 sudo pacman -S --noconfirm python
+  else
+    color_err "対応するパッケージマネージャ (brew/apt/dnf/pacman) が見つかりません。python3 を手動で install してください"
+    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] 範囲内 → 現状維持（ユーザーの環境を尊重）
@@ -622,6 +772,30 @@ ensure_claude_code() {
   fi
 }
 
+# Codex CLI を同梱でセットアップ。hub-agent 自体の動作には必須ではないため、
+# 新規導入・upgrade とも失敗時は警告してセットアップを継続する。
+ensure_codex() {
+  if present codex; then
+    local cur
+    cur=$(codex --version 2>/dev/null </dev/null || echo "unknown")
+    color_step "Codex CLI (現在 $cur) を最新版にアップデート"
+    retry 2 npm install -g "${CODEX_PACKAGE}@latest" --force \
+      || color_warn "Codex CLI upgrade に失敗 (既存版で継続)"
+  else
+    color_step "$CODEX_PACKAGE を install"
+    if ! retry 3 npm install -g "${CODEX_PACKAGE}@latest" --force; then
+      color_warn "Codex CLI の導入に失敗しました。Codex チャット / 委譲 / 画像生成は使えません"
+      color_warn "  手動で実行: npm install -g @openai/codex@latest"
+    fi
+  fi
+  hash -r 2>/dev/null || true
+  if present codex; then
+    color_ok "codex $(codex --version 2>/dev/null </dev/null || echo 'installed')"
+  else
+    color_warn "codex コマンドが PATH に見つかりません。新規シェルで再確認してください"
+  fi
+}
+
 do_enroll() {
   if [[ -z "${HUB_AGENT_TOKEN:-}" ]]; then
     color_warn "HUB_AGENT_TOKEN が未設定。enroll は skip します"
@@ -767,6 +941,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 +1023,7 @@ EOF
 
 main() {
   color_step "hub-agent ワンライナーセットアップを開始"
-  STEP_TOTAL=11
+  STEP_TOTAL=15
   STEP_NUM=0
 
   step_header "Homebrew"
@@ -842,6 +1034,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 +1050,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 +1067,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/main.mjs

@@ -520,9 +520,11 @@ export async function syncTmuxCodexEnv(profile, log) {
  * bundle hooks (cockpit_permission_bridge 等) を反映させる。
  *
  * 新規プロファイル追加 (profile.add) 直後に呼ぶ。provisionProfile は
- * `~/.claude/settings.json` を新プロファイルへコピーするが、コピー元が古い / setup 未走の
- * タイミングだと新プロファイルにフックが欠けうる。setup_hub_ai は全プロファイル対応 (案1)
- * なので 1 回叩けば新プロファイルの初回セッションでもフックが揃う。
+ * `~/.claude/settings.json` への symlink を新プロファイルへ張る (コピーではない) ので、
+ * 正本が最新ならフックは自動的に揃う。ただし正本自体が古い / setup 未走のタイミングだと
+ * 新プロファイルの初回セッションでもフックが欠けうるため、1 回叩いて正本を最新化する。
+ * 旧版がコピーで置いた実体 settings.json が残るプロファイルにも、setup_hub_ai は
+ * 全プロファイル対応 (案1) なので同じ 1 回で反映される。
  *
  * 失敗・未 setup 環境 (スクリプト不在 / python3 無し) でも **例外を投げない**。detached +
  * stdio ignore で daemon をブロックしない。session_start.py の auto-update と同じ

package/src/profiles.mjs

@@ -4,8 +4,12 @@
  * 1 台のマシンで複数の Claude アカウント (例: 個人 Max / チーム) を `CLAUDE_CONFIG_DIR`
  * で切り替えて使うための仕組み。各プロファイルは独立した config ディレクトリを持ち、
  * 認証 (`.credentials.json` / Keychain) と `.claude.json` をアカウント別に保持する。一方で
- * skills / agents / commands / scripts / hooks / CLAUDE.md は symlink で共有し、
- * settings.json はコピーで共有する (provisionProfile が面倒を見る)。
+ * skills / agents / commands / scripts / hooks / CLAUDE.md / settings.json は symlink で
+ * 共有する (provisionProfile が面倒を見る)。settings.json はプロファイル間で共有扱いとし、
+ * アカウント別の上書きはサポートしない — つまり forceLoginOrgUUID / apiKeyHelper /
+ * env.ANTHROPIC_* のようなアカウント固有の値を settings.json に置くと全プロファイルへ効く
+ * (経緯と却下案は Hub ナレッジ
+ * `ナレッジ/Cockpit/自動コンパクションとPreCompactフック` の「プロファイル間の設定ドリフト」節)。
  *
  * 会話履歴 (`projects/`) は **既定 `~/.claude/projects` に集約して全プロファイルで共有する**
  * (ensureSharedProjects が `<configDir>/projects` を既定への symlink にする)。同じ作業
@@ -312,7 +316,7 @@ function nextNumericId(profiles) {
 
 /**
  * プロファイルを新規追加する (連番 id・中立パス `~/.claude-<n>`)。
- * ディレクトリ整備 (symlink / settings コピー) は provisionProfile が行う。
+ * ディレクトリ整備 (共有資産の symlink) は provisionProfile が行う。
  * 追加後もログインは未了 (ユーザーが端末で `/login` する必要がある)。
  *
  * @param {{label?: string}} [opts]
@@ -383,7 +387,8 @@ export async function hasFileCredentials(configDir) {
   }
 }
 
-/** 既定プロファイルから共有 symlink する資産 (アプリが書き込まない読み取り中心)。 */
+/** 既定プロファイルから共有 symlink する資産。settings.json の書き手 (Claude Code 本体 /
+ *  setup_hub_ai.py の hooks auto-merge) は symlink 越しに正本 `~/.claude/settings.json` を更新する。 */
 export const SHARED_SYMLINK_ITEMS = [
   "agents",
   "skills",
@@ -391,11 +396,9 @@ export const SHARED_SYMLINK_ITEMS = [
   "scripts",
   "hooks",
   "CLAUDE.md",
+  "settings.json",
 ]
 
-/** コピーで共有する資産 (アプリが書き換えるため symlink 不可)。 */
-export const SHARED_COPY_ITEMS = ["settings.json"]
-
 /**
  * 会話履歴 (`projects/`) を既定 `~/.claude/projects` に集約・共有する。
  *
@@ -459,18 +462,17 @@ export async function ensureSharedProjects(configDir) {
 
 /**
  * プロファイルディレクトリを整備する。
- *  - 共有 symlink 資産: 既定 `~/.claude/<item>` への絶対 symlink を張る (既存・実体があれば触らない)。
- *  - 共有コピー資産: 既定からコピー (プロファイル側に未存在のときだけ)。
+ *  - 共有 symlink 資産: 既定 `~/.claude/<item>` への絶対 symlink を張る。既存 (symlink でも
+ *    実体でも) があれば触らない — 旧版がコピーで置いた settings.json も同じ規則で残る。
  * 認証・履歴・`.claude.json` には一切触れない (アカウント固有のため)。
  *
  * @param {string} configDir - 対象プロファイルの config ディレクトリ絶対パス
- * @returns {Promise<{linked: string[], copied: string[], skipped: string[]}>}
+ * @returns {Promise<{linked: string[], skipped: string[]}>}
  */
 export async function provisionProfile(configDir) {
   const base = defaultConfigDir()
   await fs.mkdir(configDir, { recursive: true, mode: 0o700 })
   const linked = []
-  const copied = []
   const skipped = []
 
   for (const item of SHARED_SYMLINK_ITEMS) {
@@ -479,8 +481,19 @@ export async function provisionProfile(configDir) {
     try {
       await fs.access(src)
     } catch {
-      skipped.push(`${item}(元無し)`)
-      continue
+      // settings.json だけは正本を空 JSON で作ってから張る。ここで skip すると、直後の
+      // setup_hub_ai (hooks auto-merge) がプロファイル側に実体を作り、以後 provisionProfile が
+      // 「既存」として触らないため、コピー時代と同じドリフトが復活する。
+      // 既定側が壊れた symlink のときは書き込み先が分からないので触らない。
+      if (item !== "settings.json" || (await isBrokenSymlink(src))) {
+        skipped.push(`${item}(元無し)`)
+        continue
+      }
+      // 既定ディレクトリ自体が無い端末 (Claude Code 未起動) でも正本を作れるようにする。
+      await fs.mkdir(base, { recursive: true, mode: 0o700 })
+      await fs.writeFile(src, "{}\n", { flag: "wx" }).catch((err) => {
+        if (err?.code !== "EEXIST") throw err
+      })
     }
     // dst が既に存在 (symlink/実体) なら触らない。
     let exists = false
@@ -498,28 +511,6 @@ export async function provisionProfile(configDir) {
     linked.push(item)
   }
 
-  for (const item of SHARED_COPY_ITEMS) {
-    const src = path.join(base, item)
-    const dst = path.join(configDir, item)
-    let dstExists = false
-    try {
-      await fs.lstat(dst)
-      dstExists = true
-    } catch {
-      /* not exists */
-    }
-    if (dstExists) {
-      skipped.push(`${item}(既存)`)
-      continue
-    }
-    try {
-      await fs.copyFile(src, dst)
-      copied.push(item)
-    } catch {
-      skipped.push(`${item}(元無し)`)
-    }
-  }
-
   // 会話履歴は既定 ~/.claude/projects へ集約して共有する (アカウント間で会話
   // コンテキストを引き継げるようにするため)。新規は素直に symlink、既存実体は
   // 無損失マージしてから symlink 化する。
@@ -531,7 +522,16 @@ export async function provisionProfile(configDir) {
     skipped.push(`projects(失敗:${err?.code || err?.message || "error"})`)
   }
 
-  return { linked, copied, skipped }
+  return { linked, skipped }
+}
+
+/** `p` が lstat できるのに access できない (= リンク先を失った symlink) なら true。 */
+async function isBrokenSymlink(p) {
+  try {
+    return (await fs.lstat(p)).isSymbolicLink()
+  } catch {
+    return false
+  }
 }
 
 /** テスト用: モジュールキャッシュを破棄する。 */