@cat-factory/app 0.116.5 → 0.116.7

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/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/components/settings/CustomManifestTypeEditor.vue

@@ -167,7 +167,7 @@ async function remove(type: CustomManifestType) {
         :label="t('settings.infrastructure.customType.manifestId')"
         :help="t('settings.infrastructure.customType.manifestIdHelp')"
       >
-        <UInput v-model="draft.manifestId" class="font-mono" placeholder="my-kargo-template" />
+        <UInput v-model="draft.manifestId" class="font-mono" placeholder="my-preview-template" />
       </UFormField>
       <UFormField :label="t('settings.infrastructure.customType.label')">
         <UInput v-model="draft.label" />

package/app/components/settings/InfraHandlersConfigurator.vue

@@ -276,7 +276,7 @@ const customSavedManifest = computed<Record<string, unknown> | undefined>(() =>
 
 // The registry backend that builds the `remote-custom` handler's provider. The generic
 // built-in `manifest` (BYO HTTP API) is the default; a deployment that registered a native
-// custom env backend (e.g. Kargo) can be picked here so the handler is pinned to it instead of
+// custom env backend can be picked here so the handler is pinned to it instead of
 // silently resolving to the generic manifest provider. Only backends that serve the
 // `remote-custom` engine are offered (the snapshot advertises each backend's engines).
 const providerConnections = useProviderConnectionsStore()
@@ -342,7 +342,7 @@ async function saveCustom(payload: {
       provisionType: 'custom',
       manifestId: selectedCustomId.value,
       config,
-      // Pin the chosen registry backend so a native custom backend (e.g. Kargo) builds the
+      // Pin the chosen registry backend so a native custom backend builds the
       // provider — absent, the engine would resolve to the generic manifest provider.
       backendKind: selectedBackendKind.value,
       secrets: payload.secrets,

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 }
+}

package/app/composables/useSourceIntegration.ts

@@ -1,5 +1,6 @@
 import { type ComputedRef, type Ref, computed, ref } from 'vue'
 import { apiErrorEnvelope, apiErrorStatus } from '~/composables/api/errors'
+import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
 import { useUpsertList } from '~/composables/useUpsertList'
 
 /**
@@ -25,6 +26,12 @@ export function useSourceIntegration<
   fetch: () => Promise<{ sources: Desc[]; connections: Conn[] }>
   /** Gate the probe (e.g. skip until a workspace is selected). */
   enabled?: () => boolean
+  /**
+   * The active workspace id, keying the single-flight probe (app-startup initiative, item 12): a
+   * board-open fan-out via `ensureProbed` hits the source once per board, and a workspace switch
+   * (new id) re-probes. Omitted ⇒ a single bucket (probe-once for the composable's lifetime).
+   */
+  workspaceId?: () => string | null
 }): {
   available: Ref<boolean | null>
   probeError: Ref<{ status: number | null; message: string } | null>
@@ -38,6 +45,7 @@ export function useSourceIntegration<
   upsertConnection: (conn: Conn) => void
   removeConnection: (source: Source) => void
   probe: () => Promise<void>
+  ensureProbed: () => Promise<void>
 } {
   /** null = unknown (not probed yet), true/false = integration on/off. */
   const available = ref<boolean | null>(null)
@@ -67,7 +75,7 @@ export function useSourceIntegration<
   }
 
   /** Probe the integration: resolves `available`, the sources and connections. */
-  async function probe() {
+  async function runProbe() {
     if (opts.enabled && !opts.enabled()) return
     try {
       const { sources: srcs, connections: conns } = await opts.fetch()
@@ -89,6 +97,13 @@ export function useSourceIntegration<
       connections.value = []
     }
   }
+  // Single-flight the probe (app-startup initiative, item 12): `probe()` still re-reads on demand
+  // (a connect/disconnect refresh), but the board-open fan-out uses `ensureProbed` so it fetches
+  // once per board rather than on every SideBar/page (re)mount.
+  const { probe, ensureProbed } = useSingleFlightProbe(
+    runProbe,
+    opts.workspaceId ?? (() => 'source-integration'),
+  )
 
   return {
     available,
@@ -103,5 +118,6 @@ export function useSourceIntegration<
     upsertConnection,
     removeConnection,
     probe,
+    ensureProbed,
   }
 }

package/app/pages/index.vue

