@bitkyc08/opencodex 2.10.2 → 2.11.0

package/src/lib/windows-secret-acl.ts

@@ -31,11 +31,20 @@
 
 import { existsSync, statSync } from "node:fs";
 import { env, platform } from "node:process";
+import {
+  resolveCurrentWindowsPrincipal,
+  resolveCurrentWindowsPrincipalAsync,
+  setSyntheticWindowsPrincipalForTests,
+} from "./windows-user-principal";
 
 const hardenedDirectories = new Map<string, HardenedIdentity>();
 const hardenedPaths = new Map<string, HardenedIdentity>();
-/** Paths whose harden TIMED OUT this process: do not re-stall every loadConfig on them. */
-const timedOutPaths = new Set<string>();
+/**
+ * Paths whose harden TIMED OUT this process: do not re-stall every loadConfig on them.
+ * `false` means one explicitly authorized recovery attempt remains; `true` means
+ * that attempt was consumed. Ordinary callers never consume it.
+ */
+const timedOutPaths = new Map<string, boolean>();
 
 /**
  * The memo value: `object:freshness` for a file a harden was actually attributed
@@ -212,6 +221,12 @@ export interface HardenOptions {
    * Must NOT be a parent directory — directory ACLs are not authoritative for new files.
    */
   timeoutMemoKey?: string;
+  /**
+   * Consume the one recovery attempt for a previously timed-out memo key.
+   * Only a caller that owns its own single-flight and bounded retry policy should
+   * set this. It never clears or bypasses an already-consumed timeout memo.
+   */
+  retryTimedOutOnce?: boolean;
 }
 
 /**
@@ -219,9 +234,23 @@ export interface HardenOptions {
  * timeout retry and the diagnostic verification pass (no per-attempt fresh budget:
  * loadConfig hardens dir+config+auth sequentially, so per-attempt budgets stack
  * into multi-minute startup stalls). Override with OPENCODEX_ACL_TIMEOUT_MS
- * (integer ms, clamped to [1000, 60000]; invalid values fall back to 5000).
+ * (integer ms, clamped to [1000, 60000]; invalid values fall back to 30000).
+ *
+ * The default was 5s until #1156. One envelope has to cover the whole sequence —
+ * `/grant:r`, `/inheritance:r`, `/remove:g`, plus the conditional `/findsid`
+ * verification — and on machines where icacls is slow (Defender real-time scanning,
+ * roaming profiles, a domain-controller round trip) 5s ran out mid-sequence. The
+ * harden then failed closed, the native-main owner published a permanent
+ * `unavailable`, and every native request returned 503 until restart. A slow start
+ * is recoverable; that is not.
+ *
+ * The cost is honest and worth stating: because loadConfig hardens three paths
+ * sequentially, the timeout-path worst case at load is ~90s, and the owner path
+ * (initial call + one recovery) is ~60.25s. Both require icacls to be
+ * pathologically slow on every call; a healthy machine finishes in milliseconds
+ * and sees no change. Operators who prefer the old bound can set the env override.
  */
-const HARDEN_DEADLINE_DEFAULT_MS = 5_000;
+const HARDEN_DEADLINE_DEFAULT_MS = 30_000;
 const HARDEN_DEADLINE_MIN_MS = 1_000;
 const HARDEN_DEADLINE_MAX_MS = 60_000;
 
@@ -312,9 +341,21 @@ export function setAsyncIcaclsRunnerForTests(runner: AsyncIcaclsRunner | null):
   asyncIcaclsRunner = runner ?? defaultAsyncIcaclsRunner;
 }
 
-/** Test seam: force the platform gate (e.g. "win32") so CI on POSIX reaches the runner. */
+/**
+ * Test seam: force the platform gate (e.g. "win32") so CI on POSIX reaches the runner.
+ *
+ * Faking win32 on a host without System32 also has to supply a principal, or
+ * every forced-branch test would fail on the identity lookup instead of
+ * exercising icacls. The synthetic value is registered with the resolver, not
+ * chosen here, so a test that injects its own runner still wins.
+ */
+const SYNTHETIC_TEST_PRINCIPAL = "*S-1-5-21-1-2-3-1001";
+
 export function setPlatformForTests(value: string | null): void {
   platformOverride = value;
+  setSyntheticWindowsPrincipalForTests(
+    value === "win32" && platform !== "win32" ? SYNTHETIC_TEST_PRINCIPAL : null,
+  );
 }
 
 /** Test seam: injectable clock for deadline tests (no real sleeps). */
