@edspencer/paddock 0.70.1 → 0.71.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.70.1",
+  "version": "0.71.1",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",
@@ -37,7 +37,7 @@
     "@fastify/swagger-ui": "4.2.0",
     "@fastify/websocket": "10.0.1",
     "@herdctl/chat": "0.8.0",
-    "@herdctl/core": "5.32.0",
+    "@herdctl/core": "5.33.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "fastify": "4.28.1",
     "jose": "6.2.3",

package/packages/server/dist/background-live.d.ts

@@ -78,6 +78,14 @@ export interface LiveBackgroundTask {
      * carried on the wire and filtered at the point of display.
      */
     skipTranscript?: boolean;
+    /**
+     * Can this task be stopped (#848)? Derived from {@link type} alongside
+     * {@link role}, at the one boundary that owns SDK task-type knowledge — see
+     * {@link UNSTOPPABLE_TASK_TYPES}. Clients gate the stop affordance on this
+     * rather than re-deriving it, so the CLI's kill-strategy table has exactly
+     * one representation in the codebase.
+     */
+    stoppable: boolean;
 }
 export type BackgroundChangeListener = (projectSlug: string, sessionId: string, tasks: LiveBackgroundTask[]) => void;
 /**
@@ -107,6 +115,22 @@ export declare class BackgroundRegistry {
      * stream ends — see the per-process caveat in the module header.
      */
     clear(sessionId: string): void;
+    /**
+     * Drop one task the way a terminal edge would, on the word of an out-of-band
+     * authority rather than the session's own stream (#848).
+     *
+     * The single caller is the stop path, for the case where
+     * `stopTaskInSession` answers `false` — no live session with that id. There
+     * is then no stream left to deliver the `task_notification` this registry
+     * normally evicts on, so without this the row would sit at `stopping…`
+     * forever describing work that is definitively gone.
+     *
+     * Safe against being wrong for the same reason {@link evict} is: the level
+     * signal remains the sole authority on membership, so a task dropped here
+     * that is somehow still running is simply put back by the next
+     * `background_tasks_changed`.
+     */
+    dropTask(sessionId: string, taskId: string): boolean;
     /**
      * Feed one raw SDK message. Returns true when the live set changed, so the
      * caller can avoid re-broadcasting on the overwhelming majority of messages

package/packages/server/dist/background-live.js

@@ -75,6 +75,25 @@ const TASK_ROLES = {
 export function roleForTaskType(type) {
     return TASK_ROLES[type] ?? type;
 }
+/**
+ * Task types the CLI has no kill strategy for, so `stopTask` on one REJECTS
+ * with `unsupported_type` rather than being swallowed (#848).
+ *
+ * Keyed on the RAW discriminant, and {@link TASK_ROLES} directly above is the
+ * proof that it has to be: that map sends BOTH `monitor_mcp` and `monitor_ws`
+ * to the same `monitor` role, and only the MCP flavour is unkillable. A
+ * consumer holding the derived `role` therefore cannot tell the stoppable one
+ * from the unstoppable one — so the answer is resolved here, next to the map
+ * that erases the distinction, and carried on the wire as `stoppable`.
+ *
+ * A DENYLIST, not an allowlist, and deliberately so: a task type the SDK adds
+ * after this was written gets a stop button, and if the CLI turns out not to
+ * support it the rejection surfaces in the row as "can't stop". An allowlist
+ * would silently withhold the button from every new stoppable type instead,
+ * which is the worse failure — the whole point of the issue is that there was
+ * nothing to click.
+ */
+const UNSTOPPABLE_TASK_TYPES = new Set(["monitor_mcp"]);
 const str = (v) => (typeof v === "string" && v ? v : undefined);
 const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
 /**
@@ -134,6 +153,24 @@ export class BackgroundRegistry {
         e.tasks.clear();
         this.emit(sessionId, e);
     }
+    /**
+     * Drop one task the way a terminal edge would, on the word of an out-of-band
+     * authority rather than the session's own stream (#848).
+     *
+     * The single caller is the stop path, for the case where
+     * `stopTaskInSession` answers `false` — no live session with that id. There
+     * is then no stream left to deliver the `task_notification` this registry
+     * normally evicts on, so without this the row would sit at `stopping…`
+     * forever describing work that is definitively gone.
+     *
+     * Safe against being wrong for the same reason {@link evict} is: the level
+     * signal remains the sole authority on membership, so a task dropped here
+     * that is somehow still running is simply put back by the next
+     * `background_tasks_changed`.
+     */
+    dropTask(sessionId, taskId) {
+        return this.evict(sessionId, taskId);
+    }
     /**
      * Feed one raw SDK message. Returns true when the live set changed, so the
      * caller can avoid re-broadcasting on the overwhelming majority of messages
@@ -205,6 +242,7 @@ export class BackgroundRegistry {
                 role: roleForTaskType(type),
                 description: str(rt.description) ?? existing?.description ?? "",
                 startedAt: existing?.startedAt ?? this.now(),
+                stoppable: !UNSTOPPABLE_TASK_TYPES.has(type),
             });
         }
         if (prev && sameSet(prev.tasks, next)) {

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

@@ -71,8 +71,16 @@ export type Command = {
  *   `paddock service install --port 7299` both work, and the flag grammar is
  *   the same one in every position.
  *
- * A verb is only a verb in first position: `paddock --port start` is still a
- * missing-value error, and `paddock start start` is still `unknown option`.
+ * A verb is only a verb in first position: `paddock --port start` is an error
+ * from `--port`, not a `start` invocation, and `paddock start start` is still
+ * `unknown option`.
+ *
+ * That first half used to claim a *missing-value* error, which was wrong (#823):
+ * `next()` only rejects `undefined`, so `start` was happily consumed as the port
+ * and became `NaN` in `config.ts`. It is now a **value** error — `--port needs a
+ * number between 1 and 65535` — which is the behaviour the claim was reaching
+ * for. Corrected rather than deleted because the grammar it documents is real
+ * and load-bearing; it was only the example's error that was misdescribed.
  */
 export declare function parseCommand(argv: string[]): Command;
 export declare function parseArgs(argv: string[]): CliOptions;
