@iflow-mcp/jkheadley-instar 0.26.2

package/dist/monitoring/SessionMonitor.d.ts

@@ -0,0 +1,102 @@
+/**
+ * SessionMonitor — Proactive session health monitoring.
+ *
+ * Unlike StallTriageNurse (reactive — triggers on unanswered messages) or
+ * SessionWatchdog (reactive — triggers on stuck bash commands), the
+ * SessionMonitor is PROACTIVE: it periodically checks all active sessions
+ * and ensures users experience the responsiveness they'd expect.
+ *
+ * Responsibilities:
+ * 1. Detect idle sessions (no tmux output changes for extended periods)
+ * 2. Track session responsiveness (time between user message and agent reply)
+ * 3. Send proactive health updates to users (not overbearing)
+ * 4. Coordinate with StallTriageNurse for recovery when issues are found
+ *
+ * Design principle: Responsive and informative but not overbearing.
+ * One update per issue per session — not a stream of "still checking" messages.
+ */
+import { EventEmitter } from 'events';
+import type { SessionRecovery, RecoveryResult } from './SessionRecovery.js';
+export interface SessionMonitorConfig {
+    /** Enable the session monitor (default: true) */
+    enabled?: boolean;
+    /** How often to check sessions, in seconds (default: 60) */
+    pollIntervalSec?: number;
+    /** Minutes of inactivity before a session is flagged as idle (default: 15) */
+    idleThresholdMinutes?: number;
+    /** Minimum minutes between user notifications per topic (default: 30) */
+    notificationCooldownMinutes?: number;
+}
+export interface SessionMonitorEvents {
+    'monitor:idle-detected': {
+        topicId: number;
+        sessionName: string;
+        idleMinutes: number;
+    };
+    'monitor:unresponsive': {
+        topicId: number;
+        sessionName: string;
+        waitMinutes: number;
+    };
+    'monitor:recovery-triggered': {
+        topicId: number;
+        sessionName: string;
+        reason: string;
+    };
+    'monitor:mechanical-recovery': {
+        topicId: number;
+        sessionName: string;
+        result: RecoveryResult;
+    };
+    'monitor:user-notified': {
+        topicId: number;
+        message: string;
+    };
+}
+export interface SessionMonitorDeps {
+    /** Get all active topic-to-session mappings */
+    getActiveTopicSessions: () => Map<number, string>;
+    /** Capture tmux output for a session */
+    captureSessionOutput: (sessionName: string, lines: number) => string | null;
+    /** Check if a session is alive */
+    isSessionAlive: (sessionName: string) => boolean;
+    /** Get recent messages for a topic */
+    getTopicHistory: (topicId: number, limit: number) => Array<{
+        text: string;
+        fromUser: boolean;
+        timestamp: string;
+    }>;
+    /** Send a message to a topic */
+    sendToTopic: (topicId: number, text: string) => Promise<any>;
+    /** Trigger triage recovery for a session */
+    triggerTriage?: (topicId: number, sessionName: string, reason: string) => Promise<{
+        resolved: boolean;
+    }>;
+    /** Optional mechanical recovery layer — runs before LLM triage */
+    sessionRecovery?: SessionRecovery;
+}
+export declare class SessionMonitor extends EventEmitter {
+    private config;
+    private deps;
+    private snapshots;
+    private interval;
+    private running;
+    constructor(deps: SessionMonitorDeps, config?: Partial<SessionMonitorConfig>);
+    emit<K extends keyof SessionMonitorEvents>(event: K, data: SessionMonitorEvents[K]): boolean;
+    on<K extends keyof SessionMonitorEvents>(event: K, listener: (data: SessionMonitorEvents[K]) => void): this;
+    start(): void;
+    stop(): void;
+    getStatus(): {
+        enabled: boolean;
+        trackedSessions: number;
+        sessionHealth: Array<{
+            topicId: number;
+            sessionName: string;
+            status: string;
+            idleMinutes: number;
+        }>;
+    };
+    poll(): Promise<void>;
+    private checkSession;
+}
+//# sourceMappingURL=SessionMonitor.d.ts.map

package/dist/monitoring/SessionMonitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionMonitor.d.ts","sourceRoot":"","sources":["../../src/monitoring/SessionMonitor.ts"],"names":[],"mappings":"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"}

package/dist/monitoring/SessionMonitor.js

