Add async diagnostics batching for summaries.

Queue git, health, and dependency diagnostics in a background worker with cache TTL and concurrency controls so full summaries return quickly while diagnostics warm asynchronously, and invalidate summary cache after worker refreshes.

Made-with: Cursor

Author: RichardGeorgeDavis

docs/CHANGELOG.md

@@ -19,6 +19,9 @@
 - Added incremental discovery invalidation in `repos/workspace-hub/server/workspace.ts` by tracking a lightweight repo-tree signature so cached discovery can be reused when unchanged and refreshed automatically when repo folders change.
 - Updated workspace cache tests in `repos/workspace-hub/test/workspace-cache-search.test.ts` to verify both repo-tree-driven refresh and explicit cache invalidation behavior.
 - Confirmed updated local test-suite pass outside sandbox with `pnpm --dir "repos/workspace-hub" test` (`13 passed, 0 failed`).
+- Added async diagnostics batching in `repos/workspace-hub/server/workspace.ts` with a background queue, diagnostics cache TTL, and configurable worker concurrency for full-summary diagnostics refresh.
+- Added worker cache-coherency invalidation so refreshed diagnostics propagate to subsequent summary reads.
+- Extended `repos/workspace-hub/test/workspace-cache-search.test.ts` with diagnostics warming coverage and confirmed updated local test-suite pass outside sandbox (`14 passed, 0 failed`).
 
 ## 2026-04-05
 

docs/HANDOVER.md

@@ -334,3 +334,31 @@ Verification after incremental invalidation slice:
 - `pnpm --dir "repos/workspace-hub" lint`: passed
 - `pnpm --dir "repos/workspace-hub" typecheck`: passed
 - `pnpm --dir "repos/workspace-hub" test`: passed outside sandbox in local terminal (`13 passed, 0 failed`, duration ~`2518ms`)
+
+### Implementation update (2026-04-07, diagnostics batching worker slice)
+
+Completed in `repos/workspace-hub`:
+
+1. Added background diagnostics batching.
+   - `server/workspace.ts` now queues and processes diagnostics refresh work asynchronously with configurable concurrency.
+   - New env controls:
+     - `WORKSPACE_HUB_DIAGNOSTICS_WORKER_CONCURRENCY` (default `4`)
+     - `WORKSPACE_HUB_DIAGNOSTICS_CACHE_TTL_MS` (default `10000`)
+
+2. Added diagnostics cache semantics for full summary mode.
+   - Full summary reads now return quickly with:
+     - warm cached diagnostics when fresh
+     - stale diagnostics while a background refresh is queued
+     - conservative placeholders on first hit while diagnostics warm asynchronously
+
+3. Added cache-coherency fix after worker refresh.
+   - When worker refresh completes, it now invalidates workspace summary cache so the next summary read can surface updated diagnostics.
+
+4. Added and validated worker-focused test coverage.
+   - Extended `repos/workspace-hub/test/workspace-cache-search.test.ts` with async diagnostics warming coverage.
+
+Verification after diagnostics worker slice:
+
+- `pnpm --dir "repos/workspace-hub" lint`: passed
+- `pnpm --dir "repos/workspace-hub" typecheck`: passed
+- `pnpm --dir "repos/workspace-hub" test`: passed outside sandbox in local terminal (`14 passed, 0 failed`, duration ~`2864ms`)

repos/workspace-hub/server/workspace.ts

@@ -148,6 +148,14 @@ const workspaceDiscoveryCacheTtlMs = Number.parseInt(
   process.env.WORKSPACE_HUB_DISCOVERY_CACHE_TTL_MS ?? '1500',
   10,
 )
