@edspencer/paddock 0.80.0 → 0.81.0

package/packages/server/dist/cli/busy-command.d.ts

@@ -0,0 +1,58 @@
+import { type BusyResult, type Nouns } from "./busy.js";
+/**
+ * How each count in `/api/busy` is said in a sentence (`busy.ts` on the server
+ * decides the keys).
+ *
+ * `background` is spelled out rather than left to the default pluraliser,
+ * because "3 backgrounds are running" is not English — and because "background
+ * task" is the thing a user recognises from the running-work bar in the UI,
+ * where they watched it start.
+ */
+export declare const PADDOCK_NOUNS: Nouns;
+/**
+ * What to do about a busy answer — and for Paddock, the first thing to say is
+ * **where to run the command from**.
+ *
+ * This is the keeper-chat trap, and it is specific to Paddock and Managers
+ * among the six tools: Paddock's agents can drive Paddock. A keeper chat that
+ * runs `paddock service restart` or `paddock update` is itself one of the chat
+ * turns the answer just counted, so it will always see itself as busy — and
+ * `--force` from there does not override a mistaken reading, it kills the chat
+ * that typed it, mid-sentence, along with whatever it had not finished. The
+ * agent then has no way to report what happened, because the thing that would
+ * report it is the thing that died.
+ *
+ * So when `chat` is non-zero the advice is not "wait or use --force": it is
+ * "run this from a terminal". When the busy work is background tasks or
+ * scheduled jobs only, nobody is holding the keyboard inside the service and
+ * the ordinary advice applies.
+ */
+export declare function paddockBusyHint(result: BusyResult): string | undefined;
+/**
+ * `paddock busy [--json]` — exit 0 not busy, 75 busy, 3 nothing answering
+ * (SPEC §1, §2).
+ *
+ * The instance is found through `<data-dir>/runtime.json` and nowhere else, so
+ * this reports on the same instance `paddock serve` and `paddock config show`
+ * resolve — `resolveDataDir` in paddock.ts is the one rule all three use.
+ */
+export declare function runBusy(home: string, json: boolean): Promise<number>;
+/**
+ * The check before `service stop` and `service restart` (SPEC §1): refuse with
+ * 75 unless `--force`, which prints the same message prefixed `Overriding:` and
+ * carries on. Returns null to go ahead.
+ *
+ * `home` is the data dir of the INSTALLED unit, not whatever `--data-dir` this
+ * invocation carries — the same rule `status` and `logs` follow (#824), because
+ * the instance being stopped is the one the unit describes.
+ *
+ * Two deliberate non-refusals. Nothing answering goes ahead: there is nothing
+ * to cut short, which is also the answer for a service that is already stopped.
+ * And an instance running a Paddock from before this release has no
+ * `runtime.json`, so it reads as not running and the stop proceeds exactly as
+ * it did before — an upgrade cannot make a stop start failing.
+ */
+export declare function guardServiceBusy(action: "stop" | "restart", home: string, opts: {
+    force?: boolean;
+    json?: boolean;
+}): Promise<number | null>;

package/packages/server/dist/cli/busy-command.js

