@cocorograph/hub-agent 0.8.18 → 0.8.20

package/src/claude-md-sync.mjs

@@ -18,7 +18,10 @@
  *
  * 関連: backend Stage 1 / 1.5
  *   GET /api/admin/project/claude-md-by-dir/?dir_name=...
- *   PUT /api/admin/project/claude-md-by-dir/?dir_name=...  body: { claude_md }
+ *   PUT /api/admin/project/claude-md-by-dir/?dir_name=...  body: { claude_md, expected_hash? }
+ *     expected_hash は楽観ロック。GET で読んだ hash を必ず添えて送る（不一致なら 409）。
+ *     CLI 種別を取り違えた本文（CLAUDE.md 正本へ AGENTS.md の内容 等）は 400
+ *     `config_md_kind_mismatch` で拒否される。再送しても通らないので理由を分ける。
  */
 import fs from "node:fs/promises"
 import os from "node:os"
@@ -70,24 +73,151 @@ function makeBakName(prefix) {
   return `${prefix}.${ts}.bak`
 }
 
+/**
+ * `makeBakName` が生成するタイムスタンプ部分の形。
+ *
+ * `new Date().toISOString()` は `YYYY-MM-DDTHH:mm:ss.sssZ` 固定で、`makeBakName` が
+ * `:` と `.` を `-` に置換するため `2026-08-01T12-34-56-789Z` になる。
+ * ⚠️ makeBakName を変えたらこの定数も必ず揃えること（`_internals` 経由の
+ * 往復テストが両者の食い違いを検知する）。
+ */
+const BAK_TS_PATTERN = "\\d{4}-\\d{2}-\\d{2}T\\d{2}-\\d{2}-\\d{2}-\\d{3}Z"
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+/**
+ * 「hub-agent が `makeBakName(prefix)` で作った .bak」だけに一致する正規表現を返す。
+ *
+ * FIFO 削除の対象集合をこれで絞る。単純な `startsWith(prefix + ".")` だと
+ * kind='normal'（prefix = `CLAUDE.md`）の集合に `CLAUDE.md.conflict.<ts>.bak` や
+ * 手作業で置かれた異物（`CLAUDE.md.contaminated.<数値>.bak` 等）まで入り込み、
+ * 名前降順では conflict が先頭に並ぶため **健全な通常 bak が保持枠から押し出されて
+ * 削除される**（実際に「手元から復元できない」事故の直接原因になった）。
+ *
+ * `.includes('.conflict.')` を弾くだけの対処にしないのは、将来別の名前が増えたときに
+ * 再び巻き添えになるため。「自分が作った形と一致するものだけ」を対象にする。
+ */
+function bakNamePattern(prefix) {
+  return new RegExp(`^${escapeRegExp(prefix)}\\.${BAK_TS_PATTERN}\\.bak$`)
+}
+
+/**
+ * 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 秒でも厳密な改善である。
+ */
+const HUB_REQUEST_TIMEOUT_MS = 15_000
+
+/**
+ * 1 往復ぶんの期限とキャンセル手段をまとめたもの。
+ *
+ * ⚠️ `Promise.race` だけでは**負けた側（`fetch` / `res.json()` / body 読み）が裏で
+ * 走り続ける**ため、期限超過時は必ず `AbortController.abort()`（+ 呼び出し側での
+ * `reader.cancel()`）を行い、正常終了時は `clear()` でタイマーを解除すること。
+ * タイマーは `unref()` して、これだけでプロセスが生き残らないようにする。
+ */
+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 })),
+      ])
+    },
+  }
+}
+
 /**
  * Hub から claude-md-by-dir で正本を取得する。
  *
  * - 404 = 該当 Project 無し（Domain 型・local_dir 型 workspace）→ null
  * - その他のエラー → null（warn ログ）
  *
+ * ⚠️ **GET は PUT より先に走る**ので、ここに期限が無いと PUT 側だけ直しても
+ * 「セッション作成が止まらない」という目的を達成できない（同じ失敗の型）。
+ * 非 OK 時の本文は読まない（status だけで十分）。掛けているのは期限だけ。
+ *
  * @returns {Promise<null | {project_id, claude_md, claude_md_hash, claude_md_updated_at}>}
  */
