@caelo-cms/provisioning 0.10.46 → 0.10.48

package/dist/agent/lock.js

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * One upgrade at a time per self-hosted install (#696 Phase 4c): the host
+ * agent and a hand-run `cms-provision upgrade` both take
+ * `.caelo/upgrade.lock` for the whole run — two concurrent rolls would
+ * overwrite each other's Compose file and restore the wrong one on rollback.
+ *
+ * The file holds the holder's pid; a lock whose process is gone (a crash, a
+ * reboot) is taken over rather than blocking updates forever.
+ *
+ * The record is written to a private temp file first and then hard-linked
+ * into place, so the lock file never exists half-written: a reader that
+ * finds it can always trust its pid. (An unreadable file is only taken over
+ * once it is older than any run could be.)
+ */
+import { linkSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** `.caelo/upgrade.lock`. */
+export function upgradeLockPath(caeloDir) {
+    return join(caeloDir, "upgrade.lock");
+}
+/** An unreadable lock file younger than this still counts as held (longer than any run). */
+const UNREADABLE_LOCK_MAX_AGE_MS = 2 * 60 * 60 * 1000;
+/** The lock file's modification time (0 when it vanished meanwhile). */
+function lockMtime(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Whether process `pid` exists (signal 0 checks without signalling). */
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // EPERM: it exists, it is just someone else's.
+        return e.code === "EPERM";
+    }
+}
+/**
+ * Take the install's upgrade lock for `holder`.
+ *
+ * @returns the release function (idempotent)
+ * @throws when a live process holds it, naming that holder
+ */
+export function acquireUpgradeLock(caeloDir, holder, deps = {}) {
+    const path = upgradeLockPath(caeloDir);
+    const alive = deps.alive ?? processAlive;
+    const record = {
+        pid: deps.pid ?? process.pid,
+        holder,
+        at: new Date().toISOString(),
+    };
+    const temp = `${path}.${record.pid}.${crypto.randomUUID()}`;
+    writeFileSync(temp, JSON.stringify(record), { mode: 0o600, flag: "wx" });
+    try {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                // Atomic: fails with EEXIST when someone holds the lock.
+                linkSync(temp, path);
+                let released = false;
+                return () => {
+                    if (released)
+                        return;
+                    released = true;
+                    rmSync(path, { force: true });
+                };
+            }
+            catch (e) {
+                if (e.code !== "EEXIST")
+                    throw e;
+            }
+            let held = null;
+            try {
+                held = JSON.parse(readFileSync(path, "utf8"));
+            }
+            catch {
+                // Corrupt (never half-written, see above): take it over only when old.
+            }
+            if (held === null) {
+                if (Date.now() - lockMtime(path) < UNREADABLE_LOCK_MAX_AGE_MS) {
+                    throw new Error(`another upgrade holds ${path} (its record is unreadable).`);
+                }
+            }
+            else if (typeof held.pid === "number" && alive(held.pid)) {
+                throw new Error(`${held.holder ?? "another upgrade"} is running on this install (pid ${held.pid}, since ${held.at ?? "?"}).`);
+            }
+            rmSync(path, { force: true });
+        }
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+    throw new Error(`could not take ${path}; another process keeps creating it.`);
+}
+//# sourceMappingURL=lock.js.map

package/dist/agent/lock.js.map

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

package/dist/agent/queue.d.ts

@@ -0,0 +1,35 @@
+import type { UpdateQueue } from "../upgrader-job.js";
+/** One check-in of the agent (`platform_update_agent`). */
+export interface AgentHeartbeat {
+    /** The Caelo release of the agent's own code. */
+    readonly agentVersion: string;
+    /** The host it runs on. */
+    readonly host: string;
+    /** Why an install would fail on this host right now; null when none. */
+    readonly problem: string | null;
+}
+/** The upgrader's queue plus the agent's heartbeat. */
+export interface AgentQueue extends UpdateQueue {
+    heartbeat(beat: AgentHeartbeat): Promise<void>;
+}
+/** Where the agent's database login reaches Postgres (loopback only). */
+export interface AgentDbConnection {
+    readonly user: string;
+    readonly password: string;
+    readonly port: number;
+}
+/** An open queue and the pools behind it. */
+export interface OpenedAgentQueue {
+    readonly queue: AgentQueue;
+    close(): Promise<void>;
+}
+/** Opens the queue over the agent's login (`@caelo-cms/platform-updater` agent-db). */
+export type OpenAgentQueue = (conn: AgentDbConnection) => Promise<OpenedAgentQueue>;
+/**
+ * Load the function that opens the agent's queue: the bundle shipped in the
+ * published package, else (a source checkout) the workspace package.
+ *
+ * @throws when neither is present — a build that skipped the bundle
+ */
+export declare function loadAgentQueueOpener(): Promise<OpenAgentQueue>;
+//# sourceMappingURL=queue.d.ts.map

