kenaz 0.0.0-stage → 0.3.2

package/core/dev/specs/agent-connect/history/KENAZ_RESPONSE_agent-hub_2026-09-09_session-channel.md

@@ -0,0 +1,57 @@
+# Kenaz 側回覆：Agent Connect C 期（S1–S5）裁定與已落地的部分
+
+日期：2026-09-09
+來源：KenazAI / TASK_1947（S1 + S5）、TASK_1948（S2）
+對應報告：`FEATURE_REQUEST_kenaz-agent-hub_2026-09-09_v0.4-session-channel.md`（FlowPix，2026-09-09）
+接續：`KENAZ_RESPONSE_agent-hub_2026-09-09_prompt-mojibake-fixed.md`
+
+## 裁定總表
+
+| 需求 | 裁定 | 落地 |
+|---|---|---|
+| S1 `X-Kenaz-Session` header + status 列 sessions | **做** | TASK_1947，main |
+| S5 預設允許網站 MCP 工具 | **做（claude）／查證後文件化（codex）** | TASK_1947，main |
+| S2 `kenaz_wait_for_message` 人格慣例 | **做** | TASK_1948，main |
+| S4 `kenaz_session_ended` | **下一輪** | 未開卡；這是 Kenaz 主動打回網站的第一個例外，會單獨設計（沿用 S1 的 launch_id、一次性、有逾時） |
+| S3 session 輸出串流 | **獨立評估** | 未開卡；牽涉事件模型與權限，且與 v0.4「Kenaz → Web 無回程」立場相抵，等 S1/S2/S5 在 FlowPix 跑穩後再談 |
+
+你們提議的順序（S1 + S2 + S5 先、S4 其次、S3 獨立）我們完全採納。
+
+## S1：session 身分
+
+- 預配網站 MCP 的 `headers` 現在是 `{"Authorization": "Bearer <token>", "X-Kenaz-Session": "<launch_id>"}`。
+- **`launch_id` 不是 pty session id**。順序上 Kenaz 先寫 MCP 設定、再組啟動腳本、最後才向 pty-server 要到終端分頁的 session id，所以 header 裡的是 Kenaz 在 launch 一開始就鑄好的 uuid v4；`GET /api/agent-hub/status` 會把兩者都列出來給你對照。
+- `GET http://127.0.0.1:18080/api/agent-hub/status` 每個 origin 新增：
+  ```json
+  "sessions": [{"session_id": "<launch_id>", "pty_session_id": "<pty uuid>", "agent": "claude", "model": "...", "cwd": "...", "started_at": "<ISO-8601>", "alive": true}]
+  ```
+  `alive` 是查 pty-server 的即時結果，等於你 S4 想要的「session 死了沒」的輪詢版；S4 做完才會有推送。
+- codex 分支：codex-cli 0.153.4 支援 `mcp_servers.<name>.env_http_headers`（header 名 → 環境變數名），值走環境變數、不進命令列，與 bearer 同一套。我們在真實啟動路徑（BOM `.ps1` 經 `powershell -File`）上實測過引號寫法，只有一種能存活，已寫進程式碼與測試。
+- PROTOCOL §2 新增第 1b 點與 `mcp.config_with_session_header` fixture；SDK_GUIDE §3.1b。網站可選讀取，Kenaz 一律送。
+
+## S5：預設允許網站 MCP 工具
+
+- claude：啟動時加 `--allowedTools 'mcp__<name>__*'`（`<name>` 即你看到的 `127` 那個 server 名）。沒有加任何 `--dangerously-*`。
+- codex：`env_http_headers` 已驗；「MCP 工具呼叫是否觸發審批提示」在 worktree 裡沒有安全的互動式 session 可以驗，先當開放問題記錄，**不會**用 `-a never` 之類會連 shell 指令審批一起關掉的旗標。請你們在 codex 路徑實測一次回報。
+- 下一步（我們自己開卡）：改成依 MCP 工具 `annotations.readOnlyHint / destructiveHint` 分級，非破壞性預設允許、破壞性照舊提問。這比 `*` 全允安全，也不需要新協定；網站只要在 `tools/list` 標 annotations 就能受益。
+
+## S2：`kenaz_wait_for_message`
+
+- PROTOCOL §2 新增第 5 點（可選）。回傳 `{"message": string|null, "message_id": string|null, "end": boolean}`，`end` 可省略視為 `false`。三個 fixture：`mcp.kenaz_wait_for_message_call` / `_result_message` / `_result_null`。
+- Ansuz 人格（Kenaz 啟動時注入）現在會：呼叫 `kenaz_hello` → 處理完 `prompt`（沒有 prompt 就直接）→ 反覆呼叫 `kenaz_wait_for_message`；有 `message` 就當使用者指令執行完再呼叫；`null` 就再呼叫；`end: true`、連續失敗 3 次、或使用者要求停止時停下並告知。工具不在 `tools/list` 裡時完全不提。呼叫前不會向使用者提問，也不會自己 sleep，等待由工具本身的阻塞完成。
+- **成本條款（強制）**：每一次呼叫都是 Kenaz 使用者訂閱額度裡的一個 agent turn。網站**必須**長輪詢（建議阻塞 20–25 秒才回 `null`），不得短輪詢。
+- minimal-site（`dev/specs/agent-connect/examples/minimal-site`）已實作記憶體信箱：`POST /message` 投遞、`kenaz_wait_for_message` 最長阻塞 20 秒；smoke test 與 conformance 都有覆蓋。你們的 bridge 可以直接對照。
+- 審批卡文案「此網站會持續傳送指令」這次沒做：Kenaz 在審批當下還沒連過網站 MCP，不知道 `tools/list` 有什麼；要做得先多一次審批前的探測，留到 S4 一起看。
+
+## 對 §5 SDK 套件的對應
+
+`@kenaz/connect-mcp` 的三個慣例工具骨架裡，`kenaz_wait_for_message` 現在有正式約定可以照抄（minimal-site 就是參考實作）；`kenaz_session_ended` / `kenaz_session_event` 等 S4 / S3 定案後再進。
+
+## 版本
+
+以上都在 main，並已隨 **0.2.231（2026-09-09 21:57Z 發布）** 出貨：S1 header、S5 allowedTools、S2 `kenaz_wait_for_message` 人格慣例都在這一版。
+
+## 附：這輪順帶修的
+
+- `prompt=` 中文亂碼（另一份回覆）。
+- Synapse wedge 復原路徑（`synapse_index` 新增 `mode` / `rebuild_graph`），跟 Agent Connect 無關，但你們的 Ansuz 在 vidora 上會用到。

package/core/dev/specs/agent-connect/history/PROTOCOL_v0.3_snapshot.md

