@remodex/rmx 1.0.2

package/src/server/system-env.ts

@@ -0,0 +1,418 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config";
+import { resolveAutoContext, type AutoContextMode } from "../claude/context-windows";
+import { PROXY_MARKER, defaultAuthDetectDeps, detectClaudeAuth, ownAdmissionTokens } from "../claude/auth-detect";
+import { resolveClaudeAuthMode } from "../claude/auth-mode";
+import type { OcxConfig } from "../types";
+import { recordOwnedConfigPath } from "../lib/config-ownership";
+
+/**
+ * Does the Remodex dummy marker belong in the system environment?
+ *
+ * Keyed on the SAME resolver `rmx claude` uses, so an auto config with no Claude auth
+ * also reaches plain `claude` launches — before this, auto-absent users got nothing
+ * from auto-connect and the feature looked broken for exactly the people it helps
+ * (devlog 260726_claude_auth_auto/035).
+ *
+ * NOTE this is a SNAPSHOT: the file only changes when this runs (proxy start, `ocx
+ * ensure`, or a settings save). `rmx claude` re-resolves live on every launch.
+ */
+function systemEnvMarkerMode(config: OcxConfig): "proxy" | "subscription" {
+  return resolveClaudeAuthMode(config, detectClaudeAuth(defaultAuthDetectDeps(process.env, ownAdmissionTokens(config)))).markerMode;
+}
+
+// ---------------------------------------------------------------------------
+// Shell-hook env file: written on inject, sourced by the shell hook in .zshrc.
+// This works for ALL new shells immediately, unlike launchctl setenv which only
+// reaches processes launched directly by launchd (not Terminal.app children).
+// ---------------------------------------------------------------------------
+
+export function getShellEnvFilePath(): string {
+  return join(getConfigDir(), "claude-env.sh");
+}
+
+function shellValue(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+function writeShellEnvFile(port: number, config: OcxConfig, modelEnv: Record<string, string> = {}, auto?: AutoContextMode): void {
+  const lines = [
+    `# Generated by Remodex — do not edit manually`,
+    `export ANTHROPIC_BASE_URL=${shellValue(`http://127.0.0.1:${port}`)}`,
+    `export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=${shellValue("1")}`,
+  ];
+  // New lever keys are CONDITIONAL exports (audit 139 R2#1): a value the user already
+  // exported in their shell wins even though launchctl knows nothing about it.
+  const conditional = (name: string, value: string) =>
+    `[ -z "\${${name}+x}" ] && export ${name}=${shellValue(value)}`;
+  if (config.apiKeys?.length) {
+    lines.push(`export ANTHROPIC_AUTH_TOKEN=${shellValue(config.apiKeys[0].key)}`);
+  } else if (systemEnvMarkerMode(config) === "proxy") {
+    lines.push(conditional("ANTHROPIC_AUTH_TOKEN", PROXY_MARKER));
+  }
+  // Model slots (default + tiers + legacy small-fast) with [1m] applied (devlog 260712 B2).
+  if (modelEnv.ANTHROPIC_MODEL) {
+    lines.push(`export ANTHROPIC_MODEL=${shellValue(modelEnv.ANTHROPIC_MODEL)}`);
+  } else if (config.claudeCode?.model) {
+    lines.push(`export ANTHROPIC_MODEL=${shellValue(config.claudeCode.model)}`);
+  }
+  for (const [name, value] of Object.entries(modelEnv)) {
+    if (name === "ANTHROPIC_MODEL") continue;
+    lines.push(conditional(name, value));
+  }
+  const maxCtx = config.claudeCode?.maxContextTokens;
+  if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) {
+    lines.push(conditional("CLAUDE_CODE_MAX_CONTEXT_TOKENS", String(Math.floor(maxCtx))));
+    lines.push(conditional("DISABLE_COMPACT", "1"));
+  }
+  // Auto-context (devlog 260712 020): same contract as `rmx claude` / launchctl.
+  const autoShell = auto ?? resolveAutoContext(config.claudeCode);
+  if (autoShell.enabled) lines.push(conditional("CLAUDE_CODE_AUTO_COMPACT_WINDOW", String(autoShell.compactWindow)));
+  if (config.claudeCode?.alwaysEnableEffort === true) {
+    lines.push(conditional("CLAUDE_CODE_ALWAYS_ENABLE_EFFORT", "1"));
+  }
+  const shellEnvPath = getShellEnvFilePath();
+  recordOwnedConfigPath(getConfigDir(), shellEnvPath);
+  mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
+  writeFileSync(shellEnvPath, lines.join("\n") + "\n", { encoding: "utf8", mode: 0o600 });
+}
+
+function removeShellEnvFile(): void {
+  try { unlinkSync(getShellEnvFilePath()); } catch { /* already gone */ }
+}
+
+// ---------------------------------------------------------------------------
+// .zshrc hook auto-install: adds a one-liner that sources claude-env.sh.
+// Idempotent — skips if the hook line already exists.
+// ---------------------------------------------------------------------------
+
+const SHELL_HOOK_MARKER = "# Remodex claude-env hook";
+const LEGACY_SHELL_HOOK_MARKER = "# opencodex claude-env hook";
+const SHELL_HOOK_LINE = `${SHELL_HOOK_MARKER}\n[ -f ~/.remodex/claude-env.sh ] && source ~/.remodex/claude-env.sh`;
+
+export function installShellHook(): { installed: boolean; reason?: string } {
+  if (process.platform !== "darwin") return { installed: false, reason: "not macOS" };
+  const home = process.env.HOME;
+  if (!home) return { installed: false, reason: "no HOME" };
+  const zshrcPath = join(home, ".zshrc");
+  try {
+    let content = "";
+    try { content = readFileSync(zshrcPath, "utf8"); } catch { /* file doesn't exist yet */ }
+    if (content.includes(SHELL_HOOK_MARKER) || content.includes(LEGACY_SHELL_HOOK_MARKER)) {
+      return { installed: false, reason: "already installed" };
+    }
+    const addition = `\n${SHELL_HOOK_LINE}\n`;
+    writeFileSync(zshrcPath, content + addition, { encoding: "utf8", mode: 0o644 });
+    return { installed: true };
+  } catch (err) {
+    return { installed: false, reason: `write failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+export function uninstallShellHook(): { removed: boolean; reason?: string } {
+  if (process.platform !== "darwin") return { removed: false, reason: "not macOS" };
+  const home = process.env.HOME;
+  if (!home) return { removed: false, reason: "no HOME" };
+  const zshrcPath = join(home, ".zshrc");
+  try {
+    const content = readFileSync(zshrcPath, "utf8");
+    if (!content.includes(SHELL_HOOK_MARKER) && !content.includes(LEGACY_SHELL_HOOK_MARKER)) {
+      return { removed: false, reason: "not installed" };
+    }
+    // Remove the hook block (marker line + source line + surrounding newlines)
+    const cleaned = content.replace(/\n?# (?:Remodex|opencodex) claude-env hook\n\[.*claude-env\.sh.*\n?/g, "\n");
+    writeFileSync(zshrcPath, cleaned, { encoding: "utf8", mode: 0o644 });
+    return { removed: true };
+  } catch {
+    return { removed: false, reason: "read/write failed" };
+  }
+}
+
+const SYSTEM_ENV_NAMES = [
+  "ANTHROPIC_BASE_URL",
+  "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY",
+  "ANTHROPIC_AUTH_TOKEN",
+] as const;
+
+const MANAGED_SYSTEM_ENV_NAMES = new Set<string>([
+  ...SYSTEM_ENV_NAMES,
+  "ANTHROPIC_DEFAULT_OPUS_MODEL",
+  "ANTHROPIC_DEFAULT_SONNET_MODEL",
+  "ANTHROPIC_DEFAULT_FABLE_MODEL",
+  "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+  "ANTHROPIC_SMALL_FAST_MODEL",
+  "CLAUDE_CODE_MAX_CONTEXT_TOKENS",
+  "DISABLE_COMPACT",
+  "CLAUDE_CODE_AUTO_COMPACT_WINDOW",
+  "CLAUDE_CODE_ALWAYS_ENABLE_EFFORT",
+]);
+
+interface SystemEnvTracking {
+  pid: number;
+  port: number;
+  injectedAt: string;
+  /** Keys that were actually set by injection (revert only unsets these). */
+  injectedKeys?: string[];
+}
+
+type SystemEnvResult = { injected: boolean; reason?: string };
+type RevertResult = { reverted: boolean; reason?: string };
+type CleanupResult = { cleaned: boolean; reason?: string };
+
+export function getSystemEnvTrackingPath(): string {
+  return join(getConfigDir(), "system-env-port");
+}
+
+export function launchctlGetenv(name: string): string | undefined {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) return undefined;
+  try {
+    const value = execFileSync("/bin/launchctl", ["getenv", name], { encoding: "utf8" }).trim();
+    return value || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function readTracking(): SystemEnvTracking | undefined {
+  try {
+    const tracking = JSON.parse(readFileSync(getSystemEnvTrackingPath(), "utf8")) as Partial<SystemEnvTracking>;
+    if (!Number.isInteger(tracking.port) || typeof tracking.pid !== "number" || typeof tracking.injectedAt !== "string") {
+      return undefined;
+    }
+    const injectedKeys = Array.isArray(tracking.injectedKeys)
+      ? [...new Set(tracking.injectedKeys.filter(
+        (name): name is string => typeof name === "string" && MANAGED_SYSTEM_ENV_NAMES.has(name),
+      ))]
+      : undefined;
+    return { ...tracking, injectedKeys } as SystemEnvTracking;
+  } catch {
+    return undefined;
+  }
+}
+
+function setLaunchctlEnv(name: string, value: string): void {
+  execFileSync("/bin/launchctl", ["setenv", name, value]);
+}
+
+function unsetLaunchctlEnv(name: string): void {
+  execFileSync("/bin/launchctl", ["unsetenv", name]);
+}
+
+function ownedBaseUrl(port: number): string {
+  return `http://127.0.0.1:${port}`;
+}
+
+function writeTracking(port: number, injectedKeys: string[]): void {
+  recordOwnedConfigPath(getConfigDir(), getSystemEnvTrackingPath());
+  mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
+  writeFileSync(getSystemEnvTrackingPath(), JSON.stringify({
+    pid: process.pid,
+    port,
+    injectedAt: new Date().toISOString(),
+    injectedKeys,
+  }), { encoding: "utf8", mode: 0o600 });
+}
+
+function rollbackInjectedKeys(port: number, injectedKeys: string[]): void {
+  const rollbackFailed: string[] = [];
+  for (const name of [...injectedKeys].reverse()) {
+    try {
+      unsetLaunchctlEnv(name);
+    } catch {
+      rollbackFailed.unshift(name);
+    }
+  }
+
+  if (rollbackFailed.length > 0) {
+    writeTracking(port, rollbackFailed);
+    return;
+  }
+
+  try { unlinkSync(getSystemEnvTrackingPath()); } catch { /* already gone */ }
+}
+
+/**
+ * In-process effective model-env (default + tier slots, [1m] applied) under the shared
+ * 3s bound (audit R4#3). Returns {} on timeout/failure so injection degrades safely.
+ */
+async function computeEffectiveModelEnv(config: OcxConfig, auto?: AutoContextMode): Promise<{ modelEnv: Record<string, string>; windows: Record<string, number> }> {
+  const { boundedContextWindows, buildClaudeContextWindows, effectiveModelEnv } = await import("../claude/context-windows");
+  const windows = await boundedContextWindows(async () => {
+    const { gatherRoutedModels, visibleNativeSlugs } = await import("../codex/catalog");
+    try {
+      return buildClaudeContextWindows([...visibleNativeSlugs(config)], await gatherRoutedModels(config));
+    } catch (error) {
+      if (error && typeof error === "object" && (error as { code?: unknown }).code === "catalog_busy") {
+        return buildClaudeContextWindows([...visibleNativeSlugs(config)], []);
+      }
+      throw error;
+    }
+  });
+  return { modelEnv: effectiveModelEnv(config.claudeCode, windows ?? {}, auto), windows: windows ?? {} };
+}
+
+export async function injectSystemEnv(port: number, config: OcxConfig): Promise<SystemEnvResult> {
+  if (process.platform !== "darwin") return { injected: false, reason: "not macOS" };
+  if (config.claudeCode?.enabled === false) return { injected: false, reason: "claude disabled" };
+
+  // Default OFF — only inject when explicitly enabled by the user.
+  if (config.claudeCode?.systemEnv !== true) return { injected: false, reason: "systemEnv disabled" };
+
+  await cleanStaleSystemEnv();
+
+  const currentBaseUrl = launchctlGetenv("ANTHROPIC_BASE_URL");
+  if (currentBaseUrl && !/^http:\/\/127\.0\.0\.1:\d+$/.test(currentBaseUrl)) {
+    return { injected: false, reason: "user has custom ANTHROPIC_BASE_URL" };
+  }
+  // After stale cleanup, if a tracking file still exists with a DIFFERENT port,
+  // another live instance owns the env — don't overwrite it.
+  const existingTracking = readTracking();
+  if (existingTracking && existingTracking.port !== port) {
+    return { injected: false, reason: `another instance owns env (port ${existingTracking.port})` };
+  }
+
+  const injectedKeys: string[] = existingTracking
+    ? [...(existingTracking.injectedKeys ?? SYSTEM_ENV_NAMES)]
+    : [];
+  const inject = (name: string, value: string) => {
+    setLaunchctlEnv(name, value);
+    if (!injectedKeys.includes(name)) injectedKeys.push(name);
+    writeTracking(port, injectedKeys);
+  };
+
+  try {
+    inject("ANTHROPIC_BASE_URL", ownedBaseUrl(port));
+    inject("CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "1");
+    if (config.apiKeys?.length) {
+      inject("ANTHROPIC_AUTH_TOKEN", config.apiKeys[0].key);
+    } else if (systemEnvMarkerMode(config) === "proxy" && launchctlGetenv("ANTHROPIC_AUTH_TOKEN") === undefined) {
+      inject("ANTHROPIC_AUTH_TOKEN", PROXY_MARKER);
+    } else if (systemEnvMarkerMode(config) !== "proxy"
+      && injectedKeys.includes("ANTHROPIC_AUTH_TOKEN")
+      && launchctlGetenv("ANTHROPIC_AUTH_TOKEN") === PROXY_MARKER) {
+      // Subscription switch-back (devlog 260720_claude_authmode_persist): remove ONLY
+      // the Remodex-owned dummy token so a launchd-started Claude regains its own
+      // claude.ai OAuth. User-set tokens (not tracked in injectedKeys, or carrying a
+      // different value) are never touched.
+      unsetLaunchctlEnv("ANTHROPIC_AUTH_TOKEN");
+      const dummyIdx = injectedKeys.indexOf("ANTHROPIC_AUTH_TOKEN");
+      if (dummyIdx >= 0) injectedKeys.splice(dummyIdx, 1);
+      writeTracking(port, injectedKeys);
+    }
+    // Lever keys (devlog 136 B6): user-wins — skip any key the user already set in the
+    // launchd domain, and track ONLY the keys we actually injected so revert cannot
+    // delete a pre-existing user value (audit 139 #3).
+    const injectLever = (name: string, value: string) => {
+      if (launchctlGetenv(name) !== undefined) return;
+      inject(name, value);
+    };
+    // Model slots (default + tier defaults + legacy small-fast) with [1m] auto-marking
+    // (devlog 260712 B2, audit R2#3/R4#3): in-process context-window computation under
+    // the same 3s bound; on timeout the tier keys are simply not injected this run.
+    // Auto-context: a user-owned launchd value drives the marking predicate so the
+    // marker and threshold never separate (audit 021 #2); injectLever's user-wins
+    // check below keeps that value untouched.
+    const userAutoCompact = launchctlGetenv("CLAUDE_CODE_AUTO_COMPACT_WINDOW");
+    const auto = resolveAutoContext(config.claudeCode, userAutoCompact);
+    const { modelEnv, windows } = await computeEffectiveModelEnv(config, auto);
+    for (const [name, value] of Object.entries(modelEnv)) {
+      if (name === "ANTHROPIC_MODEL") continue; // legacy slot handled by shell file only (back-compat)
+      injectLever(name, value);
+    }
+    const maxCtx = config.claudeCode?.maxContextTokens;
+    if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) {
+      injectLever("CLAUDE_CODE_MAX_CONTEXT_TOKENS", String(Math.floor(maxCtx)));
+      injectLever("DISABLE_COMPACT", "1");
+    }
+    // Auto-context (devlog 260712 020): user-wins lever, inert when maxContextTokens set.
+    if (auto.enabled) injectLever("CLAUDE_CODE_AUTO_COMPACT_WINDOW", String(auto.compactWindow));
+    if (config.claudeCode?.alwaysEnableEffort === true) {
+      injectLever("CLAUDE_CODE_ALWAYS_ENABLE_EFFORT", "1");
+    }
+
+    // Shell-hook env file: works for new shells in already-running Terminal.app.
+    writeShellEnvFile(port, config, modelEnv, auto);
+
+    // Gateway-model cache pre-write (devlog 030): plain `claude` sessions read the
+    // picker list from ~/.claude/cache/gateway-models.json and cannot refresh it
+    // without a token — keep it in sync with this proxy's /v1/models. Best-effort.
+    try {
+      const { refreshGatewayModelCacheFromProxy } = await import("../claude/gateway-cache");
+      await refreshGatewayModelCacheFromProxy(port);
+    } catch { /* best-effort */ }
+
+    // Roster agent definitions (devlog 070): same launch-time sync for plain `claude`.
+    // Reuses the window map computed above (audit 071 #5 — no second acquisition).
+    try {
+      const { injectClaudeAgentDefs } = await import("../claude/agents-inject");
+      injectClaudeAgentDefs(config, windows);
+    } catch { /* best-effort */ }
+
+    writeTracking(port, injectedKeys);
+  } catch (error) {
+    rollbackInjectedKeys(port, injectedKeys);
+    removeShellEnvFile();
+    console.error("Failed to inject system environment; rolled back launchctl changes:", error);
+    throw error;
+  }
+
+  return { injected: true };
+}
+
+export async function applySystemEnvToggle(config: OcxConfig, port: number): Promise<SystemEnvResult | RevertResult> {
+  if (config.claudeCode?.systemEnv === true) return injectSystemEnv(port, config);
+  return revertSystemEnv();
+}
+
+export function revertSystemEnv(): RevertResult {
+  if (process.platform !== "darwin") return { reverted: false, reason: "not macOS" };
+
+  const tracking = readTracking();
+  if (!tracking) return { reverted: false, reason: "no tracking file" };
+
+  try {
+    const tracksBaseUrl = tracking.injectedKeys?.includes("ANTHROPIC_BASE_URL") ?? true;
+    if (tracksBaseUrl && launchctlGetenv("ANTHROPIC_BASE_URL") !== ownedBaseUrl(tracking.port)) {
+      return { reverted: false, reason: "ownership mismatch" };
+    }
+
+    // Only unset keys that were actually injected (preserves pre-existing user tokens).
+    const keysToUnset = tracking.injectedKeys ?? SYSTEM_ENV_NAMES as unknown as string[];
+    for (const name of keysToUnset) {
+      try {
+        unsetLaunchctlEnv(name);
+      } catch {
+        // Continue removing the remaining variables during shutdown.
+      }
+    }
+    removeShellEnvFile();
+    try {
+      unlinkSync(getSystemEnvTrackingPath());
+    } catch {
+      // The environment was reverted even if the tracking file disappeared concurrently.
+    }
+    return { reverted: true };
+  } catch {
+    return { reverted: false, reason: "revert failed" };
+  }
+}
+
+export async function cleanStaleSystemEnv(): Promise<CleanupResult> {
+  const tracking = readTracking();
+  if (!tracking) return { cleaned: false, reason: "no tracking file" };
+
+  try {
+    const response = await fetch(`${ownedBaseUrl(tracking.port)}/healthz`, {
+      signal: AbortSignal.timeout(1_000),
+    });
+    if (response.ok) return { cleaned: false, reason: "proxy still alive" };
+  } catch {
+    // A failed or timed-out health check means the tracked proxy is stale.
+  }
+
+  const reverted = revertSystemEnv();
+  if (!reverted.reverted) return { cleaned: false, reason: reverted.reason };
+  return { cleaned: true };
+}

package/src/server/windows-tcp-drop.ts

@@ -0,0 +1,184 @@
+/**
+ * Soft SIGTERM-before-/F is NOT available on Windows (process.kill is TerminateProcess).
+ * Graceful drain is stopProxyGracefully(); this module only resets leftover TCBs after hard kill.
+ */
+import { dlopen, ptr, type Pointer } from "bun:ffi";
+import { execFileSync } from "node:child_process";
+
+export type TcpQuad = {
+  localAddr: string;
+  localPort: number;
+  remoteAddr: string;
+  remotePort: number;
+  state: string;
+};
+
+/** Parse netstat -ano rows whose local address uses `port`. Exported for tests. */
+export function parseTcpQuadsForLocalPort(output: string, port: number): TcpQuad[] {
+  const rows: TcpQuad[] = [];
+  const portSuffix = `:${port}`;
+  for (const rawLine of output.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!/^TCP\b/i.test(line)) continue;
+    const parts = line.split(/\s+/);
+    if (parts.length < 4) continue;
+    const local = parts[1]!;
+    const remote = parts[2]!;
+    const state = parts[3]!;
+    if (!local.endsWith(portSuffix) && !local.endsWith(`]:${port}`)) continue;
+    const localAddr = stripPort(local, port);
+    const remoteParsed = splitHostPort(remote);
+    if (!localAddr || !remoteParsed) continue;
+    rows.push({
+      localAddr,
+      localPort: port,
+      remoteAddr: remoteParsed.host,
+      remotePort: remoteParsed.port,
+      state,
+    });
+  }
+  return rows;
+}
+
+function stripPort(addr: string, port: number): string | null {
+  const suffix = `:${port}`;
+  if (addr.endsWith(suffix)) return addr.slice(0, -suffix.length).replace(/^\[|\]$/g, "") || "0.0.0.0";
+  return null;
+}
+
+function splitHostPort(addr: string): { host: string; port: number } | null {
+  if (addr === "0.0.0.0:0" || addr === "*:*" || addr === "[::]:0") {
+    return { host: "0.0.0.0", port: 0 };
+  }
+  const m = /^(?:\[([^\]]+)\]|([^:]+)):(\d+)$/.exec(addr);
+  if (!m) return null;
+  return { host: (m[1] ?? m[2] ?? "0.0.0.0").replace(/^::ffff:/i, ""), port: Number(m[3]) };
+}
+
+function ipv4ToWinUint32(addr: string): number | null {
+  const host = addr.replace(/^::ffff:/i, "");
+  // Refuse bare IPv6 — SetTcpEntry is IPv4-only; coercing "::"/"::1" to 0 would
+  // miss the real TCB and can hit an unrelated IPv4 wildcard row.
+  if (isBareIpv6Address(host)) return null;
+  if (host === "0.0.0.0" || host === "*") return 0;
+  const parts = host.split(".").map(Number);
+  if (parts.length !== 4 || parts.some(n => !Number.isInteger(n) || n < 0 || n > 255)) return null;
+  return (parts[0]! | (parts[1]! << 8) | (parts[2]! << 16) | (parts[3]! << 24)) >>> 0;
+}
+
+/** True for bare IPv6 (including :: / ::1), false for dotted IPv4 and IPv4-mapped. */
+export function isBareIpv6Address(addr: string): boolean {
+  const host = String(addr || "").replace(/^\[|\]$/g, "").replace(/^::ffff:/i, "");
+  if (!host) return false;
+  if (/^\d+\.\d+\.\d+\.\d+$/.test(host)) return false;
+  return host.includes(":");
+}
+
+export type WindowsTcpDropResult = {
+  /** Successful SetTcpEntry(DELETE_TCB) calls for IPv4 rows. */
+  dropped: number;
+  /** IPv6 (or unparseable) rows skipped — never coerced into IPv4 wildcards. */
+  skippedIpv6: number;
+  /**
+   * SetTcpEntry returned ERROR_ACCESS_DENIED (5) or the UAC-non-elevated code (317).
+   * On a normal (non-admin) update worker this is expected — ghost LISTEN rows must
+   * clear by waiting for the OS, not by SetTcpEntry.
+   */
+  accessDenied: number;
+};
+
+function htons(port: number): number {
+  return (((port & 0xff) << 8) | ((port >> 8) & 0xff)) >>> 0;
+}
+
+type SetTcpEntryFn = (row: Pointer) => number;
+let setTcpEntryFn: SetTcpEntryFn | null | undefined;
+
+function loadSetTcpEntry(): SetTcpEntryFn | null {
+  if (setTcpEntryFn !== undefined) return setTcpEntryFn;
+  if (process.platform !== "win32") {
+    setTcpEntryFn = null;
+    return null;
+  }
+  try {
+    const lib = dlopen("iphlpapi.dll", {
+      SetTcpEntry: { args: ["ptr"], returns: "u32" },
+    });
+    setTcpEntryFn = (row: Pointer) => lib.symbols.SetTcpEntry(row) as number;
+  } catch {
+    setTcpEntryFn = null;
+  }
+  return setTcpEntryFn;
+}
+
+function readNetstatAno(): string {
+  const netstat = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\netstat.exe`;
+  const cmd = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\cmd.exe`;
+  try {
+    return execFileSync(cmd, ["/d", "/c", `chcp 437>nul & "${netstat}" -ano -p tcp`], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+      windowsHide: true,
+    });
+  } catch {
+    return execFileSync(netstat, ["-ano", "-p", "tcp"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 4000,
+      windowsHide: true,
+    });
+  }
+}
+
+/**
+ * Force-delete IPv4 TCP rows bound to `localPort` via SetTcpEntry(DELETE_TCB).
+ * Does not kill foreign processes — only resets sockets so the listen port can bind again.
+ * Bare IPv6 rows (`::1`, `::`, etc.) are skipped (not coerced into IPv4 wildcards);
+ * IPv6 TCB reclamation is unsupported on this path.
+ */
+export function dropWindowsTcpRowsForLocalPort(port: number): WindowsTcpDropResult {
+  if (process.platform !== "win32" || !Number.isFinite(port) || port <= 0) {
+    return { dropped: 0, skippedIpv6: 0, accessDenied: 0 };
+  }
+  const setTcpEntry = loadSetTcpEntry();
+  if (!setTcpEntry) return { dropped: 0, skippedIpv6: 0, accessDenied: 0 };
+
+  let output = "";
+  try {
+    output = readNetstatAno();
+  } catch {
+    return { dropped: 0, skippedIpv6: 0, accessDenied: 0 };
+  }
+
+  const rows = parseTcpQuadsForLocalPort(output, Math.trunc(port));
+  let dropped = 0;
+  let skippedIpv6 = 0;
+  let accessDenied = 0;
+  for (const row of rows) {
+    const localDw = ipv4ToWinUint32(row.localAddr);
+    const remoteDw = ipv4ToWinUint32(row.remoteAddr);
+    if (localDw === null || remoteDw === null) {
+      if (isBareIpv6Address(row.localAddr) || isBareIpv6Address(row.remoteAddr)) {
+        skippedIpv6 += 1;
+      }
+      continue;
+    }
+    const buf = new ArrayBuffer(20);
+    const view = new DataView(buf);
+    view.setUint32(0, 12, true); // MIB_TCP_STATE_DELETE_TCB
+    view.setUint32(4, localDw, true);
+    view.setUint32(8, htons(row.localPort), true);
+    view.setUint32(12, remoteDw, true);
+    view.setUint32(16, htons(row.remotePort), true);
+    try {
+      const rc = setTcpEntry(ptr(buf));
+      if (rc === 0) dropped += 1;
+      // 5 = ERROR_ACCESS_DENIED, 317 = non-elevated SetTcpEntry (MSDN).
+      else if (rc === 5 || rc === 317) accessDenied += 1;
+    } catch {
+      /* keep going */
+    }
+  }
+  return { dropped, skippedIpv6, accessDenied };
+}