package/dist/agent/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/agent/queue.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2BAA2B;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,uDAAuD;AACvD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,SAAS,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,uFAAuF;AACvF,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAiBpF;;;;;GAKG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,cAAc,CAAC,CAmBpE"}

package/dist/agent/queue.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * The self-hosted host agent's database side (#696 Phase 4c): the same
+ * {@link UpdateQueue} the Google Cloud upgrader job drives, plus the
+ * heartbeat the admin reads to decide whether to offer "Install update".
+ *
+ * The queue is implemented in `@caelo-cms/platform-updater` (the job ops,
+ * through the Query API — never raw SQL), which the published CLI cannot
+ * depend on: it is private, and it depends on this package. So the build
+ * bundles its `agent-db` entry into `dist/agent-db.js` (package.json
+ * `build`), and {@link loadAgentQueueOpener} imports that file; a source
+ * checkout imports the workspace package instead.
+ */
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * Where the bundle is, relative to this module: next to the compiled CLI
+ * (`dist/agent/queue.js` → `dist/agent-db.js`), or — when Bun loads the
+ * published package's `src/` through its `bun` export condition — in the
+ * package's `dist/`.
+ */
+const BUNDLED_AGENT_DB = ["../agent-db.js", "../../dist/agent-db.js"];
+/**
+ * The workspace package a source checkout loads instead. Held in a variable
+ * so TypeScript does not resolve it: provisioning cannot declare a
+ * dependency on the package that depends on it.
+ */
+const WORKSPACE_AGENT_DB = "@caelo-cms/platform-updater/agent-db";
+/**
+ * Load the function that opens the agent's queue: the bundle shipped in the
+ * published package, else (a source checkout) the workspace package.
+ *
+ * @throws when neither is present — a build that skipped the bundle
+ */
+export async function loadAgentQueueOpener() {
+    const bundled = BUNDLED_AGENT_DB.map((rel) => new URL(rel, import.meta.url)).find((url) => existsSync(fileURLToPath(url)));
+    const specifier = bundled?.href ?? WORKSPACE_AGENT_DB;
+    let mod;
+    try {
+        mod = (await import(specifier));
+    }
+    catch (e) {
+        throw new Error(`the update agent's database module is missing (${specifier}: ${e instanceof Error ? e.message : String(e)}). This @caelo-cms/provisioning build is incomplete — reinstall it.`);
+    }
+    if (typeof mod.openAgentQueue !== "function") {
+        throw new Error(`${specifier} does not export openAgentQueue — reinstall @caelo-cms/provisioning.`);
+    }
+    return mod.openAgentQueue;
+}
+//# sourceMappingURL=queue.js.map

package/dist/agent/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/agent/queue.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAkCzC;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,CAAC,gBAAgB,EAAE,wBAAwB,CAAU,CAAC;AAE/E;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,sCAAsC,CAAC;AAElE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CACxF,UAAU,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAC/B,CAAC;IACF,MAAM,SAAS,GAAG,OAAO,EAAE,IAAI,IAAI,kBAAkB,CAAC;IACtD,IAAI,GAAwC,CAAC;IAC7C,IAAI,CAAC;QACH,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAAwC,CAAC;IACzE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,kDAAkD,SAAS,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,qEAAqE,CAChL,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb,GAAG,SAAS,sEAAsE,CACnF,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC,cAAc,CAAC;AAC5B,CAAC"}

package/dist/agent/run.d.ts

