impel-cli 0.20.38 → 0.20.40

package/src/commands/apps.js

@@ -32,8 +32,11 @@ import {
   ensureVendorApp,
   fetchGatewayModels,
   installManagedAppFiles,
+  MANAGED_RUNTIME_PREFLIGHT_EXIT_CODE,
   managedChatGPTConfigDrifted,
+  managedClaudeConfigDrifted,
   managedLauncherName,
+  managedRuntimePreflight,
   normalizeAppTarget,
   quitBlockingApps,
   readTenantManifest,
@@ -294,7 +297,18 @@ function windowsProcessFailure(result) {
 export function openManagedLauncher(launcher, {
   spawn = spawnSync,
   reportError = console.error,
+  preflight = managedRuntimePreflight,
 } = {}) {
+  // Runtime-presence preflight (the v0.20.32 exit-127 rule): never hand a
+  // managed bundle whose vendored runtime is missing or off-pin to the OS —
+  // that launch dies with an unactionable bare failure. One actionable line
+  // and a distinct exit code instead; unmanaged bundles are not judged here.
+  const runtime = preflight(launcher);
+  if (runtime && runtime.ok === false) {
+    reportError(runtime.message);
+    process.exitCode = MANAGED_RUNTIME_PREFLIGHT_EXIT_CODE;
+    return false;
+  }
   const result = spawn("/usr/bin/open", ["-n", launcher], { encoding: "utf8" });
   if (!result?.error && result?.status === 0) return true;
   const detail = result?.error?.message
@@ -740,7 +754,11 @@ export async function cmdWindowsApps(argv, overrides = {}) {
           claudeUserData: io.claudeUserData(io.environment, staleTenantId),
           tenantName: staleTenantId === stored.tenantId ? stored.tenantName : null,
         });
-        if (manifestIsFresh(stalePaths, stored) && !managedChatGPTConfigDrifted(stalePaths)) return true;
+        if (
+          manifestIsFresh(stalePaths, stored)
+          && !managedChatGPTConfigDrifted(stalePaths)
+          && !managedClaudeConfigDrifted(stalePaths)
+        ) return true;
       }
     }
     const config = await io.selectedConfig(targets, flags.tenant || null);
@@ -1329,7 +1347,12 @@ async function refreshApps(targets, { staleOnly = false, tenantId = null } = {},
       ? stored.tenantName || manifest?.tenantName
       : manifest?.tenantName,
   });
