@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
814 lines (757 loc) • 35.2 kB
text/typescript
import { execFileSync } from "node:child_process";
import { findLiveProxy } from "../server/proxy-liveness";
import { existsSync, readFileSync } from "node:fs";
import { randomUUID } from "node:crypto";
import { ELEVATION_REQUEST_TIMEOUT_MS, OCX_ELEVATED_PROTOCOL_FAILED, raceWithTimeout, resolveTrustedWindowsSchtasksExe, startElevatedSchtasksCreateAndRun, runWindowsElevated, toWindowsSchtasksError, WindowsElevationError, type ElevatedSchedulerOutcome, type ElevatedSchtasksCreateAndRunExecution, type ElevatedSchtasksCreateAndRunResult } from "../lib/windows-elevation";
import { statusWinswRaw } from "../lib/winsw";
import { decodeWindowsTextBytes, type WindowsTextDecodeOptions } from "../lib/windows-text";
import { isTestHomeGuardArmed } from "../lib/test-home-guard";
import { TASK, windowsServiceScriptPath, windowsLauncherVbsPath, windowsTaskXmlPath, writeServiceInstallState } from "./state";
import { buildWindowsSchtasksCreateArgs, windowsTaskRegistrationOwnedByAttempt, windowsTaskRegistrationHealthy } from "./windows-taskxml";
import type { ExpectedWindowsTaskUserId } from "./windows-taskxml";
import { WINSW_SERVICE_ID } from "../lib/winsw";
export { windowsWscript } from "./windows-wscript";
/**
* Decode schtasks stdout. `/query /xml` emits UTF-16LE (often with BOM) because the
* registered task document is UTF-16; reading that as UTF-8 makes every health check
* fail ("registration present but unhealthy") and rolls back a successful elevated create.
*
* Redirected output is NOT always UTF-16. Its encoding follows the console output code
* page of the spawning process tree rather than the XML declaration, so on a zh-CN host
* (ACP/OEMCP 936) the bytes are GBK — including inside a no-console background service.
* Decoding those as UTF-8 turned a CJK account name in
* `<SessionStateChangeTrigger><UserId>` into U+FFFD, the trigger scope then failed to
* match the correctly resolved `[SID, MACHINE\<name>]`, and `ocx service repair`
* aborted at its recognition gate on a registration OpenCodex had itself created. The
* same mojibake rolled back fresh installs at post-create verification (#4691).
*
* The fix is entirely in byte decoding, before any XML is parsed. The trigger scope stays
* an exact identity comparison: forgiving a replacement character there would let two
* different non-ASCII accounts collapse to the same value, which is a worse failure than
* the refusal it replaces.
*
* `decodeWindowsTextBytes` is the decoder this project already built for this class
* (UTF-16 -> strict UTF-8 -> the locale's legacy code page), and it already fixed the
* sibling `whoami`/PowerShell decode in `src/lib/windows-user-principal.ts` (#2914, and
* #722 for CP949). This call site was the last one still ending in a lossy UTF-8 decode.
*/
export function decodeSchtasksOutput(
buffer: Buffer,
options: WindowsTextDecodeOptions = {},
): string {
// `options` exists so a test can pin the code page; every production call passes the
// buffer alone and uses the active Intl locale, which is available to a service with no
// console because the selection reads the process locale rather than a console handle.
return decodeWindowsTextBytes(buffer, options);
}
/**
* Every schtasks operation is sub-second on a healthy system; a wedged Task
* Scheduler service must not block a guarded stop forever. A killed command
* throws into the same unreadable/failed classification a nonzero exit would —
* the guarded verdicts stay fail-closed either way.
*/
const SCHTASKS_TIMEOUT_MS = 15_000;
function runFile(file: string, args: string[]): string {
const buffer = execFileSync(file, args, {
encoding: "buffer",
stdio: ["ignore", "pipe", "pipe"],
windowsHide: true,
timeout: SCHTASKS_TIMEOUT_MS,
}) as Buffer;
return decodeSchtasksOutput(buffer);
}
function windowsSchtasks(): string {
return resolveTrustedWindowsSchtasksExe();
}
let querySchtasksForTests: ((args: string[]) => string) | null = null;
export function querySchtasks(args: string[], beforeMutation?: () => void): string {
// The repository preload isolates HOME and OPENCODEX_HOME, but Task Scheduler is
// machine-global. A partially-faked service test once fell through here and replaced the
// user's real `opencodex-proxy` task with a launcher inside its temporary test home; the
// test passed and cleanup deleted that launcher. Queries are observation-only, but every
// other operation must be injected while the explicit test-home guard is armed.
if (
isTestHomeGuardArmed()
&& args[0]?.trim().toLowerCase() !== "/query"
) {
throw new Error(
"refusing to mutate the machine-global Windows Task Scheduler from an armed test process; "
+ "inject the scheduler operation instead of calling the live manager.",
);
}
if (querySchtasksForTests) { beforeMutation?.(); return querySchtasksForTests(args); }
const file = windowsSchtasks();
beforeMutation?.();
return runFile(file, args);
}
/** Test-only seam for Task Scheduler query used by presence probes. */
export function setQuerySchtasksForTests(next: ((args: string[]) => string) | null): void {
querySchtasksForTests = next;
}
export function schtasks(args: string[], control: (() => void) | {
run?: (args: string[]) => string;
probeTask?: () => WindowsSchedulerTaskProbe;
} = {}): string {
const beforeMutation = typeof control === "function" ? control : undefined;
const io = typeof control === "function" ? {} : control;
let refused = false;
const gate = beforeMutation && (() => { try { beforeMutation(); } catch (error) { refused = true; throw error; } });
try {
return io.run ? io.run(args) : querySchtasks(args, gate);
} catch (error) {
if (refused) throw error;
let taskPresent = false;
const normalized = args.map(arg => arg.toLowerCase());
const taskIndex = normalized.indexOf("/tn");
if (normalized[0] === "/delete" && taskIndex > 0 && normalized[taskIndex + 1] === TASK
&& error && typeof error === "object" && "status" in error && error.status === 1) {
try {
taskPresent = (io.probeTask ?? probeWindowsSchedulerTask)().status === "present";
} catch { /* An unreadable task is not proof of an access denial. */ }
}
throw toWindowsSchtasksError(error, args, taskPresent);
}
}
/** Tri-state Task Scheduler presence: never treat a failed query as proven absence. */
export type WindowsSchedulerTaskProbe =
| { status: "present" }
| { status: "absent" }
| { status: "unknown"; detail: string };
export type WindowsSchedulerProxyProbe =
| { status: "running"; port: number }
| { status: "not-running" }
| { status: "unknown" };
/**
* Render Task Scheduler status without exposing localized `schtasks` table output.
* The task probe answers installation state; the identity-checked health probe answers
* runtime state. Keep probe details out of this user-facing line because they can contain
* incorrectly decoded, locale-specific command output.
*/
export function formatWindowsSchedulerServiceStatus(
task: WindowsSchedulerTaskProbe,
proxy: WindowsSchedulerProxyProbe,
): string {
if (task.status === "present") {
if (proxy.status === "running") {
return `✅ service installed (Task Scheduler); OpenCodex proxy running on port ${proxy.port}.`;
}
if (proxy.status === "not-running") {
return "⚠️ service installed (Task Scheduler); OpenCodex proxy not running.";
}
return "⚠️ service installed (Task Scheduler); OpenCodex proxy status unknown.";
}
if (task.status === "absent") {
if (proxy.status === "running") {
return `❌ service not installed (Task Scheduler); OpenCodex proxy is running independently on port ${proxy.port}.`;
}
if (proxy.status === "unknown") {
return "❌ service not installed (Task Scheduler); OpenCodex proxy status unknown.";
}
return "❌ service not installed (Task Scheduler).";
}
if (proxy.status === "running") {
return `⚠️ Task Scheduler registration unknown; OpenCodex proxy running on port ${proxy.port}.`;
}
if (proxy.status === "not-running") {
return "⚠️ service status unknown (Task Scheduler query failed); OpenCodex proxy not running.";
}
return "⚠️ service status unknown (Task Scheduler and proxy checks failed).";
}
export async function inspectWindowsSchedulerServiceStatus(io: {
probeTask?: () => WindowsSchedulerTaskProbe;
findProxy?: () => Promise<{ port: number } | null>;
} = {}): Promise<string> {
let task: WindowsSchedulerTaskProbe;
try {
task = (io.probeTask ?? probeWindowsSchedulerTask)();
} catch (error) {
task = { status: "unknown", detail: schtasksErrorDetail(error) };
}
let proxy: WindowsSchedulerProxyProbe;
try {
const live = await (io.findProxy ?? findLiveProxy)();
proxy = live ? { status: "running", port: live.port } : { status: "not-running" };
} catch {
proxy = { status: "unknown" };
}
return formatWindowsSchedulerServiceStatus(task, proxy);
}
export function schtasksErrorDetail(error: unknown): string {
if (error && typeof error === "object"
&& ("status" in error || "stderr" in error || "stdout" in error)) {
return toWindowsSchtasksError(error, ["/query"]).message;
}
return error instanceof Error ? error.message : String(error);
}
/**
* True when a schtasks CSV listing line refers to the given task name.
* "Given task name" means the task of that name in the ROOT folder — the only
* one every `/tn` operation here can address; a same-named task inside a task
* folder is a different registration and must not count.
*/
export function windowsSchedulerCsvIncludesTask(csv: string, taskName: string): boolean {
const needle = taskName.toLowerCase();
for (const line of csv.split(/\r?\n/)) {
const lower = line.toLowerCase();
if (!lower.includes(needle)) continue;
// Prefer exact CSV field matches ("\TaskName" / "TaskName") before a looser
// boundary hit. A bare backslash is NOT a boundary: `folder\name` is a path
// separator, not the root task — every /tn operation here resolves a bare
// name in the root folder only, so `,\Tools\opencodex-proxy,` is a different
// registration this probe can neither read nor stop. The optional `\\?`
// covers the unquoted root form `,\opencodex-proxy,` only.
if (
lower.includes(`"\\${needle}"`)
|| lower.includes(`"${needle}"`)
|| new RegExp(`(^|,)\\\\?${needle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([,"]|$)`).test(lower)
) {
return true;
}
}
return false;
}
/**
* Probe whether the OpenCodex Task Scheduler task exists.
* Query failures fall back to a CSV listing before concluding absence; if both
* fail, returns `unknown` so callers can fail closed instead of releasing locks.
*/
export function probeWindowsSchedulerTask(taskName = TASK): WindowsSchedulerTaskProbe {
if (process.platform !== "win32") return { status: "absent" };
let queryFailure: string | null = null;
try {
const out = querySchtasks(["/query", "/tn", taskName]);
if (out.includes(taskName)) return { status: "present" };
} catch (error) {
queryFailure = schtasksErrorDetail(error);
}
try {
const csv = querySchtasks(["/query", "/fo", "CSV"]);
if (windowsSchedulerCsvIncludesTask(csv, taskName)) return { status: "present" };
return { status: "absent" };
} catch (error) {
const listDetail = schtasksErrorDetail(error);
const detail = queryFailure
? `Specific query failed (${queryFailure}); CSV listing also failed (${listDetail}).`
: `Task query did not confirm presence and CSV listing failed (${listDetail}).`;
return { status: "unknown", detail };
}
}
/** True when the Task Scheduler registration for the default proxy task is proven present. */
export function windowsSchedulerTaskInstalled(taskName = TASK): boolean {
return probeWindowsSchedulerTask(taskName).status === "present";
}
export interface WindowsSchedulerInstallVerification {
taskInstalled: boolean;
registrationHealthy: boolean;
/** Well-formed XML that is PUBLISHED but policy-violating — permanent, never
* worth a settle retry (vs an empty/unreadable view, which is publication
* lag and transient). */
registrationInvalid: boolean;
assetsHealthy: boolean;
nativeServiceAbsent: boolean;
/** True when SCM probe failed; not a proven WinSW presence. */
nativeStatusUnknown: boolean;
conflict: boolean;
ok: boolean;
detail: string;
}
/** Pure postcondition evaluation for an elevated scheduler install. */
export function evaluateWindowsSchedulerInstallVerification(inputs: {
taskInstalled: boolean;
xml: string;
assetsExist: boolean;
nativeStatus: "started" | "stopped" | "nonexistent" | "unknown";
wscript?: string;
launcher?: string;
expectedUserId?: ExpectedWindowsTaskUserId | null;
}): WindowsSchedulerInstallVerification {
const registrationHealthy = inputs.xml.length > 0
&& windowsTaskRegistrationHealthy(inputs.xml, inputs.wscript, inputs.launcher, inputs.expectedUserId);
// Permanent invalidity: the XML IS published but violates the registration
// contract — no amount of settling changes it. Empty/unreadable XML stays
// transient (publication lag).
const registrationInvalid = inputs.taskInstalled && inputs.xml.length > 0 && !registrationHealthy;
const assetsHealthy = inputs.assetsExist;
const nativeServiceAbsent = inputs.nativeStatus === "nonexistent";
const nativeStatusUnknown = inputs.nativeStatus === "unknown";
// Only treat proven WinSW presence as a backend conflict — never "unknown".
const conflict = inputs.taskInstalled
&& (inputs.nativeStatus === "started" || inputs.nativeStatus === "stopped");
const ok = inputs.taskInstalled && registrationHealthy && assetsHealthy && nativeServiceAbsent && !conflict;
const detail = !inputs.taskInstalled
? "Task Scheduler task is not installed."
: conflict
? `CONFLICT: Task Scheduler and native WinSW (${WINSW_SERVICE_ID}) are both present.`
: !assetsHealthy
? "Required scheduler service assets are missing."
: !registrationHealthy
? (inputs.xml.trim()
? "Task Scheduler registration is present but unhealthy."
: "Task Scheduler task is present but its XML could not be read.")
: nativeStatusUnknown
? "The Task Scheduler task was created, but OpenCodex could not verify that the native WinSW service is absent."
: "ok";
return {
taskInstalled: inputs.taskInstalled,
registrationHealthy,
registrationInvalid,
assetsHealthy,
nativeServiceAbsent,
nativeStatusUnknown,
conflict,
ok,
detail,
};
}
/** Conflict-free postcondition check for an elevated scheduler install. */
export function verifyWindowsSchedulerInstall(taskName = TASK): WindowsSchedulerInstallVerification {
const taskInstalled = windowsSchedulerTaskInstalled(taskName);
let xml = "";
if (taskInstalled) {
try { xml = querySchtasks(["/query", "/tn", taskName, "/xml"]); } catch { xml = ""; }
}
// After elevated create, non-elevated `/query /xml` can fail or return empty while the
// task is still listed. Fall back to the on-disk document we registered.
if (taskInstalled && !xml.trim()) {
const diskPath = windowsTaskXmlPath();
if (existsSync(diskPath)) {
try { xml = decodeSchtasksOutput(readFileSync(diskPath)); } catch { /* keep empty */ }
}
}
return evaluateWindowsSchedulerInstallVerification({
taskInstalled,
xml,
assetsExist: [windowsServiceScriptPath(), windowsLauncherVbsPath(), windowsTaskXmlPath()].every(existsSync),
nativeStatus: statusWinswRaw(),
});
}
async function elevateSchtasks(args: string[]): Promise<void> {
const exitCode = await runWindowsElevated(windowsSchtasks(), args);
if (exitCode !== 0) {
throw new Error(`Background service install failed with exit code ${exitCode}.`);
}
}
export interface WindowsSchedulerRollbackDeps {
queryXml?: () => string;
deleteTask?: () => Promise<void>;
probe?: () => WindowsSchedulerTaskProbe;
}
export async function rollbackWindowsSchedulerTaskOwnedByAttempt(
attemptNonce: string,
taskName = TASK,
deps: WindowsSchedulerRollbackDeps = {},
): Promise<string | null> {
let registeredXml = "";
try {
registeredXml = (deps.queryXml ?? (() => querySchtasks(["/query", "/tn", taskName, "/xml"])))();
} catch (error) {
const detail = error instanceof Error ? error.message : String(error);
return `Task Scheduler task ${taskName} ownership could not be proven: ${detail}. Residual scheduler state: task ${taskName} presence is unknown; no rollback deletion was attempted.`;
}
if (!registeredXml.trim()) {
return `Task Scheduler task ${taskName} ownership could not be proven because its live XML was empty. Residual scheduler state: task ${taskName} presence is unknown; no rollback deletion was attempted.`;
}
if (!windowsTaskRegistrationOwnedByAttempt(registeredXml, attemptNonce)) {
return `Task Scheduler task ${taskName} ownership could not be proven because its attempt nonce does not match. Residual scheduler state: task ${taskName} remains registered; no rollback deletion was attempted.`;
}
try {
await (deps.deleteTask ?? (() => elevateSchtasks(["/delete", "/tn", taskName, "/f"])))();
} catch (error) {
const detail = error instanceof Error ? error.message : String(error);
return `Rollback deletion failed: ${detail}. Residual scheduler state: task ${taskName} may remain registered.`;
}
const probe = (deps.probe ?? (() => resolveWindowsSchedulerTaskProbe(taskName)))();
if (probe.status === "absent") return null;
if (probe.status === "unknown") {
return `Task Scheduler task ${taskName} presence could not be verified after rollback: ${probe.detail}. Residual scheduler state: task presence is unknown.`;
}
return `Residual scheduler state: task ${taskName} is still present after rollback.`;
}
// Legacy dashboard finalization creates and runs in one elevated child, whose protocol
// performs its own rollback before returning. This fallback remains for indeterminate
// protocol outcomes that predate the staged CLI transaction.
async function rollbackElevatedSchedulerTask(taskName = TASK): Promise<string | null> {
try {
await elevateSchtasks(["/delete", "/tn", taskName, "/f"]);
} catch (error) {
return error instanceof Error ? error.message : String(error);
}
const probe = resolveWindowsSchedulerTaskProbe(taskName);
if (probe.status === "absent") return null;
if (probe.status === "unknown") {
return `Task Scheduler task ${taskName} presence could not be verified after rollback: ${probe.detail}`;
}
return `Task Scheduler task ${taskName} is still present after rollback.`;
}
type ElevateCreateAndRunStart = (
schtasksPath: string,
createArgs: string[],
runArgs: string[],
deleteArgs: string[],
) => ElevatedSchtasksCreateAndRunExecution;
type FinalizeHooks = {
startElevateCreateAndRun?: ElevateCreateAndRunStart;
/** Legacy sync hook used by older tests — wraps a resolved result as an execution. */
elevateCreateAndRun?: (
schtasksPath: string,
createArgs: string[],
runArgs: string[],
deleteArgs: string[],
) => Promise<ElevatedSchtasksCreateAndRunResult>;
verify?: () => WindowsSchedulerInstallVerification;
writeInstallState?: () => void;
/** Preferred tri-state probe for security-sensitive reconciliation. */
probeTask?: () => WindowsSchedulerTaskProbe;
/** Legacy boolean hook; mapped to present/absent when probeTask is unset. */
taskInstalled?: () => boolean;
/** Defense-in-depth: late reconciliation must still own this attempt. */
stillOwnsAttempt?: (attemptId: string) => boolean;
requestTimeoutMs?: number;
/** Test-only seam for the post-create settle backoff; real installs use a timer. */
settleDelay?: (ms: number) => Promise<void>;
};
let finalizeHooks: FinalizeHooks | null = null;
function resolveWindowsSchedulerTaskProbe(taskName = TASK): WindowsSchedulerTaskProbe {
if (finalizeHooks?.probeTask) return finalizeHooks.probeTask();
if (finalizeHooks?.taskInstalled) {
return finalizeHooks.taskInstalled() ? { status: "present" } : { status: "absent" };
}
return probeWindowsSchedulerTask(taskName);
}
/** Test-only hooks for elevated create+run finalization. */
export function setFinalizeWindowsSchedulerHooksForTests(hooks: FinalizeHooks | null): void {
finalizeHooks = hooks;
}
function throwPartialInstall(parts: string[]): never {
throw new Error(parts.filter(Boolean).join(" "));
}
/**
* Reconcile an unrecognized elevated exit when we cannot trust the phase code.
* Never invent a create-vs-run classification; inspect actual task state first.
* An unverifiable probe must fail closed (partial / blocked), never release.
*/
async function reconcileUnknownElevatedOutcome(exitCode: number): Promise<void> {
const probe = resolveWindowsSchedulerTaskProbe();
const parts = [
"The elevated Task Scheduler operation returned an unknown result.",
`Exit code: ${exitCode}.`,
"OpenCodex could not prove whether task creation completed, so installation state was not written.",
];
if (probe.status === "unknown") {
parts.push(`Task Scheduler presence could not be verified: ${probe.detail}`);
parts.push("A partial Task Scheduler backend may remain.");
throwPartialInstall(parts);
}
if (probe.status === "absent") {
parts.push("No OpenCodex Task Scheduler task was found after the elevated operation.");
throwPartialInstall(parts);
}
parts.push("A Task Scheduler task is present; attempting cleanup.");
const rollbackError = await rollbackElevatedSchedulerTask();
if (rollbackError) {
parts.push(`Cleanup also failed: ${rollbackError}`);
parts.push(`Remove the task manually with 'schtasks /delete /tn ${TASK} /f' if it remains.`);
} else {
parts.push("The elevated Task Scheduler task was removed.");
}
throwPartialInstall(parts);
}
type ApplyElevatedOptions = {
attemptId: string;
writeOnSuccess: boolean;
stillOwnsAttempt?: (attemptId: string) => boolean;
};
function attemptStillOwned(options: ApplyElevatedOptions): boolean {
const check = options.stillOwnsAttempt ?? finalizeHooks?.stillOwnsAttempt;
return !check || check(options.attemptId);
}
/**
* Bounded post-create backoff, 1.1s total. Task Scheduler's non-elevated view can
* lag an elevated `/create` by a few hundred milliseconds, so a single verification
* would roll back a task that is merely not visible yet.
*/
export const SCHEDULER_SETTLE_DELAYS_MS = [50, 150, 300, 600] as const;
/**
* Whether a failed verification is still worth re-checking after a short delay.
*
* Retrying is confined to states that a lagging scheduler view actually produces:
* the task is not visible yet, or it is visible but its registration has not been
* published in full. Everything else keeps its existing fail-closed meaning and is
* rejected here so no delay can turn it into a pass:
*
* - a proven conflict (both backends present) is a real dual-backend install;
* - missing assets are missing on disk, which no amount of waiting creates;
* - a WinSW service that is proven present (`started`/`stopped`) is never absent
* later. This is checked independently of `conflict`, which only becomes true
* once the task itself is visible — while the task is still invisible the pair
* is `conflict: false` with `nativeServiceAbsent: false`, and that must not retry;
* - unknown SCM status is unproven rather than transient, and has its own
* task-preserving branch below.
*/
/** Exported for tests: the transient-vs-permanent settle decision. */
export function schedulerVerificationMaySettle(v: WindowsSchedulerInstallVerification): boolean {
if (v.ok) return false;
if (v.conflict) return false;
if (!v.assetsHealthy) return false;
if (!v.nativeServiceAbsent) return false;
// A published-but-invalid registration is permanent: no delay repairs it.
if (v.registrationInvalid) return false;
return !v.taskInstalled || !v.registrationHealthy;
}
export function settleDelay(ms: number): Promise<void> {
const hook = finalizeHooks?.settleDelay;
if (hook) return hook(ms);
return new Promise(resolve => setTimeout(resolve, ms));
}
/**
* Verify the elevated install, re-checking only while the failure looks like a
* scheduler view that has not caught up yet. Returns `null` when this attempt lost
* ownership mid-settle: a newer attempt owns the task, so this one must neither
* write install state nor roll anything back.
*/
async function verifyWindowsSchedulerInstallAfterSettle(
options: ApplyElevatedOptions,
): Promise<WindowsSchedulerInstallVerification | null> {
const verify = finalizeHooks?.verify ?? verifyWindowsSchedulerInstall;
let verification = verify();
for (const delayMs of SCHEDULER_SETTLE_DELAYS_MS) {
if (!schedulerVerificationMaySettle(verification)) break;
if (!attemptStillOwned(options)) return null;
await settleDelay(delayMs);
if (!attemptStillOwned(options)) return null;
verification = verify();
}
return verification;
}
async function applyElevatedSchedulerResult(
result: ElevatedSchtasksCreateAndRunResult,
options: ApplyElevatedOptions,
): Promise<void> {
if (!attemptStillOwned(options)) {
return;
}
const outcome: ElevatedSchedulerOutcome = result.outcome;
if (outcome === "create-failed") {
throw new Error("Elevated schtasks /create failed. The Task Scheduler task was not registered.");
}
if (outcome === "run-failed-rolled-back") {
throw new Error(
"Elevated schtasks /run failed after the task was registered. The elevated process rolled the task back. Installation state was not written.",
);
}
if (outcome === "run-failed-rollback-failed") {
throwPartialInstall([
"Elevated schtasks /run failed after the task was registered, and elevated rollback also failed.",
"A partial Task Scheduler backend may remain.",
`Remove the task manually with 'schtasks /delete /tn ${TASK} /f' if present.`,
"Installation state was not written.",
]);
}
if (outcome !== "success") {
await reconcileUnknownElevatedOutcome(result.exitCode);
}
const verification = await verifyWindowsSchedulerInstallAfterSettle(options);
// Ownership moved to a newer attempt while settling; that attempt owns the outcome.
if (!verification) return;
if (!verification.ok) {
// Preserve a healthy elevated task when WinSW absence cannot be proven (unknown SCM status).
// Unknown is not a confirmed dual-backend conflict; install state is still withheld.
const preserveElevatedTask = verification.taskInstalled
&& verification.registrationHealthy
&& verification.assetsHealthy
&& !verification.conflict
&& verification.nativeStatusUnknown;
if (preserveElevatedTask) {
throwPartialInstall([
"Elevated Task Scheduler registration did not produce a conflict-free install.",
verification.detail,
"The elevated Task Scheduler task was left in place because native WinSW status could not be verified.",
"Installation state was not written.",
]);
}
// Rollback deletes a real task, so it needs the same ownership fence as the
// state write below: a stale attempt must never delete a newer attempt's task.
if (!attemptStillOwned(options)) return;
const rollbackError = await rollbackElevatedSchedulerTask();
const parts = [
"Elevated Task Scheduler registration did not produce a conflict-free install.",
verification.detail,
];
if (rollbackError) {
parts.push(`Rollback also failed: ${rollbackError}`);
parts.push(`Remove the task manually with 'schtasks /delete /tn ${TASK} /f' and the native service with 'sc delete ${WINSW_SERVICE_ID}' if present.`);
} else {
parts.push("The elevated Task Scheduler task was rolled back.");
}
parts.push("Installation state was not written.");
throwPartialInstall(parts);
}
if (options.writeOnSuccess) {
if (!attemptStillOwned(options)) {
return;
}
(finalizeHooks?.writeInstallState ?? (() => writeServiceInstallState("scheduler")))();
}
}
/** Outcome of late reconciliation after a request-level elevation timeout. */
export type ElevatedReconciliationOutcome =
| "released"
| "blocked-partial";
export type FinalizeWindowsSchedulerResult =
| { kind: "done" }
| {
kind: "indeterminate";
attemptId: string;
/** Settles after the elevated transaction finishes and late reconciliation runs. */
reconciliation: Promise<ElevatedReconciliationOutcome>;
};
export type FinalizeWindowsSchedulerOptions = {
attemptId?: string;
stillOwnsAttempt?: (attemptId: string) => boolean;
requestTimeoutMs?: number;
};
function startElevateExecution(
schtasksPath: string,
createArgs: string[],
runArgs: string[],
deleteArgs: string[],
): ElevatedSchtasksCreateAndRunExecution {
if (finalizeHooks?.startElevateCreateAndRun) {
return finalizeHooks.startElevateCreateAndRun(schtasksPath, createArgs, runArgs, deleteArgs);
}
if (finalizeHooks?.elevateCreateAndRun) {
const completion = finalizeHooks.elevateCreateAndRun(schtasksPath, createArgs, runArgs, deleteArgs);
return { completion, launcherPid: null };
}
return startElevatedSchtasksCreateAndRun(schtasksPath, createArgs, runArgs, deleteArgs);
}
function isPartialInstallError(error: unknown): boolean {
if (!(error instanceof Error)) return false;
return /partial Task Scheduler/i.test(error.message)
|| /Cleanup also failed/i.test(error.message)
|| /left in place because native WinSW status could not be verified/i.test(error.message)
|| /Task Scheduler presence could not be verified/i.test(error.message);
}
/**
* Re-register the scheduler task with elevation after a non-elevated install wrote assets.
*
* Request timeout does not kill the elevated launcher. On timeout this returns
* `indeterminate` and keeps reconciling the eventual protocol result.
*/
export async function finalizeWindowsSchedulerServiceRegistration(
script = windowsServiceScriptPath(),
options?: FinalizeWindowsSchedulerOptions,
): Promise<FinalizeWindowsSchedulerResult> {
if (process.platform !== "win32") {
throw new Error("Windows scheduler registration is only supported on Windows.");
}
const attemptId = options?.attemptId ?? randomUUID();
const stillOwnsAttempt = options?.stillOwnsAttempt ?? finalizeHooks?.stillOwnsAttempt;
const createArgs = buildWindowsSchtasksCreateArgs(script);
const runArgs = ["/run", "/tn", TASK];
const deleteArgs = ["/delete", "/tn", TASK, "/f"];
const started = startElevateExecution(windowsSchtasks(), createArgs, runArgs, deleteArgs);
const timeoutMs = options?.requestTimeoutMs
?? finalizeHooks?.requestTimeoutMs
?? ELEVATION_REQUEST_TIMEOUT_MS;
const applyOpts: ApplyElevatedOptions = { attemptId, writeOnSuccess: true, stillOwnsAttempt };
let raced: { status: "completed"; value: ElevatedSchtasksCreateAndRunResult } | { status: "timed-out" };
try {
raced = await raceWithTimeout(started.completion, timeoutMs);
} catch (error) {
// Cancellation / launch failure / signal before or instead of a protocol result.
// Signal after Start-Process may leave an elevated child; reconcile conservatively.
if (error instanceof WindowsElevationError && error.reason === "terminated") {
try {
await reconcileUnknownElevatedOutcome(OCX_ELEVATED_PROTOCOL_FAILED);
} catch (reconcileError) {
// Prefer the reconciliation detail (partial install / cleanup guidance) over the
// generic signal message so callers can block retries when a task remains.
throw reconcileError;
}
}
throw error;
}
if (raced.status === "completed") {
await applyElevatedSchedulerResult(raced.value, applyOpts);
return { kind: "done" };
}
const reconciliation = (async (): Promise<ElevatedReconciliationOutcome> => {
try {
const result = await started.completion;
await applyElevatedSchedulerResult(result, applyOpts);
return "released";
} catch (error) {
if (error instanceof WindowsElevationError && error.reason === "cancelled") {
return "released";
}
if (error instanceof WindowsElevationError && error.reason === "launch-failed") {
return "released";
}
if (error instanceof WindowsElevationError && error.reason === "terminated") {
try {
await reconcileUnknownElevatedOutcome(OCX_ELEVATED_PROTOCOL_FAILED);
return "released";
} catch (reconcileError) {
return isPartialInstallError(reconcileError) ? "blocked-partial" : "released";
}
}
// applyElevatedSchedulerResult failures are expected (create/run/conflict); swallow for background.
if (isPartialInstallError(error)) {
return "blocked-partial";
}
return "released";
}
})();
return { kind: "indeterminate", attemptId, reconciliation };
}
/**
* Pure post-restart / pre-install advisory check. Does not mutate state.
* A process-local indeterminate lock cannot survive restart — callers must inspect reality.
*/
export function evaluateSchedulerInstallRestartReconciliation(inputs: {
taskInstalled: boolean;
registrationHealthy: boolean;
assetsHealthy: boolean;
nativeStatus: "started" | "stopped" | "nonexistent" | "unknown";
installStateBackend: "scheduler" | "native" | null;
}): {
status: "healthy" | "orphan-task" | "stale-install-state" | "conflict" | "unhealthy" | "unverified";
detail: string;
} {
const conflict = inputs.taskInstalled
&& (inputs.nativeStatus === "started" || inputs.nativeStatus === "stopped");
if (conflict) {
return {
status: "conflict",
detail: `CONFLICT: Task Scheduler and native WinSW (${WINSW_SERVICE_ID}) are both present.`,
};
}
if (inputs.taskInstalled && inputs.nativeStatus === "unknown") {
return {
status: "unverified",
detail: "The Task Scheduler task exists, but native WinSW status could not be verified.",
};
}
if (inputs.taskInstalled && (!inputs.registrationHealthy || !inputs.assetsHealthy)) {
return {
status: "unhealthy",
detail: !inputs.assetsHealthy
? "Required scheduler service assets are missing."
: "Task Scheduler registration is present but unhealthy.",
};
}
if (inputs.taskInstalled && inputs.installStateBackend !== "scheduler") {
return {
status: "orphan-task",
detail: "A Task Scheduler task is present without matching scheduler install state.",
};
}
if (!inputs.taskInstalled && inputs.installStateBackend === "scheduler") {
return {
status: "stale-install-state",
detail: "Scheduler install state is present but the Task Scheduler task is absent.",
};
}
return { status: "healthy", detail: "ok" };
}