@@ -0,0 +1,97 @@
+/**
+ * One poll of the self-hosted host agent (#696 Phase 4c) — what the
+ * `caelo-agent-<domain>-<hash>` timer runs every minute:
+ *
+ *   1. preflight (Docker reachable, cosign present, a recorded release) and
+ *      a heartbeat with the result, so Settings → Updates knows the agent is
+ *      alive and what would stop an install before the Owner clicks;
+ *   2. claim the oldest pending request (ending a run that died mid-way) —
+ *      the admin only ever writes the request row;
+ *   3. verify the target's signed release manifest (cosign, fixed registry
+ *      and signer — nothing from the request but the version) and decide
+ *      with the upgrader's own refusal matrix (upgrader-assess.ts): bad
+ *      signature, downgrade, below minFromVersion, contract migrations or a
+ *      policy refusal on an automatic run. Self-hosted has no separately
+ *      converged infrastructure, so the infra-contract row never applies;
+ *   4. install the TARGET release's own CLI from npm and verify its registry
+ *      signatures + provenance (agent/cli-provenance.ts, the checks of the
+ *      Cloud Shell runner) — refused outright when they fail;
+ *   5. only then run that CLI's `agent apply` (agent/apply.ts), which
+ *      performs the same backup → pull → migrate → roll → health → rollback
+ *      as a hand-run `upgrade` and narrates it into the request's timeline.
+ *      The target's CLI renders the target's Compose file, so a release that
+ *      changes the stack needs no extra step. No code of the target runs
+ *      before its manifest verified and passed the checks above;
+ *   6. if that process ended without recording an end state, end the
+ *      request as failed with its output.
+ *
+ * The install's upgrade lock is held for the whole run, so a hand-run
+ * `upgrade` and the agent never roll at the same time.
+ */
+import { type PlatformUpdateTrigger } from "@caelo-cms/shared";
+import type { ReleaseManifestResult } from "../release-manifest.js";
+import type { SelfHostedRelease } from "../self-hosted-release.js";
+import type { UpdateEndStatus } from "../upgrader-job.js";
+import { type JobLog } from "../upgrader-reporter.js";
+import type { VerifiedCli } from "./cli-provenance.js";
+import type { AgentQueue } from "./queue.js";
+/** What the target release's `agent apply` is told (argv of the child). */
+export interface AgentApplyRequest {
+    readonly requestId: string;
+    readonly targetVersion: string;
+    readonly trigger: PlatformUpdateTrigger;
+    /** From the verified manifest: the images the target must resolve to. */
+    readonly digests: {
+        readonly admin: string;
+        readonly gateway: string;
+    };
+    /** The target's CLI, installed and provenance-verified (agent/cli-provenance.ts). */
+    readonly cliPath: string;
+}
+/** How the target's `agent apply` process ended. */
+export interface AgentApplyOutcome {
+    readonly exitCode: number;
+    /** The tail of its output, for the timeline when it recorded nothing. */
+    readonly output: string;
+}
+export interface AgentRunDeps {
+    readonly queue: AgentQueue;
+    /** This agent's own release (CAELO_VERSION). */
+    readonly agentVersion: string;
+    readonly host: string;
+    /** Why an install would fail on this host now, or null. */
+    readonly preflight: () => Promise<string | null>;
+    /** `.caelo/release.json` (null when none is recorded; throws when malformed). */
+    readonly readInstalled: () => SelfHostedRelease | null;
+    /** fetchVerifiedReleaseManifest against the fixed registry. */
+    readonly fetchManifest: (version: string) => Promise<ReleaseManifestResult>;
+    /** Take the install's upgrade lock (agent/lock.ts); throws when held. */
+    readonly lock: () => () => void;
+    /**
+     * Install the target release's CLI and verify its npm signatures +
+     * provenance (agent/cli-provenance.ts). Nothing of it runs unless this
+     * passes.
+     */
+    readonly verifyTargetCli: (version: string) => Promise<VerifiedCli>;
+    /** Run the target release's `agent apply` and wait for it. */
+    readonly applyTarget: (request: AgentApplyRequest) => Promise<AgentApplyOutcome>;
+    readonly now: () => Date;
+    readonly log: JobLog;
+    readonly sleep?: (ms: number) => Promise<void>;
+    /**
+     * How often the agent keeps checking in while the target's CLI runs (an
+     * update takes minutes; the admin would otherwise think the agent gone).
+     * Default: every poll interval.
+     */
+    readonly heartbeatEveryMs?: number;
+}
+/** What one poll did. */
+export interface AgentRunResult {
+    readonly exitCode: number;
+    readonly requestId: string | null;
+    /** The end the agent itself recorded (null when the target's CLI did, or nothing ran). */
+    readonly status: UpdateEndStatus | null;
+}
+/** One poll. Never throws; see the file comment for the sequence. */
+export declare function runAgentOnce(deps: AgentRunDeps): Promise<AgentRunResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/agent/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/agent/run.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAsC,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACnG,OAAO,KAAK,EAAmB,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACrF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,OAAO,KAAK,EAAa,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErE,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACjD,iFAAiF;IACjF,QAAQ,CAAC,aAAa,EAAE,MAAM,iBAAiB,GAAG,IAAI,CAAC;IACvD,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC5E,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,IAAI,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACpE,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACjF,QAAQ,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,yBAAyB;AACzB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;CACzC;AAED,qEAAqE;AACrE,wBAAsB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAmL9E"}

