@cat-factory/app 0.261.0 → 0.261.2

package/app/components/foundational/FoundationalServiceManager.vue

@@ -45,7 +45,7 @@ watch(
   () => {
     void catalog.probe()
     // The repo pickers need the active board's installation state; probe once so they light up.
-    void github.probe()
+    void github.ensureProbed()
   },
   { immediate: true },
 )

package/app/components/fragments/FragmentLibraryManager.vue

@@ -62,7 +62,7 @@ watch(
     void documents.probe()
     // The GitHub pickers (repo search + tree browser) need the active board's
     // installation state; probe once so they light up when the App is connected.
-    void github.probe()
+    void github.ensureProbed()
   },
   { immediate: true },
 )

package/app/components/layout/BoardTopOverlays.vue

@@ -3,6 +3,7 @@ import BoardToolbar from '~/components/layout/BoardToolbar.vue'
 import ConnectionStatusBanner from '~/components/layout/ConnectionStatusBanner.vue'
 import SpendWarningBanner from '~/components/layout/SpendWarningBanner.vue'
 import GitHubPatBanner from '~/components/layout/GitHubPatBanner.vue'
+import GitHubPatPermissionsBanner from '~/components/layout/GitHubPatPermissionsBanner.vue'
 import AiProvidersBanner from '~/components/layout/AiProvidersBanner.vue'
 import ProviderConfigBanner from '~/components/layout/ProviderConfigBanner.vue'
 import InfraSetupBanner from '~/components/layout/InfraSetupBanner.vue'
@@ -68,6 +69,10 @@ const ui = useUiStore()
          - Connection status: what is on screen right now may already be stale.
          - Spend exceeded: runs are blocked until the budget moves.
          - GitHub PAT (local mode): every repo-operating step will fail.
+         - GitHub PAT permissions: a token IS configured, but it cannot push or open pull
+           requests, so every repo-operating step will fail just as surely. Directly after its
+           missing-token sibling, which it can never appear beside (that one raises only when
+           there is no token, this one only when there is).
          - AI readiness: no usable model source, or the default preset names unavailable models.
          - Infrastructure provider: env/runner-pool wired but missing mandatory config.
          - Infra setup: an executor / test env / storage this deployment needs is undefined, so
@@ -82,6 +87,7 @@ const ui = useUiStore()
     />
     <SpendWarningBanner />
     <GitHubPatBanner />
+    <GitHubPatPermissionsBanner />
     <AiProvidersBanner />
     <ProviderConfigBanner />
     <InfraSetupBanner />

package/app/components/layout/GitHubPatPermissionsBanner.vue

