feat(telemetry): instrument renderer failure and CTA events

Add PostHog instrumentation for app failures and user CTAs:
- daemon_failure (machine-readable code on DaemonStatus, IPC-forwarded)
- api_error central interceptor (categorized, IDs stripped)
- terminal_attach_failed (pane error + open timeout)
- CTA triads: task_create, session_kill, settings_save,
  orchestrator_spawn (board/restore_dialog), notification open/read

All events sanitized: project_id hashed, enum-only codes, raw error
messages never sent.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Pritom14

frontend/src/main.ts

@@ -411,6 +411,7 @@ async function refreshDaemonStatus(): Promise<DaemonStatus> {
 		setDaemonStatus({
 			state: "stopped",
 			message: "AO daemon is no longer reachable.",
+			code: "daemon_unreachable",
 		});
 	}
 	return daemonStatus;
@@ -451,6 +452,7 @@ async function startDaemonInner(startEpoch: number): Promise<DaemonStatus> {
 		setDaemonStatus({
 			state: "stopped",
 			message: "AO_DAEMON_COMMAND is not configured; renderer uses loopback REST when available.",
+			code: "not_configured",
 		});
 		return daemonStatus;
 	}
@@ -548,6 +550,7 @@ async function startDaemonInner(startEpoch: number): Promise<DaemonStatus> {
 		setDaemonStatus({
 			state: "error",
 			message: `Bundled AO daemon binary was not found at ${launch.command}. Rebuild the desktop package.`,
+			code: "binary_missing",
 		});
 		return daemonStatus;
 	}
@@ -636,6 +639,7 @@ async function startDaemonInner(startEpoch: number): Promise<DaemonStatus> {
 			state: "ready",
 			port: process.env.AO_PORT ? Number(process.env.AO_PORT) : undefined,
 			message: "Daemon port not confirmed from logs or running.json; assuming the configured port.",
+			code: "port_unconfirmed",
 		});
 	}, PORT_DISCOVERY_TIMEOUT_MS);
 