package/dist/agent/run.js

@@ -0,0 +1,198 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * One poll of the self-hosted host agent (#696 Phase 4c) — what the
+ * `caelo-agent-<domain>-<hash>` timer runs every minute:
+ *
+ *   1. preflight (Docker reachable, cosign present, a recorded release) and
+ *      a heartbeat with the result, so Settings → Updates knows the agent is
+ *      alive and what would stop an install before the Owner clicks;
+ *   2. claim the oldest pending request (ending a run that died mid-way) —
+ *      the admin only ever writes the request row;
+ *   3. verify the target's signed release manifest (cosign, fixed registry
+ *      and signer — nothing from the request but the version) and decide
+ *      with the upgrader's own refusal matrix (upgrader-assess.ts): bad
+ *      signature, downgrade, below minFromVersion, contract migrations or a
+ *      policy refusal on an automatic run. Self-hosted has no separately
+ *      converged infrastructure, so the infra-contract row never applies;
+ *   4. install the TARGET release's own CLI from npm and verify its registry
+ *      signatures + provenance (agent/cli-provenance.ts, the checks of the
+ *      Cloud Shell runner) — refused outright when they fail;
+ *   5. only then run that CLI's `agent apply` (agent/apply.ts), which
+ *      performs the same backup → pull → migrate → roll → health → rollback
+ *      as a hand-run `upgrade` and narrates it into the request's timeline.
+ *      The target's CLI renders the target's Compose file, so a release that
+ *      changes the stack needs no extra step. No code of the target runs
+ *      before its manifest verified and passed the checks above;
+ *   6. if that process ended without recording an end state, end the
+ *      request as failed with its output.
+ *
+ * The install's upgrade lock is held for the whole run, so a hand-run
+ * `upgrade` and the agent never roll at the same time.
+ */
+import { PLATFORM_UPDATE_AGENT_POLL_SECONDS } from "@caelo-cms/shared";
+import { assessUpgradeRequest } from "../upgrader-assess.js";
+import { recordUpdateEnd } from "../upgrader-job.js";
+import { eventReporter } from "../upgrader-reporter.js";
+/** One poll. Never throws; see the file comment for the sequence. */
+export async function runAgentOnce(deps) {
+    const { queue, log } = deps;
+    const problem = await deps.preflight().catch((e) => `preflight failed: ${errorText(e)}`);
+    try {
+        await queue.heartbeat({ agentVersion: deps.agentVersion, host: deps.host, problem });
+    }
+    catch (e) {
+        log({ severity: "ERROR", message: `could not check in with the database: ${errorText(e)}` });
+        return { exitCode: 1, requestId: null, status: null };
+    }
+    let claimed;
+    try {
+        claimed = await queue.claim(`agent@${deps.host}`.slice(0, 200));
+    }
+    catch (e) {
+        log({ severity: "ERROR", message: `could not read update requests: ${errorText(e)}` });
+        return { exitCode: 1, requestId: null, status: null };
+    }
+    if (!claimed)
+        return { exitCode: 0, requestId: null, status: null };
+    const request = claimed;
+    const r = eventReporter((phase, level, message) => queue.event(request.id, phase, level, message), log, request.id);
+    let release = null;
+    const unlock = () => {
+        try {
+            release?.();
+        }
+        catch (e) {
+            log({ severity: "WARNING", message: `could not release the upgrade lock: ${errorText(e)}` });
+        }
+        release = null;
+    };
+    const stopWith = async (status, codes, reason) => {
+        r.phase("finish");
+        r.error(reason);
+        await r.flush();
+        unlock();
+        const end = {
+            status,
+            reason,
+            codes,
+            pauseAutoUpdates: request.trigger === "auto" && (status === "failed" || status === "rolled_back"),
+        };
+        const recorded = await recordUpdateEnd(queue, request.id, end, log, deps.sleep);
+        const failed = status === "failed" || !recorded;
+        return { exitCode: failed ? 1 : 0, requestId: request.id, status };
+    };
+    try {
+        r.phase("start");
+        r.info(`The update agent on ${deps.host} (Caelo ${deps.agentVersion}) picked up the request to install Caelo ${request.targetVersion}.`);
+        if (problem) {
+            return await stopWith("failed", ["preflight"], `Nothing was changed: ${problem} Fix this on the server, then try again.`);
+        }
+        try {
+            release = deps.lock();
+        }
+        catch (e) {
+            return await stopWith("failed", ["state-locked"], `Nothing was changed: ${errorText(e)} Try again when it has finished.`);
+        }
+        r.phase("verify");
+        let installed;
+        try {
+            installed = deps.readInstalled();
+        }
+        catch (e) {
+            return await stopWith("failed", ["install-state"], `Nothing was changed: ${errorText(e)}`);
+        }
+        const manifest = await deps.fetchManifest(request.targetVersion);
+        const decision = assessUpgradeRequest({
+            request,
+            manifest,
+            installed: { version: installed?.version ?? null, infraContractVersion: null },
+            policy: request.policy,
+            now: deps.now(),
+            manualPath: "server",
+        });
+        if (decision.manifest) {
+            r.success(`Release information of ${decision.manifest.version} verified: signed by Caelo's release workflow.`);
+            await recordFacts(queue, request.id, decision.manifest);
+        }
+        r.phase("assess");
+        if (decision.kind === "stop") {
+            return await stopWith(decision.status, decision.codes, decision.reason);
+        }
+        for (const w of decision.warnings)
+            r.warn(w);
+        const m = decision.manifest;
+        const step = r.step(`Fetching the Caelo ${m.version} installer and verifying its npm provenance...`);
+        const cli = await deps.verifyTargetCli(m.version);
+        if (!cli.ok) {
+            step.failed(cli.error.message);
+            // A package that is not the release's is refused; a missing npm or a
+            // failed download is a failure to retry.
+            const refused = ["audit-signatures", "version", "provenance"].includes(cli.error.code);
+            return await stopWith(refused ? "refused" : "failed", [`cli-${cli.error.code}`], `Nothing was changed: the installer of Caelo ${m.version} ${refused ? "is not the one Caelo's release workflow published" : "could not be fetched"} (${cli.error.message}).`);
+        }
+        step.done(`The Caelo ${m.version} installer is signed and was built by Caelo's release workflow.`);
+        r.info(`${installed?.version} → ${m.version}: handing over to the Caelo ${m.version} installer on this server.`);
+        await r.flush();
+        const beat = setInterval(() => {
+            queue
+                .heartbeat({ agentVersion: deps.agentVersion, host: deps.host, problem: null })
+                .catch((e) => {
+                log({ severity: "WARNING", message: `could not check in: ${errorText(e)}` });
+            });
+        }, deps.heartbeatEveryMs ?? PLATFORM_UPDATE_AGENT_POLL_SECONDS * 1000);
+        let outcome;
+        try {
+            outcome = await deps.applyTarget({
+                requestId: request.id,
+                targetVersion: m.version,
+                trigger: request.trigger,
+                digests: { admin: m.digests.admin, gateway: m.digests.gateway },
+                cliPath: cli.cliPath,
+            });
+        }
+        finally {
+            clearInterval(beat);
+        }
+        unlock();
+        if (outcome.exitCode === 0)
+            return { exitCode: 0, requestId: request.id, status: null };
+        // The target's CLI ends the request itself; only if it could not (it
+        // never started, or crashed) is the request still running here.
+        const reason = `The Caelo ${m.version} installer stopped (exit ${outcome.exitCode}) before it recorded how the update ended. If the site misbehaves, check \`docker compose ps\` on the server.${outcome.output ? `\n${outcome.output}` : ""}`;
+        const end = {
+            status: "failed",
+            reason: reason.slice(0, 4000),
+            codes: ["apply"],
+            pauseAutoUpdates: request.trigger === "auto",
+        };
+        let ended = false;
+        try {
+            ended = await queue.finish(request.id, end);
+        }
+        catch (e) {
+            log({ severity: "ERROR", message: `could not end request ${request.id}: ${errorText(e)}` });
+            return { exitCode: 1, requestId: request.id, status: null };
+        }
+        if (!ended)
+            return { exitCode: 1, requestId: request.id, status: null };
+        r.phase("finish");
+        r.error(reason);
+        await r.flush();
+        return { exitCode: 1, requestId: request.id, status: "failed" };
+    }
+    catch (e) {
+        return await stopWith("failed", ["internal"], `The update agent stopped unexpectedly: ${errorText(e)}. If the site misbehaves, check \`docker compose ps\` on the server.`);
+    }
+}
+async function recordFacts(queue, requestId, m) {
+    await queue.record(requestId, {
+        manifestSecurity: m.security,
+        contractMigrations: m.migrations.contract,
+        adminDigest: m.digests.admin,
+        gatewayDigest: m.digests.gateway,
+    });
+}
+function errorText(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+//# sourceMappingURL=run.js.map

package/dist/agent/run.js.map

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

package/dist/agent/systemd.d.ts

@@ -0,0 +1,55 @@
+import type { HostRunner } from "../self-hosted-release.js";
+import { type AgentUnitSpec } 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 declare function currentAgentHost(runner: HostRunner): AgentHost;
+/**
+ * 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 declare function agentHostProblem(host: AgentHost): Promise<string | null>;
+/** `<unitDir>/<name>.service` + `.timer`. */
+export declare function agentUnitPaths(host: Pick<AgentHost, "unitDir">, name: string): {
+    service: string;
+    timer: string;
+};
+export type AgentUnitsResult = {
+    readonly ok: true;
+    readonly warnings: readonly string[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Write both units, reload, enable + start the timer, and make sure the
+ * user lingers. Idempotent: re-running rewrites the same files.
+ */
+export declare function installAgentUnits(spec: AgentUnitSpec, host: AgentHost): Promise<AgentUnitsResult>;
+/** The release the installed service runs, or null when it is not installed. */
+export declare function installedAgentVersion(host: AgentHost, name: string): string | null;
+/**
+ * Re-pin an installed agent to `spec.version` (after an update). Does
+ * nothing when the agent is not installed.
+ */
+export declare function repinAgentUnits(spec: AgentUnitSpec, host: AgentHost): Promise<AgentUnitsResult & {
+    readonly installed?: boolean;
+}>;
+/** Stop + disable the timer and delete both units. */
+export declare function uninstallAgentUnits(host: AgentHost, name: string): Promise<AgentUnitsResult>;
+/** `systemctl --user status` of both units (text for the terminal). */
+export declare function agentUnitStatus(host: AgentHost, name: string): Promise<string>;
+/** The argv that shows the agent's log (journald). */
+export declare function agentLogsArgv(name: string, opts: {
+    lines: number;
+    follow: boolean;
+}): string[];
+//# sourceMappingURL=systemd.d.ts.map

package/dist/agent/systemd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"systemd.d.ts","sourceRoot":"","sources":["../../src/agent/systemd.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EACL,KAAK,aAAa,EAInB,MAAM,YAAY,CAAC;AAEpB,gCAAgC;AAChC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CACpC;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAQ9D;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAS9E;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM;;;EAK5E;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AASnD;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,gBAAgB,CAAC,CAiB3B;AAYD,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQlF;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,gBAAgB,GAAG;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAoB9D;AAED,sDAAsD;AACtD,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,CAAC,CAU3B;AAED,uEAAuE;AACvE,wBAAsB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAWpF;AAED,sDAAsD;AACtD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,EAAE,CAW9F"}