aegis-bridge 0.1.0

package/dist/session.js

@@ -0,0 +1,1568 @@
+/**
+ * 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 { randomBytes } from 'node:crypto';
+import { readFile, writeFile, rename, mkdir, stat, readdir } from 'node:fs/promises';
+import { existsSync, unlinkSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { findSessionFile, readNewEntries } from './transcript.js';
+import { findSessionFileWithFanout } from './worktree-lookup.js';
+import { detectUIState, extractInteractiveContent, parseStatusLine } from './terminal-parser.js';
+import { computeStallThreshold } from './config.js';
+import { neutralizeBypassPermissions, restoreSettings, cleanOrphanedBackup } from './permission-guard.js';
+import { persistedStateSchema } from './validation.js';
+import { loadContinuationPointers } from './continuation-pointer.js';
+import { writeHookSettingsFile, cleanupHookSettingsFile, cleanupStaleSessionHooks } from './hook-settings.js';
+import { PermissionRequestManager } from './permission-request-manager.js';
+import { QuestionManager } from './question-manager.js';
+import { Mutex } from 'async-mutex';
+import { maybeInjectFault } from './fault-injection.js';
+import { computeProjectHash } from './path-utils.js';
+/** Convert parsed JSON arrays to Sets for activeSubagents (#668). */
+function hydrateSessions(raw) {
+    const sessions = {};
+    for (const [id, s] of Object.entries(raw)) {
+        const { activeSubagents, ...rest } = s;
+        sessions[id] = {
+            ...rest,
+            activeSubagents: activeSubagents ? new Set(activeSubagents) : undefined,
+        };
+    }
+    return sessions;
+}
+/**
+ * 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 function detectApprovalMethod(paneText) {
+    // Match CC's permission option format: indented "  1. Yes" lines.
+    // Issue #843: Tightened to require "Esc to cancel" nearby (within 300 chars)
+    // to avoid false positives on regular indented numbered lists in output.
+    const numberedOptionPattern = /^\s{2}[1-3]\.\s/m;
+    if (numberedOptionPattern.test(paneText) && /Esc to cancel/i.test(paneText)) {
+        return 'numbered';
+    }
+    return 'yes';
+}
+/**
+ * Coordinates session lifecycle, persistence, transcript discovery, and
+ * interactive approval/question flows for all managed Claude Code sessions.
+ */
+export class SessionManager {
+    tmux;
+    config;
+    state = { sessions: {} };
+    stateFile;
+    sessionMapFile;
+    pollTimers = new Map();
+    /** Next filesystem-scan time (ms epoch) for each discovery poller. */
+    discoveryNextFilesystemScanAt = new Map();
+    /** #835: Discovery timeout timers — cleared in cleanupSession to prevent orphan callbacks. */
+    discoveryTimeouts = new Map();
+    saveQueue = Promise.resolve(); // #218: serialize concurrent saves
+    saveDebounceTimer = null;
+    static SAVE_DEBOUNCE_MS = 5_000; // #357: debounce offset-only saves
+    permissionRequests = new PermissionRequestManager();
+    questions = new QuestionManager();
+    // #357: Cache of all parsed JSONL entries per session to avoid re-reading from offset 0
+    // #424: Evict oldest entries when cache exceeds max to prevent unbounded growth
+    static MAX_CACHE_ENTRIES_PER_SESSION = 10_000;
+    parsedEntriesCache = new Map();
+    // Issue #657: Cached session list to avoid allocating a new array per call
+    sessionsListCache = null;
+    // Issue #840/#880: Explicit mutex to prevent TOCTOU races in session acquisition.
+    sessionAcquireMutex = new Mutex();
+    constructor(tmux, config) {
+        this.tmux = tmux;
+        this.config = config;
+        this.stateFile = join(config.stateDir, 'state.json');
+        this.sessionMapFile = join(config.stateDir, 'session_map.json');
+    }
+    /**
+     * 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.
+     */
+    findSessionFileMaybeWorktree(sessionId) {
+        if (this.config.worktreeAwareContinuation && this.config.worktreeSiblingDirs.length > 0) {
+            return findSessionFileWithFanout(sessionId, this.config.claudeProjectsDir, this.config.worktreeSiblingDirs);
+        }
+        return findSessionFile(sessionId, this.config.claudeProjectsDir);
+    }
+    /** Validate that parsed data looks like a valid SessionState. */
+    isValidState(data) {
+        if (typeof data !== 'object' || data === null)
+            return false;
+        const obj = data;
+        if (typeof obj.sessions !== 'object' || obj.sessions === null)
+            return false;
+        const sessions = obj.sessions;
+        for (const val of Object.values(sessions)) {
+            if (typeof val !== 'object' || val === null)
+                return false;
+            const s = val;
+            if (typeof s.id !== 'string' || typeof s.windowId !== 'string')
+                return false;
+        }
+        return true;
+    }
+    /** Clean up stale .tmp files left by crashed writes. */
+    cleanTmpFiles(dir) {
+        try {
+            for (const entry of readdirSync(dir)) {
+                if (entry.endsWith('.tmp')) {
+                    const fullPath = join(dir, entry);
+                    try {
+                        unlinkSync(fullPath);
+                    }
+                    catch { /* best effort */ }
+                    console.log(`Cleaned stale tmp file: ${entry}`);
+                }
+            }
+        }
+        catch { /* dir may not exist yet */ }
+    }
+    /** Load state from disk. */
+    async load() {
+        const dir = dirname(this.stateFile);
+        if (!existsSync(dir)) {
+            await mkdir(dir, { recursive: true });
+        }
+        // Clean stale .tmp files from crashed writes
+        this.cleanTmpFiles(dir);
+        if (existsSync(this.stateFile)) {
+            try {
+                const raw = await readFile(this.stateFile, 'utf-8');
+                const parsed = persistedStateSchema.safeParse(JSON.parse(raw));
+                if (parsed.success && this.isValidState({ sessions: parsed.data })) {
+                    this.state = { sessions: hydrateSessions(parsed.data) };
+                }
+                else {
+                    console.warn('State file failed validation, attempting backup restore');
+                    // Try loading from backup before resetting
+                    const backupFile = `${this.stateFile}.bak`;
+                    if (existsSync(backupFile)) {
+                        try {
+                            const backupRaw = await readFile(backupFile, 'utf-8');
+                            const backupParsed = persistedStateSchema.safeParse(JSON.parse(backupRaw));
+                            if (backupParsed.success && this.isValidState({ sessions: backupParsed.data })) {
+                                this.state = { sessions: hydrateSessions(backupParsed.data) };
+                                console.log('Restored state from backup');
+                            }
+                            else {
+                                this.state = { sessions: {} };
+                            }
+                        }
+                        catch { /* backup state file corrupted — start empty */
+                            this.state = { sessions: {} };
+                        }
+                    }
+                    else {
+                        this.state = { sessions: {} };
+                    }
+                }
+            }
+            catch { /* state file corrupted — start empty */
+                this.state = { sessions: {} };
+            }
+        }
+        // Create backup of successfully loaded state
+        try {
+            await writeFile(`${this.stateFile}.bak`, JSON.stringify(this.state, null, 2));
+        }
+        catch { /* non-critical */ }
+        // Issue #657: Invalidate sessions list cache after loading state
+        this.invalidateSessionsListCache();
+        // 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.
+     *  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 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 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) {
+                    await cleanOrphanedBackup(session.workDir);
+                }
+                delete this.state.sessions[id];
+                this.invalidateSessionsListCache();
+                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.startDiscoveryPolling(id, session.workDir);
+                }
+                changed = true;
+            }
+            else {
+                // Session is alive — restart discovery if needed
+                if (!session.claudeSessionId || !session.jsonlPath) {
+                    console.log(`Reconcile: session ${session.windowName} — restarting JSONL discovery`);
+                    this.startDiscoveryPolling(id, session.workDir);
+                }
+                else {
+                    console.log(`Reconcile: session ${session.windowName} — alive, JSONL ready`);
+                }
+            }
+        }
+        // P0 fix: On startup, purge session_map entries that don't correspond to active sessions.
+        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));
+        for (const win of windows) {
+            if (knownWindowIds.has(win.windowId) || knownWindowNames.has(win.windowName))
+                continue;
+            // Only adopt windows that look like Aegis-created sessions (cc-* prefix or _bridge_ prefix)
+            if (!win.windowName.startsWith('cc-') && !win.windowName.startsWith('_bridge_'))
+                continue;
+            const id = crypto.randomUUID();
+            const session = {
+                id,
+                windowId: win.windowId,
+                windowName: win.windowName,
+                workDir: win.cwd || homedir(),
+                byteOffset: 0,
+                monitorOffset: 0,
+                status: 'unknown',
+                createdAt: Date.now(),
+                lastActivity: Date.now(),
+                stallThresholdMs: SessionManager.DEFAULT_STALL_THRESHOLD_MS,
+                permissionStallMs: SessionManager.DEFAULT_PERMISSION_STALL_MS,
+                permissionMode: 'default',
+            };
+            this.state.sessions[id] = session;
+            this.invalidateSessionsListCache();
+            console.log(`Reconcile: adopted orphaned window ${win.windowName} (${win.windowId}) as ${id.slice(0, 8)}`);
+            this.startDiscoveryPolling(id, session.workDir);
+            changed = true;
+        }
+        if (changed) {
+            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.startDiscoveryPolling(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() {
+        this.saveQueue = this.saveQueue.then(() => this.doSave()).catch(e => console.error('State save error:', e));
+        await this.saveQueue;
+    }
+    /** #357: Debounced save — skips immediate save for offset-only changes.
+     *  Coalesces rapid successive reads into a single disk write. */
+    debouncedSave() {
+        if (this.saveDebounceTimer !== null)
+            clearTimeout(this.saveDebounceTimer);
+        this.saveDebounceTimer = setTimeout(() => {
+            this.saveDebounceTimer = null;
+            void this.save();
+        }, SessionManager.SAVE_DEBOUNCE_MS);
+    }
+    async doSave() {
+        const dir = dirname(this.stateFile);
+        if (!existsSync(dir)) {
+            await mkdir(dir, { recursive: true });
+        }
+        const tmpFile = `${this.stateFile}.tmp`;
+        // #357: Use replacer to serialize Set<string> as arrays
+        await writeFile(tmpFile, JSON.stringify(this.state, (_, value) => {
+            if (value instanceof Set)
+                return [...value];
+            return value;
+        }, 2));
+        await rename(tmpFile, this.stateFile);
+    }
+    /** Default stall threshold: 2 min (Issue #392: 1.5x CC's 90s default, configurable via CLAUDE_STREAM_IDLE_TIMEOUT_MS). */
+    static DEFAULT_STALL_THRESHOLD_MS = computeStallThreshold();
+    static DEFAULT_PERMISSION_STALL_MS = 5 * 60 * 1000;
+    /** Create a new CC session. */
+    /** Default timeout for waiting CC to become ready (60s for cold starts). */
+    static DEFAULT_PROMPT_TIMEOUT_MS = 60_000;
+    /** Max retries if CC doesn't become ready in time. */
+    static 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.
+     */
+    async sendInitialPrompt(sessionId, prompt, timeoutMs, maxRetries) {
+        const session = this.getSession(sessionId);
+        if (!session)
+            return { delivered: false, attempts: 0 };
+        const effectiveTimeout = timeoutMs ?? SessionManager.DEFAULT_PROMPT_TIMEOUT_MS;
+        const effectiveMaxRetries = maxRetries ?? SessionManager.DEFAULT_PROMPT_MAX_RETRIES;
+        for (let attempt = 1; attempt <= effectiveMaxRetries + 1; attempt++) {
+            const attemptTimeout = attempt === 1
+                ? effectiveTimeout
+                : Math.min(effectiveTimeout * Math.pow(1.5, attempt - 1), 120_000); // cap at 2min per retry
+            const result = await this.waitForReadyAndSend(sessionId, prompt, attemptTimeout);
+            if (result.delivered) {
+                if (attempt > 1) {
+                    console.log(`sendInitialPrompt: delivered on attempt ${attempt}/${effectiveMaxRetries + 1}`);
+                }
+                return result;
+            }
+            // If this was the last attempt, return failure
+            if (attempt > effectiveMaxRetries) {
+                console.error(`sendInitialPrompt: FAILED after ${attempt} attempts for session ${sessionId.slice(0, 8)}`);
+                return result;
+            }
+            // Log retry
+            console.warn(`sendInitialPrompt: CC not ready after ${attemptTimeout}ms, retry ${attempt}/${effectiveMaxRetries}`);
+        }
+        return { delivered: false, attempts: effectiveMaxRetries + 1 };
+    }
+    /** Wait for CC idle prompt, then send. Single attempt. */
+    async waitForReadyAndSend(sessionId, prompt, timeoutMs) {
+        const session = this.getSession(sessionId);
+        if (!session)
+            return { delivered: false, attempts: 0 };
+        // #363: Exponential backoff from 500ms → 2000ms to reduce tmux CLI calls.
+        // Instead of ~120 fixed-interval polls, we get ~8-10 polls per session.
+        const MIN_POLL_MS = 500;
+        const MAX_POLL_MS = 2_000;
+        let pollInterval = MIN_POLL_MS;
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            // Use capturePaneDirect to bypass the serialize queue.
+            // At session creation, no other code is writing to this pane,
+            // so queue serialization is unnecessary and adds latency.
+            const paneText = await this.tmux.capturePaneDirect(session.windowId);
+            // Issue #561: Use detectUIState for robust readiness detection.
+            // Requires both ❯ prompt AND chrome separators (─────) to confirm idle.
+            // Naive includes('❯') matched splash/startup output, causing premature sends.
+            if (paneText && detectUIState(paneText) === 'idle') {
+                const result = await this.sendMessageDirect(sessionId, prompt);
+                if (!result.delivered)
+                    return result;
+                // Issue #561: Post-send verification. Wait for CC to transition to a
+                // recognized active state. If CC stays in idle/unknown, the prompt was
+                // swallowed — report as undelivered so the retry loop can re-attempt.
+                const verified = await this.verifyPromptAccepted(session.windowId);
+                return verified
+                    ? result
+                    : { delivered: false, attempts: result.attempts };
+            }
+            await new Promise(r => setTimeout(r, pollInterval));
+            pollInterval = Math.min(pollInterval * 2, MAX_POLL_MS);
+        }
+        return { delivered: false, attempts: 0 };
+    }
+    /**
+     * 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.
+     */
+    async verifyPromptAccepted(windowId) {
+        const VERIFY_TIMEOUT_MS = 5_000;
+        const VERIFY_POLL_MS = 500;
+        const verifyStart = Date.now();
+        while (Date.now() - verifyStart < VERIFY_TIMEOUT_MS) {
+            const paneText = await this.tmux.capturePaneDirect(windowId);
+            const state = detectUIState(paneText);
+            // Active states mean CC received and is processing the prompt.
+            // waiting_for_input = CC accepted prompt, awaiting follow-up (no chrome yet).
+            if (state === 'working' || state === 'permission_prompt' ||
+                state === 'bash_approval' || state === 'plan_mode' ||
+                state === 'ask_question' || state === 'compacting' ||
+                state === 'context_warning' || state === 'waiting_for_input') {
+                return true;
+            }
+            // idle or unknown — keep polling
+            await new Promise(r => setTimeout(r, VERIFY_POLL_MS));
+        }
+        console.warn(`verifyPromptAccepted: CC did not transition from idle/unknown within ${VERIFY_TIMEOUT_MS}ms`);
+        return false;
+    }
+    async createSession(opts) {
+        const id = crypto.randomUUID();
+        const windowName = opts.name || `cc-${id.slice(0, 8)}`;
+        // Merge defaultSessionEnv (from config) with per-session env (per-session wins)
+        // Security: validate env var names to prevent injection attacks
+        const ENV_NAME_RE = /^[A-Z_][A-Z0-9_]*$/;
+        // Issue #630: Expanded blocklist with additional dangerous env vars
+        const DANGEROUS_ENV_VARS = new Set([
+            // Dynamic loader / library injection
+            'PATH', 'LD_PRELOAD', 'LD_LIBRARY_PATH', 'NODE_OPTIONS',
+            'DYLD_INSERT_LIBRARIES', 'IFS', 'SHELL', 'ENV', 'BASH_ENV',
+            // Language-specific library paths
+            'PYTHONPATH', 'PERL5LIB', 'RUBYLIB', 'CLASSPATH',
+            'NODE_PATH', 'PYTHONHOME', 'PYTHONSTARTUP',
+            // Issue #630: Shell command injection vectors
+            'PROMPT_COMMAND', 'GIT_SSH_COMMAND', 'EDITOR', 'VISUAL',
+            'SUDO_ASKPASS', 'GIT_EXEC_PATH', 'NODE_ENV',
+            // Issue #630: Token/credential leakage
+            'GITHUB_TOKEN', 'NPM_TOKEN', 'GITLAB_TOKEN',
+            'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SESSION_TOKEN',
+            'AZURE_CLIENT_SECRET', 'GOOGLE_APPLICATION_CREDENTIALS',
+            'DOCKER_TOKEN', 'HEROKU_API_KEY',
+        ]);
+        // Issue #630: Dangerous env var prefixes (prefix match)
+        const DANGEROUS_ENV_PREFIXES = [
+            'npm_config_', // npm configuration override
+            'BASH_FUNC_', // bash function export
+            'SSH_', // SSH keys/agent config (SSH_AUTH_SOCK, SSH_PRIVATE_KEY, etc.)
+            'GITHUB_', // GitHub tokens/keys (except GITHUB_PATH which is benign)
+            'GITLAB_', // GitLab tokens
+            'AWS_', // AWS credentials
+            'AZURE_', // Azure credentials
+            'TF_', // Terraform tokens
+            'CI_', // CI tokens (CI_JOB_TOKEN, CI_BUILD_TOKEN, etc.)
+            'DOCKER_', // Docker registry tokens
+        ];
+        const mergedEnv = {};
+        const allEnv = { ...this.config.defaultSessionEnv, ...opts.env };
+        for (const [key, value] of Object.entries(allEnv)) {
+            if (!ENV_NAME_RE.test(key)) {
+                throw new Error(`Invalid env var name: "${key}" — must match /^[A-Z_][A-Z0-9_]*$/`);
+            }
+            if (DANGEROUS_ENV_VARS.has(key)) {
+                throw new Error(`Forbidden env var: "${key}" — cannot override dangerous environment variables`);
+            }
+            // Issue #630: Check dangerous prefixes
+            if (DANGEROUS_ENV_PREFIXES.some(prefix => key.startsWith(prefix))) {
+                throw new Error(`Forbidden env var: "${key}" — cannot override dangerous environment variable prefix "${DANGEROUS_ENV_PREFIXES.find(p => key.startsWith(p))}"`);
+            }
+            mergedEnv[key] = value;
+        }
+        const hasEnv = Object.keys(mergedEnv).length > 0;
+        // Permission guard: if permissionMode is "default", neutralize any project-level
+        // settings.local.json that has bypassPermissions. The CLI flag --permission-mode
+        // should be authoritative, but CC lets project settings override it.
+        // We back up the file, patch it, and restore on session cleanup.
+        const effectivePermissionMode = opts.permissionMode
+            ?? (opts.autoApprove === true ? 'bypassPermissions' : opts.autoApprove === false ? 'default' : undefined)
+            ?? this.config.defaultPermissionMode
+            ?? 'default';
+        let settingsPatched = false;
+        if (effectivePermissionMode !== 'bypassPermissions') {
+            settingsPatched = await neutralizeBypassPermissions(opts.workDir, effectivePermissionMode);
+        }
+        // Issue #629: Generate per-session HMAC secret for hook URL authentication.
+        const hookSecret = randomBytes(32).toString('hex');
+        // Issue #169 Phase 2: Generate HTTP hook settings for this session.
+        // Writes a temp file with hooks pointing to Aegis's hook receiver.
+        // Issue #936: Clean stale session hooks from settings.local.json before writing new hooks.
+        // This prevents CC from loading dead hook URLs on restart.
+        try {
+            const activeIds = new Set(this.listSessions().map(s => s.id));
+            if (activeIds.size > 0) {
+                await cleanupStaleSessionHooks(opts.workDir, activeIds);
+            }
+        }
+        catch (e) {
+            console.warn(`Hook cleanup: failed to clean stale hooks: ${e.message}`);
+        }
+        let hookSettingsFile;
+        try {
+            const baseUrl = `http://${this.config.host}:${this.config.port}`;
+            hookSettingsFile = await writeHookSettingsFile(baseUrl, id, hookSecret, opts.workDir);
+        }
+        catch (e) {
+            console.error(`Hook settings: failed to generate settings file: ${e.message}`);
+            // Non-fatal: hooks won't work for this session, but CC still launches
+        }
+        const { windowId, windowName: finalName, freshSessionId } = await this.tmux.createWindow({
+            workDir: opts.workDir,
+            windowName,
+            resumeSessionId: opts.resumeSessionId,
+            claudeCommand: opts.claudeCommand,
+            env: hasEnv ? mergedEnv : undefined,
+            permissionMode: effectivePermissionMode,
+            settingsFile: hookSettingsFile,
+        });
+        const session = {
+            id,
+            windowId,
+            windowName: finalName,
+            workDir: opts.workDir,
+            // If we know the CC session ID upfront (from --session-id), set it immediately.
+            // This eliminates the discovery delay and prevents stale ID assignment entirely.
+            claudeSessionId: freshSessionId || undefined,
+            byteOffset: 0,
+            monitorOffset: 0,
+            status: 'unknown',
+            createdAt: Date.now(),
+            lastActivity: Date.now(),
+            stallThresholdMs: opts.stallThresholdMs || SessionManager.DEFAULT_STALL_THRESHOLD_MS,
+            permissionStallMs: opts.permissionStallMs || SessionManager.DEFAULT_PERMISSION_STALL_MS,
+            permissionMode: effectivePermissionMode,
+            settingsPatched,
+            hookSettingsFile,
+            hookSecret,
+            prd: opts.prd,
+        };
+        this.state.sessions[id] = session;
+        this.invalidateSessionsListCache();
+        await this.save();
+        // Issue #702: Register child with parent
+        if (opts.parentId) {
+            const parent = this.state.sessions[opts.parentId];
+            if (parent) {
+                if (!parent.children)
+                    parent.children = [];
+                parent.children.push(id);
+                await this.save();
+            }
+        }
+        // Issue #353: Fetch CC process PID for swarm parent matching.
+        // Fire-and-forget — PID is not needed synchronously.
+        // Issue #574: Add .catch() to prevent unhandled rejection if tmux fails mid-lookup.
+        void this.tmux.listPanePid(windowId).then(pid => {
+            if (pid !== null) {
+                session.ccPid = pid;
+                void this.save().catch(e => console.error(`Session: failed to save PID for ${id}:`, e));
+            }
+        }).catch(e => console.error(`Session: failed to list pane PID for ${id}:`, e));
+        // Start coordinated discovery polling:
+        // - Hook/session_map sync: fast path
+        // - Filesystem scan fallback: works when hooks fail or are skipped (Issue #16)
+        // Field bug (Zeus 2026-03-22): hooks may not fire even without --bare
+        this.startDiscoveryPolling(id, opts.workDir);
+        // P0 fix: Clean stale entries from session_map.json for BOTH window name AND id.
+        // After archiving old .jsonl files, stale session_map entries would point
+        // to moved files, causing discovery to pick up ghost session IDs.
+        // Also cleans stale windowId entries that could collide after restart.
+        await this.cleanSessionMapForWindow(finalName, windowId);
+        return session;
+    }
+    /** Get a session by ID. */
+    getSession(id) {
+        return this.state.sessions[id] || 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, hookEvent, hookTimestamp) {
+        const session = this.state.sessions[id];
+        if (!session)
+            return null;
+        const prevStatus = session.status;
+        const now = Date.now();
+        // Map hook events to UI states
+        switch (hookEvent) {
+            case 'Stop':
+            case 'TaskCompleted':
+            case 'SessionEnd':
+            case 'TeammateIdle':
+                break;
+            case 'PreToolUse':
+            case 'PostToolUse':
+            case 'SubagentStart':
+            case 'UserPromptSubmit':
+                session.status = 'working';
+                break;
+            case 'PermissionRequest':
+                session.status = 'permission_prompt';
+                break;
+            case 'StopFailure':
+            case 'PostToolUseFailure':
+                session.status = 'error';
+                break;
+            case 'Notification':
+            case 'PreCompact':
+            case 'PostCompact':
+            case 'SubagentStop':
+                // Informational events — no status change
+                break;
+            default:
+                // Unknown hook events: no status change
+                break;
+        }
+        session.lastHookAt = now;
+        session.lastActivity = now;
+        // Issue #87: Record hook receive timestamp for latency calculation
+        session.lastHookReceivedAt = now;
+        if (hookTimestamp) {
+            // Issue #828: Clamp future timestamps to prevent clock skew corruption.
+            // If the client's clock is ahead of ours, store our timestamp instead.
+            if (hookTimestamp > now) {
+                console.warn(`updateStatusFromHook: clamping future hookTimestamp ` +
+                    `(${hookTimestamp} > ${now}) for session ${id.slice(0, 8)}`);
+                session.lastHookEventAt = now;
+            }
+            else {
+                session.lastHookEventAt = hookTimestamp;
+            }
+        }
+        // Issue #87: Track permission prompt timestamp
+        if (hookEvent === 'PermissionRequest') {
+            session.permissionPromptAt = now;
+        }
+        return prevStatus;
+    }
+    /** 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). */
+    async detectWaitingForInput(id) {
+        const session = this.state.sessions[id];
+        if (!session?.jsonlPath)
+            return false;
+        try {
+            const { raw } = await readNewEntries(session.jsonlPath, 0);
+            // Walk backwards to find the last assistant JSONL entry
+            for (let i = raw.length - 1; i >= 0; i--) {
+                const entry = raw[i];
+                if (entry.type !== 'assistant' || !entry.message)
+                    continue;
+                const content = entry.message.content;
+                if (typeof content === 'string')
+                    return true; // text-only message
+                if (!Array.isArray(content))
+                    return false;
+                // Check if any content block is a tool_use
+                const hasToolUse = content.some((block) => block.type === 'tool_use');
+                return !hasToolUse;
+            }
+        }
+        catch {
+            // If we can't read the transcript, don't override status
+        }
+        return false;
+    }
+    /** Issue #88: Add an active subagent to a session. */
+    addSubagent(id, name) {
+        const session = this.state.sessions[id];
+        if (!session)
+            return;
+        if (!session.activeSubagents)
+            session.activeSubagents = new Set();
+        session.activeSubagents.add(name);
+    }
+    /** Issue #88: Remove an active subagent from a session. */
+    removeSubagent(id, name) {
+        const session = this.state.sessions[id];
+        if (!session || !session.activeSubagents)
+            return;
+        session.activeSubagents.delete(name);
+    }
+    /** Issue #89 L25: Update the model field on a session from hook payload. */
+    updateSessionModel(id, model) {
+        const session = this.state.sessions[id];
+        if (!session)
+            return;
+        session.model = model;
+    }
+    /** Issue #87: Get latency metrics for a session. */
+    getLatencyMetrics(id) {
+        const session = this.state.sessions[id];
+        if (!session)
+            return null;
+        // hook_latency_ms: time from CC sending hook to Aegis receiving it
+        // Calculated from the difference between our receive time and the hook's timestamp
+        let hookLatency = null;
+        if (session.lastHookReceivedAt && session.lastHookEventAt) {
+            hookLatency = session.lastHookReceivedAt - session.lastHookEventAt;
+            // Guard against negative values (clock skew)
+            if (hookLatency < 0)
+                hookLatency = null;
+        }
+        // state_change_detection_ms: time from CC state change to Aegis detection
+        // Approximated as hook_latency_ms since the hook IS the state change signal
+        let stateChangeDetection = hookLatency;
+        // permission_response_ms: time from permission prompt to user action
+        let permissionResponse = null;
+        if (session.permissionPromptAt && session.permissionRespondedAt) {
+            permissionResponse = session.permissionRespondedAt - session.permissionPromptAt;
+        }
+        return {
+            hook_latency_ms: hookLatency,
+            state_change_detection_ms: stateChangeDetection,
+            permission_response_ms: permissionResponse,
+        };
+    }
+    /** 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. */
+    async isWindowAlive(id) {
+        const session = this.state.sessions[id];
+        if (!session)
+            return false;
+        try {
+            // Issue #390: Fast crash detection via stored CC PID
+            const windowHealth = await this.tmux.getWindowHealth(session.windowId);
+            if (!windowHealth.windowExists)
+                return false;
+            // Issue #1040: When CC exits (normal or crash), it becomes a zombie.
+            // isPidAlive returns false for zombies — we cannot distinguish normal exit from crash.
+            // paneDead + grace period handles both: keep alive briefly, then mark dead.
+            if (windowHealth.paneDead) {
+                const msSinceActivity = Date.now() - (session.lastActivity || session.createdAt);
+                const GRACE_PERIOD_MS = 15000; // 15 seconds — enough for CC to finish and write results
+                return msSinceActivity < GRACE_PERIOD_MS;
+            }
+            // Pane not dead — verify pane process is alive (for non-CC processes like shells)
+            const panePid = await this.tmux.listPanePid(session.windowId);
+            if (panePid !== null && !this.tmux.isPidAlive(panePid))
+                return false;
+            return true;
+        }
+        catch { /* tmux query failed — treat as not alive */
+            return false;
+        }
+    }
+    /** Issue #657: Invalidate the sessions list cache. Call on any mutation. */
+    invalidateSessionsListCache() {
+        this.sessionsListCache = null;
+    }
+    /** List all sessions. */
+    listSessions() {
+        if (!this.sessionsListCache) {
+            this.sessionsListCache = Object.values(this.state.sessions);
+        }
+        return this.sessionsListCache;
+    }
+    /** 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. */
+    async findIdleSessionByWorkDir(workDir) {
+        return this.sessionAcquireMutex.runExclusive(async () => {
+            await maybeInjectFault('session.findIdleSessionByWorkDir.start');
+            const candidates = Object.values(this.state.sessions).filter((s) => s.workDir === workDir && s.status === 'idle');
+            if (candidates.length === 0)
+                return null;
+            // Return the most recently active session
+            candidates.sort((a, b) => b.lastActivity - a.lastActivity);
+            // Issue #636: verify tmux window exists before returning
+            for (const candidate of candidates) {
+                await maybeInjectFault('session.findIdleSessionByWorkDir.windowExists');
+                if (await this.tmux.windowExists(candidate.windowId)) {
+                    // Issue #840: Mark session as acquired immediately to prevent
+                    // concurrent callers from grabbing the same session
+                    candidate.status = 'acquired';
+                    return candidate;
+                }
+            }
+            return null;
+        });
+    }
+    /** Release a session claim after the reuse path completes (success or failure). */
+    releaseSessionClaim(id) {
+        const session = this.state.sessions[id];
+        if (session) {
+            session.status = 'idle';
+        }
+    }
+    /** Get health info for a session.
+     *  Issue #2: Returns comprehensive health status for orchestrators.
+     */
+    async getHealth(id) {
+        const session = this.state.sessions[id];
+        if (!session)
+            throw new Error(`Session ${id} not found`);
+        const now = Date.now();
+        const windowHealth = await this.tmux.getWindowHealth(session.windowId);
+        // Get terminal state
+        let status = 'unknown';
+        // Issue #69: Also check if the pane PID is alive (zombie window detection)
+        let processAlive = true;
+        const paneExited = !!windowHealth.paneDead;
+        if (windowHealth.windowExists) {
+            if (paneExited) {
+                processAlive = false;
+            }
+            else {
+                try {
+                    const panePid = await this.tmux.listPanePid(session.windowId);
+                    if (panePid !== null) {
+                        processAlive = this.tmux.isPidAlive(panePid);
+                    }
+                }
+                catch { /* cannot list pane PID — assume dead */
+                    processAlive = false;
+                }
+            }
+        }
+        if (windowHealth.windowExists && processAlive) {
+            try {
+                const paneText = await this.tmux.capturePane(session.windowId);
+                status = detectUIState(paneText);
+                session.status = status;
+            }
+            catch { /* pane capture failed — default to unknown */
+                status = 'unknown';
+            }
+        }
+        const hasTranscript = !!(session.claudeSessionId && session.jsonlPath);
+        const lastActivityAgo = now - session.lastActivity;
+        const sessionAge = now - session.createdAt;
+        // Determine if session is alive
+        // Alive = window exists AND process alive AND (Claude running OR recently active)
+        const recentlyActive = lastActivityAgo < 5 * 60 * 1000; // 5 minutes
+        const alive = windowHealth.windowExists && processAlive && (windowHealth.claudeRunning || recentlyActive);
+        // Human-readable detail
+        let details;
+        if (!windowHealth.windowExists) {
+            details = 'Tmux window does not exist — session is dead';
+        }
+        else if (paneExited) {
+            details = 'Tmux pane has exited — session is dead';
+        }
+        else if (!processAlive) {
+            details = 'Tmux window exists but pane process is dead — session is dead (zombie window)';
+        }
+        else if (!windowHealth.claudeRunning && !recentlyActive) {
+            details = `Claude not running (pane: ${windowHealth.paneCommand}), no activity for ${Math.round(lastActivityAgo / 60000)}min`;
+        }
+        else if (status === 'idle') {
+            details = 'Claude is idle, awaiting input';
+        }
+        else if (status === 'working') {
+            details = 'Claude is actively working';
+        }
+        else if (status === 'permission_prompt' || status === 'bash_approval') {
+            details = `Claude is waiting for permission approval. POST /v1/sessions/${session.id}/approve to approve, or /v1/sessions/${session.id}/reject to reject.`;
+        }
+        else {
+            details = `Status: ${status}, pane: ${windowHealth.paneCommand}`;
+        }
+        // Issue #20: Action hints for interactive states
+        const actionHints = (status === 'permission_prompt' || status === 'bash_approval')
+            ? {
+                approve: { method: 'POST', url: `/v1/sessions/${session.id}/approve`, description: 'Approve the pending permission' },
+                reject: { method: 'POST', url: `/v1/sessions/${session.id}/reject`, description: 'Reject the pending permission' },
+            }
+            : undefined;
+        return {
+            alive,
+            windowExists: windowHealth.windowExists,
+            claudeRunning: windowHealth.claudeRunning,
+            paneCommand: windowHealth.paneCommand,
+            status,
+            hasTranscript,
+            lastActivity: session.lastActivity,
+            lastActivityAgo,
+            sessionAge,
+            details,
+            actionHints,
+        };
+    }
+    /** 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.
+     */
+    async sendMessage(id, text) {
+        const session = this.state.sessions[id];
+        if (!session)
+            throw new Error(`Session ${id} not found`);
+        const result = await this.tmux.sendKeysVerified(session.windowId, text);
+        if (result.delivered) {
+            session.lastActivity = Date.now();
+            try {
+                await this.save();
+            }
+            catch {
+                // Message was delivered — don't let a save failure mask the success
+            }
+        }
+        return result;
+    }
+    /** 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.
+     */
+    async sendMessageDirect(id, text) {
+        const session = this.state.sessions[id];
+        if (!session)
+            throw new Error(`Session ${id} not found`);
+        // Issue #285: Use verified sending with retry for reliability
+        const result = await this.tmux.sendKeysVerified(session.windowId, text, 3);
+        if (result.delivered) {
+            session.lastActivity = Date.now();
+            try {
+                await this.save();
+            }
+            catch {
+                // Message was delivered — don't let a save failure mask the success
+            }
+        }
+        return result;
+    }
+    /** Record that a permission prompt was detected for this session. */
+    recordPermissionPrompt(id) {
+        const session = this.state.sessions[id];
+        if (!session)
+            return;
+        session.permissionPromptAt = Date.now();
+    }
+    /** Approve a permission prompt. Resolves pending hook permission first, falls back to tmux send-keys. */
+    async approve(id) {
+        const session = this.state.sessions[id];
+        if (!session)
+            throw new Error(`Session ${id} not found`);
+        // Issue #284: Resolve pending hook-based permission first
+        if (this.permissionRequests.resolvePendingPermission(id, 'allow')) {
+            session.lastActivity = Date.now();
+            if (session.permissionPromptAt) {
+                session.permissionRespondedAt = Date.now();
+            }
+            return;
+        }
+        // Fallback: tmux send-keys
+        const paneText = await this.tmux.capturePane(session.windowId);
+        const method = detectApprovalMethod(paneText);
+        await this.tmux.sendKeys(session.windowId, method === 'numbered' ? '1' : 'y', true);
+        session.lastActivity = Date.now();
+        if (session.permissionPromptAt) {
+            session.permissionRespondedAt = Date.now();
+        }
+    }
+    /** Reject a permission prompt. Resolves pending hook permission first, falls back to tmux send-keys. */
+    async reject(id) {
+        const session = this.state.sessions[id];
+        if (!session)
+            throw new Error(`Session ${id} not found`);
+        // Issue #284: Resolve pending hook-based permission first
+        if (this.permissionRequests.resolvePendingPermission(id, 'deny')) {
+            session.lastActivity = Date.now();
+            if (session.permissionPromptAt) {
+                session.permissionRespondedAt = Date.now();
+            }
+            return;
+        }
+        // Fallback: tmux send-keys
+        await this.tmux.sendKeys(session.windowId, 'n', true);
+        session.lastActivity = Date.now();
+        if (session.permissionPromptAt) {
+            session.permissionRespondedAt = Date.now();
+        }
+    }
+    /**
+     * 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, timeoutMs = 10_000, toolName, prompt) {
+        return this.permissionRequests.waitForPermissionDecision(sessionId, timeoutMs, toolName, prompt);
+    }
+    /** Check if a session has a pending permission request. */
+    hasPendingPermission(sessionId) {
+        return this.permissionRequests.hasPendingPermission(sessionId);
+    }
+    /** Get info about a pending permission (for API responses). */
+    getPendingPermissionInfo(sessionId) {
+        return this.permissionRequests.getPendingPermissionInfo(sessionId);
+    }
+    /** Clean up any pending permission for a session (e.g. on session delete). */
+    cleanupPendingPermission(sessionId) {
+        this.permissionRequests.cleanupPendingPermission(sessionId);
+    }
+    /**
+     * Issue #336: Store a pending AskUserQuestion and return a promise that
+     * resolves when the external client provides an answer via POST /answer.
+     */
+    waitForAnswer(sessionId, toolUseId, question, timeoutMs = 30_000) {
+        return this.questions.waitForAnswer(sessionId, toolUseId, question, timeoutMs);
+    }
+    /** Issue #336: Submit an answer to a pending question. Returns true if resolved. */
+    submitAnswer(sessionId, questionId, answer) {
+        return this.questions.submitAnswer(sessionId, questionId, answer);
+    }
+    /** Issue #336: Check if a session has a pending question. */
+    hasPendingQuestion(sessionId) {
+        return this.questions.hasPendingQuestion(sessionId);
+    }
+    /** Issue #336: Get info about a pending question. */
+    getPendingQuestionInfo(sessionId) {
+        return this.questions.getPendingQuestionInfo(sessionId);
+    }
+    /** Issue #336: Clean up any pending question for a session. */
+    cleanupPendingQuestion(sessionId) {
+        this.questions.cleanupPendingQuestion(sessionId);
+    }
+    /** Send Escape key. */
+    async escape(id) {
+        const session = this.state.sessions[id];
+        if (!session)
+            throw new Error(`Session ${id} not found`);
+        await this.tmux.sendSpecialKey(session.windowId, 'Escape');
+    }
+    /** Send Ctrl+C. */
+    async interrupt(id) {
+        const session = this.state.sessions[id];
+        if (!session)
+            throw new Error(`Session ${id} not found`);
+        await this.tmux.sendSpecialKey(session.windowId, 'C-c');
+    }
+    /** Read new messages from a session. */
+    async readMessages(id) {
+        const session = this.state.sessions[id];
+        if (!session)
+            throw new Error(`Session ${id} not found`);
+        // Detect UI state from terminal
+        const paneText = await this.tmux.capturePane(session.windowId);
+        const status = detectUIState(paneText);
+        const statusText = parseStatusLine(paneText);
+        const interactive = extractInteractiveContent(paneText);
+        session.status = status;
+        session.lastActivity = Date.now();
+        // Try to find JSONL if we don't have it yet (Issue #884: worktree-aware)
+        if (!session.jsonlPath && session.claudeSessionId) {
+            const path = await this.findSessionFileMaybeWorktree(session.claudeSessionId);
+            if (path) {
+                session.jsonlPath = path;
+                session.byteOffset = 0;
+            }
+        }
+        // Read JSONL if we have the file path
+        let messages = [];
+        if (session.jsonlPath && existsSync(session.jsonlPath)) {
+            try {
+                const result = await readNewEntries(session.jsonlPath, session.byteOffset);
+                messages = result.entries;
+                session.byteOffset = result.newOffset;
+            }
+            catch {
+                // File may not exist yet
+            }
+        }
+        // #357: Debounce saves on GET reads — offsets change frequently but disk
+        // writes are expensive. Full save still happens on create/kill/reconcile.
+        this.debouncedSave();
+        return {
+            messages,
+            status,
+            statusText,
+            interactiveContent: interactive?.content || null,
+        };
+    }
+    /** Read new messages for the monitor (separate offset from API reads). */
+    async readMessagesForMonitor(id) {
+        const session = this.state.sessions[id];
+        if (!session)
+            throw new Error(`Session ${id} not found`);
+        // Detect UI state from terminal
+        const paneText = await this.tmux.capturePane(session.windowId);
+        const status = detectUIState(paneText);
+        const statusText = parseStatusLine(paneText);
+        const interactive = extractInteractiveContent(paneText);
+        session.status = status;
+        // Try to find JSONL if we don't have it yet (Issue #884: worktree-aware)
+        if (!session.jsonlPath && session.claudeSessionId) {
+            const path = await this.findSessionFileMaybeWorktree(session.claudeSessionId);
+            if (path) {
+                session.jsonlPath = path;
+                session.monitorOffset = 0;
+            }
+        }
+        // Read JSONL using monitor offset
+        let messages = [];
+        if (session.jsonlPath && existsSync(session.jsonlPath)) {
+            try {
+                const result = await readNewEntries(session.jsonlPath, session.monitorOffset);
+                messages = result.entries;
+                session.monitorOffset = result.newOffset;
+            }
+            catch {
+                // File may not exist yet
+            }
+        }
+        return {
+            messages,
+            status,
+            statusText,
+            interactiveContent: interactive?.content || 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. */
+    async getCachedEntries(session) {
+        if (!session.jsonlPath || !existsSync(session.jsonlPath))
+            return [];
+        const cached = this.parsedEntriesCache.get(session.id);
+        try {
+            const fromOffset = cached ? cached.offset : 0;
+            const result = await readNewEntries(session.jsonlPath, fromOffset);
+            if (cached) {
+                // #832: Detect JSONL truncation — newOffset resets to 0 when file is rewritten.
+                // readNewEntries returns empty entries + newOffset:0 on truncation.
+                // Discard stale cached entries and rebuild from scratch.
+                if (fromOffset > 0 && result.newOffset === 0 && result.entries.length === 0) {
+                    const freshResult = await readNewEntries(session.jsonlPath, 0);
+                    this.parsedEntriesCache.set(session.id, { entries: [...freshResult.entries], offset: freshResult.newOffset });
+                    return freshResult.entries;
+                }
+                cached.entries.push(...result.entries);
+                cached.offset = result.newOffset;
+                // #424: Evict oldest entries when cache exceeds per-session cap
+                if (cached.entries.length > SessionManager.MAX_CACHE_ENTRIES_PER_SESSION) {
+                    cached.entries.splice(0, cached.entries.length - SessionManager.MAX_CACHE_ENTRIES_PER_SESSION);
+                }
+                return cached.entries;
+            }
+            // First read — cache it
+            this.parsedEntriesCache.set(session.id, { entries: [...result.entries], offset: result.newOffset });
+            return result.entries;
+        }
+        catch { /* JSONL read failed — return cached entries or empty */
+            return cached ? [...cached.entries] : [];
+        }
+    }
+    /** Issue #35: Get a condensed summary of a session's transcript. */
+    async getSummary(id, maxMessages = 20) {
+        const session = this.state.sessions[id];
+        if (!session)
+            throw new Error(`Session ${id} not found`);
+        // #357: Use cached entries instead of re-reading from offset 0
+        const allMessages = await this.getCachedEntries(session);
+        // Take last N messages
+        const recent = allMessages.slice(-maxMessages).map(m => ({
+            role: m.role,
+            contentType: m.contentType,
+            text: m.text.slice(0, 500), // Truncate long messages
+        }));
+        return {
+            sessionId: session.id,
+            windowName: session.windowName,
+            status: session.status,
+            totalMessages: allMessages.length,
+            messages: recent,
+            createdAt: session.createdAt,
+            lastActivity: session.lastActivity,
+            permissionMode: session.permissionMode,
+            prd: session.prd,
+        };
+    }
+    /** Paginated transcript read — does NOT advance the session's byteOffset. */
+    async readTranscript(id, page = 1, limit = 50, roleFilter) {
+        const session = this.state.sessions[id];
+        if (!session)
+            throw new Error(`Session ${id} not found`);
+        // Discover JSONL path if not yet known (Issue #884: worktree-aware)
+        if (!session.jsonlPath && session.claudeSessionId) {
+            const path = await this.findSessionFileMaybeWorktree(session.claudeSessionId);
+            if (path) {
+                session.jsonlPath = path;
+                session.byteOffset = 0;
+            }
+        }
+        let allEntries = [];
+        // #357: Use cached entries instead of re-reading from offset 0
+        allEntries = await this.getCachedEntries(session);
+        if (roleFilter) {
+            allEntries = allEntries.filter(e => e.role === roleFilter);
+        }
+        const total = allEntries.length;
+        const start = (page - 1) * limit;
+        const messages = allEntries.slice(start, start + limit);
+        const hasMore = start + messages.length < total;
+        return {
+            messages,
+            total,
+            page,
+            limit,
+            hasMore,
+        };
+    }
+    /**
+     * 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.
+     */
+    async readTranscriptCursor(id, beforeId, limit = 50, roleFilter) {
+        const session = this.state.sessions[id];
+        if (!session)
+            throw new Error(`Session ${id} not found`);
+        // Discover JSONL path if not yet known
+        if (!session.jsonlPath && session.claudeSessionId) {
+            const path = await findSessionFile(session.claudeSessionId, this.config.claudeProjectsDir);
+            if (path) {
+                session.jsonlPath = path;
+                session.byteOffset = 0;
+            }
+        }
+        let allEntries = await this.getCachedEntries(session);
+        if (roleFilter) {
+            allEntries = allEntries.filter(e => e.role === roleFilter);
+        }
+        const total = allEntries.length;
+        const clampedLimit = Math.min(200, Math.max(1, limit));
+        // Determine exclusive upper index (0-based)
+        const upperExclusive = beforeId !== undefined
+            ? Math.min(beforeId - 1, total) // beforeId is 1-based
+            : total;
+        const lowerInclusive = Math.max(0, upperExclusive - clampedLimit);
+        const slice = allEntries.slice(lowerInclusive, upperExclusive);
+        const messages = slice.map((entry, i) => ({
+            ...entry,
+            _cursor_id: lowerInclusive + i + 1, // 1-based stable index
+        }));
+        return {
+            messages,
+            has_more: lowerInclusive > 0,
+            oldest_id: messages.length > 0 ? messages[0]._cursor_id : null,
+            newest_id: messages.length > 0 ? messages[messages.length - 1]._cursor_id : null,
+        };
+    }
+    /** #405: Clean up all tracking maps for a session to prevent memory leaks. */
+    cleanupSession(id) {
+        this.stopDiscoveryPolling(id);
+        this.cleanupPendingPermission(id);
+        this.cleanupPendingQuestion(id);
+        this.parsedEntriesCache.delete(id);
+    }
+    /** Kill a session. */
+    async killSession(id) {
+        const session = this.state.sessions[id];
+        if (!session)
+            return;
+        await this.tmux.killWindow(session.windowId);
+        // Permission guard: restore original settings.local.json if we patched it
+        if (session.settingsPatched) {
+            await restoreSettings(session.workDir);
+        }
+        // Issue #169 Phase 2: Clean up temp hook settings file
+        if (session.hookSettingsFile) {
+            await cleanupHookSettingsFile(session.hookSettingsFile);
+        }
+        // #405: Clean up all tracking maps (pollTimers, pendingPermissions, pendingQuestions, parsedEntriesCache)
+        this.cleanupSession(id);
+        delete this.state.sessions[id];
+        this.invalidateSessionsListCache();
+        // #357: Cancel any pending debounced save before doing an immediate save
+        if (this.saveDebounceTimer !== null) {
+            clearTimeout(this.saveDebounceTimer);
+            this.saveDebounceTimer = null;
+        }
+        await this.save();
+    }
+    /** 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.
+     */
+    async cleanSessionMapForWindow(windowName, windowId) {
+        if (!existsSync(this.sessionMapFile))
+            return;
+        try {
+            const mapData = await loadContinuationPointers(this.sessionMapFile, this.config.continuationPointerTtlMs);
+            let changed = false;
+            for (const [key, info] of Object.entries(mapData)) {
+                // Clean by window_name (original behavior)
+                if (info.window_name === windowName) {
+                    delete mapData[key];
+                    changed = true;
+                    continue;
+                }
+                // P0 fix: Also clean entries where key ends with :windowId
+                // This prevents stale windowId collisions after restart
+                if (windowId && key.endsWith(':' + windowId)) {
+                    delete mapData[key];
+                    changed = true;
+                }
+            }
+            if (changed) {
+                const tmpFile = `${this.sessionMapFile}.tmp`;
+                await writeFile(tmpFile, JSON.stringify(mapData, null, 2));
+                await rename(tmpFile, this.sessionMapFile);
+            }
+        }
+        catch { /* ignore parse/write errors */ }
+    }
+    /** 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.
+     */
+    async purgeStaleSessionMapEntries(activeWindowIds, activeWindowNames) {
+        if (!existsSync(this.sessionMapFile))
+            return;
+        try {
+            const mapData = await loadContinuationPointers(this.sessionMapFile, this.config.continuationPointerTtlMs);
+            let changed = false;
+            const activeNamesLower = new Set([...activeWindowNames].map(n => n.toLowerCase()));
+            for (const [key, info] of Object.entries(mapData)) {
+                // Extract windowId from key (format: "sessionName:windowId")
+                const keyWindowId = key.includes(':') ? key.split(':').pop() : null;
+                const windowName = (info.window_name || '').toLowerCase();
+                // Keep entry only if it matches an active window
+                const windowIdActive = keyWindowId && activeWindowIds.has(keyWindowId);
+                const windowNameActive = activeNamesLower.has(windowName);
+                if (!windowIdActive && !windowNameActive) {
+                    console.log(`Reconcile: purging stale session_map entry: ${key}`);
+                    delete mapData[key];
+                    changed = true;
+                }
+            }
+            if (changed) {
+                const tmpFile = `${this.sessionMapFile}.tmp`;
+                await writeFile(tmpFile, JSON.stringify(mapData, null, 2));
+                await rename(tmpFile, this.sessionMapFile);
+            }
+        }
+        catch { /* ignore parse/write errors */ }
+    }
+    /** Stop and remove the coordinated discovery poller/timer for a session. */
+    stopDiscoveryPolling(id) {
+        const timer = this.pollTimers.get(id);
+        if (timer) {
+            clearInterval(timer);
+            this.pollTimers.delete(id);
+        }
+        const timeout = this.discoveryTimeouts.get(id);
+        if (timeout) {
+            clearTimeout(timeout);
+            this.discoveryTimeouts.delete(id);
+        }
+        this.discoveryNextFilesystemScanAt.delete(id);
+    }
+    /** Attempt filesystem-based discovery for a single session poll tick. */
+    async maybeDiscoverFromFilesystem(session, workDir) {
+        const projectHash = computeProjectHash(workDir);
+        const projectDir = join(this.config.claudeProjectsDir, projectHash);
+        if (!existsSync(projectDir))
+            return false;
+        const files = await readdir(projectDir);
+        const jsonlFiles = files.filter(f => f.endsWith('.jsonl') && !f.startsWith('.'));
+        for (const file of jsonlFiles) {
+            const filePath = join(projectDir, file);
+            const fileStat = await stat(filePath);
+            // Only consider files created after the session.
+            if (fileStat.mtimeMs < session.createdAt)
+                continue;
+            // Extract session ID from filename (filename = sessionId.jsonl).
+            const sessionId = file.replace('.jsonl', '');
+            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(sessionId))
+                continue;
+            session.claudeSessionId = sessionId;
+            session.jsonlPath = filePath;
+            session.byteOffset = 0;
+            console.log(`Discovery (filesystem): session ${session.windowName} mapped to ${sessionId.slice(0, 8)}...`);
+            await this.save();
+            return true;
+        }
+        return false;
+    }
+    /**
+     * 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.
+     */
+    startDiscoveryPolling(id, workDir) {
+        // If a poller already exists, replace it to ensure only one active poller/session.
+        this.stopDiscoveryPolling(id);
+        const interval = setInterval(async () => {
+            const session = this.state.sessions[id];
+            if (!session) {
+                this.stopDiscoveryPolling(id);
+                return;
+            }
+            // Stop when we have both session ID and JSONL path.
+            if (session.claudeSessionId && session.jsonlPath) {
+                this.stopDiscoveryPolling(id);
+                return;
+            }
+            try {
+                await this.syncSessionMap();
+                // If we have claudeSessionId but no jsonlPath, try finding it (Issue #884: worktree-aware).
+                if (session.claudeSessionId && !session.jsonlPath) {
+                    const jsonlPath = await this.findSessionFileMaybeWorktree(session.claudeSessionId);
+                    if (jsonlPath) {
+                        session.jsonlPath = jsonlPath;
+                        session.byteOffset = 0;
+                        await this.save();
+                    }
+                }
+                // Filesystem fallback scan cadence (originally every 3s).
+                const now = Date.now();
+                const nextFsScanAt = this.discoveryNextFilesystemScanAt.get(id) ?? 0;
+                if (now >= nextFsScanAt && (!session.claudeSessionId || !session.jsonlPath)) {
+                    this.discoveryNextFilesystemScanAt.set(id, now + 3_000);
+                    await this.maybeDiscoverFromFilesystem(session, workDir);
+                }
+                if (session.claudeSessionId && session.jsonlPath) {
+                    this.stopDiscoveryPolling(id);
+                }
+            }
+            catch {
+                // best-effort polling; ignore transient errors
+            }
+        }, 2_000);
+        this.pollTimers.set(id, interval);
+        this.discoveryNextFilesystemScanAt.set(id, Date.now());
+        // P3 fix: Stop after 5 minutes if not found, log timeout.
+        // #835: Track the timeout so cleanupSession can cancel it.
+        const discoveryTimeout = setTimeout(() => {
+            const session = this.state.sessions[id];
+            this.stopDiscoveryPolling(id);
+            if (session && !session.claudeSessionId) {
+                console.log(`Discovery: session ${session.windowName} — timed out after 5min, no session_id found`);
+            }
+        }, 5 * 60 * 1000);
+        this.discoveryTimeouts.set(id, discoveryTimeout);
+    }
+    /** Sync CC session IDs from the hook-written session_map.json. */
+    async syncSessionMap() {
+        if (!existsSync(this.sessionMapFile))
+            return;
+        try {
+            const mapData = await loadContinuationPointers(this.sessionMapFile, this.config.continuationPointerTtlMs);
+            for (const session of Object.values(this.state.sessions)) {
+                if (session.claudeSessionId)
+                    continue;
+                // Find matching entry by window ID (exact match to avoid @1 matching @10, @11, etc.)
+                for (const [key, info] of Object.entries(mapData)) {
+                    // P0 fix: Match by exact windowId suffix (e.g., "aegis:@5"), not substring
+                    // This prevents @5 from matching @15, @50, etc.
+                    const keyWindowId = key.includes(':') ? key.split(':').pop() : null;
+                    const matchesWindowId = keyWindowId === session.windowId;
+                    const matchesWindowName = info.window_name === session.windowName;
+                    if (matchesWindowId || matchesWindowName) {
+                        // GUARD 1: Timestamp — reject session_map entries written before this session was created.
+                        // After service restarts, old entries survive with stale windowIds that collide
+                        // with newly assigned tmux window IDs (tmux reuses @N identifiers).
+                        // Issue #6: Zeus D51 got claudeSessionId from D18/D19/D20 due to this.
+                        const writtenAt = info.written_at || 0;
+                        if (writtenAt > 0 && writtenAt < session.createdAt) {
+                            console.log(`Discovery: session ${session.windowName} — rejecting stale entry ` +
+                                `(written_at ${new Date(writtenAt).toISOString()} < createdAt ${new Date(session.createdAt).toISOString()})`);
+                            continue;
+                        }
+                        // Use transcript_path from hook if available (M3: eliminates filesystem scan)
+                        // Falls back to findSessionFile for backward compat with old hook versions
+                        let jsonlPath = null;
+                        if (info.transcript_path && existsSync(info.transcript_path)) {
+                            jsonlPath = info.transcript_path;
+                        }
+                        else {
+                            jsonlPath = await findSessionFile(info.session_id, this.config.claudeProjectsDir);
+                        }
+                        // GUARD 2: Reject paths in _archived/ directory — these are stale sessions
+                        if (jsonlPath && (jsonlPath.includes('/_archived/') || jsonlPath.includes('\\_archived\\'))) {
+                            console.log(`Discovery: session ${session.windowName} — rejecting archived path: ${jsonlPath}`);
+                            continue;
+                        }
+                        if (!jsonlPath) {
+                            // No JSONL file found — mapping is stale or CC hasn't written it yet.
+                            // Don't break — there may be a fresher entry. Continue searching.
+                            continue;
+                        }
+                        // GUARD 3: JSONL mtime — reject if file was last modified before session creation.
+                        // Catches cases where session_map has no written_at (old hook without timestamp)
+                        // but the JSONL is clearly from a previous session.
+                        try {
+                            const fileStat = await stat(jsonlPath);
+                            if (fileStat.mtimeMs < session.createdAt) {
+                                console.log(`Discovery: session ${session.windowName} — rejecting stale JSONL ` +
+                                    `(mtime ${new Date(fileStat.mtimeMs).toISOString()} < createdAt ${new Date(session.createdAt).toISOString()})`);
+                                continue;
+                            }
+                        }
+                        catch {
+                            // stat failed — file removed between find and stat
+                            continue;
+                        }
+                        session.claudeSessionId = info.session_id;
+                        session.jsonlPath = jsonlPath;
+                        session.byteOffset = 0;
+                        console.log(`Discovery: session ${session.windowName} mapped to ` +
+                            `${info.session_id.slice(0, 8)}... (verified: timestamp + mtime)`);
+                        break;
+                    }
+                }
+            }
+            await this.save();
+        }
+        catch { /* ignore parse errors */ }
+    }
+}