impel-cli 0.17.1 → 0.17.3

package/README.md

@@ -56,7 +56,7 @@ Useful setup options:
 ```sh
 impel setup --pat <pat>       # non-interactive credential input
 impel setup --skip-apps       # prepare CLI profiles only
-impel setup --skip-clis       # Windows: do not install missing vendor CLIs
+impel setup --skip-clis       # do not install missing vendor CLIs
 impel setup --no-recovery     # disable local and assisted recovery for this run
 ```
 
@@ -133,6 +133,7 @@ Useful update options:
 ```sh
 impel update --check          # inspect npm availability without changing state
 impel update --skip-apps      # reconcile CLI profiles only
+impel update --skip-clis      # do not install missing vendor CLIs
 impel update --no-recovery    # disable recovery for this run
 ```
 
@@ -231,6 +232,8 @@ compatibility for one release, but no command can enable native routing.
 
 ### macOS
 
+- Missing Claude Code and Codex CLIs can be installed for the signed-in user
+  through the vendors' checksum-verifying native installers after confirmation.
 - Tenant apps live in `~/Applications`.
 - LaunchServices registration is non-launching and idempotent.
 - Existing bundle fingerprints and stable signing identity prevent unnecessary
@@ -308,3 +311,18 @@ run a real package manager, or modify native personal profiles.
 
 CI runs on Ubuntu, macOS, and Windows with supported Node versions. See
 [RELEASING.md](RELEASING.md) for the npm release process.