@@ -0,0 +1,108 @@
+/**
+ * Paddock's bindings for the copied busy client (`cli/busy.ts`): the nouns its
+ * message uses, the keeper-chat trap, and the two entry points — `paddock busy`
+ * and the check `service stop` / `service restart` run first (CLI contract
+ * SPEC §1, §4).
+ *
+ * Kept separate from `cli/busy.ts` so that file stays a straight copy of
+ * `reference/busy-client.ts`, which is what wave C4 re-syncs. Everything in
+ * here is Paddock-specific by definition: the contract says each tool's kinds of
+ * work are its own.
+ */
+import { EXIT } from "./exit-codes.js";
+import { createOutput } from "./output.js";
+import { guardBusy, runBusyCommand, } from "./busy.js";
+import { PADDOCK_NAME } from "../version.js";
+/**
+ * How each count in `/api/busy` is said in a sentence (`busy.ts` on the server
+ * decides the keys).
+ *
+ * `background` is spelled out rather than left to the default pluraliser,
+ * because "3 backgrounds are running" is not English — and because "background
+ * task" is the thing a user recognises from the running-work bar in the UI,
+ * where they watched it start.
+ */
+export const PADDOCK_NOUNS = {
+    chat: ["chat turn", "chat turns"],
+    background: ["background task", "background tasks"],
+    job: ["scheduled job", "scheduled jobs"],
+};
+/**
+ * What to do about a busy answer — and for Paddock, the first thing to say is
+ * **where to run the command from**.
+ *
+ * This is the keeper-chat trap, and it is specific to Paddock and Managers
+ * among the six tools: Paddock's agents can drive Paddock. A keeper chat that
+ * runs `paddock service restart` or `paddock update` is itself one of the chat
+ * turns the answer just counted, so it will always see itself as busy — and
+ * `--force` from there does not override a mistaken reading, it kills the chat
+ * that typed it, mid-sentence, along with whatever it had not finished. The
+ * agent then has no way to report what happened, because the thing that would
+ * report it is the thing that died.
+ *
+ * So when `chat` is non-zero the advice is not "wait or use --force": it is
+ * "run this from a terminal". When the busy work is background tasks or
+ * scheduled jobs only, nobody is holding the keyboard inside the service and
+ * the ordinary advice applies.
+ */
+export function paddockBusyHint(result) {
+    if (result.state !== "busy")
+        return undefined;
+    const chats = result.answer.counts?.chat ?? 0;
+    if (chats > 0) {
+        // The lead sentence is short because `guardBusy` prints it on the same line
+        // as the message, after `paddock: `. The reasoning goes underneath, indented
+        // like every other continuation this CLI prints.
+        return ("Run it from a terminal, not from inside a Paddock chat.\n" +
+            "    One of the turns counted above may be the chat asking, and --force from there\n" +
+            "    stops the service running that chat — which then never gets to say so.\n" +
+            "    Otherwise: wait for the turns to finish.");
+    }
+    return "Try again once it has finished, or use --force.";
+}
+/** The options both entry points share: name, nouns and hint are fixed for Paddock. */
+function paddockBusyOptions(home, out) {
+    return { home, out, name: PADDOCK_NAME, nouns: PADDOCK_NOUNS, hint: paddockBusyHint };
+}
+/**
+ * `paddock busy [--json]` — exit 0 not busy, 75 busy, 3 nothing answering
+ * (SPEC §1, §2).
+ *
+ * The instance is found through `<data-dir>/runtime.json` and nowhere else, so
+ * this reports on the same instance `paddock serve` and `paddock config show`
+ * resolve — `resolveDataDir` in paddock.ts is the one rule all three use.
+ */
+export async function runBusy(home, json) {
+    const out = createOutput({ tool: "paddock", json });
+    return runBusyCommand(paddockBusyOptions(home, out));
+}
+/**
+ * The check before `service stop` and `service restart` (SPEC §1): refuse with
+ * 75 unless `--force`, which prints the same message prefixed `Overriding:` and
+ * carries on. Returns null to go ahead.
+ *
+ * `home` is the data dir of the INSTALLED unit, not whatever `--data-dir` this
+ * invocation carries — the same rule `status` and `logs` follow (#824), because
+ * the instance being stopped is the one the unit describes.
+ *
+ * Two deliberate non-refusals. Nothing answering goes ahead: there is nothing
+ * to cut short, which is also the answer for a service that is already stopped.
+ * And an instance running a Paddock from before this release has no
+ * `runtime.json`, so it reads as not running and the stop proceeds exactly as
+ * it did before — an upgrade cannot make a stop start failing.
+ */
+export async function guardServiceBusy(action, home, opts) {
+    // No `result()` call on this path, so `--json` only decides which stream the
+    // prose goes to — the one JSON document a `--json` stop may print belongs to
+    // the stop, not to the check it ran first.
+    const out = createOutput({ tool: "paddock", json: opts.json === true });
+    const refusal = await guardBusy({
+        ...paddockBusyOptions(home, out),
+        ...(opts.force === true ? { force: true } : {}),
+    });
+    if (refusal === null)
+        return null;
+    // Spell out the way past it, after the hint about where to run it from.
+    out.warn(`\n    paddock service ${action} --force      ${action} it anyway\n`);
+    return EXIT.busy;
+}

