impel-cli 0.16.5 → 0.17.1

package/src/commands/setup.js

@@ -1,11 +1,7 @@
-// `impel setup` — end-to-end onboarding: token → tenant → platform clients →
-// verify. macOS installs the isolated desktop apps; Windows ensures the two
-// official vendor CLIs exist and prepares isolated CLI + desktop app profiles.
-// Native Claude Code/Codex profiles are never touched.
+// `impel setup` — authenticate once, then converge every accessible tenant.
 
 import { parseFlags } from "../args.js";
 import {
-  crossAppModelsEnabled,
   loadConfig,
   saveConfig,
   normalizeGatewayUrl,
@@ -15,104 +11,137 @@ import {
   redactSecretText,
 } from "../config.js";
 import { promptSecret, promptText } from "../prompt.js";
-import { ensureImpelClaudeProfile, ensureImpelCodexProfile } from "../cliProfiles.js";
 import { fetchTenants, normalizeTenantId, tenantCredential } from "../tenants.js";
-import { rewriteTenantTokenHelper } from "../apps.js";
-import { cmdApps } from "./apps.js";
-import { prepareWindowsClis, windowsCliInstallCommands } from "../windowsSetup.js";
+import {
+  printReconciliationSummary,
+  reconcileAllTenants,
+  selectDefaultTenant,
+} from "../provisioning.js";
+import { prepareWindowsClis } from "../windowsSetup.js";
 import { runInstallRecovery } from "../installRecovery/engine.js";
+import { restoreNativeProfiles } from "./use.js";
 
-const HELP = `impel setup - guided end-to-end gateway setup
+const HELP = `impel setup - prepare every accessible Impel tenant
 
-Runs the whole onboarding in one command: store your Personal Access Token,
-pick your organization, prepare the Impel clients for this platform, and verify
-the gateway. On macOS this installs isolated desktop apps. On Windows it
-installs any missing official Claude Code/Codex packages, prepares the
-tenant-isolated CLI profiles, and installs isolated desktop app profiles.
-Native client profiles stay untouched and the vendor executables stay signed
-and unmodified.
+Stores your Personal Access Token, discovers every tenant you can access,
+prepares each tenant's isolated Claude and Codex CLI profiles, and installs
+each supported desktop app on macOS and Windows. Personal Claude/Codex profiles
+are never used for Impel sessions.
 
 Usage:
-  impel setup                       Interactive wizard
-  impel setup --pat <pat>           Non-interactive; add --tenant to skip the picker
-  impel setup --tenant <org>        Preselect the organization
-  impel setup --skip-apps           Skip the desktop-app installation step
-  impel setup --skip-clis           On Windows, don't install missing vendor CLIs
-  impel setup --repair              Explicitly opt into sanitized assisted recovery on failure
-  impel setup --no-recovery         Disable local and hosted recovery for this run
+  impel setup                       Interactive setup
+  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 --no-recovery         Disable automatic install recovery
 `;
 
-/**
- * Pick the tenant for the wizard. Pure so it's testable: returns the tenant
- * for an explicit request (or throws if unavailable), auto-selects a sole
- * tenant, and otherwise resolves an interactive answer (number, id, slug, or
- * empty = default).
- */
+/** Kept as a pure compatibility helper for callers/tests. */
 export function resolveTenantChoice(listing, { requested = null, answer = null, currentTenantId = null } = {}) {
-  const byToken = (token) => {
-    const normalized = normalizeTenantId(token);
-    return listing.tenants.find((tenant) => tenant.id === normalized || tenant.slug === normalized) || null;
-  };
-
-  if (requested) {
-    const tenant = byToken(requested);
-    if (!tenant) throw new Error(`tenant "${requested}" is not available to this user`);
+  if (requested) return selectDefaultTenant(listing, { requested, currentTenantId });
+  if (answer && /^\d+$/u.test(answer)) {
+    const tenant = listing.tenants[Number(answer) - 1];
+    if (!tenant) throw new Error(`tenant "${answer}" is not available to this user`);
     return tenant;
   }
-  if (listing.tenants.length === 1) return listing.tenants[0];
-
-  const fallbackId = listing.tenants.some((tenant) => tenant.id === currentTenantId)
-    ? currentTenantId
-    : listing.defaultTenantId;
-  if (answer === null || answer === "") {
-    return listing.tenants.find((tenant) => tenant.id === fallbackId) || listing.tenants[0];
-  }
-  const index = /^\d+$/.test(answer) ? Number(answer) : NaN;
-  if (Number.isInteger(index) && index >= 1 && index <= listing.tenants.length) {
-    return listing.tenants[index - 1];
-  }
-  const tenant = byToken(answer);
-  if (!tenant) throw new Error(`tenant "${answer}" is not available to this user`);
-  return tenant;
+  if (answer) return selectDefaultTenant(listing, { requested: answer, currentTenantId });
+  return selectDefaultTenant(listing, { currentTenantId });
 }
 
-/** Best-effort gateway probe; any HTTP response means the gateway is routing. */
 async function probeGateway(gatewayUrl, pat, tenantId, fetchImpl = fetch) {
-  const url = `${gatewayUrl}/anthropic/v1/messages`;
   const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 5000);
+  const timeout = setTimeout(() => controller.abort(), 5_000);
   try {
-    const res = await fetchImpl(url, {
+    const response = await fetchImpl(`${gatewayUrl}/anthropic/v1/messages`, {
       method: "POST",
       headers: {
         "content-type": "application/json",
-        ...(pat && tenantId ? { authorization: `Bearer ${tenantCredential(pat, tenantId)}` } : {}),
+        authorization: `Bearer ${tenantCredential(pat, tenantId)}`,
       },
       body: "{}",
       signal: controller.signal,
     });
-    return { reachable: true, status: res.status, rejected: res.status === 401 || res.status === 403 };
-  } catch (err) {
+    return { reachable: true, status: response.status, rejected: [401, 403].includes(response.status) };
+  } catch (error) {
     return {
       reachable: false,
-      error: err?.name === "AbortError" ? "timed out after 5s" : redactSecretText(err?.message || err),
+      error: error?.name === "AbortError" ? "timed out after 5s" : redactSecretText(error?.message || error),
     };
   } finally {
     clearTimeout(timeout);
   }
 }
 
+function markProbeFailures(report, probes) {
+  probes.forEach((probe, index) => {
+    if (probe.reachable && !probe.rejected) return;
+    const tenant = report.tenants[index];
+    tenant.cli = "failed";
+    tenant.status = "failed";
+    for (const client of Object.values(tenant.clients)) {
+      if (client.cli === "ready") client.cli = "failed";
+    }
+    tenant.errors.push(probe.rejected
+      ? `credential rejected (HTTP ${probe.status})`
+      : `gateway unreachable (${probe.error || "unknown error"})`);
+  });
+  report.passed = report.tenants.every((tenant) => (
+    ["ready", "unavailable"].includes(tenant.cli)
+    && ["ready", "unavailable"].includes(tenant.apps)
+    && ["ready", "unavailable"].includes(tenant.shell)
+  ));
+  return report;
+}
+
+function recomputeReport(report) {
+  report.passed = report.tenants.every((tenant) => (
+    ["ready", "unavailable"].includes(tenant.cli)
+    && ["ready", "unavailable"].includes(tenant.apps)
+    && ["ready", "unavailable"].includes(tenant.shell)
+  ));
+  return report;
+}
+
+function mergeTenantReport(report, replacement) {
+  const byId = new Map(replacement.tenants.map((tenant) => [tenant.tenantId, tenant]));
+  report.tenants = report.tenants.map((tenant) => byId.get(tenant.tenantId) || tenant);
+  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());
+}
+
 export async function cmdSetup(argv, overrides = {}) {
   const io = {
+    loadConfig,
+    saveConfig,
     promptSecret,
     promptText,
     fetchTenants,
-    installApps: cmdApps,
     prepareWindowsClis,
+    reconcile: reconcileAllTenants,
     probe: probeGateway,
     recoverInstall: runInstallRecovery,
+    restoreNativeProfiles,
     isTTY: process.stdin.isTTY,
     platform: process.platform,
+    environment: process.env,
     ...overrides,
   };
   const { flags, positionals } = parseFlags(argv, {
@@ -122,7 +151,7 @@ export async function cmdSetup(argv, overrides = {}) {
     app: { type: "string" },
     "skip-apps": { type: "boolean" },
     "skip-clis": { type: "boolean" },
-    repair: { type: "boolean" },
+    repair: { type: "boolean" }, // deprecated compatibility no-op
     "no-recovery": { type: "boolean" },
     help: { type: "boolean" },
   });
@@ -130,422 +159,277 @@ export async function cmdSetup(argv, overrides = {}) {
     console.log(HELP);
     return;
   }
-  if (positionals.length > 0) {
-    console.error(
-      `impel setup: no longer takes a target ("${positionals[0]}"). Run bare \`impel setup\` — it installs the vendored Impel apps. To flip a native tool, use \`impel use gateway [claude|codex]\`.`
-    );
+  if (positionals.length) {
+    console.error(`impel setup: unexpected argument "${redactSecretText(positionals[0])}"; run bare \`impel setup\`.`);
     process.exitCode = 1;
     return;
   }
 
