@hivemagnus/magnus-agent 1.0.2 → 1.1.0

package/.env.example

@@ -95,6 +95,9 @@ LOG_LEVEL=info
 # ── Ardent (optional) ────────────────────────────────────────────────
 # ARDENT_OWNER_USER=operator
 # ARDENT_STAGED_PACKAGE=/opt/magnus-agent/ardent-package.tgz
+# Scoped npm names accepted as the Ardent runtime, in preference order. Add an
+# older build's package name to keep managing it (interoperating with older components).
+# MAGNUS_AGENT_ARDENT_PACKAGES=@hivemagnus/ardent
 
 # ── HiveMem credential renewal (optional, all lists empty by default) ─
 # Entries live in a root-owned 0600 JSON file; the lists below bound what the
@@ -113,3 +116,14 @@ LOG_LEVEL=info
 # MAGNUS_AGENT_WORKSPACE_ROOT=/var/lib/magnus-agent/workspaces
 # Account the docker-group heartbeat check verifies (default: the agent's own user).
 # MAGNUS_AGENT_DOCKER_USER=operator
+
+# ── Self-upgrade (after `sudo magnus-agent install-service`) ─────────
+# Accept server-driven upgrades to an exact version and integrity.
+# MAGNUS_AGENT_SELF_UPGRADE=true
+# Seconds a new version has to report a heartbeat before the launcher reverts it.
+# MAGNUS_AGENT_UPGRADE_CONFIRM_SECONDS=180
+# Refuse upgrades whose packages fail `npm audit signatures`.
+# MAGNUS_AGENT_UPGRADE_REQUIRE_PROVENANCE=true
+# Offline nodes: install from hivemagnus-magnus-agent-<X>.tgz files in this directory.
+# MAGNUS_AGENT_UPGRADE_SOURCE_DIR=
+# MAGNUS_AGENT_NPM=npm

package/README.md

@@ -121,6 +121,34 @@ verification is never disabled.
 | HiveMem credential and certificate renewal | **yes** | not started |
 | Execution supervisor (`MAGNUS_EXECUTION_SUPERVISOR_ENABLED`) | **yes** | configuration error if enabled |
 
