From fb12dce5630437fa9957bc8c31e744f1ecec331b Mon Sep 17 00:00:00 2001
From: Janic Duplessis <janicduplessis@gmail.com>
Date: Tue, 13 Oct 2026 03:43:12 -0400
Subject: [PATCH 1/4] docs: document stim-server service and setup on Windows

---
 AGENTS.md                               | 13 +++---
 packages/server/README.md               | 57 ++++++++++++++++++++++---
 packages/stim-cli/src/guide/settings.ts |  4 +-
 website/docs/remote-machines.md         | 37 +++++++++++-----
 website/docs/settings.md                | 10 +++--
 5 files changed, 93 insertions(+), 28 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 3bd8794ff..a4cf33b6e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -324,15 +324,18 @@ outside it moves to its own issue and pull request.
   and stim-server stops it when the build is cancelled, the client loses
   `build`, or the machine's available memory runs low. Gradle stops a daemon
   whose Gradle home is deleted. `stim-server service` installs,
-  reports and removes the worker's per-user service, a LaunchAgent on macOS
-  or a systemd user unit on Linux, and, only when asked, a tailnet-only serve
-  route; it never enables Funnel, never runs sudo and never touches pairings,
+  reports and removes the worker's per-user service, a LaunchAgent on macOS,
+  a systemd user unit on Linux or a scheduled task on Windows, whose action is
+  Stim's supervisor because Task Scheduler does not restart an exited process,
+  and, only when asked, a tailnet-only serve
+  route; it never enables Funnel, never runs sudo or elevates, and never touches pairings,
   `$STIM_HOME/server` or settings. `stim-server service update` and
   `rollback` install a server version beside the running one under
   `~/Library/Application Support/Stim/services/<label>/versions/` on macOS or
-  `~/.local/share/stim/services/<label>/versions/` on Linux, keeping the
+  `~/.local/share/stim/services/<label>/versions/` on Linux or
+  `%LOCALAPPDATA%\Stim\services\<label>\versions\` on Windows, keeping the
   running and the previous version, and repoint only the service's server
-  script; a failed health check switches back. A Linux worker takes Android
+  script; a failed health check switches back. A Linux or Windows worker takes Android
   builds only; setup there approves `build` and refuses `device-host`, and off macOS
   stim-server refuses device-host requests and grants. A client approved for `build` or
   `device-host` can run the same update on this machine over the tailnet, and no
diff --git a/packages/server/README.md b/packages/server/README.md
index b930e34d4..ed2171ba6 100644
--- a/packages/server/README.md
+++ b/packages/server/README.md
@@ -116,11 +116,11 @@ If the server is not installed globally, use `npx --yes --package @stim-cli/serv
 in place of `stim-server`, with the exact version from the client machine.
 At least one capability is required. The expiry must be in the future and at
 most two hours ahead. The defaults are port 7787 and label `dev.stim.server`.
-Argument and preflight refusals change nothing. Preflight requires macOS or
-Linux, Node 22.12+, running Tailscale, the client node on this tailnet, and
+Argument and preflight refusals change nothing. Preflight requires macOS,
+Linux or Windows, Node 22.12+, running Tailscale, the client node on this tailnet, and
 this user's GUI login session on macOS or systemd user manager on Linux. On
