@hivemagnus/magnus-server 1.1.2 → 1.1.3

package/dist/services/command-resource-leases.js

@@ -23,6 +23,17 @@ export class ResourceLeaseConflict extends HttpError {
     constructor() { super(409, 'RESOURCE_LEASE_CONFLICT', 'Node or service has an unsettled command owner; reconcile its evidence before retrying'); }
 }
 export function resourceLeasesRequested() { return process.env['MAGNUS_RESOURCE_LEASES_ENABLED'] === 'true'; }
+/** Online with a heartbeat at most this old: the freshness admission requires. */
+export const RESOURCE_HEARTBEAT_FRESH_MS = 120_000;
+/** Read-only predicates shared with upgrade eligibility, so it cannot drift from admission. */
+export function hasFreshOnlineHealth(node, now = Date.now()) {
+    return node.status === 'ONLINE' && Boolean(node.lastHeartbeatAt) && now - node.lastHeartbeatAt.getTime() <= RESOURCE_HEARTBEAT_FRESH_MS;
+}
+/** Legacy unleased dispatch stays possible only while this holds AND the node has no lease history. */
+export function legacyAdmissionPossible(enrollment, leasesRequested = resourceLeasesRequested()) {
+    return !leasesRequested && (!enrollment || enrollment.state === 'legacy');
+}
+export const HELD_RESOURCE_STATES = HELD;
 function canonicalServiceUnit(value) {
     // A narrow scope is granted only to the exact allowlisted immutable runbook.
     // Arbitrary shell syntax, aliases, user units and wrapper commands stay node-wide.
@@ -96,7 +107,7 @@ export async function admitResourceCommand(context, raw) {
             throw new HttpError(409, 'RESOURCE_TARGET_INVALID', 'Canonical command target differs from inventory');
         await assertNodeAdmissionOpen(tx, node.id);
         const enrollment = await tx.resourceEnrollment.findUnique({ where: { nodeId: node.id } });
-        if (!scopedArdent && !resourceLeasesRequested() && (!enrollment || enrollment.state === 'legacy')
+        if (!scopedArdent && legacyAdmissionPossible(enrollment)
             && !await tx.commandResourceLease.findFirst({ where: { nodeId: node.id }, select: { id: true } }))
             return null;
         if (scopedArdent)
@@ -106,7 +117,7 @@ export async function admitResourceCommand(context, raw) {
         if (await tx.resourceParticipantWork.findFirst({ where: { nodeId: node.id,
                 ...(scopedArdent ? { participant: { in: ['agent', 'api', 'dashboard'] } } : {}), state: { in: HELD } } }))
             throw new ResourceLeaseConflict();
-        if (node.status !== 'ONLINE' || !node.lastHeartbeatAt || Date.now() - node.lastHeartbeatAt.getTime() > 120_000)
+        if (!hasFreshOnlineHealth(node))
             throw new HttpError(409, 'RESOURCE_TARGET_INVALID', 'Canonical command target lacks fresh online health');
         if (await tx.commandResourceLease.findUnique({ where: { commandId: payload.commandId } }))
             throw new HttpError(409, 'COMMAND_ALREADY_OWNED', 'Command already has a durable resource owner; inspect its receipt without replaying');

package/dist/services/managed-cron.js

@@ -7,6 +7,7 @@ import { managedCronSchema, managedCronStageAckSchema, managedCronActivationAckS
 import { lockResourceNode } from './resource-node-lock.js';
 import { assertNodeAdmissionOpen } from './admission-fence.js';
 import { assertEnrollmentComplete } from './resource-enrollment.js';
+import { readOwnershipHistory, stickyEnrollmentObserved } from './resource-ownership.js';
 import { admitResourceCommand, markResourceDispatched, settleResourceResult, resourceLeasesRequested } from './command-resource-leases.js';
 import { commandRequestDigest } from '../security/command-request.js';
 import { verifyCommandResultSignature } from '../security/command-result-signature.js';
@@ -33,14 +34,10 @@ export async function cronMutationMode(nodeId) {
         const node = await tx.node.findUnique({ where: { id: nodeId } });
         if (!node)
             throw new HttpError(404, 'NODE_NOT_FOUND', 'Inventory node not found');
-        const [enrollment, leaseHistory, definitionHistory, participantHistory] = await Promise.all([
-            tx.resourceEnrollment.findUnique({ where: { nodeId }, select: { state: true } }),
-            tx.commandResourceLease.findFirst({ where: { nodeId }, select: { id: true } }),
-            tx.managedCronDefinition.findFirst({ where: { nodeId }, select: { cronJobId: true } }),
-            tx.resourceParticipantWork.findFirst({ where: { nodeId }, select: { workId: true } }),
+        const [enrollment, history] = await Promise.all([
+            tx.resourceEnrollment.findUnique({ where: { nodeId }, select: { state: true } }), readOwnershipHistory(tx, nodeId)
         ]);
-        const managed = resourceLeasesRequested() || Boolean(enrollment && enrollment.state !== 'legacy')
-            || Boolean(leaseHistory || definitionHistory || participantHistory);
+        const managed = resourceLeasesRequested() || stickyEnrollmentObserved(enrollment, history);
         if (managed)
             await assertEnrollmentComplete(tx, nodeId, node.hostname);
         return managed ? 'managed' : 'legacy';

package/dist/services/node-issue-monitor.js

@@ -49,6 +49,8 @@ async function checkStaleNodes() {
                 },
             }, maintenance?.id ?? null);
         });
+        // An agent that went silent mid-upgrade must not stay UPDATING.
+        await import('./agent-upgrade-service.js').then(service => service.clearAgentUpdating(node.id)).catch(() => undefined);
     }
     recordMonitorPulse('nodes');
 }

package/dist/services/resource-enrollment.js

@@ -24,9 +24,13 @@ export function canonical(value) {
 }
 export function enrollmentSigningPayload(value) { return 'magnus.resource-enrollment.v1\n' + canonical(value); }
 function fail(code, message) { throw new HttpError(409, code, message); }
+/** Read-only predicate shared with upgrade eligibility: the enrollment row admits resource execution. */
+export function enrollmentIsComplete(row, nodeFqdn) {
+    return Boolean(row) && row.state === 'enrolled' && row.nodeFqdn === nodeFqdn;
+}
 export async function assertEnrollmentComplete(tx, nodeId, nodeFqdn) {
     const row = await tx.resourceEnrollment.findUnique({ where: { nodeId } });
-    if (!row || row.state !== 'enrolled' || row.nodeFqdn !== nodeFqdn)
+    if (!enrollmentIsComplete(row, nodeFqdn))
         fail('RESOURCE_ENROLLMENT_REQUIRED', 'Verified participant drain enrollment is required before resource execution');
 }
 export function dashboardEnrollmentSecret() {
@@ -105,7 +109,9 @@ export async function inspectEnrollment(nodeId) {
             apiBlockers: row?.state === 'enrolled' || participants.some(p => p.participant === 'api' && p.status === 'verified' && p.epoch === row?.epoch
                 && p.challengeExpiresAt.getTime() > Date.now()) ? [] :
                 ['preinstrumentation-work-unverified', 'local-descendants-unverified', 'noninventory-bootstrap-unsupported', 'ssh-descendants-unverified'],
-            dashboard: await participantSnapshot(tx, nodeId, 'dashboard') };
+            dashboard: await participantSnapshot(tx, nodeId, 'dashboard'),
+            // Since this process started; empty after a restart.
+            lastFailures: lastParticipantFailures(nodeId) };
     });
 }
 export const drainDescriptorSchema = z.object({ version: z.literal(1), participant: z.enum(PARTICIPANTS),
@@ -145,11 +151,46 @@ export const apiDrainAttestationSchema = drainDescriptorSchema.extend({
 export function apiDrainAttestationSigningPayload(value) {
     return 'magnus.resource-enrollment-api-attestation.v1\n' + canonical(value);
 }
+/**
+ * Response bounds. Drain receipts are small, except the scheduler's: it lists
+ * up to 1024 external blockers (schema maximum), each about 200 bytes of JSON
+ * (an 80-character kind, a 64-hex digest, a count and the keys), so a control
+ * host with many system timers needs about 210 KiB. 256 KiB covers that with
+ * margin and stays bounded.
+ */
+export const PARTICIPANT_RECEIPT_LIMITS = { default: 16_384, scheduler: 256 * 1024 };
+/** A participant refresh that failed, as a fixed reason code (never the raw provider error or body). */
+export class ParticipantEvidenceError extends Error {
+    code;
+    agentCode;
+    constructor(code, agentCode = null) {
+        super(code);
+        this.code = code;
+        this.agentCode = agentCode;
+    }
+}
+const failures = new Map();
+/** The last refresh failure of each participant on a node, as seen by this server process. */
+export function lastParticipantFailures(nodeId) {
+    return [...failures.entries()].filter(([key]) => key.startsWith(`${nodeId}\n`)).map(([, value]) => value);
+}
 /** Bounded response consumption, including dishonest or absent content-length. */
-async function readReceipt(response) {
+export async function readParticipantReceipt(response, limit = PARTICIPANT_RECEIPT_LIMITS.default) {
     if (response.status !== 200 || !response.body) {
-        await response.body?.cancel().catch(() => undefined);
-        throw new Error('Participant response unavailable');
+        // An optional machine-readable code from the participant (`{ error: { code } }`) is kept; nothing else is.
+        let agentCode = null;
+        if (response.body && response.status >= 400) {
+            const text = await response.text().catch(() => '');
+            try {
+                const code = JSON.parse(text.slice(0, 4096))?.error?.code;
+                if (typeof code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(code))
+                    agentCode = code;
+            }
+            catch { /* no code */ }
+        }
+        else
+            await response.body?.cancel().catch(() => undefined);
+        throw new ParticipantEvidenceError(`participant-http-${response.status}`, agentCode);
     }
     const reader = response.body.getReader();
     const chunks = [];
@@ -160,11 +201,16 @@ async function readReceipt(response) {
             if (done)
                 break;
             size += value.byteLength;
-            if (size > 16_384)
-                throw new Error('Participant response exceeded bound');
+            if (size > limit)
+                throw new ParticipantEvidenceError('participant-response-too-large');
             chunks.push(value);
         }
-        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        try {
+            return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            throw new ParticipantEvidenceError('participant-response-invalid');
+        }
     }
     finally {
         await reader.cancel().catch(() => undefined);
@@ -197,9 +243,9 @@ export async function refreshEnrollmentParticipant(nodeId, participant) {
         if (participant === 'agent' || participant === 'scheduler') {
             key = RESULT_SIGNING_SECRET;
             if (key.length < 32)
-                throw new Error('Agent receipt credential unavailable');
+                throw new ParticipantEvidenceError('receipt-credential-unavailable');
             if (new URL(prepared.baseUrl).protocol !== 'https:')
-                throw new Error('Verified HTTPS agent endpoint required');
+                throw new ParticipantEvidenceError('https-endpoint-required');
             url = prepared.baseUrl.replace(/\/$/, '') + (participant === 'scheduler'
                 ? '/api/v1/cron/enrollment-drain' : '/api/v1/commands/enrollment-drain');
             headers = { 'x-node-token': getNodeManagerSecret() };
@@ -208,14 +254,18 @@ export async function refreshEnrollmentParticipant(nodeId, participant) {
             key = dashboardEnrollmentSecret();
             const origin = new URL(process.env['DASHBOARD_PUBLIC_ORIGIN'] ?? '');
             if (origin.protocol !== 'https:' || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash)
-                throw new Error('Fixed HTTPS dashboard origin unavailable');
+                throw new ParticipantEvidenceError('dashboard-origin-unavailable');
             url = origin.origin + '/api/internal/resource-enrollment/drain';
             headers = { 'x-resource-drain-key': key };
         }
         const response = await fetch(url, { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(participant !== 'dashboard' ? 25_000 : 5_000),
-            headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify(prepared.descriptor) });
-        const raw = await readReceipt(response);
-        receipt = participant === 'scheduler' ? schedulerBoundaryReceiptSchema.parse(raw) : drainReceiptSchema.parse(raw);
+            headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify(prepared.descriptor) })
+            .catch(() => { throw new ParticipantEvidenceError('participant-unreachable'); });
+        const raw = await readParticipantReceipt(response, participant === 'scheduler' ? PARTICIPANT_RECEIPT_LIMITS.scheduler : PARTICIPANT_RECEIPT_LIMITS.default);
+        const parsed = participant === 'scheduler' ? schedulerBoundaryReceiptSchema.safeParse(raw) : drainReceiptSchema.safeParse(raw);
+        if (!parsed.success)
+            throw new ParticipantEvidenceError('participant-receipt-invalid');
+        receipt = parsed.data;
         const { signature, ...unsigned } = receipt;
         const { status: _status, activeCount: _active, unknownCount: _unknown, evidenceSha256: _evidence, ...remaining } = unsigned;
         const descriptor = participant === 'scheduler'
@@ -223,12 +273,17 @@ export async function refreshEnrollmentParticipant(nodeId, participant) {
             : remaining;
         if (canonical(descriptor) !== canonical(prepared.descriptor) || receipt.expiresAt <= Date.now()
             || !timingSafeEqual(Buffer.from(signature, 'hex'), createHmac('sha256', key).update(enrollmentSigningPayload(unsigned)).digest()))
-            throw new Error('Participant receipt failed exact challenge authentication');
+            throw new ParticipantEvidenceError('participant-receipt-unauthenticated');
     }
-    catch {
-        // No raw provider error/body is exposed. Outstanding challenge remains pending.
-        return { participant, status: 'pending', reason: 'participant-evidence-unavailable' };
+    catch (error) {
+        // No raw provider error/body is exposed, only a fixed cause (and the participant's own code, if it sent one).
+        // Outstanding challenge remains pending.
+        const cause = error instanceof ParticipantEvidenceError ? error.code : 'participant-evidence-unavailable';
+        const agentCode = error instanceof ParticipantEvidenceError ? error.agentCode : null;
+        failures.set(`${nodeId}\n${participant}`, { participant, cause, agentCode, at: new Date().toISOString() });
+        return { participant, status: 'pending', reason: 'participant-evidence-unavailable', cause, agentCode };
     }
+    failures.delete(`${nodeId}\n${participant}`);
     return getDb().$transaction(async (tx) => {
         await lockResourceNode(tx, nodeId);
         const { row } = await identity(tx, nodeId);

package/dist/services/resource-ownership.js

@@ -0,0 +1,20 @@
+export async function readOwnershipHistory(tx, nodeId) {
+    const [lease, managedCron, participantWork] = await Promise.all([
+        tx.commandResourceLease.findFirst({ where: { nodeId }, select: { id: true } }),
+        tx.managedCronDefinition.findFirst({ where: { nodeId }, select: { cronJobId: true } }),
+        tx.resourceParticipantWork.findFirst({ where: { nodeId }, select: { workId: true } }),
+    ]);
+    return { lease: Boolean(lease), managedCron: Boolean(managedCron), participantWork: Boolean(participantWork) };
+}
+/** The sticky rule: what legacy-admission tells an agent (`enrolled`) and what managed cron requires. */
+export function stickyEnrollmentObserved(enrollment, history) {
+    return Boolean(enrollment && enrollment.state !== 'legacy') || history.lease || history.managedCron || history.participantWork;
+}
+/** Why the sticky rule holds, for operator-facing reasons. */
+export function stickyEnrollmentCause(enrollment, history) {
+    const causes = [enrollment && enrollment.state !== 'legacy' ? `a ${enrollment.state} enrollment` : null,
+        history.lease ? 'command lease history' : null, history.managedCron ? 'managed cron history' : null,
+        history.participantWork ? 'participant work history' : null].filter(Boolean);
+    return causes.length ? causes.join(', ') : null;
+}
+//# sourceMappingURL=resource-ownership.js.map

package/dist/utils/runtime-file.js

@@ -1,4 +1,4 @@
-import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { magnusHome } from './magnus-home.js';
 /**
@@ -8,6 +8,7 @@ import { magnusHome } from './magnus-home.js';
 export function runtimeFilePath(env = process.env) {
     return env['MAGNUS_RUNTIME_FILE']?.trim() || join(magnusHome(env), 'run', 'server-runtime.json');
 }
+/** `host` is the bind address, so tooling probes the address the server listens on. */
 export function writeRuntimeFile(details, env = process.env) {
     const path = runtimeFilePath(env);
     try {
@@ -20,4 +21,27 @@ export function writeRuntimeFile(details, env = process.env) {
         console.warn(`[startup] could not write ${path}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+/** The server this runtime file names, when its process is still alive on this host. */
+export function runningServer(env = process.env) {
+    const path = runtimeFilePath(env);
+    if (!existsSync(path))
+        return null;
+    try {
+        const info = JSON.parse(readFileSync(path, 'utf8'));
+        const pid = Number(info.pid);
+        if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid)
+            return null;
+        try {
+            process.kill(pid, 0);
+        }
+        catch (error) {
+            if (error.code !== 'EPERM')
+                return null;
+        }
+        return { pid, version: String(info.version ?? 'unknown') };
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=runtime-file.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemagnus/magnus-server",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "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.1.2",
+    "@hivemagnus/magnus-contracts": "1.1.3",
     "@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.1.2",
+    "@hivemagnus/magnus-skills": "1.1.3",
     "prisma": "^7.10.1"
   },
   "devDependencies": {