+## Upgrades
+
+Run `sudo magnus-agent install-service` (add `--unprivileged` for the ordinary-account mode) once
+per node. It does four things:
+
+- moves the install into `/opt/magnus-agent/versions/<X>`
+- links `./current`
+- installs the upgrade launcher (`launcher/launcher.mjs`)
+- writes the systemd unit
+
+`--dry-run` prints the steps first.
+
+After that, the server can upgrade the agent from the console's **Upgrade agents** action or with
+`magnus-server agents upgrade`, in four steps:
+
+1. The agent downloads the exact version the server names and checks its npm `sha512` integrity. It
+   also runs `npm audit signatures` (`MAGNUS_AGENT_UPGRADE_REQUIRE_PROVENANCE`).
+2. It installs that version beside the running one, points `./current` at it and exits.
+3. The launcher starts the new version on trial.
+4. If the new version does not report an accepted heartbeat within
+   `MAGNUS_AGENT_UPGRADE_CONFIRM_SECONDS` (default 180), or crashes twice, the launcher switches back
+   to the previous version.
+
+The agent writes only inside its install directory and never uses sudo. Set
+`MAGNUS_AGENT_SELF_UPGRADE=false` to refuse upgrade requests on a node. Offline nodes can install from
+local tarballs with `MAGNUS_AGENT_UPGRADE_SOURCE_DIR`. See
+[UPGRADING.md](../../UPGRADING.md#agents).
+
 ## CLI
 
 ```text
@@ -150,7 +178,7 @@ and `magnus-agent env-schema` prints them as JSON.
 | `SKILLS_DIR` / `SKILLS_EXTRA_DIRS` | Skill directories |
 | `HERMES_USER`, `HERMES_REGISTRY_TOKEN`, `MAGNUS_HERMES_SYNC_PULL` | Hermes Agent management and registry sync |
 | `CODEX_USER`, `CODEX_BIN`, `CODEX_HOME` | Codex CLI management |
-| `ARDENT_OWNER_USER`, `ARDENT_STAGED_PACKAGE` | Ardent management |
+| `ARDENT_OWNER_USER`, `ARDENT_STAGED_PACKAGE`, `MAGNUS_AGENT_ARDENT_PACKAGES` | Ardent management |
 | `MAGNUS_AGENT_RENEWAL_*` | HiveMem credential renewal allowlists (empty by default) |
 | `MAGNUS_AGENT_TLS_RENEWAL=tailscale` | Renew a Tailscale listener certificate |
 | `MAGNUS_AGENT_PRIVILEGED` | Privileged (root, default `true`) or unprivileged mode |
@@ -175,6 +203,17 @@ With `--submit-only` it only reports the local Hermes inventory. Applying the
 server's desired skills, plugins and MCP releases also needs
 `MAGNUS_HERMES_SYNC_PULL=true`.
 
+## Interoperating with older components
+
+`MAGNUS_AGENT_ARDENT_PACKAGES` (default `@hivemagnus/ardent`) lists the scoped
+npm package names the agent accepts as the Ardent runtime, in preference order.
+It applies to the staged `ardent-package.json` sidecar, the install path
+`node_modules/<name>`, the install receipt and the managed `ardent@<profile>`
+user unit. To keep managing an Ardent build published under another scope, add
+its name, for example `MAGNUS_AGENT_ARDENT_PACKAGES=@hivemagnus/ardent,@legacy-scope/ardent`.
+Older sidecars with the `{name, version, sha256}` shape are accepted unchanged.
+Profile channel maps accept any channel key that matches `[a-z][a-z0-9_-]{0,31}`.
+
 ## Development
 
 ```bash

package/dist/agent.js

@@ -7,6 +7,7 @@ import { controlApiFetch } from './tls.js';
 import { startSpan, formatTraceparent } from './collectors/otel-collector.js';
 import { collectHermesState } from './executors/hermes-manager.js';
 import { existsSync } from 'node:fs';
+import { confirmTrial, selfUpgradeStatus } from './upgrade/self-upgrade.js';
 const HEARTBEAT_INTERVAL_MS = 30_000; // 30s
 const HEARTBEAT_BACKOFF_MAX_MS = 5 * 60_000; // 5 min max backoff
 const HERMES_DISCOVERY_INTERVAL_MS = Number(process.env['HERMES_DISCOVERY_INTERVAL_MS'] ?? 3 * 60 * 60 * 1000);
@@ -112,6 +113,8 @@ export function startHeartbeatLoop() {
                         serviceRestart: existsSync('/etc/magnus/security-restart-services'),
                     },
                     ...(hermes ? { hermes } : {}),
+                    nodeVersion: process.version,
+                    selfUpgrade: selfUpgradeStatus(AGENT_VERSION),
                 },
                 headers: {
                     'x-node-token': NODE_TOKEN,
@@ -120,8 +123,11 @@ export function startHeartbeatLoop() {
                 timeout: 10_000,
                 fetch: controlApiFetch,
             }).json().then((resp) => {
+                // The first accepted heartbeat from a version on trial confirms the upgrade.
+                if (resp.data?.accepted && confirmTrial(AGENT_VERSION))
+                    logger.info(`Self-upgrade to ${AGENT_VERSION} confirmed`);
                 if (resp.data?.updateAvailable && resp.data.expectedVersion) {
-                    logger.info(`Agent update available: ${AGENT_VERSION} → ${resp.data.expectedVersion}`);
+                    logger.info(`Agent update available: ${AGENT_VERSION} → ${resp.data.expectedVersion} (upgrade from the console's Nodes page or with \`magnus-server agents upgrade\`)`);
                 }
             });
             if (consecutiveFailures > 0) {

package/dist/env-catalog.js

@@ -12,6 +12,11 @@ export const agentEnvCatalog = [
     { name: 'NODE_MANAGER_BIND_HOST', required: false, secret: false, default: '0.0.0.0 (TLS) / 127.0.0.1 (HTTP)', group: 'core', description: 'Listener address.' },
     { name: 'ENABLE_NODE_MANAGEMENT', required: false, secret: false, default: 'true', group: 'core', description: 'Node management routes and heartbeat. Must stay true.' },
     { name: 'MAGNUS_AGENT_PRIVILEGED', required: false, secret: false, default: 'true', group: 'core', description: 'true: run as root with every executor (startup fails if not root). false: run as an ordinary account; cron, users, system updates, docker-group remediation, Ardent management, credential renewal and the execution supervisor are disabled and their routes return 403 AGENT_NOT_PRIVILEGED.' },
+    { name: 'MAGNUS_AGENT_SELF_UPGRADE', required: false, secret: false, default: 'true', group: 'core', description: 'true: accept server-driven upgrades to an exact version and npm integrity, installed into versions/<X> and confirmed by the launcher (needs `magnus-agent install-service`). false: refuse them; upgrade by hand or by image.' },
+    { name: 'MAGNUS_AGENT_UPGRADE_CONFIRM_SECONDS', required: false, secret: false, default: '180', group: 'core', description: 'Seconds a newly installed version has to report an accepted heartbeat before the launcher switches back to the previous one (10-3600).' },
+    { name: 'MAGNUS_AGENT_UPGRADE_REQUIRE_PROVENANCE', required: false, secret: false, default: 'true', group: 'core', description: 'Run `npm audit signatures` on a staged upgrade and refuse it unless every package has valid registry signatures. Set false only for locally built tarballs.' },
+    { name: 'MAGNUS_AGENT_UPGRADE_SOURCE_DIR', required: false, secret: false, group: 'core', description: 'Install self-upgrades from tarballs in this directory (hivemagnus-magnus-agent-<X>.tgz) instead of the npm registry, for offline nodes. The integrity check still applies.' },
+    { name: 'MAGNUS_AGENT_NPM', required: false, secret: false, default: 'npm', group: 'core', description: 'npm executable used for self-upgrades.' },
     { name: 'MAGNUS_EXECUTION_SUPERVISOR_ENABLED', required: false, secret: false, default: 'false', group: 'core', description: 'Run commands under the durable execution supervisor.' },
     { name: 'CONTROL_API_CA_PATH', required: false, secret: false, group: 'tls', description: 'PEM CA bundle trusted for a private-CA Control API. Verification is never disabled.' },
     { name: 'TLS_CERT_PATH', required: false, secret: false, group: 'tls', description: 'Listener certificate (absolute or relative to AGENT_INSTALL_DIR). Required with TLS_KEY_PATH when NODE_ENV=production.' },
@@ -36,6 +41,7 @@ export const agentEnvCatalog = [
     { name: 'CODEX_HOME', required: false, secret: false, default: '~/.codex', group: 'codex', description: 'Codex state directory override.' },
     { name: 'ARDENT_OWNER_USER', required: false, secret: false, group: 'ardent', description: 'Local account that owns the Ardent runtime and profiles.' },
     { name: 'ARDENT_STAGED_PACKAGE', required: false, secret: false, default: '/opt/magnus-agent/ardent-package.tgz', group: 'ardent', description: 'Verified Ardent package tarball staged for installation.' },
+    { name: 'MAGNUS_AGENT_ARDENT_PACKAGES', required: false, secret: false, default: '@hivemagnus/ardent', group: 'ardent', description: 'Comma-separated scoped npm package names accepted as the Ardent runtime (staged sidecar, install path, receipt), in preference order. Add a legacy name to keep managing an older Ardent build.' },
     { name: 'MAGNUS_AGENT_RENEWAL_CONFIG', required: false, secret: false, default: '$AGENT_INSTALL_DIR/credential-renewal.json', group: 'renewal', description: 'HiveMem credential renewal entries (root-owned, mode 0600). Absent means renewal is off.' },
     { name: 'MAGNUS_AGENT_RENEWAL_ENDPOINTS', required: false, secret: false, group: 'renewal', description: 'Comma-separated HTTPS HiveMem base URLs renewal may call.' },
     { name: 'MAGNUS_AGENT_RENEWAL_UNITS', required: false, secret: false, group: 'renewal', description: 'Comma-separated systemd units renewal may try-restart after replacing a credential.' },

package/dist/env.js

@@ -10,6 +10,7 @@
 import { getFqdn } from './fqdn.js';
 import { isIPv4 } from 'node:net';
 import { agentPrivileged, isRoot } from './privileged.js';
+import { ardentPackageNames } from './executors/ardent-packages.js';
 function envFlag(name, fallback = false) {
     return (process.env[name] ?? String(fallback)).toLowerCase() === 'true';
 }
@@ -113,6 +114,12 @@ export function configurationErrors() {
     if (!agentPrivileged() && MAGNUS_EXECUTION_SUPERVISOR_ENABLED) {
         errors.push('MAGNUS_EXECUTION_SUPERVISOR_ENABLED=true requires MAGNUS_AGENT_PRIVILEGED=true');
     }
+    try {
+        ardentPackageNames();
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : 'MAGNUS_AGENT_ARDENT_PACKAGES is invalid');
+    }
     return errors;
 }
 //# sourceMappingURL=env.js.map

package/dist/executors/ardent-manager.d.ts

@@ -1,4 +1,5 @@
 import { Hono } from 'hono';
+export { ardentPackageNames, DEFAULT_ARDENT_PACKAGE } from './ardent-packages.js';
 type ArdentRoot = {
     owner: string;
     home: string;
@@ -6,13 +7,13 @@ type ArdentRoot = {
     install: string;
 };
 export declare function verifiedInstalledArdentPackage(install: string, staged: {
+    name?: string;
     version: string;
     sha256: string;
 }): Promise<boolean>;
 export declare function readArdentState(target?: ArdentRoot): Promise<object>;
 export declare function hermesTrafficConsumersDisabled(home: string): Promise<boolean>;
-export declare function ardentUserUnit(root: ArdentRoot, profile: string): string;
+export declare function ardentUserUnit(root: ArdentRoot, profile: string, packageName?: string): string;
 export declare function createArdentRoutes(resolveRoot?: () => Promise<ArdentRoot>): Hono;
 export declare const ardentRoutes: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
-export {};
 //# sourceMappingURL=ardent-manager.d.ts.map

package/dist/executors/ardent-manager.js

@@ -7,6 +7,8 @@ import { Hono } from 'hono';
 import { parse as parseEnv } from 'dotenv';
 import YAML from 'yaml';
 import { z } from 'zod';
+import { ardentPackageNames } from './ardent-packages.js';
+export { ardentPackageNames, DEFAULT_ARDENT_PACKAGE } from './ardent-packages.js';
 const profileName = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/);
 const configSummary = z.object({
     schema_version: z.literal(1), profile: profileName, name: z.string().min(1),
@@ -15,12 +17,34 @@ const configSummary = z.object({
     a2a: z.object({ enabled: z.boolean() }).passthrough(),
     channels: z.record(z.string().regex(/^[a-z][a-z0-9_-]{0,31}$/), z.object({ enabled: z.boolean() }).passthrough()).default({}),
 }).passthrough();
-const packageVersion = z.object({ name: z.literal('@hivemagnus/ardent'), version: z.string() });
+const acceptedPackageName = z.string().refine(name => ardentPackageNames().includes(name), 'Ardent package name is not accepted by MAGNUS_AGENT_ARDENT_PACKAGES');
+const packageVersion = z.object({ name: acceptedPackageName, version: z.string() });
 const installedPackageReceipt = z.object({
-    schemaVersion: z.literal(1), name: z.literal('@hivemagnus/ardent'),
+    schemaVersion: z.literal(1), name: acceptedPackageName,
     version: z.string(), sha256: z.string().regex(/^[a-f0-9]{64}$/),
     packageTreeSha256: z.string().regex(/^[a-f0-9]{64}$/),
 }).strict();
+/** Package directory of an accepted Ardent package name inside an install prefix. */
+function packageDir(install, name) {
+    if (!ardentPackageNames().includes(name))
+        throw new Error('Ardent package name is not accepted by MAGNUS_AGENT_ARDENT_PACKAGES');
+    return join(install, 'node_modules', ...name.split('/'));
+}
+/** The accepted Ardent package installed under `install`, in preference order. */
+async function installedPackageName(install) {
+    for (const name of ardentPackageNames()) {
+        try {
+            const installed = packageVersion.parse(JSON.parse(await readFile(join(packageDir(install, name), 'package.json'), 'utf8')));
+            if (installed.name === name)
+                return name;
+        }
+        catch { /* Try the next accepted name. */ }
+    }
+    return null;
+}
+async function installedCli(install) {
+    return join(packageDir(install, await installedPackageName(install) ?? ardentPackageNames()[0]), 'dist/cli.js');
+}
 /** Channel name -> enabled, for every channel the profile config declares. */
 function channelStates(config) {
     return Object.fromEntries(Object.entries(config.channels).map(([name, channel]) => [name, channel.enabled]));
@@ -112,11 +136,11 @@ async function stagedPackage() {
     const sidecarBytes = await readFile(sidecar);
     if (createHash('sha256').update(sidecarBytes).digest('hex') !== entry('ardent-package.json'))
         throw new Error('Staged Ardent package sidecar differs from release manifest');
-    const details = z.object({ name: z.literal('@hivemagnus/ardent'), version: z.string(), sha256: z.string().regex(/^[a-f0-9]{64}$/) }).parse(JSON.parse(sidecarBytes.toString('utf8')));
+    const details = z.object({ name: acceptedPackageName, version: z.string(), sha256: z.string().regex(/^[a-f0-9]{64}$/) }).parse(JSON.parse(sidecarBytes.toString('utf8')));
     const digest = createHash('sha256').update(await readFile(archive)).digest('hex');
     if (digest !== details.sha256 || digest !== entry('ardent-package.tgz'))
         throw new Error('Staged Ardent package differs from release manifest');
-    return { version: details.version, sha256: digest };
+    return { name: details.name, version: details.version, sha256: digest };
 }
 async function packageTreeDigest(packageRoot) {
     const entries = [];
@@ -160,15 +184,20 @@ export async function verifiedInstalledArdentPackage(install, staged) {
     const receipt = installedPackageReceipt.safeParse(JSON.parse(await readFile(receiptPath, 'utf8')));
     if (!receipt.success || receipt.data.version !== staged.version || receipt.data.sha256 !== staged.sha256)
         return false;
-    return await packageTreeDigest(join(install, 'node_modules/@hivemagnus/ardent')) === receipt.data.packageTreeSha256;
+    if (staged.name !== undefined && receipt.data.name !== staged.name)
+        return false;
+    return await packageTreeDigest(packageDir(install, receipt.data.name)) === receipt.data.packageTreeSha256;
 }
 export async function readArdentState(target) {
     const root = target ?? await ardentRoot();
     let version = null;
+    let packageName = null;
     try {
-        const packageFile = join(root.install, 'node_modules/@hivemagnus/ardent/package.json');
-        const installed = JSON.parse(await readFile(packageFile, 'utf8'));
-        version = packageVersion.parse(installed).version;
+        packageName = await installedPackageName(root.install);
+        if (packageName) {
+            const installed = JSON.parse(await readFile(join(packageDir(root.install, packageName), 'package.json'), 'utf8'));
+            version = packageVersion.parse(installed).version;
+        }
     }
     catch { /* An uninstalled package is a normal inventory state. */ }
     const profiles = await Promise.all((await safeProfiles(root.root)).map(async (name) => {
@@ -191,7 +220,7 @@ export async function readArdentState(target) {
     catch (error) {
         stagedPackageError = error instanceof Error ? error.message.slice(0, 200) : 'Staged package unavailable';
     }
-    return { installed: version !== null, version, owner: root.owner, profiles, stagedPackage: staged, stagedPackageError, checkedAt: new Date().toISOString() };
+    return { installed: version !== null, version, packageName, owner: root.owner, profiles, stagedPackage: staged, stagedPackageError, checkedAt: new Date().toISOString() };
 }
 async function managementToken(dir, envName) {
     const processToken = process.env[envName];
@@ -264,12 +293,12 @@ export async function hermesTrafficConsumersDisabled(home) {
         return false;
     }
 }
-export function ardentUserUnit(root, profile) {
+export function ardentUserUnit(root, profile, packageName = ardentPackageNames()[0]) {
     profileName.parse(profile);
     const safe = /^[A-Za-z0-9_./-]+$/;
     if (![root.home, root.root, root.install].every(path => safe.test(path)))
         throw new Error('Ardent service paths contain unsupported characters');
-    return `[Unit]\nDescription=Magnus Ardent ${profile}\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nWorkingDirectory=${join(root.root, 'profiles', profile)}\nEnvironment=ARDENT_HOME=${root.root}\nExecStart=/usr/bin/node ${join(root.install, 'node_modules/@hivemagnus/ardent/dist/cli.js')} --profile ${profile} gateway run\nRestart=on-failure\nRestartSec=5\nTimeoutStopSec=75\nNoNewPrivileges=true\n\n[Install]\nWantedBy=default.target\n`;
+    return `[Unit]\nDescription=Magnus Ardent ${profile}\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nWorkingDirectory=${join(root.root, 'profiles', profile)}\nEnvironment=ARDENT_HOME=${root.root}\nExecStart=/usr/bin/node ${join(packageDir(root.install, packageName), 'dist/cli.js')} --profile ${profile} gateway run\nRestart=on-failure\nRestartSec=5\nTimeoutStopSec=75\nNoNewPrivileges=true\n\n[Install]\nWantedBy=default.target\n`;
 }
 async function serviceAction(root, profile, action) {
     if (process.getuid?.() !== 0)
@@ -289,7 +318,7 @@ async function serviceAction(root, profile, action) {
     }
     const unit = `ardent@${profile}.service`;
     const path = join(root.home, '.config/systemd/user', unit);
-    const expected = ardentUserUnit(root, profile);
+    const expected = ardentUserUnit(root, profile, await installedPackageName(root.install) ?? undefined);
     const metadata = await lstat(path).catch((error) => {
         if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
             return undefined;
@@ -307,7 +336,7 @@ async function serviceAction(root, profile, action) {
     if (action !== 'service-start' && existing === undefined)
         throw new Error('Managed Ardent user service is not installed');
     if (action === 'service-start' && existing === undefined) {
-        const script = join(root.install, 'node_modules/@hivemagnus/ardent/dist/cli.js');
+        const script = await installedCli(root.install);
         const scriptInfo = await lstat(script);
         if (!scriptInfo.isFile() || scriptInfo.isSymbolicLink())
             throw new Error('Ardent package executable is unavailable');
@@ -377,14 +406,14 @@ async function installPackage(root) {
     let installed = false;
     try {
         await runAsOwner(root, ['/usr/bin/npm', 'install', '--prefix', stage, '--omit=dev', '--no-audit', '--no-fund', '--no-save', archive], 9 * 60_000);
-        const packageFile = join(stage, 'node_modules/@hivemagnus/ardent/package.json');
+        const packageFile = join(packageDir(stage, staged.name), 'package.json');
         const candidate = packageVersion.parse(JSON.parse(await readFile(packageFile, 'utf8')));
-        if (candidate.version !== staged.version)
-            throw new Error('Staged Ardent package version differs');
+        if (candidate.name !== staged.name || candidate.version !== staged.version)
+            throw new Error('Staged Ardent package name or version differs');
         await runAsOwner(root, ['/usr/bin/node', '-e', "const Database=require(process.argv[1]);new Database(':memory:').close()", join(stage, 'node_modules/better-sqlite3')], 10_000);
-        const packageTreeSha256 = await packageTreeDigest(join(stage, 'node_modules/@hivemagnus/ardent'));
+        const packageTreeSha256 = await packageTreeDigest(packageDir(stage, staged.name));
         await writeFile(join(stage, 'package-receipt.json'), `${JSON.stringify({
-            schemaVersion: 1, name: '@hivemagnus/ardent', version: staged.version, sha256: staged.sha256, packageTreeSha256,
+            schemaVersion: 1, name: staged.name, version: staged.version, sha256: staged.sha256, packageTreeSha256,
         })}\n`, { mode: 0o644 });
         if (priorInfo) {
             await rename(root.install, previous);
@@ -426,7 +455,7 @@ async function createProfile(root, profile, body) {
         if (current.config.api.port === input.api_port)
             throw new Error(`API port is already assigned to profile ${name}`);
     }
-    const script = join(root.install, 'node_modules/@hivemagnus/ardent/dist/cli.js');
+    const script = await installedCli(root.install);
     const metadata = await lstat(script);
     if (!metadata.isFile() || metadata.isSymbolicLink())
         throw new Error('Installed Ardent CLI is unsafe');
@@ -453,7 +482,7 @@ async function importHermesProfile(root, profile, body) {
     const sourceInfo = await lstat(source);
     if (!sourceInfo.isDirectory() || sourceInfo.isSymbolicLink())
         throw new Error('Hermes source home is unsafe');
-    const script = join(root.install, 'node_modules/@hivemagnus/ardent/dist/cli.js');
+    const script = await installedCli(root.install);
     const scriptInfo = await lstat(script);
     if (!scriptInfo.isFile() || scriptInfo.isSymbolicLink())
         throw new Error('Installed Ardent CLI is unsafe');

package/dist/executors/ardent-packages.d.ts

@@ -0,0 +1,8 @@
+export declare const DEFAULT_ARDENT_PACKAGE = "@hivemagnus/ardent";
+/**
+ * npm package names the agent accepts as the Ardent runtime, in preference
+ * order. `MAGNUS_AGENT_ARDENT_PACKAGES` (comma-separated scoped names) lets a
+ * node keep managing an Ardent build published under another scope.
+ */
+export declare function ardentPackageNames(value?: string | undefined): string[];
+//# sourceMappingURL=ardent-packages.d.ts.map

package/dist/executors/ardent-packages.js

@@ -0,0 +1,16 @@
+export const DEFAULT_ARDENT_PACKAGE = '@hivemagnus/ardent';
+const scopedPackageName = /^@[a-z0-9][a-z0-9._-]{0,99}\/[a-z0-9][a-z0-9._-]{0,99}$/;
+/**
+ * npm package names the agent accepts as the Ardent runtime, in preference
+ * order. `MAGNUS_AGENT_ARDENT_PACKAGES` (comma-separated scoped names) lets a
+ * node keep managing an Ardent build published under another scope.
+ */
+export function ardentPackageNames(value = process.env['MAGNUS_AGENT_ARDENT_PACKAGES']) {
+    if (value === undefined || value.trim() === '')
+        return [DEFAULT_ARDENT_PACKAGE];
+    const names = value.split(',').map(item => item.trim()).filter(Boolean);
+    if (!names.length || names.some(name => !scopedPackageName.test(name)))
+        throw new Error('MAGNUS_AGENT_ARDENT_PACKAGES must list scoped npm package names such as @scope/ardent');
+    return [...new Set(names)];
+}
+//# sourceMappingURL=ardent-packages.js.map

package/dist/executors/scheduler-status.d.ts

@@ -6,8 +6,8 @@ export declare const schedulerStatusSchema: z.ZodObject<{
     nodeFqdn: z.ZodString;
     nonce: z.ZodString;
     state: z.ZodEnum<{
-        enrolled: "enrolled";
         legacy: "legacy";
+        enrolled: "enrolled";
         draining: "draining";
     }>;
     epoch: z.ZodNumber;
@@ -25,7 +25,7 @@ export declare function freshSchedulerStatus(input: {
     nodeId: string;
     nodeFqdn: string;
     nonce: string;
-    state: "enrolled" | "legacy" | "draining";
+    state: "legacy" | "enrolled" | "draining";
     epoch: number;
     barrierId: string | null;
     schedulerChallenge: {

package/dist/index.js

@@ -12,6 +12,7 @@ Usage:
   magnus-agent [start] [--env-file <path>]          Start the agent (default)
   magnus-agent check [--json] [--env-file <path>]   Validate configuration without starting
   magnus-agent env-schema                           Print the configuration schema as JSON
+  magnus-agent install-service [--unprivileged]     (root, once) Versioned layout, upgrade launcher and systemd unit
   magnus-agent --help | --version
 
 Options:
@@ -92,6 +93,10 @@ export async function main(argv) {
             }
             return report.ok ? 0 : 1;
         }
+        case 'install-service': {
+            const { installService } = await import('./upgrade/install-service.js');
+            return installService(cli.rest);
+        }
         default:
             return fail(`unknown command: ${cli.command}. Run "magnus-agent --help".`);
     }

package/dist/security/native-completion-registry.d.ts

@@ -82,6 +82,16 @@ export declare const NATIVE_COMPLETION_REGISTRY: {
         readonly completionMode: "buffered-synchronous-http";
         readonly timeoutCeilingSeconds: 900;
         readonly resourceClassifier: "node-ardent";
+    }, {
+        readonly id: "agent-self-upgrade";
+        readonly method: "POST";
+        readonly pathMatcher: {
+            readonly kind: "exact";
+            readonly path: "/agent-upgrade";
+        };
+        readonly completionMode: "buffered-synchronous-http";
+        readonly timeoutCeilingSeconds: 900;
+        readonly resourceClassifier: "node-filesystem";
     }];
 };
 export type NativeCompletionDescriptor = (typeof NATIVE_COMPLETION_REGISTRY.descriptors)[number];

package/dist/security/native-completion-registry.js

@@ -20,6 +20,8 @@ export const NATIVE_COMPLETION_REGISTRY = {
             completionMode: 'buffered-synchronous-http', timeoutCeilingSeconds: 3600, resourceClassifier: 'node-scheduler' },
         { id: 'ardent-action', method: 'POST', pathMatcher: { kind: 'exact', path: '/ardent/action' },
             completionMode: 'buffered-synchronous-http', timeoutCeilingSeconds: 900, resourceClassifier: 'node-ardent' },
+        { id: 'agent-self-upgrade', method: 'POST', pathMatcher: { kind: 'exact', path: '/agent-upgrade' },
+            completionMode: 'buffered-synchronous-http', timeoutCeilingSeconds: 900, resourceClassifier: 'node-filesystem' },
     ],
 };
 export const NATIVE_COMPLETION_REGISTRY_SHA256 = createHash('sha256')

package/dist/server.js

@@ -162,7 +162,7 @@ export async function createApp() {
     });
     // ── Node-management routes (fleet agent) ──
     if (ENABLE_NODE_MANAGEMENT) {
-        const [{ healthRoutes }, { commandRoutes }, { managedMutationGuard, registerManagedHttp }, { cronRoutes }, { fileRoutes }, { skillRoutes }, { updateRoutes }, { driftRoutes }, { networkInfoRoutes }, { profilingRoutes }, { otelRoutes }, { workspaceRoutes }, { hermesRoutes }, { codexRoutes }, { ardentRoutes },] = await Promise.all([
+        const [{ healthRoutes }, { commandRoutes }, { managedMutationGuard, registerManagedHttp }, { cronRoutes }, { fileRoutes }, { skillRoutes }, { updateRoutes }, { driftRoutes }, { networkInfoRoutes }, { profilingRoutes }, { otelRoutes }, { workspaceRoutes }, { hermesRoutes }, { codexRoutes }, { ardentRoutes }, { agentUpgradeRoutes },] = await Promise.all([
             import('./collectors/health-routes.js'),
             import('./executors/command-executor.js'),
             import('./executors/managed-http.js'),
@@ -178,6 +178,7 @@ export async function createApp() {
             import('./executors/hermes-manager.js'),
             import('./executors/codex-manager.js'),
             import('./executors/ardent-manager.js'),
+            import('./upgrade/routes.js'),
         ]);
         const v1 = new Hono();
         v1.use('*', nodeAuthMiddleware);
@@ -205,6 +206,7 @@ export async function createApp() {
         v1.route('/hermes', hermesRoutes);
         v1.route('/codex', codexRoutes);
         v1.route('/ardent', ardentRoutes);
+        v1.route('/agent-upgrade', agentUpgradeRoutes);
         // User management (provision, password, listing)
         const { userRoutes } = await import('./routes/user-manager.js');
         v1.route('/users', userRoutes);

package/dist/upgrade/install-service.d.ts

@@ -0,0 +1,14 @@
+export interface InstallServiceOptions {
+    dir: string;
+    unprivileged: boolean;
+    user: string;
+    dryRun: boolean;
+    start: boolean;
+    unitPath: string;
+    nodePath: string;
+}
+export declare const INSTALL_SERVICE_USAGE = "Usage: sudo magnus-agent install-service [options]\n\nMoves this install into the versioned layout used by self-upgrades, installs\nthe upgrade launcher and writes the systemd unit. Run it once per node.\n\nOptions:\n  --dir DIR          Install directory (default: AGENT_INSTALL_DIR or /opt/magnus-agent)\n  --unprivileged     Run as an ordinary account (MAGNUS_AGENT_PRIVILEGED=false)\n  --user NAME        Account for --unprivileged (default magnus-agent; must exist)\n  --unit PATH        Unit file (default /etc/systemd/system/magnus-agent.service)\n  --no-start         Write everything, but do not restart the service\n  --dry-run          Print the steps without changing anything";
+export declare function parseInstallServiceArgs(argv: readonly string[], env?: NodeJS.ProcessEnv): InstallServiceOptions | 'help';
+export declare function renderUnit(options: Pick<InstallServiceOptions, 'dir' | 'unprivileged' | 'user' | 'nodePath'>): string;
+export declare function installService(argv: readonly string[]): Promise<number>;
+//# sourceMappingURL=install-service.d.ts.map

package/dist/upgrade/install-service.js

@@ -0,0 +1,227 @@
+/**
+ * `magnus-agent install-service`: one-time, operator-run (root) setup that
+ * moves an npm-prefix install into the versioned layout the self-upgrade
+ * needs, installs the launcher and writes the systemd unit:
+ *
+ *   /opt/magnus-agent/.env
+ *   /opt/magnus-agent/versions/<X>/node_modules/@hivemagnus/magnus-agent
+ *   /opt/magnus-agent/current -> versions/<X>
+ *   /opt/magnus-agent/launcher/launcher.mjs   (ExecStart)
+ *
+ * After this the agent upgrades itself inside that directory; it never needs
+ * root for it and never calls sudo.
+ */
+import { execFileSync } from 'node:child_process';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AGENT_PACKAGE, pointCurrentAt } from './self-upgrade.js';
+export const INSTALL_SERVICE_USAGE = `Usage: sudo magnus-agent install-service [options]
+
+Moves this install into the versioned layout used by self-upgrades, installs
+the upgrade launcher and writes the systemd unit. Run it once per node.
+
+Options:
+  --dir DIR          Install directory (default: AGENT_INSTALL_DIR or /opt/magnus-agent)
+  --unprivileged     Run as an ordinary account (MAGNUS_AGENT_PRIVILEGED=false)
+  --user NAME        Account for --unprivileged (default magnus-agent; must exist)
+  --unit PATH        Unit file (default /etc/systemd/system/magnus-agent.service)
+  --no-start         Write everything, but do not restart the service
+  --dry-run          Print the steps without changing anything`;
+export function parseInstallServiceArgs(argv, env = process.env) {
+    const options = {
+        dir: env['AGENT_INSTALL_DIR'] ?? '/opt/magnus-agent', unprivileged: false, user: 'magnus-agent', dryRun: false, start: true,
+        unitPath: '/etc/systemd/system/magnus-agent.service', nodePath: process.execPath,
+    };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        const value = () => {
+            const next = argv[++index];
+            if (!next || next.startsWith('--'))
+                throw new Error(`${arg} needs a value`);
+            return next;
+        };
+        if (arg === '--help' || arg === '-h')
+            return 'help';
+        else if (arg === '--dir')
+            options.dir = value();
+        else if (arg === '--unprivileged')
+            options.unprivileged = true;
+        else if (arg === '--user')
+            options.user = value();
+        else if (arg === '--unit')
+            options.unitPath = value();
+        else if (arg === '--no-start')
+            options.start = false;
+        else if (arg === '--dry-run')
+            options.dryRun = true;
+        else
+            throw new Error(`unknown option ${arg}`);
+    }
+    options.dir = resolve(options.dir);
+    return options;
+}
+export function renderUnit(options) {
+    const { dir } = options;
+    const common = [
+        'Type=simple',
+        `WorkingDirectory=${dir}`,
+        `Environment=AGENT_INSTALL_DIR=${dir}`,
+        `Environment=npm_config_cache=${join(dir, '.npm')}`,
+        `EnvironmentFile=${join(dir, '.env')}`,
+        `ExecStart=${options.nodePath} ${join(dir, 'launcher', 'launcher.mjs')}`,
+        '# Any exit restarts: the launcher exits to hand over to a new or reverted version.',
+        'Restart=always',
+        'RestartSec=5',
+        'StandardOutput=journal',
+        'StandardError=journal',
+        'UMask=0077',
+        'NoNewPrivileges=true',
+        'PrivateTmp=true',
+    ];
+    const hardening = options.unprivileged ? [
+        `User=${options.user}`,
+        `Group=${options.user}`,
+        'Environment=MAGNUS_AGENT_PRIVILEGED=false',
+        'CapabilityBoundingSet=',
+        'AmbientCapabilities=',
+        'PrivateDevices=true',
+        'ProtectSystem=strict',
+        `ReadWritePaths=${dir}`,
+        'StateDirectory=magnus-agent',
+        'ProtectHome=read-only',
+        'ProtectKernelTunables=true',
+        'ProtectKernelModules=true',
+        'ProtectKernelLogs=true',
+        'ProtectControlGroups=true',
+        'ProtectClock=true',
+        'ProtectHostname=true',
+        'RestrictSUIDSGID=true',
+        'RestrictRealtime=true',
+        'RestrictNamespaces=true',
+        'LockPersonality=true',
+        'RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK',
+        'SystemCallArchitectures=native',
+    ] : [];
+    return [
+        '# Generated by `magnus-agent install-service`. The launcher runs ./current and',
+        '# reverts a self-upgrade that does not report a heartbeat in time.',
+        '[Unit]',
+        `Description=Magnus Agent${options.unprivileged ? ' (unprivileged)' : ''}`,
+        'After=network-online.target',
+        'Wants=network-online.target',
+        'StartLimitIntervalSec=0',
+        '',
+        '[Service]',
+        ...common,
+        ...hardening,
+        '',
+        '[Install]',
+        'WantedBy=multi-user.target',
+        '',
+    ].join('\n');
+}
+function packageRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+function ownVersion() {
+    return JSON.parse(readFileSync(join(packageRoot(), 'package.json'), 'utf8')).version;
+}
+function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+export async function installService(argv) {
+    let options;
+    try {
+        options = parseInstallServiceArgs(argv);
+    }
+    catch (error) {
+        console.error(`magnus-agent install-service: ${error.message}`);
+        return 2;
+    }
+    if (options === 'help') {
+        console.log(INSTALL_SERVICE_USAGE);
+        return 0;
+    }
+    const { dir, dryRun } = options;
+    if (!dryRun && (typeof process.geteuid !== 'function' || process.geteuid() !== 0)) {
+        console.error('magnus-agent install-service writes a system unit; run it as root (sudo). Use --dry-run to preview.');
+        return 1;
+    }
+    const version = ownVersion();
+    const steps = [];
+    const act = (description, action) => {
+        steps.push(description);
+        if (!dryRun)
+            action();
+    };
+    const target = join(dir, 'versions', version);
+    const current = join(dir, 'current');
+    const here = realpathSync(packageRoot());
+    if (!existsSync(join(dir, '.env')))
+        console.warn(`warning: ${join(dir, '.env')} does not exist; create it before the service starts`);
+    if (isSymlink(current)) {
+        steps.push(`keep the versioned layout (./current -> ${realpathSync(current)})`);
+    }
+    else {
+        const prefixModules = join(dir, 'node_modules');
+        const fromPrefix = existsSync(prefixModules) && here === realpathSync(join(prefixModules, ...AGENT_PACKAGE.split('/')));
+        act(`create ${target}`, () => mkdirSync(target, { recursive: true }));
+        if (fromPrefix) {
+            act(`move ${prefixModules} to ${join(target, 'node_modules')}`, () => renameSync(prefixModules, join(target, 'node_modules')));
+            for (const file of ['package.json', 'package-lock.json']) {
+                if (existsSync(join(dir, file)))
+                    act(`move ${file} into ${target}`, () => renameSync(join(dir, file), join(target, file)));
+            }
+        }
+        else {
+            act(`npm install ${AGENT_PACKAGE}@${version} into ${target}`, () => {
+                writeFileSync(join(target, 'package.json'), `${JSON.stringify({ name: `magnus-agent-${version}`, version, private: true,
+                    dependencies: { [AGENT_PACKAGE]: version }, allowScripts: { 'cpu-features': true, ssh2: true } }, null, 2)}\n`);
+                execFileSync('npm', ['install', '--omit=dev', '--no-audit', '--no-fund', '--loglevel=error'], { cwd: target, stdio: 'inherit' });
+            });
+        }
+        act(`point ${current} at versions/${version}`, () => pointCurrentAt(dir, version));
+    }
+    // The launcher is copied from the release that runs install-service, not linked:
+    // self-upgrades never replace it.
+    act(`install ${join(dir, 'launcher', 'launcher.mjs')}`, () => {
+        mkdirSync(join(dir, 'launcher'), { recursive: true, mode: 0o755 });
+        copyFileSync(join(isSymlink(current) ? realpathSync(join(current, 'node_modules', ...AGENT_PACKAGE.split('/'))) : here, 'launcher', 'launcher.mjs'), join(dir, 'launcher', 'launcher.mjs'));
+    });
+    act(`create ${join(dir, '.npm')} and ${join(dir, 'versions')}`, () => {
+        mkdirSync(join(dir, '.npm'), { recursive: true, mode: 0o700 });
+        mkdirSync(join(dir, 'versions'), { recursive: true });
+    });
+    if (options.unprivileged) {
+        const user = options.user;
+        act(`give ${user} the install directory (the agent writes versions/, current and its upgrade state)`, () => {
+            execFileSync('id', ['-u', user], { stdio: 'ignore' });
+            execFileSync('chown', [`${user}:${user}`, dir]);
+            execFileSync('chown', ['-R', `${user}:${user}`, join(dir, 'versions'), join(dir, '.npm')]);
+            execFileSync('chown', ['-h', `${user}:${user}`, current]);
+        });
+    }
+    act(`write ${options.unitPath}${existsSync(options.unitPath) ? ` (previous unit kept as ${options.unitPath}.pre-launcher)` : ''}`, () => {
+        if (existsSync(options.unitPath) && !existsSync(`${options.unitPath}.pre-launcher`))
+            copyFileSync(options.unitPath, `${options.unitPath}.pre-launcher`);
+        writeFileSync(options.unitPath, renderUnit(options), { mode: 0o644 });
+    });
+    const unit = options.unitPath.split('/').pop();
+    act(`systemctl daemon-reload && systemctl enable ${unit}`, () => {
+        execFileSync('systemctl', ['daemon-reload']);
+        execFileSync('systemctl', ['enable', unit], { stdio: 'ignore' });
+    });
+    if (options.start)
+        act(`systemctl restart ${unit}`, () => execFileSync('systemctl', ['restart', unit]));
+    console.log(`${dryRun ? 'Would' : 'Done'}:\n${steps.map(step => `  - ${step}`).join('\n')}`);
+    if (!dryRun)
+        console.log(`The agent now runs ${version} through the launcher; the server can upgrade it from the Nodes page or with \`magnus-server agents upgrade\`.`);
+    return 0;
+}
+//# sourceMappingURL=install-service.js.map

package/dist/upgrade/routes.d.ts

@@ -0,0 +1,5 @@
+import { Hono } from 'hono';
+/** Seconds between the reply and the exit that hands over to the launcher. */
+export declare const RESTART_DELAY_MS = 3000;
+export declare const agentUpgradeRoutes: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=routes.d.ts.map

package/dist/upgrade/routes.js

@@ -0,0 +1,31 @@
+import { Hono } from 'hono';
+import { agentUpgradeRequestSchema } from '@hivemagnus/magnus-contracts';
+import { logger } from '../utils/logger.js';
+import { AGENT_VERSION } from '../version.js';
+import { SelfUpgradeError, selfUpgradeStatus, stageUpgrade } from './self-upgrade.js';
+/** Seconds between the reply and the exit that hands over to the launcher. */
+export const RESTART_DELAY_MS = 3_000;
+export const agentUpgradeRoutes = new Hono();
+agentUpgradeRoutes.get('/status', c => c.json({ success: true, data: selfUpgradeStatus(AGENT_VERSION) }));
+agentUpgradeRoutes.post('/', async (c) => {
+    const parsed = agentUpgradeRequestSchema.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+        return c.json({ success: false, error: { code: 'VALIDATION_ERROR', message: 'version, integrity (sha512-…) and requestId are required' } }, 400);
+    }
+    try {
+        const result = await stageUpgrade({ request: parsed.data, version: AGENT_VERSION });
+        logger.info(`Self-upgrade staged: ${result.from} -> ${result.to}; restarting through the launcher`);
+        // Reply first; the launcher starts versions/<to> on trial after this process exits.
+        setTimeout(() => process.kill(process.pid, 'SIGTERM'), RESTART_DELAY_MS).unref();
+        return c.json({ success: true, data: { accepted: true, ...result, restartInSeconds: RESTART_DELAY_MS / 1000 } });
+    }
+    catch (error) {
+        if (error instanceof SelfUpgradeError) {
+            logger.warn(`Self-upgrade to ${parsed.data.version} refused: ${error.message}`);
+            return c.json({ success: false, error: { code: error.code, message: error.message } }, error.status);
+        }
+        logger.error('Self-upgrade failed', { error: error instanceof Error ? error.message : String(error) });
+        return c.json({ success: false, error: { code: 'SELF_UPGRADE_FAILED', message: error instanceof Error ? error.message : String(error) } }, 500);
+    }
+});
+//# sourceMappingURL=routes.js.map

package/dist/upgrade/self-upgrade.d.ts

@@ -0,0 +1,65 @@
+import { type AgentSelfUpgradeStatus, type AgentUpgradeRequest } from '@hivemagnus/magnus-contracts';
+export declare const STATE_FILE = "upgrade-state.json";
+export declare const AGENT_PACKAGE = "@hivemagnus/magnus-agent";
+export interface UpgradeState {
+    state: 'idle' | 'staged' | 'trial' | 'confirmed' | 'reverted' | 'failed';
+    from: string | null;
+    to: string | null;
+    requestId: string | null;
+    attempt?: number;
+    maxAttempts?: number;
+    trialDeadline?: string;
+    reason?: string | null;
+    updatedAt?: string;
+}
+export declare function installDir(env?: NodeJS.ProcessEnv): string;
+export declare function readUpgradeState(dir: string): UpgradeState | null;
+export declare function writeUpgradeState(dir: string, state: UpgradeState): void;
+export declare function pointCurrentAt(dir: string, version: string): void;
+export type Layout = AgentSelfUpgradeStatus['layout'];
+export declare function detectLayout(dir: string, env?: NodeJS.ProcessEnv): Layout;
+/** Whether this agent can upgrade itself, and why not. Reported with every heartbeat. */
+export declare function selfUpgradeStatus(version: string, env?: NodeJS.ProcessEnv): AgentSelfUpgradeStatus;
+/**
+ * Called after every accepted heartbeat: the first one from a version on trial
+ * confirms it, and versions other than the previous and the current one are pruned.
+ */
+export declare function confirmTrial(version: string, env?: NodeJS.ProcessEnv, now?: Date): boolean;
+export declare function pruneVersions(dir: string, keep: ReadonlyArray<string | null>): void;
+export declare class SelfUpgradeError extends Error {
+    readonly code: string;
+    readonly status: 400 | 409 | 422 | 500;
+    constructor(code: string, message: string, status?: 400 | 409 | 422 | 500);
+}
+export interface Runner {
+    (command: string, args: readonly string[], options: {
+        cwd: string;
+        env: NodeJS.ProcessEnv;
+    }): Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export declare const runProcess: Runner;
+/** npm pack names files `<scope>-<name>-<version>.tgz`. */
+export declare function tarballName(version: string): string;
+export declare function sha512Integrity(file: string): string;
+/** Other @hivemagnus tarballs in the source directory, used instead of the registry (offline nodes). */
+export declare function sourceOverrides(sourceDir: string, agentTarball: string): Record<string, string>;
+export interface StageOptions {
+    request: AgentUpgradeRequest;
+    version: string;
+    env?: NodeJS.ProcessEnv;
+    run?: Runner;
+    now?: Date;
+}
+export interface StageResult {
+    from: string;
+    to: string;
+    integrity: string;
+    requestId: string;
+}
+/** Download, verify, install and switch. The caller exits afterwards so the launcher starts the new version. */
+export declare function stageUpgrade(options: StageOptions): Promise<StageResult>;
+//# sourceMappingURL=self-upgrade.d.ts.map

package/dist/upgrade/self-upgrade.js

@@ -0,0 +1,242 @@
+/**
+ * Agent self-upgrade (MAGNUS_AGENT_SELF_UPGRADE). The server asks for an exact
+ * version and its npm integrity; the agent downloads that tarball, checks it,
+ * installs it into versions/<X> beside the running one, points ./current at
+ * it and exits. The launcher (launcher/launcher.mjs, installed by
+ * `magnus-agent install-service`) starts the new version on trial and switches
+ * back if it does not report an accepted heartbeat in time. Nothing here uses
+ * sudo: the agent only writes inside its own install directory.
+ */
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { accessSync, constants, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { AGENT_SELF_UPGRADE_PROTOCOL, checkUpgradeAllowed, compareVersions, } from '@hivemagnus/magnus-contracts';
+export const STATE_FILE = 'upgrade-state.json';
+export const AGENT_PACKAGE = '@hivemagnus/magnus-agent';
+export function installDir(env = process.env) {
+    return resolve(env['AGENT_INSTALL_DIR'] ?? process.cwd());
+}
+export function readUpgradeState(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, STATE_FILE), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeUpgradeState(dir, state) {
+    const path = join(dir, STATE_FILE);
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, path);
+}
+export function pointCurrentAt(dir, version) {
+    const temporary = join(dir, `current.${process.pid}.tmp`);
+    rmSync(temporary, { force: true });
+    symlinkSync(join('versions', version), temporary, 'dir');
+    renameSync(temporary, join(dir, 'current'));
+}
+export function detectLayout(dir, env = process.env) {
+    if (env['MAGNUS_AGENT_CONTAINER'] === '1')
+        return 'container';
+    try {
+        if (env['MAGNUS_AGENT_LAUNCHER'] === '1' && lstatSync(join(dir, 'current')).isSymbolicLink())
+            return 'versioned';
+    }
+    catch {
+        // no ./current
+    }
+    return 'legacy';
+}
+function selfUpgradeSwitch(env) {
+    return (env['MAGNUS_AGENT_SELF_UPGRADE'] ?? 'true').trim().toLowerCase() !== 'false';
+}
+/** Whether this agent can upgrade itself, and why not. Reported with every heartbeat. */
+export function selfUpgradeStatus(version, env = process.env) {
+    const dir = installDir(env);
+    const layout = detectLayout(dir, env);
+    const launcherProtocol = Number.parseInt(env['MAGNUS_AGENT_LAUNCHER_PROTOCOL'] ?? '', 10);
+    const state = readUpgradeState(dir);
+    let reason = null;
+    if (!selfUpgradeSwitch(env))
+        reason = 'MAGNUS_AGENT_SELF_UPGRADE=false on this node';
+    else if (layout === 'container')
+        reason = 'container agent: upgrade by pulling a newer image';
+    else if (layout === 'legacy')
+        reason = 'not running under the upgrade launcher; run `sudo magnus-agent install-service` once on this node';
+    else {
+        try {
+            accessSync(dir, constants.W_OK);
+            accessSync(join(dir, 'versions'), constants.W_OK);
+        }
+        catch {
+            reason = `the agent cannot write ${dir}`;
+        }
+    }
+    return {
+        protocol: AGENT_SELF_UPGRADE_PROTOCOL,
+        launcherProtocol: Number.isInteger(launcherProtocol) ? launcherProtocol : null,
+        layout,
+        enabled: reason === null,
+        reason,
+        upgrade: state ? reportOf(state) : { state: 'idle', from: null, to: version },
+    };
+}
+function reportOf(state) {
+    return {
+        state: state.state, from: state.from, to: state.to, requestId: state.requestId, reason: state.reason ?? null,
+        ...(state.attempt !== undefined ? { attempt: state.attempt } : {}), ...(state.updatedAt ? { updatedAt: state.updatedAt } : {}),
+    };
+}
+/**
+ * Called after every accepted heartbeat: the first one from a version on trial
+ * confirms it, and versions other than the previous and the current one are pruned.
+ */
+export function confirmTrial(version, env = process.env, now = new Date()) {
+    const dir = installDir(env);
+    const state = readUpgradeState(dir);
+    if (!state || state.state !== 'trial' || state.to !== version)
+        return false;
+    writeUpgradeState(dir, { ...state, state: 'confirmed', reason: null, updatedAt: now.toISOString() });
+    pruneVersions(dir, [state.from, state.to]);
+    return true;
+}
+export function pruneVersions(dir, keep) {
+    const versions = join(dir, 'versions');
+    if (!existsSync(versions))
+        return;
+    for (const name of readdirSync(versions)) {
+        if (keep.includes(name))
+            continue;
+        rmSync(join(versions, name), { recursive: true, force: true });
+    }
+}
+export class SelfUpgradeError extends Error {
+    code;
+    status;
+    constructor(code, message, status = 409) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+export const runProcess = (command, args, options) => new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, { cwd: options.cwd, env: options.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', chunk => { stdout += String(chunk); });
+    child.stderr.on('data', chunk => { stderr += String(chunk); });
+    child.on('error', reject);
+    child.on('close', code => resolvePromise({ code: code ?? 1, stdout, stderr }));
+});
+/** npm pack names files `<scope>-<name>-<version>.tgz`. */
+export function tarballName(version) {
+    return `hivemagnus-magnus-agent-${version}.tgz`;
+}
+export function sha512Integrity(file) {
+    return `sha512-${createHash('sha512').update(readFileSync(file)).digest('base64')}`;
+}
+const ALLOW_SCRIPTS = { 'cpu-features': true, ssh2: true };
+const SOURCE_TARBALL = /^hivemagnus-(.+?)-(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\.tgz$/;
+/** Other @hivemagnus tarballs in the source directory, used instead of the registry (offline nodes). */
+export function sourceOverrides(sourceDir, agentTarball) {
+    const overrides = {};
+    for (const file of readdirSync(sourceDir)) {
+        const match = SOURCE_TARBALL.exec(file);
+        const path = join(sourceDir, file);
+        if (!match || path === agentTarball || match[1] === 'magnus-agent')
+            continue;
+        overrides[`@hivemagnus/${match[1]}`] = `file:${path}`;
+    }
+    return overrides;
+}
+let staging = false;
+/** Download, verify, install and switch. The caller exits afterwards so the launcher starts the new version. */
+export async function stageUpgrade(options) {
+    const env = options.env ?? process.env;
+    const run = options.run ?? runProcess;
+    const { request, version: from } = options;
+    const status = selfUpgradeStatus(from, env);
+    if (!status.enabled)
+        throw new SelfUpgradeError('SELF_UPGRADE_UNAVAILABLE', status.reason ?? 'self-upgrade is unavailable');
+    if (request.packageName !== AGENT_PACKAGE)
+        throw new SelfUpgradeError('SELF_UPGRADE_PACKAGE', `only ${AGENT_PACKAGE} can be installed`, 422);
+    if (compareVersions(request.version, from) === 0)
+        throw new SelfUpgradeError('SELF_UPGRADE_CURRENT', `already running ${from}`);
+    const decision = checkUpgradeAllowed(from, request.version);
+    if (!decision.allowed)
+        throw new SelfUpgradeError('SELF_UPGRADE_REFUSED', decision.reason ?? 'upgrade refused', 422);
+    const previous = status.upgrade?.state;
+    if (previous === 'staged' || previous === 'trial')
+        throw new SelfUpgradeError('SELF_UPGRADE_BUSY', `an upgrade to ${status.upgrade?.to} is still on trial`);
+    if (staging)
+        throw new SelfUpgradeError('SELF_UPGRADE_BUSY', 'an upgrade is already being staged');
+    staging = true;
+    const dir = installDir(env);
+    const work = join(dir, 'staging', request.version);
+    const target = join(dir, 'versions', request.version);
+    try {
+        rmSync(work, { recursive: true, force: true });
+        mkdirSync(work, { recursive: true, mode: 0o700 });
+        const npm = env['MAGNUS_AGENT_NPM'] || 'npm';
+        const npmEnv = { ...env, npm_config_cache: env['npm_config_cache'] ?? join(dir, '.npm'), npm_config_update_notifier: 'false' };
+        const fail = (step, result) => {
+            throw new SelfUpgradeError('SELF_UPGRADE_FAILED', `${step} failed (exit ${result.code}): ${(result.stderr || result.stdout).trim().split('\n').slice(-3).join(' ')}`, 500);
+        };
+        // 1. The exact tarball: from an operator-provided directory, or the registry.
+        const sourceDir = env['MAGNUS_AGENT_UPGRADE_SOURCE_DIR']?.trim();
+        let tarball;
+        if (sourceDir) {
+            tarball = join(resolve(sourceDir), tarballName(request.version));
+            if (!existsSync(tarball))
+                throw new SelfUpgradeError('SELF_UPGRADE_SOURCE', `${tarball} does not exist`, 422);
+        }
+        else {
+            const packed = await run(npm, ['pack', `${AGENT_PACKAGE}@${request.version}`, '--pack-destination', work, '--json', '--loglevel=error'], { cwd: work, env: npmEnv });
+            if (packed.code !== 0)
+                fail('npm pack', packed);
+            tarball = join(work, tarballName(request.version));
+        }
+        // 2. The bytes must match what the server pinned (npm also checks the registry's own digest on download).
+        const integrity = sha512Integrity(tarball);
+        if (integrity !== request.integrity) {
+            throw new SelfUpgradeError('SELF_UPGRADE_INTEGRITY', `tarball integrity ${integrity.slice(0, 20)}… differs from the requested ${request.integrity.slice(0, 20)}…`, 422);
+        }
+        // 3. Install beside the running version.
+        const install = join(work, 'install');
+        mkdirSync(install, { recursive: true });
+        const overrides = sourceDir ? sourceOverrides(resolve(sourceDir), tarball) : {};
+        writeFileSync(join(install, 'package.json'), `${JSON.stringify({
+            name: `magnus-agent-${request.version}`, version: request.version, private: true, type: 'module',
+            dependencies: { [AGENT_PACKAGE]: `file:${tarball}` }, ...(Object.keys(overrides).length ? { overrides } : {}), allowScripts: ALLOW_SCRIPTS,
+        }, null, 2)}\n`);
+        const installed = await run(npm, ['install', '--omit=dev', '--no-audit', '--no-fund', '--loglevel=error'], { cwd: install, env: npmEnv });
+        if (installed.code !== 0)
+            fail('npm install', installed);
+        // 4. Registry signatures and provenance of everything installed.
+        if ((env['MAGNUS_AGENT_UPGRADE_REQUIRE_PROVENANCE'] ?? 'true').trim().toLowerCase() !== 'false') {
+            const audit = await run(npm, ['audit', 'signatures', '--omit=dev', '--loglevel=error'], { cwd: install, env: npmEnv });
+            if (audit.code !== 0)
+                fail('npm audit signatures', audit);
+        }
+        // 5. The new code must at least start and report the requested version.
+        const entry = join(install, 'node_modules', '@hivemagnus', 'magnus-agent', 'dist', 'index.js');
+        const smoke = await run(process.execPath, [entry, '--version'], { cwd: install, env });
+        if (smoke.code !== 0 || smoke.stdout.trim() !== request.version) {
+            throw new SelfUpgradeError('SELF_UPGRADE_FAILED', `the installed agent reports "${smoke.stdout.trim()}", not ${request.version}`, 500);
+        }
+        rmSync(target, { recursive: true, force: true });
+        mkdirSync(join(dir, 'versions'), { recursive: true });
+        renameSync(install, target);
+        const now = (options.now ?? new Date()).toISOString();
+        writeUpgradeState(dir, { state: 'staged', from, to: request.version, requestId: request.requestId, attempt: 0, maxAttempts: 2, reason: null, updatedAt: now });
+        pointCurrentAt(dir, request.version);
+        return { from, to: request.version, integrity, requestId: request.requestId };
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+        staging = false;
+    }
+}
+//# sourceMappingURL=self-upgrade.js.map

package/launcher/launcher.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * magnus-agent launcher: the stable process systemd starts. It runs the agent
+ * from ./current and guards self-upgrades:
+ *
+ *   staged     the agent installed versions/<to>, pointed ./current at it and exited
+ *   trial      the new version runs; it must report one accepted heartbeat
+ *              (state "confirmed") before the deadline
+ *   confirmed  done
+ *   reverted   the trial failed (crash loop or no heartbeat in time); ./current
+ *              points back at versions/<from>
+ *
+ * The launcher has no dependencies and never changes during an upgrade; only
+ * `magnus-agent install-service` replaces it. It never escalates privileges.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, renameSync, rmSync, symlinkSync, writeFileSync, openSync, fsyncSync, closeSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+export const LAUNCHER_PROTOCOL = 1;
+export const STATE_FILE = 'upgrade-state.json';
+const POLL_MS = 2_000;
+
+/**
+ * Pure decision for one launch.
+ * @param {null | Record<string, any>} state
+ * @param {number} now epoch ms
+ * @param {number} confirmMs trial window
+ * @returns {{ action: 'run' | 'revert', next: Record<string, any> | null, trial: boolean, reason?: string }}
+ */
+export function decideLaunch(state, now, confirmMs) {
+  if (!state || typeof state !== 'object') return { action: 'run', next: null, trial: false };
+  const maxAttempts = Number.isInteger(state.maxAttempts) && state.maxAttempts > 0 ? state.maxAttempts : 2;
+  const stamp = new Date(now).toISOString();
+  if (state.state === 'staged') {
+    return { action: 'run', trial: true,
+      next: { ...state, state: 'trial', attempt: 1, maxAttempts, trialDeadline: new Date(now + confirmMs).toISOString(), updatedAt: stamp } };
+  }
+  if (state.state === 'trial') {
+    const deadline = Date.parse(state.trialDeadline ?? '');
+    const attempt = Number.isInteger(state.attempt) ? state.attempt : maxAttempts;
+    if (!Number.isFinite(deadline) || now >= deadline) {
+      return { action: 'revert', trial: false, reason: `no confirmed heartbeat from ${state.to} within ${Math.round(confirmMs / 1000)} s`,
+        next: { ...state, state: 'reverted', updatedAt: stamp } };
+    }
+    if (attempt >= maxAttempts) {
+      return { action: 'revert', trial: false, reason: `${state.to} exited ${attempt} time(s) before reporting a heartbeat`,
+        next: { ...state, state: 'reverted', updatedAt: stamp } };
+    }
+    return { action: 'run', trial: true, next: { ...state, attempt: attempt + 1, updatedAt: stamp } };
+  }
+  return { action: 'run', next: null, trial: false };
+}
+
+export function readState(dir) {
+  try {
+    return JSON.parse(readFileSync(join(dir, STATE_FILE), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeState(dir, state) {
+  const path = join(dir, STATE_FILE);
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  const fd = openSync(temporary, 'r');
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+  renameSync(temporary, path);
+}
+
+export function pointCurrentAt(dir, version) {
+  const temporary = join(dir, `current.${process.pid}.tmp`);
+  rmSync(temporary, { force: true });
+  symlinkSync(join('versions', version), temporary, 'dir');
+  renameSync(temporary, join(dir, 'current'));
+}
+
+function revert(dir, decision) {
+  const state = decision.next;
+  if (state.from && existsSync(join(dir, 'versions', state.from))) pointCurrentAt(dir, state.from);
+  else state.reason = `${decision.reason}; versions/${state.from} is missing, so ./current was left as it is`;
+  writeState(dir, { ...state, reason: state.reason ?? decision.reason });
+  console.error(`[launcher] reverted ${state.to} -> ${state.from}: ${decision.reason}`);
+}
+
+export function confirmSeconds(env) {
+  const value = Number.parseInt(env.MAGNUS_AGENT_UPGRADE_CONFIRM_SECONDS ?? '', 10);
+  return Number.isInteger(value) && value >= 10 ? Math.min(value, 3600) : 180;
+}
+
+function main() {
+  const dir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  const confirmMs = confirmSeconds(process.env) * 1000;
+  const decision = decideLaunch(readState(dir), Date.now(), confirmMs);
+  if (decision.action === 'revert') revert(dir, decision);
+  else if (decision.next) writeState(dir, decision.next);
+
+  const entry = join(dir, 'current', 'node_modules', '@hivemagnus', 'magnus-agent', 'dist', 'index.js');
+  if (!existsSync(entry)) {
+    console.error(`[launcher] ${entry} is missing; reinstall with magnus-agent install-service`);
+    process.exit(1);
+  }
+  const child = spawn(process.execPath, [entry, 'start'], {
+    cwd: dir,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      AGENT_INSTALL_DIR: process.env.AGENT_INSTALL_DIR ?? dir,
+      MAGNUS_AGENT_LAUNCHER: '1',
+      MAGNUS_AGENT_LAUNCHER_PROTOCOL: String(LAUNCHER_PROTOCOL),
+    },
+  });
+  for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, () => child.kill(signal));
+
+  let failedTrial = false;
+  let watcher;
+  if (decision.trial) {
+    watcher = setInterval(() => {
+      const state = readState(dir);
+      if (!state || state.state !== 'trial') { clearInterval(watcher); return; }
+      const verdict = decideLaunch({ ...state, attempt: 0 }, Date.now(), confirmMs);
+      if (verdict.action === 'revert') {
+        clearInterval(watcher);
+        failedTrial = true;
+        revert(dir, verdict);
+        child.kill('SIGTERM');
+        setTimeout(() => child.kill('SIGKILL'), 10_000).unref();
+      }
+    }, POLL_MS);
+  }
+  child.on('exit', (code, signal) => {
+    if (watcher) clearInterval(watcher);
+    // Any exit restarts through systemd (Restart=always); a failed trial exits non-zero.
+    process.exit(failedTrial ? 1 : code ?? (signal ? 1 : 0));
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemagnus/magnus-agent",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Magnus node agent: a small daemon that enrolls a Linux host with a magnus-server and runs authenticated health, command, cron, file and skill management, with optional Hermes Agent, Codex and Ardent management.",
   "keywords": [
     "magnus",
@@ -36,7 +36,8 @@
     "LICENSE",
     ".env.example",
     "deploy/*.service",
-    "deploy/*.timer"
+    "deploy/*.timer",
+    "launcher/launcher.mjs"
   ],
   "engines": {
     "node": "^24.22.1 || ^26.13.0"
@@ -54,6 +55,7 @@
     "clean": "node -e \"const fs=require('node:fs');fs.rmSync('dist',{recursive:true,force:true});fs.rmSync('tsconfig.tsbuildinfo',{force:true})\""
   },
   "dependencies": {
+    "@hivemagnus/magnus-contracts": "1.1.0",
     "@hono/node-server": "^2.1.5",
     "dotenv": "^18.0.9",
     "hono": "^4.13.14",