@cocorograph/hub-agent 0.8.21 → 0.8.23

package/src/claude-md-sync.mjs

@@ -8,10 +8,20 @@
  *   `.bak.conflict.<ts>` に退避（後で人手マージできるよう保存）
  * - どちらも変化なし → no-op
  *
- * 初回（メタファイル無し）:
- * - ローカル CLAUDE.md が空 → pull（Hub の正本をそのまま受け取り）
- * - ローカル非空 + Hub 非空 → 衝突扱い（端末側勝者）
- * - ローカル非空 + Hub 空 → no-op（Hub に空を上書きしない、Stage 3 で初期化検討）
+ * 初回（メタファイル無し）: **端末を勝たせない**（唯一の例外が下記「初回登録」）。
+ * - ローカルが空でも非空でも、Hub 本文があれば pull。手元は `.bak` へ退避するので
+ *   失われない。戻せば meta が入り、次回以降は通常どおり端末側が push される。
+ * - 出どころ（自動生成物か手書きか）を判定材料にしない。かつては sidecar
+ *   （自動生成本文の hash）を置いて見分けていたが、**判定に使う箇所は 1 か所なのに
+ *   書く / 消す箇所が 6 か所**あり、「消費できたか」がファイル削除の成否に依存する
+ *   せいで中間状態が繰り返し生まれたため廃止した（2026-08-02）。
+ *
+ * **初回登録**（`localFilePreexisted === true` のときだけ）: 「Hub に無くローカルに
+ * ある」CLAUDE.md を 1 度だけ Hub へ取り込む。meta 無し + Hub 本文が空 + ローカル
+ * 非空 + 呼び出し元が「そのファイルは元からあった」と報告したときに限り push する。
+ * それ以外で **Hub 本文が空なら何もしない**（`hub-empty` / `hub-uninitialized`）。
+ * 詳細な条件と、なぜ `localFilePreexisted` を永続化しないのかは
+ * `syncClaudeMdWithHub` 内の `isInitialRegistration` のコメントを参照。
  *
  * 失敗時のポリシー: ローカル CLAUDE.md は触らない（warn ログ + skip）。
  * session 起動を止めない（ensureClaudeMd と同じく best-effort）。
@@ -20,6 +30,8 @@
  *   GET /api/admin/project/claude-md-by-dir/?dir_name=...
  *   PUT /api/admin/project/claude-md-by-dir/?dir_name=...  body: { claude_md, expected_hash? }
  *     expected_hash は楽観ロック。GET で読んだ hash を必ず添えて送る（不一致なら 409）。
+ *     **空文字も有効なトークン**（「Hub が空である」ことを期待する）。falsy 判定で
+ *     落とすとキーごと消えて照合されず、盲目的な上書きになる。
  *     CLI 種別を取り違えた本文（CLAUDE.md 正本へ AGENTS.md の内容 等）は 400
  *     `config_md_kind_mismatch` で拒否される。再送しても通らないので理由を分ける。
  */
@@ -28,6 +40,11 @@ import os from "node:os"
 import path from "node:path"
 import crypto from "node:crypto"
 
+import {
+  HUB_REQUEST_TIMEOUT_MS,
+  acquireDeadline,
+} from "./hub-request-deadline.mjs"
+
 const DEFAULT_HUB_API = "https://api.hub.cocorograph.com"
 const META_DIR = ".cockpit-sync"
 const BAK_KEEP = 3 // 通常 .bak と衝突 .bak それぞれ直近 3 件まで保持
@@ -67,6 +84,135 @@ function nowIso() {
   return new Date().toISOString()
 }
 
