copilot-usage-studio 0.2.1 → 0.2.3

package/docs/local-deployment.md

@@ -2,7 +2,7 @@
 
 The app is intended to run locally, near the VS Code data it reads. It should not require a hosted SaaS backend for the core workflow.
 
-Current release posture: early VS Code extension preview. Version `0.2.0` exists on npm as the development/fallback host, but the VS Code extension is the product path.
+Current release posture: the VS Code Marketplace extension is the product path. The npm package remains a development and fallback host.
 
 Packaging foundation now available: the scanner exposes an in-memory Node API through `lib/scanner-api.mjs`. The existing scan command, local runtime, npm host, and VS Code extension preview use the same scanner/runtime core so behavior stays aligned across hosts.
 
@@ -94,10 +94,10 @@ GitHub Actions is the release control plane:
 
 - `.github/workflows/ci.yml` runs the full release gate and packages a VSIX artifact for every pushed branch, plus pull requests to `main`.
 - `.github/workflows/release.yml` runs automatically for version tags such as `v0.1.1`, with a manual existing-tag mode for repair and backfill.
-- The release workflow verifies that the tag matches `package.json`, runs the release gate, packages the VS Code extension VSIX, generates release notes from `CHANGELOG.md`, and creates the matching GitHub Release.
-- After maintainer smoke testing and Marketplace credentials are configured, public extension releases should be published to the VS Code Marketplace so users can install without manually downloading a VSIX.
+- The release workflow verifies that the tag matches both package versions, runs the release gate, packages one VSIX, publishes that artifact to the VS Code Marketplace, and attaches the exact VSIX to the matching GitHub Release.
+- Marketplace publication uses GitHub OIDC and Microsoft Entra workload identity federation. No Marketplace token or client secret is stored in GitHub.
 - A failed workflow can be rerun safely: an existing npm version is accepted only when its published `gitHead` matches the exact tagged commit. Conflicting or unverifiable versions are refused.
-- New versions must pass the full release gate before publication. An exact-commit backfill of an already-published historical version skips its old test suite and only repairs the missing GitHub Release.
+- Every release and repair run passes the current release gate before publication.
 
 This keeps GitHub, release artifacts, release notes, and the source tag tied to the same commit. Ordinary pushes never publish.
 
@@ -120,10 +120,28 @@ Commit and push the workflow files first, then configure npm Trusted Publishing
 3. Set repository to `copilot-usage-studio`.
 4. Set workflow filename to `release.yml`.
 5. Allow the `npm publish` action.
-6. Leave the environment blank unless the workflow is later changed to use a protected GitHub environment.
+6. Set the trusted-publisher environment to `marketplace`, matching the protected environment used by the release job.
 
 The workflow uses GitHub's OIDC identity, so no long-lived `NPM_TOKEN` repository secret is required. npm automatically adds provenance for a public package published from a public repository through Trusted Publishing.
 