@@ -0,0 +1,379 @@
+# Kenaz Agent Connect — Protocol v1 (PROTOCOL.md) — v0.3 SNAPSHOT (ARCHIVED)
+
+> **ARCHIVED 2026-09-08 by TASK_1939.** This is a frozen snapshot of
+> `dev/specs/agent-connect/PROTOCOL.md` as it stood at v0.3 (the WebSocket
+> relay + pairing-handshake protocol), taken immediately before TASK_1939
+> rewrote that file to v0.4 (relay removed — deep link + website MCP only,
+> spec `dev/KENAZ_AGENT_CONNECT_v1_SPEC.md` v0.4 §2.3, decision Q10). Kept
+> here for the same archaeology/traceability reason `history/README.md`
+> keeps the Relay v1 (FlowPix) documents: v0.4's deep-link `mcp=` param and
+> the `kenaz_hello` MCP convention both replace functionality this v0.3
+> protocol (and the Relay v1 handshake it absorbed — `site.hello` through
+> `pair.denied`) used to provide over the wire. **Do not edit this file —
+> it is a historical record, not a living spec.** The current spec is
+> `../PROTOCOL.md`.
+
+---
+
+# Kenaz Agent Connect — Protocol v1 (PROTOCOL.md)
+
+- Status: **finalized draft**, B 期（TASK_1935/TASK_1938）。取代 `dev/KENAZ_AGENT_CONNECT_v1_SPEC.md` 第 2.3 節的內嵌訊息表；規格文件改為引用本檔。
+- 標準所有權：本檔是唯一權威來源。FlowPix 的 `bridge/CONTRACT.md`「Relay v1」章節是**歷史來源**（見 `history/README.md`），已被本檔取代，不再更新。
+- `protocol_version`：目前為 `"1"`。任何新增/移除訊息型別都必須先改本檔，再改 `dashboard/src-tauri/src/features/agent_hub/protocol.rs`。
+- 這份文件的每個 ```json 範例都必須是**可直接 `JSON.parse` 的合法 JSON**——不可有 `|`、不可有註解、不可有多形態塞進同一個區塊。多形態（例如同一 type 的不同錯誤碼）各自獨立一個 `#### Fixture:` 區塊。`dashboard/scripts/agent-connect-conformance/fixtures.mjs` 直接抽取這些區塊當作 conformance suite 的唯一 fixture 來源；本檔任何一個區塊解析失敗，測試就會 fail。
+
+## 1. Transport
+
+- 一個 relay process 對應一個 WS/WSS endpoint（開發：`ws://127.0.0.1:<port>/ws`；正式：`wss://...`，TLS 終止在 relay）。
+- 每一幀（frame）是一則 UTF-8 JSON，一個 JSON object，至少要有 `"type"`（string，必填）。
+- 大多數訊息帶 `"request_id"`（string），用來把請求與其回應配對；少數 unsolicited push（`agent.connected`、`agent.disconnected`）的 `request_id` 為 `null`。
+- `request_id` 由**發起請求的一方**產生（uuid 或等效隨機字串），回應方原樣帶回；relay 轉發時不得改寫。
+- 未知 `type`：relay／Kenaz 對無法辨識的訊息型別一律回 `error {request_id, error:{code:"protocol_unsupported", ...}}` 給發送方，**不斷線**（見第 6 節）。這是 B 期硬切策略——沒有舊型別 adapter。
+
+## 2. Roles
+
+| Role | 說明 | 這次的實作 |
+|---|---|---|
+| **site** | 網站雲端 backend，代表一個瀏覽器 session 連上 relay。連線的第一則訊息若是 `site.hello`，這條連線就固定為 site 角色。 | conformance suite 的 `fake-site.mjs` |
+| **agent** | Kenaz 本機桌面應用。連線的第一則訊息若是 `pair.begin`，這條連線就固定為 agent 角色（agent 沒有獨立的 hello 步驟，`pair.begin` 身兼兩者）。 | 真實 Kenaz（`relay_client.rs`）；conformance suite 內用一段內嵌的 fake-agent 邏輯（`run.mjs`）頂替，因為本卡不碰 Rust |
+| **relay** | Kenaz 託管的中介服務。職責限於：site 握手、token 簽發、agent 配對、依 origin 轉發 launch／approval／status／exited 訊息。relay 永遠看不到 AI 憑證與 MCP bearer。 | `dashboard/scripts/agent-connect-conformance/stub-relay.mjs`（本卡自帶，僅供本卡自測；`dashboard/scripts/agent-hub-fake-relay.mjs` 是 TASK_1936 的假 relay，功能更完整，本卡不碰） |
+
+`agent ↔ site` 之間，除了下面列的訊息，沒有其他資料經過 relay——生圖、寫回、結果回傳全部走網站自己的 MCP 工具，relay／Kenaz 都看不到那段流量。
+
+## 3. 深連結格式
+
+```
+kenaz://connect?site=<url-encoded origin>&token=<token>&relay=<url-encoded relay ws url>
+```
+
+| 參數 | 必填 | 說明 |
+|---|---|---|
+| `site` | 是 | 網站 origin（`https://...`；開發模式下允許 `http://localhost` / `http://127.0.0.1` / `http://[::1]`，見 `KENAZ_AGENT_HUB_DEV=1`）。Kenaz 用 `Url::origin().ascii_serialization()` 正規化，去掉 path/query/fragment，作為 `sites.json` 的 key。 |
+| `token` | 是 | `token.mint` 發回的一次性 pairing token，60 秒 TTL，用過即失效（見第 4.3 節）。 |
+| `relay` | 是 | relay 的 WS/WSS 端點（`wss://...`；開發模式允許 `ws://127.0.0.1` / `ws://localhost` / `ws://[::1]`）。 |
+
+v0.3 收斂後，深連結**只負責喚醒與配對**——不再帶 `agent=`／`mode=`／`prompt=`／`mcp=`。這四個參數是 Relay v1（A 期）遺留的「深連結順帶啟動」語意（`agent.launch` 曾經是 relay 廣播、不是 site 請求），已被 Q7/Q9 的決定取代：`agent.launch` 一律是配對成功後 site 透過 relay 送出的**請求**（見第 4.6 節），prompt 與 MCP 端點都在那則訊息裡，不進深連結。目前 `dashboard/src-tauri/src/features/agent_hub/deep_link.rs`（TASK_1929/1932）仍解析這四個舊參數，作為 A 期 Relay v1 基線的相容層；TASK_1936 收斂 Rust 實作時會依本節簡化。
+
+## 4. 訊息（依配對→啟動→結束的時間順序）
+
+### 4.1 Site 握手：`site.hello` / `site.ready`
+
+方向：`site -> relay`（請求），`relay -> site`（回應）。
+何時發：site 連上 relay 後的第一則訊息，固定此連線的角色為 site。
+
+| 欄位 | 訊息 | 型別 | 說明 |
+|---|---|---|---|
+| `type` | 兩者 | `"site.hello"` \| `"site.ready"` | |
+| `request_id` | 兩者 | string | site 產生，relay 原樣帶回 |
+| `origin` | `site.hello` | string | 這個 site session 代表的網站 origin |
+| `site_session_id` | `site.ready` | string | relay 配發，之後 `token.mint` 沿用同一條連線，不需要再帶 |
+
+#### Fixture: site.hello
+```json
+{"type":"site.hello","request_id":"req-site-hello-1","origin":"https://flowpix.app"}
+```
+
+#### Fixture: site.ready
+```json
+{"type":"site.ready","request_id":"req-site-hello-1","site_session_id":"sess-abc123"}
+```
+
+### 4.2 Pairing token：`token.mint` / `token.minted`
+
+方向：`site -> relay`（請求），`relay -> site`（回應）。
+何時發：site 已完成 `site.hello`，使用者按下「連接 Kenaz」按鈕時。一次性、60 秒 TTL、綁定 `(site_session_id, origin, agent)`；`pair.begin` 一旦處理過這個 token（不論成功失敗）就立刻失效，不能重試。
+
+| 欄位 | 訊息 | 型別 | 說明 |
+|---|---|---|---|
+| `type` | 兩者 | `"token.mint"` \| `"token.minted"` | |
+| `request_id` | 兩者 | string | |
+| `agent` | `token.mint` | `"claude"` \| `"codex"` \| `null` | 選填，網站可預先指定希望用哪個 CLI；`null`／省略表示由 Kenaz 依使用者的 dispatch 設定決定 |
+| `token` | `token.minted` | string | 32 hex chars |
+| `ttl_s` | `token.minted` | number | 目前固定 60 |
+
+#### Fixture: token.mint
+```json
+{"type":"token.mint","request_id":"req-token-mint-1","agent":null}
+```
+
+#### Fixture: token.minted
+```json
+{"type":"token.minted","request_id":"req-token-mint-1","token":"a1b2c3d4e5f60718293a4b5c6d7e8f90","ttl_s":60}
+```
+
+site 收到 `token.minted` 後，用第 3 節的格式組出深連結並交給使用者的瀏覽器開啟。
+
+### 4.3 Agent 配對：`pair.begin` / `pair.ok` / `pair.denied`
+
+方向：`agent -> relay`（請求），`relay -> agent`（回應）。
+何時發：使用者開啟深連結，Kenaz 對外撥線到 `relay=` 指定的 relay，送出 `pair.begin`。`pair.begin` 身兼「這條連線是 agent 角色」的宣告，agent 沒有獨立的 hello 步驟。
+
+| 欄位 | 訊息 | 型別 | 說明 |
+|---|---|---|---|
+| `type` | 三者 | `"pair.begin"` \| `"pair.ok"` \| `"pair.denied"` | |
+| `request_id` | 三者 | string | |
+| `protocol_version` | `pair.begin` | string | 目前 `"1"`。relay／Kenaz 只認識自己支援的版本，不支援就 `pair.denied {code:"protocol_unsupported"}` | 
+| `token` | `pair.begin` | string | 來自深連結 `token=` |
+| `site_origin` | `pair.begin` | string | 來自深連結 `site=`；必須與 token 綁定的 origin 相符 |
+| `session_credential` | `pair.ok` | string | 配對成功後的憑證，之後作為網站 MCP 的 Bearer token（見第 7 節） |
+| `site_origin` | `pair.ok` | string | 回顯 |
+| `error.code` | `pair.denied` | enum | `token_invalid` \| `token_expired` \| `token_already_used` \| `origin_mismatch` \| `relay_unavailable` \| `protocol_unsupported`（見第 6 節） |
+| `error.message` | `pair.denied` | string | 人類可讀說明 |
+
+#### Fixture: pair.begin
+```json
+{"type":"pair.begin","request_id":"req-pair-1","protocol_version":"1","token":"a1b2c3d4e5f60718293a4b5c6d7e8f90","site_origin":"https://flowpix.app"}
+```
+
+#### Fixture: pair.ok
+```json
+{"type":"pair.ok","request_id":"req-pair-1","session_credential":"cred-9f8e7d6c5b4a","site_origin":"https://flowpix.app"}
+```
+
+#### Fixture: pair.denied.token_invalid
+```json
+{"type":"pair.denied","request_id":"req-pair-1","error":{"code":"token_invalid","message":"unknown token"}}
+```
+
+#### Fixture: pair.denied.token_expired
+```json
+{"type":"pair.denied","request_id":"req-pair-1","error":{"code":"token_expired","message":"token expired 62000ms ago (ttl 60000ms)"}}
+```
+
+#### Fixture: pair.denied.token_already_used
+```json
+{"type":"pair.denied","request_id":"req-pair-1","error":{"code":"token_already_used","message":"token already used"}}
+```
+
+#### Fixture: pair.denied.origin_mismatch
+```json
+{"type":"pair.denied","request_id":"req-pair-1","error":{"code":"origin_mismatch","message":"token was issued for https://flowpix.app, request claimed https://evil.example"}}
+```
+
+#### Fixture: pair.denied.relay_unavailable
+```json
+{"type":"pair.denied","request_id":"req-pair-1","error":{"code":"relay_unavailable","message":"token's site session already disconnected"}}
+```
+
+#### Fixture: pair.denied.protocol_unsupported
+```json
+{"type":"pair.denied","request_id":"req-pair-1","error":{"code":"protocol_unsupported","message":"relay only supports protocol_version 1"}}
+```
+
+`pair.ok` 成功後，relay 額外對已配對的 site 連線推一則 `agent.connected`（見 4.4）。
+
+### 4.4 配對成功通知：`agent.connected`（relay 內部生成，unsolicited）
+
+方向：`relay -> site`，unsolicited（`request_id` 為 `null`）。
+何時發：某個 `pair.begin` 剛拿到 `pair.ok`，relay 把這個消息轉告該 token 綁定的 site 連線。
+
+| 欄位 | 型別 | 說明 |
+|---|---|---|
+| `type` | `"agent.connected"` | |
+| `request_id` | `null` | |
+| `agent_session_id` | string | relay 內部的配對識別碼，之後路由 `agent.launch`／`approval.*`／`agent.launched` 等訊息用這個或 origin |
+
+#### Fixture: agent.connected
+```json
+{"type":"agent.connected","request_id":null,"agent_session_id":"agent-sess-1"}
+```
+
+### 4.5 狀態推送：`agent.status`（Kenaz -> site，unsolicited）
+
+方向：`agent -> relay -> site`，unsolicited。
+何時發：配對成功後立即推一次；之後 Kenaz 的登入狀態或審批模式改變時再推。
+
+| 欄位 | 型別 | 說明 |
+|---|---|---|
+| `type` | `"agent.status"` | |
+| `request_id` | string（Kenaz 送 uuid，site 忽略即可） | |
+| `agents` | object | Kenaz 內部欄位（各 CLI 的安裝/版本資訊），site 可忽略未知子欄位 |
+| `dispatch` | object | Kenaz 內部欄位（目前的 dispatch 設定），site 可忽略 |
+| `codex_logged_in` | boolean | Codex CLI 是否已登入 |
+| `rate_limits` | `null` \| object | 目前一律 `null`（Kenaz 尚無可靠用量來源） |
+| `approval_mode` | enum | `"allow_all"` \| `"ask_once"` \| `"deny"`——依該 origin 目前的權限狀態映射：`always → allow_all`、`once → ask_once`、`blocked/unauthorized → deny` |
+
+#### Fixture: agent.status
+```json
+{"type":"agent.status","request_id":"req-status-1","agents":{"claude":{"installed":true,"version":"1.2.3"},"codex":{"installed":true,"version":"0.153.4","logged_in":true}},"dispatch":{"model":"opus","adapter":"claude"},"codex_logged_in":true,"rate_limits":null,"approval_mode":"ask_once"}
+```
+
+### 4.6 啟動請求：`agent.launch`（site -> Kenaz，請求）
+
+方向：`site -> relay -> agent`。
+何時發：site 想要開啟一個掛著自己 MCP 的 Ansuz 會話時，任何時間點（不限於剛配對完）。
+
+| 欄位 | 型別 | 說明 |
+|---|---|---|
+| `type` | `"agent.launch"` | |
+| `request_id` | string | site 產生 |
+| `prompt` | string | 交給 Ansuz 的起始 prompt |
+| `mcp` | string \| `{"name":string,"url":string}` | 選填。網站自己的 MCP 端點；字串形式時 `name` 由 Kenaz 依 origin 自動產生。省略時不預配任何網站 MCP |
+| `agent` | `"claude"` \| `"codex"` | 選填。省略時依使用者 dispatch 設定決定 |
+
+**只有 interactive**：`agent.launch` 一律在 Dashboard 開一個互動終端分頁，注入 Ansuz 人格，沒有 headless、沒有 `mode`、沒有 `cwd`（cwd 固定是 Dashboard 當前專案，網站不可指定，見第 7 節）。這與 Relay v1（A 期）的 `mode:"headless"|"interactive"` 語意不同，是 v0.3 的收斂決定（Q7）。
+
+#### Fixture: agent.launch
+```json
+{"type":"agent.launch","request_id":"req-launch-1","prompt":"在畫布 hero-banner 上新增一個 1024x1024 的角色立繪","mcp":"https://flowpix.app/mcp","agent":"claude"}
+```
+
+#### Fixture: agent.launch.mcp_object
+```json
+{"type":"agent.launch","request_id":"req-launch-2","prompt":"描述目前畫布上的所有節點","mcp":{"name":"flowpix","url":"https://flowpix.app/mcp"}}
+```
+
+### 4.7 審批：`approval.pending` / `approval.resolved`
+
+方向：`agent -> relay -> site`。
+何時發：Kenaz 收到 `agent.launch` 後，在**做任何事之前**先推 `approval.pending`；使用者在 Kenaz 本機決定後推 `approval.resolved`，兩則共用同一個 `request_id`（與觸發它們的 `agent.launch` 相同）。
+
+| 欄位 | 訊息 | 型別 | 說明 |
+|---|---|---|---|
+| `type` | 兩者 | `"approval.pending"` \| `"approval.resolved"` | |
+| `request_id` | 兩者 | string | 與 `agent.launch` 相同 |
+| `summary` | `approval.pending` | string | 給使用者看的審批卡摘要：origin + prompt 前 120 字 + agent/model + **cwd 絕對路徑**（第 7 節，不可省略） |
+| `decision` | `approval.resolved` | `"allow"` \| `"deny"` | 只有這兩個值會上線；「永遠允許」只改 Kenaz 本機的 origin 權限狀態，仍以 `allow` 送出，「封鎖」與「逾時」都送 `deny`（差異由後續的 `agent.unavailable.reason` 承載，不是額外的 decision 值） |
+
+#### Fixture: approval.pending
+```json
+{"type":"approval.pending","request_id":"req-launch-1","summary":"https://flowpix.app — 在畫布 hero-banner 上新增一個 1024x1024 的角色立繪 — claude / opus — cwd: C:\\Users\\user\\Documents\\GitHub\\FlowPixProject"}
+```
+
+#### Fixture: approval.resolved.allow
+```json
+{"type":"approval.resolved","request_id":"req-launch-1","decision":"allow"}
+```
+
+#### Fixture: approval.resolved.deny
+```json
+{"type":"approval.resolved","request_id":"req-launch-1","decision":"deny"}
+```
+
+### 4.8 啟動結果：`agent.launched` / `agent.unavailable`
+
+方向：`agent -> relay -> site`。
+何時發：`approval.resolved{decision:"allow"}` 之後，Kenaz 實際嘗試開啟終端分頁；成功推 `agent.launched`，CLI 不可用（未安裝、未登入等）推 `agent.unavailable`。`decision:"deny"` 的情況不會有後續訊息——site 從 `approval.resolved{deny}` 本身就知道流程結束。
+
+| 欄位 | 訊息 | 型別 | 說明 |
+|---|---|---|---|
+| `type` | 兩者 | `"agent.launched"` \| `"agent.unavailable"` | |
+| `request_id` | 兩者 | string | 與 `agent.launch` 相同 |
+| `agent` | 兩者 | `"claude"` \| `"codex"` | 實際使用的 CLI |
+| `session_id` | `agent.launched` | string | Kenaz 的 pty-server session 識別碼（不是裸 pid——interactive 分頁是 pty session，語意上等於 Relay v1 舊合約 §8 的 `pid`，欄位改名） |
+| `reason` | `agent.unavailable` | string | 人類可讀的不可用原因 |
+
+#### Fixture: agent.launched
+```json
+{"type":"agent.launched","request_id":"req-launch-1","agent":"claude","session_id":"pty-sess-42"}
+```
+
+#### Fixture: agent.unavailable
+```json
+{"type":"agent.unavailable","request_id":"req-launch-1","agent":"claude","reason":"claude CLI not logged in"}
+```
+
+### 4.9 結束通知：`agent.exited`
+
+方向：`agent -> relay -> site`。
+何時發：`agent.launched` 對應的終端分頁 session 結束（使用者關閉分頁、CLI 進程退出等）。
+
+| 欄位 | 型別 | 說明 |
+|---|---|---|
+| `type` | `"agent.exited"` | |
+| `request_id` | string | 與 `agent.launch`／`agent.launched` 相同 |
+| `session_id` | string | 與 `agent.launched.session_id` 相同 |
+| `exit_code` | number \| `null` | CLI 進程的退出碼；使用者手動關閉分頁等無明確退出碼的情況為 `null` |
+
+#### Fixture: agent.exited
+```json
+{"type":"agent.exited","request_id":"req-launch-1","session_id":"pty-sess-42","exit_code":0}
+```
+
+#### Fixture: agent.exited.null_exit_code
+```json
+{"type":"agent.exited","request_id":"req-launch-1","session_id":"pty-sess-42","exit_code":null}
+```
+
+### 4.10 配對中斷：`agent.disconnected`
+
+方向：`relay -> site`，unsolicited（`request_id` 為 `null`）。
+何時發：已配對的 agent 連線關閉（Kenaz 結束、網路中斷等）。site 收到後，狀態讀取（等同 Relay v1 的 `get_kenaz_status()`）應回報 `connected: false`。
+
+| 欄位 | 型別 | 說明 |
+|---|---|---|
+| `type` | `"agent.disconnected"` | |
+| `request_id` | `null` | |
+
+#### Fixture: agent.disconnected
+```json
+{"type":"agent.disconnected","request_id":null}
+```
+
+## 5. 深連結、site_key 與託管 relay（C 期，本檔預留）
+
+C 期（`dev/KENAZ_AGENT_CONNECT_v1_SPEC.md` 第 5 節）導入託管 relay 與人工發放的 `site_key`：`token.mint` 屆時會新增 `site_key` 欄位，relay 驗 origin 與 key 綁定。B 期（本卡）尚未強制這個欄位——`token.mint` 的 fixture 維持 CONTRACT.md §1–§2 的原始欄位集，`site_key` 留待 C 期落地時補上，不在本卡的 conformance suite 範圍內。
+
+## 6. 錯誤碼全集合
+
+| `error.code` | 出現在 | 意義 |
+|---|---|---|
+| `token_invalid` | `pair.denied` | 未知或從未發過的 token |
+| `token_expired` | `pair.denied` | token 超過 60 秒 TTL |
+| `token_already_used` | `pair.denied` | token 已經被消耗過（不論當時成功失敗） |
+| `origin_mismatch` | `pair.denied` | `pair.begin.site_origin` 與 token 綁定的 origin 不符 |
+| `relay_unavailable` | `pair.denied` | token 綁定的 site session 已斷線 |
+| `protocol_unsupported` | `pair.denied` \| 通用 `error` | `protocol_version` 缺失或不支援；或收到已廢止／未知的 `type`（B 期硬切，見下） |
+| `payload_too_large` | 通用 `error` | legacy：Relay v1（A 期）的 256 KiB 單幀上限，隨結果不再經 relay 而失去存在理由；relay 若仍對超大幀（例如異常長的 `prompt`）設上限，沿用此碼，非強制 |
+
+### `error`（通用，relay -> 發送方）
+
+方向：`relay -> sender`（不論 site 或 agent，誰送出有問題的幀就回誰）。
+何時發：收到未知 `type`、或收到已廢止的 Relay v1 型別（`generate_image`／`generate_text`／`result`／`blob.presign`／`blob.presigned`——見下方廢止清單）。**不斷線**，只回這一則錯誤。
+
+| 欄位 | 型別 | 說明 |
+|---|---|---|
+| `type` | `"error"` | |
+| `request_id` | string \| `null` | 有帶就回顯，沒帶（如未知型別本身缺欄位）就 `null` |
+| `error.code` | enum | 見上表 |
+| `error.message` | string | |
+
+#### Fixture: error.protocol_unsupported
+```json
+{"type":"error","request_id":"req-legacy-1","error":{"code":"protocol_unsupported","message":"generate_image was removed in protocol v1 — use agent.launch and the site's own MCP tools"}}
+```
+
+#### Fixture: error.payload_too_large
+```json
+{"type":"error","request_id":"req-oversized-1","error":{"code":"payload_too_large","message":"131400 bytes exceeds the relay frame limit"}}
+```
+
+## 7. 安全注意事項
+
+- **配對同意 ≠ 執行同意**：一個 origin 被使用者允許配對（`once` 或 `always`），不代表每一次 `agent.launch` 都自動執行——`approval_mode` 不是 `allow_all` 時，每次 `agent.launch` 都要走一次 `approval.pending`/`approval.resolved`。即使 `allow_all`，Kenaz 仍會在本機記錄一次審批事件供事後稽核；只是不彈窗打斷使用者。
+- **cwd 顯示**：`agent.launch` 驅動的 agent 在使用者 Dashboard 當前專案裡有寫入能力——網站的 prompt 內容完全由網站決定，Kenaz 不審核。因此 `approval.pending.summary` **必須**顯示 cwd 絕對路徑，讓使用者在按下允許前知道這次操作會在哪個資料夾裡發生。cwd 本身不可由網站透過 `agent.launch` 或深連結指定，永遠是 Dashboard 目前開啟的專案。
+- **Bearer 走 env**：`pair.ok.session_credential` 是之後 MCP 呼叫的 Bearer token。Kenaz 產生的 MCP config 把它放進環境變數（Codex：`bearer_token_env_var`；Claude Code：`--header "Authorization: Bearer <token>"` 由 Kenaz 組出，token 來源仍是環境變數，不落 `config.toml`、不進命令列明文、不寫入任何 log）。網站與 relay 都不會看到這個 token 以外的任何 AI 憑證——Codex/ChatGPT 登入狀態永遠留在使用者本機。
+- Relay 只做**配對、轉發、逐幀日誌**；它看不到、也不需要看到 prompt 以外的網站業務資料（生圖結果、寫回內容都走網站自己的 MCP，relay 不轉發）。
+
+## 8. 廢止清單（Relay v1 → v1，B 期硬切，無 adapter）
+
+以下型別／欄位在 Relay v1（A 期，`history/` 的 FlowPix CONTRACT.md 所定義）曾經存在，v0.3 硬切後**不再支援**。收到這些型別一律回 `error {code:"protocol_unsupported"}`（第 6 節），不做欄位轉換、不斷線：
+
+| 廢止項目 | 原用途 | 為什麼廢止 |
+|---|---|---|
+| `generate_image` / `generate_text` | site 請求 Kenaz 生圖／生文 | 網站自己的 MCP 工具處理，不進協定（Q7） |
+| `result`（含 `payload`／`error` 形狀） | agent 回傳生成結果 | 沒有 `generate_*` 就沒有對應的 `result`；`agent.launch` 的成敗改用 `agent.launched`／`agent.unavailable`／`agent.exited` 表達 |
+| `blob.presign` / `blob.presigned` / `presign_failed` | 大型結果的物件儲存簽章 URL | 結果不再經 relay，presign 失去存在理由 |
+| `reference_images` | `generate_*` 的參考圖網址陣列 | 隨 `generate_*` 一併廢止 |
+| 256 KiB 單幀上限的「原因」 | 避免大型 base64／result payload 塞爆 relay | payload 已不經 relay；上限本身可能仍存在（見 `payload_too_large`），但存在理由變了 |
+| `agent.launch.mode` | 區分 `headless` / `interactive` | 只剩 interactive，欄位移除（Q7） |
+| `agent.launch.cwd` | 網站指定工作目錄 | cwd 固定為 Dashboard 當前專案，網站不可指定（Q8） |
+| `pair.error`（flat `{request_id,code,message}`） | 配對失敗 | 改為巢狀 `pair.denied {request_id, error:{code,message}}`（D3），本檔第 4.3 節為準 |
+| `agent_unavailable`（底線） | CLI 不可用通知 | 正式收編為 `agent.unavailable`（點號，與其他 `agent.*` 型別命名一致） |
+| capability envelope（Q3 的 `<site>.<name>` 命名空間提案） | 讓網站自訂能力宣告 | Q7 移除 capability 概念——網站能做什麼完全由它自己的 MCP 決定，Kenaz 不列舉、不審核 |
+
+## 9. 參考來源
+
+- `dev/KENAZ_AGENT_CONNECT_v1_SPEC.md`（v0.3，第 2.3 節與第 6 節「已決定事項」是本檔的直接依據）
+- `history/`（FlowPix Relay v1 歷史文件，已被本檔取代，見 `history/README.md`）
+- 目前的 Rust 追隨者實作（尚未對齊本檔，TASK_1936 負責）：`dashboard/src-tauri/src/features/agent_hub/protocol.rs`、`deep_link.rs`、`relay_client.rs`、`launch.rs`