@@ -0,0 +1,224 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import {
+  GITHUB_PAT_FINE_GRAINED_PERMISSIONS,
+  githubPatCheckNeedsAttention,
+  githubPatCheckSource,
+  missingGitHubPatCapabilities,
+} from '@cat-factory/contracts'
+import type { GitHubPatCapability, GitHubPatKind } from '~/types/domain'
+import { githubPatRemintUrl } from '~/utils/vcs'
+
+// The token a run would authenticate with cannot do what the pipeline needs.
+//
+// This is the board-load half of a warning the backend already logs at boot in local mode: a
+// developer's terminal is easy to miss, and on a HOSTED deployment there is no terminal at all
+// for the case this also covers, where the run initiator's own stored token outranks the App
+// installation. Either way the alternative to saying it here is saying it eight steps into a
+// pipeline as a 403 out of a container, after the run has spent money.
+//
+// It raises on ESTABLISHED blocking gaps only (`githubPatCheckNeedsAttention`). An unreachable
+// GitHub, an advisory-only finding and an unknowable fine-grained permission each render
+// nothing over the board, because none of them is something the reader can act on right now and
+// a banner that appears when nothing is wrong is one people learn to dismiss unread.
+//
+// Positioning/stacking is owned by `BoardTopOverlays`; this renders only its card.
+
+const { t } = useI18n()
+const github = useGitHubStore()
+
+const dismissed = ref(false)
+const check = computed(() => github.patCheck)
+const show = computed(
+  () => !dismissed.value && check.value !== null && githubPatCheckNeedsAttention(check.value),
+)
+
+/** The report, when the check produced one. Absent for a token GitHub rejected outright. */
+const report = computed(() => (check.value?.state === 'checked' ? check.value.report : undefined))
+
+/**
+ * Which claim the card is making. `rejected` is the strictly worse problem (the token does not
+ * authenticate at all), so it gets its own copy rather than being folded into "some capability
+ * is missing" — every capability would read as missing, which describes the symptom and not the
+ * cause.
+ */
+const claim = computed<'rejected' | 'underscoped'>(() =>
+  check.value?.state === 'token_rejected' ? 'rejected' : 'underscoped',
+)
+
+const missing = computed<GitHubPatCapability[]>(() =>
+  report.value ? missingGitHubPatCapabilities(report.value).blocking : [],
+)
+/**
+ * Established gaps that do NOT stop a pipeline, listed inside the card but never the reason it
+ * opened. Today that is `workflows`: worth fixing while you are on the token page, not worth
+ * interrupting a board for on its own.
+ */
+const advisory = computed<GitHubPatCapability[]>(() =>
+  report.value ? missingGitHubPatCapabilities(report.value).advisory : [],
+)
+
+const CAPABILITY_KEYS: Record<GitHubPatCapability, string> = {
+  push: 'layout.githubPatPermissionsBanner.capability.push',
+  pullRequests: 'layout.githubPatPermissionsBanner.capability.pullRequests',
+  workflows: 'layout.githubPatPermissionsBanner.capability.workflows',
+}
+function capabilityLabel(capability: GitHubPatCapability): string {
+  return t(CAPABILITY_KEYS[capability])
+}
+
+/**
+ * The kind carried over to the re-mint link. A rejected token was never classified, so it falls
+ * back to `unknown` — which lands on the classic form, the only one GitHub lets us pre-fill.
+ */
+const kind = computed<GitHubPatKind>(() => report.value?.kind ?? 'unknown')
+const remintUrl = computed(() =>
+  githubPatRemintUrl(kind.value, report.value?.webUrl ?? github.connection?.webUrl),
+)
+
+/**
+ * Who has to act. A deployment token is replaced by whoever runs the deployment (local mode:
+ * the developer at the terminal); an initiator token belongs to the signed-in user and is
+ * replaced in their own settings. Sending one to the other's remedy is worse than saying
+ * nothing, which is why the source rides the wire rather than being guessed from the shape.
+ *
+ * Read through the contract's own accessor rather than off `report`, because a REJECTED token
+ * produces no report and every state this banner renders carries a source. Deriving it from the
+ * report alone left the rejected case falling through to whichever branch the ternary ended on,
+ * which told a local developer whose deployment token had expired to replace it in their
+ * personal settings: the exact misrouting the wire field exists to prevent.
+ */
+const sourceKey = computed(() =>
+  check.value && githubPatCheckSource(check.value) === 'deployment'
+    ? 'layout.githubPatPermissionsBanner.sourceDeployment'
+    : 'layout.githubPatPermissionsBanner.sourceInitiator',
+)
+
+/** The fine-grained form takes no prefill, so the permissions have to be named as prose. */
+const fineGrainedPermissions = GITHUB_PAT_FINE_GRAINED_PERMISSIONS.join(', ')
+</script>
+
+<template>
+  <Transition name="fade">
+    <div v-if="show" class="pointer-events-auto w-full max-w-3xl">
+      <div
+        class="w-full max-w-3xl rounded-2xl border-2 border-red-500/70 bg-red-950/95 p-5 shadow-2xl backdrop-blur"
+        role="alert"
+        data-testid="github-pat-permissions-banner"
+      >
+        <div class="flex items-start gap-4">
+          <UIcon name="i-lucide-shield-alert" class="mt-0.5 h-9 w-9 shrink-0 text-red-400" />
+          <div class="min-w-0 flex-1">
+            <div class="flex items-start justify-between gap-3">
+              <h2 class="text-lg font-semibold text-red-100">
+                {{
+                  claim === 'rejected'
+                    ? t('layout.githubPatPermissionsBanner.rejectedTitle')
+                    : t('layout.githubPatPermissionsBanner.title')
+                }}
+              </h2>
+              <UButton
+                color="neutral"
+                variant="ghost"
+                size="xs"
+                icon="i-lucide-x"
+                :aria-label="t('common.close')"
+                @click="
+                  () => {
+                    dismissed = true
+                  }
+                "
+              />
+            </div>
+
+            <p class="mt-1 text-sm text-red-200/90">
+              {{
+                claim === 'rejected'
+                  ? t('layout.githubPatPermissionsBanner.rejectedBody')
+                  : t('layout.githubPatPermissionsBanner.body')
+              }}
+            </p>
+
+            <!-- The established gaps, named one by one. A bare "permissions are missing" leaves
+                 the reader to guess which box to tick on a form with dozens. -->
+            <p v-if="missing.length" class="mt-3 text-sm text-red-100">
+              <span class="font-medium">{{ t('layout.githubPatPermissionsBanner.missing') }}</span>
+              {{ missing.map(capabilityLabel).join(', ') }}
+            </p>
+            <p v-if="advisory.length" class="mt-1 text-xs text-red-200/80">
+              {{
+                t('layout.githubPatPermissionsBanner.alsoMissing', {
+                  capabilities: advisory.map(capabilityLabel).join(', '),
+                })
+              }}
+            </p>
+
+            <!-- For a fine-grained token, WHICH repositories it was not granted is the whole
+                 remedy: the permission list is right and the repository selection is not. -->
+            <p v-if="report && report.deniedRepos.length" class="mt-1 text-xs text-red-200/80">
+              {{
+                t('layout.githubPatPermissionsBanner.deniedRepos', {
+                  repos: report.deniedRepos.join(', '),
+                })
+              }}
+            </p>
+
+            <p class="mt-2 text-xs text-red-200/80">{{ t(sourceKey) }}</p>
+
+            <div class="mt-4">
+              <UButton
+                :to="remintUrl"
+                target="_blank"
+                rel="noopener noreferrer"
+                color="error"
+                variant="solid"
+                icon="i-lucide-external-link"
+                trailing
+              >
+                {{
+                  kind === 'fine_grained'
+                    ? t('layout.githubPatPermissionsBanner.createFineGrained')
+                    : t('layout.githubPatPermissionsBanner.createClassic')
+                }}
+              </UButton>
+              <!-- The classic form arrives with the scopes ticked; the fine-grained one accepts
+                   no prefill at all, so its permissions are spelled out. Saying so is the point:
+                   a link that silently arrived with nothing selected reads as "already done for
+                   you", which is how the missing permission got there in the first place. -->
+              <p class="mt-2 text-xs text-red-300/70">
+                {{
+                  kind === 'fine_grained'
+                    ? t('layout.githubPatPermissionsBanner.fineGrainedHint', {
+                        permissions: fineGrainedPermissions,
+                      })
+                    : t('layout.githubPatPermissionsBanner.classicHint')
+                }}
+              </p>
+              <!-- A fine-grained verdict is a SAMPLE of the linked repositories. Declaring the
+                   remainder keeps a clean-looking list from reading as a guarantee. -->
+              <p v-if="report && report.unprobedRepoCount > 0" class="mt-1 text-xs text-red-300/60">
+                {{
+                  t('layout.githubPatPermissionsBanner.sampled', {
+                    checked: report.probedRepos.length,
+                    remaining: report.unprobedRepoCount,
+                  })
+                }}
+              </p>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </Transition>
+</template>
+
+<style scoped>
+.fade-enter-active,
+.fade-leave-active {
+  transition: opacity 0.2s ease;
+}
+.fade-enter-from,
+.fade-leave-to {
+  opacity: 0;
+}
+</style>