@@ -644,7 +648,7 @@ async function startDaemonInner(startEpoch: number): Promise<DaemonStatus> {
 		if (daemonProcess !== child) return;
 		daemonProcess = null;
 		if (daemonStoppingProcess === child) daemonStoppingProcess = null;
-		setDaemonStatus({ state: "error", message: error.message });
+		setDaemonStatus({ state: "error", message: error.message, code: "spawn_failed" });
 	});
 
 	child.once("exit", (code, signal) => {
@@ -655,6 +659,9 @@ async function startDaemonInner(startEpoch: number): Promise<DaemonStatus> {
 		setDaemonStatus({
 			state: "stopped",
 			message: signal ? `Daemon exited with ${signal}` : `Daemon exited with code ${code ?? "unknown"}`,
+			code: "exited",
+			exitCode: code,
+			signal,
 		});
 	});
 

frontend/src/renderer/components/NewTaskDialog.test.tsx

@@ -3,8 +3,9 @@ import userEvent from "@testing-library/user-event";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { NewTaskDialog } from "./NewTaskDialog";
 
-const { postMock } = vi.hoisted(() => ({
+const { postMock, captureMock } = vi.hoisted(() => ({
 	postMock: vi.fn(),
+	captureMock: vi.fn().mockResolvedValue(undefined),
 }));
 
 vi.mock("../lib/api-client", () => ({
@@ -19,8 +20,13 @@ vi.mock("../lib/api-client", () => ({
 	},
 }));
 
+vi.mock("../lib/telemetry", () => ({
+	captureRendererEvent: captureMock,
+}));
+
 beforeEach(() => {
 	postMock.mockReset();
+	captureMock.mockClear();
 	postMock.mockResolvedValue({ data: { session: { id: "task-1" } }, error: undefined });
 });
 
@@ -56,5 +62,33 @@ describe("NewTaskDialog", () => {
 
 		expect(await screen.findByText("Title and brief are required.")).toBeInTheDocument();
 		expect(postMock).not.toHaveBeenCalled();
+		expect(captureMock).not.toHaveBeenCalled();
+	});
+
+	it("emits the task_create triad on success", async () => {
+		render(<NewTaskDialog open projectId="proj-1" onCreated={vi.fn()} onOpenChange={vi.fn()} />);
+
+		await userEvent.type(screen.getByLabelText("Title"), "Fix fallback renderer");
+		await userEvent.type(screen.getByLabelText("Brief"), "Restore the fallback renderer.");
+		await userEvent.click(screen.getByRole("button", { name: "Start task" }));
+
+		await waitFor(() =>
+			expect(captureMock).toHaveBeenCalledWith("ao.renderer.task_create_succeeded", { project_id: "proj-1" }),
+		);
+		expect(captureMock).toHaveBeenCalledWith("ao.renderer.task_create_requested", { project_id: "proj-1" });
+		expect(captureMock).not.toHaveBeenCalledWith("ao.renderer.task_create_failed", expect.anything());
+	});
+
+	it("emits task_create_failed when the daemon rejects the task", async () => {
+		postMock.mockResolvedValue({ data: undefined, error: { message: "no such project" } });
+		render(<NewTaskDialog open projectId="proj-1" onCreated={vi.fn()} onOpenChange={vi.fn()} />);
+
+		await userEvent.type(screen.getByLabelText("Title"), "Fix fallback renderer");
+		await userEvent.type(screen.getByLabelText("Brief"), "Restore the fallback renderer.");
+		await userEvent.click(screen.getByRole("button", { name: "Start task" }));
+
+		expect(await screen.findByText("no such project")).toBeInTheDocument();
+		expect(captureMock).toHaveBeenCalledWith("ao.renderer.task_create_failed", { project_id: "proj-1" });
+		expect(captureMock).not.toHaveBeenCalledWith("ao.renderer.task_create_succeeded", expect.anything());
 	});
 });

frontend/src/renderer/components/NewTaskDialog.tsx

@@ -5,6 +5,7 @@ import { Button } from "./ui/button";
 import { Input } from "./ui/input";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "./ui/select";
 import { apiClient, apiErrorMessage } from "../lib/api-client";
+import { captureRendererEvent } from "../lib/telemetry";
 import type { AgentProvider } from "../types/workspace";
 
 type NewTaskDialogProps = {
@@ -57,6 +58,7 @@ export function NewTaskDialog({ open, projectId, onCreated, onOpenChange }: NewT
 
 		setIsSubmitting(true);
 		setError(undefined);
+		void captureRendererEvent("ao.renderer.task_create_requested", { project_id: projectId });
 		try {
 			const { data, error: apiError } = await apiClient.POST("/api/v1/sessions", {
 				body: {
@@ -70,9 +72,11 @@ export function NewTaskDialog({ open, projectId, onCreated, onOpenChange }: NewT
 			});
 			if (apiError) throw new Error(apiErrorMessage(apiError, "Unable to start task"));
 			if (!data?.session?.id) throw new Error("Task creation returned no session");
+			void captureRendererEvent("ao.renderer.task_create_succeeded", { project_id: projectId });
 			onCreated(data.session.id);
 			onOpenChange(false);
 		} catch (err) {
+			void captureRendererEvent("ao.renderer.task_create_failed", { project_id: projectId });
 			setError(err instanceof Error ? err.message : "Unable to start task");
 		} finally {
 			setIsSubmitting(false);

frontend/src/renderer/components/NotificationCenter.tsx

@@ -10,6 +10,7 @@ import {
 import { aoBridge } from "../lib/bridge";
 import { formatTimeCompact } from "../lib/format-time";
 import { createNotificationsTransport, type NotificationDTO, unreadNotificationsQueryKey } from "../lib/notifications";
+import { captureRendererEvent } from "../lib/telemetry";
 import { cn } from "../lib/utils";
 import {
 	DropdownMenu,
@@ -37,11 +38,13 @@ export function NotificationCenter({ style }: NotificationCenterProps) {
 		(notification: NotificationDTO) => {
 			const target = notification.target;
 			if (target.kind === "pr" && target.prUrl) {
+				void captureRendererEvent("ao.renderer.notification_opened", { target: "pr" });
 				window.open(target.prUrl, "_blank", "noopener,noreferrer");
 				return;
 			}
 			const sessionId = target.sessionId || notification.sessionId;
 			if (!sessionId) return;
+			void captureRendererEvent("ao.renderer.notification_opened", { target: "session" });
 			if (notification.projectId) {
 				void navigate({
 					to: "/projects/$projectId/sessions/$sessionId",
@@ -66,6 +69,7 @@ export function NotificationCenter({ style }: NotificationCenterProps) {
 
 	const markOneRead = async (id: string) => {
 		setActionError(null);
+		void captureRendererEvent("ao.renderer.notification_marked_read", { scope: "single" });
 		try {
 			await markRead.mutateAsync(id);
 		} catch (error) {
@@ -75,6 +79,7 @@ export function NotificationCenter({ style }: NotificationCenterProps) {
 
 	const markAll = async () => {
 		setActionError(null);
+		void captureRendererEvent("ao.renderer.notification_marked_read", { scope: "all" });
 		try {
 			await markAllRead.mutateAsync();
 		} catch (error) {

frontend/src/renderer/components/ProjectSettingsForm.tsx

@@ -2,6 +2,7 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useState } from "react";
 import type { components } from "../../api/schema";
 import { apiClient, apiErrorMessage } from "../lib/api-client";
+import { captureRendererEvent } from "../lib/telemetry";
 import { workspaceQueryKey } from "../hooks/useWorkspaceQuery";
 import { RequiredAgentField } from "./CreateProjectAgentSheet";
 import { DashboardSubhead } from "./DashboardSubhead";
@@ -81,6 +82,7 @@ function SettingsBody({ project, projectId, onSaved }: { project: Project; proje
 
 	const mutation = useMutation({
 		mutationFn: async () => {
+			void captureRendererEvent("ao.renderer.settings_save_requested", { project_id: projectId });
 			// PUT replaces the whole config; merge the edited fields over what loaded
 			// so we don't drop env/symlinks/postCreate the form doesn't expose.
 			const next: ProjectConfig = {
@@ -103,11 +105,15 @@ function SettingsBody({ project, projectId, onSaved }: { project: Project; proje
 			if (error) throw new Error(apiErrorMessage(error));
 		},
 		onSuccess: () => {
+			void captureRendererEvent("ao.renderer.settings_save_succeeded", { project_id: projectId });
 			setSavedAt(Date.now());
 			setValidationError(null);
 			void queryClient.invalidateQueries({ queryKey: ["project", projectId] });
 			onSaved();
 		},
+		onError: () => {
+			void captureRendererEvent("ao.renderer.settings_save_failed", { project_id: projectId });
+		},
 	});
 
 	return (

frontend/src/renderer/components/RestoreUnavailableDialog.tsx

@@ -3,6 +3,7 @@ import { Loader2 } from "lucide-react";
 import { useState } from "react";
 import { Button } from "./ui/button";
 import { spawnOrchestrator } from "../lib/spawn-orchestrator";
+import { captureRendererEvent } from "../lib/telemetry";
 import { isOrchestratorSession } from "../types/workspace";
 import type { WorkspaceSession } from "../types/workspace";
 
@@ -21,11 +22,23 @@ export function RestoreUnavailableDialog({ open, session, onOpenChange, onRecrea
 	const recreate = async () => {
 		setBusy(true);
 		setError(undefined);
+		void captureRendererEvent("ao.renderer.orchestrator_spawn_requested", {
+			project_id: session.workspaceId,
+			source: "restore_dialog",
+		});
 		try {
 			const id = await spawnOrchestrator(session.workspaceId, true);
+			void captureRendererEvent("ao.renderer.orchestrator_spawn_succeeded", {
+				project_id: session.workspaceId,
+				source: "restore_dialog",
+			});
 			onOpenChange(false);
 			onRecreated(id);
 		} catch (err) {
+			void captureRendererEvent("ao.renderer.orchestrator_spawn_failed", {
+				project_id: session.workspaceId,
+				source: "restore_dialog",
+			});
 			setError(err instanceof Error ? err.message : "Failed to create orchestrator");
 		} finally {
 			setBusy(false);

frontend/src/renderer/components/SessionsBoard.tsx

@@ -9,6 +9,7 @@ import { DashboardSubhead } from "./DashboardSubhead";
 import { OrchestratorIcon } from "./icons";
 import { NewTaskDialog } from "./NewTaskDialog";
 import { spawnOrchestrator } from "../lib/spawn-orchestrator";
+import { captureRendererEvent } from "../lib/telemetry";
 import { prDiffSummary, sessionPRDisplaySummaries } from "../lib/pr-display";
 import { cn } from "../lib/utils";
 import { PRAttentionPanel, PRStatusStrip } from "./PRSummaryDisplay";
@@ -103,13 +104,18 @@ export function SessionsBoard({ projectId }: SessionsBoardProps) {
 			return;
 		}
 		setIsSpawning(true);
+		void captureRendererEvent("ao.renderer.orchestrator_spawn_requested", { project_id: projectId, source: "board" });
 		try {
 			const sessionId = await spawnOrchestrator(projectId);
+			void captureRendererEvent("ao.renderer.orchestrator_spawn_succeeded", { project_id: projectId, source: "board" });
 			await queryClient.invalidateQueries({ queryKey: workspaceQueryKey });
 			void navigate({
 				to: "/projects/$projectId/sessions/$sessionId",
 				params: { projectId, sessionId },
 			});
+		} catch (error) {
+			void captureRendererEvent("ao.renderer.orchestrator_spawn_failed", { project_id: projectId, source: "board" });
+			throw error;
 		} finally {
 			setIsSpawning(false);
 		}

frontend/src/renderer/components/ShellTopbar.tsx

@@ -249,16 +249,21 @@ export function TopbarKillButton({ session }: { session: WorkspaceSession }) {
 
 	const kill = useMutation({
 		mutationFn: async () => {
+			void captureRendererEvent("ao.renderer.session_kill_requested", { project_id: session.workspaceId });
 			const { error: apiError } = await apiClient.POST("/api/v1/sessions/{sessionId}/kill", {
 				params: { path: { sessionId: session.id } },
 			});
 			if (apiError) throw new Error(apiErrorMessage(apiError));
 		},
 		onSuccess: () => {
+			void captureRendererEvent("ao.renderer.session_kill_succeeded", { project_id: session.workspaceId });
 			setConfirming(false);
 			void queryClient.invalidateQueries({ queryKey: workspaceQueryKey });
 		},
-		onError: (e) => setError(e instanceof Error ? e.message : "Kill failed"),
+		onError: (e) => {
+			void captureRendererEvent("ao.renderer.session_kill_failed", { project_id: session.workspaceId });
+			setError(e instanceof Error ? e.message : "Kill failed");
+		},
 	});
 
 	if (confirming) {

frontend/src/renderer/hooks/useTerminalSession.ts

@@ -10,6 +10,7 @@
 import { useQueryClient } from "@tanstack/react-query";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { getApiBaseUrl } from "../lib/api-client";
+import { captureRendererEvent } from "../lib/telemetry";
 import { createTerminalMux, muxUrlFromApiBase, type TerminalMux } from "../lib/terminal-mux";
 import type { WorkspaceSession } from "../types/workspace";
 import { workspaceQueryKey } from "./useWorkspaceQuery";
@@ -212,6 +213,7 @@ export function useTerminalSession(session: WorkspaceSession | undefined, option
 				terminal.writeln(`\r\n\x1b[2m[terminal error] ${message}\x1b[0m`);
 				setError(message);
 				transition("error");
+				void captureRendererEvent("ao.renderer.terminal_attach_failed", { reason: "pane_error" });
 				invalidateWorkspaces();
 			}),
 			mux.onConnectionChange((connectionState) => {
@@ -267,6 +269,11 @@ export function useTerminalSession(session: WorkspaceSession | undefined, option
 		r.openTimer = setTimeout(() => {
 			if (!isCurrentAttachment(generation, handle, mux)) return;
 			r.openTimer = null;
+			// Only the first timeout of a reattach sequence is reported; the
+			// backoff loop retrying against a restarting daemon is not news.
+			if (r.attempts === 0) {
+				void captureRendererEvent("ao.renderer.terminal_attach_failed", { reason: "open_timeout" });
+			}
 			transition("reattaching");
 			teardownMux();
 			scheduleReattach();