kenaz 0.0.0-stage → 0.3.2

package/core/dev/scripts/verify-isbar-capture.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * verify-isbar-capture.js
+ * TASK_1115: Verify that a JSONL conversation produces a non-empty ISBAR context.
+ *
+ * Usage:
+ *   node dev/scripts/verify-isbar-capture.js <jsonl-path> [--project-path <path>]
+ *
+ * Exit 0: ISBAR capture passes — non-empty topic found
+ * Exit 1: ISBAR capture fails — topic is empty or only placeholder
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+let coordinator;
+try {
+  coordinator = require(path.join(ROOT, '.specialist', 'Ansuz', 'tools', 'preservation-coordinator'));
+} catch (e) {
+  console.error(`❌ Failed to load preservation-coordinator: ${e.message}`);
+  process.exit(1);
+}
+
+const {
+  analyzeConversationJsonl,
+  readActiveTaskTitle,
+  isFatiguePlaceholder,
+} = coordinator;
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args[0] === '--help') {
+    console.log('Usage: node verify-isbar-capture.js <jsonl-path> [--project-path <path>]');
+    console.log('');
+    console.log('Exit 0: valid ISBAR (non-empty topic)');
+    console.log('Exit 1: invalid ISBAR (empty or placeholder topic)');
+    process.exit(args[0] === '--help' ? 0 : 1);
+  }
+
+  const jsonlPath = path.resolve(args[0]);
+
+  let projectPath = ROOT;
+  const ppIdx = args.indexOf('--project-path');
+  if (ppIdx !== -1 && args[ppIdx + 1]) {
+    projectPath = path.resolve(args[ppIdx + 1]);
+  }
+
+  // Validate input file
+  if (!fs.existsSync(jsonlPath)) {
+    console.error(`❌ JSONL file not found: ${jsonlPath}`);
+    process.exit(1);
+  }
+
+  const stats = fs.statSync(jsonlPath);
+  const isEmpty = stats.size === 0;
+
+  console.log(`\nAnalyzing JSONL: ${jsonlPath}`);
+  console.log(`File size: ${stats.size} bytes${isEmpty ? ' (empty fixture)' : ''}`);
+
+  // Run conversation analysis
+  const conv = analyzeConversationJsonl(jsonlPath);
+
+  // Fallback: active task title
+  const taskTitle = readActiveTaskTitle(projectPath);
+  const effectiveTopic = conv.topic || (taskTitle ? `Working on: ${taskTitle}` : null);
+
+  console.log('\n=== Synthesized ISBAR Context ===');
+  console.log(`topic:             ${effectiveTopic || '(none)'}`);
+  console.log(`pending_decisions: ${conv.pendingDecisions.length > 0 ? '\n  - ' + conv.pendingDecisions.join('\n  - ') : '(none)'}`);
+  console.log(`key_decisions:     ${conv.keyDecisions.length > 0 ? '\n  - ' + conv.keyDecisions.join('\n  - ') : '(none)'}`);
+  console.log(`active_task_title: ${taskTitle || '(none)'}`);
+
+  // Assertions
+  const hasTopic = !!effectiveTopic && !isFatiguePlaceholder(effectiveTopic);
+  const hasPending = conv.pendingDecisions.length > 0;
+  const hasKeyDec = conv.keyDecisions.length > 0;
+
+  console.log('\n=== Assertions ===');
+  console.log(`non-empty topic:        ${hasTopic ? 'PASS ✅' : 'FAIL ❌'}`);
+  console.log(`pending_decisions:      ${hasPending ? 'PASS ✅' : 'INFO (none found)'}`);
+  console.log(`key_decisions:          ${hasKeyDec ? 'PASS ✅' : 'INFO (none found)'}`);
+
+  if (!hasTopic) {
+    if (isEmpty) {
+      console.error('\n❌ ISBAR capture FAIL: empty fixture — no user messages to extract topic from');
+    } else {
+      console.error('\n❌ ISBAR capture FAIL: topic is empty or only fatigue placeholder');
+    }
+    process.exit(1);
+  }
+
+  console.log('\n✅ ISBAR capture PASS');
+  process.exit(0);
+}
+
+main();