@@ -0,0 +1,238 @@
+/**
+ * SessionMonitor — Proactive session health monitoring.
+ *
+ * Unlike StallTriageNurse (reactive — triggers on unanswered messages) or
+ * SessionWatchdog (reactive — triggers on stuck bash commands), the
+ * SessionMonitor is PROACTIVE: it periodically checks all active sessions
+ * and ensures users experience the responsiveness they'd expect.
+ *
+ * Responsibilities:
+ * 1. Detect idle sessions (no tmux output changes for extended periods)
+ * 2. Track session responsiveness (time between user message and agent reply)
+ * 3. Send proactive health updates to users (not overbearing)
+ * 4. Coordinate with StallTriageNurse for recovery when issues are found
+ *
+ * Design principle: Responsive and informative but not overbearing.
+ * One update per issue per session — not a stream of "still checking" messages.
+ */
+import { EventEmitter } from 'events';
+const DEFAULT_CONFIG = {
+    enabled: true,
+    pollIntervalSec: 60,
+    idleThresholdMinutes: 15,
+    notificationCooldownMinutes: 30,
+};
+export class SessionMonitor extends EventEmitter {
+    config;
+    deps;
+    snapshots = new Map();
+    interval = null;
+    running = false;
+    constructor(deps, config) {
+        super();
+        this.deps = deps;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    // ── Typed Events ────────────────────────────────────────
+    emit(event, data) {
+        return super.emit(event, data);
+    }
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    // ── Public API ──────────────────────────────────────────
+    start() {
+        if (!this.config.enabled || this.interval)
+            return;
+        console.log(`[SessionMonitor] Starting (poll: ${this.config.pollIntervalSec}s, idle: ${this.config.idleThresholdMinutes}m)`);
+        this.interval = setInterval(() => this.poll(), this.config.pollIntervalSec * 1000);
+        // Initial poll after 10 seconds (let other systems initialize)
+        setTimeout(() => this.poll(), 10_000);
+    }
+    stop() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+    }
+    getStatus() {
+        const health = [];
+        for (const [topicId, snap] of this.snapshots) {
+            health.push({
+                topicId,
+                sessionName: snap.sessionName,
+                status: snap.status,
+                idleMinutes: Math.round((Date.now() - snap.lastOutputAt) / 60000),
+            });
+        }
+        return {
+            enabled: this.config.enabled,
+            trackedSessions: this.snapshots.size,
+            sessionHealth: health,
+        };
+    }
+    // ── Core Polling ────────────────────────────────────────
+    async poll() {
+        if (!this.config.enabled || this.running)
+            return;
+        this.running = true;
+        try {
+            const activeTopics = this.deps.getActiveTopicSessions();
+            // Clean up snapshots for topics that no longer have sessions
+            for (const topicId of this.snapshots.keys()) {
+                if (!activeTopics.has(topicId)) {
+                    this.snapshots.delete(topicId);
+                }
+            }
+            // Check each active session
+            for (const [topicId, sessionName] of activeTopics) {
+                try {
+                    await this.checkSession(topicId, sessionName);
+                }
+                catch (err) {
+                    console.error(`[SessionMonitor] Error checking topic ${topicId}:`, err);
+                }
+            }
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    async checkSession(topicId, sessionName) {
+        const now = Date.now();
+        const alive = this.deps.isSessionAlive(sessionName);
+        // Get or create snapshot
+        let snap = this.snapshots.get(topicId);
+        if (!snap) {
+            snap = {
+                sessionName,
+                topicId,
+                lastOutput: '',
+                lastOutputAt: now,
+                lastUserMessageAt: 0,
+                lastAgentMessageAt: 0,
+                notifiedAt: null,
+                status: 'healthy',
+            };
+            this.snapshots.set(topicId, snap);
+        }
+        // Update session name if it changed (respawn)
+        snap.sessionName = sessionName;
+        // Capture current output
+        const currentOutput = alive ? (this.deps.captureSessionOutput(sessionName, 30) || '') : '';
+        // Check if output changed
+        if (currentOutput !== snap.lastOutput && currentOutput.length > 0) {
+            snap.lastOutput = currentOutput;
+            snap.lastOutputAt = now;
+        }
+        // Get recent message timestamps
+        const history = this.deps.getTopicHistory(topicId, 5);
+        for (const msg of history) {
+            const ts = new Date(msg.timestamp).getTime();
+            if (msg.fromUser && ts > snap.lastUserMessageAt) {
+                snap.lastUserMessageAt = ts;
+            }
+            else if (!msg.fromUser && ts > snap.lastAgentMessageAt) {
+                snap.lastAgentMessageAt = ts;
+            }
+        }
+        // Determine session health
+        const idleMinutes = Math.round((now - snap.lastOutputAt) / 60000);
+        const prevStatus = snap.status;
+        if (!alive) {
+            snap.status = 'dead';
+        }
+        else if (snap.lastUserMessageAt > snap.lastAgentMessageAt &&
+            now - snap.lastUserMessageAt > 10 * 60 * 1000) {
+            // User sent a message > 10 min ago and agent hasn't replied
+            snap.status = 'unresponsive';
+        }
+        else if (idleMinutes >= this.config.idleThresholdMinutes) {
+            snap.status = 'idle';
+        }
+        else {
+            snap.status = 'healthy';
+        }
+        // Take action based on health status
+        if (snap.status === 'healthy')
+            return;
+        if (snap.status === prevStatus && snap.notifiedAt)
+            return; // Already handled
+        // Check notification cooldown
+        if (snap.notifiedAt && now - snap.notifiedAt < this.config.notificationCooldownMinutes * 60 * 1000) {
+            return;
+        }
+        // Only act if the user has sent a message that's gone unanswered.
+        // A session sitting idle after the agent responded is NORMAL — the user
+        // just hasn't sent a new message yet. "Recently active" is not a reason
+        // to escalate; only an unanswered user message is.
+        const userExpectsResponse = snap.lastUserMessageAt > snap.lastAgentMessageAt;
+        if (!userExpectsResponse)
+            return; // Session idle but no unanswered message — normal state
+        // Try mechanical recovery first (fast, no LLM) before escalating to triage
+        if (this.deps.sessionRecovery && (snap.status === 'dead' || snap.status === 'unresponsive')) {
+            try {
+                const recoveryResult = await this.deps.sessionRecovery.checkAndRecover(topicId, sessionName);
+                this.emit('monitor:mechanical-recovery', { topicId, sessionName, result: recoveryResult });
+                if (recoveryResult.recovered) {
+                    console.log(`[SessionMonitor] Mechanical recovery succeeded for topic ${topicId}: ${recoveryResult.message}`);
+                    snap.status = 'healthy';
+                    snap.notifiedAt = now;
+                    return;
+                }
+            }
+            catch (err) {
+                console.error(`[SessionMonitor] Mechanical recovery error for topic ${topicId}:`, err);
+            }
+        }
+        switch (snap.status) {
+            case 'dead': {
+                this.emit('monitor:recovery-triggered', { topicId, sessionName, reason: 'session_dead' });
+                if (this.deps.triggerTriage) {
+                    const result = await this.deps.triggerTriage(topicId, sessionName, 'Session died while user was waiting');
+                    if (result.resolved) {
+                        snap.status = 'healthy';
+                        snap.notifiedAt = now;
+                        return;
+                    }
+                }
+                // If triage didn't resolve or isn't available, notify user
+                if (userExpectsResponse) {
+                    await this.deps.sendToTopic(topicId, `The session has stopped. Send a new message to start a fresh session with full conversation context.`).catch(() => { });
+                    this.emit('monitor:user-notified', { topicId, message: 'session_dead' });
+                }
+                snap.notifiedAt = now;
+                break;
+            }
+            case 'unresponsive': {
+                const waitMinutes = Math.round((now - snap.lastUserMessageAt) / 60000);
+                this.emit('monitor:unresponsive', { topicId, sessionName, waitMinutes });
+                if (this.deps.triggerTriage) {
+                    const result = await this.deps.triggerTriage(topicId, sessionName, `Session unresponsive for ${waitMinutes} minutes after user message`);
+                    if (result.resolved) {
+                        snap.status = 'healthy';
+                        snap.notifiedAt = now;
+                        return;
+                    }
+                }
+                snap.notifiedAt = now;
+                break;
+            }
+            case 'idle': {
+                this.emit('monitor:idle-detected', { topicId, sessionName, idleMinutes });
+                // For idle sessions, only notify if user is actively waiting
+                if (userExpectsResponse) {
+                    const msg = `Session has been idle for ${idleMinutes} minutes. Checking if it needs attention...`;
+                    await this.deps.sendToTopic(topicId, msg).catch(() => { });
+                    this.emit('monitor:user-notified', { topicId, message: 'session_idle' });
+                    if (this.deps.triggerTriage) {
+                        await this.deps.triggerTriage(topicId, sessionName, `Session idle for ${idleMinutes} minutes, user waiting`);
+                    }
+                }
+                snap.notifiedAt = now;
+                break;
+            }
+        }
+    }
+}
+//# sourceMappingURL=SessionMonitor.js.map

package/dist/monitoring/SessionMonitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionMonitor.js","sourceRoot":"","sources":["../../src/monitoring/SessionMonitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAkDtC,MAAM,cAAc,GAAmC;IACrD,OAAO,EAAE,IAAI;IACb,eAAe,EAAE,EAAE;IACnB,oBAAoB,EAAE,EAAE;IACxB,2BAA2B,EAAE,EAAE;CAChC,CAAC;AAEF,MAAM,OAAO,cAAe,SAAQ,YAAY;IACtC,MAAM,CAAiC;IACvC,IAAI,CAAqB;IACzB,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAC;IAC/C,QAAQ,GAA0C,IAAI,CAAC;IACvD,OAAO,GAAG,KAAK,CAAC;IAExB,YAAY,IAAwB,EAAE,MAAsC;QAC1E,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC;IACjD,CAAC;IAED,2DAA2D;IAClD,IAAI,CAAuC,KAAQ,EAAE,IAA6B;QACzF,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IACQ,EAAE,CAAuC,KAAQ,EAAE,QAAiD;QAC3G,OAAO,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,2DAA2D;IAC3D,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAClD,OAAO,CAAC,GAAG,CAAC,oCAAoC,IAAI,CAAC,MAAM,CAAC,eAAe,YAAY,IAAI,CAAC,MAAM,CAAC,oBAAoB,IAAI,CAAC,CAAC;QAC7H,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;QACnF,+DAA+D;QAC/D,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC7B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC;IACH,CAAC;IAED,SAAS;QAKP,MAAM,MAAM,GAAG,EAAE,CAAC;QAClB,KAAK,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC7C,MAAM,CAAC,IAAI,CAAC;gBACV,OAAO;gBACP,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC;aAClE,CAAC,CAAC;QACL,CAAC;QACD,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI;YACpC,aAAa,EAAE,MAAM;SACtB,CAAC;IACJ,CAAC;IAED,2DAA2D;IAC3D,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QAEpB,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,CAAC;YAExD,6DAA6D;YAC7D,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC5C,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC/B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBACjC,CAAC;YACH,CAAC;YAED,4BAA4B;YAC5B,KAAK,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,YAAY,EAAE,CAAC;gBAClD,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;gBAChD,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,KAAK,CAAC,yCAAyC,OAAO,GAAG,EAAE,GAAG,CAAC,CAAC;gBAC1E,CAAC;YACH,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACvB,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,OAAe,EAAE,WAAmB;QAC7D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;QAEpD,yBAAyB;QACzB,IAAI,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,IAAI,GAAG;gBACL,WAAW;gBACX,OAAO;gBACP,UAAU,EAAE,EAAE;gBACd,YAAY,EAAE,GAAG;gBACjB,iBAAiB,EAAE,CAAC;gBACpB,kBAAkB,EAAE,CAAC;gBACrB,UAAU,EAAE,IAAI;gBAChB,MAAM,EAAE,SAAS;aAClB,CAAC;YACF,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACpC,CAAC;QAED,8CAA8C;QAC9C,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAE/B,yBAAyB;QACzB,MAAM,aAAa,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,WAAW,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAE3F,0BAA0B;QAC1B,IAAI,aAAa,KAAK,IAAI,CAAC,UAAU,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClE,IAAI,CAAC,UAAU,GAAG,aAAa,CAAC;YAChC,IAAI,CAAC,YAAY,GAAG,GAAG,CAAC;QAC1B,CAAC;QAED,gCAAgC;QAChC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACtD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;YAC7C,IAAI,GAAG,CAAC,QAAQ,IAAI,EAAE,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBAChD,IAAI,CAAC,iBAAiB,GAAG,EAAE,CAAC;YAC9B,CAAC;iBAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;gBACzD,IAAI,CAAC,kBAAkB,GAAG,EAAE,CAAC;YAC/B,CAAC;QACH,CAAC;QAED,2BAA2B;QAC3B,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,CAAC;QAClE,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;QAE/B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACvB,CAAC;aAAM,IAAI,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,kBAAkB;YAChD,GAAG,GAAG,IAAI,CAAC,iBAAiB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;YACzD,4DAA4D;YAC5D,IAAI,CAAC,MAAM,GAAG,cAAc,CAAC;QAC/B,CAAC;aAAM,IAAI,WAAW,IAAI,IAAI,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC;YAC3D,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QAC1B,CAAC;QAED,qCAAqC;QACrC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO;QACtC,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO,CAAC,kBAAkB;QAE7E,8BAA8B;QAC9B,IAAI,IAAI,CAAC,UAAU,IAAI,GAAG,GAAG,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,2BAA2B,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;YACnG,OAAO;QACT,CAAC;QAED,kEAAkE;QAClE,wEAAwE;QACxE,wEAAwE;QACxE,mDAAmD;QACnD,MAAM,mBAAmB,GAAG,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,kBAAkB,CAAC;QAE7E,IAAI,CAAC,mBAAmB;YAAE,OAAO,CAAC,wDAAwD;QAE1F,2EAA2E;QAC3E,IAAI,IAAI,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,MAAM,IAAI,IAAI,CAAC,MAAM,KAAK,cAAc,CAAC,EAAE,CAAC;YAC5F,IAAI,CAAC;gBACH,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;gBAC7F,IAAI,CAAC,IAAI,CAAC,6BAA6B,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;gBAC3F,IAAI,cAAc,CAAC,SAAS,EAAE,CAAC;oBAC7B,OAAO,CAAC,GAAG,CAAC,4DAA4D,OAAO,KAAK,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC;oBAC9G,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;oBACxB,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;oBACtB,OAAO;gBACT,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,wDAAwD,OAAO,GAAG,EAAE,GAAG,CAAC,CAAC;YACzF,CAAC;QACH,CAAC;QAED,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;YACpB,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,IAAI,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;gBAC1F,IAAI,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;oBAC5B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,qCAAqC,CAAC,CAAC;oBAC1G,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;wBACpB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;wBACxB,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;wBACtB,OAAO;oBACT,CAAC;gBACH,CAAC;gBACD,2DAA2D;gBAC3D,IAAI,mBAAmB,EAAE,CAAC;oBACxB,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,EACjC,sGAAsG,CACvG,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBAClB,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;gBAC3E,CAAC;gBACD,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;gBACtB,MAAM;YACR,CAAC;YAED,KAAK,cAAc,CAAC,CAAC,CAAC;gBACpB,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,KAAK,CAAC,CAAC;gBACvE,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC;gBAEzE,IAAI,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;oBAC5B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,WAAW,EAC/D,4BAA4B,WAAW,6BAA6B,CAAC,CAAC;oBACxE,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;wBACpB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;wBACxB,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;wBACtB,OAAO;oBACT,CAAC;gBACH,CAAC;gBACD,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;gBACtB,MAAM;YACR,CAAC;YAED,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC;gBAC1E,6DAA6D;gBAC7D,IAAI,mBAAmB,EAAE,CAAC;oBACxB,MAAM,GAAG,GAAG,6BAA6B,WAAW,6CAA6C,CAAC;oBAClG,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBAC1D,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;oBAEzE,IAAI,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;wBAC5B,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,oBAAoB,WAAW,wBAAwB,CAAC,CAAC;oBAC/G,CAAC;gBACH,CAAC;gBACD,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;gBACtB,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/monitoring/SessionRecovery.d.ts

@@ -0,0 +1,129 @@
+/**
+ * SessionRecovery — Mechanical session crash/stall recovery via JSONL analysis.
+ *
+ * A fast, deterministic layer that runs BEFORE the LLM-powered TriageOrchestrator.
+ * Detects three failure modes without any LLM calls:
+ * 1. Tool call stalls (process alive but frozen mid-tool)
+ * 2. Crashes (process dead with incomplete JSONL)
+ * 3. Error loops (same error repeated 3+ times)
+ *
+ * Recovery strategy: truncate JSONL to safe point + respawn with recovery prompt.
+ * Escalation ladder: last_exchange → last_successful_tool → n_exchanges_back → alert human.
+ *
+ * Self-contained — no Dawn dependencies. Uses only:
+ * - stall-detector.ts (pure function)
+ * - crash-detector.ts (pure function)
+ * - jsonl-truncator.ts (pure function)
+ *
+ * Part of PROP-session-stall-recovery (Instar integration)
+ */
+import { EventEmitter } from 'events';
+import { type TruncationStrategy } from './jsonl-truncator.js';
+export interface SessionRecoveryConfig {
+    enabled: boolean;
+    /** Max recovery attempts per session before alerting human */
+    maxAttempts: number;
+    /** Cooldown between recovery attempts (ms) */
+    cooldownMs: number;
+    /** Project directory (used to find JSONL files) */
+    projectDir: string;
+}
+export interface RecoveryAttempt {
+    lastAttempt: number;
+    count: number;
+}
+export interface RecoveryResult {
+    recovered: boolean;
+    failureType: 'stall' | 'crash' | 'error_loop' | null;
+    strategy?: TruncationStrategy;
+    attemptNumber?: number;
+    message: string;
+}
+export interface SessionRecoveryDeps {
+    /** Check if a tmux session's Claude process is alive */
+    isSessionAlive: (sessionName: string) => boolean;
+    /** Get the PID of the pane in a tmux session */
+    getPanePid?: (sessionName: string) => number | null;
+    /** Kill a tmux session */
+    killSession: (sessionName: string) => void;
+    /** Respawn a session for a topic, optionally with a recovery prompt */
+    respawnSession: (topicId: number, sessionName?: string, recoveryPrompt?: string) => Promise<void>;
+    /** Send a message to a topic */
+    sendToTopic?: (topicId: number, message: string) => Promise<void>;
+}
+export declare class SessionRecovery extends EventEmitter {
+    private config;
+    private deps;
+    private recoveryAttempts;
+    private stateFilePath;
+    constructor(config: Partial<SessionRecoveryConfig>, deps: SessionRecoveryDeps);
+    /**
+     * Check a session for mechanical failures and attempt recovery.
+     * Should be called from SessionMonitor.checkSession() before LLM triage.
+     *
+     * @returns RecoveryResult — if recovered is true, caller should skip LLM triage
+     */
+    checkAndRecover(topicId: number, sessionName: string): Promise<RecoveryResult>;
+    /**
+     * Log a recovery event to the JSONL event log for observability.
+     */
+    logEvent(result: RecoveryResult, topicId: number, sessionName: string): void;
+    /**
+     * Aggregate recovery stats from the event log since a given timestamp.
+     */
+    getStats(sinceMs: number): {
+        attempts: {
+            stall: number;
+            crash: number;
+            errorLoop: number;
+        };
+        successes: {
+            stall: number;
+            crash: number;
+            errorLoop: number;
+        };
+    };
+    private recoverFromStall;
+    private recoverFromCrash;
+    private recoverFromErrorLoop;
+    private buildStallRecoveryPrompt;
+    private buildCrashRecoveryPrompt;
+    private buildErrorLoopRecoveryPrompt;
+    private pickTruncationStrategy;
+    private shouldAttempt;
+    private recordAttempt;
+    /**
+     * Load recovery state from disk. Prevents infinite kill-respawn loops
+     * across dawn-server restarts by preserving attempt counts and cooldowns.
+     */
+    private loadState;
+    /**
+     * Persist recovery state to disk so it survives process restarts.
+     */
+    private saveState;
+    /**
+     * Find the JSONL file for a session using lsof (Strategy 1) with NO fallback.
+     *
+     * Previous implementation fell back to most-recently-modified JSONL which
+     * could match a DIFFERENT healthy session, leading to cross-session corruption
+     * during truncation. Now returns null if lsof can't identify the file —
+     * better to skip recovery than corrupt the wrong session.
+     */
+    private findJsonlForSession;
+    /**
+     * Clean up old recovery tracking entries and stale .bak files.
+     */
+    cleanup(): void;
+    /**
+     * Remove .bak.* files older than maxAge from the Claude projects JSONL directory.
+     * Each recovery creates a full backup — without cleanup these accumulate indefinitely,
+     * consuming disk and retaining sensitive conversation data.
+     */
+    private cleanupBackupFiles;
+}
+/**
+ * Sanitize text for injection into a recovery prompt.
+ * Strips control characters, Unicode directional overrides, and truncates.
+ */
+export declare function sanitizeForPrompt(text: string, maxLength?: number): string;
+//# sourceMappingURL=SessionRecovery.d.ts.map

package/dist/monitoring/SessionRecovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionRecovery.d.ts","sourceRoot":"","sources":["../../src/monitoring/SessionRecovery.ts"],"names":[],"mappings":"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"}