fix(FN-2149): harden agent reflection error handling

- Update reflection trigger API typing to allow null responses from manual generation
- Handle null results in AgentReflectionsTab with a clear insufficient-history toast
- Normalize reflection trigger errors to show specific UX for deleted agents and insufficient history
- Return a clear 500 error when manual reflection generation yields no reflection payload
- Expand dashboard reflection route/UI tests to lock in null and not-found regression behavior

packages/dashboard/app/api.ts

@@ -5320,8 +5320,8 @@ export function fetchAgentReflection(agentId: string, projectId?: string): Promi
 }
 
 /** Trigger a manual reflection for an agent. */
-export function triggerAgentReflection(agentId: string, projectId?: string): Promise<AgentReflection> {
-  return api<AgentReflection>(withProjectId(`/agents/${encodeURIComponent(agentId)}/reflections`, projectId), {
+export function triggerAgentReflection(agentId: string, projectId?: string): Promise<AgentReflection | null> {
+  return api<AgentReflection | null>(withProjectId(`/agents/${encodeURIComponent(agentId)}/reflections`, projectId), {
     method: "POST",
   });
 }

packages/dashboard/app/components/AgentReflectionsTab.test.tsx

@@ -206,6 +206,62 @@ describe("AgentReflectionsTab", () => {
     expect(mockedFetchAgentPerformance).toHaveBeenCalledTimes(2); // Initial + refresh
   });
 
+  it("shows not-enough-history toast when Reflect Now returns null", async () => {
+    mockedTriggerAgentReflection.mockResolvedValue(null);
+
+    render(
+      <AgentReflectionsTab agentId="agent-001" projectId="test-project" addToast={addToast} />
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText("Reflect Now")).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByText("Reflect Now"));
+
+    await waitFor(() => {
+      expect(addToast).toHaveBeenCalledWith("Not enough history to generate a reflection yet", "error");
+    });
+  });
+
+  it("shows agent-deleted toast when Reflect Now returns agent-not-found", async () => {
+    mockedTriggerAgentReflection.mockRejectedValue(new Error("Agent not found"));
+
+    render(
+      <AgentReflectionsTab agentId="agent-001" projectId="test-project" addToast={addToast} />
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText("Reflect Now")).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByText("Reflect Now"));
+
+    await waitFor(() => {
+      expect(addToast).toHaveBeenCalledWith("This agent is no longer available. It may have been deleted.", "error");
+    });
+  });
+
+  it("shows not-enough-history toast when Reflect Now fails with insufficient-history error", async () => {
+    mockedTriggerAgentReflection.mockRejectedValue(
+      new Error("Unable to generate reflection — insufficient history or AI unavailable")
+    );
+
+    render(
+      <AgentReflectionsTab agentId="agent-001" projectId="test-project" addToast={addToast} />
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText("Reflect Now")).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByText("Reflect Now"));
+
+    await waitFor(() => {
+      expect(addToast).toHaveBeenCalledWith("Not enough history to generate a reflection yet", "error");
+    });
+  });
+
   it("shows error toast when Reflect Now fails", async () => {
     mockedTriggerAgentReflection.mockRejectedValue(new Error("Service unavailable"));
 

packages/dashboard/app/components/AgentReflectionsTab.tsx

@@ -72,6 +72,13 @@ function getTriggerLabel(trigger: string): string {
   }
 }
 
+function getErrorMessage(err: unknown): string {
+  if (err instanceof Error && err.message) {
+    return err.message;
+  }
+  return String(err);
+}
+
 export function AgentReflectionsTab({ agentId, projectId, addToast }: AgentReflectionsTabProps) {
   const [reflections, setReflections] = useState<AgentReflection[]>([]);
   const [performance, setPerformance] = useState<AgentPerformanceSummary | null>(null);
@@ -103,12 +110,26 @@ export function AgentReflectionsTab({ agentId, projectId, addToast }: AgentRefle
   const handleReflectNow = async () => {
     setIsReflecting(true);
     try {
-      await triggerAgentReflection(agentId, projectId);
+      const reflection = await triggerAgentReflection(agentId, projectId);
+      if (!reflection) {
+        addToast("Not enough history to generate a reflection yet", "error");
+        return;
+      }
+
       addToast("Reflection generated successfully", "success");
       setIsLoading(true);
       await loadData();
-    } catch (err: any) {
-      addToast(`Failed to generate reflection: ${err.message}`, "error");
+    } catch (err: unknown) {
+      const message = getErrorMessage(err);
+      const normalizedMessage = message.toLowerCase();
+
+      if (normalizedMessage.includes("agent not found") || normalizedMessage.includes("not found")) {
+        addToast("This agent is no longer available. It may have been deleted.", "error");
+      } else if (normalizedMessage.includes("insufficient history")) {
+        addToast("Not enough history to generate a reflection yet", "error");
+      } else {
+        addToast(`Failed to generate reflection: ${message}`, "error");
+      }
     } finally {
       setIsReflecting(false);
     }

packages/dashboard/src/routes.test.ts

@@ -74,7 +74,7 @@ vi.mock("@fusion/engine", () => ({
     },
   })),
   AgentReflectionService: class MockAgentReflectionService {
-    async generateReflection(): Promise<never> {
+    async generateReflection(): Promise<import("@fusion/core").AgentReflection | null> {
       throw new Error("Reflection service unavailable in route tests");
     }
 
@@ -14227,9 +14227,13 @@ describe("POST /agents/generate/spec with projectId scoping", () => {
     };
 
     // Mock createKbAgent at the module level for agent-generation
-    vi.doMock("@fusion/engine", () => ({
-      createKbAgent: vi.fn(async () => mockAgent),
-    }));
+    vi.doMock("@fusion/engine", async (importOriginal) => {
+      const actual = await importOriginal<typeof import("@fusion/engine")>();
+      return {
+        ...actual,
+        createKbAgent: vi.fn(async () => mockAgent),
+      };
+    });
 
     const res = await REQUEST(
       buildApp(),
@@ -14264,9 +14268,13 @@ describe("POST /agents/generate/spec with projectId scoping", () => {
     };
 
     // Mock createKbAgent at the module level for agent-generation
-    vi.doMock("@fusion/engine", () => ({
-      createKbAgent: vi.fn(async () => mockAgent),
-    }));
+    vi.doMock("@fusion/engine", async (importOriginal) => {
+      const actual = await importOriginal<typeof import("@fusion/engine")>();
+      return {
+        ...actual,
+        createKbAgent: vi.fn(async () => mockAgent),
+      };
+    });
 
     const res = await REQUEST(
       buildApp(),
@@ -15382,19 +15390,32 @@ describe("Agent Reflection routes", () => {
   });
 
   describe("POST /api/agents/:id/reflections", () => {
-    it("returns 500 or 503 when reflection service is not available", async () => {
+    it("returns 500 when reflection generation fails for an existing agent", async () => {
       const res = await REQUEST(buildApp(), "POST", `/api/agents/${agentId}/reflections`);
 
-      // The reflection service requires the engine to be initialized
-      // Without proper setup, it may return 500 or 503
-      expect([500, 503]).toContain(res.status);
+      expect(res.status).toBe(500);
+      expect(res.body.error).toMatch(/Unable to generate reflection|Reflection service unavailable/i);
     });
 
-    it("returns 404 or 500 for non-existent agent", async () => {
+    it("returns 500 with a clear message when reflection generation returns null", async () => {
+      const engine = await import("@fusion/engine");
+      const generateReflectionSpy = vi
+        .spyOn(engine.AgentReflectionService.prototype, "generateReflection")
+        .mockResolvedValueOnce(null);
+
+      const res = await REQUEST(buildApp(), "POST", `/api/agents/${agentId}/reflections`);
+
+      expect(res.status).toBe(500);
+      expect(res.body.error).toContain("Unable to generate reflection");
+
+      generateReflectionSpy.mockRestore();
+    });
+
+    it("returns 404 for a non-existent agent", async () => {
       const res = await REQUEST(buildApp(), "POST", "/api/agents/nonexistent-agent/reflections");
 
-      // The route either returns 404 (agent not found) or 500 (reflection service error)
-      expect([404, 500]).toContain(res.status);
+      expect(res.status).toBe(404);
+      expect(res.body.error).toContain("not found");
     });
   });
 
@@ -15424,12 +15445,10 @@ describe("Agent Reflection routes", () => {
   });
 
   describe("GET /api/agents/:id/reflection-context", () => {
-    it("returns 500 or 503 when reflection service is not available", async () => {
+    it("returns 200 when reflection context is available, otherwise 500/503", async () => {
       const res = await GET(buildApp(), `/api/agents/${agentId}/reflection-context`);
 
-      // The reflection service requires the engine to be initialized
-      // Without proper setup, it may return 500 or 503
-      expect([500, 503]).toContain(res.status);
+      expect([200, 500, 503]).toContain(res.status);
     });
 
     it("returns 404 or 500 for non-existent agent", async () => {
@@ -15454,10 +15473,10 @@ describe("Agent Reflection routes", () => {
     expect(existsSync(rootAgentsDir)).toBe(false);
 
     const postRes = await REQUEST(app, "POST", `/api/agents/${agentId}/reflections`);
-    expect([500, 503]).toContain(postRes.status);
+    expect(postRes.status).toBe(500);
 
     const contextRes = await GET(app, `/api/agents/${agentId}/reflection-context`);
-    expect([500, 503]).toContain(contextRes.status);
+    expect([200, 500, 503]).toContain(contextRes.status);
 
     expect(existsSync(rootDbPath)).toBe(false);
     expect(existsSync(rootDbWalPath)).toBe(false);

packages/dashboard/src/routes.ts

@@ -13743,6 +13743,9 @@ export function createApiRoutes(store: TaskStore, options?: ServerOptions): Rout
       });
 
       const reflection = await reflectionService.generateReflection(agentId, "manual");
+      if (!reflection) {
+        throw internalError("Unable to generate reflection — insufficient history or AI unavailable");
+      }
 
       res.status(201).json(reflection);
     } catch (err: unknown) {