package/core/dev/scripts/verify-target-dir.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * verify-target-dir.js — canonical CARGO_TARGET_DIR for Rust verification (TASK_1879).
+ *
+ * THE canonical source. Every producer of verification commands (dispatch prompt
+ * generators, taskgen templates, verify scripts, formation runner/integration)
+ * must take the value from here instead of inventing its own directory.
+ *
+ * Why a short path at all (Windows): vendor/kuzu's CMake object paths exceed
+ * MAX_PATH (260) when the target dir sits under the repo or a worktree
+ * (worktree paths add ~40 chars). A short root like C:/t/... keeps CMake alive.
+ *
+ * Why ONE shared directory (user decision 2026-08-22): the previous convention
+ * — "each dispatch invents a unique dir (C:/t/vis, C:/t/emb, C:/t1599, ...)
+ * and deletes it afterwards" — was falsified in practice: 51 leftover target
+ * dirs, 693.9 GB, zero deletions between 2026-04-06 and 2026-08-04. A single
+ * shared dir bounds disk growth structurally instead of relying on agent
+ * discipline, and a warm incremental cache makes repeat verification faster.
+ *
+ * DELIBERATE TRADEOFF — parallel verifies serialize: concurrent cargo
+ * invocations against the same target dir queue on cargo's directory file
+ * lock. This does NOT corrupt anything; the later invocation prints
+ * "Blocking waiting for file lock on build directory" and waits at ~0% CPU.
+ * That is normal waiting, NOT a hang. To distinguish waiting from an orphan
+ * build holding the lock: list live processes — a healthy queue has another
+ * cargo/rustc actively compiling (CPU > 0 somewhere); an orphan holder is a
+ * cargo.exe / build-script-build.exe at 0% CPU with NO rustc children
+ * (nothing is compiling). Only in the orphan case kill the holder.
+ *
+ * Cache-heat caveat: kuzu is a [patch] path dependency, so its build artifacts
+ * are keyed per source root. Verifies from the SAME checkout (main repo, or a
+ * reused worktree) get the warm cache; a verify from a NEW worktree path
+ * recompiles kuzu but coexists in the same dir without invalidating others.
+ * The dir therefore still grows across many distinct worktree roots — when it
+ * gets too big, delete the whole canonical dir while no cargo is running; it
+ * is pure cache and rebuilds itself.
+ *
+ * Cleanup of stray non-canonical dirs: dev/scripts/clean-verify-targets.js.
+ *
+ * Usage:
+ *   const { verifyTargetDir } = require('dev/scripts/verify-target-dir.js');
+ *   node dev/scripts/verify-target-dir.js        # prints the value (for shell:
+ *   CARGO_TARGET_DIR=$(node dev/scripts/verify-target-dir.js) cargo check ...)
+ *
+ * Override: KENAZ_CARGO_TARGET_DIR env var (test harness / ops escape hatch).
+ */
+'use strict';
+
+const os = require('os');
+const path = require('path');
+
+// GEN-008 exception, documented: this MUST live outside the repo — the entire
+// point is escaping the repo's deep path prefix. Keep it short; C:/t/kenaz-verify
+// is 16 chars and proven headroom-equivalent to the old C:/t/mainverify (15).
+const CANONICAL_WIN32 = 'C:/t/kenaz-verify';
+
+function verifyTargetDir() {
+  if (process.env.KENAZ_CARGO_TARGET_DIR) return process.env.KENAZ_CARGO_TARGET_DIR;
+  if (process.platform === 'win32') return CANONICAL_WIN32;
+  // No MAX_PATH problem elsewhere; still shared+short for the same cache-heat
+  // and bounded-growth reasons (GEN-009: same behavior on all three platforms).
+  return path.join(os.tmpdir(), 'kenaz-verify');
+}
+
+module.exports = { verifyTargetDir, CANONICAL_WIN32 };
+
+if (require.main === module) {
+  process.stdout.write(verifyTargetDir());
+}