package/app/components/settings/ConnectionTestVerdict.vue

@@ -0,0 +1,62 @@
+<script setup lang="ts">
+// The verdict of one "Test connection" probe, rendered identically everywhere a connect form
+// offers that button.
+//
+// Its own component because the message stopped being a few words. A failed probe now reports
+// the EXACT transport failure plus what to do about it (kernel's `connectionFailureResult`),
+// which runs to a sentence or three, and the inline `<span>` each form used to carry sat inside
+// a `flex items-center` row beside the button, where a long message squashes the button and
+// overflows the panel. So the result is a block that wraps, and the six forms share it rather
+// than each growing its own copy of the same markup.
+//
+// Two lines, because that account is English by construction and this SPA ships in ten languages.
+// The backend states the failure CLASS as a machine-readable `failureCause`; the headline is that
+// class in the operator's own language, and the backend's prose sits under it as the detail. The
+// detail stays VISIBLE rather than folding behind a disclosure: it is the half that names the
+// concrete host, port and remedy, and a probe verdict is read to find out what to go fix.
+import { computed } from 'vue'
+import type { ConnectionFailureCause } from '@cat-factory/contracts'
+import { CONNECTION_FAILURE_CAUSE_KEYS } from '~/utils/connectionFailures'
+
+const props = defineProps<{
+  /** The probe verdict; null before the first test (renders nothing). */
+  result: { ok: boolean; message?: string; failureCause?: ConnectionFailureCause } | null
+}>()
+
+const { t, te } = useI18n()
+
+/**
+ * The translated-headline key for this failure, or null when there is none: an `unknown` cause, a
+ * cause this SPA build predates, or a failure that was an ANSWER (an HTTP status the provider
+ * mapped itself, which carries no transport cause). In every one of those the backend's own
+ * message becomes the primary line, so a missing translation is never a blank verdict.
+ */
+const causeKey = computed(() => {
+  const cause = props.result && !props.result.ok ? props.result.failureCause : undefined
+  const key = cause ? CONNECTION_FAILURE_CAUSE_KEYS[cause] : null
+  return key && te(key) ? key : null
+})
+
+const headline = computed(() =>
+  causeKey.value
+    ? t(causeKey.value)
+    : (props.result?.message ?? t('settings.providerConnection.test.failed')),
+)
+
+/** The backend's English account, shown only when a headline took the primary line from it. */
+const detail = computed(() => (causeKey.value ? (props.result?.message ?? '') : ''))
+</script>
+
+<template>
+  <p
+    v-if="result?.ok"
+    class="text-xs text-emerald-400 break-words"
+    data-testid="connection-test-result"
+  >
+    {{ result.message ?? t('settings.providerConnection.test.ok') }}
+  </p>
+  <div v-else-if="result" class="space-y-0.5" data-testid="connection-test-result">
+    <p class="text-xs text-rose-400 break-words">{{ headline }}</p>
+    <p v-if="detail" class="text-[11px] text-slate-400 break-words">{{ detail }}</p>
+  </div>
+</template>

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

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+import {
+  consumeKubernetesScrollAnchor,
+  type ScrollableSection,
+} from '~/components/settings/InfraHandlersConfigurator.logic'
+
+/**
+ * The `cat-factory k3s` hand-off promises the operator lands on the ONE form the CLI just filled
+ * in. `k3sDeepLink.spec.ts` pins that the link arms the anchor; this pins the other half, that the
+ * panel consumes it exactly once and only when there is something to scroll to.
+ */
+function recorder(): ScrollableSection & { calls: ScrollIntoViewOptions[] } {
+  const calls: ScrollIntoViewOptions[] = []
+  return { calls, scrollIntoView: (options) => calls.push(options) }
+}
+
+describe('consumeKubernetesScrollAnchor', () => {
+  it('scrolls the section into view once the panel and the section are both there', () => {
+    const section = recorder()
+    const outcome = consumeKubernetesScrollAnchor({
+      target: 'kubernetes',
+      available: true,
+      section,
+    })
+
+    expect(outcome).toBe('scrolled')
+    expect(section.calls).toEqual([{ behavior: 'smooth', block: 'start' }])
+  })
+
+  it('does nothing when no anchor is pending, so a plain open never jumps', () => {
+    const section = recorder()
+    expect(consumeKubernetesScrollAnchor({ target: null, available: true, section })).toBe(
+      'not-anchored',
+    )
+    expect(section.calls).toEqual([])
+  })
+
+  it('does nothing while the infra probe is still resolving', () => {
+    // The whole configurator is behind `v-if="infra.available === true"`, and that probe resolves
+    // AFTER the deep link fires: the section cannot be scrolled to before it exists.
+    const section = recorder()
+    expect(consumeKubernetesScrollAnchor({ target: 'kubernetes', available: null, section })).toBe(
+      'not-anchored',
+    )
+    expect(section.calls).toEqual([])
+  })
+
+  it('leaves the anchor for the next attempt when the section has not rendered yet', () => {
+    // `not-rendered` is what keeps the hand-off alive across the render the probe gates: only
+    // `scrolled` tells the caller to clear the store's target, so a miss cannot swallow the link.
+    const first = consumeKubernetesScrollAnchor({
+      target: 'kubernetes',
+      available: true,
+      section: null,
+    })
+    expect(first).toBe('not-rendered')
+
+    const section = recorder()
+    expect(consumeKubernetesScrollAnchor({ target: 'kubernetes', available: true, section })).toBe(
+      'scrolled',
+    )
+    expect(section.calls).toHaveLength(1)
+  })
+})

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

