@cocorograph/hub-agent 0.7.67 → 0.7.69

package/src/hub-bundle.mjs

@@ -16,11 +16,11 @@
  *
  * 仕様書: ナレッジ/インフラ/cockpit-hub-hosted-integration-spec (id=6080)
  */
-import { promises as fs } from "node:fs"
+import { promises as fs, readFileSync } from "node:fs"
 import path from "node:path"
 import os from "node:os"
 import { spawn } from "node:child_process"
-import { randomBytes } from "node:crypto"
+import { randomBytes, createHash } from "node:crypto"
 
 const HUB_AI_RULES_BEGIN = "<!-- BEGIN HUB-AI-RULES -->"
 const HUB_AI_RULES_END = "<!-- END HUB-AI-RULES -->"
@@ -32,9 +32,19 @@ const _CLI_DIR_NAME = { claude: ".claude", codex: ".codex" }
 
 function resolveClaudeDir(cliKind = "claude") {
   // CLAUDE_DIR env override は既存の claude 専用テスト/運用で使われているため
-  // cli_kind='claude' のときのみ効かせる (codex は CODEX_DIR で別途上書き可能)。
+  // cli_kind='claude' のときのみ効かせる。
+  //
+  // ⚠️ codex は **config / state / lock / bundle files で同一の canonical resolver を使う**
+  // （2026-07-16 修正）。以前は本関数が `CODEX_HOME` を無視して `CODEX_DIR || ~/.codex` を返す一方、
+  // config.toml のパス解決だけ `CODEX_HOME` を最優先していたため、active profile（CODEX_HOME 指定）
+  // 環境で「config は profile 側・state/lock/files は ~/.codex 側」に分裂した。codex 本体と同じく
+  // `CODEX_HOME` を最優先し、次に hub-agent の `CODEX_DIR` override、最後に `~/.codex` に揃える。
   if (cliKind === "codex") {
-    return process.env.CODEX_DIR || path.join(os.homedir(), _CLI_DIR_NAME.codex)
+    return (
+      process.env.CODEX_HOME ||
+      process.env.CODEX_DIR ||
+      path.join(os.homedir(), _CLI_DIR_NAME.codex)
+    )
   }
   return process.env.CLAUDE_DIR || path.join(os.homedir(), _CLI_DIR_NAME.claude)
 }
