impel-cli 0.17.0 → 0.17.2

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

package/package.json

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

package/src/apps.js

@@ -1373,11 +1373,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 +1405,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 +1458,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 +1491,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 +1509,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 +2135,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,
@@ -180,6 +181,21 @@ export function installedAppTenantIds(targets, {
   return installed.sort((left, right) => left.localeCompare(right));
 }
 
+async function maybeRunLegacyUpdateHandoff(argv, overrides) {
+  if (overrides.singleTenantUpdate) return null;
+  const [action, target, ...rest] = argv;
+  if (action !== "update" || target !== "all" || rest.length > 0) return null;
+
+  // impel-cli <=0.16.5 re-executes a newly installed build with this exact
+  // command. Route that cross-version handoff through the current full-tenant
+  // reconciler so first-time tenant targets are not limited to local installs.
+  const runConvergence = overrides.runAllTenantConvergence || (async () => {
+    const { cmdConverge } = await import("./converge.js");
+    return cmdConverge([]);
+  });
+  return runConvergence();
+}
+
 async function maybeUpdateAllInstalledTenants(argv, overrides, platform) {
   if (overrides.singleTenantUpdate) return null;
   const [action = "status", rawTarget, ...rest] = argv;
@@ -310,6 +326,7 @@ export async function reconcileWindowsTenantApps({
     syncSkills: syncSkillsSafe,
     syncAgents: syncAgentProfilesSafe,
     existsSync: fs.existsSync,
+    findBinary: findNativeBinary,
     log: (message) => console.log(message),
     ...overrides,
   };
@@ -360,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")),
@@ -389,6 +412,7 @@ export async function reconcileMacTenantApps({
   skipVendorTargets = [],
   confirmVendorInstall = async () => true,
   homeDir = os.homedir(),
+  environment = process.env,
 } = {}, overrides = {}) {
   const io = {
     status: appStatus,
@@ -402,6 +426,7 @@ export async function reconcileMacTenantApps({
     secureCodexHome: secureManagedCodexHome,
     openLauncher: openManagedLauncher,
     existsSync: fs.existsSync,
+    findBinary: findNativeBinary,
     log: (message) => console.log(message),
     ...overrides,
   };
@@ -447,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);
   }
@@ -712,6 +743,8 @@ export async function cmdWindowsApps(argv, overrides = {}) {
 
 export async function cmdApps(argv, overrides = {}) {
   const platform = overrides.platform || process.platform;
+  const legacyUpdateHandoff = await maybeRunLegacyUpdateHandoff(argv, overrides);
+  if (legacyUpdateHandoff !== null) return legacyUpdateHandoff;
   const allTenantUpdate = await maybeUpdateAllInstalledTenants(argv, overrides, platform);
   if (allTenantUpdate !== null) return allTenantUpdate;
   if (platform === "win32") return cmdWindowsApps(argv, overrides);

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;

package/src/commands/setup.js

@@ -17,7 +17,7 @@ import {
   reconcileAllTenants,
   selectDefaultTenant,
 } from "../provisioning.js";
-import { prepareWindowsClis } from "../windowsSetup.js";
+import { describeCliFailure, preparePlatformClis } from "../platformSetup.js";
 import { runInstallRecovery } from "../installRecovery/engine.js";
 import { restoreNativeProfiles } from "./use.js";
 
@@ -33,7 +33,7 @@ Usage:
   impel setup --pat <pat>           Non-interactive authentication
   impel setup --tenant <org>        Choose the default tenant for CLI launches
   impel setup --skip-apps           Skip desktop apps
-  impel setup --skip-clis           Windows: skip missing vendor CLI installation
+  impel setup --skip-clis           Do not install missing vendor CLIs
   impel setup --no-recovery         Disable automatic install recovery
 `;
 
@@ -53,16 +53,19 @@ async function probeGateway(gatewayUrl, pat, tenantId, fetchImpl = fetch) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), 5_000);
   try {
-    const response = await fetchImpl(`${gatewayUrl}/anthropic/v1/messages`, {
-      method: "POST",
+    const response = await fetchImpl(`${gatewayUrl}/v1/models`, {
       headers: {
-        "content-type": "application/json",
+        accept: "application/json",
         authorization: `Bearer ${tenantCredential(pat, tenantId)}`,
       },
-      body: "{}",
       signal: controller.signal,
     });
-    return { reachable: true, status: response.status, rejected: [401, 403].includes(response.status) };
+    return {
+      reachable: true,
+      healthy: response.ok,
+      status: response.status,
+      rejected: [401, 403].includes(response.status),
+    };
   } catch (error) {
     return {
       reachable: false,
@@ -75,7 +78,7 @@ async function probeGateway(gatewayUrl, pat, tenantId, fetchImpl = fetch) {
 
 function markProbeFailures(report, probes) {
   probes.forEach((probe, index) => {
-    if (probe.reachable && !probe.rejected) return;
+    if (probe.reachable && !probe.rejected && probe.healthy !== false) return;
     const tenant = report.tenants[index];
     tenant.cli = "failed";
     tenant.status = "failed";
@@ -84,7 +87,9 @@ function markProbeFailures(report, probes) {
     }
     tenant.errors.push(probe.rejected
       ? `credential rejected (HTTP ${probe.status})`
-      : `gateway unreachable (${probe.error || "unknown error"})`);
+      : probe.reachable
+        ? `gateway readiness failed (HTTP ${probe.status})`
+        : `gateway unreachable (${probe.error || "unknown error"})`);
   });
   report.passed = report.tenants.every((tenant) => (
     ["ready", "unavailable"].includes(tenant.cli)
@@ -109,20 +114,6 @@ function mergeTenantReport(report, replacement) {
   return recomputeReport(report);
 }
 
-function describeWindowsCliFailure(prepared) {
-  const labels = { claude: "Claude Code", codex: "Codex" };
-  const details = [];
-  for (const tool of prepared.missingAfter || []) {
-    const installation = prepared.installations?.[tool];
-    const failure = installation?.failure;
-    const reason = failure?.message || failure?.code
-      || (Number.isInteger(failure?.status) ? `exit ${failure.status}` : "not discoverable after installation");
-    details.push(`${labels[tool] || tool}'s native installer failed: ${redactSecretText(reason)}`);
-    if (installation?.command) details.push(`manual ${tool} installer: ${redactSecretText(installation.command)}`);
-  }
-  return details.join("; ") || `missing vendor CLIs: ${(prepared.missingAfter || []).join(", ")}`;
-}
-
 function confirmed(answer) {
   return /^(?:y|yes)$/iu.test(String(answer || "").trim());
 }
@@ -134,7 +125,7 @@ export async function cmdSetup(argv, overrides = {}) {
     promptSecret,
     promptText,
     fetchTenants,
-    prepareWindowsClis,
+    preparePlatformClis,
     reconcile: reconcileAllTenants,
     probe: probeGateway,
     recoverInstall: runInstallRecovery,
@@ -144,6 +135,9 @@ export async function cmdSetup(argv, overrides = {}) {
     environment: process.env,
     ...overrides,
   };
+  if (overrides.prepareWindowsClis && !overrides.preparePlatformClis) {
+    io.preparePlatformClis = overrides.prepareWindowsClis;
+  }
   const { flags, positionals } = parseFlags(argv, {
     pat: { type: "string" },
     tenant: { type: "string" },
@@ -234,11 +228,11 @@ export async function cmdSetup(argv, overrides = {}) {
 
   let sharedFailure = null;
   const prepareSharedClis = async ({ confirmedTools = null, inspectOnly = false } = {}) => {
-    if (io.platform !== "win32") return { binaries: {}, missingAfter: [] };
     try {
-      const inspected = await io.prepareWindowsClis({
+      const inspected = await io.preparePlatformClis({
         gatewayUrl,
         tenantId: selected.id,
+        platform: io.platform,
         skipInstall: true,
       });
       let prepared = inspected;
@@ -248,6 +242,7 @@ export async function cmdSetup(argv, overrides = {}) {
           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);
@@ -256,16 +251,17 @@ export async function cmdSetup(argv, overrides = {}) {
           }
         }
         if (installTools.length) {
-          prepared = await io.prepareWindowsClis({
+          prepared = await io.preparePlatformClis({
             gatewayUrl,
             tenantId: selected.id,
+            platform: io.platform,
             skipInstall: false,
             installTools,
           });
         }
       }
       if (prepared.missingAfter.length) {
-        sharedFailure = describeWindowsCliFailure(prepared);
+        sharedFailure = describeCliFailure(prepared);
         return prepared;
       }
       sharedFailure = null;
@@ -344,10 +340,13 @@ export async function cmdSetup(argv, overrides = {}) {
         },
       },
     }, overrides.recoveryOverrides || {});
-    if (recovery.fixed) await prepareSharedClis({ inspectOnly: true });
+    if (recovery.fixed) {
+      await prepareSharedClis({ inspectOnly: true });
+      report = await verifyConvergence();
+    }
   }
 
-  if (!flags["no-recovery"]) {
+  if (!sharedFailure && !flags["no-recovery"]) {
     for (const failed of report.tenants.filter((tenant) => tenant.status === "failed")) {
       const tenant = orderedTenants.find((candidate) => candidate.id === failed.tenantId);
       if (!tenant) continue;

package/src/commands/update.js

@@ -30,6 +30,7 @@ Usage:
   impel update              Update the CLI and reconcile every accessible tenant
   impel update --check      Report whether an update is available; change nothing
   impel update --skip-apps  Reconcile only isolated CLI profiles
+  impel update --skip-clis  Do not install missing vendor CLIs
   impel update --no-recovery  Disable local and hosted recovery for this run
 `;
 
@@ -85,6 +86,7 @@ function defaultSelfUpdate(spec) {
 // NEW code performs them, not the process that started the update.
 export function defaultRunConvergence({
   skipApps = false,
+  skipClis = false,
   noRecovery = false,
   spawn = spawnSync,
   execPath = process.execPath,
@@ -92,6 +94,7 @@ export function defaultRunConvergence({
 } = {}) {
   const args = [cliBin, "_converge"];
   if (skipApps) args.push("--skip-apps");
+  if (skipClis) args.push("--skip-clis");
   if (noRecovery) args.push("--no-recovery");
   const result = spawn(execPath, args, {
     stdio: "inherit",
@@ -157,6 +160,7 @@ export async function cmdUpdate(argv, overrides = {}) {
   const { flags } = parseFlags(argv, {
     check: { type: "boolean" },
     "skip-apps": { type: "boolean" },
+    "skip-clis": { type: "boolean" },
     "refresh-cache": { type: "boolean" },
     repair: { type: "boolean" },
     "no-recovery": { type: "boolean" },
@@ -263,6 +267,7 @@ export async function cmdUpdate(argv, overrides = {}) {
   console.log("Tenants: discovering, installing, repairing, and upgrading every accessible tenant…");
   const convergenceArgs = {
     skipApps: Boolean(flags["skip-apps"]),
+    skipClis: Boolean(flags["skip-clis"]),
     noRecovery: Boolean(flags["no-recovery"]),
   };
   if (!await io.runConvergence(convergenceArgs)) {

package/src/installRecovery/engine.js

@@ -174,6 +174,7 @@ function announceUpload(session, failure) {
   );
   session.io.log("Sanitized payload preview:");
   session.io.log(JSON.stringify(failure, null, 2));
+  session.io.log(`Install recovery ID: ${session.fingerprint.slice(0, 16)}`);
 }
 
 function terminalReturn(session, status, summary, extras = {}) {
@@ -280,6 +281,8 @@ export async function runInstallRecovery(options, overrides = {}) {
   let inference;
   try {
     const seat = await io.resolveSeat(options.config);
+    seat.recoveryId = session.fingerprint.slice(0, 16);
+    seat.cliVersion = CLI_VERSION;
     inference = io.createInference(seat);
     io.log(`Install recovery: assisted diagnosis via ${inference.model} (org ${inference.orgId}).`);
   } catch (error) {
@@ -293,7 +296,7 @@ export async function runInstallRecovery(options, overrides = {}) {
   const messages = [
     { role: "user", content: buildFirstUserMessage(session, failure, deterministicSummary, goalReport) },
   ];
-  const tools = installRecoveryToolDefinitions();
+  const tools = installRecoveryToolDefinitions(session.actionContext);
   const deadline = io.now() + RECOVERY_LIMITS.maxWallClockMs;
   const callCounts = new Map();
   let declinedSystemCalls = 0;

package/src/installRecovery/inference.js

@@ -107,6 +107,7 @@ export function createRecoveryInference(seat, fetchImpl = fetch) {
   const modelCandidates = [seat.model, ...FALLBACK_MODELS.filter((model) => model !== seat.model)];
 
   async function completeOnce(model, { system, messages, tools }) {
+    const requestId = `impel-recovery-${seat.recoveryId || "untracked"}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
     return requestJson(
       url,
       {
@@ -116,7 +117,8 @@ export function createRecoveryInference(seat, fetchImpl = fetch) {
           accept: "application/json",
           authorization: `Bearer ${seat.bearer}`,
           "anthropic-version": "2023-06-01",
-          "x-request-id": `impel-recovery-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+          "user-agent": `impel-cli-install-recovery/${seat.cliVersion || "unknown"} recovery/${seat.recoveryId || "untracked"}`,
+          "x-request-id": requestId,
         },
         body: JSON.stringify({
           model,

package/src/installRecovery/tools.js

@@ -105,7 +105,7 @@ export const INSTALL_RECOVERY_TOOLS = Object.freeze({
   install_vendor_cli: {
     risk: "system",
     description:
-      "Run the official vendor installer for one missing CLI (Windows only). Uses the vendor's checksum-verifying native installer; requires the user's confirmation.",
+      "Run the official vendor installer for one missing CLI on macOS or Windows. Uses a checksum-verifying native installer and requires the user's confirmation.",
     schema: {
       tool: { type: "string", enum: ["claude", "codex"], required: true },
     },
@@ -138,8 +138,26 @@ export const INSTALL_RECOVERY_TOOLS = Object.freeze({
   },
 });
 
-export function installRecoveryToolDefinitions() {
-  return Object.entries(INSTALL_RECOVERY_TOOLS).map(([name, tool]) => ({
+function recoveryToolAvailable(name, context) {
+  if (!context) return true;
+  switch (name) {
+    case "probe_gateway": return typeof context.probeGateway === "function";
+    case "check_auth_helper": return Boolean(context.tenantId) && context.platform !== "win32";
+    case "repair_impel_profile": return typeof context.repairProfiles === "function";
+    case "retry_step": return typeof context.retryStep === "function";
+    case "install_vendor_cli":
+      return ["darwin", "win32"].includes(context.platform)
+        && typeof context.installVendorClis === "function";
+    case "install_vendor_app": return typeof context.installVendorApp === "function";
+    case "repair_user_path": return context.platform === "win32";
+    default: return true;
+  }
+}
+
+export function installRecoveryToolDefinitions(context = null) {
+  return Object.entries(INSTALL_RECOVERY_TOOLS)
+    .filter(([name]) => recoveryToolAvailable(name, context))
+    .map(([name, tool]) => ({
     name,
     description: tool.description,
     input_schema: {
@@ -155,7 +173,7 @@ export function installRecoveryToolDefinitions() {
         .map(([key]) => key),
       additionalProperties: false,
     },
-  }));
+    }));
 }
 
 /** Validate a model-proposed call. Returns normalized input or null. */
@@ -469,7 +487,7 @@ async function retryStep(input, context) {
 }
 
 async function installVendorCli(input, context) {
-  if (context.platform !== "win32" || typeof context.installVendorClis !== "function") {
+  if (!["darwin", "win32"].includes(context.platform) || typeof context.installVendorClis !== "function") {
     return result("failed", "Automated vendor CLI installation is unavailable on this platform.");
   }
   const outcome = await context.installVendorClis(input.tool);

package/src/macSetup.js

@@ -0,0 +1,260 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { ensureImpelClaudeProfile, ensureImpelCodexProfile } from "./cliProfiles.js";
+import { findNativeBinary } from "./nativeProcess.js";
+import { syncSkillsSafe } from "./skills.js";
+
+const MAX_INSTALLER_BYTES = 512 * 1024;
+const INSTALLER_DOWNLOAD_TIMEOUT_MS = 30_000;
+const INSTALLER_RUN_TIMEOUT_MS = 10 * 60 * 1_000;
+const MAC_SIGNING_TEAMS = Object.freeze({ claude: "Q6L2SF6YDW", codex: "2DC432GLL2" });
+
+/**
+ * The script bytes are pinned per impel-cli release. Both vendor scripts then
+ * verify the downloaded native binary against the vendor release checksum.
+ */
+export const MAC_CLI_INSTALLERS = Object.freeze({
+  claude: Object.freeze({
+    url: "https://claude.ai/install.sh",
+    sha256: "b3f79015b54c751440a6488f07b1b64f9088742b9052bc1bd356d13108320d2a",
+    command: "curl -fsSL https://claude.ai/install.sh | bash -s stable",
+    args: Object.freeze(["stable"]),
+    environment: Object.freeze({}),
+  }),
+  codex: Object.freeze({
+    url: "https://chatgpt.com/codex/install.sh",
+    sha256: "1154e9daf713aacd1534efca8042bfd6665ad24bc1d1dfd86b8f439fe60a7a5d",
+    command: "curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 CODEX_RELEASE=0.144.6 sh",
+    args: Object.freeze([]),
+    environment: Object.freeze({ CODEX_NON_INTERACTIVE: "1", CODEX_RELEASE: "0.144.6" }),
+  }),
+});
+
+function verifyMacCli(tool, binary, environment, run = spawnSync) {
+  try {
+    const result = run(binary, ["--version"], {
+      encoding: "utf8",
+      env: environment,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 15_000,
+    });
+    if (result?.status !== 0 || result?.error) return false;
+    const explicitOverride = tool === "claude" ? environment.IMPEL_CLAUDE_BIN : environment.IMPEL_CODEX_BIN;
+    if (explicitOverride && path.resolve(explicitOverride) === path.resolve(binary)) return true;
+    const resolved = fs.realpathSync(binary);
+    const verified = run("/usr/bin/codesign", ["--verify", "--strict", resolved], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 15_000,
+    });
+    if (verified?.status !== 0 || verified?.error) return false;
+    const details = run("/usr/bin/codesign", ["-dv", "--verbose=4", resolved], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 15_000,
+    });
+    return details?.status === 0
+      && String(details.stderr || details.stdout || "").includes(`TeamIdentifier=${MAC_SIGNING_TEAMS[tool]}`);
+  } catch {
+    return false;
+  }
+}
+
+function detectMacClis(find, environment, verify) {
+  const detect = (tool) => find(
+    tool,
+    environment,
+    "darwin",
+    "IMPEL",
+    (binary) => verify(tool, binary, environment),
+  );
+  return { claude: detect("claude"), codex: detect("codex") };
+}
+
+async function downloadPinnedInstaller(tool, { fetchImpl, fsImpl, installers }) {
+  const installer = installers[tool];
+  if (!installer) throw new Error(`unsupported macOS CLI installer: ${tool}`);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), INSTALLER_DOWNLOAD_TIMEOUT_MS);
+  let response;
+  try {
+    response = await fetchImpl(installer.url, { redirect: "follow", signal: controller.signal });
+  } finally {
+    clearTimeout(timeout);
+  }
+  if (!response.ok) throw new Error(`official ${tool} installer returned HTTP ${response.status}`);
+  const finalUrl = new URL(response.url || installer.url);
+  if (finalUrl.protocol !== "https:" || !["claude.ai", "chatgpt.com"].includes(finalUrl.hostname)) {
+    throw new Error(`official ${tool} installer redirected to an untrusted origin`);
+  }
+  const bytes = Buffer.from(await response.arrayBuffer());
+  if (bytes.length === 0 || bytes.length > MAX_INSTALLER_BYTES) {
+    throw new Error(`official ${tool} installer had an invalid size`);
+  }
+  const digest = crypto.createHash("sha256").update(bytes).digest("hex");
+  if (digest !== installer.sha256) {
+    throw new Error(`official ${tool} installer checksum did not match this impel-cli release`);
+  }
+  const source = bytes.toString("utf8");
+  if (!source.startsWith("#!")) throw new Error(`official ${tool} installer was not a shell script`);
+  const directory = fsImpl.mkdtempSync(path.join(os.tmpdir(), `impel-${tool}-installer-`));
+  const script = path.join(directory, "install.sh");
+  fsImpl.writeFileSync(script, bytes, { mode: 0o700 });
+  return { directory, script };
+}
+
+async function installMacCli(tool, io) {
+  const installer = io.installers[tool];
+  let downloaded = null;
+  let downloadError = null;
+  for (let attempt = 0; attempt < 2 && !downloaded; attempt += 1) {
+    try {
+      downloaded = await downloadPinnedInstaller(tool, io);
+    } catch (error) {
+      downloadError = error;
+    }
+  }
+  if (!downloaded) throw downloadError || new Error(`official ${tool} installer download failed`);
+  try {
+    const environment = {
+      ...vendorInstallerEnvironment(io.environment),
+      ...(installer.environment || {}),
+    };
+    return io.run("/bin/bash", [downloaded.script, ...(installer.args || [])], {
+      env: environment,
+      stdio: "inherit",
+      timeout: INSTALLER_RUN_TIMEOUT_MS,
+    });
+  } finally {
+    io.fsImpl.rmSync(downloaded.directory, { recursive: true, force: true });
+  }
+}
+
+function vendorInstallerEnvironment(environment) {
+  const allowed = new Set([
+    "HOME", "USER", "LOGNAME", "SHELL", "PATH", "TMPDIR", "LANG", "TERM",
+    "SSL_CERT_FILE", "SSL_CERT_DIR", "NODE_EXTRA_CA_CERTS",
+    "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy",
+  ]);
+  return Object.fromEntries(Object.entries(environment).filter(([name]) => (
+    allowed.has(name) || name.startsWith("LC_")
+  )));
+}
+
+function assertUserOwnedMacInstall(environment, fsImpl, geteuid) {
+  if (environment.SUDO_USER || geteuid() === 0) {
+    throw new Error("refusing to install vendor CLIs under sudo or as root on macOS");
+  }
+  const home = environment.HOME || os.homedir();
+  if (fsImpl.existsSync(home)) {
+    const owner = fsImpl.statSync(home).uid;
+    if (Number.isInteger(owner) && owner !== geteuid()) {
+      throw new Error("the macOS home directory is not owned by the current user");
+    }
+  }
+}
+
+function installationFailure(result, thrown = null) {
+  const error = thrown || result?.error;
+  return error
+    ? { code: error.code || null, message: error.message || String(error), status: null, signal: null }
+    : {
+        code: null,
+        message: null,
+        status: Number.isInteger(result?.status) ? result.status : null,
+        signal: result?.signal || null,
+      };
+}
+
+export async function prepareMacClis({
+  gatewayUrl,
+  tenantId,
+  skipInstall = false,
+  installTools = ["claude", "codex"],
+} = {}, dependencies = {}) {
+  const io = {
+    environment: process.env,
+    find: findNativeBinary,
+    verify: verifyMacCli,
+    run: spawnSync,
+    fetchImpl: fetch,
+    fsImpl: fs,
+    geteuid: () => typeof process.geteuid === "function" ? process.geteuid() : null,
+    installers: MAC_CLI_INSTALLERS,
+    ensureClaudeProfile: ensureImpelClaudeProfile,
+    ensureCodexProfile: ensureImpelCodexProfile,
+    syncSkills: syncSkillsSafe,
+    ...dependencies,
+  };
+  const before = detectMacClis(io.find, io.environment, io.verify);
+  const missingBefore = Object.entries(before).filter(([, binary]) => !binary).map(([tool]) => tool);
+  const requested = new Set(installTools);
+  if (requested.size !== installTools.length || [...requested].some((tool) => !io.installers[tool])) {
+    throw new Error("installTools must contain unique supported macOS CLI names");
+  }
+
+  const installations = {};
+  if (missingBefore.length && !skipInstall) {
+    assertUserOwnedMacInstall(io.environment, io.fsImpl, io.geteuid);
+    for (const tool of missingBefore.filter((candidate) => requested.has(candidate))) {
+      try {
+        const result = await installMacCli(tool, io);
+        const succeeded = result?.status === 0 && !result?.error;
+        installations[tool] = {
+          attempted: true,
+          succeeded,
+          failure: succeeded ? null : installationFailure(result),
+          command: io.installers[tool].command,
+        };
+      } catch (error) {
+        installations[tool] = {
+          attempted: true,
+          succeeded: false,
+          failure: installationFailure(null, error),
+          command: io.installers[tool].command,
+        };
+      }
+    }
+  }
+
+  const installAttempted = Object.keys(installations).length > 0;
+  const binaries = installAttempted
+    ? detectMacClis(io.find, io.environment, io.verify)
+    : before;
+  const claudeProfile = io.ensureClaudeProfile(gatewayUrl, tenantId);
+  const codexProfile = io.ensureCodexProfile(gatewayUrl, tenantId);
+  if (binaries.claude) {
+    await io.syncSkills({
+      client: "claude",
+      gatewayUrl,
+      env: { CLAUDE_CONFIG_DIR: claudeProfile.configDir },
+      label: "Impel isolated Claude (impel claude)",
+    });
+  }
+  if (binaries.codex) {
+    await io.syncSkills({
+      client: "codex",
+      gatewayUrl,
+      env: { CODEX_HOME: codexProfile.codexHome },
+      label: "Impel isolated Codex (impel codex)",
+    });
+  }
+
+  return {
+    binaries,
+    missingBefore,
+    missingAfter: Object.entries(binaries).filter(([, binary]) => !binary).map(([tool]) => tool),
+    installAttempted,
+    installSucceeded: installAttempted
+      ? Object.values(installations).every((installation) => installation.succeeded)
+      : null,
+    installFailure: Object.values(installations).find((installation) => installation.failure)?.failure || null,
+    installations,
+    installCommands: Object.fromEntries(missingBefore.map((tool) => [tool, io.installers[tool].command])),
+    profiles: { claude: claudeProfile.configDir, codex: codexProfile.codexHome },
+  };
+}

package/src/nativeProcess.js

@@ -75,12 +75,12 @@ function commonCandidates(tool, environment, platform) {
   const home = environmentValue(environment, "USERPROFILE") || environmentValue(environment, "HOME") || os.homedir();
   const locations = [];
 
-  if (tool === "claude") {
+  if (tool === "claude" || tool === "codex") {
     locations.push(
-      [paths.join(home, ".local", "bin"), "claude"],
-      [paths.join(home, ".claude", "local"), "claude"],
+      [paths.join(home, ".local", "bin"), tool],
     );
   }
+  if (tool === "claude") locations.push([paths.join(home, ".claude", "local"), "claude"]);
 
   if (platform === "win32") {
     const appData = environmentValue(environment, "APPDATA");

package/src/platformSetup.js

@@ -0,0 +1,49 @@
+import { ensureImpelClaudeProfile, ensureImpelCodexProfile } from "./cliProfiles.js";
+import { redactSecretText } from "./config.js";
+import { findNativeBinary } from "./nativeProcess.js";
+import { prepareMacClis } from "./macSetup.js";
+import { prepareWindowsClis } from "./windowsSetup.js";
+
+export async function preparePlatformClis(options = {}, dependencies = {}) {
+  const platform = options.platform || process.platform;
+  if (platform === "darwin") return prepareMacClis(options, dependencies);
+  if (platform === "win32") return prepareWindowsClis(options, dependencies);
+
+  const environment = dependencies.environment || process.env;
+  const find = dependencies.find || findNativeBinary;
+  const binaries = {
+    claude: find("claude", environment, platform),
+    codex: find("codex", environment, platform),
+  };
+  const claudeProfile = (dependencies.ensureClaudeProfile || ensureImpelClaudeProfile)(options.gatewayUrl, options.tenantId);
+  const codexProfile = (dependencies.ensureCodexProfile || ensureImpelCodexProfile)(options.gatewayUrl, options.tenantId);
+  const missingAfter = Object.entries(binaries).filter(([, binary]) => !binary).map(([tool]) => tool);
+  return {
+    binaries,
+    missingBefore: [...missingAfter],
+    missingAfter,
+    installAttempted: false,
+    installSucceeded: null,
+    installFailure: null,
+    installations: {},
+    installCommands: {},
+    profiles: { claude: claudeProfile.configDir, codex: codexProfile.codexHome },
+  };
+}
+
+export function describeCliFailure(prepared) {
+  const labels = { claude: "Claude Code", codex: "Codex" };
+  const details = [];
+  for (const tool of prepared.missingAfter || []) {
+    const installation = prepared.installations?.[tool];
+    const failure = installation?.failure;
+    const reason = failure?.message || failure?.code
+      || (Number.isInteger(failure?.status)
+        ? `exit ${failure.status}`
+        : installation ? "not discoverable after installation" : "not installed or discoverable");
+    details.push(`${labels[tool] || tool}: ${redactSecretText(reason)}`);
+    const command = installation?.command || prepared.installCommands?.[tool];
+    if (command) details.push(`manual ${tool} installer: ${redactSecretText(command)}`);
+  }
+  return details.join("; ") || `missing vendor CLIs: ${(prepared.missingAfter || []).join(", ")}`;
+}

package/src/privileges.js

@@ -0,0 +1,32 @@
+function effectiveUserId() {
+  return typeof process.geteuid === "function" ? process.geteuid() : null;
+}
+
+export function commandMutatesUserState(argv = []) {
+  const [command, subcommand] = argv;
+  if (["setup", "update", "upgrade", "_converge"].includes(command)) return true;
+  if (command === "app" || command === "apps") {
+    return subcommand !== "status";
+  }
+  return false;
+}
+
+export function elevatedMacExecution({
+  argv = [],
+  platform = process.platform,
+  geteuid = effectiveUserId,
+} = {}) {
+  return platform === "darwin"
+    && commandMutatesUserState(argv)
+    && geteuid() === 0;
+}
+
+export function refuseElevatedMacExecution(argv = [], dependencies = {}) {
+  if (!elevatedMacExecution({ argv, ...dependencies })) return false;
+  console.error(
+    "impel: do not run setup, update, or app management with sudo on macOS. "
+    + "Run the command as the signed-in user so Impel state and Keychain entries have the correct owner."
+  );
+  process.exitCode = 1;
+  return true;
+}

package/src/provisioning.js

@@ -110,19 +110,21 @@ async function prepareTenantCli(config, tenant, io, binaries) {
     try {
       const profile = definition.ensure();
       const root = definition.root(profile);
+      if (!binaries[client]) {
+        clients[client] = {
+          status: "failed",
+          root,
+          error: `${client === "claude" ? "Claude Code" : "Codex"} CLI is not installed or discoverable`,
+        };
+        continue;
+      }
       await io.syncSkills({
         client,
         gatewayUrl,
         env: definition.env(profile),
         label: `Impel ${client === "claude" ? "Claude" : "Codex"} CLI (${tenant.id})`,
       });
-      clients[client] = binaries[client]
-        ? { status: "ready", root, error: null }
-        : {
-            status: "failed",
-            root,
-            error: `${client === "claude" ? "Claude Code" : "Codex"} CLI is not installed or discoverable`,
-          };
+      clients[client] = { status: "ready", root, error: null };
     } catch (error) {
       clients[client] = {
         status: "failed",
@@ -133,7 +135,7 @@ async function prepareTenantCli(config, tenant, io, binaries) {
   }
 
   const agentProfiles = Object.entries(clients)
-    .filter(([, client]) => client.root)
+    .filter(([, client]) => client.root && client.status === "ready")
     .map(([client, value]) => ({
       client,
       root: value.root,