@cat-factory/app 0.116.6 → 0.116.8

package/app/components/auth/AuthGate.vue

@@ -14,7 +14,9 @@ const { t } = useI18n()
 // out, so it must render even when auth is required and there's no user.
 const isPublicRoute = computed(() => route.path === '/reset-password')
 
-onMounted(() => auth.bootstrap())
+// Stamp the first cold-open milestone once the auth handshake settles (app-startup initiative,
+// item 1) — bootstrap resolves even on failure (it catches internally), so `finally` always fires.
+onMounted(() => void auth.bootstrap().finally(() => markBoot('auth-ready')))
 </script>
 
 <template>

package/app/components/github/AddServiceFromRepoModal.vue

@@ -8,8 +8,9 @@
 //
 // MONOREPO support: a repo flagged a monorepo can back SEVERAL services, each
 // pinned to a subdirectory. When the selected repo is a monorepo, the user
-// browses its tree and picks the service's directory before adding (and may add
-// more than one, a subset of the repo's services).
+// browses its tree and multi-selects the service directories to add — from ANY
+// parent folder, in one pass — then adds them all at once. Directories that
+// already back a service on this board are shown but not selectable.
 import type { FrameRepoType, GitHubAvailableRepo } from '~/types/domain'
 import GitHubConnect from '~/components/github/GitHubConnect.vue'
 import RepoSearchEmpty from '~/components/github/RepoSearchEmpty.vue'
