@hivemagnus/magnus-server 1.0.3 → 1.1.1

package/dist/services/agent-upgrade-service.js

@@ -0,0 +1,293 @@
+/**
+ * Server-driven agent upgrades (MAGNUS_AGENT_UPGRADES). The server pins one
+ * exact version and its npm integrity, asks one canary agent to stage it,
+ * waits until that agent reports the version on trial as confirmed, then
+ * upgrades the rest a few at a time. The first revert or failure stops the
+ * run. Agents decide for themselves whether they can upgrade
+ * (MAGNUS_AGENT_SELF_UPGRADE, launcher layout) and report it with every
+ * heartbeat, so the console can grey out the ones that cannot.
+ */
+import { randomUUID } from 'node:crypto';
+import { AGENT_SELF_UPGRADE_PROTOCOL, agentSelfUpgradeStatusSchema, checkUpgradeAllowed, compareVersions, isVersion, } from '@hivemagnus/magnus-contracts';
+import { upgradeSettings } from '../config/features.js';
+import { AGENT_VERSION } from '../config/version.js';
+import { getDb } from '../db/client.js';
+import { HttpError } from '../middleware/error-handler.js';
+import { NodeApiClient } from '../sdk/node-api-client.js';
+import { getNodeManagerSecret } from '../utils/env.js';
+import { getNodeBaseUrl } from '../utils/node-url.js';
+import { SENTINEL_NODE_IDS } from '../utils/sentinel-nodes.js';
+import { logAuditEvent } from './audit-service.js';
+export const AGENT_PACKAGE = '@hivemagnus/magnus-agent';
+/** Heartbeats are 30 s apart; older than this and the node counts as offline for upgrades. */
+const FRESH_HEARTBEAT_MS = 2 * 60_000;
+/** Install time plus the agent's confirmation window (default 180 s), with margin. */
+const CONFIRM_TIMEOUT_MS = 20 * 60_000;
+const POLL_MS = 5_000;
+const RUN_TTL_SECONDS = 7 * 24 * 60 * 60;
+function parseMetadata(raw) {
+    try {
+        const parsed = JSON.parse(raw ?? '{}');
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function storedSelfUpgrade(metadataRaw) {
+    const value = parseMetadata(metadataRaw)['agentSelfUpgrade'];
+    const parsed = agentSelfUpgradeStatusSchema.safeParse(value);
+    if (!parsed.success)
+        return null;
+    const extra = value;
+    return { ...parsed.data, nodeVersion: typeof extra.nodeVersion === 'string' ? extra.nodeVersion : null,
+        observedAt: typeof extra.observedAt === 'string' ? extra.observedAt : new Date(0).toISOString() };
+}
+/**
+ * Store the self-upgrade report from a heartbeat, keep Agent.status in step
+ * (UPDATING while a version is staged or on trial) and audit each revert once.
+ */
+export async function recordSelfUpgradeReport(node, body) {
+    const parsed = agentSelfUpgradeStatusSchema.safeParse(body.selfUpgrade);
+    if (!parsed.success)
+        return;
+    const db = getDb();
+    const row = await db.node.findUnique({ where: { id: node.id }, select: { metadata: true } });
+    const metadata = parseMetadata(row?.metadata);
+    const previous = storedSelfUpgrade(row?.metadata);
+    const nodeVersion = typeof body.nodeVersion === 'string' ? body.nodeVersion.slice(0, 32) : null;
+    const next = { ...parsed.data, nodeVersion, observedAt: new Date().toISOString() };
+    const unchanged = previous && JSON.stringify({ ...previous, observedAt: '' }) === JSON.stringify({ ...next, observedAt: '' })
+        && Date.now() - Date.parse(previous.observedAt) < 10 * 60_000;
+    if (!unchanged) {
+        await db.node.update({ where: { id: node.id }, data: { metadata: JSON.stringify({ ...metadata, agentSelfUpgrade: next, nodeVersion }) } });
+    }
+    const state = parsed.data.upgrade?.state;
+    const updating = state === 'staged' || state === 'trial';
+    await db.agent.updateMany({
+        where: { nodeId: node.id, status: updating ? { not: 'UPDATING' } : 'UPDATING' },
+        data: { status: updating ? 'UPDATING' : 'RUNNING' },
+    });
+    const upgrade = parsed.data.upgrade;
+    if (upgrade && (upgrade.state === 'reverted' || upgrade.state === 'confirmed')
+        && upgrade.requestId && previous?.upgrade?.requestId === upgrade.requestId && previous.upgrade.state !== upgrade.state) {
+        await logAuditEvent({
+            action: upgrade.state === 'reverted' ? 'agent.upgrade_reverted' : 'agent.upgrade',
+            actorId: 'system:agent-upgrade', actorType: 'system', targetType: 'node', targetId: node.id,
+            details: { node: node.name, from: upgrade.from, to: upgrade.to, requestId: upgrade.requestId, result: upgrade.state, reason: upgrade.reason ?? null },
+        }).catch(() => undefined);
+    }
+}
+/** The exact version (default: the one this server ships) and its npm integrity. */
+export async function resolveAgentRelease(options = {}) {
+    const version = options.version ?? AGENT_VERSION;
+    if (!isVersion(version))
+        throw new HttpError(400, 'INVALID_VERSION', `${version} is not an X.Y.Z version`);
+    if (options.integrity) {
+        if (!/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(options.integrity))
+            throw new HttpError(400, 'INVALID_INTEGRITY', 'integrity must be sha512-<base64>');
+        return { version, integrity: options.integrity };
+    }
+    const registry = upgradeSettings().updateRegistry;
+    const url = `${registry}/${AGENT_PACKAGE.replace('/', '%2f')}/${version}`;
+    let response;
+    try {
+        response = await (options.fetchImpl ?? fetch)(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(15_000) });
+    }
+    catch (error) {
+        throw new HttpError(502, 'REGISTRY_UNREACHABLE', `Cannot read ${AGENT_PACKAGE}@${version} from ${registry}: ${error instanceof Error ? error.message : String(error)}. Pass the integrity explicitly for offline installs.`);
+    }
+    if (response.status === 404)
+        throw new HttpError(404, 'AGENT_VERSION_NOT_PUBLISHED', `${AGENT_PACKAGE}@${version} is not published on ${registry}`);
+    if (!response.ok)
+        throw new HttpError(502, 'REGISTRY_ERROR', `${registry} answered ${response.status} for ${AGENT_PACKAGE}@${version}`);
+    const document = await response.json();
+    const integrity = document.dist?.integrity;
+    if (!integrity?.startsWith('sha512-'))
+        throw new HttpError(502, 'REGISTRY_ERROR', `${AGENT_PACKAGE}@${version} has no sha512 integrity`);
+    return { version, integrity };
+}
+/** Pure, for tests: why one node can or cannot take `target` now. */
+export function classifyCandidate(row, target, now = Date.now()) {
+    const version = row.agent?.version ?? 'unknown';
+    const report = storedSelfUpgrade(row.metadata);
+    const base = { nodeId: row.id, name: row.name, version, upgrade: report?.upgrade ?? null, layout: report?.layout ?? null };
+    const no = (reason) => ({ ...base, eligible: false, reason });
+    if (row.status !== 'ONLINE' || !row.lastHeartbeatAt || now - row.lastHeartbeatAt.getTime() > FRESH_HEARTBEAT_MS)
+        return no('offline or no recent heartbeat');
+    if (!isVersion(version))
+        return no('agent version unknown');
+    if (compareVersions(version, target) === 0)
+        return no('already on this version');
+    const decision = checkUpgradeAllowed(version, target);
+    if (!decision.allowed)
+        return no(decision.kind === 'downgrade' ? `runs ${version}, newer than ${target}` : `${version} -> ${target} crosses a major version; upgrade this node by hand`);
+    if (!report)
+        return no(`magnus-agent ${version} cannot upgrade itself (needs 1.1.0 or later and \`sudo magnus-agent install-service\`)`);
+    if (report.protocol < AGENT_SELF_UPGRADE_PROTOCOL)
+        return no('agent self-upgrade protocol too old');
+    if (!report.enabled)
+        return no(report.reason ?? 'self-upgrade disabled on this node');
+    if (report.upgrade && (report.upgrade.state === 'staged' || report.upgrade.state === 'trial'))
+        return no(`an upgrade to ${report.upgrade.to} is in progress`);
+    return { ...base, eligible: true, reason: null };
+}
+export async function listUpgradeCandidates(target, nodeIds) {
+    const rows = await getDb().node.findMany({
+        where: { id: { notIn: SENTINEL_NODE_IDS, ...(nodeIds?.length ? { in: [...nodeIds] } : {}) }, status: { not: 'DECOMMISSIONED' } },
+        select: { id: true, name: true, status: true, lastHeartbeatAt: true, metadata: true, agent: { select: { version: true } } },
+        orderBy: { name: 'asc' },
+    });
+    return rows.map(row => classifyCandidate(row, target));
+}
+const runs = new Map();
+async function saveRun(run) {
+    runs.set(run.id, run);
+    try {
+        const { getRedis } = await import('../queue/redis.js');
+        await getRedis().set(`agent-upgrade-run:${run.id}`, JSON.stringify(run), 'EX', RUN_TTL_SECONDS);
+        await getRedis().set('agent-upgrade-run:latest', run.id, 'EX', RUN_TTL_SECONDS);
+    }
+    catch {
+        // in-memory only
+    }
+}
+export async function getUpgradeRun(id) {
+    const local = runs.get(id);
+    if (local)
+        return local;
+    try {
+        const { getRedis } = await import('../queue/redis.js');
+        const raw = await getRedis().get(`agent-upgrade-run:${id}`);
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function latestUpgradeRun() {
+    try {
+        const { getRedis } = await import('../queue/redis.js');
+        const id = await getRedis().get('agent-upgrade-run:latest');
+        return id ? getUpgradeRun(id) : null;
+    }
+    catch {
+        return [...runs.values()].at(-1) ?? null;
+    }
+}
+function clientFor(node) {
+    return new NodeApiClient({ baseUrl: getNodeBaseUrl(node.ipAddress, node.port), resourceNodeId: node.id, nodeToken: getNodeManagerSecret(),
+        timeout: 15 * 60_000 });
+}
+export function defaultDeps() {
+    return {
+        request: async (nodeId, body) => {
+            const node = await getDb().node.findUniqueOrThrow({ where: { id: nodeId }, select: { id: true, ipAddress: true, port: true } });
+            await clientFor(node).upgradeAgent(body);
+        },
+        observe: async (nodeId) => {
+            const row = await getDb().node.findUnique({ where: { id: nodeId }, select: { metadata: true, agent: { select: { version: true } } } });
+            return { version: row?.agent?.version ?? null, report: storedSelfUpgrade(row?.metadata) };
+        },
+        sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+        now: () => Date.now(),
+        save: saveRun,
+        confirmTimeoutMs: CONFIRM_TIMEOUT_MS,
+        pollMs: POLL_MS,
+    };
+}
+/** Ask one node to upgrade and wait for its confirmed (or reverted) report. */
+async function upgradeOne(run, entry, deps) {
+    entry.state = 'requested';
+    await deps.save(run);
+    try {
+        await deps.request(entry.nodeId, { version: run.version, integrity: run.integrity, requestId: entry.requestId, packageName: AGENT_PACKAGE });
+    }
+    catch (error) {
+        entry.state = 'failed';
+        entry.detail = (error instanceof Error ? error.message : String(error)).slice(0, 500);
+        return;
+    }
+    const deadline = deps.now() + deps.confirmTimeoutMs;
+    while (deps.now() < deadline) {
+        await deps.sleep(deps.pollMs);
+        const { version, report } = await deps.observe(entry.nodeId);
+        const upgrade = report?.upgrade;
+        if (upgrade?.requestId === entry.requestId && upgrade.state === 'reverted') {
+            entry.state = 'reverted';
+            entry.detail = upgrade.reason ?? 'the agent switched back to its previous version';
+            return;
+        }
+        if (version === run.version && (upgrade?.requestId !== entry.requestId || upgrade.state === 'confirmed')) {
+            entry.state = 'confirmed';
+            entry.detail = null;
+            return;
+        }
+    }
+    entry.state = 'failed';
+    entry.detail = `no confirmation within ${Math.round(deps.confirmTimeoutMs / 60_000)} min`;
+}
+/** Canary first, then batches of `concurrency`. Stops at the first node that does not confirm. */
+export async function executeUpgradeRun(run, deps) {
+    const queue = run.nodes.filter(node => node.state === 'pending');
+    const [canary, ...rest] = queue;
+    const finish = async (status, message) => {
+        for (const node of run.nodes)
+            if (node.state === 'pending')
+                node.state = 'skipped';
+        run.status = status;
+        run.message = message;
+        run.finishedAt = new Date(deps.now()).toISOString();
+        await deps.save(run);
+        return run;
+    };
+    if (!canary)
+        return finish('succeeded', 'no eligible nodes');
+    await upgradeOne(run, canary, deps);
+    await deps.save(run);
+    if (canary.state !== 'confirmed')
+        return finish('failed', `canary ${canary.name} did not confirm (${canary.state}: ${canary.detail ?? ''}); the other nodes were not touched`);
+    for (let index = 0; index < rest.length; index += run.concurrency) {
+        const batch = rest.slice(index, index + run.concurrency);
+        await Promise.all(batch.map(node => upgradeOne(run, node, deps)));
+        await deps.save(run);
+        const bad = batch.find(node => node.state !== 'confirmed');
+        if (bad)
+            return finish('failed', `${bad.name} did not confirm (${bad.state}: ${bad.detail ?? ''}); remaining nodes were skipped`);
+    }
+    return finish('succeeded', `${run.nodes.filter(node => node.state === 'confirmed').length} agent(s) upgraded to ${run.version}`);
+}
+/** Validate, create the run and start it in the background. */
+export async function startUpgradeRun(options) {
+    const settings = upgradeSettings();
+    if (!settings.agentUpgrades)
+        throw new HttpError(403, 'AGENT_UPGRADES_DISABLED', 'Server-driven agent upgrades are off (MAGNUS_AGENT_UPGRADES=false)');
+    const release = await resolveAgentRelease({ version: options.version, integrity: options.integrity });
+    const candidates = await listUpgradeCandidates(release.version, options.nodeIds);
+    const eligible = candidates.filter(candidate => candidate.eligible);
+    if (eligible.length === 0) {
+        const reasons = candidates.slice(0, 5).map(candidate => `${candidate.name}: ${candidate.reason}`).join('; ');
+        throw new HttpError(409, 'NO_ELIGIBLE_AGENTS', `No selected agent can be upgraded now${reasons ? ` (${reasons})` : ''}`);
+    }
+    const running = await latestUpgradeRun();
+    if (running?.status === 'running')
+        throw new HttpError(409, 'AGENT_UPGRADE_RUNNING', `Upgrade run ${running.id} is still in progress`);
+    const run = {
+        id: randomUUID(), version: release.version, integrity: release.integrity, actorId: options.actorId, status: 'running',
+        startedAt: new Date().toISOString(), finishedAt: null, concurrency: settings.agentUpgradeConcurrency, message: null,
+        nodes: eligible.map(candidate => ({ nodeId: candidate.nodeId, name: candidate.name, from: candidate.version, state: 'pending', requestId: randomUUID(), detail: null })),
+    };
+    const deps = options.deps ?? defaultDeps();
+    await deps.save(run);
+    await logAuditEvent({ action: 'agent.upgrade', actorId: options.actorId, targetType: 'fleet', targetId: run.id,
+        details: { version: run.version, nodes: run.nodes.map(node => node.name) } }).catch(() => undefined);
+    const done = executeUpgradeRun(run, deps).catch(async (error) => {
+        run.status = 'failed';
+        run.message = error instanceof Error ? error.message : String(error);
+        run.finishedAt = new Date().toISOString();
+        await deps.save(run);
+        return run;
+    });
+    return { run, candidates, done };
+}
+//# sourceMappingURL=agent-upgrade-service.js.map

package/dist/services/agent-version-warnings.js

@@ -0,0 +1,31 @@
+import { compareVersions, isVersion } from '@hivemagnus/magnus-contracts';
+import { agentFixCommand } from './update-check-service.js';
+export function agentVersionStatus(agentVersion, expected) {
+    if (!agentVersion || !isVersion(agentVersion) || !isVersion(expected))
+        return { updateAvailable: false, relation: 'unknown' };
+    const order = compareVersions(agentVersion, expected);
+    return { updateAvailable: order < 0, relation: order === 0 ? 'current' : order < 0 ? 'behind' : 'ahead' };
+}
+const warned = new Map();
+/**
+ * One loud log line per node and version pair, with the exact fix. Mixed
+ * versions work within a major, but features and fixes need matching agents.
+ */
+export function warnOnAgentVersionMismatch(node, agentVersion, expected, log = line => console.warn(line)) {
+    const status = agentVersionStatus(agentVersion, expected);
+    if (status.relation !== 'behind' && status.relation !== 'ahead') {
+        warned.delete(node.id);
+        return status;
+    }
+    const key = `${agentVersion}->${expected}`;
+    if (warned.get(node.id) === key)
+        return status;
+    warned.set(node.id, key);
+    const major = agentVersion.split('.')[0] !== expected.split('.')[0];
+    log(status.relation === 'behind'
+        ? `[agents] VERSION MISMATCH: node ${node.name} runs magnus-agent ${agentVersion}, this server ships ${expected}`
+            + `${major ? ' (different major version: some features will not work)' : ''}. Fix: ${agentFixCommand([node.name])}`
+        : `[agents] VERSION MISMATCH: node ${node.name} runs magnus-agent ${agentVersion}, newer than this server (${expected}). Upgrade the server: magnus upgrade`);
+    return status;
+}
+//# sourceMappingURL=agent-version-warnings.js.map

package/dist/services/self-update-service.js

@@ -24,16 +24,17 @@ export async function isGitRepo() {
     }
 }
 let lastChecked = null;
-/** Read the current version directly from the version.ts source file on disk. */
+/** Read the versions from the package files on disk (they change after a pull and rebuild). */
 async function readVersionFromDisk() {
-    const versionFile = path.join(REPO_ROOT, 'src/config/version.ts');
-    const content = await readFile(versionFile, 'utf-8');
-    const agentMatch = content.match(/AGENT_VERSION\s*=\s*'([^']+)'/);
-    const controlMatch = content.match(/CONTROL_API_VERSION\s*=\s*'([^']+)'/);
-    return {
-        agent: agentMatch?.[1] ?? 'unknown',
-        controlApi: controlMatch?.[1] ?? 'unknown',
+    const read = async (file) => {
+        try {
+            return JSON.parse(await readFile(path.join(REPO_ROOT, file), 'utf-8')).version ?? 'unknown';
+        }
+        catch {
+            return 'unknown';
+        }
     };
+    return { agent: await read('agent-version.json'), controlApi: await read('package.json') };
 }
 /** Run a git command in the repo root. */
 async function git(...args) {
@@ -195,6 +196,8 @@ export async function getUpdateStatus() {
         gitCommit: commit,
         lastChecked,
         isGitRepo: gitRepo,
+        legacyGitSelfUpdate: (await import('../config/features.js')).upgradeSettings().legacyGitSelfUpdate,
+        upgradeCommand: 'magnus upgrade',
     };
 }
 //# sourceMappingURL=self-update-service.js.map

package/dist/services/update-check-service.js

@@ -0,0 +1,178 @@
+/**
+ * Opt-out update notices (MAGNUS_UPDATE_CHECK). Once a day the server reads
+ * the npm registry document of @hivemagnus/magnus (one anonymous GET; nothing
+ * about this install is sent) and summarizes the releases between the running
+ * version and the newest one of the same major: release notes, new required
+ * settings and migrations that are slow or one-way. A newer major is reported
+ * separately and never offered as a one-click upgrade.
+ */
+import { compareVersions, isVersion, latestVersion, manifestsFromPackument, summarizeUpgradePath, } from '@hivemagnus/magnus-contracts';
+import { upgradeSettings } from '../config/features.js';
+import { AGENT_VERSION, CONTROL_API_VERSION } from '../config/version.js';
+export const META_PACKAGE = '@hivemagnus/magnus';
+const DAY_MS = 24 * 60 * 60 * 1000;
+const CACHE_KEY = 'update-check:v1';
+export function emptyResult(enabled, error = null) {
+    return {
+        enabled, checkedAt: null, error, current: CONTROL_API_VERSION, latest: null, latestMajor: null, updateAvailable: false,
+        breaking: false, releases: [], newRequiredEnv: [], attention: [], command: 'magnus upgrade',
+    };
+}
+export function summarizePackument(packument, current, env, checkedAt) {
+    const versions = Object.keys(packument?.versions ?? {}).filter(isVersion);
+    const manifests = manifestsFromPackument(packument);
+    const sameMajor = latestVersion(versions, { sameMajorAs: current });
+    const newest = latestVersion(versions);
+    const latest = sameMajor && compareVersions(sameMajor, current) > 0 ? sameMajor : null;
+    const latestMajor = newest && compareVersions(newest, current) > 0 && newest.split('.')[0] !== current.split('.')[0] ? newest : null;
+    const path = latest ? summarizeUpgradePath(manifests, current, latest) : null;
+    return {
+        enabled: true,
+        checkedAt,
+        error: null,
+        current,
+        latest,
+        latestMajor,
+        updateAvailable: latest !== null,
+        breaking: path?.breaking ?? false,
+        releases: (path?.releases ?? []).map(release => ({
+            version: release.version, summary: release.summary, notesUrl: release.notesUrl ?? null, breaking: release.breaking,
+        })),
+        newRequiredEnv: (path?.newRequiredEnv ?? []).map(variable => ({
+            name: variable.name, component: variable.component, secret: variable.secret, description: variable.description,
+            missingOnServer: variable.component === 'server' && !env[variable.name],
+        })),
+        attention: (path?.attention ?? []).map(migration => ({ name: migration.name, impact: migration.impact, note: migration.note, version: migration.version })),
+        command: latest ? `magnus upgrade --to ${latest}` : 'magnus upgrade',
+    };
+}
+/** One registry read. Errors are reported in the result, never thrown. */
+export async function checkForUpdate(options = {}) {
+    const env = options.env ?? process.env;
+    const settings = upgradeSettings(env);
+    const current = options.current ?? CONTROL_API_VERSION;
+    if (!settings.updateCheck)
+        return { ...emptyResult(false), current };
+    const url = `${settings.updateRegistry}/${META_PACKAGE.replace('/', '%2f')}`;
+    const checkedAt = (options.now ?? (() => new Date()))().toISOString();
+    try {
+        const response = await (options.fetchImpl ?? fetch)(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(15_000) });
+        if (response.status === 404)
+            return { ...emptyResult(true), current, checkedAt };
+        if (!response.ok)
+            return { ...emptyResult(true, `registry answered ${response.status}`), current, checkedAt };
+        return summarizePackument(await response.json(), current, env, checkedAt);
+    }
+    catch (error) {
+        return { ...emptyResult(true, `registry unreachable: ${error instanceof Error ? error.message : String(error)}`), current, checkedAt };
+    }
+}
+/** The `updates` line of `check`: never a failure, only a notice. */
+export function updateResult(update) {
+    if (!update.enabled)
+        return { name: 'updates', status: 'pass', message: 'registry check off (MAGNUS_UPDATE_CHECK=false)' };
+    if (update.error)
+        return { name: 'updates', status: 'warn', message: `could not check: ${update.error}` };
+    const major = update.latestMajor ? `; ${update.latestMajor} is a new major version (see UPGRADING.md)` : '';
+    if (!update.updateAvailable)
+        return { name: 'updates', status: 'pass', message: `${update.current} is the newest ${update.current.split('.')[0]}.x release${major}` };
+    const env = update.newRequiredEnv.map(variable => `${variable.name}${variable.missingOnServer ? ' (not set here)' : ''}`);
+    return {
+        name: 'updates',
+        status: 'warn',
+        message: `${update.latest} is available: ${update.command}`
+            + (env.length ? `; new required settings: ${env.join(', ')}` : '')
+            + (update.attention.length ? `; slow or one-way migrations: ${update.attention.map(m => `${m.name} (${m.impact})`).join(', ')}` : '')
+            + major,
+    };
+}
+let cached = null;
+let timer;
+async function redis() {
+    const { getRedis } = await import('../queue/redis.js');
+    return getRedis();
+}
+async function store(result) {
+    cached = result;
+    try {
+        await (await redis()).set(CACHE_KEY, JSON.stringify(result), 'PX', DAY_MS + 60 * 60 * 1000);
+    }
+    catch {
+        // The in-memory copy is enough; Redis only shares the result across restarts.
+    }
+}
+/** Latest known result; refreshes when there is none yet or `refresh` is set. */
+export async function getUpdateCheck(options = {}) {
+    if (!upgradeSettings().updateCheck)
+        return emptyResult(false);
+    if (!options.refresh) {
+        if (cached && cached.current === CONTROL_API_VERSION)
+            return cached;
+        try {
+            const raw = await (await redis()).get(CACHE_KEY);
+            const parsed = raw ? JSON.parse(raw) : null;
+            if (parsed && parsed.current === CONTROL_API_VERSION) {
+                cached = parsed;
+                return parsed;
+            }
+        }
+        catch {
+            // fall through to a live check
+        }
+    }
+    const result = await checkForUpdate();
+    await store(result);
+    return result;
+}
+export function startUpdateCheck() {
+    if (!upgradeSettings().updateCheck || timer)
+        return;
+    const run = () => {
+        void getUpdateCheck({ refresh: true }).then(result => {
+            if (result.updateAvailable)
+                console.log(`[updates] Magnus ${result.latest} is available (running ${result.current}): ${result.command}`);
+            if (result.latestMajor)
+                console.log(`[updates] Magnus ${result.latestMajor} (new major) is available; see UPGRADING.md`);
+        });
+    };
+    // First check a minute after startup (with jitter), then daily.
+    timer = setTimeout(function tick() {
+        run();
+        timer = setTimeout(tick, DAY_MS);
+        timer.unref();
+    }, 60_000 + Math.floor(Math.random() * 60_000));
+    timer.unref();
+}
+export function stopUpdateCheck() {
+    if (timer)
+        clearTimeout(timer);
+    timer = undefined;
+}
+/** Classify agent versions against the version this server ships with. */
+export function classifyAgentVersions(agents, expected = AGENT_VERSION) {
+    const skew = { expected, current: 0, behind: [], ahead: [], unknown: [] };
+    for (const agent of agents) {
+        if (!isVersion(agent.version) || !isVersion(expected))
+            skew.unknown.push(agent);
+        else {
+            const order = compareVersions(agent.version, expected);
+            if (order === 0)
+                skew.current++;
+            else
+                (order < 0 ? skew.behind : skew.ahead).push(agent);
+        }
+    }
+    return skew;
+}
+export async function agentVersionSkew() {
+    const { getDb } = await import('../db/client.js');
+    const agents = await getDb().agent.findMany({ select: { version: true, node: { select: { id: true, name: true } } } });
+    return classifyAgentVersions(agents.map(agent => ({ nodeId: agent.node.id, name: agent.node.name, version: agent.version })));
+}
+/** The fix for an agent that is behind, spelled out for logs, `check` and the console. */
+export function agentFixCommand(nodeNames) {
+    return nodeNames.length > 0 && nodeNames.length <= 5
+        ? `magnus-server agents upgrade --nodes ${nodeNames.join(',')}`
+        : 'magnus-server agents upgrade';
+}
+//# sourceMappingURL=update-check-service.js.map

