@edspencer/paddock 0.79.1 → 0.81.0

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

@@ -23,8 +23,34 @@
  * the need for the guard entirely, so there is no condition left to get wrong on
  * the next shim, platform or package manager. `paddock.ts` now always runs.
  */
-/** A usage error. Thrown rather than exiting, so parsing stays testable. */
+import { EXIT } from "./exit-codes.js";
+/**
+ * A failure with an exit code attached (SPEC §2).
+ *
+ * Thrown rather than exiting, so parsing stays testable. The code travels with
+ * the error because the thing that KNOWS which code applies is whatever threw —
+ * `main` cannot tell an unsupported platform (a failure, 1) from a misspelled
+ * flag (usage, 2) by looking at a string.
+ */
 export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT.failure) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+/**
+ * An unknown command, an unknown flag, or a bad value: exit 2 (SPEC §2).
+ *
+ * **This is a behaviour change, and a deliberate one.** Every one of these used
+ * to exit 1, which is also what a genuine failure exits — so a script could not
+ * tell "you typed it wrong" from "it tried and could not". The contract splits
+ * them, and a script that tested `$? -eq 1` for a typo now needs `-eq 2`.
+ */
+export class UsageError extends CliError {
+    constructor(message) {
+        super(message, EXIT.usage);
+    }
 }
 export const MIN_NODE_MAJOR = 22;
 /**
@@ -43,6 +69,7 @@ export const SERVICE_ACTIONS = [
     "start",
     "stop",
     "restart",
+    "logs",
 ];
 /**
  * What `paddock config` can be asked to do (#878).
@@ -53,8 +80,15 @@ export const SERVICE_ACTIONS = [
  * the command that makes it unnecessary.
  */
 export const CONFIG_ACTIONS = ["show", "eject"];
