perf(cache): add P2 medium-priority performance and robustness improvements

Address five P2 (medium priority) issues from code review:

**P2-1: Stale Lock Detection**
- Add PID and timestamp to lock files
- Detect and remove stale locks (dead process or >60s old)
- Prevents permanent lockouts from crashed processes
- Files: src/utils/diskCache.ts

**P2-2: Configurable Cache Directory**
- Support PDF_READER_CACHE_DIR environment variable
- Uses MD5 hash suffix to avoid filename collisions
- Falls back to PDF directory (current behavior) if not set
- Useful for read-only filesystems and centralized caching
- Files: src/utils/diskCache.ts

**P2-3: Decision Cache Race Fix**
- Remove problematic delete-before-set pattern
- Rely on Map.set() overwrite semantics (preserves insertion order)
- Use while loop for consistent eviction behavior
- Files: src/handlers/pdfOcr.ts

**P2-4: Batched Image Extraction**
- Process images in batches of 6 to prevent memory pressure
- Replaces unbounded Promise.all with batched processing
- Maintains parallelism within batches for performance
- Files: src/pdf/extractor.ts

**P2-5: Smart OCR Optimization**
- Skip text extraction when cached decision says OCR needed
- Avoids redundant work on subsequent smart_ocr calls
- Improves performance for scanned documents
- Files: src/handlers/pdfOcr.ts

All improvements maintain backward compatibility. No breaking changes.
Tests: 144 passing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: Martin

src/handlers/pdfOcr.ts

