@bitkyc08/opencodex 2.60.0 → 2.61.0-preview.20260922

package/src/lib/debug.ts

@@ -52,3 +52,43 @@ export function debugProviderDiagnosticLazy(
     /* diagnostics must never affect request handling */
   }
 }
+
+/**
+ * One line per finalized attempt, formatted from what the recorder already counted.
+ *
+ * #3983 wanted this visibility and emitted a line per stream event to get it. Two things made
+ * that the wrong shape. It is a second record: `emitDebugLine` writes the ring AND stderr, and
+ * a service manager redirects stderr to a file, so an installed service accumulates a per-event
+ * history beside the ledger with its own retention and sequencing. And per-event lines needed a
+ * per-payload fingerprint to correlate, which under a process-global key makes every repeated
+ * prompt fragment and tool name correlatable for the life of the process.
+ *
+ * So this writes the ring ONLY -- `appendDebugLogLine` directly, never `emitDebugLine` -- and
+ * says nothing the ledger does not already hold. The ring becomes a live view of the durable
+ * record rather than a parallel source for it.
+ */
+export function debugAttemptDeliverySummary(
+  requestId: string,
+  attempt: {
+    ordinal: number;
+    adapter: string;
+    deliverySummary?: {
+      adapterEvents: number;
+      relayedEvents: number;
+      semanticBytes: number;
+      sideEffectEvents: number;
+      terminalEvents: number;
+    };
+  },
+): void {
+  if (!isDebugEnabled() || !attempt.deliverySummary) return;
+  try {
+    appendDebugLogLine(`[ocx:${attempt.adapter}:delivery] ${JSON.stringify({
+      requestId,
+      ordinal: attempt.ordinal,
+      ...attempt.deliverySummary,
+    })}`);
+  } catch {
+    /* diagnostics must never affect request handling */
+  }
+}

package/src/lib/open-url.ts

@@ -8,8 +8,33 @@ function windowsRundll32(): string {
   return existsSync(candidate) ? candidate : "rundll32";
 }
 
