impel-cli 0.20.40 → 0.20.42

package/src/nativeAgentTransport.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import {
   CONFIG_DIR,
@@ -27,6 +28,7 @@ import {
 } from "./selfInvocation.js";
 import { normalizeTenantId } from "./tenants.js";
 import { renameWithWindowsRetry } from "./windowsFs.js";
+import { CURRENT_CONFIG_VERSION } from "./managedProfileVersion.js";
 
 export {
   NATIVE_AGENT_ANSWER_TOOL,
@@ -38,6 +40,9 @@ export {
 export const NATIVE_AGENT_HANDLE_SCHEMA = "impel.native-agent-run.v1";
 export const NATIVE_AGENT_RESULT_SCHEMA = "impel.native-agent-result.v1";
 export const NATIVE_AGENT_RECOVERY_SCHEMA = "impel.native-agent-recovery.v1";
+export const NATIVE_AGENT_CLIENT_BUILD = `cli/${JSON.parse(
+  fs.readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"),
+).version}+manifest.v${CURRENT_CONFIG_VERSION}`;
 
 const STATE_SCHEMA = "impel.native-agent-state.v1";
 const DELETION_SCHEMA = "impel.native-agent-deletion.v1";
@@ -49,6 +54,7 @@ const DEFAULT_WAIT_SECONDS = 20;
 const MAX_WAIT_SECONDS = 35;
 const DEFAULT_ATTACHMENT_WINDOW_MS = 40_000;
 const DEFAULT_UPSTREAM_TIMEOUT_MS = 42_000;
+const DEFAULT_ANSWER_HEDGE_MS = 38_000;
 const DEFAULT_MAX_POLLS = 8;
 const DEFAULT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 const DEFAULT_MAX_RETAINED_RUNS = 500;
@@ -68,6 +74,11 @@ const MANAGED_VIRTUAL_KEY_MISS_RETRY_DELAY_MS = 250;
 const NEXT_AMBIGUOUS_ANSWER_CODE = "native_agent_answer_ambiguous";
 const MCP_TOOL_RESULT_ERROR = Symbol("native-agent MCP tool result error");
 const TERMINAL_STATUSES = new Set(["succeeded", "failed", "cancelled", "canceled"]);
+const SAFE_CLIENT_BUILD_RE = /^[A-Za-z0-9._+/-]{1,128}$/u;
+
+if (!SAFE_CLIENT_BUILD_RE.test(NATIVE_AGENT_CLIENT_BUILD)) {
+  throw new Error("native-agent client build header is invalid");
+}
 
 export function nativeAgentAttachmentWindowMs(environment = process.env) {
   const configured = environment?.[IMPEL_NATIVE_AGENT_ATTACHMENT_WINDOW_ENV];
@@ -82,6 +93,30 @@ export function nativeAgentAttachmentWindowMs(environment = process.env) {
   return parsed;
 }
 
+export function nativeAgentAnswerHedgeMs(environment = process.env, { warn = console.warn } = {}) {
+  const configured = environment?.IMPEL_NATIVE_ANSWER_HEDGE_MS;
+  if (configured === undefined) return DEFAULT_ANSWER_HEDGE_MS;
+  if (!/^\d{1,9}$/u.test(configured)) {
+    warn(`IMPEL_NATIVE_ANSWER_HEDGE_MS must be a non-negative integer; using ${DEFAULT_ANSWER_HEDGE_MS}ms`);
+    return DEFAULT_ANSWER_HEDGE_MS;
+  }
+  const parsed = Number(configured);
+  if (!Number.isSafeInteger(parsed)) {
+    warn(`IMPEL_NATIVE_ANSWER_HEDGE_MS must be a safe integer; using ${DEFAULT_ANSWER_HEDGE_MS}ms`);
+    return DEFAULT_ANSWER_HEDGE_MS;
+  }
+  if (parsed === 0) return 0;
+  const maximum = Math.min(DEFAULT_ATTACHMENT_WINDOW_MS, DEFAULT_UPSTREAM_TIMEOUT_MS) - 1;
+  if (parsed >= DEFAULT_ATTACHMENT_WINDOW_MS || parsed >= DEFAULT_UPSTREAM_TIMEOUT_MS) {
+    warn(
+      `IMPEL_NATIVE_ANSWER_HEDGE_MS must be below ${DEFAULT_ATTACHMENT_WINDOW_MS}ms `
+      + `and ${DEFAULT_UPSTREAM_TIMEOUT_MS}ms; clamping to ${maximum}ms`,
+    );
+    return maximum;
+  }
+  return parsed;
+}
+
 function stableValue(value) {
   if (Array.isArray(value)) return value.map(stableValue);
   if (!value || typeof value !== "object") return value;
@@ -704,6 +739,9 @@ export class NativeAgentUpstreamSession {
     telemetry = () => {},
     now = Date.now,
     requestIdFactory = crypto.randomUUID,
+    answerHedgeMs = nativeAgentAnswerHedgeMs(),
+    setTimeoutImpl = setTimeout,
+    clearTimeoutImpl = clearTimeout,
   }) {
     this.endpoint = `${normalizeGatewayUrl(gatewayUrl)}/mcp`;
     this.credential = credential;
@@ -714,6 +752,9 @@ export class NativeAgentUpstreamSession {
     this.telemetry = telemetry;
     this.now = now;
     this.requestIdFactory = requestIdFactory;
+    this.answerHedgeMs = Math.max(0, answerHedgeMs);
+    this.setTimeoutImpl = setTimeoutImpl;
+    this.clearTimeoutImpl = clearTimeoutImpl;
     this.sessionId = null;
     this.nextId = 1;
   }
@@ -729,7 +770,7 @@ export class NativeAgentUpstreamSession {
     let timedOut = false;
     const onAbort = () => controller.abort();
     signal?.addEventListener("abort", onAbort, { once: true });
-    const timeout = setTimeout(() => {
+    const timeout = this.setTimeoutImpl(() => {
       timedOut = true;
       controller.abort();
     }, this.timeoutMs);
@@ -743,6 +784,7 @@ export class NativeAgentUpstreamSession {
           "Content-Type": "application/json",
           Accept: "application/json, text/event-stream",
           "X-Impel-Client-Request-Id": correlationId,
+          "X-Impel-Client-Build": NATIVE_AGENT_CLIENT_BUILD,
           ...(this.sessionId ? { "Mcp-Session-Id": this.sessionId } : {}),
         },
         body: JSON.stringify(message),
@@ -760,7 +802,7 @@ export class NativeAgentUpstreamSession {
       const detail = timedOut ? "request timed out" : redactSecretText(error?.message || error);
       throw new NativeAgentUpstreamError(`native-agent MCP request failed: ${detail}`, { ambiguous: true });
     } finally {
-      clearTimeout(timeout);
+      this.clearTimeoutImpl(timeout);
       signal?.removeEventListener("abort", onAbort);
     }
     this.telemetry("upstream_request_completed", {
@@ -814,17 +856,78 @@ export class NativeAgentUpstreamSession {
     return toolsResponse.result.tools;
   }
 
-  async call(name, args, { signal } = {}) {
+  async ping({ signal } = {}) {
+    const id = this.nextId++;
+    const messages = await this.post({ jsonrpc: "2.0", id, method: "ping", params: {} }, { signal });
+    const response = messages.find((message) => message?.id === id);
+    if (response?.error || !response?.result || typeof response.result !== "object") {
+      throw new NativeAgentUpstreamError("native-agent MCP ping failed");
+    }
+  }
+
+  async callAnswerWithHedge(message, { signal, onHedge } = {}) {
+    throwIfAborted(signal);
+    const startedAt = this.now();
+    const controller = new AbortController();
+    let hedgeFired = false;
+    let elapsedMs = 0;
+    let replayTerminal = false;
+    const onAbort = () => controller.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = this.setTimeoutImpl(() => {
+      if (controller.signal.aborted) return;
+      hedgeFired = true;
+      elapsedMs = Math.max(0, this.now() - startedAt);
+      onHedge?.();
+      controller.abort();
+    }, this.answerHedgeMs);
+    try {
+      try {
+        const messages = await this.post(message, { signal: controller.signal });
+        return toolPayload(messages.find((candidate) => candidate?.id === message.id));
+      } catch (error) {
+        if (!hedgeFired || signal?.aborted) throw error;
+      } finally {
+        this.clearTimeoutImpl(timer);
+        signal?.removeEventListener("abort", onAbort);
+      }
+
+      try {
+        const messages = await this.post(message, { signal });
+        const payload = toolPayload(messages.find((candidate) => candidate?.id === message.id));
+        replayTerminal = TERMINAL_STATUSES.has(payload?.status);
+        return payload;
+      } finally {
+        this.telemetry("hedge_fired", { elapsedMs, replayTerminal });
+      }
+    } finally {
+      this.clearTimeoutImpl(timer);
+      signal?.removeEventListener("abort", onAbort);
+    }
+  }
+
+  async call(name, args, { signal = this.signal, hedge = true } = {}) {
+    let hedgeFiredForCall = false;
     for (let attempt = 0; attempt < 2; attempt += 1) {
       const id = this.nextId++;
+      const message = {
+        jsonrpc: "2.0",
+        id,
+        method: "tools/call",
+        params: { name, arguments: args },
+      };
       try {
-        const messages = await this.post({
-          jsonrpc: "2.0",
-          id,
-          method: "tools/call",
-          params: { name, arguments: args },
-        }, { signal });
-        return toolPayload(messages.find((message) => message?.id === id));
+        if (name === NATIVE_AGENT_UPSTREAM_ANSWER_TOOL
+          && hedge
+          && !hedgeFiredForCall
+          && this.answerHedgeMs > 0) {
+          return await this.callAnswerWithHedge(message, {
+            signal,
+            onHedge: () => { hedgeFiredForCall = true; },
+          });
+        }
+        const messages = await this.post(message, { signal });
+        return toolPayload(messages.find((candidate) => candidate?.id === id));
       } catch (error) {
         if (attempt === 0 && retryableManagedVirtualKeyMiss(error)) {
           // This gateway-authored miss happens before a native run can exist.
@@ -1700,7 +1803,7 @@ export class NativeAgentCompositeTransport {
     }
   }
 
-  async prepareExistingSession(signal) {
+  async prepareExistingSession(signal, { prewarmed = false } = {}) {
     const reused = Boolean(this.preparedSession);
     const startedAt = this.now();
     if (!this.preparedSession) {
@@ -1717,15 +1820,16 @@ export class NativeAgentCompositeTransport {
     this.telemetry("session_prepared", {
       durationMs: this.now() - startedAt,
       handshakeReused: reused,
+      prewarmed,
     });
     return prepared;
   }
 
-  async prepareNewSession(signal) {
-    const prepared = await this.prepareExistingSession(signal);
+  async prepareNewSession(signal, { prewarmed = false } = {}) {
+    const prepared = await this.prepareExistingSession(signal, { prewarmed });
     const startedAt = this.now();
     if (this.preparedAgent) {
-      this.telemetry("binding_completed", { durationMs: 0, bindingReused: true });
+      this.telemetry("binding_completed", { durationMs: 0, bindingReused: true, prewarmed });
       return { ...prepared, agent: this.preparedAgent };
     }
     const catalog = normalizeNativeAgentCatalog(
@@ -1746,10 +1850,29 @@ export class NativeAgentCompositeTransport {
     this.telemetry("binding_completed", {
       durationMs: this.now() - startedAt,
       bindingReused: false,
+      prewarmed,
     });
     return { ...prepared, agent: this.preparedAgent };
   }
 
+  async refreshPreparedSession(signal, { prewarmed = true } = {}) {
+    const prepared = await this.prepareNewSession(signal, { prewarmed });
+    try {
+      await prepared.session.ping({ signal });
+    } catch (error) {
+      const cached = this.preparedSession;
+      if (cached) {
+        try {
+          if ((await cached).session === prepared.session) this.preparedSession = null;
+        } catch {
+          this.preparedSession = null;
+        }
+      }
+      throw error;
+    }
+    return prepared;
+  }
+
   async preparePersistedStartSession(signal, state) {
     const prepared = await this.prepareExistingSession(signal);
     const catalog = normalizeNativeAgentCatalog(
@@ -2189,7 +2312,7 @@ export class NativeAgentCompositeTransport {
             started = await session.call(
               answerMode ? NATIVE_AGENT_UPSTREAM_ANSWER_TOOL : NATIVE_AGENT_START_TOOL,
               outboundArguments,
-              { signal },
+              { signal, hedge: answerMode && attempt === 0 },
             );
             if (answerMode) {
               if (!started?.runId) {

package/src/nativeInterception.js

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { impelCliInvocation } from "./selfInvocation.js";
+import { renameWithWindowsRetry } from "./windowsFs.js";
+
+export const IMPEL_NATIVE_INTERCEPT_ENV = "IMPEL_NATIVE_INTERCEPT";
+export const IMPEL_NATIVE_INTERCEPT_TIMEOUT_ENV = "IMPEL_NATIVE_INTERCEPT_TIMEOUT_MS";
+export const DEFAULT_NATIVE_INTERCEPT_TIMEOUT_MS = 100_000;
+export const MANAGED_NATIVE_INTERCEPT_FLAG = "impel-managed-native-intercept-v1";
+
+export function nativeInterceptEnabled(environment = process.env) {
+  return ["1", "true"].includes(
+    String(environment?.[IMPEL_NATIVE_INTERCEPT_ENV] || "").toLowerCase(),
+  );
+}
+
+export function nativeInterceptTimeoutMs(environment = process.env) {
+  const configured = environment?.[IMPEL_NATIVE_INTERCEPT_TIMEOUT_ENV];
+  if (configured === undefined || configured === "") return DEFAULT_NATIVE_INTERCEPT_TIMEOUT_MS;
+  if (!/^\d{1,6}$/u.test(configured)) {
+    throw new Error(`${IMPEL_NATIVE_INTERCEPT_TIMEOUT_ENV} must be an integer from 1000 through 300000`);
+  }
+  const timeoutMs = Number(configured);
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1_000 || timeoutMs > 300_000) {
+    throw new Error(`${IMPEL_NATIVE_INTERCEPT_TIMEOUT_ENV} must be an integer from 1000 through 300000`);
+  }
+  return timeoutMs;
+}
+
+function readJsonObject(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  const raw = fs.readFileSync(filePath, "utf8").trim();
+  if (!raw) return {};
+  try {
+    const value = JSON.parse(raw);
+    if (!value || Array.isArray(value) || typeof value !== "object") throw new Error();
+    return value;
+  } catch {
+    throw new Error(`${filePath} exists but isn't a valid JSON object. Fix or remove it, then re-run.`);
+  }
+}
+
+function writePrivateJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const temporaryPath = `${filePath}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    renameWithWindowsRetry(temporaryPath, filePath);
+    try { fs.chmodSync(filePath, 0o600); } catch { /* Best effort on Windows. */ }
+  } finally {
+    try { fs.rmSync(temporaryPath, { force: true }); } catch { /* Rename removed it. */ }
+  }
+}
+
+function handlerIsManaged(handler) {
+  return handler
+    && typeof handler === "object"
+    && Array.isArray(handler.args)
+    && handler.args.includes(`--${MANAGED_NATIVE_INTERCEPT_FLAG}`);
+}
+
+function removeManagedHandlers(groups) {
+  if (!Array.isArray(groups)) return { groups, changed: false };
+  let changed = false;
+  const preserved = [];
+  for (const group of groups) {
+    if (!group || typeof group !== "object" || !Array.isArray(group.hooks)) {
+      preserved.push(group);
+      continue;
+    }
+    const hooks = group.hooks.filter((handler) => {
+      if (!handlerIsManaged(handler)) return true;
+      changed = true;
+      return false;
+    });
+    if (hooks.length > 0) preserved.push({ ...group, hooks });
+  }
+  return { groups: preserved, changed };
+}
+
+export function claudeNativeInterceptHandler(tenantId, timeoutMs, invocation = null) {
+  const command = invocation || impelCliInvocation([
+    "native", "intercept",
+    "--tenant", tenantId,
+    `--${MANAGED_NATIVE_INTERCEPT_FLAG}`,
+  ]);
+  return {
+    type: "command",
+    command: command.command,
+    args: [...command.args],
+    timeout: Math.ceil(timeoutMs / 1000),
+    async: false,
+  };
+}
+
+/** Install or remove only Impel's synchronous UserPromptSubmit interception hook. */
+export function ensureClaudeNativeInterceptHook(configDir, tenantId, {
+  enabled = false,
+  timeoutMs = DEFAULT_NATIVE_INTERCEPT_TIMEOUT_MS,
+  invocation = null,
+} = {}) {
+  const settingsPath = path.join(configDir, "settings.json");
+  if (!enabled) {
+    try {
+      if (!fs.readFileSync(settingsPath, "utf8").includes(`--${MANAGED_NATIVE_INTERCEPT_FLAG}`)) {
+        return { settingsPath, enabled: false, changed: false };
+      }
+    } catch (error) {
+      if (error?.code === "ENOENT") return { settingsPath, enabled: false, changed: false };
+      throw error;
+    }
+  }
+  const settings = readJsonObject(settingsPath);
+  const hooks = settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks)
+    ? { ...settings.hooks }
+    : {};
+  const removed = removeManagedHandlers(hooks.UserPromptSubmit);
+  if (!enabled && !removed.changed) {
+    return { settingsPath, enabled: false, changed: false };
+  }
+  if (enabled) {
+    removed.groups.push({
+      hooks: [claudeNativeInterceptHandler(tenantId, timeoutMs, invocation)],
+    });
+  }
+  if (removed.groups.length > 0) hooks.UserPromptSubmit = removed.groups;
+  else delete hooks.UserPromptSubmit;
+  if (Object.keys(hooks).length > 0) settings.hooks = hooks;
+  else delete settings.hooks;
+  writePrivateJson(settingsPath, settings);
+  return { settingsPath, enabled, changed: true };
+}

package/src/windowsApps.js

@@ -90,6 +90,71 @@ function installedMsixChatGPT(environment, run = spawnSync, pin = null) {
   }
 }
 
+/**
+ * Register the already-staged ChatGPT Store package for the current user.
+ * winget resolves packages machine-wide, so on a machine where another user
+ * (or provisioning) installed the app, `winget install` reports
+ * UPDATE_NOT_APPLICABLE while the current user's Get-AppxPackage sees
+ * nothing. Add-AppxPackage -RegisterByFamilyName registers the existing
+ * staged bits for this user without downloading or elevating.
+ */
+export function registerProvisionedMsixChatGPT(environment, run = spawnSync) {
+  const familyName = `${WINDOWS_CHATGPT_PACKAGE_NAME}_${WINDOWS_CHATGPT_PUBLISHER_ID}`;
+  try {
+    const result = run("powershell.exe", [
+      "-NoProfile",
+      "-NonInteractive",
+      "-Command",
+      `Add-AppxPackage -RegisterByFamilyName -MainPackage '${familyName}' -ErrorAction Stop`,
+    ], {
+      encoding: "utf8",
+      env: windowsPowerShellEnvironment(environment),
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 120_000,
+      windowsHide: true,
+    });
+    return result?.status === 0 && !result?.error;
+  } catch {
+    return false;
+  }
+}
+
+function compareDottedVersions(left, right) {
+  const parse = (value) => String(value).split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const a = parse(left);
+  const b = parse(right);
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    const delta = (a[index] || 0) - (b[index] || 0);
+    if (delta !== 0) return delta;
+  }
+  return 0;
+}
+
+/**
+ * The version string of whatever ChatGPT Store package is installed,
+ * regardless of the reviewed pin. Diagnostic-only: it lets a pin mismatch
+ * name the actual installed version instead of a bare winget HRESULT.
+ */
+export function installedMsixChatGPTVersion(environment, run = spawnSync) {
+  const script = [
+    `$package = Get-AppxPackage -Name '${WINDOWS_CHATGPT_PACKAGE_NAME}' -ErrorAction SilentlyContinue`,
+    `$package = $package | Where-Object { $_.PublisherId -ceq '${WINDOWS_CHATGPT_PUBLISHER_ID}' } | Sort-Object Version -Descending | Select-Object -First 1`,
+    "if ($package) { $package.Version.ToString() }",
+  ].join("; ");
+  try {
+    const result = run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+      encoding: "utf8",
+      env: windowsPowerShellEnvironment(environment),
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 15_000,
+      windowsHide: true,
+    });
+    return result?.status === 0 ? String(result.stdout || "").trim() || null : null;
+  } catch {
+    return null;
+  }
+}
+
 /** Candidate paths for Anthropic's signed per-user Windows desktop install. */
 export function windowsClaudeAppCandidates(environment = process.env, dependencies = {}) {
   const io = { readDirectory: fs.readdirSync, ...dependencies };
@@ -148,7 +213,7 @@ export function findWindowsChatGPTApp(environment = process.env, dependencies =
   return msix && exists(msix) ? path.win32.normalize(msix) : null;
 }
 
-function pinnedWindowsChatGPTApp(environment = process.env, dependencies = {}) {
+export function pinnedWindowsChatGPTApp(environment = process.env, dependencies = {}) {
   const exists = dependencies.isFile || isFile;
   const pin = dependencies.pin || WINDOWS_CHATGPT_PIN;
   const msix = (dependencies.queryMsix || installedMsixChatGPT)(environment, dependencies.run, pin);
@@ -434,16 +499,36 @@ export function ensureWindowsChatGPTApp({ update = false } = {}, dependencies =
     result = { status: null, error };
   }
   let resultBinary = io.findPinned(io.environment, { pin: io.pin, run: io.run });
-  // 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
-    && resultBinary
-    && !result?.error
+  const noApplicableUpgrade = !result?.error
     && Number.isInteger(result?.status)
-    && (result.status >>> 0) === WINDOWS_WINGET_UPDATE_NOT_APPLICABLE,
-  );
+    && (result.status >>> 0) === WINDOWS_WINGET_UPDATE_NOT_APPLICABLE;
+  // winget resolves machine-wide: when it reports the package installed but
+  // the current user's probe sees nothing, the staged bits are registered to
+  // another user or provisioning. Registering them for this user is a local,
+  // download-free repair; the pin-exact probe afterwards keeps it fail-closed.
+  let registeredOffPin = false;
+  if (noApplicableUpgrade && !resultBinary) {
+    io.logger.log("ChatGPT/Codex: attempting to register the machine-wide Microsoft Store package for the current user…");
+    if ((io.registerProvisioned || registerProvisionedMsixChatGPT)(io.environment, io.run)) {
+      resultBinary = io.findPinned(io.environment, { pin: io.pin, run: io.run });
+      if (resultBinary) {
+        io.logger.log("ChatGPT/Codex: registered the already-staged Microsoft Store package for the current user.");
+      } else {
+        registeredOffPin = true;
+      }
+    } else {
+      io.logger.log("ChatGPT/Codex: the Store package could not be registered for the current user.");
+    }
+  }
+  // winget uses an error HRESULT when it finds an installed package with no
+  // newer Store release (APPINSTALLER_CLI_ERROR_UPDATE_NOT_APPLICABLE). That
+  // is a healthy idempotent result whenever the pin-exact re-query proves the
+  // reviewed package is present — during setup/install as much as update:
+  // `winget install` reports the same HRESULT for an already-installed
+  // package, and treating it as failure strands first-run machines in an
+  // unconvergeable recovery loop. Acceptance stays fail-closed through the
+  // pin-exact probe below.
+  const alreadyUpToDate = Boolean(resultBinary && noApplicableUpgrade);
   if (alreadyUpToDate) {
     io.logger.log(`ChatGPT/Codex: Microsoft Store package ${io.pin.packageVersion} already up to date.`);
   }
@@ -456,6 +541,33 @@ export function ensureWindowsChatGPTApp({ update = false } = {}, dependencies =
       ),
     };
   }
+  // A no-applicable-upgrade result over a package that fails the pin-exact
+  // probe means the Store carries a different (usually newer) build the
+  // Store cannot downgrade. Name both versions so the operator learns this
+  // needs a CLI release with an updated ChatGPT pin, not another retry.
+  if (!commandSucceeded && !resultBinary && noApplicableUpgrade) {
+    const installedVersion = (io.installedVersion || installedMsixChatGPTVersion)(io.environment, io.run);
+    if (installedVersion) {
+      const newer = compareDottedVersions(installedVersion, io.pin.packageVersion) > 0;
+      result = {
+        ...result,
+        error: new Error(
+          `installed ChatGPT Store package ${installedVersion} does not match the reviewed pin ${io.pin.packageVersion}; `
+          + (newer
+            ? "the Microsoft Store cannot downgrade, so this needs a CLI release with an updated ChatGPT pin"
+            : "the Store has not fulfilled the pinned build on this machine yet — retry once the Store catches up"),
+        ),
+      };
+    } else if (registeredOffPin) {
+      result = {
+        ...result,
+        error: new Error(
+          "a machine-wide ChatGPT Store package was registered for the current user but does not match "
+          + `the reviewed pin ${io.pin.packageVersion}; the managed app stays uninstalled until a matching build is available`,
+        ),
+      };
+    }
+  }
   const succeeded = commandSucceeded && Boolean(resultBinary);
   if (!succeeded) resultBinary = null;
   return {