impel-cli 0.7.0 → 0.7.2

package/README.md

@@ -25,78 +25,91 @@ of the protected Store directory and launches it with tenant-specific Codex and
 browser profiles. Each approach keeps the user's normal app profile and
 signed-in account untouched.
 
-## Install
+## Start here
 
-Requires Node.js 18 or newer. The same command works on macOS, Linux, and
-Windows (PowerShell):
+You do not need GitHub access to install Impel. You need an Impel account and a
+computer with Node.js installed. Node.js includes the small installer tool
+called `npm` that installs Impel for you.
 
-```sh
-npm install --global impel-cli
-```
+### 1. Install Node.js and npm
 
-The installable package is intentionally public so Impel users do not need
-access to the private GitHub repository. It contains only this dependency-free
-CLI—no credentials, service secrets, or customer data. Installing it grants no
-Impel access: every protected operation still requires an Impel PAT and the
-gateway/control plane re-checks the user's live product access, scopes, and
-tenant membership.
+If `node --version` and `npm --version` already print version numbers, skip to
+the next step.
 
-Releases are published from the private repository with npm Trusted Publishing:
-the registry accepts a short-lived OIDC credential only from the pinned release
-workflow, so no long-lived npm token is stored in GitHub. npm also verifies the
-published tarball's advertised SHA-512 integrity during installation.
+- **Mac or Windows:** visit [nodejs.org/download](https://nodejs.org/en/download),
+  choose the **LTS** installer, and accept the default installer options.
+- **Linux:** follow Node's [official package-manager instructions](https://nodejs.org/en/download/package-manager)
+  for your distribution.
 
-Maintainers can exercise the Windows-specific paths from a Linux Docker engine
-with the real Windows Node binary and Wine's `cmd.exe` compatibility layer:
+After installing Node.js, close and reopen Terminal (Mac/Linux) or PowerShell
+(Windows), then check that it worked:
 
 ```sh
-docker build --platform linux/amd64 -f test/docker/windows-wine.Dockerfile -t impel-cli-windows-test .
-docker run --rm --platform linux/amd64 impel-cli-windows-test
+node --version
+npm --version
 ```
 
-The repository CI additionally runs the complete suite on `windows-latest`;
-that native job owns the hostile percent/caret npm-shim case that Wine does not
-faithfully emulate.
+Both commands should print a version number. Impel needs Node.js 18 or newer.
+
+### 2. Install Impel
 
-## Quickstart
+In Terminal or PowerShell, run:
 
 ```sh
-impel setup                # token → tenant → platform clients → verify
-impel claude               # launch Claude Code with an isolated Impel profile
-impel codex                # launch Codex with an isolated Impel profile
-impel update               # later: update the CLI, apps, and skills in one command
+npm install --global impel-cli
 ```
 
-`impel setup` walks through everything below in one command (create your PAT at
-`https://www.useimpel.com/settings/gateway`, paste it at the secure prompt, and
-the wizard does the rest). On Windows it installs either missing official vendor
-CLI from npm, prepares both tenant-isolated CLI profiles, installs the signed
-Claude and ChatGPT desktop apps with separate tenant profiles, and syncs skills.
-On macOS it installs the isolated desktop apps. The individual commands remain
-for piecemeal use:
+This downloads the public Impel command-line app. It does **not** give anyone
+access to your Impel account, workspace, or data.
+
+### 3. Connect your Impel account
+
+1. Open [Impel gateway settings](https://www.useimpel.com/settings/gateway).
+2. Create a Personal Access Token and copy it somewhere safe.
+3. Back in Terminal or PowerShell, run:
+
+   ```sh
+   impel setup
+   ```
+
+4. Paste the token when asked. The input is hidden, and Impel stores it only in
+   your local account configuration.
+5. Choose your organization when prompted and let the setup finish.
+
+Your token is the key to your account. Never paste it into a chat, ticket, or
+shared document.
+
+### 4. Start working
 
 ```sh
-impel auth                 # paste your PAT when prompted
-impel tenant list          # see every organization available to this user
-impel tenant use impel     # select the tenant for accounts, specialists, and history
-impel claude               # launch Claude Code with an isolated Impel profile
-impel codex                # launch Codex with an isolated Impel profile
-impel status               # isolated-launcher readiness, native mode, and reachability
-impel doctor               # make one synthetic request to each provider and measure routing/latency
-
-impel app install          # install both isolated desktop app profiles
-impel app update           # update vendor apps, configs, and supported models
-impel app open claude      # open Claude Desktop with its isolated Impel profile
-impel app open codex       # open ChatGPT/Codex Desktop with its isolated Impel profile
-
-# The normal `claude` and `codex` commands keep using your personal profiles.
+impel claude               # open an isolated Impel Claude Code session
+impel codex                # open an isolated Impel Codex session
+impel status               # check your connection and configuration
+impel update               # install the latest Impel CLI later
 ```
 
-Fresh `impel claude` profiles start on **Claude Opus 4.8 with 1M context** and
-also register **Claude Fable 5** in `/model`. You can choose a different
-persistent default there, or override one session with `--model`.
+`impel setup` keeps your normal Claude and Codex profiles separate. On Mac and
+Windows it also prepares the supported isolated desktop experiences. On Windows,
+it installs missing official vendor command-line tools when needed. On Linux,
+it prepares the isolated command-line workflow.
+
+### If something does not work
+
+- **`npm` or `node` is not recognized:** install Node.js from the link above,
+  then close and reopen Terminal or PowerShell.
+- **`impel` is not recognized:** close and reopen the terminal, then run
+  `npm install --global impel-cli` again.
+- **Your token is rejected:** create a fresh token in Impel gateway settings and
+  run `impel setup` again.
+- **You need a different organization:** run `impel tenant list`, then
+  `impel tenant use <organization>`.
+
+The npm package is public so Impel users do not need access to the private
+GitHub repository. The package contains no account credentials or service
+secrets; the Impel gateway and control plane still enforce your token, product
+access, scopes, and organization membership for every protected action.
 
-## Commands
+## Command reference
 
 ```
 impel setup [--pat <pat>] [--tenant <org>] [--skip-apps] [--skip-clis]
@@ -171,7 +184,7 @@ impel auth --pat impel_pat_xxxxxxxxxxxx --gateway https://gateway.useimpel.com -
 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, update the vendor apps, rebuild the vendored Impel apps)
+(close running apps, install the CLI-pinned vendor builds, rebuild the vendored Impel apps)
 and `impel skills sync all` across every managed profile.
 
 Update discovery compares the installed package version with npm's public
@@ -572,12 +585,14 @@ configuration:
   `~/.config/impel/apps/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.
-- Impel ChatGPT is an APFS-cloned vendored copy of the official app. Its wrapper
-  sets `CODEX_HOME`, passes a separate Chromium `--user-data-dir`, and writes its
-  provider config and model catalog below `~/.config/impel/apps/chatgpt`. It also
-  supplies a process-scoped, Codex-compatible wrapper around the Impel PAT so
-  native `/status` requests can read the organization's aggregated subscription
-  pool from the gateway. Its generated Codex config uses the same snapshot and
+- 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`,
+  passes a separate Chromium `--user-data-dir`, and writes its provider config
+  and model catalog below `~/.config/impel/apps/chatgpt`. It also supplies a
+  process-scoped, Codex-compatible wrapper around the Impel PAT so native
+  `/status` requests can read the organization's aggregated subscription pool
+  from the gateway. Its generated Codex config uses the same snapshot and
   subprocess-environment hardening as `impel codex`; install, update, and every
   direct app launch also remove older snapshots for the selected profile, while
   app install/update/open sweeps inactive tenant and legacy Impel app profiles.
@@ -585,22 +600,25 @@ configuration:
   normal vendor app's browser/profile data.
 
 The official Claude and ChatGPT apps remain separate installations and keep
-their normal accounts, updater, profiles, and bundle identities. The installer
-uses an existing official app when found. If one is missing and
-Homebrew is available, it installs the corresponding cask into
-`~/Applications`. `impel app update` upgrades Homebrew-managed vendor apps,
-rebuilds the isolated apps, reapplies version-checked compatibility patches,
-rewrites versioned configs, and fetches the PAT-scoped model catalog from
-`<gateway>/v1/models`. If a vendor update changes a required renderer contract,
-the update fails without replacing the working Impel copy. If the model endpoint
-is temporarily unavailable, the installer retains functionality using the CLI's
-bundled catalog.
+their normal accounts, updater, profiles, and bundle identities. Each CLI
+release pins exact, tested vendor builds (v0.7.2 pins Claude `1.20186.9` and
+ChatGPT `26.707.72221`) and their archive SHA-256 digests. The installer reuses
+an existing official app only when its version exactly matches; otherwise it
+downloads the pinned signed archive into Impel's managed vendor cache under
+`~/.config/impel/vendor`, verifies its digest, bundle version, layout, and code
+signature, and only then rebuilds the isolated app. It never clones a moving
+Homebrew or vendor “latest” release, and it never downgrades or replaces the
+user's normal vendor app. A future app version requires a new tested CLI release
+and pin update. Config refreshes do not download or replace apps. If the model
+endpoint is temporarily unavailable, the installer retains functionality using
+the CLI's bundled catalog.
 
 For ChatGPT/Codex, the gateway controls which models and capabilities are
 enabled while the installer merges those entries with the vendor app's native
 catalog. The Impel copy relaxes the vendor renderer's ChatGPT-account-only Fast
-gate because gateway auth supplies the entitlement instead. The copy is then
-ad-hoc signed locally. This preserves model-specific instructions and exposes
+gate because gateway auth supplies the entitlement instead. The outer wrapper
+is then ad-hoc signed locally without replacing the nested OpenAI signing
+identity. This preserves model-specific instructions and exposes
 the same reasoning-effort and service-tier controls as the normal app, including
 Ultra where supported and Fast only on models that advertise the `priority`
 tier. Inference uses an explicit non-WebSocket Impel model provider so Codex
@@ -609,8 +627,10 @@ Impel PAT. Config refreshes replace only the Impel-managed gateway block; plugin
 desktop preferences, projects, and other settings written by the isolated app
 are kept.
 
-Both vendored copies are ad-hoc signed locally after their bundle identities and
-launch wrappers are installed. The Claude 3P config necessarily contains the PAT because that app accepts a
+Impel Claude and the outer Impel ChatGPT wrapper are ad-hoc signed locally after
+their bundle identities and launch wrappers are installed. The nested ChatGPT
+bundle retains OpenAI's signature. The Claude 3P config necessarily contains
+the PAT because that app accepts a
 gateway API key rather than a token-helper command. It is stored in the same
 owner-only Impel config tree as the primary credential. ChatGPT/Codex uses a
 command-backed helper and does not copy the PAT into TOML. The installable app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "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/apps.js

@@ -21,18 +21,50 @@ const CLI_VERSION = JSON.parse(
 const APP_DEFINITIONS = {
   claude: {
     label: "Impel Claude",
-    cask: "claude",
     names: ["Claude.app"],
     executableNames: ["Claude"],
   },
   chatgpt: {
     label: "Impel ChatGPT",
-    cask: "codex-app",
     names: ["ChatGPT.app", "Codex.app"],
     executableNames: ["ChatGPT", "Codex"],
   },
 };
 
+// Vendor updates can change minified renderer contracts without notice. Each
+// CLI release therefore installs and accepts only the exact app builds tested
+// with its compatibility patches. Updating a pin requires a new CLI release.
+export const PINNED_VENDOR_APPS = Object.freeze({
+  claude: Object.freeze({
+    version: "1.20186.9",
+    bundleName: "Claude.app",
+    downloads: Object.freeze({
+      arm64: Object.freeze({
+        url: "https://downloads.claude.ai/releases/darwin/universal/1.20186.9/Claude-69f150a4c9316d5c8cd7b9f130ed583d15c0383e.zip",
+        sha256: "9364648c74bd525aa293a28103eb37262a5553de21c7ca907766d7fc40623015",
+      }),
+      x64: Object.freeze({
+        url: "https://downloads.claude.ai/releases/darwin/universal/1.20186.9/Claude-69f150a4c9316d5c8cd7b9f130ed583d15c0383e.zip",
+        sha256: "9364648c74bd525aa293a28103eb37262a5553de21c7ca907766d7fc40623015",
+      }),
+    }),
+  }),
+  chatgpt: Object.freeze({
+    version: "26.707.72221",
+    bundleName: "ChatGPT.app",
+    downloads: Object.freeze({
+      arm64: Object.freeze({
+        url: "https://persistent.oaistatic.com/codex-app-prod/ChatGPT-darwin-arm64-26.707.72221.zip",
+        sha256: "d47a2c0dfb07afec21c415fcec672035a2e90410ecb7c6dc60141518fba524e0",
+      }),
+      x64: Object.freeze({
+        url: "https://persistent.oaistatic.com/codex-app-prod/ChatGPT-darwin-x64-26.707.72221.zip",
+        sha256: "cadfdc8e1efa809b021bcf4466ae8c115ffdd280f1a467b518eca8ce8f6717fe",
+      }),
+    }),
+  }),
+});
+
 const STANDARD_REASONING_LEVELS = [
   { effort: "low", description: "Fast responses with lighter reasoning" },
   { effort: "medium", description: "Balances speed and reasoning depth for everyday tasks" },
@@ -42,6 +74,8 @@ const STANDARD_REASONING_LEVELS = [
 const MAX_REASONING_LEVEL = { effort: "max", description: "Maximum reasoning depth for the hardest problems" };
 const ULTRA_REASONING_LEVEL = { effort: "ultra", description: "Maximum reasoning with automatic task delegation" };
 const FAST_SERVICE_TIER = { id: "priority", name: "Fast", description: "1.5x speed, increased usage" };
+const FAST_MODE_AUTH_GATE = /([A-Za-z_$][\w$]*)=([A-Za-z_$][\w$]*)&&!([A-Za-z_$][\w$]*)&&([A-Za-z_$][\w$]*)!=null&&\4\?\.requirements\?\.featureRequirements\?\.fast_mode!==!1/gu;
+const CHATGPT_RESOURCE_ROOT = "linked_vendor_resources_with_patched_asar";
 const CLAUDE_PLAN_USAGE_GUARD = "if(!Ze().hasOrgPolicyBackend())return;if((r=fr())";
 const IMPEL_CLAUDE_PLAN_USAGE_GUARD = `${"if(!wze())return;".padEnd("if(!Ze().hasOrgPolicyBackend())return;".length, " ")}if((r=fr())`;
 const CLAUDE_PLAN_USAGE_REQUEST = 'P.net.fetch(`${ht()}/api/organizations/${o}/usage`,{signal:AbortSignal.timeout(mcr)})';
@@ -110,16 +144,37 @@ export function bundleIsCurrent(status) {
     compatibility
     && compatibility.cliVersion === CLI_VERSION
     && compatibility.vendorVersion === status.vendorVersion
+    && managedBundleMatchesCompatibility(status, compatibility)
     && (status.target !== "chatgpt" || (
       compatibility.vendorSignaturesPreserved === true
-      && compatibility.resourceRoot === "linked_vendor_resources"
+      && compatibility.resourceRoot === CHATGPT_RESOURCE_ROOT
+      && compatibility.patches?.fastModeForGatewayAuth > 0
     )),
   );
 }
 
+function managedBundleMatchesCompatibility(status, compatibility) {
+  try {
+    const managedVendorBundle = status.target === "claude"
+      ? status.launcher
+      : APP_DEFINITIONS.chatgpt.names
+        .map((name) => path.join(status.launcher, "Contents", "Resources", name))
+        .find((candidate) => fs.existsSync(candidate));
+    const runtimeAsar = path.join(status.launcher, "Contents", "Resources", "app.asar");
+    return Boolean(
+      managedVendorBundle
+      && bundleVersion(managedVendorBundle) === compatibility.vendorVersion
+      && compatibility.asarHeaderSha256
+      && asarHeaderHash(runtimeAsar) === compatibility.asarHeaderSha256
+    );
+  } catch {
+    return false;
+  }
+}
+
 // Install/update must not run while the vendor or Impel-managed apps are open:
-// `brew` refuses to upgrade a running cask, and cloning/replacing a bundle
-// under a running instance produces broken copies and codesign failures.
+// Cloning/replacing a bundle under a running instance produces broken copies
+// and codesign failures.
 
 /** osascript application names whose bundles install/update will touch. */
 export function blockingAppNames(targets) {
@@ -269,6 +324,9 @@ export function installManagedAppFiles({
     // token helper, catalog, and manifest only. Bundle swaps require the app
     // to be closed (see quitBlockingApps), so those paths never attempt one.
     if (bundleTargets.has(target)) {
+      if (resolvedVendorPaths[target] && isVendableVendorApp(target, resolvedVendorPaths[target])) {
+        assertPinnedVendorAppVersion(target, resolvedVendorPaths[target]);
+      }
       if (target === "chatgpt") writeVendoredChatGPTBundle(paths, resolvedVendorPaths.chatgpt, config.gatewayUrl);
       else writeVendoredClaudeBundle(paths, resolvedVendorPaths.claude, config.gatewayUrl);
     }
@@ -289,8 +347,11 @@ export function installManagedAppFiles({
   return installed;
 }
 
-function vendorSearchRoots(homeDir) {
-  return ["/Applications", path.join(homeDir, "Applications")];
+function vendorSearchRoots(homeDir, target) {
+  const roots = ["/Applications", path.join(homeDir, "Applications")];
+  const pin = PINNED_VENDOR_APPS[target];
+  if (pin) roots.push(path.join(homeDir, ".config", "impel", "vendor", target, pin.version));
+  return roots;
 }
 
 export function readBundleIdentifier(appPath) {
@@ -320,19 +381,26 @@ export function isVendableVendorApp(target, appPath) {
   );
 }
 
-export function findVendorApp(target, homeDir = os.homedir(), { roots = vendorSearchRoots(homeDir) } = {}) {
+export function findVendorApp(target, homeDir = os.homedir(), {
+  roots = vendorSearchRoots(homeDir, target),
+  version = PINNED_VENDOR_APPS[target]?.version,
+} = {}) {
   const definition = APP_DEFINITIONS[target];
   for (const base of roots) {
     for (const name of definition.names) {
       const candidate = path.join(base, name);
-      if (fs.existsSync(candidate) && isVendableVendorApp(target, candidate)) return candidate;
+      if (
+        fs.existsSync(candidate)
+        && isVendableVendorApp(target, candidate)
+        && (!version || bundleVersion(candidate) === version)
+      ) return candidate;
     }
   }
   return null;
 }
 
 /** Name-matched bundles that are NOT vendable — surfaced so "why was my app ignored?" is answerable. */
-export function rejectedVendorCandidates(target, homeDir = os.homedir(), { roots = vendorSearchRoots(homeDir) } = {}) {
+export function rejectedVendorCandidates(target, homeDir = os.homedir(), { roots = vendorSearchRoots(homeDir, target) } = {}) {
   const definition = APP_DEFINITIONS[target];
   const rejected = [];
   for (const base of roots) {
@@ -346,33 +414,103 @@ export function rejectedVendorCandidates(target, homeDir = os.homedir(), { roots
   return rejected;
 }
 
-export function ensureVendorApp(target, { homeDir = os.homedir(), update = false } = {}) {
+function unpinnedVendorCandidates(target, homeDir = os.homedir(), { roots = vendorSearchRoots(homeDir, target) } = {}) {
   const definition = APP_DEFINITIONS[target];
-  const current = findVendorApp(target, homeDir);
-  const brew = findCommand("brew");
-  if (!brew) return { path: current, action: current ? "existing" : "missing", note: "Homebrew is not installed" };
-
-  if (current && !update) return { path: current, action: "existing" };
-  if (current && update) {
-    const listed = spawnSync(brew, ["list", "--cask", definition.cask], { stdio: "ignore" });
-    if (listed.status !== 0) {
-      return { path: current, action: "existing", note: "vendor app is not Homebrew-managed; its built-in updater remains active" };
+  const expectedVersion = PINNED_VENDOR_APPS[target].version;
+  const candidates = [];
+  for (const base of roots) {
+    for (const name of definition.names) {
+      const candidate = path.join(base, name);
+      if (fs.existsSync(candidate) && isVendableVendorApp(target, candidate)) {
+        const version = bundleVersion(candidate);
+        if (version !== expectedVersion) candidates.push({ path: candidate, version });
+      }
+    }
+  }
+  return candidates;
+}
+
+export function assertPinnedVendorAppVersion(target, appPath) {
+  const expected = PINNED_VENDOR_APPS[target]?.version;
+  const actual = bundleVersion(appPath);
+  if (!expected || actual !== expected) {
+    throw new Error(
+      `${APP_DEFINITIONS[target]?.label || target} vendor version ${actual || "unknown"} is unsupported; impel-cli v${CLI_VERSION} requires the verified ${expected || "pinned"} build`,
+    );
+  }
+  return actual;
+}
+
+function installPinnedVendorApp(target, homeDir) {
+  const pin = PINNED_VENDOR_APPS[target];
+  const download = pin?.downloads?.[process.arch];
+  if (!pin || !download) throw new Error(`${target}: no verified vendor download is available for ${process.arch}`);
+
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), `impel-${target}-vendor-`));
+  const archive = path.join(tempRoot, `${target}.zip`);
+  const extractedRoot = path.join(tempRoot, "extracted");
+  try {
+    console.log(`${target}: downloading verified vendor app ${pin.version}…`);
+    const fetched = spawnSync(
+      "/usr/bin/curl",
+      ["--fail", "--location", "--progress-bar", "--retry", "2", "--output", archive, download.url],
+      { stdio: ["ignore", "inherit", "inherit"] },
+    );
+    if (fetched.status !== 0 || fetched.error) {
+      throw new Error(`${target}: failed to download verified vendor app ${pin.version}`);
+    }
+    const actualHash = sha256(fs.readFileSync(archive));
+    if (actualHash !== download.sha256) {
+      throw new Error(`${target}: vendor archive integrity check failed for ${pin.version}`);
+    }
+
+    fs.mkdirSync(extractedRoot, { recursive: true });
+    const extracted = spawnSync("/usr/bin/ditto", ["-x", "-k", archive, extractedRoot], { encoding: "utf8" });
+    if (extracted.status !== 0 || extracted.error) {
+      throw new Error(`${target}: failed to extract verified vendor app ${pin.version}`);
+    }
+    const extractedApp = path.join(extractedRoot, pin.bundleName);
+    if (!isVendableVendorApp(target, extractedApp)) {
+      throw new Error(`${target}: verified vendor archive ${pin.version} has an unsupported app layout`);
+    }
+    assertPinnedVendorAppVersion(target, extractedApp);
+    const verified = spawnSync("/usr/bin/codesign", ["--verify", "--deep", "--strict", extractedApp], { encoding: "utf8" });
+    if (verified.status !== 0 || verified.error) {
+      throw new Error(`${target}: vendor signature verification failed for ${pin.version}`);
     }
-    const upgraded = spawnSync(brew, ["upgrade", "--cask", definition.cask], { stdio: "inherit" });
-    return { path: findVendorApp(target, homeDir) || current, action: upgraded.status === 0 ? "updated" : "update-failed" };
+
+    const destination = path.join(
+      homeDir, ".config", "impel", "vendor", target, pin.version, pin.bundleName,
+    );
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    replaceDirectory(destination, extractedApp);
+    return destination;
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
   }
+}
+
+export function ensureVendorApp(target, { homeDir = os.homedir() } = {}) {
+  const definition = APP_DEFINITIONS[target];
+  const pin = PINNED_VENDOR_APPS[target];
+  const current = findVendorApp(target, homeDir);
+  if (current) return { path: current, action: "existing", note: `verified ${pin.version}` };
 
   // Name-collision transparency: e.g. OpenAI's native ChatGPT chat app
-  // (com.openai.chat) at /Applications/ChatGPT.app is NOT the Codex desktop
-  // app and cannot be vendored — say so instead of silently installing.
+  // (com.openai.chat) is NOT the Electron app and cannot be vendored.
   for (const candidate of rejectedVendorCandidates(target, homeDir)) {
     console.log(
-      `${target}: ignoring ${candidate.path} (${candidate.bundleId || "unknown bundle id"}) — not a vendorable ${definition.label.replace("Impel ", "")} desktop app; installing the \`${definition.cask}\` cask instead`,
+      `${target}: ignoring ${candidate.path} (${candidate.bundleId || "unknown bundle id"}) — not a vendorable ${definition.label.replace("Impel ", "")} desktop app`,
     );
   }
-  fs.mkdirSync(path.join(homeDir, "Applications"), { recursive: true });
-  const installed = spawnSync(brew, ["install", "--cask", `--appdir=${path.join(homeDir, "Applications")}`, definition.cask], { stdio: "inherit" });
-  return { path: findVendorApp(target, homeDir), action: installed.status === 0 ? "installed" : "install-failed" };
+  for (const candidate of unpinnedVendorCandidates(target, homeDir)) {
+    console.log(
+      `${target}: ignoring ${candidate.path} (${candidate.version || "unknown version"}) — this CLI is pinned to verified version ${pin.version}`,
+    );
+  }
+
+  const installed = installPinnedVendorApp(target, homeDir);
+  return { path: installed, action: "installed", note: `verified ${pin.version}` };
 }
 
 export function appStatus(targets, homeDir = os.homedir(), tenantId = null) {
@@ -749,12 +887,7 @@ function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl) {
         IMPEL_CLAUDE_PLAN_USAGE_GUARD,
         "Claude plan-usage eligibility guard",
       );