+const diagnosticsCacheTtlMs = Number.parseInt(
+  process.env.WORKSPACE_HUB_DIAGNOSTICS_CACHE_TTL_MS ?? '10000',
+  10,
+)
+const diagnosticsWorkerConcurrency = Number.parseInt(
+  process.env.WORKSPACE_HUB_DIAGNOSTICS_WORKER_CONCURRENCY ?? '4',
+  10,
+)
 const gitVisibilityCache = new Map<
   string,
   {
@@ -166,6 +174,12 @@ type WorkspaceSummaryBuildOptions = {
   includeDiagnostics?: boolean
 }
 
+type RepoDiagnostics = {
+  dependencies: RepoDependencyState
+  git: RepoGitState
+  health: RepoHealth
+}
+
 type WorkspaceDiscoveryResult = {
   archives: WorkspaceArchive[]
   repos: WorkspaceRepo[]
@@ -180,6 +194,15 @@ let cachedWorkspaceDiscovery:
       value: WorkspaceDiscoveryResult
     }
   | null = null
+const repoDiagnosticsCache = new Map<
+  string,
+  {
+    expiresAt: number
+    value: RepoDiagnostics
+  }
+>()
+const repoDiagnosticsQueue = new Map<string, () => Promise<RepoDiagnostics>>()
+const activeDiagnosticsJobs = new Set<string>()
 
 function buildSnapshotCacheKey(
   installSnapshots: Map<string, RepoInstall>,
@@ -207,6 +230,49 @@ export function invalidateWorkspaceSummaryCache() {
   cachedWorkspaceDiscovery = null
 }
 
+function processRepoDiagnosticsQueue() {
+  while (
+    activeDiagnosticsJobs.size < Math.max(1, diagnosticsWorkerConcurrency) &&
+    repoDiagnosticsQueue.size > 0
+  ) {
+    const nextEntry = repoDiagnosticsQueue.entries().next()
+    if (nextEntry.done) {
+      break
+    }
+
+    const [key, factory] = nextEntry.value
+    repoDiagnosticsQueue.delete(key)
+    activeDiagnosticsJobs.add(key)
+
+    void factory()
+      .then((value) => {
+        repoDiagnosticsCache.set(key, {
+          expiresAt: Date.now() + Math.max(0, diagnosticsCacheTtlMs),
+          value,
+        })
+        // Diagnostics were refreshed asynchronously, so invalidate the derived
+        // summary cache and allow subsequent reads to pick up warm diagnostics.
+        invalidateWorkspaceSummaryCache()
+      })
+      .catch(() => {
+        // Keep stale diagnostics when background refresh fails.
+      })
+      .finally(() => {
+        activeDiagnosticsJobs.delete(key)
+        processRepoDiagnosticsQueue()
+      })
+  }
+}
+
+function enqueueRepoDiagnostics(key: string, factory: () => Promise<RepoDiagnostics>) {
+  if (activeDiagnosticsJobs.has(key) || repoDiagnosticsQueue.has(key)) {
+    return
+  }
+
+  repoDiagnosticsQueue.set(key, factory)
+  processRepoDiagnosticsQueue()
+}
+
 async function buildReposTreeSignature() {
   try {
     const rootStat = await stat(reposRoot)
@@ -1445,35 +1511,61 @@ async function buildRepoRecord(
     type,
   })
   const agentTooling = await readAgentTooling(fullPath)
-  const [health, git, dependencies] = includeDiagnostics
-    ? await Promise.all([
-        probeHealth(healthcheckUrl ?? resolvedPreview.previewUrl),
-        readGitState(fullPath),
-        readDependencyState({
-          buildCommand: effectiveBuildCommand,
-          devCommand: effectiveDevCommand,
-          fullPath,
-          installCommand,
-          names,
-          packageManager,
-          previewCommand,
-        }),
-      ])
-    : [buildUnknownHealth(healthcheckUrl ?? resolvedPreview.previewUrl), buildUnavailableGitState(), buildUnknownDependencyState()]
+  const diagnosticsKey = fullPath
+  const diagnosticsFactory = async (): Promise<RepoDiagnostics> => {
+    const [health, git, dependencies] = await Promise.all([
+      probeHealth(healthcheckUrl ?? resolvedPreview.previewUrl),
+      readGitState(fullPath),
+      readDependencyState({
+        buildCommand: effectiveBuildCommand,
+        devCommand: effectiveDevCommand,
+        fullPath,
+        installCommand,
+        names,
+        packageManager,
+        previewCommand,
+      }),
+    ])
+
+    return { dependencies, git, health }
+  }
+  let diagnostics: RepoDiagnostics
+  if (!includeDiagnostics) {
+    diagnostics = {
+      dependencies: buildUnknownDependencyState(),
+      git: buildUnavailableGitState(),
+      health: buildUnknownHealth(healthcheckUrl ?? resolvedPreview.previewUrl),
+    }
+  } else {
+    const cachedDiagnostics = repoDiagnosticsCache.get(diagnosticsKey)
+    if (cachedDiagnostics && cachedDiagnostics.expiresAt > Date.now()) {
+      diagnostics = cachedDiagnostics.value
+    } else if (cachedDiagnostics) {
+      diagnostics = cachedDiagnostics.value
+      enqueueRepoDiagnostics(diagnosticsKey, diagnosticsFactory)
+    } else {
+      diagnostics = {
+        dependencies: buildUnknownDependencyState(),
+        git: buildUnavailableGitState(),
+        health: buildUnknownHealth(healthcheckUrl ?? resolvedPreview.previewUrl),
+      }
+      enqueueRepoDiagnostics(diagnosticsKey, diagnosticsFactory)
+    }
+  }
 
   return {
     agentTooling,
     buildCommand: effectiveBuildCommand,
     collection: collection ?? 'direct',
     detectedBy: hasManifest ? 'manifest' : 'files',
-    dependencies,
+    dependencies: diagnostics.dependencies,
     devCommand: effectiveDevCommand,
     externalUrl,
     failureReport,
-    git,
+    git: diagnostics.git,
     hasManifest,
     hasSavedMetadata: Boolean(savedOverrides),
-    health,
+    health: diagnostics.health,
     healthcheckUrl,
     isPinned: savedOverrides?.pinned ?? false,
     install,

repos/workspace-hub/test/workspace-cache-search.test.ts

@@ -1,13 +1,16 @@
 import assert from 'node:assert/strict'
+import { execFile } from 'node:child_process'
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
 import { after, before, test } from 'node:test'
+import { promisify } from 'node:util'
 
 type WorkspaceModule = typeof import('../server/workspace.ts')
 type WorkspaceSearchModule = typeof import('../server/workspace-search.ts')
 
 let tempWorkspaceRoot = ''
+const execFileAsync = promisify(execFile)
 
 async function writeTextFile(targetPath: string, content: string) {
   await mkdir(path.dirname(targetPath), { recursive: true })
@@ -27,6 +30,11 @@ async function createNodeRepo(root: string, relativePath: string) {
   )
 }
 
+async function initGitRepo(root: string, relativePath: string) {
+  const repoPath = path.join(root, 'repos', relativePath)
+  await execFileAsync('git', ['init'], { cwd: repoPath })
+}
+
 async function importWorkspaceModule(root: string, cacheTtlMs: string) {
   process.env.WORKSPACE_HUB_WORKSPACE_ROOT = root
   process.env.WORKSPACE_HUB_DISCOVERY_CACHE_TTL_MS = cacheTtlMs
@@ -140,3 +148,45 @@ test('base summary mode skips heavy diagnostics while preserving repo discovery'
   assert.match(repo.git.summary, /skipped for base summary/i)
   assert.match(repo.dependencies.reason, /skipped for base summary/i)
 })
+
+test('diagnostics mode warms git diagnostics asynchronously via worker', async () => {
+  await createNodeRepo(tempWorkspaceRoot, 'repo-git-worker')
+  await initGitRepo(tempWorkspaceRoot, 'repo-git-worker')
+  const workspaceModule = await importWorkspaceModule(tempWorkspaceRoot, '60000')
+  workspaceModule.invalidateWorkspaceSummaryCache()
+
+  const firstSummary = await workspaceModule.buildWorkspaceSummary(
+    4101,
+    new Map(),
+    new Map(),
+    { includeDiagnostics: true },
+  )
+  const firstRepo = firstSummary.repos.find((entry) => entry.relativePath.endsWith('repo-git-worker'))
+  assert.ok(firstRepo)
+  assert.equal(firstRepo.git.hasGit, false)
+
+  const maxAttempts = 20
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    await new Promise((resolve) => {
+      setTimeout(resolve, 50)
+    })
+
+    const refreshedSummary = await workspaceModule.buildWorkspaceSummary(
+      4101,
+      new Map(),
+      new Map(),
+      { includeDiagnostics: true },
+    )
+    const refreshedRepo = refreshedSummary.repos.find((entry) =>
+      entry.relativePath.endsWith('repo-git-worker'),
+    )
+    assert.ok(refreshedRepo)
+
+    if (refreshedRepo.git.hasGit) {
+      assert.match(refreshedRepo.git.summary, /Git status available|No commits yet on/i)
+      return
+    }
+  }
+
+  assert.fail('Expected background diagnostics worker to warm git diagnostics.')
+})