feat: add rule dispatch, cross-plugin API, and Docker integration test

Wire rule registry and authenticated callbacks into both client and server
runtimes; expose __yonexusClient / __yonexusServer on globalThis for
cross-plugin communication. Add Docker-based integration test with
server-test-plugin (test_ping echo) and client-test-plugin (test_pong
receiver), plus docker-compose setup. Fix transport race condition where
a stale _connections entry caused promoteToAuthenticated to silently fail.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,2 @@
+.idea/
+tests/docker/.env

ACCEPTANCE.md

@@ -0,0 +1,256 @@
+# Yonexus v1 验收与回归清单
+
+本清单服务于 `TASKLIST.md` 中的 YNX-1205。
+
+目标：给后续开发、联调、回归提供一份统一基线，避免只凭“能跑起来了”判断完成度。
+
+---
+
+## 1. 范围
+
+覆盖对象：
+
+- `Yonexus.Protocol`
+- `Yonexus.Server`
+- `Yonexus.Client`
+- Server ↔ Client 联调主流程
+- pairing / auth / heartbeat / rule dispatch 关键失败路径
+
+不覆盖：
+
+- 多服务器拓扑
+- 离线消息队列
+- 管理 UI
+- 复杂规则匹配
+
+---
+
+## 2. 协议层验收
+
+### 2.1 builtin 编解码
+
+必须验证：
+
+- `builtin::{json}` 能正确编码
+- `builtin::{json}` 能正确解码
+- malformed builtin 消息会返回标准错误
+- 未支持 builtin type 可被明确拒绝
+
+### 2.2 rule message 解析
+
+必须验证：
+
+- `${rule}::${content}` 可被正确解析
+- `${rule}::${sender}::${content}` 可被正确解析
+- `content` 中包含 `::` 时不会被错误拆分
+- `builtin` 不能作为普通 rule 注册
+
+### 2.3 共享认证约束
+
+必须验证：
+
+- nonce 长度固定为 24
+- timestamp 新鲜度窗口符合协议
+- 签名输入序列化规则固定且可复用
+
+---
+
+## 3. Server 单体验收
+
+### 3.1 启动与配置
+
+必须验证：
+
+- 缺失 `followerIdentifiers` 会 fail fast
+- 缺失 `notifyBotToken` / `adminUserId` / `listenPort` 会 fail fast
+- 非法 `listenPort` 会 fail fast
+- 启动时会加载持久化记录并补齐 allowlist 初始记录
+
+### 3.2 pairing
+
+必须验证：
+
+- 未配对 allowlisted client 进入 `pair_required`
+- server 创建 pending pairing 记录
+- pairing code 不通过 Yonexus WebSocket 下发
+- pairing 通知失败时返回 `admin_notification_failed`
+- 正确 pairing code 返回 `pair_success`
+- 错误 pairing code 返回 `invalid_code`
+- 过期 pairing code 返回 `expired`
+
+### 3.3 auth
+
+必须验证：
+
+- paired client 可通过合法签名拿到 `auth_success`
+- 非 allowlisted identifier 被拒绝
+- 未配对 identifier 不可通过 auth
+- public key 不匹配会失败
+- stale/future timestamp 会失败
+- nonce collision 会触发 `re_pair_required`
+- 超过 `>10 attempts / 10s` 会触发 `re_pair_required`
+
+### 3.4 liveness
+
+必须验证：
+
+- heartbeat 后更新 `lastHeartbeatAt`
+- 7 分钟无心跳转为 `unstable`
+- 11 分钟无心跳转为 `offline`
+- `offline` 时发送 `disconnect_notice` 并断开连接
+
+### 3.5 messaging
+
+必须验证：
+
+- 未认证 client 发送 rule message 会被拒绝
+- 已认证 client 的消息会被重写为 `${rule}::${sender}::${content}`
+- duplicate rule 注册默认失败
+- `sendMessageToClient()` 对离线 client 返回失败
+
+---
+
+## 4. Client 单体验收
+
+### 4.1 启动与本地状态
+
+必须验证：
+
+- 缺失 state 文件时可初始化最小状态
+- 首次启动会自动生成 Ed25519 keypair
+- 重启后不会重复生成 keypair
+- 已有 secret 时可进入 auth 流程
+
+### 4.2 连接与重连
+
+必须验证：
+
+- 可连接到可用的 server
+- server 不可用时会按退避策略重连
+- 手动断开不会误触发自动重连
+- 成功重连后退避计数会重置
+
+### 4.3 pairing / auth
+
+必须验证：
+
+- 收到 `pair_request` 后进入待确认状态
+- 可提交 pairing code
+- 收到 `pair_success` 后保存 secret
+- 收到 `hello_ack(auth_required)` 后自动发 `auth_request`
+- 收到 `auth_success` 后进入 authenticated
+- 收到 `re_pair_required` 后清理本地 secret 并回退到 `pair_required`
+
+### 4.4 heartbeat / dispatch
+
+必须验证：
+
+- authenticated 后启动 heartbeat loop
+- 断线或未认证时停止 heartbeat loop
+- `registerRule()` 拒绝 `builtin`
+- `sendMessageToServer()` 拒绝 `builtin::` 和非法格式
+
+---
+
+## 5. 联调验收
+
+### 5.1 首次配对闭环
+
+必须通过：
+
+1. Client 连接 Server
+2. Client 发送 `hello`
+3. Server 返回 `hello_ack(pair_required)`
+4. Server 创建 pairing request 并发出管理员通知
+5. Client 提交正确 pairing code
+6. Server 返回 `pair_success`
+7. Client 保存 secret
+8. Client 发送 `auth_request`
+9. Server 返回 `auth_success`
+10. Client 进入 authenticated 并开始 heartbeat
+
+### 5.2 正常重连闭环
+
+必须通过：
+
+1. 已配对 Client 重连
+2. `hello_ack(auth_required)`
+3. Client 发送合法 `auth_request`
+4. Server 返回 `auth_success`
+5. 心跳恢复正常
+
+### 5.3 规则消息闭环
+
+必须通过：
+
+1. Client 认证成功
+2. Client 调用 `sendRuleMessage()`
+3. Server 收到并完成 sender rewrite
+4. Server 规则处理器命中 exact match
+5. Server 调用 `sendRuleMessageToClient()` 回发消息
+6. Client 本地规则处理器收到消息
+
+---
+
+## 6. 失败路径回归矩阵
+
+每次关键改动后，至少回归以下场景：
+
+- pairing code 错误
+- pairing 过期
+- pairing 通知失败
+- unsupported protocol version
+- malformed builtin frame
+- unknown identifier
+- invalid signature
+- stale timestamp
+- future timestamp
+- nonce collision
+- handshake rate limit
+- duplicate active connection 竞争
+- 未认证连接发送 rule message
+
+---
+
+## 7. 自动化建议
+
+建议的最小自动化分层：
+
+- `Yonexus.Protocol`: 单元测试，锁定 codec / types / auth helpers
+- `Yonexus.Server`: 单元测试，覆盖 runtime + pairing/auth/liveness 核心逻辑
+- `Yonexus.Client`: 单元测试，覆盖 state/transport/runtime 主状态机
+- Server + Client: 集成测试，覆盖 happy path 与关键失败路径
+
+建议把通过条件固化为：
+
+- `Yonexus.Protocol` 类型检查 + 测试必须全绿
+- Server / Client 类型检查必须全绿
+- 新增联调测试后，happy path 与至少一组安全失败路径必须全绿
+
+推荐的 umbrella 仓库最小回归入口：
+
+```bash
+./scripts/validate-v1.sh
+```
+
+该脚本会顺序执行：
+- `Yonexus.Protocol`: `npm run check && npm run test`
+- `Yonexus.Server`: `npm run check && npm run test`
+- `Yonexus.Client`: `npm run check && npm run test`
+
+如果某个子仓库尚未安装依赖，脚本会优先自动执行：
+- 有 `package-lock.json` 时使用 `npm ci`
+- 否则回退到 `npm install`
+
+---
+
+## 8. 当前对应关系
+
+与 `TASKLIST.md` 对应关系：
+
+- YNX-1101：协议单元测试
+- YNX-1102：Server 单元测试
+- YNX-1103：Client 单元测试
+- YNX-1104：Server-Client 集成测试
+- YNX-1105：失败路径测试矩阵
+- YNX-1205：协议测试与验收清单（本文件）

DEPLOYMENT.md

@@ -0,0 +1,123 @@
+# Yonexus 部署指南 (v1)
+
+本指南面向 **单主多从** 拓扑：
+- **主节点**：运行 `Yonexus.Server`
+- **从节点**：运行 `Yonexus.Client`
+
+> 说明：Yonexus 采用三仓库/子模块结构（Umbrella + Server + Client + Protocol）。
+
+---
+
+## 1. 拓扑与前置条件
+
+- **主节点**需要可被从节点访问的稳定地址（域名或固定 IP）
+- **从节点**只需能 outbound 访问主节点 WebSocket
+- 需要一个 Discord Bot Token，用于向管理员 DM 配对码
+- 需要管理员的 Discord User ID
+
+---
+
+## 2. 仓库结构与同步
+
+在 umbrella 仓库内：
+
+```
+Yonexus/
+├── Yonexus.Server
+├── Yonexus.Client
+├── Yonexus.Protocol
+```
+
+确保子模块已更新：
+
+```bash
+git submodule update --init --recursive
+```
+
+---
+
+## 3. 主节点部署（Yonexus.Server）
+
+### 3.1 安装与构建
+
+```bash
+cd Yonexus.Server
+npm install
+npm run build
+```
+
+### 3.2 配置
+
+示例配置（OpenClaw 配置中）：
+
+```json
+{
+  "followerIdentifiers": ["client-a", "client-b"],
+  "notifyBotToken": "<discord-bot-token>",
+  "adminUserId": "123456789012345678",
+  "listenHost": "0.0.0.0",
+  "listenPort": 8787,
+  "publicWsUrl": "wss://example.com/yonexus"
+}
+```
+
+### 3.3 启动
+
+- 将 `Yonexus.Server` 安装为 OpenClaw 插件
+- 启动 OpenClaw Gateway 后，Server 会自动启动 WebSocket 服务
+
+---
+
+## 4. 从节点部署（Yonexus.Client）
+
+### 4.1 安装与构建
+
+```bash
+cd Yonexus.Client
+npm install
+npm run build
+```
+
+### 4.2 配置
+
+```json
+{
+  "mainHost": "wss://example.com/yonexus",
+  "identifier": "client-a",
+  "notifyBotToken": "<discord-bot-token>",
+  "adminUserId": "123456789012345678"
+}
+```
+
+### 4.3 启动
+
+- 将 `Yonexus.Client` 安装为 OpenClaw 插件
+- 启动 OpenClaw Gateway 后，Client 会自动连接 Server
+
+---
+
+## 5. 首次配对流程
+
+1. Client 连接后发送 `hello`
+2. Server 检测未配对，生成配对码
+3. Server 通过 Discord DM 将配对码发送给管理员
+4. 管理员将配对码转交给 Client 操作员
+5. Client 提交 `pair_confirm` 完成配对
+6. Server 返回 `pair_success` 并下发 `secret`
+7. Client 进入认证流程并开始心跳
+
+---
+
+## 6. 版本与兼容性
+
+- 协议版本：`1`
+- 需要确保 `Yonexus.Protocol` 子模块与 Server/Client 使用的协议一致
+
+---
+
+## 7. 快速验证建议
+
+- 主节点启动后确认 WebSocket 监听端口可达
+- 从节点能建立连接且收到 `hello_ack`
+- 配对完成后收到 `auth_success`
+- 5 分钟内可看到心跳日志/状态更新

