fix: allow empty followerIdentifiers to avoid blocking openclaw CLI

An empty followerIdentifiers array caused a fatal validation error during
plugin registration, which prevented all openclaw CLI commands from running.

.gitignore

@@ -1,2 +1,4 @@
 node_modules/
 dist/
+coverage/
+*.log

README.md

@@ -13,7 +13,7 @@ It runs on the main OpenClaw instance and is responsible for:
 
 ## Status
 
-Current state: **scaffold + core runtime MVP**
+Current state: **core runtime MVP with Discord DM transport wired via REST API**
 
 Implemented in this repository today:
 
@@ -25,14 +25,13 @@ Implemented in this repository today:
 - auth proof validation flow
 - heartbeat receive + liveness sweep
 - rule registry + send-to-client APIs
-- notification service stub/mock for pairing DM flow
+- Discord DM pairing notifications via Discord REST API (`notifyBotToken` + `adminUserId`)
 
 Still pending before production use:
 
-- automated Server unit/integration tests
-- real Discord DM transport wiring
-- operator hardening / troubleshooting docs
 - broader lifecycle integration with real OpenClaw plugin hooks
+- more operator-facing hardening / troubleshooting polish
+- expanded edge-case and live-environment validation beyond the current automated suite
 
 ## Install Layout
 
@@ -133,11 +132,11 @@ npm run check
 
 Current known limitations:
 
-- pairing DM sending is still a stub/mock abstraction
+- DM delivery depends on Discord bot permissions and the target user's DM settings
 - no offline message queueing
 - no multi-server topology
 - no management UI
-- no server-side unit/integration test suite yet
+- transport is covered mainly by automated tests rather than live Discord end-to-end validation
 
 ## Related Repos
 

package.json

@@ -5,6 +5,9 @@
   "description": "Yonexus.Server OpenClaw plugin scaffold",
   "type": "module",
   "main": "dist/plugin/index.js",
