@lumenflow/core 2.18.3 → 2.20.0

package/dist/delegation-escalation.js

@@ -0,0 +1,258 @@
+/**
+ * Delegation Escalation Module (WU-1952, WU-1967)
+ *
+ * WU-1967: Replaced Bug WU creation with memory bus signalling.
+ * Signals orchestrator inbox instead of creating human-in-loop Bug WUs.
+ *
+ * Escalation Flow:
+ * 1. recoverStuckDelegation() returns { recovered: false, action: ESCALATED_STUCK }
+ * 2. escalateStuckDelegation() signals orchestrator via memory bus
+ * 3. Delegation status updated to ESCALATED (prevents duplicate signals)
+ * 4. Orchestrator decides: retry (1st), block (2nd), human escalate (3rd+)
+ *
+ * Library-First Note: This is project-specific delegation escalation code for
+ * PatientPath's custom delegation-registry.jsonl and memory bus patterns.
+ * No external library exists for this domain-specific agent lifecycle management.
+ *
+ * @see {@link packages/@lumenflow/cli/src/lib/__tests__/delegation-escalation.test.ts} - Tests
+ * @see {@link packages/@lumenflow/cli/src/lib/delegation-recovery.ts} - Recovery logic
+ * @see {@link packages/@lumenflow/cli/src/lib/mem-signal-core.ts} - Signal creation
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { DelegationRegistryStore } from './delegation-registry-store.js';
+import { DelegationStatus } from './delegation-registry-schema.js';
+import { RECOVERY_DIR_NAME } from './delegation-recovery.js';
+import { LUMENFLOW_PATHS } from './wu-constants.js';
+let createSignal = null;
+try {
+    const mod = await import('@lumenflow/memory/signal');
+    createSignal = mod.createSignal;
+}
+catch {
+    // @lumenflow/memory not available - signal features disabled
+}
+/**
+ * Log prefix for delegation-escalation messages
+ */
+const LOG_PREFIX = '[delegation-escalation]';
+/**
+ * Signal type for delegation failures.
+ */
+export const DELEGATION_FAILURE_SIGNAL_TYPE = 'delegation_failure';
+/**
+ * Severity levels for delegation failure signals
+ */
+export const SignalSeverity = Object.freeze({
+    WARNING: 'warning',
+    ERROR: 'error',
+    CRITICAL: 'critical',
+});
+/**
+ * Suggested actions for delegation failure signals
+ */
+export const SuggestedAction = Object.freeze({
+    RETRY: 'retry',
+    BLOCK: 'block',
+    HUMAN_ESCALATE: 'human_escalate',
+});
+/**
+ * @typedef {Object} DelegationFailureSignal
+ * @property {string} type - Always 'delegation_failure'
+ * @property {string} severity - 'warning' | 'error' | 'critical'
+ * @property {string} delegation_id - Delegation ID
+ * @property {string} target_wu_id - Target WU ID
+ * @property {string} parent_wu_id - Parent WU ID (orchestrator)
+ * @property {string} lane - Lane name
+ * @property {string} recovery_action - Recovery action that triggered escalation
+ * @property {number} recovery_attempts - Number of recovery attempts
+ * @property {string|null} last_checkpoint - Last checkpoint timestamp
+ * @property {string} suggested_action - 'retry' | 'block' | 'human_escalate'
+ * @property {string} message - Human-readable message
+ */
+/**
+ * @typedef {Object} EscalationResult
+ * @property {string} signalId - Signal ID (e.g., 'sig-abc12345')
+ * @property {DelegationFailureSignal} signal - The signal payload
+ * @property {string} delegationStatus - Updated delegation status (ESCALATED)
+ */
+/**
+ * @typedef {Object} AuditLogEntry
+ * @property {string} timestamp - ISO timestamp of recovery action
+ * @property {string} delegationId - ID of the delegation being recovered
+ * @property {string} action - Recovery action taken
+ * @property {string} reason - Explanation of why action was taken
+ * @property {Object} context - Additional context
+ */
+/**
+ * Counts existing escalation attempts for a delegation by reading audit logs.
+ *
+ * @param {string} baseDir - Base directory
+ * @param {string} delegationId - Delegation ID to count attempts for
+ * @returns {Promise<number>} Number of previous escalation attempts
+ */
+async function countEscalationAttempts(baseDir, delegationId) {
+    // WU-1421: Use LUMENFLOW_PATHS.BASE for consistency
+    const recoveryDir = path.join(baseDir, LUMENFLOW_PATHS.BASE, RECOVERY_DIR_NAME);
+    try {
+        const files = await fs.readdir(recoveryDir);
+        const delegationFiles = files.filter((f) => f.startsWith(`${delegationId}-`) && f.endsWith('.json'));
+        return delegationFiles.length;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return 0;
+        }
+        throw error;
+    }
+}
+/**
+ * Determines severity and suggested action based on recovery attempts.
+ *
+ * @param {number} attempts - Number of recovery attempts
+ * @returns {{ severity: string, suggestedAction: string }}
+ */
+function determineEscalationLevel(attempts) {
+    if (attempts <= 1) {
+        return {
+            severity: SignalSeverity.WARNING,
+            suggestedAction: SuggestedAction.RETRY,
+        };
+    }
+    else if (attempts === 2) {
+        return {
+            severity: SignalSeverity.ERROR,
+            suggestedAction: SuggestedAction.BLOCK,
+        };
+    }
+    else {
+        return {
+            severity: SignalSeverity.CRITICAL,
+            suggestedAction: SuggestedAction.HUMAN_ESCALATE,
+        };
+    }
+}
+/**
+ * Find the most recent escalation audit log for a delegation.
+ *
+ * @param {string} baseDir - Base directory
+ * @param {string} delegationId - Delegation ID to find audit log for
+ * @returns {Promise<AuditLogEntry|null>} Audit log entry or null if not found
+ */
+async function findEscalationAuditLog(baseDir, delegationId) {
+    // WU-1421: Use LUMENFLOW_PATHS.BASE for consistency
+    const recoveryDir = path.join(baseDir, LUMENFLOW_PATHS.BASE, RECOVERY_DIR_NAME);
+    try {
+        const files = await fs.readdir(recoveryDir);
+        // Filter files for this delegation ID, sorted by name (timestamp-based)
+        const delegationFiles = files
+            .filter((f) => f.startsWith(`${delegationId}-`) && f.endsWith('.json'))
+            .sort()
+            .reverse(); // Most recent first
+        if (delegationFiles.length === 0) {
+            return null;
+        }
+        // Read the most recent audit log
+        const auditPath = path.join(recoveryDir, delegationFiles[0]);
+        const content = await fs.readFile(auditPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Builds a delegation failure signal payload.
+ *
+ * @param {Object} delegation - Delegation event data
+ * @param {AuditLogEntry} auditLog - Escalation audit log
+ * @param {number} attempts - Number of recovery attempts
+ * @returns {DelegationFailureSignal} Signal payload
+ */
+function buildDelegationFailureSignal(delegation, auditLog, attempts) {
+    const { severity, suggestedAction } = determineEscalationLevel(attempts);
+    const lastCheckpoint = auditLog.context.lastCheckpoint || null;
+    return {
+        type: DELEGATION_FAILURE_SIGNAL_TYPE,
+        severity,
+        delegation_id: delegation.id,
+        target_wu_id: delegation.targetWuId,
+        parent_wu_id: delegation.parentWuId,
+        lane: delegation.lane,
+        recovery_action: auditLog.action,
+        recovery_attempts: attempts,
+        last_checkpoint: lastCheckpoint,
+        suggested_action: suggestedAction,
+        message: `Delegation ${delegation.id} for ${delegation.targetWuId} stuck: ${auditLog.reason}`,
+    };
+}
+export async function escalateStuckDelegation(delegationId, options = {}) {
+    const { baseDir = process.cwd(), dryRun = false } = options;
+    // WU-1421: Use LUMENFLOW_PATHS.STATE_DIR for consistency
+    const registryDir = path.join(baseDir, LUMENFLOW_PATHS.STATE_DIR);
+    // Load delegation registry
+    const store = new DelegationRegistryStore(registryDir);
+    try {
+        await store.load();
+    }
+    catch {
+        throw new Error(`Delegation ${delegationId} not found: registry unavailable`);
+    }
+    // Find the delegation
+    const delegation = store.getById(delegationId);
+    if (!delegation) {
+        throw new Error(`Delegation ${delegationId} not found in registry`);
+    }
+    // Check if signal module is available
+    if (!createSignal) {
+        throw new Error('Signal module (@lumenflow/memory) not available - cannot escalate');
+    }
+    // WU-1967: Check if already escalated (prevents duplicate signals)
+    if (delegation.status === DelegationStatus.ESCALATED) {
+        throw new Error(`Delegation ${delegationId} already escalated`);
+    }
+    // Find escalation audit log
+    const auditLog = await findEscalationAuditLog(baseDir, delegationId);
+    if (!auditLog) {
+        throw new Error(`No escalation audit log found for delegation ${delegationId}`);
+    }
+    // Count previous escalation attempts
+    const attempts = await countEscalationAttempts(baseDir, delegationId);
+    // Build signal payload
+    const signalPayload = buildDelegationFailureSignal(delegation, auditLog, attempts);
+    if (dryRun) {
+        console.log(`${LOG_PREFIX} [dry-run] Would signal orchestrator`);
+        console.log(`${LOG_PREFIX} [dry-run] Severity: ${signalPayload.severity}`);
+        console.log(`${LOG_PREFIX} [dry-run] Suggested action: ${signalPayload.suggested_action}`);
+        console.log(`${LOG_PREFIX} [dry-run] Message: ${signalPayload.message}`);
+        return {
+            signalId: 'sig-dry-run',
+            signal: signalPayload,
+            delegationStatus: DelegationStatus.ESCALATED,
+        };
+    }
+    // WU-1967: Send signal to orchestrator inbox
+    console.log(`${LOG_PREFIX} Signalling orchestrator for delegation ${delegationId}`);
+    console.log(`${LOG_PREFIX} Target WU: ${delegation.targetWuId}`);
+    console.log(`${LOG_PREFIX} Severity: ${signalPayload.severity}`);
+    console.log(`${LOG_PREFIX} Suggested action: ${signalPayload.suggested_action}`);
+    // Create signal with structured message (JSON payload in message field)
+    const signalResult = await createSignal(baseDir, {
+        message: JSON.stringify(signalPayload),
+        wuId: delegation.parentWuId, // Signal targets the orchestrator (parent WU)
+        lane: delegation.lane,
+    });
+    // Update delegation status to ESCALATED (prevents duplicate signals)
+    await store.updateStatus(delegationId, DelegationStatus.ESCALATED);
+    console.log(`${LOG_PREFIX} Signal sent: ${signalResult.signal.id}`);
+    console.log(`${LOG_PREFIX} Delegation ${delegationId} status updated to ESCALATED`);
+    return {
+        signalId: signalResult.signal.id,
+        signal: signalPayload,
+        delegationStatus: DelegationStatus.ESCALATED,
+    };
+}
+//# sourceMappingURL=delegation-escalation.js.map

package/dist/delegation-escalation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-escalation.js","sourceRoot":"","sources":["../src/delegation-escalation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAQpD,IAAI,YAAY,GAA0B,IAAI,CAAC;AAC/C,IAAI,CAAC;IACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;IACrD,YAAY,GAAG,GAAG,CAAC,YAAY,CAAC;AAClC,CAAC;AAAC,MAAM,CAAC;IACP,6DAA6D;AAC/D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,GAAG,yBAAyB,CAAC;AAE7C;;GAEG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,oBAAoB,CAAC;AAEnE;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1C,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,QAAQ,EAAE,UAAU;CACrB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3C,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,cAAc,EAAE,gBAAgB;CACjC,CAAC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AAEH;;;;;GAKG;AAEH;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,KAAK,UAAU,uBAAuB,CAAC,OAAO,EAAE,YAAY;IAC1D,oDAAoD;IACpD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;IAEhF,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC5C,MAAM,eAAe,GAAG,KAAK,CAAC,MAAM,CAClC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,YAAY,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAC/D,CAAC;QACF,OAAO,eAAe,CAAC,MAAM,CAAC;IAChC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,wBAAwB,CAAC,QAAQ;IACxC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QAClB,OAAO;YACL,QAAQ,EAAE,cAAc,CAAC,OAAO;YAChC,eAAe,EAAE,eAAe,CAAC,KAAK;SACvC,CAAC;IACJ,CAAC;SAAM,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,QAAQ,EAAE,cAAc,CAAC,KAAK;YAC9B,eAAe,EAAE,eAAe,CAAC,KAAK;SACvC,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,OAAO;YACL,QAAQ,EAAE,cAAc,CAAC,QAAQ;YACjC,eAAe,EAAE,eAAe,CAAC,cAAc;SAChD,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,sBAAsB,CAAC,OAAO,EAAE,YAAY;IACzD,oDAAoD;IACpD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;IAEhF,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC5C,wEAAwE;QACxE,MAAM,eAAe,GAAG,KAAK;aAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,YAAY,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;aACtE,IAAI,EAAE;aACN,OAAO,EAAE,CAAC,CAAC,oBAAoB;QAElC,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,iCAAiC;QACjC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,4BAA4B,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ;IAClE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,GAAG,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IACzE,MAAM,cAAc,GAAG,QAAQ,CAAC,OAAO,CAAC,cAAc,IAAI,IAAI,CAAC;IAE/D,OAAO;QACL,IAAI,EAAE,8BAA8B;QACpC,QAAQ;QACR,aAAa,EAAE,UAAU,CAAC,EAAE;QAC5B,YAAY,EAAE,UAAU,CAAC,UAAU;QACnC,YAAY,EAAE,UAAU,CAAC,UAAU;QACnC,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,eAAe,EAAE,QAAQ,CAAC,MAAM;QAChC,iBAAiB,EAAE,QAAQ;QAC3B,eAAe,EAAE,cAAc;QAC/B,gBAAgB,EAAE,eAAe;QACjC,OAAO,EAAE,cAAc,UAAU,CAAC,EAAE,QAAQ,UAAU,CAAC,UAAU,WAAW,QAAQ,CAAC,MAAM,EAAE;KAC9F,CAAC;AACJ,CAAC;AAoCD,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,YAAY,EACZ,UAA0C,EAAE;IAE5C,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IAC5D,yDAAyD;IACzD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAElE,2BAA2B;IAC3B,MAAM,KAAK,GAAG,IAAI,uBAAuB,CAAC,WAAW,CAAC,CAAC;IAEvD,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,cAAc,YAAY,kCAAkC,CAAC,CAAC;IAChF,CAAC;IAED,sBAAsB;IACtB,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAE/C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,cAAc,YAAY,wBAAwB,CAAC,CAAC;IACtE,CAAC;IAED,sCAAsC;IACtC,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IAED,mEAAmE;IACnE,IAAI,UAAU,CAAC,MAAM,KAAK,gBAAgB,CAAC,SAAS,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,cAAc,YAAY,oBAAoB,CAAC,CAAC;IAClE,CAAC;IAED,4BAA4B;IAC5B,MAAM,QAAQ,GAAG,MAAM,sBAAsB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAErE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,gDAAgD,YAAY,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,qCAAqC;IACrC,MAAM,QAAQ,GAAG,MAAM,uBAAuB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAEtE,uBAAuB;IACvB,MAAM,aAAa,GAAG,4BAA4B,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAEnF,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,sCAAsC,CAAC,CAAC;QACjE,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,wBAAwB,aAAa,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC3E,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,gCAAgC,aAAa,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAC3F,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,uBAAuB,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACzE,OAAO;YACL,QAAQ,EAAE,aAAa;YACvB,MAAM,EAAE,aAAa;YACrB,gBAAgB,EAAE,gBAAgB,CAAC,SAAS;SAC7C,CAAC;IACJ,CAAC;IAED,6CAA6C;IAC7C,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,2CAA2C,YAAY,EAAE,CAAC,CAAC;IACpF,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,eAAe,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC;IACjE,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,cAAc,aAAa,CAAC,QAAQ,EAAE,CAAC,CAAC;IACjE,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,sBAAsB,aAAa,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAEjF,wEAAwE;IACxE,MAAM,YAAY,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE;QAC/C,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC;QACtC,IAAI,EAAE,UAAU,CAAC,UAAU,EAAE,8CAA8C;QAC3E,IAAI,EAAE,UAAU,CAAC,IAAI;KACtB,CAAC,CAAC;IAEH,qEAAqE;IACrE,MAAM,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAEnE,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,iBAAiB,YAAY,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;IACpE,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,eAAe,YAAY,8BAA8B,CAAC,CAAC;IAEpF,OAAO;QACL,QAAQ,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE;QAChC,MAAM,EAAE,aAAa;QACrB,gBAAgB,EAAE,gBAAgB,CAAC,SAAS;KAC7C,CAAC;AACJ,CAAC"}

package/dist/delegation-monitor.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Delegation Monitor Library (WU-1948, WU-1968)
+ *
+ * Core monitoring logic for detecting stuck delegations and zombie locks.
+ * Used by orchestrate:monitor CLI command.
+ *
+ * Features:
+ * - Analyzes delegation registry for status counts
+ * - Detects pending delegations older than threshold (stuck)
+ * - Checks lane locks for zombie PIDs
+ * - Generates recovery suggestions
+ * - WU-1968: Processes delegation_failure signals from memory bus
+ *
+ * Library-First Note: This is project-specific monitoring code for
+ * PatientPath's delegation-registry.jsonl and lane-lock files. No external
+ * library exists for this custom format.
+ *
+ * @see {@link packages/@lumenflow/cli/src/__tests__/orchestrate-monitor.test.ts} - Tests
+ * @see {@link packages/@lumenflow/cli/src/lib/__tests__/delegation-monitor.test.ts} - Signal handler tests
+ * @see {@link packages/@lumenflow/cli/src/orchestrate-monitor.ts} - CLI entry point
+ * @see {@link packages/@lumenflow/cli/src/lib/delegation-registry-store.ts} - Registry storage
+ */
+/**
+ * Default threshold for stuck delegation detection (in minutes)
+ */
+export declare const DEFAULT_THRESHOLD_MINUTES = 30;
+/**
+ * Log prefix for delegation-monitor messages
+ */
+export declare const LOG_PREFIX = "[delegation-monitor]";
+/**
+ * @typedef {Object} SpawnAnalysis
+ * @property {number} pending - Count of pending delegations
+ * @property {number} completed - Count of completed delegations
+ * @property {number} timeout - Count of timed out delegations
+ * @property {number} crashed - Count of crashed delegations
+ * @property {number} total - Total delegation count
+ */
+/**
+ * @typedef {Object} StuckSpawnInfo
+ * @property {import('./delegation-registry-schema.js').DelegationEvent} delegation - The stuck delegation event
+ * @property {number} ageMinutes - Age of delegation in minutes
+ * @property {string|null} lastCheckpoint - Last checkpoint timestamp (if available from memory layer)
+ */
+/**
+ * @typedef {Object} ZombieLockInfo
+ * @property {string} wuId - WU ID that holds the zombie lock
+ * @property {string} lane - Lane name
+ * @property {number} pid - Process ID (no longer running)
+ * @property {string} timestamp - When lock was acquired
+ */
+/**
+ * @typedef {Object} Suggestion
+ * @property {string} command - Suggested command to run
+ * @property {string} reason - Explanation of why this is suggested
+ */
+/**
+ * @typedef {Object} MonitorResult
+ * @property {SpawnAnalysis} analysis - Delegation status counts
+ * @property {StuckSpawnInfo[]} stuckDelegations - List of stuck delegations
+ * @property {ZombieLockInfo[]} zombieLocks - List of zombie locks
+ * @property {Suggestion[]} suggestions - Recovery suggestions
+ */
+/**
+ * @typedef {Object} RecoveryResultInfo
+ * @property {string} delegationId - ID of the delegation that was processed
+ * @property {string} targetWuId - Target WU ID for the delegation
+ * @property {string} action - Recovery action taken (from RecoveryAction)
+ * @property {boolean} recovered - Whether auto-recovery was successful
+ * @property {string} reason - Human-readable explanation
+ * @property {Object} [escalation] - Escalation info if action is ESCALATED_STUCK
+ * @property {string} [escalation.bugWuId] - Bug WU ID created for escalation
+ * @property {string} [escalation.title] - Bug WU title
+ */
+/**
+ * Analyzes delegation events and returns status counts.
+ *
+ * @param {import('./delegation-registry-schema.js').DelegationEvent[]} delegations - Array of delegation events
+ * @returns {SpawnAnalysis} Status counts
+ *
+ * @example
+ * const analysis = analyzeDelegations(delegations);
+ * console.log(`Pending: ${analysis.pending}, Completed: ${analysis.completed}`);
+ */
+export declare function analyzeDelegations(delegations: any): {
+    pending: number;
+    completed: number;
+    timeout: number;
+    crashed: number;
+    total: any;
+};
+/**
+ * Detects pending delegations that have been running longer than the threshold.
+ *
+ * @param {import('./delegation-registry-schema.js').DelegationEvent[]} delegations - Array of delegation events
+ * @param {number} [thresholdMinutes=DEFAULT_THRESHOLD_MINUTES] - Threshold in minutes
+ * @returns {StuckSpawnInfo[]} Array of stuck delegation info
+ *
+ * @example
+ * const stuck = detectStuckDelegations(delegations, 30);
+ * for (const info of stuck) {
+ *   console.log(`${info.delegation.targetWuId} stuck for ${info.ageMinutes} minutes`);
+ * }
+ */
+export declare function detectStuckDelegations(delegations: any, thresholdMinutes?: number): any[];
+/**
+ * Checks lane lock files for zombie locks (dead PIDs).
+ *
+ * @param {SpawnMonitorBaseDirOptions} [options] - Options
+ * @returns {Promise<ZombieLockInfo[]>} Array of zombie lock info
+ *
+ * @example
+ * const zombies = await checkZombieLocks();
+ * for (const lock of zombies) {
+ *   console.log(`Zombie lock: ${lock.lane} (PID ${lock.pid})`);
+ * }
+ */
+interface SpawnMonitorBaseDirOptions {
+    /** Base directory (defaults to process.cwd()) */
+    baseDir?: string;
+}
+export declare function checkZombieLocks(options?: SpawnMonitorBaseDirOptions): Promise<any[]>;
+/**
+ * Generates recovery suggestions for stuck delegations and zombie locks.
+ *
+ * @param {StuckSpawnInfo[]} stuckDelegations - Array of stuck delegation info
+ * @param {ZombieLockInfo[]} zombieLocks - Array of zombie lock info
+ * @returns {Suggestion[]} Array of suggestions
+ *
+ * @example
+ * const suggestions = generateSuggestions(stuckDelegations, zombieLocks);
+ * for (const s of suggestions) {
+ *   console.log(`${s.reason}\n  ${s.command}`);
+ * }
+ */
+export declare function generateSuggestions(stuckDelegations: any, zombieLocks: any): any[];
+/**
+ * Formats monitor output for display.
+ *
+ * @param {MonitorResult} result - Monitor result to format
+ * @returns {string} Formatted output string
+ *
+ * @example
+ * const output = formatMonitorOutput(result);
+ * console.log(output);
+ */
+export declare function formatMonitorOutput(result: any): string;
+/**
+ * Runs recovery for stuck delegations by calling recoverStuckDelegation for each.
+ * When a delegation is escalated (action=ESCALATED_STUCK), chains to escalateStuckDelegation.
+ *
+ * @param {StuckSpawnInfo[]} stuckDelegations - Array of stuck delegation info
+ * @param {RunRecoveryOptions} [options] - Options
+ * @returns {Promise<RecoveryResultInfo[]>} Array of recovery results
+ *
+ * @example
+ * const results = await runRecovery(stuckDelegations, { baseDir: '/path/to/project' });
+ * for (const result of results) {
+ *   console.log(`${result.delegationId}: ${result.action}`);
+ * }
+ */
+interface RunRecoveryOptions extends SpawnMonitorBaseDirOptions {
+    /** If true, escalations return spec only */
+    dryRun?: boolean;
+}
+export declare function runRecovery(stuckDelegations: any, options?: RunRecoveryOptions): Promise<any[]>;
+/**
+ * Formats recovery results for display.
+ *
+ * @param {RecoveryResultInfo[]} results - Array of recovery results
+ * @returns {string} Formatted output string
+ *
+ * @example
+ * const output = formatRecoveryResults(results);
+ * console.log(output);
+ */
+export declare function formatRecoveryResults(results: any): string;
+/**
+ * Log prefix for signal handler messages
+ */
+export declare const SIGNAL_HANDLER_LOG_PREFIX = "[delegation-signal-handler]";
+/**
+ * Response actions for delegation failure signals
+ */
+export declare const SignalResponseAction: Readonly<{
+    RETRY: "retry";
+    BLOCK: "block";
+    BUG_WU: "bug_wu";
+    NONE: "none";
+}>;
+/**
+ * Processes delegation_failure signals from the memory bus.
+ *
+ * WU-1968: Orchestrator signal handler for delegation_failure signals.
+ *
+ * Response logic:
+ * - First failure (suggested_action=retry): logs warning, suggests retry
+ * - Second failure (suggested_action=block): marks WU blocked with reason
+ * - Third+ failure (suggested_action=human_escalate): creates Bug WU
+ *
+ * @param {RunRecoveryOptions} options - Options
+ * @returns {Promise<SignalProcessingResult>} Processing result
+ *
+ * @example
+ * const result = await processDelegationFailureSignals({ baseDir: '/path/to/project' });
+ * console.log(`Processed ${result.signalCount} signals`);
+ * for (const response of result.processed) {
+ *   console.log(`${response.targetWuId}: ${response.action}`);
+ * }
+ */
+export declare function processDelegationFailureSignals(options?: RunRecoveryOptions): Promise<{
+    processed: any[];
+    signalCount: number;
+    retryCount: number;
+    blockCount: number;
+    bugWuCount: number;
+}>;
+/**
+ * Formats signal handler output for display.
+ *
+ * @param {SignalProcessingResult} result - Processing result
+ * @returns {string} Formatted output string
+ *
+ * @example
+ * const output = formatSignalHandlerOutput(result);
+ * console.log(output);
+ */
+export declare function formatSignalHandlerOutput(result: any): string;
+export {};
+//# sourceMappingURL=delegation-monitor.d.ts.map

package/dist/delegation-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-monitor.d.ts","sourceRoot":"","sources":["../src/delegation-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA4BH;;GAEG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,UAAU,yBAAyB,CAAC;AAEjD;;;;;;;GAOG;AAEH;;;;;GAKG;AAEH;;;;;;GAMG;AAEH;;;;GAIG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,KAAA;;;;;;EA2B7C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,KAAA,EAAE,gBAAgB,SAA4B,SA4B/F;AAED;;;;;;;;;;;GAWG;AACH,UAAU,0BAA0B;IAClC,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,0BAA+B,kBAuC9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,gBAAgB,KAAA,EAAE,WAAW,KAAA,SAuBhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,KAAA,UAkEzC;AAED;;;;;;;;;;;;;GAaG;AACH,UAAU,kBAAmB,SAAQ,0BAA0B;IAC7D,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,WAAW,CAAC,gBAAgB,KAAA,EAAE,OAAO,GAAE,kBAAuB,kBA2CnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,KAAA,UAkD5C;AAMD;;GAEG;AACH,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AAEvE;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;EAK/B,CAAC;AAuIH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,+BAA+B,CAAC,OAAO,GAAE,kBAAuB;;;;;;GAwHrF;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,KAAA,UAmC/C"}