-export function openUrl(url: string): void {
-  if (!/^https?:\/\//i.test(url)) return;
+/**
+ * Whether the OS launcher actually started. `started` does not prove a browser rendered the
+ * page — nothing observable from here can — but it does separate "we handed the URL off" from
+ * "there was nothing to hand it to", which is the distinction a caller needs (#5261).
+ */
+export type OpenUrlResult =
+  | { status: "started" }
+  | { status: "failed"; reason: "invalid-url" | "spawn-error" | "launcher-exit" };
+
+/**
+ * How long to watch a launcher that did spawn before calling it started.
+ *
+ * `spawn` only proves a process began. `xdg-open` with no desktop handler, and rundll32 given a
+ * broken association, both spawn happily and exit nonzero a moment later without opening
+ * anything — so resolving on `spawn` alone would report a launch that did not happen. Those
+ * failures are immediate, and the only caller that awaits this is a login start, so a short
+ * window buys a true answer cheaply. A launcher still running when it elapses has started.
+ */
+const LAUNCHER_SETTLE_MS = 400;
+
+/**
+ * Never rejects. A browser that would not open is an inconvenience, not a login failure: the
+ * URL is still a valid thing to open by hand, so the caller decides what to say about it.
+ * Callers that genuinely do not care use `void openUrl(...)`.
+ */
+export function openUrl(url: string): Promise<OpenUrlResult> {
+  if (!/^https?:\/\//i.test(url)) return Promise.resolve({ status: "failed", reason: "invalid-url" });
   const cmd =
     process.platform === "darwin" ? "open"
     : process.platform === "win32" ? windowsRundll32()
@@ -17,9 +42,28 @@ export function openUrl(url: string): void {
   const args = process.platform === "win32"
     ? ["url.dll,FileProtocolHandler", url]
     : [url];
-  const child = spawn(cmd, args, { detached: true, stdio: "ignore", shell: false });
-  // Headless hosts (no xdg-open) emit ENOENT as an async 'error' event; without a
-  // listener that is an uncaught exception that kills the whole proxy/login flow.
-  child.on("error", () => {});
-  child.unref();
+  return new Promise<OpenUrlResult>(resolve => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const settle = (result: OpenUrlResult) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(result);
+    };
+    const child = spawn(cmd, args, { detached: true, stdio: "ignore", shell: false });
+    // Headless hosts (no xdg-open) emit ENOENT as an async 'error' event; without a
+    // listener that is an uncaught exception that kills the whole proxy/login flow.
+    // It is also the signal itself: on Windows this is how a missing rundll32 arrives.
+    child.on("error", () => settle({ status: "failed", reason: "spawn-error" }));
+    child.on("spawn", () => {
+      // Unref'd either way: this never keeps the process alive, it only decides what to report.
+      timer = setTimeout(() => settle({ status: "started" }), LAUNCHER_SETTLE_MS);
+      timer.unref?.();
+    });
+    child.on("exit", code => settle(code === 0 || code === null
+      ? { status: "started" }
+      : { status: "failed", reason: "launcher-exit" }));
+    child.unref();
+  });
 }

package/src/lib/package-tree-integrity.ts

@@ -1,4 +1,5 @@
 import { statSync } from "node:fs";
+import { isStandaloneBinary } from "./standalone";
 
 export interface PackageTreeObservation {
   readonly device: bigint;
@@ -96,6 +97,6 @@ export function createRuntimePackageTreeIntegrityGuard(
   observe: ObservePackageTree = observePackageManifest,
   now: () => number = Date.now,
 ): PackageTreeIntegrityGuard {
-  if (installer === "source") return { status: () => ({ ok: true }) };
+  if (installer === "source" || isStandaloneBinary()) return { status: () => ({ ok: true }) };
   return createPackageTreeIntegrityGuard(observe, now);
 }

package/src/lib/package-version.ts

@@ -0,0 +1,8 @@
+import pkg from "../../package.json" with { type: "json" };
+
+type PackageManifest = { version?: unknown };
+
+export function packageVersion(fallback = "unknown"): string {
+  const version = (pkg as PackageManifest).version;
+  return typeof version === "string" ? version : fallback;
+}

package/src/lib/provider-egress.ts

@@ -0,0 +1,310 @@
+/**
+ * Per-provider egress: which transport a request for THIS provider actually leaves by.
+ *
+ * The global `proxy`/`noProxy` pair is process-wide (mirrored into HTTP_PROXY/HTTPS_PROXY/
+ * ALL_PROXY/NO_PROXY by `applyProxyEnv`), so it cannot express the split #2894 describes:
+ * one upstream must exit through a regional proxy, another must stay direct on the local
+ * network. This module is the single authority that answers that question for one request,
+ * and every transport owner that can carry the answer consumes it rather than re-deriving it.
+ *
+ * It deliberately mirrors the shape #5087 established for the global decision in
+ * `effectiveProxyFor`: the question is never "is a proxy configured" but "does a proxy apply
+ * to THIS request". A provider route is resolved against the request URL, so a per-provider
+ * bypass list is part of the decision rather than a second check somewhere downstream.
+ *
+ * The three states are exactly the ones the issue asks for, with one deliberate divergence:
+ *
+ * - field absent          -> `inherit`: the global decision stands, byte-identical to today;
+ * - `null` or `"direct"` -> `direct`: this provider never uses the global proxy;
+ * - an http(s) URL        -> `proxy`: this provider uses its own HTTP(S) proxy;
+ * - a socks5(h) URL       -> `proxy`: this provider uses its own SOCKS5 proxy.
+ *
+ * The divergence is the empty string. #2894 sketches `""` as a third spelling of DIRECT.
+ * Treating it that way would make a dashboard field the operator merely cleared silently
+ * change a provider from "inherit the global proxy" to "never use the global proxy" — the
+ * quiet reinterpretation this batch exists to remove. An empty or whitespace-only value is
+ * therefore a configuration error naming both real alternatives.
+ */
+import type { OcxProviderConfig } from "../types";
+import { isSocks5ProxyUrl, noProxyMatches } from "./proxy-env";
+
+export class InvalidProviderEgressError extends Error {
+  override readonly name = "InvalidProviderEgressError";
+  constructor(
+    /** The provider field that carries the offending value. */
+    readonly field: "proxy" | "noProxy",
+    /** The failure on its own, so configuration surfaces can phrase it their own way. */
+    readonly reason: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** The literal an operator writes to pin one provider to direct egress. */
+export const PROVIDER_EGRESS_DIRECT = "direct";
+
+export type ProviderEgress =
+  | { kind: "inherit" }
+  | { kind: "direct"; reason: "configured" | "noProxy" }
+  | { kind: "proxy"; proxyUrl: string; transport: "http" | "socks5" };
+
+export interface ProviderEgressContext {
+  providerName: string;
+  provider: Pick<OcxProviderConfig, "proxy" | "noProxy">;
+  url: string | URL;
+}
+
+function egressFailure(providerName: string, field: "proxy" | "noProxy", reason: string): never {
+  throw new InvalidProviderEgressError(field, reason, `providers.${providerName}.${field} is invalid: ${reason}`);
+}
+
+/**
+ * A proxy URL reduced to scheme, host and port for operator-facing output.
+ *
+ * A proxy URL routinely carries `user:password@`, and this value reaches startup banners,
+ * diagnostics and the dashboard DTO. `URL.origin` drops userinfo, query and path, so what is
+ * left identifies the route without reproducing the credential. Nothing derived from the
+ * credential is emitted either — not a hash, not a prefix — because a short digest over a
+ * known host is a guessable stand-in for the secret and a durable correlation key for the
+ * account behind it.
+ */
+export function sanitizeProxyUrlForLog(proxyUrl: string): string {
+  try {
+    const parsed = new URL(proxyUrl);
+    return parsed.port ? `${parsed.protocol}//${parsed.hostname}:${parsed.port}` : parsed.origin;
+  } catch {
+    return "<unparseable-proxy-url>";
+  }
+}
+
+export function describeProviderEgressForLog(egress: ProviderEgress): string {
+  if (egress.kind === "inherit") return "inherit";
+  if (egress.kind === "direct") return `direct(${egress.reason})`;
+  return `${egress.transport}(${sanitizeProxyUrlForLog(egress.proxyUrl)})`;
+}
+
+function parseTargetUrl(providerName: string, url: string | URL): URL {
+  if (url instanceof URL) return url;
+  try {
+    return new URL(url);
+  } catch {
+    return egressFailure(providerName, "proxy", "the request URL is not parseable, so no provider route can be decided for it");
+  }
+}
+
+function normalizeNoProxy(providerName: string, raw: string | string[] | undefined): string | null {
+  if (raw === undefined) return null;
+  const entries = Array.isArray(raw) ? raw : [raw];
+  for (const entry of entries) {
+    if (typeof entry !== "string") {
+      return egressFailure(providerName, "noProxy", "every entry must be a string host pattern");
+    }
+  }
+  const joined = entries.join(",").trim();
+  return joined.length > 0 ? joined : null;
+}
+
+function parseProviderProxyRoute(providerName: string, raw: string): ProviderEgress {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return egressFailure(
+      providerName,
+      "proxy",
+      `an empty value is ambiguous; write "${PROVIDER_EGRESS_DIRECT}" to force direct egress, or remove the field to inherit the global proxy`,
+    );
+  }
+  if (trimmed.toLowerCase() === PROVIDER_EGRESS_DIRECT) return { kind: "direct", reason: "configured" };
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return egressFailure(
+      providerName,
+      "proxy",
+      `"${PROVIDER_EGRESS_DIRECT}" or an absolute proxy URL is required; this value is neither`,
+    );
+  }
+  if (isSocks5ProxyUrl(trimmed)) {
+    if (!parsed.hostname) {
+      return egressFailure(providerName, "proxy", "the SOCKS5 proxy URL has no host");
+    }
+    return { kind: "proxy", proxyUrl: trimmed, transport: "socks5" };
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return egressFailure(
+      providerName,
+      "proxy",
+      `unsupported proxy scheme "${parsed.protocol}"; supported schemes are http, https, socks5 and socks5h`,
+    );
+  }
+  if (!parsed.hostname) {
+    return egressFailure(providerName, "proxy", "the proxy URL has no host");
+  }
+  return { kind: "proxy", proxyUrl: parsed.toString(), transport: "http" };
+}
+
+/**
+ * The route this provider's request leaves by, or `inherit` when the global decision stands.
+ *
+ * Throws `InvalidProviderEgressError` rather than degrading to `inherit`: a malformed egress
+ * field is the one case where guessing is worst. Falling back to the global proxy would send a
+ * credential through a route the operator did not choose, and falling back to direct would
+ * leave a restricted network with no exit. Both read as success at the call site.
+ *
+ * A per-provider `noProxy` match outranks the provider's own proxy for the same reason it
+ * outranks the global one: it names destinations this provider must reach without a proxy.
+ * It is evaluated against the resolved route, so it also carves holes in an inherited global
+ * proxy — which is how a provider exempts one host without owning a proxy of its own.
+ */
+export function resolveProviderEgress(context: ProviderEgressContext): ProviderEgress {
+  const { providerName, provider } = context;
+  const raw = provider.proxy;
+  let route: ProviderEgress;
+  if (raw === undefined) {
+    route = { kind: "inherit" };
+  } else if (raw === null) {
+    route = { kind: "direct", reason: "configured" };
+  } else if (typeof raw !== "string") {
+    return egressFailure(providerName, "proxy", "the value must be a proxy URL string, \"direct\", null, or absent");
+  } else {
+    route = parseProviderProxyRoute(providerName, raw);
+  }
+  const noProxy = normalizeNoProxy(providerName, provider.noProxy);
+  if (noProxy !== null) {
+    const target = parseTargetUrl(providerName, context.url);
+    if (noProxyMatches(target, { NO_PROXY: noProxy })) return { kind: "direct", reason: "noProxy" };
+  }
+  return route;
+}
+
+/**
+ * Whether this provider decided the route itself, as opposed to deferring to the global one.
+ *
+ * Transport owners use this to tell "the operator chose this" from "nothing was configured",
+ * which are the two cases that must not be collapsed when a transport cannot carry the choice.
+ */
+export function providerEgressIsExplicit(egress: ProviderEgress): boolean {
+  return egress.kind !== "inherit";
+}
+
+/**
+ * The request-scoped fetch options that express `egress` to Bun's fetch.
+ *
+ * `proxy: false` is Bun's documented per-request direct connection: it ignores HTTP_PROXY,
+ * HTTPS_PROXY and ALL_PROXY, and it ignores NO_PROXY as well, which is what makes it a
+ * decision rather than a hint. `undefined`, `null` and `""` all mean "no option given" to
+ * Bun and fall through to the environment, so none of them can express direct egress — the
+ * reason this returns the literal `false` and never an empty string.
+ *
+ * A SOCKS5 route is returned as the same `proxy` string; `configuredOutboundFetch` recognises
+ * the scheme and hands the request to the SOCKS transport, because Bun's own fetch ignores a
+ * socks5 value.
+ */
+export function providerEgressFetchInit(egress: ProviderEgress): { proxy?: string | false } {
+  if (egress.kind === "inherit") return {};
+  if (egress.kind === "direct") return { proxy: false };
+  return { proxy: egress.proxyUrl };
+}
+
+/**
+ * Marker for an executor that forwards its `RequestInit` to a transport which honours the
+ * request-scoped proxy option.
+ *
+ * A provider route is refused on an executor that owns its own transport, because applying it
+ * is impossible and ignoring it is worse. But not every `provider.fetch` owns a transport:
+ * some are internal wrappers that add a header and delegate, and `src/providers/xai-transport.ts`
+ * installs exactly such a wrapper on every xAI route. Refusing those would make the per-provider
+ * proxy unusable on one of the two providers the original issue names.
+ *
+ * The marker is opt-in and applied by the wrapper's author, so an executor that arrives from
+ * configuration or from a caller is opaque by default and still refused. `Symbol.for` keeps the
+ * mark readable across duplicated module instances.
+ */
+const EGRESS_TRANSPARENT_EXECUTOR = Symbol.for("opencodex.provider-egress.transparent-executor");
+
+export function markEgressTransparentExecutor<Fetch extends typeof globalThis.fetch>(executor: Fetch): Fetch {
+  (executor as unknown as Record<symbol, boolean>)[EGRESS_TRANSPARENT_EXECUTOR] = true;
+  return executor;
+}
+
+export function isEgressTransparentExecutor(executor: unknown): boolean {
+  return typeof executor === "function"
+    && (executor as unknown as Record<symbol, unknown>)[EGRESS_TRANSPARENT_EXECUTOR] === true;
+}
+
+/** The destination of a fetch input, or null when it cannot be read as a URL. */
+export function egressTargetUrl(input: string | URL | Request): string | null {
+  if (typeof input === "string") return input;
+  if (input instanceof URL) return input.toString();
+  return typeof input?.url === "string" ? input.url : null;
+}
+
+/** Everything a physical send needs to decide the route for the request it is about to make. */
+export interface ProviderEgressBinding {
+  providerName: string;
+  provider: Pick<OcxProviderConfig, "proxy" | "noProxy">;
+}
+
+/**
+ * The request options expressing `binding`'s route for the destination actually being sent to.
+ *
+ * Resolved at the physical send rather than when the executor was built, for the reason #4992
+ * already established for the connection policy: a queued request can be rebuilt against a
+ * different upstream host before it leaves, and a route decided against the original
+ * destination would then be applied to a different one. With a host-scoped `noProxy` that
+ * inverts the decision, and the credential leaves by a route the operator did not choose.
+ *
+ * Refuses rather than degrades when the selected executor owns its own transport.
+ */
+export function providerEgressSendInit(
+  binding: ProviderEgressBinding,
+  physicalFetch: unknown,
+  input: string | URL | Request,
+): { proxy?: string | false } {
+  const url = egressTargetUrl(input);
+  if (url === null) return {};
+  const egress = resolveProviderEgress({ providerName: binding.providerName, provider: binding.provider, url });
+  if (providerEgressIsExplicit(egress) && !isEgressTransparentExecutor(physicalFetch)) {
+    // Name the field that actually made the route explicit. A bypass-list match with no
+    // `proxy` field at all would otherwise tell the operator to remove an override they
+    // never wrote.
+    const field = egress.kind === "direct" && egress.reason === "noProxy" ? "noProxy" : "proxy";
+    throw new InvalidProviderEgressError(
+      field,
+      "the selected transport owns its own routing, so this route cannot be applied",
+      `providers.${binding.providerName}.${field} cannot be applied to the selected provider transport; `
+      + "remove the provider egress override or the custom executor",
+    );
+  }
+  return providerEgressFetchInit(egress);
+}
+
+/**
+ * A destination used only to exercise the resolver at configuration time.
+ *
+ * Validation has no request URL, but `noProxy` is only meaningful against one. Resolving a
+ * reserved name checks the shape of both fields without asserting anything about which route a
+ * real request would take.
+ */
+const EGRESS_VALIDATION_URL = "https://validation.invalid/";
+
+/**
+ * The configuration error for a provider's egress fields, or null when they are usable.
+ *
+ * Delegates to `resolveProviderEgress` so configuration and request time cannot drift apart:
+ * a value accepted by `ocx config set` or the dashboard is one the transport will accept, and
+ * one rejected here is rejected there for the identical reason. Restating the rules would give
+ * this repository two definitions of a valid proxy value and no check that they agree.
+ */
+export function providerEgressConfigError(
+  provider: Pick<OcxProviderConfig, "proxy" | "noProxy">,
+): string | null {
+  try {
+    resolveProviderEgress({ providerName: "<validation>", provider, url: EGRESS_VALIDATION_URL });
+    return null;
+  } catch (error) {
+    if (error instanceof InvalidProviderEgressError) return `${error.field} is invalid: ${error.reason}`;
+    throw error;
+  }
+}

package/src/lib/provider-outbound.ts

@@ -7,12 +7,13 @@ import {
   resolvePublicAddresses,
 } from "./destination-policy";
 import { pinnedHttpGet, pinnedHttpPost } from "./pinned-http";
-import { configuredOutboundFetch, effectiveProxyFor, noProxyMatches, normalizeProxyHostname, outboundProxyConfigured } from "./proxy-env";
+import { configuredOutboundFetch, effectiveProxyFor, noProxyMatches, normalizeProxyHostname, schemeMatchedProxyFor } from "./proxy-env";
+import { InvalidProviderEgressError, resolveProviderEgress } from "./provider-egress";
 import { publicProviderBaseUrl } from "./provider-url";
 
 type ProviderGetInit = Omit<RequestInit, "body" | "method" | "redirect">;
 type ProviderPostInit = ProviderGetInit & { body: string };
-type ProviderOutboundConfig = Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork"> & {
+type ProviderOutboundConfig = Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork" | "proxy" | "noProxy"> & {
   fetch?: typeof globalThis.fetch;
 };
 export interface ProviderOutboundDependencies {
@@ -165,6 +166,17 @@ async function providerOutboundRequest(
   // throw inside discovery and fail the provider for a reason nothing in its configuration
   // explains; the built-in transport is what a configured value means.
   if (typeof provider.fetch === "function") {
+    // A caller-owned executor decides its own transport, so a provider egress route cannot be
+    // applied to it. Refusing is the only honest answer: running the executor anyway would send
+    // the request by whatever route that executor picked while the configuration says otherwise.
+    if (resolveProviderEgress({ providerName: name, provider, url }).kind !== "inherit") {
+      throw new InvalidProviderEgressError(
+        "proxy",
+        "a caller-supplied fetch executor owns its own routing, so this route cannot be applied",
+        `providers.${name}.proxy cannot be applied to a caller-supplied fetch executor; `
+        + "remove the provider egress override or the custom executor",
+      );
+    }
     // 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.
@@ -186,13 +198,39 @@ async function providerOutboundRequest(
     return provider.fetch(url, { ...init, method, redirect: "manual" });
   }
   const parsed = postUrl ?? new URL(url);
-  const proxyConfigured = outboundProxyConfigured();
-  // Snapshot the scheme-matched proxy once, before the DNS await, so admission and transport
-  // below reason about the same value. `null` here means "no proxy fetch would actually use",
-  // even if some other proxy variable is set.
-  const effectiveProxy = effectiveProxyFor(parsed);
+  // The provider's own route, decided against this request URL. `inherit` leaves every value
+  // below exactly as the global decision computed it.
+  const egress = resolveProviderEgress({ providerName: name, provider, url: parsed });
+  const providerProxy = egress.kind === "proxy" ? egress.proxyUrl : null;
+  // Snapshot the proxy fetch would actually use once, before the DNS await, so admission
+  // and transport below reason about the same value. `null` here means "no proxy fetch
+  // would actually use", even if some other proxy variable is set.
+  const globalProxy = effectiveProxyFor(parsed);
+  // The request leaves the DNS-pinned transport only when a proxy will actually carry it:
+  // a proxy variable fetch would use for this URL that NO_PROXY does not exempt.
+  // A scheme-mismatched or unusable variable, a NO_PROXY match, or an ALL_PROXY
+  // this target's scheme cannot use must not downgrade pinning or admit
+  // proxy-only DNS answers.
+  //
+  // A provider route replaces that decision outright rather than combining with it. An
+  // explicit provider proxy applies even where global NO_PROXY exempts the host, because the
+  // operator named this proxy for this provider; `providers.<name>.noProxy` is the exemption
+  // that belongs to that choice, and `resolveProviderEgress` has already applied it. A
+  // provider pinned to `direct` keeps the DNS-pinned transport, which reaches the peer
+  // through no proxy at all — the one route on this path that needs nothing from Bun.
+  const proxyApplies = egress.kind === "inherit"
+    ? globalProxy !== null && !noProxyMatches(parsed)
+    : providerProxy !== null;
   const isCanonicalUrl = dependencies.isCanonicalUrl ?? (() => false);
-  const allowMihomoIpv6FakeIp = (effectiveProxy !== null && !noProxyMatches(parsed))
+  // The IPv6 fake-IP gate keeps its stricter documented condition — a
+  // scheme-matched variable or a SOCKS5 ALL_PROXY, never a non-SOCKS
+  // ALL_PROXY — even when proxyApplies admits one for the transport
+  // decision, because admission binds the fetch to this value explicitly.
+  // An explicit provider proxy is exactly such a binding: the fetch below is pinned to it.
+  const bindingProxy = egress.kind === "inherit"
+    ? schemeMatchedProxyFor(parsed)
+    : providerProxy;
+  const allowMihomoIpv6FakeIp = (bindingProxy !== null && (providerProxy !== null || !noProxyMatches(parsed)))
     || transparentFakeIpException(url, parsed, isCanonicalUrl, name);
   const resolveAddresses = dependencies.resolveAddresses ?? resolvePublicAddresses;
   const pinnedGet = dependencies.pinnedGet ?? pinnedHttpGet;
@@ -216,7 +254,7 @@ async function providerOutboundRequest(
       // proof is on the final request URL — not the provider name — because an
       // OAuth/forward name matches any baseUrl by design while the bearer is
       // pinned to the registry destination independently.
-      allowBenchmarkAddresses: (proxyConfigured && !noProxyMatches(parsed))
+      allowBenchmarkAddresses: proxyApplies
         || transparentFakeIpException(url, parsed, isCanonicalUrl, name),
       // Mihomo IPv6 fake-IP (fdfe:dcba:9876::/48) answers are admitted either when bound
       // to a scheme-matched proxy (#3462) or under the TUN transparency exception for a
@@ -229,21 +267,28 @@ async function providerOutboundRequest(
     if (!dnsResolutionFailed) {
       throw new ProviderOutboundPolicyError(error instanceof Error ? error.message : "provider destination was blocked");
     }
-    if (!proxyConfigured) throw error;
+    if (!proxyApplies) throw error;
     warnProxyBoundaryOnce();
     warnProxyDnsDegradationOnce();
-    return configuredOutboundFetch(url, { ...init, method, redirect: "manual" });
+    // An explicit provider proxy stays pinned through the degradation too; re-inferring the
+    // route from the environment here would quietly move the request to a different exit.
+    return configuredOutboundFetch(url, {
+      ...init, method, redirect: "manual",
+      ...(providerProxy ? { proxy: providerProxy } : {}),
+    });
   }
   // A canonical TUN exception with no scheme-matched proxy must retain the
   // validated address, even when an unrelated HTTP_PROXY/ALL_PROXY is present.
-  if (proxyConfigured && !resolved.privateNetwork && (effectiveProxy !== null || !allowMihomoIpv6FakeIp)) {
+  if (proxyApplies && !resolved.privateNetwork) {
     warnProxyBoundaryOnce();
     // When the Mihomo exception could have admitted an answer, pin the transport to the
     // proxy the admission assumed instead of letting fetch re-infer it from the environment.
-    const proxy = (allowMihomoIpv6FakeIp && effectiveProxy) ? effectiveProxy : undefined;
+    // An explicit provider proxy is always pinned, for the same reason and unconditionally:
+    // the operator named the exit for this provider, so the environment must not re-decide it.
+    const proxy = providerProxy ?? ((allowMihomoIpv6FakeIp && bindingProxy) ? bindingProxy : undefined);
     return configuredOutboundFetch(url, { ...init, method, redirect: "manual", ...(proxy ? { proxy } : {}) });
   }
-  if (proxyConfigured && resolved.privateNetwork && !noProxyMatches(parsed)) {
+  if (proxyApplies && resolved.privateNetwork) {
     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`,