+
+The macOS config-contract job downloads the exact ChatGPT archive declared in
+`PINNED_VENDOR_APPS`, verifies its checksum, signature, app version, and
+embedded Codex version, then validates a deterministic generated profile with
+Codex's strict config loader. A ChatGPT pin update must also update the embedded
+Codex version and the reviewed config fixture when its contract changes.
+
+The pinned Claude contract job likewise force-downloads the exact desktop app,
+verifies the embedded Claude Code release manifest, builds the managed bundle
+with ad-hoc signing, and checks deterministic generated desktop and Claude Code
+settings against a reviewed fixture. The manifest-selected Claude Code runtime
+runs `doctor` in bare mode against an isolated profile; CI intercepts the
+`security` command so the check cannot read, reset, unlock, or modify a
+Keychain. A Claude pin update must also update its `claudeCodeVersion` and
+`claudeCodeCommit` pins and reviewed contract fixture.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.17.1",
+  "version": "0.17.3",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {

package/src/apps.js

@@ -43,6 +43,8 @@ const APP_DEFINITIONS = {
 export const PINNED_VENDOR_APPS = Object.freeze({
   claude: Object.freeze({
     version: "1.20186.9",
+    claudeCodeVersion: "2.1.209",
+    claudeCodeCommit: "0fe048596fd45e79e99353cbe2c3d1b1ac069568",
     bundleName: "Claude.app",
     downloads: Object.freeze({
       arm64: Object.freeze({
@@ -57,6 +59,7 @@ export const PINNED_VENDOR_APPS = Object.freeze({
   }),
   chatgpt: Object.freeze({
     version: "26.707.72221",
+    codexVersion: "0.144.2",
     bundleName: "ChatGPT.app",
     downloads: Object.freeze({
       arm64: Object.freeze({
@@ -589,6 +592,7 @@ export function installManagedAppFiles({
   writeTokenHelperFile = true,
   claudeUserData = null,
   chatgptInvocations = null,
+  generatedAt = new Date().toISOString(),
 }) {
   // true = rebuild every target's bundle; false = configs only; an array
   // limits the expensive rebuild to just the stale targets.
@@ -621,7 +625,14 @@ export function installManagedAppFiles({
       ensureClaudeSessionHooks(paths.claude.userData, config.tenantId, "claude_desktop");
     }
     else {
-      writeChatGPTConfig(paths, config, models, vendorCodexModels, chatgptInvocations);
+      writeChatGPTConfig(
+        paths,
+        config,
+        models,
+        vendorCodexModels,
+        chatgptInvocations,
+        generatedAt,
+      );
       ensureCodexSessionHooks(paths.chatgpt.codexHome, config.tenantId, "codex_desktop");
     }
     // Non-bundle targets are the background-refresh / fast-open path: configs,
@@ -666,7 +677,7 @@ export function installManagedAppFiles({
       config,
     ),
     models: models.map((model) => model.id),
-    updatedAt: new Date().toISOString(),
+    updatedAt: generatedAt,
   }, null, 2) + "\n", 0o600);
   return installed;
 }
@@ -815,10 +826,13 @@ function installPinnedVendorApp(target, homeDir) {
   }
 }
 
-export function ensureVendorApp(target, { homeDir = os.homedir() } = {}) {
+export function ensureVendorApp(target, {
+  homeDir = os.homedir(),
+  forceDownload = false,
+} = {}) {
   const definition = APP_DEFINITIONS[target];
   const pin = PINNED_VENDOR_APPS[target];
-  const current = findVendorApp(target, homeDir);
+  const current = forceDownload ? null : findVendorApp(target, homeDir);
   if (current) return { path: current, action: "existing", note: `verified ${pin.version}` };
 
   // Name-collision transparency: e.g. OpenAI's native ChatGPT chat app
@@ -974,7 +988,14 @@ function writeClaudeDefaultApp(paths) {
   writeAtomic(configPath, JSON.stringify(next, null, 2) + "\n", 0o600);
 }
 
-function writeChatGPTConfig(paths, config, models, vendorCodexModels, invocations = null) {
+function writeChatGPTConfig(
+  paths,
+  config,
+  models,
+  vendorCodexModels,
+  invocations = null,
+  generatedAt = new Date().toISOString(),
+) {
   const experimental = crossAppModelsEnabled(config);
   const orderedModels = experimental
     ? [...models.filter((model) => model.provider === "codex"), ...models.filter((model) => model.provider === "claude")]
@@ -1008,7 +1029,7 @@ function writeChatGPTConfig(paths, config, models, vendorCodexModels, invocation
     ? configuredTier
     : (configuredTier === "fast" && supportedTiers.includes("priority") ? "priority" : null);
   const catalog = {
-    fetched_at: new Date().toISOString(),
+    fetched_at: generatedAt,
     client_version: "impel-managed-2",
     models: codexModels,
   };
@@ -1209,18 +1230,27 @@ function codexCatalogEntry(model, index, vendorModel) {
 function readVendorCodexModels(vendorPath) {
   const binary = vendorPath && path.join(vendorPath, "Contents", "Resources", "codex");
   if (!binary || !fs.existsSync(binary)) return new Map();
-  const env = { ...process.env };
-  delete env.CODEX_HOME;
-  for (const args of [["debug", "models"], ["debug", "models", "--bundled"]]) {
-    const result = spawnSync(binary, args, { encoding: "utf8", env, maxBuffer: 20 * 1024 * 1024 });
-    if (result.status !== 0) continue;
+  const codexHome = fs.mkdtempSync(path.join(os.tmpdir(), "impel-vendor-codex-models-"));
+  try {
+    // Vendor enrichment must come only from the exact bundled release. Reading
+    // the operator's native CODEX_HOME here would make generated app configs
+    // depend on unrelated local state and could trigger an online catalog read.
+    const env = { ...process.env, CODEX_HOME: codexHome };
+    const result = spawnSync(binary, ["debug", "models", "--bundled"], {
+      encoding: "utf8",
+      env,
+      maxBuffer: 20 * 1024 * 1024,
+    });
+    if (result.status !== 0) return new Map();
     try {
       const payload = JSON.parse(result.stdout);
       const models = Array.isArray(payload) ? payload : payload.models;
       if (Array.isArray(models)) return new Map(models.map((model) => [model.slug, model]));
     } catch {
-      // Fall through to the bundled catalog or the Impel-generated schema.
+      // Fall through to the Impel-generated schema.
     }
+  } finally {
+    fs.rmSync(codexHome, { recursive: true, force: true });
   }
   return new Map();
 }
@@ -1373,11 +1403,13 @@ function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl, safeStorageNam
     });
 
     const macos = path.join(staging, "Contents", "MacOS");
+    const vendorExecutable = path.join(macos, executableName);
+    const signingIdentity = resolveVendoredAppSigningIdentity(vendorExecutable);
     writeAtomic(path.join(staging, "Contents", "Resources", "impel-compatibility.json"), JSON.stringify({
       schemaVersion: 4,
       cliVersion: CLI_VERSION,
       bundleFingerprint: BUNDLE_BUILD_FINGERPRINT,
-      signingMode: desiredSigningMode(),
+      signingMode: signingModeForIdentity(signingIdentity),
       vendorVersion: bundleVersion(vendorPath),
       sourceBundle: vendorPath,
       bundleIdentifier: paths.claude.bundleIdentifier,
@@ -1403,7 +1435,7 @@ function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl, safeStorageNam
       asarHeaderSha256: newAsarHash,
     }, null, 2) + "\n", 0o644);
 
-    signVendoredApp(staging, path.join(macos, executableName), "Claude");
+    signVendoredApp(staging, vendorExecutable, "Claude", signingIdentity);
     replaceDirectory(bundle, staging);
   } catch (error) {
     fs.rmSync(staging, { recursive: true, force: true });
@@ -1456,6 +1488,8 @@ function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl) {
     const runtimeAsarPath = path.join(staging, "Contents", "Resources", "app.asar");
     const fastModePatchCount = patchFastModeAuthGate(runtimeAsarPath);
     const asarHash = asarHeaderHash(runtimeAsarPath);
+    const vendorExecutable = path.join(vendorBundle, "Contents", "MacOS", executableName);
+    const signingIdentity = resolveVendoredAppSigningIdentity(vendorExecutable);
     const launchHost = ensureChatGPTLaunchHost();
     writeAtomic(
       path.join(staging, "Contents", "Info.plist"),
@@ -1487,7 +1521,7 @@ function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl) {
       schemaVersion: 3,
       cliVersion: CLI_VERSION,
       bundleFingerprint: BUNDLE_BUILD_FINGERPRINT,
-      signingMode: desiredSigningMode(),
+      signingMode: signingModeForIdentity(signingIdentity),
       vendorVersion: bundleVersion(vendorPath),
       sourceBundle: vendorPath,
       bundleIdentifier: paths.chatgpt.bundleIdentifier,
@@ -1505,7 +1539,7 @@ function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl) {
       asarHeaderSha256: asarHash,
     }, null, 2) + "\n", 0o644);
 
-    signVendoredApp(staging, path.join(vendorBundle, "Contents", "MacOS", executableName), "ChatGPT");
+    signVendoredApp(staging, vendorExecutable, "ChatGPT", signingIdentity);
     replaceDirectory(bundle, staging);
   } catch (error) {
     fs.rmSync(staging, { recursive: true, force: true });
@@ -2131,6 +2165,16 @@ if (process.type === "browser" && displayName) {
 `;
 }
 
+function resolveVendoredAppSigningIdentity(vendorExecutable) {
+  if (process.platform !== "darwin" || !isMachO(vendorExecutable)) return null;
+  return resolveSigningIdentity();
+}
+
+export function signingModeForIdentity(identity) {
+  if (!identity) return desiredSigningMode();
+  return identity.mode === "external" ? identity.descriptor : identity.mode;
+}
+
 function signVendoredApp(bundle, vendorExecutable, label, identity = null) {
   if (process.platform !== "darwin" || !isMachO(vendorExecutable)) return;
   // Resolve (and, on first use, create) the signing identity only once we know

package/src/cli.js

@@ -19,6 +19,7 @@ import { cmdSessions } from "./commands/sessions.js";
 import { cmdUpdate } from "./commands/update.js";
 import { cmdExperimental } from "./commands/experimental.js";
 import { cmdConverge } from "./commands/converge.js";
+import { refuseElevatedMacExecution } from "./privileges.js";
 
 const HELP = `impel — isolated Impel workspaces for every tenant
 
@@ -75,6 +76,7 @@ function normalizeTarget(token) {
 }
 
 export async function main(argv) {
+  if (refuseElevatedMacExecution(argv)) return;
   const [cmd, ...rest] = argv;
 
   switch (cmd) {

package/src/codesign.js

@@ -117,7 +117,10 @@ export function resolveSigningIdentity(deps = {}) {
   }
 
   try {
-    const identity = ensureLocalSigningIdentity({ run, configDir, fsImpl, randomBytes });
+    const identity = withSigningIdentityLock(
+      { configDir, fsImpl },
+      () => ensureLocalSigningIdentity({ run, configDir, fsImpl, randomBytes }),
+    );
     if (cache) cachedIdentity = identity;
     return identity;
   } catch (error) {
@@ -142,25 +145,33 @@ function ensureLocalSigningIdentity({ run, configDir, fsImpl, randomBytes }) {
   // therefore the designated requirement) stays stable across updates.
   if (fsImpl.existsSync(keychain) && fsImpl.existsSync(passwordFile)) {
     const password = fsImpl.readFileSync(passwordFile, "utf8").trim();
-    unlockKeychain(run, keychain, password);
-    ensureKeychainInSearchList(run, keychain);
-    const existing = findLocalIdentitySha(run, keychain);
-    if (existing) return localIdentity(existing, keychain);
-
-    // v0.13.0 imported a self-signed certificate but never established code-
-    // signing trust for it. `security find-identity -v` therefore reported
-    // zero valid identities and every rebuild fell back to ad-hoc signing.
-    // Repair that exact state in place so the already-generated identity stays
-    // stable instead of accumulating a second certificate with the same name.
-    trustExistingLocalCertificate({ run, keychain, fsImpl });
-    const repaired = findLocalIdentitySha(run, keychain);
-    if (repaired) return localIdentity(repaired, keychain);
-    throw new Error("existing signing identity could not be trusted");
+    try {
+      if (!password) throw new Error("stored signing keychain password is empty");
+      unlockKeychain(run, keychain, password);
+      runOrThrow(run, "/usr/bin/security", ["set-keychain-settings", keychain], "configure signing keychain");
+      ensureKeychainInSearchList(run, keychain);
+      let existing = findLocalIdentitySha(run, keychain);
+      if (existing) return localIdentity(existing, keychain);
+
+      // Repair identities created before trust was established, plus imports
+      // interrupted after the private key reached the keychain.
+      authorizeCodesignKey(run, keychain, password);
+      trustExistingLocalCertificate({ run, keychain, fsImpl });
+      existing = findLocalIdentitySha(run, keychain);
+      if (existing) return localIdentity(existing, keychain);
+      throw new Error("existing signing identity could not be trusted");
+    } catch {
+      // This keychain and password file are entirely Impel-owned. A mismatched,
+      // empty, or half-imported pair can never provide stable identity, so reset
+      // it atomically instead of falling back forever on every future rebuild.
+      resetLocalSigningIdentity({ run, keychain, passwordFile, fsImpl });
+    }
+  } else if (fsImpl.existsSync(keychain) || fsImpl.existsSync(passwordFile)) {
+    resetLocalSigningIdentity({ run, keychain, passwordFile, fsImpl });
   }
 
   const password = randomBytes(24).toString("hex");
-  createLocalSigningIdentity({ run, dir, keychain, password, fsImpl });
-  fsImpl.writeFileSync(passwordFile, `${password}\n`, { mode: 0o600 });
+  createLocalSigningIdentity({ run, dir, keychain, passwordFile, password, fsImpl });
 
   ensureKeychainInSearchList(run, keychain);
   const sha = findLocalIdentitySha(run, keychain);
@@ -183,7 +194,7 @@ function findLocalIdentitySha(run, keychain) {
   return parseIdentitySha(result.stdout, SIGNING_IDENTITY_NAME);
 }
 
-function createLocalSigningIdentity({ run, dir, keychain, password, fsImpl }) {
+function createLocalSigningIdentity({ run, dir, keychain, passwordFile, password, fsImpl }) {
   const work = fsImpl.mkdtempSync(path.join(os.tmpdir(), "impel-codesign-"));
   const keyPath = path.join(work, "key.pem");
   const certPath = path.join(work, "cert.pem");
@@ -211,26 +222,89 @@ function createLocalSigningIdentity({ run, dir, keychain, password, fsImpl }) {
       "-name", SIGNING_IDENTITY_NAME,
     ], "package signing certificate");
 
-    if (!fsImpl.existsSync(keychain)) {
-      runOrThrow(run, "/usr/bin/security", ["create-keychain", "-p", password, keychain], "create signing keychain");
+    runOrThrow(run, "/usr/bin/security", ["create-keychain", "-p", password, keychain], "create signing keychain");
+    try {
+      writePrivateAtomic(fsImpl, passwordFile, `${password}\n`);
+    } catch (error) {
+      resetLocalSigningIdentity({ run, keychain, passwordFile, fsImpl });
+      throw error;
     }
     // No auto-lock: codesign must reach the private key non-interactively.
-    run("/usr/bin/security", ["set-keychain-settings", keychain]);
+    runOrThrow(run, "/usr/bin/security", ["set-keychain-settings", keychain], "configure signing keychain");
     unlockKeychain(run, keychain, password);
     runOrThrow(run, "/usr/bin/security", [
       "import", p12Path, "-k", keychain, "-P", p12Pass, "-T", "/usr/bin/codesign",
     ], "import signing identity");
     // Grant codesign non-interactive access to the key so signing never pops a
     // "codesign wants to use a key" GUI prompt. We own the keychain password.
-    runOrThrow(run, "/usr/bin/security", [
-      "set-key-partition-list", "-S", "apple-tool:,apple:,codesign:", "-s", "-k", password, keychain,
-    ], "authorize codesign for the signing key");
+    authorizeCodesignKey(run, keychain, password);
     trustLocalCertificate(run, keychain, certPath);
   } finally {
     fsImpl.rmSync(work, { recursive: true, force: true });
   }
 }
 
+function authorizeCodesignKey(run, keychain, password) {
+  runOrThrow(run, "/usr/bin/security", [
+    "set-key-partition-list", "-S", "apple-tool:,apple:,codesign:", "-s", "-k", password, keychain,
+  ], "authorize codesign for the signing key");
+}
+
+function writePrivateAtomic(fsImpl, filePath, contents) {
+  const temporary = `${filePath}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+  try {
+    fsImpl.writeFileSync(temporary, contents, { mode: 0o600 });
+    fsImpl.renameSync(temporary, filePath);
+    fsImpl.chmodSync?.(filePath, 0o600);
+  } finally {
+    fsImpl.rmSync(temporary, { force: true });
+  }
+}
+
+function resetLocalSigningIdentity({ run, keychain, passwordFile, fsImpl }) {
+  if (fsImpl.existsSync(keychain)) {
+    run("/usr/bin/security", ["delete-keychain", keychain]);
+  }
+  fsImpl.rmSync(keychain, { force: true });
+  fsImpl.rmSync(passwordFile, { force: true });
+}
+
+const SIGNING_LOCK_STALE_MS = 5 * 60 * 1_000;
+const SIGNING_LOCK_WAIT_MS = 15_000;
+const SIGNING_LOCK_POLL_MS = 100;
+const SIGNING_LOCK_SLEEP = new Int32Array(new SharedArrayBuffer(4));
+
+function withSigningIdentityLock({ configDir, fsImpl }, run) {
+  const dir = path.join(configDir, "codesign");
+  const lock = path.join(dir, ".identity-lock");
+  fsImpl.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const deadline = Date.now() + SIGNING_LOCK_WAIT_MS;
+  while (true) {
+    try {
+      fsImpl.mkdirSync(lock, { mode: 0o700 });
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      try {
+        if (Date.now() - fsImpl.statSync(lock).mtimeMs > SIGNING_LOCK_STALE_MS) {
+          fsImpl.rmSync(lock, { recursive: true, force: true });
+          continue;
+        }
+      } catch (statError) {
+        if (statError?.code !== "ENOENT") throw statError;
+        continue;
+      }
+      if (Date.now() >= deadline) throw new Error("timed out waiting for another Impel signing operation");
+      Atomics.wait(SIGNING_LOCK_SLEEP, 0, 0, SIGNING_LOCK_POLL_MS);
+    }
+  }
+  try {
+    return run();
+  } finally {
+    fsImpl.rmSync(lock, { recursive: true, force: true });
+  }
+}
+
 function unlockKeychain(run, keychain, password) {
   runOrThrow(
     run,

package/src/commands/apps.js

@@ -43,6 +43,7 @@ import { syncAgentProfilesSafe } from "../agents.js";
 import { secureManagedCodexHome } from "../codexSecurity.js";
 import { impelCliInvocation } from "../selfInvocation.js";
 import { createProgressLogger, withProgress } from "../progress.js";
+import { findNativeBinary } from "../nativeProcess.js";
 import {
   ensureWindowsClaudeApp,
   ensureWindowsChatGPTApp,
@@ -325,6 +326,7 @@ export async function reconcileWindowsTenantApps({
     syncSkills: syncSkillsSafe,
     syncAgents: syncAgentProfilesSafe,
     existsSync: fs.existsSync,
+    findBinary: findNativeBinary,
     log: (message) => console.log(message),
     ...overrides,
   };
@@ -375,17 +377,23 @@ export async function reconcileWindowsTenantApps({
     homeDir,
     environment,
   });
+  const agentTargets = [];
   for (const target of actionTargets) {
     const { client, env, label } = appSkillTarget(target, paths);
-    await io.syncSkills({ client, gatewayUrl: resolveSkillsGateway(config.gatewayUrl), env, label });
+    if (io.findBinary(client, environment, "win32")) {
+      await io.syncSkills({ client, gatewayUrl: resolveSkillsGateway(config.gatewayUrl), env, label });
+      agentTargets.push(target);
+    }
     if (target === "chatgpt") secureManagedCodexHome(paths.chatgpt.codexHome);
   }
-  await io.syncAgents({
-    profiles: actionTargets.map((target) => appAgentProfile(target, paths)),
-    gatewayUrl: config.gatewayUrl,
-    credential: config.pat,
-    tenantId: config.tenantId,
-  });
+  if (agentTargets.length) {
+    await io.syncAgents({
+      profiles: agentTargets.map((target) => appAgentProfile(target, paths)),
+      gatewayUrl: config.gatewayUrl,
+      credential: config.pat,
+      tenantId: config.tenantId,
+    });
+  }
   const verification = {
     claude: !actionTargets.includes("claude") || io.existsSync(path.join(paths.claude.userData, "configLibrary", `${CLAUDE_CONFIG_ID}.json`)),
     chatgpt: !actionTargets.includes("chatgpt") || io.existsSync(path.join(paths.chatgpt.codexHome, "config.toml")),
@@ -404,6 +412,7 @@ export async function reconcileMacTenantApps({
   skipVendorTargets = [],
   confirmVendorInstall = async () => true,
   homeDir = os.homedir(),
+  environment = process.env,
 } = {}, overrides = {}) {
   const io = {
     status: appStatus,
@@ -417,6 +426,7 @@ export async function reconcileMacTenantApps({
     secureCodexHome: secureManagedCodexHome,
     openLauncher: openManagedLauncher,
     existsSync: fs.existsSync,
+    findBinary: findNativeBinary,
     log: (message) => console.log(message),
     ...overrides,
   };
@@ -462,17 +472,23 @@ export async function reconcileMacTenantApps({
     writeBundles: staleTargets,
   });
   const paths = appPaths(homeDir, config.tenantId, { tenantName: config.tenantName });
+  const agentItems = [];
   for (const item of installed) {
     const { client, env, label } = appSkillTarget(item.target, paths);
-    await io.syncSkills({ client, gatewayUrl: resolveSkillsGateway(config.gatewayUrl), env, label });
+    if (io.findBinary(client, environment, "darwin")) {
+      await io.syncSkills({ client, gatewayUrl: resolveSkillsGateway(config.gatewayUrl), env, label });
+      agentItems.push(item);
+    }
     if (item.target === "chatgpt") io.secureCodexHome(paths.chatgpt.codexHome);
   }
-  await io.syncAgents({
-    profiles: installed.map((item) => appAgentProfile(item.target, paths)),
-    gatewayUrl: config.gatewayUrl,
-    credential: config.pat,
-    tenantId: config.tenantId,
-  });
+  if (agentItems.length) {
+    await io.syncAgents({
+      profiles: agentItems.map((item) => appAgentProfile(item.target, paths)),
+      gatewayUrl: config.gatewayUrl,
+      credential: config.pat,
+      tenantId: config.tenantId,
+    });
+  }
   for (const item of installed) {
     if (reopenTargets.has(item.target)) io.openLauncher(item.launcher);
   }

package/src/commands/converge.js

@@ -5,6 +5,7 @@ import { runInstallRecovery } from "../installRecovery/engine.js";
 import { printReconciliationSummary, reconcileAllTenants, selectDefaultTenant } from "../provisioning.js";
 import { fetchTenants } from "../tenants.js";
 import { promptText } from "../prompt.js";
+import { describeCliFailure, preparePlatformClis } from "../platformSetup.js";
 import { restoreNativeProfiles } from "./use.js";
 
 function confirmed(answer) {
@@ -24,6 +25,7 @@ function mergeTenantReport(report, replacement) {
 
 export async function cmdConverge(argv = [], overrides = {}) {
   const skipApps = argv.includes("--skip-apps");
+  const skipClis = argv.includes("--skip-clis");
   const noRecovery = argv.includes("--no-recovery");
   const io = {
     loadConfig,
@@ -36,8 +38,12 @@ export async function cmdConverge(argv = [], overrides = {}) {
     isTTY: process.stdin.isTTY,
     platform: process.platform,
     environment: process.env,
+    preparePlatformClis,
     ...overrides,
   };
+  if (overrides.prepareWindowsClis && !overrides.preparePlatformClis) {
+    io.preparePlatformClis = overrides.prepareWindowsClis;
+  }
   const config = io.loadConfig();
   if (!config?.pat) {
     console.error("impel update: not authenticated; run `impel setup` first.");
@@ -93,8 +99,94 @@ export async function cmdConverge(argv = [], overrides = {}) {
     environment: io.environment,
     confirmVendorInstall: confirmInstall,
   }, overrides.reconcileOverrides || {});
+
+  let sharedFailure = null;
+  const prepareSharedClis = async ({ confirmedTools = null, inspectOnly = false } = {}) => {
+    try {
+      const inspected = await io.preparePlatformClis({
+        gatewayUrl: config.gatewayUrl,
+        tenantId: selected.id,
+        platform: io.platform,
+        skipInstall: true,
+      });
+      let prepared = inspected;
+      if (inspected.missingAfter.length && !inspectOnly && !skipClis) {
+        let installTools = confirmedTools;
+        if (installTools === null) {
+          installTools = [];
+          if (io.isTTY) {
+            for (const tool of inspected.missingAfter) {
+              if (!inspected.installCommands?.[tool]) continue;
+              const label = tool === "claude" ? "Claude Code" : "Codex";
+              if (confirmed(await io.promptText(`Install the official ${label} CLI for this user? [y/N] `))) {
+                installTools.push(tool);
+              }
+            }
+          }
+        }
+        if (installTools.length) {
+          prepared = await io.preparePlatformClis({
+            gatewayUrl: config.gatewayUrl,
+            tenantId: selected.id,
+            platform: io.platform,
+            skipInstall: false,
+            installTools,
+          });
+        }
+      }
+      sharedFailure = prepared.missingAfter.length ? describeCliFailure(prepared) : null;
+      return prepared;
+    } catch (error) {
+      sharedFailure = redactSecretText(error?.message || error);
+      return { binaries: {}, missingAfter: ["claude", "codex"] };
+    }
+  };
+
+  await prepareSharedClis();
   let report = await run();
-  if (!report.passed && !noRecovery) {
+  if (sharedFailure && !noRecovery) {
+    let sharedReady = false;
+    const recovery = await io.recoverInstall({
+      failure: {
+        scope: "shared",
+        platform: io.platform,
+        architecture: process.arch,
+        step: "update.shared_vendor_clis",
+        message: sharedFailure,
+      },
+      config,
+      goals: [{
+        id: "shared-vendor-clis-ready",
+        description: "Shared vendor CLI prerequisites are installed and discoverable",
+        run: () => sharedReady,
+      }],
+      explicit: true,
+      noRecovery: false,
+      actionContext: {
+        tenantId: selected.id,
+        installVendorClis: async (tool) => {
+          await prepareSharedClis({ confirmedTools: [tool] });
+          sharedReady = !sharedFailure;
+          return io.preparePlatformClis({
+            gatewayUrl: config.gatewayUrl,
+            tenantId: selected.id,
+            platform: io.platform,
+            skipInstall: true,
+          });
+        },
+        retryStep: async () => {
+          await prepareSharedClis({ inspectOnly: true });
+          sharedReady = !sharedFailure;
+          return sharedReady;
+        },
+      },
+    }, overrides.recoveryOverrides || {});
+    if (recovery.fixed) {
+      await prepareSharedClis({ inspectOnly: true });
+      report = await run();
+    }
+  }
+  if (!sharedFailure && !report.passed && !noRecovery) {
     for (const failed of report.tenants.filter((tenant) => tenant.status === "failed")) {
       const tenant = listing.tenants.find((candidate) => candidate.id === failed.tenantId);
       if (!tenant) continue;
@@ -165,7 +257,8 @@ export async function cmdConverge(argv = [], overrides = {}) {
   }
   printReconciliationSummary(report);
   console.log(`CLI tenant: ${selected.id} (change with \`impel tenant use <tenant>\`)`);
-  if (!report.passed) {
+  if (!report.passed || sharedFailure) {
+    if (sharedFailure) console.error(`Shared update failure: ${sharedFailure}`);
     console.error("impel update: one or more tenant surfaces remain incomplete.");
     process.exitCode = 1;
     return false;