@caelo-cms/provisioning 0.10.46 → 0.10.48

package/src/agent/systemd.ts

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Installs, re-pins and removes the agent's systemd --user units (#696
+ * Phase 4c). Every command goes through a {@link HostRunner} and the unit
+ * directory is a parameter, so tests run against a fake and a temp dir —
+ * nothing here touches the real systemd of the machine running the tests.
+ *
+ * User units stop with the user's last session unless the user "lingers";
+ * {@link installAgentUnits} turns lingering on (allowed for oneself on
+ * systemd-logind's default policy) and, where it may not, says which one
+ * command an administrator runs.
+ */
+
+import {
+  closeSync,
+  ftruncateSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+  writeSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { HostRunner } from "../self-hosted-release.js";
+import {
+  type AgentUnitSpec,
+  agentServiceUnit,
+  agentTimerUnit,
+  pinnedAgentVersion,
+} from "./units.js";
+
+/** The host the units go to. */
+export interface AgentHost {
+  readonly runner: HostRunner;
+  /** `~/.config/systemd/user` (or `$XDG_CONFIG_HOME/systemd/user`). */
+  readonly unitDir: string;
+  /** The operator's login name (for lingering). */
+  readonly user: string;
+  readonly platform: NodeJS.Platform;
+}
+
+/** The real host: this user's systemd user-unit directory. */
+export function currentAgentHost(runner: HostRunner): AgentHost {
+  const config = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return {
+    runner,
+    unitDir: join(config, "systemd", "user"),
+    user: process.env.USER || process.env.LOGNAME || "",
+    platform: process.platform,
+  };
+}
+
+/**
+ * Why the agent cannot be installed on this host, or null. Linux with a
+ * systemd user manager is the supported target; macOS (Docker Desktop) is
+ * a development setup, and there `upgrade` is run by hand.
+ */
+export async function agentHostProblem(host: AgentHost): Promise<string | null> {
+  if (host.platform !== "linux") {
+    return `the update agent runs on Linux hosts with systemd (this is ${host.platform}). Install updates with the upgrade command instead.`;
+  }
+  const r = await host.runner.run(["systemctl", "--user", "show-environment"]);
+  if (r.exitCode !== 0) {
+    return `systemd's user manager is not reachable (\`systemctl --user\`: ${r.stderr.trim().slice(0, 200) || `exit ${r.exitCode}`}). Log in to the host as this user directly (not via \`su\`), or install updates with the upgrade command.`;
+  }
+  return null;
+}
+
+/** `<unitDir>/<name>.service` + `.timer`. */
+export function agentUnitPaths(host: Pick<AgentHost, "unitDir">, name: string) {
+  return {
+    service: join(host.unitDir, `${name}.service`),
+    timer: join(host.unitDir, `${name}.timer`),
+  };
+}
+
+export type AgentUnitsResult =
+  | { readonly ok: true; readonly warnings: readonly string[] }
+  | { readonly ok: false; readonly error: string };
+
+async function systemctl(host: AgentHost, ...args: string[]): Promise<string | null> {
+  const r = await host.runner.run(["systemctl", "--user", ...args]);
+  return r.exitCode === 0
+    ? null
+    : `systemctl --user ${args.join(" ")}: ${r.stderr.trim().slice(0, 300) || `exit ${r.exitCode}`}`;
+}
+
+/**
+ * Write both units, reload, enable + start the timer, and make sure the
+ * user lingers. Idempotent: re-running rewrites the same files.
+ */
+export async function installAgentUnits(
+  spec: AgentUnitSpec,
+  host: AgentHost,
+): Promise<AgentUnitsResult> {
+  const paths = agentUnitPaths(host, spec.name);
+  try {
+    mkdirSync(host.unitDir, { recursive: true });
+    writeFileSync(paths.service, agentServiceUnit(spec), { mode: 0o644 });
+    writeFileSync(paths.timer, agentTimerUnit(spec), { mode: 0o644 });
+  } catch (e) {
+    return { ok: false, error: `could not write the units: ${(e as Error).message}` };
+  }
+  for (const args of [["daemon-reload"], ["enable", "--now", `${spec.name}.timer`]]) {
+    const error = await systemctl(host, ...args);
+    if (error) return { ok: false, error };
+  }
+  const warnings: string[] = [];
+  const linger = await ensureLinger(host);
+  if (linger) warnings.push(linger);
+  return { ok: true, warnings };
+}
+
+/** Lingering on for the user; returns a warning when it could not be. */
+async function ensureLinger(host: AgentHost): Promise<string | null> {
+  if (!host.user) return "could not tell the user name, so lingering was not checked";
+  const show = await host.runner.run(["loginctl", "show-user", host.user, "--property=Linger"]);
+  if (show.exitCode === 0 && show.stdout.trim() === "Linger=yes") return null;
+  const enable = await host.runner.run(["loginctl", "enable-linger", host.user]);
+  if (enable.exitCode === 0) return null;
+  return `the agent only runs while ${host.user} is logged in: lingering could not be switched on (${enable.stderr.trim().slice(0, 200) || `exit ${enable.exitCode}`}). Have an administrator run \`sudo loginctl enable-linger ${host.user}\` once.`;
+}
+
+/** The release the installed service runs, or null when it is not installed. */
+export function installedAgentVersion(host: AgentHost, name: string): string | null {
+  const { service } = agentUnitPaths(host, name);
+  try {
+    return pinnedAgentVersion(readFileSync(service, "utf8"));
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw e;
+  }
+}
+
+/**
+ * Re-pin an installed agent to `spec.version` (after an update). Does
+ * nothing when the agent is not installed.
+ */
+export async function repinAgentUnits(
+  spec: AgentUnitSpec,
+  host: AgentHost,
+): Promise<AgentUnitsResult & { readonly installed?: boolean }> {
+  const { service } = agentUnitPaths(host, spec.name);
+  try {
+    // "r+" opens only an existing file (ENOENT otherwise), so the check and
+    // the rewrite are one step — no window for the file to change between.
+    const fd = openSync(service, "r+");
+    try {
+      ftruncateSync(fd, 0);
+      writeSync(fd, agentServiceUnit(spec), 0, "utf8");
+    } finally {
+      closeSync(fd);
+    }
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") {
+      return { ok: true, warnings: [], installed: false };
+    }
+    return { ok: false, error: `could not rewrite ${service}: ${(e as Error).message}` };
+  }
+  const error = await systemctl(host, "daemon-reload");
+  return error ? { ok: false, error } : { ok: true, warnings: [], installed: true };
+}
+
+/** Stop + disable the timer and delete both units. */
+export async function uninstallAgentUnits(
+  host: AgentHost,
+  name: string,
+): Promise<AgentUnitsResult> {
+  const warnings: string[] = [];
+  const disabled = await systemctl(host, "disable", "--now", `${name}.timer`);
+  if (disabled) warnings.push(disabled);
+  const paths = agentUnitPaths(host, name);
+  rmSync(paths.service, { force: true });
+  rmSync(paths.timer, { force: true });
+  const reload = await systemctl(host, "daemon-reload");
+  if (reload) warnings.push(reload);
+  return { ok: true, warnings };
+}
+
+/** `systemctl --user status` of both units (text for the terminal). */
+export async function agentUnitStatus(host: AgentHost, name: string): Promise<string> {
+  const r = await host.runner.run([
+    "systemctl",
+    "--user",
+    "--no-pager",
+    "status",
+    `${name}.timer`,
+    `${name}.service`,
+  ]);
+  // status exits 3 for an inactive oneshot service; the text is what matters.
+  return (r.stdout || r.stderr).trim();
+}
+
+/** The argv that shows the agent's log (journald). */
+export function agentLogsArgv(name: string, opts: { lines: number; follow: boolean }): string[] {
+  return [
+    "journalctl",
+    "--user",
+    "--no-pager",
+    "-u",
+    `${name}.service`,
+    "-n",
+    String(opts.lines),
+    ...(opts.follow ? ["-f"] : []),
+  ];
+}

package/src/agent/units.test.ts

@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The agent's systemd units (agent/units.ts) and their installation
+ * (agent/systemd.ts) — against a temp unit directory and a fake runner, so
+ * no real systemd is touched.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CommandResult, HostRunner } from "../self-hosted-release.js";
+import {
+  type AgentHost,
+  agentHostProblem,
+  agentLogsArgv,
+  installAgentUnits,
+  installedAgentVersion,
+  repinAgentUnits,
+  uninstallAgentUnits,
+} from "./systemd.js";
+import {
+  type AgentUnitSpec,
+  agentServiceUnit,
+  agentTimerUnit,
+  agentUnitName,
+  pinnedAgentVersion,
+} from "./units.js";
+
+const SPEC: AgentUnitSpec = {
+  name: "caelo-agent-example-com",
+  domain: "example.com",
+  version: "0.10.47",
+  bunPath: "/home/op/.bun/bin/bun",
+  caeloDir: "/srv/caelo site/.caelo",
+  workDir: "/srv/caelo site",
+  path: "/home/op/.bun/bin:/usr/local/bin:/usr/bin:/bin",
+};
+
+describe("agent units", () => {
+  it("names one agent per install after its domain, kept apart by the install's folder", () => {
+    expect(agentUnitName("Example.com", "/srv/a/.caelo")).toMatch(
+      /^caelo-agent-example-com-[0-9a-f]{8}$/,
+    );
+    expect(agentUnitName("a.b.example.com", "/srv/one/.caelo")).not.toBe(
+      agentUnitName("a-b.example.com", "/srv/two/.caelo"),
+    );
+    expect(agentUnitName("example.com", "/srv/a/.caelo")).toBe(
+      agentUnitName("example.com", "/srv/a/.caelo"),
+    );
+    expect(() => agentUnitName("...", "/srv/a/.caelo")).toThrow();
+  });
+
+  it("runs the pinned CLI as a oneshot, as the user, never as root", () => {
+    const unit = agentServiceUnit(SPEC);
+    expect(unit).toContain("Type=oneshot");
+    expect(unit).toContain(
+      'ExecStart="/home/op/.bun/bin/bun" "x" "--bun" "@caelo-cms/provisioning@0.10.47" "agent" "run"',
+    );
+    expect(unit).toContain('WorkingDirectory="/srv/caelo site"');
+    expect(unit).toContain('Environment="CAELO_SELF_HOSTED_DIR=/srv/caelo site/.caelo"');
+    expect(unit).toContain("UMask=0077");
+    expect(unit).toContain("NoNewPrivileges=yes");
+    expect(unit).not.toMatch(/^User=|^Group=|docker\.sock/m);
+    expect(unit).not.toContain("DOCKER_HOST");
+    expect(pinnedAgentVersion(unit)).toBe("0.10.47");
+  });
+
+  it("passes a rootless DOCKER_HOST through and escapes systemd specifiers", () => {
+    const unit = agentServiceUnit({
+      ...SPEC,
+      dockerHost: "unix:///run/user/1000/docker.sock",
+      workDir: "/srv/100%",
+    });
+    expect(unit).toContain('Environment="DOCKER_HOST=unix:///run/user/1000/docker.sock"');
+    expect(unit).toContain('WorkingDirectory="/srv/100%%"');
+  });
+
+  it("after an update, runs the provenance-verified CLI instead of bun x", () => {
+    const cliPath =
+      "/srv/caelo site/.caelo/agent/cli/caelo-0.11.0/node_modules/@caelo-cms/provisioning/dist/cli.js";
+    const unit = agentServiceUnit({ ...SPEC, version: "0.11.0", cliPath });
+    expect(unit).toContain(`ExecStart="/home/op/.bun/bin/bun" "${cliPath}" "agent" "run"`);
+    expect(unit).not.toContain('"x"');
+    expect(pinnedAgentVersion(unit)).toBe("0.11.0");
+  });
+
+  it("refuses values that cannot be one systemd word", () => {
+    expect(() => agentServiceUnit({ ...SPEC, workDir: '/srv/"x"' })).toThrow();
+    expect(() => agentServiceUnit({ ...SPEC, path: "/bin\nExecStartPre=/evil" })).toThrow();
+    expect(() => agentServiceUnit({ ...SPEC, version: "latest" })).toThrow();
+  });
+
+  it("polls a minute after each run ends, from boot", () => {
+    const timer = agentTimerUnit(SPEC);
+    expect(timer).toContain("OnUnitInactiveSec=60s");
+    expect(timer).toContain("OnBootSec=2min");
+    expect(timer).toContain("OnActiveSec=1min");
+    expect(timer).toContain("Unit=caelo-agent-example-com.service");
+    expect(timer).toContain("WantedBy=timers.target");
+  });
+
+  it("shows the service's journal", () => {
+    expect(agentLogsArgv("caelo-agent-x", { lines: 50, follow: true })).toEqual([
+      "journalctl",
+      "--user",
+      "--no-pager",
+      "-u",
+      "caelo-agent-x.service",
+      "-n",
+      "50",
+      "-f",
+    ]);
+  });
+});
+
+type Rule = (line: string) => Partial<CommandResult> | undefined;
+
+function fakeRunner(rules: Rule[] = []): HostRunner & { calls: string[] } {
+  const calls: string[] = [];
+  return {
+    calls,
+    async run(argv) {
+      const line = argv.join(" ");
+      calls.push(line);
+      const hit = rules.map((r) => r(line)).find((r) => r !== undefined);
+      return { exitCode: 0, stdout: "", stderr: "", ...hit };
+    },
+  };
+}
+
+describe("agent units on the host", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "caelo-agent-units-"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  const hostWith = (runner: HostRunner, platform: NodeJS.Platform = "linux"): AgentHost => ({
+    runner,
+    unitDir: join(dir, "systemd", "user"),
+    user: "op",
+    platform,
+  });
+
+  it("supports Linux with a systemd user manager only", async () => {
+    expect(await agentHostProblem(hostWith(fakeRunner(), "darwin"))).toContain("Linux");
+    const noBus = fakeRunner([
+      (l) =>
+        l.includes("show-environment")
+          ? { exitCode: 1, stderr: "Failed to connect to bus" }
+          : undefined,
+    ]);
+    expect(await agentHostProblem(hostWith(noBus))).toContain("Failed to connect to bus");
+    expect(await agentHostProblem(hostWith(fakeRunner()))).toBeNull();
+  });
+
+  it("writes both units, enables the timer and switches lingering on — idempotently", async () => {
+    const runner = fakeRunner([
+      (l) => (l.startsWith("loginctl show-user") ? { stdout: "Linger=no\n" } : undefined),
+    ]);
+    const host = hostWith(runner);
+    for (let i = 0; i < 2; i++) {
+      expect(await installAgentUnits(SPEC, host)).toEqual({ ok: true, warnings: [] });
+    }
+    const service = readFileSync(join(host.unitDir, `${SPEC.name}.service`), "utf8");
+    expect(service).toBe(agentServiceUnit(SPEC));
+    expect(existsSync(join(host.unitDir, `${SPEC.name}.timer`))).toBe(true);
+    expect(runner.calls).toContain("systemctl --user daemon-reload");
+    expect(runner.calls).toContain(`systemctl --user enable --now ${SPEC.name}.timer`);
+    expect(runner.calls).toContain("loginctl enable-linger op");
+    expect(installedAgentVersion(host, SPEC.name)).toBe("0.10.47");
+  });
+
+  it("says what an administrator runs when lingering may not be switched on", async () => {
+    const runner = fakeRunner([
+      (l) =>
+        l.startsWith("loginctl enable-linger")
+          ? { exitCode: 1, stderr: "Access denied" }
+          : undefined,
+    ]);
+    const r = await installAgentUnits(SPEC, hostWith(runner));
+    expect(r.ok && r.warnings.join(" ")).toContain("sudo loginctl enable-linger op");
+  });
+
+  it("fails loudly when systemd refuses the timer", async () => {
+    const runner = fakeRunner([
+      (l) => (l.includes("enable --now") ? { exitCode: 1, stderr: "Unit not found" } : undefined),
+    ]);
+    const r = await installAgentUnits(SPEC, hostWith(runner));
+    expect(r).toEqual({
+      ok: false,
+      error: `systemctl --user enable --now ${SPEC.name}.timer: Unit not found`,
+    });
+  });
+
+  it("re-pins an installed agent after an update, and leaves an absent one absent", async () => {
+    const runner = fakeRunner();
+    const host = hostWith(runner);
+    expect(await repinAgentUnits({ ...SPEC, version: "0.11.0" }, host)).toMatchObject({
+      ok: true,
+      installed: false,
+    });
+    expect(installedAgentVersion(host, SPEC.name)).toBeNull();
+    await installAgentUnits(SPEC, host);
+    expect(await repinAgentUnits({ ...SPEC, version: "0.11.0" }, host)).toMatchObject({
+      ok: true,
+      installed: true,
+    });
+    expect(installedAgentVersion(host, SPEC.name)).toBe("0.11.0");
+  });
+
+  it("uninstalls: timer off, both files gone", async () => {
+    const runner = fakeRunner();
+    const host = hostWith(runner);
+    await installAgentUnits(SPEC, host);
+    expect((await uninstallAgentUnits(host, SPEC.name)).ok).toBe(true);
+    expect(runner.calls).toContain(`systemctl --user disable --now ${SPEC.name}.timer`);
+    expect(existsSync(join(host.unitDir, `${SPEC.name}.service`))).toBe(false);
+    expect(existsSync(join(host.unitDir, `${SPEC.name}.timer`))).toBe(false);
+  });
+});

