Add Linux systemd and Windows Scheduled Task supervisors so self-update works on all three platforms

Author: KenKaiii

CLAUDE.md

@@ -69,5 +69,7 @@ Mobile remote control for **desktop coding agents** (Claude Code, Codex, Gemini
 - **The EAS iOS build image is pinned** (`eas.json`) — Xcode 26.0 desyncs `react-native-keyboard-controller`'s per-frame numbers, since UIKit gates on the SDK built against. Never `auto`/`latest`; if the keyboard is off again, suspect this line first.
 - **Shipping an `.ipa` is `packages/app/scripts/build-ipa.sh`** — `eas build --local` runs the same pipeline on this Mac in ~3 min and costs no build credits, where the cloud build is metered and queues. It leaves one `pew2-build<N>.ipa` on the Desktop for Transporter, deletes the previous one *after* a successful build, and refuses to hand over anything signed `get-task-allow=true` (a development profile uploads fine, then gets rejected by email hours later). Still needs an Expo login even offline of the cloud builder: `appVersionSource: remote` means the build number is incremented server-side, so an anonymous run dies after installing pods. `release-to-device.sh` is the other half — dev-signed, for reproducing Release behaviour on a plugged-in phone, never uploadable.
 - **No Expo account is committed** (`app.config.js`) — identity layers in from `EAS_OWNER`/`EAS_PROJECT_ID` or a gitignored `eas-project.json`, so push degrades to local-only banners on a fresh clone instead of breaking.
+- **Self-update is a swap plus an exit, and the exit is the dangerous half** (`update/`). `check.ts` reads the latest release tag, `apply.ts` downloads it, verifies the published `.sha256` and *renames* it over `process.execPath`, `scheduler.ts` exits so a supervisor relaunches on the new inode. Three rules: the staging file is written **beside the target** (rename is only atomic within one filesystem, and `os.tmpdir()` is routinely another volume); it exits **only when `daemon.busyReason()` is undefined** (never mid-turn, never with a permission on screen); and it refuses unless `isCompiled()` — under `bun run`, `process.execPath` is the developer's **`bun`** binary, and a rename would replace the runtime every other project on that machine depends on.
+- **A supervisor is what makes exit-to-update legal, and it is per-machine, not per-platform** (`cli/service*.ts`). All three have one — launchd `KeepAlive`, systemd `Restart=always`, and a Scheduled Task whose repeating trigger plus `IgnoreNew` policy is the same thing at one-minute granularity. Each must restart after a **clean** exit: `Restart=on-failure` and Task Scheduler's `RestartOnFailure` both ignore exit 0, which is exactly how the updater ends the daemon, so either would swap the binary and never come back. The gate is `supervisorInstalled()` — the service *file on disk*, not `process.platform`, because `pew2 serve` is a first-class command and a fresh install has no service until `pew2 setup` writes one. Windows additionally cannot unlink or replace a running `.exe`, only rename it, so the outgoing binary is parked aside and restored if the swap then fails. systemd needs `loginctl enable-linger` or the daemon dies at logout.
 - **`pew2 setup --json` / `doctor --json` are the agent-facing surface** — `ok` is the stop condition, each problem carries a stable `id` and runnable `fix`, and missing secrets or LAN-only are `warning`, never `error`, so an agent can't loop on what it can't supply.
 <!-- gg:init:end -->

packages/daemon/src/cli/service-schtasks.ts

@@ -0,0 +1,244 @@
+/**
+ * Keeping the daemon alive on Windows, via a Scheduled Task.
+ *
+ * Windows has a real service manager, and it is the wrong tool here: a true
+ * service needs Administrator to register, runs in session 0, and would spawn
+ * every coding agent outside the user's desktop session and away from their
+ * environment. Task Scheduler registers per-user with no elevation, which is
+ * what an install script run from an ordinary shell can actually do.
+ *
+ * ## How a task becomes a keepalive
+ *
+ * Task Scheduler has no `KeepAlive`. `RestartOnFailure` is not it either: that
+ * fires when an action *fails*, and the self-updater ends the daemon with exit
+ * 0, which is a success. Under that setting an update would swap the binary,
+ * exit cleanly, and never come back.
+ *
+ * So the restart is built from two settings that do apply, and the combination
+ * is the whole trick:
+ *
+ * - a **logon trigger with a repetition** of one minute, so Windows attempts to
+ *   start the task continuously, for ever; and
+ * - **`MultipleInstancesPolicy: IgnoreNew`**, which does not start a new
+ *   instance while one is already running.
+ *
+ * Together they mean: while the daemon is up, every attempt is ignored; the
+ * moment it exits, the next attempt starts it. That is a poll rather than a
+ * supervisor, so the worst-case gap is the repetition interval — a minute,
+ * against launchd's ten-second throttle. Acceptable for an update restart, and
+ * the reason `update/scheduler.ts` only ever exits when the daemon is idle.
+ *
+ * `ExecutionTimeLimit: PT0S` disables the three-day default kill, which would
+ * otherwise terminate a long-lived daemon on a schedule.
+ */
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { logDir } from "../logs.js";
+import {
+  LABEL,
+  programArguments,
+  type CommandResult,
+  type InstallOptions,
+  type ServiceStatus,
+} from "./service-shared.js";
+
+/** Task Scheduler's own name for the job. */
+export const TASK_NAME = LABEL;
+
+/**
+ * Where the generated task XML is kept.
+ *
+ * Written to a stable path because it is also the marker `supervisorInstalled()`
+ * reads: it is the one artefact of a Windows install that exists as a file. The
+ * same caveat applies as to the launchd plist — someone can delete the task and
+ * leave the file — but the file is never written unless an install ran, which is
+ * the question being asked.
+ */
+export function taskXmlPath(home = homedir()): string {
+  return join(home, ".pew2", "service", `${TASK_NAME}.xml`);
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Quote one argument of a Windows command line.
+ *
+ * Task Scheduler hands `Arguments` to the process as a single string, which is
+ * split by the same rules as any other command line, so a path containing a
+ * space has to be quoted or it arrives as two arguments.
+ */
+function quoteArgument(value: string): string {
+  return /[\s"]/.test(value) ? `"${value.replace(/"/g, '\\"')}"` : value;
+}
+
+export function buildTaskXml(options: InstallOptions = {}): string {
+  const program = programArguments(options.bunPath);
+  const logs = logDir(options.env);
+  const port = options.port ?? Number(options.env?.PEW2_PORT ?? 8787);
+
+  // A task carries no environment of its own, and unlike launchd and systemd
+  // there is no per-variable field to set. So the daemon is started through
+  // `cmd /c` with the variables assigned inline, which is also what lets stdout
+  // be redirected to the log files the daemon rotates.
+  const assignments = [`set "PEW2_PORT=${port}"`];
+  if (options.experimental) assignments.push(`set "PEW2_EXPERIMENTAL=1"`);
+  if (options.env?.PEW2_HOME) assignments.push(`set "PEW2_HOME=${options.env.PEW2_HOME}"`);
+  if (options.env?.PEW2_RELAY) assignments.push(`set "PEW2_RELAY=${options.env.PEW2_RELAY}"`);
+
+  const start = program.map(quoteArgument).join(" ");
+  const line =
+    `${assignments.join(" && ")} && ${start} ` +
+    `>> ${quoteArgument(join(logs, "daemon.log"))} ` +
+    `2>> ${quoteArgument(join(logs, "daemon.error.log"))}`;
+
+  // UTF-16 is what `schtasks /create /xml` expects, and the declaration has to
+  // say so even though the file is written as UTF-8 with a BOM below.
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>pew2 daemon — remote control for desktop coding agents</Description>
+    <URI>\\${escapeXml(TASK_NAME)}</URI>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <!-- Retried for ever, so the daemon comes back after it exits to update.
+           Duration must exceed Interval or Windows rejects the definition. -->
+      <Repetition>
+        <Interval>PT1M</Interval>
+        <Duration>P3650D</Duration>
+        <StopAtDurationEnd>false</StopAtDurationEnd>
+      </Repetition>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <!-- The keepalive: while the daemon runs, every retry above is ignored. -->
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <!-- A laptop on battery is the normal case for this, not an exception. -->
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <!-- Without this the task is killed after three days by default. -->
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <Priority>7</Priority>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>cmd.exe</Command>
+      <Arguments>/c ${escapeXml(line)}</Arguments>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+
+export interface SchtasksDeps {
+  runCommand: (command: string, args: string[]) => Promise<CommandResult>;
+  home?: string;
+  /** Injected so tests do not spend the startup poll in real time. */
+  sleep?: (milliseconds: number) => Promise<void>;
+}
+
+export async function installScheduledTask(
+  options: InstallOptions,
+  deps: SchtasksDeps,
+): Promise<ServiceStatus> {
+  const home = options.home ?? deps.home ?? homedir();
+  const path = taskXmlPath(home);
+  await mkdir(dirname(path), { recursive: true });
+  await mkdir(logDir(options.env), { recursive: true });
+  // A BOM, because schtasks reads the file as UTF-16/Unicode and rejects a
+  // plain UTF-8 one with a bare "The task XML is malformed".
+  await writeFile(path, `\ufeff${buildTaskXml(options)}`, "utf8");
+
+  // `/f` overwrites an existing registration, so re-running install picks up a
+  // changed definition instead of failing on a name clash.
+  const created = await deps.runCommand("schtasks", [
+    "/create",
+    "/tn",
+    TASK_NAME,
+    "/xml",
+    path,
+    "/f",
+  ]);
+  if (created.code !== 0) {
+    return {
+      state: "installed",
+      servicePath: path,
+      detail: `Written, but schtasks /create failed: ${created.stdout.trim() || `exit ${created.code}`}`,
+    };
+  }
+
+  // A logon trigger does not fire until the next logon, so the first run is
+  // started by hand — otherwise `pew2 setup` reports success on a daemon that
+  // will not exist until the user signs out and back in.
+  await deps.runCommand("schtasks", ["/run", "/tn", TASK_NAME]);
+
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  for (let i = 0; i < 15; i++) {
+    const status = await scheduledTaskStatus(home, deps);
+    if (status.state === "running") return status;
+    await sleep(200);
+  }
+  return scheduledTaskStatus(home, deps);
+}
+
+export async function uninstallScheduledTask(
+  home: string,
+  deps: SchtasksDeps,
+): Promise<ServiceStatus> {
+  const path = taskXmlPath(home);
+  await deps.runCommand("schtasks", ["/end", "/tn", TASK_NAME]);
+  await deps.runCommand("schtasks", ["/delete", "/tn", TASK_NAME, "/f"]);
+  await rm(path, { force: true });
+  return { state: "not-installed", servicePath: path };
+}
+
+export async function scheduledTaskStatus(
+  home: string,
+  deps: SchtasksDeps,
+): Promise<ServiceStatus> {
+  const path = taskXmlPath(home);
+  const logPath = join(logDir(), "daemon.log");
+
+  try {
+    await readFile(path, "utf8");
+  } catch {
+    return { state: "not-installed", servicePath: path, logPath };
+  }
+
+  const queried = await deps.runCommand("schtasks", ["/query", "/tn", TASK_NAME, "/fo", "LIST"]);
+  if (queried.code !== 0) {
+    return { state: "installed", servicePath: path, logPath, detail: "Registered but not loaded." };
+  }
+
+  // `Status: Running` is Task Scheduler's word for "an instance is executing".
+  // Matched loosely because the label is localised on a non-English Windows,
+  // where falling back to "installed" is the safe answer rather than a wrong one.
+  const running = /^Status:\s*Running\s*$/im.test(queried.stdout);
+  const lastResult = queried.stdout.match(/^Last Result:\s*(-?\d+)\s*$/im)?.[1];
+
+  return {
+    state: running ? "running" : "installed",
+    servicePath: path,
+    logPath,
+    lastExitCode: lastResult ? Number(lastResult) : undefined,
+  };
+}

packages/daemon/src/cli/service-shared.ts

@@ -0,0 +1,101 @@
+/**
+ * What the three supervisor backends agree on.
+ *
+ * launchd, systemd and Task Scheduler each get their own module, because the
+ * details do not generalise — a plist, a unit file and a task XML have nothing
+ * in common but intent. This is the part that genuinely is shared: the label,
+ * the result shape, and the two questions every backend has to answer the same
+ * way ("what program should be run" and "is this a compiled binary").
+ *
+ * Separate from `service.ts` so the backends can import it without importing
+ * each other through their dispatcher.
+ */
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+/** One name across all three supervisors, so a machine cannot host two. */
+export const LABEL = "dev.pew2.daemon";
+
+export type ServiceState = "running" | "installed" | "not-installed" | "unsupported";
+
+export interface ServiceStatus {
+  state: ServiceState;
+  /**
+   * The file that defines the service: a launchd plist, a systemd unit, or the
+   * task XML on Windows. Its presence is what `supervisorInstalled()` reads.
+   */
+  servicePath?: string;
+  /** Kept as an alias so existing callers and JSON output do not change shape. */
+  plistPath?: string;
+  /** PID when running. */
+  pid?: number;
+  /** Last exit code the supervisor saw. Non-zero after a crash. */
+  lastExitCode?: number;
+  logPath?: string;
+  detail?: string;
+}
+
+export interface InstallOptions {
+  /** Absolute path to the `bun` binary. A supervisor has no PATH of its own. */
+  bunPath?: string;
+  port?: number;
+  /** Surface test fixtures such as the echo agent. */
+  experimental?: boolean;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+}
+
+export interface CommandResult {
+  code: number;
+  stdout: string;
+}
+
+export type RunCommand = (command: string, args: string[]) => Promise<CommandResult>;
+
+/**
+ * Is this a compiled binary rather than a source checkout?
+ *
+ * Bun serves a compiled binary's own modules out of a virtual filesystem rooted
+ * at `/$bunfs/`, so `import.meta.url` says so directly. Everything downstream of
+ * this question was wrong before it was asked.
+ */
+export function isCompiled(): boolean {
+  return import.meta.url.includes("/$bunfs/");
+}
+
+/**
+ * The daemon entry point, resolved from this file.
+ *
+ * A supervisor has no working directory and no shell, so every path has to be
+ * absolute. Only meaningful for a source checkout: in a compiled binary this
+ * resolves to a path inside the executable's own virtual filesystem, which no
+ * other process can open.
+ */
+export function serverEntry(): string {
+  return resolve(fileURLToPath(new URL("../server.ts", import.meta.url)));
+}
+
+/**
+ * What the supervisor should actually execute.
+ *
+ * Two different programs, because there are two ways pew2 is installed: from a
+ * checkout it is `bun run <abs path to server.ts>`, and from a released binary
+ * it is the binary itself with `serve`.
+ */
+export function programArguments(bunPath?: string): string[] {
+  if (isCompiled()) return [process.execPath, "serve"];
+  return [bunPath ?? process.execPath, "run", serverEntry()];
+}
+
+/** Run a command, treating a missing binary as a failed step rather than a throw. */
+export function run(command: string, args: string[]): Promise<CommandResult> {
+  return new Promise((resolvePromise) => {
+    const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    child.stdout.on("data", (chunk) => (stdout += chunk));
+    child.stderr.on("data", (chunk) => (stdout += chunk));
+    child.on("error", () => resolvePromise({ code: 127, stdout }));
+    child.on("close", (code) => resolvePromise({ code: code ?? 1, stdout }));
+  });
+}