@agentlayer.tech/wallet 0.1.73 → 0.1.75

package/bin/openclaw-agent-wallet.mjs

@@ -380,6 +380,123 @@ function releaseRootFor(version, env = process.env) {
   return path.join(resolveRuntimeBase(env), "releases", version);
 }
 
+function stagingRootFor(version, env = process.env) {
+  return path.join(
+    resolveRuntimeBase(env),
+    "releases",
+    `.staging-${version}-${process.pid}-${Date.now()}`,
+  );
+}
+
+function updateJournalPath(env = process.env) {
+  return path.join(resolveRuntimeBase(env), "update-journal.json");
+}
+
+function integrationRegistryPath(env = process.env) {
+  return path.join(resolveRuntimeBase(env), "integrations.json");
+}
+
+function readIntegrationRegistry(env = process.env) {
+  const payload = readJsonFile(integrationRegistryPath(env));
+  if (!payload || payload.schema_version !== 1 || typeof payload.integrations !== "object") {
+    return { schema_version: 1, integrations: {} };
+  }
+  return payload;
+}
+
+function recordManagedIntegration(name, details = {}, env = process.env) {
+  const registry = readIntegrationRegistry(env);
+  registry.integrations[name] = {
+    ...details,
+    managed: true,
+    installed_version: packageVersion,
+    updated_at: new Date().toISOString(),
+  };
+  registry.updated_at = new Date().toISOString();
+  writeJsonFileAtomic(integrationRegistryPath(env), registry);
+  return registry.integrations[name];
+}
+
+function managedIntegration(name, env = process.env) {
+  const entry = readIntegrationRegistry(env).integrations[name];
+  return entry && entry.managed === true ? entry : null;
+}
+
+function integrationSyncStatus(env = process.env) {
+  const active = activeVersion(env);
+  const registry = readIntegrationRegistry(env);
+  const integrations = Object.entries(registry.integrations)
+    .filter(([, entry]) => entry?.managed === true)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, entry]) => {
+      const versionInSync = active === null || entry.installed_version === active;
+      const registrationOk = entry.registration_ok !== false;
+      return {
+        name,
+        installed_version: entry.installed_version || null,
+        active_version: active,
+        in_sync: versionInSync && registrationOk,
+        registration_ok: registrationOk,
+        restart_required: Boolean(entry.restart_required),
+      };
+    });
+  return {
+    in_sync: integrations.every((entry) => entry.in_sync),
+    integrations,
+  };
+}
+
+function writeUpdateJournal(state, details = {}, env = process.env) {
+  writeJsonFile(updateJournalPath(env), {
+    schema_version: 1,
+    state,
+    version: packageVersion,
+    updated_at: new Date().toISOString(),
+    ...details,
+  });
+}
+
+function writeReleaseState(runtimeRoot, state, details = {}) {
+  writeJsonFile(path.join(runtimeRoot, ".agent-wallet-release.json"), {
+    schema_version: 1,
+    version: packageVersion,
+    state,
+    updated_at: new Date().toISOString(),
+    ...details,
+  });
+}
+
+function failStagingRuntime(stagingRoot, error) {
+  if (!stagingRoot || !fs.existsSync(stagingRoot)) return null;
+  writeReleaseState(stagingRoot, "failed", { error: String(error || "install failed") });
+  const failedRoot = path.join(
+    path.dirname(stagingRoot),
+    `.failed-${packageVersion}-${Date.now()}`,
+  );
+  fs.renameSync(stagingRoot, failedRoot);
+  return failedRoot;
+}
+
+function commitStagedRuntime(stagingRoot, releaseRoot) {
+  if (!stagingRoot) return null;
+  let replacedRoot = null;
+  if (fs.existsSync(releaseRoot)) {
+    replacedRoot = uniquePathWithSuffix(
+      path.join(path.dirname(releaseRoot), `${path.basename(releaseRoot)}-replaced`),
+    );
+    fs.renameSync(releaseRoot, replacedRoot);
+  }
+  try {
+    fs.renameSync(stagingRoot, releaseRoot);
+  } catch (error) {
+    if (replacedRoot && !fs.existsSync(releaseRoot)) {
+      fs.renameSync(replacedRoot, releaseRoot);
+    }
+    throw error;
+  }
+  return replacedRoot;
+}
+
 function currentRuntimePath(env = process.env) {
   return path.join(resolveRuntimeBase(env), "current");
 }
