@edspencer/paddock 0.80.0 → 0.82.0

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

@@ -0,0 +1,113 @@
+/**
+ * Paddock's bindings for the generic updater (`cli/update/`): the package name,
+ * the service hooks, the busy guard and the health probe
+ * (CLI contract SPEC §1, §5, §6).
+ *
+ * Kept separate from `cli/update/*` for the same reason `busy-command.ts` is
+ * kept separate from `cli/busy.ts`: those files are the ones wave C4 lifts into
+ * `reference/`, and everything Paddock-specific lives on this side of the seam.
+ * Four things are genuinely Paddock's own, and they are the four hooks:
+ *
+ * - **the package name and layout.** `@edspencer/paddock` is SYNTHESIZED from
+ *   two private workspaces (`scripts/make-npm-package.mjs`), so the published
+ *   tarball's root manifest carries that name and the CLI sits at
+ *   `packages/server/dist/cli/paddock.js` under it. In the repo, nothing is
+ *   called `@edspencer/paddock` at all — which is exactly why §6's walk-up
+ *   reports a checkout there, correctly.
+ * - **the busy check**, including the keeper-chat trap: a Paddock chat that
+ *   runs `paddock update` is itself one of the turns the answer counts.
+ * - **the service**, through `cli/service/index.ts`, so the unit is read by the
+ *   code that writes it.
+ * - **the health probe**, which waits for the version rather than for a 200.
+ */
+import path from "node:path";
+import { createOutput } from "./output.js";
+import { EXIT } from "./exit-codes.js";
+import { UPDATE_SYNOPSIS } from "./args.js";
+import { guardBusy } from "./busy.js";
+import { PADDOCK_NOUNS, paddockBusyHint } from "./busy-command.js";
+import { PADDOCK_NAME, PADDOCK_VERSION } from "../version.js";
+import { updateServiceHooks } from "./service/index.js";
+import { waitForVersion } from "./service/ready.js";
+import { runUpdate } from "./update/update.js";
+/** The published package. Used for the registry, the install detection and the install command. */
+export const PADDOCK_PACKAGE = "@edspencer/paddock";
+/** Where the CLI sits inside that package. See the layout note in make-npm-package.mjs. */
+export const PADDOCK_BIN_SUBPATH = path.join("packages", "server", "dist", "cli", "paddock.js");
+/** The image an `update` inside a container tells you to pull (SPEC §6, §9). */
+export const PADDOCK_IMAGE = "ghcr.io/edspencer/paddock";
+/** Release notes for a version — the `Changes:` line of SPEC §3's notice. */
+export function paddockChangelogUrl(version) {
+    return `https://github.com/edspencer/paddock/releases/tag/v${version}`;
+}
+/**
+ * `paddock update [--check] [--to <version|tag>] [--yes] [--force] [--json]`
+ * (SPEC §1, §5). `upgrade` reaches the same place.
+ *
+ * `ctx` is the same {@link ServiceContext} `paddock service` is handed, so the
+ * two agree about which Node, which script and which unit — an `update` that
+ * refreshed a different unit from the one `status` reports would be the worst
+ * possible kind of nearly-working.
+ */
+export async function runUpdateCommand(opts, ctx) {
+    const out = createOutput({ tool: "paddock", json: opts.json === true });
+    // The service layer decides the home, because the home has to be the one
+    // `service status` reads the update cache from: the UNIT's data dir when
+    // there is a unit, and this invocation's otherwise (#824's rule).
+    let service;
+    try {
+        service = updateServiceHooks(ctx);
+    }
+    catch (err) {
+        // An unsupported platform — `backendFor` throws for anything but darwin and
+        // linux. `update` still has work it could do there in principle, but it
+        // cannot refresh a unit, and pretending otherwise is how a Windows user
+        // gets a half-finished update. Report it as the failure it is.
+        return out.error(err instanceof Error ? err.message : String(err));
+    }
+    const product = {
+        name: PADDOCK_NAME,
+        tool: "paddock",
+        packageName: PADDOCK_PACKAGE,
+        envPrefix: "PADDOCK",
+        home: service.home,
+        currentVersion: PADDOCK_VERSION,
+        // NOT realpath'd: `findCli` re-resolves this symlink after the install,
+        // which is how it finds the new CLI under a package manager that puts the
+        // version in the package's real path. SPEC §6's walk-up realpaths it
+        // itself.
+        entry: process.argv[1] ?? ctx.scriptPath,
+        binSubpath: PADDOCK_BIN_SUBPATH,
+        image: PADDOCK_IMAGE,
+        usage: UPDATE_SYNOPSIS,
+        changelogUrl: paddockChangelogUrl,
+        guardBusy: async ({ force, home }) => {
+            const refusal = await guardBusy({
+                home,
+                out,
+                name: PADDOCK_NAME,
+                nouns: PADDOCK_NOUNS,
+                hint: paddockBusyHint,
+                ...(force ? { force: true } : {}),
+            });
+            if (refusal === null)
+                return null;
+            // The way past it, spelled out — the same shape `service stop` prints.
+            out.warn("\n    paddock update --force      update it anyway\n");
+            return EXIT.busy;
+        },
+        service: service.hooks,
+        waitForVersion: async ({ url, version, timeoutMs }) => waitForVersion({ url, version, timeoutMs }),
+    };
+    // `CliOptions` spells `--check` as `checkOnly`, because `check` reads as a
+    // verb in a bag of flags that also carries `write` and `follow`. Mapped here
+    // rather than renamed in the generic module, which is the one the other five
+    // tools copy.
+    return runUpdate(product, {
+        ...(opts.checkOnly === true ? { check: true } : {}),
+        ...(opts.to !== undefined ? { to: opts.to } : {}),
+        ...(opts.yes === true ? { yes: true } : {}),
+        ...(opts.force === true ? { force: true } : {}),
+        ...(opts.json === true ? { json: true } : {}),
+    }, { out });
+}

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