package/core/dev/specs/agent-connect/history/README.md

@@ -0,0 +1,47 @@
+# history/ — Relay v1（A 期）歷史來源
+
+這個資料夾是 **Kenaz Agent Connect 的前身「Relay v1」** 的原始文件存檔。Relay v1 是 FlowPix（`GameAsset_auto`）與 Kenaz 在 2026-09-07～09-08 之間，透過需求文件與回覆文件來回對帳出來的協定——它的核心是 `generate_image` / `generate_text` / `result` / `blob.presign` 這組「網站請求 Kenaz 生成內容、結果經 relay 回傳」的模型。
+
+**這一版協定已經被 [`../PROTOCOL.md`](../PROTOCOL.md)（v0.3）取代**。2026-09-08 當天，Kenaz 側用戶收斂了方向：Agent Connect 只標準化 **Web／Agent／Kenaz 三方接口**（網站發起、Kenaz 審批、開啟一個掛著網站 MCP 的 Ansuz 會話），生圖／寫回／結果回傳全部改成網站自己的 MCP 工具，不再進協定、不再經 relay。`generate_image`、`generate_text`、`result`、`blob.presign` 全部廢止（細節見 `PROTOCOL.md` 第 8 節「廢止清單」）。
+
+這些文件保留在這裡是為了：
+1. **考古**——理解為什麼 `PROTOCOL.md` 長成現在這樣（哪些欄位是從 Relay v1 直接收編的：`site.hello`／`site.ready`／`token.mint`／`token.minted`／`pair.begin`／`pair.ok`／`pair.denied`／`agent.connected`／`agent.disconnected`；哪些是被砍掉的）。
+2. **溯源**——`site.hello`→`token.mint`→深連結→`pair.begin` 這段配對流程的欄位名稱、TTL、one-time-use 語意，都是直接從這裡的 `FLOWPIX_bridge_CONTRACT.md` §1–§3 抄過去的，不是重新設計。
+3. **不做重複維護**——`FLOWPIX_bridge_CONTRACT.md` 的「Relay v1」章節不再更新；FlowPix 那邊已被通知（見 `KENAZ_RESPONSE_agent-hub_2026-09-08_direction-change-v0.3.md`）把 CONTRACT.md 的 Relay v1 章節改為引用本 repo 的 `PROTOCOL.md`。
+
+## 檔案清單（依時間順序）
+
+| 檔案 | 來源 | 內容 |
+|---|---|---|
+| `FEATURE_REQUEST_kenaz-agent-hub_2026-09-07.md` | FlowPix | K1–K8 初版需求：深連結、配對、審批 UI、Codex app-server、relay 轉發生成請求等 |
+| `KENAZ_RESPONSE_agent-hub_2026-09-07.md` | Kenaz | 對 K1–K8 的初次逐項回覆 |
+| `FLOWPIX_REPLY_agent-hub_2026-09-08_relay-v1-answers.md` | FlowPix | 對 Kenaz 09-07 回覆的追問與確認（D 系列問題的第一輪） |
+| `FLOWPIX_bridge_CONTRACT.md` | FlowPix | **合約本體**——`bridge/CONTRACT.md`，含 bridge HTTP contract、Agent hub v1（MCP 工具集）、以及本檔最相關的「Relay v1」章節（§Transport、Roles、1. Site handshake ~ 9. Disconnect、Security notes） |
+| `FLOWPIX_bridge_agent_relay_client.py` | FlowPix | 假 Kenaz 參考實作（`bridge/agent_relay_client.py`），逐訊息對照合約 |
+| `FLOWPIX_spikes_relay_spike_relay.mjs` | FlowPix | relay 原型（`spikes/relay_spike/relay.mjs`），token 一次性／60 秒／綁 origin 的參考行為 |
+| `FEATURE_REQUEST_kenaz-agent-hub_2026-09-08_relay-v1-conformance.md` | FlowPix | 回報三道 scheme 閘門擋掉本機開發環境、以及合約欄位漂移（D1–D10） |
+| `KENAZ_RESPONSE_agent-hub_2026-09-08_relay-v1-conformance.md` | Kenaz | 對 D1–D10 的逐項裁定；loopback 開發模式（`KENAZ_AGENT_HUB_DEV=1`）說明 |
+| `KENAZ_RESPONSE_agent-hub_2026-09-08_relay-v1-answers-ack.md` | Kenaz | 收到合約本體＋假 relay／假 Kenaz 後的三方最終對齊；bearer=session_credential、`agent.launch.mcp` 欄位形狀等細節確認 |
+| `KENAZ_RESPONSE_agent-hub_2026-09-08_direction-change-v0.3.md` | Kenaz | **方向收斂通知**——Relay v1 硬切為 v0.3，`generate_*`／`result`／`blob.presign` 全部廢止，改為 `agent.launch` + 網站自己的 MCP |
+
+最後四份（`KENAZ_RESPONSE_*` x4）是 Kenaz 這邊發出的回覆，隨 FlowPix 側的三份需求文件與合約本體一起歸檔，方便日後對照「誰在什麼時間點確認了什麼」。
+
+## 現況對照
+
+Relay v1 與 v0.3（`PROTOCOL.md`）的差異全表見 `PROTOCOL.md` 第 8 節「廢止清單」；配對流程（`site.hello` ~ `pair.denied`）在兩版之間沒有變化，`PROTOCOL.md` 第 4.1–4.4 節是直接收編，不是重新設計。
+
+## v0.3 → v0.4（TASK_1939，2026-09-08）
+
+`PROTOCOL_v0.3_snapshot.md`（本資料夾）是 `../PROTOCOL.md` 在 v0.3（WebSocket relay + 配對握手協定）最後一刻的凍結快照。TASK_1939 當天用戶再收斂一次方向（`dev/KENAZ_AGENT_CONNECT_v1_SPEC.md` v0.4 §6 Q10）：**relay 整個拿掉**。v0.3 剩下的「喚醒／憑證／狀態回報」三個功能分別由深連結（`kenaz://connect?site=&mcp=&token=`）、網站自己簽發的一次性 token、agent 呼叫網站 MCP 的 `kenaz_hello` 慣例工具取代——不再有 relay、WebSocket、`pair.*`／`agent.status`／`agent.launch`／`approval.*`（線上）／`agent.launched`／`agent.exited`／`error` 這些訊息型別，也不再有 `site.hello`／`token.mint` 這段從 Relay v1 收編來的握手。`../PROTOCOL.md` 現在只描述深連結格式與網站 MCP 的最小約定。
+
+## v0.4 上線後的第一輪回報（2026-09-09）
+
+FlowPix 用真實 Kenaz 0.2.230 把 v0.4 深連結 → 審批卡 → 終端分頁 → `kenaz_hello` 端到端驗通後送來的兩份文件，以及 Kenaz 側的回覆。這輪起 FlowPix 的文件經 Google Drive 傳遞，歸檔時保留原文。
+
+| 檔案 | 來源 | 內容 |
+|---|---|---|
+| `DEFECT_REPORT_kenaz-agent-hub_2026-09-09_v0.4-prompt-mojibake.md` | FlowPix | 深連結 `prompt=` 的中文到終端分頁變 Big5 亂碼（ACP 950 環境）；FlowPix 端已排除 URL 編碼問題 |
+| `KENAZ_RESPONSE_agent-hub_2026-09-09_prompt-mojibake-fixed.md` | Kenaz | 根因：`build_interactive_script` 寫出的 `.ps1` 沒有 UTF-8 BOM，PowerShell 5.1 以 ANSI 解碼內嵌字面值；TASK_1946 加 BOM + CJK 回歸測試（main `177b7f9ce`） |
+| `FEATURE_REQUEST_kenaz-agent-hub_2026-09-09_v0.4-session-channel.md` | FlowPix | C 期需求 S1–S5：session header、持續對話慣例 `kenaz_wait_for_message`、輸出串流、結束通知、預設允許網站 MCP 工具 |
+| `KENAZ_RESPONSE_agent-hub_2026-09-09_session-channel.md` | Kenaz | 裁定：S1+S5（TASK_1947）與 S2（TASK_1948）先做，S4 其次，S3 獨立評估（見該檔） |
+| `KENAZ_RESPONSE_agent-hub_2026-09-09_annotations-install-coldstart.md` | Kenaz | C-1b：`--allowedTools` 改依 tool annotations 分級（TASK_1949，FlowPix 要標 annotations）；未安裝落地流程 SDK_GUIDE §10（TASK_1950）；冷啟動深連結丟失根因與修復（TASK_1953）；三項在 main、尚未出貨 |