-async function fetchHubClaudeMd({ hubUrl, accessToken, dirName, fetchImpl, logger }) {
+async function fetchHubClaudeMd({
+  hubUrl,
+  accessToken,
+  dirName,
+  fetchImpl,
+  logger,
+  timeoutMs = HUB_REQUEST_TIMEOUT_MS,
+}) {
   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)
   try {
-    const res = await f(url, {
-      headers: { Authorization: `Bearer ${accessToken}` },
-    })
+    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, timeout_ms: timeoutMs },
+        "fetchHubClaudeMd: round-trip timed out; giving up (best-effort sync)",
+      )
+      return null
+    }
+    if (fetched.error) throw fetched.error
+    const res = fetched.value
     if (res.status === 404) return null
     if (!res.ok) {
       logger?.warn?.(
@@ -96,53 +226,325 @@ async function fetchHubClaudeMd({ hubUrl, accessToken, dirName, fetchImpl, logge
       )
       return null
     }
-    return await res.json()
+    // body 消費にも同じ期限を掛ける（headers だけ返して body を閉じない応答対策）。
+    const parsed = await deadline.guard(Promise.resolve().then(() => res.json()))
+    if (parsed.timedOut) {
+      deadline.abort()
+      logger?.warn?.(
+        { dirName, timeout_ms: timeoutMs },
+        "fetchHubClaudeMd: 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) },
       "fetchHubClaudeMd: request failed",
     )
     return null
+  } finally {
+    deadline.clear()
+  }
+}
+
+/**
+ * 非 2xx レスポンスから拒否理由を取り出すときの allowlist と長さ上限。
+ *
+ * backend は「AGENTS.md の内容を CLAUDE.md 正本へ保存しようとした」PUT を 400 +
+ * `{"error":"config_md_kind_mismatch", "detail", "expected_kind", "detected_heading"}`
+ * で拒否する（2026-08-01 本番投入）。本文を読まないとこの拒否理由が誰にも見えず、
+ * 「同期が静かに止まる」状態になるため、非 OK のときだけ本文を読む。
+ *
+ * ただしレスポンス本文は **JSON とは限らない**（nginx / Cloudflare の HTML エラー
+ * ページが返ることがある）し、巨大だったり機密値を含みうる。そのため:
+ *   - 載せるのは **allowlist したキーだけ**（本文を丸ごとログに出さない）
+ *   - 各値に長さ上限を掛け、切り捨てたことが分かる形にする
+ *   - JSON として読めない / allowlist キーが 1 つも無い場合は **本文を出さず**、
+ *     status・content-type・本文長だけにする
+ */
+const PUT_ERROR_FIELD_ALLOWLIST = ["error", "detail", "expected_kind", "detected_heading"]
+const PUT_ERROR_FIELD_MAX_CHARS = 200
+
+/**
+ * 非 2xx 本文の **受信上限（UTF-8 バイト）**。
+ *
+ * ⚠️ これは「parse の上限」ではなく「メモリに載せる上限」である。`res.text()` は
+ * 全文をメモリへ読み込んでからでないと長さが分からないため、100 MB の chunked body
+ * では 100 MB を抱えた後にしか気づけない。そこで `res.body` を**逐次読み**し、
+ * バイト数がこの上限を超えた時点で読み取りを打ち切って reader を cancel する。
+ *
+ * 64 KiB とした根拠: 実際の拒否応答（`config_md_kind_mismatch` の JSON）は 1 KB 未満、
+ * nginx / Cloudflare の HTML エラーページでも数 KB で、64 KiB あれば正当な診断情報は
+ * 必ず収まる。
+ */
+const PUT_ERROR_BODY_MAX_BYTES = 64 * 1024
+
+/** ログ・戻り値に載せる文字列に長さ上限を掛ける（切り捨てたことが分かる形にする）。 */
+function truncateForLog(value, max = PUT_ERROR_FIELD_MAX_CHARS) {
+  const s = String(value)
+  if (s.length <= max) return s
+  return `${s.slice(0, max)}…[truncated ${s.length} chars]`
+}
+
+/**
+ * パース済みレスポンスから allowlist キーだけを取り出す。
+ *
+ * 値は文字列・数値・真偽値のみ採用する。オブジェクト / 配列は入れ子に何が入るか
+ * 保証できないので載せない。1 つも取れなければ null（＝呼び出し側は本文を出さない）。
+ */
+function pickAllowedErrorFields(parsed) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null
+  const out = {}
+  for (const key of PUT_ERROR_FIELD_ALLOWLIST) {
+    const v = parsed[key]
+    if (typeof v === "string") out[key] = truncateForLog(v)
+    else if (typeof v === "number" || typeof v === "boolean") out[key] = String(v)
   }
+  return Object.keys(out).length > 0 ? out : null
+}
+
+/**
+ * `res.body`（ReadableStream）をバイト上限付きで読む。
+ *
+ * - 上限を超えた時点で読み取りを打ち切る（`tooLarge = true`）。
+ * - ⚠️ 打ち切った断片は **JSON として解釈しない**（呼び出し側で parse を抑止する）。
+ *   壊れた JSON を読ませると、無い値を「取れた」と誤認しかねない。
+ * - ⚠️ `TextDecoder` は `{stream: true}` で回す。chunk 境界がマルチバイト文字の
+ *   途中に来ても壊れないようにするため。
+ */
+async function readStreamWithByteCap(reader, maxBytes) {
+  const decoder = new TextDecoder("utf-8")
+  let text = ""
+  let bytes = 0
+  let tooLarge = false
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      const size = value?.byteLength ?? value?.length ?? 0
+      if (bytes + size > maxBytes) {
+        tooLarge = true
+        break
+      }
+      bytes += size
+      text += decoder.decode(value, { stream: true })
+    }
+    if (!tooLarge) text += decoder.decode() // 末尾の保留バイトを flush
+  } finally {
+    // 途中で抜けた場合に接続を解放する（上限超過・例外のどちらでも）。
+    try {
+      reader.cancel()?.catch?.(() => {})
+    } catch {
+      /* noop */
+    }
+  }
+  return { text, bytes, tooLarge }
+}
+
+/**
+ * 非 OK レスポンスの診断情報を安全に読み出す。
+ *
+ * 期限（`deadline`）とバイト上限の両方を掛ける。`res.body` を持たない実装
+ * （簡易スタブ / 別実装）では **例外を投げず** status だけで諦める（同期を壊さない）。
+ *
+ * @returns {Promise<{fields: object|null, contentType: string|null,
+ *                    declaredLength: number|null, bodyBytes: number|null,
+ *                    bodyTooLarge: boolean, timedOut: boolean}>}
+ */
+async function readNonOkDiagnostics(res, deadline) {
+  const header = (name) =>
+    typeof res?.headers?.get === "function" ? res.headers.get(name) : null
+  const rawType = header("content-type")
+  const contentType = rawType ? truncateForLog(rawType, 120) : null
+  // ⚠️ Number(null) は 0 になる。ヘッダー欠落を「0 バイトと申告された」と読むと
+  // ログが嘘をつくので、欠落・空文字は「申告なし (null)」として扱う。
+  const declaredRaw = header("content-length")
+  const declaredNum =
+    declaredRaw === null || declaredRaw === undefined || declaredRaw === ""
+      ? Number.NaN
+      : Number(declaredRaw)
+  const declaredLength =
+    Number.isFinite(declaredNum) && declaredNum >= 0 ? declaredNum : null
+  const base = {
+    fields: null,
+    contentType,
+    declaredLength,
+    bodyBytes: null,
+    bodyTooLarge: false,
+    timedOut: false,
+  }
+
+  // Content-Length による早期拒否。⚠️ 欠落・虚偽がありうるので、これに頼らず
+  // stream 側のバイト上限も必ず掛ける（下の readStreamWithByteCap）。
+  if (declaredLength !== null && declaredLength > PUT_ERROR_BODY_MAX_BYTES) {
+    deadline?.abort()
+    return { ...base, bodyTooLarge: true }
+  }
+
+  const body = res?.body
+  if (!body || typeof body.getReader !== "function") return base
+  let reader = null
+  try {
+    reader = body.getReader()
+  } catch {
+    return base
+  }
+
+  const read = readStreamWithByteCap(reader, PUT_ERROR_BODY_MAX_BYTES)
+  // deadline 無しでも guard と同じ形（{timedOut, value?, error?}）に揃える。
+  // 形が揃っていないと、読み取りが reject したときに value を分解して落ちる。
+  const guarded = deadline
+    ? await deadline.guard(read)
+    : await read.then(
+        (value) => ({ timedOut: false, value }),
+        (error) => ({ timedOut: false, error }),
+      )
+  if (guarded.timedOut) {
+    // ⚠️ race で勝っただけでは読み取りが止まらない。cancel + abort まで行う。
+    try {
+      reader.cancel()?.catch?.(() => {})
+    } catch {
+      /* noop */
+    }
+    deadline?.abort()
+    return { ...base, timedOut: true }
+  }
+  if (guarded.error || !guarded.value) return base
+
+  const { text, bytes, tooLarge } = guarded.value
+  let fields = null
+  if (!tooLarge && typeof text === "string" && text.length > 0) {
+    try {
+      fields = pickAllowedErrorFields(JSON.parse(text))
+    } catch {
+      fields = null // HTML エラーページ等。本文は出さない。
+    }
+  }
+  return { ...base, fields, bodyBytes: bytes, bodyTooLarge: tooLarge }
 }
 
 /**
  * Hub に PUT で本文を上書きする。Hub 側は履歴を積んでから保存する。
  *
- * @returns {Promise<boolean>} 成功なら true
+ * `expectedHash` を渡すと backend が行ロック下で現在 hash と照合し、不一致なら
+ * **409** を返す（楽観ロック）。「GET してから PUT するまでに他端末 / Hub UI が
+ * 動いた」ケースを検出するために必ず渡すこと。渡さないと素通りで盲目的に上書きする。
+ *
+ * 戻り値は「通信できたか」「HTTP ステータス」「レスポンス本文」「拒否理由」を分けて返す。
+ * 呼び出し側は 409（＝読んだ後に Hub が動いた。次回 sync で再判定すべき）・
+ * 400 config_md_kind_mismatch（＝同じ本文を再送しても永久に通らない）・
+ * 通信失敗（＝そもそも届いていない）を区別する必要があり、真偽値では表現できない。
+ * また `claude_md_updated_at` をメタへ記録するためにレスポンス本文も要る。
+ *
+ * @returns {Promise<{ok: boolean, status: number|null, data: object|null,
+ *                    error: object|null}>}
+ *          status は通信自体が失敗した場合のみ null。
+ *          error は非 OK 時の allowlist 済み拒否理由（取れなければ null）。
  */
