impel-cli 0.18.1 → 0.18.3

package/README.md

@@ -22,6 +22,11 @@ npm install --global impel-cli
 
 Node.js 18 or newer is required.
 
+On macOS, setup and update verify Apple's Xcode Command Line Tools before any
+profile, app, or skills work begins. If they are missing, Impel opens the
+system installer with `xcode-select --install` and stops safely; finish that
+installation, then rerun the same Impel command.
+
 Then run setup and paste an Impel Personal Access Token when prompted:
 
 ```sh
@@ -35,17 +40,19 @@ surfaces for each tenant. You do not need to repeat setup tenant by tenant.
 
 `impel setup`:
 
-1. Stores the PAT in the private Impel config file.
-2. Fetches the complete live tenant list.
-3. Preserves the current CLI tenant when it is still accessible, or selects the
+1. On macOS, verifies the Xcode Command Line Tools and opens Apple's installer
+   before doing any other setup work when they are missing.
+2. Stores the PAT in the private Impel config file.
+3. Fetches the complete live tenant list.
+4. Preserves the current CLI tenant when it is still accessible, or selects the
    control-plane default.
-4. Creates isolated Claude and Codex CLI profiles for every supported tenant.
-5. On Windows machines without git, installs a pinned, checksum-verified
+5. Creates isolated Claude and Codex CLI profiles for every supported tenant.
+6. On Windows machines without git, installs a pinned, checksum-verified
    MinGit into `~/.config/impel/tools/git` (no admin rights, no system PATH
    change) so Claude and Codex can install the Impel skills marketplace.
-6. Installs or repairs supported tenant desktop apps on macOS and Windows.
-7. Registers tenant apps with Finder/Spotlight or Windows Start/Search.
-8. Verifies every supported tenant surface and prints a tenant-sorted summary.
+7. Installs or repairs supported tenant desktop apps on macOS and Windows.
+8. Registers tenant apps with Finder/Spotlight or Windows Start/Search.
+9. Verifies every supported tenant surface and prints a tenant-sorted summary.
 
 Use `--tenant` only to choose the default for CLI launches. It does not limit
 which tenants setup prepares:
@@ -117,13 +124,15 @@ impel update
 
 Update:
 
-1. Checks and installs the latest `impel-cli` package from npm.
-2. Continues under the freshly installed build.
-3. Fetches the current live tenant list.
-4. Fully prepares tenants added since the previous run.
-5. Repairs and upgrades existing tenants in place.
-6. Re-registers operating-system launch entries.
-7. Reports local tenants that are no longer accessible without deleting them.
+1. On macOS, verifies the Xcode Command Line Tools and opens Apple's installer
+   before doing any other update work when they are missing.
+2. Checks and installs the latest `impel-cli` package from npm.
+3. Continues under the freshly installed build.
+4. Fetches the current live tenant list.
+5. Fully prepares tenants added since the previous run.
+6. Repairs and upgrades existing tenants in place.
+7. Re-registers operating-system launch entries.
+8. Reports local tenants that are no longer accessible without deleting them.
 
 An update preserves histories, browser state, preferences, permissions, stable
 app identity, and user-authored settings outside Impel-managed blocks. Desktop
@@ -246,6 +255,11 @@ compatibility for one release, but no command can enable native routing.
 ### Windows
 
 - Missing official Claude Code and Codex CLIs can be installed during setup.
+- Claude Desktop is downloaded from Anthropic as the exact x64 or arm64 MSIX
+  pinned by this CLI. Its SHA-256, Authenticode signature, package identity,
+  version, architecture, and required layout are checked before installation.
+- ChatGPT/Codex uses the Microsoft Store package: a missing package is installed
+  during either setup or update, while an existing package is upgraded.
 - Signed vendor desktop executables remain unchanged.
 - Tenant profiles and Start entries are isolated per tenant.
 - Shared package-manager/vendor preparation runs once per product.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {

package/src/apps.js

@@ -53,6 +53,22 @@ export const PINNED_VENDOR_APPS = Object.freeze({
     claudeCodeVersion: "2.1.209",
     claudeCodeCommit: "0fe048596fd45e79e99353cbe2c3d1b1ac069568",
     bundleName: "Claude.app",
+    windows: Object.freeze({
+      packageName: "Claude",
+      packageVersion: "1.20186.9.0",
+      publisher: 'CN="Anthropic, PBC", O="Anthropic, PBC", L=San Francisco, S=California, C=US, SERIALNUMBER=4860621, OID.2.5.4.15=Private Organization, OID.1.3.6.1.4.1.311.60.2.1.2=Delaware, OID.1.3.6.1.4.1.311.60.2.1.3=US',
+      executable: "app\\Claude.exe",
+      downloads: Object.freeze({
+        arm64: Object.freeze({
+          url: "https://downloads.claude.ai/releases/win32/arm64/1.20186.9/Claude-69f150a4c9316d5c8cd7b9f130ed583d15c0383e.msix",
+          sha256: "9a0591a0d9e298dea92d5547ee259f35e818ce0b1982512ad1550f5ed2744c39",
+        }),
+        x64: Object.freeze({
+          url: "https://downloads.claude.ai/releases/win32/x64/1.20186.9/Claude-69f150a4c9316d5c8cd7b9f130ed583d15c0383e.msix",
+          sha256: "55a0b8f8c3c8d46cd64a03d3f42818da28f312cd4be904265cd61baee7ea68a5",
+        }),
+      }),
+    }),
     downloads: Object.freeze({
       arm64: Object.freeze({
         url: "https://downloads.claude.ai/releases/darwin/universal/1.20186.9/Claude-69f150a4c9316d5c8cd7b9f130ed583d15c0383e.zip",
@@ -726,7 +742,12 @@ export function installManagedAppFiles({
       if (resolvedVendorPaths[target] && isVendableVendorApp(target, resolvedVendorPaths[target])) {
         assertPinnedVendorAppVersion(target, resolvedVendorPaths[target]);
       }
-      if (target === "chatgpt") writeVendoredChatGPTBundle(paths, resolvedVendorPaths.chatgpt, config.gatewayUrl);
+      if (target === "chatgpt") writeVendoredChatGPTBundle(
+        paths,
+        resolvedVendorPaths.chatgpt,
+        config.gatewayUrl,
+        homeDir,
+      );
       else writeVendoredClaudeBundle(
         paths,
         resolvedVendorPaths.claude,
@@ -1561,7 +1582,7 @@ function claudeUsageCompatibilityEnabled(gatewayUrl) {
   }
 }
 
-function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl) {
+function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl, homeDir) {
   if (!vendorPath) throw new Error("ChatGPT/Codex vendor app is unavailable");
   const definition = APP_DEFINITIONS.chatgpt;
   const executableName = definition.executableNames.find((name) => (
@@ -1600,7 +1621,7 @@ function writeVendoredChatGPTBundle(paths, vendorPath, gatewayUrl) {
     const asarHash = asarHeaderHash(runtimeAsarPath);
     const vendorExecutable = path.join(vendorBundle, "Contents", "MacOS", executableName);
     const signingIdentity = resolveVendoredAppSigningIdentity(vendorExecutable);
-    const launchHost = ensureChatGPTLaunchHost();
+    const launchHost = ensureChatGPTLaunchHost({ cacheDir: chatGPTLaunchHostCacheDir(homeDir) });
     writeAtomic(
       path.join(staging, "Contents", "Info.plist"),
       vendoredChatGPTWrapperPlist(vendorPath, asarHash, paths.chatgpt, launchHost ? "launch-host" : "launch"),
@@ -2083,7 +2104,7 @@ export function ensureChatGPTLaunchHost({
   platform = process.platform,
   osRelease = os.release(),
   compiler = "/usr/bin/cc",
-  cacheDir = fileURLToPath(new URL("../cache", import.meta.url)),
+  cacheDir = chatGPTLaunchHostCacheDir(),
   warn = console.warn,
 } = {}) {
   if (platform !== "darwin") return null;
@@ -2127,6 +2148,10 @@ export function ensureChatGPTLaunchHost({
   }
 }
 
+export function chatGPTLaunchHostCacheDir(homeDir = os.homedir()) {
+  return path.join(homeDir, ".config", "impel", "cache", "chatgpt-launch-host");
+}
+
 function vendoredChatGPTWrapperPlist(vendorPath, asarHash, identity, executableName = "launch") {
   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">

package/src/cli.js

@@ -20,6 +20,7 @@ import { cmdUpdate } from "./commands/update.js";
 import { cmdNuke } from "./commands/nuke.js";
 import { cmdExperimental } from "./commands/experimental.js";
 import { cmdConverge } from "./commands/converge.js";
+import { ensureMacDeveloperTools } from "./macDeveloperTools.js";
 import { refuseElevatedMacExecution } from "./privileges.js";
 
 const HELP = `impel — isolated Impel workspaces for every tenant
