task-summary-extractor 8.1.0

package/src/config.js

@@ -0,0 +1,327 @@
+/**
+ * Central configuration — all constants, API keys, and settings.
+ *
+ * Resolution priority (highest wins):
+ *   1. CLI flags (--gemini-key etc. — injected in bin/taskex.js before require)
+ *   2. process.env (set by user shell or CI)
+ *   3. CWD .env file (project-specific)
+ *   4. ~/.taskexrc (global persistent config)
+ *   5. Package root .env (development fallback)
+ */
+
+'use strict';
+
+const path = require('path');
+const fs_ = require('fs');
+
+// ── Step 1: Load .env (CWD first, then package root — both with override: false) ──
+// dotenv's default: only sets vars that aren't already set.
+// Load CWD .env first (higher priority), then package root .env (fills gaps).
+const cwd = process.cwd();
+const cwdEnv = path.join(cwd, '.env');
+const pkgEnv = path.resolve(__dirname, '..', '.env');
+if (fs_.existsSync(cwdEnv)) require('dotenv').config({ path: cwdEnv });
+if (fs_.existsSync(pkgEnv)) require('dotenv').config({ path: pkgEnv });
+
+// ── Step 2: Inject global config (~/.taskexrc) for keys still missing ─────
+const { injectGlobalConfig } = require('./utils/global-config');
+injectGlobalConfig();
+
+// ======================== HELPERS ========================
+
+/** Read an env var, returning defaultVal if missing. */
+function env(key, defaultVal = undefined) {
+  const val = process.env[key];
+  if (val !== undefined && val !== '') return val;
+  return defaultVal;
+}
+
+/** Read an env var as a number, with default. */
+function envInt(key, defaultVal) {
+  const raw = process.env[key];
+  if (raw === undefined || raw === '') return defaultVal;
+  const n = parseInt(raw, 10);
+  return isNaN(n) ? defaultVal : n;
+}
+
+/** Read an env var as a float, with default. */
+function envFloat(key, defaultVal) {
+  const raw = process.env[key];
+  if (raw === undefined || raw === '') return defaultVal;
+  const n = parseFloat(raw);
+  return isNaN(n) ? defaultVal : n;
+}
+
+// ======================== FIREBASE ========================
+
+const FIREBASE_CONFIG = {
+  apiKey: env('FIREBASE_API_KEY'),
+  authDomain: env('FIREBASE_AUTH_DOMAIN'),
+  projectId: env('FIREBASE_PROJECT_ID'),
+  storageBucket: env('FIREBASE_STORAGE_BUCKET'),
+  messagingSenderId: env('FIREBASE_MESSAGING_SENDER_ID'),
+  appId: env('FIREBASE_APP_ID'),
+  measurementId: env('FIREBASE_MEASUREMENT_ID'),
+};
+
+// ======================== GEMINI AI ========================
+
+const GEMINI_API_KEY = env('GEMINI_API_KEY');
+
+/**
+ * Complete Gemini model registry — specs, context windows, pricing, and descriptions.
+ *
+ * Pricing source: Google AI for Developers — https://ai.google.dev/gemini-api/docs/pricing
+ * Last verified: February 2026
+ *
+ * Rates are per 1 million tokens. Output pricing INCLUDES thinking tokens
+ * (unified rate). Some models have tiered pricing based on context length
+ * (short = under threshold, long = over threshold).
+ *
+ * NOTE: gemini-2.0-flash, gemini-2.0-flash-lite, and all gemini-1.5-* models
+ * are deprecated/removed. Use 2.5+ models only.
+ */
+const GEMINI_MODELS = {
+  'gemini-3.1-pro-preview': {
+    name: 'Gemini 3.1 Pro Preview',
+    description: 'Latest & most capable — best reasoning, agentic workflows, vibe-coding',
+    contextWindow: 1_048_576,
+    maxOutput: 65536,
+    thinking: true,
+    tier: 'premium',
+    pricing: {
+      inputPerM: 2.00,
+      inputLongPerM: 4.00,
+      outputPerM: 12.00,      // includes thinking tokens
+      outputLongPerM: 18.00,
+      thinkingPerM: 12.00,    // same rate as output (unified pricing)
+      longContextThreshold: 200_000,
+    },
+    costEstimate: '~$0.30/segment',
+  },
+  'gemini-3-flash-preview': {
+    name: 'Gemini 3 Flash Preview',
+    description: 'Frontier intelligence at flash speed — rivals larger models at fraction of cost',
+    contextWindow: 1_048_576,
+    maxOutput: 65536,
+    thinking: true,
+    tier: 'balanced',
+    pricing: {
+      inputPerM: 0.50,
+      inputLongPerM: 0.50,    // flat rate (no long context tier)
+      outputPerM: 3.00,       // includes thinking tokens
+      outputLongPerM: 3.00,
+      thinkingPerM: 3.00,
+      longContextThreshold: 200_000,
+    },
+    costEstimate: '~$0.07/segment',
+  },
+  'gemini-2.5-pro': {
+    name: 'Gemini 2.5 Pro',
+    description: 'Stable premium — deep reasoning, coding, math, STEM, long context',
+    contextWindow: 1_048_576,
+    maxOutput: 65536,
+    thinking: true,
+    tier: 'premium',
+    pricing: {
+      inputPerM: 1.25,
+      inputLongPerM: 2.50,
+      outputPerM: 10.00,      // includes thinking tokens
+      outputLongPerM: 15.00,
+      thinkingPerM: 10.00,
+      longContextThreshold: 200_000,
+    },
+    costEstimate: '~$0.20/segment',
+  },
+  'gemini-2.5-flash': {
+    name: 'Gemini 2.5 Flash',
+    description: 'Best price-performance — thinking, 1M context, high throughput',
+    contextWindow: 1_048_576,
+    maxOutput: 65536,
+    thinking: true,
+    tier: 'balanced',
+    pricing: {
+      inputPerM: 0.30,
+      inputLongPerM: 0.30,    // flat rate
+      outputPerM: 2.50,       // includes thinking tokens
+      outputLongPerM: 2.50,
+      thinkingPerM: 2.50,
+      longContextThreshold: 200_000,
+    },
+    costEstimate: '~$0.05/segment',
+  },
+  'gemini-2.5-flash-lite': {
+    name: 'Gemini 2.5 Flash-Lite',
+    description: 'Cheapest available — fastest, most cost-efficient for high-volume tasks',
+    contextWindow: 1_048_576,
+    maxOutput: 65536,
+    thinking: true,
+    tier: 'economy',
+    pricing: {
+      inputPerM: 0.10,
+      inputLongPerM: 0.10,    // flat rate
+      outputPerM: 0.40,       // includes thinking tokens
+      outputLongPerM: 0.40,
+      thinkingPerM: 0.40,
+      longContextThreshold: 200_000,
+    },
+    costEstimate: '~$0.01/segment',
+  },
+};
+
+// Active model — defaults from env or 'gemini-2.5-flash'
+let GEMINI_MODEL = env('GEMINI_MODEL', 'gemini-2.5-flash');
+let GEMINI_CONTEXT_WINDOW = (GEMINI_MODELS[GEMINI_MODEL] || {}).contextWindow || 1_048_576;
+
+/**
+ * Set the active model at runtime. Updates GEMINI_MODEL and GEMINI_CONTEXT_WINDOW
+ * on module.exports so all modules that reference config.GEMINI_MODEL see the change.
+ *
+ * @param {string} modelId - Model ID (key from GEMINI_MODELS)
+ * @returns {{ id: string, specs: object }} The selected model
+ */
+function setActiveModel(modelId) {
+  const specs = GEMINI_MODELS[modelId];
+  if (!specs) {
+    const valid = Object.keys(GEMINI_MODELS).join(', ');
+    throw new Error(`Unknown model "${modelId}". Valid models: ${valid}`);
+  }
+  GEMINI_MODEL = modelId;
+  GEMINI_CONTEXT_WINDOW = specs.contextWindow;
+  // Update module.exports so modules accessing config.GEMINI_MODEL see the new value
+  module.exports.GEMINI_MODEL = modelId;
+  module.exports.GEMINI_CONTEXT_WINDOW = specs.contextWindow;
+  return { id: modelId, specs };
+}
+
+/**
+ * Get the pricing config for the currently active model.
+ * @returns {object} Pricing object compatible with CostTracker
+ */
+function getActiveModelPricing() {
+  const specs = GEMINI_MODELS[module.exports.GEMINI_MODEL];
+  return specs ? specs.pricing : GEMINI_MODELS['gemini-2.5-flash'].pricing;
+}
+
+// ======================== VIDEO PROCESSING ========================
+
+const SPEED = envFloat('VIDEO_SPEED', 1.5);
+const SEG_TIME = envInt('VIDEO_SEGMENT_TIME', 280); // seconds — produces segments < 5 min
+const PRESET = env('VIDEO_PRESET', 'slow');
+const VIDEO_EXTS = ['.mp4', '.mkv', '.avi', '.mov', '.webm'];
+const DOC_EXTS = ['.vtt', '.txt', '.pdf', '.docx', '.doc', '.srt', '.csv', '.md'];
+
+// ======================== PIPELINE SETTINGS ========================
+
+const LOG_LEVEL = env('LOG_LEVEL', 'info');
+const MAX_PARALLEL_UPLOADS = envInt('MAX_PARALLEL_UPLOADS', 3);
+const MAX_RETRIES = envInt('MAX_RETRIES', 3);
+const RETRY_BASE_DELAY_MS = envInt('RETRY_BASE_DELAY_MS', 2000);
+
+// Gemini thinking budget (tokens allocated for model reasoning)
+const THINKING_BUDGET = envInt('THINKING_BUDGET', 24576);           // per-segment analysis
+const COMPILATION_THINKING_BUDGET = envInt('COMPILATION_THINKING_BUDGET', 10240); // final compilation
+const DEEP_DIVE_THINKING_BUDGET = envInt('DEEP_DIVE_THINKING_BUDGET', 16384);    // deep-dive document generation
+
+// Gemini file API polling timeout (ms) — prevents indefinite hanging
+const GEMINI_POLL_TIMEOUT_MS = envInt('GEMINI_POLL_TIMEOUT_MS', 300000); // 5 min
+
+// ======================== GEMINI FILE HANDLING ========================
+
+// Extensions that Gemini supports via File API for generateContent
+const GEMINI_FILE_API_EXTS = ['.pdf'];
+// Text-readable extensions — inlined as text parts (Gemini rejects text/vtt, text/csv etc. as fileData)
+const INLINE_TEXT_EXTS = ['.vtt', '.srt', '.txt', '.md', '.csv'];
+// Unsupported by Gemini — uploaded to Firebase only
+const GEMINI_UNSUPPORTED = ['.docx', '.doc'];
+
+// ======================== MIME TYPES ========================
+
+const MIME_MAP = {
+  '.vtt': 'text/vtt',
+  '.srt': 'application/x-subrip',
+  '.txt': 'text/plain',
+  '.md': 'text/markdown',
+  '.csv': 'text/csv',
+  '.pdf': 'application/pdf',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.doc': 'application/msword',
+  '.mp4': 'video/mp4',
+  '.mkv': 'video/x-matroska',
+  '.avi': 'video/x-msvideo',
+  '.mov': 'video/quicktime',
+  '.webm': 'video/webm',
+  '.json': 'application/json',
+};
+
+// ======================== VALIDATION ========================
+
+/**
+ * Validate that all required configuration is present.
+ * Returns { valid: boolean, errors: string[] }.
+ */
+function validateConfig({ skipFirebase = false, skipGemini = false } = {}) {
+  const errors = [];
+
+  if (!skipGemini && !GEMINI_API_KEY) {
+    errors.push('GEMINI_API_KEY is missing. Set it in .env or as an environment variable.');
+  }
+
+  if (!skipFirebase) {
+    const fbRequired = ['apiKey', 'authDomain', 'projectId', 'storageBucket'];
+    for (const key of fbRequired) {
+      if (!FIREBASE_CONFIG[key]) {
+        const envKey = `FIREBASE_${key.replace(/([A-Z])/g, '_$1').toUpperCase()}`;
+        errors.push(`Firebase ${key} is missing. Set ${envKey} in .env or as an environment variable.`);
+      }
+    }
+  }
+
+  if (SPEED <= 0 || SPEED > 10) {
+    errors.push(`VIDEO_SPEED=${SPEED} is out of range. Must be between 0.1 and 10.`);
+  }
+
+  if (SEG_TIME < 30 || SEG_TIME > 3600) {
+    errors.push(`VIDEO_SEGMENT_TIME=${SEG_TIME} is out of range. Must be between 30 and 3600.`);
+  }
+
+  const validPresets = ['ultrafast', 'superfast', 'veryfast', 'faster', 'fast', 'medium', 'slow', 'slower', 'veryslow'];
+  if (!validPresets.includes(PRESET)) {
+    errors.push(`VIDEO_PRESET="${PRESET}" is invalid. Must be one of: ${validPresets.join(', ')}`);
+  }
+
+  const validLogLevels = ['debug', 'info', 'warn', 'error'];
+  if (!validLogLevels.includes(LOG_LEVEL)) {
+    errors.push(`LOG_LEVEL="${LOG_LEVEL}" is invalid. Must be one of: ${validLogLevels.join(', ')}`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+module.exports = {
+  FIREBASE_CONFIG,
+  GEMINI_API_KEY,
+  GEMINI_MODEL,
+  GEMINI_CONTEXT_WINDOW,
+  GEMINI_MODELS,
+  setActiveModel,
+  getActiveModelPricing,
+  SPEED,
+  SEG_TIME,
+  PRESET,
+  VIDEO_EXTS,
+  DOC_EXTS,
+  GEMINI_FILE_API_EXTS,
+  INLINE_TEXT_EXTS,
+  GEMINI_UNSUPPORTED,
+  MIME_MAP,
+  LOG_LEVEL,
+  MAX_PARALLEL_UPLOADS,
+  MAX_RETRIES,
+  RETRY_BASE_DELAY_MS,
+  THINKING_BUDGET,
+  COMPILATION_THINKING_BUDGET,
+  DEEP_DIVE_THINKING_BUDGET,
+  GEMINI_POLL_TIMEOUT_MS,
+  validateConfig,
+};

package/src/logger.js

@@ -0,0 +1,355 @@
+/**
+ * Logger — dual-file logger with buffered writes, configurable log levels,
+ * structured JSON logging, phase timing spans, and reversible console patching.
+ *
+ * v6 improvements:
+ *  - Structured JSON log file: machine-parseable logs alongside human-readable
+ *  - Phase spans: automatic timing of pipeline phases with structured events
+ *  - Operation context: attach context (phase, segment, etc.) to log entries
+ *  - Log aggregation: summary stats computed from structured entries
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+
+class Logger {
+  /**
+   * @param {string} logsDir - Directory for log files
+   * @param {string} callName - Name used in the log filename
+   * @param {object} [opts]
+   * @param {string} [opts.level='info'] - Minimum log level: debug|info|warn|error
+   * @param {number} [opts.flushIntervalMs=500] - How often to flush buffers
+   */
+  constructor(logsDir, callName, opts = {}) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    fs.mkdirSync(logsDir, { recursive: true });
+
+    this.detailedPath = path.join(logsDir, `${callName}_${ts}_detailed.log`);
+    this.minimalPath = path.join(logsDir, `${callName}_${ts}_minimal.log`);
+    this.structuredPath = path.join(logsDir, `${callName}_${ts}_structured.jsonl`);
+    this.startTime = Date.now();
+    this.level = LOG_LEVELS[opts.level] ?? LOG_LEVELS.info;
+    this.closed = false;
+    this.callName = callName;
+
+    // Buffered write system — accumulate lines, flush periodically
+    this._detailedBuffer = [];
+    this._minimalBuffer = [];
+    this._structuredBuffer = [];
+    this._flushInterval = setInterval(() => this._flush(), opts.flushIntervalMs || 500);
+    // Prevent the interval from keeping the process alive
+    if (this._flushInterval.unref) this._flushInterval.unref();
+
+    // Original console methods (for unpatch)
+    this._origLog = null;
+    this._origWarn = null;
+    this._origError = null;
+
+    // Phase tracking for spans
+    this._activePhase = null;
+    this._phaseStart = null;
+    this._phases = []; // Completed phase records
+
+    // Operation context stack
+    this._context = {};
+
+    // Write headers
+    const header = `=== ${callName} | ${new Date().toISOString()} ===\n`;
+    this._detailedBuffer.push(header);
+    this._minimalBuffer.push(header);
+    this._writeStructured({
+      event: 'session_start',
+      callName,
+      timestamp: new Date().toISOString(),
+      level: 'info',
+    });
+    this._flush(); // Flush headers immediately
+  }
+
+  _ts() {
+    const elapsed = ((Date.now() - this.startTime) / 1000).toFixed(1);
+    return `[${new Date().toISOString().slice(11, 19)} +${elapsed}s]`;
+  }
+
+  _elapsedMs() {
+    return Date.now() - this.startTime;
+  }
+
+  _shouldLog(level) {
+    return LOG_LEVELS[level] >= this.level;
+  }
+
+  _writeDetailed(line) {
+    if (this.closed) return;
+    this._detailedBuffer.push(line + '\n');
+  }
+
+  _writeMinimal(line) {
+    if (this.closed) return;
+    this._minimalBuffer.push(line + '\n');
+  }
+
+  _writeBoth(line) {
+    this._writeDetailed(line);
+    this._writeMinimal(line);
+  }
+
+  /**
+   * Write a structured JSON entry to the JSONL log.
+   * @param {object} entry - Structured log entry (will have timestamp/elapsed added)
+   */
+  _writeStructured(entry) {
+    if (this.closed) return;
+    const enriched = {
+      ...entry,
+      elapsedMs: this._elapsedMs(),
+      ...(this._activePhase ? { phase: this._activePhase } : {}),
+      ...(Object.keys(this._context).length > 0 ? { context: { ...this._context } } : {}),
+    };
+    try {
+      this._structuredBuffer.push(JSON.stringify(enriched) + '\n');
+    } catch { /* ignore serialization errors */ }
+  }
+
+  _flush(sync = false) {
+    const writeFn = sync
+      ? (p, d) => fs.appendFileSync(p, d)
+      : (p, d) => fs.appendFile(p, d, () => {});
+
+    if (this._detailedBuffer.length > 0) {
+      const data = this._detailedBuffer.join('');
+      this._detailedBuffer.length = 0;
+      try { writeFn(this.detailedPath, data); }
+      catch { /* ignore write errors */ }
+    }
+    if (this._minimalBuffer.length > 0) {
+      const data = this._minimalBuffer.join('');
+      this._minimalBuffer.length = 0;
+      try { writeFn(this.minimalPath, data); }
+      catch { /* ignore write errors */ }
+    }
+    if (this._structuredBuffer.length > 0) {
+      const data = this._structuredBuffer.join('');
+      this._structuredBuffer.length = 0;
+      try { writeFn(this.structuredPath, data); }
+      catch { /* ignore write errors */ }
+    }
+  }
+
+  // ======================== CONTEXT ========================
+
+  /**
+   * Set operation context that will be attached to all subsequent log entries.
+   * @param {object} ctx - Context fields (e.g., { segment: 'seg_00', phase: 'analyze' })
+   */
+  setContext(ctx) {
+    this._context = { ...this._context, ...ctx };
+  }
+
+  /**
+   * Clear specific context keys.
+   * @param {...string} keys - Keys to remove
+   */
+  clearContext(...keys) {
+    for (const k of keys) delete this._context[k];
+  }
+
+  // ======================== PHASE SPANS ========================
+
+  /**
+   * Start a named phase span for timing.
+   * @param {string} phaseName - Name of the phase
+   */
+  phaseStart(phaseName) {
+    // End previous phase if active
+    if (this._activePhase) {
+      this.phaseEnd();
+    }
+
+    this._activePhase = phaseName;
+    this._phaseStart = Date.now();
+
+    this._writeStructured({
+      event: 'phase_start',
+      phase: phaseName,
+      timestamp: new Date().toISOString(),
+      level: 'info',
+    });
+  }
+
+  /**
+   * End the current phase span and record timing.
+   * @param {object} [meta] - Optional metadata to attach to the phase record
+   * @returns {number} Duration in milliseconds
+   */
+  phaseEnd(meta = {}) {
+    if (!this._activePhase) return 0;
+
+    const durationMs = Date.now() - this._phaseStart;
+    const record = {
+      phase: this._activePhase,
+      durationMs,
+      ...meta,
+    };
+    this._phases.push(record);
+
+    this._writeStructured({
+      event: 'phase_end',
+      phase: this._activePhase,
+      durationMs,
+      timestamp: new Date().toISOString(),
+      level: 'info',
+      meta,
+    });
+
+    const name = this._activePhase;
+    this._activePhase = null;
+    this._phaseStart = null;
+
+    return durationMs;
+  }
+
+  /**
+   * Get all completed phase records.
+   * @returns {Array<{phase: string, durationMs: number}>}
+   */
+  getPhases() {
+    return [...this._phases];
+  }
+
+  // ======================== LOG METHODS ========================
+
+  /** Detailed log only — verbose/debug info */
+  debug(msg, data = null) {
+    if (!this._shouldLog('debug')) return;
+    this._writeDetailed(`${this._ts()} DBG  ${msg}`);
+    this._writeStructured({ event: 'log', level: 'debug', message: msg, ...(data ? { data } : {}) });
+  }
+
+  /** Both logs — standard info */
+  info(msg, data = null) {
+    if (!this._shouldLog('info')) return;
+    this._writeBoth(`${this._ts()} INFO ${msg}`);
+    this._writeStructured({ event: 'log', level: 'info', message: msg, ...(data ? { data } : {}) });
+  }
+
+  /** Both logs — warnings */
+  warn(msg, data = null) {
+    if (!this._shouldLog('warn')) return;
+    this._writeBoth(`${this._ts()} WARN ${msg}`);
+    this._writeStructured({ event: 'log', level: 'warn', message: msg, ...(data ? { data } : {}) });
+  }
+
+  /** Both logs — errors */
+  error(msg, data = null) {
+    // Errors always logged regardless of level
+    this._writeBoth(`${this._ts()} ERR  ${msg}`);
+    this._writeStructured({ event: 'log', level: 'error', message: msg, ...(data ? { data } : {}) });
+  }
+
+  /** Minimal + detailed — key milestone events */
+  step(msg, data = null) {
+    this._writeBoth(`${this._ts()} STEP ${msg}`);
+    this._writeStructured({ event: 'step', level: 'info', message: msg, ...(data ? { data } : {}) });
+  }
+
+  /**
+   * Log a structured metric event (e.g., token usage, quality scores).
+   * Only goes to structured log — not human-readable logs.
+   * @param {string} metric - Metric name
+   * @param {object} value - Metric data
+   */
+  metric(metric, value) {
+    this._writeStructured({
+      event: 'metric',
+      metric,
+      value,
+      timestamp: new Date().toISOString(),
+      level: 'info',
+    });
+  }
+
+  /** Patch console so ALL output also goes to detailed log */
+  patchConsole() {
+    this._origLog = console.log.bind(console);
+    this._origWarn = console.warn.bind(console);
+    this._origError = console.error.bind(console);
+    const self = this;
+
+    console.log = function (...args) {
+      self._origLog(...args);
+      try { self.info(args.map(String).join(' ')); } catch { /* ignore */ }
+    };
+    console.warn = function (...args) {
+      self._origWarn(...args);
+      try { self.warn(args.map(String).join(' ')); } catch { /* ignore */ }
+    };
+    console.error = function (...args) {
+      self._origError(...args);
+      try { self.error(args.map(String).join(' ')); } catch { /* ignore */ }
+    };
+  }
+
+  /** Restore original console methods */
+  unpatchConsole() {
+    if (this._origLog) console.log = this._origLog;
+    if (this._origWarn) console.warn = this._origWarn;
+    if (this._origError) console.error = this._origError;
+  }
+
+  /** Write a final summary block to minimal log */
+  summary(lines) {
+    const block = '\n--- SUMMARY ---\n' + lines.join('\n') + '\n';
+    this._writeBoth(block);
+
+    this._writeStructured({
+      event: 'session_summary',
+      phases: this._phases,
+      totalElapsedMs: this._elapsedMs(),
+      timestamp: new Date().toISOString(),
+      level: 'info',
+    });
+  }
+
+  /** Flush buffers and close the logger. Safe to call multiple times. */
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    clearInterval(this._flushInterval);
+    this.unpatchConsole();
+
+    // End active phase if any
+    if (this._activePhase) {
+      this.phaseEnd();
+    }
+
+    // Write footer
+    const elapsed = ((Date.now() - this.startTime) / 1000).toFixed(1);
+    const footer = `\n=== CLOSED | elapsed: ${elapsed}s | ${new Date().toISOString()} ===\n`;
+    this._detailedBuffer.push(footer);
+    this._minimalBuffer.push(footer);
+    this._writeStructured({
+      event: 'session_end',
+      totalElapsedMs: this._elapsedMs(),
+      phases: this._phases,
+      timestamp: new Date().toISOString(),
+      level: 'info',
+    });
+    this._flush(true); // sync flush on close to ensure data is written before process exits
+  }
+
+  /** Get human-readable elapsed time */
+  elapsed() {
+    const sec = (Date.now() - this.startTime) / 1000;
+    if (sec < 60) return `${sec.toFixed(1)}s`;
+    const min = Math.floor(sec / 60);
+    const remainder = (sec % 60).toFixed(0);
+    return `${min}m ${remainder}s`;
+  }
+}
+
+module.exports = Logger;