-async function putHubClaudeMd({ hubUrl, accessToken, dirName, body, fetchImpl, logger }) {
+async function putHubClaudeMd({
+  hubUrl,
+  accessToken,
+  dirName,
+  body,
+  expectedHash,
+  fetchImpl,
+  logger,
+  timeoutMs = HUB_REQUEST_TIMEOUT_MS,
+}) {
   const f = fetchImpl || globalThis.fetch
-  if (!f) return false
+  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 }
+  // headers 受信から body 消費までを 1 本の期限に収める（別々に張ると、
+  // headers だけ返して body を閉じない応答で結局止まる）。
+  const deadline = createDeadline(timeoutMs)
   try {
-    const res = await f(url, {
-      method: "PUT",
-      headers: {
-        Authorization: `Bearer ${accessToken}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ claude_md: body }),
-    })
+    const fetched = await deadline.guard(
+      Promise.resolve().then(() =>
+        f(url, {
+          method: "PUT",
+          headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify(payload),
+          signal: deadline.signal,
+        }),
+      ),
+    )
+    if (fetched.timedOut) {
+      logger?.warn?.(
+        { dirName, timeout_ms: timeoutMs },
+        "putHubClaudeMd: round-trip timed out; giving up (best-effort sync)",
+      )
+      return { ok: false, status: null, data: null, error: null }
+    }
+    if (fetched.error) throw fetched.error
+    const res = fetched.value
     if (!res.ok) {
+      const diag = await readNonOkDiagnostics(res, deadline)
       logger?.warn?.(
-        { dirName, status: res.status },
+        {
+          dirName,
+          status: res.status,
+          content_type: diag.contentType,
+          body_bytes: diag.bodyBytes,
+          ...(diag.declaredLength !== null ? { declared_length: diag.declaredLength } : {}),
+          // 完全長は分からないが「上限より大きい」ことは分かる、という記録。
+          ...(diag.bodyTooLarge ? { body_too_large: true } : {}),
+          ...(diag.timedOut ? { body_read_timed_out: true } : {}),
+          // allowlist で絞った拒否理由のみ。取れなければ本文は一切出さない。
+          ...(diag.fields || {}),
+        },
         "putHubClaudeMd: non-OK response",
       )
-      return false
+      return { ok: false, status: res.status ?? null, data: null, error: diag.fields }
     }
-    return true
+    // 成功時の本文読み取りにも同じ期限を掛ける。読めなければ data=null のまま返し、
+    // 呼び出し側が「updated_at が取れない」として skip する（メタは進めない）。
+    const parsed = await deadline.guard(Promise.resolve().then(() => res.json()))
+    let data = null
+    if (parsed.timedOut) {
+      deadline.abort()
+      logger?.warn?.(
+        { dirName, timeout_ms: timeoutMs },
+        "putHubClaudeMd: response body read timed out",
+      )
+    } else if (!parsed.error) {
+      data = parsed.value // 本文が読めなくても PUT 自体は成功している
+    }
+    return { ok: true, status: res.status ?? 200, data, error: null }
   } catch (err) {
     logger?.warn?.(
       { dirName, err: err?.message || String(err) },
       "putHubClaudeMd: request failed",
     )
-    return false
+    return { ok: false, status: null, data: null, error: null }
+  } finally {
+    deadline.clear()
   }
 }
 
+/**
+ * PUT レスポンスから「サーバーが実際に記録した更新時刻」を取り出す。
+ *
+ * 取れなければ null。呼び出し側は null のときメタを書かずに skip する
+ * （端末時刻などの推測値を書くと、ずれがメタに固定されて後から追えなくなる）。
+ */
+function putResponseUpdatedAt(data) {
+  const v = data?.claude_md_updated_at
+  return typeof v === "string" && v ? v : null
+}
+
 async function readLocalConfigMd(targetDir, configFilename) {
   try {
     return await fs.readFile(path.join(targetDir, configPaths(configFilename).filename), "utf-8")
@@ -161,13 +563,38 @@ async function readMeta(targetDir, configFilename) {
   return await readJsonOrNull(metaPath)
 }
 
+/**
+ * 一時ファイルへ書いてから rename する（同一ディレクトリ内なので rename は原子的）。
+ *
+ * 途中で電源断・プロセス kill が起きても、**半端な内容のファイルが見えない**。
+ * meta / base はどちらも「次回 sync の判定材料」なので、壊れた中身が残ると
+ * 判定そのものが狂う。
+ * ⚠️ 一時ファイル名は `.cockpit-sync/` 直下に作るが、`bakNamePattern` は
+ * `makeBakName` の形にしか一致しないため .bak の FIFO 削除には巻き込まれない。
+ */
+async function writeFileAtomic(filePath, content) {
+  const tmp = `${filePath}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`
+  try {
+    // ⚠️ writeFile と rename を同じ try に入れること。writeFile は「一時ファイルを
+    // 作って一部を書いた後」に ENOSPC / quota / I/O エラーで失敗しうるので、
+    // cleanup を rename の catch にだけ置くと **一時ファイルが残る**。再試行のたびに
+    // 別名で増えるため、ディスク枯渇からの回復をさらに難しくする。
+    await fs.writeFile(tmp, content, "utf-8")
+    await fs.rename(tmp, filePath)
+  } catch (err) {
+    // rename 成功後はここへ来ない（＝確定済みファイルを cleanup 対象にしない）。
+    // cleanup 自体の失敗で元の書込エラーを **上書きしない** よう握り潰す。
+    await fs.unlink(tmp).catch(() => {})
+    throw err
+  }
+}
+
 async function writeMeta(targetDir, meta, configFilename) {
   const metaDir = path.join(targetDir, META_DIR)
   await fs.mkdir(metaDir, { recursive: true })
-  await fs.writeFile(
+  await writeFileAtomic(
     path.join(metaDir, configPaths(configFilename).metaFile),
     JSON.stringify(meta, null, 2),
-    "utf-8",
   )
 }
 
@@ -185,7 +612,88 @@ async function writeBaseBody(targetDir, body, configFilename) {
   if (body == null) return
   const metaDir = path.join(targetDir, META_DIR)
   await fs.mkdir(metaDir, { recursive: true })
-  await fs.writeFile(path.join(metaDir, configPaths(configFilename).baseFile), body, "utf-8")
+  await writeFileAtomic(path.join(metaDir, configPaths(configFilename).baseFile), body)
+}
+
+/** `.cockpit-sync/<name>.base` を読む。無ければ null。 */
+async function readBaseBody(targetDir, configFilename) {
+  try {
+    return await fs.readFile(
+      path.join(targetDir, META_DIR, configPaths(configFilename).baseFile),
+      "utf-8",
+    )
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 同期成功時の状態を **base → meta の順で** 書く（成功経路はすべてこれを通す）。
+ *
+ * ⚠️ 2 ファイルの書込は原子的にできない。**meta は「判定の commit marker」**なので、
+ * meta を先に書くと base の書込が失敗しても「もう同期済み」と見なされ、次回 sync は
+ * 通常 noop に入って **base が壊れたまま永久に固定される**（base が誤って
+ * ディレクトリになっている / ディスク枯渇 / 個別ファイルの権限などで実際に起きる）。
+ *
+ * base を先に書けば、失敗しても meta は古いままなので、次回 sync が変化 / 収束を
+ * 検出して丸ごとやり直せる。逆順で生まれる「base だけ新しい」中間状態は、
+ * 次回 sync の再収束で解消する（同期の判定は meta しか見ないため無害）。
+ *
+ * meta には `baseHash`（＝いま書いた base の hash）を残す。読み手（session-end の
+ * 3-way merge / 下の noop 経路）が「disk 上の base が meta の言うとおりの中身か」を
+ * 突き合わせられるようにするため。
+ */
+async function writeSyncState(targetDir, { body, meta }, configFilename) {
+  await writeBaseBody(targetDir, body, configFilename)
+  await writeMeta(
+    targetDir,
+    body == null ? { ...meta } : { ...meta, baseHash: sha256(body) },
+    configFilename,
+  )
+}
+
+/**
+ * meta の `baseHash` と disk 上の base を突き合わせ、食い違っていれば base を書き直す。
+ *
+ * 直せるのは「いまローカルにある本文が、meta が指す同期済み本文と一致している」ときだけ
+ * （＝ base に入るべき中身が確定しているとき）。それ以外は触らない — 中身が確定しない
+ * まま書くと、3-way merge の base に嘘を置くことになる。
+ *
+ * @returns {Promise<boolean>} 書き直したら true
+ */
+async function repairBaseIfInconsistent({
+  targetDir,
+  configFilename,
+  meta,
+  localBody,
+  localCurrentHash,
+  logger,
+  dirName,
+}) {
+  // baseHash は writeSyncState が付ける。旧バージョンが書いた meta には無いので、
+  // その場合は判定材料が無い＝触らない（勝手に書き直さない）。
+  if (!meta || typeof meta.baseHash !== "string" || !meta.baseHash) return false
+  if (localBody == null || localCurrentHash !== meta.lastSyncedHash) return false
+  const base = await readBaseBody(targetDir, configFilename)
+  if (base !== null && sha256(base) === meta.baseHash) return false // 整合している
+  try {
+    await writeSyncState(
+      targetDir,
+      { body: localBody, meta: { ...meta, lastSyncedAt: nowIso() } },
+      configFilename,
+    )
+  } catch (err) {
+    logger?.warn?.(
+      { dirName, err: err?.message || String(err) },
+      "syncClaudeMdWithHub: base repair failed (will retry next sync)",
+    )
+    return false
+  }
+  logger?.warn?.(
+    { dirName, base_missing: base === null },
+    "syncClaudeMdWithHub: base file was inconsistent with meta; rewrote it",
+  )
+  return true
 }
 
 /**
@@ -203,9 +711,12 @@ async function backupLocalConfigMd(targetDir, body, kind, configFilename) {
   const bakName = makeBakName(prefix)
   await fs.writeFile(path.join(metaDir, bakName), body, "utf-8")
   // 同 prefix の .bak を新しい順に BAK_KEEP 件まで残す。
+  // 対象は「hub-agent が makeBakName で作った、この kind の .bak」だけに限定する
+  // （conflict 退避や手作業で置かれた異物を巻き添えにしないため。bakNamePattern 参照）。
+  const pattern = bakNamePattern(prefix)
   const entries = await fs.readdir(metaDir).catch(() => [])
   const sameKind = entries
-    .filter((n) => n.startsWith(`${prefix}.`) && n.endsWith(".bak"))
+    .filter((n) => pattern.test(n))
     .sort() // 名前にタイムスタンプを含むので辞書順 ≒ 時系列順
     .reverse() // 新しい順
   const obsolete = sameKind.slice(BAK_KEEP)
@@ -226,6 +737,8 @@ async function backupLocalConfigMd(targetDir, body, kind, configFilename) {
  * @param {string} [args.accessToken]   省略時は ~/.claude/.hub_token.json から
  * @param {object} [args.logger]
  * @param {Function} [args.fetchImpl]   テスト注入用
+ * @param {number} [args.requestTimeoutMs] Hub API 1 往復の期限（既定
+ *   `HUB_REQUEST_TIMEOUT_MS`）。テスト注入・低速環境の調整用。
  * @returns {Promise<{ action: 'pull'|'push'|'conflict'|'noop'|'skipped', reason?: string }>}
  */
 export async function syncClaudeMdWithHub({
@@ -236,6 +749,7 @@ export async function syncClaudeMdWithHub({
   logger,
   fetchImpl,
   configFilename = "CLAUDE.md",
+  requestTimeoutMs = HUB_REQUEST_TIMEOUT_MS,
 } = {}) {
   if (!targetDir) throw new Error("syncClaudeMdWithHub requires targetDir")
   if (!dirName) throw new Error("syncClaudeMdWithHub requires dirName")
@@ -255,6 +769,7 @@ export async function syncClaudeMdWithHub({
     dirName,
     fetchImpl,
     logger,
+    timeoutMs: requestTimeoutMs,
   })
   if (!hub) {
     return { action: "skipped", reason: "hub-not-resolvable" }
@@ -304,57 +819,140 @@ export async function syncClaudeMdWithHub({
       localCurrentHash != null && localCurrentHash !== meta.lastSyncedHash
   }
 
-  // 同じ内容で書き込まれている（hash 一致）なら衝突扱いせず noop に降格。
+  // 同じ内容で書き込まれている（hash 一致）＝内容はすでに収束している。
+  //
+  // ⚠️ ここで「noop に降格」するだけで meta を放置すると、**内容は同じなのに同期基準
+  // だけが古い**状態が固定化する。その後 Hub 側だけを編集すると、meta が古いせいで
+  // localChanged も true と判定され、hash 不一致 → conflict → 端末勝者で PUT となり
+  // **Hub 側の編集が消える**（実際に踏んだ経路: PUT 成功だが updated_at が取れず
+  // meta 未更新 → 次回この分岐 → さらに次で Hub 編集を上書き）。
+  // よってこの分岐は「収束を確定させる自己修復」にする。
   if (hubChanged && localChanged && hubHash && hubHash === localCurrentHash) {
-    hubChanged = false
-    localChanged = false
+    // ⚠️ 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",
+    )
+    return { action: "noop", reason: "converged-untrusted-payload" }
   }
 
   // 4) アクション決定
   if (!hubChanged && !localChanged) {
-    return { action: "noop" }
+    // 変化は無いが、**base が meta の言うとおりの中身か**だけ確かめる。
+    // base の書込だけが失敗した中間状態（base → meta の順で書くので meta が古く
+    // 残る）は次回の変化検出で解消するが、同期後に base が壊された / 消された
+    // ケースはここでしか気づけない。3-way merge が壊れた base を使うのを防ぐ。
+    const repaired = await repairBaseIfInconsistent({
+      targetDir,
+      configFilename,
+      meta,
+      localBody,
+      localCurrentHash,
+      logger,
+      dirName,
+    })
+    return repaired ? { action: "noop", reason: "base-repaired" } : { action: "noop" }
   }
 
   if (hubChanged && !localChanged) {
     // pull: ローカルを .bak 退避 → Hub の本文で上書き
     await backupLocalConfigMd(targetDir, localBody, "normal", configFilename)
     await writeLocalConfigMd(targetDir, hubBody, configFilename)
-    await writeMeta(targetDir, {
-      lastSyncedHubUpdatedAt: hubUpdatedAt,
-      lastSyncedHash: hubHash || sha256(hubBody),
-      lastSyncedAt: nowIso(),
-    }, configFilename)
     // 3-way merge 用 base: pull 直後はローカル == Hub なので Hub 本文を base に。
-    await writeBaseBody(targetDir, hubBody, configFilename)
+    // base → meta の順で書く（writeSyncState の JSDoc 参照）。
+    await writeSyncState(targetDir, {
+      body: hubBody,
+      meta: {
+        lastSyncedHubUpdatedAt: hubUpdatedAt,
+        lastSyncedHash: hubHash || sha256(hubBody),
+        lastSyncedAt: nowIso(),
+      },
+    }, configFilename)
     logger?.info?.({ dirName }, "syncClaudeMdWithHub: pull")
     return { action: "pull" }
   }
 
   if (!hubChanged && localChanged) {
     // push: Hub に PUT。成功時にメタ更新。
-    const ok = await putHubClaudeMd({
+    const put = await putHubClaudeMd({
       hubUrl: url,
       accessToken: token,
       dirName,
       body: localBody || "",
+      // 楽観ロック: この sync が GET で読んだ時点の hash を渡す。読んだ後に Hub が
+      // 動いていれば backend が 409 を返すので、盲目的な上書きにならない。
+      expectedHash: hubHash || undefined,
       fetchImpl,
       logger,
+      timeoutMs: requestTimeoutMs,
     })
-    if (!ok) {
+    if (!put.ok) {
+      if (put.status === 409) {
+        // 409 = 読んだ後に Hub 側が動いた。通信失敗ではないので理由を分ける。
+        // メタは更新せず、次回 sync で hubChanged 込みで判定し直す。
+        logger?.warn?.(
+          { dirName },
+          "syncClaudeMdWithHub: push rejected by optimistic lock (hub moved); retry next sync",
+        )
+        return { action: "skipped", reason: "hub-put-stale" }
+      }
+      if (put.error?.error === "config_md_kind_mismatch") {
+        // CLI 種別の取り違え（AGENTS.md の内容を CLAUDE.md 正本へ送った等）。
+        // 同じ本文を再送しても永久に通らないので、リトライ前提の通信失敗と混ぜない。
+        logger?.warn?.(
+          { dirName, ...put.error },
+          "syncClaudeMdWithHub: push rejected (config md kind mismatch); resending the same body will keep failing",
+        )
+        return { action: "skipped", reason: "hub-put-kind-mismatch" }
+      }
       return { action: "skipped", reason: "hub-put-failed" }
     }
-    await writeMeta(targetDir, {
-      // PUT 後の Hub.updated_at は再度 GET しないと厳密には取れないため、
-      // 「ローカル hash と Hub.updated_at は別途次回 sync で再同期」する設計。
-      // ここでは「今 push したぶんは Hub に反映済み」として、現在のローカル
-      // hash と「今の時刻」をメタに記録する（次回 sync 時に再判定可能）。
-      lastSyncedHubUpdatedAt: nowIso(),
-      lastSyncedHash: localCurrentHash,
-      lastSyncedAt: nowIso(),
-    }, configFilename)
+    // 次回 sync の hubChanged 判定は lastSyncedHubUpdatedAt との文字列比較なので、
+    // 端末の時刻ではなく **サーバーが返した実際の値** を入れないと必ず不一致になる
+    // （Django はマイクロ秒 6 桁 / nowIso() はミリ秒 3 桁）。
+    const putUpdatedAt = putResponseUpdatedAt(put.data)
+    if (!putUpdatedAt) {
+      // 推測値を書かない。書かなければ次回 sync でやり直せる。
+      logger?.warn?.(
+        { dirName },
+        "syncClaudeMdWithHub: PUT succeeded but response had no claude_md_updated_at; meta not updated",
+      )
+      return { action: "skipped", reason: "hub-put-missing-updated-at" }
+    }
     // 3-way merge 用 base: push 直後は Hub の正本がローカルと一致するので、
-    // 次回の base は今 push した本文 (= localBody)。
-    await writeBaseBody(targetDir, localBody || "", configFilename)
+    // 次回の base は今 push した本文 (= localBody)。base → meta の順で書く。
+    await writeSyncState(targetDir, {
+      body: localBody || "",
+      meta: {
+        // lastSyncedHubUpdatedAt は「Hub 側の版を指す識別子」で、次回 sync の
+        // hubChanged 判定に使う。必ずサーバー値を入れること。
+        lastSyncedHubUpdatedAt: putUpdatedAt,
+        lastSyncedHash: localCurrentHash,
+        // lastSyncedAt は「この端末がいつ同期したか」の記録で、判定には使わない。
+        // 用途が違うので putUpdatedAt と混同しないこと。
+        lastSyncedAt: nowIso(),
+      },
+    }, configFilename)
     logger?.info?.({ dirName }, "syncClaudeMdWithHub: push")
     return { action: "push" }
   }
@@ -362,25 +960,56 @@ export async function syncClaudeMdWithHub({
   // hubChanged && localChanged → 衝突。端末側を勝者にして Hub に PUT。
   // Hub の取り込み内容は .bak.conflict に退避（後で人手マージできるよう）。
   await backupLocalConfigMd(targetDir, hubBody, "conflict", configFilename)
-  const ok = await putHubClaudeMd({
+  const put = await putHubClaudeMd({
     hubUrl: url,
     accessToken: token,
     dirName,
     body: localBody || "",
+    // push 経路と同じく、GET 時点の hash で楽観ロックを効かせる。
+    expectedHash: hubHash || undefined,
     fetchImpl,
     logger,
+    timeoutMs: requestTimeoutMs,
   })
-  if (!ok) {
+  if (!put.ok) {
     // PUT 失敗時はメタを更新しない（次回再試行）。ローカルは無傷。
+    if (put.status === 409) {
+      logger?.warn?.(
+        { dirName },
+        "syncClaudeMdWithHub: conflict push rejected by optimistic lock (hub moved); retry next sync",
+      )
+      return { action: "skipped", reason: "hub-put-stale-in-conflict" }
+    }
+    if (put.error?.error === "config_md_kind_mismatch") {
+      // push 経路と同じ理由（再送しても通らない拒否）。通信失敗と区別する。
+      logger?.warn?.(
+        { dirName, ...put.error },
+        "syncClaudeMdWithHub: conflict push rejected (config md kind mismatch); resending the same body will keep failing",
+      )
+      return { action: "skipped", reason: "hub-put-kind-mismatch-in-conflict" }
+    }
     return { action: "skipped", reason: "hub-put-failed-in-conflict" }
   }
-  await writeMeta(targetDir, {
-    lastSyncedHubUpdatedAt: nowIso(),
-    lastSyncedHash: localCurrentHash,
-    lastSyncedAt: nowIso(),
-  }, configFilename)
+  const putUpdatedAt = putResponseUpdatedAt(put.data)
+  if (!putUpdatedAt) {
+    logger?.warn?.(
+      { dirName },
+      "syncClaudeMdWithHub: conflict PUT succeeded but response had no claude_md_updated_at; meta not updated",
+    )
+    return { action: "skipped", reason: "hub-put-missing-updated-at-in-conflict" }
+  }
   // 3-way merge 用 base: conflict push 後の Hub 正本は端末側本文 (= localBody)。
-  await writeBaseBody(targetDir, localBody || "", configFilename)
+  // base → meta の順で書く（writeSyncState の JSDoc 参照）。
+  await writeSyncState(targetDir, {
+    body: localBody || "",
+    meta: {
+      // push 経路と同じ理由でサーバー値を使う（端末時刻を入れると次回必ず hubChanged）。
+      lastSyncedHubUpdatedAt: putUpdatedAt,
+      lastSyncedHash: localCurrentHash,
+      // lastSyncedAt は端末側の同期時刻。判定には使わない。
+      lastSyncedAt: nowIso(),
+    },
+  }, configFilename)
   logger?.warn?.(
     { dirName },
     "syncClaudeMdWithHub: conflict (terminal wins); hub body saved to .bak.conflict",
@@ -391,7 +1020,19 @@ export async function syncClaudeMdWithHub({
 // メタ操作・ハッシュ計算は ensureClaudeMd 側 (Hub pull 初回配信) でも使うため
 // named export する。同じファイルパス・同じスキーマで管理することで、初回配信と
 // 以降の sync で食い違いを起こさない。
-export { sha256, readMeta, writeMeta, writeBaseBody, nowIso, configPaths }
+// ⚠️ 新規の呼び出し元は `writeMeta` / `writeBaseBody` を個別に呼ばず
+// **`writeSyncState` を使うこと**（base → meta の順序と baseHash の付与を一箇所に
+// 集約するため。順序を誤ると base 書込失敗時に永久に再修復されない）。
+export {
+  sha256,
+  readMeta,
+  writeMeta,
+  writeBaseBody,
+  writeSyncState,
+  readBaseBody,
+  nowIso,
+  configPaths,
+}
 
 // 内部テスト用エクスポート
 export const _internals = {
@@ -399,7 +1040,13 @@ export const _internals = {
   readMeta,
   writeMeta,
   writeBaseBody,
+  writeSyncState,
+  readBaseBody,
   backupLocalConfigMd,
   BAK_KEEP,
   configPaths,
+  // 「生成する名前」と「FIFO 対象を選ぶ正規表現」が食い違うと保持ロジックが静かに
+  // 壊れるため、両者を突き合わせるテストから参照できるように公開する。
+  makeBakName,
+  bakNamePattern,
 }