package/packages/server/dist/cli/busy.d.ts

@@ -0,0 +1,69 @@
+import type { Output } from "./output.js";
+/** What `/api/busy` answers (SPEC §4). Counts only, until §10's first question is settled. */
+export interface BusyAnswer {
+    busy: boolean;
+    version?: string;
+    counts?: Record<string, number>;
+}
+export type BusyResult = {
+    state: "not-running";
+} | {
+    state: "idle" | "busy";
+    url: string;
+    answer: BusyAnswer;
+}
+/** Something answered, but not with a busy answer: an older version without `/api/busy`, or another program. */
+ | {
+    state: "unknown";
+    url: string;
+    detail: string;
+};
+export interface FindOptions {
+    /** The tool's data home, holding `runtime.json`. */
+    home: string;
+    /** Ask this URL instead of the one in `runtime.json` (`--url`, or a port the user named). */
+    url?: string;
+    /** How long to wait for an answer. §4 asks for well under a second; this allows for a slow machine. */
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Asks the running instance whether it's busy. There's no fallback to a default port: an instance that's running
+ * wrote `runtime.json`, and guessing a port would ask whatever else is listening there.
+ */
+export declare function checkBusy(o: FindOptions): Promise<BusyResult>;
+/** A kind's singular and plural, where adding an "s" is wrong: `{ batch: ['batch', 'batches'] }`. */
+export type Nouns = Record<string, [singular: string, plural: string]>;
+/** `2 chats and 1 job are running`, from the non-zero counts; '' if there are none. */
+export declare function describeCounts(counts?: Record<string, number>, nouns?: Nouns): string;
+/** The sentence for a person (SPEC §4): `Paddock is busy: 2 chats are running.` */
+export declare function busyMessage(name: string, result: BusyResult, nouns?: Nouns): string;
+/** 0 idle, 75 busy, 3 nothing answers, 1 an answer that isn't a busy answer. */
+export declare function busyExitCode(result: BusyResult): number;
+/** What `<tool> busy --json` prints: valid against `schemas/busy.schema.json`. */
+export declare function busyJson(result: BusyResult): Record<string, unknown>;
+/**
+ * LOCAL CHANGE (see the header): what to suggest when the answer is busy, as a string or as a function of the
+ * result. {@link resolveHint} is what both the command and the guard call, so the two can never print different
+ * advice about the same answer.
+ */
+export type BusyHint = string | ((result: BusyResult) => string | undefined);
+export interface BusyCommandOptions extends FindOptions {
+    /** The product's name, for messages: `Local Review`. */
+    name: string;
+    out: Output;
+    nouns?: Nouns;
+    /** LOCAL CHANGE: the advice printed after a busy message — Paddock's keeper-chat trap. */
+    hint?: BusyHint;
+}
+/** `<tool> busy [--json]`. Returns the exit code; the caller sets `process.exitCode`. */
+export declare function runBusyCommand(o: BusyCommandOptions): Promise<number>;
+export interface GuardOptions extends BusyCommandOptions {
+    force?: boolean;
+}
+/**
+ * The check before `service stop`, `service restart` and `update` (SPEC §4). Returns null to go ahead, or 75 after
+ * printing the refusal. With `--force` it prints the same message, prefixed `Overriding:`, and goes ahead.
+ * Nothing answering goes ahead: there's nothing to cut short.
+ */
+export declare function guardBusy(o: GuardOptions): Promise<number | null>;

package/packages/server/dist/cli/busy.js

@@ -0,0 +1,150 @@
+// From edspencer/cli-contract reference/busy-client.ts @ SPEC 0.1; local changes: `.ts` import specifiers → `.js`
+// and `../runtime-file.js` (the writer lives server-side, next to the boot path that writes the file); `EXIT.OK` /
+// `EXIT.BUSY` / `EXIT.NOT_RUNNING` / `EXIT.FAILED` → Paddock's lowercase `EXIT.ok` / `busy` / `notRunning` /
+// `failure` (see `exit-codes.ts`, which wave C4 re-syncs); and `hint` widened from a string to
+// `string | ((result) => string | undefined)`, with {@link runBusyCommand} printing it too — that is what carries
+// Paddock's keeper-chat trap (ROADMAP "Busy, per tool"), where the line to print depends on WHICH counts are
+// non-zero, so a fixed string could not say it.
+//
+// The CLI's side of the busy check (SPEC §4): find the running instance through `<home>/runtime.json`, ask its
+// `/api/busy`, and map the answer to exit 0 (idle), 75 (busy) or 3 (nothing answers), with §4's messages.
+// Used by `<tool> busy`, and before `service stop`, `service restart` and `update`. Node built-ins only.
+import { EXIT } from "./exit-codes.js";
+import { readLiveRuntimeFile } from "../runtime-file.js";
+/**
+ * Asks the running instance whether it's busy. There's no fallback to a default port: an instance that's running
+ * wrote `runtime.json`, and guessing a port would ask whatever else is listening there.
+ */
+export async function checkBusy(o) {
+    const base = o.url ?? readLiveRuntimeFile(o.home)?.url;
+    if (!base)
+        return { state: "not-running" };
+    const url = new URL("/api/busy", base).toString();
+    const doFetch = o.fetch ?? globalThis.fetch;
+    let res;
+    try {
+        res = await doFetch(url, {
+            signal: AbortSignal.timeout(o.timeoutMs ?? 3000),
+            headers: { accept: "application/json" },
+        });
+    }
+    catch {
+        // Refused, reset or timed out: nothing is answering, which §4 calls not running.
+        return { state: "not-running" };
+    }
+    if (!res.ok)
+        return { state: "unknown", url, detail: `HTTP ${res.status}` };
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        return { state: "unknown", url, detail: "the answer isn't JSON" };
+    }
+    if (!isBusyAnswer(body))
+        return { state: "unknown", url, detail: "the answer has no boolean `busy`" };
+    return { state: body.busy ? "busy" : "idle", url, answer: body };
+}
+function isBusyAnswer(v) {
+    if (typeof v !== "object" || v === null || typeof v.busy !== "boolean")
+        return false;
+    const counts = v.counts;
+    if (counts === undefined)
+        return true;
+    return (typeof counts === "object" &&
+        counts !== null &&
+        Object.values(counts).every((n) => Number.isInteger(n) && n >= 0));
+}
+/** `2 chats and 1 job are running`, from the non-zero counts; '' if there are none. */
+export function describeCounts(counts = {}, nouns = {}) {
+    const parts = Object.entries(counts)
+        .filter(([, n]) => n > 0)
+        .map(([kind, n]) => {
+        const [one, many] = nouns[kind] ?? [kind, `${kind}s`];
+        return `${n} ${n === 1 ? one : many}`;
+    });
+    if (parts.length === 0)
+        return "";
+    const list = parts.length === 1 ? parts[0] : `${parts.slice(0, -1).join(", ")} and ${parts.at(-1)}`;
+    const total = Object.values(counts).reduce((a, n) => a + (n > 0 ? n : 0), 0);
+    return `${list} ${total === 1 ? "is" : "are"} running`;
+}
+/** The sentence for a person (SPEC §4): `Paddock is busy: 2 chats are running.` */
+export function busyMessage(name, result, nouns = {}) {
+    switch (result.state) {
+        case "not-running":
+            return `${name} isn't running.`;
+        case "idle":
+            return `${name} isn't busy.`;
+        case "busy": {
+            const what = describeCounts(result.answer.counts, nouns);
+            return what ? `${name} is busy: ${what}.` : `${name} is busy.`;
+        }
+        case "unknown":
+            return `Something answered at ${result.url}, but not as ${name}'s busy check (${result.detail}).`;
+    }
+}
+/** 0 idle, 75 busy, 3 nothing answers, 1 an answer that isn't a busy answer. */
+export function busyExitCode(result) {
+    switch (result.state) {
+        case "idle":
+            return EXIT.ok;
+        case "busy":
+            return EXIT.busy;
+        case "not-running":
+            return EXIT.notRunning;
+        case "unknown":
+            return EXIT.failure;
+    }
+}
+/** What `<tool> busy --json` prints: valid against `schemas/busy.schema.json`. */
+export function busyJson(result) {
+    if (result.state === "not-running")
+        return { running: false, busy: false };
+    if (result.state === "unknown")
+        return { running: true, busy: false, url: base(result.url), error: result.detail };
+    return {
+        running: true,
+        busy: result.answer.busy,
+        url: base(result.url),
+        ...(result.answer.version !== undefined ? { version: result.answer.version } : {}),
+        counts: result.answer.counts ?? {},
+    };
+}
+const base = (busyUrl) => busyUrl.replace(/\/api\/busy$/, "");
+function resolveHint(hint, result) {
+    return typeof hint === "function" ? hint(result) : hint;
+}
+/** `<tool> busy [--json]`. Returns the exit code; the caller sets `process.exitCode`. */
+export async function runBusyCommand(o) {
+    const result = await checkBusy(o);
+    const message = busyMessage(o.name, result, o.nouns);
+    o.out.result(busyJson(result));
+    if (result.state === "unknown")
+        o.out.error(message);
+    else
+        o.out.say(message);
+    // LOCAL CHANGE: the hint rides along with a busy answer here too, not only on the guard's refusal — someone who
+    // ran `paddock busy` from inside a chat needs the same sentence as someone whose `service stop` was refused.
+    const hint = result.state === "busy" ? resolveHint(o.hint, result) : undefined;
+    if (hint !== undefined)
+        o.out.say(hint);
+    return busyExitCode(result);
+}
+/**
+ * The check before `service stop`, `service restart` and `update` (SPEC §4). Returns null to go ahead, or 75 after
+ * printing the refusal. With `--force` it prints the same message, prefixed `Overriding:`, and goes ahead.
+ * Nothing answering goes ahead: there's nothing to cut short.
+ */
+export async function guardBusy(o) {
+    const result = await checkBusy(o);
+    if (result.state !== "busy")
+        return null;
+    const message = busyMessage(o.name, result, o.nouns);
+    if (o.force) {
+        o.out.warn(`Overriding: ${message}`);
+        return null;
+    }
+    const hint = resolveHint(o.hint, result) ?? "Try again once it has finished, or use --force.";
+    return o.out.error(`${message} ${hint}`, EXIT.busy);
+}