@@ -0,0 +1,41 @@
+import type { InfrastructureScrollTarget } from '~/types/providerConnections'
+
+// The deep-link SECTION anchor the `cat-factory k3s` hand-off lands on, as a plain function so the
+// rule is testable: the component half is a `watch` plus an `onMounted` retry, and neither is
+// reachable from a spec (this SPA has no component-mounting harness).
+//
+// The rule that needed pinning is the three-way outcome, not the scroll. The anchor is one-shot and
+// is consumed only once the section is actually IN the DOM, but the section renders behind an async
+// probe, so an attempt that finds nothing must leave the anchor ARMED for the next attempt rather
+// than clear it. Clearing on a miss silently swallows the hand-off on a slow probe; never clearing
+// leaves a dead anchor, which is why "scrolled" is the only outcome the caller acts on and why
+// closing the window drops whatever is left (`closeProviderConnection`).
+
+/** The minimum of an element this needs, so a spec can pass a recorder instead of a DOM node. */
+export interface ScrollableSection {
+  scrollIntoView: (options: ScrollIntoViewOptions) => void
+}
+
+export interface ScrollAnchorAttempt {
+  /** The store's pending anchor, or null when there is nothing to land on. */
+  target: InfrastructureScrollTarget | null
+  /** The infra-probe gate the sections render behind; null while it is still resolving. */
+  available: boolean | null
+  /** The section element, or null when it has not rendered yet. */
+  section: ScrollableSection | null
+}
+
+/**
+ * - `scrolled`: the anchor was honoured and the CALLER must now clear it.
+ * - `not-anchored`: nothing is pending for this section (or the panel is not showing yet).
+ * - `not-rendered`: it IS pending, but the section is not in the DOM, so the anchor stays armed.
+ */
+export type ScrollAnchorOutcome = 'scrolled' | 'not-anchored' | 'not-rendered'
+
+/** Honour a pending Kubernetes-section anchor, reporting which of the three cases this was. */
+export function consumeKubernetesScrollAnchor(attempt: ScrollAnchorAttempt): ScrollAnchorOutcome {
+  if (attempt.target !== 'kubernetes' || attempt.available !== true) return 'not-anchored'
+  if (!attempt.section) return 'not-rendered'
+  attempt.section.scrollIntoView({ behavior: 'smooth', block: 'start' })
+  return 'scrolled'
+}

