fix: globalThis

Module-level _serverStarted / ruleRegistry / onClientAuthenticatedCallbacks
reset on hot-reload (new VM context). After hot-reload the second runtime
attempt would hit EADDRINUSE (silently swallowed) while __yonexusServer
was overwritten to point at a transport that never started, making every
sendRule() return false.

- Replace let _serverStarted with _G["_yonexusServerStarted"]
- Store ruleRegistry and onClientAuthenticatedCallbacks under globalThis
  keys, initialising only when absent
- Store transport under _G["_yonexusServerTransport"]; sendRule closure
  reads it from globalThis instead of a module-local capture
- Re-write __yonexusServer every register() call (updated closures),
  but skip runtime.start() when the globalThis flag is already set

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

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 {
@@ -67,18 +67,18 @@ export function validateYonexusServerConfig(raw: unknown): YonexusServerConfig {
     issues.push("followerIdentifiers must not contain duplicates");
   }
 
-  const notifyBotToken = source.notifyBotToken;
-  if (!isNonEmptyString(notifyBotToken)) {
+  const rawNotifyBotToken = source.notifyBotToken;
+  if (!isNonEmptyString(rawNotifyBotToken)) {
     issues.push("notifyBotToken is required");
   }
 
-  const adminUserId = source.adminUserId;
-  if (!isNonEmptyString(adminUserId)) {
+  const rawAdminUserId = source.adminUserId;
+  if (!isNonEmptyString(rawAdminUserId)) {
     issues.push("adminUserId is required");
   }
 
-  const listenPort = source.listenPort;
-  if (!isValidPort(listenPort)) {
+  const rawListenPort = source.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

@@ -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,7 +84,9 @@ export class YonexusServerRuntime {
     };
     this.sweepIntervalMs = options.sweepIntervalMs ?? 30_000;
     this.pairingService = createPairingService({ now: this.now });
-    this.notificationService = createDiscordNotificationService({
+    this.notificationService =
+      options.notificationService ??
+      createDiscordNotificationService({
         botToken: options.config.notifyBotToken,
         adminUserId: options.config.adminUserId
       });
@@ -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 {
         )
       )
     );
-
-    if (!notified) {
-      this.options.transport.sendToConnection(
-        connection,
-        encodeBuiltin(
-          buildPairFailed(
-            {
-              identifier: record.identifier,
-              reason: "admin_notification_failed"
-            },
-            { requestId, timestamp: this.now() }
-          )
-        )
-      );
-      this.pairingService.clearPairingState(record);
-    }
+    // Pairing remains pending regardless of notification status.
+    // The admin can retrieve the pairing code via the server CLI command.
   }
 
   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();
-
-      // Future: dispatch to rule registry
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      void rewritten;
+      this.options.ruleRegistry?.dispatch(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
-      let identifier: string | null = null;
-      const tempData = this.tempConnections.get(ws);
-      if (tempData) {
-        identifier = tempData.assignedIdentifier;
+      // If this ws is still in temp state, use tempConn directly.
+      // Never fall through to _connections — it may hold a stale entry for the
+      // same identifier from a previously-authenticated session that hasn't
+      // finished closing yet, which would cause promoteToAuthenticated to receive
+      // the wrong WebSocket and silently fail.
+      if (this.tempConnections.has(ws)) {
+        this.options.onMessage(tempConn, message);
+        return;
       }
-      if (!identifier) {
-        for (const [id, conn] of this._connections) {
+
+      // ws has been promoted — find it in authenticated connections
+      let connection: ClientConnection = tempConn;
+      for (const [, conn] of this._connections) {
         if (conn.ws === ws) {
-            identifier = id;
+          connection = conn;
           break;
         }
       }
-      }
-
-      const connection = identifier ? this._connections.get(identifier) ?? tempConn : tempConn;
       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 {
-  return {
-    hooks: [],
-    commands: [],
-    tools: []
+export function createYonexusServerPlugin(api: {
+  rootDir: string;
+  pluginConfig: unknown;
+  registrationMode?: string;  // "full" (gateway) | "cli-metadata" | "setup-only" | "setup-runtime"
+  // 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:
- * - Discord bot client integration (e.g., using discord.js)
- * - DM channel creation/fetching
- * - 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.
+ * Flow:
+ * 1. Create or fetch a DM channel for the configured admin user
+ * 2. Post the formatted pairing message into that DM channel
  */
 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)
-      console.log("[Yonexus.Server] Pairing notification (Discord DM stub):", {
+      try {
+        await sendDiscordDirectMessage({
+          config,
+          message: formatPairingMessage(request),
+          fetcher
+        });
+
+        console.log("[Yonexus.Server] Pairing notification sent via Discord DM", {
           identifier: request.identifier,
-        pairingCode: redactedCode,
+          pairingCode: redactPairingCode(request.pairingCode),
           expiresAt: request.expiresAt,
           ttlSeconds: request.ttlSeconds,
           adminUserId: config.adminUserId
         });
 
-      // TODO: Replace with actual Discord bot integration
-      // Example with discord.js:
-      // const client = new Client({ intents: [GatewayIntentBits.DirectMessages] });
-      // await client.login(config.botToken);
-      // const user = await client.users.fetch(config.adminUserId);
-      // await user.send(message);
-      
-      // For now, return true to allow pairing flow to continue
-      // In production, this should return false if DM fails
         return true;
+      } catch (error) {
+        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": {
-    "followerIdentifiers": [],
-    "notifyBotToken": "",
-    "adminUserId": "",
-    "listenHost": "0.0.0.0",
-    "listenPort": 8787,
-    "publicWsUrl": ""
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "followerIdentifiers": {
+        "type": "array",
+        "items": { "type": "string" }
+      },
+      "notifyBotToken": { "type": "string" },
+      "adminUserId": { "type": "string" },
+      "listenHost": { "type": "string" },
+      "listenPort": { "type": "number" },
+      "publicWsUrl": { "type": "string" }
+    },
+    "required": ["followerIdentifiers", "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

@@ -29,6 +29,7 @@ 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"));
+  fs.copyFileSync(path.join(repoRoot, "package.json"), path.join(targetDir, "package.json"));
   console.log(`Installed ${pluginName} to ${targetDir}`);
   process.exit(0);
 }

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.Client/plugin/crypto/keypair.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/runtime-flow.test.ts

@@ -98,8 +98,27 @@ function createMockTransport() {
   };
 }
 
+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({
@@ -160,6 +179,7 @@ describe("Yonexus.Server runtime flow", () => {
   });
 
   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();
@@ -287,6 +307,44 @@ describe("Yonexus.Server runtime flow", () => {
     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();

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",