package/packages/server/dist/cli/output.d.ts

@@ -0,0 +1,52 @@
+export interface OutputStream {
+    write(chunk: string): unknown;
+    isTTY?: boolean;
+}
+export interface OutputOptions {
+    /** The bin, for `<tool>: <message>`. */
+    tool: string;
+    /** `--json` was given: stdout carries exactly one JSON document, and prose goes to stderr. */
+    json?: boolean;
+    stdout?: OutputStream;
+    stderr?: OutputStream;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Whether to colour what goes to this stream (SPEC §3).
+ *
+ * - `NO_COLOR` set to anything but the empty string: never (https://no-color.org).
+ * - `FORCE_COLOR` set: `0` or `false` means never, anything else always.
+ * - Otherwise only on a TTY, and not when `TERM=dumb`.
+ */
+export declare function useColor(stream: OutputStream, env?: NodeJS.ProcessEnv): boolean;
+export interface Paint {
+    bold(s: string): string;
+    dim(s: string): string;
+    red(s: string): string;
+    green(s: string): string;
+    yellow(s: string): string;
+}
+/** Colour functions that do nothing when `on` is false. */
+export declare function paint(on: boolean): Paint;
+export interface Output {
+    readonly json: boolean;
+    /** Colour for prose on stdout (never with `--json`, which has no prose on stdout). */
+    readonly color: Paint;
+    /** Colour for stderr. */
+    readonly errColor: Paint;
+    /** Prose for a person: stdout, or stderr under `--json`. */
+    say(line: string): void;
+    /** A warning on stderr, always. */
+    warn(line: string): void;
+    /** `<tool>: <message>` on stderr. Returns `code` (default 1), for `return out.error(…)`. Sets nothing itself. */
+    error(message: string, code?: number): number;
+    /** The one JSON document `--json` promises. Prints nothing without `--json`. */
+    result(doc: unknown): void;
+}
+/** One place for a command's output. Make it once per command, after the flags are parsed. */
+export declare function createOutput(o: OutputOptions): Output;
+/**
+ * A closed pipe (`<tool> … | head -1`) exits quietly (SPEC §2): without this, Node throws EPIPE from a later write
+ * and prints a stack trace. Call once, at startup.
+ */
+export declare function exitQuietlyOnEpipe(stream?: NodeJS.WriteStream, exit?: (code: number) => void): void;

package/packages/server/dist/cli/output.js

@@ -0,0 +1,84 @@
+// From edspencer/cli-contract reference/output.ts @ SPEC 0.1; local changes: `./exit-codes.ts` → `./exit-codes.js`
+// (Paddock compiles to ESM-with-extensions, not a TS runtime); `EXIT.FAILED`/`EXIT.USAGE` → Paddock's lowercase
+// `EXIT.failure`/`EXIT.usage`, because Paddock's own `exit-codes.ts` predates the reference module and wave C4
+// re-syncs that file; and the reference's `UsageError` / `reportUsageError` are NOT copied, because `cli/args.ts`
+// already has a `UsageError` (a `CliError` subclass carrying its own code) that the entrypoint already reports.
+//
+// A CLI's output, the way SPEC §2 and §3 say: errors as `<tool>: <message>` on stderr, colour only on a TTY (honouring
+// NO_COLOR and FORCE_COLOR), and with `--json`, one JSON document on stdout and every word of prose on stderr.
+// Node built-ins only.
+import { EXIT } from "./exit-codes.js";
+/**
+ * Whether to colour what goes to this stream (SPEC §3).
+ *
+ * - `NO_COLOR` set to anything but the empty string: never (https://no-color.org).
+ * - `FORCE_COLOR` set: `0` or `false` means never, anything else always.
+ * - Otherwise only on a TTY, and not when `TERM=dumb`.
+ */
+export function useColor(stream, env = process.env) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== "")
+        return false;
+    if (env.FORCE_COLOR !== undefined)
+        return env.FORCE_COLOR !== "0" && env.FORCE_COLOR !== "false";
+    if (env.TERM === "dumb")
+        return false;
+    return stream.isTTY === true;
+}
+const sgr = (open, close) => (s) => `\u001b[${open}m${s}\u001b[${close}m`;
+const plain = (s) => s;
+/** Colour functions that do nothing when `on` is false. */
+export function paint(on) {
+    return on
+        ? {
+            bold: sgr(1, 22),
+            dim: sgr(2, 22),
+            red: sgr(31, 39),
+            green: sgr(32, 39),
+            yellow: sgr(33, 39),
+        }
+        : { bold: plain, dim: plain, red: plain, green: plain, yellow: plain };
+}
+/** One place for a command's output. Make it once per command, after the flags are parsed. */
+export function createOutput(o) {
+    const stdout = o.stdout ?? process.stdout;
+    const stderr = o.stderr ?? process.stderr;
+    const env = o.env ?? process.env;
+    const json = o.json === true;
+    let printed = false;
+    const line = (s) => (s.endsWith("\n") ? s : `${s}\n`);
+    return {
+        json,
+        color: paint(!json && useColor(stdout, env)),
+        errColor: paint(useColor(stderr, env)),
+        say(s) {
+            (json ? stderr : stdout).write(line(s));
+        },
+        warn(s) {
+            stderr.write(line(s));
+        },
+        error(message, code = EXIT.failure) {
+            stderr.write(line(`${o.tool}: ${message}`));
+            return code;
+        },
+        result(doc) {
+            if (!json)
+                return;
+            if (printed)
+                throw new Error("--json prints one document; result() was called twice");
+            printed = true;
+            stdout.write(`${JSON.stringify(doc, null, 2)}\n`);
+        },
+    };
+}
+/**
+ * A closed pipe (`<tool> … | head -1`) exits quietly (SPEC §2): without this, Node throws EPIPE from a later write
+ * and prints a stack trace. Call once, at startup.
+ */
+export function exitQuietlyOnEpipe(stream = process.stdout, exit = (c) => process.exit(c)) {
+    stream.on("error", (err) => {
+        if (err.code === "EPIPE")
+            exit(typeof process.exitCode === "number" ? process.exitCode : 0);
+        else
+            throw err;
+    });
+}

