@hivemagnus/magnus-agent 1.1.7 → 1.1.8

package/dist/executors/cron-manager.js

@@ -12,6 +12,9 @@ import { HOST_FQDN, NODE_MANAGER_SECRET, RESULT_SIGNING_SECRET } from '../env.js
 import { readdir, readFile } from 'node:fs/promises';
 import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
 import { stableCodePath } from '../upgrade/stable-path.js';
+import { logger } from '../utils/logger.js';
+/** Routes answer with a fixed code; the cause goes to the log. */
+const warnCause = (what, error) => logger.warn(`${what} failed: ${error instanceof Error ? error.message : String(error)}`);
 export const cronRoutes = new Hono();
 const scheduler = new ManagedScheduler();
 const execFileAsync = promisify(execFile);
@@ -108,7 +111,8 @@ cronRoutes.get('/os-scheduler-writer-proof', async (c) => {
         c.header('Cache-Control', 'no-store');
         return c.json({ success: true, data: { ...receipt, signature } });
     }
-    catch {
+    catch (error) {
+        warnCause('Writer proof', error);
         return c.json({ success: false, error: { code: 'WRITER_PROOF_UNAVAILABLE' } }, 409);
     }
 });
@@ -120,6 +124,7 @@ cronRoutes.get('/', async (c) => {
         return c.json({ success: true, data: jobs });
     }
     catch {
+        // no-reason-needed: `crontab -l` fails the same way for a user with no crontab, which is the common answer
         return c.json({ success: true, data: [] });
     }
 });
@@ -147,6 +152,7 @@ cronRoutes.get('/all-users', async (c) => {
         return c.json({ success: true, data: allJobs });
     }
     catch {
+        // no-reason-needed: `crontab -l` fails the same way for a user with no crontab, which is the common answer
         return c.json({ success: true, data: [] });
     }
 });
@@ -183,7 +189,8 @@ cronRoutes.post('/enrollment-stage', async (c) => {
         return c.json({ success: true, data: { ...receipt, receiptSignature: createHmac('sha256', RESULT_SIGNING_SECRET)
                     .update(cronEnrollmentStageReceiptPayload(receipt)).digest('hex') } });
     }
-    catch {
+    catch (error) {
+        warnCause('Enrollment stage', error);
         return c.json({ success: false, error: { code: 'CRON_ENROLLMENT_STAGE_CONFLICT' } }, 409);
     }
 });
@@ -195,7 +202,8 @@ cronRoutes.get('/source-reconciliation/:decisionId', async (c) => {
         c.header('Cache-Control', 'no-store');
         return c.json({ success: true, data: receipt });
     }
-    catch {
+    catch (error) {
+        warnCause('Scheduler reconciliation lookup', error);
         return c.json({ success: false, error: { code: 'SCHEDULER_RECONCILIATION_NOT_FOUND' } }, 404);
     }
 });
@@ -230,7 +238,8 @@ cronRoutes.post('/source-reconciliation', async (c) => {
         c.header('Cache-Control', 'no-store');
         return c.json({ success: true, data: settled.receipt });
     }
-    catch {
+    catch (error) {
+        warnCause('Scheduler reconciliation', error);
         return c.json({ success: false, error: { code: 'SCHEDULER_RECONCILIATION_CONFLICT' } }, 409);
     }
 });
@@ -257,7 +266,8 @@ cronRoutes.post('/sync', async (c) => {
         });
         return c.json({ success: true, data: { name: job.name, schedule: job.schedule, command: job.command, synced: true, managed: false } });
     }
-    catch {
+    catch (error) {
+        warnCause('Cron sync', error);
         return c.json({ success: false, error: { code: 'CRON_SYNC_ERROR' } }, 500);
     }
 });
@@ -285,7 +295,8 @@ cronRoutes.post('/managed-sync', async (c) => {
         return c.json({ success: true, data: { nodeFqdn: HOST_FQDN, name: job.spec.name, jobId: job.jobId,
                 revision: job.spec.revision, specSha256: job.specSha256, staged: true, enabled: false } });
     }
-    catch {
+    catch (error) {
+        warnCause('Cron sync', error);
         return c.json({ success: false, error: { code: 'CRON_SYNC_ERROR', message: 'Managed cron installation incomplete; inspect durable definition before retry' } }, 500);
     }
 });
