copilot-usage-studio 0.2.0 → 0.2.2

package/scripts/scan-vscode-sessions.mjs

@@ -1,15 +1,34 @@
-import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
-import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import {
-  costBreakdownUsdForTokens,
-  costUsdForTokens,
-  modelKey,
   normalizeModel,
-  pricingModelForModel,
 } from './pricing-utils.mjs';
+import {
+  attachMemoryRecalls as attachMemoryRecallsCore,
+  createMemoryScanner,
+} from './scanner-memory.mjs';
+import {
+  customizationEvidenceFromDebugLogs as customizationEvidenceFromDebugLogsCore,
+  mergeCustomizationRecords,
+  statusRank,
+} from './scanner-customization-evidence.mjs';
+import { createCustomizationInventoryScanner } from './scanner-customization-inventory.mjs';
+import { createSessionParser } from './scanner-session-parser.mjs';
+import {
+  defaultCodeUserDirs,
+  listDebugLogFiles as traverseDebugLogFiles,
+  listDirs as traverseDirs,
+  listFiles as traverseFiles,
+  listFilesRecursive as traverseFilesRecursive,
+  uniqueResolvedRoots,
+  userDirForRoot,
+  workspaceDirsForRoot,
+} from './scanner-traversal.mjs';
+import { parseWorkspace as parseWorkspaceEntry } from './scanner-workspace.mjs';
+
+export { defaultCodeUserDirs } from './scanner-traversal.mjs';
 
 const sessionDataSchemaVersion = 1;
 const pricingData = JSON.parse(
@@ -42,8 +61,20 @@ function createDiagnostics() {
     scannedMemoryRoots: 0,
     importedMemories: 0,
     importedPlans: 0,
+    scannedCustomizationRoots: 0,
+    scannedCustomizationLocations: [],
+    customizationEvidenceScannedSessions: 0,
+    customizationEvidenceModelCalls: 0,
+    customizationEvidenceTextParts: 0,
+    customizationEvidenceMatchedCustomizations: 0,
+    customizationEvidenceCapReason: '',
+    importedCustomizations: 0,
+    workspaceScans: [],
+    skippedSystemCustomizations: 0,
     skippedOversizedMemories: 0,
     skippedUnreadableMemories: 0,
+    skippedOversizedCustomizations: 0,
+    skippedUnreadableCustomizations: 0,
     skippedEmptyDebugLogs: 0,
     skippedChatSnapshotsWithoutRequests: 0,
     skippedDuplicateChatSnapshots: 0,
@@ -51,24 +82,6 @@ function createDiagnostics() {
   };
 }
 
-export function defaultCodeUserDirs() {
-  const home = homedir();
-
-  if (platform() === 'win32') {
-    const appData = process.env.APPDATA ?? join(home, 'AppData', 'Roaming');
-    return [join(appData, 'Code', 'User'), join(appData, 'Code - Insiders', 'User')];
-  }
-
-  if (platform() === 'darwin') {
-    return [
-      join(home, 'Library', 'Application Support', 'Code', 'User'),
-      join(home, 'Library', 'Application Support', 'Code - Insiders', 'User'),
-    ];
-  }
-
-  return [join(home, '.config', 'Code', 'User'), join(home, '.config', 'Code - Insiders', 'User')];
-}
-
 function safeJson(text) {
   try {
     return JSON.parse(text);
@@ -249,1077 +262,185 @@ function readJsonl(file) {
     .filter(Boolean);
 }
 
-function listDirs(dir) {
-  if (!existsSync(dir)) {
-    return [];
-  }
-
-  return readdirSync(dir)
-    .map((entry) => join(dir, entry))
-    .filter((path) => statSync(path).isDirectory());
-}
-
-function listFiles(dir, suffix) {
-  if (!existsSync(dir)) {
-    return [];
-  }
-
-  return readdirSync(dir)
-    .map((entry) => join(dir, entry))
-    .filter((path) => statSync(path).isFile() && path.endsWith(suffix));
-}
+function stripJsonComments(text) {
+  let output = '';
+  let inString = false;
+  let escaped = false;
+  let inLineComment = false;
+  let inBlockComment = false;
 
-function listDebugLogFiles(root) {
-  if (!existsSync(root)) {
-    return [];
-  }
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    const next = text[index + 1];
 
-  const files = [];
-  const pending = [root];
-
-  while (pending.length) {
-    const current = pending.pop();
-    for (const entry of readdirSync(current, { withFileTypes: true })) {
-      const path = join(current, entry.name);
-      if (entry.isDirectory()) {
-        pending.push(path);
-      } else if (entry.isFile() && entry.name.endsWith('.jsonl')) {
-        files.push(path);
+    if (inLineComment) {
+      if (character === '\n' || character === '\r') {
+        inLineComment = false;
+        output += character;
       }
+      continue;
     }
-  }
 
-  return files.sort();
-}
-
-function listFilesRecursive(root, predicate, limit = memoryFileLimit) {
-  if (!existsSync(root)) {
-    return [];
-  }
-
-  const files = [];
-  const pending = [root];
-
-  while (pending.length && files.length < limit) {
-    const current = pending.pop();
-    let entries = [];
-
-    try {
-      entries = readdirSync(current, { withFileTypes: true });
-    } catch (error) {
-      diagnostics.skippedUnreadableMemories += 1;
-      diagnostics.warnings.push(`${current}: memory directory skipped: ${error.message}`);
+    if (inBlockComment) {
+      if (character === '*' && next === '/') {
+        inBlockComment = false;
+        index += 1;
+      }
       continue;
     }
 
-    for (const entry of entries) {
-      const path = join(current, entry.name);
-      if (entry.isDirectory()) {
-        pending.push(path);
-      } else if (entry.isFile() && predicate(path)) {
-        files.push(path);
-        if (files.length >= limit) {
-          diagnostics.warnings.push(`${root}: memory scan capped at ${limit} files.`);
-          break;
-        }
+    if (inString) {
+      output += character;
+      if (escaped) {
+        escaped = false;
+      } else if (character === '\\') {
+        escaped = true;
+      } else if (character === '"') {
+        inString = false;
       }
+      continue;
     }
-  }
 
-  return files;
-}
+    if (character === '"') {
+      inString = true;
+      output += character;
+      continue;
+    }
 
-function decodeMemorySessionId(value) {
-  try {
-    const decoded = Buffer.from(String(value), 'base64').toString('utf8');
-    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(decoded)
-      ? decoded
-      : '';
-  } catch {
-    return '';
-  }
-}
+    if (character === '/' && next === '/') {
+      inLineComment = true;
+      index += 1;
+      continue;
+    }
 
-function memoryTitle(content, file) {
-  const heading = String(content)
-    .split(/\r?\n/)
-    .map((line) => line.match(/^#{1,3}\s+(.+?)\s*#*$/)?.[1]?.trim())
-    .find(Boolean);
+    if (character === '/' && next === '*') {
+      inBlockComment = true;
+      index += 1;
+      continue;
+    }
 
-  if (heading) {
-    return heading.slice(0, 160);
+    output += character;
   }
 
-  return basename(file, extname(file))
-    .replace(/[-_]+/g, ' ')
-    .replace(/\b\w/g, (character) => character.toUpperCase())
-    .slice(0, 160);
+  return output;
 }
 
-function memoryExcerpt(content) {
-  return String(content)
-    .replace(/^#{1,6}\s+/gm, '')
-    .replace(/[`*_>~-]+/g, ' ')
-    .replace(/\s+/g, ' ')
-    .trim()
-    .slice(0, 280);
-}
+function readJsoncFile(file) {
+  if (!existsSync(file)) {
+    return {};
+  }
 
-function memoryFromFile(file, root, source, workspace) {
   try {
-    const stats = statSync(file);
-    if (stats.size > memoryFileSizeLimit) {
-      diagnostics.skippedOversizedMemories += 1;
-      diagnostics.warnings.push(`${file}: memory skipped because it exceeds 1 MiB.`);
-      return null;
-    }
-
-    const content = readFileSync(file, 'utf8');
-    const relativePath = relative(root, file);
-    const segments = relativePath.split(sep).filter(Boolean);
-    const sessionId = source === 'workspace' ? decodeMemorySessionId(segments[0]) : '';
-    const kind = basename(file).toLowerCase() === 'plan.md' ? 'plan' : 'memory';
-    const scope = source === 'global'
-      ? 'global'
-      : segments[0]?.toLowerCase() === 'repo'
-        ? 'repository'
-        : sessionId
-          ? 'session'
-          : 'workspace';
-
-    return {
-      id: createHash('sha256').update(resolve(file)).digest('hex').slice(0, 24),
-      kind,
-      scope,
-      title: memoryTitle(content, file),
-      excerpt: memoryExcerpt(content),
-      content,
-      workspace: source === 'global' ? '' : workspace,
-      sessionId,
-      sourcePath: resolve(file),
-      relativePath,
-      createdAt: stats.birthtimeMs > 0 ? stats.birthtime.toISOString() : '',
-      modifiedAt: stats.mtime.toISOString(),
-      sizeBytes: stats.size,
-      characterCount: content.length,
-      lineCount: content ? content.split(/\r?\n/).length : 0,
-    };
+    const json = stripJsonComments(readFileSync(file, 'utf8')).replace(/,\s*([}\]])/g, '$1');
+    return safeJson(json) ?? {};
   } catch (error) {
-    diagnostics.skippedUnreadableMemories += 1;
-    diagnostics.warnings.push(`${file}: memory skipped: ${error.message}`);
-    return null;
+    diagnostics.warnings.push(`${file}: settings file skipped: ${error.message}`);
+    return {};
   }
 }
 
-function memoriesFromRoot(root, source, workspace = '') {
-  if (!existsSync(root)) {
-    return [];
-  }
-
-  diagnostics.scannedMemoryRoots += 1;
-  const memories = listFilesRecursive(root, (file) => extname(file).toLowerCase() === '.md')
-    .map((file) => memoryFromFile(file, root, source, workspace))
-    .filter(Boolean);
-
-  diagnostics.importedMemories += memories.length;
-  diagnostics.importedPlans += memories.filter((memory) => memory.kind === 'plan').length;
-  return memories;
+function listDirs(dir) {
+  return traverseDirs(dir, traversalOptions());
 }
 
-function normalizeMemoryVirtualPath(value) {
-  const path = String(value ?? '').trim().replace(/\\/g, '/');
-  return path.startsWith('/') ? path : `/${path}`;
+function listFiles(dir, suffix) {
+  return traverseFiles(dir, suffix, traversalOptions());
 }
 
-function virtualPathForMemory(memory) {
-  const segments = String(memory.relativePath ?? '').split(/[\\/]+/).filter(Boolean);
-
-  if (memory.scope === 'session') {
-    return normalizeMemoryVirtualPath(`/memories/session/${segments.slice(1).join('/')}`);
-  }
-
-  return normalizeMemoryVirtualPath(`/memories/${segments.join('/')}`);
+function listDebugLogFiles(root) {
+  return traverseDebugLogFiles(root, traversalOptions());
 }
 
-export function memoryRecallsFromDebugLog(sessionDir, workspace = '') {
-  const sessionId = basename(sessionDir);
-  const recalls = [];
-
-  for (const file of listDebugLogFiles(sessionDir)) {
-    const events = readJsonl(file);
-    let modelCallNumber = 0;
-    const modelCallNumbers = new Map();
-
-    events.forEach((event, index) => {
-      if (event.type === 'llm_request') {
-        modelCallNumber += 1;
-        modelCallNumbers.set(index, modelCallNumber);
-      }
-    });
-
-    events.forEach((event, index) => {
-      if (event.type !== 'tool_call' || event.name !== 'memory') {
-        return;
-      }
-
-      const args = safeJson(event.attrs?.args) ?? {};
-      if (args.command !== 'view' || !args.path) {
-        return;
-      }
-
-      const nextModelIndex = events.findIndex(
-        (candidate, candidateIndex) => candidateIndex > index && candidate.type === 'llm_request',
-      );
-      const nextModel = nextModelIndex >= 0 ? events[nextModelIndex] : null;
-      const tokenFields = nextModel ? llmTokenFields(nextModel) : null;
-      const sourceLog = basename(file);
-
-      recalls.push({
-        id: createHash('sha256')
-          .update(`${resolve(file)}:${index}:${args.path}`)
-          .digest('hex')
-          .slice(0, 24),
-        sessionId,
-        workspace,
-        virtualPath: normalizeMemoryVirtualPath(args.path),
-        timestamp: timestampForEvent(event),
-        sourceLog,
-        returnedCharacterCount: String(event.attrs?.result ?? '').length,
-        ...(nextModel
-          ? {
-              followingModelCall: {
-                number: modelCallNumbers.get(nextModelIndex) ?? 0,
-                model: normalizeModel(nextModel.attrs?.model, pricing),
-                inputTokens: tokenFields.inputTokens,
-                cachedInputTokens: tokenFields.cachedInputTokens,
-                outputTokens: tokenFields.outputTokens,
-              },
-            }
-          : {}),
-      });
-    });
-  }
-
-  return recalls.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+function listFilesRecursive(root, predicate, limit = memoryFileLimit, options = {}) {
+  return traverseFilesRecursive(root, predicate, limit, traversalOptions(options));
 }
 
-export function attachMemoryRecalls(memories, sessions) {
-  const recalls = sessions.flatMap((session) => session.memoryRecalls ?? []);
-
-  return memories.map((memory) => {
-    const virtualPath = virtualPathForMemory(memory);
-    const matchingRecalls = recalls.filter((recall) => {
-      if (recall.virtualPath !== virtualPath) {
-        return false;
-      }
-      if (memory.scope === 'session') {
-        return memory.sessionId === recall.sessionId;
-      }
-      if (memory.scope === 'repository' || memory.scope === 'workspace') {
-        return memory.workspace === recall.workspace;
+function traversalOptions(options = {}) {
+  return {
+    ...options,
+    onWarning: (message) => diagnostics.warnings.push(message),
+    onUnreadable: options.onUnreadable ?? (() => {
+      if (options.label === 'customization') {
+        diagnostics.skippedUnreadableCustomizations += 1;
+      } else {
+        diagnostics.skippedUnreadableMemories += 1;
       }
-      return memory.scope === 'global';
-    });
+    }),
+  };
+}
 
-    return matchingRecalls.length ? { ...memory, recalls: matchingRecalls } : memory;
+function memoryScanner() {
+  return createMemoryScanner({
+    diagnostics: () => diagnostics,
+    listDebugLogFiles,
+    listFilesRecursive,
+    llmTokenFields,
+    memoryFileLimit,
+    memoryFileSizeLimit,
+    normalizeModel: (model) => normalizeModel(model, pricing),
+    readJsonl,
+    safeJson,
+    timestampForEvent,
   });
 }
 
-function costUsd(model, tokens) {
-  return costUsdForTokens(model, tokens, pricing, fallbackPricingModel);
+function memoriesFromRoot(root, source, workspace = '') {
+  return memoryScanner().memoriesFromRoot(root, source, workspace);
 }
 
-function costBreakdownUsd(model, tokens) {
-  return costBreakdownUsdForTokens(model, tokens, pricing, fallbackPricingModel);
+export function memoryRecallsFromDebugLog(sessionDir, workspace = '') {
+  return memoryScanner().memoryRecallsFromDebugLog(sessionDir, workspace);
 }
 
-function transcriptAvailability(workspaceDir, sessionId) {
-  const sourcePath = join(workspaceDir, 'GitHub.copilot-chat', 'transcripts', `${sessionId}.jsonl`);
-
-  if (!existsSync(sourcePath)) {
-    return {
-      available: false,
-      sourcePath: '',
-      eventCount: 0,
-    };
-  }
-
-  const eventCount = readJsonl(sourcePath).length;
-
-  return {
-    available: true,
-    sourcePath,
-    eventCount,
-  };
+export function attachMemoryRecalls(memories, sessions) {
+  return attachMemoryRecallsCore(memories, sessions);
 }
 
-function numericAttr(attrs, names) {
-  for (const name of names) {
-    const value = Number(attrs?.[name] ?? 0);
-    if (Number.isFinite(value) && value > 0) {
-      return value;
-    }
-  }
-
-  return 0;
+function sessionParser() {
+  return createSessionParser({
+    diagnostics: () => diagnostics,
+    fallbackPricingModel,
+    listFiles,
+    memoryRecallsFromDebugLog,
+    pricing,
+    readJsonl,
+    safeJson,
+    traceEventLimit,
+    usdToEur: () => usdToEur,
+    workspaceName,
+  });
 }
 
 export function llmTokenFields(event) {
-  const inputTokens = Number(event.attrs?.inputTokens ?? 0);
-  const outputTokens = Number(event.attrs?.outputTokens ?? 0);
-  const rawCachedInputTokens = numericAttr(event.attrs, [
-    'cachedTokens',
-    'cachedInputTokens',
-    'cacheReadTokens',
-  ]);
-  const cachedInputTokens = Math.min(inputTokens, rawCachedInputTokens);
-  const cacheWriteTokens = numericAttr(event.attrs, ['cacheWriteTokens', 'cachedWriteTokens']);
-  const billableInputTokens = Math.max(0, inputTokens - cachedInputTokens);
-
-  return {
-    inputTokens,
-    billableInputTokens,
-    rawCachedInputTokens,
-    cachedInputTokens,
-    cacheWriteTokens,
-    outputTokens,
-  };
+  return sessionParser().llmTokenFields(event);
 }
 
 export function cacheTokenAuditFromLlmRequests(llmRequests) {
-  return llmRequests.reduce(
-    (audit, event) => {
-      const tokenFields = llmTokenFields(event);
-
-      audit.modelCalls += 1;
-      audit.rawInputTokens += tokenFields.inputTokens;
-      audit.normalInputTokens += tokenFields.billableInputTokens;
-      audit.cachedInputTokens += tokenFields.cachedInputTokens;
-      audit.cacheWriteTokens += tokenFields.cacheWriteTokens;
-      audit.outputTokens += tokenFields.outputTokens;
-
-      if (tokenFields.rawCachedInputTokens > 0) {
-        audit.callsWithCachedTokens += 1;
-      }
-
-      if (tokenFields.rawCachedInputTokens > tokenFields.inputTokens) {
-        audit.invalidCachedTokenSplits += 1;
-      }
-
-      const rawInputShare =
-        tokenFields.inputTokens > 0 ? tokenFields.cachedInputTokens / tokenFields.inputTokens : 0;
-      audit.maxCachedInputShare = Math.max(audit.maxCachedInputShare, rawInputShare);
-
-      return audit;
-    },
-    {
-      modelCalls: 0,
-      callsWithCachedTokens: 0,
-      invalidCachedTokenSplits: 0,
-      rawInputTokens: 0,
-      normalInputTokens: 0,
-      cachedInputTokens: 0,
-      cacheWriteTokens: 0,
-      outputTokens: 0,
-      maxCachedInputShare: 0,
-    },
-  );
+  return sessionParser().cacheTokenAuditFromLlmRequests(llmRequests);
 }
 
 export function mergeCacheTokenAudits(audits) {
-  return audits.reduce(
-    (total, audit) => ({
-      modelCalls: total.modelCalls + audit.modelCalls,
-      callsWithCachedTokens: total.callsWithCachedTokens + audit.callsWithCachedTokens,
-      invalidCachedTokenSplits: total.invalidCachedTokenSplits + audit.invalidCachedTokenSplits,
-      rawInputTokens: total.rawInputTokens + audit.rawInputTokens,
-      normalInputTokens: total.normalInputTokens + audit.normalInputTokens,
-      cachedInputTokens: total.cachedInputTokens + audit.cachedInputTokens,
-      cacheWriteTokens: total.cacheWriteTokens + audit.cacheWriteTokens,
-      outputTokens: total.outputTokens + audit.outputTokens,
-      maxCachedInputShare: Math.max(total.maxCachedInputShare, audit.maxCachedInputShare),
-    }),
-    {
-      modelCalls: 0,
-      callsWithCachedTokens: 0,
-      invalidCachedTokenSplits: 0,
-      rawInputTokens: 0,
-      normalInputTokens: 0,
-      cachedInputTokens: 0,
-      cacheWriteTokens: 0,
-      outputTokens: 0,
-      maxCachedInputShare: 0,
-    },
-  );
+  return sessionParser().mergeCacheTokenAudits(audits);
 }
 
 export function eventModelCostFields(rawModel, tokenFields) {
-  const normalizedModel = normalizeModel(rawModel, pricing);
-  const pricingModel = pricingModelForModel(normalizedModel, pricing, fallbackPricingModel);
-  const tokens = {
-    input: tokenFields.billableInputTokens,
-    cachedInput: tokenFields.cachedInputTokens,
-    cacheWrite: tokenFields.cacheWriteTokens,
-    output: tokenFields.outputTokens,
-  };
-  const costBreakdown = costBreakdownUsd(pricingModel, tokens);
-
-  return {
-    model: normalizedModel,
-    rawModel:
-      String(rawModel ?? '')
-        .replace(/^copilot\//i, '')
-        .trim() || 'unknown',
-    pricingModel,
-    pricingTier: costBreakdown.tier,
-    totalTokens: tokenFields.inputTokens + tokenFields.outputTokens + tokenFields.cacheWriteTokens,
-    estimatedCost: { usd: costBreakdown.total, eur: costBreakdown.total * usdToEur },
-  };
-}
-
-function parseMaybeJson(value) {
-  if (typeof value !== 'string') {
-    return value ?? null;
-  }
-
-  return safeJson(value) ?? value;
-}
-
-function charLength(value) {
-  if (value === undefined || value === null) {
-    return 0;
-  }
-
-  return typeof value === 'string' ? value.length : JSON.stringify(value).length;
-}
-
-function parseContentFile(file) {
-  const envelope = safeJson(readFileSync(file, 'utf8'));
-  const content = parseMaybeJson(envelope?.content ?? envelope);
-
-  return {
-    file,
-    content,
-    chars: charLength(content),
-  };
-}
-
-function modelCapabilityIndex(sessionDir) {
-  const file = join(sessionDir, 'models.json');
-  if (!existsSync(file)) {
-    return new Map();
-  }
-
-  const parsed = safeJson(readFileSync(file, 'utf8'));
-  const models = Array.isArray(parsed) ? parsed : [];
-  const index = new Map();
-
-  for (const model of models) {
-    const keys = [model?.id, model?.name, model?.version, model?.capabilities?.family]
-      .filter(Boolean)
-      .map(modelKey);
-
-    for (const key of keys) {
-      if (key) {
-        index.set(key, model);
-      }
-    }
-  }
-
-  return index;
-}
-
-function modelCapabilityFor(rawModel, capabilityIndex) {
-  const key = modelKey(rawModel);
-
-  return (
-    capabilityIndex.get(key) ??
-    [...capabilityIndex.entries()].find(([candidate]) => key.includes(candidate))?.[1] ??
-    null
-  );
-}
-
-function modelLimitSummaries(sessionDir, llmRequests) {
-  const capabilityIndex = modelCapabilityIndex(sessionDir);
-  if (!capabilityIndex.size || !llmRequests.length) {
-    return [];
-  }
-
-  const byModel = new Map();
-
-  for (const event of llmRequests) {
-    const rawModel = String(event.attrs?.model ?? '')
-      .replace(/^copilot\//i, '')
-      .trim();
-    const displayModel = normalizeModel(rawModel, pricing);
-    const capability = modelCapabilityFor(rawModel || displayModel, capabilityIndex);
-    const limits = capability?.capabilities?.limits ?? {};
-    const supports = capability?.capabilities?.supports ?? {};
-    const current = byModel.get(displayModel) ?? {
-      model: displayModel,
-      rawModels: new Set(),
-      modelId: capability?.id ?? rawModel,
-      vendor: capability?.vendor ?? '',
-      tokenizer: capability?.capabilities?.tokenizer ?? '',
-      contextWindowTokens: Number(limits.max_context_window_tokens ?? 0) || 0,
-      promptLimitTokens: Number(limits.max_prompt_tokens ?? 0) || 0,
-      outputLimitTokens: Number(limits.max_output_tokens ?? 0) || 0,
-      supportedReasoningEfforts: Array.isArray(supports.reasoning_effort)
-        ? supports.reasoning_effort
-        : [],
-      supportedEndpoints: Array.isArray(capability?.supported_endpoints)
-        ? capability.supported_endpoints
-        : [],
-      modelPickerEnabled: Boolean(capability?.model_picker_enabled),
-      isChatDefault: Boolean(capability?.is_chat_default),
-      isChatFallback: Boolean(capability?.is_chat_fallback),
-      modelCalls: 0,
-      largestRawInputTokens: 0,
-      totalRawInputTokens: 0,
-      largestOutputTokens: 0,
-    };
-
-    current.rawModels.add(rawModel || 'unknown');
-    current.modelCalls += 1;
-    current.largestRawInputTokens = Math.max(
-      current.largestRawInputTokens,
-      Number(event.attrs?.inputTokens ?? 0),
-    );
-    current.totalRawInputTokens += Number(event.attrs?.inputTokens ?? 0);
-    current.largestOutputTokens = Math.max(
-      current.largestOutputTokens,
-      Number(event.attrs?.outputTokens ?? 0),
-    );
-    byModel.set(displayModel, current);
-  }
-
-  return [...byModel.values()].map((summary) => ({
-    ...summary,
-    rawModels: [...summary.rawModels],
-    promptLimitShare:
-      summary.promptLimitTokens > 0
-        ? summary.largestRawInputTokens / summary.promptLimitTokens
-        : null,
-    contextWindowShare:
-      summary.contextWindowTokens > 0
-        ? summary.largestRawInputTokens / summary.contextWindowTokens
-        : null,
-    repeatedInputFactor:
-      summary.largestRawInputTokens > 0
-        ? summary.totalRawInputTokens / summary.largestRawInputTokens
-        : 0,
-  }));
-}
-
-function toolName(tool) {
-  return String(tool?.function?.name ?? tool?.name ?? tool?.toolName ?? tool?.id ?? 'unknown_tool');
-}
-
-function toolSchemaSize(tool) {
-  const descriptionChars = charLength(tool?.function?.description ?? tool?.description);
-  const parameterChars = charLength(
-    tool?.function?.parameters ?? tool?.parameters ?? tool?.input_schema,
-  );
-
-  return {
-    name: toolName(tool),
-    descriptionChars,
-    parameterChars,
-    totalChars: charLength(tool),
-  };
-}
-
-function requestOptions(event) {
-  const parsed = parseMaybeJson(event.attrs?.requestOptions);
-  return parsed && typeof parsed === 'object' ? parsed : {};
-}
-
-function reasoningEffort(event) {
-  return String(requestOptions(event)?.reasoning?.effort ?? '').trim();
-}
-
-function textVerbosity(event) {
-  return String(requestOptions(event)?.text?.verbosity ?? '').trim();
-}
-
-function requestShapeMetadata(event) {
-  const shape = parseMaybeJson(event.attrs?.requestShape);
-
-  if (!shape || typeof shape !== 'object') {
-    return null;
-  }
-
-  return {
-    api: shape.api ? String(shape.api) : '',
-    inputItemCount: Number(shape.inputItemCount ?? 0),
-    inputItemTypes: Array.isArray(shape.inputItemTypes)
-      ? shape.inputItemTypes.filter(Boolean).map(String)
-      : [],
-    hasPreviousResponseId: Boolean(shape.hasPreviousResponseId),
-  };
-}
-
-function requestShapeSummary(event) {
-  const shape = requestShapeMetadata(event);
-  if (!shape) {
-    return '';
-  }
-
-  const parts = [
-    shape.api ? `api: ${shape.api}` : '',
-    shape.inputItemCount
-      ? `${shape.inputItemCount.toLocaleString()} input item${shape.inputItemCount === 1 ? '' : 's'}`
-      : '',
-    shape.inputItemTypes.length ? `types: ${shape.inputItemTypes.join(', ')}` : '',
-    shape.hasPreviousResponseId ? 'continues previous response' : '',
-  ].filter(Boolean);
-
-  return parts.join(' · ');
-}
-
-function countedValues(values) {
-  const counts = new Map();
-
-  for (const value of values.filter(Boolean)) {
-    counts.set(value, (counts.get(value) ?? 0) + 1);
-  }
-
-  return [...counts.entries()]
-    .map(([value, count]) => ({ value, count }))
-    .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
-}
-
-function toolPayloadSummary(toolEvents) {
-  const byName = new Map();
-
-  for (const event of toolEvents) {
-    const name = String(
-      event.data?.toolName ?? event.attrs?.toolName ?? event.name ?? event.type ?? 'tool',
-    );
-    const current = byName.get(name) ?? { name, calls: 0, argsChars: 0, resultChars: 0 };
-    current.calls += 1;
-    current.argsChars += charLength(
-      event.attrs?.args ??
-        event.attrs?.arguments ??
-        event.attrs?.input ??
-        event.data?.args ??
-        event.data?.arguments ??
-        event.data?.input,
-    );
-    current.resultChars += charLength(
-      event.attrs?.result ??
-        event.attrs?.output ??
-        event.attrs?.stdout ??
-        event.data?.result ??
-        event.data?.output ??
-        event.data?.stdout,
-    );
-    byName.set(name, current);
-  }
-
-  return [...byName.values()]
-    .sort(
-      (a, b) =>
-        b.resultChars + b.argsChars - (a.resultChars + a.argsChars) || a.name.localeCompare(b.name),
-    )
-    .slice(0, 12);
-}
-
-function requestPayloadSummary(sessionDir, llmRequests, toolEvents) {
-  const systemPromptFiles = [
-    ...new Set(llmRequests.map((event) => event.attrs?.systemPromptFile).filter(Boolean)),
-  ];
-  const toolsFiles = [
-    ...new Set(llmRequests.map((event) => event.attrs?.toolsFile).filter(Boolean)),
-  ];
-  const systemPrompts = systemPromptFiles
-    .map((file) => join(sessionDir, file))
-    .filter(existsSync)
-    .map(parseContentFile);
-  const toolFileSummaries = toolsFiles
-    .map((file) => join(sessionDir, file))
-    .filter(existsSync)
-    .map(parseContentFile);
-  const tools = toolFileSummaries.flatMap((summary) =>
-    Array.isArray(summary.content) ? summary.content : [],
-  );
-  const toolSchemas = tools.map(toolSchemaSize);
-  const mcpToolNames = toolSchemas
-    .map((tool) => tool.name)
-    .filter((name) => name.startsWith('mcp_'));
-  const reasoningEfforts = countedValues(llmRequests.map(reasoningEffort)).map(
-    ({ value, count }) => ({
-      effort: value,
-      count,
-    }),
-  );
-  const subagentLogCount = listFiles(sessionDir, '.jsonl').filter((file) =>
-    basename(file).startsWith('runSubagent-'),
-  ).length;
-
-  return {
-    systemPromptFiles: systemPrompts.length,
-    systemPromptChars: systemPrompts.reduce((sum, summary) => sum + summary.chars, 0),
-    toolSchemaFiles: toolFileSummaries.length,
-    toolSchemaChars: toolFileSummaries.reduce((sum, summary) => sum + summary.chars, 0),
-    toolCount: toolSchemas.length,
-    mcpToolCount: mcpToolNames.length,
-    mcpToolNames: [...new Set(mcpToolNames)].sort(),
-    largestToolSchemas: toolSchemas.sort((a, b) => b.totalChars - a.totalChars).slice(0, 8),
-    modelCallsWithSystemPromptFile: llmRequests.filter((event) => event.attrs?.systemPromptFile)
-      .length,
-    modelCallsWithToolsFile: llmRequests.filter((event) => event.attrs?.toolsFile).length,
-    reasoningEfforts,
-    toolResultCharsByName: toolPayloadSummary(toolEvents),
-    subagentLogCount,
-  };
-}
-
-function contentSummaryFromCache(sessionDir, cache, file) {
-  if (!file) {
-    return null;
-  }
-
-  if (cache.has(file)) {
-    return cache.get(file);
-  }
-
-  const path = join(sessionDir, file);
-  const summary = existsSync(path) ? parseContentFile(path) : null;
-  cache.set(file, summary);
-  return summary;
-}
-
-function modelCallSetupPayloadFactory(sessionDir) {
-  const cache = new Map();
-
-  return (event) => {
-    if (event.type !== 'llm_request') {
-      return null;
-    }
-
-    const systemPromptFile = String(event.attrs?.systemPromptFile ?? '').trim();
-    const toolsFile = String(event.attrs?.toolsFile ?? '').trim();
-
-    if (!systemPromptFile && !toolsFile) {
-      return null;
-    }
-
-    const systemPrompt = contentSummaryFromCache(sessionDir, cache, systemPromptFile);
-    const toolsSummary = contentSummaryFromCache(sessionDir, cache, toolsFile);
-    const tools = Array.isArray(toolsSummary?.content) ? toolsSummary.content : [];
-    const toolSchemas = tools.map(toolSchemaSize);
-    const mcpToolNames = toolSchemas
-      .map((tool) => tool.name)
-      .filter((name) => name.startsWith('mcp_'));
-
-    return {
-      systemPromptFile,
-      systemPromptChars: systemPrompt?.chars ?? 0,
-      toolsFile,
-      toolSchemaChars: toolsSummary?.chars ?? 0,
-      toolCount: toolSchemas.length,
-      mcpToolCount: mcpToolNames.length,
-      mcpToolNames: [...new Set(mcpToolNames)].sort(),
-      largestToolSchemas: toolSchemas.sort((a, b) => b.totalChars - a.totalChars).slice(0, 5),
-    };
-  };
-}
-
-function debugEvidence(llmRequests, agentResponses) {
-  const inputSeries = llmRequests.map((event) => Number(event.attrs?.inputTokens ?? 0));
-  const outputCaps = [
-    ...new Set(
-      llmRequests.map((event) => Number(event.attrs?.maxTokens ?? 0)).filter((value) => value > 0),
-    ),
-  ].sort((a, b) => a - b);
-  const maxInputTokens = Math.max(0, ...inputSeries);
-  const maxRequestTokens = Math.max(0, ...outputCaps);
-  const reasoningEvents = agentResponses.filter((event) =>
-    String(event.attrs?.reasoning ?? '').trim(),
-  ).length;
-  const efforts = countedValues(llmRequests.map(reasoningEffort));
-  const primaryEffort = efforts[0]?.value ?? '';
-
-  return {
-    reasoning: {
-      visible: reasoningEvents > 0 || Boolean(primaryEffort),
-      level: primaryEffort,
-      events: reasoningEvents,
-      source: primaryEffort
-        ? 'llm_request.attrs.requestOptions.reasoning.effort'
-        : reasoningEvents > 0
-          ? 'agent_response.attrs.reasoning'
-          : '',
-      help: primaryEffort
-        ? 'VS Code Agent Debug Logs expose the request reasoning effort in llm_request.attrs.requestOptions.reasoning.effort.'
-        : reasoningEvents > 0
-          ? 'VS Code debug logs include reasoning text on agent_response events, but no request reasoning effort was imported.'
-          : 'No reasoning text field was present on imported agent_response events.',
-    },
-    context: {
-      maxInputTokens,
-      maxRequestTokens,
-      outputCaps,
-      requestCapShare: maxRequestTokens > 0 ? maxInputTokens / maxRequestTokens : null,
-      source:
-        maxRequestTokens > 0
-          ? 'llm_request.attrs.inputTokens and attrs.maxTokens'
-          : 'llm_request.attrs.inputTokens',
-      help:
-        maxRequestTokens > 0
-          ? 'Compares the largest observed input token count with the request maxTokens field present in VS Code debug logs. This is an observed pressure signal, not a provider context-window guarantee.'
-          : 'Largest observed model input token count. The log did not include a request cap to compare against.',
-    },
-  };
+  return sessionParser().eventModelCostFields(rawModel, tokenFields);
 }
 
 export function modelBreakdownFromLlmRequests(llmRequests) {
-  const byModel = new Map();
-
-  for (const event of llmRequests) {
-    const rawModel = String(event.attrs?.model ?? 'unknown')
-      .replace(/^copilot\//i, '')
-      .trim();
-    const displayModel = normalizeModel(rawModel, pricing);
-    const current = byModel.get(displayModel) ?? {
-      model: displayModel,
-      rawModels: new Set(),
-      turns: 0,
-      tokens: { input: 0, cachedInput: 0, cacheWrite: 0, output: 0 },
-      cost: { usd: 0, eur: 0 },
-      costBreakdown: { inputUsd: 0, cachedInputUsd: 0, cacheWriteUsd: 0, outputUsd: 0 },
-      pricingTiers: new Set(),
-      pricingModel: pricingModelForModel(displayModel, pricing, fallbackPricingModel),
-    };
-
-    current.rawModels.add(rawModel || 'unknown');
-    current.turns += 1;
-    const tokenFields = llmTokenFields(event);
-    current.tokens.input += tokenFields.billableInputTokens;
-    current.tokens.cachedInput += tokenFields.cachedInputTokens;
-    current.tokens.cacheWrite += tokenFields.cacheWriteTokens;
-    current.tokens.output += tokenFields.outputTokens;
-    const callCost = costBreakdownUsd(current.pricingModel, {
-      input: tokenFields.billableInputTokens,
-      cachedInput: tokenFields.cachedInputTokens,
-      cacheWrite: tokenFields.cacheWriteTokens,
-      output: tokenFields.outputTokens,
-    });
-    current.costBreakdown.inputUsd += callCost.input;
-    current.costBreakdown.cachedInputUsd += callCost.cachedInput;
-    current.costBreakdown.cacheWriteUsd += callCost.cacheWrite;
-    current.costBreakdown.outputUsd += callCost.output;
-    current.pricingTiers.add(callCost.tier);
-    byModel.set(displayModel, current);
-  }
-
-  return [...byModel.values()].map((entry) => {
-    const usd =
-      entry.costBreakdown.inputUsd +
-      entry.costBreakdown.cachedInputUsd +
-      entry.costBreakdown.cacheWriteUsd +
-      entry.costBreakdown.outputUsd;
-    return {
-      ...entry,
-      rawModels: [...entry.rawModels],
-      pricingTiers: [...entry.pricingTiers],
-      cost: { usd, eur: usd * usdToEur },
-    };
-  });
-}
-
-function sessionModelLabel(modelBreakdown, fallbackModel) {
-  if (modelBreakdown.length === 1) {
-    return modelBreakdown[0].model;
-  }
-
-  if (modelBreakdown.length > 1) {
-    return `Mixed (${modelBreakdown.map((entry) => entry.model).join(', ')})`;
-  }
-
-  return normalizeModel(fallbackModel, pricing);
-}
-
-function estimateTokens(text) {
-  const compact = String(text ?? '').trim();
-  if (!compact) {
-    return 0;
-  }
-
-  return Math.max(1, Math.round(Math.max(compact.split(/\s+/).length * 1.35, compact.length / 4)));
+  return sessionParser().modelBreakdownFromLlmRequests(llmRequests);
 }
 
 function timestampForEvent(event) {
-  return event?.timestamp ?? new Date(Number(event?.ts ?? 0)).toISOString();
+  return sessionParser().timestampForEvent(event);
 }
 
-function eventDetail(event) {
-  if (event.type === 'llm_request') {
-    return `${event.attrs?.model ?? 'model'}: ${Number(event.attrs?.inputTokens ?? 0).toLocaleString()} raw in / ${Number(
-      event.attrs?.outputTokens ?? 0,
-    ).toLocaleString()} out`;
-  }
-
-  if (String(event.type ?? '').includes('tool')) {
-    return String(event.data?.toolName ?? event.attrs?.toolName ?? event.name ?? event.type);
-  }
-
-  if (event.type === 'user_message') {
-    return String(event.attrs?.content ?? '').slice(0, 140);
-  }
-
-  if (event.type === 'agent_response') {
-    return parseAssistantResponse(event.attrs?.response).slice(0, 140);
-  }
-
-  return String(event.attrs?.details ?? event.name ?? event.type ?? '').slice(0, 140);
-}
-
-function boundedText(value, maxLength = 260) {
-  const compact = String(value ?? '')
-    .replace(/\s+/g, ' ')
-    .trim();
-  return compact.length > maxLength ? `${compact.slice(0, maxLength - 1)}...` : compact;
-}
-
-function summaryValue(value) {
-  if (value === undefined || value === null || value === '') {
-    return '';
-  }
-
-  if (typeof value === 'string') {
-    return boundedText(value);
-  }
-
-  if (typeof value === 'number' || typeof value === 'boolean') {
-    return String(value);
-  }
-
-  return boundedText(JSON.stringify(compactObject(value)));
-}
-
-function sourceEstimatedCost(event) {
-  return summaryValue(event.attrs?.estimatedCost);
-}
-
-function sourceUsageFromNanoAiu(event) {
-  const nanoAiu = Number(event.attrs?.copilotUsageNanoAiu ?? 0);
-  if (!Number.isFinite(nanoAiu) || nanoAiu <= 0) {
-    return null;
-  }
-
-  const credits = nanoAiu / 1_000_000_000;
-
-  return {
-    nanoAiu,
-    credits,
-    usd: credits * 0.01,
-    modelCalls: 1,
-  };
-}
-
-function sourceUsageSummary(llmRequests) {
-  const usages = llmRequests.map(sourceUsageFromNanoAiu).filter(Boolean);
-  const nanoAiu = usages.reduce((sum, usage) => sum + usage.nanoAiu, 0);
-  const credits = nanoAiu / 1_000_000_000;
-
-  return {
-    nanoAiu,
-    credits,
-    usd: credits * 0.01,
-    modelCalls: usages.length,
-  };
-}
-
-function compactObject(value) {
-  if (!value || typeof value !== 'object') {
-    return value;
-  }
-
-  const result = {};
-  const skip = new Set(['content', 'response', 'result', 'output', 'stdout', 'stderr']);
-
-  for (const [key, nestedValue] of Object.entries(value)) {
-    if (skip.has(key)) {
-      continue;
-    }
-
-    if (nestedValue === undefined || nestedValue === null) {
-      continue;
-    }
-
-    result[key] =
-      typeof nestedValue === 'object'
-        ? boundedText(JSON.stringify(nestedValue), 120)
-        : boundedText(nestedValue, 120);
-
-    if (Object.keys(result).length >= 6) {
-      break;
-    }
-  }
-
-  return result;
-}
-
-function eventAttributeSummary(event) {
-  const attrs = event.attrs ?? {};
-  const data = event.data ?? {};
-  const candidates = [
-    ['category', attrs.category],
-    ['source', attrs.source],
-    ['model', attrs.model],
-    ['debugName', attrs.debugName],
-    ['inputTokens', attrs.inputTokens],
-    ['cachedTokens', attrs.cachedTokens ?? attrs.cachedInputTokens ?? attrs.cacheReadTokens],
-    ['cacheWriteTokens', attrs.cacheWriteTokens ?? attrs.cachedWriteTokens],
-    ['outputTokens', attrs.outputTokens],
-    ['sourceEstimatedCost', attrs.estimatedCost],
-    ['copilotUsageNanoAiu', attrs.copilotUsageNanoAiu],
-    ['reasoningEffort', event.type === 'llm_request' ? reasoningEffort(event) : undefined],
-    ['textVerbosity', event.type === 'llm_request' ? textVerbosity(event) : undefined],
-    ['requestShape', event.type === 'llm_request' ? requestShapeSummary(event) : undefined],
-    ['maxTokens', attrs.maxTokens],
-    ['ttft', attrs.ttft],
-    ['systemPromptFile', attrs.systemPromptFile],
-    ['toolsFile', attrs.toolsFile],
-    ['vscodeVersion', attrs.vscodeVersion],
-    ['copilotVersion', attrs.copilotVersion],
-    ['responseId', attrs.responseId],
-    ['logVersion', event.v],
-    ['toolName', data.toolName ?? attrs.toolName],
-    ['details', attrs.details],
-    ['content', attrs.content],
-    [
-      'response',
-      event.type === 'agent_response' ? parseAssistantResponse(attrs.response) : undefined,
-    ],
-    ['data', data && Object.keys(data).length ? data : undefined],
-  ];
-
-  const fields = [];
-  const seen = new Set();
-
-  for (const [label, value] of candidates) {
-    const summarized = summaryValue(value);
-
-    if (!summarized || seen.has(label)) {
-      continue;
-    }
-
-    fields.push({ label, value: summarized });
-    seen.add(label);
-
-    if (fields.length >= 8) {
-      break;
-    }
-  }
-
-  return fields;
+export function sessionFromDebugLog(sessionDir, workspaceDir) {
+  return sessionParser().sessionFromDebugLog(sessionDir, workspaceDir);
 }
 
-function capTraceEvents(events) {
-  return events.slice(0, traceEventLimit);
+export function sessionFromChatSnapshot(file, workspaceDir) {
+  return sessionParser().sessionFromChatSnapshot(file, workspaceDir);
 }
 
 function workspaceName(workspaceDir) {
@@ -1329,397 +450,42 @@ function workspaceName(workspaceDir) {
   return folder ? basename(folder) : basename(workspaceDir);
 }
 
-function parseAssistantResponse(raw) {
-  const parsed = typeof raw === 'string' ? safeJson(raw) : raw;
-  if (!Array.isArray(parsed)) {
-    return String(raw ?? '');
-  }
-
-  return parsed
-    .flatMap((message) => message?.parts ?? [])
-    .map((part) => {
-      const content =
-        typeof part?.content === 'string'
-          ? (safeJson(part.content) ?? part.content)
-          : part?.content;
-      return typeof content === 'object' && content?.text ? content.text : String(content ?? '');
-    })
-    .filter(Boolean)
-    .join('\n');
-}
-
-export function sessionFromDebugLog(sessionDir, workspaceDir) {
-  const main = readJsonl(join(sessionDir, 'main.jsonl'));
-  if (!main.length) {
-    diagnostics.skippedEmptyDebugLogs += 1;
-    return null;
-  }
-
-  const sid = basename(sessionDir);
-  const userMessages = main.filter((event) => event.type === 'user_message');
-  const llmRequests = main.filter((event) => event.type === 'llm_request');
-  const assistantEvents = main.filter(
-    (event) => event.type === 'agent_response' || event.type === 'assistant.message',
-  );
-  const toolEvents = main.filter((event) => String(event.type ?? '').includes('tool'));
-  const errorEvents = main.filter((event) => event.status && event.status !== 'ok');
-
-  if (!userMessages.length && !llmRequests.length && !assistantEvents.length) {
-    diagnostics.skippedEmptyDebugLogs += 1;
-    return null;
+function workspaceFolderPath(workspaceDir) {
+  const workspaceJson = join(workspaceDir, 'workspace.json');
+  const raw = existsSync(workspaceJson) ? safeJson(readFileSync(workspaceJson, 'utf8')) : null;
+  if (!raw?.folder) {
+    return '';
   }
 
-  const firstUserMessage = userMessages[0]?.attrs?.content ?? 'Untitled Copilot session';
-  const modelBreakdown = modelBreakdownFromLlmRequests(llmRequests);
-  const model = sessionModelLabel(
-    modelBreakdown,
-    llmRequests.find((event) => event.attrs?.model)?.attrs?.model,
-  );
-  const input = llmRequests.reduce(
-    (sum, event) => sum + llmTokenFields(event).billableInputTokens,
-    0,
-  );
-  const cachedInput = llmRequests.reduce(
-    (sum, event) => sum + llmTokenFields(event).cachedInputTokens,
-    0,
-  );
-  const cacheWrite = llmRequests.reduce(
-    (sum, event) => sum + llmTokenFields(event).cacheWriteTokens,
-    0,
-  );
-  const output = llmRequests.reduce((sum, event) => sum + llmTokenFields(event).outputTokens, 0);
-  const tokens = { input, cachedInput, cacheWrite, output };
-  const usd = modelBreakdown.length
-    ? modelBreakdown.reduce((sum, entry) => sum + entry.cost.usd, 0)
-    : costUsd(model, tokens);
-  const startEvent = main.find((event) => event.type === 'session_start') ?? main[0];
-  const debugLogRuntime = {
-    logVersion: Number(startEvent?.v ?? 0) || 0,
-    vscodeVersion: String(startEvent?.attrs?.vscodeVersion ?? '').trim(),
-    copilotVersion: String(startEvent?.attrs?.copilotVersion ?? '').trim(),
-  };
-  const lastEvent = main[main.length - 1];
-  const startedAt =
-    startEvent?.timestamp ??
-    new Date(
-      Number(startEvent?.ts ?? statSync(join(sessionDir, 'main.jsonl')).mtimeMs),
-    ).toISOString();
-  const endedAt =
-    lastEvent?.timestamp ??
-    new Date(
-      Number(lastEvent?.ts ?? statSync(join(sessionDir, 'main.jsonl')).mtimeMs),
-    ).toISOString();
-  const evidence = debugEvidence(llmRequests, assistantEvents, main);
-  const payload = requestPayloadSummary(sessionDir, llmRequests, toolEvents);
-  const modelLimits = modelLimitSummaries(sessionDir, llmRequests);
-  const cacheTokenAudit = cacheTokenAuditFromLlmRequests(llmRequests);
-  const sourceUsage = sourceUsageSummary(llmRequests);
-  const setupPayloadForEvent = modelCallSetupPayloadFactory(sessionDir);
-  const transcript = transcriptAvailability(workspaceDir, sid);
-  const memoryRecalls = memoryRecallsFromDebugLog(sessionDir, workspaceName(workspaceDir));
-
-  if (transcript.available) {
-    diagnostics.debugLogSessionsWithTranscripts += 1;
-    diagnostics.transcriptEventsAvailable += transcript.eventCount;
+  try {
+    const value = String(raw.folder);
+    if (!value.startsWith('file:')) {
+      return '';
+    }
+    const folder = decodeURIComponent(value.replace(/^file:\/+/, ''));
+    const resolved = platform() === 'win32' ? folder.replace(/^\//, '') : `/${folder.replace(/^\/+/, '')}`;
+    return isAbsolute(resolved) && existsSync(resolved) ? resolved : '';
+  } catch {
+    return '';
   }
+}
 
-  if (cacheTokenAudit.invalidCachedTokenSplits > 0) {
-    diagnostics.warnings.push(
-      `${sessionDir}: ${cacheTokenAudit.invalidCachedTokenSplits} model call(s) reported cachedTokens greater than inputTokens; cached input was clamped for pricing safety`,
-    );
+function normalizedWorkspaceFolderScope(workspaceFolders) {
+  if (!Array.isArray(workspaceFolders)) {
+    return new Set();
   }
-
-  const turns = [
-    ...userMessages.map((event) => ({
-      role: 'user',
-      text: String(event.attrs?.content ?? ''),
-      tokens: estimateTokens(event.attrs?.content),
-    })),
-    ...assistantEvents.map((event) => {
-      const text =
-        event.type === 'assistant.message'
-          ? event.data?.content
-          : parseAssistantResponse(event.attrs?.response);
-      return { role: 'assistant', text: String(text ?? ''), tokens: estimateTokens(text) };
-    }),
-  ].filter((turn) => turn.text.trim());
-
-  return {
-    id: sid,
-    sourceKind: 'vscode-copilot-debug-log',
-    tokenSource: llmRequests.length
-      ? 'llm_request_token_totals'
-      : 'debug-log-visible-text-estimate',
-    sessionType: 'Local',
-    location: 'Chat Panel',
-    status: 'Idle',
-    title: firstUserMessage.slice(0, 80),
-    firstPrompt: firstUserMessage.slice(0, 240),
-    workspace: workspaceName(workspaceDir),
-    sourcePath: sessionDir,
-    ...(debugLogRuntime.logVersion ||
-    debugLogRuntime.vscodeVersion ||
-    debugLogRuntime.copilotVersion
-      ? { debugLogRuntime }
-      : {}),
-    model,
-    modelBreakdown,
-    startedAt,
-    endedAt,
-    tags: ['debug-log', llmRequests.length ? 'llm-request-token-totals' : 'estimated-visible-text'],
-    toolsUsed: [
-      ...new Set(
-        toolEvents
-          .map((event) => event.data?.toolName ?? event.attrs?.toolName ?? event.name)
-          .filter(Boolean),
-      ),
-    ],
-    tokens,
-    cost: { usd, eur: usd * usdToEur },
-    confidence: llmRequests.length ? 'exact' : 'estimated',
-    traceSummary: {
-      modelTurns: llmRequests.length,
-      toolCalls: toolEvents.length,
-      totalTokens: input + cachedInput + cacheWrite + output,
-      errors: errorEvents.length,
-      totalEvents: main.length,
-      reasoningEvents: evidence.reasoning.events,
-      maxInputTokens: evidence.context.maxInputTokens,
-      maxRequestTokens: evidence.context.maxRequestTokens,
-      reasoningEfforts: payload.reasoningEfforts,
-    },
-    cacheTokenAudit,
-    ...(sourceUsage.modelCalls > 0 ? { sourceUsage } : {}),
-    transcript,
-    advancedSignals: evidence,
-    requestPayload: payload,
-    modelLimits,
-    ...(memoryRecalls.length ? { memoryRecalls } : {}),
-    traceEvents: capTraceEvents(
-      main.map((event, index) => {
-        const tokenFields =
-          event.type === 'llm_request'
-            ? llmTokenFields(event)
-            : {
-                inputTokens: 0,
-                billableInputTokens: 0,
-                cachedInputTokens: 0,
-                cacheWriteTokens: 0,
-                outputTokens: 0,
-              };
-
-        const setupPayload = setupPayloadForEvent(event);
-        const sourceUsage = sourceUsageFromNanoAiu(event);
-        const requestShape = event.type === 'llm_request' ? requestShapeMetadata(event) : null;
-
-        return {
-          index,
-          timestamp: timestampForEvent(event),
-          type: String(event.type ?? 'unknown'),
-          name: String(event.name ?? event.type ?? 'unknown'),
-          status: String(event.status ?? 'unknown'),
-          detail: eventDetail(event),
-          attributes: eventAttributeSummary(event),
-          inputTokens: tokenFields.inputTokens,
-          cachedInputTokens: tokenFields.cachedInputTokens,
-          cacheWriteTokens: tokenFields.cacheWriteTokens,
-          outputTokens: tokenFields.outputTokens,
-          ttftMs: event.type === 'llm_request' ? Number(event.attrs?.ttft ?? 0) : 0,
-          maxTokens: event.type === 'llm_request' ? Number(event.attrs?.maxTokens ?? 0) : 0,
-          hasReasoning:
-            event.type === 'agent_response' && Boolean(String(event.attrs?.reasoning ?? '').trim()),
-          reasoningEffort: event.type === 'llm_request' ? reasoningEffort(event) : '',
-          ...(requestShape ? { requestShape } : {}),
-          ...(event.type === 'llm_request'
-            ? eventModelCostFields(event.attrs?.model, tokenFields)
-            : {}),
-          ...(event.type === 'llm_request' && sourceEstimatedCost(event)
-            ? { sourceEstimatedCost: sourceEstimatedCost(event) }
-            : {}),
-          ...(sourceUsage ? { sourceUsage } : {}),
-          ...(setupPayload ? { setupPayload } : {}),
-        };
-      }),
-    ),
-    turns: turns.slice(0, 60),
-  };
+  return new Set(workspaceFolders.map(normalizeWorkspacePath).filter(Boolean));
 }
 
-export function sessionFromChatSnapshot(file, workspaceDir) {
-  const records = readJsonl(file);
-  const snapshot =
-    records.find((record) => record.kind === 0 && record.v?.requests)?.v ??
-    records[0]?.v ??
-    records[0];
-  const requests = snapshot?.requests ?? [];
-
-  if (!requests.length) {
-    diagnostics.skippedChatSnapshotsWithoutRequests += 1;
-    return null;
+function normalizeWorkspacePath(path) {
+  if (!path) {
+    return '';
+  }
+  try {
+    return resolve(String(path)).toLowerCase();
+  } catch {
+    return '';
   }
-
-  const firstRequest = requests[0];
-  const firstPrompt =
-    firstRequest?.message?.text ?? snapshot?.customTitle ?? 'Untitled Copilot session';
-  const model = normalizeModel(
-    firstRequest?.modelId ?? firstRequest?.inputState?.selectedModel?.identifier,
-    pricing,
-  );
-  const output = requests.reduce((sum, request) => sum + Number(request.completionTokens ?? 0), 0);
-  const input = requests.reduce(
-    (sum, request) => sum + estimateTokens(request?.message?.text ?? ''),
-    0,
-  );
-  const tokens = { input, cachedInput: 0, cacheWrite: 0, output };
-  const usd = costUsd(model, tokens);
-  const pricingModel = pricingModelForModel(model, pricing, fallbackPricingModel);
-  const startedAt = new Date(Number(snapshot.creationDate ?? statSync(file).mtimeMs)).toISOString();
-  const endedAt = statSync(file).mtime.toISOString();
-
-  return {
-    id: basename(file, '.jsonl'),
-    sourceKind: 'vscode-chat-session-snapshot',
-    tokenSource: 'chat-snapshot-output-plus-visible-input-estimate',
-    sessionType: 'Local',
-    location: 'Chat Panel',
-    status: 'Idle',
-    title: String(snapshot.customTitle ?? firstPrompt).slice(0, 80),
-    firstPrompt: String(firstPrompt).slice(0, 240),
-    workspace: workspaceName(workspaceDir),
-    sourcePath: file,
-    model,
-    modelBreakdown: [
-      {
-        model,
-        rawModels: [
-          String(
-            firstRequest?.modelId ?? firstRequest?.inputState?.selectedModel?.identifier ?? model,
-          ),
-        ],
-        turns: requests.length,
-        tokens,
-        cost: { usd, eur: usd * usdToEur },
-        pricingModel,
-      },
-    ],
-    startedAt,
-    endedAt,
-    tags: ['chat-session', 'estimated-input'],
-    toolsUsed: [],
-    tokens,
-    cost: { usd, eur: usd * usdToEur },
-    confidence: 'estimated',
-    traceSummary: {
-      modelTurns: requests.length,
-      toolCalls: 0,
-      totalTokens: input + output,
-      errors: 0,
-      totalEvents: records.length,
-      reasoningEvents: 0,
-      maxInputTokens: input,
-      maxRequestTokens: 0,
-    },
-    cacheTokenAudit: {
-      modelCalls: 0,
-      callsWithCachedTokens: 0,
-      invalidCachedTokenSplits: 0,
-      rawInputTokens: 0,
-      normalInputTokens: 0,
-      cachedInputTokens: 0,
-      cacheWriteTokens: 0,
-      outputTokens: 0,
-      maxCachedInputShare: 0,
-    },
-    transcript: {
-      available: false,
-      sourcePath: '',
-      eventCount: 0,
-    },
-    advancedSignals: {
-      reasoning: {
-        visible: false,
-        level: '',
-        events: 0,
-        source: '',
-        help: 'Chat snapshots do not expose agent_response reasoning text or a reasoning-level field.',
-      },
-      context: {
-        maxInputTokens: input,
-        maxRequestTokens: 0,
-        outputCaps: [],
-        requestCapShare: null,
-        source: 'estimated visible chat text',
-        help: 'Chat snapshots only provide visible text context here, so context pressure is not reliable for cost debugging.',
-      },
-    },
-    traceEvents: capTraceEvents(
-      requests.flatMap((request, index) => {
-        const rawRequestModel =
-          request?.modelId ?? request?.inputState?.selectedModel?.identifier ?? model;
-        const userInputTokens = estimateTokens(request?.message?.text ?? '');
-        const assistantOutputTokens = Number(request.completionTokens ?? 0);
-
-        return [
-          {
-            index: index * 2,
-            timestamp: startedAt,
-            type: 'user_message',
-            name: 'user_message',
-            status: 'ok',
-            detail: String(request?.message?.text ?? '').slice(0, 140),
-            inputTokens: userInputTokens,
-            cachedInputTokens: 0,
-            cacheWriteTokens: 0,
-            outputTokens: 0,
-            ...eventModelCostFields(rawRequestModel, {
-              inputTokens: userInputTokens,
-              billableInputTokens: userInputTokens,
-              cachedInputTokens: 0,
-              cacheWriteTokens: 0,
-              outputTokens: 0,
-            }),
-          },
-          {
-            index: index * 2 + 1,
-            timestamp: endedAt,
-            type: 'assistant_response',
-            name: 'assistant_response',
-            status: 'ok',
-            detail: `${assistantOutputTokens.toLocaleString()} completion tokens`,
-            inputTokens: 0,
-            cachedInputTokens: 0,
-            cacheWriteTokens: 0,
-            outputTokens: assistantOutputTokens,
-            ...eventModelCostFields(rawRequestModel, {
-              inputTokens: 0,
-              billableInputTokens: 0,
-              cachedInputTokens: 0,
-              cacheWriteTokens: 0,
-              outputTokens: assistantOutputTokens,
-            }),
-          },
-        ];
-      }),
-    ),
-    turns: requests
-      .flatMap((request) => [
-        {
-          role: 'user',
-          text: String(request?.message?.text ?? ''),
-          tokens: estimateTokens(request?.message?.text),
-        },
-        {
-          role: 'assistant',
-          text: (request?.response ?? [])
-            .map((part) => part.value ?? part.generatedTitle ?? part.kind ?? '')
-            .filter(Boolean)
-            .join('\n'),
-          tokens: Number(request.completionTokens ?? 0),
-        },
-      ])
-      .filter((turn) => turn.text.trim())
-      .slice(0, 60),
-  };
 }
 
 function enrichSessionFromWorkspaceState(session, stateBySessionId) {
@@ -1767,66 +533,61 @@ function enrichSessionFromWorkspaceState(session, stateBySessionId) {
   };
 }
 
-function parseWorkspace(workspaceDir) {
-  diagnostics.scannedWorkspaces += 1;
-  const stateBySessionId = readWorkspaceState(workspaceDir);
-  const workspace = workspaceName(workspaceDir);
-  const debugRoot = join(workspaceDir, 'GitHub.copilot-chat', 'debug-logs');
-  const debugSessions = listDirs(debugRoot)
-    .map((sessionDir) => sessionFromDebugLog(sessionDir, workspaceDir))
-    .filter(Boolean)
-    .map((session) => enrichSessionFromWorkspaceState(session, stateBySessionId));
-  const debugIds = new Set(debugSessions.map((session) => session.id));
-  diagnostics.importedDebugLogSessions += debugSessions.length;
-
-  const chatSessions = listFiles(join(workspaceDir, 'chatSessions'), '.jsonl')
-    .map((file) => {
-      const session = sessionFromChatSnapshot(file, workspaceDir);
-      if (session && debugIds.has(session.id)) {
-        diagnostics.skippedDuplicateChatSnapshots += 1;
-        return null;
-      }
-      return session ? enrichSessionFromWorkspaceState(session, stateBySessionId) : null;
-    })
-    .filter(Boolean);
-  diagnostics.importedChatSnapshotSessions += chatSessions.length;
+function customizationInventoryScanner() {
+  return createCustomizationInventoryScanner({
+    diagnostics: () => diagnostics,
+    listDirs,
+    listFilesRecursive,
+    readJsonl,
+    workspaceFolderPath,
+    workspaceName,
+  });
+}
 
-  return {
-    sessions: [...debugSessions, ...chatSessions],
-    memories: memoriesFromRoot(
-      join(workspaceDir, 'GitHub.copilot-chat', 'memory-tool', 'memories'),
-      'workspace',
-      workspace,
-    ),
-  };
+function customizationsFromWorkspace(workspaceDir, options = {}) {
+  return customizationInventoryScanner().customizationsFromWorkspace(workspaceDir, options);
 }
 
-function workspaceDirsFromUserDir(userDir) {
-  const workspaceStorage = join(userDir, 'workspaceStorage');
-  return listDirs(workspaceStorage);
+function customizationsFromDiscoveryFolders(debugRoot, workspace, options = {}) {
+  return customizationInventoryScanner().customizationsFromDiscoveryFolders(debugRoot, workspace, options);
 }
 
-function workspaceDirsForRoot(root) {
-  if (existsSync(join(root, 'workspace.json'))) {
-    return [root];
-  }
-  if (basename(root) === 'workspaceStorage') {
-    return listDirs(root);
-  }
-  return workspaceDirsFromUserDir(root);
+function customizationsFromDebugReferences(debugRoot, bases, workspace, options = {}) {
+  return customizationInventoryScanner().customizationsFromDebugReferences(debugRoot, bases, workspace, options);
 }
 
-function userDirForRoot(root) {
-  if (existsSync(join(root, 'workspaceStorage'))) {
-    return root;
-  }
-  if (basename(root) === 'workspaceStorage') {
-    return dirname(root);
-  }
-  if (basename(dirname(root)) === 'workspaceStorage') {
-    return dirname(dirname(root));
-  }
-  return null;
+function customizationEvidenceFromDebugLogs(
+  debugRoot,
+  customizations,
+  workspace = '',
+  workspaceDir = '',
+  onProgress = () => {},
+  evidenceOptions = {},
+) {
+  return customizationEvidenceFromDebugLogsCore(debugRoot, customizations, workspace, workspaceDir, onProgress, {
+    ...evidenceOptions,
+    diagnostics,
+    listDirs,
+    readJsonl,
+  });
+}
+
+function workspaceScannerDependencies() {
+  return {
+    customizationsFromDebugReferences,
+    customizationsFromDiscoveryFolders,
+    customizationsFromWorkspace,
+    customizationEvidenceFromDebugLogs,
+    diagnostics,
+    enrichSessionFromWorkspaceState,
+    listDirs,
+    listFiles,
+    memoriesFromRoot,
+    readWorkspaceState,
+    sessionFromChatSnapshot,
+    sessionFromDebugLog,
+    workspaceName,
+  };
 }
 
 /**
@@ -1843,7 +604,7 @@ export async function scanVsCodeSessions(options = {}) {
   if (!Array.isArray(configuredRoots)) {
     throw new TypeError('roots must be an array of VS Code user-data or workspace-storage paths.');
   }
-  const roots = [...new Set(configuredRoots.map((root) => resolve(String(root))))];
+  const roots = uniqueResolvedRoots(configuredRoots);
   const conversionRate = Number(options.usdToEur ?? process.env.USD_TO_EUR ?? 1);
   if (!Number.isFinite(conversionRate) || conversionRate <= 0) {
     throw new TypeError('usdToEur must be a positive number.');
@@ -1860,11 +621,73 @@ export async function scanVsCodeSessions(options = {}) {
   diagnostics = createDiagnostics();
   diagnostics.scannedRoots = roots;
   usdToEur = conversionRate;
+  const onProgress = typeof options.onProgress === 'function' ? options.onProgress : () => {};
+  const workspaceOptions = {
+    includeCustomizations: options.includeCustomizations !== false,
+    includeSystemCustomizations: options.includeSystemCustomizations === true,
+    customizationDiscovery: options.customizationDiscovery ?? null,
+    customizationEvidence: options.customizationEvidence ?? {},
+    incrementalSince: options.incrementalSince ?? '',
+  };
 
   try {
+    onProgress({
+      stage: 'roots',
+      message: `Scanning ${roots.length} VS Code root${roots.length === 1 ? '' : 's'}.`,
+      roots,
+    });
     DatabaseSync = options.sqlite === false ? null : await loadSqliteSupport();
-    const workspaceDirs = [...new Set(roots.flatMap(workspaceDirsForRoot))];
-    const workspaceResults = workspaceDirs.map(parseWorkspace);
+    let workspaceDirs = [
+      ...new Set(roots.flatMap((root) => workspaceDirsForRoot(root, traversalOptions()))),
+    ];
+    const workspaceFolderScope = normalizedWorkspaceFolderScope(options.workspaceFolders);
+    if (workspaceFolderScope.size) {
+      const scopedWorkspaceDirs = dedupeWorkspaceDirsByFolder(
+        workspaceDirs.filter((workspaceDir) =>
+          workspaceFolderScope.has(normalizeWorkspacePath(workspaceFolderPath(workspaceDir))),
+        ),
+      );
+      onProgress({
+        stage: 'workspace-scope',
+        message: `Current workspace scope matched ${scopedWorkspaceDirs.length} VS Code storage entr${scopedWorkspaceDirs.length === 1 ? 'y' : 'ies'}.`,
+        total: scopedWorkspaceDirs.length,
+      });
+      workspaceDirs = scopedWorkspaceDirs;
+    } else if (options.requireWorkspaceFolders === true) {
+      onProgress({
+        stage: 'workspace-scope',
+        message: 'No current VS Code workspace folder was provided; skipping broad customization evidence scan.',
+        total: 0,
+      });
+      workspaceDirs = [];
+    }
+    onProgress({
+      stage: 'workspaces',
+      message: `Found ${workspaceDirs.length} VS Code storage entr${workspaceDirs.length === 1 ? 'y' : 'ies'}.`,
+      total: workspaceDirs.length,
+    });
+    const workspaceResults = [];
+    for (const [index, workspaceDir] of workspaceDirs.entries()) {
+      if (index > 0 && index % 50 === 0) {
+        onProgress({
+          stage: 'workspace-queue',
+          message: `Checked ${index}/${workspaceDirs.length} VS Code storage entries.`,
+          index,
+          total: workspaceDirs.length,
+        });
+      }
+      workspaceResults.push(parseWorkspaceEntry(
+        workspaceDir,
+        {
+          ...workspaceOptions,
+          workspaceIndex: index + 1,
+          workspaceTotal: workspaceDirs.length,
+        },
+        onProgress,
+        workspaceScannerDependencies(),
+      ));
+      await yieldToRuntime();
+    }
     const sessions = workspaceResults
       .flatMap((result) => result.sessions)
       .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
@@ -1875,6 +698,11 @@ export async function scanVsCodeSessions(options = {}) {
         .map((userDir) => join(userDir, 'globalStorage', 'github.copilot-chat', 'memory-tool', 'memories')),
     )];
     const memoryMap = new Map();
+    onProgress({
+      stage: 'memories',
+      message: `Indexing memories from ${globalMemoryRoots.length} global root${globalMemoryRoots.length === 1 ? '' : 's'} and VS Code storage.`,
+      total: globalMemoryRoots.length,
+    });
     for (const memory of [
       ...workspaceResults.flatMap((result) => result.memories),
       ...globalMemoryRoots.flatMap((root) => memoriesFromRoot(root, 'global')),
@@ -1884,6 +712,19 @@ export async function scanVsCodeSessions(options = {}) {
     const memories = attachMemoryRecalls([...memoryMap.values()], sessions).sort((a, b) =>
       b.modifiedAt.localeCompare(a.modifiedAt),
     );
+    const customizationMap = new Map();
+    for (const customization of workspaceResults.flatMap((result) => result.customizations)) {
+      customizationMap.set(
+        customization.id,
+        mergeCustomizationRecords(customizationMap.get(customization.id), customization),
+      );
+    }
+    const customizations = [...customizationMap.values()].sort(
+      (a, b) =>
+        statusRank(b.evidenceStatus) - statusRank(a.evidenceStatus) ||
+        b.modifiedAt.localeCompare(a.modifiedAt),
+    );
+    diagnostics.importedCustomizations = customizations.length;
     const seenIds = new Set();
     for (const session of sessions) {
       if (seenIds.has(session.id)) {
@@ -1892,6 +733,13 @@ export async function scanVsCodeSessions(options = {}) {
       seenIds.add(session.id);
     }
 
+    onProgress({
+      stage: 'complete',
+      message: `Scan complete: imported ${sessions.length} session${sessions.length === 1 ? '' : 's'}.`,
+      sessions: sessions.length,
+      workspaces: workspaceDirs.length,
+    });
+
     return {
       schemaVersion: sessionDataSchemaVersion,
       generatedAt,
@@ -1901,11 +749,15 @@ export async function scanVsCodeSessions(options = {}) {
       ingestion: {
         ...diagnostics,
         importedSessions: sessions.length,
+        scanKind: options.incrementalSince ? 'incremental' : 'full',
+        incrementalSince: options.incrementalSince ?? '',
+        customizationEvidenceAnalyzedAt: options.includeCustomizations !== false ? generatedAt : '',
         cacheTokenAudit: mergeCacheTokenAudits(
           sessions.map((session) => session.cacheTokenAudit).filter(Boolean),
         ),
       },
       memories,
+      customizations,
       sessions,
     };
   } finally {
@@ -1916,6 +768,26 @@ export async function scanVsCodeSessions(options = {}) {
   }
 }
 
+function yieldToRuntime() {
+  return new Promise((resolveYield) => setImmediate(resolveYield));
+}
+
+function dedupeWorkspaceDirsByFolder(workspaceDirs) {
+  const seen = new Set();
+  const deduped = [];
+  for (const workspaceDir of workspaceDirs) {
+    const folder = normalizeWorkspacePath(workspaceFolderPath(workspaceDir));
+    const key = folder || normalizeWorkspacePath(workspaceDir);
+    if (seen.has(key)) {
+      diagnostics.warnings.push(`Duplicate VS Code storage entry skipped for current workspace: ${workspaceDir}`);
+      continue;
+    }
+    seen.add(key);
+    deduped.push(workspaceDir);
+  }
+  return deduped;
+}
+
 export function writeSessionData(sessionData, outputFile = 'public/data/sessions.json') {
   const resolvedOutputFile = resolve(outputFile);
   mkdirSync(dirname(resolvedOutputFile), { recursive: true });
@@ -1923,16 +795,56 @@ export function writeSessionData(sessionData, outputFile = 'public/data/sessions
   return resolvedOutputFile;
 }
 
-export async function runScannerCli(args = process.argv.slice(2), logger = console) {
-  const outputFile = args[0] ?? 'public/data/sessions.json';
-  const roots = args.slice(1);
-  const sessionData = await scanVsCodeSessions(roots.length ? { roots } : {});
-  const resolvedOutputFile = writeSessionData(sessionData, outputFile);
+export async function runScannerCli(args = process.argv.slice(2), logger = console, dependencies = {}) {
+  const { outputFile, roots } = parseScannerCliArgs(args);
+  const scanner = dependencies.scanner ?? scanVsCodeSessions;
+  const writer = dependencies.writer ?? writeSessionData;
+  const sessionData = await scanner(roots.length ? { roots } : {});
+  const resolvedOutputFile = writer(sessionData, outputFile);
 
   logger.log(`Wrote ${sessionData.sessions.length} sessions to ${resolvedOutputFile}`);
   return sessionData;
 }
 
+function parseScannerCliArgs(args) {
+  let outputFile = '';
+  const roots = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    const [flag, inlineValue] = argument.split('=', 2);
+    if (flag === '--output' || flag === '--root') {
+      const value = inlineValue ?? args[index + 1];
+      if (!value) {
+        throw new Error(`${flag} requires a value.`);
+      }
+      if (inlineValue === undefined) {
+        index += 1;
+      }
+      if (flag === '--output') {
+        outputFile = value;
+      } else {
+        roots.push(value);
+      }
+      continue;
+    }
+
+    if (argument.startsWith('-')) {
+      throw new Error(`Unknown option: ${argument}`);
+    }
+    if (!outputFile) {
+      outputFile = argument;
+    } else {
+      roots.push(argument);
+    }
+  }
+
+  return {
+    outputFile: outputFile || 'public/data/sessions.json',
+    roots,
+  };
+}
+
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   await runScannerCli();
 }