@bitkyc08/opencodex 2.7.43-preview.20260728 → 2.8.0

package/src/lib/pinned-http.ts

@@ -0,0 +1,151 @@
+import http, { type IncomingMessage, type RequestOptions } from "node:http";
+import https from "node:https";
+
+export type PinnedAddress = { address: string; family: number };
+
+export interface PinnedHttpGetOptions {
+  headers?: HeadersInit;
+  maxBytes?: number;
+  idleTimeoutMs?: number;
+  rejectUnauthorized?: boolean;
+  context?: string;
+}
+
+/**
+ * GET a URL through one previously validated address. The original hostname
+ * remains authoritative for Host, SNI, and certificate verification.
+ */
+export function pinnedHttpGet(
+  url: string,
+  pinned: PinnedAddress,
+  signal?: AbortSignal,
+  options?: PinnedHttpGetOptions,
+): Promise<Response> {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`${options?.context ?? "request"} must use HTTP or HTTPS, got ${parsed.protocol}`);
+  }
+  const context = options?.context ?? "request";
+  const idleTimeoutMs = options?.idleTimeoutMs ?? 60_000;
+  const maxBytes = options?.maxBytes;
+  const headers = new Headers(options?.headers);
+  headers.set("host", parsed.host);
+  const requestHeaders: Record<string, string> = {};
+  headers.forEach((value, key) => { requestHeaders[key] = value; });
+
+  return new Promise<Response>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
+      return;
+    }
+
+    let settled = false;
+    const fail = (error: unknown) => {
+      try { req.destroy(); } catch { /* ignore */ }
+      if (settled) return;
+      settled = true;
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+    const requestOptions: RequestOptions & { servername?: string } = {
+      protocol: parsed.protocol,
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === "https:" ? 443 : 80),
+      path: `${parsed.pathname}${parsed.search}`,
+      method: "GET",
+      headers: requestHeaders,
+      ...(parsed.protocol === "https:"
+        ? {
+          servername: parsed.hostname,
+          rejectUnauthorized: options?.rejectUnauthorized ?? true,
+        }
+        : {}),
+      lookup(_hostname, lookupOptions, callback) {
+        const opts = typeof lookupOptions === "function" ? undefined : lookupOptions;
+        const cb = typeof lookupOptions === "function" ? lookupOptions : callback;
+        if (!cb) return;
+        if (opts && typeof opts === "object" && "all" in opts && opts.all) {
+          (cb as (error: NodeJS.ErrnoException | null, addresses: PinnedAddress[]) => void)(
+            null,
+            [{ address: pinned.address, family: pinned.family }],
+          );
+          return;
+        }
+        (cb as (error: NodeJS.ErrnoException | null, address: string, family: 4 | 6) => void)(
+          null,
+          pinned.address,
+          pinned.family as 4 | 6,
+        );
+      },
+    };
+
+    const onResponse = (response: IncomingMessage) => {
+      const status = response.statusCode ?? 0;
+      const responseHeaders = new Headers();
+      for (const [key, value] of Object.entries(response.headers)) {
+        if (value === undefined || value === null) continue;
+        if (Array.isArray(value)) {
+          for (const item of value) responseHeaders.append(key, String(item));
+        } else {
+          responseHeaders.set(key, String(value));
+        }
+      }
+
+      if (status < 200 || status >= 300) {
+        try { response.destroy(); } catch { /* ignore */ }
+        try { req.destroy(); } catch { /* ignore */ }
+        if (settled) return;
+        settled = true;
+        resolve(new Response(null, { status, headers: responseHeaders }));
+        return;
+      }
+
+      let received = 0;
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          response.setTimeout(idleTimeoutMs, () => {
+            const error = new Error(`${context} stalled`);
+            fail(error);
+            try { controller.error(error); } catch { /* closed */ }
+          });
+          response.on("data", (chunk: Buffer | string) => {
+            const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            received += buffer.byteLength;
+            if (maxBytes !== undefined && received > maxBytes) {
+              const error = new Error(`${context} exceeds ${maxBytes} byte cap`);
+              fail(error);
+              try { controller.error(error); } catch { /* closed */ }
+              return;
+            }
+            try { controller.enqueue(buffer); } catch { /* closed */ }
+          });
+          response.on("end", () => {
+            try { controller.close(); } catch { /* closed */ }
+          });
+          response.on("error", (error: Error) => {
+            fail(error);
+            try { controller.error(error); } catch { /* closed */ }
+          });
+        },
+        cancel() {
+          req.destroy();
+        },
+      });
+
+      if (settled) return;
+      settled = true;
+      resolve(new Response(stream, { status, headers: responseHeaders }));
+    };
+
+    const requestFn = parsed.protocol === "https:" ? https.request : http.request;
+    const req = requestFn(requestOptions, onResponse);
+    const onAbort = () => fail(signal?.reason instanceof Error ? signal.reason : new Error("aborted"));
+    signal?.addEventListener("abort", onAbort, { once: true });
+    req.setTimeout(idleTimeoutMs, () => fail(new Error(`${context} timed out`)));
+    req.on("error", error => {
+      signal?.removeEventListener("abort", onAbort);
+      fail(error);
+    });
+    req.on("close", () => signal?.removeEventListener("abort", onAbort));
+    req.end();
+  });
+}

