@iislee/opencodex 2.11.0

package/src/lib/windows-elevation.ts

@@ -0,0 +1,705 @@
+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";
+
+type ElevationSpawn = (
+  command: string,
+  args: ReadonlyArray<string>,
+  options: SpawnOptions,
+) => ChildProcess;
+
+let elevationSpawn: ElevationSpawn = spawn;
+
+/** Test-only seam for the elevated PowerShell launcher. */
+export function setWindowsElevationSpawnForTests(next: ElevationSpawn | null): void {
+  elevationSpawn = next ?? spawn;
+}
+
+type GetSystemDirectoryW = (buffer: Pointer, size: number) => number;
+type TrustedSystemDirectoryResolver = () => string;
+type IsUserAnAdmin = () => number;
+type WindowsElevationProbe = () => boolean | null;
+
+let getSystemDirectoryWFn: GetSystemDirectoryW | null | undefined;
+let trustedSystemDirectoryResolverForTests: TrustedSystemDirectoryResolver | null = null;
+let isUserAnAdminFn: (() => boolean) | null | undefined;
+let windowsElevationProbeForTests: WindowsElevationProbe | null = null;
+
+/** Test-only seam to replace GetSystemDirectoryW-backed resolution. */
+export function setTrustedWindowsSystemDirectoryResolverForTests(
+  next: TrustedSystemDirectoryResolver | null,
+): void {
+  trustedSystemDirectoryResolverForTests = next;
+}
+
+/** Test-only seam for the locale-independent current-token elevation probe. */
+export function setWindowsElevationProbeForTests(next: WindowsElevationProbe | null): void {
+  windowsElevationProbeForTests = next;
+}
+
+function loadIsUserAnAdmin(): (() => boolean) | null {
+  if (isUserAnAdminFn !== undefined) return isUserAnAdminFn;
+  if (process.platform !== "win32") {
+    isUserAnAdminFn = null;
+    return null;
+  }
+  try {
+    const lib = dlopen("shell32.dll", {
+      IsUserAnAdmin: {
+        args: [],
+        // Win32 BOOL is a signed 32-bit integer, not C/C++ bool.
+        returns: "i32",
+      },
+    });
+    const isUserAnAdmin = lib.symbols.IsUserAnAdmin as IsUserAnAdmin;
+    isUserAnAdminFn = () => isUserAnAdmin() !== 0;
+  } catch {
+    isUserAnAdminFn = null;
+  }
+  return isUserAnAdminFn;
+}
+
+/**
+ * Probe the effective Windows token without parsing localized command output.
+ * `null` fails closed: callers must retain the original scheduler error rather
+ * than infer that an unknown token state needs elevation.
+ */
+export function isCurrentWindowsProcessElevated(): boolean | null {
+  if (windowsElevationProbeForTests) return windowsElevationProbeForTests();
+  const isUserAnAdmin = loadIsUserAnAdmin();
+  if (!isUserAnAdmin) return null;
+  try {
+    return isUserAnAdmin();
+  } catch {
+    return null;
+  }
+}
+
+function loadGetSystemDirectoryW(): GetSystemDirectoryW | null {
+  if (getSystemDirectoryWFn !== undefined) return getSystemDirectoryWFn;
+  if (process.platform !== "win32") {
+    getSystemDirectoryWFn = null;
+    return null;
+  }
+  try {
+    const lib = dlopen("kernel32.dll", {
+      GetSystemDirectoryW: {
+        args: ["ptr", "u32"],
+        returns: "u32",
+      },
+    });
+    getSystemDirectoryWFn = (buffer, size) => lib.symbols.GetSystemDirectoryW(buffer, size) as number;
+  } catch {
+    getSystemDirectoryWFn = null;
+  }
+  return getSystemDirectoryWFn;
+}
+
+function decodeWideCString(buf: Uint16Array, length: number): string {
+  return String.fromCharCode(...buf.subarray(0, length));
+}
+
+/**
+ * Resolve the real Windows system directory via GetSystemDirectoryW.
+ * Must never trust process.env.SystemRoot / WINDIR — those are caller-controlled and
+ * must not select binaries for UAC elevation.
+ */
+export function resolveTrustedWindowsSystemDirectory(): string {
+  if (trustedSystemDirectoryResolverForTests) {
+    return trustedSystemDirectoryResolverForTests();
+  }
+  if (process.platform !== "win32") {
+    throw new Error("Trusted Windows system directory resolution is only supported on Windows.");
+  }
+  const getSystemDirectoryW = loadGetSystemDirectoryW();
+  if (!getSystemDirectoryW) {
+    throw new Error("Failed to load GetSystemDirectoryW from kernel32.dll.");
+  }
+
+  let size = 260;
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    const buf = new Uint16Array(size);
+    const written = getSystemDirectoryW(ptr(buf.buffer), size);
+    if (written === 0) {
+      throw new Error("GetSystemDirectoryW failed while resolving the trusted system directory.");
+    }
+    // When the buffer is too small, the return value is the required size including NUL.
+    if (written >= size) {
+      size = written + 1;
+      continue;
+    }
+    const directory = decodeWideCString(buf, written).replace(/[/\\]+$/, "");
+    if (!directory || !existsSync(directory)) {
+      throw new Error("GetSystemDirectoryW returned an unusable system directory.");
+    }
+    return resolvePath(directory);
+  }
+  throw new Error("GetSystemDirectoryW required a system directory path larger than expected.");
+}
+
+/**
+ * True when `candidatePath` is the trusted directory itself, or a contained child.
+ * Uses path.relative so containment works with host-native separators (Linux/macOS CI
+ * hosts fake win32 with `/tmp/...` paths; a literal `\\` prefix check rejects them).
+ */
+function isPathInsideTrustedDirectory(trustedDirectory: string, candidatePath: string): boolean {
+  const relativePath = relative(trustedDirectory, candidatePath);
+  return (
+    relativePath === "" ||
+    (!isAbsolute(relativePath) && relativePath !== ".." && !relativePath.startsWith(`..${sep}`))
+  );
+}
+
+function assertTrustedSystemExecutable(candidate: string, label: string): string {
+  const systemDir = resolveTrustedWindowsSystemDirectory();
+  const resolved = resolvePath(candidate);
+  if (!isPathInsideTrustedDirectory(systemDir, resolved)) {
+    throw new Error(`${label} resolved outside the trusted Windows system directory.`);
+  }
+  if (!existsSync(resolved)) {
+    throw new Error(`Trusted ${label} was not found at ${resolved}.`);
+  }
+  return resolved;
+}
+
+/** Test-only access to the trusted-path containment check. */
+export function assertTrustedSystemExecutableForTests(candidate: string, label: string): string {
+  return assertTrustedSystemExecutable(candidate, label);
+}
+
+type ElevationExeOverrides = { powershell?: string; schtasks?: string };
+let elevationExeOverridesForTests: ElevationExeOverrides | null = null;
+
+/**
+ * Test-only absolute executable overrides for Linux CI (which fakes win32 but has
+ * no kernel32/System32). Production resolution never consults this seam.
+ */
+export function setTrustedWindowsElevationExecutablesForTests(
+  next: ElevationExeOverrides | null,
+): void {
+  elevationExeOverridesForTests = next;
+}
+
+/** Absolute path to System32\\WindowsPowerShell\\v1.0\\powershell.exe from a trusted system directory. */
+export function resolveTrustedWindowsPowerShellExe(): string {
+  if (elevationExeOverridesForTests?.powershell) {
+    return elevationExeOverridesForTests.powershell;
+  }
+  const candidate = join(
+    resolveTrustedWindowsSystemDirectory(),
+    "WindowsPowerShell",
+    "v1.0",
+    "powershell.exe",
+  );
+  return assertTrustedSystemExecutable(candidate, "PowerShell");
+}
+
+/** Absolute path to System32\\schtasks.exe from a trusted system directory. */
+export function resolveTrustedWindowsSchtasksExe(): string {
+  if (elevationExeOverridesForTests?.schtasks) {
+    return elevationExeOverridesForTests.schtasks;
+  }
+  const candidate = join(resolveTrustedWindowsSystemDirectory(), "schtasks.exe");
+  return assertTrustedSystemExecutable(candidate, "schtasks.exe");
+}
+
+/** Stable machine-readable marker for a denied `schtasks /create`. Crosses the CLI→proxy boundary. */
+export const WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER =
+  "OCX_ERROR_CODE=WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED";
+
+/**
+ * Reserved elevated-scheduler protocol exit codes.
+ * These are OpenCodex-owned values returned by the elevated PowerShell transaction.
+ * They must never collide with UAC cancellation (1223).
+ *
+ * The elevated script never exits with raw schtasks codes — only these protocol values —
+ * so the parent can classify the transaction without a user-controlled result file.
+ */
+export const OCX_ELEVATED_SUCCESS = 0;
+export const OCX_ELEVATED_CREATE_FAILED = 10;
+export const OCX_ELEVATED_RUN_FAILED_ROLLED_BACK = 11;
+export const OCX_ELEVATED_RUN_FAILED_ROLLBACK_FAILED = 12;
+export const OCX_ELEVATED_PROTOCOL_FAILED = 13;
+/** Windows ERROR_CANCELLED — reserved for UAC denial; never emitted by the elevated script. */
+export const OCX_ELEVATED_UAC_CANCELLED = 1223;
+
+export const OCX_ELEVATED_PROTOCOL_CODES = [
+  OCX_ELEVATED_SUCCESS,
+  OCX_ELEVATED_CREATE_FAILED,
+  OCX_ELEVATED_RUN_FAILED_ROLLED_BACK,
+  OCX_ELEVATED_RUN_FAILED_ROLLBACK_FAILED,
+  OCX_ELEVATED_PROTOCOL_FAILED,
+] as const;
+
+export type WindowsSchtasksOperation = "create" | "run" | "query" | "delete" | "end" | "other";
+export type WindowsSchtasksFailureReason = "access-denied" | "other";
+
+export type WindowsElevationFailureReason =
+  | "cancelled"
+  | "timeout"
+  | "launch-failed"
+  | "child-failed"
+  | "terminated";
+
+export type ElevatedSchedulerOutcome =
+  | "success"
+  | "create-failed"
+  | "run-failed-rolled-back"
+  | "run-failed-rollback-failed"
+  | "protocol-failed";
+
+const ELEVATION_OUTPUT_LIMIT = 256 * 1024;
+
+function windowsAccessDeniedText(text: string): boolean {
+  const normalized = text.toLowerCase();
+  return normalized.includes("access denied")
+    || normalized.includes("access is denied")
+    || normalized.includes("denied access")
+    || normalized.includes("zugriff verweigert");
+}
+
+function windowsUacCancelledText(text: string): boolean {
+  const normalized = text.toLowerCase();
+  return normalized.includes("operation was canceled by the user")
+    || normalized.includes("operation was cancelled by the user")
+    || normalized.includes("the operation was canceled")
+    || normalized.includes("the operation was cancelled")
+    || normalized.includes("vom benutzer abgebrochen")
+    || normalized.includes("durch den benutzer abgebrochen");
+}
+
+/** True when a captured stderr/stdout/message indicates Windows access denial. */
+export function isWindowsAccessDenied(detail: string): boolean {
+  return windowsAccessDeniedText(detail);
+}
+
+/** True when a thrown exec error looks like Windows access denial. */
+export function isWindowsAccessDeniedError(error: unknown): boolean {
+  if (error instanceof WindowsSchtasksError) return error.reason === "access-denied";
+  if (!(error instanceof Error)) return isWindowsAccessDenied(String(error));
+  const exec = error as NodeJS.ErrnoException & { stderr?: string | Buffer; stdout?: string | Buffer };
+  const parts = [error.message, exec.stderr, exec.stdout]
+    .map(part => (typeof part === "string" ? part : part ? String(part) : ""));
+  return parts.some(part => windowsAccessDeniedText(part));
+}
+
+/** True only for a structured Task Scheduler `/create` access-denied failure. */
+export function isWindowsSchtasksCreateAccessDenied(detail: string): boolean {
+  return detail.includes(WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER);
+}
+
+export function schtasksOperationFromArgs(args: string[]): WindowsSchtasksOperation {
+  const flag = (args[0] ?? "").toLowerCase();
+  if (flag === "/create") return "create";
+  if (flag === "/run") return "run";
+  if (flag === "/query") return "query";
+  if (flag === "/delete") return "delete";
+  if (flag === "/end") return "end";
+  return "other";
+}
+
+function schedulerExitStatus(error: unknown): number | null {
+  if (!error || typeof error !== "object") return null;
+  const status = (error as { status?: unknown }).status;
+  return typeof status === "number" && Number.isInteger(status) ? status : null;
+}
+
+/**
+ * The owned scheduler install has a fixed shape. Restrict the locale-independent
+ * fallback to that shape so unrelated schtasks failures cannot request elevation.
+ */
+function isOwnedSchedulerCreate(args: string[]): boolean {
+  const normalized = args.map(arg => arg.toLowerCase());
+  const taskIndex = normalized.indexOf("/tn");
+  const xmlIndex = normalized.indexOf("/xml");
+  return normalized[0] === "/create"
+    && normalized[taskIndex + 1] === "opencodex-proxy"
+    && taskIndex > 0
+    && xmlIndex > 0
+    && Boolean(args[xmlIndex + 1])
+    && normalized.includes("/f");
+}
+
+function isWindowsSchtasksAccessDeniedError(error: unknown, args: string[]): boolean {
+  if (!isOwnedSchedulerCreate(args)) return false;
+  return isWindowsAccessDeniedError(error)
+    || (schedulerExitStatus(error) === 1 && isCurrentWindowsProcessElevated() === false);
+}
+
+/** Structured Task Scheduler failure that survives formatting and process boundaries. */
+export class WindowsSchtasksError extends Error {
+  readonly code = "WINDOWS_SCHTASKS_ERROR" as const;
+
+  constructor(
+    readonly operation: WindowsSchtasksOperation,
+    readonly reason: WindowsSchtasksFailureReason,
+    message: string,
+  ) {
+    super(message);
+    this.name = "WindowsSchtasksError";
+  }
+
+  get machineMarker(): string | null {
+    return this.operation === "create" && this.reason === "access-denied"
+      ? WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER
+      : null;
+  }
+}
+
+export class WindowsElevationError extends Error {
+  readonly code = "WINDOWS_ELEVATION_ERROR" as const;
+
+  constructor(
+    readonly reason: WindowsElevationFailureReason,
+    message: string,
+  ) {
+    super(message);
+    this.name = "WindowsElevationError";
+  }
+}
+
+/** Replace raw schtasks access-denied output with dashboard-friendly guidance. */
+export function formatWindowsSchtasksError(error: unknown, args: string[]): string {
+  const operation = schtasksOperationFromArgs(args);
+  const ownedCreateAccessDenied = isWindowsSchtasksAccessDeniedError(error, args);
+  const accessDenied = ownedCreateAccessDenied || isWindowsAccessDeniedError(error);
+  if (!accessDenied) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  const argsText = args.map(arg => (/\s/.test(arg) ? `"${arg}"` : arg)).join(" ");
+  const guidance = [
+    "Windows access denied while running Task Scheduler.",
+    `Command: schtasks ${argsText}`,
+    "Approve the Windows UAC prompt to install the background service, or run `ocx service install` from an elevated PowerShell window.",
+  ].join(" ");
+  if (operation === "create" && ownedCreateAccessDenied) {
+    return `${guidance}\n${WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER}`;
+  }
+  return guidance;
+}
+
+export function toWindowsSchtasksError(error: unknown, args: string[]): WindowsSchtasksError {
+  if (error instanceof WindowsSchtasksError) return error;
+  const operation = schtasksOperationFromArgs(args);
+  const reason: WindowsSchtasksFailureReason = isWindowsSchtasksAccessDeniedError(error, args)
+    ? "access-denied"
+    : "other";
+  return new WindowsSchtasksError(operation, reason, formatWindowsSchtasksError(error, args));
+}
+
+/**
+ * Quote one argument for Win32 CommandLineToArgvW / Start-Process -ArgumentList.
+ * Handles empty args, spaces, embedded quotes, and trailing backslashes.
+ */
+export function windowsCmdQuote(value: string): string {
+  if (value.length === 0) return '""';
+  if (!/[\s"]/.test(value)) return value;
+  let result = '"';
+  let numBackslashes = 0;
+  for (const ch of value) {
+    if (ch === "\\") {
+      numBackslashes += 1;
+      continue;
+    }
+    if (ch === '"') {
+      result += "\\".repeat(numBackslashes * 2 + 1) + '"';
+      numBackslashes = 0;
+      continue;
+    }
+    result += "\\".repeat(numBackslashes) + ch;
+    numBackslashes = 0;
+  }
+  result += "\\".repeat(numBackslashes * 2) + '"';
+  return result;
+}
+
+/** Build one Win32 argument-list string for Start-Process -ArgumentList. */
+export function buildWindowsElevatedArgumentList(args: string[]): string {
+  return args.map(windowsCmdQuote).join(" ");
+}
+
+/** Classify an elevated-process exit code into a stable scheduler outcome. */
+export function classifyElevatedSchedulerExitCode(exitCode: number): ElevatedSchedulerOutcome {
+  if (exitCode === OCX_ELEVATED_SUCCESS) return "success";
+  if (exitCode === OCX_ELEVATED_CREATE_FAILED) return "create-failed";
+  if (exitCode === OCX_ELEVATED_RUN_FAILED_ROLLED_BACK) return "run-failed-rolled-back";
+  if (exitCode === OCX_ELEVATED_RUN_FAILED_ROLLBACK_FAILED) return "run-failed-rollback-failed";
+  // Malformed / unexpected / missing-ExitCode-normalized codes fail closed.
+  return "protocol-failed";
+}
+
+function windowsPowerShell(): string {
+  return resolveTrustedWindowsPowerShellExe();
+}
+
+function psSingleQuote(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+function appendBounded(current: string, chunk: string, limit = ELEVATION_OUTPUT_LIMIT): string {
+  if (current.length >= limit) return current;
+  const remaining = limit - current.length;
+  return current + chunk.slice(0, remaining);
+}
+
+export interface WindowsElevationResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface WindowsElevationExecution {
+  /** Settles only on launcher close/error — never killed by a request-level timeout. */
+  completion: Promise<WindowsElevationResult>;
+  launcherPid: number | null;
+}
+
+/** Request-facing wait for elevation; process observation continues separately. */
+export const ELEVATION_REQUEST_TIMEOUT_MS = 120_000;
+
+/**
+ * Wait for `promise` up to `timeoutMs` without cancelling it.
+ * On timeout the original promise remains active for late settlement.
+ */
+export function raceWithTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+): Promise<{ status: "completed"; value: T } | { status: "timed-out" }> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      resolve({ status: "timed-out" });
+    }, timeoutMs);
+    promise.then(
+      value => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({ status: "completed", value });
+      },
+      error => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Spawn non-elevated PowerShell to run a -Command script.
+ * Does not kill the launcher on any timeout — callers race a separate request timeout.
+ */
+export function startPowerShellCommand(commandScript: string): WindowsElevationExecution {
+  if (process.platform !== "win32") {
+    return {
+      launcherPid: null,
+      completion: Promise.reject(new WindowsElevationError(
+        "launch-failed",
+        "Windows elevation is only supported on Windows.",
+      )),
+    };
+  }
+
+  let child: ChildProcess;
+  try {
+    child = elevationSpawn(
+      windowsPowerShell(),
+      ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", commandScript],
+      {
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+  } catch (error) {
+    return {
+      launcherPid: null,
+      completion: Promise.reject(new WindowsElevationError(
+        "launch-failed",
+        error instanceof Error ? error.message : String(error),
+      )),
+    };
+  }
+
+  const completion = new Promise<WindowsElevationResult>((resolve, reject) => {
+    let settled = false;
+    let stdout = "";
+    let stderr = "";
+
+    const settle = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      fn();
+    };
+
+    child.stdout?.setEncoding?.("utf8");
+    child.stderr?.setEncoding?.("utf8");
+    child.stdout?.on("data", (chunk: string | Buffer) => {
+      stdout = appendBounded(stdout, typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+    });
+    child.stderr?.on("data", (chunk: string | Buffer) => {
+      stderr = appendBounded(stderr, typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+    });
+
+    child.once("error", (error: NodeJS.ErrnoException) => {
+      settle(() => reject(new WindowsElevationError(
+        "launch-failed",
+        error.code === "ENOENT"
+          ? "Windows PowerShell was not found for elevation."
+          : (error.message || "Windows elevation failed to launch."),
+      )));
+    });
+
+    child.once("close", (code, signal) => {
+      const detail = [stderr.trim(), stdout.trim()].filter(Boolean).join("\n");
+      if (typeof code === "number") {
+        // Only treat UAC-cancellation text as cancelled when the process did not succeed.
+        if (
+          code === OCX_ELEVATED_UAC_CANCELLED
+          || (code !== 0 && windowsUacCancelledText(detail))
+        ) {
+          settle(() => reject(new WindowsElevationError(
+            "cancelled",
+            "Windows administrator approval was required, but the UAC prompt was cancelled or denied.",
+          )));
+          return;
+        }
+        settle(() => resolve({ exitCode: code, stdout, stderr }));
+        return;
+      }
+      // Launcher terminated without an exit code — elevated child may still exist.
+      settle(() => reject(new WindowsElevationError(
+        "terminated",
+        `Windows elevation terminated by ${signal ?? "unknown signal"}.`,
+      )));
+    });
+  });
+
+  return { completion, launcherPid: child.pid ?? null };
+}
+
+/**
+ * Launch a file with UAC elevation and wait for it to exit.
+ * Throws WindowsElevationError for cancellation, launch failure, or signal termination.
+ * Returns the elevated process exit code for completed launches (including non-zero).
+ */
+export function runWindowsElevated(file: string, args: string[]): Promise<number> {
+  const argumentList = buildWindowsElevatedArgumentList(args);
+  // Touch .Handle so Windows PowerShell 5.1 keeps a process handle; ExitCode can
+  // otherwise stay $null after -Wait and `exit $null` becomes exit 0 (false success).
+  const script = [
+    `$p = Start-Process -FilePath ${psSingleQuote(file)}`,
+    argumentList.length > 0 ? ` -ArgumentList ${psSingleQuote(argumentList)}` : "",
+    " -Verb RunAs -WindowStyle Hidden -PassThru -Wait;",
+    `if ($null -eq $p) { exit ${OCX_ELEVATED_UAC_CANCELLED} }`,
+    "$null = $p.Handle;",
+    // Missing ExitCode is a protocol failure for single-file elevation (not success).
+    `if ($null -eq $p.ExitCode) { exit ${OCX_ELEVATED_PROTOCOL_FAILED} }`,
+    "exit $p.ExitCode",
+  ].join("");
+
+  return startPowerShellCommand(script).completion.then(result => result.exitCode);
+}
+
+/**
+ * Build the elevated (post-UAC) script: create → run → optional delete rollback.
+ * Returns only OpenCodex protocol exit codes (never raw schtasks codes, never 1223).
+ * Does not write through any user-controlled pathname.
+ */
+export function buildElevatedSchtasksCreateAndRunScript(
+  schtasksPath: string,
+  createArgs: string[],
+  runArgs: string[],
+  deleteArgs: string[],
+): string {
+  const createList = buildWindowsElevatedArgumentList(createArgs);
+  const runList = buildWindowsElevatedArgumentList(runArgs);
+  const deleteList = buildWindowsElevatedArgumentList(deleteArgs);
+  return [
+    `$schtasks = ${psSingleQuote(schtasksPath)}`,
+    "function Invoke-OcxSchtasks([string]$ArgList) {",
+    "  $p = Start-Process -FilePath $schtasks -ArgumentList $ArgList -Wait -PassThru -WindowStyle Hidden",
+    "  if ($null -eq $p) { return 1 }",
+    "  $null = $p.Handle",
+    "  if ($null -eq $p.ExitCode) { return 1 }",
+    "  return [int]$p.ExitCode",
+    "}",
+    `$createCode = Invoke-OcxSchtasks ${psSingleQuote(createList)}`,
+    `if ($createCode -ne 0) { exit ${OCX_ELEVATED_CREATE_FAILED} }`,
+    `$runCode = Invoke-OcxSchtasks ${psSingleQuote(runList)}`,
+    `if ($runCode -eq 0) { exit ${OCX_ELEVATED_SUCCESS} }`,
+    `$deleteCode = Invoke-OcxSchtasks ${psSingleQuote(deleteList)}`,
+    `if ($deleteCode -eq 0) { exit ${OCX_ELEVATED_RUN_FAILED_ROLLED_BACK} }`,
+    `exit ${OCX_ELEVATED_RUN_FAILED_ROLLBACK_FAILED}`,
+  ].join("; ");
+}
+
+export interface ElevatedSchtasksCreateAndRunResult {
+  outcome: ElevatedSchedulerOutcome;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface ElevatedSchtasksCreateAndRunExecution {
+  completion: Promise<ElevatedSchtasksCreateAndRunResult>;
+  launcherPid: number | null;
+}
+
+/**
+ * Start create/run/rollback inside one elevated PowerShell process (one UAC prompt).
+ * The completion promise outlives any request-level timeout — do not kill the launcher.
+ */
+export function startElevatedSchtasksCreateAndRun(
+  schtasksPath: string,
+  createArgs: string[],
+  runArgs: string[],
+  deleteArgs: string[],
+): ElevatedSchtasksCreateAndRunExecution {
+  const inner = buildElevatedSchtasksCreateAndRunScript(schtasksPath, createArgs, runArgs, deleteArgs);
+  const launcher = [
+    `$p = Start-Process -FilePath ${psSingleQuote(windowsPowerShell())}`,
+    ` -ArgumentList ${psSingleQuote(buildWindowsElevatedArgumentList([
+      "-NoProfile",
+      "-NonInteractive",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-Command",
+      inner,
+    ]))}`,
+    " -Verb RunAs -WindowStyle Hidden -PassThru -Wait;",
+    `if ($null -eq $p) { exit ${OCX_ELEVATED_UAC_CANCELLED} }`,
+    "$null = $p.Handle;",
+    `if ($null -eq $p.ExitCode) { exit ${OCX_ELEVATED_PROTOCOL_FAILED} }`,
+    "exit $p.ExitCode",
+  ].join("");
+
+  const started = startPowerShellCommand(launcher);
+  return {
+    launcherPid: started.launcherPid,
+    completion: started.completion.then(result => ({
+      outcome: classifyElevatedSchedulerExitCode(result.exitCode),
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    })),
+  };
+}
+
+/**
+ * Create, run, and (on /run failure) roll back the scheduler task inside one elevated
+ * PowerShell process — one UAC prompt, no user-controlled result file.
+ * Waits for the full elevated transaction (no request-timeout kill).
+ */
+export function runElevatedSchtasksCreateAndRun(
+  schtasksPath: string,
+  createArgs: string[],
+  runArgs: string[],
+  deleteArgs: string[],
+): Promise<ElevatedSchtasksCreateAndRunResult> {
+  return startElevatedSchtasksCreateAndRun(schtasksPath, createArgs, runArgs, deleteArgs).completion;
+}