UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

573 lines (544 loc) • 28.4 kB
/** * Live dependencies of the checked Windows service stop (#7771, 060 "PR2: caller wiring"). * * Part A (src/service/windows-checked-stop.ts) and Part B (src/service/windows-stop-confirm.ts) * take every effect injected. This module is the production side of those seams: capped * asynchronous schtasks and sc.exe calls, the evidence snapshot with native creation times * (src/service/windows-process-evidence.ts), the checked terminate, the bind-time exit watch, * the listening-port sampler and the listener identity check. * * The bind snapshot MUST be windowsProcessSnapshot: on x64 it overlays the native creation * time, which is the exact value the handle terminate compares. A CIM-only snapshot carries * a millisecond-truncated CIM time, the terminate then answers "reused" and Part A treats a * live wrapper as exited. * * Without a native API, Part A refuses direct termination and reports evidence-unreadable. */ import { execFile } from "node:child_process"; import { existsSync } from "node:fs"; import { join } from "node:path"; import { inspectOcxStartProcessIdentity, readPid, verifyPidIdentity, type OcxStartIdentityObservation } from "../config/process-state"; import { isProcessAlive } from "../lib/process-control"; import { isTestHomeGuardArmed } from "../lib/test-home-guard"; import { resolveTrustedWindowsPowerShellExe, resolveTrustedWindowsSchtasksExe, resolveTrustedWindowsSystemDirectory } from "../lib/windows-elevation"; import { WINSW_SERVICE_ID, winswExePath, type WinswStatus } from "../lib/winsw"; import { decodeWindowsTextBytes } from "../lib/windows-text"; import { parseScQcBinaryPathName, scBinaryPathNamesExecutable } from "../service-manager-probe"; import { parseListenPidsFromNetstat, type ListenPidScan } from "../server/port-reclaim"; import { dropWindowsTcpRowsForLocalPort } from "../server/windows-tcp-drop"; import { TASK, windowsLauncherVbsPath, windowsServiceScriptPath } from "./state"; import { ancestorWrapperPids } from "./windows-guarded-manager"; import type { WindowsCheckedStopDeps, WindowsTaskEndResult, WindowsWinswScmState, WindowsWinswStopResult } from "./windows-checked-stop"; import { openWindowsProcessWatch, readScheduleServicePid, terminateWindowsProcessBound, windowsProcessSnapshot, type WindowsStopProcessEntry, } from "./windows-process-evidence"; import { windowsProcessNative, type WindowsProcessNativeApi, type WindowsTerminateResult } from "./windows-process-native"; import type { WindowsListenerIdentity, WindowsPortSample, WindowsStopConfirmDeps } from "./windows-stop-confirm"; import { windowsSchedulerCsvIncludesTask } from "./windows-scheduler"; import { WINDOWS_TASK_INSTANCE_STOP_SCRIPT, verifyWindowsTaskStopProof } from "./windows-task-instance-stop"; // Only a missing task after connecting to the local root folder establishes absence. const TASK_REGISTRATION_SCRIPT = String.raw` $ErrorActionPreference = 'Stop' try { $service = [Activator]::CreateInstance([type]::GetTypeFromProgID('Schedule.Service', $true)) $service.Connect() $folder = $service.GetFolder('\') } catch { 'unknown'; return } try { $task = $folder.GetTask('${TASK}') if ($null -ne $task) { 'present' } else { 'unknown' } } catch { if ($_.Exception.GetBaseException().HResult -eq -2147024894) { 'absent' } else { 'unknown' } }`; export interface WindowsStopCommandResult { status: number | null; /** Captured from the spawned process handle. Bun's child exit status can contain only the low byte. */ windowsExitCode?: number; stdout: string; stderr: string; timedOut: boolean; } export interface WindowsStopCommandControl { remainingMs?: () => number; signal?: AbortSignal; /** Approval was dispatched; a cap cannot assume no mutation before the helper answers. */ onDispatch?: () => void; onMutation?: () => void; } /** One spawned helper; tests inject it, production runs execFile with a hard timeout. */ export type WindowsStopCommandRunner = ( program: "schtasks" | "sc" | "powershell", args: string[], timeoutMs: number, authorizeProof?: (line: string) => boolean | Promise<boolean>, control?: WindowsStopCommandControl, ) => Promise<WindowsStopCommandResult>; function programPath(program: "schtasks" | "sc" | "powershell"): string { if (program === "schtasks") return resolveTrustedWindowsSchtasksExe(); if (program === "powershell") return resolveTrustedWindowsPowerShellExe(); const file = join(resolveTrustedWindowsSystemDirectory(), "sc.exe"); if (!existsSync(file)) throw new Error("sc.exe was not found in the trusted system directory."); return file; } export const liveWindowsStopCommandRunner: WindowsStopCommandRunner = (program, args, timeoutMs, authorizeProof, control) => new Promise(resolve => { // execFile reads a 0 timeout as "no timeout": a deadline-derived fraction is floored, and a // timeout that floors to 0 spawns nothing. const timeout = Math.floor(Math.min(timeoutMs, control?.remainingMs?.() ?? Infinity)); const deadline = performance.now() + timeout; if (!(timeout > 0) || control?.signal?.aborted) { resolve({ status: null, stdout: "", stderr: "", timedOut: true }); return; } // Task Scheduler and the SCM are machine-global: an armed test process may only observe. // `sc query` and `sc qc` only read the SCM row and its registration. const mutating = authorizeProof !== undefined || (program === "schtasks" ? args[0]?.toLowerCase() !== "/query" : program === "sc" && !["query", "qc"].includes((args[0] ?? "").toLowerCase())); if (isTestHomeGuardArmed() && mutating) { resolve({ status: null, stdout: "", stderr: "refusing a machine-global service mutation from an armed test process", timedOut: false }); return; } let file: string; let native: WindowsProcessNativeApi | null; let readExitCode: (() => number | null) | null = null; try { file = programPath(program); native = program === "schtasks" && args.includes("/hresult") ? windowsProcessNative() : null; } catch (error) { resolve({ status: null, stdout: "", stderr: error instanceof Error ? error.message : String(error), timedOut: false }); return; } const spawnTimeout = Math.floor(Math.min(deadline - performance.now(), control?.remainingMs?.() ?? Infinity)); if (!(spawnTimeout > 0) || control?.signal?.aborted) { resolve({ status: null, stdout: "", stderr: "", timedOut: true }); return; } const helper = execFile(file, args, { encoding: "buffer", timeout: spawnTimeout, windowsHide: true, maxBuffer: 1024 * 1024, signal: control?.signal }, (error, stdout, stderr) => { const text = (value: Buffer | string | undefined): string => value === undefined ? "" : typeof value === "string" ? value : decodeWindowsTextBytes(value); const failure = error as (NodeJS.ErrnoException & { killed?: boolean; signal?: string | null; code?: number | string }) | null; const windowsExitCode = readExitCode?.(); resolve({ status: failure ? (typeof failure.code === "number" ? failure.code : null) : 0, ...(windowsExitCode == null || failure?.killed ? {} : { windowsExitCode }), stdout: text(stdout), stderr: text(stderr), timedOut: control?.signal?.aborted === true || !!failure?.killed && failure.signal !== null, }); }); if (helper.pid !== undefined) readExitCode = native?.captureChildExitCode?.(helper.pid) ?? null; if (authorizeProof) { let pending = "", progressLine = "", authorized = false; helper.stdout?.on("data", (chunk: Buffer) => { progressLine += chunk.toString("latin1"); let end: number; while ((end = progressLine.indexOf("\n")) >= 0) { const line = progressLine.slice(0, end).replace(/\r$/, ""); progressLine = progressLine.slice(end + 1); if (authorized && line === "stop-attempted") control?.onMutation?.(); } }); const onProof = async (chunk: Buffer): Promise<void> => { pending += chunk.toString("latin1"); const end = pending.indexOf("\n"); if (end < 0) return; const proofReceivedAt = performance.now(); helper.stdout?.off("data", onProof); let approved = false; try { approved = await authorizeProof(pending.slice(0, end).replace(/\r$/, "")); } catch { /* An authorizer failure leaves stdin unapproved. */ } const now = performance.now(); const remaining = Math.floor(Math.min(deadline - now, control?.remainingMs?.() ?? Infinity)); authorized = approved && remaining > 0 && control?.signal?.aborted !== true; // The helper started its stopwatch before sending proof. Measuring from receipt here // gives it a conservative cutoff on that clock, even if our reply sits unread. const stopBeforeMs = Math.floor(now - proofReceivedAt + remaining); if (authorized && helper.stdin && !helper.stdin.destroyed && !helper.stdin.writableEnded) control?.onDispatch?.(); helper.stdin?.end(authorized ? `stop-before ${stopBeforeMs}\n` : "\n"); }; helper.stdin?.on("error", () => { /* execFile reports the helper's exit or timeout. */ }); helper.stdout?.on("data", onProof); } }); /** * Status words of `schtasks /query /fo CSV /nh`. schtasks localizes the column from its .mui * resources, and the PowerShell fallback cannot start inside Part A's 1 s manager-state cap on a * cold machine (#8863), so the words observed from shipped resources are read here: zh-CN, ja-JP * and ko-KR from their System32 locale directories, ko-KR running/ready also from two machines. * Any other word stays unknown and falls back to Get-ScheduledTask's locale-independent State enum. */ // A queued instance can launch after Part A. Only ready and disabled prove inactivity. const TASK_CSV_ACTIVE = new Set(["running", "queued", "正在运行", "已排队", "실행 중", "대기", "実行中", "キューに登録済み"]); const TASK_CSV_NOT_RUNNING = new Set(["ready", "disabled", "就绪", "已禁用", "준비", "사용 안 함", "準備完了", "無効"]); export function parseTaskCsvState(csv: string): "running" | "not-running" | "unknown" { for (const line of csv.split(/\r?\n/)) { if (!windowsSchedulerCsvIncludesTask(line, TASK)) continue; const fields = [...line.matchAll(/"([^"]*)"/g)].map(match => match[1]!.trim()); const status = (fields[fields.length - 1] ?? "").normalize("NFC").toLowerCase(); if (TASK_CSV_ACTIVE.has(status)) return "running"; if (TASK_CSV_NOT_RUNNING.has(status)) return "not-running"; return "unknown"; } return "unknown"; } /** sc.exe query: the numeric STATE and the 1060 "does not exist" code are not localized. */ export function parseScQueryState(result: WindowsStopCommandResult): WindowsWinswScmState { const text = result.stdout + "\n" + result.stderr; if (/\b1060\b/.test(text)) return "nonexistent"; if (result.timedOut || result.status !== 0) return "unknown"; const state = /^\s*STATE\s*:\s*(\d+)/m.exec(text); if (!state) return "unknown"; const value = Number(state[1]); if (value === 1) return "stopped"; if (value === 4) return "running"; if (value >= 2 && value <= 7) return "pending"; return "unknown"; } /** sc.exe stop without waiting: 1062 (not started) is fine, 5 is denied. */ export function classifyScStop(result: WindowsStopCommandResult): WindowsWinswStopResult { if (result.timedOut) return "failed"; const text = result.stdout + "\n" + result.stderr; if (result.status === 0 || /\b1062\b/.test(text) || /\b1060\b/.test(text)) return "sent"; if (/\bFAILED 5\b/.test(text) || result.status === 5) return "denied"; return "failed"; } export function winswStatusFromScState(state: WindowsWinswScmState): WinswStatus { if (state === "nonexistent") return "nonexistent"; if (state === "stopped") return "stopped"; // A pending service is still an active manager: Part A stops it and polls. if (state === "running" || state === "pending") return "started"; return "unknown"; } export function windowsStopCanonicalPaths(): string[] { return [windowsLauncherVbsPath(), windowsServiceScriptPath()]; } /** * The terminate Part A uses. Without a native process handle, no termination is attempted. */ export async function windowsStopTerminate( pid: number, startTime: number, timeoutMs: number, io: { native?: () => WindowsProcessNativeApi | null; terminate?: typeof terminateWindowsProcessBound } = {}, ): Promise<WindowsTerminateResult> { if ((io.native ?? windowsProcessNative)() === null) return { status: "unavailable" }; return (io.terminate ?? terminateWindowsProcessBound)(pid, startTime, { timeoutMs }); } /** Floor a deadline-derived timeout; null when it floors to 0 (nothing may be spawned). */ export function wholeTimeoutMs(timeoutMs: number): number | null { const floored = Math.floor(timeoutMs); return floored > 0 ? floored : null; } /** The evidence snapshot with a floored timeout; 0 ms reads nothing (null, unreadable). */ export function windowsStopSnapshot(timeoutMs: number): Promise<WindowsStopProcessEntry[] | null> { const whole = wholeTimeoutMs(timeoutMs); return whole === null ? Promise.resolve(null) : windowsProcessSnapshot({ timeoutMs: whole }); } /** * Does the stopping process descend from a wrapper carrying this home's launcher or * service-script path? The binding rule excludes the stopper itself but not its ancestors, * so such a stop would end its own supervision chain (structure/ops/windows-checked-stop.md, * "Who may run Part A"). */ export function stopperUnderHomeWrapper( processes: readonly WindowsStopProcessEntry[], canonicalPaths: readonly string[], selfPid: number = process.pid, ): boolean { return ancestorWrapperPids(selfPid, processes, canonicalPaths).length > 0; } export interface WindowsCheckedStopLiveOptions { run?: WindowsStopCommandRunner; /** * The `sc.exe qc` query that proves the registered WinSW service runs THIS installation's * executable. Defaults to the capped runner; tests inject it. */ scQcRun?: (timeoutMs: number) => Promise<WindowsStopCommandResult>; /** The outer cap, checked before a manager stop and again after Scheduler proof. */ gate?: () => boolean; /** Share the outer monotonic deadline and cancellation with manager helpers. */ remainingMs?: () => number; signal?: AbortSignal; snapshot?: (timeoutMs: number) => Promise<readonly WindowsStopProcessEntry[] | null>; } /** * Is the registered WinSW service this installation's? * * `sc stop opencodex-proxy-native` names a fixed ID, so a successful `sc query` is evidence * that SOMETHING is registered, not that it is ours: another installation's WinSW service * under the same ID would be stopped by this home's Part A. The registered * `BINARY_PATH_NAME` must name this home's WinSW executable, the same proof the guarded * manager path uses (`windowsWinswServiceInfo` + `commandLineHasPathToken`). Unreadable is * unknown; a foreign executable is `nonexistent`, which keeps Part A from stopping it. */ export function classifyWinswOwnership( qc: WindowsStopCommandResult | null, winswExe: string = winswExePath(), ): WinswStatus | "foreign" { if (qc === null || qc.timedOut || qc.status !== 0) return "unknown"; const binaryPathName = parseScQcBinaryPathName(qc.stdout); if (binaryPathName === null) return "unknown"; return scBinaryPathNamesExecutable(binaryPathName, winswExe) ? "started" : "foreign"; } /** The identity-checked proxy child, or null. */ export function windowsStopChildPid(): number | null { try { const pid = readPid(); return pid !== null && verifyPidIdentity(pid) === pid ? pid : null; } catch { return null; } } export function windowsCheckedStopLiveDeps(options: WindowsCheckedStopLiveOptions = {}): WindowsCheckedStopDeps { const run = options.run ?? liveWindowsStopCommandRunner; const gate = options.gate ?? (() => true); const scQuery = async (timeoutMs: number) => parseScQueryState(await run("sc", ["query", WINSW_SERVICE_ID], timeoutMs)); const scQcRun = options.scQcRun ?? (async (timeoutMs: number) => run("sc", ["qc", WINSW_SERVICE_ID], timeoutMs)); return { canonicalPaths: windowsStopCanonicalPaths(), childPid: windowsStopChildPid(), async probeScheduler(timeoutMs) { const deadline = performance.now() + timeoutMs; const unknown = { status: "unknown", detail: "the Task Scheduler query did not answer" } as const; const direct = await run("schtasks", ["/query", "/tn", `\\${TASK}`, "/fo", "CSV", "/nh", "/hresult"], timeoutMs); if (direct.timedOut || performance.now() >= deadline) return unknown; if (direct.status === 0 && (direct.windowsExitCode ?? 0) === 0 && direct.stdout.trimStart().toLowerCase().startsWith(`"\\${TASK}",`)) return { status: "present" }; if (direct.windowsExitCode !== undefined) { const missing = 0x80070002; // HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) const statusAgrees = direct.status === 2 || (direct.status !== null && (direct.status >>> 0) === missing); return direct.windowsExitCode === missing && statusAgrees ? { status: "absent" } : unknown; } const remaining = wholeTimeoutMs(deadline - performance.now()); if (remaining === null) return unknown; const probe = await run("powershell", ["-NoProfile", "-NonInteractive", "-Command", TASK_REGISTRATION_SCRIPT], remaining); if (probe.timedOut || probe.status !== 0 || performance.now() >= deadline) return unknown; const status = probe.stdout.trim(); return status === "present" || status === "absent" ? { status } : unknown; }, async probeWinsw(timeoutMs) { // One cap covers both reads: the ownership query gets only what the state query left. const started = Date.now(); const state = await scQuery(timeoutMs); const status = winswStatusFromScState(state); // Absence, and anything already unreadable, needs no ownership read. if (status !== "started") return status; const remaining = Math.floor(timeoutMs - (Date.now() - started)); if (remaining < 1) return "unknown"; const qc = await scQcRun(remaining); const ownership = classifyWinswOwnership(qc); // Foreign is `nonexistent` for Part A: a manager this home must not stop. if (ownership === "foreign") return "nonexistent"; return ownership === "unknown" ? "unknown" : status; }, enumerate: timeoutMs => (options.snapshot ?? windowsStopSnapshot)(timeoutMs), scheduleServicePid: timeoutMs => { const whole = wholeTimeoutMs(timeoutMs); return whole === null ? null : readScheduleServicePid({ timeoutMs: whole }); }, async endTask(timeoutMs, authorize, mutation) { const finish = (verdict: WindowsTaskEndResult, attempted: boolean) => { mutation?.(attempted, false); return verdict; }; timeoutMs = Math.min(timeoutMs, options.remainingMs?.() ?? Infinity); if (!gate() || !(timeoutMs >= 1) || options.signal?.aborted) return finish("failed", false); const deadline = performance.now() + Math.floor(timeoutMs); const withinDeadline = () => performance.now() < deadline && gate(); const launcher = windowsLauncherVbsPath(); const script = Buffer.from(WINDOWS_TASK_INSTANCE_STOP_SCRIPT, "utf16le").toString("base64"); let approved = false, dispatched = false, observedMutation = false; let refusal: { cause: unknown } | undefined; const ended = await run("powershell", ["-NoProfile", "-NoLogo", "-NonInteractive", "-EncodedCommand", script], timeoutMs, async line => { if (!verifyWindowsTaskStopProof(line, launcher) || !withinDeadline()) return false; try { await authorize?.(); } catch (cause) { refusal = { cause }; return false; } approved = withinDeadline(); return approved; }, { remainingMs: options.remainingMs, signal: options.signal, onDispatch: () => { dispatched = true; mutation?.(false, true); }, onMutation: () => { observedMutation = true; mutation?.(true, false); } }); if (refusal) throw refusal.cause; const lines = ended.stdout.trim().split(/\r?\n/); const attempted = observedMutation || lines.includes("stop-attempted"); if (ended.timedOut || ended.status !== 0) return finish("failed", attempted || dispatched); const verdict = lines.at(-1); if (verdict === "unverified-registration" || verdict === "denied") return finish(verdict, attempted); if (approved && (verdict === "ended" || verdict === "not-running")) return finish(verdict, attempted || verdict === "ended"); return finish("failed", attempted || dispatched && verdict !== "failed"); }, async taskState(timeoutMs) { const started = Date.now(); const csv = await run("schtasks", ["/query", "/tn", TASK, "/fo", "CSV", "/nh"], timeoutMs); const parsed = csv.status === 0 ? parseTaskCsvState(csv.stdout) : "unknown"; if (parsed !== "unknown") return parsed; // A localized status word: ask Get-ScheduledTask, whose State is an enum name. const left = timeoutMs - (Date.now() - started); if (left <= 0) return "unknown"; const ps = await run("powershell", ["-NoProfile", "-NoLogo", "-NonInteractive", "-Command", "(Get-ScheduledTask -TaskName '" + TASK + "' -TaskPath '\\' -ErrorAction Stop).State"], left); const state = ps.stdout.trim(); if (/^(running|queued)$/i.test(state)) return "running"; if (/^(ready|disabled)$/i.test(state)) return "not-running"; return "unknown"; }, async winswStop(timeoutMs) { if (!gate()) return "failed"; return classifyScStop(await run("sc", ["stop", WINSW_SERVICE_ID], timeoutMs, undefined, { remainingMs: options.remainingMs, signal: options.signal })); }, winswState: scQuery, proxyAlive: () => { const pid = windowsStopChildPid(); return pid === null ? false : isProcessAlive(pid); }, openWatch: (pid, startTime) => openWindowsProcessWatch(pid, startTime), terminate: (pid, startTime, timeoutMs) => gate() ? windowsStopTerminate(pid, startTime, timeoutMs) : { status: "unavailable" }, }; } /** One listener scan, bounded by the caller's timeout; a scan that misses it is unreadable. */ export type WindowsStopPortScan = (port: number, timeoutMs: number) => ListenPidScan | Promise<ListenPidScan>; const WINDOWS_STOP_SCAN_MAX_BUFFER = 4 * 1024 * 1024; /** * The production listener scan: netstat -ano through execFile with the caller's timeout. * * `netstat -ano` is asked directly rather than through `cmd /c chcp 437`: the locale-safe * wildcard-foreign rule in parseListenEntriesFromNetstat already recognizes a listen row, and * running the program itself means the timeout terminates the only helper spawned. The table * is read from the trusted System32 path — SystemRoot is caller-controlled. */ export function scanWindowsStopListenPids(port: number, timeoutMs: number): Promise<ListenPidScan> { const whole = wholeTimeoutMs(timeoutMs); if (whole === null) return Promise.resolve({ ok: false, error: "no positive timeout to sample with" }); let netstat: string; try { netstat = join(resolveTrustedWindowsSystemDirectory(), "netstat.exe"); } catch (error) { return Promise.resolve({ ok: false, error: error instanceof Error ? error.message : String(error) }); } return new Promise(resolve => { // execFile's timeout terminates the helper; the callback then answers unreadable. execFile(netstat, ["-ano", "-p", "tcp"], { encoding: "buffer", timeout: whole, killSignal: "SIGKILL", windowsHide: true, maxBuffer: WINDOWS_STOP_SCAN_MAX_BUFFER, }, (error, stdout) => { if (error) { resolve({ ok: false, error: error.message }); return; } const text = typeof stdout === "string" ? stdout : decodeWindowsTextBytes(stdout); resolve({ ok: true, pids: parseListenPidsFromNetstat(text, port) }); }); }); } /** * One port sample, capped by `timeoutMs`. A listener whose owner has exited is cleared like * reclaimListenPort does. * * A scan that does not answer within the budget is "unknown": Part B's closing sample is * bounded (030 "Time budget"), and a synchronous scan both ignored that cap and could stall * the stop for the helper's own 5 s. The timeout is floored and a value below 1 ms samples * nothing, because execFile reads 0 as unlimited — the same rule as the command runner. */ export async function sampleWindowsStopPort( port: number, timeoutMs: number, io: { scan?: WindowsStopPortScan; alive?: (pid: number) => boolean; /** Clears the ghost rows of the exited owners only; never another program's rows. */ drop?: (port: number, ownerPids: readonly number[]) => unknown; selfPid?: number; } = {}, ): Promise<WindowsPortSample> { const whole = wholeTimeoutMs(timeoutMs); if (whole === null) return { state: "unknown" }; const scan = await runBoundedScan(port, whole, io.scan ?? scanWindowsStopListenPids); if (scan === null || !scan.ok) return { state: "unknown" }; const pids = scan.pids.filter(pid => pid !== (io.selfPid ?? process.pid)); if (pids.length === 0) return { state: "free" }; const alive = io.alive ?? isProcessAlive; const live = pids.filter(pid => alive(pid)); if (live.length === 0) { // Clear only the ghost rows the exited PID(s) left: a program that took the port after // the scan owns its rows, and resetting them would break a connection this stop does not own. try { (io.drop ?? ((target: number, owners: readonly number[]) => dropWindowsTcpRowsForLocalPort(target, undefined, owners)))(port, pids); } catch { /* the next sample decides */ } } return { state: "listening", ownerPid: live[0] ?? pids[0] ?? null }; } /** Resolve null once the budget is spent; a scan that never answers cannot hold the stop. */ function runBoundedScan(port: number, timeoutMs: number, scan: WindowsStopPortScan): Promise<ListenPidScan | null> { return new Promise(resolve => { let settled = false; const finish = (result: ListenPidScan | null): void => { if (settled) return; settled = true; clearTimeout(timer); resolve(result); }; const timer = setTimeout(() => finish(null), timeoutMs); timer.unref?.(); let pending: ListenPidScan | Promise<ListenPidScan>; try { pending = scan(port, timeoutMs); } catch { finish(null); return; } Promise.resolve(pending).then(finish, () => finish(null)); }); } /** * ours = an opencodex process (the respawned proxy); exited = its owner is gone. * * Tri-state (#7771): only a positive "mismatch" is foreign. `verifyPidIdentity` collapses * "not an ocx process" and "the probe could not answer" into the same null, and a probe that * cannot read another account's or an elevated process's command line is not evidence that * another program holds the port — Part B would then report portHeldByForeign and let the * caller restore shared config with the proxy possibly still alive. Unreadable stays unknown. */ export function identifyWindowsStopListener( ownerPid: number | null, io: { alive?: (pid: number) => boolean; identity?: (pid: number) => OcxStartIdentityObservation; } = {}, ): WindowsListenerIdentity { if (ownerPid === null) return "unknown"; if (!(io.alive ?? isProcessAlive)(ownerPid)) return "exited"; try { const observed = (io.identity ?? inspectOcxStartProcessIdentity)(ownerPid); if (observed === "match") return "ours"; return observed === "mismatch" ? "foreign" : "unknown"; } catch { return "unknown"; } } export function windowsStopConfirmLiveDeps( port: number, remainingMs: number, options: { snapshot?: (timeoutMs: number) => Promise<readonly WindowsStopProcessEntry[] | null> } = {}, ): WindowsStopConfirmDeps { return { port, remainingMs, canonicalPaths: windowsStopCanonicalPaths(), samplePort: (samplePort, timeoutMs) => sampleWindowsStopPort(samplePort, timeoutMs), identifyListener: (_port, ownerPid) => identifyWindowsStopListener(ownerPid), enumerate: timeoutMs => (options.snapshot ?? windowsStopSnapshot)(timeoutMs), }; }