feat(09-01): define granular event types, IPC channels, entity getters, and Zustand patch methods

- Add 5 granular event interfaces (TaskUpdated, RunUpdated, ApprovalUpdated, AgentUpdated, BudgetChanged) to DesktopEvent union
- Add 4 entity getter IPC channels (getTask, getAgent, getRun, getApproval) with Zod validation and company ownership checks
- Add getRun method to AppDatabase following existing getTask pattern
- Add 4 preload bridge methods for entity getters
- Add 8 patch/remove methods and refreshBadges to CompanySlice
- Add selective-ipc.test.ts with exhaustive union type tests
- Extend store.test.ts with 14 patch method tests

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/main/database.ts

@@ -1159,6 +1159,17 @@ export class AppDatabase {
     return row ? { ...row, isPrimary: toBoolean(row.isPrimary) } : null;
   }
 
+  getRun(id: string): RunRecord {
+    const row = this.db
+      .prepare(
+        "select id, company_id as companyId, task_id as taskId, agent_id as agentId, workspace_id as workspaceId, connector_id as connectorId, status, summary, error_message as errorMessage, exit_code as exitCode, signal, model, session_display_id as sessionDisplayId, cost_usd as costUsd, unattributed_cost as unattributedCost, started_at as startedAt, finished_at as finishedAt, log_path as logPath, created_at as createdAt, updated_at as updatedAt from runs where id = ?",
+      )
+      .get(id) as RunRecord | undefined;
+    if (!row) throw new Error(`Run not found: ${id}`);
+    row.unattributedCost = Boolean(row.unattributedCost);
+    return row;
+  }
+
   getRunAuthState(runId: string): { id: string; companyId: string; agentId: string; status: RunRecord["status"] } | null {
     const row = this.db
       .prepare("select id, company_id as companyId, agent_id as agentId, status from runs where id = ?")

src/main/ipc-core-read-handlers.ts

@@ -4,6 +4,7 @@ import { z } from "zod";
 import {
   IPC_CHANNELS,
   connectorInputSchema,
+  entityGetterSchema,
   metricsQuerySchema,
   settingsSchema,
 } from "@shared/contracts";
@@ -142,4 +143,58 @@ export function registerCoreReadHandlers({
     if (err) return err;
     return ok(db.getStandupReport(companyId));
   });
+
+  // --- Entity getters for granular IPC updates ---
+
+  registerHandle(IPC_CHANNELS.getTask, (_event, payload) => {
+    const parsed = entityGetterSchema.parse(payload);
+    const companyError = ensureCompanyExists(parsed.companyId);
+    if (companyError) return companyError;
+    try {
+      const task = db.getTask(parsed.id);
+      if (task.companyId !== parsed.companyId) return fail("TASK_NOT_FOUND", "Task not found in current company.");
+      return ok(task);
+    } catch {
+      return fail("TASK_NOT_FOUND", "Task not found.");
+    }
+  });
+
+  registerHandle(IPC_CHANNELS.getAgent, (_event, payload) => {
+    const parsed = entityGetterSchema.parse(payload);
+    const companyError = ensureCompanyExists(parsed.companyId);
+    if (companyError) return companyError;
+    try {
+      const agent = db.getAgent(parsed.id);
+      if (agent.companyId !== parsed.companyId) return fail("AGENT_NOT_FOUND", "Agent not found in current company.");
+      return ok(agent);
+    } catch {
+      return fail("AGENT_NOT_FOUND", "Agent not found.");
+    }
+  });
+
+  registerHandle(IPC_CHANNELS.getRun, (_event, payload) => {
+    const parsed = entityGetterSchema.parse(payload);
+    const companyError = ensureCompanyExists(parsed.companyId);
+    if (companyError) return companyError;
+    try {
+      const run = db.getRun(parsed.id);
+      if (run.companyId !== parsed.companyId) return fail("RUN_NOT_FOUND", "Run not found in current company.");
+      return ok(run);
+    } catch {
+      return fail("RUN_NOT_FOUND", "Run not found.");
+    }
+  });
+
+  registerHandle(IPC_CHANNELS.getApproval, (_event, payload) => {
+    const parsed = entityGetterSchema.parse(payload);
+    const companyError = ensureCompanyExists(parsed.companyId);
+    if (companyError) return companyError;
+    try {
+      const approval = db.getApprovalRecord(parsed.id);
+      if (approval.companyId !== parsed.companyId) return fail("APPROVAL_NOT_FOUND", "Approval not found in current company.");
+      return ok(approval);
+    } catch {
+      return fail("APPROVAL_NOT_FOUND", "Approval not found.");
+    }
+  });
 }