@@ -92,4 +100,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. Omitted by default on purpose, so\n                          `paddock service` and a bare `paddock` are the same\n                          ~/.paddock instance reached two ways.\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 -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\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

@@ -49,8 +49,16 @@ function isServiceAction(token) {
  *   `paddock service install --port 7299` both work, and the flag grammar is
  *   the same one in every position.
  *
- * A verb is only a verb in first position: `paddock --port start` is still a
- * missing-value error, and `paddock start start` is still `unknown option`.
+ * A verb is only a verb in first position: `paddock --port start` is an error
+ * from `--port`, not a `start` invocation, and `paddock start start` is still
+ * `unknown option`.
+ *
+ * That first half used to claim a *missing-value* error, which was wrong (#823):
+ * `next()` only rejects `undefined`, so `start` was happily consumed as the port
+ * and became `NaN` in `config.ts`. It is now a **value** error — `--port needs a
+ * number between 1 and 65535` — which is the behaviour the claim was reaching
+ * for. Corrected rather than deleted because the grammar it documents is real
+ * and load-bearing; it was only the example's error that was misdescribed.
  */
 export function parseCommand(argv) {
     const [first, ...rest] = argv;
@@ -96,9 +104,23 @@ export function parseArgs(argv) {
         };
         switch (arg) {
             case "-p":
-            case "--port":
-                opts.port = next();
+            case "--port": {
+                // Validate here rather than letting `Number("start")` become NaN three
+                // files later, in `config.ts`, with nothing between the typo and a
+                // server asked to listen on NaN (#823).
+                //
+                // Scoped to NON-EMPTY values on purpose. `paddock --port "$PORT"` with
+                // PORT unset passes `""`, which is falsy at the one place that reads it
+                // (`paddock.ts`: `if (opts.port)`) and so correctly falls through to the
+                // default — a working invocation that a bare `/^\d+$/` guard would turn
+                // into a hard error.
+                const v = next();
+                if (v !== "" && (!/^\d+$/.test(v) || Number(v) < 1 || Number(v) > 65535)) {
+                    throw new CliError(`${arg} needs a number between 1 and 65535, got: ${v}`);
+                }
+                opts.port = v;
                 break;
+            }
             case "--host":
                 opts.host = next();
                 break;
@@ -261,9 +283,13 @@ Options (install only — recorded in the generated unit)
   -p, --port <port>       HTTP/WS port (default 7233)
       --host <host>       Bind address (default 127.0.0.1)
   -d, --data-dir <path>   Only if you want an instance SEPARATE from your
-                          terminal one. Omitted by default on purpose, so
+                          terminal one. Left out of the unit when you omit it
+                          AND \`PADDOCK_DATA_DIR\` is unset in this shell, so
                           \`paddock service\` and a bare \`paddock\` are the same
-                          ~/.paddock instance reached two ways.
+                          ~/.paddock instance reached two ways. If
+                          \`PADDOCK_DATA_DIR\` IS set here, that path is recorded
+                          in the unit — the service would otherwise point
+                          somewhere your terminal does not.
       --verbose           Record the server's own logs, not just warnings
 
 At login, not at boot
@@ -285,7 +311,7 @@ Where it lives
   macOS   ~/Library/LaunchAgents/net.edspencer.paddock.plist
           logs in <data-dir>/service/
   Linux   ~/.config/systemd/user/paddock.service
-          logs via  journalctl --user -u paddock -f
+          logs via  journalctl --user -u paddock.service -f
 
 Installed from npx?
   \`service install\` refuses. An npx cache path is hash-keyed and npm may prune

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

@@ -29,6 +29,7 @@ import { buildSpec, defaultDataDir, hostFromArgv, isNpxPath, NPX_REFUSAL, portFr
 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 +77,56 @@ 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) {
+/**
+ * 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),
@@ -130,7 +168,18 @@ function status(opts, ctx, backend) {
     const dataDir = dataFromUnit >= 0 && state.argv[dataFromUnit + 1] !== undefined
         ? state.argv[dataFromUnit + 1]
         : defaultDataDir(ctx.homeDir);
-    const { spec } = specFor(opts, { ...ctx, envDataDir: dataDir });
+    // Drop `--data-dir` before building the log-path spec (#824). `resolveDataDir`
+    // gives `opts.dataDir` precedence over `ctx.envDataDir`, which is right for
+    // `install` (see the comment there) and wrong here: this whole block reports
+    // the INSTALLED unit, so letting today's flag through printed the unit's data
+    // dir beside a `Logs:` path under a directory the service never writes to. On
+    // macOS that log path is real and load-bearing, not just cosmetic.
+    //
+    // `--data-dir` is documented as install-only (SERVICE_USAGE), so ignoring it
+    // here matches both the help text and the stated intent of this block.
+    const statusOpts = { ...opts };
+    delete statusOpts.dataDir;
+    const { spec } = specFor(statusOpts, { ...ctx, envDataDir: dataDir });
     const linger = backend.lingerNote();
     console.log([
         "",
@@ -149,7 +198,7 @@ function status(opts, ctx, backend) {
         "",
     ].join("\n"));
 }
-export function runService(action, opts, ctx) {
+export async function runService(action, opts, ctx) {
     const backend = backendFor(ctx);
     if (action === "install")
         return install(opts, ctx, backend);

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

@@ -0,0 +1,61 @@
+/**
+ * "Is it actually up?" — the bounded readiness poll the service CLI uses before
+ * it claims success (#873, #861).
+ *
+ * Every service command that starts something has the same failure mode without
+ * this: the supervisor accepts the request and returns, so the CLI prints a URL
+ * and a cheerful past tense while the server is still binding — or is already
+ * crash-looping on a port clash, which `launchctl` and `systemctl` will both
+ * happily report as "running" for the ten seconds between restarts. A message
+ * that can sit over a crash-loop and still say "running at <url>" is not a
+ * status line, it is a guess.
+ *
+ * So the check is deliberately end-to-end: an HTTP request to the URL a human
+ * would open, not a pid lookup. `/api/health` is the probe because it is in
+ * `ALWAYS_PUBLIC_PATHS` (`auth.ts`) — it answers whatever `PADDOCK_AUTH_MODE`
+ * the installed unit runs with, so this does not quietly stop working for the
+ * people who configured a credential.
+ *
+ * The result is a tri-state on purpose. "I could not confirm it" is a real and
+ * common answer — an unusual bind host, a slow first boot — and it is not the
+ * same claim as "it failed". Callers print it as a caveat, not an error, and
+ * point at the logs.
+ */
+/** Where the poll got to when it stopped. */
+export type Readiness = "ready" | "timeout";
+export interface ReadyOptions {
+    /** Base URL of the server, e.g. `http://127.0.0.1:7233` — no trailing slash. */
+    url: string;
+    /** Give up after this long. */
+    timeoutMs?: number;
+    /** Gap between attempts. */
+    intervalMs?: number;
+    /** Injected for tests; defaults to the global. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests, so a timeout can be proven without waiting for one. */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * How long to wait before saying "could not confirm".
+ *
+ * Generous rather than snappy: this budget is only ever spent on the unhappy
+ * path (a ready server answers in well under a second), and the cost of being
+ * too short is a false "did not answer" on a cold boot — the single most
+ * alarming thing this output could say about a service that is in fact fine.
+ */
+export declare const READY_TIMEOUT_MS = 20000;
+/** The same budget as prose, so a message and the clock cannot drift apart. */
+export declare const READY_TIMEOUT_LABEL = "20 seconds";
+/**
+ * Poll `<url>/api/health` until it answers, or until `timeoutMs` elapses.
+ *
+ * Connection errors are the expected case rather than the exceptional one — a
+ * server that has not finished binding refuses the connection — so they are
+ * swallowed and retried. Only the clock ends the loop.
+ *
+ * Each request carries its own abort so a hung socket cannot outlive the budget
+ * it was given; without it a single connection that opens and never replies
+ * would park here well past `timeoutMs`.
+ */
+export declare function waitForReady(opts: ReadyOptions): Promise<Readiness>;

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

@@ -0,0 +1,71 @@
+/**
+ * "Is it actually up?" — the bounded readiness poll the service CLI uses before
+ * it claims success (#873, #861).
+ *
+ * Every service command that starts something has the same failure mode without
+ * this: the supervisor accepts the request and returns, so the CLI prints a URL
+ * and a cheerful past tense while the server is still binding — or is already
+ * crash-looping on a port clash, which `launchctl` and `systemctl` will both
+ * happily report as "running" for the ten seconds between restarts. A message
+ * that can sit over a crash-loop and still say "running at <url>" is not a
+ * status line, it is a guess.
+ *
+ * So the check is deliberately end-to-end: an HTTP request to the URL a human
+ * would open, not a pid lookup. `/api/health` is the probe because it is in
+ * `ALWAYS_PUBLIC_PATHS` (`auth.ts`) — it answers whatever `PADDOCK_AUTH_MODE`
+ * the installed unit runs with, so this does not quietly stop working for the
+ * people who configured a credential.
+ *
+ * The result is a tri-state on purpose. "I could not confirm it" is a real and
+ * common answer — an unusual bind host, a slow first boot — and it is not the
+ * same claim as "it failed". Callers print it as a caveat, not an error, and
+ * point at the logs.
+ */
+/**
+ * How long to wait before saying "could not confirm".
+ *
+ * Generous rather than snappy: this budget is only ever spent on the unhappy
+ * path (a ready server answers in well under a second), and the cost of being
+ * too short is a false "did not answer" on a cold boot — the single most
+ * alarming thing this output could say about a service that is in fact fine.
+ */
+export const READY_TIMEOUT_MS = 20_000;
+/** The same budget as prose, so a message and the clock cannot drift apart. */
+export const READY_TIMEOUT_LABEL = `${READY_TIMEOUT_MS / 1000} seconds`;
+const DEFAULT_INTERVAL_MS = 250;
+/**
+ * Poll `<url>/api/health` until it answers, or until `timeoutMs` elapses.
+ *
+ * Connection errors are the expected case rather than the exceptional one — a
+ * server that has not finished binding refuses the connection — so they are
+ * swallowed and retried. Only the clock ends the loop.
+ *
+ * Each request carries its own abort so a hung socket cannot outlive the budget
+ * it was given; without it a single connection that opens and never replies
+ * would park here well past `timeoutMs`.
+ */
+export async function waitForReady(opts) {
+    const { url, timeoutMs = READY_TIMEOUT_MS, intervalMs = DEFAULT_INTERVAL_MS, fetchImpl = fetch, now = () => Date.now(), sleep = (ms) => new Promise((r) => setTimeout(r, ms)), } = opts;
+    const deadline = now() + timeoutMs;
+    for (;;) {
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            return "timeout";
+        const abort = new AbortController();
+        const timer = setTimeout(() => abort.abort(), Math.min(remaining, timeoutMs));
+        try {
+            const res = await fetchImpl(`${url}/api/health`, { signal: abort.signal });
+            if (res.ok)
+                return "ready";
+        }
+        catch {
+            // Refused, reset, aborted — all "not yet", all retried until the clock says stop.
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (deadline - now() <= 0)
+            return "timeout";
+        await sleep(intervalMs);
+    }
+}

package/packages/server/dist/discover.d.ts

@@ -141,6 +141,43 @@ export interface DiscoverContext {
 }
 /** The ephemeral roots on THIS machine — the well-known set plus `$TMPDIR`. */
 export declare function defaultTempRoots(): string[];
+/**
+ * Drop the transcript folders paddock planted itself, BEFORE anything is counted
+ * (issue #865).
+ *
+ * Paddock bridges each workspace's `.chats` into its Claude home as a symlink at
+ * boot — the root workspace's and the sweeper's exist on an instance nobody has
+ * touched yet. They are transcript folders by every structural test, so the scan
+ * saw two of them, excluded both as `no-recorded-cwd` (they are empty), and
+ * reported `scanned: 2`. Reporting them as *scanned* is the bug: `scanned === 0`
+ * is what the UI keys "no Claude Code history on this machine" off, and paddock's
+ * own bookkeeping is not the user's history.
+ *
+ * ## The test, and why it is this one
+ *
+ * A folder is paddock's own when it resolves INTO paddock's own storage
+ * (`ownRoots`: the projects root and the data dir) while resolving OUTSIDE every
+ * Claude home. Both halves are load-bearing:
+ *
+ *  - the second half alone would drop everything — a real folder physically
+ *    lives in `<claudeHome>/projects/`, which is itself inside the data dir;
+ *  - the first half alone would drop the user's OWN mirrored folders (#620),
+ *    which resolve into `~/.claude` — inside `legacyClaudeHome`, and exactly the
+ *    history this feature exists to offer.
+ *
+ * So: resolves into a claude home ⇒ the user's, keep. Resolves into paddock's
+ * storage but no claude home ⇒ a `.chats` bridge paddock made, drop.
+ *
+ * Note this is deliberately NOT another {@link DiscoverExclusion}. An exclusion
+ * is a directory the user has that we are declining to offer, and it is counted
+ * and shown as such; these are folders that were never theirs to begin with.
+ */
+export declare function withoutOwnTranscriptFolders(folders: TranscriptFolder[], roots: {
+    /** Paddock's own storage: the projects root and the data dir. */
+    ownRoots: string[];
+    /** Both Claude homes — paddock's and the user's. */
+    claudeHomes: string[];
+}): TranscriptFolder[];
 /**
  * Is this an ephemeral scratch directory?
  *