package/packages/server/dist/cli/paddock.js

@@ -23,7 +23,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { CliError, UsageError, USAGE, USAGE_SYNOPSIS, SERVICE_USAGE, CONFIG_USAGE, parseCommand, nodeVersionProblem, explainListenError, } from "./args.js";
+import { CliError, UsageError, USAGE, USAGE_SYNOPSIS, SERVICE_USAGE, CONFIG_USAGE, BUSY_USAGE, parseCommand, nodeVersionProblem, explainListenError, } from "./args.js";
 import { EXIT } from "./exit-codes.js";
 import { runService, safeHomeDir, realpathOr } from "./service/index.js";
 import { PADDOCK_NAME, PADDOCK_VERSION } from "../version.js";
@@ -270,7 +270,13 @@ async function main() {
     }
     const opts = command.opts;
     if (opts.help) {
-        console.log(command.verb === "service" ? SERVICE_USAGE : command.verb === "config" ? CONFIG_USAGE : USAGE);
+        console.log(command.verb === "service"
+            ? SERVICE_USAGE
+            : command.verb === "config"
+                ? CONFIG_USAGE
+                : command.verb === "busy"
+                    ? BUSY_USAGE
+                    : USAGE);
         return EXIT.ok;
     }
     if (opts.version) {
@@ -285,6 +291,14 @@ async function main() {
         return service(command);
     if (command.verb === "config")
         return config(command);
+    // `busy` (SPEC §1, §4). Nothing is imported from the server for this: the
+    // answer comes off the wire, and `cli/busy.ts` is Node built-ins only — which
+    // is what keeps a question meant for a Watchtower hook from loading Fastify,
+    // herdctl and the project layer to ask it.
+    if (command.verb === "busy") {
+        const { runBusy } = await import("./busy-command.js");
+        return runBusy(resolveDataDir(opts), opts.json === true);
+    }
     addBundledBinsToPath();
     // NOTHING here reads `process.cwd()`, and that is the point (#798). `--here`
     // used to make the current directory the workspace by setting

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

@@ -31,6 +31,18 @@ export interface ServiceContext {
      * is — `status` has to be assertable without a server to ask.
      */
     probeHealth?: (url: string) => Promise<HealthAnswer | undefined>;
+    /**
+     * The busy check `stop` and `restart` run first (SPEC §1, §4): null to go
+     * ahead, or 75 having printed the refusal.
+     *
+     * Injected for the third time for the third version of the same reason: the
+     * real one reads `<home>/runtime.json` and fetches a URL, so a test of "does
+     * stop refuse" would otherwise need a server to be busy at it.
+     */
+    guardBusy?: (action: "stop" | "restart", home: string, opts: {
+        force?: boolean;
+        json?: boolean;
+    }) => Promise<number | null>;
 }
 /**
  * The version of the Paddock the unit points at.

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

@@ -432,7 +432,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 +443,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 +477,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 +506,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,15 +574,17 @@ 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);