package/app/components/settings/InfraHandlersConfigurator.vue

@@ -12,7 +12,7 @@
 //                      per custom type (matched to a service's pinned `manifestId`).
 // In LOCAL mode each handler additionally offers a per-USER override (this-machine only),
 // written to the `/me/environment-handlers` endpoints. Drives the infraConfig store.
-import { computed, ref, watch } from 'vue'
+import { computed, nextTick, onMounted, ref, watch } from 'vue'
 import type {
   CustomManifestType,
   EnvironmentHandlerView,
@@ -28,6 +28,8 @@ import KubernetesEngineForm from '~/components/settings/KubernetesEngineForm.vue
 import ProviderManifestEditor from '~/components/settings/ProviderManifestEditor.vue'
 import CustomManifestTypeEditor from '~/components/settings/CustomManifestTypeEditor.vue'
 import CloudflareHandlerSection from '~/components/settings/CloudflareHandlerSection.vue'
+import ConnectionTestVerdict from '~/components/settings/ConnectionTestVerdict.vue'
+import { consumeKubernetesScrollAnchor } from '~/components/settings/InfraHandlersConfigurator.logic'
 
 const { t } = useI18n()
 const infra = useInfraConfigStore()
@@ -94,6 +96,32 @@ watch(
   { immediate: true },
 )
 
+// Deep-link anchor: the `cat-factory k3s` hand-off opens this window with the ui store's scroll
+// target set to `kubernetes`, so bring that section into view once rather than dropping the
+// operator at the top of the tab to hunt for the form the CLI just described.
+//
+// Attempted from BOTH the watch and `onMounted`, and the anchor is cleared only on a real scroll:
+// the section is behind `v-if="infra.available === true"`, whose probe resolves after the deep link
+// fires, so a single attempt that finds nothing rendered would swallow the hand-off with neither
+// watched value ever changing again to re-drive it. The decision itself is in the logic module,
+// where it is tested.
+const kubeSection = ref<HTMLElement | null>(null)
+async function anchorKubernetesSection() {
+  await nextTick()
+  const outcome = consumeKubernetesScrollAnchor({
+    target: ui.infrastructureScrollTarget,
+    available: infra.available,
+    section: kubeSection.value,
+  })
+  if (outcome === 'scrolled') ui.clearInfrastructureScrollTarget()
+}
+watch([() => ui.infrastructureScrollTarget, () => infra.available], () => {
+  void anchorKubernetesSection()
+})
+onMounted(() => {
+  void anchorKubernetesSection()
+})
+
 const busy = ref(false)
 
 // Connection-probe state for the kube engine forms (workspace + per-user override kept
@@ -400,7 +428,11 @@ function notifyError(e: unknown) {
     <p class="text-xs text-slate-400">{{ t('settings.infrastructure.handler.intro') }}</p>
 
     <!-- kubernetes -->
-    <section class="space-y-2 rounded-lg border border-slate-700 bg-slate-900/40 p-3">
+    <section
+      ref="kubeSection"
+      class="space-y-2 rounded-lg border border-slate-700 bg-slate-900/40 p-3"
+      data-testid="infra-kubernetes-section"
+    >
       <h3 class="text-sm font-semibold text-slate-200">
         {{ t('inspector.testConfig.provisionTypes.kubernetes') }}
       </h3>
@@ -433,7 +465,7 @@ function notifyError(e: unknown) {
           {{ t('settings.infrastructure.handler.activeEngine') }}
           <span class="text-slate-200">{{ kubeHandlerEngineLabel }}</span>
         </p>
-        <div class="flex items-center gap-2 pl-7">
+        <div class="space-y-1.5 pl-7">
           <UButton
             color="neutral"
             variant="soft"
@@ -444,12 +476,7 @@ function notifyError(e: unknown) {
           >
             {{ t('settings.providerConnection.test.button') }}
           </UButton>
-          <span v-if="kubeSavedTestResult?.ok" class="text-xs text-emerald-400">
-            {{ kubeSavedTestResult.message ?? t('settings.providerConnection.test.ok') }}
-          </span>
-          <span v-else-if="kubeSavedTestResult" class="text-xs text-rose-400">
-            {{ kubeSavedTestResult.message ?? t('settings.providerConnection.test.failed') }}
-          </span>
+          <ConnectionTestVerdict :result="kubeSavedTestResult" />
         </div>
       </div>
       <p v-else class="flex items-center gap-1.5 text-[12px] text-slate-500">

package/app/components/settings/KubernetesEngineForm.vue

@@ -9,6 +9,7 @@
 import { computed, reactive, ref, watch } from 'vue'
 import { KUBERNETES_ENV_TOKEN_SECRET_KEY } from '@cat-factory/contracts'
 import SecretInput from '~/components/common/SecretInput.vue'
+import ConnectionTestVerdict from '~/components/settings/ConnectionTestVerdict.vue'
 import type {
   EnvironmentHandlerView,
   InfraEngine,
@@ -75,6 +76,13 @@ const form = reactive({
   urlScheme: 'default' as 'default' | 'http' | 'https',
 })
 const apiToken = ref('')
+// Flag a bad paste ON THE FIELD, before Test is ever clicked. The guided CLI flow ends with
+// "copy this token out of your terminal", and a terminal wraps: a token copied across that wrap
+// carries an invisible newline that survives `.trim()` and can never become an `authorization`
+// header. Left to the probe it comes back as an opaque transport failure minutes later.
+// Destructured at the top level so the template auto-unwraps the refs (a ref nested in a plain
+// object is not unwrapped in a template, only a top-level one is).
+const { blocking: tokenBlocking, message: tokenProblem } = useServiceAccountTokenProblem(apiToken)
 
 const urlSourceItems = computed(() => [
   {
@@ -210,6 +218,7 @@ const canSave = computed(
     !!form.label.trim() &&
     !!form.apiServerUrl.trim() &&
     (tokenStored.value || !!apiToken.value.trim()) &&
+    !tokenBlocking.value &&
     urlValid.value,
 )
 
@@ -232,6 +241,9 @@ const connectBlockedReason = computed(() => {
     missing.push(t('settings.infrastructure.kubernetesEngine.serviceName'))
   if (missing.length)
     return t('settings.providerConnection.form.missingFields', { fields: missing.join(', ') })
+  // Repeated from under the token field, so the disabled button is never left unexplained for a
+  // reader whose eye is on it rather than on the field above.
+  if (tokenBlocking.value) return tokenProblem.value
   return t('settings.infrastructure.kubernetesEngine.invalidPort')
 })
 
@@ -414,6 +426,16 @@ async function copyAutoSetupCommand() {
             : undefined
         "
       />
+      <!-- Rose when the paste is impossible (blocks Test/Save), amber when it is only suspicious
+           and the operator may legitimately overrule it. -->
+      <p
+        v-if="tokenProblem"
+        class="mt-1 text-[11px]"
+        :class="tokenBlocking ? 'text-rose-400' : 'text-amber-400'"
+        data-testid="service-account-token-problem"
+      >
+        {{ tokenProblem }}
+      </p>
     </UFormField>
 
     <!-- URL derivation: how the live environment URL is resolved once the service's
@@ -517,7 +539,7 @@ async function copyAutoSetupCommand() {
       />
     </UFormField>
 
-    <div v-if="supportsTest" class="flex items-center gap-2">
+    <div v-if="supportsTest" class="space-y-1.5">
       <UButton
         color="neutral"
         variant="soft"
@@ -529,12 +551,7 @@ async function copyAutoSetupCommand() {
       >
         {{ t('settings.providerConnection.test.button') }}
       </UButton>
-      <span v-if="testResult && testResult.ok" class="text-xs text-emerald-400">
-        {{ testResult.message ?? t('settings.providerConnection.test.ok') }}
-      </span>
-      <span v-else-if="testResult" class="text-xs text-rose-400">
-        {{ testResult.message ?? t('settings.providerConnection.test.failed') }}
-      </span>
+      <ConnectionTestVerdict :result="testResult" />
     </div>
 
     <div class="flex items-center justify-end gap-3">