impel-cli 0.18.3 → 0.18.5

package/src/installRecovery/tools.js

@@ -500,10 +500,22 @@ async function installVendorApp(input, context) {
   if (typeof context.installVendorApp !== "function") {
     return result("failed", "Vendor app installation is unavailable in this recovery context.");
   }
-  const installed = await context.installVendorApp(input.target);
-  return installed === false
-    ? result("failed", `The ${input.target} vendor app did not install cleanly.`)
-    : result("succeeded", `The ${input.target} vendor app installation completed.`);
+  const outcome = await context.installVendorApp(input.target);
+  const installed = typeof outcome === "object" && outcome !== null
+    ? outcome.installed !== false
+    : outcome !== false;
+  if (installed) {
+    return result("succeeded", `The ${input.target} vendor app installation completed.`);
+  }
+  const detail = typeof outcome === "object" && outcome?.error
+    ? redactInstallRecoveryText(outcome.error).slice(0, 1_000)
+    : null;
+  return result(
+    "failed",
+    detail
+      ? `The ${input.target} vendor app did not install cleanly: ${detail}`
+      : `The ${input.target} vendor app did not install cleanly.`,
+  );
 }
 
 function repairUserPath(input, context, io) {

package/src/prompt.js

@@ -40,12 +40,32 @@ export function promptSecret(question) {
   });
 }
 
