@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
482 lines (456 loc) • 23.1 kB
text/typescript
/**
* Part A of the checked Windows service stop (#7771, 030 "Steps"): stop the manager, end
* the bound wrappers, then prove the manager inactive and every bound wrapper exited.
*
* Part A covers the manager and the wrappers only. The proxy child is stopped afterwards
* by the caller's graceful path (it may refuse, and a refusal forbids a forced stop), and
* the port is confirmed by Part B (src/service/windows-stop-confirm.ts).
*
* 1. Probe registration (task, WinSW; 2 s caps). An unreadable answer is unknown with
* nothing changed. With nothing registered, one enumeration (5 s) looks for a stray
* wrapper of a deleted task; unreadable, or nothing found, is absent.
* With a task registered or a stray sweep running, the Schedule host PID is read (2 s).
* Admission runs here, after the probe and before anything changes.
* 2. Bind (src/service/windows-stop-binding.ts) and open an exit watch per wrapper.
* 3. Ask the manager: verified Task Scheduler instances (2 s); WinSW a non-waiting stop (2 s) and an SCM poll
* capped at <stoptimeout> + 2 s. Denied is denied; an overrun is unknown; neither goes on.
* 4. Terminate the bound survivors through the checked primitive, deepest first.
* 5. Wait on the bind-time watches (steps 4 and 5 share 3 s), then read the manager state
* once (1 s). No enumeration and no PowerShell run in the wait.
*
* Every external effect is injected; nothing here touches the machine by itself, and
* nothing calls it yet.
*/
import type { WinswStatus } from "../lib/winsw";
import type { WindowsProcessWatch, WindowsTerminateResult } from "./windows-process-native";
import type { WindowsStopProcessEntry } from "./windows-process-evidence";
import type { WindowsSchedulerTaskProbe } from "./windows-scheduler";
import { bindWindowsStopWrappers, WRAPPER_OWNER_REFUSAL, type WindowsBoundWrapper, type WindowsStopBinding } from "./windows-stop-binding";
import {
DEFAULT_WINSW_STOP_TIMEOUT_MS,
WINDOWS_STOP_CAPS,
windowsStopWorstCase,
type WindowsStopBudgetInput,
} from "./windows-stop-budget";
type MaybePromise<T> = T | Promise<T>;
/** Monotonic clock and cancellable sleep; tests inject a virtual one. */
export interface WindowsStopClock {
now(): number;
sleep(ms: number, signal?: AbortSignal): Promise<void>;
}
export const windowsStopClock: WindowsStopClock = {
now: () => performance.now(),
sleep: (ms, signal) => new Promise(resolve => {
if (signal?.aborted) {
resolve();
return;
}
const done = (): void => {
clearTimeout(timer);
signal?.removeEventListener("abort", done);
resolve();
};
const timer = setTimeout(done, Math.max(0, ms));
signal?.addEventListener("abort", done, { once: true });
}),
};
export type WindowsStopReason = "access-denied" | "evidence-unreadable" | "unbound-wrapper" | "unverified-budget";
export type WindowsCheckedStopOutcome = "absent" | "stopped" | "survived" | "denied" | "unknown" | "unverified-budget";
export type WindowsTaskEndResult = "ended" | "not-running" | "denied" | "failed" | "unverified-registration";
export type WindowsWinswStopResult = "sent" | "denied" | "failed";
export type WindowsWinswScmState = "stopped" | "running" | "pending" | "nonexistent" | "unknown";
export interface WindowsCheckedStopDeps {
clock?: WindowsStopClock;
/** This home's canonical launcher VBS and service script paths. */
canonicalPaths: readonly string[];
/** The identity-checked proxy child (readPid), when known. */
childPid: number | null;
selfPid?: number;
probeScheduler(timeoutMs: number): MaybePromise<WindowsSchedulerTaskProbe>;
probeWinsw(timeoutMs: number): MaybePromise<WinswStatus>;
enumerate(timeoutMs: number): MaybePromise<readonly WindowsStopProcessEntry[] | null>;
scheduleServicePid(timeoutMs: number): MaybePromise<number | null>;
/** Reauthorize after proof; report mutation evidence separately from the final verdict. */
endTask(timeoutMs: number, authorize?: () => MaybePromise<void>, mutation?: (attempted: boolean, pending?: boolean) => void): MaybePromise<WindowsTaskEndResult>;
/** Running state of the task (schtasks /query); the final manager-state read. */
taskState(timeoutMs: number): MaybePromise<"running" | "not-running" | "unknown">;
winswStop(timeoutMs: number): MaybePromise<WindowsWinswStopResult>;
winswState(timeoutMs: number): MaybePromise<WindowsWinswScmState>;
/** The WinSW definition's <stoptimeout>; 20 s for the generated one. */
winswStopTimeoutMs?: number;
/** After WinSW reports stopped: is the proxy still alive? null = cannot tell. */
proxyAlive(timeoutMs: number): MaybePromise<boolean | null>;
openWatch(pid: number, startTime: number): MaybePromise<WindowsProcessWatch>;
terminate(pid: number, startTime: number, timeoutMs: number): MaybePromise<WindowsTerminateResult>;
}
export interface WindowsStopAdmission {
/** Absolute deadline on the deps clock. */
deadlineAt: number;
budget: Omit<WindowsStopBudgetInput, "managers" | "enumerationReused">;
}
export interface WindowsCheckedStopOptions {
/** A snapshot that already ran (guarded: revalidateManager's), reused for the bind. */
bindSnapshot?: readonly WindowsStopProcessEntry[];
admission?: WindowsStopAdmission;
/** Throws to refuse. Also runs after Scheduler proof, before the helper can stop any instance. */
authorize?: () => MaybePromise<void>;
/** Detached progress for an outer cap that must return before verification completes. */
onProgress?: (result: WindowsCheckedStopResult) => void;
}
export interface WindowsCheckedStopResult {
outcome: WindowsCheckedStopOutcome;
reason: WindowsStopReason | null;
/** Fixed text for logs and output; it never carries a path or a command line. */
detail: string;
registration: { scheduler: "present" | "absent" | "unknown"; winsw: WinswStatus };
/** The bound set (pid + creation time) for the later receipt record. */
bound: WindowsBoundWrapper[];
unbound: number[];
terminated: number[];
/** True once a manager stop or a terminate was attempted. */
changed: boolean;
budget?: { requiredMs: number; remainingMs: number };
}
export function snapshotWindowsCheckedStopResult(result: WindowsCheckedStopResult): WindowsCheckedStopResult {
return { ...result, registration: { ...result.registration }, bound: result.bound.map(wrapper => ({ ...wrapper })),
unbound: [...result.unbound], terminated: [...result.terminated],
...(result.budget ? { budget: { ...result.budget } } : {}) };
}
/** The authorizer refused; partial says what had already happened. */
export class WindowsCheckedStopRefusedError extends Error {
constructor(readonly partial: WindowsCheckedStopResult, options: { cause: unknown }) {
super("The checked Windows service stop was refused by its authorizer.", options);
this.name = "WindowsCheckedStopRefusedError";
}
}
const C = WINDOWS_STOP_CAPS;
const WINSW_POLL_INTERVAL_MS = 250;
const WATCH_POLL_INTERVAL_MS = 100;
const TIMED_OUT = Symbol("timed-out");
type Capped<T> = { ok: true; value: T } | { ok: false; timedOut: boolean };
/**
* Run one step under a cap. The race ends the wait for an asynchronous dependency; the
* elapsed check catches one that blocked past the cap anyway. Either is an overrun.
* A typed authorizer refusal propagates with the stop's partial result.
*/
export async function runCapped<T>(
clock: WindowsStopClock,
capMs: number,
run: (timeoutMs: number) => MaybePromise<T>,
): Promise<Capped<T>> {
if (capMs <= 0) return { ok: false, timedOut: true };
const started = clock.now();
const abort = new AbortController();
const work = Promise.resolve().then(() => run(capMs));
work.catch(() => undefined);
try {
const value = await Promise.race([work, clock.sleep(capMs, abort.signal).then(() => TIMED_OUT)]);
if (value === TIMED_OUT || clock.now() - started > capMs) return { ok: false, timedOut: true };
return { ok: true, value: value as T };
} catch (error) {
if (error instanceof WindowsCheckedStopRefusedError) throw error;
return { ok: false, timedOut: false };
} finally {
abort.abort();
}
}
export async function stopWindowsServiceChecked(
deps: WindowsCheckedStopDeps,
options: WindowsCheckedStopOptions = {},
): Promise<WindowsCheckedStopResult> {
const clock = deps.clock ?? windowsStopClock;
const watches = new Map<number, Extract<WindowsProcessWatch, { status: "open" }>>();
const result: WindowsCheckedStopResult = {
outcome: "unknown", reason: null, detail: "",
registration: { scheduler: "unknown", winsw: "unknown" },
bound: [], unbound: [], terminated: [], changed: false,
};
let pendingManagerMutation = false;
const publish = () => {
const snapshot = snapshotWindowsCheckedStopResult(result);
snapshot.changed ||= pendingManagerMutation;
options.onProgress?.(snapshot);
};
const finish = (outcome: WindowsCheckedStopOutcome, reason: WindowsStopReason | null, detail: string) => {
result.outcome = outcome;
result.reason = reason;
result.detail = detail;
publish();
return result;
};
const authorize = async (): Promise<void> => {
if (!options.authorize) return;
try {
await options.authorize();
} catch (cause) {
throw new WindowsCheckedStopRefusedError({ ...result, detail: "the authorizer refused the stop" }, { cause });
}
};
try {
await authorize();
// Step 1: registration.
const [scheduler, winsw] = await Promise.all([
runCapped(clock, C.registrationProbe, deps.probeScheduler),
runCapped(clock, C.registrationProbe, deps.probeWinsw),
]);
result.registration = {
scheduler: scheduler.ok && scheduler.value.status !== "unknown" ? scheduler.value.status : "unknown",
winsw: winsw.ok ? winsw.value : "unknown",
};
publish();
if (result.registration.scheduler === "unknown" || result.registration.winsw === "unknown") {
return finish("unknown", "evidence-unreadable", "the service registration could not be read");
}
const taskRegistered = result.registration.scheduler === "present";
const winswRegistered = result.registration.winsw !== "nonexistent";
const winswStarted = result.registration.winsw === "started";
const readSchedulePid = async (): Promise<number | null> => {
const pid = await runCapped(clock, C.scheduleServicePid, deps.scheduleServicePid);
return pid.ok ? pid.value : null;
};
const bindContext = {
canonicalPaths: deps.canonicalPaths,
childPid: deps.childPid,
selfPid: deps.selfPid ?? process.pid,
};
let binding: WindowsStopBinding | null = null;
let schedulePid: number | null = null;
const stray = !taskRegistered && !winswRegistered;
if (stray) {
const snapshot = await runCapped(clock, C.enumeration, deps.enumerate);
// Nothing registered and nothing readable: today's best-effort sweep skips too.
if (!snapshot.ok || snapshot.value === null) {
return finish("absent", null, "no service is registered; the process list could not be read");
}
schedulePid = await readSchedulePid();
binding = bindWindowsStopWrappers({
...bindContext, processes: snapshot.value, taskRegistered: false, managerRegistered: false,
scheduleServicePid: schedulePid,
});
if (binding.ownershipUnverified.length > 0) {
return finish("unknown", "evidence-unreadable", WRAPPER_OWNER_REFUSAL);
}
if (binding.bound.length === 0 && binding.unbound.length === 0 && binding.unreadable.length === 0) {
return finish("absent", null, "no service is registered and no wrapper of this home is running");
}
// Neither of these changes anything, so neither waits for admission.
result.unbound = binding.unbound.map(entry => entry.pid);
if (binding.unreadable.length > 0) {
return finish("unknown", "evidence-unreadable", "a possible wrapper of this home has unreadable evidence");
}
if (binding.bound.length === 0) {
return await unboundOnlyVerdict(binding, deps, watches)
? finish("survived", "unbound-wrapper", "a wrapper of this home is running but cannot be tied to a manager")
: finish("absent", null, "no service is registered and no wrapper of this home is running");
}
} else if (taskRegistered) {
schedulePid = await readSchedulePid();
}
// Admission: everything still to come must fit before anything changes.
if (options.admission) {
const budget = windowsStopWorstCase({
...options.admission.budget,
managers: { scheduler: taskRegistered, winsw: winswStarted, stray },
enumerationReused: stray || options.bindSnapshot !== undefined,
winswStopTimeoutMs: options.admission.budget.winswStopTimeoutMs ?? deps.winswStopTimeoutMs,
});
const remainingMs = options.admission.deadlineAt - clock.now();
result.budget = { requiredMs: budget.totalMs, remainingMs };
if (remainingMs < budget.totalMs) {
return finish("unverified-budget", "unverified-budget", "the remaining time cannot hold the worst case of the stop");
}
}
// Step 2: bind.
if (taskRegistered || winswRegistered) {
let processes = options.bindSnapshot ?? null;
if (processes === null) {
const snapshot = await runCapped(clock, C.enumeration, deps.enumerate);
if (!snapshot.ok || snapshot.value === null) {
return finish("unknown", "evidence-unreadable", "the process list could not be read");
}
processes = snapshot.value;
}
binding = bindWindowsStopWrappers({
...bindContext, processes, taskRegistered, managerRegistered: true,
scheduleServicePid: schedulePid,
});
}
if (binding) {
result.unbound = binding.unbound.map(entry => entry.pid);
if (binding.ownershipUnverified.length > 0) {
return finish("unknown", "evidence-unreadable", WRAPPER_OWNER_REFUSAL);
}
if (binding.unreadable.length > 0) {
return finish("unknown", "evidence-unreadable", "a possible wrapper of this home has unreadable evidence");
}
}
const targets: WindowsBoundWrapper[] = [];
for (const wrapper of binding?.bound ?? []) {
const watch = await deps.openWatch(wrapper.pid, wrapper.startTime);
if (watch.status === "gone" || watch.status === "reused") continue;
if (watch.status === "denied") {
return finish("denied", "access-denied", "a bound wrapper cannot be opened by this account");
}
if (watch.status === "open") watches.set(wrapper.pid, watch);
targets.push(wrapper);
}
result.bound = targets;
publish();
const unboundWatches = new Map<number, WindowsProcessWatch>();
for (const entry of binding?.unbound ?? []) {
if (entry.startTime === null) continue;
const watch = await deps.openWatch(entry.pid, entry.startTime);
unboundWatches.set(entry.pid, watch);
if (watch.status === "open") watches.set(entry.pid, watch);
}
// Step 3: ask the manager.
if (taskRegistered) {
// Check before launching the helper, then again at its mutation boundary.
await authorize();
let mutationKnown = false;
const ended = await runCapped(clock, C.taskEnd,
timeoutMs => deps.endTask(timeoutMs, options.authorize ? authorize : undefined, (attempted, pending = false) => {
mutationKnown = true;
pendingManagerMutation = pending;
result.changed ||= attempted;
publish();
}));
if (ended.ok && ended.value === "unverified-registration") {
return finish("unknown", "evidence-unreadable",
"the scheduled task's launcher, run-as account, or running instances could not be verified for this installation and Windows account. Ending its running instances does not repair its registration. Confirm it in Task Scheduler; repair a registration you own, or contact its owner or administrator");
}
if (!mutationKnown) result.changed ||= !ended.ok || ended.value !== "not-running";
if (!ended.ok) result.changed ||= pendingManagerMutation;
publish();
if (!ended.ok) return finish("unknown", "evidence-unreadable", "the task end command did not answer within its cap");
if (ended.value === "denied") return finish("denied", "access-denied", "ending the task was denied");
if (ended.value === "failed") return finish("unknown", "evidence-unreadable", "the task end command failed");
}
if (winswStarted) {
await authorize();
result.changed = true;
publish();
const stop = await runCapped(clock, C.winswStopCommand, deps.winswStop);
if (!stop.ok) return finish("unknown", "evidence-unreadable", "the native service stop did not answer within its cap");
if (stop.value === "denied") return finish("denied", "access-denied", "stopping the native service was denied");
if (stop.value === "failed") return finish("unknown", "evidence-unreadable", "the native service stop failed");
const pollEnd = clock.now() + (deps.winswStopTimeoutMs ?? DEFAULT_WINSW_STOP_TIMEOUT_MS) + C.winswPollMargin;
for (;;) {
const left = pollEnd - clock.now();
const state = await runCapped(clock, Math.min(C.managerState, left), deps.winswState);
if (state.ok && (state.value === "stopped" || state.value === "nonexistent")) break;
if (pollEnd - clock.now() <= 0) {
return finish("unknown", "evidence-unreadable", "the native service did not report stopped within its stop timeout");
}
await clock.sleep(Math.min(WINSW_POLL_INTERVAL_MS, pollEnd - clock.now()));
}
}
// Steps 4 and 5: terminate the bound survivors, then wait on the bind-time watches.
const windowEnd = clock.now() + C.terminateAndWait;
const exited = new Map<number, boolean>();
for (const wrapper of targets) {
if (watches.get(wrapper.pid)?.exited() === true) {
exited.set(wrapper.pid, true);
continue;
}
await authorize();
result.changed = true;
publish();
const outcome = await runCapped(clock, windowEnd - clock.now(),
timeoutMs => deps.terminate(wrapper.pid, wrapper.startTime, timeoutMs));
if (!outcome.ok) return finish("unknown", "evidence-unreadable", "terminating a bound wrapper did not answer within its cap");
const status = outcome.value.status;
if (status === "denied") return finish("denied", "access-denied", "terminating a bound wrapper was denied");
if (status === "owner-unverified") return finish("unknown", "evidence-unreadable", WRAPPER_OWNER_REFUSAL);
if (status === "unavailable") {
return finish("unknown", "evidence-unreadable",
"the wrapper's exit could not be confirmed without a verified process handle. Check it from its owning Windows session using Task Manager, stop it if it is still running, then retry");
}
if (status === "terminated") {
result.terminated.push(wrapper.pid);
publish();
if (outcome.value.exited === true) exited.set(wrapper.pid, true);
} else {
// gone, or reused: the bound process no longer exists either way, and a reused PID
// is a different process that is left untouched.
exited.set(wrapper.pid, true);
}
}
const pending = (): WindowsBoundWrapper[] => targets.filter(wrapper => {
if (exited.get(wrapper.pid)) return false;
if (watches.get(wrapper.pid)?.exited() === true) {
exited.set(wrapper.pid, true);
return false;
}
return true;
});
while (pending().length > 0 && clock.now() < windowEnd) {
await clock.sleep(Math.min(WATCH_POLL_INTERVAL_MS, windowEnd - clock.now()));
}
let boundAlive = false;
let unreadable = false;
for (const wrapper of pending()) {
const state = watches.get(wrapper.pid)?.exited();
if (state === false) boundAlive = true;
else unreadable = true;
}
// Step 5: the manager state, read once.
let managerActive = false;
if (taskRegistered) {
const state = await runCapped(clock, C.managerState, deps.taskState);
if (state.ok && state.value === "running") managerActive = true;
else if (!state.ok || state.value === "unknown") unreadable = true;
}
if (winswStarted) {
const stepEnd = clock.now() + C.managerState;
const state = await runCapped(clock, C.managerState, deps.winswState);
if (state.ok && (state.value === "running" || state.value === "pending")) managerActive = true;
else if (!state.ok || state.value === "unknown") unreadable = true;
const alive = await runCapped(clock, stepEnd - clock.now(), deps.proxyAlive);
if (alive.ok && alive.value === true) managerActive = true;
}
const unboundAlive = binding ? unboundStillAlive(binding, unboundWatches) : false;
if (unboundAlive) {
return finish("survived", "unbound-wrapper", "a wrapper of this home is running but cannot be tied to a manager");
}
if (boundAlive || managerActive) return finish("survived", null, "the manager or a bound wrapper is still running");
if (unreadable) return finish("unknown", "evidence-unreadable", "the stop could not be verified");
return finish("stopped", null, "the manager is stopped and every bound wrapper has exited");
} finally {
for (const watch of watches.values()) {
try { watch.close(); } catch { /* closing a handle cannot change the verdict */ }
}
}
}
/** An unbound wrapper counts as alive unless its watch proves it exited. */
function unboundStillAlive(binding: WindowsStopBinding, watches: ReadonlyMap<number, WindowsProcessWatch>): boolean {
return binding.unbound.some(entry => {
const watch = watches.get(entry.pid);
if (!watch) return true;
if (watch.status === "gone" || watch.status === "reused") return false;
return watch.status !== "open" || watch.exited() !== true;
});
}
/** Stray path with nothing bound: are the unbound wrappers still there? Read-only. */
async function unboundOnlyVerdict(
binding: WindowsStopBinding,
deps: WindowsCheckedStopDeps,
opened: Map<number, Extract<WindowsProcessWatch, { status: "open" }>>,
): Promise<boolean> {
const watches = new Map<number, WindowsProcessWatch>();
for (const entry of binding.unbound) {
if (entry.startTime === null) continue;
const watch = await deps.openWatch(entry.pid, entry.startTime);
watches.set(entry.pid, watch);
if (watch.status === "open") opened.set(entry.pid, watch);
}
return unboundStillAlive(binding, watches);
}
/** The updater's variant: authorize at entry and at each stop or terminate boundary. */
export function guardedStopWindowsServiceChecked(
authorize: () => MaybePromise<void>,
deps: WindowsCheckedStopDeps,
options: Omit<WindowsCheckedStopOptions, "authorize"> = {},
): Promise<WindowsCheckedStopResult> {
return stopWindowsServiceChecked(deps, { ...options, authorize });
}