From c9789c21485c3c72e5a8315779201bf1e6b7a6bf Mon Sep 17 00:00:00 2001
From: Luke The Dev <252071647+iamlukethedev@users.noreply.github.com>
Date: Mon, 23 Mar 2026 18:04:37 -0500
Subject: [PATCH] Add office agent management wizard (#56)

* Add agents

* Agent

* Added agents management

* Polish agent wizard and release blockers.

Finalize the office agent management flow by aligning the gateway fallback behavior, cleaning up UI semantics, and updating tests so the branch is ready to ship.

Made-with: Cursor

---------

Co-authored-by: iamlukethedev <iamlukethedev@users.noreply.github.com>
Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>
---
 server/studio-settings.js                     |  14 +-
 src/app/api/gateway/agent-state/route.ts      |   4 +-
 src/app/api/gateway/media/route.ts            |   4 +-
 src/app/api/gateway/skills/remove/route.ts    |   4 +-
 .../components/AgentAvatarEditorPanel.tsx     |  96 ++-
 .../components/AgentAvatarPreview3D.tsx       |  12 +-
 .../agents/components/AgentChatPanel.tsx      |  10 +-
 .../components/AgentCreateWizardModal.tsx     | 566 ++++++++++++++++++
 .../agents/components/AgentEditorModal.tsx    |  68 ++-
 .../agents/components/AgentIdentityFields.tsx |  76 +++
 .../components/inspect/AgentBrainPanel.tsx    |  60 +-
 .../agents/operations/agentFleetHydration.ts  |  14 +-
 .../agents/operations/deleteAgentOperation.ts |  41 +-
 .../useAgentSettingsMutationController.ts     |  12 +-
 .../agents/screens/AgentsPageScreen.tsx       |   7 +-
 src/features/agents/state/store.tsx           |  13 +
 src/features/office/components/HQSidebar.tsx  |  11 +
 .../office/hooks/useOfficeSkillTriggers.ts    |  18 +-
 .../hooks/useOfficeSkillsMarketplace.ts       |   2 +-
 src/features/office/screens/OfficeScreen.tsx  | 496 ++++++++++++++-
 src/features/retro-office/RetroOffice3D.tsx   |  36 +-
 src/lib/agents/personalityBuilder.ts          |   4 +-
 src/lib/gateway/GatewayClient.ts              |   1 +
 src/lib/gateway/local-gateway.ts              |  22 +
 src/lib/skills/tempAgents.ts                  |  27 +
 tests/unit/agentBrainPanel.test.ts            |  28 +-
 tests/unit/agentSettingsPanel.test.ts         |   2 +-
 tests/unit/gatewayConnectRetryPolicy.test.ts  |   5 +-
 tests/unit/onboardingState.test.ts            |   2 +-
 tests/unit/settingsRouteWorkflow.test.ts      |   4 +-
 ...useAgentSettingsMutationController.test.ts |  24 +-
 tests/unit/useSettingsRouteController.test.ts |   2 +-
 32 files changed, 1504 insertions(+), 181 deletions(-)
 create mode 100644 src/features/agents/components/AgentCreateWizardModal.tsx
 create mode 100644 src/features/agents/components/AgentIdentityFields.tsx
 create mode 100644 src/lib/skills/tempAgents.ts

diff --git a/server/studio-settings.js b/server/studio-settings.js
index a36ca0c..5e81dea 100644
--- a/server/studio-settings.js
+++ b/server/studio-settings.js
@@ -58,21 +58,9 @@ const readJsonFile = (filePath) => {
 
 const DEFAULT_GATEWAY_URL = "ws://localhost:18789";
 const OPENCLAW_CONFIG_FILENAME = "openclaw.json";
-const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
 
 const isRecord = (value) => Boolean(value && typeof value === "object");
 
-const isLocalGatewayUrl = (value) => {
-  const trimmed = typeof value === "string" ? value.trim() : "";
-  if (!trimmed) return false;
-  try {
-    const parsed = new URL(trimmed);
-    return LOOPBACK_HOSTNAMES.has(parsed.hostname.toLowerCase());
-  } catch {
-    return false;
-  }
-};
-
 const readOpenclawGatewayDefaults = (env = process.env) => {
   try {
     const stateDir = resolveStateDir(env);
@@ -100,7 +88,7 @@ const loadUpstreamGatewaySettings = (env = process.env) => {
   const gateway = parsed && typeof parsed === "object" ? parsed.gateway : null;
   const url = typeof gateway?.url === "string" ? gateway.url.trim() : "";
   const token = typeof gateway?.token === "string" ? gateway.token.trim() : "";
-  if (!token && (!url || isLocalGatewayUrl(url))) {
+  if (!token) {
     const defaults = readOpenclawGatewayDefaults(env);
     if (defaults) {
       return {
diff --git a/src/app/api/gateway/agent-state/route.ts b/src/app/api/gateway/agent-state/route.ts
index d57d514..94c77af 100644
--- a/src/app/api/gateway/agent-state/route.ts
+++ b/src/app/api/gateway/agent-state/route.ts
@@ -1,7 +1,7 @@
 import { NextResponse } from "next/server";
 
 import { restoreAgentStateLocally, trashAgentStateLocally } from "@/lib/agent-state/local";
-import { isLocalGatewayUrl } from "@/lib/gateway/local-gateway";
+import { isLikelyLocalGatewayUrl } from "@/lib/gateway/local-gateway";
 import {
   resolveConfiguredSshTarget,
   resolveGatewaySshTargetFromGatewayUrl,
@@ -30,7 +30,7 @@ const resolveAgentStateSshTarget = (): string | null => {
   if (configured) return configured;
   const settings = loadStudioSettings();
   const gatewayUrl = settings.gateway?.url ?? "";
-  if (isLocalGatewayUrl(gatewayUrl)) return null;
+  if (isLikelyLocalGatewayUrl(gatewayUrl)) return null;
   return resolveGatewaySshTargetFromGatewayUrl(gatewayUrl, process.env);
 };
 
diff --git a/src/app/api/gateway/media/route.ts b/src/app/api/gateway/media/route.ts
index bd48e1c..39ee95a 100644
--- a/src/app/api/gateway/media/route.ts
+++ b/src/app/api/gateway/media/route.ts
@@ -1,6 +1,6 @@
 import { NextResponse } from "next/server";
 
-import { isLocalGatewayUrl } from "@/lib/gateway/local-gateway";
+import { isLikelyLocalGatewayUrl } from "@/lib/gateway/local-gateway";
 import {
   resolveConfiguredSshTarget,
   resolveGatewaySshTargetFromGatewayUrl,
@@ -151,7 +151,7 @@ PY
 const resolveSshTarget = (): string | null => {
   const settings = loadStudioSettings();
   const gatewayUrl = settings.gateway?.url ?? "";
-  if (isLocalGatewayUrl(gatewayUrl)) return null;
+  if (isLikelyLocalGatewayUrl(gatewayUrl)) return null;
   const configured = resolveConfiguredSshTarget(process.env);
   if (configured) return configured;
   return resolveGatewaySshTargetFromGatewayUrl(gatewayUrl, process.env);
diff --git a/src/app/api/gateway/skills/remove/route.ts b/src/app/api/gateway/skills/remove/route.ts
index 0fe047c..bcdd4dc 100644
--- a/src/app/api/gateway/skills/remove/route.ts
+++ b/src/app/api/gateway/skills/remove/route.ts
@@ -1,6 +1,6 @@
 import { NextResponse } from "next/server";
 
-import { isLocalGatewayUrl } from "@/lib/gateway/local-gateway";
+import { isLikelyLocalGatewayUrl } from "@/lib/gateway/local-gateway";
 import { removeSkillLocally } from "@/lib/skills/remove-local";
 import type { RemovableSkillSource, SkillRemoveRequest } from "@/lib/skills/types";
 import {
@@ -33,7 +33,7 @@ const resolveSkillRemovalSshTarget = (): string | null => {
   if (configured) return configured;
   const settings = loadStudioSettings();
   const gatewayUrl = settings.gateway?.url ?? "";
-  if (isLocalGatewayUrl(gatewayUrl)) return null;
+  if (isLikelyLocalGatewayUrl(gatewayUrl)) return null;
   return resolveGatewaySshTargetFromGatewayUrl(gatewayUrl, process.env);
 };
 
diff --git a/src/features/agents/components/AgentAvatarEditorPanel.tsx b/src/features/agents/components/AgentAvatarEditorPanel.tsx
index f75d491..f1f0230 100644
--- a/src/features/agents/components/AgentAvatarEditorPanel.tsx
+++ b/src/features/agents/components/AgentAvatarEditorPanel.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useMemo, useState } from "react";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useState } from "react";
 import { RefreshCcw, Shuffle } from "lucide-react";
 import {
   AGENT_AVATAR_BOTTOM_STYLE_OPTIONS,
@@ -22,8 +22,16 @@ export type AgentAvatarEditorPanelProps = {
   agentName: string;
   initialProfile: AgentAvatarProfile | null | undefined;
   onSave: (profile: AgentAvatarProfile) => Promise<void> | void;
+  onDraftChange?: (profile: AgentAvatarProfile) => void;
   onCancel?: () => void;
   onSaved?: () => void;
+  cancelLabel?: string;
+  saveLabel?: string;
+  showActions?: boolean;
+};
+
+export type AgentAvatarEditorPanelHandle = {
+  save: () => Promise<void>;
 };
 
 const pillClassName =
@@ -32,14 +40,24 @@ const pillClassName =
 const colorSwatchClassName =
   "h-7 w-7 rounded-full border-2 transition-transform hover:scale-105";
 
-export const AgentAvatarEditorPanel = ({
-  agentId,
-  agentName,
-  initialProfile,
-  onSave,
-  onCancel,
-  onSaved,
-}: AgentAvatarEditorPanelProps) => {
+export const AgentAvatarEditorPanel = forwardRef<
+  AgentAvatarEditorPanelHandle,
+  AgentAvatarEditorPanelProps
+>(function AgentAvatarEditorPanel(
+  {
+    agentId,
+    agentName,
+    initialProfile,
+    onSave,
+    onDraftChange,
+    onCancel,
+    onSaved,
+    cancelLabel = "Cancel",
+    saveLabel = "Save avatar",
+    showActions = true,
+  }: AgentAvatarEditorPanelProps,
+  ref
+) {
   const fallbackProfile = useMemo(
     () => createDefaultAgentAvatarProfile(agentId),
     [agentId]
@@ -52,7 +70,11 @@ export const AgentAvatarEditorPanel = ({
     setDraft(resolvedInitialProfile);
   }, [resolvedInitialProfile]);
 
-  const save = async () => {
+  useEffect(() => {
+    onDraftChange?.(draft);
+  }, [draft, onDraftChange]);
+
+  const save = useCallback(async () => {
     if (saving) return;
     setSaving(true);
     try {
@@ -61,7 +83,15 @@ export const AgentAvatarEditorPanel = ({
     } finally {
       setSaving(false);
     }
-  };
+  }, [draft, onSave, onSaved, saving]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      save,
+    }),
+    [save]
+  );
 
   return (
     <div className="grid h-full min-h-0 gap-0 xl:grid-cols-[360px_minmax(0,1fr)]">
@@ -99,26 +129,28 @@ export const AgentAvatarEditorPanel = ({
       </div>
 
       <div className="min-h-0 overflow-y-auto p-5">
-        <div className="mb-6 flex items-center justify-end gap-2 border-b border-border/40 pb-4">
-          <button
-            type="button"
-            className="ui-btn-ghost px-3 py-2 text-xs"
-            onClick={onCancel}
-            disabled={saving}
-          >
-            Cancel
-          </button>
-          <button
-            type="button"
-            className="ui-btn-primary px-3 py-2 text-xs"
-            onClick={() => {
-              void save();
-            }}
-            disabled={saving}
-          >
-            {saving ? "Saving..." : "Save avatar"}
-          </button>
-        </div>
+        {showActions ? (
+          <div className="mb-6 flex items-center justify-end gap-2 border-b border-border/40 pb-4">
+            <button
+              type="button"
+              className="ui-btn-ghost px-3 py-2 text-xs"
+              onClick={onCancel}
+              disabled={saving}
+            >
+              {cancelLabel}
+            </button>
+            <button
+              type="button"
+              className="ui-btn-primary px-3 py-2 text-xs"
+              onClick={() => {
+                void save();
+              }}
+              disabled={saving}
+            >
+              {saving ? "Saving..." : saveLabel}
+            </button>
+          </div>
+        ) : null}
         <div className="grid gap-6 xl:grid-cols-2">
           <section className="space-y-3">
             <h3 className="font-mono text-[11px] font-semibold tracking-[0.06em] text-muted-foreground">
@@ -420,4 +452,4 @@ export const AgentAvatarEditorPanel = ({
       </div>
     </div>
   );
-};
+});
diff --git a/src/features/agents/components/AgentAvatarPreview3D.tsx b/src/features/agents/components/AgentAvatarPreview3D.tsx
index 70727d7..d575302 100644
--- a/src/features/agents/components/AgentAvatarPreview3D.tsx
+++ b/src/features/agents/components/AgentAvatarPreview3D.tsx
@@ -305,11 +305,9 @@ export const AgentAvatarPreview3D = ({
     () => profile ?? createDefaultAgentAvatarProfile("preview"),
     [profile]
   );
-  const [isReady, setIsReady] = useState(false);
-
-  useEffect(() => {
-    setIsReady(false);
-  }, [resolvedProfile]);
+  const profileKey = useMemo(() => JSON.stringify(resolvedProfile), [resolvedProfile]);
+  const [readyProfileKey, setReadyProfileKey] = useState<string | null>(null);
+  const isReady = readyProfileKey === profileKey;
 
   return (
     <div className={`relative ${className}`}>
@@ -321,7 +319,7 @@ export const AgentAvatarPreview3D = ({
           </div>
         </div>
       ) : null}
-      <Canvas camera={{ position: [0, 0.7, 2.5], fov: 34 }}>
+      <Canvas key={profileKey} camera={{ position: [0, 0.7, 2.5], fov: 34 }}>
         <color attach="background" args={["#070b16"]} />
         <ambientLight intensity={1.4} />
         <directionalLight position={[3, 4, 5]} intensity={2.4} />
@@ -329,7 +327,7 @@ export const AgentAvatarPreview3D = ({
         <PreviewFigure
           profile={resolvedProfile}
           onFirstFrame={() => {
-            setIsReady(true);
+            setReadyProfileKey(profileKey);
           }}
         />
         <Environment preset="city" />
diff --git a/src/features/agents/components/AgentChatPanel.tsx b/src/features/agents/components/AgentChatPanel.tsx
index 7a60afe..e280e35 100644
--- a/src/features/agents/components/AgentChatPanel.tsx
+++ b/src/features/agents/components/AgentChatPanel.tsx
@@ -1100,8 +1100,8 @@ const AgentChatComposer = memo(function AgentChatComposer({
           <div
             className={`mb-2 rounded-md border px-2.5 py-1.5 font-mono text-[10px] tracking-[0.02em] ${
               voiceError
-                ? "border-red-500/30 bg-red-500/10 text-red-200"
-                : "border-amber-700/35 bg-amber-500/8 text-amber-200"
+                ? "ui-badge-status-error"
+                : "ui-badge-status-approval"
             }`}
             data-testid="agent-voice-status"
           >
@@ -1122,7 +1122,7 @@ const AgentChatComposer = memo(function AgentChatComposer({
             <button
               className={`rounded-md border px-2.5 py-2 font-mono text-[11px] font-medium tracking-[0.02em] transition ${
                 voiceRecording
-                  ? "border-red-500/60 bg-red-500/12 text-red-200 hover:bg-red-500/18"
+                  ? "ui-btn-danger"
                   : "border-border/70 bg-surface-3 text-white hover:bg-surface-2 hover:text-white"
               } disabled:cursor-not-allowed disabled:border-border/30 disabled:bg-muted/20 disabled:text-muted-foreground`}
               type="button"
@@ -1152,7 +1152,7 @@ const AgentChatComposer = memo(function AgentChatComposer({
             </span>
           ) : null}
           <button
-            className="rounded border border-amber-700/50 bg-[#0e0a04]/90 px-3 py-2 font-mono text-[12px] font-medium tracking-wider text-amber-500/80 shadow-lg backdrop-blur transition-colors hover:border-amber-600/70 hover:text-amber-400 disabled:cursor-not-allowed disabled:border-border/30 disabled:bg-muted/20 disabled:text-amber-900/50"
+            className="rounded border border-[color:var(--status-approval-border)] bg-[#0e0a04]/90 px-3 py-2 font-mono text-[12px] font-medium tracking-wider text-[color:var(--status-approval-fg)] shadow-lg backdrop-blur transition-colors hover:border-[color:var(--status-approval-border)] hover:text-[color:var(--status-approval-fg)] disabled:cursor-not-allowed disabled:border-border/30 disabled:bg-muted/20 disabled:text-muted-foreground"
             type="button"
             onClick={onSend}
             disabled={sendDisabled}
@@ -1562,7 +1562,7 @@ export const AgentChatPanel = ({
 
           <div className="mt-0.5 flex items-center gap-2">
             <button
-              className="nodrag inline-flex items-center whitespace-nowrap rounded border border-amber-800/40 bg-amber-900/20 px-2 py-0.5 font-mono text-[9px] font-medium tracking-[0.02em] text-amber-400/80 transition hover:bg-amber-900/30 hover:text-amber-300 disabled:cursor-not-allowed disabled:opacity-40"
+              className="nodrag inline-flex items-center whitespace-nowrap rounded border border-[color:var(--status-approval-border)] bg-[color:var(--status-approval-bg)] px-2 py-0.5 font-mono text-[9px] font-medium tracking-[0.02em] text-[color:var(--status-approval-fg)] transition hover:bg-[color:var(--status-approval-bg)] hover:text-[color:var(--status-approval-fg)] disabled:cursor-not-allowed disabled:opacity-40"
               type="button"
               data-testid="agent-new-session-toggle"
               aria-label="Start new session"
diff --git a/src/features/agents/components/AgentCreateWizardModal.tsx b/src/features/agents/components/AgentCreateWizardModal.tsx
new file mode 100644
index 0000000..01883f9
--- /dev/null
+++ b/src/features/agents/components/AgentCreateWizardModal.tsx
@@ -0,0 +1,566 @@
+"use client";
+
+import { useMemo, useState } from "react";
+
+import {
+  AgentIdentityFields,
+  type AgentIdentityValues,
+} from "@/features/agents/components/AgentIdentityFields";
+import { AgentAvatarEditorPanel } from "@/features/agents/components/AgentAvatarEditorPanel";
+import {
+  AGENT_FILE_META,
+  AGENT_FILE_PLACEHOLDERS,
+} from "@/lib/agents/agentFiles";
+import {
+  createEmptyPersonalityDraft,
+  type PersonalityBuilderDraft,
+} from "@/lib/agents/personalityBuilder";
+import {
+  createDefaultAgentAvatarProfile,
+  type AgentAvatarProfile,
+} from "@/lib/avatars/profile";
+import { randomUUID } from "@/lib/uuid";
+
+type AgentCreateWizardModalProps = {
+  open: boolean;
+  suggestedName?: string;
+  busy?: boolean;
+  submitError?: string | null;
+  statusLine?: string | null;
+  onClose: (createdAgentId: string | null) => void;
+  onCreateAgent: (identity: AgentIdentityValues) => Promise<string | null>;
+  onFinishWizard: (params: {
+    agentId: string;
+    draft: PersonalityBuilderDraft;
+    profile: AgentAvatarProfile;
+  }) => Promise<void>;
+};
+
+const stepClassName =
+  "rounded-full border px-3 py-1 font-mono text-[10px] uppercase tracking-[0.16em]";
+
+const inputClassName =
+  "h-10 rounded-md border border-border/80 bg-background px-3 text-sm text-foreground outline-none";
+
+const textAreaClassName =
+  "min-h-[180px] w-full resize-y rounded-md border border-border/80 bg-background px-4 py-3 text-sm leading-6 text-foreground outline-none";
+
+type WizardStepId =
+  | "identity"
+  | "avatar"
+  | "SOUL.md"
+  | "AGENTS.md"
+  | "USER.md"
+  | "TOOLS.md"
+  | "MEMORY.md"
+  | "HEARTBEAT.md";
+
+const wizardSteps: Array<{ id: WizardStepId; label: string; hint: string }> = [
+  {
+    id: "identity",
+    label: "Identity",
+    hint: "Create the live agent first, then fill in the rest step by step.",
+  },
+  {
+    id: "avatar",
+    label: "Avatar",
+    hint: "Customize the office appearance before writing the rest of the profile.",
+  },
+  {
+    id: "SOUL.md",
+    label: "Soul",
+    hint: AGENT_FILE_META["SOUL.md"].hint,
+  },
+  {
+    id: "AGENTS.md",
+    label: "Agents",
+    hint: AGENT_FILE_META["AGENTS.md"].hint,
+  },
+  {
+    id: "USER.md",
+    label: "User",
+    hint: AGENT_FILE_META["USER.md"].hint,
+  },
+  {
+    id: "TOOLS.md",
+    label: "Tools",
+    hint: AGENT_FILE_META["TOOLS.md"].hint,
+  },
+  {
+    id: "MEMORY.md",
+    label: "Memory",
+    hint: AGENT_FILE_META["MEMORY.md"].hint,
+  },
+  {
+    id: "HEARTBEAT.md",
+    label: "Heartbeat",
+    hint: AGENT_FILE_META["HEARTBEAT.md"].hint,
+  },
+];
+
+const buildInitialDraft = (suggestedName: string): PersonalityBuilderDraft => {
+  const draft = createEmptyPersonalityDraft();
+  draft.identity.name = suggestedName.trim() || "New Agent";
+  return draft;
+};
+
+const WizardField = ({
+  label,
+  value,
+  placeholder,
+  disabled,
+  onChange,
+}: {
+  label: string;
+  value: string;
+  placeholder?: string;
+  disabled?: boolean;
+  onChange: (value: string) => void;
+}) => (
+  <label className="flex flex-col gap-2 text-xs text-muted-foreground">
+    {label}
+    <input
+      className={inputClassName}
+      value={value}
+      placeholder={placeholder}
+      disabled={disabled}
+      onChange={(event) => {
+        onChange(event.target.value);
+      }}
+    />
+  </label>
+);
+
+const WizardTextAreaField = ({
+  label,
+  value,
+  placeholder,
+  disabled,
+  rows = 6,
+  onChange,
+}: {
+  label: string;
+  value: string;
+  placeholder?: string;
+  disabled?: boolean;
+  rows?: number;
+  onChange: (value: string) => void;
+}) => (
+  <label className="flex flex-col gap-2 text-xs text-muted-foreground">
+    {label}
+    <textarea
+      className={textAreaClassName}
+      value={value}
+      placeholder={placeholder}
+      rows={rows}
+      disabled={disabled}
+      onChange={(event) => {
+        onChange(event.target.value);
+      }}
+    />
+  </label>
+);
+
+export function AgentCreateWizardModal({
+  open,
+  suggestedName = "",
+  busy = false,
+  submitError = null,
+  statusLine = null,
+  onClose,
+  onCreateAgent,
+  onFinishWizard,
+}: AgentCreateWizardModalProps) {
+  const [step, setStep] = useState<WizardStepId>("identity");
+  const [draft, setDraft] = useState<PersonalityBuilderDraft>(() =>
+    buildInitialDraft(suggestedName),
+  );
+  const [createdAgentId, setCreatedAgentId] = useState<string | null>(null);
+  const [draftAvatarProfile, setDraftAvatarProfile] = useState<AgentAvatarProfile>(() =>
+    createDefaultAgentAvatarProfile(randomUUID()),
+  );
+  const [finishing, setFinishing] = useState(false);
+
+  const canCreate = useMemo(() => draft.identity.name.trim().length > 0, [draft.identity.name]);
+  const activeStepIndex = wizardSteps.findIndex((entry) => entry.id === step);
+  const activeStep = wizardSteps[activeStepIndex] ?? wizardSteps[0];
+  const isWorking = busy || finishing;
+  const isFinalStep = step === "HEARTBEAT.md";
+  const statusCopy = finishing ? "Saving the agent files and avatar." : statusLine;
+
+  const updateDraft = <K extends keyof PersonalityBuilderDraft>(
+    key: K,
+    value: PersonalityBuilderDraft[K],
+  ) => {
+    setDraft((current) => ({
+      ...current,
+      [key]: value,
+    }));
+  };
+
+  const advanceStep = async () => {
+    if (step === "identity") {
+      if (!canCreate || isWorking) return;
+      if (!createdAgentId) {
+        const agentId = await onCreateAgent({
+          name: draft.identity.name,
+          creature: draft.identity.creature,
+          vibe: draft.identity.vibe,
+          emoji: draft.identity.emoji,
+        });
+        if (!agentId) return;
+        setCreatedAgentId(agentId);
+      }
+      setStep("avatar");
+      return;
+    }
+    if (isFinalStep) {
+      if (!createdAgentId || isWorking) return;
+      setFinishing(true);
+      try {
+        await onFinishWizard({
+          agentId: createdAgentId,
+          draft,
+          profile: draftAvatarProfile,
+        });
+      } finally {
+        setFinishing(false);
+      }
+      return;
+    }
+    const nextStep = wizardSteps[activeStepIndex + 1];
+    if (nextStep) {
+      setStep(nextStep.id);
+    }
+  };
+
+  const stepActionLabel =
+    step === "identity" && !createdAgentId
+      ? busy
+        ? "Creating..."
+        : "Create and continue"
+      : isFinalStep
+        ? isWorking
+          ? "Saving..."
+          : "Finish wizard"
+        : "Next";
+
+  if (!open) return null;
+
+  return (
+    <div
+      className="fixed inset-0 z-[140] flex items-center justify-center bg-background/84 p-4"
+      role="dialog"
+      aria-modal="true"
+      aria-label="Create agent wizard"
+      onClick={() => {
+        if (!isWorking) {
+          onClose(createdAgentId);
+        }
+      }}
+    >
+      <div
+        className="ui-panel flex h-[min(92vh,980px)] w-full max-w-6xl flex-col overflow-hidden shadow-xs"
+        onClick={(event) => event.stopPropagation()}
+      >
+        <div className="border-b border-border/40 px-6 py-5">
+          <div className="flex items-start justify-between gap-4">
+            <div>
+              <div className="font-mono text-[11px] font-semibold tracking-[0.06em] text-muted-foreground">
+                New agent wizard
+              </div>
+              <div className="mt-1 text-lg font-semibold text-foreground">
+                Create an agent step by step
+              </div>
+              <div className="mt-1 text-sm text-muted-foreground">
+                Start with identity, then build the rest of the profile before finishing.
+              </div>
+            </div>
+            <div className="flex items-center gap-2">
+              <button
+                type="button"
+                className="ui-btn-ghost px-3 py-1.5 text-xs disabled:cursor-not-allowed disabled:opacity-60"
+                disabled={isWorking}
+                onClick={() => {
+                  onClose(createdAgentId);
+                }}
+              >
+                Close
+              </button>
+              {activeStepIndex > 0 ? (
+                <button
+                  type="button"
+                  className="ui-btn-ghost px-3 py-1.5 text-xs disabled:cursor-not-allowed disabled:opacity-60"
+                  disabled={isWorking}
+                  onClick={() => {
+                    const previousStep = wizardSteps[activeStepIndex - 1];
+                    if (previousStep) {
+                      setStep(previousStep.id);
+                    }
+                  }}
+                >
+                  Back
+                </button>
+              ) : null}
+              <button
+                type="button"
+                className="ui-btn-primary px-3 py-1.5 text-xs disabled:cursor-not-allowed disabled:opacity-60"
+                disabled={(step === "identity" && !canCreate) || isWorking}
+                onClick={() => {
+                  void advanceStep();
+                }}
+              >
+                {stepActionLabel}
+              </button>
+            </div>
+          </div>
+          <div className="mt-4 flex flex-wrap gap-2">
+            {wizardSteps.map((wizardStep, index) => {
+              const complete = index < activeStepIndex;
+              const active = wizardStep.id === step;
+              return (
+                <span
+                  key={wizardStep.id}
+                  className={`${stepClassName} ${
+                    active
+                      ? "border-primary/40 bg-primary/10 text-foreground"
+                      : complete
+                        ? "border-emerald-400/35 bg-emerald-500/10 text-foreground"
+                        : "border-border/45 bg-background/40 text-muted-foreground"
+                  }`}
+                >
+                  {index + 1}. {wizardStep.label}
+                </span>
+              );
+            })}
+          </div>
+          <div className="mt-4 text-sm text-muted-foreground">{activeStep.hint}</div>
+          {statusCopy ? (
+            <div className="mt-4 rounded-md border border-border/45 bg-muted/20 px-3 py-2 text-xs text-muted-foreground">
+              {statusCopy}
+            </div>
+          ) : null}
+          {submitError ? (
+            <div className="ui-alert-danger mt-4 rounded-md px-3 py-2 text-xs">
+              {submitError}
+            </div>
+          ) : null}
+        </div>
+
+        {step === "identity" ? (
+          <div className="flex min-h-0 flex-1 flex-col overflow-y-auto px-6 py-6">
+            <div className="mx-auto flex w-full max-w-3xl flex-1 flex-col">
+              <section className="space-y-3">
+                <h3 className="text-sm font-medium text-foreground">Identity</h3>
+                <div className="text-xs text-muted-foreground">
+                  Confirm the live agent name first, then fill in the rest of `IDENTITY.md`.
+                </div>
+                <AgentIdentityFields
+                  values={draft.identity}
+                  disabled={isWorking}
+                  onChange={(field, value) => {
+                    updateDraft("identity", {
+                      ...draft.identity,
+                      [field]: value,
+                    });
+                  }}
+                />
+              </section>
+
+              <div className="mt-6 rounded-xl border border-border/45 bg-muted/20 p-4 text-sm text-muted-foreground">
+                Creating the agent in this step makes it available in OpenClaw immediately so the
+                wizard can save the full profile through the gateway in later steps.
+              </div>
+            </div>
+          </div>
+        ) : createdAgentId ? (
+          <>
+            {step === "avatar" ? (
+              <AgentAvatarEditorPanel
+                agentId={createdAgentId}
+                agentName={draft.identity.name.trim() || "New Agent"}
+                initialProfile={draftAvatarProfile}
+                showActions={false}
+                onDraftChange={(profile) => {
+                  setDraftAvatarProfile(profile);
+                }}
+                onSave={async (profile) => {
+                  setDraftAvatarProfile(profile);
+                }}
+              />
+            ) : step === "SOUL.md" ? (
+              <div className="flex min-h-0 flex-1 flex-col overflow-y-auto px-6 py-6">
+                <div className="mx-auto flex w-full max-w-4xl flex-1 flex-col gap-6 pb-8">
+                  <section className="space-y-3">
+                    <h3 className="text-sm font-medium text-foreground">Soul</h3>
+                    <div className="grid gap-4">
+                      <WizardTextAreaField
+                        label="Core truths"
+                        value={draft.soul.coreTruths}
+                        placeholder="e.g. Protect the user's time. Prefer clarity over theatrics."
+                        disabled={isWorking}
+                        rows={5}
+                        onChange={(value) => {
+                          updateDraft("soul", { ...draft.soul, coreTruths: value });
+                        }}
+                      />
+                      <WizardTextAreaField
+                        label="Boundaries"
+                        value={draft.soul.boundaries}
+                        placeholder="e.g. Do not bluff. Say when something is uncertain."
+                        disabled={isWorking}
+                        rows={5}
+                        onChange={(value) => {
+                          updateDraft("soul", { ...draft.soul, boundaries: value });
+                        }}
+                      />
+                      <WizardTextAreaField
+                        label="Vibe"
+                        value={draft.soul.vibe}
+                        placeholder="e.g. Friendly, direct, and lightly playful."
+                        disabled={isWorking}
+                        rows={4}
+                        onChange={(value) => {
+                          updateDraft("soul", { ...draft.soul, vibe: value });
+                        }}
+                      />
+                      <WizardTextAreaField
+                        label="Continuity"
+                        value={draft.soul.continuity}
+                        placeholder="e.g. Keep naming, preferences, and previous decisions consistent."
+                        disabled={isWorking}
+                        rows={4}
+                        onChange={(value) => {
+                          updateDraft("soul", { ...draft.soul, continuity: value });
+                        }}
+                      />
+                    </div>
+                  </section>
+                </div>
+              </div>
+            ) : step === "USER.md" ? (
+              <div className="flex min-h-0 flex-1 flex-col overflow-y-auto px-6 py-6">
+                <div className="mx-auto flex w-full max-w-4xl flex-1 flex-col gap-6 pb-8">
+                  <section className="space-y-3">
+                    <h3 className="text-sm font-medium text-foreground">User</h3>
+                    <div className="grid gap-4 sm:grid-cols-2">
+                      <WizardField
+                        label="Name"
+                        value={draft.user.name}
+                        placeholder="e.g. Luke"
+                        disabled={isWorking}
+                        onChange={(value) => {
+                          updateDraft("user", { ...draft.user, name: value });
+                        }}
+                      />
+                      <WizardField
+                        label="What to call them"
+                        value={draft.user.callThem}
+                        placeholder="e.g. Luke"
+                        disabled={isWorking}
+                        onChange={(value) => {
+                          updateDraft("user", { ...draft.user, callThem: value });
+                        }}
+                      />
+                      <WizardField
+                        label="Pronouns"
+                        value={draft.user.pronouns}
+                        placeholder="e.g. he/him"
+                        disabled={isWorking}
+                        onChange={(value) => {
+                          updateDraft("user", { ...draft.user, pronouns: value });
+                        }}
+                      />
+                      <WizardField
+                        label="Timezone"
+                        value={draft.user.timezone}
+                        placeholder="e.g. America/Chicago"
+                        disabled={isWorking}
+                        onChange={(value) => {
+                          updateDraft("user", { ...draft.user, timezone: value });
+                        }}
+                      />
+                      <div className="sm:col-span-2">
+                        <WizardField
+                          label="Notes"
+                          value={draft.user.notes}
+                          placeholder="e.g. Prefers concise answers and fast iteration."
+                          disabled={isWorking}
+                          onChange={(value) => {
+                            updateDraft("user", { ...draft.user, notes: value });
+                          }}
+                        />
+                      </div>
+                      <div className="sm:col-span-2">
+                        <WizardTextAreaField
+                          label="Context"
+                          value={draft.user.context}
+                          placeholder="e.g. Building Claw3D, likes practical UI improvements, and wants direct feedback."
+                          disabled={isWorking}
+                          rows={7}
+                          onChange={(value) => {
+                            updateDraft("user", { ...draft.user, context: value });
+                          }}
+                        />
+                      </div>
+                    </div>
+                  </section>
+                </div>
+              </div>
+            ) : (
+              <div className="flex min-h-0 flex-1 flex-col overflow-y-auto px-6 py-6">
+                <div className="mx-auto flex w-full max-w-4xl flex-1 flex-col gap-6 pb-8">
+                  <section className="space-y-3">
+                    <h3 className="text-sm font-medium text-foreground">{activeStep.label}</h3>
+                    <div className="text-xs text-muted-foreground">{activeStep.hint}</div>
+                    <textarea
+                      className={`${textAreaClassName} min-h-[56vh] font-mono`}
+                      value={
+                        step === "AGENTS.md"
+                          ? draft.agents
+                          : step === "TOOLS.md"
+                            ? draft.tools
+                            : step === "MEMORY.md"
+                              ? draft.memory
+                              : step === "HEARTBEAT.md"
+                                ? draft.heartbeat
+                                : ""
+                      }
+                      placeholder={
+                        AGENT_FILE_PLACEHOLDERS[
+                          step as Extract<
+                            WizardStepId,
+                            "AGENTS.md" | "TOOLS.md" | "MEMORY.md" | "HEARTBEAT.md"
+                          >
+                        ]
+                      }
+                      disabled={isWorking}
+                      onChange={(event) => {
+                        const nextValue = event.target.value;
+                        if (step === "AGENTS.md") {
+                          updateDraft("agents", nextValue);
+                          return;
+                        }
+                        if (step === "TOOLS.md") {
+                          updateDraft("tools", nextValue);
+                          return;
+                        }
+                        if (step === "MEMORY.md") {
+                          updateDraft("memory", nextValue);
+                          return;
+                        }
+                        if (step === "HEARTBEAT.md") {
+                          updateDraft("heartbeat", nextValue);
+                        }
+                      }}
+                    />
+                  </section>
+                </div>
+              </div>
+            )}
+          </>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/src/features/agents/components/AgentEditorModal.tsx b/src/features/agents/components/AgentEditorModal.tsx
index 7a5fad6..e8fae1d 100644
--- a/src/features/agents/components/AgentEditorModal.tsx
+++ b/src/features/agents/components/AgentEditorModal.tsx
@@ -1,13 +1,16 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useState } from "react";
 import {
   Brain,
+  ChevronLeft,
+  ChevronRight,
   Database,
   FileText,
   HeartPulse,
   Palette,
   Shield,
+  Trash2,
   UserRound,
   Wrench,
   X,
@@ -32,6 +35,8 @@ type AgentEditorModalProps = {
   onClose: () => void;
   onAvatarSave: (agentId: string, profile: AgentAvatarProfile) => Promise<void> | void;
   onRename?: (agentId: string, name: string) => Promise<boolean>;
+  onDelete?: (agentId: string) => Promise<void> | void;
+  onNavigateAgent?: (agentId: string, section: AgentEditorSection) => void;
 };
 
 const menuButtonClassName =
@@ -102,13 +107,17 @@ export const AgentEditorModal = ({
   onClose,
   onAvatarSave,
   onRename,
+  onDelete,
+  onNavigateAgent,
 }: AgentEditorModalProps) => {
   const [activeSection, setActiveSection] = useState<AgentEditorSection>(initialSection);
-
-  useEffect(() => {
-    if (!open) return;
-    setActiveSection(initialSection);
-  }, [initialSection, open, agent.agentId]);
+  const activeAgentIndex = agents.findIndex((entry) => entry.agentId === agent.agentId);
+  const previousAgent =
+    activeAgentIndex > 0 ? agents[activeAgentIndex - 1] : null;
+  const nextAgent =
+    activeAgentIndex >= 0 && activeAgentIndex < agents.length - 1
+      ? agents[activeAgentIndex + 1]
+      : null;
 
   if (!open) return null;
 
@@ -144,6 +153,34 @@ export const AgentEditorModal = ({
               <div className="mt-1 text-xs text-muted-foreground">
                 Edit avatar and agent brain settings from the office.
               </div>
+              {onNavigateAgent ? (
+                <div className="mt-4 flex items-center gap-2">
+                  <button
+                    type="button"
+                    onClick={() => {
+                      if (!previousAgent) return;
+                      onNavigateAgent(previousAgent.agentId, activeSection);
+                    }}
+                    disabled={!previousAgent}
+                    className="inline-flex items-center gap-1 rounded-md border border-border/50 bg-background/40 px-2.5 py-1.5 text-xs text-foreground transition-colors hover:border-border hover:bg-background/70 disabled:cursor-not-allowed disabled:opacity-40"
+                  >
+                    <ChevronLeft className="h-3.5 w-3.5" />
+                    <span>Previous</span>
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => {
+                      if (!nextAgent) return;
+                      onNavigateAgent(nextAgent.agentId, activeSection);
+                    }}
+                    disabled={!nextAgent}
+                    className="inline-flex items-center gap-1 rounded-md border border-border/50 bg-background/40 px-2.5 py-1.5 text-xs text-foreground transition-colors hover:border-border hover:bg-background/70 disabled:cursor-not-allowed disabled:opacity-40"
+                  >
+                    <span>Next</span>
+                    <ChevronRight className="h-3.5 w-3.5" />
+                  </button>
+                </div>
+              ) : null}
             </div>
 
             <div className="flex-1 space-y-2 overflow-y-auto p-3">
@@ -169,6 +206,25 @@ export const AgentEditorModal = ({
                 );
               })}
             </div>
+            {onDelete ? (
+              <div className="border-t border-border/40 p-3">
+                <button
+                  type="button"
+                  onClick={() => {
+                    void onDelete(agent.agentId);
+                  }}
+                  className="flex w-full items-center gap-3 rounded-xl border border-red-500/40 bg-red-950/55 px-3 py-3 text-left text-red-100 transition-colors hover:border-red-300/65 hover:bg-red-900/75 hover:text-white"
+                >
+                  <Trash2 className="h-4 w-4" />
+                  <div>
+                    <div className="text-sm font-semibold text-inherit">Delete Agent</div>
+                    <div className="text-xs text-red-100/85">
+                      Remove this agent from Claw3D and OpenClaw.
+                    </div>
+                  </div>
+                </button>
+              </div>
+            ) : null}
           </aside>
 
           <section className="flex min-w-0 flex-1 flex-col">
diff --git a/src/features/agents/components/AgentIdentityFields.tsx b/src/features/agents/components/AgentIdentityFields.tsx
new file mode 100644
index 0000000..4a58ce9
--- /dev/null
+++ b/src/features/agents/components/AgentIdentityFields.tsx
@@ -0,0 +1,76 @@
+"use client";
+
+export type AgentIdentityValues = {
+  name: string;
+  creature: string;
+  vibe: string;
+  emoji: string;
+};
+
+type AgentIdentityFieldsProps = {
+  values: AgentIdentityValues;
+  disabled?: boolean;
+  onChange: (field: keyof AgentIdentityValues, value: string) => void;
+};
+
+const inputClassName =
+  "h-10 rounded-md border border-border/80 bg-background px-3 text-sm text-foreground outline-none";
+
+export function AgentIdentityFields({
+  values,
+  disabled = false,
+  onChange,
+}: AgentIdentityFieldsProps) {
+  return (
+    <div className="grid gap-4 sm:grid-cols-2">
+      <label className="flex flex-col gap-2 text-xs text-muted-foreground">
+        Name
+        <input
+          className={inputClassName}
+          value={values.name}
+          placeholder="e.g. Luke"
+          disabled={disabled}
+          onChange={(event) => {
+            onChange("name", event.target.value);
+          }}
+        />
+      </label>
+      <label className="flex flex-col gap-2 text-xs text-muted-foreground">
+        Role
+        <input
+          className={inputClassName}
+          value={values.creature}
+          placeholder="e.g. Product Designer"
+          disabled={disabled}
+          onChange={(event) => {
+            onChange("creature", event.target.value);
+          }}
+        />
+      </label>
+      <label className="flex flex-col gap-2 text-xs text-muted-foreground">
+        Vibe
+        <input
+          className={inputClassName}
+          value={values.vibe}
+          placeholder="e.g. Calm, sharp, and helpful"
+          disabled={disabled}
+          onChange={(event) => {
+            onChange("vibe", event.target.value);
+          }}
+        />
+      </label>
+      <label className="flex flex-col gap-2 text-xs text-muted-foreground">
+        Emoji
+        <input
+          className={inputClassName}
+          value={values.emoji}
+          placeholder="e.g. ✨"
+          disabled={disabled}
+          onChange={(event) => {
+            onChange("emoji", event.target.value);
+          }}
+        />
+      </label>
+    </div>
+  );
+}
diff --git a/src/features/agents/components/inspect/AgentBrainPanel.tsx b/src/features/agents/components/inspect/AgentBrainPanel.tsx
index 37fe387..fa1e8d1 100644
--- a/src/features/agents/components/inspect/AgentBrainPanel.tsx
+++ b/src/features/agents/components/inspect/AgentBrainPanel.tsx
@@ -4,6 +4,7 @@ import { useCallback, useEffect, useMemo, useState, type ReactNode } from "react
 
 import type { AgentState } from "@/features/agents/state/store";
 import type { GatewayClient } from "@/lib/gateway/GatewayClient";
+import { AgentIdentityFields } from "@/features/agents/components/AgentIdentityFields";
 import {
   AGENT_FILE_META,
   AGENT_FILE_PLACEHOLDERS,
@@ -140,52 +141,13 @@ export const AgentBrainPanel = ({
           Changing <span className="font-medium text-foreground">Name</span> here also renames the live agent
           when you save.
         </div>
-        <div className="grid gap-4 sm:grid-cols-2">
-          <label className="flex flex-col gap-2 text-xs text-muted-foreground">
-            Name
-            <input
-              className="h-10 rounded-md border border-border/80 bg-background px-3 text-sm text-foreground outline-none"
-              value={draft.identity.name}
-              disabled={agentFilesLoading || agentFilesSaving}
-              onChange={(event) => {
-                setIdentityField("name", event.target.value);
-              }}
-            />
-          </label>
-          <label className="flex flex-col gap-2 text-xs text-muted-foreground">
-            Creature
-            <input
-              className="h-10 rounded-md border border-border/80 bg-background px-3 text-sm text-foreground outline-none"
-              value={draft.identity.creature}
-              disabled={agentFilesLoading || agentFilesSaving}
-              onChange={(event) => {
-                setIdentityField("creature", event.target.value);
-              }}
-            />
-          </label>
-          <label className="flex flex-col gap-2 text-xs text-muted-foreground">
-            Vibe
-            <input
-              className="h-10 rounded-md border border-border/80 bg-background px-3 text-sm text-foreground outline-none"
-              value={draft.identity.vibe}
-              disabled={agentFilesLoading || agentFilesSaving}
-              onChange={(event) => {
-                setIdentityField("vibe", event.target.value);
-              }}
-            />
-          </label>
-          <label className="flex flex-col gap-2 text-xs text-muted-foreground">
-            Emoji
-            <input
-              className="h-10 rounded-md border border-border/80 bg-background px-3 text-sm text-foreground outline-none"
-              value={draft.identity.emoji}
-              disabled={agentFilesLoading || agentFilesSaving}
-              onChange={(event) => {
-                setIdentityField("emoji", event.target.value);
-              }}
-            />
-          </label>
-        </div>
+        <AgentIdentityFields
+          values={draft.identity}
+          disabled={agentFilesLoading || agentFilesSaving}
+          onChange={(field, value) => {
+            setIdentityField(field, value);
+          }}
+        />
       </section>
     ),
     [agentFilesLoading, agentFilesSaving, draft.identity, setIdentityField],
@@ -249,7 +211,11 @@ export const AgentBrainPanel = ({
             </button>
           </div>
 
-          <div className="space-y-8 pb-8">{renderedSections}</div>
+          <div className="space-y-8 pb-8">
+            {renderedSections.map((section, index) => (
+              <div key={`${activeSection ?? "all"}-${index}`}>{section}</div>
+            ))}
+          </div>
         </section>
       </div>
     </div>
diff --git a/src/features/agents/operations/agentFleetHydration.ts b/src/features/agents/operations/agentFleetHydration.ts
index 246db32..9bca25c 100644
--- a/src/features/agents/operations/agentFleetHydration.ts
+++ b/src/features/agents/operations/agentFleetHydration.ts
@@ -1,5 +1,11 @@
-import { buildAgentMainSessionKey, isSameSessionKey } from "@/lib/gateway/GatewayClient";
+import {
+  buildAgentMainSessionKey,
+  isSameSessionKey,
+} from "@/lib/gateway/GatewayClient";
 import { type GatewayModelPolicySnapshot } from "@/lib/gateway/models";
+import {
+  isTemporarySkillAgentName,
+} from "@/lib/skills/tempAgents";
 import { type StudioSettings, type StudioSettingsPublic } from "@/lib/studio/settings";
 import {
   type SummaryPreviewSnapshot,
@@ -156,6 +162,12 @@ export async function hydrateAgentFleetFromGateway(params: {
       agentsResult = fallback;
     }
   }
+  agentsResult = {
+    ...agentsResult,
+    agents: agentsResult.agents.filter(
+      (agent) => !isTemporarySkillAgentName(agent.name ?? agent.identity?.name)
+    ),
+  };
   const mainKey = agentsResult.mainKey?.trim() || "main";
 
   const mainSessionKeyByAgent = new Map<string, SessionsListEntry | null>();
diff --git a/src/features/agents/operations/deleteAgentOperation.ts b/src/features/agents/operations/deleteAgentOperation.ts
index 1f29d22..240debc 100644
--- a/src/features/agents/operations/deleteAgentOperation.ts
+++ b/src/features/agents/operations/deleteAgentOperation.ts
@@ -34,6 +34,11 @@ export type DeleteAgentTransactionResult = {
   restored: RestoreAgentStateResult | null;
 };
 
+const EMPTY_TRASH_RESULT: TrashAgentStateResult = {
+  trashDir: "",
+  moved: [],
+};
+
 const runDeleteFlow = async (
   deps: DeleteAgentTransactionDeps,
   agentId: string
@@ -43,7 +48,15 @@ const runDeleteFlow = async (
     throw new Error("Agent id is required.");
   }
 
-  const trashed = await deps.trashAgentState(trimmedAgentId);
+  let trashed = EMPTY_TRASH_RESULT;
+  try {
+    trashed = await deps.trashAgentState(trimmedAgentId);
+  } catch (err) {
+    deps.logError?.(
+      "Failed to move agent workspace/state into trash. Continuing with gateway deletion only.",
+      err
+    );
+  }
   let removedCronJobs: CronJobRestoreInput[] = [];
 
   try {
@@ -116,3 +129,29 @@ export const deleteAgentViaStudio = async (params: {
     params.agentId
   );
 };
+
+export const deleteAgentRecordViaStudio = async (params: {
+  client: GatewayClient;
+  agentId: string;
+  logError?: (message: string, error: unknown) => void;
+}): Promise<void> => {
+  const trimmedAgentId = params.agentId.trim();
+  if (!trimmedAgentId) {
+    throw new Error("Agent id is required.");
+  }
+  const logError = params.logError ?? ((message, error) => console.error(message, error));
+  let removedCronJobs: CronJobRestoreInput[] = [];
+  try {
+    removedCronJobs = await removeCronJobsForAgentWithBackup(params.client, trimmedAgentId);
+    await deleteGatewayAgent({ client: params.client, agentId: trimmedAgentId });
+  } catch (err) {
+    if (removedCronJobs.length > 0) {
+      try {
+        await restoreCronJobs(params.client, removedCronJobs);
+      } catch (restoreErr) {
+        logError("Failed to restore removed cron jobs.", restoreErr);
+      }
+    }
+    throw err;
+  }
+};
diff --git a/src/features/agents/operations/useAgentSettingsMutationController.ts b/src/features/agents/operations/useAgentSettingsMutationController.ts
index 5942f3f..88fe763 100644
--- a/src/features/agents/operations/useAgentSettingsMutationController.ts
+++ b/src/features/agents/operations/useAgentSettingsMutationController.ts
@@ -3,7 +3,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { AgentPermissionsDraft } from "@/features/agents/operations/agentPermissionsOperation";
 import { updateAgentPermissionsViaStudio } from "@/features/agents/operations/agentPermissionsOperation";
 import { performCronCreateFlow } from "@/features/agents/operations/cronCreateOperation";
-import { deleteAgentViaStudio } from "@/features/agents/operations/deleteAgentOperation";
+import { deleteAgentRecordViaStudio } from "@/features/agents/operations/deleteAgentOperation";
 import {
   planAgentSettingsMutation,
   type AgentSettingsMutationContext,
@@ -34,7 +34,6 @@ import {
   renameGatewayAgent,
   updateGatewayAgentSkillsAllowlist,
 } from "@/lib/gateway/agentConfig";
-import { fetchJson } from "@/lib/http";
 import { canRemoveSkillSource } from "@/lib/skills/presentation";
 import { setAgentSkillEnabled } from "@/lib/skills/agentAccess";
 import { removeSkillFromGateway } from "@/lib/skills/remove";
@@ -73,6 +72,7 @@ export type UseAgentSettingsMutationControllerParams = {
   clearInspectSidebar: () => void;
   setInspectSidebarCapabilities: (agentId: string) => void;
   dispatchUpdateAgent: (agentId: string, patch: Partial<AgentState>) => void;
+  removeAgent?: (agentId: string) => void;
   setMobilePaneChat: () => void;
   setError: (message: string) => void;
 };
@@ -441,7 +441,7 @@ export function useAgentSettingsMutationController(params: UseAgentSettingsMutat
       const agent = params.agents.find((entry) => entry.agentId === decision.normalizedAgentId);
       if (!agent) return;
       const confirmed = window.confirm(
-        `Delete ${agent.name}? This removes the agent from gateway config + scheduled automations and moves its workspace/state into ~/.openclaw/trash on the gateway host.`
+        `Delete ${agent.name}? This removes the agent record from OpenClaw and clears its scheduled automations. Claw3D will not touch workspace files.`
       );
       if (!confirmed) return;
 
@@ -451,12 +451,12 @@ export function useAgentSettingsMutationController(params: UseAgentSettingsMutat
         agentName: agent.name,
         label: `Delete ${agent.name}`,
         executeMutation: async () => {
-          await deleteAgentViaStudio({
+          await deleteAgentRecordViaStudio({
             client: params.client,
             agentId: decision.normalizedAgentId,
-            fetchJson,
             logError: (message, error) => console.error(message, error),
           });
+          params.removeAgent?.(decision.normalizedAgentId);
           params.clearInspectSidebar();
         },
       });
@@ -947,7 +947,7 @@ export function useAgentSettingsMutationController(params: UseAgentSettingsMutat
         },
       });
     },
-    [runSkillSetupMutation, setSkillMessage, settingsSkillsReport]
+    [params.client, runSkillSetupMutation, setSkillMessage, settingsSkillsReport]
   );
 
   const handleSaveSkillApiKey = useCallback(
diff --git a/src/features/agents/screens/AgentsPageScreen.tsx b/src/features/agents/screens/AgentsPageScreen.tsx
index 93dfbdf..159e451 100644
--- a/src/features/agents/screens/AgentsPageScreen.tsx
+++ b/src/features/agents/screens/AgentsPageScreen.tsx
@@ -65,7 +65,6 @@ import { useFinalizedAssistantReplyListener } from "@/hooks/useFinalizedAssistan
 import { useStudioVoiceRepliesPreference } from "@/hooks/useStudioVoiceRepliesPreference";
 import { useVoiceReplyPlayback } from "@/hooks/useVoiceReplyPlayback";
 import { isLocalGatewayUrl } from "@/lib/gateway/local-gateway";
-import { randomUUID } from "@/lib/uuid";
 import type { ExecApprovalDecision, PendingExecApproval } from "@/features/agents/approvals/types";
 import {
   planAwaitingUserInputPatches,
@@ -588,6 +587,12 @@ const AgentsPageScreen = () => {
         patch,
       });
     },
+    removeAgent: (agentId) => {
+      dispatch({
+        type: "removeAgent",
+        agentId,
+      });
+    },
     setMobilePaneChat: () => {
       setMobilePane("chat");
     },
diff --git a/src/features/agents/state/store.tsx b/src/features/agents/state/store.tsx
index 774fd33..577bd1b 100644
--- a/src/features/agents/state/store.tsx
+++ b/src/features/agents/state/store.tsx
@@ -122,6 +122,7 @@ type Action =
   | { type: "setError"; error: string | null }
   | { type: "setLoading"; loading: boolean }
   | { type: "updateAgent"; agentId: string; patch: Partial<AgentState> }
+  | { type: "removeAgent"; agentId: string }
   | { type: "appendOutput"; agentId: string; line: string; transcript?: TranscriptAppendMeta }
   | { type: "enqueueQueuedMessage"; agentId: string; message: string }
   | { type: "removeQueuedMessage"; agentId: string; index: number }
@@ -338,6 +339,18 @@ const reducer = (state: AgentStoreState, action: Action): AgentStoreState => {
           };
         }),
       };
+    case "removeAgent": {
+      const nextAgents = state.agents.filter((agent) => agent.agentId !== action.agentId);
+      const selectedAgentId =
+        state.selectedAgentId === action.agentId
+          ? nextAgents[0]?.agentId ?? null
+          : state.selectedAgentId;
+      return {
+        ...state,
+        agents: nextAgents,
+        selectedAgentId,
+      };
+    }
     case "appendOutput":
       return {
         ...state,
diff --git a/src/features/office/components/HQSidebar.tsx b/src/features/office/components/HQSidebar.tsx
index 9479bc4..db35c4f 100644
--- a/src/features/office/components/HQSidebar.tsx
+++ b/src/features/office/components/HQSidebar.tsx
@@ -15,6 +15,7 @@ type HQSidebarProps = {
   onToggle: () => void;
   onTabChange: (tab: HQSidebarTab) => void;
   onOpenMarketplace: () => void;
+  onAddAgent?: () => void;
   inboxPanel: ReactNode;
   historyPanel: ReactNode;
   playbooksPanel: ReactNode;
@@ -37,6 +38,7 @@ export function HQSidebar({
   onToggle,
   onTabChange,
   onOpenMarketplace,
+  onAddAgent,
   inboxPanel,
   historyPanel,
   playbooksPanel,
@@ -114,6 +116,15 @@ export function HQSidebar({
                 ? "Cost, budgets, and performance intelligence."
                 : "Monitor outputs, runs, and schedules."}
             </div>
+            {!railOnly && onAddAgent ? (
+              <button
+                type="button"
+                onClick={onAddAgent}
+                className="mt-3 rounded border border-cyan-500/20 bg-cyan-500/10 px-2 py-1 font-mono text-[10px] uppercase tracking-[0.16em] text-cyan-200 transition-colors hover:border-cyan-400/40 hover:text-cyan-100"
+              >
+                Add Agent
+              </button>
+            ) : null}
             {railOnly ? (
               <button
                 type="button"
diff --git a/src/features/office/hooks/useOfficeSkillTriggers.ts b/src/features/office/hooks/useOfficeSkillTriggers.ts
index a2c4d40..0a7099b 100644
--- a/src/features/office/hooks/useOfficeSkillTriggers.ts
+++ b/src/features/office/hooks/useOfficeSkillTriggers.ts
@@ -54,10 +54,11 @@ export const useOfficeSkillTriggers = ({
     () => (agentIdsKey ? agentIdsKey.split("|").filter((value) => value.length > 0) : []),
     [agentIdsKey],
   );
+  const shouldLoadTriggers =
+    status === "connected" && stableAgentIds.length > 0 && packagedTriggers.length > 0;
 
   useEffect(() => {
-    if (status !== "connected" || agents.length === 0 || packagedTriggers.length === 0) {
-      setEnabledTriggersByAgentId({});
+    if (!shouldLoadTriggers) {
       return;
     }
 
@@ -107,7 +108,12 @@ export const useOfficeSkillTriggers = ({
       cancelled = true;
       window.clearInterval(intervalId);
     };
-  }, [agentIdsKey, client, packagedTriggers, stableAgentIds, status]);
+  }, [client, packagedTriggers, shouldLoadTriggers, stableAgentIds]);
+
+  const visibleEnabledTriggersByAgentId = useMemo(
+    () => (shouldLoadTriggers ? enabledTriggersByAgentId : {}),
+    [enabledTriggersByAgentId, shouldLoadTriggers]
+  );
 
   const movementTargetByAgentId = useMemo<Record<string, OfficeSkillTriggerMovementTarget>>(() => {
     const next: Record<string, OfficeSkillTriggerMovementTarget> = {};
@@ -116,17 +122,17 @@ export const useOfficeSkillTriggers = ({
         isAgentRunning: agent.status === "running" || Boolean(agent.runId),
         lastUserMessage: agent.lastUserMessage,
         transcriptEntries: agent.transcriptEntries,
-        triggers: enabledTriggersByAgentId[agent.agentId] ?? [],
+        triggers: visibleEnabledTriggersByAgentId[agent.agentId] ?? [],
       });
       if (trigger) {
         next[agent.agentId] = trigger.movementTarget;
       }
     }
     return next;
-  }, [agents, enabledTriggersByAgentId]);
+  }, [agents, visibleEnabledTriggersByAgentId]);
 
   return {
-    enabledTriggersByAgentId,
+    enabledTriggersByAgentId: visibleEnabledTriggersByAgentId,
     movementTargetByAgentId,
   };
 };
diff --git a/src/features/office/hooks/useOfficeSkillsMarketplace.ts b/src/features/office/hooks/useOfficeSkillsMarketplace.ts
index 83a6e9a..b14dfe2 100644
--- a/src/features/office/hooks/useOfficeSkillsMarketplace.ts
+++ b/src/features/office/hooks/useOfficeSkillsMarketplace.ts
@@ -318,7 +318,7 @@ export const useOfficeSkillsMarketplace = ({
         },
       });
     },
-    [runSkillMutation],
+    [client, runSkillMutation],
   );
 
   return {
diff --git a/src/features/office/screens/OfficeScreen.tsx b/src/features/office/screens/OfficeScreen.tsx
index c7a827e..81f39ae 100644
--- a/src/features/office/screens/OfficeScreen.tsx
+++ b/src/features/office/screens/OfficeScreen.tsx
@@ -25,7 +25,10 @@ import {
   type StudioSettingsLoadOptions,
 } from "@/lib/studio/coordinator";
 import { resolveDeskAssignments } from "@/lib/studio/settings";
-import { renameGatewayAgent } from "@/lib/gateway/agentConfig";
+import {
+  createGatewayAgent,
+  renameGatewayAgent,
+} from "@/lib/gateway/agentConfig";
 import {
   runStudioBootstrapLoadOperation,
   executeStudioBootstrapLoadCommands,
@@ -53,11 +56,26 @@ import {
   AgentEditorModal,
   type AgentEditorSection,
 } from "@/features/agents/components/AgentEditorModal";
+import { AgentCreateWizardModal } from "@/features/agents/components/AgentCreateWizardModal";
+import type { AgentIdentityValues } from "@/features/agents/components/AgentIdentityFields";
 import { useChatInteractionController } from "@/features/agents/operations/useChatInteractionController";
+import {
+  applyCreateAgentBootstrapPermissions,
+  CREATE_AGENT_DEFAULT_PERMISSIONS,
+} from "@/features/agents/operations/createAgentBootstrapOperation";
+import { deleteAgentRecordViaStudio } from "@/features/agents/operations/deleteAgentOperation";
+import { planAgentSettingsMutation } from "@/features/agents/operations/agentSettingsMutationWorkflow";
 import {
   executeHistorySyncCommands,
   runHistorySyncOperation,
 } from "@/features/agents/operations/historySyncOperation";
+import {
+  buildQueuedMutationBlock,
+  runAgentConfigMutationLifecycle,
+  runCreateAgentMutationLifecycle,
+  type CreateAgentBlockState,
+} from "@/features/agents/operations/mutationLifecycleWorkflow";
+import { useConfigMutationQueue } from "@/features/agents/operations/useConfigMutationQueue";
 import {
   RUNTIME_SYNC_DEFAULT_HISTORY_LIMIT,
   RUNTIME_SYNC_MAX_HISTORY_LIMIT,
@@ -72,6 +90,12 @@ import {
 } from "@/lib/gateway/models";
 import type { GatewayModelPolicySnapshot } from "@/lib/gateway/models";
 import type { AgentAvatarProfile } from "@/lib/avatars/profile";
+import {
+  createEmptyPersonalityDraft,
+  serializePersonalityFiles,
+  type PersonalityBuilderDraft,
+} from "@/lib/agents/personalityBuilder";
+import { writeGatewayAgentFiles } from "@/lib/gateway/agentFiles";
 import { randomUUID } from "@/lib/uuid";
 import {
   HQSidebar,
@@ -167,6 +191,15 @@ type PreparedTextMessageEntry = {
   scenario: MockTextMessageScenario;
 };
 
+type OfficeDeleteMutationBlockState = {
+  kind: "delete-agent";
+  agentId: string;
+  agentName: string;
+  phase: "queued" | "mutating" | "awaiting-restart";
+  startedAt: number;
+  sawDisconnect: boolean;
+};
+
 type PhoneCallSpeakPayload = {
   agentId: string;
   requestKey: string;
@@ -214,6 +247,31 @@ const formatOpenClawValue = (value: string | null | undefined) => {
 const buildPhoneCallOutputLine = (text: string) => `[phone booth] ${text}`;
 const buildTextMessageOutputLine = (text: string) => `[messaging booth] ${text}`;
 
+const buildIdentityFileDraft = (identity: AgentIdentityValues) => {
+  const draft = createEmptyPersonalityDraft();
+  draft.identity = {
+    ...draft.identity,
+    ...identity,
+  };
+  return serializePersonalityFiles(draft);
+};
+
+const resolveOfficeMutationGuardMessage = (guardReason?: string) => {
+  if (guardReason === "not-connected") {
+    return "Connect to the gateway before changing the office fleet.";
+  }
+  if (guardReason === "create-block-active") {
+    return "Finish the active agent creation before starting another fleet change.";
+  }
+  if (guardReason === "rename-block-active") {
+    return "Finish the active rename before changing the office fleet.";
+  }
+  if (guardReason === "delete-block-active") {
+    return "Finish the active deletion before changing the office fleet.";
+  }
+  return "The office fleet is busy right now.";
+};
+
 const PHONE_BOOTH_ASSISTANT_FALLBACK_RE =
   /\b(?:i\s+)?can(?:not|['’]t)\s+(?:place|make)\s+(?:phone\s+)?calls?\b/i;
 
@@ -745,6 +803,16 @@ export function OfficeScreen({
   const [agentEditorAgentId, setAgentEditorAgentId] = useState<string | null>(null);
   const [agentEditorInitialSection, setAgentEditorInitialSection] =
     useState<AgentEditorSection>("avatar");
+  const [createAgentWizardNonce, setCreateAgentWizardNonce] = useState(0);
+  const [createAgentWizardOpen, setCreateAgentWizardOpen] = useState(false);
+  const [createAgentBusy, setCreateAgentBusy] = useState(false);
+  const [createAgentModalError, setCreateAgentModalError] = useState<string | null>(
+    null,
+  );
+  const [createAgentBlock, setCreateAgentBlock] =
+    useState<CreateAgentBlockState | null>(null);
+  const [deleteAgentBlock, setDeleteAgentBlock] =
+    useState<OfficeDeleteMutationBlockState | null>(null);
   const [preparedPhoneCallsByAgentId, setPreparedPhoneCallsByAgentId] = useState<
     Record<string, PreparedPhoneCallEntry>
   >({});
@@ -900,6 +968,22 @@ export function OfficeScreen({
     stateRef.current = state;
   }, [state]);
 
+  const hasRunningAgents = useMemo(
+    () =>
+      state.agents.some(
+        (agent) => agent.status === "running" || Boolean(agent.runId),
+      ),
+    [state.agents],
+  );
+  const hasDeleteMutationBlock = deleteAgentBlock?.kind === "delete-agent";
+  const { enqueueConfigMutation } = useConfigMutationQueue({
+    status,
+    hasRunningAgents,
+    hasRestartBlockInProgress: Boolean(
+      deleteAgentBlock && deleteAgentBlock.phase !== "queued",
+    ),
+  });
+
   useEffect(() => {
     officeTriggerStateRef.current = officeTriggerState;
   }, [officeTriggerState]);
@@ -1111,6 +1195,335 @@ export function OfficeScreen({
     status,
   ]);
 
+  const handleCloseCreateAgentWizard = useCallback(
+    (createdAgentId: string | null) => {
+      setCreateAgentWizardOpen(false);
+      setCreateAgentModalError(null);
+      if (createdAgentId) {
+        openAgentEditor(createdAgentId, "IDENTITY.md");
+      }
+    },
+    [openAgentEditor],
+  );
+  const handleOpenCreateAgentWizard = useCallback(() => {
+    setCreateAgentModalError(null);
+    setCreateAgentWizardNonce((current) => current + 1);
+    setCreateAgentWizardOpen(true);
+  }, []);
+  const clearDeletedAgentUiState = useCallback((agentId: string) => {
+    setSelectedChatAgentId((current) => (current === agentId ? null : current));
+    setAgentEditorAgentId((current) => (current === agentId ? null : current));
+    setMonitorAgentId((current) => (current === agentId ? null : current));
+    setGithubReviewAgentId((current) => (current === agentId ? null : current));
+    setQaTestingAgentId((current) => (current === agentId ? null : current));
+    setPreparedPhoneCallsByAgentId((current) => {
+      if (!(agentId in current)) return current;
+      const next = { ...current };
+      delete next[agentId];
+      return next;
+    });
+    setPreparedTextMessagesByAgentId((current) => {
+      if (!(agentId in current)) return current;
+      const next = { ...current };
+      delete next[agentId];
+      return next;
+    });
+  }, []);
+  const createAgentStatusLine = useMemo(() => {
+    if (!createAgentBlock) return null;
+    if (createAgentBlock.phase === "queued") {
+      return "Waiting for active runs to finish before creating the new agent.";
+    }
+    return `Creating ${createAgentBlock.agentName}.`;
+  }, [createAgentBlock]);
+  const deleteAgentStatusLine = useMemo(() => {
+    if (!deleteAgentBlock) return null;
+    if (deleteAgentBlock.phase === "queued") {
+      return `Waiting for active runs to finish before deleting ${deleteAgentBlock.agentName}.`;
+    }
+    return `Deleting ${deleteAgentBlock.agentName}.`;
+  }, [deleteAgentBlock]);
+  const handleCreateAgentFromIdentity = useCallback(
+    async (identity: AgentIdentityValues) => {
+      let createdAgentId: string | null = null;
+      const success = await runCreateAgentMutationLifecycle(
+        {
+          payload: {
+            name: identity.name,
+          },
+          status,
+          hasCreateBlock: Boolean(createAgentBlock),
+          hasRenameBlock: false,
+          hasDeleteBlock: Boolean(hasDeleteMutationBlock),
+          createAgentBusy,
+        },
+        {
+          enqueueConfigMutation,
+          createAgent: async (name) => {
+            const created = await createGatewayAgent({ client, name });
+            const files = buildIdentityFileDraft(identity);
+            await writeGatewayAgentFiles({
+              client,
+              agentId: created.id,
+              files: {
+                "IDENTITY.md": files["IDENTITY.md"],
+              },
+            });
+            return { id: created.id };
+          },
+          setQueuedBlock: ({ agentName, startedAt }) => {
+            const queuedCreateBlock = buildQueuedMutationBlock({
+              kind: "create-agent",
+              agentId: "",
+              agentName,
+              startedAt,
+            });
+            setCreateAgentBlock({
+              agentName: queuedCreateBlock.agentName,
+              phase: "queued",
+              startedAt: queuedCreateBlock.startedAt,
+            });
+          },
+          setCreatingBlock: (agentName) => {
+            setCreateAgentBlock((current) => {
+              if (!current || current.agentName !== agentName) return current;
+              return { ...current, phase: "creating" };
+            });
+          },
+          onCompletion: async (completion) => {
+            createdAgentId = completion.agentId;
+            await loadAgents({ forceSettings: true });
+            const createdAgent =
+              stateRef.current.agents.find(
+                (entry) => entry.agentId === completion.agentId,
+              ) ?? null;
+            if (createdAgent?.sessionKey) {
+              try {
+                await applyCreateAgentBootstrapPermissions({
+                  client,
+                  agentId: createdAgent.agentId,
+                  sessionKey: createdAgent.sessionKey,
+                  draft: { ...CREATE_AGENT_DEFAULT_PERMISSIONS },
+                  loadAgents: () => loadAgents({ forceSettings: true }),
+                });
+              } catch (error) {
+                const message =
+                  error instanceof Error
+                    ? error.message
+                    : "Failed to apply default permissions.";
+                setError(
+                  `Agent created, but default permissions could not be applied: ${message}`,
+                );
+              }
+            }
+            dispatch({
+              type: "selectAgent",
+              agentId: completion.agentId,
+            });
+            setSelectedChatAgentId(completion.agentId);
+            setCreateAgentBlock(null);
+            setCreateAgentModalError(null);
+          },
+          setCreateAgentModalError,
+          setCreateAgentBusy,
+          clearCreateBlock: () => {
+            setCreateAgentBlock(null);
+          },
+          onError: setError,
+        },
+      );
+      return success ? createdAgentId : null;
+    },
+    [
+      client,
+      createAgentBlock,
+      createAgentBusy,
+      dispatch,
+      enqueueConfigMutation,
+      hasDeleteMutationBlock,
+      loadAgents,
+      setError,
+      status,
+    ],
+  );
+  const handleFinishCreateAgentAvatar = useCallback(
+    async (params: {
+      agentId: string;
+      draft: PersonalityBuilderDraft;
+      profile: AgentAvatarProfile;
+    }) => {
+      setCreateAgentBusy(true);
+      setCreateAgentModalError(null);
+      try {
+        const files = serializePersonalityFiles(params.draft);
+        await writeGatewayAgentFiles({
+          client,
+          agentId: params.agentId,
+          files,
+        });
+        const currentAgent =
+          stateRef.current.agents.find((entry) => entry.agentId === params.agentId) ?? null;
+        const nextName = params.draft.identity.name.trim();
+        const currentName = currentAgent?.name.trim() ?? "";
+        if (nextName && nextName !== currentName) {
+          const renamed = await renameGatewayAgent({
+            client,
+            agentId: params.agentId,
+            name: nextName,
+          });
+          if (!renamed) {
+            throw new Error("Saved the wizard files, but could not rename the live agent.");
+          }
+        }
+        handleAvatarProfileSave(params.agentId, params.profile);
+        await loadAgents({ forceSettings: true });
+        setCreateAgentWizardOpen(false);
+        setCreateAgentModalError(null);
+        openAgentEditor(params.agentId, "IDENTITY.md");
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Failed to finish creating the agent.";
+        setCreateAgentModalError(message);
+      } finally {
+        setCreateAgentBusy(false);
+      }
+    },
+    [client, handleAvatarProfileSave, loadAgents, openAgentEditor],
+  );
+  const handleDeleteAgent = useCallback(
+    async (agentId: string) => {
+      const decision = planAgentSettingsMutation(
+        { kind: "delete-agent", agentId },
+        {
+          status,
+          hasCreateBlock: Boolean(createAgentBlock),
+          hasRenameBlock: false,
+          hasDeleteBlock: Boolean(hasDeleteMutationBlock),
+          cronCreateBusy: false,
+          cronRunBusyJobId: null,
+          cronDeleteBusyJobId: null,
+        },
+      );
+      if (decision.kind === "deny") {
+        setError(
+          decision.message ?? resolveOfficeMutationGuardMessage(decision.guardReason),
+        );
+        return;
+      }
+      const agent = state.agents.find(
+        (entry) => entry.agentId === decision.normalizedAgentId,
+      );
+      if (!agent) return;
+      const confirmed = window.confirm(
+        `Delete ${agent.name}? This removes the agent record from OpenClaw and clears its scheduled automations. Claw3D will not touch workspace files.`,
+      );
+      if (!confirmed) return;
+
+      await runAgentConfigMutationLifecycle({
+        kind: "delete-agent",
+        label: `Delete ${agent.name}`,
+        isLocalGateway: false,
+        deps: {
+          enqueueConfigMutation,
+          setQueuedBlock: () => {
+            const queuedBlock = buildQueuedMutationBlock({
+              kind: "delete-agent",
+              agentId: decision.normalizedAgentId,
+              agentName: agent.name,
+              startedAt: Date.now(),
+            });
+            setDeleteAgentBlock({
+              kind: "delete-agent",
+              agentId: queuedBlock.agentId,
+              agentName: queuedBlock.agentName,
+              phase: queuedBlock.phase,
+              startedAt: queuedBlock.startedAt,
+              sawDisconnect: queuedBlock.sawDisconnect,
+            });
+          },
+          setMutatingBlock: () => {
+            setDeleteAgentBlock((current) => {
+              if (!current || current.agentId !== decision.normalizedAgentId) {
+                return current;
+              }
+              return {
+                ...current,
+                phase: "mutating",
+              };
+            });
+          },
+          patchBlockAwaitingRestart: (patch) => {
+            setDeleteAgentBlock((current) => {
+              if (!current || current.agentId !== decision.normalizedAgentId) {
+                return current;
+              }
+              return {
+                ...current,
+                ...patch,
+              };
+            });
+          },
+          clearBlock: () => {
+            setDeleteAgentBlock((current) => {
+              if (!current || current.agentId !== decision.normalizedAgentId) {
+                return current;
+              }
+              return null;
+            });
+          },
+          executeMutation: async () => {
+            await deleteAgentRecordViaStudio({
+              client,
+              agentId: decision.normalizedAgentId,
+              logError: (message, error) => console.error(message, error),
+            });
+            clearDeletedAgentUiState(decision.normalizedAgentId);
+            dispatch({
+              type: "removeAgent",
+              agentId: decision.normalizedAgentId,
+            });
+          },
+          shouldAwaitRemoteRestart: async () => false,
+          reloadAgents: () => loadAgents({ forceSettings: true }),
+          setMobilePaneChat: () => {},
+          onError: setError,
+        },
+      });
+    },
+    [
+      clearDeletedAgentUiState,
+      client,
+      createAgentBlock,
+      dispatch,
+      enqueueConfigMutation,
+      hasDeleteMutationBlock,
+      loadAgents,
+      setError,
+      state.agents,
+      status,
+    ],
+  );
+
+  useEffect(() => {
+    if (!createAgentBlock || createAgentBlock.phase === "queued") return;
+    const maxWaitMs = 90_000;
+    const elapsed = Date.now() - createAgentBlock.startedAt;
+    const remaining = Math.max(0, maxWaitMs - elapsed);
+    const timeoutId = window.setTimeout(() => {
+      setCreateAgentBlock((current) => {
+        if (!current || current.phase === "queued") return current;
+        return null;
+      });
+      setCreateAgentBusy(false);
+      setCreateAgentWizardOpen(false);
+      setError("Agent creation timed out.");
+      void loadAgents({ forceSettings: true });
+    }, remaining);
+    return () => {
+      window.clearTimeout(timeoutId);
+    };
+  }, [createAgentBlock, loadAgents, setError]);
+
   const requestAgentHistoryRefresh = useCallback(
     async (params: {
       agentId: string;
@@ -1341,6 +1754,11 @@ export function OfficeScreen({
     if (status === "disconnected") {
       connectionEpochRef.current += 1;
       setAgentsLoaded(false);
+      setCreateAgentWizardOpen(false);
+      setCreateAgentBusy(false);
+      setCreateAgentModalError(null);
+      setCreateAgentBlock(null);
+      setDeleteAgentBlock(null);
       loadAgentsInFlightRef.current = null;
       gatewayConfigSnapshot.current = null;
       lastLoadAgentsStartedAtRef.current = 0;
@@ -1665,6 +2083,19 @@ export function OfficeScreen({
     : null;
   const mainAgent =
     state.agents.find((agent) => agent.agentId === MAIN_AGENT_ID) ?? null;
+
+  useEffect(() => {
+    if (!selectedChatAgentId) return;
+    if (state.agents.some((agent) => agent.agentId === selectedChatAgentId)) return;
+    setSelectedChatAgentId(null);
+  }, [selectedChatAgentId, state.agents]);
+
+  useEffect(() => {
+    if (!agentEditorAgentId) return;
+    if (state.agents.some((agent) => agent.agentId === agentEditorAgentId)) return;
+    setAgentEditorAgentId(null);
+  }, [agentEditorAgentId, state.agents]);
+
   const runLog = useRunLog({ client, status, agents: state.agents });
   const standupAgentSnapshots = useMemo<StandupAgentSnapshot[]>(
     () =>
@@ -2870,9 +3301,13 @@ export function OfficeScreen({
             dispatch({ type: "selectAgent", agentId });
           }
         }}
+        onAddAgent={handleOpenCreateAgentWizard}
         onAgentEdit={(agentId) => {
           openAgentEditor(agentId, "avatar");
         }}
+        onAgentDelete={(agentId) => {
+          void handleDeleteAgent(agentId);
+        }}
         onDeskAssignmentChange={handleDeskAssignmentChange}
         onDeskAssignmentsReset={handleDeskAssignmentsReset}
         onGithubReviewDismiss={() => {
@@ -2899,20 +3334,42 @@ export function OfficeScreen({
                 </p>
                 <p className="mt-1 text-sm text-amber-50">{emptyFleetMessage}</p>
               </div>
-              <button
-                type="button"
-                className="ui-btn-secondary shrink-0 px-3 py-2 text-xs font-semibold tracking-[0.05em] text-foreground"
-                onClick={() => {
-                  void loadAgents({ forceSettings: true });
-                }}
-              >
-                Retry
-              </button>
+              <div className="flex shrink-0 items-center gap-2">
+                <button
+                  type="button"
+                  className="ui-btn-secondary px-3 py-2 text-xs font-semibold tracking-[0.05em] text-foreground"
+                  onClick={() => {
+                    handleOpenCreateAgentWizard();
+                  }}
+                >
+                  Add Agent
+                </button>
+                <button
+                  type="button"
+                  className="ui-btn-secondary px-3 py-2 text-xs font-semibold tracking-[0.05em] text-foreground"
+                  onClick={() => {
+                    void loadAgents({ forceSettings: true });
+                  }}
+                >
+                  Retry
+                </button>
+              </div>
             </div>
           </div>
         </div>
       ) : null}
 
+      {deleteAgentStatusLine ? (
+        <div className="pointer-events-none fixed left-1/2 top-5 z-40 -translate-x-1/2 px-4">
+          <div className="pointer-events-auto rounded-lg border border-red-400/30 bg-black/85 px-4 py-3 shadow-2xl backdrop-blur">
+            <div className="font-mono text-[10px] uppercase tracking-[0.16em] text-red-200/75">
+              Fleet mutation
+            </div>
+            <div className="mt-1 text-sm text-red-50">{deleteAgentStatusLine}</div>
+          </div>
+        </div>
+      ) : null}
+
       {!debugEnabled ? (
         <HQSidebar
           open={sidebarOpen}
@@ -2921,6 +3378,7 @@ export function OfficeScreen({
           onToggle={() => setSidebarOpen((prev) => !prev)}
           onTabChange={setActiveSidebarTab}
           onOpenMarketplace={() => setMarketplaceOpen(true)}
+          onAddAgent={handleOpenCreateAgentWizard}
           inboxPanel={
             <InboxPanel
               agents={state.agents}
@@ -3444,6 +3902,7 @@ export function OfficeScreen({
       ) : null}
       {agentEditorAgent ? (
         <AgentEditorModal
+          key={`${agentEditorAgent.agentId}:${agentEditorInitialSection}`}
           open
           client={client}
           agents={state.agents}
@@ -3463,8 +3922,25 @@ export function OfficeScreen({
               return false;
             }
           }}
+          onDelete={async (agentId) => {
+            await handleDeleteAgent(agentId);
+          }}
+          onNavigateAgent={(agentId, section) => {
+            openAgentEditor(agentId, section);
+          }}
         />
       ) : null}
+      <AgentCreateWizardModal
+        key={createAgentWizardNonce}
+        open={createAgentWizardOpen}
+        suggestedName={`Agent ${state.agents.length + 1}`}
+        busy={createAgentBusy}
+        submitError={createAgentModalError}
+        statusLine={createAgentStatusLine}
+        onClose={handleCloseCreateAgentWizard}
+        onCreateAgent={handleCreateAgentFromIdentity}
+        onFinishWizard={handleFinishCreateAgentAvatar}
+      />
     </main>
   );
 }
diff --git a/src/features/retro-office/RetroOffice3D.tsx b/src/features/retro-office/RetroOffice3D.tsx
index aa199e4..0b17a7c 100644
--- a/src/features/retro-office/RetroOffice3D.tsx
+++ b/src/features/retro-office/RetroOffice3D.tsx
@@ -9,6 +9,8 @@ import {
   Armchair,
   Settings2,
   Camera,
+  UserPlus,
+  Trash2,
   Users,
   X,
 } from "lucide-react";
@@ -1901,7 +1903,9 @@ export function RetroOffice3D({
   onStandupArrivalsChange,
   onStandupStartRequested,
   onMonitorSelect,
+  onAddAgent,
   onAgentEdit,
+  onAgentDelete,
   onDeskAssignmentChange,
   onDeskAssignmentsReset,
   onGithubReviewDismiss,
@@ -1965,7 +1969,9 @@ export function RetroOffice3D({
   onStandupArrivalsChange?: (arrivedAgentIds: string[]) => void;
   onStandupStartRequested?: () => void;
   onMonitorSelect?: (agentId: string | null) => void;
+  onAddAgent?: () => void;
   onAgentEdit?: (agentId: string) => void;
+  onAgentDelete?: (agentId: string) => void;
   onDeskAssignmentChange?: (deskUid: string, agentId: string | null) => void;
   onDeskAssignmentsReset?: (deskUids: string[]) => void;
   onGithubReviewDismiss?: () => void;
@@ -2497,10 +2503,7 @@ export function RetroOffice3D({
       ) ?? null
     );
   }, [assignedDeskIndexByAgentId, deskLocations, furniture, monitorAgentId]);
-  useEffect(() => {
-    if (!immersiveOverlayActive) return;
-    setAgentRosterOpen(false);
-  }, [immersiveOverlayActive]);
+  const agentRosterVisible = agentRosterOpen && !immersiveOverlayActive;
   const selectedItem = useMemo(
     () => furniture.find((item) => item._uid === selectedUid) ?? null,
     [furniture, selectedUid],
@@ -5124,7 +5127,7 @@ export function RetroOffice3D({
             </button>
           </div>
 
-          {agentRosterOpen ? (
+          {agentRosterVisible ? (
             <div className="absolute left-1/2 top-full mt-2 w-[min(92vw,560px)] -translate-x-1/2 rounded-2xl border border-amber-900/25 bg-[#120e08]/96 p-3 shadow-2xl backdrop-blur-sm">
               <div className="mb-3 flex items-center justify-between gap-3">
                 <div>
@@ -5223,6 +5226,19 @@ export function RetroOffice3D({
                       >
                         <Monitor size={12} />
                       </button>
+                      {onAgentDelete ? (
+                        <button
+                          type="button"
+                          title="Delete agent"
+                          onClick={() => {
+                            onAgentDelete(agent.id);
+                            setAgentRosterOpen(false);
+                          }}
+                          className="flex h-8 w-8 items-center justify-center rounded-lg border border-red-900/30 text-red-300/70 transition-colors hover:border-red-500/40 hover:bg-red-500/10 hover:text-red-200"
+                        >
+                          <Trash2 size={12} />
+                        </button>
+                      ) : null}
                     </div>
                   );
                 })}
@@ -5953,6 +5969,16 @@ export function RetroOffice3D({
       {/* Toolbar — top right. */}
       {!immersiveOverlayActive ? (
         <div className="absolute top-3 right-3 flex items-center gap-2 z-20">
+          {onAddAgent ? (
+            <button
+              onClick={onAddAgent}
+              title="Add agent"
+              className="flex h-7 items-center justify-center gap-1 rounded-md border border-cyan-500/35 bg-[#071018]/92 px-2 text-[10px] font-semibold uppercase tracking-[0.12em] text-cyan-200 transition-all backdrop-blur-sm hover:border-cyan-400/55 hover:text-white"
+            >
+              <UserPlus size={12} />
+              <span>Add</span>
+            </button>
+          ) : null}
           {/* New Idea 7: Heatmap toggle. */}
           <button
             onClick={() => setHeatmapMode((p) => !p)}
diff --git a/src/lib/agents/personalityBuilder.ts b/src/lib/agents/personalityBuilder.ts
index b3e5eb1..5cb5c8f 100644
--- a/src/lib/agents/personalityBuilder.ts
+++ b/src/lib/agents/personalityBuilder.ts
@@ -30,7 +30,7 @@ export type PersonalityBuilderDraft = {
 
 type AgentFilesInput = Record<AgentFileName, { content: string; exists: boolean }>;
 
-const createEmptyDraft = (): PersonalityBuilderDraft => ({
+export const createEmptyPersonalityDraft = (): PersonalityBuilderDraft => ({
   identity: {
     name: "",
     creature: "",
@@ -253,7 +253,7 @@ const serializeSoulMarkdown = (draft: PersonalityBuilderDraft["soul"]) => {
 };
 
 export const parsePersonalityFiles = (files: AgentFilesInput): PersonalityBuilderDraft => {
-  const draft = createEmptyDraft();
+  const draft = createEmptyPersonalityDraft();
 
   const identity = parseLabelMap(files["IDENTITY.md"].content);
   const identityName = readFirst(identity, ["name"]);
diff --git a/src/lib/gateway/GatewayClient.ts b/src/lib/gateway/GatewayClient.ts
index c25ec10..9db66ba 100644
--- a/src/lib/gateway/GatewayClient.ts
+++ b/src/lib/gateway/GatewayClient.ts
@@ -479,6 +479,7 @@ const NON_RETRYABLE_CONNECT_ERROR_CODES = new Set([
   "studio.gateway_token_missing",
   "studio.gateway_url_invalid",
   "studio.settings_load_failed",
+  "studio.upstream_error",
 ]);
 
 const isNonRetryableConnectErrorCode = (code: string | null): boolean => {
diff --git a/src/lib/gateway/local-gateway.ts b/src/lib/gateway/local-gateway.ts
index 02fea48..bdc67b1 100644
--- a/src/lib/gateway/local-gateway.ts
+++ b/src/lib/gateway/local-gateway.ts
@@ -8,6 +8,18 @@ const parseHostname = (gatewayUrl: string): string | null => {
   }
 };
 
+const LOCAL_HOST_SUFFIXES = [".local", ".home.arpa", ".lan", ".internal"] as const;
+
+const isPrivateIpv4Address = (hostname: string) => {
+  const match = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(hostname);
+  if (!match) return false;
+  const [first, second] = [Number.parseInt(match[1], 10), Number.parseInt(match[2], 10)];
+  if (first === 10) return true;
+  if (first === 172 && second >= 16 && second <= 31) return true;
+  if (first === 192 && second === 168) return true;
+  return false;
+};
+
 export const isLocalGatewayUrl = (gatewayUrl: string): boolean => {
   const hostname = parseHostname(gatewayUrl);
   if (!hostname) return false;
@@ -20,3 +32,13 @@ export const isLocalGatewayUrl = (gatewayUrl: string): boolean => {
   );
 };
 
+export const isLikelyLocalGatewayUrl = (gatewayUrl: string): boolean => {
+  if (isLocalGatewayUrl(gatewayUrl)) return true;
+  const hostname = parseHostname(gatewayUrl);
+  if (!hostname) return false;
+  const normalized = hostname.trim().toLowerCase();
+  if (isPrivateIpv4Address(normalized)) return true;
+  if (normalized.endsWith(".ts.net")) return true;
+  return LOCAL_HOST_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+};
+
diff --git a/src/lib/skills/tempAgents.ts b/src/lib/skills/tempAgents.ts
new file mode 100644
index 0000000..dbc96c9
--- /dev/null
+++ b/src/lib/skills/tempAgents.ts
@@ -0,0 +1,27 @@
+const TEMP_SKILL_AGENT_RE = /^Skill (Installer|Remover) (\d{13})$/;
+
+const STALE_TEMP_SKILL_AGENT_MS = 15 * 60 * 1000;
+
+export const isTemporarySkillAgentName = (value: string | null | undefined): boolean => {
+  const trimmed = value?.trim() ?? "";
+  return TEMP_SKILL_AGENT_RE.test(trimmed);
+};
+
+export const resolveTemporarySkillAgentCreatedAt = (
+  value: string | null | undefined
+): number | null => {
+  const trimmed = value?.trim() ?? "";
+  const match = TEMP_SKILL_AGENT_RE.exec(trimmed);
+  if (!match) return null;
+  const timestamp = Number.parseInt(match[2], 10);
+  return Number.isFinite(timestamp) ? timestamp : null;
+};
+
+export const isStaleTemporarySkillAgentName = (
+  value: string | null | undefined,
+  nowMs: number = Date.now()
+): boolean => {
+  const createdAt = resolveTemporarySkillAgentCreatedAt(value);
+  if (createdAt === null) return false;
+  return nowMs - createdAt >= STALE_TEMP_SKILL_AGENT_MS;
+};
diff --git a/tests/unit/agentBrainPanel.test.ts b/tests/unit/agentBrainPanel.test.ts
index 35135c6..7421ad9 100644
--- a/tests/unit/agentBrainPanel.test.ts
+++ b/tests/unit/agentBrainPanel.test.ts
@@ -111,14 +111,14 @@ describe("AgentBrainPanel", () => {
     );
 
     await waitFor(() => {
-      expect(screen.getByRole("heading", { name: "Persona" })).toBeInTheDocument();
+      expect(screen.getByRole("heading", { name: "SOUL.md" })).toBeInTheDocument();
     });
 
-    expect(screen.getByRole("heading", { name: "Directives" })).toBeInTheDocument();
-    expect(screen.getByRole("heading", { name: "Context" })).toBeInTheDocument();
-    expect(screen.getByRole("heading", { name: "Identity" })).toBeInTheDocument();
-    expect(screen.getByLabelText("Directives")).toHaveValue("alpha agents");
-    expect(screen.getByLabelText("Persona")).toHaveValue(
+    expect(screen.getByRole("heading", { name: "AGENTS.md" })).toBeInTheDocument();
+    expect(screen.getByRole("heading", { name: "USER.md" })).toBeInTheDocument();
+    expect(screen.getByRole("heading", { name: "IDENTITY.md" })).toBeInTheDocument();
+    expect(screen.getByLabelText("AGENTS.md")).toHaveValue("alpha agents");
+    expect(screen.getByLabelText("SOUL.md")).toHaveValue(
       "# SOUL.md - Who You Are\n\n## Core Truths\n\nBe useful."
     );
     expect(screen.getByLabelText("Name")).toHaveValue("Alpha");
@@ -154,10 +154,10 @@ describe("AgentBrainPanel", () => {
     );
 
     await waitFor(() => {
-      expect(screen.getByLabelText("Directives")).toBeInTheDocument();
+      expect(screen.getByLabelText("AGENTS.md")).toBeInTheDocument();
     });
 
-    fireEvent.change(screen.getByLabelText("Directives"), {
+    fireEvent.change(screen.getByLabelText("AGENTS.md"), {
       target: { value: "alpha directives updated" },
     });
 
@@ -171,15 +171,17 @@ describe("AgentBrainPanel", () => {
     expect(filesByAgent["agent-1"]["AGENTS.md"]).toBe("alpha directives updated");
   });
 
-  it("discards_unsaved_changes_without_writing_files", async () => {
+  it("calls_cancel_without_writing_files", async () => {
     const { client, calls } = createMockClient();
     const agents = [createAgent("agent-1", "Alpha", "session-1")];
+    const onCancel = vi.fn();
 
     render(
       createElement(AgentBrainPanel, {
         client,
         agents,
         selectedAgentId: "agent-1",
+        onCancel,
       })
     );
 
@@ -192,12 +194,12 @@ describe("AgentBrainPanel", () => {
     });
     expect(screen.getByLabelText("Name")).toHaveValue("Alpha Prime");
 
-    fireEvent.click(screen.getByRole("button", { name: "Discard" }));
-    expect(screen.getByLabelText("Name")).toHaveValue("Alpha");
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    expect(onCancel).toHaveBeenCalledTimes(1);
     expect(calls.some((entry) => entry.method === "agents.files.set")).toBe(false);
   });
 
-  it("does_not_render_name_editor_in_personality_panel", async () => {
+  it("does_not_render_legacy_name_editor_controls", async () => {
     const { client } = createMockClient();
     const agents = [createAgent("agent-1", "Alpha", "session-1")];
 
@@ -210,7 +212,7 @@ describe("AgentBrainPanel", () => {
     );
 
     await waitFor(() => {
-      expect(screen.getByRole("heading", { name: "Persona" })).toBeInTheDocument();
+      expect(screen.getByRole("heading", { name: "SOUL.md" })).toBeInTheDocument();
     });
     expect(screen.queryByLabelText("Agent name")).not.toBeInTheDocument();
     expect(screen.queryByRole("button", { name: "Update Name" })).not.toBeInTheDocument();
diff --git a/tests/unit/agentSettingsPanel.test.ts b/tests/unit/agentSettingsPanel.test.ts
index e718e4f..51a0fa6 100644
--- a/tests/unit/agentSettingsPanel.test.ts
+++ b/tests/unit/agentSettingsPanel.test.ts
@@ -615,7 +615,7 @@ describe("AgentSettingsPanel", () => {
       target: { value: "git" },
     });
     fireEvent.click(screen.getByRole("button", { name: "Configure" }));
-    fireEvent.click(screen.getByRole("button", { name: "Remove skill from gateway" }));
+    fireEvent.click(screen.getByRole("button", { name: "Remove for all agents" }));
 
     expect(onRemoveSkill).toHaveBeenCalledWith({
       skillKey: "github",
diff --git a/tests/unit/gatewayConnectRetryPolicy.test.ts b/tests/unit/gatewayConnectRetryPolicy.test.ts
index 6f83f2d..148a79a 100644
--- a/tests/unit/gatewayConnectRetryPolicy.test.ts
+++ b/tests/unit/gatewayConnectRetryPolicy.test.ts
@@ -18,7 +18,7 @@ describe("resolveGatewayAutoRetryDelayMs", () => {
     expect(delay).toBeNull();
   });
 
-  it("retries for non-auth connect failures", () => {
+  it("does not retry when the upstream websocket upgrade fails", () => {
     const delay = resolveGatewayAutoRetryDelayMs({
       status: "disconnected",
       didAutoConnect: true,
@@ -31,8 +31,7 @@ describe("resolveGatewayAutoRetryDelayMs", () => {
       attempt: 0,
     });
 
-    expect(delay).toBeTypeOf("number");
-    expect(delay).toBeGreaterThan(0);
+    expect(delay).toBeNull();
   });
 });
 
diff --git a/tests/unit/onboardingState.test.ts b/tests/unit/onboardingState.test.ts
index 6640b1d..7f348fe 100644
--- a/tests/unit/onboardingState.test.ts
+++ b/tests/unit/onboardingState.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 import { act, renderHook } from "@testing-library/react";
 import { useOnboardingState } from "@/features/onboarding/useOnboardingState";
 
diff --git a/tests/unit/settingsRouteWorkflow.test.ts b/tests/unit/settingsRouteWorkflow.test.ts
index f0be0f2..2868758 100644
--- a/tests/unit/settingsRouteWorkflow.test.ts
+++ b/tests/unit/settingsRouteWorkflow.test.ts
@@ -68,7 +68,7 @@ describe("settingsRouteWorkflow", () => {
       })
     ).toEqual([
       { kind: "set-personality-dirty", value: false },
-      { kind: "push", href: "/agents" },
+      { kind: "push", href: "/" },
     ]);
   });
 
@@ -169,7 +169,7 @@ describe("settingsRouteWorkflow", () => {
         hasRouteAgent: false,
         currentInspectSidebar: null,
       })
-    ).toEqual([{ kind: "replace", href: "/agents" }]);
+    ).toEqual([{ kind: "replace", href: "/" }]);
   });
 
   it("plans non-route selection reconciliation", () => {
diff --git a/tests/unit/useAgentSettingsMutationController.test.ts b/tests/unit/useAgentSettingsMutationController.test.ts
index 16fc99c..7e59352 100644
--- a/tests/unit/useAgentSettingsMutationController.test.ts
+++ b/tests/unit/useAgentSettingsMutationController.test.ts
@@ -8,7 +8,7 @@ import type { CronRunResult } from "@/lib/cron/types";
 import type { MutationBlockState } from "@/features/agents/operations/mutationLifecycleWorkflow";
 
 import { useAgentSettingsMutationController } from "@/features/agents/operations/useAgentSettingsMutationController";
-import { deleteAgentViaStudio } from "@/features/agents/operations/deleteAgentOperation";
+import { deleteAgentRecordViaStudio } from "@/features/agents/operations/deleteAgentOperation";
 import { performCronCreateFlow } from "@/features/agents/operations/cronCreateOperation";
 import { updateAgentPermissionsViaStudio } from "@/features/agents/operations/agentPermissionsOperation";
 import { runAgentConfigMutationLifecycle } from "@/features/agents/operations/mutationLifecycleWorkflow";
@@ -50,7 +50,7 @@ vi.mock("@/features/agents/operations/useGatewayRestartBlock", () => ({
 }));
 
 vi.mock("@/features/agents/operations/deleteAgentOperation", () => ({
-  deleteAgentViaStudio: vi.fn(),
+  deleteAgentRecordViaStudio: vi.fn(),
 }));
 
 vi.mock("@/features/agents/operations/cronCreateOperation", () => ({
@@ -219,7 +219,7 @@ const renderController = (overrides?: Partial<Parameters<typeof useAgentSettings
 };
 
 describe("useAgentSettingsMutationController", () => {
-  const mockedDeleteAgentViaStudio = vi.mocked(deleteAgentViaStudio);
+  const mockedDeleteAgentViaStudio = vi.mocked(deleteAgentRecordViaStudio);
   const mockedPerformCronCreateFlow = vi.mocked(performCronCreateFlow);
   const mockedRunCronJobNow = vi.mocked(runCronJobNow);
   const mockedRemoveCronJob = vi.mocked(removeCronJob);
@@ -347,7 +347,7 @@ describe("useAgentSettingsMutationController", () => {
       deps.clearBlock();
       return true;
     });
-    mockedDeleteAgentViaStudio.mockResolvedValue({ trashed: { trashDir: "", moved: [] }, restored: null });
+    mockedDeleteAgentViaStudio.mockResolvedValue(undefined);
 
     const ctx = renderController();
 
@@ -653,13 +653,15 @@ describe("useAgentSettingsMutationController", () => {
       });
     });
 
-    expect(mockedRemoveSkillFromGateway).toHaveBeenCalledWith({
-      skillKey: "browser",
-      source: "openclaw-workspace",
-      baseDir: "/tmp/workspace/skills/browser",
-      workspaceDir: "/tmp/workspace",
-      managedSkillsDir: "/tmp/skills",
-    });
+    expect(mockedRemoveSkillFromGateway).toHaveBeenCalledWith(
+      expect.objectContaining({
+        skillKey: "browser",
+        source: "openclaw-workspace",
+        baseDir: "/tmp/workspace/skills/browser",
+        workspaceDir: "/tmp/workspace",
+        managedSkillsDir: "/tmp/skills",
+      })
+    );
     expect(ctx.enqueueConfigMutation).toHaveBeenCalledWith(
       expect.objectContaining({ kind: "update-skill-setup" })
     );
diff --git a/tests/unit/useSettingsRouteController.test.ts b/tests/unit/useSettingsRouteController.test.ts
index 0ab4d8b..dec3806 100644
--- a/tests/unit/useSettingsRouteController.test.ts
+++ b/tests/unit/useSettingsRouteController.test.ts
@@ -276,7 +276,7 @@ describe("useSettingsRouteController", () => {
     });
 
     await waitFor(() => {
-      expect(ctx.replace).toHaveBeenCalledWith("/agents");
+      expect(ctx.replace).toHaveBeenCalledWith("/");
     });
   });