@agentlayer.tech/wallet 0.1.32 → 0.1.33

package/.openclaw/extensions/agent-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayertech/agent-wallet-plugin",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "OpenClaw plugin bridge for the AgentLayer wallet runtime.",
   "type": "module",
   "license": "SEE LICENSE IN ../../../LICENSE",

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+## v0.1.33 - 2026-06-01
+
+- Hardened runtime resolution end-to-end so a broken or stale runtime can no
+  longer surface as an opaque MCP `-32000`.
+  - `run_mcp.sh` (Codex + Claude Code) now self-checks the resolved `server.py`
+    with `py_compile` and emits a structured, actionable JSON error (with a
+    `fix` command) when the server is missing or fails to parse, instead of
+    silently handing a broken file to Python. JSON errors are emitted safely so
+    arbitrary paths cannot produce invalid JSON.
+  - `doctor` / `doctor --deep` now validate the live `current` runtime — symlink
+    integrity, venv python, `server.py` parse, a real MCP `initialize` handshake
+    (under `--deep`), and per-editor resolution — and attach a `fix` command to
+    every failing check (output is a structured `checks[]` array).
+  - `install` / `update` now verify the newly-activated release via an MCP
+    handshake and auto-rollback `current → previous` on failure, with guidance
+    classified as `broken_release` (our side — you stay safe on the previous
+    version) vs `local_env` (fixable locally). A first install with no previous
+    version leaves no broken runtime active and does not park the broken release
+    under `previous`.
+  - `codex install` / `claude-code install` pin the resolved `OPENCLAW_HOME`
+    into the editor `.mcp.json` env (bundle and, for Claude Code, existing
+    version-keyed cache copies), eliminating launcher/installer home divergence.
+    The venv python is intentionally not pinned so it stays correct across
+    runtime upgrades.
+
 ## v0.1.32 - 2026-06-01
 
 - Fixed a `SyntaxError` in `codex/plugins/agent-wallet/server.py` introduced by

package/agent-wallet/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openclaw-agent-wallet"
-version = "0.1.32"
+version = "0.1.33"
 description = "Plugin-friendly wallet backend for OpenClaw agents"
 requires-python = ">=3.10"
 dependencies = [

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";
+}
+
+function verifyRuntime(releaseRoot, env = process.env) {
+  if (String(env.AGENT_WALLET_VERIFY_DISABLE || "") === "1") {
+    return { ok: true, skipped: true };
+  }
+  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" };
+  }
+  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),
+  };
+}
 
-  for (const command of commands) {
-    if (!hasCommand(command)) missing.push(`command:${command}`);
+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",
+    });
   }
-  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"}`);
+  // 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",
+    });
   }
-  for (const [label, target] of requiredPaths) {
-    if (!fs.existsSync(target)) missing.push(`${label}:${target}`);
+  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,
@@ -1276,6 +1515,53 @@ function resolveClaudeCodeMarketplaceDir(env = process.env) {
   );
 }
 
+// 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 {
+    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");
@@ -1325,6 +1611,8 @@ function ensureClaudeCodeMarketplace(marketplaceDir, pluginSource, force) {
 
 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");
@@ -1397,6 +1685,8 @@ function runClaudeCodeInstall(args) {
         claude_code_install: enable,
         manual_load: pluginDirFlagFull,
         restart_required: true,
+        pinned_env: pinnedEnv,
+        pinned_cache: pinnedCache,
         note: ok
           ? "Plugin registered. Restart Claude Code to activate."
           : `If automatic registration failed, load the plugin with: ${pluginDirFlagFull}`,
@@ -1422,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

@@ -20,7 +20,7 @@ elif [ -f "$CODEX_SERVER" ]; then
 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
 
@@ -36,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"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayer.tech/wallet",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "NPM installer for the OpenClaw Agent Wallet local runtime.",
   "type": "module",
   "repository": {