package/src/lib/process-control.ts

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { loadConfig, readRuntimePort } from "../config";
+import { configuredAdminToken } from "./admin-secrets";
 
 export function isProcessAlive(pid: number): boolean {
   try {
@@ -66,8 +67,7 @@ export async function stopProxyGracefully(pid: number, io: GracefulStopIo = {}):
   if (!runtime?.port) return false;
   const env = io.env ?? process.env;
   const headers: Record<string, string> = {};
-  // Non-loopback binds require management auth; loopback ignores the extra header.
-  const token = env.OPENCODEX_API_AUTH_TOKEN?.trim();
+  const token = configuredAdminToken(env.OPENCODEX_HOME?.trim() || undefined, env as NodeJS.ProcessEnv);
   if (token) headers["x-opencodex-api-key"] = token;
   const fetchFn = io.fetchFn ?? fetch;
   try {

package/src/lib/provider-outbound.ts

@@ -0,0 +1,167 @@
+import type { OcxProviderConfig } from "../types";
+import {
+  assessUrlDestination,
+  DestinationDnsResolutionError,
+  providerAllowsPrivateNetwork,
+  providerDestinationConfigError,
+  resolvePublicAddresses,
+} from "./destination-policy";
+import { pinnedHttpGet } from "./pinned-http";
+import { outboundProxyConfigured } from "./proxy-env";
+import { publicProviderBaseUrl } from "./provider-url";
+
+type ProviderGetInit = Omit<RequestInit, "body" | "method" | "redirect">;
+type ProviderOutboundConfig = Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork"> & {
+  fetch?: typeof globalThis.fetch;
+};
+export interface ProviderOutboundDependencies {
+  resolveAddresses?: typeof resolvePublicAddresses;
+  pinnedGet?: typeof pinnedHttpGet;
+}
+
+export class ProviderOutboundPolicyError extends Error {
+  override readonly name = "ProviderOutboundPolicyError";
+}
+
+function pickPinnedAddress(addresses: Array<{ address: string; family: number }>): { address: string; family: number } {
+  return addresses.find(address => address.family === 4) ?? addresses[0]!;
+}
+
+function configuredProxyFor(): boolean {
+  return outboundProxyConfigured();
+}
+
+function normalizeProxyHostname(hostname: string): string {
+  const normalized = hostname.trim().toLowerCase().replace(/\.+$/, "");
+  return normalized.startsWith("[") && normalized.endsWith("]")
+    ? normalized.slice(1, -1)
+    : normalized;
+}
+
+function noProxyMatches(url: URL): boolean {
+  const raw = process.env.NO_PROXY ?? process.env.no_proxy ?? "";
+  const hostname = normalizeProxyHostname(url.hostname);
+  const port = url.port || (url.protocol === "https:" ? "443" : "80");
+  for (const rawEntry of raw.split(",")) {
+    let entry = rawEntry.trim().toLowerCase();
+    if (!entry) continue;
+    if (entry === "*") return true;
+    entry = entry.replace(/^https?:\/\//, "").split("/", 1)[0]!;
+
+    let entryHost = entry;
+    let entryPort = "";
+    const bracketed = /^\[([^\]]+)](?::(\d+))?$/.exec(entry);
+    if (bracketed) {
+      entryHost = bracketed[1]!;
+      entryPort = bracketed[2] ?? "";
+    } else if ((entry.match(/:/g)?.length ?? 0) === 1) {
+      const separator = entry.lastIndexOf(":");
+      const possiblePort = entry.slice(separator + 1);
+      if (/^\d+$/.test(possiblePort)) {
+        entryHost = entry.slice(0, separator);
+        entryPort = possiblePort;
+      }
+    }
+    if (entryPort && entryPort !== port) continue;
+    entryHost = normalizeProxyHostname(entryHost.replace(/^\*?\./, ""));
+    if (!entryHost) continue;
+    if (hostname === entryHost || hostname.endsWith(`.${entryHost}`)) return true;
+  }
+  return false;
+}
+
+let proxyBoundaryWarned = false;
+let proxyDnsDegradationWarned = false;
+
+function warnProxyBoundaryOnce(): void {
+  if (proxyBoundaryWarned) return;
+  proxyBoundaryWarned = true;
+  console.warn(
+    "[opencodex] Provider outbound proxy mode preserves Bun proxy/NO_PROXY routing and validates "
+    + "the URL plus available local DNS results; the final route and peer cannot be pinned locally.",
+  );
+}
+
+function warnProxyDnsDegradationOnce(): void {
+  if (proxyDnsDegradationWarned) return;
+  proxyDnsDegradationWarned = true;
+  console.warn(
+    "[opencodex] Local DNS could not resolve a proxied provider hostname; continuing after URL/literal checks. "
+    + "The proxy-selected peer cannot be verified or pinned locally.",
+  );
+}
+
+export async function providerRedirectError(response: Response, requestUrl: string): Promise<string | null> {
+  if (response.status < 300 || response.status >= 400) return null;
+  try { await response.body?.cancel(); } catch { /* ignore cancellation failures */ }
+  const location = response.headers.get("location");
+  let target = "the final upstream URL";
+  if (location) {
+    try { target = publicProviderBaseUrl(new URL(location, requestUrl).toString()); } catch { /* keep fallback */ }
+  }
+  return `provider returned ${response.status} redirect to ${target}; configure the final provider URL directly`;
+}
+
+export async function providerOutboundGet(
+  name: string,
+  provider: ProviderOutboundConfig,
+  url: string,
+  init: ProviderGetInit = {},
+  dependencies: ProviderOutboundDependencies = {},
+): Promise<Response> {
+  if (provider.fetch) {
+    // A caller-owned executor cannot be peer-pinned here. This branch keeps literal/config
+    // checks and redirect blocking, but does not provide the resolved-address guarantees of
+    // the built-in transport. Main-request migration must define that executor contract first.
+    const assessment = assessUrlDestination(url);
+    if (assessment?.kind === "metadata" || assessment?.kind === "link-local" || assessment?.kind === "unspecified") {
+      throw new ProviderOutboundPolicyError(`provider URL targets ${assessment.detail}`);
+    }
+    const allowPrivate = providerAllowsPrivateNetwork(name, provider);
+    if (!allowPrivate) {
+      const destinationError = providerDestinationConfigError(name, {
+        baseUrl: url,
+        allowPrivateNetwork: false,
+      });
+      if (destinationError) throw new ProviderOutboundPolicyError(destinationError);
+    }
+    return provider.fetch(url, { ...init, method: "GET", redirect: "manual" });
+  }
+  const parsed = new URL(url);
+  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: allowPrivate,
+    });
+  } catch (error) {
+    const dnsResolutionFailed = error instanceof DestinationDnsResolutionError
+      || (error instanceof Error && error.name === "DestinationDnsResolutionError");
+    if (!dnsResolutionFailed) {
+      throw new ProviderOutboundPolicyError(error instanceof Error ? error.message : "provider destination was blocked");
+    }
+    if (!proxyConfigured) throw error;
+    warnProxyBoundaryOnce();
+    warnProxyDnsDegradationOnce();
+    return globalThis.fetch(url, { ...init, method: "GET", redirect: "manual" });
+  }
+  if (proxyConfigured && !resolved.privateNetwork) {
+    warnProxyBoundaryOnce();
+    return globalThis.fetch(url, { ...init, method: "GET", redirect: "manual" });
+  }
+  if (proxyConfigured && resolved.privateNetwork && !noProxyMatches(parsed)) {
+    const hostname = normalizeProxyHostname(parsed.hostname);
+    throw new Error(
+      `provider URL resolves to a private-network destination; add ${hostname} to NO_PROXY before using allowPrivateNetwork with an outbound proxy`,
+    );
+  }
+  return pinnedGet(url, pickPinnedAddress(resolved.addresses), init.signal ?? undefined, {
+    headers: init.headers,
+    rejectUnauthorized: true,
+    context: "provider response",
+  });
+}

