@edspencer/paddock 0.79.1 → 0.81.0

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

@@ -31,6 +31,12 @@ export declare function plistPath(homeDir?: string): string;
  *
  * No `PADDOCK_DATA_DIR`: see `buildSpec`. One `~/.paddock` instance, reachable
  * from the service and from a terminal.
+ *
+ * `StandardOutPath` and `StandardErrorPath` name the SAME file (SPEC §7).
+ * launchd opens both in append mode, so interleaving is what a reader wants
+ * anyway — a warning and the stack trace that followed it used to land in two
+ * separate files, in an order nothing recorded. One file is also what makes
+ * `paddock service logs` one implementation across platforms.
  */
 export declare function renderPlist(spec: ServiceSpec): string;
 /**
@@ -55,6 +61,8 @@ export declare function parsePlistArgv(xml: string): string[];
  * unrecognised would silence exactly the case this exists to catch.
  */
 export declare function plistKeepsAlive(xml: string): boolean;
+/** The log file an installed plist appends to, read back from `StandardOutPath`. */
+export declare function parsePlistLogPath(xml: string): string | undefined;
 /**
  * Read liveness out of `launchctl print gui/<uid>/<label>`.
  *
@@ -67,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

@@ -77,6 +77,12 @@ function xmlEscape(s) {
  *
  * No `PADDOCK_DATA_DIR`: see `buildSpec`. One `~/.paddock` instance, reachable
  * from the service and from a terminal.
+ *
+ * `StandardOutPath` and `StandardErrorPath` name the SAME file (SPEC §7).
+ * launchd opens both in append mode, so interleaving is what a reader wants
+ * anyway — a warning and the stack trace that followed it used to land in two
+ * separate files, in an order nothing recorded. One file is also what makes
+ * `paddock service logs` one implementation across platforms.
  */
 export function renderPlist(spec) {
     const argv = [spec.nodePath, spec.scriptPath, ...spec.args];
@@ -100,9 +106,9 @@ ${strings}
     <key>WorkingDirectory</key>
     <string>${xmlEscape(spec.workingDirectory)}</string>
     <key>StandardOutPath</key>
-    <string>${xmlEscape(spec.stdoutPath)}</string>
+    <string>${xmlEscape(spec.logPath)}</string>
     <key>StandardErrorPath</key>
-    <string>${xmlEscape(spec.stderrPath)}</string>
+    <string>${xmlEscape(spec.logPath)}</string>
     <key>EnvironmentVariables</key>
     <dict>
       <key>PATH</key>
@@ -145,6 +151,17 @@ export function parsePlistArgv(xml) {
 export function plistKeepsAlive(xml) {
     return /<key>KeepAlive<\/key>\s*<true\s*\/>/.test(xml);
 }
+/** The log file an installed plist appends to, read back from `StandardOutPath`. */
+export function parsePlistLogPath(xml) {
+    const m = /<key>StandardOutPath<\/key>\s*<string>([\s\S]*?)<\/string>/.exec(xml);
+    if (m === null)
+        return undefined;
+    return m[1]
+        .replace(/&quot;/g, '"')
+        .replace(/&gt;/g, ">")
+        .replace(/&lt;/g, "<")
+        .replace(/&amp;/g, "&");
+}
 /**
  * Read liveness out of `launchctl print gui/<uid>/<label>`.
  *
@@ -171,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,
@@ -180,18 +296,17 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
         install(spec) {
             fs.mkdirSync(path.dirname(file), { recursive: true });
             fs.mkdirSync(spec.workingDirectory, { recursive: true });
+            // launchd creates neither the log file's directory nor, reliably, a log
+            // file whose parent is missing — the job just fails to spawn.
+            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()]);
@@ -210,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()]);
         },
         /**
@@ -243,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() {
@@ -260,6 +378,7 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
             const parsed = printed.status === 0
                 ? parseLaunchctlPrint(printed.stdout)
                 : { running: false, pid: undefined };
+            const logPath = parsePlistLogPath(xml);
             return {
                 registered: true,
                 running: parsed.running,
@@ -267,14 +386,15 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
                 // Strip the interpreter and script: what a reader wants from `status`
                 // is the Paddock invocation, not the absolute path to node twice.
                 argv: argv.slice(2),
+                ...(argv[0] !== undefined ? { nodePath: argv[0] } : {}),
+                ...(argv[1] !== undefined ? { cliPath: argv[1] } : {}),
+                ...(logPath !== undefined ? { logPath } : {}),
                 keepsAlive: plistKeepsAlive(xml),
             };
         },
-        logsHint(spec) {
-            return `  Logs: ${spec.stdoutPath}\n        ${spec.stderrPath}`;
-        },
-        lingerNote() {
-            return undefined;
+        /** launchd has no linger: a LaunchAgent's lifetime IS the login session. */
+        linger() {
+            return { applies: false };
         },
     };
 }

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

