impel-cli 0.11.1 → 0.12.0

package/README.md

@@ -152,7 +152,9 @@ impel agents sync [claude|codex|all]         Sync explicit tenant agents into na
 
 impel status                                 Launcher readiness + native mode + gateway reachability
 impel app install [target] [--tenant <org>]  Install isolated apps for one tenant
-impel app update [target] [--tenant <org>]   Refresh that tenant's apps, configs, and models
+impel app update [target] [--tenant <org>] [--force]
+                                             Refresh configs/models and rebuild only stale bundles;
+                                             --force performs a clean full rebuild
 impel app refresh [target] [--tenant <org>]  Configs/catalog/skills/agents only; safe while apps run
                                              (--stale-only: no-op unless 6h+ since last sync)
 impel app status [target] [--tenant <org>]   Show tenant launcher/vendor status
@@ -237,9 +239,10 @@ before running another protected command.
 One command brings everything current, in dependency order: the CLI itself
 (`npm install -g impel-cli@latest` from npm, with no GitHub credentials),
 then — re-executing the freshly installed build — `impel app update all`
-(close running apps, install the CLI-pinned vendor builds, rebuild the vendored Impel apps)
+(install the CLI-pinned vendor builds and rebuild only stale vendored Impel apps)
 followed by `impel skills sync all` and `impel agents sync all` across every
-managed profile.
+managed profile. The app cascade skips its own skills/agents pass so those
+profiles are synced once, in the dedicated bounded-concurrency steps.
 
 Update discovery compares the installed package version with npm's public
 `latest` metadata, cached for 6 hours in
@@ -608,6 +611,12 @@ MCP subprocess definition so they also work in isolated desktop profiles. They
 never contain the PAT; the subprocess reads it from Impel's owner-only config
 when invoked.
 
+Visible agent names come from the registry title. Codex keeps that title as the
+custom-agent name; Claude uses the lowercase, hyphenated form required by its
+native agent schema. The generated filenames remain stable tenant-and-agent
+identifiers so title changes update in place without colliding with user files.
+Duplicate or built-in-reserved titles receive a deterministic disambiguator.
+
 The sync writes atomically and records a manifest beside the generated files.
 It removes only stale filenames from that manifest, so user-authored agents are
 never deleted. Automatic refreshes are best-effort and retain the last good
@@ -623,13 +632,13 @@ Invocation uses the clients' native agent behavior:
 
 ```text
 # Claude Code / Claude Desktop Code tab: guaranteed explicit selection
-@agent-impel-acme-research-agent investigate the dependency change
+@agent-research-agent investigate the dependency change
 
 # Claude blocking CLI
-claude --agent impel-acme-research-agent -p "investigate the dependency change"
+claude --agent research-agent -p "investigate the dependency change"
 
 # Codex CLI / ChatGPT desktop Codex task
-Explicitly use the configured impel-acme-research-agent for this request and wait for it.
+Explicitly use the configured Research Agent for this request and wait for it.
 ```
 
 Claude exposes native custom agents in its `@` typeahead. Current Codex releases
@@ -698,13 +707,17 @@ a stable, unique bundle identifier and gateway configuration:
 - Impel Claude is an APFS-cloned vendored copy of the official app with its own
   bundle and helper identities. Its LaunchServices environment sets the
   vendor-supported `CLAUDE_USER_DATA_DIR` and writes the 3P gateway
-  `configLibrary` below `~/.config/impel/apps/tenants/<org>/claude`. A narrowly
-  version-checked compatibility patch connects Claude's native plan-usage meter
-  to the authenticated aggregate Claude subscription pool exposed by the Impel
-  gateway.
+  `configLibrary` below `~/.config/impel/apps/tenants/<org>/claude`. A new
+  isolated profile defaults to the Code app while preserving any app selection
+  the user makes afterward. A narrowly version-checked compatibility patch
+  connects Claude's native plan-usage meter to the authenticated aggregate
+  Claude subscription pool exposed by the Impel gateway.
 - Impel ChatGPT wraps an APFS-cloned official app while preserving the nested
-  OpenAI-signed bundle and executable. Its outer resource root contains the
-  narrowly patched renderer ASAR used at runtime. The wrapper sets `CODEX_HOME`,
+  OpenAI-signed bundle and executable. A wrapper-owned startup preload pins
+  Electron's application name before the native menu is created, so macOS
+  shows `Impel ChatGPT (<org>)` without changing OpenAI's signed code. Its outer
+  resource root contains the narrowly patched renderer ASAR used at runtime.
+  The wrapper sets `CODEX_HOME`,
   passes a separate Chromium `--user-data-dir`, and writes its provider config
   and model catalog below `~/.config/impel/apps/tenants/<org>/chatgpt`. It also supplies a
   process-scoped, Codex-compatible wrapper around the Impel PAT so native
@@ -728,6 +741,14 @@ Updates and uninstalls touch only the named tenant variant. The older global
 `Impel Claude.app` / `Impel ChatGPT.app` launcher is removed after the first
 successful tenant-specific rebuild.
 
