Add incremental discovery invalidation.

Track a lightweight repos tree signature in workspace discovery caching so unchanged trees can reuse cached results while repo folder changes trigger automatic refresh, with updated tests and handover documentation.

Made-with: Cursor

Author: RichardGeorgeDavis

docs/CHANGELOG.md

@@ -16,6 +16,9 @@
 - Confirmed updated local test-suite pass outside sandbox with `pnpm --dir "repos/workspace-hub" test` (`11 passed, 0 failed`).
 - Added a split summary path with lightweight diagnostics mode: new `GET /api/workspace/summary/base` route and optional `includeDiagnostics` toggle in workspace summary building.
 - Added base-summary test coverage in `repos/workspace-hub/test/workspace-cache-search.test.ts` and confirmed local test-suite pass outside sandbox (`12 passed, 0 failed`).
+- 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`).
 
 ## 2026-04-05
 

docs/HANDOVER.md

@@ -309,3 +309,28 @@ Verification after base-summary 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 (`12 passed, 0 failed`, duration ~`3114ms`)
+
+### Implementation update (2026-04-07, incremental discovery invalidation slice)
+
+Completed in `repos/workspace-hub`:
+
+1. Added repo-tree signature based cache reuse.
+   - Workspace discovery cache now tracks a lightweight `repos/` tree signature (root + immediate child directory stats).
+   - Cached discovery can be reused past TTL when snapshot state and repo-tree signature are unchanged.
+
+2. Added automatic refresh trigger on repo-tree changes.
+   - Discovery now re-runs when repo tree signature changes (for example, new repo folder appears), even without explicit cache invalidation.
+
+3. Preserved explicit invalidation behavior.
+   - `invalidateWorkspaceSummaryCache()` remains supported for guaranteed refresh in action flows.
+
+4. Updated cache behavior tests.
+   - `repos/workspace-hub/test/workspace-cache-search.test.ts` now verifies:
+     - summary refresh when repo tree changes
+     - explicit invalidation still forces refresh
+
+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`)

repos/workspace-hub/server/workspace.ts

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process'
 import { type Dirent } from 'node:fs'
-import { access, readFile, readdir } from 'node:fs/promises'
+import { access, readFile, readdir, stat } from 'node:fs/promises'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { promisify } from 'node:util'
@@ -176,6 +176,7 @@ let cachedWorkspaceDiscovery:
   | {
       expiresAt: number
       key: string
+      repoTreeSignature: string
       value: WorkspaceDiscoveryResult
     }
   | null = null
@@ -206,6 +207,33 @@ export function invalidateWorkspaceSummaryCache() {
   cachedWorkspaceDiscovery = null
 }
 
+async function buildReposTreeSignature() {
+  try {
+    const rootStat = await stat(reposRoot)
+    const rootEntries = await readVisibleEntries(reposRoot)
+    const directoryEntries = rootEntries.filter((entry) => entry.isDirectory())
+    const directorySignatures = await Promise.all(
+      directoryEntries.map(async (entry) => {
+        const fullPath = path.join(reposRoot, entry.name)
+        try {
+          const entryStat = await stat(fullPath)
+          return `${entry.name}:${entryStat.mtimeMs}:${entryStat.size}`
+        } catch {
+          return `${entry.name}:missing`
+        }
+      }),
+    )
+
+    directorySignatures.sort((left, right) => left.localeCompare(right))
+    return [
+      `root:${rootStat.mtimeMs}:${rootStat.size}`,
+      `dirs:${directorySignatures.join('|')}`,
+    ].join('::')
+  } catch {
+    return 'repos-root-unavailable'
+  }
+}
+
 function isVisible(name: string) {
   return !name.startsWith('.')
 }
@@ -1483,11 +1511,16 @@ async function discoverWorkspace(
 ) {
   const includeDiagnostics = options.includeDiagnostics ?? true
   const cacheKey = `${buildSnapshotCacheKey(installSnapshots, runtimeSnapshots)}::diagnostics=${includeDiagnostics ? 'full' : 'base'}`
+  const repoTreeSignature = await buildReposTreeSignature()
   if (
     cachedWorkspaceDiscovery &&
     cachedWorkspaceDiscovery.key === cacheKey &&
-    cachedWorkspaceDiscovery.expiresAt > Date.now()
+    cachedWorkspaceDiscovery.repoTreeSignature === repoTreeSignature
   ) {
+    if (cachedWorkspaceDiscovery.expiresAt <= Date.now()) {
+      cachedWorkspaceDiscovery.expiresAt =
+        Date.now() + Math.max(0, workspaceDiscoveryCacheTtlMs)
+    }
     return cachedWorkspaceDiscovery.value
   }
 
@@ -1591,6 +1624,7 @@ async function discoverWorkspace(
   cachedWorkspaceDiscovery = {
     expiresAt: Date.now() + Math.max(0, workspaceDiscoveryCacheTtlMs),
     key: cacheKey,
+    repoTreeSignature,
     value: nextValue,
   }
 

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

@@ -65,7 +65,7 @@ after(async () => {
   }
 })
 
-test('workspace summary cache invalidation refreshes discovered repo set', async () => {
+test('workspace summary refreshes discovered repo set when repo tree changes', async () => {
   await createNodeRepo(tempWorkspaceRoot, 'repo-a')
   const workspaceModule = await importWorkspaceModule(tempWorkspaceRoot, '60000')
 
@@ -74,16 +74,28 @@ test('workspace summary cache invalidation refreshes discovered repo set', async
 
   await createNodeRepo(tempWorkspaceRoot, 'repo-b')
 
-  const cachedSummary = await workspaceModule.buildWorkspaceSummary(4101, new Map(), new Map())
+  const cachedSummary = await workspaceModule.buildWorkspaceSummary(
+    4101,
+    new Map(),
+    new Map(),
+  )
   assert.equal(
     cachedSummary.repos.length,
-    1,
-    'Expected cached summary to remain stable before explicit invalidation.',
+    2,
+    'Expected summary to refresh when repo tree signature changes.',
   )
+})
 
+test('workspace summary cache invalidation can force a refresh', async () => {
+  const workspaceModule = await importWorkspaceModule(tempWorkspaceRoot, '60000')
   workspaceModule.invalidateWorkspaceSummaryCache()
-  const refreshedSummary = await workspaceModule.buildWorkspaceSummary(4101, new Map(), new Map())
-  assert.equal(refreshedSummary.repos.length, 2)
+
+  const refreshedSummary = await workspaceModule.buildWorkspaceSummary(
+    4101,
+    new Map(),
+    new Map(),
+  )
+  assert.ok(refreshedSummary.repos.length >= 2)
 })
 
 test('artifact search indexing is opt-in via env gate', async () => {