@bitkyc08/opencodex 2.86.0 → 2.88.0

package/src/claude/inbound-content-options.ts

@@ -76,6 +76,83 @@ export function toolsToResponses(tools: unknown): Rec[] | undefined {
   return out.length > 0 ? out : undefined;
 }
 
+/**
+ * The caller's typed Anthropic web tools (`web_search_*`, `web_fetch_*`), as declared. The
+ * Responses body has no slot for them — web_search becomes the hosted sidecar tool above and
+ * web_fetch is dropped — so an Anthropic destination receives them out of body, unchanged.
+ */
+export function declaredAnthropicServerTools(raw: unknown): Rec[] | undefined {
+  if (!isRec(raw) || !Array.isArray(raw.tools)) return undefined;
+  const tools = raw.tools.filter((t): t is Rec => isRec(t) && typeof t.type === "string" && /^web_(search|fetch)_\d+$/.test(t.type));
+  return tools.length > 0 ? tools : undefined;
+}
+
+/** Validate original call/result order without inventing inputs or pairing a later call backwards. */
+function replayableServerRun(run: readonly Rec[]): boolean {
+  const pending = new Map<string, Rec>();
+  const completed = new Set<string>();
+  for (const block of run) {
+    if (block.type === "server_tool_use") {
+      const { id, name, input } = block;
+      if (typeof id !== "string" || !id.startsWith("srvtoolu_") || pending.has(id) || completed.has(id)
+        || (name !== "web_search" && name !== "web_fetch") || !isRec(input)) return false;
+      const prototype = Object.getPrototypeOf(input);
+      const required = input[name === "web_search" ? "query" : "url"];
+      if ((prototype !== Object.prototype && prototype !== null)
+        || typeof required !== "string" || required.trim().length === 0) return false;
+      pending.set(id, block);
+    } else {
+      const id = block.tool_use_id;
+      if (typeof id !== "string") return false;
+      const call = pending.get(id);
+      if (!call || block.type !== `${call.name}_tool_result`
+        || (Array.isArray(block.content) && !block.content.every(h => isRec(h) && typeof h.encrypted_content === "string"))) return false;
+      pending.delete(id);
+      completed.add(id);
+    }
+  }
+  return completed.size > 0 && pending.size === 0;
+}
+
+/**
+ * Completed Anthropic server-tool exchanges (`server_tool_use` + `web_search_tool_result` /
+ * `web_fetch_tool_result`) in the caller's assistant history. The Responses body drops them, so
+ * an Anthropic destination re-inserts them out of body, keyed by the block that follows each run
+ * in its message: `call:<tool_use id>`, `text:<text>`, `thinking:<signature>` or
+ * `redacted:<data>`, all of which survive translation. An anchor that occurs more than once in the
+ * assistant history (string content included) cannot name one owner, so its run stays dropped,
+ * as it was before replay existed. A run with none, an unpaired call, a
+ * non-Anthropic id, or a search hit without `encrypted_content` is not replayable and stays dropped.
+ */
+export function replayedAnthropicServerBlocks(raw: unknown): Map<string, Rec[]> | undefined {
+  if (!isRec(raw) || !Array.isArray(raw.messages)) return undefined;
+  const out = new Map<string, Rec[]>();
+  const seen = new Map<string, number>();
+  const count = (anchor: string) => seen.set(anchor, (seen.get(anchor) ?? 0) + 1);
+  for (const message of raw.messages) {
+    if (!isRec(message) || message.role !== "assistant") continue;
+    if (typeof message.content === "string") count(`text:${message.content}`);
+    if (!Array.isArray(message.content)) continue;
+    let run: Rec[] = [];
+    for (const block of message.content.filter(isRec)) {
+      if (block.type === "server_tool_use" || block.type === "web_search_tool_result" || block.type === "web_fetch_tool_result") {
+        // The caller's breakpoints are dropped on this lane, as for the declared tools above.
+        run.push({ ...block, cache_control: undefined });
+        continue;
+      }
+      const anchor = block.type === "tool_use" ? `call:${String(block.id)}`
+        : block.type === "text" ? `text:${String(block.text)}`
+        : block.type === "thinking" ? `thinking:${String(block.signature)}`
+        : block.type === "redacted_thinking" ? `redacted:${String(block.data)}` : undefined;
+      if (anchor) count(anchor);
+      if (anchor && replayableServerRun(run)) out.set(anchor, run);
+      run = [];
+    }
+  }
+  for (const anchor of out.keys()) if ((seen.get(anchor) ?? 0) > 1) out.delete(anchor);
+  return out.size > 0 ? out : undefined;
+}
+
 export function toolChoiceToResponses(choice: unknown, body: Rec): void {
   if (!isRec(choice)) return;
   if (choice.disable_parallel_tool_use === true) body.parallel_tool_calls = false;

package/src/claude/inbound.ts

@@ -387,6 +387,39 @@ function canonicalJson(value: unknown): string {
 /** Provenance of the generated prompt_cache_key (never serialized into the wire body). */
 export type ClaudeCacheKeySource = "metadata" | "system" | null;
 
+/**
+ * The translated lane places its own prompt-cache breakpoints, so the caller's are dropped;
+ * their TTL is the one thing worth keeping. When every caller breakpoint asks for `ttl: "1h"`
+ * (Claude Code on a subscription marks them so) this maps to `cacheRetention: "long"`. A mixed
+ * caller (1h prefix, 5m tail) stays on the default: "long" also makes the moving per-turn
+ * breakpoint 1h, which bills writes the caller asked to keep at the 5m rate at the 1h rate.
+ * Read out of body: the Responses body has no field for it.
+ */
+export function callerCacheRetention(raw: unknown): "long" | undefined {
+  if (!isRec(raw)) return undefined;
+  // Top-level automatic caching is a breakpoint too, and content blocks nest (tool_result,
+  // search_result, document sources), so every block container is walked. Tool inputs and
+  // schemas are caller data, not blocks: a `cache_control` key there is not a breakpoint.
+  const ttls: unknown[] = [];
+  const visit = (node: unknown, depth: number): void => {
+    if (depth > 16) return;
+    if (Array.isArray(node)) { for (const item of node) visit(item, depth + 1); return; }
+    if (!isRec(node)) return;
+    if (isRec(node.cache_control)) ttls.push(node.cache_control.ttl);
+    for (const [key, value] of Object.entries(node)) {
+      if (key !== "cache_control" && key !== "input" && key !== "input_schema"
+        && (Array.isArray(value) || isRec(value))) visit(value, depth + 1);
+    }
+  };
+  if (isRec(raw.cache_control)) ttls.push(raw.cache_control.ttl);
+  visit(raw.system, 0);
+  visit(raw.tools, 0);
+  visit(raw.messages, 0);
+  return ttls.length > 0 && ttls.every(ttl => ttl === "1h")
+    ? "long"
+    : undefined;
+}
+
 export interface ClaudeInboundTranslation {
   body: Rec;
   cacheKeySource: ClaudeCacheKeySource;

package/src/claude/intercept/picker-ca-startup.ts

@@ -2,12 +2,13 @@ import { ensurePickerCa, type PickerCa } from "./picker-ca";
 import { drainPendingPickerCaUntrust } from "./picker-ca-cleanup";
 import type { PickerCaStore } from "./picker-ca-store";
 import type { SecurityRunner } from "./picker-trust";
+import { supportsDesktopPicker } from "../desktop-picker-platform";
 
 /** Internal activation seam: finish legacy cleanup before a persistent issuer is usable. */
 export async function preparePersistentPickerAuthority(options: {
   configDir: string; store?: PickerCaStore; security?: SecurityRunner; platform: NodeJS.Platform;
 }): Promise<PickerCa> {
-  if (options.platform !== "darwin") throw new Error("picker_ca_unsupported_platform");
+  if (!supportsDesktopPicker(options.platform)) throw new Error("picker_ca_unsupported_platform");
   const drain = () => drainPendingPickerCaUntrust(options.configDir, options.security, options.platform);
   if (!await drain()) throw new Error("picker_ca_pending_untrust");
   const ca = ensurePickerCa(options.configDir, { rotation: "startup", persistent: true, store: options.store });

package/src/claude/intercept/picker-runtime.ts

@@ -7,15 +7,16 @@
  * `intercept`. Everything else, and claude.ai whenever any condition fails, is a blind tunnel.
  *
  * The decision is cached by `refresh()` and only read by `selectTunnel`, so a CONNECT never
- * waits on the keychain or the catalog. Arming needs all of: macOS, the persisted resolved mode is
+ * waits on the OS trust store or the catalog. Arming needs all of: a supported platform, the persisted resolved mode is
  * first-party (observation-aware, so a pre-field first-party install counts), Desktop intent on,
  * `claudeCode.intercept.picker !== false`, the disarm latch clear, the picker listener up and the
- * current picker CA trusted in the login keychain. `disarm()` stops terminating immediately and
+ * current picker CA trusted in the OS root store. `disarm()` stops terminating immediately and
  * latches; only the picker controller's owner-only `rearm()` clears the latch.
  */
 import { join } from "node:path";
 import type { OcxConfig } from "../../types";
 import type { ClaudeDesktopMode } from "../desktop-first-party";
+import { supportsDesktopPicker } from "../desktop-picker-platform";
 import type { TunnelDecision } from "./connect-proxy";
 import type { PemKeyPair } from "./local-ca";
 import { PICKER_HOST, ensurePickerCa, issuePickerLeaf, pickerCaFingerprints, pickerLeafCertPath, pickerStateDir, type PickerCa } from "./picker-ca";
@@ -108,7 +109,7 @@ export function pickerDesired(
   mode: ClaudeDesktopMode,
   platform: NodeJS.Platform = process.platform,
 ): boolean {
-  return platform === "darwin"
+  return supportsDesktopPicker(platform)
     && config.clientIntegrations?.["claude-desktop"] !== false
     && mode === "first-party"
     && config.claudeCode?.intercept?.picker !== false;
@@ -225,7 +226,7 @@ export function createPickerRuntime(options: CreatePickerRuntimeOptions): Picker
       desired = pickerDesired(fresh, mode, platform);
       if (!desired || latched) {
         armed = false;
-        reason = platform !== "darwin" ? "unsupported_platform" : latched ? "disarmed" : "not_desired";
+        reason = !supportsDesktopPicker(platform) ? "unsupported_platform" : latched ? "disarmed" : "not_desired";
         closeListener();
         return;
       }
@@ -312,7 +313,7 @@ export function createPickerRuntime(options: CreatePickerRuntimeOptions): Picker
       const current = snapshot?.current() ?? null;
       return {
         desired,
-        supported: platform === "darwin",
+        supported: supportsDesktopPicker(platform),
         trust,
         listenerReady: listener !== null,
         effective: armed && listener !== null && !latched && !stopped,

package/src/claude/intercept/picker-trust-windows.ts

@@ -0,0 +1,338 @@
+import { X509Certificate } from "node:crypto";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveTrustedWindowsPowerShellExe } from "../../lib/windows-elevation";
+import {
+  acceptsPickerAuthority,
+  PICKER_CA_COMMON_NAME,
+  PICKER_HOST,
+  pickerCaFingerprints,
+} from "./picker-ca";
+import type { PickerTrustState, SecurityResult } from "./picker-trust";
+
+/** powershell.exe argv result; alias so the two trust seams never drift apart. */
+export type WindowsTrustResult = SecurityResult;
+/** Per-script options; fakes may ignore them, so single-arg fakes stay portable. */
+export interface WindowsTrustRunnerOptions { timeoutMs?: number }
+
+/**
+ * powershell.exe argv runner. A SecurityRunner satisfies this shape so macOS-style
+ * fakes stay portable. The caller in picker-trust.ts only forwards an explicitly
+ * injected runner and otherwise leaves this undefined for the Windows default.
+ */
+export type WindowsTrustRunner = (
+  args: readonly string[],
+  options?: WindowsTrustRunnerOptions,
+) => Promise<WindowsTrustResult>;
+
+/** Read-only argv prefix: no profile, no logo, no interaction. Used for inspection. */
+export const WINDOWS_TRUST_POWERSHELL_PREFIX = ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command"] as const;
+/** Mutating argv prefix: the OS confirmation dialog must be able to appear. */
+export const WINDOWS_TRUST_POWERSHELL_INTERACTIVE_PREFIX = ["-NoLogo", "-NoProfile", "-Command"] as const;
+
+/** Read-only inspection budget: a hung store lookup must never stall status checks. */
+export const WINDOWS_TRUST_INSPECT_TIMEOUT_MS = 10_000;
+/** Interactive import budget: Root installs raise the OS confirmation dialog. */
+export const WINDOWS_TRUST_IMPORT_TIMEOUT_MS = 120_000;
+/**
+ * Removal budget stays bounded: predecessor cleanup also runs in headless migration
+ * and startup paths where an OS confirmation dialog cannot be answered. A timed-out or
+ * declined removal reports failure and is retried on the next explicit activation.
+ */
+export const WINDOWS_TRUST_UNTRUST_TIMEOUT_MS = 30_000;
+
+const OUTPUT_LIMIT = 64 * 1024;
+const TRUST_MARKER = "OCX_PICKER_TRUST=";
+const SHA1_PATTERN = /^[0-9A-F]{40}$/;
+const BASE64_PATTERN = /^[A-Za-z0-9+/=]*$/;
+
+/** Uppercase hex without separators, or null. Trust matches on this, never on the CN. */
+export function normalizePickerTrustSha1(value: string): string | null {
+  const normalized = value.replace(/[:\s]/g, "").toUpperCase();
+  return SHA1_PATTERN.test(normalized) ? normalized : null;
+}
+
+/**
+ * Copy the environment minus every PSModulePath entry (case-insensitive).
+ * The trust scripts are .NET-only so module autoload is pure cost and shadowing
+ * risk: a PSModulePath entry can shadow resolution and stall process start on
+ * hosts with a cold module cache. Nothing here needs a module.
+ */
+export function sanitizeWindowsPowerShellEnv(env: NodeJS.ProcessEnv = process.env): Record<string, string | undefined> {
+  const out: Record<string, string | undefined> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (key.toLowerCase() === "psmodulepath") continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Production runner: trusted System32 powershell.exe, hidden window, sanitized
+ * module path, bounded runtime. Timeout and output-read errors kill the child and report code null
+ * so callers map it to unknown/declined instead of hanging periodic status.
+ */
+export const defaultWindowsPowerShellRunner: WindowsTrustRunner = async (args, options) => {
+  const timeoutMs = options?.timeoutMs ?? WINDOWS_TRUST_INSPECT_TIMEOUT_MS;
+  let exe: string;
+  try {
+    exe = resolveTrustedWindowsPowerShellExe();
+  } catch (error) {
+    return { code: null, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+  }
+  let child: { kill(): void } | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const proc = Bun.spawn([exe, ...args], {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+      windowsHide: true,
+      env: sanitizeWindowsPowerShellEnv(),
+    });
+    child = proc;
+    const pending = (async () => {
+      const [out, err, code] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+      ]);
+      return { out, err, code };
+    })();
+    const settled = await new Promise<{ out: string; err: string; code: number } | null>((resolve, reject) => {
+      timer = setTimeout(() => {
+        try { child?.kill(); } catch { /* already gone */ }
+        resolve(null);
+      }, timeoutMs);
+      pending.then(resolve, reject);
+    });
+    if (timer !== undefined) clearTimeout(timer);
+    if (settled === null) {
+      return { code: null, stdout: "", stderr: `powershell trust script timed out after ${timeoutMs}ms` };
+    }
+    return { code: settled.code, stdout: settled.out.slice(-OUTPUT_LIMIT), stderr: settled.err.slice(-OUTPUT_LIMIT) };
+  } catch (error) {
+    if (timer !== undefined) clearTimeout(timer);
+    try { child?.kill(); } catch { /* already gone */ }
+    return { code: null, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+  }
+};
+
+function base64Utf8(value: string): string {
+  return Buffer.from(value, "utf8").toString("base64");
+}
+
+/** A filesystem path carried as data, never as PowerShell syntax. */
+function encodedPathExpression(path: string): string {
+  const encoded = base64Utf8(path);
+  if (!BASE64_PATTERN.test(encoded)) throw new Error("path encoding failed");
+  return `[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encoded}'))`;
+}
+
+/** Interpolated constants must not carry a quote or wildcard that changes the script. */
+function psLiteral(value: string, label: string): string {
+  if (value.includes("'") || /[*?[\]]/.test(value)) throw new Error(`unsafe ${label} for script literal`);
+  return `'${value}'`;
+}
+
+function markerOf(stdout: string): string | null {
+  const line = stdout
+    .split(/\r?\n/)
+    .map(entry => entry.trim())
+    .find(entry => entry.startsWith(TRUST_MARKER));
+  return line === undefined ? null : line.slice(TRUST_MARKER.length);
+}
+
+function currentUserRootStore(): string {
+  return "New-Object Security.Cryptography.X509Certificates.X509Store('Root','CurrentUser')";
+}
+
+function subjectLikePattern(): string {
+  if (PICKER_CA_COMMON_NAME.length === 0 || /['*?[\]]/.test(PICKER_CA_COMMON_NAME)) {
+    throw new Error("unsafe picker CA common name for script literal");
+  }
+  return `'*CN=${PICKER_CA_COMMON_NAME}*'`;
+}
+
+/**
+ * Inspect script: exact SHA-1 lookup in CurrentUser Root, persisted-leaf chain build
+ * against that root, plus DNS-name and validity checks. Emits exactly one marker
+ * line and exits 0 (trusted), 1 (untrusted) or 2 (error). Read-only: trust is never
+ * added or removed here; installation happens only on explicit activation via trust.
+ */
+export function buildWindowsTrustInspectScript(leafPath: string, wantSha1: string): string {
+  const want = normalizePickerTrustSha1(wantSha1);
+  if (want === null) throw new Error("picker trust fingerprint must be 40 hex characters");
+  if (leafPath.length === 0) throw new Error("picker trust leaf path must not be empty");
+  const host = psLiteral(PICKER_HOST, "picker host");
+  return [
+    "$ErrorActionPreference='Stop'",
+    `$leafFile=${encodedPathExpression(leafPath)}`,
+    `$want=${psLiteral(want, "picker CA fingerprint")}`,
+    `$store=${currentUserRootStore()}`,
+    "$store.Open('ReadOnly')",
+    "try {",
+    "$found=@($store.Certificates | Where-Object { $_.Thumbprint -eq $want })",
+    `if($found.Count -eq 0) { Write-Output '${TRUST_MARKER}UNTRUSTED'; exit 1 }`,
+    "$ca=$found[0]",
+    `if($ca.Subject -notlike ${subjectLikePattern()}) { Write-Output '${TRUST_MARKER}UNTRUSTED'; exit 1 }`,
+    "$leaf=New-Object Security.Cryptography.X509Certificates.X509Certificate2($leafFile)",
+    "$dns=$leaf.GetNameInfo([Security.Cryptography.X509Certificates.X509NameType]::DnsName,$false)",
+    `if($dns -ne ${host}) { Write-Output '${TRUST_MARKER}UNTRUSTED'; exit 1 }`,
+    "$now=Get-Date",
+    `if($leaf.NotBefore -gt $now -or $leaf.NotAfter -lt $now) { Write-Output '${TRUST_MARKER}UNTRUSTED'; exit 1 }`,
+    `if($leaf.Issuer -ne $ca.Subject) { Write-Output '${TRUST_MARKER}UNTRUSTED'; exit 1 }`,
+    "$chain=New-Object Security.Cryptography.X509Certificates.X509Chain",
+    "$chain.ChainPolicy.RevocationMode=[Security.Cryptography.X509Certificates.X509RevocationMode]::NoCheck",
+    "$chain.ChainPolicy.VerificationFlags=[Security.Cryptography.X509Certificates.X509VerificationFlags]::AllowUnknownCertificateAuthority",
+    "$chain.ChainPolicy.ExtraStore.Add($ca) | Out-Null",
+    "$built=$chain.Build($leaf)",
+    "$root=$null",
+    "if($chain.ChainElements.Count -gt 0) { $root=$chain.ChainElements[$chain.ChainElements.Count-1].Certificate }",
+    `if($built -and ($null -ne $root) -and ($root.Thumbprint -eq $want)) { Write-Output '${TRUST_MARKER}TRUSTED'; exit 0 }`,
+    `Write-Output '${TRUST_MARKER}UNTRUSTED'`,
+    "exit 1",
+    `} catch { Write-Output '${TRUST_MARKER}ERROR'; exit 2 } finally { $store.Close() }`,
+  ].join(";");
+}
+
+/**
+ * Install script: imports the snapshot file into CurrentUser Root after re-checking
+ * its thumbprint inside the script. Adding to Root raises the OS confirmation
+ * dialog and that user approval is the install gate; the powershell.exe process
+ * itself stays hidden and only the OS dialog is ever visible.
+ */
+export function buildWindowsTrustInstallScript(caPath: string, wantSha1: string): string {
+  const want = normalizePickerTrustSha1(wantSha1);
+  if (want === null) throw new Error("picker trust fingerprint must be 40 hex characters");
+  if (caPath.length === 0) throw new Error("picker trust CA path must not be empty");
+  return [
+    "$ErrorActionPreference='Stop'",
+    `$caFile=${encodedPathExpression(caPath)}`,
+    `$want=${psLiteral(want, "picker CA fingerprint")}`,
+    "$cert=New-Object Security.Cryptography.X509Certificates.X509Certificate2($caFile)",
+    `if($cert.Thumbprint -ne $want) { Write-Output '${TRUST_MARKER}ERROR'; exit 2 }`,
+    `$store=${currentUserRootStore()}`,
+    "$store.Open('ReadWrite')",
+    "try {",
+    "$found=@($store.Certificates | Where-Object { $_.Thumbprint -eq $want })",
+    "if($found.Count -eq 0) { $store.Add($cert) }",
+    `Write-Output '${TRUST_MARKER}INSTALLED'`,
+    "exit 0",
+    `} catch { Write-Output '${TRUST_MARKER}ERROR'; exit 2 } finally { $store.Close() }`,
+  ].join(";");
+}
+
+/**
+ * Remove script: verifies picker identity for every exact-thumbprint Root entry before
+ * deleting any of them, then re-checks. Legacy picker roots need not match the new install profile.
+ * Removal from Root raises OS confirmation like an install, so this runs on the
+ * interactive prefix with a bounded 30s budget: predecessor cleanup also runs in headless
+ * removal may prompt, mirroring the macOS keychain prompt on migration cleanup.
+ */
+export function buildWindowsTrustRemoveScript(wantSha1: string): string {
+  const want = normalizePickerTrustSha1(wantSha1);
+  if (want === null) throw new Error("picker trust fingerprint must be 40 hex characters");
+  return [
+    "$ErrorActionPreference='Stop'",
+    `$want=${psLiteral(want, "picker CA fingerprint")}`,
+    `$pickerName=${psLiteral(PICKER_CA_COMMON_NAME, "picker CA common name")}`,
+    "try {",
+    `$store=${currentUserRootStore()}`,
+    "$store.Open('ReadWrite')",
+    "try { $found=@($store.Certificates | Where-Object { $_.Thumbprint -eq $want });",
+    "foreach($c in $found) {",
+    `if($c.GetNameInfo([Security.Cryptography.X509Certificates.X509NameType]::SimpleName,$false) -ne $pickerName) { Write-Output '${TRUST_MARKER}ERROR'; exit 2 }`,
+    "}",
+    "foreach($c in $found) { $store.Remove($c) } } finally { $store.Close() }",
+    `$check=${currentUserRootStore()}`,
+    "$check.Open('ReadOnly')",
+    "try { $left=@($check.Certificates | Where-Object { $_.Thumbprint -eq $want });",
+    `if($left.Count -eq 0) { Write-Output '${TRUST_MARKER}REMOVED'; exit 0 }`,
+    `Write-Output '${TRUST_MARKER}ERROR'; exit 1 } finally { $check.Close() }`,
+    `} catch { Write-Output '${TRUST_MARKER}ERROR'; exit 2 }`,
+  ].join(";");
+}
+
+function powershellArgs(script: string, interactive: boolean): string[] {
+  const prefix = interactive ? WINDOWS_TRUST_POWERSHELL_INTERACTIVE_PREFIX : WINDOWS_TRUST_POWERSHELL_PREFIX;
+  return [...prefix, script];
+}
+
+export async function inspectPickerTrustWindows(
+  leafPath: string,
+  caSha1: string,
+  run?: WindowsTrustRunner,
+): Promise<PickerTrustState> {
+  if (normalizePickerTrustSha1(caSha1) === null || leafPath.length === 0) return "untrusted";
+  const exec = run ?? defaultWindowsPowerShellRunner;
+  try {
+    const result = await exec(powershellArgs(buildWindowsTrustInspectScript(leafPath, caSha1), false), {
+      timeoutMs: WINDOWS_TRUST_INSPECT_TIMEOUT_MS,
+    });
+    if (result.code === 0 && markerOf(result.stdout) === "TRUSTED") return "trusted";
+    if (result.code === 1 && markerOf(result.stdout) === "UNTRUSTED") return "untrusted";
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+export async function trustPickerCaWindows(
+  caPath: string,
+  run?: WindowsTrustRunner,
+  cert?: { pem?: string },
+): Promise<{ ok: boolean; reason?: "unsupported" | "declined_or_failed" }> {
+  // The caller gates this on explicit activation; status and restart paths never call it.
+  // The installed bytes are always a private snapshot of the authority authorized here,
+  // never the shared ca.pem a same-user process could swap mid-flight.
+  const exec = run ?? defaultWindowsPowerShellRunner;
+  let privateDir: string | undefined;
+  try {
+    let pem = cert?.pem;
+    if (pem === undefined) pem = readFileSync(caPath, "utf8");
+    if (!acceptsPickerAuthority(pem)) return { ok: false, reason: "declined_or_failed" };
+    const { sha1 } = pickerCaFingerprints(pem);
+    privateDir = mkdtempSync(join(tmpdir(), "ocx-picker-ca-win-"));
+    const snapshot = join(privateDir, "ca.pem");
+    writeFileSync(snapshot, pem, { mode: 0o600 });
+    const result = await exec(powershellArgs(buildWindowsTrustInstallScript(snapshot, sha1), true), {
+      timeoutMs: WINDOWS_TRUST_IMPORT_TIMEOUT_MS,
+    });
+    return result.code === 0 && markerOf(result.stdout) === "INSTALLED"
+      ? { ok: true }
+      : { ok: false, reason: "declined_or_failed" };
+  } catch {
+    return { ok: false, reason: "declined_or_failed" };
+  } finally {
+    if (privateDir !== undefined) rmSync(privateDir, { recursive: true, force: true });
+  }
+}
+
+export async function untrustPickerCaWindows(
+  fingerprintSha1: string,
+  run?: WindowsTrustRunner,
+  cert?: { pem: string },
+): Promise<{ ok: boolean }> {
+  const exec = run ?? defaultWindowsPowerShellRunner;
+  if (normalizePickerTrustSha1(fingerprintSha1) === null) return { ok: false };
+  try {
+    // Public recovery state is not removal authority. Accept legacy picker roots,
+    // but reject foreign certificates before invoking even an injected runner.
+    if (cert) {
+      const root = new X509Certificate(cert.pem);
+      const names = root.subject.split("\n");
+      if (!root.ca || !names.includes(`CN=${PICKER_CA_COMMON_NAME}`)
+        || names.filter(name => name.startsWith("CN=")).length !== 1
+        || root.issuer !== root.subject || !root.verify(root.publicKey)
+        || pickerCaFingerprints(cert.pem).sha1 !== normalizePickerTrustSha1(fingerprintSha1)) return { ok: false };
+    }
+    const result = await exec(powershellArgs(buildWindowsTrustRemoveScript(fingerprintSha1), true), {
+      timeoutMs: WINDOWS_TRUST_UNTRUST_TIMEOUT_MS,
+    });
+    return result.code === 0 && markerOf(result.stdout) === "REMOVED" ? { ok: true } : { ok: false };
+  } catch {
+    return { ok: false };
+  }
+}

package/src/claude/intercept/picker-trust.ts

@@ -2,6 +2,11 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { PICKER_CA_COMMON_NAME, PICKER_HOST } from "./picker-ca";
+import {
+  inspectPickerTrustWindows,
+  trustPickerCaWindows,
+  untrustPickerCaWindows,
+} from "./picker-trust-windows";
 
 /** Trust is scoped to the current root fingerprint and a verified persisted leaf. */
 export type PickerTrustState = "trusted" | "untrusted" | "unsupported" | "unknown";
@@ -61,6 +66,11 @@ export async function inspectPickerTrust(
   run: SecurityRunner = defaultSecurityRunner,
   platform: NodeJS.Platform = process.platform,
 ): Promise<PickerTrustState> {
+  if (platform === "win32") {
+    // The macOS default runner is never passed down: only an explicitly injected
+    // runner crosses over, otherwise the Windows default powershell.exe runner runs.
+    return inspectPickerTrustWindows(leafPath, caSha1, run === defaultSecurityRunner ? undefined : run);
+  }
   if (platform !== "darwin") return "unsupported";
   const keychain = loginKeychainPath();
   try {
@@ -86,6 +96,9 @@ export async function trustPickerCa(
   platform: NodeJS.Platform = process.platform,
   cert?: { pem?: string },
 ): Promise<{ ok: boolean; reason?: "unsupported" | "declined_or_failed" }> {
+  if (platform === "win32") {
+    return trustPickerCaWindows(caPath, run === defaultSecurityRunner ? undefined : run, cert);
+  }
   if (platform !== "darwin") return { ok: false, reason: "unsupported" };
   // `cert.pem` is the caller-verified certificate bytes: the shared on-disk ca.pem is writable by
   // same-user processes and could be swapped between fingerprint inspection and this install, so
@@ -117,6 +130,12 @@ export async function untrustPickerCa(
   run: SecurityRunner = defaultSecurityRunner,
   platform: NodeJS.Platform = process.platform,
 ): Promise<{ ok: boolean }> {
+  if (platform === "win32") {
+    try {
+      return await untrustPickerCaWindows(fingerprintSha1, run === defaultSecurityRunner ? undefined : run,
+        { pem: readFileSync(caPath, "utf8") });
+    } catch { return { ok: false }; }
+  }
   if (platform !== "darwin") return { ok: false };
   const keychain = loginKeychainPath();
   // Listed means the current picker CA is in the login keychain; unlisted means nothing to remove,

package/src/claude/intercept/port-policy.ts

@@ -0,0 +1,30 @@
+import type { OcxConfig } from "../../types";
+
+/**
+ * Port and enablement policy for the Claude intercept pair.
+ *
+ * These are pure functions of config, with no listener, CA, or picker dependency. They live
+ * apart from `./runtime` because the first-party Desktop path reads them too: importing them
+ * from `./runtime` made `desktop-first-party` reach the picker runtime, which reaches
+ * `desktop-first-party` back. Keeping the policy in a leaf keeps that pair acyclic.
+ */
+
+export const CLAUDE_INTERCEPT_PORT_OFFSET = 100;
+
+export function claudeInterceptEnabled(config: Pick<OcxConfig, "claudeCode" | "runtimeRole">): boolean {
+  if (config.runtimeRole === "client") return false;
+  if (config.claudeCode?.enabled === false) return false;
+  return config.claudeCode?.intercept?.enabled !== false;
+}
+
+export function claudeInterceptProxyPort(config: Pick<OcxConfig, "claudeCode">, publicPort: number): number {
+  const configured = config.claudeCode?.intercept?.port;
+  if (typeof configured === "number" && Number.isInteger(configured) && configured >= 1 && configured <= 65535) return configured;
+  return publicPort + CLAUDE_INTERCEPT_PORT_OFFSET;
+}
+
+/** Desktop's egress proxy for picker mode: the port after the intercept proxy (before it at 65535). */
+export function claudePickerProxyPort(config: Pick<OcxConfig, "claudeCode">, publicPort: number): number {
+  const interceptPort = claudeInterceptProxyPort(config, publicPort);
+  return interceptPort < 65535 ? interceptPort + 1 : interceptPort - 1;
+}