@cat-factory/app 0.172.0 → 0.173.0

package/app/components/fragments/GitHubDocUrlImport.vue

@@ -0,0 +1,83 @@
+<script setup lang="ts">
+// Paste a GitHub/GitLab file or directory URL to start a document-fragment link without
+// the repo typeahead: the URL is parsed client-side (owner/repo + path + file-vs-dir) and
+// the repo resolved through the SHARED available-repos list by its exact slug — the
+// backend point-reads an exact `owner/name`, so this never depends on the provider's
+// name search (where a pasted URL matches nothing). Emits the resolved repo + location;
+// the manager stages a file or opens the tree browser at the directory for bulk picking.
+import { parseRepoWebUrl } from '@cat-factory/contracts'
+import type { GitHubAvailableRepo } from '~/types/domain'
+
+const emit = defineEmits<{
+  resolved: [{ repo: GitHubAvailableRepo; path: string; kind: 'file' | 'dir' }]
+}>()
+
+const { t } = useI18n()
+const github = useGitHubStore()
+
+const url = ref('')
+const resolving = ref(false)
+const error = ref<string | null>(null)
+
+async function importUrl() {
+  const input = url.value.trim()
+  if (!input || resolving.value) return
+  const parsed = parseRepoWebUrl(input)
+  if (!parsed) {
+    error.value = t('fragments.documents.urlImport.invalid')
+    return
+  }
+  resolving.value = true
+  error.value = null
+  const slug = `${parsed.owner}/${parsed.repo}`
+  try {
+    // Load into the SHARED picker list (not the side-effect-free search) so the repo
+    // select alongside this field can render the resolved selection's label.
+    await github.loadAvailableRepos(slug)
+    const repo = github.availableRepos.find(
+      (r) =>
+        r.owner.toLowerCase() === parsed.owner.toLowerCase() &&
+        r.name.toLowerCase() === parsed.repo.toLowerCase(),
+    )
+    if (!repo) {
+      error.value = t('fragments.documents.urlImport.notFound', { slug })
+      return
+    }
+    emit('resolved', { repo, path: parsed.path, kind: parsed.kind })
+    url.value = ''
+  } catch (e) {
+    error.value = e instanceof Error ? e.message : String(e)
+  } finally {
+    resolving.value = false
+  }
+}
+</script>
+
+<template>
+  <div class="flex flex-col gap-1">
+    <div class="flex gap-2">
+      <UInput
+        v-model="url"
+        icon="i-lucide-link-2"
+        :placeholder="t('fragments.documents.urlImport.placeholder')"
+        class="flex-1"
+        data-testid="fragment-url-import-input"
+        @keyup.enter="importUrl"
+      />
+      <UButton
+        size="sm"
+        variant="outline"
+        icon="i-lucide-folder-search"
+        :loading="resolving"
+        :disabled="!url.trim()"
+        data-testid="fragment-url-import-button"
+        @click="importUrl"
+      >
+        {{ t('fragments.documents.urlImport.action') }}
+      </UButton>
+    </div>
+    <p v-if="error" class="text-xs text-red-400" data-testid="fragment-url-import-error">
+      {{ error }}
+    </p>
+  </div>
+</template>

package/app/components/github/RepoTreeBrowser.vue

@@ -62,6 +62,22 @@ const isEmpty = computed(() =>
   props.mode === 'dir' ? dirEntries.value.length === 0 : treeEntries.value.length === 0,
 )
 