package/dist/utils/runtime-file.js

@@ -0,0 +1,23 @@
+import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { magnusHome } from './magnus-home.js';
+/**
+ * `run/server-runtime.json` tells upgrade tooling which version is actually
+ * serving (the public health endpoints deliberately omit the version).
+ */
+export function runtimeFilePath(env = process.env) {
+    return env['MAGNUS_RUNTIME_FILE']?.trim() || join(magnusHome(env), 'run', 'server-runtime.json');
+}
+export function writeRuntimeFile(details, env = process.env) {
+    const path = runtimeFilePath(env);
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const temporary = `${path}.${process.pid}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify({ ...details, pid: process.pid, startedAt: new Date().toISOString() })}\n`, { mode: 0o600 });
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        console.warn(`[startup] could not write ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=runtime-file.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemagnus/magnus-server",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "description": "Magnus server: the fleet control plane API (Hono, PostgreSQL, Redis) for nodes running magnus-agent, with optional Hive IAM, Hive Router, HiveMem, Hermes Agent and external security console integrations.",
   "keywords": [
     "magnus",
@@ -84,7 +84,7 @@
     "prepublishOnly": "npm run db:generate && npm run clean && npm run build"
   },
   "dependencies": {
-    "@hivemagnus/magnus-contracts": "1.0.3",
+    "@hivemagnus/magnus-contracts": "1.1.1",
     "@hono/node-server": "^2.1.5",
     "@hono/swagger-ui": "^0.6.2",
     "@prisma/adapter-pg": "7.10.1",
@@ -102,7 +102,7 @@
     "ws": "^8.22.0",
     "yaml": "2.9.1",
     "zod": "^4.6.7",
-    "@hivemagnus/magnus-skills": "1.0.3",
+    "@hivemagnus/magnus-skills": "1.1.1",
     "prisma": "^7.10.1"
   },
   "devDependencies": {