commandmate 0.3.5 → 0.4.0

package/dist/server/src/lib/schedule-manager.js

@@ -2,6 +2,7 @@
 /**
  * Schedule Manager
  * Issue #294: Manages scheduled execution of claude -p commands
+ * Issue #409: Performance optimization with mtime caching and batch upsert
  *
  * Uses a single timer to periodically scan all worktrees for CMATE.md changes
  * and execute scheduled tasks via croner cron expressions.
@@ -10,20 +11,30 @@
  * - globalThis for hot reload persistence (same as auto-yes-manager.ts)
  * - Single timer for all worktrees (60 second polling interval)
  * - SIGKILL fire-and-forget for stopAllSchedules (< 1ms, within 3s graceful shutdown)
+ * - mtime caching to skip unchanged CMATE.md files (Issue #409)
  *
  * [S3-001] stopAllSchedules() uses synchronous process.kill for immediate cleanup
  * [S3-010] initScheduleManager() is called after initializeWorktrees()
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_CONCURRENT_SCHEDULES = exports.POLL_INTERVAL_MS = void 0;
+exports.batchUpsertSchedules = batchUpsertSchedules;
 exports.initScheduleManager = initScheduleManager;
 exports.stopAllSchedules = stopAllSchedules;
+exports.stopScheduleForWorktree = stopScheduleForWorktree;
 exports.getActiveScheduleCount = getActiveScheduleCount;
 exports.isScheduleManagerInitialized = isScheduleManagerInitialized;
+exports.getScheduleWorktreeIds = getScheduleWorktreeIds;
 const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
 const croner_1 = require("croner");
 const cmate_parser_1 = require("./cmate-parser");
 const claude_executor_1 = require("./claude-executor");
+const cmate_constants_1 = require("../config/cmate-constants");
 // =============================================================================
 // Constants
 // =============================================================================
@@ -40,6 +51,8 @@ function getManagerState() {
             timerId: null,
             schedules: new Map(),
             initialized: false,
+            isSyncing: false,
+            cmateFileCache: new Map(),
         };
     }
     return globalThis.__scheduleManagerStates;
@@ -60,6 +73,38 @@ function getLazyDbInstance() {
     return getDbInstance();
 }
 // =============================================================================
+// CMATE.md mtime Helper
+// =============================================================================
+/**
+ * Get the modification time (mtimeMs) of the CMATE.md file in a worktree directory.
+ *
+ * Trust boundary (SEC4-003): worktreePath is DB-derived from getAllWorktrees()
+ * and was validated by validateWorktreePath() at worktree registration time.
+ * Therefore, path traversal re-validation is not needed here.
+ * readCmateFile() has validateCmatePath() because it can be called externally,
+ * whereas getCmateMtime() is an internal function called only from syncSchedules().
+ *
+ * @param worktreePath - Path to the worktree directory (DB-derived, trusted)
+ * @returns mtimeMs value, or null if the file does not exist or cannot be read
+ */
+function getCmateMtime(worktreePath) {
+    // Uses CMATE_FILENAME from @/config/cmate-constants directly (DR1-001, CR2-001)
+    const filePath = path_1.default.join(worktreePath, cmate_constants_1.CMATE_FILENAME);
+    try {
+        return (0, fs_1.statSync)(filePath).mtimeMs;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return null;
+        }
+        // Permission errors etc. - log and treat as no file (SEC4-004-note)
+        console.warn(`[schedule-manager] Failed to stat ${filePath}:`, error);
+        return null;
+    }
+}
+// =============================================================================
 // DB Operations
 // =============================================================================
 /**
@@ -78,33 +123,66 @@ function getAllWorktrees() {
     }
 }
 /**
- * Upsert a schedule entry into the database.
- * If a schedule with the same worktree_id and name exists, it is updated.
- * Otherwise, a new schedule is created.
+ * Batch upsert schedule entries into the database.
+ * Replaces the previous per-entry upsertSchedule() function (DR1-002).
  *
- * @param worktreeId - The worktree ID to associate the schedule with
- * @param entry - The schedule entry from CMATE.md
- * @returns The schedule ID (existing or newly created)
+ * Uses a single SELECT to build an existing schedules map, then performs
+ * all UPDATE/INSERT operations within a single transaction.
+ *
+ * Sanitization chain (SEC4-004): This function is called exclusively from
+ * syncSchedules(), which passes entries produced by parseSchedulesSection().
+ * parseSchedulesSection() calls sanitizeMessageContent() (S4-002) on all
+ * message fields, so entries arriving here are already sanitized.
+ * If batchUpsertSchedules() is called from a different code path in the
+ * future, an input validation layer must be added at the call site.
+ *
+ * Note on next_execute_at (CR2-002): The scheduled_executions table has a
+ * next_execute_at column (INTEGER, nullable) that is intentionally not
+ * operated on by this function, consistent with the prior upsertSchedule().
+ *
+ * @param worktreeId - The worktree ID to associate schedules with
+ * @param entries - Schedule entries from CMATE.md (sanitized by parseSchedulesSection)
+ * @returns Array of schedule IDs (existing or newly created), in the same order as entries
  */
