impel-cli 0.17.1 → 0.17.3

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;
+}