@cocorograph/hub-agent 0.8.21 → 0.8.22

package/src/claude-md.mjs

@@ -15,15 +15,41 @@
  * CLAUDE.md（Stage 1/2 で正本化したもの）が即座に引かれて作業に取り掛かれる
  * ようにするため。動的生成は「Hub に正本がまだ無いプロジェクト」の救済として
  * のみ機能する。
+ *
+ * ⚠️ 2 / 3 の自動生成本文は **sidecar を一切残さない**。かつては「この本文は
+ * 自動生成物だ」という証拠（hash）を `.cockpit-sync/*.fallback.json` に書き、
+ * 次回同期の初回判定で参照していたが、書く / 消すたびに中間状態が生まれる割に
+ * 識別力がほぼ無かったため廃止した（2026-08-02。`claude-md-sync.mjs` の
+ * meta 無し初回判定のコメントが正本）。旧版が残した sidecar は誰も読まないので
+ * 掃除もしない（掃除を入れると「消せなかったとき」の分岐がまた増える）。
+ *
+ * ⚠️ 戻り値の `source` は捨てないこと。`'existing'`（＝このセッションより前から
+ * ローカルにファイルがあった）は、同期側の **初回登録**（Hub に無くローカルに
+ * あるものを 1 度だけ取り込む）の唯一の根拠で、`syncClaudeMdWithHub` の
+ * `localFilePreexisted` へそのまま渡す。
+ *
+ * ⚠️ 本文レンダラは `./claude-md-render.mjs` に分割してある（純粋な文字列生成）。
+ * director / repositories の取得は **このファイルが持つ**（唯一の呼び出し元）。
  */
 import fs from "node:fs/promises"
 import os from "node:os"
 import path from "node:path"
 import {
-  sha256,
   writeSyncState,
+  cancelResponseBody,
   nowIso,
+  isHubSnapshotTrustworthy,
+  usableHubUpdatedAt,
 } from "./claude-md-sync.mjs"
+import {
+  HUB_REQUEST_TIMEOUT_MS,
+  acquireDeadline,
+} from "./hub-request-deadline.mjs"
+import {
+  renderPlaceholder,
+  renderRepositorySection,
+  renderWithDirector,
+} from "./claude-md-render.mjs"
 
 const DEFAULT_HUB_API = "https://api.hub.cocorograph.com"
 