FEAT.md

@@ -10,6 +10,33 @@ This repository now targets the split-plugin architecture only.
 
 ---
 
+## Shared Terminology and v1 Scope
+
+Canonical terms used across the project:
+- `identifier`: unique logical client name
+- `rule_identifier`: exact-match application route key
+- `builtin`: reserved protocol/system route namespace
+- `pairingCode`: short-lived out-of-band pairing code
+- `secret`: shared secret issued after pairing
+- `publicKey` / `privateKey`: client signing keypair
+
+Locked v1 decisions:
+- `heartbeat_ack` is optional
+- client reconnect uses exponential backoff
+- rule matching is exact-match only
+- offline sends fail immediately instead of queueing
+- `mainHost` is expected to be a full `ws://` or `wss://` URL
+
+Explicit v1 non-goals:
+- multi-server topology
+- direct client-to-client sockets
+- offline queueing guarantees
+- advanced rule matching
+- management UI
+- admin approval control plane beyond human relay of pairing codes
+
+---
+
 ## 1. Yonexus.Server Features
 
 ### 1.1 Server Runtime

OPERATIONS.md

@@ -0,0 +1,113 @@
+# Yonexus 运维与排障指南 (v1)
+
+本指南覆盖常见运行状态、错误码与恢复步骤。
+
+---
+
+## 1. 运行状态速览
+
+### Client 侧状态
+- `connecting`：正在连接
+- `pairing_required`：需要配对
+- `waiting_pair_confirm`：等待提交配对码
+- `authenticating`：认证中
+- `authenticated`：已认证，心跳中
+
+### Server 侧状态
+- `online`：已认证且心跳正常
+- `unstable`：7 分钟未收到心跳
+- `offline`：11 分钟未收到心跳，已断开连接
+
+---
+
+## 2. 常见问题与处理
+
+### 2.1 Client 无法连接 Server
+**可能原因**
+- `mainHost` 配置错误
+- Server 未启动或端口不可达
+
+**处理**
+- 检查 `mainHost` 是否为 `ws://` 或 `wss://`
+- 验证 Server 监听端口是否对外开放
+
+---
+
+### 2.2 Client 一直停在 `pairing_required`
+**可能原因**
+- Server 未能发送 Discord DM
+- `notifyBotToken` 或 `adminUserId` 配置错误
+
+**处理**
+- 检查 Server 日志是否出现 `admin_notification_failed`
+- 确认 Bot 有向目标用户发送 DM 的权限
+
+---
+
+### 2.3 配对码无效 / 过期
+**可能原因**
+- 输入错误
+- 配对码超过 TTL
+
+**处理**
+- 重新触发配对流程（断线后重连）
+- 确保管理员转发的配对码最新
+
+---
+
+### 2.4 认证失败 (`auth_failed`)
+**可能原因**
+- Secret 不匹配
+- 时间漂移过大
+- Nonce 重放或格式错误
+
+**处理**
+- 检查系统时间是否正确
+- 清除 Client 本地 secret，触发重新配对
+
+---
+
+### 2.5 频繁触发 `re_pair_required`
+**可能原因**
+- 非法重放或高频认证尝试
+- Client 有并发连接/重连异常
+
+**处理**
+- 确认同一 `identifier` 只存在一个活跃 Client
+- 检查 Client 是否重复启动多个实例
+
+---
+
+## 3. 错误码参考
+
+常见协议错误码：
+- `MALFORMED_MESSAGE`
+- `UNSUPPORTED_PROTOCOL_VERSION`
+- `IDENTIFIER_NOT_ALLOWED`
+- `PAIRING_REQUIRED`
+- `PAIRING_EXPIRED`
+- `ADMIN_NOTIFICATION_FAILED`
+- `AUTH_FAILED`
+- `NONCE_COLLISION`
+- `RATE_LIMITED`
+- `RE_PAIR_REQUIRED`
+
+---
+
+## 4. 恢复步骤建议
+
+**场景：Client 无法恢复认证**
+1. 停止 Client
+2. 删除本地 state 中的 secret
+3. 重启 Client 触发重新配对
+
+**场景：Server 端状态异常**
+1. 检查持久化 store 文件是否损坏
+2. 必要时备份后清理 store 文件（会导致所有 Client 重新配对）
+
+---
+
+## 5. 日志建议
+
+- Server 日志中应避免输出 secret / 配对码明文
+- 建议在生产环境开启结构化日志并保留最小必要字段

PLAN.md

@@ -124,6 +124,22 @@ Semantics:
 
 ---
 
+## 4.4 Shared Terminology Baseline
+
+These names are normative across umbrella docs, protocol docs, and implementation repos:
+
+- `identifier`: the unique logical name of a client/follower instance.
+- `rule_identifier`: the exact-match application route key.
+- `builtin`: reserved rule namespace for protocol/system frames.
+- `pairingCode`: short-lived out-of-band code delivered to the human admin.
+- `secret`: server-issued shared secret used for reconnect proof construction.
+- `publicKey` / `privateKey`: client-held signing keypair.
+- `nextAction`: server-directed next step returned by `hello_ack`.
+
+Implementations should avoid introducing alternative synonyms for these fields unless there is a versioned migration plan.
+
+---
+
 ## 5. Runtime Lifecycle
 
 ## 5.1 Yonexus.Server Startup
@@ -551,25 +567,39 @@ Not required in the first version unless explicitly added later:
 - direct client-to-client sockets
 - multi-server clustering
 - distributed consensus
+- offline message queues or guaranteed delivery to disconnected clients
+- advanced rule matching beyond exact string match
 - message ordering guarantees across reconnects
 - end-to-end payload encryption beyond the pairing/authentication requirements
 - management UI
+- admin-side approve/deny control plane beyond human relay of pairing codes
+- encryption-at-rest hardening beyond documenting current local storage limitations
 
 ---
 
-## 16. Open Questions To Confirm Later
+## 16. v1 Decisions Locked for Current Implementation
 
-1. Exact signing algorithm:
-   - Ed25519 is a strong default candidate
-2. Should `mainHost` accept only full WebSocket URLs or also raw `ip:port` strings?
-3. Is human code relay sufficient for v1 pairing, or should admin approve/deny controls be added later?
-4. On unsafe condition, should the old public key be retained or should the client generate a new keypair?
-5. Should offline clients support queued outbound messages from server, or should sends fail immediately?
-6. Are rule identifiers exact strings only, or should regex/prefix matching exist later?
+The following implementation-boundary decisions are now treated as settled for v1:
+
+1. Signing algorithm default: Ed25519.
+2. `mainHost` should be configured as a full `ws://` or `wss://` URL in v1.
+3. Human relay of the pairing code is sufficient for v1; richer admin approve/deny control can wait.
+4. `heartbeat_ack` remains optional.
+5. Client reconnect uses exponential backoff.
+6. Rule identifiers are exact-match strings only in v1.
+7. Outbound sends to offline clients fail immediately rather than queueing.
+
+## 17. Open Questions To Confirm Later
+
+1. On unsafe condition, should the old public key be retained or should the client generate a new keypair?
+2. Should future versions support explicit key rotation without full re-pairing?
+3. Should offline clients support queued outbound messages from server in a later version?
+4. Are richer admin approval workflows worth adding after v1 stabilizes?
+5. Should encryption-at-rest become a hard requirement in v2?
 
 ---
 
-## 17. Immediate Next Deliverables
+## 18. Immediate Next Deliverables
 
 After this plan, the next files to create should be:
 - `FEAT.md` — feature checklist derived from this plan

PROTOCOL.md

@@ -26,6 +26,22 @@ Important security rule:
 
 ---
 
+## 1.1 Canonical Terminology
+
+These names are treated as protocol-level canonical terms:
+
+- `identifier`: unique logical identity of a Yonexus client instance.
+- `rule_identifier`: exact-match routing key for application messages.
+- `builtin`: reserved protocol namespace used only for Yonexus control frames.
+- `pairingCode`: short-lived out-of-band code generated by the server for human-mediated pairing.
+- `secret`: server-issued shared secret used in reconnect authentication proof construction.
+- `publicKey` / `privateKey`: client signing keypair.
+- `nextAction`: the server's directed next step in `hello_ack`.
+
+The protocol and implementation repos should prefer these exact names over synonyms.
+
+---
+
 ## 2. Transport
 
 Transport is WebSocket.
@@ -35,13 +51,12 @@ Transport is WebSocket.
 - protocol frames are UTF-8 text in v1
 - binary frames are not required in v1
 
-Client connects to configured `mainHost`, which may be:
+Client connects to configured `mainHost`, which in v1 should be a full WebSocket URL:
 - `ws://host:port/path`
 - `wss://host:port/path`
-- or raw `host:port` if normalized by implementation
 
 Recommended canonical config:
-- prefer full WebSocket URL
+- require/prefer a full WebSocket URL in v1 rather than raw `host:port`
 
 ---
 
