@edspencer/paddock 0.71.0 → 0.71.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.71.0",
+  "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/chat-dto.d.ts

@@ -6,6 +6,7 @@
  * and the run-history page-size constants + `clampRunsLimit`.
  */
 import type { DiscoveredSession } from "@herdctl/core";
+import type { SessionWithActivity } from "./last-activity.js";
 import type { Project } from "./projects.js";
 import { type SessionTokenUsage } from "./usage.js";
 import type { RunProvenance } from "./run-provenance.js";
@@ -138,7 +139,7 @@ export type ChatUsageScope = (typeof CHAT_USAGE_SCOPES)[number];
  * each class separately (see {@link estimateCostUsd}).
  */
 export declare function toChatUsage(u: SessionTokenUsage, model: string): ChatUsage | null;
-export declare function toChatDto(s: DiscoveredSession, previewOverride?: string, usage?: ChatUsage | null, archived?: boolean, lastTurnCompletedAt?: string, lastSeen?: number, provenance?: RunProvenance | null, trigger?: ChatTriggerInfo | null, starred?: boolean, unread?: boolean, parent?: ChatParentRef | null): {
+export declare function toChatDto(s: SessionWithActivity, previewOverride?: string, usage?: ChatUsage | null, archived?: boolean, lastTurnCompletedAt?: string, lastSeen?: number, provenance?: RunProvenance | null, trigger?: ChatTriggerInfo | null, starred?: boolean, unread?: boolean, parent?: ChatParentRef | null): {
     trigger?: ChatTriggerInfo | undefined;
     parent?: ChatParentRef | undefined;
     provenance?: RunProvenance | undefined;
@@ -170,7 +171,7 @@ export declare function toChatDto(s: DiscoveredSession, previewOverride?: string
  * name reflects the user's actual request. Only preload chats trigger the extra
  * (head-of-file) read; everything else maps straight through.
  */
-export declare function buildProjectChats(projectDir: string, sessions: DiscoveredSession[], usageOf?: (s: DiscoveredSession) => Promise<ChatUsage | null>, archivedOf?: (s: DiscoveredSession) => Promise<boolean>, lastTurnAt?: ReadonlyMap<string, string>, lastSeenOf?: (s: DiscoveredSession) => Promise<number>, provenanceOf?: (s: DiscoveredSession) => Promise<RunProvenance | undefined>, triggerOf?: (s: DiscoveredSession) => Promise<ChatTriggerInfo | undefined>, starredOf?: (s: DiscoveredSession) => Promise<boolean>, unreadOf?: (s: DiscoveredSession) => Promise<boolean>, parentOf?: (s: DiscoveredSession) => Promise<ChatParentRef | null>): Promise<{
+export declare function buildProjectChats(projectDir: string, sessions: SessionWithActivity[], usageOf?: (s: DiscoveredSession) => Promise<ChatUsage | null>, archivedOf?: (s: DiscoveredSession) => Promise<boolean>, lastTurnAt?: ReadonlyMap<string, string>, lastSeenOf?: (s: DiscoveredSession) => Promise<number>, provenanceOf?: (s: DiscoveredSession) => Promise<RunProvenance | undefined>, triggerOf?: (s: DiscoveredSession) => Promise<ChatTriggerInfo | undefined>, starredOf?: (s: DiscoveredSession) => Promise<boolean>, unreadOf?: (s: DiscoveredSession) => Promise<boolean>, parentOf?: (s: DiscoveredSession) => Promise<ChatParentRef | null>): Promise<{
     trigger?: ChatTriggerInfo | undefined;
     parent?: ChatParentRef | undefined;
     provenance?: RunProvenance | undefined;

package/packages/server/dist/chat-dto.js

@@ -185,7 +185,15 @@ export function toChatDto(s, previewOverride, usage, archived = false, lastTurnC
         sessionId: s.sessionId,
         workingDirectory: s.workingDirectory,
         name: s.customName ?? s.autoName ?? preview ?? s.sessionId.slice(0, 8),
-        updatedAt: s.mtime,
+        // The last real MESSAGE in the transcript, not the file's mtime (#863).
+        // Paddock touches transcripts for reasons that are not conversation — a
+        // discovery re-stat, a resume appending a mode record — and every one of
+        // those used to restamp an idle chat as "updated a few minutes ago" and
+        // float it to the top of a list sorted by recency. mtime survives as the
+        // fallback for a transcript with no datable record, and only as that: it is
+        // still the cache key for auto-name, preview and usage, so it is read here
+        // rather than overwritten upstream.
+        updatedAt: s.lastMessageAt ?? s.mtime,
         resumable: s.resumable,
         preview,
         // Whether this chat is filed away in the Archived section (#95). Always

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/paddock.js

@@ -155,7 +155,7 @@ function openBrowser(url) {
  * for npx's cache, because a unit file pointing into a prunable hash-keyed
  * directory rots at some future login with nobody watching.
  */
-function service(command) {
+async function service(command) {
     const { action, opts } = command;
     // Unreachable: `parseCommand` only omits the action when `--help` was given,
     // which `main` has already handled. Typed rather than asserted.
@@ -164,7 +164,7 @@ function service(command) {
         return;
     }
     try {
-        runService(action, opts, {
+        await runService(action, opts, {
             platform: process.platform,
             nodePath: process.execPath,
             scriptPath: entryScript,
@@ -210,7 +210,7 @@ async function main() {
     if (problem !== undefined)
         fail(problem);
     if (command.verb === "service") {
-        service(command);
+        await service(command);
         return;
     }
     addBundledBinsToPath();

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

@@ -1,6 +1,7 @@
 import { type CliOptions, type ServiceAction } from "../args.js";
 import { isNpxPath, serviceDir, type ServiceSpec } from "./spec.js";
 import { type Runner } from "./backend.js";
+import { type Readiness } from "./ready.js";
 export interface ServiceContext {
     /** `process.platform`. */
     platform: NodeJS.Platform;
@@ -17,8 +18,16 @@ export interface ServiceContext {
     xdgConfigHome?: string;
     pathEnv?: string;
     run?: Runner;
+    /**
+     * "Did the URL answer?", injected for the same reason `run` is.
+     *
+     * 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>;
 }
-export declare function runService(action: ServiceAction, opts: CliOptions, ctx: ServiceContext): void;
+export declare function runService(action: ServiceAction, opts: CliOptions, ctx: ServiceContext): Promise<void>;
 /** Exported for the entrypoint's context assembly, and for tests. */
 export { serviceDir, isNpxPath };
 export type { ServiceSpec };

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,9 +27,10 @@ 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";
 /**
  * Pick a backend, or explain why there isn't one.
  *
@@ -76,19 +78,75 @@ 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.";
-function install(opts, ctx, backend) {
+/**
+ * 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).
+ *
+ * `backend.install` runs `launchctl bootout` / `bootstrap` / `kickstart` — or
+ * the systemd equivalents — through `spawnSync`, and on macOS the bootstrap is
+ * followed by Background-Task-Management registering the new LaunchAgent as a
+ * login item (the "… can run in the background" notification fires in this
+ * window). Three to five seconds, and every one of them silent.
+ *
+ * **There is no spinner here, and that is not laziness.** Those subprocess calls
+ * are synchronous: they block the event loop, so a `setInterval` ticker would
+ * sit frozen for exactly the span it was added to animate — worse than no
+ * spinner, because a stopped spinner reads as a crashed process. Animating it
+ * would mean making the whole `Runner` seam async, which is a much larger change
+ * than this issue is asking for. The defect reported was the SILENCE, and text
+ * on the screen fixes the silence.
+ */
+function installProgress(backend) {
+    const kind = backend.platform === "darwin" ? "the LaunchAgent" : "the user service";
+    return backend.platform === "darwin"
+        ? `\n  Installing ${kind} and starting Paddock…\n` +
+            "  macOS may take a few seconds to approve the background item."
+        : `\n  Installing ${kind} and starting Paddock…`;
+}
+async function install(opts, ctx, backend) {
     if (isNpxPath(ctx.packageRoot))
         throw new CliError(NPX_REFUSAL);
     const { spec, dataDir } = specFor(opts, ctx);
-    backend.install(spec);
     const url = `http://${hostFromArgv(spec.args)}:${portFromArgv(spec.args)}`;
+    console.log(installProgress(backend));
+    backend.install(spec);
+    // The unit is written and the supervisor has accepted it. That is NOT the
+    // same as "Paddock is running", which is what this block used to assert
+    // before anything had been checked — so the success message could sit over a
+    // crash-loop (a port clash restarts every RestartSec/ThrottleInterval, and
+    // both supervisors report `running` for most of that window) and still print
+    // a URL and a tick. Waiting is what makes the headline true.
+    console.log(`  Waiting for ${url} to answer…`);
+    const readiness = await (ctx.checkReady ?? ((u) => waitForReady({ url: u })))(url);
     const kind = backend.platform === "darwin" ? "a launchd LaunchAgent" : "a systemd --user service";
     const linger = backend.lingerNote();
     console.log([
         "",
-        `  Paddock is installed as ${kind}, and running now.`,
+        readiness === "ready"
+            ? `  ✓ Paddock is installed as ${kind}, and running at ${url}`
+            : `  Paddock is installed as ${kind}, but ${url} did not answer\n` +
+                `  within ${READY_TIMEOUT_LABEL}. The unit is in place; it may still be\n` +
+                "  coming up, or it may be failing to start — the logs below say which.",
         "",
-        `  URL:  ${url}`,
+        ...(readiness === "ready" ? [] : [`  URL:  ${url}`]),
         `  Data: ${dataDir}`,
         `  Unit: ${backend.unitPath}`,
         backend.logsHint(spec),
@@ -97,6 +155,7 @@ 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"));
@@ -156,16 +215,117 @@ function status(opts, ctx, backend) {
         backend.logsHint(spec),
         "",
         AT_LOGIN,
+        ...(state.keepsAlive ? [] : ["", staleUnitNote(backend)]),
         ...(linger !== undefined && !state.running ? ["", linger] : []),
         "",
     ].join("\n"));
 }
-export function runService(action, opts, ctx) {
+/**
+ * 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>`.
  *