@edspencer/paddock 0.80.0 → 0.82.0

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

@@ -33,6 +33,8 @@ import { createLaunchdBackend } from "./launchd.js";
 import { createSystemdBackend } from "./systemd.js";
 import { missingPaths } from "./path-env.js";
 import { DEFAULT_LOG_LINES, followFile, sizeOf, tailFile } from "./logs.js";
+import { readLiveRuntimeFile } from "../../runtime-file.js";
+import { updateSummary } from "../update/update-check.js";
 import { waitForReady, fetchHealth, READY_TIMEOUT_LABEL, } from "./ready.js";
 /**
  * Pick a backend, or explain why there isn't one.
@@ -63,8 +65,52 @@ function resolveDataDir(opts, ctx) {
     }
     return { dataDir: defaultDataDir(ctx.homeDir), explicit: undefined };
 }
-function specFor(opts, ctx) {
-    const { dataDir, explicit } = resolveDataDir(opts, ctx);
+/** The value of a flag in a recorded argument vector, or undefined. */
+function argValue(argv, names) {
+    for (let i = 0; i < argv.length; i++) {
+        if (names.includes(argv[i]) && argv[i + 1] !== undefined)
+            return argv[i + 1];
+    }
+    return undefined;
+}
+/**
+ * The settings an EXISTING unit carries, as if they had been typed
+ * (`service install --refresh`, SPEC §1 and §5 step 11).
+ *
+ * This is what makes a reinstall idempotent rather than a reset. A unit
+ * installed with `--port 9000 --data-dir /srv/paddock` must come back on 9000
+ * pointing at /srv/paddock — and `update` is precisely the caller that has no
+ * way to know those values, because it runs the NEW version's CLI in a shell
+ * that never typed them.
+ *
+ * Flags still win, so `service install --refresh --port 7300` moves the port.
+ * The ENVIRONMENT deliberately does not: `resolveDataDir` normally lets
+ * `PADDOCK_DATA_DIR` stand in for `--data-dir`, which would be wrong here —
+ * the refresh is a faithful re-render of a unit, and inheriting the updating
+ * shell's data dir would silently repoint somebody's service at a different
+ * instance. A unit with no recorded `--data-dir` keeps having none, which is
+ * how it stays the same `~/.paddock` a bare `paddock` reaches.
+ */
+function inherit(opts, state) {
+    const port = argValue(state.argv, ["--port", "-p"]);
+    const host = argValue(state.argv, ["--host"]);
+    const dataDir = argValue(state.argv, ["--data-dir", "-d"]);
+    return {
+        ...opts,
+        ...(opts.port === undefined && port !== undefined ? { port } : {}),
+        ...(opts.host === undefined && host !== undefined ? { host } : {}),
+        ...(opts.dataDir === undefined && dataDir !== undefined ? { dataDir } : {}),
+        verbose: opts.verbose || state.argv.includes("--verbose"),
+    };
+}
+function specFor(opts, ctx, 
+/** Set on a `--refresh`: the data dir comes from the unit, not the environment. */
+fromUnit = false) {
+    const { dataDir, explicit } = fromUnit
+        ? opts.dataDir !== undefined
+            ? { dataDir: path.resolve(opts.dataDir), explicit: path.resolve(opts.dataDir) }
+            : { dataDir: defaultDataDir(ctx.homeDir), explicit: undefined }
+        : resolveDataDir(opts, ctx);
     const spec = buildSpec({
         nodePath: ctx.nodePath,
         scriptPath: ctx.scriptPath,
@@ -136,8 +182,27 @@ function lingerNote(linger) {
 async function install(opts, ctx, backend) {
     if (isNpxPath(ctx.packageRoot))
         throw new CliError(NPX_REFUSAL);
-    const { spec, dataDir } = specFor(opts, ctx);
+    // `--refresh` (SPEC §5 step 11): re-render an EXISTING unit, keeping what it
+    // records. With nothing installed there is nothing to refresh — exit 4, the
+    // same code every other command that needs a unit returns, rather than
+    // quietly performing a first install from defaults. That distinction is the
+    // whole reason the flag exists: `update` runs this through the new version's
+    // CLI, and a silent fallback would move a `--port 9000` service to 7233 on
+    // the one run nobody is watching.
+    const refreshing = opts.refresh === true;
+    let existing;
+    if (refreshing) {
+        existing = backend.status();
+        if (!existing.registered) {
+            console.log(notInstalled(backend));
+            return EXIT.notInstalled;
+        }
+    }
+    const { spec, dataDir } = specFor(existing !== undefined ? inherit(opts, existing) : opts, ctx, refreshing);
     const url = `http://${hostFromArgv(spec.args)}:${portFromArgv(spec.args)}`;
+    if (refreshing) {
+        console.log(`\n  Re-writing ${backend.unitPath}\n  Keeping: paddock ${spec.args.join(" ")}`);
+    }
     console.log(installProgress(backend));
     backend.install(spec);
     // The unit is written and the supervisor has accepted it. That is NOT the
@@ -251,6 +316,11 @@ export function installedVersionOf(cliPath) {
         dir = parent;
     }
 }
+/** `{ update }` when there is a recent check to repeat, and `{}` otherwise. */
+function withUpdate(home) {
+    const summary = updateSummary(home);
+    return summary !== undefined ? { update: summary } : {};
+}
 async function buildStatus(ctx, backend) {
     const state = backend.status();
     const base = {
@@ -277,6 +347,7 @@ async function buildStatus(ctx, backend) {
             node: null,
             cli: null,
             linger: lingerValue,
+            ...withUpdate(path.resolve(ctx.envDataDir ?? defaultDataDir(ctx.homeDir))),
             warnings: [],
         };
     }
@@ -318,6 +389,7 @@ async function buildStatus(ctx, backend) {
         node: state.nodePath ?? null,
         cli: state.cliPath ?? null,
         linger: lingerValue,
+        ...withUpdate(dataDir),
         warnings,
     };
 }
@@ -354,6 +426,12 @@ async function status(opts, ctx, backend) {
             "  paddock service install     register it and start it now",
             "",
         ].join("\n"));
+        // The notice belongs here too. Found in QA: it was printed only on the
+        // installed path, so a machine with no service got `update` in `--json`
+        // and silence in the prose — the exact `--json`-disagrees-with-the-text rot
+        // that one StatusReport is supposed to prevent. A newer version is worth
+        // knowing about whether or not a unit exists.
+        noteUpdate(report);
         return EXIT.notInstalled;
     }
     const versions = report.runningVersion !== null && report.runningVersion !== report.installedVersion
@@ -387,8 +465,33 @@ async function status(opts, ctx, backend) {
         ...report.warnings.flatMap((w) => ["", `  ⚠ ${w}`]),
         "",
     ].join("\n"));
+    // The update notice goes to STDERR, and only ever repeats the cache (SPEC
+    // §3). stderr because it is prose about something other than what was asked
+    // for, and because that keeps every byte of stdout under the `--json`
+    // discipline's one rule rather than two.
+    noteUpdate(report);
     return statusExit(report);
 }