-      planUsageRequestPatchCount = patchFixedWidthAsarString(
-        asarPath,
-        CLAUDE_PLAN_USAGE_REQUEST,
-        IMPEL_CLAUDE_PLAN_USAGE_REQUEST,
-        "Claude plan-usage gateway request",
-      );
+      planUsageRequestPatchCount = patchClaudePlanUsageRequest(asarPath);
     }
     const newAsarHash = asarHeaderHash(asarPath);
 
@@ -825,22 +958,27 @@ function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl) {
     if (!fs.existsSync(asarPath) || !fs.existsSync(plistPath)) {
       const bundleId = readBundleIdentifier(vendorPath);
       const hint = bundleId === "com.openai.chat"
-        ? " — this is OpenAI's ChatGPT chat app, not the Codex desktop app; install the desktop app with `brew install --cask codex-app` and re-run"
+        ? " — this is OpenAI's non-Electron ChatGPT app, not the supported desktop build; re-run `impel app install chatgpt`"
         : bundleId
           ? ` (bundle id ${bundleId})`
           : "";
       throw new Error(`unsupported ChatGPT/Codex bundle layout in ${vendorPath}${hint}`);
     }
 
-    const asarHash = asarHeaderHash(asarPath);
-
     const macos = path.join(staging, "Contents", "MacOS");
-    writeAtomic(path.join(staging, "Contents", "Info.plist"), vendoredChatGPTWrapperPlist(vendorPath), 0o644);
     const vendorIcon = path.join(vendorBundle, "Contents", "Resources", "electron.icns");
     if (fs.existsSync(vendorIcon)) {
       fs.copyFileSync(vendorIcon, path.join(staging, "Contents", "Resources", "electron.icns"));
     }
     linkVendoredChatGPTResources(staging, vendorBundleName);
+    const runtimeAsarPath = path.join(staging, "Contents", "Resources", "app.asar");
+    const fastModePatchCount = patchFastModeAuthGate(runtimeAsarPath);
+    const asarHash = asarHeaderHash(runtimeAsarPath);
+    writeAtomic(
+      path.join(staging, "Contents", "Info.plist"),
+      vendoredChatGPTWrapperPlist(vendorPath, asarHash),
+      0o644,
+    );
     writeAtomic(
       path.join(macos, "launch"),
       vendoredChatGPTLauncher(paths, vendorBundleName, executableName, gatewayUrl),
@@ -851,9 +989,9 @@ function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl) {
       cliVersion: CLI_VERSION,
       vendorVersion: bundleVersion(vendorPath),
       sourceBundle: vendorPath,
-      patches: { fastModeForGatewayAuth: 0, desktopAPIForGatewayAuth: 0 },
+      patches: { fastModeForGatewayAuth: fastModePatchCount, desktopAPIForGatewayAuth: 0 },
       vendorSignaturesPreserved: true,
-      resourceRoot: "linked_vendor_resources",
+      resourceRoot: CHATGPT_RESOURCE_ROOT,
       asarHeaderSha256: asarHash,
     }, null, 2) + "\n", 0o644);
 
