@remodex/rmx 1.0.2

package/src/lib/windows-user-principal.ts

@@ -0,0 +1,283 @@
+/**
+ * Resolve the effective Windows token to the locale-independent SID form that
+ * icacls accepts ("*S-1-..."). Environment values such as USERDOMAIN are not
+ * an authority for the current token: on workgroup machines USERDOMAIN may be
+ * the literal WORKGROUP even though the account belongs to the local computer.
+ *
+ * There is deliberately NO name-shaped fallback. A `DOMAIN\User` string has a
+ * valid shape, but shape is not evidence that the account is the current
+ * token's subject, and both environment variables are writable by whatever
+ * launched us. A wrong principal here is not cosmetic: `runIcacls` grants it
+ * Full Control and then removes inheritance, so a wrong grant either leaves a
+ * different account holding the secret or strands the file with no usable ACE.
+ * When the SID cannot be resolved, the caller declines to touch the ACL at all.
+ *
+ * Budget caveat: callers pass their REMAINING harden budget, which becomes the
+ * child process timeout. Trusted-executable resolution (a `GetSystemDirectoryW`
+ * FFI call) and spawn setup happen before that timeout starts, and the async
+ * timer only arms once `Bun.spawn` returns. Both are small in practice, but the
+ * lookup is not bounded by the deadline to the microsecond. Tightening that
+ * would mean passing an absolute deadline through the runner interface.
+ */
+
+import { resolveTrustedWindowsPowerShellExe } from "./windows-elevation";
+
+const SID_PATTERN = /^S-1-(?:\d+-)+\d+$/i;
+const SID_EXPRESSION =
+  "[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value";
+
+export interface WindowsPrincipalLookupResult {
+  success: boolean;
+  exitCode: number | null;
+  timedOut: boolean;
+  stdout: string;
+}
+
+export type WindowsPrincipalRunner = (
+  timeoutMs: number,
+) => WindowsPrincipalLookupResult;
+
+export type AsyncWindowsPrincipalRunner = (
+  timeoutMs: number,
+) => Promise<WindowsPrincipalLookupResult>;
+
+const POWERSHELL_ARGS = [
+  "-NoLogo",
+  "-NoProfile",
+  "-NonInteractive",
+  "-WindowStyle",
+  "Hidden",
+  "-Command",
+  SID_EXPRESSION,
+] as const;
+
+function windowsPrincipalPowerShellCommand(): string[] {
+  return [resolveTrustedWindowsPowerShellExe(), ...POWERSHELL_ARGS];
+}
+
+/** Test-only readback of the exact trusted executable and static arguments. */
+export function windowsPrincipalPowerShellCommandForTests(): string[] {
+  return windowsPrincipalPowerShellCommand();
+}
+
+function defaultWindowsPrincipalRunner(timeoutMs: number): WindowsPrincipalLookupResult {
+  const result = Bun.spawnSync(windowsPrincipalPowerShellCommand(), {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "ignore",
+    timeout: Math.max(1, timeoutMs),
+    windowsHide: true,
+  });
+  return {
+    success: result.success,
+    exitCode: result.exitCode,
+    timedOut: result.exitedDueToTimeout ?? false,
+    stdout: result.stdout ? result.stdout.toString() : "",
+  };
+}
+
+async function defaultAsyncWindowsPrincipalRunner(
+  timeoutMs: number,
+): Promise<WindowsPrincipalLookupResult> {
+  const proc = Bun.spawn(windowsPrincipalPowerShellCommand(), {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "ignore",
+    windowsHide: true,
+  });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    try { proc.kill(); } catch { /* already exited */ }
+  }, Math.max(1, timeoutMs));
+  let exitCode: number | null = null;
+  try {
+    exitCode = await proc.exited;
+  } finally {
+    clearTimeout(timer);
+  }
+  const stdout = proc.stdout
+    ? await new Response(proc.stdout).text().catch(() => "")
+    : "";
+  return {
+    success: !timedOut && exitCode === 0,
+    exitCode: timedOut ? null : exitCode,
+    timedOut,
+    stdout,
+  };
+}
+
+let principalRunner: WindowsPrincipalRunner = defaultWindowsPrincipalRunner;
+let asyncPrincipalRunner: AsyncWindowsPrincipalRunner = defaultAsyncWindowsPrincipalRunner;
+let cachedPrincipal: string | null = null;
+let asyncLookupInFlight: Promise<string> | null = null;
+
+/**
+ * POSIX CI drives the Windows ACL branch through `setPlatformForTests("win32")`,
+ * on hosts that have neither System32 nor PowerShell. Those runs need SOME
+ * principal, so this seam supplies a synthetic one.
+ *
+ * It lives here rather than in `windows-secret-acl.ts` for one reason that is
+ * not cosmetic: an explicitly injected runner must be able to beat it. When the
+ * synthetic value was chosen first, in the ACL module, a test could not inject a
+ * lookup FAILURE on POSIX at all — so the fail-closed and memo-isolation cases
+ * were guarded with `if (process.platform !== "win32") return;` and never ran
+ * outside Windows. Resolution order below is what makes those cases executable
+ * on every runner.
+ */
+let syntheticPrincipalForTests: string | null = null;
+
+/**
+ * Test seam: supply the principal used when no runner was injected and the host
+ * is not really Windows. Pass null to disable.
+ */
+export function setSyntheticWindowsPrincipalForTests(principal: string | null): void {
+  syntheticPrincipalForTests = principal;
+  cachedPrincipal = null;
+}
+
+/** True when an explicit runner override is installed and must take precedence. */
+function hasSyncRunnerOverride(): boolean {
+  return principalRunner !== defaultWindowsPrincipalRunner;
+}
+
+function hasAsyncRunnerOverride(): boolean {
+  return asyncPrincipalRunner !== defaultAsyncWindowsPrincipalRunner;
+}
+
+function identityError(reason: string): NodeJS.ErrnoException {
+  const error = new Error(`Windows effective-account SID lookup ${reason}`) as NodeJS.ErrnoException;
+  // Keep identity lookup failures distinct from icacls timeouts. In particular,
+  // they must not populate windows-secret-acl's destination timeout memo.
+  error.code = "EACLIDENTITY";
+  return error;
+}
+
+function principalFromResult(result: WindowsPrincipalLookupResult): string {
+  if (!result.success) {
+    throw identityError(result.timedOut
+      ? "timed out"
+      : `exited ${result.exitCode ?? "null"}`);
+  }
+  const sid = result.stdout.trim();
+  if (!SID_PATTERN.test(sid)) {
+    throw identityError(sid ? "returned an invalid SID" : "returned an empty SID");
+  }
+  return `*${sid.toUpperCase()}`;
+}
+
+/** Resolve and process-cache the effective token SID for synchronous ACL paths. */
+export function resolveCurrentWindowsPrincipal(timeoutMs: number): string {
+  // Order matters: an explicitly injected runner outranks the synthetic value,
+  // so a test can inject a FAILURE on a POSIX host. See the seam comment above.
+  if (hasSyncRunnerOverride()) {
+    if (cachedPrincipal) return cachedPrincipal;
+    if (timeoutMs <= 0) throw identityError("had no remaining deadline");
+    let overridden: WindowsPrincipalLookupResult;
+    try {
+      overridden = principalRunner(timeoutMs);
+    } catch {
+      throw identityError("could not start");
+    }
+    const principal = principalFromResult(overridden);
+    cachedPrincipal = principal;
+    return principal;
+  }
+  if (cachedPrincipal) return cachedPrincipal;
+  if (syntheticPrincipalForTests) return syntheticPrincipalForTests;
+  if (timeoutMs <= 0) throw identityError("had no remaining deadline");
+  let result: WindowsPrincipalLookupResult;
+  try {
+    result = principalRunner(timeoutMs);
+  } catch {
+    throw identityError("could not start");
+  }
+  const principal = principalFromResult(result);
+  cachedPrincipal = principal;
+  return principal;
+}
+
+async function waitForExistingLookup(
+  lookup: Promise<string>,
+  timeoutMs: number,
+): Promise<string> {
+  if (timeoutMs <= 0) throw identityError("had no remaining deadline");
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      lookup,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(identityError("timed out while awaiting the shared lookup")),
+          Math.max(1, timeoutMs),
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Async counterpart. Concurrent callers share one owned child lookup; a later
+ * caller may exhaust its own budget without cancelling the lookup owned by the
+ * first caller. The first caller owns that child and its process timeout; a
+ * later, longer budget deliberately does not extend an already-running child.
+ */
+export async function resolveCurrentWindowsPrincipalAsync(timeoutMs: number): Promise<string> {
+  const overridden = hasAsyncRunnerOverride();
+  if (cachedPrincipal) return cachedPrincipal;
+  if (asyncLookupInFlight) return waitForExistingLookup(asyncLookupInFlight, timeoutMs);
+  // Same precedence rule as the sync path: an injected runner beats the synthetic.
+  if (!overridden && syntheticPrincipalForTests) return syntheticPrincipalForTests;
+  if (timeoutMs <= 0) throw identityError("had no remaining deadline");
+
+  const lookup = (async (): Promise<string> => {
+    let result: WindowsPrincipalLookupResult;
+    try {
+      result = await asyncPrincipalRunner(timeoutMs);
+    } catch {
+      throw identityError("could not start");
+    }
+    const principal = principalFromResult(result);
+    cachedPrincipal = principal;
+    return principal;
+  })();
+  asyncLookupInFlight = lookup;
+  try {
+    return await lookup;
+  } finally {
+    if (asyncLookupInFlight === lookup) asyncLookupInFlight = null;
+  }
+}
+
+/** Test seam: replace the sync resolver process and clear its successful cache. */
+export function setWindowsPrincipalRunnerForTests(
+  runner: WindowsPrincipalRunner | null,
+): void {
+  if (asyncLookupInFlight) {
+    throw new Error("Cannot replace the Windows principal runner while a lookup is in flight.");
+  }
+  principalRunner = runner ?? defaultWindowsPrincipalRunner;
+  cachedPrincipal = null;
+}
+
+/** Test seam: replace the async resolver process and clear its successful cache. */
+export function setAsyncWindowsPrincipalRunnerForTests(
+  runner: AsyncWindowsPrincipalRunner | null,
+): void {
+  if (asyncLookupInFlight) {
+    throw new Error("Cannot replace the Windows principal runner while a lookup is in flight.");
+  }
+  asyncPrincipalRunner = runner ?? defaultAsyncWindowsPrincipalRunner;
+  cachedPrincipal = null;
+}
+
+/** Test seam: clear only process-local principal state. */
+export function resetWindowsPrincipalForTests(): void {
+  if (asyncLookupInFlight) {
+    throw new Error("Cannot reset the Windows principal while a lookup is in flight.");
+  }
+  cachedPrincipal = null;
+  syntheticPrincipalForTests = null;
+}

package/src/lib/winsw.ts

@@ -0,0 +1,402 @@
+/**
+ * WinSW-backed native Windows service (opt-in via `rmx service install --native`).
+ *
+ * Design (devlog/_plan/260720_windows_service/060):
+ * - WinSW 2.12.0 NET461 build, downloaded on first native install and verified against
+ *   a pinned SHA-256 (fail-closed: mismatch deletes the file and throws). The binary is
+ *   NOT bundled in npm; offline installs get an explicit manual-placement hint.
+ * - Runs as the USER account (v2 `<serviceaccount>` domain/user/allowservicelogon —
+ *   never LocalSystem: the ACL hardening in windows-secret-acl grants only the user SID,
+ *   so a SYSTEM service could not read the token file, and SYSTEM-owned writes would
+ *   change the user-access contract).
+ * - No password in XML: `winsw install /p` prompts on the console (stdin inherit).
+ * - Absolute paths only — no %USERPROFILE% indirection (that exists for OEM-codepage
+ *   batch parsing; WinSW XML is Unicode).
+ */
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { expandUserPath, getConfigDir, loadConfig } from "../config";
+import { recordOwnedConfigPath } from "./config-ownership";
+import { BUN_RUNTIME_PATH_ENV, BUN_RUNTIME_SOURCE_ENV, durableBunRuntime } from "./bun-runtime";
+import type { BunRuntimeSource } from "./bun-runtime";
+import {
+  SERVICE_PROVIDER_ENV_FILE_ENV,
+  serviceApiTokenFilePath,
+  serviceProviderEnvFilePath,
+} from "./service-secrets";
+
+export const WINSW_VERSION = "2.12.0";
+export const WINSW_URL = `https://github.com/winsw/winsw/releases/download/v${WINSW_VERSION}/WinSW.NET461.exe`;
+/** SHA-256 of the official v2.12.0 WinSW.NET461.exe release asset (655872 bytes). */
+export const WINSW_SHA256 = "b5066b7bbdfba1293e5d15cda3caaea88fbeab35bd5b38c41c913d492aadfc4f";
+
+/** SCM service id — distinct from the Task Scheduler task name (opencodex-proxy). */
+export const WINSW_SERVICE_ID = "opencodex-proxy-native";
+
+export function winswDir(): string {
+  return join(getConfigDir(), "winsw");
+}
+
+/** WinSW discovers its config as the same-basename XML next to the exe. */
+export function winswExePath(): string {
+  return join(winswDir(), `${WINSW_SERVICE_ID}.exe`);
+}
+
+export function winswXmlPath(): string {
+  return join(winswDir(), `${WINSW_SERVICE_ID}.xml`);
+}
+
+function winswLogDir(): string {
+  return getConfigDir();
+}
+
+function xmlEscape(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function currentCodexHomeAbsolute(): string {
+  const raw = process.env.CODEX_HOME?.trim();
+  return raw ? resolve(expandUserPath(raw)) : join(homedir(), ".codex");
+}
+
+export interface WinswEntry {
+  bun: string;
+  /** Provenance of `bun`, resolved together with it so the two can never disagree. */
+  bunRuntimeSource: BunRuntimeSource;
+  cli: string;
+}
+
+/**
+ * Build the WinSW v2 XML. Never embeds the API token value — the app loads it from
+ * OCX_API_TOKEN_FILE at startup (cli handleStart). PATH is baked for parity with the
+ * Task Scheduler wrapper / launchd / systemd: the SCM service environment lacks the
+ * user's interactive PATH, which provider subprocesses may need.
+ */
+export function buildWinswXml(entry: WinswEntry, env: NodeJS.ProcessEnv = process.env, port?: number): string {
+  const domain = env.USERDOMAIN?.trim() || ".";
+  const user = env.USERNAME?.trim() || "";
+  const listenPort = (() => {
+    if (typeof port === "number" && Number.isFinite(port) && port > 0 && port <= 65535) return Math.trunc(port);
+    const baked = env.OCX_BAKE_PORT?.trim();
+    if (baked && /^\d+$/.test(baked)) {
+      const n = Number(baked);
+      if (n > 0 && n <= 65535) return n;
+    }
+    return loadConfig().port ?? 10100;
+  })();
+  // Services never bake `--port 0` (parsePortOption rejects it); treat as default.
+  const safeListenPort = listenPort > 0 && listenPort <= 65535 ? listenPort : 10100;
+  // SCM services do not inherit the interactive user environment (#764). Bake:
+  // - OPENCODEX_HOME so file-backed admin auth (`admin-api-token`) resolves
+  // - OPENCODEX_ACL_TIMEOUT_MS when set (not a secret)
+  // Never embed OPENCODEX_ADMIN_AUTH_TOKEN or OPENCODEX_API_AUTH_TOKEN values in XML —
+  // those stay file-pointer / generated-file only (uninstall retains the XML).
+  const aclTimeout = env.OPENCODEX_ACL_TIMEOUT_MS?.trim();
+  const envLines = [
+    `  <env name="OCX_SERVICE" value="1"/>`,
+    `  <env name="${BUN_RUNTIME_SOURCE_ENV}" value="${xmlEscape(entry.bunRuntimeSource)}"/>`,
+    `  <env name="${BUN_RUNTIME_PATH_ENV}" value="${xmlEscape(entry.bun)}"/>`,
+    `  <env name="OCX_API_TOKEN_FILE" value="${xmlEscape(serviceApiTokenFilePath())}"/>`,
+    `  <env name="${SERVICE_PROVIDER_ENV_FILE_ENV}" value="${xmlEscape(serviceProviderEnvFilePath())}"/>`,
+    `  <env name="PATH" value="${xmlEscape(env.PATH ?? "")}"/>`,
+    env.CODEX_HOME?.trim() ? `  <env name="CODEX_HOME" value="${xmlEscape(currentCodexHomeAbsolute())}"/>` : null,
+    `  <env name="OPENCODEX_HOME" value="${xmlEscape(getConfigDir())}"/>`,
+    aclTimeout ? `  <env name="OPENCODEX_ACL_TIMEOUT_MS" value="${xmlEscape(aclTimeout)}"/>` : null,
+  ].filter((line): line is string => Boolean(line));
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<service>
+  <id>${WINSW_SERVICE_ID}</id>
+  <name>Remodex Proxy (native)</name>
+  <description>Remodex proxy running as a native Windows service (windowless, starts at boot).</description>
+  <executable>${xmlEscape(entry.bun)}</executable>
+  <arguments>${xmlEscape(`"${entry.cli}" start --port ${safeListenPort}`)}</arguments>
+${envLines.join("\n")}
+  <logpath>${xmlEscape(winswLogDir())}</logpath>
+  <log mode="roll-by-size">
+    <sizeThreshold>10240</sizeThreshold>
+    <keepFiles>4</keepFiles>
+  </log>
+  <onfailure action="restart" delay="5 sec"/>
+  <stoptimeout>20 sec</stoptimeout>
+  <serviceaccount>
+    <domain>${xmlEscape(domain)}</domain>
+    <user>${xmlEscape(user)}</user>
+    <allowservicelogon>true</allowservicelogon>
+  </serviceaccount>
+</service>
+`;
+}
+
+export function sha256Hex(data: Uint8Array | Buffer): string {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+/**
+ * Ensure the pinned WinSW binary exists locally; download + verify on first use.
+ * Fail-closed: any hash mismatch deletes the file and throws.
+ */
+export async function ensureWinswBinary(fetchImpl: typeof fetch = fetch): Promise<string> {
+  const exe = winswExePath();
+  if (existsSync(exe)) {
+    const digest = sha256Hex(readFileSync(exe));
+    if (digest === WINSW_SHA256) return exe;
+    unlinkSync(exe);
+    console.warn("⚠️  Existing WinSW binary failed hash verification; re-downloading.");
+  }
+  recordOwnedConfigPath(getConfigDir(), winswDir());
+  if (!existsSync(winswDir())) mkdirSync(winswDir(), { recursive: true });
+  let body: ArrayBuffer;
+  try {
+    const res = await fetchImpl(WINSW_URL);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    body = await res.arrayBuffer();
+  } catch (err) {
+    throw new Error(
+      `Failed to download WinSW ${WINSW_VERSION} (${err instanceof Error ? err.message : String(err)}). ` +
+        `Offline? Place the official WinSW.NET461.exe (v${WINSW_VERSION}) at ${exe} and retry.`,
+    );
+  }
+  const bytes = Buffer.from(body);
+  const digest = sha256Hex(bytes);
+  if (digest !== WINSW_SHA256) {
+    throw new Error(
+      `WinSW download failed SHA-256 verification (got ${digest}, expected ${WINSW_SHA256}). ` +
+        "Refusing to install an unverified service binary.",
+    );
+  }
+  writeFileSync(exe, bytes);
+  return exe;
+}
+
+function runWinsw(args: string[]): string {
+  return execFileSync(winswExePath(), args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true }).trim();
+}
+
+/** `install /p` prompts for the service-account password on the console — stdin must be inherited. */
+function runWinswInteractive(args: string[]): void {
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      "WinSW install requires an interactive console to prompt for the service account password. "
+        + "Run `rmx service install --native` from an elevated Command Prompt or PowerShell window, not a hidden or piped session.",
+    );
+  }
+  execFileSync(winswExePath(), args, { stdio: "inherit" });
+}
+
+function scQc(): string {
+  const sc = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "sc.exe");
+  return execFileSync(existsSync(sc) ? sc : "sc.exe", ["qc", WINSW_SERVICE_ID], {
+    encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true,
+  });
+}
+
+export type WinswStatus = "started" | "stopped" | "nonexistent" | "unknown";
+
+/** WinSW v2 `status` prints exactly Started / Stopped / NonExistent. */
+export function parseWinswStatus(output: string): WinswStatus {
+  const normalized = output.trim().toLowerCase();
+  if (normalized.includes("nonexistent")) return "nonexistent";
+  if (normalized.includes("started")) return "started";
+  if (normalized.includes("stopped")) return "stopped";
+  // Anything else is an unparseable result — NOT proof of absence. Callers must
+  // fail closed: only an exact NonExistent may skip stop/uninstall.
+  return "unknown";
+}
+
+export function statusWinswRaw(): WinswStatus {
+  if (existsSync(winswExePath())) {
+    try {
+      return parseWinswStatus(runWinsw(["status"]));
+    } catch {
+      // The query itself failed (access denied, damaged/quarantined exe, ...). Treat the
+      // service as possibly-installed so lifecycle operations still attempt stop/uninstall
+      // instead of skipping a live SCM service that would keep respawning the proxy.
+      return "unknown";
+    }
+  }
+  // A missing exe does NOT prove the SCM registration is gone (quarantined binary,
+  // partial uninstall): a stale opencodex-proxy-native registration can outlive it.
+  // Confirm absence against the SCM itself before reporting "nonexistent".
+  if (process.platform !== "win32") return "nonexistent";
+  const probe = probeScmRegistration();
+  // probe === "error": the SCM could not be queried — fail closed, never claim absence.
+  return probe === false ? "nonexistent" : "unknown";
+}
+
+/**
+ * Probe the SCM for the native service registration.
+ * Returns true (registered), false (confirmed absent — exit 1060 only), or "error"
+ * (query itself failed: access denied, sc.exe missing, ...). Only a confirmed
+ * ERROR_SERVICE_DOES_NOT_EXIST may prove absence to lifecycle callers.
+ */
+export function probeScmRegistration(run: () => string = queryScmForService): boolean | "error" {
+  try {
+    run();
+    return true;
+  } catch (err) {
+    const e = err as { status?: number | null; stderr?: string | Buffer | null; stdout?: string | Buffer | null; message?: string };
+    // sc.exe does not reliably channel the 1060 line — it can land on stderr OR stdout
+    // depending on the host — so scan every captured stream and the error message.
+    const text = [e.stderr, e.stdout, e.message]
+      .map(v => (typeof v === "string" ? v : ""))
+      .join("\n");
+    // ERROR_SERVICE_DOES_NOT_EXIST: the numeric identifier 1060 is locale-invariant
+    // (FALHA 1060 pt-BR, localized ko output, English FAILED 1060). The query is a
+    // fixed `sc.exe query <service>` so a standalone 1060 in its output is proof of
+    // absence. Bun may deliver e.status as 36 (1060 & 0xff) — status 36 ALONE is
+    // NOT accepted (collides with any status ≡ 36 mod 256); the textual 1060 is
+    // required corroboration and covers those hosts.
+    if (e.status === 1060 || /\b1060\b/.test(text)) return false;
+    return "error";
+  }
+}
+
+function scExePath(): string {
+  const sc = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "sc.exe");
+  return existsSync(sc) ? sc : "sc.exe";
+}
+
+function queryScmForService(): string {
+  return execFileSync(scExePath(), ["query", WINSW_SERVICE_ID], {
+    encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true,
+  });
+}
+
+/**
+ * Verify the installed SCM service runs as the intended user, not LocalSystem (WinSW's
+ * default when the XML account section is ignored/malformed). Rolls back on mismatch.
+ */
+function assertServiceAccountApplied(env: NodeJS.ProcessEnv = process.env): void {
+  const qc = scQc();
+  const startName = /SERVICE_START_NAME\s*:\s*(.+)/i.exec(qc)?.[1]?.trim() ?? "";
+  const user = env.USERNAME?.trim() ?? "";
+  if (/localsystem/i.test(startName) || (user && !startName.toLowerCase().includes(user.toLowerCase()))) {
+    try { runWinsw(["uninstall"]); } catch { /* rollback is best-effort */ }
+    throw new Error(
+      `Native service was registered as "${startName || "unknown"}" instead of the current user; ` +
+        "rolled back. Re-run `rmx service install --native` and enter the account credentials when prompted.",
+    );
+  }
+}
+
+export interface WinswInstallDeps {
+  ensureBinary?: () => Promise<string>;
+  writeXml?: (path: string, content: string) => void;
+  interactive?: (args: string[]) => void;
+  run?: (args: string[]) => string;
+  verifyAccount?: () => void;
+  status?: () => WinswStatus;
+}
+
+/**
+ * Install (or repair) the native service. Re-running against an existing service skips
+ * `install /p` — assets are rewritten and the service restarted without re-prompting
+ * credentials (WinSW `install` fails with "service already exists").
+ */
+export async function installWinswService(entry: WinswEntry, deps: WinswInstallDeps = {}): Promise<void> {
+  const ensureBinary = deps.ensureBinary ?? ensureWinswBinary;
+  const writeXml = deps.writeXml ?? ((path: string, content: string) => writeFileSync(path, content, "utf8"));
+  const interactive = deps.interactive ?? runWinswInteractive;
+  const run = deps.run ?? runWinsw;
+  const verifyAccount = deps.verifyAccount ?? assertServiceAccountApplied;
+  const status = deps.status ?? statusWinswRaw;
+
+  await ensureBinary();
+  writeXml(winswXmlPath(), buildWinswXml(entry));
+  const existing = status();
+  if (existing === "unknown") {
+    throw new Error(
+      "Could not query the native service state (WinSW status failed or returned an unexpected result). " +
+        "Refusing to guess the install state — check 'rmx service status' and retry.",
+    );
+  }
+  if (existing === "nonexistent") {
+    // WinSW self-elevates via UAC; a refused prompt aborts install (no silent fallback).
+    // v2.12 recognizes prompting only as args[1]: `install /p` (XML is auto-discovered
+    // as the same-basename file next to the exe).
+    interactive(["install", "/p"]);
+    verifyAccount();
+  } else {
+    // Use `stopwait` (not `stop`) so the SCM service fully stops before `start` — bare
+    // `stop` only sends the stop request; `start` against a STOP_PENDING service fails.
+    try { run(["stopwait"]); } catch { /* already stopped */ }
+  }
+  run(["start"]);
+}
+
+export function startWinswService(): void { runWinsw(["start"]); }
+
+/**
+ * Stop the native service and prove it is no longer running. `stopwait` can fail both
+ * for the benign already-stopped case and for real access/timeout failures, so a bare
+ * catch cannot decide whether it is safe for lifecycle callers to continue. Re-read
+ * SCM state and only accept the two states that cannot still own the proxy listener.
+ */
+export function stopWinswService(): void {
+  try { runWinsw(["stopwait"]); } catch { /* classify by verified state below */ }
+  const status = statusWinswRaw();
+  if (status === "stopped" || status === "nonexistent") return;
+  if (status === "unknown") {
+    throw new Error("Native service stop could not be verified.");
+  }
+  throw new Error("Native service is still running after stop.");
+}
+
+export function uninstallWinswService(): void {
+  if (!existsSync(winswExePath())) {
+    // The binary is gone but the SCM registration can outlive it (quarantine, partial
+    // uninstall). WinSW can't run without its exe, so remove the stale registration
+    // directly via sc.exe — otherwise the SCM service survives every cleanup path.
+    if (process.platform === "win32") {
+      const probe = probeScmRegistration();
+      if (probe === "error") {
+        // Presence unknown — fail closed: keep service state, surface the failure
+        // instead of reporting a clean uninstall over a possibly-live registration.
+        throw new Error(
+          `Cannot verify the native service registration (sc.exe query failed). ` +
+            `Uninstall aborted; check 'sc query ${WINSW_SERVICE_ID}' and retry.`,
+        );
+      }
+      if (probe === true) {
+        try {
+          execFileSync(scExePath(), ["stop", WINSW_SERVICE_ID], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+        } catch { /* not running */ }
+        execFileSync(scExePath(), ["delete", WINSW_SERVICE_ID], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+      }
+    }
+    return;
+  }
+  try { runWinsw(["stopwait"]); } catch { /* not running */ }
+  try { runWinsw(["uninstall"]); } catch (err) {
+    // Surface the failure so the caller can decide; silent swallow hides UAC refusals.
+    const msg = err instanceof Error ? err.message : String(err);
+    if (!msg.toLowerCase().includes("nonexistent")) throw new Error(`WinSW uninstall failed: ${msg}`);
+    // "NonExistent" means already absent — that's fine.
+  }
+  // exe/xml intentionally retained for credential-free reinstall; `--purge` is out of scope.
+}
+
+export function winswStatusSummary(): string {
+  const status = statusWinswRaw();
+  if (status === "nonexistent") {
+    // A stale SCM service can outlive a deleted exe; surface the repair path.
+    return existsSync(winswXmlPath()) && !existsSync(winswExePath())
+      ? "native assets present but WinSW binary missing — run 'rmx service repair'"
+      : "";
+  }
+  return `native (WinSW ${WINSW_VERSION}): ${status}`;
+}
+
+/** Default entry mirrors the Task Scheduler baking: durable Bun + cli.ts. */
+export function defaultWinswEntry(cliDir: string): WinswEntry {
+  const runtime = durableBunRuntime();
+  return { bun: runtime.path, bunRuntimeSource: runtime.source, cli: join(cliDir, "cli", "index.ts") };
+}