From 1367ef1f76a3810ad2bf7d1699d22579fa69ca7c Mon Sep 17 00:00:00 2001
From: kenny lopez <klopez4212@gmail.com>
Date: Wed, 5 Aug 2026 18:56:40 +0100
Subject: [PATCH 1/5] Polish advanced agent setup and Welcome composer

Signed-off-by: kenny lopez <klopez4212@gmail.com>
---
 .../agents/ui/AgentDefinitionDialog.tsx       |  6 +-
 .../agents/ui/PersonaAdvancedFields.tsx       |  5 ++
 .../features/agents/ui/WhereToRunSection.tsx  | 29 ++++---
 .../src/features/channels/ui/ChannelPane.tsx  | 18 ++---
 .../channels/ui/WelcomeComposerBanner.tsx     | 27 +++++++
 .../messages/ui/ComposerDockBackdrop.tsx      | 23 +++++-
 desktop/tests/e2e/onboarding.spec.ts          | 75 ++++++++++++++++++-
 desktop/tests/e2e/where-to-run-config.spec.ts | 44 ++++++++++-
 8 files changed, 197 insertions(+), 30 deletions(-)

diff --git a/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx b/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx
index 12702f45ac..b3f8ee86a7 100644
--- a/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx
+++ b/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx
@@ -109,7 +109,6 @@ type AgentDefinitionDialogProps = {
   ) => Promise<unknown>;
   /** Publishes saved changes when the edited agent is shared in the catalog. */
   publishCatalogUpdatesOnSave?: boolean;
-  /** Rendered below the form fields in create mode only ("Where to run"). */
   createRunSection?: React.ReactNode;
   /** Extra create-mode submit gate (e.g. incomplete provider config). */
   createSubmitBlocked?: boolean;
