@bitkyc08/opencodex 2.7.43 → 2.8.2-preview.20260731

package/src/lib/bun-binary-validator.mjs

@@ -0,0 +1,18 @@
+import { existsSync, statSync } from "node:fs";
+
+// The `bun` package leaves a tiny ASCII placeholder at bin/bun.exe until its
+// postinstall downloads the real ~60MB binary. Keep the threshold and the
+// false-on-filesystem-error contract shared by the Node launcher and Bun code.
+export const REAL_BUN_MIN_BYTES = 1_000_000;
+
+/**
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function isRealBunBinary(path) {
+  try {
+    return existsSync(path) && statSync(path).size >= REAL_BUN_MIN_BYTES;
+  } catch {
+    return false;
+  }
+}

package/src/lib/bun-runtime.ts

@@ -11,15 +11,13 @@
  * back to `process.execPath` (which is itself Bun when run via `bun src/cli/index.ts`).
  */
 import { createRequire } from "node:module";
-import { existsSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { isRealBunBinary } from "./bun-binary-validator.mjs";
+
+export { isRealBunBinary };
 
 const require = createRequire(import.meta.url);
 
-// The `bun` package leaves a tiny ASCII placeholder at bin/bun.exe until its
-// postinstall downloads the real ~60MB binary; reject the stub by size so we
-// never bake a non-executable path into durable artifacts.
-const REAL_BUN_MIN_BYTES = 1_000_000;
 const BUN_OVERRIDE_ENV = "OPENCODEX_BUN_PATH";
 
 export type DurableBunRuntime = {
@@ -28,19 +26,6 @@ export type DurableBunRuntime = {
   overrideEnv: typeof BUN_OVERRIDE_ENV;
 };
 
-/**
- * True only for a real, downloaded Bun binary — not the ~450-byte ASCII
- * placeholder stub left by `--ignore-scripts` / pnpm. A size gate cleanly
- * separates the two on every platform (real binary is tens of MB).
- */
-export function isRealBunBinary(path: string): boolean {
-  try {
-    return existsSync(path) && statSync(path).size >= REAL_BUN_MIN_BYTES;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Absolute path to the bundled Bun binary, or null if the `bun` dependency is
  * not installed/resolvable (or only the un-downloaded placeholder is present).
@@ -63,7 +48,8 @@ export function bundledBunPath(): string | null {
 export function overrideBunPath(): string | null {
   const value = process.env[BUN_OVERRIDE_ENV]?.trim();
   if (!value) return null;
-  return isRealBunBinary(value) ? value : null;
+  const resolved = resolve(value);
+  return isRealBunBinary(resolved) ? resolved : null;
 }
 
 export function durableBunRuntime(): DurableBunRuntime {

package/src/lib/destination-policy.ts

@@ -130,13 +130,31 @@ function registryAllowsPrivateNetwork(name: string): boolean {
   return getProviderRegistryEntry(name)?.allowPrivateNetworkByDefault === true;
 }
 
+/**
+ * Whether a provider may reach loopback/private addresses.
+ *
+ * Two sources, and both have to be consulted at every boundary: the operator's explicit
+ * `allowPrivateNetwork`, and the registry's `allowPrivateNetworkByDefault` for entries that are
+ * local BY DEFINITION (Ollama, vLLM, LM Studio, LiteLLM). Config validation already read both;
+ * outbound discovery read only the first, so a stock Ollama entry passed validation and was then
+ * refused at the fetch (#758).
+ *
+ * This grants nothing new. Metadata, link-local and unspecified destinations are rejected before
+ * this is consulted, and a provider without either source still cannot reach a private address.
+ */
+export function providerAllowsPrivateNetwork(
+  name: string,
+  provider: Pick<OcxProviderConfig, "allowPrivateNetwork">,
+): boolean {
+  return provider.allowPrivateNetwork === true || registryAllowsPrivateNetwork(name);
+}
+
 export function providerDestinationConfigError(name: string, provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">): string | null {
   const assessment = assessDestination(provider.baseUrl);
   if (!assessment) return null;
   if (assessment.kind === "public" || assessment.kind === "hostname") return null;
   if (assessment.kind === "metadata") return "baseUrl targets a blocked metadata endpoint";
-  if (registryAllowsPrivateNetwork(name)) return null;
-  if (provider.allowPrivateNetwork === true) return null;
+  if (providerAllowsPrivateNetwork(name, provider)) return null;
   return `baseUrl points to a ${assessment.detail}; set allowPrivateNetwork:true only for intentionally local/self-hosted providers`;
 }
 
@@ -174,7 +192,7 @@ export async function providerDestinationResolvedError(
   if (!hostname || isIP(hostname) !== 0 || hostname === "localhost" || hostname.endsWith(".localhost")) {
     return null; // literals and localhost are fully handled by the sync path
   }
-  if (registryAllowsPrivateNetwork(name) || provider.allowPrivateNetwork === true) return null;
+  if (providerAllowsPrivateNetwork(name, provider)) return null;
   let addresses: { address: string }[];
   try {
     addresses = await lookup(hostname, { all: true, verbatim: true });

package/src/lib/provider-outbound.ts

@@ -2,6 +2,7 @@ import type { OcxProviderConfig } from "../types";
 import {
   assessUrlDestination,
   DestinationDnsResolutionError,
+  providerAllowsPrivateNetwork,
   providerDestinationConfigError,
   resolvePublicAddresses,
 } from "./destination-policy";
@@ -116,7 +117,11 @@ export async function providerOutboundGet(
     if (assessment?.kind === "metadata" || assessment?.kind === "link-local" || assessment?.kind === "unspecified") {
       throw new ProviderOutboundPolicyError(`provider URL targets ${assessment.detail}`);
     }
-    if (!provider.allowPrivateNetwork) {
+    // Registry defaults count here too, not just the operator flag: a stock Ollama entry is
+    // local by definition and previously passed config validation only to be refused at the
+    // fetch (#758). Metadata/link-local/unspecified were already rejected above.
+    const allowPrivate = providerAllowsPrivateNetwork(name, provider);
+    if (!allowPrivate) {
       const destinationError = providerDestinationConfigError(name, {
         baseUrl: url,
         allowPrivateNetwork: false,
@@ -129,11 +134,12 @@ export async function providerOutboundGet(
   const proxyConfigured = configuredProxyFor();
   const resolveAddresses = dependencies.resolveAddresses ?? resolvePublicAddresses;
   const pinnedGet = dependencies.pinnedGet ?? pinnedHttpGet;
+  const allowPrivate = providerAllowsPrivateNetwork(name, provider);
   let resolved: Awaited<ReturnType<typeof resolvePublicAddresses>>;
   try {
     resolved = await resolveAddresses(url, {
       context: "provider URL",
-      allowPrivateNetwork: provider.allowPrivateNetwork,
+      allowPrivateNetwork: allowPrivate,
     });
   } catch (error) {
     const dnsResolutionFailed = error instanceof DestinationDnsResolutionError

package/src/lib/shadow-call.ts

@@ -0,0 +1,30 @@
+/**
+ * Shadow-call intercept source models.
+ *
+ * Codex's hard-coded helper model is not stable across client versions: it was
+ * `gpt-5.4-mini` up to 0.144.x and became `gpt-5.6-luna` in 0.145.0. The
+ * intercept therefore matches a prefix SET, and every surface that names the
+ * intercepted model (management API, GUI badges/tooltips, CLI) reads it from
+ * here instead of hard-coding a slug that goes stale on the next client bump.
+ */
+export const DEFAULT_SHADOW_SOURCE_MODELS = ["gpt-5.4-mini", "gpt-5.6-luna"] as const;
+
+/** Normalize a persisted `sourceModels` override; falls back to the defaults. */
+export function shadowSourceModels(configured?: unknown): string[] {
+  const configuredStrings = Array.isArray(configured)
+    ? configured
+      .filter((v): v is string => typeof v === "string" && v.trim() !== "")
+      .map(v => v.trim())
+    : [];
+  return configuredStrings.length > 0 ? configuredStrings : [...DEFAULT_SHADOW_SOURCE_MODELS];
+}
+
+/**
+ * True when `modelId` is one of Codex's helper/shadow source models.
+ * Routed ids (`provider/model`) are hard-excluded: a shadow call is always a
+ * bare native slug, and an explicit routed selection must never be hijacked.
+ */
+export function isShadowSourceModel(modelId: string, configured?: unknown): boolean {
+  if (modelId.includes("/")) return false;
+  return shadowSourceModels(configured).some(prefix => modelId.startsWith(prefix));
+}

package/src/lib/test-home-guard.ts

@@ -0,0 +1,90 @@
+/**
+ * Fail-closed protection for the user's REAL OpenCodex home while tests run.
+ *
+ * A management-route unit test once passed an in-memory fixture config to a handler
+ * that persisted it through the process-global writer, replacing a live 41KB,
+ * ten-provider `~/.opencodex/config.json` with an 874-byte fixture on a real machine.
+ * Credentials survived only because the store files are separate; the providers were
+ * recoverable only because an unrelated backup snapshot happened to exist.
+ * (devlog `_plan/260730_codex_rs_upstream_v2_live_handoff/070`.)
+ *
+ * Two properties matter more than breadth here:
+ *
+ * 1. It must be INERT in production. Guessing "am I a test?" from ecosystem variables
+ *    like NODE_ENV would brick `NODE_ENV=test ocx ...` for a user who did nothing
+ *    wrong — worse than the bug it prevents. Arming requires OCX_TEST_HOME_GUARD=1,
+ *    which only this repository's test preload sets.
+ * 2. It must fail CLOSED for code nobody has written yet. So it denies ONE path — the
+ *    captured production home — instead of allow-listing known-good test directories.
+ *    An allowlist would have to be opted into, and the test that forgets is exactly
+ *    how this incident happened.
+ */
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { realpathSync } from "node:fs";
+
+const GUARD_ENV = "OCX_TEST_HOME_GUARD";
+/**
+ * Set by `scripts/test.ts` to the ORIGINAL home before it hands the child a rewritten
+ * HOME. On that path `homedir()` already points at the sandbox by the time this module
+ * loads, so the true home is only knowable from this hand-off.
+ */
+const REAL_HOME_ENV = "OCX_REAL_HOME";
+
+/**
+ * Resolve symlinks so two spellings of one location compare equal — macOS hands out
+ * `/var/folders/...` whose realpath is `/private/var/folders/...` — and so a path that
+ * merely *points* at the protected home cannot slip past a string comparison. A path
+ * that does not exist yet canonicalizes through its nearest existing ancestor, which is
+ * the common case for a config file about to be created.
+ */
+function canonicalize(path: string): string {
+  let current = resolve(path);
+  const unresolved: string[] = [];
+  for (;;) {
+    try {
+      return join(realpathSync.native(current), ...unresolved.reverse());
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) return resolve(path);
+      unresolved.push(current.slice(parent.length + 1));
+      current = parent;
+    }
+  }
+}
+
+/**
+ * Captured ONCE at module load, before any harness replaces HOME/USERPROFILE. Reading
+ * `homedir()` later would return the sandbox and leave the real home unprotected — the
+ * guard would be perfectly inverted while its tests still looked green.
+ */
+const PROTECTED_HOME = canonicalize(
+  join(process.env[REAL_HOME_ENV]?.trim() || homedir(), ".opencodex"),
+);
+
+/** The production home this process protects. Exported for the guard's own tests. */
+export function protectedHomeForTests(): string {
+  return PROTECTED_HOME;
+}
+
+export function isTestHomeGuardArmed(): boolean {
+  return process.env[GUARD_ENV] === "1";
+}
+
+/**
+ * Throw when an armed test process is about to write the real OpenCodex home.
+ *
+ * Call FIRST inside a writer, before any mkdir/chmod/write, so a rejected write leaves
+ * nothing behind. Silent no-op when disarmed (production) or when `dir` is any other
+ * location, including a suite's own `mkdtemp` fixture — no registration required, which
+ * is what keeps the 54 existing suites that write config working untouched.
+ */
+export function assertNotRealHomeUnderTest(dir: string): void {
+  if (!isTestHomeGuardArmed()) return;
+  if (canonicalize(dir) !== PROTECTED_HOME) return;
+  throw new Error(
+    `refusing to write the real OpenCodex home (${PROTECTED_HOME}) from a test process. `
+    + "Point OPENCODEX_HOME at a temp directory for this test, or inject persistence "
+    + "instead of calling the global writer (see devlog 260730_codex_rs_upstream_v2_live_handoff/070).",
+  );
+}

package/src/lib/win-exec.ts

@@ -44,8 +44,18 @@ export function resolveWindowsCommand(command: string, deps: ResolveDeps = {}):
   if (win32.extname(command) || command.includes("\\") || command.includes("/") || win32.isAbsolute(command)) {
     return command;
   }
-  const exts = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
-  for (const dir of (env.PATH ?? env.Path ?? "").split(win32.delimiter).filter(Boolean)) {
+  // Windows environment variables are case-insensitive, and a spawned child can
+  // arrive with `Path`, `PATH`, or both depending on who built its env. Reading
+  // only two fixed spellings silently resolved against the wrong list once a
+  // caller added a second casing, so match however the key is spelled.
+  const lookup = (name: string): string | undefined => {
+    const direct = env[name] ?? env[name.toUpperCase()] ?? env[name.toLowerCase()];
+    if (direct !== undefined) return direct;
+    const key = Object.keys(env).find(k => k.toLowerCase() === name.toLowerCase());
+    return key ? env[key] : undefined;
+  };
+  const exts = (lookup("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+  for (const dir of (lookup("PATH") ?? "").split(win32.delimiter).filter(Boolean)) {
     for (const ext of exts) {
       const candidate = win32.join(dir, command + ext.toLowerCase());
       if (exists(candidate)) return candidate;

package/src/lib/winsw.ts

@@ -165,6 +165,12 @@ function runWinsw(args: string[]): string {
 
 /** `install /p` prompts for the service-account password on the console — stdin must be inherited. */
 function runWinswInteractive(args: string[]): void {
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      "WinSW install requires an interactive console to prompt for the service account password. "
+        + "Run `ocx service install --native` from an elevated Command Prompt or PowerShell window, not a hidden or piped session.",
+    );
+  }
   execFileSync(winswExePath(), args, { stdio: "inherit" });
 }
 

package/src/oauth/index.ts

@@ -14,7 +14,8 @@ import { loginCursor, refreshCursorToken } from "./cursor";
 import { loginGithubCopilot, refreshGithubCopilotToken, validateCopilotApiBaseUrl } from "./github-copilot";
 import { deriveOAuthDefaultModel, deriveOAuthProviderConfig } from "../providers/derive";
 import { apiKeyPoolEntryId, sanitizeApiKeyValue } from "../providers/api-keys";
-import { effectiveGoogleMode, getProviderRegistryEntry } from "../providers/registry";
+import { effectiveGoogleMode, getProviderRegistryEntry, providerMatchesRegistryTransport } from "../providers/registry";
+import { resolveProviderModelDiscoveryUrl } from "../providers/model-discovery";
 import { resolveProviderTransport } from "../providers/xai-transport";
 import { detectClaudeCodeToken, detectGrokCliToken, hasComparableGrokIdentity, isSameGrokIdentity, shouldAdoptGrokGeneration } from "./local-token-detect";
 import { logOAuthEvent } from "./log";
@@ -467,6 +468,22 @@ export async function resolveModelsAuthToken(name: string, prov: OcxProviderConf
   return resolveEnvValue(prov.apiKey);
 }
 
+function modelDiscoveryTransportSeed(providerName: string, prov: OcxProviderConfig): OcxProviderConfig {
+  const entry = getProviderRegistryEntry(providerName);
+  if (
+    prov.authMode !== "oauth"
+    || entry?.authKind !== "oauth"
+    || entry.allowBaseUrlOverride === true
+    || /\{[^}]*\}/.test(entry.baseUrl)
+    || !providerMatchesRegistryTransport(providerName, prov)
+  ) {
+    return prov;
+  }
+  // Normal routing pins fixed OAuth presets before adapter-specific transport resolution.
+  // Discovery must do the same so a stale or modified config baseUrl never receives a token.
+  return { ...prov, adapter: entry.adapter, baseUrl: entry.baseUrl };
+}
+
 /**
  * Provider-correct `GET /models` request (URL + headers), so both model-listing paths fetch the
  * LIVE catalog correctly per adapter. Anthropic is the special case: its endpoint is `/v1/models`
@@ -479,20 +496,27 @@ export async function resolveModelsAuthToken(name: string, prov: OcxProviderConf
  * response.
  */
 export function buildModelsRequest(prov: OcxProviderConfig, apiKey: string | undefined, providerName = ""): { url: string; headers: Record<string, string> } {
+  const transportSeed = modelDiscoveryTransportSeed(providerName, prov);
   const effectiveProvider = resolveProviderTransport(
     providerName,
-    prov,
+    transportSeed,
     undefined,
     providerName === "github-copilot" ? getOAuthCredentialApiBaseUrl(providerName) : undefined,
   );
   const headers: Record<string, string> = { ...(effectiveProvider.headers ?? {}) };
+  const discoveryUrl = (defaultUrl: string): string => resolveProviderModelDiscoveryUrl(
+    providerName,
+    prov,
+    effectiveProvider.baseUrl,
+    defaultUrl,
+  );
   if (effectiveGoogleMode(providerName, effectiveProvider) === "ai-studio") {
     // Generative Language API: API key goes in x-goog-api-key (never Authorization: Bearer),
     // models live under /v1beta (v1 misses preview models), and pageSize maxes at 1000 —
     // enough to list everything without a pageToken loop. Vertex/antigravity keep the
     // generic branch (they fall back to their static model lists).
     if (apiKey) headers["x-goog-api-key"] = apiKey;
-    return { url: `${effectiveProvider.baseUrl}/v1beta/models?pageSize=1000`, headers };
+    return { url: discoveryUrl(`${effectiveProvider.baseUrl}/v1beta/models?pageSize=1000`), headers };
   }
   if (effectiveProvider.adapter === "anthropic") {
     const base = effectiveProvider.baseUrl.replace(/\/v1\/?$/, "");
@@ -504,10 +528,10 @@ export function buildModelsRequest(prov: OcxProviderConfig, apiKey: string | und
       if (effectiveProvider.apiKeyTransport === "bearer") headers["Authorization"] = `Bearer ${apiKey}`;
       else headers["x-api-key"] = apiKey;
     }
-    return { url: `${base}/v1/models?limit=1000`, headers };
+    return { url: discoveryUrl(`${base}/v1/models?limit=1000`), headers };
   }
   if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
-  return { url: `${effectiveProvider.baseUrl}/models`, headers };
+  return { url: discoveryUrl(`${effectiveProvider.baseUrl}/models`), headers };
 }
 
 /**

package/src/oauth/key-providers.ts

@@ -1,5 +1,6 @@
 import type { OcxProviderConfig } from "../types";
 import { deriveKeyLoginMap, enrichProviderFromRegistry, type DerivedKeyLoginProvider } from "../providers/derive";
+import { resolveProviderModelDiscoveryUrl } from "../providers/model-discovery";
 
 /**
  * API-key "login" providers: not OAuth — the flow opens the provider's dashboard so the user can
@@ -45,7 +46,11 @@ function anthropicKeyValidationHeaders(provider: Pick<KeyLoginProvider, "apiKeyT
 }
 
 /** Best-effort key validation. Returns true/false/unknown; never persists the key itself. */
-export async function validateApiKey(provider: KeyLoginProvider, key: string): Promise<boolean | "unknown"> {
+export async function validateApiKey(
+  providerName: string,
+  provider: KeyLoginProvider,
+  key: string,
+): Promise<boolean | "unknown"> {
   try {
     if (provider.adapter === "anthropic") {
       const base = provider.baseUrl.replace(/\/v1\/?$/, "");
@@ -57,6 +62,7 @@ export async function validateApiKey(provider: KeyLoginProvider, key: string): P
           max_tokens: 1,
           messages: [{ role: "user", content: "ping" }],
         }),
+        redirect: "error",
         signal: AbortSignal.timeout(8000),
       });
       if (res.ok) return true;
@@ -69,6 +75,7 @@ export async function validateApiKey(provider: KeyLoginProvider, key: string): P
       // documented x-goog-api-key header instead (pageSize=1 — validation only needs a 200).
       const res = await fetch(`${provider.baseUrl}/v1beta/models?pageSize=1`, {
         headers: { "x-goog-api-key": key },
+        redirect: "error",
         signal: AbortSignal.timeout(8000),
       });
       if (res.ok) return true;
@@ -76,8 +83,20 @@ export async function validateApiKey(provider: KeyLoginProvider, key: string): P
       return "unknown";
     }
 
-    const res = await fetch(`${provider.baseUrl}/models`, {
+    const configuredProvider: OcxProviderConfig = {
+      adapter: provider.adapter,
+      baseUrl: provider.baseUrl,
+      authMode: "key",
+    };
+    const modelsUrl = resolveProviderModelDiscoveryUrl(
+      providerName,
+      configuredProvider,
+      provider.baseUrl,
+      `${provider.baseUrl}/models`,
+    );
+    const res = await fetch(modelsUrl, {
       headers: { Authorization: `Bearer ${key}` },
+      redirect: "error",
       signal: AbortSignal.timeout(8000),
     });
     if (res.ok) return true;

package/src/oauth/kiro-credentials.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { chmodSync, closeSync, existsSync, fsyncSync, linkSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, closeSync, existsSync, fsyncSync, linkSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { isAbsolute, join } from "node:path";
+import { isAbsolute, join, posix, win32 } from "node:path";
 import { Database } from "bun:sqlite";
 
 const DEFAULT_EXPIRES_MS = 3600_000;
@@ -39,7 +39,14 @@ export type KiroDiagnosticStatus =
   | "registration_found";
 
 export interface KiroImportDiagnostic {
-  location: "kiro-creds-file" | "kiro-cli-db-env" | "kiro-cli-data" | "kiro-cli-linux-data" | "amazon-q-data" | "kiro-sso-cache";
+  location:
+    | "kiro-creds-file"
+    | "kiro-cli-db-env"
+    | "kiro-cli-data"
+    | "kiro-cli-linux-data"
+    | "kiro-cli-windows-data"
+    | "amazon-q-data"
+    | "kiro-sso-cache";
   status: KiroDiagnosticStatus;
 }
 
@@ -122,14 +129,127 @@ function jsonCredentialPaths(): string[] {
     .map(expandPath);
 }
 
-function nativeKiroCliSessionEntries(): Array<{ location: "kiro-cli-data" | "kiro-cli-linux-data"; path: string }> {
-  const home = userHome();
+export type KiroCliNativeLocation = "kiro-cli-data" | "kiro-cli-linux-data" | "kiro-cli-windows-data";
+
+export interface KiroCliNativeInputs {
+  env: Record<string, string | undefined>;
+  platform: NodeJS.Platform;
+  home: string;
+}
+
+/**
+ * Native kiro-cli session stores, as a pure function of (env, platform, home).
+ *
+ * Pure + parameterized following `src/claude/desktop-3p-paths.ts`: `process.platform` is stubbable
+ * in this repo, but `os.platform()` does NOT follow it under Bun, so a pure resolver is the reliable
+ * way to exercise the win32 branch (and its env fallbacks) on a macOS/Linux host.
+ *
+ * Windows (issue #710): the official installer stores the auth DB at
+ * `%LOCALAPPDATA%\Kiro-Cli\data.sqlite3`. When LOCALAPPDATA is unset or blank, fall back to
+ * `%USERPROFILE%\AppData\Local`, then to the injected platform-native home. Deliberately NOT
+ * `userHome()`: that is `HOME || homedir()` and Windows shells (Git Bash / MSYS / CI) routinely
+ * export a POSIX-style `HOME`, which would point this at a non-native path.
+ *
+ * One entry per platform on purpose: this list also drives forced-login snapshot/rollback, so it
+ * must name the database the LOCAL kiro-cli actually mutates, never a foreign platform's path.
+ */
+export function resolveKiroCliNativeSessionEntries(
+  inputs: KiroCliNativeInputs,
+): Array<{ location: KiroCliNativeLocation; path: string }> {
+  const { env, platform, home } = inputs;
+  if (platform === "win32") {
+    const base = env.LOCALAPPDATA?.trim()
+      || (env.USERPROFILE?.trim() ? win32.join(env.USERPROFILE.trim(), "AppData", "Local") : "")
+      || win32.join(home, "AppData", "Local");
+    return [{ location: "kiro-cli-windows-data", path: win32.join(base, "Kiro-Cli", "data.sqlite3") }];
+  }
+  if (platform === "darwin") {
+    return [{ location: "kiro-cli-data", path: posix.join(home, "Library", "Application Support", "kiro-cli", "data.sqlite3") }];
+  }
+  return [{ location: "kiro-cli-linux-data", path: posix.join(home, ".local", "share", "kiro-cli", "data.sqlite3") }];
+}
+
+/**
+ * Resolve the absolute kiro-cli executable for spawn/login helpers.
+ *
+ * Pure + parameterized like `resolveKiroCliNativeSessionEntries` so Windows install layouts can be
+ * covered from any host. PATH remains the first choice; only when bare `kiro-cli` is missing do we
+ * fall back to the platform-native install directories next to the session database.
+ *
+ * Windows: official MSI installs to `C:\Program Files\Kiro-Cli\kiro-cli.exe`, while some local
+ * installs keep the binary next to `%LOCALAPPDATA%\Kiro-Cli\data.sqlite3`.
+ * macOS/Linux: prefer PATH, then the usual user-local bin directories.
+ */
+export function resolveKiroCliExecutable(
+  inputs: KiroCliNativeInputs & {
+    pathEntries?: string[];
+    exists?: (path: string) => boolean;
+    isFile?: (path: string) => boolean;
+  },
+): string {
+  const exists = inputs.exists ?? existsSync;
+  // A directory named `kiro-cli` on PATH satisfies existsSync and would then be handed to
+  // spawn(), which fails with EACCES at login instead of falling through to the next candidate.
+  // When a caller injects `exists` it owns the whole filesystem view, so the real stat would
+  // reject every synthetic path; such callers inject `isFile` too when they care about it.
+  const isFile = inputs.isFile ?? (inputs.exists ? () => true : ((path: string) => {
+    try {
+      return statSync(path).isFile();
+    } catch {
+      return false;
+    }
+  }));
+  const pathEntries = inputs.pathEntries
+    ?? (inputs.env.PATH ?? inputs.env.Path ?? "").split(inputs.platform === "win32" ? ";" : ":")
+      .map(entry => entry.trim())
+      .filter(Boolean);
+
+  const pathCandidates = inputs.platform === "win32"
+    ? pathEntries.flatMap(entry => [
+        win32.join(entry, "kiro-cli.exe"),
+        win32.join(entry, "kiro-cli"),
+      ])
+    : pathEntries.map(entry => posix.join(entry, "kiro-cli"));
+
+  const installCandidates: string[] = [];
+  if (inputs.platform === "win32") {
+    const localBase = inputs.env.LOCALAPPDATA?.trim()
+      || (inputs.env.USERPROFILE?.trim() ? win32.join(inputs.env.USERPROFILE.trim(), "AppData", "Local") : "")
+      || win32.join(inputs.home, "AppData", "Local");
+    const programFiles = inputs.env["ProgramFiles"]?.trim() || "C:\\Program Files";
+    installCandidates.push(
+      win32.join(localBase, "Kiro-Cli", "kiro-cli.exe"),
+      win32.join(programFiles, "Kiro-Cli", "kiro-cli.exe"),
+    );
+  } else if (inputs.platform === "darwin") {
+    installCandidates.push(
+      posix.join(inputs.home, ".local", "bin", "kiro-cli"),
+      "/usr/local/bin/kiro-cli",
+      "/opt/homebrew/bin/kiro-cli",
+    );
+  } else {
+    installCandidates.push(
+      posix.join(inputs.home, ".local", "bin", "kiro-cli"),
+      "/usr/local/bin/kiro-cli",
+    );
+  }
+
+  for (const candidate of [...pathCandidates, ...installCandidates]) {
+    if (exists(candidate) && isFile(candidate)) return candidate;
+  }
+  return inputs.platform === "win32" ? "kiro-cli.exe" : "kiro-cli";
+}
+
+function nativeKiroCliSessionEntries(): Array<{ location: KiroCliNativeLocation; path: string }> {
   // Only the stores that `kiro-cli logout` / `kiro-cli login` themselves mutate. Import fallbacks
   // (Amazon Q / SSO cache) and KIROCLI_DB_PATH selectors must not be snapshotted for rollback.
-  return [
-    { location: "kiro-cli-data", path: join(home, "Library", "Application Support", "kiro-cli", "data.sqlite3") },
-    { location: "kiro-cli-linux-data", path: join(home, ".local", "share", "kiro-cli", "data.sqlite3") },
-  ];
+  return resolveKiroCliNativeSessionEntries({
+    env: process.env,
+    platform: process.platform,
+    // POSIX keeps HOME-first userHome() so existing HOME-based fixtures still resolve; win32 prefers
+    // LOCALAPPDATA/USERPROFILE and only falls back to this platform-native home.
+    home: process.platform === "win32" ? homedir() : userHome(),
+  });
 }
 
 function sqliteEntries(): Array<{ location: KiroImportDiagnostic["location"]; path: string }> {

package/src/oauth/kiro.ts

@@ -18,6 +18,7 @@ import {
   persistKiroCliSessionRecovery,
   readImportedKiroCredential,
   readKiroCliSqliteCredential,
+  resolveKiroCliExecutable,
   restoreKiroCliSession,
   restoreStaleKiroCliSessionRecovery,
   requireKiroRegion,
@@ -25,6 +26,7 @@ import {
   type KiroCliSessionSnapshot,
   type KiroImportDiagnostic,
 } from "./kiro-credentials";
+import { homedir } from "node:os";
 import { getAccountSet, saveAccountCredential } from "./store";
 
 const DEFAULT_REGION = "us-east-1";
@@ -72,9 +74,18 @@ const pendingKiroLoginTransactions = new WeakMap<OAuthCredentials, KiroCliSessio
 /** Forced logins that started with no native CLI DB must logout on persistence failure. */
 const pendingKiroEmptyPriorSessions = new WeakSet<OAuthCredentials>();
 
+
+function resolveRuntimeKiroCliExecutable(): string {
+  return resolveKiroCliExecutable({
+    env: process.env,
+    platform: process.platform,
+    home: process.platform === "win32" ? homedir() : (process.env.HOME || homedir()),
+  });
+}
+
 function logoutKiroCliBestEffort(): void {
   try {
-    Bun.spawnSync(["kiro-cli", "logout"], {
+    Bun.spawnSync([resolveRuntimeKiroCliExecutable(), "logout"], {
       stdin: "ignore",
       stdout: "ignore",
       stderr: "ignore",
@@ -128,7 +139,7 @@ async function defaultKiroCliRunner(args: string[], signal?: AbortSignal): Promi
   throwIfKiroLoginCancelled(signal);
   let child: ReturnType<typeof Bun.spawn>;
   try {
-    child = Bun.spawn(["kiro-cli", ...args], {
+    child = Bun.spawn([resolveRuntimeKiroCliExecutable(), ...args], {
       stdin: "ignore",
       stdout: "pipe",
       stderr: "ignore",
@@ -289,7 +300,8 @@ export async function loginKiro(ctrl: OAuthController, options: KiroLoginOptions
         "Kiro CLI session could not be backed up, so OCX will not sign it out. " +
           "Repair or remove the unreadable kiro-cli credential database " +
           "(usually `~/.local/share/kiro-cli/data.sqlite3` or " +
-          "`~/Library/Application Support/kiro-cli/data.sqlite3`), " +
+          "`~/Library/Application Support/kiro-cli/data.sqlite3`, or " +
+          "`%LOCALAPPDATA%\\Kiro-Cli\\data.sqlite3` on Windows), " +
           "unset KIROCLI_DB_PATH / KIRO_CLI_DB_FILE if set for import-only overrides, then retry.",
       );
     }

package/src/oauth/login-cli.ts

@@ -135,7 +135,7 @@ async function handleKeyLogin(name: string): Promise<void> {
     process.exit(1);
   }
   process.stdout.write("   validating… ");
-  const valid = await validateApiKey({ ...def, baseUrl }, key);
+  const valid = await validateApiKey(name, { ...def, baseUrl }, key);
   console.log(valid === true ? "valid ✅" : valid === false ? "INVALID ❌" : "couldn't validate (may still work)");
   if (valid === false) {
     console.error("Provider rejected the key. Not saved.");