+  "openclaw": {
+    "extensions": ["./dist/Yonexus.Server/plugin/index.js"]
+  },
   "files": [
     "dist",
     "plugin",

plugin/core/config.ts

@@ -35,7 +35,7 @@ function normalizeOptionalString(value: unknown): string | undefined {
 }
 
 function isValidPort(value: unknown): value is number {
-  return Number.isInteger(value) && value >= 1 && value <= 65535;
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535;
 }
 
 function isValidWsUrl(value: string): boolean {
@@ -59,26 +59,26 @@ export function validateYonexusServerConfig(raw: unknown): YonexusServerConfig {
         .filter((value) => value.length > 0)
     : [];
 
-  if (!Array.isArray(rawIdentifiers) || followerIdentifiers.length === 0) {
+  if (!Array.isArray(rawIdentifiers)) {
-    issues.push("followerIdentifiers must contain at least one non-empty identifier");
+    issues.push("followerIdentifiers must be an array");
   }
 
   if (new Set(followerIdentifiers).size !== followerIdentifiers.length) {
     issues.push("followerIdentifiers must not contain duplicates");
   }
 
-  const notifyBotToken = source.notifyBotToken;
+  const rawNotifyBotToken = source.notifyBotToken;
-  if (!isNonEmptyString(notifyBotToken)) {
+  if (!isNonEmptyString(rawNotifyBotToken)) {
     issues.push("notifyBotToken is required");
   }
 
-  const adminUserId = source.adminUserId;
+  const rawAdminUserId = source.adminUserId;
-  if (!isNonEmptyString(adminUserId)) {
+  if (!isNonEmptyString(rawAdminUserId)) {
     issues.push("adminUserId is required");
   }
 
-  const listenPort = source.listenPort;
+  const rawListenPort = source.listenPort;
-  if (!isValidPort(listenPort)) {
+  if (!isValidPort(rawListenPort)) {
     issues.push("listenPort must be an integer between 1 and 65535");
   }
 
@@ -93,6 +93,10 @@ export function validateYonexusServerConfig(raw: unknown): YonexusServerConfig {
     throw new YonexusServerConfigError(issues);
   }
 
+  const notifyBotToken = rawNotifyBotToken as string;
+  const adminUserId = rawAdminUserId as string;
+  const listenPort = rawListenPort as number;
+
   return {
     followerIdentifiers,
     notifyBotToken: notifyBotToken.trim(),

plugin/core/persistence.ts

@@ -79,6 +79,9 @@ export interface ClientRecord {
   /** Last successful authentication timestamp (UTC unix seconds) */
   lastAuthenticatedAt?: number;
 
+  /** Last successful pairing timestamp (UTC unix seconds) */
+  pairedAt?: number;
+
   /**
    * Recent nonces used in authentication attempts.
    * This is a rolling window that may be cleared on restart.
@@ -151,6 +154,7 @@ export interface SerializedClientRecord {
   status: ClientLivenessStatus;
   lastHeartbeatAt?: number;
   lastAuthenticatedAt?: number;
+  pairedAt?: number;
   createdAt: number;
   updatedAt: number;
   // Note: recentNonces and recentHandshakeAttempts are intentionally
@@ -203,6 +207,7 @@ export function serializeClientRecord(record: ClientRecord): SerializedClientRec
     status: record.status,
     lastHeartbeatAt: record.lastHeartbeatAt,
     lastAuthenticatedAt: record.lastAuthenticatedAt,
+    pairedAt: record.pairedAt,
     createdAt: record.createdAt,
     updatedAt: record.updatedAt
   };

plugin/core/runtime.ts

@@ -38,7 +38,7 @@ import {
   type ClientRecord,
   type ServerRegistry
 } from "./persistence.js";
-import { verifySignature } from "../../../Yonexus.Client/plugin/crypto/keypair.js";
+import { verifySignature } from "../../../Yonexus.Protocol/src/crypto.js";
 import type { YonexusServerStore } from "./store.js";
 import { type ClientConnection, type ServerTransport } from "./transport.js";
 import { createPairingService, type PairingService } from "../services/pairing.js";
@@ -47,11 +47,15 @@ import {
   type DiscordNotificationService
 } from "../notifications/discord.js";
 import { safeErrorMessage } from "./logging.js";
+import type { ServerRuleRegistry } from "./rules.js";
 
 export interface YonexusServerRuntimeOptions {
   config: YonexusServerConfig;
   store: YonexusServerStore;
   transport: ServerTransport;
+  notificationService?: DiscordNotificationService;
+  ruleRegistry?: ServerRuleRegistry;
+  onClientAuthenticated?: (identifier: string) => void;
   now?: () => number;
   sweepIntervalMs?: number;
 }
@@ -80,10 +84,12 @@ export class YonexusServerRuntime {
     };
     this.sweepIntervalMs = options.sweepIntervalMs ?? 30_000;
     this.pairingService = createPairingService({ now: this.now });
-    this.notificationService = createDiscordNotificationService({
+    this.notificationService =
-      botToken: options.config.notifyBotToken,
+      options.notificationService ??
-      adminUserId: options.config.adminUserId
+      createDiscordNotificationService({
-    });
+        botToken: options.config.notifyBotToken,
+        adminUserId: options.config.adminUserId
+      });
   }
 
   get state(): ServerLifecycleState {
@@ -261,7 +267,7 @@ export class YonexusServerRuntime {
       isAuthenticated: false,
       connectedAt: connection.connectedAt,
       lastActivityAt: this.now(),
-      publicKey: payload.publicKey
+      publicKey: payload.publicKey?.trim() || undefined
     });
 
     const nextAction = this.determineNextAction(record);
@@ -444,7 +450,7 @@ export class YonexusServerRuntime {
     );
     record.recentHandshakeAttempts.push(now);
 
-    if (record.recentHandshakeAttempts.length > AUTH_MAX_ATTEMPTS_PER_WINDOW) {
+    if (record.recentHandshakeAttempts.length >= AUTH_MAX_ATTEMPTS_PER_WINDOW) {
       await this.triggerRePairRequired(connection, record, envelope.requestId, "rate_limited");
       return;
     }
@@ -540,7 +546,10 @@ export class YonexusServerRuntime {
       session.lastActivityAt = now;
       session.publicKey = publicKey;
     }
-    this.options.transport.promoteToAuthenticated(identifier, connection.ws);
+    const promoted = this.options.transport.promoteToAuthenticated(identifier, connection.ws);
+    if (promoted) {
+      this.options.onClientAuthenticated?.(identifier);
+    }
     this.options.transport.sendToConnection(
       { ...connection, identifier },
       encodeBuiltin(
@@ -610,6 +619,11 @@ export class YonexusServerRuntime {
       this.pairingService.markNotificationFailed(record);
     }
 
+    // Persist immediately so the pairing code is readable from disk (e.g. via CLI)
+    if (!reusePending) {
+      await this.persist();
+    }
+
     this.options.transport.sendToConnection(
       connection,
       encodeBuiltin(
@@ -617,7 +631,7 @@ export class YonexusServerRuntime {
           {
             identifier: record.identifier,
             expiresAt: request.expiresAt,
-            ttlSeconds: this.pairingService.getRemainingTtl(record),
+            ttlSeconds: request.ttlSeconds,
             adminNotification: notified ? "sent" : "failed",
             codeDelivery: "out_of_band"
           },
@@ -625,22 +639,8 @@ export class YonexusServerRuntime {
         )
       )
     );
-
+    // Pairing remains pending regardless of notification status.
-    if (!notified) {
+    // The admin can retrieve the pairing code via the server CLI command.
-      this.options.transport.sendToConnection(
-        connection,
-        encodeBuiltin(
-          buildPairFailed(
-            {
-              identifier: record.identifier,
-              reason: "admin_notification_failed"
-            },
-            { requestId, timestamp: this.now() }
-          )
-        )
-      );
-      this.pairingService.clearPairingState(record);
-    }
   }
 
   private async handleHeartbeat(
@@ -929,16 +929,8 @@ export class YonexusServerRuntime {
       const parsed = parseRuleMessage(raw);
       const rewritten = `${parsed.ruleIdentifier}::${senderIdentifier}::${parsed.content}`;
 
-      // TODO: Dispatch to registered rules via rule registry
-      // For now, just log the rewritten message
-      // this.ruleRegistry.dispatch(rewritten);
-
-      // Update last activity
       session.lastActivityAt = this.now();
-
+      this.options.ruleRegistry?.dispatch(rewritten);
-      // Future: dispatch to rule registry
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      void rewritten;
     } catch (error) {
       // Malformed rule message
       this.options.transport.sendToConnection(

plugin/core/transport.ts

@@ -186,6 +186,16 @@ export class YonexusServerTransport implements ServerTransport {
       this._connections.delete(identifier);
     }
 
+    // Also close any OTHER temp connections that claimed the same identifier.
+    // This handles the case where a second hello came in with the same identifier
+    // while the first was still in the temp/pairing phase.
+    for (const [otherWs, otherTemp] of this.tempConnections.entries()) {
+      if (otherWs !== ws && otherTemp.assignedIdentifier === identifier) {
+        otherWs.close(1008, "Connection replaced by new authenticated session");
+        this.tempConnections.delete(otherWs);
+      }
+    }
+
     // Remove from temp connections
     this.tempConnections.delete(ws);
 
@@ -229,22 +239,24 @@ export class YonexusServerTransport implements ServerTransport {
 
     ws.on("message", (data: RawData) => {
       const message = data.toString("utf8");
-      // Try to get identifier from temp connections first, then authenticated connections
+      // If this ws is still in temp state, use tempConn directly.
-      let identifier: string | null = null;
+      // Never fall through to _connections — it may hold a stale entry for the
-      const tempData = this.tempConnections.get(ws);
+      // same identifier from a previously-authenticated session that hasn't
-      if (tempData) {
+      // finished closing yet, which would cause promoteToAuthenticated to receive
-        identifier = tempData.assignedIdentifier;
+      // the wrong WebSocket and silently fail.
-      }
+      if (this.tempConnections.has(ws)) {
-      if (!identifier) {
+        this.options.onMessage(tempConn, message);
-        for (const [id, conn] of this._connections) {
+        return;
-          if (conn.ws === ws) {
-            identifier = id;
-            break;
-          }
-        }
       }
 
-      const connection = identifier ? this._connections.get(identifier) ?? tempConn : tempConn;
+      // ws has been promoted — find it in authenticated connections
+      let connection: ClientConnection = tempConn;
+      for (const [, conn] of this._connections) {
+        if (conn.ws === ws) {
+          connection = conn;
+          break;
+        }
+      }
       this.options.onMessage(connection, message);
     });
 

plugin/index.ts

@@ -30,30 +30,189 @@ export {
   type YonexusServerStore
 } from "./core/store.js";
 
+import path from "node:path";
+import fs from "node:fs";
+import { validateYonexusServerConfig } from "./core/config.js";
+import { createYonexusServerStore } from "./core/store.js";
+import { createServerTransport, type ServerTransport } from "./core/transport.js";
+import { createYonexusServerRuntime } from "./core/runtime.js";
+import { createServerRuleRegistry, YonexusServerRuleRegistry } from "./core/rules.js";
+import { encodeRuleMessage } from "../../Yonexus.Protocol/src/index.js";
+import type { ServerPersistenceData } from "./core/persistence.js";
+
+const _G = globalThis as Record<string, unknown>;
+const _STARTED_KEY   = "_yonexusServerStarted";
+const _TRANSPORT_KEY = "_yonexusServerTransport";
+const _REGISTRY_KEY  = "_yonexusServerRegistry";
+const _CALLBACKS_KEY = "_yonexusServerOnAuthCallbacks";
+
 export interface YonexusServerPluginManifest {
   readonly name: "Yonexus.Server";
   readonly version: string;
   readonly description: string;
 }
 
-export interface YonexusServerPluginRuntime {
-  readonly hooks: readonly [];
-  readonly commands: readonly [];
-  readonly tools: readonly [];
-}
-
 const manifest: YonexusServerPluginManifest = {
   name: "Yonexus.Server",
   version: "0.1.0",
   description: "Yonexus central hub plugin for cross-instance OpenClaw communication"
 };
 
-export function createYonexusServerPlugin(): YonexusServerPluginRuntime {
+export function createYonexusServerPlugin(api: {
-  return {
+  rootDir: string;
-    hooks: [],
+  pluginConfig: unknown;
-    commands: [],
+  registrationMode?: string;  // "full" (gateway) | "cli-metadata" | "setup-only" | "setup-runtime"
-    tools: []
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  registerCli?: (registrar: (ctx: { program: any }) => void, opts?: { commands?: string[] }) => void;
+}): void {
+  const stateFilePath = path.join(api.rootDir, "state.json");
+
+  // Register CLI regardless of whether the gateway is already running.
+  // The CLI process is a separate invocation that reads from the persisted state file.
+  api.registerCli?.(({ program }) => {
+    const group = program
+      .command("yonexus-server")
+      .description("Yonexus.Server management");
+
+    group
+      .command("pair-code <identifier>")
+      .description("Show the pending pairing code for a device awaiting confirmation")
+      .action((identifier: string) => {
+        let raw: ServerPersistenceData;
+        try {
+          raw = JSON.parse(fs.readFileSync(stateFilePath, "utf8")) as ServerPersistenceData;
+        } catch {
+          console.error("Error: could not read server state. Is the gateway running?");
+          process.exit(1);
+        }
+
+        const client = raw.clients?.find((c) => c.identifier === identifier);
+        if (!client) {
+          console.error(`Error: identifier "${identifier}" not found in server registry.`);
+          process.exit(1);
+        }
+        if (client.pairingStatus !== "pending" || !client.pairingCode) {
+          const status = client.pairingStatus;
+          console.error(`Error: no pending pairing for "${identifier}" (status: ${status}).`);
+          process.exit(1);
+        }
+        if (client.pairingExpiresAt && Math.floor(Date.now() / 1000) > client.pairingExpiresAt) {
+          console.error(`Error: pairing for "${identifier}" has expired.`);
+          process.exit(1);
+        }
+
+        const expiresIn = client.pairingExpiresAt
+          ? Math.max(0, client.pairingExpiresAt - Math.floor(Date.now() / 1000))
+          : 0;
+        const mm = String(Math.floor(expiresIn / 60)).padStart(2, "0");
+        const ss = String(expiresIn % 60).padStart(2, "0");
+
+        console.log(`Identifier : ${client.identifier}`);
+        console.log(`Pairing code : ${client.pairingCode}`);
+        console.log(`Expires in : ${mm}m ${ss}s`);
+      });
+
+    group
+      .command("list-pending")
+      .description("List all identifiers with a pending pairing code")
+      .action(() => {
+        let raw: ServerPersistenceData;
+        try {
+          raw = JSON.parse(fs.readFileSync(stateFilePath, "utf8")) as ServerPersistenceData;
+        } catch {
+          console.error("Error: could not read server state. Is the gateway running?");
+          process.exit(1);
+        }
+
+        const now = Math.floor(Date.now() / 1000);
+        const pending = (raw.clients ?? []).filter(
+          (c) => c.pairingStatus === "pending" && c.pairingCode && (!c.pairingExpiresAt || now <= c.pairingExpiresAt)
+        );
+
+        if (pending.length === 0) {
+          console.log("No pending pairings.");
+          return;
+        }
+        for (const c of pending) {
+          const expiresIn = c.pairingExpiresAt ? Math.max(0, c.pairingExpiresAt - now) : 0;
+          const mm = String(Math.floor(expiresIn / 60)).padStart(2, "0");
+          const ss = String(expiresIn % 60).padStart(2, "0");
+          console.log(`  ${c.identifier}  (expires in ${mm}m ${ss}s)`);
+        }
+      });
+  }, { commands: ["yonexus-server"] });
+
+  // 1. Ensure shared state survives hot-reload — only initialise when absent
+  if (!(_G[_REGISTRY_KEY] instanceof YonexusServerRuleRegistry)) {
+    _G[_REGISTRY_KEY] = createServerRuleRegistry();
+  }
+  if (!Array.isArray(_G[_CALLBACKS_KEY])) {
+    _G[_CALLBACKS_KEY] = [];
+  }
+
+  const ruleRegistry                  = _G[_REGISTRY_KEY] as YonexusServerRuleRegistry;
+  const onClientAuthenticatedCallbacks = _G[_CALLBACKS_KEY] as Array<(identifier: string) => void>;
+
+  // 2. Refresh the cross-plugin API object every call so that sendRule closure
+  //    always reads the live transport from globalThis.
+  _G["__yonexusServer"] = {
+    ruleRegistry,
+    sendRule: (identifier: string, ruleId: string, content: string): boolean =>
+      (_G[_TRANSPORT_KEY] as ServerTransport | undefined)?.send(identifier, encodeRuleMessage(ruleId, content)) ?? false,
+    onClientAuthenticated: onClientAuthenticatedCallbacks
   };
+
+  // 3. Start the runtime only once — the globalThis flag survives hot-reload
+  if (_G[_STARTED_KEY]) return;
+  _G[_STARTED_KEY] = true;
+
+  const config = validateYonexusServerConfig(api.pluginConfig);
+  const store = createYonexusServerStore(stateFilePath);
+
+  // runtimeRef is local; transport is stored in globalThis so sendRule closures stay valid
+  let runtimeRef: ReturnType<typeof createYonexusServerRuntime> | null = null;
+  const transport = createServerTransport({
+    config,
+    onMessage: (conn, msg) => {
+      runtimeRef?.handleMessage(conn, msg).catch((err: unknown) => {
+        console.error("[yonexus-server] message handler error:", err);
+      });
+    },
+    onDisconnect: (identifier) => {
+      if (identifier && runtimeRef) {
+        runtimeRef.handleDisconnect(identifier);
+      }
+    }
+  });
+  _G[_TRANSPORT_KEY] = transport;
+
+  const runtime = createYonexusServerRuntime({
+    config,
+    store,
+    transport,
+    ruleRegistry,
+    onClientAuthenticated: (identifier) => {
+      for (const cb of onClientAuthenticatedCallbacks) cb(identifier);
+    }
+  });
+  runtimeRef = runtime;
+
+  const shutdown = (): void => {
+    runtime.stop().catch((err: unknown) => {
+      console.error("[yonexus-server] shutdown error:", err);
+    });
+  };
+  process.once("SIGTERM", shutdown);
+  process.once("SIGINT", shutdown);
+
+  runtime.start().catch((err: unknown) => {
+    // EADDRINUSE means the gateway is already running (e.g. this is a CLI invocation).
+    // Any other error is a real problem worth logging.
+    const code = (err as NodeJS.ErrnoException | undefined)?.code;
+    if (code !== "EADDRINUSE") {
+      console.error("[yonexus-server] failed to start:", err);
+    }
+  });
 }
 
 export default createYonexusServerPlugin;

plugin/notifications/discord.ts

@@ -5,7 +5,7 @@
  */
 
 import type { PairingRequest } from "../services/pairing.js";
-import { redactPairingCode } from "../core/logging.js";
+import { redactPairingCode, safeErrorMessage } from "../core/logging.js";
 
 export interface DiscordNotificationService {
   /**
@@ -20,48 +20,136 @@ export interface DiscordNotificationConfig {
   adminUserId: string;
 }
 
+export interface DiscordApiResponse {
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+}
+
+export type DiscordFetch = (
+  input: string,
+  init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  }
+) => Promise<DiscordApiResponse>;
+
+interface CreateDmChannelResponse {
+  id?: string;
+}
+
+interface SendDiscordDirectMessageOptions {
+  config: DiscordNotificationConfig;
+  message: string;
+  fetcher: DiscordFetch;
+}
+
+const DISCORD_API_BASE_URL = "https://discord.com/api/v10";
+
 /**
- * Create a Discord notification service.
+ * Create a Discord notification service backed by Discord's REST API.
  *
- * Note: This is a framework stub. Full implementation requires:
+ * Flow:
- * - Discord bot client integration (e.g., using discord.js)
+ * 1. Create or fetch a DM channel for the configured admin user
- * - DM channel creation/fetching
+ * 2. Post the formatted pairing message into that DM channel
- * - Error handling for blocked DMs, invalid tokens, etc.
- * 
- * For v1, this provides the interface and a mock implementation
- * that logs to console. Production deployments should replace
- * this with actual Discord bot integration.
  */
 export function createDiscordNotificationService(
-  config: DiscordNotificationConfig
+  config: DiscordNotificationConfig,
+  options: { fetcher?: DiscordFetch } = {}
 ): DiscordNotificationService {
+  const fetcher = options.fetcher ?? getDefaultFetch();
+
   return {
     async sendPairingNotification(request: PairingRequest): Promise<boolean> {
-      const redactedCode = redactPairingCode(request.pairingCode);
+      if (!config.botToken.trim() || !config.adminUserId.trim()) {
+        console.error("[Yonexus.Server] Discord DM notification misconfigured", {
+          hasBotToken: Boolean(config.botToken.trim()),
+          hasAdminUserId: Boolean(config.adminUserId.trim())
+        });
+        return false;
+      }
 
-      // Log to console (visible in OpenClaw logs)
+      try {
-      console.log("[Yonexus.Server] Pairing notification (Discord DM stub):", {
+        await sendDiscordDirectMessage({
-        identifier: request.identifier,
+          config,
-        pairingCode: redactedCode,
+          message: formatPairingMessage(request),
-        expiresAt: request.expiresAt,
+          fetcher
-        ttlSeconds: request.ttlSeconds,
+        });
-        adminUserId: config.adminUserId
-      });
 
-      // TODO: Replace with actual Discord bot integration
+        console.log("[Yonexus.Server] Pairing notification sent via Discord DM", {
-      // Example with discord.js:
+          identifier: request.identifier,
-      // const client = new Client({ intents: [GatewayIntentBits.DirectMessages] });
+          pairingCode: redactPairingCode(request.pairingCode),
-      // await client.login(config.botToken);
+          expiresAt: request.expiresAt,
-      // const user = await client.users.fetch(config.adminUserId);
+          ttlSeconds: request.ttlSeconds,
-      // await user.send(message);
+          adminUserId: config.adminUserId
+        });
 
-      // For now, return true to allow pairing flow to continue
+        return true;
-      // In production, this should return false if DM fails
+      } catch (error) {
-      return true;
+        console.error("[Yonexus.Server] Failed to send Discord DM pairing notification", {
+          identifier: request.identifier,
+          pairingCode: redactPairingCode(request.pairingCode),
+          adminUserId: config.adminUserId,
+          error: safeErrorMessage(error)
+        });
+        return false;
+      }
     }
   };
 }
 
+async function sendDiscordDirectMessage(
+  options: SendDiscordDirectMessageOptions
+): Promise<void> {
+  const { config, message, fetcher } = options;
+  const headers = {
+    Authorization: `Bot ${config.botToken}`,
+    "Content-Type": "application/json"
+  };
+
+  const dmResponse = await fetcher(`${DISCORD_API_BASE_URL}/users/@me/channels`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ recipient_id: config.adminUserId })
+  });
+
+  if (!dmResponse.ok) {
+    throw new Error(`Discord DM channel creation failed with status ${dmResponse.status}`);
+  }
+
+  const dmPayload = (await dmResponse.json()) as CreateDmChannelResponse;
+  const channelId = dmPayload.id?.trim();
+  if (!channelId) {
+    throw new Error("Discord DM channel creation did not return a channel id");
+  }
+
+  const messageResponse = await fetcher(`${DISCORD_API_BASE_URL}/channels/${channelId}/messages`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ content: message })
+  });
+
+  if (!messageResponse.ok) {
+    throw new Error(`Discord DM send failed with status ${messageResponse.status}`);
+  }
+
+  await messageResponse.json();
+}
+
+function getDefaultFetch(): DiscordFetch {
+  if (typeof fetch !== "function") {
+    throw new Error("Global fetch is not available in this runtime");
+  }
+
+  return (input, init) =>
+    fetch(input, {
+      method: init?.method,
+      headers: init?.headers,
+      body: init?.body
+    }) as Promise<DiscordApiResponse>;
+}
+
 /**
  * Format a pairing request as a Discord DM message.
  */

plugin/openclaw.plugin.json

@@ -1,15 +1,24 @@
 {
+  "id": "yonexus-server",
   "name": "Yonexus.Server",
   "version": "0.1.0",
   "description": "Yonexus central hub plugin for cross-instance OpenClaw communication",
-  "entry": "dist/plugin/index.js",
+  "entry": "./dist/Yonexus.Server/plugin/index.js",
   "permissions": [],
-  "config": {
+  "configSchema": {
-    "followerIdentifiers": [],
+    "type": "object",
-    "notifyBotToken": "",
+    "additionalProperties": false,
-    "adminUserId": "",
+    "properties": {
-    "listenHost": "0.0.0.0",
+      "followerIdentifiers": {
-    "listenPort": 8787,
+        "type": "array",
-    "publicWsUrl": ""
+        "items": { "type": "string" }
+      },
+      "notifyBotToken": { "type": "string" },
+      "adminUserId": { "type": "string" },
+      "listenHost": { "type": "string" },
+      "listenPort": { "type": "number" },
+      "publicWsUrl": { "type": "string" }
+    },
+    "required": ["notifyBotToken", "adminUserId", "listenPort"]
   }
 }

plugin/types/ws.d.ts

@@ -0,0 +1,21 @@
+declare module "ws" {
+  export type RawData = Buffer | ArrayBuffer | Buffer[] | string;
+
+  export class WebSocket {
+    static readonly OPEN: number;
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    on(event: "message", listener: (data: RawData) => void): this;
+    on(event: "close", listener: (code: number, reason: Buffer) => void): this;
+    on(event: "error", listener: (error: Error) => void): this;
+  }
+
+  export class WebSocketServer {
+    constructor(options: { host?: string; port: number });
+    on(event: "error", listener: (error: Error) => void): this;
+    on(event: "listening", listener: () => void): this;
+    on(event: "connection", listener: (ws: WebSocket, req: import("http").IncomingMessage) => void): this;
+    close(callback?: () => void): void;
+  }
+}

scripts/install.mjs

@@ -3,6 +3,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { execSync } from "node:child_process";
 
 const args = process.argv.slice(2);
 const mode = args.includes("--install") ? "install" : args.includes("--uninstall") ? "uninstall" : null;
@@ -15,9 +16,42 @@ if (!mode) {
 }
 
 const repoRoot = path.resolve(import.meta.dirname, "..");
-const pluginName = "Yonexus.Server";
+const pluginId = "yonexus-server";
 const sourceDist = path.join(repoRoot, "dist");
-const targetDir = path.join(profilePath, "plugins", pluginName);
+const targetDir = path.join(profilePath, "plugins", pluginId);
+
+function oc(cmd) {
+  try {
+    return execSync(`openclaw ${cmd}`, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch (e) {
+    console.error(`  ⚠ openclaw ${cmd}: ${e.stderr?.trim() || e.message}`);
+    return null;
+  }
+}
+
+function ensureInArray(configKey, value) {
+  const raw = oc(`config get ${configKey}`);
+  if (!raw) return;
+  const arr = JSON.parse(raw);
+  if (!arr.includes(value)) {
+    arr.push(value);
+    oc(`config set ${configKey} '${JSON.stringify(arr)}' --json`);
+    console.log(`  ✓ ${configKey} includes ${value}`);
+  } else {
+    console.log(`  ✓ ${configKey} already includes ${value}`);
+  }
+}
+
+function removeFromArray(configKey, value) {
+  const raw = oc(`config get ${configKey}`);
+  if (!raw) return;
+  const arr = JSON.parse(raw);
+  const filtered = arr.filter(v => v !== value);
+  if (filtered.length !== arr.length) {
+    oc(`config set ${configKey} '${JSON.stringify(filtered)}' --json`);
+    console.log(`  ✓ Removed ${value} from ${configKey}`);
+  }
+}
 
 if (mode === "install") {
   if (!fs.existsSync(sourceDist)) {
@@ -29,9 +63,17 @@ if (mode === "install") {
   fs.rmSync(targetDir, { recursive: true, force: true });
   fs.cpSync(sourceDist, path.join(targetDir, "dist"), { recursive: true });
   fs.copyFileSync(path.join(repoRoot, "plugin", "openclaw.plugin.json"), path.join(targetDir, "openclaw.plugin.json"));
-  console.log(`Installed ${pluginName} to ${targetDir}`);
+  fs.copyFileSync(path.join(repoRoot, "package.json"), path.join(targetDir, "package.json"));
+  console.log(`  ✓ Plugin files → ${targetDir}`);
+
+  ensureInArray("plugins.load.paths", targetDir);
+  ensureInArray("plugins.allow", pluginId);
+  console.log(`Installed ${pluginId} to ${targetDir}`);
   process.exit(0);
 }
 
+// uninstall
 fs.rmSync(targetDir, { recursive: true, force: true });
-console.log(`Removed ${pluginName} from ${targetDir}`);
+removeFromArray("plugins.load.paths", targetDir);
+removeFromArray("plugins.allow", pluginId);
+console.log(`Removed ${pluginId} from ${targetDir}`);

tests/auth-failures.test.ts

@@ -0,0 +1,705 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+import {
+  buildAuthRequest,
+  decodeBuiltin,
+  encodeBuiltin,
+  createAuthRequestSigningInput
+} from "../../Yonexus.Protocol/src/index.js";
+import { createYonexusServerRuntime } from "../plugin/core/runtime.js";
+import type { ClientRecord } from "../plugin/core/persistence.js";
+import type { YonexusServerStore } from "../plugin/core/store.js";
+import type { ClientConnection, ServerTransport } from "../plugin/core/transport.js";
+import { generateKeyPair, signMessage } from "../../Yonexus.Protocol/src/crypto.js";
+
+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((record) => [record.identifier, record]));
+
+  return {
+    filePath: "/tmp/yonexus-server-auth-failures.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 client of clients) {
+        persisted.set(client.identifier, client);
+      }
+    })
+  };
+}
+
+function createMockTransport() {
+  const sent: Array<{ connection: ClientConnection; message: string }> = [];
+
+  const transport: ServerTransport = {
+    isRunning: false,
+    connections: new Map(),
+    start: vi.fn(),
+    stop: vi.fn(),
+    send: vi.fn((identifier: string, message: string) => {
+      sent.push({ connection: { identifier } as ClientConnection, message });
+      return true;
+    }),
+    sendToConnection: vi.fn((connection: ClientConnection, message: string) => {
+      sent.push({ connection, message });
+      return true;
+    }),
+    broadcast: vi.fn(),
+    closeConnection: vi.fn(),
+    promoteToAuthenticated: vi.fn(),
+    removeTempConnection: vi.fn(),
+    assignIdentifierToTemp: vi.fn()
+  };
+
+  return { transport, sent };
+}
+
+async function buildSignedAuthRequest(options: {
+  identifier: string;
+  secret: string;
+  privateKey: string;
+  publicKey: string;
+  nonce: string;
+  proofTimestamp: number;
+  requestId?: string;
+  signatureOverride?: string;
+  publicKeyOverride?: string;
+}) {
+  const signature =
+    options.signatureOverride ??
+    (await signMessage(
+      options.privateKey,
+      createAuthRequestSigningInput({
+        secret: options.secret,
+        nonce: options.nonce,
+        proofTimestamp: options.proofTimestamp
+      })
+    ));
+
+  return encodeBuiltin(
+    buildAuthRequest(
+      {
+        identifier: options.identifier,
+        nonce: options.nonce,
+        proofTimestamp: options.proofTimestamp,
+        signature,
+        publicKey: options.publicKeyOverride ?? options.publicKey
+      },
+      { requestId: options.requestId, timestamp: options.proofTimestamp }
+    )
+  );
+}
+
+describe("YNX-1105c: Auth Failure Paths", () => {
+  let now = 1_710_000_000;
+
+  beforeEach(() => {
+    now = 1_710_000_000;
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("AF-01: unknown identifier returns auth_failed(unknown_identifier)", async () => {
+    const keyPair = await generateKeyPair();
+    const store = createMockStore([]);
+    const { transport, sent } = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("rogue-client");
+    await runtime.handleMessage(
+      connection,
+      await buildSignedAuthRequest({
+        identifier: "rogue-client",
+        secret: "shared-secret",
+        privateKey: keyPair.privateKey,
+        publicKey: keyPair.publicKey.trim(),
+        nonce: "NONCE1234567890123456789",
+        proofTimestamp: now,
+        requestId: "req-auth-unknown"
+      })
+    );
+
+    const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+    expect(lastMessage.type).toBe("auth_failed");
+    expect(lastMessage.payload).toMatchObject({
+      identifier: "rogue-client",
+      reason: "unknown_identifier"
+    });
+  });
+
+  it("AF-02: auth before pairing returns auth_failed(not_paired)", async () => {
+    const keyPair = await generateKeyPair();
+    const store = createMockStore([
+      {
+        identifier: "client-a",
+        pairingStatus: "unpaired",
+        status: "offline",
+        recentNonces: [],
+        recentHandshakeAttempts: [],
+        createdAt: now - 10,
+        updatedAt: now - 10
+      }
+    ]);
+    const { transport, sent } = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("client-a");
+    runtime.state.registry.sessions.set("client-a", {
+      identifier: "client-a",
+      socket: connection.ws,
+      isAuthenticated: false,
+      connectedAt: now,
+      lastActivityAt: now,
+      publicKey: keyPair.publicKey.trim()
+    });
+
+    await runtime.handleMessage(
+      connection,
+      await buildSignedAuthRequest({
+        identifier: "client-a",
+        secret: "shared-secret",
+        privateKey: keyPair.privateKey,
+        publicKey: keyPair.publicKey.trim(),
+        nonce: "NONCE1234567890123456789",
+        proofTimestamp: now,
+        requestId: "req-auth-not-paired"
+      })
+    );
+
+    const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+    expect(lastMessage.type).toBe("auth_failed");
+    expect(lastMessage.payload).toMatchObject({ identifier: "client-a", reason: "not_paired" });
+  });
+
+  it("AF-03: invalid signature returns auth_failed(invalid_signature)", async () => {
+    const keyPair = await generateKeyPair();
+    const wrongKeyPair = await generateKeyPair();
+    const store = createMockStore([
+      {
+        identifier: "client-a",
+        pairingStatus: "paired",
+        publicKey: keyPair.publicKey.trim(),
+        secret: "shared-secret",
+        status: "offline",
+        recentNonces: [],
+        recentHandshakeAttempts: [],
+        createdAt: now - 10,
+        updatedAt: now - 10
+      }
+    ]);
+    const { transport, sent } = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("client-a");
+    runtime.state.registry.sessions.set("client-a", {
+      identifier: "client-a",
+      socket: connection.ws,
+      isAuthenticated: false,
+      connectedAt: now,
+      lastActivityAt: now,
+      publicKey: keyPair.publicKey.trim()
+    });
+
+    await runtime.handleMessage(
+      connection,
+      await buildSignedAuthRequest({
+        identifier: "client-a",
+        secret: "shared-secret",
+        privateKey: wrongKeyPair.privateKey,
+        publicKey: keyPair.publicKey.trim(),
+        nonce: "NONCE1234567890123456789",
+        proofTimestamp: now,
+        requestId: "req-auth-invalid-signature"
+      })
+    );
+
+    const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+    expect(lastMessage.type).toBe("auth_failed");
+    expect(lastMessage.payload).toMatchObject({ identifier: "client-a", reason: "invalid_signature" });
+  });
+
+  it("AF-05: stale timestamp returns auth_failed(stale_timestamp)", async () => {
+    const keyPair = await generateKeyPair();
+    const store = createMockStore([
+      {
+        identifier: "client-a",
+        pairingStatus: "paired",
+        publicKey: keyPair.publicKey.trim(),
+        secret: "shared-secret",
+        status: "offline",
+        recentNonces: [],
+        recentHandshakeAttempts: [],
+        createdAt: now - 20,
+        updatedAt: now - 20
+      }
+    ]);
+    const { transport, sent } = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("client-a");
+    runtime.state.registry.sessions.set("client-a", {
+      identifier: "client-a",
+      socket: connection.ws,
+      isAuthenticated: false,
+      connectedAt: now,
+      lastActivityAt: now,
+      publicKey: keyPair.publicKey.trim()
+    });
+
+    await runtime.handleMessage(
+      connection,
+      await buildSignedAuthRequest({
+        identifier: "client-a",
+        secret: "shared-secret",
+        privateKey: keyPair.privateKey,
+        publicKey: keyPair.publicKey.trim(),
+        nonce: "NONCE1234567890123456789",
+        proofTimestamp: now - 11,
+        requestId: "req-auth-stale"
+      })
+    );
+
+    const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+    expect(lastMessage.type).toBe("auth_failed");
+    expect(lastMessage.payload).toMatchObject({ identifier: "client-a", reason: "stale_timestamp" });
+  });
+
+  it("AF-06: future timestamp returns auth_failed(future_timestamp)", async () => {
+    const keyPair = await generateKeyPair();
+    const store = createMockStore([
+      {
+        identifier: "client-a",
+        pairingStatus: "paired",
+        publicKey: keyPair.publicKey.trim(),
+        secret: "shared-secret",
+        status: "offline",
+        recentNonces: [],
+        recentHandshakeAttempts: [],
+        createdAt: now - 20,
+        updatedAt: now - 20
+      }
+    ]);
+    const { transport, sent } = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("client-a");
+    runtime.state.registry.sessions.set("client-a", {
+      identifier: "client-a",
+      socket: connection.ws,
+      isAuthenticated: false,
+      connectedAt: now,
+      lastActivityAt: now,
+      publicKey: keyPair.publicKey.trim()
+    });
+
+    await runtime.handleMessage(
+      connection,
+      await buildSignedAuthRequest({
+        identifier: "client-a",
+        secret: "shared-secret",
+        privateKey: keyPair.privateKey,
+        publicKey: keyPair.publicKey.trim(),
+        nonce: "NONCE1234567890123456789",
+        proofTimestamp: now + 11,
+        requestId: "req-auth-future"
+      })
+    );
+
+    const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+    expect(lastMessage.type).toBe("auth_failed");
+    expect(lastMessage.payload).toMatchObject({ identifier: "client-a", reason: "future_timestamp" });
+  });
+
+  it("AF-07: nonce collision triggers re_pair_required", async () => {
+    const keyPair = await generateKeyPair();
+    const store = createMockStore([
+      {
+        identifier: "client-a",
+        pairingStatus: "paired",
+        publicKey: keyPair.publicKey.trim(),
+        secret: "shared-secret",
+        status: "offline",
+        recentNonces: [],
+        recentHandshakeAttempts: [],
+        createdAt: now - 10,
+        updatedAt: now - 10
+      }
+    ]);
+    const { transport, sent } = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("client-a");
+    runtime.state.registry.sessions.set("client-a", {
+      identifier: "client-a",
+      socket: connection.ws,
+      isAuthenticated: false,
+      connectedAt: now,
+      lastActivityAt: now,
+      publicKey: keyPair.publicKey.trim()
+    });
+
+    const nonce = "NONCE1234567890123456789";
+
+    await runtime.handleMessage(
+      connection,
+      await buildSignedAuthRequest({
+        identifier: "client-a",
+        secret: "shared-secret",
+        privateKey: keyPair.privateKey,
+        publicKey: keyPair.publicKey.trim(),
+        nonce,
+        proofTimestamp: now,
+        requestId: "req-auth-1"
+      })
+    );
+
+    now += 1;
+
+    await runtime.handleMessage(
+      connection,
+      await buildSignedAuthRequest({
+        identifier: "client-a",
+        secret: "shared-secret",
+        privateKey: keyPair.privateKey,
+        publicKey: keyPair.publicKey.trim(),
+        nonce,
+        proofTimestamp: now,
+        requestId: "req-auth-2"
+      })
+    );
+
+    const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+    expect(lastMessage.type).toBe("re_pair_required");
+    expect(lastMessage.payload).toMatchObject({ identifier: "client-a", reason: "nonce_collision" });
+
+    const record = runtime.state.registry.clients.get("client-a");
+    expect(record?.secret).toBeUndefined();
+    expect(record?.pairingStatus).toBe("revoked");
+  });
+
+  it("AF-08: rate limit triggers re_pair_required", async () => {
+    const keyPair = await generateKeyPair();
+    const store = createMockStore([
+      {
+        identifier: "client-a",
+        pairingStatus: "paired",
+        publicKey: keyPair.publicKey.trim(),
+        secret: "shared-secret",
+        status: "offline",
+        recentNonces: [],
+        recentHandshakeAttempts: Array.from({ length: 10 }, () => now - 1),
+        createdAt: now - 10,
+        updatedAt: now - 10
+      }
+    ]);
+    const { transport, sent } = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("client-a");
+    runtime.state.registry.sessions.set("client-a", {
+      identifier: "client-a",
+      socket: connection.ws,
+      isAuthenticated: false,
+      connectedAt: now,
+      lastActivityAt: now,
+      publicKey: keyPair.publicKey.trim()
+    });
+
+    await runtime.handleMessage(
+      connection,
+      await buildSignedAuthRequest({
+        identifier: "client-a",
+        secret: "shared-secret",
+        privateKey: keyPair.privateKey,
+        publicKey: keyPair.publicKey.trim(),
+        nonce: "NONCE9876543210987654321",
+        proofTimestamp: now,
+        requestId: "req-auth-rate-limit"
+      })
+    );
+
+    const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+    expect(lastMessage.type).toBe("re_pair_required");
+    expect(lastMessage.payload).toMatchObject({ identifier: "client-a", reason: "rate_limited" });
+
+    const record = runtime.state.registry.clients.get("client-a");
+    expect(record?.secret).toBeUndefined();
+    expect(record?.pairingStatus).toBe("revoked");
+  });
+
+  it("AF-09: wrong public key returns auth_failed(invalid_signature)", async () => {
+    const keyPair = await generateKeyPair();
+    const rotatedKeyPair = await generateKeyPair();
+    const store = createMockStore([
+      {
+        identifier: "client-a",
+        pairingStatus: "paired",
+        publicKey: keyPair.publicKey.trim(),
+        secret: "shared-secret",
+        status: "offline",
+        recentNonces: [],
+        recentHandshakeAttempts: [],
+        createdAt: now - 10,
+        updatedAt: now - 10
+      }
+    ]);
+    const { transport, sent } = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("client-a");
+    runtime.state.registry.sessions.set("client-a", {
+      identifier: "client-a",
+      socket: connection.ws,
+      isAuthenticated: false,
+      connectedAt: now,
+      lastActivityAt: now,
+      publicKey: keyPair.publicKey.trim()
+    });
+
+    await runtime.handleMessage(
+      connection,
+      await buildSignedAuthRequest({
+        identifier: "client-a",
+        secret: "shared-secret",
+        privateKey: rotatedKeyPair.privateKey,
+        publicKey: keyPair.publicKey.trim(),
+        publicKeyOverride: rotatedKeyPair.publicKey.trim(),
+        nonce: "NONCE1234567890123456789",
+        proofTimestamp: now,
+        requestId: "req-auth-wrong-public-key"
+      })
+    );
+
+    const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+    expect(lastMessage.type).toBe("auth_failed");
+    expect(lastMessage.payload).toMatchObject({ identifier: "client-a", reason: "invalid_signature" });
+  });
+
+  it("AF-10: malformed auth_request payload returns protocol error", async () => {
+    const store = createMockStore([]);
+    const { transport, sent } = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("client-a");
+    await runtime.handleMessage(
+      connection,
+      encodeBuiltin({
+        type: "auth_request",
+        requestId: "req-auth-malformed",
+        timestamp: now
+      })
+    );
+
+    const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+    expect(lastMessage.type).toBe("error");
+    expect(lastMessage.payload).toMatchObject({
+      code: "MALFORMED_MESSAGE",
+      message: "auth_request payload is required"
+    });
+  });
+
+  it("AF-11: tampered signature returns auth_failed(invalid_signature)", async () => {
+    const keyPair = await generateKeyPair();
+    const store = createMockStore([
+      {
+        identifier: "client-a",
+        pairingStatus: "paired",
+        publicKey: keyPair.publicKey.trim(),
+        secret: "shared-secret",
+        status: "offline",
+        recentNonces: [],
+        recentHandshakeAttempts: [],
+        createdAt: now - 10,
+        updatedAt: now - 10
+      }
+    ]);
+    const { transport, sent } = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("client-a");
+    runtime.state.registry.sessions.set("client-a", {
+      identifier: "client-a",
+      socket: connection.ws,
+      isAuthenticated: false,
+      connectedAt: now,
+      lastActivityAt: now,
+      publicKey: keyPair.publicKey.trim()
+    });
+
+    const validMessage = decodeBuiltin(
+      await buildSignedAuthRequest({
+        identifier: "client-a",
+        secret: "shared-secret",
+        privateKey: keyPair.privateKey,
+        publicKey: keyPair.publicKey.trim(),
+        nonce: "NONCE1234567890123456789",
+        proofTimestamp: now,
+        requestId: "req-auth-tampered"
+      })
+    );
+
+    await runtime.handleMessage(
+      connection,
+      encodeBuiltin({
+        ...validMessage,
+        payload: {
+          ...validMessage.payload,
+          signature: `A${String(validMessage.payload?.signature).slice(1)}`
+        }
+      })
+    );
+
+    const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+    expect(lastMessage.type).toBe("auth_failed");
+    expect(lastMessage.payload).toMatchObject({ identifier: "client-a", reason: "invalid_signature" });
+  });
+});

tests/connection-heartbeat-failures.test.ts

@@ -0,0 +1,297 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+import {
+  buildHeartbeat,
+  buildHello,
+  decodeBuiltin,
+  encodeBuiltin,
+  YONEXUS_PROTOCOL_VERSION
+} from "../../Yonexus.Protocol/src/index.js";
+import { createYonexusServerRuntime } from "../plugin/core/runtime.js";
+import { createClientRecord, type ClientRecord } from "../plugin/core/persistence.js";
+import type { YonexusServerStore } from "../plugin/core/store.js";
+import type { ClientConnection, ServerTransport } from "../plugin/core/transport.js";
+
+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((record) => [record.identifier, record]));
+
+  return {
+    filePath: "/tmp/yonexus-server-connection-heartbeat-failures.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 client of clients) {
+        persisted.set(client.identifier, client);
+      }
+    })
+  };
+}
+
+function createMockTransport() {
+  const sent: Array<{ connection: ClientConnection; message: string }> = [];
+  const tempAssignments = new Map<ClientConnection["ws"], string>();
+  const connections = new Map<string, ClientConnection>();
+
+  const transport: ServerTransport = {
+    isRunning: false,
+    connections,
+    start: vi.fn(),
+    stop: vi.fn(),
+    send: vi.fn(),
+    sendToConnection: vi.fn((connection: ClientConnection, message: string) => {
+      sent.push({ connection, message });
+      return true;
+    }),
+    broadcast: vi.fn(),
+    closeConnection: vi.fn(),
+    promoteToAuthenticated: vi.fn((identifier: string, ws: ClientConnection["ws"]) => {
+      if (!tempAssignments.has(ws)) {
+        return false;
+      }
+
+      const existing = connections.get(identifier);
+      if (existing) {
+        existing.ws.close(1008, "Connection replaced by new authenticated session");
+      }
+
+      connections.set(identifier, {
+        identifier,
+        ws,
+        connectedAt: 1_710_000_000,
+        isAuthenticated: true
+      });
+      tempAssignments.delete(ws);
+      return true;
+    }),
+    removeTempConnection: vi.fn((ws: ClientConnection["ws"]) => {
+      tempAssignments.delete(ws);
+    }),
+    assignIdentifierToTemp: vi.fn((ws: ClientConnection["ws"], identifier: string) => {
+      tempAssignments.set(ws, identifier);
+    })
+  };
+
+  return { transport, sent };
+}
+
+describe("YNX-1105d: Connection & Heartbeat Failure Paths", () => {
+  let now = 1_710_000_000;
+
+  beforeEach(() => {
+    now = 1_710_000_000;
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("CF-06: unauthenticated rule message closes connection", async () => {
+    const record = createClientRecord("client-a");
+    const store = createMockStore([record]);
+    const { transport } = createMockTransport();
+
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("client-a");
+    runtime.state.registry.sessions.set("client-a", {
+      identifier: "client-a",
+      socket: connection.ws,
+      isAuthenticated: false,
+      connectedAt: now,
+      lastActivityAt: now,
+      publicKey: undefined
+    });
+
+    await runtime.handleMessage(connection, "chat::hello");
+
+    expect(connection.ws.close).toHaveBeenCalledWith(1008, "Not authenticated");
+  });
+
+  it("HF-03: heartbeat before auth returns error", async () => {
+    const record = createClientRecord("client-a");
+    const store = createMockStore([record]);
+    const { transport, sent } = createMockTransport();
+
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("client-a");
+    runtime.state.registry.sessions.set("client-a", {
+      identifier: "client-a",
+      socket: connection.ws,
+      isAuthenticated: false,
+      connectedAt: now,
+      lastActivityAt: now,
+      publicKey: undefined
+    });
+
+    await runtime.handleMessage(
+      connection,
+      encodeBuiltin(
+        buildHeartbeat(
+          { identifier: "client-a", status: "alive" },
+          { requestId: "req-hb-early", timestamp: now }
+        )
+      )
+    );
+
+    const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+    expect(lastMessage.type).toBe("error");
+    expect(lastMessage.payload).toMatchObject({
+      code: "AUTH_FAILED"
+    });
+  });
+
+  it("HF-04: heartbeat without session returns error", async () => {
+    const record = createClientRecord("client-a");
+    const store = createMockStore([record]);
+    const { transport, sent } = createMockTransport();
+
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("client-a");
+
+    await runtime.handleMessage(
+      connection,
+      encodeBuiltin(
+        buildHeartbeat(
+          { identifier: "client-a", status: "alive" },
+          { requestId: "req-hb-unauth", timestamp: now }
+        )
+      )
+    );
+
+    const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+    expect(lastMessage.type).toBe("error");
+    expect(lastMessage.payload).toMatchObject({
+      code: "AUTH_FAILED"
+    });
+  });
+
+  it("CF-04: protocol version mismatch returns error and closes the connection", async () => {
+    const record = createClientRecord("client-a");
+    const store = createMockStore([record]);
+    const { transport, sent } = createMockTransport();
+
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection();
+    await runtime.handleMessage(
+      connection,
+      encodeBuiltin(
+        buildHello(
+          {
+            identifier: "client-a",
+            hasSecret: false,
+            hasKeyPair: false,
+            protocolVersion: `${YONEXUS_PROTOCOL_VERSION}-unsupported`
+          },
+          { requestId: "req-hello-version", timestamp: now }
+        )
+      )
+    );
+
+    const lastMessage = decodeBuiltin(sent.at(-1)!.message);
+    expect(lastMessage.type).toBe("error");
+    expect(lastMessage.payload).toMatchObject({
+      code: "UNSUPPORTED_PROTOCOL_VERSION"
+    });
+    expect(connection.ws.close).toHaveBeenCalledWith(1002, "Unsupported protocol version");
+  });
+
+  it("CF-03: promoting a new authenticated connection replaces the old one", async () => {
+    const previousSocket = createMockSocket();
+    const replacementSocket = createMockSocket();
+    const previousConnection = {
+      identifier: "client-a",
+      ws: previousSocket,
+      connectedAt: now - 5,
+      isAuthenticated: true
+    } satisfies ClientConnection;
+
+    const { transport } = createMockTransport();
+    transport.connections.set("client-a", previousConnection);
+
+    transport.assignIdentifierToTemp(replacementSocket, "client-a");
+    const promoted = transport.promoteToAuthenticated("client-a", replacementSocket);
+
+    expect(promoted).toBe(true);
+    expect(previousSocket.close).toHaveBeenCalledWith(
+      1008,
+      "Connection replaced by new authenticated session"
+    );
+
+    const activeConnection = transport.connections.get("client-a");
+    expect(activeConnection?.ws).toBe(replacementSocket);
+    expect(activeConnection?.isAuthenticated).toBe(true);
+  });
+});

tests/notifications.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  createDiscordNotificationService,
+  formatPairingMessage,
+  type DiscordFetch
+} from "../plugin/notifications/discord.js";
+
+const request = {
+  identifier: "client-a",
+  pairingCode: "PAIR-1234-CODE",
+  expiresAt: 1_710_000_300,
+  ttlSeconds: 300,
+  createdAt: 1_710_000_000
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("Discord notification service", () => {
+  it("formats pairing requests as a DM-friendly message", () => {
+    const message = formatPairingMessage(request);
+
+    expect(message).toContain("Yonexus Pairing Request");
+    expect(message).toContain("`client-a`");
+    expect(message).toContain("`PAIR-1234-CODE`");
+    expect(message).toContain("TTL:** 300 seconds");
+  });
+
+  it("creates a DM channel and posts the pairing message", async () => {
+    const fetcher = vi
+      .fn<DiscordFetch>()
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({ id: "dm-channel-1" })
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({ id: "message-1" })
+      });
+
+    const service = createDiscordNotificationService(
+      {
+        botToken: "discord-bot-token",
+        adminUserId: "123456789012345678"
+      },
+      { fetcher }
+    );
+
+    await expect(service.sendPairingNotification(request)).resolves.toBe(true);
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(fetcher).toHaveBeenNthCalledWith(
+      1,
+      "https://discord.com/api/v10/users/@me/channels",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          Authorization: "Bot discord-bot-token"
+        }),
+        body: JSON.stringify({ recipient_id: "123456789012345678" })
+      })
+    );
+    expect(fetcher).toHaveBeenNthCalledWith(
+      2,
+      "https://discord.com/api/v10/channels/dm-channel-1/messages",
+      expect.objectContaining({
+        method: "POST"
+      })
+    );
+  });
+
+  it("returns false when Discord rejects DM channel creation", async () => {
+    const fetcher = vi.fn<DiscordFetch>().mockResolvedValueOnce({
+      ok: false,
+      status: 403,
+      json: async () => ({ message: "Missing Access" })
+    });
+
+    const service = createDiscordNotificationService(
+      {
+        botToken: "discord-bot-token",
+        adminUserId: "123456789012345678"
+      },
+      { fetcher }
+    );
+
+    await expect(service.sendPairingNotification(request)).resolves.toBe(false);
+    expect(fetcher).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns false when config is missing required Discord credentials", async () => {
+    const fetcher = vi.fn<DiscordFetch>();
+    const service = createDiscordNotificationService(
+      {
+        botToken: "",
+        adminUserId: ""
+      },
+      { fetcher }
+    );
+
+    await expect(service.sendPairingNotification(request)).resolves.toBe(false);
+    expect(fetcher).not.toHaveBeenCalled();
+  });
+});

