task-summary-extractor 9.6.0 → 9.7.0

package/ARCHITECTURE.md

@@ -15,6 +15,7 @@
   - [Per-Segment Processing](#per-segment-processing)
     - [File Resolution Strategies](#file-resolution-strategies)
     - [Quality Gate Decision Table](#quality-gate-decision-table)
+  - [Multi-Segment Batching](#multi-segment-batching)
   - [Smart Change Detection](#smart-change-detection)
     - [Correlation Strategies](#correlation-strategies)
     - [Assessment Thresholds](#assessment-thresholds)
@@ -249,6 +250,56 @@ After all passes complete, any Gemini File API uploads are cleaned up (fire-and-
 
 ---
 
+## Multi-Segment Batching
+
+When the Gemini context window has enough headroom, consecutive video segments are grouped into single API calls. This reduces the number of Gemini calls and gives the model better cross-segment awareness.
+
+```mermaid
+flowchart TB
+    START(["All Segments"]) --> CHECK{"Batching enabled?\n!noBatch && !skipGemini\n&& segments > 1"}
+    CHECK -->|No| SINGLE["Single-segment\nprocessing (original)"]
+    CHECK -->|Yes| PLAN["planSegmentBatches()\nGreedy bin-packing"]
+
+    PLAN --> BUDGET["Calculate token budget:\ncontextWindow (1M)\n− promptOverhead (120K)\n− docTokens\n− prevAnalysesTokens\n= available for video"]
+
+    BUDGET --> FIT{"batchSize > 1?"}
+    FIT -->|No| SINGLE
+    FIT -->|Yes| BATCH["Process in batches"]
+
+    BATCH --> B1["Batch 1:\nsegs 1–N"]
+    BATCH --> B2["Batch 2:\nsegs N+1–M"]
+    BATCH --> BN["..."]
+
+    B1 --> CALL["processSegmentBatch()\nMultiple fileData parts\nper Gemini call"]
+    CALL --> PARSE["Parse + Quality Gate\n+ Schema Validation"]
+    PARSE --> TAG["Tag items with\nsource_segment"]
+
+    CALL -->|Error| FALLBACK["Fall back to\nsingle-segment mode"]
+    FALLBACK --> SINGLE
+```
+
+### How It Works
+
+| Step | Detail |
+| ------ | -------- |
+| **Token budget** | `contextWindow − 120K overhead − docTokens − prevAnalysesTokens = available` |
+| **Video cost** | ~300 tokens/sec × segment duration |
+| **Bin-packing** | Greedy: add consecutive segments until budget or max batch size (8) reached |
+| **Deep summary synergy** | Deep summary frees 60–80% of doc tokens → more room for video → larger batches |
+| **Fallback** | Any batch failure → entire remaining file falls back to single-segment processing |
+| **Cache aware** | Cached segment runs are loaded from disk; only uncached batches hit the API |
+| **Disable** | `--no-batch` forces original single-segment behavior |
+
+### Token Math Example
+
+| Scenario | Doc Tokens | Available | Seg Duration | Tokens/Seg | Batch Size |
+| ---------- | ----------- | ----------- | ------------- | ----------- | ----------- |
+| No deep summary | 300K | ~580K | 280s | 84K | 6 |
+| With deep summary | 60K | ~820K | 280s | 84K | 9 |
+| Raw mode | 60K | ~820K | 1200s | 360K | 2 |
+
+---
+
 ## Smart Change Detection
 
 The `--update-progress` mode tracks which extracted items have been addressed:

package/QUICK_START.md

@@ -236,6 +236,17 @@ my-project/runs/{timestamp}/
 
 ---
 
+## Advanced Features
+
+| Feature | Flag | Description |
+| --------- | ------ | ------------- |
+| **Deep Summary** | `--deep-summary` | Pre-summarizes context docs — saves 60-80% input tokens per segment |
+| **Deep Dive** | `--deep-dive` | Generates explanatory docs for each discussion topic |
+| **Multi-Segment Batching** | enabled by default | When context window has headroom, groups consecutive segments into single API calls — fewer requests, better cross-segment awareness. Use `--no-batch` to disable |
+| **Raw Video Mode** | `--no-compress` | Skip re-encoding — pass video directly to Gemini |
+
+---
+
 ## Troubleshooting
 
 | Problem | Fix |

package/README.md

@@ -1,13 +1,13 @@
 # Task Summary Extractor
 
-> **v9.4.0** — AI-powered content analysis CLI — meetings, recordings, documents, or any mix. Install globally, run anywhere.
+> **v9.7.0** — AI-powered content analysis CLI — meetings, recordings, documents, or any mix. Install globally, run anywhere.
 
 <p align="center">
   <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-green" alt="Node.js" />
   <img src="https://img.shields.io/badge/gemini-2.5--flash-blue" alt="Gemini" />
-  <img src="https://img.shields.io/badge/firebase-11.x-orange" alt="Firebase" />
-  <img src="https://img.shields.io/badge/version-9.4.0-brightgreen" alt="Version" />
-  <img src="https://img.shields.io/badge/tests-331%20passing-brightgreen" alt="Tests" />
+  <img src="https://img.shields.io/badge/firebase-12.x-orange" alt="Firebase" />
+  <img src="https://img.shields.io/badge/version-9.7.0-brightgreen" alt="Version" />
+  <img src="https://img.shields.io/badge/tests-345%20passing-brightgreen" alt="Tests" />
   <img src="https://img.shields.io/badge/npm-task--summary--extractor-red" alt="npm" />
 </p>
 
@@ -183,7 +183,7 @@ These are the ones you'll actually use:
 | `--resume` | Continue an interrupted run | `--resume` |
 | `--reanalyze` | Force fresh analysis (ignore cache) | `--reanalyze` |
 | `--dry-run` | Preview what would run, without running | `--dry-run` |
-| `--format <type>` | Output format: `md`, `html`, `json`, `pdf`, `docx`, `all` (default: `md`) | `--format html` |
+| `--format <type>` | Output format: `md`, `html`, `json`, `pdf`, `docx`, `all` (default: `all`) | `--format html` |
 | `--min-confidence <level>` | Filter items by confidence: `high`, `medium`, `low` | `--min-confidence high` |
 | `--no-html` | Suppress HTML report generation | `--no-html` |
 | `--deep-summary` | Pre-summarize context docs (60-80% token savings) | `--deep-summary` |
@@ -273,6 +273,7 @@ Control how video is processed before AI analysis:
 | `--no-focused-pass` | enabled | Disable targeted re-analysis of weak segments |
 | `--no-learning` | enabled | Disable auto-tuning from historical run data |
 | `--no-diff` | enabled | Disable diff comparison with the previous run |
+| `--no-batch` | enabled | Disable multi-segment batching (force 1 segment per API call) |
 
 ### Available Models
 
@@ -304,7 +305,7 @@ DYNAMIC    --request <text>
 PROGRESS   --repo <path>
 TUNING     --thinking-budget  --compilation-thinking-budget  --parallel
            --parallel-analysis  --log-level  --output
-           --no-focused-pass  --no-learning  --no-diff
+           --no-focused-pass  --no-learning  --no-diff  --no-batch
 INFO       --help (-h)  --version (-v)
 ```
 
@@ -472,6 +473,7 @@ GEMINI_API_KEY=your-key-here
 | **Deep Summary** | `--deep-summary` pre-summarizes context docs, 60-80% token savings per segment |
 | **Context Window Safety** | Auto-truncation, pre-flight token checks, RESOURCE_EXHAUSTED recovery |
 | **Multi-Format Output** | `--format` flag: Markdown, HTML, JSON, PDF, DOCX, or all formats at once |
+| **Multi-Segment Batching** | Groups consecutive segments into single API calls when context window has headroom — fewer calls, better cross-segment awareness. `--no-batch` to disable |
 | **Interactive CLI** | Run with no args → guided experience |
 | **Resume / Checkpoint** | `--resume` continues interrupted runs |
 | **Firebase Upload** | Team access via cloud (optional) |
@@ -586,7 +588,7 @@ task-summary-extractor/
 | `npm run check` | Validate environment |
 | `npm start` | Run the pipeline |
 | `npm run help` | Show CLI help |
-| `npm test` | Run test suite (331 tests) |
+| `npm test` | Run test suite (345 tests) |
 | `npm run test:watch` | Run tests in watch mode |
 | `npm run test:coverage` | Run tests with coverage report |
 
@@ -596,6 +598,7 @@ task-summary-extractor/
 
 | Version | Highlights |
 |---------|-----------|
+| **v9.7.0** | **Multi-segment batching** — groups consecutive video segments into single Gemini API calls when context window has headroom, greedy bin-packing by token budget (`planSegmentBatches`), `processSegmentBatch()` multi-video API calls, automatic fallback to single-segment on failure, `--no-batch` to disable, codebase audit fixes (unused imports, variable shadowing) |
 | **v9.6.0** | **Interactive CLI UX** — arrow-key navigation for all selectors (folder, model, run mode, formats, confidence, doc exclusion), zero-dependency prompt engine (`interactive.js`), `selectOne()` with ↑↓+Enter, `selectMany()` with Space toggle + A all/none, non-TTY fallback to number input |
 | **v9.5.0** | **Video processing flags** — `--no-compress`, `--speed`, `--segment-time` CLI flags, hardcoded 1200s for raw mode, deprecated `--skip-compression` |
 | **v9.4.0** | **Context window safety** — pre-flight token checks, auto-truncation for oversized docs/VTTs, RESOURCE_EXHAUSTED recovery with automatic doc shedding, chunked compilation for large segment sets, P0/P1 hard cap (2× budget) prevents context overflow, improved deep-summary prompt quality |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-summary-extractor",
-  "version": "9.6.0",
+  "version": "9.7.0",
   "description": "AI-powered meeting analysis & document generation CLI — video + document processing, deep dive docs, dynamic mode, interactive CLI with model selection, confidence scoring, learning loop, git progress tracking",
   "main": "process_and_upload.js",
   "bin": {

package/src/phases/init.js

@@ -66,6 +66,7 @@ async function phaseInit() {
     disableLearning: !!flags['no-learning'],
     disableDiff: !!flags['no-diff'],
     noHtml: !!flags['no-html'],
+    noBatch: !!flags['no-batch'],
     // Video processing flags
     noCompress: !!flags['no-compress'],
     speed: flags.speed ? parseFloat(flags.speed) : null,
@@ -355,6 +356,7 @@ function _printRunSummary(opts, modelId, models, targetDir) {
   if (opts.deepDive) features.push(c.cyan('deep-dive'));
   if (opts.deepSummary) features.push(c.cyan('deep-summary'));
   if (opts.dynamic) features.push(c.cyan('dynamic'));
+  if (!opts.noBatch) features.push(c.green('batch'));
   if (opts.resume) features.push(c.yellow('resume'));
   if (opts.dryRun) features.push(c.yellow('dry-run'));
   if (opts.skipUpload) features.push(c.dim('skip-upload'));
@@ -363,6 +365,7 @@ function _printRunSummary(opts, modelId, models, targetDir) {
   if (opts.disableFocusedPass) disabled.push(c.dim('no-focused'));
   if (opts.disableLearning) disabled.push(c.dim('no-learning'));
   if (opts.disableDiff) disabled.push(c.dim('no-diff'));
+  if (opts.noBatch) disabled.push(c.dim('no-batch'));
 
   if (features.length > 0) {
     console.log(`    ${c.dim('Features:')}    ${features.join(c.dim(' · '))}`);

package/src/phases/process-media.js

@@ -9,7 +9,7 @@ const { AUDIO_EXTS, SPEED } = config;
 
 // --- Services ---
 const { uploadToStorage, storageExists } = require('../services/firebase');
-const { processWithGemini, cleanupGeminiFiles } = require('../services/gemini');
+const { processWithGemini, processSegmentBatch, cleanupGeminiFiles } = require('../services/gemini');
 const { compressAndSegment, compressAndSegmentAudio, splitOnly, probeFormat, verifySegment } = require('../services/video');
 
 // --- Utils ---
@@ -19,7 +19,7 @@ const { parallelMap } = require('../utils/retry');
 const { assessQuality, formatQualityLine, getConfidenceStats, THRESHOLDS } = require('../utils/quality-gate');
 const { validateAnalysis, formatSchemaLine, schemaScore, normalizeAnalysis } = require('../utils/schema-validator');
 const { calculateThinkingBudget } = require('../utils/adaptive-budget');
-const { detectBoundaryContext, sliceVttForSegment } = require('../utils/context-manager');
+const { detectBoundaryContext, sliceVttForSegment, planSegmentBatches, estimateTokens, buildProgressiveContext } = require('../utils/context-manager');
 
 // --- Modes ---
 const { identifyWeaknesses, runFocusedPass, mergeFocusedResults } = require('../modes/focused-reanalysis');
@@ -245,6 +245,215 @@ async function phaseProcessVideo(ctx, videoPath, videoIndex) {
   const segmentAnalyses = [];
   const segmentReports = []; // Quality reports for health dashboard
 
+  // ════════════════════════════════════════════════════════════
+  //  Multi-Segment Batching — pass multiple segments per call
+  //  when the context window has enough headroom.
+  // ════════════════════════════════════════════════════════════
+  const useBatching = !opts.noBatch && !opts.skipGemini && !opts.dryRun && segments.length > 1;
+  let batchedSuccessfully = false;
+
+  if (useBatching) {
+    const prevTokens = estimateTokens(buildProgressiveContext(previousAnalyses, userName) || '');
+    const { batches, batchSize, reason } = planSegmentBatches(
+      segmentMeta, contextDocs,
+      {
+        contextWindow: config.GEMINI_CONTEXT_WINDOW || 1_048_576,
+        previousAnalysesTokens: prevTokens,
+      }
+    );
+
+    if (batchSize > 1) {
+      console.log(`  ${c.cyan('⚡ Multi-segment batching:')} ${batches.length} batch(es), up to ${batchSize} segments/batch`);
+      console.log(`    ${c.dim(reason)}`);
+      console.log('');
+      batchedSuccessfully = true; // will be set false if we need to fall back
+
+      for (let bIdx = 0; bIdx < batches.length; bIdx++) {
+        if (isShuttingDown()) break;
+        const batchIndices = batches[bIdx];
+        const batchSegs = batchIndices.map(i => ({
+          segPath: segmentMeta[i].segPath,
+          segName: segmentMeta[i].segName,
+          durSec: segmentMeta[i].durSec,
+          storageUrl: segmentMeta[i].storageUrl,
+        }));
+        const batchTimes = batchIndices.map(i => ({
+          startTimeSec: segmentMeta[i].startTimeSec,
+          endTimeSec: segmentMeta[i].endTimeSec,
+        }));
+
+        const batchLabel = batchIndices.length === 1
+          ? `seg ${batchIndices[0] + 1}`
+          : `segs ${batchIndices[0] + 1}–${batchIndices[batchIndices.length - 1] + 1}`;
+        console.log(`  ${c.cyan('══')} Batch ${c.highlight(`${bIdx + 1}/${batches.length}`)} (${batchLabel}) ${c.cyan('══')}`);
+
+        // Skip batches where all segments have cached runs and user didn't force re-analyze
+        if (!forceReanalyze) {
+          const allCached = batchIndices.every(i => {
+            const prefix = `segment_${String(i).padStart(2, '0')}_`;
+            const existing = fs.readdirSync(geminiRunsDir).filter(f => f.startsWith(prefix) && f.endsWith('.json'));
+            return existing.length > 0;
+          });
+          if (allCached) {
+            // Load cached results for all segments in this batch
+            let cacheOk = true;
+            for (const i of batchIndices) {
+              const prefix = `segment_${String(i).padStart(2, '0')}_`;
+              const existing = fs.readdirSync(geminiRunsDir).filter(f => f.startsWith(prefix) && f.endsWith('.json')).sort();
+              const latestFile = existing[existing.length - 1];
+              try {
+                const cached = JSON.parse(fs.readFileSync(path.join(geminiRunsDir, latestFile), 'utf8'));
+                const analysis = normalizeAnalysis(cached.output.parsed || { rawResponse: cached.output.raw });
+                analysis._geminiMeta = {
+                  model: cached.run.model,
+                  processedAt: cached.run.timestamp,
+                  durationMs: cached.run.durationMs,
+                  tokenUsage: cached.run.tokenUsage || null,
+                  runFile: path.relative(PROJECT_ROOT, path.join(geminiRunsDir, latestFile)),
+                  parseSuccess: cached.output.parseSuccess,
+                  skipped: true,
+                };
+                if (cached.run.tokenUsage) {
+                  costTracker.addSegment(segmentMeta[i].segName, cached.run.tokenUsage, cached.run.durationMs, true);
+                }
+                const cachedQuality = assessQuality(analysis, { parseSuccess: cached.output.parseSuccess, rawLength: (cached.output.raw || '').length });
+                segmentReports.push({ segmentName: segmentMeta[i].segName, qualityReport: cachedQuality, retried: false, retryImproved: false });
+                previousAnalyses.push(analysis);
+                segmentAnalyses.push(analysis);
+
+                fileResult.segments.push({
+                  segmentFile: segmentMeta[i].segName, segmentIndex: i,
+                  storagePath: segmentMeta[i].storagePath, storageUrl: segmentMeta[i].storageUrl,
+                  duration: fmtDuration(segmentMeta[i].durSec), durationSeconds: segmentMeta[i].durSec,
+                  fileSizeMB: parseFloat(segmentMeta[i].sizeMB),
+                  geminiRunFile: path.relative(PROJECT_ROOT, path.join(geminiRunsDir, latestFile)),
+                  analysis,
+                });
+                console.log(`    ${c.success(`seg ${i + 1}: loaded from cache (${latestFile})`)}`);
+              } catch (err) {
+                console.warn(`    ${c.warn(`seg ${i + 1}: cache corrupt — will re-analyze`)}`);
+                cacheOk = false;
+                break;
+              }
+            }
+            if (cacheOk) {
+              console.log('');
+              continue; // skip to next batch
+            }
+          }
+        }
+
+        // Verify all segments in batch
+        const invalidInBatch = batchIndices.filter(i => !verifySegment(segmentMeta[i].segPath));
+        if (invalidInBatch.length > 0) {
+          console.warn(`    ${c.warn(`${invalidInBatch.length} corrupt segment(s) in batch — falling back to single-segment mode`)}`);
+          batchedSuccessfully = false;
+          break;
+        }
+
+        try {
+          const batchRun = await processSegmentBatch(
+            ai, batchSegs,
+            `${callName}_${baseName}_batch${bIdx}`,
+            contextDocs, previousAnalyses, userName, PKG_ROOT,
+            {
+              segmentIndices: batchIndices,
+              totalSegments: segments.length,
+              segmentTimes: batchTimes,
+              thinkingBudget: opts.thinkingBudget || 24576,
+              noStorageUrl: !!opts.noStorageUrl,
+            }
+          );
+
+          // Save batch run file
+          const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+          const batchRunFileName = `batch_${bIdx}_segs_${batchIndices[0]}-${batchIndices[batchIndices.length - 1]}_${ts}.json`;
+          const batchRunPath = path.join(geminiRunsDir, batchRunFileName);
+          fs.writeFileSync(batchRunPath, JSON.stringify(batchRun, null, 2), 'utf8');
+
+          const analysis = normalizeAnalysis(batchRun.output.parsed || { rawResponse: batchRun.output.raw });
+          analysis._geminiMeta = {
+            model: batchRun.run.model,
+            processedAt: batchRun.run.timestamp,
+            durationMs: batchRun.run.durationMs,
+            tokenUsage: batchRun.run.tokenUsage || null,
+            runFile: path.relative(PROJECT_ROOT, batchRunPath),
+            parseSuccess: batchRun.output.parseSuccess,
+            batchMode: true,
+            segmentIndices: batchIndices,
+          };
+
+          // Track cost
+          costTracker.addSegment(`batch_${bIdx}`, batchRun.run.tokenUsage, batchRun.run.durationMs, false);
+
+          // Quality gate
+          const qualityReport = assessQuality(analysis, {
+            parseSuccess: batchRun.output.parseSuccess,
+            rawLength: (batchRun.output.raw || '').length,
+          });
+          console.log(formatQualityLine(qualityReport, `batch ${bIdx + 1}`));
+
+          // Schema validation
+          const schemaReport = validateAnalysis(analysis, 'segment');
+          console.log(formatSchemaLine(schemaReport));
+
+          // Assign batch analysis to each segment in the batch
+          for (const i of batchIndices) {
+            segmentReports.push({ segmentName: segmentMeta[i].segName, qualityReport, retried: false, retryImproved: false });
+            fileResult.segments.push({
+              segmentFile: segmentMeta[i].segName, segmentIndex: i,
+              storagePath: segmentMeta[i].storagePath, storageUrl: segmentMeta[i].storageUrl,
+              duration: fmtDuration(segmentMeta[i].durSec), durationSeconds: segmentMeta[i].durSec,
+              fileSizeMB: parseFloat(segmentMeta[i].sizeMB),
+              geminiRunFile: path.relative(PROJECT_ROOT, batchRunPath),
+              analysis,
+            });
+          }
+
+          // Source-segment tagging
+          const tagSeg = (arr, segNum) => (arr || []).forEach(item => { if (!item.source_segment) item.source_segment = segNum; });
+          for (const i of batchIndices) {
+            tagSeg(analysis.action_items, i + 1);
+            tagSeg(analysis.change_requests, i + 1);
+            tagSeg(analysis.blockers, i + 1);
+            tagSeg(analysis.scope_changes, i + 1);
+          }
+
+          previousAnalyses.push(analysis);
+          segmentAnalyses.push(analysis);
+
+          // Cleanup Gemini File API uploads
+          if (batchRun._geminiFileNames && batchRun._geminiFileNames.length > 0 && ai) {
+            cleanupGeminiFiles(ai, batchRun._geminiFileNames).catch(() => {});
+          }
+
+          const dur = (batchRun.run.durationMs / 1000).toFixed(1);
+          console.log(`    ${c.success(`Batch analysis complete (${dur}s, ${batchIndices.length} segments)`)}`);
+          progress.markAnalyzed(`${baseName}_batch${bIdx}`, path.relative(PROJECT_ROOT, batchRunPath));
+        } catch (err) {
+          console.error(`    ${c.error(`Batch analysis failed: ${err.message}`)}`);
+          console.warn(`    ${c.warn('Falling back to single-segment processing for remaining segments')}`);
+          console.warn(`    ${c.dim('Tip: use --no-batch to disable batching if this persists.')}`);
+          log.error(`Batch ${bIdx} failed — ${err.message}`);
+          batchedSuccessfully = false;
+          break;
+        }
+        console.log('');
+      }
+
+      if (batchedSuccessfully) {
+        const totalSegs = batches.reduce((s, b) => s + b.length, 0);
+        console.log(`  ${c.success(`All ${batches.length} batch(es) complete: ${totalSegs} segments analyzed`)}`);
+        console.log('');
+      }
+    }
+  }
+
+  // ════════════════════════════════════════════════════════════
+  //  Single-Segment Processing (original path / fallback)
+  // ════════════════════════════════════════════════════════════
+  if (!batchedSuccessfully) {
+
   for (let j = 0; j < segments.length; j++) {
     if (isShuttingDown()) break;
 
@@ -647,6 +856,8 @@ async function phaseProcessVideo(ctx, videoPath, videoIndex) {
     console.log('');
   }
 
+  } // end if (!batchedSuccessfully) — single-segment fallback
+
   // Compute totals for this file
   fileResult.compressedTotalMB = fileResult.segments
     .reduce((sum, s) => sum + s.fileSizeMB, 0).toFixed(2);

package/src/phases/summary.js

@@ -40,11 +40,11 @@ function phaseSummary(ctx, results, { jsonPath, mdPath, runTs, compilationRun })
   if (cost.totalTokens > 0) {
     console.log('');
     console.log(`  ${c.heading(`Cost estimate (${config.GEMINI_MODEL}):`)}`);
-    console.log(`    Input tokens  : ${c.yellow(cost.inputTokens.toLocaleString())} ${c.dim(`($${cost.inputCost.toFixed(4)})`)}`);
-    console.log(`    Output tokens : ${c.yellow(cost.outputTokens.toLocaleString())} ${c.dim(`($${cost.outputCost.toFixed(4)})`)}`);
-    console.log(`    Thinking tokens: ${c.yellow(cost.thinkingTokens.toLocaleString())} ${c.dim(`($${cost.thinkingCost.toFixed(4)})`)}`);
-    console.log(`    Total         : ${c.highlight(cost.totalTokens.toLocaleString() + ' tokens')} | ${c.green('$' + cost.totalCost.toFixed(4))}`);
-    console.log(`    AI time       : ${c.yellow((cost.totalDurationMs / 1000).toFixed(1) + 's')}`);
+    console.log(`    Input:    ${c.yellow(cost.inputTokens.toLocaleString())} ${c.dim(`($${cost.inputCost.toFixed(4)})`)}`);
+    console.log(`    Output:   ${c.yellow(cost.outputTokens.toLocaleString())} ${c.dim(`($${cost.outputCost.toFixed(4)})`)}`);
+    console.log(`    Thinking: ${c.yellow(cost.thinkingTokens.toLocaleString())} ${c.dim(`($${cost.thinkingCost.toFixed(4)})`)}`);
+    console.log(`    Total:    ${c.highlight(cost.totalTokens.toLocaleString() + ' tokens')} | ${c.green('$' + cost.totalCost.toFixed(4))}`);
+    console.log(`    AI time:  ${c.yellow((cost.totalDurationMs / 1000).toFixed(1) + 's')}`);
   }
 
   if (firebaseReady && !opts.skipUpload) {

package/src/pipeline.js

@@ -151,7 +151,7 @@ async function run() {
     files: [],
   };
 
-  fullCtx.progress.setPhase('compress');
+  fullCtx.progress.setPhase('analyze');
   bar.setPhase('analyze', mediaFiles.length);
   if (log && log.phaseStart) log.phaseStart('process_videos');
 
@@ -702,6 +702,7 @@ async function runDynamic(initCtx) {
     });
   } catch (err) {
     console.error(`  ${c.error(`Topic planning failed: ${err.message}`)}`);
+    console.error(`    ${c.dim('Tip: check your Gemini API key, or try a simpler --request.')}`);
     log.error(`Dynamic topic planning failed: ${err.message}`);    bar.finish();    initCtx.progress.cleanup();
     log.close();
     return;

package/src/renderers/docx.js

@@ -13,7 +13,7 @@
 'use strict';
 
 const {
-  stripParens, clusterNames, resolve,
+  clusterNames, resolve,
   dedupBy,
 } = require('./shared');
 

package/src/renderers/html.js

@@ -13,9 +13,8 @@
 'use strict';
 
 const {
-  stripParens, normalizeKey, clusterNames, resolve,
+  clusterNames, resolve,
   dedupBy, normalizeDesc, dedupByDesc,
-  fmtTs, priBadge, confBadge, confBadgeFull,
   escHtml,
 } = require('./shared');
 

package/src/services/gemini.js

@@ -26,7 +26,9 @@ const {
   sliceVttForSegment,
   buildProgressiveContext,
   buildSegmentFocus,
+  buildBatchSegmentFocus,
   estimateTokens,
+  estimateDocTokens,
 } = require('../utils/context-manager');
 const { formatHMS } = require('../utils/format');
 const { withRetry } = require('../utils/retry');
@@ -564,6 +566,230 @@ async function processWithGemini(ai, filePath, displayName, contextDocs = [], pr
   };
 }
 
+// ======================== MULTI-SEGMENT BATCH ANALYSIS ========================
+
+/**
+ * Process multiple consecutive video segments in a single Gemini call.
+ * This takes advantage of unused context-window headroom (especially after
+ * deep summary) to reduce the number of API calls and give the model a
+ * more holistic view of the meeting.
+ *
+ * @param {object}  ai           – Gemini AI instance
+ * @param {Array<{ segPath: string, segName: string, durSec: number, storageUrl?: string }>} batchSegments
+ * @param {string}  displayName  – label for logging (e.g. "call1_video_batch0-2")
+ * @param {Array}   contextDocs  – prepared context docs
+ * @param {Array}   previousAnalyses – analyses from earlier batches
+ * @param {string}  userName
+ * @param {string}  scriptDir    – where prompt.json lives
+ * @param {object}  batchOpts
+ * @param {number[]} batchOpts.segmentIndices      – 0-based global indices of the segments
+ * @param {number}   batchOpts.totalSegments       – total segment count for the whole file
+ * @param {Array<{startTimeSec: number, endTimeSec: number}>} batchOpts.segmentTimes
+ * @param {number}  [batchOpts.thinkingBudget=24576]
+ * @param {boolean} [batchOpts.noStorageUrl=false]
+ * @returns {Promise<object>} Run record (same shape as processWithGemini)
+ */
+async function processSegmentBatch(ai, batchSegments, displayName, contextDocs, previousAnalyses, userName, scriptDir, batchOpts = {}) {
+  const {
+    segmentIndices = batchSegments.map((_, i) => i),
+    totalSegments = batchSegments.length,
+    segmentTimes = [],
+    thinkingBudget = 24576,
+    noStorageUrl = false,
+  } = batchOpts;
+
+  const { systemInstruction, promptText } = loadPrompt(scriptDir);
+
+  const EXTERNAL_URL_MAX_BYTES = 20 * 1024 * 1024;
+
+  // ── Upload / reference all video files ─────────────────────────────────────
+  const fileRefs = []; // { uri, mimeType, name, usedExternalUrl }
+
+  for (const seg of batchSegments) {
+    const fileSizeBytes = fs.existsSync(seg.segPath) ? fs.statSync(seg.segPath).size : 0;
+
+    if (!noStorageUrl && seg.storageUrl && fileSizeBytes <= EXTERNAL_URL_MAX_BYTES) {
+      fileRefs.push({ uri: seg.storageUrl, mimeType: 'video/mp4', name: null, usedExternalUrl: true });
+      console.log(`    ${seg.segName}: using Storage URL`);
+    } else {
+      // Upload via Gemini File API
+      console.log(`    ${seg.segName}: uploading to Gemini File API...`);
+      let uploaded = await withRetry(
+        () => ai.files.upload({
+          file: seg.segPath,
+          config: { mimeType: 'video/mp4', displayName: `${displayName}_${seg.segName}` },
+        }),
+        { label: `Gemini upload (${seg.segName})`, maxRetries: 3 }
+      );
+
+      let waited = 0;
+      const pollStart = Date.now();
+      while (uploaded.state === 'PROCESSING') {
+        if (Date.now() - pollStart > GEMINI_POLL_TIMEOUT_MS) {
+          throw new Error(`File "${seg.segName}" still processing after ${(GEMINI_POLL_TIMEOUT_MS / 1000).toFixed(0)}s`);
+        }
+        process.stdout.write(`    Processing ${seg.segName}${'.'.repeat((waited % 3) + 1)}   \r`);
+        await new Promise(r => setTimeout(r, 5000));
+        waited++;
+        uploaded = await withRetry(
+          () => ai.files.get({ name: uploaded.name }),
+          { label: 'Gemini file status', maxRetries: 2, baseDelay: 1000 }
+        );
+      }
+      if (uploaded.state === 'FAILED') {
+        throw new Error(`Gemini processing failed for ${seg.segName}`);
+      }
+      fileRefs.push({ uri: uploaded.uri, mimeType: uploaded.mimeType || 'video/mp4', name: uploaded.name, usedExternalUrl: false });
+      console.log(`    ${seg.segName}: upload complete`);
+    }
+  }
+
+  // ── Build content parts ────────────────────────────────────────────────────
+  const contentParts = [];
+
+  // Video files — one fileData part per segment, in order
+  for (let i = 0; i < fileRefs.length; i++) {
+    const ref = fileRefs[i];
+    const segIdx = segmentIndices[i];
+    contentParts.push({ text: `=== VIDEO SEGMENT ${segIdx + 1} of ${totalSegments} ===` });
+    contentParts.push({ fileData: { mimeType: ref.mimeType, fileUri: ref.uri } });
+  }
+
+  // Context docs — same budget logic as single-segment but account for multiple videos
+  const videoTokenEstimate = batchSegments.reduce((sum, s) => sum + Math.ceil((s.durSec || 280) * 300), 0);
+  const prevContextEstimate = estimateTokens(buildProgressiveContext(previousAnalyses, userName) || '');
+  const docBudget = Math.max(50000, config.GEMINI_CONTEXT_WINDOW - videoTokenEstimate - 120000 - prevContextEstimate);
+  console.log(`    Doc budget: ${(docBudget / 1000).toFixed(0)}K tokens for ${contextDocs.length} doc(s)`);
+
+  const { selected: selectedDocs, excluded } = selectDocsByBudget(contextDocs, docBudget, { segmentIndex: segmentIndices[0] });
+  if (excluded.length > 0) {
+    console.log(`    Context: ${selectedDocs.length} docs included, ${excluded.length} excluded`);
+  }
+
+  // Attach selected docs with VTT time-slicing across the batch range
+  const batchStartSec = segmentTimes.length > 0 ? segmentTimes[0].startTimeSec : null;
+  const batchEndSec = segmentTimes.length > 0 ? segmentTimes[segmentTimes.length - 1].endTimeSec : null;
+
+  for (const doc of selectedDocs) {
+    if (doc.type === 'inlineText') {
+      let content = doc.content;
+      const isVtt = doc.fileName.toLowerCase().endsWith('.vtt') || doc.fileName.toLowerCase().endsWith('.srt');
+      if (isVtt && batchStartSec != null && batchEndSec != null) {
+        content = sliceVttForSegment(content, batchStartSec, batchEndSec);
+        console.log(`    VTT sliced to ${formatHMS(batchStartSec)}–${formatHMS(batchEndSec)} range`);
+      }
+      contentParts.push({ text: `=== Document: ${doc.fileName} ===\n${content}` });
+    } else if (doc.type === 'fileData') {
+      contentParts.push({ fileData: { mimeType: doc.mimeType, fileUri: doc.fileUri } });
+    }
+  }
+
+  // Bridge text
+  const bridgeText = buildDocBridgeText(selectedDocs);
+  if (bridgeText) contentParts.push({ text: bridgeText });
+
+  // Progressive context from previous batches
+  const prevText = buildProgressiveContext(previousAnalyses, userName);
+  if (prevText) contentParts.push({ text: prevText });
+
+  // Multi-segment focus instructions
+  const focusText = buildBatchSegmentFocus(segmentIndices, totalSegments, previousAnalyses, userName);
+  contentParts.push({ text: focusText });
+
+  // User identity
+  if (userName) {
+    contentParts.push({
+      text: `CURRENT USER: "${userName}". Tag tasks assigned to or owned by "${userName}". Populate the "your_tasks" section.`
+    });
+  }
+
+  contentParts.push({ text: promptText });
+
+  // ── Send request ──────────────────────────────────────────────────────────
+  console.log(`    Analyzing batch [segments ${segmentIndices[0] + 1}–${segmentIndices[segmentIndices.length - 1] + 1}] with ${config.GEMINI_MODEL}...`);
+
+  const requestPayload = {
+    model: config.GEMINI_MODEL,
+    contents: [{ role: 'user', parts: contentParts }],
+    config: {
+      systemInstruction,
+      maxOutputTokens: 65536,
+      temperature: 0,
+    },
+  };
+
+  const t0 = Date.now();
+  const response = await withRetry(
+    () => ai.models.generateContent(requestPayload),
+    { label: `Gemini batch analysis (${displayName})`, maxRetries: 2, baseDelay: 5000 }
+  );
+  const durationMs = Date.now() - t0;
+
+  const rawText = response.text;
+
+  // Token usage
+  const usage = response.usageMetadata || {};
+  const tokenUsage = {
+    inputTokens: usage.promptTokenCount || 0,
+    outputTokens: usage.candidatesTokenCount || 0,
+    totalTokens: usage.totalTokenCount || 0,
+    thoughtTokens: usage.thoughtsTokenCount || 0,
+  };
+  const contextRemaining = config.GEMINI_CONTEXT_WINDOW - tokenUsage.inputTokens;
+  const contextUsedPct = ((tokenUsage.inputTokens / config.GEMINI_CONTEXT_WINDOW) * 100).toFixed(1);
+  tokenUsage.contextWindow = config.GEMINI_CONTEXT_WINDOW;
+  tokenUsage.contextRemaining = contextRemaining;
+  tokenUsage.contextUsedPct = parseFloat(contextUsedPct);
+
+  console.log(`    Tokens — input: ${tokenUsage.inputTokens.toLocaleString()} | output: ${tokenUsage.outputTokens.toLocaleString()} | thinking: ${tokenUsage.thoughtTokens.toLocaleString()}`);
+  console.log(`    Context — used: ${contextUsedPct}% | remaining: ${contextRemaining.toLocaleString()} tokens`);
+
+  // Parse
+  const parsed = extractJson(rawText);
+
+  // Input summary
+  const inputSummary = contentParts.map(part => {
+    if (part.fileData) return { type: 'fileData', mimeType: part.fileData.mimeType, fileUri: part.fileData.fileUri };
+    if (part.text) return { type: 'text', chars: part.text.length, preview: part.text.substring(0, 300) };
+    return part;
+  });
+
+  // ── Cleanup Gemini File API uploads ────────────────────────────────────────
+  const geminiFileNames = fileRefs.filter(r => r.name && !r.usedExternalUrl).map(r => r.name);
+
+  return {
+    run: {
+      model: config.GEMINI_MODEL,
+      displayName,
+      userName,
+      timestamp: new Date().toISOString(),
+      durationMs,
+      tokenUsage,
+      systemInstruction,
+      batchMode: true,
+      segmentIndices,
+    },
+    input: {
+      videoFiles: fileRefs.map((ref, i) => ({
+        mimeType: ref.mimeType,
+        fileUri: ref.uri,
+        segmentName: batchSegments[i].segName,
+        usedExternalUrl: ref.usedExternalUrl,
+      })),
+      contextDocuments: contextDocs.map(d => ({ fileName: d.fileName, type: d.type })),
+      previousSegmentCount: previousAnalyses.length,
+      parts: inputSummary,
+      promptText,
+    },
+    output: {
+      raw: rawText,
+      parsed,
+      parseSuccess: parsed !== null,
+    },
+    _geminiFileNames: geminiFileNames,
+  };
+}
+
 // ======================== FINAL COMPILATION ========================
 
 /**
@@ -945,7 +1171,12 @@ console.log(`    ${c.success(`Summary: ${summary.length.toLocaleString()} chars
  */
 async function cleanupGeminiFiles(ai, geminiFileName, contextDocs = []) {
   const toDelete = [];
-  if (geminiFileName) toDelete.push(geminiFileName);
+  // Accept a single name string or an array of names
+  if (Array.isArray(geminiFileName)) {
+    toDelete.push(...geminiFileName.filter(Boolean));
+  } else if (geminiFileName) {
+    toDelete.push(geminiFileName);
+  }
   for (const doc of contextDocs) {
     if (doc.type === 'fileData' && doc.geminiFileName) {
       toDelete.push(doc.geminiFileName);
@@ -970,6 +1201,7 @@ module.exports = {
   prepareDocsForGemini,
   loadPrompt,
   processWithGemini,
+  processSegmentBatch,
   compileFinalResult,
   buildDocBridgeText,
   analyzeVideoForContext,

package/src/services/video.js

@@ -237,7 +237,7 @@ function compressAndSegment(inputFile, outputDir, { segTime = SEG_TIME, speed =
     const fbResult = spawnSync(getFFmpeg(), fbArgs, { stdio: 'inherit' });
     if (fbResult.status === 0 && verifySegment(fallbackPath)) {
       // Remove all corrupt segments and replace with the fallback
-      for (const seg of corrupt) { try { fs.unlinkSync(seg); } catch {} }
+      for (const seg of corrupt) { try { fs.unlinkSync(seg); } catch { /* best-effort cleanup */ } }
       // If this was the only segment, just rename it
       if (segments.length === 1) {
         const dest = path.join(outputDir, 'segment_00.mp4');
@@ -261,8 +261,8 @@ function compressAndSegment(inputFile, outputDir, { segTime = SEG_TIME, speed =
         for (const f of reSegs) {
           fs.renameSync(path.join(reSegDir, f), path.join(outputDir, f));
         }
-        try { fs.rmSync(reSegDir, { recursive: true }); } catch {}
-        try { fs.unlinkSync(fallbackPath); } catch {}
+        try { fs.rmSync(reSegDir, { recursive: true }); } catch { /* best-effort cleanup */ }
+        try { fs.unlinkSync(fallbackPath); } catch { /* best-effort cleanup */ }
         // Re-collect
         segments = fs.readdirSync(outputDir)
           .filter(f => f.startsWith('segment_') && f.endsWith('.mp4'))
@@ -272,13 +272,13 @@ function compressAndSegment(inputFile, outputDir, { segTime = SEG_TIME, speed =
       }
     } else {
       console.error(`  ${c.error('Fallback re-encode also failed')}`);
-      try { fs.unlinkSync(fallbackPath); } catch {}
+      try { fs.unlinkSync(fallbackPath); } catch { /* best-effort cleanup */ }
     }
   } else if (corrupt.length > 0 && !needsSegmentation) {
     // Single-output mode also failed — try once more without segment muxer flags
     console.log(`  Retrying single-output compression...`);
     const retryPath = path.join(outputDir, 'segment_00.mp4');
-    try { fs.unlinkSync(retryPath); } catch {}
+    try { fs.unlinkSync(retryPath); } catch { /* best-effort cleanup */ }
     const retryArgs = [
       '-y',
       '-i', inputFile,
@@ -373,7 +373,7 @@ function compressAndSegmentAudio(inputFile, outputDir, { segTime = SEG_TIME, spe
     const fbArgs = ['-y', '-i', inputFile, ...encodingArgs, fallbackPath];
     const fbResult = spawnSync(getFFmpeg(), fbArgs, { stdio: 'inherit' });
     if (fbResult.status === 0 && verifySegment(fallbackPath)) {
-      for (const seg of corrupt) { try { fs.unlinkSync(seg); } catch {} }
+      for (const seg of corrupt) { try { fs.unlinkSync(seg); } catch { /* best-effort cleanup */ } }
       if (segments.length === 1) {
         const dest = path.join(outputDir, 'segment_00.m4a');
         fs.renameSync(fallbackPath, dest);
@@ -394,8 +394,8 @@ function compressAndSegmentAudio(inputFile, outputDir, { segTime = SEG_TIME, spe
         for (const f of reSegs) {
           fs.renameSync(path.join(reSegDir, f), path.join(outputDir, f));
         }
-        try { fs.rmSync(reSegDir, { recursive: true }); } catch {}
-        try { fs.unlinkSync(fallbackPath); } catch {}
+        try { fs.rmSync(reSegDir, { recursive: true }); } catch { /* best-effort cleanup */ }
+        try { fs.unlinkSync(fallbackPath); } catch { /* best-effort cleanup */ }
         segments = fs.readdirSync(outputDir)
           .filter(f => f.startsWith('segment_') && (f.endsWith('.m4a') || f.endsWith('.mp4')))
           .sort()
@@ -404,7 +404,7 @@ function compressAndSegmentAudio(inputFile, outputDir, { segTime = SEG_TIME, spe
       }
     } else {
       console.error(`  ${c.error('Fallback audio re-encode failed')}`);
-      try { fs.unlinkSync(fallbackPath); } catch {}
+      try { fs.unlinkSync(fallbackPath); } catch { /* best-effort cleanup */ }
     }
   }
 

package/src/utils/cli.js

@@ -38,7 +38,7 @@ function parseArgs(argv) {
     'resume', 'reanalyze', 'dry-run',
     'dynamic', 'deep-dive', 'deep-summary', 'update-progress',
     'no-focused-pass', 'no-learning', 'no-diff',
-    'no-html',
+    'no-html', 'no-batch',
   ]);
 
   for (let i = 0; i < argv.length; i++) {
@@ -329,6 +329,7 @@ ${f('--compilation-thinking-budget <n>', 'Thinking tokens for compilation (defau
 ${f('--no-focused-pass', 'Disable focused re-analysis')}
 ${f('--no-learning', 'Disable learning loop')}
 ${f('--no-diff', 'Disable diff comparison')}
+${f('--no-batch', 'Disable multi-segment batching')}
 ${f('--no-html', 'Skip HTML output (Markdown only)')}
 ${f('--log-level <level>', 'debug, info, warn, error (default: info)')}
 

package/src/utils/context-manager.js

@@ -511,12 +511,164 @@ function detectBoundaryContext(vttContent, segmentStartSec, segmentEndSec, segme
   return `SEGMENT BOUNDARY CONTEXT:\n${notes.map(n => `• ${n}`).join('\n')}\n→ Pay special attention to continuity — pick up where the previous segment left off. Do NOT re-extract items that were already captured in previous segments unless their status changed.`;
 }
 
+// ════════════════════════════════════════════════════════════
+//  Multi-Segment Batch Planning
+// ════════════════════════════════════════════════════════════
+
+/** Tokens per second of video at standard resolution (Google docs: ~300 tok/s). */
+const VIDEO_TOKENS_PER_SEC = 300;
+
+/**
+ * Plan how to group consecutive segments into batches that fit the context window.
+ *
+ * Token budget breakdown:
+ *   contextWindow
+ *   − promptOverhead (system instruction + prompt template + output buffer + safety)
+ *   − docTokens (context documents, already accounting for deep-summary condensation)
+ *   − prevContextTokens (progressive previous-analysis context, grows with batches)
+ *   = available for video segments
+ *
+ * Each segment costs ~300 tok/sec × durationSec.
+ *
+ * @param {Array<{durSec: number}>} segmentMetas  – per-segment metadata with durations
+ * @param {Array}  contextDocs      – prepared context docs (after deep-summary, if any)
+ * @param {object} opts
+ * @param {number} opts.contextWindow        – model context window (default: 1_048_576)
+ * @param {number} [opts.promptOverhead=120000] – tokens reserved for prompt/output/thinking
+ * @param {number} [opts.previousAnalysesTokens=0] – current progressive context size
+ * @param {number} [opts.maxBatchSize=8]    – hard cap on segments per batch
+ * @returns {{ batches: number[][], batchSize: number, reason: string }}
+ */
+function planSegmentBatches(segmentMetas, contextDocs, opts = {}) {
+  const {
+    contextWindow = 1_048_576,
+    promptOverhead = 120_000,
+    previousAnalysesTokens = 0,
+    maxBatchSize = 8,
+  } = opts;
+
+  // Total doc tokens
+  const docTokens = contextDocs.reduce((sum, d) => sum + estimateDocTokens(d), 0);
+
+  // Available tokens for video
+  const available = contextWindow - promptOverhead - docTokens - previousAnalysesTokens;
+
+  if (available <= 0) {
+    return { batches: segmentMetas.map((_, i) => [i]), batchSize: 1, reason: 'no headroom — 1 segment per call' };
+  }
+
+  // Greedy batching: pack consecutive segments while they fit
+  const batches = [];
+  let batch = [];
+  let batchTokens = 0;
+
+  for (let i = 0; i < segmentMetas.length; i++) {
+    const segTokens = Math.ceil((segmentMetas[i].durSec || 280) * VIDEO_TOKENS_PER_SEC);
+
+    if (batch.length > 0 && (batchTokens + segTokens > available || batch.length >= maxBatchSize)) {
+      batches.push(batch);
+      batch = [];
+      batchTokens = 0;
+    }
+
+    batch.push(i);
+    batchTokens += segTokens;
+  }
+  if (batch.length > 0) batches.push(batch);
+
+  // Effective max batch size across all batches
+  const effectiveBatchSize = Math.max(...batches.map(b => b.length));
+
+  const reason = effectiveBatchSize > 1
+    ? `${(available / 1000).toFixed(0)}K tokens available → up to ${effectiveBatchSize} segments/batch`
+    : 'segments too large for batching — 1 per call';
+
+  return { batches, batchSize: effectiveBatchSize, reason };
+}
+
+/**
+ * Build a segment focus block that covers a RANGE of segments in a batch.
+ *
+ * @param {number[]} segmentIndices  – indices of segments in this batch (0-based)
+ * @param {number}   totalSegments   – total segment count across the whole file
+ * @param {Array}    previousAnalyses – all analyses from prior batches
+ * @param {string}   userName
+ * @returns {string}
+ */
+function buildBatchSegmentFocus(segmentIndices, totalSegments, previousAnalyses, userName) {
+  const first = segmentIndices[0];
+  const last = segmentIndices[segmentIndices.length - 1];
+  const isRange = segmentIndices.length > 1;
+  const lines = [];
+
+  const posLabel = first === 0 ? 'FIRST' :
+    last === totalSegments - 1 ? 'LAST' : 'MIDDLE';
+
+  if (isRange) {
+    lines.push(`MULTI-SEGMENT BATCH: segments ${first + 1}–${last + 1} of ${totalSegments} (${posLabel} — analyzing ${segmentIndices.length} consecutive segments together)`);
+    lines.push(`You are watching ${segmentIndices.length} video segments in sequence. Each segment is a separate video file provided in order.`);
+    lines.push(`IMPORTANT: Tag every extracted item with its correct source_segment number (${first + 1}–${last + 1}) based on which video it appears in.`);
+  } else {
+    lines.push(`SEGMENT POSITION: ${first + 1} of ${totalSegments} (${
+      first === 0 ? 'FIRST — establish baseline' :
+      first === totalSegments - 1 ? 'LAST — capture final decisions & wrap-up tasks' :
+      'MIDDLE — track changes & new items'
+    })`);
+  }
+
+  if (first === 0) {
+    lines.push('FOCUS: Identify ALL tickets, participants, and initial task assignments.');
+    lines.push('Establish the baseline state for each ticket. Cross-reference everything against task documents.');
+    lines.push(`Pay special attention to tasks assigned to "${userName}".`);
+  } else {
+    // Build awareness of what's been found
+    const allTicketIds = new Set();
+    const allCrIds = new Set();
+    const allActionIds = new Set();
+    const allBlockerIds = new Set();
+
+    for (const prev of previousAnalyses) {
+      (prev.tickets || []).forEach(t => allTicketIds.add(t.ticket_id));
+      (prev.change_requests || []).forEach(cr => allCrIds.add(cr.id));
+      (prev.action_items || []).forEach(ai => allActionIds.add(ai.id));
+      (prev.blockers || []).forEach(b => allBlockerIds.add(b.id));
+    }
+
+    lines.push('ALREADY FOUND in previous segments:');
+    if (allTicketIds.size > 0) lines.push(`  Tickets: ${[...allTicketIds].join(', ')}`);
+    if (allCrIds.size > 0) lines.push(`  CRs: ${[...allCrIds].slice(0, 20).join(', ')}${allCrIds.size > 20 ? ` (+${allCrIds.size - 20} more)` : ''}`);
+    if (allActionIds.size > 0) lines.push(`  Actions: ${[...allActionIds].join(', ')}`);
+    if (allBlockerIds.size > 0) lines.push(`  Blockers: ${[...allBlockerIds].join(', ')}`);
+
+    lines.push('');
+    lines.push('FOCUS for this batch:');
+    lines.push('1. DETECT NEW tickets, CRs, action items, blockers not yet found');
+    lines.push('2. TRACK STATE CHANGES to already-known items within and across the segments');
+    lines.push('3. CAPTURE any tasks assigned, re-assigned, or completed');
+    lines.push(`4. UPDATE ${userName}'s task list — any new assignments, completions, or blockers`);
+
+    if (last === totalSegments - 1) {
+      lines.push('');
+      lines.push('LAST SEGMENT SPECIAL:');
+      lines.push('- Capture all FINAL DECISIONS and wrap-up action items');
+      lines.push('- Note any "next steps" or "follow-up" items mentioned');
+      lines.push('- Identify items that were discussed but NOT resolved');
+    }
+  }
+
+  return lines.join('\n');
+}
+
 module.exports = {
   estimateTokens,
+  estimateDocTokens,
   selectDocsByBudget,
   sliceVttForSegment,
   buildProgressiveContext,
   buildSegmentFocus,
+  buildBatchSegmentFocus,
   detectBoundaryContext,
+  planSegmentBatches,
   VTT_FALLBACK_MAX_CHARS,
+  VIDEO_TOKENS_PER_SEC,
 };

package/src/utils/diff-engine.js

@@ -238,10 +238,10 @@ function renderDiffMarkdown(diff) {
   for (const { name, d } of categories) {
     const a = d.added?.length || 0;
     const r = d.removed?.length || 0;
-    const c = d.changed?.length || 0;
+    const ch = d.changed?.length || 0;
     const u = d.unchanged?.length || 0;
-    if (a + r + c > 0) {
-      ln(`| ${name} | ${a > 0 ? `+${a}` : '-'} | ${r > 0 ? `-${r}` : '-'} | ${c > 0 ? `~${c}` : '-'} | ${u} |`);
+    if (a + r + ch > 0) {
+      ln(`| ${name} | ${a > 0 ? `+${a}` : '-'} | ${r > 0 ? `-${r}` : '-'} | ${ch > 0 ? `~${ch}` : '-'} | ${u} |`);
     }
   }
   ln('');
@@ -293,10 +293,10 @@ function renderDiffMarkdown(diff) {
   if (allChanged.length > 0) {
     ln('### 🔀 Changed Items');
     ln('');
-    for (const c of allChanged) {
-      const title = c.item.title || c.item.description || c.item.ticket_id || c.id;
-      ln(`- **[${c.type}]** ${c.id}: ${title}`);
-      for (const ch of c.changes) {
+    for (const change of allChanged) {
+      const title = change.item.title || change.item.description || change.item.ticket_id || change.id;
+      ln(`- **[${change.type}]** ${change.id}: ${title}`);
+      for (const ch of change.changes) {
         ln(`  - \`${ch.field}\`: ${ch.from || '_empty_'} → **${ch.to || '_empty_'}**`);
       }
     }

package/src/utils/interactive.js

@@ -34,6 +34,31 @@ const CR   = '\r';
 
 // ── Render helpers ────────────────────────────────────────────────────────────
 
+/**
+ * Truncate a string that may contain ANSI escape codes to fit within
+ * `maxCols` visible characters.  Preserves ANSI sequences so colours are
+ * not broken, and appends '…' when truncation occurs.
+ */
+function fitToWidth(str, maxCols) {
+  if (!maxCols || maxCols <= 0) return str;
+  const visible = strip(str);
+  if (visible.length <= maxCols) return str;
+
+  let visCount = 0;
+  let i = 0;
+  const target = maxCols - 1; // leave room for '…'
+  while (i < str.length && visCount < target) {
+    if (str[i] === '\x1b') {
+      // Skip full ANSI sequence: ESC [ ... m
+      const end = str.indexOf('m', i);
+      if (end !== -1) { i = end + 1; continue; }
+    }
+    visCount++;
+    i++;
+  }
+  return str.slice(0, i) + '\x1b[0m…';
+}
+
 /**
  * Build display strings for each item.
  *
@@ -66,11 +91,14 @@ function renderList(items, cursor, selected, multi = false) {
 /**
  * Write an array of strings to stdout, one per line.
  * Each line is preceded by CR + CLEAR_LINE so the entire row is wiped first.
+ * Lines are truncated to terminal width to prevent wrapping (which breaks
+ * cursor-UP repositioning on redraw).
  */
 function writeLines(lines) {
+  const cols = process.stdout.columns || 80;
   for (let i = 0; i < lines.length; i++) {
     if (i > 0) process.stdout.write('\n');
-    process.stdout.write(`${CR}${CLEAR_LINE}${lines[i]}`);
+    process.stdout.write(`${CR}${CLEAR_LINE}${fitToWidth(lines[i], cols - 1)}`);
   }
 }
 
@@ -89,7 +117,7 @@ function decodeKey(buf) {
   }
   if (buf[0] === 0x0d || buf[0] === 0x0a) return 'enter';
   if (buf[0] === 0x20) return 'space';
-  if (buf[0] === 0x03) return 'escape';
+  if (buf[0] === 0x03) return 'ctrl-c';
   if (buf[0] === 0x61 || buf[0] === 0x41) return 'a';
   return null;
 }
@@ -107,6 +135,10 @@ function decodeKey(buf) {
  * @returns {Promise<{index: number, value: any}>}
  */
 function selectOne({ title, items, default: defaultIdx = 0, footer }) {
+  if (!items || items.length === 0) {
+    return Promise.resolve({ index: -1, value: undefined });
+  }
+
   if (!process.stdin.isTTY) {
     return _fallbackSelectOne({ title, items, default: defaultIdx });
   }
@@ -136,8 +168,9 @@ function selectOne({ title, items, default: defaultIdx = 0, footer }) {
       const lines = renderList(items, cursor);
       writeLines(lines);
       if (hasFooter) {
+        const cols = process.stdout.columns || 80;
         process.stdout.write('\n');
-        process.stdout.write(`${CR}${CLEAR_LINE}${c.dim(`  ${footer}`)}`);
+        process.stdout.write(`${CR}${CLEAR_LINE}${fitToWidth(c.dim(`  ${footer}`), cols - 1)}`);
       }
       // Terminal cursor is now on the LAST rendered line
       firstDraw = false;
@@ -173,6 +206,10 @@ function selectOne({ title, items, default: defaultIdx = 0, footer }) {
         const chosen = items[defaultIdx];
         console.log(c.success(`${strip(chosen.label)}`));
         resolve({ index: defaultIdx, value: chosen.value });
+      } else if (key === 'ctrl-c') {
+        cleanup();
+        console.log('');
+        process.exit(130);
       }
     };
 
@@ -193,6 +230,10 @@ function selectOne({ title, items, default: defaultIdx = 0, footer }) {
  * @returns {Promise<{indices: number[], values: any[]}>}
  */
 function selectMany({ title, items, defaultSelected, footer }) {
+  if (!items || items.length === 0) {
+    return Promise.resolve({ indices: [], values: [] });
+  }
+
   if (!process.stdin.isTTY) {
     return _fallbackSelectMany({ title, items, defaultSelected });
   }
@@ -220,8 +261,9 @@ function selectMany({ title, items, defaultSelected, footer }) {
       }
       const lines = renderList(items, cursor, selected, true);
       writeLines(lines);
+      const cols = process.stdout.columns || 80;
       process.stdout.write('\n');
-      process.stdout.write(`${CR}${CLEAR_LINE}${c.dim(`  ${footerText}`)}`);
+      process.stdout.write(`${CR}${CLEAR_LINE}${fitToWidth(c.dim(`  ${footerText}`), cols - 1)}`);
       firstDraw = false;
     };
 
@@ -271,6 +313,10 @@ function selectMany({ title, items, defaultSelected, footer }) {
         const indices = [...(defaultSelected || [])].sort((a, b) => a - b);
         const values  = indices.map(i => items[i].value);
         resolve({ indices, values });
+      } else if (key === 'ctrl-c') {
+        cleanup();
+        console.log('');
+        process.exit(130);
       }
     };
 

package/src/utils/progress-bar.js

@@ -18,16 +18,17 @@ const { fmtDuration } = require('./format');
 // ======================== PHASE DEFINITIONS ========================
 
 const PHASES = [
-  { key: 'init',       label: 'Init',         index: 1 },
-  { key: 'discover',   label: 'Discover',     index: 2 },
-  { key: 'services',   label: 'Services',     index: 3 },
-  { key: 'compress',   label: 'Compress',     index: 4 },
-  { key: 'upload',     label: 'Upload',       index: 5 },
-  { key: 'analyze',    label: 'Analyze',      index: 6 },
-  { key: 'compile',    label: 'Compile',      index: 7 },
-  { key: 'output',     label: 'Output',       index: 8 },
-  { key: 'summary',    label: 'Summary',      index: 9 },
-  { key: 'deep-dive',  label: 'Deep Dive',    index: 10 },
+  { key: 'init',         label: 'Init',         index: 1 },
+  { key: 'discover',     label: 'Discover',     index: 2 },
+  { key: 'services',     label: 'Services',     index: 3 },
+  { key: 'deep-summary', label: 'Deep Summary', index: 4 },
+  { key: 'compress',     label: 'Compress',     index: 5 },
+  { key: 'upload',       label: 'Upload',       index: 6 },
+  { key: 'analyze',      label: 'Analyze',      index: 7 },
+  { key: 'compile',      label: 'Compile',      index: 8 },
+  { key: 'output',       label: 'Output',       index: 9 },
+  { key: 'summary',      label: 'Summary',      index: 10 },
+  { key: 'deep-dive',    label: 'Deep Dive',    index: 11 },
 ];
 
 const PHASE_MAP = Object.fromEntries(PHASES.map(p => [p.key, p]));