@bitkyc08/opencodex 2.68.0-preview.20260927 → 2.69.0-preview.20260928

package/src/integrations/state.ts

@@ -33,11 +33,15 @@ import {
 } from "./ownership-policy";
 import {
   INTEGRATION_CLIENTS,
+  boundIntegrationConfigPath,
+  assertDroidPathsUnambiguous,
+  assertDroidRecordedSettingsUnambiguous,
   resolveIntegrationPaths,
   unresolvedPathHintFor,
   type IntegrationClientId,
 } from "./registry";
 import { resolveIntegrationTarget, type IntegrationTarget } from "./target";
+import { inspectKiloCandidates } from "./kilo-candidates";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 
 export type IntegrationState = "absent" | "current" | "stale" | "conflict" | "unsafe";
@@ -49,6 +53,7 @@ export type StateReason =
   /** A container we would have to write through holds a non-object value. */
   | "blocked-container"
   | "ambiguous-selector"
+  | "candidate-conflict"
   /** A path selector we cannot resolve, e.g. a relative OPENCLAW_CONFIG_PATH. */
   | "unresolvable-path";
 
@@ -60,6 +65,10 @@ export interface IntegrationStatus {
   appliedAt?: string;
   lastOpId?: string;
   reason?: StateReason;
+  /** Other Kilo global candidates defining provider.opencodex. */
+  conflictPaths?: string[];
+  /** Kilo candidate that could not be inspected; may differ from the owned target. */
+  candidateFailurePath?: string;
   /**
    * The store this client reads instead of `configPath`.
    *
@@ -328,7 +337,13 @@ export function classifyIntegration(input: {
     }
     throw error;
   }
-  if (!hasOurFragments(input.parsed, input.contribution)) return { state: "absent" };
+  // A catalog can shrink to zero while the record still owns earlier rows.
+  // Presence for disable must include those recorded paths, independent of the
+  // current export roster; the ownership fingerprint is checked below.
+  if (!hasOurFragments(input.parsed, input.contribution)
+    && !(input.record?.fragmentPaths.some(path => readPath(input.parsed, path) !== undefined))) {
+    return { state: "absent" };
+  }
 
   /*
    * Fragments the desired contribution carries beyond the paths this record names. Both
@@ -520,7 +535,9 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
   try {
     // One resolution for both, so a client whose paths come from mutable state
     // cannot report one account's install beside another account's config path.
-    const paths = input.resolvedPaths ?? resolveIntegrationPaths(input.clientId, input.env, input.home);
+    const context = exportContextOf(input);
+    const paths = input.resolvedPaths ?? resolveIntegrationPaths(input.clientId, input.env, input.home, context);
+    if (input.clientId === "droid" && input.resolvedPaths) assertDroidPathsUnambiguous(paths.detectDir, context);
     installed = io.statKind(paths.detectDir) === "dir";
     if (input.clientId === "cline") io = createClineIO(io, paths.configPath, store);
     /*
@@ -530,8 +547,12 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
      * would let the badge and the switch disagree.
      */
     record = store.readRecords()[input.clientId] ?? null;
+    const recordedPath = boundIntegrationConfigPath({
+      clientId: input.clientId, record, resolvedPath: paths.configPath,
+      statKind: io.statKind, env: input.env, home: input.home,
+    });
     effective = resolveIntegrationTarget({
-      clientId: input.clientId, configPath: paths.configPath, io, record, env: input.env, home: input.home,
+      clientId: input.clientId, configPath: recordedPath, io, record, env: input.env, home: input.home,
     });
   } catch (error) {
     if (!(error instanceof ClientPathError)) throw error;
@@ -558,6 +579,20 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
   }
 
   const configPath = effective.configPath;
