From 917a7aefc4bb06ac0c0528c3ad3035d49f196b30 Mon Sep 17 00:00:00 2001
From: morgmart <98432065+morgmart@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:43:36 -0700
Subject: [PATCH 1/5] Rework onboarding around one default harness

Signed-off-by: morgmart <98432065+morgmart@users.noreply.github.com>
---
 desktop/src/features/agents/AGENTS.md         |  26 +-
 .../agents/lib/agentConfigCore.test.mjs       |  17 +-
 .../features/agents/lib/agentConfigCore.ts    |  14 +-
 .../features/agents/ui/AgentConfigFields.tsx  |  37 +-
 .../src/features/agents/ui/bakedEnvHelpers.ts |  22 +
 .../onboarding/ui/DefaultConfigStep.tsx       | 872 +++++++++++++-----
 .../onboarding/ui/HarnessChoiceCard.tsx       |  53 ++
 .../onboarding/ui/MachineOnboardingFlow.tsx   |  30 +-
 .../src/features/onboarding/ui/SetupStep.tsx  | 663 ++-----------
 desktop/src/features/onboarding/ui/types.ts   |   3 +-
 desktop/src/testing/e2eBridge.ts              |   7 +-
 .../e2e/onboarding-agent-defaults.spec.ts     | 860 +++++++----------
 desktop/tests/helpers/bridge.ts               |   2 +
 13 files changed, 1218 insertions(+), 1388 deletions(-)
 create mode 100644 desktop/src/features/onboarding/ui/HarnessChoiceCard.tsx

diff --git a/desktop/src/features/agents/AGENTS.md b/desktop/src/features/agents/AGENTS.md
index 35ad4a63af5..54227a2466d 100644
--- a/desktop/src/features/agents/AGENTS.md
+++ b/desktop/src/features/agents/AGENTS.md
@@ -34,13 +34,12 @@ with a TypeScript lookup table or an id comparison in a component.
    descriptor's `currentPersistence` key — never a raw
    `BUZZ_AGENT_THINKING_EFFORT` literal in UI code. `currentPersistence` is
    where the value lives *today*; `targetApplication` is how the harness
-   *should* receive it. They intentionally differ until PR 2.7 migrates
-   Goose/Claude — do not "fix" one to match the other without doing the
-   migration work.
+   *should* receive it. Do not render Goose effort until its native
+   `GOOSE_THINKING_EFFORT` persistence and live option source are wired.
 3. **Field absence has a named reason, not a boolean.** Codex effort is
-   `ownedByModelId`; Claude effort is `deferredUntilNativeOptionsAvailable`.
-   New absences get new named reasons in `AgentConfigOmission` /
-   `render` — never a `showX` prop.
+   `ownedByModelId`; Goose effort is `pendingNativePersistence`; Claude effort
+   is `deferredUntilNativeOptionsAvailable`. New absences get new named reasons
+   in `AgentConfigOmission` / `render` — never a `showX` prop.
 4. **The clearing policy is the named types.** `onContextChange:
    "resetDependentValues"` (user changed harness/provider → dependent values
    reset everywhere) vs `onCatalogMismatch: "explainOnly" | "onboardingCleanup"`
@@ -64,14 +63,17 @@ with a TypeScript lookup table or an id comparison in a component.
    via `synthesizeEmptyDiscoveryStatus()` and is intentionally **not cached**
    so that closing → reopening the dialog re-runs discovery after the user
    installs or signs into the CLI (`isCacheableDiscoveryResponse()`).
-7. **Onboarding setup detects readiness; it does not select defaults.** The
-   setup page derives visible and ready harnesses from the runtime catalog and
-   only offers install or sign-in actions. The following defaults page is the
-   sole onboarding surface that chooses and persists `preferred_runtime`, and
-   its Finish gate consumes the shared renderer's `onValidityChange` signal —
-   a harness selection alone does not complete onboarding when the harness
+7. **Onboarding chooses locally, then sets up one selected harness.** The
+   chooser page derives visible harnesses from the runtime catalog, renders
+   simple single-choice cards, and must not install, sign in, configure, or
+   persist. The selected-harness setup page handles only the chosen harness's
+   missing work: install, sign-in, or provider/model defaults — and its
+   Finish gate consumes the shared renderer's `onValidityChange` signal: a
+   harness selection alone does not complete onboarding when the harness
    requires provider/model/credential config (e.g. buzz-agent with no
    provider). Baked build env and runtime-file config satisfy the gate.
+   Card clicks are local draft state; final completion is the only
+   onboarding action that persists `preferred_runtime`.
    `onboarding-agent-defaults.spec.ts` is the acceptance gate for anything
    touching this flow or the shared renderer.
 8. **Omit the Model control only after a confirmed successful empty
diff --git a/desktop/src/features/agents/lib/agentConfigCore.test.mjs b/desktop/src/features/agents/lib/agentConfigCore.test.mjs
index 62d8a61a6fa..423065443c9 100644
--- a/desktop/src/features/agents/lib/agentConfigCore.test.mjs
+++ b/desktop/src/features/agents/lib/agentConfigCore.test.mjs
@@ -60,7 +60,7 @@ test("Buzz Agent exposes provider, model, and Buzz-owned effort", () => {
   });
 });
 
