@lumenflow/core 1.0.0

package/dist/spawn-monitor.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Spawn Monitor Library (WU-1948, WU-1968)
+ *
+ * Core monitoring logic for detecting stuck spawns and zombie locks.
+ * Used by orchestrate:monitor CLI command.
+ *
+ * Features:
+ * - Analyzes spawn registry for status counts
+ * - Detects pending spawns older than threshold (stuck)
+ * - Checks lane locks for zombie PIDs
+ * - Generates recovery suggestions
+ * - WU-1968: Processes spawn_failure signals from memory bus
+ *
+ * Library-First Note: This is project-specific monitoring code for
+ * PatientPath's spawn-registry.jsonl and lane-lock files. No external
+ * library exists for this custom format.
+ *
+ * @see {@link tools/__tests__/orchestrate-monitor.test.mjs} - Tests
+ * @see {@link tools/lib/__tests__/spawn-monitor.test.mjs} - Signal handler tests
+ * @see {@link tools/orchestrate-monitor.mjs} - CLI entry point
+ * @see {@link tools/lib/spawn-registry-store.mjs} - Registry storage
+ */
+/**
+ * Default threshold for stuck spawn detection (in minutes)
+ */
+export declare const DEFAULT_THRESHOLD_MINUTES = 30;
+/**
+ * Log prefix for spawn-monitor messages
+ */
+export declare const LOG_PREFIX = "[spawn-monitor]";
+/**
+ * @typedef {Object} SpawnAnalysis
+ * @property {number} pending - Count of pending spawns
+ * @property {number} completed - Count of completed spawns
+ * @property {number} timeout - Count of timed out spawns
+ * @property {number} crashed - Count of crashed spawns
+ * @property {number} total - Total spawn count
+ */
+/**
+ * @typedef {Object} StuckSpawnInfo
+ * @property {import('./spawn-registry-schema.js').SpawnEvent} spawn - The stuck spawn event
+ * @property {number} ageMinutes - Age of spawn 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 - Spawn status counts
+ * @property {StuckSpawnInfo[]} stuckSpawns - List of stuck spawns
+ * @property {ZombieLockInfo[]} zombieLocks - List of zombie locks
+ * @property {Suggestion[]} suggestions - Recovery suggestions
+ */
+/**
+ * @typedef {Object} RecoveryResultInfo
+ * @property {string} spawnId - ID of the spawn that was processed
+ * @property {string} targetWuId - Target WU ID for the spawn
+ * @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 spawn events and returns status counts.
+ *
+ * @param {import('./spawn-registry-schema.js').SpawnEvent[]} spawns - Array of spawn events
+ * @returns {SpawnAnalysis} Status counts
+ *
+ * @example
+ * const analysis = analyzeSpawns(spawns);
+ * console.log(`Pending: ${analysis.pending}, Completed: ${analysis.completed}`);
+ */
+export declare function analyzeSpawns(spawns: any): {
+    pending: number;
+    completed: number;
+    timeout: number;
+    crashed: number;
+    total: any;
+};
+/**
+ * Detects pending spawns that have been running longer than the threshold.
+ *
+ * @param {import('./spawn-registry-schema.js').SpawnEvent[]} spawns - Array of spawn events
+ * @param {number} [thresholdMinutes=DEFAULT_THRESHOLD_MINUTES] - Threshold in minutes
+ * @returns {StuckSpawnInfo[]} Array of stuck spawn info
+ *
+ * @example
+ * const stuck = detectStuckSpawns(spawns, 30);
+ * for (const info of stuck) {
+ *   console.log(`${info.spawn.targetWuId} stuck for ${info.ageMinutes} minutes`);
+ * }
+ */
+export declare function detectStuckSpawns(spawns: 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 spawns and zombie locks.
+ *
+ * @param {StuckSpawnInfo[]} stuckSpawns - Array of stuck spawn info
+ * @param {ZombieLockInfo[]} zombieLocks - Array of zombie lock info
+ * @returns {Suggestion[]} Array of suggestions
+ *
+ * @example
+ * const suggestions = generateSuggestions(stuckSpawns, zombieLocks);
+ * for (const s of suggestions) {
+ *   console.log(`${s.reason}\n  ${s.command}`);
+ * }
+ */
+export declare function generateSuggestions(stuckSpawns: 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 spawns by calling recoverStuckSpawn for each.
+ * When a spawn is escalated (action=ESCALATED_STUCK), chains to escalateStuckSpawn.
+ *
+ * @param {StuckSpawnInfo[]} stuckSpawns - Array of stuck spawn info
+ * @param {RunRecoveryOptions} [options] - Options
+ * @returns {Promise<RecoveryResultInfo[]>} Array of recovery results
+ *
+ * @example
+ * const results = await runRecovery(stuckSpawns, { baseDir: '/path/to/project' });
+ * for (const result of results) {
+ *   console.log(`${result.spawnId}: ${result.action}`);
+ * }
+ */
+interface RunRecoveryOptions extends SpawnMonitorBaseDirOptions {
+    /** If true, escalations return spec only */
+    dryRun?: boolean;
+}
+export declare function runRecovery(stuckSpawns: 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 = "[spawn-signal-handler]";
+/**
+ * Response actions for spawn failure signals
+ */
+export declare const SignalResponseAction: Readonly<{
+    RETRY: "retry";
+    BLOCK: "block";
+    BUG_WU: "bug_wu";
+    NONE: "none";
+}>;
+/**
+ * Processes spawn_failure signals from the memory bus.
+ *
+ * WU-1968: Orchestrator signal handler for spawn_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 processSpawnFailureSignals({ 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 processSpawnFailureSignals(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 {};