package/core/dev/specs/peer/CODEX_INTERACTIVE_PUSH.md

@@ -0,0 +1,65 @@
+# Bifrost interactive Codex as a peer push target (TASK_2167)
+
+## What the launcher does now
+
+`node .formation/bifrost/launch.js` (interactive path only):
+
+1. Picks a free port, starts `codex app-server --listen ws://127.0.0.1:<port>` (loopback only, same env as the TUI:
+   `KENAZ_PEER_PULL=1`, `KENAZ_CONSOLIDATE_ROOT`, `BIFROST_ADAPTER`), waits (max 15 s) until the ws endpoint accepts.
+2. Starts the normal TUI with the usual flags plus `--remote ws://127.0.0.1:<port>`.
+3. A watcher polls the app-server (`thread/loaded/list`, ranked by `thread/list` `updatedAt` only when several are
+   loaded) and calls `registerInteractive(projectRoot, wsUrl, threadId, pid)` -> `.kenaz/codex/sessions.json`.
+   A thread that newly appears (e.g. `/new`) replaces the registered one.
+4. On TUI exit, Ctrl-C, SIGTERM or app-server exit the entry is removed (only this launcher's own entry: matched on
+   `ws_url` + `pid`) and the app-server child is killed (`taskkill /T` on Windows, own PID only).
+
+Fallback: if the app-server cannot start or never accepts connections, one line
+`peer push unavailable for this session (...)` is printed, the TUI starts exactly as before (no `--remote`) and nothing is registered.
+
+Code: `.formation/bifrost/shared/codex-appserver.js` (helpers), `launch.js` (`startPushServer`, `launchCodex`).
+Test: `node --test dev/specs/peer/codex-push-launcher.test.js` (fake ws app-server; includes the negative control).
+
+## Pull vs push (no double delivery)
+
+`peer_poller.rs` pre-acks rows before a Claude push and, after `wake_codex_session` returns Delivered, sets
+`delivered_to_session = 1` on the same rows. The KENAZ_PEER_PULL hook only returns rows with `delivered_to_session = 0`,
+so a pushed message is not re-delivered by the pull. If the push fails (no entry, ws down, gate off) nothing is marked and the
+pull path delivers as before. The pull path itself is unchanged. Residual race: if the user submits a prompt (pull hook runs)
+in the instant between the poller storing a row and the push completing, both could show it; the message body is identical and idempotent to read.
+
+## Enabling push for a room (off by default)
+
+In the project that the Codex session works in, create or edit `.kenaz/peer.yaml`:
+
+```yaml
+codex_push: true
+```
+
+The default is and stays `false`; without this line the registry entry is ignored by the Dashboard and behaviour is unchanged
+(pull only). What it means: the Dashboard can then call `turn/start` / `turn/steer` on the live Codex session, so an
+external peer message can START a turn in a Codex running with `-s danger-full-access -a never` without the user typing anything.
+The text is wrapped by `frame_for_codex` and `neutralize_markup` but it is still untrusted input driving a full-access agent.
+Enable only for rooms whose peers you trust. Remove the line (or set `false`) to turn it off; no restart of the Codex session needed.
+
+## Verification status
+
+Automated: 7 node tests pass (fake app-server). Live (non-interactive shell): a real `codex app-server` on 127.0.0.1,
+`thread/start` + `turn/start` with a codeword -> agent message repeated it; the watcher discovered the thread and removed the entry on stop.
+
+NOT verified here (needs a human at a terminal, TASK_2141 risk 6): the real TUI attaching with `--remote`, and `/new` re-registration. Steps:
+
+1. In the target project set `.kenaz/peer.yaml` `codex_push: true`; Dashboard running.
+2. Run `node .formation/bifrost/launch.js --specialist Ansuz [--project <path>]`; expect the line `push target: app-server ws://127.0.0.1:<port>`.
+3. After the TUI is up, `cat <project>/.kenaz/codex/sessions.json` shows an `interactive` entry with a `thread_id`; send a prompt in the TUI so a turn exists.
+4. From another room send a peer message to this project; while the TUI is idle the Codex should start a turn on its own; while it is mid-turn the text should be steered in. Check it is not repeated by the next hook pull.
+5. Type `/new`, wait ~2 s: `thread_id` in sessions.json changes.
+6. Quit the TUI (or Ctrl-C): the `interactive` entry disappears and no `codex app-server` process for that port remains.
+
+## Launcher gate (2026-10-05)
+
+launch.js enters push-target mode (local app-server + TUI `--remote`) ONLY when the
+project's `.kenaz/peer.yaml` has `codex_push: true` (same parser as codex_wake.rs,
+`codexPushEnabled` in shared/codex-appserver.js). Rooms that did not opt in keep the
+plain TUI, so the experimental `--remote` path is never forced on them. On Node < 22
+(no global WebSocket) the launcher prints one line and uses the plain TUI immediately
+instead of waiting the 15 s readiness timeout.