@@ -0,0 +1,39 @@
+/** How many lines `logs` prints when nobody says otherwise (SPEC §1). */
+export declare const DEFAULT_LOG_LINES = 50;
+/**
+ * The last `lines` lines of `file`.
+ *
+ * Only the last {@link TAIL_WINDOW} bytes are read. A service log is append-only
+ * and can reach tens of megabytes between rotations, and reading all of it to
+ * print fifty lines would make `logs` slower than the thing it is reporting on.
+ * A window that happens to start mid-line drops that partial first line rather
+ * than printing half of one.
+ */
+export declare function tailFile(file: string, lines: number): string;
+export interface FollowOptions {
+    /** Where to start reading from — normally the file's size after the tail. */
+    from: number;
+    /** Injected for tests. */
+    intervalMs?: number;
+    /** Injected for tests: return false to stop the loop. */
+    keepGoing?: () => boolean;
+    write?: (s: string) => void;
+}
+/**
+ * Print what gets appended to `file`, from `from` onwards, until the process is
+ * interrupted.
+ *
+ * Polling rather than `fs.watch`: the writer here is the supervisor's own file
+ * descriptor, and `fs.watch` on an appended-to file is unreliable across
+ * platforms (no events at all on some network filesystems, and a stream of
+ * them on others). A 400 ms poll of the size is both portable and cheap.
+ *
+ * Rotation is handled by the one case that can actually happen: the server
+ * rotates by COPY-AND-TRUNCATE (see `service-log.ts`), so the inode is stable
+ * and the size goes DOWN. Seeing that, this resets to the new start rather than
+ * reading past the end forever, which is what a naive follower does — it goes
+ * quiet after the first rotation and never recovers.
+ */
+export declare function followFile(file: string, opts: FollowOptions): Promise<void>;
+/** The file's size, or 0 if it is not there — where a follow should start. */
+export declare function sizeOf(file: string): number;

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