package/src/agent/units.ts

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The systemd units of `caelo-agent` (#696 Phase 4c), as text. Pure, so the
+ * exact files are unit-tested; agent/systemd.ts installs them.
+ *
+ * Why a systemd --user timer on the host, and not a container: the agent
+ * has to run `docker compose` for the install, and the only way a container
+ * could is the Docker socket — root on the host for anything that gets into
+ * that container (Watchtower, the usual answer, was archived in 2025 and
+ * verifies no signatures). The agent instead runs as the operator who ran
+ * `init`, a member of the `docker` group like that operator already is to
+ * run Compose at all; nothing new gets Docker access, and no unit runs as
+ * root.
+ *
+ * Shape: a oneshot service (one poll: heartbeat, then claim and run at most
+ * one request) started by a timer every {@link PLATFORM_UPDATE_AGENT_POLL_SECONDS}
+ * seconds after the previous run ended — systemd never starts the service
+ * while a run (an upgrade can take many minutes) is still active.
+ *
+ * The service runs the provisioning CLI pinned to an exact release
+ * (`bun x --bun @caelo-cms/provisioning@<version> agent run`); a successful
+ * update re-pins it to the release it installed.
+ */
+
+import { createHash } from "node:crypto";
+import { PLATFORM_UPDATE_AGENT_POLL_SECONDS } from "@caelo-cms/shared";
+
+/** Everything the units name; all paths absolute. */
+export interface AgentUnitSpec {
+  /** Unit base name (`caelo-agent-<domain>-<hash>`), see {@link agentUnitName}. */
+  readonly name: string;
+  readonly domain: string;
+  /** The provisioning release the service runs. */
+  readonly version: string;
+  /** The `bun` binary (the one that ran `init`). */
+  readonly bunPath: string;
+  /** The install's `.caelo/` directory. */
+  readonly caeloDir: string;
+  /** Where `.caelo/` lives (the service's working directory). */
+  readonly workDir: string;
+  /** PATH for the service: docker, cosign and bun must be on it. */
+  readonly path: string;
+  /** DOCKER_HOST of the installing shell (rootless Docker), when set. */
+  readonly dockerHost?: string;
+  /**
+   * The provenance-verified CLI of {@link version} (agent/cli-provenance.ts)
+   * — what an update re-pins the agent to. Without it the service runs the
+   * release the operator installed with (`bun x`, as they did by hand).
+   */
+  readonly cliPath?: string;
+}
+
+/** The longest a single run (one full upgrade) may take before systemd stops it. */
+export const AGENT_RUN_TIMEOUT_MINUTES = 80;
+
+/**
+ * `caelo-agent-<domain>-<hash>`: one agent per install, several installs
+ * per host possible. The slug is for people; the hash of the install's
+ * `.caelo/` path keeps two installs apart even when their slugs collide
+ * (`a.b.example.com` vs `a-b.example.com`).
+ */
+export function agentUnitName(domain: string, caeloDir: string): string {
+  const slug = domain
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  if (!slug) throw new Error(`cannot name the agent unit after domain ${JSON.stringify(domain)}`);
+  const hash = createHash("sha256").update(caeloDir).digest("hex").slice(0, 8);
+  return `caelo-agent-${slug}-${hash}`;
+}
+
+/** The package the service runs, pinned. */
+export function agentPackageRef(version: string): string {
+  if (!/^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new Error(`not a release version: ${JSON.stringify(version)}`);
+  }
+  return `@caelo-cms/provisioning@${version}`;
+}
+
+/**
+ * One systemd word: double-quoted, `%` escaped (systemd specifiers). Values
+ * with a quote, backslash or control character are refused rather than
+ * escaped — they are paths and versions, and such a path is a mistake.
+ */
+function word(value: string): string {
+  if (!value || /["\\\p{Cc}]/u.test(value)) {
+    throw new Error(`cannot put ${JSON.stringify(value)} into a systemd unit`);
+  }
+  return `"${value.replace(/%/g, "%%")}"`;
+}
+
+/** `Environment="KEY=value"`. */
+function environment(key: string, value: string): string {
+  return `Environment=${word(`${key}=${value}`)}`;
+}
+
+/** The argv of one agent run (also what `agent status` shows). */
+export function agentRunArgv(
+  spec: Pick<AgentUnitSpec, "bunPath" | "version" | "cliPath">,
+): string[] {
+  if (spec.cliPath) return [spec.bunPath, spec.cliPath, "agent", "run"];
+  return [spec.bunPath, "x", "--bun", agentPackageRef(spec.version), "agent", "run"];
+}
+
+/** `<name>.service`. */
+export function agentServiceUnit(spec: AgentUnitSpec): string {
+  return [
+    "# SPDX-License-Identifier: MPL-2.0",
+    "# Generated by cms-provision (agent install) — do not edit; re-run it instead.",
+    "[Unit]",
+    `Description=Caelo update agent for ${spec.domain}`,
+    "Documentation=https://caelo-cms.com/install-self-hosted",
+    "After=network-online.target",
+    "",
+    "[Service]",
+    "Type=oneshot",
+    `WorkingDirectory=${word(spec.workDir)}`,
+    environment("CAELO_SELF_HOSTED_DIR", spec.caeloDir),
+    environment("PATH", spec.path),
+    ...(spec.dockerHost ? [environment("DOCKER_HOST", spec.dockerHost)] : []),
+    `ExecStart=${agentRunArgv(spec).map(word).join(" ")}`,
+    `TimeoutStartSec=${AGENT_RUN_TIMEOUT_MINUTES}min`,
+    // Backups, config.json and the lock file: the operator's only.
+    "UMask=0077",
+    "NoNewPrivileges=yes",
+    "Nice=5",
+    "",
+  ].join("\n");
+}
+
+/** `<name>.timer`. */
+export function agentTimerUnit(spec: Pick<AgentUnitSpec, "name" | "domain">): string {
+  return [
+    "# SPDX-License-Identifier: MPL-2.0",
+    "# Generated by cms-provision (agent install) — do not edit; re-run it instead.",
+    "[Unit]",
+    `Description=Poll for Caelo updates for ${spec.domain}`,
+    "",
+    "[Timer]",
+    // The first poll a minute after the timer starts (install, boot);
+    // then a minute after each run ends.
+    "OnActiveSec=1min",
+    "OnBootSec=2min",
+    `OnUnitInactiveSec=${PLATFORM_UPDATE_AGENT_POLL_SECONDS}s`,
+    "AccuracySec=5s",
+    `Unit=${spec.name}.service`,
+    "",
+    "[Install]",
+    "WantedBy=timers.target",
+    "",
+  ].join("\n");
+}
+
+/** The release an installed service file runs, or null when it names none. */
+export function pinnedAgentVersion(serviceUnit: string): string | null {
+  const exec = /^ExecStart=.*$/m.exec(serviceUnit)?.[0] ?? "";
+  const m =
+    /@caelo-cms\/provisioning@([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?)"/.exec(exec) ??
+    /\/caelo-([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?)\/node_modules\//.exec(exec);
+  return m?.[1] ?? null;
+}