From 8b68d3493438d37eeea04a996cbe975140197a6c Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Mon, 3 Aug 2026 20:05:14 +0800
Subject: [PATCH 1/8] redesign(desktop): rebuild the subagent settings page on
 the settings route idiom
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#1999 shipped 设置 · 子 Agent as a list of dense rows over a 560px Dialog
holding eight fields behind an inner scrollbar, plus three hand-written
`.subagentPreset*` CSS rules. A modal exists to interrupt the current task
for something short and immediately decidable; naming a capability, writing
the guidance the main agent selects on, and picking a connection/model/
thinking route is none of those — Astryx says the same ("if the content
grows beyond what fits, consider a full page instead"), and the providers
panel next door already answers this exact shape with a route level.

- the editor becomes the page's second level (list ── editor), reusing
  `settingsRouteLevel` + the back-header Toolbar rather than a Dialog;
- `RouteHeader`, private to ProvidersPanel, moves to `settings-route-header`
  as the one way back from a settings sub-level, so the shape is not
  written twice;
- the page drops all three CSS rules: the flex-wrap action cluster is the
  row end slot, the oklch-tinted callout is `Banner status="warning"`, and
  the flex-end button row is a plain action row;
- rows carry the name, the guidance, and a badge ONLY when the preset
  cannot be selected — a list where every row says 可用 says nothing. The
  route, the id, and the capability boundary are the editor's answer;
- the list group loses its title and lede, which restated the page heading
  verbatim; the preset ceiling speaks only once it is hit;
- 立即启用 leaves the editor: whether the main agent may select a preset is
  the list row's switch, which was already answering it;
- a new preset's subagent_id starts empty (the name fills it) instead of
  pre-deriving `subagent`, and a saved one reads as a settled row value
  rather than a disabled input;
- delete moves out of the row into its own trailing section, so nothing
  quiet sits beside the destructive action.

Presentation only: availability, validation, id immutability, and the
`settings.update({ subagents })` contract are unchanged.

Verified: typecheck, lint, format:check, check-dead-css, check-a11y/copy/
console, 1379 desktop unit tests, Storybook smoke (75 renders), and
settings + providers e2e. Story gains SubagentEditorExisting for the
read-only id, the implementation warning, and the delete section.
---
 apps/desktop/e2e/settings.spec.ts             |  14 +-
 .../locales/settings-subagents-copy.ts        |  65 +--
 .../src/renderer/settings/ProvidersPanel.tsx  |  52 +-
 .../settings/settings-route-header.tsx        |  57 ++
 .../settings/subagent-settings-page.tsx       | 511 ++++++++++--------
 .../src/renderer/styles/settings/models.css   |  28 -
 .../settings/settings-pages.stories.tsx       |  18 +-
 7 files changed, 398 insertions(+), 347 deletions(-)
 create mode 100644 apps/desktop/src/renderer/settings/settings-route-header.tsx

diff --git a/apps/desktop/e2e/settings.spec.ts b/apps/desktop/e2e/settings.spec.ts
index 0411971704..630340d5ed 100644
--- a/apps/desktop/e2e/settings.spec.ts
+++ b/apps/desktop/e2e/settings.spec.ts
@@ -55,15 +55,15 @@ test('subagent presets can be reviewed and edited in desktop settings', async ({
   const settings = page.getByRole('main', { name: '设置内容' });
   await expect(settings.getByRole('heading', { name: '子 Agent', exact: true })).toBeVisible();
   await expect(settings.getByText('E2E 快速阅读', { exact: true })).toBeVisible();
-  await expect(settings.getByText('可用', { exact: true })).toBeVisible();
 
-  await settings.getByRole('button', { name: '编辑', exact: true }).click();
-  const dialog = page.getByRole('dialog', { name: '编辑子 Agent' });
-  const description = dialog.getByRole('textbox', { name: '适用场景' });
-  await description.fill('快速阅读代码，并总结关键调用链。');
-  await dialog.getByRole('button', { name: '保存', exact: true }).click();
+  // The editor is a route level, not a dialog: the list is replaced in place
+  // and the back affordance is the only way out.
+  await settings.getByRole('button', { name: '配置“E2E 快速阅读”' }).click();
+  await expect(settings.getByRole('heading', { name: 'E2E 快速阅读', exact: true })).toBeVisible();
+  await settings.getByRole('textbox', { name: '适用场景' }).fill('快速阅读代码，并总结关键调用链。');
+  await settings.getByRole('button', { name: '保存', exact: true }).click();
 
-  await expect(dialog).toBeHidden();
+  await expect(settings.getByRole('button', { name: '添加子 Agent' })).toBeVisible();
   await expect(settings.getByText('快速阅读代码，并总结关键调用链。', { exact: true })).toBeVisible();
   await expect.poll(async () => page.evaluate(async () => {
     const current = await window.maka.settings.get();
diff --git a/apps/desktop/src/renderer/locales/settings-subagents-copy.ts b/apps/desktop/src/renderer/locales/settings-subagents-copy.ts
index 71f7aad786..6faa0cedae 100644
--- a/apps/desktop/src/renderer/locales/settings-subagents-copy.ts
+++ b/apps/desktop/src/renderer/locales/settings-subagents-copy.ts
@@ -12,48 +12,45 @@ type ProfileCopy = {
 
 export type SubagentSettingsCopy = {
   section: {
-    title: string;
-    description: string;
-    count(enabled: number, total: number): string;
     add: string;
-    limitReached: string;
+    limitNote: string;
     emptyTitle: string;
     emptyDescription: string;
   };
   row: {
-    edit: string;
-    remove: string;
     enabled: string;
+    configure(name: string): string;
     fallbackDescription: string;
-    route(profile: string, connection: string, model: string, thinking?: string): string;
   };
   status: {
-    available: string;
     disabled: string;
     missingConnection: string;
     connectionDisabled: string;
     modelDisabled: string;
   };
   editor: {
+    backToList: string;
     createTitle: string;
     createSubtitle: string;
-    editTitle: string;
     editSubtitle: string;
+    groupPurpose: string;
+    groupPurposeHelp: string;
+    groupRoute: string;
+    groupRouteHelp: string;
+    dangerZone: string;
+    delete: string;
     name: string;
     namePlaceholder: string;
     id: string;
     idDescription: string;
     idPlaceholder: string;
     description: string;
-    descriptionHelp: string;
     descriptionPlaceholder: string;
     profile: string;
     connection: string;
     model: string;
     thinking: string;
     defaultThinking: string;
-    enabled: string;
-    enabledDescription: string;
     implementationWarning: string;
     noConnection: string;
     noModel: string;
@@ -83,49 +80,45 @@ export type SubagentSettingsCopy = {
 const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
   zh: {
     section: {
-      title: '已批准的子 Agent',
-      description: '主 Agent 会根据适用场景，从已启用且可用的配置中选择。每个配置固定自己的能力边界、连接和模型。',
-      count: (enabled, total) => `已启用 ${enabled} / 共 ${total}`,
       add: '添加子 Agent',
-      limitReached: '已达到 64 个配置的上限',
+      limitNote: '已达到 64 个配置的上限。',
       emptyTitle: '还没有子 Agent 配置',
       emptyDescription: '添加一个配置后，主 Agent 就能把合适的任务交给独立模型处理。',
     },
     row: {
-      edit: '编辑',
-      remove: '删除',
       enabled: '启用',
+      configure: (name) => `配置“${name}”`,
       fallbackDescription: '尚未填写适用场景',
-      route: (profile, connection, model, thinking) =>
-        `${profile} · ${connection} / ${model}${thinking ? ` · 思考 ${thinking}` : ''}`,
     },
     status: {
-      available: '可用',
       disabled: '已停用',
       missingConnection: '连接不存在',
       connectionDisabled: '连接已停用',
       modelDisabled: '模型未启用',
     },
     editor: {
+      backToList: '返回子 Agent 列表',
       createTitle: '添加子 Agent',
       createSubtitle: '创建一个可由主 Agent 自动选择的模型配置。',
-      editTitle: '编辑子 Agent',
       editSubtitle: '修改适用场景、能力边界和模型路由。',
+      groupPurpose: '用途',
+      groupPurposeHelp: '主 Agent 主要根据这里的名称和适用场景挑选配置。',
+      groupRoute: '能力与模型',
+      groupRouteHelp: '固定这个子 Agent 能做什么，以及它运行在哪个模型上。',
+      dangerZone: '删除子 Agent',
+      delete: '删除',
       name: '显示名称',
       namePlaceholder: '快速代码阅读',
       id: 'subagent_id',
       idDescription: '创建后保持不变，主 Agent 和历史会话会用它识别此配置。',
       idPlaceholder: 'fast-reader',
       description: '适用场景',
-      descriptionHelp: '写清楚何时应该使用它；主 Agent 主要根据这段描述挑选配置。',
       descriptionPlaceholder: '适合快速、低成本地阅读大型仓库',
       profile: '能力 Profile',
       connection: '模型连接',
       model: '模型',
       thinking: '思考级别',
       defaultThinking: '跟随模型默认',
-      enabled: '立即启用',
-      enabledDescription: '启用后，主 Agent 可以选择这个配置。',
       implementationWarning: '实现代码 Profile 可以写文件和执行命令，并会在隔离 worktree 中运行。',
       noConnection: '请先在“模型”页启用一个模型连接。',
       noModel: '所选连接没有已启用的模型。',
@@ -165,49 +158,45 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
   },
   en: {
     section: {
-      title: 'Approved subagents',
-      description: 'The main agent selects from enabled, available presets based on when each should be used. Every preset fixes its capability boundary, connection, and model.',
-      count: (enabled, total) => `${enabled} enabled · ${total} total`,
       add: 'Add subagent',
-      limitReached: 'The 64-preset limit has been reached',
+      limitNote: 'The 64-preset limit has been reached.',
       emptyTitle: 'No subagent presets yet',
       emptyDescription: 'Add a preset so the main agent can delegate suitable work to a separate model.',
     },
     row: {
-      edit: 'Edit',
-      remove: 'Remove',
       enabled: 'Enabled',
+      configure: (name) => `Configure “${name}”`,
       fallbackDescription: 'No usage guidance yet',
-      route: (profile, connection, model, thinking) =>
-        `${profile} · ${connection} / ${model}${thinking ? ` · Thinking ${thinking}` : ''}`,
     },
     status: {
-      available: 'Available',
       disabled: 'Disabled',
       missingConnection: 'Connection missing',
       connectionDisabled: 'Connection disabled',
       modelDisabled: 'Model not enabled',
     },
     editor: {
+      backToList: 'Back to subagents',
       createTitle: 'Add subagent',
       createSubtitle: 'Create a model preset that the main agent can select automatically.',
-      editTitle: 'Edit subagent',
       editSubtitle: 'Change its usage guidance, capability boundary, and model route.',
+      groupPurpose: 'Purpose',
+      groupPurposeHelp: 'The main agent selects a preset primarily from the name and guidance here.',
+      groupRoute: 'Capability and model',
+      groupRouteHelp: 'Fix what this subagent may do, and which model it runs on.',
+      dangerZone: 'Remove subagent',
+      delete: 'Remove',
       name: 'Display name',
       namePlaceholder: 'Fast code reader',
       id: 'subagent_id',
       idDescription: 'Stable after creation. The main agent and session history use it to identify this preset.',
       idPlaceholder: 'fast-reader',
       description: 'When to use',
-      descriptionHelp: 'Describe when this preset is the right choice. The main agent relies primarily on this guidance.',
       descriptionPlaceholder: 'Fast, low-cost exploration of large repositories',
       profile: 'Capability profile',
       connection: 'Model connection',
       model: 'Model',
       thinking: 'Thinking level',
       defaultThinking: 'Use model default',
-      enabled: 'Enable immediately',
-      enabledDescription: 'When enabled, the main agent may select this preset.',
       implementationWarning: 'The Implementation profile can write files and run commands inside an isolated worktree.',
       noConnection: 'Enable a model connection on the Models page first.',
       noModel: 'The selected connection has no enabled models.',
diff --git a/apps/desktop/src/renderer/settings/ProvidersPanel.tsx b/apps/desktop/src/renderer/settings/ProvidersPanel.tsx
index 1e2639f203..c2d508df7e 100644
--- a/apps/desktop/src/renderer/settings/ProvidersPanel.tsx
+++ b/apps/desktop/src/renderer/settings/ProvidersPanel.tsx
@@ -31,6 +31,7 @@ import {
   type SetupTarget,
 } from './provider-catalog-page';
 import { ConnectionDetail } from './provider-connection-detail';
+import { SettingsRouteHeader } from './settings-route-header';
 import { ProviderLogo, providerDisplay } from './provider-display';
 import { oauthPanelSubtitle } from './provider-oauth-section';
 import { providerPanelActionErrorMessage, type ConnectionsBridge } from './provider-panel-shared';
@@ -275,7 +276,7 @@ export function ProvidersPanel({ bridge, initialPage = 'connections', initialCon
         // the standard SPA answer to "where does focus go when the page
         // swaps", and it draws no ring.
         <VStack gap={5} tabIndex={-1} className="settingsRouteLevel" data-maka-contract="connection-detail">
-          <RouteHeader
+          <SettingsRouteHeader
             onBack={goToList}
             backLabel={copy.backToList}
             contract="connection-detail-back"
@@ -299,7 +300,7 @@ export function ProvidersPanel({ bridge, initialPage = 'connections', initialCon
         </VStack>
       ) : level === 'catalog' ? (
         <VStack gap={5}>
-          <RouteHeader
+          <SettingsRouteHeader
             onBack={goToList}
             backLabel={copy.backToList}
             contract="catalog-back"
@@ -314,7 +315,7 @@ export function ProvidersPanel({ bridge, initialPage = 'connections', initialCon
         </VStack>
       ) : level === 'setup' && route.kind === 'setup' ? (
         <VStack gap={5}>
-          <RouteHeader
+          <SettingsRouteHeader
             onBack={goBack}
             backLabel={route.origin === 'catalog' ? copy.backToCatalog : copy.backToList}
             contract="setup-back"
@@ -435,51 +436,6 @@ export function ProvidersPanel({ bridge, initialPage = 'connections', initialCon
   }
 }
 
-/**
- * The way out of any level below the list, spelled once. Modelled on the
- * settings-sidebar template's detail view, which puts the same Toolbar inside
- * the content area rather than reaching for a second page shell.
- */
-function RouteHeader(props: {
-  onBack(): void;
-  backLabel: string;
-  contract: string;
-  logo?: ReactNode;
-  title: string;
-  badge?: ReactNode;
-  subtitle?: string;
-}) {
-  return (
-    <Toolbar
-      label={props.title}
-      gap={2}
-      startContent={(
-        <>
-          <IconButton
-            variant="ghost"
-            label={props.backLabel}
-            tooltip={props.backLabel}
-            icon={<ArrowLeft size={16} aria-hidden="true" />}
-            onClick={props.onBack}
-            data-maka-contract={props.contract}
-          />
-          {props.logo}
-          <VStack gap={0}>
-            <HStack gap={2} vAlign="center">
-              <Heading level={3}>{props.title}</Heading>
-              {props.badge}
-            </HStack>
-            {props.subtitle && (
-              <Text type="supporting" color="secondary">{props.subtitle}</Text>
-            )}
-          </VStack>
-        </>
-      )}
-    />
-  );
-}
-
-
 /** Provider · default model — the row's second line, and the detail's subtitle. */
 function connectionSubtitle(connection: LlmConnection, locale: 'zh' | 'en'): string {
   const providerName = providerDisplay(connection.providerType, locale).name;
diff --git a/apps/desktop/src/renderer/settings/settings-route-header.tsx b/apps/desktop/src/renderer/settings/settings-route-header.tsx
new file mode 100644
index 0000000000..18512ec0c6
--- /dev/null
+++ b/apps/desktop/src/renderer/settings/settings-route-header.tsx
@@ -0,0 +1,57 @@
+// The header of a settings sub-level: back affordance, title, and one quiet
+// line of context.
+//
+// A settings page that owns more than one level (a list and the detail behind
+// a row) needs exactly one way back. This was private to `ProvidersPanel`,
+// where the four-level provider route lives; the subagent page needs the same
+// two-level shape, so the header moved here rather than being written twice.
+//
+// Deliberately a `Toolbar` with everything in `startContent`: the back button,
+// the optional logo, and the title block read as one left-aligned cluster, so
+// the title sits where the list's rows started and the eye does not travel.
+// Modelled on the settings-sidebar template's detail view, which puts this
+// same Toolbar inside the content area rather than reaching for a second page
+// shell.
+import type { ReactNode } from 'react';
+import { Heading, HStack, IconButton, Text, Toolbar, VStack } from '@astryxdesign/core';
+import { ArrowLeft } from '@maka/ui/icons';
+
+export function SettingsRouteHeader(props: {
+  onBack(): void;
+  backLabel: string;
+  /** `data-maka-contract` on the back button, so an e2e can aim at this level. */
+  contract: string;
+  logo?: ReactNode;
+  title: string;
+  badge?: ReactNode;
+  subtitle?: string;
+}) {
+  return (
+    <Toolbar
+      label={props.title}
+      gap={2}
+      startContent={(
+        <>
+          <IconButton
+            variant="ghost"
+            label={props.backLabel}
+            tooltip={props.backLabel}
+            icon={<ArrowLeft size={16} aria-hidden="true" />}
+            onClick={props.onBack}
+            data-maka-contract={props.contract}
+          />
+          {props.logo}
+          <VStack gap={0}>
+            <HStack gap={2} vAlign="center">
+              <Heading level={3}>{props.title}</Heading>
+              {props.badge}
+            </HStack>
+            {props.subtitle && (
+              <Text type="supporting" color="secondary">{props.subtitle}</Text>
+            )}
+          </VStack>
+        </>
+      )}
+    />
+  );
+}
diff --git a/apps/desktop/src/renderer/settings/subagent-settings-page.tsx b/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
index 94aee9bfd4..6705e47375 100644
--- a/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
+++ b/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
@@ -1,7 +1,26 @@
+// 设置 · 子 Agent — the approved model routes the main agent may delegate to.
+//
+// Two levels, one container, one back affordance, and nothing modal:
+//
+//   list ── editor(new | existing)
+//
+// The editor was a 560px Dialog holding eight fields behind an inner
+// scrollbar. A modal exists to interrupt the current task for something short
+// and immediately decidable while preserving the context behind it; naming a
+// capability, writing the guidance the main agent selects on, and picking a
+// connection/model/thinking route is none of those. Astryx says the same —
+// "if the content grows beyond what fits, consider a full page instead" — and
+// the providers panel next door already answers this exact shape with a route
+// level, so this page follows it rather than inventing a second answer.
+//
+// Every element here is a settings-kit part (`SettingsSection`, `SettingsRow`,
+// `SettingsField`, `SettingsActions`) or an Astryx primitive. The page owns no
+// CSS: the three hand-written `.subagentPreset*` rules — a flex-wrap action
+// cluster, an oklch-tinted warning callout, and a flex-end button row — were
+// each a restatement of something the kit or Astryx already draws (the row end
+// slot, `Banner status="warning"`, `SettingsActions`).
 import { useMemo, useState } from 'react';
-import { Badge, HStack, Text, VStack } from '@astryxdesign/core';
-import { Dialog, DialogHeader } from '@astryxdesign/core/Dialog';
-import { Layout, LayoutContent } from '@astryxdesign/core/Layout';
+import { Badge, Banner, HStack, VStack } from '@astryxdesign/core';
 import {
   connectionEnabledModelIds,
   isSafeSubagentPresetId,
@@ -17,7 +36,7 @@ import {
 import {
   Button,
   EmptyState,
-  FormLayout,
+  IconButton,
   Selector,
   Switch,
   TextArea,
@@ -26,16 +45,26 @@ import {
   useToast,
   useUiLocale,
 } from '@maka/ui';
-import { AlertTriangle } from '@maka/ui/icons';
+import { ChevronRight } from '@maka/ui/icons';
 import { getSubagentSettingsCopy } from '../locales/settings-subagents-copy.js';
 import { settingsActionErrorMessage } from './settings-error-copy.js';
-import { SettingsPage, SettingsRow, SettingsSection } from './settings-section.js';
+import { SettingsRouteHeader } from './settings-route-header.js';
+import {
+  SettingsActions,
+  SettingsField,
+  SettingsPage,
+  SettingsRow,
+  SettingsSection,
+} from './settings-section.js';
 import {
   subagentPresetAvailability,
   suggestSubagentPresetId,
 } from './subagent-preset-presentation.js';
 import { statusBadgeVariant } from './settings-status-badge.js';
 
+/** `null` is the unsaved new preset; a string is an existing preset's id. */
+type EditorRoute = { presetId: string | null };
+
 type EditorDraft = {
   id: string;
   name: string;
@@ -44,7 +73,6 @@ type EditorDraft = {
   connectionSlug: string;
   model: string;
   thinkingLevel: ThinkingLevel | '';
-  enabled: boolean;
 };
 
 export function SubagentSettingsPage(props: {
@@ -57,13 +85,12 @@ export function SubagentSettingsPage(props: {
   const locale = useUiLocale();
   const copy = getSubagentSettingsCopy(locale);
   const toast = useToast();
-  const [editorPresetId, setEditorPresetId] = useState<string | null | undefined>(undefined);
+  const [route, setRoute] = useState<EditorRoute | null>(null);
   const [saving, setSaving] = useState(false);
   const presets = props.settings.subagents.presets;
-  const editorPreset = editorPresetId == null
+  const editorPreset = route?.presetId == null
     ? null
-    : presets.find((preset) => preset.id === editorPresetId) ?? null;
-  const enabledCount = presets.filter((preset) => preset.enabled).length;
+    : presets.find((preset) => preset.id === route.presetId) ?? null;
   const atLimit = presets.length >= MAX_SUBAGENT_PRESETS;
 
   async function persist(nextPresets: SubagentPreset[]): Promise<boolean> {
@@ -79,13 +106,6 @@ export function SubagentSettingsPage(props: {
     }
   }
 
-  async function savePreset(next: SubagentPreset): Promise<boolean> {
-    const nextPresets = editorPresetId == null
-      ? [...presets, next]
-      : presets.map((candidate) => candidate.id === editorPresetId ? next : candidate);
-    return persist(nextPresets);
-  }
-
   async function removePreset(preset: SubagentPreset): Promise<void> {
     const confirmed = await toast.confirm({
       title: copy.remove.title(preset.name),
@@ -95,21 +115,61 @@ export function SubagentSettingsPage(props: {
       destructive: true,
     });
     if (!confirmed) return;
-    await persist(presets.filter((candidate) => candidate.id !== preset.id));
+    const removed = await persist(presets.filter((candidate) => candidate.id !== preset.id));
+    if (removed) setRoute(null);
+  }
+
+  if (route) {
+    return (
+      // tabIndex -1 so the level itself can take focus when it lands, instead
+      // of dropping a keyboard user on document.body. It draws no ring.
+      <VStack
+        gap={5}
+        tabIndex={-1}
+        className="settingsRouteLevel"
+        data-maka-contract="subagent-detail"
+      >
+        <SettingsRouteHeader
+          onBack={() => setRoute(null)}
+          backLabel={copy.editor.backToList}
+          contract="subagent-detail-back"
+          title={editorPreset ? editorPreset.name : copy.editor.createTitle}
+          subtitle={editorPreset ? copy.editor.editSubtitle : copy.editor.createSubtitle}
+        />
+        <SubagentPresetEditor
+          key={editorPreset?.id ?? 'new'}
+          preset={editorPreset}
+          presets={presets}
+          connections={props.connections}
+          isSaving={saving}
+          onCancel={() => setRoute(null)}
+          onDelete={editorPreset ? () => void removePreset(editorPreset) : undefined}
+          onSave={async (next) => {
+            const nextPresets = editorPreset
+              ? presets.map((candidate) => candidate.id === editorPreset.id ? next : candidate)
+              : [...presets, next];
+            if (await persist(nextPresets)) setRoute(null);
+          }}
+        />
+      </VStack>
+    );
   }
 
   return (
     <SettingsPage className="settingsSubagentsPage">
+      {/* The page's single lead group, so it carries no title of its own: the
+          settings surface already heads it 子 Agent over the same sentence,
+          and a section title here was that heading a second time. Only the
+          preset ceiling has anything left to say, and only once it is hit. */}
       <SettingsSection
-        title={copy.section.title}
-        description={`${copy.section.description} ${copy.section.count(enabledCount, presets.length)}`}
+        description={atLimit ? copy.section.limitNote : undefined}
         action={(
           <Button
             variant="primary"
             size="sm"
-            label={atLimit ? copy.section.limitReached : copy.section.add}
+            label={copy.section.add}
             isDisabled={saving || atLimit}
-            onClick={() => setEditorPresetId(null)}
+            onClick={() => setRoute({ presetId: null })}
           />
         )}
       >
@@ -122,26 +182,22 @@ export function SubagentSettingsPage(props: {
                 variant="primary"
                 label={copy.section.add}
                 isDisabled={saving}
-                onClick={() => setEditorPresetId(null)}
+                onClick={() => setRoute({ presetId: null })}
               />
             )}
           />
         ) : presets.map((preset) => {
           const availability = subagentPresetAvailability(preset, props.connections);
-          const connection = props.connections.find(
-            (candidate) => candidate.slug === preset.connectionSlug,
-          );
-          const profile = copy.profiles[preset.profile];
-          const statusLabel = {
-            available: copy.status.available,
+          // A row states what the preset is for; its route, its id, and its
+          // capability boundary are the editor's answer, one level in. Only a
+          // preset that cannot currently be selected carries a badge — a list
+          // where every row says 可用 says nothing.
+          const problem = availability.kind === 'available' ? null : {
             disabled: copy.status.disabled,
             missing_connection: copy.status.missingConnection,
             connection_disabled: copy.status.connectionDisabled,
             model_disabled: copy.status.modelDisabled,
           }[availability.kind];
-          const thinking = preset.thinkingLevel
-            ? copy.thinking[preset.thinkingLevel]
-            : undefined;
           return (
             <SettingsRow
               key={preset.id}
@@ -149,29 +205,14 @@ export function SubagentSettingsPage(props: {
               label={(
                 <HStack gap={2} vAlign="center" wrap="wrap">
                   <span>{preset.name}</span>
-                  <Badge
-                    variant={statusBadgeVariant(availability.tone)}
-                    label={statusLabel}
-                  />
+                  {problem ? (
+                    <Badge variant={statusBadgeVariant(availability.tone)} label={problem} />
+                  ) : null}
                 </HStack>
               )}
-              description={(
-                <VStack gap={0.5}>
-                  <span>{preset.description || copy.row.fallbackDescription}</span>
-                  <Text type="supporting" size="sm" color="secondary">
-                    {copy.row.route(
-                      profile.label,
-                      connection?.name ?? preset.connectionSlug,
-                      preset.model,
-                      thinking,
-                    )}
-                    {' · '}
-                    <code>{preset.id}</code>
-                  </Text>
-                </VStack>
-              )}
+              description={preset.description || copy.row.fallbackDescription}
               end={(
-                <div className="subagentPresetActions">
+                <>
                   <Switch
                     label={`${copy.row.enabled}: ${preset.name}`}
                     isLabelHidden
@@ -185,41 +226,21 @@ export function SubagentSettingsPage(props: {
                       );
                     }}
                   />
-                  <Button
-                    variant="secondary"
-                    size="sm"
-                    label={copy.row.edit}
-                    isDisabled={saving}
-                    onClick={() => setEditorPresetId(preset.id)}
-                  />
-                  <Button
+                  <IconButton
                     variant="ghost"
                     size="sm"
-                    label={copy.row.remove}
+                    label={copy.row.configure(preset.name)}
+                    tooltip={copy.row.configure(preset.name)}
+                    icon={<ChevronRight size={16} aria-hidden="true" />}
                     isDisabled={saving}
-                    onClick={() => void removePreset(preset)}
+                    onClick={() => setRoute({ presetId: preset.id })}
                   />
-                </div>
+                </>
               )}
             />
           );
         })}
       </SettingsSection>
-
-      {editorPresetId !== undefined ? (
-        <SubagentPresetEditor
-          key={editorPreset?.id ?? 'new'}
-          preset={editorPreset}
-          presets={presets}
-          connections={props.connections}
-          isSaving={saving}
-          onClose={() => setEditorPresetId(undefined)}
-          onSave={async (next) => {
-            const saved = await savePreset(next);
-            if (saved) setEditorPresetId(undefined);
-          }}
-        />
-      ) : null}
     </SettingsPage>
   );
 }
@@ -229,7 +250,8 @@ function SubagentPresetEditor(props: {
   presets: readonly SubagentPreset[];
   connections: readonly LlmConnection[];
   isSaving: boolean;
-  onClose(): void;
+  onCancel(): void;
+  onDelete?(): void;
   onSave(preset: SubagentPreset): Promise<void>;
 }) {
   const locale = useUiLocale();
@@ -249,14 +271,16 @@ function SubagentPresetEditor(props: {
     ? connectionEnabledModelIds(initialConnection)
     : [];
   const [draft, setDraft] = useState<EditorDraft>(() => ({
-    id: props.preset?.id ?? suggestSubagentPresetId('', existingIds),
+    // Empty, not a pre-derived `subagent`: an id the user has not been asked
+    // for yet reads as a value the page already decided. Typing the name fills
+    // it (until the user takes it over), and the placeholder says what it is.
+    id: props.preset?.id ?? '',
     name: props.preset?.name ?? '',
     description: props.preset?.description ?? '',
     profile: props.preset?.profile ?? 'local_read',
     connectionSlug: props.preset?.connectionSlug ?? usableConnections[0]?.slug ?? '',
     model: props.preset?.model ?? initialModels[0] ?? '',
     thinkingLevel: props.preset?.thinkingLevel ?? '',
-    enabled: props.preset?.enabled ?? true,
   }));
   const [idWasEdited, setIdWasEdited] = useState(props.preset !== null);
   const [submitted, setSubmitted] = useState(false);
@@ -328,10 +352,6 @@ function SubagentPresetEditor(props: {
     }));
   }
 
-  function selectModel(model: string): void {
-    setDraft((current) => ({ ...current, model, thinkingLevel: '' }));
-  }
-
   async function submit(): Promise<void> {
     setSubmitted(true);
     if (!canSave) return;
@@ -343,7 +363,10 @@ function SubagentPresetEditor(props: {
       connectionSlug: draft.connectionSlug,
       model: draft.model,
       ...(draft.thinkingLevel ? { thinkingLevel: draft.thinkingLevel } : {}),
-      enabled: draft.enabled,
+      // A preset is created ready to use, and whether the main agent may still
+      // select it is the list row's switch — the one place that answers it. A
+      // second "enable now" control in here answered the same question twice.
+      enabled: props.preset?.enabled ?? true,
     });
   }
 
@@ -354,152 +377,190 @@ function SubagentPresetEditor(props: {
       : undefined;
 
   return (
-    <Dialog
-      isOpen
-      onOpenChange={(isOpen) => { if (!isOpen) props.onClose(); }}
-      className="subagentPresetEditorDialog"
-      width={560}
-      maxHeight="calc(100dvh - 80px)"
-      purpose="form"
-    >
-      <Layout
-        header={(
-          <DialogHeader
-            title={props.preset ? copy.editor.editTitle : copy.editor.createTitle}
-            subtitle={props.preset ? copy.editor.editSubtitle : copy.editor.createSubtitle}
-            onOpenChange={(isOpen) => { if (!isOpen) props.onClose(); }}
+    <SettingsPage>
+      {/* Name and guidance are prose the user writes, so they are full-width
+          fields, not values crammed into a row's end slot. */}
+      <SettingsSection title={copy.editor.groupPurpose} description={copy.editor.groupPurposeHelp}>
+        <SettingsField>
+          <TextInput
+            label={copy.editor.name}
+            value={draft.name}
+            placeholder={copy.editor.namePlaceholder}
+            isDisabled={props.isSaving}
+            status={submitted && !draft.name.trim()
+              ? { type: 'error', message: copy.editor.requiredName }
+              : undefined}
+            onChange={updateName}
           />
+        </SettingsField>
+        <SettingsField>
+          <TextArea
+            label={copy.editor.description}
+            value={draft.description}
+            placeholder={copy.editor.descriptionPlaceholder}
+            rows={3}
+            isDisabled={props.isSaving}
+            status={submitted && !draft.description.trim()
+              ? { type: 'error', message: copy.editor.requiredDescription }
+              : undefined}
+            onChange={(description) => setDraft((current) => ({ ...current, description }))}
+          />
+        </SettingsField>
+        {/* An existing id is a settled fact — session history and the main
+            agent's routing both reference it — so it reads as a row's value.
+            Only a new preset's id is still the user's to type. */}
+        {props.preset ? (
+          <SettingsRow
+            label={copy.editor.id}
+            description={copy.editor.idDescription}
+            align="start"
+            end={<code className="settingsReadOnlyValue">{props.preset.id}</code>}
+          />
+        ) : (
+          <SettingsField>
+            <TextInput
+              label={copy.editor.id}
+              description={copy.editor.idDescription}
+              value={draft.id}
+              placeholder={copy.editor.idPlaceholder}
+              isDisabled={props.isSaving}
+              status={idStatus}
+              onChange={(id) => {
+                setIdWasEdited(true);
+                setDraft((current) => ({ ...current, id }));
+              }}
+            />
+          </SettingsField>
         )}
-        content={(
-          <LayoutContent padding={6} isScrollable>
-            <FormLayout>
-              <TextInput
-                label={copy.editor.name}
-                value={draft.name}
-                placeholder={copy.editor.namePlaceholder}
-                isDisabled={props.isSaving}
-                status={submitted && !draft.name.trim()
-                  ? { type: 'error', message: copy.editor.requiredName }
-                  : undefined}
-                onChange={updateName}
-              />
-              <TextInput
-                label={copy.editor.id}
-                description={copy.editor.idDescription}
-                value={draft.id}
-                placeholder={copy.editor.idPlaceholder}
-                isDisabled={props.preset !== null || props.isSaving}
-                status={idStatus}
-                onChange={(id) => {
-                  setIdWasEdited(true);
-                  setDraft((current) => ({ ...current, id }));
-                }}
-              />
-              <TextArea
-                label={copy.editor.description}
-                description={copy.editor.descriptionHelp}
-                value={draft.description}
-                placeholder={copy.editor.descriptionPlaceholder}
-                rows={3}
-                isDisabled={props.isSaving}
-                status={submitted && !draft.description.trim()
-                  ? { type: 'error', message: copy.editor.requiredDescription }
+      </SettingsSection>
+
+      <SettingsSection title={copy.editor.groupRoute} description={copy.editor.groupRouteHelp}>
+        <SettingsRow
+          label={copy.editor.profile}
+          description={profileCopy.description}
+          align="start"
+          end={(
+            <Selector
+              label={copy.editor.profile}
+              isLabelHidden
+              value={draft.profile}
+              options={(Object.keys(copy.profiles) as SubagentProfile[]).map((profile) => ({
+                value: profile,
+                label: copy.profiles[profile].label,
+              }))}
+              width="100%"
+              isDisabled={props.isSaving}
+              onChange={(profile) => setDraft((current) => ({
+                ...current,
+                profile: profile as SubagentProfile,
+              }))}
+            />
+          )}
+        />
+        {draft.profile === 'implementation' ? (
+          <SettingsField>
+            <Banner status="warning" title={copy.editor.implementationWarning} />
+          </SettingsField>
+        ) : null}
+        <SettingsRow
+          label={copy.editor.connection}
+          end={(
+            <Selector
+              label={copy.editor.connection}
+              isLabelHidden
+              value={draft.connectionSlug}
+              options={connectionOptions}
+              width="100%"
+              isDisabled={props.isSaving || usableConnections.length === 0}
+              disabledMessage={usableConnections.length === 0 ? copy.editor.noConnection : undefined}
+              status={submitted && !validRoute
+                ? { type: 'error', message: copy.editor.invalidRoute }
+                : usableConnections.length === 0
+                  ? { type: 'warning', message: copy.editor.noConnection }
                   : undefined}
-                onChange={(description) => setDraft((current) => ({ ...current, description }))}
-              />
+              onChange={selectConnection}
+            />
+          )}
+        />
+        <SettingsRow
+          label={copy.editor.model}
+          end={(
+            <Selector
+              label={copy.editor.model}
+              isLabelHidden
+              value={draft.model}
+              options={modelOptions}
+              width="100%"
+              isDisabled={props.isSaving || enabledModels.length === 0}
+              disabledMessage={enabledModels.length === 0 ? copy.editor.noModel : undefined}
+              onChange={(model) => setDraft((current) => ({ ...current, model, thinkingLevel: '' }))}
+            />
+          )}
+        />
+        {thinkingLevels.length > 0 ? (
+          <SettingsRow
+            label={copy.editor.thinking}
+            end={(
               <Selector
-                label={copy.editor.profile}
-                description={profileCopy.description}
-                value={draft.profile}
-                options={(Object.keys(copy.profiles) as SubagentProfile[]).map((profile) => ({
-                  value: profile,
-                  label: copy.profiles[profile].label,
-                }))}
+                label={copy.editor.thinking}
+                isLabelHidden
+                value={thinkingLevels.includes(draft.thinkingLevel as ThinkingLevel)
+                  ? draft.thinkingLevel
+                  : ''}
+                options={[
+                  { value: '', label: copy.editor.defaultThinking },
+                  ...thinkingLevels.map((level) => ({ value: level, label: copy.thinking[level] })),
+                ]}
                 width="100%"
                 isDisabled={props.isSaving}
-                onChange={(profile) => setDraft((current) => ({
+                onChange={(thinkingLevel) => setDraft((current) => ({
                   ...current,
-                  profile: profile as SubagentProfile,
+                  thinkingLevel: thinkingLevel as ThinkingLevel | '',
                 }))}
               />
-              {draft.profile === 'implementation' ? (
-                <div className="subagentPresetWarning" role="note">
-                  <AlertTriangle size={16} aria-hidden="true" />
-                  <Text type="supporting" size="sm">{copy.editor.implementationWarning}</Text>
-                </div>
-              ) : null}
-              <FormLayout direction="horizontal">
-                <Selector
-                  label={copy.editor.connection}
-                  value={draft.connectionSlug}
-                  options={connectionOptions}
-                  width="100%"
-                  isDisabled={props.isSaving || usableConnections.length === 0}
-                  disabledMessage={usableConnections.length === 0 ? copy.editor.noConnection : undefined}
-                  status={submitted && !validRoute
-                    ? { type: 'error', message: copy.editor.invalidRoute }
-                    : usableConnections.length === 0
-                      ? { type: 'warning', message: copy.editor.noConnection }
-                      : undefined}
-                  onChange={selectConnection}
-                />
-                <Selector
-                  label={copy.editor.model}
-                  value={draft.model}
-                  options={modelOptions}
-                  width="100%"
-                  isDisabled={props.isSaving || enabledModels.length === 0}
-                  disabledMessage={enabledModels.length === 0 ? copy.editor.noModel : undefined}
-                  onChange={selectModel}
-                />
-              </FormLayout>
-              {thinkingLevels.length > 0 ? (
-                <Selector
-                  label={copy.editor.thinking}
-                  value={thinkingLevels.includes(draft.thinkingLevel as ThinkingLevel)
-                    ? draft.thinkingLevel
-                    : ''}
-                  options={[
-                    { value: '', label: copy.editor.defaultThinking },
-                    ...thinkingLevels.map((level) => ({ value: level, label: copy.thinking[level] })),
-                  ]}
-                  width="100%"
-                  isDisabled={props.isSaving}
-                  onChange={(thinkingLevel) => setDraft((current) => ({
-                    ...current,
-                    thinkingLevel: thinkingLevel as ThinkingLevel | '',
-                  }))}
-                />
-              ) : null}
-              <Switch
-                label={copy.editor.enabled}
-                description={copy.editor.enabledDescription}
-                value={draft.enabled}
-                isDisabled={props.isSaving}
-                onChange={(enabled) => setDraft((current) => ({ ...current, enabled }))}
-              />
-              <div className="subagentPresetEditorActions">
-                <Button
-                  variant="ghost"
-                  label={copy.editor.cancel}
-                  isDisabled={props.isSaving}
-                  onClick={props.onClose}
-                />
-                <Button
-                  variant="primary"
-                  label={props.isSaving
-                    ? copy.editor.saving
-                    : props.preset
-                      ? copy.editor.save
-                      : copy.editor.create}
-                  isDisabled={props.isSaving}
-                  onClick={() => void submit()}
-                />
-              </div>
-            </FormLayout>
-          </LayoutContent>
-        )}
-      />
-    </Dialog>
+            )}
+          />
+        ) : null}
+      </SettingsSection>
+
+      {/* Save commits the whole preset, not the route group it would sit
+          inside, so it stands on its own between the groups and the delete
+          section. */}
+      <SettingsSection variant="bare">
+        <HStack gap={2} wrap="wrap">
+          <Button
+            variant="primary"
+            label={props.isSaving
+              ? copy.editor.saving
+              : props.preset
+                ? copy.editor.save
+                : copy.editor.create}
+            isDisabled={props.isSaving}
+            onClick={() => void submit()}
+          />
+          <Button
+            variant="ghost"
+            label={copy.editor.cancel}
+            isDisabled={props.isSaving}
+            onClick={props.onCancel}
+          />
+        </HStack>
+      </SettingsSection>
+
+      {/* Deletion is last and stands alone, so a mis-aimed cursor has nothing
+          quiet to hit beside it — the providers detail answers it the same way. */}
+      {props.onDelete ? (
+        <SettingsSection title={copy.editor.dangerZone} description={copy.remove.description}>
+          <SettingsActions>
+            <Button
+              variant="destructive"
+              label={copy.editor.delete}
+              isDisabled={props.isSaving}
+              onClick={props.onDelete}
+            />
+          </SettingsActions>
+        </SettingsSection>
+      ) : null}
+    </SettingsPage>
   );
 }
diff --git a/apps/desktop/src/renderer/styles/settings/models.css b/apps/desktop/src/renderer/styles/settings/models.css
index 9d4bd17a6a..acb1bc82f5 100644
--- a/apps/desktop/src/renderer/styles/settings/models.css
+++ b/apps/desktop/src/renderer/styles/settings/models.css
@@ -90,31 +90,3 @@
   mask-repeat: no-repeat;
   mask-size: contain;
 }
-.subagentPresetActions {
-  display: flex;
-  align-items: center;
-  flex-wrap: wrap;
-  gap: var(--space-2);
-}
-
-.subagentPresetWarning {
-  display: flex;
-  align-items: flex-start;
-  gap: var(--space-2);
-  padding: var(--space-3);
-  border: var(--border-width-hairline) solid oklch(from var(--warning) l c h / 0.28);
-  border-radius: var(--radius-control);
-  background: oklch(from var(--warning) l c h / 0.08);
-}
-
-.subagentPresetWarning svg {
-  flex: 0 0 auto;
-  color: var(--warning-text, var(--foreground-secondary));
-}
-
-.subagentPresetEditorActions {
-  display: flex;
-  justify-content: flex-end;
-  gap: var(--space-2);
-  padding-top: var(--space-2);
-}
diff --git a/apps/desktop/stories/settings/settings-pages.stories.tsx b/apps/desktop/stories/settings/settings-pages.stories.tsx
index 76110dd48b..469e156b7e 100644
--- a/apps/desktop/stories/settings/settings-pages.stories.tsx
+++ b/apps/desktop/stories/settings/settings-pages.stories.tsx
@@ -913,7 +913,8 @@ export const SubagentsNarrow: Story = {
   parameters: { viewport: { defaultViewport: 'mobile2' } },
 };
 
-// Real path: 设置 → 子 Agent → 添加子 Agent.
+// Real path: 设置 → 子 Agent → 添加子 Agent. The editor is a route level, so
+// this story shows the whole page swapped for the create form.
 export const SubagentEditorOpen: Story = {
   decorators: [withSubagentSettingsBridge],
   render: () => <SettingsStory section="subagents" />,
@@ -925,6 +926,21 @@ export const SubagentEditorOpen: Story = {
     await userEvent.click(button);
   },
 };
+
+// Real path: 设置 → 子 Agent → 配置一个已有的实现类 Profile. Covers the three
+// states the create form has no way to show: the settled read-only
+// subagent_id, the implementation capability warning, and the delete section.
+export const SubagentEditorExisting: Story = {
+  decorators: [withSubagentSettingsBridge],
+  render: () => <SettingsStory section="subagents" />,
+  play: async ({ canvasElement }) => {
+    const button = await waitForStoryButton(
+      canvasElement,
+      (candidate) => candidate.getAttribute('aria-label') === '配置“实现与验证”',
+    );
+    await userEvent.click(button);
+  },
+};
 // Real path: 设置 → 通用.
 export const General: Story = {
   decorators: [withSettingsBridge],

From 1bae1cc5ec296d12d52ad64869fee089fe5ee312 Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Mon, 3 Aug 2026 20:17:18 +0800
Subject: [PATCH 2/8] fix(desktop): give settings stories a bounded height, and
 one story per subagent level
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two follow-ups from reviewing the rebuilt page in Storybook.

The settings story harness wrapped `SettingsSurface` in `height: '100%'`.
`SettingsSurface` is a `Layout height="fill"`, which needs a bounded
ancestor before it hands its content pane a scroll box; under Storybook's
fullscreen body a percentage height resolves against an auto-height parent,
so every page taller than the frame stretched the whole surface instead of
scrolling inside it. 权限与能力 reached 1942px in a 720px frame with no way
down, and 记忆 and the subagent editor were stuck the same way — a
pre-existing hole that only shows on a page long enough to need it.
`100dvh` restores the scroll box: the editor's content pane now measures
582/1005 with `overflow-y: auto`, and the delete section is reachable.

The subagent page also arrived with four stories where the settings
convention is one per page plus a variant for a state the page cannot
otherwise show. The narrow variant had nothing to say now that the row's
trailing cluster is a switch and a chevron, and the create form is the
edit form minus three elements, so both are gone: 子 Agent keeps its list
story and one editor story, on the preset that exercises the most of it.

Verified: typecheck, lint, Storybook smoke (67 manifest checks, 73 catalog
renders across three viewports), and a scroll probe on the editor level.
---
 .../settings/settings-pages.stories.tsx       | 37 ++++++-------------
 1 file changed, 12 insertions(+), 25 deletions(-)

diff --git a/apps/desktop/stories/settings/settings-pages.stories.tsx b/apps/desktop/stories/settings/settings-pages.stories.tsx
index 469e156b7e..13ac654fe7 100644
--- a/apps/desktop/stories/settings/settings-pages.stories.tsx
+++ b/apps/desktop/stories/settings/settings-pages.stories.tsx
@@ -792,11 +792,17 @@ function SettingsStory(props: {
 
   return (
     <ToastProvider>
+      {/* `100dvh`, not `100%`: `SettingsSurface` is a `Layout height="fill"`,
+          which needs a bounded ancestor to hand its content pane a scroll
+          box. Under Storybook's fullscreen body a percentage height resolves
+          against an auto-height parent, so every page taller than the
+          viewport stretched the whole surface instead of scrolling inside it
+          — 权限与能力 reached 1942px in a 720px frame with no way down. */}
       <div
         data-maka-e2e-fixture="true"
         style={{
           background: 'var(--surface-canvas)',
-          height: '100%',
+          height: '100dvh',
           minHeight: 640,
         }}
       >
@@ -907,30 +913,11 @@ export const Subagents: Story = {
   render: () => <SettingsStory section="subagents" />,
 };
 
-// Real path: Settings → Subagents at the minimum supported window width.
-export const SubagentsNarrow: Story = {
-  ...Subagents,
-  parameters: { viewport: { defaultViewport: 'mobile2' } },
-};
-
-// Real path: 设置 → 子 Agent → 添加子 Agent. The editor is a route level, so
-// this story shows the whole page swapped for the create form.
-export const SubagentEditorOpen: Story = {
-  decorators: [withSubagentSettingsBridge],
-  render: () => <SettingsStory section="subagents" />,
-  play: async ({ canvasElement }) => {
-    const button = await waitForStoryButton(
-      canvasElement,
-      (candidate) => candidate.textContent?.trim() === '添加子 Agent',
-    );
-    await userEvent.click(button);
-  },
-};
-
-// Real path: 设置 → 子 Agent → 配置一个已有的实现类 Profile. Covers the three
-// states the create form has no way to show: the settled read-only
-// subagent_id, the implementation capability warning, and the delete section.
-export const SubagentEditorExisting: Story = {
+// Real path: 设置 → 子 Agent → 配置一个已有的实现类 Profile. One story for the
+// editor level, on the preset that exercises the most of it: the settled
+// read-only subagent_id, the implementation capability warning, and the
+// delete section. The create form is this form minus those three.
+export const SubagentEditor: Story = {
   decorators: [withSubagentSettingsBridge],
   render: () => <SettingsStory section="subagents" />,
   play: async ({ canvasElement }) => {

From 8893f2d96fd253cb5faa18ac3b15cc0d588cdcab Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Mon, 3 Aug 2026 20:22:09 +0800
Subject: [PATCH 3/8] test(desktop): drop the redundant subagent editor story,
 pin the level in e2e
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The editor story was the list story plus one click — same bridge, same
render, one `play`. A reviewer reaches the same screen by clicking the row,
so 子 Agent keeps one story, as the settings convention has it.

What the story was covering, the e2e now states outright: the level carries
the settled subagent_id and the delete action, the two things the list row
deliberately does not show. That path already ran in a real Electron window;
it just was not asserting the level's shape.

Verified: typecheck, lint, Storybook smoke (72 catalog renders), settings
e2e (3 passed).
---
 apps/desktop/e2e/settings.spec.ts                 |  4 ++++
 .../stories/settings/settings-pages.stories.tsx   | 15 ---------------
 2 files changed, 4 insertions(+), 15 deletions(-)

diff --git a/apps/desktop/e2e/settings.spec.ts b/apps/desktop/e2e/settings.spec.ts
index 630340d5ed..e0118e348f 100644
--- a/apps/desktop/e2e/settings.spec.ts
+++ b/apps/desktop/e2e/settings.spec.ts
@@ -60,6 +60,10 @@ test('subagent presets can be reviewed and edited in desktop settings', async ({
   // and the back affordance is the only way out.
   await settings.getByRole('button', { name: '配置“E2E 快速阅读”' }).click();
   await expect(settings.getByRole('heading', { name: 'E2E 快速阅读', exact: true })).toBeVisible();
+  // The level owns the whole preset, so it carries the two things the list
+  // row deliberately does not: the settled id, and deletion.
+  await expect(settings.getByText('e2e-fast-reader', { exact: true })).toBeVisible();
+  await expect(settings.getByRole('button', { name: '删除', exact: true })).toBeVisible();
   await settings.getByRole('textbox', { name: '适用场景' }).fill('快速阅读代码，并总结关键调用链。');
   await settings.getByRole('button', { name: '保存', exact: true }).click();
 
diff --git a/apps/desktop/stories/settings/settings-pages.stories.tsx b/apps/desktop/stories/settings/settings-pages.stories.tsx
index 13ac654fe7..79df27ac51 100644
--- a/apps/desktop/stories/settings/settings-pages.stories.tsx
+++ b/apps/desktop/stories/settings/settings-pages.stories.tsx
@@ -913,21 +913,6 @@ export const Subagents: Story = {
   render: () => <SettingsStory section="subagents" />,
 };
 
-// Real path: 设置 → 子 Agent → 配置一个已有的实现类 Profile. One story for the
-// editor level, on the preset that exercises the most of it: the settled
-// read-only subagent_id, the implementation capability warning, and the
-// delete section. The create form is this form minus those three.
-export const SubagentEditor: Story = {
-  decorators: [withSubagentSettingsBridge],
-  render: () => <SettingsStory section="subagents" />,
-  play: async ({ canvasElement }) => {
-    const button = await waitForStoryButton(
-      canvasElement,
-      (candidate) => candidate.getAttribute('aria-label') === '配置“实现与验证”',
-    );
-    await userEvent.click(button);
-  },
-};
 // Real path: 设置 → 通用.
 export const General: Story = {
   decorators: [withSettingsBridge],

From 508c06f78f181c1f7a6beed3f169de56e4e6c40e Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Mon, 3 Aug 2026 20:30:14 +0800
Subject: [PATCH 4/8] docs(desktop): one story per state, not per click

The subagent page arrived with four stories for one surface. FIDELITY.md
is where the Product/* story conventions live, so the rule goes there
rather than into a second document beside it: a surface gets one story,
and earns another only for a state that story cannot reach.
---
 apps/desktop/stories/FIDELITY.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/apps/desktop/stories/FIDELITY.md b/apps/desktop/stories/FIDELITY.md
index bf8f1bf946..a61cdaa5bb 100644
--- a/apps/desktop/stories/FIDELITY.md
+++ b/apps/desktop/stories/FIDELITY.md
@@ -19,6 +19,12 @@ The annotation is prose on purpose. Its value is that someone traced the path an
 
 Two of the first batch of annotations were wrong, and both were caught by reading rather than by running anything: one named a path through a builder that cannot produce the state (`CommandPaletteDisabledCommand`), and one named two hosts for a frame that is only one of them. Write the sentence narrow enough to be falsifiable — the host, the builder, the gate — because a sentence vague enough to always be true buys nothing.
 
+## One story per state, not per click
+
+A surface gets one story. It earns a second only for a state that story cannot reach — not for a state one click away from it, and not for the same state at another width: the smoke script already renders every story at three viewports, so a narrow variant needs a layout that genuinely differs there.
+
+Extra stories do not just cost their own size. A reviewer scanning the sidebar can no longer tell which entry is the page, and the duplicates re-render the same pixels every smoke run while claiming coverage they do not add. Where a state matters but does not earn a story, pin it somewhere that runs — a `packages/ui` test or an e2e journey.
+
 ## The frame matters, not just the component
 
 A story that mounts the right component inside the wrong wrapper is still unreachable. If the app wraps a surface in a class that owns its height, padding or alignment, the story has to use that wrapper too — otherwise every geometry comparison against the story is measuring the story's own scaffolding.

From a4ac64d54143e4d9d65236943f396f1918b61220 Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Mon, 3 Aug 2026 20:56:50 +0800
Subject: [PATCH 5/8] fix(desktop): give the subagent page its route
 controller, and restore what the rebuild dropped
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three-way review of #2008 (codex + two agents) against the providers panel it
copies. The rebuild took that panel's route-level shell without its route
controller, and traded away two capabilities to look simpler.

Route controller, at the owner:
- focus follows the level. The level carried `tabIndex={-1}` and a comment
  claiming it takes focus on landing, but nothing ever called `focus()`:
  clicking the chevron unmounted the button that had it, so a keyboard user
  restarted from `document.body` on every move. The Dialog this replaced got
  this for free. Entering focuses the level (not the back button — an
  IconButton pops its tooltip on focus), returning goes back to the row the
  user left from, falling back to the add button when that row is gone, and
  first render does not pull focus off the settings nav at all.
- an edit route whose preset vanished used to render as a BLANK CREATE FORM
  that appended a second preset on save, because "no presetId" and "presetId
  that no longer resolves" were the same `null`. The route is now a
  discriminated union and an unsatisfiable edit derives back to the list, as
  ProvidersPanel:194 already spells out.

Restored:
- a preset can again be created disabled. Dropping the editor switch left a
  real window where a just-saved preset is selectable before the user can
  reach the list row, and the reviewers were right that two controls over one
  state are two entrances, not two authorities. The switch is back on create
  only; for an existing preset the header states the disabled fact via the
  badge slot providers already uses for its default connection.
- `SubagentEditor` story. It was deleted under a rule written in this same PR,
  worded widely enough to cover a whole second route level — the wrong
  direction. `play` does run in the browser, so that story was the editor's
  only automated render; without it the entire `preset === null` branch and
  every degraded-route state rendered nowhere.

Corrections to what this PR asserted:
- FIDELITY.md claimed the smoke script renders every story at three viewports.
  It renders the seven manifest surfaces that way and every other story once,
  at 1280 light (`catalogJobs`). The rule is rewritten around what actually
  renders, and the "play does not execute" section is corrected to what is
  true: it runs, nothing collects its assertions.
- the id read-only row hand-rolled `<code class="settingsReadOnlyValue">`,
  missing `data-mono`, so a 128-char id rendered as body type in a 320px
  right-anchored box. It uses the kit's `SettingRow mono` path.
- the list section header lost its title, leaving an empty header with a
  divider under it and dropping the only count under a 64-preset ceiling.
  Title and count are back, and the ceiling reads from MAX_SUBAGENT_PRESETS
  rather than a hardcoded 64 in copy.
- the empty state showed two identical add buttons; the section action now
  yields to the EmptyState CTA.
- three imports left dead in ProvidersPanel by the RouteHeader extraction
  (biome has no noUnusedImports, tsc no noUnusedLocals — CI cannot see them).
- `settingsSubagentsPage` was a class with no rule, on a page whose header
  says it owns no CSS; the save/cancel row was a title-less SettingsSection
  rendering neither header nor divider around one HStack; the danger section
  repeated the confirm dialog's sentence verbatim.

Tests, for the regressions that shipped green:
- e2e seeds the preset DISABLED, so saving an unrelated field proves
  `enabled` survives — the single line holding up the switch removal.
- a create journey: id derives from the name, create-disabled persists as
  false, and the list row's switch enables it.
- focus assertions on both level changes and on arrival.
- `nextSubagentDraftForName` extracted and unit-tested, including the
  `idWasEdited` takeover the UI wiring had no coverage for.
- availability now asserts `tone` with `kind`; a broken route quietly turning
  green was a pure-data regression with no other home.
- the story fixture gains an enabled preset whose connection is gone, so the
  destructive badge renders somewhere (the disabled one short-circuits first).

Verified: typecheck, lint, format:check, check-dead-css, check-story-
annotations, check-a11y/copy/console, 1382 unit tests, Storybook smoke, and
settings + providers e2e (6 passed).
---
 apps/desktop/e2e/settings.spec.ts             |  61 +++++-
 .../subagent-preset-presentation.test.ts      |  66 +++++-
 .../locales/settings-subagents-copy.ts        |  19 +-
 .../src/renderer/settings/ProvidersPanel.tsx  |   5 +-
 .../settings/subagent-preset-presentation.ts  |  18 ++
 .../settings/subagent-settings-page.tsx       | 193 +++++++++++++-----
 apps/desktop/stories/FIDELITY.md              |  13 +-
 .../settings/settings-pages.stories.tsx       |  27 +++
 8 files changed, 332 insertions(+), 70 deletions(-)

diff --git a/apps/desktop/e2e/settings.spec.ts b/apps/desktop/e2e/settings.spec.ts
index e0118e348f..e8c6c51fc3 100644
--- a/apps/desktop/e2e/settings.spec.ts
+++ b/apps/desktop/e2e/settings.spec.ts
@@ -42,7 +42,11 @@ test('subagent presets can be reviewed and edited in desktop settings', async ({
           profile: 'local_read',
           connectionSlug: connection.slug,
           model: connection.enabledModelIds?.[0] ?? connection.defaultModel,
-          enabled: true,
+          // Seeded DISABLED on purpose: the editor no longer carries an enable
+          // switch for an existing preset, so this run is what proves saving an
+          // unrelated field does not quietly re-enable a preset the user turned
+          // off — the one invariant holding that removal up.
+          enabled: false,
         }],
       },
     });
@@ -55,13 +59,21 @@ test('subagent presets can be reviewed and edited in desktop settings', async ({
   const settings = page.getByRole('main', { name: '设置内容' });
   await expect(settings.getByRole('heading', { name: '子 Agent', exact: true })).toBeVisible();
   await expect(settings.getByText('E2E 快速阅读', { exact: true })).toBeVisible();
+  await expect(settings.getByText('已停用', { exact: true })).toBeVisible();
+  // Arriving is not navigating: the page must not pull focus off the settings
+  // nav item the user just clicked. Only a level change moves focus.
+  await expect(settings.getByRole('button', { name: '添加子 Agent' })).not.toBeFocused();
 
   // The editor is a route level, not a dialog: the list is replaced in place
   // and the back affordance is the only way out.
   await settings.getByRole('button', { name: '配置“E2E 快速阅读”' }).click();
   await expect(settings.getByRole('heading', { name: 'E2E 快速阅读', exact: true })).toBeVisible();
-  // The level owns the whole preset, so it carries the two things the list
-  // row deliberately does not: the settled id, and deletion.
+  await expect(settings.getByRole('button', { name: '添加子 Agent' })).toBeHidden();
+  // A level change moves focus to the level itself; without it the chevron
+  // that had focus unmounts and a keyboard user restarts from document.body.
+  await expect(settings.locator('[data-maka-contract="subagent-detail"]')).toBeFocused();
+  // The level owns the whole preset, so it carries the three things the list
+  // row deliberately does not: the settled id, the disabled state, and deletion.
   await expect(settings.getByText('e2e-fast-reader', { exact: true })).toBeVisible();
   await expect(settings.getByRole('button', { name: '删除', exact: true })).toBeVisible();
   await settings.getByRole('textbox', { name: '适用场景' }).fill('快速阅读代码，并总结关键调用链。');
@@ -69,10 +81,49 @@ test('subagent presets can be reviewed and edited in desktop settings', async ({
 
   await expect(settings.getByRole('button', { name: '添加子 Agent' })).toBeVisible();
   await expect(settings.getByText('快速阅读代码，并总结关键调用链。', { exact: true })).toBeVisible();
+  // Returning to the list puts focus back on the row the user left from.
+  await expect(settings.locator('[data-subagent-preset="e2e-fast-reader"]')).toBeFocused();
   await expect.poll(async () => page.evaluate(async () => {
     const current = await window.maka.settings.get();
-    return current.subagents.presets[0]?.description;
-  })).toBe('快速阅读代码，并总结关键调用链。');
+    const preset = current.subagents.presets[0];
+    return { description: preset?.description, enabled: preset?.enabled };
+  })).toEqual({ description: '快速阅读代码，并总结关键调用链。', enabled: false });
+});
+
+test('a subagent preset can be created disabled and then enabled from its row', async ({ window: page }) => {
+  await page.evaluate(async () => {
+    await window.maka.settings.update({ subagents: { presets: [] } });
+  });
+
+  await page.getByRole('button', { name: '展开侧边栏' }).click();
+  await page.getByRole('button', { name: '设置' }).click();
+  await settingsNavigation(page).getByRole('button', { name: '子 Agent', exact: true }).click();
+
+  const settings = page.getByRole('main', { name: '设置内容' });
+  // The create branch is a structurally different tree from the edit branch —
+  // a typed id instead of a settled one, an enable switch, no delete section —
+  // so it needs its own journey rather than riding on the edit one.
+  await settings.getByRole('button', { name: '添加子 Agent' }).click();
+  await settings.getByRole('textbox', { name: '显示名称' }).fill('E2E Web Research');
+  // The id derives from the name until the user takes it over.
+  await expect(settings.getByRole('textbox', { name: 'subagent_id' })).toHaveValue('e2e-web-research');
+  await settings.getByRole('textbox', { name: '适用场景' }).fill('查找外部资料。');
+  await settings.getByRole('switch', { name: '创建后即可用' }).click();
+  await settings.getByRole('button', { name: '创建', exact: true }).click();
+
+  await expect(settings.getByText('E2E Web Research', { exact: true })).toBeVisible();
+  await expect.poll(async () => page.evaluate(async () => {
+    const current = await window.maka.settings.get();
+    const preset = current.subagents.presets[0];
+    return { id: preset?.id, enabled: preset?.enabled };
+  })).toEqual({ id: 'e2e-web-research', enabled: false });
+
+  // The list row's switch is the only way to enable an existing preset.
+  await settings.getByRole('switch', { name: '启用: E2E Web Research' }).click();
+  await expect.poll(async () => page.evaluate(async () => {
+    const current = await window.maka.settings.get();
+    return current.subagents.presets[0]?.enabled;
+  })).toBe(true);
 });
 
 test('remote access prioritizes a configured channel that needs attention', async ({ window: page }) => {
diff --git a/apps/desktop/src/main/__tests__/subagent-preset-presentation.test.ts b/apps/desktop/src/main/__tests__/subagent-preset-presentation.test.ts
index 5e59c0b986..1f5a76da81 100644
--- a/apps/desktop/src/main/__tests__/subagent-preset-presentation.test.ts
+++ b/apps/desktop/src/main/__tests__/subagent-preset-presentation.test.ts
@@ -2,6 +2,7 @@ import { strict as assert } from 'node:assert';
 import { describe, it } from 'node:test';
 import type { LlmConnection, SubagentPreset } from '@maka/core';
 import {
+  nextSubagentDraftForName,
   subagentPresetAvailability,
   suggestSubagentPresetId,
 } from '../../renderer/settings/subagent-preset-presentation.js';
@@ -39,15 +40,24 @@ describe('subagentPresetAvailability', () => {
       kind: 'available',
       tone: 'success',
     });
-    assert.equal(subagentPresetAvailability(preset({ enabled: false }), []).kind, 'disabled');
-    assert.equal(subagentPresetAvailability(preset(), []).kind, 'missing_connection');
-    assert.equal(
-      subagentPresetAvailability(preset(), [connection({ enabled: false })]).kind,
-      'connection_disabled',
-    );
-    assert.equal(
-      subagentPresetAvailability(preset({ model: 'deepseek-reasoner' }), [connection()]).kind,
-      'model_disabled',
+    // The tone is asserted with the kind, not separately: the tone is what the
+    // list row actually renders, so a broken route quietly turning green is a
+    // pure-data regression this file is the only place to catch.
+    assert.deepEqual(subagentPresetAvailability(preset({ enabled: false }), []), {
+      kind: 'disabled',
+      tone: 'neutral',
+    });
+    assert.deepEqual(subagentPresetAvailability(preset(), []), {
+      kind: 'missing_connection',
+      tone: 'destructive',
+    });
+    assert.deepEqual(subagentPresetAvailability(preset(), [connection({ enabled: false })]), {
+      kind: 'connection_disabled',
+      tone: 'warning',
+    });
+    assert.deepEqual(
+      subagentPresetAvailability(preset({ model: 'deepseek-reasoner' }), [connection()]),
+      { kind: 'model_disabled', tone: 'warning' },
     );
   });
 });
@@ -62,3 +72,41 @@ describe('suggestSubagentPresetId', () => {
     );
   });
 });
+
+describe('nextSubagentDraftForName', () => {
+  const draft = { name: '', id: '' };
+
+  it('derives the id from the name until the user takes the id over', () => {
+    assert.deepEqual(nextSubagentDraftForName(draft, 'Fast Code Reader', false, new Set()), {
+      name: 'Fast Code Reader',
+      id: 'fast-code-reader',
+    });
+    // Once the user has typed an id, a later name edit must not overwrite it —
+    // an editor that silently drops this gate looks identical on screen.
+    assert.deepEqual(
+      nextSubagentDraftForName({ name: 'Fast', id: 'my-own-id' }, 'Fast Reader', true, new Set()),
+      { name: 'Fast Reader', id: 'my-own-id' },
+    );
+  });
+
+  it('keeps other draft fields untouched and resolves collisions', () => {
+    assert.deepEqual(
+      nextSubagentDraftForName(
+        { name: '', id: '', model: 'glm-4.7' },
+        'Fast Code Reader',
+        false,
+        new Set(['fast-code-reader']),
+      ),
+      { name: 'Fast Code Reader', id: 'fast-code-reader-2', model: 'glm-4.7' },
+    );
+  });
+
+  it('falls back to a safe id for a name with no ASCII, so two of them differ', () => {
+    const first = nextSubagentDraftForName(draft, '快速阅读', false, new Set());
+    assert.equal(first.id, 'subagent');
+    assert.equal(
+      nextSubagentDraftForName(draft, '网页研究', false, new Set([first.id])).id,
+      'subagent-2',
+    );
+  });
+});
diff --git a/apps/desktop/src/renderer/locales/settings-subagents-copy.ts b/apps/desktop/src/renderer/locales/settings-subagents-copy.ts
index 6faa0cedae..6b706554c9 100644
--- a/apps/desktop/src/renderer/locales/settings-subagents-copy.ts
+++ b/apps/desktop/src/renderer/locales/settings-subagents-copy.ts
@@ -12,6 +12,8 @@ type ProfileCopy = {
 
 export type SubagentSettingsCopy = {
   section: {
+    title: string;
+    count(total: number, max: number): string;
     add: string;
     limitNote: string;
     emptyTitle: string;
@@ -38,7 +40,10 @@ export type SubagentSettingsCopy = {
     groupRoute: string;
     groupRouteHelp: string;
     dangerZone: string;
+    dangerZoneHelp: string;
     delete: string;
+    enabled: string;
+    enabledDescription: string;
     name: string;
     namePlaceholder: string;
     id: string;
@@ -80,8 +85,10 @@ export type SubagentSettingsCopy = {
 const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
   zh: {
     section: {
+      title: '已批准的子 Agent',
+      count: (total, max) => `共 ${total} / ${max} 个配置`,
       add: '添加子 Agent',
-      limitNote: '已达到 64 个配置的上限。',
+      limitNote: '已达到配置数量上限。',
       emptyTitle: '还没有子 Agent 配置',
       emptyDescription: '添加一个配置后，主 Agent 就能把合适的任务交给独立模型处理。',
     },
@@ -106,7 +113,10 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
       groupRoute: '能力与模型',
       groupRouteHelp: '固定这个子 Agent 能做什么，以及它运行在哪个模型上。',
       dangerZone: '删除子 Agent',
+      dangerZoneHelp: '删除后，这个配置将从设置中移除，且无法撤销。',
       delete: '删除',
+      enabled: '创建后即可用',
+      enabledDescription: '关闭后，配置会被保存但主 Agent 暂时不会选择它。',
       name: '显示名称',
       namePlaceholder: '快速代码阅读',
       id: 'subagent_id',
@@ -158,8 +168,10 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
   },
   en: {
     section: {
+      title: 'Approved subagents',
+      count: (total, max) => `${total} of ${max} presets`,
       add: 'Add subagent',
-      limitNote: 'The 64-preset limit has been reached.',
+      limitNote: 'The preset limit has been reached.',
       emptyTitle: 'No subagent presets yet',
       emptyDescription: 'Add a preset so the main agent can delegate suitable work to a separate model.',
     },
@@ -184,7 +196,10 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
       groupRoute: 'Capability and model',
       groupRouteHelp: 'Fix what this subagent may do, and which model it runs on.',
       dangerZone: 'Remove subagent',
+      dangerZoneHelp: 'Removing takes this preset out of settings, and cannot be undone.',
       delete: 'Remove',
+      enabled: 'Available once created',
+      enabledDescription: 'Turn this off to save the preset without letting the main agent select it yet.',
       name: 'Display name',
       namePlaceholder: 'Fast code reader',
       id: 'subagent_id',
diff --git a/apps/desktop/src/renderer/settings/ProvidersPanel.tsx b/apps/desktop/src/renderer/settings/ProvidersPanel.tsx
index c2d508df7e..3d1c0e2ef8 100644
--- a/apps/desktop/src/renderer/settings/ProvidersPanel.tsx
+++ b/apps/desktop/src/renderer/settings/ProvidersPanel.tsx
@@ -1,4 +1,4 @@
-import { type ReactNode, useEffect, useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import {
   Badge,
   Banner,
@@ -6,7 +6,6 @@ import {
   EmptyState,
   Heading,
   HStack,
-  IconButton,
   List,
   ListItem,
   Skeleton,
@@ -15,7 +14,7 @@ import {
   Toolbar,
   VStack,
 } from '@astryxdesign/core';
-import { ArrowLeft, ChevronRight } from '@maka/ui/icons';
+import { ChevronRight } from '@maka/ui/icons';
 import {
   type LlmConnection,
   type ProviderType,
diff --git a/apps/desktop/src/renderer/settings/subagent-preset-presentation.ts b/apps/desktop/src/renderer/settings/subagent-preset-presentation.ts
index c12f56e0e9..929e591daa 100644
--- a/apps/desktop/src/renderer/settings/subagent-preset-presentation.ts
+++ b/apps/desktop/src/renderer/settings/subagent-preset-presentation.ts
@@ -31,6 +31,24 @@ export function subagentPresetAvailability(
   return { kind: 'available', tone: 'success' };
 }
 
+/**
+ * Typing the display name fills the id — until the user takes the id over.
+ *
+ * The rule lives here rather than inside the editor because it is state math,
+ * not rendering: `idWasEdited` is the whole contract ("the id is derived until
+ * the user says otherwise, and an existing preset's id is never derived"), and
+ * an editor that quietly stops honouring it looks identical on screen.
+ */
+export function nextSubagentDraftForName<Draft extends { name: string; id: string }>(
+  draft: Draft,
+  name: string,
+  idWasEdited: boolean,
+  existingIds: ReadonlySet<string>,
+): Draft {
+  if (idWasEdited) return { ...draft, name };
+  return { ...draft, name, id: suggestSubagentPresetId(name, existingIds) };
+}
+
 export function suggestSubagentPresetId(
   name: string,
   existingIds: ReadonlySet<string>,
diff --git a/apps/desktop/src/renderer/settings/subagent-settings-page.tsx b/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
index 6705e47375..3e362dd999 100644
--- a/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
+++ b/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
@@ -19,7 +19,7 @@
 // cluster, an oklch-tinted warning callout, and a flex-end button row — were
 // each a restatement of something the kit or Astryx already draws (the row end
 // slot, `Banner status="warning"`, `SettingsActions`).
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import { Badge, Banner, HStack, VStack } from '@astryxdesign/core';
 import {
   connectionEnabledModelIds,
@@ -56,16 +56,25 @@ import {
   SettingsRow,
   SettingsSection,
 } from './settings-section.js';
+import { SettingRow } from './settings-rows.js';
 import {
+  nextSubagentDraftForName,
   subagentPresetAvailability,
   suggestSubagentPresetId,
 } from './subagent-preset-presentation.js';
 import { statusBadgeVariant } from './settings-status-badge.js';
 
-/** `null` is the unsaved new preset; a string is an existing preset's id. */
-type EditorRoute = { presetId: string | null };
+/**
+ * Where the page is. `create` and `edit` are the same form; they are separate
+ * cases because the id, the delete section, and the enabled control differ, and
+ * because an `edit` route can become unsatisfiable while `create` cannot.
+ */
+type PageRoute =
+  | { kind: 'list' }
+  | { kind: 'create' }
+  | { kind: 'edit'; presetId: string };
 
-type EditorDraft = {
+export type SubagentEditorDraft = {
   id: string;
   name: string;
   description: string;
@@ -73,6 +82,7 @@ type EditorDraft = {
   connectionSlug: string;
   model: string;
   thinkingLevel: ThinkingLevel | '';
+  enabled: boolean;
 };
 
 export function SubagentSettingsPage(props: {
@@ -85,13 +95,68 @@ export function SubagentSettingsPage(props: {
   const locale = useUiLocale();
   const copy = getSubagentSettingsCopy(locale);
   const toast = useToast();
-  const [route, setRoute] = useState<EditorRoute | null>(null);
+  const [route, setRoute] = useState<PageRoute>({ kind: 'list' });
   const [saving, setSaving] = useState(false);
   const presets = props.settings.subagents.presets;
-  const editorPreset = route?.presetId == null
-    ? null
-    : presets.find((preset) => preset.id === route.presetId) ?? null;
+  const editorPreset = route.kind === 'edit'
+    ? presets.find((preset) => preset.id === route.presetId) ?? null
+    : null;
+  // An edit route whose preset vanished (deleted in another window, or removed
+  // by an external settings write) is an unsatisfiable route, not a state to
+  // correct: the list is what it renders as. Deriving that beats scheduling a
+  // setState from inside render — and beats the alternative this page shipped
+  // with, where a missing preset silently became a blank create form that
+  // appended a second preset on save.
+  const level: PageRoute['kind'] = route.kind === 'edit' && !editorPreset ? 'list' : route.kind;
   const atLimit = presets.length >= MAX_SUBAGENT_PRESETS;
+  const addButtonRef = useRef<HTMLButtonElement>(null);
+  // Which row the user left the list from, so returning puts focus back where
+  // they were rather than at the top of the page.
+  const listReturnFocusRef = useRef<string | null>(null);
+
+  // Focus follows the level. Without this a level change leaves the ring on
+  // `document.body` — the chevron that had focus just unmounted — and a
+  // keyboard user restarts from the top of the document on every move. The
+  // Dialog this page replaced got the same behaviour for free; a route level
+  // has to say it. Mirrors ProvidersPanel, which owns the same two levels.
+  //
+  // Navigating, not arriving: the page does not grab focus when the settings
+  // surface first renders the list — the user is still in the settings nav
+  // they clicked to get here, and taking the ring off it strands them.
+  const hasNavigatedRef = useRef(false);
+  useEffect(() => {
+    if (!hasNavigatedRef.current) {
+      hasNavigatedRef.current = true;
+      return;
+    }
+    const frame = window.requestAnimationFrame(() => {
+      if (level !== 'list') {
+        // The level, not its back button: an IconButton opens its tooltip on
+        // focus, so focusing one on arrival would pop a tooltip at every mouse
+        // user who merely clicked a row. `preventScroll` because this is a
+        // landing — the level just rendered at the top of the content area.
+        document
+          .querySelector<HTMLElement>('[data-maka-contract="subagent-detail"]')
+          ?.focus({ preventScroll: true });
+        return;
+      }
+      // Consumed here and only here. The row the user came from may be gone —
+      // that is exactly what deletion does — so the add button is the
+      // fallback, not the default.
+      const returnToId = listReturnFocusRef.current;
+      listReturnFocusRef.current = null;
+      const row = returnToId
+        ? document.querySelector<HTMLElement>(`[data-subagent-preset="${CSS.escape(returnToId)}"]`)
+        : null;
+      (row ?? addButtonRef.current)?.focus({ preventScroll: true });
+    });
+    return () => window.cancelAnimationFrame(frame);
+  }, [level]);
+
+  function openEditor(presetId: string): void {
+    listReturnFocusRef.current = presetId;
+    setRoute({ kind: 'edit', presetId });
+  }
 
   async function persist(nextPresets: SubagentPreset[]): Promise<boolean> {
     setSaving(true);
@@ -116,13 +181,14 @@ export function SubagentSettingsPage(props: {
     });
     if (!confirmed) return;
     const removed = await persist(presets.filter((candidate) => candidate.id !== preset.id));
-    if (removed) setRoute(null);
+    if (removed) setRoute({ kind: 'list' });
   }
 
-  if (route) {
+  if (level !== 'list') {
     return (
-      // tabIndex -1 so the level itself can take focus when it lands, instead
-      // of dropping a keyboard user on document.body. It draws no ring.
+      // tabIndex -1 so the level itself can take the focus the effect above
+      // hands it, instead of dropping a keyboard user on document.body. It
+      // draws no ring.
       <VStack
         gap={5}
         tabIndex={-1}
@@ -130,11 +196,18 @@ export function SubagentSettingsPage(props: {
         data-maka-contract="subagent-detail"
       >
         <SettingsRouteHeader
-          onBack={() => setRoute(null)}
+          onBack={() => setRoute({ kind: 'list' })}
           backLabel={copy.editor.backToList}
           contract="subagent-detail-back"
           title={editorPreset ? editorPreset.name : copy.editor.createTitle}
           subtitle={editorPreset ? copy.editor.editSubtitle : copy.editor.createSubtitle}
+          // Enabled state is a fact about the preset the user just opened, and
+          // the row that carried it is now off screen. The header slot already
+          // exists for exactly this (providers marks its default connection
+          // here), so the editor states it instead of re-asking for it.
+          badge={editorPreset && !editorPreset.enabled
+            ? <Badge variant="neutral" label={copy.status.disabled} />
+            : null}
         />
         <SubagentPresetEditor
           key={editorPreset?.id ?? 'new'}
@@ -142,13 +215,13 @@ export function SubagentSettingsPage(props: {
           presets={presets}
           connections={props.connections}
           isSaving={saving}
-          onCancel={() => setRoute(null)}
+          onCancel={() => setRoute({ kind: 'list' })}
           onDelete={editorPreset ? () => void removePreset(editorPreset) : undefined}
           onSave={async (next) => {
             const nextPresets = editorPreset
               ? presets.map((candidate) => candidate.id === editorPreset.id ? next : candidate)
               : [...presets, next];
-            if (await persist(nextPresets)) setRoute(null);
+            if (await persist(nextPresets)) setRoute({ kind: 'list' });
           }}
         />
       </VStack>
@@ -156,33 +229,34 @@ export function SubagentSettingsPage(props: {
   }
 
   return (
-    <SettingsPage className="settingsSubagentsPage">
-      {/* The page's single lead group, so it carries no title of its own: the
-          settings surface already heads it 子 Agent over the same sentence,
-          and a section title here was that heading a second time. Only the
-          preset ceiling has anything left to say, and only once it is hit. */}
+    <SettingsPage>
       <SettingsSection
-        description={atLimit ? copy.section.limitNote : undefined}
-        action={(
+        title={copy.section.title}
+        description={atLimit ? copy.section.limitNote : copy.section.count(presets.length, MAX_SUBAGENT_PRESETS)}
+        action={presets.length > 0 ? (
           <Button
+            ref={addButtonRef}
             variant="primary"
             size="sm"
             label={copy.section.add}
             isDisabled={saving || atLimit}
-            onClick={() => setRoute({ presetId: null })}
+            onClick={() => setRoute({ kind: 'create' })}
           />
-        )}
+        ) : undefined}
       >
         {presets.length === 0 ? (
+          // The empty state owns the only call to action here; a section
+          // action beside it would be the same button twice on one screen.
           <EmptyState
             title={copy.section.emptyTitle}
             description={copy.section.emptyDescription}
             actions={(
               <Button
+                ref={addButtonRef}
                 variant="primary"
                 label={copy.section.add}
                 isDisabled={saving}
-                onClick={() => setRoute({ presetId: null })}
+                onClick={() => setRoute({ kind: 'create' })}
               />
             )}
           />
@@ -233,7 +307,11 @@ export function SubagentSettingsPage(props: {
                     tooltip={copy.row.configure(preset.name)}
                     icon={<ChevronRight size={16} aria-hidden="true" />}
                     isDisabled={saving}
-                    onClick={() => setRoute({ presetId: preset.id })}
+                    // The focus anchor for the way back. It rides the control
+                    // the page already renders, so the settings kit does not
+                    // need a row-level data escape hatch for one caller.
+                    data-subagent-preset={preset.id}
+                    onClick={() => openEditor(preset.id)}
                   />
                 </>
               )}
@@ -270,7 +348,7 @@ function SubagentPresetEditor(props: {
   const initialModels = initialConnection && initialConnection.enabled
     ? connectionEnabledModelIds(initialConnection)
     : [];
-  const [draft, setDraft] = useState<EditorDraft>(() => ({
+  const [draft, setDraft] = useState<SubagentEditorDraft>(() => ({
     // Empty, not a pre-derived `subagent`: an id the user has not been asked
     // for yet reads as a value the page already decided. Typing the name fills
     // it (until the user takes it over), and the placeholder says what it is.
@@ -281,6 +359,7 @@ function SubagentPresetEditor(props: {
     connectionSlug: props.preset?.connectionSlug ?? usableConnections[0]?.slug ?? '',
     model: props.preset?.model ?? initialModels[0] ?? '',
     thinkingLevel: props.preset?.thinkingLevel ?? '',
+    enabled: props.preset?.enabled ?? true,
   }));
   const [idWasEdited, setIdWasEdited] = useState(props.preset !== null);
   const [submitted, setSubmitted] = useState(false);
@@ -334,11 +413,7 @@ function SubagentPresetEditor(props: {
   }
 
   function updateName(name: string): void {
-    setDraft((current) => ({
-      ...current,
-      name,
-      ...(!idWasEdited ? { id: suggestSubagentPresetId(name, existingIds) } : {}),
-    }));
+    setDraft((current) => nextSubagentDraftForName(current, name, idWasEdited, existingIds));
   }
 
   function selectConnection(connectionSlug: string): void {
@@ -363,10 +438,7 @@ function SubagentPresetEditor(props: {
       connectionSlug: draft.connectionSlug,
       model: draft.model,
       ...(draft.thinkingLevel ? { thinkingLevel: draft.thinkingLevel } : {}),
-      // A preset is created ready to use, and whether the main agent may still
-      // select it is the list row's switch — the one place that answers it. A
-      // second "enable now" control in here answered the same question twice.
-      enabled: props.preset?.enabled ?? true,
+      enabled: draft.enabled,
     });
   }
 
@@ -410,11 +482,16 @@ function SubagentPresetEditor(props: {
             agent's routing both reference it — so it reads as a row's value.
             Only a new preset's id is still the user's to type. */}
         {props.preset ? (
-          <SettingsRow
-            label={copy.editor.id}
-            description={copy.editor.idDescription}
-            align="start"
-            end={<code className="settingsReadOnlyValue">{props.preset.id}</code>}
+          // `SettingRow mono`, not a hand-rolled <code> in the end slot: the
+          // kit renders machine text as its own full-width line under the
+          // description, because `.settingsReadOnlyValue` without
+          // `data-mono="true"` is body type in a 320px right-anchored box —
+          // and a subagent_id runs to 128 characters.
+          <SettingRow
+            title={copy.editor.id}
+            detail={copy.editor.idDescription}
+            value={props.preset.id}
+            mono
           />
         ) : (
           <SettingsField>
@@ -521,13 +598,36 @@ function SubagentPresetEditor(props: {
             )}
           />
         ) : null}
+        {/* Only on create. An existing preset is switched from its list row —
+            one back-press away, and the header states the current value — but
+            a preset that does not exist yet has no row, so without this the
+            user cannot land one in a disabled state and has to reach for the
+            switch in the window where the main agent can already select it. */}
+        {props.preset ? null : (
+          <SettingsRow
+            label={copy.editor.enabled}
+            description={copy.editor.enabledDescription}
+            align="start"
+            end={(
+              <Switch
+                label={copy.editor.enabled}
+                isLabelHidden
+                value={draft.enabled}
+                isDisabled={props.isSaving}
+                onChange={(enabled) => setDraft((current) => ({ ...current, enabled }))}
+              />
+            )}
+          />
+        )}
       </SettingsSection>
 
       {/* Save commits the whole preset, not the route group it would sit
           inside, so it stands on its own between the groups and the delete
-          section. */}
-      <SettingsSection variant="bare">
-        <HStack gap={2} wrap="wrap">
+          section. A bare `HStack` under the page stack, not a title-less
+          `SettingsSection`: with no header that section renders no header and
+          no divider, so it was two wrappers around the same 32px rhythm the
+          page stack already gives any direct child. */}
+      <HStack gap={2} wrap="wrap">
           <Button
             variant="primary"
             label={props.isSaving
@@ -544,13 +644,12 @@ function SubagentPresetEditor(props: {
             isDisabled={props.isSaving}
             onClick={props.onCancel}
           />
-        </HStack>
-      </SettingsSection>
+      </HStack>
 
       {/* Deletion is last and stands alone, so a mis-aimed cursor has nothing
           quiet to hit beside it — the providers detail answers it the same way. */}
       {props.onDelete ? (
-        <SettingsSection title={copy.editor.dangerZone} description={copy.remove.description}>
+        <SettingsSection title={copy.editor.dangerZone} description={copy.editor.dangerZoneHelp}>
           <SettingsActions>
             <Button
               variant="destructive"
diff --git a/apps/desktop/stories/FIDELITY.md b/apps/desktop/stories/FIDELITY.md
index a61cdaa5bb..914aa2dd46 100644
--- a/apps/desktop/stories/FIDELITY.md
+++ b/apps/desktop/stories/FIDELITY.md
@@ -19,11 +19,16 @@ The annotation is prose on purpose. Its value is that someone traced the path an
 
 Two of the first batch of annotations were wrong, and both were caught by reading rather than by running anything: one named a path through a builder that cannot produce the state (`CommandPaletteDisabledCommand`), and one named two hosts for a frame that is only one of them. Write the sentence narrow enough to be falsifiable — the host, the builder, the gate — because a sentence vague enough to always be true buys nothing.
 
-## One story per state, not per click
+## One story per state, not per variant
 
-A surface gets one story. It earns a second only for a state that story cannot reach — not for a state one click away from it, and not for the same state at another width: the smoke script already renders every story at three viewports, so a narrow variant needs a layout that genuinely differs there.
+A story earns its place by rendering pixels no other story renders. A second level of a page — a route level that replaces the list, a form that shares no content with the screen behind it — is its own state, and gets its own story even though a click reaches it. A narrower version of a state already on screen is not.
 
-Extra stories do not just cost their own size. A reviewer scanning the sidebar can no longer tell which entry is the page, and the duplicates re-render the same pixels every smoke run while claiming coverage they do not add. Where a state matters but does not earn a story, pin it somewhere that runs — a `packages/ui` test or an e2e journey.
+Two facts decide it, and both were guessed wrong once:
+
+- **Where a story renders.** `scripts/storybook-visual-smoke.mjs` renders the `product-smoke-manifest.json` surfaces at three viewports across light and dark, and every *other* story exactly once, at 1280 wide in light (`catalogJobs`). A story is not a width matrix; a surface that needs one belongs in the manifest. And `parameters.viewport.defaultViewport` does nothing in Storybook 10, so a story claiming a viewport that way has been rendering at the default width all along.
+- **Whether `play` reaches the state.** `play` does run in the browser, so a story that clicks into a level renders that level, for a reviewer and for the smoke pass. What it does not do is fail the run when its assertions throw (see below) — so use `play` to reach a state, never to prove one.
+
+Extra stories still cost: a reviewer scanning the sidebar cannot tell which entry is the page, and duplicates re-render the same pixels every run while claiming coverage they do not add. Where a state matters but renders nothing new, pin it somewhere that runs — a `packages/ui` test or an e2e journey.
 
 ## The frame matters, not just the component
 
@@ -39,7 +44,7 @@ If the runtime computes a field, ask the runtime for it. A story that hardcodes
 
 ## Assertions belong where they run
 
-`play` functions do not execute here. No test addon is configured, and `scripts/storybook-visual-smoke.mjs` only listens for the failure events a play function would emit — a story whose `play` throws unconditionally still ships green. #1853 landed a computed line-height assertion in a `play`; it never ran once. Put behavioural and computed-style contracts in a `packages/ui` test or in the smoke script's `checks`, and keep stories to what they can actually prove: that the surface renders.
+`play` functions run, but nothing collects what they assert. No test addon is configured, and `scripts/storybook-visual-smoke.mjs` only listens for the failure events a play function would emit — so a story whose `play` throws unconditionally still ships green. #1853 landed a computed line-height assertion in a `play`; it has never failed a run and never could. The interaction still happens, which is why `play` is the right way to *reach* a second level (above) and the wrong way to *check* one. Put behavioural and computed-style contracts in a `packages/ui` test or in the smoke script's `checks`, and keep stories to what they can actually prove: that the surface renders.
 
 ## A story that renders nothing is not a story
 
diff --git a/apps/desktop/stories/settings/settings-pages.stories.tsx b/apps/desktop/stories/settings/settings-pages.stories.tsx
index 79df27ac51..0ca5858d4e 100644
--- a/apps/desktop/stories/settings/settings-pages.stories.tsx
+++ b/apps/desktop/stories/settings/settings-pages.stories.tsx
@@ -664,6 +664,15 @@ const subagentStorySettings = mergeSettings(createDefaultSettings(), {
         thinkingLevel: 'high',
         enabled: true,
       },
+      {
+        id: 'orphaned-route',
+        name: '外部资料检索',
+        description: '连接被删除后仍处于启用状态，用于展示失效路由。',
+        profile: 'web_research',
+        connectionSlug: 'removed-connection',
+        model: 'legacy-search-model',
+        enabled: true,
+      },
       {
         id: 'retired-researcher',
         name: '旧研究配置',
@@ -913,6 +922,24 @@ export const Subagents: Story = {
   render: () => <SettingsStory section="subagents" />,
 };
 
+// Real path: 设置 → 子 Agent → 配置“实现与验证”. A second story because the
+// editor is a route level, not a disclosure: it replaces the list, shares no
+// content with it, and is where this page's pixel work happens. Landed on the
+// implementation preset because it exercises the most of the level at once —
+// the settled read-only subagent_id, the capability warning, the degraded
+// model option, and the delete section.
+export const SubagentEditor: Story = {
+  decorators: [withSubagentSettingsBridge],
+  render: () => <SettingsStory section="subagents" />,
+  play: async ({ canvasElement }) => {
+    const button = await waitForStoryButton(
+      canvasElement,
+      (candidate) => candidate.getAttribute('aria-label') === '配置“实现与验证”',
+    );
+    await userEvent.click(button);
+  },
+};
+
 // Real path: 设置 → 通用.
 export const General: Story = {
   decorators: [withSettingsBridge],

From 5a364f7c7c0e37e7133705610d6dc78c8d2e0bb8 Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Mon, 3 Aug 2026 21:31:26 +0800
Subject: [PATCH 6/8] fix(desktop): make the subagent page agree with the
 contract it writes to
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Second review round on this PR found the page disagreeing with three owners
at once, so this fixes them at those owners rather than at the symptoms.

The store: `normalizeSubagentSettings` DROPS a preset it dislikes instead of
rejecting the write. A name past 128 characters therefore resolved the promise,
returned the user to the list, and deleted the row they had just edited — with
no error anywhere. The limits are now exported from core and enforced where the
fields change, and `persist` reads the result back instead of trusting a
resolved promise, which also covers a preset created into a list that filled up
elsewhere. Conversely the store makes `description` optional and the list has a
fallback line for it, so requiring it here made a legal preset uneditable until
the user wrote prose; that requirement is gone.

The id: an existing preset's id now comes from the preset at submit time, not
from the draft. `idWasEdited` was the only thing standing between a rename and
a silently re-keyed preset, and the branch it guarded does not even render the
field — the flag disarmed a trap that no longer exists.

The route controller: `useSettingsRouteFocus` is now shared with ProvidersPanel,
which had the same 48 lines of arrive-vs-navigate, rAF, return-focus and
fallback logic written out separately. A focus rule is the one duplication that
cannot be seen on screen when the two copies drift. The unsatisfiable-edit-route
rule moves out with it into `resolveSubagentRoute`, where it can be tested — its
regression (a vanished preset rendering the create branch, so saving appended a
second preset) had no coverage at all.

Also: `enabled` had three authorities (a list switch, a create-only switch, and
a read-only badge on the level that owns deletion) — the editor now carries it
in both branches and the badge is gone; the route's two choices get two errors
instead of one aimed at the connection; `contract` was a required prop with
zero consumers; `.settingsRouteLevel` moves out of the models stylesheet to the
shared one, since it now has two owners.

Tests: the rename that could re-key a preset, the delete flow in both
directions (cancel keeps it; confirm returns to the list and lands focus on the
fallback), and arrival focus asserted positively on the settings nav item.
---
 apps/desktop/e2e/settings.spec.ts             |  84 +++++-
 .../subagent-preset-presentation.test.ts      |  42 ++-
 .../locales/settings-subagents-copy.ts        |  36 +--
 .../src/renderer/settings/ProvidersPanel.tsx  |  76 ++---
 .../renderer/settings/settings-route-focus.ts |  74 +++++
 .../settings/settings-route-header.tsx        |  12 +-
 .../settings/subagent-preset-presentation.ts  |  26 ++
 .../settings/subagent-settings-page.tsx       | 279 ++++++++----------
 apps/desktop/src/renderer/styles/settings.css |   1 +
 .../src/renderer/styles/settings/models.css   |  11 -
 .../src/renderer/styles/settings/route.css    |  13 +
 packages/core/src/index.ts                    |   2 +
 packages/core/src/subagent-settings.ts        |  12 +-
 13 files changed, 401 insertions(+), 267 deletions(-)
 create mode 100644 apps/desktop/src/renderer/settings/settings-route-focus.ts
 create mode 100644 apps/desktop/src/renderer/styles/settings/route.css

diff --git a/apps/desktop/e2e/settings.spec.ts b/apps/desktop/e2e/settings.spec.ts
index e8c6c51fc3..11972366d9 100644
--- a/apps/desktop/e2e/settings.spec.ts
+++ b/apps/desktop/e2e/settings.spec.ts
@@ -54,15 +54,19 @@ test('subagent presets can be reviewed and edited in desktop settings', async ({
 
   await page.getByRole('button', { name: '展开侧边栏' }).click();
   await page.getByRole('button', { name: '设置' }).click();
-  await settingsNavigation(page).getByRole('button', { name: '子 Agent', exact: true }).click();
+  const navItem = settingsNavigation(page).getByRole('button', { name: '子 Agent', exact: true });
+  await navItem.click();
 
   const settings = page.getByRole('main', { name: '设置内容' });
   await expect(settings.getByRole('heading', { name: '子 Agent', exact: true })).toBeVisible();
   await expect(settings.getByText('E2E 快速阅读', { exact: true })).toBeVisible();
-  await expect(settings.getByText('已停用', { exact: true })).toBeVisible();
-  // Arriving is not navigating: the page must not pull focus off the settings
-  // nav item the user just clicked. Only a level change moves focus.
-  await expect(settings.getByRole('button', { name: '添加子 Agent' })).not.toBeFocused();
+  // The row's switch states the disabled preset; a badge beside it would be the
+  // same fact twice.
+  const rowSwitch = settings.getByRole('switch', { name: '启用: E2E 快速阅读' });
+  await expect(rowSwitch).not.toBeChecked();
+  // Arriving is not navigating: focus stays on the settings nav item the user
+  // just clicked. Only a level change moves it.
+  await expect(navItem).toBeFocused();
 
   // The editor is a route level, not a dialog: the list is replaced in place
   // and the back affordance is the only way out.
@@ -72,10 +76,13 @@ test('subagent presets can be reviewed and edited in desktop settings', async ({
   // A level change moves focus to the level itself; without it the chevron
   // that had focus unmounts and a keyboard user restarts from document.body.
   await expect(settings.locator('[data-maka-contract="subagent-detail"]')).toBeFocused();
-  // The level owns the whole preset, so it carries the three things the list
-  // row deliberately does not: the settled id, the disabled state, and deletion.
+  // The level owns the whole preset, so it carries the two things the list row
+  // deliberately does not: the settled id, and deletion.
   await expect(settings.getByText('e2e-fast-reader', { exact: true })).toBeVisible();
   await expect(settings.getByRole('button', { name: '删除', exact: true })).toBeVisible();
+  // Renaming is the one edit that could re-key the preset: the id derives from
+  // the name while creating, and an existing preset must never follow it.
+  await settings.getByRole('textbox', { name: '显示名称' }).fill('E2E 快速阅读 v2');
   await settings.getByRole('textbox', { name: '适用场景' }).fill('快速阅读代码，并总结关键调用链。');
   await settings.getByRole('button', { name: '保存', exact: true }).click();
 
@@ -86,8 +93,65 @@ test('subagent presets can be reviewed and edited in desktop settings', async ({
   await expect.poll(async () => page.evaluate(async () => {
     const current = await window.maka.settings.get();
     const preset = current.subagents.presets[0];
-    return { description: preset?.description, enabled: preset?.enabled };
-  })).toEqual({ description: '快速阅读代码，并总结关键调用链。', enabled: false });
+    return { id: preset?.id, name: preset?.name, description: preset?.description, enabled: preset?.enabled };
+  })).toEqual({
+    id: 'e2e-fast-reader',
+    name: 'E2E 快速阅读 v2',
+    description: '快速阅读代码，并总结关键调用链。',
+    enabled: false,
+  });
+});
+
+test('deleting a subagent preset is reversible until the confirm is accepted', async ({ window: page }) => {
+  await page.evaluate(async () => {
+    const connections = await window.maka.connections.list();
+    const connection = connections[0];
+    if (!connection) throw new Error('E2E subagent settings requires a seeded connection');
+    await window.maka.settings.update({
+      subagents: {
+        presets: [{
+          id: 'e2e-doomed',
+          name: 'E2E 待删除',
+          description: '这个配置会在本次测试里被删除。',
+          profile: 'local_read',
+          connectionSlug: connection.slug,
+          model: connection.enabledModelIds?.[0] ?? connection.defaultModel,
+          enabled: true,
+        }],
+      },
+    });
+  });
+
+  await page.getByRole('button', { name: '展开侧边栏' }).click();
+  await page.getByRole('button', { name: '设置' }).click();
+  await settingsNavigation(page).getByRole('button', { name: '子 Agent', exact: true }).click();
+
+  const settings = page.getByRole('main', { name: '设置内容' });
+  await settings.getByRole('button', { name: '配置“E2E 待删除”' }).click();
+  const deleteButton = settings.getByRole('button', { name: '删除', exact: true });
+
+  // Cancelling the confirm has to leave the preset alone — the destructive path
+  // is the one place where "it did nothing" cannot be checked by eye.
+  await deleteButton.click();
+  const confirm = page.getByRole('alertdialog');
+  await expect(confirm).toBeVisible();
+  await confirm.getByRole('button', { name: '取消', exact: true }).click();
+  await expect(confirm).toBeHidden();
+  await expect(settings.getByText('e2e-doomed', { exact: true })).toBeVisible();
+
+  await deleteButton.click();
+  await expect(confirm).toBeVisible();
+  await confirm.getByRole('button', { name: '删除', exact: true }).click();
+  await expect(confirm).toBeHidden();
+
+  // Deletion is the only way the row a user came from can be missing, so it is
+  // the only thing that exercises the focus fallback.
+  await expect(settings.getByText('E2E 待删除', { exact: true })).toBeHidden();
+  await expect(settings.getByRole('button', { name: '添加子 Agent' })).toBeFocused();
+  await expect.poll(async () => page.evaluate(async () => {
+    const current = await window.maka.settings.get();
+    return current.subagents.presets.length;
+  })).toBe(0);
 });
 
 test('a subagent preset can be created disabled and then enabled from its row', async ({ window: page }) => {
@@ -108,7 +172,7 @@ test('a subagent preset can be created disabled and then enabled from its row',
   // The id derives from the name until the user takes it over.
   await expect(settings.getByRole('textbox', { name: 'subagent_id' })).toHaveValue('e2e-web-research');
   await settings.getByRole('textbox', { name: '适用场景' }).fill('查找外部资料。');
-  await settings.getByRole('switch', { name: '创建后即可用' }).click();
+  await settings.getByRole('switch', { name: '启用', exact: true }).click();
   await settings.getByRole('button', { name: '创建', exact: true }).click();
 
   await expect(settings.getByText('E2E Web Research', { exact: true })).toBeVisible();
diff --git a/apps/desktop/src/main/__tests__/subagent-preset-presentation.test.ts b/apps/desktop/src/main/__tests__/subagent-preset-presentation.test.ts
index 1f5a76da81..4a7fd7ba97 100644
--- a/apps/desktop/src/main/__tests__/subagent-preset-presentation.test.ts
+++ b/apps/desktop/src/main/__tests__/subagent-preset-presentation.test.ts
@@ -3,6 +3,7 @@ import { describe, it } from 'node:test';
 import type { LlmConnection, SubagentPreset } from '@maka/core';
 import {
   nextSubagentDraftForName,
+  resolveSubagentRoute,
   subagentPresetAvailability,
   suggestSubagentPresetId,
 } from '../../renderer/settings/subagent-preset-presentation.js';
@@ -40,9 +41,11 @@ describe('subagentPresetAvailability', () => {
       kind: 'available',
       tone: 'success',
     });
-    // The tone is asserted with the kind, not separately: the tone is what the
-    // list row actually renders, so a broken route quietly turning green is a
-    // pure-data regression this file is the only place to catch.
+    // The tone is asserted with the kind, not separately: it is what decides
+    // the badge variant, so a broken route quietly turning green is a pure-data
+    // regression this file is the only place to catch. `available` and
+    // `disabled` render no badge — the switch beside the row says the second —
+    // but they stay in the value range so callers branch on one thing.
     assert.deepEqual(subagentPresetAvailability(preset({ enabled: false }), []), {
       kind: 'disabled',
       tone: 'neutral',
@@ -110,3 +113,36 @@ describe('nextSubagentDraftForName', () => {
     );
   });
 });
+
+describe('resolveSubagentRoute', () => {
+  const fastReader = preset();
+
+  it('resolves an edit route to the preset it names', () => {
+    assert.deepEqual(resolveSubagentRoute({ kind: 'edit', presetId: 'fast-reader' }, [fastReader]), {
+      level: 'edit',
+      preset: fastReader,
+    });
+  });
+
+  it('renders the list for an edit route whose preset is gone', () => {
+    // The whole reason this is a function: a preset deleted from under an open
+    // editor used to leave `preset` null while the editor still rendered, which
+    // is its create branch — so saving appended a SECOND preset instead of
+    // updating one. Nothing on screen said so.
+    assert.deepEqual(resolveSubagentRoute({ kind: 'edit', presetId: 'gone' }, [fastReader]), {
+      level: 'list',
+      preset: null,
+    });
+  });
+
+  it('carries list and create through untouched', () => {
+    assert.deepEqual(resolveSubagentRoute({ kind: 'list' }, [fastReader]), {
+      level: 'list',
+      preset: null,
+    });
+    assert.deepEqual(resolveSubagentRoute({ kind: 'create' }, []), {
+      level: 'create',
+      preset: null,
+    });
+  });
+});
diff --git a/apps/desktop/src/renderer/locales/settings-subagents-copy.ts b/apps/desktop/src/renderer/locales/settings-subagents-copy.ts
index 6b706554c9..1c987d3510 100644
--- a/apps/desktop/src/renderer/locales/settings-subagents-copy.ts
+++ b/apps/desktop/src/renderer/locales/settings-subagents-copy.ts
@@ -15,7 +15,6 @@ export type SubagentSettingsCopy = {
     title: string;
     count(total: number, max: number): string;
     add: string;
-    limitNote: string;
     emptyTitle: string;
     emptyDescription: string;
   };
@@ -25,14 +24,12 @@ export type SubagentSettingsCopy = {
     fallbackDescription: string;
   };
   status: {
-    disabled: string;
     missingConnection: string;
     connectionDisabled: string;
     modelDisabled: string;
   };
   editor: {
     backToList: string;
-    createTitle: string;
     createSubtitle: string;
     editSubtitle: string;
     groupPurpose: string;
@@ -60,10 +57,10 @@ export type SubagentSettingsCopy = {
     noConnection: string;
     noModel: string;
     requiredName: string;
-    requiredDescription: string;
     invalidId: string;
     duplicateId: string;
-    invalidRoute: string;
+    invalidConnection: string;
+    invalidModel: string;
     cancel: string;
     create: string;
     save: string;
@@ -77,6 +74,7 @@ export type SubagentSettingsCopy = {
   };
   toast: {
     saveFailed: string;
+    rejected: string;
   };
   profiles: Record<SubagentProfile, ProfileCopy>;
   thinking: Record<ThinkingLevel, string>;
@@ -88,7 +86,6 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
       title: '已批准的子 Agent',
       count: (total, max) => `共 ${total} / ${max} 个配置`,
       add: '添加子 Agent',
-      limitNote: '已达到配置数量上限。',
       emptyTitle: '还没有子 Agent 配置',
       emptyDescription: '添加一个配置后，主 Agent 就能把合适的任务交给独立模型处理。',
     },
@@ -98,14 +95,12 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
       fallbackDescription: '尚未填写适用场景',
     },
     status: {
-      disabled: '已停用',
       missingConnection: '连接不存在',
       connectionDisabled: '连接已停用',
       modelDisabled: '模型未启用',
     },
     editor: {
       backToList: '返回子 Agent 列表',
-      createTitle: '添加子 Agent',
       createSubtitle: '创建一个可由主 Agent 自动选择的模型配置。',
       editSubtitle: '修改适用场景、能力边界和模型路由。',
       groupPurpose: '用途',
@@ -113,10 +108,10 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
       groupRoute: '能力与模型',
       groupRouteHelp: '固定这个子 Agent 能做什么，以及它运行在哪个模型上。',
       dangerZone: '删除子 Agent',
-      dangerZoneHelp: '删除后，这个配置将从设置中移除，且无法撤销。',
+      dangerZoneHelp: '此操作不可撤销。',
       delete: '删除',
-      enabled: '创建后即可用',
-      enabledDescription: '关闭后，配置会被保存但主 Agent 暂时不会选择它。',
+      enabled: '启用',
+      enabledDescription: '关闭后配置仍会保留，但主 Agent 暂时不会选择它。',
       name: '显示名称',
       namePlaceholder: '快速代码阅读',
       id: 'subagent_id',
@@ -133,10 +128,10 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
       noConnection: '请先在“模型”页启用一个模型连接。',
       noModel: '所选连接没有已启用的模型。',
       requiredName: '请输入显示名称。',
-      requiredDescription: '请说明这个子 Agent 的适用场景。',
       invalidId: '只能使用字母、数字、点、下划线、冒号和连字符，最多 128 个字符。',
       duplicateId: '这个 subagent_id 已经存在。',
-      invalidRoute: '请选择已启用的连接和模型。',
+      invalidConnection: '请选择一个已启用的模型连接。',
+      invalidModel: '请选择一个已启用的模型。',
       cancel: '取消',
       create: '创建',
       save: '保存',
@@ -150,6 +145,7 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
     },
     toast: {
       saveFailed: '保存子 Agent 配置失败',
+      rejected: '配置没有被保存。请确认名称长度和配置数量都在上限之内。',
     },
     profiles: {
       local_read: { label: '代码阅读', description: '只读访问当前工作区，适合搜索、理解和总结代码。' },
@@ -171,7 +167,6 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
       title: 'Approved subagents',
       count: (total, max) => `${total} of ${max} presets`,
       add: 'Add subagent',
-      limitNote: 'The preset limit has been reached.',
       emptyTitle: 'No subagent presets yet',
       emptyDescription: 'Add a preset so the main agent can delegate suitable work to a separate model.',
     },
@@ -181,14 +176,12 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
       fallbackDescription: 'No usage guidance yet',
     },
     status: {
-      disabled: 'Disabled',
       missingConnection: 'Connection missing',
       connectionDisabled: 'Connection disabled',
       modelDisabled: 'Model not enabled',
     },
     editor: {
       backToList: 'Back to subagents',
-      createTitle: 'Add subagent',
       createSubtitle: 'Create a model preset that the main agent can select automatically.',
       editSubtitle: 'Change its usage guidance, capability boundary, and model route.',
       groupPurpose: 'Purpose',
@@ -196,10 +189,10 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
       groupRoute: 'Capability and model',
       groupRouteHelp: 'Fix what this subagent may do, and which model it runs on.',
       dangerZone: 'Remove subagent',
-      dangerZoneHelp: 'Removing takes this preset out of settings, and cannot be undone.',
+      dangerZoneHelp: 'This cannot be undone.',
       delete: 'Remove',
-      enabled: 'Available once created',
-      enabledDescription: 'Turn this off to save the preset without letting the main agent select it yet.',
+      enabled: 'Enabled',
+      enabledDescription: 'Turn this off to keep the preset without letting the main agent select it.',
       name: 'Display name',
       namePlaceholder: 'Fast code reader',
       id: 'subagent_id',
@@ -216,10 +209,10 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
       noConnection: 'Enable a model connection on the Models page first.',
       noModel: 'The selected connection has no enabled models.',
       requiredName: 'Enter a display name.',
-      requiredDescription: 'Describe when this subagent should be used.',
       invalidId: 'Use only letters, numbers, dots, underscores, colons, and hyphens, up to 128 characters.',
       duplicateId: 'That subagent_id already exists.',
-      invalidRoute: 'Select an enabled connection and model.',
+      invalidConnection: 'Select an enabled model connection.',
+      invalidModel: 'Select an enabled model.',
       cancel: 'Cancel',
       create: 'Create',
       save: 'Save',
@@ -233,6 +226,7 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
     },
     toast: {
       saveFailed: 'Failed to save subagent presets',
+      rejected: 'The preset was not saved. Check that its name length and the preset count are within their limits.',
     },
     profiles: {
       local_read: { label: 'Code reading', description: 'Read-only access to the current workspace for search, understanding, and summaries.' },
diff --git a/apps/desktop/src/renderer/settings/ProvidersPanel.tsx b/apps/desktop/src/renderer/settings/ProvidersPanel.tsx
index 3d1c0e2ef8..32eb200efd 100644
--- a/apps/desktop/src/renderer/settings/ProvidersPanel.tsx
+++ b/apps/desktop/src/renderer/settings/ProvidersPanel.tsx
@@ -30,6 +30,7 @@ import {
   type SetupTarget,
 } from './provider-catalog-page';
 import { ConnectionDetail } from './provider-connection-detail';
+import { useSettingsRouteFocus } from './settings-route-focus';
 import { SettingsRouteHeader } from './settings-route-header';
 import { ProviderLogo, providerDisplay } from './provider-display';
 import { oauthPanelSubtitle } from './provider-oauth-section';
@@ -99,7 +100,6 @@ export function ProvidersPanel({ bridge, initialPage = 'connections', initialCon
   // Which row the user left the list from, so returning puts focus back where
   // they were rather than on the page's primary action.
   const listReturnFocusRef = useRef<string | null>(null);
-  const hasNavigatedRef = useRef(false);
   const locale = useUiLocale();
   const providerCopy = getProviderSettingsCopy(locale);
   const copy = providerCopy.panel;
@@ -199,60 +199,23 @@ export function ProvidersPanel({ bridge, initialPage = 'connections', initialCon
   // as. Deriving that beats scheduling a setState from inside render.
   const level: PanelRoute['kind'] = route.kind === 'detail' && !selected ? 'list' : route.kind;
 
-  // Focus follows the level, to its first meaningful control. Navigating
-  // without this leaves the ring on `document.body` every time a level
-  // unmounts, which costs a keyboard user their place on every move.
-  //
-  // Navigating, not arriving: the panel does not grab focus when the settings
-  // page first renders the list — the user is still in the settings nav they
-  // clicked to get here.
-  useEffect(() => {
-    if (loading) return;
-    if (!hasNavigatedRef.current) {
-      hasNavigatedRef.current = true;
-      return;
-    }
-    const frame = window.requestAnimationFrame(focusLevel);
-    return () => window.cancelAnimationFrame(frame);
-
-    function focusLevel() {
-      const find = (selector: string) => document.querySelector<HTMLElement>(selector);
-      // `preventScroll` because this is a landing, not a jump: the level just
-      // rendered at the top of the content area, and scrolling to whatever the
-      // focus target happens to be would push its own header out of view.
-      const focusFirst = (...selectors: string[]) => {
-        for (const selector of selectors) {
-          const element = find(selector);
-          if (element) return element.focus({ preventScroll: true });
-        }
-      };
-      switch (level) {
-        case 'catalog':
-          focusFirst('[data-maka-contract="provider-catalog"] input');
-          return;
-        case 'setup':
-          focusFirst('[data-maka-contract="provider-setup"] input', '[data-maka-contract="provider-setup"]');
-          return;
-        case 'detail':
-          // The region, not its back button: an IconButton opens its tooltip on
-          // focus, so focusing one on arrival would pop a tooltip at every
-          // mouse user who merely clicked a row.
-          focusFirst('[data-maka-contract="connection-detail"]');
-          return;
-        case 'list': {
-          // Consumed here and only here: the ref is set on the way down and has
-          // to survive the levels in between.
-          const returnToSlug = listReturnFocusRef.current;
-          listReturnFocusRef.current = null;
-          // The row the user came from may be gone — that is exactly what
-          // happens after a deletion — so the primary action is the fallback,
-          // not the default.
-          ((returnToSlug ? find(`[data-connection-slug="${returnToSlug}"] button`) : null)
-            ?? addButtonRef.current)?.focus({ preventScroll: true });
-        }
-      }
-    }
-  }, [level, route, loading]);
+  useSettingsRouteFocus({
+    level,
+    listLevel: 'list',
+    routeKey: route,
+    isReady: !loading,
+    focusSelectors: (current) => current === 'detail'
+      // The region, not its back button: an IconButton opens its tooltip on
+      // focus, so focusing one on arrival would pop a tooltip at every mouse
+      // user who merely clicked a row.
+      ? ['[data-maka-contract="connection-detail"]']
+      : current === 'catalog'
+        ? ['[data-maka-contract="provider-catalog"] input']
+        : ['[data-maka-contract="provider-setup"] input', '[data-maka-contract="provider-setup"]'],
+    listReturnFocusRef,
+    listReturnSelector: (slug) => `[data-connection-slug="${slug}"] button`,
+    listFallbackRef: addButtonRef,
+  });
 
   if (loading) {
     return (
@@ -278,7 +241,6 @@ export function ProvidersPanel({ bridge, initialPage = 'connections', initialCon
           <SettingsRouteHeader
             onBack={goToList}
             backLabel={copy.backToList}
-            contract="connection-detail-back"
             logo={<ProviderLogo type={selected.providerType} compact />}
             title={selected.name}
             badge={selected.slug === defaultSlug ? <Badge variant="neutral" label={copy.default} /> : null}
@@ -302,7 +264,6 @@ export function ProvidersPanel({ bridge, initialPage = 'connections', initialCon
           <SettingsRouteHeader
             onBack={goToList}
             backLabel={copy.backToList}
-            contract="catalog-back"
             title={copy.addConnection}
             subtitle={copy.addHelp}
           />
@@ -317,7 +278,6 @@ export function ProvidersPanel({ bridge, initialPage = 'connections', initialCon
           <SettingsRouteHeader
             onBack={goBack}
             backLabel={route.origin === 'catalog' ? copy.backToCatalog : copy.backToList}
-            contract="setup-back"
             logo={<ProviderLogo type={route.target.providerType} compact />}
             title={copy.connectTitle(route.target.name)}
             subtitle={route.target.method === 'account'
diff --git a/apps/desktop/src/renderer/settings/settings-route-focus.ts b/apps/desktop/src/renderer/settings/settings-route-focus.ts
new file mode 100644
index 0000000000..1e7471354b
--- /dev/null
+++ b/apps/desktop/src/renderer/settings/settings-route-focus.ts
@@ -0,0 +1,74 @@
+// Focus follows the level, for any settings page that owns more than one.
+//
+// Without this a level change leaves the ring on `document.body` — the control
+// that had focus just unmounted — and a keyboard user restarts from the top of
+// the document on every move. A Dialog gets this for free; a route level has
+// to say it, and both settings pages that own levels said it separately until
+// this file existed. A focus rule is the one duplication that cannot be seen
+// on screen when the two copies drift.
+import { useEffect, useRef, type RefObject } from 'react';
+
+export type SettingsRouteFocusOptions = {
+  /** The level being rendered. `listLevel` is the one the user returns to. */
+  level: string;
+  listLevel: string;
+  /**
+   * Anything that should re-run the focus move without changing `level` —
+   * a second detail opened directly from a first, say. Compared by identity.
+   */
+  routeKey?: unknown;
+  /** False while the page has nothing to focus yet (loading its data). */
+  isReady?: boolean;
+  /** Focus targets for a non-list level, in preference order. */
+  focusSelectors(level: string): readonly string[];
+  /** Which row the user left the list from; consumed on the way back. */
+  listReturnFocusRef: RefObject<string | null>;
+  listReturnSelector(token: string): string;
+  /** Where focus lands when the row is gone — deletion is exactly that. */
+  listFallbackRef: RefObject<HTMLElement | null>;
+};
+
+export function useSettingsRouteFocus(options: SettingsRouteFocusOptions): void {
+  // Read through a ref so callers can pass fresh closures every render without
+  // the effect re-running: the level (and `routeKey`) is what decides a move.
+  const latest = useRef(options);
+  latest.current = options;
+  const { level, routeKey, isReady = true } = options;
+
+  // Navigating, not arriving: the page does not grab focus when the settings
+  // surface first renders it — the user is still on the settings nav item they
+  // clicked to get here, and taking the ring off it strands them.
+  const hasNavigatedRef = useRef(false);
+  useEffect(() => {
+    if (!isReady) return;
+    if (!hasNavigatedRef.current) {
+      hasNavigatedRef.current = true;
+      return;
+    }
+    const frame = window.requestAnimationFrame(() => {
+      const current = latest.current;
+      // `preventScroll` throughout because this is a landing, not a jump: the
+      // level just rendered at the top of the content area, and scrolling to
+      // whatever the focus target happens to be would push its header away.
+      if (level !== current.listLevel) {
+        for (const selector of current.focusSelectors(level)) {
+          const element = document.querySelector<HTMLElement>(selector);
+          if (element) {
+            element.focus({ preventScroll: true });
+            return;
+          }
+        }
+        return;
+      }
+      // Consumed here and only here: the ref is set on the way down and has to
+      // survive the levels in between.
+      const returnTo = current.listReturnFocusRef.current;
+      current.listReturnFocusRef.current = null;
+      const row = returnTo
+        ? document.querySelector<HTMLElement>(current.listReturnSelector(returnTo))
+        : null;
+      (row ?? current.listFallbackRef.current)?.focus({ preventScroll: true });
+    });
+    return () => window.cancelAnimationFrame(frame);
+  }, [level, routeKey, isReady]);
+}
diff --git a/apps/desktop/src/renderer/settings/settings-route-header.tsx b/apps/desktop/src/renderer/settings/settings-route-header.tsx
index 18512ec0c6..2f265b2bd3 100644
--- a/apps/desktop/src/renderer/settings/settings-route-header.tsx
+++ b/apps/desktop/src/renderer/settings/settings-route-header.tsx
@@ -1,10 +1,7 @@
 // The header of a settings sub-level: back affordance, title, and one quiet
 // line of context.
 //
-// A settings page that owns more than one level (a list and the detail behind
-// a row) needs exactly one way back. This was private to `ProvidersPanel`,
-// where the four-level provider route lives; the subagent page needs the same
-// two-level shape, so the header moved here rather than being written twice.
+// A settings page that owns more than one level needs exactly one way back.
 //
 // Deliberately a `Toolbar` with everything in `startContent`: the back button,
 // the optional logo, and the title block read as one left-aligned cluster, so
@@ -19,10 +16,10 @@ import { ArrowLeft } from '@maka/ui/icons';
 export function SettingsRouteHeader(props: {
   onBack(): void;
   backLabel: string;
-  /** `data-maka-contract` on the back button, so an e2e can aim at this level. */
-  contract: string;
   logo?: ReactNode;
   title: string;
+  /** Wire the level's `aria-labelledby` to this heading, so it is announced. */
+  titleId?: string;
   badge?: ReactNode;
   subtitle?: string;
 }) {
@@ -38,12 +35,11 @@ export function SettingsRouteHeader(props: {
             tooltip={props.backLabel}
             icon={<ArrowLeft size={16} aria-hidden="true" />}
             onClick={props.onBack}
-            data-maka-contract={props.contract}
           />
           {props.logo}
           <VStack gap={0}>
             <HStack gap={2} vAlign="center">
-              <Heading level={3}>{props.title}</Heading>
+              <Heading level={3} id={props.titleId}>{props.title}</Heading>
               {props.badge}
             </HStack>
             {props.subtitle && (
diff --git a/apps/desktop/src/renderer/settings/subagent-preset-presentation.ts b/apps/desktop/src/renderer/settings/subagent-preset-presentation.ts
index 929e591daa..95ceee4ba4 100644
--- a/apps/desktop/src/renderer/settings/subagent-preset-presentation.ts
+++ b/apps/desktop/src/renderer/settings/subagent-preset-presentation.ts
@@ -5,6 +5,32 @@ import {
 } from '@maka/core';
 import type { StatusTone } from './settings-status-badge.js';
 
+/**
+ * Where the page is. `create` and `edit` are the same form; they are separate
+ * cases because the id is settled in one and typed in the other, and because
+ * an `edit` route can become unsatisfiable while `create` cannot.
+ */
+export type SubagentPageRoute =
+  | { kind: 'list' }
+  | { kind: 'create' }
+  | { kind: 'edit'; presetId: string };
+
+/**
+ * An edit route whose preset vanished (deleted, or removed by an external
+ * settings write) is an unsatisfiable route, not a state to correct: the list
+ * is what it renders as. Resolving it here rather than in the component keeps
+ * the rule testable — inlined, the only way to reach it was to delete a preset
+ * from under an open editor, and nothing did.
+ */
+export function resolveSubagentRoute(
+  route: SubagentPageRoute,
+  presets: readonly SubagentPreset[],
+): { level: SubagentPageRoute['kind']; preset: SubagentPreset | null } {
+  if (route.kind !== 'edit') return { level: route.kind, preset: null };
+  const preset = presets.find((candidate) => candidate.id === route.presetId) ?? null;
+  return preset ? { level: 'edit', preset } : { level: 'list', preset: null };
+}
+
 export type SubagentPresetAvailabilityKind =
   | 'available'
   | 'disabled'
diff --git a/apps/desktop/src/renderer/settings/subagent-settings-page.tsx b/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
index 3e362dd999..0e9173e24b 100644
--- a/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
+++ b/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
@@ -4,27 +4,24 @@
 //
 //   list ── editor(new | existing)
 //
-// The editor was a 560px Dialog holding eight fields behind an inner
-// scrollbar. A modal exists to interrupt the current task for something short
-// and immediately decidable while preserving the context behind it; naming a
-// capability, writing the guidance the main agent selects on, and picking a
-// connection/model/thinking route is none of those. Astryx says the same —
-// "if the content grows beyond what fits, consider a full page instead" — and
-// the providers panel next door already answers this exact shape with a route
-// level, so this page follows it rather than inventing a second answer.
+// A modal exists to interrupt the current task for something short and
+// immediately decidable; naming a capability, writing the guidance the main
+// agent selects on, and picking a connection/model/thinking route is none of
+// those. The providers panel next door already answers this same list→detail
+// shape with a route level, so this page follows it rather than inventing a
+// second answer — including its focus controller, which is shared.
 //
 // Every element here is a settings-kit part (`SettingsSection`, `SettingsRow`,
 // `SettingsField`, `SettingsActions`) or an Astryx primitive. The page owns no
-// CSS: the three hand-written `.subagentPreset*` rules — a flex-wrap action
-// cluster, an oklch-tinted warning callout, and a flex-end button row — were
-// each a restatement of something the kit or Astryx already draws (the row end
-// slot, `Banner status="warning"`, `SettingsActions`).
-import { useEffect, useMemo, useRef, useState } from 'react';
-import { Badge, Banner, HStack, VStack } from '@astryxdesign/core';
+// CSS of its own; `.settingsRouteLevel` is the shared route-level focus reset.
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
+import { Banner, HStack, VStack } from '@astryxdesign/core';
 import {
   connectionEnabledModelIds,
   isSafeSubagentPresetId,
   MAX_SUBAGENT_PRESETS,
+  SUBAGENT_PRESET_DESCRIPTION_MAX_CHARS,
+  SUBAGENT_PRESET_NAME_MAX_CHARS,
   thinkingVariantsForModel,
   type AppSettings,
   type LlmConnection,
@@ -34,6 +31,7 @@ import {
   type UpdateAppSettingsResult,
 } from '@maka/core';
 import {
+  Badge,
   Button,
   EmptyState,
   IconButton,
@@ -48,6 +46,7 @@ import {
 import { ChevronRight } from '@maka/ui/icons';
 import { getSubagentSettingsCopy } from '../locales/settings-subagents-copy.js';
 import { settingsActionErrorMessage } from './settings-error-copy.js';
+import { useSettingsRouteFocus } from './settings-route-focus.js';
 import { SettingsRouteHeader } from './settings-route-header.js';
 import {
   SettingsActions,
@@ -59,30 +58,15 @@ import {
 import { SettingRow } from './settings-rows.js';
 import {
   nextSubagentDraftForName,
+  resolveSubagentRoute,
   subagentPresetAvailability,
-  suggestSubagentPresetId,
+  type SubagentPageRoute,
 } from './subagent-preset-presentation.js';
 import { statusBadgeVariant } from './settings-status-badge.js';
 
-/**
- * Where the page is. `create` and `edit` are the same form; they are separate
- * cases because the id, the delete section, and the enabled control differ, and
- * because an `edit` route can become unsatisfiable while `create` cannot.
- */
-type PageRoute =
-  | { kind: 'list' }
-  | { kind: 'create' }
-  | { kind: 'edit'; presetId: string };
-
-export type SubagentEditorDraft = {
-  id: string;
-  name: string;
-  description: string;
-  profile: SubagentProfile;
-  connectionSlug: string;
-  model: string;
+/** The preset as the form holds it: `thinkingLevel` gains the Selector's ''. */
+type SubagentEditorDraft = Omit<SubagentPreset, 'thinkingLevel'> & {
   thinkingLevel: ThinkingLevel | '';
-  enabled: boolean;
 };
 
 export function SubagentSettingsPage(props: {
@@ -95,73 +79,61 @@ export function SubagentSettingsPage(props: {
   const locale = useUiLocale();
   const copy = getSubagentSettingsCopy(locale);
   const toast = useToast();
-  const [route, setRoute] = useState<PageRoute>({ kind: 'list' });
+  const [route, setRoute] = useState<SubagentPageRoute>({ kind: 'list' });
   const [saving, setSaving] = useState(false);
   const presets = props.settings.subagents.presets;
-  const editorPreset = route.kind === 'edit'
-    ? presets.find((preset) => preset.id === route.presetId) ?? null
-    : null;
-  // An edit route whose preset vanished (deleted in another window, or removed
-  // by an external settings write) is an unsatisfiable route, not a state to
-  // correct: the list is what it renders as. Deriving that beats scheduling a
-  // setState from inside render — and beats the alternative this page shipped
-  // with, where a missing preset silently became a blank create form that
-  // appended a second preset on save.
-  const level: PageRoute['kind'] = route.kind === 'edit' && !editorPreset ? 'list' : route.kind;
+  const { level, preset: editorPreset } = resolveSubagentRoute(route, presets);
   const atLimit = presets.length >= MAX_SUBAGENT_PRESETS;
   const addButtonRef = useRef<HTMLButtonElement>(null);
-  // Which row the user left the list from, so returning puts focus back where
-  // they were rather than at the top of the page.
   const listReturnFocusRef = useRef<string | null>(null);
+  const detailTitleId = useId();
 
-  // Focus follows the level. Without this a level change leaves the ring on
-  // `document.body` — the chevron that had focus just unmounted — and a
-  // keyboard user restarts from the top of the document on every move. The
-  // Dialog this page replaced got the same behaviour for free; a route level
-  // has to say it. Mirrors ProvidersPanel, which owns the same two levels.
-  //
-  // Navigating, not arriving: the page does not grab focus when the settings
-  // surface first renders the list — the user is still in the settings nav
-  // they clicked to get here, and taking the ring off it strands them.
-  const hasNavigatedRef = useRef(false);
+  // The route the user is on has to agree with the level being rendered, or a
+  // preset that reappears under the same id (an undo elsewhere, a re-import)
+  // would re-open an editor the user already left.
   useEffect(() => {
-    if (!hasNavigatedRef.current) {
-      hasNavigatedRef.current = true;
-      return;
-    }
-    const frame = window.requestAnimationFrame(() => {
-      if (level !== 'list') {
-        // The level, not its back button: an IconButton opens its tooltip on
-        // focus, so focusing one on arrival would pop a tooltip at every mouse
-        // user who merely clicked a row. `preventScroll` because this is a
-        // landing — the level just rendered at the top of the content area.
-        document
-          .querySelector<HTMLElement>('[data-maka-contract="subagent-detail"]')
-          ?.focus({ preventScroll: true });
-        return;
-      }
-      // Consumed here and only here. The row the user came from may be gone —
-      // that is exactly what deletion does — so the add button is the
-      // fallback, not the default.
-      const returnToId = listReturnFocusRef.current;
-      listReturnFocusRef.current = null;
-      const row = returnToId
-        ? document.querySelector<HTMLElement>(`[data-subagent-preset="${CSS.escape(returnToId)}"]`)
-        : null;
-      (row ?? addButtonRef.current)?.focus({ preventScroll: true });
-    });
-    return () => window.cancelAnimationFrame(frame);
-  }, [level]);
+    if (level === 'list' && route.kind !== 'list') setRoute({ kind: 'list' });
+  }, [level, route.kind]);
+
+  useSettingsRouteFocus({
+    level,
+    listLevel: 'list',
+    // The level, not its back button: an IconButton opens its tooltip on
+    // focus, so focusing one on arrival would pop a tooltip at every mouse
+    // user who merely clicked a row.
+    focusSelectors: () => ['[data-maka-contract="subagent-detail"]'],
+    listReturnFocusRef,
+    listReturnSelector: (id) => `[data-subagent-preset="${CSS.escape(id)}"]`,
+    listFallbackRef: addButtonRef,
+  });
 
   function openEditor(presetId: string): void {
     listReturnFocusRef.current = presetId;
     setRoute({ kind: 'edit', presetId });
   }
 
-  async function persist(nextPresets: SubagentPreset[]): Promise<boolean> {
+  /**
+   * `expectPresent` is the whole point of reading the result back. Settings
+   * normalization DROPS a preset it dislikes instead of rejecting the write
+   * (`normalizeSubagentSettings`), so a resolved promise is not a saved
+   * preset: a name past the limit, or a 65th preset created while the list
+   * filled up elsewhere, would otherwise report success and return the user
+   * to a list that does not contain what they just saved.
+   */
+  async function persist(
+    nextPresets: SubagentPreset[],
+    expectPresent?: string,
+  ): Promise<boolean> {
     setSaving(true);
     try {
-      await props.onUpdate({ subagents: { presets: nextPresets } });
+      const result = await props.onUpdate({ subagents: { presets: nextPresets } });
+      if (
+        expectPresent !== undefined &&
+        !result.settings.subagents.presets.some((candidate) => candidate.id === expectPresent)
+      ) {
+        toast.error(copy.toast.saveFailed, copy.toast.rejected);
+        return false;
+      }
       return true;
     } catch (error) {
       toast.error(copy.toast.saveFailed, settingsActionErrorMessage(error, locale));
@@ -180,34 +152,31 @@ export function SubagentSettingsPage(props: {
       destructive: true,
     });
     if (!confirmed) return;
-    const removed = await persist(presets.filter((candidate) => candidate.id !== preset.id));
-    if (removed) setRoute({ kind: 'list' });
+    // No `setRoute` on success: the preset is gone, so the edit route is
+    // unsatisfiable and the effect above commits the list for both this path
+    // and a deletion that happened somewhere else.
+    await persist(presets.filter((candidate) => candidate.id !== preset.id));
   }
 
   if (level !== 'list') {
     return (
-      // tabIndex -1 so the level itself can take the focus the effect above
-      // hands it, instead of dropping a keyboard user on document.body. It
-      // draws no ring.
+      // A named region, so a screen reader announces which preset the user
+      // landed in. tabIndex -1 so the level itself can take the focus the
+      // route-focus hook hands it; it draws no ring.
       <VStack
         gap={5}
         tabIndex={-1}
+        role="region"
+        aria-labelledby={detailTitleId}
         className="settingsRouteLevel"
         data-maka-contract="subagent-detail"
       >
         <SettingsRouteHeader
           onBack={() => setRoute({ kind: 'list' })}
           backLabel={copy.editor.backToList}
-          contract="subagent-detail-back"
-          title={editorPreset ? editorPreset.name : copy.editor.createTitle}
+          titleId={detailTitleId}
+          title={editorPreset ? editorPreset.name : copy.section.add}
           subtitle={editorPreset ? copy.editor.editSubtitle : copy.editor.createSubtitle}
-          // Enabled state is a fact about the preset the user just opened, and
-          // the row that carried it is now off screen. The header slot already
-          // exists for exactly this (providers marks its default connection
-          // here), so the editor states it instead of re-asking for it.
-          badge={editorPreset && !editorPreset.enabled
-            ? <Badge variant="neutral" label={copy.status.disabled} />
-            : null}
         />
         <SubagentPresetEditor
           key={editorPreset?.id ?? 'new'}
@@ -221,7 +190,7 @@ export function SubagentSettingsPage(props: {
             const nextPresets = editorPreset
               ? presets.map((candidate) => candidate.id === editorPreset.id ? next : candidate)
               : [...presets, next];
-            if (await persist(nextPresets)) setRoute({ kind: 'list' });
+            if (await persist(nextPresets, next.id)) setRoute({ kind: 'list' });
           }}
         />
       </VStack>
@@ -232,7 +201,7 @@ export function SubagentSettingsPage(props: {
     <SettingsPage>
       <SettingsSection
         title={copy.section.title}
-        description={atLimit ? copy.section.limitNote : copy.section.count(presets.length, MAX_SUBAGENT_PRESETS)}
+        description={copy.section.count(presets.length, MAX_SUBAGENT_PRESETS)}
         action={presets.length > 0 ? (
           <Button
             ref={addButtonRef}
@@ -264,10 +233,12 @@ export function SubagentSettingsPage(props: {
           const availability = subagentPresetAvailability(preset, props.connections);
           // A row states what the preset is for; its route, its id, and its
           // capability boundary are the editor's answer, one level in. Only a
-          // preset that cannot currently be selected carries a badge — a list
-          // where every row says 可用 says nothing.
-          const problem = availability.kind === 'available' ? null : {
-            disabled: copy.status.disabled,
+          // route the main agent cannot take carries a badge — 已停用 would be
+          // the switch beside it said twice, and a list where every row says
+          // 可用 says nothing.
+          const problem = {
+            available: null,
+            disabled: null,
             missing_connection: copy.status.missingConnection,
             connection_disabled: copy.status.connectionDisabled,
             model_disabled: copy.status.modelDisabled,
@@ -307,9 +278,7 @@ export function SubagentSettingsPage(props: {
                     tooltip={copy.row.configure(preset.name)}
                     icon={<ChevronRight size={16} aria-hidden="true" />}
                     isDisabled={saving}
-                    // The focus anchor for the way back. It rides the control
-                    // the page already renders, so the settings kit does not
-                    // need a row-level data escape hatch for one caller.
+                    // The focus anchor for the way back.
                     data-subagent-preset={preset.id}
                     onClick={() => openEditor(preset.id)}
                   />
@@ -361,7 +330,7 @@ function SubagentPresetEditor(props: {
     thinkingLevel: props.preset?.thinkingLevel ?? '',
     enabled: props.preset?.enabled ?? true,
   }));
-  const [idWasEdited, setIdWasEdited] = useState(props.preset !== null);
+  const [idWasEdited, setIdWasEdited] = useState(false);
   const [submitted, setSubmitted] = useState(false);
   const selectedConnection = props.connections.find(
     (connection) => connection.slug === draft.connectionSlug,
@@ -375,15 +344,13 @@ function SubagentPresetEditor(props: {
   const profileCopy = copy.profiles[draft.profile];
   const validId = isSafeSubagentPresetId(draft.id.trim());
   const duplicateId = existingIds.has(draft.id.trim());
-  const validRoute = Boolean(
-    selectedConnection?.enabled && enabledModels.includes(draft.model),
-  );
+  const validConnection = Boolean(selectedConnection?.enabled);
+  const validModel = enabledModels.includes(draft.model);
   const canSave = Boolean(
     draft.name.trim() &&
-    draft.description.trim() &&
-    validId &&
-    !duplicateId &&
-    validRoute,
+    (props.preset !== null || (validId && !duplicateId)) &&
+    validConnection &&
+    validModel,
   );
   const connectionOptions = props.connections.map((connection) => ({
     value: connection.slug,
@@ -412,7 +379,12 @@ function SubagentPresetEditor(props: {
     });
   }
 
-  function updateName(name: string): void {
+  function updateName(value: string): void {
+    // Capped at the one place the name changes, because the store DROPS a
+    // preset whose name is over the limit rather than trimming it — an error
+    // message would arrive after the row had already disappeared, and Astryx's
+    // TextInput has no maxLength to lean on.
+    const name = value.slice(0, SUBAGENT_PRESET_NAME_MAX_CHARS);
     setDraft((current) => nextSubagentDraftForName(current, name, idWasEdited, existingIds));
   }
 
@@ -431,7 +403,10 @@ function SubagentPresetEditor(props: {
     setSubmitted(true);
     if (!canSave) return;
     await props.onSave({
-      id: draft.id.trim(),
+      // An existing preset's id comes from the preset, never from the draft:
+      // session history and the main agent's routing key on it, and the field
+      // is not even rendered in this branch.
+      id: props.preset ? props.preset.id : draft.id.trim(),
       name: draft.name.trim(),
       description: draft.description.trim(),
       profile: draft.profile,
@@ -466,27 +441,28 @@ function SubagentPresetEditor(props: {
           />
         </SettingsField>
         <SettingsField>
+          {/* Optional, because the stored contract makes it optional and the
+              list has a fallback line for exactly that. Requiring it here made
+              a legal preset uneditable until the user wrote prose. */}
           <TextArea
             label={copy.editor.description}
             value={draft.description}
             placeholder={copy.editor.descriptionPlaceholder}
             rows={3}
+            // The counter is Astryx's; the cap is ours, because `maxLength`
+            // only styles the counter and the store truncates silently.
+            maxLength={SUBAGENT_PRESET_DESCRIPTION_MAX_CHARS}
             isDisabled={props.isSaving}
-            status={submitted && !draft.description.trim()
-              ? { type: 'error', message: copy.editor.requiredDescription }
-              : undefined}
-            onChange={(description) => setDraft((current) => ({ ...current, description }))}
+            onChange={(description) => setDraft((current) => ({
+              ...current,
+              description: description.slice(0, SUBAGENT_PRESET_DESCRIPTION_MAX_CHARS),
+            }))}
           />
         </SettingsField>
         {/* An existing id is a settled fact — session history and the main
             agent's routing both reference it — so it reads as a row's value.
             Only a new preset's id is still the user's to type. */}
         {props.preset ? (
-          // `SettingRow mono`, not a hand-rolled <code> in the end slot: the
-          // kit renders machine text as its own full-width line under the
-          // description, because `.settingsReadOnlyValue` without
-          // `data-mono="true"` is body type in a 320px right-anchored box —
-          // and a subagent_id runs to 128 characters.
           <SettingRow
             title={copy.editor.id}
             detail={copy.editor.idDescription}
@@ -550,8 +526,8 @@ function SubagentPresetEditor(props: {
               width="100%"
               isDisabled={props.isSaving || usableConnections.length === 0}
               disabledMessage={usableConnections.length === 0 ? copy.editor.noConnection : undefined}
-              status={submitted && !validRoute
-                ? { type: 'error', message: copy.editor.invalidRoute }
+              status={submitted && !validConnection
+                ? { type: 'error', message: copy.editor.invalidConnection }
                 : usableConnections.length === 0
                   ? { type: 'warning', message: copy.editor.noConnection }
                   : undefined}
@@ -570,6 +546,11 @@ function SubagentPresetEditor(props: {
               width="100%"
               isDisabled={props.isSaving || enabledModels.length === 0}
               disabledMessage={enabledModels.length === 0 ? copy.editor.noModel : undefined}
+              // The route is two choices, so it gets two errors: an enabled
+              // connection with no model selected is the model's problem.
+              status={submitted && validConnection && !validModel
+                ? { type: 'error', message: copy.editor.invalidModel }
+                : undefined}
               onChange={(model) => setDraft((current) => ({ ...current, model, thinkingLevel: '' }))}
             />
           )}
@@ -598,35 +579,25 @@ function SubagentPresetEditor(props: {
             )}
           />
         ) : null}
-        {/* Only on create. An existing preset is switched from its list row —
-            one back-press away, and the header states the current value — but
-            a preset that does not exist yet has no row, so without this the
-            user cannot land one in a disabled state and has to reach for the
-            switch in the window where the main agent can already select it. */}
-        {props.preset ? null : (
-          <SettingsRow
-            label={copy.editor.enabled}
-            description={copy.editor.enabledDescription}
-            align="start"
-            end={(
-              <Switch
-                label={copy.editor.enabled}
-                isLabelHidden
-                value={draft.enabled}
-                isDisabled={props.isSaving}
-                onChange={(enabled) => setDraft((current) => ({ ...current, enabled }))}
-              />
-            )}
-          />
-        )}
+        <SettingsRow
+          label={copy.editor.enabled}
+          description={copy.editor.enabledDescription}
+          align="start"
+          end={(
+            <Switch
+              label={copy.editor.enabled}
+              isLabelHidden
+              value={draft.enabled}
+              isDisabled={props.isSaving}
+              onChange={(enabled) => setDraft((current) => ({ ...current, enabled }))}
+            />
+          )}
+        />
       </SettingsSection>
 
       {/* Save commits the whole preset, not the route group it would sit
           inside, so it stands on its own between the groups and the delete
-          section. A bare `HStack` under the page stack, not a title-less
-          `SettingsSection`: with no header that section renders no header and
-          no divider, so it was two wrappers around the same 32px rhythm the
-          page stack already gives any direct child. */}
+          section. */}
       <HStack gap={2} wrap="wrap">
           <Button
             variant="primary"
diff --git a/apps/desktop/src/renderer/styles/settings.css b/apps/desktop/src/renderer/styles/settings.css
index f70ab0d3e9..b289dbc4e4 100644
--- a/apps/desktop/src/renderer/styles/settings.css
+++ b/apps/desktop/src/renderer/styles/settings.css
@@ -1,6 +1,7 @@
 /* settings.css — entry; rules split into styles/settings/ (issue #253 Round F). */
 @import "./settings/form.css";
 @import "./settings/rows.css";
+@import "./settings/route.css";
 @import "./settings/nav-sidebar.css";
 @import "./settings/about.css";
 @import "./settings/theme-preview.css";
diff --git a/apps/desktop/src/renderer/styles/settings/models.css b/apps/desktop/src/renderer/styles/settings/models.css
index acb1bc82f5..a34f4c2b03 100644
--- a/apps/desktop/src/renderer/styles/settings/models.css
+++ b/apps/desktop/src/renderer/styles/settings/models.css
@@ -2,17 +2,6 @@
    (data-selected → --state-selected-bg), one selected-row implementation
    across the app. */
 
-/* A route level takes focus when it lands, so a keyboard user does not get
-   dropped on document.body every time the panel navigates. It is a landing
-   target, not a control — the ring belongs to whatever they Tab to next.
-   Astryx draws its focus ring with box-shadow, not outline, so both are
-   cleared — an outline-only reset leaves a 2px ring around the whole page. */
-.settingsRouteLevel:focus,
-.settingsRouteLevel:focus-visible {
-  outline: none;
-  box-shadow: none;
-}
-
 .connectionRow[data-disabled="true"] {
   opacity: var(--opacity-muted);
 }
diff --git a/apps/desktop/src/renderer/styles/settings/route.css b/apps/desktop/src/renderer/styles/settings/route.css
new file mode 100644
index 0000000000..efc0700f1b
--- /dev/null
+++ b/apps/desktop/src/renderer/styles/settings/route.css
@@ -0,0 +1,13 @@
+/* Shared by every settings page that owns more than one level (providers,
+   subagents), which is why this is not in a page's own stylesheet.
+
+   A route level takes focus when it lands, so a keyboard user does not get
+   dropped on document.body every time the page navigates. It is a landing
+   target, not a control — the ring belongs to whatever they Tab to next.
+   Astryx draws its focus ring with box-shadow, not outline, so both are
+   cleared — an outline-only reset leaves a 2px ring around the whole page. */
+.settingsRouteLevel:focus,
+.settingsRouteLevel:focus-visible {
+  outline: none;
+  box-shadow: none;
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index a10bbd3c9e..0fe7afaae2 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1562,7 +1562,9 @@ export type {
 export type { SubagentPreset, SubagentProfile, SubagentSettings } from './subagent-settings.js';
 export {
   MAX_SUBAGENT_PRESETS,
+  SUBAGENT_PRESET_DESCRIPTION_MAX_CHARS,
   SUBAGENT_PRESET_ID_MAX_CHARS,
+  SUBAGENT_PRESET_NAME_MAX_CHARS,
   SUBAGENT_PROFILES,
   isSafeSubagentPresetId,
   isSubagentProfile,
diff --git a/packages/core/src/subagent-settings.ts b/packages/core/src/subagent-settings.ts
index 13f582b5d4..5e0fa980cc 100644
--- a/packages/core/src/subagent-settings.ts
+++ b/packages/core/src/subagent-settings.ts
@@ -5,6 +5,12 @@ export type SubagentProfile = (typeof SUBAGENT_PROFILES)[number];
 
 export const MAX_SUBAGENT_PRESETS = 64;
 export const SUBAGENT_PRESET_ID_MAX_CHARS = 128;
+// Normalization DROPS a preset whose name is too long and TRUNCATES a
+// description that is, so any editor writing these fields has to enforce the
+// same numbers — silently losing the preset the user just saved is the
+// alternative. Exported for exactly that.
+export const SUBAGENT_PRESET_NAME_MAX_CHARS = 128;
+export const SUBAGENT_PRESET_DESCRIPTION_MAX_CHARS = 1_000;
 const SAFE_SUBAGENT_PRESET_ID = /^[A-Za-z0-9._:-]+$/;
 
 /** User-approved model route for one catalog subagent capability. */
@@ -56,7 +62,7 @@ export function normalizeSubagentSettings(input: unknown): SubagentSettings {
       !isSubagentProfile(value.profile) ||
       typeof value.name !== 'string' ||
       value.name.trim().length < 1 ||
-      value.name.trim().length > 128 ||
+      value.name.trim().length > SUBAGENT_PRESET_NAME_MAX_CHARS ||
       typeof value.connectionSlug !== 'string' ||
       value.connectionSlug.trim().length < 1 ||
       value.connectionSlug.trim().length > 128 ||
@@ -74,7 +80,9 @@ export function normalizeSubagentSettings(input: unknown): SubagentSettings {
       id,
       name: value.name.trim(),
       description:
-        typeof value.description === 'string' ? value.description.trim().slice(0, 1_000) : '',
+        typeof value.description === 'string'
+          ? value.description.trim().slice(0, SUBAGENT_PRESET_DESCRIPTION_MAX_CHARS)
+          : '',
       profile: value.profile,
       connectionSlug: value.connectionSlug.trim(),
       model: value.model.trim(),

From 19844682c0c20ac8fff428b8835b57a6c502cda8 Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Mon, 3 Aug 2026 21:31:43 +0800
Subject: [PATCH 7/8] docs(desktop): correct what a Storybook play function
 proves
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

FIDELITY.md said a story whose `play` throws "still ships green" and "never
could" fail. It is the opposite: `storybook-visual-smoke.mjs` subscribes to
`playFunctionThrewException` and `unhandledErrorsWhilePlaying` and collects the
console error too, so a throwing play function fails the smoke run and CI —
verified by adding a probe story that throws unconditionally and watching the
run exit 1. The script's own header says the same thing from the other side:
that pass exists BECAUSE a build alone would let such a story through.

What `play` genuinely cannot do is report: with no test addon a failure names
the story, not the assertion, the state, or the expectation — and reaching it
costs a Storybook build. That is the reason to put contracts elsewhere, and it
is what the section now says.

The viewport claim was overstated in the same paragraph: manifest surfaces
declare their own viewports and colour schemes, with a written opt-out for each
one skipped, rather than all rendering at three widths across light and dark.

The subagent editor story's annotation claimed it "exercises" four states it
only renders; the e2e journeys are what pin them.
---
 apps/desktop/stories/FIDELITY.md                       | 10 ++++++----
 .../stories/settings/settings-pages.stories.tsx        |  7 ++++---
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/apps/desktop/stories/FIDELITY.md b/apps/desktop/stories/FIDELITY.md
index 914aa2dd46..222b3d9c1b 100644
--- a/apps/desktop/stories/FIDELITY.md
+++ b/apps/desktop/stories/FIDELITY.md
@@ -25,8 +25,8 @@ A story earns its place by rendering pixels no other story renders. A second lev
 
 Two facts decide it, and both were guessed wrong once:
 
-- **Where a story renders.** `scripts/storybook-visual-smoke.mjs` renders the `product-smoke-manifest.json` surfaces at three viewports across light and dark, and every *other* story exactly once, at 1280 wide in light (`catalogJobs`). A story is not a width matrix; a surface that needs one belongs in the manifest. And `parameters.viewport.defaultViewport` does nothing in Storybook 10, so a story claiming a viewport that way has been rendering at the default width all along.
-- **Whether `play` reaches the state.** `play` does run in the browser, so a story that clicks into a level renders that level, for a reviewer and for the smoke pass. What it does not do is fail the run when its assertions throw (see below) — so use `play` to reach a state, never to prove one.
+- **Where a story renders.** `scripts/storybook-visual-smoke.mjs` renders each `product-smoke-manifest.json` surface at the viewports and colour schemes that surface declares — several are wide-only or light-only, and every skipped viewport carries a written opt-out reason — and every *other* story exactly once, at 1280 wide in light (`catalogJobs`). A story is not a width matrix; a surface that needs one belongs in the manifest, with its reasons. And `parameters.viewport.defaultViewport` does nothing in Storybook 10, so a story claiming a viewport that way has been rendering at the default width all along.
+- **Whether `play` reaches the state.** `play` runs in the browser, so a story that clicks into a level renders that level — for a reviewer and for the smoke pass, which also fails if the click never lands (see below).
 
 Extra stories still cost: a reviewer scanning the sidebar cannot tell which entry is the page, and duplicates re-render the same pixels every run while claiming coverage they do not add. Where a state matters but renders nothing new, pin it somewhere that runs — a `packages/ui` test or an e2e journey.
 
@@ -42,9 +42,11 @@ When a component has two hosts, one frame is not both. `capability-audit-strip.s
 
 If the runtime computes a field, ask the runtime for it. A story that hardcodes what a classifier would have returned is asserting a fact rather than showing one, and nothing fails when the classifier moves.
 
-## Assertions belong where they run
+## A `play` function is a step, not a test report
 
-`play` functions run, but nothing collects what they assert. No test addon is configured, and `scripts/storybook-visual-smoke.mjs` only listens for the failure events a play function would emit — so a story whose `play` throws unconditionally still ships green. #1853 landed a computed line-height assertion in a `play`; it has never failed a run and never could. The interaction still happens, which is why `play` is the right way to *reach* a second level (above) and the wrong way to *check* one. Put behavioural and computed-style contracts in a `packages/ui` test or in the smoke script's `checks`, and keep stories to what they can actually prove: that the surface renders.
+A `play` that throws — including from an assertion — fails the smoke run and CI: `scripts/storybook-visual-smoke.mjs` subscribes to `playFunctionThrewException` and `unhandledErrorsWhilePlaying`, and the throw also surfaces as a console error it collects. What `play` cannot do is *report*: there is no test addon, so a run tells you the story broke, not which assertion, in what state, or against what expectation. It is also the slowest place to put a check, because reaching it means building and serving Storybook.
+
+So put behavioural and computed-style contracts where they can name what they check — a `packages/ui` test, an e2e journey, or the smoke script's `checks` — and use `play` for what it is good at: driving a story into the state it claims to render.
 
 ## A story that renders nothing is not a story
 
diff --git a/apps/desktop/stories/settings/settings-pages.stories.tsx b/apps/desktop/stories/settings/settings-pages.stories.tsx
index 0ca5858d4e..7dc1891369 100644
--- a/apps/desktop/stories/settings/settings-pages.stories.tsx
+++ b/apps/desktop/stories/settings/settings-pages.stories.tsx
@@ -925,9 +925,10 @@ export const Subagents: Story = {
 // Real path: 设置 → 子 Agent → 配置“实现与验证”. A second story because the
 // editor is a route level, not a disclosure: it replaces the list, shares no
 // content with it, and is where this page's pixel work happens. Landed on the
-// implementation preset because it exercises the most of the level at once —
-// the settled read-only subagent_id, the capability warning, the degraded
-// model option, and the delete section.
+// implementation preset because it renders the most of the level at once — the
+// settled read-only subagent_id, the capability warning, the degraded model
+// option, and the delete section. It renders them; what they must be is pinned
+// in the e2e journeys, not here.
 export const SubagentEditor: Story = {
   decorators: [withSubagentSettingsBridge],
   render: () => <SettingsStory section="subagents" />,

From 86b02b56e2c5c82687b679b96a53ceb2855f5340 Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Mon, 3 Aug 2026 22:00:58 +0800
Subject: [PATCH 8/8] refactor(desktop): shrink the shared route-focus hook to
 what actually drifts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Third review round. The hook landed with eight options, three of which the
subagent page degenerated (a `focusSelectors` that ignores its argument, no
`routeKey`, no `isReady`) — and the total came out longer than the duplication
it removed. It now shares only the mechanism that drifts invisibly: skip the
first render, one animation frame, `preventScroll`, cancel on the way out. Which
element a level focuses goes back to the page, because a wrong target puts the
ring somewhere you can see. Its `resolveTarget` is also read through a ref
written in an effect rather than during render.

Deleting the effect that committed the derived route back into state: it was the
same rule as `resolveSubagentRoute` said twice, it contradicted ProvidersPanel —
which answers the identical vanished-target case by deriving alone — and it had
a window where a click landing between commit and effect would be overwritten.

The three claims the diff made that the code did not support:

- Three e2e comments said the editor no longer carries an enable switch for an
  existing preset. It carries one in both branches; that was this PR's own last
  round. The tests are fine, the reasons written on them were not.
- "An IconButton opens its tooltip on focus, so focusing one on arrival would
  pop a tooltip at every mouse user" is false in both files that said it:
  Astryx's `handleFocusIn` returns early unless `:focus-visible` matches, and
  says so in a comment. Focusing the region is still right; the reason is that
  a named region is what gets announced.
- The unit test explained itself with a bug that only existed in this PR's own
  intermediate commit, which no reader after merge can see. It now states the
  present-tense structure: `preset: null` IS the create branch.

Coverage: breaking any of the three providers focus branches left CI green, so
the catalog landing, the detail region landing, and the return-to-row are now
asserted there — each verified to fail when its branch is broken. The create
journey also takes the id over before renaming, which is the half of the
derivation contract the component never exercised.

Also: an existing preset's id is no longer derived at the call site either, not
just ignored at submit; the back affordance is disabled mid-save, where leaving
discarded a draft the failed write could not give back; a thinking level whose
row is off screen is no longer submitted; the id limit is interpolated from
`SUBAGENT_PRESET_ID_MAX_CHARS` instead of spelled out in two locales; name and
description truncate the way the store measures them, after trimming; and the
providers detail is a named region too, since it now shares this header.
---
 apps/desktop/e2e/providers.spec.ts            |  26 +++
 apps/desktop/e2e/settings.spec.ts             |  24 +--
 .../subagent-preset-presentation.test.ts      |   8 +-
 .../locales/settings-subagents-copy.ts        |   6 +-
 .../src/renderer/settings/ProvidersPanel.tsx  |  37 ++--
 .../renderer/settings/settings-route-focus.ts |  71 +++-----
 .../settings/settings-route-header.tsx        |   5 +-
 .../settings/subagent-preset-presentation.ts  |   6 +-
 .../settings/subagent-settings-page.tsx       | 164 ++++++++++--------
 .../src/renderer/styles/settings/route.css    |   5 +-
 10 files changed, 193 insertions(+), 159 deletions(-)

diff --git a/apps/desktop/e2e/providers.spec.ts b/apps/desktop/e2e/providers.spec.ts
index d6371299b9..536d359b25 100644
--- a/apps/desktop/e2e/providers.spec.ts
+++ b/apps/desktop/e2e/providers.spec.ts
@@ -38,6 +38,10 @@ async function openCatalog(page: Page, options: { category: string; search: stri
   await page.getByRole('button', { name: '添加连接', exact: true }).click();
   const catalog = page.locator('[data-maka-contract="provider-catalog"]');
   await expect(catalog).toBeVisible();
+  // The catalog level lands on its search field before anything else is
+  // touched: it is what a user arrives here to do, and the shared route-focus
+  // hook is what puts them there.
+  await expect(catalog.getByPlaceholder('搜索服务商')).toBeFocused();
   await catalog.getByRole('combobox', { name: '分类', exact: true }).click();
   await page.getByRole('option', { name: options.category, exact: true }).click();
   await catalog.getByPlaceholder('搜索服务商').fill(options.search);
@@ -128,11 +132,33 @@ test('adds a catalog provider through the canonical API-key setup page', async (
     // the page that owns every next move — no hunting for the new row.
     await expect(setup).toHaveCount(0);
     await expect(detail).toBeVisible();
+    // The level itself takes focus, not its back button, and it is a region
+    // named by its own heading so the landing is announced.
+    await expect(detail).toBeFocused();
+    await expect(detail).toHaveAttribute('role', 'region');
+    await expect(page.getByRole('region', { name: 'Cerebras' })).toBeVisible();
     const detailMark = detail.locator('.providerLogo[data-provider="cerebras"] img');
     await expect(detailMark).toBeVisible();
     expect(await detailMark.evaluate(colorAssetRenderContract)).toEqual(COLOR_ASSET_RENDER_CONTRACT);
   });
 
+  await test.step('going back lands where the user came from', async () => {
+    await page.getByRole('button', { name: '返回模型连接', exact: true }).click();
+    await expect(detail).toHaveCount(0);
+    // This detail was reached by saving a new provider, not by opening a row,
+    // so there is no row to go back to and the primary action takes the ring.
+    await expect(page.getByRole('button', { name: '添加连接', exact: true })).toBeFocused();
+
+    // Opened from a row, the way back is that row — the ring returns to where
+    // the user left, not to the top of the list.
+    await connection.click();
+    await expect(detail).toBeVisible();
+    await page.getByRole('button', { name: '返回模型连接', exact: true }).click();
+    await expect(connection).toBeFocused();
+    await connection.click();
+    await expect(detail).toBeVisible();
+  });
+
   await test.step('the detail replaces a key and manages enabled and default models', async () => {
     // A settled credential is a row, not a form: it reports its state and
     // carries one control. The input only exists while the user is changing it.
diff --git a/apps/desktop/e2e/settings.spec.ts b/apps/desktop/e2e/settings.spec.ts
index 11972366d9..efff2d268e 100644
--- a/apps/desktop/e2e/settings.spec.ts
+++ b/apps/desktop/e2e/settings.spec.ts
@@ -42,10 +42,10 @@ test('subagent presets can be reviewed and edited in desktop settings', async ({
           profile: 'local_read',
           connectionSlug: connection.slug,
           model: connection.enabledModelIds?.[0] ?? connection.defaultModel,
-          // Seeded DISABLED on purpose: the editor no longer carries an enable
-          // switch for an existing preset, so this run is what proves saving an
-          // unrelated field does not quietly re-enable a preset the user turned
-          // off — the one invariant holding that removal up.
+          // Seeded DISABLED on purpose: the editor's own switch reads from the
+          // preset, so this run is what proves saving an unrelated field makes
+          // the round trip without quietly re-enabling a preset the user
+          // turned off.
           enabled: false,
         }],
       },
@@ -165,25 +165,29 @@ test('a subagent preset can be created disabled and then enabled from its row',
 
   const settings = page.getByRole('main', { name: '设置内容' });
   // The create branch is a structurally different tree from the edit branch —
-  // a typed id instead of a settled one, an enable switch, no delete section —
-  // so it needs its own journey rather than riding on the edit one.
+  // a typed id instead of a settled one, and no delete section — so it needs
+  // its own journey rather than riding on the edit one.
   await settings.getByRole('button', { name: '添加子 Agent' }).click();
   await settings.getByRole('textbox', { name: '显示名称' }).fill('E2E Web Research');
   // The id derives from the name until the user takes it over.
   await expect(settings.getByRole('textbox', { name: 'subagent_id' })).toHaveValue('e2e-web-research');
+  // Taking the id over stops the derivation for good: a later name edit must
+  // not walk over what the user typed.
+  await settings.getByRole('textbox', { name: 'subagent_id' }).fill('web-research-owned');
+  await settings.getByRole('textbox', { name: '显示名称' }).fill('E2E Web Research 2');
+  await expect(settings.getByRole('textbox', { name: 'subagent_id' })).toHaveValue('web-research-owned');
   await settings.getByRole('textbox', { name: '适用场景' }).fill('查找外部资料。');
   await settings.getByRole('switch', { name: '启用', exact: true }).click();
   await settings.getByRole('button', { name: '创建', exact: true }).click();
 
-  await expect(settings.getByText('E2E Web Research', { exact: true })).toBeVisible();
+  await expect(settings.getByText('E2E Web Research 2', { exact: true })).toBeVisible();
   await expect.poll(async () => page.evaluate(async () => {
     const current = await window.maka.settings.get();
     const preset = current.subagents.presets[0];
     return { id: preset?.id, enabled: preset?.enabled };
-  })).toEqual({ id: 'e2e-web-research', enabled: false });
+  })).toEqual({ id: 'web-research-owned', enabled: false });
 
-  // The list row's switch is the only way to enable an existing preset.
-  await settings.getByRole('switch', { name: '启用: E2E Web Research' }).click();
+  await settings.getByRole('switch', { name: '启用: E2E Web Research 2' }).click();
   await expect.poll(async () => page.evaluate(async () => {
     const current = await window.maka.settings.get();
     return current.subagents.presets[0]?.enabled;
diff --git a/apps/desktop/src/main/__tests__/subagent-preset-presentation.test.ts b/apps/desktop/src/main/__tests__/subagent-preset-presentation.test.ts
index 4a7fd7ba97..e1ab4fbef3 100644
--- a/apps/desktop/src/main/__tests__/subagent-preset-presentation.test.ts
+++ b/apps/desktop/src/main/__tests__/subagent-preset-presentation.test.ts
@@ -125,10 +125,10 @@ describe('resolveSubagentRoute', () => {
   });
 
   it('renders the list for an edit route whose preset is gone', () => {
-    // The whole reason this is a function: a preset deleted from under an open
-    // editor used to leave `preset` null while the editor still rendered, which
-    // is its create branch — so saving appended a SECOND preset instead of
-    // updating one. Nothing on screen said so.
+    // The whole reason this is a function: `preset: null` is what the editor
+    // reads as "new", so an edit level that kept rendering with a vanished
+    // preset would be its create branch — and saving appends rather than
+    // updates. Falling back to the list is what keeps those two apart.
     assert.deepEqual(resolveSubagentRoute({ kind: 'edit', presetId: 'gone' }, [fastReader]), {
       level: 'list',
       preset: null,
diff --git a/apps/desktop/src/renderer/locales/settings-subagents-copy.ts b/apps/desktop/src/renderer/locales/settings-subagents-copy.ts
index 1c987d3510..67b45224d5 100644
--- a/apps/desktop/src/renderer/locales/settings-subagents-copy.ts
+++ b/apps/desktop/src/renderer/locales/settings-subagents-copy.ts
@@ -57,7 +57,7 @@ export type SubagentSettingsCopy = {
     noConnection: string;
     noModel: string;
     requiredName: string;
-    invalidId: string;
+    invalidId(max: number): string;
     duplicateId: string;
     invalidConnection: string;
     invalidModel: string;
@@ -128,7 +128,7 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
       noConnection: '请先在“模型”页启用一个模型连接。',
       noModel: '所选连接没有已启用的模型。',
       requiredName: '请输入显示名称。',
-      invalidId: '只能使用字母、数字、点、下划线、冒号和连字符，最多 128 个字符。',
+      invalidId: (max) => `只能使用字母、数字、点、下划线、冒号和连字符，最多 ${max} 个字符。`,
       duplicateId: '这个 subagent_id 已经存在。',
       invalidConnection: '请选择一个已启用的模型连接。',
       invalidModel: '请选择一个已启用的模型。',
@@ -209,7 +209,7 @@ const SETTINGS_SUBAGENTS_COPY_BY_LOCALE = {
       noConnection: 'Enable a model connection on the Models page first.',
       noModel: 'The selected connection has no enabled models.',
       requiredName: 'Enter a display name.',
-      invalidId: 'Use only letters, numbers, dots, underscores, colons, and hyphens, up to 128 characters.',
+      invalidId: (max) => `Use only letters, numbers, dots, underscores, colons, and hyphens, up to ${max} characters.`,
       duplicateId: 'That subagent_id already exists.',
       invalidConnection: 'Select an enabled model connection.',
       invalidModel: 'Select an enabled model.',
diff --git a/apps/desktop/src/renderer/settings/ProvidersPanel.tsx b/apps/desktop/src/renderer/settings/ProvidersPanel.tsx
index 32eb200efd..162b064c0e 100644
--- a/apps/desktop/src/renderer/settings/ProvidersPanel.tsx
+++ b/apps/desktop/src/renderer/settings/ProvidersPanel.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useId, useRef, useState } from 'react';
 import {
   Badge,
   Banner,
@@ -100,6 +100,7 @@ export function ProvidersPanel({ bridge, initialPage = 'connections', initialCon
   // Which row the user left the list from, so returning puts focus back where
   // they were rather than on the page's primary action.
   const listReturnFocusRef = useRef<string | null>(null);
+  const detailTitleId = useId();
   const locale = useUiLocale();
   const providerCopy = getProviderSettingsCopy(locale);
   const copy = providerCopy.panel;
@@ -201,20 +202,27 @@ export function ProvidersPanel({ bridge, initialPage = 'connections', initialCon
 
   useSettingsRouteFocus({
     level,
-    listLevel: 'list',
     routeKey: route,
     isReady: !loading,
-    focusSelectors: (current) => current === 'detail'
-      // The region, not its back button: an IconButton opens its tooltip on
-      // focus, so focusing one on arrival would pop a tooltip at every mouse
-      // user who merely clicked a row.
-      ? ['[data-maka-contract="connection-detail"]']
-      : current === 'catalog'
-        ? ['[data-maka-contract="provider-catalog"] input']
-        : ['[data-maka-contract="provider-setup"] input', '[data-maka-contract="provider-setup"]'],
-    listReturnFocusRef,
-    listReturnSelector: (slug) => `[data-connection-slug="${slug}"] button`,
-    listFallbackRef: addButtonRef,
+    resolveTarget: (current) => {
+      const find = (selector: string) => document.querySelector<HTMLElement>(selector);
+      if (current === 'catalog') return find('[data-maka-contract="provider-catalog"] input');
+      if (current === 'setup') {
+        return find('[data-maka-contract="provider-setup"] input')
+          ?? find('[data-maka-contract="provider-setup"]');
+      }
+      // The region rather than its back button, so a screen reader announces
+      // the level the user landed in instead of the way out of it.
+      if (current === 'detail') return find('[data-maka-contract="connection-detail"]');
+      // Consumed here and only here: the ref is set on the way down and has to
+      // survive the levels in between. The row the user came from may be gone —
+      // that is exactly what a deletion does — so the primary action is the
+      // fallback, not the default.
+      const returnToSlug = listReturnFocusRef.current;
+      listReturnFocusRef.current = null;
+      return (returnToSlug ? find(`[data-connection-slug="${returnToSlug}"] button`) : null)
+        ?? addButtonRef.current;
+    },
   });
 
   if (loading) {
@@ -237,11 +245,12 @@ export function ProvidersPanel({ bridge, initialPage = 'connections', initialCon
         // tabIndex -1 so a route change can land focus on the level itself —
         // the standard SPA answer to "where does focus go when the page
         // swaps", and it draws no ring.
-        <VStack gap={5} tabIndex={-1} className="settingsRouteLevel" data-maka-contract="connection-detail">
+        <VStack gap={5} tabIndex={-1} role="region" aria-labelledby={detailTitleId} className="settingsRouteLevel" data-maka-contract="connection-detail">
           <SettingsRouteHeader
             onBack={goToList}
             backLabel={copy.backToList}
             logo={<ProviderLogo type={selected.providerType} compact />}
+            titleId={detailTitleId}
             title={selected.name}
             badge={selected.slug === defaultSlug ? <Badge variant="neutral" label={copy.default} /> : null}
             subtitle={connectionSubtitle(selected, locale)}
diff --git a/apps/desktop/src/renderer/settings/settings-route-focus.ts b/apps/desktop/src/renderer/settings/settings-route-focus.ts
index 1e7471354b..b5a84541e1 100644
--- a/apps/desktop/src/renderer/settings/settings-route-focus.ts
+++ b/apps/desktop/src/renderer/settings/settings-route-focus.ts
@@ -2,38 +2,35 @@
 //
 // Without this a level change leaves the ring on `document.body` — the control
 // that had focus just unmounted — and a keyboard user restarts from the top of
-// the document on every move. A Dialog gets this for free; a route level has
-// to say it, and both settings pages that own levels said it separately until
-// this file existed. A focus rule is the one duplication that cannot be seen
-// on screen when the two copies drift.
-import { useEffect, useRef, type RefObject } from 'react';
+// the document on every move.
+//
+// Only the mechanism is shared, because only the mechanism drifts invisibly:
+// skipping the first render, the animation frame, `preventScroll`, cancelling
+// on the way out. Which element each level focuses stays with the page — a
+// wrong target puts the ring somewhere you can see.
+import { useEffect, useRef } from 'react';
 
-export type SettingsRouteFocusOptions = {
-  /** The level being rendered. `listLevel` is the one the user returns to. */
+export function useSettingsRouteFocus(options: {
+  /** The level being rendered. A change here is what moves focus. */
   level: string;
-  listLevel: string;
   /**
-   * Anything that should re-run the focus move without changing `level` —
-   * a second detail opened directly from a first, say. Compared by identity.
+   * Anything that should re-run the move without changing `level`. Compared by
+   * identity, and only needed by a page whose level is not the whole route.
    */
   routeKey?: unknown;
   /** False while the page has nothing to focus yet (loading its data). */
   isReady?: boolean;
-  /** Focus targets for a non-list level, in preference order. */
-  focusSelectors(level: string): readonly string[];
-  /** Which row the user left the list from; consumed on the way back. */
-  listReturnFocusRef: RefObject<string | null>;
-  listReturnSelector(token: string): string;
-  /** Where focus lands when the row is gone — deletion is exactly that. */
-  listFallbackRef: RefObject<HTMLElement | null>;
-};
-
-export function useSettingsRouteFocus(options: SettingsRouteFocusOptions): void {
-  // Read through a ref so callers can pass fresh closures every render without
-  // the effect re-running: the level (and `routeKey`) is what decides a move.
-  const latest = useRef(options);
-  latest.current = options;
+  /** Where focus goes for the level being rendered; null to leave it alone. */
+  resolveTarget(level: string): HTMLElement | null;
+}): void {
   const { level, routeKey, isReady = true } = options;
+  // `resolveTarget` closes over fresh state every render but must not re-run
+  // the effect, so it is read through a ref written in its own effect —
+  // committed values only, which a ref written during render would not be.
+  const resolveTargetRef = useRef(options.resolveTarget);
+  useEffect(() => {
+    resolveTargetRef.current = options.resolveTarget;
+  });
 
   // Navigating, not arriving: the page does not grab focus when the settings
   // surface first renders it — the user is still on the settings nav item they
@@ -46,28 +43,10 @@ export function useSettingsRouteFocus(options: SettingsRouteFocusOptions): void
       return;
     }
     const frame = window.requestAnimationFrame(() => {
-      const current = latest.current;
-      // `preventScroll` throughout because this is a landing, not a jump: the
-      // level just rendered at the top of the content area, and scrolling to
-      // whatever the focus target happens to be would push its header away.
-      if (level !== current.listLevel) {
-        for (const selector of current.focusSelectors(level)) {
-          const element = document.querySelector<HTMLElement>(selector);
-          if (element) {
-            element.focus({ preventScroll: true });
-            return;
-          }
-        }
-        return;
-      }
-      // Consumed here and only here: the ref is set on the way down and has to
-      // survive the levels in between.
-      const returnTo = current.listReturnFocusRef.current;
-      current.listReturnFocusRef.current = null;
-      const row = returnTo
-        ? document.querySelector<HTMLElement>(current.listReturnSelector(returnTo))
-        : null;
-      (row ?? current.listFallbackRef.current)?.focus({ preventScroll: true });
+      // `preventScroll` because this is a landing, not a jump: the level just
+      // rendered at the top of the content area, and scrolling to whatever the
+      // target happens to be would push its own header out of view.
+      resolveTargetRef.current(level)?.focus({ preventScroll: true });
     });
     return () => window.cancelAnimationFrame(frame);
   }, [level, routeKey, isReady]);
diff --git a/apps/desktop/src/renderer/settings/settings-route-header.tsx b/apps/desktop/src/renderer/settings/settings-route-header.tsx
index 2f265b2bd3..89a41ccde6 100644
--- a/apps/desktop/src/renderer/settings/settings-route-header.tsx
+++ b/apps/desktop/src/renderer/settings/settings-route-header.tsx
@@ -1,8 +1,6 @@
 // The header of a settings sub-level: back affordance, title, and one quiet
 // line of context.
 //
-// A settings page that owns more than one level needs exactly one way back.
-//
 // Deliberately a `Toolbar` with everything in `startContent`: the back button,
 // the optional logo, and the title block read as one left-aligned cluster, so
 // the title sits where the list's rows started and the eye does not travel.
@@ -16,6 +14,8 @@ import { ArrowLeft } from '@maka/ui/icons';
 export function SettingsRouteHeader(props: {
   onBack(): void;
   backLabel: string;
+  /** True while a write is in flight: leaving would discard the draft. */
+  isBackDisabled?: boolean;
   logo?: ReactNode;
   title: string;
   /** Wire the level's `aria-labelledby` to this heading, so it is announced. */
@@ -34,6 +34,7 @@ export function SettingsRouteHeader(props: {
             label={props.backLabel}
             tooltip={props.backLabel}
             icon={<ArrowLeft size={16} aria-hidden="true" />}
+            isDisabled={props.isBackDisabled}
             onClick={props.onBack}
           />
           {props.logo}
diff --git a/apps/desktop/src/renderer/settings/subagent-preset-presentation.ts b/apps/desktop/src/renderer/settings/subagent-preset-presentation.ts
index 95ceee4ba4..31f44c912e 100644
--- a/apps/desktop/src/renderer/settings/subagent-preset-presentation.ts
+++ b/apps/desktop/src/renderer/settings/subagent-preset-presentation.ts
@@ -18,9 +18,9 @@ export type SubagentPageRoute =
 /**
  * An edit route whose preset vanished (deleted, or removed by an external
  * settings write) is an unsatisfiable route, not a state to correct: the list
- * is what it renders as. Resolving it here rather than in the component keeps
- * the rule testable — inlined, the only way to reach it was to delete a preset
- * from under an open editor, and nothing did.
+ * is what it renders as. It lives here rather than inside the component
+ * because the only way to reach it there is to delete a preset from under an
+ * open editor — a state a unit test can hand it directly.
  */
 export function resolveSubagentRoute(
   route: SubagentPageRoute,
diff --git a/apps/desktop/src/renderer/settings/subagent-settings-page.tsx b/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
index 0e9173e24b..ad78de57d4 100644
--- a/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
+++ b/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
@@ -4,23 +4,21 @@
 //
 //   list ── editor(new | existing)
 //
-// A modal exists to interrupt the current task for something short and
-// immediately decidable; naming a capability, writing the guidance the main
-// agent selects on, and picking a connection/model/thinking route is none of
-// those. The providers panel next door already answers this same list→detail
-// shape with a route level, so this page follows it rather than inventing a
-// second answer — including its focus controller, which is shared.
+// The providers panel next door answers the same list→detail shape, so this
+// page follows it rather than inventing a second answer — down to the shared
+// focus controller and route header.
 //
-// Every element here is a settings-kit part (`SettingsSection`, `SettingsRow`,
-// `SettingsField`, `SettingsActions`) or an Astryx primitive. The page owns no
-// CSS of its own; `.settingsRouteLevel` is the shared route-level focus reset.
-import { useEffect, useId, useMemo, useRef, useState } from 'react';
+// The page owns no CSS of its own: layout comes from the settings kit and the
+// controls from `@maka/ui`, and `.settingsRouteLevel` is the route-level focus
+// reset it shares with the providers panel.
+import { useId, useMemo, useRef, useState } from 'react';
 import { Banner, HStack, VStack } from '@astryxdesign/core';
 import {
   connectionEnabledModelIds,
   isSafeSubagentPresetId,
   MAX_SUBAGENT_PRESETS,
   SUBAGENT_PRESET_DESCRIPTION_MAX_CHARS,
+  SUBAGENT_PRESET_ID_MAX_CHARS,
   SUBAGENT_PRESET_NAME_MAX_CHARS,
   thinkingVariantsForModel,
   type AppSettings,
@@ -64,6 +62,11 @@ import {
 } from './subagent-preset-presentation.js';
 import { statusBadgeVariant } from './settings-status-badge.js';
 
+/** How many characters a value spends on leading whitespace the store trims. */
+function leadingSpace(value: string): number {
+  return value.length - value.trimStart().length;
+}
+
 /** The preset as the form holds it: `thinkingLevel` gains the Selector's ''. */
 type SubagentEditorDraft = Omit<SubagentPreset, 'thinkingLevel'> & {
   thinkingLevel: ThinkingLevel | '';
@@ -88,23 +91,23 @@ export function SubagentSettingsPage(props: {
   const listReturnFocusRef = useRef<string | null>(null);
   const detailTitleId = useId();
 
-  // The route the user is on has to agree with the level being rendered, or a
-  // preset that reappears under the same id (an undo elsewhere, a re-import)
-  // would re-open an editor the user already left.
-  useEffect(() => {
-    if (level === 'list' && route.kind !== 'list') setRoute({ kind: 'list' });
-  }, [level, route.kind]);
-
   useSettingsRouteFocus({
     level,
-    listLevel: 'list',
-    // The level, not its back button: an IconButton opens its tooltip on
-    // focus, so focusing one on arrival would pop a tooltip at every mouse
-    // user who merely clicked a row.
-    focusSelectors: () => ['[data-maka-contract="subagent-detail"]'],
-    listReturnFocusRef,
-    listReturnSelector: (id) => `[data-subagent-preset="${CSS.escape(id)}"]`,
-    listFallbackRef: addButtonRef,
+    resolveTarget: (current) => {
+      // The region rather than its back button, so a screen reader announces
+      // the preset the user landed in instead of the way out of it.
+      if (current !== 'list') {
+        return document.querySelector<HTMLElement>('[data-maka-contract="subagent-detail"]');
+      }
+      // Consumed here and only here: the ref is set on the way down. The row
+      // may be gone — that is exactly what a deletion does — so the add button
+      // is the fallback, not the default.
+      const returnToId = listReturnFocusRef.current;
+      listReturnFocusRef.current = null;
+      return (returnToId
+        ? document.querySelector<HTMLElement>(`[data-subagent-preset="${returnToId}"]`)
+        : null) ?? addButtonRef.current;
+    },
   });
 
   function openEditor(presetId: string): void {
@@ -112,13 +115,19 @@ export function SubagentSettingsPage(props: {
     setRoute({ kind: 'edit', presetId });
   }
 
+  function openCreate(): void {
+    // Nothing to return to: the create level was not opened from a row.
+    listReturnFocusRef.current = null;
+    setRoute({ kind: 'create' });
+  }
+
   /**
-   * `expectPresent` is the whole point of reading the result back. Settings
-   * normalization DROPS a preset it dislikes instead of rejecting the write
-   * (`normalizeSubagentSettings`), so a resolved promise is not a saved
-   * preset: a name past the limit, or a 65th preset created while the list
-   * filled up elsewhere, would otherwise report success and return the user
-   * to a list that does not contain what they just saved.
+   * Settings normalization DROPS a preset it dislikes instead of rejecting the
+   * write, so a resolved promise is not a saved preset. The fields the user
+   * can get wrong are held inside their limits before they are submitted;
+   * `expectPresent` is the backstop for the rest — a count that filled up
+   * elsewhere, a rule this page has not heard about — because the alternative
+   * failure is silent, and returns the user to a list missing what they saved.
    */
   async function persist(
     nextPresets: SubagentPreset[],
@@ -152,9 +161,9 @@ export function SubagentSettingsPage(props: {
       destructive: true,
     });
     if (!confirmed) return;
-    // No `setRoute` on success: the preset is gone, so the edit route is
-    // unsatisfiable and the effect above commits the list for both this path
-    // and a deletion that happened somewhere else.
+    // No `setRoute`: with the preset gone the edit route is unsatisfiable, so
+    // `resolveSubagentRoute` renders the list for this path and for a deletion
+    // that happened somewhere else alike.
     await persist(presets.filter((candidate) => candidate.id !== preset.id));
   }
 
@@ -174,6 +183,8 @@ export function SubagentSettingsPage(props: {
         <SettingsRouteHeader
           onBack={() => setRoute({ kind: 'list' })}
           backLabel={copy.editor.backToList}
+          // Leaving mid-save discards a draft the failed write cannot give back.
+          isBackDisabled={saving}
           titleId={detailTitleId}
           title={editorPreset ? editorPreset.name : copy.section.add}
           subtitle={editorPreset ? copy.editor.editSubtitle : copy.editor.createSubtitle}
@@ -209,13 +220,12 @@ export function SubagentSettingsPage(props: {
             size="sm"
             label={copy.section.add}
             isDisabled={saving || atLimit}
-            onClick={() => setRoute({ kind: 'create' })}
+            onClick={openCreate}
           />
         ) : undefined}
       >
         {presets.length === 0 ? (
-          // The empty state owns the only call to action here; a section
-          // action beside it would be the same button twice on one screen.
+          // The empty state owns the only call to action on an empty page.
           <EmptyState
             title={copy.section.emptyTitle}
             description={copy.section.emptyDescription}
@@ -225,17 +235,15 @@ export function SubagentSettingsPage(props: {
                 variant="primary"
                 label={copy.section.add}
                 isDisabled={saving}
-                onClick={() => setRoute({ kind: 'create' })}
+                onClick={openCreate}
               />
             )}
           />
         ) : presets.map((preset) => {
           const availability = subagentPresetAvailability(preset, props.connections);
-          // A row states what the preset is for; its route, its id, and its
-          // capability boundary are the editor's answer, one level in. Only a
-          // route the main agent cannot take carries a badge — 已停用 would be
-          // the switch beside it said twice, and a list where every row says
-          // 可用 says nothing.
+          // Only a route the main agent cannot take earns a badge: 已停用 is
+          // the switch beside it said twice, and a row that says 可用 says
+          // nothing a list of approved presets does not already say.
           const problem = {
             available: null,
             disabled: null,
@@ -319,8 +327,7 @@ function SubagentPresetEditor(props: {
     : [];
   const [draft, setDraft] = useState<SubagentEditorDraft>(() => ({
     // Empty, not a pre-derived `subagent`: an id the user has not been asked
-    // for yet reads as a value the page already decided. Typing the name fills
-    // it (until the user takes it over), and the placeholder says what it is.
+    // for yet reads as a value the page already decided.
     id: props.preset?.id ?? '',
     name: props.preset?.name ?? '',
     description: props.preset?.description ?? '',
@@ -383,8 +390,15 @@ function SubagentPresetEditor(props: {
     // Capped at the one place the name changes, because the store DROPS a
     // preset whose name is over the limit rather than trimming it — an error
     // message would arrive after the row had already disappeared, and Astryx's
-    // TextInput has no maxLength to lean on.
-    const name = value.slice(0, SUBAGENT_PRESET_NAME_MAX_CHARS);
+    // TextInput has no maxLength to lean on. Measured the way the store
+    // measures it, after trimming, so leading spaces cost no real characters.
+    const name = value.slice(0, SUBAGENT_PRESET_NAME_MAX_CHARS + leadingSpace(value));
+    // An existing preset's id is settled: it is not rendered in this branch and
+    // it is not derived here either, so the two cannot disagree.
+    if (props.preset) {
+      setDraft((current) => ({ ...current, name }));
+      return;
+    }
     setDraft((current) => nextSubagentDraftForName(current, name, idWasEdited, existingIds));
   }
 
@@ -412,13 +426,17 @@ function SubagentPresetEditor(props: {
       profile: draft.profile,
       connectionSlug: draft.connectionSlug,
       model: draft.model,
-      ...(draft.thinkingLevel ? { thinkingLevel: draft.thinkingLevel } : {}),
+      // Only if the row is on screen: a level left over from a previous model
+      // is not a choice the user can still see, let alone change.
+      ...(draft.thinkingLevel && thinkingLevels.includes(draft.thinkingLevel)
+        ? { thinkingLevel: draft.thinkingLevel }
+        : {}),
       enabled: draft.enabled,
     });
   }
 
   const idStatus = submitted && !validId
-    ? { type: 'error' as const, message: copy.editor.invalidId }
+    ? { type: 'error' as const, message: copy.editor.invalidId(SUBAGENT_PRESET_ID_MAX_CHARS) }
     : submitted && duplicateId
       ? { type: 'error' as const, message: copy.editor.duplicateId }
       : undefined;
@@ -441,9 +459,8 @@ function SubagentPresetEditor(props: {
           />
         </SettingsField>
         <SettingsField>
-          {/* Optional, because the stored contract makes it optional and the
-              list has a fallback line for exactly that. Requiring it here made
-              a legal preset uneditable until the user wrote prose. */}
+          {/* Optional, because the stored contract is: the list carries a
+              fallback line for a preset that has no guidance yet. */}
           <TextArea
             label={copy.editor.description}
             value={draft.description}
@@ -455,7 +472,10 @@ function SubagentPresetEditor(props: {
             isDisabled={props.isSaving}
             onChange={(description) => setDraft((current) => ({
               ...current,
-              description: description.slice(0, SUBAGENT_PRESET_DESCRIPTION_MAX_CHARS),
+              description: description.slice(
+                0,
+                SUBAGENT_PRESET_DESCRIPTION_MAX_CHARS + leadingSpace(description),
+              ),
             }))}
           />
         </SettingsField>
@@ -595,30 +615,28 @@ function SubagentPresetEditor(props: {
         />
       </SettingsSection>
 
-      {/* Save commits the whole preset, not the route group it would sit
-          inside, so it stands on its own between the groups and the delete
-          section. */}
+      {/* Save commits the whole preset, not the group above it. */}
       <HStack gap={2} wrap="wrap">
-          <Button
-            variant="primary"
-            label={props.isSaving
-              ? copy.editor.saving
-              : props.preset
-                ? copy.editor.save
-                : copy.editor.create}
-            isDisabled={props.isSaving}
-            onClick={() => void submit()}
-          />
-          <Button
-            variant="ghost"
-            label={copy.editor.cancel}
-            isDisabled={props.isSaving}
-            onClick={props.onCancel}
-          />
+        <Button
+          variant="primary"
+          label={props.isSaving
+            ? copy.editor.saving
+            : props.preset
+              ? copy.editor.save
+              : copy.editor.create}
+          isDisabled={props.isSaving}
+          onClick={() => void submit()}
+        />
+        <Button
+          variant="ghost"
+          label={copy.editor.cancel}
+          isDisabled={props.isSaving}
+          onClick={props.onCancel}
+        />
       </HStack>
 
       {/* Deletion is last and stands alone, so a mis-aimed cursor has nothing
-          quiet to hit beside it — the providers detail answers it the same way. */}
+          quiet to hit beside it. */}
       {props.onDelete ? (
         <SettingsSection title={copy.editor.dangerZone} description={copy.editor.dangerZoneHelp}>
           <SettingsActions>
diff --git a/apps/desktop/src/renderer/styles/settings/route.css b/apps/desktop/src/renderer/styles/settings/route.css
index efc0700f1b..65cbe6c93c 100644
--- a/apps/desktop/src/renderer/styles/settings/route.css
+++ b/apps/desktop/src/renderer/styles/settings/route.css
@@ -1,7 +1,4 @@
-/* Shared by every settings page that owns more than one level (providers,
-   subagents), which is why this is not in a page's own stylesheet.
-
-   A route level takes focus when it lands, so a keyboard user does not get
+/* A route level takes focus when it lands, so a keyboard user does not get
    dropped on document.body every time the page navigates. It is a landing
    target, not a control — the ring belongs to whatever they Tab to next.
    Astryx draws its focus ring with box-shadow, not outline, so both are