-function upsertSchedule(worktreeId, entry) {
+function batchUpsertSchedules(worktreeId, entries) {
+    if (entries.length === 0)
+        return [];
     const db = getLazyDbInstance();
     const now = Date.now();
-    // Check if schedule already exists
-    const existing = db.prepare('SELECT id FROM scheduled_executions WHERE worktree_id = ? AND name = ?').get(worktreeId, entry.name);
-    if (existing) {
-        db.prepare(`
-      UPDATE scheduled_executions
-      SET message = ?, cron_expression = ?, cli_tool_id = ?, enabled = ?, updated_at = ?
-      WHERE id = ?
-    `).run(entry.message, entry.cronExpression, entry.cliToolId, entry.enabled ? 1 : 0, now, existing.id);
-        return existing.id;
+    // Bulk fetch existing schedules for this worktree.
+    // better-sqlite3's prepare() is cached at the DB instance level (DR1-007),
+    // so calling it each invocation does not incur additional compilation cost.
+    const existingRows = db.prepare('SELECT id, name FROM scheduled_executions WHERE worktree_id = ?').all(worktreeId);
+    const existingByName = new Map();
+    for (const row of existingRows) {
+        existingByName.set(row.name, row.id);
     }
-    const id = (0, crypto_1.randomUUID)();
-    db.prepare(`
+    const resultIds = [];
+    const updateStmt = db.prepare(`
+    UPDATE scheduled_executions
+    SET message = ?, cron_expression = ?, cli_tool_id = ?, enabled = ?, updated_at = ?
+    WHERE id = ?
+  `);
+    const insertStmt = db.prepare(`
     INSERT INTO scheduled_executions (id, worktree_id, name, message, cron_expression, cli_tool_id, enabled, created_at, updated_at)
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(id, worktreeId, entry.name, entry.message, entry.cronExpression, entry.cliToolId, entry.enabled ? 1 : 0, now, now);
-    return id;
+  `);
+    const runTransaction = db.transaction(() => {
+        for (const entry of entries) {
+            const existingId = existingByName.get(entry.name);
+            if (existingId) {
+                updateStmt.run(entry.message, entry.cronExpression, entry.cliToolId, entry.enabled ? 1 : 0, now, existingId);
+                resultIds.push(existingId);
+            }
+            else {
+                const id = (0, crypto_1.randomUUID)();
+                insertStmt.run(id, worktreeId, entry.name, entry.message, entry.cronExpression, entry.cliToolId, entry.enabled ? 1 : 0, now, now);
+                resultIds.push(id);
+            }
+        }
+    });
+    runTransaction();
+    return resultIds;
 }
 /**
  * Create an execution log entry in 'running' status.
@@ -183,6 +261,11 @@ function disableStaleSchedules(activeScheduleIds, worktreeIds) {
     try {
         const db = getLazyDbInstance();
         const now = Date.now();
+        // SEC4-002: Dynamic placeholder generation is SQL injection-safe because only
+        // '?' placeholders are interpolated into SQL; actual values are passed via
+        // prepared statement parameter binding. worktreeIds originates from
+        // getAllWorktrees() (bounded by MAX_CONCURRENT_SCHEDULES ~100), well within
+        // SQLite's SQLITE_MAX_VARIABLE_NUMBER (default 999).
         const placeholders = worktreeIds.map(() => '?').join(',');
         // Get enabled schedules for the scanned worktrees
         const rows = db.prepare(`SELECT id FROM scheduled_executions WHERE worktree_id IN (${placeholders}) AND enabled = 1`).all(...worktreeIds);
@@ -250,77 +333,121 @@ async function executeSchedule(state) {
  * Sync schedules from CMATE.md files for all worktrees.
  * Reads CMATE.md from each worktree, upserts schedules to DB,
  * creates/updates cron jobs, and removes stale schedules.
+ *
+ * Issue #406: Async I/O for readCmateFile() to avoid event loop blocking.
+ * Issue #409: Uses mtime caching to skip unchanged CMATE.md files
+ * and batchUpsertSchedules() for efficient DB operations.
+ *
+ * DJ-007: isSyncing guard prevents concurrent execution when async
+ * operations exceed the 60-second polling interval.
  */
-function syncSchedules() {
+async function syncSchedules() {
     const manager = getManagerState();
-    const worktrees = getAllWorktrees();
-    // Track which scheduleIds are still valid
-    const activeScheduleIds = new Set();
-    for (const worktree of worktrees) {
-        try {
-            const config = (0, cmate_parser_1.readCmateFile)(worktree.path);
-            if (!config)
-                continue;
-            const scheduleRows = config.get('Schedules');
-            if (!scheduleRows)
-                continue;
-            const entries = (0, cmate_parser_1.parseSchedulesSection)(scheduleRows);
-            for (const entry of entries) {
-                if (manager.schedules.size >= exports.MAX_CONCURRENT_SCHEDULES) {
-                    console.warn(`[schedule-manager] MAX_CONCURRENT_SCHEDULES (${exports.MAX_CONCURRENT_SCHEDULES}) reached`);
-                    return;
-                }
-                const scheduleId = upsertSchedule(worktree.id, entry);
-                activeScheduleIds.add(scheduleId);
-                // Check if this schedule already has a running cron job
-                const existingState = manager.schedules.get(scheduleId);
-                if (existingState) {
-                    // Update entry if changed
-                    existingState.entry = entry;
+    // DJ-007: Prevent concurrent execution (SEC4-004)
+    if (manager.isSyncing)
+        return;
+    manager.isSyncing = true;
+    try {
+        const worktrees = getAllWorktrees();
+        // Track which scheduleIds are still valid
+        const activeScheduleIds = new Set();
+        for (const worktree of worktrees) {
+            try {
+                // Issue #409: Check CMATE.md mtime for change detection
+                const mtime = getCmateMtime(worktree.path);
+                const cachedMtime = manager.cmateFileCache.get(worktree.path);
+                if (mtime === null) {
+                    // CMATE.md does not exist (or was deleted).
+                    // DR1-009: By not adding to activeScheduleIds, this worktree's
+                    // schedules will be cleaned up in Step 4 (stale cron job removal)
+                    // and disableStaleSchedules() (DB enabled=0 update).
+                    if (cachedMtime !== undefined) {
+                        manager.cmateFileCache.delete(worktree.path);
+                    }
                     continue;
                 }
-                if (!entry.enabled || !entry.cronExpression)
+                // If mtime matches cached value, skip DB operations for this worktree
+                if (cachedMtime !== undefined && cachedMtime === mtime) {
+                    // File unchanged - re-add existing schedule IDs to keep them active
+                    for (const [scheduleId, state] of manager.schedules) {
+                        if (state.worktreeId === worktree.id) {
+                            activeScheduleIds.add(scheduleId);
+                        }
+                    }
                     continue;
-                // Create new cron job
-                try {
-                    const cronJob = new croner_1.Cron(entry.cronExpression, {
-                        paused: false,
-                        protect: true, // Prevent overlapping
-                    });
-                    const state = {
-                        scheduleId,
-                        worktreeId: worktree.id,
-                        cronJob,
-                        isExecuting: false,
-                        entry,
-                    };
-                    // Schedule execution
-                    cronJob.schedule(() => {
-                        void executeSchedule(state);
-                    });
-                    manager.schedules.set(scheduleId, state);
-                    console.log(`[schedule-manager] Scheduled ${entry.name} (${entry.cronExpression})`);
                 }
-                catch (cronError) {
-                    console.warn(`[schedule-manager] Invalid cron for ${entry.name}:`, cronError);
+                // Update mtime cache
+                manager.cmateFileCache.set(worktree.path, mtime);
+                const config = await (0, cmate_parser_1.readCmateFile)(worktree.path);
+                if (!config)
+                    continue;
+                const scheduleRows = config.get('Schedules');
+                if (!scheduleRows)
+                    continue;
+                const entries = (0, cmate_parser_1.parseSchedulesSection)(scheduleRows);
+                // Issue #409: Batch upsert all entries for this worktree
+                const scheduleIds = batchUpsertSchedules(worktree.id, entries);
+                for (let i = 0; i < entries.length; i++) {
+                    const entry = entries[i];
+                    const scheduleId = scheduleIds[i];
+                    if (manager.schedules.size >= exports.MAX_CONCURRENT_SCHEDULES) {
+                        console.warn(`[schedule-manager] MAX_CONCURRENT_SCHEDULES (${exports.MAX_CONCURRENT_SCHEDULES}) reached`);
+                        return;
+                    }
+                    activeScheduleIds.add(scheduleId);
+                    // Check if this schedule already has a running cron job
+                    const existingState = manager.schedules.get(scheduleId);
+                    if (existingState) {
+                        // Update entry if changed
+                        existingState.entry = entry;
+                        continue;
+                    }
+                    if (!entry.enabled || !entry.cronExpression)
+                        continue;
+                    // Create new cron job
+                    try {
+                        const cronJob = new croner_1.Cron(entry.cronExpression, {
+                            paused: false,
+                            protect: true, // Prevent overlapping
+                        });
+                        const state = {
+                            scheduleId,
+                            worktreeId: worktree.id,
+                            cronJob,
+                            isExecuting: false,
+                            entry,
+                        };
+                        // Schedule execution
+                        cronJob.schedule(() => {
+                            void executeSchedule(state);
+                        });
+                        manager.schedules.set(scheduleId, state);
+                        console.log(`[schedule-manager] Scheduled ${entry.name} (${entry.cronExpression})`);
+                    }
+                    catch (cronError) {
+                        console.warn(`[schedule-manager] Invalid cron for ${entry.name}:`, cronError);
+                    }
                 }
             }
+            catch (error) {
+                console.error(`[schedule-manager] Error syncing schedules for worktree ${worktree.id}:`, error);
+            }
         }
-        catch (error) {
-            console.error(`[schedule-manager] Error syncing schedules for worktree ${worktree.id}:`, error);
+        // Clean up schedules that no longer exist in CMATE.md
+        for (const [scheduleId, state] of manager.schedules) {
+            if (!activeScheduleIds.has(scheduleId)) {
+                state.cronJob.stop();
+                manager.schedules.delete(scheduleId);
+                console.log(`[schedule-manager] Removed stale schedule ${state.entry.name}`);
+            }
         }
+        // Disable DB records for schedules no longer in CMATE.md
+        const worktreeIds = worktrees.map(w => w.id);
+        disableStaleSchedules(activeScheduleIds, worktreeIds);
     }
-    // Clean up schedules that no longer exist in CMATE.md
-    for (const [scheduleId, state] of manager.schedules) {
-        if (!activeScheduleIds.has(scheduleId)) {
-            state.cronJob.stop();
-            manager.schedules.delete(scheduleId);
-            console.log(`[schedule-manager] Removed stale schedule ${state.entry.name}`);
-        }
+    finally {
+        manager.isSyncing = false;
     }
-    // Disable DB records for schedules no longer in CMATE.md
-    const worktreeIds = worktrees.map(w => w.id);
-    disableStaleSchedules(activeScheduleIds, worktreeIds);
 }
 // =============================================================================
 // Manager Lifecycle
@@ -340,11 +467,11 @@ function initScheduleManager() {
     console.log('[schedule-manager] Initializing...');
     // Recovery: mark stale running logs as failed
     recoverRunningLogs();
-    // Initial sync
-    syncSchedules();
-    // Start periodic sync timer
+    // Initial sync (DJ-002: fire-and-forget, no .catch - fail-fast for fatal errors)
+    void syncSchedules();
+    // Start periodic sync timer (DJ-003: .catch for repeated execution safety)
     manager.timerId = setInterval(() => {
-        syncSchedules();
+        void syncSchedules().catch(err => console.error('[schedule-manager] Unexpected sync error:', err));
     }, exports.POLL_INTERVAL_MS);
     manager.initialized = true;
     console.log(`[schedule-manager] Initialized with ${manager.schedules.size} schedule(s)`);
@@ -372,6 +499,9 @@ function stopAllSchedules() {
         }
     }
     manager.schedules.clear();
+    // DR1-008: Clear mtime cache to prevent stale values from causing
+    // incorrect skip decisions on next initScheduleManager() call
+    manager.cmateFileCache.clear();
     // Kill all active child processes (fire-and-forget SIGKILL)
     const activeProcesses = (0, claude_executor_1.getActiveProcesses)();
     for (const [pid] of activeProcesses) {
@@ -386,6 +516,47 @@ function stopAllSchedules() {
     manager.initialized = false;
     console.log('[schedule-manager] All schedules stopped');
 }
+/**
+ * Stop schedules for a specific worktree.
+ * Issue #404: Used during worktree deletion to prevent resource leaks.
+ *
+ * Iterates the schedules map (O(N), N<=MAX_CONCURRENT_SCHEDULES=100),
+ * stops cron jobs for the target worktree, and removes their entries.
+ * Also removes the cmateFileCache entry for the worktree path (via DB lookup).
+ *
+ * activeProcesses are NOT killed (method (c): natural reclamation).
+ * cronJob.stop() prevents new executions; running processes finish naturally.
+ *
+ * @param worktreeId - The worktree ID whose schedules should be stopped
+ */
+function stopScheduleForWorktree(worktreeId) {
+    const manager = getManagerState();
+    // Stop and remove cron jobs for the target worktree
+    for (const [scheduleId, state] of manager.schedules) {
+        if (state.worktreeId === worktreeId) {
+            try {
+                state.cronJob.stop();
+            }
+            catch {
+                // Ignore errors during cleanup
+            }
+            manager.schedules.delete(scheduleId);
+        }
+    }
+    // Remove cmateFileCache entry via DB lookup (worktreeId -> path)
+    try {
+        const db = getLazyDbInstance();
+        const row = db.prepare('SELECT path FROM worktrees WHERE id = ?').get(worktreeId);
+        if (row?.path) {
+            manager.cmateFileCache.delete(row.path);
+        }
+    }
+    catch (error) {
+        // DB lookup failed - schedule stop already completed above (fallback)
+        console.warn(`[schedule-manager] Failed to resolve worktree path for cache cleanup (worktreeId: ${worktreeId}):`, error);
+    }
+    console.log(`[schedule-manager] Stopped schedules for worktree: ${worktreeId}`);
+}
 /**
  * Get the current number of active schedules.
  * Useful for monitoring and testing.
@@ -399,3 +570,18 @@ function getActiveScheduleCount() {
 function isScheduleManagerInitialized() {
     return getManagerState().initialized;
 }
+/**
+ * Get all unique worktree IDs that have active schedule entries.
+ * Used by periodic resource cleanup to detect orphaned entries.
+ *
+ * @internal Exported for resource-cleanup and testing purposes.
+ * @returns Array of unique worktree IDs present in the schedules Map
+ */
+function getScheduleWorktreeIds() {
+    const manager = getManagerState();
+    const worktreeIds = new Set();
+    for (const [, state] of manager.schedules) {
+        worktreeIds.add(state.worktreeId);
+    }
+    return Array.from(worktreeIds);
+}

package/dist/server/src/lib/tmux-capture-cache.js

@@ -0,0 +1,221 @@
+"use strict";
+/**
+ * tmux capture cache module
+ * Issue #405: TTL-based cache for tmux capture-pane output with singleflight deduplication
+ *
+ * Provides in-memory caching of tmux capture-pane results to eliminate redundant
+ * tmux process invocations. Uses globalThis pattern for Next.js hot reload persistence.
+ *
+ * Cache key: sessionName (mcbd-{cliToolId}-{worktreeId} format)
+ * Cache value: CacheEntry (output + metadata)
+ * TTL: 2 seconds (CACHE_TTL_MS)
+ *
+ * [SEC4-001] Trust Boundary: sessionName is validated by the caller chain
+ * (CLIToolManager.getTool(cliToolId).getSessionName()). This module does not
+ * perform additional sessionName validation.
+ *
+ * [DA3-002] Singleflight key uses sessionName, which contains cliToolId.
+ * Different cliToolIds cannot share the same singleflight entry, preventing
+ * error message context mismatch across callers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CACHE_MAX_CAPTURE_LINES = exports.CACHE_MAX_ENTRIES = exports.CACHE_TTL_MS = void 0;
+exports.sliceOutput = sliceOutput;
+exports.getCachedCapture = getCachedCapture;
+exports.setCachedCapture = setCachedCapture;
+exports.invalidateCache = invalidateCache;
+exports.clearAllCache = clearAllCache;
+exports.resetCacheForTesting = resetCacheForTesting;
+exports.getOrFetchCapture = getOrFetchCapture;
+// =========================================================================
+// Constants
+// =========================================================================
+/** Cache TTL in milliseconds */
+exports.CACHE_TTL_MS = 2000;
+/** Maximum number of cache entries */
+exports.CACHE_MAX_ENTRIES = 100;
+/** Maximum capture lines for cache storage */
+exports.CACHE_MAX_CAPTURE_LINES = 10000;
+function getCache() {
+    return (globalThis.__tmuxCaptureCache ??= new Map());
+}
+function getInflight() {
+    return (globalThis.__tmuxCaptureCacheInflight ??= new Map());
+}
+// =========================================================================
+// sliceOutput()
+// =========================================================================
+/**
+ * Slice output from the end to return the last requestedLines lines.
+ * If requestedLines >= total lines, returns the full output.
+ *
+ * @param fullOutput - Full captured output string
+ * @param requestedLines - Number of lines requested from the end
+ * @returns Sliced output string
+ */
+function sliceOutput(fullOutput, requestedLines) {
+    if (fullOutput === '')
+        return '';
+    const lines = fullOutput.split('\n');
+    if (requestedLines >= lines.length)
+        return fullOutput;
+    return lines.slice(-requestedLines).join('\n');
+}
+// =========================================================================
+// getCachedCapture()
+// =========================================================================
+/**
+ * Get cached capture output for a session.
+ * Returns null on cache miss, TTL expiration, or insufficient cached lines.
+ * Performs lazy eviction of TTL-expired entries.
+ *
+ * [SEC4-002] Lazy eviction only: expired entries that are never queried
+ * may persist in memory. Full sweep is performed in setCachedCapture().
+ *
+ * @param sessionName - tmux session name (cache key)
+ * @param requestedLines - Number of lines requested
+ * @returns Cached output (sliced to requestedLines) or null
+ */
+function getCachedCapture(sessionName, requestedLines) {
+    const cache = getCache();
+    const entry = cache.get(sessionName);
+    if (!entry)
+        return null;
+    // TTL check with lazy eviction
+    const now = Date.now();
+    if (now - entry.timestamp > exports.CACHE_TTL_MS) {
+        cache.delete(sessionName);
+        return null;
+    }
+    // Insufficient cached lines check
+    if (requestedLines > entry.capturedLines) {
+        return null;
+    }
+    return sliceOutput(entry.output, requestedLines);
+}
+// =========================================================================
+// setCachedCapture()
+// =========================================================================
+/**
+ * Store capture output in cache.
+ * Performs full sweep of TTL-expired entries before writing (SEC4-002).
+ * Enforces CACHE_MAX_ENTRIES limit by evicting oldest entry.
+ *
+ * @param sessionName - tmux session name (cache key)
+ * @param output - Captured output string
+ * @param capturedLines - Number of lines the output was captured with
+ */
+function setCachedCapture(sessionName, output, capturedLines) {
+    const cache = getCache();
+    const now = Date.now();
+    // [SEC4-002] Full sweep: remove all TTL-expired entries
+    for (const [key, entry] of cache) {
+        if (now - entry.timestamp > exports.CACHE_TTL_MS) {
+            cache.delete(key);
+        }
+    }
+    // Enforce size limit (evict oldest if at capacity)
+    if (cache.size >= exports.CACHE_MAX_ENTRIES && !cache.has(sessionName)) {
+        // Find and delete oldest entry
+        let oldestKey = null;
+        let oldestTimestamp = Infinity;
+        for (const [key, entry] of cache) {
+            if (entry.timestamp < oldestTimestamp) {
+                oldestTimestamp = entry.timestamp;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            cache.delete(oldestKey);
+        }
+    }
+    cache.set(sessionName, {
+        output,
+        capturedLines,
+        timestamp: now,
+    });
+}
+// =========================================================================
+// invalidateCache()
+// =========================================================================
+/**
+ * Invalidate cache for a specific session.
+ * [SEC4-006] Logs debug message with session name for troubleshooting.
+ *
+ * @param sessionName - tmux session name to invalidate
+ */
+function invalidateCache(sessionName) {
+    const cache = getCache();
+    cache.delete(sessionName);
+    // [SEC4-006] Debug log for cache invalidation chain tracking
+    console.debug('invalidateCache:', { sessionName });
+}
+// =========================================================================
+// clearAllCache()
+// =========================================================================
+/**
+ * Clear all cache entries and inflight requests.
+ * Used for graceful shutdown.
+ */
+function clearAllCache() {
+    const cache = getCache();
+    cache.clear();
+    const inflight = getInflight();
+    inflight.clear();
+}
+// =========================================================================
+// resetCacheForTesting()
+// =========================================================================
+/**
+ * Reset cache and inflight maps for test isolation.
+ * @internal Exported for testing purposes only.
+ */
+function resetCacheForTesting() {
+    globalThis.__tmuxCaptureCache = undefined;
+    globalThis.__tmuxCaptureCacheInflight = undefined;
+}
+// =========================================================================
+// getOrFetchCapture() - singleflight pattern
+// =========================================================================
+/**
+ * Get capture output from cache or fetch it.
+ * Implements singleflight pattern: concurrent requests for the same session
+ * share a single fetchFn invocation.
+ *
+ * [DA3-002] Singleflight key is sessionName which contains cliToolId,
+ * preventing cross-cliTool error context mismatch.
+ *
+ * @param sessionName - tmux session name
+ * @param requestedLines - Number of lines requested
+ * @param fetchFn - Function to fetch output on cache miss
+ * @returns Captured output (sliced to requestedLines)
+ */
+async function getOrFetchCapture(sessionName, requestedLines, fetchFn) {
+    // 1. Check cache first
+    const cached = getCachedCapture(sessionName, requestedLines);
+    if (cached !== null) {
+        return cached;
+    }
+    // 2. Check for inflight request (singleflight)
+    const inflight = getInflight();
+    const existingPromise = inflight.get(sessionName);
+    if (existingPromise) {
+        const result = await existingPromise;
+        return sliceOutput(result, requestedLines);
+    }
+    // 3. Create new fetch promise
+    const fetchPromise = fetchFn();
+    inflight.set(sessionName, fetchPromise);
+    try {
+        const output = await fetchPromise;
+        // Cache non-empty results only [SEC4-007]
+        if (output.length > 0) {
+            setCachedCapture(sessionName, output, exports.CACHE_MAX_CAPTURE_LINES);
+        }
+        return sliceOutput(output, requestedLines);
+    }
+    finally {
+        // Clean up inflight entry
+        inflight.delete(sessionName);
+    }
+}