src/preload/index.ts

@@ -82,6 +82,10 @@ const api: DesktopApi = {
     ipcRenderer.invoke("recovery:dismiss", { taskId }),
   recoveryFail: (taskId: string) =>
     ipcRenderer.invoke("recovery:fail", { taskId }),
+  getTask: (input) => ipcRenderer.invoke(IPC_CHANNELS.getTask, input),
+  getAgent: (input) => ipcRenderer.invoke(IPC_CHANNELS.getAgent, input),
+  getRun: (input) => ipcRenderer.invoke(IPC_CHANNELS.getRun, input),
+  getApproval: (input) => ipcRenderer.invoke(IPC_CHANNELS.getApproval, input),
   subscribe: (callback: (event: DesktopEvent) => void) => {
     const listener = (_event: Electron.IpcRendererEvent, payload: DesktopEvent) => callback(payload);
     ipcRenderer.on(IPC_CHANNELS.rendererEvent, listener);

src/renderer/state/slices/company.ts

@@ -1,10 +1,14 @@
 import type { StateCreator } from "zustand";
 import type { AppState } from "../store";
 import type {
+  AgentRecord,
+  ApprovalRecord,
   CompanyMetrics,
   InboxItem,
   ProfileSnapshot,
+  RunRecord,
   StandupReport,
+  TaskRecord,
 } from "@shared/types";
 import type { SidebarBadges } from "@shared/contracts";
 
@@ -24,6 +28,15 @@ export interface CompanySlice {
   setBadges: (badges: SidebarBadges | null) => void;
   setError: (error: string | null) => void;
   refreshSnapshot: () => Promise<void>;
+  patchTask: (task: TaskRecord) => void;
+  removeTask: (taskId: string) => void;
+  patchRun: (run: RunRecord) => void;
+  removeRun: (runId: string) => void;
+  patchAgent: (agent: AgentRecord) => void;
+  removeAgent: (agentId: string) => void;
+  patchApproval: (approval: ApprovalRecord) => void;
+  removeApproval: (approvalId: string) => void;
+  refreshBadges: () => Promise<void>;
 }
 
 export const createCompanySlice: StateCreator<
@@ -31,7 +44,7 @@ export const createCompanySlice: StateCreator<
   [["zustand/immer", never]],
   [],
   CompanySlice
-> = (set) => ({
+> = (set, get) => ({
   snapshot: null,
   currentCompanyId: null,
   companyMetrics: null,
@@ -85,4 +98,85 @@ export const createCompanySlice: StateCreator<
       });
     }
   },
+
+  // --- Granular patch methods for selective IPC updates ---
+
+  patchTask: (task) =>
+    set((state) => {
+      if (!state.snapshot) return;
+      const idx = state.snapshot.tasks.findIndex((t) => t.id === task.id);
+      if (idx >= 0) {
+        state.snapshot.tasks[idx] = task;
+      } else {
+        state.snapshot.tasks.unshift(task);
+      }
+    }),
+  removeTask: (taskId) =>
+    set((state) => {
+      if (!state.snapshot) return;
+      state.snapshot.tasks = state.snapshot.tasks.filter((t) => t.id !== taskId);
+    }),
+
+  patchRun: (run) =>
+    set((state) => {
+      if (!state.snapshot) return;
+      const idx = state.snapshot.runs.findIndex((r) => r.id === run.id);
+      if (idx >= 0) {
+        state.snapshot.runs[idx] = run;
+      } else {
+        state.snapshot.runs.unshift(run);
+      }
+    }),
+  removeRun: (runId) =>
+    set((state) => {
+      if (!state.snapshot) return;
+      state.snapshot.runs = state.snapshot.runs.filter((r) => r.id !== runId);
+    }),
+
+  patchAgent: (agent) =>
+    set((state) => {
+      if (!state.snapshot) return;
+      const idx = state.snapshot.agents.findIndex((a) => a.id === agent.id);
+      if (idx >= 0) {
+        state.snapshot.agents[idx] = agent;
+      } else {
+        state.snapshot.agents.unshift(agent);
+      }
+    }),
+  removeAgent: (agentId) =>
+    set((state) => {
+      if (!state.snapshot) return;
+      state.snapshot.agents = state.snapshot.agents.filter((a) => a.id !== agentId);
+    }),
+
+  patchApproval: (approval) =>
+    set((state) => {
+      if (!state.snapshot) return;
+      const idx = state.snapshot.approvals.findIndex((a) => a.id === approval.id);
+      if (idx >= 0) {
+        state.snapshot.approvals[idx] = approval;
+      } else {
+        state.snapshot.approvals.unshift(approval);
+      }
+    }),
+  removeApproval: (approvalId) =>
+    set((state) => {
+      if (!state.snapshot) return;
+      state.snapshot.approvals = state.snapshot.approvals.filter((a) => a.id !== approvalId);
+    }),
+
+  refreshBadges: async () => {
+    const companyId = get().currentCompanyId;
+    if (!companyId) return;
+    try {
+      const result = await window.agentCompany.getSidebarBadges(companyId);
+      if (result.ok) {
+        set((state) => {
+          state.badges = result.data;
+        });
+      }
+    } catch {
+      /* ignore -- badges are non-critical */
+    }
+  },
 });