-  const existing = loadConfig();
+  const existing = io.loadConfig();
   const gatewayUrl = normalizeGatewayUrl(flags.gateway || existing?.gatewayUrl || resolveDefaultGateway());
   const appUrl = normalizeGatewayUrl(flags.app || existing?.appUrl || resolveDefaultAppUrl());
-
-  console.log("Impel gateway setup");
-  console.log(`  gateway: ${gatewayUrl}`);
-  console.log(`  app:     ${appUrl}`);
-  console.log("");
-
-  // ── Step 1: token ────────────────────────────────────────────────────────
   let pat = flags.pat;
   if (!pat && existing?.pat) {
-    if (io.isTTY) {
-      const entered = await io.promptSecret(
-        `1/4 Token — one is already stored (${maskSecret(existing.pat)}). Press Enter to keep it, or paste a new one: `
-      );
-      pat = entered || existing.pat;
-    } else {
-      pat = existing.pat;
-    }
-  } else if (!pat) {
-    if (!io.isTTY) {
-      console.error("impel setup: no token stored and stdin is not a TTY; pass --pat <impel_pat_...>.");
-      process.exitCode = 1;
-      return;
-    }
-    console.log(`1/4 Token — create one at ${appUrl}/settings/gateway (step 3 on that page mints it).`);
-    pat = await io.promptSecret("    Paste your Personal Access Token (impel_pat_...): ");
+    pat = io.isTTY
+      ? (await io.promptSecret(`Token (${maskSecret(existing.pat)} stored; Enter keeps it): `)) || existing.pat
+      : existing.pat;
+  } else if (!pat && io.isTTY) {
+    pat = await io.promptSecret("Impel Personal Access Token (impel_pat_...): ");
   }
   if (!pat) {
-    console.error("impel setup: no token provided, aborting.");
+    console.error("impel setup: no token provided; pass --pat or run interactively.");
     process.exitCode = 1;
     return;
   }