package/src/lib/provider-url.ts

@@ -0,0 +1,14 @@
+/** Strip credentials and non-routing URL components before displaying a provider URL. */
+export function publicProviderBaseUrl(baseUrl: string): string {
+  try {
+    const parsed = new URL(baseUrl.trim());
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return "(invalid URL)";
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString().replace(/\/$/, baseUrl.endsWith("/") ? "/" : "");
+  } catch {
+    return "(invalid URL)";
+  }
+}

package/src/lib/proxy-env.ts

@@ -0,0 +1,18 @@
+export const OUTBOUND_PROXY_ENV_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY"] as const;
+export const PROXY_ENV_KEYS = [...OUTBOUND_PROXY_ENV_KEYS, "NO_PROXY"] as const;
+
+export type ProxyEnvKey = typeof PROXY_ENV_KEYS[number];
+export type ProxyEnvMap = Record<string, string | undefined>;
+
+export function proxyEnvPresent(
+  key: ProxyEnvKey,
+  env: ProxyEnvMap = process.env,
+): boolean {
+  return Boolean(env[key]?.trim() || env[key.toLowerCase()]?.trim());
+}
+
+export function outboundProxyConfigured(
+  env: ProxyEnvMap = process.env,
+): boolean {
+  return OUTBOUND_PROXY_ENV_KEYS.some(key => proxyEnvPresent(key, env));
+}

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/windows-elevation.ts

