@hivemagnus/magnus-server 1.0.2 → 1.1.0

package/dist/cli.js

@@ -4,12 +4,13 @@
 // named on the command line have been applied.
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs, USAGE, UsageError } from './cli/args.js';
 import { buildEnvSchemaDocument, renderEnvTable } from './cli/env-catalog.js';
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+/** Node reads NODE_EXTRA_CA_CERTS only at startup; an env file that sets it needs a fresh process. */
+const STARTUP_EXTRA_CA = process.env['NODE_EXTRA_CA_CERTS'];
 const MIGRATIONS_DIR = join(PACKAGE_ROOT, 'prisma', 'migrations');
 const PRISMA_CONFIG = join(PACKAGE_ROOT, 'prisma.config.ts');
 class FatalError extends Error {
@@ -47,10 +48,10 @@ async function version() {
 async function migrate() {
     if (!process.env['DATABASE_URL'] && process.env['NODE_ENV'] === 'production')
         fatal('Configuration error: DATABASE_URL is required to run migrations in production.');
+    const { prismaCliPath } = await import('./cli/migrations.js');
     let prismaCli;
     try {
-        const require = createRequire(import.meta.url);
-        prismaCli = join(dirname(require.resolve('prisma/package.json')), 'build', 'index.js');
+        prismaCli = prismaCliPath();
     }
     catch {
         return fatal('Migration error: the prisma CLI package is not installed next to magnus-server.');
@@ -75,7 +76,7 @@ async function migrate() {
         await disconnectDb();
     }
 }
-async function commandCheck() {
+async function commandCheck(format) {
     const { listMissingSecrets } = await import('./utils/env.js');
     const { loadEnv } = await import('./config/env.js');
     const { featureFlags } = await import('./config/features.js');
@@ -104,11 +105,19 @@ async function commandCheck() {
     if (databaseUrl)
         results.push(...await checkDatabase(databaseUrl, MIGRATIONS_DIR));
     results.push(await checkRedis(process.env['REDIS_URL'] ?? 'redis://127.0.0.1:6379'));
+    const { checkForUpdate, updateResult } = await import('./services/update-check-service.js');
+    const update = await checkForUpdate();
+    results.push(updateResult(update));
+    const features = featureFlags();
+    const failures = results.filter(result => result.status === 'fail').length;
+    if (format === 'json') {
+        console.log(JSON.stringify({ version: await version(), ok: failures === 0, results, integrations: features, update }, null, 2));
+        return failures === 0 ? 0 : 1;
+    }
     const symbol = { pass: '✓', warn: '!', fail: '✗' };
     console.log(`magnus-server ${await version()} configuration check`);
     for (const result of results)
         console.log(`  ${symbol[result.status]} ${result.name.padEnd(12)} ${result.message}`);
-    const features = featureFlags();
     const onOff = (value) => (value ? 'on' : 'off');
     console.log('Integrations:');
     console.log(`  Hive IAM           ${onOff(features.iam)}`);
@@ -119,13 +128,94 @@ async function commandCheck() {
     console.log(`  Hermes registry    ${onOff(features.hermesRegistry)}`);
     console.log(`  Resource leases    ${onOff(features.resourceLeases)}`);
     console.log(`  Agent discovery    ${onOff(features.agentDiscovery)}`);
-    const failures = results.filter(result => result.status === 'fail').length;
     console.log(failures === 0 ? 'Result: OK' : `Result: ${failures} problem(s) found`);
     return failures === 0 ? 0 : 1;
 }
+/** Applied and pending migrations, with impact notes (`--format json` for tooling). */
+async function commandMigrations(format) {
+    const { resolveDatabaseUrl } = await import('./db/client.js');
+    const { readMigrationState } = await import('./cli/migrations.js');
+    const pg = (await import('pg')).default;
+    const client = new pg.Client({ connectionString: resolveDatabaseUrl(), connectionTimeoutMillis: 10_000 });
+    await client.connect();
+    try {
+        const state = await readMigrationState(client, MIGRATIONS_DIR);
+        if (format === 'json') {
+            console.log(JSON.stringify({ version: await version(), packaged: state.packaged, applied: [...state.applied].sort(), pending: state.pending, fresh: state.fresh }, null, 2));
+        }
+        else {
+            for (const name of state.packaged) {
+                const pending = state.pending.find(migration => migration.name === name);
+                console.log(`  ${pending ? '…' : '✓'} ${name}${pending ? ` (pending, ${pending.impact}${pending.note ? `: ${pending.note}` : ''})` : ''}`);
+            }
+            console.log(state.pending.length === 0 ? 'All migrations applied.' : `${state.pending.length} pending; run \`magnus-server migrate\`.`);
+        }
+        return 0;
+    }
+    finally {
+        await client.end().catch(() => undefined);
+    }
+}
+/** `pg_dump -Fc` into MAGNUS_BACKUP_DIR; prints JSON with the file and restore command. */
+async function commandBackup(label) {
+    const { resolveDatabaseUrl } = await import('./db/client.js');
+    const { backupDatabase } = await import('./cli/migrations.js');
+    const { defaultBackupDir } = await import('./cli/auto-migrate.js');
+    const { magnusHome } = await import('./utils/magnus-home.js');
+    const pg = (await import('pg')).default;
+    const databaseUrl = resolveDatabaseUrl();
+    const client = new pg.Client({ connectionString: databaseUrl, connectionTimeoutMillis: 10_000 });
+    await client.connect();
+    try {
+        const result = await backupDatabase({
+            databaseUrl, client, backupDir: defaultBackupDir(process.env, magnusHome()),
+            label: label ?? `manual-${await version()}`, pgDump: process.env['MAGNUS_PG_DUMP'],
+        });
+        console.log(JSON.stringify(result));
+        return 0;
+    }
+    finally {
+        await client.end().catch(() => undefined);
+    }
+}
+/** `MAGNUS_AUTO_MIGRATE=true`: back up and migrate under an advisory lock before listening. */
+async function startupAutoMigrate() {
+    const { upgradeSettings } = await import('./config/features.js');
+    const settings = upgradeSettings();
+    if (!settings.autoMigrate)
+        return;
+    const { resolveDatabaseUrl } = await import('./db/client.js');
+    const { autoMigrate, defaultBackupDir } = await import('./cli/auto-migrate.js');
+    const { magnusHome } = await import('./utils/magnus-home.js');
+    try {
+        await autoMigrate({
+            databaseUrl: resolveDatabaseUrl(),
+            migrationsDir: MIGRATIONS_DIR,
+            backupDir: defaultBackupDir(process.env, magnusHome()),
+            version: await version(),
+            settings,
+            pgDump: process.env['MAGNUS_PG_DUMP'],
+            migrate,
+        });
+    }
+    catch (error) {
+        if (error instanceof FatalError)
+            throw error;
+        fatal(error instanceof Error ? error.message : String(error));
+    }
+}
 async function commandStart(options) {
+    // Without --env-file the server reads its package-level .env; apply it here
+    // too so startup switches such as MAGNUS_AUTO_MIGRATE see the same values.
+    const packageEnv = join(PACKAGE_ROOT, '.env');
+    if (!process.env['MAGNUS_ENV_FILE'] && existsSync(packageEnv)) {
+        process.loadEnvFile(packageEnv);
+        dropEmptyValues();
+    }
     if (options.migrate)
         await migrate();
+    else
+        await startupAutoMigrate();
     await import('./index.js');
 }
 async function run(argv) {
@@ -146,7 +236,31 @@ async function run(argv) {
             return 0;
         case 'check':
             loadEnvFiles(options.envFiles);
-            return commandCheck();
+            return commandCheck(options.formatGiven ? options.format : 'table');
+        case 'migrations':
+            loadEnvFiles(options.envFiles);
+            return commandMigrations(options.formatGiven ? options.format : 'table');
+        case 'backup':
+            loadEnvFiles(options.envFiles);
+            return commandBackup(options.label);
+        case 'upgrade':
+        case 'rollback': {
+            const { delegateToProject } = await import('./cli/upgrade.js');
+            return delegateToProject(options.command, options.passthrough, PACKAGE_ROOT);
+        }
+        case 'agents': {
+            loadEnvFiles(options.envFiles);
+            // The command calls agents over TLS: trust the same extra CA as the service.
+            if (process.env['NODE_EXTRA_CA_CERTS'] && process.env['NODE_EXTRA_CA_CERTS'] !== STARTUP_EXTRA_CA) {
+                return new Promise((resolvePromise, reject) => {
+                    const child = spawn(process.execPath, process.argv.slice(1), { stdio: 'inherit', env: process.env });
+                    child.on('error', reject);
+                    child.on('close', code => resolvePromise(code ?? 1));
+                });
+            }
+            const { commandAgents } = await import('./cli/agents.js');
+            return commandAgents(options.passthrough);
+        }
         case 'migrate':
             loadEnvFiles(options.envFiles);
             await migrate();

package/dist/config/env.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import path from 'node:path';
+import { parseRouteAliases } from './route-aliases.js';
+import { webhookTypeAliases } from '../services/webhook-types.js';
 // ─── Shared environment schema — validated with Zod ───
 const portSchema = z.coerce.number().int().min(1).max(65535);
 const booleanEnvSchema = z.enum(['true', 'false']).default('false').transform((value) => value === 'true');
@@ -48,6 +50,10 @@ export const envSchema = z.object({
     APPROVAL_TELEGRAM_ACTOR_SHA256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     APPROVAL_IPHONE_ACTOR_SHA256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     MAGNUS_APPROVAL_BRIDGE_CONSUMER: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,63}$/i).optional(),
+    // Accepted approval-assertion signature domain prefixes (comma-separated); first is preferred.
+    MAGNUS_APPROVAL_ASSERTION_DOMAINS: z.string()
+        .regex(/^\s*[a-z0-9](?:[a-z0-9.-]{0,98}[a-z0-9])?\s*(?:,\s*[a-z0-9](?:[a-z0-9.-]{0,98}[a-z0-9])?\s*)*$/, 'must list domain prefixes made of a-z, 0-9, "." and "-", separated by commas')
+        .optional(),
     // Security Fusion: off (default) | local (in-process) | remote (external security console).
     SECURITY_FUSION_MODE: z.enum(['off', 'local', 'remote']).default('off'),
     SECURITY_FUSION_API_URL: z.string().url().optional(),
@@ -151,7 +157,27 @@ export const envSchema = z.object({
     HERMES_HIVEMEM_WORKSPACE_ID: z.string().optional(),
     HERMES_HIVEMEM_DEFAULT_SCOPE: z.enum(['private', 'shared']).optional(),
     HERMES_OPENAI_RUNTIME: z.enum(['auto', 'codex_app_server']).optional(),
+    // Optional legacy-path -> current-path prefix map for older clients (see config/route-aliases.ts).
+    MAGNUS_ROUTE_ALIASES_JSON: z.string().optional(),
+    // Optional legacy webhook type names: comma-separated legacy=format pairs.
+    MAGNUS_WEBHOOK_TYPE_ALIASES: z.string()
+        .regex(/^\s*(?:[a-z][a-z0-9_-]{0,31}\s*=\s*(?:generic|slack|discord|mattermost)\s*(?:,\s*|$))*$/, 'must list legacy=format pairs, where format is generic, slack, discord or mattermost')
+        .optional(),
 }).superRefine((env, ctx) => {
+    try {
+        webhookTypeAliases(env.MAGNUS_WEBHOOK_TYPE_ALIASES);
+    }
+    catch (error) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['MAGNUS_WEBHOOK_TYPE_ALIASES'],
+            message: error instanceof Error ? error.message : 'MAGNUS_WEBHOOK_TYPE_ALIASES is invalid' });
+    }
+    try {
+        parseRouteAliases(env.MAGNUS_ROUTE_ALIASES_JSON);
+    }
+    catch (error) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['MAGNUS_ROUTE_ALIASES_JSON'],
+            message: error instanceof Error ? error.message : 'MAGNUS_ROUTE_ALIASES_JSON is invalid' });
+    }
     if (env.HEALTH_SNAPSHOT_FULL_FIDELITY_HOURS > env.HEALTH_SNAPSHOT_RETENTION_DAYS * 24) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,

package/dist/config/features.js

@@ -13,4 +13,26 @@ export function featureFlags(env = process.env) {
         agentDiscovery: truthy(env['ENABLE_AGENT_DISCOVERY']),
     };
 }
+/** Boolean switch with an explicit default: only `true`/`false` (any case) override it. */
+export function envSwitch(value, fallback) {
+    const normalized = (value ?? '').trim().toLowerCase();
+    if (normalized === 'true')
+        return true;
+    if (normalized === 'false')
+        return false;
+    return fallback;
+}
+export function upgradeSettings(env = process.env) {
+    const concurrency = Number.parseInt(env['MAGNUS_AGENT_UPGRADE_CONCURRENCY'] ?? '', 10);
+    return {
+        autoMigrate: envSwitch(env['MAGNUS_AUTO_MIGRATE'], false),
+        autoMigrateBackup: envSwitch(env['MAGNUS_AUTO_MIGRATE_BACKUP'], true),
+        autoMigrateAllowSlow: envSwitch(env['MAGNUS_AUTO_MIGRATE_ALLOW_SLOW'], false),
+        updateCheck: envSwitch(env['MAGNUS_UPDATE_CHECK'], true),
+        updateRegistry: (env['MAGNUS_UPDATE_REGISTRY']?.trim() || 'https://registry.npmjs.org').replace(/\/+$/, ''),
+        agentUpgrades: envSwitch(env['MAGNUS_AGENT_UPGRADES'], true),
+        agentUpgradeConcurrency: Number.isInteger(concurrency) && concurrency > 0 ? Math.min(concurrency, 50) : 5,
+        legacyGitSelfUpdate: envSwitch(env['MAGNUS_LEGACY_GIT_SELF_UPDATE'], false),
+    };
+}
 //# sourceMappingURL=features.js.map

package/dist/config/route-aliases.js

@@ -0,0 +1,73 @@
+/**
+ * Optional request path aliases for clients built against older route names.
+ *
+ * `MAGNUS_ROUTE_ALIASES_JSON` is a JSON object that maps a legacy path prefix
+ * to the current one, for example
+ * `{"/api/v1/old/prefix": "/api/v1/new/prefix"}`. A request whose path equals a
+ * legacy prefix, or continues it after a `/`, is rewritten before routing, so
+ * authentication, endpoint scopes, rate limits and audit all see the current
+ * path. Unset (the default) means no aliases.
+ */
+const segment = '[A-Za-z0-9._~-]+';
+const aliasPath = new RegExp(`^/api/v1(?:/${segment})+$`);
+function validPath(path) {
+    return aliasPath.test(path) && !path.split('/').some(part => part === '.' || part === '..');
+}
+/** Parse and validate the alias map; throws a descriptive error when it is malformed. */
+export function parseRouteAliases(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return [];
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('MAGNUS_ROUTE_ALIASES_JSON must be a JSON object');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('MAGNUS_ROUTE_ALIASES_JSON must be a JSON object');
+    const entries = Object.entries(value);
+    if (entries.length > 64)
+        throw new Error('MAGNUS_ROUTE_ALIASES_JSON may define at most 64 aliases');
+    const aliases = [];
+    for (const [from, to] of entries) {
+        if (typeof to !== 'string' || !validPath(from) || !validPath(to))
+            throw new Error('MAGNUS_ROUTE_ALIASES_JSON keys and values must be /api/v1/... paths without "." or ".." segments');
+        if (from === to)
+            throw new Error('MAGNUS_ROUTE_ALIASES_JSON maps a path to itself');
+        aliases.push({ from, to });
+    }
+    for (const { to } of aliases)
+        if (aliases.some(alias => to === alias.from || to.startsWith(`${alias.from}/`)))
+            throw new Error('MAGNUS_ROUTE_ALIASES_JSON targets must not be aliases themselves');
+    // Longest prefix first, so a more specific alias wins.
+    return aliases.sort((a, b) => b.from.length - a.from.length);
+}
+/** The current path for `path`, or null when no alias applies. */
+export function resolveRouteAlias(path, aliases) {
+    for (const { from, to } of aliases) {
+        if (path === from)
+            return to;
+        if (path.startsWith(`${from}/`))
+            return to + path.slice(from.length);
+    }
+    return null;
+}
+/** Wrap a fetch handler so legacy paths reach their current routes. Returns `fetch` unchanged without aliases. */
+export function withRouteAliases(fetch, aliases) {
+    if (!aliases.length)
+        return fetch;
+    return (request, env, context) => {
+        const url = new URL(request.url);
+        const target = resolveRouteAlias(url.pathname, aliases);
+        if (target === null)
+            return fetch(request, env, context);
+        url.pathname = target;
+        const init = {
+            method: request.method, headers: request.headers, redirect: request.redirect, signal: request.signal,
+            ...(request.body ? { body: request.body, duplex: 'half' } : {}),
+        };
+        return fetch(new Request(url, init), env, context);
+    };
+}
+//# sourceMappingURL=route-aliases.js.map

package/dist/index.js

@@ -18,6 +18,8 @@ const { securityFusionLocal, securityFusionMode, startSecurityExporter, stopSecu
 const { featureFlags } = await import('./config/features.js');
 const { serve } = await import('@hono/node-server');
 const { app } = await import('./server.js');
+const { parseRouteAliases, withRouteAliases } = await import('./config/route-aliases.js');
+const handler = withRouteAliases(app.fetch, parseRouteAliases(process.env['MAGNUS_ROUTE_ALIASES_JSON']));
 const { startRolloutReconciler, stopRolloutReconciler } = await import('./services/rollout-service.js');
 const { startApplicationProbes, stopApplicationProbes } = await import('./services/application-probes.js');
 const { startNodeIssueMonitor } = await import('./services/node-issue-monitor.js');
@@ -31,6 +33,7 @@ const { startSecurityFusionRetention, stopSecurityFusionRetention } = await impo
 const { reconcileSecurityFusionEvidence } = await import('./services/security-fusion-evidence-integrity.js');
 const { startSecurityFusionOutboxDispatcher, stopSecurityFusionOutboxDispatcher, } = await import('./services/security-fusion-outbox.js');
 const { startCommandWorker, closeCommandQueue } = await import('./queue/workers.js');
+const { startUpdateCheck, stopUpdateCheck } = await import('./services/update-check-service.js');
 const { startWebhookWorker, closeWebhookQueue } = await import('./services/webhook-service.js');
 const { setupTerminalWebSocket } = await import('./routes/terminal.js');
 const { disconnectRedis } = await import('./queue/redis.js');
@@ -49,8 +52,11 @@ if (securityFusionLocal()) {
         + `updated=${evidenceReconciliation.updated} quarantined=${evidenceReconciliation.quarantined} `
         + `mismatched_cases=${evidenceReconciliation.mismatchedCases}`);
 }
+const { writeRuntimeFile } = await import('./utils/runtime-file.js');
+const { CONTROL_API_VERSION } = await import('./config/version.js');
 /** Background services shared by the TLS and development listeners. */
-function startBackgroundServices() {
+function startBackgroundServices(listenPort) {
+    writeRuntimeFile({ version: CONTROL_API_VERSION, port: listenPort });
     startNodeIssueMonitor();
     startApplicationProbes();
     startLogRetention();
@@ -65,6 +71,7 @@ function startBackgroundServices() {
     startRolloutReconciler();
     startWebhookWorker();
     startCodexFleetMonitor();
+    startUpdateCheck();
     if (features.hermesRegistry) {
         startExtensionSourceMonitor();
         void importPackageSkills().then(result => console.log(`[hermes-registry] catalog import: ${JSON.stringify(result)}`))
@@ -89,7 +96,7 @@ const listener = resolveListenerSecurity({
 });
 const server = listener.useTls
     ? serve({
-        fetch: app.fetch,
+        fetch: handler,
         port,
         hostname: listener.hostname,
         createServer,
@@ -99,11 +106,11 @@ const server = listener.useTls
         },
     }, (info) => {
         console.log(`🚀 Magnus server listening on https://${listener.hostname}:${info.port}`);
-        startBackgroundServices();
+        startBackgroundServices(info.port);
     })
-    : serve({ fetch: app.fetch, port, hostname: listener.hostname }, (info) => {
+    : serve({ fetch: handler, port, hostname: listener.hostname }, (info) => {
         console.log(`🚀 Magnus server listening on http://${listener.hostname}:${info.port} (development opt-in)`);
-        startBackgroundServices();
+        startBackgroundServices(info.port);
     });
 const terminalWss = setupTerminalWebSocket(server);
 // ── Graceful shutdown ──
@@ -131,6 +138,7 @@ async function shutdown(signal) {
                 stopSecurityExporter();
                 stopSecurityFusionOutboxDispatcher();
                 stopCodexFleetMonitor();
+                stopUpdateCheck();
                 stopExtensionSourceMonitor();
                 for (const client of terminalWss.clients)
                     client.terminate();

package/dist/openapi/spec.js

@@ -2011,36 +2011,6 @@ const paths = {
             },
         },
     },
-    '/deploy/upgrade/{nodeId}': {
-        post: {
-            tags: ['Deploy'],
-            summary: 'Upgrade agent',
-            description: 'Upgrade the agent on a node to the current expected version. Runs asynchronously.',
-            security: apiSecretAuth,
-            parameters: [pp('nodeId', 'Node ID')],
-            responses: {
-                202: success('Upgrade started'),
-                401: err401,
-                403: err403,
-                404: err404,
-            },
-        },
-    },
-    '/deploy/version': {
-        get: {
-            tags: ['Deploy'],
-            summary: 'Expected agent version',
-            description: 'Returns the expected agent version and deploy username.',
-            security: apiSecretAuth,
-            responses: {
-                200: success('Version info', {
-                    type: 'object',
-                    properties: { agentVersion: { type: 'string' }, deployUsername: { type: 'string' } },
-                }),
-                401: err401,
-            },
-        },
-    },
     '/deploy/control-node': {
         post: {
             tags: ['Deploy'],
@@ -2157,6 +2127,77 @@ const paths = {
         },
     },
     // ──────────────── Self-Update ────────────────
+    '/system/updates': {
+        get: {
+            tags: ['Updates'],
+            summary: 'Available releases and agent version skew',
+            description: 'Result of the daily npm registry check (MAGNUS_UPDATE_CHECK): the newest release of the running major, a newer major if any, release notes, new required settings and slow or one-way migrations. Also lists agents that run a different version than this server ships with, and the command that fixes it.',
+            security: apiSecretAuth,
+            responses: { 200: success('Update status', { type: 'object', properties: {
+                        version: { type: 'string' },
+                        server: { type: 'object', properties: { enabled: { type: 'boolean' }, current: { type: 'string' }, latest: { type: ['string', 'null'] },
+                                latestMajor: { type: ['string', 'null'] }, updateAvailable: { type: 'boolean' }, command: { type: 'string' } } },
+                        agents: { type: 'object', properties: { expected: { type: 'string' }, current: { type: 'integer' },
+                                behind: { type: 'array', items: { type: 'object' } }, ahead: { type: 'array', items: { type: 'object' } },
+                                upgradesEnabled: { type: 'boolean' }, fixCommand: { type: ['string', 'null'] } } },
+                    } }), 401: err401 },
+        },
+    },
+    '/system/updates/check': {
+        post: {
+            tags: ['Updates'],
+            summary: 'Check the registry now',
+            description: 'Refreshes the update check immediately (ADMIN or OPERATOR).',
+            security: apiSecretAuth,
+            responses: { 200: success('Update status'), 401: err401, 403: err403 },
+        },
+    },
+    '/agents/upgrade/eligibility': {
+        get: {
+            tags: ['Agent upgrades'],
+            summary: 'Which agents can take a version',
+            description: 'For every node: its agent version and whether it can upgrade itself to `version` (default: the agent version this server ships with) now, or why not (offline, not set up with `magnus-agent install-service`, MAGNUS_AGENT_SELF_UPGRADE=false, another major version, already current).',
+            security: apiSecretAuth,
+            parameters: [qp('version', 'Target agent version (X.Y.Z)')],
+            responses: { 200: success('Eligibility', { type: 'object', properties: {
+                        version: { type: 'string' }, upgradesEnabled: { type: 'boolean' }, disabledReason: { type: ['string', 'null'] },
+                        nodes: { type: 'array', items: { type: 'object', properties: { nodeId: { type: 'string' }, name: { type: 'string' },
+                                    version: { type: 'string' }, eligible: { type: 'boolean' }, reason: { type: ['string', 'null'] } } } },
+                    } }), 400: err400, 401: err401 },
+        },
+    },
+    '/agents/upgrade': {
+        post: {
+            tags: ['Agent upgrades'],
+            summary: 'Upgrade agents',
+            description: 'Starts an upgrade run (ADMIN, MAGNUS_AGENT_UPGRADES=true): one canary, then MAGNUS_AGENT_UPGRADE_CONCURRENCY agents at a time, stopping at the first agent that does not confirm. Each agent installs the exact version and npm integrity and switches back by itself if the new version does not report a heartbeat in time.',
+            security: apiSecretAuth,
+            requestBody: { required: false, content: { 'application/json': { schema: { type: 'object', properties: {
+                                version: { type: 'string', description: 'Agent version (default: the one this server ships with)' },
+                                integrity: { type: 'string', description: 'npm sha512 integrity (default: read from the registry)' },
+                                nodeIds: { type: 'array', items: { type: 'string' }, description: 'Only these nodes' },
+                            } } } } },
+            responses: { 202: success('Run started'), 400: err400, 401: err401, 403: err403, 409: err409 },
+        },
+    },
+    '/agents/upgrade/runs/latest': {
+        get: {
+            tags: ['Agent upgrades'],
+            summary: 'Latest upgrade run',
+            security: apiSecretAuth,
+            responses: { 200: success('Run (or null)'), 401: err401 },
+        },
+    },
+    '/agents/upgrade/runs/{id}': {
+        get: {
+            tags: ['Agent upgrades'],
+            summary: 'Upgrade run status',
+            description: 'Per-node state of a run: pending, requested, confirmed, reverted, failed or skipped.',
+            security: apiSecretAuth,
+            parameters: [pp('id', 'Run ID')],
+            responses: { 200: success('Run'), 401: err401, 404: err404 },
+        },
+    },
     '/self-update/status': {
         get: {
             tags: ['Self-Update'],
@@ -2214,7 +2255,7 @@ const paths = {
         post: {
             tags: ['Self-Update'],
             summary: 'Apply update',
-            description: 'Pull latest code, run `npm ci`, build, and optionally restart the process. Requires ADMIN role.',
+            description: 'Source checkouts only, and only with MAGNUS_LEGACY_GIT_SELF_UPDATE=true (otherwise 410 SELF_UPDATE_RETIRED): pull latest code, run `npm ci`, build, and optionally restart the process. npm installs upgrade with `magnus upgrade`. Requires ADMIN role.',
             security: apiSecretAuth,
             requestBody: {
                 required: false,

package/dist/routes/agent-upgrades.js

@@ -0,0 +1,42 @@
+import { Hono } from 'hono';
+import { z } from 'zod';
+import { authMiddleware, getUser, requireRole } from '../middleware/auth.js';
+import { HttpError } from '../middleware/error-handler.js';
+import { upgradeSettings } from '../config/features.js';
+import { AGENT_VERSION } from '../config/version.js';
+import { getUpgradeRun, latestUpgradeRun, listUpgradeCandidates, startUpgradeRun } from '../services/agent-upgrade-service.js';
+/** /api/v1/agents/upgrade: which agents can take a version, and fleet upgrade runs. */
+export const agentUpgradesRouter = new Hono();
+agentUpgradesRouter.use('*', authMiddleware);
+const version = z.string().regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/);
+agentUpgradesRouter.get('/eligibility', async (c) => {
+    const target = version.safeParse(c.req.query('version') ?? AGENT_VERSION);
+    if (!target.success)
+        throw new HttpError(400, 'INVALID_VERSION', 'version must be X.Y.Z');
+    const nodes = await listUpgradeCandidates(target.data);
+    return c.json({ success: true, data: {
+            version: target.data, serverVersion: AGENT_VERSION, upgradesEnabled: upgradeSettings().agentUpgrades,
+            disabledReason: upgradeSettings().agentUpgrades ? null : 'MAGNUS_AGENT_UPGRADES=false on the server',
+            nodes, latestRun: await latestUpgradeRun(),
+        } });
+});
+const startSchema = z.object({
+    version: version.optional(),
+    integrity: z.string().regex(/^sha512-[A-Za-z0-9+/]+={0,2}$/).optional(),
+    nodeIds: z.array(z.string().min(1).max(128)).max(1000).optional(),
+}).strict();
+agentUpgradesRouter.post('/', requireRole('ADMIN'), async (c) => {
+    const parsed = startSchema.safeParse(await c.req.json().catch(() => ({})));
+    if (!parsed.success)
+        throw new HttpError(400, 'VALIDATION_ERROR', parsed.error.issues.map(issue => issue.message).join('; '));
+    const { run } = await startUpgradeRun({ ...parsed.data, actorId: getUser(c).userId });
+    return c.json({ success: true, data: run }, 202);
+});
+agentUpgradesRouter.get('/runs/latest', async (c) => c.json({ success: true, data: await latestUpgradeRun() }));
+agentUpgradesRouter.get('/runs/:id', async (c) => {
+    const run = await getUpgradeRun(c.req.param('id'));
+    if (!run)
+        throw new HttpError(404, 'NOT_FOUND', 'Upgrade run not found');
+    return c.json({ success: true, data: run });
+});
+//# sourceMappingURL=agent-upgrades.js.map

package/dist/routes/heartbeat.js

@@ -1,4 +1,6 @@
 import { enqueueSecurityObservations, securityFusionLocal } from '../services/security-export.js';
+import { warnOnAgentVersionMismatch } from '../services/agent-version-warnings.js';
+import { recordSelfUpgradeReport } from '../services/agent-upgrade-service.js';
 import { Hono } from 'hono';
 import { z } from 'zod';
 import { nanoid } from 'nanoid';
@@ -330,6 +332,11 @@ heartbeatRouter.post('/', async (c) => {
                 }) },
         });
     }
+    if (existing && body.selfUpgrade !== undefined) {
+        await recordSelfUpgradeReport({ id: nodeId, name: existing.name }, body).catch((err) => {
+            console.error(`[agent-upgrade] could not record the self-upgrade report of ${existing.name}:`, err instanceof Error ? err.message : err);
+        });
+    }
     if (!fqdn && existing) {
         // If the node's hostname already contains a dot it's likely an FQDN — skip lookup
         if (!existing.hostname.includes('.')) {
@@ -521,7 +528,7 @@ heartbeatRouter.post('/', async (c) => {
         }
     }
     const expectedVersion = AGENT_VERSION;
-    const updateAvailable = body.agentVersion && body.agentVersion !== expectedVersion;
+    const { updateAvailable } = warnOnAgentVersionMismatch({ id: nodeId, name: existing?.name ?? fqdn ?? nodeId }, body.agentVersion, expectedVersion);
     return c.json({ success: true, data: { accepted: true, expectedVersion, updateAvailable } });
 });
 // ── Retired Redis Streams heartbeat ingress ──

package/dist/routes/self-update.js

@@ -6,6 +6,7 @@ import { authMiddleware, getUser, requireRole } from '../middleware/auth.js';
 import { logAuditEvent } from '../services/audit-service.js';
 import { checkForUpdates, performSelfUpdate, scheduleRestart, getUpdateStatus, } from '../services/self-update-service.js';
 import { HttpError } from '../middleware/error-handler.js';
+import { upgradeSettings } from '../config/features.js';
 export const selfUpdateRouter = new Hono();
 selfUpdateRouter.use('*', authMiddleware);
 selfUpdateRouter.use('*', async (c, next) => {
@@ -16,6 +17,24 @@ selfUpdateRouter.use('*', async (c, next) => {
         c.header(c.res.headers.has('X-Magnus-Work-Id') ? 'X-Magnus-Restart-Work-Id' : 'X-Magnus-Work-Id', c.error.workId);
     }
 });
+/**
+ * The git-checkout update path (`git pull`, rebuild, restart) only works for
+ * source installs. npm installs upgrade with `magnus upgrade`, which backs up
+ * the database and reverts on failure; the old endpoints stay behind
+ * MAGNUS_LEGACY_GIT_SELF_UPDATE=true.
+ */
+const legacyGitSelfUpdate = async (c, next) => {
+    if (!upgradeSettings().legacyGitSelfUpdate) {
+        return c.json({ success: false, error: { code: 'SELF_UPDATE_RETIRED',
+                message: 'In-place git self-update is off. Upgrade with `magnus upgrade` (or `magnus-server upgrade`) on the server host; '
+                    + 'set MAGNUS_LEGACY_GIT_SELF_UPDATE=true to re-enable this endpoint for a source checkout.',
+                upgradeCommand: 'magnus upgrade' } }, 410);
+    }
+    await next();
+};
+selfUpdateRouter.use('/check', legacyGitSelfUpdate);
+selfUpdateRouter.use('/apply', legacyGitSelfUpdate);
+selfUpdateRouter.use('/restart', legacyGitSelfUpdate);
 selfUpdateRouter.get('/work/:workId', requireRole('ADMIN', 'OPERATOR'), async (c) => {
     const id = z.string().guid().safeParse(c.req.param('workId'));
     if (!id.success)

package/dist/routes/system-updates.js

@@ -0,0 +1,27 @@
+import { Hono } from 'hono';
+import { authMiddleware, requireRole } from '../middleware/auth.js';
+import { upgradeSettings } from '../config/features.js';
+import { CONTROL_API_VERSION } from '../config/version.js';
+import { agentFixCommand, agentVersionSkew, getUpdateCheck } from '../services/update-check-service.js';
+/**
+ * GET /api/v1/system/updates: available releases (MAGNUS_UPDATE_CHECK) and
+ * agents running a different version than the server ships with.
+ */
+export const systemUpdatesRouter = new Hono();
+systemUpdatesRouter.use('*', authMiddleware);
+async function report(refresh) {
+    const [server, agents] = await Promise.all([getUpdateCheck({ refresh }), agentVersionSkew()]);
+    const settings = upgradeSettings();
+    return {
+        version: CONTROL_API_VERSION,
+        server,
+        agents: {
+            ...agents,
+            upgradesEnabled: settings.agentUpgrades,
+            fixCommand: agents.behind.length > 0 ? agentFixCommand(agents.behind.map(node => node.name)) : null,
+        },
+    };
+}
+systemUpdatesRouter.get('/', async (c) => c.json({ success: true, data: await report(false) }));
+systemUpdatesRouter.post('/check', requireRole('ADMIN', 'OPERATOR'), async (c) => c.json({ success: true, data: await report(true) }));
+//# sourceMappingURL=system-updates.js.map