@@ -136,11 +137,39 @@ const repoMenuItems = computed(() => {
 // repo + requires a directory when it creates the service). A repo already flagged a
 // monorepo (it backs other services) seeds the toggle on when selected.
 const isMonorepo = ref(false)
-const selectedDirectory = ref<string | undefined>(undefined)
+// The cart of monorepo service directories the user has picked (repo-root-relative),
+// accumulated across the whole browse session so picks from different parent folders
+// coexist. Added all at once (see `addServices`), unlike the one-at-a-time whole-repo add.
+const selectedDirectories = ref<string[]>([])
+
+// Directories in the selected repo that ALREADY back a service on this board — surfaced
+// so the tree browser can disable them (adding one again would be a no-op). Derived from
+// the org catalog filtered to this repo; a whole-repo service (null directory) is ignored.
+const addedDirectories = computed<string[]>(() => {
+  if (selectedRepoId.value === undefined) return []
+  return services.catalog
+    .filter((s) => s.repoGithubId === selectedRepoId.value && s.directory)
+    .map((s) => normalizeRepoPath(s.directory as string))
+})
+const addedDirSet = computed(() => new Set(addedDirectories.value))
 
 function toggleMonorepo(value: boolean) {
   isMonorepo.value = value
-  selectedDirectory.value = undefined
+  selectedDirectories.value = []
+}
+
+// Add/remove a directory from the cart. Guards against an already-added directory (the
+// browser disables it, but keep the model authoritative).
+function toggleDirectory(path: string) {
+  if (addedDirSet.value.has(normalizeRepoPath(path))) return
+  const i = selectedDirectories.value.indexOf(path)
+  if (i >= 0) selectedDirectories.value.splice(i, 1)
+  else selectedDirectories.value.push(path)
+}
+
+function removeSelected(path: string) {
+  const i = selectedDirectories.value.indexOf(path)
+  if (i >= 0) selectedDirectories.value.splice(i, 1)
 }
 
 // On repo change, capture the picked repo (from the volatile loaded list, before a later
@@ -152,13 +181,13 @@ watch(selectedRepoId, (id) => {
     if (found) selectedRepo.value = found
   }
   isMonorepo.value = selectedRepo.value?.isMonorepo === true
-  selectedDirectory.value = undefined
+  selectedDirectories.value = []
   configuredBlockId.value = undefined
 })
 
 function resetSelection() {
   selectedRepoId.value = undefined
-  selectedDirectory.value = undefined
+  selectedDirectories.value = []
   isMonorepo.value = false
   configuredBlockId.value = undefined
   resetRepoSearch()
@@ -186,12 +215,11 @@ function openManageInstall() {
   if (manageInstallUrl.value) window.open(manageInstallUrl.value, '_blank', 'noopener')
 }
 
-// The just-added service, kept on the board store so the user can configure it (test
-// infra + fragments) right here — the same controls as the inspector. A monorepo can
-// host several services, so adding another keeps the modal open; a whole-repo service
-// can only be added once (its repo is then on the board).
+// The just-added whole-repo service, kept on the board store so the user can configure it
+// (test infra + fragments) right here — the same controls as the inspector. Only the
+// whole-repo flow surfaces this inline configure step; a monorepo adds several services at
+// once and they're configured later in the inspector.
 const configuredBlockId = ref<string | undefined>(undefined)
-const configuredDirectory = ref<string | undefined>(undefined)
 const configuredBlock = computed(() =>
   configuredBlockId.value ? board.getBlock(configuredBlockId.value) : undefined,
 )
@@ -210,12 +238,21 @@ watch(
   { immediate: true },
 )
 
-// A monorepo service needs a chosen directory; a whole-repo service can be added once.
+// A whole-repo service is added once (then configured inline). A monorepo instead
+// multi-selects directories and adds them together via `addServices`.
 const canAdd = computed(
   () =>
     !needsGitHub.value &&
     selectedRepoId.value !== undefined &&
-    (isMonorepo.value ? !!selectedDirectory.value : !configuredBlockId.value),
+    !isMonorepo.value &&
+    !configuredBlockId.value,
+)
+const canAddServices = computed(
+  () =>
+    !needsGitHub.value &&
+    selectedRepoId.value !== undefined &&
+    isMonorepo.value &&
+    selectedDirectories.value.length > 0,
 )
 
 async function add() {
@@ -223,8 +260,10 @@ async function add() {
   adding.value = true
   try {
     const block = await board.addServiceFromRepo(selectedRepoId.value, {
-      directory: isMonorepo.value ? selectedDirectory.value : undefined,
-      isMonorepo: isMonorepo.value,
+      // The switch is off, so import the whole repo as ONE service. Send the flag
+      // explicitly: a repo already flagged a monorepo (the toggle seeds on) must be
+      // un-flagged here, or the backend still requires a service subdirectory and rejects.
+      isMonorepo: false,
       type: selectedType.value,
       // Place the imported frame in free space (centred in view) instead of the
       // backend's default stagger, so it never overlaps an existing service.
@@ -235,15 +274,57 @@ async function add() {
     // Centre the camera on the newly imported service.
     await focusFrame(block.id)
     configuredBlockId.value = block.id
-    configuredDirectory.value = isMonorepo.value ? selectedDirectory.value : undefined
     toast.add({
       title: t('github.addService.toast.addedTitle'),
       description: t('github.addService.toast.addedDescription', { title: block.title }),
       icon: 'i-lucide-check',
       color: 'success',
     })
-    // Ready to pick another monorepo service (the just-added directory is taken).
-    selectedDirectory.value = undefined
+  } catch (e) {
+    toast.add({
+      title: t('github.addService.toast.addFailedTitle'),
+      description: e instanceof Error ? e.message : String(e),
+      icon: 'i-lucide-triangle-alert',
+      color: 'error',
+    })
+  } finally {
+    adding.value = false
+  }
+}
+
+// Add every directory in the cart as its own service, in one action. Each add lays the
+// frame out in free space (seeing the ones added earlier in the loop, so they don't
+// overlap); the projection is refreshed and the camera centres on the last one. The
+// just-added directories then move to `addedDirectories`, so the cart is cleared and the
+// tree marks them "added" — ready to pick more (from any folder) or close.
+async function addServices() {
+  if (!canAddServices.value || selectedRepoId.value === undefined) return
+  const dirs = selectedDirectories.value.filter((d) => !addedDirSet.value.has(normalizeRepoPath(d)))
+  if (dirs.length === 0) return
+  adding.value = true
+  try {
+    let lastBlock: Awaited<ReturnType<typeof board.addServiceFromRepo>> | undefined
+    for (const directory of dirs) {
+      lastBlock = await board.addServiceFromRepo(selectedRepoId.value, {
+        directory,
+        isMonorepo: true,
+        type: selectedType.value,
+        position: freeFramePosition(),
+      })
+    }
+    await github.load()
+    if (lastBlock) await focusFrame(lastBlock.id)
+    selectedDirectories.value = []
+    toast.add({
+      title: t('github.addService.toast.servicesAddedTitle'),
+      description: t(
+        'github.addService.toast.servicesAddedDescription',
+        { count: dirs.length },
+        dirs.length,
+      ),
+      icon: 'i-lucide-check',
+      color: 'success',
+    })
   } catch (e) {
     toast.add({
       title: t('github.addService.toast.addFailedTitle'),
@@ -329,8 +410,9 @@ function done() {
             <USelect v-model="selectedType" :items="typeItems" value-key="value" class="w-full" />
           </UFormField>
 
-          <!-- monorepo handling: flag + directory picker -->
-          <div v-if="selectedRepoId !== undefined" class="space-y-3">
+          <!-- monorepo handling: flag + multi-directory picker (hidden once a whole-repo
+               service has been added and is being configured inline) -->
+          <div v-if="selectedRepoId !== undefined && !configuredBlock" class="space-y-3">
             <USwitch
               :model-value="isMonorepo"
               :label="t('github.addService.monorepoLabel')"
@@ -340,23 +422,65 @@ function done() {
 
             <div
               v-if="isMonorepo"
-              class="rounded-md border border-slate-700/60 bg-slate-900/40 p-3"
+              class="space-y-3 rounded-md border border-slate-700/60 bg-slate-900/40 p-3"
             >
-              <p class="mb-2 text-xs text-slate-400">
+              <p class="text-xs text-slate-400">
                 {{ t('github.addService.monorepoBrowseHint') }}
               </p>
               <RepoTreeBrowser
-                v-model="selectedDirectory"
                 :repo-github-id="selectedRepoId!"
                 mode="dir"
+                multiple
+                :selected-paths="selectedDirectories"
+                :added-paths="addedDirectories"
+                @toggle="toggleDirectory"
               />
-              <p class="mt-2 truncate text-xs text-slate-400">
-                <template v-if="selectedDirectory">
-                  {{ t('github.addService.serviceDirectory') }}
-                  <code class="text-slate-200">{{ selectedDirectory }}</code>
-                </template>
-                <template v-else>{{ t('github.addService.noDirectorySelected') }}</template>
-              </p>
+
+              <!-- the selection cart + the add action sit right beside the tree, so the
+                   picked services and the button that adds them are never scrolled apart -->
+              <div class="space-y-2 rounded-md border border-slate-800 bg-slate-950/40 p-2.5">
+                <p class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+                  {{ t('github.addService.selectedServices') }}
+                </p>
+                <div v-if="selectedDirectories.length" class="flex flex-wrap gap-1.5">
+                  <span
+                    v-for="dir in selectedDirectories"
+                    :key="dir"
+                    class="inline-flex items-center gap-1 rounded bg-slate-800 px-2 py-0.5 text-xs text-slate-200"
+                  >
+                    <code class="text-slate-200">{{ dir }}</code>
+                    <button
+                      type="button"
+                      class="text-slate-400 hover:text-slate-100"
+                      :aria-label="t('github.addService.removeService', { directory: dir })"
+                      @click="removeSelected(dir)"
+                    >
+                      <UIcon name="i-lucide-x" class="h-3 w-3" />
+                    </button>
+                  </span>
+                </div>
+                <p v-else class="text-xs text-slate-500">
+                  {{ t('github.addService.noServicesSelected') }}
+                </p>
+                <div class="flex justify-end">
+                  <UButton
+                    color="primary"
+                    icon="i-lucide-plus"
+                    size="sm"
+                    :loading="adding"
+                    :disabled="!canAddServices"
+                    @click="addServices"
+                  >
+                    {{
+                      t(
+                        'github.addService.addServices',
+                        { count: selectedDirectories.length },
+                        selectedDirectories.length,
+                      )
+                    }}
+                  </UButton>
+                </div>
+              </div>
             </div>
           </div>
 
@@ -373,7 +497,7 @@ function done() {
             </div>
             <ServiceTestConfig
               :block="configuredBlock"
-              :repo="{ githubId: selectedRepoId!, directory: configuredDirectory }"
+              :repo="{ githubId: selectedRepoId! }"
               default-open
             />
             <ServiceFragments :block="configuredBlock" default-open />
@@ -395,22 +519,27 @@ function done() {
           </div>
 
           <div class="flex justify-end gap-2">
-            <UButton v-if="configuredBlock" color="neutral" variant="soft" size="sm" @click="done">
+            <!-- Monorepo adds via the cart's own button; the footer only closes. A
+                 whole-repo add shows its "Add service" button until one is added, then
+                 the inline configure panel + this Done. -->
+            <UButton
+              v-if="configuredBlock || isMonorepo"
+              color="neutral"
+              variant="soft"
+              size="sm"
+              @click="done"
+            >
               {{ t('github.addService.done') }}
             </UButton>
             <UButton
-              v-if="!configuredBlock || isMonorepo"
+              v-if="!isMonorepo && !configuredBlock"
               color="primary"
               icon="i-lucide-plus"
               :loading="adding"
               :disabled="!canAdd"
               @click="add"
             >
-              {{
-                configuredBlock && isMonorepo
-                  ? t('github.addService.addAnother')
-                  : t('github.addService.add')
-              }}
+              {{ t('github.addService.add') }}
             </UButton>
           </div>
         </template>

package/app/components/github/RepoTreeBrowser.vue

@@ -6,20 +6,37 @@
 // The selected path (relative to the repo root, as GitHub returns it) is exposed
 // via `v-model`. The component owns its own navigation/loading state so callers
 // just bind a repo id + mode; it self-loads on mount and when those change.
+//
+// `dir` mode additionally supports `multiple`: instead of the single `v-model`
+// path, the caller passes the current `selectedPaths` (a cart) + `addedPaths`
+// (directories already on the board, shown disabled) and handles the `toggle`
+// event to add/remove a directory. This lets one browse session accumulate
+// several services from ANY parent folder (the monorepo add flow) — navigating
+// away never drops earlier picks.
 import type { RepoTreeEntry } from '~/types/domain'
 
 const props = withDefaults(
   defineProps<{
     repoGithubId: number
     mode?: 'dir' | 'file'
-    /** Currently picked path (repo-root-relative), via v-model. */
+    /** Currently picked path (repo-root-relative), via v-model. Single-select only. */
     modelValue?: string
     /** Directory to open at (e.g. a monorepo service's subdirectory). */
     startPath?: string
+    /** `dir` mode: accumulate a set of picks (via `selectedPaths`/`toggle`) instead of one. */
+    multiple?: boolean
+    /** `dir` + `multiple`: the current cart of picked directories (repo-root-relative). */
+    selectedPaths?: string[]
+    /** `dir` + `multiple`: directories already on the board — listed but not selectable. */
+    addedPaths?: string[]
   }>(),
-  { mode: 'dir', startPath: '' },
+  { mode: 'dir', startPath: '', multiple: false, selectedPaths: () => [], addedPaths: () => [] },
 )
-const emit = defineEmits<{ 'update:modelValue': [string | undefined] }>()
+const emit = defineEmits<{
+  'update:modelValue': [string | undefined]
+  /** `dir` + `multiple`: the user asked to add/remove this directory from the cart. */
+  toggle: [string]
+}>()
 
 const { t } = useI18n()
 const github = useGitHubStore()
@@ -29,6 +46,15 @@ const currentPath = ref(props.startPath)
 const treeEntries = ref<RepoTreeEntry[]>([])
 const loading = ref(false)
 
+const selectedSet = computed(() => new Set(props.selectedPaths.map(normalizeRepoPath)))
+const addedSet = computed(() => new Set(props.addedPaths.map(normalizeRepoPath)))
+function isAdded(path: string): boolean {
+  return props.multiple && addedSet.value.has(normalizeRepoPath(path))
+}
+function isPicked(path: string): boolean {
+  return props.multiple ? selectedSet.value.has(normalizeRepoPath(path)) : props.modelValue === path
+}
+
 const dirEntries = computed(() => treeEntries.value.filter((e) => e.type === 'dir'))
 const fileEntries = computed(() => treeEntries.value.filter((e) => e.type === 'file'))
 const isEmpty = computed(() =>
@@ -63,7 +89,13 @@ async function browseTo(path: string) {
 }
 
 function pick(path: string) {
-  emit('update:modelValue', path)
+  if (props.multiple) {
+    // Already-on-board directories are shown for orientation but can't be re-added.
+    if (addedSet.value.has(normalizeRepoPath(path))) return
+    emit('toggle', path)
+  } else {
+    emit('update:modelValue', path)
+  }
 }
 
 // Re-open at the start path whenever the repo (or requested root) changes.
@@ -124,18 +156,21 @@ watch(
             <UIcon name="i-lucide-folder" class="h-4 w-4 shrink-0 text-amber-400" />
             <span class="truncate">{{ entry.name }}</span>
           </button>
+          <span
+            v-if="mode === 'dir' && isAdded(entry.path)"
+            class="flex shrink-0 items-center gap-1 text-xs text-slate-500"
+          >
+            <UIcon name="i-lucide-check" class="h-3.5 w-3.5" />
+            {{ t('github.repoTree.added') }}
+          </span>
           <UButton
-            v-if="mode === 'dir'"
+            v-else-if="mode === 'dir'"
             size="xs"
             variant="soft"
-            :color="modelValue === entry.path ? 'primary' : 'neutral'"
+            :color="isPicked(entry.path) ? 'primary' : 'neutral'"
             @click="pick(entry.path)"
           >
-            {{
-              modelValue === entry.path
-                ? t('github.repoTree.selected')
-                : t('github.repoTree.select')
-            }}
+            {{ isPicked(entry.path) ? t('github.repoTree.selected') : t('github.repoTree.select') }}
           </UButton>
         </li>
         <template v-if="mode === 'file'">
@@ -164,14 +199,21 @@ watch(
     </div>
 
     <!-- dir mode: pin the current folder without descending into a child -->
-    <div v-if="mode === 'dir' && currentPath" class="mt-2 flex justify-end">
+    <div
+      v-if="mode === 'dir' && currentPath && !isAdded(currentPath)"
+      class="mt-2 flex justify-end"
+    >
       <UButton
         size="xs"
         variant="soft"
-        :color="modelValue === currentPath ? 'primary' : 'neutral'"
+        :color="isPicked(currentPath) ? 'primary' : 'neutral'"
         @click="pick(currentPath)"
       >
-        {{ t('github.repoTree.useThisFolder') }}
+        {{
+          multiple && isPicked(currentPath)
+            ? t('github.repoTree.selected')
+            : t('github.repoTree.useThisFolder')
+        }}
       </UButton>
     </div>
   </div>

package/app/components/layout/SideBar.vue

@@ -100,11 +100,14 @@ watch(
   () => workspace.workspaceId,
   (id) => {
     if (!id) return
-    void documents.probe()
-    void tasks.probe()
-    void github.probe()
-    void slack.probe()
-    void library.probe()
+    // `ensureProbed` single-flights per board (app-startup initiative, item 12): on a cold open
+    // these coalesce with the board page's own github probe and don't refire on a re-mount, while a
+    // workspace switch (new id) still re-probes. `probe()` stays the explicit post-connect refresh.
+    void documents.ensureProbed()
+    void tasks.ensureProbed()
+    void github.ensureProbed()
+    void slack.ensureProbed()
+    void library.ensureProbed()
     void providerConnections.ensureLoaded().catch(() => {})
   },
   { immediate: true },

package/app/composables/useSingleFlightProbe.spec.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it, vi } from 'vitest'
+import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
+
+// Single-flight probe guard (app-startup initiative, item 12). Pure logic, no Pinia/Nuxt: a fake
+// `run` (counting calls, with a manually-resolved promise) and a mutable `id` getter.
+
+/** A `run` whose promise the test resolves by hand, plus a call counter. */
+function deferredRun() {
+  let resolve!: () => void
+  const calls = { count: 0 }
+  const run = vi.fn(() => {
+    calls.count++
+    return new Promise<void>((r) => (resolve = r))
+  })
+  return { run, calls, resolve: () => resolve() }
+}
+
+describe('useSingleFlightProbe', () => {
+  it('coalesces concurrent probe() calls for the same board into one run', async () => {
+    const { run, calls, resolve } = deferredRun()
+    const { probe } = useSingleFlightProbe(run, () => 'ws1')
+
+    const a = probe()
+    const b = probe()
+    expect(calls.count).toBe(1) // one in-flight run shared by both callers
+    resolve()
+    await Promise.all([a, b])
+  })
+
+  it('ensureProbed() is a no-op once the board is already probed', async () => {
+    const { run, calls, resolve } = deferredRun()
+    const { ensureProbed } = useSingleFlightProbe(run, () => 'ws1')
+
+    const first = ensureProbed()
+    resolve()
+    await first
+    expect(calls.count).toBe(1)
+
+    await ensureProbed() // already settled for ws1 → does not run again
+    expect(calls.count).toBe(1)
+  })
+
+  it('ensureProbed() re-runs when the workspace id changes', async () => {
+    const { run, calls, resolve } = deferredRun()
+    let id = 'ws1'
+    const { ensureProbed } = useSingleFlightProbe(run, () => id)
+
+    const first = ensureProbed()
+    resolve()
+    await first
+    expect(calls.count).toBe(1)
+
+    id = 'ws2' // a switch — connections are per board, so it must re-probe
+    const second = ensureProbed()
+    resolve()
+    await second
+    expect(calls.count).toBe(2)
+  })
+
+  it('probe() always re-runs (a deliberate refresh) even after a completed probe', async () => {
+    const { run, calls, resolve } = deferredRun()
+    const guard = useSingleFlightProbe(run, () => 'ws1')
+
+    const first = guard.probe()
+    resolve()
+    await first
+    expect(calls.count).toBe(1)
+
+    const refresh = guard.probe() // e.g. after a connect — re-reads
+    resolve()
+    await refresh
+    expect(calls.count).toBe(2)
+  })
+
+  it('a probe() refresh in flight is shared by a concurrent ensureProbed()', async () => {
+    const { run, calls, resolve } = deferredRun()
+    const guard = useSingleFlightProbe(run, () => 'ws1')
+
+    const refresh = guard.probe()
+    const ensured = guard.ensureProbed() // rides the in-flight probe rather than firing a duplicate
+    expect(calls.count).toBe(1)
+    resolve()
+    await Promise.all([refresh, ensured])
+  })
+
+  it('a superseded out-of-order completion does not stamp a stale probedId', async () => {
+    // ws1 probe starts, then a switch to ws2 starts a second — and ws2 (the newer, current board)
+    // resolves BEFORE the older ws1 probe. The late ws1 completion must NOT record ws1 as the
+    // settled board, else the next ensureProbed() for ws2 would redundantly re-run.
+    let id = 'ws1'
+    let n = 0
+    let resolve1!: () => void
+    let resolve2!: () => void
+    const run = vi.fn(() => {
+      n++
+      return new Promise<void>((r) => (n === 1 ? (resolve1 = r) : (resolve2 = r)))
+    })
+    const { ensureProbed } = useSingleFlightProbe(run, () => id)
+
+    const p1 = ensureProbed() // starts ws1
+    id = 'ws2'
+    const p2 = ensureProbed() // starts ws2 (a switch — different id)
+    expect(run).toHaveBeenCalledTimes(2)
+
+    resolve2() // the current board settles first
+    await p2
+    resolve1() // the superseded older probe settles late
+    await p1
+
+    // ws2 is the current, settled board → ensureProbed() is a no-op, not a third (redundant) run.
+    await ensureProbed()
+    expect(run).toHaveBeenCalledTimes(2)
+  })
+})

package/app/composables/useSingleFlightProbe.ts

@@ -0,0 +1,70 @@
+/**
+ * Single-flight guard for a per-workspace integration probe (app-startup initiative, item 12).
+ *
+ * On a board open the same probe is fired from several places at once — e.g. `github.probe()` runs
+ * from both the board page (to resolve the onboarding gate) and the SideBar, and the SideBar fans
+ * out five more (`documents` / `tasks` / `slack` / `library` / provider connections). Each was an
+ * independent network call, and a re-mount re-ran them. This wraps a store's probe with two
+ * behaviours keyed on the active workspace id:
+ *
+ *   - {@link probe} — always re-runs the probe (deliberate refresh, e.g. after a connect), but a
+ *     burst of concurrent callers on ONE board open shares the single in-flight request.
+ *   - {@link ensureProbed} — runs the probe AT MOST ONCE per workspace: a no-op when this board is
+ *     already probed, or the shared in-flight promise otherwise. This is what the on-board-open
+ *     fan-out uses, so the duplicate/refire collapses to one call — while a workspace SWITCH (a new
+ *     id) still re-probes, since connections are per board.
+ *
+ * The id-keying means no explicit reset on workspace change: a call for a different id than the last
+ * completed probe re-runs. `run` reads whatever workspace-scoped state it needs itself; `currentId`
+ * only supplies the key (and the "which board did this settle for" record).
+ */
+interface SingleFlightProbe {
+  probe: () => Promise<void>
+  ensureProbed: () => Promise<void>
+}
+
+export function useSingleFlightProbe(
+  run: () => Promise<void>,
+  currentId: () => string | null,
+): SingleFlightProbe {
+  let inFlight: Promise<void> | null = null
+  let inFlightId: string | null = null
+  let probedId: string | null = null
+
+  function start(id: string | null): Promise<void> {
+    const p = Promise.resolve(run()).finally(() => {
+      // Only record "settled for this board" / clear the in-flight slot when a NEWER probe hasn't
+      // superseded us. Otherwise an out-of-order completion — an older probe for board A resolving
+      // after a newer probe for board B — would stamp probedId back to A and force a redundant
+      // re-probe of B on the next ensureProbed. The newer probe owns `inFlight`, so it records the
+      // board that's actually current.
+      if (inFlight === p) {
+        probedId = id
+        inFlight = null
+        inFlightId = null
+      }
+    })
+    inFlight = p
+    inFlightId = id
+    return p
+  }
+
+  function probe(): Promise<void> {
+    const id = currentId()
+    // Share an already-running probe for the same board (the concurrent-burst case); otherwise
+    // start a fresh one — a deliberate refresh must always re-read.
+    if (inFlight && inFlightId === id) return inFlight
+    return start(id)
+  }
+
+  function ensureProbed(): Promise<void> {
+    const id = currentId()
+    // Already settled for this board and nothing running → nothing to do.
+    if (probedId === id && !inFlight) return Promise.resolve()
+    // A probe for this board is in flight → ride it rather than firing a duplicate.
+    if (inFlight && inFlightId === id) return inFlight
+    return start(id)
+  }
+
+  return { probe, ensureProbed }
+}