UNPKG

@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
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" }; }