@@ -310,7 +321,8 @@ cronRoutes.post('/managed-activate', async (c) => {
         });
         return c.json({ success: true, data: { ...parsed.data, activated: true, enabled: true } });
     }
-    catch {
+    catch (error) {
+        warnCause('Managed cron activation', error);
         return c.json({ success: false, error: { code: 'CRON_ACTIVATION_ERROR', message: 'Managed cron activation was not acknowledged' } }, 500);
     }
 });
@@ -333,7 +345,8 @@ cronRoutes.post('/managed-revoke', async (c) => {
         });
         return c.json({ success: true, data: { ...parsed.data, revoked: true, enabled: false } });
     }
-    catch {
+    catch (error) {
+        warnCause('Managed cron revocation', error);
         return c.json({ success: false, error: { code: 'CRON_REVOCATION_ERROR', message: 'Managed cron revocation was not acknowledged' } }, 500);
     }
 });
@@ -349,7 +362,8 @@ cronRoutes.delete('/:name', async (c) => {
         });
         return c.json({ success: true, data: { deleted: true } });
     }
-    catch {
+    catch (error) {
+        warnCause('Cron delete', error);
         return c.json({ success: false, error: { code: 'CRON_DELETE_ERROR' } }, 500);
     }
 });

package/dist/executors/enrollment-drain.js

@@ -56,7 +56,8 @@ enrollmentDrainRoutes.get('/host-local-writer-proof', async (c) => {
         c.header('Cache-Control', 'no-store');
         return c.json({ success: true, data: { ...receipt, signature } });
     }
-    catch {
+    catch (error) {
+        logger.warn('Host-local writer proof failed', { error: error instanceof Error ? error.message : String(error) });
         return c.json({ success: false, error: { code: 'WRITER_PROOF_UNAVAILABLE' } }, 409);
     }
 });