-Linux, setup takes `--build` only and refuses `--device-host`, because hosting
-needs a Mac; see [On Linux](#on-linux). Off macOS, stim-server also refuses a
+Linux and Windows, setup takes `--build` only and refuses `--device-host`, because hosting
+needs a Mac; see [On Linux](#on-linux) and [On Windows](#on-windows). Off macOS, stim-server also refuses a
 device-host request at hello and `stim-server devices grant <id> --device-host`.
 
 Running setup on the worker is the worker-side approval. It pre-approves at
@@ -141,7 +141,7 @@ any change. Requests themselves lapse after 15 minutes.
 Setup installs its exact server release into the service's `versions/`
 directory (`~/Library/Application Support/Stim/services/<label>/versions/` on
 macOS), installs Stim Host on macOS, installs or reuses the managed
-LaunchAgent or systemd user service, and creates or reuses a
+LaunchAgent, systemd user service or scheduled task, and creates or reuses a
 tailnet-only HTTPS route on 7443 or the next free port. Older managed services
 use the service update busy-wait and rollback behavior. Newer versions stay
 installed; tools report a Stim build difference. A reused server must be at
@@ -1024,7 +1024,8 @@ before replacement. Automatic placement remains in
 ## Run as a service
 
 `stim-server service install` runs stim-server as a per-user LaunchAgent on
-macOS, or a systemd user service on Linux ([On Linux](#on-linux)), so a remote
+macOS, a systemd user service on Linux ([On Linux](#on-linux)), or a scheduled
+task on Windows ([On Windows](#on-windows)), so a remote
 machine or a phone-serving Mac keeps it running without a terminal. Other
 systems refuse; start stim-server from your own service manager there:
 
@@ -1226,6 +1227,50 @@ installs Stim Host and has no permission grants.
   `--device-host`, needs no GUI session, and skips Stim Host, the permission
   steps and the Xcode, iOS runtime and CocoaPods checks.
 
+### On Windows
+
+On Windows, `service` manages a per-user scheduled task with the same commands,
+flags and checks, and never needs elevation. A Windows machine takes offloaded
+Android builds only, so it never installs Stim Host and has no permission
+grants.
+
+- `install` writes the service file
+  `%LOCALAPPDATA%\Stim\services\<label>.json` (the server's `node`, script,
+  arguments and environment, `STIM_SERVICE_LABEL=<label>`, the serve route and
+  the previous server script), copies the supervisor
+  `stim-service-runner.mjs` into `%LOCALAPPDATA%\Stim\services\<label>\`, and
+  registers the task `\Stim\<label>` with `schtasks /Create`, then starts it.
+  It logs to `%LOCALAPPDATA%\Stim\Logs\<label>.log`.
+- The task starts at your logon and runs whether or not you are logged on
+  (Task Scheduler's S4U logon type, which an ordinary user can register), so it
+  keeps running after you sign out; after a reboot it starts at your next
+  logon. Task Scheduler restarts a task only when it fails to start, not when
+  its process exits, so the task runs the supervisor, which restarts the
+  server 30 seconds after it exits and reads the service file again each time.
+  The supervisor records its pid, the server's, the number of runs and the last
+  exit code in `supervisor.json`, which `status` reports.
+- Stopping the service ends the supervisor's process tree with
+  `taskkill /T /F`; a remote update the server starts runs detached from that
+  tree, so restarting the service does not stop it.
+- `update` and `rollback` keep versions under
+  `%LOCALAPPDATA%\Stim\services\<label>\versions\` and rewrite only the
+  service file's arguments and previous script. `uninstall` stops the task,
+  deletes it and removes the service file.
+- The task's environment is your user environment, without a login shell.
+  Builds start tools such as Expo's config loader with the first `node.exe` on
+  `PATH`, and a version manager's `node.exe` shim, such as pnpm's, breaks their
+  Node IPC, so builds fail with `fingerprint-mismatch`. Stim keeps `PATH` as
+  you set it; `install` names a first `node.exe` that is not the Node running
+  the server, and `--path-prepend` puts the real Node first:
+
+  ```powershell
+  stim-server service install --serve --path-prepend "C:\Program Files\nodejs" `
+    --env JAVA_HOME="C:\Program Files\Eclipse Adoptium\jdk-17" `
+    --env ANDROID_HOME="$env:LOCALAPPDATA\Android\Sdk"
+  ```
+
+- `stim-server setup` works on Windows for `--build`, as on Linux.
+
 ## Remote update
 
 A machine this one approved for builds (`--build`) or device hosting
diff --git a/packages/stim-cli/src/guide/settings.ts b/packages/stim-cli/src/guide/settings.ts
index bf10c3855..bcf3bf6b1 100644
--- a/packages/stim-cli/src/guide/settings.ts
+++ b/packages/stim-cli/src/guide/settings.ts
@@ -984,9 +984,9 @@ when a build is cancelled, the client is revoked, or the machine has less
 than 2 GB of memory available, and deleting the client's directory under the
 worker root stops it too.
 \`stim-server service install [--serve]\` on a remote machine keeps stim-server
-running as a login LaunchAgent on macOS or a systemd user service on Linux
+running as a login LaunchAgent on macOS, a systemd user service on Linux
 (\`sudo loginctl enable-linger <user>\` keeps it running after logout; install
-prints that command and never runs it); \`--path-prepend <dir>\` and \`--env KEY=VALUE\`
+prints that command and never runs it), or a logon scheduled task on Windows; \`--path-prepend <dir>\` and \`--env KEY=VALUE\`
 pin a PATH entry or variable, such as a private CocoaPods, that stim-server's
 toolchain discovery does not find.
 \`stim-server service update --release <version>\` there moves the service to
diff --git a/website/docs/remote-machines.md b/website/docs/remote-machines.md
index 4e2bc2475..bc3c8f466 100644
--- a/website/docs/remote-machines.md
+++ b/website/docs/remote-machines.md
@@ -567,18 +567,33 @@ the Windows machine:
 
 1. Install Node 22.12.0 or later, Tailscale signed in to the same tailnet,
    JDK 17 and the Android SDK with the project's NDK, build-tools and compile
-   SDK, and set `JAVA_HOME` and `ANDROID_HOME`.
-2. Serve stim-server on a tailnet-only route once:
-   `tailscale serve --bg --https=7443 http://127.0.0.1:7787`.
-3. Install the server globally with `npm install --global @stim-cli/server@latest`
-   and start it yourself: `stim-server`
-   (`setup` and `service` are macOS and Linux only).
-   Start it with a real Node first on `PATH`. A version manager's `node.exe`
-   shim, such as pnpm's, breaks the Node IPC that Expo's config loader uses,
-   and the build then fails with `fingerprint-mismatch`.
-4. On your main machine, add it to `remote.machines` and run
+   SDK.
+2. Install the server globally and run it as a scheduled task with a
+   tailnet-only route. No administrator rights are needed:
+
+   ```powershell
+   npm install --global @stim-cli/server@latest
+   stim-server service install --serve --path-prepend "C:\Program Files\nodejs" `
+     --env JAVA_HOME="C:\Program Files\Eclipse Adoptium\jdk-17" `
+     --env ANDROID_HOME="$env:LOCALAPPDATA\Android\Sdk"
+   stim-server service status
+   ```
+
+   The task starts at your logon and keeps running after you sign out; the
+   log is `%LOCALAPPDATA%\Stim\Logs\dev.stim.server.log`. `service update`
+   and `service rollback` work as on a Mac, and an approved client can update
+   the server remotely.
+   `--path-prepend` puts the real Node first on the server's `PATH`. A version
+   manager's `node.exe` shim, such as pnpm's, breaks the Node IPC that Expo's
+   config loader uses, and the build then fails with `fingerprint-mismatch`;
+   `install` says so when the first `node.exe` on `PATH` is not the Node that
+   runs the server.
+
+3. On your main machine, add it to `remote.machines` and run
    `stim doctor --fix` as above. Approve the request on the Windows machine
-   with `stim-server devices grant <build-id> --build`.
+   with `stim-server devices grant <build-id> --build`, or run the setup
+   command Desktop generates there with `--build` only. Setup on Windows
+   refuses `--device-host` and skips Stim Host and the permission steps.
 
 The NDK's ninja on Windows cannot open a path longer than 260 characters, so
 a Windows worker keeps each checkout and each client's Gradle home in a short
diff --git a/website/docs/settings.md b/website/docs/settings.md
index d14aaea29..f4c299386 100644
--- a/website/docs/settings.md
+++ b/website/docs/settings.md
@@ -505,7 +505,9 @@ each client machine.
 On the remote machine, `server.workerRoot` (an absolute path; default
 `$STIM_HOME/build-worker`) holds each client's checkouts, dependencies,
 DerivedData, compilation cache, ccache and Gradle home, with a separate Stim
-home per client and repository and one Gradle home per client. Put it on a
+home per client and repository and one Gradle home per client. On a Windows
+machine, the checkouts and Gradle homes themselves live in short directories
+under `C:\sw` instead (see [Windows worker](./remote-machines.md#windows-worker)). Put it on a
 large volume. It runs one offloaded build at a time and boots or installs
 nothing. It declines a build while that volume has less than 10 GB free,
 while its own Stim builds and the offloaded one fill its
@@ -531,9 +533,9 @@ client's directory under the worker root stops it too.
 
 To keep stim-server running on a remote machine across logins, run
 `stim-server service install --serve` there. It installs a per-user LaunchAgent
-that starts at login on macOS, or a systemd user service on Linux (with
-`sudo loginctl enable-linger $USER` so it starts at boot), and restarts the
-server if it exits. `--serve` adds the
+that starts at login on macOS, a systemd user service on Linux (with
+`sudo loginctl enable-linger $USER` so it starts at boot), or a scheduled task
+on Windows that starts at logon, and restarts the server if it exits. `--serve` adds the
 tailnet-only `tailscale serve` route (port 7443, or the next free one). `--path-prepend <dir>` and
 `--env KEY=VALUE` pin a PATH entry or a variable, such as a private CocoaPods
 install, that stim-server's toolchain discovery does not find.

From 82678226a53aa050e834c70793d5d61509e53d7c Mon Sep 17 00:00:00 2001
From: Janic Duplessis <janicduplessis@gmail.com>
Date: Tue, 13 Oct 2026 03:42:42 -0400
Subject: [PATCH 2/4] feat: run stim-server service and setup on Windows as a
 scheduled task

---
 .../server/__tests__/service-task.test.ts     | 100 ++++++++++
 packages/server/__tests__/setup.test.ts       | 100 +++++-----
 packages/server/bin/stim-server.ts            |   2 +-
 packages/server/src/service-manager.ts        | 176 +++++++++++++++++-
 packages/server/src/service-runner.ts         |  83 +++++++++
 packages/server/src/service-task.ts           | 149 +++++++++++++++
 packages/server/src/service.ts                |  84 +++++++--
 packages/server/src/setup.ts                  |  70 ++++---
 packages/server/tsdown.config.mts             |   1 +
 9 files changed, 664 insertions(+), 101 deletions(-)
 create mode 100644 packages/server/__tests__/service-task.test.ts
 create mode 100644 packages/server/src/service-runner.ts
 create mode 100644 packages/server/src/service-task.ts

diff --git a/packages/server/__tests__/service-task.test.ts b/packages/server/__tests__/service-task.test.ts
new file mode 100644
index 000000000..c38212de8
--- /dev/null
+++ b/packages/server/__tests__/service-task.test.ts
@@ -0,0 +1,100 @@
+import type { ServiceSpec } from '../src/service-plist.ts';
+import { netstatListeners } from '../src/service.ts';
+import { editTask, parseTask, renderTask, renderTaskXml, windowsArgument } from '../src/service-task.ts';
+
+const SPEC: ServiceSpec = {
+  label: 'dev.stim.server',
+  host: null,
+  node: 'C:\\Program Files\\nodejs\\node.exe',
+  script: 'C:\\Users\\me\\AppData\\Roaming\\npm\\node_modules\\@stim-cli\\server\\dist\\stim-server.mjs',
+  port: 7787,
+  env: ['JAVA_HOME=C:\\Program Files\\Eclipse Adoptium\\jdk-17', 'TOKEN=a"b'],
+  pathPrepend: ['C:\\Program Files\\nodejs'],
+  environment: { STIM_HOME: 'C:\\Users\\me\\.stim' },
+  logPath: 'C:\\Users\\me\\AppData\\Local\\Stim\\Logs\\dev.stim.server.log',
+  workingDirectory: 'C:\\Users\\me',
+  serve: { port: 7443, created: true },
+};
+
+describe('Windows service file', () => {
+  it('reads back what it wrote, with the env values and the serve record', () => {
+    expect(parseTask(renderTask(SPEC))).toEqual({
+      label: 'dev.stim.server',
+      host: null,
+      node: SPEC.node,
+      script: SPEC.script,
+      port: 7787,
+      env: SPEC.env,
+      pathPrepend: SPEC.pathPrepend,
+      stimHome: 'C:\\Users\\me\\.stim',
+      logPath: SPEC.logPath,
+      managed: true,
+      serve: { port: 7443, created: true },
+      previousScript: null,
+      programArguments: expect.arrayContaining([SPEC.node, SPEC.script, '--port', '7787']),
+    });
+  });
+
+  it('switches the server script and records the previous one, or replaces only the serve record', () => {
+    const installed = parseTask(renderTask(SPEC));
+    const switched = parseTask(
+      editTask(renderTask(SPEC), {
+        programArguments: [SPEC.node, 'C:\\new\\stim-server.mjs', ...(installed?.programArguments.slice(2) ?? [])],
+        previousScript: SPEC.script,
+      }),
+    );
+    expect(switched).toMatchObject({ script: 'C:\\new\\stim-server.mjs', previousScript: SPEC.script, port: 7787 });
+    expect(switched?.env).toEqual(SPEC.env);
+    expect(parseTask(editTask(renderTask(SPEC), { serve: { port: 8443, created: false } }))).toMatchObject({
+      serve: { port: 8443, created: false },
+      script: SPEC.script,
+    });
+  });
+
+  it('is not a service install wrote unless it says so', () => {
+    expect(parseTask(renderTask(SPEC).replace('"managed": true', '"managed": false'))?.managed).toBe(false);
+    expect(parseTask('not json')).toBeNull();
+  });
+});
+
+describe('Windows scheduled task', () => {
+  it('quotes words the way the C runtime splits them', () => {
+    expect(windowsArgument('C:\\Program Files\\x.mjs')).toBe('"C:\\Program Files\\x.mjs"');
+    expect(windowsArgument('a"b')).toBe('"a\\"b"');
+    expect(windowsArgument('C:\\dir\\')).toBe('"C:\\dir\\\\"');
+  });
+
+  it('runs the supervisor at the user logon without elevation, with XML-escaped paths', () => {
+    const xml = renderTaskXml({
+      label: 'dev.stim.server',
+      user: 'HOST\\me',
+      node: 'C:\\R&D\\node.exe',
+      runner: 'C:\\Users\\me\\AppData\\Local\\Stim\\services\\dev.stim.server\\stim-service-runner.mjs',
+      file: 'C:\\Users\\me\\AppData\\Local\\Stim\\services\\dev.stim.server.json',
+      state: 'C:\\Users\\me\\AppData\\Local\\Stim\\services\\dev.stim.server\\supervisor.json',
+      workingDirectory: 'C:\\Users\\me',
+    });
+    expect(xml).toContain('<LogonTrigger><Enabled>true</Enabled><UserId>HOST\\me</UserId></LogonTrigger>');
+    expect(xml).toContain('<LogonType>S4U</LogonType><RunLevel>LeastPrivilege</RunLevel>');
+    expect(xml).toContain('<Command>C:\\R&#38;D\\node.exe</Command>');
+    expect(xml).toMatch(
+      /<Arguments>&#34;C:\\Users.*stim-service-runner\.mjs&#34; .*supervisor\.json&#34; &#34;30&#34;<\/Arguments>/,
+    );
+  });
+});
+
+test('netstat listeners are the pids listening on exactly that port', () => {
+  const output = [
+    '',
+    'Active Connections',
+    '',
+    '  Proto  Local Address          Foreign Address        State           PID',
+    '  TCP    0.0.0.0:135            0.0.0.0:0              LISTENING       1012',
+    '  TCP    127.0.0.1:7787         0.0.0.0:0              LISTENING       4242',
+    '  TCP    127.0.0.1:7787         127.0.0.1:50000        ESTABLISHED     4242',
+    '  TCP    100.100.38.114:7787    0.0.0.0:0              LISTENING       4242',
+    '  TCP    127.0.0.1:17787        0.0.0.0:0              LISTENING       99',
+    '  TCP    [::]:7787              [::]:0                 LISTENING       4243',
+  ].join('\r\n');
+  expect(netstatListeners(output, 7787)).toEqual(['4242', '4243']);
+});
diff --git a/packages/server/__tests__/setup.test.ts b/packages/server/__tests__/setup.test.ts
index cbcf87530..08465aa64 100644
--- a/packages/server/__tests__/setup.test.ts
+++ b/packages/server/__tests__/setup.test.ts
@@ -474,54 +474,60 @@ test('a new worker installs the exact release and records route ownership only a
   expect(JSON.parse(f.stdout[0]!).route.port).toBe(7449);
 });
 
-test('on Linux, setup approves builds under a systemd user service without Stim Host or Apple tools', async () => {
-  const f = fixture({
-    platform: 'linux',
-    installed: async () => ({
-      label: 'dev.stim.server',
-      host: null,
-      node: '/node',
-      script: '/server.mjs',
-      port: 7787,
-      env: [],
-      pathPrepend: [],
-      stimHome: home,
-      logPath: '/log',
-      managed: true,
-      serve: { port: 7447, created: false },
-      previousScript: null,
-      programArguments: [],
-    }),
-    installJob: async (_opts, setup) => {
-      expect(setup?.host).toBeNull();
-      f.actions.push('service');
-      return [];
-    },
-    toolchain: async () => ({
-      stimBuild: 'digest',
-      arch: 'x64',
-      xcode: null,
-      simulatorSdk: null,
-      macosSdk: null,
-      cocoapods: null,
-      runtimes: [],
-      jdk: '17',
-      androidSdk: { ndk: ['27'], buildTools: ['36'], platforms: ['36'] },
-    }),
-  });
-  expect(await runSetup([...args, '--yes', '--json'], '1.16.0', f.deps)).toBe(0);
-  expect(f.actions).toEqual(['service']);
-  expect(f.grants).toEqual([{ id: 'build-id', capabilities: ['build'] }]);
-  const output = JSON.parse(f.stdout.join(''));
-  expect(
-    output.tools.filter((t: { state: string }) => t.state !== 'present').map((t: { tool: string }) => t.tool),
-  ).toEqual(['Xcode', 'iOS runtime', 'CocoaPods']);
-  expect(readSetupJournal(options.ticketHash)?.steps.some((s) => s.id === 'host')).toBe(false);
-});
+test.each(['linux', 'win32'] as const)(
+  'on %s, setup approves builds under its user service without Stim Host or Apple tools',
+  async (platform) => {
+    const f = fixture({
+      platform,
+      installed: async () => ({
+        label: 'dev.stim.server',
+        host: null,
+        node: '/node',
+        script: '/server.mjs',
+        port: 7787,
+        env: [],
+        pathPrepend: [],
+        stimHome: home,
+        logPath: '/log',
+        managed: true,
+        serve: { port: 7447, created: false },
+        previousScript: null,
+        programArguments: [],
+      }),
+      installJob: async (_opts, setup) => {
+        expect(setup?.host).toBeNull();
+        f.actions.push('service');
+        return [];
+      },
+      toolchain: async () => ({
+        stimBuild: 'digest',
+        arch: 'x64',
+        xcode: null,
+        simulatorSdk: null,
+        macosSdk: null,
+        cocoapods: null,
+        runtimes: [],
+        jdk: '17',
+        androidSdk: { ndk: ['27'], buildTools: ['36'], platforms: ['36'] },
+      }),
+    });
+    expect(await runSetup([...args, '--yes', '--json'], '1.16.0', f.deps)).toBe(0);
+    expect(f.actions).toEqual(['service']);
+    expect(f.grants).toEqual([{ id: 'build-id', capabilities: ['build'] }]);
+    const output = JSON.parse(f.stdout.join(''));
+    expect(
+      output.tools.filter((t: { state: string }) => t.state !== 'present').map((t: { tool: string }) => t.tool),
+    ).toEqual(['Xcode', 'iOS runtime', 'CocoaPods']);
+    expect(readSetupJournal(options.ticketHash)?.steps.some((s) => s.id === 'host')).toBe(false);
+  },
+);
 
-test('on Linux, setup refuses device hosting before preflight', async () => {
+test.each([
+  ['linux', 'On Linux'],
+  ['win32', 'On Windows'],
+] as const)('on %s, setup refuses device hosting before preflight', async (platform, where) => {
   const f = fixture({
-    platform: 'linux',
+    platform,
     preflight: async () => {
       throw new Error('Preflight must not run');
     },
@@ -529,7 +535,7 @@ test('on Linux, setup refuses device hosting before preflight', async () => {
   expect(await runSetup([...args, '--device-host', '--json'], '1.16.0', f.deps)).toBe(1);
   expect(f.actions).toEqual([]);
   expect(f.grants).toEqual([]);
-  expect(JSON.parse(f.stdout.join('')).warnings.join('\n')).toContain('Hosting simulators needs a Mac');
+  expect(JSON.parse(f.stdout.join('')).warnings.join('\n')).toContain(`Hosting simulators needs a Mac. ${where}, run`);
 });
 
 test('a newer managed server stays installed and a different Stim build produces partial success', async () => {
diff --git a/packages/server/bin/stim-server.ts b/packages/server/bin/stim-server.ts
index d69c2be78..60e491a58 100644
--- a/packages/server/bin/stim-server.ts
+++ b/packages/server/bin/stim-server.ts
@@ -65,7 +65,7 @@ const USAGE = `Usage:
   stim-server service install [--port <n>] [--label <name>] [--serve]
                               [--env KEY=VALUE]... [--path-prepend <dir>]...
                                     run stim-server as a macOS LaunchAgent that starts at login,
-                                    or a Linux systemd user service;
+                                    a Linux systemd user service, or a Windows scheduled task;
                                     --serve adds a tailnet-only \`tailscale serve\` route
   stim-server service status [--label <name>] [--json]
   stim-server service update [--label <name>] --release <version>|--from <dir>
diff --git a/packages/server/src/service-manager.ts b/packages/server/src/service-manager.ts
index 9ccada557..7bcd9bd62 100644
--- a/packages/server/src/service-manager.ts
+++ b/packages/server/src/service-manager.ts
@@ -1,7 +1,9 @@
 import { execFile } from 'node:child_process';
-import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir, userInfo } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isJsonObject } from '@stim-cli/core/state';
 import {
   argumentsWithScript,
   parseInstalledPlist,
@@ -21,9 +23,12 @@ import {
   renderUnit,
   SHOW_PROPERTIES,
 } from './service-unit.ts';
+import type { SupervisorState } from './service-runner.ts';
+import { editTask, parseTask, renderTask, renderTaskXml } from './service-task.ts';
 import { installHostApp, type HostApp } from './stim-host.ts';
 
 const MANAGER_TIMEOUT_MS = 15_000;
+const SUPERVISOR_WAIT_MS = 30_000;
 
 export interface Run {
   ok: boolean;
@@ -36,12 +41,13 @@ export function run(
   args: string[],
   env: NodeJS.ProcessEnv = process.env,
   timeout: number = MANAGER_TIMEOUT_MS,
+  cwd?: string,
 ): Promise<Run> {
   return new Promise((resolve) => {
     execFile(
       file,
       args,
-      { env, timeout, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 },
+      { env, timeout, cwd, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 },
       (error, stdout, stderr) => resolve({ ok: !error, stdout, stderr: stderr || (error ? error.message : '') }),
     );
   });
@@ -58,8 +64,8 @@ type ServiceChange = { script: string; previousScript: string } | { serve: Serve
 
 /** What differs between running stim-server as a launchd LaunchAgent and as a systemd user unit. */
 export interface ServiceManager {
-  name: 'launchd' | 'systemd';
-  /** What the service is called in messages: "LaunchAgent" or "systemd user service". */
+  name: 'launchd' | 'systemd' | 'taskscheduler';
+  /** What the service is called in messages: "LaunchAgent", "systemd user service" or "scheduled task". */
   noun: string;
   file(label: string): string;
   logPath(label: string): string;
@@ -79,7 +85,7 @@ export interface ServiceManager {
   rewrite(installed: InstalledService, staged: string, change: ServiceChange): Promise<void>;
   /** The commands that start the service from its file by hand. */
   restartRemedy(label: string): string;
-  /** The launcher the server runs under, so macOS attributes its permissions to Stim Host; null on Linux. */
+  /** The launcher the server runs under, so macOS attributes its permissions to Stim Host; null elsewhere. */
   host(): Promise<HostApp | null>;
   /** How the service survives logout and reboot. */
   sessionNotes(): Promise<string[]>;
@@ -249,19 +255,169 @@ const systemd: ServiceManager = {
   runningLabel: (env) => labelFrom(env[LABEL_VARIABLE]),
 };
 
-/** Where `service update` keeps server versions and its outcome for `label`: the launchd layout off Linux. */
-export const serviceRoot = (label: string): string => (process.platform === 'linux' ? systemd : launchd).root(label);
+const localAppData = () => process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local');
+const taskName = (label: string) => `Stim\\${label}`;
+const supervisorState = (label: string) => join(taskScheduler.root(label), 'supervisor.json');
+
+/**
+ * The supervisor's state while the task runs. Task Scheduler runs one instance of the task, and that instance wrote
+ * the state file `start` cleared, so its pids are current.
+ */
+async function runningSupervisor(label: string): Promise<SupervisorState | null> {
+  const task = await run('powershell.exe', [
+    '-NoProfile',
+    '-NonInteractive',
+    '-Command',
+    `(Get-ScheduledTask -TaskPath '\\Stim\\' -TaskName '${label}' -ErrorAction SilentlyContinue).State`,
+  ]);
+  if (task.stdout.trim() !== 'Running') return null;
+  let value: unknown;
+  try {
+    value = JSON.parse(readFileSync(supervisorState(label), 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!isJsonObject(value) || typeof value.supervisor !== 'number' || !serverAlive(value.supervisor)) return null;
+  return {
+    supervisor: value.supervisor,
+    server: typeof value.server === 'number' ? value.server : null,
+    runs: typeof value.runs === 'number' ? value.runs : 0,
+    lastExitCode: typeof value.lastExitCode === 'string' ? value.lastExitCode : null,
+  };
+}
+
+function serverAlive(pid: number | null): pid is number {
+  if (pid === null) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error instanceof Error && 'code' in error && error.code === 'EPERM';
+  }
+}
+
+/**
+ * Starts `node args` so it outlives `stop`, which ends the supervisor's process tree with `taskkill /T`: the middle
+ * process exits at once, and `taskkill /T` follows only live parents. This one waits for that process to exit.
+ */
+const ORPHAN =
+  "const c=require('node:child_process').spawn(process.argv[1],process.argv.slice(2),{detached:true,stdio:['ignore',2,2],windowsHide:true});process.stdout.write(String(c.pid));c.unref();";
+const WAIT = `const r=require('node:child_process').spawnSync(process.execPath,['-e',${JSON.stringify(ORPHAN)},...process.argv.slice(1)],{stdio:['ignore','pipe','inherit'],windowsHide:true});const pid=Number(String(r.stdout));if(!pid)process.exit(1);const t=setInterval(()=>{try{process.kill(pid,0)}catch{clearInterval(t)}},1000);`;
+
+const taskScheduler: ServiceManager = {
+  name: 'taskscheduler',
+  noun: 'scheduled task',
+  file: (label) => join(localAppData(), 'Stim', 'services', `${label}.json`),
+  logPath: (label) => join(localAppData(), 'Stim', 'Logs', `${label}.log`),
+  root: (label) => join(localAppData(), 'Stim', 'services', label),
+  async read(label, path = taskScheduler.file(label)) {
+    if (!existsSync(path)) return null;
+    return parseTask(readFileSync(path, 'utf8'));
+  },
+  async job(label) {
+    const state = await runningSupervisor(label);
+    if (!state) return null;
+    return {
+      state: 'running',
+      pid: serverAlive(state.server) ? state.server : null,
+      runs: state.runs,
+      lastExitCode: state.lastExitCode,
+    };
+  },
+  render: renderTask,
+  async start(label) {
+    const installed = await taskScheduler.read(label);
+    const [node] = installed?.programArguments ?? [];
+    if (!node) return { ok: false, stdout: '', stderr: `${taskScheduler.file(label)} names no server.` };
+    const runner = join(taskScheduler.root(label), 'stim-service-runner.mjs');
+    mkdirSync(taskScheduler.root(label), { recursive: true });
+    copyFileSync(join(dirname(fileURLToPath(import.meta.url)), 'stim-service-runner.mjs'), runner);
+    const whoami = await run('whoami', []);
+    if (!whoami.ok) return whoami;
+    const user = whoami.stdout.trim();
+    const definition = `${taskScheduler.file(label)}.${process.pid}.xml`;
+    writeFileSync(
+      definition,
+      `\ufeff${renderTaskXml({
+        label,
+        user,
+        node,
+        runner,
+        file: taskScheduler.file(label),
+        state: supervisorState(label),
+        workingDirectory: homedir(),
+      })}`,
+      'utf16le',
+    );
+    rmSync(supervisorState(label), { force: true });
+    try {
+      const created = await run('schtasks', ['/Create', '/TN', taskName(label), '/XML', definition, '/F']);
+      if (!created.ok) return created;
+    } finally {
+      rmSync(definition, { force: true });
+    }
+    const started = await run('schtasks', ['/Run', '/TN', taskName(label)]);
+    if (!started.ok) return started;
+    const deadline = Date.now() + SUPERVISOR_WAIT_MS;
+    while (!(await runningSupervisor(label))) {
+      if (Date.now() >= deadline)
+        return {
+          ok: false,
+          stdout: '',
+          stderr: `${taskName(label)} did not start its supervisor within ${SUPERVISOR_WAIT_MS / 1000} s; see \`schtasks /Query /TN ${taskName(label)} /V /FO LIST\`.`,
+        };
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    return started;
+  },
+  async stop(label) {
+    const state = await runningSupervisor(label);
+    const killed = state ? await run('taskkill', ['/PID', String(state.supervisor), '/T', '/F']) : null;
+    const ended = await run('schtasks', ['/End', '/TN', taskName(label)]);
+    return killed ?? ended;
+  },
+  async remove(label) {
+    const deleted = await run('schtasks', ['/Delete', '/TN', taskName(label), '/F']);
+    if (!deleted.ok && (await run('schtasks', ['/Query', '/TN', taskName(label)])).ok)
+      throw new ServiceError(`schtasks /Delete ${taskName(label)} failed: ${deleted.stderr.trim()}`);
+    rmSync(taskScheduler.file(label), { force: true });
+  },
+  async rewrite(installed, staged, change) {
+    writeFileSync(
+      staged,
+      editTask(
+        readFileSync(staged, 'utf8'),
+        'serve' in change
+          ? change
+          : { programArguments: argumentsWithScript(installed, change.script), previousScript: change.previousScript },
+      ),
+    );
+  },
+  restartRemedy: (label) => `run \`schtasks /Run /TN ${taskName(label)}\``,
+  host: async () => null,
+  sessionNotes: async () => [
+    'The scheduled task starts stim-server when you log on to Windows and keeps it running after you sign out. After a reboot it starts at your next logon.',
+  ],
+  sessionProblem: async () => null,
+  linger: async () => null,
+  detached: (node, args) => ({ file: node, args: ['-e', WAIT, node, ...args] }),
+  runningLabel: (env) => labelFrom(env[LABEL_VARIABLE]),
+};
+
+/** Where `service update` keeps server versions and its outcome for `label`. */
+export const serviceRoot = (label: string): string =>
+  (process.platform === 'linux' ? systemd : process.platform === 'win32' ? taskScheduler : launchd).root(label);
 
 /** The service manager of this platform, or null where `stim-server service` does not run. */
 export function serviceManagerOrNull(platform: NodeJS.Platform = process.platform): ServiceManager | null {
-  return platform === 'darwin' ? launchd : platform === 'linux' ? systemd : null;
+  return platform === 'darwin' ? launchd : platform === 'linux' ? systemd : platform === 'win32' ? taskScheduler : null;
 }
 
 export function serviceManager(): ServiceManager {
   const manager = serviceManagerOrNull();
   if (!manager) {
     throw new ServiceError(
-      `stim-server service manages a launchd LaunchAgent on macOS or a systemd user service on Linux, and does not run on ${process.platform}. On this system, start stim-server from your own service manager.`,
+      `stim-server service manages a launchd LaunchAgent on macOS, a systemd user service on Linux or a scheduled task on Windows, and does not run on ${process.platform}. On this system, start stim-server from your own service manager.`,
     );
   }
   return manager;
diff --git a/packages/server/src/service-runner.ts b/packages/server/src/service-runner.ts
new file mode 100644
index 000000000..0d9635854
--- /dev/null
+++ b/packages/server/src/service-runner.ts
@@ -0,0 +1,83 @@
+import { spawn } from 'node:child_process';
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+/**
+ * The Windows supervisor of `stim-server service`. It imports nothing but Node, so `install` can copy this one file
+ * beside the service and it keeps working whatever server version the service runs.
+ */
+export interface SupervisorState {
+  supervisor: number;
+  server: number | null;
+  runs: number;
+  lastExitCode: string | null;
+}
+
+interface Program {
+  argv: string[];
+  environment: Record<string, string>;
+  workingDirectory: string;
+  logPath: string;
+}
+
+function program(file: string): Program {
+  const parsed: unknown = JSON.parse(readFileSync(file, 'utf8'));
+  const value: { [key: string]: unknown } = parsed && typeof parsed === 'object' ? { ...parsed } : {};
+  const argv = Array.isArray(value.programArguments)
+    ? value.programArguments.filter((entry): entry is string => typeof entry === 'string')
+    : [];
+  if (value.managed !== true || !argv.length || typeof value.logPath !== 'string')
+    throw new Error(`${file} is not a service file install wrote.`);
+  const environment: Record<string, string> = {};
+  if (value.environment && typeof value.environment === 'object') {
+    for (const [name, entry] of Object.entries(value.environment))
+      if (typeof entry === 'string') environment[name] = entry;
+  }
+  const workingDirectory = typeof value.workingDirectory === 'string' ? value.workingDirectory : '';
+  return { argv, environment, workingDirectory, logPath: value.logPath };
+}
+
+async function supervise(file: string, statePath: string, throttleMs: number): Promise<void> {
+  let runs = 0;
+  let lastExitCode: string | null = null;
+  const record = (server: number | null) => {
+    const state: SupervisorState = { supervisor: process.pid, server, runs, lastExitCode };
+    mkdirSync(dirname(statePath), { recursive: true });
+    const partial = `${statePath}.${process.pid}.tmp`;
+    writeFileSync(partial, `${JSON.stringify(state)}\n`);
+    renameSync(partial, statePath);
+  };
+  for (;;) {
+    const { argv, environment, workingDirectory, logPath } = program(file);
+    const [node = '', ...args] = argv;
+    mkdirSync(dirname(logPath), { recursive: true });
+    const out = openSync(logPath, 'a');
+    const child = spawn(node, args, {
+      cwd: workingDirectory || undefined,
+      env: { ...process.env, ...environment },
+      stdio: ['ignore', out, out],
+      windowsHide: true,
+    });
+    closeSync(out);
+    runs += 1;
+    record(child.pid ?? null);
+    lastExitCode = await new Promise<string>((resolve) => {
+      child.once('error', (error) => resolve(error.message));
+      child.once('exit', (code, signal) => resolve(code === null ? `signal ${signal}` : String(code)));
+    });
+    record(null);
+    await sleep(throttleMs);
+  }
+}
+
+const [file, statePath, throttle] = process.argv.slice(2);
+if (!file || !statePath || !/^\d+$/.test(throttle ?? '')) {
+  process.stderr.write('usage: stim-service-runner <service file> <state file> <restart delay seconds>\n');
+  process.exitCode = 2;
+} else {
+  supervise(file, statePath, Number(throttle) * 1000).catch((error: unknown) => {
+    process.stderr.write(`stim-service-runner: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}
diff --git a/packages/server/src/service-task.ts b/packages/server/src/service-task.ts
new file mode 100644
index 000000000..ff38e3051
--- /dev/null
+++ b/packages/server/src/service-task.ts
@@ -0,0 +1,149 @@
+import { isJsonObject } from '@stim-cli/core/state';
+import {
+  environmentValues,
+  installedService,
+  serverArguments,
+  THROTTLE_SECONDS,
+  type InstalledService,
+  type ServeRecord,
+  type ServiceSpec,
+} from './service-plist.ts';
+import { LABEL_VARIABLE } from './service-unit.ts';
+
+/**
+ * The service file `install` writes on Windows: what the supervisor starts, read again by the supervisor each time it
+ * starts the server. `managed` marks a file `install` wrote, so `install` and `uninstall` never touch another one.
+ */
+interface TaskFile {
+  label: string;
+  programArguments: string[];
+  environment: Record<string, string>;
+  workingDirectory: string;
+  logPath: string;
+  managed: boolean;
+  servePort?: number;
+  serveCreated?: boolean;
+  previousScript?: string;
+}
+
+export function renderTask(spec: ServiceSpec): string {
+  const environment: Record<string, string> = { ...spec.environment };
+  for (const [name, value] of environmentValues(spec.env)) environment[name] = value;
+  environment[LABEL_VARIABLE] = spec.label;
+  const file: TaskFile = {
+    label: spec.label,
+    programArguments: [spec.node, spec.script, ...serverArguments(spec)],
+    environment,
+    workingDirectory: spec.workingDirectory,
+    logPath: spec.logPath,
+    managed: true,
+    ...(spec.serve ? { servePort: spec.serve.port, serveCreated: spec.serve.created } : {}),
+  };
+  return `${JSON.stringify(file, null, 2)}\n`;
+}
+
+const strings = (list: unknown[]) => list.filter((entry): entry is string => typeof entry === 'string');
+
+/** The `TaskFile` in `text`, or null when it is not one `renderTask` wrote. */
+function readTaskFile(text: string): TaskFile | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isJsonObject(value) || typeof value.label !== 'string' || !Array.isArray(value.programArguments)) return null;
+  const environment: Record<string, string> = {};
+  if (isJsonObject(value.environment)) {
+    for (const [name, entry] of Object.entries(value.environment))
+      if (typeof entry === 'string') environment[name] = entry;
+  }
+  return {
+    label: value.label,
+    programArguments: strings(value.programArguments),
+    environment,
+    workingDirectory: typeof value.workingDirectory === 'string' ? value.workingDirectory : '',
+    logPath: typeof value.logPath === 'string' ? value.logPath : '',
+    managed: value.managed === true,
+    ...(typeof value.servePort === 'number' ? { servePort: value.servePort } : {}),
+    ...(value.serveCreated === true ? { serveCreated: true } : {}),
+    ...(typeof value.previousScript === 'string' ? { previousScript: value.previousScript } : {}),
+  };
+}
+
+export function parseTask(text: string): InstalledService | null {
+  const file = readTaskFile(text);
+  if (!file) return null;
+  return installedService({
+    label: file.label,
+    programArguments: file.programArguments,
+    environment: file.environment,
+    logPath: file.logPath || null,
+    managed: file.managed,
+    servePort: file.servePort ?? null,
+    serveCreated: file.serveCreated === true,
+    previousScript: file.previousScript ?? null,
+  });
+}
+
+/** `text` with the server arguments and previous script, or the serve record, replaced. */
+export function editTask(
+  text: string,
+  change: { programArguments: string[]; previousScript: string } | { serve: ServeRecord },
+): string {
+  const file = readTaskFile(text);
+  if (!file) throw new Error('The service file is not one install wrote.');
+  const edited: TaskFile =
+    'serve' in change
+      ? { ...file, servePort: change.serve.port, serveCreated: change.serve.created }
+      : { ...file, programArguments: change.programArguments, previousScript: change.previousScript };
+  return `${JSON.stringify(edited, null, 2)}\n`;
+}
+
+const xml = (text: string) => text.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+
+/** A command-line word as the Windows C runtime splits it: quoted, with backslashes before a quote doubled. */
+export function windowsArgument(value: string): string {
+  return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`;
+}
+
+/**
+ * The Task Scheduler definition that starts the supervisor `runner` with `node` at `user`'s logon. S4U runs it
+ * without an interactive session, and a user registers it without elevation. Task Scheduler's restart-on-failure
+ * reacts only to a task that fails to start, not to its process exiting, so the supervisor restarts the server.
+ */
+export function renderTaskXml(options: {
+  label: string;
+  user: string;
+  node: string;
+  runner: string;
+  file: string;
+  state: string;
+  workingDirectory: string;
+}): string {
+  const args = [options.runner, options.file, options.state, String(THROTTLE_SECONDS)].map(windowsArgument).join(' ');
+  return [
+    '<?xml version="1.0" encoding="UTF-16"?>',
+    '<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">',
+    `  <RegistrationInfo><Description>stim-server (${xml(options.label)})</Description></RegistrationInfo>`,
+    `  <Triggers><LogonTrigger><Enabled>true</Enabled><UserId>${xml(options.user)}</UserId></LogonTrigger></Triggers>`,
+    '  <Principals><Principal id="Author">',
+    `    <UserId>${xml(options.user)}</UserId><LogonType>S4U</LogonType><RunLevel>LeastPrivilege</RunLevel>`,
+    '  </Principal></Principals>',
+    '  <Settings>',
+    '    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>',
+    '    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>',
+    '    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>',
+    '    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>',
+    '    <RestartOnFailure><Interval>PT1M</Interval><Count>999</Count></RestartOnFailure>',
+    '    <Hidden>true</Hidden>',
+    '  </Settings>',
+    '  <Actions Context="Author"><Exec>',
+    `    <Command>${xml(options.node)}</Command>`,
+    `    <Arguments>${xml(args)}</Arguments>`,
+    `    <WorkingDirectory>${xml(options.workingDirectory)}</WorkingDirectory>`,
+    '  </Exec></Actions>',
+    '</Task>',
+    '',
+  ].join('\r\n');
+}
diff --git a/packages/server/src/service.ts b/packages/server/src/service.ts
index 8c68ab6d4..fea687d95 100644
--- a/packages/server/src/service.ts
+++ b/packages/server/src/service.ts
@@ -38,6 +38,7 @@ import {
   serviceRoot,
   type Run,
   type ServiceJob,
+  type ServiceManager,
 } from './service-manager.ts';
 import { hostPermissionPanes, requestHostPermissions, type HostApp } from './stim-host.ts';
 import { findTailscale, readTailscaleStatus, serveCommand, serveRoute } from '@stim-cli/transport-tailscale';
@@ -57,9 +58,14 @@ export interface ServiceOptions {
 
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
-const fileNoun = () => (serviceManager().name === 'launchd' ? 'plist' : 'unit');
-const startCommand = () =>
-  serviceManager().name === 'launchd' ? 'launchctl bootstrap' : 'systemctl --user enable and start';
+const FILE_NOUNS = { launchd: 'plist', systemd: 'unit', taskscheduler: 'service file' } as const;
+const START_COMMANDS = {
+  launchd: 'launchctl bootstrap',
+  systemd: 'systemctl --user enable and start',
+  taskscheduler: 'schtasks /Create and /Run',
+} as const;
+const fileNoun = () => FILE_NOUNS[serviceManager().name];
+const startCommand = () => START_COMMANDS[serviceManager().name];
 
 const plistPath = (label: string) => serviceManager().file(label);
 const logPath = (label: string) => serviceManager().logPath(label);
@@ -73,7 +79,7 @@ export function stableNode(pathEnv: string | undefined): string {
   for (const dir of (pathEnv ?? '').split(delimiter)) {
     if (!dir) continue;
     try {
-      const candidate = join(dir, 'node');
+      const candidate = join(dir, process.platform === 'win32' ? 'node.exe' : 'node');
       if (realpathSync(candidate) === real) return candidate;
     } catch {
       continue;
@@ -106,10 +112,24 @@ async function portFree(port: number): Promise<boolean> {
 }
 
 async function listenerPids(port: number): Promise<string[]> {
+  if (process.platform === 'win32') {
+    const listed = await run('netstat', ['-ano', '-p', 'TCP']);
+    return listed.ok ? netstatListeners(listed.stdout, port) : [];
+  }
   const listener = await run('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t']);
   return listener.ok ? listener.stdout.trim().split(/\s+/).filter(Boolean) : [];
 }
 
+/** The pids listening on TCP `port` in `netstat -ano -p TCP` output. */
+export function netstatListeners(output: string, port: number): string[] {
+  const pids = new Set<string>();
+  for (const line of output.split(/\r?\n/)) {
+    const [protocol, local, , state, pid] = line.trim().split(/\s+/);
+    if (protocol === 'TCP' && state === 'LISTENING' && pid && local?.endsWith(`:${port}`)) pids.add(pid);
+  }
+  return [...pids];
+}
+
 async function unload(label: string, port: number | null): Promise<void> {
   const job = await loaded(label);
   if (!job) return;
@@ -201,7 +221,7 @@ export async function requireManaged(label: string): Promise<InstalledService |
   const installed = await readInstalled(label);
   if (!installed && existsSync(plistPath(label))) {
     throw new ServiceError(
-      `${plistPath(label)} is not a ${serviceManager().name === 'launchd' ? 'plist' : 'unit'} that install wrote; not touching it. Use another --label.`,
+      `${plistPath(label)} is not a ${fileNoun()} that install wrote; not touching it. Use another --label.`,
     );
   }
   if (installed && !installed.managed) {
@@ -325,7 +345,8 @@ export async function installJob(
 
   const notes = [`Installed ${options.label}: ${path}`, `Log: ${spec.logPath}`];
   const follow = `Run \`stim-server service status --label ${options.label}\` and check ${spec.logPath}.`;
-  const noun = manager.name === 'launchd' ? 'LaunchAgent' : 'Service';
+  const noun =
+    manager.name === 'launchd' ? 'LaunchAgent' : manager.name === 'taskscheduler' ? 'Scheduled task' : 'Service';
   notes.push(
     !health
       ? `${noun} installed, but server readiness is unavailable on 127.0.0.1:${options.port}. ${follow}`
@@ -360,10 +381,25 @@ export async function installJob(
   } else {
     notes.push(`No tailnet route. Run \`${serveCommand(7443, options.port)}\` or install again with --serve.`);
   }
+  const shim = process.platform === 'win32' ? nodeShim(spec.node, spec.pathPrepend) : null;
+  if (shim) {
+    notes.push(
+      `The first node.exe on PATH, ${shim}, is not the Node that runs stim-server (${spec.node}). Builds start tools such as Expo's config loader with it, and a version manager's node.exe shim, such as pnpm's, breaks their Node IPC, so builds fail with fingerprint-mismatch. Install again with --path-prepend "${dirname(spec.node)}" to put the real Node first.`,
+    );
+  }
   notes.push(...(await manager.sessionNotes()));
   return notes;
 }
 
+/** The first `node.exe` the service's PATH finds, when it is not `node`; builds run their tools with that one. */
+function nodeShim(node: string, pathPrepend: string[]): string | null {
+  for (const dir of [...pathPrepend, ...(process.env.PATH ?? '').split(delimiter)]) {
+    const candidate = dir && join(dir, 'node.exe');
+    if (candidate && existsSync(candidate)) return sameFile(candidate, node) ? null : candidate;
+  }
+  return null;
+}
+
 export async function recordServiceRoute(label: string, port: number, record: ServeRecord): Promise<void> {
   await withUpdateClaim(label, async (installed) => {
     if (installed.port !== port)
@@ -390,7 +426,7 @@ export async function recordServiceRoute(label: string, port: number, record: Se
 export interface ServiceStatus {
   label: string;
   /** The service manager: launchd on macOS, systemd on Linux. */
-  manager: 'launchd' | 'systemd';
+  manager: ServiceManager['name'];
   installed: boolean;
   /** The service file: the LaunchAgent plist, or the systemd user unit. */
   plist: string;
@@ -573,7 +609,7 @@ export function statusLines(status: ServiceStatus, panes: { screen: string; cont
         : `  linger: off, so the service stops when you log out; run \`sudo loginctl enable-linger <user>\``,
     );
   }
-  lines.push(`  ${status.manager === 'launchd' ? 'plist' : 'unit'}: ${status.plist}`);
+  lines.push(`  ${FILE_NOUNS[status.manager]}: ${status.plist}`);
   return lines;
 }
 
@@ -719,12 +755,21 @@ function sameFile(a: string, b: string): boolean {
   }
 }
 
-function npmFor(node: string): { npm: string; env: NodeJS.ProcessEnv } {
+/**
+ * How to run npm for `node`. On Windows npm is a `.cmd` shim, which Node runs only through a shell, so this runs its
+ * `npm-cli.js` with `node` instead.
+ */
+function npmFor(node: string): { npm: string; prefix: string[]; env: NodeJS.ProcessEnv } {
   const path = [dirname(node), ...(process.env.PATH ?? '').split(delimiter)].filter(Boolean);
   const env = { ...process.env, PATH: path.join(delimiter) };
   for (const dir of path) {
+    if (process.platform === 'win32') {
+      const cli = join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js');
+      if (existsSync(cli)) return { npm: node, prefix: [cli], env };
+      continue;
+    }
     const npm = join(dir, 'npm');
-    if (existsSync(npm)) return { npm, env };
+    if (existsSync(npm)) return { npm, prefix: [], env };
   }
   throw new ServiceError(`No npm next to ${node} or on PATH. Install npm for that node, then run update again.`);
 }
@@ -750,7 +795,12 @@ async function localPackageSpecs(dir: string, names: string[]): Promise<Record<s
   const specs: Record<string, string> = {};
   for (const file of names) {
     const path = join(dir, file);
-    const manifest = await run('/usr/bin/tar', ['-xzOf', path, 'package/package.json'], process.env, 60_000);
+    const manifest = await run(
+      process.platform === 'win32' ? 'tar' : '/usr/bin/tar',
+      ['-xzOf', path, 'package/package.json'],
+      process.env,
+      60_000,
+    );
     let name: unknown;
     try {
       name = (JSON.parse(manifest.stdout) as { name?: unknown }).name;
@@ -781,7 +831,7 @@ export async function installServer(
   const staging = join(versions, `.install-${process.pid}`);
   mkdirSync(staging);
   try {
-    const { npm, env } = npmFor(node);
+    const { npm, prefix, env } = npmFor(node);
     const registry = [`--registry=${REGISTRY}`, `--@stim-cli:registry=${REGISTRY}`];
     let files: { name: string; sha256: string }[] = [];
     let specs: string[];
@@ -806,9 +856,13 @@ export async function installServer(
     log(
       `Installing ${'release' in source ? `${SERVER_PACKAGE}@${source.release} from ${REGISTRY}` : `${files.length} package file(s) from ${source.from}`}.`,
     );
+    // npm 10 on Windows fails to save the root package.json of a project that only lists `file:` packages
+    // (TypeError reading 'spec' in arborist's reify), and with a working directory outside the project it looks
+    // for a package.json there; nothing needs saving, and npm runs from the project.
     const installed = await run(
       npm,
       [
+        ...prefix,
         'install',
         '--prefix',
         staging,
@@ -816,19 +870,21 @@ export async function installServer(
         '--no-audit',
         '--no-fund',
         '--omit=dev',
-        '--save-exact',
+        ...(localPackages && process.platform === 'win32' ? ['--no-save'] : ['--save-exact']),
         ...registry,
         ...specs,
       ],
       env,
       NPM_TIMEOUT_MS,
+      staging,
     );
     if (!installed.ok) throw new ServiceError(`npm install failed:\n${lastLines(installed.stderr)}`);
     const audit = await run(
       npm,
-      ['audit', 'signatures', '--json', '--prefix', staging, ...registry],
+      [...prefix, 'audit', 'signatures', '--json', '--prefix', staging, ...registry],
       env,
       NPM_TIMEOUT_MS,
+      staging,
     );
     const problem = signatureProblem(audit.stdout, audit.stderr);
     if (problem) throw new ServiceError(`${problem}. Not switching to it.`);
diff --git a/packages/server/src/setup.ts b/packages/server/src/setup.ts
index beceaaf2d..9d3e8cd72 100644
--- a/packages/server/src/setup.ts
+++ b/packages/server/src/setup.ts
@@ -169,13 +169,13 @@ export function setupVersionDecision(
   return compareVersions(current.replace(/-.*/, ''), SETUP_MIN_VERSION) < 0 ? 'too-old' : 'reuse';
 }
 
-function tailscaleRefusal(install: TailscaleInstall, linux: boolean): string {
+function tailscaleRefusal(install: TailscaleInstall, platform: SetupDeps['platform']): string {
   if (install === 'none')
-    return linux
-      ? 'Install Tailscale on this machine and sign in to the same tailnet: https://tailscale.com/download/linux'
-      : 'Install Tailscale on this Mac and sign in to the same tailnet: https://tailscale.com/download/mac';
+    return platform === 'darwin'
+      ? 'Install Tailscale on this Mac and sign in to the same tailnet: https://tailscale.com/download/mac'
+      : `Install Tailscale on this machine and sign in to the same tailnet: https://tailscale.com/download/${platform === 'win32' ? 'windows' : 'linux'}`;
   if (install === 'app') return 'Turn on Tailscale from its menu bar icon on this Mac, then run this again.';
-  return `Run tailscale up on this ${linux ? 'machine' : 'Mac'}, then run this again.`;
+  return `Run tailscale up on this ${platform === 'darwin' ? 'Mac' : 'machine'}, then run this again.`;
 }
 
 export function setupExitCode(journal: SetupJournal): number {
@@ -205,8 +205,11 @@ interface SetupOutput {
 }
 
 export interface SetupDeps {
-  /** Where setup runs. On Linux it approves builds only, under a systemd user service, with no Stim Host. */
-  platform: 'darwin' | 'linux';
+  /**
+   * Where setup runs. On Linux and Windows it approves builds only, under a systemd user service or a scheduled task,
+   * with no Stim Host.
+   */
+  platform: 'darwin' | 'linux' | 'win32';
   display?: SetupDisplay;
   signal?: AbortSignal;
   now(): number;
@@ -309,8 +312,9 @@ export async function discardTypedAhead(stream: NodeJS.ReadableStream & { isTTY?
 
 export function defaultSetupDeps(): SetupDeps {
   const manager = serviceManagerOrNull();
+  const platform = manager?.name === 'systemd' ? 'linux' : manager?.name === 'taskscheduler' ? 'win32' : 'darwin';
   return {
-    platform: manager?.name === 'systemd' ? 'linux' : 'darwin',
+    platform,
     now: Date.now,
     sleep,
     tty: process.stdin.isTTY === true,
@@ -344,7 +348,7 @@ export function defaultSetupDeps(): SetupDeps {
       });
     },
     async preflight(options) {
-      if (!manager) throw new SetupRefusal('setup runs only on macOS and Linux.');
+      if (!manager) throw new SetupRefusal('setup runs only on macOS, Linux and Windows.');
       if (compareVersions(process.versions.node, '22.12.0') < 0)
         throw new SetupRefusal('setup needs Node 22.12 or later.');
       const status = await readRawTailscaleStatus(binary(), process.env);
@@ -354,7 +358,7 @@ export function defaultSetupDeps(): SetupDeps {
         typeof status.Self.DNSName !== 'string' ||
         !status.Self.DNSName
       ) {
-        throw new SetupRefusal(tailscaleRefusal(tailscaleInstall(process.env), manager.name === 'systemd'));
+        throw new SetupRefusal(tailscaleRefusal(tailscaleInstall(process.env), platform));
       }
       if (
         !isJsonObject(status.Peer) ||
@@ -519,7 +523,7 @@ async function checkPermissions(
 function toolChecks(
   tools: BuildToolchain,
   stimBuild: string | null,
-  linux: boolean,
+  platform: SetupDeps['platform'],
 ): [string, boolean, string, string][] {
   return [
     [
@@ -544,17 +548,21 @@ function toolChecks(
       'JDK',
       !!tools.jdk,
       tools.jdk ?? 'Missing JDK',
-      linux
+      platform === 'linux'
         ? 'Install JDK 17 (for example sudo apt install openjdk-17-jdk-headless) and rerun setup with --env JAVA_HOME=<jdk>'
-        : 'brew install --cask zulu@17',
+        : platform === 'win32'
+          ? 'Install JDK 17 (for example winget install EclipseAdoptium.Temurin.17.JDK) and rerun setup with --env JAVA_HOME=<jdk>'
+          : 'brew install --cask zulu@17',
     ],
     [
       'Android SDK',
       !!tools.androidSdk?.platforms.length && !!tools.androidSdk.buildTools.length && !!tools.androidSdk.ndk.length,
       tools.androidSdk ? JSON.stringify(tools.androidSdk) : 'Missing Android SDK',
-      linux
+      platform === 'linux'
         ? 'Install the Android SDK in ~/Android/Sdk, or rerun setup with --env ANDROID_HOME=<sdk>'
-        : 'Install Android Studio or set ANDROID_HOME',
+        : platform === 'win32'
+          ? 'Install the Android SDK in %LOCALAPPDATA%\\Android\\Sdk, or rerun setup with --env ANDROID_HOME=<sdk>'
+          : 'Install Android Studio or set ANDROID_HOME',
     ],
     [
       'Stim build',
@@ -570,22 +578,23 @@ function reportTools(
   opts: SetupOptions,
   output: SetupOutput,
   report: StepWriter,
-  linux: boolean,
+  platform: SetupDeps['platform'],
 ): void {
-  const checks = toolChecks(tools, output.server.stimBuild, linux);
+  const checks = toolChecks(tools, output.server.stimBuild, platform);
   for (const [tool, present, detail, fix] of checks) {
     const appleTool = tool === 'Xcode' || tool === 'iOS runtime' || tool === 'CocoaPods';
-    const needed = linux
-      ? !appleTool
-      : opts.capabilities.includes('build') || tool === 'Xcode' || tool === 'iOS runtime' || tool === 'Stim build';
+    const needed =
+      platform !== 'darwin'
+        ? !appleTool
+        : opts.capabilities.includes('build') || tool === 'Xcode' || tool === 'iOS runtime' || tool === 'Stim build';
     output.tools.push({ tool, state: !needed ? 'not-needed' : present ? 'present' : 'missing', detail, fix });
     report(
       `tools.${tool}`,
       present || !needed ? 'ok' : 'pending',
       tool,
       !needed
-        ? linux
-          ? 'Not needed on Linux, which builds Android only.'
+        ? platform !== 'darwin'
+          ? `Not needed on ${platform === 'win32' ? 'Windows' : 'Linux'}, which builds Android only.`
           : 'Not needed for hosted simulators.'
         : present
           ? detail
@@ -723,9 +732,10 @@ export async function runSetup(args: string[], version: string, deps: SetupDeps)
   const chatter = concise ? () => {} : log;
   const gaps: { subject: string; fix: string }[] = [];
   if (!json) printer.banner();
-  const linux = deps.platform === 'linux';
-  const here = linux ? 'this machine' : 'this Mac';
-  const serviceNoun = linux ? 'systemd user service' : 'LaunchAgent';
+  const androidOnly = deps.platform !== 'darwin';
+  const here = androidOnly ? 'this machine' : 'this Mac';
+  const serviceNoun =
+    deps.platform === 'linux' ? 'systemd user service' : deps.platform === 'win32' ? 'scheduled task' : 'LaunchAgent';
   const wait = <T>(work: Promise<T>) => interruptible(work, deps.signal);
   let release: (() => void) | undefined;
   let active = 'args';
@@ -761,8 +771,10 @@ export async function runSetup(args: string[], version: string, deps: SetupDeps)
   try {
     options = parseSetupArgs(args, deps.now());
     Object.assign(output, { label: options.label, port: options.port });
-    if (linux && options.capabilities.includes('device-host'))
-      throw new SetupRefusal('Hosting simulators needs a Mac. On Linux, run setup with --build only.');
+    if (androidOnly && options.capabilities.includes('device-host'))
+      throw new SetupRefusal(
+        `Hosting simulators needs a Mac. On ${deps.platform === 'win32' ? 'Windows' : 'Linux'}, run setup with --build only.`,
+      );
     if (options.capabilities.includes('device-host'))
       output.permissions = { screenRecording: 'denied', deviceControl: 'denied' };
     journal = {
@@ -845,7 +857,7 @@ export async function runSetup(args: string[], version: string, deps: SetupDeps)
           text: serverText(desktop, decision, output.server.version),
         },
       );
-      if (!linux) {
+      if (!androidOnly) {
         step('host', 'running', 'Stim Host', undefined, undefined, { running: 'Installing Stim Host' });
         const installedHost = await wait(deps.installHost());
         host = installedHost;
@@ -993,7 +1005,7 @@ export async function runSetup(args: string[], version: string, deps: SetupDeps)
       step('tools', 'running', 'Tools', undefined, undefined, { running: 'Checking build tools' });
       const tools = await wait(deps.toolchain(opts));
       if (!tools) throw new SetupRefusal('Could not read the local build toolchain.');
-      reportTools(tools, opts, output, step, linux);
+      reportTools(tools, opts, output, step, deps.platform);
       step('tools', 'ok', 'Tools', 'Checked; installs nothing.', undefined, {
         text: 'build tools ready',
         hidden: output.tools.some((t) => t.state === 'missing'),
diff --git a/packages/server/tsdown.config.mts b/packages/server/tsdown.config.mts
index 70f722719..3eabea866 100644
--- a/packages/server/tsdown.config.mts
+++ b/packages/server/tsdown.config.mts
@@ -10,6 +10,7 @@ if (!nodeFloor) throw new Error(`engines.node must have the form >=X.Y.Z, got ${
 export default defineConfig({
   entry: {
     'stim-server': 'bin/node-check.ts',
+    'stim-service-runner': 'src/service-runner.ts',
     protocol: 'src/protocol.ts',
   },
   format: 'esm',

From 3f50a21e107ec388908c8eb7726e4d77ae159479 Mon Sep 17 00:00:00 2001
From: Janic Duplessis <janicduplessis@gmail.com>
Date: Tue, 13 Oct 2026 04:03:10 -0400
Subject: [PATCH 3/4] fix: harden the Windows service task and supervisor

---
 packages/server/README.md                     |  5 +-
 .../server/__tests__/service-task.test.ts     | 10 ++--
 packages/server/src/service-manager.ts        | 25 +++++----
 packages/server/src/service-runner.ts         | 53 ++++++++++++-------
 packages/server/src/service-task.ts           |  8 +--
 packages/server/src/service.ts                | 20 ++++---
 website/docs/remote-machines.md               |  2 +-
 7 files changed, 79 insertions(+), 44 deletions(-)

diff --git a/packages/server/README.md b/packages/server/README.md
index ed2171ba6..5aa5eee52 100644
--- a/packages/server/README.md
+++ b/packages/server/README.md
@@ -1248,7 +1248,10 @@ grants.
   its process exits, so the task runs the supervisor, which restarts the
   server 30 seconds after it exits and reads the service file again each time.
   The supervisor records its pid, the server's, the number of runs and the last
-  exit code in `supervisor.json`, which `status` reports.
+  exit code in `supervisor.json`, which `status` reports, and its own errors,
+  such as an unreadable service file, in `supervisor.log` beside it. The task
+  runs at normal priority, so builds are not slowed by Task Scheduler's
+  below-normal default.
 - Stopping the service ends the supervisor's process tree with
   `taskkill /T /F`; a remote update the server starts runs detached from that
   tree, so restarting the service does not stop it.
diff --git a/packages/server/__tests__/service-task.test.ts b/packages/server/__tests__/service-task.test.ts
index c38212de8..d7df8d2cb 100644
--- a/packages/server/__tests__/service-task.test.ts
+++ b/packages/server/__tests__/service-task.test.ts
@@ -67,15 +67,16 @@ describe('Windows scheduled task', () => {
   it('runs the supervisor at the user logon without elevation, with XML-escaped paths', () => {
     const xml = renderTaskXml({
       label: 'dev.stim.server',
-      user: 'HOST\\me',
+      user: 'S-1-5-21-1-2-3-1001',
       node: 'C:\\R&D\\node.exe',
       runner: 'C:\\Users\\me\\AppData\\Local\\Stim\\services\\dev.stim.server\\stim-service-runner.mjs',
       file: 'C:\\Users\\me\\AppData\\Local\\Stim\\services\\dev.stim.server.json',
       state: 'C:\\Users\\me\\AppData\\Local\\Stim\\services\\dev.stim.server\\supervisor.json',
       workingDirectory: 'C:\\Users\\me',
     });
-    expect(xml).toContain('<LogonTrigger><Enabled>true</Enabled><UserId>HOST\\me</UserId></LogonTrigger>');
+    expect(xml).toContain('<LogonTrigger><Enabled>true</Enabled><UserId>S-1-5-21-1-2-3-1001</UserId></LogonTrigger>');
     expect(xml).toContain('<LogonType>S4U</LogonType><RunLevel>LeastPrivilege</RunLevel>');
+    expect(xml).toContain('<Priority>4</Priority>');
     expect(xml).toContain('<Command>C:\\R&#38;D\\node.exe</Command>');
     expect(xml).toMatch(
       /<Arguments>&#34;C:\\Users.*stim-service-runner\.mjs&#34; .*supervisor\.json&#34; &#34;30&#34;<\/Arguments>/,
@@ -83,7 +84,7 @@ describe('Windows scheduled task', () => {
   });
 });
 
-test('netstat listeners are the pids listening on exactly that port', () => {
+test('netstat listeners are the pids listening on exactly that port, whatever the locale calls the state', () => {
   const output = [
     '',
     'Active Connections',
@@ -94,7 +95,8 @@ test('netstat listeners are the pids listening on exactly that port', () => {
     '  TCP    127.0.0.1:7787         127.0.0.1:50000        ESTABLISHED     4242',
     '  TCP    100.100.38.114:7787    0.0.0.0:0              LISTENING       4242',
     '  TCP    127.0.0.1:17787        0.0.0.0:0              LISTENING       99',
-    '  TCP    [::]:7787              [::]:0                 LISTENING       4243',
+    '  TCP    [::]:7787              [::]:0                 ABH\u00d6REN         4243',
+    '  UDP    0.0.0.0:7787           *:*                                    77',
   ].join('\r\n');
   expect(netstatListeners(output, 7787)).toEqual(['4242', '4243']);
 });
diff --git a/packages/server/src/service-manager.ts b/packages/server/src/service-manager.ts
index 7bcd9bd62..7c3818b79 100644
--- a/packages/server/src/service-manager.ts
+++ b/packages/server/src/service-manager.ts
@@ -1,5 +1,5 @@
 import { execFile } from 'node:child_process';
-import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir, userInfo } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -29,6 +29,9 @@ import { installHostApp, type HostApp } from './stim-host.ts';
 
 const MANAGER_TIMEOUT_MS = 15_000;
 const SUPERVISOR_WAIT_MS = 30_000;
+const TASK_STATE_RUNNING = 4;
+/** Task Scheduler records `LastRunTime` to the second. */
+const TASK_CLOCK_SLACK_MS = 2000;
 
 export interface Run {
   ok: boolean;
@@ -260,19 +263,22 @@ const taskName = (label: string) => `Stim\\${label}`;
 const supervisorState = (label: string) => join(taskScheduler.root(label), 'supervisor.json');
 
 /**
- * The supervisor's state while the task runs. Task Scheduler runs one instance of the task, and that instance wrote
- * the state file `start` cleared, so its pids are current.
+ * The supervisor's state while the task runs: Task Scheduler runs one instance of the task, and only a state file
+ * written since that instance started describes it. This reads the task through the Task Scheduler COM API, whose
+ * state numbers, unlike the text `schtasks` prints, are not localized.
  */
 async function runningSupervisor(label: string): Promise<SupervisorState | null> {
   const task = await run('powershell.exe', [
     '-NoProfile',
     '-NonInteractive',
     '-Command',
-    `(Get-ScheduledTask -TaskPath '\\Stim\\' -TaskName '${label}' -ErrorAction SilentlyContinue).State`,
+    `$s = New-Object -ComObject Schedule.Service; $s.Connect(); $t = $s.GetFolder('\\Stim').GetTask('${label}'); "$($t.State) $(([DateTimeOffset]$t.LastRunTime).ToUnixTimeMilliseconds())"`,
   ]);
-  if (task.stdout.trim() !== 'Running') return null;
+  const [state, lastRun] = task.stdout.trim().split(' ').map(Number);
+  if (state !== TASK_STATE_RUNNING || lastRun === undefined || !Number.isFinite(lastRun)) return null;
   let value: unknown;
   try {
+    if (statSync(supervisorState(label)).mtimeMs < lastRun - TASK_CLOCK_SLACK_MS) return null;
     value = JSON.parse(readFileSync(supervisorState(label), 'utf8'));
   } catch {
     return null;
@@ -332,9 +338,10 @@ const taskScheduler: ServiceManager = {
     const runner = join(taskScheduler.root(label), 'stim-service-runner.mjs');
     mkdirSync(taskScheduler.root(label), { recursive: true });
     copyFileSync(join(dirname(fileURLToPath(import.meta.url)), 'stim-service-runner.mjs'), runner);
-    const whoami = await run('whoami', []);
-    if (!whoami.ok) return whoami;
-    const user = whoami.stdout.trim();
+    const whoami = await run('whoami', ['/user', '/fo', 'csv', '/nh']);
+    const user = /"(S-1-[\d-]+)"\s*$/.exec(whoami.stdout.trim())?.[1];
+    if (!user)
+      return { ok: false, stdout: '', stderr: `whoami /user did not print this user's SID: ${whoami.stderr.trim()}` };
     const definition = `${taskScheduler.file(label)}.${process.pid}.xml`;
     writeFileSync(
       definition,
@@ -364,7 +371,7 @@ const taskScheduler: ServiceManager = {
         return {
           ok: false,
           stdout: '',
-          stderr: `${taskName(label)} did not start its supervisor within ${SUPERVISOR_WAIT_MS / 1000} s; see \`schtasks /Query /TN ${taskName(label)} /V /FO LIST\`.`,
+          stderr: `${taskName(label)} did not start its supervisor within ${SUPERVISOR_WAIT_MS / 1000} s; see ${join(taskScheduler.root(label), 'supervisor.log')} and \`schtasks /Query /TN ${taskName(label)} /V /FO LIST\`.`,
         };
       await new Promise((resolve) => setTimeout(resolve, 250));
     }
diff --git a/packages/server/src/service-runner.ts b/packages/server/src/service-runner.ts
index 0d9635854..b502863e5 100644
--- a/packages/server/src/service-runner.ts
+++ b/packages/server/src/service-runner.ts
@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
-import { closeSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 
 /**
@@ -48,29 +48,44 @@ async function supervise(file: string, statePath: string, throttleMs: number): P
     writeFileSync(partial, `${JSON.stringify(state)}\n`);
     renameSync(partial, statePath);
   };
+  record(null);
   for (;;) {
-    const { argv, environment, workingDirectory, logPath } = program(file);
-    const [node = '', ...args] = argv;
-    mkdirSync(dirname(logPath), { recursive: true });
-    const out = openSync(logPath, 'a');
-    const child = spawn(node, args, {
-      cwd: workingDirectory || undefined,
-      env: { ...process.env, ...environment },
-      stdio: ['ignore', out, out],
-      windowsHide: true,
-    });
-    closeSync(out);
-    runs += 1;
-    record(child.pid ?? null);
-    lastExitCode = await new Promise<string>((resolve) => {
-      child.once('error', (error) => resolve(error.message));
-      child.once('exit', (code, signal) => resolve(code === null ? `signal ${signal}` : String(code)));
-    });
+    try {
+      lastExitCode = await runOnce(file, (server) => {
+        runs += 1;
+        record(server);
+      });
+    } catch (error) {
+      lastExitCode = `supervisor: ${error instanceof Error ? error.message : String(error)}`;
+      try {
+        appendFileSync(join(dirname(statePath), 'supervisor.log'), `${new Date().toISOString()} ${lastExitCode}\n`);
+      } catch {}
+    }
     record(null);
     await sleep(throttleMs);
   }
 }
 
+/** Starts the server once from the service file and resolves with how it ended. */
+async function runOnce(file: string, started: (server: number | null) => void): Promise<string> {
+  const { argv, environment, workingDirectory, logPath } = program(file);
+  const [node = '', ...args] = argv;
+  mkdirSync(dirname(logPath), { recursive: true });
+  const out = openSync(logPath, 'a');
+  const child = spawn(node, args, {
+    cwd: workingDirectory || undefined,
+    env: { ...process.env, ...environment },
+    stdio: ['ignore', out, out],
+    windowsHide: true,
+  });
+  closeSync(out);
+  started(child.pid ?? null);
+  return new Promise<string>((resolve) => {
+    child.once('error', (error) => resolve(error.message));
+    child.once('exit', (code, signal) => resolve(code === null ? `signal ${signal}` : String(code)));
+  });
+}
+
 const [file, statePath, throttle] = process.argv.slice(2);
 if (!file || !statePath || !/^\d+$/.test(throttle ?? '')) {
   process.stderr.write('usage: stim-service-runner <service file> <state file> <restart delay seconds>\n');
diff --git a/packages/server/src/service-task.ts b/packages/server/src/service-task.ts
index ff38e3051..8b49019ae 100644
--- a/packages/server/src/service-task.ts
+++ b/packages/server/src/service-task.ts
@@ -108,9 +108,10 @@ export function windowsArgument(value: string): string {
 }
 
 /**
- * The Task Scheduler definition that starts the supervisor `runner` with `node` at `user`'s logon. S4U runs it
- * without an interactive session, and a user registers it without elevation. Task Scheduler's restart-on-failure
- * reacts only to a task that fails to start, not to its process exiting, so the supervisor restarts the server.
+ * The Task Scheduler definition that starts the supervisor `runner` with `node` at the logon of `user`, a SID. S4U
+ * runs it without an interactive session, and a user registers it without elevation. Task Scheduler's
+ * restart-on-failure reacts only to a task that fails to start, not to its process exiting, so the supervisor
+ * restarts the server. Without `Priority` a task runs at 7, below normal CPU, I/O and memory priority; 4 is normal.
  */
 export function renderTaskXml(options: {
   label: string;
@@ -135,6 +136,7 @@ export function renderTaskXml(options: {
     '    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>',
     '    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>',
     '    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>',
+    '    <Priority>4</Priority>',
     '    <RestartOnFailure><Interval>PT1M</Interval><Count>999</Count></RestartOnFailure>',
     '    <Hidden>true</Hidden>',
     '  </Settings>',
diff --git a/packages/server/src/service.ts b/packages/server/src/service.ts
index fea687d95..12e34492f 100644
--- a/packages/server/src/service.ts
+++ b/packages/server/src/service.ts
@@ -113,19 +113,23 @@ async function portFree(port: number): Promise<boolean> {
 
 async function listenerPids(port: number): Promise<string[]> {
   if (process.platform === 'win32') {
-    const listed = await run('netstat', ['-ano', '-p', 'TCP']);
+    const listed = await run('netstat', ['-ano']);
     return listed.ok ? netstatListeners(listed.stdout, port) : [];
   }
   const listener = await run('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t']);
   return listener.ok ? listener.stdout.trim().split(/\s+/).filter(Boolean) : [];
 }
 
-/** The pids listening on TCP `port` in `netstat -ano -p TCP` output. */
+/**
+ * The pids listening on TCP `port` in `netstat -ano` output. netstat localizes the state column, so a listener is a
+ * TCP row with no foreign address.
+ */
 export function netstatListeners(output: string, port: number): string[] {
   const pids = new Set<string>();
   for (const line of output.split(/\r?\n/)) {
-    const [protocol, local, , state, pid] = line.trim().split(/\s+/);
-    if (protocol === 'TCP' && state === 'LISTENING' && pid && local?.endsWith(`:${port}`)) pids.add(pid);
+    const [protocol, local, foreign, , pid] = line.trim().split(/\s+/);
+    if (protocol === 'TCP' && (foreign === '0.0.0.0:0' || foreign === '[::]:0') && pid && local?.endsWith(`:${port}`))
+      pids.add(pid);
   }
   return [...pids];
 }
@@ -796,7 +800,9 @@ async function localPackageSpecs(dir: string, names: string[]): Promise<Record<s
   for (const file of names) {
     const path = join(dir, file);
     const manifest = await run(
-      process.platform === 'win32' ? 'tar' : '/usr/bin/tar',
+      process.platform === 'win32'
+        ? join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'tar.exe')
+        : '/usr/bin/tar',
       ['-xzOf', path, 'package/package.json'],
       process.env,
       60_000,
@@ -876,7 +882,7 @@ export async function installServer(
       ],
       env,
       NPM_TIMEOUT_MS,
-      staging,
+      process.platform === 'win32' ? staging : undefined,
     );
     if (!installed.ok) throw new ServiceError(`npm install failed:\n${lastLines(installed.stderr)}`);
     const audit = await run(
@@ -884,7 +890,7 @@ export async function installServer(
       [...prefix, 'audit', 'signatures', '--json', '--prefix', staging, ...registry],
       env,
       NPM_TIMEOUT_MS,
-      staging,
+      process.platform === 'win32' ? staging : undefined,
     );
     const problem = signatureProblem(audit.stdout, audit.stderr);
     if (problem) throw new ServiceError(`${problem}. Not switching to it.`);
diff --git a/website/docs/remote-machines.md b/website/docs/remote-machines.md
index bc3c8f466..d692bf780 100644
--- a/website/docs/remote-machines.md
+++ b/website/docs/remote-machines.md
@@ -581,7 +581,7 @@ the Windows machine:
 
    The task starts at your logon and keeps running after you sign out; the
    log is `%LOCALAPPDATA%\Stim\Logs\dev.stim.server.log`. `service update`
-   and `service rollback` work as on a Mac, and an approved client can update
+   and `service rollback` work as on macOS and Linux, and an approved client can update
    the server remotely.
    `--path-prepend` puts the real Node first on the server's `PATH`. A version
    manager's `node.exe` shim, such as pnpm's, breaks the Node IPC that Expo's

From 7ac4cb5e92ca33a5c4bead306bf6e44452ccb399 Mon Sep 17 00:00:00 2001
From: Janic Duplessis <janicduplessis@gmail.com>
Date: Tue, 13 Oct 2026 04:15:24 -0400
Subject: [PATCH 4/4] fix: trust the Windows supervisor by its Task Scheduler
 process id

---
 packages/server/src/service-manager.ts | 19 +++++++------------
 packages/server/src/service-runner.ts  | 21 ++++++++++++++-------
 2 files changed, 21 insertions(+), 19 deletions(-)

diff --git a/packages/server/src/service-manager.ts b/packages/server/src/service-manager.ts
index 7c3818b79..943e5377b 100644
--- a/packages/server/src/service-manager.ts
+++ b/packages/server/src/service-manager.ts
@@ -1,5 +1,5 @@
 import { execFile } from 'node:child_process';
-import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir, userInfo } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -29,9 +29,6 @@ import { installHostApp, type HostApp } from './stim-host.ts';
 
 const MANAGER_TIMEOUT_MS = 15_000;
 const SUPERVISOR_WAIT_MS = 30_000;
-const TASK_STATE_RUNNING = 4;
-/** Task Scheduler records `LastRunTime` to the second. */
-const TASK_CLOCK_SLACK_MS = 2000;
 
 export interface Run {
   ok: boolean;
@@ -263,27 +260,25 @@ const taskName = (label: string) => `Stim\\${label}`;
 const supervisorState = (label: string) => join(taskScheduler.root(label), 'supervisor.json');
 
 /**
- * The supervisor's state while the task runs: Task Scheduler runs one instance of the task, and only a state file
- * written since that instance started describes it. This reads the task through the Task Scheduler COM API, whose
- * state numbers, unlike the text `schtasks` prints, are not localized.
+ * The supervisor's state while the task runs: the state file counts only when the pid it names is the process
+ * Task Scheduler started for the task's running instance (its `EnginePID`), read through the Task Scheduler COM API.
+ * `GetInstances(1)` includes hidden tasks.
  */
 async function runningSupervisor(label: string): Promise<SupervisorState | null> {
   const task = await run('powershell.exe', [
     '-NoProfile',
     '-NonInteractive',
     '-Command',
-    `$s = New-Object -ComObject Schedule.Service; $s.Connect(); $t = $s.GetFolder('\\Stim').GetTask('${label}'); "$($t.State) $(([DateTimeOffset]$t.LastRunTime).ToUnixTimeMilliseconds())"`,
+    `$s = New-Object -ComObject Schedule.Service; $s.Connect(); foreach ($i in $s.GetFolder('\\Stim').GetTask('${label}').GetInstances(1)) { $i.EnginePID }`,
   ]);
-  const [state, lastRun] = task.stdout.trim().split(' ').map(Number);
-  if (state !== TASK_STATE_RUNNING || lastRun === undefined || !Number.isFinite(lastRun)) return null;
+  const running = new Set(task.stdout.split(/\s+/).filter(Boolean).map(Number));
   let value: unknown;
   try {
-    if (statSync(supervisorState(label)).mtimeMs < lastRun - TASK_CLOCK_SLACK_MS) return null;
     value = JSON.parse(readFileSync(supervisorState(label), 'utf8'));
   } catch {
     return null;
   }
-  if (!isJsonObject(value) || typeof value.supervisor !== 'number' || !serverAlive(value.supervisor)) return null;
+  if (!isJsonObject(value) || typeof value.supervisor !== 'number' || !running.has(value.supervisor)) return null;
   return {
     supervisor: value.supervisor,
     server: typeof value.server === 'number' ? value.server : null,
diff --git a/packages/server/src/service-runner.ts b/packages/server/src/service-runner.ts
index b502863e5..a890797cf 100644
--- a/packages/server/src/service-runner.ts
+++ b/packages/server/src/service-runner.ts
@@ -41,12 +41,21 @@ function program(file: string): Program {
 async function supervise(file: string, statePath: string, throttleMs: number): Promise<void> {
   let runs = 0;
   let lastExitCode: string | null = null;
+  const log = (line: string) => {
+    try {
+      appendFileSync(join(dirname(statePath), 'supervisor.log'), `${new Date().toISOString()} ${line}\n`);
+    } catch {}
+  };
   const record = (server: number | null) => {
     const state: SupervisorState = { supervisor: process.pid, server, runs, lastExitCode };
-    mkdirSync(dirname(statePath), { recursive: true });
-    const partial = `${statePath}.${process.pid}.tmp`;
-    writeFileSync(partial, `${JSON.stringify(state)}\n`);
-    renameSync(partial, statePath);
+    try {
+      mkdirSync(dirname(statePath), { recursive: true });
+      const partial = `${statePath}.${process.pid}.tmp`;
+      writeFileSync(partial, `${JSON.stringify(state)}\n`);
+      renameSync(partial, statePath);
+    } catch (error) {
+      log(`could not record ${statePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
   };
   record(null);
   for (;;) {
@@ -57,9 +66,7 @@ async function supervise(file: string, statePath: string, throttleMs: number): P
       });
     } catch (error) {
       lastExitCode = `supervisor: ${error instanceof Error ? error.message : String(error)}`;
-      try {
-        appendFileSync(join(dirname(statePath), 'supervisor.log'), `${new Date().toISOString()} ${lastExitCode}\n`);
-      } catch {}
+      log(lastExitCode);
     }
     record(null);
     await sleep(throttleMs);