@hivemagnus/magnus-server 1.0.3 → 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/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/index.js

@@ -33,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');
@@ -51,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();
@@ -67,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)}`))
@@ -101,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: 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 ──
@@ -133,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

package/dist/sdk/node-api-client.js

@@ -390,9 +390,10 @@ export class NodeApiClient {
     async removeSkill(skillName) {
         return this.mutate('DELETE', `skills/${encodeURIComponent(skillName)}`);
     }
-    // ── Self-update ──
-    async triggerUpdate(payload) {
-        return this.mutate('POST', 'update', payload);
+    // ── Agent self-upgrade ──
+    /** Stage an exact agent version; the agent restarts into it through its launcher. */
+    async upgradeAgent(request) {
+        return this.mutate('POST', 'agent-upgrade', request, 15 * 60_000);
     }
     // ── Ping ──
     async ping() {

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

@@ -30,6 +30,8 @@ import { libraryRouter } from './routes/library.js';
 import { rolesRouter } from './routes/roles.js';
 import { notificationsRouter } from './routes/notifications.js';
 import { selfUpdateRouter } from './routes/self-update.js';
+import { systemUpdatesRouter } from './routes/system-updates.js';
+import { agentUpgradesRouter } from './routes/agent-upgrades.js';
 import { scanRouter } from './routes/scan.js';
 import { terminalTicketRouter } from './routes/terminal-ticket.js';
 import { usersRouter, authRouter } from './routes/users.js';
@@ -93,6 +95,7 @@ const v1 = new Hono();
 // ── Rate limiting on sensitive endpoints (permissive — Beta) ──
 v1.use('/auth/*', rateLimitMiddleware({ windowMs: 60_000, max: 20, keyPrefix: 'rl:auth', failClosed: true }));
 v1.use('/deploy/*', rateLimitMiddleware({ windowMs: 60_000, max: 10, keyPrefix: 'rl:deploy', failClosed: true }));
+v1.use('/agents/upgrade', rateLimitMiddleware({ windowMs: 60_000, max: 10, keyPrefix: 'rl:agent-upgrade', failClosed: true }));
 v1.use('/self-update/*', rateLimitMiddleware({ windowMs: 60_000, max: 10, keyPrefix: 'rl:selfupdate', failClosed: true }));
 v1.use('/commands/*', rateLimitMiddleware({ windowMs: 60_000, max: 60, keyPrefix: 'rl:commands' }));
 v1.use('/quick-command/*', rateLimitMiddleware({ windowMs: 60_000, max: 30, keyPrefix: 'rl:quickcmd' }));
@@ -125,6 +128,8 @@ v1.route('/library', libraryRouter);
 v1.route('/roles', rolesRouter);
 v1.route('/notifications', notificationsRouter);
 v1.route('/self-update', selfUpdateRouter);
+v1.route('/system/updates', systemUpdatesRouter);
+v1.route('/agents/upgrade', agentUpgradesRouter);
 v1.route('/scan', scanRouter);
 v1.route('/terminal', terminalTicketRouter);
 v1.route('/users', usersRouter);