package/core/dev/scripts/verify-task-1839.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * TASK_1839 verification — forseti-verify now consumes the shared dispatch-lock
+ * protocol (utils.dispatchLockPath + utils.dispatchLockStaleness) instead of
+ * carrying a third inline implementation.
+ *
+ * Arms:
+ *  A. Source hygiene: no inline `.dispatch-lock-` path string, no hard-coded
+ *     3_600_000 staleness constant in forseti-verify.js.
+ *  B. Cross-implementation mutual exclusion: a lock acquired by forseti's
+ *     acquireDispatchLock (at utils.dispatchLockPath) blocks
+ *     utils.tryAcquireDispatchLock, and cleanupStaleLocks does NOT delete it
+ *     while fresh + live (control: must survive).
+ *  C. Control (must-wait): forseti does NOT break a fresh lock held by a live
+ *     pid — it waits and times out with the lock intact.
+ *  D. TASK_1833 guard: a 30min pid:null serial lock is NOT judged dead —
+ *     forseti waits, lock survives.
+ *  E. Stale break: a 90min-old lock IS broken and re-acquired by forseti.
+ *  F. Dead-pid break: a fresh lock whose pid is dead IS broken.
+ *  G. Crash recovery seam: a forseti lock aged to 90min is cleared by
+ *     cleanupStaleLocks (the sweep recognizes forseti's lock file).
+ *
+ * Uses a fake projectPath so the lock key never collides with real dispatches.
+ * NOTE: arms C and D each busy-spin ~5s (forseti's existing LOCK_POLL_MS wait,
+ * deliberately unchanged by TASK_1839).
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const forseti = require(path.join(ROOT, '.formation', 'tools', 'forseti-verify.js'));
+const utils = require(path.join(ROOT, '.formation', 'tools', 'utils.js'));
+const registry = require(path.join(ROOT, '.formation', 'tools', 'dispatch-registry.js'));
+
+const FAKE_PROJECT = 'C:/tmp/task1839_probe_project';
+const LOCK = utils.dispatchLockPath(FAKE_PROJECT);
+
+let pass = 0, fail = 0;
+function check(name, ok, detail = '') {
+  if (ok) { pass++; console.log(`  ✅ ${name}`); }
+  else { fail++; console.log(`  ❌ ${name}${detail ? ` — ${detail}` : ''}`); }
+}
+function rmLock() { try { fs.unlinkSync(LOCK); } catch { /* absent */ } }
+function writeLock(holder) {
+  fs.mkdirSync(path.dirname(LOCK), { recursive: true });
+  fs.writeFileSync(LOCK, JSON.stringify(holder));
+}
+function readLock() {
+  try { return JSON.parse(fs.readFileSync(LOCK, 'utf8')); } catch { return null; }
+}
+function minutesAgo(m) { return new Date(Date.now() - m * 60000).toISOString(); }
+
+// ── A. Source hygiene ──
+console.log('\nArm A: source hygiene');
+{
+  const src = fs.readFileSync(path.join(ROOT, '.formation', 'tools', 'forseti-verify.js'), 'utf8');
+  // Only the require + comments may mention the protocol; no template/string
+  // that BUILDS a .dispatch-lock-* filename may remain.
+  const inlinePath = /['"`]\.dispatch-lock-\$\{|['"`]\.dispatch-lock-[a-z]/.test(src);
+  check('no inline .dispatch-lock-* path construction', !inlinePath);
+  check('no hard-coded 3_600_000 staleness constant', !src.includes('3_600_000') && !src.includes('3600000'));
+  check('requires dispatchLockPath + dispatchLockStaleness from utils',
+    /require\('\.\/utils'\)/.test(src) && src.includes('dispatchLockPath') && src.includes('dispatchLockStaleness'));
+  check('no local isProcessAlive dead-pid implementation remains', !src.includes('function isProcessAlive'));
+}
+
+// ── B. Cross-implementation mutual exclusion (fresh live lock must survive) ──
+console.log('\nArm B: cross-implementation mutual exclusion');
+{
+  rmLock();
+  const { release } = forseti.acquireDispatchLock(LOCK, 'TASK_1839_TEST', 100);
+  const held = readLock();
+  check('forseti acquired at utils.dispatchLockPath location', !!held && held.tool === 'forseti-verify');
+  const attempt = utils.tryAcquireDispatchLock(LOCK, { taskId: 'INTRUDER', pid: process.pid });
+  check('tryAcquireDispatchLock refuses forseti-held fresh lock', attempt.acquired === false);
+  const after = readLock();
+  check('tryAcquireDispatchLock did not destroy the lock', !!after && after.tool === 'forseti-verify');
+  registry.cleanupStaleLocks(null);
+  check('cleanupStaleLocks leaves fresh live forseti lock (control)', readLock() !== null && readLock().tool === 'forseti-verify');
+  release();
+  check('forseti release() removes its own lock', !fs.existsSync(LOCK));
+}
+
+// ── C. Control: fresh live-pid lock held by another — forseti must WAIT, not break ──
+console.log('\nArm C: must-wait control (~5s spin)');
+{
+  writeLock({ taskId: 'OTHER_TASK', pid: process.pid, startedAt: new Date().toISOString() });
+  const { release } = forseti.acquireDispatchLock(LOCK, 'TASK_1839_TEST', 100); // times out
+  const holder = readLock();
+  check('fresh live lock NOT broken (still OTHER_TASK)', !!holder && holder.taskId === 'OTHER_TASK');
+  release(); // acquired=false -> must be a no-op
+  check('release() after timeout does not delete the other holder\'s lock', fs.existsSync(LOCK));
+  rmLock();
+}
+
+// ── D. TASK_1833 pid:null serial lock at 30min — not dead, must survive ──
+console.log('\nArm D: pid:null serial lock survives (~5s spin)');
+{
+  writeLock({ taskId: 'SERIAL_1833', pid: null, holder: 'subagent-shared-tree', startedAt: minutesAgo(30) });
+  const { release } = forseti.acquireDispatchLock(LOCK, 'TASK_1839_TEST', 100);
+  const holder = readLock();
+  check('30min pid:null lock NOT judged dead/broken', !!holder && holder.taskId === 'SERIAL_1833');
+  release();
+  rmLock();
+}
+
+// ── E. Stale (90min) lock — forseti must break and acquire ──
+console.log('\nArm E: stale break');
+{
+  writeLock({ taskId: 'ANCIENT', pid: null, startedAt: minutesAgo(90) });
+  const { release } = forseti.acquireDispatchLock(LOCK, 'TASK_1839_TEST', 30_000);
+  const holder = readLock();
+  check('90min stale lock broken and re-acquired by forseti', !!holder && holder.tool === 'forseti-verify');
+  release();
+}
+
+// ── F. Dead-pid lock — forseti must break ──
+console.log('\nArm F: dead-pid break');
+{
+  const dead = spawnSync(process.execPath, ['-e', ''], { windowsHide: true });
+  writeLock({ taskId: 'DEAD_HOLDER', pid: dead.pid, startedAt: new Date().toISOString() });
+  const { release } = forseti.acquireDispatchLock(LOCK, 'TASK_1839_TEST', 30_000);
+  const holder = readLock();
+  check('fresh dead-pid lock broken and re-acquired', !!holder && holder.tool === 'forseti-verify');
+  release();
+}
+
+// ── G. Crash seam: aged forseti lock cleared by cleanupStaleLocks ──
+console.log('\nArm G: cleanupStaleLocks recognizes an aged forseti lock');
+{
+  writeLock({ taskId: 'TASK_1839_TEST', pid: 999999999, tool: 'forseti-verify', startedAt: minutesAgo(90) });
+  registry.cleanupStaleLocks(null);
+  check('90min forseti lock swept by cleanupStaleLocks', !fs.existsSync(LOCK));
+  rmLock();
+}
+
+console.log(`\n${fail === 0 ? '✅' : '❌'} verify_1839: ${pass} passed, ${fail} failed`);
+process.exit(fail === 0 ? 0 : 1);

package/core/dev/specs/agent-connect/PROTOCOL.md

@@ -0,0 +1,177 @@
+# Kenaz Agent Connect — Protocol v0.4 (PROTOCOL.md)
+
+- **開發者請先讀 [`SDK_GUIDE.md`](./SDK_GUIDE.md)**——那份文件是給生態系網站開發者的接入指南（10 分鐘接入、深連結參數表、MCP 約定、審批 UX、開發模式、測試、疑難排解 toast 對照表、可跑的 `examples/minimal-site/` 範例），本檔是它背後的協定權威來源。只需要接入的讀者不需要從這裡開始讀。
+- Status: **finalized draft**, B 期（TASK_1939，2026-09-08）。取代本檔 v0.3（WebSocket relay + 配對握手協定，凍結快照在 `history/PROTOCOL_v0.3_snapshot.md`）。
+- 標準所有權：本檔是唯一權威來源。`dev/KENAZ_AGENT_CONNECT_v1_SPEC.md` 第 2.3 節指向本檔。
+- **v0.4 的核心收斂（用戶決定，2026-09-08 晚，spec 第 6 節 Q10）：relay 整個拿掉。** 三方接口只剩兩個東西——一個 `kenaz://connect` 深連結格式、一份「網站 MCP 該長什麼樣」的最小約定。沒有 relay、沒有 WebSocket、沒有配對憑證交換、沒有線上協定訊息型別。v0.3 剩下的喚醒／憑證／狀態回報三個功能分別由深連結、網站自己簽發的一次性 token、agent 呼叫網站 MCP 得取代——見第 4 節「廢止清單」。
+- 這份文件的每個 ```json 範例都必須是**可直接 `JSON.parse` 的合法 JSON**——不可有 `|`、不可有註解、不可有多形態塞進同一個區塊。`dashboard/scripts/agent-connect-conformance/fixtures.mjs` 直接抽取這些區塊當作 conformance suite 的唯一 fixture 來源；本檔任何一個區塊解析失敗，測試就會 fail。
+
+## 0. 一句話
+
+**任何網站只要照 Kenaz 的深連結格式與 MCP 約定開發，就能用一個深連結在用戶本機喚醒 Kenaz、經用戶審批後開啟一個掛著該網站 MCP 的 Ansuz 會話；之後網站與 agent 之間的一切都走網站自己的 MCP。**
+
+三方接口：
+- **Web → Kenaz**：深連結 `kenaz://connect?site=&mcp=&token=[&prompt=][&agent=][&v=]`。用戶按下「連接」那一下（同意深連結）就是 launch 本身——沒有另外的 launch 訊息，沒有事先的配對步驟。
+- **Kenaz → Web**：沒有回程通道。網站靠 agent 呼叫它自己的 MCP 得知「連上了」（`kenaz_hello` 慣例工具，見第 2 節），逾時未呼叫就顯示「請安裝 Kenaz」。
+- **Agent ↔ Web**：只透過網站的 MCP 工具，bearer = 深連結裡的一次性 token，由網站自己簽發與驗證。
+
+明確的非目標：這不是 OAuth、不是帳號系統、不做用戶身份聯邦。「透過 Kenaz 登入 agent」的意思是把網站和本機 agent 串起來，網站不需要知道用戶是誰。
+
+## 1. 深連結格式
+
+```
+kenaz://connect?site=<url-encoded https origin>&mcp=<url-encoded https MCP url>&token=<one-time token>[&prompt=<url-encoded text>][&agent=claude|codex][&v=1]
+```
+
+| 參數 | 必填 | 說明 |
+|---|---|---|
+| `site` | 是 | 網站 origin。`https://...`；開發模式（`KENAZ_AGENT_HUB_DEV=1` 或 debug build）允許 `http://localhost` / `http://127.0.0.1` / `http://[::1]`。Kenaz 用 `Url::origin().ascii_serialization()` 正規化，去掉 path/query/fragment，作為 sites.json 的 key。 |
+| `mcp` | 是 | 網站自己的 MCP 端點，完整 URL（含 path）。scheme 規則與 `site` 相同（https；dev 模式同上放寬）。**審批卡以其 host 為主要識別**（第 3 節）——沒有 relay 就沒有「relay 驗過的 origin」，MCP URL 是 agent 真正會連的對象。 |
+| `token` | 是 | 一次性 bearer，≤512 字元，charset 限 `[A-Za-z0-9._-]`；由網站自己簽發、綁定它自己的用戶 session、自己驗證。Kenaz 不解讀、不落盤持久化——只在這次啟動的存續期間，以環境變數形式交給 agent 當 MCP 的 `Authorization: Bearer` 值。 |
+| `prompt` | 否 | 起始 prompt，交給 Ansuz 當第一則使用者訊息。**省略時由 Kenaz 自己補一句開場訊息**（純 ASCII，帶 `site` origin）觸發第一個 turn——網站不必也不應為了讓 agent 動起來而塞 `prompt=`（見第 2 節第 5 點 `kenaz_wait_for_message`）。深連結整體長度在 Windows 上約有 2 KB 限制——長內容請放在 MCP 工具裡讓 agent 自己取，不要塞進 `prompt=`。 |
+| `agent` | 否 | 指定 CLI，`"claude"` 或 `"codex"`。省略時依用戶的 dispatch 設定決定；顯式指定的 CLI 未安裝時 launch 失敗（不會靜默退回預設值）。 |
+| `v` | 否 | 協定版本，缺省 `"1"`。Kenaz 只認識自己支援的版本；不支援的版本一律 toast 拒絕（"protocol version unsupported"），不出審批卡。目前只有 `"1"`。 |
+
+任何其他/未知 query 參數（包含 v0.3 的 `relay=`）一律靜默忽略，不拒絕——只有格式不合法（scheme 錯誤、`token` 過長、`v` 不支援等）才拒絕。
+
+#### Fixture: deep_link.valid
+
+```json
+{"name": "valid", "url": "kenaz://connect?site=https://flowpix.app&mcp=https://flowpix.app/mcp&token=a1b2c3d4e5f60718293a4b5c6d7e8f90&prompt=summarize+the+canvas&agent=claude"}
+```
+
+#### Fixture: deep_link.missing_mcp
+
+```json
+{"name": "missing_mcp", "url": "kenaz://connect?site=https://flowpix.app&token=a1b2c3d4e5f60718293a4b5c6d7e8f90", "rejected_because": "missing required field: mcp"}
+```
+
+#### Fixture: deep_link.http_site_not_dev
+
+```json
+{"name": "http_site_not_dev", "url": "kenaz://connect?site=http://evil.example&mcp=https://flowpix.app/mcp&token=abc", "rejected_because": "site scheme not allowed: http (not localhost/127.0.0.1/[::1], or not in dev mode)"}
+```
+
+#### Fixture: deep_link.unsupported_version
+
+```json
+{"name": "unsupported_version", "url": "kenaz://connect?site=https://flowpix.app&mcp=https://flowpix.app/mcp&token=abc&v=999", "rejected_because": "protocol version unsupported: 999"}
+```
+
+Kenaz 收到後的完整流程：解析並驗證 → 若該 origin 已被封鎖，直接 toast 拒絕（不出審批卡）→ 否則出審批卡（第 3 節）→ 允許則在 Dashboard 開一個互動終端分頁：用戶配置的 CLI（`claude` 或 `codex`）+ Ansuz 人格（`session.js prompt Ansuz --mode=assembled --depth=elixir --no-muninn` 的輸出，逐字沿用）+ 預配 MCP（`{"mcpServers":{<name>:{"type":"http","url":<mcp>,"headers":{"Authorization":"Bearer <token>"}}}}`，`<name>` 由 `mcp` 的 hostname 衍生）+ `prompt` 作為第一則使用者訊息。cwd 永遠是 Dashboard 目前開啟的專案——網站不可指定。
+
+## 2. 網站 MCP 最小約定
+
+任何網站只要提供一個符合下列約定的 MCP 端點，就能被 Kenaz 的深連結串接：
+
+1. **驗證 bearer**：每個請求的 `Authorization: Bearer <token>` 必須被驗證是自己簽發、未過期、未撤銷的。Kenaz 不做任何驗證——這完全是網站自己的責任，也是網站唯一需要信任的邊界（Kenaz 只是把深連結裡的 token 原樣轉交給 agent）。
+1b. **`X-Kenaz-Session` header（TASK_1947，選讀）**：Kenaz 預配 MCP 時，除了 `Authorization: Bearer <token>` 之外，一律額外送一個 `X-Kenaz-Session: <launch_id>` header——`<launch_id>` 是 Kenaz 在這次啟動一開始就產生的 uuid v4（早於任何 pty 終端 session id 存在之前），同一次深連結啟動的存續期間固定不變。網站**不需要**讀這個 header 才能運作（bearer 仍是唯一必須驗證的邊界，見上一點）；它存在的目的是讓網站能分辨「這次 MCP 呼叫屬於哪一次連接」，比單純用 token 對應更直接——同一個 token 理論上可能被同一使用者的多個分頁/連接重用，但 launch_id 保證每次啟動獨一無二。codex 分支目前用 `-c mcp_servers.<name>.env_http_headers` 覆寫達到同樣效果（見下方「codex 限制」一節）；claude 分支則直接寫進預配 MCP JSON 的 `headers`。
+2. **提供 `kenaz_hello` 工具（建議）**：無參數，成功回 `{"ok": true}`。Ansuz 人格會在會話開始時、處理 `prompt` 之前呼叫一次——這是網站得知「Kenaz 真的連上了」的唯一方式（沒有回程通道，見第 0 節）。網站建議設一個逾時（建議 60 秒）：逾時未收到 `kenaz_hello` 呼叫，就顯示「請安裝 Kenaz」之類的安裝指引，而不是無限等待。
+3. **其餘工具完全由網站自訂**：Kenaz 不列舉、不審核、不限制。網站的產品邏輯（生圖、寫回、查詢……）全部經由這些自訂工具與 agent 互動，Kenaz 對這段流量完全不可見。
+4. **沒有結束通知**：agent 的終端分頁何時關閉，網站不會被告知。網站應以 token 撤銷或閒置逾時來回收狀態，不要假設有明確的「已結束」事件。
+5. **可選：`kenaz_wait_for_message`（持續對話，TASK_1948，FlowPix 分靈 2026-09-09 Feature Request S2）**：`kenaz_hello` 只解決「連上了沒」，不解決「agent 會不會一直聽網站接下來說的話」——這一點刻意不留給網站自己做 prompt 工程，而是搬進 Kenaz 人格本身：網站只要在 `tools/list` 多提供一個無參數工具 `kenaz_wait_for_message`，Ansuz 人格在呼叫過 `kenaz_hello` 並處理完 `prompt` 之後，就會反覆呼叫它。**`prompt` 省略時由 Kenaz 保證仍有一個真實的第一個 turn**（TASK_1956）——CLI 的位置參數就是互動式會話的第一則使用者訊息，空字串等於沒有第一個 turn，人格與這條約定就永遠不會被讀到；Kenaz 在 `prompt` 為空/空白時會自己補一句純 ASCII 的開場訊息（帶 `site` origin）當作這個第一則訊息，網站因此完全不需要、也不應該為了觸發第一個 turn 而自己塞一句 `prompt=`。
+   - **回傳形狀**（無參數呼叫，成功時）：
+     ```json
+     {"message": "<string|null>", "message_id": "<string|null>", "end": false}
+     ```
+     `end` 欄位可省略，省略時視為 `false`。
+   - `message` 非 `null`：agent 把它當成使用者的下一則指令執行，執行完再呼叫一次 `kenaz_wait_for_message`。
+   - `message` 為 `null`：目前沒有新訊息，不是錯誤——agent 直接再呼叫一次。
+   - `end` 為 `true`：agent 停止呼叫，告知使用者對話已結束。
+   - agent 連續呼叫這個工具失敗（逾時、拋錯、連線失敗）達 3 次，也會停止並告知使用者。
+   - 這個工具沒被列在網站的 `tools/list` 裡時，agent 完全不會呼叫它、也完全不會向使用者提起它——這段行為對沒有實作它的網站是純粹的無操作，不影響本節其餘四點的最小約定。
+   - **成本條款（強制）**：每一次 `kenaz_wait_for_message` 呼叫都是一次真實的 agent turn，成本由 Kenaz 使用者自己的訂閱額度承擔，不是網站的成本。網站**必須**用長輪詢實作——建議在伺服器端阻塞 **20-25 秒**才回傳 `message: null`，把呼叫頻率壓到最低；**不得**用短輪詢（例如每 1 秒就回一次 `null`）迫使 agent 高頻空轉，消耗使用者的訂閱額度。這是本約定唯一的強制條款，其餘都是建議。
+6. **建議標 `tool annotations`（TASK_1949，Agent Connect C-1b）**：`tools/list` 回應裡每個工具可以帶一個 `annotations` 物件（`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`，MCP 規格既有欄位）。claude 分支啟動前會對你的 MCP 做一次 3 秒的 `tools/list` 探測，把 `readOnlyHint: true` 或 `destructiveHint: false` 的工具直接加進 `--allowedTools`（跳過第一次呼叫的終端機權限提示）；沒有 `annotations`、或有 `annotations` 但沒寫 `destructiveHint` 的工具，一律當成「有後果」（MCP 規格 `destructiveHint` 缺省即為 `true`），維持逐次詢問。探測本身逾時、回應非 2xx、JSON 解析失敗、或回應裡沒有 `result.tools` 陣列，一律不預先允許任何工具（不是退回全允、也不是整個 MCP 都不能用——只是每次呼叫都會跳終端機提示），並在啟動的終端第一行印出失敗原因。**未標 annotations 的工具在 claude 會逐次提問**——這不影響功能，只影響使用者要不要多按幾次終端機提示。
+
+#### Fixture: mcp.tools_list_with_annotations
+
+```json
+{"jsonrpc": "2.0", "id": 1, "result": {"tools": [{"name": "kenaz_hello", "annotations": {"destructiveHint": false, "idempotentHint": true}}, {"name": "kenaz_wait_for_message", "annotations": {"readOnlyHint": true}}, {"name": "echo", "annotations": {"readOnlyHint": true}}, {"name": "delete_all_data", "annotations": {"destructiveHint": true}}]}}
+```
+
+#### Fixture: mcp.kenaz_hello_call
+
+```json
+{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "kenaz_hello", "arguments": {}}}
+```
+
+#### Fixture: mcp.kenaz_hello_result
+
+```json
+{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "{\"ok\":true}"}], "isError": false}}
+```
+
+#### Fixture: mcp.config_with_session_header
+
+claude 分支預配的 MCP config JSON 形狀（TASK_1947）——`headers` 同時帶 `Authorization` 與 `X-Kenaz-Session`：
+
+```json
+{"mcpServers": {"flowpix": {"type": "http", "url": "https://flowpix.app/mcp", "headers": {"Authorization": "Bearer a1b2c3d4e5f60718293a4b5c6d7e8f90", "X-Kenaz-Session": "1b0d6b9a-8f2a-4c56-8abc-9f9e9c9d9e9f"}}}}
+```
+
+#### Fixture: mcp.kenaz_wait_for_message_call
+
+```json
+{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "kenaz_wait_for_message", "arguments": {}}}
+```
+
+#### Fixture: mcp.kenaz_wait_for_message_result_message
+
+```json
+{"jsonrpc": "2.0", "id": 2, "result": {"content": [{"type": "text", "text": "{\"message\":\"add a red circle to the canvas\",\"message_id\":\"m_1\",\"end\":false}"}], "isError": false}}
+```
+
+#### Fixture: mcp.kenaz_wait_for_message_result_null
+
+```json
+{"jsonrpc": "2.0", "id": 2, "result": {"content": [{"type": "text", "text": "{\"message\":null,\"message_id\":null}"}], "isError": false}}
+```
+
+## 3. 審批與權限模型
+
+不變於 v0.3：per-origin 四態權限，`unauthorized` / `once` / `always` / `blocked`，持久化在 `~/.kenaz/agent_hub/sites.json`。
+
+- `unauthorized`／`once`：每次深連結請求都出一張審批卡，內容：**site origin**、**MCP host**（主要識別——沒有 relay 驗證過的 origin，MCP 端點是 agent 真正會連的對象）、要用的 `agent`/`model`、**cwd 絕對路徑**（不可省略——網站的 prompt 完全由網站決定，用戶按允許前必須知道這次操作會在哪個資料夾發生）、`prompt` 前 120 字。用戶選擇 一次允許 / 永遠允許 / 拒絕 / 封鎖此網站。
+- `always`：跳過審批卡，直接執行（仍在本機記錄一次事件供事後稽核）。
+- `blocked`：直接拒絕，不出審批卡，只有一個本機 toast。`blocked` 也可由手動編輯 `sites.json` 達成——每次請求都重新讀檔，不信任純記憶體快取。
+- 一個被暫停的 Agent Hub（tray「Pause Agent Hub」）擋下所有深連結，包含 `always` 狀態的 origin，且不出審批卡。
+
+審批卡摘要字串格式：`"{site} → MCP {mcp_host} → {agent}/{model} · cwd {絕對路徑} · {prompt 前 120 字}"`。
+
+## 4. 廢止清單（v0.3 → v0.4，relay 全部拿掉）
+
+以下 v0.3（WebSocket relay 協定，含它收編自 Relay v1 的配對握手）曾經存在的一切，v0.4 硬切後**不再支援**。完整的歷史協定內容見 `history/PROTOCOL_v0.3_snapshot.md`；Relay v1（FlowPix）的更早歷史見 `history/README.md`。
+
+| 廢止項目 | 原用途 | 由什麼取代 |
+|---|---|---|
+| relay（整個角色，含託管 relay、`site_key`、網站註冊） | Kenaz 與網站之間的中介轉發服務 | 沒有中介——深連結直達 Kenaz，Kenaz 與網站之間再無任何直接通訊 |
+| WebSocket 連線（`ws://`/`wss://`） | relay ↔ Kenaz、relay ↔ 網站的雙向連線 | 深連結是一次性、單向、同步的請求；沒有任何持續連線 |
+| `site.hello` / `site.ready` | 網站向 relay 註冊一個 session | 不需要——網站不與 Kenaz 建立任何連線 |
+| `token.mint` / `token.minted` | 網站向 relay 請求一次性配對 token | 網站自己簽發 `token`，直接放進深連結 |
+| `pair.begin` / `pair.ok` / `pair.denied`（含 `protocol_version` 欄位） | Kenaz 向 relay 用 token 換取 `session_credential` | 深連結本身就是完整請求；`token` 直接就是 MCP bearer，不需要換發；深連結自己的 `v=` 參數取代線上版本協商 |
+| `agent.connected` / `agent.disconnected` | relay 通知網站「Kenaz 連上／斷線了」 | 網站靠 agent 呼叫 `kenaz_hello`（第 2 節）得知連上；沒有斷線通知 |
+| `agent.status`（含 `agents`/`dispatch`/`codex_logged_in`/`approval_mode`） | Kenaz 主動推送安裝/登入/審批狀態 | 沒有回程通道；審批狀態直接影響審批卡本身是否出現（第 3 節），網站不需要知道 |
+| `agent.launch`（線上訊息，含 `mcp`/`agent` 欄位） | 網站透過 relay 請求啟動一個 agent | 深連結本身就是這個請求——`mcp=`/`agent=` 是深連結參數，不是另一則訊息 |
+| `approval.pending` / `approval.resolved`（線上訊息） | Kenaz 把審批結果告知網站 | 沒有回程通道；審批只影響 Kenaz 本機是否執行 |
+| `agent.launched` / `agent.unavailable` / `agent.exited` | Kenaz 把啟動結果/結束狀態告知網站 | 沒有回程通道；網站靠 `kenaz_hello` 得知連上，之後的一切都是網站自己 MCP 工具的呼叫紀錄 |
+| 通用 `error {code, message}` | relay 對未知/廢止訊息型別的拒絕 | 深連結解析失敗直接 toast 拒絕（本機），沒有線上訊息可回 |
+| `session_credential`（`sites.json` 欄位） | relay 核發、持久化以便重連 | 深連結的 `token` 每次都由網站重新提供，不持久化、不重連 |
+| `relay_url`（`sites.json` 欄位） | 記住上次配對的 relay 端點 | 沒有 relay |
+| `mcp_url`（`sites.json` 欄位，v0.3 的「上次用過的 MCP」） | 供重連時沿用 | 深連結每次都帶 `mcp=`，不需要記住 |
+
+`sites.json` 的 origin 四態權限（`unauthorized`/`once`/`always`/`blocked`）**保留**，語意不變——見第 3 節。
+
+## codex 限制（TASK_1947 查證，codex-cli 0.153.4）
+
+- **自訂 header 支援**：codex 的 `mcp_servers.<name>` 設定支援 `env_http_headers`（header 名 → 環境變數名的對照表，值在啟動當下從環境變數讀取，同 `bearer_token_env_var` 的「值不落地在命令列/設定檔」設計）與 `http_headers`（header 名 → 字面值，直接寫死）兩種欄位——經 `codex debug models -c mcp_servers.<n>.url=... -c mcp_servers.<n>.bearer_token_env_var=... -c mcp_servers.<n>.env_http_headers={X-Kenaz-Session='<env var name>'}` 本機驗證可正常載入設定（exit 0，無錯誤）。Kenaz 因此對 codex 也送 `X-Kenaz-Session`，用 `env_http_headers` 而非 `http_headers`（維持與 bearer token 一致的「敏感/識別值只經環境變數傳遞」慣例，即使 launch_id 本身不是密鑰）。注意：`codex mcp add ... -c mcp_servers.<n>.http_headers=...`（該子指令自己的設定合併順序）會回傳 `invalid transport` 錯誤——這是 `codex mcp add` 這個子指令自己的限制，不代表 codex 整體不支援這個欄位；Kenaz 的 codex 分支走的是 `codex <prompt> -c ...` 直接呼叫，不經過 `codex mcp add`，已驗證可行。
+- **MCP 工具呼叫是否觸發審批**：codex 的 `-a/--ask-for-approval` 只列舉兩個值（`on-request` 模型自行決定何時詢問、`never` 完全不詢問），且其說明文字只提到「執行 model-generated shell 指令」——`codex mcp add --help` 也沒有任何「MCP 工具需要額外信任/審批」的旗標。查證範圍內（`--help`、`mcp add --help`、`mcp mcp --help`）沒有找到 codex 對 MCP 工具呼叫本身有獨立審批閘門的證據，也沒有找到能反面證實的方式（需要一次真的互動 session 才能實測，超出本任務 worktree 的驗證範圍——不能對正在跑的 live tauri dev 動任何東西，見本任務 worktree 規則）。**結論：未完全驗證，文件化為已知限制**——Kenaz 目前的 codex 直接呼叫（`build_interactive_script` 的 codex 分支）刻意不加 `-a never`：那會連同「shell 指令執行」的審批也一起關掉，影響範圍比「只想讓 MCP 工具別跳審批」大得多，不是這個任務該做的取捨。若之後有人在真的互動 session 裡觀察到 MCP 工具呼叫真的卡在審批提示，才是加這個旗標（或改用更窄的等效設定）的時機。
+- **annotations 分級不套用到 codex（TASK_1949 查證）**：codex `mcp_servers.<name>` 的設定欄位（`url`/`bearer_token_env_var`/`env_http_headers` 等，見上一點）裡沒有任何「只允許某些工具」或「依 tool annotations 分級」的等效設定；`codex mcp add --help`、`codex --help` 查證範圍內都沒有找到這類旗標。結論：codex 分支對 §2 point 6 的 `tools/list` annotations 完全不讀取、不探測——上一點記錄的「MCP 工具呼叫是否觸發審批」未完全驗證的結論同樣適用，codex 使用者的工具呼叫審批行為完全由 codex 自身決定，與這個任務新增的 claude-only 分級機制無關。
+
+## 5. 參考來源
+
+- `dev/specs/agent-connect/SDK_GUIDE.md`（TASK_1940，給網站開發者的接入指南——本檔的讀者導向版本）
+- `dev/KENAZ_AGENT_CONNECT_v1_SPEC.md`（v0.4，第 0、2.2、2.3、2.4、3 節是本檔的直接依據）
+- `history/PROTOCOL_v0.3_snapshot.md`（v0.3 凍結快照——WebSocket relay + 配對握手協定的完整內容）
+- `history/README.md`（Relay v1／FlowPix 更早的歷史來源）
+- 目前的 Rust 實作：`dashboard/src-tauri/src/features/agent_hub/deep_link.rs`（深連結解析）、`launch.rs`（執行）、`approval.rs`（審批卡）、`permissions.rs`（origin 四態）、`mod.rs`（串接三者）
+- 假 MCP（conformance/live-verification 用）：`dashboard/scripts/agent-hub-fake-mcp.mjs`