@cat-factory/app 0.171.0 → 0.173.0

package/app/components/settings/InfrastructureWindow.vue

@@ -13,6 +13,7 @@ import { computed, ref, watch } from 'vue'
 import type { ProviderConnectionKind } from '~/types/providerConnections'
 import InfrastructureBackendPicker from '~/components/settings/InfrastructureBackendPicker.vue'
 import InfraHandlersConfigurator from '~/components/settings/InfraHandlersConfigurator.vue'
+import DefaultProvisionTypeSection from '~/components/settings/DefaultProvisionTypeSection.vue'
 import LocalContainerPoolSettings from '~/components/settings/LocalContainerPoolSettings.vue'
 import SharedStacksPanel from '~/components/settings/SharedStacksPanel.vue'
 
@@ -131,10 +132,16 @@ watch([tabs, () => store.loaded], () => {
           </template>
           <template #environment>
             <div class="space-y-4">
+              <!-- What this board's services PRODUCE by default. Comes first because it is the
+                   question the per-type handlers below answer "how" for, and because a board that
+                   has never chosen is the one the setup banner deep-links straight to here. -->
+              <DefaultProvisionTypeSection />
               <!-- The Tester's environment is driven by each SERVICE's declared provision type
                    (the "what/where"); the workspace configures HOW each type is handled here —
                    the engine + connection per provision type, plus the custom-type catalog. -->
-              <InfraHandlersConfigurator />
+              <div class="border-t border-slate-800 pt-4">
+                <InfraHandlersConfigurator />
+              </div>
             </div>
           </template>
           <template #shared-stacks>

package/app/composables/useContextLinking.ts

@@ -161,8 +161,18 @@ export function useContextLinking() {
    * reasons as the body, and a "Copy details" action that puts the full diagnostic
    * report ({@link buildLinkFailureReport}) on the clipboard. Sticky (`duration: 0`)
    * so the cause stays readable long enough to act on. No-op when nothing failed.
+   *
+   * `opts.title` names what WAS created, which differs per host ("Task added, but …" vs
+   * "Initiative created, but …"). It is a resolver over the count rather than a message key, so
+   * each caller keeps a literal key at its own translation call site — passing the key through
+   * would make it a variable, which defeats both the typed-message-key check and the extractor's
+   * static scan — and the plural choice has to be made against the same count.
    */
-  function presentLinkFailures(failures: LinkFailure[], blockId?: string): void {
+  function presentLinkFailures(
+    failures: LinkFailure[],
+    blockId?: string,
+    opts: { title?: (count: number) => string } = {},
+  ): void {
     if (failures.length === 0) return
     const description = failures.map((f) => `${f.item.title}: ${f.message}`).join('\n')
     const report = buildLinkFailureReport(failures, {
@@ -171,7 +181,9 @@ export function useContextLinking() {
       when: new Date().toISOString(),
     })
     toast.add({
-      title: t('board.addTask.linkFailed', { count: failures.length }, failures.length),
+      title:
+        opts.title?.(failures.length) ??
+        t('board.addTask.linkFailed', { count: failures.length }, failures.length),
       description,
       icon: 'i-lucide-triangle-alert',
       color: 'warning',

package/app/composables/useInitiativePlanning.ts

@@ -4,6 +4,7 @@ import { useExecutionStore } from '~/stores/execution'
 import { useInitiativesStore } from '~/stores/initiative'
 import { usePipelinesStore } from '~/stores/pipelines'
 import { useUiStore } from '~/stores/ui'
+import { interviewGatePhase } from '~/utils/interviewGate'
 
 /**
  * Shared planning affordances for an `initiative`-level block, used by BOTH the board card
@@ -37,13 +38,32 @@ export function useInitiativePlanning(blockId: MaybeRefOrGetter<string>) {
   const running = computed(() => !!block.value?.executionId)
 
   /**
-   * The interviewer has PARKED the planning run for the human. Keyed purely on the interview's
-   * parked `status` (`awaiting`) — NOT on whether individual questions are still blank — so the
-   * "Answer planning questions" affordance stays available even after every question is filled but
-   * before the human resumes. Gating on unanswered questions would hide the only path back to the
-   * interview window once all are answered, stranding the still-parked run.
+   * The live interview phase, derived from the entity AND the planning run (see
+   * {@link interviewGatePhase} for why the run status is load-bearing).
    */
-  const awaitingAnswers = computed(() => initiative.value?.interview?.status === 'awaiting')
+  const interviewPhase = computed(() =>
+    interviewGatePhase(
+      initiative.value?.interview?.status,
+      execution.getByBlock(toValue(blockId))?.status,
+    ),
+  )
+
+  /**
+   * The interviewer has PARKED the planning run for the human. NOT keyed on whether individual
+   * questions are still blank — the "Answer planning questions" affordance must stay available
+   * after every question is filled but before the human resumes, or the only path back to the
+   * interview window disappears and the still-parked run is stranded.
+   *
+   * It IS keyed on the run not being mid-pass: after a continue/proceed the entity still reads
+   * `awaiting` for the whole (slow) interviewer pass, so an entity-only reading keeps the card
+   * pulsing and offering "Answer planning questions" over a question set that is already
+   * submitted and about to be replaced. {@link interviewing} covers that window instead, and a
+   * pass that fails takes the run out of `running`, so this comes back rather than stranding.
+   */
+  const awaitingAnswers = computed(() => interviewPhase.value === 'awaiting')
+
+  /** An interviewer pass is running — the human is waiting on the planner, not the reverse. */
+  const interviewing = computed(() => interviewPhase.value === 'working')
 
   /**
    * Optimistic start flag: flip true the instant "Run planning" is clicked, before the stream
@@ -82,7 +102,9 @@ export function useInitiativePlanning(blockId: MaybeRefOrGetter<string>) {
   return {
     planningPipeline,
     running,
+    interviewPhase,
     awaitingAnswers,
+    interviewing,
     starting,
     runPlanning,
     openPlanning,

package/app/pages/index.vue

@@ -9,6 +9,7 @@ import GitHubPatBanner from '~/components/layout/GitHubPatBanner.vue'
 import AiProvidersBanner from '~/components/layout/AiProvidersBanner.vue'
 import ProviderConfigBanner from '~/components/layout/ProviderConfigBanner.vue'
 import InfraSetupBanner from '~/components/layout/InfraSetupBanner.vue'
+import DefaultTestEnvBanner from '~/components/layout/DefaultTestEnvBanner.vue'
 // Always-mounted, fast-path surfaces (opened frequently during a run / board edits, or
 // store-driven so they must react from anywhere — kept eager for snappy open/close).
 import PipelineBuilder from '~/components/pipeline/PipelineBuilder.vue'
@@ -155,6 +156,9 @@ onMounted(() => {
   // Honour a `cat-factory k3s` CLI hand-off (`?infraSetup=local-k3s&…`): open the Infrastructure
   // window pre-seeded with the provisioned connection so the user only pastes the token + saves.
   ui.consumeK3sSetupDeepLink()
+  // Honour the setup banner's shareable link (`?settings=default-test-env`): open the
+  // Infrastructure window on the default test-environment provisioning section.
+  ui.consumeDefaultProvisionDeepLink()
 })
 
 // Per-session guards so each AI-onboarding dialog auto-opens at most once (later opens are
@@ -179,6 +183,9 @@ watch(
       ui.resetAiOnboarding()
       // Infra-setup banner session dismissals are per-workspace too — clear them on switch.
       ui.resetInfraSetupDismissals()
+      // Same for the default test-environment prompt: each board records its own choice, so a
+      // dismissal on one must not hide the (independent) prompt for another.
+      ui.resetDefaultProvisionDismissal()
       // A different board has its own pipeline library, so re-arm the once-per-session advisory.
       ui.pipelineHealthSeen = false
     }
@@ -312,7 +319,10 @@ watch(
          - AI-readiness (no usable model source, or default preset uses unavailable models).
          - Infrastructure provider (env/runner-pool wired but missing mandatory config).
          - Infra-setup (this deployment needs an executor / test env / storage the operator hasn't
-           defined yet, so a class of agents can't run). -->
+           defined yet, so a class of agents can't run).
+         - Default test environment (this BOARD has never chosen the provisioning mechanism its
+           new services should default to). Last in the column: it asks for a convenience default,
+           so it yields to the prompts about things that are outright broken. -->
     <div
       v-if="workspace.ready && !needsGitHubInstall && !githubProbePending"
       class="pointer-events-none absolute inset-x-0 top-0 z-40 flex flex-col items-center gap-2 px-4 pt-4"
@@ -320,6 +330,7 @@ watch(
       <AiProvidersBanner />
       <ProviderConfigBanner />
       <InfraSetupBanner />
+      <DefaultTestEnvBanner />
     </div>
 
     <!-- Resolving whether the GitHub App is installed, before we decide what to show. -->

package/app/stores/ui/modals.ts

@@ -1,6 +1,10 @@
 import { ref } from 'vue'
 import type { DocumentSourceKind, InfraSetupArea, TaskSourceKind } from '~/types/domain'
 import type { PendingContext } from '~/composables/useContextLinking'
+import {
+  DEFAULT_PROVISION_DEEP_LINK_PARAM,
+  DEFAULT_PROVISION_DEEP_LINK_VALUE,
+} from '~/utils/defaultProvisioning'
 
 /** Values used to seed the add-task form when it is opened from another surface. */
 export interface AddTaskPrefill {
@@ -761,6 +765,29 @@ function createInfraModals(resetHubReturn: ResetHubReturn) {
     const qs = params.toString()
     history.replaceState(null, '', window.location.pathname + (qs ? `?${qs}` : ''))
   }
+  // Open the Infrastructure window straight at the default test-environment provisioning
+  // mechanism (the section at the top of the Test-environments tab). Distinct from
+  // `openProviderConnection('environment')` only in intent today, but it is the target of a
+  // SHAREABLE deep link (see `consumeDefaultProvisionDeepLink`), so it gets its own entry point
+  // rather than leaving the banner and the URL to duplicate the tab choice independently.
+  function openDefaultProvisionSettings() {
+    resetHubReturn()
+    infrastructureTab.value = 'environment'
+    infrastructureOpen.value = true
+  }
+  // Capture the `?settings=default-test-env` deep link on app load — the URL the setup banner
+  // shows, so an operator can send "go configure this" to a teammate rather than describing
+  // where the screen lives. Strips the param afterwards (mirroring the k3s hand-off above) so a
+  // reload doesn't re-open the window and the link isn't left in history. No-op when absent.
+  function consumeDefaultProvisionDeepLink() {
+    if (typeof window === 'undefined') return
+    const params = new URLSearchParams(window.location.search)
+    if (params.get(DEFAULT_PROVISION_DEEP_LINK_PARAM) !== DEFAULT_PROVISION_DEEP_LINK_VALUE) return
+    openDefaultProvisionSettings()
+    params.delete(DEFAULT_PROVISION_DEEP_LINK_PARAM)
+    const qs = params.toString()
+    history.replaceState(null, '', window.location.pathname + (qs ? `?${qs}` : ''))
+  }
   // Launch the environment setup wizard, optionally preselecting the service frame it targets
   // (the inspector nudge passes the frame; the navbar entry opens it with the pick step active).
   function openEnvironmentSetup(frameId: string | null = null) {
@@ -781,6 +808,8 @@ function createInfraModals(resetHubReturn: ResetHubReturn) {
     consumeK3sSetupDeepLink,
     environmentWizardOpen,
     environmentWizardFrameId,
+    openDefaultProvisionSettings,
+    consumeDefaultProvisionDeepLink,
     openProviderConnection,
     closeProviderConnection,
     openEnvironmentSetup,
@@ -815,6 +844,20 @@ function createAiOnboardingModals() {
     infraSetupSessionDismissed.value = []
   }
 
+  // Default-test-environment banner: a single per-SESSION dismissal, cleared on workspace switch
+  // like the flags above. There is deliberately no PERMANENT dismissal here (unlike the
+  // infra-setup areas): the prompt asks for a DECISION, and every answer — including `infraless`
+  // ("services stand up no environment") — is recordable in one click, so "silence this forever
+  // without answering" would only ever produce a board nobody can tell apart from an unconfigured
+  // one. Dismissing hides it until the next load.
+  const defaultProvisionDismissed = ref(false)
+  function dismissDefaultProvision() {
+    defaultProvisionDismissed.value = true
+  }
+  function resetDefaultProvisionDismissal() {
+    defaultProvisionDismissed.value = false
+  }
+
   function openAiProviderSetup() {
     aiProviderSetupOpen.value = true
   }
@@ -857,6 +900,9 @@ function createAiOnboardingModals() {
     infraSetupSessionDismissed,
     dismissInfraSetupForSession,
     resetInfraSetupDismissals,
+    defaultProvisionDismissed,
+    dismissDefaultProvision,
+    resetDefaultProvisionDismissal,
     openAiProviderSetup,
     closeAiProviderSetup,
     openAiPresetMismatch,

package/app/stores/workspaceSettings.ts

@@ -20,6 +20,11 @@ const DEFAULTS: WorkspaceSettings = {
   reviewFrictionBlockStuckMinutes: null,
   spendCurrency: null,
   spendMonthlyLimit: null,
+  // Null means the operator has never chosen a default test-environment provisioning mechanism,
+  // which is what the setup banner nags about. Defaulting it to a type here would silence that
+  // banner on every board before the snapshot even lands.
+  defaultProvisionType: null,
+  defaultProvisionManifestId: null,
 }
 
 /**

package/app/utils/defaultProvisioning.spec.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest'
+import type { CustomManifestType } from '@cat-factory/contracts'
+import {
+  canSaveDefaultProvisioning,
+  needsDefaultProvisioningChoice,
+  suggestDefaultProvisioning,
+} from './defaultProvisioning'
+
+function customType(
+  manifestId: string,
+  source: CustomManifestType['source'] = 'registered',
+): CustomManifestType {
+  return { manifestId, label: manifestId, source }
+}
+
+describe('needsDefaultProvisioningChoice', () => {
+  it('an unset default still owes a decision', () => {
+    expect(needsDefaultProvisioningChoice({ defaultProvisionType: null })).toBe(true)
+  })
+
+  it('an explicit infraless is a decision, not an absence', () => {
+    // The case that separates "nobody chose" from "we chose no environments" — get this wrong
+    // and a workspace that deliberately runs infraless is nagged forever.
+    expect(needsDefaultProvisioningChoice({ defaultProvisionType: 'infraless' })).toBe(false)
+  })
+
+  it('any recorded type settles it', () => {
+    expect(needsDefaultProvisioningChoice({ defaultProvisionType: 'kubernetes' })).toBe(false)
+  })
+})
+
+describe('suggestDefaultProvisioning', () => {
+  const unset = { defaultProvisionType: null, defaultProvisionManifestId: null }
+
+  it('opens on the recorded choice rather than re-suggesting over it', () => {
+    expect(
+      suggestDefaultProvisioning(
+        { defaultProvisionType: 'kubernetes', defaultProvisionManifestId: null },
+        [customType('acme-preview')],
+      ),
+    ).toEqual({ type: 'kubernetes', manifestId: null })
+  })
+
+  it('round-trips a recorded custom choice with its manifest id', () => {
+    expect(
+      suggestDefaultProvisioning(
+        { defaultProvisionType: 'custom', defaultProvisionManifestId: 'acme-preview' },
+        [customType('acme-preview'), customType('other')],
+      ),
+    ).toEqual({ type: 'custom', manifestId: 'acme-preview' })
+  })
+
+  it('suggests the first registered custom provider when nothing is selected', () => {
+    expect(
+      suggestDefaultProvisioning(unset, [customType('acme-preview'), customType('acme-legacy')]),
+    ).toEqual({ type: 'custom', manifestId: 'acme-preview' })
+  })
+
+  it('prefers a registered provider over a hand-authored workspace type', () => {
+    // A registered type is a deployment-level integration; a workspace row is one someone typed
+    // into the UI. Order in the catalog must not decide which one we recommend.
+    expect(
+      suggestDefaultProvisioning(unset, [
+        customType('typed-by-hand', 'workspace'),
+        customType('acme-preview', 'registered'),
+      ]),
+    ).toEqual({ type: 'custom', manifestId: 'acme-preview' })
+  })
+
+  it('falls back to a workspace-defined type when no provider is registered', () => {
+    expect(suggestDefaultProvisioning(unset, [customType('typed-by-hand', 'workspace')])).toEqual({
+      type: 'custom',
+      manifestId: 'typed-by-hand',
+    })
+  })
+
+  it('suggests nothing when there are no custom providers at all', () => {
+    // Deliberately does NOT guess a built-in: the picker offering `kubernetes` says nothing
+    // about whether this workspace's services actually use it.
+    expect(suggestDefaultProvisioning(unset, [])).toEqual({ type: null, manifestId: null })
+  })
+})
+
+describe('canSaveDefaultProvisioning', () => {
+  it('refuses an empty selection', () => {
+    expect(canSaveDefaultProvisioning({ type: null, manifestId: null })).toBe(false)
+  })
+
+  it('refuses custom with no manifest id, mirroring the server rule', () => {
+    expect(canSaveDefaultProvisioning({ type: 'custom', manifestId: null })).toBe(false)
+  })
+
+  it('accepts custom once a manifest type is named', () => {
+    expect(canSaveDefaultProvisioning({ type: 'custom', manifestId: 'acme-preview' })).toBe(true)
+  })
+
+  it('accepts a built-in type, including infraless', () => {
+    expect(canSaveDefaultProvisioning({ type: 'infraless', manifestId: null })).toBe(true)
+  })
+})

package/app/utils/defaultProvisioning.ts

@@ -0,0 +1,99 @@
+import type { CustomManifestType, ProvisionType, WorkspaceSettings } from '@cat-factory/contracts'
+
+/**
+ * The workspace-level default test-environment provisioning mechanism: what the SPA nags about
+ * when it is unset, and what the config section preselects when the operator first opens it.
+ *
+ * Pure so both consumers — the banner's visibility and the section's initial selection — agree
+ * on the same notion of "nothing chosen yet" without either re-deriving it.
+ */
+
+/**
+ * The query param that deep-links straight to the default-provisioning config section
+ * (`?settings=default-test-env`). Defined here — beside the logic both ends share — so the
+ * banner that BUILDS the URL and the ui store that CONSUMES it can never drift; a mismatch
+ * would produce a link that silently opens nothing.
+ */
+export const DEFAULT_PROVISION_DEEP_LINK_PARAM = 'settings'
+export const DEFAULT_PROVISION_DEEP_LINK_VALUE = 'default-test-env'
+
+/**
+ * The shareable absolute URL for the config screen. Built from the CURRENT location (rather
+ * than a configured base) so it is correct for whatever origin/path this SPA is actually served
+ * from — a deployment mounted under a sub-path included. Returns just the query string when
+ * there is no `window` (SSR is off, but the util stays callable in a unit test).
+ */
+export function defaultProvisioningConfigUrl(location?: {
+  origin: string
+  pathname: string
+}): string {
+  const query = `?${DEFAULT_PROVISION_DEEP_LINK_PARAM}=${DEFAULT_PROVISION_DEEP_LINK_VALUE}`
+  const loc = location ?? (typeof window === 'undefined' ? undefined : window.location)
+  return loc ? `${loc.origin}${loc.pathname}${query}` : query
+}
+
+/** The section's editable selection: a provision type plus, for `custom`, the pinned manifest id. */
+export interface DefaultProvisioningSelection {
+  type: ProvisionType | null
+  manifestId: string | null
+}
+
+/**
+ * Whether the workspace still owes a decision. `null` means the operator has never chosen —
+ * distinct from an explicit `infraless` ("services stand up no environment"), which is a real
+ * choice and silences the prompt. See the contracts block comment on `defaultProvisionType`.
+ */
+export function needsDefaultProvisioningChoice(
+  settings: Pick<WorkspaceSettings, 'defaultProvisionType'>,
+): boolean {
+  return settings.defaultProvisionType == null
+}
+
+/**
+ * The selection the config section opens on.
+ *
+ * A recorded choice always wins — the section is an editor for it, not a recommender that
+ * overrides what the workspace already decided.
+ *
+ * With nothing recorded, a deployment that has REGISTERED custom providers is telling us it
+ * brought its own environment tooling, and that tooling is almost always what its services
+ * should use — so the first one is preselected rather than making the operator discover the
+ * `custom` tab and then pick from a list only they can interpret. `registered` (code-defined,
+ * shipped by the deployment) is preferred over `workspace` (a row somebody typed into the UI):
+ * only the former is evidence of a deliberate platform-level integration. Falling back to the
+ * first workspace-defined type keeps the suggestion useful on a board whose only custom type
+ * was authored by hand.
+ *
+ * With no custom providers at all there is nothing to suggest, so the section opens UNSET and
+ * the operator picks from the built-in types. It deliberately does not guess a built-in: unlike
+ * a registered custom provider, the presence of `kubernetes` in the picker says nothing about
+ * whether this workspace's services use it.
+ *
+ * Nothing here is persisted — this is the form's initial value, and the operator still saves.
+ */
+export function suggestDefaultProvisioning(
+  settings: Pick<WorkspaceSettings, 'defaultProvisionType' | 'defaultProvisionManifestId'>,
+  customTypes: readonly CustomManifestType[],
+): DefaultProvisioningSelection {
+  if (settings.defaultProvisionType != null) {
+    return {
+      type: settings.defaultProvisionType,
+      manifestId: settings.defaultProvisionManifestId,
+    }
+  }
+  const suggested =
+    customTypes.find((t) => t.source === 'registered') ?? customTypes[0] ?? undefined
+  return suggested
+    ? { type: 'custom', manifestId: suggested.manifestId }
+    : { type: null, manifestId: null }
+}
+
+/**
+ * Whether a selection can be saved. Mirrors the server's cross-field rule so the button
+ * disables instead of round-tripping to a 422: `custom` must name the manifest type it uses,
+ * and there is nothing to save until a type is picked.
+ */
+export function canSaveDefaultProvisioning(selection: DefaultProvisioningSelection): boolean {
+  if (selection.type == null) return false
+  return selection.type !== 'custom' || !!selection.manifestId
+}

package/app/utils/interviewGate.spec.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest'
+import { interviewGatePhase } from './interviewGate'
+
+// `interviewGatePhase` is what stops continue/proceed reading as no-ops in BOTH interview windows
+// (initiative planning, document interview): the resume is asynchronous — the HTTP call only wakes
+// the durable driver, so it returns the PRE-resume entity — and these pin that the RUN status is
+// what distinguishes "parked, waiting on you" from "a pass is running", a distinction the entity
+// alone cannot make.
+
+describe('interviewGatePhase', () => {
+  it('is awaiting while the run is parked on the human', () => {
+    expect(interviewGatePhase('awaiting', 'blocked')).toBe('awaiting')
+  })
+
+  it('is working once the resumed run is running again, even though the entity still says awaiting', () => {
+    // The exact regression: continue/proceed leave the entity's status untouched until the pass
+    // finishes, so an entity-only reading renders the same questions and looks like a dead button.
+    expect(interviewGatePhase('awaiting', 'running')).toBe('working')
+  })
+
+  it('is working for the FIRST pass, before any question exists', () => {
+    expect(interviewGatePhase(undefined, 'running')).toBe('working')
+  })
+
+  it('is failed when the run stopped before the interview settled', () => {
+    // Must not stay `working`: a pass that dies would otherwise spin forever.
+    expect(interviewGatePhase('awaiting', 'failed')).toBe('failed')
+    expect(interviewGatePhase(undefined, 'failed')).toBe('failed')
+  })
+
+  it('is converged once the interview settled, whatever the run went on to do', () => {
+    // `converged` outranks `failed`: a later step's failure belongs to that step, not the
+    // interview, and the block's own failure surface reports it.
+    expect(interviewGatePhase('done', 'running')).toBe('converged')
+    expect(interviewGatePhase('done', 'failed')).toBe('converged')
+    expect(interviewGatePhase('done', undefined)).toBe('converged')
+  })
+
+  it('is idle when the interview never ran', () => {
+    expect(interviewGatePhase(undefined, undefined)).toBe('idle')
+  })
+
+  it('degrades to the entity-only reading when the run is not cached', () => {
+    // A window opened before the execution snapshot lands must show the questions, never a spinner.
+    expect(interviewGatePhase('awaiting', undefined)).toBe('awaiting')
+  })
+
+  it('keeps a paused run answerable', () => {
+    expect(interviewGatePhase('awaiting', 'paused')).toBe('awaiting')
+  })
+})

package/app/utils/interviewGate.ts

@@ -0,0 +1,51 @@
+import type { ExecutionInstance } from '~/types/domain'
+
+// The frontend dual of the backend's shared `InterviewGateController` spine. Both interview gates
+// — the initiative-planning interviewer and the document interviewer — park their run on a
+// decision-wait, expose the SAME `awaiting | done` status on their entity, and resume the same
+// way, so how their windows read "what is happening right now" is shared vocabulary rather than
+// two copies. See `docs/initiatives/clarification-items.md`.
+
+/**
+ * What an interview gate is doing right now, from the human's point of view. Drives the interview
+ * window's body AND (for the initiative) the card/inspector affordances, so the surfaces can't
+ * disagree about whether there is anything to answer.
+ *
+ *  - `idle` — the interview has not run yet (nothing to answer, nothing in flight).
+ *  - `working` — an interviewer pass is running; the human waits.
+ *  - `awaiting` — the run is parked on the human's answers.
+ *  - `converged` — the interview settled; the run moved on.
+ *  - `failed` — the run stopped before the interview settled.
+ */
+export type InterviewGatePhase = 'idle' | 'working' | 'awaiting' | 'converged' | 'failed'
+
+/**
+ * Resolve the phase from the interview entity's status AND its run's status.
+ *
+ * The RUN status is load-bearing, not redundant. Continue/proceed are ASYNC by design: the HTTP
+ * call only records the intent on the parked step and wakes the durable driver, which then runs
+ * the (slow) interviewer LLM — so the response carries the PRE-resume entity, with the same
+ * questions and the same `awaiting` status. Keyed on the entity alone a window is therefore
+ * byte-identical before and after the click, which is indistinguishable from the button doing
+ * nothing for however long the pass takes. A resumed run flips `blocked` → `running` and emits,
+ * so `running` while the interview is unsettled is exactly "a pass is in flight".
+ *
+ * Deriving this from the run rather than a local in-flight flag also survives a reload and cannot
+ * wedge: a pass that FAILS takes the run to `failed`, so the window drops out of `working` and
+ * says so instead of spinning forever. An unknown run (no instance cached yet) degrades to the
+ * entity-only reading, never to a spinner.
+ *
+ * `converged` wins over `failed` on purpose: once the interview settled, a later failure belongs
+ * to the step that failed (the analyst/planner, the writer), and the block's own failure surface
+ * reports it — the interview window claiming the interview broke would be wrong.
+ */
+export function interviewGatePhase(
+  status: 'awaiting' | 'done' | undefined,
+  runStatus: ExecutionInstance['status'] | undefined,
+): InterviewGatePhase {
+  if (status === 'done') return 'converged'
+  if (runStatus === 'failed') return 'failed'
+  if (runStatus === 'running') return 'working'
+  if (status === 'awaiting') return 'awaiting'
+  return 'idle'
+}