+/**
+ * Repeat the cached update answer on stderr, when there is one worth repeating
+ * (SPEC §3).
+ *
+ * Nothing is fetched here. The `Run:` line is the plain `paddock update`
+ * rather than §6's per-install variant, because working that out needs the
+ * install method and the target's tag — and `status` has deliberately not
+ * asked the registry, so it has neither. Anyone whose install cannot update
+ * itself gets the right command from `update --check`, which has.
+ */
+function noteUpdate(report) {
+    const update = report.update;
+    if (update === undefined || !update.updateAvailable)
+        return;
+    console.error("");
+    const have = report.runningVersion ?? report.installedVersion;
+    console.error(`  ${update.latest} is available${have !== null && have !== undefined ? ` (you have ${have})` : ""}.`);
+    console.error("    Run: paddock update");
+    console.error(`    Checked: ${update.checkedAt}`);
+}
 /** The exit code a report means (SPEC §2). */
 function statusExit(report) {
     if (!report.installed)
@@ -432,7 +535,7 @@ function notInstalled(backend) {
  * `ThrottleInterval`, and `launchctl print` says `running` for most of that
  * window). The wait is what makes the last line true.
  */
-async function startOrRestart(action, ctx, backend) {
+async function startOrRestart(action, opts, ctx, backend) {
     const before = backend.status();
     if (!before.registered) {
         console.log(notInstalled(backend));
@@ -443,6 +546,14 @@ async function startOrRestart(action, ctx, backend) {
         console.log(`\n  Paddock is already running${pid(before)}.\n\n  URL:  ${url}\n`);
         return EXIT.ok;
     }
+    // A restart stops the instance first, so it asks the same question `stop`
+    // asks (SPEC §1): refuse with 75 unless `--force`. `start` does not — there
+    // is nothing running for it to cut short, and asking would be theatre.
+    if (action === "restart") {
+        const refused = await busyCheck(action, opts, ctx, before);
+        if (refused !== null)
+            return refused;
+    }
     console.log(`\n  ${action === "start" ? "Starting" : "Restarting"} Paddock…`);
     if (action === "start")
         backend.start();
@@ -469,8 +580,26 @@ async function startOrRestart(action, ctx, backend) {
     // caller — often an Ansible task — has no other way to find out.
     return readiness === "ready" ? EXIT.ok : EXIT.failure;
 }
+/**
+ * The busy check, asked of the instance the UNIT describes (SPEC §1, §4).
+ *
+ * `home` is `dataDirOf(state, ctx)` — the unit's own data dir, not whatever
+ * `--data-dir` this invocation carries. Same rule as `status` and `logs`
+ * (#824): the instance about to be stopped is the one the unit points at, and
+ * reading `runtime.json` from somewhere else would ask a different Paddock
+ * whether this one is busy.
+ *
+ * Returns null to go ahead, or the code to return (75).
+ */
+async function busyCheck(action, opts, ctx, state) {
+    const guard = ctx.guardBusy ?? (await import("../busy-command.js")).guardServiceBusy;
+    return guard(action, dataDirOf(state, ctx), {
+        ...(opts.force === true ? { force: true } : {}),
+        ...(opts.json === true ? { json: true } : {}),
+    });
+}
 /** `stop` (#873): put it down, leave it installed. */
-function stop(backend) {
+async function stop(opts, ctx, backend) {
     const state = backend.status();
     if (!state.registered) {
         console.log(notInstalled(backend));
@@ -480,6 +609,12 @@ function stop(backend) {
         console.log(`\n  Paddock is already stopped.\n  Unit: ${backend.unitPath}\n`);
         return EXIT.ok;
     }
+    // Refuse with 75 if it is in the middle of something, unless --force (SPEC
+    // §4). Deliberately AFTER the two cases above: an unit that is not there, or
+    // a service already stopped, has no instance to ask and no work to cut short.
+    const refused = await busyCheck("stop", opts, ctx, state);
+    if (refused !== null)
+        return refused;
     backend.stop();
     console.log([
         "",
@@ -542,19 +677,85 @@ async function logs(opts, ctx, backend) {
  * never `process.exit()`, which truncates piped output mid-write.
  */
 export async function runService(action, opts, ctx) {
+    // `--force` is rejected on every action but `stop` and `restart` — in
+    // `parseCommand`, once, for every verb. See the note there.
     const backend = backendFor(ctx);
     if (action === "install")
         return install(opts, ctx, backend);
     if (action === "uninstall")
         return uninstall(ctx, backend);
     if (action === "start" || action === "restart")
-        return startOrRestart(action, ctx, backend);
+        return startOrRestart(action, opts, ctx, backend);
     if (action === "stop")
-        return stop(backend);
+        return stop(opts, ctx, backend);
     if (action === "logs")
         return logs(opts, ctx, backend);
     return status(opts, ctx, backend);
 }
+/**
+ * What `paddock update` needs to know and do about the service (SPEC §5).
+ *
+ * Built here rather than in the update module so that everything which reads a
+ * unit file stays in one place: `update` gets the same answer `status` and
+ * `logs` get, from the same backend, including the #824 rule that the instance
+ * in question is the one the UNIT describes and not whatever `--data-dir` the
+ * invocation carries.
+ *
+ * Returns `home` too, which is the data dir `update.lock` and
+ * `update-check.json` go in. It has to be the unit's: the cache's reader is
+ * `service status`, which looks in the unit's data dir, so writing it anywhere
+ * else would be writing a file nothing reads.
+ */
+export function updateServiceHooks(ctx) {
+    const backend = backendFor(ctx);
+    const first = backend.status();
+    const home = first.registered
+        ? dataDirOf(first, ctx)
+        : path.resolve(ctx.envDataDir ?? defaultDataDir(ctx.homeDir));
+    const inspect = () => {
+        const state = backend.status();
+        if (!state.registered) {
+            // No unit. A foreground `paddock serve` is still worth finding, because
+            // SPEC §5's "without a service" path has to be able to say "restart
+            // Paddock to use the new version" — and `runtime.json` is the only honest
+            // way to find it (no guessing at a default port, the busy client's rule).
+            const live = readLiveRuntimeFile(home);
+            return {
+                installed: false,
+                running: live !== null,
+                ...(live !== null ? { url: live.url } : {}),
+            };
+        }
+        return {
+            installed: true,
+            running: state.running,
+            url: urlOf(state),
+            log: logPathOf(state, dataDirOf(state, ctx)),
+        };
+    };
+    return {
+        installed: first.registered,
+        home,
+        hooks: {
+            inspect,
+            stop: () => backend.stop(),
+            // The NEW version's CLI writes the unit (SPEC §5 step 11). Run with the
+            // interpreter we are running, not the bin shim: the shim's shebang has to
+            // find `node` on PATH, and under a version manager there may not be one.
+            refresh: (cliPath) => {
+                const run = ctx.run ?? spawnRunner;
+                return run(process.execPath, [cliPath, "service", "install", "--refresh"]);
+            },
+            tail: (lines) => {
+                const state = backend.status();
+                if (!state.registered)
+                    return "";
+                const file = logPathOf(state, dataDirOf(state, ctx));
+                return fs.existsSync(file) ? tailFile(file, lines) : "";
+            },
+        },
+    };
+}
 /** Exported for the entrypoint's context assembly, and for tests. */
 export { serviceDir, isNpxPath };
 /** Best-effort home dir; `os.homedir()` throws on a machine with no passwd entry. */

package/packages/server/dist/cli/service/launchd.d.ts

@@ -75,4 +75,18 @@ export declare function parseLaunchctlPrint(out: string): {
     running: boolean;
     pid?: string;
 };
-export declare function createLaunchdBackend(run: Runner, homeDir?: string): ServiceBackend;
+/**
+ * Block this thread for `ms`.
+ *
+ * The backend's {@link Runner} is synchronous (`execFileSync`) and so is every
+ * `ServiceBackend` method, so the wait has to be too — making `install` async
+ * would ripple through the whole service CLI for a sleep. `Atomics.wait` on a
+ * throwaway buffer is the built-in way to do it; `setTimeout` cannot help here
+ * and spinning on `Date.now()` would burn a core.
+ *
+ * Injectable because the unit tests drive the retry path with a fake runner
+ * that fails every attempt: with the real sleep, pinning the retry count would
+ * cost three seconds per case.
+ */
+export declare function sleepSync(ms: number): void;
+export declare function createLaunchdBackend(run: Runner, homeDir?: string, sleep?: (ms: number) => void): ServiceBackend;

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

@@ -188,8 +188,107 @@ function target() {
 function domain() {
     return `gui/${process.getuid?.() ?? 0}`;
 }
-export function createLaunchdBackend(run, homeDir = os.homedir()) {
+/**
+ * ## The bootout/bootstrap race (#984)
+ *
+ * `launchctl bootout` returns as soon as launchd has ACCEPTED the request, not
+ * once the job has gone. Every sequence below that boots out and then
+ * bootstraps the same label therefore races launchd's own teardown, and when it
+ * loses, `bootstrap` fails with:
+ *
+ * ```
+ * launchctl bootstrap failed (exit 5): Input/output error
+ * ```
+ *
+ * Exit 5 is `EIO`, which is launchd's generic "I cannot do that right now" and
+ * the classic symptom of this race. It is timing-dependent, so it passes
+ * locally and on a PR and then fails on a release: Paddock 0.80.0's first
+ * release run failed exactly here, in CI's real-launchd job, on
+ * `paddock service restart`.
+ *
+ * Both halves of the fix are needed, and neither is sufficient:
+ *
+ *  - **Wait for the job to go.** After a bootout, poll `launchctl print` until
+ *    it reports the label gone (a non-zero exit), up to {@link BOOTOUT_POLLS}
+ *    times. That removes the race in the case we caused it.
+ *  - **Retry the bootstrap.** A bootout we did NOT issue can still be in
+ *    flight — `service start` after a separate process's `service stop`, or a
+ *    login racing a logout — and there is nothing to poll for there, because
+ *    from this process's point of view the job was already gone. So a
+ *    bootstrap that fails with a race code is retried with a short backoff.
+ *
+ * Timing out the poll is not an error: the retry is the backstop, and a job
+ * that will not go is a real failure the bootstrap reports in its own words.
+ */
+const BOOTOUT_POLLS = 40;
+const BOOTOUT_POLL_MS = 250; // 40 × 250ms = 10s
+const BOOTSTRAP_ATTEMPTS = 6;
+const BOOTSTRAP_BACKOFF_MS = 500;
+/**
+ * launchctl exits that mean "try again", as opposed to "no".
+ *
+ * `5` is `EIO`, what the release failure printed. `37` is launchd's "operation
+ * already in progress", which is the same race seen from the other side: the
+ * bootout is still being processed. Anything else — a malformed plist, a label
+ * genuinely already loaded, a permission problem — is reported, not retried,
+ * because retrying it only delays the message by three seconds.
+ */
+const BOOTSTRAP_RACE_CODES = new Set([5, 37]);
+/**
+ * Block this thread for `ms`.
+ *
+ * The backend's {@link Runner} is synchronous (`execFileSync`) and so is every
+ * `ServiceBackend` method, so the wait has to be too — making `install` async
+ * would ripple through the whole service CLI for a sleep. `Atomics.wait` on a
+ * throwaway buffer is the built-in way to do it; `setTimeout` cannot help here
+ * and spinning on `Date.now()` would burn a core.
+ *
+ * Injectable because the unit tests drive the retry path with a fake runner
+ * that fails every attempt: with the real sleep, pinning the retry count would
+ * cost three seconds per case.
+ */
+export function sleepSync(ms) {
+    if (ms <= 0)
+        return;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+export function createLaunchdBackend(run, homeDir = os.homedir(), sleep = sleepSync) {
     const file = plistPath(homeDir);
+    /**
+     * Boot the job out and wait until launchd agrees it has gone — see the race
+     * note above. The bootout's own result is deliberately not inspected: "there
+     * was no previous service" is the expected case on a first install, and a
+     * bootout that genuinely failed shows up as a job that is still there, which
+     * is what the poll below is looking at anyway.
+     */
+    const bootoutAndWait = () => {
+        run("launchctl", ["bootout", target()]);
+        // Counted, not timed: an injected no-op sleep has to terminate the loop
+        // too, and a wall-clock deadline with a no-op sleep is a ten-second spin.
+        for (let poll = 1; poll <= BOOTOUT_POLLS; poll++) {
+            // A non-zero `print` is launchd saying it has never heard of the label,
+            // which is precisely the state `bootstrap` needs.
+            if (run("launchctl", ["print", target()]).status !== 0)
+                return;
+            if (poll < BOOTOUT_POLLS)
+                sleep(BOOTOUT_POLL_MS);
+        }
+    };
+    /** Bootstrap the plist, retrying the race codes. Throws with launchctl's own words. */
+    const bootstrapOrThrow = () => {
+        for (let attempt = 1;; attempt++) {
+            // NOT `load`/`unload`: those are the legacy API, and on a modern macOS
+            // they are shims over this one that report success in cases where it
+            // reports the actual error.
+            const boot = run("launchctl", ["bootstrap", domain(), file]);
+            if (boot.status === 0)
+                return;
+            if (attempt >= BOOTSTRAP_ATTEMPTS || !BOOTSTRAP_RACE_CODES.has(boot.status ?? -1)) {
+                throw new Error(launchctlFailure("bootstrap", boot));
+            }
+            sleep(BOOTSTRAP_BACKOFF_MS);
+        }
+    };
     return {
         platform: "darwin",
         unitPath: file,
@@ -202,16 +301,12 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
             fs.mkdirSync(path.dirname(spec.logPath), { recursive: true });
             fs.writeFileSync(file, renderPlist(spec), "utf8");
             // `bootstrap` fails outright if the label is already loaded, so a
-            // reinstall has to unload first. A first install has nothing to unload,
-            // and says so on stderr — ignored rather than reported, because "there
-            // was no previous service" is the expected case, not a problem.
-            run("launchctl", ["bootout", target()]);
-            // NOT `load`/`unload`: those are the legacy API, and on a modern macOS
-            // they are shims over this one that report success in cases where it
-            // reports the actual error.
-            const boot = run("launchctl", ["bootstrap", domain(), file]);
-            if (boot.status !== 0)
-                throw new Error(launchctlFailure("bootstrap", boot));
+            // reinstall has to unload first — and has to WAIT for that, which is what
+            // `bootoutAndWait` is for (see the race note). A first install has
+            // nothing to unload, and says so on stderr: ignored rather than reported,
+            // because "there was no previous service" is the expected case.
+            bootoutAndWait();
+            bootstrapOrThrow();
             // `RunAtLoad` should already have started it; `kickstart -k` makes that
             // true rather than probable, and is the same command a later restart uses.
             run("launchctl", ["kickstart", "-k", target()]);
@@ -230,11 +325,13 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
          * Paddock is not merely idle, it is absent from the domain — and `start` on
          * a label launchd has never heard of fails. Bootstrapping is also what a
          * login does, so `service start` and the next login take the same path.
+         *
+         * No bootout to wait on here, but the retry in `bootstrapOrThrow` still
+         * earns its keep: the `stop` that booted it out may have been a different
+         * `paddock` process seconds ago, and launchd may not have finished with it.
          */
         start() {
-            const boot = run("launchctl", ["bootstrap", domain(), file]);
-            if (boot.status !== 0)
-                throw new Error(launchctlFailure("bootstrap", boot));
+            bootstrapOrThrow();
             run("launchctl", ["kickstart", target()]);
         },
         /**
@@ -263,12 +360,13 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
          * service that is stopped. This sequence is identical to `install`'s minus
          * writing the plist, which also gives `restart` the property the issue asks
          * for — the unit is re-read on the way up, so an edited plist takes effect.
+         *
+         * This is the sequence that failed Paddock 0.80.0's release run: bootout
+         * and bootstrap back to back, with nothing between them. See the race note.
          */
         restart() {
-            run("launchctl", ["bootout", target()]);
-            const boot = run("launchctl", ["bootstrap", domain(), file]);
-            if (boot.status !== 0)
-                throw new Error(launchctlFailure("bootstrap", boot));
+            bootoutAndWait();
+            bootstrapOrThrow();
             run("launchctl", ["kickstart", "-k", target()]);
         },
         status() {

package/packages/server/dist/cli/service/ready.d.ts

@@ -81,3 +81,33 @@ export declare const READY_TIMEOUT_LABEL = "20 seconds";
  * would park here well past `timeoutMs`.
  */
 export declare function waitForReady(opts: ReadyOptions): Promise<Readiness>;
+/** What {@link waitForVersion} concluded (CLI contract SPEC §5 step 12). */
+export type VersionVerdict = {
+    state: "ok";
+    version: string;
+}
+/** Something answers, and it is not the version we were waiting for. */
+ | {
+    state: "wrong-version";
+    version: string;
+} | {
+    state: "no-answer";
+};
+/**
+ * Poll until `/api/health` reports exactly `version` (SPEC §5 step 12).
+ *
+ * The version is the point, and it is what makes `update`'s health check mean
+ * something. "The URL answers" is satisfied by the OLD server that has not
+ * finished shutting down, by a sibling instance on the same port, and by a
+ * supervisor that restarted the old unit because the new one crashed — all
+ * three of which are exactly the failures step 13's rollback exists for. An
+ * update that polled for a 200 would call every one of them a success.
+ *
+ * The distinction between "no answer" and "the wrong version answers" is kept
+ * because the two read completely differently in a failure report: one is a
+ * server that did not come up, the other is a server that came up as something
+ * else.
+ */
+export declare function waitForVersion(opts: ReadyOptions & {
+    version: string;
+}): Promise<VersionVerdict>;

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

@@ -99,3 +99,38 @@ export async function waitForReady(opts) {
         await sleep(intervalMs);
     }
 }
+/**
+ * Poll until `/api/health` reports exactly `version` (SPEC §5 step 12).
+ *
+ * The version is the point, and it is what makes `update`'s health check mean
+ * something. "The URL answers" is satisfied by the OLD server that has not
+ * finished shutting down, by a sibling instance on the same port, and by a
+ * supervisor that restarted the old unit because the new one crashed — all
+ * three of which are exactly the failures step 13's rollback exists for. An
+ * update that polled for a 200 would call every one of them a success.
+ *
+ * The distinction between "no answer" and "the wrong version answers" is kept
+ * because the two read completely differently in a failure report: one is a
+ * server that did not come up, the other is a server that came up as something
+ * else.
+ */
+export async function waitForVersion(opts) {
+    const { url, version, timeoutMs = READY_TIMEOUT_MS, intervalMs = DEFAULT_INTERVAL_MS, fetchImpl = fetch, now = () => Date.now(), sleep = (ms) => new Promise((r) => setTimeout(r, ms)), } = opts;
+    const deadline = now() + timeoutMs;
+    let last;
+    for (;;) {
+        const health = await fetchHealth(url, {
+            fetchImpl,
+            timeoutMs: Math.max(250, Math.min(2_000, deadline - now())),
+        });
+        if (health?.version !== undefined) {
+            if (health.version === version)
+                return { state: "ok", version };
+            last = health.version;
+        }
+        if (deadline - now() <= 0) {
+            return last !== undefined ? { state: "wrong-version", version: last } : { state: "no-answer" };
+        }
+        await sleep(intervalMs);
+    }
+}

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

@@ -224,6 +224,9 @@ export function createSystemdBackend(run, homeDir, xdgConfigHome) {
         unitPath: file,
         label: SYSTEMD_UNIT,
         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";
             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
@@ -239,6 +242,30 @@ export function createSystemdBackend(run, homeDir, xdgConfigHome) {
             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));
+            }
         },
         uninstall() {
             const existed = fs.existsSync(file);