aegis-bridge 2.3.0 → 2.3.1

package/dist/channels/types.d.ts

@@ -14,7 +14,7 @@ export interface ChannelHealthStatus {
     pendingCount: number;
 }
 /** Events a channel can subscribe to. */
-export type SessionEvent = 'session.created' | 'session.ended' | 'message.user' | 'message.assistant' | 'message.thinking' | 'message.tool_use' | 'message.tool_result' | 'status.idle' | 'status.working' | 'status.permission' | 'status.question' | 'status.plan' | 'status.stall' | 'status.dead' | 'status.stopped' | 'status.error' | 'status.rate_limited' | 'status.permission_timeout' | 'swarm.teammate_spawned' | 'swarm.teammate_finished';
+export type SessionEvent = 'session.created' | 'session.ended' | 'message.user' | 'message.assistant' | 'message.thinking' | 'message.tool_use' | 'message.tool_result' | 'status.idle' | 'status.working' | 'status.permission' | 'status.question' | 'status.plan' | 'status.stall' | 'status.dead' | 'status.stopped' | 'status.error' | 'status.rate_limited' | 'status.permission_timeout' | 'status.recovered' | 'swarm.teammate_spawned' | 'swarm.teammate_finished';
 /** Payload for all session events. */
 export interface SessionEventPayload {
     event: SessionEvent;

package/dist/monitor.d.ts

@@ -7,6 +7,7 @@
  * 3. Routes events to the ChannelManager (which fans out to Telegram, webhooks, etc.)
  */
 import { type SessionManager } from './session.js';
+import { type TmuxManager } from './tmux.js';
 import { type ChannelManager } from './channels/index.js';
 import { type SessionEventBus } from './events.js';
 import { type JsonlWatcher } from './jsonl-watcher.js';
@@ -40,6 +41,9 @@ export declare class SessionMonitor {
     private deadNotified;
     private prevStatusForStall;
     private rateLimitedSessions;
+    private tmuxWasDown;
+    private lastTmuxHealthCheck;
+    private static readonly TMUX_HEALTH_CHECK_INTERVAL_MS;
     /** Issue #89 L4: Debounce status change broadcasts per session.
      *  If multiple status changes happen within 500ms, only emit the last one.
      *  Prevents rapid-fire notifications during state transitions. */
@@ -51,6 +55,9 @@ export declare class SessionMonitor {
     constructor(sessions: SessionManager, channels: ChannelManager, config?: MonitorConfig);
     /** Issue #32: Set the event bus for SSE streaming. */
     setEventBus(bus: SessionEventBus): void;
+    /** Issue #397: Set the TmuxManager reference for tmux health checks. */
+    private tmux?;
+    setTmuxManager(tmuxManager: TmuxManager): void;
     /** Issue #84: Set the JSONL watcher for fs.watch-based message detection. */
     setJsonlWatcher(watcher: JsonlWatcher): void;
     start(): void;
@@ -79,6 +86,8 @@ export declare class SessionMonitor {
     private makePayload;
     /** Check for dead tmux windows and notify via channels. */
     private checkDeadSessions;
+    /** Issue #397: Check tmux server health. Detect crashes and trigger reconciliation. */
+    private checkTmuxHealth;
     /** Clean up tracking for a killed session. */
     removeSession(sessionId: string): void;
 }

package/dist/monitor.js

@@ -43,6 +43,10 @@ export class SessionMonitor {
     deadNotified = new Set(); // don't spam dead session events
     prevStatusForStall = new Map(); // track previous status for stall transition detection
     rateLimitedSessions = new Set(); // sessions in rate-limit backoff
+    // Issue #397: Track tmux server health for crash recovery
+    tmuxWasDown = false;
+    lastTmuxHealthCheck = 0;
+    static TMUX_HEALTH_CHECK_INTERVAL_MS = 10_000; // check every 10s
     /** Issue #89 L4: Debounce status change broadcasts per session.
      *  If multiple status changes happen within 500ms, only emit the last one.
      *  Prevents rapid-fire notifications during state transitions. */
@@ -61,6 +65,11 @@ export class SessionMonitor {
     setEventBus(bus) {
         this.eventBus = bus;
     }
+    /** Issue #397: Set the TmuxManager reference for tmux health checks. */
+    tmux;
+    setTmuxManager(tmuxManager) {
+        this.tmux = tmuxManager;
+    }
     /** Issue #84: Set the JSONL watcher for fs.watch-based message detection. */
     setJsonlWatcher(watcher) {
         this.jsonlWatcher = watcher;
@@ -130,6 +139,11 @@ export class SessionMonitor {
             this.lastDeadCheck = now;
             await this.checkDeadSessions();
         }
+        // Issue #397: Tmux server health check (every 10s)
+        if (now - this.lastTmuxHealthCheck >= SessionMonitor.TMUX_HEALTH_CHECK_INTERVAL_MS) {
+            this.lastTmuxHealthCheck = now;
+            await this.checkTmuxHealth();
+        }
     }
     /** Smart stall detection: multiple stall types with graduated thresholds.
      *
@@ -547,6 +561,33 @@ export class SessionMonitor {
             }
         }
     }
+    /** Issue #397: Check tmux server health. Detect crashes and trigger reconciliation. */
+    async checkTmuxHealth() {
+        if (!this.tmux)
+            return;
+        const { healthy } = await this.tmux.isServerHealthy();
+        if (!healthy) {
+            if (!this.tmuxWasDown) {
+                console.warn('Monitor: tmux server is unreachable — sessions may be orphaned');
+                this.tmuxWasDown = true;
+            }
+            return;
+        }
+        // Tmux is healthy now
+        if (this.tmuxWasDown) {
+            console.log('Monitor: tmux server recovered — triggering crash reconciliation');
+            this.tmuxWasDown = false;
+            // Trigger crash reconciliation to re-attach or mark orphaned sessions
+            const result = await this.sessions.reconcileTmuxCrash();
+            if (result.recovered > 0 || result.orphaned > 0) {
+                console.log(`Monitor: crash reconciliation complete — recovered: ${result.recovered}, orphaned: ${result.orphaned}`);
+                // Notify channels about recovery
+                for (const session of this.sessions.listSessions()) {
+                    await this.channels.statusChange(this.makePayload('status.recovered', session, `tmux server recovered. Session ${session.windowName} re-attached.`));
+                }
+            }
+        }
+    }
     /** Clean up tracking for a killed session. */
     removeSession(sessionId) {
         // Issue #84: Stop watching JSONL file for this session

package/dist/server.js

@@ -230,16 +230,19 @@ const createSessionSchema = z.object({
     permissionMode: z.enum(['default', 'bypassPermissions', 'plan']).optional(),
     autoApprove: z.boolean().optional(),
 }).strict();
-// Health
+// Health — Issue #397: includes tmux server health check
 app.get('/v1/health', async () => {
     const pkg = await import('../package.json', { with: { type: 'json' } });
     const activeCount = sessions.listSessions().length;
     const totalCount = metrics.getTotalSessionsCreated();
+    const tmuxHealth = await tmux.isServerHealthy();
+    const status = tmuxHealth.healthy ? 'ok' : 'degraded';
     return {
-        status: 'ok',
+        status,
         version: pkg.default.version,
         uptime: process.uptime(),
         sessions: { active: activeCount, total: totalCount },
+        tmux: tmuxHealth,
         timestamp: new Date().toISOString(),
     };
 });
@@ -248,11 +251,14 @@ app.get('/health', async () => {
     const pkg = await import('../package.json', { with: { type: 'json' } });
     const activeCount = sessions.listSessions().length;
     const totalCount = metrics.getTotalSessionsCreated();
+    const tmuxHealth = await tmux.isServerHealthy();
+    const status = tmuxHealth.healthy ? 'ok' : 'degraded';
     return {
-        status: 'ok',
+        status,
         version: pkg.default.version,
         uptime: process.uptime(),
         sessions: { active: activeCount, total: totalCount },
+        tmux: tmuxHealth,
         timestamp: new Date().toISOString(),
     };
 });
@@ -1427,6 +1433,8 @@ async function main() {
     await channels.init(handleInbound);
     // Wire SSE event bus (Issue #32)
     monitor.setEventBus(eventBus);
+    // Issue #397: Wire TmuxManager for tmux health monitoring
+    monitor.setTmuxManager(tmux);
     // Issue #84: Wire JSONL watcher for fs.watch-based message detection
     jsonlWatcher = new JsonlWatcher();
     monitor.setJsonlWatcher(jsonlWatcher);

package/dist/session.d.ts

@@ -70,8 +70,16 @@ export declare class SessionManager {
     private cleanTmpFiles;
     /** Load state from disk. */
     load(): Promise<void>;
-    /** Reconcile state with actual tmux windows. Remove dead sessions, restart discovery for live ones. */
+    /** Reconcile state with actual tmux windows. Remove dead sessions, restart discovery for live ones.
+     *  Issue #397: Also handles re-attach by window name when windowId is stale after tmux restart. */
     private reconcile;
+    /** Issue #397: Reconcile after tmux server crash recovery.
+     *  Called when the monitor detects tmux server came back after a crash.
+     *  Returns counts for observability. */
+    reconcileTmuxCrash(): Promise<{
+        recovered: number;
+        orphaned: number;
+    }>;
     /** Save state to disk atomically (write to temp, then rename).
      *  #218: Uses a write queue to serialize concurrent saves and prevent corruption. */
     save(): Promise<void>;

package/dist/session.js

@@ -143,15 +143,19 @@ export class SessionManager {
         // Reconcile: verify tmux windows still exist, clean up dead sessions
         await this.reconcile();
     }
-    /** Reconcile state with actual tmux windows. Remove dead sessions, restart discovery for live ones. */
+    /** Reconcile state with actual tmux windows. Remove dead sessions, restart discovery for live ones.
+     *  Issue #397: Also handles re-attach by window name when windowId is stale after tmux restart. */
     async reconcile() {
         const windows = await this.tmux.listWindows();
         const windowIds = new Set(windows.map(w => w.windowId));
-        const windowNames = new Set(windows.map(w => w.windowName));
+        const windowByName = new Map();
+        for (const w of windows)
+            windowByName.set(w.windowName, w);
         let changed = false;
         for (const [id, session] of Object.entries(this.state.sessions)) {
-            const alive = windowIds.has(session.windowId) || windowNames.has(session.windowName);
-            if (!alive) {
+            const windowIdAlive = windowIds.has(session.windowId);
+            const windowNameAlive = windowByName.has(session.windowName);
+            if (!windowIdAlive && !windowNameAlive) {
                 console.log(`Reconcile: session ${session.windowName} (${id.slice(0, 8)}) — tmux window gone, removing`);
                 // Restore patched settings before removing dead session
                 if (session.settingsPatched) {
@@ -160,6 +164,19 @@ export class SessionManager {
                 delete this.state.sessions[id];
                 changed = true;
             }
+            else if (!windowIdAlive && windowNameAlive) {
+                // Issue #397: Window exists with same name but different ID (tmux restarted).
+                // Re-attach by updating the windowId to the new one.
+                const win = windowByName.get(session.windowName);
+                const oldWindowId = session.windowId;
+                session.windowId = win.windowId;
+                console.log(`Reconcile: session ${session.windowName} re-attached: ${oldWindowId} → ${win.windowId}`);
+                // Restart discovery if needed
+                if (!session.claudeSessionId || !session.jsonlPath) {
+                    this.startSessionIdDiscovery(id);
+                }
+                changed = true;
+            }
             else {
                 // Session is alive — restart discovery if needed
                 if (!session.claudeSessionId || !session.jsonlPath) {
@@ -172,7 +189,9 @@ export class SessionManager {
             }
         }
         // P0 fix: On startup, purge session_map entries that don't correspond to active sessions.
-        await this.purgeStaleSessionMapEntries(windowIds, windowNames);
+        const finalWindowIds = new Set(Object.values(this.state.sessions).map(s => s.windowId));
+        const finalWindowNames = new Set(Object.values(this.state.sessions).map(s => s.windowName));
+        await this.purgeStaleSessionMapEntries(finalWindowIds, finalWindowNames);
         // Issue #35: Adopt orphaned tmux windows (cc-* prefix) not in state
         const knownWindowIds = new Set(Object.values(this.state.sessions).map(s => s.windowId));
         const knownWindowNames = new Set(Object.values(this.state.sessions).map(s => s.windowName));
@@ -207,6 +226,56 @@ export class SessionManager {
             await this.save();
         }
     }
+    /** Issue #397: Reconcile after tmux server crash recovery.
+     *  Called when the monitor detects tmux server came back after a crash.
+     *  Returns counts for observability. */
+    async reconcileTmuxCrash() {
+        console.log('Reconcile: tmux crash recovery — checking all sessions');
+        const windows = await this.tmux.listWindows();
+        const windowIds = new Set(windows.map(w => w.windowId));
+        const windowByName = new Map();
+        for (const w of windows)
+            windowByName.set(w.windowName, w);
+        let recovered = 0;
+        let orphaned = 0;
+        let changed = false;
+        for (const [id, session] of Object.entries(this.state.sessions)) {
+            const windowIdAlive = windowIds.has(session.windowId);
+            const windowNameAlive = windowByName.has(session.windowName);
+            if (windowIdAlive) {
+                // Window ID still matches — session survived the crash
+                continue;
+            }
+            if (windowNameAlive) {
+                // Window exists by name but ID changed — re-attach
+                const win = windowByName.get(session.windowName);
+                const oldWindowId = session.windowId;
+                session.windowId = win.windowId;
+                session.status = 'unknown';
+                session.lastActivity = Date.now();
+                console.log(`Reconcile (crash): session ${session.windowName} re-attached: ${oldWindowId} → ${win.windowId}`);
+                // Restart discovery in case the session state is stale
+                if (!session.claudeSessionId || !session.jsonlPath) {
+                    this.startSessionIdDiscovery(id);
+                    this.startFilesystemDiscovery(id, session.workDir);
+                }
+                recovered++;
+                changed = true;
+            }
+            else {
+                // Window gone entirely — session is orphaned
+                console.log(`Reconcile (crash): session ${session.windowName} (${id.slice(0, 8)}) — window gone, marking orphaned`);
+                session.status = 'unknown';
+                session.lastDeadAt = Date.now();
+                orphaned++;
+                changed = true;
+            }
+        }
+        if (changed) {
+            await this.save();
+        }
+        return { recovered, orphaned };
+    }
     /** Save state to disk atomically (write to temp, then rename).
      *  #218: Uses a write queue to serialize concurrent saves and prevent corruption. */
     async save() {

package/dist/tmux.d.ts

@@ -154,6 +154,15 @@ export declare class TmuxManager {
     resizePane(windowId: string, cols: number, rows: number): Promise<void>;
     /** Kill a window. */
     killWindow(windowId: string): Promise<void>;
+    /** Issue #397: Check if the tmux server is reachable and healthy.
+     *  Returns { healthy, error } — does not throw. */
+    isServerHealthy(): Promise<{
+        healthy: boolean;
+        error: string | null;
+    }>;
+    /** Issue #397: Check if a tmux error indicates the server crashed (vs window-not-found).
+     *  Server crash errors contain specific patterns from tmux CLI. */
+    isTmuxServerError(error: unknown): boolean;
     /** Kill the entire tmux session. Used for cleanup on shutdown. */
     killSession(sessionName?: string): Promise<void>;
     /** #357: Poll until condition returns true or timeout elapses. */

package/dist/tmux.js

@@ -697,6 +697,32 @@ export class TmuxManager {
             console.warn(`Tmux: killWindow failed for ${target}: ${e.message}`);
         }
     }
+    /** Issue #397: Check if the tmux server is reachable and healthy.
+     *  Returns { healthy, error } — does not throw. */
+    async isServerHealthy() {
+        try {
+            await this.tmuxInternal('list-sessions');
+            return { healthy: true, error: null };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return { healthy: false, error: msg };
+        }
+    }
+    /** Issue #397: Check if a tmux error indicates the server crashed (vs window-not-found).
+     *  Server crash errors contain specific patterns from tmux CLI. */
+    isTmuxServerError(error) {
+        if (!(error instanceof Error))
+            return false;
+        const msg = error.message.toLowerCase();
+        // "no server running" = tmux server not started
+        // "failed to connect to server" = socket/protocol error
+        // "connection refused" = server died mid-operation
+        return msg.includes('no server running')
+            || msg.includes('failed to connect')
+            || msg.includes('connection refused')
+            || msg.includes('no tmux server');
+    }
     /** Kill the entire tmux session. Used for cleanup on shutdown. */
     async killSession(sessionName) {
         const target = sessionName ?? this.sessionName;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aegis-bridge",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "type": "module",
   "description": "Orchestrate Claude Code sessions via API. Create, brief, monitor, refine, ship.",
   "main": "dist/server.js",