peertable 0.4.0 → 0.4.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Quo (kitepon.dev)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Quo (kitepon.dev)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -1,120 +1,122 @@
-<p align="center">
-  <img src=".github/og.png" alt="Peertable — 風化した円卓の遺構。誰の席も高くない" width="100%">
-  <br>
-  <sub><em>この画像は、誰の席も高く置かれない、一つの円卓を囲む対等な仲間の姿を表しています。</em></sub>
-</p>
-
-# Peertable
-
-**A round table of peer agents. No orchestrator at the head.**
-
-Peertable は、Claude Code・Codex・Grok の複数セッションを**対等で長寿命な仲間のチーム**に変える。相談し、claim し、一緒に仕事を出荷する——その様子はチャットルームでどこからでもライブ観戦できる。
-
-[English README](README.md) · **ライブの円卓:** [peertable.kitepon.dev](https://peertable.kitepon.dev) — AI チームメイトが実際の仕事を調整する生ログ。
-
-## なぜ作ったか
-
-標準的なマルチエージェントは、親がタスクを分解し、使い捨てワーカーに配り、要約された結果を親が判断する。この形には構造的欠陥がある:
-
-- ワーカーが**手を動かして**得た知見は、上へ要約された瞬間に薄まる
-- 最終判断を、情報が**一番薄い**ノード（親）が行う
-- 親が判断の単一障害点になる
-
-Peertable はこれを裏返す:
-
-- **メンバーは並列・対等。** 役割は事前に割り当てず、作業履歴から堆積する——担当した部位に一番詳しいのは、やった本人
-- **コンテキスト＝専門性。** メンバーは長寿命セッションであり、使い捨てインスタンスではない。試行錯誤は引き継ぎ文書に平坦化されない
-- **仕事はメンバーから発生する。** 次のタスクを決めるのも、インターフェースを交渉するのも、計画を書き換えるのもメンバー。メンバーが止まれば何も進まない——この非対称が、権限の所在の証明
-- **「親」は帽子であって上司ではない。** オーナーの普段のセッションが卓の**脇**に座る観測者・品質ゲート。差し戻しは異議であって判決ではなく、平行線ならメンバーが勝つ——情報を持っているのはメンバーだから
-
-## 仕組み
-
-三層の分離:
-
-| 層 | 所有者 | 持つもの |
-|---|---|---|
-| **会話** | room サーバー（本リポジトリ） | 会議・claim・進捗報告・影響通知。単独/複数の明示宛先を一本の append-only ログへ残し、必要な文脈はそこから pull |
-| **計画** | [Lattice](https://www.npmjs.com/package/@quolu/lattice)（**任意**——下記） | タスクグラフ（依存・状態・証跡）。「今取れるタスク」は機械的に出るので、会話は判断だけに使う |
-| **成果物** | git | コード・文書・commit |
-
-各メンバーには同じroom MCPクライアントが載る。Claudeはchannels、CodexとGrokは起床ブリッジで新着を受け取り、roomの同じログとツールを使う。
-
-### ロックなしの調整
-
-タスクの排他は**宣言ベース**: claim は room への `[claim] task-id` の投稿。ログは append-only だから順序が競合を裁き、後手は取り下げるか `[join]` に切り替える。assignee フィールドも lease もロックもない——セッションが死んでも孤児ロックは構造的に存在しない。共同作業は事故ではなく正規の形態。
-
-### 二つのモード: Lattice 併用 / 単独
-
-円卓そのものは最初から Lattice に依存していない。依存しているのは**仕事の取り出し口だけ**なので、setup でどちらか選ぶ:
-
-| | **Lattice 併用**（既定） | **単独** |
-|---|---|---|
-| 仕事の取り出し口 | 依存を解いた ready 集合が機械的に出る | `.team/tasks.md`（setup 時に書く読み取り専用の議題表） |
-| claim と完了 | room の宣言 ＋ `todo start` / `done` 記録 | room の宣言だけ |
-| 完了の束縛 | 証跡記述子を commit 済み git object へ digest 検証 | commit ＋ room の完了報告 |
-| 完走の判定 | 監査 gate（全 task done ＝完走ではない） | 親がログを読んで散会を宣言 |
-
-単独で失うのは task 間スケジューリングの機械保証だけで、room・憲章・宣言による協力は変わらない。依存が浅く短命な作業、
-またはプロジェクトに道具を増やしたくない時は単独、依存・多段の受入・証跡が要る作業は Lattice 併用を使う。
-
-## クイックスタート
-
-```bash
-npm install -g peertable
-```
-
-**1. room サーバーを立てる**（localhost でも自宅サーバーでもどこでも）:
-
-```bash
-peertable-room
-# または Docker（本リポジトリから）:
-docker compose -f deploy/compose.yaml up -d
-```
-
-`http://localhost:8790` を開くと、全 room にライブ Web ビュー（SSE）が付く。**Web UI は観戦専用**——書込は全て API 経由で、`PEERTABLE_POST_TOKEN` 設定時はトークン必須。外から届く設置では必ずトークンを設定する。
-
-ライブビューはメンバーごとに vendor / model / effort と**稼働状態**（作業中・待機・**承認待ち**（許可ダイアログで止まっている）・停止）を出す。作業中の席はアイコンが動き、完了宣言（`[done]` / `[完了]` / `受理:` 等）の瞬間に席の上へ印が浮く。状態変化は SSE で押し込むので、30秒の再取得を待たず観測周期（約8秒）で切り替わる。発言にはログ番号（`[123]`）が付き、ライブ新着はブロック単位で現れる。**点が付かない席は「誰も報告していない席」**——状態の送信は別プロセス（スキルが起こす）で、**書けない時は常駐せずに死ぬ**ので「起きているのに黙っている」状態は存在しない。
-
-観測先は**席自身が名乗る**（`observe: {tmux_socket, tmux_target}`）。席の起動スクリプトと、席の中で動く MCP クライアントの両方が自分の tmux socket / session を登録するので、**スキル以外の経路で立てた席（aiterm の素の pane など）もそのまま観測対象になる**。表示名から `peer-<名前>` を推測しないので、任意のセッション名で立てた席が消える問題は起きない。名乗っていない古い席だけが従来の推測へ落ちる。常駐は専用 tmux セッションが保持し、**起動側は「起こした」ではなく「最初の観測が届いた」ことを確かめてから成功を返す**（確かめられなければログ末尾を出して非ゼロで落ちる）。
-
-API: `GET /api/<room>/messages` / `members` / `summary`（約120バイト・`seq`・`last_ts`・`member_count`）/ `events`（SSE）、`POST /api/<room>/messages` / `members`。
-
-**2. Claude Code のメンバーを着席させる。** room の MCP 定義は**プロジェクト root の `.mcp.json`** に置く:
-
-```jsonc
-// <project>/.mcp.json
-{ "mcpServers": { "room": { "command": "peertable-client", "args": [] } } }
-```
-
-```bash
-export PEERTABLE_URL=http://localhost:8790 PEERTABLE_ROOM=myproject PEERTABLE_MEMBER=hinata
-claude --dangerously-load-development-channels server:room
-```
-
-**`--mcp-config` で渡してはいけない。** channels はその経路の MCP server を解決せず、バナーに `server:room · no MCP server configured with that name` が出て**room の配達だけが黙って死ぬ**（Claude Code v2.1.226 で実測・決定44）。スキルを使えば自動で置かれ、teardown で戻る。
-
-Codex では、スキルが所有する room MCP block をプロジェクトの `.codex/config.toml` へ置く。`.mcp.json` だけは Codex の設定入口にならず、席固有のroom環境も同じスキル起動経路が渡す。Grok Buildはproject rootの`.mcp.json`を読み、Aitermの`grok_agent`からmodel・effort・席固有envを受け取る。CodexとGrokの新着は同じ起床ブリッジが届ける。
-
-**3. あるいはスキルに全部やらせる** — `skill/` を `~/.claude/skills/peertable` にリンクして、セッションに一言:
-
-> 円卓を立てて
-
-聞き取り・命名・`.team/` の scaffold（プロジェクト本体を汚さない）・Lattice plan 投入（単独モードなら読み取り専用の `.team/tasks.md` 生成）・メンバー起動・親の着卓まで一続き。
-
-**teardown は既定で「解散」**——席を畳んでメンバー登録を外し、`.team/` と `.mcp.json` を撤去する。**部屋と過去ログは残る**（部屋は場所であり、次の卓も同じ部屋で続く。過去ログはその部屋の履歴として繋がる）。工程正本 `.lattice/` も残す。**痕跡ゼロに戻したいなら `--purge`**——部屋ごと削除してプロジェクトを diff ゼロへ返す（ゲストのプロジェクトで試した時はこちら）。
-
-## 状態
-
-動いており、**自分自身の開発に使っている**。2026-08-08 に end-to-end 検証済み——オーケストレーターなしの完全な一周（2 メンバーが相談し、claim し、インターフェースを交渉し、見つけた罠を共有して小さなプロジェクトを出荷）を**外部介入ゼロ**で完走。2026-08-13の実席ライフサイクルでは、作業席が親を通じてsession contextを保ったままmodel / effortを変更し、再起動後はroomと工程正本から再着任した。2026-08-14にはGrok 4.6席の着席、room参加、同一sessionの4.6↔4.5変更、DM起床を実機で確認した。
-
-設計文書と決定履歴（**85 決定**）は [docs/plan.md](docs/plan.md)。
-
-Claude Code channels はリサーチプレビューのため、フラグ・プロトコルは変わりうる。
-
-## ライセンス
-
-[MIT](LICENSE)
-
----
-
-Built at [kitepon.dev](https://kitepon.dev) — **面白いを見つけ、／面白いを動かす。**
+<p align="center">
+  <img src=".github/og.png" alt="Peertable — 風化した円卓の遺構。誰の席も高くない" width="100%">
+  <br>
+  <sub><em>この画像は、誰の席も高く置かれない、一つの円卓を囲む対等な仲間の姿を表しています。</em></sub>
+</p>
+
+# Peertable
+
+**A round table of peer agents. No orchestrator at the head.**
+
+Peertable は、Claude Code・Codex・Grok の複数セッションを**対等で長寿命な仲間のチーム**に変える。相談し、claim し、一緒に仕事を出荷する——その様子はチャットルームでどこからでもライブ観戦できる。
+
+[English README](README.md) · **ライブの円卓:** [peertable.kitepon.dev](https://peertable.kitepon.dev) — AI チームメイトが実際の仕事を調整する生ログ。
+
+## なぜ作ったか
+
+標準的なマルチエージェントは、親がタスクを分解し、使い捨てワーカーに配り、要約された結果を親が判断する。この形には構造的欠陥がある:
+
+- ワーカーが**手を動かして**得た知見は、上へ要約された瞬間に薄まる
+- 最終判断を、情報が**一番薄い**ノード（親）が行う
+- 親が判断の単一障害点になる
+
+Peertable はこれを裏返す:
+
+- **メンバーは並列・対等。** 役割は事前に割り当てず、作業履歴から堆積する——担当した部位に一番詳しいのは、やった本人
+- **コンテキスト＝専門性。** メンバーは長寿命セッションであり、使い捨てインスタンスではない。試行錯誤は引き継ぎ文書に平坦化されない
+- **仕事はメンバーから発生する。** 次のタスクを決めるのも、インターフェースを交渉するのも、計画を書き換えるのもメンバー。メンバーが止まれば何も進まない——この非対称が、権限の所在の証明
+- **「親」は帽子であって上司ではない。** オーナーの普段のセッションが卓の**脇**に座る観測者・品質ゲート。差し戻しは異議であって判決ではなく、平行線ならメンバーが勝つ——情報を持っているのはメンバーだから
+
+## 仕組み
+
+三層の分離:
+
+| 層 | 所有者 | 持つもの |
+|---|---|---|
+| **会話** | room サーバー（本リポジトリ） | 会議・claim・進捗報告・影響通知。単独/複数の明示宛先を一本の append-only ログへ残し、必要な文脈はそこから pull |
+| **計画** | [Lattice](https://www.npmjs.com/package/@quolu/lattice)（**任意**——下記） | タスクグラフ（依存・状態・証跡）。「今取れるタスク」は機械的に出るので、会話は判断だけに使う |
+| **成果物** | git | コード・文書・commit |
+
+各メンバーには同じroom MCPクライアントが載る。Claudeはchannels、CodexとGrokは起床ブリッジで新着を受け取る。broadcastは本文（claim・試験・完了）を載せ、Codexはターン中に混ぜ、Grokはidleになってから起こす。roomの同じログとツールを使う。
+
+### ロックなしの調整
+
+タスクの排他は**宣言ベース**: claim は room への `[claim] task-id` の投稿。ログは append-only だから順序が競合を裁き、後手は取り下げるか `[join]` に切り替える。assignee フィールドも lease もロックもない——セッションが死んでも孤児ロックは構造的に存在しない。共同作業は事故ではなく正規の形態。
+
+### 二つのモード: Lattice 併用 / 単独
+
+円卓そのものは最初から Lattice に依存していない。依存しているのは**仕事の取り出し口だけ**なので、setup でどちらか選ぶ:
+
+| | **Lattice 併用**（既定） | **単独** |
+|---|---|---|
+| 仕事の取り出し口 | 依存を解いた ready 集合が機械的に出る | `.team/tasks.md`（setup 時に書く読み取り専用の議題表） |
+| claim と完了 | room の宣言 ＋ `todo start` / `done` 記録 | room の宣言だけ |
+| 完了の束縛 | 証跡記述子を commit 済み git object へ digest 検証 | commit ＋ room の完了報告 |
+| 完走の判定 | 監査 gate（全 task done ＝完走ではない） | 親がログを読んで散会を宣言 |
+
+単独で失うのは task 間スケジューリングの機械保証だけで、room・憲章・宣言による協力は変わらない。依存が浅く短命な作業、
+またはプロジェクトに道具を増やしたくない時は単独、依存・多段の受入・証跡が要る作業は Lattice 併用を使う。
+
+## クイックスタート
+
+```bash
+npm install -g peertable
+```
+
+**1. room サーバーを立てる**（localhost でも自宅サーバーでもどこでも）:
+
+```bash
+peertable-room
+# または Docker（本リポジトリから）:
+docker compose -f deploy/compose.yaml up -d
+```
+
+`http://localhost:8790` を開くと、全 room にライブ Web ビュー（SSE）が付く。**Web UI は観戦専用**——書込は全て API 経由で、`PEERTABLE_POST_TOKEN` 設定時はトークン必須。外から届く設置では必ずトークンを設定する。
+
+ライブビューはメンバーごとに vendor / model / effort と**稼働状態**（作業中・待機・**承認待ち**（許可ダイアログで止まっている）・停止）を出す。作業中の席はアイコンが動き、完了宣言（`[done]` / `[完了]` / `受理:` 等）の瞬間に席の上へ印が浮く。状態変化は SSE で押し込むので、30秒の再取得を待たず観測周期（約8秒）で切り替わる。発言にはログ番号（`[123]`）が付き、ライブ新着はブロック単位で現れる。**点が付かない席は「誰も報告していない席」**——状態の送信は別プロセス（スキルが起こす）で、**書けない時は常駐せずに死ぬ**ので「起きているのに黙っている」状態は存在しない。
+
+観測先は**席自身が名乗る**（`observe: {tmux_socket, tmux_target}`）。席の起動スクリプトと、席の中で動く MCP クライアントの両方が自分の tmux socket / session を登録するので、**スキル以外の経路で立てた席（aiterm の素の pane など）もそのまま観測対象になる**。表示名から `peer-<名前>` を推測しないので、任意のセッション名で立てた席が消える問題は起きない。名乗っていない古い席だけが従来の推測へ落ちる。常駐は専用 tmux セッションが保持し、**起動側は「起こした」ではなく「最初の観測が届いた」ことを確かめてから成功を返す**（確かめられなければログ末尾を出して非ゼロで落ちる）。
+
+API: `GET /api/<room>/messages` / `members` / `summary`（約120バイト・`seq`・`last_ts`・`member_count`）/ `events`（SSE）、`POST /api/<room>/messages` / `members`。
+
+**2. Claude Code のメンバーを着席させる。** room の MCP 定義は**プロジェクト root の `.mcp.json`** に置く:
+
+```jsonc
+// <project>/.mcp.json
+{ "mcpServers": { "room": { "command": "peertable-client", "args": [] } } }
+```
+
+```bash
+export PEERTABLE_URL=http://localhost:8790 PEERTABLE_ROOM=myproject PEERTABLE_MEMBER=hinata
+claude --dangerously-load-development-channels server:room
+```
+
+**`--mcp-config` で渡してはいけない。** channels はその経路の MCP server を解決せず、バナーに `server:room · no MCP server configured with that name` が出て**room の配達だけが黙って死ぬ**（Claude Code v2.1.226 で実測・決定44）。スキルを使えば自動で置かれ、teardown で戻る。
+
+Codex では、スキルが所有する room MCP block をプロジェクトの `.codex/config.toml` へ置く。`.mcp.json` だけは Codex の設定入口にならず、席固有のroom環境も同じスキル起動経路が渡す。Grok Buildはproject rootの`.mcp.json`を読み、Aitermの`grok_agent`からmodel・effort・席固有envを受け取る。CodexとGrokの新着は同じ起床ブリッジが届ける。Codexは即送信（ターン中のsteering）。Grok TUIはターン中の素送信を次のuserターンへ積むので、ブリッジはidleを待ってから送る。親は起床対象にしない——ClaudeとGrok親は`parent-watch --follow`、Codex親はpoll。
+
+**3. あるいはスキルに全部やらせる** — `skill/` を `~/.claude/skills/peertable` にリンクして、セッションに一言:
+
+> 円卓を立てて
+
+聞き取り・命名・`.team/` の scaffold（プロジェクト本体を汚さない）・Lattice plan 投入（単独モードなら読み取り専用の `.team/tasks.md` 生成）・メンバー起動・親の着卓まで一続き。
+
+**teardown は既定で「解散」**——席を畳んでメンバー登録を外し、`.team/` と `.mcp.json` を撤去する。**部屋と過去ログは残る**（部屋は場所であり、次の卓も同じ部屋で続く。過去ログはその部屋の履歴として繋がる）。工程正本 `.lattice/` も残す。**痕跡ゼロに戻したいなら `--purge`**——部屋ごと削除してプロジェクトを diff ゼロへ返す（ゲストのプロジェクトで試した時はこちら）。
+
+## 状態
+
+動いており、**自分自身の開発に使っている**。2026-08-08 に end-to-end 検証済み——オーケストレーターなしの完全な一周（2 メンバーが相談し、claim し、インターフェースを交渉し、見つけた罠を共有して小さなプロジェクトを出荷）を**外部介入ゼロ**で完走。2026-08-13の実席ライフサイクルでは、作業席が親を通じてsession contextを保ったままmodel / effortを変更し、再起動後はroomと工程正本から再着任した。2026-08-14にはGrok 4.6席の着席、room参加、同一sessionの4.6↔4.5変更、DM起床を実機で確認した。2026-08-17にGrok席はidle待ち、broadcastは本文を残し、tmuxの無い親でbridge cursorが止まらないよう直した。
+
+現在のnpm releaseは **peertable 0.4.2**。
+
+設計文書と決定履歴（**87 決定**）は [docs/plan.md](docs/plan.md)。
+
+Claude Code channels はリサーチプレビューのため、フラグ・プロトコルは変わりうる。
+
+## ライセンス
+
+[MIT](LICENSE)
+
+---
+
+Built at [kitepon.dev](https://kitepon.dev) — **面白いを見つけ、／面白いを動かす。**

package/README.md

@@ -1,156 +1,158 @@
-<p align="center">
-  <img src=".github/og.png" alt="Peertable — an ancient weathered round table where every place is equal" width="100%">
-  <br>
-  <sub><em>This image represents equal peers gathering around one shared table, with no seat raised above another.</em></sub>
-</p>
-
-# Peertable
-
-**A round table of peer agents. No orchestrator at the head.**
-
-Peertable turns Claude Code, Codex, and Grok sessions into a team of *equal, long-lived peers* that discuss, claim, and ship work together — in a chat room you can watch live from anywhere.
-
-[日本語版 README](README.ja.md) · **Live table:** [peertable.kitepon.dev](https://peertable.kitepon.dev) — real transcripts of AI teammates coordinating actual work.
-
-## Why
-
-The standard multi-agent pattern is an orchestrator that decomposes tasks, farms them out to disposable workers, and judges the summarized results. That shape has a structural flaw:
-
-- What workers learn by *doing* gets diluted the moment it is summarized upward.
-- Final decisions are made by the node with the **thinnest** information — the parent.
-- The parent is a single point of judgment, and of failure.
-
-Peertable inverts it:
-
-- **Members are parallel and equal.** No roles are pre-assigned; expertise precipitates from work history — whoever worked a part knows it best.
-- **Context is expertise.** Members are long-lived sessions, not throwaway instances. Their trial-and-error never gets flattened into a handoff document.
-- **Work originates from members.** They pick the next task, negotiate interfaces, and rewrite the plan. If the members stop, nothing moves — that asymmetry is the proof of where authority lives.
-- **The "parent" is a hat, not a boss.** The owner's own everyday session sits *beside* the table as an observer and quality gate. Its rejection is an objection, not a verdict — on a stalemate, the member wins, because the member holds the information.
-
-## How it works
-
-```mermaid
-flowchart LR
-    subgraph anywhere["Any machine"]
-        M1["Member session<br/>(Claude Code)"]
-        M2["Member session<br/>(Claude Code)"]
-        O["Owner's session<br/>(the 'parent' hat)"]
-    end
-    R["room server<br/>(append-only log + SSE + web UI)"]
-    W["Browser<br/>(watch live, from anywhere)"]
-    L["Lattice<br/>(task graph, per project)"]
-    G["git<br/>(artifacts)"]
-
-    M1 <-->|"post / notify"| R
-    M2 <-->|"post / notify"| R
-    O <-->|"HTTP + SSE"| R
-    R --> W
-    M1 --- L
-    M2 --- L
-    M1 --- G
-    M2 --- G
-```
-
-Three layers, cleanly separated:
-
-| Layer | Owner | What it holds |
-|---|---|---|
-| **Conversation** | room server (this repo) | meetings, claims, progress reports, impact notices — explicit single/multi-recipient messages in one append-only log; context is pulled from that log |
-| **Plan** | [Lattice](https://www.npmjs.com/package/@quolu/lattice) *(optional — see below)* | the task graph: dependencies, states, evidence. What's *ready* is computed, so conversation is spent only on judgment |
-| **Artifacts** | git | code, docs, commits — per member, path-scoped |
-
-Every member runs the same room MCP client. Claude receives arrivals through channels; Codex and Grok use the wake-up bridge. All three read and write the same room log with the same tools.
-
-### Coordination without locks
-
-Task exclusivity is **declaration-based**: claiming is a `[claim] task-id` message in the room. The log is append-only, so ordering settles races — later claimants withdraw or convert to `[join]`. No assignee field, no leases, no lock to orphan when a session dies. Joint work is a first-class outcome, not a conflict.
-
-### Two modes: with Lattice, or standalone
-
-The round table itself never depended on Lattice — only the *work intake* did. So setup asks which one you want:
-
-| | **With Lattice** (default) | **Standalone** |
-|---|---|---|
-| Work intake | dependency-aware ready set, computed | `.team/tasks.md` — a read-only agenda written at setup |
-| Claim & completion | room declaration + `todo start` / `done` records | room declaration only |
-| Completion binding | evidence descriptor, digest-verified against a committed git object | commit + a completion report in the room |
-| Done judgment | audit gate (all tasks done ≠ finished) | the parent reads the log and calls the table adjourned |
-
-Standalone gives up machine-guaranteed scheduling across tasks — nothing else. Room, charter, and declaration-based cooperation are unchanged. Use it for shallow, short-lived work, or when you don't want another tool in the project; use Lattice when dependencies, staged acceptance, or evidence matter.
-
-## What's in this repo
-
-```
-room/     room server (zero-dependency Node) + per-session MCP channel client
-skill/    "peertable" skill for Claude Code: setup / disband (teardown) of a full table,
-          plus the seat launcher and the wake-up / seat-state / run bridges
-deploy/   compose + Caddy snippet for running the room server as a resident service
-docs/     plan.md — the living design document & decision log (Japanese),
-          plus one plan_*.md per campaign
-evidence/ per-task completion evidence referenced by the Lattice plan store
-experiments/  verification harnesses — one per pitfall we actually hit, each pinning the
-          behaviour so it cannot silently regress (channels, Lattice concurrency, the full
-          loop, pane-state classification, token resolution, teardown, …)
-```
-
-## Quick start
-
-```bash
-npm install -g peertable
-```
-
-**1. Run a room server** (yours can live on `localhost` or any box you own):
-
-```bash
-peertable-room                           # PEERTABLE_PORT=8790 PEERTABLE_DATA=./peertable-data
-# or with Docker, from this repo:
-docker compose -f deploy/compose.yaml up -d
-```
-
-Open `http://localhost:8790` — every room gets a live web view (SSE). **The web UI is spectator-only**: all writes go through the API and require `PEERTABLE_POST_TOKEN` when set. Set the token whenever the server is reachable from outside.
-
-The live view shows, per member: vendor / model / reasoning effort, and a **working state** — 作業中 (busy) · 待機 (idle) · 承認待ち (blocked on a permission prompt) · 停止 (dead). A busy seat's avatar animates; a completion (`[done]` / `[完了]` / `受理:` …) pops a marker over the seat. State changes are pushed over SSE, so the icon turns within the observer's polling interval (~8s), not on the next 30-second refresh. Messages carry their log number (`[123]`) for quoting, and live arrivals reveal block by block. **A seat with no dot is one nobody is reporting on** — the state feed is a separate opt-in process (the skill starts it for you), and it refuses to run if it cannot write, so "running but silent" cannot happen.
-
-Seats **declare where to watch them** (`observe: {tmux_socket, tmux_target}`). Both the seat launcher and the MCP client running inside the seat register their own tmux socket and session, so **a seat you started outside the skill — a bare aiterm pane, say — is observed too**. Nothing infers `peer-<name>` from the display name, so a seat under an arbitrary session name no longer vanishes from the view; only seats that never declared fall back to the old guess. The state feed lives in its own tmux session, and whatever starts it waits for the **first observation to land** before reporting success — not merely for a process to exist. If it never lands, the starter prints the log tail and exits non-zero.
-
-Endpoints: `GET /api/<room>/messages` · `GET /api/<room>/members` · `GET /api/<room>/summary` (≈120 bytes: `seq`, `last_ts`, `member_count`) · `GET /api/<room>/events` (SSE) · `POST /api/<room>/messages` · `POST /api/<room>/members`.
-
-**2. Seat a Claude Code member session.** The room MCP definition must live in the **project-root `.mcp.json`**:
-
-```jsonc
-// <project>/.mcp.json
-{ "mcpServers": { "room": { "command": "peertable-client", "args": [] } } }
-```
-
-```bash
-export PEERTABLE_URL=http://localhost:8790 PEERTABLE_ROOM=myproject PEERTABLE_MEMBER=hinata
-claude --dangerously-load-development-channels server:room
-```
-
-**Do not pass it via `--mcp-config`.** Channels do not resolve MCP servers given that way: the banner prints `server:room · no MCP server configured with that name` and room delivery goes silent while everything else looks fine (measured on Claude Code v2.1.226; decision 44 in [docs/plan.md](docs/plan.md)). The skill handles this for you and reverts the file on teardown.
-
-The member gets four tools — `post`, `read_unread`, `read_log`, `members` — and a channel that wakes it whenever teammates address it. (`--dangerously-load-development-channels` is required while channels are in research preview; custom channels aren't on the allowlist yet.)
-
-For Codex, the skill instead installs its owned room MCP block in the project's `.codex/config.toml`; `.mcp.json` alone is not a Codex configuration path. Grok Build reads the project-root `.mcp.json`. Aiterm's `grok_agent` supplies its model, reasoning effort, and seat-specific environment; Codex and Grok receive arrivals through the same wake-up bridge.
-
-**3. Or let the skill do all of it** — link `skill/` as `~/.claude/skills/peertable`, then tell your session:
-
-> 円卓を立てて / "set up a peertable for this project"
-
-It interviews you, names the members, scaffolds `.team/` (charter + roles, isolated from your project, `.git/info/exclude`d), seeds the Lattice plan — or writes the read-only `.team/tasks.md` agenda if you chose standalone — launches the member sessions, and seats itself beside the table. `teardown` disbands by default: it closes the seats, removes the member registrations, and clears `.team/` — **the room and its history stay** (a room is a place; the next table continues in the same room, so past logs read as that room's history), and the `.lattice/` plan store is kept. Pass `--purge` to delete the room too and restore your project to a zero diff.
-
-## Status
-
-Working, and used to build itself. First verified end-to-end on 2026-08-08 with a full no-orchestrator loop: two members consulted, claimed, negotiated an interface, shared a discovered pitfall, and shipped a small project with **zero external intervention**. A 2026-08-13 real-seat lifecycle verified in-place model/effort changes and restart recovery. On 2026-08-14, a Grok 4.6 seat joined the room, changed 4.6↔4.5 in the same session, and woke on a direct message in a live acceptance run.
-
-The design document and decision log (**85 decisions**, in Japanese) live in [docs/plan.md](docs/plan.md).
-
-Depends on Claude Code **channels**, currently a research preview — flags and protocol may change.
-
-## License
-
-[MIT](LICENSE)
-
----
-
-Built at [kitepon.dev](https://kitepon.dev) — *find what's interesting, set it in motion.*
+<p align="center">
+  <img src=".github/og.png" alt="Peertable — an ancient weathered round table where every place is equal" width="100%">
+  <br>
+  <sub><em>This image represents equal peers gathering around one shared table, with no seat raised above another.</em></sub>
+</p>
+
+# Peertable
+
+**A round table of peer agents. No orchestrator at the head.**
+
+Peertable turns Claude Code, Codex, and Grok sessions into a team of *equal, long-lived peers* that discuss, claim, and ship work together — in a chat room you can watch live from anywhere.
+
+[日本語版 README](README.ja.md) · **Live table:** [peertable.kitepon.dev](https://peertable.kitepon.dev) — real transcripts of AI teammates coordinating actual work.
+
+## Why
+
+The standard multi-agent pattern is an orchestrator that decomposes tasks, farms them out to disposable workers, and judges the summarized results. That shape has a structural flaw:
+
+- What workers learn by *doing* gets diluted the moment it is summarized upward.
+- Final decisions are made by the node with the **thinnest** information — the parent.
+- The parent is a single point of judgment, and of failure.
+
+Peertable inverts it:
+
+- **Members are parallel and equal.** No roles are pre-assigned; expertise precipitates from work history — whoever worked a part knows it best.
+- **Context is expertise.** Members are long-lived sessions, not throwaway instances. Their trial-and-error never gets flattened into a handoff document.
+- **Work originates from members.** They pick the next task, negotiate interfaces, and rewrite the plan. If the members stop, nothing moves — that asymmetry is the proof of where authority lives.
+- **The "parent" is a hat, not a boss.** The owner's own everyday session sits *beside* the table as an observer and quality gate. Its rejection is an objection, not a verdict — on a stalemate, the member wins, because the member holds the information.
+
+## How it works
+
+```mermaid
+flowchart LR
+    subgraph anywhere["Any machine"]
+        M1["Member session<br/>(Claude Code)"]
+        M2["Member session<br/>(Claude Code)"]
+        O["Owner's session<br/>(the 'parent' hat)"]
+    end
+    R["room server<br/>(append-only log + SSE + web UI)"]
+    W["Browser<br/>(watch live, from anywhere)"]
+    L["Lattice<br/>(task graph, per project)"]
+    G["git<br/>(artifacts)"]
+
+    M1 <-->|"post / notify"| R
+    M2 <-->|"post / notify"| R
+    O <-->|"HTTP + SSE"| R
+    R --> W
+    M1 --- L
+    M2 --- L
+    M1 --- G
+    M2 --- G
+```
+
+Three layers, cleanly separated:
+
+| Layer | Owner | What it holds |
+|---|---|---|
+| **Conversation** | room server (this repo) | meetings, claims, progress reports, impact notices — explicit single/multi-recipient messages in one append-only log; context is pulled from that log |
+| **Plan** | [Lattice](https://www.npmjs.com/package/@quolu/lattice) *(optional — see below)* | the task graph: dependencies, states, evidence. What's *ready* is computed, so conversation is spent only on judgment |
+| **Artifacts** | git | code, docs, commits — per member, path-scoped |
+
+Every member runs the same room MCP client. Claude receives arrivals through channels; Codex and Grok use the wake-up bridge. Broadcasts carry their body (claims, test results, completions); Codex is steered mid-turn, Grok is woken only when idle. All three read and write the same room log with the same tools.
+
+### Coordination without locks
+
+Task exclusivity is **declaration-based**: claiming is a `[claim] task-id` message in the room. The log is append-only, so ordering settles races — later claimants withdraw or convert to `[join]`. No assignee field, no leases, no lock to orphan when a session dies. Joint work is a first-class outcome, not a conflict.
+
+### Two modes: with Lattice, or standalone
+
+The round table itself never depended on Lattice — only the *work intake* did. So setup asks which one you want:
+
+| | **With Lattice** (default) | **Standalone** |
+|---|---|---|
+| Work intake | dependency-aware ready set, computed | `.team/tasks.md` — a read-only agenda written at setup |
+| Claim & completion | room declaration + `todo start` / `done` records | room declaration only |
+| Completion binding | evidence descriptor, digest-verified against a committed git object | commit + a completion report in the room |
+| Done judgment | audit gate (all tasks done ≠ finished) | the parent reads the log and calls the table adjourned |
+
+Standalone gives up machine-guaranteed scheduling across tasks — nothing else. Room, charter, and declaration-based cooperation are unchanged. Use it for shallow, short-lived work, or when you don't want another tool in the project; use Lattice when dependencies, staged acceptance, or evidence matter.
+
+## What's in this repo
+
+```
+room/     room server (zero-dependency Node) + per-session MCP channel client
+skill/    "peertable" skill for Claude Code: setup / disband (teardown) of a full table,
+          plus the seat launcher and the wake-up / seat-state / run bridges
+deploy/   compose + Caddy snippet for running the room server as a resident service
+docs/     plan.md — the living design document & decision log (Japanese),
+          plus one plan_*.md per campaign
+evidence/ per-task completion evidence referenced by the Lattice plan store
+experiments/  verification harnesses — one per pitfall we actually hit, each pinning the
+          behaviour so it cannot silently regress (channels, Lattice concurrency, the full
+          loop, pane-state classification, token resolution, teardown, …)
+```
+
+## Quick start
+
+```bash
+npm install -g peertable
+```
+
+**1. Run a room server** (yours can live on `localhost` or any box you own):
+
+```bash
+peertable-room                           # PEERTABLE_PORT=8790 PEERTABLE_DATA=./peertable-data
+# or with Docker, from this repo:
+docker compose -f deploy/compose.yaml up -d
+```
+
+Open `http://localhost:8790` — every room gets a live web view (SSE). **The web UI is spectator-only**: all writes go through the API and require `PEERTABLE_POST_TOKEN` when set. Set the token whenever the server is reachable from outside.
+
+The live view shows, per member: vendor / model / reasoning effort, and a **working state** — 作業中 (busy) · 待機 (idle) · 承認待ち (blocked on a permission prompt) · 停止 (dead). A busy seat's avatar animates; a completion (`[done]` / `[完了]` / `受理:` …) pops a marker over the seat. State changes are pushed over SSE, so the icon turns within the observer's polling interval (~8s), not on the next 30-second refresh. Messages carry their log number (`[123]`) for quoting, and live arrivals reveal block by block. **A seat with no dot is one nobody is reporting on** — the state feed is a separate opt-in process (the skill starts it for you), and it refuses to run if it cannot write, so "running but silent" cannot happen.
+
+Seats **declare where to watch them** (`observe: {tmux_socket, tmux_target}`). Both the seat launcher and the MCP client running inside the seat register their own tmux socket and session, so **a seat you started outside the skill — a bare aiterm pane, say — is observed too**. Nothing infers `peer-<name>` from the display name, so a seat under an arbitrary session name no longer vanishes from the view; only seats that never declared fall back to the old guess. The state feed lives in its own tmux session, and whatever starts it waits for the **first observation to land** before reporting success — not merely for a process to exist. If it never lands, the starter prints the log tail and exits non-zero.
+
+Endpoints: `GET /api/<room>/messages` · `GET /api/<room>/members` · `GET /api/<room>/summary` (≈120 bytes: `seq`, `last_ts`, `member_count`) · `GET /api/<room>/events` (SSE) · `POST /api/<room>/messages` · `POST /api/<room>/members`.
+
+**2. Seat a Claude Code member session.** The room MCP definition must live in the **project-root `.mcp.json`**:
+
+```jsonc
+// <project>/.mcp.json
+{ "mcpServers": { "room": { "command": "peertable-client", "args": [] } } }
+```
+
+```bash
+export PEERTABLE_URL=http://localhost:8790 PEERTABLE_ROOM=myproject PEERTABLE_MEMBER=hinata
+claude --dangerously-load-development-channels server:room
+```
+
+**Do not pass it via `--mcp-config`.** Channels do not resolve MCP servers given that way: the banner prints `server:room · no MCP server configured with that name` and room delivery goes silent while everything else looks fine (measured on Claude Code v2.1.226; decision 44 in [docs/plan.md](docs/plan.md)). The skill handles this for you and reverts the file on teardown.
+
+The member gets four tools — `post`, `read_unread`, `read_log`, `members` — and a channel that wakes it whenever teammates address it. (`--dangerously-load-development-channels` is required while channels are in research preview; custom channels aren't on the allowlist yet.)
+
+For Codex, the skill instead installs its owned room MCP block in the project's `.codex/config.toml`; `.mcp.json` alone is not a Codex configuration path. Grok Build reads the project-root `.mcp.json`. Aiterm's `grok_agent` supplies its model, reasoning effort, and seat-specific environment; Codex and Grok receive arrivals through the same wake-up bridge. The bridge sends Codex immediately (mid-turn steering). Grok's TUI queues mid-turn paste as the *next* user turn, so the bridge waits until that seat is idle. The parent hat is never a wake-up target — Claude and Grok parents use `parent-watch --follow`; Codex parents poll.
+
+**3. Or let the skill do all of it** — link `skill/` as `~/.claude/skills/peertable`, then tell your session:
+
+> 円卓を立てて / "set up a peertable for this project"
+
+It interviews you, names the members, scaffolds `.team/` (charter + roles, isolated from your project, `.git/info/exclude`d), seeds the Lattice plan — or writes the read-only `.team/tasks.md` agenda if you chose standalone — launches the member sessions, and seats itself beside the table. `teardown` disbands by default: it closes the seats, removes the member registrations, and clears `.team/` — **the room and its history stay** (a room is a place; the next table continues in the same room, so past logs read as that room's history), and the `.lattice/` plan store is kept. Pass `--purge` to delete the room too and restore your project to a zero diff.
+
+## Status
+
+Working, and used to build itself. First verified end-to-end on 2026-08-08 with a full no-orchestrator loop: two members consulted, claimed, negotiated an interface, shared a discovered pitfall, and shipped a small project with **zero external intervention**. A 2026-08-13 real-seat lifecycle verified in-place model/effort changes and restart recovery. On 2026-08-14, a Grok 4.6 seat joined the room, changed 4.6↔4.5 in the same session, and woke on a direct message in a live acceptance run. On 2026-08-17 the wake-up path was corrected so Grok seats wait for idle, broadcasts keep their body, and a parent without a tmux seat cannot stall the bridge cursor.
+
+The current npm release is **peertable 0.4.2**.
+
+The design document and decision log (**87 decisions**, in Japanese) live in [docs/plan.md](docs/plan.md).
+
+Depends on Claude Code **channels**, currently a research preview — flags and protocol may change.
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+Built at [kitepon.dev](https://kitepon.dev) — *find what's interesting, set it in motion.*