@@ -40,14 +40,18 @@ const getCachedDecision = (fingerprint: string, page: number): OcrDecision | und
 
 const setCachedDecision = (fingerprint: string, page: number, decision: OcrDecision): void => {
   const key = buildDecisionCacheKey(fingerprint, page);
-  if (decisionCache.has(key)) {
-    decisionCache.delete(key);
-  }
+
+  // Just set - Map.set() overwrites existing entries without changing insertion order
+  // for existing keys (ES2015+ Map preserves insertion order)
   decisionCache.set(key, decision);
-  if (decisionCache.size > DECISION_CACHE_MAX_ENTRIES) {
+
+  // Evict oldest entries if over limit
+  while (decisionCache.size > DECISION_CACHE_MAX_ENTRIES) {
     const oldestKey = decisionCache.keys().next().value;
     if (oldestKey) {
       decisionCache.delete(oldestKey);
+    } else {
+      break;
     }
   }
 };
@@ -231,18 +235,20 @@ const handleSmartOcrDecision = async (
   if (!smartOcr) return undefined;
 
   const cached = getCachedDecision(fingerprint, page);
-  let decision = cached;
-  let pageText = '';
 
+  // If cached decision says OCR is needed, skip text extraction entirely
+  if (cached?.needsOcr) {
+    return undefined; // Proceed to OCR
+  }
+
+  // Need to extract text for decision or result
+  const pdfPage = await pdfDocument.getPage(page);
+  const pageText = await extractTextFromPage(pdfPage);
+
+  let decision = cached;
   if (!decision) {
-    const pdfPage = await pdfDocument.getPage(page);
-    pageText = await extractTextFromPage(pdfPage);
     decision = await decideNeedsOcr(pdfPage, pageText);
     setCachedDecision(fingerprint, page, decision);
-  } else {
-    // Decision was cached, extract text now
-    const pdfPage = await pdfDocument.getPage(page);
-    pageText = await extractTextFromPage(pdfPage);
   }
 
   if (!decision.needsOcr) {

src/pdf/extractor.ts

@@ -320,23 +320,29 @@ const extractImagesFromPage = async (
       }
     }
 
-    // Extract each image using shared helper functions
-    const imagePromises = imageIndices.map(async (imgIndex, arrayIndex) => {
-      const argsArray = operatorList.argsArray[imgIndex];
-      if (!argsArray || argsArray.length === 0) {
-        return null;
-      }
+    // Extract images in batches to avoid memory pressure
+    const BATCH_SIZE = 6;
+    for (let batchStart = 0; batchStart < imageIndices.length; batchStart += BATCH_SIZE) {
+      const batch = imageIndices.slice(batchStart, batchStart + BATCH_SIZE);
 
-      const imageName = argsArray[0] as string;
-      const imageResult = await retrieveImageData(page, imageName, pageNum);
-      if (imageResult.warning) {
-        warnings.push(imageResult.warning);
-      }
-      return processImageData(imageResult.data, pageNum, arrayIndex);
-    });
+      const batchPromises = batch.map(async (imgIndex, localIdx) => {
+        const globalIndex = batchStart + localIdx;
+        const argsArray = operatorList.argsArray[imgIndex];
+        if (!argsArray || argsArray.length === 0) {
+          return null;
+        }
 
-    const resolvedImages = await Promise.all(imagePromises);
-    images.push(...resolvedImages.filter((img): img is ExtractedImage => img !== null));
+        const imageName = argsArray[0] as string;
+        const imageResult = await retrieveImageData(page, imageName, pageNum);
+        if (imageResult.warning) {
+          warnings.push(imageResult.warning);
+        }
+        return processImageData(imageResult.data, pageNum, globalIndex);
+      });
+
+      const batchResults = await Promise.all(batchPromises);
+      images.push(...batchResults.filter((img): img is ExtractedImage => img !== null));
+    }
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);
     logger.warn('Error extracting images from page', { pageNum, error: message });

src/utils/diskCache.ts

@@ -5,6 +5,7 @@
  * Format: {pdf_basename}_ocr.json
  */
 
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import fsPromises from 'node:fs/promises';
 import path from 'node:path';
@@ -15,13 +16,30 @@ const logger = createLogger('DiskCache');
 const LOCK_RETRY_MS = 25;
 const LOCK_TIMEOUT_MS = 5_000;
 
+/**
+ * Get cache directory from environment variable or default to PDF directory
+ */
+const getCacheDirectory = (): string | null => {
+  return process.env.PDF_READER_CACHE_DIR ?? null;
+};
+
 /**
  * Generate cache file path from PDF path
  * Example: /path/to/document.pdf → /path/to/document_ocr.json
+ * If PDF_READER_CACHE_DIR is set, uses that directory with hash to avoid collisions
  */
 export const getCacheFilePath = (pdfPath: string): string => {
-  const dir = path.dirname(pdfPath);
+  const cacheDir = getCacheDirectory();
   const basename = path.basename(pdfPath, path.extname(pdfPath));
+
+  if (cacheDir) {
+    // Use configured cache directory with hash to avoid collisions
+    const hash = crypto.createHash('md5').update(pdfPath).digest('hex').slice(0, 8);
+    return path.join(cacheDir, `${basename}_${hash}_ocr.json`);
+  }
+
+  // Default: alongside the PDF
+  const dir = path.dirname(pdfPath);
   return path.join(dir, `${basename}_ocr.json`);
 };
 
@@ -64,18 +82,58 @@ const sleep = (ms: number): Promise<void> => {
   return new Promise((resolve) => setTimeout(resolve, ms));
 };
 
+const LOCK_STALE_MS = 60_000; // Consider lock stale after 60 seconds
+
+/**
+ * Check if a lock file is stale (process died or lock too old)
+ */
+const isLockStale = async (lockPath: string): Promise<boolean> => {
+  try {
+    const content = await fsPromises.readFile(lockPath, 'utf-8');
+    const { pid, timestamp } = JSON.parse(content) as { pid: number; timestamp: number };
+
+    // Check if process is still running
+    try {
+      process.kill(pid, 0); // Signal 0 checks existence without killing
+    } catch {
+      logger.debug('Lock process no longer exists', { pid, lockPath });
+      return true; // Process doesn't exist, lock is stale
+    }
+
+    // Check if lock is too old
+    if (Date.now() - timestamp > LOCK_STALE_MS) {
+      logger.debug('Lock exceeded max age', { pid, age: Date.now() - timestamp, lockPath });
+      return true;
+    }
+
+    return false;
+  } catch {
+    // Can't read lock file, consider it stale
+    return true;
+  }
+};
+
 const acquireCacheLock = async (lockPath: string): Promise<fsPromises.FileHandle | null> => {
   const start = Date.now();
 
   // eslint-disable-next-line no-constant-condition
   while (true) {
     try {
       const handle = await fsPromises.open(lockPath, 'wx');
+      // Write our PID and timestamp to the lock file
+      await handle.write(JSON.stringify({ pid: process.pid, timestamp: Date.now() }));
       return handle;
     } catch (error: unknown) {
       const err = error as NodeJS.ErrnoException;
 
       if (err.code === 'EEXIST') {
+        // Check if lock is stale
+        if (await isLockStale(lockPath)) {
+          logger.warn('Removing stale cache lock', { lockPath });
+          await fsPromises.rm(lockPath, { force: true });
+          continue; // Retry acquisition
+        }
+
         if (Date.now() - start > LOCK_TIMEOUT_MS) {
           throw new Error(`Timed out waiting for cache lock at ${lockPath}`);
         }