-export function promptText(question) {
+export function promptText(question, {
+  signal = null,
+  input = process.stdin,
+  output = process.stdout,
+} = {}) {
   return new Promise((resolve) => {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    rl.question(question, (answer) => {
+    const rl = readline.createInterface({ input, output });
+    let settled = false;
+    const finish = (answer, aborted = false) => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener("abort", abort);
       rl.close();
-      resolve(answer.trim());
+      // A cancelled readline prompt otherwise leaves the next status line on
+      // the same terminal row as its unanswered question.
+      if (aborted && output?.isTTY) output.write("\n");
+      resolve(String(answer || "").trim());
+    };
+    const abort = () => finish("", true);
+    if (signal?.aborted) {
+      abort();
+      return;
+    }
+    signal?.addEventListener("abort", abort, { once: true });
+    rl.question(question, (answer) => {
+      finish(answer);
     });
   });
 }

package/src/provisioning.js

@@ -16,6 +16,7 @@ import {
   tenantCredential,
 } from "./tenants.js";
 import { reconcileTenantApps } from "./commands/apps.js";
+import { RUNTIME_BRAND } from "./runtimeBrand.js";
 
 export function selectDefaultTenant(listing, { requested = null, currentTenantId = null } = {}) {
   const normalized = requested ? normalizeTenantId(requested) : null;
@@ -62,8 +63,8 @@ export function buildTenantInventory(listing, {
 
 export function locallyKnownTenantIds({ homeDir = os.homedir(), readDirectory = fs.readdirSync } = {}) {
   const roots = [
-    path.join(homeDir, ".config", "impel", "cli", "tenants"),
-    path.join(homeDir, ".config", "impel", "apps", "tenants"),
+    path.join(homeDir, ".config", RUNTIME_BRAND.cli.configNamespace, "cli", "tenants"),
+    path.join(homeDir, ".config", RUNTIME_BRAND.cli.configNamespace, "apps", "tenants"),
   ];
   const ids = new Set();
   for (const root of roots) {
@@ -118,7 +119,7 @@ async function prepareTenantCli(config, tenant, io, binaries) {
         };
         continue;
       }
-      await io.syncSkills({
+      if (RUNTIME_BRAND.features.skills) await io.syncSkills({
         client,
         gatewayUrl,
         env: definition.env(profile),
@@ -143,7 +144,7 @@ async function prepareTenantCli(config, tenant, io, binaries) {
       root: value.root,
       label: `Impel ${client === "claude" ? "Claude" : "Codex"} CLI (${tenant.id})`,
     }));
-  if (agentProfiles.length) {
+  if (RUNTIME_BRAND.features.agents && agentProfiles.length) {
     try {
       await io.syncAgents({
         profiles: agentProfiles,

package/src/runtimeBrand.js

@@ -0,0 +1,140 @@
+import path from "node:path";
+
+const SAFE_ID = /^[a-z][a-z0-9-]{1,63}$/u;
+const SAFE_NAMESPACE = /^[a-z][a-z0-9_-]{1,63}$/u;
+const SAFE_PREFIX = /^[a-z][a-z0-9_]{2,63}_$/u;
+const SAFE_ENV = /^[A-Z][A-Z0-9_]{1,63}$/u;
+const SAFE_TENANT = /^[A-Za-z0-9_.-]{1,128}$/u;
+const SAFE_PACKAGE = /^(?:@[a-z0-9][a-z0-9._-]{0,62}\/)?[a-z0-9][a-z0-9._-]{0,126}$/u;
+const SAFE_BUNDLE_PREFIX = /^[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)+$/u;
+const CONTROL_RE = /[\u0000-\u001F\u007F-\u009F]/u;
+const SUPPORTED_COMMANDS = new Set(["setup", "auth", "pat", "app", "claude", "codex", "status", "token"]);
+
+const DEFAULT = Object.freeze({
+  schemaVersion: 1,
+  product: Object.freeze({ id: "impel", displayName: "Impel" }),
+  cli: Object.freeze({
+    command: "impel",
+    packageName: "impel-cli",
+    configNamespace: "impel",
+    providerId: "impel",
+    managedMarker: "impel-cli",
+    environmentPrefix: "IMPEL",
+  }),
+  auth: Object.freeze({ patPrefix: "impel_pat_", tenantPrefix: "impel_tenant_" }),
+  tenant: Object.freeze({ defaultId: null, displayName: null }),
+  gateway: Object.freeze({ defaultOrigin: "https://gateway.useimpel.com" }),
+  controlPlane: Object.freeze({ defaultOrigin: "https://www.useimpel.com" }),
+  apps: Object.freeze({
+    displayPrefix: "Impel",
+    bundleIdentifierPrefix: "com.useimpel",
+    windowsStartMenuFolder: "Impel",
+  }),
+  capabilities: Object.freeze({ commands: Object.freeze([...SUPPORTED_COMMANDS]), agentPats: true }),
+  features: Object.freeze({ sessions: true, mcp: true, skills: true, agents: true }),
+});
+
+function text(name, value, pattern = null) {
+  if (typeof value !== "string" || !value || value.trim() !== value || value.length > 128 || CONTROL_RE.test(value)) {
+    throw new Error(`impel-cli runtime brand ${name} is invalid`);
+  }
+  if (pattern && !pattern.test(value)) throw new Error(`impel-cli runtime brand ${name} is invalid`);
+  return value;
+}
+
+function origin(name, value) {
+  const parsed = new URL(text(name, value));
+  const local = parsed.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
+  if ((parsed.protocol !== "https:" && !local) || parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash) {
+    throw new Error(`impel-cli runtime brand ${name} must be a bare HTTPS origin`);
+  }
+  return parsed.toString().replace(/\/$/u, "");
+}
+
+function pathSegment(name, value) {
+  const result = text(name, value);
+  if (result === "." || result === ".." || /[\\/:]/u.test(result)) {
+    throw new Error(`impel-cli runtime brand ${name} is invalid`);
+  }
+  return result;
+}
+
+export function validateRuntimeBrand(input) {
+  if (!input || Array.isArray(input) || typeof input !== "object" || input.schemaVersion !== 1) {
+    throw new Error("impel-cli runtime brand schemaVersion must be 1");
+  }
+  const command = text("cli.command", input.cli?.command, SAFE_ID);
+  const packageName = text("cli.packageName", input.cli?.packageName || command, SAFE_PACKAGE);
+  if (path.isAbsolute(packageName)) throw new Error("impel-cli runtime brand cli.packageName is invalid");
+  const defaultTenant = input.tenant?.defaultId == null ? null : text("tenant.defaultId", input.tenant.defaultId, SAFE_TENANT);
+  const requestedCommands = input.capabilities?.commands;
+  if (!Array.isArray(requestedCommands) || requestedCommands.length === 0) {
+    throw new Error("impel-cli runtime brand capabilities.commands must be a non-empty array");
+  }
+  const commands = [...new Set(requestedCommands.map((commandName) => text("capabilities.commands", commandName, SAFE_ID)))];
+  if (commands.some((commandName) => !SUPPORTED_COMMANDS.has(commandName))) {
+    throw new Error("impel-cli runtime brand capabilities.commands contains an unsupported command");
+  }
+  return Object.freeze({
+    schemaVersion: 1,
+    product: Object.freeze({
+      id: text("product.id", input.product?.id, SAFE_ID),
+      displayName: text("product.displayName", input.product?.displayName),
+    }),
+    cli: Object.freeze({
+      command,
+      packageName,
+      configNamespace: text("cli.configNamespace", input.cli?.configNamespace, SAFE_NAMESPACE),
+      providerId: text("cli.providerId", input.cli?.providerId, SAFE_NAMESPACE),
+      managedMarker: text("cli.managedMarker", input.cli?.managedMarker, SAFE_NAMESPACE),
+      environmentPrefix: text("cli.environmentPrefix", input.cli?.environmentPrefix, SAFE_ENV),
+    }),
+    auth: Object.freeze({
+      patPrefix: text("auth.patPrefix", input.auth?.patPrefix, SAFE_PREFIX),
+      tenantPrefix: text("auth.tenantPrefix", input.auth?.tenantPrefix, SAFE_PREFIX),
+    }),
+    tenant: Object.freeze({
+      defaultId: defaultTenant,
+      displayName: input.tenant?.displayName == null ? defaultTenant : text("tenant.displayName", input.tenant.displayName),
+    }),
+    gateway: Object.freeze({ defaultOrigin: origin("gateway.defaultOrigin", input.gateway?.defaultOrigin) }),
+    controlPlane: Object.freeze({ defaultOrigin: origin("controlPlane.defaultOrigin", input.controlPlane?.defaultOrigin) }),
+    apps: Object.freeze({
+      displayPrefix: pathSegment("apps.displayPrefix", input.apps?.displayPrefix || input.product?.displayName),
+      bundleIdentifierPrefix: text("apps.bundleIdentifierPrefix", input.apps?.bundleIdentifierPrefix, SAFE_BUNDLE_PREFIX),
+      windowsStartMenuFolder: pathSegment("apps.windowsStartMenuFolder", input.apps?.windowsStartMenuFolder || input.product?.displayName),
+    }),
+    capabilities: Object.freeze({
+      commands: Object.freeze(commands),
+      agentPats: input.capabilities?.agentPats === true,
+    }),
+    features: Object.freeze({
+      sessions: input.features?.sessions === true,
+      mcp: input.features?.mcp === true,
+      skills: input.features?.skills === true,
+      agents: input.features?.agents === true,
+    }),
+  });
+}
+
+function loadRuntimeBrand() {
+  const encoded = process.env.IMPEL_CLI_RUNTIME_BRAND;
+  if (!encoded) return DEFAULT;
+  let parsed;
+  try { parsed = JSON.parse(encoded); }
+  catch { throw new Error("IMPEL_CLI_RUNTIME_BRAND must contain valid JSON"); }
+  return validateRuntimeBrand(parsed);
+}
+
+export const RUNTIME_BRAND = loadRuntimeBrand();
+
+export function brandedEnvironmentName(suffix) {
+  return `${RUNTIME_BRAND.cli.environmentPrefix}_${suffix}`;
+}
+
+export function brandedText(value) {
+  return String(value)
+    .replaceAll("impel-cli", `${RUNTIME_BRAND.cli.command}-cli`)
+    .replaceAll("Impel", RUNTIME_BRAND.product.displayName)
+    .replaceAll("impel", RUNTIME_BRAND.cli.command);
+}

package/src/selfInvocation.js

@@ -2,9 +2,11 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { environmentValue } from "./nativeProcess.js";
+import { RUNTIME_BRAND } from "./runtimeBrand.js";
 
 /** The running package's own bin script, used directly for live child spawns. */
-export const IMPEL_CLI_ENTRYPOINT = fileURLToPath(new URL("../bin/impel.js", import.meta.url));
+export const IMPEL_CLI_ENTRYPOINT = process.env.IMPEL_CLI_EXTENSION_ENTRYPOINT
+  || fileURLToPath(new URL("../bin/impel.js", import.meta.url));
 
 // Matches a real package install (npm/pnpm/volta all place the package under
 // node_modules/impel-cli; an unsupported project-local install matches too,
@@ -12,7 +14,9 @@ export const IMPEL_CLI_ENTRYPOINT = fileURLToPath(new URL("../bin/impel.js", imp
 // install). A git checkout or worktree never matches, so development runs
 // keep baking their own path instead of repointing the machine-wide stable
 // entry at a checkout.
-const GLOBAL_INSTALL_RE = /[\\/]node_modules[\\/]impel-cli[\\/]bin[\\/]impel\.js$/iu;
+const escapedPackageName = RUNTIME_BRAND.cli.packageName.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&").replaceAll("/", "[\\\\/]");
+const escapedCommand = RUNTIME_BRAND.cli.command.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+const GLOBAL_INSTALL_RE = new RegExp(`[\\\\/]node_modules[\\\\/]${escapedPackageName}[\\\\/]bin[\\\\/]${escapedCommand}\\.js$`, "iu");
 
 export function runningFromGlobalInstall(entrypoint = IMPEL_CLI_ENTRYPOINT) {
   return GLOBAL_INSTALL_RE.test(entrypoint);
@@ -22,7 +26,7 @@ export function runningFromGlobalInstall(entrypoint = IMPEL_CLI_ENTRYPOINT) {
 export function windowsStableEntrypointPath(environment = process.env) {
   const localAppData = environmentValue(environment, "LOCALAPPDATA");
   if (typeof localAppData !== "string" || !localAppData.trim()) return null;
-  return path.join(localAppData, "Impel", "bin", "impel-entry.cjs");
+  return path.join(localAppData, RUNTIME_BRAND.apps.windowsStartMenuFolder, "bin", `${RUNTIME_BRAND.cli.command}-entry.cjs`);
 }
 
 /** The directory `impel nuke` removes to erase the stable entry point. */

package/src/shellEntries.js

@@ -9,6 +9,7 @@ import { environmentValue, nativeCommandInvocation, resolveNativeBinary } from "
 import { managedCliEntrypoint } from "./selfInvocation.js";
 import { normalizeTenantId } from "./tenants.js";
 import { windowsClaudeUserData } from "./windowsApps.js";
+import { RUNTIME_BRAND } from "./runtimeBrand.js";
 
 const LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
 
@@ -42,7 +43,9 @@ export function windowsShortcutArgument(value) {
 export function windowsTenantShortcutName(product, tenantId, tenantName) {
   const id = normalizeTenantId(tenantId);
   const name = safeShortcutSegment(tenantName, id);
-  const label = product === "claude" ? "Impel Claude" : "Impel ChatGPT";
+  const label = product === "claude"
+    ? `${RUNTIME_BRAND.apps.displayPrefix} Claude`
+    : `${RUNTIME_BRAND.apps.displayPrefix} ChatGPT`;
   return `${label} (${name} · ${id}).lnk`;
 }
 
@@ -59,7 +62,7 @@ export function registerWindowsTenantShortcut({
 }) {
   const appData = environmentValue(environment, "APPDATA");
   if (!appData) throw new Error("Windows APPDATA is unavailable; Start menu entry was not created");
-  const shortcutDirectory = path.win32.join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Impel");
+  const shortcutDirectory = path.win32.join(appData, "Microsoft", "Windows", "Start Menu", "Programs", RUNTIME_BRAND.apps.windowsStartMenuFolder);
   mkdirSync(shortcutDirectory, { recursive: true });
   const shortcutPath = path.win32.join(
     shortcutDirectory,

package/src/stableEntrypoint.js

@@ -7,6 +7,7 @@ import {
   windowsStableEntrypointPath,
 } from "./selfInvocation.js";
 import { redactSecretText } from "./config.js";
+import { brandedEnvironmentName, RUNTIME_BRAND } from "./runtimeBrand.js";
 
 /**
  * Render the stable Windows entry point (`%LOCALAPPDATA%\Impel\bin\impel-entry.cjs`).
@@ -22,12 +23,15 @@ import { redactSecretText } from "./config.js";
  * supported Node (>=18). Output is deterministic for a given baked path.
  */
 export function renderStableEntrypoint(cliEntrypoint = IMPEL_CLI_ENTRYPOINT) {
+  const packageParts = RUNTIME_BRAND.cli.packageName.split("/");
+  const cliSuffixParts = ["node_modules", ...packageParts, "bin", `${RUNTIME_BRAND.cli.command}.js`];
+  const completeInstallFile = RUNTIME_BRAND.cli.packageName === "impel-cli" ? path.join("src", "cli.js") : null;
   return `#!/usr/bin/env node
 "use strict";
-// Managed by impel-cli — stable Impel entry point.
+// Managed by ${RUNTIME_BRAND.cli.command}-cli — stable ${RUNTIME_BRAND.product.displayName} entry point.
 //
-// Vendor apps (Impel Claude, Impel ChatGPT) persist absolute invocations of
-// this file in their managed profiles. It resolves the current impel-cli
+// Vendor apps (${RUNTIME_BRAND.apps.displayPrefix} Claude, ${RUNTIME_BRAND.apps.displayPrefix} ChatGPT) persist absolute invocations of
+// this file in their managed profiles. It resolves the current ${RUNTIME_BRAND.cli.packageName}
 // global install at run time, so replacing or moving the npm global package
 // never strands the invocations baked into those profiles.
 
@@ -37,10 +41,12 @@ const { pathToFileURL } = require("node:url");
 const { spawnSync } = require("node:child_process");
 
 const BAKED_CLI = ${JSON.stringify(cliEntrypoint)};
-const CLI_SUFFIX = path.join("node_modules", "impel-cli", "bin", "impel.js");
+const CLI_SUFFIX = path.join(${cliSuffixParts.map((part) => JSON.stringify(part)).join(", ")});
+const PACKAGE_NAME = ${JSON.stringify(RUNTIME_BRAND.cli.packageName)};
+const REQUIRED_FILE = ${JSON.stringify(completeInstallFile)};
 
 function waitBudgetMs() {
-  const raw = Number.parseInt(process.env.IMPEL_ENTRYPOINT_WAIT_MS || "", 10);
+  const raw = Number.parseInt(process.env.${brandedEnvironmentName("ENTRYPOINT_WAIT_MS")} || "", 10);
   if (Number.isFinite(raw) && raw >= 0) return Math.min(raw, 60000);
   return 8000;
 }
@@ -73,8 +79,8 @@ function isFile(candidate) {
 function isCompleteInstall(cliPath) {
   try {
     const root = path.dirname(path.dirname(cliPath));
-    if (!isFile(cliPath) || !isFile(path.join(root, "src", "cli.js"))) return false;
-    return JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).name === "impel-cli";
+    if (!isFile(cliPath) || (REQUIRED_FILE && !isFile(path.join(root, REQUIRED_FILE)))) return false;
+    return JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).name === PACKAGE_NAME;
   } catch {
     return false;
   }
@@ -106,8 +112,8 @@ async function main() {
   if (!cli) cli = candidateCliPaths().find(isFile) || null;
   if (!cli) {
     process.stderr.write(
-      "impel-entry: no impel-cli install found (checked " + candidateCliPaths().join("; ") + "). " +
-      "Run \`npm install -g impel-cli\`, then \`impel setup\`.\\n"
+      "${RUNTIME_BRAND.cli.command}-entry: no ${RUNTIME_BRAND.cli.packageName} install found (checked " + candidateCliPaths().join("; ") + "). " +
+      "Run \`npm install -g ${RUNTIME_BRAND.cli.packageName}\`, then \`${RUNTIME_BRAND.cli.command} setup\`.\\n"
     );
     process.exit(1);
   }
@@ -125,7 +131,7 @@ async function main() {
     });
     if (typeof rerun.status === "number") process.exit(rerun.status);
     process.stderr.write(
-      "impel-entry: could not start " + cli + " (" +
+      "${RUNTIME_BRAND.cli.command}-entry: could not start " + cli + " (" +
       (error && error.message ? error.message : String(error)) + ")\\n"
     );
     process.exit(1);
@@ -134,7 +140,7 @@ async function main() {
 
 main().catch((error) => {
   process.stderr.write(
-    "impel-entry: " + (error && error.message ? error.message : String(error)) + "\\n"
+    "${RUNTIME_BRAND.cli.command}-entry: " + (error && error.message ? error.message : String(error)) + "\\n"
   );
   process.exit(1);
 });
@@ -187,7 +193,7 @@ export function ensureWindowsStableEntrypointQuietly(options = {}) {
     return ensureWindowsStableEntrypoint(options);
   } catch (error) {
     console.error(
-      `impel: could not refresh the stable Windows entry point (${redactSecretText(error?.message || error)})`
+      `${RUNTIME_BRAND.cli.command}: could not refresh the stable Windows entry point (${redactSecretText(error?.message || error)})`
     );
     return null;
   }

package/src/tenants.js

@@ -4,8 +4,9 @@ import {
   resolveDefaultAppUrl,
   saveConfig,
 } from "./config.js";
+import { RUNTIME_BRAND } from "./runtimeBrand.js";
 
-export const TENANT_CREDENTIAL_PREFIX = "impel_tenant_";
+export const TENANT_CREDENTIAL_PREFIX = RUNTIME_BRAND.auth.tenantPrefix;
 export const PRODUCT_ACCESS_WORKSPACE = "workspace";
 export const PRODUCT_ACCESS_IDENTITY = "identity";
 export const PRODUCT_ACCESS_GATEWAY = "gateway";
@@ -85,15 +86,15 @@ function normalizeTenantName(value, fallback) {
 }
 
 export function tenantCredential(pat, tenantId) {
-  if (!String(pat || "").startsWith("impel_pat_")) {
-    throw new Error("an Impel PAT is required to create a tenant credential");
+  if (!String(pat || "").startsWith(RUNTIME_BRAND.auth.patPrefix)) {
+    throw new Error(`a ${RUNTIME_BRAND.product.displayName} PAT is required to create a tenant credential`);
   }
   const encodedTenant = Buffer.from(normalizeTenantId(tenantId), "utf8").toString("base64url");
   return `${TENANT_CREDENTIAL_PREFIX}${encodedTenant}.${pat}`;
 }
 
 export async function fetchTenants(config, fetchImpl = fetch) {
-  if (!config?.pat) throw new Error("not authenticated; run `impel setup` (or `impel auth`) first");
+  if (!config?.pat) throw new Error(`not authenticated; run \`${RUNTIME_BRAND.cli.command} setup\` (or \`${RUNTIME_BRAND.cli.command} auth\`) first`);
   const appUrl = normalizeGatewayUrl(config.appUrl || resolveDefaultAppUrl());
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), 7_000);
@@ -141,9 +142,16 @@ export async function fetchTenants(config, fetchImpl = fetch) {
   if (!tenants.some((tenant) => tenant.id === defaultTenantId)) {
     throw new Error("tenant API default is not in the available tenant list");
   }
+  const fixedTenant = RUNTIME_BRAND.tenant.defaultId;
+  const visibleTenants = fixedTenant
+    ? tenants.filter((tenant) => tenant.id === fixedTenant || tenant.slug === fixedTenant)
+    : tenants;
+  if (fixedTenant && visibleTenants.length !== 1) {
+    throw new Error(`the required ${RUNTIME_BRAND.product.displayName} tenant is not available`);
+  }
   return {
-    tenants,
-    defaultTenantId,
+    tenants: visibleTenants,
+    defaultTenantId: fixedTenant ? visibleTenants[0].id : defaultTenantId,
     patTenantId: payload.patTenantId || null,
     productAccess,
     scopes,
@@ -151,7 +159,7 @@ export async function fetchTenants(config, fetchImpl = fetch) {
 }
 
 export async function ensureTenantSelection(config, { refresh = false } = {}) {
-  if (!config?.pat) throw new Error("not authenticated; run `impel setup` (or `impel auth`) first");
+  if (!config?.pat) throw new Error(`not authenticated; run \`${RUNTIME_BRAND.cli.command} setup\` (or \`${RUNTIME_BRAND.cli.command} auth\`) first`);
   if (config.tenantId && !refresh) {
     const tenantId = normalizeTenantId(config.tenantId);
     return {

package/src/windowsApps.js

@@ -9,11 +9,13 @@ import { pipeline } from "node:stream/promises";
 import { PINNED_VENDOR_APPS } from "./apps.js";
 import { environmentValue, nativeCommandInvocation } from "./nativeProcess.js";
 import { normalizeTenantId } from "./tenants.js";
+import { brandedEnvironmentName, RUNTIME_BRAND } from "./runtimeBrand.js";
 
 export const WINDOWS_CHATGPT_PACKAGE = "9PLM9XGG6VKS";
 export const WINDOWS_CHATGPT_PACKAGE_NAME = "OpenAI.Codex";
 export const WINDOWS_CHATGPT_PUBLISHER_ID = "2p2nqsd0c76g0";
 const WINDOWS_CLAUDE_DOWNLOAD_TIMEOUT_MS = 5 * 60 * 1000;
+const WINDOWS_WINGET_UPDATE_NOT_APPLICABLE = 0x8A15002B;
 
 export function windowsClaudeUserData(environment = process.env, tenantId = null) {
   const localAppData = environmentValue(environment, "LOCALAPPDATA")
@@ -21,7 +23,7 @@ export function windowsClaudeUserData(environment = process.env, tenantId = null
   return path.win32.join(
     localAppData,
     "Claude-3p",
-    "Impel",
+    RUNTIME_BRAND.apps.windowsStartMenuFolder,
     normalizeTenantId(tenantId || "default"),
   );
 }
@@ -34,6 +36,16 @@ function isFile(filePath) {
   }
 }
 
+// A CLI launched from PowerShell 7 inherits its PSModulePath. Passing that
+// value into Windows PowerShell 5.1 makes legacy modules such as
+// Microsoft.PowerShell.Security visible but unloadable. Omit the variable so
+// powershell.exe reconstructs its own version-correct default module path.
+function windowsPowerShellEnvironment(environment = process.env) {
+  return Object.fromEntries(
+    Object.entries(environment).filter(([key]) => key.toLowerCase() !== "psmodulepath"),
+  );
+}
+
 function versionedSquirrelCandidates(root, readDirectory = fs.readdirSync) {
   try {
     return readDirectory(root, { withFileTypes: true })
@@ -61,7 +73,7 @@ function installedMsixChatGPT(environment, run = spawnSync) {
   try {
     const result = run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
       encoding: "utf8",
-      env: environment,
+      env: windowsPowerShellEnvironment(environment),
       stdio: ["ignore", "pipe", "ignore"],
       windowsHide: true,
     });
@@ -74,7 +86,7 @@ function installedMsixChatGPT(environment, run = spawnSync) {
 /** Candidate paths for Anthropic's signed per-user Windows desktop install. */
 export function windowsClaudeAppCandidates(environment = process.env, dependencies = {}) {
   const io = { readDirectory: fs.readdirSync, ...dependencies };
-  const overridden = environmentValue(environment, "IMPEL_CLAUDE_APP_BIN");
+  const overridden = environmentValue(environment, brandedEnvironmentName("CLAUDE_APP_BIN"));
   const localAppData = environmentValue(environment, "LOCALAPPDATA")
     || path.win32.join(environmentValue(environment, "USERPROFILE") || os.homedir(), "AppData", "Local");
   const programFiles = environmentValue(environment, "ProgramFiles");
@@ -103,8 +115,8 @@ export function findWindowsClaudeApp(environment = process.env, dependencies = {
 
 /** Candidate paths for an unpackaged OpenAI ChatGPT/Codex desktop install. */
 export function windowsChatGPTAppCandidates(environment = process.env) {
-  const overridden = environmentValue(environment, "IMPEL_CHATGPT_APP_BIN")
-    || environmentValue(environment, "IMPEL_CODEX_APP_BIN");
+  const overridden = environmentValue(environment, brandedEnvironmentName("CHATGPT_APP_BIN"))
+    || environmentValue(environment, brandedEnvironmentName("CODEX_APP_BIN"));
   const localAppData = environmentValue(environment, "LOCALAPPDATA")
     || path.win32.join(environmentValue(environment, "USERPROFILE") || os.homedir(), "AppData", "Local");
   const programFiles = environmentValue(environment, "ProgramFiles");
@@ -179,7 +191,7 @@ function pinnedWindowsClaudeApp(environment = process.env, dependencies = {}) {
     const result = io.run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
       encoding: "utf8",
       env: {
-        ...environment,
+        ...windowsPowerShellEnvironment(environment),
         IMPEL_CLAUDE_PACKAGE_VERSION: io.pin.packageVersion,
         IMPEL_CLAUDE_PACKAGE_PUBLISHER: io.pin.publisher,
         IMPEL_CLAUDE_PACKAGE_ARCHITECTURE: expectedArchitecture,
@@ -269,7 +281,7 @@ function installPinnedWindowsClaudeMsix(packagePath, environment, pin, architect
     {
       encoding: "utf8",
       env: {
-        ...environment,
+        ...windowsPowerShellEnvironment(environment),
         IMPEL_CLAUDE_MSIX_PATH: packagePath,
         IMPEL_CLAUDE_PACKAGE_NAME: pin.packageName,
         IMPEL_CLAUDE_PACKAGE_VERSION: pin.packageVersion,
@@ -289,8 +301,8 @@ function installPinnedWindowsClaudeMsix(packagePath, environment, pin, architect
 }
 
 function windowsClaudeCacheRoot(homeDir, environment, version, architecture) {
-  const appsRoot = environmentValue(environment, "IMPEL_APP_HOME")
-    || path.join(homeDir, ".config", "impel", "apps");
+  const appsRoot = environmentValue(environment, brandedEnvironmentName("APP_HOME"))
+    || path.join(homeDir, ".config", RUNTIME_BRAND.cli.configNamespace, "apps");
   return path.join(appsRoot, "vendor-cache", "claude", version, architecture);
 }
 
@@ -363,6 +375,7 @@ export function ensureWindowsChatGPTApp({ update = false } = {}, dependencies =
   const io = {
     environment: process.env,
     find: findWindowsChatGPTApp,
+    logger: console,
     run: spawnSync,
     ...dependencies,
   };
@@ -388,10 +401,25 @@ export function ensureWindowsChatGPTApp({ update = false } = {}, dependencies =
     result = { status: null, error };
   }
   const binary = io.find(io.environment) || before;
-  const succeeded = result?.status === 0 && !result?.error;
+  // winget uses an error HRESULT when `upgrade` finds an installed package
+  // with no newer Store release. That is a healthy idempotent update result,
+  // not an installation failure (APPINSTALLER_CLI_ERROR_UPDATE_NOT_APPLICABLE).
+  const alreadyUpToDate = Boolean(
+    shouldUpdate
+    && binary
+    && !result?.error
+    && Number.isInteger(result?.status)
+    && (result.status >>> 0) === WINDOWS_WINGET_UPDATE_NOT_APPLICABLE,
+  );
+  if (alreadyUpToDate) {
+    io.logger.log("ChatGPT/Codex: Microsoft Store package already up to date.");
+  }
+  const succeeded = (result?.status === 0 && !result?.error) || alreadyUpToDate;
   return {
     binary,
-    action: succeeded ? (shouldUpdate ? "updated" : "installed") : (before ? "existing" : "install-failed"),
+    action: alreadyUpToDate
+      ? "existing"
+      : succeeded ? (shouldUpdate ? "updated" : "installed") : (before ? "existing" : "install-failed"),
     result,
   };
 }