impel-cli 0.11.2 → 0.12.1

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]
+                                             `all` without --tenant updates every installed tenant;
+                                             --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
@@ -165,7 +167,9 @@ impel help                                   Show help
 impel --version                              Show version
 
 For app commands, `target` is `claude`, `chatgpt`/`codex`, or `all` (the
-default). `--tenant` defaults to the currently selected organization.
+default). `impel app update all` without `--tenant` updates every locally
+installed tenant. Other app commands, a specific update target, or an explicit
+`--tenant` operate on one organization and default to the current selection.
 
 # `impel setup` no longer takes a per-tool target and never flips native
 # configs; flip a native tool explicitly with `impel use gateway [claude|codex]`.
@@ -237,9 +241,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)
+(update every locally installed tenant and rebuild only stale vendored Impel apps)
 followed by `impel skills sync all` and `impel agents sync all` across every
-managed profile.
+native and isolated CLI profile. Each tenant's app step syncs that tenant's app
+profiles; the dedicated steps exclude apps, so every profile is synced once.
 
 Update discovery compares the installed package version with npm's public
 `latest` metadata, cached for 6 hours in
@@ -608,6 +613,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 +634,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,10 +709,11 @@ 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. A wrapper-owned startup preload pins
   Electron's application name before the native menu is created, so macOS
