@zhihand/mcp 0.29.0 → 0.32.0

package/bin/zhihand

@@ -1,16 +1,36 @@
 #!/usr/bin/env node
 
 import os from "node:os";
+import fs from "node:fs";
 import { parseArgs } from "node:util";
 import { startStdioServer } from "../dist/index.js";
 import { startDaemon, stopDaemon, isAlreadyRunning } from "../dist/daemon/index.js";
 import { detectCLITools, formatDetectedTools } from "../dist/cli/detect.js";
-import { detectAndSetupOpenClaw } from "../dist/cli/openclaw.js";
-import { loadDefaultCredential, loadBackendConfig, saveBackendConfig, DEFAULT_MODELS } from "../dist/core/config.js";
-import { executePairing } from "../dist/core/pair.js";
+import {
+  loadConfig,
+  listUsers,
+  getUserRecord,
+  removeUser,
+  removeDeviceFromUser,
+  findDeviceOwner,
+  updateDeviceLabel,
+  updateControllerToken,
+  loadBackendConfig,
+  saveBackendConfig,
+  addUser,
+  DEFAULT_MODELS,
+  resolveConfig,
+  resolveDefaultEndpoint,
+} from "../dist/core/config.js";
+import {
+  executePairingNewUser,
+  executePairingAddDevice,
+} from "../dist/core/pair.js";
+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.32.0";
 
 const CLI_TOOL_MAP = {
   claude: "claudecode",
@@ -23,8 +43,10 @@ const { positionals, values } = parseArgs({
   strict: false,
   options: {
     device: { type: "string" },
+    label: { type: "string" },
     model: { type: "string", short: "m" },
     help: { type: "boolean", short: "h", default: false },
+    version: { type: "boolean", short: "v", default: false },
     detach: { type: "boolean", short: "d", default: false },
     debug: { type: "boolean", default: false },
     force: { type: "boolean", default: false },
@@ -32,42 +54,50 @@ const { positionals, values } = parseArgs({
   },
 });
 
-const command = positionals[0] ?? "serve";
+const command = positionals[0] ?? "mcp";
+
+if (values.version) {
+  console.log(VERSION);
+  process.exit(0);
+}
 
 if (values.help) {
   console.log(`
-zhihand — MCP Server and Relay for phone control
+zhihand v${VERSION} — MCP Server and Relay for phone control
 
 Usage:
   zhihand start              Start daemon (MCP Server + Relay, foreground)
   zhihand start -d           Start daemon in background (detach)
-  zhihand start --debug      Start daemon with verbose debug logging
   zhihand stop               Stop daemon
   zhihand status             Show status (pairing, backend, brain)
 
-  zhihand gemini             Switch backend to Gemini CLI (default model: flash)
-  zhihand claude             Switch backend to Claude Code (default model: sonnet)
-  zhihand codex              Switch backend to Codex CLI (default model: gpt-5.4-mini)
-  zhihand gemini --model pro Switch backend with custom model
+  zhihand gemini             Switch backend to Gemini CLI
+  zhihand claude             Switch backend to Claude Code
+  zhihand codex              Switch backend to Codex CLI
 
   zhihand setup              Interactive setup: pair + configure + start
-  zhihand pair               Pair with a phone device
+  zhihand pair [--label X]   Pair new user + first device + auto-configure MCP
+  zhihand pair <user_id>     Add device to existing user
+  zhihand list [<user_id>]   List users/devices with real-time online status
+  zhihand unpair <id>        Remove user (usr_*) or device (credential)
+  zhihand rename <cred> <n>  Rename a device (server-side + local)
+  zhihand export <user_id>   Export user credentials as JSON to stdout
+  zhihand import <file>      Import user credentials from JSON file
+  zhihand rotate <user_id>   Rotate controller token
   zhihand detect             Detect available CLI tools
 
-  zhihand list               List all available tests with IDs
-  zhihand test               Run all safe device tests (skips capability-gated)
-  zhihand test <ids>         Run specific test(s), e.g. 'zhihand test 4' or '4,9,20'
-  zhihand test all           Run ALL tests (including unsafe, e.g. power button)
-  zhihand test --force       Bypass capability gates (run anyway even if NOT ready)
-  zhihand serve              Start MCP Server (stdio mode, backward compat)
+  zhihand test [cred] [ids]  Run device tests (all, specific ids, or for a credential)
+  zhihand mcp                Start stdio MCP server (for Claude/Codex/Gemini hosts)
 
 Options:
-  --device <name>    Use a specific paired device
-  --model, -m <name> Set model alias (e.g. flash, pro, sonnet, opus, gpt-5.4-mini)
+  --device <name>    Use a specific paired credential_id (test only)
+  --label <label>    Label for new device (pair only)
+  --model, -m <name> Backend model alias
   --port <port>      Override daemon port (default: 18686)
   -d, --detach       Run daemon in background
-  --debug            Enable verbose debug logging
+  --debug            Verbose debug logging
   --force            (test only) Run tests even if capability not ready
+  -v, --version      Print version
   -h, --help         Show this help
 `);
   process.exit(0);
@@ -90,7 +120,6 @@ if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
     console.error(`Warning: ${command} is installed but not logged in.`);
   }
 
-  // Check if daemon is running — if so, notify it via HTTP
   const daemonPid = isAlreadyRunning();
   const config = loadBackendConfig();
   const previous = config.activeBackend;
@@ -105,11 +134,9 @@ if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
 
   console.log(`Switching backend to ${displayName(backendName)} (model: ${effectiveModel})...`);
 
-  // Configure MCP (HTTP transport)
   const { configured, removed } = configureMCP(backendName, previous);
 
   if (configured) {
-    // Notify daemon if running
     if (daemonPid) {
       try {
         const port = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || 18686;
@@ -123,7 +150,6 @@ if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
           console.log(`\nDaemon notified. Backend switched to ${displayName(backendName)}.`);
         }
       } catch {
-        // Daemon not responding, just save config
         saveBackendConfig({ activeBackend: backendName, model: userModel });
         console.log(`\nBackend config saved. Daemon not responding — restart with 'zhihand start'.`);
       }
@@ -153,10 +179,8 @@ switch (command) {
 
       const args = [process.argv[1], "start"];
       if (values.port) args.push("--port", values.port);
-      if (values.device) args.push("--device", values.device);
       if (values.debug) args.push("--debug");
 
-      // Write daemon logs to ~/.zhihand/daemon.log
       const zhihandDir = pathMod.default.join(osMod.default.homedir(), ".zhihand");
       fsSync.default.mkdirSync(zhihandDir, { recursive: true });
       const logPath = pathMod.default.join(zhihandDir, "daemon.log");
@@ -174,48 +198,327 @@ switch (command) {
       process.exit(0);
     }
     const port = values.port ? parseInt(values.port, 10) : undefined;
-    await startDaemon({
-      port,
-      deviceName: values.device ?? process.env.ZHIHAND_DEVICE,
-      debug: values.debug,
-    });
+    await startDaemon({ port, debug: values.debug });
     break;
   }
 
   case "stop": {
     const stopped = stopDaemon();
-    if (stopped) {
-      console.log("Daemon stopped.");
-    } else {
-      console.log("No daemon is running.");
-    }
+    console.log(stopped ? "Daemon stopped." : "No daemon is running.");
     break;
   }
 
+  case "mcp":
   case "serve": {
-    // Backward compatible: stdio MCP server (for old configs)
-    await startStdioServer(values.device ?? process.env.ZHIHAND_DEVICE);
+    await startStdioServer();
     break;
   }
 
   case "pair": {
-    const edgeId = `mcp-${Date.now().toString(36)}`;
-    const deviceName = values.device ?? `mcp-${os.hostname()}`;
-    await executePairing(DEFAULT_ENDPOINT, edgeId, deviceName);
+    const arg1 = positionals[1];
+    const label = values.label ?? undefined;
+
+    if (arg1 && arg1.startsWith("usr_")) {
+      // Add device to existing user
+      const deviceRecord = await executePairingAddDevice(arg1, label);
+      console.log(`\nDevice paired: ${deviceRecord.label} (${deviceRecord.credential_id})`);
+    } else {
+      // New user + first device
+      const { userRecord, deviceRecord } = await executePairingNewUser(label);
+      console.log(`\nUser created: ${userRecord.label} (${userRecord.user_id})`);
+      console.log(`Device paired: ${deviceRecord.label} (${deviceRecord.credential_id})`);
+      console.log(`\nAdd another device: zhihand pair ${userRecord.user_id}`);
+
+      // Auto-configure MCP hosts
+      const tools = await detectCLITools();
+      if (tools.length > 0) {
+        const best = tools.find((t) => t.loggedIn) ?? tools[0];
+        console.log(`\nAuto-configuring MCP for ${displayName(best.name)}...`);
+        const backendCfg = loadBackendConfig();
+        configureMCP(best.name, backendCfg.activeBackend);
+        saveBackendConfig({ activeBackend: best.name });
+      }
+    }
+    break;
+  }
+
+  case "list": {
+    const userIdFilter = positionals[1];
+    const users = listUsers();
+    const endpoint = resolveDefaultEndpoint();
+
+    if (users.length === 0) {
+      console.log("No users configured. Run: zhihand pair");
+      break;
+    }
+
+    const filteredUsers = userIdFilter
+      ? users.filter((u) => u.user_id === userIdFilter)
+      : users;
+
+    if (filteredUsers.length === 0) {
+      console.error(`User '${userIdFilter}' not found.`);
+      process.exit(1);
+    }
+
+    for (const user of filteredUsers) {
+      console.log(`\nUSER: ${user.label} (${user.user_id})`);
+
+      // Fetch real-time online status from server
+      let onlineMap = new Map();
+      try {
+        const creds = await fetchUserCredentials(endpoint, user.user_id, user.controller_token);
+        for (const c of creds) {
+          onlineMap.set(c.credential_id, c.online ?? false);
+        }
+      } catch {
+        // Fallback: no online status
+      }
+
+      if (user.devices.length === 0) {
+        console.log("  (no devices)");
+        continue;
+      }
+
+      const header = ["DEVICE_ID", "LABEL", "PLATFORM", "ONLINE", "PAIRED"];
+      const rows = user.devices.map((d) => [
+        d.credential_id,
+        d.label,
+        d.platform,
+        onlineMap.has(d.credential_id)
+          ? (onlineMap.get(d.credential_id) ? "yes" : "no")
+          : "?",
+        d.paired_at,
+      ]);
+      const widths = header.map((h, i) => Math.max(h.length, ...rows.map((row) => row[i].length)));
+      const fmt = (row) => row.map((c, i) => c.padEnd(widths[i])).join("  ");
+      console.log("  " + fmt(header));
+      console.log("  " + widths.map((w) => "-".repeat(w)).join("  "));
+      for (const r of rows) console.log("  " + fmt(r));
+    }
+    break;
+  }
+
+  case "unpair": {
+    const id = positionals[1];
+    if (!id) {
+      console.error("Usage: zhihand unpair <user_id | credential_id>");
+      process.exit(1);
+    }
+
+    const endpoint = resolveDefaultEndpoint();
+
+    if (id.startsWith("usr_")) {
+      // Delete user (cascade)
+      const user = getUserRecord(id);
+      if (!user) {
+        console.error(`User '${id}' not found.`);
+        process.exit(1);
+      }
+      // Best-effort server-side delete
+      try {
+        const res = await fetch(`${endpoint}/v1/users/${encodeURIComponent(id)}`, {
+          method: "DELETE",
+          headers: { "Authorization": `Bearer ${user.controller_token}` },
+          signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok) {
+          console.warn(`Warning: server delete returned ${res.status} (continuing to remove locally)`);
+        }
+      } catch (err) {
+        console.warn(`Warning: server delete failed: ${err.message} (continuing to remove locally)`);
+      }
+      removeUser(id);
+      console.log(`Removed user: ${id} (${user.label})`);
+    } else {
+      // Delete single credential
+      const owner = findDeviceOwner(id);
+      if (!owner) {
+        console.error(`Device '${id}' not found.`);
+        process.exit(1);
+      }
+      // Best-effort server-side delete
+      try {
+        const res = await fetch(`${endpoint}/v1/credentials/${encodeURIComponent(id)}`, {
+          method: "DELETE",
+          headers: { "Authorization": `Bearer ${owner.user.controller_token}` },
+          signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok) {
+          console.warn(`Warning: server delete returned ${res.status} (continuing to remove locally)`);
+        }
+      } catch (err) {
+        console.warn(`Warning: server delete failed: ${err.message} (continuing to remove locally)`);
+      }
+      removeDeviceFromUser(owner.user.user_id, id);
+      console.log(`Removed device: ${id}`);
+    }
+    break;
+  }
+
+  case "rename": {
+    const credId = positionals[1];
+    const newLabel = positionals[2];
+    if (!credId || !newLabel) {
+      console.error("Usage: zhihand rename <credential_id> <new_label>");
+      process.exit(1);
+    }
+    const owner = findDeviceOwner(credId);
+    if (!owner) {
+      console.error(`Device '${credId}' not found.`);
+      process.exit(1);
+    }
+    // Server-side PATCH
+    const endpoint = resolveDefaultEndpoint();
+    try {
+      const res = await fetch(`${endpoint}/v1/credentials/${encodeURIComponent(credId)}`, {
+        method: "PATCH",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${owner.user.controller_token}`,
+        },
+        body: JSON.stringify({ device_label: newLabel }),
+        signal: AbortSignal.timeout(5000),
+      });
+      if (!res.ok) {
+        console.warn(`Warning: server rename returned ${res.status}`);
+      }
+    } catch (err) {
+      console.warn(`Warning: server rename failed: ${err.message}`);
+    }
+    updateDeviceLabel(owner.user.user_id, credId, newLabel);
+    console.log(`Renamed ${credId} to '${newLabel}'`);
+    break;
+  }
+
+  case "export": {
+    const userId = positionals[1];
+    if (!userId) {
+      console.error("Usage: zhihand export <user_id>");
+      process.exit(1);
+    }
+    const user = getUserRecord(userId);
+    if (!user) {
+      console.error(`User '${userId}' not found.`);
+      process.exit(1);
+    }
+    // Plain JSON to stdout
+    console.log(JSON.stringify({ user_id: user.user_id, controller_token: user.controller_token }, null, 2));
+    break;
+  }
+
+  case "import": {
+    const filePath = positionals[1];
+    if (!filePath) {
+      console.error("Usage: zhihand import <file>");
+      process.exit(1);
+    }
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    } catch (err) {
+      console.error(`Error reading file: ${err.message}`);
+      process.exit(1);
+    }
+    if (!data.user_id || !data.controller_token) {
+      console.error("Invalid import file: must contain user_id and controller_token");
+      process.exit(1);
+    }
+    // Validate by fetching user info from server
+    const endpoint = resolveDefaultEndpoint();
+    let serverUser;
+    try {
+      const res = await fetch(`${endpoint}/v1/users/${encodeURIComponent(data.user_id)}`, {
+        headers: { "Authorization": `Bearer ${data.controller_token}` },
+        signal: AbortSignal.timeout(10000),
+      });
+      if (!res.ok) {
+        console.error(`Server validation failed: ${res.status}`);
+        process.exit(1);
+      }
+      serverUser = await res.json();
+    } catch (err) {
+      console.error(`Server validation failed: ${err.message}`);
+      process.exit(1);
+    }
+    // Fetch credentials
+    let creds = [];
+    try {
+      creds = await fetchUserCredentials(endpoint, data.user_id, data.controller_token);
+    } catch {
+      // Non-fatal
+    }
+    const devices = creds.map((c) => ({
+      credential_id: c.credential_id,
+      label: c.label ?? c.credential_id,
+      platform: c.platform ?? "unknown",
+      paired_at: c.paired_at ?? new Date().toISOString(),
+      last_seen_at: c.last_seen_at ?? new Date().toISOString(),
+    }));
+    const userRecord = {
+      user_id: data.user_id,
+      controller_token: data.controller_token,
+      label: serverUser.label ?? data.user_id,
+      created_at: serverUser.created_at ?? new Date().toISOString(),
+      devices,
+    };
+    addUser(userRecord);
+    console.log(`Imported user: ${userRecord.label} (${userRecord.user_id}) with ${devices.length} device(s)`);
+    break;
+  }
+
+  case "rotate": {
+    const userId = positionals[1];
+    if (!userId) {
+      console.error("Usage: zhihand rotate <user_id>");
+      process.exit(1);
+    }
+    const user = getUserRecord(userId);
+    if (!user) {
+      console.error(`User '${userId}' not found.`);
+      process.exit(1);
+    }
+    const endpoint = resolveDefaultEndpoint();
+    // Find current token ID (we need to pass it in the URL)
+    // The API is POST /v1/users/{id}/controller-tokens/{token}/rotate
+    try {
+      const res = await fetch(
+        `${endpoint}/v1/users/${encodeURIComponent(userId)}/controller-tokens/${encodeURIComponent(user.controller_token)}/rotate`,
+        {
+          method: "POST",
+          headers: { "Authorization": `Bearer ${user.controller_token}` },
+          signal: AbortSignal.timeout(10000),
+        },
+      );
+      if (!res.ok) {
+        console.error(`Rotate failed: ${res.status}`);
+        process.exit(1);
+      }
+      const result = await res.json();
+      updateControllerToken(userId, result.new_token);
+      console.log(`Token rotated for ${userId}. New token saved.`);
+    } catch (err) {
+      console.error(`Rotate failed: ${err.message}`);
+      process.exit(1);
+    }
     break;
   }
 
   case "status": {
-    const cred = loadDefaultCredential();
+    const users = listUsers();
     const backend = loadBackendConfig();
     const daemonPid = isAlreadyRunning();
 
-    if (cred) {
-      console.log(`Paired device: ${cred.deviceName}`);
-      console.log(`Credential ID: ${cred.credentialId}`);
-      console.log(`Endpoint: ${cred.endpoint}`);
+    if (users.length === 0) {
+      console.log("No users configured. Run: zhihand setup");
     } else {
-      console.log("No paired device. Run: zhihand setup");
+      console.log(`Users: ${users.length}`);
+      for (const u of users) {
+        console.log(`  ${u.user_id} (${u.label}) — ${u.devices.length} device(s)`);
+        for (const d of u.devices) {
+          console.log(`    ${d.credential_id} (${d.label}, ${d.platform})`);
+        }
+      }
     }
     const backendLabel = backend.activeBackend ? displayName(backend.activeBackend) : "(none)";
     const modelLabel = backend.activeBackend
@@ -224,7 +527,6 @@ switch (command) {
     console.log(`Active backend: ${backendLabel} (model: ${modelLabel})`);
     console.log(`Daemon: ${daemonPid ? `running (PID ${daemonPid})` : "not running"}`);
 
-    // If daemon running, get live status
     if (daemonPid) {
       try {
         const port = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || 18686;
@@ -248,20 +550,13 @@ switch (command) {
   }
 
   case "setup": {
-    // 1. Pair
-    let cred = loadDefaultCredential();
-    if (!cred) {
-      console.log("No paired device found. Starting pairing...\n");
-      const edgeId = `mcp-${Date.now().toString(36)}`;
-      const deviceName = values.device ?? `mcp-${os.hostname()}`;
-      await executePairing(DEFAULT_ENDPOINT, edgeId, deviceName);
-      cred = loadDefaultCredential();
-    }
-    if (cred) {
-      console.log(`\nPaired: ${cred.deviceName} (${cred.credentialId})\n`);
+    const users = listUsers();
+    if (users.length === 0) {
+      console.log("No users found. Starting pairing...\n");
+      const { userRecord } = await executePairingNewUser(values.label);
+      console.log(`\nUser created: ${userRecord.label} (${userRecord.user_id})\n`);
     }
 
-    // 2. Detect tools
     const tools = await detectCLITools();
     console.log(formatDetectedTools(tools));
 
@@ -270,88 +565,51 @@ switch (command) {
       break;
     }
 
-    // 3. Auto-select best tool and configure MCP (HTTP transport)
     const best = tools.find((t) => t.loggedIn) ?? tools[0];
     const config = loadBackendConfig();
 
     console.log(`\nAuto-selecting backend: ${displayName(best.name)}...`);
-    // Ensure MCP URL uses correct port
-    if (values.port) {
-      process.env.ZHIHAND_PORT = values.port;
-    }
+    if (values.port) process.env.ZHIHAND_PORT = values.port;
     configureMCP(best.name, config.activeBackend);
     saveBackendConfig({ activeBackend: best.name });
 
-    // 4. Start daemon
     console.log(`\nStarting daemon...\n`);
     const port = values.port ? parseInt(values.port, 10) : undefined;
-    await startDaemon({
-      port,
-      deviceName: values.device ?? process.env.ZHIHAND_DEVICE,
-    });
+    await startDaemon({ port });
     break;
   }
 
-  case "list":
   case "test": {
-    const { resolveConfig: resolveTestConfig } = await import("../dist/core/config.js");
     const { createControlCommand, createSystemCommand, enqueueCommand } = await import("../dist/core/command.js");
     const { waitForCommandAck } = await import("../dist/core/sse.js");
     const { fetchScreenshot, getSnapshotStaleThresholdMs } = await import("../dist/core/screenshot.js");
-    const { fetchDeviceProfile, getStaticContext, isDeviceProfileLoaded, formatDeviceStatus, getCapabilities } = await import("../dist/core/device.js");
-
-    // ── Test Registry ────────────────────────────────────────
-    // Kind: "profile" | "status" | "screenshot" | "hid" | "system"
-    //   - Each kind maps to a required capability (see KIND_CAPABILITY).
-    // Platform: undefined | "android" | "ios" (skipped on non-matching)
-    // Unsafe: won't run in full-suite unless explicitly requested
-
-    // Required capability per test kind. Tests whose required capability
-    // is not ready are SKIPPED (not failed), unless --force is passed.
-    //
-    // NOTE: `system` commands (volume, brightness, notification, media,
-    // etc.) are executed by the phone app via native OS APIs
-    // (AccessibilityService on Android, Shortcuts/system hooks on iOS)
-    // and do NOT depend on the BLE HID channel. Only the `hid` kind
-    // (click, swipe, type, keycombo — which inject into the paired
-    // target via the ZhiHand peripheral) needs the HID capability.
+    const { fetchDeviceProfileOnce, extractStatic, computeCapabilities, formatDeviceStatus } = await import("../dist/core/device.js");
+
     const KIND_CAPABILITY = {
-      profile: "none",
-      status: "none",
-      screenshot: "screen",
-      hid: "hid",
-      system: "none",
+      profile: "none", status: "none", screenshot: "screen", hid: "hid", system: "none",
     };
     const REGISTRY = [
-      // Phase A — Device Info API
       { id: 1, phase: "Device Info", label: "Fetch device profile", kind: "profile" },
       { id: 2, phase: "Device Info", label: "Device status fields", kind: "status" },
-      // Phase B — Screenshot
       { id: 3, phase: "Screenshot", label: "Screenshot", kind: "screenshot" },
-      // Phase C — Tap / Touch
       { id: 4, phase: "Tap/Touch", label: "Click center", kind: "hid", params: { action: "click", xRatio: 0.5, yRatio: 0.5 } },
       { id: 5, phase: "Tap/Touch", label: "Double click", kind: "hid", params: { action: "doubleclick", xRatio: 0.5, yRatio: 0.5 } },
       { id: 6, phase: "Tap/Touch", label: "Long click (800ms)", kind: "hid", params: { action: "longclick", xRatio: 0.5, yRatio: 0.5, durationMs: 800 } },
       { id: 7, phase: "Tap/Touch", label: "Right click", kind: "hid", params: { action: "rightclick", xRatio: 0.5, yRatio: 0.5 } },
       { id: 8, phase: "Tap/Touch", label: "Middle click", kind: "hid", params: { action: "middleclick", xRatio: 0.5, yRatio: 0.5 } },
-      // Phase D — Swipe / Scroll
       { id: 9, phase: "Swipe/Scroll", label: "Swipe up", kind: "hid", params: { action: "swipe", startXRatio: 0.5, startYRatio: 0.7, endXRatio: 0.5, endYRatio: 0.3, durationMs: 300 } },
       { id: 10, phase: "Swipe/Scroll", label: "Swipe down", kind: "hid", params: { action: "swipe", startXRatio: 0.5, startYRatio: 0.3, endXRatio: 0.5, endYRatio: 0.7, durationMs: 300 } },
       { id: 11, phase: "Swipe/Scroll", label: "Swipe left", kind: "hid", params: { action: "swipe", startXRatio: 0.7, startYRatio: 0.5, endXRatio: 0.3, endYRatio: 0.5, durationMs: 300 } },
       { id: 12, phase: "Swipe/Scroll", label: "Swipe right", kind: "hid", params: { action: "swipe", startXRatio: 0.3, startYRatio: 0.5, endXRatio: 0.7, endYRatio: 0.5, durationMs: 300 } },
       { id: 13, phase: "Swipe/Scroll", label: "Scroll down", kind: "hid", params: { action: "scroll", xRatio: 0.5, yRatio: 0.5, direction: "down", amount: 3 } },
       { id: 14, phase: "Swipe/Scroll", label: "Scroll up", kind: "hid", params: { action: "scroll", xRatio: 0.5, yRatio: 0.5, direction: "up", amount: 3 } },
-      // Phase E — Text + Keys
       { id: 15, phase: "Text+Keys", label: "Type text", kind: "hid", params: { action: "type", text: "zhihand" } },
       { id: 16, phase: "Text+Keys", label: "Enter key", kind: "hid", params: { action: "enter" } },
       { id: 17, phase: "Text+Keys", label: "Key combo (select all)", kind: "hid", platformAware: "select_all" },
-      // Phase F — App Navigation
       { id: 18, phase: "Navigation", label: "Press Home", kind: "hid", params: { action: "home" } },
       { id: 19, phase: "Navigation", label: "Press Back", kind: "hid", params: { action: "back" } },
       { id: 20, phase: "Navigation", label: "Open WeChat", kind: "hid", platformAware: "open_wechat" },
-      // Phase G — Clipboard
       { id: 21, phase: "Clipboard", label: "Clipboard set", kind: "hid", platformAware: "clipboard_set" },
-      // Phase H — System Navigation
       { id: 22, phase: "System Nav", label: "Notification shade", kind: "system", params: { action: "notification" } },
       { id: 23, phase: "System Nav", label: "Recent apps", kind: "system", params: { action: "recent" } },
       { id: 24, phase: "System Nav", label: "Search (query='zhihand')", kind: "system", params: { action: "search", text: "zhihand" } },
@@ -360,7 +618,6 @@ switch (command) {
       { id: 27, phase: "System Nav", label: "Control Center", kind: "system", params: { action: "control_center" }, platform: "ios" },
       { id: 28, phase: "System Nav", label: "Open browser", kind: "system", params: { action: "open_browser" }, platform: "android" },
       { id: 29, phase: "System Nav", label: "Shortcut help", kind: "system", params: { action: "shortcut_help" }, platform: "android" },
-      // Phase I — Media
       { id: 30, phase: "Media", label: "Volume up", kind: "system", params: { action: "volume_up" } },
       { id: 31, phase: "Media", label: "Volume down", kind: "system", params: { action: "volume_down" } },
       { id: 32, phase: "Media", label: "Mute toggle", kind: "system", params: { action: "mute" } },
@@ -370,50 +627,36 @@ switch (command) {
       { id: 36, phase: "Media", label: "Fast forward", kind: "system", params: { action: "fast_forward" } },
       { id: 37, phase: "Media", label: "Rewind", kind: "system", params: { action: "rewind" } },
       { id: 38, phase: "Media", label: "Stop", kind: "system", params: { action: "stop" } },
-      // Phase J — Hardware
       { id: 39, phase: "Hardware", label: "Brightness up", kind: "system", params: { action: "brightness_up" } },
       { id: 40, phase: "Hardware", label: "Brightness down", kind: "system", params: { action: "brightness_down" } },
-      { id: 41, phase: "Hardware", label: "Power button (⚠️ may lock screen)", kind: "system", params: { action: "power" }, unsafe: true },
+      { id: 41, phase: "Hardware", label: "Power button (may lock screen)", kind: "system", params: { action: "power" }, unsafe: true },
     ];
 
-    // ── "list" sub-command ───────────────────────────────────
-    if (command === "list") {
-      console.log("📋 ZhiHand Test Registry\n");
-      let currentPhase = "";
-      for (const t of REGISTRY) {
-        if (t.phase !== currentPhase) {
-          console.log(`\n   ── ${t.phase} ──`);
-          currentPhase = t.phase;
-        }
-        const tags = [];
-        if (t.platform) tags.push(`${t.platform}-only`);
-        if (t.unsafe) tags.push("unsafe");
-        const tagStr = tags.length ? ` [${tags.join(", ")}]` : "";
-        console.log(`   ${String(t.id).padStart(2)}. ${t.label}${tagStr}`);
+    // Parse first positional: credential_id (crd_*) or test ids
+    let credentialArg = values.device ?? process.env.ZHIHAND_DEVICE;
+    let filterArg = null;
+    const arg1 = positionals[1];
+    const arg2 = positionals[2];
+    if (arg1) {
+      if (/^crd_/.test(arg1)) {
+        credentialArg = arg1;
+        filterArg = arg2 ?? null;
+      } else {
+        filterArg = arg1;
       }
-      console.log(`\n   Total: ${REGISTRY.length} tests`);
-      console.log("\nUsage:");
-      console.log("   zhihand test            # run all safe tests");
-      console.log("   zhihand test 4          # run test #4 only");
-      console.log("   zhihand test 4,9,20     # run tests #4, #9, #20");
-      console.log("   zhihand test all        # run ALL tests (including unsafe)");
-      process.exit(0);
     }
 
-    // ── "test" sub-command ───────────────────────────────────
     let testConfig;
     try {
-      testConfig = resolveTestConfig(values.device ?? process.env.ZHIHAND_DEVICE);
+      testConfig = resolveConfig(credentialArg);
     } catch (err) {
       console.error(`Error: ${err.message}`);
-      console.error("Run 'zhihand setup' to pair a device first.");
+      console.error("Run 'zhihand pair' to add a device first.");
       process.exit(1);
     }
 
-    // Parse which tests to run from positional args
-    const filterArg = positionals[1];  // e.g. "4" or "4,9,20" or "all"
     const forceRun = values.force === true;
-    let selectedIds = null;   // null = default (all safe)
+    let selectedIds = null;
     let includeUnsafe = false;
     if (filterArg) {
       if (filterArg === "all") {
@@ -423,56 +666,55 @@ switch (command) {
           filterArg.split(",").map((s) => {
             const trimmed = s.trim();
             const n = Number(trimmed);
-            // Strict: reject ranges like "4-10" (Number returns NaN), floats, empty
             return Number.isInteger(n) && n > 0 ? n : NaN;
           }).filter((n) => !isNaN(n))
         );
         if (selectedIds.size === 0) {
           console.error(`Invalid test IDs: ${filterArg}`);
-          console.error("Run 'zhihand list' to see available tests.");
           process.exit(1);
         }
-        // Explicit selection implies user knows what they're doing
         includeUnsafe = true;
       }
     }
 
-    console.log("🧪 ZhiHand Device Test");
+    console.log("ZhiHand Device Test");
     console.log(`   Device: ${testConfig.credentialId}`);
     console.log(`   Endpoint: ${testConfig.controlPlaneEndpoint}\n`);
 
-    // Pre-fetch device profile so platform-aware tests work.
-    // Note: platform is read dynamically via getDevicePlatform() so Test 1
-    // (Fetch device profile) can populate it before later tests consume it.
+    // Pre-fetch device profile
+    let currentRawAttrs = {};
+    let currentProfile = null;
+    let currentCaps = null;
+    let profileReceivedAtMs = 0;
     try {
-      await fetchDeviceProfile(testConfig);
-    } catch { /* non-fatal — Test 1 will retry and platform will update */ }
-    const getDevicePlatform = () => isDeviceProfileLoaded() ? getStaticContext().platform : "unknown";
-
-    // ── Capability readiness pre-flight ──
-    console.log("   ── Capability readiness ──");
-    const preCaps = isDeviceProfileLoaded() ? getCapabilities() : null;
-    if (!preCaps) {
-      console.log("   ⚠️  Device profile not loaded — all capability gates will allow tests through.");
+      const fetched = await fetchDeviceProfileOnce(testConfig);
+      if (fetched) {
+        currentRawAttrs = fetched.rawAttrs;
+        profileReceivedAtMs = fetched.receivedAtMs;
+        currentProfile = extractStatic(currentRawAttrs);
+        currentCaps = computeCapabilities(currentRawAttrs, profileReceivedAtMs);
+      }
+    } catch { /* non-fatal */ }
+    const getDevicePlatform = () => currentProfile?.platform ?? "unknown";
+
+    console.log("   -- Capability readiness --");
+    if (!currentCaps) {
+      console.log("   [!] Device profile not loaded — all capability gates will allow tests through.");
     } else {
-      const fmt = (name, cap) => `   ${cap.ready ? "✅" : "⚠️"} ${name.padEnd(14)} ${cap.ready ? "ready" : "NOT ready"}  — ${cap.reason}`;
-      console.log(fmt("screen_sharing", preCaps.screen_sharing));
-      console.log(fmt("hid",            preCaps.hid));
-      console.log(fmt("live_session",   preCaps.live_session));
-      const ageStr = preCaps.profile.age_ms >= 0 ? `${(preCaps.profile.age_ms / 1000).toFixed(1)}s` : "unknown";
-      console.log(`   ${preCaps.profile.stale ? "⚠️" : "✅"} profile        age=${ageStr}${preCaps.profile.stale ? " (STALE)" : ""}`);
+      const fmt = (name, cap) => `   ${cap.ready ? "[ok]" : "[!]"} ${name.padEnd(14)} ${cap.ready ? "ready" : "NOT ready"}  — ${cap.reason}`;
+      console.log(fmt("screen_sharing", currentCaps.screen_sharing));
+      console.log(fmt("hid", currentCaps.hid));
+      console.log(fmt("live_session", currentCaps.live_session));
+      const ageStr = currentCaps.profile.age_ms >= 0 ? `${(currentCaps.profile.age_ms / 1000).toFixed(1)}s` : "unknown";
+      console.log(`   ${currentCaps.profile.stale ? "[!]" : "[ok]"} profile        age=${ageStr}${currentCaps.profile.stale ? " (STALE)" : ""}`);
       if (forceRun) {
         console.log("   --force passed: capability gates disabled.");
       }
     }
     console.log("");
 
-    let passed = 0;
-    let failed = 0;
-    let skipped = 0;
-    let totalSteps = 0;
+    let passed = 0, failed = 0, skipped = 0, totalSteps = 0;
 
-    // ── Resolve platform-aware params (evaluated at test time) ──
     function resolvePlatformAwareParams(variant) {
       const platform = getDevicePlatform();
       if (variant === "open_wechat") {
@@ -490,7 +732,6 @@ switch (command) {
       return null;
     }
 
-    // ── Test runners (shared ACK logic) ──
     async function runCommandTest(t, command) {
       totalSteps++;
       process.stdout.write(`   ${String(t.id).padStart(2)}. ${t.label}... `);
@@ -503,43 +744,36 @@ switch (command) {
           const ackStatus = ack.command?.ack_status ?? "ok";
           const resultInfo = ack.command?.ack_result ? ` ${JSON.stringify(ack.command.ack_result)}` : "";
           if (ackStatus === "ok") {
-            console.log(`✅ (${ms}ms)${resultInfo}`);
+            console.log(`[PASS] (${ms}ms)${resultInfo}`);
             passed++;
           } else {
-            console.log(`❌ [${ackStatus}] (${ms}ms)${resultInfo}`);
+            console.log(`[FAIL] [${ackStatus}] (${ms}ms)${resultInfo}`);
             failed++;
           }
         } else {
-          console.log(`⏱️  Timeout (${ms}ms)`);
+          console.log(`[TIMEOUT] (${ms}ms)`);
           failed++;
         }
       } catch (err) {
-        console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
+        console.log(`[FAIL] ${err.message} (${Date.now() - t0}ms)`);
         failed++;
       }
     }
 
     async function runSingleTest(t) {
-      // Platform skip (evaluated at test time — Test 1 may have just populated the profile)
       const currentPlatform = getDevicePlatform();
       if (t.platform && t.platform !== currentPlatform) {
-        totalSteps++;
-        skipped++;
-        console.log(`   ${String(t.id).padStart(2)}. ${t.label}... ⏭️  Skipped (${t.platform}-only, device is ${currentPlatform})`);
+        totalSteps++; skipped++;
+        console.log(`   ${String(t.id).padStart(2)}. ${t.label}... [SKIP] (${t.platform}-only, device is ${currentPlatform})`);
         return;
       }
-
-      // Capability gate (unless --force) — evaluated per-test so later
-      // tests see fresh readiness flags pushed after Test 1's profile fetch.
-      if (!forceRun && isDeviceProfileLoaded()) {
+      if (!forceRun && currentCaps) {
         const requiredCap = KIND_CAPABILITY[t.kind] ?? "none";
         if (requiredCap !== "none") {
-          const caps = getCapabilities();
-          const gate = requiredCap === "screen" ? caps.screen_sharing : caps.hid;
+          const gate = requiredCap === "screen" ? currentCaps.screen_sharing : currentCaps.hid;
           if (!gate.ready) {
-            totalSteps++;
-            skipped++;
-            console.log(`   ${String(t.id).padStart(2)}. ${t.label}... ⏭️  Skipped (${requiredCap} not ready: ${gate.reason})`);
+            totalSteps++; skipped++;
+            console.log(`   ${String(t.id).padStart(2)}. ${t.label}... [SKIP] (${requiredCap} not ready: ${gate.reason})`);
             return;
           }
         }
@@ -551,18 +785,22 @@ switch (command) {
           process.stdout.write(`   ${String(t.id).padStart(2)}. ${t.label}... `);
           const t0 = Date.now();
           try {
-            await fetchDeviceProfile(testConfig);
+            const fetched = await fetchDeviceProfileOnce(testConfig);
             const ms = Date.now() - t0;
-            if (isDeviceProfileLoaded()) {
-              const s = getStaticContext();
-              console.log(`✅ ${s.platform} ${s.model}, ${s.osVersion}, ${s.screenWidthPx}x${s.screenHeightPx} (${ms}ms)`);
+            if (fetched) {
+              currentRawAttrs = fetched.rawAttrs;
+              profileReceivedAtMs = fetched.receivedAtMs;
+              currentProfile = extractStatic(currentRawAttrs);
+              currentCaps = computeCapabilities(currentRawAttrs, profileReceivedAtMs);
+              const s = currentProfile;
+              console.log(`[PASS] ${s.platform} ${s.model}, ${s.osVersion}, ${s.screenWidthPx}x${s.screenHeightPx} (${ms}ms)`);
               passed++;
             } else {
-              console.log(`⚠️  Loaded but empty (${ms}ms)`);
+              console.log(`[!] Loaded but empty (${ms}ms)`);
               failed++;
             }
           } catch (err) {
-            console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
+            console.log(`[FAIL] ${err.message} (${Date.now() - t0}ms)`);
             failed++;
           }
           break;
@@ -571,23 +809,33 @@ switch (command) {
           totalSteps++;
           process.stdout.write(`   ${String(t.id).padStart(2)}. ${t.label}... `);
           try {
-            const status = formatDeviceStatus();
-            // Count curated top-level fields (excluding the nested 'raw'
-            // and 'capabilities' containers) plus every allowlisted raw
-            // attribute — this is what the LLM actually sees via
-            // zhihand_status.
+            const state = {
+              credentialId: testConfig.credentialId,
+              userId: "",
+              userLabel: "",
+              label: "(test)",
+              platform: getDevicePlatform(),
+              online: true,
+              lastSeenAtMs: Date.now(),
+              profile: currentProfile,
+              capabilities: currentCaps,
+              profileReceivedAtMs,
+              rawAttributes: currentRawAttrs,
+              record: { credential_id: testConfig.credentialId, label: "", platform: "unknown", paired_at: "", last_seen_at: "" },
+            };
+            const status = formatDeviceStatus(state);
             const topLevel = Object.keys(status).filter((k) => k !== "raw" && k !== "capabilities");
             const rawKeys = Object.keys(status.raw ?? {});
             const caps = status.capabilities ?? {};
             const capReadySummary = ["screen_sharing", "hid", "live_session"]
               .map((k) => `${k}=${caps[k]?.ready ? "ready" : "not-ready"}`)
               .join(", ");
-            console.log(`✅ ${topLevel.length} curated + ${rawKeys.length} raw attributes; ${capReadySummary}`);
+            console.log(`[PASS] ${topLevel.length} curated + ${rawKeys.length} raw attributes; ${capReadySummary}`);
             console.log(`      curated: ${topLevel.join(", ")}`);
             console.log(`      raw:     ${rawKeys.join(", ")}`);
             passed++;
           } catch (err) {
-            console.log(`❌ ${err.message}`);
+            console.log(`[FAIL] ${err.message}`);
             failed++;
           }
           break;
@@ -601,37 +849,34 @@ switch (command) {
             const queued = await enqueueCommand(testConfig, cmd);
             const ack = await waitForCommandAck(testConfig, { commandId: queued.id, timeoutMs: 10_000 });
             if (!ack.acked) {
-              console.log(`⏱️  Timeout (${Date.now() - t0}ms)`);
+              console.log(`[TIMEOUT] (${Date.now() - t0}ms)`);
               failed++;
               break;
             }
             const shot = await fetchScreenshot(testConfig);
             const kb = (shot.buffer.length / 1024).toFixed(0);
             const ms = Date.now() - t0;
-            // The screenshot endpoint returns the last cached frame even
-            // when the phone isn't actively sharing — the age header is
-            // the only way to tell. Treat stale as failure.
             if (shot.stale) {
               const threshold = getSnapshotStaleThresholdMs();
-              console.log(`❌ Stale (${kb}KB, age=${(shot.ageMs / 1000).toFixed(1)}s > ${(threshold / 1000).toFixed(1)}s) ${shot.width}x${shot.height} seq=${shot.sequence} — phone may not be screen-sharing (${ms}ms)`);
+              console.log(`[FAIL] Stale (${kb}KB, age=${(shot.ageMs / 1000).toFixed(1)}s > ${(threshold / 1000).toFixed(1)}s) ${shot.width}x${shot.height} seq=${shot.sequence} — phone may not be screen-sharing (${ms}ms)`);
               failed++;
             } else {
-              console.log(`✅ ${kb}KB, ${shot.width}x${shot.height}, age=${shot.ageMs >= 0 ? `${shot.ageMs}ms` : "?"}, seq=${shot.sequence} (${ms}ms)`);
+              console.log(`[PASS] ${kb}KB, ${shot.width}x${shot.height}, age=${shot.ageMs >= 0 ? `${shot.ageMs}ms` : "?"}, seq=${shot.sequence} (${ms}ms)`);
               passed++;
             }
           } catch (err) {
-            console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
+            console.log(`[FAIL] ${err.message} (${Date.now() - t0}ms)`);
             failed++;
           }
           break;
         }
         case "hid": {
           const params = t.platformAware ? resolvePlatformAwareParams(t.platformAware) : t.params;
-          await runCommandTest(t, createControlCommand(params));
+          await runCommandTest(t, createControlCommand(params, getDevicePlatform()));
           break;
         }
         case "system": {
-          await runCommandTest(t, createSystemCommand(t.params));
+          await runCommandTest(t, createSystemCommand(t.params, getDevicePlatform()));
           break;
         }
       }
@@ -639,7 +884,6 @@ switch (command) {
 
     const pause = () => new Promise((r) => setTimeout(r, 1500));
 
-    // Select tests to run
     const toRun = REGISTRY.filter((t) => {
       if (selectedIds) return selectedIds.has(t.id);
       if (t.unsafe && !includeUnsafe) return false;
@@ -648,37 +892,29 @@ switch (command) {
 
     if (toRun.length === 0) {
       console.error("No matching tests.");
-      console.error("Run 'zhihand list' to see available tests.");
       process.exit(1);
     }
 
-    // Warn about missing IDs
     if (selectedIds) {
       const foundIds = new Set(toRun.map((t) => t.id));
       const missing = [...selectedIds].filter((id) => !foundIds.has(id));
-      if (missing.length) {
-        console.warn(`⚠️  Unknown test IDs: ${missing.join(", ")}`);
-      }
+      if (missing.length) console.warn(`[!] Unknown test IDs: ${missing.join(", ")}`);
     }
 
     let currentPhase = "";
     for (let i = 0; i < toRun.length; i++) {
       const t = toRun[i];
       if (t.phase !== currentPhase) {
-        console.log(`   ── ${t.phase} ──`);
+        console.log(`   -- ${t.phase} --`);
         currentPhase = t.phase;
       }
       await runSingleTest(t);
       if (i < toRun.length - 1) await pause();
     }
 
-    // ── Summary ──────────────────────────────────────────────
     console.log(`\n   Result: ${passed}/${totalSteps} passed, ${failed} failed, ${skipped} skipped`);
-    if (failed === 0) {
-      console.log("   ✅ All tests passed! Device is fully responsive.");
-    } else {
-      console.log(`   ⚠️  ${failed} test(s) failed. Check phone connectivity.`);
-    }
+    if (failed === 0) console.log("   All tests passed! Device is fully responsive.");
+    else console.log(`   ${failed} test(s) failed. Check phone connectivity.`);
     process.exit(failed > 0 ? 1 : 0);
   }