@@ -371,6 +371,25 @@ export declare class HerdctlService {
      * error, returns `false` — the pre-#397 behaviour.
      */
     isSdkSessionLive(sessionId: string): boolean;
+    /**
+     * How many scheduler jobs are running right now, read from memory.
+     *
+     * This exists for `GET /api/busy` (CLI contract SPEC §4), which must read
+     * in-memory state and never walk the disk. The number the contract's ROADMAP
+     * names is `fleetStatus().counts.runningJobs` — but {@link fleetStatus} is
+     * built from `getAgentInfo()`, which re-reads the fleet state FILE on every
+     * call, and that re-parse has been this server's single largest CPU cost.
+     *
+     * The two are the same number. `counts.runningJobs` is
+     * `Σ scheduler.getRunningJobCount(agent.qualifiedName)` over the configured
+     * agents, and `getTotalRunningJobCount()` is the size of the same scheduler
+     * map keyed `<agent>/<schedule>` — one entry per running agent+schedule pair
+     * either way. So this reads the authority directly instead of a derived
+     * snapshot of it.
+     *
+     * Null-safe like {@link isSdkSessionLive}: no fleet or no scheduler means 0.
+     */
+    runningJobCount(): number;
     fleetStatus(): Promise<FleetStatus>;
     agents(): Promise<AgentInfo[]>;
     /**

package/packages/server/dist/herdctl.js

@@ -528,6 +528,32 @@ export class HerdctlService {
             return false;
         }
     }
+    /**
+     * How many scheduler jobs are running right now, read from memory.
+     *
+     * This exists for `GET /api/busy` (CLI contract SPEC §4), which must read
+     * in-memory state and never walk the disk. The number the contract's ROADMAP
+     * names is `fleetStatus().counts.runningJobs` — but {@link fleetStatus} is
+     * built from `getAgentInfo()`, which re-reads the fleet state FILE on every
+     * call, and that re-parse has been this server's single largest CPU cost.
+     *
+     * The two are the same number. `counts.runningJobs` is
+     * `Σ scheduler.getRunningJobCount(agent.qualifiedName)` over the configured
+     * agents, and `getTotalRunningJobCount()` is the size of the same scheduler
+     * map keyed `<agent>/<schedule>` — one entry per running agent+schedule pair
+     * either way. So this reads the authority directly instead of a derived
+     * snapshot of it.
+     *
+     * Null-safe like {@link isSdkSessionLive}: no fleet or no scheduler means 0.
+     */
+    runningJobCount() {
+        try {
+            return this.fleet?.getScheduler()?.getTotalRunningJobCount() ?? 0;
+        }
+        catch {
+            return 0;
+        }
+    }
     async fleetStatus() {
         return this.manager.getFleetStatus();
     }

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

@@ -6,8 +6,14 @@ 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).
@@ -128,6 +134,45 @@ export function registerMetaRoutes(app, ctx) {
             },
         },
     }, 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/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,7 +1,8 @@
 /**
- * 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
@@ -9,8 +10,51 @@
  */
 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 { 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
@@ -20,13 +64,76 @@ export async function start() {
             app.log.warn(message);
         },
     });
-    const shutdown = async () => {
+    /**
+     * 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();
-        await close();
+        // 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/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.80.0",
+  "version": "0.82.0",
   "private": true,
   "type": "module"
 }

package/packages/web/dist/assets/{DeleteProjectDialog-DHczLhwQ.js → DeleteProjectDialog-CphdGB3R.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-DN82do6Z.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-CHOtvlnO.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-C4OPLNO8.js

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