@hivemagnus/magnus-contracts 1.1.7 → 1.1.10

package/dist/ardent.d.ts

@@ -1,4 +1,23 @@
 import { z } from 'zod';
+export declare const ArdentContextAdoptionInputSchema: z.ZodObject<{
+    release_id: z.ZodString;
+    expected_bundle_sha256: z.ZodString;
+    expected_base_sha256: z.ZodString;
+    expected_policy_sha256: z.ZodString;
+    expected_config_sha256: z.ZodString;
+}, z.core.$strict>;
+export declare const ArdentContextReleaseSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    engine_version: z.ZodLiteral<"0.1.0">;
+    bundle_sha256: z.ZodString;
+    base_sha256: z.ZodString;
+    policy_sha256: z.ZodString;
+    config_sha256: z.ZodString;
+    single_profile: z.ZodBoolean;
+    service_unit_matches: z.ZodBoolean;
+}, z.core.$strict>;
+export type ArdentContextAdoptionInput = z.infer<typeof ArdentContextAdoptionInputSchema>;
+export type ArdentContextRelease = z.infer<typeof ArdentContextReleaseSchema>;
 export declare const ArdentProfileSummarySchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;

package/dist/ardent.js

@@ -1,4 +1,10 @@
 import { z } from 'zod';
+export const ArdentContextAdoptionInputSchema = z.object({ release_id: z.string().guid(),
+    expected_bundle_sha256: z.string().regex(/^[a-f0-9]{64}$/), expected_base_sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    expected_policy_sha256: z.string().regex(/^[a-f0-9]{64}$/), expected_config_sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
+export const ArdentContextReleaseSchema = z.object({ schema_version: z.literal(1), engine_version: z.literal('0.1.0'),
+    bundle_sha256: z.string().regex(/^[a-f0-9]{64}$/), base_sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    policy_sha256: z.string().regex(/^[a-f0-9]{64}$/), config_sha256: z.string().regex(/^[a-f0-9]{64}$/), single_profile: z.boolean(), service_unit_matches: z.boolean() }).strict();
 export const ArdentProfileSummarySchema = z.object({
     id: z.string(), name: z.string(), backend: z.enum(['llamacpp', 'codex']).nullable(),
     apiPort: z.number().int().nullable(), running: z.boolean(), a2aEnabled: z.boolean(),

package/dist/index.d.ts

@@ -154,8 +154,8 @@ export declare const securityFusionSourceSchema: z.ZodEnum<{
     security_console: "security_console";
 }>;
 export declare const securityFusionSeveritySchema: z.ZodEnum<{
-    info: "info";
     low: "low";
+    info: "info";
     medium: "medium";
     high: "high";
     critical: "critical";
@@ -210,8 +210,8 @@ export declare const securityFusionEventSchema: z.ZodObject<{
     kind: z.ZodString;
     observedAt: z.ZodString;
     severity: z.ZodEnum<{
-        info: "info";
         low: "low";
+        info: "info";
         medium: "medium";
         high: "high";
         critical: "critical";
@@ -261,8 +261,8 @@ export declare const securityFusionEventBatchSchema: z.ZodObject<{
         kind: z.ZodString;
         observedAt: z.ZodString;
         severity: z.ZodEnum<{
-            info: "info";
             low: "low";
+            info: "info";
             medium: "medium";
             high: "high";
             critical: "critical";
@@ -408,3 +408,4 @@ export declare const securityInventoryExportSchema: z.ZodObject<{
 export type SecurityInventoryTarget = z.infer<typeof securityInventoryTargetSchema>;
 export type SecurityInventoryExport = z.infer<typeof securityInventoryExportSchema>;
 export * from './release.js';
+export * from './upgrade-remedies.js';

package/dist/index.js

@@ -166,3 +166,4 @@ export const securityInventoryExportSchema = z.object({
     data: z.array(securityInventoryTargetSchema).max(10000),
 });
 export * from './release.js';
+export * from './upgrade-remedies.js';

package/dist/release.d.ts

@@ -179,6 +179,42 @@ export declare const agentManagedEnrollmentSchema: z.ZodObject<{
     nodeId: z.ZodString;
     nodeFqdn: z.ZodString;
 }, z.core.$strip>;
+/** Highest fence the agent's ledger accepted, per resource key. Decimal strings: a fence can exceed 2^53. */
+export declare const fenceHighWaterSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export declare const agentLedgerHealthSchema: z.ZodObject<{
+    readable: z.ZodBoolean;
+    activeLock: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        commandId: z.ZodString;
+        receipt: z.ZodString;
+    }, z.core.$strip>>>;
+    nonTerminalReceipts: z.ZodOptional<z.ZodNumber>;
+    unresolvedReceipts: z.ZodOptional<z.ZodNumber>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const agentDiskHealthSchema: z.ZodObject<{
+    freeBytes: z.ZodNumber;
+    requiredBytes: z.ZodNumber;
+    low: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const agentNpmHealthSchema: z.ZodObject<{
+    present: z.ZodBoolean;
+    version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    problem: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const agentMarkerStateSchema: z.ZodEnum<{
+    unknown: "unknown";
+    present: "present";
+    absent: "absent";
+}>;
+/** Known reasons plus any future one, which the server treats as a problem and not as an expected state. */
+export declare const agentSelfUpgradeReasonCode: z.ZodUnion<readonly [z.ZodEnum<{
+    SWITCHED_OFF: "SWITCHED_OFF";
+    CONTAINER: "CONTAINER";
+    LEGACY_LAYOUT: "LEGACY_LAYOUT";
+    NOT_WRITABLE: "NOT_WRITABLE";
+    NPM: "NPM";
+}>, z.ZodString]>;
 export declare const agentSelfUpgradeStatusSchema: z.ZodObject<{
     protocol: z.ZodNumber;
     launcherProtocol: z.ZodNullable<z.ZodNumber>;
@@ -189,6 +225,13 @@ export declare const agentSelfUpgradeStatusSchema: z.ZodObject<{
     }>;
     enabled: z.ZodBoolean;
     reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    reasonCode: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodEnum<{
+        SWITCHED_OFF: "SWITCHED_OFF";
+        CONTAINER: "CONTAINER";
+        LEGACY_LAYOUT: "LEGACY_LAYOUT";
+        NOT_WRITABLE: "NOT_WRITABLE";
+        NPM: "NPM";
+    }>, z.ZodString]>>>>;
     upgrade: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         state: z.ZodUnion<readonly [z.ZodEnum<{
             failed: "failed";
@@ -210,6 +253,101 @@ export declare const agentSelfUpgradeStatusSchema: z.ZodObject<{
         nodeId: z.ZodString;
         nodeFqdn: z.ZodString;
     }, z.core.$strip>>>;
+    managedEnrollmentState: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        present: "present";
+        absent: "absent";
+    }>>>;
+    fenceHighWater: z.ZodCatch<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    ledger: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        readable: z.ZodBoolean;
+        activeLock: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            commandId: z.ZodString;
+            receipt: z.ZodString;
+        }, z.core.$strip>>>;
+        nonTerminalReceipts: z.ZodOptional<z.ZodNumber>;
+        unresolvedReceipts: z.ZodOptional<z.ZodNumber>;
+        truncated: z.ZodOptional<z.ZodBoolean>;
+        error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    disk: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        freeBytes: z.ZodNumber;
+        requiredBytes: z.ZodNumber;
+        low: z.ZodBoolean;
+    }, z.core.$strip>>>;
+    npm: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        present: z.ZodBoolean;
+        version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        problem: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** The answer of an agent's read-only GET /api/v1/agent-upgrade/preflight. Each field drops alone when malformed, and a newer agent's extras are ignored. */
+export declare const agentUpgradePreflightSchema: z.ZodObject<{
+    preflightProtocol: z.ZodNumber;
+    version: z.ZodString;
+    target: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    layout: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+        versioned: "versioned";
+        legacy: "legacy";
+        container: "container";
+    }>>>;
+    launcherProtocol: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodNumber>>>;
+    enabled: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    reason: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    reasonCode: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodEnum<{
+        SWITCHED_OFF: "SWITCHED_OFF";
+        CONTAINER: "CONTAINER";
+        LEGACY_LAYOUT: "LEGACY_LAYOUT";
+        NOT_WRITABLE: "NOT_WRITABLE";
+        NPM: "NPM";
+    }>, z.ZodString]>>>>;
+    writable: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        ok: z.ZodBoolean;
+        blocked: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    disk: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        freeBytes: z.ZodNumber;
+        requiredBytes: z.ZodNumber;
+        low: z.ZodBoolean;
+    }, z.core.$strip>>>;
+    npm: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        present: z.ZodBoolean;
+        version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        problem: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    fromVersionComplete: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    ledger: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        readable: z.ZodBoolean;
+        activeLock: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            commandId: z.ZodString;
+            receipt: z.ZodString;
+        }, z.core.$strip>>>;
+        nonTerminalReceipts: z.ZodOptional<z.ZodNumber>;
+        unresolvedReceipts: z.ZodOptional<z.ZodNumber>;
+        truncated: z.ZodOptional<z.ZodBoolean>;
+        error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    fenceHighWater: z.ZodCatch<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    managedEnrollment: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        nodeId: z.ZodString;
+        nodeFqdn: z.ZodString;
+    }, z.core.$strip>>>>;
+    managedEnrollmentState: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        present: "present";
+        absent: "absent";
+    }>>>;
+    fenceProof: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        nonce: z.ZodString;
+        nodeFqdn: z.ZodString;
+        signature: z.ZodString;
+    }, z.core.$strip>>>;
+    engines: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        node: z.ZodString;
+        range: z.ZodNullable<z.ZodString>;
+        compatible: z.ZodNullable<z.ZodBoolean>;
+        problem: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export declare const agentUpgradeRequestSchema: z.ZodObject<{
     version: z.ZodString;
@@ -222,6 +360,10 @@ export type AgentUpgradeReport = z.infer<typeof agentUpgradeReportSchema>;
 export type AgentSelfUpgradeStatus = z.infer<typeof agentSelfUpgradeStatusSchema>;
 export type AgentManagedEnrollment = z.infer<typeof agentManagedEnrollmentSchema>;
 export type AgentUpgradeRequest = z.infer<typeof agentUpgradeRequestSchema>;
+export type AgentLedgerHealth = z.infer<typeof agentLedgerHealthSchema>;
+export type AgentDiskHealth = z.infer<typeof agentDiskHealthSchema>;
+export type AgentNpmHealth = z.infer<typeof agentNpmHealthSchema>;
+export type AgentUpgradePreflight = z.infer<typeof agentUpgradePreflightSchema>;
 /** Name for the schema kept aside during a restore. */
 export declare function restoreAsideSchema(now: Date): string;
 /** Moves `public` aside and recreates it with the same owner and privileges. */

package/dist/release.js

@@ -244,16 +244,81 @@ export const agentManagedEnrollmentSchema = z.object({
     nodeId: z.string().min(1).max(128),
     nodeFqdn: z.string().min(1).max(253),
 });
+/** Highest fence the agent's ledger accepted, per resource key. Decimal strings: a fence can exceed 2^53. */
+export const fenceHighWaterSchema = z.record(z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9:._-]{0,199}$/), z.string().regex(/^[0-9]{1,20}$/))
+    .refine(value => Object.keys(value).length <= 64, 'too many fence keys');
+export const agentLedgerHealthSchema = z.object({
+    readable: z.boolean(),
+    /** The command that owns active.lock, and the state of its receipt (`none` when it has no receipt). */
+    activeLock: z.object({ commandId: z.string().max(128), receipt: z.string().max(32) }).nullable().optional(),
+    /** Receipts that are neither completed nor reconciled, and those of them no process is running. */
+    nonTerminalReceipts: z.number().int().nonnegative().optional(),
+    unresolvedReceipts: z.number().int().nonnegative().optional(),
+    /** More receipts than one scan reads: the counts are a lower bound. */
+    truncated: z.boolean().optional(),
+    error: z.string().max(300).nullable().optional(),
+});
+export const agentDiskHealthSchema = z.object({
+    freeBytes: z.number().nonnegative(),
+    requiredBytes: z.number().nonnegative(),
+    low: z.boolean(),
+});
+export const agentNpmHealthSchema = z.object({
+    present: z.boolean(),
+    version: z.string().max(64).nullable().optional(),
+    problem: z.string().max(500).nullable().optional(),
+});
+export const agentMarkerStateSchema = z.enum(['absent', 'present', 'unknown']);
+/** Known reasons plus any future one, which the server treats as a problem and not as an expected state. */
+export const agentSelfUpgradeReasonCode = z.union([z.enum(['SWITCHED_OFF', 'CONTAINER', 'LEGACY_LAYOUT', 'NOT_WRITABLE', 'NPM']), z.string().regex(/^[A-Z][A-Z0-9_]{0,63}$/)]);
 export const agentSelfUpgradeStatusSchema = z.object({
     protocol: z.number().int().nonnegative(),
     launcherProtocol: z.number().int().nonnegative().nullable(),
     layout: z.enum(['versioned', 'legacy', 'container']),
     enabled: z.boolean(),
     reason: z.string().max(1000).nullable().optional(),
+    /** Why self-upgrade is off, for the server; `reason` is for people. Older agents leave it out. */
+    reasonCode: agentSelfUpgradeReasonCode.nullable().optional().catch(undefined),
     upgrade: agentUpgradeReportSchema.nullable().optional(),
     /** Seconds a new version has on trial before the launcher switches back (MAGNUS_AGENT_UPGRADE_CONFIRM_SECONDS). */
     confirmSeconds: z.number().int().positive().max(86_400).nullable().optional(),
     managedEnrollment: agentManagedEnrollmentSchema.nullable().optional(),
+    /** `unknown`: the marker could not be read, which says nothing about a mismatch either way. */
+    managedEnrollmentState: agentMarkerStateSchema.optional().catch(undefined),
+    // Drift evidence from 1.1.8 agents. Each drops alone when malformed, so a bad value never costs the whole report.
+    fenceHighWater: fenceHighWaterSchema.optional().catch(undefined),
+    ledger: agentLedgerHealthSchema.optional().catch(undefined),
+    disk: agentDiskHealthSchema.optional().catch(undefined),
+    npm: agentNpmHealthSchema.optional().catch(undefined),
+});
+/** The answer of an agent's read-only GET /api/v1/agent-upgrade/preflight. Each field drops alone when malformed, and a newer agent's extras are ignored. */
+export const agentUpgradePreflightSchema = z.object({
+    /** Read-only report format. */
+    preflightProtocol: z.number().int().nonnegative(),
+    version: z.string().max(64),
+    target: z.string().max(64).nullable().optional().catch(null),
+    layout: z.enum(['versioned', 'legacy', 'container']).optional().catch(undefined),
+    launcherProtocol: z.number().int().nonnegative().nullable().optional().catch(null),
+    enabled: z.boolean().optional().catch(undefined),
+    reason: z.string().max(1000).nullable().optional().catch(null),
+    reasonCode: agentSelfUpgradeReasonCode.nullable().optional().catch(undefined),
+    writable: z.object({ ok: z.boolean(), blocked: z.array(z.string().max(255)).max(16).optional() }).optional().catch(undefined),
+    disk: agentDiskHealthSchema.optional().catch(undefined),
+    npm: agentNpmHealthSchema.optional().catch(undefined),
+    /** versions/<from> is complete and ./current runs it, so a failed upgrade can switch back. */
+    fromVersionComplete: z.boolean().optional().catch(undefined),
+    ledger: agentLedgerHealthSchema.optional().catch(undefined),
+    fenceHighWater: fenceHighWaterSchema.optional().catch(undefined),
+    managedEnrollment: agentManagedEnrollmentSchema.nullable().optional().catch(null),
+    managedEnrollmentState: agentMarkerStateSchema.optional().catch(undefined),
+    /** `fenceHighWater`, signed by the agent for this nonce. Only a verified proof can move a server generation. */
+    fenceProof: z.object({ nonce: z.string().max(64), nodeFqdn: z.string().max(253), signature: z.string().regex(/^[a-f0-9]{64}$/) }).optional().catch(undefined),
+    engines: z.object({
+        node: z.string().max(64),
+        range: z.string().max(200).nullable(),
+        compatible: z.boolean().nullable(),
+        problem: z.string().max(500).nullable().optional(),
+    }).optional().catch(undefined),
 });
 export const agentUpgradeRequestSchema = z.object({
     version: versionString,

package/dist/upgrade-remedies.d.ts

@@ -0,0 +1,450 @@
+/** `release`: evidence about the release itself. `node`: this node's own state. */
+export type UpgradeFailureClass = 'release' | 'node';
+export interface UpgradeRemedy {
+    class: UpgradeFailureClass;
+    /** Same artifact everywhere: a single occurrence stops the whole run. */
+    stopsRun?: boolean;
+    /** Clears by itself: the run tries the node again at the end of the wave. Never set for ambiguous outcomes. */
+    transient?: boolean;
+    /** The request may have reached the agent: watched by request id, never retried automatically. */
+    ambiguous?: boolean;
+    /** An expected state that does not make a run `partial`, such as a node already on the target. */
+    informational?: boolean;
+    /**
+     * Nodes that all refuse with this, with nothing confirmed, point at what they have in common: the release.
+     * Off for any code that names a node-level cause of its own, which says nothing about the release however many nodes share it.
+     */
+    suspectable?: boolean;
+    /** Not in the catalogue, for example from a newer agent: treated as node-level, and shown as unrecognised. */
+    unknown?: boolean;
+    cause: string;
+    remedy: string;
+}
+export declare const UPGRADE_REMEDIES: {
+    readonly SELF_UPGRADE_INTEGRITY: {
+        readonly class: "release";
+        readonly stopsRun: true;
+        readonly cause: "The downloaded tarball does not match the pinned npm integrity.";
+        readonly remedy: "Do not retry. Check the registry or MAGNUS_AGENT_UPGRADE_SOURCE_DIR, and the integrity passed to the run.";
+    };
+    readonly SELF_UPGRADE_SOURCE: {
+        readonly class: "release";
+        readonly stopsRun: true;
+        readonly cause: "The tarball is missing from MAGNUS_AGENT_UPGRADE_SOURCE_DIR.";
+        readonly remedy: "Copy the exact tarball to that directory on the nodes, then retry.";
+    };
+    readonly SELF_UPGRADE_FAILED: {
+        readonly class: "release";
+        readonly cause: "The package itself failed on the node: a bad tarball, an install error, missing provenance or a smoke test that failed or hung. An agent older than 1.1.8 also reports environment causes this way.";
+        readonly remedy: "Read the detail and the agent log. If several nodes fail the same way, the release is at fault.";
+    };
+    readonly SELF_UPGRADE_REVERTED: {
+        readonly class: "release";
+        readonly cause: "The new version crashed or stayed silent during its trial, and the launcher switched back.";
+        readonly remedy: "Read the reason on the node and in the agent log. To try again, retry with allowRetryReverted (--retry-reverted).";
+    };
+    readonly CONFIRM_TIMEOUT: {
+        readonly class: "release";
+        readonly cause: "The agent accepted the request, but the new version was not confirmed within its trial window.";
+        readonly remedy: "Read the agent log on the node. A later report for this request is still recorded in the run.";
+    };
+    readonly AGENT_SILENT: {
+        readonly class: "release";
+        readonly cause: "The agent accepted the request and then stopped sending heartbeats.";
+        readonly remedy: "Check the service on the node. The launcher switches back by itself if it is running.";
+    };
+    readonly MUTATION_OUTCOME_UNKNOWN: {
+        readonly class: "node";
+        readonly ambiguous: true;
+        readonly cause: "The request was sent and no usable answer came back.";
+        readonly remedy: "The run keeps watching the node by request id. If it never reports, check the node, then reconcile the lease of the request (agent-upgrade-<requestId>).";
+    };
+    readonly MANAGED_MUTATION_UNCERTAIN: {
+        readonly class: "node";
+        readonly ambiguous: true;
+        readonly cause: "The agent cannot say whether a managed request ran. Any version answers this when a handler failed after it may have started; an agent older than 1.1.8 also answers it for every refusal, whatever the real cause. The command lease stays unknown and blocks later managed requests on this node.";
+        readonly remedy: "Read the agent log for the real cause. If the agent holds a receipt for the command (agent-upgrade-<requestId>), settle it with signed evidence: POST /api/v1/commands/<id>/reconcile-resource. If it holds none, an agent older than 1.1.8 offers no way out: upgrade that agent by hand on the node, after which the readiness monitor or `magnus-server agents doctor --heal` can settle the lease. If the cause was a stale fence, first run `magnus-server agents fence NODE VALUE`, or the next request fails the same way.";
+    };
+    readonly OUTCOME_UNKNOWN: {
+        readonly class: "node";
+        readonly ambiguous: true;
+        readonly cause: "The agent ledger holds an unresolved receipt for this command.";
+        readonly remedy: "Inspect the receipt and reconcile it with signed evidence (docs/COMMAND_RESOURCE_LEASES.md).";
+    };
+    readonly RUN_INTERRUPTED: {
+        readonly class: "node";
+        readonly ambiguous: true;
+        readonly cause: "The server stopped watching this node when the run was interrupted.";
+        readonly remedy: "A later report is recorded in the run. If the node does not report, retry it.";
+    };
+    readonly SELF_UPGRADE_ENV_NETWORK: {
+        readonly class: "node";
+        readonly transient: true;
+        readonly cause: "The node could not reach the registry while fetching the new version.";
+        readonly remedy: "Check the path from the node to the registry, or use MAGNUS_AGENT_UPGRADE_SOURCE_DIR, then retry it.";
+    };
+    readonly AGENT_UNREACHABLE: {
+        readonly class: "node";
+        readonly transient: true;
+        readonly cause: "The server could not open a connection to the agent.";
+        readonly remedy: "Check that the agent is running and that its address and port in the inventory are correct.";
+    };
+    readonly SELF_UPGRADE_BUSY: {
+        readonly class: "node";
+        readonly transient: true;
+        readonly cause: "The agent is already staging an upgrade or another process holds its upgrade lock.";
+        readonly remedy: "Wait for it to finish, then retry the node.";
+    };
+    readonly RESOURCE_BUSY: {
+        readonly class: "node";
+        readonly transient: true;
+        readonly cause: "Another command owns the single execution slot on the node.";
+        readonly remedy: "Wait for the command to finish, then retry the node.";
+    };
+    readonly RESOURCE_LEASE_CONFLICT: {
+        readonly class: "node";
+        readonly transient: true;
+        readonly cause: "The server holds another unsettled command lease for the node.";
+        readonly remedy: "Wait for it to settle. If it stays `unknown`, run `magnus-server agents doctor --heal` or reconcile it.";
+    };
+    readonly ENROLLMENT_AUTHORITY_UNAVAILABLE: {
+        readonly class: "node";
+        readonly transient: true;
+        readonly cause: "The agent could not reach the server to confirm its enrollment.";
+        readonly remedy: "Check the path from the node to the server (CONTROL_API_URL, TLS trust).";
+    };
+    readonly STALE_FENCE: {
+        readonly class: "node";
+        readonly transient: true;
+        readonly cause: "The agent holds a resource fence at least as high as the one the server sent, and refused without running anything.";
+        readonly remedy: "The server repairs this by itself by moving its generation up, and tries the node again. Nothing to do unless the problem persists.";
+    };
+    readonly LEASE_EXPIRED: {
+        readonly class: "node";
+        readonly transient: true;
+        readonly cause: "The command lease expired before the agent could start it; nothing ran.";
+        readonly remedy: "Retry the node. If this repeats, compare the clocks of the node and the server.";
+    };
+    readonly NOT_DISPATCHED: {
+        readonly class: "node";
+        readonly transient: true;
+        readonly cause: "The server did not send the request.";
+        readonly remedy: "Read the detail, then retry the node.";
+    };
+    readonly CHECK_FAILED: {
+        readonly class: "node";
+        readonly transient: true;
+        readonly cause: "The server could not check this node right before asking it, so it did not ask.";
+        readonly remedy: "Read the detail, usually a database or Redis problem on the server, then retry the node.";
+    };
+    readonly AGENT_SILENT_AFTER_LOST_REPLY: {
+        readonly class: "node";
+        readonly ambiguous: true;
+        readonly cause: "The request may or may not have arrived, and the agent has stopped sending heartbeats.";
+        readonly remedy: "Check the service on the node. A later report for this request is still recorded in the run.";
+    };
+    readonly FENCE_UNREPORTED: {
+        readonly class: "node";
+        readonly cause: "This agent is older than 1.1.8, has handled managed requests before, and cannot say what fence it holds. If that fence is ahead of the server, its request fails as MANAGED_MUTATION_UNCERTAIN and strands a lease.";
+        readonly remedy: "Before the wave, read .magnus/command-receipts/fence-*.json on the node and run `magnus-server agents fence NODE VALUE`. Nothing to do if the fence is not ahead.";
+    };
+    readonly LEDGER_MISSING: {
+        readonly class: "node";
+        readonly cause: "The agent has no command ledger, so its \"no receipt\" proves nothing about a lease held for it. The ledger may have moved, or the install may have been rebuilt.";
+        readonly remedy: "Check AGENT_INSTALL_DIR and restore .magnus/command-receipts if it moved; the lease then settles by itself. If it is gone, Magnus has no way to settle the lease: establish by hand what the command did, then change the lease row in the database yourself.";
+    };
+    readonly LEDGER_NO_FENCE: {
+        readonly class: "node";
+        readonly cause: "The agent ledger holds neither a fence nor this node's enrollment marker, so nothing shows it is the ledger this command would have used.";
+        readonly remedy: "Check whether .magnus/command-receipts was replaced, and restore it if so; the lease then settles by itself. If it cannot be restored, Magnus has no way to settle the lease: establish by hand what the command did, then change the lease row in the database yourself.";
+    };
+    readonly LEDGER_EVIDENCE_INCONSISTENT: {
+        readonly class: "node";
+        readonly cause: "The agent ledger accepted this lease's fence, but holds no receipt, no claim and no record of a failed admission for it. Either a receipt was removed, or an admission failed on an agent build that kept no such record.";
+        readonly remedy: "Inspect .magnus/command-receipts on the node and the agent log around the lease's time. Magnus has no way to settle the lease: establish by hand what the command did, then change the lease row in the database yourself.";
+    };
+    readonly ENROLLMENT_MARKER_UNKNOWN: {
+        readonly class: "node";
+        readonly cause: "The agent could not read its managed-enrollment marker, so a mismatch cannot be ruled out.";
+        readonly remedy: "Check .magnus/command-receipts/managed-enrollment.json on the node: its mode, owner and content.";
+    };
+    readonly SELF_UPGRADE_ENV_TLS: {
+        readonly class: "node";
+        readonly cause: "npm would not trust the registry's certificate on this node: a wrong clock, an expired certificate or an intercepting proxy.";
+        readonly remedy: "Check the clock on the node and its CA trust for the registry, then retry it.";
+    };
+    readonly SELF_UPGRADE_ENV_AUTH: {
+        readonly class: "node";
+        readonly cause: "The registry refused this node's request (401 or 403).";
+        readonly remedy: "Check the npm credentials and registry settings on the node, or use MAGNUS_AGENT_UPGRADE_SOURCE_DIR, then retry it.";
+    };
+    readonly SELF_UPGRADE_ENV_RESOURCE: {
+        readonly class: "node";
+        readonly cause: "The node ran out of memory or file handles, npm was killed, or a file was busy. A killed npm is told apart by how the process ended; a lifecycle script killed inside npm still reads as a package fault.";
+        readonly remedy: "Check the memory on the node and its kernel log, then retry it.";
+    };
+    readonly RETRY_HELD_SUSPECTED: {
+        readonly class: "node";
+        readonly cause: "The run this one retries stopped because older agents answered ambiguously with nothing confirmed. Each further attempt on an older agent can strand another lease, so this retry leaves them alone.";
+        readonly remedy: "Read the agent log of the nodes that answered, and run `magnus-server agents fence NODE VALUE` where a fence is ahead. Then retry with acknowledgeSuspicion (--acknowledge-suspicion).";
+    };
+    readonly SELF_UPGRADE_ENV_DISK: {
+        readonly class: "node";
+        readonly cause: "The node ran out of disk space or quota, or hit an I/O error, while installing the new version.";
+        readonly remedy: "Free disk space on the node, then retry it.";
+    };
+    readonly SELF_UPGRADE_ENV_ACCESS: {
+        readonly class: "node";
+        readonly cause: "The node refused a write while installing the new version.";
+        readonly remedy: "Run `sudo magnus-agent install-service` again on the node, which repairs ownership, then retry it.";
+    };
+    readonly RESOURCE_ENROLLMENT_REQUIRED: {
+        readonly class: "node";
+        readonly cause: "Admission refused the request because the node's resource enrollment is not complete.";
+        readonly remedy: "Complete the node's resource enrollment (docs/COMMAND_RESOURCE_LEASES.md).";
+    };
+    readonly FENCE_OVERFLOW: {
+        readonly class: "node";
+        readonly cause: "The agent reports a resource fence above the highest value the server will adopt.";
+        readonly remedy: "Stop the agent, inspect .magnus/command-receipts/fence-*.json on the node, and repair that file by hand. The server does not change its generation.";
+    };
+    readonly FENCE_INVALID: {
+        readonly class: "node";
+        readonly cause: "The agent reports a resource fence that is not a decimal value for its own node.";
+        readonly remedy: "Inspect .magnus/command-receipts/fence-*.json on the node.";
+    };
+    readonly FENCE_AHEAD: {
+        readonly class: "node";
+        readonly cause: "The agent holds a resource fence above the server generation, so managed requests would be refused.";
+        readonly remedy: "Nothing to do for an upgrade run: it repairs this at its start. `magnus-server agents doctor --heal` repairs it now.";
+    };
+    readonly IDEMPOTENCY_CONFLICT: {
+        readonly class: "node";
+        readonly cause: "The agent already has a receipt for this command identifier with different input.";
+        readonly remedy: "Retry the node, which uses a new identifier, and report the conflict if it repeats.";
+    };
+    readonly LEDGER_UNAVAILABLE: {
+        readonly class: "node";
+        readonly cause: "The agent could not read or write its command ledger.";
+        readonly remedy: "Check ownership, mode 0700 and free space of .magnus/command-receipts on the node.";
+    };
+    readonly LEDGER_UNRESOLVED: {
+        readonly class: "node";
+        readonly cause: "The agent ledger holds a command with an unresolved outcome, which blocks every later managed request.";
+        readonly remedy: "Reconcile that command with signed evidence (docs/COMMAND_RESOURCE_LEASES.md).";
+    };
+    readonly LEASE_HELD: {
+        readonly class: "node";
+        readonly cause: "A command lease on the node is reserved, running or unknown.";
+        readonly remedy: "Wait for it to finish. On a 1.1.8 agent, a lease stuck `unknown` with no receipt is settled by the readiness monitor, a run, or `magnus-server agents doctor --heal`; one with a receipt needs signed reconciliation. On an older agent, see MANAGED_MUTATION_UNCERTAIN.";
+    };
+    readonly WORK_HELD: {
+        readonly class: "node";
+        readonly cause: "Participant work, such as a console terminal or SSH session, is still held on the node.";
+        readonly remedy: "Finish or reconcile that work, then retry the node.";
+    };
+    readonly UNMANAGED_MUTATION: {
+        readonly class: "node";
+        readonly suspectable: true;
+        readonly cause: "The agent is enrolled for managed requests and refused a request without a valid claim.";
+        readonly remedy: "Complete the node's resource enrollment on the server (docs/COMMAND_RESOURCE_LEASES.md), or upgrade the agent by hand.";
+    };
+    readonly RESOURCE_CLAIM_INVALID: {
+        readonly class: "node";
+        readonly cause: "The server would not confirm the agent's claim for this request.";
+        readonly remedy: "Check the enrollment and inventory host name of the node, then retry.";
+    };
+    readonly RESOURCE_TARGET_INVALID: {
+        readonly class: "node";
+        readonly cause: "Admission refused the node: its inventory address changed or its health is not fresh.";
+        readonly remedy: "Wait for a fresh heartbeat, or repair the inventory address.";
+    };
+    readonly ADMISSION_FENCE_CLOSED: {
+        readonly class: "node";
+        readonly cause: "A server release closed admission to this node.";
+        readonly remedy: "Release the admission fence (POST /api/v1/resource-leases/admission/<nodeId>/release).";
+    };
+    readonly ENROLLMENT_MISSING: {
+        readonly class: "node";
+        readonly cause: "Resource leases apply to this node but it is not enrolled.";
+        readonly remedy: "Enroll the node (docs/COMMAND_RESOURCE_LEASES.md).";
+    };
+    readonly ENROLLMENT_DRAINING: {
+        readonly class: "node";
+        readonly cause: "The node's resource enrollment is stuck in draining.";
+        readonly remedy: "Finish the drain: POST /api/v1/resource-leases/enrollment/<nodeId>/complete.";
+    };
+    readonly ENROLLMENT_HOST_MISMATCH: {
+        readonly class: "node";
+        readonly cause: "The enrollment names another host than the inventory.";
+        readonly remedy: "Correct the host name of the node in the inventory.";
+    };
+    readonly ENROLLMENT_INCOMPLETE: {
+        readonly class: "node";
+        readonly cause: "The node's resource enrollment is not complete.";
+        readonly remedy: "Enroll the node (docs/COMMAND_RESOURCE_LEASES.md).";
+    };
+    readonly ENROLLMENT_MARKER_MISMATCH: {
+        readonly class: "node";
+        readonly cause: "The agent holds a local managed-enrollment marker the server does not share.";
+        readonly remedy: "Complete the node's resource enrollment on the server (docs/COMMAND_RESOURCE_LEASES.md), or upgrade the agent by hand.";
+    };
+    readonly NODE_OFFLINE: {
+        readonly class: "node";
+        readonly transient: true;
+        readonly cause: "The node is offline or has no recent heartbeat.";
+        readonly remedy: "Bring the agent back, then retry the node.";
+    };
+    readonly NODE_NOT_FOUND: {
+        readonly class: "node";
+        readonly cause: "The node is no longer in the inventory.";
+        readonly remedy: "Register the node again if it should be managed.";
+    };
+    readonly VERSION_UNKNOWN: {
+        readonly class: "node";
+        readonly cause: "The agent has not reported a usable version.";
+        readonly remedy: "Wait for a heartbeat, or upgrade the agent by hand.";
+    };
+    readonly SELF_UPGRADE_TIMEOUT: {
+        readonly class: "node";
+        readonly cause: "An npm step of the upgrade did not finish in its time budget on the node. A new version that hangs when it is run reports SELF_UPGRADE_FAILED instead. A lifecycle script that hangs inside npm also ends up here: it cannot be told apart.";
+        readonly remedy: "Check the network and disk speed of the node, then retry it. If every node hangs the same way, suspect the release.";
+    };
+    readonly SELF_UPGRADE_UNAVAILABLE: {
+        readonly class: "node";
+        readonly cause: "The agent cannot upgrade itself now: its layout, launcher, directories or npm are not usable.";
+        readonly remedy: "Read the detail. Running `sudo magnus-agent install-service` once on the node usually repairs it.";
+    };
+    readonly SELF_UPGRADE_LAUNCHER: {
+        readonly class: "node";
+        readonly suspectable: true;
+        readonly cause: "The new version needs a newer launcher than the node has.";
+        readonly remedy: "Run `sudo magnus-agent install-service` once on the node.";
+    };
+    readonly SELF_UPGRADE_ENGINE: {
+        readonly class: "node";
+        readonly suspectable: true;
+        readonly cause: "The new version does not support the Node.js on this node.";
+        readonly remedy: "Upgrade Node.js on the node.";
+    };
+    readonly SELF_UPGRADE_PACKAGE: {
+        readonly class: "node";
+        readonly suspectable: true;
+        readonly cause: "The agent refused to install a package other than magnus-agent.";
+        readonly remedy: "Report this: the server sent an unexpected package name.";
+    };
+    readonly SELF_UPGRADE_REFUSED: {
+        readonly class: "node";
+        readonly suspectable: true;
+        readonly cause: "The agent refused the version change.";
+        readonly remedy: "Read the detail. Crossing a major version is done by hand.";
+    };
+    readonly PREFLIGHT_NOT_WRITABLE: {
+        readonly class: "node";
+        readonly cause: "The agent cannot write to its install directory.";
+        readonly remedy: "Run `sudo magnus-agent install-service` again on the node, which repairs ownership.";
+    };
+    readonly PREFLIGHT_DISK_LOW: {
+        readonly class: "node";
+        readonly cause: "The install directory has less free space than an upgrade needs.";
+        readonly remedy: "Free disk space on the node.";
+    };
+    readonly PREFLIGHT_NPM: {
+        readonly class: "node";
+        readonly cause: "npm is missing on the node or too old.";
+        readonly remedy: "Install npm beside the agent's Node.js, or set MAGNUS_AGENT_NPM.";
+    };
+    readonly PREFLIGHT_FROM_INCOMPLETE: {
+        readonly class: "node";
+        readonly cause: "The running version is not complete under versions/, so a failed upgrade could not switch back.";
+        readonly remedy: "Run `sudo magnus-agent install-service` again on the node.";
+    };
+    readonly PREFLIGHT_ENGINE: {
+        readonly class: "node";
+        readonly cause: "The target version does not support the Node.js on this node.";
+        readonly remedy: "Upgrade Node.js on the node.";
+    };
+    readonly NOT_REACHED: {
+        readonly class: "node";
+        readonly cause: "The run ended before it reached this node.";
+        readonly remedy: "Retry the run, once what ended it is dealt with. This node was not asked and did not change.";
+    };
+    readonly RUN_STOPPED: {
+        readonly class: "node";
+        readonly cause: "Someone stopped the run before it reached this node.";
+        readonly remedy: "Retry the run when you want this node upgraded. This node was not asked and did not change.";
+    };
+    readonly NOT_ELIGIBLE: {
+        readonly class: "node";
+        readonly cause: "This node became ineligible at its turn, for a reason without a code of its own.";
+        readonly remedy: "Read the detail, then retry the node.";
+    };
+    readonly ALREADY_CURRENT: {
+        readonly class: "node";
+        readonly informational: true;
+        readonly cause: "The node already runs the target version.";
+        readonly remedy: "Nothing to do.";
+    };
+    readonly SELF_UPGRADE_CURRENT: {
+        readonly class: "node";
+        readonly informational: true;
+        readonly cause: "The agent already runs the target version.";
+        readonly remedy: "Nothing to do.";
+    };
+    readonly DOWNGRADE: {
+        readonly class: "node";
+        readonly informational: true;
+        readonly cause: "The node runs a newer version than the target.";
+        readonly remedy: "Nothing to do, or choose a newer target.";
+    };
+    readonly MAJOR_VERSION: {
+        readonly class: "node";
+        readonly informational: true;
+        readonly cause: "The change crosses a major version.";
+        readonly remedy: "Upgrade this node by hand.";
+    };
+    readonly NOT_SELF_UPGRADABLE: {
+        readonly class: "node";
+        readonly informational: true;
+        readonly cause: "This agent cannot upgrade itself: it is too old, or not set up with the launcher.";
+        readonly remedy: "Run `sudo magnus-agent install-service` once on the node.";
+    };
+    readonly PROTOCOL_TOO_OLD: {
+        readonly class: "node";
+        readonly informational: true;
+        readonly cause: "The agent speaks an older self-upgrade protocol.";
+        readonly remedy: "Upgrade this agent by hand.";
+    };
+    readonly SELF_UPGRADE_DISABLED: {
+        readonly class: "node";
+        readonly informational: true;
+        readonly cause: "An operator switched self-upgrade off on this node, or it runs in a container or the legacy layout.";
+        readonly remedy: "Nothing to do if that is intended. Otherwise set MAGNUS_AGENT_SELF_UPGRADE=true, pull a newer image, or run `sudo magnus-agent install-service` once.";
+    };
+    readonly UPGRADE_IN_PROGRESS: {
+        readonly class: "node";
+        readonly cause: "An upgrade is staged or on trial on this node, and it can still switch back.";
+        readonly remedy: "Wait for its trial to end, then retry the node if it did not confirm.";
+    };
+    readonly ALREADY_REVERTED: {
+        readonly class: "node";
+        readonly cause: "This node already switched back from this exact version.";
+        readonly remedy: "Read the reason. To try again, use allowRetryReverted (--retry-reverted).";
+    };
+    readonly PREFLIGHT_UNAVAILABLE: {
+        readonly class: "node";
+        readonly informational: true;
+        readonly cause: "An agent older than 1.1.8 has no preflight check; heartbeat data is used instead.";
+        readonly remedy: "Nothing to do: the agent gains the check when it is upgraded.";
+    };
+    readonly PREFLIGHT_UNREACHABLE: {
+        readonly class: "node";
+        readonly informational: true;
+        readonly cause: "The preflight check got no answer. The node stays in the run, and dispatch decides.";
+        readonly remedy: "Nothing to do unless the node then fails with AGENT_UNREACHABLE.";
+    };
+};
+export type UpgradeProblemCode = keyof typeof UPGRADE_REMEDIES;
+/** Cause and remedy for a code; an unknown code (a newer agent, an unexpected 4xx) is a node-level problem. */
+export declare function upgradeRemedy(code: string | null | undefined): UpgradeRemedy;
+export declare const upgradeFailureClass: (code: string | null | undefined) => UpgradeFailureClass;

package/dist/upgrade-remedies.js

@@ -0,0 +1,95 @@
+// The one table of agent upgrade problem codes. The server sorts failures with
+// it, and the console, the CLI and UPGRADING.md show its cause and remedy.
+// Dependency-free so browser code can import it through
+// `@hivemagnus/magnus-contracts/upgrade-remedies`.
+export const UPGRADE_REMEDIES = {
+    // Release evidence.
+    SELF_UPGRADE_INTEGRITY: { class: 'release', stopsRun: true, cause: 'The downloaded tarball does not match the pinned npm integrity.', remedy: 'Do not retry. Check the registry or MAGNUS_AGENT_UPGRADE_SOURCE_DIR, and the integrity passed to the run.' },
+    SELF_UPGRADE_SOURCE: { class: 'release', stopsRun: true, cause: 'The tarball is missing from MAGNUS_AGENT_UPGRADE_SOURCE_DIR.', remedy: 'Copy the exact tarball to that directory on the nodes, then retry.' },
+    SELF_UPGRADE_FAILED: { class: 'release', cause: 'The package itself failed on the node: a bad tarball, an install error, missing provenance or a smoke test that failed or hung. An agent older than 1.1.8 also reports environment causes this way.', remedy: 'Read the detail and the agent log. If several nodes fail the same way, the release is at fault.' },
+    SELF_UPGRADE_REVERTED: { class: 'release', cause: 'The new version crashed or stayed silent during its trial, and the launcher switched back.', remedy: 'Read the reason on the node and in the agent log. To try again, retry with allowRetryReverted (--retry-reverted).' },
+    CONFIRM_TIMEOUT: { class: 'release', cause: 'The agent accepted the request, but the new version was not confirmed within its trial window.', remedy: 'Read the agent log on the node. A later report for this request is still recorded in the run.' },
+    AGENT_SILENT: { class: 'release', cause: 'The agent accepted the request and then stopped sending heartbeats.', remedy: 'Check the service on the node. The launcher switches back by itself if it is running.' },
+    // Ambiguous: the request may have run.
+    MUTATION_OUTCOME_UNKNOWN: { class: 'node', ambiguous: true, cause: 'The request was sent and no usable answer came back.', remedy: 'The run keeps watching the node by request id. If it never reports, check the node, then reconcile the lease of the request (agent-upgrade-<requestId>).' },
+    MANAGED_MUTATION_UNCERTAIN: { class: 'node', ambiguous: true, cause: 'The agent cannot say whether a managed request ran. Any version answers this when a handler failed after it may have started; an agent older than 1.1.8 also answers it for every refusal, whatever the real cause. The command lease stays unknown and blocks later managed requests on this node.', remedy: 'Read the agent log for the real cause. If the agent holds a receipt for the command (agent-upgrade-<requestId>), settle it with signed evidence: POST /api/v1/commands/<id>/reconcile-resource. If it holds none, an agent older than 1.1.8 offers no way out: upgrade that agent by hand on the node, after which the readiness monitor or `magnus-server agents doctor --heal` can settle the lease. If the cause was a stale fence, first run `magnus-server agents fence NODE VALUE`, or the next request fails the same way.' },
+    OUTCOME_UNKNOWN: { class: 'node', ambiguous: true, cause: 'The agent ledger holds an unresolved receipt for this command.', remedy: 'Inspect the receipt and reconcile it with signed evidence (docs/COMMAND_RESOURCE_LEASES.md).' },
+    RUN_INTERRUPTED: { class: 'node', ambiguous: true, cause: 'The server stopped watching this node when the run was interrupted.', remedy: 'A later report is recorded in the run. If the node does not report, retry it.' },
+    // Node-level and transient: tried again at the end of the wave.
+    SELF_UPGRADE_ENV_NETWORK: { class: 'node', transient: true, cause: 'The node could not reach the registry while fetching the new version.', remedy: 'Check the path from the node to the registry, or use MAGNUS_AGENT_UPGRADE_SOURCE_DIR, then retry it.' },
+    AGENT_UNREACHABLE: { class: 'node', transient: true, cause: 'The server could not open a connection to the agent.', remedy: 'Check that the agent is running and that its address and port in the inventory are correct.' },
+    SELF_UPGRADE_BUSY: { class: 'node', transient: true, cause: 'The agent is already staging an upgrade or another process holds its upgrade lock.', remedy: 'Wait for it to finish, then retry the node.' },
+    RESOURCE_BUSY: { class: 'node', transient: true, cause: 'Another command owns the single execution slot on the node.', remedy: 'Wait for the command to finish, then retry the node.' },
+    RESOURCE_LEASE_CONFLICT: { class: 'node', transient: true, cause: 'The server holds another unsettled command lease for the node.', remedy: 'Wait for it to settle. If it stays `unknown`, run `magnus-server agents doctor --heal` or reconcile it.' },
+    ENROLLMENT_AUTHORITY_UNAVAILABLE: { class: 'node', transient: true, cause: 'The agent could not reach the server to confirm its enrollment.', remedy: 'Check the path from the node to the server (CONTROL_API_URL, TLS trust).' },
+    STALE_FENCE: { class: 'node', transient: true, cause: 'The agent holds a resource fence at least as high as the one the server sent, and refused without running anything.', remedy: 'The server repairs this by itself by moving its generation up, and tries the node again. Nothing to do unless the problem persists.' },
+    LEASE_EXPIRED: { class: 'node', transient: true, cause: 'The command lease expired before the agent could start it; nothing ran.', remedy: 'Retry the node. If this repeats, compare the clocks of the node and the server.' },
+    NOT_DISPATCHED: { class: 'node', transient: true, cause: 'The server did not send the request.', remedy: 'Read the detail, then retry the node.' },
+    CHECK_FAILED: { class: 'node', transient: true, cause: 'The server could not check this node right before asking it, so it did not ask.', remedy: 'Read the detail, usually a database or Redis problem on the server, then retry the node.' },
+    // Node-level: needs someone.
+    AGENT_SILENT_AFTER_LOST_REPLY: { class: 'node', ambiguous: true, cause: 'The request may or may not have arrived, and the agent has stopped sending heartbeats.', remedy: 'Check the service on the node. A later report for this request is still recorded in the run.' },
+    FENCE_UNREPORTED: { class: 'node', cause: 'This agent is older than 1.1.8, has handled managed requests before, and cannot say what fence it holds. If that fence is ahead of the server, its request fails as MANAGED_MUTATION_UNCERTAIN and strands a lease.', remedy: 'Before the wave, read .magnus/command-receipts/fence-*.json on the node and run `magnus-server agents fence NODE VALUE`. Nothing to do if the fence is not ahead.' },
+    LEDGER_MISSING: { class: 'node', cause: 'The agent has no command ledger, so its "no receipt" proves nothing about a lease held for it. The ledger may have moved, or the install may have been rebuilt.', remedy: 'Check AGENT_INSTALL_DIR and restore .magnus/command-receipts if it moved; the lease then settles by itself. If it is gone, Magnus has no way to settle the lease: establish by hand what the command did, then change the lease row in the database yourself.' },
+    LEDGER_NO_FENCE: { class: 'node', cause: 'The agent ledger holds neither a fence nor this node\'s enrollment marker, so nothing shows it is the ledger this command would have used.', remedy: 'Check whether .magnus/command-receipts was replaced, and restore it if so; the lease then settles by itself. If it cannot be restored, Magnus has no way to settle the lease: establish by hand what the command did, then change the lease row in the database yourself.' },
+    LEDGER_EVIDENCE_INCONSISTENT: { class: 'node', cause: 'The agent ledger accepted this lease\'s fence, but holds no receipt, no claim and no record of a failed admission for it. Either a receipt was removed, or an admission failed on an agent build that kept no such record.', remedy: 'Inspect .magnus/command-receipts on the node and the agent log around the lease\'s time. Magnus has no way to settle the lease: establish by hand what the command did, then change the lease row in the database yourself.' },
+    ENROLLMENT_MARKER_UNKNOWN: { class: 'node', cause: 'The agent could not read its managed-enrollment marker, so a mismatch cannot be ruled out.', remedy: 'Check .magnus/command-receipts/managed-enrollment.json on the node: its mode, owner and content.' },
+    SELF_UPGRADE_ENV_TLS: { class: 'node', cause: 'npm would not trust the registry\'s certificate on this node: a wrong clock, an expired certificate or an intercepting proxy.', remedy: 'Check the clock on the node and its CA trust for the registry, then retry it.' },
+    SELF_UPGRADE_ENV_AUTH: { class: 'node', cause: 'The registry refused this node\'s request (401 or 403).', remedy: 'Check the npm credentials and registry settings on the node, or use MAGNUS_AGENT_UPGRADE_SOURCE_DIR, then retry it.' },
+    SELF_UPGRADE_ENV_RESOURCE: { class: 'node', cause: 'The node ran out of memory or file handles, npm was killed, or a file was busy. A killed npm is told apart by how the process ended; a lifecycle script killed inside npm still reads as a package fault.', remedy: 'Check the memory on the node and its kernel log, then retry it.' },
+    RETRY_HELD_SUSPECTED: { class: 'node', cause: 'The run this one retries stopped because older agents answered ambiguously with nothing confirmed. Each further attempt on an older agent can strand another lease, so this retry leaves them alone.', remedy: 'Read the agent log of the nodes that answered, and run `magnus-server agents fence NODE VALUE` where a fence is ahead. Then retry with acknowledgeSuspicion (--acknowledge-suspicion).' },
+    SELF_UPGRADE_ENV_DISK: { class: 'node', cause: 'The node ran out of disk space or quota, or hit an I/O error, while installing the new version.', remedy: 'Free disk space on the node, then retry it.' },
+    SELF_UPGRADE_ENV_ACCESS: { class: 'node', cause: 'The node refused a write while installing the new version.', remedy: 'Run `sudo magnus-agent install-service` again on the node, which repairs ownership, then retry it.' },
+    RESOURCE_ENROLLMENT_REQUIRED: { class: 'node', cause: 'Admission refused the request because the node\'s resource enrollment is not complete.', remedy: 'Complete the node\'s resource enrollment (docs/COMMAND_RESOURCE_LEASES.md).' },
+    FENCE_OVERFLOW: { class: 'node', cause: 'The agent reports a resource fence above the highest value the server will adopt.', remedy: 'Stop the agent, inspect .magnus/command-receipts/fence-*.json on the node, and repair that file by hand. The server does not change its generation.' },
+    FENCE_INVALID: { class: 'node', cause: 'The agent reports a resource fence that is not a decimal value for its own node.', remedy: 'Inspect .magnus/command-receipts/fence-*.json on the node.' },
+    FENCE_AHEAD: { class: 'node', cause: 'The agent holds a resource fence above the server generation, so managed requests would be refused.', remedy: 'Nothing to do for an upgrade run: it repairs this at its start. `magnus-server agents doctor --heal` repairs it now.' },
+    IDEMPOTENCY_CONFLICT: { class: 'node', cause: 'The agent already has a receipt for this command identifier with different input.', remedy: 'Retry the node, which uses a new identifier, and report the conflict if it repeats.' },
+    LEDGER_UNAVAILABLE: { class: 'node', cause: 'The agent could not read or write its command ledger.', remedy: 'Check ownership, mode 0700 and free space of .magnus/command-receipts on the node.' },
+    LEDGER_UNRESOLVED: { class: 'node', cause: 'The agent ledger holds a command with an unresolved outcome, which blocks every later managed request.', remedy: 'Reconcile that command with signed evidence (docs/COMMAND_RESOURCE_LEASES.md).' },
+    LEASE_HELD: { class: 'node', cause: 'A command lease on the node is reserved, running or unknown.', remedy: 'Wait for it to finish. On a 1.1.8 agent, a lease stuck `unknown` with no receipt is settled by the readiness monitor, a run, or `magnus-server agents doctor --heal`; one with a receipt needs signed reconciliation. On an older agent, see MANAGED_MUTATION_UNCERTAIN.' },
+    WORK_HELD: { class: 'node', cause: 'Participant work, such as a console terminal or SSH session, is still held on the node.', remedy: 'Finish or reconcile that work, then retry the node.' },
+    UNMANAGED_MUTATION: { class: 'node', suspectable: true, cause: 'The agent is enrolled for managed requests and refused a request without a valid claim.', remedy: 'Complete the node\'s resource enrollment on the server (docs/COMMAND_RESOURCE_LEASES.md), or upgrade the agent by hand.' },
+    RESOURCE_CLAIM_INVALID: { class: 'node', cause: 'The server would not confirm the agent\'s claim for this request.', remedy: 'Check the enrollment and inventory host name of the node, then retry.' },
+    RESOURCE_TARGET_INVALID: { class: 'node', cause: 'Admission refused the node: its inventory address changed or its health is not fresh.', remedy: 'Wait for a fresh heartbeat, or repair the inventory address.' },
+    ADMISSION_FENCE_CLOSED: { class: 'node', cause: 'A server release closed admission to this node.', remedy: 'Release the admission fence (POST /api/v1/resource-leases/admission/<nodeId>/release).' },
+    ENROLLMENT_MISSING: { class: 'node', cause: 'Resource leases apply to this node but it is not enrolled.', remedy: 'Enroll the node (docs/COMMAND_RESOURCE_LEASES.md).' },
+    ENROLLMENT_DRAINING: { class: 'node', cause: 'The node\'s resource enrollment is stuck in draining.', remedy: 'Finish the drain: POST /api/v1/resource-leases/enrollment/<nodeId>/complete.' },
+    ENROLLMENT_HOST_MISMATCH: { class: 'node', cause: 'The enrollment names another host than the inventory.', remedy: 'Correct the host name of the node in the inventory.' },
+    ENROLLMENT_INCOMPLETE: { class: 'node', cause: 'The node\'s resource enrollment is not complete.', remedy: 'Enroll the node (docs/COMMAND_RESOURCE_LEASES.md).' },
+    ENROLLMENT_MARKER_MISMATCH: { class: 'node', cause: 'The agent holds a local managed-enrollment marker the server does not share.', remedy: 'Complete the node\'s resource enrollment on the server (docs/COMMAND_RESOURCE_LEASES.md), or upgrade the agent by hand.' },
+    NODE_OFFLINE: { class: 'node', transient: true, cause: 'The node is offline or has no recent heartbeat.', remedy: 'Bring the agent back, then retry the node.' },
+    NODE_NOT_FOUND: { class: 'node', cause: 'The node is no longer in the inventory.', remedy: 'Register the node again if it should be managed.' },
+    VERSION_UNKNOWN: { class: 'node', cause: 'The agent has not reported a usable version.', remedy: 'Wait for a heartbeat, or upgrade the agent by hand.' },
+    SELF_UPGRADE_TIMEOUT: { class: 'node', cause: 'An npm step of the upgrade did not finish in its time budget on the node. A new version that hangs when it is run reports SELF_UPGRADE_FAILED instead. A lifecycle script that hangs inside npm also ends up here: it cannot be told apart.', remedy: 'Check the network and disk speed of the node, then retry it. If every node hangs the same way, suspect the release.' },
+    SELF_UPGRADE_UNAVAILABLE: { class: 'node', cause: 'The agent cannot upgrade itself now: its layout, launcher, directories or npm are not usable.', remedy: 'Read the detail. Running `sudo magnus-agent install-service` once on the node usually repairs it.' },
+    SELF_UPGRADE_LAUNCHER: { class: 'node', suspectable: true, cause: 'The new version needs a newer launcher than the node has.', remedy: 'Run `sudo magnus-agent install-service` once on the node.' },
+    SELF_UPGRADE_ENGINE: { class: 'node', suspectable: true, cause: 'The new version does not support the Node.js on this node.', remedy: 'Upgrade Node.js on the node.' },
+    SELF_UPGRADE_PACKAGE: { class: 'node', suspectable: true, cause: 'The agent refused to install a package other than magnus-agent.', remedy: 'Report this: the server sent an unexpected package name.' },
+    SELF_UPGRADE_REFUSED: { class: 'node', suspectable: true, cause: 'The agent refused the version change.', remedy: 'Read the detail. Crossing a major version is done by hand.' },
+    PREFLIGHT_NOT_WRITABLE: { class: 'node', cause: 'The agent cannot write to its install directory.', remedy: 'Run `sudo magnus-agent install-service` again on the node, which repairs ownership.' },
+    PREFLIGHT_DISK_LOW: { class: 'node', cause: 'The install directory has less free space than an upgrade needs.', remedy: 'Free disk space on the node.' },
+    PREFLIGHT_NPM: { class: 'node', cause: 'npm is missing on the node or too old.', remedy: 'Install npm beside the agent\'s Node.js, or set MAGNUS_AGENT_NPM.' },
+    PREFLIGHT_FROM_INCOMPLETE: { class: 'node', cause: 'The running version is not complete under versions/, so a failed upgrade could not switch back.', remedy: 'Run `sudo magnus-agent install-service` again on the node.' },
+    PREFLIGHT_ENGINE: { class: 'node', cause: 'The target version does not support the Node.js on this node.', remedy: 'Upgrade Node.js on the node.' },
+    NOT_REACHED: { class: 'node', cause: 'The run ended before it reached this node.', remedy: 'Retry the run, once what ended it is dealt with. This node was not asked and did not change.' },
+    RUN_STOPPED: { class: 'node', cause: 'Someone stopped the run before it reached this node.', remedy: 'Retry the run when you want this node upgraded. This node was not asked and did not change.' },
+    NOT_ELIGIBLE: { class: 'node', cause: 'This node became ineligible at its turn, for a reason without a code of its own.', remedy: 'Read the detail, then retry the node.' },
+    // Expected states: reported, but not a problem with the run.
+    ALREADY_CURRENT: { class: 'node', informational: true, cause: 'The node already runs the target version.', remedy: 'Nothing to do.' },
+    SELF_UPGRADE_CURRENT: { class: 'node', informational: true, cause: 'The agent already runs the target version.', remedy: 'Nothing to do.' },
+    DOWNGRADE: { class: 'node', informational: true, cause: 'The node runs a newer version than the target.', remedy: 'Nothing to do, or choose a newer target.' },
+    MAJOR_VERSION: { class: 'node', informational: true, cause: 'The change crosses a major version.', remedy: 'Upgrade this node by hand.' },
+    NOT_SELF_UPGRADABLE: { class: 'node', informational: true, cause: 'This agent cannot upgrade itself: it is too old, or not set up with the launcher.', remedy: 'Run `sudo magnus-agent install-service` once on the node.' },
+    PROTOCOL_TOO_OLD: { class: 'node', informational: true, cause: 'The agent speaks an older self-upgrade protocol.', remedy: 'Upgrade this agent by hand.' },
+    SELF_UPGRADE_DISABLED: { class: 'node', informational: true, cause: 'An operator switched self-upgrade off on this node, or it runs in a container or the legacy layout.', remedy: 'Nothing to do if that is intended. Otherwise set MAGNUS_AGENT_SELF_UPGRADE=true, pull a newer image, or run `sudo magnus-agent install-service` once.' },
+    UPGRADE_IN_PROGRESS: { class: 'node', cause: 'An upgrade is staged or on trial on this node, and it can still switch back.', remedy: 'Wait for its trial to end, then retry the node if it did not confirm.' },
+    ALREADY_REVERTED: { class: 'node', cause: 'This node already switched back from this exact version.', remedy: 'Read the reason. To try again, use allowRetryReverted (--retry-reverted).' },
+    PREFLIGHT_UNAVAILABLE: { class: 'node', informational: true, cause: 'An agent older than 1.1.8 has no preflight check; heartbeat data is used instead.', remedy: 'Nothing to do: the agent gains the check when it is upgraded.' },
+    PREFLIGHT_UNREACHABLE: { class: 'node', informational: true, cause: 'The preflight check got no answer. The node stays in the run, and dispatch decides.', remedy: 'Nothing to do unless the node then fails with AGENT_UNREACHABLE.' },
+};
+const FALLBACK = { class: 'node', unknown: true, suspectable: true, cause: 'Unrecognised code: the agent or the server refused this node for a reason the catalogue does not list.', remedy: 'Read the detail and the agent log, then retry the node. An agent newer than the server can cause this.' };
+/** Cause and remedy for a code; an unknown code (a newer agent, an unexpected 4xx) is a node-level problem. */
+export function upgradeRemedy(code) {
+    return (code ? UPGRADE_REMEDIES[code] : undefined) ?? FALLBACK;
+}
+export const upgradeFailureClass = (code) => upgradeRemedy(code).class;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemagnus/magnus-contracts",
-  "version": "1.1.7",
+  "version": "1.1.10",
   "description": "Shared Zod schemas and TypeScript types for the Magnus server, UI and node agent wire contracts.",
   "keywords": [
     "magnus",
@@ -26,6 +26,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./upgrade-remedies": {
+      "types": "./dist/upgrade-remedies.d.ts",
+      "default": "./dist/upgrade-remedies.js"
     }
   },
   "files": [