-  if (staleOnly && manifestIsFresh(paths, stored) && !managedChatGPTConfigDrifted(paths)) return;
+  if (
+    staleOnly
+    && manifestIsFresh(paths, stored)
+    && !managedChatGPTConfigDrifted(paths)
+    && !managedClaudeConfigDrifted(paths)
+  ) return;
 
   let config;
   try {

package/src/commands/converge.js

@@ -214,7 +214,23 @@ export async function cmdConverge(argv = [], overrides = {}) {
       goals: [{
         id: "shared-vendor-clis-ready",
         description: "Shared vendor CLI prerequisites are installed and discoverable",
-        run: () => sharedReady,
+        // Live probe, not a session snapshot: a vendor CLI installed outside
+        // this process (for example by the user in another terminal while the
+        // recovery session runs) must count as complete the moment the goal
+        // is evaluated, so recovery never re-issues an already-finished step.
+        run: async () => {
+          if (sharedReady) return true;
+          const prepared = await io.preparePlatformClis({
+            gatewayUrl: config.gatewayUrl,
+            tenantId: selected.id,
+            platform: io.platform,
+            skipInstall: true,
+            // Goals re-run before every system-risk step: the probe must be
+            // pure discovery — no installs, profile writes, or skill syncs.
+            inspectOnly: true,
+          });
+          return prepared.missingAfter.length === 0;
+        },
       }],
       explicit: true,
       noRecovery: false,

package/src/commands/mcp.js

@@ -263,7 +263,7 @@ export function runNativeAgentMcpServer({
         let value;
         if (name === NATIVE_AGENT_ANSWER_TOOL) {
           if (mode !== "answer") throw new Error("this native-agent binding cannot answer directly");
-          value = await transport.answer(args, { signal: controller.signal });
+          value = await transport.answer(args, { signal: controller.signal, onProgress });
         } else if (name === NATIVE_AGENT_RUN_TOOL) {
           if (mode === "recovery") throw new Error("retired native-agent bindings cannot start new runs");
           if (mode === "answer") throw new Error("direct-answer native-agent bindings cannot start durable runs");

package/src/commands/sessions.js

@@ -2,7 +2,8 @@ import { spawn } from "node:child_process";
 import path from "node:path";
 
 import { parseFlags } from "../args.js";
-import { appPaths, managedChatGPTConfigDrifted } from "../apps.js";
+import { appPaths, managedChatGPTConfigDrifted, managedClaudeConfigDrifted } from "../apps.js";
+import { windowsClaudeUserData } from "../windowsApps.js";
 import {
   clearSessionFlushLock,
   collectSessionHook,
@@ -32,23 +33,36 @@ const SPEC = {
   [MANAGED_SESSION_HOOK_FLAG]: { type: "boolean" },
 };
 
+// The Claude drift check reads the Claude app profile, which lives under
+// %LOCALAPPDATA% on Windows rather than the darwin tenant root.
+function managedAppDriftPaths(tenantId) {
+  return appPaths(undefined, tenantId, process.platform === "win32"
+    ? { claudeUserData: windowsClaudeUserData(process.env, tenantId) }
+    : {});
+}
+
+function anyManagedAppConfigDrifted(paths) {
+  return managedChatGPTConfigDrifted(paths) || managedClaudeConfigDrifted(paths);
+}
+
 /**
- * Repair a managed ChatGPT profile the desktop app just rewrote out from under
- * the gateway. Hooks are the only Impel code guaranteed to run while the app
- * is broken (the app stops calling the provider token helper once the managed
- * `model_provider` key is gone), so each codex hook event checks for drift and
- * kicks one detached stale-only refresh — which the drift-aware staleness gate
- * turns into a real repair. The heartbeat lock keeps repeated hook events from
- * stacking refresh children while one is already running.
+ * Repair a managed app profile a vendor just rewrote out from under the
+ * gateway. Hooks and the token helper are the only Impel code guaranteed to
+ * run while an app is broken (a drifted config can stop calling the provider
+ * token helper entirely), so both check for drift and kick one detached
+ * stale-only refresh — which the drift-aware staleness gate turns into a real
+ * repair. The heartbeat lock keeps repeated events from stacking refresh
+ * children while one is already running. Content-checks both managed
+ * surfaces (ChatGPT/Codex and Claude) by default.
  */
-export function maybeRepairManagedCodexApp(tenantId, {
-  drifted = managedChatGPTConfigDrifted,
+export function maybeRepairManagedApps(tenantId, {
+  drifted = anyManagedAppConfigDrifted,
   lockIsFresh = sessionFlushLockIsFresh,
   touchLock = touchSessionFlushLock,
   spawnRefresh = spawnDetachedAppRefresh,
 } = {}) {
   if (!tenantId) return false;
-  const paths = appPaths(undefined, tenantId);
+  const paths = managedAppDriftPaths(tenantId);
   if (!drifted(paths)) return false;
   const lock = path.join(paths.tenantRoot, "app-repair-heartbeat");
   if (lockIsFresh(lock, 60_000)) return false;
@@ -57,6 +71,19 @@ export function maybeRepairManagedCodexApp(tenantId, {
   return true;
 }
 
+/**
+ * The codex session-hook entry point: same repair, scoped to ChatGPT/Codex
+ * drift exactly as before the helper was generalized (the codex hook fires on
+ * codex events; Claude drift is healed by the token helper and the Claude
+ * session hooks' own refresh channel).
+ */
+export function maybeRepairManagedCodexApp(tenantId, overrides = {}) {
+  return maybeRepairManagedApps(tenantId, {
+    drifted: managedChatGPTConfigDrifted,
+    ...overrides,
+  });
+}
+
 function startDetachedFlush({ provider, tenant, session }) {
   const invocation = impelCliInvocation([
     "sessions",
@@ -101,6 +128,12 @@ export async function cmdSessions(argv) {
         flush: false,
       });
       if (flags.provider === "codex") maybeRepairManagedCodexApp(flags.tenant);
+      // The Claude mirror of the codex repair above: Claude Desktop rewrites
+      // its co-owned profile files too, and its session hooks are the only
+      // Impel code guaranteed to still run afterward.
+      if (flags.provider === "claude_code") {
+        maybeRepairManagedApps(flags.tenant, { drifted: managedClaudeConfigDrifted });
+      }
       if (config && (config.tenantId === flags.tenant || environmentValue("SESSIONS_DEV_ORG_ID"))) {
         // Hooks fire on every session event; only spawn a flush child when no
         // live one is already polling this session's outbox (heartbeat lock).

package/src/commands/setup.js

@@ -370,7 +370,23 @@ export async function cmdSetup(argv, overrides = {}) {
       goals: [{
         id: "shared-vendor-clis-ready",
         description: "Shared vendor CLI prerequisites are installed and discoverable",
-        run: () => sharedReady,
+        // Live probe, not a session snapshot: a vendor CLI installed outside
+        // this process (for example by the user in another terminal while the
+        // recovery session runs) must count as complete the moment the goal
+        // is evaluated, so recovery never re-issues an already-finished step.
+        run: async () => {
+          if (sharedReady) return true;
+          const prepared = await io.preparePlatformClis({
+            gatewayUrl,
+            tenantId: selected.id,
+            platform: io.platform,
+            skipInstall: true,
+            // Goals re-run before every system-risk step: the probe must be
+            // pure discovery — no installs, profile writes, or skill syncs.
+            inspectOnly: true,
+          });
+          return prepared.missingAfter.length === 0;
+        },
       }],
       explicit: Boolean(flags.repair),
       noRecovery: false,

package/src/commands/token.js

@@ -1,14 +1,21 @@
 import { loadConfig } from "../config.js";
 import { parseFlags } from "../args.js";
 import { ensureTenantSelection, normalizeTenantId, tenantCredential } from "../tenants.js";
+import { maybeRepairManagedApps } from "./sessions.js";
 import { RUNTIME_BRAND } from "../runtimeBrand.js";
 
 // This is the `apiKeyHelper` / auth-command contract: stdout (and only
 // stdout) must be exactly the bearer token, nothing else. Both Claude Code's
 // apiKeyHelper and Codex CLI's `model_providers.<id>.auth.command` call this.
-export async function cmdToken(argv = []) {
+export async function cmdToken(argv = [], overrides = {}) {
+  const io = {
+    loadConfig,
+    ensureTenantSelection,
+    repairManagedApps: maybeRepairManagedApps,
+    ...overrides,
+  };
   const { flags } = parseFlags(argv, { tenant: { type: "string" } });
-  const config = loadConfig();
+  const config = io.loadConfig();
   if (!config?.pat) {
     process.stderr.write(`${RUNTIME_BRAND.cli.command}: not authenticated. Run \`${RUNTIME_BRAND.cli.command} setup\` (or \`${RUNTIME_BRAND.cli.command} auth\`) first.\n`);
     process.exitCode = 1;
@@ -17,8 +24,21 @@ export async function cmdToken(argv = []) {
   try {
     const tenantId = flags.tenant
       ? normalizeTenantId(flags.tenant)
-      : (await ensureTenantSelection(config)).tenantId;
+      : (await io.ensureTenantSelection(config)).tenantId;
     process.stdout.write(`${tenantCredential(config.pat, tenantId)}\n`);
+    // Drift-aware self-heal, strictly AFTER the token bytes are on stdout: the
+    // vendor apps call this helper on every auth, which makes it an Impel
+    // entry point that keeps running even after a vendor settings-writer
+    // rewrites a managed profile (a drifted config once stopped invoking the
+    // rest of the heal channel entirely). Kick the same detached,
+    // heartbeat-locked stale-only refresh the session hooks use — for both
+    // Codex and Claude drift. It must never write to stdout, never block the
+    // emission above, and never change this command's exit code.
+    try {
+      io.repairManagedApps(tenantId);
+    } catch {
+      // Opportunistic only; the token contract is already fulfilled.
+    }
   } catch (error) {
     process.stderr.write(`${RUNTIME_BRAND.cli.command}: ${error.message}\n`);
     process.exitCode = 1;

package/src/commands/update.js

@@ -10,7 +10,7 @@ import { loadConfig, redactSecretText } from "../config.js";
 import { nativeCommandInvocation } from "../nativeProcess.js";
 import { withProgress } from "../progress.js";
 import { runInstallRecovery } from "../installRecovery/engine.js";
-import { brandedText, RUNTIME_BRAND } from "../runtimeBrand.js";
+import { brandedEnvironmentName, brandedText, RUNTIME_BRAND } from "../runtimeBrand.js";
 import { IMPEL_CLI_ENTRYPOINT } from "../selfInvocation.js";
 import {
   fetchRemoteVersion,
@@ -18,12 +18,20 @@ import {
   isNewerVersion,
   refreshUpdateCache,
   updateInstallSpec,
+  updatePackage,
   updateTagForVersion,
   writeUpdateCache,
 } from "../updates.js";
 
 const CLI_BIN = IMPEL_CLI_ENTRYPOINT;
 
+/**
+ * Loop guard for the fresh-build continuation: `_converge` children run with
+ * this marker so a nested `impel update` inside the cascade can never start
+ * another self-update (and thus another cascade) recursively.
+ */
+export const UPDATE_CASCADE_ENV = brandedEnvironmentName("UPDATE_CASCADE");
+
 /**
  * The version now on disk at the package that owns CLI_BIN, read FRESH (never
  * from this process's cached module graph). After `npm install -g` this is the
@@ -39,6 +47,28 @@ export function postInstallCliVersion() {
   }
 }
 
+/**
+ * Whether the build at CLI_BIN actually RUNS and reports the expected
+ * version. A bare package.json read is not proof after a failed
+ * `npm install -g`: the global replace is non-atomic (notably on Windows),
+ * so a half-written package can carry the new manifest with broken code.
+ */
+export function postInstallCliRunnable(expectedVersion, { spawn = spawnSync, execPath = process.execPath } = {}) {
+  if (typeof expectedVersion !== "string" || !expectedVersion.trim()) return false;
+  try {
+    const run = spawn(execPath, [CLI_BIN, "--version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 15_000,
+      windowsHide: true,
+    });
+    if (run.status !== 0 || run.error) return false;
+    return String(run.stdout || "").trim() === expectedVersion.trim();
+  } catch {
+    return false;
+  }
+}
+
 const HELP = brandedText(`impel update - update everything Impel in one command
 
 Reinstalls impel-cli from npm, then uses the new build to discover every
@@ -101,11 +131,67 @@ function defaultSelfUpdate(spec) {
   return installUpdateFromRegistry(spec);
 }
 
+/**
+ * After `npm install -g` exits 0 but the RUNNING CLI's own package still
+ * resolves the old version (npm-prefix skew: nvm/Homebrew node transitions,
+ * npm 11 dangling prepare-script symlinks), locate the build npm actually
+ * installed so the cascade can run under it. Fail-closed: the entry point
+ * must live inside the global root of the same `npm` the installer ran, and
+ * its package.json must resolve exactly the version npm reported for the
+ * update tag; anything else returns null and the caller keeps the hard error.
+ */
+export function resolveFreshGlobalEntrypoint(targetVersion, dependencies = {}) {
+  const io = {
+    spawnSync,
+    platform: process.platform,
+    environment: process.env,
+    readFileSync: fs.readFileSync,
+    existsSync: fs.existsSync,
+    ...dependencies,
+  };
+  if (typeof targetVersion !== "string" || !targetVersion.trim()) return null;
+  try {
+    const invocation = nativeCommandInvocation("npm", ["root", "-g"], io.environment, io.platform);
+    const run = io.spawnSync(invocation.command, invocation.args, {
+      encoding: "utf8",
+      env: io.environment,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 15_000,
+      windowsHide: true,
+      windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+    });
+    if (run.status !== 0 || run.error) return null;
+    const globalRoot = String(run.stdout || "").trim();
+    if (!globalRoot || !path.isAbsolute(globalRoot)) return null;
+    // Containment is enforced at every hop: the package directory must stay
+    // inside the npm global root (an env-supplied package name cannot
+    // traverse out), the declared bin must stay inside the package, and the
+    // real (symlink-resolved) entry point must still live under the real
+    // global root. Anything else fails closed to the caller's hard error.
+    const packageRoot = path.resolve(path.join(globalRoot, ...updatePackage().split("/")));
+    if (!packageRoot.startsWith(path.resolve(globalRoot) + path.sep)) return null;
+    const pkg = JSON.parse(io.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+    if (pkg?.version !== targetVersion) return null;
+    const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.[RUNTIME_BRAND.cli.command];
+    if (typeof bin !== "string" || !bin.trim()) return null;
+    const entrypoint = path.resolve(packageRoot, bin);
+    if (!entrypoint.startsWith(packageRoot + path.sep)) return null;
+    if (!io.existsSync(entrypoint)) return null;
+    const realEntrypoint = (io.realpathSync || fs.realpathSync)(entrypoint);
+    const realRoot = (io.realpathSync || fs.realpathSync)(globalRoot);
+    if (!realEntrypoint.startsWith(realRoot + path.sep)) return null;
+    return entrypoint;
+  } catch {
+    return null;
+  }
+}
+
 // The cascading steps re-execute the (freshly installed) CLI binary so the
 // NEW code performs them, not the process that started the update. On
 // Windows this is also what refreshes the stable %LOCALAPPDATA% entry point:
 // bin/impel.js rewrites it at startup, so the shim is only ever updated by a
-// build that the postInstallCliVersion guard below already verified.
+// build verified either by the postInstallCliVersion guard below or by
+// resolveFreshGlobalEntrypoint's fail-closed skew resolution.
 export function defaultRunConvergence({
   skipApps = false,
   skipClis = false,
@@ -113,6 +199,7 @@ export function defaultRunConvergence({
   spawn = spawnSync,
   execPath = process.execPath,
   cliBin = CLI_BIN,
+  environment = process.env,
 } = {}) {
   const args = [cliBin, "_converge"];
   if (skipApps) args.push("--skip-apps");
@@ -120,6 +207,7 @@ export function defaultRunConvergence({
   if (noRecovery) args.push("--no-recovery");
   const result = spawn(execPath, args, {
     stdio: "inherit",
+    env: { ...environment, [UPDATE_CASCADE_ENV]: "1" },
   });
   return result.status === 0;
 }
@@ -161,9 +249,12 @@ export async function cmdUpdate(argv, overrides = {}) {
     runSkillsSync: defaultRunSkillsSync,
     runAgentsSync: defaultRunAgentsSync,
     platform: process.platform,
+    environment: process.env,
     progress: withProgress,
     recoverInstall: runInstallRecovery,
     postInstallVersion: postInstallCliVersion,
+    postInstallRunnable: postInstallCliRunnable,
+    resolveFreshInstall: resolveFreshGlobalEntrypoint,
     loadConfig,
     ...overrides,
   };
@@ -225,10 +316,22 @@ export async function cmdUpdate(argv, overrides = {}) {
   }
 
   // ── CLI ────────────────────────────────────────────────────────────────
+  let cascadeEntrypoint = null;
   if (!remote) {
     console.warn("CLI: npm update check unavailable; keeping the installed build.");
   } else if (upToDate) {
     console.log("CLI: already up to date.");
+  } else if (io.environment?.[UPDATE_CASCADE_ENV] === "1") {
+    // Loop guard: a self-update must never start from inside its own
+    // fresh-build continuation, or a buggy cascade could respawn forever.
+    // Degrade rather than abort: an inherited marker (e.g. a terminal opened
+    // under a converge child) must not permanently brick `impel update` —
+    // convergence still runs; only the self-update is withheld.
+    console.warn(
+      `impel update: skipping the self-update because ${UPDATE_CASCADE_ENV} is set `
+      + "(update cascade in progress, or inherited from one). Convergence continues; "
+      + `for a self-update, unset ${UPDATE_CASCADE_ENV} or open a fresh terminal.`,
+    );
   } else {
     console.log(`CLI: installing the npm ${updateTag} build…`);
     if (!await io.progress(`Installing the npm ${updateTag} impel-cli build`, () => io.selfUpdate(installSpec))) {
@@ -240,8 +343,11 @@ export async function cmdUpdate(argv, overrides = {}) {
       const config = io.loadConfig();
       let recovered = false;
       if (config?.pat && config?.tenantId) {
-        // The goal tracks the most recent reviewed retry of the npm install:
-        // recovery may only end "fixed" once that retry actually succeeded.
+        // The goal passes on the most recent reviewed retry of the npm
+        // install OR on a live disk probe of the package that owns the
+        // running CLI: when the user completes the printed manual
+        // `npm install --global …` in another terminal mid-recovery, the goal
+        // must observe that completion instead of re-issuing the same step.
         const updateState = { ok: false };
         try {
           const recovery = await io.recoverInstall(
@@ -259,7 +365,10 @@ export async function cmdUpdate(argv, overrides = {}) {
                 {
                   id: "cli-update",
                   description: `The global ${RUNTIME_BRAND.cli.packageName} npm update completed successfully`,
-                  run: () => updateState.ok === true,
+                  run: () => updateState.ok === true
+                    || (remote != null
+                      && io.postInstallVersion() === remote
+                      && io.postInstallRunnable(remote)),
                 },
               ],
               explicit: Boolean(flags.repair),
@@ -296,19 +405,35 @@ export async function cmdUpdate(argv, overrides = {}) {
       console.log("CLI: recovery verified the update path.");
     }
     // npm exiting 0 is NOT proof the RUNNING install was updated: with multiple
-    // Node installs / npm prefixes (common on Windows), the install can land in
-    // a different global prefix while CLI_BIN — the path the cascade re-executes
-    // — still holds the old build. Cascading then runs old code that believes
-    // an update is still pending, which is how unbounded respawn storms start.
-    // Probe the version at CLI_BIN fresh from disk and refuse to cascade on skew.
+    // Node installs / npm prefixes (nvm/Homebrew node transitions on macOS,
+    // prefix skew on Windows), the install can land in a different global
+    // prefix while CLI_BIN — the path the cascade re-executes — still holds
+    // the old build. Cascading old code that believes an update is still
+    // pending is how unbounded respawn storms start, so the cascade may only
+    // ever run a build that provably resolves the target version. Probe the
+    // version at CLI_BIN fresh from disk; on skew, locate and verify the
+    // build npm actually installed and hand the continuation to THAT binary.
+    // (The previous behavior — abort with exit 1 — left the machine
+    // half-updated: CLI updated in the other prefix, no tenant/app/skills
+    // convergence, and a rerun from the same terminal repeated the abort via
+    // the shell's stale command hash. That is the field-reported "run
+    // `impel update` twice, sometimes in separate terminals".)
     const postInstall = io.postInstallVersion();
     if (remote && postInstall !== remote) {
-      console.error(`impel update: npm reported success but the running CLI still resolves v${postInstall ?? "?"} (expected v${remote}).`);
-      console.error(`  Running CLI: ${CLI_BIN}`);
-      console.error("  This usually means the `impel` on PATH belongs to a different npm prefix than `npm prefix -g`.");
-      console.error(`  Fix: run \`npm prefix -g\`, confirm it owns the \`impel\` shim on PATH, then \`npm install --global ${installSpec}\` there.`);
-      process.exitCode = 1;
-      return;
+      cascadeEntrypoint = io.resolveFreshInstall(remote);
+      if (!cascadeEntrypoint) {
+        console.error(`impel update: npm reported success but the running CLI still resolves v${postInstall ?? "?"} (expected v${remote}), and the freshly installed build could not be located and verified.`);
+        console.error(`  Running CLI: ${CLI_BIN}`);
+        console.error("  This usually means the `impel` on PATH belongs to a different npm prefix than `npm prefix -g`.");
+        console.error(`  Fix: run \`npm prefix -g\`, confirm it owns the \`impel\` shim on PATH, then \`npm install --global ${installSpec}\` there.`);
+        process.exitCode = 1;
+        return;
+      }
+      console.warn(`impel update: the running CLI at ${CLI_BIN} still resolves v${postInstall ?? "?"}; continuing with the freshly installed v${remote}.`);
+      console.warn(`  Fresh build: ${cascadeEntrypoint}`);
+      console.warn(io.platform === "win32"
+        ? "  Your current shell may still launch the old install. Open a new terminal, and align the `impel` on PATH with `npm prefix -g`."
+        : "  Your current shell may still launch the old install. Run `hash -r` (zsh/bash) or open a new terminal, and align the `impel` on PATH with `npm prefix -g`.");
     }
     console.log(`CLI: updated${remote ? ` to v${remote}` : ""}.`);
   }
@@ -318,6 +443,9 @@ export async function cmdUpdate(argv, overrides = {}) {
     skipApps: Boolean(flags["skip-apps"]),
     skipClis: Boolean(flags["skip-clis"]),
     noRecovery: Boolean(flags["no-recovery"]),
+    // On npm-prefix skew the continuation must re-exec the verified fresh
+    // build; everywhere else CLI_BIN already holds the new bytes.
+    ...(cascadeEntrypoint ? { cliBin: cascadeEntrypoint } : {}),
   };
   if (!await io.runConvergence(convergenceArgs)) {
     console.error("impel update: tenant convergence failed; rerun `impel update` after addressing the reported issue.");

package/src/installRecovery/engine.js

@@ -358,6 +358,27 @@ export async function runInstallRecovery(options, overrides = {}) {
               continue;
             }
           }
+          // A blocked report gets one live goal pass before it stands: when
+          // every health check succeeds (a skipped step, or the user
+          // finishing the work in another terminal), the machine is healthy
+          // regardless of what the model concluded — mirroring the
+          // budget-exhaustion upgrade below.
+          if (status === "blocked") {
+            goalReport = await runGoals(session.goals);
+            if (goalReport.passed) {
+              finished = {
+                status: "fixed",
+                summary: "Every goal health check passes; the reported blocker is no longer present.",
+                userAction: null,
+              };
+              toolResults.push({
+                type: "tool_result",
+                tool_use_id: call.id,
+                content: "Outcome recorded.",
+              });
+              break;
+            }
+          }
           finished = {
             status,
             summary: String(call.input?.summary || "").slice(0, 2_000),
@@ -371,6 +392,24 @@ export async function runInstallRecovery(options, overrides = {}) {
           break;
         }
 
+        // Live re-probe before any system-risk step: when every goal health
+        // check already passes, the state this step would produce is already
+        // present on the machine (typically because the user completed the
+        // instruction in another terminal mid-session). Skip the step instead
+        // of re-prompting for an installer the environment no longer needs.
+        if (installRecoveryToolRisk(call.name) === "system" && session.goals.length) {
+          const live = await runGoals(session.goals);
+          if (live.passed) {
+            io.log(`Install recovery: skipping ${call.name} — every goal health check already passes.`);
+            toolResults.push({
+              type: "tool_result",
+              tool_use_id: call.id,
+              content: "Skipped: every goal health check now passes — this step is already satisfied on this machine. Verify with check_health and finish with report_outcome.",
+            });
+            continue;
+          }
+        }
+
         const result = await executeCall(session, call.name, call.input);
         if (result.outcome === "declined" && installRecoveryToolRisk(call.name) === "system") {
           declinedSystemCalls += 1;
@@ -397,6 +436,12 @@ export async function runInstallRecovery(options, overrides = {}) {
       }
 
       if (declinedSystemCalls >= 2) {
+        // Same live upgrade as the blocked and budget paths: declining a
+        // repair the machine no longer needs must not read as a failure.
+        goalReport = await runGoals(session.goals);
+        if (goalReport.passed) {
+          return terminalReturn(session, "fixed", "The installation passes all health checks.");
+        }
         return terminalReturn(
           session,
           "aborted",

package/src/macSetup.js

@@ -7,7 +7,7 @@ import { spawnSync } from "node:child_process";
 import { ensureImpelClaudeProfile, ensureImpelCodexProfile } from "./cliProfiles.js";
 import { findNativeBinary } from "./nativeProcess.js";
 import { syncSkillsSafe } from "./skills.js";
-import { verifyReviewedMacVendorCli } from "./vendorCliBinaries.js";
+import { findReviewedVendorCliBinary, verifyReviewedMacVendorCli } from "./vendorCliBinaries.js";
 import { PINNED_VENDOR_CLI_VERSIONS } from "./vendorCliVersions.js";
 
 const MAX_INSTALLER_BYTES = 512 * 1024;
@@ -49,13 +49,14 @@ export const MAC_CLI_INSTALLERS = Object.freeze({
 });
 
 function detectMacClis(find, environment, verify) {
-  const detect = (tool) => find(
-    tool,
-    environment,
-    "darwin",
-    "IMPEL",
-    (binary) => verify(tool, binary, environment),
-  );
+  // Detection must share the launcher's reviewed resolution (including the
+  // side-by-side fallback after vendor auto-update drift); a raw PATH probe
+  // here would classify a drifted-but-launchable install as missing and
+  // reinstall it on every setup/update pass.
+  const detect = (tool) => findReviewedVendorCliBinary(tool, environment, "darwin", "IMPEL", {
+    find,
+    verify,
+  });
   return { claude: detect("claude"), codex: detect("codex") };
 }
 
@@ -171,6 +172,7 @@ export async function prepareMacClis({
   gatewayUrl,
   tenantId,
   skipInstall = false,
+  inspectOnly = false,
   installTools = ["claude", "codex"],
 } = {}, dependencies = {}) {
   const io = {
@@ -193,6 +195,22 @@ export async function prepareMacClis({
   if (requested.size !== installTools.length || [...requested].some((tool) => !io.installers[tool])) {
     throw new Error("installTools must contain unique supported macOS CLI names");
   }
+  // A pure discovery probe: recovery goals and health checks re-evaluate
+  // this repeatedly, so it must never install, write profiles, or sync
+  // skills — only report what is currently discoverable.
+  if (inspectOnly) {
+    return {
+      binaries: before,
+      missingBefore,
+      missingAfter: [...missingBefore],
+      installAttempted: false,
+      installSucceeded: null,
+      installFailure: null,
+      installations: {},
+      installCommands: {},
+      profiles: null,
+    };
+  }
 
   const installations = {};
   if (missingBefore.length && !skipInstall) {