@edspencer/paddock 0.82.0 → 0.82.1

package/packages/server/dist/cli/service/systemd.js

@@ -1,152 +1,56 @@
+// From edspencer/cli-contract reference/service/systemd.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// Linux: a systemd user unit (`systemctl --user`, SPEC §7), running as the user. Without linger the user's manager,
+// and the service with it, stops at their last logout, SSH sessions included; `linger()` asks, and the tool prints
+// the `sudo loginctl enable-linger` line rather than running it. Node built-ins only.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 /**
- * The Linux backend: a `systemd --user` unit (#796).
- *
- * ## Not the server story
- *
- * Paddock already documents itself under systemd — `guides/proxmox-lxc.md`
- * Path B, provisioned by the `paddock-deploy` Ansible recipes. That is a
- * SYSTEM unit, running as a service user, behind a reverse proxy, with a token
- * in its environment. This is the other one: a user unit, running as you, on
- * loopback, using the Claude login you already have. They should not be
- * confused, and this module writes nothing outside `~/.config/systemd/user`.
- *
- * ## Lingering
- *
- * A `--user` manager is started at your first login and stopped at your last
- * logout, so by default the unit dies when you log out — including when you log
- * out of an SSH session, which is how most people meet this. `loginctl
- * enable-linger <user>` keeps the manager (and therefore Paddock) alive.
- *
- * That is called out in the install output rather than being run for the user:
- * lingering is a real change to how the machine behaves after they leave it,
- * and it needs a privilege this command otherwise never asks for.
- */
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { SYSTEMD_UNIT } from "./spec.js";
-/**
- * `~/.config/systemd/user/paddock.service`, honouring `XDG_CONFIG_HOME`.
- *
- * ## An injected home outranks the ambient variable
- *
- * The precedence is: an explicit `xdgConfigHome` argument, then an explicitly
- * **injected** `homeDir`, then — only when the caller named neither — the real
- * environment. That middle rung is the whole point, and getting it wrong was a
- * live bug rather than a style question.
- *
- * The first version read `process.env.XDG_CONFIG_HOME` before falling back to
- * `homeDir`. On any machine with that variable set — CI, and plenty of Linux
- * desktops — the `homeDir` parameter was therefore **a lie**: a caller passing a
- * throwaway directory still resolved to the real config home. Two things
- * followed. Test isolation quietly stopped working, so which assertion passed
- * depended on test ORDER rather than test content. And the suite wrote a real
- * `paddock.service` into the runner's actual config directory, outside every
- * temp dir it thought it was confined to — which on a contributor's machine
- * would have installed a unit they never asked for.
- *
- * So: passing a home is a statement about where home is, and it wins. The
- * ambient read survives only on the branch where nobody said otherwise, which
- * is the real-use branch and the one where honouring `XDG_CONFIG_HOME` is
- * correct. (`paddock.ts` threads the variable in explicitly as well, so the
- * production path does not depend on this fallback — it is here so that a
- * caller with no opinion still gets the right answer.)
+ * `${XDG_CONFIG_HOME:-~/.config}/systemd/user/<unit>`. A home passed in beats the ambient `XDG_CONFIG_HOME`: a test
+ * that names a throwaway home must not write a unit into the real config folder because the variable was set.
  */
-export function unitPath(homeDir, xdgConfigHome) {
-    const base = xdgConfigHome ??
-        (homeDir !== undefined
-            ? path.join(homeDir, ".config")
-            : (process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config")));
-    return path.join(base, "systemd", "user", SYSTEMD_UNIT);
+export function unitPath(id, homeDir, xdgConfigHome) {
+    const base = xdgConfigHome ?? (homeDir !== undefined ? path.join(homeDir, '.config') : (process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config')));
+    return path.join(base, 'systemd', 'user', id.unit);
 }
-/**
- * Unit-file escaping, ported from Local Review's `server/service/systemd.ts`
- * (`pct`, `cEscape`, `cUnescape`, `execWord`, `execWords`) @ cli-contract spec
- * 0.1; local changes: doc comments only. Wave C4 moves these to
- * `reference/service/` and re-syncs.
- *
- * `%` starts a specifier EVERYWHERE in a unit file, so it is doubled; `$`
- * starts a variable in `ExecStart`, so it is doubled there too.
- */
-const pct = (s) => s.replace(/%/g, "%%");
-const cEscape = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\t/g, "\\t");
-const cUnescape = (s) => s.replace(/\\(.)/g, (_, c) => (c === "n" ? "\n" : c === "t" ? "\t" : c));
-/** One `ExecStart` word: specifiers and variables escaped, quoted when it has to be. */
+// `%` starts a specifier anywhere in a unit file, so it's doubled; `$` starts a variable in `ExecStart`, so it's
+// doubled there too.
+const pct = (s) => s.replace(/%/g, '%%');
+const cEscape = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\t/g, '\\t');
+const cUnescape = (s) => s.replace(/\\(.)/g, (_, c) => (c === 'n' ? '\n' : c === 't' ? '\t' : c));
+/** One `ExecStart` word: specifiers and variables escaped, and quoted when it has to be. */
 export function execWord(a) {
-    const s = pct(a).replace(/\$/g, "$$$$");
-    return s === "" || /[\s"'\\;]/.test(s) ? `"${cEscape(s)}"` : s;
+    const s = pct(a).replace(/\$/g, '$$$$');
+    return s === '' || /[\s"'\\;]/.test(s) ? `"${cEscape(s)}"` : s;
 }
-/**
- * The other way: the words of an `ExecStart` line.
- *
- * Reads both shapes on purpose. A unit written before #796's quoting is a bare
- * whitespace-separated line, and its owner is exactly the person whose `status`
- * has to keep working — so unquoted words pass through unchanged, and quoted
- * ones are unescaped.
- */
+/** The words of an `ExecStart` line. Reads unquoted words too, so an older unit's `status` still works. */
 export function execWords(line) {
-    const out = [];
-    for (const m of line.matchAll(/"((?:[^"\\]|\\.)*)"|(\S+)/g)) {
-        const w = m[1] !== undefined ? cUnescape(m[1]) : m[2];
-        out.push(w.replace(/\$\$/g, "$").replace(/%%/g, "%"));
-    }
-    return out;
+    return [...line.matchAll(/"((?:[^"\\]|\\.)*)"|(\S+)/g)].map((m) => (m[1] !== undefined ? cUnescape(m[1]) : m[2]).replace(/\$\$/g, '$').replace(/%%/g, '%'));
 }
 /**
- * Render the unit.
- *
- * `Restart=always`, matching launchd's `KeepAlive=<true/>` (#872). It was
- * `on-failure`, which for a service is the wrong default for the same reason it
- * was wrong there: `start.ts` exits `0` on SIGTERM, so a logout — or anything
- * else that signals the user manager — was read as an intended stop and Paddock
- * stayed down.
- *
- * `always` does not make the unit unstoppable. systemd never restarts a unit it
- * was itself asked to stop, so `systemctl --user stop` (and therefore
- * `uninstall`) remains the clean, explicit way to put it down. That is the
- * difference between an exit code, which has to guess at intent, and a command,
- * which carries it.
- *
- * `WantedBy=default.target` is what makes `systemctl --user enable` mean
- * "start at login" for a user unit; `multi-user.target` is the system-unit
- * spelling and does nothing here.
- *
- * ## Logs go to a file, not the journal (SPEC §7)
- *
- * `StandardOutput=append:` / `StandardError=append:` name one file, the same
- * one launchd's two keys name. The journal was the obvious choice and the wrong
- * one for three reasons: `journalctl --user` shows nothing at all on a distro
- * whose journal is volatile (the output is gone after a reboot, which is
- * exactly when someone looks); it makes "where are the logs" have a different
- * answer on each platform, so `paddock service logs` would be two
- * implementations; and it rules out Windows, which the contract requires
- * nothing rule out.
+ * The unit.
  *
- * The directory has to exist first — systemd creates the file, not its parent —
- * which `install` below does.
- *
- * ## Every ExecStart word is quoted
- *
- * `%` starts a specifier anywhere in a unit file and `$` starts a variable in
- * `ExecStart`, so both are escaped; a word containing whitespace, a quote or a
- * backslash is quoted. Paths with a space in them are the common case
- * (`/Users/Ed Spencer/.paddock`), and the old unqualified `join(" ")` wrote a
- * unit systemd then split into the wrong arguments — a service that fails at
- * login having printed nothing.
+ * - `Restart=always`, matching launchd's `KeepAlive`: a server exits 0 on SIGTERM, so `on-failure` would leave it
+ *   down after a logout signals the user's manager. systemd never restarts a unit it was asked to stop.
+ * - Both streams `append:` to one file rather than the journal, which is volatile on many distributions and would
+ *   make `logs` a different program on each OS. systemd creates the file, not its folder, so `install` makes that.
+ * - Every `ExecStart` word is escaped and quoted where needed: paths with spaces are common (`/Users/Ed Spencer/…`).
  */
-export function renderUnit(spec) {
-    const exec = [spec.nodePath, spec.scriptPath, ...spec.args].map(execWord).join(" ");
-    return `# Generated by Paddock — \`paddock service install\` rewrites this file.
+export function renderUnit(id, spec) {
+    const exec = [spec.nodePath, spec.scriptPath, ...spec.args].map(execWord).join(' ');
+    const env = Object.entries({ PATH: spec.pathEnv, ...spec.env })
+        .map(([k, v]) => `Environment="${cEscape(pct(`${k}=${v}`))}"`)
+        .join('\n');
+    return `# Generated by ${id.name}: \`${id.tool} service install\` rewrites this file.
 # Node: ${spec.nodePath}
 [Unit]
-Description=Paddock — persistent, resumable Claude Code sessions, by project
-Documentation=https://paddock.edspencer.net
-
+Description=${id.description}
+${id.documentation !== undefined ? `Documentation=${id.documentation}\n` : ''}
 [Service]
 Type=simple
 ExecStart=${exec}
 WorkingDirectory=${pct(spec.workingDirectory)}
-Environment="PATH=${cEscape(pct(spec.pathEnv))}"
+${env}
 StandardOutput=append:${pct(spec.logPath)}
 StandardError=append:${pct(spec.logPath)}
 Restart=always
@@ -156,160 +60,101 @@ RestartSec=10
 WantedBy=default.target
 `;
 }
-/** The log file an installed unit appends to, or undefined if it names none. */
+/** `ExecStart=`, read back as an argv. */
+export function parseUnitArgv(text) {
+    const m = /^ExecStart=(.*)$/m.exec(text);
+    return m === null ? [] : execWords(m[1].trim());
+}
+/** The log the unit appends to, if it names one. */
 export function parseUnitLogPath(text) {
     const m = /^StandardOutput=append:(.*)$/m.exec(text);
-    return m === null ? undefined : m[1].trim().replace(/%%/g, "%");
+    return m === null ? undefined : m[1].trim().replace(/%%/g, '%');
 }
-/**
- * Does an installed unit carry `Restart=always` (#872)?
- *
- * The counterpart to `plistKeepsAlive`, and narrow for the same reason: the
- * value it has to reject is the `on-failure` this file used to write, which
- * leaves Paddock down after the graceful exit `start.ts` performs on SIGTERM.
- * Anything unrecognised reads as "not the fixed shape", which at worst tells a
- * hand-edited unit's owner to re-run install.
- */
+/** Whether the unit has `Restart=always` (the older `on-failure` doesn't count). */
 export function unitKeepsAlive(text) {
     return /^Restart=always\s*$/m.test(text);
 }
-/** Read `ExecStart=` back out of an installed unit, split into an argv. */
-export function parseUnitArgv(text) {
-    const m = /^ExecStart=(.*)$/m.exec(text);
-    if (m === null)
-        return [];
-    return execWords(m[1].trim());
-}
-/**
- * What a `systemctl` failure means, in the manager's own words where it has any.
- *
- * The `status === null` branch is the one QA found: `spawnSync` reports a
- * missing binary that way, with no output at all, so the message was
- * `systemctl --user enable --now failed (exit null).` and then a blank line —
- * which tells someone on a container with no systemd nothing whatsoever. That
- * is also the single likeliest way this command fails on a machine it was never
- * going to work on.
- */
-export function systemctlFailure(args, r) {
+/** What a `systemctl` failure means, in the manager's words where it has any. */
+export function systemctlFailure(id, args, r) {
+    // spawnSync reports a missing binary as status null with no output, which would print nothing useful.
     if (r.status === null || r.status === 127) {
-        return ("systemctl is not available, so Paddock cannot install a service here.\n" +
-            "It needs systemd's per-user instance (`systemctl --user`) — a container " +
-            "or a non-systemd distribution has none.\n" +
-            "Run `paddock serve` in a terminal, or keep it up with whatever this " +
-            "machine uses.");
+        return (`systemctl isn't available, so ${id.name} can't install a service here: it needs systemd's per-user instance ` +
+            `(\`systemctl --user\`), which a container or a distribution without systemd doesn't have. Run \`${id.tool} serve\` ` +
+            'in a terminal instead, or keep it running with whatever this machine uses.');
     }
     if (/Failed to connect to (user scope )?bus|DBUS_SESSION_BUS_ADDRESS|XDG_RUNTIME_DIR/.test(r.stderr)) {
-        return (`cannot reach systemd's per-user instance (${r.stderr.trim()}).\n` +
-            "Run this from a login session, and check that $XDG_RUNTIME_DIR is set " +
-            "(usually /run/user/$(id -u)).");
+        return `can't reach systemd's per-user instance (${r.stderr.trim()}). Run this from a login session, with $XDG_RUNTIME_DIR set (usually /run/user/$(id -u)).`;
     }
-    return (`systemctl ${args.join(" ")} failed (exit ${String(r.status)}).\n` +
-        `${r.stderr || r.stdout}`.trim());
-}
-/** Run a `systemctl` and turn a non-zero exit into something actionable. */
-function systemctlOrThrow(run, args) {
-    const r = run("systemctl", args);
-    if (r.status === 0)
-        return;
-    throw new Error(systemctlFailure(args, r));
+    return `systemctl ${args.join(' ')} failed (exit ${String(r.status)}): ${`${r.stderr || r.stdout}`.trim()}`;
 }
-export function createSystemdBackend(run, homeDir, xdgConfigHome) {
-    // Both forwarded, neither defaulted here: `unitPath` owns the precedence, and
-    // defaulting `homeDir` to `os.homedir()` at this layer would collapse "the
-    // caller named a home" into "the caller named nothing" — the exact
-    // distinction that precedence turns on.
-    const file = unitPath(homeDir, xdgConfigHome);
+export function createSystemd(id, o) {
+    const { run } = o;
+    const file = unitPath(id, o.homeDir, o.xdgConfigHome);
+    const systemctl = (...args) => {
+        const r = run('systemctl', ['--user', ...args]);
+        if (r.status !== 0)
+            throw new Error(systemctlFailure(id, ['--user', ...args], r));
+    };
+    const isActive = () => run('systemctl', ['--user', 'is-active', id.unit]).stdout.trim() === 'active';
     return {
-        platform: "linux",
+        platform: 'linux',
         unitPath: file,
-        label: SYSTEMD_UNIT,
+        label: id.unit,
+        kind: 'a systemd --user service',
         install(spec) {
-            // Asked BEFORE the unit is overwritten, because the answer decides whether a restart is
-            // needed below and the file is about to stop describing what is running.
-            const wasActive = fs.existsSync(file) && run("systemctl", ["--user", "is-active", SYSTEMD_UNIT]).stdout.trim() === "active";
+            // Asked before the unit is overwritten, while it still describes what's running.
+            const wasActive = fs.existsSync(file) && isActive();
             fs.mkdirSync(path.dirname(file), { recursive: true });
             fs.mkdirSync(spec.workingDirectory, { recursive: true });
-            // systemd creates the log FILE for `append:` but not its directory, and a
-            // missing directory fails the unit at start with the server never having
-            // run — no output anywhere, because the thing that would have written it
-            // is what failed.
             fs.mkdirSync(path.dirname(spec.logPath), { recursive: true });
-            fs.writeFileSync(file, renderUnit(spec), "utf8");
-            // Without this the manager keeps serving the previous unit from cache and
-            // an "upgrade" silently changes nothing.
-            run("systemctl", ["--user", "daemon-reload"]);
-            const args = ["--user", "enable", "--now", SYSTEMD_UNIT];
-            const enabled = run("systemctl", args);
-            if (enabled.status !== 0)
-                throw new Error(systemctlFailure(args, enabled));
-            // And then RESTART, but only if it was ALREADY active, because `enable --now` does nothing
-            // to a unit that is already running — systemd starts it only if it is stopped. So a
-            // reinstall over a running service wrote a new unit, left the old process serving, and
-            // reported success.
-            //
-            // That is not a theoretical gap: it is the one `paddock update`'s ROLLBACK walks into. The
-            // forward path stops the service first (SPEC §5 step 9), so `enable --now` starts the new
-            // version cleanly; the rollback runs `service install --refresh` while the FAILED version
-            // is still up, and without this the "restored" service was the broken one — which turns a
-            // clean exit 6 into an exit 7 and a machine nobody has fixed.
-            //
-            // Conditional rather than unconditional, even though `restart` would converge both states
-            // in one call: on a stopped unit that would be TWO starts milliseconds apart, and systemd's
-            // default start limit is five in ten seconds. Halving the headroom of a unit whose whole
-            // job is to come back is not worth saving a question.
-            //
-            // launchd needs no equivalent — its install is a bootout followed by a bootstrap, which
-            // already replaces a running job.
-            if (wasActive) {
-                const restartArgs = ["--user", "restart", SYSTEMD_UNIT];
-                const restarted = run("systemctl", restartArgs);
-                if (restarted.status !== 0)
-                    throw new Error(systemctlFailure(restartArgs, restarted));
-            }
+            fs.writeFileSync(file, renderUnit(id, spec), 'utf8');
+            // Without a reload the manager keeps serving its cached copy of the old unit.
+            run('systemctl', ['--user', 'daemon-reload']);
+            systemctl('enable', '--now', id.unit);
+            // `enable --now` doesn't touch a unit that's already active: a reinstall over a running service would leave the
+            // old process serving and report success. That's the state `update`'s rollback refreshes in, while the failed
+            // version is still up. So restart, but only then: on a stopped unit it would be two starts milliseconds apart,
+            // and systemd's default limit is five starts in ten seconds.
+            if (wasActive)
+                systemctl('restart', id.unit);
         },
         uninstall() {
             const existed = fs.existsSync(file);
-            run("systemctl", ["--user", "disable", "--now", SYSTEMD_UNIT]);
+            run('systemctl', ['--user', 'disable', '--now', id.unit]);
             if (existed)
                 fs.rmSync(file, { force: true });
-            run("systemctl", ["--user", "daemon-reload"]);
+            run('systemctl', ['--user', 'daemon-reload']);
             return existed;
         },
         /**
-         * The lifecycle three (#873), which on systemd are just the verbs.
-         *
-         * None of them touches `enable`/`disable`: those decide whether Paddock
-         * comes back at your NEXT login, which is a different question from whether
-         * it is running now, and quietly answering both would make `stop` a
-         * surprise the following morning. `uninstall` is where that link is cut.
-         *
-         * `restart` re-reads the unit itself, but a `daemon-reload` first is what
-         * makes an EDITED unit take effect rather than the manager's cached copy —
-         * the same reason `install` reloads before enabling.
+         * `start` clears a failed state first: a unit that hit the start limit stays failed, and won't start, until
+         * `reset-failed`. None of the three touches enable or disable: whether it starts at the next login is a
+         * different question from whether it's running now.
          */
         start() {
-            systemctlOrThrow(run, ["--user", "start", SYSTEMD_UNIT]);
+            run('systemctl', ['--user', 'reset-failed', id.unit]);
+            systemctl('start', id.unit);
         },
         stop() {
-            systemctlOrThrow(run, ["--user", "stop", SYSTEMD_UNIT]);
+            systemctl('stop', id.unit);
         },
+        /** A reload first, so an edited unit takes effect. */
         restart() {
-            run("systemctl", ["--user", "daemon-reload"]);
-            systemctlOrThrow(run, ["--user", "restart", SYSTEMD_UNIT]);
+            run('systemctl', ['--user', 'daemon-reload']);
+            run('systemctl', ['--user', 'reset-failed', id.unit]);
+            systemctl('restart', id.unit);
         },
         status() {
             if (!fs.existsSync(file))
                 return { registered: false, running: false, argv: [], keepsAlive: true };
-            const text = fs.readFileSync(file, "utf8");
+            const text = fs.readFileSync(file, 'utf8');
             const argv = parseUnitArgv(text);
-            const active = run("systemctl", ["--user", "is-active", SYSTEMD_UNIT]);
-            const pid = run("systemctl", ["--user", "show", "-p", "MainPID", "--value", SYSTEMD_UNIT]);
-            const mainPid = pid.stdout.trim();
+            const pid = run('systemctl', ['--user', 'show', '-p', 'MainPID', '--value', id.unit]).stdout.trim();
             const logPath = parseUnitLogPath(text);
             return {
                 registered: true,
-                running: active.stdout.trim() === "active",
-                ...(mainPid !== "" && mainPid !== "0" ? { pid: mainPid } : {}),
+                running: isActive(),
+                ...(pid !== '' && pid !== '0' ? { pid } : {}),
                 argv: argv.slice(2),
                 ...(argv[0] !== undefined ? { nodePath: argv[0] } : {}),
                 ...(argv[1] !== undefined ? { cliPath: argv[1] } : {}),
@@ -318,23 +163,22 @@ export function createSystemdBackend(run, homeDir, xdgConfigHome) {
             };
         },
         /**
-         * `loginctl show-user <user> -p Linger` (SPEC §7).
-         *
-         * Parsed rather than trusted to exit codes: `loginctl` is absent in plenty
-         * of containers and exits non-zero for a user logind has no record of, and
-         * neither of those is "linger is off". An unparseable answer is reported as
-         * unknown, which prints nothing — the alternative is handing a `sudo`
-         * command to someone whose machine has no `loginctl` to run it with.
+         * `loginctl show-user <user> -p Linger`, parsed rather than trusted to its exit code: no `loginctl` (a container)
+         * or no record of the user isn't "off". An answer it can't read is unknown, and the tool says nothing.
          */
         linger() {
-            const user = os.userInfo().username;
-            const r = run("loginctl", ["show-user", user, "-p", "Linger"]);
+            let user = o.user;
+            try {
+                user ??= os.userInfo().username;
+            }
+            catch {
+                user = process.env.USER;
+            }
+            if (user === undefined)
+                return { applies: true };
+            const r = run('loginctl', ['show-user', user, '-p', 'Linger']);
             const m = /Linger=(yes|no)/i.exec(`${r.stdout}${r.stderr}`);
-            return {
-                applies: true,
-                user,
-                ...(m !== null ? { enabled: m[1].toLowerCase() === "yes" } : {}),
-            };
+            return { applies: true, user, ...(m !== null ? { enabled: m[1].toLowerCase() === 'yes' } : {}) };
         },
     };
 }

package/packages/server/dist/cli/update/health.d.ts

@@ -0,0 +1,48 @@
+/** What `/api/health` said. */
+export interface HealthAnswer {
+    ok: boolean;
+    /** The running server's version; absent from a tool that predates the contract. */
+    version?: string;
+}
+export interface HealthOptions {
+    /** The server's base URL: `http://127.0.0.1:7233`. */
+    url: string;
+    fetch?: typeof globalThis.fetch;
+}
+/** Asks once. Undefined means nothing answered (with a 2xx), which is an answer, not an error. */
+export declare function fetchHealth(o: HealthOptions & {
+    timeoutMs?: number;
+}): Promise<HealthAnswer | undefined>;
+export interface WaitOptions extends HealthOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * How long to wait before saying it didn't answer. Generous, because it's only spent when something is wrong, and
+ * too short a wait says "didn't start" about a service that's only slow to boot.
+ */
+export declare const READY_TIMEOUT_MS = 20000;
+/** Polls until `/api/health` answers 2xx, or the time runs out. Each request has its own abort. */
+export declare function waitForReady(o: WaitOptions): Promise<'ready' | 'timeout'>;
+/** What `waitForVersion` found (SPEC §5 step 12). */
+export type HealthVerdict = {
+    state: 'ok';
+    version: string;
+}
+/** Something answers, but as another version. */
+ | {
+    state: 'wrong-version';
+    version: string;
+} | {
+    state: 'no-answer';
+};
+/**
+ * Polls until `/api/health` reports exactly `version`. "It answers" isn't enough: the old server still shutting
+ * down, another instance on the port, and a supervisor that brought the old unit back all answer, and those are the
+ * failures a rollback is for. A wrong version and no answer are kept apart because they read differently in a report.
+ */
+export declare function waitForVersion(o: WaitOptions & {
+    version: string;
+}): Promise<HealthVerdict>;

package/packages/server/dist/cli/update/health.js

@@ -0,0 +1,64 @@
+// From edspencer/cli-contract reference/health.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// Asking `/api/health` (SPEC §8): once, until it answers, or until it answers with one version. The service commands
+// wait on it before they claim success, and `update` waits for the target version (SPEC §5 step 12). It's an HTTP
+// request to the URL a person would open, not a pid lookup: launchd and systemd both report a crash-looping job as
+// running for most of each restart interval. Node built-ins only.
+const healthUrl = (base) => new URL('/api/health', base).toString();
+/** Asks once. Undefined means nothing answered (with a 2xx), which is an answer, not an error. */
+export async function fetchHealth(o) {
+    try {
+        const res = await (o.fetch ?? globalThis.fetch)(healthUrl(o.url), { signal: AbortSignal.timeout(o.timeoutMs ?? 2000) });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        return { ok: body.ok === true, ...(typeof body.version === 'string' ? { version: body.version } : {}) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * How long to wait before saying it didn't answer. Generous, because it's only spent when something is wrong, and
+ * too short a wait says "didn't start" about a service that's only slow to boot.
+ */
+export const READY_TIMEOUT_MS = 20_000;
+const defaults = (o) => ({
+    timeoutMs: o.timeoutMs ?? READY_TIMEOUT_MS,
+    intervalMs: o.intervalMs ?? 250,
+    now: o.now ?? (() => Date.now()),
+    sleep: o.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))),
+});
+/** Polls until `/api/health` answers 2xx, or the time runs out. Each request has its own abort. */
+export async function waitForReady(o) {
+    const { timeoutMs, intervalMs, now, sleep } = defaults(o);
+    const deadline = now() + timeoutMs;
+    for (;;) {
+        const answer = await fetchHealth({ ...o, timeoutMs: Math.max(250, Math.min(2000, deadline - now())) });
+        if (answer !== undefined)
+            return 'ready';
+        if (deadline - now() <= 0)
+            return 'timeout';
+        await sleep(intervalMs);
+    }
+}
+/**
+ * Polls until `/api/health` reports exactly `version`. "It answers" isn't enough: the old server still shutting
+ * down, another instance on the port, and a supervisor that brought the old unit back all answer, and those are the
+ * failures a rollback is for. A wrong version and no answer are kept apart because they read differently in a report.
+ */
+export async function waitForVersion(o) {
+    const { timeoutMs, intervalMs, now, sleep } = defaults(o);
+    const deadline = now() + timeoutMs;
+    let last;
+    for (;;) {
+        const answer = await fetchHealth({ ...o, timeoutMs: Math.max(250, Math.min(2000, deadline - now())) });
+        if (answer?.version !== undefined) {
+            if (answer.version === o.version)
+                return { state: 'ok', version: o.version };
+            last = answer.version;
+        }
+        if (deadline - now() <= 0)
+            return last !== undefined ? { state: 'wrong-version', version: last } : { state: 'no-answer' };
+        await sleep(intervalMs);
+    }
+}