src/shared/contracts.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { AgentMessageRecord, AgentMetrics, BrowserActionRecord, CommentRecord, CompanyMetrics, DesktopEvent, InboxItem, OnboardingBootstrapResult, ProfileSnapshot, RunLogChunk, StandupReport } from "./types";
+import type { AgentMessageRecord, AgentMetrics, AgentRecord, ApprovalRecord, BrowserActionRecord, CommentRecord, CompanyMetrics, DesktopEvent, InboxItem, OnboardingBootstrapResult, ProfileSnapshot, RunLogChunk, RunRecord, StandupReport, TaskRecord } from "./types";
 
 export const IPC_CHANNELS = {
   loadSnapshot: "agent-company:load-snapshot",
@@ -73,6 +73,10 @@ export const IPC_CHANNELS = {
   runWorkflow: "agent-company:run-workflow",
   autoAssignTask: "agent-company:auto-assign-task",
   searchMessages: "agent-company:search-messages",
+  getTask: "agent-company:get-task",
+  getAgent: "agent-company:get-agent",
+  getRun: "agent-company:get-run",
+  getApproval: "agent-company:get-approval",
 } as const;
 
 const optionalId = z.preprocess(
@@ -514,6 +518,11 @@ export const autoAssignSchema = z.object({
   companyId: z.string().uuid(),
 });
 
+export const entityGetterSchema = z.object({
+  companyId: z.string().uuid(),
+  id: z.string().uuid(),
+});
+
 export type DesktopResult<T> =
   | { ok: true; data: T }
   | { ok: false; error: { code: string; message: string } };
@@ -592,5 +601,9 @@ export type DesktopApi = {
   recoveryRetry: (taskId: string, agentId: string, companyId: string) => Promise<DesktopResult<null>>;
   recoveryDismiss: (taskId: string) => Promise<DesktopResult<null>>;
   recoveryFail: (taskId: string) => Promise<DesktopResult<null>>;
+  getTask: (input: z.infer<typeof entityGetterSchema>) => Promise<DesktopResult<TaskRecord>>;
+  getAgent: (input: z.infer<typeof entityGetterSchema>) => Promise<DesktopResult<AgentRecord>>;
+  getRun: (input: z.infer<typeof entityGetterSchema>) => Promise<DesktopResult<RunRecord>>;
+  getApproval: (input: z.infer<typeof entityGetterSchema>) => Promise<DesktopResult<ApprovalRecord>>;
   subscribe: (callback: (event: DesktopEvent) => void) => () => void;
 };

src/shared/types.ts

@@ -385,6 +385,35 @@ export interface NotificationClickEvent {
   entityId?: string;
 }
 
+export interface TaskUpdatedEvent {
+  type: "task-updated";
+  taskId: string;
+  action: "created" | "updated" | "deleted";
+}
+
+export interface RunUpdatedEvent {
+  type: "run-updated";
+  runId: string;
+  action: "created" | "status_changed" | "completed";
+}
+
+export interface ApprovalUpdatedEvent {
+  type: "approval-updated";
+  approvalId: string;
+  action: "created" | "decided" | "deleted";
+}
+
+export interface AgentUpdatedEvent {
+  type: "agent-updated";
+  agentId: string;
+  action: "updated" | "paused";
+}
+
+export interface BudgetChangedEvent {
+  type: "budget-changed";
+  companyId: string;
+}
+
 export type DesktopEvent =
   | LogChunkEvent
   | DomainChangedEvent
@@ -394,7 +423,12 @@ export type DesktopEvent =
   | AgentMessageEvent
   | AutomationFiredEvent
   | NewMessageEvent
-  | NotificationClickEvent;
+  | NotificationClickEvent
+  | TaskUpdatedEvent
+  | RunUpdatedEvent
+  | ApprovalUpdatedEvent
+  | AgentUpdatedEvent
+  | BudgetChangedEvent;
 
 export type InboxItemType = "pending_approval" | "failed_run" | "budget_warning" | "blocked_task" | "review_needed" | "agent_message";