-  if (!pat.startsWith("impel_pat_")) {
-    console.warn(
-      `impel: warning: that token doesn't start with "impel_pat_" — double check you copied the right value.`
-    );
-  }
 
   const config = { ...(existing || {}), pat, gatewayUrl, appUrl, updatedAt: new Date().toISOString() };
-  saveConfig(config);
-  console.log(`    ✓ stored in ~/.config/impel/config.json (mode 0600)`);
-  console.log("");
-
-  const setupFailures = [];
-  const recordSetupFailure = (failure) => {
-    setupFailures.push({
-      platform: io.platform,
-      architecture: process.arch,
-      ...failure,
-    });
-  };
+  io.saveConfig(config);
+  console.log("✓ Stored the Impel credential privately.");
 
-  // ── Step 2: organization ─────────────────────────────────────────────────
-  // A successful tenant fetch also proves the token: the app verifies it
-  // against impel-identity before answering.
   let listing;
   try {
     listing = await io.fetchTenants(config);
   } catch (error) {
     console.error(`impel setup: could not verify the token (${redactSecretText(error?.message || error)})`);
-    console.error("  Check the token and your network, then re-run `impel setup`.");
     process.exitCode = 1;
     return;
   }
+  const selected = selectDefaultTenant(listing, {
+    requested: flags.tenant || null,
+    currentTenantId: existing?.tenantId || null,
+  });
+  config.tenantId = selected.id;
+  config.tenantName = selected.name;
+  if (listing.productAccess) config.productAccess = listing.productAccess;
+  if (listing.scopes) config.scopes = listing.scopes;
+  config.tenantsUpdatedAt = new Date().toISOString();
+  io.saveConfig(config);
 
