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.

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) {
-    issues.push("followerIdentifiers must contain at least one non-empty identifier");
+  if (!Array.isArray(rawIdentifiers)) {
+    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;
-  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

@@ -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,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": ["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

@@ -10,7 +10,7 @@ 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";
+import { generateKeyPair, signMessage } from "../../Yonexus.Protocol/src/crypto.js";
 
 function createMockSocket() {
   return { close: vi.fn() } as unknown as ClientConnection["ws"];

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

@@ -17,7 +17,7 @@ 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.Client/plugin/crypto/keypair.js";
+import { generateKeyPair, signMessage, verifySignature } from "../../Yonexus.Protocol/src/crypto.js";
 
 function createMockSocket() {
   return {
@@ -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

@@ -5,6 +5,7 @@ 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,
@@ -90,6 +91,7 @@ describe("YNX-1105e: Server state recovery", () => {
       },
       store,
       transport: firstTransport.transport,
+      notificationService: createMockNotificationService(),
       now: () => now
     });
 
@@ -145,6 +147,7 @@ describe("YNX-1105e: Server state recovery", () => {
       },
       store,
       transport: secondTransport.transport,
+      notificationService: createMockNotificationService(),
       now: () => now
     });
 
@@ -193,6 +196,103 @@ describe("YNX-1105e: Server state recovery", () => {
     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");

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