@agentlayer.tech/wallet 0.1.30 → 0.1.33

package/bin/openclaw-agent-wallet.mjs

@@ -392,6 +392,17 @@ function switchSymlink(linkPath, targetPath) {
   fs.renameSync(tempLink, linkPath);
 }
 
+// Remove a runtime pointer symlink (current/previous). recursive+force tolerate
+// a stray directory in that slot; on a symlink this unlinks the pointer only and
+// never deletes the release directory it targets.
+function removeRuntimePointer(pointerPath) {
+  try {
+    fs.rmSync(pointerPath, { recursive: true, force: true });
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
 function parseFlagValue(args, name) {
   const prefix = `${name}=`;
   for (let index = 0; index < args.length; index += 1) {
@@ -617,56 +628,214 @@ function ensureBootKeyFile(env = process.env) {
   return { path: keyFile, status: "created" };
 }
 
-function runDoctor() {
-  const requiredPaths = [
-    ["setup.sh", setupPath],
-    ["agent-wallet", path.join(packageRoot, "agent-wallet")],
-    ["OpenClaw extension", path.join(packageRoot, ".openclaw", "extensions", "agent-wallet")],
-    ["Codex plugin", path.join(packageRoot, "codex", "plugins", "agent-wallet", ".codex-plugin", "plugin.json")],
-    ["Claude Code plugin", path.join(packageRoot, "claude-code", "plugins", "agent-wallet", ".claude-plugin", "plugin.json")],
-    ["wdk-btc-wallet", path.join(packageRoot, "wdk-btc-wallet", "package.json")],
-    ["wdk-evm-wallet", path.join(packageRoot, "wdk-evm-wallet", "package.json")],
+function resolveVenvPython(releaseRoot) {
+  const candidates = [
+    path.join(releaseRoot, "agent-wallet", ".venv", "bin", "python"),
+    path.join(releaseRoot, "agent-wallet", ".runtime-venv", "bin", "python"),
   ];
-  const commands = ["node", "npm"];
-  const missing = [];
-  const python = selectedPythonProbe();
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+// Classify a verification failure so the caller can route the right guidance:
+//   broken_release -> our shipped code is bad; user cannot fix, stay on previous.
+//   local_env      -> user's machine/runtime is fixable (python/venv/corrupt unpack).
+//   unknown        -> fall back to generic guidance.
+function classifyVerifyError(detail) {
+  const text = String(detail || "");
+  if (/SyntaxError|IndentationError|ImportError|ModuleNotFoundError|TabError|NameError/.test(text)) {
+    return "broken_release";
+  }
+  if (/ENOENT|python|venv|ensurepip|not found|No such file|Permission denied|spawn/i.test(text)) {
+    return "local_env";
+  }
+  return "unknown";
+}
 
-  for (const command of commands) {
-    if (!hasCommand(command)) missing.push(`command:${command}`);
+function verifyRuntime(releaseRoot, env = process.env) {
+  if (String(env.AGENT_WALLET_VERIFY_DISABLE || "") === "1") {
+    return { ok: true, skipped: true };
   }
-  if (!python.path) {
-    missing.push("command:python3.10-or-python3");
-  } else if (!python.version_ok) {
-    missing.push(`python>=3.10:selected:${python.version || "unknown"}`);
-  } else if (!python.venv_ok) {
-    missing.push(`python-venv-ensurepip:selected:${python.version || "unknown"}`);
+  if (String(env.AGENT_WALLET_VERIFY_FORCE_FAIL || "") === "1") {
+    return { ok: false, error: "verify forced to fail (AGENT_WALLET_VERIFY_FORCE_FAIL)", category: "broken_release" };
   }
-  for (const [label, target] of requiredPaths) {
-    if (!fs.existsSync(target)) missing.push(`${label}:${target}`);
+  const serverPy = path.join(releaseRoot, "codex", "plugins", "agent-wallet", "server.py");
+  if (!fs.existsSync(serverPy)) {
+    return { ok: false, error: `server.py missing at ${serverPy}`, category: "local_env" };
   }
+  const python =
+    env.AGENT_WALLET_PYTHON ||
+    env.OPENCLAW_AGENT_WALLET_PYTHON ||
+    resolveVenvPython(releaseRoot) ||
+    commandPath("python3") ||
+    "python3";
+  const initLine = JSON.stringify({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "verify", version: "0" } },
+  });
+  const probe = spawnSync(python, [serverPy], {
+    input: initLine + "\n",
+    encoding: "utf8",
+    timeout: Number(env.AGENT_WALLET_VERIFY_TIMEOUT_MS || 25000),
+    env: { ...env, FASTMCP_SHOW_SERVER_BANNER: "false", FASTMCP_LOG_LEVEL: "ERROR" },
+  });
+  if (probe.error) {
+    const isTimeout = String(probe.error.message || "").includes("ETIMEDOUT");
+    return {
+      ok: false,
+      error: `handshake ${isTimeout ? "timed out (server did not respond)" : "spawn failed"}: ${probe.error.message}`,
+      category: isTimeout ? "broken_release" : "local_env",
+    };
+  }
+  const out = String(probe.stdout || "");
+  if (out.includes('"serverInfo"')) {
+    return { ok: true };
+  }
+  const detail = (probe.stderr || out || "").trim().split("\n").slice(-3).join(" ");
+  return {
+    ok: false,
+    error: `MCP initialize handshake failed: ${detail || "no serverInfo in response"}`,
+    category: classifyVerifyError(detail),
+  };
+}
+
+function resolveEditorServerChecks(env = process.env) {
+  const checks = [];
+  // Claude Code's launcher (run_mcp.sh) falls back to the runtime codex
+  // server.py when its own plugin-cache copy lacks one, so a present runtime
+  // server.py is exactly what that launcher will exec. We check its presence
+  // as the proxy for "Claude can resolve a server" (we do not inspect the
+  // version-specific cache copy directly).
+  const root = resolvedCurrentRuntimeRoot(env);
+  const runtimeCodex = root ? path.join(root, "codex", "plugins", "agent-wallet", "server.py") : null;
+  const claudeCacheRoot = expandHome("~/.claude/plugins/cache");
+  if (fs.existsSync(claudeCacheRoot)) {
+    const reachable = Boolean(runtimeCodex && fs.existsSync(runtimeCodex));
+    checks.push({
+      name: "editor:claude-code",
+      ok: reachable,
+      error: reachable ? "" : "Claude cache copy cannot resolve server.py from runtime",
+      fix: reachable ? "" : "npx @agentlayer.tech/wallet claude-code install --yes",
+    });
+  }
+  // Codex: plugin symlink target under the codex plugin install root.
+  const codexInstallRoot = resolveCodexPluginInstallRoot(env);
+  const codexTarget = path.join(codexInstallRoot, "agent-wallet", "server.py");
+  if (fs.existsSync(codexInstallRoot)) {
+    const ok = fs.existsSync(codexTarget);
+    checks.push({
+      name: "editor:codex",
+      ok,
+      error: ok ? "" : `codex plugin server.py missing at ${codexTarget}`,
+      fix: ok ? "" : "npx @agentlayer.tech/wallet codex install --yes",
+    });
+  }
+  return checks;
+}
+
+function runDoctor(args = []) {
+  const deep = hasFlag(args, "--deep");
+  const env = process.env;
+  const checks = [];
+  const fixInstall = "npx @agentlayer.tech/wallet install --yes";
 
+  for (const command of ["node", "npm"]) {
+    const ok = hasCommand(command);
+    checks.push({
+      name: `command:${command}`,
+      ok,
+      error: ok ? "" : `${command} not found on PATH`,
+      fix: ok ? "" : `install ${command}`,
+    });
+  }
+  const python = selectedPythonProbe();
+  const pythonOk = Boolean(python.path && python.version_ok && python.venv_ok);
+  checks.push({
+    name: "python_version",
+    ok: pythonOk,
+    error: !python.path ? "python3 not found"
+      : !python.version_ok ? `selected python ${python.version} < 3.10`
+      : !python.venv_ok ? `python ${python.version} lacks venv/ensurepip` : "",
+    fix: pythonOk ? "" : "install python>=3.10 with venv",
+  });
+
+  const currentPath = currentRuntimePath(env);
+  const currentRoot = resolvedCurrentRuntimeRoot(env);
+  const symlinkOk = Boolean(currentRoot && fs.existsSync(currentRoot));
+  checks.push({
+    name: "current_symlink",
+    ok: symlinkOk,
+    target: readLinkOrNull(currentPath),
+    error: symlinkOk ? "" : `current does not resolve to an existing release (${currentPath})`,
+    fix: symlinkOk ? "" : fixInstall,
+  });
+
+  const venvPython = currentRoot ? resolveVenvPython(currentRoot) : null;
+  checks.push({
+    name: "runtime_venv_python",
+    ok: Boolean(venvPython),
+    path: venvPython,
+    error: venvPython ? "" : "runtime .runtime-venv/bin/python missing",
+    fix: venvPython ? "" : fixInstall,
+  });
+
+  const serverPy = currentRoot
+    ? path.join(currentRoot, "codex", "plugins", "agent-wallet", "server.py")
+    : null;
+  const serverExists = Boolean(serverPy && fs.existsSync(serverPy));
+  let parseOk = false;
+  if (serverExists && venvPython) {
+    const compiled = spawnSync(venvPython, ["-m", "py_compile", serverPy], { encoding: "utf8" });
+    parseOk = compiled.status === 0;
+  }
+  checks.push({
+    name: "server_py_parses",
+    ok: parseOk,
+    error: !serverExists ? "runtime codex server.py missing"
+      : !venvPython ? "server.py parse skipped (runtime venv missing)"
+      : parseOk ? "" : "server.py present but failed to parse",
+    fix: parseOk ? "" : fixInstall,
+  });
+
+  if (deep) {
+    const verify = currentRoot
+      ? verifyRuntime(currentRoot, env)
+      : { ok: false, error: "no runtime to handshake", category: "local_env" };
+    checks.push({
+      name: "mcp_initialize_handshake",
+      ok: verify.ok,
+      error: verify.ok ? "" : verify.error,
+      fix: verify.ok ? "" : `${fixInstall} (or: npx @agentlayer.tech/wallet rollback)`,
+    });
+  }
+
+  for (const editorCheck of resolveEditorServerChecks(env)) {
+    checks.push(editorCheck);
+  }
+
+  const ok = checks.every((c) => c.ok);
   console.log(
     JSON.stringify(
       {
-        ok: missing.length === 0,
+        ok,
         package_name: packageJson.name,
         package_version: packageVersion,
-        package_root: packageRoot,
-        setup_path: setupPath,
         openclaw_home: resolveOpenclawHome(),
-        runtime_base: resolveRuntimeBase(),
-        current_runtime: currentRuntimePath(),
+        current_runtime: currentPath,
         active_version: activeVersion(),
         releases: listReleases(),
-        python,
-        commands: Object.fromEntries(commands.map((command) => [command, hasCommand(command)])),
-        missing,
+        deep,
+        checks,
       },
       null,
       2,
     ),
   );
-  return missing.length === 0 ? 0 : 1;
+  return ok ? 0 : 1;
 }
 
 function runStatus(args = []) {
@@ -786,6 +955,68 @@ function runInstall(args, { commandName = "install" } = {}) {
   }
   switchSymlink(currentPath, releaseRoot);
 
+  // Installs that pass --skip-python-setup may have no venv, so this handshake
+  // would fail and trigger a spurious rollback; such flows must set
+  // AGENT_WALLET_VERIFY_DISABLE=1 (verifyRuntime then skips).
+  const verification = verifyRuntime(releaseRoot, env);
+  if (!verification.ok && !verification.skipped) {
+    const rollbackTarget = currentTarget; // pre-switch target captured before the switch, if any
+    const rolledBack = Boolean(rollbackTarget);
+    if (rolledBack) {
+      switchSymlink(currentPath, rollbackTarget);
+    }
+    const previousVersion = rolledBack
+      ? path.basename(path.resolve(path.dirname(currentPath), rollbackTarget))
+      : null;
+
+    let human;
+    let fix;
+    if (!rolledBack) {
+      // First install / no good fallback — leave no active runtime rather than a
+      // broken one. Deliberately do NOT point `previous` at the broken release,
+      // so a later `rollback` cannot reactivate it; the release stays under
+      // releases/<version> for inspection via `install --version`.
+      removeRuntimePointer(currentPath);
+      human =
+        verification.category === "broken_release"
+          ? `Release ${packageVersion} is broken and there is no previous working version to fall back to. Nothing is active. This is a bad release — please report it; a patched version will follow.`
+          : `Release ${packageVersion} failed to verify and there is no previous version. Your local environment looks incomplete: ${verification.error}.`;
+      fix =
+        verification.category === "local_env"
+          ? "Ensure python>=3.10 with venv is installed, then: npx @agentlayer.tech/wallet install --yes"
+          : "npx @agentlayer.tech/wallet install --version <known-good-version> --yes";
+    } else if (verification.category === "broken_release") {
+      human = `Release ${packageVersion} is broken; kept you on the working version ${previousVersion}. This is on our side — you are safe. Re-run update when a patched release ships.`;
+      fix = "npx @agentlayer.tech/wallet update --yes";
+    } else if (verification.category === "local_env") {
+      human = `Release ${packageVersion} could not start on this machine; kept you on ${previousVersion}. This looks fixable locally: ${verification.error}.`;
+      fix = "Fix python>=3.10/venv, then: npx @agentlayer.tech/wallet install --yes";
+    } else {
+      human = `Release ${packageVersion} failed verification; kept you on ${previousVersion}.`;
+      fix = "npx @agentlayer.tech/wallet doctor --deep  (then install --yes once resolved)";
+    }
+
+    console.error(
+      JSON.stringify(
+        {
+          ok: false,
+          command: commandName,
+          version: packageVersion,
+          category: verification.category || "unknown",
+          error: `runtime verification failed: ${verification.error}`,
+          rolled_back: rolledBack,
+          kept_version: previousVersion,
+          current_runtime_target: readLinkOrNull(currentPath),
+          message: human,
+          fix,
+        },
+        null,
+        2,
+      ),
+    );
+    return 1;
+  }
+
   if (env.AGENT_WALLET_BOOT_KEY) {
     envFileSet(path.join(releaseRoot, "agent-wallet", ".env"), {
       AGENT_WALLET_BOOT_KEY: env.AGENT_WALLET_BOOT_KEY,
@@ -986,6 +1217,9 @@ function resolveHermesPluginSource() {
 }
 
 function resolveCodexPluginSource() {
+  // test/CI override: inject a staged bundle dir
+  const override = String(process.env.AGENT_WALLET_CODEX_PLUGIN_SOURCE || "").trim();
+  if (override) return path.resolve(expandHome(override));
   const currentRoot = resolvedCurrentRuntimeRoot();
   const candidates = [];
   if (currentRoot) {
@@ -1001,6 +1235,9 @@ function resolveCodexPluginSource() {
 }
 
 function resolveClaudeCodePluginSource() {
+  // test/CI override: inject a staged bundle dir
+  const override = String(process.env.AGENT_WALLET_CLAUDE_CODE_PLUGIN_SOURCE || "").trim();
+  if (override) return path.resolve(expandHome(override));
   const currentRoot = resolvedCurrentRuntimeRoot();
   const candidates = [];
   if (currentRoot) {
@@ -1190,6 +1427,7 @@ function runHermesInstall(args) {
 function runCodexInstall(args) {
   const codexHome = resolveCodexHome();
   const pluginSource = resolveCodexPluginSource();
+  const pinnedEnv = pinEditorMcpEnv(pluginSource);
   const pluginRoot = resolveCodexPluginInstallRoot();
   const pluginTarget = path.join(pluginRoot, "agent-wallet");
   const marketplacePath = resolveCodexMarketplacePath();
@@ -1260,6 +1498,7 @@ function runCodexInstall(args) {
         marketplace_name: marketplace.marketplace_name,
         codex_add: add,
         restart_required: true,
+        pinned_env: pinnedEnv,
       },
       null,
       2,
@@ -1268,71 +1507,189 @@ function runCodexInstall(args) {
   return add.skipped || add.ok ? 0 : 1;
 }
 
-function runClaudeCodeInstall(args) {
-  const pluginSource = resolveClaudeCodePluginSource();
-  const force = hasFlag(args, "--force");
-  const skipEnable = hasFlag(args, "--skip-enable");
-  const claudeBin = commandPath("claude");
+const CLAUDE_CODE_MARKETPLACE_NAME = "agentlayer-local";
 
-  // Symlink the plugin into ~/.claude/plugins/agent-wallet so Claude Code can load it.
-  const pluginInstallDir = path.join(os.homedir(), ".claude", "plugins");
-  const pluginTarget = path.join(pluginInstallDir, "agent-wallet");
+function resolveClaudeCodeMarketplaceDir(env = process.env) {
+  return path.resolve(
+    expandHome(env.AGENT_WALLET_CLAUDE_CODE_MARKETPLACE_DIR || "~/.claude/agentlayer-local"),
+  );
+}
 
-  fs.mkdirSync(pluginInstallDir, { recursive: true });
+// Pin OPENCLAW_HOME into one .mcp.json so run_mcp.sh uses the install-time home
+// instead of re-deriving the ~/.openclaw default. We deliberately do NOT pin
+// AGENT_WALLET_PYTHON: the launcher resolves the venv from OPENCLAW_HOME->current
+// dynamically, so a pinned python would go stale (and wrongly win) after upgrade.
+function pinHomeIntoMcpFile(mcpPath, env = process.env) {
+  if (!fs.existsSync(mcpPath)) return { pinned: false, reason: "no .mcp.json", path: mcpPath };
+  let doc;
   try {
-    const existing = fs.lstatSync(pluginTarget);
+    doc = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
+  } catch (error) {
+    return { pinned: false, reason: `unreadable .mcp.json: ${error.message}`, path: mcpPath };
+  }
+  const entry = (doc.mcpServers || {})["agent-wallet"];
+  if (!entry) return { pinned: false, reason: "no agent-wallet server entry", path: mcpPath };
+  const home = resolveOpenclawHome(env);
+  entry.env = { ...(entry.env || {}), OPENCLAW_HOME: home };
+  writeJsonFile(mcpPath, doc);
+  return { pinned: true, openclaw_home: home, path: mcpPath };
+}
+
+function pinEditorMcpEnv(pluginSource, env = process.env) {
+  return pinHomeIntoMcpFile(path.join(pluginSource, ".mcp.json"), env);
+}
+
+// Claude Code copies the plugin into a version-keyed cache and reads THAT copy,
+// so the bundle pin alone is ineffective once a cache exists. Pin every cached
+// copy too. Cache root is overridable for tests.
+function pinClaudeCacheCopies(env = process.env) {
+  const cacheRoot = path.resolve(
+    expandHome(env.AGENT_WALLET_CLAUDE_CODE_CACHE_ROOT || "~/.claude/plugins/cache"),
+  );
+  const pluginCacheDir = path.join(cacheRoot, CLAUDE_CODE_MARKETPLACE_NAME, "agent-wallet");
+  const results = [];
+  if (!fs.existsSync(pluginCacheDir)) return results;
+  let versions;
+  try {
+    versions = fs.readdirSync(pluginCacheDir);
+  } catch {
+    return results;
+  }
+  for (const version of versions) {
+    const mcpPath = path.join(pluginCacheDir, version, ".mcp.json");
+    if (fs.existsSync(mcpPath)) results.push(pinHomeIntoMcpFile(mcpPath, env));
+  }
+  return results;
+}
+
+function ensureClaudeCodeMarketplace(marketplaceDir, pluginSource, force) {
+  const pluginsDir = path.join(marketplaceDir, "plugins");
+  const pluginLink = path.join(pluginsDir, "agent-wallet");
+  const manifestDir = path.join(marketplaceDir, ".claude-plugin");
+  const manifestPath = path.join(manifestDir, "marketplace.json");
+
+  fs.mkdirSync(pluginsDir, { recursive: true });
+  fs.mkdirSync(manifestDir, { recursive: true });
+
+  // Symlink plugin source into marketplace plugins dir.
+  try {
+    const existing = fs.lstatSync(pluginLink);
     if (!existing.isSymbolicLink()) {
       if (!force) {
-        throw new Error(`${pluginTarget} exists and is not a symlink. Pass --force to replace it.`);
+        throw new Error(
+          `${pluginLink} exists and is not a symlink. Pass --force to replace it.`,
+        );
       }
-      fs.rmSync(pluginTarget, { recursive: true, force: true });
+      fs.rmSync(pluginLink, { recursive: true, force: true });
     } else {
-      fs.unlinkSync(pluginTarget);
+      fs.unlinkSync(pluginLink);
     }
   } catch (error) {
     if (error?.code !== "ENOENT") throw error;
   }
-  fs.symlinkSync(pluginSource, pluginTarget, "dir");
+  fs.symlinkSync(pluginSource, pluginLink, "dir");
+
+  // Write marketplace manifest (Claude Code requires owner + plugins[].source as relative path).
+  const manifest = {
+    name: CLAUDE_CODE_MARKETPLACE_NAME,
+    description: "Local AgentLayer plugins",
+    owner: { name: "AgentLayer" },
+    plugins: [
+      {
+        name: "agent-wallet",
+        displayName: "Agent Wallet",
+        description:
+          "Bridge to the existing local AgentLayer wallet runtime (Solana, Bitcoin, EVM).",
+        category: "development",
+        source: "./plugins/agent-wallet",
+      },
+    ],
+  };
+  writeJsonFile(manifestPath, manifest);
+  return { pluginLink, manifestPath };
+}
 
-  // Try `claude plugin install <path>` when the CLI is present.
+function runClaudeCodeInstall(args) {
+  const pluginSource = resolveClaudeCodePluginSource();
+  const pinnedEnv = pinEditorMcpEnv(pluginSource);
+  const pinnedCache = pinClaudeCacheCopies();
+  const force = hasFlag(args, "--force");
+  const skipEnable = hasFlag(args, "--skip-enable");
+  const claudeBin = commandPath("claude");
+  const marketplaceDir = resolveClaudeCodeMarketplaceDir();
+
+  const { pluginLink } = ensureClaudeCodeMarketplace(marketplaceDir, pluginSource, force);
+
+  const pluginDirFlag = `claude --plugin-dir ${pluginLink}`;
+
+  // Without the Claude CLI we can only set up the files; the user must register manually.
+  let marketplaceAdd = { attempted: false, ok: false, skipped: skipEnable, error: "" };
   let enable = { attempted: false, ok: false, skipped: skipEnable, error: "" };
+
   if (!skipEnable) {
     if (!claudeBin) {
-      enable = {
-        attempted: false,
-        ok: false,
-        skipped: false,
-        error:
-          "Claude Code CLI was not found on PATH. Load the plugin manually with: claude --plugin-dir " +
-          pluginTarget,
-      };
+      const msg =
+        "Claude Code CLI was not found on PATH. Load the plugin manually with: " + pluginDirFlag;
+      marketplaceAdd = { attempted: false, ok: false, skipped: false, error: msg };
+      enable = { attempted: false, ok: false, skipped: false, error: msg };
     } else {
-      const result = spawnSync(claudeBin, ["plugin", "install", pluginTarget, "--scope", "user"], {
-        encoding: "utf8",
-        stdio: "pipe",
-      });
-      enable = {
+      // Register the local marketplace (idempotent — safe to re-run).
+      const addResult = spawnSync(
+        claudeBin,
+        ["plugin", "marketplace", "add", marketplaceDir, "--scope", "user"],
+        { encoding: "utf8", stdio: "pipe" },
+      );
+      marketplaceAdd = {
         attempted: true,
-        ok: result.status === 0,
+        ok: addResult.status === 0,
         skipped: false,
-        error: result.status === 0 ? "" : (result.stderr || result.stdout || "").trim(),
+        error: addResult.status === 0 ? "" : (addResult.stderr || addResult.stdout || "").trim(),
       };
+
+      if (marketplaceAdd.ok) {
+        // Install plugin from the now-registered local marketplace.
+        const installResult = spawnSync(
+          claudeBin,
+          ["plugin", "install", `agent-wallet@${CLAUDE_CODE_MARKETPLACE_NAME}`, "--scope", "user"],
+          { encoding: "utf8", stdio: "pipe" },
+        );
+        enable = {
+          attempted: true,
+          ok: installResult.status === 0,
+          skipped: false,
+          error:
+            installResult.status === 0
+              ? ""
+              : (installResult.stderr || installResult.stdout || "").trim(),
+        };
+      } else {
+        enable = {
+          attempted: false,
+          ok: false,
+          skipped: false,
+          error: "Skipped plugin install because marketplace registration failed.",
+        };
+      }
     }
   }
 
-  const pluginDirFlag = `claude --plugin-dir ${pluginTarget}`;
+  const ok = enable.skipped || enable.ok;
+  const pluginDirFlagFull = `claude --plugin-dir ${pluginSource}`;
   console.log(
     JSON.stringify(
       {
-        ok: enable.skipped || enable.ok,
+        ok,
         plugin_source: pluginSource,
-        plugin_target: pluginTarget,
+        marketplace_dir: marketplaceDir,
+        marketplace_add: marketplaceAdd,
         claude_code_install: enable,
-        manual_load: pluginDirFlag,
+        manual_load: pluginDirFlagFull,
         restart_required: true,
-        note: enable.ok
+        pinned_env: pinnedEnv,
+        pinned_cache: pinnedCache,
+        note: ok
           ? "Plugin registered. Restart Claude Code to activate."
-          : `If automatic registration failed, load the plugin with: ${pluginDirFlag}`,
+          : `If automatic registration failed, load the plugin with: ${pluginDirFlagFull}`,
       },
       null,
       2,
@@ -1355,7 +1712,16 @@ if (command === "--version" || command === "-v" || command === "version") {
 }
 
 if (command === "doctor") {
-  process.exit(runDoctor());
+  process.exit(runDoctor(args.slice(1)));
+}
+
+if (command === "--self-verify") {
+  const releaseRoot = args[1] ? path.resolve(expandHome(args[1])) : resolvedCurrentRuntimeRoot();
+  const result = releaseRoot
+    ? verifyRuntime(releaseRoot)
+    : { ok: false, error: "no runtime to verify", category: "local_env" };
+  console.log(JSON.stringify(result));
+  process.exit(result.ok ? 0 : 1);
 }
 
 if (command === "status") {

package/claude-code/plugins/agent-wallet/scripts/run_mcp.sh

@@ -6,16 +6,21 @@ PLUGIN_ROOT=$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)
 OPENCLAW_HOME=${OPENCLAW_HOME:-"$HOME/.openclaw"}
 PACKAGE_ROOT=${AGENT_WALLET_PACKAGE_ROOT:-${OPENCLAW_AGENT_WALLET_PACKAGE_ROOT:-"$OPENCLAW_HOME/agent-wallet-runtime/current/agent-wallet"}}
 
-# Resolve server.py: check sibling codex plugin (same npm package), then local copy
-CODEX_SERVER="$PLUGIN_ROOT/../../codex/plugins/agent-wallet/server.py"
+# Resolve server.py. When Claude Code copies this plugin into its cache, the
+# relative sibling paths below no longer resolve, so fall back to the codex
+# plugin copy inside the installed runtime package, which is always present.
 LOCAL_SERVER="$PLUGIN_ROOT/server.py"
+CODEX_SERVER="$PLUGIN_ROOT/../../codex/plugins/agent-wallet/server.py"
+RUNTIME_CODEX_DIR="$OPENCLAW_HOME/agent-wallet-runtime/current/codex/plugins/agent-wallet"
 
 if [ -f "$LOCAL_SERVER" ]; then
   SERVER_PY="$LOCAL_SERVER"
 elif [ -f "$CODEX_SERVER" ]; then
   SERVER_PY=$(CDPATH= cd -- "$PLUGIN_ROOT/../../codex/plugins/agent-wallet" && pwd)/server.py
+elif [ -f "$RUNTIME_CODEX_DIR/server.py" ]; then
+  SERVER_PY=$(CDPATH= cd -- "$RUNTIME_CODEX_DIR" && pwd)/server.py
 else
-  printf '{"error":"agent-wallet server.py not found. Run: npx @agentlayer.tech/wallet install --yes"}\n' >&2
+  printf '{"error":"agent-wallet server.py not found in plugin, codex sibling, or runtime package.","fix":"npx @agentlayer.tech/wallet install --yes"}\n' >&2
   exit 1
 fi
 
@@ -31,4 +36,17 @@ else
   PYTHON_BIN=python3
 fi
 
+# Fail loudly (not -32000) if the resolved server cannot even be parsed.
+if ! "$PYTHON_BIN" -m py_compile "$SERVER_PY" 2>/dev/null; then
+  "$PYTHON_BIN" - "$SERVER_PY" >&2 <<'PY'
+import json, sys
+print(json.dumps({
+    "error": "agent-wallet server.py failed to parse — runtime likely broken.",
+    "server_py": sys.argv[1],
+    "fix": "npx @agentlayer.tech/wallet install --yes (or: npx @agentlayer.tech/wallet rollback)",
+}))
+PY
+  exit 1
+fi
+
 exec "$PYTHON_BIN" "$SERVER_PY"

package/codex/plugins/agent-wallet/scripts/run_mcp.sh

@@ -18,4 +18,22 @@ else
   PYTHON_BIN=python3
 fi
 
+if [ ! -f "$PLUGIN_ROOT/server.py" ]; then
+  printf '{"error":"agent-wallet server.py not found in codex plugin.","fix":"npx @agentlayer.tech/wallet install --yes"}\n' >&2
+  exit 1
+fi
+
+# Fail loudly (not -32000) if the resolved server cannot even be parsed.
+if ! "$PYTHON_BIN" -m py_compile "$PLUGIN_ROOT/server.py" 2>/dev/null; then
+  "$PYTHON_BIN" - "$PLUGIN_ROOT/server.py" >&2 <<'PY'
+import json, sys
+print(json.dumps({
+    "error": "agent-wallet server.py failed to parse — runtime likely broken.",
+    "server_py": sys.argv[1],
+    "fix": "npx @agentlayer.tech/wallet install --yes (or: npx @agentlayer.tech/wallet rollback)",
+}))
+PY
+  exit 1
+fi
+
 exec "$PYTHON_BIN" "$PLUGIN_ROOT/server.py"