+### One-Time VS Code Marketplace Setup
+
+1. In Microsoft Entra ID, create an app registration for Marketplace publishing. Record its application (client) ID and directory (tenant) ID. Do not create a client secret.
+2. Add a federated credential to that app registration using the GitHub Actions scenario:
+   - organization: `fortunes-guardian`
+   - repository: `copilot-usage-studio`
+   - entity type: **Environment**
+   - environment: `marketplace`
+3. In GitHub, create an environment named `marketplace`. Restrict deployment to protected version tags when practical.
+4. Add environment variables `AZURE_CLIENT_ID` and `AZURE_TENANT_ID`. These identifiers are not credentials; GitHub's short-lived OIDC assertion is the credential.
+5. After this workflow is merged to `main`, run **Marketplace Identity Check** from GitHub Actions.
+6. Copy the profile ID from the workflow summary. In the Visual Studio Marketplace publisher management page, add that identity ID as a member of publisher `fortunes-guardian` with the **Contributor** role.
+7. Rerun **Marketplace Identity Check** if publisher membership or federation changes.
+
+The release job uses `azure/login` with GitHub OIDC, then publishes with `vsce --azure-credential`. No PAT, client secret, or certificate is created. The workflow publishes the already packaged `tmp/*.vsix`, and that exact file is uploaded to the GitHub Release.
+
+References: [VS Code secure automated publishing](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#secure-automated-publishing-to-visual-studio-marketplace) and [GitHub OIDC with Azure](https://docs.github.com/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-azure).
+
 ### Publishing a Version
 
 Start from an up-to-date, clean `main` branch. Choose the semantic-version bump that matches the change:
@@ -138,20 +156,21 @@ npm version patch
 git push origin main --follow-tags
 ```
 
-`npm version patch` updates both `package.json` and `package-lock.json`, creates a version commit, and creates an annotated `vX.Y.Z` tag. Use `npm version minor` for a backward-compatible feature release or `npm version major` for a breaking release.
+`npm version patch` updates `package.json` and `package-lock.json`; the repository's `version` lifecycle hook synchronizes `vscode-extension/package.json` before npm creates the version commit and annotated `vX.Y.Z` tag. Use `npm version minor` for a backward-compatible feature release or `npm version major` for a breaking release.
 
 After the tag is pushed:
 
 1. Watch the **Release** workflow in GitHub Actions.
-2. Confirm the new version appears on npm.
-3. Confirm GitHub created a Release for the same tag.
-4. Confirm the release notes read well and include the curated highlights.
-5. Download the attached VSIX if the extension should be tested or shared.
-6. Run `npx copilot-usage-studio@X.Y.Z --version` from a clean directory as a final smoke test.
+2. Confirm the new version appears in the VS Code Marketplace.
+3. Confirm the new version appears on npm.
+4. Confirm GitHub created a Release for the same tag and attached the same-version VSIX.
+5. Confirm the release notes read well and include the curated highlights.
+6. Install or update from the Marketplace and run one final extension smoke test.
+7. Run `npx copilot-usage-studio@X.Y.Z --version` from a clean directory as a fallback-host smoke test.
 
 If CI or release validation fails, fix the issue on `main` and publish a new version. Do not move or reuse a public release tag, and do not overwrite an npm version; both are immutable release coordinates.
 
-The workflow also has a manual **Run workflow** action with a required existing tag. Use this to repair or backfill the GitHub Release for an exact tag. For the already-published first version, ensure `v0.1.0` exists on GitHub, then run the workflow once with `v0.1.0`; it will verify npm's published `gitHead`, skip the historical release gate and npm publication, and create the missing GitHub Release.
+The workflow also has a manual **Run workflow** action with a required existing tag. Use it to repair a release from that immutable tag. Duplicate npm and Marketplace publication is skipped safely, while the release gate reruns and the GitHub Release notes/artifact are repaired.
 
 ### Manual Emergency Fallback
 
@@ -286,7 +305,7 @@ npm run vscode:package
 Install it locally:
 
 ```bash
-code --install-extension tmp/copilot-usage-studio-vscode-0.2.0.vsix --force
+code --install-extension tmp/copilot-usage-studio-vscode-X.Y.Z.vsix --force
 ```
 
 The extension exposes the full app inside VS Code: Usage, Sessions, Memory, Customizations preview, Compare, Insights, and Prices. The npm/browser host remains useful for development and fallback testing, but the extension is the primary product surface.

package/docs/pricing.md

@@ -169,6 +169,8 @@ The user should be able to inspect the cost inputs directly. If a session looks
 - cached input or cache-write accounting
 - a model fallback because the raw model id was not in the known GitHub table
 
+Some VS Code logs can contain internal raw model ids that are not published as GitHub pricing rows. For example, a raw id such as `oswe-vscode-prime` stays visible in the UI and is estimated with the configured fallback pricing row. The app should not silently rename that id unless a reliable pricing alias is added.
+
 The `GitHub prices` view therefore shows every rate row the app knows about, where it came from, and whether any imported session currently uses it.
 
 The same view also shows the selected Business/Enterprise AI-credit allowance and how the current imported sessions compare with it.

package/docs/scanner-api.md

@@ -81,6 +81,18 @@ Next decomposition targets:
 - pricing/token normalization
 - SQLite/state enrichment helpers
 
+## Incremental scans
+
+The runtime passes the previous snapshot's `generatedAt` value as `incrementalSince` during a normal quick refresh. The scanner still discovers known VS Code storage entries, but it parses only debug-session `main.jsonl` files and chat snapshots modified after that cursor. The runtime merges changed sessions by stable session ID and retains unchanged sessions.
+
+This provides two explicit modes: quick/incremental for normal startup, visibility refresh, and `Refresh Data`; full for recovery/debugging through `Copilot Usage Studio: Full Rescan`.
+
+Incremental scans intentionally do not infer deletions. A full rescan rebuilds the snapshot and is the recovery path for deleted or externally rewritten sources. Memory roots remain indexed during quick scans because memory files are small and can be independently added or removed.
+
+Customization analysis has its own cache boundary. Inventory records include a SHA-256 content fingerprint. If all current fingerprints match the previous analysis, only changed session logs are checked and prior evidence is retained. Any customization content change invalidates that shortcut.
+
+The current delta cursor is timestamp-based because VS Code does not publish a stable scanner API or change journal for Agent Debug Logs. The full-rescan command exists specifically to recover from timestamp anomalies or external file restoration.
+
 ## Local Runtime Host
 
 `lib/local-runtime.mjs` is the first shared API host. It keeps the last valid `SessionData` snapshot in memory, serves it while scans run, and persists successful refreshes.

package/lib/local-runtime.mjs

@@ -62,6 +62,7 @@ export function createLocalRuntime(options = {}) {
   let activeScanController = null;
   let activeScanId = 0;
   let activeScanMode = '';
+  let lastScanMode = '';
   let scanSequence = 0;
 
   function status() {
@@ -78,6 +79,7 @@ export function createLocalRuntime(options = {}) {
       lastError,
       activeScanId,
       activeScanMode,
+      lastScanMode,
       scanProgress,
       progressHistory: progressHistory.slice(-40),
       workspaceProgress: [...workspaceProgress.values()],
@@ -107,7 +109,7 @@ export function createLocalRuntime(options = {}) {
     }
 
     const scanMode = normalizeScanMode(refreshOptions.mode ?? 'quick');
-    const effectiveScanOptions = scanOptionsForMode(scanMode, scanOptions);
+    const effectiveScanOptions = scanOptionsForMode(scanMode, scanOptions, sessionData);
     const started = Date.now();
     const scanId = ++scanSequence;
     activeScanId = scanId;
@@ -138,28 +140,28 @@ export function createLocalRuntime(options = {}) {
         }),
       )
       .then((nextSessionData) => {
+        const changedSessionCount = nextSessionData.sessions?.length ?? 0;
         const finalSessionData = sessionData
           ? scanMode === 'customizations'
             ? mergeCustomizationScan(sessionData, nextSessionData)
-            : preserveCustomizationSnapshot(sessionData, nextSessionData)
+            : scanMode === 'quick'
+              ? mergeIncrementalScan(sessionData, nextSessionData)
+              : preserveCustomizationSnapshot(sessionData, nextSessionData)
           : nextSessionData;
         writer(finalSessionData, dataFile);
         sessionData = finalSessionData;
         phase = 'ready';
         lastScanCompletedAt = new Date().toISOString();
         lastScanDurationMs = Date.now() - started;
+        lastScanMode = scanMode;
         scanProgress = rememberProgress({
           stage: 'complete',
-          message: scanMode === 'customizations'
-            ? `Customization usage check complete.`
-            : `Scan #${scanId} imported ${finalSessionData.sessions.length} sessions.`,
+          message: scanResultMessage(scanMode, changedSessionCount, finalSessionData.sessions.length),
           sessions: finalSessionData.sessions.length,
         }, scanId, reason, lastScanCompletedAt);
         emitLog(
           'log',
-          scanMode === 'customizations'
-            ? `Customization usage check #${scanId} (${reason}) completed in ${lastScanDurationMs}ms.`
-            : `Local data refresh #${scanId} (${reason}) imported ${finalSessionData.sessions.length} sessions in ${lastScanDurationMs}ms.`,
+          `${scanResultMessage(scanMode, changedSessionCount, finalSessionData.sessions.length)} (${lastScanDurationMs}ms).`,
         );
         return finalSessionData;
       })
