@cocorograph/hub-agent 0.8.38 → 0.8.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.8.38",
+  "version": "0.8.40",
   "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの Claude / Codex チャットと tmux セッションを中継する。",
   "type": "module",
   "license": "UNLICENSED",

package/src/claude-md-sync.mjs

@@ -1,16 +1,23 @@
 /**
- * Hub 正本 (Project.claude_md) と workspace ローカル CLAUDE.md の双方向同期。
+ * Hub 正本 (Project.claude_md) と workspace ローカル CLAUDE.md の同期。
  *
- * 方針: 双方向 last-write-wins + 履歴。
+ * 方針: **受け取り専用**（Hub → 端末の一方向。唯一の例外が下記「初回登録」）。
  * - Hub 側更新 → 端末 pull（ローカルを `.bak.<ts>` 退避してから全文上書き）
- * - 端末側更新 → Hub に PUT（Hub 側は履歴に直前版を積む。directly handled by backend）
- * - 両方変化（衝突）→ 端末側を勝者にして Hub に PUT、Hub の取り込み内容は
- *   `.bak.conflict.<ts>` に退避（後で人手マージできるよう保存）
+ * - 端末側更新 → **何もしない**（PUT せず、ローカルも黙って上書きしない）。
+ *   warn ＋ `config-md-receive-only-drift` で乖離を見える形に残す
+ * - 両方変化 → 同上（端末を勝者にしない）
  * - どちらも変化なし → no-op
  *
+ * ⚠️ 2026-08-09 までは双方向 last-write-wins（端末側更新は PUT、両方変化は端末勝者で
+ * PUT ＋ Hub 本文を `.bak.conflict.<ts>` へ退避）だった。Hub の正本がプレースホルダ入り
+ * になり、GET が CLI 別のレンダリング結果を返すようになったため、端末が持つ本文を
+ * 送り返すと必ず正本を平坦化する（backend が 400 で拒否し、`.bak.conflict` だけが
+ * 溜まる）。**正本を直すのは Hub 側**（AI が MCP / API 経由で更新する）。
+ *
  * 初回（メタファイル無し）: **端末を勝たせない**（唯一の例外が下記「初回登録」）。
  * - ローカルが空でも非空でも、Hub 本文があれば pull。手元は `.bak` へ退避するので
- *   失われない。戻せば meta が入り、次回以降は通常どおり端末側が push される。
+ *   失われない（受け取り専用にした後は、戻しても push されないので **取り込みは
+ *   Hub 側の正本を直して行う**）。
  * - 出どころ（自動生成物か手書きか）を判定材料にしない。かつては sidecar
  *   （自動生成本文の hash）を置いて見分けていたが、**判定に使う箇所は 1 か所なのに
  *   書く / 消す箇所が 6 か所**あり、「消費できたか」がファイル削除の成否に依存する
@@ -23,6 +30,23 @@
  * 詳細な条件と、なぜ `localFilePreexisted` を永続化しないのかは
  * `syncClaudeMdWithHub` 内の `isInitialRegistration` のコメントを参照。
  *
+ * **ローカルの設定ファイルは受け取り専用**（2026-08-09）。Hub の正本は
+ * `Project.claude_md` 1 本（プレースホルダ入り）で、GET は `cli_kind` に応じて CLI 別へ
+ * レンダリングして返す。端末に置かれる **CLAUDE.md も AGENTS.md もその
+ * レンダリング結果**であって正本ではないので、
+ * - GET には必ず `cli_kind` を載せる（載せないと Codex が CLAUDE.md 向け本文を掴む）
+ * - **PUT は初回登録を除いて一切行わない**（push / conflict のどちらも）。乖離は
+ *   warn ＋ `config-md-receive-only-drift` で見える形にし、ローカルも黙って上書きしない
+ * - 正本を直すのは **Hub 側**（AI が MCP / API 経由で更新する）。端末の編集は次回
+ *   pull で上書きされる前に `.bak` へ退避されるので失われない
+ * ⚠️ 初版（同日）は AGENTS.md だけを対象にしていたが、それは実装漏れだった。CLAUDE.md も
+ * 同じ経路を通り、送ると backend の平坦化ガードに 400 `config_md_flattened` で弾かれ、
+ * `.bak.conflict` だけが毎セッション積み上がる。詳細は `syncClaudeMdWithHub` 内の
+ * 受け取り専用ガードのコメント。
+ * `cli_kind` を載せていなかった頃に作られた壊れた同期状態（AGENTS.md の base に
+ * CLAUDE.md 本文が入っている）は、sync の冒頭で meta / base を捨てて初回 sync へ戻す
+ * （`migrateBrokenAgentsBase`）。
+ *
  * 失敗時のポリシー: ローカル CLAUDE.md は触らない（warn ログ + skip）。
  * session 起動を止めない（ensureClaudeMd と同じく best-effort）。
  *
@@ -58,6 +82,35 @@ function configPaths(configFilename = "CLAUDE.md") {
   }
 }
 
+/**
+ * backend へ渡す `cli_kind`（レンダリング先の CLI 種別）を設定ファイル名から導出する。
+ *
+ * Hub は `Project.claude_md` を唯一の正本として持ち、**GET のたびに CLI 別へ
+ * レンダリングして返す**（`cli_kind=codex` なら AGENTS.md 向け）。省略すると
+ * `claude` 扱いになるため、Codex セッションで載せ忘れると **CLAUDE.md 向けの本文を
+ * AGENTS.md へ書き込む**ことになる（実際にそうなっていた）。
+ *
+ * ⚠️ 判定は `configPaths().filename` を通す（`configFilename` の生値で分岐すると、
+ * 未知の値の扱いがこの関数とファイル名解決とで食い違う）。
+ */
+function cliKindForConfig(configFilename) {
+  return configPaths(configFilename).filename === "AGENTS.md" ? "codex" : "claude"
+}
+
+/**
+ * `claude-md-by-dir` の URL を組み立てる（GET / PUT 共通）。
+ *
+ * ⚠️ `cliKind` は **GET のときだけ** 渡す。PUT はレンダリング結果ではなく正本そのものを
+ * 送る経路で、backend 側の解釈が GET と同じとは限らないため、こちらの都合で
+ * 勝手にパラメータを増やさない。
+ */
+function claudeMdByDirUrl({ hubUrl, dirName, cliKind }) {
+  const base =
+    `${hubUrl.replace(/\/+$/, "")}/api/admin/project/claude-md-by-dir/` +
+    `?dir_name=${encodeURIComponent(dirName)}`
+  return cliKind ? `${base}&cli_kind=${encodeURIComponent(cliKind)}` : base
+}
+
 async function readJsonOrNull(p) {
   try {
     const text = await fs.readFile(p, "utf-8")
@@ -298,14 +351,19 @@ async function fetchHubClaudeMd({
   dirName,
   fetchImpl,
   logger,
+  configFilename = "CLAUDE.md",
   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)}`
+  // ⚠️ `cli_kind` を必ず載せる。省略すると backend は claude 向けにレンダリングする
+  // ので、Codex セッションが CLAUDE.md 向け本文を AGENTS.md の正本として掴む。
+  const url = claudeMdByDirUrl({
+    hubUrl,
+    dirName,
+    cliKind: cliKindForConfig(configFilename),
+  })
   const deadline = acquireDeadline(budget, timeoutMs)
   try {
     const fetched = await deadline.guard(
@@ -571,9 +629,7 @@ async function putHubClaudeMd({
 }) {
   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)}`
+  const url = claudeMdByDirUrl({ hubUrl, dirName })
   // expected_hash は **string なら必ず載せる（空文字を含む）**。
   //
   // ⚠️ 空文字は「Hub が空であることを期待する」という **有効な CAS トークン**である。
@@ -668,6 +724,97 @@ function putResponseUpdatedAt(data) {
   return typeof v === "string" && v ? v : null
 }
 
+/**
+ * **同じ本文を再送しても永久に通らない** 400 拒否の一覧（backend の `error` 値 → reason）。
+ *
+ * リトライ前提の通信失敗（`hub-put-failed`）と混ぜないために分ける。理由文字列は
+ * 拒否ごとに変える — 「CLI 種別を取り違えた」と「プレースホルダを失った平坦化本文を
+ * 送った」は原因も直し方も違うので、ログと戻り値で区別できないと調査が止まる。
+ *
+ * - `config_md_kind_mismatch` … CLAUDE.md の正本へ AGENTS.md の内容を送った等
+ * - `config_md_flattened` … レンダリング結果（プレースホルダが展開済み）を正本として
+ *   送った。正本にはあるプレースホルダが保存本文に無いので backend が拒否する
+ */
+const PERMANENT_PUT_REJECTIONS = {
+  config_md_kind_mismatch: "hub-put-kind-mismatch",
+  config_md_flattened: "hub-put-flattened",
+}
+
+/**
+ * PUT の拒否理由が「再送しても通らない種類」なら、その reason を返す（違えば null）。
+ *
+ * ⚠️ 判定は 1 か所に束ねる（push 経路と conflict 経路で条件が分岐すると、片方だけ
+ * 新しい拒否理由に対応していない状態が生まれる）。呼び出し側は接尾辞を足すだけ。
+ */
+function permanentPutRejectionReason(putError) {
+  const key = putError?.error
+  return (typeof key === "string" && PERMANENT_PUT_REJECTIONS[key]) || null
+}
+
+/**
+ * 「AGENTS.md の base に CLAUDE.md 本文が入っている」壊れた同期状態か。
+ *
+ * `cli_kind` を載せずに GET していた頃、Codex セッションは CLAUDE.md 向けの本文を
+ * 掴んで AGENTS.md 系の base / meta に書いていた。その base を残したまま新しい
+ * （AGENTS.md 向けにレンダリングされた）本文を受け取ると、3-way merge の base が
+ * 別 CLI の本文を指したままになる。
+ *
+ * ⚠️ 判定は **先頭の意味のある行**（空行を飛ばした最初の行）だけで行い、meta の
+ * `baseHash` の有無に依存させない。実端末の `agents-md.json` には `baseHash` キーが
+ * 無い（旧バージョンが書いた meta）ため、それを条件にすると移行が発火しない。
+ */
+function looksLikeClaudeMdBody(text) {
+  if (typeof text !== "string") return false
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trim()
+    if (line === "") continue
+    return /^#{1,6}\s*CLAUDE\.md\b/.test(line)
+  }
+  return false
+}
+
+/**
+ * 壊れた AGENTS.md の同期状態（base に CLAUDE.md 本文）を捨てて、次回を初回 sync に戻す。
+ *
+ * 1. ローカル本文を `.bak` へ退避（手元の内容を失わせない）
+ * 2. meta → base の順で削除する。**meta を先に消す**のは、meta だけ残ると
+ *    `repairBaseIfInconsistent` が「ローカル本文で base を書き直す」経路に入り、
+ *    壊れた base を作り直しかねないため
+ *
+ * 呼び出し側はこの回をそこで終える（同一実行内で続けて判定しない ＝ 中間状態を作らない）。
+ *
+ * @returns {Promise<boolean>} 移行を実行したら true
+ */
+async function migrateBrokenAgentsBase({ targetDir, configFilename, logger, dirName }) {
+  const { filename, metaFile, baseFile } = configPaths(configFilename)
+  if (filename !== "AGENTS.md") return false
+  const base = await readBaseBody(targetDir, configFilename)
+  if (!looksLikeClaudeMdBody(base)) return false
+
+  const localBody = await readLocalConfigMd(targetDir, configFilename)
+  await backupLocalConfigMd(targetDir, localBody, "normal", configFilename)
+  const metaDir = path.join(targetDir, META_DIR)
+  const unlinkIfPresent = async (name) => {
+    try {
+      await fs.unlink(path.join(metaDir, name))
+    } catch (err) {
+      if (err?.code !== "ENOENT") throw err
+    }
+  }
+  await unlinkIfPresent(metaFile)
+  await unlinkIfPresent(baseFile)
+  logger?.warn?.(
+    {
+      dirName,
+      config_filename: filename,
+      base_bytes: Buffer.byteLength(base, "utf-8"),
+      local_backed_up: localBody != null,
+    },
+    "syncClaudeMdWithHub: AGENTS.md sync state held CLAUDE.md content; discarded meta/base so the next sync starts fresh",
+  )
+  return true
+}
+
 async function readLocalConfigMd(targetDir, configFilename) {
   try {
     return await fs.readFile(path.join(targetDir, configPaths(configFilename).filename), "utf-8")
@@ -946,15 +1093,35 @@ export async function syncClaudeMdWithHub({
     )
     return { action: "skipped", reason: "budget-exhausted" }
   }
+
+  // 0) 壊れた同期状態（AGENTS.md の base に CLAUDE.md 本文）の移行。
+  //
+  // ⚠️ **通信より前・判定より前**に置き、実行したらその回はそこで終える。同一実行内で
+  // 続けて判定すると「meta を消した直後の初回 sync」が同じ回に走り、移行が中途半端に
+  // 効いた中間状態を作る（次回セッションの初回 sync で pull させれば足りる）。
+  try {
+    if (await migrateBrokenAgentsBase({ targetDir, configFilename, logger, dirName })) {
+      return { action: "skipped", reason: "agents-md-base-migrated" }
+    }
+  } catch (err) {
+    // 退避 / 削除に失敗した回は同期を進めない（壊れた base を基準に使わせない）。
+    logger?.warn?.(
+      { dirName, err: err?.message || String(err) },
+      "syncClaudeMdWithHub: failed to discard the broken AGENTS.md sync state; skip (retry next sync)",
+    )
+    return { action: "skipped", reason: "agents-md-base-migration-failed" }
+  }
+
   const url = hubUrl || DEFAULT_HUB_API
 
-  // 1) Hub の正本を取得
+  // 1) Hub の正本を取得（`cli_kind` を載せて CLI 別レンダリング結果を受け取る）
   const hub = await fetchHubClaudeMd({
     hubUrl: url,
     accessToken: token,
     dirName,
     fetchImpl,
     logger,
+    configFilename,
     timeoutMs: requestTimeoutMs,
     budget,
   })
@@ -1083,6 +1250,11 @@ export async function syncClaudeMdWithHub({
 
   // --- 初回登録: 「Hub に無くローカルにある」ものを一度だけ Hub へ取り込む -------
   //
+  // ⚠️ 2026-08-09 以降、**これが PUT を発行する唯一の経路**（受け取り専用ガードの
+  // 唯一の例外）。両立する理由は下の受け取り専用ガードのコメントに書いてある
+  // （要約: 正本が空なら端末の本文は「正本のレンダリング結果」ではありえないので、
+  // 送っても正本を平坦化しない ＝ 上書きではなく種付け）。
+  //
   // 条件は **すべて** 満たすときだけ:
   //   - meta が無い（この端末はまだ一度も同期していない）
   //   - Hub 本文が空（**等値比較のみ**。`updated_at` の有無は問わない）
@@ -1291,11 +1463,78 @@ export async function syncClaudeMdWithHub({
     return { action: "pull" }
   }
 
+  // ---- ローカルの設定ファイルは受け取り専用（ここから下は必ず localChanged === true）
+  //
+  // Hub は `Project.claude_md`（プレースホルダ入りの正本）を CLI 別にレンダリングして
+  // 返す。端末の **CLAUDE.md も AGENTS.md もそのレンダリング結果**であって正本では
+  // ないので、端末側で編集されたからといって Hub へ送り返してはいけない（正本に
+  // プレースホルダが残っていても、送るのは展開済みの平坦な本文になる ＝ backend の
+  // 平坦化ガードに 400 `config_md_flattened` で弾かれる）。
+  //
+  // ⚠️ **設定ファイルの種別で分岐しない**。初版（2026-08-09）は
+  // `filename === "AGENTS.md"` で絞っていたが、合意した設計は
+  // 「ローカルは常に受け取るだけ。AI が Hub の正本を更新する」であり、種別を問わない。
+  // CLAUDE.md を放置すると、正本がプレースホルダ化された後に
+  // 「GET はレンダリング結果 → 端末は localChanged と判定 → PUT → 400 で拒否」を
+  // 毎セッション繰り返し、`.bak.conflict` だけが積み上がって収束しない
+  // （AGENTS.md が 2026-08-01 から起こしていた症状の再演）。
+  //
+  // ⚠️ **この判定を前へ動かさないこと**。pull 分岐の **後ろ** に置いているので、
+  // 「Hub だけが変化した純粋な pull」は従来どおり取り込む。前へ動かすと
+  // 「受け取り専用」ではなく「受け取らない」になり、移行後の初回 pull も止まる。
+  //
+  // ⚠️ **push 経路と conflict 経路で別々に判定しない**。ここから下は両方とも
+  // 「ローカルが（前回同期時点から）変化した」経路で、PUT する / しないの分岐は
+  // 1 か所に置く。経路ごとに掛けると、片方だけ塞がった状態が生まれる。
+  //
+  // ⚠️ **ローカルを黙って上書きもしない**。conflict 側で「端末が勝てないなら Hub で
+  // 上書き」に倒すと、退避 `.bak` は残っても人は気づかず、端末の編集が事実上消える。
+  // 乖離は **warn ＋ 専用の reason** で見える形にして残し、取り込みは人に委ねる。
+  //
+  // 【唯一の例外＝初回登録（`isInitialRegistration`）がなぜ受け取り専用と両立するか】
+  // 初回登録が成立するのは **Hub の正本が空**（`hubBody === ""` ＋ meta 無し ＋
+  // 呼び出し元が「このセッションより前からファイルがあった」と報告）のときだけ。
+  // 正本が空である以上、端末の本文は「正本のレンダリング結果」ではありえない
+  // （レンダリング元が無い）ので、送り返しても正本を平坦化しない。これは
+  // **上書きではなく、未登録の正本を 1 度だけ種付けする**経路であり、
+  // 「レンダリング結果を正本へ書き戻さない」という受け取り専用の禁止事項に触れない。
+  // 実データ 16 件がこの経路を通っており、消すと未登録 workspace の正本が
+  // 永久に空のままになる（＝端末には毎回プレースホルダが配られ、Hub 側に
+  // 案件固有の内容が載らない）。種付けが済めば meta と非空の正本が揃うので、
+  // 以降の乖離はすべてこのガードに落ちる。
+  //
+  // ⚠️ ログに本文を載せないこと（接続情報が混ざりうる）。出してよいのは長さ・行数・
+  // ハッシュのような、中身を復元できない指標だけ。
+  if (!isInitialRegistration) {
+    logger?.warn?.(
+      {
+        dirName,
+        // ⚠️ 固定値を書かない。種別を広げた後に「常に AGENTS.md」と出ると、
+        // どちらのファイルで乖離したのかがログから分からなくなる。
+        config_filename: configPaths(configFilename).filename,
+        hub_changed: hubChanged,
+        local_bytes: localBody == null ? 0 : Buffer.byteLength(localBody, "utf-8"),
+        local_lines: localBody == null ? 0 : localBody.split("\n").length,
+        local_hash: localCurrentHash,
+        hub_hash: hubHash,
+      },
+      "syncClaudeMdWithHub: local config md drifted from the rendered hub source of truth; it is receive-only so nothing was pushed and nothing was overwritten (edit the source of truth on Hub, then let the next sync pull)",
+    )
+    return { action: "skipped", reason: "config-md-receive-only-drift" }
+  }
+
   if (!hubChanged && localChanged) {
     // ⚠️ hash の観測と snapshot の自己整合性は **入口の門で保証済み**。ここに
     // 個別チェックを再掲しないこと（検査の本体が 2 つになると、片方だけ適用範囲が
     // 戻る回帰が起きる。実際に「PUT 経路にだけ掛ける」設計から blocker が出た）。
     // push: Hub に PUT。成功時にメタ更新。
+    //
+    // ⚠️ **ここへ来るのは初回登録だけ**（2026-08-09 以降）。上の受け取り専用ガードが
+    // それ以外の `localChanged` を全部返しているため。`isInitialRegistration` は
+    // `hubBody === ""` かつ meta 無しが前提なので、この分岐の `hubChanged` は
+    // 常に false になる（＝ `!hubChanged` の条件はいま実質的に常に真）。
+    // 条件を消して単純化しないこと: 受け取り専用ガードの例外を将来増やしたときに、
+    // 「Hub が動いているのに端末本文で PUT する」経路が黙って復活する。
     const put = await putHubClaudeMd({
       hubUrl: url,
       accessToken: token,
@@ -1320,14 +1559,15 @@ export async function syncClaudeMdWithHub({
         )
         return { action: "skipped", reason: "hub-put-stale" }
       }
-      if (put.error?.error === "config_md_kind_mismatch") {
-        // CLI 種別の取り違え（AGENTS.md の内容を CLAUDE.md 正本へ送った等）。
-        // 同じ本文を再送しても永久に通らないので、リトライ前提の通信失敗と混ぜない。
+      const permanent = permanentPutRejectionReason(put.error)
+      if (permanent) {
+        // CLI 種別の取り違え / 平坦化本文の送信。**同じ本文を再送しても永久に通らない**
+        // ので、リトライ前提の通信失敗と混ぜない（meta も進めない）。
         logger?.warn?.(
           { dirName, ...put.error },
-          "syncClaudeMdWithHub: push rejected (config md kind mismatch); resending the same body will keep failing",
+          "syncClaudeMdWithHub: push rejected by a permanent guard; resending the same body will keep failing",
         )
-        return { action: "skipped", reason: "hub-put-kind-mismatch" }
+        return { action: "skipped", reason: permanent }
       }
       return { action: "skipped", reason: "hub-put-failed" }
     }
@@ -1363,6 +1603,19 @@ export async function syncClaudeMdWithHub({
 
   // hubChanged && localChanged → 衝突。端末側を勝者にして Hub に PUT。
   //
+  // ⚠️⚠️ **この分岐はいま到達しない**（2026-08-09 以降）。受け取り専用ガードが
+  // `localChanged` の経路を初回登録以外すべて返し、初回登録は `hubBody === ""` が
+  // 前提なので `hubChanged` が false になるため。テストも
+  // 「conflict 相当の入力 → `skipped(config-md-receive-only-drift)`・PUT 0 回・
+  // `.bak.conflict` 0 件」を固定する側へ載せ替えてある。
+  //
+  // ⚠️ **消していないのは意図的**。「受け取り専用」は方針であって backend の制約では
+  // なく（正本にプレースホルダを保ったまま端末から更新する API ができれば覆りうる）、
+  // ガードと同じ commit で衝突解決の機構ごと落とすと、方針を見直すときに
+  // 退避 (.bak.conflict) と楽観ロックの組み合わせを一から書き直すことになる。
+  // ⚠️ 逆に言えば **いまは検査されていないコード**なので、ここを直したくなったら
+  // 先に到達可能性（受け取り専用ガードの例外）を決めること。
+  //
   // ⚠️ hash の観測と snapshot の自己整合性は **入口の門で保証済み**（push 経路と同じ
   // 理由でここに再掲しない）。壊れた snapshot は入口で返すので、**PUT しない回に
   // `.bak.conflict` だけが増える**こともない。
@@ -1389,13 +1642,14 @@ export async function syncClaudeMdWithHub({
       )
       return { action: "skipped", reason: "hub-put-stale-in-conflict" }
     }
-    if (put.error?.error === "config_md_kind_mismatch") {
+    const permanent = permanentPutRejectionReason(put.error)
+    if (permanent) {
       // push 経路と同じ理由（再送しても通らない拒否）。通信失敗と区別する。
       logger?.warn?.(
         { dirName, ...put.error },
-        "syncClaudeMdWithHub: conflict push rejected (config md kind mismatch); resending the same body will keep failing",
+        "syncClaudeMdWithHub: conflict push rejected by a permanent guard; resending the same body will keep failing",
       )
-      return { action: "skipped", reason: "hub-put-kind-mismatch-in-conflict" }
+      return { action: "skipped", reason: `${permanent}-in-conflict` }
     }
     return { action: "skipped", reason: "hub-put-failed-in-conflict" }
   }
@@ -1441,6 +1695,11 @@ export {
   readBaseBody,
   nowIso,
   configPaths,
+  // `cli_kind` の導出と URL 組み立ては初期化経路（claude-md.mjs）でも使う。
+  // ⚠️ 複製しないこと（片方だけ `cli_kind` を載せ忘れると、初回配信だけ別 CLI 向けの
+  // 本文を掴むという非対称が生まれる）。
+  cliKindForConfig,
+  claudeMdByDirUrl,
 }
 
 // 内部テスト用エクスポート
@@ -1458,4 +1717,7 @@ export const _internals = {
   // 壊れるため、両者を突き合わせるテストから参照できるように公開する。
   makeBakName,
   bakNamePattern,
+  cliKindForConfig,
+  claudeMdByDirUrl,
+  looksLikeClaudeMdBody,
 }

package/src/claude-md.mjs

@@ -40,6 +40,8 @@ import {
   nowIso,
   isHubSnapshotTrustworthy,
   usableHubUpdatedAt,
+  cliKindForConfig,
+  claudeMdByDirUrl,
 } from "./claude-md-sync.mjs"
 import {
   HUB_REQUEST_TIMEOUT_MS,
@@ -92,12 +94,18 @@ async function fetchHubClaudeMdProject({
   fetchImpl,
   deadline,
   logger,
+  configFilename = "CLAUDE.md",
 }) {
   const f = fetchImpl || globalThis.fetch
   if (!f) return null
-  const url =
-    `${hubUrl.replace(/\/+$/, "")}/api/admin/project/claude-md-by-dir/` +
-    `?dir_name=${encodeURIComponent(dirName)}`
+  // ⚠️ 同期側（`fetchHubClaudeMd`）と **同じ導出・同じ URL 組み立て**を使う。初回配信だけ
+  // `cli_kind` を落とすと、Codex の初回セッションが CLAUDE.md 向けの本文を AGENTS.md
+  // として書き込み、その本文が base / meta（同期の基準）にまで入る。
+  const url = claudeMdByDirUrl({
+    hubUrl,
+    dirName,
+    cliKind: cliKindForConfig(configFilename),
+  })
   try {
     const fetched = await deadline.guard(
       // 同期的に throw する fetch 実装でも guard に載るよう then で包む。
@@ -325,6 +333,7 @@ export async function ensureClaudeMd({
         fetchImpl,
         deadline,
         logger,
+        configFilename,
       })
     } finally {
       deadline.clear()

package/src/tmux.mjs

@@ -828,14 +828,16 @@ export async function createSession(name, cwd, opts = {}) {
     }
   }
   // HUB_PROJECTS_BASE 配下の workspace の場合は CLAUDE.md を必要なら生成し、
-  // Hub の正本（Project.claude_md）と双方向同期する。
+  // Hub の正本（Project.claude_md）から受け取る。
   // - ensureClaudeMd: 既存 CLAUDE.md は触らない。無ければ director frontmatter
   //   または placeholder を生成する。
-  // - syncClaudeMdWithHub: Hub 正本と双方向 last-write-wins 同期。Hub 側更新は
-  //   ローカルへ pull（.bak 退避してから上書き）、端末側更新は Hub へ push、
-  //   両方変化は端末側を勝者にして Hub へ push（Hub の取り込み内容は
-  //   .bak.conflict に退避）。Hub が一度も保存されていないプロジェクトでは
-  //   何もしない（テナント標準 CLAUDE.md の運用を尊重する）。
+  // - syncClaudeMdWithHub: **受け取り専用**。Hub 側更新はローカルへ pull（.bak 退避
+  //   してから上書き）、端末側で編集されていても Hub へは送り返さない（正本は
+  //   プレースホルダ入りで、端末にあるのはそのレンダリング結果のため）。乖離は
+  //   warn ＋ `config-md-receive-only-drift` で見える形に残す。唯一の例外が
+  //   **初回登録**（Hub の正本が空 + そのファイルが元からあった場合に 1 度だけ push）。
+  //   Hub が一度も保存されていないプロジェクトでは何もしない（テナント標準
+  //   CLAUDE.md の運用を尊重する）。
   // どちらも失敗しても session 起動自体は止めない (warn のみ)。
   // ⚠️ 2 つの呼び出しで **1 本の budget を共有**する。1 往復ごとの期限だけでは
   //   往復の本数ぶん足し算されてセッション起動が長時間止まりうるため、Hub 処理に