package/src/server/windows-tray-control.ts

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { durableBunPath } from "../lib/bun-runtime";
+import type { WindowsTrayStatus } from "../tray/windows";
+
+export type WindowsTrayAction = "install" | "start" | "stop" | "status" | "uninstall";
+
+/** Run blocking registry/PowerShell waits outside the proxy event loop. */
+export function runWindowsTrayAction(action: WindowsTrayAction): Promise<WindowsTrayStatus> {
+  if (action === "status") {
+    return import("../tray/windows").then(({ getWindowsTrayStatusAsync }) => getWindowsTrayStatusAsync());
+  }
+  const bun = durableBunPath();
+  const cli = join(import.meta.dir, "..", "cli", "index.ts");
+  return new Promise((resolve, reject) => {
+    execFile(bun, [cli, "tray", action, "--json"], {
+      encoding: "utf8",
+      env: process.env,
+      timeout: 30_000,
+      windowsHide: true,
+      maxBuffer: 256 * 1024,
+    }, (error, stdout, stderr) => {
+      const lines = stdout.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+      for (let index = lines.length - 1; index >= 0; index -= 1) {
+        try {
+          const parsed = JSON.parse(lines[index]) as WindowsTrayStatus | { error?: unknown };
+          if ("supported" in parsed && typeof parsed.supported === "boolean") {
+            resolve(parsed);
+            return;
+          }
+          const failure = parsed as { error?: unknown };
+          if (typeof failure.error === "string") {
+            reject(new Error(failure.error));
+            return;
+          }
+        } catch { /* scan earlier lines */ }
+      }
+      reject(new Error(error?.message || stderr.trim() || "Windows tray action returned no status"));
+    });
+  });
+}