@edspencer/paddock 0.66.2 → 0.68.0

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

@@ -0,0 +1,206 @@
+/**
+ * The darwin backend: a launchd **LaunchAgent** (#796).
+ *
+ * ## Why an agent and not a daemon
+ *
+ * A LaunchAgent is bootstrapped into the `gui/<uid>` domain when that user logs
+ * in, and runs as them. A LaunchDaemon starts at boot, as root, before anyone
+ * has logged in. The difference is not convenience — it decides whether Paddock
+ * can use your Claude login at all.
+ *
+ * On macOS that login is a Keychain item, and the login keychain is unlocked by
+ * your account password *at login*. A daemon has no such session, so the item
+ * is locked and unreadable; `UserName` in the plist does not help, because it
+ * changes the effective uid and not the keychain's unlock state. `claude.
+ * credentials: host` on darwin therefore structurally requires a logged-in user
+ * session, and boot-time start and Keychain credentials are mutually exclusive.
+ *
+ * The consequence users will meet is that Paddock starts **at login, not at
+ * boot** — after a restart nobody logs into, it is not running. Every surface
+ * that mentions this service says so, because otherwise it gets filed as a bug.
+ *
+ * A boot-time instance is a genuinely different feature: a LaunchDaemon plus
+ * `claude.credentials: own` and a token sitting in `EnvironmentVariables` —
+ * which is exactly the long-lived-credential-in-a-plist problem the agent shape
+ * avoids. Stated in the docs as the trade, not offered as a flag.
+ *
+ * ## What has actually been verified
+ *
+ * A turn completed under `launchctl kickstart` on a Mac whose Claude login
+ * existed only as the Keychain item, with `ps eww` confirming no credential in
+ * the process environment, and with no permission dialog. Start **at login**
+ * (`RunAtLoad` after a real logout/login) has NOT been tested; if a login-time
+ * agent can race keychain unlock, the fix belongs in this file's plist rather
+ * than in the design. Nothing here should be read as covering that case.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { LAUNCHD_LABEL } from "./spec.js";
+/** `~/Library/LaunchAgents/net.edspencer.paddock.plist`. */
+export function plistPath(homeDir = os.homedir()) {
+    return path.join(homeDir, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+}
+function xmlEscape(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/**
+ * Render the plist.
+ *
+ * `KeepAlive` is a dict rather than `<true/>` on purpose: `SuccessfulExit:
+ * false` means "restart it if it exits nonzero, leave it alone if it exits
+ * cleanly". A bare `<true/>` would fight a deliberate `launchctl bootout` and
+ * make stopping Paddock a wrestling match.
+ *
+ * `EnvironmentVariables` carries PATH and nothing else. It carries PATH because
+ * launchd hands a process a stub PATH that a version manager's `node`, and the
+ * `git` an agent will want, are both missing from. It carries nothing else
+ * because a plist is a world-readable file in the user's home, and the one
+ * category of value that would be tempting to put here — a credential — is
+ * precisely what the agent shape exists to avoid needing.
+ *
+ * No `PADDOCK_DATA_DIR`: see `buildSpec`. One `~/.paddock` instance, reachable
+ * from the service and from a terminal.
+ */
+export function renderPlist(spec) {
+    const argv = [spec.nodePath, spec.scriptPath, ...spec.args];
+    const strings = argv.map((a) => `      <string>${xmlEscape(a)}</string>`).join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${xmlEscape(LAUNCHD_LABEL)}</string>
+    <key>ProgramArguments</key>
+    <array>
+${strings}
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+      <key>SuccessfulExit</key>
+      <false/>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+    <key>WorkingDirectory</key>
+    <string>${xmlEscape(spec.workingDirectory)}</string>
+    <key>StandardOutPath</key>
+    <string>${xmlEscape(spec.stdoutPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${xmlEscape(spec.stderrPath)}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+      <key>PATH</key>
+      <string>${xmlEscape(spec.pathEnv)}</string>
+    </dict>
+  </dict>
+</plist>
+`;
+}
+/**
+ * Pull `ProgramArguments` back out of a plist we wrote.
+ *
+ * `status` reports the port the service is ACTUALLY installed with, which is
+ * only knowable from the installed unit — recomputing it from today's flags
+ * would print a confident URL for a server listening somewhere else. Regex
+ * rather than a plist parser because the input is a file this module wrote, in
+ * a shape this module controls, and adding an XML dependency to read it back
+ * would be the larger risk.
+ */
+export function parsePlistArgv(xml) {
+    const block = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(xml);
+    if (block === null)
+        return [];
+    return [...block[1].matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => m[1]
+        .replace(/&quot;/g, '"')
+        .replace(/&gt;/g, ">")
+        .replace(/&lt;/g, "<")
+        .replace(/&amp;/g, "&"));
+}
+/**
+ * Read liveness out of `launchctl print gui/<uid>/<label>`.
+ *
+ * That command is the honest answer to "is it running": it reports the service
+ * as launchd currently understands it, including `state = running` and the pid.
+ * The alternative — checking whether the plist file exists — answers "is it
+ * registered", which is a different and much weaker question.
+ */
+export function parseLaunchctlPrint(out) {
+    const state = /^\s*state\s*=\s*(\S+)/m.exec(out);
+    const pid = /^\s*pid\s*=\s*(\d+)/m.exec(out);
+    return {
+        running: state !== null && state[1] === "running",
+        ...(pid !== null ? { pid: pid[1] } : {}),
+    };
+}
+function target() {
+    return `gui/${process.getuid?.() ?? 0}/${LAUNCHD_LABEL}`;
+}
+function domain() {
+    return `gui/${process.getuid?.() ?? 0}`;
+}
+export function createLaunchdBackend(run, homeDir = os.homedir()) {
+    const file = plistPath(homeDir);
+    return {
+        platform: "darwin",
+        unitPath: file,
+        label: LAUNCHD_LABEL,
+        install(spec) {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.mkdirSync(spec.workingDirectory, { recursive: true });
+            fs.writeFileSync(file, renderPlist(spec), "utf8");
+            // `bootstrap` fails outright if the label is already loaded, so a
+            // reinstall has to unload first. A first install has nothing to unload,
+            // and says so on stderr — ignored rather than reported, because "there
+            // was no previous service" is the expected case, not a problem.
+            run("launchctl", ["bootout", target()]);
+            // NOT `load`/`unload`: those are the legacy API, and on a modern macOS
+            // they are shims over this one that report success in cases where it
+            // reports the actual error.
+            const boot = run("launchctl", ["bootstrap", domain(), file]);
+            if (boot.status !== 0) {
+                throw new Error(`launchctl bootstrap failed (exit ${String(boot.status)}).\n` +
+                    `${boot.stderr || boot.stdout}`.trim());
+            }
+            // `RunAtLoad` should already have started it; `kickstart -k` makes that
+            // true rather than probable, and is the same command a later restart uses.
+            run("launchctl", ["kickstart", "-k", target()]);
+        },
+        uninstall() {
+            const existed = fs.existsSync(file);
+            run("launchctl", ["bootout", target()]);
+            if (existed)
+                fs.rmSync(file, { force: true });
+            return existed;
+        },
+        status() {
+            if (!fs.existsSync(file))
+                return { registered: false, running: false, argv: [] };
+            const argv = parsePlistArgv(fs.readFileSync(file, "utf8"));
+            const printed = run("launchctl", ["print", target()]);
+            const parsed = printed.status === 0
+                ? parseLaunchctlPrint(printed.stdout)
+                : { running: false, pid: undefined };
+            return {
+                registered: true,
+                running: parsed.running,
+                ...(parsed.pid !== undefined ? { pid: parsed.pid } : {}),
+                // Strip the interpreter and script: what a reader wants from `status`
+                // is the Paddock invocation, not the absolute path to node twice.
+                argv: argv.slice(2),
+            };
+        },
+        logsHint(spec) {
+            return `  Logs: ${spec.stdoutPath}\n        ${spec.stderrPath}`;
+        },
+        lingerNote() {
+            return undefined;
+        },
+    };
+}

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

@@ -0,0 +1,106 @@
+/**
+ * Reverse-DNS on macOS, plain on Linux. Both are stable identifiers a user may
+ * end up typing (`launchctl print gui/501/net.edspencer.paddock`,
+ * `systemctl --user status paddock`), so neither is derived from anything that
+ * could vary between installs.
+ */
+export declare const LAUNCHD_LABEL = "net.edspencer.paddock";
+export declare const SYSTEMD_UNIT = "paddock.service";
+/** Default port, matching the server's own (#741). Kept here so the generated
+ * unit can name a port even when the user passed no flag — a unit that relies
+ * on a default is a unit whose port changes under it on upgrade. */
+export declare const DEFAULT_PORT = "7233";
+export interface ServiceSpec {
+    /** Absolute path to the `node` that will run us — `process.execPath`. */
+    nodePath: string;
+    /**
+     * Absolute path to `dist/cli/paddock.js`.
+     *
+     * NOT the `bin` shim. npm installs a bin as a symlink whose `#!/usr/bin/env
+     * node` shebang has to find `node` on PATH, and launchd's PATH is a stub —
+     * under a version manager there is no `node` on it at all. Invoking the
+     * interpreter explicitly removes the lookup entirely.
+     */
+    scriptPath: string;
+    /** Arguments after the script: always starts with the `start` 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. */
+    pathEnv: string;
+}
+export interface SpecInput {
+    nodePath: string;
+    scriptPath: string;
+    /** Resolved data dir — where the working directory and logs go. */
+    dataDir: string;
+    /** Only forwarded when the user asked for it explicitly. */
+    port?: string;
+    host?: string;
+    /** Only present when the user wants an instance separate from their terminal one. */
+    dataDirArg?: string;
+    verbose?: boolean;
+    pathEnv?: string;
+}
+/**
+ * The service's own directory inside the data dir.
+ *
+ * `WorkingDirectory` has to be *something*, and the two obvious candidates are
+ * both wrong. `$HOME` is wrong on the merits — a background process has no cwd
+ * anyone chose, and it should not sit in a directory full of the user's things
+ * (it was also, until #798, actively dangerous: `.paddock` was the here-marker
+ * AND the default data dir, so `$HOME` looked like an already-opened
+ * workspace). The data dir root is wrong because launchd's `StandardOutPath`
+ * would then drop log files in among the state directories. A dedicated
+ * subdirectory is neither.
+ */
+export declare function serviceDir(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`
+ * 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.
+ *
+ * `--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
+ * and a `paddock` typed into a terminal both fall through to `~/.paddock` and
+ * are the same instance. Naming it — even naming it as the same value — would
+ * be a second place to change on the day someone moves it.
+ *
+ * `--open` is deliberately never forwarded, whatever was passed to `install`: a
+ * service opening a browser tab at login is not a feature.
+ */
+export declare function buildSpec(input: SpecInput): ServiceSpec;
+/**
+ * Is this copy of Paddock running out of npx's cache?
+ *
+ * npx materialises a package under `~/.npm/_npx/<hash>/`, where the hash is
+ * keyed on the resolved spec. Copies accumulate, and the whole tree is removed
+ * by `npm cache clean`. A unit file pointing in there works right up until it
+ * doesn't — at a login, unattended, with the failure reported as "Paddock
+ * stopped starting". Refusing to write it is the only outcome that cannot
+ * mislead someone six months from now.
+ *
+ * Matched on the path separator both sides so a project genuinely named `_npx`
+ * is not caught, and with a Windows-separator variant because `packageRoot` is
+ * whatever the platform produced.
+ */
+export declare function isNpxPath(p: string): boolean;
+export declare const NPX_REFUSAL: string;
+/**
+ * The port a generated unit will actually serve on, read back out of its own
+ * recorded argument vector.
+ *
+ * `status` reports a URL, and it must be the URL of the service as installed
+ * rather than the one an install run today would produce — those differ the
+ * moment someone installs with `--port` and then upgrades their expectations.
+ */
+export declare function portFromArgv(argv: string[], fallback?: string): string;
+/** As {@link portFromArgv}, for the bind address. */
+export declare function hostFromArgv(argv: string[], fallback?: string): string;

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

@@ -0,0 +1,124 @@
+/**
+ * What a Paddock background service IS, independent of how any one init system
+ * spells it (#796).
+ *
+ * Everything in this file is pure. The two backends — `launchd.ts` and
+ * `systemd.ts` — are writers: they take a {@link ServiceSpec} and render a
+ * plist or a unit file. Keeping the decisions here rather than in either writer
+ * is what lets the darwin plist be tested on Linux, which is the only place it
+ * CAN be tested in this project's CI.
+ */
+import os from "node:os";
+import path from "node:path";
+/**
+ * Reverse-DNS on macOS, plain on Linux. Both are stable identifiers a user may
+ * end up typing (`launchctl print gui/501/net.edspencer.paddock`,
+ * `systemctl --user status paddock`), so neither is derived from anything that
+ * could vary between installs.
+ */
+export const LAUNCHD_LABEL = "net.edspencer.paddock";
+export const SYSTEMD_UNIT = "paddock.service";
+/** Default port, matching the server's own (#741). Kept here so the generated
+ * unit can name a port even when the user passed no flag — a unit that relies
+ * on a default is a unit whose port changes under it on upgrade. */
+export const DEFAULT_PORT = "7233";
+/**
+ * The service's own directory inside the data dir.
+ *
+ * `WorkingDirectory` has to be *something*, and the two obvious candidates are
+ * both wrong. `$HOME` is wrong on the merits — a background process has no cwd
+ * anyone chose, and it should not sit in a directory full of the user's things
+ * (it was also, until #798, actively dangerous: `.paddock` was the here-marker
+ * AND the default data dir, so `$HOME` looked like an already-opened
+ * workspace). The data dir root is wrong because launchd's `StandardOutPath`
+ * would then drop log files in among the state directories. A dedicated
+ * subdirectory is neither.
+ */
+export function serviceDir(dataDir) {
+    return path.join(dataDir, "service");
+}
+/** 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");
+}
+/**
+ * Assemble the spec.
+ *
+ * The argument vector leads with the `start` 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.
+ *
+ * `--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
+ * and a `paddock` typed into a terminal both fall through to `~/.paddock` and
+ * are the same instance. Naming it — even naming it as the same value — would
+ * be a second place to change on the day someone moves it.
+ *
+ * `--open` is deliberately never forwarded, whatever was passed to `install`: a
+ * service opening a browser tab at login is not a feature.
+ */
+export function buildSpec(input) {
+    const args = ["start"];
+    if (input.port !== undefined)
+        args.push("--port", input.port);
+    if (input.host !== undefined)
+        args.push("--host", input.host);
+    if (input.dataDirArg !== undefined)
+        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",
+    };
+}
+/**
+ * Is this copy of Paddock running out of npx's cache?
+ *
+ * npx materialises a package under `~/.npm/_npx/<hash>/`, where the hash is
+ * keyed on the resolved spec. Copies accumulate, and the whole tree is removed
+ * by `npm cache clean`. A unit file pointing in there works right up until it
+ * doesn't — at a login, unattended, with the failure reported as "Paddock
+ * stopped starting". Refusing to write it is the only outcome that cannot
+ * mislead someone six months from now.
+ *
+ * Matched on the path separator both sides so a project genuinely named `_npx`
+ * is not caught, and with a Windows-separator variant because `packageRoot` is
+ * whatever the platform produced.
+ */
+export function isNpxPath(p) {
+    return p.includes(`${path.sep}_npx${path.sep}`) || p.includes("/_npx/");
+}
+export const NPX_REFUSAL = "`service install` needs an install path that will still be there at your\n" +
+    "         next login, and this copy is running from npx's cache — a hash-keyed\n" +
+    "         directory that `npm cache clean` removes.\n\n" +
+    "  npm i -g @edspencer/paddock && paddock service install\n";
+/**
+ * The port a generated unit will actually serve on, read back out of its own
+ * recorded argument vector.
+ *
+ * `status` reports a URL, and it must be the URL of the service as installed
+ * rather than the one an install run today would produce — those differ the
+ * moment someone installs with `--port` and then upgrades their expectations.
+ */
+export function portFromArgv(argv, fallback = DEFAULT_PORT) {
+    for (let i = 0; i < argv.length; i++) {
+        if ((argv[i] === "--port" || argv[i] === "-p") && argv[i + 1] !== undefined)
+            return argv[i + 1];
+    }
+    return fallback;
+}
+/** As {@link portFromArgv}, for the bind address. */
+export function hostFromArgv(argv, fallback = "127.0.0.1") {
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--host" && argv[i + 1] !== undefined)
+            return argv[i + 1];
+    }
+    return fallback;
+}

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

@@ -0,0 +1,48 @@
+import { type ServiceSpec } from "./spec.js";
+import type { Runner, ServiceBackend } from "./backend.js";
+/**
+ * `~/.config/systemd/user/paddock.service`, honouring `XDG_CONFIG_HOME`.
+ *
+ * ## An injected home outranks the ambient variable
+ *
+ * The precedence is: an explicit `xdgConfigHome` argument, then an explicitly
+ * **injected** `homeDir`, then — only when the caller named neither — the real
+ * environment. That middle rung is the whole point, and getting it wrong was a
+ * live bug rather than a style question.
+ *
+ * The first version read `process.env.XDG_CONFIG_HOME` before falling back to
+ * `homeDir`. On any machine with that variable set — CI, and plenty of Linux
+ * desktops — the `homeDir` parameter was therefore **a lie**: a caller passing a
+ * throwaway directory still resolved to the real config home. Two things
+ * followed. Test isolation quietly stopped working, so which assertion passed
+ * depended on test ORDER rather than test content. And the suite wrote a real
+ * `paddock.service` into the runner's actual config directory, outside every
+ * temp dir it thought it was confined to — which on a contributor's machine
+ * would have installed a unit they never asked for.
+ *
+ * So: passing a home is a statement about where home is, and it wins. The
+ * ambient read survives only on the branch where nobody said otherwise, which
+ * is the real-use branch and the one where honouring `XDG_CONFIG_HOME` is
+ * correct. (`paddock.ts` threads the variable in explicitly as well, so the
+ * production path does not depend on this fallback — it is here so that a
+ * caller with no opinion still gets the right answer.)
+ */
+export declare function unitPath(homeDir?: string, xdgConfigHome?: string): string;
+/**
+ * Render the unit.
+ *
+ * `Restart=on-failure` rather than `always`, matching launchd's `SuccessfulExit:
+ * false` — a clean shutdown should stay shut down.
+ *
+ * `WantedBy=default.target` is what makes `systemctl --user enable` mean
+ * "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".
+ */
+export declare function renderUnit(spec: ServiceSpec): string;
+/** Read `ExecStart=` back out of an installed unit, split into an argv. */
+export declare function parseUnitArgv(text: string): string[];
+export declare function createSystemdBackend(run: Runner, homeDir?: string, xdgConfigHome?: string): ServiceBackend;

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

@@ -0,0 +1,155 @@
+/**
+ * The Linux backend: a `systemd --user` unit (#796).
+ *
+ * ## Not the server story
+ *
+ * Paddock already documents itself under systemd — `guides/proxmox-lxc.md`
+ * Path B, provisioned by the `paddock-deploy` Ansible recipes. That is a
+ * SYSTEM unit, running as a service user, behind a reverse proxy, with a token
+ * in its environment. This is the other one: a user unit, running as you, on
+ * loopback, using the Claude login you already have. They should not be
+ * confused, and this module writes nothing outside `~/.config/systemd/user`.
+ *
+ * ## Lingering
+ *
+ * A `--user` manager is started at your first login and stopped at your last
+ * logout, so by default the unit dies when you log out — including when you log
+ * out of an SSH session, which is how most people meet this. `loginctl
+ * enable-linger <user>` keeps the manager (and therefore Paddock) alive.
+ *
+ * That is called out in the install output rather than being run for the user:
+ * lingering is a real change to how the machine behaves after they leave it,
+ * and it needs a privilege this command otherwise never asks for.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { SYSTEMD_UNIT } from "./spec.js";
+/**
+ * `~/.config/systemd/user/paddock.service`, honouring `XDG_CONFIG_HOME`.
+ *
+ * ## An injected home outranks the ambient variable
+ *
+ * The precedence is: an explicit `xdgConfigHome` argument, then an explicitly
+ * **injected** `homeDir`, then — only when the caller named neither — the real
+ * environment. That middle rung is the whole point, and getting it wrong was a
+ * live bug rather than a style question.
+ *
+ * The first version read `process.env.XDG_CONFIG_HOME` before falling back to
+ * `homeDir`. On any machine with that variable set — CI, and plenty of Linux
+ * desktops — the `homeDir` parameter was therefore **a lie**: a caller passing a
+ * throwaway directory still resolved to the real config home. Two things
+ * followed. Test isolation quietly stopped working, so which assertion passed
+ * depended on test ORDER rather than test content. And the suite wrote a real
+ * `paddock.service` into the runner's actual config directory, outside every
+ * temp dir it thought it was confined to — which on a contributor's machine
+ * would have installed a unit they never asked for.
+ *
+ * So: passing a home is a statement about where home is, and it wins. The
+ * ambient read survives only on the branch where nobody said otherwise, which
+ * is the real-use branch and the one where honouring `XDG_CONFIG_HOME` is
+ * correct. (`paddock.ts` threads the variable in explicitly as well, so the
+ * production path does not depend on this fallback — it is here so that a
+ * caller with no opinion still gets the right answer.)
+ */
+export function unitPath(homeDir, xdgConfigHome) {
+    const base = xdgConfigHome ??
+        (homeDir !== undefined
+            ? path.join(homeDir, ".config")
+            : (process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config")));
+    return path.join(base, "systemd", "user", SYSTEMD_UNIT);
+}
+/**
+ * Render the unit.
+ *
+ * `Restart=on-failure` rather than `always`, matching launchd's `SuccessfulExit:
+ * false` — a clean shutdown should stay shut down.
+ *
+ * `WantedBy=default.target` is what makes `systemctl --user enable` mean
+ * "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".
+ */
+export function renderUnit(spec) {
+    const exec = [spec.nodePath, spec.scriptPath, ...spec.args].join(" ");
+    return `[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}
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`;
+}
+/** Read `ExecStart=` back out of an installed unit, split into an argv. */
+export function parseUnitArgv(text) {
+    const m = /^ExecStart=(.*)$/m.exec(text);
+    if (m === null)
+        return [];
+    return m[1].trim().split(/\s+/).filter(Boolean);
+}
+export function createSystemdBackend(run, homeDir, xdgConfigHome) {
+    // Both forwarded, neither defaulted here: `unitPath` owns the precedence, and
+    // defaulting `homeDir` to `os.homedir()` at this layer would collapse "the
+    // caller named a home" into "the caller named nothing" — the exact
+    // distinction that precedence turns on.
+    const file = unitPath(homeDir, xdgConfigHome);
+    return {
+        platform: "linux",
+        unitPath: file,
+        label: SYSTEMD_UNIT,
+        install(spec) {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.mkdirSync(spec.workingDirectory, { 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());
+            }
+        },
+        uninstall() {
+            const existed = fs.existsSync(file);
+            run("systemctl", ["--user", "disable", "--now", SYSTEMD_UNIT]);
+            if (existed)
+                fs.rmSync(file, { force: true });
+            run("systemctl", ["--user", "daemon-reload"]);
+            return existed;
+        },
+        status() {
+            if (!fs.existsSync(file))
+                return { registered: false, running: false, argv: [] };
+            const argv = parseUnitArgv(fs.readFileSync(file, "utf8"));
+            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();
+            return {
+                registered: true,
+                running: active.stdout.trim() === "active",
+                ...(mainPid !== "" && mainPid !== "0" ? { pid: mainPid } : {}),
+                argv: argv.slice(2),
+            };
+        },
+        logsHint() {
+            return `  Logs: journalctl --user -u ${SYSTEMD_UNIT} -f`;
+        },
+        lingerNote() {
+            const user = os.userInfo().username;
+            return ("  A user service stops when you log out. To keep Paddock up:\n" +
+                `    loginctl enable-linger ${user}`);
+        },
+    };
+}