@cocorograph/hub-agent 0.8.39 → 0.8.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.8.39",
+  "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,12 +30,19 @@
  * 詳細な条件と、なぜ `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` で見える形にし、ローカルも黙って上書きしない
+ * **ローカルの設定ファイルは受け取り専用**（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`）。
@@ -1236,6 +1250,11 @@ export async function syncClaudeMdWithHub({
 
   // --- 初回登録: 「Hub に無くローカルにある」ものを一度だけ Hub へ取り込む -------
   //
+  // ⚠️ 2026-08-09 以降、**これが PUT を発行する唯一の経路**（受け取り専用ガードの
+  // 唯一の例外）。両立する理由は下の受け取り専用ガードのコメントに書いてある
+  // （要約: 正本が空なら端末の本文は「正本のレンダリング結果」ではありえないので、
+  // 送っても正本を平坦化しない ＝ 上書きではなく種付け）。
+  //
   // 条件は **すべて** 満たすときだけ:
   //   - meta が無い（この端末はまだ一度も同期していない）
   //   - Hub 本文が空（**等値比較のみ**。`updated_at` の有無は問わない）
@@ -1444,12 +1463,25 @@ export async function syncClaudeMdWithHub({
     return { action: "pull" }
   }
 
-  // ---- AGENTS.md は受け取り専用（ここから下は必ず localChanged === true）--------
+  // ---- ローカルの設定ファイルは受け取り専用（ここから下は必ず 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 から起こしていた症状の再演）。
   //
-  // Hub は `Project.claude_md`（CLAUDE.md 正本）を CLI 別にレンダリングして返す。
-  // AGENTS.md はその **レンダリング結果** であって正本ではないので、端末側で編集された
-  // からといって Hub へ送り返してはいけない（正本にプレースホルダが残っていても、
-  // 送るのは展開済みの平坦な本文になる ＝ backend の平坦化ガードに 400 で弾かれる）。
+  // ⚠️ **この判定を前へ動かさないこと**。pull 分岐の **後ろ** に置いているので、
+  // 「Hub だけが変化した純粋な pull」は従来どおり取り込む。前へ動かすと
+  // 「受け取り専用」ではなく「受け取らない」になり、移行後の初回 pull も止まる。
   //
   // ⚠️ **push 経路と conflict 経路で別々に判定しない**。ここから下は両方とも
   // 「ローカルが（前回同期時点から）変化した」経路で、PUT する / しないの分岐は
@@ -1459,22 +1491,36 @@ export async function syncClaudeMdWithHub({
   // 上書き」に倒すと、退避 `.bak` は残っても人は気づかず、端末の編集が事実上消える。
   // 乖離は **warn ＋ 専用の reason** で見える形にして残し、取り込みは人に委ねる。
   //
+  // 【唯一の例外＝初回登録（`isInitialRegistration`）がなぜ受け取り専用と両立するか】
+  // 初回登録が成立するのは **Hub の正本が空**（`hubBody === ""` ＋ meta 無し ＋
+  // 呼び出し元が「このセッションより前からファイルがあった」と報告）のときだけ。
+  // 正本が空である以上、端末の本文は「正本のレンダリング結果」ではありえない
+  // （レンダリング元が無い）ので、送り返しても正本を平坦化しない。これは
+  // **上書きではなく、未登録の正本を 1 度だけ種付けする**経路であり、
+  // 「レンダリング結果を正本へ書き戻さない」という受け取り専用の禁止事項に触れない。
+  // 実データ 16 件がこの経路を通っており、消すと未登録 workspace の正本が
+  // 永久に空のままになる（＝端末には毎回プレースホルダが配られ、Hub 側に
+  // 案件固有の内容が載らない）。種付けが済めば meta と非空の正本が揃うので、
+  // 以降の乖離はすべてこのガードに落ちる。
+  //
   // ⚠️ ログに本文を載せないこと（接続情報が混ざりうる）。出してよいのは長さ・行数・
   // ハッシュのような、中身を復元できない指標だけ。
-  if (configPaths(configFilename).filename === "AGENTS.md") {
+  if (!isInitialRegistration) {
     logger?.warn?.(
       {
         dirName,
-        config_filename: "AGENTS.md",
+        // ⚠️ 固定値を書かない。種別を広げた後に「常に 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 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)",
+      "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: "agents-md-receive-only-drift" }
+    return { action: "skipped", reason: "config-md-receive-only-drift" }
   }
 
   if (!hubChanged && localChanged) {
@@ -1482,6 +1528,13 @@ export async function syncClaudeMdWithHub({
     // 個別チェックを再掲しないこと（検査の本体が 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,
@@ -1550,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` だけが増える**こともない。

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 処理に