-  let tenant;
+  const orderedTenants = [...listing.tenants].sort((left, right) => left.id.localeCompare(right.id));
+  console.log(`Accessible tenants (${orderedTenants.length}):`);
+  for (const tenant of orderedTenants) {
+    console.log(`  ${tenant.id}${tenant.id === selected.id ? " (CLI default)" : ""} — ${tenant.name}`);
+  }
   try {
-    if (flags.tenant || listing.tenants.length === 1 || !io.isTTY) {
-      tenant = resolveTenantChoice(listing, {
-        requested: flags.tenant || null,
-        currentTenantId: existing?.tenantId || null,
-      });
-    } else {
-      console.log("2/4 Organization");
-      listing.tenants.forEach((candidate, index) => {
-        const markers = [
-          candidate.id === existing?.tenantId ? "current" : null,
-          candidate.id === listing.defaultTenantId ? "default" : null,
-        ].filter(Boolean);
-        console.log(`    [${index + 1}] ${candidate.id}${markers.length ? ` (${markers.join(", ")})` : ""}\t${candidate.name}`);
-      });
-      const fallback = resolveTenantChoice(listing, { currentTenantId: existing?.tenantId || null });
-      const answer = await io.promptText(`    Select [1-${listing.tenants.length}] (Enter for ${fallback.id}): `);
-      tenant = resolveTenantChoice(listing, { answer, currentTenantId: existing?.tenantId || null });
-    }
+    io.restoreNativeProfiles({ quiet: true });
   } catch (error) {
-    console.error(`impel setup: ${redactSecretText(error?.message || error)}`);
-    process.exitCode = 1;
-    return;
+    console.warn(`Legacy native-profile cleanup was skipped safely (${redactSecretText(error?.message || error)}).`);
   }
 
