@cat-factory/app 0.182.0 → 0.183.0

package/README.md

@@ -177,9 +177,13 @@ Two placements are load-bearing enough to state, because putting a new one in th
 wrong place is invisible until a user cannot find it:
 
 - **The sidebar section is a claim about what the destination IS.** `models` is the
-  engines, `integrations` the optional systems, `infrastructure` where agent
-  containers and test environments run, `configuration` workspace/account settings.
-  `nav-contributions.spec.ts` pins the section order and each section's membership.
+  model layer — the engines, the per-agent model choice, and the surfaces that
+  evaluate a prompt+agent+model combination (Sandbox, Kaizen); `integrations` the
+  optional EXTERNAL systems; `infrastructure` where agent containers and test
+  environments run; `configuration` workspace/account settings. A surface that
+  connects to nothing does not belong in `integrations` however configuration-shaped
+  it feels. `nav-contributions.spec.ts` pins the section order and each section's
+  membership.
 - **A flow that edits ONE entity's config is a section of the window that owns that
   config, not a sibling nav entry.** The guided Docker Compose environment setup
   (`ComposeEnvironmentSetupSection.vue` → `EnvironmentSetupWizard.vue`) lives inside
@@ -188,6 +192,15 @@ wrong place is invisible until a user cannot find it:
   It also carries a full "how it works / when you need this / when you can skip it"
   explanation there rather than a one-line hint, since the decision to run it has to
   be made before opening a five-minute wizard.
+- **"It talks to an external service" is not what puts a surface in `integrations`.**
+  Private package registries connect to npmjs.com and GitHub Packages and still belong
+  in Infrastructure, because the question they answer is _what may a container install
+  from_ — a property of where agents RUN, which is what the Infrastructure window is
+  for. `integrations` is for a system the WORKSPACE links in and would still be a
+  coherent product without. Ask which question the destination answers, not whether a
+  credential leaves the building. A surface moved between sections must also move its
+  entry point: leaving a hub row behind as a shortcut splits the answer across two
+  places, so the row goes and the window's tab becomes the single route in.
 
 ## Develop & test
 

package/app/components/board/nodes/BlockNode.vue

@@ -83,12 +83,22 @@ const selected = computed(() => ui.selectedBlockId === props.id)
 // kept (gated off) so the prior behaviour is one edit away if we want chips back.
 const showExpanded = computed(() => true)
 
