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

package/README.md

@@ -106,10 +106,58 @@ against the new bundle, `install` stops the old process and starts it again thro
 `stop`/`start` machinery the `ac-agent stop`/`ac-agent start` commands use, then confirms the new
 process is actually answering (a health check, retried for a few seconds — the OS command that
 launches a process can report success before that process has actually started listening) before
-printing `restarted: now serving <version>`. If the restart fails outright, or the health check
-never comes back healthy, the install is still reported as a success — the printed line is
-`restart failed: <reason>; run ac-agent stop && ac-agent start`, and that manual sequence is the
-fallback. A fresh install, with nothing running yet, prints neither line.
+printing `restarted: now serving <version>`. Only a health answer reporting the **new** version
+counts (#659), so the old process still answering on the port is not mistaken for the new one.
+
+Before copying the new bundle in over a running agent, `install` keeps the one it replaces as
+`bin/ac-agent.prev.mjs` in the state dir (#659; one backup, overwritten by the next install). If the
+new bundle never answers health at its own version, `install` rolls back:
+1. It stops the task/unit again. On Windows this ends `launch.js`'s retry loop, so it can't rerun the
+   broken bundle in the middle of the restore.
+2. It restores `ac-agent.prev.mjs` and starts it.
+3. It confirms the previous version answers, then prints
+   `rolled back: now serving <previous version> (<reason>)`. The previous version is read from the
+   running agent's own health answer just before it is stopped. If that read got no version (no
+   `cert.pem` to read it with, no answer, an error answer, or one without a version), any healthy
+   answer is accepted, and the line says
+   `now serving the previous bundle`.
+
+Whenever a rollback is possible, the restart confirmation waits up to a minute instead of a few
+seconds, because a false failure would undo a good release (the Windows cold start has never been
+timed). This applies to a plain install too, such as Tooling's `Update-AcAgent.ps1`. A new bundle that
+never comes up therefore takes about two minutes to report (a minute waiting for it, up to another
+confirming the rollback; a hung connection adds to each attempt). If the install fails before the
+restart (registering the task/unit, the certificate) and a backup was made, the running agent's bundle
+is copied back onto the disk; the error is reported as before.
+
+The install then **fails** (exit 1), because it did not take. If the rollback fails too, it prints
+`rollback failed: ...`, leaves both bundles in place, and also exits 1; `ac-agent start` is the
+fallback.
+
+When there was no bundle to go back to, a restart that fails outright still reports the install as a
+success, with `restart failed: <reason>; run ac-agent stop && ac-agent start`, and that manual
+sequence is the fallback. A fresh install, with nothing running yet, prints neither line.
+
+`install --update` is what the agent's own update route launches; it isn't meant to be run by hand.
+It differs from a plain install in two ways:
+- Its restart confirmation (when an agent is running to restart) is always the minute-long one,
+  even with no backup to roll back to.
+- It records each step in `update.json` in the state dir:
+  `{status: "installing" | "ok" | "rolled-back" | "failed", from, target, at, message?}`, where
+  `from` is null when the previous version could not be read.
+  - Once `installing` is written, the outcome is recorded as `ok`, `rolled-back` or `failed`. That
+    covers a failure before the restart, and no agent running afterwards.
+  - A failure before `installing` is written (reading the config, the backup copy) leaves the
+    previous record as it was.
+  - It writes a temp file and renames it over, so a reader never sees a partial record.
+  - A write that fails (for example a locked file) prints a `warning: could not record update
+    status ...` line and never changes the install's outcome. The record then still shows the last
+    write that landed, which may be `installing`, so a reader should treat an old `installing` as
+    unknown.
+
+A plain install never writes `update.json`. `ac-agent version --json` prints
+`{"version", "apiVersion"}`, which is how a staged bundle's agent API version is read without starting
+it.
 
 ### The firewall step
 
@@ -223,7 +271,8 @@ when this session's own AppData writes to the resolved config/state dirs are vir
 packaged app (see **Run install from a normal shell** above), which also prints a `warning: this
 session's AppData is virtualized (<packageFamily>); the logon task cannot see <stateDir> -- see
 README, Install` line to stderr. `serve` logs the same warning line once at startup, in the same
-circumstance, without refusing to start.
+circumstance, without refusing to start. `update` (#659) is the last `install --update`'s record from
+`update.json`, or `null` when there is none or it is unreadable.
 
 ## Pair
 
@@ -275,7 +324,7 @@ or `systemctl --user stop/start`) without touching the registration itself.
 | | Windows | Linux |
 |---|---|---|
 | Config (`agent.toml`) | `%APPDATA%\ac-agent\` | `~/.config/ac-agent/` |
-| State (cert, key, token hash, grants, log, pid, the installed bundle copy) | `%LOCALAPPDATA%\ac-agent\` | `~/.local/state/ac-agent/` |
+| State (cert, key, token hash, grants, log, pid, the installed bundle copy and its one backup, `update.json`) | `%LOCALAPPDATA%\ac-agent\` | `~/.local/state/ac-agent/` |
 
 Both are overridable with `AC_AGENT_CONFIG_DIR` / `AC_AGENT_STATE_DIR` — **absolute paths only**; a
 relative override throws, naming the value. `install` resolves these once, in its own process, and
@@ -762,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.47";
+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;
@@ -21945,35 +21976,66 @@ function detectVirtualization(deps) {
 function bundleTargetPath(stateDir) {
     return path.join(stateDir, "bin", "ac-agent.mjs");
 }
-// #277 review round 1 (correctness lens): `deps.platform.start()`/`.stop()` are backed by
-// `runPowerShell`/`runCommand` (cli.ts), which resolve unconditionally on the child process's
-// `close` event and never inspect its exit code -- a `Start-ScheduledTask`/`systemctl start` that
-// runs but fails (bad permissions, a corrupted registration, ...) would otherwise be
-// indistinguishable here from one that actually worked, so `installService` could print `restarted:
-// now serving <version>` while nothing is actually listening. `confirmHealthy` below closes that gap
-// by requiring a real, successful `/v1/health` response -- not just "the launch command exited" --
-// before the restart is reported as a success. The new process is several process-creation hops away
-// on Windows (Start-ScheduledTask -> wscript.exe -> JScript -> node), so this retries briefly rather
-// than judging on a single immediate check.
-//
-// #277 review round 2: this budget (worst case: 7 delays x 400ms = 2.8s, plus the fetch attempts
-// themselves) is a deliberately generous, but UNVERIFIED-ON-WINDOWS, guess -- live verification for
-// this fix only covered Linux (nitro, over ssh); no live Windows box was installed against (Melody's
-// install refuses under MSIX AppData virtualization regardless, #263; MILE/SHIORI are roshne's own
-// boxes, out of scope here). A real Start-ScheduledTask -> wscript.exe -> JScript -> node cold start
-// that took longer than this window would report a false "restart failed" over an agent that's
-// actually fine a moment later -- a safe failure direction (never a false "restarted"), but still
-// worth a live Windows timing check before trusting this number long-term.
-const HEALTH_CHECK_ATTEMPTS = 8;
-const HEALTH_CHECK_DELAY_MS = 400;
-async function confirmHealthy(deps, port, certPem, expectedFingerprint) {
-    for (let attempt = 0; attempt < HEALTH_CHECK_ATTEMPTS; attempt++) {
+/** The one previous bundle `install` keeps while it restarts onto a new one (#659): restored when
+ *  the new bundle never answers health at its own version. Overwritten by the next install. */
+function bundleBackupPath(stateDir) {
+    return path.join(stateDir, "bin", "ac-agent.prev.mjs");
+}
+function updateRecordPath(stateDir) {
+    return path.join(stateDir, "update.json");
+}
+/** Best-effort: the record reports an install's outcome, it never decides it. A write that fails
+ *  (on Windows, `renameSync` over a file a reader holds open can throw EPERM/EBUSY; a full disk) is
+ *  printed and swallowed -- left to throw inside the restart sequence, it would roll back a release
+ *  that came up healthy (#659 review round 1). */
+function writeUpdateRecord(deps, record) {
+    const target = updateRecordPath(deps.stateDir);
+    const tmp = `${target}.tmp`;
+    try {
+        deps.writeFile(tmp, `${JSON.stringify(record, null, 2)}\n`);
+        deps.renameFile(tmp, target);
+    }
+    catch (err) {
+        deps.print(`warning: could not record update status ${record.status} in ${target}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** `update.json` parsed, or null when absent or unreadable -- `status` reports it as-is. */
+function readUpdateRecord(deps) {
+    const text = deps.readFile(updateRecordPath(deps.stateDir));
+    if (text === null)
+        return null;
+    try {
+        const value = JSON.parse(text);
+        return typeof value === "object" && value !== null && typeof value.status === "string"
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+const HEALTH_BUDGET = { attempts: 8, delayMs: 400 };
+/** `install --update` (#659): a false failure here rolls back a good release, so the update path
+ *  waits up to a minute -- the Windows cold start (Start-ScheduledTask -> wscript -> node) has never
+ *  been timed live, see above. */
+const UPDATE_HEALTH_BUDGET = { attempts: 60, delayMs: 1000 };
+/** Waits for a health answer that is `ok` and, when `expectedVersion` is given, reports exactly that
+ *  version (#659): the old process still answering on the port is not the new bundle coming up. */
+async function confirmHealthy(deps, port, certPem, expectedFingerprint, expectedVersion, budget) {
+    let lastVersion;
+    for (let attempt = 0; attempt < budget.attempts; attempt++) {
         const health = await deps.fetchHealth(port, certPem, expectedFingerprint);
-        if (health?.ok)
-            return;
-        if (attempt < HEALTH_CHECK_ATTEMPTS - 1) {
-            await new Promise((resolve) => setTimeout(resolve, HEALTH_CHECK_DELAY_MS));
+        if (health?.ok) {
+            if (expectedVersion === null || health.version === expectedVersion)
+                return;
+            lastVersion = health.version;
         }
+        if (attempt < budget.attempts - 1) {
+            await new Promise((resolve) => setTimeout(resolve, budget.delayMs));
+        }
+    }
+    if (lastVersion !== undefined) {
+        throw new Error(`port ${port} still answers version ${lastVersion}, not ${expectedVersion}`);
     }
     throw new Error(`new process did not answer a health check on port ${port}`);
 }
@@ -22028,28 +22090,72 @@ async function installService(deps) {
         deps.print("warning: AC_AGENT_REPOS_ROOT overrides repos_root; the saved value will take effect when it is unset");
     }
     const bundlePath = bundleTargetPath(deps.stateDir);
-    deps.copyFile(deps.bundleSourcePath, bundlePath);
-    const { certPem } = await ensureCert({
-        stateDir: deps.stateDir,
-        hostname: deps.hostname(),
-        ips: deps.ips,
-        readFile: deps.readFile,
-        writeFile: (p, content, mode) => deps.writeFile(p, content, mode),
-    });
-    const fp = fingerprint(certPem);
-    // #263: refuse before registering a task/unit nothing can ever see, rather than leave a broken
-    // registration behind for `status`/`start` to fail against later. Must run after the state-dir
-    // writes above (so a genuinely virtualized session's own writes are what the probe finds) and
-    // before `deps.platform.install` (which is what actually registers the task/unit on Windows).
-    const virtualization = detectVirtualization(deps);
-    if (virtualization.virtualized) {
-        throw new Error(installRefusalMessage(virtualization.packageFamily, virtualization.vfsPath));
+    const backupPath = bundleBackupPath(deps.stateDir);
+    // #659: an install over a running agent keeps the bundle it is replacing, and the version that
+    // bundle is serving, so a new bundle that never comes up can be undone. Read before the copy: once
+    // the copy lands, the file on disk is no longer what the running process loaded.
+    const wasRunning = isAgentRunning(deps);
+    let backedUp = false;
+    let previousVersion = null;
+    if (wasRunning && deps.exists(bundlePath)) {
+        previousVersion = await runningVersion(deps, port);
+        deps.copyFile(bundlePath, backupPath);
+        backedUp = true;
+    }
+    const record = (status, message) => {
+        if (!deps.updateMode)
+            return;
+        writeUpdateRecord(deps, {
+            status,
+            from: previousVersion,
+            target: deps.version,
+            at: nowIso(deps),
+            ...(message !== undefined ? { message } : {}),
+        });
+    };
+    record("installing");
+    let certPem;
+    let fp;
+    let result;
+    try {
+        deps.copyFile(deps.bundleSourcePath, bundlePath);
+        certPem = (await ensureCert({
+            stateDir: deps.stateDir,
+            hostname: deps.hostname(),
+            ips: deps.ips,
+            readFile: deps.readFile,
+            writeFile: (p, content, mode) => deps.writeFile(p, content, mode),
+        })).certPem;
+        fp = fingerprint(certPem);
+        // #263: refuse before registering a task/unit nothing can ever see, rather than leave a broken
+        // registration behind for `status`/`start` to fail against later. Must run after the state-dir
+        // writes above (so a genuinely virtualized session's own writes are what the probe finds) and
+        // before `deps.platform.install` (which is what actually registers the task/unit on Windows).
+        const virtualization = detectVirtualization(deps);
+        if (virtualization.virtualized) {
+            throw new Error(installRefusalMessage(virtualization.packageFamily, virtualization.vfsPath));
+        }
+        result = await deps.platform.install({
+            nodePath: deps.nodePath,
+            bundlePath,
+            user: deps.user,
+        });
+    }
+    catch (err) {
+        // #659 review round 1: a failure before the restart leaves the old process running, so put its
+        // bundle back on disk (the next crash restart must load what was serving, not the half-installed
+        // new one) and record the outcome -- `installing` must never be the last word.
+        if (backedUp) {
+            try {
+                deps.copyFile(backupPath, bundlePath);
+            }
+            catch {
+                // the backup is still in place for a manual restore; the original error is what matters
+            }
+        }
+        record("failed", err instanceof Error ? err.message : String(err));
+        throw err;
     }
-    const result = await deps.platform.install({
-        nodePath: deps.nodePath,
-        bundlePath,
-        user: deps.user,
-    });
     deps.print(`config: ${path.join(deps.configDir, "agent.toml")} (${loaded.source})`);
     deps.print(`state: ${deps.stateDir}`);
     deps.print(`fingerprint: ${fp}`);
@@ -22063,19 +22169,101 @@ async function installService(deps) {
     // path -- so `stopService`'s #238 ordering (task/unit stop before the orphaned-pid kill) is
     // exercised here unchanged, just followed by the same `platform.start()` the `start` verb calls.
     if (isAgentRunning(deps)) {
+        // The long budget whenever a rollback is possible, not only under --update: a false failure there
+        // stops a healthy new process and restores the old bundle. Tooling's Update-AcAgent.ps1 runs a
+        // plain `install`, and the Windows cold start has never been timed (#659 review round 1). With
+        // nothing to roll back to, a failure only prints, so the short budget stays.
+        const budget = deps.updateMode || backedUp
+            ? (deps.rollbackHealthBudget ?? UPDATE_HEALTH_BUDGET)
+            : HEALTH_BUDGET;
+        let restartError = null;
         try {
             await stopService(deps);
             await deps.platform.start();
-            await confirmHealthy(deps, port, certPem, fp);
-            deps.print(`restarted: now serving ${deps.version}`);
+            await confirmHealthy(deps, port, certPem, fp, deps.version, budget);
         }
         catch (err) {
-            // The install itself already succeeded (the task/unit is registered against the new bundle);
-            // a restart failure must not be reported as an install failure -- the operator's fallback is
-            // the same manual stop/start #238 already documents.
-            deps.print(`restart failed: ${err instanceof Error ? err.message : String(err)}; run ac-agent stop && ac-agent start`);
+            restartError = err;
+        }
+        if (restartError === null) {
+            // Recorded only after the restart sequence: a failed record write must never look like a
+            // failed restart (#659 review round 1).
+            deps.print(`restarted: now serving ${deps.version}`);
+            record("ok");
+            return;
+        }
+        const reason = restartError instanceof Error ? restartError.message : String(restartError);
+        if (!backedUp) {
+            // Nothing to go back to (no bundle was in place): the install itself already succeeded (the
+            // task/unit is registered against the new bundle), so a restart failure must not be reported
+            // as an install failure -- the operator's fallback is the manual stop/start #238 documents.
+            deps.print(`restart failed: ${reason}; run ac-agent stop && ac-agent start`);
+            record("failed", reason);
+            return;
         }
+        await rollBack(deps, {
+            port,
+            certPem,
+            fp,
+            bundlePath,
+            backupPath,
+            previousVersion,
+            budget,
+            reason,
+        });
+        return;
+    }
+    // Nothing was running to restart (the agent died between the pre-check and now, or a fresh install).
+    // Under --update the agent that launched this install was running, so this is a failure the record
+    // must say, not leave at `installing` (#659 review round 2).
+    record("failed", "no agent was running after the install; run ac-agent start");
+}
+function nowIso(deps) {
+    return (deps.now ?? (() => new Date()))().toISOString();
+}
+/** The version the running agent reports before it is stopped (#659), read with the cert already in
+ *  the state dir -- null when there is no cert yet or the agent does not answer. */
+async function runningVersion(deps, port) {
+    const certPem = deps.readFile(path.join(deps.stateDir, "cert.pem"));
+    if (certPem === null)
+        return null;
+    const health = await deps.fetchHealth(port, certPem, fingerprint(certPem));
+    return health?.ok && typeof health.version === "string" ? health.version : null;
+}
+/** #659: the new bundle never answered health at its own version, so restore the one it replaced.
+ *  Stops first, in #238's order (the task/unit, then the pid) -- on Windows that ends `launch.js`'s
+ *  retry loop, which would otherwise rerun the broken bundle a minute later, mid-restore. Throws
+ *  either way, so `install` exits 1: the install did not take. */
+async function rollBack(deps, ctx) {
+    const record = (status, message) => {
+        if (!deps.updateMode)
+            return;
+        writeUpdateRecord(deps, {
+            status,
+            from: ctx.previousVersion,
+            target: deps.version,
+            at: nowIso(deps),
+            message,
+        });
+    };
+    try {
+        await stopService(deps);
+        deps.copyFile(ctx.backupPath, ctx.bundlePath);
+        await deps.platform.start();
+        await confirmHealthy(deps, ctx.port, ctx.certPem, ctx.fp, ctx.previousVersion, ctx.budget);
     }
+    catch (err) {
+        const why = err instanceof Error ? err.message : String(err);
+        deps.print(`rollback failed: ${why}; the new bundle failed first (${ctx.reason}). ` +
+            `${ctx.backupPath} holds the previous bundle: copy it over ${ctx.bundlePath} if it is not ` +
+            "already there, then run ac-agent start");
+        record("failed", `${ctx.reason}; rollback failed: ${why}`);
+        throw new Error(`install did not take and the rollback failed: ${why}`);
+    }
+    const serving = ctx.previousVersion ?? "the previous bundle";
+    deps.print(`rolled back: now serving ${serving} (${ctx.reason})`);
+    record("rolled-back", ctx.reason);
+    throw new Error(`install did not take: ${deps.version} never came up; rolled back to ${serving}`);
 }
 async function status(deps, now = () => new Date()) {
     const loaded = loadConfig(deps.configDir, {
@@ -22113,6 +22301,7 @@ async function status(deps, now = () => new Date()) {
         grants,
         virtualized: virtualization.virtualized,
         lanAddress: deps.ips[0] ?? null,
+        update: readUpdateRecord(deps),
     };
 }
 /** Generates a one-time pairing code (#48): refuses when already paired unless `force` (which is how
@@ -22199,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
@@ -22609,6 +22813,8 @@ async function dispatch(argv, io) {
                         port: { type: "string" },
                         name: { type: "string" },
                         "repos-root": { type: "string" },
+                        // #659: set only by the agent's own update route -- see ServiceDeps.updateMode.
+                        update: { type: "boolean", default: false },
                     },
                     allowPositionals: false,
                 });
@@ -22619,6 +22825,7 @@ async function dispatch(argv, io) {
                     port: values.port !== undefined ? Number.parseInt(values.port, 10) : undefined,
                     name: values.name,
                     reposRoot,
+                    update: values.update ?? false,
                 });
                 return 0;
             }
@@ -22661,9 +22868,19 @@ async function dispatch(argv, io) {
             case "publish-adopt":
                 await io.publishAdopt();
                 return 0;
-            case "version":
-                io.print(packageJson.version);
+            case "version": {
+                const { values } = parseArgs({
+                    args: rest,
+                    options: { json: { type: "boolean", default: false } },
+                    allowPositionals: false,
+                });
+                // #659: `--json` is how the update route reads a staged bundle's API version without
+                // starting it.
+                io.print(values.json
+                    ? JSON.stringify({ version: packageJson.version, apiVersion: AGENT_API_VERSION })
+                    : packageJson.version);
                 return 0;
+            }
             default:
                 io.printError(USAGE);
                 return 1;
@@ -22854,6 +23071,13 @@ async function buildPlatformOps(port, unitPath, launchScriptPath, configDir, sta
 function systemdUnitPath(homedir) {
     return path.posix.join(homedir, ".config", "systemd", "user", "ac-agent.service");
 }
+/** A `/v1/health` answer as `install`/`status` read it: the HTTP status, plus the reported version
+ *  when the body carries one (#659) -- that version is what tells a restarted new bundle from the old
+ *  process still answering on the port. */
+function healthResultFrom(ok, body) {
+    const version = typeof body === "object" && body !== null ? body.version : undefined;
+    return typeof version === "string" ? { ok, version } : { ok };
+}
 async function buildServiceDeps(overrides = {}) {
     const os = await import('node:os');
     const fs = await import('node:fs');
@@ -22886,6 +23110,7 @@ async function buildServiceDeps(overrides = {}) {
         },
         readFile,
         writeFile: (p, content, mode) => fs.writeFileSync(p, content, mode !== undefined ? { mode } : undefined),
+        renameFile: (from, to) => fs.renameSync(from, to),
         removeFile: (p) => {
             try {
                 fs.unlinkSync(p);
@@ -22912,6 +23137,7 @@ async function buildServiceDeps(overrides = {}) {
         machineNameOverride: overrides.name,
         portOverride: overrides.port,
         reposRootOverride: overrides.reposRoot,
+        updateMode: overrides.update ?? false,
         env: process.env,
         osPlatform: process.platform,
         readdir: (p) => fs.readdirSync(p),
@@ -22939,7 +23165,14 @@ async function buildServiceDeps(overrides = {}) {
                 const res = await undiciFetch(`https://127.0.0.1:${healthPort}/v1/health`, {
                     dispatcher: agent,
                 });
-                return { ok: res.ok };
+                let body;
+                try {
+                    body = await res.json();
+                }
+                catch {
+                    // an unparseable body still counts by its status alone, as before
+                }
+                return healthResultFrom(res.ok, body);
             }
             catch {
                 return null;
@@ -22954,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; });
@@ -23172,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,
     });
@@ -23192,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,
@@ -23212,6 +23495,7 @@ async function realServe(overrides = {}) {
         grants: grants$1,
         preflight: () => runPreflight(preflightDeps),
         claudeDesktop: claudeDesktopWatch.current,
+        update: updater$1,
     });
     const running = await startServer({
         app,
@@ -23224,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);
                 }
@@ -64118,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,
@@ -74959,4 +75243,423 @@ var tunnel = /*#__PURE__*/Object.freeze({
   registerTunnelVerb: registerTunnelVerb
 });
 
-export { AGENT_API_VERSION, buildRepoFs, buildWhichFs, dispatch, isEntryPoint, main, realExists };
+/**
+ * #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.47",
+  "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.",