@@ -245,12 +245,13 @@ watch(
 
 // Probe the GitHub integration as soon as a board is active (re-probe per board —
 // connections are per workspace). The result drives the onboarding gate below
-// before the board mounts, so an unconnected user can't slip past it. SideBar
-// re-probes once it mounts; that duplicate is harmless (probe is idempotent).
+// before the board mounts, so an unconnected user can't slip past it. `ensureProbed`
+// single-flights per board (app-startup initiative, item 12), so this and the SideBar's
+// probe collapse to one request on a cold open instead of two.
 watch(
   () => workspace.workspaceId,
   (id) => {
-    if (id) void github.probe()
+    if (id) void github.ensureProbed()
   },
   { immediate: true },
 )
@@ -268,6 +269,9 @@ const stream = useWorkspaceStream()
 // in the template would not unwrap, since `stream` is a plain object). Drives the headless
 // `workspace-stream` readiness marker the e2e suite waits on.
 const streamConnected = computed(() => stream.connected.value)
+// Final cold-open milestone (app-startup initiative, item 1): a live, reconciled board. `markBoot`
+// fires once, so only the first connect of the session times the waterfall's tail.
+watch(streamConnected, (c) => c && markBoot('stream-connected'), { immediate: true })
 const streamEverConnected = computed(() => stream.everConnected.value)
 const streamConnectionFailed = computed(() => stream.connectionFailed.value)
 watch(

package/app/stores/documents.ts

@@ -35,6 +35,7 @@ export const useDocumentsStore = defineStore('documents', () => {
     DocumentSourceDescriptor
   >({
     enabled: () => !!workspace.workspaceId,
+    workspaceId: () => workspace.workspaceId,
     fetch: async () => {
       const [{ sources }, { connections }] = await Promise.all([
         api.listDocumentSources(workspace.requireId()),
@@ -44,7 +45,7 @@ export const useDocumentsStore = defineStore('documents', () => {
     },
   })
   const { available, sources, connections, connectedSources, anyConnected } = integration
-  const { descriptorFor, connectionFor, isConnected, probe } = integration
+  const { descriptorFor, connectionFor, isConnected, probe, ensureProbed } = integration
 
   const { items: documents, upsert: upsertDoc } = useUpsertList<SourceDocument>({
     key: (d) => `${d.source}:${d.externalId}`,
@@ -187,6 +188,7 @@ export const useDocumentsStore = defineStore('documents', () => {
     isConnected,
     docsForBlock,
     probe,
+    ensureProbed,
     connect,
     disconnect,
     loadDocuments,

package/app/stores/fragmentLibrary.ts

@@ -10,6 +10,7 @@ import type {
   ResolvedFragment,
   UpdatePromptFragmentInput,
 } from '~/types/domain'
+import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
 import { useWorkspaceStore } from '~/stores/workspace'
 import { useFragmentsStore } from '~/stores/fragments'
 
@@ -62,7 +63,7 @@ function fragmentLibrarySetup(kind: FragmentOwnerKind, resolveOwnerId: () => str
   }
 
   /** Probe the feature + load this owner's tier, sources and (ws) resolved catalog. */
-  async function probe() {
+  async function runProbe() {
     const id = resolveOwnerId()
     if (!id) return
     try {
@@ -82,6 +83,10 @@ function fragmentLibrarySetup(kind: FragmentOwnerKind, resolveOwnerId: () => str
       resolved.value = []
     }
   }
+  // Single-flight the probe keyed on the owner id (app-startup initiative, item 12): the SideBar's
+  // board-open fan-out uses `ensureProbed`, so it loads once per owner; `probe()` stays the
+  // on-demand refresh (a library mutation still re-reads via the explicit calls).
+  const { probe, ensureProbed } = useSingleFlightProbe(runProbe, () => resolveOwnerId())
 
   async function refreshResolved() {
     // Every library mutation lands here: drop the picker catalog's cache so the
@@ -192,6 +197,7 @@ function fragmentLibrarySetup(kind: FragmentOwnerKind, resolveOwnerId: () => str
     viaWorkspaceId,
     builtinCount,
     probe,
+    ensureProbed,
     refreshResolved,
     create,
     createDocumentFragment,

package/app/stores/github.ts

@@ -13,6 +13,7 @@ import type {
   OpenPullRequestInput,
   ResyncRequest,
 } from '~/types/domain'
+import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
 import { useWorkspaceStore } from '~/stores/workspace'
 import { useServicesStore } from '~/stores/services'
 
@@ -96,7 +97,7 @@ export const useGitHubStore = defineStore('github', () => {
   }
 
   /** Probe the integration: resolves `available` and the current connection. */
-  async function probe() {
+  async function runProbe() {
     if (!workspace.workspaceId) return
     try {
       const { connection: conn } = await api.getGitHubConnection(workspace.requireId())
@@ -108,6 +109,11 @@ export const useGitHubStore = defineStore('github', () => {
       connection.value = null
     }
   }
+  // Single-flight the probe (app-startup initiative, item 12): `probe()` still re-reads on demand,
+  // but the on-board-open callers (the board page's onboarding gate + the SideBar) use
+  // `ensureProbed()` so their duplicate fire collapses to one request per board. A workspace switch
+  // (new id) re-probes.
+  const { probe, ensureProbed } = useSingleFlightProbe(runProbe, () => workspace.workspaceId)
 
   /** Load the cached repos, pull requests and issues for the workspace. */
   async function load() {
@@ -327,6 +333,7 @@ export const useGitHubStore = defineStore('github', () => {
     pullUrl,
     issueUrl,
     probe,
+    ensureProbed,
     load,
     ensureLoaded,
     loadAvailableRepos,

package/app/stores/slack.ts

@@ -6,6 +6,7 @@ import type {
   SlackMemberMappingEntry,
   SlackNotificationSettings,
 } from '~/types/domain'
+import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
 import { useWorkspaceStore } from '~/stores/workspace'
 
 /**
@@ -43,7 +44,8 @@ export const useSlackStore = defineStore('slack', () => {
    * is off — hide the UI. On success, capture the connection + whether OAuth is
    * available. Called on workspace change, like the GitHub probe.
    */
-  async function probe() {
+  async function runProbe() {
+    if (!workspace.workspaceId) return
     try {
       const { connection: conn, oauthEnabled: oauth } = await api.getSlackConnection(
         workspace.requireId(),
@@ -56,6 +58,9 @@ export const useSlackStore = defineStore('slack', () => {
       connection.value = null
     }
   }
+  // Single-flight the probe (app-startup initiative, item 12) so the SideBar's board-open fan-out
+  // (via `ensureProbed`) hits Slack once per board; `probe()` stays the on-demand refresh.
+  const { probe, ensureProbed } = useSingleFlightProbe(runProbe, () => workspace.workspaceId)
 
   /** Resolve the "Add to Slack" OAuth URL (only when oauthEnabled). */
   function installUrl(): Promise<string> {
@@ -130,6 +135,7 @@ export const useSlackStore = defineStore('slack', () => {
     saving,
     connected,
     probe,
+    ensureProbed,
     installUrl,
     connectWithToken,
     disconnect,

package/app/stores/tasks.ts

@@ -34,6 +34,7 @@ export const useTasksStore = defineStore('tasks', () => {
   // (integration disabled vs a server/backend error) instead of "install it first".
   const integration = useSourceIntegration<TaskSourceKind, TaskConnection, TaskSourceState>({
     enabled: () => !!workspace.workspaceId,
+    workspaceId: () => workspace.workspaceId,
     fetch: async () => {
       const [{ sources }, { connections }] = await Promise.all([
         api.listTaskSources(workspace.requireId()),
@@ -44,7 +45,7 @@ export const useTasksStore = defineStore('tasks', () => {
   })
   const { available, probeError, sources, connections, connectedSources, anyConnected } =
     integration
-  const { descriptorFor, connectionFor, isConnected, probe } = integration
+  const { descriptorFor, connectionFor, isConnected, probe, ensureProbed } = integration
 
   const { items: tasks, upsert: upsertTask } = useUpsertList<SourceTask>({
     key: (t) => `${t.source}:${t.externalId}`,
@@ -224,6 +225,7 @@ export const useTasksStore = defineStore('tasks', () => {
     isConnected,
     tasksForBlock,
     probe,
+    ensureProbed,
     checkSetup,
     connect,
     startLinearOAuth,

package/app/stores/workspace.spec.ts

@@ -112,3 +112,70 @@ describe('workspace store refresh ordering', () => {
     expect(board.getBlock('spawned')).toBeDefined()
   })
 })
+
+// Cold-open waterfall flattening (app-startup initiative, item 8): `init()` fetches the persisted
+// board's snapshot SPECULATIVELY, in parallel with the workspace list, instead of waiting for the
+// list to resolve before the (heaviest) snapshot fetch. These pin that (a) a still-valid persisted
+// board is opened with EXACTLY ONE snapshot fetch — the reused speculative one — and (b) a stale
+// persisted id falls back cleanly, discarding the speculative result.
+describe('workspace store cold-open speculative snapshot', () => {
+  beforeEach(() => {
+    // A working accounts store (the inert stub returns non-promises, which init's `.catch` chain +
+    // `accountWorkspaces` can't use). Auth off ⇒ all boards are in scope.
+    vi.stubGlobal('useAccountsStore', () => ({
+      load: async () => {},
+      enabled: false,
+      activeAccountId: null,
+    }))
+  })
+
+  it('reuses the speculative persisted snapshot — one getWorkspace on a cold open', async () => {
+    const getWorkspace = vi.fn().mockResolvedValue(snapshot('ws1', [block('f1')]))
+    const listWorkspaces = vi.fn().mockResolvedValue([{ id: 'ws1', name: 'ws1', accountId: null }])
+    vi.stubGlobal('useApi', () => ({ getWorkspace, listWorkspaces }))
+
+    const ws = useWorkspaceStore()
+    ws.workspaceId = 'ws1' // the persisted board (read from localStorage on a real cold open)
+    await ws.init()
+
+    // The persisted board's snapshot was fetched exactly once (speculatively) and REUSED —
+    // resolveActiveBoard did not fetch it a second time.
+    expect(listWorkspaces).toHaveBeenCalledTimes(1)
+    expect(getWorkspace).toHaveBeenCalledTimes(1)
+    expect(getWorkspace).toHaveBeenCalledWith('ws1')
+    expect(useBoardStore().getBlock('f1')).toBeDefined()
+  })
+
+  it('falls back to the first board when the persisted id is gone', async () => {
+    const getWorkspace = vi.fn(async (id: string) => {
+      if (id === 'gone') throw new Error('404') // the speculative fetch for a removed board rejects
+      return snapshot(id, [block('f2')])
+    })
+    const listWorkspaces = vi.fn().mockResolvedValue([{ id: 'ws2', name: 'ws2', accountId: null }])
+    vi.stubGlobal('useApi', () => ({ getWorkspace, listWorkspaces }))
+
+    const ws = useWorkspaceStore()
+    ws.workspaceId = 'gone'
+    await ws.init()
+
+    // The rejected speculative fetch didn't wedge init; it fell back to the one board in scope.
+    expect(getWorkspace).toHaveBeenNthCalledWith(1, 'gone')
+    expect(getWorkspace).toHaveBeenCalledWith('ws2')
+    expect(ws.workspaceId).toBe('ws2')
+    expect(useBoardStore().getBlock('f2')).toBeDefined()
+  })
+
+  it('no persisted board: no speculative fetch, opens the first board', async () => {
+    const getWorkspace = vi.fn().mockResolvedValue(snapshot('ws3', [block('f3')]))
+    const listWorkspaces = vi.fn().mockResolvedValue([{ id: 'ws3', name: 'ws3', accountId: null }])
+    vi.stubGlobal('useApi', () => ({ getWorkspace, listWorkspaces }))
+
+    const ws = useWorkspaceStore()
+    ws.workspaceId = null
+    await ws.init()
+
+    expect(getWorkspace).toHaveBeenCalledTimes(1)
+    expect(getWorkspace).toHaveBeenCalledWith('ws3')
+    expect(useBoardStore().getBlock('f3')).toBeDefined()
+  })
+})

package/app/stores/workspace.ts

@@ -32,6 +32,7 @@ import { useConsensusStore } from '~/stores/consensus'
 import { useGitHubStore } from '~/stores/github'
 import { useFragmentsStore } from '~/stores/fragments'
 import { useProviderConnectionsStore } from '~/stores/providerConnections'
+import { markBoot } from '~/utils/bootMarks'
 
 /**
  * Owns the active workspace and bootstraps the app against the backend. On load
@@ -159,6 +160,17 @@ export const useWorkspaceStore = defineStore(
       ready.value = false
       error.value = null
       try {
+        // Cold-open waterfall flattening (app-startup initiative, item 8): the persisted board is
+        // usually known from localStorage BEFORE any request fires, and its snapshot is the app's
+        // heaviest payload (the ~18-read aggregate). Fetch it SPECULATIVELY in parallel with the
+        // workspace list + accounts instead of waiting for the list to resolve first — one fewer
+        // sequential round trip on the critical path. Validated for membership in
+        // resolveActiveBoard; a stale/removed persisted id just discards the speculative result and
+        // falls back to today's path. `.catch` keeps a gone-board 404 from rejecting the whole init.
+        const persistedId = workspaceId.value
+        const speculativeSnapshot = persistedId
+          ? api.getWorkspace(persistedId).catch(() => null)
+          : null
         // Accounts (an auth concept — empty in dev, which leaves boards unscoped) and the
         // workspace list are independent, so fetch them concurrently. resolveActiveBoard
         // needs both, so it still runs after.
@@ -168,25 +180,38 @@ export const useWorkspaceStore = defineStore(
             .catch(() => {}),
           api.listWorkspaces(),
         ])
+        markBoot('workspaces-listed')
         workspaces.value = workspaceList
-        await resolveActiveBoard()
+        await resolveActiveBoard(await speculativeSnapshot)
+        markBoot('snapshot-hydrated')
         ready.value = true
       } catch (e) {
         error.value = e instanceof Error ? e.message : 'Failed to reach the backend.'
       }
     }
 
-    /** Open the persisted board (aligning the active account to it), else pick/create one. */
-    async function resolveActiveBoard() {
+    /**
+     * Open the persisted board (aligning the active account to it), else pick/create one.
+     *
+     * `prefetched` is the speculatively-fetched snapshot for the persisted board (see {@link init}):
+     * when it's for the SAME still-valid board we reuse it instead of re-fetching, so the cold open
+     * pays exactly one snapshot fetch — overlapped with the workspace list rather than after it.
+     */
+    async function resolveActiveBoard(prefetched?: WorkspaceSnapshot | null) {
       const accounts = useAccountsStore()
       if (workspaceId.value) {
         const existing = workspaces.value.find((w) => w.id === workspaceId.value)
         if (existing) {
           if (accounts.enabled && existing.accountId) accounts.activeAccountId = existing.accountId
-          hydrate(await api.getWorkspace(existing.id))
+          hydrate(
+            prefetched && prefetched.workspace.id === existing.id
+              ? prefetched
+              : await api.getWorkspace(existing.id),
+          )
           return
         }
-        // Persisted board is gone (deleted, or now another tenant's) — fall through.
+        // Persisted board is gone (deleted, or now another tenant's) — fall through (and discard the
+        // now-irrelevant speculative snapshot).
         workspaceId.value = null
       }
       const first = accountWorkspaces.value[0]

package/app/utils/bootMarks.ts

@@ -0,0 +1,49 @@
+/**
+ * Cold-open instrumentation (app-startup initiative, item 1). The SPA is `ssr: false`, so the whole
+ * "launch → usable board" path runs client-side after the bundle loads, and nothing timed the
+ * milestones along it. `markBoot` drops a `performance.mark` at each one plus `performance.measure`s
+ * so the cold-open waterfall is visible in a Playwright/browser trace:
+ *   - one `cat-factory:open→<milestone>` measure = absolute ms from navigation start to the milestone,
+ *   - one `cat-factory:<prev>→<milestone>` measure = the segment since the previous milestone.
+ *
+ * Milestones (fired once per cold open): `auth-ready` → `workspaces-listed` → `snapshot-hydrated`
+ * → `stream-connected`. It is pure instrumentation — no behaviour depends on it — and it is a no-op
+ * where the User Timing API is unavailable (SSR/prerender, ancient engines), so callers never guard.
+ */
+
+const PREFIX = 'cat-factory'
+
+/** Milestones already stamped this session — cold-open marks fire ONCE (later switches don't re-time). */
+const seen = new Set<string>()
+/** The previous milestone's mark name, so each call can measure the segment since it. */
+let previousMark: string | null = null
+
+export function markBoot(milestone: string): void {
+  if (seen.has(milestone)) return
+  if (typeof performance === 'undefined' || typeof performance.mark !== 'function') return
+  seen.add(milestone)
+  const mark = `${PREFIX}:${milestone}`
+  const prev = previousMark
+  try {
+    performance.mark(mark)
+  } catch {
+    return
+  }
+  // Advance the chain as soon as the mark itself lands, INDEPENDENT of the derived measures below.
+  // Some engines reject the numeric-`start` measure form; if that throws we still want the NEXT
+  // milestone to measure its segment from THIS mark rather than a stale earlier one.
+  previousMark = mark
+  try {
+    // Absolute time from navigation start (DOMHighResTimeStamp 0 = timeOrigin) to this milestone.
+    performance.measure(`${PREFIX}:open→${milestone}`, { start: 0, end: mark })
+    // The segment since the previous milestone — the waterfall bar.
+    if (prev) {
+      performance.measure(`${PREFIX}:${prev.slice(PREFIX.length + 1)}→${milestone}`, {
+        start: prev,
+        end: mark,
+      })
+    }
+  } catch {
+    // Derived measures unsupported on this engine; the marks still land, so the trace is usable.
+  }
+}

package/i18n/locales/de.json

@@ -137,7 +137,7 @@
         "editTitle": "{id} bearbeiten",
         "addTitle": "Einen Typ hinzufügen",
         "manifestId": "Manifest-ID",
-        "manifestIdHelp": "Ein Lower-Kebab-Slug, z. B. my-kargo-template.",
+        "manifestIdHelp": "Ein Lower-Kebab-Slug, z. B. my-preview-template.",
         "label": "Bezeichnung",
         "acceptsInputHint": "Eingabehinweis (optional)",
         "acceptsInputHintHelp": "Beschreibt die Eingabeform, die der Provider erwartet.",
@@ -1737,7 +1737,7 @@
       },
       "ephemeralEnvironments": {
         "title": "Testumgebung nicht konfiguriert",
-        "body": "Es ist kein Anbieter für ephemere Umgebungen registriert, sodass Test-Agenten, die eine Live-Umgebung benötigen, nicht laufen können. Verbinden Sie einen, um sie zu aktivieren.",
+        "body": "Es ist kein Anbieter für ephemere Umgebungen registriert, sodass Test-Agenten, die eine aktive Vorschau-Umgebung benötigen, nicht laufen können. Öffnen Sie unten „Testumgebungen“ und verbinden Sie einen Kubernetes-Cluster oder einen benutzerdefinierten HTTP-Umgebungsanbieter, um sie zu aktivieren.",
         "action": "Environment konfigurieren"
       },
       "binaryStorage": {

package/i18n/locales/en.json

@@ -1660,7 +1660,7 @@
       },
       "ephemeralEnvironments": {
         "title": "Test environment not configured",
-        "body": "No ephemeral environment provider is registered, so testing agents that need a live environment can't run. Connect one to enable them.",
+        "body": "No ephemeral environment provider is registered, so testing agents that need a live preview environment can't run. Open Test environments below and connect a Kubernetes cluster or a custom HTTP environment provider to enable them.",
         "action": "Configure environment"
       },
       "binaryStorage": {
@@ -1989,7 +1989,7 @@
         "editTitle": "Edit {id}",
         "addTitle": "Add a type",
         "manifestId": "Manifest id",
-        "manifestIdHelp": "A lower-kebab slug, e.g. my-kargo-template.",
+        "manifestIdHelp": "A lower-kebab slug, e.g. my-preview-template.",
         "label": "Label",
         "acceptsInputHint": "Input hint (optional)",
         "acceptsInputHintHelp": "Describes the input shape the provider expects.",

package/i18n/locales/es.json

@@ -1600,7 +1600,7 @@
       },
       "ephemeralEnvironments": {
         "title": "Entorno de pruebas no configurado",
-        "body": "No hay ningún proveedor de entornos efímeros registrado, así que los agentes de pruebas que necesitan un entorno activo no pueden ejecutarse. Conecta uno para habilitarlos.",
+        "body": "No hay ningún proveedor de entornos efímeros registrado, así que los agentes de pruebas que necesitan un entorno de vista previa activo no pueden ejecutarse. Abre Entornos de prueba abajo y conecta un clúster de Kubernetes o un proveedor de entornos HTTP personalizado para habilitarlos.",
         "action": "Configurar entorno"
       },
       "binaryStorage": {
@@ -2511,7 +2511,7 @@
         "editTitle": "Editar {id}",
         "addTitle": "Añadir un tipo",
         "manifestId": "Id del manifiesto",
-        "manifestIdHelp": "Un slug en minúsculas y guiones, p. ej. my-kargo-template.",
+        "manifestIdHelp": "Un slug en minúsculas y guiones, p. ej. my-preview-template.",
         "label": "Etiqueta",
         "acceptsInputHint": "Pista de entrada (opcional)",
         "acceptsInputHintHelp": "Describe la forma de entrada que espera el proveedor.",

package/i18n/locales/fr.json

@@ -1600,7 +1600,7 @@
       },
       "ephemeralEnvironments": {
         "title": "Environnement de test non configuré",
-        "body": "Aucun fournisseur d'environnements éphémères n'est enregistré, donc les agents de test qui nécessitent un environnement actif ne peuvent pas s'exécuter. Connectez-en un pour les activer.",
+        "body": "Aucun fournisseur d'environnements éphémères n'est enregistré, donc les agents de test qui nécessitent un environnement de prévisualisation actif ne peuvent pas s'exécuter. Ouvrez Environnements de test ci-dessous et connectez un cluster Kubernetes ou un fournisseur d'environnements HTTP personnalisé pour les activer.",
         "action": "Configurer l'environnement"
       },
       "binaryStorage": {
@@ -2511,7 +2511,7 @@
         "editTitle": "Modifier {id}",
         "addTitle": "Ajouter un type",
         "manifestId": "Id du manifeste",
-        "manifestIdHelp": "Un slug en minuscules avec des tirets, p. ex. my-kargo-template.",
+        "manifestIdHelp": "Un slug en minuscules avec des tirets, p. ex. my-preview-template.",
         "label": "Libellé",
         "acceptsInputHint": "Indice d'entrée (facultatif)",
         "acceptsInputHintHelp": "Décrit la forme d'entrée attendue par le fournisseur.",

package/i18n/locales/he.json

@@ -1600,7 +1600,7 @@
       },
       "ephemeralEnvironments": {
         "title": "סביבת בדיקות אינה מוגדרת",
-        "body": "לא רשום שום ספק סביבות ארעיות, ולכן סוכני בדיקה הזקוקים לסביבה פעילה אינם יכולים לפעול. חברו ספק כדי להפעיל אותם.",
+        "body": "לא רשום שום ספק סביבות ארעיות, ולכן סוכני בדיקה הזקוקים לסביבת תצוגה מקדימה פעילה אינם יכולים לפעול. פתחו את 'סביבות בדיקה' למטה וחברו אשכול Kubernetes או ספק סביבות HTTP מותאם אישית כדי להפעיל אותם.",
         "action": "הגדרת סביבה"
       },
       "binaryStorage": {
@@ -1928,7 +1928,7 @@
         "editTitle": "עריכת {id}",
         "addTitle": "הוספת סוג",
         "manifestId": "מזהה מניפסט",
-        "manifestIdHelp": "slug באותיות קטנות ומקפים, לדוגמה my-kargo-template.",
+        "manifestIdHelp": "slug באותיות קטנות ומקפים, לדוגמה my-preview-template.",
         "label": "תווית",
         "acceptsInputHint": "רמז קלט (אופציונלי)",
         "acceptsInputHintHelp": "מתאר את צורת הקלט שהספק מצפה לה.",

package/i18n/locales/it.json

@@ -137,7 +137,7 @@
         "editTitle": "Modifica {id}",
         "addTitle": "Aggiungi un tipo",
         "manifestId": "Id del manifest",
-        "manifestIdHelp": "Uno slug in lower-kebab, es. my-kargo-template.",
+        "manifestIdHelp": "Uno slug in lower-kebab, es. my-preview-template.",
         "label": "Etichetta",
         "acceptsInputHint": "Suggerimento di input (facoltativo)",
         "acceptsInputHintHelp": "Descrive la forma di input attesa dal provider.",
@@ -1737,7 +1737,7 @@
       },
       "ephemeralEnvironments": {
         "title": "Ambiente di test non configurato",
-        "body": "Nessun provider di ambiente effimero è registrato, quindi gli agenti di test che necessitano di un ambiente live non possono funzionare. Connettine uno per abilitarli.",
+        "body": "Nessun provider di ambiente effimero è registrato, quindi gli agenti di test che necessitano di un ambiente di anteprima live non possono funzionare. Apri Ambienti di test qui sotto e connetti un cluster Kubernetes o un provider di ambienti HTTP personalizzato per abilitarli.",
         "action": "Configura l'ambiente"
       },
       "binaryStorage": {

package/i18n/locales/ja.json

@@ -1600,7 +1600,7 @@
       },
       "ephemeralEnvironments": {
         "title": "テスト環境が未設定です",
-        "body": "エフェメラル環境プロバイダーが登録されていないため、稼働中の環境を必要とするテストエージェントを実行できません。有効にするには接続してください。",
+        "body": "エフェメラル環境プロバイダーが登録されていないため、稼働中のプレビュー環境を必要とするテストエージェントを実行できません。下の「テスト環境」を開き、Kubernetes クラスターまたはカスタム HTTP 環境プロバイダーを接続して有効にしてください。",
         "action": "環境を設定"
       },
       "binaryStorage": {
@@ -1929,7 +1929,7 @@
         "editTitle": "{id} を編集",
         "addTitle": "タイプを追加",
         "manifestId": "マニフェスト ID",
-        "manifestIdHelp": "小文字とハイフンの slug。例: my-kargo-template。",
+        "manifestIdHelp": "小文字とハイフンの slug。例: my-preview-template。",
         "label": "ラベル",
         "acceptsInputHint": "入力ヒント（任意）",
         "acceptsInputHintHelp": "プロバイダーが期待する入力形式を説明します。",

package/i18n/locales/pl.json

@@ -1600,7 +1600,7 @@
       },
       "ephemeralEnvironments": {
         "title": "Środowisko testowe nie jest skonfigurowane",
-        "body": "Nie zarejestrowano żadnego dostawcy środowisk efemerycznych, więc agenci testowi wymagający działającego środowiska nie mogą działać. Podłącz jednego, aby je włączyć.",
+        "body": "Nie zarejestrowano żadnego dostawcy środowisk efemerycznych, więc agenci testowi wymagający działającego środowiska podglądu nie mogą działać. Otwórz poniżej „Środowiska testowe” i podłącz klaster Kubernetes lub niestandardowego dostawcę środowisk HTTP, aby je włączyć.",
         "action": "Skonfiguruj środowisko"
       },
       "binaryStorage": {
@@ -2511,7 +2511,7 @@
         "editTitle": "Edytuj {id}",
         "addTitle": "Dodaj typ",
         "manifestId": "Id manifestu",
-        "manifestIdHelp": "Slug małymi literami z myślnikami, np. my-kargo-template.",
+        "manifestIdHelp": "Slug małymi literami z myślnikami, np. my-preview-template.",
         "label": "Etykieta",
         "acceptsInputHint": "Wskazówka wejścia (opcjonalnie)",
         "acceptsInputHintHelp": "Opisuje format wejścia oczekiwany przez dostawcę.",

package/i18n/locales/tr.json

@@ -1600,7 +1600,7 @@
       },
       "ephemeralEnvironments": {
         "title": "Test ortamı yapılandırılmadı",
-        "body": "Kayıtlı bir geçici ortam sağlayıcısı yok; bu nedenle çalışan bir ortama ihtiyaç duyan test aracıları çalışamaz. Etkinleştirmek için bir tane bağlayın.",
+        "body": "Kayıtlı bir geçici ortam sağlayıcısı yok; bu nedenle çalışan bir önizleme ortamına ihtiyaç duyan test aracıları çalışamaz. Aşağıdaki Test ortamları sekmesini açın ve etkinleştirmek için bir Kubernetes kümesi ya da özel bir HTTP ortam sağlayıcısı bağlayın.",
         "action": "Ortamı yapılandır"
       },
       "binaryStorage": {
@@ -1929,7 +1929,7 @@
         "editTitle": "{id} düzenle",
         "addTitle": "Tür ekle",
         "manifestId": "Manifest kimliği",
-        "manifestIdHelp": "Küçük harf ve tireli bir slug, ör. my-kargo-template.",
+        "manifestIdHelp": "Küçük harf ve tireli bir slug, ör. my-preview-template.",
         "label": "Etiket",
         "acceptsInputHint": "Girdi ipucu (isteğe bağlı)",
         "acceptsInputHintHelp": "Sağlayıcının beklediği girdi biçimini açıklar.",

package/i18n/locales/uk.json

@@ -1600,7 +1600,7 @@
       },
       "ephemeralEnvironments": {
         "title": "Тестове середовище не налаштоване",
-        "body": "Не зареєстровано жодного постачальника ефемерних середовищ, тож тестові агенти, яким потрібне робоче середовище, не можуть працювати. Підключіть постачальника, щоб увімкнути їх.",
+        "body": "Не зареєстровано жодного постачальника ефемерних середовищ, тож тестові агенти, яким потрібне робоче середовище попереднього перегляду, не можуть працювати. Відкрийте нижче «Тестові середовища» та підключіть кластер Kubernetes або власного постачальника середовищ HTTP, щоб увімкнути їх.",
         "action": "Налаштувати середовище"
       },
       "binaryStorage": {
@@ -2511,7 +2511,7 @@
         "editTitle": "Редагувати {id}",
         "addTitle": "Додати тип",
         "manifestId": "Id маніфесту",
-        "manifestIdHelp": "Slug у нижньому регістрі з дефісами, напр. my-kargo-template.",
+        "manifestIdHelp": "Slug у нижньому регістрі з дефісами, напр. my-preview-template.",
         "label": "Мітка",
         "acceptsInputHint": "Підказка вводу (необов'язково)",
         "acceptsInputHintHelp": "Описує форму вводу, яку очікує провайдер.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.116.5",
+  "version": "0.116.7",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "valibot": "^1.4.2",
     "vue": "3.5.39",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.128.1"
+    "@cat-factory/contracts": "0.128.2"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",