/**
 * 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),
  };
}