+`impel app update` compares the installed bundle's CLI version, pinned vendor
+version, identity, profile paths, and ASAR compatibility hash before touching
+it. A current bundle is not closed, cloned, patched, or codesigned; its config
+and model catalog are still refreshed. If an interrupted update left a machine
+in a bad state, `impel app update --force` removes the selected launcher and
+performs a clean rebuild while sweeping abandoned `.tmp-*` and `.previous-*`
+staging directories.
+
 The official Claude and ChatGPT apps remain separate installations and keep
 their normal accounts, updater, profiles, and bundle identities. Each CLI
 release pins exact, tested vendor builds (v0.10.0 pins Claude `1.20186.9` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Configure Claude Code and Codex CLI to talk to Impel's gateway, authenticated by an Impel Personal Access Token",
   "type": "module",
   "bin": {

package/src/agents.js

@@ -29,6 +29,10 @@ const NATIVE_AGENT_TOOL_NAMES = [
 const SAFE_AGENT_ID_RE = /^[A-Za-z0-9_.:-]{1,160}$/u;
 const SAFE_SCOPE_PARAM_RE = /^[A-Za-z0-9_.:-]{1,160}$/u;
 const MAX_CATALOG_ITEMS = 500;
+const RESERVED_AGENT_NAMES = Object.freeze({
+  claude: new Set(["explore", "general-purpose", "plan"]),
+  codex: new Set(["default", "explorer", "worker"]),
+});
 
 function privateDirectory(directory) {
   if (fs.existsSync(directory) && fs.lstatSync(directory).isSymbolicLink()) {
@@ -262,29 +266,58 @@ export async function fetchNativeAgentCatalog({
   );
 }
 
-function slug(value) {
+function slug(value, fallback = "agent") {
   return String(value)
     .toLowerCase()
     .replace(/[^a-z0-9]+/gu, "-")
     .replace(/^-+|-+$/gu, "")
-    .slice(0, 48) || "agent";
+    .slice(0, 48) || fallback;
 }
 
-function generatedAgentNames(tenantId, agents) {
+function agentBindingHash(agent) {
+  return crypto.createHash("sha256")
+    .update(`${agent.scopeParam}:${agent.agentId}`)
+    .digest("hex")
+    .slice(0, 8);
+}
+
+function generatedAgentFileStems(tenantId, agents) {
   const used = new Map();
   return agents.map((agent) => {
     const base = `impel-${slug(tenantId)}-${slug(agent.agentId)}`.slice(0, 63).replace(/-+$/u, "");
     const previous = used.get(base);
     used.set(base, (previous || 0) + 1);
     if (!previous) return base;
-    const suffix = crypto.createHash("sha256")
-      .update(`${agent.scopeParam}:${agent.agentId}`)
-      .digest("hex")
-      .slice(0, 8);
+    const suffix = agentBindingHash(agent);
     return `${base.slice(0, 54)}-${suffix}`;
   });
 }
 
+function generatedClientAgentNames(client, agents) {
+  const claudeNames = agents.map((agent) => slug(agent.title, slug(agent.agentId)));
+  const collisionKeys = agents.map((agent, index) => client === "claude"
+    ? claudeNames[index]
+    : slug(agent.title, agent.title.normalize("NFKC").toLocaleLowerCase("en-US")));
+  const collisionKeyCounts = collisionKeys.reduce((counts, key) => {
+    counts.set(key, (counts.get(key) || 0) + 1);
+    return counts;
+  }, new Map());
+
+  return agents.map((agent, index) => {
+    const visualKey = claudeNames[index];
+    const duplicate = collisionKeyCounts.get(collisionKeys[index]) > 1;
+    const reserved = RESERVED_AGENT_NAMES[client].has(visualKey);
+    if (client === "claude") {
+      const base = reserved ? `impel-${visualKey}` : visualKey;
+      if (duplicate) return `${base.slice(0, 54)}-${agentBindingHash(agent)}`;
+      return base;
+    }
+    const base = reserved ? `Impel ${agent.title}` : agent.title;
+    if (duplicate) return `${base} (${agentBindingHash(agent)})`;
+    return base;
+  });
+}
+
 function adapterInstructions(tenantId, agent) {
   const toolName = nativeToolName;
   const contextRequirement = agent.requiredContext.length
@@ -360,14 +393,15 @@ function renderCodexAgent({ tenantId, agent, name, invocation }) {
 export function renderManagedAgents(client, tenantId, agents, invocation = impelMcpInvocation(["--tenant", tenantId])) {
   if (client !== "claude" && client !== "codex") throw new Error(`unknown agent client ${client}`);
   const normalizedTenant = normalizeTenantId(tenantId);
-  const names = generatedAgentNames(normalizedTenant, agents);
+  const fileStems = generatedAgentFileStems(normalizedTenant, agents);
+  const names = generatedClientAgentNames(client, agents);
   return agents.map((agent, index) => {
     const name = names[index];
     const extension = client === "claude" ? ".md" : ".toml";
     const contents = client === "claude"
       ? renderClaudeAgent({ tenantId: normalizedTenant, agent, name, invocation })
       : renderCodexAgent({ tenantId: normalizedTenant, agent, name, invocation });
-    return { agentId: agent.agentId, name, fileName: `${name}${extension}`, contents };
+    return { agentId: agent.agentId, name, fileName: `${fileStems[index]}${extension}`, contents };
   });
 }
 

package/src/apps.js

@@ -142,7 +142,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 = 9;
+export const CURRENT_CONFIG_VERSION = 10;
 
 /** Parse the tenant's install manifest, or null when absent/corrupt. */
 export function readTenantManifest(homeDir = os.homedir(), tenantId = null) {
@@ -193,6 +193,7 @@ export function bundleIsCurrent(status) {
       compatibility.vendorSignaturesPreserved === true
       && compatibility.resourceRoot === CHATGPT_RESOURCE_ROOT
       && compatibility.patches?.fastModeForGatewayAuth > 0
+      && compatibility.patches?.tenantDisplayNamePreload === 1
     )),
   );
 }
@@ -378,7 +379,10 @@ export function installManagedAppFiles({
 
   const installed = [];
   for (const target of targets) {
-    if (target === "claude") writeClaudeConfig(paths, config, models);
+    if (target === "claude") {
+      writeClaudeDefaultApp(paths);
+      writeClaudeConfig(paths, config, models);
+    }
     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
@@ -549,6 +553,7 @@ function installPinnedVendorApp(target, homeDir) {
       homeDir, ".config", "impel", "vendor", target, pin.version, pin.bundleName,
     );
     fs.mkdirSync(path.dirname(destination), { recursive: true });
+    sweepStaleBundleArtifacts(path.dirname(destination), path.basename(destination));
     replaceDirectory(destination, extractedApp);
     return destination;
   } finally {
@@ -645,6 +650,33 @@ function writeClaudeConfig(paths, config, models) {
   }, null, 2) + "\n", 0o600);
 }
 
+function writeClaudeDefaultApp(paths) {
+  const configPath = path.join(paths.claude.userData, "claude_desktop_config.json");
+  let current = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      current = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    } catch {
+      throw new Error(`Claude desktop config is not valid JSON: ${configPath}`);
+    }
+  }
+  if (!current || typeof current !== "object" || Array.isArray(current)) {
+    throw new Error(`Claude desktop config must contain a JSON object: ${configPath}`);
+  }
+  const preferences = current.preferences ?? {};
+  if (!preferences || typeof preferences !== "object" || Array.isArray(preferences)) {
+    throw new Error(`Claude desktop preferences must contain a JSON object: ${configPath}`);
+  }
+  // Claude persists the selected top-level app as `preferences.sidebarMode`.
+  // Seed Code for a new isolated profile, then leave subsequent user choices
+  // alone during install, update, and background config refreshes.
+  if (Object.hasOwn(preferences, "sidebarMode")) return;
+  writeAtomic(configPath, JSON.stringify({
+    ...current,
+    preferences: { ...preferences, sidebarMode: "code" },
+  }, null, 2) + "\n", 0o600);
+}
+
 function writeChatGPTConfig(paths, config, models, vendorCodexModels, invocations = null) {
   const experimental = crossAppModelsEnabled(config);
   const orderedModels = experimental
@@ -940,6 +972,7 @@ function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl) {
 
   const bundle = paths.claude.launcher;
   const staging = `${bundle}.tmp-${process.pid}`;
+  sweepStaleBundleArtifacts(path.dirname(bundle), path.basename(bundle));
   fs.rmSync(staging, { recursive: true, force: true });
   cloneAppBundle(vendorPath, staging);
   try {
@@ -1026,6 +1059,7 @@ function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl) {
   const staging = `${bundle}.tmp-${process.pid}`;
   const vendorBundleName = path.basename(vendorPath);
   const vendorBundle = path.join(staging, "Contents", "Resources", vendorBundleName);
+  sweepStaleBundleArtifacts(path.dirname(bundle), path.basename(bundle));
   fs.rmSync(staging, { recursive: true, force: true });
   cloneAppBundle(vendorPath, vendorBundle);
   try {
@@ -1060,6 +1094,11 @@ function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl) {
       vendoredChatGPTLauncher(paths, vendorBundleName, executableName, gatewayUrl),
       0o755,
     );
+    writeAtomic(
+      path.join(staging, "Contents", "Resources", "impel-chatgpt-preload.cjs"),
+      vendoredChatGPTDisplayNamePreload(),
+      0o644,
+    );
     writeAtomic(path.join(staging, "Contents", "Resources", "impel-compatibility.json"), JSON.stringify({
       schemaVersion: 2,
       cliVersion: CLI_VERSION,
@@ -1070,7 +1109,11 @@ function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl) {
       profileRoot: paths.chatgpt.root,
       codexHome: paths.chatgpt.codexHome,
       browserData: paths.chatgpt.browserData,
-      patches: { fastModeForGatewayAuth: fastModePatchCount, desktopAPIForGatewayAuth: 0 },
+      patches: {
+        fastModeForGatewayAuth: fastModePatchCount,
+        desktopAPIForGatewayAuth: 0,
+        tenantDisplayNamePreload: 1,
+      },
       vendorSignaturesPreserved: true,
       resourceRoot: CHATGPT_RESOURCE_ROOT,
       asarHeaderSha256: asarHash,
@@ -1384,14 +1427,138 @@ unset TOKEN
 secure_codex_home
 BROWSER_DATA=${shellQuote(paths.chatgpt.browserData)}
 mkdir -p "$BROWSER_DATA"
-# Electron resolves resources from the Impel wrapper when a nested app is
-# executed directly. The wrapper exposes the vendor resource tree there, so
-# app.asar and companion binaries resolve without LaunchServices handing the
-# process to the separately running, identically identified vendor app.
+export IMPEL_APP_DISPLAY_NAME=${shellQuote(paths.chatgpt.displayName)}
+PRELOAD="$HERE/../Resources/impel-chatgpt-preload.cjs"
+export NODE_OPTIONS="--require=\\\"$PRELOAD\\\""
+# Electron resolves resources from the Impel wrapper when the nested app is
+# executed directly. The wrapper exposes the vendor resource tree there while
+# preserving the nested OpenAI-signed executable and bundle. The startup
+# preload pins Electron's application name before its native menu is created.
 exec "$VENDOR_APP/Contents/MacOS/${executableName}" --user-data-dir="$BROWSER_DATA" "$@"
 `;
 }
 
+function vendoredChatGPTDisplayNamePreload() {
+  return `"use strict";
+
+const displayName = process.env.IMPEL_APP_DISPLAY_NAME;
+if (process.type === "browser" && displayName) {
+  const Module = require("node:module");
+  const path = require("node:path");
+  const load = Module._load;
+  let objc;
+  let appKit;
+  let launchServicesNamed = false;
+  let activationPolicyRefreshed = false;
+
+  const loadNativeBridge = () => {
+    objc ||= require(path.join(
+      process.resourcesPath,
+      "app.asar.unpacked/node_modules/objc-js/dist/index.js",
+    ));
+    appKit ||= new objc.NobjcLibrary("/System/Library/Frameworks/AppKit.framework/AppKit");
+    return { objc, appKit };
+  };
+
+  const setLaunchServicesApplicationName = () => {
+    if (launchServicesNamed) return;
+    try {
+      const native = loadNativeBridge();
+      new native.objc.NobjcLibrary(
+        "/System/Library/Frameworks/ApplicationServices.framework/Versions/A/ApplicationServices",
+      );
+      const title = native.appKit.NSString.stringWithUTF8String$(displayName);
+      const info = native.appKit.NSMutableDictionary.dictionaryWithDictionary$(
+        native.appKit.NSBundle.mainBundle().infoDictionary(),
+      );
+      for (const key of ["CFBundleName", "CFBundleDisplayName"]) {
+        info.setObject$forKey$(title, native.appKit.NSString.stringWithUTF8String$(key));
+      }
+      native.objc.callFunction(
+        "_LSSetApplicationLaunchServicesServerConnectionStatus",
+        { returns: "v", args: ["Q", "@"] },
+        0,
+        null,
+      );
+      const checked = native.objc.callFunction(
+        "_LSApplicationCheckIn",
+        { returns: "@", args: ["i", "@"] },
+        -2,
+        info,
+      );
+      const asn = native.objc.callFunction("_LSGetCurrentApplicationASN", { returns: "@" });
+      if (!checked || !asn) return;
+      const status = native.objc.callFunction(
+        "_LSSetApplicationInformationItem",
+        { returns: "i", args: ["i", "@", "@", "@", "@"] },
+        -2,
+        asn,
+        native.appKit.NSString.stringWithUTF8String$("LSDisplayName"),
+        title,
+        null,
+      );
+      launchServicesNamed = status === 0;
+    } catch {
+      // Keep the signed vendor app usable if LaunchServices changes this
+      // private-but-established process-title API in a future macOS release.
+    }
+  };
+
+  const setNativeApplicationMenuTitle = () => {
+    try {
+      const native = loadNativeBridge();
+      const title = native.appKit.NSString.stringWithUTF8String$(displayName);
+      native.appKit.NSProcessInfo.processInfo().setProcessName$(title);
+      const application = native.appKit.NSApplication.sharedApplication();
+      application.setAccessibilityTitle$(title);
+      const menu = application.mainMenu();
+      if (menu && menu.numberOfItems() > 0) {
+        const item = menu.itemAtIndex$(0);
+        item.setTitle$(title);
+        item.setAccessibilityTitle$(title);
+        item.setAccessibilityLabel$(title);
+      }
+    } catch {
+      // The OpenAI-signed native bridge is version-specific. Leave the app
+      // usable if a future vendor build removes it; compatibility metadata
+      // will force the next CLI version to rebuild the wrapper.
+    }
+  };
+
+  Module._load = function (request) {
+    const loaded = load.apply(this, arguments);
+    if (request === "electron" && loaded?.app) {
+      Module._load = load;
+      const setName = loaded.app.setName.bind(loaded.app);
+      setName(displayName);
+      loaded.app.setName = () => setName(displayName);
+      setLaunchServicesApplicationName();
+      setNativeApplicationMenuTitle();
+      const setApplicationMenu = loaded.Menu.setApplicationMenu.bind(loaded.Menu);
+      loaded.Menu.setApplicationMenu = (menu) => {
+        const result = setApplicationMenu(menu);
+        setNativeApplicationMenuTitle();
+        if (!activationPolicyRefreshed) {
+          activationPolicyRefreshed = true;
+          loaded.app.setActivationPolicy("accessory");
+          setTimeout(() => {
+            loaded.app.setActivationPolicy("regular");
+            launchServicesNamed = false;
+            setLaunchServicesApplicationName();
+            setApplicationMenu(menu);
+            setNativeApplicationMenuTitle();
+          }, 0);
+        }
+        setTimeout(setNativeApplicationMenuTitle, 0);
+        return result;
+      };
+    }
+    return loaded;
+  };
+}
+`;
+}
+
 function signVendoredApp(bundle, vendorExecutable, label) {
   if (process.platform !== "darwin" || !isMachO(vendorExecutable)) return;
   spawnSync("/usr/bin/xattr", ["-dr", "com.apple.quarantine", bundle], { stdio: "ignore" });
@@ -1519,6 +1686,22 @@ function sha256(contents) {
   return crypto.createHash("sha256").update(contents).digest("hex");
 }
 
+export function sweepStaleBundleArtifacts(dir, baseName) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+  const prefixes = [`${baseName}.tmp-`, `${baseName}.previous-`];
+  const removed = entries.filter((entry) => prefixes.some((prefix) => entry.startsWith(prefix)));
+  for (const entry of removed) {
+    fs.rmSync(path.join(dir, entry), { recursive: true, force: true });
+  }
+  return removed;
+}
+
 function replaceDirectory(destination, staging) {
   const backup = `${destination}.previous-${process.pid}`;
   fs.rmSync(backup, { recursive: true, force: true });

package/src/cli.js

@@ -49,7 +49,8 @@ Manage:
 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 vendor apps and managed profiles
+  impel app update [target] [--tenant <org>]  Update profiles; rebuild only stale bundles
+                                              (--force performs a clean full 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]

package/src/commands/apps.js

@@ -40,6 +40,7 @@ import { resolveSkillsGateway, syncSkillsSafe } from "../skills.js";
 import { syncAgentProfilesSafe } from "../agents.js";
 import { secureManagedCodexHome } from "../codexSecurity.js";
 import { impelCliInvocation } from "../selfInvocation.js";
+import { withProgress } from "../progress.js";
 import {
   ensureWindowsClaudeApp,
   ensureWindowsChatGPTApp,
@@ -85,6 +86,20 @@ function windowsProcessFailure(result) {
   return "no exit status";
 }
 
+export function openManagedLauncher(launcher, {
+  spawn = spawnSync,
+  reportError = console.error,
+} = {}) {
+  const result = spawn("/usr/bin/open", ["-n", launcher], { encoding: "utf8" });
+  if (!result?.error && result?.status === 0) return true;
+  const detail = result?.error?.message
+    || String(result?.stderr || "").trim()
+    || (Number.isInteger(result?.status) ? `exit code ${result.status}` : "no exit status");
+  reportError(`impel app: could not open ${launcher}: ${redactSecretText(detail)}`);
+  process.exitCode = 1;
+  return false;
+}
+
 async function fetchWindowsCatalog(config, io) {
   try {
     return await io.fetchModels(config);
@@ -123,8 +138,11 @@ export async function cmdWindowsApps(argv, overrides = {}) {
   const flagArgs = rawTarget?.startsWith("--") ? [rawTarget, ...rest] : rest;
   const { flags } = parseFlags(flagArgs, {
     "skip-vendor": { type: "boolean" },
+    "skip-skills": { type: "boolean" },
+    "skip-agents": { type: "boolean" },
     "keep-data": { type: "boolean" },
     "stale-only": { type: "boolean" },
+    force: { type: "boolean" },
     tenant: { type: "string" },
   });
   const io = {
@@ -253,7 +271,9 @@ export async function cmdWindowsApps(argv, overrides = {}) {
     if (targets.includes("claude") && action !== "refresh" && !vendorPaths.claude) {
       throw new Error("Claude vendor app is unavailable; run `impel app install claude` or install it from https://claude.com/download");
     }
-    const catalog = await fetchWindowsCatalog(config, io);
+    const catalog = await withProgress("Fetching the tenant model catalog", () => (
+      fetchWindowsCatalog(config, io)
+    ));
     let managedChatGPT = targets.includes("chatgpt")
       ? io.findManagedChatGPTApp(actionPaths.root)
       : null;
@@ -283,15 +303,21 @@ export async function cmdWindowsApps(argv, overrides = {}) {
         const profile = target === "claude" ? tenantPaths.claude.userData : tenantPaths.chatgpt.root;
         console.log(`${verb} Impel ${target === "claude" ? "Claude" : "ChatGPT"} profile at ${profile}`);
         const { client, env, label } = appSkillTarget(target, tenantPaths);
-        await io.syncSkills({ client, gatewayUrl: resolveSkillsGateway(config.gatewayUrl), env, label });
+        if (!flags["skip-skills"]) {
+          await withProgress(`Syncing skills for ${label}`, () => (
+            io.syncSkills({ client, gatewayUrl: resolveSkillsGateway(config.gatewayUrl), env, label })
+          ));
+        }
         if (target === "chatgpt") secureManagedCodexHome(tenantPaths.chatgpt.codexHome);
       }
-      await io.syncAgents({
-        profiles: targets.map((target) => appAgentProfile(target, tenantPaths)),
-        gatewayUrl: config.gatewayUrl,
-        credential: config.pat,
-        tenantId: config.tenantId,
-      });
+      if (!flags["skip-agents"]) {
+        await withProgress("Syncing app agent profiles", () => io.syncAgents({
+          profiles: targets.map((target) => appAgentProfile(target, tenantPaths)),
+          gatewayUrl: config.gatewayUrl,
+          credential: config.pat,
+          tenantId: config.tenantId,
+        }));
+      }
       console.log(`Models: ${catalog.models.length} from ${catalog.source}. The signed vendor apps and their normal profiles were not changed.`);
     }
     if (action === "open") {
@@ -320,8 +346,9 @@ export async function cmdWindowsApps(argv, overrides = {}) {
 }
 
 export async function cmdApps(argv, overrides = {}) {
-  if (process.platform === "win32") return cmdWindowsApps(argv, overrides);
-  if (process.platform !== "darwin") {
+  const platform = overrides.platform || process.platform;
+  if (platform === "win32") return cmdWindowsApps(argv, overrides);
+  if (platform !== "darwin") {
     console.error("impel app: isolated Impel desktop apps are unavailable on this platform.");
     process.exitCode = 1;
     return;
@@ -332,8 +359,11 @@ export async function cmdApps(argv, overrides = {}) {
   const flagArgs = targetToken?.startsWith("--") ? [targetToken, ...rest] : rest;
   const { flags } = parseFlags(flagArgs, {
     "skip-vendor": { type: "boolean" },
+    "skip-skills": { type: "boolean" },
+    "skip-agents": { type: "boolean" },
     "keep-data": { type: "boolean" },
     "stale-only": { type: "boolean" },
+    force: { type: "boolean" },
     tenant: { type: "string" },
   });
 
@@ -382,7 +412,7 @@ export async function cmdApps(argv, overrides = {}) {
     if (fastLaunchers) {
       spawnDetachedAppRefresh(tenantId);
       for (const launcher of fastLaunchers) {
-        spawnSync("/usr/bin/open", ["-n", launcher], { stdio: "inherit" });
+        openManagedLauncher(launcher);
       }
       return;
     }
@@ -401,55 +431,109 @@ export async function cmdApps(argv, overrides = {}) {
     throw new Error(`unknown app action "${action}"; use install, update, refresh, status, open, or uninstall`);
   }
 
-  const config = await selectedAppConfig(targets, flags.tenant || null);
+  const io = {
+    homeDir: os.homedir(),
+    selectedConfig: selectedAppConfig,
+    status: appStatus,
+    bundleCurrent: bundleIsCurrent,
+    ensureVendor: ensureVendorApp,
+    fetchModels: fetchGatewayModels,
+    quitApps: quitBlockingApps,
+    installFiles: installManagedAppFiles,
+    syncSkills: syncSkillsSafe,
+    syncAgents: syncAgentProfilesSafe,
+    secureCodexHome: secureManagedCodexHome,
+    removeLauncher: (launcher) => fs.rmSync(launcher, { recursive: true, force: true }),
+    log: (message) => console.log(message),
+    ...overrides,
+  };
+  const config = await io.selectedConfig(targets, flags.tenant || null);
   console.log(`Tenant: ${config.tenantId} (desktop history is isolated per tenant).`);
 
-  // A running vendor or Impel app makes the pinned vendor install / bundle swap fail.
-  await quitBlockingApps(targets, {
-    tenantId: config.tenantId,
-    tenantName: config.tenantName,
-  });
-
   const vendorPaths = {};
   if (!flags["skip-vendor"]) {
     for (const target of targets) {
       // Reuse or install only the exact vendor build verified by this CLI.
       // Moving "latest" releases are never cloned into a managed bundle.
-      const result = ensureVendorApp(target);
+      const result = await withProgress(`Preparing the verified ${target} vendor app`, () => (
+        io.ensureVendor(target, { homeDir: io.homeDir })
+      ));
       vendorPaths[target] = result.path;
-      console.log(`${target}: vendor app ${result.action}${result.note ? ` (${result.note})` : ""}`);
+      io.log(`${target}: vendor app ${result.action}${result.note ? ` (${result.note})` : ""}`);
       if (!result.path) throw new Error(`${target} verified vendor app is unavailable; retry the pinned download`);
     }
   }
 
+  const statuses = io.status(
+    targets,
+    io.homeDir,
+    config.tenantId,
+    config.tenantName,
+  );
+  for (const status of statuses) vendorPaths[status.target] ||= status.vendorPath;
+  const force = Boolean(flags.force);
+  const staleBundleTargets = force
+    ? [...targets]
+    : statuses.filter((status) => !io.bundleCurrent(status)).map((status) => status.target);
+
   let catalog;
   try {
-    catalog = await fetchGatewayModels(config);
+    catalog = await withProgress("Fetching the tenant model catalog", () => io.fetchModels(config));
   } catch (error) {
     throw new Error(
       `tenant model catalog is unavailable (${redactSecretText(error.message)}); no Impel app files were changed`,
     );
   }
-  const installed = installManagedAppFiles({ config, targets, models: catalog.models, homeDir: os.homedir(), vendorPaths });
-  for (const item of installed) console.log(`${action === "install" ? "Installed" : "Updated"} ${item.launcher}`);
+
+  // A running vendor or Impel app only needs to close when its bundle will be swapped.
+  if (staleBundleTargets.length > 0) {
+    await io.quitApps(staleBundleTargets, {
+      tenantId: config.tenantId,
+      tenantName: config.tenantName,
+    });
+  }
+  if (force) {
+    for (const status of statuses) io.removeLauncher(status.launcher);
+  }
+  const installed = await withProgress(
+    staleBundleTargets.length > 0 ? "Rebuilding managed app bundles" : "Updating managed app profiles",
+    () => io.installFiles({
+      config,
+      targets,
+      models: catalog.models,
+      homeDir: io.homeDir,
+      vendorPaths,
+      writeBundles: staleBundleTargets,
+    }),
+  );
+  const rebuilt = new Set(staleBundleTargets);
+  for (const item of installed) {
+    const verb = action === "install" ? "Installed" : "Updated";
+    io.log(`${verb} ${item.launcher}${rebuilt.has(item.target) ? "" : " (bundle already current)"}`);
+  }
   console.log(`Models: ${catalog.models.length} from ${catalog.source}. Normal ~/.claude and ~/.codex profiles were not changed.`);
 
   // Best-effort: sync the Bifrost shared skills into each installed isolated app
   // profile. Never fails the install/update.
-  const paths = appPaths(os.homedir(), config.tenantId, { tenantName: config.tenantName });
+  const paths = appPaths(io.homeDir, config.tenantId, { tenantName: config.tenantName });
   const gatewayUrl = resolveSkillsGateway(config.gatewayUrl);
   for (const item of installed) {
     const { client, env, label } = appSkillTarget(item.target, paths);
-    await syncSkillsSafe({ client, gatewayUrl, env, label });
-    if (item.target === "chatgpt") secureManagedCodexHome(paths.chatgpt.codexHome);
+    if (!flags["skip-skills"]) {
+      await withProgress(`Syncing skills for ${label}`, () => (
+        io.syncSkills({ client, gatewayUrl, env, label })
+      ));
+    }
+    if (item.target === "chatgpt") io.secureCodexHome(paths.chatgpt.codexHome);
+  }
+  if (!flags["skip-agents"]) {
+    await withProgress("Syncing app agent profiles", () => io.syncAgents({
+      profiles: installed.map((item) => appAgentProfile(item.target, paths)),
+      gatewayUrl: config.gatewayUrl,
+      credential: config.pat,
+      tenantId: config.tenantId,
+    }));
   }
-  const syncAgents = overrides.syncAgents || syncAgentProfilesSafe;
-  await syncAgents({
-    profiles: installed.map((item) => appAgentProfile(item.target, paths)),
-    gatewayUrl: config.gatewayUrl,
-    credential: config.pat,
-    tenantId: config.tenantId,
-  });
 }
 
 /**
@@ -474,7 +558,7 @@ export async function provisionAndOpenManagedApps({
     syncSkills: syncSkillsSafe,
     syncAgents: syncAgentProfilesSafe,
     secureCodexHome: secureManagedCodexHome,
-    openLauncher: (launcher) => spawnSync("/usr/bin/open", ["-n", launcher], { stdio: "inherit" }),
+    openLauncher: openManagedLauncher,
     log: (message) => console.log(message),
     ...overrides,
   };
@@ -483,7 +567,7 @@ export async function provisionAndOpenManagedApps({
   // This keeps unavailable/unauthorized tenants fail-closed on first use.
   let catalog;
   try {
-    catalog = await io.fetchModels(config);
+    catalog = await withProgress("Fetching the tenant model catalog", () => io.fetchModels(config));
   } catch (error) {
     throw new Error(
       `tenant model catalog is unavailable (${redactSecretText(error?.message || error)}); the selected tenant app was not opened`,
@@ -494,7 +578,9 @@ export async function provisionAndOpenManagedApps({
   for (const status of statuses) {
     let vendorPath = status.vendorPath;
     if (!vendorPath) {
-      const result = io.ensureVendor(status.target, { homeDir });
+      const result = await withProgress(`Preparing the verified ${status.target} vendor app`, () => (
+        io.ensureVendor(status.target, { homeDir })
+      ));
       vendorPath = result.path;
       io.log(`${status.target}: vendor app ${result.action}${result.note ? ` (${result.note})` : ""}`);
       if (!vendorPath) {
@@ -516,14 +602,17 @@ export async function provisionAndOpenManagedApps({
     });
   }
 
-  const installed = io.installFiles({
-    config,
-    targets,
-    models: catalog.models,
-    homeDir,
-    vendorPaths,
-    writeBundles: staleBundleTargets,
-  });
+  const installed = await withProgress(
+    staleBundleTargets.length > 0 ? "Rebuilding managed app bundles" : "Updating managed app profiles",
+    () => io.installFiles({
+      config,
+      targets,
+      models: catalog.models,
+      homeDir,
+      vendorPaths,
+      writeBundles: staleBundleTargets,
+    }),
+  );
   const newlyInstalled = new Set(
     statuses.filter((status) => !status.launcherInstalled).map((status) => status.target),
   );
@@ -539,15 +628,17 @@ export async function provisionAndOpenManagedApps({
   const gatewayUrl = resolveSkillsGateway(config.gatewayUrl);
   for (const item of installed) {
     const { client, env, label } = appSkillTarget(item.target, paths);
-    await io.syncSkills({ client, gatewayUrl, env, label });
+    await withProgress(`Syncing skills for ${label}`, () => (
+      io.syncSkills({ client, gatewayUrl, env, label })
+    ));
     if (item.target === "chatgpt") io.secureCodexHome(paths.chatgpt.codexHome);
   }
-  await io.syncAgents({
+  await withProgress("Syncing app agent profiles", () => io.syncAgents({
     profiles: installed.map((item) => appAgentProfile(item.target, paths)),
     gatewayUrl: config.gatewayUrl,
     credential: config.pat,
     tenantId: config.tenantId,
-  });
+  }));
   for (const item of installed) await io.openLauncher(item.launcher);
   return installed;
 }

package/src/commands/skills.js

@@ -15,6 +15,7 @@ import { CLAUDE_CONFIG_ID, appPaths } from "../apps.js";
 import { resolveSkillsGateway, syncSkillsSafe } from "../skills.js";
 import { ensureTenantSelection } from "../tenants.js";
 import { windowsClaudeUserData } from "../windowsApps.js";
+import { mapWithConcurrency, withProgress } from "../progress.js";
 
 const VALID_TARGETS = ["claude", "codex", "all"];
 
@@ -78,7 +79,7 @@ export function managedSkillProfiles(
   return profiles;
 }
 
-export async function cmdSkills(argv) {
+export async function cmdSkills(argv, overrides = {}) {
   const [action = "sync", targetToken] = argv;
   if (action !== "sync") {
     console.error(`impel skills: unknown action "${action}". Try \`impel skills sync [claude|codex|all]\`.`);
@@ -93,16 +94,26 @@ export async function cmdSkills(argv) {
     return;
   }
 
-  const config = loadConfig();
+  const io = {
+    loadConfig,
+    ensureTenantSelection,
+    managedProfiles: managedSkillProfiles,
+    syncSkills: syncSkillsSafe,
+    ...overrides,
+  };
+  const config = io.loadConfig();
   const gatewayUrl = resolveSkillsGateway(config?.gatewayUrl);
   const tenantId = config?.pat
-    ? (await ensureTenantSelection(config)).tenantId
+    ? (await io.ensureTenantSelection(config)).tenantId
     : null;
   const clients = target === "all" ? ["claude", "codex"] : [target];
+  const profiles = clients.flatMap((client) => (
+    io.managedProfiles(client, { tenantId }).map((profile) => ({ client, profile }))
+  ));
 
-  for (const client of clients) {
-    for (const profile of managedSkillProfiles(client, { tenantId })) {
-      await syncSkillsSafe({ client, gatewayUrl, env: profile.env, label: profile.label });
-    }
-  }
+  await withProgress(`Syncing skills into ${profiles.length} managed profile${profiles.length === 1 ? "" : "s"}`, () => (
+    mapWithConcurrency(profiles, 4, ({ client, profile }) => (
+      io.syncSkills({ client, gatewayUrl, env: profile.env, label: profile.label })
+    ))
+  ));
 }

package/src/commands/update.js

@@ -14,6 +14,7 @@ import { CLAUDE_CONFIG_ID, appPaths } from "../apps.js";
 import { loadConfig, redactSecretText } from "../config.js";
 import { nativeCommandInvocation } from "../nativeProcess.js";
 import { windowsClaudeUserData } from "../windowsApps.js";
+import { withProgress } from "../progress.js";
 import {
   fetchRemoteVersion,
   installedVersion,
@@ -88,8 +89,12 @@ function defaultSelfUpdate(spec) {
 
 // The cascading steps re-execute the (freshly installed) CLI binary so the
 // NEW code performs them, not the process that started the update.
-function defaultRunAppsUpdate() {
-  const result = spawnSync(process.execPath, [CLI_BIN, "app", "update", "all"], {
+export function defaultRunAppsUpdate({
+  spawn = spawnSync,
+  execPath = process.execPath,
+  cliBin = CLI_BIN,
+} = {}) {
+  const result = spawn(execPath, [cliBin, "app", "update", "all", "--skip-skills", "--skip-agents"], {
     stdio: "inherit",
   });
   return result.status === 0;
@@ -166,7 +171,7 @@ export async function cmdUpdate(argv, overrides = {}) {
   }
 
   const current = io.installedVersion();
-  const remote = await io.fetchRemoteVersion();
+  const remote = await withProgress("Checking npm for impel-cli updates", () => io.fetchRemoteVersion());
   if (remote) io.writeCache({ remoteVersion: remote, checkedAt: Date.now() });
 
   console.log(`impel-cli v${current ?? "?"}`);
@@ -185,7 +190,7 @@ export async function cmdUpdate(argv, overrides = {}) {
     console.log("CLI: already up to date.");
   } else {
     console.log("CLI: installing the latest build…");
-    if (!io.selfUpdate(updateInstallSpec())) {
+    if (!await withProgress("Installing the latest impel-cli build", () => io.selfUpdate(updateInstallSpec()))) {
       console.error("impel update: `npm install -g` failed; the CLI was not updated.");
       if (io.platform === "win32") {
         console.error("  Verify `npm --version` in PowerShell, then retry `impel update`.");
@@ -208,21 +213,21 @@ export async function cmdUpdate(argv, overrides = {}) {
   } else {
     console.log(io.platform === "win32"
       ? "Apps: updating the signed Claude and ChatGPT vendor apps and isolated profiles…"
-      : "Apps: updating (running apps are closed, verified vendor builds installed, bundles rebuilt)…");
-    if (!io.runAppsUpdate()) {
+      : "Apps: refreshing profiles and rebuilding only stale app bundles…");
+    if (!await withProgress("Updating managed desktop apps", () => io.runAppsUpdate())) {
       console.error("impel update: the app update failed; re-run `impel app update` after fixing the issue.");
       cascadeFailed = true;
     }
   }
 
   console.log("Skills: syncing every managed profile…");
-  if (!io.runSkillsSync()) {
+  if (!await withProgress("Syncing skills across managed profiles", () => io.runSkillsSync())) {
     console.error("impel update: skill sync failed; re-run `impel skills sync` after fixing the issue.");
     cascadeFailed = true;
   }
 
   console.log("Agents: syncing the selected tenant into every managed profile…");
-  if (!io.runAgentsSync()) {
+  if (!await withProgress("Syncing agents across managed profiles", () => io.runAgentsSync())) {
     console.error("impel update: agent sync failed; re-run `impel agents sync` after fixing the issue.");
     cascadeFailed = true;
   }

package/src/progress.js

@@ -0,0 +1,85 @@
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+function noopSpinner() {
+  return {
+    update() {},
+    succeed() {},
+    fail() {},
+  };
+}
+
+/**
+ * Render a small stderr-only spinner without changing machine-readable stdout.
+ * Non-interactive processes and detached app refreshes get a no-op object.
+ */
+export function createSpinner(label, { stream = process.stderr } = {}) {
+  if (!stream?.isTTY || process.env.IMPEL_NO_PROGRESS === "1") return noopSpinner();
+
+  let currentLabel = String(label);
+  let frame = 0;
+  let finished = false;
+  const startedAt = Date.now();
+  const render = () => {
+    const elapsed = ((Date.now() - startedAt) / 1000).toFixed(1);
+    stream.write(`\r${FRAMES[frame % FRAMES.length]} ${currentLabel} (${elapsed}s)\x1b[K`);
+    frame += 1;
+  };
+  const finish = (symbol, nextLabel) => {
+    if (finished) return;
+    finished = true;
+    clearInterval(timer);
+    if (nextLabel) currentLabel = String(nextLabel);
+    const elapsed = ((Date.now() - startedAt) / 1000).toFixed(1);
+    stream.write(`\r${symbol} ${currentLabel} (${elapsed}s)\x1b[K\n`);
+  };
+
+  render();
+  const timer = setInterval(render, 80);
+  timer.unref?.();
+  return {
+    update(nextLabel) {
+      if (!finished && nextLabel) currentLabel = String(nextLabel);
+    },
+    succeed(nextLabel) {
+      finish("✓", nextLabel);
+    },
+    fail(nextLabel) {
+      finish("✗", nextLabel);
+    },
+  };
+}
+
+export async function withProgress(label, fn, options) {
+  const spinner = createSpinner(label, options);
+  try {
+    const result = await fn(spinner);
+    spinner.succeed();
+    return result;
+  } catch (error) {
+    spinner.fail();
+    throw error;
+  }
+}
+
+/** Run independent jobs with bounded concurrency while preserving result order. */
+export async function mapWithConcurrency(items, limit, fn) {
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new RangeError("concurrency limit must be a positive integer");
+  }
+  const values = Array.from(items);
+  const results = new Array(values.length);
+  let nextIndex = 0;
+
+  async function worker() {
+    while (nextIndex < values.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await fn(values[index], index);
+    }
+  }
+
+  await Promise.all(
+    Array.from({ length: Math.min(limit, values.length) }, () => worker()),
+  );
+  return results;
+}