-/** The leading words {@link parseCommand} recognises. Anything else is a flag. */
-export const VERBS = ["start", "service", "config"];
+/**
+ * The leading words {@link parseCommand} recognises. Anything else is a flag.
+ *
+ * `serve` is the contract's name for running in the foreground (SPEC §1), and
+ * `start` is kept as an alias **for good** — the spec says so explicitly for
+ * Paddock and Managers, every existing service unit's `ExecStart` names it, and
+ * it is in two years of other people's scripts. They parse to the same command.
+ */
+export const VERBS = ["serve", "start", "service", "config", "busy"];
 /**
  * Split an action off a verb's argv, then parse what follows as flags.
  *
@@ -67,7 +101,7 @@ function parseAction(verb, actions, rest) {
     let action;
     if (head !== undefined && !head.startsWith("-")) {
         if (!actions.includes(head)) {
-            throw new CliError(`unknown ${verb} action: ${head}\n` +
+            throw new UsageError(`unknown ${verb} action: ${head}\n` +
                 `Expected one of: ${actions.join(", ")}.\n` +
                 `Run \`paddock ${verb} --help\` for usage.`);
         }
@@ -76,7 +110,7 @@ function parseAction(verb, actions, rest) {
     const opts = parseArgs(action === undefined ? rest : rest.slice(1));
     // `--help` wins over a missing action: asking for usage is not a usage error.
     if (action === undefined && !opts.help) {
-        throw new CliError(`\`paddock ${verb}\` needs an action: ${actions.join(", ")}.\n` +
+        throw new UsageError(`\`paddock ${verb}\` needs an action: ${actions.join(", ")}.\n` +
             `Run \`paddock ${verb} --help\` for usage.`);
     }
     return { action, opts };
@@ -108,6 +142,30 @@ function parseAction(verb, actions, rest) {
  * and load-bearing; it was only the example's error that was misdescribed.
  */
 export function parseCommand(argv) {
+    const command = dispatch(argv);
+    // `--force` overrides the busy check (SPEC §1, §4) and nothing else, so it
+    // only means anything on the two commands that run one. Rejecting it
+    // everywhere else, rather than parsing and dropping it, is the difference
+    // between being told and guessing: the two readings of a quiet
+    // `service uninstall --force` are "it overrode something" and "it did
+    // nothing", and the exit code is 0 either way.
+    //
+    // Checked here, once, rather than in each command: a second copy of this rule
+    // is a second chance for the two to drift apart about what `--force` means.
+    if (command.opts.force === true &&
+        // `--help` wins, the same way it wins over a missing action above: asking
+        // for the usage is not a usage error.
+        !command.opts.help &&
+        !(command.verb === "service" && (command.action === "stop" || command.action === "restart"))) {
+        const what = command.verb === "service" && command.action !== undefined
+            ? `\`service ${command.action}\``
+            : `\`${command.verb}\``;
+        throw new UsageError(`--force applies to \`service stop\` and \`service restart\` only, not ${what}.\n` +
+            "It overrides the busy check, and those are the two commands that run one.");
+    }
+    return command;
+}
+function dispatch(argv) {
     const [first, ...rest] = argv;
     if (first === "service") {
         return { verb: "service", ...parseAction("service", SERVICE_ACTIONS, rest) };
@@ -115,9 +173,15 @@ export function parseCommand(argv) {
     if (first === "config") {
         return { verb: "config", ...parseAction("config", CONFIG_ACTIONS, rest) };
     }
-    if (first === "start")
-        return { verb: "start", opts: parseArgs(rest) };
-    return { verb: "start", opts: parseArgs(argv) };
+    // `busy` (SPEC §1, §4). A top-level verb rather than a `service` action
+    // because its whole point is to be askable where there is no service to ask:
+    // a Docker container, a Watchtower pre-update hook, an Ansible task.
+    if (first === "busy")
+        return { verb: "busy", opts: parseArgs(rest) };
+    // `serve` and `start` are one command: see VERBS.
+    if (first === "serve" || first === "start")
+        return { verb: "serve", opts: parseArgs(rest) };
+    return { verb: "serve", opts: parseArgs(argv) };
 }
 export function parseArgs(argv) {
     const opts = {
@@ -131,7 +195,7 @@ export function parseArgs(argv) {
         const next = () => {
             const v = argv[++i];
             if (v === undefined)
-                throw new CliError(`${arg} needs a value`);
+                throw new UsageError(`${arg} needs a value`);
             return v;
         };
         switch (arg) {
@@ -148,7 +212,7 @@ export function parseArgs(argv) {
                 // into a hard error.
                 const v = next();
                 if (v !== "" && (!/^\d+$/.test(v) || Number(v) < 1 || Number(v) > 65535)) {
-                    throw new CliError(`${arg} needs a number between 1 and 65535, got: ${v}`);
+                    throw new UsageError(`${arg} needs a number between 1 and 65535, got: ${v}`);
                 }
                 opts.port = v;
                 break;
@@ -185,6 +249,25 @@ export function parseArgs(argv) {
             case "--include-env":
                 opts.includeEnv = true;
                 break;
+            // `service stop` / `service restart`: override the busy check (SPEC §4).
+            case "--force":
+                opts.force = true;
+                break;
+            // `service logs` flags, the names `tail`, `journalctl` and every other
+            // log reader uses — this is not the place to be original.
+            case "-f":
+            case "--follow":
+                opts.follow = true;
+                break;
+            case "-n":
+            case "--lines": {
+                const v = next();
+                if (!/^\d+$/.test(v) || Number(v) < 1) {
+                    throw new UsageError(`${arg} needs a positive number of lines, got: ${v}`);
+                }
+                opts.lines = Number(v);
+                break;
+            }
             case "-h":
             case "--help":
                 opts.help = true;
@@ -194,7 +277,7 @@ export function parseArgs(argv) {
                 opts.version = true;
                 break;
             default:
-                throw new CliError(`unknown option: ${arg}\nRun \`paddock --help\` for usage.`);
+                throw new UsageError(`unknown option: ${arg}`);
         }
     }
     return opts;
@@ -232,14 +315,38 @@ export function explainListenError(err, host, port) {
     }
     return String(err?.message ?? err);
 }
+/**
+ * The command list, on its own.
+ *
+ * Printed after a usage error, because SPEC §2 says the usage follows the
+ * message — and because {@link USAGE} is a thousand words of guide that would
+ * bury the one line explaining what went wrong. The full text is one
+ * `--help` away, and the last line here says so.
+ */
+export const USAGE_SYNOPSIS = `Usage
+  paddock [serve] [options]               run the server in this terminal
+  paddock service <action> [options]      install|uninstall|status|start|stop|restart|logs
+  paddock busy [--json]                   is the running instance busy?
+  paddock config <show|eject> [options]   what this instance's config resolved to
+  paddock -v | --version                  print the version and exit
+  paddock -h | --help                     the full help`;
 export const USAGE = `paddock — run a Paddock instance locally
 
 Usage
-  npx @edspencer/paddock [options]        start the server (the default)
-  paddock start [options]                 the same thing, said out loud
-  paddock service <install|uninstall|status>
-                                          run it in the background from login
+  npx @edspencer/paddock [options]        run the server (the default)
+  paddock serve [options]                 the same thing, said out loud
+                                          (\`paddock start\` is a permanent alias)
+  paddock service install [options]       run it in the background from login
+  paddock service uninstall               stop it and remove the unit
+  paddock service status [--json]         installed? running? which version?
+  paddock service start                   start an installed service
+  paddock service stop [--force]          stop it, leave it installed
+  paddock service restart [--force]       stop it and start it again
+  paddock service logs [-f] [-n <lines>]  the service's log
                                           (\`paddock service --help\`)
+  paddock busy [--json]                   is it busy? exit 0 no, 75 yes, 3
+                                          nothing answering
+                                          (\`paddock busy --help\`)
   paddock config show [--resolved]        what this instance's config resolved
                                           to, and where each value came from
   paddock config eject [--write]          freeze that resolution into
@@ -255,6 +362,14 @@ Options
   -v, --version           Print the Paddock version and exit
   -h, --help              Show this help
 
+Exit codes
+  0   done; running and answering; not busy
+  1   failed
+  2   usage: an unknown command or flag, or a bad value
+  3   not running: installed, but not running or not answering; nothing answers
+  4   not installed: there is no service unit
+  75  busy: refused, and why was printed. Try later, or use --force
+
 Opening your own directories
   Where you run this from does not matter — the instance is decided by its data
   dir alone. Directories are added inside the app, on the Discover screen: it
@@ -358,10 +473,30 @@ export const SERVICE_USAGE = `paddock service — keep Paddock running in the ba
 Usage
   paddock service install [options]   register it and start it now
   paddock service uninstall           stop it and deregister it
-  paddock service status              is it registered, is it running, where are the logs
+  paddock service status [--json]     is it registered, is it running, which
+                                      version, where are the logs
   paddock service start               start an installed service that is stopped
-  paddock service stop                stop it, and leave it installed
-  paddock service restart             stop it and start it again, re-reading config
+  paddock service stop [--force]      stop it, and leave it installed
+  paddock service restart [--force]   stop it and start it again, re-reading config
+  paddock service logs [-f] [-n <n>]  the service's log (the last 50 lines)
+
+Options (logs)
+  -f, --follow            keep printing what gets appended, until Ctrl-C
+  -n, --lines <n>         how many lines to print first (default 50)
+
+Options (stop, restart)
+      --force             stop it even though it is busy
+
+Busy
+  \`stop\` and \`restart\` ask the running instance whether it is busy first, and
+  refuse with exit 75 if it is — a chat turn in flight, a background task, a
+  scheduled job. \`paddock busy\` asks the same question on its own.
+
+  Being refused is the useful case: a restart kills a chat turn mid-sentence,
+  and the turn cannot be resumed from where it was. Wait, or --force.
+
+  \`uninstall\` does not ask. Removing the service is an explicit act, and
+  someone uninstalling it has already decided.
 
 Options (install only — recorded in the generated unit)
   -p, --port <port>       HTTP/WS port (default 7233)
@@ -393,9 +528,21 @@ At login, not at boot
 
 Where it lives
   macOS   ~/Library/LaunchAgents/net.edspencer.paddock.plist
-          logs in <data-dir>/service/
   Linux   ~/.config/systemd/user/paddock.service
-          logs via  journalctl --user -u paddock.service -f
+
+  Both write stdout and stderr to ONE file, <data-dir>/logs/service.log, which
+  is what \`paddock service logs\` reads. Not the journal on Linux: a volatile
+  journal has nothing in it after the reboot you are asking about, and one file
+  means one answer to "where are the logs" on every OS. Paddock rotates it
+  itself at 8 MB, keeping three older generations beside it.
+
+Exit codes
+  0   it is installed, running and answering
+  3   installed, but not running or not answering
+  4   not installed: there is no unit  (status, logs, start, stop, restart)
+  1   something failed
+  2   usage: an unknown action or flag, or a bad value
+  75  busy, and --force was not given  (stop, restart)
 
 Installed from npx?
   \`service install\` refuses. An npx cache path is hash-keyed and npm may prune
@@ -411,6 +558,66 @@ A note on access
   process that could reach the port could already read the same Claude login as
   you. Set PADDOCK_AUTH_MODE if you want a credential on it anyway.
 
+Docs: https://github.com/edspencer/paddock`;
+export const BUSY_USAGE = `paddock busy — is the running instance in the middle of something?
+
+Usage
+  paddock busy                        ask, and say so in a sentence
+  paddock busy --json                 the same answer as one JSON document
+  paddock busy -d <path>              ask a particular instance
+
+Exit codes — this command is FOR its exit code
+  0   not busy. Nothing a restart would cut short.
+  75  busy. What is running was printed.
+  3   nothing answered. No instance is running, so there is nothing to wait for.
+  1   something answered, but not as Paddock's busy check.
+
+Options
+  -d, --data-dir <path>   Which instance to ask (default ~/.paddock, or
+                          \$PADDOCK_DATA_DIR) — the same rule \`paddock serve\`
+                          uses, so the two always mean the same instance
+      --json              One JSON document on stdout: running, busy, url,
+                          version, counts. Prose goes to stderr
+  -h, --help              Show this help
+
+What counts as busy
+  Only work a restart would LOSE or cut short:
+
+    chat         a chat turn running — a human turn, a fired trigger, a cron
+                 fire. A turn is a live claude subprocess writing a transcript,
+                 and it cannot be resumed from where it was interrupted.
+    background   a background task a live session is still holding after its
+                 turn ended: a background shell, a sub-agent, a Monitor.
+    job          a scheduled job herdctl is running.
+
+  Not busy: an idle session (it resumes), an open browser tab (it reconnects),
+  a pending curation sweep (it re-runs from its watermark).
+
+Where to run it from
+  From a terminal. A Paddock chat that runs this is itself one of the chat turns
+  it counts, so it will always see itself as busy — and \`service stop --force\`
+  from inside a chat stops the service that is running the chat, which does not
+  come back with an explanation. That is why the refusal says so.
+
+For scripts, containers and Watchtower
+  \`busy\` is there for callers with no service to ask. 75 is EX_TEMPFAIL, which
+  is the code Watchtower's pre-update hook reads as "skip this one":
+
+    labels:
+      com.centurylinklabs.watchtower.lifecycle.pre-update: paddock busy
+
+  An Ansible task does the same thing with a retry. Nothing here contacts the
+  network or the npm registry, and the question is answered from memory — it is
+  cheap enough to ask in a loop.
+
+How it finds the instance
+  \`<data-dir>/runtime.json\`, written 0600 when the server starts listening and
+  removed when it stops. There is no fallback to a default port: guessing one
+  would ask whatever else happened to be listening there, and get an answer.
+
+  A Paddock from before this feature shipped writes no such file, so it reads as
+  not running (exit 3). Upgrade it and restart it once.
+
 Docs: https://github.com/edspencer/paddock`;
 export const CONFIG_USAGE = `paddock config — what this instance's configuration actually resolved to
 

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>;