package/core/dev/specs/peer/CODEX_PEER_PULL_SPIKE.md

@@ -0,0 +1,54 @@
+# Codex UserPromptSubmit hook injection spike (TASK_2299)
+
+Date: 2026-10-04. Codex CLI: `codex-cli 0.159.2` (model gpt-6-astra). Closes TASK_2141 open risk 5.
+
+## Result: WORKS
+
+A Codex `UserPromptSubmit` command hook's stdout reaches the model's context for that turn. Both shapes were accepted:
+
+| Hook stdout | Reached the model? |
+|---|---|
+| Plain text, e.g. `PEERNONCE_PLAIN_7Q4K` | yes |
+| JSON `{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"PEERNONCE_JSON_9X2M"}}` | yes |
+
+The shim uses plain text (simplest; no JSON-escaping of peer text).
+
+## Hook config format (config.toml, same as setup-codex.js already writes)
+
+```toml
+[[hooks.UserPromptSubmit]]
+
+[[hooks.UserPromptSubmit.hooks]]
+type = "command"
+command = 'node "/abs/path/hook.js"'
+timeout = 15
+```
+
+Hook stdin is JSON: `session_id`, `turn_id`, `transcript_path`, `cwd`, `hook_event_name`, `prompt` (observed keys: `session_id`, `turn_id`, `transcript_path`, `cwd`).
+
+## IMPORTANT: hook trust
+
+Codex 0.159.2 does NOT run a newly registered hook until it is reviewed/trusted ("New hook - review required"; persisted as `[hooks.state."<key>"] trusted_hash` in config.toml; re-review after the hook changes). Control run: with the hooks registered but untrusted, the model reported `NONE` and the hook log file was never written. Trust is granted by the user in the TUI (`/hooks`); `codex exec --dangerously-bypass-hook-trust` bypasses it for one invocation (used only in the isolated spike). So registering the hook via setup-codex.js is necessary but not sufficient: the user must trust it once, and again after the shim/command changes.
+
+## Commands (isolated CODEX_HOME; real ~/.codex untouched)
+
+1. Copy `~/.codex/auth.json` and `config.toml` to a temp dir; append two `[[hooks.UserPromptSubmit]]` blocks (plain-text hook, JSON hook).
+2. Control (no bypass): `CODEX_HOME=<tmp> codex exec --json --skip-git-repo-check -s read-only -C <tmp> "Repeat back any unusual codeword tokens ... If none, say NONE."` -> `NONE`, no hook log.
+3. With bypass: same command plus `--dangerously-bypass-hook-trust` -> agent_message `PEERNONCE_PLAIN_7Q4K` and `PEERNONCE_JSON_9X2M`; hook log shows stdin JSON.
+
+## This machine
+
+`~/.codex/config.toml` has NO kenaz hooks (no `[[hooks.*]]` at all, including UserPromptSubmit). `setup-codex.js` `missingHookEvents()` reports all five events missing. Installing (re-running setup-codex) plus a one-time `/hooks` trust review is needed before the pull is live.
+
+## Implementation
+
+`.formation/bifrost/openai/codex-hook-shim.js` on `UserPromptSubmit`: resolve root (`KENAZ_CONSOLIDATE_ROOT` or hook `cwd`, via `_peer-project-root.js`) -> `GET /api/peer/pending?peek=true&projectPath&sessionId` (2.5 s bound, fail-open) -> print Codex-tuned frame (mirrors `codex_wake.rs frame_for_codex`) to stdout -> `POST /api/peer/ack {projectPath, ids}`. Messages are text only; nothing is acted on. Tests: `dev/specs/peer/codex-hook-shim-peer.test.js`, `dev/specs/peer/setup-codex-hooks.test.js`.
+
+Gate: the pull runs only when `KENAZ_PEER_PULL=1` (set by `.formation/bifrost/launch.js` for the interactive session; `relay.js` deletes it from headless worker env) so formation workers sharing the user-wide hook never peek/ack the inbox.
+
+## Operational notes (2026-10-05, from wei@Ashfall's field verification)
+
+- Verified live on Ashfall after 645343bc8: three pending messages were injected on the next prompt.
+- Session identity: inside Codex, use `CODEX_SESSION_ID` as the session id (for `kenaz_peer_send` and handoffs). The fast-boot banner now prefers it (ansuz-boot-fast.js `harnessSessionIdFromEnv`); before that it reported an id taken from Claude hook hints, and replies bound to that id were not delivered to the Codex session.
+- Diagnostics: `GET /api/peer/pending?peek=true` WITH `sessionId` claims a 60 s lease on the returned rows (`peer.rs` LEASE_SECS, TASK_2285); a diagnostic peek under another id delays delivery to the real session for up to 60 s. Diagnose with peek and NO sessionId.
+- Idle push (delivery without a user prompt) is not provided for Codex: `codex_push` is off by design and the Claude helper push path (`expected exactly one SendMessage call`) is parked in favour of the kenaz-peer mod (TASK_2159 / TASK_2234).