+  if (input.clientId === "kilo") {
+    const candidates = inspectKiloCandidates({ io, selectedPath: configPath, env: input.env, home: input.home });
+    if (candidates.kind !== "ok") return {
+      clientId: input.clientId,
+      state: candidates.kind === "conflict" ? "conflict" : "unsafe",
+      installed,
+      configPath,
+      reason: candidates.kind === "conflict" ? "candidate-conflict" : candidates.why,
+      ...(candidates.kind === "conflict" ? { conflictPaths: candidates.paths } : {}),
+      ...(candidates.kind === "unsafe" ? { candidateFailurePath: candidates.path } : {}),
+      ...(record && record.configPath === configPath ? { appliedAt: record.appliedAt, lastOpId: record.opId } : {}),
+      ...retention,
+    };
+  }
   const loaded = loadTarget(io, configPath);
   if (!loaded.ok) {
     return {
@@ -572,8 +607,13 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
 
   const parsed = input.clientId === "cline"
     ? parseClineDocument(loaded.before)
-    : parseConfig(loaded.before, effective.format);
+    : parseConfig(loaded.before, effective.format, EXPORT_CLIENTS[input.clientId].jsonc ? { jsonc: true } : undefined);
   const contribution = effective.buildContribution(exportContextOf(input));
+  if (input.clientId === "droid" && input.models.length > 0 && contribution.fragments.length === 0
+    && (!record || record.configPath !== configPath)) {
+    return { clientId: input.clientId, state: "unsafe", installed, configPath,
+      reason: "unresolvable-path", ...retention };
+  }
   const { state, reason } = classifyIntegration({
     fileText: loaded.before,
     fileIsRegular: true,
@@ -584,6 +624,14 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
     clientId: input.clientId,
     format: effective.format,
   });
+  if (input.clientId === "droid" && record && (state === "current" || state === "stale")) {
+    try { assertDroidRecordedSettingsUnambiguous(spec.detectDir(input.env, input.home), parsed, record); }
+    catch (error) {
+      if (!(error instanceof ClientPathError)) throw error;
+      return { clientId: input.clientId, state: "unsafe", installed, configPath,
+        reason: "unresolvable-path", ...retention };
+    }
+  }
 
   return {
     clientId: input.clientId,

package/src/integrations/target.ts

@@ -194,6 +194,9 @@ export function declaredIntegrationTarget(args: {
 }): IntegrationTarget | null {
   const { clientId, configPath, resolvedConfigPath } = args;
   if (configPath === resolvedConfigPath) return configFileTarget(clientId, configPath, null);
+  if (INTEGRATION_CLIENTS[clientId].bindsDriftedRecord?.(configPath, args.env, args.home) === true) {
+    return configFileTarget(clientId, configPath, null);
+  }
   const declared = INTEGRATION_CLIENTS[clientId].currentStore;
   if (!declared) return null;
   try {

package/src/integrations/writer.ts

@@ -19,6 +19,7 @@ import { detachedConfigSnapshot } from "../config/admitted-identity";
 import { copyPlainData } from "../lib/plain-data";
 import type { OcxConfig } from "../types";
 import { defaultIntegrationIO, loadTarget, type IntegrationIO } from "./config-io";
+import { inspectKiloCandidates } from "./kilo-candidates";
 import {
   fingerprint,
   canonicalContribution,
@@ -33,7 +34,14 @@ import {
   semanticProtectedContributionFingerprint,
 } from "./ownership-policy";
 import { AmbiguousSelectorError, createdContainerPaths, mergeContribution, removeFragments } from "./merge";
-import { INTEGRATION_CLIENTS, isLoopbackOnly, resolveIntegrationPaths, type IntegrationClientId } from "./registry";
+import {
+  INTEGRATION_CLIENTS,
+  assertDroidPathsUnambiguous,
+  isLoopbackOnly,
+  resolveIntegrationPaths,
+  restoreOwnershipCollision,
+  type IntegrationClientId,
+} from "./registry";
 import { declaredIntegrationTarget } from "./target";
 import { exportContextOf } from "./state";
 import type { IntegrationState } from "./state";
@@ -225,8 +233,8 @@ function sourcePreservingFragmentValue(
  * and Cline transaction recovery both write. Translating the planner's refusal into WriteRefused
  * here keeps the planner free of any dependency on this module's result type.
  */
-function preflight(input: IntegrationWriteInput) {
-  const observed = observeIntegration(input, { maintenance: true, recover: true });
+function preflight(input: IntegrationWriteInput, operation: "apply" | "disable") {
+  const observed = observeIntegration(input, { maintenance: true, recover: true }, operation);
   if (!observed.failed) return observed;
   const { reason, state, message, snapshotPath, residual } = observed.failed;
   const refused = refuse(input.clientId, reason, state, message, snapshotPath);
@@ -251,7 +259,7 @@ function applyOrRefreshIntegration(
   allowAbsent: boolean,
   conflictPolicy: ConflictPolicy = "refuse",
 ): WriteOutcome {
-  const pre = preflight(input);
+  const pre = preflight(input, "apply");
   if (pre.failed) return pre.failed;
   const { store, io, clientId, spec, target, configPath, detectDir, before, parsed, contribution, record, classified } = pre;
 
@@ -264,6 +272,9 @@ function applyOrRefreshIntegration(
     return refuse(clientId, "non_loopback", classified.state,
       `The generated ${clientId} integration is loopback-only and does not emit the admission header a non-loopback bind requires. Give it loopback access instead, through a tunnel or a local forwarder.`);
   }
+  if (clientId === "droid" && contribution.fragments.length === 0) {
+    return refuse(clientId, "unsafe", classified.state, "Factory Droid has no addressable models in the selected catalog");
+  }
   /*
    * The write would land, and nothing would read it.
    *
@@ -429,6 +440,21 @@ function applyOrRefreshIntegration(
   if (rechecked === undefined || rechecked !== before) {
     return refuse(clientId, "conflict", "conflict", `${configPath} changed while applying`);
   }
+  if (clientId === "kilo") {
+    const candidates = inspectKiloCandidates({ io, selectedPath: configPath, env: input.env, home: input.home });
+    if (candidates.kind === "conflict") return refuse(clientId, "conflict", "conflict",
+      `${configPath} cannot be managed while ${candidates.paths.join(", ")} also defines provider.opencodex`);
+    if (candidates.kind === "unsafe") return refuse(clientId, "unsafe", "unsafe",
+      `${candidates.path} cannot be inspected safely (${candidates.why})`);
+  }
+  if (clientId === "droid") {
+    try {
+      assertDroidPathsUnambiguous(detectDir, exportContextOf(input));
+    } catch (error) {
+      if (!(error instanceof ClientPathError)) throw error;
+      return refuse(clientId, "unsafe", "unsafe", messageOf(error));
+    }
+  }
 
   const opId = newOpId();
   const snapshot = store.captureSnapshot(clientId, opId, before);
@@ -497,7 +523,7 @@ export function refreshIntegration(input: IntegrationWriteInput): WriteOutcome {
 }
 
 export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
-  const pre = preflight(input);
+  const pre = preflight(input, "disable");
   if (pre.failed) return pre.failed;
   const { store, io, clientId, spec, target, configPath, before, parsed, record, classified } = pre;
 
@@ -625,6 +651,21 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
     return refuse(clientId, "conflict", "conflict",
       `that operation was recorded for ${configPath}, which this client no longer writes; it now resolves to ${resolvedPath}`);
   }
+  /*
+   * Preview refuses this in observeRestore. Refusing here too is what keeps an
+   * undo of an older candidate from replacing the record a newer candidate owns.
+   */
+  const currentOwner = store.readRecords()[clientId] ?? null;
+  const collision = restoreOwnershipCollision({
+    clientId,
+    journaledPath: configPath,
+    currentPath: currentOwner && currentOwner.clientId === clientId ? currentOwner.configPath : null,
+    env: input.env,
+    home: input.home,
+  });
+  if (collision !== null) {
+    return refuse(clientId, "conflict", "conflict", collision);
+  }
   if (clientId === "cline") {
     try { io = createClineIO(io, configPath, store, true); }
     catch (error) {
@@ -763,6 +804,14 @@ function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegration
   const store = input.store ?? createIntegrationStateStore();
   const io = input.io ?? defaultIntegrationIO(store);
   const spec = INTEGRATION_CLIENTS[input.clientId];
+  const config = detachedConfigSnapshot(input.config);
+  if (config === null) {
+    throw new UncopyableIntegrationInputError("the proxy configuration could not be captured for this write");
+  }
+  const models = copyPlainData(input.models);
+  if (!models.ok) {
+    throw new UncopyableIntegrationInputError("the model roster could not be captured for this write");
+  }
   /*
    * One resolution for both paths. Aside derives them from the account id in
    * its manifest, so two independent calls could verify one account's install
@@ -770,7 +819,7 @@ function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegration
    */
   const resolvedPaths = input.resolvedPaths
     ? { ...input.resolvedPaths }
-    : resolveIntegrationPaths(input.clientId, env, home);
+    : resolveIntegrationPaths(input.clientId, env, home, exportContextOf({ ...input, config, models: models.value }));
   /*
    * The configuration and the roster are seams like the others, and they were the two still held
    * by reference. A coordinated write plans from this input, awaits the writer lock and a
@@ -779,14 +828,6 @@ function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegration
    * checked in one state and written from another, which is the substitution the fingerprint
    * exists to prevent. Copying both here gives the plan and the document one input.
    */
-  const config = detachedConfigSnapshot(input.config);
-  if (config === null) {
-    throw new UncopyableIntegrationInputError("the proxy configuration could not be captured for this write");
-  }
-  const models = copyPlainData(input.models);
-  if (!models.ok) {
-    throw new UncopyableIntegrationInputError("the model roster could not be captured for this write");
-  }
   return { ...input, config, models: models.value, env, home, store, io, resolvedPaths };
 }
 

package/src/lib/account-selection-events.ts

@@ -6,6 +6,7 @@ export type AccountSelectionEvent = {
 };
 
 const listeners = new Set<(event: AccountSelectionEvent) => void>();
+const oauthPauseListeners = new Set<(provider: string) => void>();
 let revision = 0;
 
 /** Call only after the authoritative selection has been persisted. */
@@ -27,6 +28,19 @@ export function subscribeAccountSelections(listener: (event: AccountSelectionEve
   return () => { listeners.delete(subscription); };
 }
 
+/** Internal eligibility invalidation; separate from the public selection stream contract. */
+export function publishOAuthAccountPauseChange(provider: string): void {
+  for (const listener of [...oauthPauseListeners]) {
+    try { listener(provider); } catch { /* A disconnected cache consumer cannot undo persistence. */ }
+  }
+}
+
+export function subscribeOAuthAccountPauseChanges(listener: (provider: string) => void): () => void {
+  const subscription = (provider: string) => listener(provider);
+  oauthPauseListeners.add(subscription);
+  return () => { oauthPauseListeners.delete(subscription); };
+}
+
 export function currentAccountSelectionRevision(): number {
   return revision;
 }

package/src/lib/jsonc.ts

@@ -0,0 +1,110 @@
+/**
+ * JSONC parse used by OpenCode's launcher and Kilo's managed writer.
+ *
+ * Comments and trailing commas are stripped by escape-aware passes that are
+ * identity on valid strict JSON, so no strict-parse probe is ever needed.
+ */
+
+/**
+ * Strip `//` and block comments outside string literals. Escape-aware so a quote inside
+ * an escaped sequence cannot flip string state and expose config text to the stripper.
+ */
+function stripJsonComments(text: string): string {
+  let out = "";
+  let inString = false;
+  let inLine = false;
+  let inBlock = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]!;
+    const next = text[i + 1];
+    if (inLine) {
+      if (ch === "\n") {
+        inLine = false;
+        out += ch;
+      }
+      continue;
+    }
+    if (inBlock) {
+      // Newlines are preserved so JSON.parse error positions stay meaningful.
+      if (ch === "\n") out += ch;
+      else if (ch === "*" && next === "/") {
+        // Emit a separator, not nothing: a block comment between two digits is
+        // two tokens and must not collapse into one, which would silently
+        // change a malformed value into a different valid one. Whitespace is
+        // legal wherever a comment was, so this is identity for valid JSONC.
+        out += " ";
+        inBlock = false;
+        i++;
+      }
+      continue;
+    }
+    if (inString) {
+      out += ch;
+      if (ch === "\\") {
+        const escaped = text[i + 1];
+        if (escaped !== undefined) { out += escaped; i++; }
+        continue;
+      }
+      if (ch === "\"") inString = false;
+      continue;
+    }
+    if (ch === "\"") { inString = true; out += ch; continue; }
+    if (ch === "/" && next === "/") { inLine = true; i++; continue; }
+    if (ch === "/" && next === "*") { inBlock = true; i++; continue; }
+    out += ch;
+  }
+  /*
+   * An unterminated block comment means the remainder of the document was
+   * comment text. Returning it stripped would let a trailing `/*` delete an
+   * arbitrary malformed tail, so the caller sees a parse failure instead.
+   */
+  if (inBlock) throw new SyntaxError("Unterminated block comment");
+  return out;
+}
+
+/** Drop commas that sit directly before `}` or `]`, ignoring string contents. */
+function stripTrailingCommas(text: string): string {
+  let out = "";
+  let inString = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]!;
+    if (inString) {
+      out += ch;
+      if (ch === "\\") {
+        const escaped = text[i + 1];
+        if (escaped !== undefined) { out += escaped; i++; }
+        continue;
+      }
+      if (ch === "\"") inString = false;
+      continue;
+    }
+    if (ch === "\"") { inString = true; out += ch; continue; }
+    if (ch === ",") {
+      let j = i + 1;
+      while (j < text.length && /\s/.test(text[j]!)) j++;
+      if (text[j] === "}" || text[j] === "]") continue;
+    }
+    out += ch;
+  }
+  return out;
+}
+
+/**
+ * Return JSON that `JSON.parse` will accept. Comments and trailing commas are
+ * stripped unconditionally: never probed with a strict `JSON.parse` first,
+ * because materializing a deeply nested document before the rewrite guard's
+ * depth ceiling would bypass that guard's resource contract. The passes are
+ * identity on valid strict JSON — `//`, `/*`, and a comma before `}` or `]`
+ * can only appear inside strings there, which the strippers never touch.
+ */
+export function canonicalizeJsonc(text: string): string {
+  return stripTrailingCommas(stripJsonComments(text));
+}
+
+/**
+ * JSON with optional comments and trailing commas. Same stripping rules as
+ * `canonicalizeJsonc`; throws on text that is still not JSON afterwards.
+ */
+export function parseJsonc(text: string): unknown {
+  return JSON.parse(canonicalizeJsonc(text));
+}

package/src/lib/standalone.ts

@@ -7,7 +7,15 @@ export function isStandaloneBinary(): boolean {
 }
 
 export function isStandaloneModuleUrl(url: string): boolean {
-  return url.includes("/$bunfs/") || /^file:\/\/\/[A-Za-z]:\/~BUN\//.test(url);
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "file:" || parsed.host !== "") return false;
+    // Bun may encode the Windows virtual root's tilde; decode one URL layer only.
+    const path = decodeURIComponent(parsed.pathname);
+    return path.startsWith("/$bunfs/") || /^\/[A-Za-z]:\/~BUN\//.test(path);
+  } catch {
+    return false;
+  }
 }
 
 /** Directory containing the compiled executable and its copied runtime assets. */

package/src/lib/windows-system-proxy.ts

@@ -10,7 +10,8 @@ import { decodeWindowsTextBytes } from "./windows-text";
  * normalized `http://host:port` URL when a static proxy is enabled. PAC/WPAD, per-request
  * resolution, ProxyOverride, live refresh, and direct fallback are deliberately out of scope:
  * this is the piece an operator can audit from one log line, and everything else needs the
- * transport boundary the reviewer asked for first.
+ * transport boundary the reviewer asked for first. The bypass readers further down serve
+ * `ocx doctor` only; egress discovery does not consult them.
  */
 
 const INTERNET_SETTINGS_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings";
@@ -114,6 +115,105 @@ export function readWindowsSystemProxy(
   return parseWindowsProxyServer(values.proxyServer);
 }
 
+/**
+ * The two values that decide whether a host skips the static proxy: `ProxyOverride` (the bypass
+ * list) and `AutoConfigURL` (a PAC script, which takes over the decision entirely), plus the
+ * "Automatically detect settings" (WPAD) flag, which can also pick a proxy per request. Read on
+ * demand by diagnostics only; startup discovery above still ignores all three.
+ */
+export interface WindowsProxyBypassValues {
+  proxyOverride: string | null;
+  autoConfigUrl: string | null;
+  /** `null` when the connection-settings blob could not be read: detection may be on. */
+  autoDetect: boolean | null;
+}
+
+/** Output lines of `reg query <key>`, or `null` when the key could not be read at all. */
+export type WindowsRegistryKeyLister = (key: string) => string | null;
+
+function listRegistryKey(key: string): string | null {
+  try {
+    const stdout = execFileSync(registryExe(), ["query", key], {
+      encoding: "buffer",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000,
+      maxBuffer: 256 * 1024,
+      windowsHide: true,
+    });
+    return decodeWindowsTextBytes(stdout);
+  } catch {
+    return null;
+  }
+}
+
+function registryValue(listing: string, name: string): string | null {
+  for (const row of listing.split(/\r?\n/)) {
+    // "    Name    REG_TYPE    data" (data is absent for an empty string)
+    const match = row.match(/^ {4}(\S.*?) {4}(REG_[A-Z_]+)(?: {4}(.*))?$/);
+    if (match && match[1]!.toLowerCase() === name.toLowerCase()) return (match[3] ?? "").trim();
+  }
+  return null;
+}
+
+/**
+ * WinINET `DefaultConnectionSettings` stores its flags in the ninth byte; 0x08 is
+ * "Automatically detect settings". Anything unparseable returns `null` (unknown), never `false`.
+ */
+export function parseWindowsAutoDetect(hex: string | null): boolean | null {
+  if (!hex || !/^[0-9a-f]{18,}$/i.test(hex)) return null;
+  return (Number.parseInt(hex.slice(16, 18), 16) & 0x08) !== 0;
+}
+
+/**
+ * Reads the bypass values from one listing of the Internet Settings key, so an absent value
+ * (`null`) is distinguishable from a failed read (the whole result is `null`).
+ */
+export function readWindowsProxyBypassRegistry(
+  list: WindowsRegistryKeyLister = listRegistryKey,
+): WindowsProxyBypassValues | null {
+  const settings = list(INTERNET_SETTINGS_KEY);
+  if (settings === null) return null;
+  const connections = list(`${INTERNET_SETTINGS_KEY}\\Connections`);
+  return {
+    proxyOverride: registryValue(settings, "ProxyOverride"),
+    autoConfigUrl: registryValue(settings, "AutoConfigURL") || null,
+    autoDetect: connections === null ? null : parseWindowsAutoDetect(registryValue(connections, "DefaultConnectionSettings")),
+  };
+}
+
+/**
+ * Whether a WinINET `ProxyOverride` list exempts an HTTPS `host` (port 443). Entries are
+ * semicolon separated, case-insensitive, and may use `*` wildcards, a leading `.` for
+ * subdomains, an optional `scheme://` prefix and an optional `:port`. `<local>` matches only
+ * dotless names, so it never exempts a public API host.
+ */
+export function windowsProxyOverrideBypasses(proxyOverride: string | null, host: string): boolean {
+  if (!proxyOverride) return false;
+  const target = host.toLowerCase();
+  for (const raw of proxyOverride.split(";")) {
+    let entry = raw.trim().toLowerCase();
+    if (!entry) continue;
+    if (entry === "<local>") {
+      if (!target.includes(".")) return true;
+      continue;
+    }
+    const scheme = entry.match(/^([a-z][a-z0-9+.-]*):\/\//);
+    if (scheme) {
+      if (scheme[1] !== "https") continue;
+      entry = entry.slice(scheme[0].length);
+    }
+    const port = entry.match(/:(\d+)$/);
+    if (port) {
+      if (port[1] !== "443") continue;
+      entry = entry.slice(0, -port[0].length);
+    }
+    if (entry.startsWith(".")) entry = `*${entry}`;
+    const pattern = new RegExp(`^${entry.split("*").map(part => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`);
+    if (pattern.test(target)) return true;
+  }
+  return false;
+}
+
 /** Log-safe form: origin only, so a credentialed value can never reach the console. */
 export function describeProxyForLog(url: string): string {
   try { return new URL(url).origin; } catch { return "<unparseable>"; }

package/src/link/relay-auth.ts

@@ -0,0 +1,29 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+export const LINK_RELAY_AUTH_PATH = "/.well-known/opencodex/link-relay-auth";
+export const LINK_RELAY_SESSION_HEADER = "x-opencodex-link-session";
+export const LINK_RELAY_AUTH_VERSION = "2";
+export const LINK_RELAY_AUTH_TIMEOUT_MS = 5_000;
+
+/** The direction and both identities are covered; a caller proof is never a listener proof. */
+export function linkRelayProof(
+  fingerprint: string, direction: "caller" | "listener", keyId: string, linkId: string, nonce: string,
+): string | null {
+  if (!/^[a-f0-9]{64}$/.test(fingerprint) || !/^lnk_[a-f0-9]{16}$/.test(linkId)
+    || !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,255}$/.test(keyId) || !/^[a-f0-9]{64}$/.test(nonce)) return null;
+  return createHmac("sha256", Buffer.from(fingerprint, "hex"))
+    .update(`opencodex-link-relay-v2\0${direction}\0${keyId}\0${linkId}\0${nonce}`).digest("hex");
+}
+
+export function linkRelayChallenge(fingerprint: string, keyId: string, linkId: string) {
+  const nonce = randomBytes(32).toString("hex");
+  const caller = linkRelayProof(fingerprint, "caller", keyId, linkId, nonce);
+  const expected = linkRelayProof(fingerprint, "listener", keyId, linkId, nonce);
+  if (!caller || !expected) throw new Error("invalid link relay identity");
+  return { nonce, caller, expected };
+}
+
+export function linkRelayProofMatches(actual: string | null, expected: string | null): boolean {
+  return !!actual && !!expected && /^[a-f0-9]{64}$/.test(actual) && /^[a-f0-9]{64}$/.test(expected)
+    && timingSafeEqual(Buffer.from(actual, "hex"), Buffer.from(expected, "hex"));
+}

package/src/link/ssh-argv.ts

@@ -114,7 +114,7 @@ export function buildTunnelArgv(options: TunnelArgvOptions): string[] {
 
 export interface ExecArgvOptions {
   alias: string;
-  /** Remote argv. Each element is quoted for the remote POSIX shell. */
+  /** Remote argv. The command must be sh; its arguments are quoted for the remote shell. */
   argv: readonly string[];
   knownHostsFile: string;
 }
@@ -177,10 +177,13 @@ export function buildResolveArgv(alias: string): string[] {
   return ["ssh", "-G", "--", assertSshAlias(alias)];
 }
 
-/** Quote argv for a POSIX remote shell: every element single-quoted, embedded quotes escaped. */
+/** Emit only sh in command position; single-quote every argument for the remote shell. */
 export function quoteRemote(argv: readonly string[]): string {
-  return argv.map(arg => {
+  if (argv[0] !== "sh") throw new LinkSshArgumentError("remote command must be sh");
+  return argv.map((arg, index) => {
     if (arg.includes("\0")) throw new LinkSshArgumentError("remote argument contains NUL");
+    // PowerShell treats a leading quoted word as an expression, not a command invocation.
+    if (index === 0) return "sh";
     return `'${arg.replaceAll("'", `'"'"'`)}'`;
   }).join(" ");
 }

package/src/link/ssh-runner.ts

@@ -93,7 +93,7 @@ export class SshRunnerError extends Error {
   }
 }
 
-async function readOutput(stream: ReadableStream<Uint8Array>, maxBytes: number, kill?: () => void): Promise<string> {
+async function readOutput(stream: ReadableStream<Uint8Array>, maxBytes: number, kill?: () => void, fatalUtf8 = true): Promise<string> {
   const reader = stream.getReader();
   const chunks: Uint8Array[] = [];
   let total = 0;
@@ -118,7 +118,7 @@ async function readOutput(stream: ReadableStream<Uint8Array>, maxBytes: number,
     offset += chunk.byteLength;
   }
   try {
-    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return new TextDecoder("utf-8", { fatal: fatalUtf8 }).decode(bytes);
   } catch (error) {
     throw new SshRunnerError("decode", "ssh output was not valid UTF-8", { cause: error });
   }
@@ -150,7 +150,7 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
       throw new SshRunnerError("spawn", `could not spawn ${argv[0] ?? "ssh"}`, { cause: error });
     }
     const stdout = readOutput(outputStream(child.stdout), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"));
-    const stderr = readOutput(outputStream(child.stderr), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"));
+    const stderr = readOutput(outputStream(child.stderr), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"), false);
     void stdout.catch(() => {});
     void stderr.catch(() => {});
     return {
@@ -181,8 +181,8 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
         throw new SshRunnerError("spawn", `could not spawn ${argv[0] ?? "ssh"}`, { cause: error });
       }
 
-    const stdout = readOutput(outputStream(child.stdout), Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), () => defaultKill(child, "SIGTERM"));
-    const stderr = readOutput(outputStream(child.stderr), Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), () => defaultKill(child, "SIGTERM"));
+      const stdout = readOutput(outputStream(child.stdout), Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), () => defaultKill(child, "SIGTERM"));
+      const stderr = readOutput(outputStream(child.stderr), Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), () => defaultKill(child, "SIGTERM"), false);
       if (options.stdin !== undefined) {
         try {
           const input = child.stdin;