[codex] Fix Windows service install discovery (#1046)

Author: RhysSullivan

.changeset/windows-service-manifest.md

@@ -0,0 +1,5 @@
+---
+"executor": patch
+---
+
+Windows installs now repair stale Executor service listeners and only report success after the background daemon publishes the sign-in manifest used by `executor web`. The desktop app also attaches to a reachable supervised daemon before trusting Windows PID probes, so it no longer starts a competing sidecar when the background service already owns the port.

apps/cli/src/main.ts

@@ -124,7 +124,12 @@ import {
   resolveExecutorDataDir,
   writeLocalServerManifest,
 } from "./local-server-manifest";
-import { DEFAULT_SERVICE_PORT, getServiceBackend, SERVICE_LABEL } from "./service";
+import {
+  DEFAULT_SERVICE_PORT,
+  getServiceBackend,
+  SERVICE_LABEL,
+  stopWindowsExecutorListenersOnPort,
+} from "./service";
 import {
   defaultCliServerConnectionProfile,
   findCliServerConnectionProfile,
@@ -165,6 +170,7 @@ const DEFAULT_BASE_URL = `http://localhost:${DEFAULT_PORT}`;
 const DAEMON_BOOT_TIMEOUT_MS = 15_000;
 const DAEMON_BOOT_POLL_MS = 150;
 const DAEMON_STOP_TIMEOUT_MS = 10_000;
+const SERVICE_BOOT_TIMEOUT_MS = 45_000;
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -197,15 +203,15 @@ const readActiveLocalServerManifest = (): Effect.Effect<
     const manifest = yield* readLocalServerManifest();
     if (!manifest) return null;
 
+    if (yield* isServerReachable(manifest.connection.origin)) {
+      return manifest;
+    }
+
     if (!isPidAlive(manifest.pid)) {
       yield* removeLocalServerManifestIfOwnedBy({ pid: manifest.pid }).pipe(Effect.ignore);
       return null;
     }
 
-    if (yield* isServerReachable(manifest.connection.origin)) {
-      return manifest;
-    }
-
     return yield* Effect.fail(
       new Error(
         [
@@ -2201,6 +2207,68 @@ const mcpCommand = Command.make(
 
 const supervisedServiceOrigin = (port: number): string => `http://127.0.0.1:${port}`;
 
+const LOCAL_SERVICE_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+
+const originPort = (url: URL): string => url.port || (url.protocol === "https:" ? "443" : "80");
+
+const sameServerOrigin = (left: string, right: string): boolean => {
+  const leftUrl = new URL(normalizeExecutorServerConnection({ origin: left }).origin);
+  const rightUrl = new URL(normalizeExecutorServerConnection({ origin: right }).origin);
+  if (leftUrl.toString() === rightUrl.toString()) return true;
+  return (
+    leftUrl.protocol === rightUrl.protocol &&
+    originPort(leftUrl) === originPort(rightUrl) &&
+    LOCAL_SERVICE_HOSTS.has(leftUrl.hostname.toLowerCase()) &&
+    LOCAL_SERVICE_HOSTS.has(rightUrl.hostname.toLowerCase())
+  );
+};
+
+const hasReachableCliDaemonManifest = (input: {
+  readonly origin: string;
+  readonly version: string;
+}): Effect.Effect<boolean, never, FileSystem.FileSystem | PlatformPath.Path> =>
+  Effect.gen(function* () {
+    const manifest = yield* readActiveLocalServerManifest().pipe(
+      Effect.catchCause(() => Effect.succeed(null)),
+    );
+    if (!manifest || manifest.kind !== "cli-daemon") return false;
+    if (!sameServerOrigin(manifest.connection.origin, input.origin)) return false;
+    if (manifest.owner.version !== input.version) return false;
+    return yield* isServerReachable(manifest.connection.origin);
+  });
+
+const clearUnmanifestedWindowsExecutorListener = (input: {
+  readonly port: number;
+  readonly origin: string;
+}): Effect.Effect<void, Error, FileSystem.FileSystem | PlatformPath.Path> =>
+  Effect.gen(function* () {
+    const active = yield* readActiveLocalServerManifest().pipe(
+      Effect.catchCause(() => Effect.succeed(null)),
+    );
+    if (active && sameServerOrigin(active.connection.origin, input.origin)) return;
+    if (!(yield* isServerReachable(input.origin))) return;
+
+    const stoppedPids = yield* stopWindowsExecutorListenersOnPort(input.port);
+    const stopped = yield* waitForUnreachable({
+      check: isServerReachable(input.origin),
+      timeoutMs: DAEMON_STOP_TIMEOUT_MS,
+      intervalMs: DAEMON_BOOT_POLL_MS,
+    });
+    if (stopped) return;
+
+    return yield* Effect.fail(
+      new Error(
+        [
+          `Executor is already reachable at ${input.origin}, but no live server manifest exists for it.`,
+          stoppedPids.length > 0
+            ? `Tried to stop orphaned Executor pid(s): ${stoppedPids.join(", ")}.`
+            : `No orphaned executor.exe listener could be stopped on port ${input.port}.`,
+          "Stop the process using that port and re-run the install.",
+        ].join("\n"),
+      ),
+    );
+  });
+
 const portFromOrigin = (origin: string): number | null => {
   try {
     const url = new URL(origin);
@@ -2274,7 +2342,10 @@ const installService = (port: number, commandName: string) =>
       return;
     }
 
-    if (plan === "takeover-then-install") {
+    if (
+      plan === "takeover-then-install" ||
+      (backend.platform === "win32" && plan === "reinstall")
+    ) {
       const replaced = yield* takeOverActiveLocalServer();
       if (replaced) {
         console.log(
@@ -2294,22 +2365,29 @@ const installService = (port: number, commandName: string) =>
     console.log("");
     console.log("Writing the service definition and starting Executor...");
 
+    if (backend.platform === "win32") {
+      yield* clearUnmanifestedWindowsExecutorListener({ port, origin });
+    }
+
     // The unit carries no secret: the supervised daemon mints/loads its bearer
     // from auth.json (under EXECUTOR_DATA_DIR) on first boot, and clients read
     // the same file — so reachability is the credential-free /api/health probe.
     yield* backend.install({ executablePath: process.execPath, port, version: CLI_VERSION });
 
-    console.log(`Waiting for Executor to become reachable at ${origin}...`);
+    console.log(`Waiting for Executor to publish its service manifest at ${origin}...`);
     const reachable = yield* waitForReachable({
-      check: isServerReachable(origin),
-      timeoutMs: DAEMON_BOOT_TIMEOUT_MS,
+      check: hasReachableCliDaemonManifest({
+        origin,
+        version: CLI_VERSION,
+      }),
+      timeoutMs: SERVICE_BOOT_TIMEOUT_MS,
       intervalMs: DAEMON_BOOT_POLL_MS,
     });
     if (!reachable) {
       return yield* Effect.fail(
         new Error(
           [
-            `Installed ${SERVICE_LABEL} but it did not become reachable at ${origin} within ${DAEMON_BOOT_TIMEOUT_MS / 1000}s.`,
+            `Installed ${SERVICE_LABEL} but it did not publish a reachable server manifest for ${origin} within ${SERVICE_BOOT_TIMEOUT_MS / 1000}s.`,
             `Check ~/.executor/logs/daemon.error.log and \`${cliPrefix} service status\`.`,
           ].join("\n"),
         ),
@@ -2334,19 +2412,25 @@ const serviceInstallCommand = Command.make(
 const serviceUninstallCommand = Command.make("uninstall", {}, () =>
   Effect.gen(function* () {
     const backend = getServiceBackend();
-    const wasRunning = backend.automated
-      ? yield* backend.status().pipe(
-          Effect.map((status) => status.running),
-          Effect.catchCause(() => Effect.succeed(false)),
-        )
-      : false;
+    const activeBefore = yield* readActiveLocalServerManifest().pipe(
+      Effect.catchCause(() => Effect.succeed(null)),
+    );
+    const servicePort = activeBefore
+      ? (portFromOrigin(activeBefore.connection.origin) ?? DEFAULT_SERVICE_PORT)
+      : DEFAULT_SERVICE_PORT;
+    const status = backend.automated
+      ? yield* backend.status().pipe(Effect.catchCause(() => Effect.succeed(null)))
+      : null;
     yield* backend.uninstall();
-    if (wasRunning) {
-      const stopped = yield* takeOverActiveLocalServer({ onlyKind: "cli-daemon" });
-      if (stopped) {
-        console.log(
-          `Stopped running Executor daemon at ${stopped.connection.origin} (pid ${stopped.pid}).`,
-        );
+    const stopped = yield* takeOverActiveLocalServer({ onlyKind: "cli-daemon" });
+    if (stopped) {
+      console.log(
+        `Stopped running Executor daemon at ${stopped.connection.origin} (pid ${stopped.pid}).`,
+      );
+    } else if (backend.platform === "win32" && status?.registered) {
+      const stoppedPids = yield* stopWindowsExecutorListenersOnPort(servicePort);
+      if (stoppedPids.length > 0) {
+        console.log(`Stopped orphaned Executor daemon pid(s): ${stoppedPids.join(", ")}.`);
       }
     }
     console.log("Executor background service uninstalled.");

apps/cli/src/service.test.ts

@@ -6,6 +6,7 @@ import {
   generateSystemdUnit,
   generateWindowsDaemonWrapper,
   generateWindowsRegisterScript,
+  generateWindowsStopExecutorListenersScript,
   getServiceBackend,
 } from "./service";
 
@@ -136,6 +137,16 @@ describe("service unit generation", () => {
     expect(script).toContain("Register-ScheduledTask -TaskName 'ExecutorDaemon'");
     expect(script).toContain("Start-ScheduledTask -TaskName 'ExecutorDaemon'");
   });
+
+  it("stops orphaned executor.exe listeners without shadowing PowerShell's $PID", () => {
+    const script = generateWindowsStopExecutorListenersScript(4789);
+
+    expect(script).toContain("Get-NetTCPConnection -LocalPort 4789 -State Listen");
+    expect(script).toContain("$listenerPid");
+    expect(script).not.toContain("foreach ($pid");
+    expect(script).toContain("[string]$process.Name -ieq 'executor.exe'");
+    expect(script).toContain('Write-Output ("STOPPED=" + $listenerPid)');
+  });
 });
 
 describe("service backend dispatch", () => {

apps/cli/src/service.ts

@@ -579,6 +579,28 @@ export const generateWindowsRegisterScript = (options: {
     `Start-ScheduledTask -TaskName ${psSingleQuote(options.taskName)}`,
   ].join("\n");
 
+/**
+ * Stop orphaned Windows `executor.exe` listeners on the service port. Task
+ * Scheduler can report the task as stopped after terminating the `.cmd` action
+ * while leaving the child `executor.exe` process bound to 4789. That process is
+ * healthy enough to satisfy `/api/health`, but `executor web` cannot discover it
+ * once its `server.json` is gone.
+ */
+export const generateWindowsStopExecutorListenersScript = (port: number): string =>
+  [
+    `$connections = @(Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue)`,
+    `$listenerPids = @($connections | Select-Object -ExpandProperty OwningProcess -Unique)`,
+    `foreach ($listenerPid in $listenerPids) {`,
+    `  $process = Get-CimInstance Win32_Process -Filter "ProcessId=$listenerPid" -ErrorAction SilentlyContinue`,
+    `  if ($null -eq $process) { continue }`,
+    `  $pathName = if ($process.ExecutablePath) { [System.IO.Path]::GetFileName([string]$process.ExecutablePath) } else { '' }`,
+    `  if ([string]$process.Name -ieq 'executor.exe' -or $pathName -ieq 'executor.exe') {`,
+    `    Stop-Process -Id $listenerPid -Force -ErrorAction SilentlyContinue`,
+    `    Write-Output ("STOPPED=" + $listenerPid)`,
+    `  }`,
+    `}`,
+  ].join("\n");
+
 /** Run a PowerShell script via -EncodedCommand (sidesteps all shell quoting). */
 const runPowerShell = (script: string): Effect.Effect<CommandResult, Error> =>
   runCommand("powershell.exe", [
@@ -590,6 +612,25 @@ const runPowerShell = (script: string): Effect.Effect<CommandResult, Error> =>
     Buffer.from(script, "utf16le").toString("base64"),
   ]);
 
+export const stopWindowsExecutorListenersOnPort = (
+  port: number,
+): Effect.Effect<ReadonlyArray<number>, Error> =>
+  Effect.gen(function* () {
+    const result = yield* runPowerShell(generateWindowsStopExecutorListenersScript(port));
+    if (result.code !== 0) {
+      const detail = result.stderr.trim() || result.stdout.trim();
+      return yield* Effect.fail(
+        new Error(`Failed to inspect Executor listeners on port ${port}: ${detail}`),
+      );
+    }
+    return result.stdout.split(/\r?\n/).flatMap((line) => {
+      const match = /^STOPPED=(\d+)\s*$/.exec(line.trim());
+      if (!match) return [];
+      const pid = Number.parseInt(match[1], 10);
+      return Number.isInteger(pid) && pid > 0 ? [pid] : [];
+    });
+  });
+
 const makeWindowsBackend = (): ServiceBackend => ({
   platform: "win32",
   automated: true,

apps/desktop/package.json

@@ -16,6 +16,7 @@
     "package:mac": "electron-builder --mac --config electron-builder.config.ts",
     "package:win": "electron-builder --win --config electron-builder.config.ts",
     "package:linux": "electron-builder --linux --config electron-builder.config.ts",
+    "test": "bun --bun vitest run",
     "test:smoke": "bun ./scripts/smoke-sidecar.ts",
     "typecheck": "tsgo --noEmit",
     "typecheck:slow": "tsc --noEmit"
@@ -29,6 +30,7 @@
     "electron-window-state": "^5.0.3"
   },
   "devDependencies": {
+    "@effect/vitest": "catalog:",
     "@executor-js/app": "workspace:*",
     "@executor-js/local": "workspace:*",
     "@executor-js/plugin-desktop-settings": "workspace:*",
@@ -50,6 +52,7 @@
     "electron-vite": "^5",
     "quickjs-emscripten": "catalog:",
     "typescript": "catalog:",
-    "vite": "catalog:"
+    "vite": "catalog:",
+    "vitest": "catalog:"
   }
 }

apps/desktop/src/main/sidecar.ts

@@ -24,6 +24,7 @@ import {
 import { loadOrMintLocalAuthToken } from "./local-auth";
 import { getServerSettings } from "./settings";
 import { reportSidecarCrash, sidecarCrashReportingEnv } from "./diagnostics";
+import { resolveSupervisedDaemonAttach } from "./supervised-daemon";
 import { SERVER_SETTINGS_USERNAME, type DesktopServerSettings } from "../shared/server-settings";
 
 // Sidecar output is echoed to the terminal (visible when Electron is run
@@ -465,10 +466,9 @@ const isDaemonReachable = async (origin: string): Promise<boolean> => {
 
 /**
  * Attach to an already-running OS-supervised daemon instead of spawning our own
- * sidecar. Reads `server.json`, confirms the recorded process is alive and the
- * endpoint answers, and returns a child-less `SidecarConnection` flagged
- * `supervisedDaemon: true`. Returns null when no usable supervised daemon is
- * present.
+ * sidecar. Reads `server.json`, confirms the endpoint answers, and returns a
+ * child-less `SidecarConnection` flagged `supervisedDaemon: true`. Returns null
+ * when no usable supervised daemon is present.
  *
  * Only a `cli-daemon` manifest is treated as supervised — a `desktop-sidecar`
  * manifest belongs to a managed sidecar (ours or another desktop instance) and
@@ -477,36 +477,40 @@ const isDaemonReachable = async (origin: string): Promise<boolean> => {
 export async function attachToSupervisedDaemon(): Promise<SidecarConnection | null> {
   const dataDir = join(homedir(), ".executor");
   const manifest = readManifest(dataDir);
-  if (!manifest || manifest.kind !== "cli-daemon") return null;
-  if (!isPidAlive(manifest.pid)) {
-    removeManifestIfOwnedBy(dataDir, manifest.pid);
-    return null;
+  const decision = await resolveSupervisedDaemonAttach(manifest, {
+    isReachable: isDaemonReachable,
+    isPidAlive,
+  });
+  if (decision._tag === "Attach") {
+    const { manifest, authToken } = decision;
+    const origin = manifest.connection.origin;
+    const url = new URL(origin);
+    sidecarLog.info(`attaching to supervised daemon at ${origin} (pid ${manifest.pid})`);
+    return {
+      baseUrl: origin,
+      hostname: url.hostname,
+      port: Number.parseInt(url.port, 10) || (url.protocol === "https:" ? 443 : 80),
+      username: SERVER_SETTINGS_USERNAME,
+      authToken,
+      child: null,
+      supervisedDaemon: true,
+      ownerVersion: manifest.owner.version,
+      ownerClient: manifest.owner.client,
+      ownerExecutablePath: manifest.owner.executablePath,
+    };
   }
 
-  const origin = manifest.connection.origin;
-  const auth = manifest.connection.auth;
-  const authToken = auth && auth.kind === "bearer" ? auth.token : "";
-  if (!(await isDaemonReachable(origin))) {
-    sidecarLog.warn(
-      `supervised daemon at ${origin} (pid ${manifest.pid}) did not answer the health probe; keeping its manifest because the process is still alive`,
-    );
+  if (decision._tag === "RemoveStaleManifest") {
+    removeManifestIfOwnedBy(dataDir, decision.pid);
     return null;
   }
 
-  const url = new URL(origin);
-  sidecarLog.info(`attaching to supervised daemon at ${origin} (pid ${manifest.pid})`);
-  return {
-    baseUrl: origin,
-    hostname: url.hostname,
-    port: Number.parseInt(url.port, 10) || (url.protocol === "https:" ? 443 : 80),
-    username: SERVER_SETTINGS_USERNAME,
-    authToken,
-    child: null,
-    supervisedDaemon: true,
-    ownerVersion: manifest.owner.version,
-    ownerClient: manifest.owner.client,
-    ownerExecutablePath: manifest.owner.executablePath,
-  };
+  if (!manifest || manifest.kind !== "cli-daemon") return null;
+
+  sidecarLog.warn(
+    `supervised daemon at ${manifest.connection.origin} (pid ${manifest.pid}) did not answer the health probe; keeping its manifest because the process is still alive`,
+  );
+  return null;
 }
 
 export async function stopSidecar(child: ChildProcess): Promise<void> {