-// Surface a pending decision from this frame OR any of its tasks (O(tasks) map
+// Every child whose parked run the frame badge speaks for: its tasks AND its initiative
+// blocks. An initiative is a frame child like a module and runs an ordinary pipeline (its
+// planner parks on a real approval gate), so leaving it out made a whole class of parked run
+// invisible at frame level — the badge read "nothing needs you" while a plan sat waiting.
+const attentionIds = computed(() => {
+  const ids = new Set(taskIds.value)
+  for (const i of initiativeBlocks.value) ids.add(i.id)
+  return ids
+})
+
+// Surface a pending decision from this frame OR any of its children (O(children) map
 // lookups, not a scan of every open decision per frame).
 const blockDecisions = computed(() => {
   const byBlock = execution.decisionsByBlock
   const out = [...(byBlock.get(props.id) ?? [])]
-  for (const id of taskIds.value) {
+  for (const id of attentionIds.value) {
     const list = byBlock.get(id)
     if (list) out.push(...list)
   }
@@ -100,14 +110,14 @@ function openFirstDecision() {
   if (d) ui.openDecision(d.instanceId, d.decision.id)
 }
 
-// Surface a pending approval gate from this frame OR any of its tasks — but NOT an
+// Surface a pending approval gate from this frame OR any of its children — but NOT an
 // iterative reviewer gate (requirements-review / clarity-review) that's mid-cycle
 // (incorporating / re-reviewing in the driver), which is background work needing no human,
 // so it stays off the frame's "Approval" badge.
 const blockApprovals = computed(() => {
   const byBlock = execution.approvalsByBlock
   const candidates = [...(byBlock.get(props.id) ?? [])]
-  for (const id of taskIds.value) {
+  for (const id of attentionIds.value) {
     const list = byBlock.get(id)
     if (list) candidates.push(...list)
   }

package/app/components/board/nodes/InitiativeCard.vue

@@ -5,12 +5,18 @@
 // initiative's equivalent "Run planning" (and, while parked mid-interview, "Answer
 // planning questions") lives right here on the board — the same actions the
 // inspector offers — so starting an initiative isn't hidden behind selecting it.
+// It likewise mirrors a task card's `attention` affordance: a planning run parked
+// on the plan-approval gate (or on an agent-raised decision) offers the button that
+// opens the window resolving it, instead of leaving the card on a spinning "Run
+// planning" whose only route in was the inspector's execution panel.
 // The tracker button opens the dedicated window directly. Draggable within its
 // frame like a task card.
 import type { InitiativeStatus } from '~/types/domain'
 import { useBlockDrag } from '~/composables/useBlockDrag'
 import { useInitiativePlanning } from '~/composables/useInitiativePlanning'
 import {
+  INITIATIVE_ATTENTION_ICONS,
+  INITIATIVE_ATTENTION_LABEL_KEYS,
   INITIATIVE_STATUS_CHIPS,
   INITIATIVE_STATUS_LABEL_KEYS,
   initiativeProgress,
@@ -40,6 +46,7 @@ const {
   running,
   awaitingAnswers,
   interviewing,
+  attention,
   starting,
   runPlanning,
   openPlanning,
@@ -79,7 +86,10 @@ function onHandle(e: PointerEvent) {
       data-testid="initiative-card"
       :data-status="status"
       class="cursor-pointer rounded-b-lg border border-indigo-800/60 bg-indigo-950/40 p-3 transition hover:border-indigo-600"
-      :class="[selected ? 'ring-2 ring-indigo-400/60' : '', awaitingAnswers ? 'board-pulse' : '']"
+      :class="[
+        selected ? 'ring-2 ring-indigo-400/60' : '',
+        awaitingAnswers || attention ? 'board-pulse' : '',
+      ]"
       @click.stop="select"
     >
       <div class="flex items-start justify-between gap-2">
@@ -106,8 +116,23 @@ function onHandle(e: PointerEvent) {
         </div>
       </div>
       <div class="nodrag mt-2 flex flex-wrap items-center gap-1">
+        <!-- Parked for a human: the drafted plan awaits approval, or an agent raised a
+             decision. Opens the window that can resolve the park (never the generic panel,
+             which the server refuses for a park a dedicated window owns). -->
         <UButton
-          v-if="awaitingAnswers"
+          v-if="attention"
+          data-testid="initiative-card-review"
+          :data-attention="attention.kind"
+          size="xs"
+          variant="solid"
+          color="warning"
+          :icon="INITIATIVE_ATTENTION_ICONS[attention.kind]"
+          @click.stop="attention.open()"
+        >
+          {{ t(INITIATIVE_ATTENTION_LABEL_KEYS[attention.kind]) }}
+        </UButton>
+        <UButton
+          v-else-if="awaitingAnswers"
           data-testid="initiative-card-answer-planning"
           size="xs"
           variant="solid"

package/app/components/initiative/InitiativeTrackerWindow.vue

@@ -1,14 +1,20 @@
 <script setup lang="ts">
-// The initiative tracker window — the dedicated read-only view of an initiative's
-// plan/tracker entity: goal + constraints, the phases with their per-item status +
-// PR links, the execution policy, and the decisions / deviations / follow-ups /
-// caveats logs. Renders the DB entity (the source of truth) — never the in-repo
-// mirror, which may not exist (GitHub-unwired workspaces). Opened via the universal
-// result-view host: from the board card / inspector (`ui.openInitiativeTracker`) or
-// as the planner step's result view. Live `initiative` stream events patch the
-// store, so an open window follows the plan as it is ingested and later executed.
-import { computed, reactive, ref } from 'vue'
+// The initiative tracker window — the dedicated view of an initiative's plan/tracker
+// entity: goal + constraints, the phases with their per-item status + PR links, the
+// execution policy, and the decisions / deviations / follow-ups / caveats logs.
+// Renders the DB entity (the source of truth) — never the in-repo mirror, which may
+// not exist (GitHub-unwired workspaces). Opened via the universal result-view host:
+// from the board card / inspector (`ui.openInitiativeTracker`) or as the planner
+// step's result view. Live `initiative` stream events patch the store, so an open
+// window follows the plan as it is ingested and later executed.
+//
+// It also OWNS the planner's plan-approval gate: this window is where the planner
+// step's park routes (its archetype declares this result view), so the approve /
+// request-changes rail has to live here or the gate has no resolving surface at all —
+// which is exactly how an approved-only-over-REST plan gate shipped.
+import { computed, reactive, ref, watch } from 'vue'
 import type { InitiativeFollowUp, InitiativeItem } from '~/types/domain'
+import { useInitiativePlanning } from '~/composables/useInitiativePlanning'
 import {
   INITIATIVE_FOLLOWUP_STATUS_CHIPS,
   INITIATIVE_FOLLOWUP_STATUS_LABEL_KEYS,
@@ -23,6 +29,8 @@ import StepRunMeta from '~/components/panels/StepRunMeta.vue'
 
 const board = useBoardStore()
 const initiatives = useInitiativesStore()
+const execution = useExecutionStore()
+const access = useWorkspaceAccess()
 const { t } = useI18n()
 const toast = useToast()
 
@@ -92,6 +100,58 @@ async function checkpointControl(action: 'resume' | 'cancel') {
   }
 }
 
+// ---- Plan review: the planner step's human gate, resolved right here -----------------------
+// Derived from the BLOCK (via the shared planning composable), not from this window's own
+// `stepIndex`: the card / inspector open the tracker with no step, and that is the entry point a
+// human parked on the gate actually uses. So the rail appears on every route into the window.
+const { planApproval } = useInitiativePlanning(() => blockId.value ?? '')
+
+/** Draft feedback for "request changes" (the planner re-runs with it), and the rail's in-flight
+ *  state. Reset when a different initiative opens so a draft can't follow the window. */
+const planFeedback = ref('')
+const requestingChanges = ref(false)
+const resolvingPlan = ref(false)
+watch(blockId, () => {
+  planFeedback.value = ''
+  requestingChanges.value = false
+})
+
+const canRequestChanges = computed(() => planFeedback.value.trim().length > 0)
+
+/**
+ * Accept the drafted plan: the run advances to the committer, which persists the initiative and
+ * arms the execution loop. The window deliberately stays OPEN — the rail disappears with the
+ * approval (live), and the tracker is where the plan then starts executing.
+ */
+async function approvePlan() {
+  const parked = planApproval.value
+  if (!parked || resolvingPlan.value) return
+  resolvingPlan.value = true
+  try {
+    await execution.approveStep(parked.instanceId, parked.approval.id)
+  } finally {
+    resolvingPlan.value = false
+  }
+}
+
+/** Send the plan back to the planner with what to change; it re-plans and parks again. */
+async function submitPlanChanges() {
+  const parked = planApproval.value
+  if (!parked || resolvingPlan.value || !canRequestChanges.value) return
+  resolvingPlan.value = true
+  try {
+    const ok = await execution.requestStepChanges(parked.instanceId, parked.approval.id, {
+      feedback: planFeedback.value.trim(),
+    })
+    if (ok) {
+      planFeedback.value = ''
+      requestingChanges.value = false
+    }
+  } finally {
+    resolvingPlan.value = false
+  }
+}
+
 const policyRules = computed(() => initiative.value?.policy?.rules ?? [])
 function ruleAxes(rule: { minComplexity?: number; minRisk?: number; minImpact?: number }): string {
   const axes = [
@@ -234,6 +294,86 @@ async function savePolicy() {
         </div>
 
         <template v-else>
+          <!-- The planner's human gate: the plan below is drafted but NOT yet committed. This
+               is the only surface that can resolve it (the generic approval panel is never
+               reached — the planner's archetype routes its park to this window), so approve /
+               request changes live here, beside the plan they judge. -->
+          <section
+            v-if="planApproval"
+            class="mb-4 rounded-lg border border-amber-500/40 bg-amber-500/10 p-3.5"
+            data-testid="initiative-plan-review"
+          >
+            <div class="flex items-start gap-2.5">
+              <UIcon
+                name="i-lucide-clipboard-check"
+                class="mt-0.5 h-4 w-4 shrink-0 text-amber-300"
+              />
+              <div class="min-w-0 flex-1">
+                <h3 class="text-[13px] font-semibold text-amber-200">
+                  {{ t('initiative.planReview.title') }}
+                </h3>
+                <p class="mt-0.5 text-[12px] leading-relaxed text-amber-100/80">
+                  {{ t('initiative.planReview.body') }}
+                </p>
+                <div v-if="!requestingChanges" class="mt-2.5 flex flex-wrap gap-2">
+                  <button
+                    class="rounded bg-indigo-600 px-2.5 py-1 text-[11px] font-medium text-white hover:bg-indigo-500 disabled:opacity-50"
+                    :disabled="resolvingPlan || !access.canExecuteRuns.value"
+                    :title="access.canExecuteRuns.value ? undefined : t('access.noRunExecute')"
+                    data-testid="initiative-plan-approve"
+                    @click="approvePlan"
+                  >
+                    {{ t('initiative.planReview.approve') }}
+                  </button>
+                  <button
+                    class="rounded border border-amber-400/50 px-2.5 py-1 text-[11px] font-medium text-amber-200 hover:bg-amber-500/10 disabled:opacity-50"
+                    :disabled="resolvingPlan || !access.canExecuteRuns.value"
+                    :title="access.canExecuteRuns.value ? undefined : t('access.noRunExecute')"
+                    data-testid="initiative-plan-request-changes"
+                    @click="requestingChanges = true"
+                  >
+                    {{ t('initiative.planReview.requestChanges') }}
+                  </button>
+                </div>
+                <!-- Request-changes composer: the feedback is what the planner re-plans FROM,
+                     so it is required — an empty send would re-run the planner with nothing
+                     to act on and park again on the same plan. -->
+                <div v-else class="mt-2.5">
+                  <UTextarea
+                    v-model="planFeedback"
+                    :rows="3"
+                    autoresize
+                    size="sm"
+                    class="w-full"
+                    data-testid="initiative-plan-feedback"
+                    :placeholder="t('initiative.planReview.feedbackPlaceholder')"
+                  />
+                  <div class="mt-2 flex flex-wrap gap-2">
+                    <button
+                      class="rounded bg-amber-500 px-2.5 py-1 text-[11px] font-medium text-slate-950 hover:bg-amber-400 disabled:opacity-50"
+                      :disabled="
+                        resolvingPlan || !canRequestChanges || !access.canExecuteRuns.value
+                      "
+                      :title="access.canExecuteRuns.value ? undefined : t('access.noRunExecute')"
+                      data-testid="initiative-plan-send-back"
+                      @click="submitPlanChanges"
+                    >
+                      {{ t('initiative.planReview.sendBack') }}
+                    </button>
+                    <button
+                      class="rounded border border-slate-600 px-2.5 py-1 text-[11px] font-medium text-slate-300 hover:bg-slate-800 disabled:opacity-50"
+                      :disabled="resolvingPlan"
+                      data-testid="initiative-plan-cancel-changes"
+                      @click="requestingChanges = false"
+                    >
+                      {{ t('common.cancel') }}
+                    </button>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </section>
+
           <!-- Paused at a phase checkpoint (D2): a completed checkpoint phase is awaiting
                    review before the next phase spawns. Read the phase's artifacts/PRs below,
                    then resume (continue) or cancel (stop) the initiative right here. -->

package/app/components/layout/IntegrationsHub.vue

@@ -30,7 +30,6 @@ const documents = useDocumentsStore()
 const tasks = useTasksStore()
 const tracker = useTrackerStore()
 const releaseHealth = useReleaseHealthStore()
-const packageRegistries = usePackageRegistriesStore()
 const publicApiKeys = usePublicApiKeysStore()
 const userSecrets = useUserSecretsStore()
 const uiMode = useUiModeStore()
@@ -60,7 +59,6 @@ watch(
     if (isOpen) {
       query.value = ''
       void releaseHealth.ensureLoaded().catch(() => {})
-      void packageRegistries.ensureLoaded().catch(() => {})
       void publicApiKeys.ensureLoaded().catch(() => {})
       void userSecrets.load().catch(() => {})
     }
@@ -271,22 +269,10 @@ const groups = computed<IntegrationGroup[]>(() => {
     })
   }
 
-  // --- Development (private package registries + API access tokens) -----------
-  // Each row is gated like observability: hidden until a probe confirms its module is
-  // wired (`available === true`), so an unconfigured backend doesn't show a dead row.
+  // --- Development (API access tokens) ---------------------------------------
+  // Gated like observability: hidden until a probe confirms its module is wired
+  // (`available === true`), so an unconfigured backend doesn't show a dead row.
   const development: IntegrationItem[] = []
-  if (packageRegistries.available) {
-    const hasEntries = packageRegistries.entries.length > 0
-    development.push({
-      key: 'package-registries',
-      icon: 'i-lucide-package',
-      label: t('layout.integrationsHub.items.packageRegistries.label'),
-      description: t('layout.integrationsHub.items.packageRegistries.description'),
-      status: hasEntries ? t('layout.integrationsHub.status.connected') : undefined,
-      connected: hasEntries,
-      onClick: () => go(ui.openPackageRegistries),
-    })
-  }
   if (publicApiKeys.available) {
     const hasKeys = publicApiKeys.keys.length > 0
     development.push({
@@ -303,8 +289,9 @@ const groups = computed<IntegrationGroup[]>(() => {
     out.push({ title: t('layout.integrationsHub.groups.development'), items: development })
 
   // NOTE: Infrastructure (agent-container execution + Tester environments + the local-mode
-  // warm pool/checkout) is no longer listed here — it moved to its OWN top-level navbar menu
-  // (SideBar → "Infrastructure" → the tabbed Infrastructure window). See `ui.openInfrastructure`.
+  // warm pool/checkout + the private package registries a checkout installs from) is no longer
+  // listed here — it moved to its OWN top-level navbar menu (SideBar → "Infrastructure" → the
+  // tabbed Infrastructure window). See `ui.openInfrastructure`.
 
   // --- Personal (only you) — fallback when there is no UserMenu to host "My setup" -------
   // Per-user connections normally live in the My-setup hub; with auth disabled they fold in

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

@@ -6,7 +6,12 @@
 // with slice 4.
 import type { Block, InitiativeStatus } from '~/types/domain'
 import { useInitiativePlanning } from '~/composables/useInitiativePlanning'
-import { INITIATIVE_STATUS_LABEL_KEYS, initiativeProgress } from '~/utils/initiative'
+import {
+  INITIATIVE_ATTENTION_ICONS,
+  INITIATIVE_ATTENTION_LABEL_KEYS,
+  INITIATIVE_STATUS_LABEL_KEYS,
+  initiativeProgress,
+} from '~/utils/initiative'
 
 const props = defineProps<{ block: Block }>()
 
@@ -24,6 +29,7 @@ const {
   running,
   awaitingAnswers,
   interviewing,
+  attention,
   starting,
   runPlanning,
   openPlanning,
@@ -56,8 +62,23 @@ function control(action: 'pause' | 'resume' | 'cancel') {
     </p>
 
     <div class="flex flex-wrap items-center gap-2">
+      <!-- Parked for a human (the drafted plan awaits approval, or an agent raised a decision).
+           The same affordance the board card carries, resolved from the same composable — the
+           run's park must not be reachable only through the execution panel's step list. -->
       <UButton
-        v-if="awaitingAnswers"
+        v-if="attention"
+        data-testid="initiative-review"
+        :data-attention="attention.kind"
+        color="warning"
+        variant="solid"
+        size="sm"
+        :icon="INITIATIVE_ATTENTION_ICONS[attention.kind]"
+        @click="attention.open()"
+      >
+        {{ t(INITIATIVE_ATTENTION_LABEL_KEYS[attention.kind]) }}
+      </UButton>
+      <UButton
+        v-else-if="awaitingAnswers"
         data-testid="initiative-answer-planning"
         color="primary"
         variant="solid"

package/app/components/settings/InfrastructureWindow.logic.spec.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest'
+import {
+  infrastructureTabs,
+  openInfrastructureTab,
+  repinInfrastructureTab,
+} from './InfrastructureWindow.logic'
+
+const NONE = { agents: false, environments: false, packageRegistries: false }
+
+describe('infrastructureTabs', () => {
+  it('shows nothing when no probe reports a backend', () => {
+    expect(infrastructureTabs(NONE)).toEqual([])
+  })
+
+  it('rides the environment probe for shared stacks', () => {
+    // A shared stack is infra a Tester environment ATTACHES to, so it cannot stand on its own:
+    // without an environment backend there is nothing to attach it to.
+    expect(infrastructureTabs({ ...NONE, environments: true })).toEqual([
+      'environment',
+      'shared-stacks',
+    ])
+  })
+
+  it('gates the registries tab on its own module probe', () => {
+    // The backend 503s the module with no encryption key. That is independent of any execution
+    // or test-env backend, so the tab can be the ONLY one a deployment shows.
+    expect(infrastructureTabs({ ...NONE, packageRegistries: true })).toEqual(['package-registries'])
+    expect(infrastructureTabs({ ...NONE, agents: true })).toEqual(['runner-pool'])
+  })
+
+  it('orders tabs by the question they answer, not by which probe resolved', () => {
+    expect(
+      infrastructureTabs({ agents: true, environments: true, packageRegistries: true }),
+    ).toEqual(['runner-pool', 'environment', 'shared-stacks', 'package-registries'])
+  })
+})
+
+describe('openInfrastructureTab', () => {
+  it('honours an available deep-linked tab over the first one', () => {
+    expect(openInfrastructureTab(['runner-pool', 'package-registries'], 'package-registries')).toBe(
+      'package-registries',
+    )
+  })
+
+  it('falls back to the first available tab when the request is off', () => {
+    expect(openInfrastructureTab(['runner-pool'], 'package-registries')).toBe('runner-pool')
+  })
+
+  it('keeps naming the requested tab when nothing is available yet', () => {
+    // Every probe is still in flight on the first open. Holding the request (rather than
+    // inventing a selection) is what lets the re-pin land on it the moment its probe resolves.
+    expect(openInfrastructureTab([], 'package-registries')).toBe('package-registries')
+  })
+})
+
+describe('repinInfrastructureTab', () => {
+  it('leaves the user where they are when their tab is still available', () => {
+    // The list GROWS as probes resolve; someone reading a tab must not be yanked off it.
+    expect(
+      repinInfrastructureTab(
+        ['runner-pool', 'environment', 'package-registries'],
+        'environment',
+        'runner-pool',
+        true,
+      ),
+    ).toBe('environment')
+  })
+
+  it('lands on the deep-linked tab once its probe resolves', () => {
+    // The registries probe is the slow one: the window opened on `runner-pool` because
+    // `package-registries` was not there yet, and this is the moment it arrives.
+    expect(
+      repinInfrastructureTab(
+        ['runner-pool', 'package-registries'],
+        'shared-stacks',
+        'package-registries',
+        true,
+      ),
+    ).toBe('package-registries')
+  })
+
+  it('does not steal the selection while the probes are still settling', () => {
+    // A transient list holding only the fastest probe's tab. Falling back to it here would pin
+    // the user to whichever probe won the race and then REJECT the deep link for being a peer
+    // of the current tab.
+    expect(
+      repinInfrastructureTab(['runner-pool'], 'package-registries', 'package-registries', false),
+    ).toBe('package-registries')
+  })
+
+  it('falls back to the first tab once loading settled and the request is unavailable', () => {
+    expect(
+      repinInfrastructureTab(['runner-pool'], 'package-registries', 'package-registries', true),
+    ).toBe('runner-pool')
+  })
+
+  it('holds the current tab when settling left nothing available at all', () => {
+    expect(repinInfrastructureTab([], 'environment', 'environment', true)).toBe('environment')
+  })
+})

package/app/components/settings/InfrastructureWindow.logic.ts

@@ -0,0 +1,78 @@
+import type { InfrastructureTab } from '~/types/providerConnections'
+
+// Pure tab arithmetic behind `InfrastructureWindow.vue`: which tabs exist for this deployment,
+// and which one to show. Extracted so it is unit-tested directly rather than through the DOM —
+// the window's tabs come from THREE probes that resolve independently (the infrastructure
+// capability, the provider-connection store, the package-registries module), so the interesting
+// behaviour is what happens while the list is still growing, which a rendered-component test
+// reproduces only by accident.
+//
+// Labels stay in the component: a label resolved here would have to travel as a message KEY and
+// be fed to `t()` as a variable, which is exactly what defeats the typed-message-key check. The
+// component maps a tab onto a literal `t()` call through an exhaustive Record instead.
+
+/** Which of the window's tabs this deployment can show, as their probes currently read. */
+export interface InfrastructureTabAvailability {
+  /** An execution backend is reported (runner pool / container runtime / local). */
+  agents: boolean
+  /** A test-environment backend is reported. Also gates the shared-stacks tab. */
+  environments: boolean
+  /** The package-registries module answered its probe affirmatively (it 503s unconfigured). */
+  packageRegistries: boolean
+}
+
+/**
+ * The window's tabs, in display order. Order is the reading order of the questions they answer:
+ * where agent containers run, where test environments run, what those environments attach to,
+ * and what a checkout may install from.
+ *
+ * Shared stacks ride the test-environment probe because a stack is infra an environment attaches
+ * to — there is nothing to attach without an environment backend.
+ */
+export function infrastructureTabs(available: InfrastructureTabAvailability): InfrastructureTab[] {
+  const tabs: InfrastructureTab[] = []
+  if (available.agents) tabs.push('runner-pool')
+  if (available.environments) tabs.push('environment', 'shared-stacks')
+  if (available.packageRegistries) tabs.push('package-registries')
+  return tabs
+}
+
+/**
+ * The tab to show when the window OPENS. The deep-linked request wins whenever it is available;
+ * otherwise fall back to the first tab that is.
+ *
+ * Whatever tab was showing last time is deliberately NOT consulted: the caller has just asked
+ * for `requested`, and honouring a leftover selection over it would silently ignore the deep
+ * link. Falling back to `requested` when nothing is available at all keeps the ref naming the
+ * thing that was asked for, so the re-pin below can land on it once its probe resolves.
+ */
+export function openInfrastructureTab(
+  tabs: readonly InfrastructureTab[],
+  requested: InfrastructureTab,
+): InfrastructureTab {
+  if (tabs.includes(requested)) return requested
+  return tabs[0] ?? requested
+}
+
+/**
+ * The tab to show after the tab list CHANGES (a probe resolved). Unlike the open-time choice
+ * this one protects the user's current position: a tab list that grows under someone reading a
+ * tab must not yank them elsewhere.
+ *
+ * `settled` is what stops the transient single-tab list from stealing the selection. The probes
+ * resolve independently, so the list legitimately passes through states missing tabs that are
+ * about to appear; falling back to the first tab before the probes have settled would pin the
+ * user to whichever one happened to resolve first, and the deep-linked tab would then be
+ * REJECTED for being the current one's peer rather than shown.
+ */
+export function repinInfrastructureTab(
+  tabs: readonly InfrastructureTab[],
+  current: InfrastructureTab,
+  requested: InfrastructureTab,
+  settled: boolean,
+): InfrastructureTab {
+  if (tabs.includes(current)) return current
+  if (tabs.includes(requested)) return requested
+  if (settled && tabs.length) return tabs[0]!
+  return current
+}