@@ -963,8 +962,6 @@ export function AgentDefinitionDialog({
               open={isAddHarnessOpen}
             />
 
-            {isCreateMode ? createRunSection : null}
-
             <div className="space-y-3">
               <button
                 aria-expanded={showAdvancedFields}
@@ -1002,6 +999,9 @@ export function AgentDefinitionDialog({
                     transition={advancedFieldsTransition}
                   >
                     <PersonaAdvancedFields
+                      afterRespondTo={
+                        isCreateMode ? createRunSection : undefined
+                      }
                       behaviorDraft={behaviorDraft}
                       disabled={isPending}
                       envVars={envVars}
diff --git a/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx b/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx
index 1ecd98b83f..bb600007fa 100644
--- a/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx
+++ b/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx
@@ -33,6 +33,7 @@ export function PersonaAdvancedFields({
   behaviorDraft,
   disabled,
   envVars,
+  afterRespondTo,
   inheritedEnvVars = {},
   model,
   modelTuningRuntimeId = "",
@@ -50,6 +51,8 @@ export function PersonaAdvancedFields({
   behaviorDraft: PersonaBehaviorDraft;
   disabled: boolean;
   envVars: EnvVarsValue;
+  /** Optional create-only field rendered after instruction permissions. */
+  afterRespondTo?: React.ReactNode;
   /** Env vars to display as inherited defaults in tuning-field placeholders.
    *  For templates, pass `globalConfig.env_vars` (the fallback layer). */
   inheritedEnvVars?: EnvVarsValue;
@@ -120,6 +123,8 @@ export function PersonaAdvancedFields({
         variant="persona"
       />
 
+      {afterRespondTo}
+
       <div className="grid gap-5 sm:grid-cols-2">
         <div className="space-y-1.5">
           <label
diff --git a/desktop/src/features/agents/ui/WhereToRunSection.tsx b/desktop/src/features/agents/ui/WhereToRunSection.tsx
index ee9ec37132..095690f937 100644
--- a/desktop/src/features/agents/ui/WhereToRunSection.tsx
+++ b/desktop/src/features/agents/ui/WhereToRunSection.tsx
@@ -5,6 +5,7 @@ import { useBackendProvidersQuery } from "@/features/agents/hooks";
 import { probeBackendProvider } from "@/shared/api/tauri";
 
 import { ProviderConfigFields } from "./ProviderConfigFields";
+import { PersonaDropdownField } from "./PersonaDropdownField";
 import {
   applyProbeResult,
   emptyWhereToRunDraft,
@@ -23,6 +24,16 @@ export function WhereToRunSection({
 }) {
   const backendProviders = useBackendProvidersQuery().data ?? [];
   const [probeError, setProbeError] = React.useState<string | null>(null);
+  const runOnOptions = React.useMemo(
+    () => [
+      { label: "This computer", value: "local" },
+      ...backendProviders.map((provider) => ({
+        label: provider.id,
+        value: provider.id,
+      })),
+    ],
+    [backendProviders],
+  );
   const isProviderMode = draft.runOn !== "local";
   const selectedBackendProvider = React.useMemo(
     () =>
@@ -80,25 +91,19 @@ export function WhereToRunSection({
         <label className="text-sm font-medium" htmlFor="agent-run-on">
           Run on
         </label>
-        <select
-          className="flex h-9 w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-xs"
+        <PersonaDropdownField
           disabled={isPending}
           id="agent-run-on"
-          onChange={(event) =>
+          onValueChange={(runOn) =>
             onDraftChange({
               ...emptyWhereToRunDraft,
-              runOn: event.target.value,
+              runOn,
             })
           }
+          options={runOnOptions}
+          placeholder="Choose where to run"
           value={draft.runOn}
-        >
-          <option value="local">This computer</option>
-          {backendProviders.map((provider) => (
-            <option key={provider.id} value={provider.id}>
-              {provider.id}
-            </option>
-          ))}
-        </select>
+        />
       </div>
 
       {isProviderMode && selectedBackendProvider ? (
diff --git a/desktop/src/features/channels/ui/ChannelPane.tsx b/desktop/src/features/channels/ui/ChannelPane.tsx
index 9e5152edfe..73d8f38f30 100644
--- a/desktop/src/features/channels/ui/ChannelPane.tsx
+++ b/desktop/src/features/channels/ui/ChannelPane.tsx
@@ -42,7 +42,7 @@ import { BotActivityComposerAction } from "@/features/channels/ui/BotActivityBar
 import { ChannelComposerActivityAccessory } from "@/features/channels/ui/ChannelComposerActivityAccessory";
 import {
   containsWelcomePersonaMention,
-  WelcomeComposerBanner,
+  WelcomeComposerGuidanceLayer,
   WELCOME_COMPOSER_BANNER_DISMISS_DURATION_SECONDS,
   WELCOME_COMPOSER_BANNER_HIDE_BUFFER_MS,
   WELCOME_COMPOSER_BANNER_SUCCESS_SETTLE_MS,
@@ -737,18 +737,18 @@ export const ChannelPane = React.memo(function ChannelPane({
                   hasComposerBottomActivity && "composer-dock--with-activity",
                 )}
               >
+                {isActiveWelcomeChannel && !timeoutState.active ? (
+                  <WelcomeComposerGuidanceLayer
+                    settingUp={welcomeKickoffSettingUp}
+                    state={welcomeComposerBannerState}
+                  >
+                    {welcomeKickoffStage}
+                  </WelcomeComposerGuidanceLayer>
+                ) : null}
                 {timeoutState.active ? (
                   <ComposerTimeoutBanner
                     expiresAtMs={timeoutState.expiresAtMs}
                   />
-                ) : isActiveWelcomeChannel ? (
-                  <div className="relative">
-                    {welcomeKickoffStage}
-                    <WelcomeComposerBanner
-                      settingUp={welcomeKickoffSettingUp}
-                      state={welcomeComposerBannerState}
-                    />
-                  </div>
                 ) : null}
                 <ComposerDockBackdrop gutterClassName="inset-x-5" />
                 <MessageComposer
diff --git a/desktop/src/features/channels/ui/WelcomeComposerBanner.tsx b/desktop/src/features/channels/ui/WelcomeComposerBanner.tsx
index 8d492c9181..f75b8dbeb9 100644
--- a/desktop/src/features/channels/ui/WelcomeComposerBanner.tsx
+++ b/desktop/src/features/channels/ui/WelcomeComposerBanner.tsx
@@ -2,6 +2,7 @@ import * as React from "react";
 import { AnimatePresence, motion, useReducedMotion } from "motion/react";
 import { Bot, Check } from "lucide-react";
 
+import { ComposerDockGlassBackdrop } from "@/features/messages/ui/ComposerDockBackdrop";
 import { cn } from "@/shared/lib/cn";
 
 const WELCOME_PERSONA_NAMES = ["Fizz"] as const;
@@ -414,3 +415,29 @@ export function WelcomeComposerBanner({
     </AnimatePresence>
   );
 }
+
+type WelcomeComposerGuidanceLayerProps = WelcomeComposerBannerProps & {
+  children: React.ReactNode;
+};
+
+export function WelcomeComposerGuidanceLayer({
+  children,
+  settingUp,
+  state,
+}: WelcomeComposerGuidanceLayerProps) {
+  return (
+    <div
+      className="absolute inset-x-0 bottom-full z-[-1]"
+      data-testid="welcome-composer-guidance-layer"
+    >
+      <div className="relative">
+        <ComposerDockGlassBackdrop
+          className="absolute inset-x-5 top-0 bottom-3 z-0 rounded-t-2xl"
+          testId="welcome-composer-guidance-backdrop"
+        />
+        {children}
+        <WelcomeComposerBanner settingUp={settingUp} state={state} />
+      </div>
+    </div>
+  );
+}
diff --git a/desktop/src/features/messages/ui/ComposerDockBackdrop.tsx b/desktop/src/features/messages/ui/ComposerDockBackdrop.tsx
index 840be49bea..edf4c61fa1 100644
--- a/desktop/src/features/messages/ui/ComposerDockBackdrop.tsx
+++ b/desktop/src/features/messages/ui/ComposerDockBackdrop.tsx
@@ -1,5 +1,26 @@
 import { cn } from "@/shared/lib/cn";
 
+type ComposerDockGlassBackdropProps = {
+  className?: string;
+  testId?: string;
+};
+
+export function ComposerDockGlassBackdrop({
+  className,
+  testId,
+}: ComposerDockGlassBackdropProps) {
+  return (
+    <div
+      aria-hidden="true"
+      className={cn(
+        "pointer-events-none backdrop-blur-md dark:backdrop-blur-xl",
+        className,
+      )}
+      data-testid={testId}
+    />
+  );
+}
+
 type ComposerDockBackdropProps = {
   gutterClassName: string;
 };
@@ -21,7 +42,7 @@ export function ComposerDockBackdrop({
         )}
         data-testid="composer-dock-backdrop"
       >
-        <div className="h-full w-full rounded-2xl backdrop-blur-md dark:backdrop-blur-xl" />
+        <ComposerDockGlassBackdrop className="h-full w-full rounded-2xl" />
       </div>
       <div
         aria-hidden="true"
diff --git a/desktop/tests/e2e/onboarding.spec.ts b/desktop/tests/e2e/onboarding.spec.ts
index 57e812091c..bf9d6dd075 100644
--- a/desktop/tests/e2e/onboarding.spec.ts
+++ b/desktop/tests/e2e/onboarding.spec.ts
@@ -202,8 +202,23 @@ async function expectWelcomeComposerBannerLayout(page: Page) {
   const bannerBox = await banner.boundingBox();
   const personaMentionBox = await personaMention.boundingBox();
   const composerBox = await composer.boundingBox();
+  const dockBackdropBox = await page
+    .getByTestId("composer-dock-backdrop")
+    .locator("div")
+    .boundingBox();
+  const guidanceLayer = page.getByTestId("welcome-composer-guidance-layer");
+  const guidanceBackdrop = page.getByTestId(
+    "welcome-composer-guidance-backdrop",
+  );
+  const guidanceBackdropBox = await guidanceBackdrop.boundingBox();
 
-  if (!bannerBox || !personaMentionBox || !composerBox) {
+  if (
+    !bannerBox ||
+    !personaMentionBox ||
+    !composerBox ||
+    !dockBackdropBox ||
+    !guidanceBackdropBox
+  ) {
     throw new Error("Could not measure welcome composer banner layout");
   }
 
@@ -212,11 +227,40 @@ async function expectWelcomeComposerBannerLayout(page: Page) {
   ).toBe(0);
   expect(bannerBox.y).toBeLessThan(composerBox.y);
   expect(bannerBox.y + bannerBox.height).toBeGreaterThan(composerBox.y);
+  expect(Math.abs(dockBackdropBox.y - composerBox.y)).toBeLessThanOrEqual(1);
+  expect(guidanceBackdropBox.y).toBeLessThanOrEqual(bannerBox.y);
+  expect(
+    Math.abs(
+      guidanceBackdropBox.y + guidanceBackdropBox.height - composerBox.y,
+    ),
+  ).toBeLessThanOrEqual(1);
+  const [guidanceZIndex, backdropZIndex] = await Promise.all([
+    guidanceLayer.evaluate((element) =>
+      Number(window.getComputedStyle(element).zIndex),
+    ),
+    page
+      .getByTestId("composer-dock-backdrop")
+      .evaluate((element) => Number(window.getComputedStyle(element).zIndex)),
+  ]);
+  expect(guidanceZIndex).toBeLessThan(backdropZIndex);
+  expect(
+    await page
+      .getByTestId("channel-composer-overlay")
+      .getByTestId("welcome-composer-guidance-layer")
+      .count(),
+  ).toBe(1);
+  expect(
+    await page
+      .getByTestId("composer-dock-backdrop")
+      .getByTestId("welcome-composer-guidance-layer")
+      .count(),
+  ).toBe(0);
 
   const radii = await banner.evaluate((element) => {
     const styles = window.getComputedStyle(element);
     return {
       backdropFilter: styles.backdropFilter,
+      backgroundColor: styles.backgroundColor,
       bottomLeft: styles.borderBottomLeftRadius,
       bottomRight: styles.borderBottomRightRadius,
       filter: styles.filter,
@@ -227,11 +271,24 @@ async function expectWelcomeComposerBannerLayout(page: Page) {
       willChange: styles.willChange,
     };
   });
+  const composerBackgroundColor = await composer.evaluate(
+    (element) => window.getComputedStyle(element).backgroundColor,
+  );
+  const dockBackdropFilter = await page
+    .getByTestId("composer-dock-backdrop")
+    .locator("div")
+    .evaluate((element) => window.getComputedStyle(element).backdropFilter);
+  const guidanceBackdropFilter = await guidanceBackdrop.evaluate(
+    (element) => window.getComputedStyle(element).backdropFilter,
+  );
 
   expect(radii.topLeft).toBe(radii.topRight);
   expect(radii.bottomLeft).toBe("0px");
   expect(radii.bottomRight).toBe("0px");
   expect(radii.backdropFilter).toBe("none");
+  expect(radii.backgroundColor).not.toBe(composerBackgroundColor);
+  expect(dockBackdropFilter).not.toBe("none");
+  expect(guidanceBackdropFilter).toBe(dockBackdropFilter);
   expect(radii.filter).toBe("none");
   expect(radii.transform).toBe("none");
   expect(radii.willChange).toBe("auto");
@@ -385,6 +442,11 @@ async function expectWelcomeComposerBannerCompletesAfterPersonaMention(
 ) {
   const banner = page.getByTestId("welcome-composer-guide-banner");
   const channelIntro = page.getByTestId("message-channel-intro");
+  const composer = page.getByTestId("message-composer");
+  const initialComposerBox = await composer.boundingBox();
+  if (!initialComposerBox) {
+    throw new Error("Could not measure the Welcome composer");
+  }
 
   await page.getByTestId("message-input").fill("Thanks @Fizz");
   await page.getByTestId("send-message").click();
@@ -403,6 +465,17 @@ async function expectWelcomeComposerBannerCompletesAfterPersonaMention(
   await expect(banner).toContainText("Nice work.");
   await expect(banner).not.toContainText("Try mentioning");
   await expect(channelIntro).toBeVisible();
+  const completeComposerBox = await composer.boundingBox();
+  expect(completeComposerBox).not.toBeNull();
+  expect(
+    Math.abs((completeComposerBox?.y ?? 0) - initialComposerBox.y),
+  ).toBeLessThanOrEqual(1);
+  await expect(banner).toHaveCount(0, { timeout: 6_000 });
+  const hiddenComposerBox = await composer.boundingBox();
+  expect(hiddenComposerBox).not.toBeNull();
+  expect(
+    Math.abs((hiddenComposerBox?.y ?? 0) - initialComposerBox.y),
+  ).toBeLessThanOrEqual(1);
 }
 
 async function getMockChannels(page: Page) {
diff --git a/desktop/tests/e2e/where-to-run-config.spec.ts b/desktop/tests/e2e/where-to-run-config.spec.ts
index 869e9b2138..e0c0c459ad 100644
--- a/desktop/tests/e2e/where-to-run-config.spec.ts
+++ b/desktop/tests/e2e/where-to-run-config.spec.ts
@@ -63,7 +63,28 @@ async function probeInvocations(page: Page): Promise<number> {
   );
 }
 
-/** Open the create-agent dialog and select the mocked provider in "Run on". */
+async function selectRunOnOption(
+  page: Page,
+  dialog: import("@playwright/test").Locator,
+  optionName: string,
+) {
+  const trigger = dialog.locator("#agent-run-on");
+  await expect(trigger).toHaveAttribute("aria-expanded", "false");
+  await trigger.press("Enter");
+
+  const option = page.getByRole("menuitemradio", {
+    exact: true,
+    name: optionName,
+  });
+  await expect(option).toBeVisible();
+  // The shared PersonaDropdownField supports keyboard selection. Using it here
+  // avoids racing the menu's open animation when this test changes locations
+  // repeatedly.
+  await option.press("Enter");
+  await expect(trigger).toHaveAttribute("aria-expanded", "false");
+}
+
+/** Open Advanced in the create-agent dialog and select the mocked provider. */
 async function openCreateDialogOnProvider(page: Page) {
   await page.goto("/", { waitUntil: "domcontentloaded" });
   await page.getByTestId("open-agents-view").click();
@@ -71,7 +92,22 @@ async function openCreateDialogOnProvider(page: Page) {
   await page.getByRole("menuitem", { name: "Create agent" }).click();
   const dialog = page.getByTestId("persona-dialog");
   await expect(dialog).toBeVisible({ timeout: 10_000 });
-  await dialog.locator("#agent-run-on").selectOption(PROVIDER.id);
+  const advanced = dialog.getByRole("button", {
+    name: "Advanced",
+    exact: true,
+  });
+  await expect(advanced).toHaveAttribute("aria-expanded", "false");
+  await expect(dialog.locator("#agent-run-on")).toHaveCount(0);
+  await advanced.click();
+  await expect(advanced).toHaveAttribute("aria-expanded", "true");
+  const respondTo = dialog.getByTestId("agent-respond-to");
+  const runOn = dialog.locator("#agent-run-on");
+  await expect(respondTo).toBeVisible();
+  await expect(runOn).toBeVisible();
+  expect(await respondTo.evaluate((element) => element.offsetTop)).toBeLessThan(
+    await runOn.evaluate((element) => element.offsetTop),
+  );
+  await selectRunOnOption(page, dialog, PROVIDER.id);
   return dialog;
 }
 
@@ -141,10 +177,10 @@ test("provider → local → provider re-probes and resets the config", async ({
   await expect(contextField).toBeVisible({ timeout: 10_000 });
   await contextField.fill("stale-value");
 
-  await dialog.locator("#agent-run-on").selectOption("local");
+  await selectRunOnOption(page, dialog, "This computer");
   await expect(contextField).toHaveCount(0);
 
-  await dialog.locator("#agent-run-on").selectOption(PROVIDER.id);
+  await selectRunOnOption(page, dialog, PROVIDER.id);
   await expect(dialog.locator("#provider-cfg-context")).toBeVisible({
     timeout: 10_000,
   });

From 32ca907e99f5b12b3ac5f9d513aef9fe5a198933 Mon Sep 17 00:00:00 2001
From: Watcher
 <bb7abfd757d0af7b66569d02ab9c0316b616f9d0c151ecf5b964344c462e7f8f@buzz.block.builderlab.xyz>
Date: Thu, 6 Aug 2026 15:32:04 +0100
Subject: [PATCH 2/5] docs(agents): record advanced run location placement

Document that the create-only Run on field belongs in Advanced immediately after instruction permissions, keeping the contributor rules aligned with the configuration rendering change.

Co-authored-by: Kenny Lopez <klopez4212@gmail.com>
Signed-off-by: Kenny Lopez <klopez4212@gmail.com>
---
 desktop/src/features/agents/AGENTS.md | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/desktop/src/features/agents/AGENTS.md b/desktop/src/features/agents/AGENTS.md
index f2eb7f285c..ecbb74837b 100644
--- a/desktop/src/features/agents/AGENTS.md
+++ b/desktop/src/features/agents/AGENTS.md
@@ -101,11 +101,13 @@ with a TypeScript lookup table or an id comparison in a component.
    Once the Advanced toggle is visible, its expanded state is exclusively
    user-controlled: provider, harness, and required-env changes must never
    open it automatically in defaults, create, or edit flows. In Create mode,
-   the defaults summary follows preferred-harness changes saved while the
-   dialog is open, and its configured state includes required credentials as
-   well as provider/model values. If no available harness can resolve, Create
-   starts in Customize and lets unavailable catalog entries be selected only
-   to expose their setup guidance; submission remains blocked.
+   `Run on` belongs in Advanced directly after **Who can send instructions**;
+   keep it out of the basic create fields. The defaults summary follows
+   preferred-harness changes saved while the dialog is open, and its configured
+   state includes required credentials as well as provider/model values. If no
+   available harness can resolve, Create starts in Customize and lets unavailable
+   catalog entries be selected only to expose their setup guidance; submission
+   remains blocked.
    Advanced-only required credentials mark the collapsed Advanced toggle
    without opening it in Global Defaults and Edit, and block incomplete saves.
    Runtime-file credentials satisfy Global Defaults just as they do Create and

From 189e218e1b63f7b3e95cda78517c3d5dfb257885 Mon Sep 17 00:00:00 2001
From: Watcher
 <bb7abfd757d0af7b66569d02ab9c0316b616f9d0c151ecf5b964344c462e7f8f@buzz.block.builderlab.xyz>
Date: Thu, 6 Aug 2026 16:40:13 +0100
Subject: [PATCH 3/5] fix(agents): avoid duplicate provider probes

Co-authored-by: Watcher <bb7abfd757d0af7b66569d02ab9c0316b616f9d0c151ecf5b964344c462e7f8f@buzz.block.builderlab.xyz>
Signed-off-by: Watcher <bb7abfd757d0af7b66569d02ab9c0316b616f9d0c151ecf5b964344c462e7f8f@buzz.block.builderlab.xyz>
---
 .../features/agents/ui/WhereToRunSection.tsx  |  4 ++--
 desktop/tests/e2e/where-to-run-config.spec.ts | 19 +++++++++++++++++--
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/desktop/src/features/agents/ui/WhereToRunSection.tsx b/desktop/src/features/agents/ui/WhereToRunSection.tsx
index 095690f937..eb2fc8f0f1 100644
--- a/desktop/src/features/agents/ui/WhereToRunSection.tsx
+++ b/desktop/src/features/agents/ui/WhereToRunSection.tsx
@@ -62,7 +62,7 @@ export function WhereToRunSection({
     ? (selectedBackendProvider?.binaryPath ?? null)
     : null;
   React.useEffect(() => {
-    if (!selectedBinaryPath) {
+    if (!selectedBinaryPath || draft.probedProvider) {
       setProbeError(null);
       return;
     }
@@ -81,7 +81,7 @@ export function WhereToRunSection({
     return () => {
       cancelled = true;
     };
-  }, [selectedBinaryPath]);
+  }, [selectedBinaryPath, draft.probedProvider]);
 
   if (backendProviders.length === 0) return null;
 
diff --git a/desktop/tests/e2e/where-to-run-config.spec.ts b/desktop/tests/e2e/where-to-run-config.spec.ts
index e0c0c459ad..cd0b18ba40 100644
--- a/desktop/tests/e2e/where-to-run-config.spec.ts
+++ b/desktop/tests/e2e/where-to-run-config.spec.ts
@@ -9,7 +9,8 @@
  *
  * Covers:
  *  - typing into a defaultless provider field sticks, and the provider is
- *    probed exactly once for the selection (not once per keystroke)
+ *    probed exactly once for the selection (not once per keystroke or
+ *    Advanced disclosure toggle)
  *  - the config form is gated on probe resolution (no half-rendered form),
  *    and defaults prefill exactly once when a slow probe lands
  *  - switching provider → local → provider re-probes and resets cleanly
@@ -131,7 +132,21 @@ test("typing into a defaultless provider field sticks and probes only once", asy
   await contextField.pressSequentially("prod-us-west", { delay: 20 });
   await expect(contextField).toHaveValue("prod-us-west");
 
-  // One selection, one probe — keystrokes must not refire it.
+  // One selection, one probe — keystrokes and Advanced disclosure toggles
+  // must not refire executable provider discovery after it has completed.
+  expect(await probeInvocations(page)).toBe(1);
+  const advanced = dialog.getByRole("button", {
+    name: "Advanced",
+    exact: true,
+  });
+  await advanced.click();
+  await expect(advanced).toHaveAttribute("aria-expanded", "false");
+  await expect(dialog.locator("#agent-run-on")).toHaveCount(0);
+  await advanced.click();
+  await expect(advanced).toHaveAttribute("aria-expanded", "true");
+  await expect(dialog.locator("#provider-cfg-context")).toHaveValue(
+    "prod-us-west",
+  );
   expect(await probeInvocations(page)).toBe(1);
 });
 

From d1fc9237180009fb1ccf46c3b9696d0129082308 Mon Sep 17 00:00:00 2001
From: kenny lopez <klopez4212@gmail.com>
Date: Thu, 6 Aug 2026 19:40:19 +0100
Subject: [PATCH 4/5] fix(agents): surface required run setup

Signed-off-by: kenny lopez <klopez4212@gmail.com>
---
 desktop/src/features/agents/AGENTS.md         |  5 ++--
 .../agents/ui/AgentDefinitionDialog.tsx       |  4 +--
 desktop/tests/e2e/where-to-run-config.spec.ts | 27 +++++++++++++++++++
 3 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/desktop/src/features/agents/AGENTS.md b/desktop/src/features/agents/AGENTS.md
index 3e7c3deb61..b578326eba 100644
--- a/desktop/src/features/agents/AGENTS.md
+++ b/desktop/src/features/agents/AGENTS.md
@@ -120,8 +120,9 @@ with a TypeScript lookup table or an id comparison in a component.
    available harness can resolve, Create starts in Customize and lets unavailable
    catalog entries be selected only to expose their setup guidance; submission
    remains blocked.
-   Advanced-only required credentials mark the collapsed Advanced toggle
-   without opening it in Global Defaults and Edit, and block incomplete saves.
+   Advanced-only required credentials and incomplete remote **Run on** setup
+   mark the collapsed Advanced toggle without opening it, and block incomplete
+   saves.
    Runtime-file credentials satisfy Global Defaults just as they do Create and
    Edit. In Edit,
    selecting Custom command keeps its required command field beside the harness
diff --git a/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx b/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx
index b3f8ee86a7..409ae6a821 100644
--- a/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx
+++ b/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx
@@ -961,7 +961,6 @@ export function AgentDefinitionDialog({
               onSaved={selectSavedHarness}
               open={isAddHarnessOpen}
             />
-
             <div className="space-y-3">
               <button
                 aria-expanded={showAdvancedFields}
@@ -970,7 +969,8 @@ export function AgentDefinitionDialog({
                 type="button"
               >
                 <span>Advanced</span>
-                {localModeGate.missingEnvKeys.some((key) =>
+                {(isCreateMode && createSubmitBlocked) ||
+                localModeGate.missingEnvKeys.some((key) =>
                   advancedRequiredEnvKeys.includes(key),
                 ) ? (
                   <span
diff --git a/desktop/tests/e2e/where-to-run-config.spec.ts b/desktop/tests/e2e/where-to-run-config.spec.ts
index cd0b18ba40..1aa2f5c126 100644
--- a/desktop/tests/e2e/where-to-run-config.spec.ts
+++ b/desktop/tests/e2e/where-to-run-config.spec.ts
@@ -13,6 +13,8 @@
  *    Advanced disclosure toggle)
  *  - the config form is gated on probe resolution (no half-rendered form),
  *    and defaults prefill exactly once when a slow probe lands
+ *  - collapsing Advanced during an incomplete remote setup keeps the submit
+ *    blocker visible through the Required badge
  *  - switching provider → local → provider re-probes and resets cleanly
  *
  * The stale-closure merge on probe resolution (defaults beneath in-flight
@@ -179,6 +181,31 @@ test("config fields render only after a slow probe resolves, with defaults", asy
   expect(await probeInvocations(page)).toBe(1);
 });
 
+test("collapsed Advanced marks incomplete remote setup as required", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    backendProviders: [PROVIDER],
+    backendProviderProbeResult: PROBE_RESULT,
+    backendProviderProbeDelayMs: 10_000,
+  });
+  const dialog = await openCreateDialogOnProvider(page);
+  const advanced = dialog.getByRole("button", {
+    name: "Advanced",
+    exact: true,
+  });
+  const submit = dialog.getByTestId("persona-dialog-submit");
+
+  await expect(submit).toBeDisabled();
+  await advanced.click();
+  await expect(advanced).toHaveAttribute("aria-expanded", "false");
+  await expect(dialog.locator("#agent-run-on")).toHaveCount(0);
+  await expect(
+    dialog.getByTestId("persona-advanced-required-badge"),
+  ).toHaveText("Required");
+  await expect(submit).toBeDisabled();
+});
+
 test("provider → local → provider re-probes and resets the config", async ({
   page,
 }) => {

From 198666a8804e09e2adf786a763aa1523f28aa8a3 Mon Sep 17 00:00:00 2001
From: kenny lopez <klopez4212@gmail.com>
Date: Thu, 6 Aug 2026 19:54:29 +0100
Subject: [PATCH 5/5] docs(desktop): describe shared composer glass

Signed-off-by: kenny lopez <klopez4212@gmail.com>
---
 desktop/src/features/messages/ui/ComposerDockBackdrop.tsx | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/desktop/src/features/messages/ui/ComposerDockBackdrop.tsx b/desktop/src/features/messages/ui/ComposerDockBackdrop.tsx
index edf4c61fa1..0e237d5145 100644
--- a/desktop/src/features/messages/ui/ComposerDockBackdrop.tsx
+++ b/desktop/src/features/messages/ui/ComposerDockBackdrop.tsx
@@ -5,6 +5,10 @@ type ComposerDockGlassBackdropProps = {
   testId?: string;
 };
 
+/**
+ * Applies the composer dock's shared blur without adding color or layout.
+ * Reuse it for composer-adjacent surfaces that need the same glass treatment.
+ */
 export function ComposerDockGlassBackdrop({
   className,
   testId,