@@ -870,11 +1008,17 @@ function linkVendoredChatGPTResources(bundle, vendorBundleName) {
   const vendorResources = path.join(outerResources, vendorBundleName, "Contents", "Resources");
   for (const entry of fs.readdirSync(vendorResources, { withFileTypes: true })) {
     // The wrapper owns its icon and compatibility record. Every other vendor
-    // resource is exposed at the outer Electron resource root through a
-    // relative link, leaving the OpenAI-signed nested bundle untouched.
+    // resource is exposed at the outer Electron resource root, leaving the
+    // OpenAI-signed nested bundle untouched. app.asar is the sole copied file
+    // because the runtime needs the narrowly scoped compatibility patch below.
     if (entry.name === "electron.icns") continue;
     const target = path.join(vendorBundleName, "Contents", "Resources", entry.name);
-    fs.symlinkSync(target, path.join(outerResources, entry.name));
+    const destination = path.join(outerResources, entry.name);
+    // Electron resolves app.asar from the outer wrapper's resource root. Keep
+    // the nested OpenAI bundle byte-for-byte signed, but use a patched copy at
+    // runtime so gateway-authenticated profiles retain the native Fast control.
+    if (entry.name === "app.asar") fs.copyFileSync(path.join(vendorResources, entry.name), destination);
+    else fs.symlinkSync(target, destination);
   }
 }
 