+// file + multiple: the bulk-pick header. "Select all" checks every file of the CURRENT
+// listing that isn't already picked or added elsewhere; unchecking clears only this
+// listing's picks (never the cart entries staged from other folders).
+const selectableFiles = computed(() =>
+  props.mode === 'file' && props.multiple ? fileEntries.value.filter((e) => !isAdded(e.path)) : [],
+)
+const allSelected = computed(
+  () => selectableFiles.value.length > 0 && selectableFiles.value.every((e) => isPicked(e.path)),
+)
+function toggleAllFiles() {
+  const check = !allSelected.value
+  for (const entry of selectableFiles.value) {
+    if (isPicked(entry.path) !== check) emit('toggle', entry.path)
+  }
+}
+
 const breadcrumbs = computed(() => {
   const segments = currentPath.value ? currentPath.value.split('/') : []
   let acc = ''
@@ -175,21 +191,60 @@ watch(
           </UButton>
         </li>
         <template v-if="mode === 'file'">
+          <!-- multiple: a bulk header so a whole directory of documents is one click -->
           <li
-            v-for="entry in fileEntries"
-            :key="entry.path"
-            class="flex items-center justify-between gap-2 px-3 py-1.5"
+            v-if="selectableFiles.length > 1"
+            class="flex items-center gap-2 bg-slate-900/60 px-3 py-1.5"
           >
+            <UCheckbox
+              :model-value="allSelected"
+              :aria-label="
+                t(
+                  'github.repoTree.selectAllFiles',
+                  { count: selectableFiles.length },
+                  selectableFiles.length,
+                )
+              "
+              data-testid="repo-tree-select-all"
+              @update:model-value="toggleAllFiles"
+            />
             <button
               type="button"
-              class="flex items-center gap-2 truncate text-sm hover:text-primary-400"
-              :class="isPicked(entry.path) ? 'text-primary-400' : 'text-slate-300'"
-              :disabled="isAdded(entry.path)"
-              @click="pick(entry.path)"
+              class="text-xs text-slate-400 hover:text-primary-400"
+              @click="toggleAllFiles"
             >
-              <UIcon name="i-lucide-file" class="h-4 w-4 shrink-0 text-slate-400" />
-              <span class="truncate">{{ entry.name }}</span>
+              {{
+                t(
+                  'github.repoTree.selectAllFiles',
+                  { count: selectableFiles.length },
+                  selectableFiles.length,
+                )
+              }}
             </button>
+          </li>
+          <li
+            v-for="entry in fileEntries"
+            :key="entry.path"
+            class="flex items-center justify-between gap-2 px-3 py-1.5"
+          >
+            <div class="flex min-w-0 items-center gap-2">
+              <UCheckbox
+                v-if="multiple && !isAdded(entry.path)"
+                :model-value="isPicked(entry.path)"
+                :aria-label="entry.name"
+                @update:model-value="pick(entry.path)"
+              />
+              <button
+                type="button"
+                class="flex items-center gap-2 truncate text-sm hover:text-primary-400"
+                :class="isPicked(entry.path) ? 'text-primary-400' : 'text-slate-300'"
+                :disabled="isAdded(entry.path)"
+                @click="pick(entry.path)"
+              >
+                <UIcon name="i-lucide-file" class="h-4 w-4 shrink-0 text-slate-400" />
+                <span class="truncate">{{ entry.name }}</span>
+              </button>
+            </div>
             <span
               v-if="isAdded(entry.path)"
               class="flex shrink-0 items-center gap-1 text-xs text-slate-500"
@@ -198,7 +253,7 @@ watch(
               {{ t('github.repoTree.added') }}
             </span>
             <UIcon
-              v-else-if="isPicked(entry.path)"
+              v-else-if="!multiple && isPicked(entry.path)"
               name="i-lucide-check"
               class="h-4 w-4 shrink-0 text-primary-400"
             />

package/app/components/initiative/InitiativePlanningWindow.vue

@@ -1,19 +1,31 @@
 <script setup lang="ts">
 // The interactive-planning Q&A window (slice 2) — the dedicated view of the initiative
 // INTERVIEWER gate. While the planning run is parked, the interviewer's clarifying questions
-// (pending `qa` entries with an empty answer) are shown here; the human answers them, then
-// either CONTINUES (the interviewer re-runs and may ask follow-ups) or PROCEEDS (skip
-// remaining questions — the interviewer converges and the run advances to the analyst/planner).
+// (pending `qa` entries with an empty answer) are shown here; the human answers them, then either
+// SUBMITS them (the `continue` action: the interviewer re-runs and may ask follow-ups) or plans
+// now (the `proceed` action: skip the remaining questions — the interviewer converges and the run
+// advances to the analyst/planner). The labels say submit/plan-now rather than continue/proceed
+// because the latter pair both read as "go forward" and were indistinguishable in use.
 // Opened via the universal result-view host: from the inspector / card
 // (`ui.openInitiativePlanning`) or as the interviewer step's result view. Live `initiative`
 // stream events patch the store, so an open window follows the interview as it progresses.
+//
+// CONTINUE/PROCEED ARE ASYNC. They only record the intent on the parked step and wake the durable
+// driver; the interviewer LLM then runs for as long as it takes, and the response carries the
+// PRE-resume entity. So the window must not key its body on the entity alone — that renders
+// identically before and after the click, which reads as the button having done nothing. The
+// phase below folds the planning RUN's status in, so the wait is visible and a failed pass says
+// so instead of leaving the human staring at questions they already submitted.
 import { computed, reactive, watch } from 'vue'
 import ClarificationItem from '~/components/common/ClarificationItem.vue'
+import InterviewGateNotice from '~/components/common/InterviewGateNotice.vue'
 import { INITIATIVE_STATUS_LABEL_KEYS } from '~/utils/initiative'
+import { interviewGatePhase } from '~/utils/interviewGate'
 import ResultWindowShell from '~/components/panels/ResultWindowShell.vue'
 
 const board = useBoardStore()
 const initiatives = useInitiativesStore()
+const execution = useExecutionStore()
 const { t } = useI18n()
 
 const { open, blockId, close } = useResultView('initiative-planning', {
@@ -22,6 +34,7 @@ const { open, blockId, close } = useResultView('initiative-planning', {
 
 const block = computed(() => (blockId.value ? board.getBlock(blockId.value) : undefined))
 const initiative = computed(() => (blockId.value ? initiatives.forBlock(blockId.value) : null))
+const run = computed(() => (blockId.value ? execution.getByBlock(blockId.value) : undefined))
 
 /** Every interview exchange, with a stable key for the list + draft map. */
 const questions = computed(() =>
@@ -31,8 +44,6 @@ const questions = computed(() =>
 const pending = computed(() =>
   questions.value.filter((q) => q.status !== 'dismissed' && !(q.answer ?? '').trim()),
 )
-/** The interview converged (or never started with a model): nothing left to answer. */
-const converged = computed(() => initiative.value?.interview?.status === 'done')
 
 // Per-question answer drafts, seeded from the entity and refreshed as new rounds arrive
 // without clobbering an answer the human is mid-edit on.
@@ -48,11 +59,26 @@ watch(
 )
 
 const resuming = computed(() => initiatives.resuming)
+
 /**
- * Continue is meaningful once every pending question has a drafted answer. A dismissed question
- * doesn't count (it was set aside), so an all-dismissed round is trivially "answered".
+ * The live phase (see `interviewGatePhase`). `resuming` folds in the request itself so the
+ * body swaps to the waiting state on the click rather than a beat later when the run's `running`
+ * event lands — and if the request fails, `resuming` clears and the phase falls back to whatever
+ * the run actually says, so the questions come back rather than the window sticking on a spinner.
  */
-const allAnswered = computed(() => pending.value.every((q) => drafts[q.key]?.trim()))
+const phase = computed(() =>
+  resuming.value
+    ? 'working'
+    : interviewGatePhase(initiative.value?.interview?.status, run.value?.status),
+)
+
+/**
+ * Questions still missing a drafted answer. Continue is only meaningful once this is empty — but a
+ * disabled button with no stated reason is itself a "nothing happened", so the count is rendered.
+ * A dismissed question doesn't count (it was set aside), so an all-dismissed round is trivially
+ * answered.
+ */
+const unanswered = computed(() => pending.value.filter((q) => !drafts[q.key]?.trim()).length)
 
 /**
  * Persist one answer if its draft differs from what's recorded. A `dismissed` question is skipped:
@@ -135,9 +161,38 @@ const onProceed = () => flushThen((id) => initiatives.proceedPlanning(id))
           {{ t('initiative.planning.intro') }}
         </p>
 
+        <!-- A pass is running: the human is waiting on the planner. Without this the window is
+             byte-identical to the parked state and the submit reads as a no-op. -->
+        <InterviewGateNotice
+          v-if="phase === 'working'"
+          variant="working"
+          :title="t('initiative.planning.working')"
+          :hint="t('initiative.planning.workingHint')"
+          testid="initiative-planning-working"
+        />
+
+        <!-- The planning run stopped before the interview settled — a dead end otherwise. -->
+        <InterviewGateNotice
+          v-else-if="phase === 'failed'"
+          variant="failed"
+          :title="t('initiative.planning.failed')"
+          :hint="t('initiative.planning.failedHint')"
+          testid="initiative-planning-failed"
+        />
+
+        <!-- Planning was never started, so there is nothing to answer YET (distinct from
+             converged, which means the planner already has what it needs). -->
+        <div
+          v-else-if="phase === 'idle' && questions.length === 0"
+          class="rounded-lg border border-slate-800 bg-slate-950/40 p-4 text-center text-[13px] text-slate-400"
+          data-testid="initiative-planning-idle"
+        >
+          {{ t('initiative.planning.idle') }}
+        </div>
+
         <!-- Converged / no pending questions -->
         <div
-          v-if="converged || questions.length === 0"
+          v-else-if="phase === 'converged' || questions.length === 0"
           class="rounded-lg border border-slate-800 bg-slate-950/40 p-4 text-center text-[13px] text-slate-400"
           data-testid="initiative-planning-converged"
         >
@@ -166,13 +221,21 @@ const onProceed = () => flushThen((id) => initiatives.proceedPlanning(id))
       </template>
     </div>
 
-    <!-- Action rail -->
+    <!-- Action rail. Only while the run is actually parked on the human: mid-pass these would
+         re-submit a question set already in flight, and the resume is a no-op once it isn't. -->
     <footer
-      v-if="initiative && !converged && questions.length > 0"
+      v-if="initiative && phase === 'awaiting' && questions.length > 0"
       class="flex items-center justify-between gap-3 border-t border-slate-800 px-5 py-3"
     >
       <p class="text-[11px] text-slate-500">
-        {{ t('initiative.planning.hint') }}
+        <span
+          v-if="unanswered > 0"
+          class="text-amber-400/90"
+          data-testid="initiative-planning-unanswered"
+        >
+          {{ t('initiative.planning.unanswered', { count: unanswered }) }}
+        </span>
+        <span v-else>{{ t('initiative.planning.hint') }}</span>
       </p>
       <div class="flex items-center gap-2">
         <UButton
@@ -180,6 +243,7 @@ const onProceed = () => flushThen((id) => initiatives.proceedPlanning(id))
           variant="ghost"
           size="sm"
           :loading="resuming"
+          :title="t('initiative.planning.proceedTitle')"
           data-testid="initiative-planning-proceed"
           @click="onProceed"
         >
@@ -189,7 +253,12 @@ const onProceed = () => flushThen((id) => initiatives.proceedPlanning(id))
           color="primary"
           size="sm"
           :loading="resuming"
-          :disabled="!allAnswered"
+          :disabled="unanswered > 0"
+          :title="
+            unanswered > 0
+              ? t('initiative.planning.unanswered', { count: unanswered })
+              : t('initiative.planning.continueTitle')
+          "
           data-testid="initiative-planning-continue"
           @click="onContinue"
         >

package/app/components/panels/inspector/InitiativeInspector.vue

@@ -23,6 +23,7 @@ const {
   planningPipeline,
   running,
   awaitingAnswers,
+  interviewing,
   starting,
   runPlanning,
   openPlanning,
@@ -66,6 +67,20 @@ function control(action: 'pause' | 'resume' | 'cancel') {
       >
         {{ t('initiative.inspector.answerPlanning') }}
       </UButton>
+      <!-- Mid-pass there is nothing to answer, but the window must stay reachable — it is where
+           the "planner is working" state is shown. -->
+      <UButton
+        v-else-if="interviewing"
+        data-testid="initiative-planning-in-progress"
+        color="neutral"
+        variant="soft"
+        size="sm"
+        icon="i-lucide-loader-circle"
+        :ui="{ leadingIcon: 'animate-spin' }"
+        @click="openPlanning"
+      >
+        {{ t('initiative.inspector.planningInProgress') }}
+      </UButton>
       <UButton
         data-testid="initiative-run-planning"
         color="primary"

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