@@ -384,17 +425,26 @@ function icaclsError(step: string, result: IcaclsResult): NodeJS.ErrnoException
 }
 
 /**
- * Return the current Windows username from the environment.
- * Falls back to USERDOMAIN\USERNAME if USERNAME alone is ambiguous.
- * The value is used directly in icacls arguments, so it must be present.
+ * The ACL principal is the effective token SID and nothing else.
+ *
+ * There is no name-shaped fallback here, and that absence is the fix for #1149
+ * rather than an omission. `USERDOMAIN\USERNAME` has the right shape but is not
+ * evidence of the current token's subject, and both variables are writable by
+ * the process that launched us. Granting Full Control to a wrong principal and
+ * then running `/inheritance:r` is destructive in both directions: another
+ * account can be left holding the secret, or the file can be left with no ACE
+ * the current user can use. When the SID cannot be resolved we decline.
+ *
+ * Non-Windows hosts that force this branch through `setPlatformForTests` get
+ * their principal from `setSyntheticWindowsPrincipalForTests`, which lives with
+ * the resolver so an injected runner can still take precedence over it.
  */
-function currentWindowsUser(): string | undefined {
-  const username = env["USERNAME"];
-  const domain = env["USERDOMAIN"];
-  if (!username) return undefined;
-  // USERDOMAIN is the machine/domain name; USERNAME is the account name.
-  // icacls accepts "DOMAIN\User" or just "User" for local accounts.
-  return domain ? `${domain}\\${username}` : username;
+function currentWindowsPrincipal(deadline: number): string {
+  return resolveCurrentWindowsPrincipal(deadline - nowFn());
+}
+
+async function currentWindowsPrincipalAsync(deadline: number): Promise<string> {
+  return resolveCurrentWindowsPrincipalAsync(deadline - nowFn());
 }
 
 /**
@@ -414,10 +464,7 @@ function grantAce(user: string, directory: boolean): string {
 }
 
 function runIcacls(targetPath: string, directory: boolean, deadline: number): void {
-  const user = currentWindowsUser();
-  if (!user) {
-    throw new Error("Cannot determine current Windows user for ACL hardening");
-  }
+  const principal = currentWindowsPrincipal(deadline);
 
   // The deadline is owned by hardenEntry (total budget incl. retry + verification).
   const run = (step: string, args: string[]): IcaclsResult => {
@@ -434,7 +481,7 @@ function runIcacls(targetPath: string, directory: boolean, deadline: number): vo
 
   // Step 1: grant current user full control BEFORE any destructive ACL change.
   // If this fails, inheritance is untouched and the writer keeps inherited access.
-  runOrThrow("/grant:r", [targetPath, "/grant:r", grantAce(user, directory)]);
+  runOrThrow("/grant:r", [targetPath, "/grant:r", grantAce(principal, directory)]);
 
   // Step 2: disable inheritance and remove inherited ACEs. The explicit owner ACE
   // from step 1 survives this transition, so a later failure still leaves cleanup access.
@@ -463,10 +510,7 @@ function runIcacls(targetPath: string, directory: boolean, deadline: number): vo
 
 /** Async counterpart of runIcacls — same step order and timeout/error classification (#612). */
 async function runIcaclsAsync(targetPath: string, directory: boolean, deadline: number): Promise<void> {
-  const user = currentWindowsUser();
-  if (!user) {
-    throw new Error("Cannot determine current Windows user for ACL hardening");
-  }
+  const principal = await currentWindowsPrincipalAsync(deadline);
 
   const run = async (step: string, args: string[]): Promise<IcaclsResult> => {
     const remaining = deadline - nowFn();
@@ -480,7 +524,7 @@ async function runIcaclsAsync(targetPath: string, directory: boolean, deadline:
     if (!result.success) throw icaclsError(step, result);
   };
 
-  await runOrThrow("/grant:r", [targetPath, "/grant:r", grantAce(user, directory)]);
+  await runOrThrow("/grant:r", [targetPath, "/grant:r", grantAce(principal, directory)]);
   await runOrThrow("/inheritance:r", [targetPath, "/inheritance:r"]);
 
   const removal = await run("/remove:g", [targetPath, "/remove:g", ...BROAD_SIDS]);
@@ -514,6 +558,8 @@ function sanitizeDiagnostics(error: unknown): string {
       return `ACL hardening failed (${code}) — permission denied running icacls`;
     case "EICACLS":
       return "ACL hardening failed (EICACLS) — icacls command error; filesystem may not support per-user NTFS ACLs";
+    case "EACLIDENTITY":
+      return "ACL hardening failed (EACLIDENTITY) — the effective Windows account SID could not be resolved";
     default:
       return `ACL hardening failed${code ? ` (${code})` : ""} — filesystem may not support per-user NTFS ACLs`;
   }
@@ -524,6 +570,60 @@ function isTimeoutError(error: unknown): boolean {
     && String((error as NodeJS.ErrnoException).code) === "ETIMEDOUT";
 }
 
+/** Preserve only the bounded machine-readable cause on a sanitized public error. */
+function sanitizedAclError(diagnostics: string, cause: unknown): NodeJS.ErrnoException {
+  const error = new Error(diagnostics) as NodeJS.ErrnoException;
+  const code = cause && typeof cause === "object" && "code" in cause
+    ? String((cause as { code?: unknown }).code)
+    : "";
+  // EACLIDENTITY belongs here for the same reason as the rest: a caller that
+  // catches a required-mode failure has to tell "the SID could not be resolved"
+  // apart from "icacls stalled". Without it the code was dropped and only the
+  // message carried the cause, which no caller can branch on.
+  if (
+    code === "ETIMEDOUT" ||
+    code === "EICACLS" ||
+    code === "EACCES" ||
+    code === "EPERM" ||
+    code === "EACLIDENTITY"
+  ) {
+    error.code = code;
+  }
+  return error;
+}
+
+function previousTimeoutError(retryConsumed: boolean): NodeJS.ErrnoException {
+  if (retryConsumed) {
+    const error = new Error(
+      "ACL hardening skipped — the previous timeout recovery was already consumed",
+    ) as NodeJS.ErrnoException;
+    error.code = "EACLRETRYEXHAUSTED";
+    return error;
+  }
+  return sanitizedAclError(
+    "ACL hardening skipped — previous attempt timed out",
+    Object.assign(new Error("timeout"), { code: "ETIMEDOUT" }),
+  );
+}
+
+/** Consume, but never reset, the single explicit recovery attempt for this key. */
+function timeoutMemoErrorIfBlocked(
+  memoKey: string,
+  opts: HardenOptions,
+): NodeJS.ErrnoException | null {
+  const retryConsumed = timedOutPaths.get(memoKey);
+  if (retryConsumed === undefined) return null;
+  if (opts.retryTimedOutOnce && retryConsumed === false) {
+    timedOutPaths.set(memoKey, true);
+    return null;
+  }
+  return previousTimeoutError(retryConsumed);
+}
+
+function recordTimeout(memoKey: string): void {
+  if (!timedOutPaths.has(memoKey)) timedOutPaths.set(memoKey, false);
+}
+
 /**
  * Diagnostic-only post-timeout probe (never promotes to ok:true — a clean /findsid
  * does not prove inheritance was disabled or the user grant ran; only a fully
@@ -588,10 +688,10 @@ function hardenEntry(
   if (effectivePlatform() !== "win32") return { ok: true };
   if (memoSatisfied(cache, targetPath)) return { ok: true };
   const memoKey = timeoutMemoKey(targetPath, opts);
-  if (timedOutPaths.has(memoKey)) {
-    const diagnostics = "ACL hardening skipped — previous attempt timed out";
-    if (opts.required) throw new Error(diagnostics);
-    return { ok: false, diagnostics };
+  const timeoutMemoError = timeoutMemoErrorIfBlocked(memoKey, opts);
+  if (timeoutMemoError) {
+    if (opts.required) throw timeoutMemoError;
+    return { ok: false, diagnostics: timeoutMemoError.message };
   }
 
   const deadline = nowFn() + resolveHardenDeadlineMs();
@@ -606,6 +706,7 @@ function hardenEntry(
         if (opts.required) throw new Error(SUBSTITUTED_DIAGNOSTIC);
         return { ok: false, diagnostics: SUBSTITUTED_DIAGNOSTIC };
       }
+      timedOutPaths.delete(memoKey);
       return { ok: true };
     } catch (err) {
       // A substitution is not a transient icacls stall; do not spend the retry on it.
@@ -617,14 +718,14 @@ function hardenEntry(
 
   const diagnostics = sanitizeDiagnostics(lastErr);
   if (isTimeoutError(lastErr)) {
-    timedOutPaths.add(memoKey);
+    recordTimeout(memoKey);
     const state = describeAclStateAfterTimeout(targetPath, deadline);
     const annotated = `${diagnostics}; ${state}`;
-    if (opts.required) throw new Error(annotated);
+    if (opts.required) throw sanitizedAclError(annotated, lastErr);
     console.warn(`[opencodex] ${annotated} — continuing without NTFS ACL harden`);
     return { ok: false, diagnostics: annotated };
   }
-  if (opts.required) throw new Error(diagnostics);
+  if (opts.required) throw sanitizedAclError(diagnostics, lastErr);
   return { ok: false, diagnostics };
 }
 
@@ -639,10 +740,10 @@ async function hardenEntryAsync(
   if (effectivePlatform() !== "win32") return { ok: true };
   if (memoSatisfied(cache, targetPath)) return { ok: true };
   const memoKey = timeoutMemoKey(targetPath, opts);
-  if (timedOutPaths.has(memoKey)) {
-    const diagnostics = "ACL hardening skipped — previous attempt timed out";
-    if (opts.required) throw new Error(diagnostics);
-    return { ok: false, diagnostics };
+  const timeoutMemoError = timeoutMemoErrorIfBlocked(memoKey, opts);
+  if (timeoutMemoError) {
+    if (opts.required) throw timeoutMemoError;
+    return { ok: false, diagnostics: timeoutMemoError.message };
   }
 
   const deadline = nowFn() + resolveHardenDeadlineMs();
@@ -656,6 +757,7 @@ async function hardenEntryAsync(
         if (opts.required) throw new Error(SUBSTITUTED_DIAGNOSTIC);
         return { ok: false, diagnostics: SUBSTITUTED_DIAGNOSTIC };
       }
+      timedOutPaths.delete(memoKey);
       return { ok: true };
     } catch (err) {
       if (err instanceof Error && err.message === SUBSTITUTED_DIAGNOSTIC) throw err;
@@ -666,14 +768,14 @@ async function hardenEntryAsync(
 
   const diagnostics = sanitizeDiagnostics(lastErr);
   if (isTimeoutError(lastErr)) {
-    timedOutPaths.add(memoKey);
+    recordTimeout(memoKey);
     const state = await describeAclStateAfterTimeoutAsync(targetPath, deadline);
     const annotated = `${diagnostics}; ${state}`;
-    if (opts.required) throw new Error(annotated);
+    if (opts.required) throw sanitizedAclError(annotated, lastErr);
     console.warn(`[opencodex] ${annotated} — continuing without NTFS ACL harden`);
     return { ok: false, diagnostics: annotated };
   }
-  if (opts.required) throw new Error(diagnostics);
+  if (opts.required) throw sanitizedAclError(diagnostics, lastErr);
   return { ok: false, diagnostics };
 }
 

package/src/lib/windows-user-principal.ts

@@ -0,0 +1,283 @@
+/**
+ * Resolve the effective Windows token to the locale-independent SID form that
+ * icacls accepts ("*S-1-..."). Environment values such as USERDOMAIN are not
+ * an authority for the current token: on workgroup machines USERDOMAIN may be
+ * the literal WORKGROUP even though the account belongs to the local computer.
+ *
+ * There is deliberately NO name-shaped fallback. A `DOMAIN\User` string has a
+ * valid shape, but shape is not evidence that the account is the current
+ * token's subject, and both environment variables are writable by whatever
+ * launched us. A wrong principal here is not cosmetic: `runIcacls` grants it
+ * Full Control and then removes inheritance, so a wrong grant either leaves a
+ * different account holding the secret or strands the file with no usable ACE.
+ * When the SID cannot be resolved, the caller declines to touch the ACL at all.
+ *
+ * Budget caveat: callers pass their REMAINING harden budget, which becomes the
+ * child process timeout. Trusted-executable resolution (a `GetSystemDirectoryW`
+ * FFI call) and spawn setup happen before that timeout starts, and the async
+ * timer only arms once `Bun.spawn` returns. Both are small in practice, but the
+ * lookup is not bounded by the deadline to the microsecond. Tightening that
+ * would mean passing an absolute deadline through the runner interface.
+ */
+
+import { resolveTrustedWindowsPowerShellExe } from "./windows-elevation";
+
+const SID_PATTERN = /^S-1-(?:\d+-)+\d+$/i;
+const SID_EXPRESSION =
+  "[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value";
+
+export interface WindowsPrincipalLookupResult {
+  success: boolean;
+  exitCode: number | null;
+  timedOut: boolean;
+  stdout: string;
+}
+
+export type WindowsPrincipalRunner = (
+  timeoutMs: number,
+) => WindowsPrincipalLookupResult;
+
+export type AsyncWindowsPrincipalRunner = (
+  timeoutMs: number,
+) => Promise<WindowsPrincipalLookupResult>;
+
+const POWERSHELL_ARGS = [
+  "-NoLogo",
+  "-NoProfile",
+  "-NonInteractive",
+  "-WindowStyle",
+  "Hidden",
+  "-Command",
+  SID_EXPRESSION,
+] as const;
+
+function windowsPrincipalPowerShellCommand(): string[] {
+  return [resolveTrustedWindowsPowerShellExe(), ...POWERSHELL_ARGS];
+}
+
+/** Test-only readback of the exact trusted executable and static arguments. */
+export function windowsPrincipalPowerShellCommandForTests(): string[] {
+  return windowsPrincipalPowerShellCommand();
+}
+
+function defaultWindowsPrincipalRunner(timeoutMs: number): WindowsPrincipalLookupResult {
+  const result = Bun.spawnSync(windowsPrincipalPowerShellCommand(), {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "ignore",
+    timeout: Math.max(1, timeoutMs),
+    windowsHide: true,
+  });
+  return {
+    success: result.success,
+    exitCode: result.exitCode,
+    timedOut: result.exitedDueToTimeout ?? false,
+    stdout: result.stdout ? result.stdout.toString() : "",
+  };
+}
+
+async function defaultAsyncWindowsPrincipalRunner(
+  timeoutMs: number,
+): Promise<WindowsPrincipalLookupResult> {
+  const proc = Bun.spawn(windowsPrincipalPowerShellCommand(), {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "ignore",
+    windowsHide: true,
+  });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    try { proc.kill(); } catch { /* already exited */ }
+  }, Math.max(1, timeoutMs));
+  let exitCode: number | null = null;
+  try {
+    exitCode = await proc.exited;
+  } finally {
+    clearTimeout(timer);
+  }
+  const stdout = proc.stdout
+    ? await new Response(proc.stdout).text().catch(() => "")
+    : "";
+  return {
+    success: !timedOut && exitCode === 0,
+    exitCode: timedOut ? null : exitCode,
+    timedOut,
+    stdout,
+  };
+}
+
+let principalRunner: WindowsPrincipalRunner = defaultWindowsPrincipalRunner;
+let asyncPrincipalRunner: AsyncWindowsPrincipalRunner = defaultAsyncWindowsPrincipalRunner;
+let cachedPrincipal: string | null = null;
+let asyncLookupInFlight: Promise<string> | null = null;
+
+/**
+ * POSIX CI drives the Windows ACL branch through `setPlatformForTests("win32")`,
+ * on hosts that have neither System32 nor PowerShell. Those runs need SOME
+ * principal, so this seam supplies a synthetic one.
+ *
+ * It lives here rather than in `windows-secret-acl.ts` for one reason that is
+ * not cosmetic: an explicitly injected runner must be able to beat it. When the
+ * synthetic value was chosen first, in the ACL module, a test could not inject a
+ * lookup FAILURE on POSIX at all — so the fail-closed and memo-isolation cases
+ * were guarded with `if (process.platform !== "win32") return;` and never ran
+ * outside Windows. Resolution order below is what makes those cases executable
+ * on every runner.
+ */
+let syntheticPrincipalForTests: string | null = null;
+
+/**
+ * Test seam: supply the principal used when no runner was injected and the host
+ * is not really Windows. Pass null to disable.
+ */
+export function setSyntheticWindowsPrincipalForTests(principal: string | null): void {
+  syntheticPrincipalForTests = principal;
+  cachedPrincipal = null;
+}
+
+/** True when an explicit runner override is installed and must take precedence. */
+function hasSyncRunnerOverride(): boolean {
+  return principalRunner !== defaultWindowsPrincipalRunner;
+}
+
+function hasAsyncRunnerOverride(): boolean {
+  return asyncPrincipalRunner !== defaultAsyncWindowsPrincipalRunner;
+}
+
+function identityError(reason: string): NodeJS.ErrnoException {
+  const error = new Error(`Windows effective-account SID lookup ${reason}`) as NodeJS.ErrnoException;
+  // Keep identity lookup failures distinct from icacls timeouts. In particular,
+  // they must not populate windows-secret-acl's destination timeout memo.
+  error.code = "EACLIDENTITY";
+  return error;
+}
+
+function principalFromResult(result: WindowsPrincipalLookupResult): string {
+  if (!result.success) {
+    throw identityError(result.timedOut
+      ? "timed out"
+      : `exited ${result.exitCode ?? "null"}`);
+  }
+  const sid = result.stdout.trim();
+  if (!SID_PATTERN.test(sid)) {
+    throw identityError(sid ? "returned an invalid SID" : "returned an empty SID");
+  }
+  return `*${sid.toUpperCase()}`;
+}
+
+/** Resolve and process-cache the effective token SID for synchronous ACL paths. */
+export function resolveCurrentWindowsPrincipal(timeoutMs: number): string {
+  // Order matters: an explicitly injected runner outranks the synthetic value,
+  // so a test can inject a FAILURE on a POSIX host. See the seam comment above.
+  if (hasSyncRunnerOverride()) {
+    if (cachedPrincipal) return cachedPrincipal;
+    if (timeoutMs <= 0) throw identityError("had no remaining deadline");
+    let overridden: WindowsPrincipalLookupResult;
+    try {
+      overridden = principalRunner(timeoutMs);
+    } catch {
+      throw identityError("could not start");
+    }
+    const principal = principalFromResult(overridden);
+    cachedPrincipal = principal;
+    return principal;
+  }
+  if (cachedPrincipal) return cachedPrincipal;
+  if (syntheticPrincipalForTests) return syntheticPrincipalForTests;
+  if (timeoutMs <= 0) throw identityError("had no remaining deadline");
+  let result: WindowsPrincipalLookupResult;
+  try {
+    result = principalRunner(timeoutMs);
+  } catch {
+    throw identityError("could not start");
+  }
+  const principal = principalFromResult(result);
+  cachedPrincipal = principal;
+  return principal;
+}
+
+async function waitForExistingLookup(
+  lookup: Promise<string>,
+  timeoutMs: number,
+): Promise<string> {
+  if (timeoutMs <= 0) throw identityError("had no remaining deadline");
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      lookup,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(identityError("timed out while awaiting the shared lookup")),
+          Math.max(1, timeoutMs),
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Async counterpart. Concurrent callers share one owned child lookup; a later
+ * caller may exhaust its own budget without cancelling the lookup owned by the
+ * first caller. The first caller owns that child and its process timeout; a
+ * later, longer budget deliberately does not extend an already-running child.
+ */
+export async function resolveCurrentWindowsPrincipalAsync(timeoutMs: number): Promise<string> {
+  const overridden = hasAsyncRunnerOverride();
+  if (cachedPrincipal) return cachedPrincipal;
+  if (asyncLookupInFlight) return waitForExistingLookup(asyncLookupInFlight, timeoutMs);
+  // Same precedence rule as the sync path: an injected runner beats the synthetic.
+  if (!overridden && syntheticPrincipalForTests) return syntheticPrincipalForTests;
+  if (timeoutMs <= 0) throw identityError("had no remaining deadline");
+
+  const lookup = (async (): Promise<string> => {
+    let result: WindowsPrincipalLookupResult;
+    try {
+      result = await asyncPrincipalRunner(timeoutMs);
+    } catch {
+      throw identityError("could not start");
+    }
+    const principal = principalFromResult(result);
+    cachedPrincipal = principal;
+    return principal;
+  })();
+  asyncLookupInFlight = lookup;
+  try {
+    return await lookup;
+  } finally {
+    if (asyncLookupInFlight === lookup) asyncLookupInFlight = null;
+  }
+}
+
+/** Test seam: replace the sync resolver process and clear its successful cache. */
+export function setWindowsPrincipalRunnerForTests(
+  runner: WindowsPrincipalRunner | null,
+): void {
+  if (asyncLookupInFlight) {
+    throw new Error("Cannot replace the Windows principal runner while a lookup is in flight.");
+  }
+  principalRunner = runner ?? defaultWindowsPrincipalRunner;
+  cachedPrincipal = null;
+}
+
+/** Test seam: replace the async resolver process and clear its successful cache. */
+export function setAsyncWindowsPrincipalRunnerForTests(
+  runner: AsyncWindowsPrincipalRunner | null,
+): void {
+  if (asyncLookupInFlight) {
+    throw new Error("Cannot replace the Windows principal runner while a lookup is in flight.");
+  }
+  asyncPrincipalRunner = runner ?? defaultAsyncWindowsPrincipalRunner;
+  cachedPrincipal = null;
+}
+
+/** Test seam: clear only process-local principal state. */
+export function resetWindowsPrincipalForTests(): void {
+  if (asyncLookupInFlight) {
+    throw new Error("Cannot reset the Windows principal while a lookup is in flight.");
+  }
+  cachedPrincipal = null;
+  syntheticPrincipalForTests = null;
+}

package/src/lib/winsw.ts

@@ -328,7 +328,23 @@ export async function installWinswService(entry: WinswEntry, deps: WinswInstallD
 }
 
 export function startWinswService(): void { runWinsw(["start"]); }
-export function stopWinswService(): void { try { runWinsw(["stopwait"]); } catch { /* not running */ } }
+
+/**
+ * Stop the native service and prove it is no longer running. `stopwait` can fail both
+ * for the benign already-stopped case and for real access/timeout failures, so a bare
+ * catch cannot decide whether it is safe for lifecycle callers to continue. Re-read
+ * SCM state and only accept the two states that cannot still own the proxy listener.
+ */
+export function stopWinswService(): void {
+  try { runWinsw(["stopwait"]); } catch { /* classify by verified state below */ }
+  const status = statusWinswRaw();
+  if (status === "stopped" || status === "nonexistent") return;
+  if (status === "unknown") {
+    throw new Error("Native service stop could not be verified.");
+  }
+  throw new Error("Native service is still running after stop.");
+}
+
 export function uninstallWinswService(): void {
   if (!existsSync(winswExePath())) {
     // The binary is gone but the SCM registration can outlive it (quarantine, partial
@@ -378,4 +394,4 @@ export function winswStatusSummary(): string {
 export function defaultWinswEntry(cliDir: string): WinswEntry {
   const runtime = durableBunRuntime();
   return { bun: runtime.path, bunRuntimeSource: runtime.source, cli: join(cliDir, "cli", "index.ts") };
-}
+}

package/src/oauth/key-providers.ts

@@ -18,9 +18,21 @@ export const KEY_LOGIN_PROVIDERS: Record<string, KeyLoginProvider> = deriveKeyLo
  * `noReasoningModels`, `defaultModel`) onto a provider config being created, for any field the
  * caller didn't already supply. Lets the vision/reasoning classification actually reach the saved
  * config (the GUI/API only send adapter/baseUrl/apiKey/defaultModel). No-op for unknown names.
+ *
+ * `modelSupportsReasoningSummaries` is deliberately excluded from what gets persisted. It is
+ * registry-only metadata resolved at runtime, and this function feeds a config that is about to
+ * be written to disk. Persisting today's registry defaults would freeze them as the user's own
+ * overrides: a later registry correction — say we learn a model's backend rejects summary
+ * delivery — would never reach anyone who created their provider before the correction, and they
+ * would keep getting upstream 400s with no way to know why. Catalog gathering enriches a
+ * detached runtime clone, so the defaults still apply where they matter.
  */
 export function enrichProviderFromCatalog(name: string, prov: OcxProviderConfig): void {
+  const hadOwnSummaries = Object.hasOwn(prov, "modelSupportsReasoningSummaries");
+  const submittedSummaries = prov.modelSupportsReasoningSummaries;
   enrichProviderFromRegistry(name, prov);
+  if (hadOwnSummaries) prov.modelSupportsReasoningSummaries = submittedSummaries;
+  else delete prov.modelSupportsReasoningSummaries;
 }
 
 export function isKeyLoginProvider(name: string): boolean {