aegis-bridge 0.1.0

package/dist/session-cleanup.d.ts

@@ -0,0 +1,18 @@
+/**
+ * session-cleanup.ts — Shared per-session cleanup for terminated sessions.
+ *
+ * Ensures all server-side session-keyed tracking structures are cleaned in
+ * every termination path (API kill, inbound kill, stale reaper, zombie reaper).
+ */
+export interface SessionCleanupDeps {
+    monitor: {
+        removeSession(sessionId: string): void;
+    };
+    metrics: {
+        cleanupSession(sessionId: string): void;
+    };
+    toolRegistry: {
+        cleanupSession(sessionId: string): void;
+    };
+}
+export declare function cleanupTerminatedSessionState(sessionId: string, deps: SessionCleanupDeps): void;

package/dist/session-cleanup.js

@@ -0,0 +1,11 @@
+/**
+ * session-cleanup.ts — Shared per-session cleanup for terminated sessions.
+ *
+ * Ensures all server-side session-keyed tracking structures are cleaned in
+ * every termination path (API kill, inbound kill, stale reaper, zombie reaper).
+ */
+export function cleanupTerminatedSessionState(sessionId, deps) {
+    deps.monitor.removeSession(sessionId);
+    deps.metrics.cleanupSession(sessionId);
+    deps.toolRegistry.cleanupSession(sessionId);
+}

package/dist/session.d.ts

