Add diagnostics freshness indicators.

Expose diagnostics freshness state on repo summaries and surface it in the list and details UI so operators can distinguish warm diagnostics from placeholder or stale values, with updated worker transition tests and handover notes.

Made-with: Cursor

Author: RichardGeorgeDavis

docs/CHANGELOG.md

@@ -22,6 +22,8 @@
 - 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`).
+- Added diagnostics freshness state (`fresh`, `warming`, `stale`) to workspace repo summaries and surfaced it in repo list and details UI.
+- Updated diagnostics worker coverage to assert `warming -> fresh` transition and reconfirmed local test-suite pass (`14 passed, 0 failed`).
 
 ## 2026-04-05
 

docs/HANDOVER.md

@@ -362,3 +362,28 @@ 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`)
+
+### Implementation update (2026-04-07, diagnostics freshness indicator slice)
+
+Completed in `repos/workspace-hub`:
+
+1. Added diagnostics freshness state on repo records.
+   - `WorkspaceRepo` now includes `diagnosticsFreshness` with values: `fresh`, `warming`, `stale`.
+
+2. Surfaced freshness in UI.
+   - Added freshness status pills to repo cards in `RepoSnapshot`.
+   - Added a diagnostics freshness row in `RepoDetails` overview.
+
+3. Defined freshness transitions in summary generation.
+   - `warming`: first full-summary read before diagnostics cache is warm
+   - `stale`: expired diagnostics returned while background refresh is queued
+   - `fresh`: warm diagnostics cache or intentionally skipped diagnostics mode
+
+4. Extended worker test assertions.
+   - `workspace-cache-search` test now validates `warming -> fresh` transition during async diagnostics warmup.
+
+Verification after diagnostics freshness slice:
+
+- `pnpm --dir "repos/workspace-hub" lint`: passed
+- `pnpm --dir "repos/workspace-hub" typecheck`: passed
+- `pnpm --dir "repos/workspace-hub" test`: passed (`14 passed, 0 failed`, duration ~`2337ms`)

repos/workspace-hub/server/workspace.ts

@@ -176,6 +176,7 @@ type WorkspaceSummaryBuildOptions = {
 
 type RepoDiagnostics = {
   dependencies: RepoDependencyState
+  freshness: 'fresh' | 'stale' | 'warming'
   git: RepoGitState
   health: RepoHealth
 }
@@ -1527,12 +1528,13 @@ async function buildRepoRecord(
       }),
     ])
 
-    return { dependencies, git, health }
+    return { dependencies, freshness: 'fresh', git, health }
   }
   let diagnostics: RepoDiagnostics
   if (!includeDiagnostics) {
     diagnostics = {
       dependencies: buildUnknownDependencyState(),
+      freshness: 'fresh',
       git: buildUnavailableGitState(),
       health: buildUnknownHealth(healthcheckUrl ?? resolvedPreview.previewUrl),
     }
@@ -1541,11 +1543,15 @@ async function buildRepoRecord(
     if (cachedDiagnostics && cachedDiagnostics.expiresAt > Date.now()) {
       diagnostics = cachedDiagnostics.value
     } else if (cachedDiagnostics) {
-      diagnostics = cachedDiagnostics.value
+      diagnostics = {
+        ...cachedDiagnostics.value,
+        freshness: 'stale',
+      }
       enqueueRepoDiagnostics(diagnosticsKey, diagnosticsFactory)
     } else {
       diagnostics = {
         dependencies: buildUnknownDependencyState(),
+        freshness: 'warming',
         git: buildUnavailableGitState(),
         health: buildUnknownHealth(healthcheckUrl ?? resolvedPreview.previewUrl),
       }
@@ -1558,6 +1564,7 @@ async function buildRepoRecord(
     buildCommand: effectiveBuildCommand,
     collection: collection ?? 'direct',
     detectedBy: hasManifest ? 'manifest' : 'files',
+    diagnosticsFreshness: diagnostics.freshness,
     dependencies: diagnostics.dependencies,
     devCommand: effectiveDevCommand,
     externalUrl,

repos/workspace-hub/src/features/repos/RepoDetails.tsx

@@ -669,6 +669,14 @@ function RepoDetailsContent({
               {` ${repo.dependencies.reason}`}
             </dd>
           </div>
+          <div className="details-row">
+            <dt>Diagnostics freshness</dt>
+            <dd>
+              <span className={`status-pill ${repo.diagnosticsFreshness}`}>
+                {repo.diagnosticsFreshness}
+              </span>
+            </dd>
+          </div>
           <div className="details-row">
             <dt>Dev command</dt>
             <dd>{repo.devCommand ?? 'Not inferred yet'}</dd>

repos/workspace-hub/src/features/repos/RepoSnapshot.tsx

@@ -134,6 +134,9 @@ function RepoSnapshotCard({ repo, selected }: RepoSnapshotCardProps) {
       </span>
       <span className="repo-card-diagnostics">
         <span className="repo-card-branch">git {formatBranchLabel(repo)}</span>
+        <span className={`status-pill ${repo.diagnosticsFreshness}`}>
+          {repo.diagnosticsFreshness}
+        </span>
         <span className={`status-pill ${repo.git.visibility}`}>
           {formatGitVisibilityLabel(repo)}
         </span>

repos/workspace-hub/src/types/workspace.ts

@@ -229,6 +229,7 @@ export type WorkspaceRepo = {
   buildCommand: string | null
   collection: string
   detectedBy: 'files' | 'manifest'
+  diagnosticsFreshness: 'fresh' | 'stale' | 'warming'
   dependencies: RepoDependencyState
   devCommand: string | null
   externalUrl: string | null

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

@@ -164,6 +164,7 @@ test('diagnostics mode warms git diagnostics asynchronously via worker', async (
   const firstRepo = firstSummary.repos.find((entry) => entry.relativePath.endsWith('repo-git-worker'))
   assert.ok(firstRepo)
   assert.equal(firstRepo.git.hasGit, false)
+  assert.equal(firstRepo.diagnosticsFreshness, 'warming')
 
   const maxAttempts = 20
   for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
@@ -183,6 +184,7 @@ test('diagnostics mode warms git diagnostics asynchronously via worker', async (
     assert.ok(refreshedRepo)
 
     if (refreshedRepo.git.hasGit) {
+      assert.equal(refreshedRepo.diagnosticsFreshness, 'fresh')
       assert.match(refreshedRepo.git.summary, /Git status available|No commits yet on/i)
       return
     }