@cocorograph/hub-agent 0.8.38 → 0.8.39

package/package.json

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

package/src/claude-md-sync.mjs

@@ -23,6 +23,16 @@
  * 詳細な条件と、なぜ `localFilePreexisted` を永続化しないのかは
  * `syncClaudeMdWithHub` 内の `isInitialRegistration` のコメントを参照。
  *
+ * **AGENTS.md は受け取り専用**（2026-08-09）。Hub の正本は `Project.claude_md` 1 本で、
+ * GET は `cli_kind` に応じて CLI 別へレンダリングして返す。AGENTS.md はその
+ * **レンダリング結果**であって正本ではないので、
+ * - GET には必ず `cli_kind=codex` を載せる（載せないと CLAUDE.md 向け本文を掴む）
+ * - **PUT は一切行わない**（push / conflict のどちらも）。乖離は warn ＋
+ *   `agents-md-receive-only-drift` で見える形にし、ローカルも黙って上書きしない
+ * `cli_kind` を載せていなかった頃に作られた壊れた同期状態（AGENTS.md の base に
+ * CLAUDE.md 本文が入っている）は、sync の冒頭で meta / base を捨てて初回 sync へ戻す
+ * （`migrateBrokenAgentsBase`）。
+ *
  * 失敗時のポリシー: ローカル CLAUDE.md は触らない（warn ログ + skip）。
  * session 起動を止めない（ensureClaudeMd と同じく best-effort）。
  *
@@ -58,6 +68,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 +337,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 +615,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 +710,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 +1079,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,
   })
@@ -1291,6 +1444,39 @@ export async function syncClaudeMdWithHub({
     return { action: "pull" }
   }
 
+  // ---- AGENTS.md は受け取り専用（ここから下は必ず localChanged === true）--------
+  //
+  // Hub は `Project.claude_md`（CLAUDE.md 正本）を CLI 別にレンダリングして返す。
+  // AGENTS.md はその **レンダリング結果** であって正本ではないので、端末側で編集された
+  // からといって Hub へ送り返してはいけない（正本にプレースホルダが残っていても、
+  // 送るのは展開済みの平坦な本文になる ＝ backend の平坦化ガードに 400 で弾かれる）。
+  //
+  // ⚠️ **push 経路と conflict 経路で別々に判定しない**。ここから下は両方とも
+  // 「ローカルが（前回同期時点から）変化した」経路で、PUT する / しないの分岐は
+  // 1 か所に置く。経路ごとに掛けると、片方だけ塞がった状態が生まれる。
+  //
+  // ⚠️ **ローカルを黙って上書きもしない**。conflict 側で「端末が勝てないなら Hub で
+  // 上書き」に倒すと、退避 `.bak` は残っても人は気づかず、端末の編集が事実上消える。
+  // 乖離は **warn ＋ 専用の reason** で見える形にして残し、取り込みは人に委ねる。
+  //
+  // ⚠️ ログに本文を載せないこと（接続情報が混ざりうる）。出してよいのは長さ・行数・
+  // ハッシュのような、中身を復元できない指標だけ。
+  if (configPaths(configFilename).filename === "AGENTS.md") {
+    logger?.warn?.(
+      {
+        dirName,
+        config_filename: "AGENTS.md",
+        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 AGENTS.md drifted from the rendered hub source of truth; AGENTS.md is receive-only so nothing was pushed and nothing was overwritten (edit CLAUDE.md on Hub, then let the next sync pull)",
+    )
+    return { action: "skipped", reason: "agents-md-receive-only-drift" }
+  }
+
   if (!hubChanged && localChanged) {
     // ⚠️ hash の観測と snapshot の自己整合性は **入口の門で保証済み**。ここに
     // 個別チェックを再掲しないこと（検査の本体が 2 つになると、片方だけ適用範囲が
@@ -1320,14 +1506,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" }
     }
@@ -1389,13 +1576,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 +1629,11 @@ export {
   readBaseBody,
   nowIso,
   configPaths,
+  // `cli_kind` の導出と URL 組み立ては初期化経路（claude-md.mjs）でも使う。
+  // ⚠️ 複製しないこと（片方だけ `cli_kind` を載せ忘れると、初回配信だけ別 CLI 向けの
+  // 本文を掴むという非対称が生まれる）。
+  cliKindForConfig,
+  claudeMdByDirUrl,
 }
 
 // 内部テスト用エクスポート
@@ -1458,4 +1651,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()