@@ -18,9 +18,13 @@ export function setWindowsElevationSpawnForTests(next: ElevationSpawn | null): v
 
 type GetSystemDirectoryW = (buffer: Pointer, size: number) => number;
 type TrustedSystemDirectoryResolver = () => string;
+type IsUserAnAdmin = () => number;
+type WindowsElevationProbe = () => boolean | null;
 
 let getSystemDirectoryWFn: GetSystemDirectoryW | null | undefined;
 let trustedSystemDirectoryResolverForTests: TrustedSystemDirectoryResolver | null = null;
+let isUserAnAdminFn: (() => boolean) | null | undefined;
+let windowsElevationProbeForTests: WindowsElevationProbe | null = null;
 
 /** Test-only seam to replace GetSystemDirectoryW-backed resolution. */
 export function setTrustedWindowsSystemDirectoryResolverForTests(
@@ -29,6 +33,49 @@ export function setTrustedWindowsSystemDirectoryResolverForTests(
   trustedSystemDirectoryResolverForTests = next;
 }
 
+/** Test-only seam for the locale-independent current-token elevation probe. */
+export function setWindowsElevationProbeForTests(next: WindowsElevationProbe | null): void {
+  windowsElevationProbeForTests = next;
+}
+
+function loadIsUserAnAdmin(): (() => boolean) | null {
+  if (isUserAnAdminFn !== undefined) return isUserAnAdminFn;
+  if (process.platform !== "win32") {
+    isUserAnAdminFn = null;
+    return null;
+  }
+  try {
+    const lib = dlopen("shell32.dll", {
+      IsUserAnAdmin: {
+        args: [],
+        // Win32 BOOL is a signed 32-bit integer, not C/C++ bool.
+        returns: "i32",
+      },
+    });
+    const isUserAnAdmin = lib.symbols.IsUserAnAdmin as IsUserAnAdmin;
+    isUserAnAdminFn = () => isUserAnAdmin() !== 0;
+  } catch {
+    isUserAnAdminFn = null;
+  }
+  return isUserAnAdminFn;
+}
+
+/**
+ * Probe the effective Windows token without parsing localized command output.
+ * `null` fails closed: callers must retain the original scheduler error rather
+ * than infer that an unknown token state needs elevation.
+ */
+export function isCurrentWindowsProcessElevated(): boolean | null {
+  if (windowsElevationProbeForTests) return windowsElevationProbeForTests();
+  const isUserAnAdmin = loadIsUserAnAdmin();
+  if (!isUserAnAdmin) return null;
+  try {
+    return isUserAnAdmin();
+  } catch {
+    return null;
+  }
+}
+
 function loadGetSystemDirectoryW(): GetSystemDirectoryW | null {
   if (getSystemDirectoryWFn !== undefined) return getSystemDirectoryWFn;
   if (process.platform !== "win32") {
@@ -252,6 +299,34 @@ export function schtasksOperationFromArgs(args: string[]): WindowsSchtasksOperat
   return "other";
 }
 
+function schedulerExitStatus(error: unknown): number | null {
+  if (!error || typeof error !== "object") return null;
+  const status = (error as { status?: unknown }).status;
+  return typeof status === "number" && Number.isInteger(status) ? status : null;
+}
+
+/**
+ * The owned scheduler install has a fixed shape. Restrict the locale-independent
+ * fallback to that shape so unrelated schtasks failures cannot request elevation.
+ */
+function isOwnedSchedulerCreate(args: string[]): boolean {
+  const normalized = args.map(arg => arg.toLowerCase());
+  const taskIndex = normalized.indexOf("/tn");
+  const xmlIndex = normalized.indexOf("/xml");
+  return normalized[0] === "/create"
+    && normalized[taskIndex + 1] === "opencodex-proxy"
+    && taskIndex > 0
+    && xmlIndex > 0
+    && Boolean(args[xmlIndex + 1])
+    && normalized.includes("/f");
+}
+
+function isWindowsSchtasksAccessDeniedError(error: unknown, args: string[]): boolean {
+  if (!isOwnedSchedulerCreate(args)) return false;
+  return isWindowsAccessDeniedError(error)
+    || (schedulerExitStatus(error) === 1 && isCurrentWindowsProcessElevated() === false);
+}
+
 /** Structured Task Scheduler failure that survives formatting and process boundaries. */
 export class WindowsSchtasksError extends Error {
   readonly code = "WINDOWS_SCHTASKS_ERROR" as const;
@@ -287,7 +362,8 @@ export class WindowsElevationError extends Error {
 /** Replace raw schtasks access-denied output with dashboard-friendly guidance. */
 export function formatWindowsSchtasksError(error: unknown, args: string[]): string {
   const operation = schtasksOperationFromArgs(args);
-  const accessDenied = isWindowsAccessDeniedError(error);
+  const ownedCreateAccessDenied = isWindowsSchtasksAccessDeniedError(error, args);
+  const accessDenied = ownedCreateAccessDenied || isWindowsAccessDeniedError(error);
   if (!accessDenied) {
     return error instanceof Error ? error.message : String(error);
   }
@@ -297,7 +373,7 @@ export function formatWindowsSchtasksError(error: unknown, args: string[]): stri
     `Command: schtasks ${argsText}`,
     "Approve the Windows UAC prompt to install the background service, or run `ocx service install` from an elevated PowerShell window.",
   ].join(" ");
-  if (operation === "create") {
+  if (operation === "create" && ownedCreateAccessDenied) {
     return `${guidance}\n${WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER}`;
   }
   return guidance;
@@ -306,7 +382,9 @@ export function formatWindowsSchtasksError(error: unknown, args: string[]): stri
 export function toWindowsSchtasksError(error: unknown, args: string[]): WindowsSchtasksError {
   if (error instanceof WindowsSchtasksError) return error;
   const operation = schtasksOperationFromArgs(args);
-  const reason: WindowsSchtasksFailureReason = isWindowsAccessDeniedError(error) ? "access-denied" : "other";
+  const reason: WindowsSchtasksFailureReason = isWindowsSchtasksAccessDeniedError(error, args)
+    ? "access-denied"
+    : "other";
   return new WindowsSchtasksError(operation, reason, formatWindowsSchtasksError(error, args));
 }