@hivemagnus/magnus-agent 1.1.3 → 1.1.5

package/dist/executors/enrollment-drain.d.ts

@@ -1,4 +1,6 @@
 import { Hono } from 'hono';
+/** Fixed, non-secret reasons an agent drain proof was refused. */
+export type DrainFailureReason = 'authority-unavailable' | 'authority-binding' | 'fence-failed' | 'supervisor-required' | 'supervisor-unverified' | 'inventory-failed' | 'challenge-expired' | 'receipt-failed';
 export declare const HOST_LOCAL_WRITER_DOMAIN = "magnus.host-local-writer.v1\n";
 export declare function canonicalDrainJson(value: unknown): string;
 export declare const enrollmentDrainRoutes: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/executors/enrollment-drain.js

@@ -6,6 +6,14 @@ import { CONTROL_API_URL, HOST_FQDN, NODE_MANAGER_SECRET, RESULT_SIGNING_SECRET,
 import { controlApiFetch } from '../tls.js';
 import { commandLedger, executionSupervisor } from './command-executor.js';
 import { mutationBarrier } from './mutation-barrier.js';
+import { logger } from '../utils/logger.js';
+class DrainFailure extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
 const descriptorSchema = z.object({ version: z.literal(1), participant: z.literal('agent'),
     nodeId: z.string().min(1).max(128), nodeFqdn: z.string().min(1).max(253), epoch: z.number().int().positive(),
     barrierId: z.string().guid(), challengeId: z.string().guid(), expiresAt: z.number().int().positive() }).strict();
@@ -72,6 +80,9 @@ enrollmentDrainRoutes.post('/enrollment-drain', async (c) => {
         || descriptor.expiresAt > Date.now() + 300_000 || RESULT_SIGNING_SECRET.length < 32
         || RESULT_SIGNING_SECRET === NODE_MANAGER_SECRET)
         return c.json({ success: false, error: { code: 'INVALID_DRAIN_CHALLENGE' } }, 409);
+    // The step in progress names the refusal when a dependency throws.
+    let step = 'authority-unavailable';
+    const started = Date.now();
     try {
         const request = { nodeFqdn: HOST_FQDN, nonce: randomUUID() };
         const response = await controlApiFetch(CONTROL_API_URL.replace(/\/+$/, '') + '/api/v1/resource-leases/enrollment/node-status', {
@@ -87,18 +98,21 @@ enrollmentDrainRoutes.post('/enrollment-drain', async (c) => {
             || status.nodeId !== descriptor.nodeId || status.state !== 'draining' || status.epoch !== descriptor.epoch
             || status.barrierId !== descriptor.barrierId || status.agentChallenge?.challengeId !== descriptor.challengeId
             || status.agentChallenge.expiresAt !== descriptor.expiresAt)
-            throw new Error('Drain authority binding differs');
+            throw new DrainFailure('authority-binding', 'Drain authority binding differs');
         const identity = { nodeId: descriptor.nodeId, nodeFqdn: descriptor.nodeFqdn, epoch: descriptor.epoch, barrierId: descriptor.barrierId };
+        step = 'fence-failed';
         await mutationBarrier.drain(identity);
         if (!MAGNUS_EXECUTION_SUPERVISOR_ENABLED)
-            throw new Error('Supervised execution is required for enrollment proof');
+            throw new DrainFailure('supervisor-required', 'Supervised execution is required for enrollment proof');
+        step = 'inventory-failed';
         const supervisor = await executionSupervisor.inventory();
         if (!supervisor.supported || !supervisor.quiescent)
-            throw new Error('Supervisor work remains unverified');
+            throw new DrainFailure('supervisor-unverified', 'Supervisor work remains unverified');
         const mutations = await mutationBarrier.snapshot(identity);
         const commands = await commandLedger.drainSnapshot();
         if (descriptor.expiresAt <= Date.now())
-            throw new Error('Drain challenge expired while collecting evidence');
+            throw new DrainFailure('challenge-expired', 'Drain challenge expired while collecting evidence');
+        step = 'receipt-failed';
         const activeCount = mutations.activeCount + commands.activeCount;
         const unknownCount = mutations.unknownCount + commands.unknownCount;
         const receipt = { ...descriptor, status: activeCount || unknownCount ? 'pending' : 'drained', activeCount, unknownCount,
@@ -107,8 +121,12 @@ enrollmentDrainRoutes.post('/enrollment-drain', async (c) => {
         c.header('Cache-Control', 'no-store');
         return c.json({ ...receipt, signature });
     }
-    catch {
-        return c.json({ success: false, error: { code: 'DRAIN_EVIDENCE_UNAVAILABLE',
+    catch (error) {
+        const reason = error instanceof DrainFailure ? error.reason : step;
+        // The local log keeps the real cause; the response carries only the fixed reason.
+        logger.warn('Agent enrollment drain refused', { reason, error: error instanceof Error ? error.message : String(error),
+            epoch: descriptor.epoch, barrierId: descriptor.barrierId, elapsedMs: Date.now() - started });
+        return c.json({ success: false, error: { code: 'DRAIN_EVIDENCE_UNAVAILABLE', reason,
                 message: 'Drain evidence is incomplete; no enrollment acknowledgment issued' } }, 409);
     }
 });

package/dist/executors/scheduler-discovery.d.ts

@@ -46,6 +46,19 @@ export declare function boundedTimerInlineSources(executable: string, argv: stri
     commands: string[];
     mdmonitor: boolean;
 } | null;
+export declare function stableServiceProperties(raw: string): string;
+/** A timer list keeps unit, load and active state; the SUB column
+ * (waiting/running/elapsed) and description change whenever a timer fires. */
+export declare function stableTimerUnitList(raw: string): string;
+/**
+ * A process is a possible Hermes runtime when what it executes is Hermes: its
+ * executable, the script or module an interpreter runs, or an explicit Hermes
+ * home option. Other argument text is data, not identity: an operator's
+ * `grep hermes`, a report filter naming a Hermes kind, or a shell whose inline
+ * code mentions Hermes is not a runtime (any Hermes it starts is a separate
+ * process observed on its own).
+ */
+export declare function hermesRuntimeCommand(args: string[]): boolean;
 export declare function discoverSchedulerSources(options?: DiscoveryOptions): Promise<{
     homes: string[];
     hermesRoots: string[];

package/dist/executors/scheduler-discovery.js

@@ -113,6 +113,61 @@ export function boundedTimerInlineSources(executable, argv) {
             commands: ['sponge', ...(shell.startsWith('/') ? [] : [shell])], mdmonitor: false };
     return null;
 }
+/**
+ * systemd appends the status of the last run to every Exec* record
+ * (`start_time=[...] ; stop_time=[...] ; pid=... ; code=... ; status=...`).
+ * That is runtime state, not the command definition: a timer that fires
+ * between two observations would otherwise change the source evidence on
+ * every run. Remove only a trailing run of those exact fields after the
+ * record's final `ignore_errors=`; anything else is kept byte for byte.
+ */
+const EXEC_RECORD_WITH_RUNTIME = /^((?:ExecStart|ExecStartPre|ExecStartPost|ExecCondition)=\{[\s\S]*;\s*ignore_errors=(?:yes|no))((?:\s*;\s*(?:start_time=\[[^\]\n]*\]|stop_time=\[[^\]\n]*\]|pid=\d+|code=[^\s;}]+|status=[^\s;}]+))+)(\s*\})$/;
+export function stableServiceProperties(raw) {
+    return raw.split('\n').map(line => {
+        const match = EXEC_RECORD_WITH_RUNTIME.exec(line);
+        return match ? match[1] + match[3] : line;
+    }).join('\n');
+}
+/** A timer list keeps unit, load and active state; the SUB column
+ * (waiting/running/elapsed) and description change whenever a timer fires. */
+export function stableTimerUnitList(raw) {
+    return raw.split('\n').map(line => line.trim().split(/\s+/).slice(0, 3).join(' ')).join('\n');
+}
+const HERMES_RUNTIME_TEXT = /(?:hermes|run_gateway\.py)/i;
+const SCRIPT_INTERPRETER = /^(?:python(?:[23](?:\.\d+)?)?|pypy3?|node|bun|deno|bash|sh|dash|zsh)$/;
+/**
+ * A process is a possible Hermes runtime when what it executes is Hermes: its
+ * executable, the script or module an interpreter runs, or an explicit Hermes
+ * home option. Other argument text is data, not identity: an operator's
+ * `grep hermes`, a report filter naming a Hermes kind, or a shell whose inline
+ * code mentions Hermes is not a runtime (any Hermes it starts is a separate
+ * process observed on its own).
+ */
+export function hermesRuntimeCommand(args) {
+    const executable = args[0] ?? '';
+    if (HERMES_RUNTIME_TEXT.test(executable))
+        return true;
+    if (args.some(arg => /^--hermes-home(?:=|$)/.test(arg)))
+        return true;
+    if (!SCRIPT_INTERPRETER.test(executable.split('/').pop() ?? ''))
+        return false;
+    for (let index = 1; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === '-m')
+            return HERMES_RUNTIME_TEXT.test(args[index + 1] ?? '');
+        if (/^-m./.test(arg))
+            return HERMES_RUNTIME_TEXT.test(arg.slice(2));
+        // Inline code is not a script identity.
+        if (/^-[a-zA-Z]*[ce]$/.test(arg) || ['--command', '--eval', '--print'].includes(arg))
+            return false;
+        if (arg === '--')
+            return HERMES_RUNTIME_TEXT.test(args[index + 1] ?? '');
+        if (arg.startsWith('-'))
+            continue;
+        return HERMES_RUNTIME_TEXT.test(arg);
+    }
+    return false;
+}
 export async function discoverSchedulerSources(options = {}) {
     const issues = [];
     const blockers = [];
@@ -207,7 +262,7 @@ export async function discoverSchedulerSources(options = {}) {
                 '--state=active,activating,reloading', '--all', '--plain', '--no-legend', '--no-pager']);
             const enabledRaw = await run('/usr/bin/systemctl', [...scope, 'list-unit-files', '--type=timer',
                 '--state=enabled,enabled-runtime', '--plain', '--no-legend', '--no-pager']);
-            sources[sourceKey] = schedulerContentDigest(JSON.stringify([activeRaw, enabledRaw]));
+            sources[sourceKey] = schedulerContentDigest(JSON.stringify([stableTimerUnitList(activeRaw), enabledRaw]));
             const names = [...new Set([...timerNames(activeRaw), ...timerNames(enabledRaw)])].sort(compareText);
             for (const name of names) {
                 try {
@@ -416,10 +471,11 @@ export async function discoverSchedulerSources(options = {}) {
                             if (error.code !== 'ENOENT')
                                 throw error;
                         }
+                    const stableService = stableServiceProperties(serviceRaw);
                     if (await run('/usr/bin/systemctl', showArgs) !== raw
-                        || await run('/usr/bin/systemctl', serviceShowArgs) !== serviceRaw)
+                        || stableServiceProperties(await run('/usr/bin/systemctl', serviceShowArgs)) !== stableService)
                         throw new Error('Timer or triggered service identity changed during observation');
-                    sources[sourceKey + ':' + hash(name)] = schedulerContentDigest(JSON.stringify([raw, serviceRaw]));
+                    sources[sourceKey + ':' + hash(name)] = schedulerContentDigest(JSON.stringify([raw, stableService]));
                     blockEvidence(kind, evidence, 1);
                 }
                 catch (error) {
@@ -628,13 +684,13 @@ export async function discoverSchedulerSources(options = {}) {
                 const command = await boundedSchedulerRead(join(proc, pid, 'cmdline'));
                 if (command.length > 256 * 1024)
                     throw new Error('Process command bound');
-                if (/(?:hermes|run_gateway\.py)/i.test(command.toString('utf8'))) {
+                if (hermesRuntimeCommand(command.toString('utf8').split('\0'))) {
                     try {
                         const startedAt = await processStart(pid);
                         const member = await boundedSchedulerMemberEvidence(join(proc, pid, 'cmdline'), `process:${pid}:start:${startedAt}`);
                         const verified = await boundedSchedulerRead(join(proc, pid, 'cmdline'));
                         if (await processStart(pid) !== startedAt || schedulerContentDigest(verified) !== member.contentSha256
-                            || !/(?:hermes|run_gateway\.py)/i.test(verified.toString('utf8')))
+                            || !hermesRuntimeCommand(verified.toString('utf8').split('\0')))
                             throw new Error('Process identity changed during observation');
                         blockEvidence('NATIVE_HERMES_RUNTIME_UNINSTRUMENTED', [member]);
                     }

package/dist/executors/scheduler-drain.d.ts

@@ -2,6 +2,15 @@ import { Hono } from 'hono';
 import { freshSchedulerStatus } from './scheduler-status.js';
 import { ManagedScheduler } from './managed-scheduler.js';
 import { type SchedulerInventoryOptions } from './scheduler-inventory.js';
+/** Fixed, non-secret reasons a scheduler drain proof was refused. */
+export type SchedulerDrainFailureReason = 'authority-unavailable' | 'authority-binding' | 'fence-failed' | 'inventory-failed' | 'inventory-changed' | 'ownership-changed' | 'challenge-expired' | 'receipt-failed';
+/** Which parts of two inventories differ: field names, source keys (path hashes or
+ * fixed labels) and blocker kinds only, never source content or paths. */
+export declare function schedulerInventoryDifference(first: Record<string, unknown>, second: Record<string, unknown>): {
+    fields: string[];
+    sources: string[];
+    blockerKinds: (string | undefined)[];
+};
 export declare function canonicalSchedulerEvidence(value: unknown): string;
 export declare function schedulerDrainRoutes(options?: {
     scheduler?: ManagedScheduler;

package/dist/executors/scheduler-drain.js

@@ -8,6 +8,32 @@ import { nodeAuthMiddleware } from '../middleware.js';
 import { ManagedScheduler } from './managed-scheduler.js';
 import { schedulerInventory } from './scheduler-inventory.js';
 import { schedulerAuthority } from './scheduler-authority.js';
+import { logger } from '../utils/logger.js';
+class SchedulerDrainFailure extends Error {
+    reason;
+    detail;
+    constructor(reason, message, detail = {}) {
+        super(message);
+        this.reason = reason;
+        this.detail = detail;
+    }
+}
+/** Which parts of two inventories differ: field names, source keys (path hashes or
+ * fixed labels) and blocker kinds only, never source content or paths. */
+export function schedulerInventoryDifference(first, second) {
+    const fields = [...new Set([...Object.keys(first), ...Object.keys(second)])].sort()
+        .filter(key => canonicalSchedulerEvidence(first[key]) !== canonicalSchedulerEvidence(second[key]));
+    const sourcesOf = (value) => (value['sources'] ?? {});
+    const sources = [...new Set([...Object.keys(sourcesOf(first)), ...Object.keys(sourcesOf(second))])].sort()
+        .filter(key => sourcesOf(first)[key] !== sourcesOf(second)[key]);
+    const blockersOf = (value) => new Set((value['blockers'] ?? [])
+        .map(row => row.kind + ':' + row.sourceSha256 + ':' + row.count));
+    const left = blockersOf(first);
+    const right = blockersOf(second);
+    const blockerKinds = [...new Set([...left].filter(row => !right.has(row)).concat([...right].filter(row => !left.has(row)))
+            .map(row => row.split(':')[0]))].sort();
+    return { fields, sources: sources.slice(0, 32), blockerKinds };
+}
 const EXTERNAL_SCHEDULER_KINDS = new Set([
     'LEGACY_OR_UNSUPPORTED_CRONTAB', 'SYSTEM_ANACRON', 'SYSTEM_CRONTAB', 'SYSTEM_CRON_SOURCE',
     'SYSTEM_TIMER_DEFINITION', 'USER_TIMER_DEFINITION', 'USER_TIMER_OFFLINE_ENABLED',
@@ -33,18 +59,23 @@ export function schedulerDrainRoutes(options = {}) {
         if (!parsed.success)
             return c.json({ success: false, error: { code: 'INVALID_SCHEDULER_DRAIN' } }, 400);
         const descriptor = parsed.data;
+        const started = Date.now();
         if (descriptor.nodeFqdn !== HOST_FQDN || descriptor.expiresAt <= Date.now() || descriptor.expiresAt > Date.now() + 300_000
             || RESULT_SIGNING_SECRET.length < 32 || RESULT_SIGNING_SECRET === NODE_MANAGER_SECRET)
             return c.json({ success: false, error: { code: 'INVALID_SCHEDULER_DRAIN' } }, 409);
+        // The step in progress names the refusal when a dependency throws.
+        let step = 'authority-unavailable';
         try {
             const query = { nodeFqdn: HOST_FQDN, nonce: randomUUID() };
             const status = schedulerStatusSchema.parse(await (options.status ?? freshSchedulerStatus)(query));
             if (status.nonce !== query.nonce || status.nodeFqdn !== descriptor.nodeFqdn || status.nodeId !== descriptor.nodeId
                 || status.state !== 'draining' || status.epoch !== descriptor.epoch || status.barrierId !== descriptor.barrierId
                 || status.schedulerChallenge?.challengeId !== descriptor.challengeId || status.schedulerChallenge.expiresAt !== descriptor.expiresAt)
-                throw new Error('Scheduler drain authority binding differs');
+                throw new SchedulerDrainFailure('authority-binding', 'Scheduler drain authority binding differs');
             const identity = { nodeId: descriptor.nodeId, nodeFqdn: descriptor.nodeFqdn, epoch: descriptor.epoch, barrierId: descriptor.barrierId };
+            step = 'fence-failed';
             await scheduler.drain(identity);
+            step = 'inventory-failed';
             const owned = await scheduler.inventory(identity);
             const recovery = options.recover ?? (id => scheduler.recover(id, schedulerAuthority()));
             // Recover only original receipts. Never call trigger/admit/run from a drain.
@@ -69,18 +100,19 @@ export function schedulerDrainRoutes(options = {}) {
             if (firstBoundaryReady) {
                 observed = await schedulerInventory({ ...options.inventory, scheduler, expectedBarrier: identity });
                 if (canonicalSchedulerEvidence(first) !== canonicalSchedulerEvidence(observed))
-                    throw new Error('Scheduler source inventory changed during proof');
+                    throw new SchedulerDrainFailure('inventory-changed', 'Scheduler source inventory changed during proof', schedulerInventoryDifference(first, observed));
             }
             // Bind the final managed snapshot under its flock, after all source reads.
             const finalOwned = await scheduler.inventory(identity);
             if (canonicalSchedulerEvidence(finalOwned) !== canonicalSchedulerEvidence(await scheduler.inventory(identity)))
-                throw new Error('Scheduler ownership changed during proof');
+                throw new SchedulerDrainFailure('ownership-changed', 'Scheduler ownership changed during proof');
             const activeCount = finalOwned.occurrences.filter(row => ['admitting', 'running'].includes(row.state)).length;
             const unknownCount = finalOwned.occurrences.filter(row => row.state === 'unknown' || row.settlementPending).length
                 + finalOwned.issues.length + observed.issues.length
                 + observed.blockers.filter(source => !EXTERNAL_SCHEDULER_KINDS.has(source.kind)).reduce((sum, source) => sum + source.count, 0);
             if (descriptor.expiresAt <= Date.now())
-                throw new Error('Scheduler challenge expired');
+                throw new SchedulerDrainFailure('challenge-expired', 'Scheduler challenge expired', { lateByMs: Date.now() - descriptor.expiresAt });
+            step = 'receipt-failed';
             const receipt = { ...descriptor, status: firstBoundaryReady && !activeCount && !unknownCount ? 'managed-drained' : 'pending',
                 scope: 'magnus-managed-scheduler-only', activeCount, unknownCount,
                 externalBlockers: observed.blockers.filter(source => EXTERNAL_SCHEDULER_KINDS.has(source.kind)),
@@ -89,8 +121,14 @@ export function schedulerDrainRoutes(options = {}) {
             c.header('Cache-Control', 'no-store');
             return c.json({ ...receipt, signature });
         }
-        catch {
-            return c.json({ success: false, error: { code: 'SCHEDULER_DRAIN_EVIDENCE_UNAVAILABLE', message: 'Scheduler evidence remains incomplete; no drain acknowledgment issued' } }, 409);
+        catch (error) {
+            const reason = error instanceof SchedulerDrainFailure ? error.reason : step;
+            // The local log keeps the real cause; the response carries only the fixed reason.
+            logger.warn('Scheduler enrollment drain refused', { reason, error: error instanceof Error ? error.message : String(error),
+                ...(error instanceof SchedulerDrainFailure ? error.detail : {}), epoch: descriptor.epoch, barrierId: descriptor.barrierId,
+                elapsedMs: Date.now() - started });
+            return c.json({ success: false, error: { code: 'SCHEDULER_DRAIN_EVIDENCE_UNAVAILABLE', reason,
+                    message: 'Scheduler evidence remains incomplete; no drain acknowledgment issued' } }, 409);
         }
     });
     return app;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemagnus/magnus-agent",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Magnus node agent: a small daemon that enrolls a Linux host with a magnus-server and runs authenticated health, command, cron, file and skill management, with optional Hermes Agent, Codex and Ardent management.",
   "keywords": [
     "magnus",
@@ -58,7 +58,7 @@
     "clean": "node -e \"const fs=require('node:fs');fs.rmSync('dist',{recursive:true,force:true});fs.rmSync('tsconfig.tsbuildinfo',{force:true})\""
   },
   "dependencies": {
-    "@hivemagnus/magnus-contracts": "1.1.3",
+    "@hivemagnus/magnus-contracts": "1.1.5",
     "@hono/node-server": "^2.1.5",
     "dotenv": "^18.0.9",
     "hono": "^4.13.16",