@rackbops/ac-agent 2.0.0-alpha.48 → 2.0.0-alpha.49

package/README.md

@@ -811,6 +811,71 @@ free text (a `broken` row's last non-empty output line, `unauthenticated`'s
   `gh`'s `--version` answering just under 15 s and then `auth status` timing out at 15 s too --
   under the console's own 100 s edge-request budget behind Cloudflare Access.
 
+## Update: `POST /v1/update`, `GET /v1/update`
+
+The console can update a paired agent to a newer release (#659). Like `PUT /v1/grants`, both routes
+are bearer-gated, have no capability, and refuse a caller carrying `X-AC-Plugin` with 403: installing
+software is never something a grant could hand to a plugin.
+
+`POST /v1/update {"version": "<x.y.z[-pre]>"}`:
+
+1. **Refuses before any download:**
+   - 400 for a body without such a version.
+   - 409 `self-update is not supported on this platform` (anything but Windows and Linux).
+   - 409 `already running <v>`.
+   - 409 `a downgrade is not supported` (semver precedence).
+   - 409 `update in progress` while another request is still verifying in this process, or while
+     `update.json` reads `installing` and is under 10 minutes old.
+   - 409 `jobs running` while any `exec/claude` job runs. This is checked again after verification,
+     just before the hand-off.
+2. **Resolves exactly that version on the public npm registry** (`https://registry.npmjs.org`, a
+   constant, never configurable):
+   - The metadata must name `@rackbops/ac-agent` and that version.
+   - Its tarball URL must be the registry's own canonical one for it.
+   - Its integrity must be one sha512.
+3. **Downloads the tarball** (60 s timeout) and refuses it over 20 MB or unless its sha512 matches.
+   A declared `content-length` over the cap is refused before reading. Without one, the body is read
+   in full and then checked, so only the timeout bounds that read.
+4. **Reads only `package/dist/ac-agent.mjs` and `package/package.json` out of it,** in memory,
+   refusing an archive that unpacks past 100 MB. No path from the archive is ever written.
+   `package.json` must name the same package and version.
+5. **Stages the bundle** as `<stateDir>/update/<version>/ac-agent.mjs` and runs it with
+   `version --json`. It must report that version and this agent's API version (the host pinned the
+   API version at pairing).
+6. **Answers.** Any refusal in steps 2-5 is 422 `{ok:false, error}` with the staging directory
+   removed. Otherwise it writes `update.json` `installing` and answers 202 `{ok, from, target}`.
+7. **Hands off** to the staged bundle's own `install --update` (see **Install**) in a process that
+   outlives this one:
+   - On Windows, a detached child, which `Stop-ScheduledTask` doesn't reach.
+   - On Linux, a transient user unit (`systemd-run --user --collect`). The agent's own unit would kill
+     a plain child when the install stops it.
+   - Either way the hand-off gets the agent's config and state dirs, and on Linux the agent's `PATH`,
+     because the install bakes `PATH` into the unit it writes.
+
+   That install restarts the agent, rolls back if the new version doesn't come up, and writes the
+   final `update.json`. A hand-off that can't be launched is recorded as `failed`:
+   - on Windows, a spawn error;
+   - on Linux, `systemd-run` missing, exiting non-zero (no user bus, for example) or timing out after
+     30 s. It returns once the transient unit has started.
+
+   If the launched install dies before writing anything, the record stays `installing` and reads as
+   `unknown` after 10 minutes. After that age a new request is accepted again, so an install genuinely
+   still running past 10 minutes could have its staging directory cleared under it. The install
+   normally takes a minute or two, so the window is generous, but not a guarantee.
+
+A fault that is not a refusal (an unexpected error) answers 500, with the staging directory removed
+and nothing recorded.
+
+`GET /v1/update` answers:
+- `{ok, status: "idle"}` with no record;
+- the record from `update.json`;
+- `{ok, status: "unknown", record}` for an `installing` record over 10 minutes old, or whose `at` is
+  unreadable. Record writes are
+  best-effort, so an install can finish without its last write landing.
+
+Every refusal, the verified hand-off, and a failed hand-off are logged as
+`update: <from> -> <target> <outcome>`.
+
 ## Security model
 
 - **HTTPS only**, with a self-signed certificate generated once at install (RSA 2048, SHA-256,

package/dist/ac-agent.mjs

@@ -17,7 +17,7 @@ import require$$0$1 from 'node:events';
 import require$$0$4 from 'node:diagnostics_channel';
 import require$$0$5 from 'node:buffer';
 import require$$4 from 'node:tls';
-import require$$0$6 from 'node:zlib';
+import require$$0$6, { gunzipSync } from 'node:zlib';
 import require$$5$1 from 'node:perf_hooks';
 import require$$8 from 'node:util/types';
 import require$$2$1 from 'node:worker_threads';
@@ -47,7 +47,7 @@ function _mergeNamespaces(n, m) {
 }
 
 var name = "@rackbops/ac-agent";
-var version = "2.0.0-alpha.48";
+var version = "2.0.0-alpha.49";
 var type = "module";
 var description = "The per-machine host agent (installed with npx @rackbops/ac-agent): an HTTPS health server plus install/status/uninstall for a Windows logon task or a systemd user unit.";
 var bin = {
@@ -5441,6 +5441,37 @@ function createApp(deps) {
         deps.logEvent(`preflight: ${okCount} ok, ${notOkCount} not ok (${perRow}) searchPath=${report.searchPath}`);
         return c.json({ ok: true, ...report });
     });
+    // #659: the console's update control plane -- bearer-gated by the middleware above, no capability,
+    // refuses a plugin-shaped caller exactly like PUT /v1/grants: installing software is never a verb a
+    // grant could hand to a plugin.
+    const updater = deps.update;
+    if (updater !== undefined) {
+        app.post("/v1/update", async (c) => {
+            if (c.req.header("X-AC-Plugin") !== undefined) {
+                return c.json({ ok: false, error: "updates are started by the console, not by a plugin" }, 403);
+            }
+            let body;
+            try {
+                body = await c.req.json();
+            }
+            catch {
+                body = undefined;
+            }
+            const answer = await updater.request(body);
+            const after = answer.after;
+            if (after !== undefined) {
+                // After the answer is on its way: the install this starts stops this process within seconds.
+                setTimeout(() => void after(), 0);
+            }
+            return c.json(answer.body, answer.status);
+        });
+        app.get("/v1/update", (c) => {
+            if (c.req.header("X-AC-Plugin") !== undefined) {
+                return c.json({ ok: false, error: "update status is the console's, not a plugin's" }, 403);
+            }
+            return c.json(updater.current());
+        });
+    }
     mountVerbs(app, deps.verbs, { grants: deps.grants, machine: deps.machine });
     app.notFound((c) => c.json({ error: "no such verb" }, 404));
     return app;
@@ -22357,6 +22388,21 @@ async function uninstall(deps, options) {
     }
 }
 
+var index$3 = /*#__PURE__*/Object.freeze({
+  __proto__: null,
+  detectVirtualization: detectVirtualization,
+  installService: installService,
+  isAgentRunning: isAgentRunning,
+  killRunningAgent: killRunningAgent,
+  pair: pair,
+  readUpdateRecord: readUpdateRecord,
+  status: status,
+  stopService: stopService,
+  uninstall: uninstall,
+  updateRecordPath: updateRecordPath,
+  writeUpdateRecord: writeUpdateRecord
+});
+
 /**
  * Linux install (E4 §5 decision 7): `~/.config/systemd/user/ac-agent.service`, a `Type=simple`
  * unit restarting on failure, `PATH` baked at install time rather than read live at start (a
@@ -23141,7 +23187,7 @@ async function realServe(overrides = {}) {
     const crypto = await import('node:crypto');
     const { resolveDirs } = await Promise.resolve().then(function () { return paths; });
     const { ensureCert, lanIPv4Candidates } = await Promise.resolve().then(function () { return cert; });
-    const { acquire, release } = await Promise.resolve().then(function () { return lock; });
+    const { acquire, release: release$1 } = await Promise.resolve().then(function () { return lock; });
     const { openLog } = await Promise.resolve().then(function () { return log; });
     const { createRun, createSpawn } = await Promise.resolve().then(function () { return run$1; });
     const { createVerbRegistry } = await Promise.resolve().then(function () { return registry$2; });
@@ -23359,8 +23405,10 @@ async function realServe(overrides = {}) {
         run,
     });
     registerScanVerbs(registry$3, scans, { logEvent: (message) => log$1.write(message) });
+    // Hoisted (#659): the update route refuses while any job is running.
+    const jobs = createJobRegistry();
     registerClaudeVerbs(registry$3, {
-        jobs: createJobRegistry(),
+        jobs,
         resolveRepo: (name) => resolveRepo(loaded.config.reposRoot, name, repoFs),
         which: which$1,
     });
@@ -23379,6 +23427,54 @@ async function realServe(overrides = {}) {
         onInconclusive: () => log$1.write("claude desktop: detection inconclusive (a command timed out, could not start, threw, or overran its deadline); the held answer, if any, is unchanged"),
     });
     const stopClaudeDesktopWatch = claudeDesktopWatch.start();
+    // #659 PR 2: POST/GET /v1/update. The registry is the public npm one, never configurable; the
+    // hand-off starts the verified staged bundle's own `install --update`, which restarts this agent.
+    const { createUpdater, createHandOff, selfUpdateSupported } = await Promise.resolve().then(function () { return updater; });
+    const { NPM_REGISTRY } = await Promise.resolve().then(function () { return release; });
+    const { readUpdateRecord, writeUpdateRecord } = await Promise.resolve().then(function () { return index$3; });
+    const recordDeps = {
+        stateDir: dirs.stateDir,
+        readFile,
+        writeFile: (p, content) => fs.writeFileSync(p, content),
+        renameFile: (from, to) => fs.renameSync(from, to),
+        print: (line) => log$1.write(line),
+    };
+    const updater$1 = createUpdater({
+        version: packageJson.version,
+        apiVersion: AGENT_API_VERSION,
+        stateDir: dirs.stateDir,
+        configDir: dirs.configDir,
+        registry: NPM_REGISTRY,
+        fetch: (url, init) => fetch(url, init),
+        readStagedVersion: async (staged) => {
+            const result = await run(process.execPath, [staged, "version", "--json"], {
+                timeoutMs: 15_000,
+            });
+            if (result.code !== 0)
+                throw new Error(`exit ${result.code}: ${result.stderr.trim()}`);
+            return result.stdout;
+        },
+        writeFile: (p, content) => fs.writeFileSync(p, content),
+        mkdir: (p) => fs.mkdirSync(p, { recursive: true }),
+        removeDir: (p) => fs.rmSync(p, { recursive: true, force: true }),
+        readRecord: () => readUpdateRecord(recordDeps),
+        writeRecord: (record) => writeUpdateRecord(recordDeps, record),
+        handOff: createHandOff({
+            platform: process.platform,
+            execPath: process.execPath,
+            configDir: dirs.configDir,
+            stateDir: dirs.stateDir,
+            path: process.env.PATH ?? "",
+            now: () => new Date(),
+            spawn: createSpawn(),
+            run,
+            env: process.env,
+        }),
+        selfUpdateSupported: selfUpdateSupported(process.platform),
+        runningJobs: () => jobs.runningCount(),
+        now: () => new Date(),
+        logEvent: (message) => log$1.write(message),
+    });
     const app = createApp({
         version: packageJson.version,
         apiVersion: AGENT_API_VERSION,
@@ -23399,6 +23495,7 @@ async function realServe(overrides = {}) {
         grants: grants$1,
         preflight: () => runPreflight(preflightDeps),
         claudeDesktop: claudeDesktopWatch.current,
+        update: updater$1,
     });
     const running = await startServer({
         app,
@@ -23411,7 +23508,7 @@ async function realServe(overrides = {}) {
     const shutdown = () => {
         stopClaudeDesktopWatch();
         void running.close().then(() => {
-            release(dirs.stateDir, (p) => {
+            release$1(dirs.stateDir, (p) => {
                 try {
                     fs.unlinkSync(p);
                 }
@@ -64305,14 +64402,14 @@ function acquire(stateDir, deps) {
     }
     return { ok: false, reason: `already running (pid ${existingPid})` };
 }
-function release(stateDir, unlink) {
+function release$1(stateDir, unlink) {
     unlink(path.join(stateDir, "agent.pid"));
 }
 
 var lock = /*#__PURE__*/Object.freeze({
   __proto__: null,
   acquire: acquire,
-  release: release
+  release: release$1
 });
 
 /** `agent.log`, rotated to `agent.log.1` past 1 MiB on open -- checked once at `serve` startup,
@@ -75146,4 +75243,423 @@ var tunnel = /*#__PURE__*/Object.freeze({
   registerTunnelVerb: registerTunnelVerb
 });
 
+/**
+ * #659 PR 2: where an update comes from and what is allowed. The agent installs only an exact
+ * published version of `@rackbops/ac-agent` from the public npm registry -- never a URL, a tarball
+ * or a registry the caller names. The registry base is a constant here; the only other value
+ * `createUpdater` ever receives is a test's loopback stub, passed through its own wiring.
+ */
+const NPM_REGISTRY = "https://registry.npmjs.org";
+const AGENT_PACKAGE = "@rackbops/ac-agent";
+/** `major.minor.patch` with an optional prerelease -- the only shape a version string may take
+ *  anywhere in the update path (and the host's own copy, #659 PR 3). */
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?$/;
+/** A refusal the route answers with its message: the update is not possible, and nothing was
+ *  installed. Anything else thrown is a fault. */
+class UpdateRefusal extends Error {
+}
+function tarballUrlFor(registry, version) {
+    return `${registry}/${AGENT_PACKAGE}/-/ac-agent-${version}.tgz`;
+}
+const INTEGRITY = /^sha512-[A-Za-z0-9+/]+={0,2}$/;
+/** The registry's metadata for exactly `version`, checked: the right package and version, a tarball
+ *  at the registry's own canonical URL for it, and a single sha512 integrity. */
+async function resolveRelease(version, fetchImpl, registry, timeoutMs = 15_000) {
+    if (!VERSION_PATTERN.test(version))
+        throw new UpdateRefusal(`not a version: ${version}`);
+    const url = `${registry}/${AGENT_PACKAGE.replace("/", "%2f")}/${version}`;
+    let res;
+    try {
+        res = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) });
+    }
+    catch (err) {
+        throw new UpdateRefusal(`registry unreachable: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (res.status === 404)
+        throw new UpdateRefusal(`${version} is not published`);
+    if (!res.ok)
+        throw new UpdateRefusal(`registry answered ${res.status} for ${version}`);
+    const meta = (await res.json());
+    if (meta.name !== AGENT_PACKAGE || meta.version !== version) {
+        throw new UpdateRefusal(`registry metadata is not ${AGENT_PACKAGE}@${version}`);
+    }
+    const expectedTarball = tarballUrlFor(registry, version);
+    if (meta.dist?.tarball !== expectedTarball) {
+        throw new UpdateRefusal(`unexpected tarball URL for ${version}`);
+    }
+    const integrity = meta.dist?.integrity;
+    if (typeof integrity !== "string" || !INTEGRITY.test(integrity)) {
+        throw new UpdateRefusal(`no single sha512 integrity for ${version}`);
+    }
+    return { version, tarballUrl: expectedTarball, integrity };
+}
+/** Semver precedence for `VERSION_PATTERN` strings: numeric core, then a release above any of its
+ *  prereleases, then prerelease identifiers left to right (numeric < alphanumeric, numerics by
+ *  value). Negative when `a` is older. */
+function compareVersions(a, b) {
+    const [coreA = "", preA] = splitVersion(a);
+    const [coreB = "", preB] = splitVersion(b);
+    const numsA = coreA.split(".").map(Number);
+    const numsB = coreB.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const diff = (numsA[i] ?? 0) - (numsB[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    if (preA === undefined || preB === undefined) {
+        return preA === preB ? 0 : preA === undefined ? 1 : -1;
+    }
+    const idsA = preA.split(".");
+    const idsB = preB.split(".");
+    for (let i = 0; i < Math.max(idsA.length, idsB.length); i++) {
+        const x = idsA[i];
+        const y = idsB[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const xNum = /^\d+$/.test(x);
+        const yNum = /^\d+$/.test(y);
+        if (xNum && yNum) {
+            const diff = Number(x) - Number(y);
+            if (diff !== 0)
+                return diff;
+        }
+        else if (xNum !== yNum) {
+            return xNum ? -1 : 1;
+        }
+        else if (x !== y) {
+            return x < y ? -1 : 1;
+        }
+    }
+    return 0;
+}
+function splitVersion(v) {
+    const dash = v.indexOf("-");
+    return dash === -1 ? [v, undefined] : [v.slice(0, dash), v.slice(dash + 1)];
+}
+
+var release = /*#__PURE__*/Object.freeze({
+  __proto__: null,
+  AGENT_PACKAGE: AGENT_PACKAGE,
+  NPM_REGISTRY: NPM_REGISTRY,
+  UpdateRefusal: UpdateRefusal,
+  VERSION_PATTERN: VERSION_PATTERN,
+  compareVersions: compareVersions,
+  resolveRelease: resolveRelease,
+  tarballUrlFor: tarballUrlFor
+});
+
+/** The published tarball is ~0.5 MB; anything near this is not our package. */
+const MAX_TARBALL_BYTES = 20 * 1024 * 1024;
+/** Downloads the release's tarball and checks its sha512 against the registry's `integrity` before
+ *  anything else reads it (#659). A mismatch is a refusal; nothing is written. */
+async function downloadVerified(release, fetchImpl, timeoutMs = 60_000) {
+    let res;
+    try {
+        res = await fetchImpl(release.tarballUrl, { signal: AbortSignal.timeout(timeoutMs) });
+    }
+    catch (err) {
+        throw new UpdateRefusal(`tarball download failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!res.ok)
+        throw new UpdateRefusal(`tarball download answered ${res.status}`);
+    const declared = Number(res.headers.get("content-length") ?? "0");
+    if (declared > MAX_TARBALL_BYTES)
+        throw new UpdateRefusal("tarball is too large");
+    let bytes;
+    try {
+        bytes = Buffer.from(await res.arrayBuffer());
+    }
+    catch (err) {
+        // The body read can outlast the timeout (AbortError) or drop: a refusal, not a fault (#659 PR 2
+        // review round 2).
+        throw new UpdateRefusal(`tarball download failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (bytes.length > MAX_TARBALL_BYTES)
+        throw new UpdateRefusal("tarball is too large");
+    const expected = Buffer.from(release.integrity.slice("sha512-".length), "base64");
+    const actual = createHash("sha512").update(bytes).digest();
+    if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) {
+        throw new UpdateRefusal(`tarball sha512 does not match the registry for ${release.version}`);
+    }
+    return bytes;
+}
+/** The unpacked package is ~2 MB; a gzip bomb stops here (#659 PR 2 review round 1). */
+const MAX_UNPACKED_BYTES = 100 * 1024 * 1024;
+const BUNDLE_ENTRY = "package/dist/ac-agent.mjs";
+const MANIFEST_ENTRY = "package/package.json";
+/** Reads the two entries the update needs out of a verified `.tgz` -- the bundle and
+ *  `package.json` -- by walking the ustar headers in memory. No path from the archive is ever
+ *  written anywhere: only these two exact names are taken, everything else is skipped. */
+function extractBundle(tgz, version, maxUnpackedBytes = MAX_UNPACKED_BYTES) {
+    let tar;
+    try {
+        tar = gunzipSync(tgz, { maxOutputLength: maxUnpackedBytes });
+    }
+    catch (err) {
+        if (err?.code === "ERR_BUFFER_TOO_LARGE") {
+            throw new UpdateRefusal("tarball unpacks too large");
+        }
+        throw new UpdateRefusal("tarball is not gzip");
+    }
+    const found = new Map();
+    let offset = 0;
+    while (offset + 512 <= tar.length) {
+        const header = tar.subarray(offset, offset + 512);
+        if (header.every((byte) => byte === 0))
+            break;
+        const name = cString(header.subarray(0, 100));
+        const prefix = cString(header.subarray(345, 500));
+        const size = Number.parseInt(cString(header.subarray(124, 136)).trim() || "0", 8);
+        const type = String.fromCharCode(header[156] ?? 0);
+        if (!Number.isFinite(size) || size < 0)
+            throw new UpdateRefusal("tarball header is malformed");
+        const full = prefix ? `${prefix}/${name}` : name;
+        const bodyStart = offset + 512;
+        if ((type === "0" || type === "\0") && (full === BUNDLE_ENTRY || full === MANIFEST_ENTRY)) {
+            found.set(full, Buffer.from(tar.subarray(bodyStart, bodyStart + size)));
+        }
+        offset = bodyStart + Math.ceil(size / 512) * 512;
+    }
+    const bundle = found.get(BUNDLE_ENTRY);
+    const manifestBytes = found.get(MANIFEST_ENTRY);
+    if (bundle === undefined || manifestBytes === undefined) {
+        throw new UpdateRefusal("tarball has no agent bundle");
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestBytes.toString("utf8"));
+    }
+    catch {
+        throw new UpdateRefusal("tarball package.json is unreadable");
+    }
+    if (manifest.name !== AGENT_PACKAGE || manifest.version !== version) {
+        throw new UpdateRefusal(`tarball is not ${AGENT_PACKAGE}@${version}`);
+    }
+    return bundle;
+}
+function cString(field) {
+    const end = field.indexOf(0);
+    return field.subarray(0, end === -1 ? field.length : end).toString("utf8");
+}
+
+/**
+ * #659 PR 2: the agent's side of an update. `POST /v1/update { version }` resolves that exact
+ * version on npm, downloads and verifies it, stages the bundle, checks the staged bundle's own
+ * agent API version, then hands off to the staged bundle's `install --update` in a process that
+ * outlives this one (PR 1's install restarts the agent, rolls back on failure, and writes
+ * `update.json`). This module never stops or restarts anything itself, and nothing in this process
+ * waits for the install to finish (on Linux it waits only for `systemd-run` to start the unit).
+ */
+/** An `installing` record older than this is treated as unknown, not in progress: record writes are
+ *  best-effort (#659 PR 1), so an install can finish without its last write landing. */
+const STALE_INSTALLING_MS = 10 * 60 * 1000;
+function refuse(status, error) {
+    return { status, body: { ok: false, error } };
+}
+function isStaleInstalling(record, now) {
+    const at = Date.parse(record.at);
+    return (record.status === "installing" && (Number.isNaN(at) || now.getTime() - at > STALE_INSTALLING_MS));
+}
+function createUpdater(deps) {
+    // One request at a time in this process (#659 PR 2 review round 1): the in-progress check below
+    // reads update.json, which is only written once verification finishes -- up to ~90 s later -- so
+    // two overlapping POSTs (a double click, a retry) would otherwise both pass it, clobber one staging
+    // directory and start two installs. Set synchronously, before the first await.
+    let inFlight = null;
+    return {
+        current() {
+            const record = deps.readRecord();
+            if (record === null)
+                return { ok: true, status: "idle" };
+            if (isStaleInstalling(record, deps.now()))
+                return { ok: true, status: "unknown", record };
+            return { ok: true, ...record };
+        },
+        async request(body) {
+            const target = typeof body === "object" && body !== null
+                ? body.version
+                : undefined;
+            const refuseLogged = (status, error) => {
+                // `target` is the caller's, unvalidated on the 400 path: quoted and cut, so it can't forge
+                // log lines (#659 PR 2 review round 2).
+                // Never String(target): an object whose `toString` isn't callable throws there (round 3).
+                const shown = typeof target === "string" && VERSION_PATTERN.test(target)
+                    ? target
+                    : JSON.stringify(target ?? null).slice(0, 80);
+                deps.logEvent(`update: ${deps.version} -> ${shown} refused (${error})`);
+                return refuse(status, error);
+            };
+            if (typeof target !== "string" || !VERSION_PATTERN.test(target)) {
+                return refuseLogged(400, "body must be { version: <x.y.z[-pre]> }");
+            }
+            if (!deps.selfUpdateSupported) {
+                return refuseLogged(409, "self-update is not supported on this platform");
+            }
+            if (target === deps.version)
+                return refuseLogged(409, `already running ${target}`);
+            if (compareVersions(target, deps.version) < 0) {
+                return refuseLogged(409, `a downgrade is not supported (running ${deps.version})`);
+            }
+            if (inFlight !== null)
+                return refuseLogged(409, `update in progress (${inFlight})`);
+            if (deps.runningJobs() > 0) {
+                return refuseLogged(409, "jobs running; try again when they finish");
+            }
+            const record = deps.readRecord();
+            if (record !== null &&
+                record.status === "installing" &&
+                !isStaleInstalling(record, deps.now())) {
+                return refuseLogged(409, `update in progress (${record.target})`);
+            }
+            inFlight = target;
+            try {
+                return await verifyAndStage(target, refuseLogged);
+            }
+            finally {
+                inFlight = null;
+            }
+        },
+    };
+    async function verifyAndStage(target, refuseLogged) {
+        // The whole update/ directory, not just this version's: an earlier staged bundle has either been
+        // installed (copied into bin/) or refused, so nothing in it is ever needed again.
+        const updateRoot = path.join(deps.stateDir, "update");
+        const stageDir = path.join(updateRoot, target);
+        const stagedPath = path.join(stageDir, "ac-agent.mjs");
+        try {
+            const release = await resolveRelease(target, deps.fetch, deps.registry);
+            const tgz = await downloadVerified(release, deps.fetch);
+            const bundle = extractBundle(tgz, target);
+            deps.removeDir(updateRoot);
+            deps.mkdir(stageDir);
+            deps.writeFile(stagedPath, bundle);
+            await checkStaged(deps, stagedPath, target);
+        }
+        catch (err) {
+            deps.removeDir(stageDir);
+            if (err instanceof UpdateRefusal)
+                return refuseLogged(422, err.message);
+            throw err;
+        }
+        // A job may have started during the download (#659 PR 2 review round 1): the install would
+        // restart the agent under it.
+        if (deps.runningJobs() > 0) {
+            deps.removeDir(stageDir);
+            return refuseLogged(409, "jobs running; try again when they finish");
+        }
+        deps.writeRecord({
+            status: "installing",
+            from: deps.version,
+            target,
+            at: deps.now().toISOString(),
+        });
+        deps.logEvent(`update: ${deps.version} -> ${target} verified, handing off to install`);
+        return {
+            status: 202,
+            body: { ok: true, from: deps.version, target },
+            after: async () => {
+                try {
+                    await deps.handOff(stagedPath);
+                }
+                catch (err) {
+                    const message = `hand-off failed: ${err instanceof Error ? err.message : String(err)}`;
+                    deps.writeRecord({
+                        status: "failed",
+                        from: deps.version,
+                        target,
+                        at: deps.now().toISOString(),
+                        message,
+                    });
+                    deps.logEvent(`update: ${deps.version} -> ${target} ${message}`);
+                }
+            },
+        };
+    }
+}
+/** The staged bundle must report exactly the target version and this agent's API version -- the
+ *  host pinned the API version at pairing, and a mismatch is a 409 on every call after. */
+async function checkStaged(deps, stagedPath, target) {
+    let reported;
+    try {
+        reported = JSON.parse(await deps.readStagedVersion(stagedPath));
+    }
+    catch (err) {
+        throw new UpdateRefusal(`the staged bundle did not report its version: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (reported.version !== target) {
+        throw new UpdateRefusal(`the staged bundle reports ${String(reported.version)}, not ${target}`);
+    }
+    if (reported.apiVersion !== deps.apiVersion) {
+        throw new UpdateRefusal(`the staged bundle speaks agent API ${String(reported.apiVersion)}, this agent ${deps.apiVersion}`);
+    }
+}
+function selfUpdateSupported(platform) {
+    return platform === "win32" || platform === "linux";
+}
+/** The command that runs the staged bundle's `install --update` so it survives this agent being
+ *  stopped. Windows: a detached child (`Stop-ScheduledTask` does not reach it, #238). Linux: its own
+ *  transient user unit -- the agent's unit uses systemd's default `KillMode=control-group`, which
+ *  would kill a plain child along with the agent. */
+function handOffCommand(opts, stagedPath) {
+    const install = [stagedPath, "install", "--update"];
+    if (opts.platform === "win32")
+        return { cmd: opts.execPath, args: install };
+    if (opts.platform === "linux") {
+        return {
+            cmd: "systemd-run",
+            args: [
+                "--user",
+                "--collect",
+                "--quiet",
+                `--unit=ac-agent-update-${opts.now().getTime()}`,
+                `--setenv=AC_AGENT_CONFIG_DIR=${opts.configDir}`,
+                `--setenv=AC_AGENT_STATE_DIR=${opts.stateDir}`,
+                `--setenv=PATH=${opts.path}`,
+                opts.execPath,
+                ...install,
+            ],
+        };
+    }
+    return null;
+}
+function createHandOff(opts) {
+    return async (stagedPath) => {
+        const command = handOffCommand(opts, stagedPath);
+        if (command === null)
+            throw new Error(`self-update is not supported on ${opts.platform}`);
+        if (opts.platform === "linux") {
+            // The environment the install needs travels as --setenv arguments; the unit never inherits
+            // this process's.
+            const result = await opts.run(command.cmd, command.args, { timeoutMs: 30_000 });
+            if (result.code !== 0) {
+                const why = result.timedOut ? "timed out" : `exited ${result.code}`;
+                throw new Error(`systemd-run ${why}: ${result.stderr.trim().slice(0, 300)}`);
+            }
+            return;
+        }
+        await opts.spawn(command.cmd, command.args, {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+            env: {
+                ...opts.env,
+                AC_AGENT_CONFIG_DIR: opts.configDir,
+                AC_AGENT_STATE_DIR: opts.stateDir,
+            },
+        });
+    };
+}
+
+var updater = /*#__PURE__*/Object.freeze({
+  __proto__: null,
+  STALE_INSTALLING_MS: STALE_INSTALLING_MS,
+  createHandOff: createHandOff,
+  createUpdater: createUpdater,
+  handOffCommand: handOffCommand,
+  isStaleInstalling: isStaleInstalling,
+  selfUpdateSupported: selfUpdateSupported
+});
+
 export { AGENT_API_VERSION, buildRepoFs, buildWhichFs, dispatch, healthResultFrom, isEntryPoint, main, realExists };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rackbops/ac-agent",
-  "version": "2.0.0-alpha.48",
+  "version": "2.0.0-alpha.49",
   "private": false,
   "type": "module",
   "description": "The per-machine host agent (installed with npx @rackbops/ac-agent): an HTTPS health server plus install/status/uninstall for a Windows logon task or a systemd user unit.",