+/**
+ * GET が返した `claude_md_updated_at` を「同期判定に使える値」へ正規化する。
+ *
+ * 非空 string だけを採用し、それ以外（キー欠落 / null / 空文字 / 数値など）は
+ * **`null`＝観測できていない**に倒す。空文字を残すと文字列比較で常に不一致になり
+ * 「Hub が動いた」と誤認するため、null と同じ扱いにする。
+ *
+ * ⚠️ **信用判定（`isHubSnapshotTrustworthy` / `isNeverSavedLegacy`）へ渡す前に
+ * これを掛けないこと。** 掛けると「欠落」と「型不正」の区別が消える。掛けてよいのは
+ * 門を通った後だけ。
+ *
+ * @param {unknown} raw GET 応答の生値
+ * @returns {string|null}
+ */
+export function usableHubUpdatedAt(raw) {
+  return typeof raw === "string" && raw !== "" ? raw : null
+}
+
+/**
+ * 「Project.save が一度も走っていない legacy」の判定（信用契約の正例 (a)）。
+ *
+ * ⚠️ **判定は 3 値**。`body === "" && hash === ""` の 2 値だけにすると、
+ * `"" / "" / 1750000000` のように「時刻が観測できない（型不正）」snapshot まで
+ * legacy として通ってしまう。backend は一度でも save すれば必ず `updated_at` を
+ * 打つ（本文が空でも打つ ＝ 経路 C）ので、**`null` / キー欠落（`undefined`）だけ**が
+ * legacy の正常形。
+ *
+ * ⚠️ 引数の `hubUpdatedAtRaw` は **GET 応答の生値**。正規化済みの値を渡すと
+ * 「欠落」と「型不正」の区別が消える（それがこの述語の存在理由）。
+ *
+ * この 1 か所を `isHubSnapshotTrustworthy` と `syncClaudeMdWithHub` の両方が使う
+ * （2 か所に書き分けると、片方だけ 2 値へ戻る回帰が起きる）。
+ *
+ * @param {unknown} hubBody GET が返した `claude_md`
+ * @param {unknown} hubHash GET が返した `claude_md_hash`
+ * @param {unknown} hubUpdatedAtRaw GET が返した `claude_md_updated_at`（生値）
+ */
+function isNeverSavedLegacy(hubBody, hubHash, hubUpdatedAtRaw) {
+  return (
+    hubBody === "" &&
+    hubHash === "" &&
+    (hubUpdatedAtRaw === null || hubUpdatedAtRaw === undefined)
+  )
+}
+
+/**
+ * この GET snapshot を **「同期済み状態の基準」として信用してよいか**。
+ *
+ * ⚠️ **PUT 経路に限定して使わないこと。** 契約は「PUT してよいか」ではなく
+ * 「基準にしてよいか」で、**pull も基準（meta / base）を書く**。かつて「pull は Hub に
+ * 書かないから安全」と考えて PUT 経路だけに掛けたが、これは誤りだった:
+ *
+ *   1. 1 回目の GET が壊れた snapshot `{body: C, hash: sha256(H), updated_at: T}` を返す
+ *   2. pull してローカルを C にし、meta に `lastSyncedHash = sha256(H)` / `T` を保存する
+ *      → meta は本来「ローカル本文 == 同期済み Hub 本文」を意味する commit marker
+ *        なのに、**本文 C と hash sha256(H) を同じ世代へ書いて不変条件が壊れる**
+ *   3. 2 回目の GET が正常化して `{body: H, hash: sha256(H), updated_at: T}` を返すと、
+ *      `hubChanged=false`（updated_at 同値）/ `localChanged=true`（C ≠ sha256(H)）と
+ *      判定され、CAS も `expected_hash=sha256(H)` で **正しく通る**
+ *   4. 結果 **C が PUT されて Hub 正本 H が消える**（実測: 1 回目 pull → 2 回目 push）
+ *
+ * つまり「壊れた回に書いた基準」が、**正常化した次の回に上書きを成立させる**。
+ * だから経路ごとに掛ける / 掛けないを判断せず、**入口で 1 回だけ**掛ける。
+ *
+ * ⚠️ **CAS（`expected_hash`）は「GET の後に Hub の版が動いていないこと」しか守らない。
+ * 「クライアントがその版の本文を実際に観測したこと」は守らない。** hash が正しいほど
+ * CAS は成功するので、CAS はこの型の事故に対する防御にならない。
+ *
+ * 正例は 2 つあり、**どちらも実データに存在する**ので片方を落とさないこと:
+ *   (a) `"" / "" / (null | undefined)` … Project.save が一度も走っていない legacy
+ *                        （hash が空文字）。この 1 件だけが `updated_at` の欠落を
+ *                        許される正例。
+ *   (b) `hash === sha256(body)` かつ `updated_at` が非空 string … 保存済み。
+ *       `"" / sha256("")`（経路 C の 4 件）も含む
+ *
+ * ⚠️ **(a) が許すのは `updated_at` が `null` / `undefined`（＝キー欠落）のときだけ。**
+ * `""` / 数値 / 非空文字列は legacy を名乗れない（backend が一度も save していない
+ * なら `null` かキー欠落しか返さない）ので (b) に落ち、`hash !== sha256("")` で false に
+ * なる。`undefined` を残しているのは、キーを省略して返す**古い backend との互換**を
+ * 壊さないため。
+ *
+ * ⚠️ **呼び出し側で `updated_at` を正規化してから渡さないこと。** 空文字や数値を
+ * 事前に `null` へ潰すと、この関数から見て「欠落（legacy の正例）」と「型不正
+ * （観測漏れ）」が区別できなくなり、`"" / "" / 1750000000` のような壊れた snapshot が
+ * legacy として門を通る。**GET 応答の生値をそのまま渡し、正規化は判定を通った後に
+ * 行うこと**（`syncClaudeMdWithHub` / `ensureClaudeMd` の両方がその順で呼んでいる）。
+ * 2026-08-02 の実データ走査では `"" / "" / 非空 updated_at` は 0 件だったが、
+ * **件数を契約にはしない**（0 件だったのは「今そうだった」に過ぎない）。
+ *
+ * ⚠️ **判定に使う値は 3 つ（`body` / `hash` / `updated_at`）で、3 つともここで見る。**
+ * `updated_at` を外に出していた頃、`{body: H1, hash: sha256(H1), updated_at: T0}`
+ * （本文と hash は進んでいるのに時刻だけ前回値）という「自己整合だが時刻が古い」
+ * snapshot が基準として採用され、Hub の H0 → H1 を `hubChanged = false` と誤認した。
+ * その回は noop でも、次にローカルを編集した回に「Hub 不変・ローカルだけ変化」＝
+ * push と判定され、**CAS は現在の sha256(H1) を送るので正しく成功し、Hub の H1 が
+ * 消える**。だから 3 値は 1 か所で束ねる。
+ *
+ * ⚠️ 旧 backend が空本文を `null` で返す互換があれば、その環境では同期が止まる。
+ * ただし現 backend の契約は文字列であり、**暗黙に空へ補正して共有正本を上書きする
+ * より安全**なのでこの方針を採る。
+ *
+ * ⚠️ **この関数が snapshot を信用してよいかの唯一の契約**。呼び出し側で 3 値のうち
+ * 一部だけを見る形に戻さないこと。呼び出し側が利用者向けに細かい reason を出すために
+ * 個別チェックを先に置くのは構わないが（二重でよい）、**最終判定は必ずここを通す**。
+ *
+ * ⚠️ 初期化経路（`claude-md.mjs` の `ensureClaudeMd`）も **同じ関数を同じ 3 引数で**
+ * 使うこと。あちらも Hub 本文と meta を書く ＝ 基準を作るので、条件が同じでなければ
+ * ならない（複製すると片方だけ適用範囲が戻る回帰が起きる）。
+ *
+ * @param {unknown} hubBody GET が返した `claude_md`
+ * @param {unknown} hubHash GET が返した `claude_md_hash`
+ * @param {unknown} hubUpdatedAt GET が返した `claude_md_updated_at`（**生値**。
+ *   呼び出し側で `null` へ正規化してから渡さないこと）
+ * @returns {boolean} この snapshot を同期の基準として使ってよいか
+ */
+export function isHubSnapshotTrustworthy(hubBody, hubHash, hubUpdatedAt) {
+  if (typeof hubBody !== "string" || typeof hubHash !== "string") return false
+  // (a) 一度も保存されていない legacy。sha256("") とは違う値なので (b) では拾えない。
+  //     backend が一度も save していない ＝ `updated_at` は null / キー欠落が正常。
+  //     ⚠️ **3 値すべてを見る**（`body` / `hash` だけで true を返さない）。
+  if (isNeverSavedLegacy(hubBody, hubHash, hubUpdatedAt)) return true
+  // (b) 申告された hash が本文と実際に一致する。
+  if (hubHash !== sha256(hubBody)) return false
+  // (b-2) 一度でも保存されていれば backend は必ず `updated_at` を打つ（本文が空でも
+  //       打つ。実データの経路 C = `"" / sha256("") / timestamp` がその実例）。
+  //       空文字は「観測できていない」と同じ扱い（比較しても常に不一致で基準にならない）。
+  return typeof hubUpdatedAt === "string" && hubUpdatedAt !== ""
+}
+
 function makeBakName(prefix) {
   // ファイル名に使えるよう : を - に置換し、ミリ秒精度を保つ。
   const ts = nowIso().replace(/[:.]/g, "-")
@@ -104,72 +250,33 @@ function bakNamePattern(prefix) {
 }
 
 /**
- * Hub API **1 往復あたり**（headers 受信 〜 body 消費）に掛ける既定の期限 (ms)。
- *
- * ⚠️ **このモジュールが保証するのは「各 HTTP 往復が 15 秒で打ち切られる」ことだけ**。
- * 1 回の同期は GET と PUT を行うし、ファイル I/O と呼び出し元の処理も乗る。さらに
- * 初期化経路（`src/claude-md.mjs` の `ensureClaudeMd`）にはまだ期限が無い。
- * つまり **同期全体・セッション起動全体の budget はここでは決まらない**（別タスク）。
- * ここに「全体で N 秒以内」と書くと、その瞬間から嘘になる。
- *
- * 15 秒とした根拠: 短くしたい誘惑があるが、低速回線・スリープ復帰直後の**正常な**
- * 往復を恒常的に失敗させる方が害が大きい（同期が毎回諦めると正本がドリフトし続ける）。
- * 実際の往復は本文 1 KB 未満・1 秒以内で完了するため 15 秒は十分な余裕がある。
- * ⚠️ 変更前は **無制限**（body を閉じないレスポンスで往復が永久に返らない）だったので、
- * 15 秒でも厳密な改善である。
+ * 期限・全体予算は `./hub-request-deadline.mjs` へ物理移動した（初期化経路
+ * `src/claude-md.mjs` と共有するため。複製すると片方だけ直ってドリフトする）。
+ * 保証する範囲もそちらの JSDoc が正本。
  */
-const HUB_REQUEST_TIMEOUT_MS = 15_000
 
 /**
- * 1 往復ぶんの期限とキャンセル手段をまとめたもの。
+ * 使わないレスポンス body を **その応答単位で** 解放する。
+ *
+ * ⚠️ 非 2xx を「status だけ見て return」すると、body を読みも閉じもしないまま
+ * 関数を抜けることになり、**サーバーが body を閉じない応答では接続が残り続ける**
+ * （実測: 503 のヘッダーだけ返す 3 本の GET で、`ensureClaudeMd` が 17ms で
+ * 返った 350ms 後もソケットが 3 本接続中だった）。`deadline.clear()` は
+ * タイマーとリスナーを外すだけで signal を abort しないので、ここが唯一の解放手段。
  *
- * ⚠️ `Promise.race` だけでは**負けた側（`fetch` / `res.json()` / body 読み）が裏で
- * 走り続ける**ため、期限超過時は必ず `AbortController.abort()`（+ 呼び出し側での
- * `reader.cancel()`）を行い、正常終了時は `clear()` でタイマーを解除すること。
- * タイマーは `unref()` して、これだけでプロセスが生き残らないようにする。
+ * ⚠️ **共有 deadline の signal を abort してはいけない**。`fetchDirector` と
+ * `fetchRepositories` は 1 本の deadline を共有しており、片方の通常 404 で共有
+ * signal を切ると、成功しうるもう片方まで巻き添えで中断される。共有 abort は
+ * 「期限切れ」か「両方の処理が終わった後」に限る。
+ *
+ * ⚠️ `await` しない（cancel が返ってこない実装で、ここが新たな詰まりになる）。
  */
-function createDeadline(ms) {
-  const controller = new AbortController()
-  let fire = null
-  const expired = new Promise((resolve) => {
-    fire = resolve
-  })
-  const timer = setTimeout(() => {
-    try {
-      controller.abort()
-    } catch {
-      /* noop */
-    }
-    fire()
-  }, ms)
-  if (typeof timer.unref === "function") timer.unref()
-  return {
-    signal: controller.signal,
-    abort() {
-      try {
-        controller.abort()
-      } catch {
-        /* noop */
-      }
-    },
-    clear() {
-      clearTimeout(timer)
-    },
-    /**
-     * `promise` を期限付きで待つ。
-     * @returns {Promise<{timedOut: boolean, value?: any, error?: any}>}
-     *   期限超過なら `{timedOut:true}`。負けた promise には必ずハンドラを付けて
-     *   unhandled rejection にしない。
-     */
-    async guard(promise) {
-      return await Promise.race([
-        promise.then(
-          (value) => ({ timedOut: false, value }),
-          (error) => ({ timedOut: false, error }),
-        ),
-        expired.then(() => ({ timedOut: true })),
-      ])
-    },
+export function cancelResponseBody(res) {
+  try {
+    const p = res?.body?.cancel?.()
+    if (p && typeof p.catch === "function") p.catch(() => {})
+  } catch {
+    /* noop: 解放できなくても呼び出し側の判断は変わらない */
   }
 }
 
@@ -181,7 +288,7 @@ function createDeadline(ms) {
  *
  * ⚠️ **GET は PUT より先に走る**ので、ここに期限が無いと PUT 側だけ直しても
  * 「セッション作成が止まらない」という目的を達成できない（同じ失敗の型）。
- * 非 OK 時の本文は読まない（status だけで十分）。掛けているのは期限だけ。
+ * 非 OK 時の本文は読まないが、**閉じずに捨てない**（`cancelResponseBody`）。
  *
  * @returns {Promise<null | {project_id, claude_md, claude_md_hash, claude_md_updated_at}>}
  */
@@ -192,13 +299,14 @@ async function fetchHubClaudeMd({
   fetchImpl,
   logger,
   timeoutMs = HUB_REQUEST_TIMEOUT_MS,
+  budget,
 }) {
   const f = fetchImpl || globalThis.fetch
   if (!f) return null
   const url =
     `${hubUrl.replace(/\/+$/, "")}/api/admin/project/claude-md-by-dir/` +
     `?dir_name=${encodeURIComponent(dirName)}`
-  const deadline = createDeadline(timeoutMs)
+  const deadline = acquireDeadline(budget, timeoutMs)
   try {
     const fetched = await deadline.guard(
       // 同期的に throw する fetch 実装でも guard に載るよう then で包む。
@@ -218,8 +326,12 @@ async function fetchHubClaudeMd({
     }
     if (fetched.error) throw fetched.error
     const res = fetched.value
-    if (res.status === 404) return null
+    if (res.status === 404) {
+      cancelResponseBody(res)
+      return null
+    }
     if (!res.ok) {
+      cancelResponseBody(res)
       logger?.warn?.(
         { dirName, status: res.status },
         "fetchHubClaudeMd: non-OK response",
@@ -275,9 +387,10 @@ const PUT_ERROR_FIELD_MAX_CHARS = 200
  * では 100 MB を抱えた後にしか気づけない。そこで `res.body` を**逐次読み**し、
  * バイト数がこの上限を超えた時点で読み取りを打ち切って reader を cancel する。
  *
- * 64 KiB とした根拠: 実際の拒否応答（`config_md_kind_mismatch` の JSON）は 1 KB 未満、
- * nginx / Cloudflare の HTML エラーページでも数 KB で、64 KiB あれば正当な診断情報は
- * 必ず収まる。
+ * 64 KiB とした根拠: 正当な診断応答は「allowlist した数フィールドの JSON」か
+ * 「nginx / Cloudflare の定型 HTML エラーページ」のどちらかで、どちらも 64 KiB に
+ * 収まらない構造になっていない。これを超える本文は診断情報ではなく異常とみなす。
+ * ⚠️ 実測サイズを根拠として書かないこと（応答の文面が変われば陳腐化する）。
  */
 const PUT_ERROR_BODY_MAX_BYTES = 64 * 1024
 
@@ -431,6 +544,8 @@ async function readNonOkDiagnostics(res, deadline) {
  * `expectedHash` を渡すと backend が行ロック下で現在 hash と照合し、不一致なら
  * **409** を返す（楽観ロック）。「GET してから PUT するまでに他端末 / Hub UI が
  * 動いた」ケースを検出するために必ず渡すこと。渡さないと素通りで盲目的に上書きする。
+ * **空文字 `""` も有効なトークン**（「Hub が空であること」を期待する）で、省略とは
+ * 意味が違う。呼び出し側は falsy 判定で潰さず、観測した値をそのまま渡すこと。
  *
  * 戻り値は「通信できたか」「HTTP ステータス」「レスポンス本文」「拒否理由」を分けて返す。
  * 呼び出し側は 409（＝読んだ後に Hub が動いた。次回 sync で再判定すべき）・
@@ -452,21 +567,29 @@ async function putHubClaudeMd({
   fetchImpl,
   logger,
   timeoutMs = HUB_REQUEST_TIMEOUT_MS,
+  budget,
 }) {
   const f = fetchImpl || globalThis.fetch
   if (!f) return { ok: false, status: null, data: null, error: null }
   const url =
     `${hubUrl.replace(/\/+$/, "")}/api/admin/project/claude-md-by-dir/` +
     `?dir_name=${encodeURIComponent(dirName)}`
-  // expected_hash は「値があるときだけ」載せる。undefined を JSON 化すると
-  // キーごと消えるとはいえ、空文字を送ると backend 側で「空 hash と一致するか」の
-  // 照合に落ちるため、truthy のときのみ明示的に付与する。
-  const payload = expectedHash
-    ? { claude_md: body, expected_hash: expectedHash }
-    : { claude_md: body }
+  // expected_hash は **string なら必ず載せる（空文字を含む）**。
+  //
+  // ⚠️ 空文字は「Hub が空であることを期待する」という **有効な CAS トークン**である。
+  // backend は `expected_hash is not None` で照合に入り、行ロック下で
+  // `locked.claude_md_hash or ''` と比較する。つまり GET と PUT の間に人が本文を
+  // 保存していれば `"" != sha256(本文)` で 409 になり、正しく守られる。
+  // truthy 判定で落とすと **キーごと消えて照合されず、盲目的な上書きになる**
+  // （初回登録経路でこの穴が実際に開いていた）。
+  // undefined / null（＝呼び出し側が hash を観測できていない）のときだけ省く。
+  const payload =
+    typeof expectedHash === "string"
+      ? { claude_md: body, expected_hash: expectedHash }
+      : { claude_md: body }
   // headers 受信から body 消費までを 1 本の期限に収める（別々に張ると、
   // headers だけ返して body を閉じない応答で結局止まる）。
-  const deadline = createDeadline(timeoutMs)
+  const deadline = acquireDeadline(budget, timeoutMs)
   try {
     const fetched = await deadline.guard(
       Promise.resolve().then(() =>
@@ -696,10 +819,52 @@ async function repairBaseIfInconsistent({
   return true
 }
 
+/** 同名衝突で名前を作り直す上限回数（超えたら例外を投げて退避を諦める）。 */
+const BAK_NAME_MAX_ATTEMPTS = 5
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/**
+ * `.bak` を **排他作成**（`flag: 'wx'`）で書き、実際に使った名前を返す。
+ *
+ * ⚠️ 素の `writeFile` だと、同一ミリ秒に 2 回退避したとき（`makeBakName` の精度は
+ * ミリ秒）に **既存の退避を黙って上書きする**。退避は「手元の本文が失われない」
+ * ことの唯一の根拠なので、上書きは許さない: `EEXIST` なら少し待って名前を作り直し、
+ * 上限まで衝突したら **例外を投げる**（呼び出し側の pull はそこで中止され、
+ * ローカルは無傷のまま次回やり直せる）。
+ */
+async function writeBakExclusive(metaDir, prefix, body) {
+  let lastErr = null
+  for (let attempt = 0; attempt < BAK_NAME_MAX_ATTEMPTS; attempt += 1) {
+    const name = makeBakName(prefix)
+    try {
+      await fs.writeFile(path.join(metaDir, name), body, { encoding: "utf-8", flag: "wx" })
+      return name
+    } catch (err) {
+      if (err?.code !== "EEXIST") throw err
+      lastErr = err
+      // 名前はミリ秒精度なので、1ms 以上待てば別名になる。
+      await sleep(2)
+    }
+  }
+  throw (
+    lastErr ||
+    new Error(`backupLocalConfigMd: could not create a unique .bak for ${prefix}`)
+  )
+}
+
 /**
  * 既存ローカル CLAUDE.md を .cockpit-sync/CLAUDE.md.<prefix>.<ts>.bak に退避する。
  * 同 prefix の .bak は新しい順に BAK_KEEP 件保持し、古いものから FIFO 削除する。
  *
+ * ⚠️ **いま作成した .bak は FIFO の削除対象から必ず除外する**。名前の辞書順を
+ * 時系列順として扱っているため、既存 .bak が未来時刻の名前を持っていると
+ * （時計の巻き戻り・手作業で置かれた未来日付・別端末の時刻ずれ）新規 .bak が
+ * 「最も古い側」に並び、**同じ関数の中で作った直後に消される**。pull はその後
+ * ローカルを Hub 本文で上書きするので、手元の本文が復元不能になる。
+ * 「初回は Hub が勝つが、手元は .bak に退避されるので失われない」という安全性の
+ * 根拠は、この除外が無いと成立しない。
+ *
  * @param {'normal'|'conflict'} kind バックアップ種別（命名 prefix）
  */
 async function backupLocalConfigMd(targetDir, body, kind, configFilename) {
@@ -708,8 +873,7 @@ async function backupLocalConfigMd(targetDir, body, kind, configFilename) {
   await fs.mkdir(metaDir, { recursive: true })
   const filename = configPaths(configFilename).filename
   const prefix = kind === "conflict" ? `${filename}.conflict` : filename
-  const bakName = makeBakName(prefix)
-  await fs.writeFile(path.join(metaDir, bakName), body, "utf-8")
+  const bakName = await writeBakExclusive(metaDir, prefix, body)
   // 同 prefix の .bak を新しい順に BAK_KEEP 件まで残す。
   // 対象は「hub-agent が makeBakName で作った、この kind の .bak」だけに限定する
   // （conflict 退避や手作業で置かれた異物を巻き添えにしないため。bakNamePattern 参照）。
@@ -719,7 +883,9 @@ async function backupLocalConfigMd(targetDir, body, kind, configFilename) {
     .filter((n) => pattern.test(n))
     .sort() // 名前にタイムスタンプを含むので辞書順 ≒ 時系列順
     .reverse() // 新しい順
-  const obsolete = sameKind.slice(BAK_KEEP)
+  // ⚠️ `bakName` を除外する。保持枠を 1 件超えることはあるが、次回以降の退避で
+  // 収束する（対して「いま退避した本文を消す」は取り返しがつかない）。
+  const obsolete = sameKind.slice(BAK_KEEP).filter((n) => n !== bakName)
   await Promise.all(
     obsolete.map((n) =>
       fs.unlink(path.join(metaDir, n)).catch(() => {}),
@@ -739,6 +905,15 @@ async function backupLocalConfigMd(targetDir, body, kind, configFilename) {
  * @param {Function} [args.fetchImpl]   テスト注入用
  * @param {number} [args.requestTimeoutMs] Hub API 1 往復の期限（既定
  *   `HUB_REQUEST_TIMEOUT_MS`）。テスト注入・低速環境の調整用。
+ * @param {object} [args.budget] `createSessionBudget()` の戻り値。セッション起動 1 回で
+ *   **Hub 処理に割り当てた wall-clock 予算**（生成時からの経過時間。通信の待ち時間の
+ *   累積ではない）。渡すと各往復が「1 往復の期限」と「予算の残り」の小さい方で
+ *   打ち切られる。予算切れなら **何も書かずに** `skipped(budget-exhausted)` を返す。
+ * @param {boolean} [args.localFilePreexisted] 呼び出し元（`ensureClaudeMd` の
+ *   `source === 'existing'`）が「このセッションより前からローカルにファイルがあった」
+ *   と確認できたときだけ `true` を渡す。**初回登録の唯一の根拠**で、`undefined` /
+ *   `false` なら初回登録しない（安全側）。ディスクには永続化しない（下記
+ *   `isInitialRegistration` のコメント参照）。
  * @returns {Promise<{ action: 'pull'|'push'|'conflict'|'noop'|'skipped', reason?: string }>}
  */
 export async function syncClaudeMdWithHub({
@@ -750,6 +925,8 @@ export async function syncClaudeMdWithHub({
   fetchImpl,
   configFilename = "CLAUDE.md",
   requestTimeoutMs = HUB_REQUEST_TIMEOUT_MS,
+  budget,
+  localFilePreexisted,
 } = {}) {
   if (!targetDir) throw new Error("syncClaudeMdWithHub requires targetDir")
   if (!dirName) throw new Error("syncClaudeMdWithHub requires dirName")
@@ -760,6 +937,15 @@ export async function syncClaudeMdWithHub({
     logger?.info?.({ dirName }, "syncClaudeMdWithHub: no access token, skip")
     return { action: "skipped", reason: "no-token" }
   }
+  if (budget?.expired()) {
+    // セッション起動 1 回ぶんの wall-clock 予算を使い切った（通信していなくても、
+    // 生成時から経てば尽きる）。ローカルは触らず次回へ。
+    logger?.warn?.(
+      { dirName },
+      "syncClaudeMdWithHub: session wall-clock budget for hub work exhausted; skip (retry next session)",
+    )
+    return { action: "skipped", reason: "budget-exhausted" }
+  }
   const url = hubUrl || DEFAULT_HUB_API
 
   // 1) Hub の正本を取得
@@ -770,13 +956,123 @@ export async function syncClaudeMdWithHub({
     fetchImpl,
     logger,
     timeoutMs: requestTimeoutMs,
+    budget,
   })
   if (!hub) {
     return { action: "skipped", reason: "hub-not-resolvable" }
   }
-  const hubBody = hub.claude_md || ""
-  const hubHash = hub.claude_md_hash || "" // 空文字なら Project.save 未実行 = 空本文
-  const hubUpdatedAt = hub.claude_md_updated_at || null
+  // ⚠️ 「観測できた空文字」と「そもそも観測できていない」を、**本文も hash も**
+  // 区別する。
+  // - string（**`""` を含む**）→ その値をそのまま採用。`""` は「Hub が空である」を
+  //   意味する **有効な CAS トークン**（Project.save 未実行 = 空本文）。
+  // - string でない（キー欠落 / null）→ `null`。「照合できない」を意味する。
+  // 両者を `|| ""` で潰すと、照合できない状態を「空を期待する」と偽って PUT して
+  // しまう（＝盲目的な上書き）。`null` のときは PUT せず次回へ回す（fail-closed）。
+  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 の正例 (a) から見て「キー欠落」と
+  // 「型不正」が同じ値になり、`"" / "" / 1750000000` のような壊れた snapshot が
+  // legacy として門を通ってしまう（＝ `expected_hash: ""` の PUT が成立する）。
+  // 利用向けの正規化は門を通った後（下）で行う。
+  const hubUpdatedAtRaw = hub.claude_md_updated_at
+
+  // ---- 入口の門: snapshot を使う前に **1 回だけ** 信用できるかを検査する ----------
+  //
+  // ⚠️ **経路ごとに掛ける / 掛けないを判断しない。** かつては「PUT する経路だけ」に
+  // 絞っていたが、それがこの穴の作り方そのものだった。pull は Hub に書かないが、
+  // **meta / base という同期の基準を書く**。壊れた基準を残すと、次回に正常な応答が
+  // 返ったときに上書きが成立する（詳細な再現手順は `isHubSnapshotTrustworthy` の
+  // JSDoc）。よって **ローカル読み込みより前・あらゆる判定と書込より前**に置く。
+  //
+  // ここを通った後は、以降のすべての経路で次を前提にしてよい:
+  //   - `hubBody` は string（`""` を含む）
+  //   - `hubHash` は string（`""` を含む）
+  //   - snapshot は自己整合（`"" / ""` か `hash === sha256(body)`）
+  //   - `hubUpdatedAt` は、未保存 legacy（`"" / ""`）を除いて非空 string
+  // したがって **push / conflict の直前に同じ検査を再掲しないこと**（本体が 2 つに
+  // なり、「どちらが本物か」が分からなくなる）。
+  //
+  // ⚠️ **同期判定が依存する値は 3 つ（`body` / `hash` / `updated_at`）で、3 つとも
+  // ここで検査する。** 前回は body と hash だけを検査していたため、
+  // `{body: H1, hash: sha256(H1), updated_at: T0}`（本文と hash は新しいのに時刻だけ
+  // 前回値）という自己整合な snapshot が門を通り、Hub の H0 → H1 を
+  // `hubChanged = false` と誤認していた。その回は noop でも、次にローカルを編集した
+  // 回に「Hub 不変・ローカルだけ変化」＝ push と判定され、**CAS は現在の
+  // sha256(H1) を送るので正しく成功し、Hub の H1 がローカル本文で消える**
+  // （`.bak.conflict` も残らない）。「2 つは見たが 3 つ目を見ていない」を閉じるため、
+  // **検査を入口以外に分散させないこと**。
+  //
+  // ⚠️ 旧実装の `hub.claude_md || ""` は、本文欠落を「Hub は空」へ黙って変換していた。
+  // 初回登録（Hub 空 + ローカル非空 → push）を足したことで、この変換は
+  // **「本文を観測していないのに PUT の許可条件を満たす」** 経路になった。しかも
+  // hash と updated_at が正しく返る壊れた payload では **CAS が正しく一致して通る**。
+  //
+  // ⚠️ warn に本文・入力値を出さない（固定の理由と dirName だけ）。
+  if (hubBody === null) {
+    logger?.warn?.(
+      { dirName },
+      "syncClaudeMdWithHub: hub payload had no claude_md body; skip (cannot compare or overwrite safely)",
+    )
+    return { action: "skipped", reason: "hub-body-missing" }
+  }
+  if (hubHash === null) {
+    // 照合トークンを観測できていない。**本文から hash を推測して送らない**
+    // （捏造したトークンで照合が通ると上書きが成立する）。基準としても使えない。
+    logger?.warn?.(
+      { dirName },
+      "syncClaudeMdWithHub: hub payload had no claude_md_hash; skip (cannot verify optimistic lock or trust the snapshot)",
+    )
+    return { action: "skipped", reason: "hub-hash-missing" }
+  }
+  // 一度でも保存されていれば backend は必ず `updated_at` を打つ（本文が空でも打つ。
+  // 実データの経路 C = `"" / sha256("") / timestamp` がその実例）。したがって
+  // **「未保存 legacy だけ」が `updated_at` 欠落の正例**で、それ以外は観測漏れ。
+  // ⚠️ 経路 C を誤って弾かないよう、例外条件は `isHubSnapshotTrustworthy` の (a) と
+  // **同じ述語**（`isNeverSavedLegacy` の 3 値）を使う。`hubBody === ""` だけ /
+  // `"" / ""` の 2 値だけで判定しないこと。
+  const hubNeverSaved = isNeverSavedLegacy(hubBody, hubHash, hubUpdatedAtRaw)
+  // ⚠️ 以下 2 つは **利用者に返す reason を細かく保つための先読み**であって、信用判定の
+  // 本体ではない（本体は下の `isHubSnapshotTrustworthy` 1 か所）。条件を足すときは
+  // 必ず関数側に足し、ここは reason の説明を合わせるだけにすること。
+  //
+  // ⚠️ **時刻 → hash の順**にしている。legacy を名乗れない理由が「時刻が観測できない」
+  // ときは、本文と hash が `"" / ""` でも「保存済みなのに時刻が無い」＝
+  // `hub-updated-at-missing` の方が実態に近い（`"" / ""` は hash 不整合としても
+  // 説明できてしまうが、それでは「何を直せばよいか」が伝わらない）。
+  if (!hubNeverSaved && usableHubUpdatedAt(hubUpdatedAtRaw) === null) {
+    logger?.warn?.(
+      { dirName },
+      "syncClaudeMdWithHub: hub payload had no usable claude_md_updated_at (and is not an unsaved legacy); skip (cannot tell whether hub moved)",
+    )
+    return { action: "skipped", reason: "hub-updated-at-missing" }
+  }
+  if (!hubNeverSaved && hubHash !== sha256(hubBody)) {
+    logger?.warn?.(
+      { dirName },
+      "syncClaudeMdWithHub: hub payload is not self-consistent (hash does not match body); skip (cannot use it as a sync baseline)",
+    )
+    return { action: "skipped", reason: "hub-payload-inconsistent" }
+  }
+  // ---- 信用判定の本体（正本は 1 か所）------------------------------------------
+  // 上の先読みを全部通っていればここは常に true になる。冗長に見えるが、**先読み側を
+  // 触ったときに契約から外れたら気づける**ようにするための最終ゲート。
+  // ⚠️ 渡すのは **生値**（`hubUpdatedAtRaw`）。正規化済みの値を渡すと legacy の正例が
+  // 「欠落」と「型不正」を区別できなくなる（関数側の JSDoc 参照）。
+  if (!isHubSnapshotTrustworthy(hubBody, hubHash, hubUpdatedAtRaw)) {
+    logger?.warn?.(
+      { dirName },
+      "syncClaudeMdWithHub: hub snapshot failed the trust contract; skip (cannot use it as a sync baseline)",
+    )
+    return { action: "skipped", reason: "hub-payload-inconsistent" }
+  }
+
+  // ---- 門を通った後で、利用用の timestamp へ正規化する --------------------------
+  // ここから下は「Hub が動いたか」の文字列比較・meta への保存に使う値。
+  // ⚠️ **正規化はここより上へ動かさないこと**（門に正規化済みの値が渡ると、legacy の
+  // 正例 (a) が「欠落」と「型不正」を区別できなくなる）。門を通っているので、
+  // ここでの値は「未保存 legacy なら null / それ以外は非空 string」が保証される。
+  const hubUpdatedAt = usableHubUpdatedAt(hubUpdatedAtRaw)
 
   // 2) ローカル CLAUDE.md を読み、現在 hash を計算
   const localBody = await readLocalConfigMd(targetDir, configFilename)
@@ -785,36 +1081,123 @@ export async function syncClaudeMdWithHub({
   // 3) メタファイルを読み、前回 sync の状態を取得
   const meta = await readMeta(targetDir, configFilename)
 
-  // Hub が一度も保存されていない（空本文 + updated_at が null）プロジェクトは
+  // --- 初回登録: 「Hub に無くローカルにある」ものを一度だけ Hub へ取り込む -------
+  //
+  // 条件は **すべて** 満たすときだけ:
+  //   - meta が無い（この端末はまだ一度も同期していない）
+  //   - Hub 本文が空（**等値比較のみ**。`updated_at` の有無は問わない）
+  //   - ローカル本文が非空
+  //   - `localFilePreexisted === true`（厳密比較。`undefined` / `false` は登録しない）
+  //   - CLAUDE.md（AGENTS.md は対象外）
+  //
+  // ⚠️ **なぜ `localFilePreexisted` をディスクに永続化しないのか**
+  // `ensureClaudeMd` は戻り値 `{written, source}` で「ファイルが元からあったか」を
+  // 既に知っているのに、呼び出し元がそれを捨てていた。ディスクに証拠を残すと
+  // 「消費できたかが削除の成否に依存する」問題（3 巡連続で blocker を出した
+  // 自動生成本文の sidecar）が再発するため、**同一呼び出し内のメモリでだけ受け渡す**。
+  // 渡されなければ登録しない ＝ 迷ったら Hub を触らない側に倒れる。
+  //
+  // ⚠️ **なぜ AGENTS.md を対象外にするのか**
+  // Hub 側では CLAUDE.md と同じ `Project.claude_md` フィールドを共有しており、
+  // AGENTS.md の内容を送ると混入事故になる（backend に混入ガードが入っていて 400
+  // `config_md_kind_mismatch` で拒否される）。フィールド分離が入るまで対象外。
+  const isInitialRegistration =
+    !meta &&
+    hubBody === "" &&
+    !!localBody &&
+    localFilePreexisted === true &&
+    configPaths(configFilename).filename === "CLAUDE.md"
+
+  // Hub が一度も保存されていない（空本文 + 空 hash + updated_at 欠落）プロジェクトは
   // 「Hub UI で意図的に未設定にしている」運用（テナント標準 CLAUDE.md に任せる等）の
   // 可能性がある。端末側に何か書いてあっても push せず noop に倒す。
-  // ユーザー確定方針: 「Hub の claude_md が空のプロジェクトは何もしない」。
-  const hubInitialized = !!hubUpdatedAt
-  if (!hubInitialized) {
+  //
+  // ⚠️ 判定は入口と **同じ述語**（`isNeverSavedLegacy` の 3 値 ＝ 上で計算済みの
+  // `hubNeverSaved`）を使う。門を通った後は `hubNeverSaved === (hubUpdatedAt === null)`
+  // が成り立つので値としては `!hubUpdatedAt` と等価だが、**述語を 1 つに束ねておかないと
+  // 片方だけ 2 値へ戻る**（＝ 3 値契約が部分的に破れる）回帰が起きる。
+  const hubInitialized = !hubNeverSaved
+  if (!hubInitialized && !isInitialRegistration) {
     return { action: "noop", reason: "hub-uninitialized" }
   }
 
+  // 本文が空 + `updated_at` は非 null（＝経路 C。backend は空本文でも保存時に
+  // updated_at を打つため、実データで 4 件実在した）。上の早期 return では拾えないので
+  // **アクション判定に入る前に**ここで止める。
+  //
+  // ⚠️ 判定は空文字との **等値比較のみ**（`!hubBody` のような truthy 判定にしない。
+  // 「本文が空である」以外の意味を混ぜないため）。
+  //
+  // 初回登録（上）だけがこの門を通れる。2 回目以降（meta あり）は、Hub UI で本文が
+  // 消された状態を端末側本文で勝手に埋め戻さない。
+  if (hubBody === "" && !isInitialRegistration) {
+    return { action: "noop", reason: "hub-empty" }
+  }
+
   // 判定: hubChanged / localChanged を計算する。
-  // - hubChanged: Hub.updated_at が前回 sync 時より進んだ
-  //   updated_at が null（Project.save 未実行で初期空）の場合は変化なし扱い。
+  // - hubChanged: Hub.updated_at が前回 sync 時より進んだ **か**、Hub 本文の hash が
+  //   前回 sync 時の基準と異なる（どちらか一方でも動いていれば Hub は動いている）。
+  //   updated_at が null（Project.save 未実行で初期空）の場合は時刻側を変化なし扱い。
   // - localChanged: 現在の localHash が前回 sync 時の hash と異なる（=端末で編集）
-  //   meta が無くてローカル非空なら、初回参加時のローカル変更扱い（衝突候補）。
+  //   meta が無い初回は常に false（＝ Hub-wins）。唯一の例外が初回登録（下記）。
   let hubChanged, localChanged
   if (!meta) {
-    // 初回 sync。
+    // 初回 sync。**CLAUDE.md / AGENTS.md で扱いを分けない**。
+    //
+    // 【なぜ初回は Hub を勝たせるのか】
+    // 「ローカルに何か書いてある」だけで端末の変更と見なすと、ensureClaudeMd が
+    // Hub 到達不能時に書いた placeholder / director 版が conflict の勝者になり、
+    // **Hub の共有正本（手書き・数千文字）が自動生成物（数百文字）で潰れる**。
+    // 実データ 30 workspace のうち 8 件がこの経路で PUT を発行し、4 件は正本を
+    // 破壊する内容だった。Codex の AGENTS.md も同じで、既存リポジトリ同梱の
+    // ローカル規約が Project.claude_md を壊さないよう Hub を優先する。
+    //
+    // 【なぜ「出どころ」を見分けようとしないのか】
+    // 自動生成物かどうかを sidecar（生成時の hash）で見分ける実装を廃止した。
+    //
+    // ⚠️ sidecar に識別力が無かったわけではない。同一セッション内では
+    // ensureClaudeMd → syncClaudeMdWithHub が連続 await されるので識別の必要が
+    // そもそも無いが、**次セッション以降では同じファイルが `source === 'existing'`
+    // になるため、sidecar は「前回自分が生成した本文だ」を跨いで識別できていた**。
+    // それでも廃止したのは、判定に使うのはここ 1 か所だけなのに書く / 消す箇所が
+    // 6 か所あり、「消費できたか」がファイル削除の成否に依存して **データ喪失を
+    // 伴う中間状態が繰り返し生まれた**ため（3 巡のレビューで毎回この境界から
+    // blocker が出た）。
+    // **その結果、旧セッションが生成した雛形が空の Hub へ初回登録されることは、
+    // トレードオフとして明示的に受け入れている**（実データでは初回登録される
+    // 16 件のうち 10 件が hub-agent の自動生成雛形にあたる）。
+    //
+    // ⚠️ 将来「雛形を正本にしたくない」が要件化しても、**この sidecar を復活させない
+    // こと**。サーバー側に origin / 登録状態を持つなど、削除の成否に依存しない
+    // durable な設計を先に決める。
+    // 「昔のレンダラで再現して等値なら自動生成物」という救済も実データ 0 件で廃止
+    // 済み（本文は 2026-07-22 の aa58223 で変わっており原理的に一致しない）。
+    //
+    // 【引き換えに何が起きるか】
+    // 手書き CLAUDE.md の **初回** 同期では 1 回だけ Hub 側が勝ち、手元は
+    // `.bak` へ退避される（pull 経路が退避してから上書きする）。`.bak` から
+    // 戻せば meta が入るので、次回以降は通常どおり端末側が push される。失われない。
     hubChanged = !!hubBody
-    if (configPaths(configFilename).filename === "AGENTS.md") {
-      // Codex の AGENTS.md は既存リポジトリにも通常存在し、案件正本とは別の
-      // ローカル規約を含む。初回に terminal-wins で Project.claude_md を壊さないよう、
-      // Hub 正本を優先して pull（既存 AGENTS.md は .bak に退避）する。
-      localChanged = false
-    } else if (localBody == null) {
-      localChanged = false
-    } else {
-      localChanged = !!localBody // 非空なら端末側に何かある＝衝突候補
-    }
+    // 唯一の例外が初回登録（Hub に無くローカルにある）。push 経路へ載せる。
+    localChanged = isInitialRegistration
   } else {
-    hubChanged = !!hubUpdatedAt && hubUpdatedAt !== meta.lastSyncedHubUpdatedAt
+    // 「Hub が動いたか」は **時刻と本文 hash の両方**で見る（片方だけにしない）。
+    //
+    // ⚠️ **OR を外して hash 基準だけにしないこと。** 同一本文を Hub で保存し直した
+    // 「時刻だけの更新」は hash が変わらないので、hash 基準だけだと見落とす。
+    // ⚠️ **時刻基準だけにも戻さないこと。** `updated_at` が前回値のまま本文だけ
+    // 進んだ snapshot（入口の門を通る自己整合な payload）で Hub の変更を見落とし、
+    // 次にローカルを編集した回に push が成立して Hub 側が消える（入口の門の
+    // コメント参照）。
+    //
+    // `meta.lastSyncedHash` は全書込経路で「前回同期時点の **Hub 本文** の hash」に
+    // なっている（pull / 収束修復は `hubHash`、push / conflict は PUT 後に Hub 正本と
+    // 一致するローカル本文の hash、初期 pull は `hubHash`）。だから現在の `hubHash`
+    // と直接比較してよい。
+    const hubTimestampMoved =
+      !!hubUpdatedAt && hubUpdatedAt !== meta.lastSyncedHubUpdatedAt
+    const hubBodyMoved = hubHash !== meta.lastSyncedHash
+    hubChanged = hubTimestampMoved || hubBodyMoved
     localChanged =
       localCurrentHash != null && localCurrentHash !== meta.lastSyncedHash
   }
@@ -828,32 +1211,35 @@ export async function syncClaudeMdWithHub({
   // meta 未更新 → 次回この分岐 → さらに次で Hub 編集を上書き）。
   // よってこの分岐は「収束を確定させる自己修復」にする。
   if (hubChanged && localChanged && hubHash && hubHash === localCurrentHash) {
-    // ⚠️ GET の payload を無条件に信用しない。updated_at があり、かつ申告された
-    // hash が本文と実際に一致するときだけ同期基準を進める（壊れた payload で
-    // 基準を進めると、その後の pull / push の判定が丸ごと狂う）。
-    if (hubUpdatedAt && hubHash === sha256(hubBody)) {
-      // ⚠️ base → meta の順（writeSyncState）。meta を先に進めると、base の書込が
-      // 失敗しても「同期済み」と見なされ、次回 sync が通常 noop に入って
-      // base が壊れたまま固定される。
-      await writeSyncState(targetDir, {
-        body: hubBody,
-        meta: {
-          lastSyncedHubUpdatedAt: hubUpdatedAt,
-          lastSyncedHash: hubHash,
-          lastSyncedAt: nowIso(),
-        },
-      }, configFilename)
-      logger?.info?.(
-        { dirName },
-        "syncClaudeMdWithHub: converged (meta/base repaired to hub state)",
-      )
-      return { action: "noop", reason: "converged" }
-    }
-    logger?.warn?.(
-      { dirName, has_updated_at: !!hubUpdatedAt },
-      "syncClaudeMdWithHub: converged but hub payload is inconsistent; meta not advanced",
+    // snapshot の自己整合性（本文 / hash / updated_at）は **入口の門で保証済み**
+    // なのでここでは見ない（見ると検査の本体が 2 つになる）。
+    //
+    // ⚠️ かつてここに `if (hubUpdatedAt)` と、その偽側で
+    // `converged-untrusted-payload` を返す分岐があったが **到達不能**だったので消した:
+    //   - meta あり … `hub-uninitialized` の早期 return が手前で効くので
+    //     `hubUpdatedAt` は必ず truthy（入口の門で「保存済みなら非空 string」も要求）
+    //   - meta なし … `hubChanged = !!hubBody` と `localChanged = isInitialRegistration`
+    //     （後者は `hubBody === ""` が前提）が同時に true にならない
+    // 到達しないのにログが「payload is inconsistent」と説明していて、入口へ検査を
+    // 集約した現契約とも逆になっていた。⚠️ `hubChanged` の定義を変えるときは
+    // この到達可能性を取り直すこと。
+    //
+    // ⚠️ base → meta の順（writeSyncState）。meta を先に進めると、base の書込が
+    // 失敗しても「同期済み」と見なされ、次回 sync が通常 noop に入って
+    // base が壊れたまま固定される。
+    await writeSyncState(targetDir, {
+      body: hubBody,
+      meta: {
+        lastSyncedHubUpdatedAt: hubUpdatedAt,
+        lastSyncedHash: hubHash,
+        lastSyncedAt: nowIso(),
+      },
+    }, configFilename)
+    logger?.info?.(
+      { dirName },
+      "syncClaudeMdWithHub: converged (meta/base repaired to hub state)",
     )
-    return { action: "noop", reason: "converged-untrusted-payload" }
+    return { action: "noop", reason: "converged" }
   }
 
   // 4) アクション決定
@@ -875,16 +1261,29 @@ export async function syncClaudeMdWithHub({
   }
 
   if (hubChanged && !localChanged) {
-    // pull: ローカルを .bak 退避 → Hub の本文で上書き
-    await backupLocalConfigMd(targetDir, localBody, "normal", configFilename)
-    await writeLocalConfigMd(targetDir, hubBody, configFilename)
+    // pull: ローカルを .bak 退避 → Hub の本文で上書き。
+    //
+    // ⚠️ **バイト等値なら本文も `.bak` も触らない**。内容が同じなのに毎回 `.bak` を
+    // 作ると、`BAK_KEEP=3` の FIFO で **利用者の元の本文が押し出される**。meta の
+    // 書込が繰り返し失敗する状況（＝毎回この pull 経路に入る）で実際に起こりうる。
+    // 退避が「初回は Hub が勝つが手元は失われない」の唯一の根拠なので、
+    // 「同じ内容を退避し直して古い退避を捨てる」動きは許さない。
+    if (localBody !== hubBody) {
+      await backupLocalConfigMd(targetDir, localBody, "normal", configFilename)
+      await writeLocalConfigMd(targetDir, hubBody, configFilename)
+    }
     // 3-way merge 用 base: pull 直後はローカル == Hub なので Hub 本文を base に。
     // base → meta の順で書く（writeSyncState の JSDoc 参照）。
+    //
+    // ⚠️ `lastSyncedHash` に **snapshot が申告した hash をそのまま**入れてよいのは、
+    // 入口の門で `hubHash === sha256(hubBody)` を保証しているから。ここで
+    // `hubHash || sha256(hubBody)` のようなフォールバックを足すと「本文とは別物の
+    // hash を基準として保存する」余地が戻り、次回の正常応答で push が成立する。
     await writeSyncState(targetDir, {
       body: hubBody,
       meta: {
         lastSyncedHubUpdatedAt: hubUpdatedAt,
-        lastSyncedHash: hubHash || sha256(hubBody),
+        lastSyncedHash: hubHash,
         lastSyncedAt: nowIso(),
       },
     }, configFilename)
@@ -893,18 +1292,23 @@ export async function syncClaudeMdWithHub({
   }
 
   if (!hubChanged && localChanged) {
+    // ⚠️ hash の観測と snapshot の自己整合性は **入口の門で保証済み**。ここに
+    // 個別チェックを再掲しないこと（検査の本体が 2 つになると、片方だけ適用範囲が
+    // 戻る回帰が起きる。実際に「PUT 経路にだけ掛ける」設計から blocker が出た）。
     // push: Hub に PUT。成功時にメタ更新。
     const put = await putHubClaudeMd({
       hubUrl: url,
       accessToken: token,
       dirName,
       body: localBody || "",
-      // 楽観ロック: この sync が GET で読んだ時点の hash を渡す。読んだ後に Hub が
+      // 楽観ロック: この sync が GET で読んだ時点の hash を **そのまま** 渡す
+      // （`""` も有効なトークンなので falsy 判定で潰さない）。読んだ後に Hub が
       // 動いていれば backend が 409 を返すので、盲目的な上書きにならない。
-      expectedHash: hubHash || undefined,
+      expectedHash: hubHash,
       fetchImpl,
       logger,
       timeoutMs: requestTimeoutMs,
+      budget,
     })
     if (!put.ok) {
       if (put.status === 409) {
@@ -958,6 +1362,10 @@ export async function syncClaudeMdWithHub({
   }
 
   // hubChanged && localChanged → 衝突。端末側を勝者にして Hub に PUT。
+  //
+  // ⚠️ hash の観測と snapshot の自己整合性は **入口の門で保証済み**（push 経路と同じ
+  // 理由でここに再掲しない）。壊れた snapshot は入口で返すので、**PUT しない回に
+  // `.bak.conflict` だけが増える**こともない。
   // Hub の取り込み内容は .bak.conflict に退避（後で人手マージできるよう）。
   await backupLocalConfigMd(targetDir, hubBody, "conflict", configFilename)
   const put = await putHubClaudeMd({
@@ -965,11 +1373,12 @@ export async function syncClaudeMdWithHub({
     accessToken: token,
     dirName,
     body: localBody || "",
-    // push 経路と同じく、GET 時点の hash で楽観ロックを効かせる。
-    expectedHash: hubHash || undefined,
+    // push 経路と同じく、GET 時点の hash を **そのまま** 渡して楽観ロックを効かせる。
+    expectedHash: hubHash,
     fetchImpl,
     logger,
     timeoutMs: requestTimeoutMs,
+    budget,
   })
   if (!put.ok) {
     // PUT 失敗時はメタを更新しない（次回再試行）。ローカルは無傷。