@@ -398,12 +400,20 @@ function summarizeScanOptions(scanOptions = {}) {
   };
 }
 
+function scanResultMessage(mode, changedSessions, totalSessions) {
+  if (mode === 'customizations') return 'Customization analysis complete';
+  if (mode === 'full') return `Full rescan complete: ${totalSessions} sessions imported`;
+  return changedSessions
+    ? `${changedSessions} session${changedSessions === 1 ? '' : 's'} added or updated`
+    : 'Copilot data is up to date';
+}
+
 function normalizeScanMode(mode) {
   return ['quick', 'full', 'customizations'].includes(String(mode)) ? String(mode) : 'quick';
 }
 
-function scanOptionsForMode(mode, baseScanOptions = {}) {
-  if (mode === 'full' || mode === 'customizations') {
+function scanOptionsForMode(mode, baseScanOptions = {}, previousData = null) {
+  if (mode === 'customizations') {
     const { customizationWorkspaceFolders, ...scanOptions } = baseScanOptions;
     if (mode === 'customizations' && Array.isArray(customizationWorkspaceFolders)) {
       return {
@@ -411,11 +421,14 @@ function scanOptionsForMode(mode, baseScanOptions = {}) {
         includeCustomizations: true,
         requireWorkspaceFolders: true,
         workspaceFolders: customizationWorkspaceFolders,
+        incrementalSince: previousData?.ingestion?.customizationEvidenceAnalyzedAt ?? '',
         customizationEvidence: {
           maxSessions: 0,
           maxModelCalls: 0,
           maxElapsedMs: 0,
           maxPartChars: 250_000,
+          previousEvidence: previousData?.customizations ?? [],
+          incrementalSince: previousData?.ingestion?.customizationEvidenceAnalyzedAt ?? '',
           ...(scanOptions.customizationEvidence ?? {}),
         },
       };
@@ -434,12 +447,40 @@ function scanOptionsForMode(mode, baseScanOptions = {}) {
     };
   }
 
+  if (mode === 'full') {
+    return {
+      ...baseScanOptions,
+      includeCustomizations: false,
+      incrementalSince: '',
+    };
+  }
+
   return {
     ...baseScanOptions,
     includeCustomizations: false,
+    incrementalSince: previousData?.generatedAt ?? '',
   };
 }
 
+function mergeIncrementalScan(previousData, deltaData) {
+  const changedSessions = deltaData.sessions ?? [];
+  const changedIds = new Set(changedSessions.map((session) => session.id));
+  const sessions = [
+    ...changedSessions,
+    ...(previousData.sessions ?? []).filter((session) => !changedIds.has(session.id)),
+  ]
+    .sort((a, b) => String(b.startedAt ?? '').localeCompare(String(a.startedAt ?? '')));
+  return preserveCustomizationSnapshot(previousData, {
+    ...deltaData,
+    ingestion: {
+      ...deltaData.ingestion,
+      importedSessions: sessions.length,
+      incrementalSessionsImported: changedSessions.length,
+    },
+    sessions,
+  });
+}
+
 function mergeCustomizationScan(previousData, currentWorkspaceData) {
   const scannedWorkspaces = new Set(
     (currentWorkspaceData.ingestion?.workspaceScans ?? [])
@@ -502,6 +543,9 @@ function preserveCustomizationSnapshot(previousData, nextData) {
       customizationEvidenceScannedSessions:
         nextData.ingestion?.customizationEvidenceScannedSessions ??
         previousData.ingestion?.customizationEvidenceScannedSessions,
+      customizationEvidenceAnalyzedAt:
+        nextData.ingestion?.customizationEvidenceAnalyzedAt ||
+        previousData.ingestion?.customizationEvidenceAnalyzedAt,
       customizationEvidenceModelCalls:
         nextData.ingestion?.customizationEvidenceModelCalls ??
         previousData.ingestion?.customizationEvidenceModelCalls,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copilot-usage-studio",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Local VS Code GitHub Copilot usage, cost, and session insights.",
   "type": "module",
   "bin": {
@@ -46,13 +46,15 @@
     "schema:accept": "node scripts/audit-vscode-schema.mjs --accept",
     "vscode:typecheck": "tsc -p vscode-extension/tsconfig.json --noEmit",
     "vscode:compile": "npm run vscode:typecheck && node scripts/build-vscode-extension.mjs --extension-only",
+    "verify:versions": "node scripts/verify-release-versions.mjs",
     "vscode:build": "npm run build && npm run vscode:typecheck && node scripts/build-vscode-extension.mjs",
     "vscode:verify": "npm run vscode:build && node scripts/verify-vscode-extension.mjs",
     "vscode:vsix:dry-run": "npm run vscode:verify && cd vscode-extension && vsce ls --tree",
     "vscode:package": "npm run vscode:verify && node scripts/package-vscode-extension.mjs",
     "verify:package": "node scripts/verify-package.mjs",
     "release:notes": "node scripts/generate-release-notes.mjs",
-    "release:check": "npm run test:scripts && npm test -- --watch=false && npm run build && npm run verify:package",
+    "version": "node scripts/sync-release-version.mjs",
+    "release:check": "npm run verify:versions && npm run test:scripts && npm test -- --watch=false && npm run build && npm run verify:package",
     "prepack": "npm run build"
   },
   "exports": {

package/scripts/scan-vscode-sessions.mjs

@@ -627,6 +627,7 @@ export async function scanVsCodeSessions(options = {}) {
     includeSystemCustomizations: options.includeSystemCustomizations === true,
     customizationDiscovery: options.customizationDiscovery ?? null,
     customizationEvidence: options.customizationEvidence ?? {},
+    incrementalSince: options.incrementalSince ?? '',
   };
 
   try {
@@ -748,6 +749,9 @@ 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),
         ),

package/scripts/scanner-customization-evidence.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { basename, isAbsolute, join, resolve, sep } from 'node:path';
 
 function safeJson(text) {
@@ -144,7 +144,13 @@ function matchedChunkPreview(chunks) {
 }
 
 function hasStrongContentMatch(chunks) {
-  return chunks.length > 0;
+  const unique = [...new Set(chunks.map(normalizeMatchText).filter(Boolean))];
+  const totalCharacters = unique.reduce((sum, chunk) => sum + chunk.length, 0);
+  const totalWords = unique.reduce((sum, chunk) => sum + normalizedWordCount(chunk), 0);
+  return (
+    unique.some((chunk) => chunk.length >= 120 && normalizedWordCount(chunk) >= 16) ||
+    (unique.length >= 2 && totalCharacters >= 140 && totalWords >= 20)
+  );
 }
 
 function extractPayloadText(value, depth = 0) {
@@ -311,6 +317,30 @@ function recordCustomizationMatch(state, match) {
   state.matches = state.matches.slice(0, 60);
 }
 
+function initialMatchState(customization, fileNameCounts, previous) {
+  const matches = previous?.matches ?? [];
+  return {
+    rank: statusRank(previous?.evidenceStatus),
+    matches: [...matches],
+    chunks: customizationChunks(customization._content),
+    terms: customizationTerms(customization),
+    readTerms: readTermsForCustomization(customization, fileNameCounts),
+    readSessions: new Set(
+      matches.filter((match) => statusRank(match.status) >= 2).map((match) => match.sessionId),
+    ),
+  };
+}
+
+function sourceChangedSince(path, since) {
+  const sinceMs = Date.parse(String(since ?? ''));
+  if (!Number.isFinite(sinceMs)) return true;
+  try {
+    return statSync(path).mtimeMs > sinceMs;
+  } catch {
+    return true;
+  }
+}
+
 export function customizationEvidenceFromDebugLogs(
   debugRoot,
   customizations,
@@ -343,25 +373,32 @@ export function customizationEvidenceFromDebugLogs(
   }
 
   const fileNameCounts = basenameCounts(customizations);
+  const previousById = new Map((context.previousEvidence ?? []).map((item) => [item.id, item]));
+  const canIncrement = Boolean(context.incrementalSince) && customizations.every((customization) =>
+    previousById.get(customization.id)?.contentHash === customization.contentHash);
+
   const matchState = new Map(
     customizations.map((customization) => [
       customization.id,
-      {
-        rank: 0,
-        matches: [],
-        chunks: customizationChunks(customization._content),
-        terms: customizationTerms(customization),
-        readTerms: readTermsForCustomization(customization, fileNameCounts),
-        readSessions: new Set(),
-      },
+      initialMatchState(
+        customization,
+        fileNameCounts,
+        canIncrement ? previousById.get(customization.id) : null,
+      ),
     ]),
   );
   const chunkMatchers = buildCustomizationChunkMatchers(matchState);
 
   const allSessionDirs = listDirs(debugRoot);
-  const sessionDirs = Number.isFinite(maxSessions) ? allSessionDirs.slice(0, maxSessions) : allSessionDirs;
-  if (allSessionDirs.length > sessionDirs.length) {
-    const sessionLimitReason = `limited to ${sessionDirs.length}/${allSessionDirs.length} debug-log folders`;
+  const candidateSessionDirs = canIncrement
+    ? allSessionDirs.filter((sessionDir) =>
+      sourceChangedSince(join(sessionDir, 'main.jsonl'), context.incrementalSince))
+    : allSessionDirs;
+  const sessionDirs = Number.isFinite(maxSessions)
+    ? candidateSessionDirs.slice(0, maxSessions)
+    : candidateSessionDirs;
+  if (candidateSessionDirs.length > sessionDirs.length) {
+    const sessionLimitReason = `limited to ${sessionDirs.length}/${candidateSessionDirs.length} changed debug-log folders`;
     diagnostics.warnings?.push?.(
       `Customization evidence scan for ${workspace || workspaceDir || debugRoot} ${sessionLimitReason}.`,
     );

package/scripts/scanner-customization-inventory.mjs

@@ -343,6 +343,7 @@ function parseSimpleFrontmatter(content) {
         sourcePath: resolve(file),
         relativePath,
         createdAt: stats.birthtimeMs > 0 ? stats.birthtime.toISOString() : '',
+        contentHash: createHash('sha256').update(content).digest('hex'),
         modifiedAt: stats.mtime.toISOString(),
         sizeBytes: stats.size,
         characterCount: content.length,

package/scripts/scanner-workspace.mjs

@@ -1,5 +1,5 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
 
 export function parseWorkspace(workspaceDir, options = {}, onProgress = () => {}, dependencies = {}) {
   const {
@@ -64,15 +64,25 @@ export function parseWorkspace(workspaceDir, options = {}, onProgress = () => {}
     });
   };
   const debugRoot = join(workspaceDir, 'GitHub.copilot-chat', 'debug-logs');
-  const debugSessionDirs = listDirs(debugRoot);
-  const chatSessionFiles = listFiles(join(workspaceDir, 'chatSessions'), '.jsonl');
+  const allDebugSessionDirs = listDirs(debugRoot);
+  const allChatSessionFiles = listFiles(join(workspaceDir, 'chatSessions'), '.jsonl');
+  const incrementalSinceMs = timestampMs(options.incrementalSince);
+  const debugSessionDirs = incrementalSinceMs
+    ? allDebugSessionDirs.filter((sessionDir) =>
+      sourceChangedSince(join(sessionDir, 'main.jsonl'), incrementalSinceMs))
+    : allDebugSessionDirs;
+  const chatSessionFiles = incrementalSinceMs
+    ? allChatSessionFiles.filter((file) => sourceChangedSince(file, incrementalSinceMs))
+    : allChatSessionFiles;
   const memoryRoot = join(workspaceDir, 'GitHub.copilot-chat', 'memory-tool', 'memories');
   const hasMemoryRoot = existsSync(memoryRoot);
-  workspaceScan.debugLogFolders = debugSessionDirs.length;
-  workspaceScan.chatSnapshots = chatSessionFiles.length;
+  workspaceScan.debugLogFolders = allDebugSessionDirs.length;
+  workspaceScan.chatSnapshots = allChatSessionFiles.length;
+  workspaceScan.changedDebugLogFolders = debugSessionDirs.length;
+  workspaceScan.changedChatSnapshots = chatSessionFiles.length;
   workspaceScan.hasMemoryRoot = hasMemoryRoot;
 
-  if (!debugSessionDirs.length && !chatSessionFiles.length && !hasMemoryRoot) {
+  if (!allDebugSessionDirs.length && !allChatSessionFiles.length && !hasMemoryRoot) {
     workspaceScan.completedAt = new Date().toISOString();
     workspaceScan.durationMs = Date.now() - workspaceStartedAt;
     workspaceScan.lastStage = 'empty';
@@ -84,8 +94,10 @@ export function parseWorkspace(workspaceDir, options = {}, onProgress = () => {}
   }
 
   progress('workspace', `Checking VS Code storage entry for ${workspace}.`, {
-    debugLogFolders: debugSessionDirs.length,
-    chatSnapshots: chatSessionFiles.length,
+    debugLogFolders: allDebugSessionDirs.length,
+    chatSnapshots: allChatSessionFiles.length,
+    changedDebugLogFolders: debugSessionDirs.length,
+    changedChatSnapshots: chatSessionFiles.length,
     hasMemoryRoot,
   });
   progress('workspace-state', `Reading workspace metadata for ${workspace}.`);
@@ -146,7 +158,7 @@ export function parseWorkspace(workspaceDir, options = {}, onProgress = () => {}
       debugSessions.push(enrichSessionFromWorkspaceState(session, stateBySessionId));
     }
   }
-  const debugIds = new Set(debugSessions.map((session) => session.id));
+  const debugIds = new Set(allDebugSessionDirs.map((sessionDir) => basename(sessionDir)));
   diagnostics.importedDebugLogSessions += debugSessions.length;
 
   if (chatSessionFiles.length) {
@@ -186,6 +198,22 @@ export function parseWorkspace(workspaceDir, options = {}, onProgress = () => {}
   };
 }
 
+
+function timestampMs(value) {
+  if (!value) {
+    return 0;
+  }
+  const parsed = Date.parse(String(value));
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function sourceChangedSince(path, sinceMs) {
+  try {
+    return statSync(path).mtimeMs > sinceMs;
+  } catch {
+    return true;
+  }
+}
 function assertWorkspaceDependencies(dependencies) {
   for (const name of [
     'customizationsFromDebugReferences',