@theford/runly 0.0.0-stage → 0.20.0

package/dist/cli/client.js

@@ -0,0 +1,294 @@
+/**
+ * CLI-side client: auto-spawn the daemon on first use (tmux/Docker pattern,
+ * decision 0009) and speak JSON over the unix socket.
+ */
+import { request } from 'node:http';
+import { spawn } from 'node:child_process';
+import { openSync, statSync, readSync, closeSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { installedUnit, startUnit, unitRunsThisBuild } from './daemon-unit.js';
+import { socketPath, stateRoot } from '../core/paths.js';
+import { isAlive } from '../core/procscan.js';
+import { collectCallerEnv } from '../core/caller-env.js';
+/** A wedged daemon must not hang a caller forever. Overridable for tests. */
+const RPC_TIMEOUT_MS = () => Number(process.env.BACKLOT_RPC_TIMEOUT_MS ?? 15 * 60_000);
+/**
+ * Classify a client-side failure for the exit-code contract (decision 0010).
+ *
+ * Agents branch on the class mechanically, so an unreachable or wedged daemon
+ * must NOT report env-error: that tells the agent to recycle an environment,
+ * which cannot fix a broken daemon. Anything that never became a classified
+ * daemon response is infrastructure.
+ */
+export function classifyClientError(err) {
+    const tagged = err?.backlotClass;
+    if (tagged === 'infra-error' || tagged === 'env-error')
+        return tagged;
+    const msg = String(err?.message ?? err);
+    return /daemon (did not|closed|is not)|ECONNREFUSED|ENOENT|EACCES|EPIPE|ECONNRESET|socket/i.test(msg)
+        ? 'infra-error'
+        : 'env-error';
+}
+/**
+ * The daemon streams newline-delimited frames: {type:'progress',phase} … then
+ * one {type:'result',ok,…}. `onProgress` (optional) sees each phase; the
+ * promise resolves on the result frame. Consumers that ignore progress (for example,
+ * ping, most verbs) just don't pass it — the frames are consumed and dropped.
+ */
+export function rpc(verb, args, onProgress, deadlineMs) {
+    return new Promise((resolve, reject) => {
+        const req = request({ socketPath: socketPath(), path: '/rpc', method: 'POST', headers: { 'content-type': 'application/json' } }, (res) => {
+            let buf = '';
+            let result;
+            res.on('data', (d) => {
+                buf += d;
+                let nl;
+                while ((nl = buf.indexOf('\n')) >= 0) {
+                    const line = buf.slice(0, nl);
+                    buf = buf.slice(nl + 1);
+                    if (!line.trim())
+                        continue;
+                    let frame;
+                    try {
+                        frame = JSON.parse(line);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (frame.type === 'progress')
+                        onProgress?.(String(frame.phase ?? ''));
+                    else if (frame.type === 'result') {
+                        result = frame.ok ? { ok: true, data: frame.data } : { ok: false, error: frame.error };
+                    }
+                    else {
+                        // Back-compat: an un-typed object is a bare result.
+                        result = frame;
+                    }
+                }
+            });
+            res.on('end', () => (result ? resolve(result) : reject(new Error('daemon closed the stream without a result frame'))));
+        });
+        req.on('error', reject);
+        // setTimeout ALONE is inert: Node emits 'timeout' and does nothing else, so
+        // a wedged daemon left the CLI (and any agent driving it) hanging forever.
+        // Destroying the socket is what turns the deadline into a real one.
+        req.setTimeout(RPC_TIMEOUT_MS(), () => {
+            req.destroy(Object.assign(new Error(`daemon did not respond to '${verb}' within ${Math.round(RPC_TIMEOUT_MS() / 1000)}s — it may be wedged; check ${join(stateRoot(), 'daemon.log')}`), {
+                backlotClass: 'infra-error',
+            }));
+        });
+        // Shutdown polling has its own wall-clock budget. A stalled or streaming
+        // ping must not extend it to the ordinary RPC inactivity timeout.
+        if (deadlineMs !== undefined) {
+            const deadline = setTimeout(() => req.destroy(Object.assign(new Error(`daemon did not respond to '${verb}' before the deadline`), {
+                backlotClass: 'infra-error',
+            })), deadlineMs);
+            deadline.unref();
+            req.once('close', () => clearTimeout(deadline));
+        }
+        req.end(JSON.stringify({ verb, args }));
+    });
+}
+async function probe(deadlineMs) {
+    try {
+        const res = await rpc('ping', {}, undefined, deadlineMs);
+        if (!res.ok) {
+            return { state: 'unresponsive', error: Object.assign(new Error(res.error.message), { backlotClass: 'infra-error' }) };
+        }
+        const d = (res.data ?? {});
+        return { state: 'up', info: { pid: d.pid, version: d.version, journalSchema: d.journalSchema } };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ECONNREFUSED')
+            return { state: 'absent' };
+        return { state: 'unresponsive', error: error };
+    }
+}
+async function ping() {
+    const p = await probe();
+    return p.state === 'up' ? p.info : null;
+}
+/** Inspect without spawning; only an absent socket/listener means no daemon. */
+export async function daemonInfo() {
+    const p = await probe();
+    if (p.state === 'unresponsive')
+        throw p.error;
+    return p.state === 'up' ? p.info : null;
+}
+/**
+ * How long `daemon stop` waits for the acknowledged shutdown to finish. The
+ * engine serialises a verified group kill per service (SIGTERM grace plus a
+ * post-SIGKILL wait) across every supervisor before it reaps, so a shared box
+ * with many signal-trapping services legitimately needs more than `update`'s
+ * default window.
+ */
+export const DAEMON_STOP_TIMEOUT_MS = 60_000;
+/** The stop window, overridable (BACKLOT_DAEMON_STOP_TIMEOUT_MS) so a test of the timeout need not sit through a minute. */
+export const daemonStopTimeoutMs = () => {
+    const v = Number(process.env.BACKLOT_DAEMON_STOP_TIMEOUT_MS);
+    return Number.isFinite(v) && v > 0 ? v : DAEMON_STOP_TIMEOUT_MS;
+};
+/**
+ * Wait for the daemon to be really gone — not answering AND not running.
+ *
+ * `update` needs this between the restart request and the respawn, and
+ * `daemon stop` (with `DAEMON_STOP_TIMEOUT_MS`) before it reports `stopped`,
+ * for two distinct reasons:
+ *
+ * - `shutdown` returns its result frame ~50ms BEFORE the process exits, so
+ *   pinging straight away is answered by the daemon that is about to die,
+ *   ensureDaemon concludes one is already up, and the update silently does
+ *   nothing.
+ * - The socket is removed a moment BEFORE the process exits and releases the
+ *   election lock. A daemon spawned in that window finds the lock held by a
+ *   still-live holder, and electSelf refuses to break a live claim (correctly —
+ *   that check is what stops two daemons binding the same journal), so it
+ *   concedes with exit 0. The client then reads "our child exited cleanly, a
+ *   winner must exist" and waits out a full window for a winner that was never
+ *   started. Waiting on the PID closes it.
+ *
+ * Each ping is cut at the remaining budget, and a ping that had to be cut is
+ * evidence of a daemon, not of its absence: a listener that never answered is
+ * still a listener. Only a probe that found no socket or no listener, with the
+ * recorded pid (when known) also dead, counts as gone.
+ */
+export async function awaitDaemonGone(oldPid, timeoutMs = 15_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const p = await probe(Math.max(1, deadline - Date.now()));
+        const running = oldPid !== undefined && isAlive(oldPid);
+        if (p.state === 'absent' && !running)
+            return true;
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    return false;
+}
+export async function ensureDaemon(cwd = process.cwd()) {
+    // Validate the socket path FIRST: ping() swallows every throw into "not up",
+    // which would turn socketPath()'s loud sun_path refusal into a silent spawn
+    // of a daemon bound to a truncated (colliding) socket.
+    socketPath();
+    const existing = await ping();
+    if (existing)
+        return existing;
+    // NOTE: the daemon is spawned from THIS CLI's own dist — which is what makes
+    // `update` work (the next invocation after a stop brings up the installed
+    // build) and equally what makes skew possible (an upgrade cannot replace a
+    // daemon that is already running).
+    // A supervised daemon (decision 0039) is started through its unit, so it
+    // stays supervised: spawning one here would run it outside systemd/launchd.
+    // The election still guards against two; if the unit does not answer, the
+    // ordinary spawn below is the fallback.
+    const unit = installedUnit();
+    if (unit && unitRunsThisBuild(unit) && startUnit(unit)) {
+        const deadline = Date.now() + 10_000;
+        while (Date.now() < deadline) {
+            const info = await ping();
+            if (info)
+                return info;
+            await new Promise((r) => setTimeout(r, 100));
+        }
+    }
+    const daemonEntry = join(dirname(fileURLToPath(import.meta.url)), '..', 'daemon', 'index.js');
+    const daemonEnv = { ...process.env };
+    if (cwd !== undefined) {
+        try {
+            // Input values travel in the lease request, never in the shared daemon's
+            // ambient environment. Otherwise the FIRST caller leaks them into every
+            // future check, exec and unrelated service on this daemon.
+            for (const name of Object.keys(collectCallerEnv(cwd)))
+                delete daemonEnv[name];
+        }
+        catch {
+            // status/doctor/update also work outside a stack or with a broken manifest.
+            // Binding clients validate/collect their input envelope before spawning.
+        }
+    }
+    // HOME/XDG inputs may legitimately be service-specific. Pin routing before
+    // the stripped daemon recomputes its state root from its own environment.
+    daemonEnv.BACKLOT_STATE_DIR = stateRoot();
+    // A daemon autospawned from inside `runly db with`'s command must not carry
+    // that copy's tag: reaping the copy kills what carries it (decision 0039).
+    delete daemonEnv.BACKLOT_DB_COPY;
+    // Nor a supervisor's marks: an autospawned daemon is supervised by nobody,
+    // whatever service the CLI that spawned it runs under.
+    delete daemonEnv.RUNLY_SUPERVISOR;
+    delete daemonEnv.INVOCATION_ID;
+    const log = openSync(join(stateRoot(), 'daemon.log'), 'a');
+    // node:sqlite (the journal) prints "SQLite is an experimental feature" on
+    // every spawn, burying daemon.log's signal. Suppress ONLY that warning class,
+    // and only for the daemon we spawn — a direct CLI or daemon run still warns.
+    const child = spawn(process.execPath, ['--disable-warning=ExperimentalWarning', daemonEntry], {
+        // The state root, as under the systemd/launchd unit — never the caller's
+        // directory: a worktree the daemon outlives (it may be deleted while the
+        // daemon still sits in it), and the cwd of anything the daemon starts
+        // without one of its own.
+        cwd: stateRoot(),
+        detached: true,
+        stdio: ['ignore', log, log],
+        env: daemonEnv,
+    });
+    child.unref();
+    const pingUntil = async (deadline) => {
+        while (Date.now() < deadline) {
+            const info = await ping();
+            if (info)
+                return info;
+            await new Promise((r) => setTimeout(r, 100));
+        }
+        return null;
+    };
+    const up = await pingUntil(Date.now() + 10_000);
+    if (up)
+        return up;
+    // Cold-start stampede: parallel verbs on a cold state dir each spawn a
+    // daemon, the singleton election picks one, and every loser exits 0. Our
+    // child exiting CLEANLY therefore proves a winner exists somewhere — so give
+    // that winner one more window instead of failing a healthy cold start.
+    if (child.exitCode === 0) {
+        const winner = await pingUntil(Date.now() + 10_000);
+        if (winner)
+            return winner;
+    }
+    // Name the REASON, not just the log path. A daemon that refuses to start now
+    // has causes a human must act on rather than retry — the journal-from-the-
+    // future refusal (JOURNAL_SCHEMA_VERSION) is one — and "see daemon.log" sent
+    // every one of them through a file the caller has to go and find.
+    throw new Error(`daemon did not come up — see ${join(stateRoot(), 'daemon.log')}${lastLogLine()}`);
+}
+/** The tail of daemon.log, for a start failure whose cause is already written down. */
+function lastLogLine() {
+    try {
+        const path = join(stateRoot(), 'daemon.log');
+        const size = statSync(path).size;
+        const fd = openSync(path, 'r');
+        try {
+            // Tail only: this log is append-only for the life of a state root.
+            const len = Math.min(size, 4096);
+            const buf = Buffer.alloc(len);
+            readSync(fd, buf, 0, len, size - len);
+            // Pick the line that CARRIES the reason. A refusal thrown while the
+            // daemon's module graph is still initialising (the journal-from-the-future
+            // check runs in an Engine field initialiser) surfaces as an uncaught
+            // top-level throw, so the literal last line is Node's own
+            // "Node.js v22.15.1" footer — useless to the person reading it.
+            const lines = buf
+                .toString('utf8')
+                .split('\n')
+                .map((l) => l.trim())
+                .filter((l) => l !== '' && !l.startsWith('at ') && !/^Node\.js v/.test(l) && !/^\^+$/.test(l));
+            const errorLine = lines.filter((l) => /^[A-Za-z]*Error: /.test(l)).pop();
+            const chosen = errorLine ?? lines[lines.length - 1];
+            return chosen ? `\n  last log line: ${chosen.slice(0, 500)}` : '';
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return ''; // best-effort: never turn a diagnostic into a second failure
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/cli/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/cli/client.ts"],"names":[],"mappings":"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"}

package/dist/cli/daemon-unit.d.ts

@@ -0,0 +1,58 @@
+export type UnitKind = 'systemd' | 'launchd';
+export interface UnitPlan {
+    kind: UnitKind;
+    /** systemd unit name (without .service) or launchd label. */
+    name: string;
+    /** Where the unit file goes. */
+    path: string;
+    content: string;
+}
+/** `runly-daemon`, or `runly-daemon-<hash>` for a non-default state root. */
+export declare function unitBaseName(root?: string): string;
+export declare function unitKind(): UnitKind | null;
+export interface CapturedEnv {
+    /** What goes into the unit (BACKLOT_STATE_DIR and RUNLY_SUPERVISOR included). */
+    env: Record<string, string>;
+    /** Names taken from the installing shell, sorted. */
+    captured: string[];
+    /** Names the manifest's commands reference, or `--env` asked for, that this shell does not set. */
+    notSet: string[];
+    /** The manifest's `env_from` inputs: supplied per `up`, never stored in a unit. */
+    excluded: string[];
+    /** How many other variables of this shell were left out. */
+    leftOut: number;
+}
+/**
+ * What the daemon runs with under the unit: the installing shell's PATH, the
+ * allowlist above, the BACKLOT_* settings, every variable the stack's commands
+ * reference (when installed from a stack) and each `--env NAME` — never an
+ * `env_from` input, which travels with each `up`. RUNLY_SUPERVISOR tells the
+ * daemon who restarts it (`status.supervisor`).
+ */
+export declare function captureEnvironment(root: string, kind: UnitKind, extra?: string[], cwd?: string, from?: NodeJS.ProcessEnv): CapturedEnv;
+export declare function unitPlan(root?: string, extraEnv?: string[], opts?: {
+    capture?: boolean;
+}): (UnitPlan & {
+    environment: CapturedEnv;
+}) | null;
+/** The installed unit for this state root, if any. */
+export declare function installedUnit(root?: string): UnitPlan | null;
+/**
+ * Does the installed unit run THIS CLI's daemon? A unit written by another
+ * install (a global one, while this CLI is a checkout) would start a daemon of
+ * another version, which the version gate then refuses — and `runly update`
+ * would restart the same wrong one. Such a unit is left alone.
+ */
+export declare function unitRunsThisBuild(plan: UnitPlan): boolean;
+/** Write and enable the unit. Does not start it (the caller decides: a daemon may already run). */
+export declare function installUnit(plan: UnitPlan): {
+    steps: string[];
+    error?: string;
+};
+/** Disable and remove the unit. The daemon that runs keeps running, unsupervised. */
+export declare function uninstallUnit(plan: UnitPlan): {
+    steps: string[];
+    error?: string;
+};
+/** Start the installed unit (the CLI's autospawn path when one is installed). True when the start was accepted. */
+export declare function startUnit(plan: UnitPlan): boolean;

package/dist/cli/daemon-unit.js

@@ -0,0 +1,289 @@
+/**
+ * Supervision for the daemon (decision 0039): `runly daemon install` writes a
+ * systemd user unit (Linux) or a launchd agent (macOS) that runs the daemon
+ * with restart-on-failure, so a crashed daemon is back within seconds —
+ * `recover()` re-holds the public ports and reaps what the dead one left —
+ * instead of waiting for the next CLI command.
+ *
+ * It coexists with the CLI's autospawn. The socket lock (election) still
+ * decides who serves, so there is never a second daemon; and once the unit is
+ * installed, a CLI that finds no daemon starts the UNIT rather than spawning
+ * one of its own, so the daemon stays supervised across `runly update` and
+ * `runly daemon stop`.
+ *
+ * One unit per state root: the default root gets `runly-daemon`, any other
+ * (`BACKLOT_STATE_DIR`) a name with a hash of its path, so test daemons and
+ * parallel installs never touch each other's unit.
+ */
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { stateRoot } from '../core/paths.js';
+import { loadStack } from '../core/manifest.js';
+/** The default state root, as paths.ts derives it without BACKLOT_STATE_DIR. */
+function defaultStateRoot() {
+    const base = process.env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state');
+    return join(base, 'backlot');
+}
+/** `runly-daemon`, or `runly-daemon-<hash>` for a non-default state root. */
+export function unitBaseName(root = stateRoot()) {
+    if (root === defaultStateRoot())
+        return 'runly-daemon';
+    return `runly-daemon-${createHash('sha256').update(root).digest('hex').slice(0, 8)}`;
+}
+export function unitKind() {
+    if (process.platform === 'linux')
+        return 'systemd';
+    if (process.platform === 'darwin')
+        return 'launchd';
+    return null;
+}
+const daemonEntry = () => join(dirname(fileURLToPath(import.meta.url)), '..', 'daemon', 'index.js');
+/**
+ * The installing shell's variables a daemon needs and a unit would not have:
+ * a unit starts from systemd's or launchd's bare environment, while services,
+ * builds, upkeep and datastore commands run with the daemon's. Missing
+ * DOTNET_ROOT made every template bake of a .NET stack fail under the unit.
+ */
+const CAPTURE_EXACT = ['PATH', 'LANG', 'DOTNET_ROOT', 'DOCKER_HOST', 'DOCKER_CONTEXT', 'JAVA_HOME', 'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy'];
+const CAPTURE_PREFIXES = ['DOTNET_', 'LC_', 'NODE_', 'NVM_', 'SSL_CERT_'];
+/** runly's own per-process tags and per-call inputs: never baked into a unit. */
+const NEVER_CAPTURE = ['BACKLOT_STATE_DIR', 'BACKLOT_HOLDER_PID', 'BACKLOT_DB_COPY', 'BACKLOT_ENV_ID', 'BACKLOT_SERVICE', 'BACKLOT_STATE_ROOT', 'BACKLOT_FAKE_VERSION', 'RUNLY_SUPERVISOR', 'INVOCATION_ID'];
+/**
+ * `$NAME` / `${NAME}` the stack's commands read from the daemon's environment
+ * — run, build, upkeep, datastore and appliance commands, auth.token — when
+ * the install runs in a stack. Best effort: nothing when there is no manifest.
+ */
+function manifestReferences(cwd) {
+    try {
+        const m = loadStack(cwd, { validate: false }).manifest;
+        const texts = [];
+        for (const s of Object.values(m.services ?? {})) {
+            texts.push(s.run, typeof s.build === 'string' ? s.build : s.build?.run ?? '', s.ready?.cmd ?? '');
+        }
+        for (const u of m.upkeep ?? [])
+            texts.push(u.run);
+        for (const d of Object.values(m.datastores ?? {}))
+            texts.push(d.create ?? '', d.drop ?? '', d.template_restore ?? '', d.list ?? '');
+        for (const a of Object.values(m.appliances ?? {}))
+            texts.push(a.start ?? '', a.stop ?? '', a.ready ?? '');
+        texts.push(m.auth?.token ?? '');
+        const names = new Set();
+        for (const t of texts)
+            for (const match of t.matchAll(/\$\{?([A-Za-z_][A-Za-z0-9_]*)/g))
+                names.add(match[1]);
+        const inputs = Object.values(m.services ?? {}).flatMap((s) => Object.keys(s.env_from ?? {}));
+        return { names: [...names], inputs };
+    }
+    catch {
+        return { names: [], inputs: [] };
+    }
+}
+/**
+ * What the daemon runs with under the unit: the installing shell's PATH, the
+ * allowlist above, the BACKLOT_* settings, every variable the stack's commands
+ * reference (when installed from a stack) and each `--env NAME` — never an
+ * `env_from` input, which travels with each `up`. RUNLY_SUPERVISOR tells the
+ * daemon who restarts it (`status.supervisor`).
+ */
+export function captureEnvironment(root, kind, extra = [], cwd = process.cwd(), from = process.env) {
+    const refs = manifestReferences(cwd);
+    const inputs = new Set(refs.inputs);
+    const wanted = new Set([...refs.names, ...extra]);
+    const env = {};
+    const captured = [];
+    const notSet = [];
+    let leftOut = 0;
+    for (const [k, v] of Object.entries(from)) {
+        if (v === undefined)
+            continue;
+        const take = !NEVER_CAPTURE.includes(k) && !inputs.has(k) && (k.startsWith('BACKLOT_') || CAPTURE_EXACT.includes(k) || CAPTURE_PREFIXES.some((p) => k.startsWith(p)) || wanted.has(k));
+        if (take) {
+            env[k] = v;
+            captured.push(k);
+        }
+        else
+            leftOut++;
+    }
+    for (const k of wanted)
+        if (from[k] === undefined && !inputs.has(k) && !NEVER_CAPTURE.includes(k))
+            notSet.push(k);
+    env.BACKLOT_STATE_DIR = root;
+    env.RUNLY_SUPERVISOR = kind;
+    return { env, captured: captured.sort(), notSet: notSet.sort(), excluded: [...inputs].filter((k) => from[k] !== undefined).sort(), leftOut };
+}
+/** systemd quoting for one Environment= assignment. */
+const systemdEnv = (k, v) => `Environment="${`${k}=${v}`.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%')}"`;
+const systemdArg = (a) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(a) ? a : `"${a.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`).replace(/%/g, '%%').replace(/\$/g, '$$$$');
+/**
+ * A path in a setting that takes the rest of the line (WorkingDirectory=,
+ * StandardOutput=append:): never quoted — systemd reads quotes as part of the
+ * path and refuses it as not absolute — only `%` escaped. A state root with
+ * spaces works this way (verified with `systemd-analyze --user verify`).
+ */
+const systemdPath = (p) => p.replace(/%/g, '%%');
+const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+export function unitPlan(root = stateRoot(), extraEnv = [], opts = {}) {
+    const kind = unitKind();
+    if (!kind)
+        return null;
+    const name = unitBaseName(root);
+    const argv = [process.execPath, '--disable-warning=ExperimentalWarning', daemonEntry()];
+    // Locating an installed unit needs only its name and path, not the capture.
+    const environment = opts.capture === false
+        ? { env: { BACKLOT_STATE_DIR: root, RUNLY_SUPERVISOR: kind }, captured: [], notSet: [], excluded: [], leftOut: 0 }
+        : captureEnvironment(root, kind, extraEnv);
+    const env = environment.env;
+    const log = join(root, 'daemon.log');
+    if (kind === 'systemd') {
+        const dir = join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'systemd', 'user');
+        const content = [
+            '# Written by `runly daemon install` (decision 0039). `runly daemon uninstall` removes it.',
+            '[Unit]',
+            `Description=runly daemon (state root ${root})`,
+            'Documentation=https://github.com/ChristianKohlberg/backlot/blob/main/docs/overview.md#the-daemon',
+            '',
+            '[Service]',
+            'Type=simple',
+            `ExecStart=${argv.map(systemdArg).join(' ')}`,
+            ...Object.entries(env).map(([k, v]) => systemdEnv(k, v)),
+            `WorkingDirectory=${systemdPath(root)}`,
+            // A crash (non-zero exit, a fatal signal) restarts it within seconds;
+            // `runly daemon stop` and `runly update` exit 0 and are not undone.
+            'Restart=on-failure',
+            'RestartSec=1',
+            // Services are the daemon's children by design and must survive its
+            // crash (decision 0009): stop and restart signal the daemon alone, which
+            // stops its services itself on a clean stop.
+            'KillMode=process',
+            // `daemon stop` waits up to 60 s for services to stop; leave room.
+            'TimeoutStopSec=90',
+            `StandardOutput=append:${systemdPath(log)}`,
+            `StandardError=append:${systemdPath(log)}`,
+            '',
+            '[Install]',
+            'WantedBy=default.target',
+            '',
+        ].join('\n');
+        return { kind, name, path: join(dir, `${name}.service`), content, environment };
+    }
+    const label = name.replace(/^runly-daemon/, 'dev.runly.daemon');
+    const content = `<?xml version="1.0" encoding="UTF-8"?>
+<!-- Written by \`runly daemon install\` (decision 0039). \`runly daemon uninstall\` removes it. -->
+<!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>${xml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argv.map((a) => `    <string>${xml(a)}</string>`).join('\n')}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${Object.entries(env).map(([k, v]) => `    <key>${xml(k)}</key><string>${xml(v)}</string>`).join('\n')}
+  </dict>
+  <key>WorkingDirectory</key><string>${xml(root)}</string>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+  <key>ThrottleInterval</key><integer>2</integer>
+  <key>AbandonProcessGroup</key><true/>
+  <key>StandardOutPath</key><string>${xml(log)}</string>
+  <key>StandardErrorPath</key><string>${xml(log)}</string>
+</dict>
+</plist>
+`;
+    return { kind, name: label, path: join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`), content, environment };
+}
+/** The installed unit for this state root, if any. */
+export function installedUnit(root = stateRoot()) {
+    const plan = unitPlan(root, [], { capture: false });
+    return plan && existsSync(plan.path) ? plan : null;
+}
+/**
+ * Does the installed unit run THIS CLI's daemon? A unit written by another
+ * install (a global one, while this CLI is a checkout) would start a daemon of
+ * another version, which the version gate then refuses — and `runly update`
+ * would restart the same wrong one. Such a unit is left alone.
+ */
+export function unitRunsThisBuild(plan) {
+    try {
+        const xmlEntry = daemonEntry().replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+        const text = readFileSync(plan.path, 'utf8');
+        return text.includes(daemonEntry()) || text.includes(xmlEntry);
+    }
+    catch {
+        return false;
+    }
+}
+function run(cmd, args) {
+    try {
+        const output = execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15_000 });
+        return { ok: true, output: output.trim() };
+    }
+    catch (err) {
+        const e = err;
+        return { ok: false, output: String(e.stderr || e.message || err).trim() };
+    }
+}
+const uid = () => (typeof process.getuid === 'function' ? process.getuid() : 0);
+const systemctl = (...args) => run(process.env.BACKLOT_SYSTEMCTL || 'systemctl', ['--user', ...args]);
+const launchctl = (...args) => run(process.env.BACKLOT_LAUNCHCTL || 'launchctl', args);
+/** Write and enable the unit. Does not start it (the caller decides: a daemon may already run). */
+export function installUnit(plan) {
+    const steps = [];
+    mkdirSync(dirname(plan.path), { recursive: true });
+    const previous = existsSync(plan.path) ? readFileSync(plan.path, 'utf8') : null;
+    writeFileSync(plan.path, plan.content);
+    steps.push(`${previous === null ? 'wrote' : previous === plan.content ? 'kept' : 'updated'} ${plan.path}`);
+    if (plan.kind === 'systemd') {
+        for (const args of [['daemon-reload'], ['enable', `${plan.name}.service`]]) {
+            const r = systemctl(...args);
+            if (!r.ok)
+                return { steps, error: `systemctl --user ${args.join(' ')} failed: ${r.output}` };
+            steps.push(`systemctl --user ${args.join(' ')}`);
+        }
+    }
+    else {
+        // bootstrap loads it (and, with RunAtLoad, starts it); reloading an
+        // already-loaded label needs a bootout first.
+        launchctl('bootout', `gui/${uid()}/${plan.name}`);
+        const r = launchctl('bootstrap', `gui/${uid()}`, plan.path);
+        if (!r.ok)
+            return { steps, error: `launchctl bootstrap failed: ${r.output}` };
+        steps.push(`launchctl bootstrap gui/${uid()} ${plan.path}`);
+    }
+    return { steps };
+}
+/** Disable and remove the unit. The daemon that runs keeps running, unsupervised. */
+export function uninstallUnit(plan) {
+    const steps = [];
+    if (plan.kind === 'systemd') {
+        const r = systemctl('disable', `${plan.name}.service`);
+        if (r.ok)
+            steps.push(`systemctl --user disable ${plan.name}.service`);
+        rmSync(plan.path, { force: true });
+        steps.push(`removed ${plan.path}`);
+        const reload = systemctl('daemon-reload');
+        if (reload.ok)
+            steps.push('systemctl --user daemon-reload');
+    }
+    else {
+        // bootout stops a launchd job; the daemon is restarted by the next verb.
+        const r = launchctl('bootout', `gui/${uid()}/${plan.name}`);
+        if (r.ok)
+            steps.push(`launchctl bootout gui/${uid()}/${plan.name}`);
+        rmSync(plan.path, { force: true });
+        steps.push(`removed ${plan.path}`);
+    }
+    return { steps };
+}
+/** Start the installed unit (the CLI's autospawn path when one is installed). True when the start was accepted. */
+export function startUnit(plan) {
+    if (plan.kind === 'systemd')
+        return systemctl('start', `${plan.name}.service`).ok;
+    return launchctl('kickstart', `gui/${uid()}/${plan.name}`).ok;
+}
+//# sourceMappingURL=daemon-unit.js.map