@edspencer/paddock 0.79.1 → 0.81.0

package/packages/server/dist/routes/meta.js

@@ -5,8 +5,15 @@ import { TranscriptionError } from "../transcribe.js";
 import { resolveModels, resolveDefaultModel } from "../models.js";
 import { sendProjectError } from "../route-errors.js";
 import { cspFor, parseRangeHeader } from "../http-bytes.js";
+import { PADDOCK_VERSION } from "../version.js";
+import { collectBusy } from "../busy.js";
 export function registerMetaRoutes(app, ctx) {
     const { herdctl, transcriber, attachments, cfg } = ctx;
+    // Both optional for the same reason `turn-interlock.ts` takes an optional hub:
+    // a server built without the WS layer (several integration tests) has neither,
+    // and the honest answer for it is zero rather than a crash.
+    const hub = ctx.managementOpsContext?.hub;
+    const background = ctx.managementOpsContext?.background;
     // --- voice dictation (#voice): capability probe + transcription -------
     // The composer polls this to decide whether to show a mic button. `available`
     // is false on instances with dictation off (or a misconfigured remote).
@@ -106,20 +113,66 @@ export function registerMetaRoutes(app, ctx) {
             },
         },
     }, async (req) => req.user);
+    // The CLI contract's one required server endpoint (SPEC §8): `{ ok, version }`,
+    // no auth. The version is load-bearing rather than decorative — it is how
+    // `paddock service status` can say that the version RUNNING differs from the
+    // one installed (an upgrade that never restarted), and how wave C2's
+    // `paddock update` will confirm the service came back as the version it just
+    // installed rather than merely coming back. `ALWAYS_PUBLIC_PATHS` in auth.ts
+    // keeps it answerable whatever `PADDOCK_AUTH_MODE` is set to.
     app.get("/api/health", {
         schema: {
             tags: ["System"],
             summary: "Health check",
-            description: "Liveness probe. Returns a JSON object `{ ok: true }`.",
+            description: "Liveness probe. Returns a JSON object `{ ok: true, version: \"<semver>\" }`. Never requires authentication.",
             response: {
                 200: {
-                    description: "Service is up.",
+                    description: "Service is up, and the version it is running.",
                     type: "object",
                     additionalProperties: true,
                 },
             },
         },
-    }, async () => ({ ok: true }));
+    }, async () => ({ ok: true, version: PADDOCK_VERSION }));
+    // The contract's second server endpoint (SPEC §4, §8): is this instance busy?
+    //
+    // **Counts only, and no auth, and those two facts are the same fact.** There
+    // is nothing in the answer to protect — no chat title, no session id, no
+    // project name, just three integers and the version — which is why the route
+    // can sit beside `/api/health` in `HEALTH_PATHS` without widening what an
+    // unauthenticated caller can learn beyond "something is happening here".
+    // `reasons` (a line per piece of work, for a person) waits on SPEC §10's first
+    // question: how a CLI proves it is local, given that a reverse proxy on the
+    // same host also connects from loopback. Until that is designed, this answer
+    // is the whole answer for every caller — so nothing here may grow a string
+    // field without revisiting the auth decision above it.
+    //
+    // The callers that make the cheapness requirement real: `paddock service
+    // stop`, `paddock update`, and Watchtower's pre-update hook, which runs
+    // `paddock busy` before every image pull. `collectBusy` is synchronous and
+    // reads three in-memory structures — see busy.ts for why `job` does NOT come
+    // from `fleetStatus()`.
+    app.get("/api/busy", {
+        schema: {
+            tags: ["System"],
+            summary: "Is this instance busy?",
+            description: "The CLI contract's busy check (SPEC §4). Returns `{ busy, version, counts }`, where `counts` has `chat` (chat turns running, including fired triggers and cron fires), `background` (live sessions holding background work after their turn ended) and `job` (herdctl scheduler jobs). `busy` is true only for work a restart would lose or cut short. Counts only — never labels, ids or titles — so it needs no authentication. Reads in-memory state, never the disk.",
+            response: {
+                200: {
+                    description: "Whether work a restart would cut short is under way.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async () => collectBusy({
+        runningChats: () => hub?.runningSessions().length ?? 0,
+        // Tasks in a session count only while its SDK session is still live —
+        // see `BackgroundRegistry.liveTaskCount`, which explains why a stale
+        // batch-mode entry must not wedge this at busy.
+        backgroundTasks: () => background?.liveTaskCount((id) => herdctl.isSdkSessionLive(id)) ?? 0,
+        runningJobs: () => herdctl.runningJobCount(),
+    }, PADDOCK_VERSION));
     // --- instance-wide settings (issue #385) --------------------------------
     // A top-level admin screen over the frozen instance config. GET reports every
     // surfaced field (value / default / editable / sensitive / env-shadow); PUT

package/packages/server/dist/runtime-file.d.ts

@@ -0,0 +1,26 @@
+export interface RuntimeInfo {
+    pid: number;
+    port: number;
+    /** Where the CLI reaches it, e.g. `http://127.0.0.1:3729`. */
+    url: string;
+    version: string;
+    /** ISO 8601. */
+    startedAt: string;
+}
+export declare const RUNTIME_FILE = "runtime.json";
+export declare function runtimeFilePath(home: string): string;
+/** Writes the file atomically (a temporary file, then a rename), readable only by this user. */
+export declare function writeRuntimeFile(home: string, info: Omit<RuntimeInfo, "startedAt"> & {
+    startedAt?: string;
+}): RuntimeInfo;
+/** The file's contents, or null if it's missing or isn't a runtime file (a half-written or foreign file). */
+export declare function readRuntimeFile(home: string): RuntimeInfo | null;
+/**
+ * Removes the file, but only if it's still ours: a second instance may have started since and written its own.
+ * Call it on a clean exit. Returns whether it removed anything.
+ */
+export declare function removeRuntimeFile(home: string, pid?: number): boolean;
+/** Whether a process with this pid exists. EPERM means it exists but isn't ours, which still counts. */
+export declare function isPidAlive(pid: number): boolean;
+/** The runtime file, if the process it names is still alive. A crashed instance leaves a stale file behind. */
+export declare function readLiveRuntimeFile(home: string): RuntimeInfo | null;

package/packages/server/dist/runtime-file.js

@@ -0,0 +1,91 @@
+// From edspencer/cli-contract reference/runtime-file.ts @ SPEC 0.1; local changes: `node:fs` / `node:path` imports
+// unchanged, nothing else — the module is Node built-ins only and Paddock's `<home>` is its data dir, so it needed
+// no adaptation. Kept verbatim on purpose: wave C4 re-syncs it, and a divergence here would be a divergence in the
+// one file every tool's `busy`, `service status` and `update` agree on.
+//
+// `<home>/runtime.json`: what a running instance tells its own CLI (SPEC §4, ROADMAP). `serve` writes it once it's
+// listening and removes it on a clean exit; `busy`, `service status` and `update` read it to find the instance.
+//
+// It holds `{ pid, port, url, version, startedAt }`. A token for /api/busy will join it once SPEC §10's first question
+// is settled; the file is written 0600 already, so adding one later changes nothing about who can read it.
+// Node built-ins only.
+import fs from "node:fs";
+import path from "node:path";
+export const RUNTIME_FILE = "runtime.json";
+export function runtimeFilePath(home) {
+    return path.join(home, RUNTIME_FILE);
+}
+/** Writes the file atomically (a temporary file, then a rename), readable only by this user. */
+export function writeRuntimeFile(home, info) {
+    const full = {
+        pid: info.pid,
+        port: info.port,
+        url: info.url,
+        version: info.version,
+        startedAt: info.startedAt ?? new Date().toISOString(),
+    };
+    fs.mkdirSync(home, { recursive: true });
+    const file = runtimeFilePath(home);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(full, null, 2)}\n`, { mode: 0o600 });
+    try {
+        fs.renameSync(tmp, file);
+    }
+    catch (err) {
+        fs.rmSync(tmp, { force: true });
+        throw err;
+    }
+    return full;
+}
+/** The file's contents, or null if it's missing or isn't a runtime file (a half-written or foreign file). */
+export function readRuntimeFile(home) {
+    let raw;
+    try {
+        raw = fs.readFileSync(runtimeFilePath(home), "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const v = JSON.parse(raw);
+        if (Number.isInteger(v.pid) &&
+            Number.isInteger(v.port) &&
+            typeof v.url === "string" &&
+            typeof v.version === "string" &&
+            typeof v.startedAt === "string") {
+            return v;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return null;
+}
+/**
+ * Removes the file, but only if it's still ours: a second instance may have started since and written its own.
+ * Call it on a clean exit. Returns whether it removed anything.
+ */
+export function removeRuntimeFile(home, pid = process.pid) {
+    const info = readRuntimeFile(home);
+    if (!info || info.pid !== pid)
+        return false;
+    fs.rmSync(runtimeFilePath(home), { force: true });
+    return true;
+}
+/** Whether a process with this pid exists. EPERM means it exists but isn't ours, which still counts. */
+export function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** The runtime file, if the process it names is still alive. A crashed instance leaves a stale file behind. */
+export function readLiveRuntimeFile(home) {
+    const info = readRuntimeFile(home);
+    return info && isPidAlive(info.pid) ? info : null;
+}

package/packages/server/dist/service-log.d.ts

@@ -0,0 +1,29 @@
+/** Rotate once the log passes this. */
+export declare const ROTATE_AT_BYTES: number;
+/** How many rotated generations to keep (`service.log.1` … `.3`). */
+export declare const KEEP_GENERATIONS = 3;
+/** How often to look. */
+export declare const ROTATE_CHECK_MS: number;
+export interface RotateOptions {
+    maxBytes?: number;
+    keep?: number;
+    /** Where a warning goes. Failing to rotate is never fatal. */
+    warn?: (message: string) => void;
+}
+/** `<dataDir>/logs/service.log` — the one file both streams append to. */
+export declare function serviceLogFile(dataDir: string): string;
+/**
+ * Rotate `<dataDir>/logs/service.log` if it has grown past the limit.
+ *
+ * Returns true if it rotated. Never throws: a log directory that has become
+ * read-only is worth a warning, not a server that will not start.
+ */
+export declare function rotateServiceLog(dataDir: string, opts?: RotateOptions): boolean;
+/**
+ * Rotate now, then every {@link ROTATE_CHECK_MS}. Returns a stop function.
+ *
+ * The timer is unref'd, so this cannot hold the process open — which matters
+ * because the one thing worse than an unrotated log is a `paddock serve` that
+ * does not exit on Ctrl-C.
+ */
+export declare function startServiceLogRotation(dataDir: string, opts?: RotateOptions): () => void;

package/packages/server/dist/service-log.js

@@ -0,0 +1,104 @@
+/**
+ * Rotating the service log (SPEC §7: "the tool rotates its own log").
+ *
+ * The service's stdout and stderr are appended to `<dataDir>/logs/service.log`
+ * by the supervisor itself — launchd's `StandardOutPath`, systemd's
+ * `StandardOutput=append:`. Nothing else rotates it: a `systemd --user` unit
+ * gets no journal rotation because it is not using the journal, and macOS has
+ * never had anything that would. Left alone, an instance that has been up for
+ * months has a log file nobody can open.
+ *
+ * ## Why copy-and-truncate, and not rename
+ *
+ * The usual rotation is `rename(log, log.1)` then create a new `log`. That is
+ * exactly wrong here, because **we are not the writer**. The supervisor holds
+ * an open append-mode descriptor on the inode; renaming the path does not move
+ * the descriptor, so every subsequent line goes to `service.log.1` and the
+ * fresh `service.log` stays empty for ever. `logrotate`'s `copytruncate` exists
+ * for this case and this is it: copy the bytes out, then `truncate()` the
+ * original to zero. The descriptor's next write — `O_APPEND`, so the offset is
+ * re-derived from the file length — lands at 0.
+ *
+ * The cost is honest and small: a line written between the copy and the
+ * truncate is lost. The alternative costs every line after the first rotation.
+ *
+ * ## When it runs
+ *
+ * At boot, and then on an interval. Not on every write, because the writes do
+ * not come through this process's own logger — they come through a file
+ * descriptor the supervisor opened — so there is no write to hook. The timer is
+ * `unref`'d: a rotation pending must never be the reason the process will not
+ * exit.
+ *
+ * It is a no-op anywhere there is no service log, which is every foreground
+ * `paddock serve`: the file does not exist, so nothing is copied and nothing is
+ * truncated. No caller has to know whether it is running under a supervisor.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** Rotate once the log passes this. */
+export const ROTATE_AT_BYTES = 8 * 1024 * 1024;
+/** How many rotated generations to keep (`service.log.1` … `.3`). */
+export const KEEP_GENERATIONS = 3;
+/** How often to look. */
+export const ROTATE_CHECK_MS = 15 * 60 * 1000;
+/** `<dataDir>/logs/service.log` — the one file both streams append to. */
+export function serviceLogFile(dataDir) {
+    return path.join(dataDir, "logs", "service.log");
+}
+/**
+ * Rotate `<dataDir>/logs/service.log` if it has grown past the limit.
+ *
+ * Returns true if it rotated. Never throws: a log directory that has become
+ * read-only is worth a warning, not a server that will not start.
+ */
+export function rotateServiceLog(dataDir, opts = {}) {
+    const maxBytes = opts.maxBytes ?? ROTATE_AT_BYTES;
+    const keep = opts.keep ?? KEEP_GENERATIONS;
+    const file = serviceLogFile(dataDir);
+    try {
+        const size = fs.statSync(file).size;
+        if (size <= maxBytes)
+            return false;
+    }
+    catch {
+        // No log file: a foreground run, or a service that has not written yet.
+        return false;
+    }
+    try {
+        // Shuffle the generations down, oldest first, so nothing is overwritten
+        // before it has been moved. The oldest is dropped.
+        const gen = (n) => `${file}.${String(n)}`;
+        fs.rmSync(gen(keep), { force: true });
+        for (let n = keep - 1; n >= 1; n--) {
+            if (fs.existsSync(gen(n)))
+                fs.renameSync(gen(n), gen(n + 1));
+        }
+        fs.copyFileSync(file, gen(1));
+        // The truncate, not an unlink: see the header. The supervisor's descriptor
+        // has to keep working, and it only does if the inode survives.
+        fs.truncateSync(file, 0);
+        return true;
+    }
+    catch (err) {
+        opts.warn?.(`could not rotate ${file}: ${err.message}`);
+        return false;
+    }
+}
+/**
+ * Rotate now, then every {@link ROTATE_CHECK_MS}. Returns a stop function.
+ *
+ * The timer is unref'd, so this cannot hold the process open — which matters
+ * because the one thing worse than an unrotated log is a `paddock serve` that
+ * does not exit on Ctrl-C.
+ */
+export function startServiceLogRotation(dataDir, opts = {}) {
+    rotateServiceLog(dataDir, opts);
+    const timer = setInterval(() => {
+        rotateServiceLog(dataDir, opts);
+    }, ROTATE_CHECK_MS);
+    timer.unref();
+    return () => {
+        clearInterval(timer);
+    };
+}

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

@@ -1 +1,34 @@
+/**
+ * How long a clean shutdown gets before we exit anyway.
+ *
+ * The CLI contract requires the SIGTERM path to exit "within the unit's stop
+ * timeout" (SPEC §4, §8), and the tightest of those is **launchd's**: with no
+ * `ExitTimeOut` in the plist, a LaunchAgent gets 20 seconds before SIGKILL
+ * (systemd's user default is 90). So the budget is 20 seconds, and this sits
+ * inside it with room for the exit itself.
+ *
+ * The deadline matters because the two awaits below are not bounded by anything
+ * else. `app.close()` waits for in-flight requests and open WebSockets, and a
+ * browser holding `/ws` is the normal state of a running Paddock; `fleet.stop()`
+ * talks to subprocesses. Exceeding the budget is strictly worse than exiting at
+ * it: SIGKILL skips the rest of this function, so the runtime file would be left
+ * behind for the next instance's `busy` to find and the log would have no record
+ * of what was cut short.
+ */
+export declare const SHUTDOWN_DEADLINE_MS = 15000;
+/**
+ * The URL to record in `runtime.json` — the one a CLI on this machine can
+ * actually fetch, which is not always the one we bound.
+ *
+ * A wildcard bind is the normal case for a container or a dev box (`HOST=0.0.0.0`
+ * is what this repo's own `pm` wrapper injects), and `http://0.0.0.0:<port>` is
+ * not an address to connect TO. Node happens to resolve it to loopback on Linux
+ * and fails on some other stacks, so the file records loopback explicitly rather
+ * than relying on that. A real interface address is left alone: someone who
+ * bound `192.168.1.10` meant it, and that address reaches the server from here
+ * as well as from anywhere else.
+ *
+ * IPv6 gets brackets, because `new URL('http://::1:7233')` is not a URL.
+ */
+export declare function runtimeUrl(host: string, port: number): string;
 export declare function start(): Promise<void>;

package/packages/server/dist/start.js

@@ -1,21 +1,139 @@
 /**
- * Process lifecycle for a Paddock server: bind the port and wire signal-driven
- * shutdown. Split out of `index.ts` so the `paddock` CLI (src/cli/paddock.ts)
- * and the plain `node dist/index.js` entrypoint share one implementation.
+ * Process lifecycle for a Paddock server: bind the port, publish
+ * `runtime.json`, and wire signal-driven shutdown. Split out of `index.ts` so
+ * the `paddock` CLI (src/cli/paddock.ts) and the plain `node dist/index.js`
+ * entrypoint share one implementation.
  *
  * Config is resolved INSIDE `buildApp()`, not at module load, so a caller may
  * still mutate `process.env` right up until this function is invoked. The CLI
  * depends on that to apply its own defaults (e.g. a data dir under $HOME).
  */
 import { buildApp } from "./app.js";
+import { startServiceLogRotation } from "./service-log.js";
+import { removeRuntimeFile, writeRuntimeFile } from "./runtime-file.js";
+import { PADDOCK_VERSION } from "./version.js";
+/**
+ * How long a clean shutdown gets before we exit anyway.
+ *
+ * The CLI contract requires the SIGTERM path to exit "within the unit's stop
+ * timeout" (SPEC §4, §8), and the tightest of those is **launchd's**: with no
+ * `ExitTimeOut` in the plist, a LaunchAgent gets 20 seconds before SIGKILL
+ * (systemd's user default is 90). So the budget is 20 seconds, and this sits
+ * inside it with room for the exit itself.
+ *
+ * The deadline matters because the two awaits below are not bounded by anything
+ * else. `app.close()` waits for in-flight requests and open WebSockets, and a
+ * browser holding `/ws` is the normal state of a running Paddock; `fleet.stop()`
+ * talks to subprocesses. Exceeding the budget is strictly worse than exiting at
+ * it: SIGKILL skips the rest of this function, so the runtime file would be left
+ * behind for the next instance's `busy` to find and the log would have no record
+ * of what was cut short.
+ */
+export const SHUTDOWN_DEADLINE_MS = 15_000;
+/**
+ * The URL to record in `runtime.json` — the one a CLI on this machine can
+ * actually fetch, which is not always the one we bound.
+ *
+ * A wildcard bind is the normal case for a container or a dev box (`HOST=0.0.0.0`
+ * is what this repo's own `pm` wrapper injects), and `http://0.0.0.0:<port>` is
+ * not an address to connect TO. Node happens to resolve it to loopback on Linux
+ * and fails on some other stacks, so the file records loopback explicitly rather
+ * than relying on that. A real interface address is left alone: someone who
+ * bound `192.168.1.10` meant it, and that address reaches the server from here
+ * as well as from anywhere else.
+ *
+ * IPv6 gets brackets, because `new URL('http://::1:7233')` is not a URL.
+ */
+export function runtimeUrl(host, port) {
+    const loopback = {
+        "0.0.0.0": "127.0.0.1",
+        "::": "::1",
+        "": "127.0.0.1",
+    };
+    const h = loopback[host] ?? host;
+    return `http://${h.includes(":") ? `[${h}]` : h}:${String(port)}`;
+}
 export async function start() {
-    const { app, cfg, close } = await buildApp();
-    const shutdown = async () => {
-        await close();
+    const { app, cfg, close, hub } = await buildApp();
+    // Nothing else rotates the service log: the supervisor appends to it through
+    // its own descriptor, a `systemd --user` unit writing to a file gets no
+    // journal rotation, and macOS has nothing that would (SPEC §7). A no-op on a
+    // foreground run, where that file does not exist — see service-log.ts.
+    const stopRotation = startServiceLogRotation(cfg.dataDir, {
+        warn: (message) => {
+            app.log.warn(message);
+        },
+    });
+    /**
+     * Exit on SIGTERM/SIGINT having said what was cut short (SPEC §4, §8).
+     *
+     * Three things are deliberate here.
+     *
+     * **It records rather than finishes.** A chat turn is a `claude` subprocess
+     * that can run for minutes; no 20-second stop timeout can wait for one, and
+     * `herdctl.stop()` ends the fleet with `waitForJobs: false` precisely because
+     * waiting is not an option. So the contract's other half applies — record the
+     * work under way — and the record is this `warn` line in the service log,
+     * which is the one artefact that survives the restart and which
+     * `paddock service logs` reads. What is NOT done, and should not be, is
+     * writing a note into the cut-short chat's transcript: `claude` owns that file
+     * and may append to it after we are gone, so a server-side write cannot be
+     * ordered against the subprocess's own and would be the resurrection race
+     * `turn-interlock.ts` exists to avoid.
+     *
+     * The reason a count is enough: `/api/busy` reports the same numbers BEFORE
+     * the stop, and `paddock service stop` refuses on them. The log line is for
+     * the race §4 admits — work that started between the check and the signal.
+     *
+     * **It is idempotent.** A supervisor that sends SIGTERM twice, or a Ctrl-C
+     * after a SIGTERM, used to re-enter `close()` concurrently: a second
+     * `app.close()` on a closing Fastify rejects, and a second `fleet.stop()`
+     * races the first. The guard makes the extra signals no-ops.
+     *
+     * **It exits 0.** The unit's `Restart=always` / `KeepAlive` means the
+     * supervisor brings Paddock back whatever the code; 0 is what makes a logout
+     * or a `service stop` read as a clean stop rather than a crash in the logs.
+     */
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        const running = hub.runningSessions().length;
+        app.log.warn(running > 0
+            ? `${signal}: shutting down with ${running} chat turn(s) in flight — they are being cut short. ` +
+                "Run `paddock busy` before a stop or an update to see this before it happens."
+            : `${signal}: shutting down, no chat turn in flight.`);
+        stopRotation();
+        // Published once we were listening; removed here so a `busy` or a
+        // `service status` run after this exit does not find a live-looking
+        // instance. Before the slow awaits, because this is the part that must land
+        // even if they overrun the deadline below.
+        removeRuntimeFile(cfg.dataDir);
+        // Bounded: see SHUTDOWN_DEADLINE_MS. `exit(0)` either way, so a hung
+        // `app.close()` cannot turn a stop into a SIGKILL.
+        await Promise.race([close(), new Promise((r) => setTimeout(r, SHUTDOWN_DEADLINE_MS))]).catch(() => undefined);
         process.exit(0);
     };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
     await app.listen({ port: cfg.port, host: cfg.host });
+    // `<dataDir>/runtime.json`, 0600, written only once we are actually listening
+    // (SPEC §4) — it is how `paddock busy`, and later `update`, find THIS instance
+    // without guessing a port. A failure to write it is logged and not fatal: the
+    // server is up and serving, and the one thing that stops working is a CLI
+    // finding it, which is better than refusing to run.
+    try {
+        writeRuntimeFile(cfg.dataDir, {
+            pid: process.pid,
+            port: cfg.port,
+            url: runtimeUrl(cfg.host, cfg.port),
+            version: PADDOCK_VERSION,
+        });
+    }
+    catch (err) {
+        app.log.warn(`could not write ${cfg.dataDir}/runtime.json (${err.message}) — ` +
+            "`paddock busy` will report this instance as not running");
+    }
     app.log.info(`paddock-server listening on http://${cfg.host}:${cfg.port}`);
 }

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

@@ -0,0 +1,3 @@
+export declare const PADDOCK_VERSION: string;
+/** What the product is called in prose, for `serve`'s banner line (SPEC §3). */
+export declare const PADDOCK_NAME = "Paddock";

package/packages/server/dist/version.js

@@ -0,0 +1,32 @@
+/**
+ * The running Paddock version, resolved once.
+ *
+ * Three surfaces have to agree on this string and now do, because they read it
+ * from one place: the OpenAPI document's `info.version` (`app.ts`), the
+ * management MCP server's advertised version, and — the reason this module
+ * exists — `GET /api/health`, which the CLI contract requires to carry the
+ * version so that `paddock service status` can compare the version that is
+ * RUNNING with the version that is installed (SPEC §8).
+ *
+ * `createRequire(import.meta.url)` resolves against this module's own path, so
+ * `../package.json` is `packages/server/package.json` from `dist/version.js` in
+ * both layouts the package ships in (the repo, and the synthesized npm tarball
+ * — see `scripts/make-npm-package.mjs`, which keeps that manifest precisely so
+ * a version is readable at runtime).
+ *
+ * Never throws. A missing or unreadable manifest degrades to `"0.0.0"`: a
+ * health endpoint that 500s because it could not find its own version would be
+ * a worse failure than one that answers with a version nobody shipped.
+ */
+import { createRequire } from "node:module";
+export const PADDOCK_VERSION = (() => {
+    try {
+        const require = createRequire(import.meta.url);
+        return require("../package.json").version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+/** What the product is called in prose, for `serve`'s banner line (SPEC §3). */
+export const PADDOCK_NAME = "Paddock";

package/packages/server/dist/ws-context.d.ts

@@ -14,6 +14,7 @@ import type { SweepService } from "./sweep.js";
 import type { PaddockConfig } from "./config.js";
 import type { DriveMode } from "./models.js";
 import type { SessionHub } from "./session-hub.js";
+import type { BackgroundRegistry } from "./background-live.js";
 import type { AttachmentStore } from "./attachments.js";
 import type { QueuedMessageStore } from "./queued-message.js";
 import type { ArchiveStore } from "./archive.js";
@@ -152,6 +153,14 @@ export type FireTrigger = (slug: string, triggerName: string) => Promise<string
 export interface ChatHandlerContext {
     deps: ChatHandlerDeps;
     hub: SessionHub;
+    /**
+     * The live background-work registry (#604). Here for the same reason `hub` is:
+     * it is per-server state owned by the WS layer that a NON-socket caller has to
+     * be able to read. `GET /api/busy` is that caller — a turn can end while its
+     * background tasks keep running, so the hub alone would report a session with
+     * a live sub-agent as idle (CLI contract SPEC §4).
+     */
+    background: BackgroundRegistry;
     startAgentTurn: StartAgentTurn;
     composePreloadedPrompt: ComposePreloadedPrompt;
     fireTrigger: FireTrigger;

package/packages/server/dist/ws-turn.js

@@ -85,6 +85,7 @@ export function makeTurnEngine(engine) {
     const selfMcpCtx = {
         deps,
         hub,
+        background,
         startAgentTurn,
         composePreloadedPrompt: triggers.composePreloadedPrompt,
         fireTrigger: triggers.fireTrigger,

package/packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paddock/server",
-  "version": "0.79.1",
+  "version": "0.81.0",
   "private": true,
   "type": "module"
 }

package/packages/web/dist/assets/{DeleteProjectDialog-BcxJMA1w.js → DeleteProjectDialog-D8oIJ8HC.js}

@@ -1,2 +1,2 @@
-import{r as l,e as k,j as s,A as y,d as p,a as w}from"./index-C4tsPSvG.js";import{c as N}from"./lastTab-CU1zsF0j.js";function v({open:e,title:t,message:c,confirmLabel:n="Delete",cancelLabel:o="Cancel",danger:a=!0,wide:h=!1,dismissOnBackdrop:b=!0,onConfirm:g,onClose:d}){const[r,m]=l.useState(!1),[f,u]=l.useState(null);if(l.useEffect(()=>{e?u(null):m(!1)},[e]),k(e&&!r,d),!e)return null;const j=async()=>{m(!0),u(null);try{await g()}catch(i){u(i instanceof Error?i.message:"Action failed"),m(!1)}};return s.jsx("div",{className:"fixed inset-0 z-[60] flex items-center justify-center bg-overlay p-4 backdrop-blur-sm",onClick:()=>b&&!r&&d(),children:s.jsxs("div",{className:`w-full ${h?"max-w-md":"max-w-sm"} animate-scale-in rounded-2xl border border-edge bg-surface-raised p-6 shadow-2xl`,onClick:i=>i.stopPropagation(),role:"alertdialog","aria-modal":"true",children:[s.jsxs("div",{className:"flex items-start gap-3",children:[a&&s.jsx("span",{className:"mt-0.5 flex h-9 w-9 shrink-0 items-center justify-center rounded-xl bg-danger-soft text-danger",children:s.jsx(y,{width:18,height:18})}),s.jsxs("div",{className:"min-w-0",children:[s.jsx("h2",{className:"text-base font-semibold",children:t}),s.jsx("div",{className:"mt-1.5 text-sm text-fg-muted",children:c})]})]}),f&&s.jsx("p",{className:"mt-4 rounded-lg bg-danger-soft px-3 py-2 text-sm text-danger",children:f}),s.jsxs("div",{className:"mt-5 flex justify-end gap-2",children:[s.jsx("button",{type:"button",className:"btn-ghost",onClick:d,disabled:r,children:o}),s.jsx("button",{type:"button",className:a?"btn btn-danger":"btn-primary",onClick:j,disabled:r,children:r?"Working…":n})]})]})})}function P(e,t){return e===t?!0:e.startsWith(t.endsWith("/")?t:`${t}/`)}function x(e){return!P(e.workingDir,e.dir)}function C({project:e}){const t=s.jsx("span",{className:"font-medium text-fg",children:e.name});return x(e)?s.jsxs(s.Fragment,{children:[t," will be unlinked. Paddock’s notes, settings and chats for it are permanently removed, and this cannot be undone — but the directory it works in is left alone:",s.jsx("span",{className:"mt-1.5 block break-all font-mono text-xs text-fg",children:e.workingDir}),s.jsx("span",{className:"mt-1.5 block",children:"Nothing in there is deleted."})]}):s.jsxs(s.Fragment,{children:[t," and all its chats and files will be permanently removed. This cannot be undone."]})}function D(){const{remove:e}=p();return l.useCallback(async t=>{await w.deleteProject(t),e(t),N(t)},[e])}function W({project:e,open:t,onClose:c,onDeleted:n}){const o=D(),a=x(e);return s.jsx(v,{open:t,title:"Delete project?",message:s.jsx(C,{project:e}),confirmLabel:"Delete project",wide:a,dismissOnBackdrop:!a,onConfirm:async()=>{await o(e.slug),n==null||n()},onClose:c})}export{v as C,W as D,x as d};
+import{r as l,e as k,j as s,A as y,d as p,a as w}from"./index-CvaWErFv.js";import{c as N}from"./lastTab-CU1zsF0j.js";function v({open:e,title:t,message:c,confirmLabel:n="Delete",cancelLabel:o="Cancel",danger:a=!0,wide:h=!1,dismissOnBackdrop:b=!0,onConfirm:g,onClose:d}){const[r,m]=l.useState(!1),[f,u]=l.useState(null);if(l.useEffect(()=>{e?u(null):m(!1)},[e]),k(e&&!r,d),!e)return null;const j=async()=>{m(!0),u(null);try{await g()}catch(i){u(i instanceof Error?i.message:"Action failed"),m(!1)}};return s.jsx("div",{className:"fixed inset-0 z-[60] flex items-center justify-center bg-overlay p-4 backdrop-blur-sm",onClick:()=>b&&!r&&d(),children:s.jsxs("div",{className:`w-full ${h?"max-w-md":"max-w-sm"} animate-scale-in rounded-2xl border border-edge bg-surface-raised p-6 shadow-2xl`,onClick:i=>i.stopPropagation(),role:"alertdialog","aria-modal":"true",children:[s.jsxs("div",{className:"flex items-start gap-3",children:[a&&s.jsx("span",{className:"mt-0.5 flex h-9 w-9 shrink-0 items-center justify-center rounded-xl bg-danger-soft text-danger",children:s.jsx(y,{width:18,height:18})}),s.jsxs("div",{className:"min-w-0",children:[s.jsx("h2",{className:"text-base font-semibold",children:t}),s.jsx("div",{className:"mt-1.5 text-sm text-fg-muted",children:c})]})]}),f&&s.jsx("p",{className:"mt-4 rounded-lg bg-danger-soft px-3 py-2 text-sm text-danger",children:f}),s.jsxs("div",{className:"mt-5 flex justify-end gap-2",children:[s.jsx("button",{type:"button",className:"btn-ghost",onClick:d,disabled:r,children:o}),s.jsx("button",{type:"button",className:a?"btn btn-danger":"btn-primary",onClick:j,disabled:r,children:r?"Working…":n})]})]})})}function P(e,t){return e===t?!0:e.startsWith(t.endsWith("/")?t:`${t}/`)}function x(e){return!P(e.workingDir,e.dir)}function C({project:e}){const t=s.jsx("span",{className:"font-medium text-fg",children:e.name});return x(e)?s.jsxs(s.Fragment,{children:[t," will be unlinked. Paddock’s notes, settings and chats for it are permanently removed, and this cannot be undone — but the directory it works in is left alone:",s.jsx("span",{className:"mt-1.5 block break-all font-mono text-xs text-fg",children:e.workingDir}),s.jsx("span",{className:"mt-1.5 block",children:"Nothing in there is deleted."})]}):s.jsxs(s.Fragment,{children:[t," and all its chats and files will be permanently removed. This cannot be undone."]})}function D(){const{remove:e}=p();return l.useCallback(async t=>{await w.deleteProject(t),e(t),N(t)},[e])}function W({project:e,open:t,onClose:c,onDeleted:n}){const o=D(),a=x(e);return s.jsx(v,{open:t,title:"Delete project?",message:s.jsx(C,{project:e}),confirmLabel:"Delete project",wide:a,dismissOnBackdrop:!a,onConfirm:async()=>{await o(e.slug),n==null||n()},onClose:c})}export{v as C,W as D,x as d};
 

package/packages/web/dist/assets/DiscoverPage-CQlzxsn4.js

@@ -0,0 +1,2 @@
+import{j as o}from"./index-CvaWErFv.js";import{D as r}from"./DiscoverView-o0KCr3aB.js";import{u as e}from"./documentTitle-BwTIA8rI.js";import"./Surfaces-MkhXlB8z.js";function p(){return e(["Discover"]),o.jsx(r,{})}export{p as DiscoverPage};
+