@@ -426,6 +441,9 @@ builtin::{
 ### `heartbeat_ack`
 Optional response by `Yonexus.Server`.
 
+v1 policy:
+- `heartbeat_ack` may be enabled by the server but clients must not require it for healthy operation
+
 Example:
 
 ```text
@@ -624,6 +642,9 @@ Dispatch algorithm:
 4. invoke the first exact match
 5. ignore/log if no match is found
 
+v1 policy:
+- rule matching is exact string match only; prefix, wildcard, and regex routing are out of scope
+
 Processor input:
 - on client: `${rule_identifier}::${message_content}`
 - on server for client-originated messages: `${rule_identifier}::${sender_identifier}::${message_content}`

README.md

@@ -154,12 +154,46 @@ Reserved rule: `builtin`
 
 ---
 
+## Shared Terminology
+
+To keep the umbrella repo, protocol repo, and both plugin repos aligned, Yonexus uses these terms consistently:
+
+- `identifier`: the stable logical name of a follower/client instance, unique within one Yonexus network.
+- `rule_identifier`: the exact-match application routing key used in `${rule_identifier}::${message_content}`.
+- `builtin`: the reserved rule namespace for Yonexus protocol/control messages only.
+- `pairingCode`: the short-lived out-of-band code generated by `Yonexus.Server` and delivered to a human admin by Discord DM.
+- `secret`: the server-issued shared secret established after successful pairing and used in reconnect authentication proof construction.
+- `publicKey` / `privateKey`: the client-owned signing keypair used for auth proof signing and verification.
+- `nextAction`: the server decision returned in `hello_ack`, currently one of `pair_required`, `waiting_pair_confirm`, `auth_required`, or `rejected`.
+
+## v1 Scope Boundaries
+
+In scope for v1:
+- WebSocket transport between one server and one or more clients
+- out-of-band pairing via Discord DM to a human administrator
+- signed reconnect authentication using `secret + nonce + timestamp`
+- heartbeat/liveness tracking (`online | unstable | offline`)
+- exact-match rule dispatch
+- lightweight persistence for trust/state material
+- optional `heartbeat_ack`
+- exponential reconnect backoff on the client side
+
+Explicitly out of scope for v1:
+- multi-server topology
+- direct client-to-client sockets
+- offline message queues / delivery guarantees
+- advanced rule matching (prefix/regex/wildcard)
+- management UI
+- distributed consensus / clustering
+- automatic admin approve/deny workflows beyond human relay of the pairing code
+- encryption-at-rest hardening beyond documenting local sensitive storage behavior
+
 ## Status
 
-- planning/specification stage
-- split-plugin architecture defined
-- protocol draft defined in `Yonexus.Protocol`
-- implementation not started yet
+- umbrella/specification repo is aligned with the split architecture
+- core implementation work is underway in `Yonexus.Server`, `Yonexus.Client`, and `Yonexus.Protocol`
+- protocol/types/codec/test scaffolding already exists in `Yonexus.Protocol`
+- runtime, transport, pairing, auth, heartbeat, rule dispatch, and test coverage are largely implemented in submodules; remaining work is focused on boundary cleanup and leftover failure-path coverage
 
 ---
 

scripts/validate-v1.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+run_step() {
+  local title="$1"
+  shift
+
+  echo
+  echo ">>> ${title}"
+  "$@"
+}
+
+ensure_node_modules() {
+  local dir="$1"
+
+  if [[ -d "$ROOT_DIR/$dir/node_modules" ]]; then
+    return 0
+  fi
+
+  local install_cmd="npm install"
+  if [[ -f "$ROOT_DIR/$dir/package-lock.json" ]]; then
+    install_cmd="npm ci"
+  fi
+
+  echo "Dependencies missing in $dir (node_modules not found). Bootstrapping with: ${install_cmd}"
+  run_step "${dir}: ${install_cmd}" bash -lc "cd '$ROOT_DIR/$dir' && ${install_cmd}"
+}
+
+run_npm_script() {
+  local dir="$1"
+  local script="$2"
+
+  ensure_node_modules "$dir"
+  run_step "${dir}: npm run ${script}" bash -lc "cd '$ROOT_DIR/$dir' && npm run ${script}"
+}
+
+run_npm_script "Yonexus.Protocol" check
+run_npm_script "Yonexus.Protocol" test
+run_npm_script "Yonexus.Server" check
+run_npm_script "Yonexus.Server" test
+run_npm_script "Yonexus.Client" check
+run_npm_script "Yonexus.Client" test
+
+echo
+printf 'Yonexus v1 validation passed.\n'

tests/docker/client-test-plugin/index.mjs

@@ -0,0 +1,33 @@
+// Singleton guard — openclaw calls register() twice per process
+let _registered = false;
+
+export default function register(_api) {
+  if (_registered) return;
+  _registered = true;
+
+  const client = globalThis.__yonexusClient;
+  if (!client) {
+    console.error('[client-test] __yonexusClient not on globalThis — ensure Yonexus.Client loads first');
+    return;
+  }
+
+  console.log('[client-test] __yonexusClient available, keys:', Object.keys(client));
+
+  // Register test_pong rule
+  // Received format (plain rule message from server): test_pong::<content>
+  client.ruleRegistry.registerRule('test_pong', (raw) => {
+    const sep = raw.indexOf('::');
+    const content = raw.slice(sep + 2);
+    console.log(`[client-test] MATCH  test_pong  content="${content}"`);
+  });
+
+  // When authenticated, send one matching and one non-matching rule message to server
+  client.onAuthenticated.push(() => {
+    console.log('[client-test] Authenticated — sending test_ping + other_rule to server');
+    const s1 = client.sendRule('test_ping', 'hello-from-client');
+    const s2 = client.sendRule('other_rule', 'other-from-client');
+    console.log(`[client-test] sendRule results: test_ping=${s1} other_rule=${s2}`);
+  });
+
+  console.log('[client-test] registered test_pong rule and onAuthenticated callback');
+}

tests/docker/client-test-plugin/openclaw.plugin.json

@@ -0,0 +1,13 @@
+{
+  "id": "yonexus-client-test",
+  "name": "Yonexus Client Test Plugin",
+  "version": "0.1.0",
+  "description": "Test plugin for Yonexus.Client rule routing",
+  "entry": "./index.mjs",
+  "permissions": [],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

tests/docker/client/Dockerfile

@@ -0,0 +1,37 @@
+# Build context: repo root (Yonexus/)
+# ── Stage 1: compile ──────────────────────────────────────────────────────────
+FROM node:22-alpine AS builder
+
+WORKDIR /build
+
+# Client imports Yonexus.Protocol only
+COPY Yonexus.Protocol/src                    ./Yonexus.Protocol/src
+
+COPY Yonexus.Client/package.json             ./Yonexus.Client/
+COPY Yonexus.Client/package-lock.json        ./Yonexus.Client/
+COPY Yonexus.Client/tsconfig.json            ./Yonexus.Client/
+COPY Yonexus.Client/plugin                   ./Yonexus.Client/plugin
+
+WORKDIR /build/Yonexus.Client
+RUN npm ci
+RUN npm run build
+
+# ── Stage 2: runtime ─────────────────────────────────────────────────────────
+FROM node:22-alpine AS runtime
+
+RUN npm install -g openclaw@2026.4.9
+
+WORKDIR /app
+
+# Layout expected by install.mjs: repoRoot = /app, sourceDist = /app/dist
+COPY --from=builder /build/Yonexus.Client/dist         ./dist
+COPY --from=builder /build/Yonexus.Client/node_modules ./node_modules
+COPY Yonexus.Client/package.json               ./package.json
+COPY Yonexus.Client/plugin/openclaw.plugin.json ./plugin/openclaw.plugin.json
+COPY Yonexus.Client/scripts/install.mjs        ./scripts/install.mjs
+
+COPY tests/docker/client-test-plugin /app/client-test-plugin
+COPY tests/docker/client/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]

tests/docker/client/entrypoint.sh

@@ -0,0 +1,69 @@
+#!/bin/sh
+set -e
+
+: "${IDENTIFIER:?IDENTIFIER is required}"
+: "${NOTIFY_BOT_TOKEN:?NOTIFY_BOT_TOKEN is required}"
+: "${ADMIN_USER_ID:?ADMIN_USER_ID is required}"
+: "${YONEXUS_SERVER_URL:?YONEXUS_SERVER_URL is required}"
+
+STATE_DIR=/app/.openclaw-state
+PLUGIN_DIR="$STATE_DIR/plugins/Yonexus.Client"
+TEST_PLUGIN_DIR="$STATE_DIR/plugins/yonexus-client-test"
+
+# Install plugin dist + manifest into isolated state directory
+node /app/scripts/install.mjs --install --openclaw-profile-path "$STATE_DIR"
+# Symlink node_modules so bare-module imports (e.g. ws) resolve from plugin dir
+ln -sf /app/node_modules "$PLUGIN_DIR/node_modules"
+
+# Install test plugin (plain .mjs, no compilation needed)
+mkdir -p "$TEST_PLUGIN_DIR"
+cp /app/client-test-plugin/index.mjs "$TEST_PLUGIN_DIR/"
+cp /app/client-test-plugin/openclaw.plugin.json "$TEST_PLUGIN_DIR/"
+
+# Write openclaw config — plugin id is "yonexus-client" per openclaw.plugin.json
+mkdir -p "$STATE_DIR"
+cat > "$STATE_DIR/openclaw.json" << EOF
+{
+  "meta": { "lastTouchedVersion": "2026.4.9" },
+  "gateway": { "bind": "loopback" },
+  "agents": { "defaults": { "workspace": "$STATE_DIR/workspace" } },
+  "plugins": {
+    "allow": ["yonexus-client", "yonexus-client-test"],
+    "load": { "paths": ["$PLUGIN_DIR", "$TEST_PLUGIN_DIR"] },
+    "installs": {
+      "yonexus-client": {
+        "source": "path",
+        "sourcePath": "$PLUGIN_DIR",
+        "installPath": "$PLUGIN_DIR",
+        "version": "0.1.0",
+        "installedAt": "2026-04-10T00:00:00.000Z"
+      },
+      "yonexus-client-test": {
+        "source": "path",
+        "sourcePath": "$TEST_PLUGIN_DIR",
+        "installPath": "$TEST_PLUGIN_DIR",
+        "version": "0.1.0",
+        "installedAt": "2026-04-10T00:00:00.000Z"
+      }
+    },
+    "entries": {
+      "yonexus-client": {
+        "enabled": true,
+        "config": {
+          "mainHost": "$YONEXUS_SERVER_URL",
+          "identifier": "$IDENTIFIER",
+          "notifyBotToken": "$NOTIFY_BOT_TOKEN",
+          "adminUserId": "$ADMIN_USER_ID"
+        }
+      },
+      "yonexus-client-test": {
+        "enabled": true,
+        "config": {}
+      }
+    }
+  }
+}
+EOF
+
+export OPENCLAW_STATE_DIR="$STATE_DIR"
+exec openclaw gateway run --allow-unconfigured

tests/docker/docker-compose.yml

@@ -0,0 +1,46 @@
+services:
+  yonexus-server:
+    build:
+      context: ../..
+      dockerfile: tests/docker/server/Dockerfile
+    environment:
+      # Identifier the client will use — must match IDENTIFIER on the client side
+      CLIENT_IDENTIFIER: test-client
+      # Required: Discord bot token and admin user ID for pairing notifications
+      NOTIFY_BOT_TOKEN: ${NOTIFY_BOT_TOKEN}
+      ADMIN_USER_ID: ${ADMIN_USER_ID}
+      # Optional: override the publicWsUrl advertised to clients
+      # PUBLIC_WS_URL: ws://yonexus-server:8787
+    networks:
+      - yonexus-net
+    healthcheck:
+      # Wait until the Yonexus WebSocket port is accepting connections
+      test:
+        - CMD
+        - node
+        - -e
+        - "require('net').createConnection({port:8787,host:'127.0.0.1'}).on('connect',()=>process.exit(0)).on('error',()=>process.exit(1))"
+      interval: 5s
+      timeout: 3s
+      retries: 12
+      start_period: 15s
+
+  yonexus-client:
+    build:
+      context: ../..
+      dockerfile: tests/docker/client/Dockerfile
+    environment:
+      # Must match CLIENT_IDENTIFIER on the server side
+      IDENTIFIER: test-client
+      NOTIFY_BOT_TOKEN: ${NOTIFY_BOT_TOKEN}
+      ADMIN_USER_ID: ${ADMIN_USER_ID}
+      YONEXUS_SERVER_URL: ws://yonexus-server:8787
+    networks:
+      - yonexus-net
+    depends_on:
+      yonexus-server:
+        condition: service_healthy
+
+networks:
+  yonexus-net:
+    driver: bridge

tests/docker/server-test-plugin/index.mjs

@@ -0,0 +1,39 @@
+// Singleton guard — openclaw calls register() twice per process
+let _registered = false;
+
+export default function register(_api) {
+  if (_registered) return;
+  _registered = true;
+
+  const server = globalThis.__yonexusServer;
+  if (!server) {
+    console.error('[server-test] __yonexusServer not on globalThis — ensure Yonexus.Server loads first');
+    return;
+  }
+
+  console.log('[server-test] __yonexusServer available, keys:', Object.keys(server));
+
+  // Register test_ping rule
+  // Received format (rewritten by server): test_ping::<senderIdentifier>::<content>
+  server.ruleRegistry.registerRule('test_ping', (raw) => {
+    const firstSep = raw.indexOf('::');
+    const rest = raw.slice(firstSep + 2);
+    const secondSep = rest.indexOf('::');
+    const sender = rest.slice(0, secondSep);
+    const content = rest.slice(secondSep + 2);
+    console.log(`[server-test] MATCH  test_ping  from="${sender}"  content="${content}"`);
+    // Echo back to sender via test_pong
+    const sent = server.sendRule(sender, 'test_pong', `echo-${content}`);
+    console.log(`[server-test] echo sent=${sent}`);
+  });
+
+  // When a client authenticates, send one matching and one non-matching rule message
+  server.onClientAuthenticated.push((identifier) => {
+    console.log(`[server-test] Client "${identifier}" authenticated — sending test_pong + other_rule`);
+    const s1 = server.sendRule(identifier, 'test_pong', 'welcome-from-server');
+    const s2 = server.sendRule(identifier, 'other_rule', 'other-from-server');
+    console.log(`[server-test] sendRule results: test_pong=${s1} other_rule=${s2}`);
+  });
+
+  console.log('[server-test] registered test_ping rule and onClientAuthenticated callback');
+}

tests/docker/server-test-plugin/openclaw.plugin.json

@@ -0,0 +1,13 @@
+{
+  "id": "yonexus-server-test",
+  "name": "Yonexus Server Test Plugin",
+  "version": "0.1.0",
+  "description": "Test plugin for Yonexus.Server rule routing",
+  "entry": "./index.mjs",
+  "permissions": [],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

tests/docker/server/Dockerfile

@@ -0,0 +1,40 @@
+# Build context: repo root (Yonexus/)
+# ── Stage 1: compile ──────────────────────────────────────────────────────────
+FROM node:22-alpine AS builder
+
+WORKDIR /build
+
+# Server imports Yonexus.Protocol and Yonexus.Client/crypto — all needed for tsc
+COPY Yonexus.Protocol/src                    ./Yonexus.Protocol/src
+COPY Yonexus.Client/plugin/crypto            ./Yonexus.Client/plugin/crypto
+
+COPY Yonexus.Server/package.json             ./Yonexus.Server/
+COPY Yonexus.Server/package-lock.json        ./Yonexus.Server/
+COPY Yonexus.Server/tsconfig.json            ./Yonexus.Server/
+COPY Yonexus.Server/plugin                   ./Yonexus.Server/plugin
+
+WORKDIR /build/Yonexus.Server
+RUN npm ci
+RUN npm run build
+
+# ── Stage 2: runtime ─────────────────────────────────────────────────────────
+FROM node:22-alpine AS runtime
+
+RUN npm install -g openclaw@2026.4.9
+
+WORKDIR /app
+
+# Layout expected by install.mjs: repoRoot = /app, sourceDist = /app/dist
+COPY --from=builder /build/Yonexus.Server/dist         ./dist
+COPY --from=builder /build/Yonexus.Server/node_modules ./node_modules
+COPY Yonexus.Server/package.json               ./package.json
+COPY Yonexus.Server/plugin/openclaw.plugin.json ./plugin/openclaw.plugin.json
+COPY Yonexus.Server/scripts/install.mjs        ./scripts/install.mjs
+
+COPY tests/docker/server-test-plugin /app/server-test-plugin
+COPY tests/docker/server/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+EXPOSE 8787
+
+ENTRYPOINT ["/entrypoint.sh"]

tests/docker/server/entrypoint.sh

@@ -0,0 +1,71 @@
+#!/bin/sh
+set -e
+
+: "${CLIENT_IDENTIFIER:?CLIENT_IDENTIFIER is required}"
+: "${NOTIFY_BOT_TOKEN:?NOTIFY_BOT_TOKEN is required}"
+: "${ADMIN_USER_ID:?ADMIN_USER_ID is required}"
+
+STATE_DIR=/app/.openclaw-state
+PLUGIN_DIR="$STATE_DIR/plugins/Yonexus.Server"
+TEST_PLUGIN_DIR="$STATE_DIR/plugins/yonexus-server-test"
+SERVER_WS_URL="${PUBLIC_WS_URL:-ws://yonexus-server:8787}"
+
+# Install plugin dist + manifest into isolated state directory
+node /app/scripts/install.mjs --install --openclaw-profile-path "$STATE_DIR"
+# Symlink node_modules so bare-module imports (e.g. ws) resolve from plugin dir
+ln -sf /app/node_modules "$PLUGIN_DIR/node_modules"
+
+# Install test plugin (plain .mjs, no compilation needed)
+mkdir -p "$TEST_PLUGIN_DIR"
+cp /app/server-test-plugin/index.mjs "$TEST_PLUGIN_DIR/"
+cp /app/server-test-plugin/openclaw.plugin.json "$TEST_PLUGIN_DIR/"
+
+# Write openclaw config — plugin id is "yonexus-server" per openclaw.plugin.json
+mkdir -p "$STATE_DIR"
+cat > "$STATE_DIR/openclaw.json" << EOF
+{
+  "meta": { "lastTouchedVersion": "2026.4.9" },
+  "gateway": { "bind": "loopback" },
+  "agents": { "defaults": { "workspace": "$STATE_DIR/workspace" } },
+  "plugins": {
+    "allow": ["yonexus-server", "yonexus-server-test"],
+    "load": { "paths": ["$PLUGIN_DIR", "$TEST_PLUGIN_DIR"] },
+    "installs": {
+      "yonexus-server": {
+        "source": "path",
+        "sourcePath": "$PLUGIN_DIR",
+        "installPath": "$PLUGIN_DIR",
+        "version": "0.1.0",
+        "installedAt": "2026-04-10T00:00:00.000Z"
+      },
+      "yonexus-server-test": {
+        "source": "path",
+        "sourcePath": "$TEST_PLUGIN_DIR",
+        "installPath": "$TEST_PLUGIN_DIR",
+        "version": "0.1.0",
+        "installedAt": "2026-04-10T00:00:00.000Z"
+      }
+    },
+    "entries": {
+      "yonexus-server": {
+        "enabled": true,
+        "config": {
+          "followerIdentifiers": ["$CLIENT_IDENTIFIER"],
+          "notifyBotToken": "$NOTIFY_BOT_TOKEN",
+          "adminUserId": "$ADMIN_USER_ID",
+          "listenHost": "0.0.0.0",
+          "listenPort": 8787,
+          "publicWsUrl": "$SERVER_WS_URL"
+        }
+      },
+      "yonexus-server-test": {
+        "enabled": true,
+        "config": {}
+      }
+    }
+  }
+}
+EOF
+
+export OPENCLAW_STATE_DIR="$STATE_DIR"
+exec openclaw gateway run --allow-unconfigured

tests/failure-path/MATRIX.md

@@ -0,0 +1,167 @@
+# Yonexus Failure Path Test Matrix
+
+This document defines the systematic test coverage for pairing and authentication failure scenarios.
+
+## Test Matrix Legend
+
+- ✅ = Test implemented
+- 🔄 = Test stub exists, needs implementation
+- ⬜ = Not yet implemented
+- ⏸ = Deferred / intentionally out of v1 scope
+- 🔴 = Critical path, high priority
+
+---
+
+## 1. Pairing Failure Paths
+
+| ID | Scenario | Trigger | Expected Behavior | Status |
+|----|----------|---------|-------------------|--------|
+| PF-01 | Invalid pairing code | Client submits wrong code | `pair_failed(invalid_code)`, allow retry | ✅ |
+| PF-02 | Expired pairing code | Client submits after expiry | `pair_failed(expired)`, reset to `pair_required` | ✅ |
+| PF-03 | Identifier not in allowlist | Unknown client tries to pair | `pair_failed(identifier_not_allowed)`, close connection | ✅ |
+| PF-04 | Admin notification failed | Discord DM fails to send | `pair_failed(admin_notification_failed)`, abort pairing | ✅ |
+| PF-05 | Empty pairing code | Client submits empty string | `pair_failed(invalid_code)` | ✅ |
+| PF-06 | Malformed pair_confirm payload | Missing required fields | Protocol error, no state change | ✅ |
+| PF-07 | Double pairing attempt | Client calls pair_confirm twice | Second attempt rejected if already paired | ✅ |
+| PF-08 | Pairing during active session | Paired client tries to pair again | Reject, maintain existing trust | ✅ |
+| PF-09 | Server restart during pairing | Server restarts before confirm | Pairing state preserved, code still valid | ✅ |
+| PF-10 | Client restart during pairing | Client restarts before submit | Client must restart pairing flow | ✅ |
+
+---
+
+## 2. Authentication Failure Paths
+
+| ID | Scenario | Trigger | Expected Behavior | Status |
+|----|----------|---------|-------------------|--------|
+| AF-01 | Unknown identifier | Auth from unpaired client | `auth_failed(unknown_identifier)` | ✅ |
+| AF-02 | Not paired | Auth before pairing complete | `auth_failed(not_paired)` | ✅ |
+| AF-03 | Invalid signature | Wrong private key used | `auth_failed(invalid_signature)` | ✅ |
+| AF-04 | Wrong secret | Client has outdated secret | 当前实现将其并入 `auth_failed(invalid_signature)`；`invalid_secret` 语义保留待后续确认 | ⏸ |
+| AF-05 | Stale timestamp | Proof timestamp >10s old | `auth_failed(stale_timestamp)` | ✅ |
+| AF-06 | Future timestamp | Proof timestamp in future | `auth_failed(future_timestamp)` | ✅ |
+| AF-07 | Nonce collision | Reused nonce within window | `auth_failed(nonce_collision)` → `re_pair_required` 🔴 | ✅ |
+| AF-08 | Rate limited | >10 attempts in 10s | `auth_failed(rate_limited)` → `re_pair_required` 🔴 | ✅ |
+| AF-09 | Wrong public key | Key doesn't match stored | `auth_failed(invalid_signature)` | ✅ |
+| AF-10 | Malformed auth_request | Missing required fields | Protocol error | ✅ |
+| AF-11 | Tampered proof | Modified signature | `auth_failed(invalid_signature)` | ✅ |
+
+---
+
+## 3. Re-pairing Triggers
+
+| ID | Scenario | Cause | Server Action | Client Action | Status |
+|----|----------|-------|---------------|---------------|--------|
+| RP-01 | Nonce collision | Replay attack detected | Clear secret, reset state | Enter `pair_required` | ✅ |
+| RP-02 | Rate limit exceeded | Brute force detected | Clear secret, reset state | Enter `pair_required` | ✅ |
+| RP-03 | Admin-initiated | Manual revocation | Mark revoked, notify | Enter `pair_required` | ⏸ |
+| RP-04 | Key rotation | Client sends new public key | Update key, keep secret | Continue with new key | ⏸ |
+
+---
+
+## 4. Connection Failure Paths
+
+| ID | Scenario | Trigger | Expected Behavior | Status |
+|----|----------|---------|-------------------|--------|
+| CF-01 | Network partition | Connection drops mid-auth | Client retries with backoff | ✅ |
+| CF-02 | Server unreachable | Initial connect fails | Exponential backoff retry | ✅ |
+| CF-03 | Duplicate connection | Same ID connects twice | Old connection closed, new accepted | ✅ |
+| CF-04 | Protocol version mismatch | Unsupported version | Connection rejected with error | ✅ |
+| CF-05 | Malformed hello | Invalid payload / missing required hello fields | Error response, connection maintained | ✅ |
+| CF-06 | Unauthenticated rule message | Client sends before auth | Connection closed | ✅ |
+| CF-07 | Reserved rule registration | Plugin tries `registerRule("builtin")` | Registration rejected | ✅ |
+
+---
+
+## 5. Heartbeat Failure Paths
+
+| ID | Scenario | Trigger | Expected Behavior | Status |
+|----|----------|---------|-------------------|--------|
+| HF-01 | 7-minute timeout | No heartbeat received | Status → `unstable`, notify | ✅ |
+| HF-02 | 11-minute timeout | Still no heartbeat | Status → `offline`, disconnect | ✅ |
+| HF-03 | Early heartbeat | Heartbeat before auth | Rejected/ignored | ✅ |
+| HF-04 | Heartbeat from unauthenticated | Wrong state | Error, possible disconnect | ✅ |
+
+---
+
+## 6. State Recovery Scenarios
+
+| ID | Scenario | Condition | Expected Recovery | Status |
+|----|----------|-----------|-------------------|--------|
+| SR-01 | Server restart with pending pairing | Pairing in progress | Preserve pairing state, code valid | ✅ |
+| SR-02 | Server restart with active sessions | Online clients | All marked offline, reconnect required | ✅ |
+| SR-03 | Client restart with credentials | Has secret + keys | Resume with auth, no re-pairing | ✅ |
+| SR-04 | Client restart without credentials | First run | Full pairing flow required | ✅ |
+| SR-05 | Corrupted server store | File unreadable | Surface corruption error clearly for operator handling | ✅ |
+| SR-06 | Corrupted client state | File unreadable | Surface corruption error clearly for operator handling | ✅ |
+
+---
+
+## Implementation Priority
+
+### Phase 1: Critical Security Paths (🔴)
+1. AF-07 Nonce collision → re-pairing
+2. AF-08 Rate limiting → re-pairing
+3. PF-04 Admin notification failure
+4. CF-06 Unauthenticated message handling
+
+### Phase 2: Core Functionality
+5. PF-01/02 Invalid/expired pairing codes
+6. AF-03/04 Signature and secret validation
+7. AF-05/06 Timestamp validation
+8. HF-01/02 Heartbeat timeout handling
+
+### Phase 3: Edge Cases
+9. All connection failure paths
+10. State recovery scenarios
+11. Double-attempt scenarios
+
+---
+
+## Test Implementation Notes
+
+### Running the Matrix
+
+```bash
+# Run specific failure path category
+npm test -- pairing-failures
+npm test -- auth-failures
+npm test -- connection-failures
+
+# Run all failure path tests
+npm test -- failure-paths
+```
+
+### Current Notes
+
+- AF-04 (`invalid_secret`) 目前明确按 v1 语义并入 `invalid_signature`，不再单独视为未完成缺口；若后续要保留独立错误码，需要先同步更新协议与实现。
+- RP-03（管理员主动撤销）与 RP-04（key rotation）继续作为 v2+ 议题保留，不阻塞当前 v1 交付判断。
+- 本轮已补齐 AF-01/02/03/05/06/09/10/11、RP-01/02、CF-01/02/03/04/05/07、HF-01/02、PF-08/09/10、SR-01/02/03/04/05/06。
+
+### Umbrella Validation Entry Point
+
+在 umbrella 仓库根目录可运行：
+
+```bash
+./scripts/validate-v1.sh
+```
+
+它会顺序执行：
+- `Yonexus.Protocol` 测试
+- `Yonexus.Server` 类型检查 + 测试
+- `Yonexus.Client` 类型检查 + 测试
+
+### Adding New Test Cases
+
+1. Add row to appropriate table above
+2. Assign unique ID (PF-, AF-, RP-, CF-, HF-, SR- prefix)
+3. Update status when implementing
+4. Link to test file location
+
+---
+
+## Cross-References
+
+- Protocol spec: `../PROTOCOL.md`
+- Acceptance criteria: `../ACCEPTANCE.md`
+- Server tests: `../Yonexus.Server/tests/`
+- Client tests: `../Yonexus.Client/tests/`

tests/failure-path/pairing-failures.test.ts

@@ -0,0 +1,666 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import {
+  decodeBuiltin,
+  encodeBuiltin,
+  buildHello,
+  buildHelloAck,
+  buildPairRequest,
+  buildPairConfirm,
+  buildPairFailed,
+  buildPairSuccess,
+  type PairConfirmPayload,
+  type PairFailedPayload,
+  YONEXUS_PROTOCOL_VERSION,
+  ProtocolErrorCode
+} from "../../Yonexus.Protocol/src/index.js";
+import { createYonexusServerRuntime } from "../../Yonexus.Server/plugin/core/runtime.js";
+import type { ClientRecord } from "../../Yonexus.Server/plugin/core/persistence.js";
+import type { YonexusServerStore } from "../../Yonexus.Server/plugin/core/store.js";
+import type { ClientConnection, ServerTransport } from "../../Yonexus.Server/plugin/core/transport.js";
+
+/**
+ * YNX-1105b: Pairing Failure Path Tests
+ *
+ * Covers:
+ * - PF-01: Invalid pairing code
+ * - PF-02: Expired pairing code
+ * - PF-03: Identifier not in allowlist
+ * - PF-04: Admin notification failed (partial - notification stub)
+ * - PF-05: Empty pairing code
+ * - PF-06: Malformed pair_confirm payload
+ * - PF-07: Double pairing attempt
+ */
+
+// ============================================================================
+// Test Utilities
+// ============================================================================
+
+function createMockSocket() {
+  return { close: vi.fn() } as unknown as ClientConnection["ws"];
+}
+
+function createConnection(identifier: string | null = null): ClientConnection {
+  return {
+    identifier,
+    ws: createMockSocket(),
+    connectedAt: 1_710_000_000,
+    isAuthenticated: false
+  };
+}
+
+function createMockStore(initialClients: ClientRecord[] = []): YonexusServerStore {
+  const persisted = new Map(initialClients.map((r) => [r.identifier, r]));
+  return {
+    filePath: "/tmp/test.json",
+    load: vi.fn(async () => ({
+      version: 1,
+      persistedAt: 1_710_000_000,
+      clients: new Map(persisted)
+    })),
+    save: vi.fn(async (clients: Iterable<ClientRecord>) => {
+      persisted.clear();
+      for (const c of clients) persisted.set(c.identifier, c);
+    })
+  };
+}
+
+function createMockTransport() {
+  const sent: Array<{ connection: ClientConnection; message: string }> = [];
+  const closed: Array<{ identifier: string; code?: number; reason?: string }> = [];
+
+  const transport: ServerTransport = {
+    isRunning: false,
+    connections: new Map(),
+    start: vi.fn(),
+    stop: vi.fn(),
+    send: vi.fn((id: string, msg: string) => { sent.push({ connection: { identifier: id } as ClientConnection, message: msg }); return true; }),
+    sendToConnection: vi.fn((conn: ClientConnection, msg: string) => { sent.push({ connection: conn, message: msg }); return true; }),
+    broadcast: vi.fn(),
+    closeConnection: vi.fn((id: string, code?: number, reason?: string) => { closed.push({ identifier: id, code, reason }); return true; }),
+    promoteToAuthenticated: vi.fn(),
+    removeTempConnection: vi.fn(),
+    assignIdentifierToTemp: vi.fn()
+  };
+
+  return { transport, sent, closed };
+}
+
+// ============================================================================
+// Pairing Failure Path Tests
+// ============================================================================
+
+describe("YNX-1105b: Pairing Failure Paths", () => {
+  let now = 1_710_000_000;
+
+  beforeEach(() => {
+    now = 1_710_000_000;
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe("PF-01: Invalid pairing code", () => {
+    it("returns pair_failed(invalid_code) when wrong code submitted", async () => {
+      const store = createMockStore();
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["client-a"],
+          notifyBotToken: "test-token",
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      // Start pairing flow
+      const conn = createConnection();
+      await runtime.handleMessage(conn, encodeBuiltin(buildHello(
+        { identifier: "client-a", hasSecret: false, hasKeyPair: true, protocolVersion: YONEXUS_PROTOCOL_VERSION },
+        { timestamp: now }
+      )));
+
+      const pairingCode = runtime.state.registry.clients.get("client-a")?.pairingCode;
+      expect(pairingCode).toBeDefined();
+
+      // Submit wrong code
+      await runtime.handleMessage(conn, encodeBuiltin(buildPairConfirm(
+        { identifier: "client-a", pairingCode: "WRONG-CODE-999" },
+        { timestamp: now + 10 }
+      )));
+
+      const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+      expect(lastMessage.type).toBe("pair_failed");
+      expect((lastMessage.payload as PairFailedPayload).reason).toBe("invalid_code");
+
+      // Client remains in pending state, can retry
+      expect(runtime.state.registry.clients.get("client-a")?.pairingStatus).toBe("pending");
+    });
+
+    it("allows retry after invalid code failure", async () => {
+      const store = createMockStore();
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["client-a"],
+          notifyBotToken: "test-token",
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      const conn = createConnection();
+      await runtime.handleMessage(conn, encodeBuiltin(buildHello(
+        { identifier: "client-a", hasSecret: false, hasKeyPair: true, protocolVersion: YONEXUS_PROTOCOL_VERSION },
+        { timestamp: now }
+      )));
+
+      const correctCode = runtime.state.registry.clients.get("client-a")?.pairingCode;
+
+      // First attempt: wrong code
+      await runtime.handleMessage(conn, encodeBuiltin(buildPairConfirm(
+        { identifier: "client-a", pairingCode: "WRONG" },
+        { timestamp: now + 10 }
+      )));
+      expect(decodeBuiltin(sent.at(-1)!.message).type).toBe("pair_failed");
+
+      // Second attempt: correct code
+      await runtime.handleMessage(conn, encodeBuiltin(buildPairConfirm(
+        { identifier: "client-a", pairingCode: correctCode! },
+        { timestamp: now + 20 }
+      )));
+      expect(decodeBuiltin(sent.at(-1)!.message).type).toBe("pair_success");
+    });
+  });
+
+  describe("PF-02: Expired pairing code", () => {
+    it("returns pair_failed(expired) when code submitted after expiry", async () => {
+      const store = createMockStore();
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["client-a"],
+          notifyBotToken: "test-token",
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      const conn = createConnection();
+      await runtime.handleMessage(conn, encodeBuiltin(buildHello(
+        { identifier: "client-a", hasSecret: false, hasKeyPair: true, protocolVersion: YONEXUS_PROTOCOL_VERSION },
+        { timestamp: now }
+      )));
+
+      const pairingCode = runtime.state.registry.clients.get("client-a")?.pairingCode;
+      const expiresAt = runtime.state.registry.clients.get("client-a")?.pairingExpiresAt;
+      expect(expiresAt).toBeDefined();
+
+      // Advance time past expiry
+      now = expiresAt! + 1;
+
+      await runtime.handleMessage(conn, encodeBuiltin(buildPairConfirm(
+        { identifier: "client-a", pairingCode: pairingCode! },
+        { timestamp: now }
+      )));
+
+      const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+      expect(lastMessage.type).toBe("pair_failed");
+      expect((lastMessage.payload as PairFailedPayload).reason).toBe("expired");
+
+      // Pairing state reset to allow new pairing
+      expect(runtime.state.registry.clients.get("client-a")?.pairingStatus).toBe("unpaired");
+      expect(runtime.state.registry.clients.get("client-a")?.pairingCode).toBeUndefined();
+    });
+  });
+
+  describe("PF-03: Identifier not in allowlist", () => {
+    it("rejects hello from unknown identifier", async () => {
+      const store = createMockStore();
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["allowed-client"], // Only this one is allowed
+          notifyBotToken: "test-token",
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      const conn = createConnection();
+      await runtime.handleMessage(conn, encodeBuiltin(buildHello(
+        { identifier: "unknown-client", hasSecret: false, hasKeyPair: true, protocolVersion: YONEXUS_PROTOCOL_VERSION },
+        { timestamp: now }
+      )));
+
+      // Should receive hello_ack with rejected or an error
+      const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+      expect(lastMessage.type).toBe("error");
+      // Identifier should not be registered
+      expect(runtime.state.registry.clients.has("unknown-client")).toBe(false);
+    });
+
+    it("rejects pair_confirm from unknown identifier even if somehow received", async () => {
+      const store = createMockStore();
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["allowed-client"],
+          notifyBotToken: "test-token",
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      // Try to send pair_confirm for unknown client
+      const conn = createConnection();
+      await runtime.handleMessage(conn, encodeBuiltin(buildPairConfirm(
+        { identifier: "unknown-client", pairingCode: "SOME-CODE" },
+        { timestamp: now }
+      )));
+
+      const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+      expect(lastMessage.type).toBe("pair_failed");
+      expect((lastMessage.payload as PairFailedPayload).reason).toBe("identifier_not_allowed");
+    });
+  });
+
+  describe("PF-04: Admin notification failure", () => {
+    it("fails pairing when notification cannot be sent", async () => {
+      const store = createMockStore();
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["client-a"],
+          notifyBotToken: "", // Empty token should cause notification failure
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      const conn = createConnection();
+      await runtime.handleMessage(conn, encodeBuiltin(buildHello(
+        { identifier: "client-a", hasSecret: false, hasKeyPair: true, protocolVersion: YONEXUS_PROTOCOL_VERSION },
+        { timestamp: now }
+      )));
+
+      // Check the pair_request indicates notification failure
+      const pairRequest = sent.find(m => decodeBuiltin(m.message).type === "pair_request");
+      expect(pairRequest).toBeDefined();
+
+      // Should not have created a valid pending pairing
+      const record = runtime.state.registry.clients.get("client-a");
+      if (record?.pairingStatus === "pending") {
+        // If notification failed, pairing should indicate this
+        expect(record.pairingNotifyStatus).toBe("failed");
+      }
+    });
+  });
+
+  describe("PF-05: Empty pairing code", () => {
+    it("rejects empty pairing code", async () => {
+      const store = createMockStore();
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["client-a"],
+          notifyBotToken: "test-token",
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      const conn = createConnection();
+      await runtime.handleMessage(conn, encodeBuiltin(buildHello(
+        { identifier: "client-a", hasSecret: false, hasKeyPair: true, protocolVersion: YONEXUS_PROTOCOL_VERSION },
+        { timestamp: now }
+      )));
+
+      // Submit empty code
+      await runtime.handleMessage(conn, encodeBuiltin(buildPairConfirm(
+        { identifier: "client-a", pairingCode: "" },
+        { timestamp: now + 10 }
+      )));
+
+      const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+      expect(lastMessage.type).toBe("pair_failed");
+      expect((lastMessage.payload as PairFailedPayload).reason).toBe("invalid_code");
+    });
+
+    it("rejects whitespace-only pairing code", async () => {
+      const store = createMockStore();
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["client-a"],
+          notifyBotToken: "test-token",
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      const conn = createConnection();
+      await runtime.handleMessage(conn, encodeBuiltin(buildHello(
+        { identifier: "client-a", hasSecret: false, hasKeyPair: true, protocolVersion: YONEXUS_PROTOCOL_VERSION },
+        { timestamp: now }
+      )));
+
+      // Submit whitespace code
+      await runtime.handleMessage(conn, encodeBuiltin(buildPairConfirm(
+        { identifier: "client-a", pairingCode: "   \t\n  " },
+        { timestamp: now + 10 }
+      )));
+
+      const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+      expect(lastMessage.type).toBe("pair_failed");
+    });
+  });
+
+  describe("PF-06: Malformed pair_confirm payload", () => {
+    it("handles missing identifier in pair_confirm", async () => {
+      const store = createMockStore();
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["client-a"],
+          notifyBotToken: "test-token",
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      const conn = createConnection();
+      await runtime.handleMessage(conn, encodeBuiltin(buildHello(
+        { identifier: "client-a", hasSecret: false, hasKeyPair: true, protocolVersion: YONEXUS_PROTOCOL_VERSION },
+        { timestamp: now }
+      )));
+
+      // Send malformed payload (missing fields)
+      await runtime.handleMessage(conn, encodeBuiltin({
+        type: "pair_confirm",
+        timestamp: now,
+        payload: { pairingCode: "SOME-CODE" } // Missing identifier
+      }));
+
+      // Should receive an error response
+      const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+      expect(lastMessage.type).toBe("error");
+    });
+
+    it("handles missing pairingCode in pair_confirm", async () => {
+      const store = createMockStore();
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["client-a"],
+          notifyBotToken: "test-token",
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      const conn = createConnection();
+      await runtime.handleMessage(conn, encodeBuiltin(buildHello(
+        { identifier: "client-a", hasSecret: false, hasKeyPair: true, protocolVersion: YONEXUS_PROTOCOL_VERSION },
+        { timestamp: now }
+      )));
+
+      // Send malformed payload (missing pairingCode)
+      await runtime.handleMessage(conn, encodeBuiltin({
+        type: "pair_confirm",
+        timestamp: now,
+        payload: { identifier: "client-a" } // Missing pairingCode
+      }));
+
+      const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+      expect(lastMessage.type).toBe("pair_failed");
+    });
+  });
+
+  describe("PF-07: Double pairing attempt", () => {
+    it("rejects pair_confirm for already paired client", async () => {
+      const store = createMockStore([{
+        identifier: "client-a",
+        pairingStatus: "paired",
+        publicKey: "existing-key",
+        secret: "existing-secret",
+        status: "offline",
+        recentNonces: [],
+        recentHandshakeAttempts: [],
+        createdAt: now - 1000,
+        updatedAt: now - 500,
+        pairedAt: now - 500
+      }]);
+
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["client-a"],
+          notifyBotToken: "test-token",
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      // Try to pair an already paired client
+      const conn = createConnection();
+      await runtime.handleMessage(conn, encodeBuiltin(buildPairConfirm(
+        { identifier: "client-a", pairingCode: "SOME-CODE" },
+        { timestamp: now }
+      )));
+
+      // Should reject since already paired
+      const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+      expect(lastMessage.type).toBe("pair_failed");
+
+      // Existing trust material preserved
+      const record = runtime.state.registry.clients.get("client-a");
+      expect(record?.pairingStatus).toBe("paired");
+      expect(record?.secret).toBe("existing-secret");
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("PF-08: pairing attempt during an active paired session is rejected without losing trust", async () => {
+      const store = createMockStore([{
+        identifier: "client-a",
+        pairingStatus: "paired",
+        publicKey: "existing-key",
+        secret: "existing-secret",
+        status: "online",
+        recentNonces: [],
+        recentHandshakeAttempts: [],
+        createdAt: now - 1000,
+        updatedAt: now - 10,
+        pairedAt: now - 500,
+        lastAuthenticatedAt: now - 5,
+        lastHeartbeatAt: now - 5
+      }]);
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["client-a"],
+          notifyBotToken: "test-token",
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      const conn = createConnection("client-a");
+      await runtime.handleMessage(conn, encodeBuiltin(buildPairConfirm(
+        { identifier: "client-a", pairingCode: "NEW-PAIR-CODE" },
+        { timestamp: now }
+      )));
+
+      const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+      expect(lastMessage.type).toBe("pair_failed");
+      expect((lastMessage.payload as PairFailedPayload).reason).toBe("internal_error");
+
+      const record = runtime.state.registry.clients.get("client-a");
+      expect(record).toMatchObject({
+        pairingStatus: "paired",
+        secret: "existing-secret",
+        publicKey: "existing-key",
+        status: "online"
+      });
+    });
+
+    it("handles concurrent pair_confirm from different connections with same identifier", async () => {
+      const store = createMockStore();
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["client-a"],
+          notifyBotToken: "test-token",
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      // First connection starts pairing
+      const conn1 = createConnection();
+      await runtime.handleMessage(conn1, encodeBuiltin(buildHello(
+        { identifier: "client-a", hasSecret: false, hasKeyPair: true, protocolVersion: YONEXUS_PROTOCOL_VERSION },
+        { timestamp: now }
+      )));
+
+      const pairingCode = runtime.state.registry.clients.get("client-a")?.pairingCode;
+
+      // Second connection tries to pair with same identifier
+      const conn2 = createConnection();
+      await runtime.handleMessage(conn2, encodeBuiltin(buildPairConfirm(
+        { identifier: "client-a", pairingCode: pairingCode! },
+        { timestamp: now + 10 }
+      )));
+
+      // Should succeed - pairing is identifier-based, not connection-based
+      const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+      expect(lastMessage.type).toBe("pair_success");
+    });
+
+    it("cleans up pending pairing state on expiry", async () => {
+      const store = createMockStore();
+      const { transport, sent } = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["client-a"],
+          notifyBotToken: "test-token",
+          adminUserId: "admin",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport,
+        now: () => now
+      });
+
+      await runtime.start();
+
+      const conn = createConnection();
+      await runtime.handleMessage(conn, encodeBuiltin(buildHello(
+        { identifier: "client-a", hasSecret: false, hasKeyPair: true, protocolVersion: YONEXUS_PROTOCOL_VERSION },
+        { timestamp: now }
+      )));
+
+      // Verify pending state exists
+      const recordBefore = runtime.state.registry.clients.get("client-a");
+      expect(recordBefore?.pairingStatus).toBe("pending");
+      expect(recordBefore?.pairingCode).toBeDefined();
+
+      // Expire and try to use old code
+      now += 400; // Past default TTL
+      await runtime.handleMessage(conn, encodeBuiltin(buildPairConfirm(
+        { identifier: "client-a", pairingCode: recordBefore?.pairingCode! },
+        { timestamp: now }
+      )));
+
+      const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+      expect(lastMessage.type).toBe("pair_failed");
+      expect((lastMessage.payload as PairFailedPayload).reason).toBe("expired");
+
+      // State cleaned up
+      const recordAfter = runtime.state.registry.clients.get("client-a");
+      expect(recordAfter?.pairingStatus).toBe("unpaired");
+      expect(recordAfter?.pairingCode).toBeUndefined();
+    });
+  });
+});

tests/integration/framework.test.ts

@@ -0,0 +1,630 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import type { ClientConnection, ServerTransport } from "../../Yonexus.Server/plugin/core/transport.js";
+import type { ClientTransport } from "../../Yonexus.Client/plugin/core/transport.js";
+import type { YonexusServerStore } from "../../Yonexus.Server/plugin/core/store.js";
+import type { YonexusClientStateStore } from "../../Yonexus.Client/plugin/core/state.js";
+import { createYonexusServerRuntime } from "../../Yonexus.Server/plugin/core/runtime.js";
+import { createYonexusClientRuntime } from "../../Yonexus.Client/plugin/core/runtime.js";
+import {
+  decodeBuiltin,
+  encodeBuiltin,
+  buildHello,
+  buildHelloAck,
+  buildPairRequest,
+  buildPairConfirm,
+  buildPairSuccess,
+  buildAuthRequest,
+  buildAuthSuccess,
+  buildHeartbeat,
+  buildHeartbeatAck,
+  createAuthRequestSigningInput,
+  YONEXUS_PROTOCOL_VERSION
+} from "../../Yonexus.Protocol/src/index.js";
+import { generateKeyPair, signMessage } from "../../Yonexus.Client/plugin/crypto/keypair.js";
+import type { ClientRecord } from "../../Yonexus.Server/plugin/core/persistence.js";
+import type { YonexusClientState } from "../../Yonexus.Client/plugin/core/state.js";
+
+/**
+ * Yonexus Server-Client Integration Test Framework
+ *
+ * This module provides utilities for testing Server and Client interactions
+ * without requiring real network sockets.
+ */
+
+// ============================================================================
+// Mock Transport Pair - Simulates network connection between Server and Client
+// ============================================================================
+
+export interface MockMessageChannel {
+  serverToClient: string[];
+  clientToServer: string[];
+}
+
+export interface MockTransportPair {
+  serverTransport: ServerTransport;
+  clientTransport: ClientTransport;
+  channel: MockMessageChannel;
+  getServerReceived: () => string[];
+  getClientReceived: () => string[];
+  clearMessages: () => void;
+}
+
+export function createMockTransportPair(): MockTransportPair {
+  const channel: MockMessageChannel = {
+    serverToClient: [],
+    clientToServer: []
+  };
+
+  // Track server-side connections
+  const serverConnections = new Map<string, ClientConnection>();
+  let tempConnection: ClientConnection | null = null;
+
+  // Server Transport Mock
+  const serverTransport: ServerTransport = {
+    isRunning: false,
+    connections: serverConnections,
+
+    start: vi.fn(async () => {
+      serverTransport.isRunning = true;
+    }),
+
+    stop: vi.fn(async () => {
+      serverTransport.isRunning = false;
+      serverConnections.clear();
+    }),
+
+    send: vi.fn((identifier: string, message: string) => {
+      if (serverConnections.has(identifier)) {
+        channel.serverToClient.push(message);
+        return true;
+      }
+      return false;
+    }),
+
+    sendToConnection: vi.fn((connection: ClientConnection, message: string) => {
+      channel.serverToClient.push(message);
+      return true;
+    }),
+
+    broadcast: vi.fn((message: string) => {
+      channel.serverToClient.push(`[broadcast]:${message}`);
+    }),
+
+    closeConnection: vi.fn((identifier: string, code?: number, reason?: string) => {
+      const conn = serverConnections.get(identifier);
+      if (conn) {
+        conn.isAuthenticated = false;
+        serverConnections.delete(identifier);
+      }
+      return true;
+    }),
+
+    assignIdentifierToTemp: vi.fn((ws, identifier: string) => {
+      if (tempConnection) {
+        tempConnection.identifier = identifier;
+      }
+    }),
+
+    promoteToAuthenticated: vi.fn((identifier: string, ws) => {
+      if (tempConnection && tempConnection.identifier === identifier) {
+        tempConnection.isAuthenticated = true;
+        serverConnections.set(identifier, tempConnection);
+        tempConnection = null;
+      }
+    }),
+
+    removeTempConnection: vi.fn(() => {
+      tempConnection = null;
+    })
+  };
+
+  // Client Transport Mock
+  let clientState: import("../../Yonexus.Client/plugin/core/transport.js").ClientConnectionState = "idle";
+
+  const clientTransport: ClientTransport = {
+    get state() {
+      return clientState;
+    },
+
+    get isConnected() {
+      return clientState !== "idle" && clientState !== "disconnected" && clientState !== "error";
+    },
+
+    get isAuthenticated() {
+      return clientState === "authenticated";
+    },
+
+    connect: vi.fn(async () => {
+      clientState = "connected";
+      // Simulate connection - create temp connection on server side
+      tempConnection = {
+        identifier: null,
+        ws: { close: vi.fn() } as unknown as WebSocket,
+        connectedAt: Date.now(),
+        isAuthenticated: false
+      };
+    }),
+
+    disconnect: vi.fn(() => {
+      clientState = "disconnected";
+      tempConnection = null;
+    }),
+
+    send: vi.fn((message: string) => {
+      if (clientState === "connected" || clientState === "authenticated" || clientState === "authenticating") {
+        channel.clientToServer.push(message);
+        return true;
+      }
+      return false;
+    }),
+
+    markAuthenticated: vi.fn(() => {
+      clientState = "authenticated";
+    }),
+
+    markAuthenticating: vi.fn(() => {
+      clientState = "authenticating";
+    })
+  };
+
+  return {
+    serverTransport,
+    clientTransport,
+    channel,
+    getServerReceived: () => [...channel.clientToServer],
+    getClientReceived: () => [...channel.serverToClient],
+    clearMessages: () => {
+      channel.serverToClient.length = 0;
+      channel.clientToServer.length = 0;
+    }
+  };
+}
+
+// ============================================================================
+// Mock Store Factories
+// ============================================================================
+
+export function createMockServerStore(initialClients: ClientRecord[] = []): YonexusServerStore {
+  const persisted = new Map(initialClients.map((record) => [record.identifier, record]));
+
+  return {
+    filePath: "/tmp/yonexus-server-test.json",
+    load: vi.fn(async () => ({
+      version: 1,
+      persistedAt: Date.now(),
+      clients: new Map(persisted)
+    })),
+    save: vi.fn(async (clients: Iterable<ClientRecord>) => {
+      persisted.clear();
+      for (const client of clients) {
+        persisted.set(client.identifier, client);
+      }
+    })
+  };
+}
+
+export function createMockClientStore(initialState?: Partial<YonexusClientState>): YonexusClientStateStore {
+  let state: YonexusClientState = {
+    identifier: initialState?.identifier ?? "test-client",
+    publicKey: initialState?.publicKey,
+    privateKey: initialState?.privateKey,
+    secret: initialState?.secret,
+    pairedAt: initialState?.pairedAt,
+    authenticatedAt: initialState?.authenticatedAt,
+    updatedAt: initialState?.updatedAt ?? Date.now()
+  };
+
+  return {
+    filePath: "/tmp/yonexus-client-test.json",
+    load: vi.fn(async () => ({ ...state })),
+    save: vi.fn(async (next) => {
+      state = { ...next };
+    })
+  };
+}
+
+// ============================================================================
+// Test Runtime Factory
+// ============================================================================
+
+export interface IntegrationTestContext {
+  serverRuntime: ReturnType<typeof createYonexusServerRuntime>;
+  clientRuntime: ReturnType<typeof createYonexusClientRuntime>;
+  transports: MockTransportPair;
+  serverStore: YonexusServerStore;
+  clientStore: YonexusClientStateStore;
+  advanceTime: (seconds: number) => void;
+  processServerToClient: () => Promise<void>;
+  processClientToServer: () => Promise<void>;
+  processAllMessages: () => Promise<void>;
+}
+
+export async function createIntegrationTestContext(
+  options: {
+    clientIdentifier?: string;
+    paired?: boolean;
+    authenticated?: boolean;
+    serverTime?: number;
+    initialClientState?: Partial<YonexusClientState>;
+    initialServerClients?: ClientRecord[];
+  } = {}
+): Promise<IntegrationTestContext> {
+  const initialNow = options.serverTime ?? 1_710_000_000;
+  const identifier = options.clientIdentifier ?? "test-client";
+
+  const transports = createMockTransportPair();
+  const serverStore = createMockServerStore(options.initialServerClients ?? []);
+  const clientStore = createMockClientStore({ identifier, ...options.initialClientState });
+
+  // Generate keypair for client if needed
+  const keyPair = await generateKeyPair();
+
+  let currentTime = initialNow;
+
+  const serverRuntime = createYonexusServerRuntime({
+    config: {
+      followerIdentifiers: [identifier],
+      notifyBotToken: "test-token",
+      adminUserId: "admin-user",
+      listenHost: "127.0.0.1",
+      listenPort: 8787
+    },
+    store: serverStore,
+    transport: transports.serverTransport,
+    now: () => currentTime
+  });
+
+  const clientRuntime = createYonexusClientRuntime({
+    config: {
+      mainHost: "ws://localhost:8787",
+      identifier,
+      notifyBotToken: "test-token",
+      adminUserId: "admin-user"
+    },
+    transport: transports.clientTransport,
+    stateStore: clientStore,
+    now: () => currentTime
+  });
+
+  await serverRuntime.start();
+  const advanceTime = (seconds: number) => {
+    currentTime += seconds;
+  };
+
+  // Message processing helpers
+  const processServerToClient = async () => {
+    const messages = transports.getClientReceived();
+    transports.clearMessages();
+    for (const msg of messages) {
+      await clientRuntime.handleMessage(msg);
+    }
+  };
+
+  const processClientToServer = async () => {
+    const messages = transports.getServerReceived();
+    transports.clearMessages();
+
+    // Get the temp connection for message handling
+    const connection = {
+      identifier: identifier,
+      ws: { close: vi.fn() } as unknown as WebSocket,
+      connectedAt: currentTime,
+      isAuthenticated: options.authenticated ?? false
+    };
+
+    for (const msg of messages) {
+      await serverRuntime.handleMessage(connection, msg);
+    }
+  };
+
+  const processAllMessages = async () => {
+    await processClientToServer();
+    await processServerToClient();
+  };
+
+  return {
+    serverRuntime,
+    clientRuntime,
+    transports,
+    serverStore,
+    clientStore,
+    advanceTime,
+    processServerToClient,
+    processClientToServer,
+    processAllMessages
+  };
+}
+
+// ============================================================================
+// Integration Test Suite
+// ============================================================================
+
+describe("Yonexus Server-Client Integration", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe("First-Time Pairing Flow", () => {
+    it("completes full pairing and authentication cycle", async () => {
+      const ctx = await createIntegrationTestContext({
+        clientIdentifier: "new-client"
+      });
+
+      // Step 1: Client connects and sends hello
+      await ctx.clientRuntime.start();
+      ctx.clientRuntime.handleTransportStateChange("connected");
+      await vi.advanceTimersByTimeAsync(100);
+
+      // Process hello -> hello_ack + pair_request
+      await ctx.processClientToServer();
+      await ctx.processServerToClient();
+
+      // Verify client received pair_request
+      expect(ctx.clientRuntime.state.phase).toBe("waiting_pair_confirm");
+      expect(ctx.clientRuntime.state.pendingPairing).toBeDefined();
+
+      // Step 2: Client submits pairing code
+      const pairingCode = ctx.serverRuntime.state.registry.clients.get("new-client")?.pairingCode;
+      expect(pairingCode).toBeDefined();
+
+      ctx.clientRuntime.submitPairingCode(pairingCode!, "req-pair-confirm");
+      await vi.advanceTimersByTimeAsync(100);
+
+      // Process pair_confirm -> pair_success
+      await ctx.processClientToServer();
+      await ctx.processServerToClient();
+
+      // Verify client received secret
+      expect(ctx.clientRuntime.state.clientState.secret).toBeDefined();
+      expect(ctx.clientRuntime.state.phase).toBe("auth_required");
+
+      // Step 3: Client sends auth request
+      await vi.advanceTimersByTimeAsync(100);
+      await ctx.processClientToServer();
+      await ctx.processServerToClient();
+
+      // Verify authentication success
+      expect(ctx.clientRuntime.state.phase).toBe("authenticated");
+      expect(ctx.serverRuntime.state.registry.sessions.get("new-client")?.isAuthenticated).toBe(true);
+    });
+  });
+
+  describe("Reconnection Flow", () => {
+    it("reconnects with existing credentials without re-pairing", async () => {
+      const now = 1_710_000_000;
+      const keyPair = await generateKeyPair();
+
+      const ctx = await createIntegrationTestContext({
+        clientIdentifier: "reconnect-client",
+        paired: true,
+        authenticated: false,
+        initialClientState: {
+          secret: "existing-secret",
+          publicKey: keyPair.publicKey.trim(),
+          privateKey: keyPair.privateKey,
+          pairedAt: now - 1000,
+          updatedAt: now - 1000
+        },
+        initialServerClients: [
+          {
+            identifier: "reconnect-client",
+            pairingStatus: "paired",
+            publicKey: keyPair.publicKey.trim(),
+            secret: "existing-secret",
+            status: "offline",
+            recentNonces: [],
+            recentHandshakeAttempts: [],
+            createdAt: now - 2000,
+            updatedAt: now - 1000
+          }
+        ]
+      });
+
+      // Connect and send hello
+      await ctx.clientRuntime.start();
+      ctx.clientRuntime.handleTransportStateChange("connected");
+      await vi.advanceTimersByTimeAsync(100);
+
+      await ctx.processClientToServer();
+      await ctx.processServerToClient();
+
+      // Should go directly to auth_required, skipping pairing
+      expect(ctx.clientRuntime.state.phase).toBe("auth_required");
+
+      // Complete authentication
+      await vi.advanceTimersByTimeAsync(100);
+      await ctx.processClientToServer();
+      await ctx.processServerToClient();
+
+      expect(ctx.clientRuntime.state.phase).toBe("authenticated");
+    });
+  });
+
+  describe("Heartbeat Flow", () => {
+    it("exchanges heartbeats after authentication", async () => {
+      const now = 1_710_000_000;
+      const keyPair = await generateKeyPair();
+      const ctx = await createIntegrationTestContext({
+        clientIdentifier: "heartbeat-client",
+        serverTime: now,
+        initialClientState: {
+          secret: "existing-secret",
+          publicKey: keyPair.publicKey.trim(),
+          privateKey: keyPair.privateKey,
+          pairedAt: now - 1000,
+          updatedAt: now - 1000
+        },
+        initialServerClients: [
+          {
+            identifier: "heartbeat-client",
+            pairingStatus: "paired",
+            publicKey: keyPair.publicKey.trim(),
+            secret: "existing-secret",
+            status: "offline",
+            recentNonces: [],
+            recentHandshakeAttempts: [],
+            createdAt: now - 2000,
+            updatedAt: now - 1000
+          }
+        ]
+      });
+
+      await ctx.clientRuntime.start();
+      ctx.clientRuntime.handleTransportStateChange("connected");
+      await vi.advanceTimersByTimeAsync(100);
+      await ctx.processClientToServer();
+      await ctx.processServerToClient();
+      await vi.advanceTimersByTimeAsync(100);
+      await ctx.processClientToServer();
+      await ctx.processServerToClient();
+
+      expect(ctx.clientRuntime.state.phase).toBe("authenticated");
+
+      await ctx.clientRuntime.handleMessage("heartbeat_tick");
+      await vi.advanceTimersByTimeAsync(100);
+      await ctx.processClientToServer();
+
+      const record = ctx.serverRuntime.state.registry.clients.get("heartbeat-client");
+      expect(record?.lastHeartbeatAt).toBeDefined();
+    });
+
+    it("marks client unstable then offline after heartbeat timeout", async () => {
+      const now = 1_710_000_000;
+      const keyPair = await generateKeyPair();
+      const ctx = await createIntegrationTestContext({
+        clientIdentifier: "timed-out-client",
+        serverTime: now
+      });
+
+      ctx.serverRuntime.state.registry.clients.set("timed-out-client", {
+        identifier: "timed-out-client",
+        pairingStatus: "paired",
+        publicKey: keyPair.publicKey.trim(),
+        secret: "existing-secret",
+        status: "online",
+        recentNonces: [],
+        recentHandshakeAttempts: [],
+        lastAuthenticatedAt: now,
+        lastHeartbeatAt: now,
+        createdAt: now - 100,
+        updatedAt: now
+      });
+      ctx.serverRuntime.state.registry.sessions.set("timed-out-client", {
+        identifier: "timed-out-client",
+        socket: { close: vi.fn() } as unknown as WebSocket,
+        isAuthenticated: true,
+        connectedAt: now,
+        lastActivityAt: now,
+        publicKey: keyPair.publicKey.trim()
+      });
+      ctx.transports.serverTransport.connections.set("timed-out-client", {
+        identifier: "timed-out-client",
+        ws: { close: vi.fn() } as unknown as WebSocket,
+        connectedAt: now,
+        isAuthenticated: true
+      });
+
+      ctx.advanceTime(7 * 60);
+      await vi.advanceTimersByTimeAsync(30_100);
+
+      const unstableRecord = ctx.serverRuntime.state.registry.clients.get("timed-out-client");
+      expect(unstableRecord?.status).toBe("unstable");
+      expect(ctx.transports.channel.serverToClient.some((message) => {
+        const envelope = decodeBuiltin(message);
+        return envelope.type === "status_update";
+      })).toBe(true);
+
+      ctx.advanceTime(4 * 60);
+      await vi.advanceTimersByTimeAsync(30_100);
+
+      const offlineRecord = ctx.serverRuntime.state.registry.clients.get("timed-out-client");
+      expect(offlineRecord?.status).toBe("offline");
+      expect(ctx.serverRuntime.state.registry.sessions.has("timed-out-client")).toBe(false);
+      expect(ctx.transports.channel.serverToClient.some((message) => {
+        const envelope = decodeBuiltin(message);
+        return envelope.type === "disconnect_notice";
+      })).toBe(true);
+    });
+  });
+
+  describe("Re-pair Flow", () => {
+    it("forces client back to pair_required after nonce collision", async () => {
+      const now = 1_710_000_000;
+      const keyPair = await generateKeyPair();
+      const collisionNonce = "NONCE1234567890123456789";
+      const ctx = await createIntegrationTestContext({
+        clientIdentifier: "collision-client",
+        serverTime: now,
+        initialClientState: {
+          secret: "existing-secret",
+          publicKey: keyPair.publicKey.trim(),
+          privateKey: keyPair.privateKey,
+          pairedAt: now - 100,
+          updatedAt: now - 100
+        },
+        initialServerClients: [
+          {
+            identifier: "collision-client",
+            pairingStatus: "paired",
+            publicKey: keyPair.publicKey.trim(),
+            secret: "existing-secret",
+            status: "offline",
+            recentNonces: [{ nonce: collisionNonce, timestamp: now - 1 }],
+            recentHandshakeAttempts: [],
+            createdAt: now - 200,
+            updatedAt: now - 100
+          }
+        ]
+      });
+
+      ctx.serverRuntime.state.registry.sessions.set("collision-client", {
+        identifier: "collision-client",
+        socket: { close: vi.fn() } as unknown as WebSocket,
+        isAuthenticated: false,
+        connectedAt: now,
+        lastActivityAt: now,
+        publicKey: keyPair.publicKey.trim()
+      });
+
+      const authRequest = buildAuthRequest(
+        {
+          identifier: "collision-client",
+          nonce: collisionNonce,
+          proofTimestamp: now,
+          signature: await signMessage(
+            keyPair.privateKey,
+            createAuthRequestSigningInput({
+              secret: "existing-secret",
+              nonce: collisionNonce,
+              proofTimestamp: now
+            })
+          ),
+          publicKey: keyPair.publicKey.trim()
+        },
+        { requestId: "req-collision", timestamp: now }
+      );
+
+      await ctx.serverRuntime.handleMessage(
+        {
+          identifier: "collision-client",
+          ws: { close: vi.fn() } as unknown as WebSocket,
+          connectedAt: now,
+          isAuthenticated: false
+        },
+        encodeBuiltin(authRequest)
+      );
+
+      const serverEnvelope = decodeBuiltin(ctx.transports.channel.serverToClient.at(-1) ?? "");
+      expect(serverEnvelope.type).toBe("re_pair_required");
+
+      await ctx.clientRuntime.handleMessage(ctx.transports.channel.serverToClient.at(-1)!);
+      expect(ctx.clientRuntime.state.phase).toBe("pair_required");
+      expect(ctx.clientRuntime.state.clientState.secret).toBeUndefined();
+      expect(ctx.clientRuntime.state.lastPairingFailure).toBe("re_pair_required");
+    });
+  });
+});