@edspencer/paddock 0.82.0 → 0.82.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.82.0",
+  "version": "0.82.1",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",

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

@@ -34,7 +34,7 @@ import { EXIT } from "./exit-codes.js";
  */
 export class CliError extends Error {
     exitCode;
-    constructor(message, exitCode = EXIT.failure) {
+    constructor(message, exitCode = EXIT.FAILED) {
         super(message);
         this.exitCode = exitCode;
     }
@@ -49,7 +49,7 @@ export class CliError extends Error {
  */
 export class UsageError extends CliError {
     constructor(message) {
-        super(message, EXIT.usage);
+        super(message, EXIT.USAGE);
     }
 }
 export const MIN_NODE_MAJOR = 22;

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

@@ -104,5 +104,5 @@ export async function guardServiceBusy(action, home, opts) {
         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;
+    return EXIT.BUSY;
 }

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

@@ -1,10 +1,8 @@
-// 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.
+// From edspencer/cli-contract reference/busy-client.ts @ 0.2; local changes: `.ts` import specifiers → `.js` and
+// `../runtime-file.js` (the writer lives server-side, next to the boot path that writes the file); 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.
@@ -88,13 +86,13 @@ export function busyMessage(name, result, nouns = {}) {
 export function busyExitCode(result) {
     switch (result.state) {
         case "idle":
-            return EXIT.ok;
+            return EXIT.OK;
         case "busy":
-            return EXIT.busy;
+            return EXIT.BUSY;
         case "not-running":
-            return EXIT.notRunning;
+            return EXIT.NOT_RUNNING;
         case "unknown":
-            return EXIT.failure;
+            return EXIT.FAILED;
     }
 }
 /** What `<tool> busy --json` prints: valid against `schemas/busy.schema.json`. */
@@ -146,5 +144,5 @@ export async function guardBusy(o) {
         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);
+    return o.out.error(`${message} ${hint}`, EXIT.BUSY);
 }

package/packages/server/dist/cli/exit-codes.d.ts

@@ -1,49 +1,25 @@
-/**
- * The CLI contract's exit codes (SPEC §2), as constants.
- *
- * From edspencer/cli-contract SPEC.md §2 @ 0.1. Written here rather than copied
- * from `reference/exit-codes.ts` because the reference module did not exist yet
- * when Paddock aligned; wave C4 re-syncs this file to it and adds the usual
- * provenance header. The numbers, and what each means, are the contract.
- *
- * | 0 | done; running and answering; up to date; not busy
- * | 1 | failed
- * | 2 | usage: an unknown command or flag, a bad value
- * | 3 | not running: installed but not running or not answering
- * | 4 | not installed: there is no service unit
- * | 5 | this install cannot update itself          (`update`, not yet built)
- * | 6 | the update failed and was rolled back      (`update`, not yet built)
- * | 7 | the update failed and could not be rolled back
- * | 75 | busy: refused, and why was printed        (`busy`, not yet built)
- *
- * Codes 3 and 4 are what `systemctl status` and LSB init scripts use for "not
- * running" and "no such service", so a script that already branches on them
- * keeps working. 75 is `EX_TEMPFAIL` from `sysexits.h`, which is also the code
- * that makes Watchtower's pre-update hook skip an update.
- *
- * The three `update` codes are declared now and unused until wave C2. They are
- * here because the contract's whole point is that the numbers mean the same
- * thing in every tool: adding them later, from a different file, is how two
- * tools end up disagreeing about what 5 means.
- */
 export declare const EXIT: {
-    /** Done. Running and answering. Up to date. Not busy. */
-    readonly ok: 0;
-    /** Failed — the catch-all. */
-    readonly failure: 1;
-    /** Usage: an unknown command or flag, or a bad value. Usage follows the message. */
-    readonly usage: 2;
-    /** Not running: installed, but not running or not answering. */
-    readonly notRunning: 3;
-    /** Not installed: there is no service unit. */
-    readonly notInstalled: 4;
-    /** This install cannot update itself; the right command was printed. */
-    readonly cannotSelfUpdate: 5;
+    /** Done; running and answering; up to date; not busy. */
+    readonly OK: 0;
+    /** Failed. */
+    readonly FAILED: 1;
+    /** Usage: an unknown command or flag, a bad value. The usage is printed after the message. */
+    readonly USAGE: 2;
+    /** Not running: installed but not running or not answering, or no instance answers. */
+    readonly NOT_RUNNING: 3;
+    /** Not installed: there's no service unit. */
+    readonly NOT_INSTALLED: 4;
+    /** This install can't update itself; the right command was printed. */
+    readonly CANNOT_UPDATE: 5;
     /** The update failed and was rolled back; the old version is running again. */
-    readonly rolledBack: 6;
-    /** The update failed and could not be rolled back; a person is needed. */
-    readonly needsHuman: 7;
-    /** Busy: refused, and why was printed. Try later, or use `--force`. */
-    readonly busy: 75;
+    readonly ROLLED_BACK: 6;
+    /** The update failed and couldn't be rolled back; a person is needed. */
+    readonly ROLLBACK_FAILED: 7;
+    /** Busy: refused, and why was printed. Try later, or use `--force`. `EX_TEMPFAIL` from sysexits.h. */
+    readonly BUSY: 75;
 };
 export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** A tool may use 8 to 63 for its own commands (SPEC §2). */
+export declare function isToolOwnCode(code: number): boolean;
+/** The SPEC's name for a shared code, for messages ("expected 4 (not installed), got 0 (ok)"). */
+export declare function describeExitCode(code: number | null): string;

package/packages/server/dist/cli/exit-codes.js

@@ -1,48 +1,45 @@
-/**
- * The CLI contract's exit codes (SPEC §2), as constants.
- *
- * From edspencer/cli-contract SPEC.md §2 @ 0.1. Written here rather than copied
- * from `reference/exit-codes.ts` because the reference module did not exist yet
- * when Paddock aligned; wave C4 re-syncs this file to it and adds the usual
- * provenance header. The numbers, and what each means, are the contract.
- *
- * | 0 | done; running and answering; up to date; not busy
- * | 1 | failed
- * | 2 | usage: an unknown command or flag, a bad value
- * | 3 | not running: installed but not running or not answering
- * | 4 | not installed: there is no service unit
- * | 5 | this install cannot update itself          (`update`, not yet built)
- * | 6 | the update failed and was rolled back      (`update`, not yet built)
- * | 7 | the update failed and could not be rolled back
- * | 75 | busy: refused, and why was printed        (`busy`, not yet built)
- *
- * Codes 3 and 4 are what `systemctl status` and LSB init scripts use for "not
- * running" and "no such service", so a script that already branches on them
- * keeps working. 75 is `EX_TEMPFAIL` from `sysexits.h`, which is also the code
- * that makes Watchtower's pre-update hook skip an update.
- *
- * The three `update` codes are declared now and unused until wave C2. They are
- * here because the contract's whole point is that the numbers mean the same
- * thing in every tool: adding them later, from a different file, is how two
- * tools end up disagreeing about what 5 means.
- */
+// From edspencer/cli-contract reference/exit-codes.ts @ 0.2; local changes: none.
+// The exit codes every tool shares (SPEC §2). Copy this file; don't renumber it.
+//
+// Set `process.exitCode`, never call `process.exit()`, so piped output isn't cut short.
 export const EXIT = {
-    /** Done. Running and answering. Up to date. Not busy. */
-    ok: 0,
-    /** Failed — the catch-all. */
-    failure: 1,
-    /** Usage: an unknown command or flag, or a bad value. Usage follows the message. */
-    usage: 2,
-    /** Not running: installed, but not running or not answering. */
-    notRunning: 3,
-    /** Not installed: there is no service unit. */
-    notInstalled: 4,
-    /** This install cannot update itself; the right command was printed. */
-    cannotSelfUpdate: 5,
+    /** Done; running and answering; up to date; not busy. */
+    OK: 0,
+    /** Failed. */
+    FAILED: 1,
+    /** Usage: an unknown command or flag, a bad value. The usage is printed after the message. */
+    USAGE: 2,
+    /** Not running: installed but not running or not answering, or no instance answers. */
+    NOT_RUNNING: 3,
+    /** Not installed: there's no service unit. */
+    NOT_INSTALLED: 4,
+    /** This install can't update itself; the right command was printed. */
+    CANNOT_UPDATE: 5,
     /** The update failed and was rolled back; the old version is running again. */
-    rolledBack: 6,
-    /** The update failed and could not be rolled back; a person is needed. */
-    needsHuman: 7,
-    /** Busy: refused, and why was printed. Try later, or use `--force`. */
-    busy: 75,
+    ROLLED_BACK: 6,
+    /** The update failed and couldn't be rolled back; a person is needed. */
+    ROLLBACK_FAILED: 7,
+    /** Busy: refused, and why was printed. Try later, or use `--force`. `EX_TEMPFAIL` from sysexits.h. */
+    BUSY: 75,
 };
+/** A tool may use 8 to 63 for its own commands (SPEC §2). */
+export function isToolOwnCode(code) {
+    return Number.isInteger(code) && code >= 8 && code <= 63;
+}
+/** The SPEC's name for a shared code, for messages ("expected 4 (not installed), got 0 (ok)"). */
+export function describeExitCode(code) {
+    if (code === null)
+        return 'no exit code (killed by a signal)';
+    const names = {
+        0: 'ok',
+        1: 'failed',
+        2: 'usage',
+        3: 'not running',
+        4: 'not installed',
+        5: "can't update itself",
+        6: 'rolled back',
+        7: "couldn't roll back",
+        75: 'busy',
+    };
+    return names[code] ? `${code} (${names[code]})` : String(code);
+}

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

@@ -1,8 +1,7 @@
-// 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.
+// From edspencer/cli-contract reference/output.ts @ 0.2; local changes: `./exit-codes.ts` → `./exit-codes.js`
+// (Paddock compiles to ESM-with-extensions, not a TS runtime); 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.
@@ -56,7 +55,7 @@ export function createOutput(o) {
         warn(s) {
             stderr.write(line(s));
         },
-        error(message, code = EXIT.failure) {
+        error(message, code = EXIT.FAILED) {
             stderr.write(line(`${o.tool}: ${message}`));
             return code;
         },

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

@@ -78,9 +78,9 @@ const packageRoot = findUp("package.json") ?? path.resolve(moduleDir, "../..");
  * says the usage follows the message — the short one, not {@link USAGE}'s
  * thousand words, which would bury the line that says what was wrong.
  */
-function fail(message, code = EXIT.failure) {
+function fail(message, code = EXIT.FAILED) {
     console.error(`paddock: ${message}`);
-    if (code === EXIT.usage) {
+    if (code === EXIT.USAGE) {
         console.error("");
         console.error(USAGE_SYNOPSIS);
     }
@@ -175,7 +175,7 @@ async function service(command) {
     // which `main` has already handled. Typed rather than asserted.
     if (action === undefined) {
         console.log(SERVICE_USAGE);
-        return EXIT.ok;
+        return EXIT.OK;
     }
     try {
         return await runService(action, opts, serviceContext());
@@ -246,13 +246,13 @@ async function config(command) {
     // which `main` has already handled. Typed rather than asserted.
     if (action === undefined) {
         console.log(CONFIG_USAGE);
-        return EXIT.ok;
+        return EXIT.OK;
     }
     process.env.PADDOCK_DATA_DIR = resolveDataDir(opts);
     const { runConfig } = await import("./config.js");
     try {
         await runConfig(action, opts);
-        return EXIT.ok;
+        return EXIT.OK;
     }
     catch (err) {
         // A config that will not load reaches here as a CliError already carrying
@@ -290,12 +290,12 @@ async function main() {
                     : command.verb === "update"
                         ? UPDATE_USAGE
                         : USAGE);
-        return EXIT.ok;
+        return EXIT.OK;
     }
     if (opts.version) {
         // Bare: the version and a newline, nothing else (SPEC §1). Scripts parse this.
         console.log(PADDOCK_VERSION);
-        return EXIT.ok;
+        return EXIT.OK;
     }
     const problem = nodeVersionProblem(process.versions.node);
     if (problem !== undefined)
@@ -420,7 +420,7 @@ async function main() {
     // 0, but NOT yet: a foreground serve keeps running because the server holds
     // the event loop open. `process.exitCode` is set and never acted on until the
     // listener closes, which is what SIGTERM does (start.ts).
-    return EXIT.ok;
+    return EXIT.OK;
 }
 /**
  * A closed pipe exits quietly (SPEC §2).
@@ -440,5 +440,5 @@ main().then((code) => {
     process.exitCode = code;
 }, (err) => {
     console.error("fatal:", err);
-    process.exitCode = EXIT.failure;
+    process.exitCode = EXIT.FAILED;
 });

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

@@ -1,6 +1,6 @@
 import { type CliOptions, type ServiceAction } from "../args.js";
-import { isNpxPath, serviceDir, type ServiceSpec } from "./spec.js";
-import { type Runner } from "./backend.js";
+import { isNpxPath, serviceDir } from "./spec.js";
+import { type Runner, type ServiceSpec } from "./manager.js";
 import { type UpdateSummary } from "../update/update-check.js";
 import { type HealthAnswer, type Readiness } from "./ready.js";
 export interface ServiceContext {

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

@@ -27,13 +27,14 @@ import os from "node:os";
 import path from "node:path";
 import { CliError } from "../args.js";
 import { EXIT } from "../exit-codes.js";
-import { buildSpec, defaultDataDir, hostFromArgv, isNpxPath, NPX_REFUSAL, portFromArgv, serviceDir, serviceLogPath, } from "./spec.js";
-import { spawnRunner, } from "./backend.js";
-import { createLaunchdBackend } from "./launchd.js";
-import { createSystemdBackend } from "./systemd.js";
+import { buildSpec, defaultDataDir, hostFromArgv, isNpxPath, NPX_REFUSAL, portFromArgv, serviceDir, serviceLogPath, PADDOCK_SERVICE, } from "./spec.js";
+import { spawnRunner, } from "./manager.js";
+import { createLaunchd } from "./launchd.js";
+import { createSystemd } 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 { PADDOCK_VERSION } from "../../version.js";
 import { updateSummary } from "../update/update-check.js";
 import { waitForReady, fetchHealth, READY_TIMEOUT_LABEL, } from "./ready.js";
 /**
@@ -46,9 +47,14 @@ import { waitForReady, fetchHealth, READY_TIMEOUT_LABEL, } from "./ready.js";
 function backendFor(ctx) {
     const run = ctx.run ?? spawnRunner;
     if (ctx.platform === "darwin")
-        return createLaunchdBackend(run, ctx.homeDir);
-    if (ctx.platform === "linux")
-        return createSystemdBackend(run, ctx.homeDir, ctx.xdgConfigHome);
+        return createLaunchd(PADDOCK_SERVICE, { run, homeDir: ctx.homeDir });
+    if (ctx.platform === "linux") {
+        return createSystemd(PADDOCK_SERVICE, {
+            run,
+            homeDir: ctx.homeDir,
+            ...(ctx.xdgConfigHome !== undefined ? { xdgConfigHome: ctx.xdgConfigHome } : {}),
+        });
+    }
     throw new CliError(`\`paddock service\` supports macOS (launchd) and Linux (systemd --user), not ${ctx.platform}.\n` +
         "Run `paddock` in a terminal, or keep it up with whatever your platform uses.");
 }
@@ -195,7 +201,7 @@ async function install(opts, ctx, backend) {
         existing = backend.status();
         if (!existing.registered) {
             console.log(notInstalled(backend));
-            return EXIT.notInstalled;
+            return EXIT.NOT_INSTALLED;
         }
     }
     const { spec, dataDir } = specFor(existing !== undefined ? inherit(opts, existing) : opts, ctx, refreshing);
@@ -241,7 +247,7 @@ async function install(opts, ctx, backend) {
     ].join("\n"));
     // "It is installed but did not answer" is a failure, and used to exit 0 — so
     // an Ansible task or a CI step could not tell it from a working install.
-    return readiness === "ready" ? EXIT.ok : EXIT.failure;
+    return readiness === "ready" ? EXIT.OK : EXIT.FAILED;
 }
 function uninstall(ctx, backend) {
     const existed = backend.uninstall();
@@ -255,7 +261,7 @@ function uninstall(ctx, backend) {
     // 0 either way: "there was nothing to remove" is the state the caller asked
     // for. `uninstall` is idempotent on purpose, so a teardown script can run it
     // without first asking whether it has anything to do.
-    return EXIT.ok;
+    return EXIT.OK;
 }
 /**
  * The data dir the INSTALLED unit uses, read out of its own argument vector.
@@ -318,7 +324,7 @@ export function installedVersionOf(cliPath) {
 }
 /** `{ update }` when there is a recent check to repeat, and `{}` otherwise. */
 function withUpdate(home) {
-    const summary = updateSummary(home);
+    const summary = updateSummary(home, { currentVersion: PADDOCK_VERSION });
     return summary !== undefined ? { update: summary } : {};
 }
 async function buildStatus(ctx, backend) {
@@ -432,7 +438,7 @@ async function status(opts, ctx, backend) {
         // 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;
+        return EXIT.NOT_INSTALLED;
     }
     const versions = report.runningVersion !== null && report.runningVersion !== report.installedVersion
         ? `  Version: ${report.runningVersion} running, ${report.installedVersion ?? "unknown"} installed`
@@ -495,10 +501,10 @@ function noteUpdate(report) {
 /** The exit code a report means (SPEC §2). */
 function statusExit(report) {
     if (!report.installed)
-        return EXIT.notInstalled;
+        return EXIT.NOT_INSTALLED;
     if (!report.running || !report.answering)
-        return EXIT.notRunning;
-    return EXIT.ok;
+        return EXIT.NOT_RUNNING;
+    return EXIT.OK;
 }
 /**
  * The URL an installed unit is actually serving, or undefined if none is.
@@ -539,12 +545,12 @@ async function startOrRestart(action, opts, ctx, backend) {
     const before = backend.status();
     if (!before.registered) {
         console.log(notInstalled(backend));
-        return EXIT.notInstalled;
+        return EXIT.NOT_INSTALLED;
     }
     const url = installedUrl(before);
     if (action === "start" && before.running) {
         console.log(`\n  Paddock is already running${pid(before)}.\n\n  URL:  ${url}\n`);
-        return EXIT.ok;
+        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
@@ -578,7 +584,7 @@ async function startOrRestart(action, opts, ctx, backend) {
     ].join("\n"));
     // A start that never answered is a failure, not a success with a caveat: the
     // caller — often an Ansible task — has no other way to find out.
-    return readiness === "ready" ? EXIT.ok : EXIT.failure;
+    return readiness === "ready" ? EXIT.OK : EXIT.FAILED;
 }
 /**
  * The busy check, asked of the instance the UNIT describes (SPEC §1, §4).
@@ -603,11 +609,11 @@ async function stop(opts, ctx, backend) {
     const state = backend.status();
     if (!state.registered) {
         console.log(notInstalled(backend));
-        return EXIT.notInstalled;
+        return EXIT.NOT_INSTALLED;
     }
     if (!state.running) {
         console.log(`\n  Paddock is already stopped.\n  Unit: ${backend.unitPath}\n`);
-        return EXIT.ok;
+        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
@@ -626,7 +632,7 @@ async function stop(opts, ctx, backend) {
         "    paddock service start",
         "",
     ].join("\n"));
-    return EXIT.ok;
+    return EXIT.OK;
 }
 function pid(state) {
     return state.pid !== undefined ? ` (pid ${state.pid})` : "";
@@ -648,7 +654,7 @@ async function logs(opts, ctx, backend) {
     const state = backend.status();
     if (!state.registered) {
         console.log(notInstalled(backend));
-        return EXIT.notInstalled;
+        return EXIT.NOT_INSTALLED;
     }
     const file = logPathOf(state, dataDirOf(state, ctx));
     const lines = opts.lines ?? DEFAULT_LOG_LINES;
@@ -657,7 +663,7 @@ async function logs(opts, ctx, backend) {
         // would be mixed into the log output itself.
         console.error(`paddock: nothing has been written to ${file} yet.`);
         if (opts.follow !== true)
-            return EXIT.ok;
+            return EXIT.OK;
     }
     else {
         const tail = tailFile(file, lines);
@@ -668,7 +674,7 @@ async function logs(opts, ctx, backend) {
         console.error(`paddock: following ${file} — Ctrl-C to stop.`);
         await followFile(file, { from: sizeOf(file) });
     }
-    return EXIT.ok;
+    return EXIT.OK;
 }
 /**
  * Dispatch, returning the exit code rather than setting one (SPEC §2).

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

@@ -1,92 +1,39 @@
-import { type ServiceSpec } from "./spec.js";
-import type { Runner, ServiceBackend } from "./backend.js";
-/** `~/Library/LaunchAgents/net.edspencer.paddock.plist`. */
-export declare function plistPath(homeDir?: string): string;
+import { type Runner, type ServiceIdentity, type ServiceManager, type ServiceSpec } from './manager.js';
+/** `~/Library/LaunchAgents/<label>.plist`. */
+export declare function plistPath(id: Pick<ServiceIdentity, 'label'>, homeDir?: string): string;
 /**
- * Render the plist.
- *
- * `KeepAlive` is unconditional `<true/>`, and that is a deliberate reversal
- * (#872). It used to be `{ SuccessfulExit: false }` — "restart it if it exits
- * nonzero, leave it alone if it exits cleanly" — which reads like the polite
- * choice and is, for a service, a trap. `start.ts` handles SIGTERM by shutting
- * down cleanly and exiting `0`, so **every** SIGTERM the OS routinely sends a
- * LaunchAgent (sleep, logout, a stray `kill`) looked to launchd like "it meant
- * to stop", and Paddock stayed down until the next login. A hard crash was the
- * survivable case; the graceful stop was the terminal one.
- *
- * The worry that motivated the dict — that `<true/>` fights a deliberate stop —
- * does not hold for the stop this CLI actually performs. `launchctl bootout`
- * unloads the job from the domain, and KeepAlive only applies to a job that is
- * still loaded, so `uninstall` still stops Paddock in one call. What `<true/>`
- * does fight is `launchctl stop`, which is why nothing here uses it.
- *
- * Intent belongs in an explicit command, not in an exit code.
- *
- * `EnvironmentVariables` carries PATH and nothing else. It carries PATH because
- * launchd hands a process a stub PATH that a version manager's `node`, and the
- * `git` an agent will want, are both missing from. It carries nothing else
- * because a plist is a world-readable file in the user's home, and the one
- * category of value that would be tempting to put here — a credential — is
- * precisely what the agent shape exists to avoid needing.
- *
- * 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;
-/**
- * Pull `ProgramArguments` back out of a plist we wrote.
- *
- * `status` reports the port the service is ACTUALLY installed with, which is
- * only knowable from the installed unit — recomputing it from today's flags
- * would print a confident URL for a server listening somewhere else. Regex
- * rather than a plist parser because the input is a file this module wrote, in
- * a shape this module controls, and adding an XML dependency to read it back
- * would be the larger risk.
+ * The plist.
+ *
+ * - `KeepAlive` is an unconditional `<true/>`. `{ SuccessfulExit: false }` reads as the polite choice, but a server
+ *   exits 0 on SIGTERM, so every SIGTERM launchd sends an agent (sleep, logout) would leave it down until the next
+ *   login. `bootout` unloads the job, so `KeepAlive` doesn't fight a deliberate stop.
+ * - `StandardOutPath` and `StandardErrorPath` name the same file.
+ * - `EnvironmentVariables` has PATH (launchd's is a stub) and the spec's `env`. Never a credential: a plist is a
+ *   readable file.
  */
+export declare function renderPlist(id: Pick<ServiceIdentity, 'label'>, spec: ServiceSpec): string;
+/** `ProgramArguments`, read back from a plist this wrote. A regex is enough for a file whose shape we control. */
 export declare function parsePlistArgv(xml: string): string[];
-/**
- * Does an installed plist carry the unconditional `KeepAlive` from #872?
- *
- * Deliberately narrow: it matches `<key>KeepAlive</key>` followed by `<true/>`
- * and nothing else. The shape it must NOT accept is the old
- * `<dict><key>SuccessfulExit</key><false/></dict>`, which is the one that
- * leaves a service dead after a graceful stop — so a `false` here is the signal
- * `status` turns into "re-run install", and defaulting to `true` on anything
- * 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`. */
+/** The log the plist names (`StandardOutPath`). */
 export declare function parsePlistLogPath(xml: string): string | undefined;
-/**
- * Read liveness out of `launchctl print gui/<uid>/<label>`.
- *
- * That command is the honest answer to "is it running": it reports the service
- * as launchd currently understands it, including `state = running` and the pid.
- * The alternative — checking whether the plist file exists — answers "is it
- * registered", which is a different and much weaker question.
- */
+/** Whether the plist has an unconditional `KeepAlive` (the old `SuccessfulExit` dict doesn't count). */
+export declare function plistKeepsAlive(xml: string): boolean;
+/** `state = running` and the pid, from `launchctl print gui/<uid>/<label>`. */
 export declare function parseLaunchctlPrint(out: string): {
     running: boolean;
     pid?: string;
 };
-/**
- * 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;
+export declare const BOOTOUT_POLLS = 40;
+export declare const BOOTOUT_POLL_MS = 250;
+export declare const BOOTSTRAP_ATTEMPTS = 6;
+export declare const BOOTSTRAP_BACKOFF_MS = 500;
+/** 5 is `EIO`; 37 is "operation already in progress". Both mean the last bootout hasn't finished. */
+export declare const BOOTSTRAP_RACE_CODES: ReadonlySet<number>;
+export interface LaunchdOptions {
+    run: Runner;
+    homeDir?: string;
+    uid?: number;
+    /** Injected for tests. */
+    sleep?: (ms: number) => void;
+}
+export declare function createLaunchd(id: ServiceIdentity, o: LaunchdOptions): ServiceManager;