@@ -0,0 +1,115 @@
+/**
+ * `paddock service logs [-f] [-n <lines>]` (SPEC §1, §7).
+ *
+ * One implementation for every platform, which is the whole reason the units
+ * write to a file rather than to the journal: `journalctl --user -u paddock` on
+ * Linux and a pair of files on macOS meant "where are the logs" had two
+ * answers, neither of which Windows could ever have.
+ *
+ * Reading the tail of a file is deliberately done by hand rather than by
+ * spawning `tail`: `tail -f` is not on every box this runs on (and is `Get-
+ * Content -Wait` on the platform the contract requires us not to rule out),
+ * and shelling out would make the output depend on which `tail` won a PATH
+ * lookup.
+ */
+import fs from "node:fs";
+/** How many lines `logs` prints when nobody says otherwise (SPEC §1). */
+export const DEFAULT_LOG_LINES = 50;
+/** How much of the end of the file to read for a tail, in bytes. */
+const TAIL_WINDOW = 256 * 1024;
+/** The gap between size checks when following. */
+const FOLLOW_INTERVAL_MS = 400;
+/**
+ * The last `lines` lines of `file`.
+ *
+ * Only the last {@link TAIL_WINDOW} bytes are read. A service log is append-only
+ * and can reach tens of megabytes between rotations, and reading all of it to
+ * print fifty lines would make `logs` slower than the thing it is reporting on.
+ * A window that happens to start mid-line drops that partial first line rather
+ * than printing half of one.
+ */
+export function tailFile(file, lines) {
+    const fd = fs.openSync(file, "r");
+    try {
+        const size = fs.fstatSync(fd).size;
+        const start = Math.max(0, size - TAIL_WINDOW);
+        const length = size - start;
+        if (length === 0)
+            return "";
+        const buf = Buffer.alloc(length);
+        fs.readSync(fd, buf, 0, length, start);
+        let text = buf.toString("utf8");
+        // A window that starts mid-line: drop the fragment.
+        if (start > 0) {
+            const nl = text.indexOf("\n");
+            text = nl === -1 ? "" : text.slice(nl + 1);
+        }
+        const all = text.split("\n");
+        // A trailing newline produces a final empty element that is not a line.
+        if (all[all.length - 1] === "")
+            all.pop();
+        return all.slice(-lines).join("\n");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Print what gets appended to `file`, from `from` onwards, until the process is
+ * interrupted.
+ *
+ * Polling rather than `fs.watch`: the writer here is the supervisor's own file
+ * descriptor, and `fs.watch` on an appended-to file is unreliable across
+ * platforms (no events at all on some network filesystems, and a stream of
+ * them on others). A 400 ms poll of the size is both portable and cheap.
+ *
+ * Rotation is handled by the one case that can actually happen: the server
+ * rotates by COPY-AND-TRUNCATE (see `service-log.ts`), so the inode is stable
+ * and the size goes DOWN. Seeing that, this resets to the new start rather than
+ * reading past the end forever, which is what a naive follower does — it goes
+ * quiet after the first rotation and never recovers.
+ */
+export async function followFile(file, opts) {
+    const interval = opts.intervalMs ?? FOLLOW_INTERVAL_MS;
+    const write = opts.write ?? ((s) => process.stdout.write(s));
+    const keepGoing = opts.keepGoing ?? (() => true);
+    let offset = opts.from;
+    while (keepGoing()) {
+        await new Promise((r) => setTimeout(r, interval));
+        let size;
+        try {
+            size = fs.statSync(file).size;
+        }
+        catch {
+            // The file can vanish: an uninstall, or a rotation that renames. Wait for
+            // it to come back rather than giving up — `logs -f` is left running.
+            continue;
+        }
+        if (size < offset) {
+            // Truncated: the rotation above, or a hand-run `: > service.log`.
+            offset = 0;
+        }
+        if (size === offset)
+            continue;
+        const fd = fs.openSync(file, "r");
+        try {
+            const length = size - offset;
+            const buf = Buffer.alloc(length);
+            fs.readSync(fd, buf, 0, length, offset);
+            write(buf.toString("utf8"));
+            offset = size;
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+}
+/** The file's size, or 0 if it is not there — where a follow should start. */
+export function sizeOf(file) {
+    try {
+        return fs.statSync(file).size;
+    }
+    catch {
+        return 0;
+    }
+}

package/packages/server/dist/cli/service/path-env.d.ts

@@ -0,0 +1,27 @@
+/** PATH entries that belong to one shell session or one npm invocation. */
+export declare const PER_SHELL_PATTERNS: readonly RegExp[];
+/** Where the usual tools live, after the inherited PATH. Only existing ones are kept. */
+export declare const SYSTEM_DIRS: readonly string[];
+export interface ServicePathOptions {
+    /** Injected for tests: "is this an existing directory?". */
+    exists?: (p: string) => boolean;
+    /** Injected for tests: the system directories to append. */
+    systemDirs?: readonly string[];
+}
+/**
+ * The job's PATH: Node's bin directory, then the usable part of `inherited`,
+ * then the system directories. De-duplicated, order preserved.
+ */
+export declare function servicePath(nodeBin: string, inherited: string | undefined, opts?: ServicePathOptions): string;
+/** `which`: the first executable called `name` on `pathVar`, or undefined. */
+export declare function which(name: string, pathVar: string, isExec?: (p: string) => boolean): string | undefined;
+/**
+ * Of `paths`, those that are no longer on disk.
+ *
+ * This is the check behind `status`'s and (from wave G) `doctor`'s "the Node it
+ * runs has gone" warning. It happens under nvm, fnm and volta the moment a Node
+ * version is uninstalled: the unit still names an absolute interpreter path,
+ * the supervisor still dutifully tries to exec it, and the failure arrives as
+ * Paddock being absent with nothing in its own logs — because it never ran.
+ */
+export declare function missingPaths(paths: readonly (string | undefined)[], exists?: (p: string) => boolean): string[];

package/packages/server/dist/cli/service/path-env.js

@@ -0,0 +1,120 @@
+/**
+ * The PATH a generated unit gives the service (SPEC §7).
+ *
+ * From edspencer/cli-contract — Local Review's `server/service/spec.ts`
+ * (`PER_SHELL_PATTERNS`, `SYSTEM_DIRS`, `servicePath`, `which`) @ spec 0.1;
+ * local changes: Paddock's own doc comments, `node:path`'s platform-aware
+ * `delimiter`/`join` instead of hard-coded `:` and `path.posix`, and a
+ * `missingFromPath` helper the CLI uses for its unit warnings. Wave C4 moves
+ * this to `reference/service/` and re-syncs.
+ *
+ * ## Why a unit cannot just inherit the installing shell's PATH
+ *
+ * Paddock used to record `process.env.PATH` verbatim. That is the PATH of one
+ * terminal at one moment, and several of its entries are *per-session*:
+ *
+ * - **fnm** puts a symlink per terminal under `fnm_multishells/<pid>_<ts>/bin`.
+ *   The directory is deleted when that shell exits — and fnm never cleans up
+ *   the stale ones, so a unit installed from an fnm shell names a `node`
+ *   directory that stops existing the moment the tab closes.
+ * - **npx** adds its own per-invocation cache; `npm run` adds `node-gyp-bin`
+ *   and the package's `node_modules/.bin`. A long-lived background job has no
+ *   business looking in any of them for `git`.
+ *
+ * So the job's PATH is rebuilt: Node's own bin directory first (so the `node`
+ * the unit runs can resolve its neighbours), then whatever of the installing
+ * shell's PATH is worth keeping, then the system directories. Entries that are
+ * relative, per-shell, or simply not there are dropped — a PATH naming
+ * directories that do not exist is how `git` goes missing at some later login,
+ * silently, with the symptom appearing in an agent's turn rather than at
+ * install time.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** PATH entries that belong to one shell session or one npm invocation. */
+export const PER_SHELL_PATTERNS = [
+    /[/\\]fnm_multishells[/\\]/, // fnm: a symlink per terminal, never cleaned up
+    /[/\\]_npx[/\\]/, // npx's per-invocation package cache
+    /[/\\]node-gyp-bin$/, // added by `npm run` for the script it is running
+    /[/\\]node_modules[/\\]\.bin$/, // likewise (and by npx): a package's tools, not the user's
+];
+/** Where the usual tools live, after the inherited PATH. Only existing ones are kept. */
+export const SYSTEM_DIRS = [
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+    "/usr/sbin",
+    "/sbin",
+];
+function isDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isExecutableFile(p) {
+    try {
+        if (!fs.statSync(p).isFile())
+            return false;
+        fs.accessSync(p, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Kept on the job's PATH: non-empty, absolute, not per-shell, and an existing directory. */
+function keep(dir, exists) {
+    if (dir === "" || !path.isAbsolute(dir))
+        return false;
+    if (PER_SHELL_PATTERNS.some((re) => re.test(dir) || re.test(`${dir}${path.sep}`)))
+        return false;
+    return exists(dir);
+}
+/**
+ * The job's PATH: Node's bin directory, then the usable part of `inherited`,
+ * then the system directories. De-duplicated, order preserved.
+ */
+export function servicePath(nodeBin, inherited, opts = {}) {
+    const exists = opts.exists ?? isDir;
+    const system = opts.systemDirs ?? SYSTEM_DIRS;
+    const out = [];
+    const add = (d) => {
+        // Trailing separators would make `/usr/bin/` and `/usr/bin` two entries.
+        const clean = d.length > 1 ? d.replace(/[/\\]+$/, "") : d;
+        if (!out.includes(clean) && keep(clean, exists))
+            out.push(clean);
+    };
+    add(nodeBin);
+    for (const d of (inherited ?? "").split(path.delimiter))
+        add(d);
+    for (const d of system)
+        add(d);
+    return out.join(path.delimiter);
+}
+/** `which`: the first executable called `name` on `pathVar`, or undefined. */
+export function which(name, pathVar, isExec = isExecutableFile) {
+    for (const dir of pathVar.split(path.delimiter)) {
+        if (dir === "")
+            continue;
+        const p = path.join(dir, name);
+        if (isExec(p))
+            return p;
+    }
+    return undefined;
+}
+/**
+ * Of `paths`, those that are no longer on disk.
+ *
+ * This is the check behind `status`'s and (from wave G) `doctor`'s "the Node it
+ * runs has gone" warning. It happens under nvm, fnm and volta the moment a Node
+ * version is uninstalled: the unit still names an absolute interpreter path,
+ * the supervisor still dutifully tries to exec it, and the failure arrives as
+ * Paddock being absent with nothing in its own logs — because it never ran.
+ */
+export function missingPaths(paths, exists = (p) => fs.existsSync(p)) {
+    return paths.filter((p) => p !== undefined && p !== "" && !exists(p));
+}

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

@@ -23,6 +23,28 @@
  */
 /** Where the poll got to when it stopped. */
 export type Readiness = "ready" | "timeout";
+/** What `/api/health` said, when it said anything (SPEC §8). */
+export interface HealthAnswer {
+    ok: boolean;
+    /** The version the RUNNING server reports. Absent from a pre-contract Paddock. */
+    version?: string;
+}
+/**
+ * Ask `<url>/api/health` once, and say what it answered.
+ *
+ * Distinct from {@link waitForReady}, which only needs a boolean and polls for
+ * it. `status` needs the body: the version in it is the only way to tell a
+ * server that is running the installed Paddock from one that has been up since
+ * before an upgrade — the single most confusing state a service can be in, and
+ * invisible from the outside until something reports both numbers.
+ *
+ * `undefined` means nothing answered. That is a real answer (exit 3), not an
+ * error, so nothing is thrown.
+ */
+export declare function fetchHealth(url: string, opts?: {
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<HealthAnswer | undefined>;
 export interface ReadyOptions {
     /** Base URL of the server, e.g. `http://127.0.0.1:7233` — no trailing slash. */
     url: string;

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

@@ -21,6 +21,36 @@
  * same claim as "it failed". Callers print it as a caveat, not an error, and
  * point at the logs.
  */
+/**
+ * Ask `<url>/api/health` once, and say what it answered.
+ *
+ * Distinct from {@link waitForReady}, which only needs a boolean and polls for
+ * it. `status` needs the body: the version in it is the only way to tell a
+ * server that is running the installed Paddock from one that has been up since
+ * before an upgrade — the single most confusing state a service can be in, and
+ * invisible from the outside until something reports both numbers.
+ *
+ * `undefined` means nothing answered. That is a real answer (exit 3), not an
+ * error, so nothing is thrown.
+ */
+export async function fetchHealth(url, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    try {
+        const res = await fetchImpl(`${url}/api/health`, {
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 2_000),
+        });
+        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 "could not confirm".
  *