@edspencer/paddock 0.71.1 → 0.71.2

package/package.json

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

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

@@ -36,8 +36,16 @@ export interface CliOptions {
 export declare class CliError extends Error {
 }
 export declare const MIN_NODE_MAJOR = 22;
-/** What `paddock service` can be asked to do. */
-export declare const SERVICE_ACTIONS: readonly ["install", "uninstall", "status"];
+/**
+ * What `paddock service` can be asked to do.
+ *
+ * `start`/`stop`/`restart` join the original three in #873. Note that `start`
+ * is also a top-level VERB — `paddock start` runs a server in this terminal,
+ * `paddock service start` asks the supervisor to run one. The overlap is safe
+ * because `parseCommand` dispatches on `argv[0]` alone and only then reads an
+ * action, so the two never compete for the same token.
+ */
+export declare const SERVICE_ACTIONS: readonly ["install", "uninstall", "status", "start", "stop", "restart"];
 export type ServiceAction = (typeof SERVICE_ACTIONS)[number];
 /** The leading words {@link parseCommand} recognises. Anything else is a flag. */
 export declare const VERBS: readonly ["start", "service"];
@@ -100,4 +108,4 @@ export declare function nodeVersionProblem(nodeVersion: string): string | undefi
  */
 export declare function explainListenError(err: unknown, host: string, port: string): string;
 export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]        start the server (the default)\n  paddock start [options]                 the same thing, said out loud\n  paddock service <install|uninstall|status>\n                                          run it in the background from login\n                                          (`paddock service --help`)\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 7233, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nOpening your own directories\n  Where you run this from does not matter \u2014 the instance is decided by its data\n  dir alone. Directories are added inside the app, on the Discover screen: it\n  reads your Claude Code history, lists the directories you have worked in, and\n  links the ones you tick as projects. A new instance opens on it.\n\n  Importing a directory does not write into it. No .paddock/, no .chats/, no\n  .gitignore edits, no CLAUDE.md \u2014 the project record and the copied transcripts\n  both live in the data dir, and the project just points at the path. Your own\n  ~/.claude transcripts are copied, never moved or deleted, so your terminal\n  `claude` keeps working exactly as before.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials \u2014 and if you\n  already use Claude Code on this machine, it uses the login you already have.\n  That is a macOS Keychain entry on a Mac, or your ~/.claude/.credentials.json\n  elsewhere (symlinked in, never copied). Reading a login writes nothing.\n\n  Otherwise: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment,\n  or a one-off `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`. With no\n  login at all anywhere, run `claude setup-token`. Paddock says at startup when\n  it can find none.\n\nSharing your Claude Code state\n  Apart from that login, Paddock writes nothing outside its data dir by\n  default: transcripts go to each project's .chats/, and your ~/.claude is read\n  for config only. Each thing it can share is one key in\n  <data-dir>/paddock.config.yaml:\n\n    claude:\n      transcripts: host   # own | host, default own\n      credentials: host   # own | host, default host\n      instructions: host  # own | host, default own\n      hooks: host         # own | host, default own\n      mcpServers: host    # own | host, default own\n\n  transcripts: host makes a chat and a `claude --resume` in the same directory\n  the same file, live in both directions; deleting such a chat in Paddock\n  releases it rather than removing it, because it is your history rather than\n  Paddock's copy. credentials: own is the opt-out from sharing the login above.\n\n  instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and\n  plugins/. Off by default, which is a change: your curated CLAUDE.md does not\n  reach Paddock's agents unless you say so. Each project's own CLAUDE.md always\n  does.\n\n  hooks: host runs the shell commands your ~/.claude/settings.json binds to\n  tool use. Off by default \u2014 inheriting someone's hooks is not something to\n  discover after the fact. Its other keys (permissions, model, statusline)\n  apply either way: under hooks: own Paddock writes its own settings.json\n  carrying them with hooks dropped, regenerated at startup.\n\n  mcpServers: host attaches the MCP servers declared in your ~/.claude.json \u2014\n  the top-level ones, plus a project's own when its directory matches. To give\n  this instance a server your machine doesn't have, declare it instead in a\n  sibling mcpServers: block of the same file; use env:VAR_NAME anywhere a\n  string goes so tokens stay out of it. That keeps a token out of the file, not\n  out of `ps`: leave driveMode on its default (session) for a server holding\n  one, since batch passes the definition to claude as a command-line argument.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";