@@ -0,0 +1,379 @@
+/**
+ * session.ts — Session state manager.
+ *
+ * Manages the lifecycle of CC sessions running in tmux windows.
+ * Tracks: session ID, window ID, byte offset for JSONL reading, status.
+ */
+import { TmuxManager } from './tmux.js';
+import { type ParsedEntry } from './transcript.js';
+import { type UIState } from './terminal-parser.js';
+import type { Config } from './config.js';
+import { type PermissionPolicy, type PermissionProfile } from './validation.js';
+import { type PermissionDecision } from './permission-request-manager.js';
+/**
+ * Canonical runtime metadata for an Aegis-managed Claude Code session.
+ *
+ * This structure is persisted to disk and reused by the REST API, SSE layer,
+ * monitoring loop, and session recovery logic.
+ */
+export interface SessionInfo {
+    id: string;
+    windowId: string;
+    windowName: string;
+    workDir: string;
+    claudeSessionId?: string;
+    jsonlPath?: string;
+    byteOffset: number;
+    monitorOffset: number;
+    status: UIState;
+    createdAt: number;
+    lastActivity: number;
+    stallThresholdMs: number;
+    permissionStallMs: number;
+    permissionMode: string;
+    settingsPatched?: boolean;
+    hookSettingsFile?: string;
+    hookSecret?: string;
+    lastHookAt?: number;
+    activeSubagents?: Set<string>;
+    permissionPromptAt?: number;
+    permissionRespondedAt?: number;
+    lastHookReceivedAt?: number;
+    lastHookEventAt?: number;
+    model?: string;
+    lastDeadAt?: number;
+    ccPid?: number;
+    parentId?: string;
+    children?: string[];
+    permissionPolicy?: PermissionPolicy;
+    permissionProfile?: PermissionProfile;
+    prd?: string;
+}
+/** Persisted session store keyed by Aegis session ID. */
+export interface SessionState {
+    sessions: Record<string, SessionInfo>;
+}
+/**
+ * Detect whether CC is showing numbered permission options (e.g. "1. Yes, 2. No")
+ * vs a simple y/N prompt. Returns the approval method to use.
+ *
+ * CC's permission UI uses indented numbered lines with "Esc to cancel" nearby.
+ * We look for the pattern "  <N>. <option>" where N is 1-3, which distinguishes
+ * permission options from regular numbered lists in output.
+ */
+export declare function detectApprovalMethod(paneText: string): 'numbered' | 'yes';
+/** Resolves a pending PermissionRequest hook with a decision. */
+export type { PermissionDecision };
+/**
+ * Coordinates session lifecycle, persistence, transcript discovery, and
+ * interactive approval/question flows for all managed Claude Code sessions.
+ */
+export declare class SessionManager {
+    private tmux;
+    private config;
+    private state;
+    private stateFile;
+    private sessionMapFile;
+    private pollTimers;
+    /** Next filesystem-scan time (ms epoch) for each discovery poller. */
+    private discoveryNextFilesystemScanAt;
+    /** #835: Discovery timeout timers — cleared in cleanupSession to prevent orphan callbacks. */
+    private discoveryTimeouts;
+    private saveQueue;
+    private saveDebounceTimer;
+    private static readonly SAVE_DEBOUNCE_MS;
+    private permissionRequests;
+    private questions;
+    private static readonly MAX_CACHE_ENTRIES_PER_SESSION;
+    private parsedEntriesCache;
+    private sessionsListCache;
+    private readonly sessionAcquireMutex;
+    constructor(tmux: TmuxManager, config: Config);
+    /**
+     * Issue #884: Worktree-aware session file lookup.
+     * When `worktreeAwareContinuation` is enabled, fans out to sibling worktree
+     * project dirs; otherwise falls back to the existing single-directory search.
+     */
+    private findSessionFileMaybeWorktree;
+    /** Validate that parsed data looks like a valid SessionState. */
+    private isValidState;
+    /** Clean up stale .tmp files left by crashed writes. */
+    private cleanTmpFiles;
+    /** Load state from disk. */
+    load(): Promise<void>;
+    /** 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>;
+    /** #357: Debounced save — skips immediate save for offset-only changes.
+     *  Coalesces rapid successive reads into a single disk write. */
+    debouncedSave(): void;
+    private doSave;
+    /** Default stall threshold: 2 min (Issue #392: 1.5x CC's 90s default, configurable via CLAUDE_STREAM_IDLE_TIMEOUT_MS). */
+    static readonly DEFAULT_STALL_THRESHOLD_MS: number;
+    static readonly DEFAULT_PERMISSION_STALL_MS: number;
+    /** Create a new CC session. */
+    /** Default timeout for waiting CC to become ready (60s for cold starts). */
+    static readonly DEFAULT_PROMPT_TIMEOUT_MS = 60000;
+    /** Max retries if CC doesn't become ready in time. */
+    static readonly DEFAULT_PROMPT_MAX_RETRIES = 2;
+    /**
+     * Wait for CC to show its idle prompt in the tmux pane, then send the initial prompt.
+     * Uses exponential backoff on retry: first attempt waits timeoutMs, subsequent attempts
+     * wait 1.5x the previous timeout.
+     *
+     * Returns delivery result. Logs warnings on each retry for observability.
+     */
+    sendInitialPrompt(sessionId: string, prompt: string, timeoutMs?: number, maxRetries?: number): Promise<{
+        delivered: boolean;
+        attempts: number;
+    }>;
+    /** Wait for CC idle prompt, then send. Single attempt. */
+    private waitForReadyAndSend;
+    /**
+     * Issue #561: After sending an initial prompt, verify CC actually accepted it
+     * by polling for a state transition away from idle/unknown.
+     * Returns true if CC transitions to a recognized active state within the timeout.
+     */
+    private verifyPromptAccepted;
+    createSession(opts: {
+        workDir: string;
+        name?: string;
+        prd?: string;
+        resumeSessionId?: string;
+        claudeCommand?: string;
+        env?: Record<string, string>;
+        stallThresholdMs?: number;
+        permissionStallMs?: number;
+        permissionMode?: string;
+        /** @deprecated Use permissionMode instead. Maps true→bypassPermissions, false→default. */
+        autoApprove?: boolean;
+        /** Issue #702: Parent session ID for sub-agent hierarchy */
+        parentId?: string;
+    }): Promise<SessionInfo>;
+    /** Get a session by ID. */
+    getSession(id: string): SessionInfo | null;
+    /** Issue #169 Phase 3: Update session status from a hook event.
+     *  Returns the previous status for change detection.
+     *  Issue #87: Also records hook latency timestamps. */
+    updateStatusFromHook(id: string, hookEvent: string, hookTimestamp?: number): UIState | null;
+    /** Issue #812: Detect if CC is waiting for user input by analyzing the JSONL transcript.
+     *  Returns true if the last assistant message has text content only (no tool_use). */
+    detectWaitingForInput(id: string): Promise<boolean>;
+    /** Issue #88: Add an active subagent to a session. */
+    addSubagent(id: string, name: string): void;
+    /** Issue #88: Remove an active subagent from a session. */
+    removeSubagent(id: string, name: string): void;
+    /** Issue #89 L25: Update the model field on a session from hook payload. */
+    updateSessionModel(id: string, model: string): void;
+    /** Issue #87: Get latency metrics for a session. */
+    getLatencyMetrics(id: string): {
+        hook_latency_ms: number | null;
+        state_change_detection_ms: number | null;
+        permission_response_ms: number | null;
+    } | null;
+    /** Check if a session's tmux window still exists and has a live process.
+     *  Issue #69: A window can exist with a crashed/zombie CC process (zombie window).
+     *  After checking window exists, also verify the pane PID is alive.
+     *  Issue #390: Check stored ccPid first for immediate crash detection.
+     *  When CC crashes (SIGKILL, OOM), the shell prompt returns in the pane,
+     *  so the current pane PID is the shell (alive). Checking ccPid catches
+     *  the crash within seconds instead of waiting for the 5-min stall timer. */
+    isWindowAlive(id: string): Promise<boolean>;
+    /** Issue #657: Invalidate the sessions list cache. Call on any mutation. */
+    private invalidateSessionsListCache;
+    /** List all sessions. */
+    listSessions(): SessionInfo[];
+    /** Issue #607: Find an idle session for the given workDir.
+     *  Returns the most recently active idle session, or null if none found.
+     *  Used to resume existing sessions instead of creating duplicates.
+     *  Issue #636: Verifies tmux window is still alive before returning.
+     *  Issue #840/#880: Atomically acquires the session under a mutex to prevent TOCTOU race. */
+    findIdleSessionByWorkDir(workDir: string): Promise<SessionInfo | null>;
+    /** Release a session claim after the reuse path completes (success or failure). */
+    releaseSessionClaim(id: string): void;
+    /** Get health info for a session.
+     *  Issue #2: Returns comprehensive health status for orchestrators.
+     */
+    getHealth(id: string): Promise<{
+        alive: boolean;
+        windowExists: boolean;
+        claudeRunning: boolean;
+        paneCommand: string | null;
+        status: UIState;
+        hasTranscript: boolean;
+        lastActivity: number;
+        lastActivityAgo: number;
+        sessionAge: number;
+        details: string;
+        actionHints?: Record<string, {
+            method: string;
+            url: string;
+            description: string;
+        }>;
+    }>;
+    /** Send a message to a session with delivery verification.
+     *  Issue #1: Uses capture-pane to verify the prompt was delivered.
+     *  Returns delivery status for API response.
+     */
+    sendMessage(id: string, text: string): Promise<{
+        delivered: boolean;
+        attempts: number;
+    }>;
+    /** Send message bypassing the tmux serialize queue.
+     *  Used by sendInitialPrompt for critical-path prompt delivery.
+     *
+     *  Issue #285: Changed from sendKeysDirect (unverified) to sendKeysVerified
+     *  with 3 retry attempts. tmux send-keys can silently fail even at session
+     *  creation time, causing ~20% prompt delivery failure rate.
+     *
+     *  We still bypass the serialize queue (using capturePaneDirect in verifyDelivery)
+     *  but now verify actual delivery to CC.
+     */
+    private sendMessageDirect;
+    /** Record that a permission prompt was detected for this session. */
+    recordPermissionPrompt(id: string): void;
+    /** Approve a permission prompt. Resolves pending hook permission first, falls back to tmux send-keys. */
+    approve(id: string): Promise<void>;
+    /** Reject a permission prompt. Resolves pending hook permission first, falls back to tmux send-keys. */
+    reject(id: string): Promise<void>;
+    /**
+     * Issue #284: Store a pending permission request and return a promise that
+     * resolves when the client approves/rejects via the API.
+     *
+     * @param sessionId - Aegis session ID
+     * @param timeoutMs - Timeout before auto-rejecting (default 10_000ms, matching CC's hook timeout)
+     * @param toolName - Optional tool name from the hook payload
+     * @param prompt - Optional permission prompt text
+     * @returns Promise that resolves with the client's decision
+     */
+    waitForPermissionDecision(sessionId: string, timeoutMs?: number, toolName?: string, prompt?: string): Promise<PermissionDecision>;
+    /** Check if a session has a pending permission request. */
+    hasPendingPermission(sessionId: string): boolean;
+    /** Get info about a pending permission (for API responses). */
+    getPendingPermissionInfo(sessionId: string): {
+        toolName?: string;
+        prompt?: string;
+    } | null;
+    /** Clean up any pending permission for a session (e.g. on session delete). */
+    cleanupPendingPermission(sessionId: string): void;
+    /**
+     * Issue #336: Store a pending AskUserQuestion and return a promise that
+     * resolves when the external client provides an answer via POST /answer.
+     */
+    waitForAnswer(sessionId: string, toolUseId: string, question: string, timeoutMs?: number): Promise<string | null>;
+    /** Issue #336: Submit an answer to a pending question. Returns true if resolved. */
+    submitAnswer(sessionId: string, questionId: string, answer: string): boolean;
+    /** Issue #336: Check if a session has a pending question. */
+    hasPendingQuestion(sessionId: string): boolean;
+    /** Issue #336: Get info about a pending question. */
+    getPendingQuestionInfo(sessionId: string): {
+        toolUseId: string;
+        question: string;
+        timestamp: number;
+    } | null;
+    /** Issue #336: Clean up any pending question for a session. */
+    cleanupPendingQuestion(sessionId: string): void;
+    /** Send Escape key. */
+    escape(id: string): Promise<void>;
+    /** Send Ctrl+C. */
+    interrupt(id: string): Promise<void>;
+    /** Read new messages from a session. */
+    readMessages(id: string): Promise<{
+        messages: ParsedEntry[];
+        status: UIState;
+        statusText: string | null;
+        interactiveContent: string | null;
+    }>;
+    /** Read new messages for the monitor (separate offset from API reads). */
+    readMessagesForMonitor(id: string): Promise<{
+        messages: ParsedEntry[];
+        status: UIState;
+        statusText: string | null;
+        interactiveContent: string | null;
+    }>;
+    /** #357: Get all parsed entries for a session, using a cache to avoid full reparse.
+     *  Reads only the delta from the last cached offset. */
+    private getCachedEntries;
+    /** Issue #35: Get a condensed summary of a session's transcript. */
+    getSummary(id: string, maxMessages?: number): Promise<{
+        sessionId: string;
+        windowName: string;
+        status: UIState;
+        totalMessages: number;
+        messages: Array<{
+            role: string;
+            contentType: string;
+            text: string;
+        }>;
+        createdAt: number;
+        lastActivity: number;
+        permissionMode: string;
+        prd?: string;
+    }>;
+    /** Paginated transcript read — does NOT advance the session's byteOffset. */
+    readTranscript(id: string, page?: number, limit?: number, roleFilter?: 'user' | 'assistant' | 'system'): Promise<{
+        messages: ParsedEntry[];
+        total: number;
+        page: number;
+        limit: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * Cursor-based transcript read — stable under concurrent appends.
+     *
+     * Uses 1-based sequential entry indices as cursors.
+     * - `beforeId`: exclusive upper bound (fetch entries with index < beforeId).
+     *               If omitted, fetch the newest `limit` entries.
+     * - `limit`: max entries to return (capped at 200).
+     * - Returns entries in ascending order (oldest first) within the window.
+     */
+    readTranscriptCursor(id: string, beforeId?: number, limit?: number, roleFilter?: 'user' | 'assistant' | 'system'): Promise<{
+        messages: (ParsedEntry & {
+            _cursor_id: number;
+        })[];
+        has_more: boolean;
+        oldest_id: number | null;
+        newest_id: number | null;
+    }>;
+    /** #405: Clean up all tracking maps for a session to prevent memory leaks. */
+    private cleanupSession;
+    /** Kill a session. */
+    killSession(id: string): Promise<void>;
+    /** Remove stale entries from session_map.json for a given window.
+     *  P0 fix: After aegis service restarts, old session_map entries with stale windowIds
+     *  can survive and cause new sessions to inherit context from old sessions.
+     *  We must clean by BOTH windowName AND windowId to prevent collisions.
+     *
+     *  After archiving old .jsonl files, old hook entries would cause discovery
+     *  to map the new session to a ghost claudeSessionId whose file no longer exists.
+     */
+    private cleanSessionMapForWindow;
+    /** P0 fix: Purge session_map entries that don't correspond to active aegis sessions.
+     *  After aegis restarts, old session_map entries with stale windowIds can survive
+     *  and cause new sessions to inherit context from old sessions.
+     */
+    private purgeStaleSessionMapEntries;
+    /** Stop and remove the coordinated discovery poller/timer for a session. */
+    private stopDiscoveryPolling;
+    /** Attempt filesystem-based discovery for a single session poll tick. */
+    private maybeDiscoverFromFilesystem;
+    /**
+     * Coordinated discovery poller for a session.
+     *
+     * Consolidates hook/session_map sync and filesystem fallback into a single
+     * interval loop per session, reducing duplicate independent pollers.
+     */
+    private startDiscoveryPolling;
+    /** Sync CC session IDs from the hook-written session_map.json. */
+    private syncSessionMap;
+}