@edspencer/paddock 0.79.1 → 0.81.0

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

@@ -22,14 +22,23 @@ export interface ServiceSpec {
      * interpreter explicitly removes the lookup entirely.
      */
     scriptPath: string;
-    /** Arguments after the script: always starts with the `start` verb. */
+    /** Arguments after the script: always starts with the `serve` verb. */
     args: string[];
     /** A directory the service can sit in that it certainly owns. */
     workingDirectory: string;
-    /** Where stdout/stderr go on launchd. systemd uses journald and ignores these. */
-    stdoutPath: string;
-    stderrPath: string;
-    /** PATH for the service, captured at install time. */
+    /**
+     * The one file both streams append to, on every OS (SPEC §7).
+     *
+     * launchd names it twice (`StandardOutPath` and `StandardErrorPath`); systemd
+     * names it twice as well (`StandardOutput=append:` / `StandardError=append:`)
+     * rather than using the journal. That is what makes `paddock service logs`
+     * one Node implementation instead of two, and it is also what makes the
+     * Linux logs survive a journal that is volatile or rate-limited — the default
+     * on plenty of distributions, where `journalctl --user` after a reboot showed
+     * nothing at all.
+     */
+    logPath: string;
+    /** PATH for the service: Node's bin, the usable inherited entries, the system dirs. */
     pathEnv: string;
 }
 export interface SpecInput {
@@ -44,6 +53,19 @@ export interface SpecInput {
     dataDirArg?: string;
     verbose?: boolean;
     pathEnv?: string;
+    /**
+     * Injected by tests: "is this an existing directory?", and which system
+     * directories to append.
+     *
+     * Not a knob — a necessity. `servicePath` keeps only directories that EXIST,
+     * which is what stops a unit naming a `node` that went away with a terminal
+     * (path-env.ts). That makes the rendered unit depend on the filesystem it was
+     * rendered on, so a golden plist asserted on this box would differ from the
+     * same golden on a macOS runner, for reasons that have nothing to do with the
+     * code under test. Pinning both makes the goldens about the renderer again.
+     */
+    pathExists?: (p: string) => boolean;
+    systemDirs?: readonly string[];
 }
 /**
  * The service's own directory inside the data dir.
@@ -58,14 +80,31 @@ export interface SpecInput {
  * subdirectory is neither.
  */
 export declare function serviceDir(dataDir: string): string;
+/**
+ * Where the service's log lives: `<dataDir>/logs/service.log` (SPEC §7).
+ *
+ * One file, both streams, every platform — so `paddock service logs` is one
+ * implementation and the answer to "where are the logs" is one path. It is NOT
+ * under {@link serviceDir}: the logs outlive any one install (`uninstall` keeps
+ * them deliberately), and the server rotates this file itself
+ * (`service-log.ts`), which means something other than the service CLI has to
+ * be able to name it from the data dir alone.
+ */
+export declare function logsDir(dataDir: string): string;
+/** The single log file both streams append to. */
+export declare function serviceLogPath(dataDir: string): string;
 /** The data dir the service will use, resolved the same way `paddock.ts` does. */
 export declare function defaultDataDir(homeDir?: string): string;
 /**
  * Assemble the spec.
  *
- * The argument vector leads with the `start` verb even though bare `paddock`
+ * The argument vector leads with the `serve` verb even though bare `paddock`
  * would do the same thing. It costs nothing and it is the difference between
  * `launchctl print` showing an argv you can read and one you have to recognise.
+ * It was `start` until the CLI contract made `serve` the name for running in
+ * the foreground (SPEC §1); `start` is a permanent alias, so a unit written by
+ * an older Paddock keeps working untouched and only gets `serve` when something
+ * rewrites it.
  *
  * `--data-dir` is forwarded ONLY when the user passed it. The default of
  * setting nothing is load-bearing: with no data dir named anywhere, the service

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

@@ -10,6 +10,7 @@
  */
 import os from "node:os";
 import path from "node:path";
+import { servicePath } from "./path-env.js";
 /**
  * Reverse-DNS on macOS, plain on Linux. Both are stable identifiers a user may
  * end up typing (`launchctl print gui/501/net.edspencer.paddock`,
@@ -37,6 +38,23 @@ export const DEFAULT_PORT = "7233";
 export function serviceDir(dataDir) {
     return path.join(dataDir, "service");
 }
+/**
+ * Where the service's log lives: `<dataDir>/logs/service.log` (SPEC §7).
+ *
+ * One file, both streams, every platform — so `paddock service logs` is one
+ * implementation and the answer to "where are the logs" is one path. It is NOT
+ * under {@link serviceDir}: the logs outlive any one install (`uninstall` keeps
+ * them deliberately), and the server rotates this file itself
+ * (`service-log.ts`), which means something other than the service CLI has to
+ * be able to name it from the data dir alone.
+ */
+export function logsDir(dataDir) {
+    return path.join(dataDir, "logs");
+}
+/** The single log file both streams append to. */
+export function serviceLogPath(dataDir) {
+    return path.join(logsDir(dataDir), "service.log");
+}
 /** The data dir the service will use, resolved the same way `paddock.ts` does. */
 export function defaultDataDir(homeDir = os.homedir()) {
     return path.join(homeDir, ".paddock");
@@ -44,9 +62,13 @@ export function defaultDataDir(homeDir = os.homedir()) {
 /**
  * Assemble the spec.
  *
- * The argument vector leads with the `start` verb even though bare `paddock`
+ * The argument vector leads with the `serve` verb even though bare `paddock`
  * would do the same thing. It costs nothing and it is the difference between
  * `launchctl print` showing an argv you can read and one you have to recognise.
+ * It was `start` until the CLI contract made `serve` the name for running in
+ * the foreground (SPEC §1); `start` is a permanent alias, so a unit written by
+ * an older Paddock keeps working untouched and only gets `serve` when something
+ * rewrites it.
  *
  * `--data-dir` is forwarded ONLY when the user passed it. The default of
  * setting nothing is load-bearing: with no data dir named anywhere, the service
@@ -58,7 +80,7 @@ export function defaultDataDir(homeDir = os.homedir()) {
  * service opening a browser tab at login is not a feature.
  */
 export function buildSpec(input) {
-    const args = ["start"];
+    const args = ["serve"];
     if (input.port !== undefined)
         args.push("--port", input.port);
     if (input.host !== undefined)
@@ -67,15 +89,20 @@ export function buildSpec(input) {
         args.push("--data-dir", input.dataDirArg);
     if (input.verbose === true)
         args.push("--verbose");
-    const dir = serviceDir(input.dataDir);
     return {
         nodePath: input.nodePath,
         scriptPath: input.scriptPath,
         args,
-        workingDirectory: dir,
-        stdoutPath: path.join(dir, "paddock.log"),
-        stderrPath: path.join(dir, "paddock.error.log"),
-        pathEnv: input.pathEnv ?? "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
+        workingDirectory: serviceDir(input.dataDir),
+        logPath: serviceLogPath(input.dataDir),
+        // Node's own bin directory leads, so the interpreter the unit names can
+        // find its neighbours; `servicePath` drops the installing shell's
+        // per-session entries. See path-env.ts for why inheriting PATH verbatim
+        // writes a unit that rots when a terminal closes.
+        pathEnv: servicePath(path.dirname(input.nodePath), input.pathEnv, {
+            ...(input.pathExists !== undefined ? { exists: input.pathExists } : {}),
+            ...(input.systemDirs !== undefined ? { systemDirs: input.systemDirs } : {}),
+        }),
     };
 }
 /**

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

@@ -1,5 +1,5 @@
 import { type ServiceSpec } from "./spec.js";
-import type { Runner, ServiceBackend } from "./backend.js";
+import type { RunResult, Runner, ServiceBackend } from "./backend.js";
 /**
  * `~/.config/systemd/user/paddock.service`, honouring `XDG_CONFIG_HOME`.
  *
@@ -28,6 +28,17 @@ import type { Runner, ServiceBackend } from "./backend.js";
  * caller with no opinion still gets the right answer.)
  */
 export declare function unitPath(homeDir?: string, xdgConfigHome?: string): string;
+/** One `ExecStart` word: specifiers and variables escaped, quoted when it has to be. */
+export declare function execWord(a: string): string;
+/**
+ * The other way: the words of an `ExecStart` line.
+ *
+ * Reads both shapes on purpose. A unit written before #796's quoting is a bare
+ * whitespace-separated line, and its owner is exactly the person whose `status`
+ * has to keep working — so unquoted words pass through unchanged, and quoted
+ * ones are unescaped.
+ */
+export declare function execWords(line: string): string[];
 /**
  * Render the unit.
  *
@@ -47,11 +58,32 @@ export declare function unitPath(homeDir?: string, xdgConfigHome?: string): stri
  * "start at login" for a user unit; `multi-user.target` is the system-unit
  * spelling and does nothing here.
  *
- * No `StandardOutput=` — a user unit's output goes to the journal, which is
- * where a Linux user will look, and duplicating it into a file would give two
- * answers to "where are the logs".
+ * ## Logs go to a file, not the journal (SPEC §7)
+ *
+ * `StandardOutput=append:` / `StandardError=append:` name one file, the same
+ * one launchd's two keys name. The journal was the obvious choice and the wrong
+ * one for three reasons: `journalctl --user` shows nothing at all on a distro
+ * whose journal is volatile (the output is gone after a reboot, which is
+ * exactly when someone looks); it makes "where are the logs" have a different
+ * answer on each platform, so `paddock service logs` would be two
+ * implementations; and it rules out Windows, which the contract requires
+ * nothing rule out.
+ *
+ * The directory has to exist first — systemd creates the file, not its parent —
+ * which `install` below does.
+ *
+ * ## Every ExecStart word is quoted
+ *
+ * `%` starts a specifier anywhere in a unit file and `$` starts a variable in
+ * `ExecStart`, so both are escaped; a word containing whitespace, a quote or a
+ * backslash is quoted. Paths with a space in them are the common case
+ * (`/Users/Ed Spencer/.paddock`), and the old unqualified `join(" ")` wrote a
+ * unit systemd then split into the wrong arguments — a service that fails at
+ * login having printed nothing.
  */
 export declare function renderUnit(spec: ServiceSpec): string;
+/** The log file an installed unit appends to, or undefined if it names none. */
+export declare function parseUnitLogPath(text: string): string | undefined;
 /**
  * Does an installed unit carry `Restart=always` (#872)?
  *
@@ -64,4 +96,15 @@ export declare function renderUnit(spec: ServiceSpec): string;
 export declare function unitKeepsAlive(text: string): boolean;
 /** Read `ExecStart=` back out of an installed unit, split into an argv. */
 export declare function parseUnitArgv(text: string): string[];
+/**
+ * What a `systemctl` failure means, in the manager's own words where it has any.
+ *
+ * The `status === null` branch is the one QA found: `spawnSync` reports a
+ * missing binary that way, with no output at all, so the message was
+ * `systemctl --user enable --now failed (exit null).` and then a blank line —
+ * which tells someone on a container with no systemd nothing whatsoever. That
+ * is also the single likeliest way this command fails on a machine it was never
+ * going to work on.
+ */
+export declare function systemctlFailure(args: string[], r: RunResult): string;
 export declare function createSystemdBackend(run: Runner, homeDir?: string, xdgConfigHome?: string): ServiceBackend;

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

@@ -59,6 +59,39 @@ export function unitPath(homeDir, xdgConfigHome) {
             : (process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config")));
     return path.join(base, "systemd", "user", SYSTEMD_UNIT);
 }
+/**
+ * Unit-file escaping, ported from Local Review's `server/service/systemd.ts`
+ * (`pct`, `cEscape`, `cUnescape`, `execWord`, `execWords`) @ cli-contract spec
+ * 0.1; local changes: doc comments only. Wave C4 moves these to
+ * `reference/service/` and re-syncs.
+ *
+ * `%` starts a specifier EVERYWHERE in a unit file, so it is doubled; `$`
+ * starts a variable in `ExecStart`, so it is doubled there too.
+ */
+const pct = (s) => s.replace(/%/g, "%%");
+const cEscape = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\t/g, "\\t");
+const cUnescape = (s) => s.replace(/\\(.)/g, (_, c) => (c === "n" ? "\n" : c === "t" ? "\t" : c));
+/** One `ExecStart` word: specifiers and variables escaped, quoted when it has to be. */
+export function execWord(a) {
+    const s = pct(a).replace(/\$/g, "$$$$");
+    return s === "" || /[\s"'\\;]/.test(s) ? `"${cEscape(s)}"` : s;
+}
+/**
+ * The other way: the words of an `ExecStart` line.
+ *
+ * Reads both shapes on purpose. A unit written before #796's quoting is a bare
+ * whitespace-separated line, and its owner is exactly the person whose `status`
+ * has to keep working — so unquoted words pass through unchanged, and quoted
+ * ones are unescaped.
+ */
+export function execWords(line) {
+    const out = [];
+    for (const m of line.matchAll(/"((?:[^"\\]|\\.)*)"|(\S+)/g)) {
+        const w = m[1] !== undefined ? cUnescape(m[1]) : m[2];
+        out.push(w.replace(/\$\$/g, "$").replace(/%%/g, "%"));
+    }
+    return out;
+}
 /**
  * Render the unit.
  *
@@ -78,21 +111,44 @@ export function unitPath(homeDir, xdgConfigHome) {
  * "start at login" for a user unit; `multi-user.target` is the system-unit
  * spelling and does nothing here.
  *
- * No `StandardOutput=` — a user unit's output goes to the journal, which is
- * where a Linux user will look, and duplicating it into a file would give two
- * answers to "where are the logs".
+ * ## Logs go to a file, not the journal (SPEC §7)
+ *
+ * `StandardOutput=append:` / `StandardError=append:` name one file, the same
+ * one launchd's two keys name. The journal was the obvious choice and the wrong
+ * one for three reasons: `journalctl --user` shows nothing at all on a distro
+ * whose journal is volatile (the output is gone after a reboot, which is
+ * exactly when someone looks); it makes "where are the logs" have a different
+ * answer on each platform, so `paddock service logs` would be two
+ * implementations; and it rules out Windows, which the contract requires
+ * nothing rule out.
+ *
+ * The directory has to exist first — systemd creates the file, not its parent —
+ * which `install` below does.
+ *
+ * ## Every ExecStart word is quoted
+ *
+ * `%` starts a specifier anywhere in a unit file and `$` starts a variable in
+ * `ExecStart`, so both are escaped; a word containing whitespace, a quote or a
+ * backslash is quoted. Paths with a space in them are the common case
+ * (`/Users/Ed Spencer/.paddock`), and the old unqualified `join(" ")` wrote a
+ * unit systemd then split into the wrong arguments — a service that fails at
+ * login having printed nothing.
  */
 export function renderUnit(spec) {
-    const exec = [spec.nodePath, spec.scriptPath, ...spec.args].join(" ");
-    return `[Unit]
+    const exec = [spec.nodePath, spec.scriptPath, ...spec.args].map(execWord).join(" ");
+    return `# Generated by Paddock — \`paddock service install\` rewrites this file.
+# Node: ${spec.nodePath}
+[Unit]
 Description=Paddock — persistent, resumable Claude Code sessions, by project
 Documentation=https://paddock.edspencer.net
 
 [Service]
 Type=simple
 ExecStart=${exec}
-WorkingDirectory=${spec.workingDirectory}
-Environment=PATH=${spec.pathEnv}
+WorkingDirectory=${pct(spec.workingDirectory)}
+Environment="PATH=${cEscape(pct(spec.pathEnv))}"
+StandardOutput=append:${pct(spec.logPath)}
+StandardError=append:${pct(spec.logPath)}
 Restart=always
 RestartSec=10
 
@@ -100,6 +156,11 @@ RestartSec=10
 WantedBy=default.target
 `;
 }
+/** The log file an installed unit appends to, or undefined if it names none. */
+export function parseUnitLogPath(text) {
+    const m = /^StandardOutput=append:(.*)$/m.exec(text);
+    return m === null ? undefined : m[1].trim().replace(/%%/g, "%");
+}
 /**
  * Does an installed unit carry `Restart=always` (#872)?
  *
@@ -117,15 +178,40 @@ export function parseUnitArgv(text) {
     const m = /^ExecStart=(.*)$/m.exec(text);
     if (m === null)
         return [];
-    return m[1].trim().split(/\s+/).filter(Boolean);
+    return execWords(m[1].trim());
 }
-/** Run a `systemctl` and turn a non-zero exit into the manager's own words. */
+/**
+ * What a `systemctl` failure means, in the manager's own words where it has any.
+ *
+ * The `status === null` branch is the one QA found: `spawnSync` reports a
+ * missing binary that way, with no output at all, so the message was
+ * `systemctl --user enable --now failed (exit null).` and then a blank line —
+ * which tells someone on a container with no systemd nothing whatsoever. That
+ * is also the single likeliest way this command fails on a machine it was never
+ * going to work on.
+ */
+export function systemctlFailure(args, r) {
+    if (r.status === null || r.status === 127) {
+        return ("systemctl is not available, so Paddock cannot install a service here.\n" +
+            "It needs systemd's per-user instance (`systemctl --user`) — a container " +
+            "or a non-systemd distribution has none.\n" +
+            "Run `paddock serve` in a terminal, or keep it up with whatever this " +
+            "machine uses.");
+    }
+    if (/Failed to connect to (user scope )?bus|DBUS_SESSION_BUS_ADDRESS|XDG_RUNTIME_DIR/.test(r.stderr)) {
+        return (`cannot reach systemd's per-user instance (${r.stderr.trim()}).\n` +
+            "Run this from a login session, and check that $XDG_RUNTIME_DIR is set " +
+            "(usually /run/user/$(id -u)).");
+    }
+    return (`systemctl ${args.join(" ")} failed (exit ${String(r.status)}).\n` +
+        `${r.stderr || r.stdout}`.trim());
+}
+/** Run a `systemctl` and turn a non-zero exit into something actionable. */
 function systemctlOrThrow(run, args) {
     const r = run("systemctl", args);
     if (r.status === 0)
         return;
-    throw new Error(`systemctl ${args.join(" ")} failed (exit ${String(r.status)}).\n` +
-        `${r.stderr || r.stdout}`.trim());
+    throw new Error(systemctlFailure(args, r));
 }
 export function createSystemdBackend(run, homeDir, xdgConfigHome) {
     // Both forwarded, neither defaulted here: `unitPath` owns the precedence, and
@@ -140,15 +226,19 @@ export function createSystemdBackend(run, homeDir, xdgConfigHome) {
         install(spec) {
             fs.mkdirSync(path.dirname(file), { recursive: true });
             fs.mkdirSync(spec.workingDirectory, { recursive: true });
+            // systemd creates the log FILE for `append:` but not its directory, and a
+            // missing directory fails the unit at start with the server never having
+            // run — no output anywhere, because the thing that would have written it
+            // is what failed.
+            fs.mkdirSync(path.dirname(spec.logPath), { recursive: true });
             fs.writeFileSync(file, renderUnit(spec), "utf8");
             // Without this the manager keeps serving the previous unit from cache and
             // an "upgrade" silently changes nothing.
             run("systemctl", ["--user", "daemon-reload"]);
-            const enabled = run("systemctl", ["--user", "enable", "--now", SYSTEMD_UNIT]);
-            if (enabled.status !== 0) {
-                throw new Error(`systemctl --user enable --now failed (exit ${String(enabled.status)}).\n` +
-                    `${enabled.stderr || enabled.stdout}`.trim());
-            }
+            const args = ["--user", "enable", "--now", SYSTEMD_UNIT];
+            const enabled = run("systemctl", args);
+            if (enabled.status !== 0)
+                throw new Error(systemctlFailure(args, enabled));
         },
         uninstall() {
             const existed = fs.existsSync(file);
@@ -188,21 +278,36 @@ export function createSystemdBackend(run, homeDir, xdgConfigHome) {
             const active = run("systemctl", ["--user", "is-active", SYSTEMD_UNIT]);
             const pid = run("systemctl", ["--user", "show", "-p", "MainPID", "--value", SYSTEMD_UNIT]);
             const mainPid = pid.stdout.trim();
+            const logPath = parseUnitLogPath(text);
             return {
                 registered: true,
                 running: active.stdout.trim() === "active",
                 ...(mainPid !== "" && mainPid !== "0" ? { pid: mainPid } : {}),
                 argv: argv.slice(2),
+                ...(argv[0] !== undefined ? { nodePath: argv[0] } : {}),
+                ...(argv[1] !== undefined ? { cliPath: argv[1] } : {}),
+                ...(logPath !== undefined ? { logPath } : {}),
                 keepsAlive: unitKeepsAlive(text),
             };
         },
-        logsHint() {
-            return `  Logs: journalctl --user -u ${SYSTEMD_UNIT} -f`;
-        },
-        lingerNote() {
+        /**
+         * `loginctl show-user <user> -p Linger` (SPEC §7).
+         *
+         * Parsed rather than trusted to exit codes: `loginctl` is absent in plenty
+         * of containers and exits non-zero for a user logind has no record of, and
+         * neither of those is "linger is off". An unparseable answer is reported as
+         * unknown, which prints nothing — the alternative is handing a `sudo`
+         * command to someone whose machine has no `loginctl` to run it with.
+         */
+        linger() {
             const user = os.userInfo().username;
-            return ("  A user service stops when you log out. To keep Paddock up:\n" +
-                `    loginctl enable-linger ${user}`);
+            const r = run("loginctl", ["show-user", user, "-p", "Linger"]);
+            const m = /Linger=(yes|no)/i.exec(`${r.stdout}${r.stderr}`);
+            return {
+                applies: true,
+                user,
+                ...(m !== null ? { enabled: m[1].toLowerCase() === "yes" } : {}),
+            };
         },
     };
 }

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/management-mcp-server.d.ts

@@ -1,3 +1,22 @@
+/**
+ * The MCP server for external Management API callers (issue #312 M2).
+ *
+ * Adapts the SAME tool definitions the in-process keeper gets — an
+ * {@link InjectedMcpServerDef} produced by `selfMcpServerDefForOps` — onto the
+ * official MCP SDK, so an external client sees exactly the toolset a keeper
+ * sees, minus whatever its scope hides. Nothing is redefined here: if a tool is
+ * added to the self-MCP, it appears over `/mcp` with no further work, which is
+ * the "upgrade the server, every client's toolset upgrades" property the epic
+ * calls out.
+ *
+ * ── Why the LOW-LEVEL `Server`, not `McpServer` ────────────────────────────
+ * The high-level `McpServer.registerTool` wants Zod schemas and converts them to
+ * JSON Schema for the wire. Our tools already carry hand-written JSON Schema
+ * (shared with herdctl's injected-MCP bridge), so going through Zod would mean
+ * translating JSON Schema → Zod → JSON Schema and hoping the round trip is
+ * faithful. Implementing `tools/list` + `tools/call` directly passes our schemas
+ * through verbatim and keeps ONE source of truth for the tool surface.
+ */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import type { InjectedMcpServerDef } from "@herdctl/core";
 import { type ManagementPrincipal } from "./management-policy.js";
@@ -5,9 +24,8 @@ import { type ManagementPrincipal } from "./management-policy.js";
 export declare const MANAGEMENT_MCP_SERVER_NAME = "paddock";
 /**
  * Package version, advertised to the client so it can report which Paddock it
- * is talking to. Resolved at runtime (dist/management-mcp-server.js →
- * ../package.json), the same way app.ts resolves it for the OpenAPI document,
- * so it tracks releases without a build step.
+ * is talking to. One resolution, shared with the OpenAPI document and
+ * `/api/health` (version.ts), so the three cannot disagree.
  */
 export declare const MANAGEMENT_MCP_SERVER_VERSION: string;
 /**

package/packages/server/dist/management-mcp-server.js

@@ -17,27 +17,18 @@
  * faithful. Implementing `tools/list` + `tools/call` directly passes our schemas
  * through verbatim and keeps ONE source of truth for the tool surface.
  */
-import { createRequire } from "node:module";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { ManagementDeniedError } from "./management-policy.js";
+import { PADDOCK_VERSION } from "./version.js";
 /** Server identity advertised in the MCP `initialize` handshake. */
 export const MANAGEMENT_MCP_SERVER_NAME = "paddock";
 /**
  * Package version, advertised to the client so it can report which Paddock it
- * is talking to. Resolved at runtime (dist/management-mcp-server.js →
- * ../package.json), the same way app.ts resolves it for the OpenAPI document,
- * so it tracks releases without a build step.
+ * is talking to. One resolution, shared with the OpenAPI document and
+ * `/api/health` (version.ts), so the three cannot disagree.
  */
-export const MANAGEMENT_MCP_SERVER_VERSION = (() => {
-    try {
-        const require = createRequire(import.meta.url);
-        return require("../package.json").version ?? "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-})();
+export const MANAGEMENT_MCP_SERVER_VERSION = PADDOCK_VERSION;
 /**
  * Build an MCP server exposing `def`'s tools to `principal`.
  *