-export declare const SERVICE_USAGE = "paddock service \u2014 keep Paddock running in the background\n\nUsage\n  paddock service install [options]   register it and start it now\n  paddock service uninstall           stop it and deregister it\n  paddock service status              is it registered, is it running, where are the logs\n\nOptions (install only \u2014 recorded in the generated unit)\n  -p, --port <port>       HTTP/WS port (default 7233)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Only if you want an instance SEPARATE from your\n                          terminal one. Left out of the unit when you omit it\n                          AND `PADDOCK_DATA_DIR` is unset in this shell, so\n                          `paddock service` and a bare `paddock` are the same\n                          ~/.paddock instance reached two ways. If\n                          `PADDOCK_DATA_DIR` IS set here, that path is recorded\n                          in the unit \u2014 the service would otherwise point\n                          somewhere your terminal does not.\n      --verbose           Record the server's own logs, not just warnings\n\nAt login, not at boot\n  This registers a per-USER service \u2014 a launchd LaunchAgent on macOS, a\n  `systemd --user` unit on Linux \u2014 so it runs as you, with your own Claude\n  login. That is not incidental: on macOS your Claude login is a Keychain item\n  that only a logged-in user session can read. A boot-time system daemon has no\n  such session and could not use it.\n\n  So Paddock starts when you LOG IN, not when the machine boots. After a\n  restart that nobody logs into, Paddock is not running. That is the design, not\n  a fault.\n\n  On Linux, a user service is also stopped when you log out. To keep it up:\n\n    loginctl enable-linger $USER\n\nWhere it lives\n  macOS   ~/Library/LaunchAgents/net.edspencer.paddock.plist\n          logs in <data-dir>/service/\n  Linux   ~/.config/systemd/user/paddock.service\n          logs via  journalctl --user -u paddock.service -f\n\nInstalled from npx?\n  `service install` refuses. An npx cache path is hash-keyed and npm may prune\n  it, so the unit would work until it silently didn't, at some future login.\n  Install properly first:\n\n    npm i -g @edspencer/paddock && paddock service install\n\nA note on access\n  Paddock binds loopback with authentication off, which is right for a laptop.\n  A service is up for as long as you are logged in rather than as long as a\n  terminal tab, so that window is longer \u2014 but it is not wider: any local\n  process that could reach the port could already read the same Claude login as\n  you. Set PADDOCK_AUTH_MODE if you want a credential on it anyway.\n\nDocs: https://github.com/edspencer/paddock";
+export declare const SERVICE_USAGE = "paddock service \u2014 keep Paddock running in the background\n\nUsage\n  paddock service install [options]   register it and start it now\n  paddock service uninstall           stop it and deregister it\n  paddock service status              is it registered, is it running, where are the logs\n  paddock service start               start an installed service that is stopped\n  paddock service stop                stop it, and leave it installed\n  paddock service restart             stop it and start it again, re-reading config\n\nOptions (install only \u2014 recorded in the generated unit)\n  -p, --port <port>       HTTP/WS port (default 7233)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Only if you want an instance SEPARATE from your\n                          terminal one. Left out of the unit when you omit it\n                          AND `PADDOCK_DATA_DIR` is unset in this shell, so\n                          `paddock service` and a bare `paddock` are the same\n                          ~/.paddock instance reached two ways. If\n                          `PADDOCK_DATA_DIR` IS set here, that path is recorded\n                          in the unit \u2014 the service would otherwise point\n                          somewhere your terminal does not.\n      --verbose           Record the server's own logs, not just warnings\n\nAt login, not at boot\n  This registers a per-USER service \u2014 a launchd LaunchAgent on macOS, a\n  `systemd --user` unit on Linux \u2014 so it runs as you, with your own Claude\n  login. That is not incidental: on macOS your Claude login is a Keychain item\n  that only a logged-in user session can read. A boot-time system daemon has no\n  such session and could not use it.\n\n  So Paddock starts when you LOG IN, not when the machine boots. After a\n  restart that nobody logs into, Paddock is not running. That is the design, not\n  a fault.\n\n  On Linux, a user service is also stopped when you log out. To keep it up:\n\n    loginctl enable-linger $USER\n\nWhere it lives\n  macOS   ~/Library/LaunchAgents/net.edspencer.paddock.plist\n          logs in <data-dir>/service/\n  Linux   ~/.config/systemd/user/paddock.service\n          logs via  journalctl --user -u paddock.service -f\n\nInstalled from npx?\n  `service install` refuses. An npx cache path is hash-keyed and npm may prune\n  it, so the unit would work until it silently didn't, at some future login.\n  Install properly first:\n\n    npm i -g @edspencer/paddock && paddock service install\n\nA note on access\n  Paddock binds loopback with authentication off, which is right for a laptop.\n  A service is up for as long as you are logged in rather than as long as a\n  terminal tab, so that window is longer \u2014 but it is not wider: any local\n  process that could reach the port could already read the same Claude login as\n  you. Set PADDOCK_AUTH_MODE if you want a credential on it anyway.\n\nDocs: https://github.com/edspencer/paddock";

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