@@ -507,7 +624,21 @@ function listReleases(env = process.env) {
   try {
     return fs
       .readdirSync(releasesDir, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
+      .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+function listFailedReleases(env = process.env) {
+  const releasesDir = path.join(resolveRuntimeBase(env), "releases");
+  try {
+    return fs
+      .readdirSync(releasesDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && entry.name.startsWith(".failed-"))
       .map((entry) => entry.name)
       .sort();
   } catch (error) {
@@ -867,6 +998,22 @@ function writeJsonFile(pathname, value) {
   fs.writeFileSync(pathname, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+function writeJsonFileAtomic(pathname, value, mode = 0o600) {
+  fs.mkdirSync(path.dirname(pathname), { recursive: true });
+  const tempPath = `${pathname}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, { mode });
+    fs.renameSync(tempPath, pathname);
+    fs.chmodSync(pathname, mode);
+  } finally {
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {
+      // ignored
+    }
+  }
+}
+
 function currentBootKey(env = process.env) {
   const currentRoot = resolvedCurrentRuntimeRoot(env);
   if (!currentRoot) return "";
@@ -944,6 +1091,44 @@ function readBootKeyFromKeystore(env = process.env) {
   }
 }
 
+// New runtimes own boot-key precedence and verify candidates against
+// sealed_keys.json. An import failure means the active runtime predates this
+// bridge, so callers may use the legacy JS fallback below.
+function readBootKeyFromRuntimeResolver(env = process.env) {
+  const runtimeRoot = resolvedCurrentRuntimeRoot(env);
+  if (!runtimeRoot) return { supported: false, key: "" };
+  const py = resolveVenvPython(runtimeRoot);
+  if (!py) return { supported: false, key: "" };
+  try {
+    const res = spawnSync(
+      py,
+      ["-c", "from agent_wallet.config import resolve_boot_key_for_installer as r; print(r())"],
+      {
+        cwd: path.join(runtimeRoot, "agent-wallet"),
+        encoding: "utf8",
+        timeout: positiveIntEnv("AGENT_WALLET_KEYSTORE_BRIDGE_TIMEOUT_MS", KEYSTORE_BRIDGE_TIMEOUT_MS, env),
+        env: { ...env, OPENCLAW_HOME: resolveOpenclawHome(env) },
+      },
+    );
+    if ((res.status ?? 1) !== 0) return { supported: false, key: "" };
+    return { supported: true, key: String(res.stdout || "").trim() };
+  } catch {
+    return { supported: false, key: "" };
+  }
+}
+
+function resolveLegacyInstallerBootKey(env = process.env) {
+  for (const [source, key] of [
+    ["legacy_keystore", readBootKeyFromKeystore(env)],
+    ["current_runtime_env", currentBootKey(env)],
+    ["configured_file", resolveBootKeyFromFile(env)],
+    ["default_file", readTextIfExists(defaultBootKeyFile(env)).trim()],
+  ]) {
+    if (key) return { key, source };
+  }
+  return { key: "", source: "none" };
+}
+
 // Provision the boot key into the OS keystore via the freshly installed runtime's
 // Python. Returns true only when the import stored AND verified the key, so the
 // caller may safely drop the plaintext .env copy. Best-effort: false on any failure
@@ -1186,6 +1371,16 @@ function runDoctor(args = []) {
     fix: rsync.in_sync === false ? "npm run release:local" : "",
   });
 
+  const integrationSync = integrationSyncStatus(env);
+  checks.push({
+    name: "framework_integrations_in_sync",
+    ok: true,
+    in_sync: integrationSync.in_sync,
+    integrations: integrationSync.integrations,
+    error: "",
+    fix: integrationSync.in_sync ? "" : "wallet update --yes",
+  });
+
   const ok = checks.every((c) => c.ok);
   console.log(
     JSON.stringify(
@@ -1218,8 +1413,10 @@ function runStatus(args = []) {
     previous_runtime: readLinkOrNull(previousRuntimePath()),
     active_version: activeVersion(),
     available_releases: listReleases(),
+    failed_releases: listFailedReleases(),
     update_available: computeUpdateAvailability(),
     runtime_in_sync: computeRuntimeInSync(),
+    framework_integrations: integrationSyncStatus(),
   };
   if (hasFlag(args, "--verbose")) {
     payload.verbose = true;
@@ -1236,15 +1433,17 @@ function buildInstallerEnv(args) {
   const sealedKeysPath = path.join(resolveOpenclawHome(env), "sealed_keys.json");
   const sealedKeysExist = fs.existsSync(sealedKeysPath);
   const dryRun = hasFlag(args, "--dry-run");
+  let bootKeySource = env.AGENT_WALLET_BOOT_KEY ? "environment" : "none";
   if (!env.AGENT_WALLET_BOOT_KEY) {
-    // Keep installer/update boot-key resolution aligned with the runtime:
-    // explicit env first, then keystore, then plaintext fallback paths. A stale
-    // boot-key file must not override a good keystore key and break updates.
-    const existingBootKey =
-      readBootKeyFromKeystore(env) ||
-      resolveBootKeyFromFile(env) ||
-      readTextIfExists(defaultBootKeyFile(env)).trim() ||
-      currentBootKey(env);
+    const runtimeResolution = readBootKeyFromRuntimeResolver(env);
+    const fallback = runtimeResolution.supported
+      ? {
+          key: runtimeResolution.key,
+          source: runtimeResolution.key ? "runtime_verified" : "runtime_rejected",
+        }
+      : resolveLegacyInstallerBootKey(env);
+    const existingBootKey = fallback.key;
+    bootKeySource = fallback.source;
     if (existingBootKey) {
       env.AGENT_WALLET_BOOT_KEY = existingBootKey;
     }
@@ -1264,6 +1463,7 @@ function buildInstallerEnv(args) {
   if (!sealedKeysExist && shouldGenerateSecrets && !env.AGENT_WALLET_BOOT_KEY) {
     generated.AGENT_WALLET_BOOT_KEY = token();
     env.AGENT_WALLET_BOOT_KEY = generated.AGENT_WALLET_BOOT_KEY;
+    bootKeySource = "generated";
   }
   if (!sealedKeysExist && shouldGenerateSecrets && !env.AGENT_WALLET_MASTER_KEY) {
     generated.AGENT_WALLET_MASTER_KEY = token();
@@ -1273,7 +1473,7 @@ function buildInstallerEnv(args) {
     generated.AGENT_WALLET_APPROVAL_SECRET = token();
     env.AGENT_WALLET_APPROVAL_SECRET = generated.AGENT_WALLET_APPROVAL_SECRET;
   }
-  return { env, generated };
+  return { env, generated, bootKeySource };
 }
 
 function runInstall(args, { commandName = "install" } = {}) {
@@ -1290,9 +1490,11 @@ function runInstall(args, { commandName = "install" } = {}) {
   const previousPath = previousRuntimePath();
   const installerArgs = withoutCliOnlyArgs(args);
   const dryRun = hasFlag(args, "--dry-run");
+  const stagingRoot = !explicitRuntimeRoot && !dryRun ? stagingRootFor(packageVersion) : null;
+  const installRoot = stagingRoot || releaseRoot;
 
   if (!hasFlag(installerArgs, "--runtime-root")) {
-    installerArgs.push("--runtime-root", releaseRoot);
+    installerArgs.push("--runtime-root", installRoot);
   }
   if (!hasFlag(installerArgs, "--install-from-runtime")) {
     installerArgs.push("--install-from-runtime");
@@ -1305,7 +1507,11 @@ function runInstall(args, { commandName = "install" } = {}) {
     console.error(error.message);
     return 1;
   }
-  const { env, generated } = installerEnv;
+  const { env, generated, bootKeySource } = installerEnv;
+  if (stagingRoot) {
+    env.OPENCLAW_INSTALL_FINAL_ROOT = releaseRoot;
+    writeUpdateJournal("preparing", { staging_root: stagingRoot, release_root: releaseRoot }, env);
+  }
   const result = spawnSync("sh", [setupPath, ...installerArgs], {
     cwd: packageRoot,
     stdio: "inherit",
@@ -1313,10 +1519,22 @@ function runInstall(args, { commandName = "install" } = {}) {
   });
 
   if (result.error) {
+    const failedRoot = failStagingRuntime(stagingRoot, result.error.message);
+    if (!dryRun) {
+      writeUpdateJournal("failed", { failed_runtime: failedRoot, error: result.error.message }, env);
+    }
     console.error(result.error.message);
     return 1;
   }
   if ((result.status ?? 1) !== 0) {
+    const failedRoot = failStagingRuntime(stagingRoot, `installer exited with ${result.status ?? 1}`);
+    if (!dryRun) {
+      writeUpdateJournal(
+        "failed",
+        { failed_runtime: failedRoot, error: `installer exited with ${result.status ?? 1}` },
+        env,
+      );
+    }
     return result.status ?? 1;
   }
 
@@ -1324,34 +1542,21 @@ function runInstall(args, { commandName = "install" } = {}) {
     return 0;
   }
 
-  const currentTarget = existingRuntimePointerTarget(currentPath);
-  if (currentTarget) {
-    switchSymlink(previousPath, currentTarget);
-  }
-  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);
+  const currentTarget = existingRuntimePointerTarget(currentPath);
+  const verification = verifyRuntime(installRoot, 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 failedRoot = failStagingRuntime(stagingRoot, verification.error);
+    const rolledBack = Boolean(currentTarget);
     const previousVersion = rolledBack
-      ? path.basename(path.resolve(path.dirname(currentPath), rollbackTarget))
+      ? path.basename(currentTarget)
       : 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.`
@@ -1380,7 +1585,9 @@ function runInstall(args, { commandName = "install" } = {}) {
           category: verification.category || "unknown",
           error: `runtime verification failed: ${verification.error}`,
           rolled_back: rolledBack,
+          switched_current: false,
           kept_version: previousVersion,
+          failed_runtime: failedRoot,
           current_runtime_target: readLinkOrNull(currentPath),
           message: human,
           fix,
@@ -1389,15 +1596,20 @@ function runInstall(args, { commandName = "install" } = {}) {
         2,
       ),
     );
+    writeUpdateJournal(
+      "failed",
+      { failed_runtime: failedRoot, error: verification.error, kept_version: previousVersion },
+      env,
+    );
     return 1;
   }
 
   if (env.AGENT_WALLET_BOOT_KEY) {
-    const envPath = path.join(releaseRoot, "agent-wallet", ".env");
+    const envPath = path.join(installRoot, "agent-wallet", ".env");
     // Prefer the OS keystore: provision the boot key there and keep the plaintext
     // out of the release .env entirely. Only fall back to the legacy .env write when
     // no keystore round-trip is possible, so the runtime can still resolve the key.
-    if (provisionBootKeyToKeystore(releaseRoot, env, env.AGENT_WALLET_BOOT_KEY)) {
+    if (provisionBootKeyToKeystore(installRoot, env, env.AGENT_WALLET_BOOT_KEY)) {
       envFileUnset(envPath, ["AGENT_WALLET_BOOT_KEY"]);
     } else {
       envFileSet(envPath, {
@@ -1406,7 +1618,45 @@ function runInstall(args, { commandName = "install" } = {}) {
     }
   }
 
-  const integrationRefresh = refreshInstalledEditorIntegrations(env);
+  writeReleaseState(installRoot, "verified", {
+    verification_skipped: Boolean(verification.skipped),
+  });
+  writeUpdateJournal("verified", { staging_root: stagingRoot, release_root: releaseRoot }, env);
+
+  let replacedRoot = null;
+  try {
+    replacedRoot = commitStagedRuntime(stagingRoot, releaseRoot);
+  } catch (error) {
+    const failedRoot = failStagingRuntime(stagingRoot, error.message);
+    writeUpdateJournal("failed", { failed_runtime: failedRoot, error: error.message }, env);
+    console.error(`Could not commit staged runtime: ${error.message}`);
+    return 1;
+  }
+
+  const previousTarget =
+    currentTarget && path.resolve(currentTarget) === path.resolve(releaseRoot) && replacedRoot
+      ? replacedRoot
+      : currentTarget;
+  if (previousTarget) {
+    switchSymlink(previousPath, previousTarget);
+  }
+  switchSymlink(currentPath, releaseRoot);
+  writeUpdateJournal("committed", { release_root: releaseRoot, previous_runtime: previousTarget }, env);
+
+  recordManagedIntegration(
+    "openclaw",
+    {
+      config_path: path.resolve(
+        expandHome(parseFlagValue(args, "--config-path") || path.join(resolveOpenclawHome(env), "openclaw.json")),
+      ),
+      extension_path: path.join(currentPath, ".openclaw", "extensions", "agent-wallet"),
+      package_root: path.join(currentPath, "agent-wallet"),
+    },
+    env,
+  );
+
+  const integrationRefresh = repairInstalledEditorIntegrations(env);
+  const globalCliRefresh = refreshGlobalCliIfNeeded(env);
 
   const pythonInfo = activePythonRuntimeInfo(env);
   const nodeInfo = activeNodeRuntimeInfo(env)
@@ -1426,7 +1676,11 @@ function runInstall(args, { commandName = "install" } = {}) {
         current_runtime: currentPath,
         previous_runtime: readLinkOrNull(previousPath),
         generated_runtime_secrets: Object.keys(generated),
+        boot_key_source: bootKeySource,
+        staged: Boolean(stagingRoot),
+        release_state: "verified",
         integration_refresh: integrationRefresh,
+        global_cli_refresh: globalCliRefresh,
       },
       null,
       2,
@@ -1842,6 +2096,14 @@ function runHermesInstall(args) {
     }
   }
 
+  recordManagedIntegration("hermes", {
+    hermes_home: hermesHome,
+    plugin_target: pluginTarget,
+    env_path: hermesEnvPath,
+    restart_required: true,
+    ...(enable.skipped ? {} : { registration_ok: enable.ok }),
+  });
+
   console.log(
     JSON.stringify(
       {
@@ -1867,7 +2129,7 @@ function runHermesInstall(args) {
 function runCodexInstall(args) {
   const codexHome = resolveCodexHome();
   const pluginSource = resolveCodexPluginSource();
-  const pinnedEnv = pinEditorMcpEnv(pluginSource);
+  const pinnedEnv = { pinned: false, reason: "plugin source is immutable" };
   const pluginRoot = resolveCodexPluginInstallRoot();
   const pluginTarget = path.join(pluginRoot, "agent-wallet");
   const marketplacePath = resolveCodexMarketplacePath();
@@ -1927,6 +2189,15 @@ function runCodexInstall(args) {
     }
   }
 
+  recordManagedIntegration("codex", {
+    codex_home: codexHome,
+    plugin_target: pluginTarget,
+    marketplace_path: marketplace.marketplace_path,
+    marketplace_name: marketplace.marketplace_name,
+    restart_required: true,
+    ...(add.skipped ? {} : { registration_ok: add.ok }),
+  });
+
   console.log(
     JSON.stringify(
       {
@@ -1989,10 +2260,6 @@ function pinHomeIntoMcpFile(mcpPath, env = process.env) {
   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.
@@ -2065,8 +2332,7 @@ function ensureClaudeCodeMarketplace(marketplaceDir, pluginSource, force) {
 
 function runClaudeCodeInstall(args) {
   const pluginSource = resolveClaudeCodePluginSource();
-  const pinnedEnv = pinEditorMcpEnv(pluginSource);
-  const pinnedCache = pinClaudeCacheCopies();
+  const pinnedEnv = { pinned: false, reason: "plugin source is immutable" };
   const force = hasFlag(args, "--force");
   const skipEnable = hasFlag(args, "--skip-enable");
   const claudeBin = commandPath("claude");
@@ -2127,7 +2393,18 @@ function runClaudeCodeInstall(args) {
     }
   }
 
+  recordManagedIntegration("claude-code", {
+    marketplace_dir: marketplaceDir,
+    plugin_target: pluginLink,
+    cache_root: path.resolve(
+      expandHome(process.env.AGENT_WALLET_CLAUDE_CODE_CACHE_ROOT || "~/.claude/plugins/cache"),
+    ),
+    restart_required: true,
+    ...(enable.skipped ? {} : { registration_ok: enable.ok }),
+  });
+
   const ok = enable.skipped || enable.ok;
+  const pinnedCache = pinClaudeCacheCopies();
   const pluginDirFlagFull = `claude --plugin-dir ${pluginSource}`;
   console.log(
     JSON.stringify(
@@ -2152,76 +2429,449 @@ function runClaudeCodeInstall(args) {
   return enable.skipped || enable.ok ? 0 : 1;
 }
 
-function hermesInstallPresent(env = process.env) {
+function runtimeReleasePath(value, env = process.env) {
+  if (!value) return false;
+  try {
+    const releasesRoot = path.join(resolveRuntimeBase(env), "releases");
+    const relative = path.relative(releasesRoot, path.resolve(expandHome(String(value))));
+    return Boolean(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`);
+  } catch {
+    return false;
+  }
+}
+
+function pathEntryExists(pathname) {
+  try {
+    fs.lstatSync(pathname);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function repairRuntimeSymlink(name, linkPath, desiredTarget, env = process.env, { allowExternal = false } = {}) {
+  let rawTarget;
+  try {
+    const stat = fs.lstatSync(linkPath);
+    if (!stat.isSymbolicLink()) {
+      return { name, attempted: false, ok: true, repaired: false, reason: "not a symlink" };
+    }
+    rawTarget = fs.readlinkSync(linkPath);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return { name, attempted: false, ok: true, repaired: false, reason: "not installed" };
+    }
+    return { name, attempted: true, ok: false, repaired: false, error: error.message };
+  }
+
+  const absoluteTarget = path.resolve(path.dirname(linkPath), rawTarget);
+  const logicalCurrent = currentRuntimePath(env);
+  if (absoluteTarget === path.resolve(desiredTarget) || absoluteTarget.startsWith(`${logicalCurrent}${path.sep}`)) {
+    return { name, attempted: true, ok: true, repaired: false, reason: "already current" };
+  }
+  if (!allowExternal && !runtimeReleasePath(absoluteTarget, env)) {
+    return { name, attempted: false, ok: true, repaired: false, reason: "external target preserved" };
+  }
+  if (!fs.existsSync(desiredTarget)) {
+    return { name, attempted: true, ok: false, repaired: false, error: `missing ${desiredTarget}` };
+  }
+  switchSymlink(linkPath, desiredTarget);
+  return { name, attempted: true, ok: true, repaired: true, target: desiredTarget };
+}
+
+function repairHermesEnv(envPath, env = process.env) {
+  const existing = readEnvFile(envPath);
+  const repaired = [];
+  const currentPackage = path.join(currentRuntimePath(env), "agent-wallet");
+  if (runtimeReleasePath(existing.AGENT_WALLET_PACKAGE_ROOT, env)) {
+    envFileSet(envPath, { AGENT_WALLET_PACKAGE_ROOT: currentPackage });
+    repaired.push("AGENT_WALLET_PACKAGE_ROOT");
+  }
+  if (runtimeReleasePath(existing.AGENT_WALLET_PYTHON, env)) {
+    const currentPython = resolveVenvPython(currentRuntimePath(env));
+    if (currentPython) {
+      envFileSet(envPath, { AGENT_WALLET_PYTHON: currentPython });
+    } else {
+      envFileUnset(envPath, ["AGENT_WALLET_PYTHON"]);
+    }
+    repaired.push("AGENT_WALLET_PYTHON");
+  }
+  return repaired;
+}
+
+function legacyHermesIntegration(env = process.env) {
   const hermesHome = resolveHermesHome(env);
-  return (
-    fs.existsSync(path.join(hermesHome, "plugins", "agent_wallet")) ||
-    fs.existsSync(path.join(hermesHome, ".env"))
+  const pluginTarget = path.join(hermesHome, "plugins", "agent_wallet");
+  let target;
+  try {
+    if (!fs.lstatSync(pluginTarget).isSymbolicLink()) return null;
+    target = path.resolve(path.dirname(pluginTarget), fs.readlinkSync(pluginTarget));
+  } catch {
+    return null;
+  }
+  const manifest = readTextIfExists(path.join(target, "plugin.yaml"));
+  if (!/^name:\s*agent[-_]wallet\s*$/m.test(manifest)) return null;
+  return recordManagedIntegration(
+    "hermes",
+    {
+      hermes_home: hermesHome,
+      plugin_target: pluginTarget,
+      env_path: path.join(hermesHome, ".env"),
+      adopted_legacy_install: true,
+    },
+    env,
   );
 }
 
-function codexInstallPresent(env = process.env) {
-  return (
-    fs.existsSync(path.join(resolveCodexPluginInstallRoot(env), "agent-wallet")) ||
-    fs.existsSync(resolveCodexMarketplacePath(env))
+function repairOpenclawIntegration(env = process.env) {
+  const entry = managedIntegration("openclaw", env);
+  if (!entry) {
+    return { name: "openclaw", attempted: false, ok: true, repaired: false, reason: "not managed" };
+  }
+  const configPath = path.resolve(
+    expandHome(entry.config_path || path.join(resolveOpenclawHome(env), "openclaw.json")),
+  );
+  let config;
+  try {
+    config = readJsonFile(configPath);
+  } catch (error) {
+    return { name: "openclaw", attempted: true, ok: false, repaired: false, error: error.message };
+  }
+  if (!config || typeof config !== "object") {
+    return { name: "openclaw", attempted: true, ok: false, repaired: false, error: `missing ${configPath}` };
+  }
+
+  const currentRoot = currentRuntimePath(env);
+  const extensionPath = path.join(currentRoot, ".openclaw", "extensions", "agent-wallet");
+  const packageRootPath = path.join(currentRoot, "agent-wallet");
+  const pythonBin = resolveVenvPython(currentRoot);
+  const plugins = config.plugins && typeof config.plugins === "object" ? config.plugins : (config.plugins = {});
+  const load = plugins.load && typeof plugins.load === "object" ? plugins.load : (plugins.load = {});
+  const paths = Array.isArray(load.paths) ? load.paths : [];
+  load.paths = [
+    ...paths.filter((item) => {
+      const value = String(item || "");
+      return !value.replaceAll("\\", "/").endsWith("/.openclaw/extensions/agent-wallet");
+    }),
+    extensionPath,
+  ];
+  const entries = plugins.entries && typeof plugins.entries === "object" ? plugins.entries : (plugins.entries = {});
+  const walletEntry = entries["agent-wallet"];
+  if (!walletEntry || typeof walletEntry !== "object") {
+    return {
+      name: "openclaw",
+      attempted: false,
+      ok: true,
+      repaired: false,
+      reason: "plugin entry not configured",
+    };
+  }
+  walletEntry.enabled = true;
+  walletEntry.config = walletEntry.config && typeof walletEntry.config === "object" ? walletEntry.config : {};
+  walletEntry.config.packageRoot = packageRootPath;
+  if (pythonBin) walletEntry.config.pythonBin = pythonBin;
+  writeJsonFileAtomic(configPath, config);
+  recordManagedIntegration(
+    "openclaw",
+    {
+      config_path: configPath,
+      extension_path: extensionPath,
+      package_root: packageRootPath,
+      restart_required: true,
+    },
+    env,
   );
+  return {
+    name: "openclaw",
+    attempted: true,
+    ok: true,
+    repaired: true,
+    config_path: configPath,
+    restart_required: true,
+  };
 }
 
-function claudeCodeInstallPresent(env = process.env) {
-  const marketplaceDir = resolveClaudeCodeMarketplaceDir(env);
-  const cacheRoot = path.resolve(
-    expandHome(env.AGENT_WALLET_CLAUDE_CODE_CACHE_ROOT || "~/.claude/plugins/cache"),
+function symlinkManifestMatches(linkPath, manifestRelativePath, expectedName) {
+  let target;
+  try {
+    if (!fs.lstatSync(linkPath).isSymbolicLink()) return false;
+    target = path.resolve(path.dirname(linkPath), fs.readlinkSync(linkPath));
+  } catch {
+    return false;
+  }
+  try {
+    const manifest = readJsonFile(path.join(target, manifestRelativePath));
+    return manifest && manifest.name === expectedName;
+  } catch {
+    return false;
+  }
+}
+
+function legacyCodexIntegration(env = process.env) {
+  const marketplacePath = resolveCodexMarketplacePath(env);
+  let marketplace;
+  try {
+    marketplace = readJsonFile(marketplacePath);
+  } catch {
+    return null;
+  }
+  const pluginTarget = path.join(resolveCodexPluginInstallRoot(env), "agent-wallet");
+  const registered = Array.isArray(marketplace?.plugins) && marketplace.plugins.some(
+    (item) => item?.name === "agent-wallet" && item?.source?.source === "local",
   );
-  return (
-    fs.existsSync(path.join(marketplaceDir, "plugins", "agent-wallet")) ||
-    fs.existsSync(path.join(cacheRoot, CLAUDE_CODE_MARKETPLACE_NAME, "agent-wallet"))
+  if (!registered || !symlinkManifestMatches(pluginTarget, ".codex-plugin/plugin.json", "agent-wallet")) {
+    return null;
+  }
+  return recordManagedIntegration(
+    "codex",
+    {
+      codex_home: resolveCodexHome(env),
+      plugin_target: pluginTarget,
+      marketplace_path: marketplacePath,
+      marketplace_name: String(marketplace.name || "local"),
+      adopted_legacy_install: true,
+    },
+    env,
   );
 }
 
-function captureInstallerRefresh(name, runFn, args) {
-  const originalLog = console.log;
-  const lines = [];
-  console.log = (...items) => {
-    lines.push(items.join(" "));
-  };
+function legacyClaudeCodeIntegration(env = process.env) {
+  const marketplaceDir = resolveClaudeCodeMarketplaceDir(env);
+  let manifest;
   try {
-    const code = runFn(args);
-    const output = lines.join("\n");
-    return {
-      name,
-      attempted: true,
-      ok: code === 0,
-      code,
-      payload: output ? extractTrailingJson(output) : null,
-      error: code === 0 ? "" : output.trim(),
-    };
-  } catch (error) {
+    manifest = readJsonFile(path.join(marketplaceDir, ".claude-plugin", "marketplace.json"));
+  } catch {
+    return null;
+  }
+  const pluginTarget = path.join(marketplaceDir, "plugins", "agent-wallet");
+  const registered = manifest?.name === CLAUDE_CODE_MARKETPLACE_NAME &&
+    Array.isArray(manifest.plugins) && manifest.plugins.some((item) => item?.name === "agent-wallet");
+  if (!registered || !symlinkManifestMatches(pluginTarget, ".claude-plugin/plugin.json", "agent-wallet")) {
+    return null;
+  }
+  return recordManagedIntegration(
+    "claude-code",
+    {
+      marketplace_dir: marketplaceDir,
+      plugin_target: pluginTarget,
+      cache_root: path.resolve(
+        expandHome(env.AGENT_WALLET_CLAUDE_CODE_CACHE_ROOT || "~/.claude/plugins/cache"),
+      ),
+      adopted_legacy_install: true,
+    },
+    env,
+  );
+}
+
+function runHostRefresh(command, args, env = process.env) {
+  const binary = commandPath(command);
+  if (!binary) {
     return {
-      name,
-      attempted: true,
+      attempted: false,
       ok: false,
-      code: 1,
-      payload: null,
-      error: error?.message || String(error),
+      error: `${command} CLI not found`,
+      fix: args.join(" "),
     };
-  } finally {
-    console.log = originalLog;
   }
+  const result = spawnSync(binary, args, { cwd: packageRoot, encoding: "utf8", env });
+  return {
+    attempted: true,
+    ok: result.status === 0,
+    error: result.status === 0 ? "" : (result.stderr || result.stdout || "").trim(),
+    fix: result.status === 0 ? "" : `${command} ${args.join(" ")}`,
+  };
 }
 
-function refreshInstalledEditorIntegrations(env = process.env) {
-  const results = [];
-  if (hermesInstallPresent(env)) {
-    results.push(captureInstallerRefresh("hermes", runHermesInstall, ["--yes", "--force", "--skip-enable"]));
+function globalNpmPackageInfo(env = process.env) {
+  const npmBin = commandPath("npm");
+  if (!npmBin) return null;
+  const rootResult = spawnSync(npmBin, ["root", "--global"], { encoding: "utf8", env });
+  if (rootResult.status !== 0) return null;
+  const packageRoot = path.join(rootResult.stdout.trim(), ...packageJson.name.split("/"));
+  try {
+    const manifest = readJsonFile(path.join(packageRoot, "package.json"));
+    if (manifest?.name !== packageJson.name) return null;
+    return { npm_bin: npmBin, package_root: packageRoot, version: manifest.version || null };
+  } catch {
+    return null;
   }
-  if (codexInstallPresent(env)) {
-    results.push(captureInstallerRefresh("codex", runCodexInstall, ["--yes", "--force", "--skip-enable"]));
+}
+
+function refreshGlobalCliIfNeeded(env = process.env) {
+  const installed = globalNpmPackageInfo(env);
+  if (!installed) {
+    return { attempted: false, ok: true, reason: "global package is not installed" };
+  }
+  if (installed.version === packageVersion) {
+    return { attempted: false, ok: true, reason: "already current", version: packageVersion };
   }
-  if (claudeCodeInstallPresent(env)) {
-    results.push(
-      captureInstallerRefresh("claude-code", runClaudeCodeInstall, ["--yes", "--force", "--skip-enable"]),
+  const fromNpmCache = path.resolve(packageRoot).split(path.sep).includes("_npx");
+  const forced = env.AGENT_WALLET_FORCE_GLOBAL_CLI_REFRESH === "1";
+  if (!fromNpmCache && !forced) {
+    return {
+      attempted: false,
+      ok: false,
+      reason: "installer is not running from npm exec",
+      installed_version: installed.version,
+      target_version: packageVersion,
+      fix: `npm install --global ${packageJson.name}@${packageVersion}`,
+    };
+  }
+  const packageSpec = `${packageJson.name}@${packageVersion}`;
+  const result = spawnSync(
+    installed.npm_bin,
+    ["install", "--global", "--no-audit", "--no-fund", packageSpec],
+    { encoding: "utf8", env },
+  );
+  return {
+    attempted: true,
+    ok: result.status === 0,
+    previous_version: installed.version,
+    target_version: packageVersion,
+    error: result.status === 0 ? "" : (result.stderr || result.stdout || "").trim(),
+    fix: result.status === 0 ? "" : `npm install --global ${packageSpec}`,
+  };
+}
+
+function refreshCodexIntegration(entry, env = process.env) {
+  const pluginTarget = path.resolve(
+    expandHome(entry.plugin_target || path.join(resolveCodexPluginInstallRoot(env), "agent-wallet")),
+  );
+  const marketplacePath = path.resolve(
+    expandHome(entry.marketplace_path || resolveCodexMarketplacePath(env)),
+  );
+  const link = repairRuntimeSymlink(
+    "codex",
+    pluginTarget,
+    path.join(currentRuntimePath(env), "codex", "plugins", "agent-wallet"),
+    env,
+    { allowExternal: true },
+  );
+  if (!link.ok) return link;
+  const marketplace = ensureCodexMarketplaceEntry({ marketplacePath, pluginName: "agent-wallet" });
+  const registration = runHostRefresh(
+    "codex",
+    ["plugin", "add", `agent-wallet@${marketplace.marketplace_name}`],
+    { ...env, CODEX_HOME: entry.codex_home || resolveCodexHome(env) },
+  );
+  recordManagedIntegration(
+    "codex",
+    {
+      ...entry,
+      plugin_target: pluginTarget,
+      marketplace_path: marketplacePath,
+      marketplace_name: marketplace.marketplace_name,
+      registration_ok: registration.ok,
+      restart_required: true,
+    },
+    env,
+  );
+  return {
+    ...link,
+    ok: link.ok && registration.ok,
+    registration,
+    restart_required: true,
+  };
+}
+
+function refreshClaudeCodeIntegration(entry, env = process.env) {
+  const marketplaceDir = path.resolve(
+    expandHome(entry.marketplace_dir || resolveClaudeCodeMarketplaceDir(env)),
+  );
+  const cacheRoot = path.resolve(
+    expandHome(entry.cache_root || env.AGENT_WALLET_CLAUDE_CODE_CACHE_ROOT || "~/.claude/plugins/cache"),
+  );
+  const pluginTarget = path.resolve(
+    expandHome(entry.plugin_target || path.join(marketplaceDir, "plugins", "agent-wallet")),
+  );
+  const link = repairRuntimeSymlink(
+    "claude-code",
+    pluginTarget,
+    path.join(currentRuntimePath(env), "claude-code", "plugins", "agent-wallet"),
+    env,
+    { allowExternal: true },
+  );
+  if (!link.ok) return link;
+  ensureClaudeCodeMarketplace(
+    marketplaceDir,
+    path.join(currentRuntimePath(env), "claude-code", "plugins", "agent-wallet"),
+    true,
+  );
+  const marketplaceAdd = runHostRefresh(
+    "claude",
+    ["plugin", "marketplace", "add", marketplaceDir, "--scope", "user"],
+    env,
+  );
+  const registration = marketplaceAdd.ok
+    ? runHostRefresh(
+        "claude",
+        ["plugin", "install", `agent-wallet@${CLAUDE_CODE_MARKETPLACE_NAME}`, "--scope", "user"],
+        env,
+      )
+    : { attempted: false, ok: false, error: "marketplace refresh failed", fix: marketplaceAdd.fix };
+  const cachePins = pinClaudeCacheCopies({
+    ...env,
+    AGENT_WALLET_CLAUDE_CODE_CACHE_ROOT: cacheRoot,
+  });
+  recordManagedIntegration(
+    "claude-code",
+    {
+      ...entry,
+      marketplace_dir: marketplaceDir,
+      plugin_target: pluginTarget,
+      cache_root: cacheRoot,
+      registration_ok: registration.ok,
+      restart_required: true,
+    },
+    env,
+  );
+  return {
+    ...link,
+    ok: link.ok && marketplaceAdd.ok && registration.ok,
+    marketplace_add: marketplaceAdd,
+    registration,
+    cache_pins: cachePins,
+    restart_required: true,
+  };
+}
+
+function repairInstalledEditorIntegrations(env = process.env) {
+  const results = [repairOpenclawIntegration(env)];
+  const currentRoot = currentRuntimePath(env);
+  const hermesEntry = managedIntegration("hermes", env) || legacyHermesIntegration(env);
+  if (hermesEntry) {
+    const hermesTarget = path.resolve(expandHome(hermesEntry.plugin_target));
+    const hermesEnvPath = path.resolve(expandHome(hermesEntry.env_path));
+    const result = repairRuntimeSymlink(
+      "hermes",
+      hermesTarget,
+      path.join(currentRoot, "hermes", "plugins", "agent_wallet"),
+      env,
+      { allowExternal: true },
     );
+    result.env_repaired = repairHermesEnv(hermesEnvPath, env);
+    result.restart_required = true;
+    if (result.ok) {
+      recordManagedIntegration(
+        "hermes",
+        {
+          ...hermesEntry,
+          plugin_target: hermesTarget,
+          env_path: hermesEnvPath,
+          restart_required: true,
+        },
+        env,
+      );
+    }
+    results.push(result);
   }
+
+  const codexEntry = managedIntegration("codex", env) || legacyCodexIntegration(env);
+  if (codexEntry) results.push(refreshCodexIntegration(codexEntry, env));
+
+  const claudeEntry = managedIntegration("claude-code", env) || legacyClaudeCodeIntegration(env);
+  if (claudeEntry) results.push(refreshClaudeCodeIntegration(claudeEntry, env));
   return results;
 }