@bitkyc08/opencodex 2.37.0 → 2.38.0

package/src/integrations/writer.ts

@@ -28,7 +28,7 @@ import {
   semanticProtectedContributionFingerprint,
 } from "./ownership-policy";
 import { createdContainerPaths, mergeContribution, removeFragments } from "./merge";
-import { INTEGRATION_CLIENTS, isLoopbackOnly, type IntegrationClientId } from "./registry";
+import { INTEGRATION_CLIENTS, isLoopbackOnly, resolveIntegrationPaths, type IntegrationClientId } from "./registry";
 import { classifyIntegration, exportContextOf } from "./state";
 import type { IntegrationState } from "./state";
 import { serializeDocument, UnserializableValueError } from "./serialize";
@@ -210,8 +210,20 @@ function preflight(input: IntegrationWriteInput) {
    * whole Integrations page because one client is misconfigured.
    */
   let configPath: string;
+  let detectDir: string;
   try {
-    configPath = input.resolvedPaths?.configPath ?? spec.configPath(input.env, input.home);
+    /*
+     * Resolve the PAIR, never one half.
+     *
+     * The coordinated path hands us a frozen pair, but applyIntegration,
+     * refreshIntegration and disableIntegration are public and may be called
+     * without one. Resolving configPath here and detectDir separately later let
+     * an Aside account switch land between the two, so a direct apply could
+     * verify account 1 was installed and then write account 0's catalog.
+     */
+    const resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home);
+    configPath = resolved.configPath;
+    detectDir = resolved.detectDir;
   } catch (error) {
     if (!(error instanceof ClientPathError)) throw error;
     return { failed: refuse(clientId, "unsafe", "unsafe", error.message) } as const;
@@ -248,15 +260,17 @@ function preflight(input: IntegrationWriteInput) {
   const classified = classifyIntegration({
     fileText: before, fileIsRegular: true, parsed, record, contribution, configPath, clientId,
   });
-  return { failed: undefined, store, io, clientId, spec, exportSpec, configPath, before, parsed, contribution, record, classified } as const;
+  return { failed: undefined, store, io, clientId, spec, exportSpec, configPath, detectDir, before, parsed, contribution, record, classified } as const;
 }
 
 function applyOrRefreshIntegration(input: IntegrationWriteInput, allowAbsent: boolean): WriteOutcome {
   const pre = preflight(input);
   if (pre.failed) return pre.failed;
-  const { store, io, clientId, spec, exportSpec, configPath, before, parsed, contribution, record, classified } = pre;
+  const { store, io, clientId, spec, exportSpec, configPath, detectDir, before, parsed, contribution, record, classified } = pre;
 
-  if (io.statKind(input.resolvedPaths?.detectDir ?? spec.detectDir(input.env, input.home)) !== "dir") {
+  // The detect directory preflight already resolved, so it cannot name a
+  // different account than the config path this operation is about to write.
+  if (io.statKind(detectDir) !== "dir") {
     return refuse(clientId, "not_installed", "absent", `${clientId} is not installed`);
   }
   if (isLoopbackOnly(clientId) && !isLoopbackHostname(input.config.hostname)) {
@@ -624,10 +638,12 @@ function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegration
   const store = input.store ?? createIntegrationStateStore();
   const io = input.io ?? defaultIntegrationIO(store);
   const spec = INTEGRATION_CLIENTS[input.clientId];
-  const resolvedPaths = {
-    configPath: spec.configPath(env, home),
-    detectDir: spec.detectDir(env, home),
-  };
+  /*
+   * 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
+   * and then write another account's catalog if a switch landed between them.
+   */
+  const resolvedPaths = resolveIntegrationPaths(input.clientId, env, home);
   return { ...input, env, home, store, io, resolvedPaths };
 }
 

package/src/lib/bounded-subprocess.ts

@@ -0,0 +1,36 @@
+export interface KillableSubprocess {
+  exited: Promise<number>;
+  kill(): unknown;
+  unref?(): unknown;
+}
+
+export interface BoundedSubprocessExit {
+  exitCode: number | null;
+  timedOut: boolean;
+}
+
+/** Kill at the deadline and abandon immediately; late exit/rejection remains observed. */
+export function waitForSubprocessExit(
+  proc: KillableSubprocess,
+  timeoutMs: number,
+): Promise<BoundedSubprocessExit> {
+  return new Promise(resolve => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (result: BoundedSubprocessExit): void => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      resolve(result);
+    };
+    timer = setTimeout(() => {
+      try { proc.kill(); } catch { /* already exited */ }
+      try { proc.unref?.(); } catch { /* abandonment is still authoritative */ }
+      finish({ exitCode: null, timedOut: true });
+    }, Math.max(1, timeoutMs));
+    void proc.exited.then(
+      exitCode => finish({ exitCode, timedOut: false }),
+      () => finish({ exitCode: null, timedOut: false }),
+    );
+  });
+}

package/src/lib/strict-semver.ts

@@ -0,0 +1,47 @@
+// Core and build metadata are unambiguous and stay inline. The prerelease section does not:
+// the semver.org pattern for one identifier is
+//   0 | [1-9]\d* | [0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*
+// whose three alternatives overlap, and wrapping that in `(?:\.…)*` gives a regex engine an
+// exponential number of ways to split the same string. CodeQL flagged it (`js/redos`) and the
+// cost is real, not theoretical: `0.0.0-0.` followed by repetitions of `--.` took **522ms for a
+// single 125-character input** — inside the 128-char ceiling this module already enforced, and
+// inside the 96-char one its only caller uses. A length cap does not fix superlinear blowup; it
+// only decides where the curve is sampled.
+//
+// So the prerelease section is matched with one non-backtracking pass and its identifiers are
+// validated individually. Each identifier is checked by an anchored regex with no repetition of
+// an alternation, which is linear in the identifier's length.
+const STRICT_SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+
+const NUMERIC_IDENTIFIER_RE = /^(?:0|[1-9]\d*)$/;
+const ALPHANUMERIC_IDENTIFIER_RE = /^[0-9A-Za-z-]+$/;
+
+/**
+ * A prerelease identifier is either a numeric identifier with no leading zero, or an
+ * alphanumeric one that contains at least one non-digit. Empty identifiers are invalid,
+ * which is what rejects a trailing or doubled dot.
+ */
+function isPrereleaseIdentifier(part: string): boolean {
+  if (part.length === 0) return false;
+  if (NUMERIC_IDENTIFIER_RE.test(part)) return true;
+  return ALPHANUMERIC_IDENTIFIER_RE.test(part) && !/^\d+$/.test(part);
+}
+
+export interface StrictSemver {
+  readonly raw: string;
+  readonly core: readonly [bigint, bigint, bigint];
+  readonly prerelease: readonly (bigint | string)[];
+}
+
+export function parseStrictSemver(value: unknown, maxLength = 128): StrictSemver | null {
+  if (typeof value !== "string" || value.length === 0 || value.length > maxLength) return null;
+  const match = STRICT_SEMVER_RE.exec(value);
+  if (!match) return null;
+  const prereleaseParts = match[4] === undefined ? [] : match[4].split(".");
+  if (!prereleaseParts.every(isPrereleaseIdentifier)) return null;
+  return Object.freeze({
+    raw: value,
+    core: Object.freeze([BigInt(match[1]!), BigInt(match[2]!), BigInt(match[3]!)]) as readonly [bigint, bigint, bigint],
+    prerelease: Object.freeze(prereleaseParts.map(part => /^\d+$/.test(part) ? BigInt(part) : part)),
+  });
+}

package/src/lib/windows-elevation.ts

@@ -2,6 +2,7 @@ import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process"
 import { existsSync } from "node:fs";
 import { isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
 import { dlopen, ptr, type Pointer } from "bun:ffi";
+import { isTestHomeGuardArmed } from "./test-home-guard";
 
 type ElevationSpawn = (
   command: string,
@@ -530,6 +531,19 @@ export function startPowerShellCommand(commandScript: string): WindowsElevationE
     };
   }
 
+  // HOME isolation cannot contain UAC children or other machine-global effects. Keep the
+  // final process boundary closed while the real launcher is installed; explicitly injected
+  // launchers remain available to tests that exercise the elevation protocol in memory.
+  if (isTestHomeGuardArmed() && elevationSpawn === spawn) {
+    return {
+      launcherPid: null,
+      completion: Promise.reject(new WindowsElevationError(
+        "launch-failed",
+        "Refusing to launch a live Windows elevation process from an armed test process; inject the elevation launcher instead.",
+      )),
+    };
+  }
+
   let child: ChildProcess;
   try {
     child = elevationSpawn(
@@ -638,8 +652,16 @@ export function runWindowsElevated(file: string, args: string[]): Promise<number
 export function runWindowsElevatedScheduledTaskRegistration(
   taskName: string,
   xml: string,
+  replace = false,
+  expectedExistingXml?: string,
 ): Promise<number> {
+  if (replace && !expectedExistingXml?.trim()) {
+    throw new Error("Elevated Task Scheduler replacement requires a captured existing definition.");
+  }
   const xmlBase64 = Buffer.from(xml, "utf16le").toString("base64");
+  const expectedExistingBase64 = expectedExistingXml === undefined
+    ? null
+    : Buffer.from(expectedExistingXml, "utf16le").toString("base64");
   const powerShellPath = windowsPowerShell();
   const powerShellDirectory = powerShellPath.replace(/[\\/][^\\/]+$/, "");
   const scheduledTasksModule = `${powerShellDirectory}\\Modules\\ScheduledTasks\\ScheduledTasks.psd1`;
@@ -650,7 +672,16 @@ export function runWindowsElevatedScheduledTaskRegistration(
     `$module = Microsoft.PowerShell.Core\\Import-Module -Name ${psSingleQuote(scheduledTasksModule)} -PassThru -Force -ErrorAction Stop`,
     "$registerTask = $module.ExportedCommands['Register-ScheduledTask']",
     "if ($null -eq $registerTask) { throw 'Trusted ScheduledTasks module does not export Register-ScheduledTask.' }",
-    "& $registerTask -TaskName $taskName -Xml $xml -Force -ErrorAction Stop | Out-Null",
+    ...(replace ? [
+      `$expectedBase64 = ${psSingleQuote(expectedExistingBase64!)}`,
+      "$expectedXml = [Text.Encoding]::Unicode.GetString([Convert]::FromBase64String($expectedBase64))",
+      `$schtasks = ${psSingleQuote(resolveTrustedWindowsSchtasksExe())}`,
+      "$currentXml = & $schtasks /query /tn $taskName /xml 2>$null | Out-String",
+      "if ($LASTEXITCODE -ne 0) { throw 'Task Scheduler replacement precondition could not be read.' }",
+      "function Normalize-OcxTaskXml([string]$value) { return (($value.TrimStart([char]0xFEFF) -replace \"`r`n?\", \"`n\").Trim()) }",
+      "if ((Normalize-OcxTaskXml $currentXml) -cne (Normalize-OcxTaskXml $expectedXml)) { throw 'Task Scheduler replacement precondition changed.' }",
+    ] : []),
+    `& $registerTask -TaskName $taskName -Xml $xml${replace ? " -Force" : ""} -ErrorAction Stop | Out-Null`,
   ].join("; ");
   const encodedCommand = Buffer.from(inner, "utf16le").toString("base64");
   const script = [

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

@@ -31,6 +31,7 @@
 
 import { existsSync, statSync } from "node:fs";
 import { env, platform } from "node:process";
+import { waitForSubprocessExit } from "./bounded-subprocess";
 import { resolveTrustedWindowsIcaclsExe } from "./windows-elevation";
 import {
   cachedCurrentWindowsIdentity,
@@ -216,6 +217,11 @@ export interface HardenResult {
 
 export interface HardenOptions {
   required: boolean;
+  /**
+   * Explicit total budget for this harden call. Shutdown recovery uses a reduced
+   * caller-owned slice instead of opening the normal 30-second window.
+   */
+  deadlineMs?: number;
   /**
    * Optional timeout-memo key distinct from `targetPath` (issue #612).
    * Atomic writers mint a fresh `.tmp` path per write; keying the timeout cache by the
@@ -257,7 +263,11 @@ const HARDEN_DEADLINE_MIN_MS = 1_000;
 const HARDEN_DEADLINE_MAX_MS = 60_000;
 
 /** Resolve the total harden budget once per call (env mutation cannot change it midway). */
-function resolveHardenDeadlineMs(): number {
+function resolveHardenDeadlineMs(overrideMs?: number): number {
+  if (overrideMs !== undefined) {
+    if (!Number.isSafeInteger(overrideMs) || overrideMs <= 0) return 1;
+    return Math.min(HARDEN_DEADLINE_MAX_MS, overrideMs);
+  }
   const raw = env["OPENCODEX_ACL_TIMEOUT_MS"]?.trim();
   if (!raw) return HARDEN_DEADLINE_DEFAULT_MS;
   const parsed = Number(raw);
@@ -328,27 +338,16 @@ function defaultIcaclsRunner(args: string[], timeoutMs: number): IcaclsResult {
 
 /**
  * Async icacls runner (#612): yields the event loop while waiting for the child.
- * Timeout provenance is recorded by our timer (async Subprocess has no exitedDueToTimeout);
- * we still await process exit before classifying so settlement is confirmed.
+ * Async Subprocess has no exitedDueToTimeout, so the shared settlement helper
+ * classifies the deadline and abandons a child that does not settle after kill.
  */
 async function defaultAsyncIcaclsRunner(args: string[], timeoutMs: number): Promise<IcaclsResult> {
   const proc = trySpawnIcacls(args);
   if (!proc) return spawnFailedResult();
-  let timedOutByUs = false;
-  const timer = setTimeout(() => {
-    timedOutByUs = 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
+  const { exitCode, timedOut } = await waitForSubprocessExit(proc, timeoutMs);
+  const stdout = !timedOut && proc.stdout
     ? await new Response(proc.stdout).text().catch(() => "")
     : "";
-  const timedOut = timedOutByUs;
   return {
     success: !timedOut && exitCode === 0,
     exitCode: timedOut ? null : exitCode,
@@ -357,6 +356,24 @@ async function defaultAsyncIcaclsRunner(args: string[], timeoutMs: number): Prom
   };
 }
 
+function awaitAsyncIcaclsRunner(args: string[], timeoutMs: number): Promise<IcaclsResult> {
+  return new Promise(resolve => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (result: IcaclsResult): void => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      resolve(result);
+    };
+    timer = setTimeout(
+      () => finish({ success: false, exitCode: null, timedOut: true, stdout: "" }),
+      Math.max(1, timeoutMs),
+    );
+    void asyncIcaclsRunner(args, timeoutMs).then(finish, () => finish(spawnFailedResult()));
+  });
+}
+
 let icaclsRunner: IcaclsRunner = defaultIcaclsRunner;
 let asyncIcaclsRunner: AsyncIcaclsRunner = defaultAsyncIcaclsRunner;
 let platformOverride: string | null = null;
@@ -537,12 +554,14 @@ function shouldVerifyExistingAcl(): boolean {
   return env["OPENCODEX_ACL_VERIFY_EXISTING"] === "1";
 }
 
-function existingAclAlreadyCompliant(targetPath: string, directory: boolean): boolean {
+function existingAclAlreadyCompliant(targetPath: string, directory: boolean, deadline: number): boolean {
   if (!shouldVerifyExistingAcl()) return false;
   const identity = cachedCurrentWindowsIdentity();
   if (!identity) return false;
   try {
-    const result = icaclsRunner([targetPath], resolveHardenDeadlineMs());
+    const remaining = deadline - nowFn();
+    if (remaining <= 0) return false;
+    const result = icaclsRunner([targetPath], remaining);
     return result.success && existingAclIsCompliant(targetPath, directory, result.stdout, identity.name);
   } catch {
     return false;
@@ -552,12 +571,15 @@ function existingAclAlreadyCompliant(targetPath: string, directory: boolean): bo
 async function existingAclAlreadyCompliantAsync(
   targetPath: string,
   directory: boolean,
+  deadline: number,
 ): Promise<boolean> {
   if (!shouldVerifyExistingAcl()) return false;
   const identity = cachedCurrentWindowsIdentity();
   if (!identity) return false;
   try {
-    const result = await asyncIcaclsRunner([targetPath], resolveHardenDeadlineMs());
+    const remaining = deadline - nowFn();
+    if (remaining <= 0) return false;
+    const result = await awaitAsyncIcaclsRunner([targetPath], remaining);
     return result.success && existingAclIsCompliant(targetPath, directory, result.stdout, identity.name);
   } catch {
     return false;
@@ -618,7 +640,7 @@ async function runIcaclsAsync(targetPath: string, directory: boolean, deadline:
     if (remaining <= 0) {
       throw icaclsError(step, { success: false, exitCode: null, timedOut: true, stdout: "" });
     }
-    return asyncIcaclsRunner(args, remaining);
+    return awaitAsyncIcaclsRunner(args, remaining);
   };
   const runOrThrow = async (step: string, args: string[]): Promise<void> => {
     const result = await run(step, args);
@@ -751,7 +773,7 @@ async function describeAclStateAfterTimeoutAsync(targetPath: string, deadline: n
     for (const sid of BROAD_SIDS) {
       const remaining = deadline - nowFn();
       if (remaining <= 0) return "ACL state unverified (budget exhausted)";
-      const found = await asyncIcaclsRunner([targetPath, "/findsid", sid], remaining);
+      const found = await awaitAsyncIcaclsRunner([targetPath, "/findsid", sid], remaining);
       if (!found.success) return "ACL state unverified (probe failed)";
       if (found.stdout.includes(targetPath)) return "broad ACL grants still present";
     }
@@ -788,7 +810,8 @@ function hardenEntry(
   if (!existsSync(targetPath)) { cache.delete(targetPath); return { ok: true }; }
   if (effectivePlatform() !== "win32") return { ok: true };
   if (memoSatisfied(cache, targetPath)) return { ok: true };
-  if (existingAclAlreadyCompliant(targetPath, directory)) return { ok: true };
+  const deadline = nowFn() + resolveHardenDeadlineMs(opts.deadlineMs);
+  if (existingAclAlreadyCompliant(targetPath, directory, deadline)) return { ok: true };
   const memoKey = timeoutMemoKey(targetPath, opts);
   const timeoutMemoError = timeoutMemoErrorIfBlocked(memoKey, opts);
   if (timeoutMemoError) {
@@ -796,7 +819,6 @@ function hardenEntry(
     return { ok: false, diagnostics: timeoutMemoError.message };
   }
 
-  const deadline = nowFn() + resolveHardenDeadlineMs();
   let lastErr: unknown;
   for (let attempt = 0; attempt < 2; attempt++) {
     if (attempt > 0 && deadline - nowFn() <= 0) break; // retry only while budget remains
@@ -841,7 +863,8 @@ async function hardenEntryAsync(
   if (!existsSync(targetPath)) { cache.delete(targetPath); return { ok: true }; }
   if (effectivePlatform() !== "win32") return { ok: true };
   if (memoSatisfied(cache, targetPath)) return { ok: true };
-  if (await existingAclAlreadyCompliantAsync(targetPath, directory)) return { ok: true };
+  const deadline = nowFn() + resolveHardenDeadlineMs(opts.deadlineMs);
+  if (await existingAclAlreadyCompliantAsync(targetPath, directory, deadline)) return { ok: true };
   const memoKey = timeoutMemoKey(targetPath, opts);
   const timeoutMemoError = timeoutMemoErrorIfBlocked(memoKey, opts);
   if (timeoutMemoError) {
@@ -849,7 +872,6 @@ async function hardenEntryAsync(
     return { ok: false, diagnostics: timeoutMemoError.message };
   }
 
-  const deadline = nowFn() + resolveHardenDeadlineMs();
   let lastErr: unknown;
   for (let attempt = 0; attempt < 2; attempt++) {
     if (attempt > 0 && deadline - nowFn() <= 0) break;

package/src/lib/windows-service-mutation-lock.ts

@@ -0,0 +1,133 @@
+import { Database } from "bun:sqlite";
+import { chmodSync, lstatSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { resolveEffectiveUserIdentity, resolveEffectiveUserRuntimeRoot } from "../codex/user-identity";
+import { hardenSecretDir, hardenSecretPath } from "./windows-secret-acl";
+
+type LockDatabase = Pick<Database, "exec" | "close">;
+
+export interface WindowsServiceMutationLockDeps {
+  lockPath?: string;
+  openDatabase?: (path: string) => LockDatabase;
+  hardenDirectory?: (path: string) => void;
+  hardenFile?: (path: string) => void;
+}
+
+export class WindowsServiceMutationBusyError extends Error {
+  readonly code = "WINDOWS_SERVICE_MUTATION_BUSY";
+
+  constructor() {
+    super("Another OpenCodex Windows service operation is already in progress. Wait for it to finish, then retry.");
+    this.name = "WindowsServiceMutationBusyError";
+  }
+}
+
+export class WindowsServiceMutationLockError extends Error {
+  readonly code = "WINDOWS_SERVICE_MUTATION_LOCK_FAILED";
+
+  constructor(operation: "acquire" | "release", cause: unknown) {
+    super(`The Windows service mutation lock could not be ${operation === "acquire" ? "acquired" : "released"}.`, { cause });
+    this.name = "WindowsServiceMutationLockError";
+  }
+}
+
+function errorCode(error: unknown): string | undefined {
+  return error && typeof error === "object" && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+}
+
+function isBusy(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return errorCode(error) === "SQLITE_BUSY"
+    || errorCode(error) === "SQLITE_LOCKED"
+    || /database (?:is|table is) locked/i.test(message);
+}
+
+/**
+ * Stable per-user lock namespace for the fixed `opencodex-proxy` task name.
+ *
+ * Deliberately outside OPENCODEX_HOME: creating the lock must not make a genuinely fresh
+ * config root look pre-existing before the installer records its uninstall ownership. The
+ * effective-user runtime root ignores LOCALAPPDATA/USERPROFILE overrides, so two processes
+ * running as the same SID cannot split the lock by changing their environment or config home.
+ */
+export function windowsServiceMutationLockPath(): string {
+  const identity = resolveEffectiveUserIdentity();
+  if (identity.platform !== "win32") {
+    throw new Error("The Windows service mutation lock is only available on Windows.");
+  }
+  return join(resolveEffectiveUserRuntimeRoot(identity), "windows-service-mutation.sqlite");
+}
+
+function assertRegularPath(path: string, kind: "directory" | "file"): void {
+  const entry = lstatSync(path);
+  const valid = kind === "directory" ? entry.isDirectory() : entry.isFile();
+  if (!valid || entry.isSymbolicLink()) {
+    throw new Error(`The Windows service mutation lock ${kind} is not a regular ${kind}.`);
+  }
+}
+
+/**
+ * Serialize one complete Windows service mutation across OpenCodex processes.
+ *
+ * The SQLite write transaction is the lock. It stays held across UAC and async verification,
+ * and the OS releases it if the process exits, so no stale lock file needs unsafe reclamation.
+ */
+export async function withWindowsServiceMutationLock<T>(
+  operation: () => Promise<T>,
+  deps: WindowsServiceMutationLockDeps = {},
+): Promise<T> {
+  const lockPath = deps.lockPath ?? windowsServiceMutationLockPath();
+  const lockDir = dirname(lockPath);
+  let database: LockDatabase | undefined;
+  let acquired = false;
+
+  try {
+    mkdirSync(lockDir, { recursive: true, mode: 0o700 });
+    assertRegularPath(lockDir, "directory");
+    try { chmodSync(lockDir, 0o700); } catch { /* Windows ACL below is authoritative. */ }
+    (deps.hardenDirectory ?? (path => { hardenSecretDir(path, { required: true }); }))(lockDir);
+
+    try {
+      database = (deps.openDatabase ?? (path => new Database(path, { create: true })))(lockPath);
+      assertRegularPath(lockPath, "file");
+      try { chmodSync(lockPath, 0o600); } catch { /* Windows ACL below is authoritative. */ }
+      (deps.hardenFile ?? (path => { hardenSecretPath(path, { required: true }); }))(lockPath);
+      database.exec("PRAGMA locking_mode = NORMAL; PRAGMA busy_timeout = 0; BEGIN IMMEDIATE");
+      acquired = true;
+    } catch (error) {
+      try { database?.close(); } catch { /* acquisition already failed */ }
+      database = undefined;
+      if (isBusy(error)) throw new WindowsServiceMutationBusyError();
+      throw new WindowsServiceMutationLockError("acquire", error);
+    }
+
+    let result: T;
+    let operationError: unknown;
+    try {
+      result = await operation();
+    } catch (error) {
+      operationError = error;
+    }
+
+    let releaseError: unknown;
+    if (acquired) {
+      try { database.exec("ROLLBACK"); } catch (error) { releaseError = error; }
+    }
+    try { database.close(); } catch (error) { releaseError ??= error; }
+    acquired = false;
+    database = undefined;
+
+    if (operationError !== undefined) throw operationError;
+    if (releaseError !== undefined) throw new WindowsServiceMutationLockError("release", releaseError);
+    return result!;
+  } catch (error) {
+    if (acquired) {
+      try { database?.exec("ROLLBACK"); } catch { /* close still releases the OS lock */ }
+    }
+    try { database?.close(); } catch { /* preserve the primary error */ }
+    throw error;
+  }
+}

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

@@ -22,12 +22,20 @@
 
 import { existsSync } from "node:fs";
 import { win32 as windowsPath } from "node:path";
+import { waitForSubprocessExit } from "./bounded-subprocess";
 
 import {
   resolveTrustedWindowsPowerShellExe,
   WindowsSystemDirectoryFfiUnavailableError,
 } from "./windows-elevation";
 
+/**
+ * Shared ceiling for a full effective-token identity lookup. PowerShell startup can
+ * legitimately take several seconds on loaded desktops as well as CI, so every caller
+ * that is not spending a smaller pre-existing deadline uses the same #2914-tested budget.
+ */
+export const WINDOWS_PRINCIPAL_LOOKUP_TIMEOUT_MS = 30_000;
+
 const SID_PATTERN = /^S-1-(?:\d+-)+\d+$/i;
 const IDENTITY_EXPRESSION =
   "$identity=[System.Security.Principal.WindowsIdentity]::GetCurrent();$identity.User.Value;$identity.Name";
@@ -143,18 +151,8 @@ async function defaultAsyncWindowsPrincipalRunner(
     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
+  const { exitCode, timedOut } = await waitForSubprocessExit(proc, timeoutMs);
+  const stdout = !timedOut && proc.stdout
     ? await new Response(proc.stdout).text().catch(() => "")
     : "";
   return {
@@ -314,11 +312,11 @@ export async function resolveCurrentWindowsPrincipalAsync(timeoutMs: number): Pr
     return `*${cachedIdentity.sid}`;
   })();
   asyncLookupInFlight = lookup;
-  try {
-    return await lookup;
-  } finally {
-    if (asyncLookupInFlight === lookup) asyncLookupInFlight = null;
-  }
+  void lookup.then(
+    () => { if (asyncLookupInFlight === lookup) asyncLookupInFlight = null; },
+    () => { if (asyncLookupInFlight === lookup) asyncLookupInFlight = null; },
+  );
+  return waitForExistingLookup(lookup, timeoutMs);
 }
 
 /** Test seam: replace the sync resolver process and clear its successful cache. */