-  config.tenantId = tenant.id;
-  config.tenantName = tenant.name;
-  if (listing.productAccess) config.productAccess = listing.productAccess;
-  else delete config.productAccess;
-  if (listing.scopes) config.scopes = listing.scopes;
-  else delete config.scopes;
-  config.tenantsUpdatedAt = new Date().toISOString();
-  saveConfig(config);
-  console.log(`    ✓ tenant: ${tenant.id} (${tenant.name})`);
-  console.log("");
-
-  // ── Step 3: apps ─────────────────────────────────────────────────────────
-  // Order inside `impel app install`: close running Claude/ChatGPT apps (a
-  // running app makes the install fail), bring the vendor apps to the verified
-  // version, then build the vendored Impel bundles from that fresh copy.
-  // Native Claude Code and Codex profiles are never touched.
-  let platformSetupFailed = false;
-  if (io.platform === "win32") {
-    console.log(
-      flags["skip-clis"]
-        ? "3/4 Windows CLIs: preparing isolated profiles (vendor CLI installation skipped)…"
-        : "3/4 Windows CLIs: ensuring Claude Code and Codex are installed, then preparing isolated profiles…"
+  const vendorAppDecisions = new Map();
+  const confirmVendorInstall = async (target, context) => {
+    if (vendorAppDecisions.has(target)) return vendorAppDecisions.get(target);
+    if (!io.isTTY) {
+      vendorAppDecisions.set(target, false);
+      return false;
+    }
+    const label = target === "claude" ? "Claude" : "ChatGPT/Codex";
+    const answer = await io.promptText(
+      `Allow the verified ${label} vendor ${context.mode === "update" ? "update" : "installation"}? [y/N] `,
     );
+    const allowed = confirmed(answer);
+    vendorAppDecisions.set(target, allowed);
+    return allowed;
+  };
+
+  let sharedFailure = null;
+  const prepareSharedClis = async ({ confirmedTools = null, inspectOnly = false } = {}) => {
+    if (io.platform !== "win32") return { binaries: {}, missingAfter: [] };
     try {
-      const result = await io.prepareWindowsClis({
+      const inspected = await io.prepareWindowsClis({
         gatewayUrl,
-        tenantId: tenant.id,
-        skipInstall: Boolean(flags["skip-clis"]),
+        tenantId: selected.id,
+        skipInstall: true,
       });
-      for (const [tool, label] of [["claude", "Claude Code"], ["codex", "Codex"]]) {
-        const binary = result.binaries[tool];
-        if (binary) console.log(`    ✓ ${label}: ${redactSecretText(binary)}`);
-        else console.log(`    ✗ ${label}: not found`);
-      }
-      if (result.missingAfter.length > 0 && !flags["skip-clis"]) {
-        platformSetupFailed = true;
-        const fallbackCommands = windowsCliInstallCommands(result.missingAfter);
-        for (const tool of result.missingAfter) {
-          const label = tool === "claude" ? "Claude Code" : "Codex";
-          const installation = result.installations?.[tool];
-          const failure = installation?.failure;
-          if (installation?.succeeded === false || (!installation && result.installSucceeded === false)) {
-            const detail = failure?.message
-              ? `: ${redactSecretText(failure.message)}`
-              : Number.isInteger(failure?.status)
-                ? ` (exit code ${failure.status})`
-                : failure?.signal
-                  ? ` (signal ${failure.signal})`
-                  : "";
-            console.error(`    ${label}'s native installer failed${detail}.`);
-            recordSetupFailure({
-              step: `install.vendor_cli.${tool}`,
-              command: installation?.command || result.installCommands?.[tool] || fallbackCommands[tool],
-              exitCode: failure?.status,
-              signal: failure?.signal,
-              errorCode: failure?.code,
-              message: failure?.message
-                ? `${label}'s native installer failed: ${failure.message}`
-                : `${label}'s native installer did not reach a verified state.`,
-            });
-          } else {
-            console.error(`    ${label}'s native installer completed, but Impel could not verify the command.`);
-            recordSetupFailure({
-              step: `verify.vendor_cli.${tool}`,
-              command: installation?.command || result.installCommands?.[tool] || fallbackCommands[tool],
-              message: `${label}'s installer completed but the command was not discoverable or did not pass its version check.`,
-            });
+      let prepared = inspected;
+      if (inspected.missingAfter.length && !inspectOnly && !flags["skip-clis"]) {
+        let installTools = confirmedTools;
+        if (installTools === null) {
+          installTools = [];
+          if (io.isTTY) {
+            for (const tool of inspected.missingAfter) {
+              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);
+              }
+            }
           }
-          console.error("    Retry its official installer in the same PowerShell window:");
-          console.error(`      ${installation?.command || result.installCommands?.[tool] || fallbackCommands[tool]}`);
         }
-        console.error("    Then close and reopen PowerShell and re-run `impel setup`.");
-      } else if (result.missingAfter.length > 0) {
-        console.log("    Vendor CLI installation was skipped; install it before using the matching launcher.");
-      } else {
-        console.log("    ✓ tenant-isolated Claude and Codex profiles are ready");
-      }
-    } catch (error) {
-      platformSetupFailed = true;
-      console.error(`    ✗ Windows CLI setup failed (${redactSecretText(error?.message || error)})`);
-      console.error("    Fix the issue, then re-run `impel setup`.");
-      recordSetupFailure({
-        step: "setup.windows_clis",
-        errorCode: error?.code,
-        message: `Windows CLI setup failed: ${error?.message || error}`,
-      });
-    }
-    if (flags["skip-apps"]) {
-      console.log("    Windows desktop apps: skipped (--skip-apps).");
-    } else {
-      console.log("    Windows desktop apps: installing signed vendor apps and isolated Impel profiles…");
-      try {
-        const installed = await io.installApps(["install", "all"]);
-        if (installed === false) {
-          platformSetupFailed = true;
-          console.error("    ✗ Windows desktop app setup failed; fix the issue above, then re-run `impel app install all`.");
-          recordSetupFailure({
-            step: "install.vendor_app.all",
-            message: "Windows desktop app setup returned an unsuccessful result.",
+        if (installTools.length) {
+          prepared = await io.prepareWindowsClis({
+            gatewayUrl,
+            tenantId: selected.id,
+            skipInstall: false,
+            installTools,
           });
-        } else {
-          console.log("    ✓ available Impel desktop app profiles are ready");
         }
-      } catch (error) {
-        platformSetupFailed = true;
-        console.error(`    ✗ Windows desktop app setup failed (${redactSecretText(error?.message || error)})`);
-        console.error("    Fix the issue, then re-run `impel app install all`.");
-        recordSetupFailure({
-          step: "install.vendor_app.all",
-          errorCode: error?.code,
-          message: `Windows desktop app setup failed: ${error?.message || error}`,
-        });
       }
-    }
-  } else if (flags["skip-apps"]) {
-    console.log("3/4 Apps: skipped (--skip-apps). Install later with `impel app install`.");
-  } else if (io.platform !== "darwin") {
-    console.log(
-      "3/4 Apps: skipped — isolated desktop apps are unavailable on this platform. Use `impel claude` / `impel codex` for isolated CLI sessions."
-    );
-  } else {
-    console.log(
-      "3/4 Installing the Impel desktop apps (running Claude/ChatGPT apps are closed, verified vendor builds installed first)…"
-    );
-    try {
-      await io.installApps(["install", "all"]);
-      console.log("    ✓ available Impel desktop apps installed");
+      if (prepared.missingAfter.length) {
+        sharedFailure = describeWindowsCliFailure(prepared);
+        return prepared;
+      }
+      sharedFailure = null;
+      return prepared;
     } catch (error) {
-      platformSetupFailed = true;
-      console.error(
-        `    ✗ app installation failed (${redactSecretText(error?.message || error)})`
-      );
-      console.error("    Fix the issue, then re-run `impel app install`.");
-      recordSetupFailure({
-        step: "install.vendor_app.all",
-        errorCode: error?.code,
-        message: `Desktop app installation failed: ${error?.message || error}`,
-      });
+      sharedFailure = redactSecretText(error?.message || error);
+      return { binaries: {}, missingAfter: ["claude", "codex"] };
     }
-  }
-  console.log("");
+  };
+  await prepareSharedClis();
 
-  // ── Step 4: verify ───────────────────────────────────────────────────────
-  const probe = await io.probe(gatewayUrl, pat, tenant.id);
-  let verificationFailed = false;
-  if (probe.reachable && !probe.rejected) {
-    console.log(`4/4 Verify: ✓ gateway reachable (HTTP ${probe.status})`);
-  } else if (probe.rejected) {
-    verificationFailed = true;
-    console.log(`4/4 Verify: ✗ gateway reachable but it rejected the token (HTTP ${probe.status}).`);
-    console.log("    Mint a fresh token and re-run `impel setup`.");
-    recordSetupFailure({
-      step: "verify.gateway",
-      exitCode: probe.status,
-      message: `The gateway rejected the configured credential with HTTP ${probe.status}.`,
-    });
-  } else {
-    verificationFailed = true;
-    console.log(`4/4 Verify: ✗ gateway unreachable (${probe.error}).`);
-    console.log("    Check your network, then run `impel status` to retry.");
-    recordSetupFailure({
-      step: "verify.gateway",
-      message: `The gateway could not be reached: ${probe.error}.`,
-    });
-  }
+  const runConvergence = (
+    includeApps = !flags["skip-apps"],
+    tenants = orderedTenants,
+    confirmInstall = confirmVendorInstall,
+  ) => io.reconcile({
+    config,
+    listing: { ...listing, tenants },
+    mode: "setup",
+    includeApps,
+    platform: io.platform,
+    environment: io.environment,
+    confirmVendorInstall: confirmInstall,
+  }, {
+    ...(overrides.installApps ? { installApps: overrides.installApps } : {}),
+    ...(overrides.registerShellEntries ? { registerShellEntries: overrides.registerShellEntries } : {}),
+    ...(overrides.ensureClaude ? { ensureClaude: overrides.ensureClaude } : {}),
+    ...(overrides.ensureCodex ? { ensureCodex: overrides.ensureCodex } : {}),
+    ...(overrides.syncSkills ? { syncSkills: overrides.syncSkills } : {}),
+    ...(overrides.syncAgents ? { syncAgents: overrides.syncAgents } : {}),
+    ...(overrides.knownTenantIds ? { knownTenantIds: overrides.knownTenantIds } : {}),
+    ...(overrides.findBinary ? { findBinary: overrides.findBinary } : {}),
+  });
 
-  if (platformSetupFailed || verificationFailed) {
-    const aggregateFailure = {
-      platform: io.platform,
-      architecture: process.arch,
-      step: setupFailures.length === 1 ? setupFailures[0].step : "setup.multiple",
-      message:
-        setupFailures.length === 1
-          ? setupFailures[0].message
-          : `${setupFailures.length} setup checks failed.`,
-      diagnostics: Object.fromEntries(
-        setupFailures.slice(0, 20).map((failure, index) => [
-          `failure${index + 1}`,
-          `${failure.step}: ${failure.message}`,
-        ])
-      ),
-    };
+  const verifyConvergence = async (
+    includeApps = !flags["skip-apps"],
+    tenants = orderedTenants,
+    confirmInstall = confirmVendorInstall,
+  ) => {
+    const nextReport = await runConvergence(includeApps, tenants, confirmInstall);
+    const probes = await Promise.all(tenants.map((tenant) => io.probe(gatewayUrl, pat, tenant.id)));
+    return markProbeFailures(nextReport, probes);
+  };
+  let report = await verifyConvergence();
+  if (sharedFailure) report.passed = false;
 
-    // Recovery ends as "fixed" only when every goal derived from the failed
-    // steps passes a fresh local check. App installs have no cheap external
-    // probe, so that goal tracks the most recent reviewed install result.
-    const appInstallState = { ok: false };
-    const installVendorApp = async (target) => {
-      const installed = await io.installApps(["install", target]);
-      appInstallState.ok = installed !== false;
-      return installed;
-    };
-    const goals = [];
-    if (io.platform === "win32" && setupFailures.some((failure) => /vendor_cli|windows_clis/iu.test(failure.step))) {
-      goals.push({
-        id: "windows-clis",
-        description: "Claude Code and Codex are installed and pass their version checks",
-        run: async () => {
-          const checked = await io.prepareWindowsClis({
-            gatewayUrl,
-            tenantId: tenant.id,
-            skipInstall: true,
-          });
-          return checked.missingAfter.length === 0
-            ? true
-            : { ok: false, detail: `still missing: ${checked.missingAfter.join(", ")}` };
+  if (sharedFailure && !flags["no-recovery"]) {
+    let sharedReady = false;
+    const recovery = await io.recoverInstall({
+      failure: {
+        scope: "shared",
+        platform: io.platform,
+        architecture: process.arch,
+        step: "setup.shared_vendor_clis",
+        message: sharedFailure,
+      },
+      config,
+      goals: [{
+        id: "shared-vendor-clis-ready",
+        description: "Shared vendor CLI prerequisites are installed and discoverable",
+        run: () => sharedReady,
+      }],
+      explicit: Boolean(flags.repair),
+      noRecovery: false,
+      actionContext: {
+        tenantId: selected.id,
+        installVendorClis: async (tool) => {
+          const prepared = await prepareSharedClis({ confirmedTools: [tool] });
+          sharedReady = !sharedFailure;
+          return prepared;
         },
-      });
-    }
-    if (setupFailures.some((failure) => /vendor_app/iu.test(failure.step))) {
-      goals.push({
-        id: "desktop-apps",
-        description: "The Impel desktop app profiles installed cleanly",
-        run: () => appInstallState.ok === true,
-      });
-    }
-    if (setupFailures.some((failure) => failure.step === "verify.gateway")) {
-      goals.push({
-        id: "gateway",
-        description: "The gateway accepts the stored credential",
-        run: async () => {
-          const checked = await io.probe(gatewayUrl, pat, tenant.id);
-          return checked.reachable && !checked.rejected
-            ? true
-            : { ok: false, detail: checked.error || `HTTP ${checked.status}` };
+        retryStep: async () => {
+          await prepareSharedClis({ inspectOnly: true });
+          sharedReady = !sharedFailure;
+          return sharedReady;
         },
-      });
-    }
+      },
+    }, overrides.recoveryOverrides || {});
+    if (recovery.fixed) await prepareSharedClis({ inspectOnly: true });
+  }
 
-    try {
-      const recovery = await io.recoverInstall(
-        {
-          failure: aggregateFailure,
-          config,
-          goals,
-          explicit: Boolean(flags.repair),
-          noRecovery: Boolean(flags["no-recovery"]),
-          actionContext: {
-            tenantId: tenant.id,
-            probeGateway: () => io.probe(gatewayUrl, pat, tenant.id),
-            installVendorClis: (tool) =>
-              io.prepareWindowsClis({
-                gatewayUrl,
-                tenantId: tenant.id,
-                skipInstall: false,
-                installTools: [tool],
-              }),
-            repairProfiles: async () => {
-              if (io.platform === "win32") {
-                const result = await io.prepareWindowsClis({
-                  gatewayUrl,
-                  tenantId: tenant.id,
-                  skipInstall: true,
-                });
-                return result.missingAfter.length === 0;
-              }
-              ensureImpelClaudeProfile(gatewayUrl, tenant.id, {
-                crossAppModels: crossAppModelsEnabled(config),
-              });
-              ensureImpelCodexProfile(gatewayUrl, tenant.id);
-              // Also refresh the app token helper: a stale baked node/CLI
-              // path there breaks every managed app's auth.
-              rewriteTenantTokenHelper(tenant.id);
-              return true;
-            },
-            installVendorApp,
-            retryStep: async (step) => {
-              if (/vendor_cli|windows_clis/iu.test(step || "")) {
-                const result = await io.prepareWindowsClis({
-                  gatewayUrl,
-                  tenantId: tenant.id,
-                  skipInstall: false,
-                });
-                return result.missingAfter.length === 0;
-              }
-              if (/vendor_app/iu.test(step || "")) {
-                return (await installVendorApp("all")) !== false;
-              }
-              if (/gateway/iu.test(step || "")) {
-                const result = await io.probe(gatewayUrl, pat, tenant.id);
-                return Boolean(result.reachable && !result.rejected);
-              }
-              return false;
+  if (!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;
+      let retryReport = null;
+      let retryPassed = false;
+      const retryTenant = async (confirmInstall) => {
+        retryReport = await verifyConvergence(!flags["skip-apps"], [tenant], confirmInstall);
+        retryPassed = retryReport.passed;
+        return retryPassed;
+      };
+      const retrySafeState = async () => {
+        const profileReport = await verifyConvergence(false, [tenant], async () => false);
+        const profile = profileReport.tenants[0];
+        const current = report.tenants.find((candidate) => candidate.tenantId === tenant.id);
+        const cliReady = ["ready", "unavailable"].includes(profile?.cli);
+        const nonCliReady = ["ready", "unavailable"].includes(current?.apps)
+          && ["ready", "unavailable"].includes(current?.shell);
+        retryPassed = cliReady && nonCliReady;
+        if (retryPassed) {
+          const combined = {
+            ...current,
+            cli: profile.cli,
+            clients: {
+              claude: { ...current.clients.claude, cli: profile.clients.claude.cli },
+              codex: { ...current.clients.codex, cli: profile.clients.codex.cli },
             },
+            errors: profile.errors,
+            status: "ready",
+          };
+          retryReport = { ...profileReport, tenants: [combined], passed: true };
+        }
+        return retryPassed;
+      };
+      await io.recoverInstall({
+        failure: {
+          scope: "tenant",
+          tenantId: tenant.id,
+          platform: io.platform,
+          architecture: process.arch,
+          step: "setup.tenant_convergence",
+          message: failed.errors.join("; ") || "Tenant readiness verification failed.",
+          diagnostics: { tenant: tenant.id },
+        },
+        config,
+        goals: [{
+          id: `tenant-${tenant.id}-ready`,
+          description: `Tenant ${tenant.id} is locally verified and launchable`,
+          run: () => retryPassed,
+        }],
+        explicit: Boolean(flags.repair),
+        noRecovery: false,
+        actionContext: {
+          tenantId: tenant.id,
+          probeGateway: () => io.probe(gatewayUrl, pat, tenant.id),
+          repairProfiles: async () => {
+            const profileReport = await verifyConvergence(false, [tenant]);
+            return ["ready", "unavailable"].includes(profileReport.tenants[0]?.cli);
           },
+          retryStep: () => retrySafeState(),
+          installVendorApp: (target) => retryTenant(async (product) => (
+            target === "all"
+            || product === target
+            || (target === "codex" && product === "chatgpt")
+          )),
         },
-        {
-          isTTY: io.isTTY,
-          promptText: io.promptText,
-          ...(overrides.recoveryOverrides || {}),
-        }
-      );
-      // "fixed" is only reported after every goal passed a fresh local check
-      // inside the engine, so no separate re-verification is needed here.
-      if (recovery.fixed) {
-        platformSetupFailed = false;
-        verificationFailed = false;
-      }
-    } catch (error) {
-      console.warn(`Install recovery could not start (${redactSecretText(error?.message || error)}).`);
+      }, overrides.recoveryOverrides || {});
+      if (retryReport) mergeTenantReport(report, retryReport);
     }
   }
+  recomputeReport(report);
+  report.passed = report.passed && !sharedFailure;
 
-  if (platformSetupFailed || verificationFailed) process.exitCode = 1;
-
-  console.log("");
-  if (platformSetupFailed || verificationFailed) {
-    console.log("Setup is incomplete; the token and tenant were saved, but the failed step above still needs attention.");
-    console.log("Fix it and re-run `impel setup`.");
-    return;
+  printReconciliationSummary(report);
+  console.log(`CLI tenant: ${selected.id}`);
+  console.log("Change it: impel tenant use <tenant>");
+  console.log("Launch: impel claude | impel codex");
+  if (!report.passed || sharedFailure) {
+    if (sharedFailure) console.error(`Shared setup failure: ${sharedFailure}`);
+    console.error("Setup is incomplete. Fix the reported issue or rerun `impel setup`.");
+    process.exitCode = 1;
+    return report;
   }
-  console.log("You're set. Try:");
-  if (io.platform === "darwin") console.log("  impel app open    open the Impel desktop apps");
-  if (io.platform === "win32") console.log("  impel app open all    open Claude and ChatGPT with isolated Impel profiles");
-  console.log("  impel claude      isolated Claude Code through the gateway");
-  console.log("  impel codex       isolated Codex through the gateway");
-  console.log("  impel status      full diagnostics any time");
+  console.log("Setup complete for every accessible tenant.");
+  return report;
 }