# 複数 PC の Claude Code を 1 枚のスプレッドシート経由で結ぶ「PC 間メール」の設計 — 「配達済み」と「読まれた」を分けないと 13 時間黙って止まる ## 症状 別 PC の Claude Code に作業依頼を送った。送信側は「配達済み」と表示されたのに返事が来ず、「未着」と判断して人が止まった。実際は受信側に 4 秒で届いており、受信側の Claude がそれを読んだのは 13 時間後だった。 ## 真因（10 件の構造欠陥のうち主因 4 つ） 1. サーバー（Google Sheet ＋ Apps Script の WebApp）が「既読」を持たない。`delivered` は「受信 PC の 2 分ポーリングが取った」だけ。 2. 宛先解決が `label.indexOf(to)` の部分一致。`kim` が複数 PC に当たり、先にポーリングした PC が消費する。 3. 受信側は対話セッションでプロンプトが打たれるまで誰も見ない（hook が UserPromptSubmit のみ）。 4. hook が古い順・1500 字で打ち切るため、未読が 100 通を超えると新着が永久に出ない。 ## 設計（そのまま実装できる粒度） ### 状態機械はサーバー 1 か所に置く ``` new → delivered → seen → done | failed | expired ``` - `delivered`: 受信 PC のポーリングが取得（deliveredAt, deliveredBy） - `seen`: 受信 PC の Claude のコンテキストに注入された／CLI で本文を読んだ／ヘッドレス実行を開始した（seenAt, seenBy） - `done`: 返信（resultAt）または返信不要の ack（ackAt） - `failed`: 受信側で処理不能（failReason）、`expired`: 期限切れ（サーバーの時間トリガーが付与） - 遷移は**前進のみ・冪等**（done の後に seen を受けても done のまま ok を返す）。送信側は `--sent-status ` で「どこまで進んだか」を見る。`--wait-for seen|done` で「読まれた」時点で戻れる。 ### 宛先は完全一致 - PC 名簿（JSON: 作業用番号 ⇔ ラベル ⇔ hostname）を正本にし、CLI は送信前に正規ラベルへ解決。解決できなければ送らず exit 4 で候補を表示。 - サーバー側も完全一致を優先。旧 CLI の互換で部分一致を残すなら「既知ラベルに完全一致する宛先は部分一致で絶対に配達しない」「既知ラベル集合が取れなければ fail-closed」。 ### 受信（2 分ポーリング） - 処理済み判定は inbox の `status` 1 か所（`.processed` のような別マーカーを作らない。対話で返信済みのものをポーリングが再実行して二重返信する）。 - 1 通ごと try/catch。**検証エラーだけ**隔離（quarantine ＋ `fail`）、I/O 例外は次回再試行。 - inbox JSON の read-modify-write はファイル単位ロック（`wx` で作成、mtime 2 分で stale 回収）。hook とポーリングが同時に書くため。 - 到着時に即時アクションを分類: `[判断依頼]`/`[作業依頼]`/urgent は Discord に 1 行通知（1 id 1 回、受信完了後に一括・5 秒/通・合計 20 秒で打ち切り）。 - サーバーへの `seen`/`ack` 送信失敗は `pendingServer` に積み、次回ポーリングで一括再送（未知 action は 1 時間バックオフ・5 回で諦める。旧サーバーと混在しても壊れない）。 ### 提示（hook） - SessionStart と UserPromptSubmit の両方。**hook はサーバーと通信しない**（5 秒で kill される）。ポーリングが 3 分より古ければ detached で起動するだけ。lock を持たない。 - 表示順: 未回答の判断依頼 3 → 作業依頼/urgent 3 → 自分宛の回答 3（注入後に自動 ack）→ その他 2。**全カテゴリ新しい順**。1 通 240 字・全体 1800 字。末尾に「他 N 件（期限切れ M 件は除外）: <一覧コマンド>」。 - 注入した id は `presentedAt`/`presentedSession` を記録し `seen` をサーバーへ fire-and-forget。同じセッションでは件数行だけにする。 ### ループ・重複の遮断 - 全メールに `auto`（自動生成か）と `hop`。auto→auto の返信はサーバーが拒否、hop≥3 も拒否。返信への返信は CLI が exit 3。 - 返信は固定 id（原本 id ＋送信者の hash）で重複防止。ただし**本文が異なる 2 通目は新 id**（受領 ack が先に固定 id を取って本回答が消える事故を防ぐ）。 - id は `mail--<8hex 乱数>`。サーバーが duplicate を返したら id を再生成して 1 回だけ再送。 ### 監視はサーバー側に移す - Apps Script の 10 分時間トリガー: (a) 期限切れ→expired（done/failed は上書きしない）、(b) delivered で seen 無しが 2h（urgent）/6h 超→「未読 SLA 超過」、(c) new で delivered 無しが 30 分超→「未配達（受信タスク停止）」。アラートは専用タブに 1 id 1 行 upsert、webhook があれば直接投稿、無ければタブ記録のみ（PC 側 watchdog がフォールバック）。 - 受信タスクの自己修復は「LastRunTime があるか」ではなく「LastTaskResult≠0（実行中 0x41301/未実行 0x41303 は正常）または最終ポーリングが 10 分より古い」で再登録＋即 1 回ポーリング。 ### 実測で踏んだ罠 - Sheets は boolean/number を型変換して返すため、書込後の read-back を厳密比較すると「行は作られたのに mismatch」で CLI が失敗を返し、呼び出し側が再送する。比較前に両辺を正規化（boolean→'true'/'false'、数値→String、空→''、オブジェクト→JSON）。 - コマンドキュー（Drive フォルダに `cmd_*.json` を置く方式）へ API で投入するときは mimeType を `application/json` に明示。省略すると Google ドキュメントに変換され、Apps Script が `%PDF` を読んでエラーになる。 - テストで detached spawn を期待するときは `detached: true` を手書きせず、OS 別オプションを返す正本関数から導出する（Windows CI で落ちる）。 ## 完了の定義（実測） 自分宛に note を送る → 2 分以内に delivered → 新セッションの hook が先頭側に提示 → `--sent-status` が seen → `--ack` で done。部分一致の宛先は exit 4。 ---