@@ -66,7 +67,8 @@ enrollmentDrainRoutes.get('/mutation-inventory', async (c) => {
         c.header('Cache-Control', 'no-store');
         return c.json({ success: true, data: inventory });
     }
-    catch {
+    catch (error) {
+        logger.warn('Mutation inventory failed', { error: error instanceof Error ? error.message : String(error) });
         return c.json({ success: false, error: { code: 'MUTATION_INVENTORY_UNAVAILABLE',
                 message: 'Retained mutation inventory cannot be validated' } }, 409);
     }

package/dist/executors/managed-http.js

@@ -4,11 +4,13 @@ import { z } from 'zod';
 import { CONTROL_API_URL, HOST_FQDN, NODE_MANAGER_SECRET, RESULT_SIGNING_SECRET, MAGNUS_EXECUTION_SUPERVISOR_ENABLED } from '../env.js';
 import { controlApiFetch } from '../tls.js';
 import { commandLedger, executeBodySchema } from './command-executor.js';
-import { commandFenceSchema, commandRequestDigest, isArdentScopedCommand } from './command-ledger.js';
+import { refusalError, refusalStatus } from './command-refusal.js';
+import { admissionCause, CommandAdmissionError, commandFenceSchema, commandRequestDigest, isArdentScopedCommand } from './command-ledger.js';
 import { managedExecution } from '../security/managed-context.js';
 import { legacyAdmissionResponseSchema, managedClaimSchema, MANAGED_CLAIM_HEADER, httpIdentity, httpReceiptBody } from '../security/managed-http.js';
 import { nativeCompletionDescriptor, nativeCompletionResourceKey } from '../security/native-completion-registry.js';
 import { signCommandResult } from '../security/command-result-signature.js';
+import { logger } from '../utils/logger.js';
 import { mutationBarrier } from './mutation-barrier.js';
 import { recoverSkillPublication } from './skill-publication.js';
 export const managedHttpRequestSchema = z.object({ claim: managedClaimSchema, commandId: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/),
@@ -66,18 +68,39 @@ export const managedMutationGuard = async (c, next) => {
         return next();
     const encoded = c.req.header(MANAGED_CLAIM_HEADER);
     if (path === '/commands/execute' && encoded) {
+        let input;
+        let leaseId;
+        try {
+            leaseId = managedClaimSchema.parse(JSON.parse(encoded)).leaseId;
+        }
+        catch (error) {
+            logger.warn(`Managed command claim does not parse: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const refused = async (code, message) => {
+            // Only a well-formed request can be bound to a signed refusal.
+            const parsed = executeBodySchema.safeParse(input ?? await c.req.json().catch(() => null));
+            const error = parsed.success
+                ? await refusalError({ commandId: parsed.data.commandId, requestSha256: commandRequestDigest(parsed.data), leaseId }, code, message, { notStarted: true })
+                : { code, message };
+            return c.json({ success: false, error }, 409);
+        };
         if (activeLegacy || enrolling)
-            return c.json({ success: false, error: { code: 'RESOURCE_BUSY' } }, 409);
+            return refused('RESOURCE_BUSY', 'Another request owns the node execution slot; nothing ran');
         enrolling = true;
+        let confirmed = false;
         try {
             const claim = managedClaimSchema.parse(JSON.parse(encoded));
-            const input = await c.req.json();
+            input = await c.req.json();
             await confirm(claim, input);
+            confirmed = true;
             return await managedExecution.run({ claim, commandId: input.commandId, requestSha256: commandRequestDigest(input),
                 ...(input.coordination ? { coordination: input.coordination } : {}), signal: c.req.raw.signal }, () => next());
         }
-        catch {
-            return c.json({ success: false, error: { code: 'RESOURCE_CLAIM_INVALID', message: 'A current authoritative resource claim is required' } }, 409);
+        catch (error) {
+            logger.warn(`Managed command claim failed: ${error instanceof Error ? error.message : String(error)}`);
+            const message = 'A current authoritative resource claim is required';
+            // After confirmation the handler may have started: stay uncertain.
+            return confirmed ? c.json({ success: false, error: { code: 'RESOURCE_CLAIM_INVALID', message } }, 409) : refused('RESOURCE_CLAIM_INVALID', message);
         }
         finally {
             enrolling = false;
@@ -117,7 +140,8 @@ export const managedMutationGuard = async (c, next) => {
             && MAGNUS_EXECUTION_SUPERVISOR_ENABLED)
             completed = true;
     }
-    catch {
+    catch (error) {
+        logger.warn(`Mutation ${c.req.method} ${path} ${dispatched ? 'outcome is uncertain' : 'was not admitted'}: ${error instanceof Error ? error.message : String(error)}`);
         return c.json({ success: false,
             error: dispatched
                 ? { code: 'MUTATION_OUTCOME_UNKNOWN', message: 'Mutation outcome is uncertain; reconcile before retrying' }
@@ -142,20 +166,19 @@ export function registerManagedHttp(app) {
         if (value.recoveryOnly && (value.method !== 'POST' || value.path !== '/skills/install'))
             return c.json({ success: false, error: { code: 'INVALID_RECOVERY_ONLY',
                     message: 'Recovery-only execution is limited to exact skill publication evidence' } }, 409);
+        const identity = { ...httpIdentity(value.commandId, value.method, value.path, value.body, value.timeoutSeconds), coordination: value.coordination };
+        const digest = commandRequestDigest(identity);
+        const refuse = async (code, message, details) => c.json({ success: false, error: await refusalError({ commandId: value.commandId, requestSha256: digest, leaseId: value.claim.leaseId }, code, message, details) }, refusalStatus(code));
         const descriptor = nativeCompletionDescriptor(value.method, value.path);
         if (!descriptor)
-            return c.json({ success: false,
-                error: { code: 'UNREVIEWED_MUTATION', message: 'This mutation needs a separately reviewed completion boundary' } }, 409);
+            return refuse('UNREVIEWED_MUTATION', 'This mutation needs a separately reviewed completion boundary', { notStarted: true });
         if (value.timeoutSeconds > descriptor.timeoutCeilingSeconds
             || value.coordination.resourceKey !== nativeCompletionResourceKey(descriptor, value.claim.nodeId))
-            return c.json({ success: false, error: { code: 'UNREVIEWED_MUTATION',
-                    message: 'Native mutation exceeds its reviewed completion or resource boundary' } }, 409);
+            return refuse('UNREVIEWED_MUTATION', 'Native mutation exceeds its reviewed completion or resource boundary', { notStarted: true });
         if (activeLegacy || enrolling)
-            return c.json({ success: false, error: { code: 'RESOURCE_BUSY' } }, 409);
+            return refuse('RESOURCE_BUSY', 'Another request owns the node execution slot; nothing ran', { notStarted: true });
         enrolling = true;
         try {
-            const identity = { ...httpIdentity(value.commandId, value.method, value.path, value.body, value.timeoutSeconds), coordination: value.coordination };
-            const digest = commandRequestDigest(identity);
             const prior = await commandLedger.receipt(value.commandId);
             if (value.recoveryOnly) {
                 if (prior && (prior.requestSha256 !== digest || !['unknown', 'completed'].includes(prior.state)))
@@ -175,8 +198,20 @@ export function registerManagedHttp(app) {
                 const adopted = await commandLedger.settleRecoveredResult(identity, signed, value.claim);
                 return c.json({ success: true, data: { response: recovered, receipt: adopted.result } });
             }
-            await confirm(value.claim, identity);
+            try {
+                await confirm(value.claim, identity);
+            }
+            catch (error) {
+                // Before the ledger: no handler can have started for this request.
+                logger.warn(`Managed request ${value.commandId} was not confirmed: ${error instanceof Error ? error.message : String(error)}`);
+                throw new CommandAdmissionError('RESOURCE_CLAIM_INVALID', 'The server did not confirm the exact resource owner; nothing ran', { notStarted: !prior });
+            }
             let response;
+            const afterSettled = [];
+            const settled = async () => {
+                for (const task of afterSettled.splice(0))
+                    await Promise.resolve().then(task).catch((error) => logger.warn(`After ${value.commandId} settled: ${error instanceof Error ? error.message : String(error)}`));
+            };
             const receipt = await commandLedger.execute(identity, async (digest) => {
                 const start = Date.now();
                 // Durable fence/enrollment/receipt writes may outlast the authority
@@ -196,7 +231,7 @@ export function registerManagedHttp(app) {
                 }
                 else
                     result = await managedExecution.run({ claim: value.claim, commandId: value.commandId, requestSha256: digest,
-                        coordination: value.coordination, signal: c.req.raw.signal }, () => app.request(`http://localhost/api/v1${value.path}`, {
+                        coordination: value.coordination, signal: c.req.raw.signal, afterSettled }, () => app.request(`http://localhost/api/v1${value.path}`, {
                         method: value.method, headers: { 'content-type': 'application/json', 'x-node-token': NODE_MANAGER_SECRET },
                         signal: c.req.raw.signal,
                         ...(value.body ? { body: value.body } : {}),
@@ -233,12 +268,18 @@ export function registerManagedHttp(app) {
                     durationMs: Date.now() - start, truncated: false,
                     coordination: { ...value.coordination, requestSha256: digest } };
                 return { ...signed, signature: signCommandResult(signed, RESULT_SIGNING_SECRET) };
-            }, value.claim);
+            }, value.claim).finally(settled);
             if (!response)
                 return c.json({ success: false, error: { code: 'RESULT_ALREADY_RECORDED', message: 'Read the existing signed receipt without replay' } }, 409);
             return c.json({ success: true, data: { response, receipt } });
         }
-        catch {
+        catch (error) {
+            // A refusal the ledger can name keeps its name; only what is really uncertain is reported as uncertain.
+            if (error instanceof CommandAdmissionError && error.code !== 'OUTCOME_UNKNOWN') {
+                logger.warn(`Managed request ${value.commandId} ${value.method} ${value.path} refused: ${error.code}: ${error.message}${admissionCause(error)}${error.highWater ? ` (${error.highWater.resourceKey} is at fence ${error.highWater.fence}, the request has ${value.coordination.fence})` : ''}`);
+                return refuse(error.code, error.message, { notStarted: error.notStarted, ...(error.highWater ? { highWater: error.highWater } : {}) });
+            }
+            logger.warn(`Managed request ${value.commandId} ${value.method} ${value.path} is uncertain: ${error instanceof Error ? error.message : String(error)}${error instanceof CommandAdmissionError ? admissionCause(error) : ''}`);
             return c.json({ success: false, error: { code: 'MANAGED_MUTATION_UNCERTAIN', message: 'Inspect the exact resource receipt before further work; no automatic replay' } }, 409);
         }
         finally {

package/dist/security/command-result-signature.d.ts

@@ -43,4 +43,46 @@ export interface CommandReconciliationAssertion {
 /** Separate key and domain: a result signer cannot authorize releasing an unknown claim. */
 export declare function commandReconciliationSigningPayload(assertion: Omit<CommandReconciliationAssertion, 'signature'>): string;
 export declare function verifyCommandReconciliation(assertion: CommandReconciliationAssertion, secret: string): boolean;
+/**
+ * A certain refusal: this exact request did not start and has no receipt. Bound
+ * to the request digest, the lease and the node, so it settles nothing else.
+ */
+export interface CommandRefusal {
+    commandId: string;
+    requestSha256: string;
+    code: string;
+    highWater: string | null;
+    nodeFqdn: string;
+    leaseId: string;
+    signature: string;
+}
+export declare function commandRefusalSigningPayload(refusal: Omit<CommandRefusal, 'signature'>): string;
+/**
+ * What this ledger holds about a command right now, bound to the node and a fresh
+ * nonce. Absence means something only next to positive evidence that a ledger is
+ * there at all: its root, the fence high-water and the enrollment marker.
+ */
+export interface CommandAbsence {
+    commandId: string;
+    nodeFqdn: string;
+    nonce: string;
+    ledgerExists: boolean;
+    receipt: boolean;
+    activeLock: boolean;
+    resourceKey: string;
+    fenceHighWater: string | null;
+    markerState: 'absent' | 'present' | 'unknown';
+    markerNodeId: string | null;
+    /** The fence of this command's durable record of a failed admission, if it has one. */
+    admissionFailedFence: string | null;
+    signature: string;
+}
+export declare function commandAbsenceSigningPayload(absence: Omit<CommandAbsence, 'signature'>): string;
+/** The fence high-water a preflight reports, bound to the node and a fresh nonce. Only this can move a server generation. */
+export declare function fenceProofSigningPayload(proof: {
+    nonce: string;
+    nodeFqdn: string;
+    fenceHighWater: Readonly<Record<string, string>>;
+}): string;
+export declare function signCommandEvidence(payload: string, secret: string): string;
 //# sourceMappingURL=command-result-signature.d.ts.map

package/dist/security/command-result-signature.js

@@ -47,4 +47,23 @@ export function verifyCommandReconciliation(assertion, secret) {
     const expected = createHmac('sha256', secret).update(commandReconciliationSigningPayload(assertion)).digest();
     return timingSafeEqual(expected, Buffer.from(assertion.signature, 'hex'));
 }
+export function commandRefusalSigningPayload(refusal) {
+    return JSON.stringify({ domain: 'magnus.command-refusal.v1', commandId: refusal.commandId, requestSha256: refusal.requestSha256,
+        code: refusal.code, highWater: refusal.highWater, nodeFqdn: refusal.nodeFqdn, leaseId: refusal.leaseId });
+}
+export function commandAbsenceSigningPayload(absence) {
+    return JSON.stringify({ domain: 'magnus.command-absence.v1', commandId: absence.commandId, nodeFqdn: absence.nodeFqdn, nonce: absence.nonce,
+        ledgerExists: absence.ledgerExists, receipt: absence.receipt, activeLock: absence.activeLock, resourceKey: absence.resourceKey,
+        fenceHighWater: absence.fenceHighWater, markerState: absence.markerState, markerNodeId: absence.markerNodeId, admissionFailedFence: absence.admissionFailedFence });
+}
+/** The fence high-water a preflight reports, bound to the node and a fresh nonce. Only this can move a server generation. */
+export function fenceProofSigningPayload(proof) {
+    return JSON.stringify({ domain: 'magnus.fence-high-water.v1', nonce: proof.nonce, nodeFqdn: proof.nodeFqdn,
+        fenceHighWater: Object.fromEntries(Object.entries(proof.fenceHighWater).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) });
+}
+export function signCommandEvidence(payload, secret) {
+    if (secret.length < 32)
+        throw new Error('RESULT_SIGNING_SECRET must contain at least 32 characters');
+    return createHmac('sha256', secret).update(payload).digest('hex');
+}
 //# sourceMappingURL=command-result-signature.js.map

package/dist/security/managed-context.d.ts

@@ -7,6 +7,8 @@ export interface ManagedExecutionContext {
     requestSha256: string;
     coordination?: CommandFence;
     signal?: AbortSignal;
+    /** Run once the ledger's terminal receipt for this request is durable, or the attempt ended without one. */
+    afterSettled?: Array<() => void | Promise<void>>;
 }
 /** Process-only trusted context. HTTP callers cannot set this with a header. */
 export declare const managedExecution: AsyncLocalStorage<ManagedExecutionContext>;

package/dist/upgrade/preflight.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What the server needs to know before it touches a node. Read only: nothing
+ * here takes a lock or writes a file, so asking is safe at any time and needs
+ * no lease. The same data, minus the checks against a target, goes out with
+ * every heartbeat, so an operator sees drift long before an upgrade.
+ */
+import type { AgentDiskHealth, AgentLedgerHealth, AgentNpmHealth, AgentUpgradePreflight } from '@hivemagnus/magnus-contracts';
+import type { CommandLedger } from '../executors/command-ledger.js';
+export declare const PREFLIGHT_PROTOCOL = 1;
+type LedgerReader = Pick<CommandLedger, 'health' | 'enrollmentMarker'>;
+export declare function upgradePreflight(options: {
+    version: string;
+    target?: string | undefined;
+    engines?: string | undefined;
+    nonce?: string | undefined;
+    ledger: LedgerReader;
+    env?: NodeJS.ProcessEnv;
+    nodeVersion?: string;
+}): Promise<AgentUpgradePreflight>;
+/** The optional drift fields of a heartbeat's self-upgrade report. An older server ignores them. */
+export declare function heartbeatDrift(ledger: LedgerReader, env?: NodeJS.ProcessEnv): {
+    fenceHighWater?: Record<string, string>;
+    ledger?: AgentLedgerHealth;
+    disk?: AgentDiskHealth;
+    npm: AgentNpmHealth;
+};
+export {};
+//# sourceMappingURL=preflight.d.ts.map

package/dist/upgrade/preflight.js

@@ -0,0 +1,62 @@
+import { HOST_FQDN, RESULT_SIGNING_SECRET } from '../env.js';
+import { fenceProofSigningPayload, signCommandEvidence } from '../security/command-result-signature.js';
+import { logger } from '../utils/logger.js';
+import { diskHealth, engineProblem, installDir, npmHealth, runsVersion, selfUpgradeStatus, unwritablePaths, versionComplete } from './self-upgrade.js';
+export const PREFLIGHT_PROTOCOL = 1;
+const LEDGER_CACHE_MS = 60_000;
+const ledgerReport = (health) => ({ readable: health.readable, activeLock: health.activeLock,
+    nonTerminalReceipts: health.nonTerminalReceipts, unresolvedReceipts: health.unresolvedReceipts, truncated: health.truncated, error: health.error });
+export async function upgradePreflight(options) {
+    const env = options.env ?? process.env;
+    const dir = installDir(env);
+    const status = selfUpgradeStatus(options.version, env);
+    const health = await options.ledger.health();
+    const marker = await options.ledger.enrollmentMarker();
+    if (marker.error)
+        logger.warn(`Local enrollment marker could not be read: ${marker.error}`);
+    const nodeVersion = options.nodeVersion ?? process.versions.node;
+    const range = options.engines?.slice(0, 200) || null;
+    const problem = range ? engineProblem(range, nodeVersion) : null;
+    const blocked = unwritablePaths(dir);
+    const disk = diskHealth(dir);
+    return {
+        preflightProtocol: PREFLIGHT_PROTOCOL,
+        version: options.version,
+        target: options.target?.slice(0, 64) ?? null,
+        layout: status.layout,
+        launcherProtocol: status.launcherProtocol,
+        enabled: status.enabled,
+        reason: status.reason ?? null,
+        reasonCode: status.reasonCode ?? null,
+        writable: { ok: blocked.length === 0, blocked },
+        ...(disk ? { disk } : {}),
+        npm: npmHealth(env),
+        fromVersionComplete: versionComplete(dir, options.version) && runsVersion(dir, options.version),
+        ledger: ledgerReport(health),
+        fenceHighWater: health.fenceHighWater,
+        ...(options.nonce && /^[a-zA-Z0-9-]{16,64}$/.test(options.nonce) && RESULT_SIGNING_SECRET.length >= 32 ? { fenceProof: { nonce: options.nonce, nodeFqdn: HOST_FQDN,
+                signature: signCommandEvidence(fenceProofSigningPayload({ nonce: options.nonce, nodeFqdn: HOST_FQDN, fenceHighWater: health.fenceHighWater }), RESULT_SIGNING_SECRET) } } : {}),
+        managedEnrollment: marker.marker ? { nodeId: marker.marker.nodeId, nodeFqdn: marker.marker.nodeFqdn } : null,
+        managedEnrollmentState: marker.state,
+        engines: { node: nodeVersion, range, compatible: range ? problem === null : null, problem },
+    };
+}
+let cached = null;
+let refreshing = false;
+/** Ledger health for heartbeats: the last scan at once, with a new scan in the background once a minute. */
+function cachedLedgerHealth(ledger, now = Date.now()) {
+    if (!refreshing && (!cached || now - cached.at >= LEDGER_CACHE_MS)) {
+        refreshing = true;
+        void ledger.health().then(health => { cached = { at: Date.now(), health }; }, (error) => {
+            logger.warn(`Ledger health could not be read: ${error instanceof Error ? error.message : String(error)}`);
+        }).finally(() => { refreshing = false; });
+    }
+    return cached?.health ?? null;
+}
+/** The optional drift fields of a heartbeat's self-upgrade report. An older server ignores them. */
+export function heartbeatDrift(ledger, env = process.env) {
+    const health = cachedLedgerHealth(ledger);
+    const disk = diskHealth(installDir(env));
+    return { ...(health ? { fenceHighWater: health.fenceHighWater, ledger: ledgerReport(health) } : {}), ...(disk ? { disk } : {}), npm: npmHealth(env) };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/upgrade/routes.js

@@ -1,12 +1,19 @@
 import { Hono } from 'hono';
 import { agentUpgradeRequestSchema } from '@hivemagnus/magnus-contracts';
+import { managedExecution } from '../security/managed-context.js';
 import { logger } from '../utils/logger.js';
 import { AGENT_VERSION } from '../version.js';
+import { upgradePreflight } from './preflight.js';
 import { EXIT_BACKSTOP_MS, SelfUpgradeError, selfUpgradeStatus, stageUpgrade } from './self-upgrade.js';
 /** Seconds between the reply and the exit that hands over to the launcher. */
 export const RESTART_DELAY_MS = 3_000;
 export const agentUpgradeRoutes = new Hono();
 agentUpgradeRoutes.get('/status', c => c.json({ success: true, data: selfUpgradeStatus(AGENT_VERSION) }));
+// Read only, and a GET, so it needs no lease, no claim and no registry entry. Older agents answer 404.
+agentUpgradeRoutes.get('/preflight', async (c) => {
+    const { commandLedger } = await import('../executors/command-executor.js');
+    return c.json({ success: true, data: await upgradePreflight({ version: AGENT_VERSION, target: c.req.query('target'), engines: c.req.query('engines'), nonce: c.req.query('nonce'), ledger: commandLedger }) });
+});
 agentUpgradeRoutes.post('/', async (c) => {
     const parsed = agentUpgradeRequestSchema.safeParse(await c.req.json().catch(() => null));
     if (!parsed.success) {
@@ -19,9 +26,17 @@ agentUpgradeRoutes.post('/', async (c) => {
             return c.json({ success: true, data: { accepted: true, ...result } });
         logger.info(`Self-upgrade staged: ${result.from} -> ${result.to}; restarting through the launcher`);
         // Reply first; the launcher starts versions/<to> on trial after this process exits.
-        setTimeout(() => process.kill(process.pid, 'SIGTERM'), RESTART_DELAY_MS).unref();
-        // Backstop: a shutdown that hangs must not keep the old version running on the new ./current.
-        setTimeout(() => process.exit(0), EXIT_BACKSTOP_MS).unref();
+        const restart = () => {
+            setTimeout(() => process.kill(process.pid, 'SIGTERM'), RESTART_DELAY_MS).unref();
+            // Backstop: a shutdown that hangs must not keep the old version running on the new ./current.
+            setTimeout(() => process.exit(0), EXIT_BACKSTOP_MS).unref();
+        };
+        // A managed request's terminal receipt is written after this handler returns: the clock starts when it is durable.
+        const managed = managedExecution.getStore();
+        if (managed?.afterSettled)
+            managed.afterSettled.push(restart);
+        else
+            restart();
         return c.json({ success: true, data: { accepted: true, ...result, restartInSeconds: RESTART_DELAY_MS / 1000 } });
     }
     catch (error) {

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

@@ -1,4 +1,4 @@
-import { type AgentSelfUpgradeStatus, type AgentUpgradeReport, type AgentUpgradeRequest } from '@hivemagnus/magnus-contracts';
+import { type AgentDiskHealth, type AgentNpmHealth, type AgentSelfUpgradeStatus, type AgentUpgradeReport, type AgentUpgradeRequest } from '@hivemagnus/magnus-contracts';
 export declare const STATE_FILE = "upgrade-state.json";
 export declare const LOCK_FILE = "upgrade-state.lock";
 /** Written while on trial when heartbeats cannot reach the control API; the launcher then extends the trial. */
@@ -18,6 +18,8 @@ export declare const STEP_TIMEOUT_MS: {
 export declare const STAGE_BUDGET_MS: number;
 /** After staging, the agent exits even if a graceful shutdown hangs. */
 export declare const EXIT_BACKSTOP_MS = 60000;
+/** Free space an upgrade needs in the install directory: the staged install, its npm cache and the new version. */
+export declare const REQUIRED_FREE_BYTES: number;
 export interface UpgradeState {
     state: 'idle' | 'staged' | 'trial' | 'confirmed' | 'reverted' | 'failed';
     from: string | null;
@@ -71,8 +73,13 @@ export interface NpmCommand {
  * often lacks the directory of a version-managed Node.js.
  */
 export declare function resolveNpm(env?: NodeJS.ProcessEnv, execPath?: string): NpmCommand;
+/** The paths in the install directory this agent cannot write, relative to it. */
+export declare function unwritablePaths(dir: string): string[];
+/** Free space of the install directory, or null where the filesystem does not say. */
+export declare function diskHealth(dir: string, requiredBytes?: number): AgentDiskHealth | null;
+export declare function npmHealth(env?: NodeJS.ProcessEnv): AgentNpmHealth;
 /** Whether this agent can upgrade itself, and why not. Reported with every heartbeat. */
-export declare function selfUpgradeStatus(version: string, env?: NodeJS.ProcessEnv): AgentSelfUpgradeStatus;
+export declare function selfUpgradeStatus(version: string, env?: NodeJS.ProcessEnv, execPath?: string): AgentSelfUpgradeStatus;
 /** The upgrade state when `version` is the one on trial. */
 export declare function trialOf(version: string, env?: NodeJS.ProcessEnv): UpgradeState | null;
 /** Tell the launcher this version runs but cannot reach the control API, so it extends the trial instead of reverting. */
@@ -95,16 +102,46 @@ export declare function upgradeLauncher(dir: string, version: string, execPath?:
  */
 export declare function confirmTrial(version: string, env?: NodeJS.ProcessEnv, now?: Date): boolean;
 export declare function pruneVersions(dir: string, keep: ReadonlyArray<string | null>): void;
+/**
+ * The class of a failed npm step, read only from what npm itself says and from
+ * facts the package cannot write. Lifecycle scripts run inside npm, and their
+ * output comes back in the same stream, so free text proves nothing:
+ * - the first `npm error code X` line decides, because npm prints it before it
+ *   repeats any script output. A numeric code, ELIFECYCLE or `npm error command`
+ *   is a script failing, and that is the package's fault whatever it printed.
+ * - a killed npm is recognised by how the process ended (SIGKILL, or status 137
+ *   through a wrapper), never by reading "Killed".
+ * - a full disk that surfaces as a tar or JSON parse error is recognised by
+ *   measuring the disk (`diskLow`), and by npm's own tar warning line.
+ * The limit: a script runs as this account and can kill npm or write to npm's own
+ * stderr. It gains only that a bad package reads as node-level on the nodes it
+ * runs on, and the run then says no node confirmed.
+ */
+export declare function npmFailureCode(output: string, facts?: {
+    signal?: NodeJS.Signals | null;
+    exitCode?: number;
+    diskLow?: boolean;
+}): string;
+/** What a failed write of the state file or the links says: the node, unless the errno says nothing. */
+export declare function switchFailureCode(error: unknown): string;
+/** Output a package controls, made safe for a reason or a log: no control characters, and bounded. */
+export declare function cleanPackageText(text: string, max: number): string;
 export declare class SelfUpgradeError extends Error {
     readonly code: string;
-    readonly status: 400 | 409 | 422 | 500 | 504;
-    constructor(code: string, message: string, status?: 400 | 409 | 422 | 500 | 504);
+    readonly status: 400 | 409 | 422;
+    /**
+     * Always below 500: a thrown SelfUpgradeError means the attempt ended and the
+     * staging was cleaned up, so over managed-http it is a settled, signed result
+     * rather than an uncertain mutation. Anything else that goes wrong stays a 500.
+     */
+    constructor(code: string, message: string, status?: 400 | 409 | 422);
 }
 export interface RunResult {
     code: number;
     stdout: string;
     stderr: string;
     timedOut?: boolean;
+    signal?: NodeJS.Signals | null;
 }
 export interface Runner {
     (command: string, args: readonly string[], options: {