@lumenflow/core 3.1.1 → 3.1.3

package/dist/spawn-monitor.d.ts

@@ -1,230 +0,0 @@
-/**
- * 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 packages/@lumenflow/cli/src/__tests__/orchestrate-monitor.test.ts} - Tests
- * @see {@link packages/@lumenflow/cli/src/lib/__tests__/spawn-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/spawn-registry-store.ts} - 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 {};
-//# sourceMappingURL=spawn-monitor.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"spawn-monitor.d.ts","sourceRoot":"","sources":["../src/spawn-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA4BH;;GAEG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,UAAU,oBAAoB,CAAC;AAE5C;;;;;;;GAOG;AAEH;;;;;GAKG;AAEH;;;;;;GAMG;AAEH;;;;GAIG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,KAAA;;;;;;EA2BnC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,KAAA,EAAE,gBAAgB,SAA4B,SA4BrF;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,WAAW,KAAA,EAAE,WAAW,KAAA,SAuB3D;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,WAAW,KAAA,EAAE,OAAO,GAAE,kBAAuB,kBA2C9E;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,KAAA,UAkD5C;AAMD;;GAEG;AACH,eAAO,MAAM,yBAAyB,2BAA2B,CAAC;AAElE;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;EAK/B,CAAC;AAsIH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,GAAE,kBAAuB;;;;;;GAwHhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,KAAA,UAmC/C"}