@@ -353,12 +363,27 @@ function runOnce(argv, { logger } = {}) {
  */
 export const HUB_MCP_NAMES = new Set(["hub", "hub_staff"])
 
-export async function applyMcpServers(bundle, { agentId, agentToken, logger } = {}) {
+export async function applyMcpServers(
+  bundle,
+  { agentId, agentToken, logger, nonInteractive = false, resolveBinImpl, runImpl } = {},
+) {
   const servers = Array.isArray(bundle?.mcp_servers) ? bundle.mcp_servers : []
   if (servers.length === 0) return { added: [], skipped: [] }
+  // CLI 解決 / 実行はテスト注入可能（既定は実 which/spawn）。決定的テストのため。
+  const resolveBin = resolveBinImpl || resolveCliBin
+  const run = runImpl || runOnce
+
+  // ⚠️ 非対話（自動同期）モードでは Claude MCP の登録に一切触らない（2026-07-16 修正）。
+  // Claude 版は既存 server を **remove → add** で再登録するため、add が失敗すると正常に動いていた
+  // Hub MCP が消えてしまう（破壊的）。自動同期は files/hooks/setup（+ codex 承認補完）が目的で、
+  // Claude MCP の登録は enroll / 明示手動 sync（対話）に委ねる。ここでは非破壊に全 server を skip する。
+  if (nonInteractive) {
+    logger?.info?.("非対話モードのため Claude MCP 登録（remove→add）はスキップ（既存登録を破壊しない）")
+    return { added: [], skipped: servers.map((s) => s?.name || "<unnamed>") }
+  }
 
   // `claude` CLI の存在確認 (which / where 相当)。なければ no-op。
-  const claudeBin = await resolveCliBin("claude")
+  const claudeBin = await resolveBin("claude")
   if (!claudeBin) {
     logger?.info("claude CLI が PATH に無いため MCP server 自動登録をスキップ")
     return { added: [], skipped: servers.map((s) => s.name) }
@@ -411,12 +436,12 @@ export async function applyMcpServers(bundle, { agentId, agentToken, logger } =
       if (wantHeader) {
         // 既存があると add が弾かれるため、先に落とす（無ければ失敗するので無視）。
         try {
-          await runOnce([claudeBin, "mcp", "remove", s.name, "-s", scope], { logger })
+          await run([claudeBin, "mcp", "remove", s.name, "-s", scope], { logger })
         } catch {
           // 未登録 → remove は失敗するが正常系。
         }
       }
-      await runOnce(argv, { logger })
+      await run(argv, { logger })
       added.push(s.name)
     } catch (err) {
       // ヘッダ不要の外部 MCP は既存なら "already exists" で失敗する。これは「既に正しく
@@ -444,45 +469,71 @@ export async function applyMcpServers(bundle, { agentId, agentToken, logger } =
  * ユーザー自身が `codex mcp login hub`/`hub_staff` を一度実行する運用に
  * なる可能性が高い）。
  */
-export async function applyCodexMcpServers(bundle, { logger } = {}) {
+export async function applyCodexMcpServers(
+  bundle,
+  { logger, nonInteractive = false, resolveBinImpl, runImpl } = {},
+) {
   const servers = Array.isArray(bundle?.mcp_servers) ? bundle.mcp_servers : []
-  if (servers.length === 0) return { added: [], skipped: [] }
-
-  const codexBin = await resolveCliBin("codex")
-  if (!codexBin) {
-    logger?.info("codex CLI が PATH に無いため MCP server 自動登録をスキップ")
-    return { added: [], skipped: servers.map((s) => s.name) }
+  if (servers.length === 0) {
+    return { added: [], skipped: [], approvalUpdated: [], approvalPending: [], approvalSkipped: [], approvalError: null }
   }
+  // CLI バイナリ解決 / 実行はテスト注入可能（既定は実 which/spawn）。実 subprocess に依存しない
+  // 決定的テストのため（環境の TMPDIR noexec / PATH 解決差で偽バイナリ方式が不安定になる問題の対処）。
+  const resolveBin = resolveBinImpl || resolveCliBin
+  const run = runImpl || runOnce
 
   const added = []
   const skipped = []
-  for (const s of servers) {
-    if (!s?.name || !s?.url) {
-      skipped.push(s?.name || "<unnamed>")
-      continue
-    }
-    const argv = [codexBin, "mcp", "add", s.name, "--url", s.url]
-    try {
-      await runOnce(argv, { logger })
-      added.push(s.name)
-    } catch (err) {
-      logger?.warn({ name: s.name, err: err.message }, "codex mcp add failed")
-      skipped.push(s.name)
+
+  // ⚠️ 非対話（自動同期）モードでは **`codex mcp add` を一切呼ばない**。`codex mcp add` は Hub MCP の
+  // OAuth 2.0 + PKCE 登録を伴い、ブラウザ認証ポップアップを起動しうる（バックグラウンド自動同期が
+  // ユーザーの操作を勝手に奪う）。登録＝対話（enroll / 明示手動 sync / 明示的認証）に限定し、自動同期は
+  // 「既に登録済み（＝ OAuth 認証済み）テーブルへ承認モードを補完する」ことだけを行う。
+  if (!nonInteractive) {
+    const codexBin = await resolveBin("codex")
+    if (!codexBin) {
+      logger?.info("codex CLI が PATH に無いため MCP server 自動登録をスキップ")
+      skipped.push(...servers.map((s) => s?.name || "<unnamed>"))
+    } else {
+      for (const s of servers) {
+        if (!s?.name || !s?.url) {
+          skipped.push(s?.name || "<unnamed>")
+          continue
+        }
+        const argv = [codexBin, "mcp", "add", s.name, "--url", s.url]
+        try {
+          await run(argv, { logger })
+          added.push(s.name)
+        } catch (err) {
+          logger?.warn({ name: s.name, err: err.message }, "codex mcp add failed")
+          skipped.push(s.name)
+        }
+      }
     }
   }
+
   // MCP 承認モードを `~/.codex/config.toml` に反映する（2026-07-15）。
   // ⚠️ `codex mcp add` には承認モードの永続設定オプションが無いため、Bundle が宣言した
   // `default_tools_approval_mode` を config.toml の `[mcp_servers.<name>]` テーブルへ直接
-  // マージする。add の成否に関わらず全 target に対して実行する（add が「already exists」で
-  // 失敗しても承認設定は更新する要件）。config 破壊を避けるため fail-soft（warn のみ）。
+  // マージする。対話 add の成否に関わらず全 target に対して実行する（add が「already exists」で
+  // 失敗しても承認設定は更新する要件）。非対話モードでは onlyExisting=true で「既存テーブルの承認モード
+  // 補完」だけを行い、未登録 server には新規テーブルを作らず pending 報告する。I/O・ネットワーク失敗
+  // （transient）は approvalError として上位（syncBundle）へ返し、state に「再試行すべき失敗」として
+  // 記録させる。config 破壊は _atomicWriteFilePreserving が防ぐ。
   let approvalUpdated = []
+  let approvalPending = []
+  let approvalSkipped = []
+  let approvalError = null
   try {
-    const res = await applyCodexMcpApprovalModes(servers, { logger })
+    const res = await applyCodexMcpApprovalModes(servers, { logger, onlyExisting: nonInteractive })
     approvalUpdated = res.updated
+    approvalPending = res.pending || []
+    approvalSkipped = res.skipped || []
   } catch (err) {
     logger?.warn({ err: err.message }, "codex MCP approval mode の config.toml 反映に失敗")
+    approvalError = err?.message || String(err)
   }
-  return { added, skipped, approvalUpdated }
+  return { added, skipped, approvalUpdated, approvalPending, approvalSkipped, approvalError }
 }
 
 // Codex の MCP サーバーごと承認モードとして `~/.codex/config.toml` へ書いてよい許可値
@@ -497,9 +548,8 @@ const _CODEX_MCP_APPROVAL_MODES = new Set(["auto", "prompt", "writes", "approve"
  * Windows/macOS/Linux とも `os.homedir()`（Windows は USERPROFILE）で解決する。
  */
 function resolveCodexConfigPath() {
-  const dir =
-    process.env.CODEX_HOME || process.env.CODEX_DIR || path.join(os.homedir(), ".codex")
-  return path.join(dir, "config.toml")
+  // config / state / lock / bundle files で同一 resolver を使う（2026-07-16 修正）。
+  return path.join(resolveClaudeDir("codex"), "config.toml")
 }
 
 /**
@@ -517,10 +567,14 @@ function resolveCodexConfigPath() {
  *  - 不正な approvalMode は無視（url のみ・または no-op）。改行コード（LF/CRLF）は維持する。
  *
  * @param {string} configText
- * @param {{name: string, url?: string, approvalMode?: string}} opts
+ * @param {{name: string, url?: string, approvalMode?: string, onlyExisting?: boolean}} opts
+ *   onlyExisting=true のとき、標準テーブルが**まだ無い** server には新規テーブルを追記しない
+ *   （config を無変更で返す）。自動同期（非対話）で使う: 未登録 MCP に承認モードだけ書くと
+ *   OAuth 未認証の「半登録テーブル」を作ってしまうため、登録は対話経路（`codex mcp add`）に
+ *   限定し、自動同期は既存テーブルの承認モード補完だけを行う。
  * @returns {string}
  */
-export function upsertCodexMcpApprovalMode(configText, { name, url, approvalMode } = {}) {
+export function upsertCodexMcpApprovalMode(configText, { name, url, approvalMode, onlyExisting = false } = {}) {
   if (!name) return configText
   const mode = _CODEX_MCP_APPROVAL_MODES.has(approvalMode) ? approvalMode : null
   const kv = []
@@ -548,6 +602,9 @@ export function upsertCodexMcpApprovalMode(configText, { name, url, approvalMode
     // 既に定義されている場合、標準テーブルを追記すると重複定義（不正 TOML）になる。安全側で
     // 何も変えずに返す（apply 側がスキップ扱いにする）。2026-07-15 レビュー指摘対応。
     if (_codexServerAlreadyDefined(configText, name)) return configText
+    // 自動同期（非対話）は未登録テーブルを作らない。OAuth 未認証の半登録を避け、登録は
+    // 対話経路（codex mcp add）に委ねる。呼び出し側が pending として記録する。
+    if (onlyExisting) return configText
     // 真に未定義 → 末尾に新規追記（Bundle 由来 server のみ・呼び出し側が保証）。
     const block = [headerBare, ...kv.map(([k, v]) => `${k} = ${v}`)].join(eol)
     let base = configText
@@ -603,18 +660,22 @@ export function upsertCodexMcpApprovalMode(configText, { name, url, approvalMode
  *    残さない）。rename が失敗した場合は破壊的フォールバックを行わず中止し、既存 config を無変更で維持する。
  *
  * @param {Array<{name?: string, url?: string, default_tools_approval_mode?: string}>} servers
- * @param {{configPath?: string, logger?: any, fsImpl?: any, isWindows?: boolean}} [opts]
+ * @param {{configPath?: string, logger?: any, fsImpl?: any, isWindows?: boolean, onlyExisting?: boolean}} [opts]
  *   configPath 省略時は resolveCodexConfigPath()。fsImpl / isWindows はテスト用の注入点（既定は実 fs / 実 OS）。
- * @returns {Promise<{updated: string[], skipped: string[]}>}
+ *   onlyExisting=true（自動同期・非対話）のとき、標準テーブルが**まだ無い** server には新規
+ *   テーブルを追記せず `pending` として報告する（未登録 MCP に承認モードだけ書いて OAuth 未認証の
+ *   半登録を作らない。登録は対話経路に委ねる）。
+ * @returns {Promise<{updated: string[], skipped: string[], pending: string[]}>}
+ *   pending: onlyExisting で未登録のためスキップした server（対話 sync / codex mcp login が必要）。
  */
 export async function applyCodexMcpApprovalModes(
   servers,
-  { configPath, logger, fsImpl = fs, isWindows = process.platform === "win32" } = {},
+  { configPath, logger, fsImpl = fs, isWindows = process.platform === "win32", onlyExisting = false } = {},
 ) {
   const targets = (Array.isArray(servers) ? servers : []).filter(
     (s) => s?.name && _CODEX_MCP_APPROVAL_MODES.has(s?.default_tools_approval_mode),
   )
-  if (targets.length === 0) return { updated: [], skipped: [] }
+  if (targets.length === 0) return { updated: [], skipped: [], pending: [] }
 
   const cfgPath = configPath || resolveCodexConfigPath()
   let text = ""
@@ -633,11 +694,32 @@ export async function applyCodexMcpApprovalModes(
   let next = text
   const updated = []
   const skipped = []
+  const pending = []
   for (const s of targets) {
+    // 自動同期（onlyExisting）で標準テーブルが無い server は、新規テーブルを作らない。
+    // 非標準形（空白入り/ドット記法/インライン）で既に定義されていれば「安全に編集できない」
+    // → skipped、真に未登録なら「登録が必要」→ pending として区別する（ブラウザは開かない）。
+    if (onlyExisting && !_codexStandardTableExists(next, s.name)) {
+      if (_codexServerAlreadyDefined(next, s.name)) {
+        logger?.warn(
+          { name: s.name },
+          "codex config.toml の該当テーブルが非標準形のため自動同期では編集できずスキップ（既存 config は不変）",
+        )
+        skipped.push(s.name)
+      } else {
+        logger?.info(
+          { name: s.name },
+          "codex MCP が未登録のため承認モードの自動反映を保留（対話 sync / codex mcp login が必要）",
+        )
+        pending.push(s.name)
+      }
+      continue
+    }
     const candidate = upsertCodexMcpApprovalMode(next, {
       name: s.name,
       url: s.url,
       approvalMode: s.default_tools_approval_mode,
+      onlyExisting,
     })
     if (candidate === next) {
       // 変化なし。原因が「既に正しく反映済み（＝ no-op）」か「非標準形で upsert が編集を拒否した」
@@ -666,12 +748,12 @@ export async function applyCodexMcpApprovalModes(
     next = candidate
     updated.push(s.name)
   }
-  if (next === text) return { updated: [], skipped } // 冪等 no-op / 全スキップ
+  if (next === text) return { updated: [], skipped, pending } // 冪等 no-op / 全スキップ
 
   // ⚠️ 失敗しても既存 config.toml を必ず維持する fail-safe な atomic write。
   await _atomicWriteFilePreserving(cfgPath, next, fileMode, { fsImpl, isWindows, logger })
-  logger?.info({ updated, skipped }, "codex MCP approval mode を config.toml へ反映")
-  return { updated, skipped }
+  logger?.info({ updated, skipped, pending }, "codex MCP approval mode を config.toml へ反映")
+  return { updated, skipped, pending }
 }
 
 /**
@@ -752,6 +834,19 @@ function _codexServerAlreadyDefined(text, name) {
   return bracket.test(text) || dotted.test(text)
 }
 
+/**
+ * `name` の MCP サーバーが **標準形ヘッダ** `[mcp_servers.<name>]`（空白/引用ゆらぎ含む）で
+ * 定義されているかを判定する。自動同期（onlyExisting）で「既に登録済み（承認モードだけ補完すれば
+ * よい）」server と「未登録（登録＝OAuth が必要なため保留すべき）」server を区別するのに使う。
+ * 非標準形（ドット記法/インライン/空白入り）は標準テーブルではないため false を返す
+ * （その場合の可否判定は `_codexServerAlreadyDefined` と組み合わせて呼び出し側が行う）。
+ */
+function _codexStandardTableExists(text, name) {
+  const n = _escapeRegExp(name)
+  const bracket = new RegExp(`^\\s*\\[\\s*mcp_servers\\s*\\.\\s*"?${n}"?\\s*\\]\\s*$`, "m")
+  return bracket.test(text)
+}
+
 /**
  * TOML の `key = "..."` 行について、**値（クォート文字列）だけ**を差し替えて返す。
  * インデント・キー左辺・行末インラインコメント（`# ...`）を保持する。値がクォート文字列で
@@ -867,6 +962,351 @@ export function resolveSyncTargets(availableClis) {
   return detected.length > 0 ? detected : ["claude"]
 }
 
+/**
+ * `<cliDir>/.hub_ai_state.json` の絶対パス。setup_hub_ai.py（Python）が `installed_version` を書き、
+ * hub-agent（JS）が `mcp_approval_applied_version` / `last_sync_*` を書く共有 state。
+ * 同一 syncBundle シーケンス内では post_install(setup) → 承認反映の順で直列に書き、跨プロセスの
+ * 競合は acquireBundleSyncLock で防ぐ（read-modify-write の lost update を避ける）。
+ */
+export function hubAiStatePath(cliKind = "claude") {
+  return path.join(resolveClaudeDir(cliKind), ".hub_ai_state.json")
+}
+
+/**
+ * ドット区切り version 文字列を数値比較する。a < b で -1、a === b で 0、a > b で 1。
+ * 解析不能な要素は 0 扱い（session_start.py の `_version_tuple` と同じ寛容さ）。
+ */
+export function compareBundleVersions(a, b) {
+  const pa = String(a || "0").split(".").map((x) => parseInt(x, 10) || 0)
+  const pb = String(b || "0").split(".").map((x) => parseInt(x, 10) || 0)
+  const len = Math.max(pa.length, pb.length)
+  for (let i = 0; i < len; i++) {
+    const da = pa[i] || 0
+    const db = pb[i] || 0
+    if (da < db) return -1
+    if (da > db) return 1
+  }
+  return 0
+}
+
+// codex の恒久 skip とみなす last_sync_error（同一 config・同一 version 再試行を抑止する終端状態）。
+const _CODEX_TERMINAL_ERRORS = new Set(["nonstandard_config", "mcp_not_registered"])
+
+/**
+ * state + 現在の config.toml テキストから、**有効な** 恒久 skip version を返す（無効なら null）。
+ * `last_sync_error` が terminal（非標準 config / 未登録）**かつ** 記録した config fingerprint が現在の
+ * config と一致するときだけ有効。config が変われば（あるいは io にリセットされれば）null を返し、再試行を許す。
+ * heartbeat 報告（sync）と daemon の `_bundleTargetSatisfied`（async）で同一判定を使うための共通純関数。
+ */
+export function codexTerminalSkipVersion(state, configText) {
+  if (!state || !_CODEX_TERMINAL_ERRORS.has(state.last_sync_error)) return null
+  const v = state.mcp_approval_skipped_version
+  const h = state.mcp_approval_skipped_config_hash
+  if (!v || !h) return null
+  const cur = createHash("sha256")
+    .update(typeof configText === "string" ? configText : "")
+    .digest("hex")
+  return h === cur ? v : null
+}
+
+/** `.hub_ai_state.json` を **sync** で読む（壊れていれば {}）。heartbeat 用。 */
+export function readHubAiStateSync(cliKind = "claude") {
+  try {
+    const obj = JSON.parse(readFileSync(hubAiStatePath(cliKind), "utf-8"))
+    return obj && typeof obj === "object" ? obj : {}
+  } catch {
+    return {}
+  }
+}
+
+/** codex config.toml のテキストを読む（読めなければ空文字）。terminal skip 判定用。 */
+export async function readCodexConfigText({ fsImpl = fs } = {}) {
+  try {
+    return await fsImpl.readFile(resolveCodexConfigPath(), "utf-8")
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * heartbeat が報告する **setup 完了済み** version（`installed_version`）を sync で読む。
+ * ⚠️ `<cliDir>/scripts/manifest.json` は post_install/setup **より先に** 配置されるため、setup が失敗しても
+ * manifest だけ新版になる。backend の「反映済み」判定に manifest を使うと setup 失敗を「適用済み」と誤報告して
+ * 再要求が止まる。正本は setup 完了時に書かれる `installed_version`（2026-07-16 修正）。未セットアップは null。
+ */
+export function readCliInstalledVersionSync(cliKind) {
+  const st = readHubAiStateSync(cliKind)
+  return typeof st.installed_version === "string" ? st.installed_version : null
+}
+
+/**
+ * `<cliDir>/scripts/manifest.json` の version を **sync** で読む（未セットアップは null）。
+ * これは「配置済み（setup 完了とは限らない）」= downloaded version。backend の反映判定には使わず、参考報告用。
+ */
+export function readCliBundleVersionSync(cliKind) {
+  try {
+    const p = path.join(resolveClaudeDir(cliKind), "scripts", "manifest.json")
+    const data = JSON.parse(readFileSync(p, "utf-8"))
+    return typeof data?.version === "string" ? data.version : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * codex の承認反映状況を **sync** で読む（heartbeat 用）。
+ * `applied` = 承認反映済み version。`skipped` = **fingerprint 検証済み** の有効な恒久 skip version
+ * （config が変われば無効化されて null。io リセット後も null）。backend はこれで再要求を抑止/再開する。
+ */
+export function readCodexApprovalStatusSync() {
+  const state = readHubAiStateSync("codex")
+  let configText = ""
+  try {
+    configText = readFileSync(resolveCodexConfigPath(), "utf-8")
+  } catch {
+    /* config 無し → 空文字（skip fingerprint は一致しないので skip は無効化される） */
+  }
+  return {
+    applied:
+      typeof state.mcp_approval_applied_version === "string"
+        ? state.mcp_approval_applied_version
+        : null,
+    skipped: codexTerminalSkipVersion(state, configText),
+  }
+}
+
+/** `.hub_ai_state.json` を読む（壊れていれば {}）。 */
+export async function readHubAiState(cliKind = "claude", { fsImpl = fs } = {}) {
+  try {
+    const obj = JSON.parse(await fsImpl.readFile(hubAiStatePath(cliKind), "utf-8"))
+    return obj && typeof obj === "object" ? obj : {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * `.hub_ai_state.json` に patch をマージ保存する（既存キーは保持）。失敗は warn のみ。
+ * ⚠️ **atomic write**（temp → rename）で torn read / 破損を防ぐ（2026-07-16）。並行書き込みの主保護は
+ * bundle 同期ロックだが、SessionStart（Python）等ロック外の reader/writer もあるため atomic を defense-in-depth
+ * で担保する（読む側は常に「古い完全な JSON」か「新しい完全な JSON」のどちらかを見る）。
+ */
+export async function updateHubAiState(cliKind, patch, { fsImpl = fs, logger } = {}) {
+  const p = hubAiStatePath(cliKind)
+  const state = await readHubAiState(cliKind, { fsImpl })
+  const next = { ...state, ...patch }
+  let mode = 0o644
+  try {
+    mode = (await fsImpl.stat(p)).mode & 0o777
+  } catch {
+    /* 新規 → 0o644 */
+  }
+  try {
+    await fsImpl.mkdir(path.dirname(p), { recursive: true })
+    await _atomicWriteFilePreserving(p, JSON.stringify(next, null, 2), mode, { fsImpl, logger })
+  } catch (err) {
+    logger?.warn?.({ err: err?.message }, ".hub_ai_state.json の書き込みに失敗")
+  }
+  return next
+}
+
+/**
+ * 跨プロセス同期ロック（CLI 種別 = configDir 単位）。daemon / SessionStart 経由の
+ * `hub-agent sync-bundle` / 手動 sync が同時に走っても、同一 cli_kind の bundle 同期は 1 本に直列化する。
+ * mkdir は atomic なので EEXIST でロック保持を検知できる。TTL 超過の stale ロックは回収する
+ * （プロセスがクラッシュしてロックを残した場合の自己回復）。取得できなければ null を返す（呼び出し側は skip）。
+ *
+ * @returns {Promise<null | (() => Promise<void>)>} release 関数（取得成功時）、または null（保持中）。
+ */
+/** PID が生存しているか（signal 0）。EPERM は「存在するが権限なし＝生きている」。 */
+function _pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return err?.code === "EPERM"
+  }
+}
+
+export async function acquireBundleSyncLock(
+  cliKind = "claude",
+  { fsImpl = fs, ttlMs = 5 * 60 * 1000, nowMs, logger, pidAliveImpl } = {},
+) {
+  const dir = resolveClaudeDir(cliKind)
+  const lockDir = path.join(dir, ".hub_ai_sync.lock")
+  const metaPath = path.join(lockDir, "owner.json")
+  const now = typeof nowMs === "number" ? nowMs : Date.now()
+  const isAlive = pidAliveImpl || _pidAlive
+  await fsImpl.mkdir(dir, { recursive: true })
+
+  // 各取得ごとに一意な token を発行し、**自分の token と一致するときだけ lockDir を消す** release を返す。
+  // stale 回収でロックが他者へ渡った後に、元保持者の release が他者のロックを誤削除するのを防ぐ。
+  const makeRelease = (token) => async () => {
+    try {
+      const meta = JSON.parse(await fsImpl.readFile(metaPath, "utf-8"))
+      if (meta?.token && meta.token !== token) return // 自分のものでない → 触らない
+    } catch {
+      /* meta 無し/破損: 自分が取得直後で meta を書けなかった等 → 下で後始末する */
+    }
+    try {
+      await fsImpl.rm(lockDir, { recursive: true, force: true })
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  const tryAcquire = async () => {
+    const token = randomBytes(12).toString("hex")
+    try {
+      await fsImpl.mkdir(lockDir) // recursive:false → 既存なら EEXIST（atomic）
+    } catch (err) {
+      if (err?.code === "EEXIST") return null
+      throw err
+    }
+    // ロック取得成功。owner.json（token / pid / at）を書く。
+    // ⚠️ owner.json の書き込みに失敗したら **ロック取得自体を失敗させる**（2026-07-16 修正）。
+    // owner 無しのロックを残すと staleness 判定が pid ベースにならず、初期化窓の曖昧さが復活するため。
+    try {
+      await fsImpl.writeFile(
+        metaPath,
+        JSON.stringify({ token, pid: process.pid, at: now }),
+        { mode: 0o600 },
+      )
+    } catch (err) {
+      logger?.warn?.({ err: err?.message, cliKind }, "lock owner.json 書き込み失敗 → ロックを解放")
+      try {
+        await fsImpl.rm(lockDir, { recursive: true, force: true })
+      } catch {
+        /* best-effort */
+      }
+      return null
+    }
+    return makeRelease(token)
+  }
+
+  // stale ロックの所有権を **atomic rename で獲得** する（2026-07-16 修正）。複数プロセスが同一 stale を
+  // 検知しても、lockDir を一意な隔離名へ rename できるのは 1 プロセスだけ（他は ENOENT）。`rm→mkdir` の
+  // 非原子的な回収では両者が mkdir 成功して二重取得できたため、rename で「回収の勝者」を 1 本に絞る。
+  const reclaimStale = async () => {
+    const isoName = `${lockDir}.stale-${randomBytes(6).toString("hex")}`
+    try {
+      await fsImpl.rename(lockDir, isoName)
+    } catch {
+      return false // 別プロセスが先に回収した（ENOENT 等）→ 敗者
+    }
+    try {
+      await fsImpl.rm(isoName, { recursive: true, force: true })
+    } catch {
+      /* 隔離ディレクトリの掃除失敗は無害 */
+    }
+    return true
+  }
+
+  const first = await tryAcquire()
+  if (first) return first
+
+  // 保持中 → stale 判定。
+  // ⚠️ 生存中 PID からは TTL だけでロックを奪わない（2026-07-16 修正）。5 分以上かかる正当な同期を
+  // 途中から並行実行させないため。回収するのは「保持プロセスが死亡」または「owner.json 不在かつ
+  // lockDir mtime が TTL 超過（＝ crash で owner を書けなかった / 初期化窓を大幅超過）」のときだけ。
+  let stale = false
+  let ownerMeta = null
+  try {
+    ownerMeta = JSON.parse(await fsImpl.readFile(metaPath, "utf-8"))
+  } catch {
+    ownerMeta = null
+  }
+  if (ownerMeta && Number.isInteger(ownerMeta.pid)) {
+    // owner がいる。死んでいれば回収、生きていれば（TTL 超過でも）奪わない。
+    if (!isAlive(ownerMeta.pid)) stale = true
+  } else {
+    // owner.json 不在/破損 = 初期化中 or crash。lockDir の mtime で短い猶予を見て TTL 超過なら回収。
+    try {
+      const st = await fsImpl.stat(lockDir)
+      const mtimeMs = st.mtimeMs ?? (st.mtime ? st.mtime.getTime() : now)
+      if (now - mtimeMs > ttlMs) stale = true
+    } catch {
+      /* stat 失敗（レース中に消えた等）→ 回収しない */
+    }
+  }
+
+  if (!stale) return null
+
+  logger?.warn?.({ cliKind }, "stale な bundle 同期ロックを回収します")
+  const won = await reclaimStale()
+  if (!won) return null // 回収レースの敗者は取得しない
+  // 回収に勝ったら新規取得（lockDir は rename で消えているので mkdir は成功するはず）。
+  return (await tryAcquire()) || null
+}
+
+/** codex config.toml の内容ハッシュ（恒久 skip の fingerprint 用。読めなければ null）。 */
+async function _hashCodexConfig(fsImpl) {
+  try {
+    const text = await fsImpl.readFile(resolveCodexConfigPath(), "utf-8")
+    return createHash("sha256").update(text).digest("hex")
+  } catch {
+    return null
+  }
+}
+
+/**
+ * codex 承認反映の結果を `.hub_ai_state.json` に記録する。
+ *  - 完全反映 → `mcp_approval_applied_version = version`、skip マーカー消去
+ *  - I/O 等の一時失敗（approvalError）→ `last_sync_error="io"`・**retriable**（applied 進めず再試行）
+ *  - 恒久 skip（非標準 config / 未登録）→ skip version + **config fingerprint** を記録し、同一 config・同一
+ *    version では再試行しない（session_start / daemon の無限ループ防止）
+ * 併せて role フィルタ済み expected server 名を保存し、session_start がハードコードに頼らず判定できるようにする。
+ *
+ * @returns {{approvalComplete: boolean, retriable: boolean, patch: object}}
+ */
+async function _recordCodexApprovalState({ version, mcp, bundle, fsImpl, logger }) {
+  const expected = (Array.isArray(bundle?.mcp_servers) ? bundle.mcp_servers : [])
+    .filter((s) => _CODEX_MCP_APPROVAL_MODES.has(s?.default_tools_approval_mode))
+    .map((s) => s.name)
+  const patch = {
+    last_sync_attempt: new Date().toISOString(),
+    codex_expected_mcp_servers: expected,
+  }
+  let approvalComplete = false
+  let retriable = false
+  const _markComplete = () => {
+    patch.mcp_approval_applied_version = version
+    patch.last_sync_error = null
+    patch.mcp_approval_skipped_version = null
+    patch.mcp_approval_skipped_config_hash = null
+    approvalComplete = true
+  }
+  if (expected.length === 0) {
+    // 承認モードを宣言する server が無い（後方互換の旧レスポンス）→ 承認反映は不要。
+    _markComplete()
+  } else if (mcp?.approvalError) {
+    // I/O・ネットワーク等の一時失敗 → applied は進めず再試行させる。
+    // ⚠️ 旧 skip マーカーを **消す**（2026-07-16 修正）。config を直して再同期→I/O 失敗した場合、
+    // 古い skip version/hash が残っていると heartbeat が「恒久 skip 済み」と誤報告し、backend が再要求を
+    // 止めてしまう。io は retriable なので skip は必ずクリアする。
+    patch.last_sync_error = "io"
+    patch.mcp_approval_skipped_version = null
+    patch.mcp_approval_skipped_config_hash = null
+    retriable = true
+  } else {
+    const pending = mcp?.approvalPending || []
+    const skipped = mcp?.approvalSkipped || []
+    const unresolved = expected.filter((n) => pending.includes(n) || skipped.includes(n))
+    if (unresolved.length === 0) {
+      _markComplete()
+    } else {
+      // 恒久 skip（非標準 config で安全に編集不可 / MCP 未登録で OAuth 必要）。config fingerprint を
+      // 記録し、同一 config・同一 version では再試行しない（無限ループ防止）。config が変われば再試行する。
+      patch.last_sync_error = skipped.length > 0 ? "nonstandard_config" : "mcp_not_registered"
+      patch.mcp_approval_skipped_version = version
+      patch.mcp_approval_skipped_config_hash = await _hashCodexConfig(fsImpl)
+    }
+  }
+  await updateHubAiState("codex", patch, { fsImpl, logger })
+  return { approvalComplete, retriable, patch }
+}
+
 /**
  * fetch + apply + post_install(setup) + MCP server 自動登録を **同期的に** まとめて実行。
  * cliKind='codex' で Codex 向け（`~/.codex/`、`codex mcp add`）に切り替わる
@@ -886,7 +1326,43 @@ export function resolveSyncTargets(availableClis) {
  *    （手動 `hub-agent sync-bundle` は setup 完了まで同期的に待つ）。CLI 別パスは backend が
  *    `{{CLI_DIR_NAME}}` を解決して返すため、Codex 同期で `~/.claude` の setup を誤実行しない。
  */
-export async function syncBundle({ hubUrl, agentId, agentToken, logger, fetchImpl, cliKind = "claude" } = {}) {
+export async function syncBundle({
+  hubUrl,
+  agentId,
+  agentToken,
+  logger,
+  fetchImpl,
+  cliKind = "claude",
+  nonInteractive = false,
+  lock = true,
+  fsImpl = fs,
+} = {}) {
+  // 跨プロセス/経路の同時実行を直列化する（daemon / SessionStart 経由 CLI / 手動 sync）。
+  // 取得できなければ他が同期中なので skip（冪等・重複作業回避）。lock:false でテスト時に無効化可能。
+  let release = null
+  if (lock) {
+    release = await acquireBundleSyncLock(cliKind, { fsImpl, logger })
+    if (!release) {
+      logger?.info?.({ cliKind }, "別経路が bundle 同期中のためスキップ（lock 取得できず）")
+      return {
+        version: null,
+        written: [],
+        skipped_same: [],
+        merged_claude_md: false,
+        mcp: { added: [], skipped: [] },
+        skipped: true,
+        reason: "locked",
+      }
+    }
+  }
+  try {
+    return await _syncBundleLocked({ hubUrl, agentId, agentToken, logger, fetchImpl, cliKind, nonInteractive, fsImpl })
+  } finally {
+    if (release) await release()
+  }
+}
+
+async function _syncBundleLocked({ hubUrl, agentId, agentToken, logger, fetchImpl, cliKind, nonInteractive, fsImpl }) {
   const bundle = await fetchBundle({ hubUrl, agentId, agentToken, fetchImpl, cliKind })
   const result = await applyBundle({ bundle, logger, cliKind })
   try {
@@ -908,12 +1384,31 @@ export async function syncBundle({ hubUrl, agentId, agentToken, logger, fetchImp
   let mcp = { added: [], skipped: [] }
   try {
     mcp = cliKind === "codex"
-      ? await applyCodexMcpServers(bundle, { logger })
-      : await applyMcpServers(bundle, { agentId, agentToken, logger })
+      ? await applyCodexMcpServers(bundle, { logger, nonInteractive })
+      : await applyMcpServers(bundle, { agentId, agentToken, logger, nonInteractive })
   } catch (err) {
     logger?.warn({ cliKind, err: err.message }, "applyMcpServers failed (continuing)")
   }
-  return { version: bundle.version, ...result, mcp }
+  // Codex のみ: 承認モード反映の結果を `.hub_ai_state.json` に記録する。
+  // installed_version（files/hooks 済み）とは別に mcp_approval_applied_version を持つことで、
+  // 「files は更新済みだが承認未反映」の状態を「完了」と誤認せず、次回の自己修復対象にできる。
+  // approvalComplete=false かつ retriable（I/O 失敗）の場合は、bundle 本体の version が最新でも
+  // 「component 未完了」として呼び出し側（syncBundleTargets / daemon）へ再試行を促す。
+  let approvalComplete = true // claude / 承認不要 codex は完了扱い
+  let approvalRetriable = false
+  if (cliKind === "codex") {
+    try {
+      const rec = await _recordCodexApprovalState({ version: bundle.version, mcp, bundle, fsImpl, logger })
+      approvalComplete = rec.approvalComplete
+      approvalRetriable = rec.retriable
+    } catch (err) {
+      // 記録自体に失敗 = 完了を保証できない → 再試行対象。
+      logger?.warn?.({ err: err?.message }, "codex approval state の記録に失敗（再試行対象）")
+      approvalComplete = false
+      approvalRetriable = true
+    }
+  }
+  return { version: bundle.version, ...result, mcp, approvalComplete, approvalRetriable }
 }
 
 /**
@@ -933,13 +1428,32 @@ export async function syncBundleTargets({
   fetchImpl,
   logger,
   syncImpl,
+  nonInteractive = false,
+  lock,
 } = {}) {
   const sync = syncImpl || syncBundle
   const results = {}
   const failures = []
   for (const cliKind of Array.isArray(targets) ? targets : []) {
     try {
-      results[cliKind] = await sync({ hubUrl, agentId, agentToken, fetchImpl, cliKind, logger })
+      const r = await sync({
+        hubUrl,
+        agentId,
+        agentToken,
+        fetchImpl,
+        cliKind,
+        logger,
+        nonInteractive,
+        ...(lock !== undefined ? { lock } : {}),
+      })
+      results[cliKind] = r
+      // ⚠️ component 単位の未完了を failure として扱う（2026-07-16 修正）。codex の承認反映が
+      // I/O 等で一時失敗（retriable）した場合、bundle 本体の version が最新になっても「承認だけ」を
+      // 再試行対象にする（daemon の backoff・backend の再要求が続くよう failure に載せる）。
+      // 恒久 skip（非標準 config / 未登録）は retriable=false なので failure にはしない（無限リトライ回避）。
+      if (r && r.approvalRetriable) {
+        failures.push(cliKind)
+      }
     } catch (err) {
       // exit code を message から救い出す（runOnce は "... (exit N): ..." を投げる）。
       const m = /exit (\d+)/.exec(err?.cause?.message || err?.message || "")