@@ -27,8 +27,23 @@
 export class CliError extends Error {
 }
 export const MIN_NODE_MAJOR = 22;
-/** What `paddock service` can be asked to do. */
-export const SERVICE_ACTIONS = ["install", "uninstall", "status"];
+/**
+ * What `paddock service` can be asked to do.
+ *
+ * `start`/`stop`/`restart` join the original three in #873. Note that `start`
+ * is also a top-level VERB — `paddock start` runs a server in this terminal,
+ * `paddock service start` asks the supervisor to run one. The overlap is safe
+ * because `parseCommand` dispatches on `argv[0]` alone and only then reads an
+ * action, so the two never compete for the same token.
+ */
+export const SERVICE_ACTIONS = [
+    "install",
+    "uninstall",
+    "status",
+    "start",
+    "stop",
+    "restart",
+];
 /** The leading words {@link parseCommand} recognises. Anything else is a flag. */
 export const VERBS = ["start", "service"];
 function isServiceAction(token) {
@@ -278,6 +293,9 @@ 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 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
 
 Options (install only — recorded in the generated unit)
   -p, --port <port>       HTTP/WS port (default 7233)

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

@@ -20,6 +20,21 @@ export interface ServiceState {
     pid?: string;
     /** The Paddock arguments recorded in the installed unit, interpreter stripped. */
     argv: string[];
+    /**
+     * Does the unit ON DISK come back after a graceful stop (#872)?
+     *
+     * Read from the installed file rather than from what we would write today,
+     * because those differ for exactly the people who need to hear about it.
+     * Upgrading the package does not rewrite a unit, so anyone who installed
+     * before #872 still has `SuccessfulExit: false` / `Restart=on-failure` — the
+     * shape where one sleep or logout stops Paddock for good. They cannot see
+     * that from the outside: the service simply is not running one morning.
+     * `status` is where they look, so `status` is where it has to say so.
+     *
+     * Meaningless when `registered` is false, and `true` there — "nothing to warn
+     * about" — so no caller has to special-case a unit that does not exist.
+     */
+    keepsAlive: boolean;
 }
 export interface ServiceBackend {
     platform: "darwin" | "linux";
@@ -31,6 +46,24 @@ export interface ServiceBackend {
     /** True if something was actually there to remove. */
     uninstall(): boolean;
     status(): ServiceState;
+    /**
+     * Start / stop / restart an already-installed unit (#873).
+     *
+     * These exist so an intended stop has a channel of its OWN. Before them the
+     * only stop was `uninstall`, which also deregisters, so "bounce it after
+     * editing config" meant either losing the unit or dropping to raw
+     * `launchctl kickstart -k gui/$(id -u)/net.edspencer.paddock` — undiscoverable,
+     * and different on each platform. The exit-code heuristic that #872 removed
+     * was carrying the same meaning by inference; a command carries it directly.
+     *
+     * Each throws with the supervisor's own stderr rather than returning a
+     * boolean: the interesting failures here (a unit that was booted out, a
+     * manager that is not running) have text worth showing, and swallowing it
+     * would leave `start` printing a URL for a server that never came up.
+     */
+    start(): void;
+    stop(): void;
+    restart(): void;
     /** How to read the logs, as printed lines. */
     logsHint(spec: ServiceSpec): string;
     /** The `enable-linger` warning, or undefined where it does not apply. */

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

@@ -21,9 +21,9 @@ export interface ServiceContext {
     /**
      * "Did the URL answer?", injected for the same reason `run` is.
      *
-     * Without a seam here every install test would really poll 127.0.0.1 for the
-     * full timeout and then assert on the disappointed message — twenty seconds
-     * per case, and green for the wrong reason.
+     * Without a seam here every `install` / `start` / `restart` test would really
+     * poll 127.0.0.1 for the full timeout and then assert on the disappointed
+     * message — twenty seconds per case, and green for the wrong reason.
      */
     checkReady?: (url: string) => Promise<Readiness>;
 }

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

@@ -1,5 +1,6 @@
 /**
- * `paddock service install | uninstall | status` (#796).
+ * `paddock service install | uninstall | status | start | stop | restart`
+ * (#796; the lifecycle three added in #873).
  *
  * Registers Paddock as a **per-user** background service — a launchd
  * LaunchAgent on macOS, a `systemd --user` unit on Linux — so it is up from
@@ -26,7 +27,7 @@ import os from "node:os";
 import path from "node:path";
 import { CliError } from "../args.js";
 import { buildSpec, defaultDataDir, hostFromArgv, isNpxPath, NPX_REFUSAL, portFromArgv, serviceDir, } from "./spec.js";
-import { spawnRunner } from "./backend.js";
+import { spawnRunner, } from "./backend.js";
 import { createLaunchdBackend } from "./launchd.js";
 import { createSystemdBackend } from "./systemd.js";
 import { waitForReady, READY_TIMEOUT_LABEL } from "./ready.js";
@@ -77,6 +78,25 @@ function specFor(opts, ctx) {
 const AT_LOGIN = "  Paddock starts when you LOG IN, not when the machine boots — it runs as\n" +
     "  you, so it can use the Claude login you already have. After a restart\n" +
     "  that nobody logs into, Paddock is not running.";
+/**
+ * What `status` says about a unit installed before #872.
+ *
+ * Upgrading the package leaves the unit file alone, so the people still holding
+ * the broken shape are exactly the people who will never notice — the symptom
+ * is Paddock being absent one morning, with nothing in the logs, because it was
+ * signalled rather than crashed. Naming the fix here is the only path from that
+ * symptom back to a working service.
+ */
+function staleUnitNote(backend) {
+    const key = backend.platform === "darwin"
+        ? "KeepAlive is conditional on a non-zero exit"
+        : "Restart=on-failure";
+    return (`  ⚠ This unit predates a fix (#872): ${key}, so a graceful stop —\n` +
+        "    the kind sleep, logout or a stray `kill` sends — puts Paddock down\n" +
+        "    until you start it again by hand. Re-run to update the unit:\n" +
+        "\n" +
+        "      paddock service install");
+}
 /**
  * Say what is about to happen, before the part that looks like a hang (#861).
  *
@@ -135,6 +155,7 @@ async function install(opts, ctx, backend) {
         ...(linger !== undefined ? ["", linger] : []),
         "",
         "  paddock service status      is it up, and where",
+        "  paddock service restart     bounce it after editing config",
         "  paddock service uninstall   stop it and remove the unit",
         "",
     ].join("\n"));
@@ -194,16 +215,117 @@ function status(opts, ctx, backend) {
         backend.logsHint(spec),
         "",
         AT_LOGIN,
+        ...(state.keepsAlive ? [] : ["", staleUnitNote(backend)]),
         ...(linger !== undefined && !state.running ? ["", linger] : []),
         "",
     ].join("\n"));
 }
+/**
+ * The URL an installed unit is actually serving, or undefined if none is.
+ *
+ * Read out of the unit rather than recomputed from today's flags, for the same
+ * reason `status` does it: the port in the file is the port the server is on.
+ */
+function installedUrl(state) {
+    return `http://${hostFromArgv(state.argv)}:${portFromArgv(state.argv)}`;
+}
+/** "It isn't installed" — the same answer, wherever it is asked. */
+function notInstalled(backend) {
+    return [
+        "",
+        "  Paddock is not installed as a service.",
+        `  Looked for: ${backend.unitPath}`,
+        "",
+        "  paddock service install     register it and start it now",
+        "",
+    ].join("\n");
+}
+/**
+ * `start` / `restart` (#873), which differ only in what they tolerate.
+ *
+ * `start` on something already running is reported and not acted on — asking
+ * launchd to bootstrap a loaded job is an error, and "it is already up" is the
+ * outcome the user wanted anyway. `restart` has no such case: bouncing a
+ * stopped service is a legitimate way to start it, and the sequence each
+ * backend uses handles both states.
+ *
+ * Both then WAIT. Neither supervisor's "started" means the port answers — it
+ * means the fork succeeded — so printing a URL on the strength of it produces a
+ * success message that can sit over a crash-loop (a port clash restarts every
+ * `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) {
+    const before = backend.status();
+    if (!before.registered) {
+        console.log(notInstalled(backend));
+        return;
+    }
+    const url = installedUrl(before);
+    if (action === "start" && before.running) {
+        console.log(`\n  Paddock is already running${pid(before)}.\n\n  URL:  ${url}\n`);
+        return;
+    }
+    console.log(`\n  ${action === "start" ? "Starting" : "Restarting"} Paddock…`);
+    if (action === "start")
+        backend.start();
+    else
+        backend.restart();
+    const readiness = await (ctx.checkReady ?? ((u) => waitForReady({ url: u })))(url);
+    const after = backend.status();
+    console.log([
+        "",
+        readiness === "ready"
+            ? `  ✓ Paddock is running${pid(after)} at ${url}`
+            : `  Paddock was ${action === "start" ? "started" : "restarted"}, but ${url} did not\n` +
+                `  answer within ${READY_TIMEOUT_LABEL}. It may still be coming up — check:`,
+        ...(readiness === "ready" ? [] : ["", "  paddock service status", backend.logsHint(specForLogs(ctx, after))]),
+        "",
+    ].join("\n"));
+}
+/** `stop` (#873): put it down, leave it installed. */
+function stop(backend) {
+    const state = backend.status();
+    if (!state.registered) {
+        console.log(notInstalled(backend));
+        return;
+    }
+    if (!state.running) {
+        console.log(`\n  Paddock is already stopped.\n  Unit: ${backend.unitPath}\n`);
+        return;
+    }
+    backend.stop();
+    console.log([
+        "",
+        "  Paddock is stopped. The unit is still installed.",
+        `  Unit: ${backend.unitPath}`,
+        "",
+        "  It comes back when you log in again, or now with:",
+        "",
+        "    paddock service start",
+        "",
+    ].join("\n"));
+}
+function pid(state) {
+    return state.pid !== undefined ? ` (pid ${state.pid})` : "";
+}
+/** The spec `logsHint` needs, built from the INSTALLED unit's data dir. */
+function specForLogs(ctx, state) {
+    const i = state.argv.indexOf("--data-dir");
+    const dataDir = i >= 0 && state.argv[i + 1] !== undefined ? state.argv[i + 1] : undefined;
+    const { spec } = specFor({ open: false, verbose: false, help: false, version: false }, { ...ctx, ...(dataDir !== undefined ? { envDataDir: dataDir } : {}) });
+    return spec;
+}
 export async function runService(action, opts, ctx) {
     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);
+    if (action === "stop")
+        return stop(backend);
     return status(opts, ctx, backend);
 }
 /** Exported for the entrypoint's context assembly, and for tests. */

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

@@ -5,10 +5,22 @@ export declare function plistPath(homeDir?: string): string;
 /**
  * Render the plist.
  *
- * `KeepAlive` is a dict rather than `<true/>` on purpose: `SuccessfulExit:
- * false` means "restart it if it exits nonzero, leave it alone if it exits
- * cleanly". A bare `<true/>` would fight a deliberate `launchctl bootout` and
- * make stopping Paddock a wrestling match.
+ * `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
@@ -32,6 +44,17 @@ export declare function renderPlist(spec: ServiceSpec): string;
  * would be the larger risk.
  */
 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;
 /**
  * Read liveness out of `launchctl print gui/<uid>/<label>`.
  *

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

@@ -51,10 +51,22 @@ function xmlEscape(s) {
 /**
  * Render the plist.
  *
- * `KeepAlive` is a dict rather than `<true/>` on purpose: `SuccessfulExit:
- * false` means "restart it if it exits nonzero, leave it alone if it exits
- * cleanly". A bare `<true/>` would fight a deliberate `launchctl bootout` and
- * make stopping Paddock a wrestling match.
+ * `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
@@ -82,10 +94,7 @@ ${strings}
     <key>RunAtLoad</key>
     <true/>
     <key>KeepAlive</key>
-    <dict>
-      <key>SuccessfulExit</key>
-      <false/>
-    </dict>
+    <true/>
     <key>ThrottleInterval</key>
     <integer>10</integer>
     <key>WorkingDirectory</key>
@@ -123,6 +132,19 @@ export function parsePlistArgv(xml) {
         .replace(/&lt;/g, "<")
         .replace(/&amp;/g, "&"));
 }
+/**
+ * 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 function plistKeepsAlive(xml) {
+    return /<key>KeepAlive<\/key>\s*<true\s*\/>/.test(xml);
+}
 /**
  * Read liveness out of `launchctl print gui/<uid>/<label>`.
  *
@@ -139,6 +161,10 @@ export function parseLaunchctlPrint(out) {
         ...(pid !== null ? { pid: pid[1] } : {}),
     };
 }
+/** One phrasing for "launchctl said no", so every caller reports it the same way. */
+function launchctlFailure(verb, r) {
+    return (`launchctl ${verb} failed (exit ${String(r.status)}).\n` + `${r.stderr || r.stdout}`.trim());
+}
 function target() {
     return `gui/${process.getuid?.() ?? 0}/${LAUNCHD_LABEL}`;
 }
@@ -164,10 +190,8 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
             // they are shims over this one that report success in cases where it
             // reports the actual error.
             const boot = run("launchctl", ["bootstrap", domain(), file]);
-            if (boot.status !== 0) {
-                throw new Error(`launchctl bootstrap failed (exit ${String(boot.status)}).\n` +
-                    `${boot.stderr || boot.stdout}`.trim());
-            }
+            if (boot.status !== 0)
+                throw new Error(launchctlFailure("bootstrap", boot));
             // `RunAtLoad` should already have started it; `kickstart -k` makes that
             // true rather than probable, and is the same command a later restart uses.
             run("launchctl", ["kickstart", "-k", target()]);
@@ -179,10 +203,59 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
                 fs.rmSync(file, { force: true });
             return existed;
         },
+        /**
+         * Load the job back into the GUI domain and make sure it is running (#873).
+         *
+         * `bootstrap`, not `launchctl start`: `stop` below BOOTS OUT, so a stopped
+         * Paddock is not merely idle, it is absent from the domain — and `start` on
+         * a label launchd has never heard of fails. Bootstrapping is also what a
+         * login does, so `service start` and the next login take the same path.
+         */
+        start() {
+            const boot = run("launchctl", ["bootstrap", domain(), file]);
+            if (boot.status !== 0)
+                throw new Error(launchctlFailure("bootstrap", boot));
+            run("launchctl", ["kickstart", target()]);
+        },
+        /**
+         * `bootout`, not `launchctl stop`.
+         *
+         * With #872's unconditional `KeepAlive`, `stop` is a request launchd
+         * immediately overrules — it stops the process and then relaunches it,
+         * which is exactly the wrestling match the old conditional KeepAlive was
+         * meant to avoid. `bootout` unloads the job, so KeepAlive no longer applies
+         * and it stays down. The plist is untouched, so `status` still reports it
+         * registered, `start` puts it back, and the next LOGIN starts it again via
+         * `RunAtLoad` — a stop is for this session, not forever. Uninstall is the
+         * one that is forever.
+         */
+        stop() {
+            const out = run("launchctl", ["bootout", target()]);
+            // Exit 3 / "No such process" is launchd for "it was not loaded", which is
+            // the state the caller asked for. Anything else is worth surfacing.
+            if (out.status !== 0 && !/no such process/i.test(`${out.stderr}${out.stdout}`)) {
+                throw new Error(launchctlFailure("bootout", out));
+            }
+        },
+        /**
+         * Boot out, bootstrap, kick. Not `kickstart -k` alone, which needs the job
+         * to be loaded and so fails on the case `restart` most needs to handle: a
+         * service that is stopped. This sequence is identical to `install`'s minus
+         * writing the plist, which also gives `restart` the property the issue asks
+         * for — the unit is re-read on the way up, so an edited plist takes effect.
+         */
+        restart() {
+            run("launchctl", ["bootout", target()]);
+            const boot = run("launchctl", ["bootstrap", domain(), file]);
+            if (boot.status !== 0)
+                throw new Error(launchctlFailure("bootstrap", boot));
+            run("launchctl", ["kickstart", "-k", target()]);
+        },
         status() {
             if (!fs.existsSync(file))
-                return { registered: false, running: false, argv: [] };
-            const argv = parsePlistArgv(fs.readFileSync(file, "utf8"));
+                return { registered: false, running: false, argv: [], keepsAlive: true };
+            const xml = fs.readFileSync(file, "utf8");
+            const argv = parsePlistArgv(xml);
             const printed = run("launchctl", ["print", target()]);
             const parsed = printed.status === 0
                 ? parseLaunchctlPrint(printed.stdout)
@@ -194,6 +267,7 @@ export function createLaunchdBackend(run, homeDir = os.homedir()) {
                 // Strip the interpreter and script: what a reader wants from `status`
                 // is the Paddock invocation, not the absolute path to node twice.
                 argv: argv.slice(2),
+                keepsAlive: plistKeepsAlive(xml),
             };
         },
         logsHint(spec) {

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

@@ -31,8 +31,17 @@ export declare function unitPath(homeDir?: string, xdgConfigHome?: string): stri
 /**
  * Render the unit.
  *
- * `Restart=on-failure` rather than `always`, matching launchd's `SuccessfulExit:
- * false` — a clean shutdown should stay shut down.
+ * `Restart=always`, matching launchd's `KeepAlive=<true/>` (#872). It was
+ * `on-failure`, which for a service is the wrong default for the same reason it
+ * was wrong there: `start.ts` exits `0` on SIGTERM, so a logout — or anything
+ * else that signals the user manager — was read as an intended stop and Paddock
+ * stayed down.
+ *
+ * `always` does not make the unit unstoppable. systemd never restarts a unit it
+ * was itself asked to stop, so `systemctl --user stop` (and therefore
+ * `uninstall`) remains the clean, explicit way to put it down. That is the
+ * difference between an exit code, which has to guess at intent, and a command,
+ * which carries it.
  *
  * `WantedBy=default.target` is what makes `systemctl --user enable` mean
  * "start at login" for a user unit; `multi-user.target` is the system-unit
@@ -43,6 +52,16 @@ export declare function unitPath(homeDir?: string, xdgConfigHome?: string): stri
  * answers to "where are the logs".
  */
 export declare function renderUnit(spec: ServiceSpec): string;
+/**
+ * Does an installed unit carry `Restart=always` (#872)?
+ *
+ * The counterpart to `plistKeepsAlive`, and narrow for the same reason: the
+ * value it has to reject is the `on-failure` this file used to write, which
+ * leaves Paddock down after the graceful exit `start.ts` performs on SIGTERM.
+ * Anything unrecognised reads as "not the fixed shape", which at worst tells a
+ * hand-edited unit's owner to re-run install.
+ */
+export declare function unitKeepsAlive(text: string): boolean;
 /** Read `ExecStart=` back out of an installed unit, split into an argv. */
 export declare function parseUnitArgv(text: string): string[];
 export declare function createSystemdBackend(run: Runner, homeDir?: string, xdgConfigHome?: string): ServiceBackend;