-test("Goose exposes provider, model, and its real effort application key", () => {
+test("Goose omits effort until native persistence and options are wired", () => {
   const model = deriveAgentConfigFieldModel({
     config,
     runtime: runtime("goose", {
@@ -72,17 +72,12 @@ test("Goose exposes provider, model, and its real effort application key", () =>
   });
 
   assert.equal(
-    field(model, "effort").optionSource,
-    "legacyProviderModelCatalog",
+    model.fields.some((item) => item.kind === "effort"),
+    false,
   );
-  assert.deepEqual(field(model, "effort").currentPersistence, {
-    kind: "envVar",
-    key: "BUZZ_AGENT_THINKING_EFFORT",
-  });
-  assert.deepEqual(field(model, "effort").targetApplication, {
-    kind: "envVar",
-    key: "GOOSE_THINKING_EFFORT",
-  });
+  assert.deepEqual(model.omissions, [
+    { kind: "effort", reason: "pendingNativePersistence" },
+  ]);
 });
 
 test("Claude models effort as a deferred native ACP option", () => {
diff --git a/desktop/src/features/agents/lib/agentConfigCore.ts b/desktop/src/features/agents/lib/agentConfigCore.ts
index 5827aedfa7b..cc99456f413 100644
--- a/desktop/src/features/agents/lib/agentConfigCore.ts
+++ b/desktop/src/features/agents/lib/agentConfigCore.ts
@@ -73,7 +73,10 @@ export type AgentConfigFieldDescriptor =
 
 export type AgentConfigOmission = {
   kind: "effort";
-  reason: "ownedByModelId" | "unsupportedByHarness";
+  reason:
+    | "ownedByModelId"
+    | "pendingNativePersistence"
+    | "unsupportedByHarness";
 };
 
 export type AgentConfigFieldModel = {
@@ -127,13 +130,10 @@ export function deriveAgentConfigFieldModel({
     value: config.model,
   });
 
-  if (runtime?.thinkingEnvVar) {
+  if (runtime?.id === "buzz-agent" && runtime.thinkingEnvVar) {
     fields.push({
       kind: "effort",
-      optionSource:
-        runtime.id === "buzz-agent"
-          ? "buzzAgentCatalog"
-          : "legacyProviderModelCatalog",
+      optionSource: "buzzAgentCatalog",
       currentPersistence: {
         kind: "envVar",
         key: BUZZ_AGENT_THINKING_EFFORT,
@@ -142,6 +142,8 @@ export function deriveAgentConfigFieldModel({
       render: "control",
       value: valueFromEnv(config, BUZZ_AGENT_THINKING_EFFORT),
     });
+  } else if (runtime?.id === "goose" && runtime.thinkingEnvVar) {
+    omissions.push({ kind: "effort", reason: "pendingNativePersistence" });
   } else if (runtime?.id === "claude") {
     fields.push({
       kind: "effort",
diff --git a/desktop/src/features/agents/ui/AgentConfigFields.tsx b/desktop/src/features/agents/ui/AgentConfigFields.tsx
index 1bd8af89761..5c2fbf88e35 100644
--- a/desktop/src/features/agents/ui/AgentConfigFields.tsx
+++ b/desktop/src/features/agents/ui/AgentConfigFields.tsx
@@ -1,14 +1,11 @@
 /**
  * Controlled field group for global agent config (provider, model, effort, env vars).
  *
- * Used by AgentDefaultsSettingsCard (settings panel) and AgentDefaultsSection
- * (onboarding setup step). The parent manages load/save state; this component is
- * purely presentational and calls onConfigChange on every user edit.
+ * The parent manages load/save state; edits are reported through onConfigChange.
  */
 import * as React from "react";
 import { ChevronDown } from "lucide-react";
 import { AnimatePresence, motion, useReducedMotion } from "motion/react";
-
 import type {
   BakedEnvEntry,
   RuntimeFileConfigSubset,
@@ -27,7 +24,7 @@ import {
 } from "@/features/agents/lib/agentConfigCore";
 import {
   getBakedProviderInheritLabel,
-  getGlobalModelFallback,
+  getRuntimeBakedDefaults,
 } from "@/features/agents/ui/bakedEnvHelpers";
 import {
   AUTO_PROVIDER_DROPDOWN_VALUE,
@@ -271,11 +268,12 @@ export function AgentConfigFields({
     effortField?.currentPersistence.kind === "envVar"
       ? effortField.currentPersistence.key
       : null;
-  const bakedProvider = React.useMemo(
-    () => bakedEnv.find((e) => e.key === "BUZZ_AGENT_PROVIDER")?.value ?? null,
-    [bakedEnv],
-  );
   const selectedRuntimeId = selectedRuntime?.id ?? "";
+  const runtimeBakedDefaults = React.useMemo(
+    () => getRuntimeBakedDefaults(bakedEnv, selectedRuntime, config.env_vars),
+    [bakedEnv, config.env_vars, selectedRuntime],
+  );
+  const bakedProvider = runtimeBakedDefaults.provider;
   const providerFieldVisible = hasRenderableAgentConfigField(
     fieldModel,
     "provider",
@@ -283,10 +281,7 @@ export function AgentConfigFields({
   const effectiveProvider = providerFieldVisible
     ? config.provider?.trim() || bakedProvider || ""
     : "";
-  const fallbackModel = React.useMemo(
-    () => getGlobalModelFallback(bakedEnv, effectiveProvider, config.env_vars),
-    [bakedEnv, config.env_vars, effectiveProvider],
-  );
+  const fallbackModel = runtimeBakedDefaults.model;
   const modelField = fieldModel.fields.find(
     (field) => field.kind === "model" && field.render === "control",
   );
@@ -641,14 +636,20 @@ export function AgentConfigFields({
   const effortFieldVisible = showEffortField && effortField !== undefined;
 
   const progressiveDefaults = disclosure === "progressive-defaults";
+  const onboardingEssential = disclosure === "onboarding-essential";
   const fieldClassName = unstyled
-    ? progressiveDefaults
-      ? "space-y-1.5"
-      : "space-y-4"
+    ? onboardingEssential
+      ? "space-y-0"
+      : progressiveDefaults
+        ? "space-y-1.5"
+        : "space-y-4"
     : "space-y-1.5 p-3";
   const blockClassName = unstyled ? "" : "p-3";
-  const fieldLabelClassName =
-    unstyled && !progressiveDefaults ? "pl-3" : undefined;
+  const fieldLabelClassName = onboardingEssential
+    ? "sr-only"
+    : unstyled && !progressiveDefaults
+      ? "pl-3"
+      : undefined;
   const providerDropdownOptions = [
     ...providerOptions
       .filter(
diff --git a/desktop/src/features/agents/ui/bakedEnvHelpers.ts b/desktop/src/features/agents/ui/bakedEnvHelpers.ts
index 40b33282566..b119407365d 100644
--- a/desktop/src/features/agents/ui/bakedEnvHelpers.ts
+++ b/desktop/src/features/agents/ui/bakedEnvHelpers.ts
@@ -58,6 +58,28 @@ export function getBakedModelInheritLabel(bakedModelId: string): string {
   return `Inherit build default (${bakedModelId})`;
 }
 
+/** Resolve baked provider/model values only from this runtime's catalog keys. */
+export function getRuntimeBakedDefaults(
+  bakedEnv: readonly BakedEnvEntry[],
+  runtime:
+    | { id: string; modelEnvVar: string | null; providerEnvVar: string | null }
+    | undefined,
+  globalEnv: Readonly<Record<string, string>>,
+): { model: string | null; provider: string | null } {
+  const provider = runtime?.providerEnvVar
+    ? resolveInheritedDefault(null, bakedEnv, runtime.providerEnvVar).value
+    : "";
+  const directModel = runtime?.modelEnvVar
+    ? resolveInheritedDefault(null, bakedEnv, runtime.modelEnvVar).value
+    : "";
+  const model =
+    directModel ||
+    (runtime?.id === "buzz-agent"
+      ? getGlobalModelFallback(bakedEnv, provider, globalEnv)
+      : null);
+  return { model: model || null, provider: provider || null };
+}
+
 function providerModelEnvKey(provider: string): string | null {
   switch (provider.trim().toLowerCase()) {
     case "databricks":
diff --git a/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx b/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
index 50887f08aa7..a5181255283 100644
--- a/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
+++ b/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
@@ -1,7 +1,11 @@
 import * as React from "react";
+import { openUrl } from "@tauri-apps/plugin-opener";
 
 import {
+  useAcpAuthMethodsQuery,
   useAcpRuntimesQuery,
+  useConnectAcpRuntimeMutation,
+  useInstallAcpRuntimeMutation,
   useRuntimeFileConfigQuery,
 } from "@/features/agents/hooks";
 import {
@@ -9,19 +13,27 @@ import {
   EMPTY_GLOBAL_CONFIG,
 } from "@/features/agents/ui/AgentConfigFields";
 import { resetConfigForHarnessChange } from "@/features/agents/ui/agentConfigOptions";
-import { AgentDropdownSelect } from "@/features/agents/ui/agentConfigControls";
-import { createSaveCoalescer } from "./saveCoalescer";
+import { getRuntimeBakedDefaults } from "@/features/agents/ui/bakedEnvHelpers";
+import { getGlobalAgentCredentialState } from "@/features/agents/ui/globalAgentCredentialState";
 import { getBakedBuildEnv, type BakedEnvEntry } from "@/shared/api/tauri";
 import {
   getGlobalAgentConfig,
   setGlobalAgentConfig,
 } from "@/shared/api/tauriGlobalAgentConfig";
 import type {
+  AcpAuthMethod,
   AcpRuntimeCatalogEntry,
   GlobalAgentConfig,
 } from "@/shared/api/types";
+import { cn } from "@/shared/lib/cn";
+import { getInstallErrorMessage } from "@/shared/lib/installError";
 import { Button } from "@/shared/ui/button";
 import { Spinner } from "@/shared/ui/spinner";
+import {
+  HARNESS_SETUP_CARD_WIDTH_CLASS,
+  HarnessChoiceCard,
+} from "./HarnessChoiceCard";
+import { RuntimeErrorTooltip } from "./RuntimeErrorTooltip";
 import { ONBOARDING_PRIMARY_CTA_CLASS } from "./OnboardingChrome";
 import { OnboardingFooter } from "./OnboardingFooter";
 import {
@@ -29,295 +41,695 @@ import {
   OnboardingSlideTransition,
 } from "./OnboardingSlideTransition";
 import {
-  getReadyOnboardingRuntimes,
   getVisibleOnboardingRuntimes,
+  runtimeIsReadyForOnboarding,
 } from "./onboardingRuntimeSelection";
+import { getRuntimeDisplayLabel } from "./RuntimeIcon";
 import type { DefaultConfigStepActions } from "./types";
 
 type DefaultConfigStepProps = {
   actions: DefaultConfigStepActions;
   direction: OnboardingTransitionDirection;
-  readyRuntimeIds: readonly string[];
+  selectedRuntimeId: string | null;
+};
+
+type InstallResultState = {
+  error: string | null;
+  success: boolean;
 };
 
-function formatHarnessLabel(runtime: AcpRuntimeCatalogEntry | undefined) {
-  if (!runtime) return "Select a harness";
-  return runtime.id === "buzz-agent" ? "Buzz" : runtime.label;
+type SetupPlanKind =
+  | "loading"
+  | "catalog-error"
+  | "missing-runtime"
+  | "needs-install"
+  | "needs-sign-in"
+  | "auth-unknown"
+  | "auth-invalid"
+  | "needs-provider-defaults"
+  | "ready";
+
+function runtimeNeedsOnboardingProviderSetup(runtime: AcpRuntimeCatalogEntry) {
+  return Boolean(runtime.providerEnvVar);
+}
+
+function bakedEnvKeys(bakedEnv: readonly BakedEnvEntry[]) {
+  return bakedEnv.map((entry) => entry.key);
 }
 
-function AgentDefaultsSection({
-  onPersistenceStateChange,
-  readyRuntimeIds,
+function providerDefaultsAreSatisfied({
+  bakedEnv,
+  config,
+  runtimeFileConfig,
+  runtime,
 }: {
-  onPersistenceStateChange: (state: {
-    canComplete: boolean;
-    flush: () => Promise<void>;
-  }) => void;
-  readyRuntimeIds: readonly string[];
+  bakedEnv: readonly BakedEnvEntry[];
+  config: GlobalAgentConfig;
+  runtimeFileConfig:
+    | {
+        provider: string | null;
+        model: string | null;
+        satisfiedEnvKeys: string[];
+      }
+    | null
+    | undefined;
+  runtime: AcpRuntimeCatalogEntry;
 }) {
-  const runtimesQuery = useAcpRuntimesQuery();
-  const [config, setConfig] =
-    React.useState<GlobalAgentConfig>(EMPTY_GLOBAL_CONFIG);
-  const [isLoading, setIsLoading] = React.useState(true);
-  const [isCustomProvider, setIsCustomProvider] = React.useState(false);
-  const [isCustomModelEditing, setIsCustomModelEditing] = React.useState(false);
-  const [bakedEnv, setBakedEnv] = React.useState<BakedEnvEntry[]>([]);
-  const coalescerRef = React.useRef<{
-    enqueue: (value: GlobalAgentConfig) => void;
-    flush: () => Promise<void>;
-    cancel: () => void;
-  } | null>(null);
-  const [isSaving, setIsSaving] = React.useState(false);
-  const [configIsValid, setConfigIsValid] = React.useState(false);
-
-  React.useEffect(() => {
-    let unmounted = false;
-
-    async function loadDefaults() {
-      const [configResult, bakedEnvResult] = await Promise.allSettled([
-        getGlobalAgentConfig(),
-        getBakedBuildEnv(),
-      ]);
+  const runtimeBakedDefaults = getRuntimeBakedDefaults(
+    bakedEnv,
+    runtime,
+    config.env_vars,
+  );
+  const effectiveProvider =
+    config.provider?.trim() ||
+    runtimeBakedDefaults.provider ||
+    runtimeFileConfig?.provider?.trim() ||
+    "";
+  const effectiveModel =
+    config.model?.trim() ||
+    runtimeFileConfig?.model?.trim() ||
+    runtimeBakedDefaults.model ||
+    "";
+  const { credentialsValid } = getGlobalAgentCredentialState({
+    bakedEnvKeys: bakedEnvKeys(bakedEnv),
+    envVars: config.env_vars,
+    provider: effectiveProvider,
+    runtimeFileConfig,
+    runtimeId: runtime.id,
+  });
 
-      if (unmounted) return;
+  return (
+    effectiveProvider.length > 0 &&
+    effectiveModel.length > 0 &&
+    credentialsValid
+  );
+}
 
-      if (configResult.status === "fulfilled") {
-        setConfig(configResult.value);
-      }
-      if (bakedEnvResult.status === "fulfilled") {
-        setBakedEnv(bakedEnvResult.value);
+function deriveSetupPlan({
+  bakedEnv,
+  config,
+  isConfigLoading,
+  runtime,
+  runtimeFileConfig,
+}: {
+  bakedEnv: readonly BakedEnvEntry[];
+  config: GlobalAgentConfig;
+  isConfigLoading: boolean;
+  runtime: AcpRuntimeCatalogEntry | undefined;
+  runtimeFileConfig:
+    | {
+        provider: string | null;
+        model: string | null;
+        satisfiedEnvKeys: string[];
       }
-      setIsLoading(false);
+    | null
+    | undefined;
+}): SetupPlanKind {
+  if (isConfigLoading) return "loading";
+  if (!runtime) return "missing-runtime";
+  if (runtime.availability !== "available") return "needs-install";
+  if (runtime.authStatus.status === "logged_out") return "needs-sign-in";
+  if (runtime.authStatus.status === "unknown") return "auth-unknown";
+  if (runtime.authStatus.status === "config_invalid") return "auth-invalid";
+
+  if (runtimeNeedsOnboardingProviderSetup(runtime)) {
+    if (
+      providerDefaultsAreSatisfied({
+        bakedEnv,
+        config,
+        runtimeFileConfig,
+        runtime,
+      })
+    ) {
+      return "ready";
     }
+    return "needs-provider-defaults";
+  }
 
-    void loadDefaults();
+  return runtimeIsReadyForOnboarding(runtime) ? "ready" : "auth-unknown";
+}
 
-    // The coalescer serializes autosaves and drains any edit that arrived
-    // while a previous save was in flight. Cancel on unmount so a slow
-    // in-flight request never calls setState on an unmounted component.
-    const coalescer = createSaveCoalescer<GlobalAgentConfig>(
-      // set_global_agent_config returns a save result (config + restart
-      // counts); the coalescer round-trips the persisted config only.
-      async (next) => (await setGlobalAgentConfig(next)).config,
-      (saving) => {
-        if (!unmounted) setIsSaving(saving);
-      },
-      (saved) => {
-        if (!unmounted) setConfig(saved);
-      },
-    );
-    coalescerRef.current = coalescer;
+function isSupportedOnboardingAuthMethod(
+  runtime: AcpRuntimeCatalogEntry,
+  method: AcpAuthMethod,
+) {
+  if (runtime.id !== "codex") return true;
+  return !/api[-_ ]?key/i.test(`${method.id} ${method.name}`);
+}
 
-    return () => {
-      unmounted = true;
-      coalescer.cancel();
-    };
-  }, []);
-
-  const effectiveReadyRuntimeIds = React.useMemo(
-    () =>
-      readyRuntimeIds.length > 0
-        ? readyRuntimeIds
-        : getReadyOnboardingRuntimes(runtimesQuery.data ?? []).map(
-            (runtime) => runtime.id,
-          ),
-    [readyRuntimeIds, runtimesQuery.data],
+function isPreferredClaudeAuthMethod(method: AcpAuthMethod) {
+  const haystack = [
+    method.id,
+    method.name,
+    method.description ?? "",
+    method.command.join(" "),
+    method.args.join(" "),
+  ]
+    .join(" ")
+    .toLowerCase();
+  return (
+    haystack.includes("claudeai") ||
+    haystack.includes("claude ai") ||
+    haystack.includes("claude.ai") ||
+    haystack.includes("subscription")
   );
-  const readyRuntimeIdSet = React.useMemo(
-    () => new Set(effectiveReadyRuntimeIds),
-    [effectiveReadyRuntimeIds],
+}
+
+function getOnboardingAuthMethods(
+  runtime: AcpRuntimeCatalogEntry,
+  methods: AcpAuthMethod[],
+) {
+  const supported = methods.filter((method) =>
+    isSupportedOnboardingAuthMethod(runtime, method),
   );
-  // Setup already confirmed readiness. Re-filter only for onboarding
-  // visibility here; a transient auth recheck must not invalidate that handoff.
-  const readyRuntimes = React.useMemo(
-    () =>
-      getVisibleOnboardingRuntimes(runtimesQuery.data ?? []).filter((runtime) =>
-        readyRuntimeIdSet.has(runtime.id),
-      ),
-    [readyRuntimeIdSet, runtimesQuery.data],
+  if (runtime.id === "claude") {
+    const preferred =
+      supported.find(isPreferredClaudeAuthMethod) ?? supported[0];
+    return preferred ? [preferred] : [];
+  }
+  if (runtime.id === "codex") return supported.slice(0, 1);
+  return supported;
+}
+
+function SelectedRuntimeHeader({
+  runtime,
+}: {
+  runtime: AcpRuntimeCatalogEntry | undefined;
+}) {
+  return (
+    <div className="w-full max-w-[540px] text-center">
+      <h1 className="text-title font-normal text-foreground">
+        Set up {runtime ? getRuntimeDisplayLabel(runtime) : "your harness"}
+      </h1>
+      <p className="mx-auto mt-3 max-w-[440px] text-sm leading-5 text-foreground/80">
+        Buzz will use this harness by default. You can connect and add more
+        harnesses later in Settings.
+      </p>
+    </div>
   );
-  const selectedRuntime = React.useMemo(
-    () =>
-      readyRuntimes.find((runtime) => runtime.id === config.preferred_runtime),
-    [config.preferred_runtime, readyRuntimes],
+}
+
+/**
+ * Setup-page layout: the selected harness card sits on the left and the
+ * state-specific description + action live in a left-aligned column on the
+ * right. The parent page owns the single vanilla fade transition.
+ */
+function SelectedHarnessLayout({
+  children,
+  runtime,
+}: {
+  children: React.ReactNode;
+  runtime: AcpRuntimeCatalogEntry;
+}) {
+  return (
+    <div className="flex w-full flex-col items-center gap-8 sm:flex-row sm:items-center sm:justify-center sm:gap-14">
+      <div
+        className={cn("shrink-0", HARNESS_SETUP_CARD_WIDTH_CLASS)}
+        data-testid="onboarding-selected-runtime-card"
+      >
+        <HarnessChoiceCard runtime={runtime} />
+      </div>
+      <div className="flex w-full max-w-2xs flex-col items-start gap-4 text-left [@media(max-height:560px)]:gap-2">
+        {children}
+      </div>
+    </div>
   );
-  const selectedRuntimeId = selectedRuntime?.id ?? "";
-  const { data: runtimeFileConfig } =
-    useRuntimeFileConfigQuery(selectedRuntimeId);
-  const configSurfaceLoading = isLoading || runtimesQuery.isLoading;
-
-  const configSurfaceError =
-    runtimesQuery.isError ||
-    (!configSurfaceLoading &&
-      effectiveReadyRuntimeIds.length > 0 &&
-      readyRuntimes.length === 0);
-  const harnessOptions = React.useMemo(
-    () =>
-      readyRuntimes.map((runtime) => ({
-        label: formatHarnessLabel(runtime),
-        value: runtime.id,
-      })),
-    [readyRuntimes],
+}
+
+function LoadingSetup({ runtime }: { runtime: AcpRuntimeCatalogEntry }) {
+  return (
+    <SelectedHarnessLayout runtime={runtime}>
+      <div
+        aria-live="polite"
+        className="flex items-center gap-2 text-sm text-muted-foreground"
+        role="status"
+      >
+        <Spinner className="h-4 w-4 border-2" />
+        Checking setup…
+      </div>
+    </SelectedHarnessLayout>
   );
+}
+
+function InstallSetup({
+  installResult,
+  isInstalling,
+  onInstall,
+  runtime,
+}: {
+  installResult: InstallResultState;
+  isInstalling: boolean;
+  onInstall: () => void;
+  runtime: AcpRuntimeCatalogEntry;
+}) {
+  const installLabel = installResult.error ? "Retry install" : "Install";
 
-  const handleHarnessChange = React.useCallback(
-    (runtimeId: string) => {
-      const next = resetConfigForHarnessChange(config, runtimeId);
-      setIsCustomModelEditing(false);
-      setIsCustomProvider(false);
-      setConfig(next);
-      coalescerRef.current?.enqueue(next);
-    },
-    [config],
+  return (
+    <SelectedHarnessLayout runtime={runtime}>
+      <p className="text-sm leading-6 text-foreground/80">
+        {getRuntimeDisplayLabel(runtime)} hasn’t been detected on your computer.
+        You can install it now.
+      </p>
+      {runtime.canAutoInstall ? (
+        <Button
+          className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
+          data-testid={`onboarding-runtime-install-${runtime.id}`}
+          disabled={isInstalling}
+          onClick={onInstall}
+          type="button"
+        >
+          {isInstalling ? (
+            <span className="inline-flex items-center gap-2">
+              <Spinner className="h-4 w-4 border-2 text-foreground" />
+              Installing…
+            </span>
+          ) : (
+            installLabel
+          )}
+        </Button>
+      ) : (
+        <Button
+          className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
+          onClick={() => void openUrl(runtime.installInstructionsUrl)}
+          type="button"
+        >
+          View install instructions
+        </Button>
+      )}
+      {installResult.error ? (
+        <RuntimeErrorTooltip
+          className="flex min-w-0 items-center gap-1.5 overflow-hidden whitespace-nowrap text-xs leading-4 text-destructive"
+          detail={installResult.error}
+          label="Installation failed"
+          showIcon
+          testId={`onboarding-runtime-error-${runtime.id}`}
+        />
+      ) : null}
+    </SelectedHarnessLayout>
   );
+}
+
+function SignInSetup({ runtime }: { runtime: AcpRuntimeCatalogEntry }) {
+  const methodsQuery = useAcpAuthMethodsQuery(runtime.id, {
+    enabled:
+      runtime.availability === "available" &&
+      runtime.authStatus.status === "logged_out",
+  });
+  const connectMutation = useConnectAcpRuntimeMutation();
+  const runtimesQuery = useAcpRuntimesQuery();
+  const [isWaitingForSignIn, setIsWaitingForSignIn] = React.useState(false);
+  const [didSignInCheckTimeOut, setDidSignInCheckTimeOut] =
+    React.useState(false);
+  const isReady = runtimeIsReadyForOnboarding(runtime);
 
   React.useEffect(() => {
-    if (configSurfaceLoading || selectedRuntimeId) return;
-    if (readyRuntimes.length !== 1) return;
-    handleHarnessChange(readyRuntimes[0].id);
-  }, [
-    configSurfaceLoading,
-    handleHarnessChange,
-    readyRuntimes,
-    selectedRuntimeId,
-  ]);
-
-  const flushPersistence = React.useCallback(
-    () => coalescerRef.current?.flush() ?? Promise.resolve(),
-    [],
-  );
+    if (!isWaitingForSignIn || !isReady) return;
+    setIsWaitingForSignIn(false);
+    setDidSignInCheckTimeOut(false);
+  }, [isReady, isWaitingForSignIn]);
+
   React.useEffect(() => {
-    onPersistenceStateChange({
-      // configIsValid comes from AgentConfigFields' onValidityChange and
-      // covers model + provider credentials — a harness selection alone is
-      // not a working default (e.g. buzz-agent with no provider configured).
-      canComplete: selectedRuntimeId.length > 0 && configIsValid && !isSaving,
-      flush: flushPersistence,
-    });
-  }, [
-    configIsValid,
-    flushPersistence,
-    isSaving,
-    onPersistenceStateChange,
-    selectedRuntimeId,
-  ]);
+    if (!isWaitingForSignIn) return;
+
+    const interval = window.setInterval(() => {
+      void runtimesQuery.refetch();
+    }, 2_000);
+    const timeout = window.setTimeout(() => {
+      setIsWaitingForSignIn(false);
+      setDidSignInCheckTimeOut(true);
+    }, 120_000);
+
+    return () => {
+      window.clearInterval(interval);
+      window.clearTimeout(timeout);
+    };
+  }, [isWaitingForSignIn, runtimesQuery.refetch]);
+
+  const authMethods = getOnboardingAuthMethods(
+    runtime,
+    methodsQuery.data?.methods ?? [],
+  );
+  const authMethod = authMethods[0] ?? null;
+  const authMethodsUnavailable =
+    !methodsQuery.isLoading && !methodsQuery.error && authMethod === null;
 
   return (
-    <section className="w-full space-y-4 text-left text-sm">
-      {configSurfaceLoading ? (
-        <div className="flex items-center justify-center gap-2 py-4 text-sm text-muted-foreground">
-          <Spinner className="h-4 w-4 border-2" />
-          Loading…
-        </div>
-      ) : configSurfaceError ? (
-        <p className="py-4 text-center text-sm text-destructive">
-          Couldn't load harness settings. Go back and try again.
+    <SelectedHarnessLayout runtime={runtime}>
+      <p className="text-sm leading-6 text-foreground/80">
+        Sign in to {getRuntimeDisplayLabel(runtime)} so Buzz can start agents
+        with this harness.
+      </p>
+      <Button
+        aria-label={`Sign in to ${runtime.label}`}
+        className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
+        data-testid={`onboarding-runtime-instructions-${runtime.id}`}
+        disabled={connectMutation.isPending || authMethodsUnavailable}
+        onClick={() => {
+          if (didSignInCheckTimeOut) {
+            setDidSignInCheckTimeOut(false);
+            setIsWaitingForSignIn(true);
+            void runtimesQuery.refetch();
+            return;
+          }
+          if (!authMethod) {
+            void methodsQuery.refetch();
+            return;
+          }
+          connectMutation.mutate(
+            { methodId: authMethod.id, runtimeId: runtime.id },
+            { onSuccess: () => setIsWaitingForSignIn(true) },
+          );
+        }}
+        type="button"
+      >
+        {isWaitingForSignIn
+          ? "Checking…"
+          : didSignInCheckTimeOut
+            ? "Check again"
+            : "Sign in"}
+      </Button>
+      {authMethodsUnavailable ? (
+        <p className="text-xs leading-4 text-destructive" role="status">
+          No supported sign-in method is available.
         </p>
-      ) : (
-        <div className="space-y-7">
-          <div className="space-y-4">
-            <label
-              className="pl-3 text-sm font-medium"
-              htmlFor="global-agent-default-harness"
-            >
-              Default harness
-            </label>
-            <AgentDropdownSelect
-              className="h-12 rounded-2xl border-foreground/15 bg-white px-4 py-2 text-sm shadow-none hover:bg-white/95"
-              id="global-agent-default-harness"
-              onValueChange={handleHarnessChange}
-              options={harnessOptions}
-              placeholder="Select a harness"
-              placeholderClassName="text-foreground/70"
-              testId="global-agent-default-harness"
-              value={selectedRuntimeId}
-            />
-          </div>
-
-          <AgentConfigFields
-            bakedEnv={bakedEnv}
-            selectedRuntime={selectedRuntime}
-            config={config}
-            isCustomModelEditing={isCustomModelEditing}
-            isCustomProvider={isCustomProvider}
-            onConfigChange={(next) => {
-              // Always apply optimistically so the UI never reverts mid-save,
-              // then enqueue the persist — the coalescer serialises multiple
-              // rapid edits into a single trailing request.
-              setConfig(next);
-              coalescerRef.current?.enqueue(next);
-            }}
-            onCustomModelEditingChange={setIsCustomModelEditing}
-            onIsCustomProviderChange={setIsCustomProvider}
-            onValidityChange={setConfigIsValid}
-            placeholderClassName="text-foreground/70"
-            runtimeFileConfig={runtimeFileConfig}
-            selectClassName="h-12 rounded-2xl border-foreground/15 bg-white px-4 py-2 text-sm shadow-none hover:bg-white/95"
-            disclosure="onboarding-essential"
-            unstyled
-            useCustomSelect
-          />
-        </div>
-      )}
-    </section>
+      ) : null}
+      {methodsQuery.error instanceof Error ? (
+        <RuntimeErrorTooltip
+          className="text-xs leading-4 text-destructive"
+          detail="Couldn’t load sign-in options."
+          label="Sign-in unavailable"
+        />
+      ) : null}
+      {connectMutation.error instanceof Error ? (
+        <RuntimeErrorTooltip
+          className="text-xs leading-4 text-destructive"
+          detail="Couldn’t start sign-in. Try again."
+          label="Sign-in failed"
+        />
+      ) : null}
+    </SelectedHarnessLayout>
+  );
+}
+
+function AuthCheckSetup({
+  label,
+  message,
+  runtime,
+}: {
+  label: string;
+  message: string;
+  runtime: AcpRuntimeCatalogEntry;
+}) {
+  const runtimesQuery = useAcpRuntimesQuery();
+
+  return (
+    <SelectedHarnessLayout runtime={runtime}>
+      <p className="text-sm leading-6 text-foreground/80">{message}</p>
+      <Button
+        className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
+        disabled={runtimesQuery.isFetching}
+        onClick={() => void runtimesQuery.refetch()}
+        type="button"
+      >
+        {runtimesQuery.isFetching ? "Checking…" : label}
+      </Button>
+    </SelectedHarnessLayout>
+  );
+}
+
+function ProviderDefaultsSetup({
+  bakedEnv,
+  config,
+  onConfigChange,
+  onValidityChange,
+  runtime,
+  runtimeFileConfig,
+}: {
+  bakedEnv: BakedEnvEntry[];
+  config: GlobalAgentConfig;
+  onConfigChange: (next: GlobalAgentConfig) => void;
+  onValidityChange: (valid: boolean) => void;
+  runtime: AcpRuntimeCatalogEntry;
+  runtimeFileConfig:
+    | {
+        provider: string | null;
+        model: string | null;
+        satisfiedEnvKeys: string[];
+      }
+    | null
+    | undefined;
+}) {
+  const [isCustomProvider, setIsCustomProvider] = React.useState(false);
+  const [isCustomModelEditing, setIsCustomModelEditing] = React.useState(false);
+
+  return (
+    <SelectedHarnessLayout runtime={runtime}>
+      <p className="text-sm leading-6 text-foreground/80">
+        Choose the default provider and model Buzz should use with this harness.
+      </p>
+      <div className="w-full">
+        <AgentConfigFields
+          bakedEnv={bakedEnv}
+          selectedRuntime={runtime}
+          config={config}
+          isCustomModelEditing={isCustomModelEditing}
+          isCustomProvider={isCustomProvider}
+          onConfigChange={onConfigChange}
+          onCustomModelEditingChange={setIsCustomModelEditing}
+          onIsCustomProviderChange={setIsCustomProvider}
+          onValidityChange={onValidityChange}
+          placeholderClassName="text-foreground/70"
+          runtimeFileConfig={runtimeFileConfig}
+          selectClassName="h-12 rounded-2xl border-foreground/15 bg-white px-4 py-2 text-sm shadow-none hover:bg-white/95"
+          disclosure="onboarding-essential"
+          unstyled
+          useCustomSelect
+        />
+      </div>
+    </SelectedHarnessLayout>
+  );
+}
+
+function ReadySetup({ runtime }: { runtime: AcpRuntimeCatalogEntry }) {
+  return (
+    <SelectedHarnessLayout runtime={runtime}>
+      <p className="text-sm leading-6 text-foreground/80">
+        {getRuntimeDisplayLabel(runtime)} is ready. Buzz will use it as your
+        default harness.
+      </p>
+    </SelectedHarnessLayout>
   );
 }
 
-/**
- * Machine onboarding page 4 — default model configuration. Presents the
- * global agent defaults (provider, model, effort, env vars) centered under
- * the mock's "Configure your default model settings" heading.
- */
 export function DefaultConfigStep({
   actions,
   direction,
-  readyRuntimeIds,
+  selectedRuntimeId,
 }: DefaultConfigStepProps) {
-  const [persistenceState, setPersistenceState] = React.useState<{
-    canComplete: boolean;
-    flush: () => Promise<void>;
-  }>({ canComplete: false, flush: () => Promise.resolve() });
+  const runtimesQuery = useAcpRuntimesQuery();
+  const visibleRuntimes = React.useMemo(
+    () => getVisibleOnboardingRuntimes(runtimesQuery.data ?? []),
+    [runtimesQuery.data],
+  );
+  const selectedRuntime = visibleRuntimes.find(
+    (runtime) => runtime.id === selectedRuntimeId,
+  );
+  const { data: runtimeFileConfig, isLoading: runtimeFileConfigLoading } =
+    useRuntimeFileConfigQuery(selectedRuntimeId ?? "", {
+      enabled: Boolean(selectedRuntimeId),
+    });
+  const [config, setConfig] =
+    React.useState<GlobalAgentConfig>(EMPTY_GLOBAL_CONFIG);
+  const [bakedEnv, setBakedEnv] = React.useState<BakedEnvEntry[]>([]);
+  const [isConfigLoading, setIsConfigLoading] = React.useState(true);
+  const [configValid, setConfigValid] = React.useState(false);
+  const [installResult, setInstallResult] = React.useState<InstallResultState>({
+    error: null,
+    success: false,
+  });
+  const installMutation = useInstallAcpRuntimeMutation();
   const [completionError, setCompletionError] = React.useState<string | null>(
     null,
   );
   const [isCompleting, setIsCompleting] = React.useState(false);
 
+  React.useEffect(() => {
+    let unmounted = false;
+
+    async function loadDefaults() {
+      const [configResult, bakedEnvResult] = await Promise.allSettled([
+        getGlobalAgentConfig(),
+        getBakedBuildEnv(),
+      ]);
+
+      if (unmounted) return;
+
+      if (configResult.status === "fulfilled") {
+        const harnessChanged =
+          selectedRuntimeId !== null &&
+          selectedRuntimeId !== configResult.value.preferred_runtime;
+        setConfig(
+          harnessChanged
+            ? resetConfigForHarnessChange(configResult.value, selectedRuntimeId)
+            : configResult.value,
+        );
+      }
+      if (bakedEnvResult.status === "fulfilled") {
+        setBakedEnv(bakedEnvResult.value);
+      }
+      setIsConfigLoading(false);
+    }
+
+    void loadDefaults();
+
+    return () => {
+      unmounted = true;
+    };
+  }, [selectedRuntimeId]);
+
+  const plan: SetupPlanKind = runtimesQuery.isError
+    ? "catalog-error"
+    : deriveSetupPlan({
+        bakedEnv,
+        config,
+        isConfigLoading:
+          isConfigLoading ||
+          runtimesQuery.isLoading ||
+          runtimeFileConfigLoading,
+        runtime: selectedRuntime,
+        runtimeFileConfig,
+      });
+  // Once this page has disclosed provider setup, keep those fields mounted as
+  // they become valid. Validity gates Finish; it must not replace the form the
+  // user is actively completing.
+  const [providerSetupActivated, setProviderSetupActivated] =
+    React.useState(false);
+  React.useEffect(() => {
+    if (plan === "needs-provider-defaults") setProviderSetupActivated(true);
+  }, [plan]);
+  const effectivePlan =
+    providerSetupActivated &&
+    plan === "ready" &&
+    selectedRuntime &&
+    runtimeNeedsOnboardingProviderSetup(selectedRuntime)
+      ? "needs-provider-defaults"
+      : plan;
+  const canFinish =
+    effectivePlan === "ready" ||
+    (effectivePlan === "needs-provider-defaults" && configValid);
+
+  const handleInstall = React.useCallback(() => {
+    if (!selectedRuntime) return;
+    setInstallResult({ error: null, success: false });
+    installMutation.mutate(selectedRuntime.id, {
+      onSuccess: (result) => {
+        if (result.success) {
+          setInstallResult({ error: null, success: true });
+          void runtimesQuery.refetch();
+          return;
+        }
+        setInstallResult({
+          error: getInstallErrorMessage(result.steps),
+          success: false,
+        });
+      },
+      onError: (error) => {
+        setInstallResult({
+          error: error instanceof Error ? error.message : "Install failed.",
+          success: false,
+        });
+      },
+    });
+  }, [installMutation, runtimesQuery, selectedRuntime]);
+
   const handleComplete = React.useCallback(async () => {
+    if (!selectedRuntimeId) return;
     setIsCompleting(true);
     setCompletionError(null);
     try {
-      await persistenceState.flush();
+      await setGlobalAgentConfig({
+        ...config,
+        preferred_runtime: selectedRuntimeId,
+      });
       actions.complete();
     } catch {
       setCompletionError("Couldn't save your default harness. Try again.");
       setIsCompleting(false);
     }
-  }, [actions, persistenceState]);
+  }, [actions, config, selectedRuntimeId]);
 
   return (
     <OnboardingSlideTransition
       className="flex min-h-full w-full flex-col items-center"
       data-testid="onboarding-page-config"
       direction={direction}
+      effect="fade"
       transitionKey={`default-config-${direction}`}
     >
-      <div className="w-full max-w-[500px] text-center">
-        <h1 className="text-title font-normal text-foreground">
-          Configure your default model settings
-        </h1>
-        <p className="mx-auto mt-3 max-w-[440px] text-sm leading-5 text-foreground/80">
-          This will be set as your default model configuration across Buzz. You
-          can always change this in your Settings or give specific agents a
-          different configuration.
-        </p>
-      </div>
+      <SelectedRuntimeHeader runtime={selectedRuntime} />
 
-      <div className="flex w-full flex-1 items-center justify-center py-10">
-        <div className="w-full max-w-[328px]">
-          <AgentDefaultsSection
-            onPersistenceStateChange={setPersistenceState}
-            readyRuntimeIds={readyRuntimeIds}
-          />
+      <div className="flex w-full flex-1 items-center justify-center py-6 [@media(max-height:560px)]:items-start [@media(max-height:560px)]:py-2">
+        <div className="w-full max-w-[760px]">
+          {effectivePlan === "loading" && selectedRuntime ? (
+            <LoadingSetup runtime={selectedRuntime} />
+          ) : effectivePlan === "loading" ? (
+            <div className="flex items-center justify-center gap-2 py-4 text-sm text-muted-foreground">
+              <Spinner className="h-4 w-4 border-2" />
+              Loading…
+            </div>
+          ) : effectivePlan === "catalog-error" ? (
+            <div className="flex flex-col items-center gap-3 py-4 text-center text-sm">
+              <p className="text-destructive">
+                Couldn't load harness settings. Try again.
+              </p>
+              <Button
+                className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
+                disabled={runtimesQuery.isFetching}
+                onClick={() => void runtimesQuery.refetch()}
+                type="button"
+              >
+                {runtimesQuery.isFetching ? "Checking…" : "Try again"}
+              </Button>
+            </div>
+          ) : effectivePlan === "missing-runtime" ? (
+            <p className="py-4 text-center text-sm text-destructive">
+              Couldn't load this harness. Go back and try again.
+            </p>
+          ) : selectedRuntime ? (
+            effectivePlan === "needs-install" ? (
+              <InstallSetup
+                installResult={installResult}
+                isInstalling={installMutation.isPending}
+                onInstall={handleInstall}
+                runtime={selectedRuntime}
+              />
+            ) : effectivePlan === "needs-sign-in" ? (
+              <SignInSetup runtime={selectedRuntime} />
+            ) : effectivePlan === "auth-unknown" ? (
+              <AuthCheckSetup
+                label="Check again"
+                message="Buzz couldn't verify this harness yet. Check again after you've finished setup."
+                runtime={selectedRuntime}
+              />
+            ) : effectivePlan === "auth-invalid" ? (
+              <AuthCheckSetup
+                label="Check again"
+                message="This harness's configuration looks invalid. Fix it outside Buzz, then check again."
+                runtime={selectedRuntime}
+              />
+            ) : effectivePlan === "needs-provider-defaults" ? (
+              <ProviderDefaultsSetup
+                bakedEnv={bakedEnv}
+                config={config}
+                onConfigChange={setConfig}
+                onValidityChange={setConfigValid}
+                runtime={selectedRuntime}
+                runtimeFileConfig={runtimeFileConfig}
+              />
+            ) : (
+              <ReadySetup runtime={selectedRuntime} />
+            )
+          ) : null}
           {completionError ? (
             <p
               className="mt-3 text-center text-xs text-destructive"
@@ -333,11 +745,11 @@ export function DefaultConfigStep({
         <Button
           className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
           data-testid="onboarding-finish"
-          disabled={!persistenceState.canComplete || isCompleting}
+          disabled={!canFinish || isCompleting}
           onClick={() => void handleComplete()}
           type="button"
         >
-          Next
+          Finish
         </Button>
 
         <Button
diff --git a/desktop/src/features/onboarding/ui/HarnessChoiceCard.tsx b/desktop/src/features/onboarding/ui/HarnessChoiceCard.tsx
new file mode 100644
index 00000000000..8b484858117
--- /dev/null
+++ b/desktop/src/features/onboarding/ui/HarnessChoiceCard.tsx
@@ -0,0 +1,53 @@
+import type * as React from "react";
+
+import type { AcpRuntimeCatalogEntry } from "@/shared/api/types";
+import { cn } from "@/shared/lib/cn";
+import { Card, type CardProps } from "@/shared/ui/card";
+import { getRuntimeDisplayLabel, RuntimeIcon } from "./RuntimeIcon";
+
+/**
+ * Setup-page width that mirrors one column of the untouched chooser grid:
+ * the onboarding frame is min(viewport - page padding, 65rem), with three
+ * 1rem gaps divided across four columns. Do not apply this to the chooser —
+ * its grid remains the source of truth.
+ */
+export const HARNESS_SETUP_CARD_WIDTH_CLASS =
+  "w-full max-w-[288px] md:w-[calc((min(100vw-2rem,65rem)-3rem)/4)]";
+
+type HarnessChoiceCardProps = Omit<CardProps, "variant"> & {
+  runtime: AcpRuntimeCatalogEntry;
+};
+
+/**
+ * The single visual for an onboarding harness card — icon + name on the
+ * textured surface. The chooser renders it interactive; the setup page
+ * renders it static. Both pages keep identical size and content.
+ */
+export function HarnessChoiceCard({
+  className,
+  runtime,
+  ...cardProps
+}: HarnessChoiceCardProps): React.JSX.Element {
+  return (
+    <Card
+      className={cn(
+        // Height compresses on short windows (800×500 minimum) so the grid +
+        // docked footer fit without clipping. The textured variant's
+        // min-height floor must drop with it (see card-texture.css — compact
+        // cards opt in via the variable). Chooser and setup page share this
+        // class, keeping the card-travel transition dimension-stable.
+        "h-[180px] w-full select-none items-center px-3 py-1.5 text-center [--buzz-card-textured-min-height:180px] [@media(max-height:560px)]:h-[120px] [@media(max-height:560px)]:[--buzz-card-textured-min-height:120px]",
+        className,
+      )}
+      variant="textured"
+      {...cardProps}
+    >
+      <div className="flex min-w-0 flex-col items-center gap-3">
+        <RuntimeIcon className="h-8 w-8" runtime={runtime} />
+        <h2 className="truncate text-sm font-normal leading-5 text-foreground">
+          {getRuntimeDisplayLabel(runtime)}
+        </h2>
+      </div>
+    </Card>
+  );
+}
diff --git a/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx b/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
index ca87c76636b..2dda0a6f6d9 100644
--- a/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
+++ b/desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
@@ -64,13 +64,9 @@ export function MachineOnboardingFlow({
   const [selectedPubkey, setSelectedPubkey] = React.useState<string | null>(
     null,
   );
-  const [readyRuntimeIds, setReadyRuntimeIds] = React.useState<string[]>([]);
-  const handleReadyRuntimeIdsChange = React.useCallback(
-    (runtimeIds: readonly string[]) => {
-      setReadyRuntimeIds(Array.from(new Set(runtimeIds)));
-    },
-    [],
-  );
+  const [selectedRuntimeId, setSelectedRuntimeId] = React.useState<
+    string | null
+  >(null);
 
   const loadFreshIdentity = React.useCallback(async () => {
     setIsPending(true);
@@ -234,17 +230,11 @@ export function MachineOnboardingFlow({
               actions={{
                 back: () =>
                   setPage(identityWasImported ? "key-import" : "backup"),
-                next: (runtimeIds) => {
-                  const ids = Array.from(runtimeIds);
-                  setReadyRuntimeIds(ids);
-                  // Harness install can fail (Windows/PATH/network). Don't soft-lock
-                  // onboarding — users can finish setup later in Settings → Agents.
-                  if (ids.length === 0) {
-                    complete(selectedPubkey ?? undefined);
-                    return;
-                  }
+                next: (runtimeId) => {
+                  setSelectedRuntimeId(runtimeId);
                   setPage("config");
                 },
+                skip: () => complete(selectedPubkey ?? undefined),
                 navigateToAgentSettings: () => {
                   // Complete onboarding first, then delegate the Settings → Agents
                   // navigation to the parent.  The parent owns RouterProvider, so
@@ -258,18 +248,18 @@ export function MachineOnboardingFlow({
                 },
               }}
               direction="forward"
-              onReadyRuntimeIdsChange={handleReadyRuntimeIdsChange}
+              selectedRuntimeId={selectedRuntimeId}
             />
-          ) : (
+          ) : page === "config" ? (
             <DefaultConfigStep
               actions={{
                 back: () => setPage("setup"),
                 complete: () => complete(selectedPubkey ?? undefined),
               }}
               direction="forward"
-              readyRuntimeIds={readyRuntimeIds}
+              selectedRuntimeId={selectedRuntimeId}
             />
-          )}
+          ) : null}
         </div>
       </OnboardingFooterProvider>
     </div>
diff --git a/desktop/src/features/onboarding/ui/SetupStep.tsx b/desktop/src/features/onboarding/ui/SetupStep.tsx
index 843206aa706..3c10eb66685 100644
--- a/desktop/src/features/onboarding/ui/SetupStep.tsx
+++ b/desktop/src/features/onboarding/ui/SetupStep.tsx
@@ -1,54 +1,33 @@
 import * as React from "react";
-import { openUrl } from "@tauri-apps/plugin-opener";
-import { Check } from "lucide-react";
+import { useReducedMotion } from "motion/react";
 
-import {
-  useAcpAuthMethodsQuery,
-  useAcpRuntimesQuery,
-  useConnectAcpRuntimeMutation,
-  useInstallAcpRuntimeMutation,
-} from "@/features/agents/hooks";
-import { describeResolvedCommand } from "@/features/agents/ui/agentUi";
-import type { AcpAuthMethod, AcpRuntimeCatalogEntry } from "@/shared/api/types";
-import { getInstallErrorMessage } from "@/shared/lib/installError";
+import { useAcpRuntimesQuery } from "@/features/agents/hooks";
+import type { AcpRuntimeCatalogEntry } from "@/shared/api/types";
 import { cn } from "@/shared/lib/cn";
 import { Button } from "@/shared/ui/button";
-import { Card } from "@/shared/ui/card";
 import { FlappingBee } from "@/shared/ui/buzz-logo/FlappingBee";
-import { Spinner } from "@/shared/ui/spinner";
-import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
-import {
-  getReadyOnboardingRuntimes,
-  getVisibleOnboardingRuntimes,
-  runtimeIsReadyForOnboarding,
-} from "./onboardingRuntimeSelection";
-import { ONBOARDING_PRIMARY_CTA_CLASS } from "./OnboardingChrome";
-import { RuntimeErrorTooltip } from "./RuntimeErrorTooltip";
+import { HarnessChoiceCard } from "./HarnessChoiceCard";
+import { getVisibleOnboardingRuntimes } from "./onboardingRuntimeSelection";
 import { OnboardingFooter } from "./OnboardingFooter";
-import { getRuntimeDisplayLabel, RuntimeIcon } from "./RuntimeIcon";
 import {
   type OnboardingTransitionDirection,
   OnboardingSlideTransition,
 } from "./OnboardingSlideTransition";
 import type { SetupStepActions, SetupStepState } from "./types";
 
+/** How long unselected cards fade before the page advances (ms). */
+const CHOICE_FADE_MS = 200;
+
 type SetupStepProps = {
   actions: SetupStepActions;
   direction: OnboardingTransitionDirection;
-  onReadyRuntimeIdsChange: (runtimeIds: readonly string[]) => void;
+  selectedRuntimeId: string | null;
 };
 
 type SetupStepContentProps = SetupStepProps & {
   state: SetupStepState;
 };
 
-type InstallResultState = {
-  error: string | null;
-  success: boolean;
-};
-
-type InstallResultsState = Record<string, InstallResultState>;
-
 function useSetupStepState(): SetupStepState {
   const runtimesQuery = useAcpRuntimesQuery();
   const items = runtimesQuery.data ?? [];
@@ -65,507 +44,40 @@ function useSetupStepState(): SetupStepState {
   };
 }
 
-function RuntimeReadinessIndicator({
+function RuntimeChoiceCard({
+  dimmed,
+  onChoose,
   runtime,
-  ready,
+  selected,
 }: {
+  dimmed: boolean;
+  onChoose: () => void;
   runtime: AcpRuntimeCatalogEntry;
-  ready: boolean;
+  selected: boolean;
 }) {
-  // Checkmark temporarily hidden; flip to true to restore it.
-  const showReadinessCheckmark = false;
-  if (!ready || !showReadinessCheckmark) return null;
-
-  return (
-    <span
-      aria-hidden="true"
-      className="pointer-events-none absolute right-8 top-8 flex h-8 w-8 items-center justify-center rounded-full border border-[var(--buzz-welcome-chartreuse)] bg-[var(--buzz-welcome-chartreuse)]"
-      data-testid={`onboarding-runtime-check-${runtime.id}`}
-    >
-      <Check
-        className="h-4 w-4 text-foreground"
-        data-testid={`onboarding-runtime-checkmark-${runtime.id}`}
-        strokeWidth={3}
-      />
-    </span>
-  );
-}
-
-function RuntimeStatus({
-  installError,
-  isInstalling,
-  onInstall,
-  runtime,
-}: {
-  installError: string | null;
-  isInstalling: boolean;
-  onInstall: () => void;
-  runtime: AcpRuntimeCatalogEntry;
-}) {
-  const methodsQuery = useAcpAuthMethodsQuery(runtime.id, {
-    enabled:
-      runtime.availability === "available" &&
-      runtime.authStatus.status === "logged_out",
-  });
-  const connectMutation = useConnectAcpRuntimeMutation();
-  const runtimesQuery = useAcpRuntimesQuery();
-  const [isWaitingForSignIn, setIsWaitingForSignIn] = React.useState(false);
-  const [didSignInCheckTimeOut, setDidSignInCheckTimeOut] =
-    React.useState(false);
-  const isReady = runtimeIsReadyForOnboarding(runtime);
-
-  React.useEffect(() => {
-    if (!isWaitingForSignIn || !isReady) return;
-    setIsWaitingForSignIn(false);
-    setDidSignInCheckTimeOut(false);
-  }, [isReady, isWaitingForSignIn]);
-
-  React.useEffect(() => {
-    if (!isWaitingForSignIn) return;
-
-    const interval = window.setInterval(() => {
-      void runtimesQuery.refetch();
-    }, 2_000);
-    const timeout = window.setTimeout(() => {
-      setIsWaitingForSignIn(false);
-      setDidSignInCheckTimeOut(true);
-    }, 120_000);
-
-    return () => {
-      window.clearInterval(interval);
-      window.clearTimeout(timeout);
-    };
-  }, [isWaitingForSignIn, runtimesQuery.refetch]);
-  const authMethods = getOnboardingAuthMethods(
-    runtime,
-    methodsQuery.data?.methods ?? [],
-  );
-  const authMethod = authMethods[0] ?? null;
-  const shouldSignIn =
-    runtime.availability === "available" &&
-    runtime.authStatus.status === "logged_out";
-
-  if (shouldSignIn) {
-    return (
-      <div className="flex flex-col items-center gap-1.5">
-        <Button
-          aria-label={`Sign in to ${runtime.label}`}
-          className="buzz-onboarding-runtime-setup h-5 rounded-full bg-[var(--buzz-welcome-chartreuse)]/30 px-2.5 font-mono !text-badge font-normal uppercase text-foreground hover:bg-[var(--buzz-welcome-chartreuse)]/40"
-          data-testid={`onboarding-runtime-instructions-${runtime.id}`}
-          onClick={() => {
-            if (didSignInCheckTimeOut) {
-              setDidSignInCheckTimeOut(false);
-              setIsWaitingForSignIn(true);
-              void runtimesQuery.refetch();
-              return;
-            }
-            if (!authMethod) {
-              void methodsQuery.refetch();
-              return;
-            }
-            connectMutation.mutate(
-              {
-                methodId: authMethod.id,
-                runtimeId: runtime.id,
-              },
-              {
-                onSuccess: () => setIsWaitingForSignIn(true),
-              },
-            );
-          }}
-          type="button"
-          variant="ghost"
-        >
-          {isWaitingForSignIn
-            ? "CHECKING…"
-            : didSignInCheckTimeOut
-              ? "CHECK AGAIN"
-              : "SIGN IN"}
-        </Button>
-        {methodsQuery.error instanceof Error ? (
-          <RuntimeErrorTooltip
-            className="absolute inset-x-3 bottom-2 truncate text-xs leading-4 text-destructive"
-            detail="Couldn’t load sign-in options."
-            label="Sign-in unavailable"
-          />
-        ) : null}
-        {connectMutation.error instanceof Error ? (
-          <RuntimeErrorTooltip
-            className="absolute inset-x-3 bottom-2 truncate text-xs leading-4 text-destructive"
-            detail="Couldn’t start sign-in. Try again."
-            label="Sign-in failed"
-          />
-        ) : null}
-      </div>
-    );
-  }
-
-  if (isInstalling) {
-    return (
-      <div
-        aria-label={`Installing ${runtime.label}`}
-        className="flex h-5 items-center gap-2 rounded-full bg-white/60 px-2.5 font-mono text-badge font-normal uppercase text-foreground"
-        role="status"
-      >
-        <Spinner className="h-3 w-3 border-2 text-foreground" />
-        INSTALLING
-      </div>
-    );
-  }
-
-  if (runtimeIsReadyForOnboarding(runtime)) {
-    return (
-      <Tooltip>
-        <TooltipTrigger asChild>
-          <span
-            className="inline-flex h-5 cursor-default items-center rounded-full bg-[#EBEFEF] px-2.5 font-mono text-badge font-normal uppercase text-foreground"
-            data-testid={`onboarding-runtime-ready-${runtime.id}`}
-          >
-            READY
-          </span>
-        </TooltipTrigger>
-        <TooltipContent
-          className="max-w-80 bg-black text-left text-xs text-white shadow-sm"
-          side="top"
-        >
-          <RuntimeDetails runtime={runtime} />
-        </TooltipContent>
-      </Tooltip>
-    );
-  }
-
-  if (
-    runtime.availability === "available" &&
-    runtime.authStatus.status === "unknown"
-  ) {
-    return (
-      <Button
-        aria-label={`Check ${runtime.label} again`}
-        className="buzz-onboarding-runtime-setup h-5 rounded-full bg-[var(--buzz-welcome-chartreuse)]/30 px-2.5 font-mono !text-badge font-normal uppercase text-foreground hover:bg-[var(--buzz-welcome-chartreuse)]/40"
-        disabled={runtimesQuery.isFetching}
-        onClick={() => void runtimesQuery.refetch()}
-        type="button"
-        variant="ghost"
-      >
-        {runtimesQuery.isFetching ? "CHECKING…" : "CHECK AGAIN"}
-      </Button>
-    );
-  }
-
-  const installLabel = installError ? "RETRY INSTALL" : "INSTALL";
-  if (runtime.canAutoInstall) {
-    return (
-      <Button
-        aria-label={`${installError ? "Retry installing" : "Install"} ${runtime.label}`}
-        className="buzz-onboarding-runtime-setup h-5 rounded-full bg-[var(--buzz-welcome-chartreuse)]/30 px-2.5 font-mono !text-badge font-normal uppercase text-foreground hover:bg-[var(--buzz-welcome-chartreuse)]/40"
-        data-testid={`onboarding-runtime-install-${runtime.id}`}
-        onClick={onInstall}
-        type="button"
-        variant="ghost"
-      >
-        {installLabel}
-      </Button>
-    );
-  }
-
   return (
-    <Button
-      aria-label={`View ${runtime.label} install instructions`}
-      className="buzz-onboarding-runtime-setup h-5 rounded-full bg-[var(--buzz-welcome-chartreuse)]/30 px-2.5 font-mono !text-badge font-normal uppercase text-foreground hover:bg-[var(--buzz-welcome-chartreuse)]/40"
-      data-testid={`onboarding-runtime-instructions-${runtime.id}`}
-      onClick={() => void openUrl(runtime.installInstructionsUrl)}
-      type="button"
-      variant="ghost"
-    >
-      INSTALL
-    </Button>
-  );
-}
-
-function RuntimeDetails({ runtime }: { runtime: AcpRuntimeCatalogEntry }) {
-  if (
-    runtime.availability === "available" &&
-    runtime.command &&
-    runtime.binaryPath
-  ) {
-    const description = describeResolvedCommand(
-      runtime.command,
-      runtime.binaryPath,
-    );
-    return (
-      <>
-        <p className="text-xs leading-4 text-white">
-          {description.charAt(0).toUpperCase() + description.slice(1)}
-        </p>
-        {runtime.defaultArgs.length > 0 ? (
-          <p className="mt-1 text-xs leading-4 text-white">
-            Args:{" "}
-            <code className="font-mono">{runtime.defaultArgs.join(", ")}</code>
-          </p>
-        ) : null}
-      </>
-    );
-  }
-
-  if (runtime.availability === "adapter_missing") {
-    return (
-      <>
-        <p className="text-xs leading-4 text-white">
-          CLI detected; ACP adapter missing.
-        </p>
-        <p className="mt-1 text-xs leading-4 text-white">
-          {runtime.installHint}
-        </p>
-      </>
-    );
-  }
-
-  if (runtime.availability === "adapter_outdated") {
-    return (
-      <>
-        <p className="text-xs leading-4 text-white">
-          ACP adapter detected but outdated — reinstall required.
-        </p>
-        <p className="mt-1 text-xs leading-4 text-white">
-          This updates the machine-global{" "}
-          <code className="rounded bg-white/10 px-0.5 font-mono text-xs text-white">
-            codex-acp
-          </code>{" "}
-          adapter. Older Buzz releases using the legacy adapter contract may
-          lose community access until{" "}
-          <code className="rounded bg-white/10 px-0.5 font-mono text-xs text-white">
-            @zed-industries/codex-acp@0.16.0
-          </code>{" "}
-          is restored.
-        </p>
-        <p className="mt-1 text-xs leading-4 text-white">
-          {runtime.installHint}
-        </p>
-      </>
-    );
-  }
-
-  if (runtime.availability === "cli_missing") {
-    return (
-      <>
-        <p className="text-xs leading-4 text-white">
-          ACP adapter detected; CLI missing.
-        </p>
-        <p className="mt-1 text-xs leading-4 text-white">
-          {runtime.installHint}
-        </p>
-      </>
-    );
-  }
-
-  return (
-    <>
-      <p className="text-xs leading-4 text-white">Not installed yet.</p>
-      <p className="mt-1 text-xs leading-4 text-white">{runtime.installHint}</p>
-    </>
-  );
-}
-
-function runtimeDetailText(runtime: AcpRuntimeCatalogEntry): string {
-  if (
-    runtime.availability === "available" &&
-    runtime.command &&
-    runtime.binaryPath
-  ) {
-    const description = describeResolvedCommand(
-      runtime.command,
-      runtime.binaryPath,
-    );
-    return description.charAt(0).toUpperCase() + description.slice(1);
-  }
-  if (runtime.availability === "adapter_missing") {
-    return "CLI detected; ACP adapter missing.";
-  }
-  if (runtime.availability === "adapter_outdated") {
-    return "ACP adapter detected but outdated — reinstall required.";
-  }
-  if (
-    runtime.availability === "cli_missing" ||
-    runtime.availability === "not_installed"
-  ) {
-    return "CLI not detected.";
-  }
-  return "";
-}
-
-function isSupportedOnboardingAuthMethod(
-  runtime: AcpRuntimeCatalogEntry,
-  method: AcpAuthMethod,
-) {
-  if (runtime.id !== "codex") return true;
-  return !/api[-_ ]?key/i.test(`${method.id} ${method.name}`);
-}
-
-function isPreferredClaudeAuthMethod(method: AcpAuthMethod) {
-  const haystack = [
-    method.id,
-    method.name,
-    method.description ?? "",
-    method.command.join(" "),
-    method.args.join(" "),
-  ]
-    .join(" ")
-    .toLowerCase();
-  return (
-    haystack.includes("claudeai") ||
-    haystack.includes("claude ai") ||
-    haystack.includes("claude.ai") ||
-    haystack.includes("subscription")
-  );
-}
-
-function getOnboardingAuthMethods(
-  runtime: AcpRuntimeCatalogEntry,
-  methods: AcpAuthMethod[],
-) {
-  const supported = methods.filter((method) =>
-    isSupportedOnboardingAuthMethod(runtime, method),
-  );
-
-  if (runtime.id === "claude") {
-    const preferred =
-      supported.find(isPreferredClaudeAuthMethod) ?? supported[0];
-    return preferred ? [preferred] : [];
-  }
-
-  if (runtime.id === "codex") {
-    return supported.slice(0, 1);
-  }
-
-  return supported;
-}
-
-function RuntimeAuthError({ runtime }: { runtime: AcpRuntimeCatalogEntry }) {
-  if (runtime.authStatus.status === "config_invalid") {
-    return (
-      <RuntimeErrorTooltip
-        className="absolute inset-x-3 bottom-2 truncate text-xs leading-4 text-destructive"
-        detail="Check this runtime’s configuration and try again."
-        label="Configuration invalid"
-      />
-    );
-  }
-  if (
-    runtime.availability === "available" &&
-    runtime.authStatus.status === "unknown"
-  ) {
-    return (
-      <RuntimeErrorTooltip
-        className="absolute inset-x-3 bottom-2 truncate text-xs leading-4 text-destructive"
-        detail="Couldn’t verify authentication."
-        label="Status unavailable"
-      />
-    );
-  }
-  return null;
-}
-
-function RuntimeCard({
-  installResults,
-  onInstallResultsChange,
-  runtime,
-}: {
-  installResults: InstallResultsState;
-  onInstallResultsChange: React.Dispatch<
-    React.SetStateAction<InstallResultsState>
-  >;
-  runtime: AcpRuntimeCatalogEntry;
-}) {
-  // Each card owns its own mutation instance so concurrent installs on
-  // different cards each track their own isPending state and callbacks
-  // independently (react-query v5 per-mutate callbacks only fire for the
-  // latest mutate() call on a shared instance, silently dropping earlier ones).
-  const installMutation = useInstallAcpRuntimeMutation();
-  const installError = installResults[runtime.id]?.error ?? null;
-  const isInstalling = installMutation.isPending;
-  const isAvailable = runtime.availability === "available";
-  const isReady = runtimeIsReadyForOnboarding(runtime);
-
-  function handleInstall() {
-    onInstallResultsChange((current) => ({
-      ...current,
-      [runtime.id]: { error: null, success: false },
-    }));
-
-    installMutation.mutate(runtime.id, {
-      onSuccess: (result) => {
-        onInstallResultsChange((current) => ({
-          ...current,
-          [runtime.id]: result.success
-            ? { error: null, success: true }
-            : {
-                error: getInstallErrorMessage(result.steps),
-                success: false,
-              },
-        }));
-      },
-      onError: (error) => {
-        onInstallResultsChange((current) => ({
-          ...current,
-          [runtime.id]: {
-            error: error instanceof Error ? error.message : "Install failed.",
-            success: false,
-          },
-        }));
-      },
-    });
-  }
-
-  return (
-    <Card
+    <div
       className={cn(
-        "group h-[224px] w-full max-w-[288px] select-none items-center px-3 py-1.5 text-center",
-        installError && "ring-1 ring-destructive/40",
-        isReady && "brightness-[0.98]",
+        "relative w-full max-w-[288px] transition-opacity duration-200",
+        dimmed && "pointer-events-none opacity-0",
       )}
-      data-ready={isReady ? "true" : "false"}
-      data-testid={`onboarding-runtime-${runtime.id}`}
-      variant="textured"
     >
-      <RuntimeReadinessIndicator ready={isReady} runtime={runtime} />
-
-      <div className="flex min-w-0 flex-col items-center gap-2.5">
-        <div className="flex min-w-0 items-center justify-center gap-3">
-          <RuntimeIcon className="h-7 w-7" runtime={runtime} />
-          <h2 className="truncate text-sm font-normal leading-5 text-foreground">
-            {getRuntimeDisplayLabel(runtime)}
-          </h2>
-        </div>
-        <RuntimeStatus
-          installError={installError}
-          isInstalling={isInstalling}
-          onInstall={handleInstall}
-          runtime={runtime}
-        />
-        {!isAvailable && runtimeDetailText(runtime) ? (
-          <p
-            aria-hidden={installError ? "true" : undefined}
-            className={cn(
-              "max-w-[13rem] text-2xs leading-4 text-muted-foreground",
-              installError && "invisible",
-            )}
-          >
-            {runtimeDetailText(runtime)}
-          </p>
-        ) : null}
-      </div>
-      {installError ? (
-        <RuntimeErrorTooltip
-          className="absolute inset-x-3 bottom-2 flex min-w-0 items-center justify-center gap-1.5 overflow-hidden whitespace-nowrap text-xs leading-4 text-destructive"
-          detail={installError}
-          label="Installation failed"
-          showIcon
-          testId={`onboarding-runtime-error-${runtime.id}`}
-        />
-      ) : (
-        <RuntimeAuthError runtime={runtime} />
-      )}
-    </Card>
+      <HarnessChoiceCard
+        aria-pressed={selected}
+        className="cursor-pointer transition duration-150 hover:-translate-y-0.5 hover:brightness-[0.98] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-foreground/35"
+        data-selected={selected ? "true" : "false"}
+        data-testid={`onboarding-runtime-${runtime.id}`}
+        onClick={onChoose}
+        onKeyDown={(event) => {
+          if (event.key !== "Enter" && event.key !== " ") return;
+          event.preventDefault();
+          onChoose();
+        }}
+        role="button"
+        runtime={runtime}
+        tabIndex={0}
+      />
+    </div>
   );
 }
 
@@ -588,40 +100,45 @@ function RuntimeProvidersLoadingState() {
 }
 
 function RuntimeProvidersSection({
-  installResults,
-  onInstallResultsChange,
+  onChooseRuntime,
+  pendingRuntimeId,
   runtimeProviders,
+  selectedRuntimeId,
 }: {
-  installResults: InstallResultsState;
-  onInstallResultsChange: React.Dispatch<
-    React.SetStateAction<InstallResultsState>
-  >;
+  onChooseRuntime: (runtimeId: string) => void;
+  pendingRuntimeId: string | null;
   runtimeProviders: SetupStepState["runtimeProviders"];
+  selectedRuntimeId: string | null;
 }) {
   const { errorMessage, isChecking, items } = runtimeProviders;
   const orderedItems = getVisibleOnboardingRuntimes(items);
+  const highlightedRuntimeId = pendingRuntimeId ?? selectedRuntimeId;
 
   return (
     <section className="flex min-h-full w-full flex-col items-center">
       <div className="w-full max-w-[820px] text-center">
         <h1 className="text-title font-normal text-foreground">
-          Set up your agent harnesses
+          Choose your default harness
         </h1>
-        <p className="mx-auto mt-3 max-w-[760px] text-sm leading-6 text-foreground/90">
-          Buzz checks for command-line harnesses on this machine. Install the
-          CLI or sign in to at least one to continue.
+        <p className="mx-auto mt-3 max-w-[640px] text-sm leading-6 text-foreground/90">
+          Pick the harness Buzz should use by default. You can always connect
+          and add more harnesses later in Settings.
         </p>
       </div>
 
-      <div className="flex w-full flex-1 flex-col items-center justify-center gap-8 py-10">
+      <div className="flex w-full flex-1 flex-col items-center justify-center gap-8 py-6 [@media(max-height:560px)]:py-2">
         {orderedItems.length > 0 ? (
-          <div className="grid min-w-0 w-full max-w-[1200px] grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-4">
+          // 4-across from md so the grid fits the 800×500 minimum window
+          // without scrolling under the docked footer (cards shrink below
+          // their 288px max); single column only on very narrow layouts.
+          <div className="grid min-w-0 w-full max-w-[1200px] grid-cols-1 justify-items-center gap-4 md:grid-cols-4">
             {orderedItems.map((runtime) => (
-              <RuntimeCard
-                installResults={installResults}
+              <RuntimeChoiceCard
+                dimmed={pendingRuntimeId !== null}
                 key={runtime.id}
-                onInstallResultsChange={onInstallResultsChange}
+                onChoose={() => onChooseRuntime(runtime.id)}
                 runtime={runtime}
+                selected={runtime.id === highlightedRuntimeId}
               />
             ))}
           </div>
@@ -632,8 +149,8 @@ function RuntimeProvidersSection({
             className="max-w-[560px] rounded-2xl bg-white/70 px-6 py-6 text-sm text-muted-foreground"
             data-testid="onboarding-acp-empty"
           >
-            No supported command-line harnesses were detected yet. Install a
-            supported CLI, then check again.
+            No supported agent harnesses were detected yet. You can finish
+            onboarding now and connect a harness later in Settings.
           </p>
         )}
 
@@ -650,55 +167,57 @@ function RuntimeProvidersSection({
 function SetupStepContent({
   actions,
   direction,
-  onReadyRuntimeIdsChange,
+  selectedRuntimeId,
   state,
 }: SetupStepContentProps) {
-  const { runtimeProviders } = state;
-  const [installResults, setInstallResults] =
-    React.useState<InstallResultsState>({});
-  const readyRuntimeIds = React.useMemo(
-    () =>
-      getReadyOnboardingRuntimes(runtimeProviders.items).map(
-        (runtime) => runtime.id,
-      ),
-    [runtimeProviders.items],
+  const shouldReduceMotion = useReducedMotion() ?? false;
+  const [pendingRuntimeId, setPendingRuntimeId] = React.useState<string | null>(
+    null,
+  );
+
+  // Card click: fade the unselected cards out, then advance into the setup
+  // page's vanilla fade.
+  const chooseRuntime = React.useCallback(
+    (runtimeId: string) => {
+      if (pendingRuntimeId) return;
+      if (shouldReduceMotion) {
+        actions.next(runtimeId);
+        return;
+      }
+      setPendingRuntimeId(runtimeId);
+    },
+    [actions, pendingRuntimeId, shouldReduceMotion],
   );
-  const readyRuntimeIdsKey = readyRuntimeIds.join("\0");
-  // The key prevents catalog object refreshes from creating an effect loop
-  // when the detected ready IDs have not changed.
-  // biome-ignore lint/correctness/useExhaustiveDependencies: keyed by ID content
+
   React.useEffect(() => {
-    onReadyRuntimeIdsChange(readyRuntimeIds);
-  }, [onReadyRuntimeIdsChange, readyRuntimeIdsKey]);
+    if (!pendingRuntimeId) return;
+    const timeout = window.setTimeout(
+      () => actions.next(pendingRuntimeId),
+      CHOICE_FADE_MS,
+    );
+    return () => window.clearTimeout(timeout);
+  }, [actions, pendingRuntimeId]);
 
   return (
     <OnboardingSlideTransition
       className="flex min-h-full w-full flex-col items-center"
       data-testid="onboarding-page-2"
       direction={direction}
+      effect="fade"
       transitionKey={`setup-${direction}`}
     >
       <RuntimeProvidersSection
-        installResults={installResults}
-        onInstallResultsChange={setInstallResults}
-        runtimeProviders={runtimeProviders}
+        onChooseRuntime={chooseRuntime}
+        pendingRuntimeId={pendingRuntimeId}
+        runtimeProviders={state.runtimeProviders}
+        selectedRuntimeId={selectedRuntimeId}
       />
 
       <OnboardingFooter>
-        <Button
-          className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
-          data-testid="onboarding-setup-next"
-          disabled={readyRuntimeIds.length === 0}
-          onClick={() => actions.next(readyRuntimeIds)}
-          type="button"
-        >
-          Next
-        </Button>
-
         <Button
           className="h-9 rounded-full bg-foreground/10 px-6 text-sm hover:bg-foreground/15"
           data-testid="onboarding-setup-skip"
-          onClick={() => actions.next([])}
+          onClick={actions.skip}
           type="button"
           variant="ghost"
         >
@@ -739,7 +258,7 @@ function SetupStepContent({
 export function SetupStep({
   actions,
   direction,
-  onReadyRuntimeIdsChange,
+  selectedRuntimeId,
 }: SetupStepProps) {
   const state = useSetupStepState();
 
@@ -747,7 +266,7 @@ export function SetupStep({
     <SetupStepContent
       actions={actions}
       direction={direction}
-      onReadyRuntimeIdsChange={onReadyRuntimeIdsChange}
+      selectedRuntimeId={selectedRuntimeId}
       state={state}
     />
   );
diff --git a/desktop/src/features/onboarding/ui/types.ts b/desktop/src/features/onboarding/ui/types.ts
index 443a1f3f4e7..94b0d0ff32f 100644
--- a/desktop/src/features/onboarding/ui/types.ts
+++ b/desktop/src/features/onboarding/ui/types.ts
@@ -58,7 +58,8 @@ export type ProfileStepActions = {
 
 export type SetupStepActions = {
   back: () => void;
-  next: (readyRuntimeIds: readonly string[]) => void;
+  next: (runtimeId: string) => void;
+  skip: () => void;
   navigateToAgentSettings?: () => void;
 };
 
diff --git a/desktop/src/testing/e2eBridge.ts b/desktop/src/testing/e2eBridge.ts
index 7b13273c602..f88d08cc6da 100644
--- a/desktop/src/testing/e2eBridge.ts
+++ b/desktop/src/testing/e2eBridge.ts
@@ -190,6 +190,8 @@ type E2eConfig = {
     acpRuntimesCatalogAfterInstallSequence?: RawAcpRuntimeCatalogEntry[][];
     /** Catalog responses for successive discovery calls. The final response repeats. */
     acpRuntimesCatalogSequence?: RawAcpRuntimeCatalogEntry[][];
+    /** Sequenced discovery failures. Null succeeds; a string throws. */
+    acpRuntimesErrors?: (string | null)[];
     acpRuntimesDelayMs?: number;
     acpAuthMethods?: Record<string, RawAcpAuthMethodsResult>;
     acpAuthMethodsErrors?: Record<string, string>;
@@ -10416,8 +10418,11 @@ export function maybeInstallE2eTauriMocks() {
         return getRelayHttpUrl(activeConfig);
       case "relay_requires_membership":
         return activeConfig?.mock?.relayRequiresMembership ?? false;
-      case "discover_acp_providers":
+      case "discover_acp_providers": {
+        const error = activeConfig?.mock?.acpRuntimesErrors?.shift();
+        if (error) throw new Error(error);
         return handleDiscoverAcpRuntimes(activeConfig);
+      }
       case "save_custom_harness":
         return handleSaveCustomHarness(
           payload as Parameters<typeof handleSaveCustomHarness>[0],
diff --git a/desktop/tests/e2e/onboarding-agent-defaults.spec.ts b/desktop/tests/e2e/onboarding-agent-defaults.spec.ts
index dbd726d1792..8213b652dac 100644
--- a/desktop/tests/e2e/onboarding-agent-defaults.spec.ts
+++ b/desktop/tests/e2e/onboarding-agent-defaults.spec.ts
@@ -35,7 +35,7 @@ function runtime(
   };
 }
 
-async function navigateToSetupPage(
+async function navigateToChooserPage(
   page: Parameters<typeof installMockBridge>[0],
 ) {
   await page.getByRole("button", { name: "Create a new identity key" }).click();
@@ -57,7 +57,9 @@ async function readSavedRuntime(page: Parameters<typeof installMockBridge>[0]) {
   });
 }
 
-test("setup shows all bundled harnesses as detected", async ({ page }) => {
+test("chooser shows all bundled harnesses without setup controls", async ({
+  page,
+}) => {
   await installMockBridge(
     page,
     {
@@ -71,47 +73,51 @@ test("setup shows all bundled harnesses as detected", async ({ page }) => {
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
+  await navigateToChooserPage(page);
 
+  await expect(page.getByText("Choose your default harness")).toBeVisible();
+  await expect(
+    page.getByText(/connect and add more harnesses later/i),
+  ).toBeVisible();
   await expect(page.getByTestId("onboarding-runtime-claude")).toBeVisible();
   await expect(page.getByTestId("onboarding-runtime-codex")).toBeVisible();
   await expect(page.getByTestId("onboarding-runtime-goose")).toBeVisible();
   await expect(page.getByTestId("onboarding-runtime-buzz-agent")).toBeVisible();
-  await expect(page.getByRole("checkbox")).toHaveCount(0);
+  await expect(page.getByText("READY")).toHaveCount(0);
+  await expect(page.getByRole("button", { name: /install/i })).toHaveCount(0);
+  await expect(page.getByRole("button", { name: /sign in/i })).toHaveCount(0);
+  await expect(page.getByTestId("onboarding-setup-next")).toHaveCount(0);
+  expect(await readSavedRuntime(page)).toBeNull();
 });
 
-test("setup distinguishes a missing CLI from an installed desktop app", async ({
+test("Skip for now completes onboarding without saving a default", async ({
   page,
 }) => {
   await installMockBridge(
     page,
     {
       acpRuntimesCatalog: [
-        runtime(
-          "codex",
-          "not_installed",
-          { status: "unknown" },
-          {
-            install_hint: "Buzz talks to Codex through the Codex CLI.",
-            install_instructions_url:
-              "https://developers.openai.com/codex/cli/",
-          },
-        ),
+        runtime("claude", "available", { status: "logged_in" }),
+        runtime("codex", "available", { status: "logged_in" }),
       ],
+      globalAgentConfig: {
+        env_vars: {},
+        provider: null,
+        model: null,
+        preferred_runtime: null,
+      },
     },
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
+  await navigateToChooserPage(page);
 
-  const card = page.getByTestId("onboarding-runtime-codex");
-  await expect(card).toContainText("CLI not detected.");
-  await expect(card.getByTestId("onboarding-runtime-install-codex")).toHaveText(
-    "INSTALL",
-  );
+  await page.getByTestId("onboarding-setup-skip").click();
+  await expect(page.getByText("Join or create a community")).toBeVisible();
+  expect(await readSavedRuntime(page)).toBeNull();
 });
 
-test("ready state is detected and enables Next without persisting a default", async ({
+test("card click is local, advances to setup, and Finish persists the default", async ({
   page,
 }) => {
   await installMockBridge(
@@ -119,174 +125,95 @@ test("ready state is detected and enables Next without persisting a default", as
     {
       acpRuntimesCatalog: [
         runtime("claude", "available", { status: "logged_in" }),
-        runtime("codex", "available", { status: "logged_out" }),
+        runtime("codex", "available", { status: "logged_in" }),
       ],
+      globalAgentConfig: {
+        env_vars: {},
+        provider: null,
+        model: null,
+        preferred_runtime: null,
+      },
     },
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
+  await navigateToChooserPage(page);
 
-  await expect(page.getByTestId("onboarding-runtime-ready-claude")).toHaveText(
-    "READY",
+  const chooserCard = page.getByTestId("onboarding-runtime-claude");
+  const chooserBox = await chooserCard.boundingBox();
+  await chooserCard.click();
+  await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
+  await expect(page.getByText("Set up Claude Code")).toBeVisible();
+  const setupCard = page.getByTestId("onboarding-selected-runtime-card");
+  const setupBox = await setupCard.boundingBox();
+  expect(chooserBox).not.toBeNull();
+  expect(setupBox).not.toBeNull();
+  expect(Math.round(setupBox?.width ?? 0)).toBe(
+    Math.round(chooserBox?.width ?? 0),
+  );
+  expect(Math.round(setupBox?.height ?? 0)).toBe(
+    Math.round(chooserBox?.height ?? 0),
   );
-  await expect(
-    page.getByTestId("onboarding-runtime-checkmark-claude"),
-  ).toHaveCount(0);
-  await expect(
-    page.getByTestId("onboarding-runtime-checkmark-codex"),
-  ).toHaveCount(0);
-  await expect(page.getByTestId("onboarding-setup-next")).toBeEnabled();
   expect(await readSavedRuntime(page)).toBeNull();
+
+  await page.getByTestId("onboarding-finish").click();
+  await expect(page.getByText("Join or create a community")).toBeVisible();
+  expect(await readSavedRuntime(page)).toBe("claude");
 });
 
-test("setup shows runtime discovery loading before rendering harnesses", async ({
-  page,
-}) => {
+test("Back returns to chooser with the pick remembered", async ({ page }) => {
   await installMockBridge(
     page,
     {
       acpRuntimesCatalog: [
         runtime("claude", "available", { status: "logged_in" }),
+        runtime("codex", "available", { status: "logged_in" }),
       ],
-      acpRuntimesDelayMs: 500,
     },
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
+  await navigateToChooserPage(page);
 
-  await expect(page.getByTestId("onboarding-runtime-loading")).toBeVisible();
-  await expect(page.getByTestId("onboarding-runtime-claude")).toBeVisible();
-  await expect(page.getByTestId("onboarding-runtime-loading")).toHaveCount(0);
-});
-
-test("unknown authentication can be checked again", async ({ page }) => {
-  const unknown = runtime("claude", "available", { status: "unknown" });
-  const loggedIn = runtime("claude", "available", { status: "logged_in" });
-  await installMockBridge(
-    page,
-    { acpRuntimesCatalogSequence: [[unknown], [loggedIn]] },
-    { skipCommunitySeed: true, skipOnboardingSeed: true },
-  );
-  await page.goto("/");
-  await navigateToSetupPage(page);
-
-  const checkAgain = page.getByRole("button", {
-    name: "Check Claude Code again",
-  });
-  await expect(checkAgain).toHaveText("CHECK AGAIN");
-  await checkAgain.click();
-  await expect(page.getByTestId("onboarding-runtime-ready-claude")).toHaveText(
-    "READY",
+  await page.getByTestId("onboarding-runtime-codex").click();
+  // Card click fades the unselected cards before advancing — wait for the
+  // setup page so Back targets it rather than the chooser.
+  await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
+  await page.getByTestId("onboarding-back").click();
+  await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
+  await expect(page.getByTestId("onboarding-runtime-codex")).toHaveAttribute(
+    "data-selected",
+    "true",
   );
 });
 
-test("auth discovery failure stays actionable without exposing internals", async ({
+test("Back returns to choose a different harness; last click wins", async ({
   page,
 }) => {
   await installMockBridge(
     page,
     {
       acpRuntimesCatalog: [
-        runtime("claude", "available", { status: "logged_out" }),
-      ],
-      acpAuthMethodsError: "sensitive auth discovery details",
-    },
-    { skipCommunitySeed: true, skipOnboardingSeed: true },
-  );
-  await page.goto("/");
-  await navigateToSetupPage(page);
-
-  const card = page.getByTestId("onboarding-runtime-claude");
-  await expect(
-    card.getByRole("status", { name: /Sign-in unavailable/ }),
-  ).toBeVisible();
-  await expect(
-    card.getByTestId("onboarding-runtime-instructions-claude"),
-  ).toHaveText("SIGN IN");
-  await expect(card).not.toContainText("sensitive auth discovery details");
-});
-
-test("terminal launch failure keeps Sign in available", async ({ page }) => {
-  await installMockBridge(
-    page,
-    {
-      acpRuntimesCatalog: [
-        runtime("claude", "available", { status: "logged_out" }),
+        runtime("claude", "available", { status: "logged_in" }),
+        runtime("codex", "available", { status: "logged_in" }),
       ],
-      acpAuthMethods: {
-        claude: {
-          methods: [
-            {
-              id: "subscription",
-              name: "Claude.ai subscription",
-              description: null,
-              type: "terminal",
-            },
-          ],
-        },
-      },
-      connectAcpRuntimeError: "sensitive launch details",
-    },
-    { skipCommunitySeed: true, skipOnboardingSeed: true },
-  );
-  await page.goto("/");
-  await navigateToSetupPage(page);
-
-  const card = page.getByTestId("onboarding-runtime-claude");
-  const signIn = card.getByRole("button", { name: "Sign in to Claude Code" });
-  await signIn.click();
-  await expect(
-    card.getByRole("status", { name: /Sign-in failed/ }),
-  ).toBeVisible();
-  await expect(signIn).toHaveText("SIGN IN");
-  await expect(card).not.toContainText("sensitive launch details");
-});
-
-test("sign in stays pending until catalog detection confirms Ready", async ({
-  page,
-}) => {
-  const loggedOut = runtime("claude", "available", { status: "logged_out" });
-  const loggedIn = runtime("claude", "available", { status: "logged_in" });
-  await installMockBridge(
-    page,
-    {
-      acpRuntimesCatalogSequence: [[loggedOut], [loggedOut], [loggedIn]],
-      acpAuthMethods: {
-        claude: {
-          methods: [
-            {
-              id: "subscription",
-              name: "Claude.ai subscription",
-              description: null,
-              type: "terminal",
-            },
-          ],
-        },
-      },
     },
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
+  await navigateToChooserPage(page);
 
-  const signIn = page.getByRole("button", { name: "Sign in to Claude Code" });
-  await expect(signIn).toHaveText("SIGN IN");
-  await expect(page.getByTestId("onboarding-setup-next")).toBeDisabled();
-  await signIn.click();
-  await expect(signIn).toHaveText("CHECKING…");
-  await expect(page.getByTestId("onboarding-setup-next")).toBeDisabled();
-  await expect(page.getByTestId("onboarding-runtime-ready-claude")).toHaveText(
-    "READY",
-    { timeout: 5_000 },
-  );
-  await expect(page.getByTestId("onboarding-setup-next")).toBeEnabled();
+  await page.getByTestId("onboarding-runtime-claude").click();
+  await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
+  await page.getByTestId("onboarding-back").click();
+  await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
+  await page.getByTestId("onboarding-runtime-codex").click();
+  await page.getByTestId("onboarding-finish").click();
+  await expect(page.getByText("Join or create a community")).toBeVisible();
+  expect(await readSavedRuntime(page)).toBe("codex");
 });
 
-test("failed install can be retried without shifting card content", async ({
-  page,
-}) => {
+test("selected setup handles install before Finish", async ({ page }) => {
   const notInstalled = runtime("claude", "adapter_missing", {
     status: "unknown",
   });
@@ -329,40 +256,72 @@ test("failed install can be retried without shifting card content", async ({
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-claude").click();
 
-  const card = page.getByTestId("onboarding-runtime-claude");
-  const heading = card.getByRole("heading", { name: "Claude Code" });
-  const headingTop = await heading.evaluate(
-    (element) => element.getBoundingClientRect().top,
-  );
   const install = page.getByTestId("onboarding-runtime-install-claude");
+  await expect(page.getByTestId("onboarding-finish")).toBeDisabled();
   await install.click();
-  const error = page.getByTestId("onboarding-runtime-error-claude");
-  await expect(error).toBeVisible();
-  await expect(install).toHaveText("RETRY INSTALL");
-  await expect(error).not.toContainText("sensitive install details");
-  expect(
-    await heading.evaluate((element) => element.getBoundingClientRect().top),
-  ).toBe(headingTop);
+  const installError = page.getByTestId("onboarding-runtime-error-claude");
+  await expect(installError).toBeVisible();
+  await expect(installError).not.toContainText("sensitive install details");
+  await expect(install).toHaveText("Retry install");
   await install.click();
-  await expect(page.getByTestId("onboarding-runtime-ready-claude")).toHaveText(
-    "READY",
-  );
+  await expect(page.getByText(/Claude Code is ready/i)).toBeVisible();
+  await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
 });
 
-test("install transitions through Sign in to Ready", async ({ page }) => {
+test("post-install catalog failure stays retryable without exposing internals", async ({
+  page,
+}) => {
   const notInstalled = runtime("claude", "adapter_missing", {
     status: "unknown",
   });
+  await installMockBridge(
+    page,
+    {
+      acpRuntimesCatalog: [notInstalled],
+      acpRuntimesErrors: [
+        null,
+        ...Array.from({ length: 4 }, () => "sensitive catalog details"),
+      ],
+      installAcpRuntimeResult: {
+        success: true,
+        steps: [
+          {
+            step: "adapter",
+            command: "mock install claude",
+            success: true,
+            stdout: "installed",
+            stderr: "",
+            exit_code: 0,
+          },
+        ],
+      },
+    },
+    { skipCommunitySeed: true, skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-claude").click();
+  await page.getByTestId("onboarding-runtime-install-claude").click();
+
+  await expect(
+    page.getByText("Couldn't load harness settings. Try again."),
+  ).toBeVisible();
+  await expect(page.getByRole("button", { name: "Try again" })).toBeVisible();
+  await expect(page.getByTestId("onboarding-page-config")).not.toContainText(
+    "sensitive catalog details",
+  );
+});
+
+test("selected setup handles sign-in before Finish", async ({ page }) => {
   const loggedOut = runtime("claude", "available", { status: "logged_out" });
   const loggedIn = runtime("claude", "available", { status: "logged_in" });
   await installMockBridge(
     page,
     {
-      acpRuntimesCatalog: [notInstalled],
-      acpRuntimesCatalogAfterInstallSequence: [[loggedOut], [loggedIn]],
-      installAcpRuntimeDelayMs: 500,
+      acpRuntimesCatalogSequence: [[loggedOut], [loggedOut], [loggedIn]],
       acpAuthMethods: {
         claude: {
           methods: [
@@ -379,243 +338,265 @@ test("install transitions through Sign in to Ready", async ({ page }) => {
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
-
-  const install = page.getByTestId("onboarding-runtime-install-claude");
-  await expect(install).toHaveText("INSTALL");
-  await install.click();
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-claude").click();
 
   const signIn = page.getByRole("button", { name: "Sign in to Claude Code" });
-  await expect(signIn).toHaveText("SIGN IN");
-  await expect(page.getByTestId("onboarding-setup-next")).toBeDisabled();
+  await expect(page.getByTestId("onboarding-finish")).toBeDisabled();
   await signIn.click();
-  await expect(page.getByTestId("onboarding-runtime-ready-claude")).toHaveText(
-    "READY",
-    { timeout: 5_000 },
-  );
-  await expect(
-    page.getByTestId("onboarding-runtime-checkmark-claude"),
-  ).toHaveCount(0);
+  await expect(signIn).toHaveText("Checking…");
+  await expect(page.getByText(/Claude Code is ready/i)).toBeVisible({
+    timeout: 5_000,
+  });
+  await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
 });
 
-test("defaults waits for baked configuration before rendering fields", async ({
-  page,
-}) => {
+test("Claude preserves API-key auth methods from main", async ({ page }) => {
   await installMockBridge(
     page,
     {
       acpRuntimesCatalog: [
-        runtime("claude", "available", { status: "logged_in" }),
-      ],
-      bakedBuildEnv: [
-        { key: "ANTHROPIC_API_KEY", masked: true, value: "••••••" },
+        runtime("claude", "available", { status: "logged_out" }),
       ],
-      bakedBuildEnvDelayMs: 500,
+      acpAuthMethods: {
+        claude: {
+          methods: [
+            {
+              id: "api-key",
+              name: "API key",
+              description: null,
+              type: "terminal",
+            },
+          ],
+        },
+      },
+      connectAcpRuntimeResult: { launched: true },
     },
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
-  await page.getByTestId("onboarding-setup-next").click();
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-claude").click();
 
-  await expect(page.getByText("Loading…")).toBeVisible();
-  await expect(page.getByTestId("global-agent-default-harness")).toHaveText(
-    "Claude Code",
-  );
+  const signIn = page.getByRole("button", { name: "Sign in to Claude Code" });
+  await expect(signIn).toBeEnabled();
+  await signIn.click();
+  await expect(signIn).toHaveText("Checking…");
 });
 
-test("defaults renders only fields supported by the selected harness", async ({
+test("sign-in failures stay actionable without exposing internals", async ({
   page,
 }) => {
   await installMockBridge(
     page,
     {
       acpRuntimesCatalog: [
-        runtime("claude", "available", { status: "logged_in" }),
+        runtime("claude", "available", { status: "logged_out" }),
       ],
-      globalAgentConfig: {
-        env_vars: { BUZZ_AGENT_THINKING_EFFORT: "high" },
-        provider: null,
-        model: "stale-model",
-        preferred_runtime: null,
+      acpAuthMethods: {
+        claude: {
+          methods: [
+            {
+              id: "subscription",
+              name: "Claude.ai subscription",
+              description: null,
+              type: "terminal",
+            },
+          ],
+        },
       },
+      connectAcpRuntimeError: "sensitive launch details",
     },
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
-  await page.getByTestId("onboarding-setup-next").click();
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-claude").click();
 
-  await expect(page.getByTestId("global-agent-default-harness")).toHaveText(
-    "Claude Code",
-  );
-  await expect(page.getByTestId("global-agent-provider")).toHaveCount(0);
-  await expect(page.getByTestId("global-agent-model")).toHaveText(
-    "Default model",
-  );
+  const signIn = page.getByRole("button", { name: "Sign in to Claude Code" });
+  await signIn.click();
   await expect(
-    page.getByTestId("global-agent-thinking-effort-select"),
-  ).toHaveCount(0);
+    page.getByRole("status", { name: /Sign-in failed/ }),
+  ).toBeVisible();
+  await expect(signIn).toHaveText("Sign in");
+  await expect(page.getByTestId("onboarding-page-config")).not.toContainText(
+    "sensitive launch details",
+  );
 });
 
-test("defaults hides model when optional harness has empty discovery", async ({
+test("auth discovery failures stay actionable without exposing internals", async ({
   page,
 }) => {
   await installMockBridge(
     page,
     {
       acpRuntimesCatalog: [
-        runtime("claude", "available", { status: "logged_in" }),
+        runtime("claude", "available", { status: "logged_out" }),
       ],
-      discoverAgentModels: {
-        models: [],
-        supportsSwitching: false,
-      },
-      globalAgentConfig: {
-        env_vars: {},
-        provider: null,
-        model: null,
-        preferred_runtime: null,
-      },
+      acpAuthMethodsError: "sensitive auth discovery details",
     },
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
-  await page.getByTestId("onboarding-setup-next").click();
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-claude").click();
 
-  await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
-  await expect(page.getByTestId("global-agent-default-harness")).toHaveText(
-    "Claude Code",
+  await expect(
+    page.getByRole("status", { name: /Sign-in unavailable/ }),
+  ).toBeVisible();
+  await expect(page.getByTestId("onboarding-page-config")).not.toContainText(
+    "sensitive auth discovery details",
   );
-  // Confirmed successful empty catalog — omit the Model control; harness
-  // default applies and Finish stays available.
-  await expect(page.getByTestId("global-agent-model")).toHaveCount(0);
+});
+
+test("unknown authentication can be checked again", async ({ page }) => {
+  const unknown = runtime("claude", "available", { status: "unknown" });
+  const loggedIn = runtime("claude", "available", { status: "logged_in" });
+  await installMockBridge(
+    page,
+    { acpRuntimesCatalogSequence: [[unknown], [loggedIn]] },
+    { skipCommunitySeed: true, skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-claude").click();
+
+  const checkAgain = page.getByRole("button", { name: "Check again" });
+  await checkAgain.click();
+  await expect(page.getByText(/Claude Code is ready/i)).toBeVisible();
   await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
 });
 
-test("defaults keeps model control when optional harness discovery fails", async ({
+test("Goose provider setup omits the incompatible Buzz effort control", async ({
   page,
 }) => {
   await installMockBridge(
     page,
     {
       acpRuntimesCatalog: [
-        runtime("claude", "available", { status: "logged_in" }),
+        runtime("goose", "available", { status: "not_applicable" }),
       ],
-      discoverAgentModelsError: "CLI discovery timed out",
-      globalAgentConfig: {
-        env_vars: {},
-        provider: null,
-        model: null,
-        preferred_runtime: null,
-      },
     },
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
-  await page.getByTestId("onboarding-setup-next").click();
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-goose").click();
 
-  await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
-  await expect(page.getByTestId("global-agent-default-harness")).toHaveText(
-    "Claude Code",
-  );
-  // Failed discovery must not look like successful empty: keep the control
-  // and surface #2246 failure UI (status line bypasses onboarding-essential).
+  await expect(page.getByTestId("global-agent-provider")).toBeVisible();
   await expect(page.getByTestId("global-agent-model")).toBeVisible();
-  await expect(page.getByText(/Could not load live models/i)).toBeVisible();
-  await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
+  await expect(
+    page.getByTestId("global-agent-thinking-effort-select"),
+  ).toHaveCount(0);
 });
 
-test("defaults Back returns to harness setup", async ({ page }) => {
+test("Buzz baked defaults do not mark Goose ready", async ({ page }) => {
   await installMockBridge(
     page,
     {
       acpRuntimesCatalog: [
-        runtime("claude", "available", { status: "logged_in" }),
+        runtime("goose", "available", { status: "not_applicable" }),
+      ],
+      bakedBuildEnv: [
+        { key: "BUZZ_AGENT_PROVIDER", masked: false, value: "anthropic" },
+        { key: "BUZZ_AGENT_MODEL", masked: false, value: "claude-sonnet-4" },
+        { key: "ANTHROPIC_API_KEY", masked: true, value: "••••••" },
       ],
     },
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
-  await page.getByTestId("onboarding-setup-next").click();
-  await page.getByTestId("onboarding-back").click();
-  await expect(page.getByTestId("onboarding-page-2")).toBeVisible();
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-goose").click();
+
+  await expect(page.getByTestId("global-agent-provider")).toBeVisible();
+  await expect(page.getByTestId("onboarding-finish")).toBeDisabled();
+  await expect(page.getByText(/Goose is ready/i)).toHaveCount(0);
 });
 
-test("defaults auto-selects the only ready visible harness", async ({
+test("provider setup is skipped when runtime file config already satisfies Goose", async ({
   page,
 }) => {
   await installMockBridge(
     page,
     {
       acpRuntimesCatalog: [
-        runtime("buzz-agent", "not_installed", { status: "not_applicable" }),
-        runtime("goose", "not_installed", { status: "not_applicable" }),
-        runtime("claude", "available", { status: "logged_in" }),
-        runtime("codex", "available", { status: "logged_out" }),
+        runtime("goose", "available", { status: "not_applicable" }),
       ],
-      globalAgentConfig: {
-        env_vars: {},
-        provider: null,
-        model: null,
-        preferred_runtime: null,
+      runtimeFileConfigs: {
+        goose: {
+          provider: "anthropic",
+          model: "claude-sonnet-4",
+          satisfiedEnvKeys: ["ANTHROPIC_API_KEY"],
+        },
       },
     },
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
-  await page.getByTestId("onboarding-setup-next").click();
-  await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-goose").click();
 
-  await expect(page.getByTestId("global-agent-default-harness")).toHaveText(
-    "Claude Code",
-  );
+  await expect(page.getByText(/Goose is ready/i)).toBeVisible();
+  await expect(page.getByTestId("global-agent-provider")).toHaveCount(0);
+  await expect(page.getByTestId("global-agent-model")).toHaveCount(0);
   await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
-  await expect.poll(() => readSavedRuntime(page)).toBe("claude");
 });
 
-test("Finish waits for the latest rapid harness choice to persist", async ({
+test("Buzz Agent provider setup collects defaults before Finish", async ({
   page,
 }) => {
   await installMockBridge(
     page,
     {
       acpRuntimesCatalog: [
-        runtime("claude", "available", { status: "logged_in" }),
-        runtime("codex", "available", { status: "logged_in" }),
+        runtime("buzz-agent", "available", { status: "not_applicable" }),
       ],
+      discoverAgentModels: {
+        models: [
+          {
+            id: "claude-sonnet-4",
+            name: "Claude Sonnet 4",
+          },
+        ],
+        supportsSwitching: true,
+      },
       globalAgentConfig: {
         env_vars: {},
         provider: null,
         model: null,
         preferred_runtime: null,
       },
-      setGlobalAgentConfigDelayMs: 300,
     },
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
-  await page.getByTestId("onboarding-setup-next").click();
-
-  const harness = page.getByTestId("global-agent-default-harness");
-  await harness.click();
-  await page.getByTestId("global-agent-default-harness-option-claude").click();
-  await harness.click();
-  await page.getByTestId("global-agent-default-harness-option-codex").click();
-  const finish = page.getByTestId("onboarding-finish");
-  await expect(finish).toBeDisabled();
-  await expect(finish).toBeEnabled({ timeout: 2_000 });
-  await finish.click();
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-buzz-agent").click();
+
+  await expect(page.getByTestId("global-agent-provider")).toBeVisible();
+  await expect(page.getByTestId("global-agent-model")).toBeVisible();
+  await expect(page.getByTestId("onboarding-finish")).toBeDisabled();
+
+  const provider = page.getByTestId("global-agent-provider");
+  await provider.click();
+  await page.getByTestId("global-agent-provider-option-anthropic").click();
+  await expect(page.getByTestId("global-agent-model")).toBeVisible();
+  await expect(page.getByTestId("onboarding-finish")).toBeDisabled();
+
+  const model = page.getByTestId("global-agent-model");
+  await model.click();
+  await page.getByTestId("global-agent-model-option-claude-sonnet-4").click();
+  await page.getByTestId("persona-provider-api-key").fill("sk-ant-test");
+  await expect(page.getByTestId("global-agent-provider")).toBeVisible();
+  await expect(page.getByTestId("global-agent-model")).toBeVisible();
+  await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
+  await page.getByTestId("onboarding-finish").click();
   await expect(page.getByText("Join or create a community")).toBeVisible();
-  expect(await readSavedRuntime(page)).toBe("codex");
+  expect(await readSavedRuntime(page)).toBe("buzz-agent");
 });
 
-test("defaults requires a choice when multiple visible harnesses are ready", async ({
+test("baked build env satisfies Buzz Agent setup with no manual config", async ({
   page,
 }) => {
   await installMockBridge(
@@ -623,9 +604,11 @@ test("defaults requires a choice when multiple visible harnesses are ready", asy
     {
       acpRuntimesCatalog: [
         runtime("buzz-agent", "available", { status: "not_applicable" }),
-        runtime("goose", "available", { status: "not_applicable" }),
-        runtime("claude", "available", { status: "logged_in" }),
-        runtime("codex", "available", { status: "logged_in" }),
+      ],
+      bakedBuildEnv: [
+        { key: "BUZZ_AGENT_PROVIDER", masked: false, value: "anthropic" },
+        { key: "BUZZ_AGENT_MODEL", masked: false, value: "claude-sonnet-4" },
+        { key: "ANTHROPIC_API_KEY", masked: true, value: "••••••" },
       ],
       globalAgentConfig: {
         env_vars: {},
@@ -637,211 +620,82 @@ test("defaults requires a choice when multiple visible harnesses are ready", asy
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
-  await page.getByTestId("onboarding-setup-next").click();
-  await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-buzz-agent").click();
 
-  const harness = page.getByTestId("global-agent-default-harness");
-  await expect(harness).toHaveText("Select a harness");
-  await expect(page.getByTestId("onboarding-finish")).toBeDisabled();
-  await harness.click();
-  await expect(
-    page.getByTestId("global-agent-default-harness-option-claude"),
-  ).toBeVisible();
-  await expect(
-    page.getByTestId("global-agent-default-harness-option-codex"),
-  ).toBeVisible();
-  await expect(
-    page.getByTestId("global-agent-default-harness-option-goose"),
-  ).toBeVisible();
-  await expect(
-    page.getByTestId("global-agent-default-harness-option-buzz-agent"),
-  ).toBeVisible();
-  await page.getByTestId("global-agent-default-harness-option-codex").click();
-  await expect(harness).toHaveText("Codex");
+  // Internal builds bake provider/model/credential env — setup is skipped
+  // entirely and Finish is immediately available.
+  await expect(page.getByText(/Buzz is ready/i)).toBeVisible();
+  await expect(page.getByTestId("global-agent-provider")).toHaveCount(0);
   await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
-  await expect.poll(() => readSavedRuntime(page)).toBe("codex");
+  await page.getByTestId("onboarding-finish").click();
+  await expect(page.getByText("Join or create a community")).toBeVisible();
+  expect(await readSavedRuntime(page)).toBe("buzz-agent");
 });
 
-/**
- * Two installs started concurrently — claude fails with a multiline error
- * (rich hint+stderr in the tooltip) while codex succeeds. Each card must
- * keep its own independent spinner and its own terminal result; neither card
- * may show the other's outcome.
- *
- * This is the behavioral regression test for the per-card mutation fix
- * (Bug B) and the multiline tooltip fix (Bug A / F3 from Thufir pass 1).
- */
-test("concurrent installs each keep their own state — one fails, one succeeds", async ({
+test("Finish preserves existing values when the selected harness is unchanged", async ({
   page,
 }) => {
-  // Realistic 512-head + 1024-tail shape: many short lines followed by one
-  // long unbroken Windows path.  This exercises both overflow axes:
-  //   • vertical: enough lines to exceed max-h-48 (192px at ~16px/line)
-  //   • horizontal: the long path has no spaces, so only break-words prevents
-  //     scrollWidth > clientWidth.
-  const longWindowsPath =
-    "C:\\Users\\willp\\AppData\\Roaming\\npm\\node_modules\\@agentclientprotocol\\claude-agent-acp\\dist\\bin\\claude-agent-acp.exe";
-  const multilineError = [
-    "npm ERR! code EACCES",
-    "npm ERR! syscall mkdir",
-    "npm ERR! path C:\\Users\\willp\\AppData\\Roaming\\npm",
-    "npm ERR! errno -4048",
-    "npm ERR! Error: EACCES: permission denied, mkdir 'C:\\Users\\willp\\AppData\\Roaming\\npm'",
-    "npm ERR!  { [Error: EACCES: permission denied, mkdir 'C:\\Users\\willp\\AppData\\Roaming\\npm']",
-    "npm ERR!   errno: -4048,",
-    "npm ERR!   code: 'EACCES',",
-    "npm ERR!   syscall: 'mkdir',",
-    "npm ERR!   path: 'C:\\\\Users\\\\willp\\\\AppData\\\\Roaming\\\\npm' }",
-    "npm ERR!",
-    "npm ERR! The operation was rejected by your operating system.",
-    "npm ERR! It is likely you do not have the permissions to access this file as the current user",
-    "npm ERR!",
-    `npm ERR! If you believe this might be a permissions issue, please double-check the`,
-    `npm ERR! permissions of the file and its containing directories, or try running`,
-    `npm ERR! the command again as root/Administrator.`,
-    "",
-    `Hint: Run as Administrator or change npm prefix: npm config set prefix ${longWindowsPath}`,
-  ].join("\n");
-  const claudeNotInstalled = runtime("claude", "adapter_missing", {
-    status: "unknown",
-  });
-  const codexNotInstalled = runtime("codex", "adapter_missing", {
-    status: "unknown",
-  });
   await installMockBridge(
     page,
     {
-      acpRuntimesCatalog: [claudeNotInstalled, codexNotInstalled],
-      // Claude: long delay then failure with multiline stderr + hint.
-      // Codex: short delay then success.
-      // Per-runtime config lets both be in flight simultaneously.
-      installAcpRuntimeByRuntime: {
-        claude: {
-          delayMs: 600,
-          result: {
-            success: false,
-            steps: [
-              {
-                step: "adapter",
-                command: "npm install -g @agentclientprotocol/claude-agent-acp",
-                success: false,
-                stdout: "",
-                stderr: multilineError,
-                exit_code: 1,
-              },
-            ],
-          },
-        },
-        codex: {
-          delayMs: 200,
-          result: {
-            success: true,
-            steps: [
-              {
-                step: "adapter",
-                command: "npm install -g @zed-industries/codex-acp",
-                success: true,
-                stdout: "added 1 package",
-                stderr: "",
-                exit_code: 0,
-              },
-            ],
-          },
+      acpRuntimesCatalog: [
+        runtime("buzz-agent", "available", { status: "not_applicable" }),
+      ],
+      globalAgentConfig: {
+        env_vars: {
+          ANTHROPIC_API_KEY: "sk-existing",
+          BUZZ_AGENT_THINKING_EFFORT: "high",
         },
+        provider: "anthropic",
+        model: "claude-sonnet-4",
+        preferred_runtime: "buzz-agent",
       },
-      acpRuntimesCatalogAfterInstall: [
-        runtime("claude", "adapter_missing", { status: "unknown" }),
-        runtime("codex", "available", { status: "logged_in" }),
-      ],
     },
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
-
-  const claudeInstall = page.getByTestId("onboarding-runtime-install-claude");
-  const codexInstall = page.getByTestId("onboarding-runtime-install-codex");
-
-  // Start both installs before either settles.
-  await claudeInstall.click();
-  await codexInstall.click();
-
-  // While in flight: both install buttons must be absent (no duplicate clicks).
-  await expect(claudeInstall).toHaveCount(0);
-  await expect(codexInstall).toHaveCount(0);
-
-  // Codex settles first (shorter delay): success indicator, no error.
-  await expect(page.getByTestId("onboarding-runtime-ready-codex")).toBeVisible({
-    timeout: 3_000,
-  });
-  await expect(page.getByTestId("onboarding-runtime-error-codex")).toHaveCount(
-    0,
-  );
-
-  // Claude still in flight: its install button must still be absent.
-  await expect(claudeInstall).toHaveCount(0);
-
-  // Claude settles: failure error visible; codex still shows ready (not reset).
-  const claudeError = page.getByTestId("onboarding-runtime-error-claude");
-  await expect(claudeError).toBeVisible({ timeout: 3_000 });
-  await expect(
-    page.getByTestId("onboarding-runtime-ready-codex"),
-  ).toBeVisible();
-  await expect(page.getByTestId("onboarding-runtime-error-codex")).toHaveCount(
-    0,
-  );
-
-  // The error trigger has the full aria-label (label + detail).
-  await expect(claudeError).toHaveAttribute("aria-label", /npm ERR!/);
-  // Open the tooltip and verify the detail span handles overflow correctly:
-  //   • vertical overflow exists and is scrollable (max-h-48 + overflow-y-auto)
-  //   • no horizontal overflow (break-words forces the long unbroken path to wrap)
-  await claudeError.focus();
-  const tooltip = page.getByRole("tooltip");
-  await expect(tooltip).toBeVisible({ timeout: 2_000 });
-  await expect(tooltip).toContainText("npm ERR! code EACCES");
-  await expect(tooltip).toContainText("Hint: Run as Administrator");
-
-  // Locate the scroll container using page-level locator since Radix portals
-  // can place content outside the tooltip role element's subtree in the DOM.
-  // Use .first() because Radix keeps a hidden duplicate in the light DOM.
-  const detailSpan = page.locator("span.overflow-y-auto").first();
-  await expect(detailSpan).toBeVisible();
-
-  // Vertical: scrollHeight must exceed clientHeight (content taller than max-h-48).
-  // Scroll position must advance when set, proving scrollability.
-  const isVerticallyScrollable = await detailSpan.evaluate((el) => {
-    return el.scrollHeight > el.clientHeight;
-  });
-  expect(isVerticallyScrollable).toBe(true);
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-buzz-agent").click();
+  await page.getByTestId("onboarding-finish").click();
+  await expect(page.getByText("Join or create a community")).toBeVisible();
 
-  // Confirm scroll position can actually advance.
-  await detailSpan.evaluate((el) => {
-    el.scrollTop = 9999;
+  const saved = await page.evaluate(async () => {
+    return await (
+      window as Window & {
+        __BUZZ_E2E_INVOKE_MOCK_COMMAND__?: (
+          command: string,
+          payload: unknown,
+        ) => Promise<{
+          env_vars: Record<string, string>;
+          model: string | null;
+          provider: string | null;
+        }>;
+      }
+    ).__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.("get_global_agent_config", null);
   });
-  const scrolledDown = await detailSpan.evaluate((el) => el.scrollTop > 0);
-  expect(scrolledDown).toBe(true);
-
-  // Horizontal: break-words must prevent horizontal overflow.
-  const hasHorizontalOverflow = await detailSpan.evaluate((el) => {
-    return el.scrollWidth > el.clientWidth;
+  expect(saved).toMatchObject({
+    env_vars: {
+      ANTHROPIC_API_KEY: "sk-existing",
+      BUZZ_AGENT_THINKING_EFFORT: "high",
+    },
+    model: "claude-sonnet-4",
+    provider: "anthropic",
   });
-  expect(hasHorizontalOverflow).toBe(false);
 });
 
-test("Finish stays disabled until a provider-required harness is fully configured", async ({
+test("defaults hides model when optional harness has empty discovery", async ({
   page,
 }) => {
   await installMockBridge(
     page,
     {
       acpRuntimesCatalog: [
-        runtime("buzz-agent", "available", { status: "not_applicable" }),
+        runtime("claude", "available", { status: "logged_in" }),
       ],
       discoverAgentModels: {
-        models: [{ id: "claude-sonnet-4", name: "Claude Sonnet 4" }],
-        supportsSwitching: true,
+        models: [],
+        supportsSwitching: false,
       },
       globalAgentConfig: {
         env_vars: {},
@@ -853,47 +707,24 @@ test("Finish stays disabled until a provider-required harness is fully configure
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
-  await page.getByTestId("onboarding-setup-next").click();
-  await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
-
-  // buzz-agent auto-selects as the only ready harness, but with no provider
-  // configured the default is not launchable — Finish must be gated.
-  await expect(page.getByTestId("global-agent-default-harness")).toHaveText(
-    "Buzz",
-  );
-  const finish = page.getByTestId("onboarding-finish");
-  await expect(finish).toBeDisabled();
-
-  // Configure provider + credential; model resolves via discovery/fallback.
-  await page.getByTestId("global-agent-provider").click();
-  await page.getByTestId("global-agent-provider-option-anthropic").click();
-  await page.getByTestId("persona-provider-api-key").fill("sk-test-key");
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-claude").click();
 
-  await expect(finish).toBeEnabled();
-  await finish.click();
-  await expect(page.getByText("Join or create a community")).toBeVisible();
-  expect(await readSavedRuntime(page)).toBe("buzz-agent");
+  await expect(page.getByTestId("global-agent-model")).toHaveCount(0);
+  await expect(page.getByText(/Claude Code is ready/i)).toBeVisible();
+  await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
 });
 
-test("baked build config keeps Finish enabled without manual provider setup", async ({
+test("defaults keeps model control when optional harness discovery fails", async ({
   page,
 }) => {
   await installMockBridge(
     page,
     {
       acpRuntimesCatalog: [
-        runtime("buzz-agent", "available", { status: "not_applicable" }),
-      ],
-      bakedBuildEnv: [
-        { key: "BUZZ_AGENT_PROVIDER", masked: false, value: "databricks_v2" },
-        {
-          key: "DATABRICKS_HOST",
-          masked: false,
-          value: "https://example.cloud.databricks.com",
-        },
-        { key: "DATABRICKS_MODEL", masked: false, value: "baked-model" },
+        runtime("claude", "available", { status: "logged_in" }),
       ],
+      discoverAgentModelsError: "CLI discovery timed out",
       globalAgentConfig: {
         env_vars: {},
         provider: null,
@@ -904,14 +735,9 @@ test("baked build config keeps Finish enabled without manual provider setup", as
     { skipCommunitySeed: true, skipOnboardingSeed: true },
   );
   await page.goto("/");
-  await navigateToSetupPage(page);
-  await page.getByTestId("onboarding-setup-next").click();
-  await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-claude").click();
 
-  // Internal builds bake provider/model/credentials — the gate must treat
-  // baked config as complete and never block Finish.
-  await expect(page.getByTestId("global-agent-default-harness")).toHaveText(
-    "Buzz",
-  );
+  await expect(page.getByText(/Claude Code is ready/i)).toBeVisible();
   await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
 });
diff --git a/desktop/tests/helpers/bridge.ts b/desktop/tests/helpers/bridge.ts
index ca4d62ddd62..562e2f4d22f 100644
--- a/desktop/tests/helpers/bridge.ts
+++ b/desktop/tests/helpers/bridge.ts
@@ -162,6 +162,8 @@ type MockBridgeOptions = {
   acpRuntimesCatalogAfterInstallSequence?: Record<string, unknown>[][];
   /** Catalog responses for successive discovery calls. The final response repeats. */
   acpRuntimesCatalogSequence?: Record<string, unknown>[][];
+  /** Sequenced discovery failures. Null succeeds; a string throws. */
+  acpRuntimesErrors?: (string | null)[];
   acpRuntimesDelayMs?: number;
   acpAuthMethods?: Record<string, { methods: Record<string, unknown>[] }>;
   acpAuthMethodsError?: string;

From 04de530ef122f24666f016df95a2eb087a2c6cf8 Mon Sep 17 00:00:00 2001
From: morgmart <98432065+morgmart@users.noreply.github.com>
Date: Wed, 29 Jul 2026 09:36:30 -0700
Subject: [PATCH 2/5] Update onboarding navigation coverage

Signed-off-by: morgmart <98432065+morgmart@users.noreply.github.com>
---
 .../onboarding/ui/DefaultConfigStep.tsx       | 21 ++++++++++++-------
 desktop/tests/e2e/harness-management.spec.ts  |  2 +-
 desktop/tests/e2e/onboarding.spec.ts          | 14 +++++++------
 3 files changed, 22 insertions(+), 15 deletions(-)

diff --git a/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx b/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
index a5181255283..4c8061675f9 100644
--- a/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
+++ b/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
@@ -531,15 +531,20 @@ export function DefaultConfigStep({
     () => getVisibleOnboardingRuntimes(runtimesQuery.data ?? []),
     [runtimesQuery.data],
   );
+  const [config, setConfig] =
+    React.useState<GlobalAgentConfig>(EMPTY_GLOBAL_CONFIG);
+  // Reopening machine config from the first-community flow starts directly on
+  // this page, without a chooser draft. Fall back to the persisted default so
+  // the same selected-harness setup renders instead of a missing-runtime state.
+  const effectiveSelectedRuntimeId =
+    selectedRuntimeId ?? config.preferred_runtime;
   const selectedRuntime = visibleRuntimes.find(
-    (runtime) => runtime.id === selectedRuntimeId,
+    (runtime) => runtime.id === effectiveSelectedRuntimeId,
   );
   const { data: runtimeFileConfig, isLoading: runtimeFileConfigLoading } =
-    useRuntimeFileConfigQuery(selectedRuntimeId ?? "", {
-      enabled: Boolean(selectedRuntimeId),
+    useRuntimeFileConfigQuery(effectiveSelectedRuntimeId ?? "", {
+      enabled: Boolean(effectiveSelectedRuntimeId),
     });
-  const [config, setConfig] =
-    React.useState<GlobalAgentConfig>(EMPTY_GLOBAL_CONFIG);
   const [bakedEnv, setBakedEnv] = React.useState<BakedEnvEntry[]>([]);
   const [isConfigLoading, setIsConfigLoading] = React.useState(true);
   const [configValid, setConfigValid] = React.useState(false);
@@ -643,20 +648,20 @@ export function DefaultConfigStep({
   }, [installMutation, runtimesQuery, selectedRuntime]);
 
   const handleComplete = React.useCallback(async () => {
-    if (!selectedRuntimeId) return;
+    if (!effectiveSelectedRuntimeId) return;
     setIsCompleting(true);
     setCompletionError(null);
     try {
       await setGlobalAgentConfig({
         ...config,
-        preferred_runtime: selectedRuntimeId,
+        preferred_runtime: effectiveSelectedRuntimeId,
       });
       actions.complete();
     } catch {
       setCompletionError("Couldn't save your default harness. Try again.");
       setIsCompleting(false);
     }
-  }, [actions, config, selectedRuntimeId]);
+  }, [actions, config, effectiveSelectedRuntimeId]);
 
   return (
     <OnboardingSlideTransition
diff --git a/desktop/tests/e2e/harness-management.spec.ts b/desktop/tests/e2e/harness-management.spec.ts
index 50047f8f81e..6ef196706af 100644
--- a/desktop/tests/e2e/harness-management.spec.ts
+++ b/desktop/tests/e2e/harness-management.spec.ts
@@ -677,7 +677,7 @@ test("onboarding setup More-harnesses click navigates to Settings → Agents", a
 
   // Now on the setup page.
   await expect(
-    page.getByRole("heading", { name: "Set up your agent harnesses" }),
+    page.getByRole("heading", { name: "Choose your default harness" }),
   ).toBeVisible({ timeout: 10_000 });
 
   // Click the "More harnesses" link — fires navigateToAgentSettings.
diff --git a/desktop/tests/e2e/onboarding.spec.ts b/desktop/tests/e2e/onboarding.spec.ts
index 0c4d6309947..8ae48197e84 100644
--- a/desktop/tests/e2e/onboarding.spec.ts
+++ b/desktop/tests/e2e/onboarding.spec.ts
@@ -1177,6 +1177,12 @@ test("first-community shows the scenario cards for localhost", async ({
   await installMockBridge(
     page,
     {
+      globalAgentConfig: {
+        env_vars: {},
+        provider: null,
+        model: null,
+        preferred_runtime: "claude",
+      },
       acpRuntimesCatalog: [
         {
           id: "claude",
@@ -1220,13 +1226,9 @@ test("first-community shows the scenario cards for localhost", async ({
   await page.getByTestId("welcome-setup-back").click();
   await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
   await expect(
-    page.getByRole("heading", {
-      name: "Configure your default model settings",
-    }),
+    page.getByRole("heading", { name: "Set up Claude Code" }),
   ).toBeVisible();
-  await expect(page.getByTestId("global-agent-default-harness")).toHaveText(
-    "Claude Code",
-  );
+  await expect(page.getByText(/Claude Code is ready/i)).toBeVisible();
   await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
 });
 

From 0027b461bf817a69416973fe80ae5e4d74097c0a Mon Sep 17 00:00:00 2001
From: morgmart <98432065+morgmart@users.noreply.github.com>
Date: Wed, 29 Jul 2026 09:54:33 -0700
Subject: [PATCH 3/5] Update onboarding screenshot coverage

Signed-off-by: morgmart <98432065+morgmart@users.noreply.github.com>
---
 desktop/tests/e2e/onboarding-docked-cta-screenshots.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/desktop/tests/e2e/onboarding-docked-cta-screenshots.spec.ts b/desktop/tests/e2e/onboarding-docked-cta-screenshots.spec.ts
index dbb8a92a1f7..7b204a7822d 100644
--- a/desktop/tests/e2e/onboarding-docked-cta-screenshots.spec.ts
+++ b/desktop/tests/e2e/onboarding-docked-cta-screenshots.spec.ts
@@ -67,7 +67,7 @@ test("machine onboarding: landing, backup, setup docked CTAs", async ({
 
   await page.getByTestId("onboarding-next").click();
   await expect(
-    page.getByRole("heading", { name: "Set up your agent harnesses" }),
+    page.getByRole("heading", { name: "Choose your default harness" }),
   ).toBeVisible();
   await waitForAnimations(page);
   await page.screenshot({ path: `${SHOT_DIR}/03-setup.png` });

From 45ce229d5f724d189e4035466f96cee04f419531 Mon Sep 17 00:00:00 2001
From: morgmart <98432065+morgmart@users.noreply.github.com>
Date: Wed, 19 Aug 2026 20:29:38 -0700
Subject: [PATCH 4/5] fix: fail closed on onboarding config load

Signed-off-by: morgmart <98432065+morgmart@users.noreply.github.com>
---
 .../onboarding/ui/DefaultConfigStep.tsx       | 91 +++++++++++++------
 desktop/src/testing/e2eBridge.ts              |  4 +
 .../e2e/onboarding-agent-defaults.spec.ts     | 91 +++++++++++++++++++
 desktop/tests/helpers/bridge.ts               |  2 +
 4 files changed, 160 insertions(+), 28 deletions(-)

diff --git a/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx b/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
index 4c8061675f9..55c9bfb40d0 100644
--- a/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
+++ b/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
@@ -60,6 +60,7 @@ type InstallResultState = {
 
 type SetupPlanKind =
   | "loading"
+  | "config-error"
   | "catalog-error"
   | "missing-runtime"
   | "needs-install"
@@ -547,6 +548,13 @@ export function DefaultConfigStep({
     });
   const [bakedEnv, setBakedEnv] = React.useState<BakedEnvEntry[]>([]);
   const [isConfigLoading, setIsConfigLoading] = React.useState(true);
+  const [configLoadError, setConfigLoadError] = React.useState<string | null>(
+    null,
+  );
+  const [configLoadNonce, retryConfigLoad] = React.useReducer(
+    (nonce: number) => nonce + 1,
+    0,
+  );
   const [configValid, setConfigValid] = React.useState(false);
   const [installResult, setInstallResult] = React.useState<InstallResultState>({
     error: null,
@@ -561,7 +569,9 @@ export function DefaultConfigStep({
   React.useEffect(() => {
     let unmounted = false;
 
-    async function loadDefaults() {
+    async function loadDefaults(_retryAttempt: number) {
+      setIsConfigLoading(true);
+      setConfigLoadError(null);
       const [configResult, bakedEnvResult] = await Promise.allSettled([
         getGlobalAgentConfig(),
         getBakedBuildEnv(),
@@ -569,41 +579,52 @@ export function DefaultConfigStep({
 
       if (unmounted) return;
 
-      if (configResult.status === "fulfilled") {
-        const harnessChanged =
-          selectedRuntimeId !== null &&
-          selectedRuntimeId !== configResult.value.preferred_runtime;
-        setConfig(
-          harnessChanged
-            ? resetConfigForHarnessChange(configResult.value, selectedRuntimeId)
-            : configResult.value,
-        );
-      }
       if (bakedEnvResult.status === "fulfilled") {
         setBakedEnv(bakedEnvResult.value);
       }
+
+      if (configResult.status === "rejected") {
+        setConfigLoadError(
+          configResult.reason instanceof Error
+            ? configResult.reason.message
+            : "Couldn't load your existing default harness.",
+        );
+        setIsConfigLoading(false);
+        return;
+      }
+
+      const harnessChanged =
+        selectedRuntimeId !== null &&
+        selectedRuntimeId !== configResult.value.preferred_runtime;
+      setConfig(
+        harnessChanged
+          ? resetConfigForHarnessChange(configResult.value, selectedRuntimeId)
+          : configResult.value,
+      );
       setIsConfigLoading(false);
     }
 
-    void loadDefaults();
+    void loadDefaults(configLoadNonce);
 
     return () => {
       unmounted = true;
     };
-  }, [selectedRuntimeId]);
-
-  const plan: SetupPlanKind = runtimesQuery.isError
-    ? "catalog-error"
-    : deriveSetupPlan({
-        bakedEnv,
-        config,
-        isConfigLoading:
-          isConfigLoading ||
-          runtimesQuery.isLoading ||
-          runtimeFileConfigLoading,
-        runtime: selectedRuntime,
-        runtimeFileConfig,
-      });
+  }, [configLoadNonce, selectedRuntimeId]);
+
+  const plan: SetupPlanKind = configLoadError
+    ? "config-error"
+    : runtimesQuery.isError
+      ? "catalog-error"
+      : deriveSetupPlan({
+          bakedEnv,
+          config,
+          isConfigLoading:
+            isConfigLoading ||
+            runtimesQuery.isLoading ||
+            runtimeFileConfigLoading,
+          runtime: selectedRuntime,
+          runtimeFileConfig,
+        });
   // Once this page has disclosed provider setup, keep those fields mounted as
   // they become valid. Validity gates Finish; it must not replace the form the
   // user is actively completing.
@@ -648,7 +669,7 @@ export function DefaultConfigStep({
   }, [installMutation, runtimesQuery, selectedRuntime]);
 
   const handleComplete = React.useCallback(async () => {
-    if (!effectiveSelectedRuntimeId) return;
+    if (!effectiveSelectedRuntimeId || !canFinish || isCompleting) return;
     setIsCompleting(true);
     setCompletionError(null);
     try {
@@ -661,7 +682,7 @@ export function DefaultConfigStep({
       setCompletionError("Couldn't save your default harness. Try again.");
       setIsCompleting(false);
     }
-  }, [actions, config, effectiveSelectedRuntimeId]);
+  }, [actions, canFinish, config, effectiveSelectedRuntimeId, isCompleting]);
 
   return (
     <OnboardingSlideTransition
@@ -682,6 +703,20 @@ export function DefaultConfigStep({
               <Spinner className="h-4 w-4 border-2" />
               Loading…
             </div>
+          ) : effectivePlan === "config-error" ? (
+            <div className="flex flex-col items-center gap-3 py-4 text-center text-sm">
+              <p className="text-destructive">
+                Couldn't load your existing default harness. Try again.
+              </p>
+              <Button
+                className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
+                disabled={isConfigLoading}
+                onClick={retryConfigLoad}
+                type="button"
+              >
+                {isConfigLoading ? "Checking…" : "Try again"}
+              </Button>
+            </div>
           ) : effectivePlan === "catalog-error" ? (
             <div className="flex flex-col items-center gap-3 py-4 text-center text-sm">
               <p className="text-destructive">
diff --git a/desktop/src/testing/e2eBridge.ts b/desktop/src/testing/e2eBridge.ts
index f88d08cc6da..66323cf76db 100644
--- a/desktop/src/testing/e2eBridge.ts
+++ b/desktop/src/testing/e2eBridge.ts
@@ -402,6 +402,8 @@ type E2eConfig = {
       model: string | null;
       preferred_runtime?: string | null;
     };
+    /** Sequenced `get_global_agent_config` failures. Null succeeds; a string throws. */
+    globalAgentConfigErrors?: (string | null)[];
     /** File-layer config returned by runtime id. */
     runtimeFileConfigs?: Record<string, RuntimeFileConfigSubset | null>;
     /** Baked build env returned by the display and key-name Tauri commands. */
@@ -10954,6 +10956,8 @@ export function maybeInstallE2eTauriMocks() {
         return config.mock?.runtimeFileConfigs?.[runtimeId] ?? null;
       }
       case "get_global_agent_config": {
+        const readError = activeConfig?.mock?.globalAgentConfigErrors?.shift();
+        if (readError) throw new Error(readError);
         // Return the mutable persisted mock value, seeded from the test config.
         return (
           mockGlobalAgentConfig ?? {
diff --git a/desktop/tests/e2e/onboarding-agent-defaults.spec.ts b/desktop/tests/e2e/onboarding-agent-defaults.spec.ts
index 8213b652dac..ccbd05f5a24 100644
--- a/desktop/tests/e2e/onboarding-agent-defaults.spec.ts
+++ b/desktop/tests/e2e/onboarding-agent-defaults.spec.ts
@@ -684,6 +684,97 @@ test("Finish preserves existing values when the selected harness is unchanged",
   });
 });
 
+test("failed config read blocks Finish, preserves existing config, and retry succeeds", async ({
+  page,
+}) => {
+  await installMockBridge(
+    page,
+    {
+      acpRuntimesCatalog: [
+        runtime("claude", "available", { status: "logged_in" }),
+        runtime("codex", "available", { status: "logged_in" }),
+      ],
+      globalAgentConfig: {
+        env_vars: {
+          ANTHROPIC_API_KEY: "sk-existing",
+          BUZZ_AGENT_THINKING_EFFORT: "high",
+        },
+        provider: "anthropic",
+        model: "claude-sonnet-4",
+        preferred_runtime: "claude",
+      },
+      globalAgentConfigErrors: ["temporary config read failure", null],
+    },
+    { skipCommunitySeed: true, skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+  await navigateToChooserPage(page);
+  await page.getByTestId("onboarding-runtime-codex").click();
+
+  await expect(
+    page.getByText("Couldn't load your existing default harness. Try again."),
+  ).toBeVisible();
+  await expect(page.getByTestId("onboarding-finish")).toBeDisabled();
+  await page.getByTestId("onboarding-finish").click({ force: true });
+  await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
+
+  let saved = await page.evaluate(async () => {
+    return await (
+      window as Window & {
+        __BUZZ_E2E_INVOKE_MOCK_COMMAND__?: (
+          command: string,
+          payload: unknown,
+        ) => Promise<{
+          env_vars: Record<string, string>;
+          model: string | null;
+          preferred_runtime: string | null;
+          provider: string | null;
+        }>;
+      }
+    ).__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.("get_global_agent_config", null);
+  });
+  expect(saved).toMatchObject({
+    env_vars: {
+      ANTHROPIC_API_KEY: "sk-existing",
+      BUZZ_AGENT_THINKING_EFFORT: "high",
+    },
+    model: "claude-sonnet-4",
+    preferred_runtime: "claude",
+    provider: "anthropic",
+  });
+
+  await page.getByRole("button", { name: "Try again" }).click();
+  await expect(page.getByText(/Codex is ready/i)).toBeVisible();
+  await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
+  await page.getByTestId("onboarding-finish").click();
+  await expect(page.getByText("Join or create a community")).toBeVisible();
+
+  saved = await page.evaluate(async () => {
+    return await (
+      window as Window & {
+        __BUZZ_E2E_INVOKE_MOCK_COMMAND__?: (
+          command: string,
+          payload: unknown,
+        ) => Promise<{
+          env_vars: Record<string, string>;
+          model: string | null;
+          preferred_runtime: string | null;
+          provider: string | null;
+        }>;
+      }
+    ).__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.("get_global_agent_config", null);
+  });
+  expect(saved).toMatchObject({
+    env_vars: {
+      ANTHROPIC_API_KEY: "sk-existing",
+    },
+    model: null,
+    preferred_runtime: "codex",
+    provider: null,
+  });
+  expect(saved?.env_vars).not.toHaveProperty("BUZZ_AGENT_THINKING_EFFORT");
+});
+
 test("defaults hides model when optional harness has empty discovery", async ({
   page,
 }) => {
diff --git a/desktop/tests/helpers/bridge.ts b/desktop/tests/helpers/bridge.ts
index 562e2f4d22f..972076dd5af 100644
--- a/desktop/tests/helpers/bridge.ts
+++ b/desktop/tests/helpers/bridge.ts
@@ -422,6 +422,8 @@ type MockBridgeOptions = {
     model: string | null;
     preferred_runtime?: string | null;
   };
+  /** Sequenced `get_global_agent_config` failures. Null succeeds; a string throws. */
+  globalAgentConfigErrors?: (string | null)[];
   /** File-layer config returned by runtime id. */
   runtimeFileConfigs?: Record<
     string,

From 8b85a2b315b686b4abf6a43e8a0d1e570004a72c Mon Sep 17 00:00:00 2001
From: morgmart <98432065+morgmart@users.noreply.github.com>
Date: Wed, 19 Aug 2026 20:40:59 -0700
Subject: [PATCH 5/5] fix: fail closed on onboarding config load

Signed-off-by: morgmart <98432065+morgmart@users.noreply.github.com>
---
 .../onboarding/ui/DefaultConfigStep.tsx       | 48 +++++++---
 desktop/src/features/onboarding/ui/types.ts   |  3 +-
 desktop/src/testing/e2eBridge.ts              |  4 +
 .../e2e/onboarding-agent-defaults.spec.ts     | 96 +++++++++++++++++++
 desktop/tests/helpers/bridge.ts               |  2 +
 5 files changed, 140 insertions(+), 13 deletions(-)

diff --git a/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx b/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
index 1fd2e4bcabd..2c20e187764 100644
--- a/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
+++ b/desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
@@ -77,6 +77,11 @@ function AgentDefaultsSection({
     initialDraftRef.current?.isCustomModelEditing ?? false,
   );
   const [bakedEnv, setBakedEnv] = React.useState<BakedEnvEntry[]>([]);
+  const [configLoadError, setConfigLoadError] = React.useState(false);
+  const [configLoadNonce, retryConfigLoad] = React.useReducer(
+    (nonce: number) => nonce + 1,
+    0,
+  );
   const configRef = React.useRef<GlobalAgentConfig>(
     initialDraftRef.current?.config ?? EMPTY_GLOBAL_CONFIG,
   );
@@ -86,7 +91,9 @@ function AgentDefaultsSection({
   React.useEffect(() => {
     let unmounted = false;
 
-    async function loadDefaults() {
+    async function loadDefaults(_retryAttempt: number) {
+      setIsLoading(true);
+      setConfigLoadError(false);
       const [configResult, bakedEnvResult] = await Promise.allSettled([
         getGlobalAgentConfig(),
         getBakedBuildEnv(),
@@ -94,25 +101,27 @@ function AgentDefaultsSection({
 
       if (unmounted) return;
 
-      if (
-        initialDraftRef.current === null &&
-        configResult.status === "fulfilled"
-      ) {
-        configRef.current = configResult.value;
-        setConfig(configResult.value);
-      }
       if (bakedEnvResult.status === "fulfilled") {
         setBakedEnv(bakedEnvResult.value);
       }
+      if (configResult.status === "rejected") {
+        setConfigLoadError(true);
+        setIsLoading(false);
+        return;
+      }
+      if (initialDraftRef.current === null) {
+        configRef.current = configResult.value;
+        setConfig(configResult.value);
+      }
       setIsLoading(false);
     }
 
-    void loadDefaults();
+    void loadDefaults(configLoadNonce);
 
     return () => {
       unmounted = true;
     };
-  }, []);
+  }, [configLoadNonce]);
 
   const effectiveReadyRuntimeIds = React.useMemo(
     () =>
@@ -147,6 +156,7 @@ function AgentDefaultsSection({
   const configSurfaceLoading = isLoading || runtimesQuery.isLoading;
 
   const configSurfaceError =
+    configLoadError ||
     runtimesQuery.isError ||
     (!configSurfaceLoading &&
       effectiveReadyRuntimeIds.length > 0 &&
@@ -212,12 +222,14 @@ function AgentDefaultsSection({
       // configIsValid comes from AgentConfigFields' onValidityChange and
       // covers model + provider credentials — a harness selection alone is
       // not a working default (e.g. buzz-agent with no provider configured).
-      canComplete: selectedRuntimeId.length > 0 && configIsValid,
+      canComplete:
+        !configLoadError && selectedRuntimeId.length > 0 && configIsValid,
       commit: commitPersistence,
     });
   }, [
     commitPersistence,
     configIsValid,
+    configLoadError,
     onPersistenceStateChange,
     selectedRuntimeId,
   ]);
@@ -233,6 +245,20 @@ function AgentDefaultsSection({
           <Spinner className="h-4 w-4 border-2" />
           Loading…
         </div>
+      ) : configLoadError ? (
+        <div className="flex flex-col items-center gap-3 py-4 text-center text-sm">
+          <p className="text-destructive">
+            Couldn't load your existing default harness. Try again.
+          </p>
+          <Button
+            className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
+            disabled={isLoading}
+            onClick={retryConfigLoad}
+            type="button"
+          >
+            {isLoading ? "Checking…" : "Try again"}
+          </Button>
+        </div>
       ) : configSurfaceError ? (
         <p className="py-4 text-center text-sm text-destructive">
           Couldn't load harness settings. Go back and try again.
diff --git a/desktop/src/features/onboarding/ui/types.ts b/desktop/src/features/onboarding/ui/types.ts
index 2658850c75a..5216bfefa4d 100644
--- a/desktop/src/features/onboarding/ui/types.ts
+++ b/desktop/src/features/onboarding/ui/types.ts
@@ -62,8 +62,7 @@ export type ProfileStepActions = {
 
 export type SetupStepActions = {
   back: () => void;
-  next: (runtimeId: string) => void;
-  skip: () => void;
+  next: (readyRuntimeIds: readonly string[]) => void;
   navigateToAgentSettings?: () => void;
 };
 
diff --git a/desktop/src/testing/e2eBridge.ts b/desktop/src/testing/e2eBridge.ts
index af17af4f758..85f46f25d5f 100644
--- a/desktop/src/testing/e2eBridge.ts
+++ b/desktop/src/testing/e2eBridge.ts
@@ -537,6 +537,8 @@ type E2eConfig = {
       model: string | null;
       preferred_runtime?: string | null;
     };
+    /** Sequenced `get_global_agent_config` failures. Null succeeds; a string throws. */
+    globalAgentConfigErrors?: (string | null)[];
     /** Explicit owner-only agent-access capability; independent of baked defaults. */
     ownerOnlyAccessBuild?: boolean;
     /** File-layer config returned by runtime id. */
@@ -13153,6 +13155,8 @@ export function maybeInstallE2eTauriMocks() {
         return config.mock?.runtimeFileConfigs?.[runtimeId] ?? null;
       }
       case "get_global_agent_config": {
+        const readError = activeConfig?.mock?.globalAgentConfigErrors?.shift();
+        if (readError) throw new Error(readError);
         // Return the mutable persisted mock value, seeded from the test config.
         return (
           mockGlobalAgentConfig ?? {
diff --git a/desktop/tests/e2e/onboarding-agent-defaults.spec.ts b/desktop/tests/e2e/onboarding-agent-defaults.spec.ts
index 3a15d21767d..293e7e7362c 100644
--- a/desktop/tests/e2e/onboarding-agent-defaults.spec.ts
+++ b/desktop/tests/e2e/onboarding-agent-defaults.spec.ts
@@ -491,6 +491,102 @@ test("defaults renders only fields supported by the selected harness", async ({
   ).toHaveCount(0);
 });
 
+test("failed config read blocks Next, preserves existing config, and retry succeeds", async ({
+  page,
+}) => {
+  await installMockBridge(
+    page,
+    {
+      acpRuntimesCatalog: [
+        runtime("claude", "available", { status: "logged_in" }),
+        runtime("codex", "available", { status: "logged_in" }),
+      ],
+      globalAgentConfig: {
+        env_vars: {
+          ANTHROPIC_API_KEY: "sk-existing",
+          BUZZ_AGENT_THINKING_EFFORT: "high",
+        },
+        provider: "anthropic",
+        model: "claude-sonnet-4",
+        preferred_runtime: "claude",
+      },
+      globalAgentConfigErrors: ["temporary config read failure", null],
+    },
+    { skipCommunitySeed: true, skipOnboardingSeed: true },
+  );
+  await page.goto("/");
+  await navigateToSetupPage(page);
+  await page.getByTestId("onboarding-setup-next").click();
+
+  await expect(
+    page.getByText("Couldn't load your existing default harness. Try again."),
+  ).toBeVisible();
+  await expect(page.getByTestId("onboarding-finish")).toBeDisabled();
+  await page.getByTestId("onboarding-finish").click({ force: true });
+  await expect(page.getByTestId("onboarding-page-config")).toBeVisible();
+
+  let saved = await page.evaluate(async () => {
+    return await (
+      window as Window & {
+        __BUZZ_E2E_INVOKE_MOCK_COMMAND__?: (
+          command: string,
+          payload: unknown,
+        ) => Promise<{
+          env_vars: Record<string, string>;
+          model: string | null;
+          preferred_runtime: string | null;
+          provider: string | null;
+        }>;
+      }
+    ).__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.("get_global_agent_config", null);
+  });
+  expect(saved).toMatchObject({
+    env_vars: {
+      ANTHROPIC_API_KEY: "sk-existing",
+      BUZZ_AGENT_THINKING_EFFORT: "high",
+    },
+    model: "claude-sonnet-4",
+    preferred_runtime: "claude",
+    provider: "anthropic",
+  });
+
+  await page.getByRole("button", { name: "Try again" }).click();
+  await expect(page.getByTestId("global-agent-default-harness")).toHaveText(
+    "Claude Code",
+  );
+  const harness = page.getByTestId("global-agent-default-harness");
+  await harness.click();
+  await page.getByTestId("global-agent-default-harness-option-codex").click();
+  await expect(page.getByTestId("onboarding-finish")).toBeEnabled();
+  await page.getByTestId("onboarding-finish").click();
+  await expect(page.getByText("Join or create a community")).toBeVisible();
+
+  saved = await page.evaluate(async () => {
+    return await (
+      window as Window & {
+        __BUZZ_E2E_INVOKE_MOCK_COMMAND__?: (
+          command: string,
+          payload: unknown,
+        ) => Promise<{
+          env_vars: Record<string, string>;
+          model: string | null;
+          preferred_runtime: string | null;
+          provider: string | null;
+        }>;
+      }
+    ).__BUZZ_E2E_INVOKE_MOCK_COMMAND__?.("get_global_agent_config", null);
+  });
+  expect(saved).toMatchObject({
+    env_vars: {
+      ANTHROPIC_API_KEY: "sk-existing",
+    },
+    model: null,
+    preferred_runtime: "codex",
+    provider: null,
+  });
+  expect(saved?.env_vars).not.toHaveProperty("BUZZ_AGENT_THINKING_EFFORT");
+});
+
 test("defaults hides model when optional harness has empty discovery", async ({
   page,
 }) => {
diff --git a/desktop/tests/helpers/bridge.ts b/desktop/tests/helpers/bridge.ts
index ed94e6b1767..493017582d9 100644
--- a/desktop/tests/helpers/bridge.ts
+++ b/desktop/tests/helpers/bridge.ts
@@ -497,6 +497,8 @@ type MockBridgeOptions = {
     model: string | null;
     preferred_runtime?: string | null;
   };
+  /** Sequenced `get_global_agent_config` failures. Null succeeds; a string throws. */
+  globalAgentConfigErrors?: (string | null)[];
   ownerOnlyAccessBuild?: boolean;
   /** File-layer config returned by runtime id. */
   runtimeFileConfigs?: Record<