impel-cli 0.16.4 → 0.17.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "impel-cli",
-  "version": "0.16.4",
-  "description": "Configure Claude Code and Codex CLI to talk to Impel's gateway, authenticated by an Impel Personal Access Token",
+  "version": "0.17.0",
+  "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {
     "impel": "bin/impel.js"

package/src/apps.js

@@ -12,6 +12,7 @@ import {
 import { normalizeTenantId } from "./tenants.js";
 import { impelCliInvocation } from "./selfInvocation.js";
 import { crossAppModelsEnabled, redactSecretText } from "./config.js";
+import { ensureClaudeSessionHooks, ensureCodexSessionHooks } from "./sessionHooks.js";
 import { ADHOC_IDENTITY, codesignIdentityArgs, desiredSigningMode, resolveSigningIdentity } from "./codesign.js";
 import { applyImpelClaudeSandbox } from "./claudeSandbox.js";
 
@@ -163,7 +164,7 @@ export function managedAppIdentity(target, tenantId = null, tenantName = null) {
 
 // Bump when the written config/manifest schema changes; a mismatch forces the
 // slow open path (and thus a full config rewrite) after a CLI update.
-export const CURRENT_CONFIG_VERSION = 15;
+export const CURRENT_CONFIG_VERSION = 16;
 
 // Identifies the bundle-BUILDING logic — the asar patches, plist rewrites,
 // helper rebranding, and signing. A vendored bundle is rebuilt only when this
@@ -617,8 +618,12 @@ export function installManagedAppFiles({
       writeClaudeDefaultApp(paths);
       writeClaudeCodeSettings(paths);
       writeClaudeConfig(paths, config, models);
+      ensureClaudeSessionHooks(paths.claude.userData, config.tenantId, "claude_desktop");
+    }
+    else {
+      writeChatGPTConfig(paths, config, models, vendorCodexModels, chatgptInvocations);
+      ensureCodexSessionHooks(paths.chatgpt.codexHome, config.tenantId, "codex_desktop");
     }
-    else writeChatGPTConfig(paths, config, models, vendorCodexModels, chatgptInvocations);
     // Non-bundle targets are the background-refresh / fast-open path: configs,
     // token helper, catalog, and manifest only. Bundle swaps require the app
     // to be closed (see quitBlockingApps), so those paths never attempt one.
@@ -1024,6 +1029,7 @@ function writeChatGPTConfig(paths, config, models, vendorCodexModels, invocation
   const managedToml = [
     CHATGPT_CONFIG_START,
     "# Managed by `impel app update`. This profile is isolated from ~/.codex.",
+    "# Impel session-hook trust is pinned separately by exact handler hash.",
     `model = ${tomlString(selectedModel.slug)}`,
     'model_provider = "impel"',
     `chatgpt_base_url = ${tomlString(`${config.gatewayUrl}/chatgpt_passthrough/backend-api`)}`,

package/src/cli.js

@@ -15,61 +15,43 @@ import { cmdAgents } from "./commands/agents.js";
 import { cmdTenant } from "./commands/tenant.js";
 import { cmdDoctor } from "./commands/doctor.js";
 import { cmdSetup } from "./commands/setup.js";
+import { cmdSessions } from "./commands/sessions.js";
 import { cmdUpdate } from "./commands/update.js";
 import { cmdExperimental } from "./commands/experimental.js";
+import { cmdConverge } from "./commands/converge.js";
 
-const HELP = `impel — the Impel gateway CLI: isolated Claude Code, Codex, and desktop apps
+const HELP = `impel — isolated Impel workspaces for every tenant
 
 Get started:
-  impel setup                                 Guided end-to-end onboarding: token, tenant,
-                                              platform clients, gateway verification
-                                              (--pat <pat> --tenant <org> --skip-apps/--skip-clis
-                                               --repair/--no-recovery)
-  impel update                                Update everything: the CLI itself, then the
-                                              Impel apps, skills, and agents (--check, --skip-apps)
-
-Run:
+  impel setup                                 Authenticate and prepare every accessible tenant
+                                              (--pat <pat>, --tenant <org>, --no-recovery)
+  impel update                                Update the CLI and reconcile every tenant
+                                              (--check, --skip-apps, --no-recovery)
+
+Work:
   impel claude [args...]                      Launch Claude Code with an isolated Impel profile
   impel codex [args...]                       Launch Codex with an isolated Impel profile
-  impel app open [target] [--tenant <org>]    Install/configure on first use, then open the app(s)
-  impel status                                Tenant, PAT, per-tool mode, gateway reachability
-  impel doctor [--tenant <org>|--all-tenants] Synthetic provider, routing, and latency checks
+  impel tenant list                           List accessible organizations
+  impel tenant current                        Show the CLI's current organization
+  impel tenant use <org>                      Select the organization for CLI launches
+
+Workspace:
+  impel tasks list|get|create|update|delete   Work with Impel tickets (aliases: task, ticket[s])
 
-Manage:
-  impel auth [--pat <pat>]                    Store your PAT + URLs (--gateway/--app <url>)
+Account:
   impel pat create --label <label>            Mint a personal PAT (--org/--scopes/--ttl-days)
   impel pat create --agent <agent-id>         Mint an org-scoped PAT associated with an agent
   impel pat revoke <token-id> --yes           Irreversibly revoke one of your PATs
-  impel tenant list|current|use <org>         List or select the active organization
-  impel tasks list|get|create|update|delete   CRUD Impel tickets (aliases: task, ticket[s])
-  impel token [--tenant <org>]                Print the selected-tenant bearer
-  impel mcp                                   Run the local Impel MCP stdio bridge
-  impel skills sync [claude|codex|all]        Sync shared skills into managed clients
-  impel agents sync [claude|codex|all]        Sync explicit tenant agents into native clients
-
-Desktop apps (macOS and Windows):
-  target is claude, chatgpt/codex, or all (default: all)
-  impel app install [target] [--tenant <org>] Install that tenant's isolated app/profile
-  impel app update [target] [--tenant <org>]  Update profiles; all without --tenant updates
-                                              every installed tenant (--force: clean rebuild)
-  impel app refresh [target] [--tenant <org>] Configs/catalog/skills/agents only; safe while apps run
-  impel app status [target] [--tenant <org>]  Show isolated app and vendor versions
-  impel app uninstall [target] [--tenant <org>] [--keep-data]
-                                              Remove only that tenant's managed apps/data
-
-Native profile switching (advanced; setup never touches native tools):
-  impel use gateway [claude|codex|all]        Route native Claude Code/Codex through the gateway
-  impel use account [claude|codex|all]        Revert to your own Anthropic/OpenAI login
-  impel on / impel off                        Aliases for the two commands above
+
+Diagnostics:
+  impel status                                Authentication, current tenant, and local readiness
+  impel doctor [--tenant <org>|--all-tenants] Synthetic provider, routing, and latency checks
 
   impel help                                  Show this help
   impel --version                             Show the installed version
 
 Env:
-  IMPEL_GATEWAY_URL   Default gateway URL when --gateway isn't passed.
-  IMPEL_APP_URL       Default app/control-plane URL for setup, auth, PATs, and tasks.
   IMPEL_SKIP_UPDATE_CHECK=1   Silence launch-time update notices.
-  IMPEL_SKIP_AGENT_SYNC=1     Keep the last native-agent catalog without refreshing it.
   IMPEL_DISABLE_INSTALL_RECOVERY=1   Disable local and hosted install recovery.
 
 Config file:
@@ -121,6 +103,10 @@ export async function main(argv) {
     case "mcp":
       return cmdMcp(rest);
 
+    // Hidden transport used by managed Claude/Codex lifecycle hooks.
+    case "sessions":
+      return cmdSessions(rest);
+
     case "claude":
     case "codex":
       return cmdLaunch(cmd, rest);
@@ -154,6 +140,8 @@ export async function main(argv) {
     case "agent":
       return cmdAgents(rest);
 
+    // Compatibility shims retained for one release. They can only refuse an
+    // old enable request or restore legacy Impel-owned native mutations.
     case "on":
       return runUse("gateway", rest[0]);
 
@@ -164,7 +152,7 @@ export async function main(argv) {
       const [mode, targetToken] = rest;
       if (mode !== "gateway" && mode !== "account") {
         console.error(`impel use: expected \`gateway\` or \`account\`, got "${mode ?? ""}".`);
-        console.error("  Try `impel use gateway` (alias `impel on`) or `impel use account` (alias `impel off`).");
+        console.error("  Native switching has been removed; use `impel claude` or `impel codex`.");
         process.exitCode = 1;
         return;
       }
@@ -173,14 +161,23 @@ export async function main(argv) {
 
     case "setup":
       // The old per-tool aliases (setup claude|codex-cli|codex-app) flipped
-      // native configs; that swap is no longer part of setup. cmdSetup rejects
-      // positional targets with a pointer to `impel use gateway`.
+      // native configs; that swap is no longer part of setup.
       return cmdSetup(rest);
 
     case "update":
     case "upgrade":
       return cmdUpdate(rest);
 
+    // Hidden continuation executed by the freshly installed CLI build.
+    case "_converge":
+      return cmdConverge(rest);
+
+    // Hidden OS-shell launcher. Setup/update guarantees the app is ready.
+    case "_app-launch": {
+      const [target = "all", ...args] = rest;
+      return cmdApps(["open", target, ...args]);
+    }
+
     // Intentionally omitted from the public help while the contract is gated
     // server-side and limited to Impel-managed desktop apps.
     case "experimental":

package/src/cliProfiles.js

@@ -12,6 +12,7 @@ import { CONFIG_DIR } from "./config.js";
 import { normalizeTenantId } from "./tenants.js";
 import { impelCliInvocation, impelMcpInvocation } from "./selfInvocation.js";
 import { applyImpelClaudeSandbox } from "./claudeSandbox.js";
+import { ensureClaudeSessionHooks, ensureCodexSessionHooks } from "./sessionHooks.js";
 
 export const IMPEL_CLI_PROFILES_DIR = path.join(CONFIG_DIR, "cli");
 
@@ -131,6 +132,7 @@ export function ensureImpelClaudeProfile(gatewayUrl, tenantId, { crossAppModels
 
   writePrivateFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
   writePrivateFile(userConfigPath, `${JSON.stringify(userConfig, null, 2)}\n`);
+  ensureClaudeSessionHooks(configDir, tenantId, "claude_cli");
 
   return { configDir, settingsPath, userConfigPath };
 }
@@ -203,9 +205,10 @@ export function ensureImpelCodexProfile(gatewayUrl, tenantId) {
 
   const { preamble, rest } = splitTomlPreamble(withoutManagedBlock);
   const providerLine = 'model_provider = "impel"';
-  const nextPreamble = CODEX_PROVIDER_LINE_RE.test(preamble)
+  let nextPreamble = CODEX_PROVIDER_LINE_RE.test(preamble)
     ? preamble.replace(CODEX_PROVIDER_LINE_RE, providerLine)
     : `${preamble.trimEnd()}${preamble.trim() ? "\n" : ""}${providerLine}\n`;
+  nextPreamble = nextPreamble.replace(/^bypass_hook_trust[ \t]*=[ \t]*(?:true|false)[ \t]*\n?/gm, "");
   const restText = rest.trim();
   const next = [nextPreamble.trimEnd(), codexManagedBlock(gatewayUrl, tenantId), restText]
     .filter(Boolean)
@@ -213,6 +216,7 @@ export function ensureImpelCodexProfile(gatewayUrl, tenantId) {
     .concat("\n");
 
   writePrivateFile(configPath, hardenManagedCodexToml(next, configPath));
+  ensureCodexSessionHooks(codexHome, tenantId, "codex_cli");
   secureManagedCodexHome(codexHome);
   return { codexHome, configPath };
 }

package/src/commands/apps.js

@@ -265,6 +265,221 @@ function configureWindowsApps(config, targets, vendorPaths, catalog, io) {
   return { catalog, userData };
 }
 
+function explicitTenantAppConfig(baseConfig, tenant, targets) {
+  if (!baseConfig?.pat || !baseConfig?.gatewayUrl) throw new Error("an authenticated Impel config is required");
+  const tenantId = normalizeTenantId(tenant?.id || tenant?.slug);
+  const providers = crossAppModelsEnabled(baseConfig)
+    ? ["claude", "codex"]
+    : targets.map((target) => (target === "claude" ? "claude" : "codex"));
+  assertProviderScopes(baseConfig.scopes, providers, { requireLive: true });
+  return {
+    ...baseConfig,
+    tenantId,
+    tenantName: tenant?.name || tenantId,
+    pat: tenantCredential(baseConfig.pat, tenantId),
+  };
+}
+
+/**
+ * Reconcile one explicit tenant's Windows app profiles without parsing CLI
+ * arguments or changing the globally selected tenant. Shared vendor work is
+ * skipped after the first tenant by passing skipVendor.
+ */
+export async function reconcileWindowsTenantApps({
+  baseConfig,
+  tenant,
+  mode = "update",
+  targets = ["claude", "chatgpt"],
+  skipVendor = false,
+  skipVendorTargets = [],
+  confirmVendorInstall = async () => true,
+  homeDir = os.homedir(),
+  environment = process.env,
+} = {}, overrides = {}) {
+  const io = {
+    findClaudeApp: findWindowsClaudeApp,
+    ensureClaudeApp: ensureWindowsClaudeApp,
+    claudeUserData: windowsClaudeUserData,
+    findChatGPTApp: findWindowsChatGPTApp,
+    ensureChatGPTApp: ensureWindowsChatGPTApp,
+    findManagedChatGPTApp: findManagedWindowsChatGPTApp,
+    stageChatGPTApp: stageWindowsChatGPTApp,
+    chatGPTStageIsCurrent: windowsChatGPTStageIsCurrent,
+    fetchModels: fetchGatewayModels,
+    installFiles: installManagedAppFiles,
+    syncSkills: syncSkillsSafe,
+    syncAgents: syncAgentProfilesSafe,
+    existsSync: fs.existsSync,
+    log: (message) => console.log(message),
+    ...overrides,
+  };
+  const config = explicitTenantAppConfig(baseConfig, tenant, targets);
+  const catalog = await fetchWindowsCatalog(config, io);
+  const actionTargets = selectCatalogAppTargets(targets, catalog.models, config, { log: io.log });
+  const supported = new Set(actionTargets);
+  const unsupported = targets.filter((target) => !supported.has(target));
+  const userData = io.claudeUserData(environment, config.tenantId);
+  const paths = appPaths(homeDir, config.tenantId, { claudeUserData: userData, tenantName: config.tenantName });
+  const vendorPaths = {};
+  const preparedTargets = new Set(skipVendor ? actionTargets : skipVendorTargets);
+
+  for (const target of actionTargets) {
+    const isClaude = target === "claude";
+    const find = isClaude ? io.findClaudeApp : io.findChatGPTApp;
+    const ensure = isClaude ? io.ensureClaudeApp : io.ensureChatGPTApp;
+    let binary = find(environment);
+    if (!preparedTargets.has(target)) {
+      const confirmed = await confirmVendorInstall(target, { platform: "win32", mode });
+      if (!confirmed) {
+        throw new Error(`${isClaude ? "Claude" : "ChatGPT/Codex"} vendor ${mode === "update" ? "update" : "installation"} requires confirmation`);
+      }
+      const vendor = ensure({ update: mode === "update" }, { environment });
+      binary = vendor.binary;
+      if (!binary) {
+        const label = isClaude ? "Claude" : "ChatGPT/Codex";
+        throw new Error(`${label} vendor installation failed (${windowsProcessFailure(vendor.result)})`);
+      }
+    }
+    if (binary) vendorPaths[target] = binary;
+  }
+  if (actionTargets.includes("claude") && !vendorPaths.claude) {
+    throw new Error("Claude vendor app is unavailable");
+  }
+  if (actionTargets.includes("chatgpt")) {
+    let managed = io.findManagedChatGPTApp(paths.root);
+    const stale = vendorPaths.chatgpt && !io.chatGPTStageIsCurrent(vendorPaths.chatgpt, paths.root);
+    if (!managed || stale) {
+      if (!vendorPaths.chatgpt) throw new Error("ChatGPT/Codex vendor app is unavailable");
+      managed = io.stageChatGPTApp(vendorPaths.chatgpt, paths.root);
+    }
+    if (!managed) throw new Error("the managed ChatGPT/Codex app could not be staged");
+  }
+
+  configureWindowsApps(config, actionTargets, vendorPaths, catalog, {
+    ...io,
+    homeDir,
+    environment,
+  });
+  for (const target of actionTargets) {
+    const { client, env, label } = appSkillTarget(target, paths);
+    await io.syncSkills({ client, gatewayUrl: resolveSkillsGateway(config.gatewayUrl), env, label });
+    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,
+  });
+  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")),
+  };
+  if (!Object.values(verification).every(Boolean)) throw new Error("Windows app profile verification failed");
+  return { tenantId: config.tenantId, targets: actionTargets, unsupported, paths, verification };
+}
+
+/** Reconcile one explicit tenant's macOS app bundles and profiles. */
+export async function reconcileMacTenantApps({
+  baseConfig,
+  tenant,
+  mode = "update",
+  targets = ["claude", "chatgpt"],
+  skipVendor = false,
+  skipVendorTargets = [],
+  confirmVendorInstall = async () => true,
+  homeDir = os.homedir(),
+} = {}, overrides = {}) {
+  const io = {
+    status: appStatus,
+    bundleCurrent: bundleIsCurrent,
+    ensureVendor: ensureVendorApp,
+    fetchModels: fetchGatewayModels,
+    quitApps: quitBlockingApps,
+    installFiles: installManagedAppFiles,
+    syncSkills: syncSkillsSafe,
+    syncAgents: syncAgentProfilesSafe,
+    secureCodexHome: secureManagedCodexHome,
+    openLauncher: openManagedLauncher,
+    existsSync: fs.existsSync,
+    log: (message) => console.log(message),
+    ...overrides,
+  };
+  const config = explicitTenantAppConfig(baseConfig, tenant, targets);
+  let catalog;
+  try {
+    catalog = await io.fetchModels(config);
+  } catch (error) {
+    throw new Error(`tenant model catalog is unavailable (${redactSecretText(error?.message || error)}); no Impel app files were changed`);
+  }
+  const actionTargets = selectCatalogAppTargets(targets, catalog.models, config, { log: io.log });
+  const supported = new Set(actionTargets);
+  const unsupported = targets.filter((target) => !supported.has(target));
+  const vendorPaths = {};
+  const statuses = io.status(actionTargets, homeDir, config.tenantId, config.tenantName);
+  for (const status of statuses) vendorPaths[status.target] ||= status.vendorPath;
+  const preparedTargets = new Set(skipVendor ? actionTargets : skipVendorTargets);
+  {
+    for (const target of actionTargets.filter((target) => !preparedTargets.has(target))) {
+      if (vendorPaths[target]) continue;
+      const confirmed = await confirmVendorInstall(target, { platform: "darwin", mode });
+      if (!confirmed) throw new Error(`${target} vendor installation requires confirmation`);
+      const result = await io.ensureVendor(target, { homeDir });
+      vendorPaths[target] = result.path;
+      if (!result.path) throw new Error(`${target} verified vendor app is unavailable; retry the pinned download`);
+    }
+  }
+  const staleTargets = statuses.filter((status) => !io.bundleCurrent(status)).map((status) => status.target);
+  let closedApps = [];
+  if (staleTargets.length) {
+    const result = await io.quitApps(staleTargets, { tenantId: config.tenantId, tenantName: config.tenantName });
+    if (Array.isArray(result)) closedApps = result;
+  }
+  const reopenTargets = new Set(staleTargets.filter((target) => closedApps.includes(
+    managedLauncherName(target, { tenantId: config.tenantId, tenantName: config.tenantName }),
+  )));
+  const installed = await io.installFiles({
+    config,
+    targets: actionTargets,
+    models: catalog.models,
+    homeDir,
+    vendorPaths,
+    writeBundles: staleTargets,
+  });
+  const paths = appPaths(homeDir, config.tenantId, { tenantName: config.tenantName });
+  for (const item of installed) {
+    const { client, env, label } = appSkillTarget(item.target, paths);
+    await io.syncSkills({ client, gatewayUrl: resolveSkillsGateway(config.gatewayUrl), env, label });
+    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,
+  });
+  for (const item of installed) {
+    if (reopenTargets.has(item.target)) io.openLauncher(item.launcher);
+  }
+  const verification = Object.fromEntries(actionTargets.map((target) => [
+    target,
+    io.existsSync(paths[target].launcher) && io.existsSync(
+      target === "claude"
+        ? path.join(paths.claude.userData, "configLibrary", `${CLAUDE_CONFIG_ID}.json`)
+        : path.join(paths.chatgpt.codexHome, "config.toml"),
+    ),
+  ]));
+  if (!Object.values(verification).every(Boolean)) throw new Error("macOS app bundle/profile verification failed");
+  return { tenantId: config.tenantId, targets: actionTargets, unsupported, paths, verification, installed };
+}
+
+export function reconcileTenantApps(options = {}, overrides = {}) {
+  const platform = options.platform || process.platform;
+  if (platform === "win32") return reconcileWindowsTenantApps(options, overrides);
+  if (platform === "darwin") return reconcileMacTenantApps(options, overrides);
+  return Promise.resolve({ tenantId: options.tenant?.id, targets: [], unsupported: ["claude", "chatgpt"], paths: null, verification: {} });
+}
+
 export async function cmdWindowsApps(argv, overrides = {}) {
   const [action = "status", rawTarget, ...rest] = argv;
   const targetToken = rawTarget?.startsWith("--") ? undefined : rawTarget;

package/src/commands/converge.js

@@ -0,0 +1,174 @@
+// Hidden fresh-build continuation used by `impel update`.
+
+import { loadConfig, saveConfig, redactSecretText } from "../config.js";
+import { runInstallRecovery } from "../installRecovery/engine.js";
+import { printReconciliationSummary, reconcileAllTenants, selectDefaultTenant } from "../provisioning.js";
+import { fetchTenants } from "../tenants.js";
+import { promptText } from "../prompt.js";
+import { restoreNativeProfiles } from "./use.js";
+
+function confirmed(answer) {
+  return /^(?:y|yes)$/iu.test(String(answer || "").trim());
+}
+
+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);
+  report.passed = report.tenants.every((tenant) => (
+    ["ready", "unavailable"].includes(tenant.cli)
+    && ["ready", "unavailable"].includes(tenant.apps)
+    && ["ready", "unavailable"].includes(tenant.shell)
+  ));
+  return report;
+}
+
+export async function cmdConverge(argv = [], overrides = {}) {
+  const skipApps = argv.includes("--skip-apps");
+  const noRecovery = argv.includes("--no-recovery");
+  const io = {
+    loadConfig,
+    saveConfig,
+    fetchTenants,
+    reconcile: reconcileAllTenants,
+    recoverInstall: runInstallRecovery,
+    restoreNativeProfiles,
+    promptText,
+    isTTY: process.stdin.isTTY,
+    platform: process.platform,
+    environment: process.env,
+    ...overrides,
+  };
+  const config = io.loadConfig();
+  if (!config?.pat) {
+    console.error("impel update: not authenticated; run `impel setup` first.");
+    process.exitCode = 1;
+    return false;
+  }
+  let listing;
+  try {
+    listing = await io.fetchTenants(config);
+  } catch (error) {
+    console.error(`impel update: tenant discovery failed (${redactSecretText(error?.message || error)})`);
+    process.exitCode = 1;
+    return false;
+  }
+  const selected = selectDefaultTenant(listing, { currentTenantId: config.tenantId });
+  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);
+  try {
+    io.restoreNativeProfiles({ quiet: true });
+  } catch (error) {
+    console.warn(`Legacy native-profile cleanup was skipped safely (${redactSecretText(error?.message || error)}).`);
+  }
+
+  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 allowed = confirmed(await io.promptText(
+      `Allow the verified ${label} vendor ${context.mode === "update" ? "update" : "installation"}? [y/N] `,
+    ));
+    vendorAppDecisions.set(target, allowed);
+    return allowed;
+  };
+
+  const run = (
+    tenants = listing.tenants,
+    includeApps = !skipApps,
+    confirmInstall = confirmVendorInstall,
+  ) => io.reconcile({
+    config,
+    listing: { ...listing, tenants },
+    mode: "update",
+    includeApps,
+    platform: io.platform,
+    environment: io.environment,
+    confirmVendorInstall: confirmInstall,
+  }, overrides.reconcileOverrides || {});
+  let report = await run();
+  if (!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;
+      let retryReport = null;
+      let retryPassed = false;
+      const retryTenant = async (confirmInstall) => {
+        retryReport = await run([tenant], !skipApps, confirmInstall);
+        retryPassed = retryReport.passed;
+        return retryPassed;
+      };
+      const retrySafeState = async () => {
+        const profileReport = await run([tenant], false, 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: "update.tenant_convergence",
+          message: failed.errors.join("; ") || "Tenant update verification failed.",
+          diagnostics: { tenant: tenant.id },
+        },
+        config,
+        goals: [{
+          id: `tenant-${tenant.id}-ready`,
+          description: `Tenant ${tenant.id} is upgraded and locally verified`,
+          run: () => retryPassed,
+        }],
+        explicit: true,
+        noRecovery: false,
+        actionContext: {
+          tenantId: tenant.id,
+          repairProfiles: async () => {
+            const profileReport = await run([tenant], false, async () => false);
+            return ["ready", "unavailable"].includes(profileReport.tenants[0]?.cli);
+          },
+          retryStep: () => retrySafeState(),
+          installVendorApp: (target) => retryTenant(async (product) => (
+            target === "all"
+            || product === target
+            || (target === "codex" && product === "chatgpt")
+          )),
+        },
+      }, overrides.recoveryOverrides || {});
+      if (retryReport) mergeTenantReport(report, retryReport);
+    }
+  }
+  printReconciliationSummary(report);
+  console.log(`CLI tenant: ${selected.id} (change with \`impel tenant use <tenant>\`)`);
+  if (!report.passed) {
+    console.error("impel update: one or more tenant surfaces remain incomplete.");
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}