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.

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

@@ -59,8 +59,8 @@ 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) {

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,12 +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;
 }
@@ -447,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;
     }
@@ -543,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(
@@ -613,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(
@@ -620,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"
           },
@@ -628,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(
@@ -932,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 (!identifier) {
-        for (const [id, conn] of this._connections) {
-          if (conn.ws === ws) {
-            identifier = id;
-            break;
-          }
-        }
+      // 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;
       }
 
-      const connection = identifier ? this._connections.get(identifier) ?? tempConn : tempConn;
+      // ws has been promoted — find it in authenticated connections
+      let connection: ClientConnection = tempConn;
+      for (const [, conn] of this._connections) {
+        if (conn.ws === ws) {
+          connection = conn;
+          break;
+        }
+      }
       this.options.onMessage(connection, message);
     });
 

plugin/index.ts

@@ -30,30 +30,189 @@ export {
   type YonexusServerStore
 } from "./core/store.js";
 
+import path from "node:path";
+import fs from "node:fs";
+import { validateYonexusServerConfig } from "./core/config.js";
+import { createYonexusServerStore } from "./core/store.js";
+import { createServerTransport, type ServerTransport } from "./core/transport.js";
+import { createYonexusServerRuntime } from "./core/runtime.js";
+import { createServerRuleRegistry, YonexusServerRuleRegistry } from "./core/rules.js";
+import { encodeRuleMessage } from "../../Yonexus.Protocol/src/index.js";
+import type { ServerPersistenceData } from "./core/persistence.js";
+
+const _G = globalThis as Record<string, unknown>;
+const _STARTED_KEY   = "_yonexusServerStarted";
+const _TRANSPORT_KEY = "_yonexusServerTransport";
+const _REGISTRY_KEY  = "_yonexusServerRegistry";
+const _CALLBACKS_KEY = "_yonexusServerOnAuthCallbacks";
+
 export interface YonexusServerPluginManifest {
   readonly name: "Yonexus.Server";
   readonly version: string;
   readonly description: string;
 }
 
-export interface YonexusServerPluginRuntime {
-  readonly hooks: readonly [];
-  readonly commands: readonly [];
-  readonly tools: readonly [];
-}
-
 const manifest: YonexusServerPluginManifest = {
   name: "Yonexus.Server",
   version: "0.1.0",
   description: "Yonexus central hub plugin for cross-instance OpenClaw communication"
 };
 
-export function createYonexusServerPlugin(): YonexusServerPluginRuntime {
-  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/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"]
   }
 }

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/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 {