@@ -727,9 +739,24 @@ impel app open all --tenant acme
 impel app open all --tenant globex
 ```
 
-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.
+Updates with `--tenant` and all uninstalls touch only the named tenant variant.
+`impel app update all` without `--tenant` discovers every locally installed
+tenant and updates each sequentially; it does not install variants for tenants
+that have never been installed. 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.
+
+Skills plugin subprocesses run asynchronously, so the TTY progress indicator
+continues animating while Claude or Codex refreshes a marketplace. Skill status
+lines temporarily clear and redraw the spinner instead of overwriting it.
 
 The official Claude and ChatGPT apps remain separate installations and keep
 their normal accounts, updater, profiles, and bundle identities. Each CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.11.2",
+  "version": "0.12.1",
   "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) {
@@ -379,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
@@ -550,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 {
@@ -646,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
@@ -941,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 {
@@ -1027,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 {
@@ -1653,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; 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]

package/src/commands/agents.js

@@ -4,6 +4,7 @@
 import os from "node:os";
 
 import { agentProfileRoot, syncAgentProfiles } from "../agents.js";
+import { parseFlags } from "../args.js";
 import { loadConfig, normalizeGatewayUrl, redactSecretText, resolveDefaultGateway } from "../config.js";
 import { ensureTenantSelection, tenantCredential } from "../tenants.js";
 import { managedSkillProfiles } from "./skills.js";
@@ -41,7 +42,8 @@ export function managedAgentProfiles(client, options = {}) {
 }
 
 export async function cmdAgents(argv, overrides = {}) {
-  const [action = "sync", targetToken] = argv;
+  const [action = "sync", rawTarget, ...rest] = argv;
+  const targetToken = rawTarget?.startsWith("--") ? undefined : rawTarget;
   if (["help", "--help", "-h"].includes(action)) {
     console.log(HELP);
     return;
@@ -57,6 +59,8 @@ export async function cmdAgents(argv, overrides = {}) {
     process.exitCode = 1;
     return;
   }
+  const flagArgs = rawTarget?.startsWith("--") ? [rawTarget, ...rest] : rest;
+  const { flags } = parseFlags(flagArgs, { "skip-apps": { type: "boolean" } });
 
   const io = {
     loadConfig,
@@ -83,6 +87,7 @@ export async function cmdAgents(argv, overrides = {}) {
       tenantId,
       environment: io.environment,
       homeDir: io.homeDir,
+      includeApps: !flags["skip-apps"],
     }));
     await io.syncAgentProfiles({
       profiles,

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 { createProgressLogger, withProgress } from "../progress.js";
 import {
   ensureWindowsClaudeApp,
   ensureWindowsChatGPTApp,
@@ -78,6 +79,102 @@ function windowsAppTargets(targetToken) {
   return null;
 }
 
+function macTargetOrArtifactExists(paths, target, existsSync = fs.existsSync) {
+  const launcher = paths[target].launcher;
+  if (existsSync(launcher)) return true;
+  try {
+    const baseName = path.basename(launcher);
+    return fs.readdirSync(path.dirname(launcher)).some((entry) => (
+      entry.startsWith(`${baseName}.tmp-`) || entry.startsWith(`${baseName}.previous-`)
+    ));
+  } catch {
+    return false;
+  }
+}
+
+/** Locally installed tenant variants eligible for an all-target app update. */
+export function installedAppTenantIds(targets, {
+  homeDir = os.homedir(),
+  platform = process.platform,
+  environment = process.env,
+  existsSync = fs.existsSync,
+  readdirSync = fs.readdirSync,
+} = {}) {
+  const tenantsRoot = path.join(appPaths(homeDir).root, "tenants");
+  let entries;
+  try {
+    entries = readdirSync(tenantsRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+
+  const installed = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    let tenantId;
+    try {
+      tenantId = normalizeTenantId(entry.name);
+    } catch {
+      continue;
+    }
+    const manifest = readTenantManifest(homeDir, tenantId);
+    const claudeUserData = platform === "win32"
+      ? windowsClaudeUserData(environment, tenantId)
+      : null;
+    const paths = appPaths(homeDir, tenantId, {
+      claudeUserData,
+      tenantName: manifest?.tenantName,
+    });
+    const hasTarget = targets.some((target) => {
+      if (platform !== "win32") return macTargetOrArtifactExists(paths, target, existsSync);
+      return target === "claude"
+        ? existsSync(path.join(paths.claude.userData, "configLibrary", `${CLAUDE_CONFIG_ID}.json`))
+        : existsSync(path.join(paths.chatgpt.codexHome, "config.toml"));
+    });
+    if (hasTarget) installed.push(tenantId);
+  }
+  return installed.sort((left, right) => left.localeCompare(right));
+}
+
+async function maybeUpdateAllInstalledTenants(argv, overrides, platform) {
+  if (overrides.singleTenantUpdate) return null;
+  const [action = "status", rawTarget, ...rest] = argv;
+  if (action !== "update") return null;
+  const targetToken = rawTarget?.startsWith("--") ? undefined : rawTarget;
+  const targets = normalizeAppTarget(targetToken);
+  if (!targets || targets.length !== 2) return null;
+  const flagArgs = rawTarget?.startsWith("--") ? [rawTarget, ...rest] : rest;
+  const { flags } = parseFlags(flagArgs, {
+    "skip-vendor": { type: "boolean" },
+    "skip-skills": { type: "boolean" },
+    "skip-agents": { type: "boolean" },
+    force: { type: "boolean" },
+    tenant: { type: "string" },
+  });
+  if (flags.tenant) return null;
+
+  const discover = overrides.installedTenantIds || installedAppTenantIds;
+  const tenantIds = discover(targets, {
+    homeDir: overrides.homeDir || os.homedir(),
+    platform,
+    environment: overrides.environment || process.env,
+  });
+  if (tenantIds.length === 0) return null;
+
+  const log = overrides.log || console.log;
+  log(`Updating all managed app targets across ${tenantIds.length} installed tenant${tenantIds.length === 1 ? "" : "s"}: ${tenantIds.join(", ")}`);
+  const runTenantUpdate = overrides.runTenantUpdate || cmdApps;
+  for (const tenantId of tenantIds) {
+    const result = await runTenantUpdate(
+      ["update", "all", ...flagArgs, "--tenant", tenantId],
+      { ...overrides, singleTenantUpdate: true },
+    );
+    if (result === false) return false;
+  }
+  return true;
+}
+
 function windowsProcessFailure(result) {
   if (result?.error?.message) return redactSecretText(result.error.message);
   if (Number.isInteger(result?.status)) return `exit code ${result.status}`;
@@ -85,6 +182,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 +234,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 +367,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 +399,27 @@ 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}`, (spinner) => (
+            io.syncSkills({
+              client,
+              gatewayUrl: resolveSkillsGateway(config.gatewayUrl),
+              env,
+              label,
+              logger: createProgressLogger(spinner),
+            })
+          ));
+        }
         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 +448,11 @@ 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;