@@ -82,6 +83,7 @@ function normalizeTarget(token) {
 
 export async function main(argv) {
   if (refuseElevatedMacExecution(argv)) return;
+  if (!ensureMacDeveloperTools(argv)) return;
   const [cmd, ...rest] = argv;
 
   switch (cmd) {

package/src/commands/apps.js

@@ -402,7 +402,7 @@ export async function reconcileWindowsTenantApps({
         fail(target, `${label} vendor ${mode === "update" ? "update" : "installation"} requires confirmation`);
         continue;
       }
-      const vendor = ensure({ update: mode === "update" }, { environment });
+      const vendor = await ensure({ update: mode === "update" }, { environment, homeDir });
       binary = vendor.binary;
       if (!binary) {
         fail(target, `${label} vendor installation failed (${windowsProcessFailure(vendor.result)})`);
@@ -741,7 +741,10 @@ export async function cmdWindowsApps(argv, overrides = {}) {
         || (action === "open" && !binary)
       );
       if (shouldEnsureVendor) {
-        const vendor = ensure({ update: action === "update" }, { environment: io.environment });
+        const vendor = await ensure(
+          { update: action === "update" },
+          { environment: io.environment, homeDir: io.homeDir },
+        );
         binary = vendor.binary;
         console.log(`${target}: vendor app ${vendor.action}`);
         if (!binary) {

package/src/macDeveloperTools.js

@@ -0,0 +1,65 @@
+import { spawnSync } from "node:child_process";
+
+const XCODE_SELECT = "/usr/bin/xcode-select";
+
+function hasHelpFlag(argv) {
+  return argv[0] === "help" || argv.slice(1).some((arg) => ["--help", "-h"].includes(arg));
+}
+
+/**
+ * Commands that may clone a skills marketplace or build a managed macOS app.
+ * Read-only commands deliberately stay available while Apple's installer is
+ * pending, and `update --check` keeps its documented no-mutation contract.
+ */
+export function commandRequiresMacDeveloperTools(argv = []) {
+  const [command, subcommand] = argv;
+  if (!command || hasHelpFlag(argv)) return false;
+
+  if (["setup", "_converge"].includes(command)) return true;
+  if (["update", "upgrade"].includes(command)) {
+    return !argv.includes("--check") && !argv.includes("--refresh-cache");
+  }
+  if (["skill", "skills"].includes(command)) return !subcommand || subcommand === "sync";
+  if (["app", "apps"].includes(command)) {
+    return ["install", "update", "open", "refresh"].includes(subcommand);
+  }
+  return false;
+}
+
+/**
+ * Ensure Apple's Command Line Tools are available before Impel mutates any
+ * lifecycle state that depends on git or the native compiler. The Apple
+ * installer runs asynchronously, so a newly requested install must stop this
+ * invocation and let the operator rerun it after installation finishes.
+ */
+export function ensureMacDeveloperTools(argv = [], dependencies = {}) {
+  const io = {
+    platform: process.platform,
+    spawn: spawnSync,
+    log: (message) => console.log(message),
+    error: (message) => console.error(message),
+    setExitCode: (code) => {
+      process.exitCode = code;
+    },
+    ...dependencies,
+  };
+  if (io.platform !== "darwin" || !commandRequiresMacDeveloperTools(argv)) return true;
+
+  const selected = io.spawn(XCODE_SELECT, ["-p"], { stdio: "ignore" });
+  if (!selected.error && selected.status === 0) return true;
+
+  io.log("Xcode Command Line Tools are required; opening Apple's installer…");
+  const requested = io.spawn(XCODE_SELECT, ["--install"], { stdio: "inherit" });
+  if (requested.error) {
+    io.error(`impel: could not start the Xcode Command Line Tools installer (${requested.error.message || requested.error}).`);
+    io.error("  Run `xcode-select --install`, finish the system installation, then rerun this Impel command.");
+  } else if (requested.status !== 0) {
+    io.error("impel: the Xcode Command Line Tools installer did not start successfully.");
+    io.error("  Run `xcode-select --install`, finish the system installation, then rerun this Impel command.");
+  } else {
+    io.error("impel: finish installing the Xcode Command Line Tools in the system dialog, then rerun this command.");
+    io.error("  No Impel profiles, apps, or skills were changed.");
+  }
+  io.setExitCode(1);
+  return false;
+}

package/src/windowsApps.js

@@ -3,14 +3,17 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
 
+import { PINNED_VENDOR_APPS } from "./apps.js";
 import { environmentValue, nativeCommandInvocation } from "./nativeProcess.js";
 import { normalizeTenantId } from "./tenants.js";
 
-export const WINDOWS_CLAUDE_PACKAGE = "Anthropic.Claude";
 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;
 
 export function windowsClaudeUserData(environment = process.env, tenantId = null) {
   const localAppData = environmentValue(environment, "LOCALAPPDATA")
@@ -45,24 +48,6 @@ function versionedSquirrelCandidates(root, readDirectory = fs.readdirSync) {
   }
 }
 
-function installedMsixClaude(environment, run = spawnSync) {
-  const script = [
-    "$package = Get-AppxPackage -Name Claude | Sort-Object Version -Descending | Select-Object -First 1",
-    "if ($package) { Join-Path $package.InstallLocation 'app\\Claude.exe' }",
-  ].join("; ");
-  try {
-    const result = run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
-      encoding: "utf8",
-      env: environment,
-      stdio: ["ignore", "pipe", "ignore"],
-      windowsHide: true,
-    });
-    return result?.status === 0 ? String(result.stdout || "").trim() || null : null;
-  } catch {
-    return null;
-  }
-}
-
 function installedMsixChatGPT(environment, run = spawnSync) {
   const script = [
     `$package = Get-AppxPackage -Name '${WINDOWS_CHATGPT_PACKAGE_NAME}' -ErrorAction SilentlyContinue`,
@@ -108,11 +93,12 @@ export function windowsClaudeAppCandidates(environment = process.env, dependenci
 }
 
 export function findWindowsClaudeApp(environment = process.env, dependencies = {}) {
-  const exists = dependencies.isFile || isFile;
-  const unpackaged = windowsClaudeAppCandidates(environment, dependencies).find((candidate) => exists(candidate));
-  if (unpackaged) return unpackaged;
-  const msix = (dependencies.queryMsix || installedMsixClaude)(environment, dependencies.run);
-  return msix && exists(msix) ? path.win32.normalize(msix) : null;
+  if (dependencies.queryMsix) {
+    const msix = dependencies.queryMsix(environment, dependencies.run);
+    const exists = dependencies.isFile || isFile;
+    return msix && exists(msix) ? path.win32.normalize(msix) : null;
+  }
+  return pinnedWindowsClaudeApp(environment, dependencies);
 }
 
 /** Candidate paths for an unpackaged OpenAI ChatGPT/Codex desktop install. */
@@ -166,37 +152,210 @@ function wingetInvocation(action, environment, { packageId, source = "winget", s
   );
 }
 
-/** Install/update Anthropic's signed per-user app without modifying its files. */
-export function ensureWindowsClaudeApp({ update = false } = {}, dependencies = {}) {
+function windowsClaudeArchitecture(environment, fallback = process.arch) {
+  const detected = environmentValue(environment, "PROCESSOR_ARCHITEW6432")
+    || environmentValue(environment, "PROCESSOR_ARCHITECTURE")
+    || fallback;
+  if (/arm64/iu.test(detected)) return "arm64";
+  if (/amd64|x64/iu.test(detected)) return "x64";
+  return fallback;
+}
+
+function pinnedWindowsClaudeApp(environment = process.env, dependencies = {}) {
   const io = {
-    environment: process.env,
-    find: findWindowsClaudeApp,
     run: spawnSync,
+    isFile,
+    pin: PINNED_VENDOR_APPS.claude.windows,
+    architecture: windowsClaudeArchitecture(environment),
     ...dependencies,
   };
-  const before = io.find(io.environment);
-  if (before && !update) return { binary: before, action: "existing", result: null };
-
-  const invocation = wingetInvocation(update ? "update" : "install", io.environment, {
-    packageId: WINDOWS_CLAUDE_PACKAGE,
-  });
-  let result;
+  const expectedArchitecture = io.architecture === "arm64" ? "Arm64" : "X64";
+  const script = [
+    "$package = Get-AppxPackage -Name 'Claude' -ErrorAction SilentlyContinue",
+    "$package = $package | Where-Object { $_.Version.ToString() -ceq $env:IMPEL_CLAUDE_PACKAGE_VERSION -and $_.Publisher -ceq $env:IMPEL_CLAUDE_PACKAGE_PUBLISHER -and $_.Architecture.ToString() -ieq $env:IMPEL_CLAUDE_PACKAGE_ARCHITECTURE } | Select-Object -First 1",
+    "if ($package) { Join-Path $package.InstallLocation $env:IMPEL_CLAUDE_PACKAGE_EXECUTABLE }",
+  ].join("; ");
   try {
-    result = io.run(invocation.command, invocation.args, {
-      env: io.environment,
-      stdio: "inherit",
-      windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+    const result = io.run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+      encoding: "utf8",
+      env: {
+        ...environment,
+        IMPEL_CLAUDE_PACKAGE_VERSION: io.pin.packageVersion,
+        IMPEL_CLAUDE_PACKAGE_PUBLISHER: io.pin.publisher,
+        IMPEL_CLAUDE_PACKAGE_ARCHITECTURE: expectedArchitecture,
+        IMPEL_CLAUDE_PACKAGE_EXECUTABLE: io.pin.executable,
+      },
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
     });
+    const binary = result?.status === 0 ? String(result.stdout || "").trim() : "";
+    return binary && io.isFile(binary) ? path.win32.normalize(binary) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function downloadWindowsClaudeMsix(url, destination, fetchImpl, timeoutMs) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(url, { signal: controller.signal, redirect: "follow" });
+    if (!response?.ok || !response.body) {
+      throw new Error(`Claude MSIX download failed (HTTP ${response?.status ?? "error"})`);
+    }
+    await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(destination, { flags: "wx" }));
   } catch (error) {
-    result = { status: null, error };
+    if (error?.name === "AbortError") {
+      throw new Error(`Claude MSIX download timed out after ${timeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
   }
-  const binary = io.find(io.environment) || before;
-  const succeeded = result?.status === 0 && !result?.error;
-  return {
-    binary,
-    action: succeeded ? (update ? "updated" : "installed") : (before ? "existing" : "install-failed"),
-    result,
+}
+
+const INSTALL_PINNED_CLAUDE_MSIX = String.raw`
+$ErrorActionPreference = 'Stop'
+$packagePath = $env:IMPEL_CLAUDE_MSIX_PATH
+if (-not (Test-Path -LiteralPath $packagePath -PathType Leaf)) {
+  throw 'the verified Claude MSIX is missing'
+}
+
+$signature = Get-AuthenticodeSignature -LiteralPath $packagePath
+if ($signature.Status.ToString() -cne 'Valid') {
+  throw "Claude MSIX signature is not valid ($($signature.Status))"
+}
+
+Add-Type -AssemblyName System.IO.Compression.FileSystem
+$archive = [System.IO.Compression.ZipFile]::OpenRead($packagePath)
+try {
+  $manifestEntry = $archive.GetEntry('AppxManifest.xml')
+  if ($null -eq $manifestEntry) { throw 'Claude MSIX has no AppxManifest.xml' }
+  $reader = [System.IO.StreamReader]::new($manifestEntry.Open())
+  try { [xml]$manifest = $reader.ReadToEnd() } finally { $reader.Dispose() }
+  $identity = $manifest.Package.Identity
+  if ([string]$identity.Name -cne $env:IMPEL_CLAUDE_PACKAGE_NAME) {
+    throw "unexpected Claude MSIX package name: $($identity.Name)"
+  }
+  if ([string]$identity.Version -cne $env:IMPEL_CLAUDE_PACKAGE_VERSION) {
+    throw "unexpected Claude MSIX version: $($identity.Version)"
+  }
+  if ([string]$identity.Publisher -cne $env:IMPEL_CLAUDE_PACKAGE_PUBLISHER) {
+    throw 'unexpected Claude MSIX publisher'
+  }
+  if ([string]$identity.ProcessorArchitecture -cne $env:IMPEL_CLAUDE_MANIFEST_ARCHITECTURE) {
+    throw "unexpected Claude MSIX architecture: $($identity.ProcessorArchitecture)"
+  }
+  $application = $manifest.Package.Applications.Application | Where-Object Id -ceq 'Claude' | Select-Object -First 1
+  if ($null -eq $application -or [string]$application.Executable -cne $env:IMPEL_CLAUDE_PACKAGE_EXECUTABLE) {
+    throw 'Claude MSIX has an unexpected application entry point'
+  }
+  foreach ($entryName in @('app/claude.exe', 'app/resources/app.asar', 'AppxSignature.p7x')) {
+    if ($null -eq $archive.GetEntry($entryName)) {
+      throw "Claude MSIX is missing required entry $entryName"
+    }
+  }
+} finally {
+  $archive.Dispose()
+}
+
+Add-AppxPackage -Path $packagePath -ForceApplicationShutdown -ForceUpdateFromAnyVersion
+`;
+
+function installPinnedWindowsClaudeMsix(packagePath, environment, pin, architecture, run = spawnSync) {
+  const result = run(
+    "powershell.exe",
+    ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", INSTALL_PINNED_CLAUDE_MSIX],
+    {
+      encoding: "utf8",
+      env: {
+        ...environment,
+        IMPEL_CLAUDE_MSIX_PATH: packagePath,
+        IMPEL_CLAUDE_PACKAGE_NAME: pin.packageName,
+        IMPEL_CLAUDE_PACKAGE_VERSION: pin.packageVersion,
+        IMPEL_CLAUDE_PACKAGE_PUBLISHER: pin.publisher,
+        IMPEL_CLAUDE_PACKAGE_EXECUTABLE: pin.executable,
+        IMPEL_CLAUDE_MANIFEST_ARCHITECTURE: architecture,
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    },
+  );
+  if (result?.status !== 0 && !result?.error) {
+    const detail = String(result?.stderr || "").trim().split(/\r?\n/u).find(Boolean);
+    if (detail) return { ...result, error: new Error(`Claude MSIX installation failed: ${detail}`) };
+  }
+  return result;
+}
+
+function windowsClaudeCacheRoot(homeDir, environment, version, architecture) {
+  const appsRoot = environmentValue(environment, "IMPEL_APP_HOME")
+    || path.join(homeDir, ".config", "impel", "apps");
+  return path.join(appsRoot, "vendor-cache", "claude", version, architecture);
+}
+
+/** Download, verify, and install Anthropic's exact signed per-user MSIX. */
+export async function ensureWindowsClaudeApp(_options = {}, dependencies = {}) {
+  const io = {
+    environment: process.env,
+    architecture: null,
+    downloadTimeoutMs: WINDOWS_CLAUDE_DOWNLOAD_TIMEOUT_MS,
+    fetchImpl: fetch,
+    findPinned: pinnedWindowsClaudeApp,
+    homeDir: os.homedir(),
+    install: installPinnedWindowsClaudeMsix,
+    logger: console,
+    pin: PINNED_VENDOR_APPS.claude,
+    run: spawnSync,
+    ...dependencies,
   };
+  const architecture = io.architecture || windowsClaudeArchitecture(io.environment);
+  const windowsPin = io.pin?.windows;
+  const release = windowsPin?.downloads?.[architecture];
+  if (!windowsPin || !release) {
+    const error = new Error(`Claude: no verified Windows MSIX is available for ${architecture}`);
+    return { binary: null, action: "install-failed", result: { status: null, error } };
+  }
+  const findPinned = () => io.findPinned(io.environment, {
+    architecture,
+    pin: windowsPin,
+    run: io.run,
+  });
+  const existing = findPinned();
+  if (existing) return { binary: existing, action: "existing", result: null };
+
+  const cacheRoot = windowsClaudeCacheRoot(io.homeDir, io.environment, io.pin.version, architecture);
+  const archive = path.join(cacheRoot, `Claude-${io.pin.version}-${architecture}.msix`);
+  const temporary = `${archive}.download-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+  try {
+    fs.mkdirSync(cacheRoot, { recursive: true, mode: 0o700 });
+    if (fs.existsSync(archive) && sha256File(archive) !== release.sha256) fs.rmSync(archive, { force: true });
+    if (!fs.existsSync(archive)) {
+      io.logger.log(`Claude: downloading verified vendor app ${io.pin.version} for Windows ${architecture}…`);
+      await downloadWindowsClaudeMsix(release.url, temporary, io.fetchImpl, io.downloadTimeoutMs);
+      if (sha256File(temporary) !== release.sha256) {
+        throw new Error(`Claude MSIX integrity check failed for ${io.pin.version} (${architecture})`);
+      }
+      fs.renameSync(temporary, archive);
+    }
+    let result = io.install(archive, io.environment, windowsPin, architecture, io.run);
+    const binary = result?.status === 0 && !result?.error ? findPinned() : null;
+    if (result?.status === 0 && !result?.error && !binary) {
+      result = {
+        ...result,
+        error: new Error(`Claude ${io.pin.version} did not appear after its verified MSIX was installed`),
+      };
+    }
+    return {
+      binary,
+      action: binary ? "installed" : "install-failed",
+      result,
+    };
+  } catch (error) {
+    return { binary: null, action: "install-failed", result: { status: null, error } };
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
 }
 
 /** Install/update OpenAI's official ChatGPT/Codex Store package. */
@@ -210,7 +369,10 @@ export function ensureWindowsChatGPTApp({ update = false } = {}, dependencies =
   const before = io.find(io.environment);
   if (before && !update) return { binary: before, action: "existing", result: null };
 
-  const invocation = wingetInvocation(update ? "update" : "install", io.environment, {
+  // `impel update` also repairs missing surfaces. A missing Store package must
+  // be installed, not sent to `winget upgrade` (which returns 0x8A150014).
+  const shouldUpdate = Boolean(update && before);
+  const invocation = wingetInvocation(shouldUpdate ? "update" : "install", io.environment, {
     packageId: WINDOWS_CHATGPT_PACKAGE,
     source: "msstore",
     scope: null,
@@ -229,7 +391,7 @@ export function ensureWindowsChatGPTApp({ update = false } = {}, dependencies =
   const succeeded = result?.status === 0 && !result?.error;
   return {
     binary,
-    action: succeeded ? (update ? "updated" : "installed") : (before ? "existing" : "install-failed"),
+    action: succeeded ? (shouldUpdate ? "updated" : "installed") : (before ? "existing" : "install-failed"),
     result,
   };
 }