@agentlayer.tech/wallet 0.1.74 → 0.1.76

package/bin/openclaw-agent-wallet.mjs

@@ -6,6 +6,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { createBootKeyManager } from "./lib/boot-key.mjs";
+import { createHostIntegrationManager, createIntegrationManager } from "./lib/integrations.mjs";
+import { createUpdateTransactionManager } from "./lib/update-transaction.mjs";
 
 const cliPath = fileURLToPath(import.meta.url);
 const packageRoot = path.resolve(path.dirname(cliPath), "..");
@@ -388,20 +391,85 @@ function stagingRootFor(version, env = process.env) {
   );
 }
 
-function updateJournalPath(env = process.env) {
-  return path.join(resolveRuntimeBase(env), "update-journal.json");
+function updateTransactions(env = process.env) {
+  return createUpdateTransactionManager({
+    runtimeBase: resolveRuntimeBase(env),
+    packageVersion,
+    env,
+  });
 }
 
-function writeUpdateJournal(state, details = {}, env = process.env) {
-  writeJsonFile(updateJournalPath(env), {
-    schema_version: 1,
-    state,
-    version: packageVersion,
-    updated_at: new Date().toISOString(),
-    ...details,
+function acquireUpdateLock(env = process.env) {
+  return updateTransactions(env).acquireLock();
+}
+
+function releaseUpdateLock(lock) {
+  return createUpdateTransactionManager({
+    runtimeBase: path.dirname(lock.path),
+    packageVersion,
+  }).releaseLock(lock);
+}
+
+function holdUpdateLockForTest(env = process.env) {
+  updateTransactions(env).holdLockForTest();
+}
+
+function readUpdateJournal(env = process.env) {
+  return updateTransactions(env).readJournal();
+}
+
+function integrations(env = process.env) {
+  return createIntegrationManager({
+    runtimeBase: resolveRuntimeBase(env),
+    packageVersion,
+    activeVersion: () => activeVersion(env),
+  });
+}
+
+function recordManagedIntegration(name, details = {}, env = process.env) {
+  return integrations(env).record(name, details);
+}
+
+function integrationSyncStatus(env = process.env) {
+  return integrations(env).status();
+}
+
+function hostIntegrations(env = process.env) {
+  return createHostIntegrationManager({
+    env,
+    packageRoot,
+    registry: integrations(env),
+    currentRuntimePath: currentRuntimePath(env),
+    openclawHome: resolveOpenclawHome(env),
+    hermesHome: resolveHermesHome(env),
+    codexHome: resolveCodexHome(env),
+    codexPluginRoot: resolveCodexPluginInstallRoot(env),
+    codexMarketplacePath: resolveCodexMarketplacePath(env),
+    claudeMarketplaceDir: resolveClaudeCodeMarketplaceDir(env),
+    claudeMarketplaceName: CLAUDE_CODE_MARKETPLACE_NAME,
+    expandHome,
+    resolveVenvPython,
+    commandPath,
+    repairRuntimeSymlink,
+    repairHermesEnv,
+    ensureCodexMarketplaceEntry,
+    ensureClaudeCodeMarketplace,
+    pinClaudeCacheCopies,
   });
 }
 
+function writeUpdateJournal(state, details = {}, env = process.env) {
+  updateTransactions(env).writeJournal(state, details);
+}
+
+function recoverInterruptedUpdate(env = process.env) {
+  return updateTransactions(env).recover();
+}
+
+function updateRecoveryStatus(env = process.env) {
+  return updateTransactions(env).status();
+}
+
 function writeReleaseState(runtimeRoot, state, details = {}) {
   writeJsonFile(path.join(runtimeRoot, ".agent-wallet-release.json"), {
     schema_version: 1,
@@ -423,14 +491,14 @@ function failStagingRuntime(stagingRoot, error) {
   return failedRoot;
 }
 
-function commitStagedRuntime(stagingRoot, releaseRoot) {
+function commitStagedRuntime(stagingRoot, releaseRoot, replacedRoot = null, env = process.env) {
   if (!stagingRoot) return null;
-  let replacedRoot = null;
   if (fs.existsSync(releaseRoot)) {
-    replacedRoot = uniquePathWithSuffix(
+    replacedRoot ||= uniquePathWithSuffix(
       path.join(path.dirname(releaseRoot), `${path.basename(releaseRoot)}-replaced`),
     );
     fs.renameSync(releaseRoot, replacedRoot);
+    if (env.AGENT_WALLET_TEST_EXIT_AFTER_RELEASE_RENAME === "1") process.exit(86);
   }
   try {
     fs.renameSync(stagingRoot, releaseRoot);
@@ -944,146 +1012,52 @@ function writeJsonFile(pathname, value) {
   fs.writeFileSync(pathname, `${JSON.stringify(value, null, 2)}\n`);
 }
 
-function currentBootKey(env = process.env) {
-  const currentRoot = resolvedCurrentRuntimeRoot(env);
-  if (!currentRoot) return "";
-  return readEnvFile(path.join(currentRoot, "agent-wallet", ".env")).AGENT_WALLET_BOOT_KEY || "";
-}
-
-function readTextIfExists(pathname) {
-  try {
-    return fs.readFileSync(pathname, "utf8");
-  } catch (error) {
-    if (error?.code === "ENOENT") return "";
-    throw error;
-  }
-}
-
-function writeSecretFile(pathname, value) {
+function writeJsonFileAtomic(pathname, value, mode = 0o600) {
   fs.mkdirSync(path.dirname(pathname), { recursive: true });
-  fs.writeFileSync(pathname, `${String(value || "").trim()}\n`, { mode: 0o600 });
+  const tempPath = `${pathname}.tmp-${process.pid}-${Date.now()}`;
   try {
-    fs.chmodSync(pathname, 0o600);
-  } catch {
-    // ignored
+    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 resolveBootKeyFromFile(env = process.env) {
-  const keyFile = String(env.AGENT_WALLET_BOOT_KEY_FILE || "").trim();
-  if (!keyFile) return "";
-  return readTextIfExists(path.resolve(expandHome(keyFile))).trim();
-}
-
-function defaultBootKeyFile(env = process.env) {
-  return path.join(resolveRuntimeBase(env), "boot-key");
+function bootKeys(env = process.env) {
+  return createBootKeyManager({
+    runtimeBase: resolveRuntimeBase(env),
+    openclawHome: resolveOpenclawHome(env),
+    currentRuntimeRoot: () => resolvedCurrentRuntimeRoot(env),
+    resolveVenvPython,
+    expandHome,
+    bridgeTimeoutMs: positiveIntEnv(
+      "AGENT_WALLET_KEYSTORE_BRIDGE_TIMEOUT_MS",
+      KEYSTORE_BRIDGE_TIMEOUT_MS,
+      env,
+    ),
+    env,
+  });
 }
 
 function ensureBootKeyFile(env = process.env) {
-  const configuredFile = String(env.AGENT_WALLET_BOOT_KEY_FILE || "").trim();
-  const keyFile = configuredFile ? path.resolve(expandHome(configuredFile)) : defaultBootKeyFile(env);
-  const existing = readTextIfExists(keyFile).trim();
-  if (existing) {
-    return { path: keyFile, status: "existing" };
-  }
-  const bootKey = String(env.AGENT_WALLET_BOOT_KEY || "").trim() || resolveBootKeyFromFile(env) || currentBootKey(env);
-  if (!bootKey) {
-    return { path: keyFile, status: "missing" };
-  }
-  writeSecretFile(keyFile, bootKey);
-  return { path: keyFile, status: "created" };
-}
-
-// Read the boot key from the OS keystore via the current runtime's Python
-// (best-effort, "" on any failure). Lets a re-install after the runtime migration
-// — which moves the key into the keystore and deletes every plaintext copy — still
-// resolve the existing boot key instead of refusing to touch sealed secrets.
-function readBootKeyFromKeystore(env = process.env) {
-  const runtimeRoot = resolvedCurrentRuntimeRoot(env);
-  if (!runtimeRoot) return "";
-  const py = resolveVenvPython(runtimeRoot);
-  if (!py) return "";
-  try {
-    const res = spawnSync(
-      py,
-      ["-c", "from agent_wallet.config import read_boot_key_from_keystore 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 "";
-    return String(res.stdout || "").trim();
-  } catch {
-    return "";
-  }
+  return bootKeys(env).ensureFile();
 }
 
-// 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: "" };
-  }
+  return bootKeys(env).resolveFromRuntime();
 }
 
 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" };
+  return bootKeys(env).resolveLegacy();
 }
 
-// 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
-// (e.g. no usable keystore), in which case the caller keeps the legacy .env write.
 function provisionBootKeyToKeystore(releaseRoot, env, bootKey) {
-  const key = String(bootKey || "").trim();
-  if (!key) return false;
-  const py = resolveVenvPython(releaseRoot);
-  if (!py) return false;
-  try {
-    const res = spawnSync(
-      py,
-      ["-m", "agent_wallet.openclaw_cli", "boot-key-import", "--key-stdin"],
-      {
-        cwd: path.join(releaseRoot, "agent-wallet"),
-        input: key,
-        encoding: "utf8",
-        timeout: positiveIntEnv("AGENT_WALLET_KEYSTORE_BRIDGE_TIMEOUT_MS", KEYSTORE_BRIDGE_TIMEOUT_MS, env),
-        env: { ...env, OPENCLAW_HOME: resolveOpenclawHome(env) },
-      },
-    );
-    return (res.status ?? 1) === 0;
-  } catch {
-    return false;
-  }
+  return bootKeys(env).provision(releaseRoot, bootKey);
 }
 
 function resolveVenvPython(releaseRoot) {
@@ -1161,6 +1135,10 @@ function verifyRuntime(releaseRoot, env = process.env) {
   };
 }
 
+function verifyBootKeyWithRuntime(releaseRoot, env = process.env) {
+  return bootKeys(env).verifyWithRuntime(releaseRoot);
+}
+
 function resolveEditorServerChecks(env = process.env) {
   const checks = [];
   // Claude Code's launcher (run_mcp.sh) falls back to the runtime codex
@@ -1301,10 +1279,30 @@ 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 recoveryStatus = updateRecoveryStatus(env);
+  checks.push({
+    name: "update_recovery_state",
+    ok: true,
+    ...recoveryStatus,
+    error: "",
+    fix: recoveryStatus.needs_recovery ? "wallet install --yes" : "",
+  });
+
   const ok = checks.every((c) => c.ok);
   console.log(
     JSON.stringify(
       {
+        schema_version: 1,
         ok,
         package_name: packageJson.name,
         package_version: packageVersion,
@@ -1324,6 +1322,7 @@ function runDoctor(args = []) {
 
 function runStatus(args = []) {
   const payload = {
+    schema_version: 1,
     ok: true,
     package_name: packageJson.name,
     package_version: packageVersion,
@@ -1336,6 +1335,8 @@ function runStatus(args = []) {
     failed_releases: listFailedReleases(),
     update_available: computeUpdateAvailability(),
     runtime_in_sync: computeRuntimeInSync(),
+    framework_integrations: integrationSyncStatus(),
+    update_recovery: updateRecoveryStatus(),
   };
   if (hasFlag(args, "--verbose")) {
     payload.verbose = true;
@@ -1353,19 +1354,18 @@ function buildInstallerEnv(args) {
   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) {
-    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;
+  const runtimeResolution = readBootKeyFromRuntimeResolver(env);
+  if (runtimeResolution.supported) {
+    bootKeySource = runtimeResolution.key ? "runtime_verified" : "runtime_rejected";
+    if (runtimeResolution.key) {
+      env.AGENT_WALLET_BOOT_KEY = runtimeResolution.key;
+    } else {
+      delete env.AGENT_WALLET_BOOT_KEY;
     }
+  } else if (!env.AGENT_WALLET_BOOT_KEY) {
+    const fallback = resolveLegacyInstallerBootKey(env);
+    bootKeySource = fallback.source;
+    if (fallback.key) env.AGENT_WALLET_BOOT_KEY = fallback.key;
   }
 
   const shouldGenerateSecrets =
@@ -1395,7 +1395,7 @@ function buildInstallerEnv(args) {
   return { env, generated, bootKeySource };
 }
 
-function runInstall(args, { commandName = "install" } = {}) {
+function runInstallUnlocked(args, { commandName = "install" } = {}) {
   if (!fs.existsSync(setupPath)) {
     console.error(`Missing bundled setup.sh at ${setupPath}`);
     return 1;
@@ -1409,6 +1409,13 @@ function runInstall(args, { commandName = "install" } = {}) {
   const previousPath = previousRuntimePath();
   const installerArgs = withoutCliOnlyArgs(args);
   const dryRun = hasFlag(args, "--dry-run");
+  const recovery = dryRun
+    ? { attempted: false, ok: true, reason: "dry run" }
+    : recoverInterruptedUpdate(process.env);
+  if (!recovery.ok) {
+    console.error(`Could not recover interrupted update: ${recovery.reason || recovery.error}`);
+    return 1;
+  }
   const stagingRoot = !explicitRuntimeRoot && !dryRun ? stagingRootFor(packageVersion) : null;
   const installRoot = stagingRoot || releaseRoot;
 
@@ -1429,7 +1436,17 @@ function runInstall(args, { commandName = "install" } = {}) {
   const { env, generated, bootKeySource } = installerEnv;
   if (stagingRoot) {
     env.OPENCLAW_INSTALL_FINAL_ROOT = releaseRoot;
-    writeUpdateJournal("preparing", { staging_root: stagingRoot, release_root: releaseRoot }, env);
+    writeUpdateJournal(
+      "preparing",
+      {
+        transaction_id: crypto.randomUUID(),
+        staging_root: stagingRoot,
+        release_root: releaseRoot,
+        current_target_before: readLinkOrNull(currentPath),
+        previous_target_before: readLinkOrNull(previousPath),
+      },
+      env,
+    );
   }
   const result = spawnSync("sh", [setupPath, ...installerArgs], {
     cwd: packageRoot,
@@ -1523,6 +1540,34 @@ function runInstall(args, { commandName = "install" } = {}) {
     return 1;
   }
 
+  const bootKeyVerification = verifyBootKeyWithRuntime(installRoot, env);
+  if (!bootKeyVerification.ok) {
+    const failedRoot = failStagingRuntime(stagingRoot, bootKeyVerification.error);
+    writeUpdateJournal(
+      "failed",
+      { failed_runtime: failedRoot, error: bootKeyVerification.error },
+      env,
+    );
+    console.error(
+      JSON.stringify(
+        {
+          ok: false,
+          command: commandName,
+          version: packageVersion,
+          category: "boot_key_rejected",
+          error: bootKeyVerification.error,
+          switched_current: false,
+          failed_runtime: failedRoot,
+          current_runtime_target: readLinkOrNull(currentPath),
+          fix: "Remove stale AGENT_WALLET_BOOT_KEY overrides and retry the update.",
+        },
+        null,
+        2,
+      ),
+    );
+    return 1;
+  }
+
   if (env.AGENT_WALLET_BOOT_KEY) {
     const envPath = path.join(installRoot, "agent-wallet", ".env");
     // Prefer the OS keystore: provision the boot key there and keep the plaintext
@@ -1540,11 +1585,32 @@ function runInstall(args, { commandName = "install" } = {}) {
   writeReleaseState(installRoot, "verified", {
     verification_skipped: Boolean(verification.skipped),
   });
-  writeUpdateJournal("verified", { staging_root: stagingRoot, release_root: releaseRoot }, env);
+  writeUpdateJournal(
+    "verified",
+    { ...readUpdateJournal(env), staging_root: stagingRoot, release_root: releaseRoot },
+    env,
+  );
 
   let replacedRoot = null;
   try {
-    replacedRoot = commitStagedRuntime(stagingRoot, releaseRoot);
+    replacedRoot = fs.existsSync(releaseRoot)
+      ? uniquePathWithSuffix(
+          path.join(path.dirname(releaseRoot), `${path.basename(releaseRoot)}-replaced`),
+        )
+      : null;
+    writeUpdateJournal(
+      "committing",
+      {
+        ...readUpdateJournal(env),
+        staging_root: stagingRoot,
+        release_root: releaseRoot,
+        replaced_root: replacedRoot,
+        current_target_before: readLinkOrNull(currentPath),
+        previous_target_before: readLinkOrNull(previousPath),
+      },
+      env,
+    );
+    replacedRoot = commitStagedRuntime(stagingRoot, releaseRoot, replacedRoot, env);
   } catch (error) {
     const failedRoot = failStagingRuntime(stagingRoot, error.message);
     writeUpdateJournal("failed", { failed_runtime: failedRoot, error: error.message }, env);
@@ -1560,9 +1626,29 @@ function runInstall(args, { commandName = "install" } = {}) {
     switchSymlink(previousPath, previousTarget);
   }
   switchSymlink(currentPath, releaseRoot);
-  writeUpdateJournal("committed", { release_root: releaseRoot, previous_runtime: previousTarget }, env);
+  writeUpdateJournal(
+    "committed",
+    { ...readUpdateJournal(env), 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 = safelyRefreshIntegration(
+    "global-cli",
+    () => refreshGlobalCliIfNeeded(env),
+  );
 
   const pythonInfo = activePythonRuntimeInfo(env);
   const nodeInfo = activeNodeRuntimeInfo(env)
@@ -1585,7 +1671,9 @@ function runInstall(args, { commandName = "install" } = {}) {
         boot_key_source: bootKeySource,
         staged: Boolean(stagingRoot),
         release_state: "verified",
+        recovery,
         integration_refresh: integrationRefresh,
+        global_cli_refresh: globalCliRefresh,
       },
       null,
       2,
@@ -1594,6 +1682,34 @@ function runInstall(args, { commandName = "install" } = {}) {
   return 0;
 }
 
+function runInstall(args, options = {}) {
+  if (hasFlag(args, "--dry-run")) return runInstallUnlocked(args, options);
+  const lock = acquireUpdateLock(process.env);
+  if (!lock.ok) {
+    console.error(
+      JSON.stringify(
+        {
+          ok: false,
+          category: "update_locked",
+          error: "Another wallet install or update is already running.",
+          lock_path: lock.path,
+          lock_owner: lock.owner,
+          fix: "Wait for the active update to finish, then retry.",
+        },
+        null,
+        2,
+      ),
+    );
+    return 1;
+  }
+  try {
+    holdUpdateLockForTest(process.env);
+    return runInstallUnlocked(args, options);
+  } finally {
+    releaseUpdateLock(lock);
+  }
+}
+
 function resolveUpdatePackageSpec(env = process.env) {
   const explicit = String(env[UPDATE_PACKAGE_SPEC_ENV] || "").trim();
   if (explicit) return explicit;
@@ -2001,6 +2117,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(
       {
@@ -2086,6 +2210,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(
       {
@@ -2281,6 +2414,16 @@ 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}`;
@@ -2328,7 +2471,7 @@ function pathEntryExists(pathname) {
   }
 }
 
-function repairRuntimeSymlink(name, linkPath, desiredTarget, env = process.env) {
+function repairRuntimeSymlink(name, linkPath, desiredTarget, env = process.env, { allowExternal = false } = {}) {
   let rawTarget;
   try {
     const stat = fs.lstatSync(linkPath);
@@ -2348,7 +2491,7 @@ function repairRuntimeSymlink(name, linkPath, desiredTarget, env = process.env)
   if (absoluteTarget === path.resolve(desiredTarget) || absoluteTarget.startsWith(`${logicalCurrent}${path.sep}`)) {
     return { name, attempted: true, ok: true, repaired: false, reason: "already current" };
   }
-  if (!runtimeReleasePath(absoluteTarget, env)) {
+  if (!allowExternal && !runtimeReleasePath(absoluteTarget, env)) {
     return { name, attempted: false, ok: true, repaired: false, reason: "external target preserved" };
   }
   if (!fs.existsSync(desiredTarget)) {
@@ -2358,8 +2501,7 @@ function repairRuntimeSymlink(name, linkPath, desiredTarget, env = process.env)
   return { name, attempted: true, ok: true, repaired: true, target: desiredTarget };
 }
 
-function repairHermesEnv(env = process.env) {
-  const envPath = path.join(resolveHermesHome(env), ".env");
+function repairHermesEnv(envPath, env = process.env) {
   const existing = readEnvFile(envPath);
   const repaired = [];
   const currentPackage = path.join(currentRuntimePath(env), "agent-wallet");
@@ -2379,45 +2521,63 @@ function repairHermesEnv(env = process.env) {
   return repaired;
 }
 
-function repairInstalledEditorIntegrations(env = process.env) {
-  const results = [];
-  const currentRoot = currentRuntimePath(env);
-  const hermesTarget = path.join(resolveHermesHome(env), "plugins", "agent_wallet");
-  if (pathEntryExists(hermesTarget) || fs.existsSync(path.join(resolveHermesHome(env), ".env"))) {
-    const result = repairRuntimeSymlink(
-      "hermes",
-      hermesTarget,
-      path.join(currentRoot, "hermes", "plugins", "agent_wallet"),
-      env,
-    );
-    result.env_repaired = repairHermesEnv(env);
-    results.push(result);
+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;
   }
+}
 
-  const codexTarget = path.join(resolveCodexPluginInstallRoot(env), "agent-wallet");
-  if (pathEntryExists(codexTarget)) {
-    results.push(
-      repairRuntimeSymlink(
-        "codex",
-        codexTarget,
-        path.join(currentRoot, "codex", "plugins", "agent-wallet"),
-        env,
-      ),
-    );
+function refreshGlobalCliIfNeeded(env = process.env) {
+  const installed = globalNpmPackageInfo(env);
+  if (!installed) {
+    return { attempted: false, ok: true, reason: "global package is not installed" };
   }
-
-  const claudeTarget = path.join(resolveClaudeCodeMarketplaceDir(env), "plugins", "agent-wallet");
-  if (pathEntryExists(claudeTarget)) {
-    const result = repairRuntimeSymlink(
-      "claude-code",
-      claudeTarget,
-      path.join(currentRoot, "claude-code", "plugins", "agent-wallet"),
-      env,
-    );
-    result.cache_pins = pinClaudeCacheCopies(env);
-    results.push(result);
+  if (installed.version === packageVersion) {
+    return { attempted: false, ok: true, reason: "already current", version: packageVersion };
   }
-  return results;
+  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 safelyRefreshIntegration(name, callback) {
+  return integrations().safelyRefresh(name, callback);
+}
+
+function repairInstalledEditorIntegrations(env = process.env) {
+  return hostIntegrations(env).refreshAll();
 }
 
 const args = process.argv.slice(2);