+  const allTenantUpdate = await maybeUpdateAllInstalledTenants(argv, overrides, platform);
+  if (allTenantUpdate !== null) return allTenantUpdate;
+  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 +463,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 +516,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 +535,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}`, (spinner) => (
+        io.syncSkills({ client, gatewayUrl, env, label, logger: createProgressLogger(spinner) })
+      ));
+    }
+    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 +662,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 +671,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 +682,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 +706,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 +732,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}`, (spinner) => (
+      io.syncSkills({ client, gatewayUrl, env, label, logger: createProgressLogger(spinner) })
+    ));
     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

@@ -8,6 +8,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+import { parseFlags } from "../args.js";
 import { loadConfig } from "../config.js";
 import { CODEX_HOME } from "../codexSetup.js";
 import { tenantCliProfilePaths } from "../cliProfiles.js";
@@ -15,6 +16,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 { createProgressLogger, mapWithConcurrency, withProgress } from "../progress.js";
 
 const VALID_TARGETS = ["claude", "codex", "all"];
 
@@ -39,6 +41,7 @@ export function managedSkillProfiles(
     tenantId = null,
     platform = process.platform,
     environment = process.env,
+    includeApps = true,
   } = {},
 ) {
   const profiles = [];
@@ -58,7 +61,7 @@ export function managedSkillProfiles(
     const appInstalled = platform === "win32"
       ? existsSync(path.join(paths.claude.userData, "configLibrary", `${CLAUDE_CONFIG_ID}.json`))
       : existsSync(paths.claude.launcher);
-    if (appInstalled) {
+    if (includeApps && appInstalled) {
       profiles.push({ label: "Impel Claude app", env: { CLAUDE_CONFIG_DIR: paths.claude.userData } });
     }
   } else {
@@ -70,7 +73,7 @@ export function managedSkillProfiles(
     const appInstalled = platform === "win32"
       ? existsSync(path.join(paths.chatgpt.codexHome, "config.toml"))
       : existsSync(paths.chatgpt.launcher);
-    if (appInstalled) {
+    if (includeApps && appInstalled) {
       profiles.push({ label: "Impel ChatGPT app", env: { CODEX_HOME: paths.chatgpt.codexHome } });
     }
   }
@@ -78,8 +81,9 @@ export function managedSkillProfiles(
   return profiles;
 }
 
-export async function cmdSkills(argv) {
-  const [action = "sync", targetToken] = argv;
+export async function cmdSkills(argv, overrides = {}) {
+  const [action = "sync", rawTarget, ...rest] = argv;
+  const targetToken = rawTarget?.startsWith("--") ? undefined : rawTarget;
   if (action !== "sync") {
     console.error(`impel skills: unknown action "${action}". Try \`impel skills sync [claude|codex|all]\`.`);
     process.exitCode = 1;
@@ -92,17 +96,38 @@ export async function cmdSkills(argv) {
     process.exitCode = 1;
     return;
   }
+  const flagArgs = rawTarget?.startsWith("--") ? [rawTarget, ...rest] : rest;
+  const { flags } = parseFlags(flagArgs, { "skip-apps": { type: "boolean" } });
 
-  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,
+      includeApps: !flags["skip-apps"],
+    }).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"}`, (spinner) => (
+    mapWithConcurrency(profiles, 4, ({ client, profile }) => (
+      io.syncSkills({
+        client,
+        gatewayUrl,
+        env: profile.env,
+        label: profile.label,
+        logger: createProgressLogger(spinner),
+      })
+    ))
+  ));
 }

package/src/commands/update.js

@@ -14,6 +14,8 @@ 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 { installedAppTenantIds } from "./apps.js";
 import {
   fetchRemoteVersion,
   installedVersion,
@@ -28,9 +30,9 @@ const CLI_BIN = fileURLToPath(new URL("../../bin/impel.js", import.meta.url));
 const HELP = `impel update - update everything Impel in one command
 
 Reinstalls impel-cli from npm, then cascades with the NEW build:
-\`impel app update all\` (update the platform's vendor apps and managed app
-profiles) when Impel apps are installed, then \`impel skills sync all\` and
-\`impel agents sync all\` across every managed profile.
+\`impel app update all\` (update every locally installed tenant's vendor apps
+and managed app profiles), then \`impel skills sync all\` and
+\`impel agents sync all\` across native and isolated CLI profiles.
 
 Usage:
   impel update              Update the CLI, then cascade to apps, skills, and agents
@@ -88,28 +90,45 @@ 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"], {
     stdio: "inherit",
   });
   return result.status === 0;
 }
 
-function defaultRunSkillsSync() {
-  const result = spawnSync(process.execPath, [CLI_BIN, "skills", "sync", "all"], {
+export function defaultRunSkillsSync({
+  spawn = spawnSync,
+  execPath = process.execPath,
+  cliBin = CLI_BIN,
+} = {}) {
+  const result = spawn(execPath, [cliBin, "skills", "sync", "all", "--skip-apps"], {
     stdio: "inherit",
   });
   return result.status === 0;
 }
 
-function defaultRunAgentsSync() {
-  const result = spawnSync(process.execPath, [CLI_BIN, "agents", "sync", "all"], {
+export function defaultRunAgentsSync({
+  spawn = spawnSync,
+  execPath = process.execPath,
+  cliBin = CLI_BIN,
+} = {}) {
+  const result = spawn(execPath, [cliBin, "agents", "sync", "all", "--skip-apps"], {
     stdio: "inherit",
   });
   return result.status === 0;
 }
 
 function anyAppInstalled(homeDir = os.homedir()) {
+  if (installedAppTenantIds(["claude", "chatgpt"], {
+    homeDir,
+    platform: process.platform,
+    environment: process.env,
+  }).length > 0) return true;
   const config = loadConfig();
   const claudeUserData = process.platform === "win32"
     ? windowsClaudeUserData(process.env, config?.tenantId || null)
@@ -166,7 +185,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 +204,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`.");
@@ -197,7 +216,7 @@ export async function cmdUpdate(argv, overrides = {}) {
     console.log(`CLI: updated${remote ? ` to v${remote}` : ""}.`);
   }
 
-  // ── Cascade: apps, then skills across every managed profile ────────────
+  // ── Cascade: every tenant app, then non-app managed profiles ───────────
   let cascadeFailed = false;
   if (flags["skip-apps"]) {
     console.log("Apps: skipped (--skip-apps).");
@@ -207,22 +226,22 @@ export async function cmdUpdate(argv, overrides = {}) {
     console.log("Apps: none installed; skipping (run `impel app install` or `impel setup`).");
   } 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: updating every installed tenant's signed Claude and ChatGPT profiles…"
+      : "Apps: refreshing every installed tenant 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()) {
+  console.log("Skills: syncing native and isolated CLI profiles…");
+  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()) {
+  console.log("Agents: syncing the selected tenant into native and isolated CLI profiles…");
+  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,106 @@
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+function noopSpinner() {
+  return {
+    active: false,
+    update() {},
+    writeLine() { return false; },
+    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 {
+    active: true,
+    update(nextLabel) {
+      if (!finished && nextLabel) currentLabel = String(nextLabel);
+    },
+    writeLine(message) {
+      if (finished) return false;
+      stream.write(`\r\x1b[K${String(message)}\n`);
+      render();
+      return true;
+    },
+    succeed(nextLabel) {
+      finish("✓", nextLabel);
+    },
+    fail(nextLabel) {
+      finish("✗", nextLabel);
+    },
+  };
+}
+
+/** Keep ordinary log lines from overwriting an active progress display. */
+export function createProgressLogger(spinner, fallback = console) {
+  const write = (method, args) => {
+    const message = args.map((value) => String(value)).join(" ");
+    if (!spinner?.writeLine?.(message)) fallback[method](...args);
+  };
+  return {
+    log: (...args) => write("log", args),
+    warn: (...args) => write("warn", args),
+  };
+}
+
+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;
+}

package/src/skills.js

@@ -19,7 +19,7 @@
 //   - Codex:       `plugin marketplace add|upgrade`, `plugin add` (install + refresh)
 // so we keep a per-client command table rather than assuming one shape.
 
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 
 import { resolveDefaultGateway, normalizeGatewayUrl } from "./config.js";
 import { nativeCommandInvocation } from "./nativeProcess.js";
@@ -159,44 +159,95 @@ export function buildSkillCommands({ client, marketplaceSourceUrl: sourceUrl, ma
   return commands;
 }
 
-/** Default command runner: spawns the client binary non-interactively. */
-function defaultRun(bin, args, env) {
+const SKILL_COMMAND_TIMEOUT_MS = 120_000;
+const SKILL_COMMAND_OUTPUT_LIMIT = 10 * 1024 * 1024;
+
+/** Default async command runner: keeps progress timers responsive while plugins sync. */
+export function runSkillCommand(bin, args, env, {
+  spawnImpl = spawn,
+  timeoutMs = SKILL_COMMAND_TIMEOUT_MS,
+} = {}) {
   const environment = { ...process.env, ...env };
   let invocation;
   try {
     invocation = nativeCommandInvocation(bin, args, environment);
   } catch (error) {
-    return {
+    return Promise.resolve({
       ok: false,
       missing: false,
       status: null,
       stdout: "",
       stderr: error?.message || String(error),
-    };
+    });
   }
-  const result = spawnSync(invocation.command, invocation.args, {
-    env: environment,
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-    timeout: 120000,
-    windowsVerbatimArguments: invocation.windowsVerbatimArguments,
-  });
-  if (result.error) {
-    return {
+
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnImpl(invocation.command, invocation.args, {
+        env: environment,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+      });
+    } catch (error) {
+      resolve({
+        ok: false,
+        missing: error?.code === "ENOENT",
+        status: null,
+        stdout: "",
+        stderr: error?.message || String(error),
+      });
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    const append = (current, chunk) => (
+      `${current}${String(chunk)}`.slice(-SKILL_COMMAND_OUTPUT_LIMIT)
+    );
+    child.stdout?.setEncoding?.("utf8");
+    child.stderr?.setEncoding?.("utf8");
+    child.stdout?.on("data", (chunk) => { stdout = append(stdout, chunk); });
+    child.stderr?.on("data", (chunk) => { stderr = append(stderr, chunk); });
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      try {
+        child.kill();
+      } catch {
+        // The process may have exited between the timer firing and kill().
+      }
+      finish({
+        ok: false,
+        missing: false,
+        status: null,
+        stdout,
+        stderr: `skill command timed out after ${timeoutMs}ms`,
+      });
+    }, timeoutMs);
+    child.on("error", (error) => finish({
       ok: false,
-      missing: result.error.code === "ENOENT",
+      missing: error?.code === "ENOENT",
       status: null,
-      stdout: "",
-      stderr: result.error.message || String(result.error),
-    };
-  }
-  return {
-    ok: result.status === 0,
-    missing: false,
-    status: result.status,
-    stdout: result.stdout || "",
-    stderr: result.stderr || "",
-  };
+      stdout,
+      stderr: error?.message || String(error),
+    }));
+    child.on("close", (status) => finish({
+      ok: !timedOut && status === 0,
+      missing: false,
+      status,
+      stdout,
+      stderr: timedOut ? `skill command timed out after ${timeoutMs}ms` : stderr,
+    }));
+  });
 }
 
 function firstLine(text) {
@@ -237,7 +288,7 @@ export async function syncSkills({
   env = {},
   label,
   fetchImpl = fetch,
-  run = defaultRun,
+  run = runSkillCommand,
   logger = console,
 } = {}) {
   const spec = CLIENT_SPECS[client];
@@ -254,7 +305,7 @@ export async function syncSkills({
 
   try {
     // Confirm the binary and its `plugin` subcommand exist before doing anything.
-    const help = run(spec.bin, ["plugin", "--help"], env);
+    const help = await run(spec.bin, ["plugin", "--help"], env);
     if (help.missing) {
       logger.warn(`impel: skipping skill sync for ${displayLabel} — \`${spec.bin}\` CLI not found on PATH.`);
       return { client, label: displayLabel, skipped: true, reason: "binary-missing" };
@@ -272,7 +323,7 @@ export async function syncSkills({
     logger.log(`Skills: syncing ${SKILL_PLUGIN_NAME} for ${displayLabel}…`);
     const failures = [];
     for (const command of commands) {
-      const result = run(spec.bin, command.args, env);
+      const result = await run(spec.bin, command.args, env);
       if (result.missing) {
         failures.push({ phase: command.phase, reason: `\`${spec.bin}\` disappeared mid-sync` });
         break;