impel-cli 0.18.2 → 0.18.4

package/README.md

@@ -255,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.
@@ -324,6 +329,14 @@ run a real package manager, or modify native personal profiles.
 CI runs on Ubuntu, macOS, and Windows with supported Node versions. See
 [RELEASING.md](RELEASING.md) for the npm release process.
 
+The separate Windows vendor contract runs only on a disposable GitHub-hosted
+Windows VM. It installs the exact newer Claude fixture that preceded the
+current compatibility pin, invokes the production downloader and installer to
+downgrade to the exact pinned MSIX, verifies the registered AppX identity,
+version, architecture, executable, and idempotent second run, then removes the
+package. Docker/Wine remains useful for Windows path and process semantics, but
+cannot validate AppX deployment, packaged services, trust, or Store behavior.
+
 The macOS config-contract job downloads the exact ChatGPT archive declared in
 `PINNED_VENDOR_APPS`, verifies its checksum, signature, app version, and
 embedded Codex version, then validates a deterministic generated profile with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.18.2",
+  "version": "0.18.4",
   "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",

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/commands/converge.js

@@ -91,13 +91,18 @@ export async function cmdConverge(argv = [], overrides = {}) {
     // answer (not unref'd) so the auto-decline reliably fires even when the
     // prompt is the only thing keeping the event loop alive.
     const allowed = confirmed(await new Promise((resolve) => {
-      const timer = setTimeout(() => resolve(""), io.vendorPromptTimeoutMs ?? 60_000);
+      const controller = new AbortController();
+      const timer = setTimeout(() => {
+        controller.abort();
+        resolve("");
+      }, io.vendorPromptTimeoutMs ?? 60_000);
       const settle = (answer) => {
         clearTimeout(timer);
         resolve(answer);
       };
       Promise.resolve(io.promptText(
         `Allow the verified ${label} vendor ${context.mode === "update" ? "update" : "installation"}? [y/N] (auto-N in 60s) `,
+        { signal: controller.signal },
       )).then(settle, () => settle(""));
     }));
     vendorAppDecisions.set(target, allowed);
@@ -272,7 +277,14 @@ export async function cmdConverge(argv = [], overrides = {}) {
               || product === target
               || (target === "codex" && product === "chatgpt")
             ));
-            return vendorAppTargetReady(retryReport, target);
+            const installed = vendorAppTargetReady(retryReport, target);
+            return {
+              installed,
+              error: installed
+                ? null
+                : retryReport?.tenants?.[0]?.errors?.join("; ")
+                  || `The ${target} vendor app did not reach a verified state.`,
+            };
           },
         },
       }, overrides.recoveryOverrides || {});

package/src/commands/setup.js

@@ -453,7 +453,14 @@ export async function cmdSetup(argv, overrides = {}) {
               || product === target
               || (target === "codex" && product === "chatgpt")
             ));
-            return vendorAppTargetReady(retryReport, target);
+            const installed = vendorAppTargetReady(retryReport, target);
+            return {
+              installed,
+              error: installed
+                ? null
+                : retryReport?.tenants?.[0]?.errors?.join("; ")
+                  || `The ${target} vendor app did not reach a verified state.`,
+            };
           },
         },
       }, overrides.recoveryOverrides || {});

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/windowsApps.js

@@ -3,14 +3,18 @@ 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;
+const WINDOWS_WINGET_UPDATE_NOT_APPLICABLE = 0x8A15002B;
 
 export function windowsClaudeUserData(environment = process.env, tenantId = null) {
   const localAppData = environmentValue(environment, "LOCALAPPDATA")
@@ -31,6 +35,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 })
@@ -45,24 +59,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`,
@@ -76,7 +72,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,
     });
@@ -108,11 +104,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 +163,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: {
+        ...windowsPowerShellEnvironment(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: {
+        ...windowsPowerShellEnvironment(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. */
@@ -204,13 +374,17 @@ export function ensureWindowsChatGPTApp({ update = false } = {}, dependencies =
   const io = {
     environment: process.env,
     find: findWindowsChatGPTApp,
+    logger: console,
     run: spawnSync,
     ...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,
@@ -226,10 +400,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 ? (update ? "updated" : "installed") : (before ? "existing" : "install-failed"),
+    action: alreadyUpToDate
+      ? "existing"
+      : succeeded ? (shouldUpdate ? "updated" : "installed") : (before ? "existing" : "install-failed"),
     result,
   };
 }