@zhihand/mcp 0.33.0 → 0.34.0

package/bin/zhihand

@@ -21,6 +21,8 @@ import {
   DEFAULT_MODELS,
   resolveConfig,
   resolveDefaultEndpoint,
+  loadPluginIdentity,
+  clearPluginIdentity,
 } from "../dist/core/config.js";
 import {
   executePairingNewUser,
@@ -30,7 +32,7 @@ import { fetchUserCredentials } from "../dist/core/ws.js";
 import { configureMCP, displayName } from "../dist/cli/mcp-config.js";
 
 const DEFAULT_ENDPOINT = "https://api.zhihand.com";
-const VERSION = "0.33.0";
+const VERSION = "0.33.1";
 
 const CLI_TOOL_MAP = {
   claude: "claudecode",
@@ -207,6 +209,24 @@ switch (command) {
     break;
   }
 
+  case "identity": {
+    const subCmd = positionals[1];
+    if (subCmd === "reset") {
+      clearPluginIdentity();
+      console.log("Plugin identity cleared. Next 'zhihand pair' will register a new identity.");
+    } else {
+      const id = loadPluginIdentity();
+      if (id) {
+        console.log(`Edge ID:          ${id.edge_id}`);
+        console.log(`Stable Identity:  ${id.stable_identity}`);
+        console.log(`Plugin Secret:    ${id.plugin_secret.slice(0, 6)}...(redacted)`);
+      } else {
+        console.log("No plugin identity found. Run 'zhihand pair' to create one.");
+      }
+    }
+    break;
+  }
+
   case "mcp":
   case "serve": {
     await startStdioServer();
@@ -558,6 +578,9 @@ switch (command) {
     const { createControlCommand, createSystemCommand } = await import("../dist/core/command.js");
     const { fetchScreenshot, getSnapshotStaleThresholdMs } = await import("../dist/core/screenshot.js");
     const { fetchDeviceProfileOnce, extractStatic, computeCapabilities, formatDeviceStatus } = await import("../dist/core/device.js");
+    const { setDebugEnabled: setCoreDebug, setTimestampEnabled, log: coreLog } = await import("../dist/core/logger.js");
+    if (values.debug) setCoreDebug(true);
+    setTimestampEnabled(true);
 
     const KIND_CAPABILITY = {
       profile: "none", status: "none", screenshot: "screen", hid: "hid", system: "none",
@@ -633,17 +656,26 @@ switch (command) {
     const DAEMON_PORT = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || 18686;
     const DAEMON_BASE = `http://127.0.0.1:${DAEMON_PORT}`;
     let daemonOk = false;
+    let daemonStatus = null;
     try {
       const resp = await fetch(`${DAEMON_BASE}/internal/status`, { signal: AbortSignal.timeout(2000) });
       daemonOk = resp.ok;
+      if (resp.ok) daemonStatus = await resp.json();
     } catch { /* daemon not reachable */ }
     if (!daemonOk) {
       console.error("❌ Daemon is not running. Start it first: zhihand start");
       process.exit(1);
     }
 
+    const testDbg = values.debug
+      ? (msg) => coreLog.debug(`[test] ${msg}`)
+      : () => {};
+
     // Execute command via daemon's /internal/exec endpoint
     async function execViaDaemon(command, timeoutMs = 10_000) {
+      const action = command?.payload?.action ?? command?.type ?? "?";
+      testDbg(`exec action=${action} timeout=${timeoutMs}ms`);
+      const t0 = Date.now();
       const resp = await fetch(`${DAEMON_BASE}/internal/exec`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -652,9 +684,12 @@ switch (command) {
       });
       if (!resp.ok) {
         const body = await resp.text();
+        testDbg(`exec FAILED ${resp.status} ${Date.now() - t0}ms`);
         throw new Error(`Daemon exec failed: ${resp.status} ${body}`);
       }
-      return resp.json();
+      const result = await resp.json();
+      testDbg(`exec done action=${action} acked=${result.acked} id=${result.id ?? "-"} ${Date.now() - t0}ms`);
+      return result;
     }
 
     const forceRun = values.force === true;
@@ -681,7 +716,11 @@ switch (command) {
 
     console.log("🔧 ZhiHand Device Test");
     console.log(`   Device: ${testConfig.credentialId}`);
-    console.log(`   Endpoint: ${testConfig.controlPlaneEndpoint}\n`);
+    console.log(`   Endpoint: ${testConfig.controlPlaneEndpoint}`);
+    if (daemonStatus) {
+      console.log(`   Daemon: v${daemonStatus.version} pid=${daemonStatus.pid} backend=${daemonStatus.backend ?? "none"}`);
+    }
+    console.log("");
 
     // Pre-fetch device profile
     let currentRawAttrs = {};

package/dist/core/config.d.ts

@@ -34,9 +34,20 @@ export interface BackendConfig {
     model?: string | null;
 }
 export declare const DEFAULT_MODELS: Record<Exclude<BackendName, "openclaw">, string>;
+export interface PluginIdentity {
+    stable_identity: string;
+    edge_id: string;
+    plugin_secret: string;
+}
 export declare function resolveZhiHandDir(): string;
 export declare function ensureZhiHandDir(): void;
 export declare function getConfigPath(): string;
+/** Read persisted Plugin identity. Returns null if missing or malformed. */
+export declare function loadPluginIdentity(): PluginIdentity | null;
+/** Atomically persist Plugin identity (write-to-tmp + rename, mode 0o600). */
+export declare function savePluginIdentity(identity: PluginIdentity): void;
+/** Delete identity.json (used by `zhihand identity reset`). */
+export declare function clearPluginIdentity(): void;
 export declare function loadConfig(): ZhihandConfigV3;
 /**
  * Atomically write config: write to .tmp, then rename. Prevents corruption

package/dist/core/config.js

@@ -11,6 +11,7 @@ const ZHIHAND_DIR = path.join(os.homedir(), ".zhihand");
 const CONFIG_PATH = path.join(ZHIHAND_DIR, "config.json");
 const STATE_PATH = path.join(ZHIHAND_DIR, "state.json");
 const BACKEND_PATH = path.join(ZHIHAND_DIR, "backend.json");
+const IDENTITY_PATH = path.join(ZHIHAND_DIR, "identity.json");
 export function resolveZhiHandDir() {
     return ZHIHAND_DIR;
 }
@@ -20,6 +21,36 @@ export function ensureZhiHandDir() {
 export function getConfigPath() {
     return CONFIG_PATH;
 }
+// ── Plugin identity I/O ──────────────────────────────────
+/** Read persisted Plugin identity. Returns null if missing or malformed. */
+export function loadPluginIdentity() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(IDENTITY_PATH, "utf-8"));
+        if (raw.stable_identity && raw.edge_id && raw.plugin_secret) {
+            return raw;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomically persist Plugin identity (write-to-tmp + rename, mode 0o600). */
+export function savePluginIdentity(identity) {
+    ensureZhiHandDir();
+    const tmp = IDENTITY_PATH + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(identity, null, 2), { mode: 0o600 });
+    fs.renameSync(tmp, IDENTITY_PATH);
+}
+/** Delete identity.json (used by `zhihand identity reset`). */
+export function clearPluginIdentity() {
+    try {
+        fs.unlinkSync(IDENTITY_PATH);
+    }
+    catch {
+        // already gone
+    }
+}
 // ── v3 config I/O ──────────────────────────────────────────
 let legacyWarningPrinted = false;
 function emptyConfig() {

package/dist/core/logger.d.ts

@@ -1,12 +1,15 @@
 /**
  * Unified logger — all log output goes to stderr so stdout stays clean
- * for MCP JSON-RPC. Replaces ad-hoc process.stderr.write and dbg() calls
- * in core/ and tools/ code.
+ * for MCP JSON-RPC.
  *
- * The daemon has its own stdout-based log() in daemon/index.ts — that is
- * intentional (it writes to daemon.log). The daemon's debug logger
- * (daemon/logger.ts) remains for daemon-specific verbose output.
+ * All modules (core/, daemon/, tools/) should use this logger.
+ * The daemon's dbg() in daemon/logger.ts delegates here for the debug flag.
  */
+/**
+ * Redact sensitive tokens from log messages.
+ * Replaces Bearer tokens and controller_token values with <REDACTED>.
+ */
+export declare function redact(msg: string): string;
 export declare const log: {
     info: (...args: unknown[]) => void;
     warn: (...args: unknown[]) => void;
@@ -15,3 +18,5 @@ export declare const log: {
 };
 export declare function setDebugEnabled(v: boolean): void;
 export declare function isDebugEnabled(): boolean;
+/** Enable timestamps in log output (for daemon / CLI long-running processes). */
+export declare function setTimestampEnabled(v: boolean): void;

package/dist/core/logger.js

@@ -1,26 +1,50 @@
 /**
  * Unified logger — all log output goes to stderr so stdout stays clean
- * for MCP JSON-RPC. Replaces ad-hoc process.stderr.write and dbg() calls
- * in core/ and tools/ code.
+ * for MCP JSON-RPC.
  *
- * The daemon has its own stdout-based log() in daemon/index.ts — that is
- * intentional (it writes to daemon.log). The daemon's debug logger
- * (daemon/logger.ts) remains for daemon-specific verbose output.
+ * All modules (core/, daemon/, tools/) should use this logger.
+ * The daemon's dbg() in daemon/logger.ts delegates here for the debug flag.
  */
 let debugEnabled = false;
+let timestampEnabled = false;
+// ── Token redaction ──────────────────────────────────────
+const REDACT_PATTERNS = [
+    // Bearer tokens in headers / JSON
+    /(Bearer\s+)[^\s"',}]+/gi,
+    // controller_token in JSON / key=value
+    /(controller_token["']?\s*[:=]\s*["']?)[^\s"',}]+/gi,
+];
+/**
+ * Redact sensitive tokens from log messages.
+ * Replaces Bearer tokens and controller_token values with <REDACTED>.
+ */
+export function redact(msg) {
+    let result = msg;
+    for (const pattern of REDACT_PATTERNS) {
+        result = result.replace(pattern, "$1<REDACTED>");
+    }
+    return result;
+}
+// ── Logger ───────────────────────────────────────────────
+function prefix(level) {
+    if (timestampEnabled) {
+        return `[${new Date().toLocaleTimeString()}] [${level}] `;
+    }
+    return `[${level.padEnd(5)}] `;
+}
 export const log = {
     info: (...args) => {
-        process.stderr.write(`[info]  ${args.map(String).join(" ")}\n`);
+        process.stderr.write(`${prefix("info")}${redact(args.map(String).join(" "))}\n`);
     },
     warn: (...args) => {
-        process.stderr.write(`[warn]  ${args.map(String).join(" ")}\n`);
+        process.stderr.write(`${prefix("warn")}${redact(args.map(String).join(" "))}\n`);
     },
     error: (...args) => {
-        process.stderr.write(`[error] ${args.map(String).join(" ")}\n`);
+        process.stderr.write(`${prefix("error")}${redact(args.map(String).join(" "))}\n`);
     },
     debug: (...args) => {
         if (debugEnabled) {
-            process.stderr.write(`[debug] ${args.map(String).join(" ")}\n`);
+            process.stderr.write(`${prefix("debug")}${redact(args.map(String).join(" "))}\n`);
         }
     },
 };
@@ -30,3 +54,7 @@ export function setDebugEnabled(v) {
 export function isDebugEnabled() {
     return debugEnabled;
 }
+/** Enable timestamps in log output (for daemon / CLI long-running processes). */
+export function setTimestampEnabled(v) {
+    timestampEnabled = v;
+}

package/dist/core/pair.d.ts

@@ -1,4 +1,4 @@
-import type { DeviceRecord, UserRecord } from "./config.ts";
+import type { DeviceRecord, UserRecord, PluginIdentity } from "./config.ts";
 export interface PairingSession {
     session_id: string;
     pair_url: string;
@@ -30,7 +30,14 @@ export declare function registerPlugin(endpoint: string, options: {
     adapterKind?: string;
 }): Promise<{
     edge_id: string;
+    plugin_secret: string;
 }>;
+/**
+ * Ensure a persistent Plugin identity exists. Reuses existing identity
+ * if present; otherwise registers a new plugin and persists the result.
+ * All pair operations share the same identity → same EdgeID.
+ */
+export declare function ensurePluginIdentity(endpoint: string): Promise<PluginIdentity>;
 /**
  * Poll pairing session until claimed or expired.
  */

package/dist/core/pair.js

@@ -1,5 +1,6 @@
 import QRCode from "qrcode";
-import { addUser, addDeviceToUser, ensureZhiHandDir, saveState, resolveDefaultEndpoint, getUserRecord, cleanupLegacyConfig, } from "./config.js";
+import os from "node:os";
+import { addUser, addDeviceToUser, ensureZhiHandDir, saveState, resolveDefaultEndpoint, getUserRecord, cleanupLegacyConfig, loadPluginIdentity, savePluginIdentity, } from "./config.js";
 import { fetchDeviceProfileOnce, extractStatic } from "./device.js";
 import { fetchUserCredentials } from "./ws.js";
 // ── Server API helpers ─────────────────────────────────────
@@ -58,7 +59,24 @@ export async function registerPlugin(endpoint, options) {
         throw new Error(`Register plugin failed: ${response.status} ${await response.text()}`);
     }
     const payload = (await response.json());
-    return { edge_id: payload.plugin.edge_id };
+    return { edge_id: payload.plugin.edge_id, plugin_secret: payload.plugin.plugin_secret };
+}
+/**
+ * Ensure a persistent Plugin identity exists. Reuses existing identity
+ * if present; otherwise registers a new plugin and persists the result.
+ * All pair operations share the same identity → same EdgeID.
+ */
+export async function ensurePluginIdentity(endpoint) {
+    const existing = loadPluginIdentity();
+    const stableId = existing?.stable_identity ?? `mcp-${os.hostname()}-${Date.now().toString(36)}`;
+    const plugin = await registerPlugin(endpoint, { stableIdentity: stableId });
+    const identity = {
+        stable_identity: stableId,
+        edge_id: plugin.edge_id,
+        plugin_secret: plugin.plugin_secret,
+    };
+    savePluginIdentity(identity);
+    return identity;
 }
 /**
  * Poll pairing session until claimed or expired.
@@ -97,10 +115,9 @@ export async function executePairingNewUser(preferredLabel) {
     cleanupLegacyConfig();
     const userId = userResp.user_id;
     const controllerToken = userResp.controller_token;
-    // 2. Register plugin (get edge_id)
-    const stableIdentity = `mcp-${Date.now().toString(36)}`;
-    const plugin = await registerPlugin(endpoint, { stableIdentity });
-    const edgeId = plugin.edge_id;
+    // 2. Ensure persistent plugin identity (same EdgeID across all pairs)
+    const identity = await ensurePluginIdentity(endpoint);
+    const edgeId = identity.edge_id;
     // 3. Create pairing session
     const session = await createPairingSession(endpoint, userId, controllerToken, edgeId, 300);
     saveState({
@@ -186,10 +203,9 @@ export async function executePairingAddDevice(userId, preferredLabel) {
     if (!user)
         throw new Error(`User '${userId}' not found in config`);
     const controllerToken = user.controller_token;
-    // Register plugin (get edge_id)
-    const stableIdentity = `mcp-${Date.now().toString(36)}`;
-    const plugin = await registerPlugin(endpoint, { stableIdentity });
-    const edgeId = plugin.edge_id;
+    // Ensure persistent plugin identity (same EdgeID across all pairs)
+    const identity = await ensurePluginIdentity(endpoint);
+    const edgeId = identity.edge_id;
     // Get existing credential IDs before pairing
     const existingCreds = await fetchUserCredentials(endpoint, userId, controllerToken);
     const existingIds = new Set(existingCreds.map((c) => c.credential_id));

package/dist/core/ws.js

@@ -283,12 +283,15 @@ export async function fetchUserCredentials(endpoint, userId, controllerToken, on
 export async function waitForCommandAck(_config, options) {
     const timeoutMs = options.timeoutMs ?? 15_000;
     log.debug(`[ws-cmd] Waiting for ACK: commandId=${options.commandId}, timeout=${timeoutMs}ms`);
+    const t0 = Date.now();
     return new Promise((resolve, reject) => {
         const timeout = setTimeout(() => {
+            log.debug(`[ws-cmd] ACK timeout: commandId=${options.commandId} after ${Date.now() - t0}ms`);
             cleanup();
             resolve({ acked: false });
         }, timeoutMs);
         const unsubscribe = subscribeToCommandAck(options.commandId, (ackedCommand) => {
+            log.debug(`[ws-cmd] ACK received: commandId=${options.commandId} status=${ackedCommand.ack_status ?? "ok"} ${Date.now() - t0}ms`);
             cleanup();
             resolve({ acked: true, command: ackedCommand });
         });

package/dist/daemon/heartbeat.d.ts

@@ -1,12 +1,17 @@
-import type { ZhiHandRuntimeConfig } from "../core/config.ts";
 /** Brain metadata included in every heartbeat, so the app always knows the current backend/model. */
 export interface BrainMeta {
     backend?: string | null;
     model?: string | null;
 }
+/** Plugin-level heartbeat target. Uses edgeId + pluginSecret instead of per-credential auth. */
+export interface HeartbeatTarget {
+    controlPlaneEndpoint: string;
+    edgeId: string;
+    pluginSecret: string;
+}
 /** Update the backend/model metadata that will be sent with the next heartbeat. */
 export declare function setBrainMeta(meta: BrainMeta): void;
-export declare function sendBrainOnline(config: ZhiHandRuntimeConfig): Promise<boolean>;
-export declare function sendBrainOffline(config: ZhiHandRuntimeConfig): Promise<boolean>;
-export declare function startHeartbeatLoop(config: ZhiHandRuntimeConfig, log: (msg: string) => void): void;
+export declare function sendBrainOnline(target: HeartbeatTarget): Promise<boolean>;
+export declare function sendBrainOffline(target: HeartbeatTarget): Promise<boolean>;
+export declare function startHeartbeatLoop(target: HeartbeatTarget, log: (msg: string) => void): void;
 export declare function stopHeartbeatLoop(): void;

package/dist/daemon/heartbeat.js

@@ -9,23 +9,23 @@ let currentMeta = {};
 export function setBrainMeta(meta) {
     currentMeta = meta;
 }
-function buildUrl(config) {
-    return `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/brain-status`;
+function buildUrl(target) {
+    return `${target.controlPlaneEndpoint}/v1/plugins/${encodeURIComponent(target.edgeId)}/brain-status`;
 }
-async function sendHeartbeat(config, online) {
+async function sendHeartbeat(target, online) {
     try {
         const body = { plugin_online: online };
         if (currentMeta.backend)
             body.backend = currentMeta.backend;
         if (currentMeta.model)
             body.model = currentMeta.model;
-        const url = buildUrl(config);
+        const url = buildUrl(target);
         dbg(`[heartbeat] POST ${url} body=${JSON.stringify(body)}`);
         const response = await fetch(url, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                "Authorization": `Bearer ${config.controllerToken}`,
+                "Authorization": `Bearer ${target.pluginSecret}`,
             },
             body: JSON.stringify(body),
             signal: AbortSignal.timeout(10_000),
@@ -38,20 +38,20 @@ async function sendHeartbeat(config, online) {
         return false;
     }
 }
-export async function sendBrainOnline(config) {
-    return sendHeartbeat(config, true);
+export async function sendBrainOnline(target) {
+    return sendHeartbeat(target, true);
 }
-export async function sendBrainOffline(config) {
-    return sendHeartbeat(config, false);
+export async function sendBrainOffline(target) {
+    return sendHeartbeat(target, false);
 }
-export function startHeartbeatLoop(config, log) {
+export function startHeartbeatLoop(target, log) {
     let retrying = false;
     stopped = false;
     async function beat() {
         // Skip main-timer beats while retry loop is active (avoids overlap & flapping)
         if (retrying || stopped)
             return;
-        const ok = await sendBrainOnline(config);
+        const ok = await sendBrainOnline(target);
         if (stopped)
             return; // check after await — stopHeartbeatLoop() may have been called
         if (ok) {
@@ -70,7 +70,7 @@ export function startHeartbeatLoop(config, log) {
         retryTimer = setTimeout(async () => {
             if (!retrying || stopped)
                 return;
-            const recovered = await sendBrainOnline(config);
+            const recovered = await sendBrainOnline(target);
             if (stopped)
                 return; // check after await
             if (recovered) {

package/dist/daemon/index.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 // Transport type used only for cleanup interface
 import { createServer as createMcpServer } from "../index.js";
-import { resolveConfig, loadBackendConfig, saveBackendConfig, resolveZhiHandDir, ensureZhiHandDir, DEFAULT_MODELS, } from "../core/config.js";
+import { resolveConfig, loadBackendConfig, saveBackendConfig, resolveZhiHandDir, resolveDefaultEndpoint, ensureZhiHandDir, loadPluginIdentity, DEFAULT_MODELS, } from "../core/config.js";
 import { PACKAGE_VERSION } from "../index.js";
 import { startHeartbeatLoop, stopHeartbeatLoop, sendBrainOffline, setBrainMeta } from "./heartbeat.js";
 import { PromptListener } from "./prompt-listener.js";
@@ -21,9 +21,9 @@ let activeBackend = null;
 let activeModel = null; // user-selected model alias, null = use default
 let isProcessing = false;
 const promptQueue = [];
+import { log as coreLog, setTimestampEnabled } from "../core/logger.js";
 function log(msg) {
-    const ts = new Date().toLocaleTimeString();
-    process.stdout.write(`[${ts}] ${msg}\n`);
+    coreLog.info(msg);
 }
 // ── Prompt Processing ──────────────────────────────────────
 async function processPrompt(config, prompt) {
@@ -106,7 +106,6 @@ function handleInternalAPI(req, res) {
     }
     // Execute command via daemon's WS (used by zhihand test)
     if (url === "/internal/exec" && req.method === "POST") {
-        dbg(`[api] POST /internal/exec`);
         let body = "";
         const MAX_BODY = 10 * 1024;
         req.on("data", (chunk) => {
@@ -118,19 +117,28 @@ function handleInternalAPI(req, res) {
             }
         });
         req.on("end", async () => {
+            const t0 = Date.now();
             try {
                 const { command, credentialId, timeoutMs } = JSON.parse(body);
+                const cmdType = command.type ?? "unknown";
+                const cmdAction = command.payload?.action ?? "-";
+                dbg(`[api] POST /internal/exec cred=${credentialId} type=${cmdType} action=${cmdAction} timeout=${timeoutMs ?? 10_000}ms`);
                 const cfg = resolveConfig(credentialId);
                 const effectiveTimeout = timeoutMs ?? 10_000;
                 const queued = await enqueueCommand(cfg, command);
+                dbg(`[api] /internal/exec enqueued id=${queued.id}`);
                 const ack = await waitForCommandAck(cfg, {
                     commandId: queued.id,
                     timeoutMs: effectiveTimeout,
                 });
+                const ms = Date.now() - t0;
+                const ackStatus = ack.acked ? (ack.command?.ack_status ?? "ok") : "timeout";
+                dbg(`[api] /internal/exec done id=${queued.id} acked=${ack.acked} status=${ackStatus} ${ms}ms`);
                 res.writeHead(200, { "Content-Type": "application/json" });
                 res.end(JSON.stringify({ id: queued.id, ...ack }));
             }
             catch (err) {
+                dbg(`[api] /internal/exec error: ${err.message} ${Date.now() - t0}ms`);
                 res.writeHead(500, { "Content-Type": "application/json" });
                 res.end(JSON.stringify({ error: err.message }));
             }
@@ -190,6 +198,7 @@ export function isAlreadyRunning() {
 }
 // ── Main Daemon Entry ──────���───────────────────────────────
 export async function startDaemon(options) {
+    setTimestampEnabled(true);
     if (options?.debug)
         setDebugEnabled(true);
     const port = options?.port ?? (parseInt(process.env.ZHIHAND_PORT ?? "", 10) || DEFAULT_PORT);
@@ -350,15 +359,35 @@ export async function startDaemon(options) {
         httpServer.listen(port, "127.0.0.1", () => resolve());
     });
     writePid();
-    // Start heartbeat
-    startHeartbeatLoop(config, log);
-    // Start prompt listener
-    const promptListener = new PromptListener(config, (prompt) => onPromptReceived(config, prompt), log);
+    // Load Plugin identity for edge-level heartbeat + prompt WS
+    const identity = loadPluginIdentity();
+    if (!identity) {
+        log("[identity] No plugin identity found. Run 'zhihand pair' first.");
+        process.exit(1);
+    }
+    log(`[identity] Loaded: edge_id=${identity.edge_id}, stable_identity=${identity.stable_identity}`);
+    const heartbeatTarget = {
+        controlPlaneEndpoint: resolveDefaultEndpoint(),
+        edgeId: identity.edge_id,
+        pluginSecret: identity.plugin_secret,
+    };
+    // Start heartbeat (edge-level, pluginSecret auth)
+    startHeartbeatLoop(heartbeatTarget, log);
+    // Start prompt listener (edge-level single WS)
+    const promptListener = new PromptListener({
+        controlPlaneEndpoint: resolveDefaultEndpoint(),
+        edgeId: identity.edge_id,
+        pluginSecret: identity.plugin_secret,
+    }, (prompt) => onPromptReceived(config, prompt), log, (reason) => {
+        log(`[fatal] ${reason}`);
+        process.exit(1);
+    });
     promptListener.start();
     log(`ZhiHand daemon started.`);
     log(`  PID: ${process.pid}`);
     log(`  MCP: http://127.0.0.1:${port}/mcp`);
     log(`  Backend: ${activeBackend ?? "(none)"}`);
+    log(`  Edge: ${identity.edge_id}`);
     log(`  Device: ${config.credentialId}`);
     log(`Listening for prompts...`);
     // Graceful shutdown
@@ -368,7 +397,7 @@ export async function startDaemon(options) {
         stopHeartbeatLoop();
         clearInterval(sessionCleanupTimer);
         await killActiveChild();
-        await sendBrainOffline(config);
+        await sendBrainOffline(heartbeatTarget);
         // Close all MCP sessions
         for (const session of mcpSessions.values()) {
             try {

package/dist/daemon/logger.d.ts

@@ -1,10 +1,12 @@
 /**
  * Debug logger for ZhiHand daemon.
  *
- * Enable with `zhihand start --debug` to see detailed request/response,
- * CLI spawn args, stdin/stdout data, SSE events, and timing information.
+ * Delegates to core/logger.ts for the debug flag, redaction, and output.
+ * All output goes to stderr to keep stdout clean for MCP JSON-RPC.
+ *
+ * Enable with `zhihand start --debug`.
  */
 export declare function setDebugEnabled(enabled: boolean): void;
 export declare function isDebugEnabled(): boolean;
-/** Debug log — only outputs when --debug is active. */
+/** Debug log — only outputs when --debug is active. Writes to stderr with redaction. */
 export declare function dbg(msg: string): void;

package/dist/daemon/logger.js

@@ -1,22 +1,21 @@
 /**
  * Debug logger for ZhiHand daemon.
  *
- * Enable with `zhihand start --debug` to see detailed request/response,
- * CLI spawn args, stdin/stdout data, SSE events, and timing information.
+ * Delegates to core/logger.ts for the debug flag, redaction, and output.
+ * All output goes to stderr to keep stdout clean for MCP JSON-RPC.
+ *
+ * Enable with `zhihand start --debug`.
  */
-let debugEnabled = false;
+import { log, setDebugEnabled as coreSetDebug, isDebugEnabled as coreIsDebug, } from "../core/logger.js";
 export function setDebugEnabled(enabled) {
-    debugEnabled = enabled;
+    coreSetDebug(enabled);
 }
 export function isDebugEnabled() {
-    return debugEnabled;
-}
-function ts() {
-    return new Date().toLocaleTimeString();
+    return coreIsDebug();
 }
-/** Debug log — only outputs when --debug is active. */
+/** Debug log — only outputs when --debug is active. Writes to stderr with redaction. */
 export function dbg(msg) {
-    if (!debugEnabled)
+    if (!coreIsDebug())
         return;
-    process.stdout.write(`[${ts()}] [DEBUG] ${msg}\n`);
+    log.debug(msg);
 }

package/dist/daemon/prompt-listener.d.ts

@@ -1,5 +1,3 @@
-import type { ZhiHandRuntimeConfig } from "../core/config.ts";
-type ZhiHandConfig = ZhiHandRuntimeConfig;
 export interface MobilePrompt {
     id: string;
     credential_id: string;
@@ -11,14 +9,21 @@ export interface MobilePrompt {
     attachments?: unknown[];
 }
 export type PromptHandler = (prompt: MobilePrompt) => void;
+/** Edge-level prompt listener config. Uses pluginSecret instead of per-user controllerToken. */
+export interface PromptListenerConfig {
+    controlPlaneEndpoint: string;
+    edgeId: string;
+    pluginSecret: string;
+}
 export declare class PromptListener {
     private config;
     private handler;
     private log;
+    private onFatalError?;
     private processedIds;
     private rws;
     private stopped;
-    constructor(config: ZhiHandConfig, handler: PromptHandler, log: (msg: string) => void);
+    constructor(config: PromptListenerConfig, handler: PromptHandler, log: (msg: string) => void, onFatalError?: (reason: string) => void);
     start(): void;
     stop(): void;
     private dispatchPrompt;
@@ -26,4 +31,3 @@ export declare class PromptListener {
     private handleWSMessage;
     private handleEvent;
 }
-export {};

package/dist/daemon/prompt-listener.js

@@ -4,13 +4,15 @@ export class PromptListener {
     config;
     handler;
     log;
+    onFatalError;
     processedIds = new Set();
     rws = null;
     stopped = false;
-    constructor(config, handler, log) {
+    constructor(config, handler, log, onFatalError) {
         this.config = config;
         this.handler = handler;
         this.log = log;
+        this.onFatalError = onFatalError;
     }
     start() {
         this.stopped = false;
@@ -27,7 +29,7 @@ export class PromptListener {
             return;
         }
         this.processedIds.add(prompt.id);
-        dbg(`[prompt] Dispatching prompt: id=${prompt.id}, status=${prompt.status}, text="${prompt.text.slice(0, 100)}${prompt.text.length > 100 ? "..." : ""}"`);
+        dbg(`[prompt] Dispatching prompt: id=${prompt.id}, cred=${prompt.credential_id}, status=${prompt.status}, text="${prompt.text.slice(0, 100)}${prompt.text.length > 100 ? "..." : ""}"`);
         // Prevent unbounded growth
         if (this.processedIds.size > 500) {
             const arr = [...this.processedIds];
@@ -38,21 +40,18 @@ export class PromptListener {
     connectWS() {
         if (this.stopped)
             return;
-        const wsUrl = `${this.config.controlPlaneEndpoint.replace(/^http/, "ws")}/v1/credentials/${encodeURIComponent(this.config.credentialId)}/ws?topic=prompts`;
+        // Edge-level WS: single connection for all credentials under this edge
+        const wsUrl = `${this.config.controlPlaneEndpoint.replace(/^http/, "ws")}/v1/plugins/${encodeURIComponent(this.config.edgeId)}/ws?topic=prompts`;
         dbg(`[ws] Connecting to ${wsUrl}`);
         this.rws = new ReconnectingWebSocket({
             url: wsUrl,
-            headers: {
-                "Authorization": `Bearer ${this.config.controllerToken}`,
-            },
+            headers: {},
             onOpen: () => {
-                // Send auth message as first frame (required by server).
+                // Send auth frame with pluginSecret (server verifies before streaming)
                 this.rws.send(JSON.stringify({
                     type: "auth",
-                    controller_token: this.config.controllerToken,
-                    topics: ["prompts"],
+                    plugin_secret: this.config.pluginSecret,
                 }));
-                // onConnected deferred until auth_ok is received (see handleWSMessage)
             },
             onClose: (_code, _reason) => {
                 dbg("[ws] Disconnected. ReconnectingWebSocket will retry.");
@@ -68,42 +67,38 @@ export class PromptListener {
     }
     handleWSMessage(data) {
         const msg = data;
-        // Auth responses
         if (msg.type === "auth_ok") {
-            this.log("[ws] Connected to prompt stream.");
+            this.log("[ws] Connected to Edge prompt stream.");
             return;
         }
         if (msg.type === "auth_error") {
-            this.log(`[ws] Auth failed: ${msg.error}`);
+            const reason = `Plugin auth failed: ${msg.error}. Run 'zhihand pair' to re-register.`;
+            this.log(`[ws] ${reason}`);
             this.rws?.stop();
             this.rws = null;
+            this.onFatalError?.(reason);
             return;
         }
-        // Application-level ping (if server sends these alongside protocol pings)
         if (msg.type === "ping") {
             this.rws?.send(JSON.stringify({ type: "pong" }));
             return;
         }
-        // Event dispatch
         if (msg.type === "event" || msg.kind) {
             this.handleEvent(msg);
         }
     }
     handleEvent(event) {
         const kind = event.kind;
-        dbg(`[ws] Event: kind=${kind}, prompt=${event.prompt?.id ?? "-"}, prompts=${event.prompts?.length ?? 0}`);
+        dbg(`[ws] Event: kind=${kind}, prompt=${event.prompt?.id ?? "-"}`);
         if (kind === "prompt.queued" && event.prompt) {
             this.dispatchPrompt(event.prompt);
         }
-        else if (kind === "prompt.snapshot" && event.prompts) {
-            for (const p of event.prompts) {
-                if (p.status === "pending" || p.status === "processing") {
-                    this.dispatchPrompt(p);
-                }
+        else if (kind === "prompt.snapshot" && event.prompt) {
+            // Edge WS sends individual snapshot events (one per pending prompt)
+            const p = event.prompt;
+            if (p.status === "pending" || p.status === "processing") {
+                this.dispatchPrompt(p);
             }
         }
-        else if (kind === "device_profile.updated") {
-            this.log("[device] device_profile.updated event received on prompts stream (ignored; registry handles it)");
-        }
     }
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare const PACKAGE_VERSION = "0.33.0";
+export declare const PACKAGE_VERSION = "0.34.0";
 export declare function createServer(): McpServer;
 export declare function startStdioServer(): Promise<void>;

package/dist/index.js

@@ -8,7 +8,7 @@ import { handlePair } from "./tools/pair.js";
 import { resolveTargetDevice } from "./tools/resolve.js";
 import { buildControlToolDescription, buildSystemToolDescription, buildScreenshotToolDescription, formatDeviceStatus, extractDynamic, } from "./core/device.js";
 import { registry } from "./core/registry.js";
-export const PACKAGE_VERSION = "0.33.0";
+export const PACKAGE_VERSION = "0.34.0";
 function errorResult(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhihand/mcp",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "private": false,
   "type": "module",
   "description": "ZhiHand MCP Server — phone control tools for Claude Code, Codex, Gemini CLI, and OpenClaw",