impel-cli 0.20.54 → 0.20.56

package/RELEASE_NOTES.md

@@ -1,5 +1,52 @@
 # Release notes
 
+## 0.20.56 — Enforce reviewed Windows vendor CLIs, follow the Store pin, harden convergence
+
+- Bumps the Windows ChatGPT Store pin to `26.818.2441.0` (embedded Codex
+  `0.148.0-alpha.21`, verified from the registered package on the disposable
+  Windows runner): the Store stopped fulfilling `26.814.5167.0`, so fresh
+  Windows installs failed the exact registered-package check (IMP-590). The
+  macOS pin stays held at `26.810.41047` pending a build that passes the
+  managed Tasks board launch smoke. Exact package, publisher, executable, and
+  embedded-runtime verification is unchanged.
+
+- Enforces the exact reviewed Claude Code and Codex CLI releases on Windows,
+  matching the macOS contract: a vendor auto-update past the pin no longer
+  launches an unreviewed build against the gateway (the drift behind the
+  Windows `403 Forbidden` lockouts), and the launcher resolves the pinned
+  side-by-side release under `.local/share/claude/versions/` when the shared
+  launcher has drifted — including installs whose `HOME` diverges from
+  `USERPROFILE`.
+- Disables the vendor background auto-updater in managed Claude CLI profiles
+  (`DISABLE_AUTOUPDATER=1`) so a session on the reviewed release cannot move
+  the shared launcher past the pin; manual `claude update` still works.
+- Names vendor version drift in setup/update diagnostics ("installed v2.1.237
+  does not match the reviewed v2.1.220") instead of the misleading
+  "not installed or discoverable".
+- Stops `chmod` failures from aborting Windows tenant convergence: managed
+  profile writers treat the FAT-era mode bits as best-effort on Windows, and
+  the all-tenant security sweep no longer fails every tenant over one
+  tenant's locked file. POSIX keeps failing loudly.
+- Retries the Windows stable-entrypoint and managed-artifact renames through
+  the shared antivirus-tolerant retry helper.
+- Carries which tenants failed and why in the auto-filed
+  "Tenant convergence failed during `impel update`" report, via a redacted
+  on-disk summary the cascaded child leaves for the parent's single report.
+- Sends `X-Impel-Cli-Version` on gateway requests from `impel claude` so a
+  production 403 can be correlated to a CLI release.
+
+## 0.20.55 — Route managed CLIs through the signed runner
+
+- Launches `impel codex` and `impel claude` through the tenant-agnostic macOS
+  managed runner when the corresponding signed descriptor is installed.
+- Binds each launch to the exact logical application ID and leaves descriptor
+  signature, trust-anchor, runtime-lock, and payload verification with the
+  signed runner before any vendor CLI starts.
+- Prefers the standalone Codex MSI on Windows while retaining the legacy
+  ChatGPT-embedded Codex package only as a compatibility fallback.
+- Stops newly managed Codex sessions from reaching retired macOS wrappers that
+  injected an invalid `--console` argument into no-argument launches.
+
 ## 0.20.54 — Restore ChatGPT Store compatibility and scope skills per tenant
 
 - Restores managed ChatGPT/Codex installation on Windows by pinning Store

package/package.json

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

package/src/apps.js

@@ -20,6 +20,7 @@ import {
   isImpelTasksMcpInvocation,
 } from "./selfInvocation.js";
 import { crossAppModelsEnabled, redactSecretText } from "./config.js";
+import { chmodWithPlatformPolicy, renameWithWindowsRetry } from "./windowsFs.js";
 import { ensureClaudeSessionHooks, ensureCodexSessionHooks } from "./sessionHooks.js";
 import { ADHOC_IDENTITY, codesignIdentityArgs, desiredSigningMode, resolveSigningIdentity } from "./codesign.js";
 import { applyImpelClaudeSandbox } from "./claudeSandbox.js";
@@ -131,12 +132,15 @@ export const PINNED_VENDOR_APPS = Object.freeze({
       // against this value. updateManifestUrl below is advertisement, read by
       // the contract test alone and never by the install path.
       //
-      // Those two disagree as of 2026-08-18: the manifest advertises
-      // 26.814.5517.0 while the Store installs 26.814.5167.0. Pin what actually
-      // installs — a pin matching only the advertisement would fail closed on
-      // every real machine.
-      packageVersion: "26.814.5167.0",
-      codexVersion: "0.148.0-alpha.15",
+      // Those two disagree again as of 2026-08-20: the manifest advertises
+      // 26.818.2872.0 while the disposable-runner Store install registered
+      // 26.818.2441.0 (the Store stopped fulfilling 26.814.5167.0 entirely —
+      // IMP-590). Pin what actually installs — a pin matching only the
+      // advertisement would fail closed on every real machine.
+      packageVersion: "26.818.2441.0",
+      // Verified on the disposable Windows runner: the registered package's
+      // embedded codex.exe --version reports exactly this release.
+      codexVersion: "0.148.0-alpha.21",
       publisherId: "2p2nqsd0c76g0",
       executable: "app\\ChatGPT.exe",
       updateManifestUrl: "https://persistent.oaistatic.com/codex-app-prod/windows-store-update.json",
@@ -820,14 +824,14 @@ export function migrateLegacyClaudeAppSessions(userData, homeDir = os.homedir())
       const sourceStat = fs.statSync(source);
       if (fs.existsSync(destination) && fs.statSync(destination).mtimeMs >= sourceStat.mtimeMs) continue;
       fs.mkdirSync(destinationDirectory, { recursive: true, mode: 0o700 });
-      fs.chmodSync(destinationDirectory, 0o700);
+      chmodWithPlatformPolicy(destinationDirectory, 0o700);
       const temporary = `${destination}.tmp-${process.pid}`;
       try {
         fs.copyFileSync(source, temporary);
-        fs.chmodSync(temporary, 0o600);
-        fs.renameSync(temporary, destination);
+        chmodWithPlatformPolicy(temporary, 0o600);
+        renameWithWindowsRetry(temporary, destination);
         fs.utimesSync(destination, sourceStat.atime, sourceStat.mtime);
-        fs.chmodSync(destination, 0o600);
+        chmodWithPlatformPolicy(destination, 0o600);
         copied += 1;
       } finally {
         fs.rmSync(temporary, { force: true });
@@ -3368,13 +3372,13 @@ function isExplicitNoSeatCatalog(payload) {
 function writeAtomic(target, contents, mode) {
   fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
   if (fs.existsSync(target) && fs.readFileSync(target, "utf8") === contents) {
-    fs.chmodSync(target, mode);
+    chmodWithPlatformPolicy(target, mode);
     return;
   }
   const tmp = `${target}.tmp-${process.pid}`;
   fs.writeFileSync(tmp, contents, { mode });
-  fs.renameSync(tmp, target);
-  fs.chmodSync(target, mode);
+  renameWithWindowsRetry(tmp, target);
+  chmodWithPlatformPolicy(target, mode);
 }
 
 function bundleVersion(bundle) {

package/src/cliProfiles.js

@@ -120,6 +120,11 @@ export function ensureImpelClaudeProfile(gatewayUrl, tenantId, { crossAppModels
     ...(settings.env && typeof settings.env === "object" && !Array.isArray(settings.env)
       ? settings.env
       : {}),
+    // The launcher is shared machine-wide and this session runs the exact
+    // reviewed release; a background self-update from inside it would move
+    // that shared launcher past the reviewed pin for every later launch.
+    // Manual `claude update` keeps working.
+    DISABLE_AUTOUPDATER: "1",
     ANTHROPIC_BASE_URL: crossAppModels
       ? impelCrossAppClaudeBaseUrl(gatewayUrl)
       : impelClaudeBaseUrl(gatewayUrl),

package/src/codexSecurity.js

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import { chmodWithPlatformPolicy } from "./windowsFs.js";
+
 const PRIVATE_ROOT_FILES = ["auth.json", "config.toml", "models.json"];
 const MANAGED_COMMENT = "# Impel security policy: keep gateway credentials out of shell state.";
 
@@ -189,10 +191,10 @@ function assertSafeManagedPath(target, expectedType) {
  * to decide whether the file contains one. Known credential/config files are
  * owner-only. This function must never be called for the native ~/.codex home.
  */
-export function secureManagedCodexHome(codexHome) {
+export function secureManagedCodexHome(codexHome, { bestEffortChmod = false } = {}) {
   const existing = assertSafeManagedPath(codexHome, "directory");
   if (!existing) fs.mkdirSync(codexHome, { recursive: true, mode: 0o700 });
-  fs.chmodSync(codexHome, 0o700);
+  chmodWithPlatformPolicy(codexHome, 0o700, { bestEffort: bestEffortChmod });
 
   const snapshots = path.join(codexHome, "shell_snapshots");
   const snapshotStat = assertSafeManagedPath(snapshots, "directory");
@@ -201,7 +203,7 @@ export function secureManagedCodexHome(codexHome) {
     const filePath = path.join(codexHome, fileName);
     const stat = assertSafeManagedPath(filePath, "file");
     if (!stat) continue;
-    fs.chmodSync(filePath, 0o600);
+    chmodWithPlatformPolicy(filePath, 0o600, { bestEffort: bestEffortChmod });
   }
 }
 
@@ -214,7 +216,12 @@ function secureExistingManagedHome(root, relativeParts, secured) {
     if (stat.isSymbolicLink()) throw new Error(`${current} must not be a symbolic link.`);
     if (!stat.isDirectory()) throw new Error(`${current} must be a directory.`);
   }
-  secureManagedCodexHome(current);
+  // The sweep opportunistically tightens every managed home, including other
+  // tenants'. A chmod refusal on a sibling tenant's file must not abort the
+  // active tenant's convergence (observed in the field as an all-tenant
+  // failure over one tenant's models.json); symlink/type violations above
+  // still fail closed because they indicate tampering, not permissions.
+  secureManagedCodexHome(current, { bestEffortChmod: true });
   secured.push(current);
 }
 

package/src/commands/converge.js

@@ -1,6 +1,7 @@
 // Hidden fresh-build continuation used by `impel update`.
 
 import { loadConfig, saveConfig, redactSecretText } from "../config.js";
+import { writeConvergenceSummary } from "../convergenceSummary.js";
 import { runInstallRecovery } from "../installRecovery/engine.js";
 import {
   printReconciliationSummary,
@@ -10,6 +11,7 @@ import {
 import { applyCliUser, fetchTenants } from "../tenants.js";
 import { promptText } from "../prompt.js";
 import { describeCliFailure, preparePlatformClis } from "../platformSetup.js";
+import { brandedEnvironmentName } from "../runtimeBrand.js";
 import { restoreNativeProfiles } from "./use.js";
 import { createTenantRecoveryReportTracker } from "./tenantRecoveryReport.js";
 import { resolveSkillCredential } from "../skillBundle.js";
@@ -58,9 +60,22 @@ export async function cmdConverge(argv = [], overrides = {}) {
   if (overrides.prepareWindowsClis && !overrides.preparePlatformClis) {
     io.preparePlatformClis = overrides.prepareWindowsClis;
   }
+  // The summary exists solely for the `impel update` parent's failure report;
+  // a directly invoked `_converge` (tests, manual runs) writes nothing.
+  const cascade = io.environment?.[brandedEnvironmentName("UPDATE_CASCADE")] === "1";
+  const leaveSummary = (outcome) => {
+    if (!cascade) return;
+    (io.writeConvergenceSummary || writeConvergenceSummary)(outcome);
+  };
+  const summarize = (sharedFailure) => leaveSummary({
+    passed: false,
+    sharedFailure,
+    failedTenants: [],
+  });
   const config = io.loadConfig();
   if (!config?.pat) {
     console.error("impel update: not authenticated; run `impel setup` first.");
+    summarize("not authenticated");
     process.exitCode = 1;
     return false;
   }
@@ -72,6 +87,7 @@ export async function cmdConverge(argv = [], overrides = {}) {
   } catch (error) {
     if (!RETRYABLE_TENANT_DISCOVERY_ERROR.test(String(error?.message || error))) {
       console.error(`impel update: tenant discovery failed (${redactSecretText(error?.message || error)})`);
+      summarize(`tenant discovery failed: ${error?.message || error}`);
       process.exitCode = 1;
       return false;
     }
@@ -81,6 +97,7 @@ export async function cmdConverge(argv = [], overrides = {}) {
       listing = await io.fetchTenants(config);
     } catch (retryError) {
       console.error(`impel update: tenant discovery failed (${redactSecretText(retryError?.message || retryError)})`);
+      summarize(`tenant discovery failed after retry: ${retryError?.message || retryError}`);
       process.exitCode = 1;
       return false;
     }
@@ -346,7 +363,17 @@ export async function cmdConverge(argv = [], overrides = {}) {
   }
   printReconciliationSummary(report);
   console.log(`CLI tenant: ${selected.id} (change with \`impel tenant use <tenant>\`)`);
-  if (!report.passed || sharedFailure) {
+  const passed = report.passed && !sharedFailure;
+  // Leave the machine-readable outcome for the `impel update` parent, whose
+  // auto-filed report otherwise knows nothing beyond this child's exit status.
+  leaveSummary({
+    passed,
+    sharedFailure,
+    failedTenants: report.tenants
+      .filter((tenant) => tenant.status === "failed")
+      .map((tenant) => ({ tenantId: tenant.tenantId, errors: tenant.errors })),
+  });
+  if (!passed) {
     if (sharedFailure) console.error(`Shared update failure: ${sharedFailure}`);
     console.error("impel update: one or more tenant surfaces remain incomplete.");
     process.exitCode = 1;

package/src/commands/launch.js

@@ -23,7 +23,7 @@ import { impelClaudeBaseUrl, impelCrossAppClaudeBaseUrl } from "../claudeSetup.j
 import { parentVerbatimRelayAppendix } from "../verbatimRelay.js";
 import { withGitEnvironment } from "../skills.js";
 import { assertProviderScopes, ensureTenantSelection, tenantCredential } from "../tenants.js";
-import { maybePrintUpdateNotice } from "../updates.js";
+import { installedVersion, maybePrintUpdateNotice } from "../updates.js";
 import { nativeSpawnInvocation } from "../nativeProcess.js";
 import { IMPEL_NATIVE_BENCHMARK_ENV } from "../selfInvocation.js";
 import { resolveReviewedVendorCliBinary } from "../vendorCliBinaries.js";
@@ -392,7 +392,13 @@ async function assertLiveProviderReadiness({ config, gatewayUrl, credential, ten
   if (!readiness.reachable) {
     throw new Error(`could not verify live ${label} availability for tenant "${tenantId}" (${readiness.error || "gateway unreachable"})`);
   }
-  if (readiness.rejected) throw new Error(`gateway credential was rejected (HTTP ${readiness.status})`);
+  if (readiness.rejected) {
+    throw new Error(
+      `gateway credential was rejected (HTTP ${readiness.status}). `
+      + `Your access to tenant "${tenantId}" may have changed; rerun \`${RUNTIME_BRAND.cli.command} setup\` `
+      + "to refresh it, or ask a workspace administrator to confirm your gateway seat.",
+    );
+  }
   if (!readiness.healthy) {
     throw new Error(`could not verify live ${label} availability for tenant "${tenantId}" (${readiness.error || `HTTP ${readiness.status}`})`);
   }
@@ -408,9 +414,13 @@ function runNativeCli(tool, argv, environment) {
   const binary = resolveReviewedVendorCliBinary(tool, environment);
   if (!binary) {
     const version = PINNED_VENDOR_CLI_VERSIONS[tool];
+    const repair = process.platform === "win32"
+      ? `${RUNTIME_BRAND.cli.command}.cmd update`
+      : `${RUNTIME_BRAND.cli.command} update`;
     console.error(
       `impel ${tool}: reviewed ${tool === "claude" ? "Claude Code" : "Codex"} CLI `
-      + `v${version} is not installed. Run \`impel update\` to repair it.`,
+      + `v${version} is not installed (an unreviewed or auto-updated build is not launched `
+      + `against the gateway). Run \`${repair}\` to repair it.`,
     );
     return Promise.resolve(127);
   }
@@ -547,6 +557,13 @@ export async function cmdLaunch(tool, argv) {
     // Impel PATs are bearer tokens, so keep the token process-scoped instead of
     // writing it into Claude's isolated profile.
     environment.ANTHROPIC_AUTH_TOKEN = gatewayCredential;
+    // Version attribution for gateway logs: a 403 in production is currently
+    // impossible to correlate to a CLI/vendor build. Appended so a user's own
+    // custom headers survive.
+    const versionHeader = `X-Impel-Cli-Version: ${RUNTIME_BRAND.cli.packageName}/${installedVersion() || "unknown"}`;
+    environment.ANTHROPIC_CUSTOM_HEADERS = environment.ANTHROPIC_CUSTOM_HEADERS
+      ? `${environment.ANTHROPIC_CUSTOM_HEADERS}\n${versionHeader}`
+      : versionHeader;
   } else if (tool === "codex") {
     const profile = ensureImpelCodexProfile(gatewayUrl, tenantId);
     agentProfile = {

package/src/commands/update.js

@@ -11,6 +11,10 @@ import { nativeCommandInvocation } from "../nativeProcess.js";
 import { withProgress } from "../progress.js";
 import { runInstallRecovery } from "../installRecovery/engine.js";
 import { reportInstallFailure } from "../autoReport.js";
+import {
+  convergenceSummaryDiagnostics,
+  readRecentConvergenceSummary,
+} from "../convergenceSummary.js";
 import { brandedEnvironmentName, brandedText, RUNTIME_BRAND } from "../runtimeBrand.js";
 import { IMPEL_CLI_ENTRYPOINT } from "../selfInvocation.js";
 import {
@@ -512,12 +516,11 @@ export async function cmdUpdate(argv, overrides = {}) {
     console.error("impel update: tenant convergence failed; rerun `impel update` after addressing the reported issue.");
     // The child is `impel _converge`, which files no report of its own — and
     // this parent only sees its exit status, because the child inherits stdio
-    // so its progress reaches the terminal live. So this report carries what
-    // the parent does know: that it was an update cascade, and which flags
-    // shaped the run it failed under. Which tenants failed is visible on the
-    // user's screen but not in the report; closing that gap needs a channel
-    // between the two processes, which R2 (one report per invocation) says must
-    // not simply be a second report from the child.
+    // so its progress reaches the terminal live. The child does leave a
+    // machine-readable summary on disk, though, so the single report R2
+    // allows can carry which tenants failed and why instead of only the
+    // flags that shaped the run.
+    const summary = (io.readConvergenceSummary || readRecentConvergenceSummary)();
     await reportUpdateFailure({
       scope: "shared",
       platform: io.platform,
@@ -528,6 +531,7 @@ export async function cmdUpdate(argv, overrides = {}) {
         skipApps: String(Boolean(flags["skip-apps"])),
         skipClis: String(Boolean(flags["skip-clis"])),
         cascadedEntrypoint: String(Boolean(cascadeEntrypoint)),
+        ...convergenceSummaryDiagnostics(summary),
       },
     });
     process.exitCode = 1;

package/src/convergenceSummary.js

@@ -0,0 +1,84 @@
+// The `impel update` parent spawns `impel _converge` with inherited stdio and
+// only sees its exit status, and R2 allows one report per invocation — so the
+// auto-filed "Tenant convergence failed" report has carried no tenant detail
+// at all. The child instead leaves a machine-readable summary on disk that the
+// parent folds into the diagnostics of the report it was already filing.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { CONFIG_DIR, redactSecretText } from "./config.js";
+import { renameWithWindowsRetry } from "./windowsFs.js";
+
+export const CONVERGENCE_SUMMARY_PATH = path.join(CONFIG_DIR, "reports", ".last-convergence.json");
+
+// Wide enough to survive install-recovery sessions between the child's write
+// and the parent's read; narrow enough that yesterday's failure never
+// masquerades as today's.
+export const CONVERGENCE_SUMMARY_FRESHNESS_MS = 15 * 60 * 1_000;
+
+const MAX_FAILED_TENANTS = 12;
+const MAX_ERRORS_PER_TENANT = 4;
+const MAX_ERROR_LENGTH = 300;
+
+/** Best-effort: losing the summary only costs report detail, never the run. */
+export function writeConvergenceSummary({ passed, sharedFailure = null, failedTenants = [] }, {
+  summaryPath = CONVERGENCE_SUMMARY_PATH,
+  now = Date.now(),
+} = {}) {
+  try {
+    const summary = {
+      writtenAt: new Date(now).toISOString(),
+      passed: Boolean(passed),
+      sharedFailure: sharedFailure ? redactSecretText(String(sharedFailure)).slice(0, 2_000) : null,
+      failedTenants: failedTenants.slice(0, MAX_FAILED_TENANTS).map((tenant) => ({
+        tenantId: String(tenant.tenantId || "").slice(0, 128),
+        errors: (tenant.errors || [])
+          .slice(0, MAX_ERRORS_PER_TENANT)
+          .map((error) => redactSecretText(String(error)).slice(0, MAX_ERROR_LENGTH)),
+      })),
+    };
+    fs.mkdirSync(path.dirname(summaryPath), { recursive: true, mode: 0o700 });
+    const temporaryPath = `${summaryPath}.tmp-${process.pid}`;
+    fs.writeFileSync(temporaryPath, `${JSON.stringify(summary)}\n`, { mode: 0o600 });
+    renameWithWindowsRetry(temporaryPath, summaryPath);
+  } catch {
+    // Deliberately silent: the summary is diagnostics for a report about a
+    // failure that has already been announced on the user's terminal.
+  }
+}
+
+/** Returns the parsed summary only while it is plausibly from this cascade. */
+export function readRecentConvergenceSummary({
+  summaryPath = CONVERGENCE_SUMMARY_PATH,
+  now = Date.now(),
+} = {}) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(summaryPath, "utf8"));
+    const writtenAt = Date.parse(parsed?.writtenAt || "");
+    if (!Number.isFinite(writtenAt)) return null;
+    if (writtenAt > now + 60_000 || now - writtenAt > CONVERGENCE_SUMMARY_FRESHNESS_MS) return null;
+    if (typeof parsed.passed !== "boolean" || !Array.isArray(parsed.failedTenants)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Flatten a summary into the bounded string map the report envelope accepts. */
+export function convergenceSummaryDiagnostics(summary) {
+  if (!summary || summary.passed) return {};
+  const failed = summary.failedTenants.filter((tenant) => tenant?.tenantId);
+  return {
+    ...(summary.sharedFailure ? { sharedFailure: summary.sharedFailure } : {}),
+    ...(failed.length
+      ? {
+        failedTenantIds: failed.map((tenant) => tenant.tenantId).join(","),
+        failedTenantErrors: failed
+          .map((tenant) => `${tenant.tenantId}: ${(tenant.errors || []).join("; ")}`)
+          .join(" | ")
+          .slice(0, 1_800),
+      }
+      : {}),
+  };
+}

package/src/managedApps.js

@@ -4,7 +4,12 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 
 const TENANT = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/u;
-const APPLICATION_BY_TOOL = Object.freeze({ claude: "claude", codex: "chatgpt" });
+const APPLICATIONS_BY_TOOL = Object.freeze({
+  claude: ["claude"],
+  codex: ["codex", "chatgpt"],
+});
+const MAC_RUNNER = "/Applications/Impel Managed App Runner.app/Contents/Library/LaunchServices/impel-managed-runner";
+const MAC_DESCRIPTOR_ROOT = "/Library/Application Support/Impel/Managed App Runner/descriptors";
 
 function regularFile(file) {
   try {
@@ -15,7 +20,7 @@ function regularFile(file) {
   }
 }
 
-function parseCandidate(manifestPath, launcher, tool, platform, home) {
+function parseCandidate(manifestPath, launcher, applicationId, platform, home) {
   if (!regularFile(manifestPath) || !regularFile(launcher)) return null;
   let manifest;
   try {
@@ -25,7 +30,6 @@ function parseCandidate(manifestPath, launcher, tool, platform, home) {
   } catch {
     return null;
   }
-  const applicationId = APPLICATION_BY_TOOL[tool];
   const tenantId = manifest?.tenant?.id;
   const expectedPlatform = platform === "win32" ? "windows" : "macos";
   if (
@@ -46,11 +50,12 @@ function parseCandidate(manifestPath, launcher, tool, platform, home) {
     tenantId,
     tenantDisplayName: typeof manifest.tenant.displayName === "string" ? manifest.tenant.displayName : tenantId,
     launcher,
+    logicalApplicationId: manifest.logicalApplicationId,
     manifestPath,
   };
 }
 
-function macCandidates(tool, home, applicationsRoot) {
+function legacyMacCandidates(tool, home, applicationsRoot) {
   let entries;
   try {
     entries = fs.readdirSync(applicationsRoot, { withFileTypes: true });
@@ -58,13 +63,14 @@ function macCandidates(tool, home, applicationsRoot) {
     return [];
   }
   const candidates = [];
+  const applicationId = tool === "codex" ? "chatgpt" : tool;
   for (const entry of entries) {
     if (!entry.isDirectory() || !entry.name.endsWith(".app")) continue;
     const root = path.join(applicationsRoot, entry.name, "Contents");
     const candidate = parseCandidate(
       path.join(root, "Resources", "app-manifest.json"),
       path.join(root, "MacOS", "impel-apps-launcher"),
-      tool,
+      applicationId,
       "darwin",
       home,
     );
@@ -73,6 +79,78 @@ function macCandidates(tool, home, applicationsRoot) {
   return candidates;
 }
 
+function runnerEnvelopeCandidate(envelopePath, launcher, tool, home) {
+  if (!regularFile(envelopePath) || !regularFile(launcher)) return null;
+  let envelope;
+  try {
+    const raw = fs.readFileSync(envelopePath, "utf8");
+    if (Buffer.byteLength(raw, "utf8") > 512 * 1024) return null;
+    envelope = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const payload = envelope?.payload;
+  const tenantId = payload?.tenant?.id;
+  if (
+    envelope?.schemaVersion !== 1
+    || payload?.kind !== "com.useimpel.managed-application-descriptor"
+    || payload?.runtimeContract?.entrypoint !== "engine/main.mjs"
+    || payload?.application?.id !== tool
+    || payload?.application?.adapter !== tool
+    || !TENANT.test(tenantId || "")
+    || String(tenantId).includes("..")
+    || payload?.logicalApplicationId !== `${tenantId}.${tool}`
+  ) return null;
+  const credential = path.join(home, ".config", "impel", "apps", "credentials", `${tenantId}.json`);
+  if (!regularFile(credential)) return null;
+  return {
+    tenantId,
+    tenantDisplayName: typeof payload.tenant.displayName === "string" ? payload.tenant.displayName : tenantId,
+    launcher,
+    logicalApplicationId: payload.logicalApplicationId,
+    managedRunner: true,
+  };
+}
+
+function managedRunnerMacCandidates(tool, home, descriptorRoot, runnerLauncher) {
+  if (!regularFile(runnerLauncher)) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(descriptorRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const candidates = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (!entry.isDirectory() || !entry.name.endsWith(`.${tool}`)) continue;
+    const directory = path.join(descriptorRoot, entry.name);
+    let envelopes;
+    try {
+      envelopes = fs.readdirSync(directory, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const envelope of envelopes.sort((left, right) => left.name.localeCompare(right.name))) {
+      if (!envelope.isFile() || !envelope.name.endsWith(".json")) continue;
+      const candidate = runnerEnvelopeCandidate(path.join(directory, envelope.name), runnerLauncher, tool, home);
+      if (!candidate || candidate.logicalApplicationId !== entry.name) continue;
+      candidates.push(candidate);
+      break;
+    }
+  }
+  return candidates;
+}
+
+function macCandidates(tool, home, applicationsRoot, descriptorRoot, runnerLauncher) {
+  const preferred = managedRunnerMacCandidates(tool, home, descriptorRoot, runnerLauncher);
+  const legacy = legacyMacCandidates(tool, home, applicationsRoot);
+  const byTenant = new Map();
+  for (const candidate of [...preferred, ...legacy]) {
+    if (!byTenant.has(candidate.tenantId)) byTenant.set(candidate.tenantId, candidate);
+  }
+  return [...byTenant.values()];
+}
+
 function windowsCandidates(tool, home, applicationsRoot) {
   const candidates = [];
   let tenants;
@@ -83,15 +161,19 @@ function windowsCandidates(tool, home, applicationsRoot) {
   }
   for (const tenant of tenants) {
     if (!tenant.isDirectory() || !TENANT.test(tenant.name) || tenant.name.includes("..")) continue;
-    const root = path.join(applicationsRoot, tenant.name, APPLICATION_BY_TOOL[tool]);
-    const candidate = parseCandidate(
-      path.join(root, "resources", "app-manifest.json"),
-      path.join(root, "impel-apps-launcher.exe"),
-      tool,
-      "win32",
-      home,
-    );
-    if (candidate) candidates.push(candidate);
+    for (const applicationId of APPLICATIONS_BY_TOOL[tool]) {
+      const root = path.join(applicationsRoot, tenant.name, applicationId);
+      const candidate = parseCandidate(
+        path.join(root, "resources", "app-manifest.json"),
+        path.join(root, "impel-apps-launcher.exe"),
+        applicationId,
+        "win32",
+        home,
+      );
+      if (!candidate) continue;
+      candidates.push(candidate);
+      break;
+    }
   }
   return candidates;
 }
@@ -102,11 +184,15 @@ export function installedManagedAppCandidates(tool, {
   applicationsRoot = platform === "win32"
     ? path.join(process.env.ProgramFiles || "C:\\Program Files", "Impel", "Apps")
     : "/Applications",
+  descriptorRoot = MAC_DESCRIPTOR_ROOT,
+  runnerLauncher = MAC_RUNNER,
 } = {}) {
-  if (!APPLICATION_BY_TOOL[tool]) return [];
+  if (!APPLICATIONS_BY_TOOL[tool]) return [];
   const candidates = platform === "win32"
     ? windowsCandidates(tool, home, applicationsRoot)
-    : platform === "darwin" ? macCandidates(tool, home, applicationsRoot) : [];
+    : platform === "darwin"
+      ? macCandidates(tool, home, applicationsRoot, descriptorRoot, runnerLauncher)
+      : [];
   return candidates.sort((left, right) => left.tenantId.localeCompare(right.tenantId));
 }
 
@@ -170,8 +256,11 @@ export function runManagedAppCli(candidate, tool, argv, {
   cwd = process.cwd(),
   spawnProcess = spawn,
 } = {}) {
+  const args = candidate.managedRunner === true
+    ? ["--descriptor", candidate.logicalApplicationId, "--managed-cli", tool, "--", ...argv]
+    : ["--managed-cli", tool, "--", ...argv];
   return new Promise((resolve) => {
-    const child = spawnProcess(candidate.launcher, ["--managed-cli", tool, "--", ...argv], {
+    const child = spawnProcess(candidate.launcher, args, {
       cwd,
       env: environment,
       stdio: "inherit",
@@ -191,4 +280,3 @@ export function runManagedAppCli(candidate, tool, argv, {
     });
   });
 }
-

package/src/managedProfileVersion.js

@@ -6,4 +6,7 @@
 // managed ChatGPT profiles.
 // v43 sends tenant-checked issue handoffs from the embedded board to the main
 // Impel browser app without expanding the capability-scoped desktop session.
-export const CURRENT_CONFIG_VERSION = 43;
+// v44 disables the vendor background auto-updater in managed Claude CLI
+// profiles so a session on the reviewed release cannot move the shared
+// launcher past the pin (the Windows drift behind the gateway lockouts).
+export const CURRENT_CONFIG_VERSION = 44;

package/src/platformSetup.js

@@ -55,6 +55,7 @@ export function describeCliFailure(prepared, {
       || failure
       || installation?.succeeded === false,
     );
+    const drift = prepared.drifted?.[tool];
     const reason = failure?.message || failure?.code
       || (Number.isInteger(failure?.status)
         ? `exit ${failure.status}`
@@ -64,9 +65,11 @@ export function describeCliFailure(prepared, {
             ? "automatic installation was declined"
             : skipClis
               ? "installation was skipped by --skip-clis"
-              : !isTTY && prepared.installCommands?.[tool]
-                ? `interactive confirmation required; rerun \`${cliExecutable} ${commandName}\` interactively (or use \`--skip-clis\` to leave it uninstalled)`
-                : "not installed or discoverable");
+              : drift
+                ? `installed v${drift.version} does not match the reviewed v${drift.pinned} this release launches against the gateway`
+                : !isTTY && prepared.installCommands?.[tool]
+                  ? `interactive confirmation required; rerun \`${cliExecutable} ${commandName}\` interactively (or use \`--skip-clis\` to leave it uninstalled)`
+                  : "not installed or discoverable");
     details.push(`${labels[tool] || tool}: ${redactSecretText(reason)}`);
     const command = installation?.command || prepared.installCommands?.[tool];
     if (attempted && command) details.push(`manual ${tool} recovery command: ${redactSecretText(command)}`);

package/src/stableEntrypoint.js

@@ -8,6 +8,7 @@ import {
 } from "./selfInvocation.js";
 import { redactSecretText } from "./config.js";
 import { brandedEnvironmentName, RUNTIME_BRAND } from "./runtimeBrand.js";
+import { renameWithWindowsRetry } from "./windowsFs.js";
 
 /**
  * Render the stable Windows entry point (`%LOCALAPPDATA%\Impel\bin\impel-entry.cjs`).
@@ -172,7 +173,7 @@ export function ensureWindowsStableEntrypoint({
   const temporaryPath = `${target}.tmp-${process.pid}`;
   try {
     fs.writeFileSync(temporaryPath, content, { mode: 0o700 });
-    fs.renameSync(temporaryPath, target);
+    renameWithWindowsRetry(temporaryPath, target);
   } finally {
     try {
       fs.rmSync(temporaryPath, { force: true });

package/src/vendorCliBinaries.js

@@ -5,6 +5,7 @@ import { spawnSync } from "node:child_process";
 import {
   environmentValue,
   findNativeBinary,
+  nativeSpawnInvocation,
   resolveNativeBinary,
 } from "./nativeProcess.js";
 import { PINNED_VENDOR_CLI_VERSIONS } from "./vendorCliVersions.js";
@@ -99,9 +100,100 @@ export function verifyReviewedMacVendorCli(
   }
 }
 
+/** Run `<binary> --version` through the platform-safe spawn and parse it. */
+export function windowsVendorCliVersion(binary, environment = process.env, { run = spawnSync } = {}) {
+  try {
+    const invocation = nativeSpawnInvocation(binary, ["--version"], environment, "win32");
+    const result = run(invocation.command, invocation.args, {
+      encoding: "utf8",
+      env: environment,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 15_000,
+      windowsHide: true,
+      windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+    });
+    if (result?.status !== 0 || result?.error) return null;
+    return parseVendorCliVersion(`${result.stdout || ""}\n${result.stderr || ""}`);
+  } catch {
+    return null;
+  }
+}
+
 /**
- * Locate the reviewed macOS vendor CLI. On other platforms this intentionally
- * preserves the existing native resolution behavior.
+ * Accept only the exact reviewed release on Windows. Windows ships no
+ * in-box codesign equivalent for these unsigned-shim installs, so the gate
+ * is the exact version contract; explicit binary overrides remain
+ * authoritative for development and recovery, as on macOS.
+ */
+export function verifyReviewedWindowsVendorCli(
+  tool,
+  binary,
+  environment = process.env,
+  {
+    run = spawnSync,
+    versions = PINNED_VENDOR_CLI_VERSIONS,
+    environmentPrefix = "IMPEL",
+  } = {},
+) {
+  if (!versions[tool]) return false;
+  try {
+    const override = vendorOverrideName(tool, environmentPrefix);
+    const overriddenBinary = override ? environmentValue(environment, override) : null;
+    if (overriddenBinary && path.resolve(overriddenBinary) === path.resolve(binary)) return true;
+    return windowsVendorCliVersion(binary, environment, { run }) === versions[tool];
+  } catch {
+    return false;
+  }
+}
+
+function reviewedWindowsClaudeFallback(environment, environmentPrefix, accept, { find, realpath, stat }) {
+  // The native Windows installer keeps releases side by side under
+  // .local/share/claude/versions/<release> and its auto-updater replaces the
+  // .local/bin launcher in place. When the launcher drifts past the reviewed
+  // release, resolve the exact reviewed release directly instead of failing
+  // the launch; every candidate still passes the version verification.
+  const candidates = [];
+  const drifted = find("claude", environment, "win32", environmentPrefix);
+  if (drifted) {
+    try {
+      candidates.push(path.win32.join(
+        path.win32.dirname(realpath(drifted)),
+        "..", "share", "claude", "versions", PINNED_VENDOR_CLI_VERSIONS.claude,
+      ));
+    } catch {
+      // An unresolvable launcher only forfeits the derived candidate.
+    }
+  }
+  // USERPROFILE gates the fixed-root candidates: it is only set on real
+  // Windows sessions, so cross-platform tests injecting fake finders never
+  // fall through to a genuine macOS side-by-side install. HOME is probed too
+  // because the vendor updater follows HOME when it diverges from USERPROFILE.
+  const userProfile = environmentValue(environment, "USERPROFILE");
+  if (userProfile) {
+    const homes = [userProfile];
+    const home = environmentValue(environment, "HOME");
+    if (home && home !== userProfile) homes.push(home);
+    for (const root of homes) {
+      candidates.push(path.win32.join(root, ".local", "share", "claude", "versions", PINNED_VENDOR_CLI_VERSIONS.claude));
+    }
+  }
+  for (const base of candidates) {
+    // The release file is stored bare on every platform, but probe the .exe
+    // sibling too in case the installer ever normalizes Windows names.
+    for (const candidate of [base, `${base}.exe`]) {
+      try {
+        if (stat(candidate).isFile() && accept(candidate)) return candidate;
+      } catch {
+        // A missing side-by-side release keeps resolution fail-closed.
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Locate the reviewed vendor CLI on macOS and Windows. Other platforms
+ * intentionally preserve the existing native resolution behavior.
  */
 export function findReviewedVendorCliBinary(
   tool,
@@ -110,13 +202,17 @@ export function findReviewedVendorCliBinary(
   environmentPrefix = "IMPEL",
   {
     find = findNativeBinary,
-    verify = verifyReviewedMacVendorCli,
+    verify = null,
     realpath = fs.realpathSync,
     stat = fs.statSync,
   } = {},
 ) {
-  if (platform !== "darwin") return find(tool, environment, platform, environmentPrefix);
-  const accept = (binary) => verify(tool, binary, environment, { environmentPrefix });
+  if (platform !== "darwin" && platform !== "win32") {
+    return find(tool, environment, platform, environmentPrefix);
+  }
+  const verifier = verify
+    || (platform === "win32" ? verifyReviewedWindowsVendorCli : verifyReviewedMacVendorCli);
+  const accept = (binary) => verifier(tool, binary, environment, { environmentPrefix });
   const reviewed = find(tool, environment, platform, environmentPrefix, accept);
   if (reviewed || tool !== "claude") return reviewed;
   // An explicit override remains authoritative even while unusable: callers
@@ -124,6 +220,10 @@ export function findReviewedVendorCliBinary(
   const override = vendorOverrideName(tool, environmentPrefix);
   if (override && environmentValue(environment, override)) return null;
 
+  if (platform === "win32") {
+    return reviewedWindowsClaudeFallback(environment, environmentPrefix, accept, { find, realpath, stat });
+  }
+
   // The standalone Claude installer keeps releases side by side under
   // versions/<release> and its auto-updater only moves the launcher symlink.
   // When the symlink drifts past the reviewed release, resolve the exact
@@ -153,9 +253,9 @@ export function findReviewedVendorCliBinary(
 }
 
 /**
- * Resolve a launch target. macOS deliberately returns null when only an
- * unreviewed or version-drifted binary exists so callers can request repair
- * instead of silently launching it.
+ * Resolve a launch target. macOS and Windows deliberately return null when
+ * only an unreviewed or version-drifted binary exists so callers can request
+ * repair instead of silently launching it.
  */
 export function resolveReviewedVendorCliBinary(
   tool,
@@ -163,7 +263,7 @@ export function resolveReviewedVendorCliBinary(
   platform = process.platform,
   environmentPrefix = "IMPEL",
 ) {
-  if (platform !== "darwin") {
+  if (platform !== "darwin" && platform !== "win32") {
     return resolveNativeBinary(tool, environment, platform, environmentPrefix);
   }
   return findReviewedVendorCliBinary(tool, environment, platform, environmentPrefix);

package/src/windowsFs.js

@@ -42,3 +42,26 @@ export function renameWithWindowsRetry(from, to, {
     }
   }
 }
+
+// chmod on Windows only toggles the FAT-era read-only attribute — it cannot
+// deliver the owner-only guarantee the POSIX callers rely on, and it fails
+// EPERM whenever the file is momentarily held by antivirus or carries an
+// inherited deny ACL (observed in the field: `setup.shared_vendor_clis`
+// aborting a whole tenant convergence over chmod of a managed models.json).
+// On POSIX the mode bits are a real security property, so failures there
+// still throw unless the caller explicitly opts into best-effort.
+
+/** chmod that swallows Windows failures; POSIX failures throw unless bestEffort. */
+export function chmodWithPlatformPolicy(target, mode, {
+  platform = process.platform,
+  chmod = fs.chmodSync,
+  bestEffort = false,
+} = {}) {
+  try {
+    chmod(target, mode);
+    return true;
+  } catch (error) {
+    if (platform === "win32" || bestEffort) return false;
+    throw error;
+  }
+}

package/src/windowsSetup.js

@@ -5,9 +5,13 @@ import { ensureImpelClaudeProfile, ensureImpelCodexProfile } from "./cliProfiles
 import {
   findNativeBinary,
   nativeCommandInvocation,
-  nativeSpawnInvocation,
 } from "./nativeProcess.js";
 import { syncSkillsSafe } from "./skills.js";
+import {
+  findReviewedVendorCliBinary,
+  verifyReviewedWindowsVendorCli,
+  windowsVendorCliVersion,
+} from "./vendorCliBinaries.js";
 import { PINNED_VENDOR_CLI_VERSIONS } from "./vendorCliVersions.js";
 import { provisionWindowsGit } from "./windowsGit.js";
 
@@ -47,37 +51,49 @@ export function windowsCliInstallCommands(tools = Object.keys(WINDOWS_CLI_INSTAL
   }));
 }
 
-function verifyWindowsCli(_tool, binary, environment) {
-  try {
-    const invocation = nativeSpawnInvocation(binary, ["--version"], environment, "win32");
-    const result = spawnSync(invocation.command, invocation.args, {
-      encoding: "utf8",
-      env: environment,
-      stdio: ["ignore", "pipe", "pipe"],
-      timeout: 15_000,
-      windowsHide: true,
-      windowsVerbatimArguments: invocation.windowsVerbatimArguments,
-    });
-    return result?.status === 0 && !result?.error;
-  } catch {
-    return false;
-  }
+function verifyWindowsCli(tool, binary, environment) {
+  // The exact reviewed release, matching the macOS contract: a runnable but
+  // version-drifted vendor CLI must count as missing so setup/update repair
+  // it, instead of launching an unreviewed build against the gateway
+  // (observed in the field: Windows Claude auto-updated past the pin and the
+  // gateway rejected the session while macOS stayed on the reviewed release).
+  return verifyReviewedWindowsVendorCli(tool, binary, environment);
 }
 
 function detectWindowsClis(find, environment, verify) {
-  const detect = (tool) => find(
-    tool,
-    environment,
-    "win32",
-    "IMPEL",
-    (binary) => verify(tool, binary, environment),
-  );
+  // Detection must share the launcher's reviewed resolution (including the
+  // side-by-side fallback after vendor auto-update drift); a raw PATH probe
+  // here would classify a drifted-but-launchable install as missing and
+  // reinstall it on every setup/update pass.
+  const detect = (tool) => findReviewedVendorCliBinary(tool, environment, "win32", "IMPEL", {
+    find,
+    verify: (candidateTool, binary, candidateEnvironment) =>
+      verify(candidateTool, binary, candidateEnvironment),
+  });
   return {
     claude: detect("claude"),
     codex: detect("codex"),
   };
 }
 
+/**
+ * Pin-agnostic probe for the drift diagnostic: which build is actually on
+ * this machine when the reviewed detection came back empty.
+ */
+function detectDriftedWindowsClis(find, environment, binaries, { versionOf = windowsVendorCliVersion } = {}) {
+  const drifted = {};
+  for (const tool of ["claude", "codex"]) {
+    if (binaries[tool]) continue;
+    const binary = find(tool, environment, "win32", "IMPEL");
+    if (!binary) continue;
+    const version = versionOf(binary, environment);
+    if (version && version !== PINNED_VENDOR_CLI_VERSIONS[tool]) {
+      drifted[tool] = { binary, version, pinned: PINNED_VENDOR_CLI_VERSIONS[tool] };
+    }
+  }
+  return drifted;
+}
+
 function installCli(tool, { environment, run }) {
   const installer = WINDOWS_CLI_INSTALLERS[tool];
   if (!installer) throw new Error(`unsupported Windows CLI installer: ${tool}`);
@@ -132,6 +148,7 @@ export async function prepareWindowsClis({
     environment: process.env,
     find: findNativeBinary,
     verify: verifyWindowsCli,
+    versionOf: windowsVendorCliVersion,
     run: spawnSync,
     ensureClaudeProfile: ensureImpelClaudeProfile,
     ensureCodexProfile: ensureImpelCodexProfile,
@@ -164,6 +181,7 @@ export async function prepareWindowsClis({
       binaries: before,
       missingBefore,
       missingAfter: [...missingBefore],
+      drifted: detectDriftedWindowsClis(io.find, io.environment, before, { versionOf: io.versionOf }),
       installAttempted: false,
       installSucceeded: null,
       installFailure: null,
@@ -219,6 +237,7 @@ export async function prepareWindowsClis({
   const binaries = installAttempted
     ? detectWindowsClis(io.find, io.environment, io.verify)
     : before;
+  const drifted = detectDriftedWindowsClis(io.find, io.environment, binaries, { versionOf: io.versionOf });
   const claudeProfile = io.ensureClaudeProfile(gatewayUrl, tenantId);
   const codexProfile = io.ensureCodexProfile(gatewayUrl, tenantId);
 
@@ -248,6 +267,7 @@ export async function prepareWindowsClis({
     binaries,
     missingBefore,
     missingAfter: Object.entries(binaries).filter(([, binary]) => !binary).map(([tool]) => tool),
+    drifted,
     installAttempted,
     installSucceeded,
     installFailure,