@@ -54,42 +80,138 @@ async function loadAccessToken(configFilename = "CLAUDE.md") {
  * 同じエンドポイントは syncClaudeMdWithHub も使うが、ensureClaudeMd は
  * 初回生成 (メタ無し) 経路でしか呼ばれず、PUT もしないため import せず
  * 個別実装する。
+ *
+ * ⚠️ `fetch` にも `res.json()` にも **同じ deadline** を掛ける（headers だけ返して
+ * body を閉じない応答では往復が永久に返らない）。ここが止まると `createSession`
+ * ごと止まる。
  */
-async function fetchHubClaudeMdProject({ hubUrl, accessToken, dirName, fetchImpl }) {
+async function fetchHubClaudeMdProject({
+  hubUrl,
+  accessToken,
+  dirName,
+  fetchImpl,
+  deadline,
+  logger,
+}) {
   const f = fetchImpl || globalThis.fetch
   if (!f) return null
   const url =
     `${hubUrl.replace(/\/+$/, "")}/api/admin/project/claude-md-by-dir/` +
     `?dir_name=${encodeURIComponent(dirName)}`
   try {
-    const res = await f(url, {
-      headers: { Authorization: `Bearer ${accessToken}` },
-    })
-    if (!res.ok) return null
-    return await res.json()
+    const fetched = await deadline.guard(
+      // 同期的に throw する fetch 実装でも guard に載るよう then で包む。
+      Promise.resolve().then(() =>
+        f(url, {
+          headers: { Authorization: `Bearer ${accessToken}` },
+          signal: deadline.signal,
+        }),
+      ),
+    )
+    if (fetched.timedOut) {
+      logger?.warn?.({ dirName }, "fetchHubClaudeMdProject: round-trip timed out; giving up")
+      return null
+    }
+    if (fetched.error) throw fetched.error
+    const res = fetched.value
+    if (!res?.ok) {
+      // 本文は使わないが、閉じずに捨てない（body を閉じない応答で接続が残る）。
+      // ⚠️ ここで共有 deadline を abort しないこと（cancelResponseBody の JSDoc 参照）。
+      cancelResponseBody(res)
+      return null
+    }
+    const parsed = await deadline.guard(Promise.resolve().then(() => res.json()))
+    if (parsed.timedOut) {
+      deadline.abort()
+      logger?.warn?.({ dirName }, "fetchHubClaudeMdProject: response body read timed out")
+      return null
+    }
+    if (parsed.error) throw parsed.error
+    return parsed.value
   } catch {
     return null
   }
 }
 
-async function fetchDirector({ hubUrl, accessToken, dirName, fetchImpl }) {
+/**
+ * GET して JSON を読むだけの共通処理（期限付き）。失敗・非 OK・期限切れは null。
+ *
+ * ⚠️ `fetch` だけでなく `res.json()` にも同じ期限を掛ける。headers だけ返して
+ * body を閉じない応答で往復が永久に返らないのが元の欠陥だったため。
+ */
+async function fetchJsonWithDeadline({ f, url, accessToken, deadline, logger, dirName, label }) {
+  try {
+    const fetched = await deadline.guard(
+      // 同期的に throw する fetch 実装でも guard に載るよう then で包む。
+      Promise.resolve().then(() =>
+        f(url, {
+          headers: { Authorization: `Bearer ${accessToken}` },
+          signal: deadline.signal,
+        }),
+      ),
+    )
+    if (fetched.timedOut) {
+      logger?.warn?.({ dirName }, `${label}: round-trip timed out; giving up`)
+      return null
+    }
+    if (fetched.error) throw fetched.error
+    const res = fetched.value
+    if (!res?.ok) {
+      // ⚠️ **共有 deadline を abort しない**。director と repositories は 1 本の
+      // deadline を共有しており、片方の通常 404（旧 backend では repositories が
+      // 404）で共有 signal を切ると、成功しうるもう片方まで巻き添えになる。
+      // 解放するのは **この応答の body だけ**。
+      cancelResponseBody(res)
+      return null
+    }
+    const parsed = await deadline.guard(Promise.resolve().then(() => res.json()))
+    if (parsed.timedOut) {
+      deadline.abort()
+      logger?.warn?.({ dirName }, `${label}: response body read timed out`)
+      return null
+    }
+    if (parsed.error) throw parsed.error
+    return parsed.value
+  } catch (err) {
+    logger?.warn?.(
+      { dirName, err: err?.message || String(err) },
+      `${label}: request failed`,
+    )
+    return null
+  }
+}
+
+/**
+ * dir 名から Hub director（KnowledgePage）を取得する。
+ *
+ * ⚠️ 一度 `claude-md-sync.mjs` へ物理移動していたが、移動の理由だった「救済判定」
+ * （旧レンダラで再現して等値比較する移行措置）を廃止したため**ここへ戻した**。
+ * 呼び出し元は `ensureClaudeMd` だけで、sync 側は director を引かない。
+ *
+ * @param {object} args
+ * @param {object} args.deadline `hub-request-deadline.mjs` の deadline。
+ *   ⚠️ director と repositories は**同じ deadline を共有**して呼ぶこと
+ *   （片方が期限切れになったらもう片方も abort される、を成立させるため）。
+ */
+async function fetchDirector({ hubUrl, accessToken, dirName, fetchImpl, deadline, logger }) {
   const f = fetchImpl || globalThis.fetch
   if (!f) return null
   const slug = `${dirName}/_director`
   const url =
     `${hubUrl.replace(/\/+$/, "")}/api/knowledge-pages/` +
     `?slug=${encodeURIComponent(slug)}&doc_type=director`
-  try {
-    const res = await f(url, {
-      headers: { Authorization: `Bearer ${accessToken}` },
-    })
-    if (!res.ok) return null
-    const payload = await res.json()
-    const items = payload?.results || []
-    return items[0] || null
-  } catch {
-    return null
-  }
+  const payload = await fetchJsonWithDeadline({
+    f,
+    url,
+    accessToken,
+    deadline,
+    logger,
+    dirName,
+    label: "fetchDirector",
+  })
+  if (!payload) return null
+  const items = payload?.results || []
+  return items[0] || null
 }
 
 /**
@@ -97,237 +219,40 @@ async function fetchDirector({ hubUrl, accessToken, dirName, fetchImpl }) {
  *
  * 旧 Hub backend（GitRepository モデル未導入）では 404 を返すので、
  * その場合は空配列扱いで後方互換を維持する。
+ * ⚠️ 配置の経緯は `fetchDirector` の JSDoc 参照。
  *
  * @returns {Promise<Array<object>>}
  */
-async function fetchRepositories({ hubUrl, accessToken, dirName, fetchImpl }) {
+async function fetchRepositories({ hubUrl, accessToken, dirName, fetchImpl, deadline, logger }) {
   const f = fetchImpl || globalThis.fetch
   if (!f) return []
   const url =
     `${hubUrl.replace(/\/+$/, "")}/api/git-repositories/by-dir/` +
     `${encodeURIComponent(dirName)}/`
-  try {
-    const res = await f(url, {
-      headers: { Authorization: `Bearer ${accessToken}` },
-    })
-    if (!res.ok) return []
-    const payload = await res.json()
-    return Array.isArray(payload?.repositories) ? payload.repositories : []
-  } catch {
-    return []
-  }
-}
-
-/**
- * GitRepository 配列を CLAUDE.md のクローンレス作業手順セクションに描画する。
- *
- * リポジトリが 1 件もない場合は空文字列を返し、CLAUDE.md には何も追記しない。
- */
-/**
- * repo_url が GitHub の `owner/repo` slug 形式かを判定する。
- *
- * `://` や `@` を含むフル URL（GitLab の `git@gitlab.com:...` や
- * `https://gitlab.com/...` 等）は false を返す。これらは `gh` ではなく
- * 素の `git clone` でチェックアウトする。
- */
-function isGitHubSlug(repoUrl) {
-  if (/:\/\/|@/.test(repoUrl)) return false
-  return /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repoUrl)
-}
-
-function renderRepositorySection(repositories, dirName = "", cliKind = "claude") {
-  if (!Array.isArray(repositories) || repositories.length === 0) return ""
-
-  const lines = ["## Cockpit クローンレス開発フロー", ""]
-  lines.push(
-    "この workspace ディレクトリには Git リポジトリを常設しません。",
-    "コードを修正するときは、毎回一時ディレクトリにチェックアウトして作業します。",
-    "",
-  )
-
-  for (const repo of repositories) {
-    const repoUrl = (repo?.repo_url || "").trim()
-    if (!repoUrl) continue
-    const branch = (repo?.default_branch || "main").trim()
-    const deployDisplay = (repo?.deploy_method_display || "").trim()
-    const deployNotes = (repo?.deploy_notes || "").trim()
-    const stagingName = (repo?.staging_server_name || "").trim()
-    const productionName = (repo?.production_server_name || "").trim()
-    const repoLabel = (repo?.name || "").trim()
-    const heading = repoLabel
-      ? `### ${repoUrl} — ${repoLabel}`
-      : `### ${repoUrl}`
-
-    lines.push(heading)
-    lines.push("")
-    lines.push(`- **デフォルトブランチ**: \`${branch}\``)
-    if (deployDisplay) lines.push(`- **デプロイ方式**: ${deployDisplay}`)
-    if (stagingName) lines.push(`- **ステージング**: ${stagingName}`)
-    if (productionName) lines.push(`- **本番**: ${productionName}`)
-    lines.push("")
-
-    const githubSlug = isGitHubSlug(repoUrl)
-    lines.push("**作業手順（クローンレス）**:")
-    lines.push("")
-    lines.push("```bash")
-    lines.push("TMPDIR=$(mktemp -d)")
-    if (githubSlug) {
-      // GitHub: gh CLI で clone・PR 作成
-      lines.push(`gh repo clone ${repoUrl} "$TMPDIR" -- --depth 1 --filter=blob:none --no-checkout`)
-      lines.push(`cd "$TMPDIR" && git fetch origin ${branch} && git checkout -b feat/<your-change> origin/${branch}`)
-      lines.push("# ファイル編集 → 動作確認")
-      lines.push('git commit -am "<message>"')
-      lines.push("git push -u origin HEAD")
-      lines.push(`gh pr create --base ${branch} --fill`)
-    } else {
-      // GitLab 等: 素の git clone。MR は push 後に Web/glab で作成
-      lines.push(`git clone --depth 1 --filter=blob:none --no-checkout ${repoUrl} "$TMPDIR"`)
-      lines.push(`cd "$TMPDIR" && git fetch origin ${branch} && git checkout -b feat/<your-change> origin/${branch}`)
-      lines.push("# ファイル編集 → 動作確認")
-      lines.push('git commit -am "<message>"')
-      lines.push("git push -u origin HEAD")
-      lines.push("# MR は GitLab の Web UI（push 時に表示される URL）か `glab mr create` で作成")
-    }
-    lines.push("# 作業終了後")
-    lines.push('cd / && rm -rf "$TMPDIR"')
-    lines.push("```")
-    lines.push("")
-
-    if (deployNotes) {
-      lines.push("**デプロイ手順メモ**:")
-      lines.push("")
-      lines.push("```")
-      lines.push(deployNotes)
-      lines.push("```")
-      lines.push("")
-    }
-
-    // デプロイ接続情報の安全な取得手順（秘匿値を会話に出さない）。
-    if (stagingName || productionName) {
-      const envExample = productionName ? "production" : "staging"
-      lines.push("**デプロイ接続情報の取得（秘匿値を会話に出さない）**:")
-      lines.push("")
-      lines.push("```bash")
-      lines.push(
-        "# 秘密鍵を ~/.ssh/hub_deploy/ に書き出し、ssh コマンドだけ受け取る",
-      )
-      lines.push(
-        `python3 ~/.${cliKind === "codex" ? "codex" : "claude"}/scripts/hub_helper.py deploy_creds ${dirName || "<dir_name>"} --env ${envExample}`,
-      )
-      lines.push("```")
-      lines.push("")
-      lines.push(
-        "返り値の `ssh_command` をそのまま使って接続します。`key_file` は",
-        "chmod 600 で書き出されます。パスワード認証のサーバーは `password_set: true`",
-        "だけ返るので、その場合は Hub の「サーバー情報」タブから人手で取得します。",
-        "",
-      )
-    }
-  }
-
-  lines.push("### デプロイ前の必須ガード", "")
-  lines.push(
-    "- **本番反映の前に必ず現状バックアップを取る**（DB ダンプ / 対象ディレクトリの退避）。",
-    "- ステージングで動作確認してから本番へ。",
-    "- 破壊的操作（`reset --hard` / `rm -rf` / DB 操作）の前に対象を確認する。",
-    "- Git 認証はローカルの `gh` CLI（GitHub）/ SSH 鍵（GitLab 等）を使用します。",
-    "",
-  )
-  return lines.join("\n")
-}
-
-function renderWithDirector(dirName, director, repositorySection = "", configFilename = "CLAUDE.md") {
-  const fm = director?.frontmatter || {}
-  const client = (fm.client || "").trim()
-  const domain = (fm.domain || "").trim()
-  const industry = (fm.industry || "").trim()
-  const service = (fm.service || "").trim()
-  const techStack = Array.isArray(fm.tech_stack) ? fm.tech_stack : []
-  const googleDrive = (fm.google_drive || "").trim()
-
-  const lines = [
-    `# ${configFilename}`,
-    "",
-    `This file provides guidance to ${configFilename === "AGENTS.md" ? "Codex" : "Claude Code"} when working with code in this repository.`,
-    "",
-    "## プロジェクト概要",
-    "",
-  ]
-  if (client) lines.push(`- **クライアント**: ${client}`)
-  if (domain) lines.push(`- **ドメイン**: ${domain}`)
-  if (industry) lines.push(`- **業種**: ${industry}`)
-  if (service) lines.push(`- **サービス**: ${service}`)
-  if (!(client || domain || industry || service)) {
-    lines.push("- (director frontmatter に該当情報なし)")
-  }
-  lines.push("")
-
-  if (techStack.length > 0) {
-    lines.push("## 技術スタック")
-    lines.push("")
-    for (const t of techStack) lines.push(`- ${t}`)
-    lines.push("")
-  }
-
-  lines.push("## 関連")
-  lines.push("")
-  lines.push(
-    `- **Hub Director**: \`[[${dirName}/_director]]\` — 案件の進行・意思決定・直近ログ`,
-  )
-  if (googleDrive) {
-    lines.push(`- **Google Drive**: \`$GDRIVE/${googleDrive}/\` — 成果物・素材`)
-  }
-  lines.push("")
-
-  if (repositorySection) {
-    lines.push(repositorySection)
-  }
-
-  lines.push("## 初期化")
-  lines.push("")
-  lines.push(
-    "これは hub-agent が director frontmatter から自動生成した雛形です。",
-  )
-  lines.push(
-    "開発手順・SSH 接続情報・横断ナレッジへのポインタなど、より詳細な内容は",
-  )
-  lines.push(
-    `このリポジトリで ${configFilename === "AGENTS.md" ? "`codex` を起動して `/init-Codex-md`" : "`claude` を起動して `/init-claude-md`"} スキルを実行してください。`,
-  )
-  lines.push("")
-  return lines.join("\n")
-}
-
-function renderPlaceholder(dirName, repositorySection = "", configFilename = "CLAUDE.md") {
-  const sections = [
-    `# ${configFilename}`,
-    "",
-    `This file provides guidance to ${configFilename === "AGENTS.md" ? "Codex" : "Claude Code"} when working with code in this repository.`,
-    "",
-    "## 関連",
-    "",
-    `- **Hub Director**: \`[[${dirName}/_director]]\` — 案件の進行・意思決定・直近ログ (未作成)`,
-    "",
-  ]
-  if (repositorySection) {
-    sections.push(repositorySection)
-  }
-  sections.push(
-    "## 初期化",
-    "",
-    "これは hub-agent の自動生成プレースホルダです。Hub director も未作成です。",
-    `詳細を生成するには、このリポジトリで ${configFilename === "AGENTS.md" ? "`codex` を起動して `/init-Codex-md`" : "`claude` を起動して `/init-claude-md`"} スキルを実行してください。`,
-    "",
-  )
-  return sections.join("\n")
+  const payload = await fetchJsonWithDeadline({
+    f,
+    url,
+    accessToken,
+    deadline,
+    logger,
+    dirName,
+    label: "fetchRepositories",
+  })
+  return Array.isArray(payload?.repositories) ? payload.repositories : []
 }
 
 /**
  * `<targetDir>/CLAUDE.md` を必要に応じて生成する。
  *
  * - CLAUDE.md が既存なら何もしない (上書きしない)
+ * - Hub に正本があればそれを書き、同期メタを初期化する (source: 'hub')
  * - Hub director が見つかれば frontmatter 連動の構造化 CLAUDE.md を生成
  * - 見つからない / 認証なし / API 失敗ならプレースホルダを生成
+ * - **予算切れのときは何も書かない** (source: 'deferred')。不確定な状態で
+ *   自動生成物を置かず次回へ持ち越す。
+ * - **200 が返ったのに snapshot が自己整合でないときも何も書かない**
+ *   (source: 'deferred')。不整合な本文 / hash を「同期済みの基準」として保存すると、
+ *   直後の `syncClaudeMdWithHub` が正常な応答を得た瞬間に Hub 正本を上書きする。
  *
  * @param {object} args
  * @param {string} args.targetDir       絶対パス
@@ -336,7 +261,15 @@ function renderPlaceholder(dirName, repositorySection = "", configFilename = "CL
  * @param {string} [args.accessToken]   省略時は `~/.claude/.hub_token.json` から読む
  * @param {object} [args.logger]
  * @param {Function} [args.fetchImpl]   テスト注入用
- * @returns {Promise<{ written: boolean, source: 'existing' | 'director' | 'placeholder' }>}
+ * @param {number} [args.requestTimeoutMs] Hub API 1 往復の期限（既定
+ *   `HUB_REQUEST_TIMEOUT_MS`）
+ * @param {object} [args.budget]        `createSessionBudget()` の戻り値。セッション
+ *   起動 1 回で **Hub 処理に割り当てた wall-clock 予算**（生成時からの経過時間。
+ *   通信の待ち時間の累積ではない）を超えたら打ち切る。⚠️ 予算切れのときは
+ *   **fallback 本文を書かずに** `deferred` を返す（不確定な状態で自動生成物を
+ *   置くと、次回 sync が Hub 正本をそれで上書きしうるため）。
+ * @returns {Promise<{ written: boolean,
+ *                     source: 'existing' | 'hub' | 'director' | 'placeholder' | 'deferred' }>}
  */
 export async function ensureClaudeMd({
   targetDir,
@@ -346,6 +279,8 @@ export async function ensureClaudeMd({
   logger,
   fetchImpl,
   configFilename = "CLAUDE.md",
+  requestTimeoutMs = HUB_REQUEST_TIMEOUT_MS,
+  budget,
 } = {}) {
   if (!targetDir) throw new Error("ensureClaudeMd requires targetDir")
   if (!dirName) throw new Error("ensureClaudeMd requires dirName")
@@ -360,6 +295,16 @@ export async function ensureClaudeMd({
     /* not found → continue */
   }
 
+  /** 予算切れ: 何も書かずに諦める（セッション起動は止めない）。 */
+  const deferred = () => {
+    logger?.warn?.(
+      { dirName, configMdPath },
+      "ensureClaudeMd: session wall-clock budget for hub work exhausted; wrote nothing (retry next session)",
+    )
+    return { written: false, source: "deferred" }
+  }
+  if (budget?.expired()) return deferred()
+
   // accessToken は明示 null (テスト用) で「token を読まない」を選べるようにする。
   // undefined のときだけ ~/.claude/.hub_token.json にフォールバックする。
   const token =
@@ -370,14 +315,72 @@ export async function ensureClaudeMd({
   // （以降の syncClaudeMdWithHub が双方向同期の起点として使う）。
   // Hub 側未保存 (claude_md_updated_at が null) なら従来パスへフォールバック。
   if (token) {
-    const hub = await fetchHubClaudeMdProject({
-      hubUrl: url,
-      accessToken: token,
-      dirName,
-      fetchImpl,
-    })
-    const hubBody = hub?.claude_md || ""
-    const hubInitialized = !!hub?.claude_md_updated_at
+    const deadline = acquireDeadline(budget, requestTimeoutMs)
+    let hub = null
+    try {
+      hub = await fetchHubClaudeMdProject({
+        hubUrl: url,
+        accessToken: token,
+        dirName,
+        fetchImpl,
+        deadline,
+        logger,
+      })
+    } finally {
+      deadline.clear()
+    }
+    // ⚠️ 本文も hash も「観測できた空文字」と「キー欠落 / 型不正」を区別する
+    // （`|| ""` で潰さない）。同期側（claude-md-sync.mjs）では、この潰しが
+    // 「Hub は空」の誤判定を生み、正しい hash の CAS が通って共有正本を上書きする
+    // 経路になっていた。
+    const hubBody = typeof hub?.claude_md === "string" ? hub.claude_md : null
+    const hubHash = typeof hub?.claude_md_hash === "string" ? hub.claude_md_hash : null
+    // ⚠️ `updated_at` は **門を通すまで正規化しない**（生値のまま持つ）。空文字や数値を
+    // 先に `null` へ潰すと、門から見て「キー欠落（未保存 legacy の正例）」と「型不正
+    // （観測漏れ）」が同じ値になり、`"" / "" / 1750000000` のような壊れた snapshot が
+    // legacy として通ってしまう。正規化は門を通った後（下）で行う。
+    const hubUpdatedAtRaw = hub?.claude_md_updated_at
+
+    // ---- 初期化経路にも **同じ門**を掛ける（`isHubSnapshotTrustworthy` を共有）----
+    //
+    // ここは PUT を発行しないが、**ローカル本文と meta / base（＝同期基準）を書く**。
+    // 不整合な snapshot（本文 C なのに hash が sha256(H)）をそのまま基準にすると、
+    // 直後に連続 await される `syncClaudeMdWithHub` の GET が正常な H を返した瞬間に
+    // 「Hub 不変・ローカルだけ変化」と判定され、**C が CAS 付きで PUT されて H が
+    // 消える**（実測済み）。前回は本文の型判定だけ揃えて **対になる hash の検査を
+    // 揃えなかった**ため、`hub.claude_md_hash || sha256(hubBody)` が
+    // 「truthy な不一致 hash」をそのまま基準として採用していた。
+    //
+    // ⚠️ **検査する値は同期側と同じ 3 つ（`body` / `hash` / `updated_at`）。**
+    // 「同期側は 3 値を見るが初期化側は 2 値だけ」という非対称を残さないこと
+    // （＝「片方は塞いだが対になる側を見ていない」型の穴）。ここで書く meta の
+    // `lastSyncedHubUpdatedAt` は、以降の `syncClaudeMdWithHub` が「Hub が動いたか」を
+    // 判定する基準そのものなので、時刻を観測できていない snapshot を基準にしてはいけない。
+    //
+    // ⚠️ **「壊れた 200」と「正常な未初期化 / 404」を同じ fallback に丸めないこと。**
+    //   - GET 自体が失敗 / 404（`hub === null`）→ 従来どおり fallback 生成へ進む
+    //   - 未初期化（`"" / ""` + `updated_at` なし）→ 整合しているので従来どおり
+    //     fallback 生成へ進む（経路 C の `"" / sha256("") / T` も同じく整合）
+    //   - **200 なのに契約を満たさない**（hash 不一致 / 保存済みなのに `updated_at` が
+    //     欠落・非文字列）→ `deferred`（何も書かずに次回へ回す）
+    // ⚠️ ログに body / hash / updated_at の実値を出さない（固定の理由と dirName だけ）。
+    //
+    // ⚠️ 渡すのは **生値**（`hubUpdatedAtRaw`）。正規化してから渡すと、門が
+    // 「未保存 legacy（`null` / キー欠落）」と「型不正（空文字・数値）」を区別できなくなる
+    // （`isHubSnapshotTrustworthy` の JSDoc 参照）。
+    if (hub && !isHubSnapshotTrustworthy(hubBody, hubHash, hubUpdatedAtRaw)) {
+      logger?.warn?.(
+        { dirName },
+        "ensureClaudeMd: hub snapshot failed the trust contract (hash/updated_at do not match a saved body); wrote nothing (retry next session)",
+      )
+      return { written: false, source: "deferred" }
+    }
+
+    // 門を通った後で、利用用（meta の同期基準になる文字列）へ正規化する。
+    // ⚠️ この正規化を門より上へ動かさないこと。同期側と **同じ関数**を使い、
+    // 「初期化側だけ判定が違う」非対称を作らない。
+    const hubUpdatedAt = usableHubUpdatedAt(hubUpdatedAtRaw)
+    const hubInitialized = hubUpdatedAt !== null
     if (hubInitialized && hubBody) {
       await fs.writeFile(configMdPath, hubBody, "utf-8")
       // 初回 pull 直後は base = Hub 本文。以降の session-end 3-way merge の入力。
@@ -387,8 +390,12 @@ export async function ensureClaudeMd({
       await writeSyncState(targetDir, {
         body: hubBody,
         meta: {
-          lastSyncedHubUpdatedAt: hub.claude_md_updated_at,
-          lastSyncedHash: hub.claude_md_hash || sha256(hubBody),
+          // 門を通っているので非空 string であることが保証されている。
+          lastSyncedHubUpdatedAt: hubUpdatedAt,
+          // ⚠️ 門を通っているので `hubHash === sha256(hubBody)` が保証されている。
+          // `|| sha256(hubBody)` のフォールバックを戻さないこと（「本文と別物の
+          // hash を基準に採用する」余地が復活し、次の正常応答で push が成立する）。
+          lastSyncedHash: hubHash,
           lastSyncedAt: nowIso(),
         },
       }, configFilename)
@@ -402,12 +409,25 @@ export async function ensureClaudeMd({
 
   // 従来パス: director と repositories は独立して取れるので並列フェッチする。
   // どちらも失敗時は null / [] にフォールバックする (token なしの場合も同様)。
-  const [director, repositories] = token
-    ? await Promise.all([
-        fetchDirector({ hubUrl: url, accessToken: token, dirName, fetchImpl }),
-        fetchRepositories({ hubUrl: url, accessToken: token, dirName, fetchImpl }),
+  // ⚠️ **同じ deadline を共有**する（片方が期限切れになったらもう片方も abort）。
+  let director = null
+  let repositories = []
+  if (token) {
+    const deadline = acquireDeadline(budget, requestTimeoutMs)
+    try {
+      ;[director, repositories] = await Promise.all([
+        fetchDirector({ hubUrl: url, accessToken: token, dirName, fetchImpl, deadline, logger }),
+        fetchRepositories({ hubUrl: url, accessToken: token, dirName, fetchImpl, deadline, logger }),
       ])
-    : [null, []]
+    } finally {
+      deadline.clear()
+    }
+  }
+
+  // ⚠️ 書く直前にもう一度予算を見る。取得の途中で予算が尽きた場合、director が
+  // 取れていない = 入力が不確定な状態なので、その状態の placeholder を置いてはいけない
+  // （次回 sync でそれが Hub 正本を上書きする経路が生まれる）。
+  if (budget?.expired()) return deferred()
 
   const cliKind = configFilename === "AGENTS.md" ? "codex" : "claude"
   const repositorySection = renderRepositorySection(repositories, dirName, cliKind)
@@ -416,6 +436,8 @@ export async function ensureClaudeMd({
     : renderPlaceholder(dirName, repositorySection, configFilename)
   const source = director ? "director" : "placeholder"
 
+  // 自動生成本文はそのまま書くだけ（sidecar は書かない）。書込に失敗したら例外が
+  // 呼び出し元へ抜けるが、hub-agent 側で warn に落としてセッション起動は続行する。
   await fs.writeFile(configMdPath, body, "utf-8")
   logger?.info?.(
     { dirName, configMdPath, source },