tests/pairing-auth-liveness.test.ts

@@ -0,0 +1,486 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createClientRecord, type ClientRecord } from "../plugin/core/persistence.js";
+import { createServerRuleRegistry, ServerRuleRegistryError } from "../plugin/core/rules.js";
+import { createPairingService } from "../plugin/services/pairing.js";
+
+// Inline protocol helpers (to avoid submodule dependency in tests)
+function createAuthRequestSigningInput(input: {
+  secret: string;
+  nonce: string;
+  proofTimestamp: number;
+}): string {
+  return JSON.stringify({
+    secret: input.secret,
+    nonce: input.nonce,
+    timestamp: input.proofTimestamp
+  });
+}
+
+function isTimestampFresh(
+  proofTimestamp: number,
+  now: number,
+  maxDriftSeconds: number = 10
+): { ok: true } | { ok: false; reason: "stale_timestamp" | "future_timestamp" } {
+  const drift = proofTimestamp - now;
+  if (Math.abs(drift) < maxDriftSeconds) {
+    return { ok: true };
+  }
+  return { ok: false, reason: drift < 0 ? "stale_timestamp" : "future_timestamp" };
+}
+
+describe("Yonexus.Server PairingService", () => {
+  it("creates a pending pairing request with ttl metadata", () => {
+    const record = createClientRecord("client-a");
+    const pairing = createPairingService({ now: () => 1_710_000_000 });
+
+    const request = pairing.createPairingRequest(record, { ttlSeconds: 180 });
+
+    expect(request.identifier).toBe("client-a");
+    expect(request.ttlSeconds).toBe(180);
+    expect(request.expiresAt).toBe(1_710_000_180);
+    expect(record.pairingStatus).toBe("pending");
+    expect(record.pairingCode).toBe(request.pairingCode);
+    expect(record.pairingNotifyStatus).toBe("pending");
+  });
+
+  it("confirms a valid pairing and clears pairing-only fields", () => {
+    const record = createClientRecord("client-a");
+    const pairing = createPairingService({ now: () => 1_710_000_100 });
+    const request = pairing.createPairingRequest(record, { ttlSeconds: 300 });
+
+    const result = pairing.confirmPairing(record, request.pairingCode);
+
+    expect(result).toMatchObject({
+      success: true,
+      pairedAt: 1_710_000_100
+    });
+    expect(typeof result.secret).toBe("string");
+    expect(record.pairingStatus).toBe("paired");
+    expect(record.secret).toBe(result.secret);
+    expect(record.pairingCode).toBeUndefined();
+    expect(record.pairingExpiresAt).toBeUndefined();
+    expect(record.pairingNotifyStatus).toBeUndefined();
+  });
+
+  it("rejects expired and invalid pairing confirmations without dirtying state", () => {
+    const record = createClientRecord("client-a");
+    let now = 1_710_000_000;
+    const pairing = createPairingService({ now: () => now });
+    const request = pairing.createPairingRequest(record, { ttlSeconds: 60 });
+
+    const invalid = pairing.confirmPairing(record, "WRONG-CODE-000");
+    expect(invalid).toEqual({ success: false, reason: "invalid_code" });
+    expect(record.pairingStatus).toBe("pending");
+    expect(record.pairingCode).toBe(request.pairingCode);
+
+    now = 1_710_000_100;
+    const expired = pairing.confirmPairing(record, request.pairingCode);
+    expect(expired).toEqual({ success: false, reason: "expired" });
+    expect(record.pairingStatus).toBe("unpaired");
+    expect(record.pairingCode).toBeUndefined();
+  });
+
+  it("marks notification delivery state transitions", () => {
+    const record = createClientRecord("client-a");
+    const pairing = createPairingService({ now: () => 1_710_000_000 });
+    pairing.createPairingRequest(record);
+
+    pairing.markNotificationSent(record);
+    expect(record.pairingNotifyStatus).toBe("sent");
+    expect(record.pairingNotifiedAt).toBe(1_710_000_000);
+
+    pairing.markNotificationFailed(record);
+    expect(record.pairingNotifyStatus).toBe("failed");
+  });
+});
+
+describe("Yonexus.Server RuleRegistry", () => {
+  it("dispatches exact-match rewritten messages to the registered processor", () => {
+    const registry = createServerRuleRegistry();
+    const processor = vi.fn();
+    registry.registerRule("chat_sync", processor);
+
+    const handled = registry.dispatch("chat_sync::client-a::{\"body\":\"hello\"}");
+
+    expect(handled).toBe(true);
+    expect(processor).toHaveBeenCalledWith("chat_sync::client-a::{\"body\":\"hello\"}");
+    expect(registry.hasRule("chat_sync")).toBe(true);
+    expect(registry.getRules()).toEqual(["chat_sync"]);
+  });
+
+  it("rejects reserved and duplicate rule registrations", () => {
+    const registry = createServerRuleRegistry();
+    registry.registerRule("chat_sync", () => undefined);
+
+    expect(() => registry.registerRule("builtin", () => undefined)).toThrow(ServerRuleRegistryError);
+    expect(() => registry.registerRule("chat_sync", () => undefined)).toThrow(
+      "Rule 'chat_sync' is already registered"
+    );
+  });
+
+  it("returns false when no processor matches a rewritten message", () => {
+    const registry = createServerRuleRegistry();
+
+    expect(registry.dispatch("chat_sync::client-a::{\"body\":\"hello\"}")).toBe(false);
+  });
+});
+
+describe("Yonexus.Server Auth Service", () => {
+  it("verifies valid auth request payload", () => {
+    const record = createClientRecord("client-a");
+    record.pairingStatus = "paired";
+    record.publicKey = "test-pk";
+    record.secret = "test-secret";
+
+    const nonce = "RANDOM24CHARACTERSTRINGX";
+    const timestamp = 1_710_000_000;
+    const signingInput = createAuthRequestSigningInput({
+      secret: "test-secret",
+      nonce,
+      proofTimestamp: timestamp
+    });
+
+    // Mock signature verification (in real impl would use crypto)
+    const mockSignature = `signed:${signingInput}`;
+
+    const result = verifyAuthRequest(
+      record,
+      {
+        identifier: "client-a",
+        nonce,
+        proofTimestamp: timestamp,
+        signature: mockSignature,
+        publicKey: "test-pk"
+      },
+      {
+        now: () => timestamp,
+        verifySignature: (sig, input) => sig === `signed:${input}`
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result).toHaveProperty("authenticatedAt");
+  });
+
+  it("rejects auth for unpaired client", () => {
+    const record = createClientRecord("client-a");
+
+    const result = verifyAuthRequest(
+      record,
+      {
+        identifier: "client-a",
+        nonce: "RANDOM24CHARACTERSTRINGX",
+        proofTimestamp: 1_710_000_000,
+        signature: "sig",
+        publicKey: "pk"
+      },
+      { now: () => 1_710_000_000 }
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.reason).toBe("not_paired");
+  });
+
+  it("rejects auth with mismatched public key", () => {
+    const record = createClientRecord("client-a");
+    record.pairingStatus = "paired";
+    record.publicKey = "expected-pk";
+    record.secret = "secret";
+
+    const result = verifyAuthRequest(
+      record,
+      {
+        identifier: "client-a",
+        nonce: "RANDOM24CHARACTERSTRINGX",
+        proofTimestamp: 1_710_000_000,
+        signature: "sig",
+        publicKey: "different-pk"
+      },
+      { now: () => 1_710_000_000 }
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.reason).toBe("public_key_mismatch");
+  });
+
+  it("rejects auth with stale timestamp", () => {
+    const record = createClientRecord("client-a");
+    record.pairingStatus = "paired";
+    record.publicKey = "pk";
+    record.secret = "secret";
+
+    const result = verifyAuthRequest(
+      record,
+      {
+        identifier: "client-a",
+        nonce: "RANDOM24CHARACTERSTRINGX",
+        proofTimestamp: 1_710_000_000,
+        signature: "sig",
+        publicKey: "pk"
+      },
+      {
+        now: () => 1_710_000_100
+      }
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.reason).toBe("stale_timestamp");
+  });
+
+  it("rejects auth with future timestamp", () => {
+    const record = createClientRecord("client-a");
+    record.pairingStatus = "paired";
+    record.publicKey = "pk";
+    record.secret = "secret";
+
+    const result = verifyAuthRequest(
+      record,
+      {
+        identifier: "client-a",
+        nonce: "RANDOM24CHARACTERSTRINGX",
+        proofTimestamp: 1_710_000_100,
+        signature: "sig",
+        publicKey: "pk"
+      },
+      { now: () => 1_710_000_000 }
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.reason).toBe("future_timestamp");
+  });
+
+  it("rejects auth with nonce collision", () => {
+    const record = createClientRecord("client-a");
+    record.pairingStatus = "paired";
+    record.publicKey = "pk";
+    record.secret = "secret";
+    record.recentNonces = [{ nonce: "COLLIDING24CHARSTRINGX", timestamp: 1_710_000_000 }];
+
+    const result = verifyAuthRequest(
+      record,
+      {
+        identifier: "client-a",
+        nonce: "COLLIDING24CHARSTRINGX",
+        proofTimestamp: 1_710_000_010,
+        signature: "sig",
+        publicKey: "pk"
+      },
+      { now: () => 1_710_000_010 }
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.reason).toBe("nonce_collision");
+  });
+
+  it("rejects auth with rate limit exceeded", () => {
+    const record = createClientRecord("client-a");
+    record.pairingStatus = "paired";
+    record.publicKey = "pk";
+    record.secret = "secret";
+    const now = 1_710_000_000;
+    record.recentHandshakeAttempts = Array(11).fill(now - 5);
+
+    const result = verifyAuthRequest(
+      record,
+      {
+        identifier: "client-a",
+        nonce: "RANDOM24CHARSTRINGX01",
+        proofTimestamp: now,
+        signature: "sig",
+        publicKey: "pk"
+      },
+      { now: () => now }
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.reason).toBe("rate_limited");
+  });
+
+  it("invalid signature triggers re_pair_required", () => {
+    const record = createClientRecord("client-a");
+    record.pairingStatus = "paired";
+    record.publicKey = "pk";
+    record.secret = "secret";
+
+    const result = verifyAuthRequest(
+      record,
+      {
+        identifier: "client-a",
+        nonce: "RANDOM24CHARSTRINGX01",
+        proofTimestamp: 1_710_000_000,
+        signature: "invalid-sig",
+        publicKey: "pk"
+      },
+      {
+        now: () => 1_710_000_000,
+        verifySignature: () => false
+      }
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.reason).toBe("re_pair_required");
+  });
+
+  it("tracks successful auth attempt in record", () => {
+    const record = createClientRecord("client-a");
+    record.pairingStatus = "paired";
+    record.publicKey = "pk";
+    record.secret = "secret";
+
+    const now = 1_710_000_000;
+    const nonce = "RANDOM24CHARSTRINGX01";
+
+    const signingInput = createAuthRequestSigningInput({
+      secret: "secret",
+      nonce,
+      proofTimestamp: now
+    });
+
+    const result = verifyAuthRequest(
+      record,
+      {
+        identifier: "client-a",
+        nonce,
+        proofTimestamp: now,
+        signature: `signed:${signingInput}`,
+        publicKey: "pk"
+      },
+      {
+        now: () => now,
+        verifySignature: (sig, input) => sig === `signed:${input}`
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(record.recentNonces).toContainEqual({ nonce, timestamp: now });
+    expect(record.recentHandshakeAttempts).toContain(now);
+    expect(record.lastAuthenticatedAt).toBe(now);
+  });
+});
+
+describe("Yonexus.Server Heartbeat / Liveness", () => {
+  it("evaluates client online when recent heartbeat exists", () => {
+    const record = createClientRecord("client-a");
+    record.lastHeartbeatAt = 1_710_000_000;
+    record.status = "online";
+
+    const status = evaluateLiveness(record, { now: () => 1_710_000_300 });
+    expect(status).toBe("online");
+  });
+
+  it("evaluates client unstable after 7 minutes without heartbeat", () => {
+    const record = createClientRecord("client-a");
+    record.lastHeartbeatAt = 1_710_000_000;
+    record.status = "online";
+
+    const status = evaluateLiveness(record, { now: () => 1_710_000_420 });
+    expect(status).toBe("unstable");
+  });
+
+  it("evaluates client offline after 11 minutes without heartbeat", () => {
+    const record = createClientRecord("client-a");
+    record.lastHeartbeatAt = 1_710_000_000;
+    record.status = "online";
+
+    const status = evaluateLiveness(record, { now: () => 1_710_000_660 });
+    expect(status).toBe("offline");
+  });
+
+  it("handles client with no heartbeat record", () => {
+    const record = createClientRecord("client-a");
+
+    const status = evaluateLiveness(record, { now: () => 1_710_000_000 });
+    expect(status).toBe("offline");
+  });
+});
+
+function evaluateLiveness(
+  record: ReturnType<typeof createClientRecord>,
+  options: { now: () => number }
+): "online" | "unstable" | "offline" {
+  const now = options.now();
+  const lastHeartbeat = record.lastHeartbeatAt;
+
+  if (!lastHeartbeat) {
+    return "offline";
+  }
+
+  const elapsed = now - lastHeartbeat;
+
+  if (elapsed >= 11 * 60) {
+    return "offline";
+  }
+  if (elapsed >= 7 * 60) {
+    return "unstable";
+  }
+  return "online";
+}
+
+interface AuthRequestPayload {
+  identifier: string;
+  nonce: string;
+  proofTimestamp: number;
+  signature: string;
+  publicKey?: string;
+}
+
+interface AuthVerifyResult {
+  success: boolean;
+  reason?: string;
+  authenticatedAt?: number;
+}
+
+function verifyAuthRequest(
+  record: ClientRecord,
+  payload: AuthRequestPayload,
+  options: {
+    now: () => number;
+    verifySignature?: (signature: string, input: string) => boolean;
+  }
+): AuthVerifyResult {
+  if (record.pairingStatus !== "paired") {
+    return { success: false, reason: "not_paired" };
+  }
+
+  if (payload.publicKey && record.publicKey !== payload.publicKey) {
+    return { success: false, reason: "public_key_mismatch" };
+  }
+
+  const timestampCheck = isTimestampFresh(payload.proofTimestamp, options.now());
+  if (!timestampCheck.ok) {
+    return { success: false, reason: timestampCheck.reason };
+  }
+
+  const nonceCollision = record.recentNonces.some((n) => n.nonce === payload.nonce);
+  if (nonceCollision) {
+    return { success: false, reason: "nonce_collision" };
+  }
+
+  const now = options.now();
+  const recentAttempts = record.recentHandshakeAttempts.filter((t) => now - t < 10_000);
+  if (recentAttempts.length >= 10) {
+    return { success: false, reason: "rate_limited" };
+  }
+
+  const signingInput = createAuthRequestSigningInput({
+    secret: record.secret!,
+    nonce: payload.nonce,
+    proofTimestamp: payload.proofTimestamp
+  });
+
+  const isValidSignature = options.verifySignature?.(payload.signature, signingInput) ?? true;
+  if (!isValidSignature) {
+    return { success: false, reason: "re_pair_required" };
+  }
+
+  record.recentNonces.push({ nonce: payload.nonce, timestamp: now });
+  if (record.recentNonces.length > 10) {
+    record.recentNonces.shift();
+  }
+  record.recentHandshakeAttempts.push(now);
+  record.lastAuthenticatedAt = now;
+  record.lastHeartbeatAt = now;
+
+  return { success: true, authenticatedAt: now };
+}

tests/runtime-flow.test.ts

@@ -0,0 +1,448 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  buildAuthRequest,
+  buildHeartbeat,
+  buildHello,
+  buildPairConfirm,
+  createAuthRequestSigningInput,
+  decodeBuiltin,
+  encodeBuiltin,
+  type AuthRequestPayload,
+  type BuiltinEnvelope,
+  type PairRequestPayload,
+  YONEXUS_PROTOCOL_VERSION
+} from "../../Yonexus.Protocol/src/index.js";
+import { createYonexusServerRuntime } from "../plugin/core/runtime.js";
+import type { ClientRecord } from "../plugin/core/persistence.js";
+import type { YonexusServerStore } from "../plugin/core/store.js";
+import type { ClientConnection, ServerTransport } from "../plugin/core/transport.js";
+import { generateKeyPair, signMessage, verifySignature } from "../../Yonexus.Protocol/src/crypto.js";
+
+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((record) => [record.identifier, record]));
+
+  return {
+    filePath: "/tmp/yonexus-server-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 client of clients) {
+        persisted.set(client.identifier, client);
+      }
+    })
+  };
+}
+
+function createMockTransport() {
+  const sentToConnection: Array<{ connection: ClientConnection; message: string }> = [];
+  const sentByIdentifier: Array<{ identifier: string; message: string }> = [];
+  const assigned = new Map<object, string>();
+  const promoted: string[] = [];
+  const closed: Array<{ identifier: string; code?: number; reason?: string }> = [];
+
+  const transport: ServerTransport = {
+    isRunning: false,
+    connections: new Map(),
+    start: vi.fn(async () => undefined),
+    stop: vi.fn(async () => undefined),
+    send: vi.fn((identifier: string, message: string) => {
+      sentByIdentifier.push({ identifier, message });
+      return true;
+    }),
+    sendToConnection: vi.fn((connection: ClientConnection, message: string) => {
+      sentToConnection.push({ connection, message });
+      return true;
+    }),
+    broadcast: vi.fn(),
+    closeConnection: vi.fn((identifier: string, code?: number, reason?: string) => {
+      closed.push({ identifier, code, reason });
+      return true;
+    }),
+    promoteToAuthenticated: vi.fn((identifier: string, _ws) => {
+      promoted.push(identifier);
+      return true;
+    }),
+    removeTempConnection: vi.fn(),
+    assignIdentifierToTemp: vi.fn((ws, identifier: string) => {
+      assigned.set(ws as object, identifier);
+    })
+  };
+
+  return {
+    transport,
+    sentToConnection,
+    sentByIdentifier,
+    assigned,
+    promoted,
+    closed
+  };
+}
+
+function stubDiscordFetchSuccess() {
+  vi.stubGlobal(
+    "fetch",
+    vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({ id: "dm-channel-1" })
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({ id: "message-1" })
+      })
+  );
+}
+
+describe("Yonexus.Server runtime flow", () => {
+  it("runs hello -> pair_request for an unpaired client", async () => {
+    stubDiscordFetchSuccess();
+    const store = createMockStore();
+    const transportState = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport: transportState.transport,
+      now: () => 1_710_000_000
+    });
+
+    await runtime.start();
+
+    const connection = createConnection();
+    await runtime.handleMessage(
+      connection,
+      encodeBuiltin(
+        buildHello(
+          {
+            identifier: "client-a",
+            hasSecret: false,
+            hasKeyPair: false,
+            protocolVersion: YONEXUS_PROTOCOL_VERSION
+          },
+          { requestId: "req-hello", timestamp: 1_710_000_000 }
+        )
+      )
+    );
+
+    expect(transportState.assigned.get(connection.ws as object)).toBe("client-a");
+    expect(transportState.sentToConnection).toHaveLength(2);
+
+    const helloAck = decodeBuiltin(transportState.sentToConnection[0].message);
+    expect(helloAck.type).toBe("hello_ack");
+    expect(helloAck.payload).toMatchObject({
+      identifier: "client-a",
+      nextAction: "pair_required"
+    });
+
+    const pairRequest = decodeBuiltin(transportState.sentToConnection[1].message) as BuiltinEnvelope<
+      "pair_request",
+      PairRequestPayload
+    >;
+    expect(pairRequest.type).toBe("pair_request");
+    expect(pairRequest.payload).toMatchObject({
+      identifier: "client-a",
+      adminNotification: "sent",
+      codeDelivery: "out_of_band"
+    });
+
+    const record = runtime.state.registry.clients.get("client-a");
+    expect(record?.pairingStatus).toBe("pending");
+    expect(record?.pairingCode).toBeTypeOf("string");
+  });
+
+  it("completes pair_confirm -> auth_request -> heartbeat for a client", async () => {
+    stubDiscordFetchSuccess();
+    let now = 1_710_000_000;
+    const keyPair = await generateKeyPair();
+    const store = createMockStore();
+    const transportState = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport: transportState.transport,
+      now: () => now
+    });
+
+    await runtime.start();
+
+    const connection = createConnection();
+    await runtime.handleMessage(
+      connection,
+      encodeBuiltin(
+        buildHello(
+          {
+            identifier: "client-a",
+            hasSecret: false,
+            hasKeyPair: true,
+            publicKey: keyPair.publicKey,
+            protocolVersion: YONEXUS_PROTOCOL_VERSION
+          },
+          { requestId: "req-hello", timestamp: now }
+        )
+      )
+    );
+
+    const pairRequest = decodeBuiltin(transportState.sentToConnection[1].message) as BuiltinEnvelope<
+      "pair_request",
+      PairRequestPayload
+    >;
+    const pairingCode = runtime.state.registry.clients.get("client-a")?.pairingCode;
+    expect(pairingCode).toBeTypeOf("string");
+    expect(pairRequest.payload?.identifier).toBe("client-a");
+
+    now += 2;
+    await runtime.handleMessage(
+      connection,
+      encodeBuiltin(
+        buildPairConfirm(
+          {
+            identifier: "client-a",
+            pairingCode: pairingCode!
+          },
+          { requestId: "req-pair", timestamp: now }
+        )
+      )
+    );
+
+    const pairSuccess = decodeBuiltin(
+      transportState.sentToConnection[transportState.sentToConnection.length - 1].message
+    );
+    expect(pairSuccess.type).toBe("pair_success");
+
+    const recordAfterPair = runtime.state.registry.clients.get("client-a");
+    expect(recordAfterPair?.pairingStatus).toBe("paired");
+    expect(recordAfterPair?.publicKey).toBe(keyPair.publicKey.trim());
+    expect(recordAfterPair?.secret).toBeTypeOf("string");
+
+    now += 2;
+    const nonce = "AUTHNONCESTRING000000001";
+    const signingInput = createAuthRequestSigningInput({
+      secret: recordAfterPair!.secret!,
+      nonce,
+      proofTimestamp: now
+    });
+    const signature = await signMessage(keyPair.privateKey, signingInput);
+    await expect(verifySignature(keyPair.publicKey, signingInput, signature)).resolves.toBe(true);
+
+    await runtime.handleMessage(
+      connection,
+      encodeBuiltin(
+        buildAuthRequest(
+          {
+            identifier: "client-a",
+            nonce,
+            proofTimestamp: now,
+            signature,
+            publicKey: keyPair.publicKey
+          },
+          { requestId: "req-auth", timestamp: now }
+        )
+      )
+    );
+
+    const authSuccess = decodeBuiltin(
+      transportState.sentToConnection[transportState.sentToConnection.length - 1].message
+    );
+    expect(authSuccess.type).toBe("auth_success");
+    expect(transportState.promoted).toContain("client-a");
+
+    const session = runtime.state.registry.sessions.get("client-a");
+    expect(session?.isAuthenticated).toBe(true);
+
+    now += 5;
+    await runtime.handleMessage(
+      { ...connection, identifier: "client-a", isAuthenticated: true },
+      encodeBuiltin(
+        buildHeartbeat(
+          {
+            identifier: "client-a",
+            status: "alive"
+          },
+          { requestId: "req-heartbeat", timestamp: now }
+        )
+      )
+    );
+
+    const heartbeatAck = decodeBuiltin(
+      transportState.sentToConnection[transportState.sentToConnection.length - 1].message
+    );
+    expect(heartbeatAck.type).toBe("heartbeat_ack");
+
+    const recordAfterHeartbeat = runtime.state.registry.clients.get("client-a");
+    expect(recordAfterHeartbeat?.status).toBe("online");
+    expect(recordAfterHeartbeat?.lastHeartbeatAt).toBe(now);
+  });
+
+  it("returns MALFORMED_MESSAGE for hello without payload and keeps the connection open", async () => {
+    const store = createMockStore();
+    const transportState = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport: transportState.transport,
+      now: () => 1_710_000_000
+    });
+
+    await runtime.start();
+
+    const connection = createConnection();
+    await runtime.handleMessage(
+      connection,
+      encodeBuiltin({
+        type: "hello",
+        requestId: "req-bad-hello",
+        timestamp: 1_710_000_000
+      })
+    );
+
+    expect(transportState.sentToConnection).toHaveLength(1);
+    const errorResponse = decodeBuiltin(transportState.sentToConnection[0].message);
+    expect(errorResponse.type).toBe("error");
+    expect(errorResponse.payload).toMatchObject({
+      code: "MALFORMED_MESSAGE",
+      message: "hello payload is required"
+    });
+    expect((connection.ws.close as ReturnType<typeof vi.fn>)).not.toHaveBeenCalled();
+  });
+
+  it("rejects unauthenticated rule messages by closing the connection", async () => {
+    const store = createMockStore();
+    const transportState = createMockTransport();
+    const runtime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport: transportState.transport,
+      now: () => 1_710_000_000
+    });
+
+    await runtime.start();
+
+    const connection = createConnection("client-a");
+    runtime.state.registry.sessions.set("client-a", {
+      identifier: "client-a",
+      socket: connection.ws,
+      isAuthenticated: false,
+      connectedAt: connection.connectedAt,
+      lastActivityAt: 1_710_000_000
+    });
+
+    await runtime.handleMessage(connection, 'chat_sync::{"body":"hello"}');
+
+    expect((connection.ws.close as ReturnType<typeof vi.fn>)).toHaveBeenCalledWith(
+      1008,
+      "Not authenticated"
+    );
+  });
+
+  it("marks stale authenticated clients unstable then offline during liveness sweep", async () => {
+    vi.useFakeTimers();
+    try {
+      let now = 1_710_000_000;
+      const store = createMockStore();
+      const transportState = createMockTransport();
+      const runtime = createYonexusServerRuntime({
+        config: {
+          followerIdentifiers: ["client-a"],
+          notifyBotToken: "stub-token",
+          adminUserId: "admin-user",
+          listenHost: "127.0.0.1",
+          listenPort: 8787
+        },
+        store,
+        transport: transportState.transport,
+        now: () => now,
+        sweepIntervalMs: 1000
+      });
+
+      await runtime.start();
+
+      runtime.state.registry.clients.set("client-a", {
+        identifier: "client-a",
+        pairingStatus: "paired",
+        publicKey: "pk",
+        secret: "secret",
+        status: "online",
+        recentNonces: [],
+        recentHandshakeAttempts: [],
+        createdAt: now,
+        updatedAt: now,
+        lastAuthenticatedAt: now,
+        lastHeartbeatAt: now
+      });
+      runtime.state.registry.sessions.set("client-a", {
+        identifier: "client-a",
+        socket: createMockSocket(),
+        isAuthenticated: true,
+        connectedAt: now,
+        lastActivityAt: now
+      });
+
+      now += 7 * 60;
+      await vi.advanceTimersByTimeAsync(1000);
+
+      expect(runtime.state.registry.clients.get("client-a")?.status).toBe("unstable");
+      const unstableNotice = transportState.sentByIdentifier.at(-1);
+      expect(unstableNotice?.identifier).toBe("client-a");
+      expect(decodeBuiltin(unstableNotice!.message).type).toBe("status_update");
+
+      now += 4 * 60;
+      await vi.advanceTimersByTimeAsync(1000);
+
+      expect(runtime.state.registry.clients.get("client-a")?.status).toBe("offline");
+      expect(transportState.closed).toContainEqual({
+        identifier: "client-a",
+        code: 1001,
+        reason: "Heartbeat timeout"
+      });
+      expect(runtime.state.registry.sessions.has("client-a")).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

tests/state-recovery.test.ts

@@ -0,0 +1,303 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createYonexusServerRuntime } from "../plugin/core/runtime.js";
+import { createMockNotificationService } from "../plugin/notifications/discord.js";
+import {
+  createYonexusServerStore,
+  loadServerStore,
+  YonexusServerStoreCorruptionError
+} from "../plugin/core/store.js";
+import type { ClientConnection, ServerTransport } from "../plugin/core/transport.js";
+import {
+  buildHello,
+  decodeBuiltin,
+  encodeBuiltin,
+  type BuiltinEnvelope,
+  type PairRequestPayload,
+  YONEXUS_PROTOCOL_VERSION
+} from "../../Yonexus.Protocol/src/index.js";
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+async function createTempServerStorePath(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "yonexus-server-recovery-"));
+  tempDirs.push(dir);
+  return join(dir, "server-store.json");
+}
+
+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 createMockTransport() {
+  const sentToConnection: Array<{ connection: ClientConnection; message: string }> = [];
+
+  const transport: ServerTransport = {
+    isRunning: false,
+    connections: new Map(),
+    start: vi.fn(async () => undefined),
+    stop: vi.fn(async () => undefined),
+    send: vi.fn(() => true),
+    sendToConnection: vi.fn((connection: ClientConnection, message: string) => {
+      sentToConnection.push({ connection, message });
+      return true;
+    }),
+    broadcast: vi.fn(),
+    closeConnection: vi.fn(() => true),
+    promoteToAuthenticated: vi.fn(() => true),
+    removeTempConnection: vi.fn(),
+    assignIdentifierToTemp: vi.fn()
+  };
+
+  return {
+    transport,
+    sentToConnection
+  };
+}
+
+describe("YNX-1105e: Server state recovery", () => {
+  it("SR-01: preserves pending pairing across restart and reuses the same pairing code", async () => {
+    const storePath = await createTempServerStorePath();
+    const store = createYonexusServerStore(storePath);
+    let now = 1_710_000_000;
+
+    const firstTransport = createMockTransport();
+    const firstRuntime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport: firstTransport.transport,
+      notificationService: createMockNotificationService(),
+      now: () => now
+    });
+
+    await firstRuntime.start();
+
+    const firstConnection = createConnection();
+    await firstRuntime.handleMessage(
+      firstConnection,
+      encodeBuiltin(
+        buildHello(
+          {
+            identifier: "client-a",
+            hasSecret: false,
+            hasKeyPair: false,
+            protocolVersion: YONEXUS_PROTOCOL_VERSION
+          },
+          { requestId: "req-hello-1", timestamp: now }
+        )
+      )
+    );
+
+    const initialRecord = firstRuntime.state.registry.clients.get("client-a");
+    const initialPairingCode = initialRecord?.pairingCode;
+    const initialExpiresAt = initialRecord?.pairingExpiresAt;
+
+    expect(initialRecord?.pairingStatus).toBe("pending");
+    expect(initialPairingCode).toBeTypeOf("string");
+    expect(initialExpiresAt).toBeTypeOf("number");
+
+    await firstRuntime.stop();
+
+    const persistedRaw = JSON.parse(await readFile(storePath, "utf8")) as {
+      clients: Array<{ identifier: string; pairingStatus: string; pairingCode?: string }>;
+    };
+    expect(
+      persistedRaw.clients.find((client) => client.identifier === "client-a")
+    ).toMatchObject({
+      identifier: "client-a",
+      pairingStatus: "pending",
+      pairingCode: initialPairingCode
+    });
+
+    now += 30;
+
+    const secondTransport = createMockTransport();
+    const secondRuntime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport: secondTransport.transport,
+      notificationService: createMockNotificationService(),
+      now: () => now
+    });
+
+    await secondRuntime.start();
+
+    const reloadedRecord = secondRuntime.state.registry.clients.get("client-a");
+    expect(reloadedRecord?.pairingStatus).toBe("pending");
+    expect(reloadedRecord?.pairingCode).toBe(initialPairingCode);
+    expect(reloadedRecord?.pairingExpiresAt).toBe(initialExpiresAt);
+
+    const secondConnection = createConnection();
+    await secondRuntime.handleMessage(
+      secondConnection,
+      encodeBuiltin(
+        buildHello(
+          {
+            identifier: "client-a",
+            hasSecret: false,
+            hasKeyPair: false,
+            protocolVersion: YONEXUS_PROTOCOL_VERSION
+          },
+          { requestId: "req-hello-2", timestamp: now }
+        )
+      )
+    );
+
+    const helloAck = decodeBuiltin(secondTransport.sentToConnection[0].message);
+    expect(helloAck.type).toBe("hello_ack");
+    expect(helloAck.payload).toMatchObject({
+      identifier: "client-a",
+      nextAction: "waiting_pair_confirm"
+    });
+
+    const pairRequest = decodeBuiltin(secondTransport.sentToConnection[1].message) as BuiltinEnvelope<
+      "pair_request",
+      PairRequestPayload
+    >;
+    expect(pairRequest.type).toBe("pair_request");
+    expect(pairRequest.payload).toMatchObject({
+      identifier: "client-a",
+      adminNotification: "sent",
+      codeDelivery: "out_of_band"
+    });
+    expect(pairRequest.payload?.expiresAt).toBe(initialExpiresAt);
+
+    await secondRuntime.stop();
+  });
+
+  it("SR-02: restart drops in-memory active sessions and requires reconnect", async () => {
+    const storePath = await createTempServerStorePath();
+    const store = createYonexusServerStore(storePath);
+    const now = 1_710_000_000;
+
+    const firstTransport = createMockTransport();
+    const firstRuntime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport: firstTransport.transport,
+      now: () => now
+    });
+
+    await firstRuntime.start();
+    const record = firstRuntime.state.registry.clients.get("client-a");
+    expect(record).toBeDefined();
+
+    record!.pairingStatus = "paired";
+    record!.publicKey = "test-public-key";
+    record!.secret = "test-secret";
+    record!.status = "online";
+    record!.lastAuthenticatedAt = now;
+    record!.lastHeartbeatAt = now;
+    record!.updatedAt = now;
+
+    firstRuntime.state.registry.sessions.set("client-a", {
+      identifier: "client-a",
+      socket: createMockSocket(),
+      isAuthenticated: true,
+      connectedAt: now,
+      lastActivityAt: now,
+      publicKey: "test-public-key"
+    });
+
+    await firstRuntime.stop();
+
+    const secondTransport = createMockTransport();
+    const secondRuntime = createYonexusServerRuntime({
+      config: {
+        followerIdentifiers: ["client-a"],
+        notifyBotToken: "stub-token",
+        adminUserId: "admin-user",
+        listenHost: "127.0.0.1",
+        listenPort: 8787
+      },
+      store,
+      transport: secondTransport.transport,
+      now: () => now + 5
+    });
+
+    await secondRuntime.start();
+
+    const reloadedRecord = secondRuntime.state.registry.clients.get("client-a");
+    expect(reloadedRecord).toMatchObject({
+      identifier: "client-a",
+      pairingStatus: "paired",
+      secret: "test-secret",
+      publicKey: "test-public-key",
+      status: "online",
+      lastAuthenticatedAt: now,
+      lastHeartbeatAt: now
+    });
+    expect(secondRuntime.state.registry.sessions.size).toBe(0);
+
+    const reconnectConnection = createConnection();
+    await secondRuntime.handleMessage(
+      reconnectConnection,
+      encodeBuiltin(
+        buildHello(
+          {
+            identifier: "client-a",
+            hasSecret: true,
+            hasKeyPair: true,
+            publicKey: "test-public-key",
+            protocolVersion: YONEXUS_PROTOCOL_VERSION
+          },
+          { requestId: "req-hello-reconnect", timestamp: now + 5 }
+        )
+      )
+    );
+
+    const helloAck = decodeBuiltin(secondTransport.sentToConnection[0].message);
+    expect(helloAck.type).toBe("hello_ack");
+    expect(helloAck.payload).toMatchObject({
+      identifier: "client-a",
+      nextAction: "auth_required"
+    });
+
+    await secondRuntime.stop();
+  });
+
+  it("SR-05: corrupted server store raises YonexusServerStoreCorruptionError", async () => {
+    const storePath = await createTempServerStorePath();
+    await writeFile(storePath, '{"version":1,"clients":"oops"}\n', "utf8");
+
+    await expect(loadServerStore(storePath)).rejects.toBeInstanceOf(YonexusServerStoreCorruptionError);
+    await expect(loadServerStore(storePath)).rejects.toThrow("invalid clients array");
+  });
+});

tsconfig.json

@@ -4,7 +4,7 @@
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "outDir": "dist",
-    "rootDir": ".",
+    "rootDir": "..",
     "strict": true,
     "skipLibCheck": true,
     "esModuleInterop": true,
@@ -15,7 +15,9 @@
   },
   "include": [
     "plugin/**/*.ts",
-    "servers/**/*.ts"
+    "plugin/**/*.d.ts",
+    "servers/**/*.ts",
+    "../Yonexus.Protocol/src/**/*.ts"
   ],
   "exclude": [
     "dist",