@@ -883,17 +1027,88 @@ function patchFixedWidthAsarString(asarPath, original, replacement, label) {
     throw new Error(`${label} replacement must preserve the vendor ASAR byte length`);
   }
   const archive = fs.readFileSync(asarPath);
-  const metadata = readAsarMetadata(archive);
   const source = archive.toString("latin1");
-  const patchOffsets = [];
+  const patches = [];
   for (let offset = source.indexOf(original); offset !== -1; offset = source.indexOf(original, offset + original.length)) {
-    patchOffsets.push(offset);
+    patches.push({ offset, original, replacement });
+  }
+  return applyFixedWidthAsarPatches(asarPath, archive, patches, label);
+}
+
+function patchClaudePlanUsageRequest(asarPath) {
+  const archive = fs.readFileSync(asarPath);
+  const source = archive.toString("latin1");
+  const legacyPatches = [];
+  for (
+    let offset = source.indexOf(CLAUDE_PLAN_USAGE_REQUEST);
+    offset !== -1;
+    offset = source.indexOf(CLAUDE_PLAN_USAGE_REQUEST, offset + CLAUDE_PLAN_USAGE_REQUEST.length)
+  ) {
+    legacyPatches.push({
+      offset,
+      original: CLAUDE_PLAN_USAGE_REQUEST,
+      replacement: IMPEL_CLAUDE_PLAN_USAGE_REQUEST,
+    });
+  }
+  if (legacyPatches.length > 0) {
+    return applyFixedWidthAsarPatches(
+      asarPath, archive, legacyPatches, "Claude plan-usage gateway request",
+    );
+  }
+  const credentialAccessor = source.match(
+    /function ([A-Za-z_$][\w$]*)\(e\)\{var t;return [\s\S]{0,500}?\[custom-3p\] Credentials loaded from managed config/u,
+  )?.[1];
+  if (!credentialAccessor) {
+    return applyFixedWidthAsarPatches(asarPath, archive, [], "Claude plan-usage gateway request");
+  }
+  const configAccessorPattern = new RegExp(
+    `${escapeRegex(credentialAccessor)}\\(([A-Za-z_$][\\w$]*)\\(\\)\\)`,
+    "u",
+  );
+  const configAccessor = source.match(configAccessorPattern)?.[1];
+  if (!configAccessor) {
+    return applyFixedWidthAsarPatches(asarPath, archive, [], "Claude plan-usage gateway request");
   }
-  if (patchOffsets.length === 0) {
+
+  const requestPattern = /([A-Za-z_$][\w$]*)\.net\.fetch\(`\$\{[A-Za-z_$][\w$]*\(\)\}\/api\/organizations\/\$\{[A-Za-z_$][\w$]*\}\/usage`,\{signal:AbortSignal\.timeout\([A-Za-z_$][\w$]*\)\}\)/gu;
+  const patches = [...source.matchAll(requestPattern)].map((match) => {
+    const original = match[0];
+    const replacement = `${match[1]}.net.fetch("https://gateway.useimpel.com/ui/a/u",{headers:{key:${credentialAccessor}(${configAccessor}()).apiKey}})`;
+    if (replacement.length > original.length) {
+      throw new Error("Claude plan-usage gateway request replacement no longer fits the vendor ASAR contract");
+    }
+    return { offset: match.index, original, replacement: replacement.padEnd(original.length, " ") };
+  });
+  return applyFixedWidthAsarPatches(asarPath, archive, patches, "Claude plan-usage gateway request");
+}
+
+function patchFastModeAuthGate(asarPath) {
+  const archive = fs.readFileSync(asarPath);
+  const source = archive.toString("latin1");
+  const patches = [...source.matchAll(FAST_MODE_AUTH_GATE)].map((match) => {
+    const replacement = `${match[1]}=!${match[3]}`;
+    return {
+      offset: match.index,
+      original: match[0],
+      replacement: replacement.padEnd(match[0].length, " "),
+    };
+  });
+  return applyFixedWidthAsarPatches(asarPath, archive, patches, "ChatGPT/Codex Fast-mode eligibility contract");
+}
+
+function applyFixedWidthAsarPatches(asarPath, archive, patches, label) {
+  if (patches.length === 0) {
     throw new Error(`this desktop app version has an unsupported ${label}; update impel-cli before installing it`);
   }
-  const patchedArchive = Buffer.from(source.replaceAll(original, replacement), "latin1");
-  const entries = new Set(patchOffsets.map((offset) => findAsarEntry(metadata.header, metadata.dataOffset, offset)));
+  const metadata = readAsarMetadata(archive);
+  const patchedArchive = Buffer.from(archive);
+  for (const { offset, original, replacement } of patches) {
+    if (Buffer.byteLength(original, "latin1") !== Buffer.byteLength(replacement, "latin1")) {
+      throw new Error(`${label} replacement must preserve the vendor ASAR byte length`);
+    }
+    Buffer.from(replacement, "latin1").copy(patchedArchive, offset);
+  }
+  const entries = new Set(patches.map(({ offset }) => findAsarEntry(metadata.header, metadata.dataOffset, offset)));
   for (const entry of entries) updateAsarEntryIntegrity(patchedArchive, metadata.dataOffset, entry);
   const header = Buffer.from(JSON.stringify(metadata.header));
   if (header.length !== metadata.headerLength) {
@@ -901,7 +1116,7 @@ function patchFixedWidthAsarString(asarPath, original, replacement, label) {
   }
   header.copy(patchedArchive, 16);
   fs.writeFileSync(asarPath, patchedArchive);
-  return patchOffsets.length;
+  return patches.length;
 }
 
 function cloneAppBundle(source, destination) {
@@ -1039,7 +1254,7 @@ function rebrandElectronHelpers(bundle, { fromName, toName, fromIdentifier, toId
   }
 }
 
-function vendoredChatGPTWrapperPlist(vendorPath) {
+function vendoredChatGPTWrapperPlist(vendorPath, asarHash) {
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0"><dict>
@@ -1050,6 +1265,7 @@ function vendoredChatGPTWrapperPlist(vendorPath) {
 <key>CFBundleName</key><string>Impel ChatGPT</string>
 <key>CFBundlePackageType</key><string>APPL</string>
 <key>CFBundleShortVersionString</key><string>${xmlEscape(bundleVersion(vendorPath) || "1")}</string>
+<key>ElectronAsarIntegrity</key><dict><key>Resources/app.asar</key><dict><key>algorithm</key><string>SHA256</string><key>hash</key><string>${xmlEscape(asarHash)}</string></dict></dict>
 <key>LSMinimumSystemVersion</key><string>12.0</string>
 <key>NSHighResolutionCapable</key><true/>
 </dict></plist>
@@ -1191,9 +1407,26 @@ function isMachO(file) {
 }
 
 function asarHeaderHash(file) {
-  const archive = fs.readFileSync(file);
-  const { headerLength } = readAsarMetadata(archive);
-  return sha256(archive.subarray(16, 16 + headerLength));
+  const handle = fs.openSync(file, "r");
+  try {
+    const prefix = Buffer.alloc(16);
+    if (fs.readSync(handle, prefix, 0, prefix.length, 0) !== prefix.length) {
+      throw new Error("desktop app ASAR header is invalid");
+    }
+    const headerLength = prefix.readUInt32LE(12);
+    const dataOffset = 8 + prefix.readUInt32LE(4);
+    const fileSize = fs.fstatSync(handle).size;
+    if (headerLength <= 0 || 16 + headerLength > dataOffset || dataOffset > fileSize) {
+      throw new Error("desktop app ASAR offsets are invalid");
+    }
+    const header = Buffer.alloc(headerLength);
+    if (fs.readSync(handle, header, 0, header.length, 16) !== header.length) {
+      throw new Error("desktop app ASAR header is truncated");
+    }
+    return sha256(header);
+  } finally {
+    fs.closeSync(handle);
+  }
 }
 
 function sha256(contents) {
@@ -1241,11 +1474,6 @@ function bundleVersion(bundle) {
   }
 }
 
-function findCommand(command) {
-  const result = spawnSync("/usr/bin/which", [command], { encoding: "utf8" });
-  return result.status === 0 ? result.stdout.trim() : null;
-}
-
 function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'"'"'`)}'`;
 }

package/src/commands/apps.js

@@ -352,19 +352,18 @@ export async function cmdApps(argv, overrides = {}) {
 
   const config = await selectedAppConfig(targets);
 
-  // A running vendor or Impel app makes the cask upgrade / bundle swap fail.
+  // A running vendor or Impel app makes the pinned vendor install / bundle swap fail.
   await quitBlockingApps(targets);
 
   const vendorPaths = {};
   if (!flags["skip-vendor"]) {
     for (const target of targets) {
-      // Always bring the vendor (system) app to the latest version before
-      // cloning it into the vendored Impel bundle, so install and update both
-      // start from a current copy. A failed upgrade keeps the existing app.
-      const result = ensureVendorApp(target, { update: true });
+      // 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);
       vendorPaths[target] = result.path;
       console.log(`${target}: vendor app ${result.action}${result.note ? ` (${result.note})` : ""}`);
-      if (!result.path) throw new Error(`${target} vendor app is unavailable; install it manually or fix Homebrew, then re-run`);
+      if (!result.path) throw new Error(`${target} verified vendor app is unavailable; retry the pinned download`);
     }
   }
 

package/src/commands/setup.js

@@ -225,7 +225,7 @@ export async function cmdSetup(argv, overrides = {}) {
 
   // ── Step 3: apps ─────────────────────────────────────────────────────────
   // Order inside `impel app install`: close running Claude/ChatGPT apps (a
-  // running app makes the install fail), bring the vendor apps to the latest
+  // running app makes the install fail), bring the vendor apps to the verified
   // version, then build the vendored Impel bundles from that fresh copy.
   // Native Claude Code and Codex profiles are never touched.
   let platformSetupFailed = false;
@@ -301,7 +301,7 @@ export async function cmdSetup(argv, overrides = {}) {
     );
   } else {
     console.log(
-      "3/4 Installing the Impel desktop apps (running Claude/ChatGPT apps are closed, vendor apps updated first)…"
+      "3/4 Installing the Impel desktop apps (running Claude/ChatGPT apps are closed, verified vendor builds installed first)…"
     );
     try {
       await io.installApps(["install", "all"]);

package/src/commands/update.js

@@ -196,7 +196,7 @@ 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, vendor apps updated, bundles rebuilt)…");
+      : "Apps: updating (running apps are closed, verified vendor builds installed, bundles rebuilt)…");
     if (!io.runAppsUpdate()) {
       console.error("impel update: the app update failed; re-run `impel app update` after fixing the issue.");
       cascadeFailed = true;