viewable-one 0.0.0-stage → 0.12.1

package/lib/logindaemon.mjs

@@ -0,0 +1,976 @@
+// THE LOGIN DAEMON: one interface, three implementations, chosen by platform.
+//
+// Brief 19 installed ONE thing on the machine - a LaunchAgent - and that was
+// the whole of "install once, never keep a terminal open" (CONTEXT.md, "a
+// person runs the runner", retired 2026-09-06 by ruling 1). Brief 21 asks the
+// same of Windows, and the rulings of 2026-09-07 say what that means:
+//
+//   1A  Windows gets a Task Scheduler per-user `onlogon` task (`schtasks`),
+//       and it is chosen BECAUSE IT IS QUERYABLE: `doctor` keeps its two
+//       halves (is the thing installed, and is it actually running) only if
+//       the OS can be asked the first half. A Startup-folder shortcut cannot
+//       answer that question, and a Windows service cannot see the logged-in
+//       user's agent credentials.
+//   6C  WSL counts as well as native Windows, and `doctor` names which one it
+//       is running in ("macOS", "Windows", "WSL (Linux)"). WSL is Linux, so
+//       saying yes to it is saying yes to a THIRD implementation: a systemd
+//       user unit. Where `systemctl --user` is not there at all - an older
+//       WSL with no systemd - the row says so and names the fallback rather
+//       than pretending, because a lie about the daemon is a session that
+//       never starts.
+//
+// The launchd implementation and its macOS tests use this shared daemon
+// interface directly. The former launchagent.mjs compatibility wrapper is
+// retired. All three implementations follow the same rules:
+//
+//   - THE EXEC IS INJECTED. Every test asserts the argv sequence and the file
+//     content, and NOTHING in the suite runs launchctl, schtasks or
+//     systemctl on the machine running it.
+//   - GLYTCH_HOME MOVES THE FILE. A test cannot write into
+//     ~/Library/LaunchAgents or ~/.config/systemd/user even by accident.
+//   - ONE ESCAPE ENV, GLYTCH_NO_DAEMON_INSTALL, honoured by all three: the
+//     file is written and NOTHING is registered or loaded. GLYTCH_NO_LAUNCHCTL
+//     keeps working as an alias (2026-09-07: it is what brief 19 ruling 7
+//     named, it is set in the CLI suite and it may be set in his shell, so it
+//     is retired as a NAME and not as a behaviour).
+//
+// THE PATH TRAP TRAVELS. On macOS a launchd job's PATH is a short system
+// default with no Homebrew and no npm global bin, so the plist carries the
+// shell's PATH captured at `glytch init` (see renderPlist). Brief 21's audit
+// said a scheduled task inherits the logon environment and so needs no
+// capture - true of the environment a task STARTS with, and no help at all
+// when the user installs Homebrew-for-Windows, nvm or a new npm prefix after
+// logon and the daemon keeps the old one until the next reboot. So all three
+// capture, all three re-check, and all three refresh as a ONE-WAY UNION
+// (lib/sync.mjs): the same trap is covered in the same words on every
+// platform, and there is one story to tell rather than three.
+
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join, win32 } from "node:path";
+import { glytchHome } from "./registry.mjs";
+import { logDir, logPath } from "./logs.mjs";
+
+/** One name on all three platforms: the launchd label, the scheduled task
+ * name and the systemd unit are the same string, so a person reading any of
+ * the three OS tools sees what the docs call it. */
+export const DAEMON_LABEL = "ai.glytch.runner";
+export const PLIST_NAME = `${DAEMON_LABEL}.plist`;
+export const LAUNCHER_NAME = `${DAEMON_LABEL}.cmd`;
+export const TASK_XML_NAME = `${DAEMON_LABEL}.xml`;
+export const UNIT_NAME = `${DAEMON_LABEL}.service`;
+
+/** Which escape is set, by name, or null. GLYTCH_NO_DAEMON_INSTALL is the
+ * one brief 21 names; GLYTCH_NO_LAUNCHCTL is brief 19's and still works. */
+export const noDaemonInstall = (env = process.env) =>
+  (env.VIEWABLE_NO_DAEMON_INSTALL ?? env.GLYTCH_NO_DAEMON_INSTALL) ? "GLYTCH_NO_DAEMON_INSTALL" : (env.VIEWABLE_NO_LAUNCHCTL ?? env.GLYTCH_NO_LAUNCHCTL) ? "GLYTCH_NO_LAUNCHCTL" : null;
+
+/** /proc/version, or "". The WSL probe: a WSL kernel says "microsoft" in it,
+ * and a bare Linux kernel does not. Read synchronously and injectable, so
+ * platformKind stays a pure function of two inputs in every test. */
+export const readProcVersion = () => {
+  try {
+    return readFileSync("/proc/version", "utf8");
+  } catch {
+    return "";
+  }
+};
+
+/** "macos" | "windows" | "wsl" | "linux". Ruling 6C: BOTH native Windows and
+ * WSL count, and doctor names which one it is in - so the two Linuxes are
+ * told apart here rather than merged, even though they install the same
+ * systemd unit. */
+export function platformKind({ platform = process.platform, procVersion } = {}) {
+  if (platform === "darwin") return "macos";
+  if (platform === "win32") return "windows";
+  const text = procVersion ?? (platform === "linux" ? readProcVersion() : "");
+  return /microsoft/i.test(String(text)) ? "wsl" : "linux";
+}
+
+/** What doctor's first row prints. Ruling 6C's three words, plus the plain
+ * Linux that the same systemd implementation serves. */
+export const PLATFORM_LABEL = {
+  macos: "macOS",
+  windows: "Windows",
+  wsl: "WSL (Linux)",
+  linux: "Linux",
+};
+
+/** The glytch dispatcher, as an absolute path.
+ *
+ * The daemon runs `node <this file> runner watch` rather than bare `glytch`,
+ * and that is not a shortcut around ruling 2's one name - it is the same
+ * command with one less thing to resolve. launchd would have to find `glytch`
+ * on a PATH it does not have yet (the PATH is set by the very plist being
+ * loaded), and a global npm bin is a symlink to exactly this file anyway. On
+ * Windows the same argument is stronger: the global bin is `glytch.cmd`, and
+ * a `.cmd` is exactly what Node refuses to spawn without a shell. */
+export const glytchScriptPath = () => fileURLToPath(new URL("../glytch.mjs", import.meta.url));
+
+/** The script path the INSTALLED daemon file on this machine actually runs,
+ * or null - never glytchScriptPath() above, which is what THIS running
+ * package would install, not what a plist, launcher or unit written by some
+ * earlier `viewable init` still points at. Null covers both "there is no file"
+ * (impl.read already returns null, and the plist/scheduled-task/systemd row
+ * says so) and "the file is there but does not carry the shape we render" -
+ * doctor's daemon-version row treats both the same way: unknown, not a
+ * second FAIL for a fact the row above it already reported.
+ *
+ * GLYTCH_HOME moves the file exactly the way impl.read does, and nothing
+ * here runs launchctl, schtasks or systemctl - the same two rules every
+ * other function in this module follows. */
+export async function daemonScriptPath({
+  env = process.env,
+  platform = process.platform,
+  procVersion,
+  impl = loginDaemon({ env, platform, procVersion }),
+} = {}) {
+  const text = await impl.read(env);
+  return text === null ? null : impl.programScriptPath(text);
+}
+
+/** The version of the package a daemon script path belongs to, read from the
+ * package.json beside it - the script is `<pkg>/glytch.mjs`, so
+ * `<pkg>/package.json`, the same layout packageVersion() (lib/update.mjs)
+ * reads for the package running doctor. Never throws: a stale or since-
+ * evicted npx cache, or a script path with nothing next to it, is data for
+ * the row to call "unknown", not a crash. */
+export async function daemonPackageVersion(scriptPath) {
+  if (!scriptPath) return null;
+  try {
+    const text = await readFile(join(dirname(scriptPath), "package.json"), "utf8");
+    const version = JSON.parse(text).version;
+    return typeof version === "string" ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+const exists = async (path) => {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** The default runner for one of the three OS tools. Never throws: a non-zero
+ * exit is data.
+ *
+ * THE ESCAPE WRITES THE FILE AND REGISTERS NOTHING. It exists for two callers
+ * and both are real: the test suite, which must never touch launchd, Task
+ * Scheduler or systemd on the machine running it, and ruling 7 of brief 19 -
+ * "the LaunchAgent goes on his Mac only after the build is finished, by his
+ * word at that moment". So `viewable init` can be run end to end today, leave
+ * the file on disk, and load nothing until he says so. The skip is REPORTED,
+ * never silent: the row says the daemon was not loaded. */
+export const makeDaemonExec = (tool) => (args, env = process.env) => {
+  const escape = noDaemonInstall(env);
+  if (escape) {
+    return Promise.resolve({
+      ok: false,
+      code: 0,
+      stdout: "",
+      stderr: `${tool} ${args.join(" ")} was NOT run: ${escape} is set.`,
+    });
+  }
+  return new Promise((resolve) => {
+    execFile(tool, args, { timeout: 10_000, windowsHide: true }, (error, stdout, stderr) =>
+      resolve({
+        ok: !error,
+        code: error?.code ?? 0,
+        stdout: String(stdout ?? ""),
+        stderr: String(stderr ?? ""),
+      }),
+    );
+  });
+};
+
+export const execLaunchctl = makeDaemonExec("launchctl");
+export const execSchtasks = makeDaemonExec("schtasks");
+export const execSystemctl = makeDaemonExec("systemctl");
+
+/** Write the file if it is absent, or when `force` says so.
+ *
+ * IF ABSENT IS THE WHOLE RULE (ruling 5's sync: put back what is missing
+ * without touching what is there). A plist, a launcher or a unit someone has
+ * edited by hand - a different node, an extra variable, a nice+20 - is
+ * theirs, and `init` run again must not quietly undo it. `force` exists for
+ * the one caller that means it: a `doctor` that found the captured PATH
+ * gone. */
+async function writeIfAbsent(file, text, force) {
+  if ((await exists(file)) && !force) return false;
+  await mkdir(join(file, ".."), { recursive: true });
+  await writeFile(file, text, "utf8");
+  return true;
+}
+
+/** The log directory, made BEFORE the daemon is registered.
+ *
+ * WHY (2026-09-11, his Windows machine, the first `viewable init` that
+ * registered without elevation): every launcher below redirects the runner's
+ * output into `~/.glytch/logs/runner.log`, and the only code that ever
+ * created that directory was the runner's own logger (logs.mjs) - which is
+ * Node, and Node is what the redirect has to succeed BEFORE. cmd.exe opens
+ * the `>>` target before it starts the command, cannot create a parent
+ * directory to do it, fails the whole line with "The system cannot find the
+ * path specified" and exits 1: Task Scheduler reports the task ran and
+ * exited at once, doctor says "daemon loaded - OK" (the registration is
+ * there) and "heartbeat - never" (the process never was), and nothing on
+ * disk says why. systemd's `append:` has the same rule. launchd starts the
+ * job with or without its StandardOutPath, which is why the Mac never saw
+ * it - but it loses the log the same way. So install makes the directory
+ * itself, once, for all three; the .cmd launcher also carries an `if not
+ * exist` line, because a per-user onlogon task outlives a `rm -r
+ * ~/.glytch/logs` and a launcher that dies at the next logon is this bug
+ * back with a delay. */
+async function ensureLogDir(env) {
+  await mkdir(logDir(env), { recursive: true });
+}
+
+// ---------------------------------------------------------------- launchd --
+
+const xml = (text) =>
+  String(text)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+
+/** Where the plist goes. ~/Library/LaunchAgents on a real machine; under
+ * GLYTCH_HOME when it is set, which is what keeps the suite off this Mac. */
+export const plistPath = (env = process.env) =>
+  (env.VIEWABLE_HOME ?? env.GLYTCH_HOME)?.trim()
+    ? join(glytchHome(env), "LaunchAgents", PLIST_NAME)
+    : join(homedir(), "Library", "LaunchAgents", PLIST_NAME);
+
+/** The plist, rendered. Kept a pure function of its inputs so the test reads
+ * the same string launchd would. */
+export function renderPlist({
+  nodePath = process.execPath,
+  scriptPath = glytchScriptPath(),
+  path = process.env.PATH ?? "",
+  out = logPath(),
+  home,
+} = {}) {
+  const env = [
+    // The switch. A daemon is still not consent by itself: this is the same
+    // variable a person would have typed, written down once at install
+    // instead of on every command line.
+    ["PM_SPAWN_RUNNER", "on"],
+    // The captured shell PATH. See the launchd PATH trap above.
+    ["PATH", path],
+    ...(home ? [["GLYTCH_HOME", home]] : []),
+  ];
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xml(DAEMON_LABEL)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(nodePath)}</string>
+    <string>${xml(scriptPath)}</string>
+    <string>runner</string>
+    <string>watch</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${env.map(([k, v]) => `    <key>${xml(k)}</key>\n    <string>${xml(v)}</string>`).join("\n")}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xml(out)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(out)}</string>
+</dict>
+</plist>
+`;
+}
+
+/** The PATH a plist on disk carries, or null. `doctor` and the sync compare
+ * it against the shell's, because a PATH captured before Homebrew was
+ * installed is a daemon that cannot find the engine the app is offering. */
+export function capturedPlistPath(text) {
+  const match = /<key>PATH<\/key>\s*<string>([^<]*)<\/string>/.exec(String(text ?? ""));
+  return match ? match[1] : null;
+}
+
+/** The script path a plist's ProgramArguments carries - the SECOND
+ * `<string>`, after the node binary - or null. The counterpart of
+ * capturedPlistPath: same file, the OTHER value doctor's daemon-version row
+ * needs (brief 31, Move 5). A plist that is there and loaded is not proof it
+ * runs THIS package: his Mac's pointed at an `~/.npm/_npx` cache running
+ * 0.5.0 while `doctor` ran from a 0.7.0 checkout and called the login agent
+ * fine, because that row only checks the plist exists. */
+export function scriptPathFromPlist(text) {
+  const args = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(String(text ?? ""));
+  if (!args) return null;
+  const strings = [...args[1].matchAll(/<string>([^<]*)<\/string>/g)].map((m) => m[1]);
+  return strings[1] ?? null;
+}
+
+const launchd = {
+  kind: "launchd",
+  platforms: ["macos"],
+  /** The OS tool this implementation shells out to, by name, for the rows
+   * that have to say what was or was not run. */
+  tool: "launchctl",
+  /** What doctor and init call this row. Kept "login agent" on macOS because
+   * that is what brief 19 shipped and what the CLI suite reads. */
+  rowLabel: "LaunchAgent",
+  /** Who holds the registration, in a sentence. */
+  holder: "launchd",
+  mechanism: "a launchd LaunchAgent",
+  pathDelimiter: ":",
+  defaultExec: execLaunchctl,
+  filePath: plistPath,
+  render: renderPlist,
+  capturedPath: capturedPlistPath,
+  programScriptPath: scriptPathFromPlist,
+  read: (env = process.env) => readFile(plistPath(env), "utf8").catch(() => null),
+
+  /** Write the plist if it is absent and load it. Returns {file, wrote,
+   * loaded, why, calls} - `calls` being every launchctl argv, in order, so a
+   * test can assert the sequence. */
+  async install({
+    env = process.env,
+    exec = execLaunchctl,
+    nodePath = process.execPath,
+    scriptPath = glytchScriptPath(),
+    path = env.PATH ?? "",
+    force = false,
+    load = true,
+  } = {}) {
+    const file = plistPath(env);
+    const calls = [];
+    const run = async (args) => {
+      calls.push(args);
+      return exec(args, env);
+    };
+    await ensureLogDir(env);
+    const wrote = await writeIfAbsent(
+      file,
+      renderPlist({
+        nodePath,
+        scriptPath,
+        path,
+        out: logPath(env),
+        home: (env.VIEWABLE_HOME ?? env.GLYTCH_HOME)?.trim() || undefined,
+      }),
+      force,
+    );
+    if (!load) return { file, wrote, loaded: false, why: "not asked to load", calls };
+    // UNLOAD FIRST, ALWAYS, and ignore what it says. `launchctl load` on a
+    // label that is already loaded is an error, and a rewritten plist that is
+    // never unloaded keeps running the OLD one until the next login - which is
+    // the failure mode where `init` says it fixed the PATH and nothing changed.
+    await run(["unload", file]);
+    const loaded = await run(["load", "-w", file]);
+    return {
+      file,
+      wrote,
+      loaded: loaded.ok === true,
+      why: loaded.ok === true ? "" : loaded.stderr.trim() || `launchctl load exited ${loaded.code}`,
+      calls,
+    };
+  },
+
+  /** Unload the agent. The plist is LEFT ON DISK: `viewable stop` is "stop the
+   * daemon", not "forget this machine", and a person who stops it for an
+   * afternoon should get it back with `viewable init` rather than a reinstall.
+   * `removeFile` is there for an uninstall that means it. */
+  async stop({ env = process.env, exec = execLaunchctl, removeFile = false } = {}) {
+    const file = plistPath(env);
+    const calls = [];
+    if (!(await exists(file))) {
+      return { file, unloaded: false, why: "there is no plist to unload", calls };
+    }
+    calls.push(["unload", "-w", file]);
+    const result = await exec(["unload", "-w", file], env);
+    if (removeFile) await rm(file, { force: true }).catch(() => {});
+    return {
+      file,
+      unloaded: result.ok === true,
+      why: result.ok === true ? "" : result.stderr.trim() || `launchctl unload exited ${result.code}`,
+      calls,
+    };
+  },
+
+  /** Is launchd holding the label? `launchctl list <label>` exits non-zero
+   * when it is not. Doctor checks row-backed presence separately because
+   * a loaded daemon is not necessarily sending heartbeats. */
+  async loadedState({ env = process.env, exec = execLaunchctl } = {}) {
+    const result = await exec(["list", DAEMON_LABEL], env);
+    return { loaded: result.ok === true, unavailable: false, why: result.stderr?.trim() ?? "" };
+  },
+};
+
+// --------------------------------------------------------------- schtasks --
+
+/** Where the launcher batch file goes: ~/.glytch/ai.glytch.runner.cmd, or
+ * under GLYTCH_HOME.
+ *
+ * WHY THERE IS A FILE AT ALL. Ruling 1A's task command is `<node> <script>
+ * runner watch`, and that is exactly the last line of this file. The wrapper
+ * exists for the two things `schtasks` has no slot for and the plist gets for
+ * free: the environment (PM_SPAWN_RUNNER, and the captured PATH - see the
+ * PATH trap at the top) and a place to send stdout, since a scheduled task
+ * has no StandardOutPath. It also keeps `/tr` a single unquoted argument,
+ * which is the one part of schtasks that is genuinely hard to get right. */
+export const launcherPath = (env = process.env) => join(glytchHome(env), LAUNCHER_NAME);
+
+/** The launcher, rendered. Pure, so the test reads the same text Task
+ * Scheduler would run.
+ *
+ * A `"` in a PATH entry would end the `set` quoting early, and Windows does
+ * not allow one in a path anyway, so it is dropped rather than escaped. */
+export function renderLauncher({
+  nodePath = process.execPath,
+  scriptPath = glytchScriptPath(),
+  path = process.env.PATH ?? "",
+  out = logPath(),
+  home,
+} = {}) {
+  const q = (value) => String(value).replace(/"/g, "");
+  return `@echo off
+rem  ${DAEMON_LABEL} - the viewable login daemon, run by a Task Scheduler
+rem  onlogon task (brief 21, ruling 1A of 2026-09-07). Written by
+rem  \`viewable init\`; edit it and \`viewable init\` will leave your copy alone.
+set "PM_SPAWN_RUNNER=on"
+set "PATH=${q(path)}"
+${home ? `set "GLYTCH_HOME=${q(home)}"\n` : ""}if not exist "${q(win32.dirname(out))}" mkdir "${q(win32.dirname(out))}"
+"${q(nodePath)}" "${q(scriptPath)}" runner watch >> "${q(out)}" 2>&1
+`;
+}
+
+/** The PATH the launcher carries, or null. The counterpart of
+ * capturedPlistPath, and it exists for the same reason: a PATH captured
+ * before nvm was installed is a daemon that cannot find the engine. */
+export function capturedLauncherPath(text) {
+  const match = /^set "PATH=(.*)"$/m.exec(String(text ?? ""));
+  return match ? match[1] : null;
+}
+
+/** The script path the launcher's own invocation line runs - the second
+ * quoted argument, after the node binary, on the `"<node>" "<script>" runner
+ * watch >> ...` line - or null. The Windows half of the same daemon-version
+ * check (brief 31, Move 5): the task XML's `<Command>` only names this
+ * launcher, so the launcher itself is where the actual glytch.mjs path
+ * lives. */
+export function scriptPathFromLauncher(text) {
+  const match = /^"[^"]*"\s+"([^"]*)"\s+runner watch\b/m.exec(String(text ?? ""));
+  return match ? match[1] : null;
+}
+
+/** Where the task definition goes: ~/.glytch/ai.glytch.runner.xml, or under
+ * GLYTCH_HOME.
+ *
+ * WHY THERE IS AN XML AT ALL (2026-09-11, his Windows machine, `glytch
+ * doctor`): `schtasks /create /sc onlogon /tn <name> /tr <file>` names no
+ * principal, so Task Scheduler registers the logon trigger for the Users
+ * GROUP - an all-users task in the root of the Task Scheduler Library, which
+ * is an administrator's registration to make. From a normal PowerShell it is
+ * `ERROR: Access is denied.`, and the row that reported it sent him to
+ * `viewable init`, which ran the same command and failed the same way. Brief
+ * 21's audit ("no dependency, no admin, runs as the user") was right about
+ * the MECHANISM and wrong about this spelling of it.
+ *
+ * The XML carries the two things the command line has no slot for: the
+ * trigger's UserId is THIS user, and the principal runs with an
+ * InteractiveToken at LeastPrivilege. That registration is the user's own
+ * and needs no elevation. It is still a per-user onlogon task and still
+ * queryable with `/query /tn`, so ruling 1A is untouched - only the spelling
+ * of the registration changed, and the command-line form stays as the
+ * fallback for a schtasks that will not take the file. */
+export const taskXmlPath = (env = process.env) => join(glytchHome(env), TASK_XML_NAME);
+
+/** `DOMAIN\user`, or null when the environment does not say who we are (a
+ * stripped env, or a test). Null is what sends install back to the
+ * command-line form: an XML with no UserId would be the all-users task this
+ * exists to avoid. */
+export function taskUser(env = process.env) {
+  const user = String(env.USERNAME ?? "").trim();
+  if (!user) return null;
+  const domain = String(env.USERDOMAIN ?? "").trim();
+  return domain && domain.toLowerCase() !== user.toLowerCase() ? `${domain}\\${user}` : user;
+}
+
+/** The task definition, rendered. Pure, so the test reads the same text Task
+ * Scheduler would import.
+ *
+ * The element ORDER is Task Scheduler's own export order and not a taste:
+ * the schema is a sequence, and a Settings block in another order is
+ * rejected with a parse error rather than a helpful one. Everything here is
+ * the launchd plist's intent said in Windows: run at logon (LogonTrigger),
+ * keep running (ExecutionTimeLimit PT0S is "no limit", RestartOnFailure is
+ * KeepAlive), start it even if the trigger was missed (StartWhenAvailable),
+ * and never stop it for a battery or an idle machine - a laptop on its own
+ * power is not a reason for the board to go quiet.
+ *
+ * `<Command>` IS QUOTED WHEN IT HAS A SPACE. Task Scheduler resolves this
+ * element as a path the same way CreateProcess would, not as text a pair of
+ * XML tags already delimits unambiguously - Microsoft's own schema docs say
+ * a path containing a space must be quoted here, exactly the way the .cmd
+ * launcher already quotes its own node/script invocation below. `glytch
+ * init` run from `C:\Users\John Doe\...` or a OneDrive-synced folder
+ * (`...\OneDrive - Acme Corp\...`) both put a space in this path, launcher
+ * name included (`~\.glytch\ai.glytch.runner.cmd`), and an unquoted one is
+ * read as a shorter path plus a stray trailing argument - Task Scheduler
+ * reports the task ran and immediately exited, with nothing on the board to
+ * say why. */
+export function renderTaskXml({ command, user, description = "Viewable on your computer" } = {}) {
+  const commandXml = /\s/.test(String(command ?? "")) ? `"${command}"` : command;
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>${xml(description)}</Description>
+    <URI>\\${xml(DAEMON_LABEL)}</URI>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${xml(user)}</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${xml(user)}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>3</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${xml(commandXml)}</Command>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+
+/** Task Scheduler XML is read as UTF-16: schtasks refuses a plain UTF-8 file
+ * with a parse error that says nothing about the encoding. The BOM is the
+ * half that matters, and `utf16le` + `\ufeff` is how Node writes one. */
+async function writeTaskXml(file, text) {
+  await mkdir(join(file, ".."), { recursive: true });
+  await writeFile(file, Buffer.from(`\ufeff${text}`, "utf16le"));
+  return file;
+}
+
+/** Is this Task Scheduler refusing US, rather than a task that is not there?
+ * Told apart because the two need opposite answers: a missing task is
+ * installed, and a refused one is a person opening an elevated terminal. */
+export const schtasksDenied = (result) =>
+  /access is denied|do(es)? not have permission|requires elevation/i.test(
+    `${result?.stderr ?? ""} ${result?.stdout ?? ""}`,
+  );
+
+/** What to type on Windows when the daemon cannot be registered.
+ * POWERSHELL'S SPELLING, because that is the shell VS Code and Windows
+ * Terminal open - `PM_SPAWN_RUNNER=on viewable runner watch` is POSIX syntax
+ * that neither PowerShell nor cmd.exe has, so RUNNER_BY_HAND pasted there is
+ * an error rather than a runner. cmd.exe's own is `set PM_SPAWN_RUNNER=on &&
+ * viewable runner watch`; the README carries both. */
+export const RUNNER_BY_HAND_WINDOWS = '$env:PM_SPAWN_RUNNER="on"; viewable runner watch';
+
+/** The one next step a denied registration leaves. It travels on the row as
+ * `action`, so doctor prints THIS under "Next steps" instead of its default
+ * "run viewable init", which is the advice that looped. */
+export const ELEVATED_INIT =
+  'Task Scheduler refused the registration. Open a terminal with "Run as administrator" and run viewable init once from this project folder' +
+  ` - or skip the daemon and run the runner by hand: ${RUNNER_BY_HAND_WINDOWS}`;
+
+const schtasks = {
+  kind: "schtasks",
+  platforms: ["windows"],
+  tool: "schtasks",
+  rowLabel: "scheduled task",
+  holder: "Task Scheduler",
+  mechanism: "a Task Scheduler per-user onlogon task",
+  // Windows PATH is `;` separated and its entries contain `C:`. Splitting on
+  // `:` here would make every comparison nonsense (brief 21, sync.mjs:90).
+  pathDelimiter: ";",
+  defaultExec: execSchtasks,
+  filePath: launcherPath,
+  render: renderLauncher,
+  capturedPath: capturedLauncherPath,
+  programScriptPath: scriptPathFromLauncher,
+  read: (env = process.env) => readFile(launcherPath(env), "utf8").catch(() => null),
+
+  async install({
+    env = process.env,
+    exec = execSchtasks,
+    nodePath = process.execPath,
+    scriptPath = glytchScriptPath(),
+    path = env.PATH ?? env.Path ?? "",
+    force = false,
+    load = true,
+  } = {}) {
+    const file = launcherPath(env);
+    const calls = [];
+    const run = async (args) => {
+      calls.push(args);
+      return exec(args, env);
+    };
+    await ensureLogDir(env);
+    const wrote = await writeIfAbsent(
+      file,
+      renderLauncher({
+        nodePath,
+        scriptPath,
+        path,
+        out: logPath(env),
+        home: (env.VIEWABLE_HOME ?? env.GLYTCH_HOME)?.trim() || undefined,
+      }),
+      force,
+    );
+    if (!load) return { file, wrote, loaded: false, why: "not asked to load", calls };
+    // THE REGISTRATION, IN TWO SPELLINGS. The XML is the one that works
+    // unelevated (see taskXmlPath): it names this user on both the trigger
+    // and the principal. /f OVERWRITES an existing registration, which is the
+    // schtasks spelling of launchd's unload-then-load: the task must end up
+    // naming the launcher we just wrote, not a stale one.
+    const user = taskUser(env);
+    let created = null;
+    if (user) {
+      const xmlFile = await writeTaskXml(taskXmlPath(env), renderTaskXml({ command: file, user }));
+      created = await run(["/create", "/tn", DAEMON_LABEL, "/xml", xmlFile, "/f"]);
+    }
+    // THE FALLBACK IS THE OLD COMMAND LINE, and it is not tried after a
+    // refusal: `/sc onlogon` with no principal asks for MORE than the XML did
+    // (an all-users task), so a machine that denied the XML denies this too
+    // and the second error only buries the first. It is for the other
+    // failures - a schtasks too old for `/xml`, a definition it will not
+    // parse - where the form that used to work still can.
+    // The escape makes every call a reported no-op (makeDaemonExec), and a
+    // second no-op says nothing the first did not - so it is the same one
+    // call it always was.
+    if (!created || (created.ok !== true && !noDaemonInstall(env) && !schtasksDenied(created))) {
+      created = await run(["/create", "/sc", "onlogon", "/tn", DAEMON_LABEL, "/tr", file, "/f"]);
+    }
+    if (created.ok !== true) {
+      const denied = schtasksDenied(created);
+      return {
+        file,
+        wrote,
+        loaded: false,
+        denied,
+        action: denied ? ELEVATED_INIT : undefined,
+        // The advice rides on `action`, never in `why`: the detail line says
+        // what the OS said, and the next step is printed once, under its own
+        // heading, rather than twice in two different wordings.
+        why: created.stderr.trim() || (denied ? "access is denied" : `schtasks /create exited ${created.code}`),
+        calls,
+      };
+    }
+    // END THEN RUN, and ignore what /end says. An onlogon task does not start
+    // itself at install time (the next logon is a reboot away), and one that
+    // IS running is running the environment it was given before the PATH was
+    // refreshed - the same failure the plist's unload-then-load exists to
+    // prevent. /end on a task that is not running exits non-zero and that is
+    // fine, exactly as `launchctl unload` on an unloaded label is.
+    await run(["/end", "/tn", DAEMON_LABEL]);
+    const started = await run(["/run", "/tn", DAEMON_LABEL]);
+    const denied = started.ok !== true && schtasksDenied(started);
+    return {
+      file,
+      wrote,
+      loaded: started.ok === true,
+      denied,
+      action: denied ? ELEVATED_INIT : undefined,
+      why: started.ok === true
+        ? ""
+        : started.stderr.trim() || (denied ? "access is denied" : `schtasks /run exited ${started.code}`),
+      calls,
+    };
+  },
+
+  /** Delete the registration, leave the launcher on disk.
+   *
+   * /delete rather than /end, because `viewable stop` means "this machine stops
+   * running it until I say otherwise" and an ended task is still registered -
+   * doctor would keep saying the daemon is installed and the next logon would
+   * start it again. The launcher file stays, so `viewable init` brings it back
+   * without a reinstall, which is exactly what the plist does. */
+  async stop({ env = process.env, exec = execSchtasks, removeFile = false } = {}) {
+    const file = launcherPath(env);
+    const calls = [];
+    if (!(await exists(file))) {
+      return { file, unloaded: false, why: "there is no scheduled task to unload", calls };
+    }
+    calls.push(["/end", "/tn", DAEMON_LABEL]);
+    await exec(["/end", "/tn", DAEMON_LABEL], env);
+    calls.push(["/delete", "/tn", DAEMON_LABEL, "/f"]);
+    const result = await exec(["/delete", "/tn", DAEMON_LABEL, "/f"], env);
+    // The XML is the registration's argument and nothing else reads it, so it
+    // goes with the launcher when the caller means "leave nothing behind".
+    if (removeFile) {
+      await rm(file, { force: true }).catch(() => {});
+      await rm(taskXmlPath(env), { force: true }).catch(() => {});
+    }
+    return {
+      file,
+      unloaded: result.ok === true,
+      why: result.ok === true ? "" : result.stderr.trim() || `schtasks /delete exited ${result.code}`,
+      calls,
+    };
+  },
+
+  /** Is the task registered? `schtasks /query /tn <name>` exits non-zero when
+   * it is not. This is the half ruling 1A chose Task Scheduler FOR: a Startup
+   * shortcut could not be asked. */
+  async loadedState({ env = process.env, exec = execSchtasks } = {}) {
+    const result = await exec(["/query", "/tn", DAEMON_LABEL], env);
+    // A REFUSED QUERY IS NOT A MISSING TASK. Both exit non-zero, and reading
+    // the refusal as "not registered" is what sent init off to re-register
+    // something it was never allowed to touch. The caller gets the
+    // difference and stops rather than loops.
+    const denied = result.ok !== true && schtasksDenied(result);
+    return {
+      loaded: result.ok === true,
+      unavailable: false,
+      denied,
+      action: denied ? ELEVATED_INIT : undefined,
+      why: result.stderr?.trim() || (denied ? "access is denied" : ""),
+    };
+  },
+};
+
+// ---------------------------------------------------------------- systemd --
+
+/** ~/.config/systemd/user/ai.glytch.runner.service, XDG honoured, and under
+ * GLYTCH_HOME when it is set so the suite writes nowhere systemd reads. */
+export const unitPath = (env = process.env) =>
+  (env.VIEWABLE_HOME ?? env.GLYTCH_HOME)?.trim()
+    ? join(glytchHome(env), "systemd", "user", UNIT_NAME)
+    : join(env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config"), "systemd", "user", UNIT_NAME);
+
+/** The unit, rendered. Every value is quoted: systemd splits ExecStart and
+ * Environment on whitespace otherwise, and a home directory with a space in
+ * it is ordinary. */
+export function renderUnit({
+  nodePath = process.execPath,
+  scriptPath = glytchScriptPath(),
+  path = process.env.PATH ?? "",
+  out = logPath(),
+  home,
+} = {}) {
+  const q = (value) => String(value).replace(/"/g, '\\"');
+  return `[Unit]
+Description=Viewable on your computer
+Documentation=https://github.com/glytch-ai/viewable
+After=default.target
+
+[Service]
+Type=simple
+ExecStart="${q(nodePath)}" "${q(scriptPath)}" runner watch
+Environment="PM_SPAWN_RUNNER=on"
+Environment="PATH=${q(path)}"
+${home ? `Environment="GLYTCH_HOME=${q(home)}"\n` : ""}# KeepAlive, in systemd's words. The mac's plist asks for the same thing.
+Restart=always
+RestartSec=5
+StandardOutput=append:${out}
+StandardError=append:${out}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+/** The PATH the unit carries, or null. */
+export function capturedUnitPath(text) {
+  const match = /^Environment="PATH=(.*)"$/m.exec(String(text ?? ""));
+  return match ? match[1] : null;
+}
+
+/** The script path a systemd unit's ExecStart runs - the second quoted
+ * argument, after the node binary - or null. The Linux/WSL half of the same
+ * daemon-version check (brief 31, Move 5). */
+export function scriptPathFromUnit(text) {
+  const match = /^ExecStart="[^"]*"\s+"([^"]*)"\s+runner watch\b/m.exec(String(text ?? ""));
+  return match ? match[1] : null;
+}
+
+/** Is this "systemctl --user is not here" rather than "the unit is not
+ * active"? An older WSL with no systemd has no `systemctl` on PATH at all,
+ * and a systemd that is there without a user bus refuses to connect. Ruling
+ * 6C: say so honestly and name the fallback - never report it as a unit that
+ * simply is not running, which would send a person to `viewable init` for ever. */
+export const systemctlUnavailable = (result) =>
+  /ENOENT|not found|no such file|failed to connect to bus|failed to get d-?bus|is not running/i.test(
+    `${result?.stderr ?? ""}`,
+  ) || result?.code === "ENOENT";
+
+/** What to type when there is no systemd to install into. */
+export const RUNNER_BY_HAND = "PM_SPAWN_RUNNER=on viewable runner watch";
+
+const systemd = {
+  kind: "systemd",
+  platforms: ["wsl", "linux"],
+  tool: "systemctl",
+  rowLabel: "systemd user unit",
+  holder: "systemd --user",
+  mechanism: "a systemd user unit",
+  pathDelimiter: ":",
+  defaultExec: execSystemctl,
+  filePath: unitPath,
+  render: renderUnit,
+  capturedPath: capturedUnitPath,
+  programScriptPath: scriptPathFromUnit,
+  read: (env = process.env) => readFile(unitPath(env), "utf8").catch(() => null),
+
+  async install({
+    env = process.env,
+    exec = execSystemctl,
+    nodePath = process.execPath,
+    scriptPath = glytchScriptPath(),
+    path = env.PATH ?? "",
+    force = false,
+    load = true,
+  } = {}) {
+    const file = unitPath(env);
+    const calls = [];
+    const run = async (args) => {
+      calls.push(args);
+      return exec(args, env);
+    };
+    await ensureLogDir(env);
+    const wrote = await writeIfAbsent(
+      file,
+      renderUnit({
+        nodePath,
+        scriptPath,
+        path,
+        out: logPath(env),
+        home: (env.VIEWABLE_HOME ?? env.GLYTCH_HOME)?.trim() || undefined,
+      }),
+      force,
+    );
+    if (!load) return { file, wrote, loaded: false, why: "not asked to load", calls };
+    // DAEMON-RELOAD FIRST, ALWAYS. systemd caches unit files, so a rewritten
+    // unit that is never re-read keeps running the OLD one - the same failure
+    // the plist's unload-then-load prevents. `enable --now` then both
+    // registers it for the next login and starts it in this one, which is
+    // RunAtLoad and the plist's `-w` in one call.
+    const reloaded = await run(["--user", "daemon-reload"]);
+    if (!reloaded.ok) {
+      const unavailable = systemctlUnavailable(reloaded);
+      return { file, wrote, loaded: false, unavailable,
+        why: unavailable ? `systemctl --user is not available on your computer: run ${RUNNER_BY_HAND}` : reloaded.stderr?.trim() || "systemctl daemon-reload failed", calls };
+    }
+    let enabled = await run(["--user", "enable", "--now", UNIT_NAME]);
+    // enable --now leaves an already-running process alone, even after the
+    // file at ExecStart was replaced. Explicit repair/update must reload it.
+    if (enabled.ok && force) enabled = await run(["--user", "restart", UNIT_NAME]);
+    const unavailable = enabled.ok !== true && systemctlUnavailable(enabled);
+    return {
+      file,
+      wrote,
+      loaded: enabled.ok === true,
+      unavailable,
+      why: enabled.ok === true
+        ? ""
+        : unavailable
+          ? `systemctl --user is not available on your computer: run ${RUNNER_BY_HAND}`
+          : enabled.stderr.trim() || `systemctl --user enable exited ${enabled.code}`,
+      calls,
+    };
+  },
+
+  /** Disable and stop, leaving the unit file on disk - the plist's rule. */
+  async stop({ env = process.env, exec = execSystemctl, removeFile = false } = {}) {
+    const file = unitPath(env);
+    const calls = [];
+    if (!(await exists(file))) {
+      return { file, unloaded: false, why: "there is no systemd user unit to unload", calls };
+    }
+    calls.push(["--user", "disable", "--now", UNIT_NAME]);
+    const result = await exec(["--user", "disable", "--now", UNIT_NAME], env);
+    if (removeFile) await rm(file, { force: true }).catch(() => {});
+    return {
+      file,
+      unloaded: result.ok === true,
+      why: result.ok === true ? "" : result.stderr.trim() || `systemctl --user disable exited ${result.code}`,
+      calls,
+    };
+  },
+
+  /** `systemctl --user is-active <unit>` exits non-zero for every kind of
+   * not-running, so the unavailable case is told apart by what it SAID. */
+  async loadedState({ env = process.env, exec = execSystemctl } = {}) {
+    const result = await exec(["--user", "is-active", UNIT_NAME], env);
+    if (result.ok === true) return { loaded: true, unavailable: false, why: "" };
+    const unavailable = systemctlUnavailable(result);
+    return {
+      loaded: false,
+      unavailable,
+      why: unavailable
+        ? `systemctl --user is not available on your computer: run ${RUNNER_BY_HAND}`
+        : result.stderr?.trim() ?? "",
+    };
+  },
+};
+
+export const IMPLEMENTATIONS = { launchd, schtasks, systemd };
+
+const BY_KIND = { macos: launchd, windows: schtasks, wsl: systemd, linux: systemd };
+
+/** THE INTERFACE, for one machine.
+ *
+ * Everything above is chosen here and nowhere else: sync, doctor and the CLI
+ * ask for the implementation and then call install / stop / isLoaded /
+ * describe on it, so adding a fourth platform is a fourth object and no
+ * fourth `if`. */
+export function loginDaemon({ platform = process.platform, procVersion, env = process.env } = {}) {
+  const kind = platformKind({ platform, procVersion });
+  const impl = BY_KIND[kind] ?? launchd;
+  return {
+    ...impl,
+    platform: kind,
+    platformLabel: PLATFORM_LABEL[kind] ?? kind,
+    /** Everything a row needs to print itself, without asking the OS. */
+    describe: () => ({
+      platform: kind,
+      platformLabel: PLATFORM_LABEL[kind] ?? kind,
+      kind: impl.kind,
+      label: impl.rowLabel,
+      holder: impl.holder,
+      mechanism: impl.mechanism,
+      file: impl.filePath(env),
+    }),
+    /** The boolean half. `loadedState` is there for the caller that needs to
+     * tell "not running" from "there is no systemd here". */
+    isLoaded: async (options = {}) => (await impl.loadedState({ env, ...options })).loaded,
+  };
+}