From eff02f5ee58a6c6a31547b785ae55daa321b4c0f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 7 Jun 2026 07:29:47 +0000
Subject: [PATCH 1/4] feat: add OpenCode to spawn dialogs and empty-state UI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- SpawnAgentCli type: 'claude' | 'codex' → 'claude' | 'codex' | 'opencode'
- SpawnAgentDialog: adds OpenCode card to the spawn grid (3-col)
- TerminalPane empty state: adds OpenCode quick-spawn button alongside Claude and Codex

UI-only change. No relay package bump, no headless routing.

https://claude.ai/code/session_01KXU1uAUwx3L82TMLnAmU4z
---
 .../src/components/sidebar/SpawnAgentDialog.tsx    |  7 ++++---
 .../src/components/terminal/TerminalPane.tsx       | 14 ++++++++++++--
 src/renderer/src/lib/spawn-agent.ts                |  2 +-
 3 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx b/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx
index 0e99049..4d01dd9 100644
--- a/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx
+++ b/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx
@@ -1,7 +1,7 @@
 import type React from 'react'
 import { useCallback, useEffect, useRef, useState } from 'react'
 import { Loader2, X } from 'lucide-react'
-import { ClaudeIcon, CodexIcon } from '@/components/common/AgentIcons'
+import { ClaudeIcon, CodexIcon, OpenCodeIcon } from '@/components/common/AgentIcons'
 import { listProjectPersonas, spawnProjectAgent, spawnProjectPersona, type SpawnAgentCli } from '@/lib/spawn-agent'
 import type { WorkforcePersona } from '@/lib/ipc'
 import { useProjectStore, type ProjectRoot } from '@/stores/project-store'
@@ -9,7 +9,8 @@ import { useUIStore } from '@/stores/ui-store'
 
 const AGENT_OPTIONS: Array<{ cli: SpawnAgentCli; label: string; Icon: typeof ClaudeIcon }> = [
   { cli: 'claude', label: 'Claude', Icon: ClaudeIcon },
-  { cli: 'codex', label: 'Codex', Icon: CodexIcon }
+  { cli: 'codex', label: 'Codex', Icon: CodexIcon },
+  { cli: 'opencode', label: 'OpenCode', Icon: OpenCodeIcon }
 ]
 
 export function SpawnAgentDialog(): React.ReactNode {
@@ -207,7 +208,7 @@ export function SpawnAgentDialog(): React.ReactNode {
                   className="h-9 w-full rounded-md border border-[var(--pear-border-subtle)] bg-[var(--pear-bg)] px-3 text-sm text-[var(--pear-text)] outline-none placeholder:text-[var(--pear-text-faint)] focus:border-[var(--pear-accent-dim)] disabled:opacity-50"
                 />
               </div>
-              <div className="grid grid-cols-2 gap-3">
+              <div className="grid grid-cols-3 gap-3">
                 {AGENT_OPTIONS.map(({ cli, label, Icon }) => (
                   <button
                     key={cli}
diff --git a/src/renderer/src/components/terminal/TerminalPane.tsx b/src/renderer/src/components/terminal/TerminalPane.tsx
index 7aa8a08..5f14621 100644
--- a/src/renderer/src/components/terminal/TerminalPane.tsx
+++ b/src/renderer/src/components/terminal/TerminalPane.tsx
@@ -1,7 +1,7 @@
 import type React from 'react'
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { AlertTriangle, ChevronLeft, ChevronRight, Columns2, Loader2, Network, PanelTop, X } from 'lucide-react'
-import { AgentHarnessIcon, ClaudeIcon, CodexIcon } from '@/components/common/AgentIcons'
+import { AgentHarnessIcon, ClaudeIcon, CodexIcon, OpenCodeIcon } from '@/components/common/AgentIcons'
 import { GraphView } from '@/components/graph/GraphView'
 import { ChatComposerInput } from '@/components/chat/ChatComposerInput'
 import { spawnProjectAgent, type SpawnAgentCli } from '@/lib/spawn-agent'
@@ -781,7 +781,7 @@ export function TerminalPane(): React.ReactNode {
           {activeProject ? 'No agents running' : 'No project selected'}
         </p>
         {activeProject ? (
-          <div className="mt-4 grid w-full max-w-[340px] grid-cols-2 gap-3">
+          <div className="mt-4 grid w-full max-w-[420px] grid-cols-3 gap-3">
             <button
               type="button"
               onClick={() => handleSpawn('claude')}
@@ -802,6 +802,16 @@ export function TerminalPane(): React.ReactNode {
               <CodexIcon className="h-4 w-4" />
               <span>{spawningCli === 'codex' ? 'Starting' : 'Codex'}</span>
             </button>
+            <button
+              type="button"
+              onClick={() => handleSpawn('opencode')}
+              disabled={!activeRoot?.pathExists || spawningCli !== null}
+              className="flex items-center justify-center gap-2 rounded-lg border border-[var(--pear-border)] px-4 py-3 text-sm text-[var(--pear-text-dim)] hover:border-[var(--pear-accent-dim)] hover:text-[var(--pear-text)] disabled:cursor-not-allowed disabled:opacity-40"
+              title={activeRoot?.pathExists ? 'Spawn OpenCode' : `Path not found: ${activeRoot?.path || activeProject.rootPath}`}
+            >
+              <OpenCodeIcon className="h-4 w-4" />
+              <span>{spawningCli === 'opencode' ? 'Starting' : 'OpenCode'}</span>
+            </button>
           </div>
         ) : (
           <button
diff --git a/src/renderer/src/lib/spawn-agent.ts b/src/renderer/src/lib/spawn-agent.ts
index 4f20bb7..f908e98 100644
--- a/src/renderer/src/lib/spawn-agent.ts
+++ b/src/renderer/src/lib/spawn-agent.ts
@@ -3,7 +3,7 @@ import { getAgentKey, useAgentStore } from '@/stores/agent-store'
 import { useProjectStore, type Project, type ProjectRoot } from '@/stores/project-store'
 import { useUIStore } from '@/stores/ui-store'
 
-export type SpawnAgentCli = 'claude' | 'codex'
+export type SpawnAgentCli = 'claude' | 'codex' | 'opencode'
 
 function nextAgentName(cli: SpawnAgentCli, projectId: string, liveNames: string[]): string {
   const existingNames = new Set([

From 3b52becd887ef8aef6409f0460e86eacdc6bdf9a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 7 Jun 2026 09:57:34 +0000
Subject: [PATCH 2/4] feat: grey out spawn buttons when CLI is not installed

Adds a broker:check-cli-available IPC that resolves each CLI binary
on PATH using the same augmented-path lookup as preflightSpawnCli.

Both SpawnAgentDialog and TerminalPane check availability on mount
and disable (opacity-40, not-allowed cursor) any spawn button whose
CLI is not found, with a tooltip explaining it is not installed.
Buttons remain enabled until the check resolves so there is no flash.

https://claude.ai/code/session_01KXU1uAUwx3L82TMLnAmU4z
---
 src/main/broker.ts                            |  2 +-
 src/main/ipc-handlers.ts                      |  6 +-
 src/preload/index.ts                          |  2 +
 .../components/sidebar/SpawnAgentDialog.tsx   | 21 ++++++-
 .../src/components/terminal/TerminalPane.tsx  | 62 ++++++++++---------
 src/shared/types/ipc.ts                       |  1 +
 6 files changed, 59 insertions(+), 35 deletions(-)

diff --git a/src/main/broker.ts b/src/main/broker.ts
index 4c584c7..1d32575 100644
--- a/src/main/broker.ts
+++ b/src/main/broker.ts
@@ -81,7 +81,7 @@ function augmentedPath(): string {
   return Array.from(entries).join(delimiter)
 }
 
-function resolveCommandWithAugmentedPath(command: string): string | undefined {
+export function resolveCommandWithAugmentedPath(command: string): string | undefined {
   const resolved = resolveCommandOnPath(command)
   if (resolved) return resolved
 
diff --git a/src/main/ipc-handlers.ts b/src/main/ipc-handlers.ts
index 941d5b0..4276e77 100644
--- a/src/main/ipc-handlers.ts
+++ b/src/main/ipc-handlers.ts
@@ -17,7 +17,7 @@ import {
   addProjectIntegration,
   removeProjectIntegration
 } from './store'
-import { brokerManager } from './broker'
+import { brokerManager, resolveCommandWithAugmentedPath } from './broker'
 import * as git from './git'
 import * as filesystem from './filesystem'
 import * as auth from './auth'
@@ -351,6 +351,10 @@ export function registerIpcHandlers(): void {
     return brokerManager.listAgents(projectId)
   })
 
+  ipcMain.handle('broker:check-cli-available', (_, cli: string) => {
+    return Boolean(resolveCommandWithAugmentedPath(cli))
+  })
+
   ipcMain.handle('broker:list-details', async () => {
     return brokerManager.listBrokerDetails()
   })
diff --git a/src/preload/index.ts b/src/preload/index.ts
index f5c8985..af878ca 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -275,6 +275,8 @@ const api = {
       invoke<void>('broker:release-agent', projectId, name),
     listAgents: (projectId?: string) =>
       invoke<BrokerListAgent[]>('broker:list-agents', projectId),
+    checkCliAvailable: (cli: string) =>
+      invoke<boolean>('broker:check-cli-available', cli),
     listDetails: () => invoke<BrokerDetails[]>('broker:list-details'),
     listEvents: () => invoke<BrokerEventRecord[]>('broker:list-events'),
     shutdown: () => invoke<void>('broker:shutdown'),
diff --git a/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx b/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx
index 4d01dd9..98d2aa5 100644
--- a/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx
+++ b/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx
@@ -3,7 +3,7 @@ import { useCallback, useEffect, useRef, useState } from 'react'
 import { Loader2, X } from 'lucide-react'
 import { ClaudeIcon, CodexIcon, OpenCodeIcon } from '@/components/common/AgentIcons'
 import { listProjectPersonas, spawnProjectAgent, spawnProjectPersona, type SpawnAgentCli } from '@/lib/spawn-agent'
-import type { WorkforcePersona } from '@/lib/ipc'
+import { pear, type WorkforcePersona } from '@/lib/ipc'
 import { useProjectStore, type ProjectRoot } from '@/stores/project-store'
 import { useUIStore } from '@/stores/ui-store'
 
@@ -21,6 +21,7 @@ export function SpawnAgentDialog(): React.ReactNode {
   const [selectedPersonaId, setSelectedPersonaId] = useState('')
   const [customName, setCustomName] = useState('')
   const [error, setError] = useState<string | null>(null)
+  const [cliAvailability, setCliAvailability] = useState<Partial<Record<SpawnAgentCli, boolean>>>({})
   const [selectedRootId, setSelectedRootId] = useState<string | null>(null)
   const project = useProjectStore((s) => s.getActiveProject())
   const defaultRoot = useProjectStore((s) => s.getActiveRoot())
@@ -46,6 +47,16 @@ export function SpawnAgentDialog(): React.ReactNode {
     }
   }, [project, root?.id, selectedRootId])
 
+  useEffect(() => {
+    const clis: SpawnAgentCli[] = ['claude', 'codex', 'opencode']
+    void Promise.all(clis.map(async (cli) => {
+      const available = await pear.broker.checkCliAvailable(cli).catch(() => false)
+      return [cli, available] as const
+    })).then((results) => {
+      setCliAvailability(Object.fromEntries(results))
+    })
+  }, [])
+
   useEffect(() => {
     let cancelled = false
 
@@ -215,9 +226,13 @@ export function SpawnAgentDialog(): React.ReactNode {
                     type="button"
                     autoFocus={cli === 'claude'}
                     onClick={() => handleSpawn(cli)}
-                    disabled={!root?.pathExists || spawning}
+                    disabled={!root?.pathExists || spawning || cliAvailability[cli] === false}
                     className="flex min-h-[92px] flex-col items-center justify-center gap-2 rounded-lg border border-[var(--pear-border)] text-sm text-[var(--pear-text-dim)] hover:border-[var(--pear-accent-dim)] hover:text-[var(--pear-text)] disabled:cursor-not-allowed disabled:opacity-40"
-                    title={root?.pathExists ? `Spawn ${label}` : `Path not found: ${root?.path || project.rootPath}`}
+                    title={
+                      !root?.pathExists ? `Path not found: ${root?.path || project.rootPath}`
+                      : cliAvailability[cli] === false ? `${label} is not installed — run: npm install -g ${cli}`
+                      : `Spawn ${label}`
+                    }
                   >
                     <Icon className="h-6 w-6" />
                     <span>{spawningCli === cli ? 'Starting' : label}</span>
diff --git a/src/renderer/src/components/terminal/TerminalPane.tsx b/src/renderer/src/components/terminal/TerminalPane.tsx
index 5f14621..270dc50 100644
--- a/src/renderer/src/components/terminal/TerminalPane.tsx
+++ b/src/renderer/src/components/terminal/TerminalPane.tsx
@@ -432,6 +432,7 @@ export function TerminalPane(): React.ReactNode {
   const setTerminalLayout = useUIStore((s) => s.setTerminalLayout)
   const [spawningCli, setSpawningCli] = useState<SpawnAgentCli | null>(null)
   const [spawnError, setSpawnError] = useState<string | null>(null)
+  const [cliAvailability, setCliAvailability] = useState<Partial<Record<SpawnAgentCli, boolean>>>({})
   const spawnRequestRef = useRef(false)
   const [burnSummariesByAgentKey, setBurnSummariesByAgentKey] = useState<Record<string, BurnAgentSummary>>({})
   const [splitPage, setSplitPage] = useState(0)
@@ -567,6 +568,16 @@ export function TerminalPane(): React.ReactNode {
     })
   }
 
+  useEffect(() => {
+    const clis: SpawnAgentCli[] = ['claude', 'codex', 'opencode']
+    void Promise.all(clis.map(async (cli) => {
+      const available = await pear.broker.checkCliAvailable(cli).catch(() => false)
+      return [cli, available] as const
+    })).then((results) => {
+      setCliAvailability(Object.fromEntries(results))
+    })
+  }, [])
+
   useEffect(() => {
     let cancelled = false
 
@@ -782,36 +793,27 @@ export function TerminalPane(): React.ReactNode {
         </p>
         {activeProject ? (
           <div className="mt-4 grid w-full max-w-[420px] grid-cols-3 gap-3">
-            <button
-              type="button"
-              onClick={() => handleSpawn('claude')}
-              disabled={!activeRoot?.pathExists || spawningCli !== null}
-              className="flex items-center justify-center gap-2 rounded-lg border border-[var(--pear-border)] px-4 py-3 text-sm text-[var(--pear-text-dim)] hover:border-[var(--pear-accent-dim)] hover:text-[var(--pear-text)] disabled:cursor-not-allowed disabled:opacity-40"
-              title={activeRoot?.pathExists ? 'Spawn Claude' : `Path not found: ${activeRoot?.path || activeProject.rootPath}`}
-            >
-              <ClaudeIcon className="h-4 w-4" />
-              <span>{spawningCli === 'claude' ? 'Starting' : 'Claude'}</span>
-            </button>
-            <button
-              type="button"
-              onClick={() => handleSpawn('codex')}
-              disabled={!activeRoot?.pathExists || spawningCli !== null}
-              className="flex items-center justify-center gap-2 rounded-lg border border-[var(--pear-border)] px-4 py-3 text-sm text-[var(--pear-text-dim)] hover:border-[var(--pear-accent-dim)] hover:text-[var(--pear-text)] disabled:cursor-not-allowed disabled:opacity-40"
-              title={activeRoot?.pathExists ? 'Spawn Codex' : `Path not found: ${activeRoot?.path || activeProject.rootPath}`}
-            >
-              <CodexIcon className="h-4 w-4" />
-              <span>{spawningCli === 'codex' ? 'Starting' : 'Codex'}</span>
-            </button>
-            <button
-              type="button"
-              onClick={() => handleSpawn('opencode')}
-              disabled={!activeRoot?.pathExists || spawningCli !== null}
-              className="flex items-center justify-center gap-2 rounded-lg border border-[var(--pear-border)] px-4 py-3 text-sm text-[var(--pear-text-dim)] hover:border-[var(--pear-accent-dim)] hover:text-[var(--pear-text)] disabled:cursor-not-allowed disabled:opacity-40"
-              title={activeRoot?.pathExists ? 'Spawn OpenCode' : `Path not found: ${activeRoot?.path || activeProject.rootPath}`}
-            >
-              <OpenCodeIcon className="h-4 w-4" />
-              <span>{spawningCli === 'opencode' ? 'Starting' : 'OpenCode'}</span>
-            </button>
+            {([
+              { cli: 'claude', label: 'Claude', Icon: ClaudeIcon },
+              { cli: 'codex', label: 'Codex', Icon: CodexIcon },
+              { cli: 'opencode', label: 'OpenCode', Icon: OpenCodeIcon }
+            ] as const).map(({ cli, label, Icon }) => (
+              <button
+                key={cli}
+                type="button"
+                onClick={() => handleSpawn(cli)}
+                disabled={!activeRoot?.pathExists || spawningCli !== null || cliAvailability[cli] === false}
+                className="flex items-center justify-center gap-2 rounded-lg border border-[var(--pear-border)] px-4 py-3 text-sm text-[var(--pear-text-dim)] hover:border-[var(--pear-accent-dim)] hover:text-[var(--pear-text)] disabled:cursor-not-allowed disabled:opacity-40"
+                title={
+                  !activeRoot?.pathExists ? `Path not found: ${activeRoot?.path || activeProject.rootPath}`
+                  : cliAvailability[cli] === false ? `${label} is not installed`
+                  : `Spawn ${label}`
+                }
+              >
+                <Icon className="h-4 w-4" />
+                <span>{spawningCli === cli ? 'Starting' : label}</span>
+              </button>
+            ))}
           </div>
         ) : (
           <button
diff --git a/src/shared/types/ipc.ts b/src/shared/types/ipc.ts
index 19516bb..9d4a9bc 100644
--- a/src/shared/types/ipc.ts
+++ b/src/shared/types/ipc.ts
@@ -883,6 +883,7 @@ export interface PearAPI {
     unsubscribeAgentChannel: (projectId: string | undefined, name: string, channel: string) => Promise<void>
     releaseAgent: (projectId: string | undefined, name: string) => Promise<void>
     listAgents: (projectId?: string) => Promise<BrokerListAgent[]>
+    checkCliAvailable: (cli: string) => Promise<boolean>
     listDetails: () => Promise<BrokerDetails[]>
     listEvents: () => Promise<BrokerEventRecord[]>
     shutdown: () => Promise<void>

From ed6285cd0b8bcea97400b00c254f56eb024525cf Mon Sep 17 00:00:00 2001
From: "agent-relay-code[bot]" <agent-relay-code[bot]@users.noreply.github.com>
Date: Sun, 7 Jun 2026 10:02:33 +0000
Subject: [PATCH 3/4] chore: apply pr-reviewer fixes for #143

---
 src/main/broker.test.ts                       | 28 ++++++++++++++-
 src/main/broker.ts                            |  9 +++++
 src/main/ipc-handlers.test.ts                 | 35 ++++++++++++++++++-
 src/main/ipc-handlers.ts                      |  4 +--
 .../components/sidebar/SpawnAgentDialog.tsx   |  4 +--
 .../src/components/terminal/TerminalPane.tsx  |  4 +--
 src/renderer/src/lib/spawn-agent.ts           |  6 ++++
 7 files changed, 82 insertions(+), 8 deletions(-)

diff --git a/src/main/broker.test.ts b/src/main/broker.test.ts
index 5d83b63..215b714 100644
--- a/src/main/broker.test.ts
+++ b/src/main/broker.test.ts
@@ -142,7 +142,7 @@ vi.mock('./burn', () => ({
   getPearBurnAgentKey: vi.fn((projectId: string, name: string) => `${projectId}:${name}`)
 }))
 
-import { BrokerManager, resolveAgentRelayMcpCommand } from './broker'
+import { BrokerManager, isCommandAvailableWithAugmentedPath, resolveAgentRelayMcpCommand } from './broker'
 
 const PROJECT_ID = 'project-1'
 const originalMcpCommand = process.env.AGENT_RELAY_MCP_COMMAND
@@ -150,6 +150,7 @@ const originalResourcesPathDescriptor = Object.getOwnPropertyDescriptor(process,
 const originalPlatformDescriptor = Object.getOwnPropertyDescriptor(process, 'platform')
 const originalPublicEnv = process.env.PUBLIC
 const originalProgramDataEnv = process.env.ProgramData
+const originalPathEnv = process.env.PATH
 
 function setProcessPlatform(platform: NodeJS.Platform): void {
   Object.defineProperty(process, 'platform', {
@@ -1159,3 +1160,28 @@ describe('BrokerManager spawnAgent CLI preflight', () => {
     await manager.shutdown()
   })
 })
+
+describe('isCommandAvailableWithAugmentedPath', () => {
+  let tempDir: string | null = null
+
+  afterEach(async () => {
+    process.env.PATH = originalPathEnv
+    if (tempDir) await rm(tempDir, { recursive: true, force: true })
+    tempDir = null
+  })
+
+  it('resolves commands without mutating PATH', async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'pear-cli-path-'))
+    const toolPath = join(tempDir, 'opencode')
+    await writeFile(toolPath, '#!/bin/sh\nexit 0\n')
+    await chmod(toolPath, 0o755)
+    process.env.PATH = tempDir
+
+    expect(isCommandAvailableWithAugmentedPath('opencode')).toBe(true)
+    expect(process.env.PATH).toBe(tempDir)
+  })
+
+  it('returns false for blank commands', () => {
+    expect(isCommandAvailableWithAugmentedPath('   ')).toBe(false)
+  })
+})
diff --git a/src/main/broker.ts b/src/main/broker.ts
index 1d32575..7796039 100644
--- a/src/main/broker.ts
+++ b/src/main/broker.ts
@@ -96,6 +96,15 @@ export function resolveCommandWithAugmentedPath(command: string): string | undef
   return undefined
 }
 
+export function isCommandAvailableWithAugmentedPath(command: string): boolean {
+  const trimmed = command.trim()
+  if (!trimmed) return false
+  return Boolean(resolveCommandOnPath(trimmed, {
+    ...process.env,
+    PATH: augmentedPath()
+  }))
+}
+
 function executableCliPath(input: SpawnPtyInput): string {
   return isAbsolute(input.cli)
     ? input.cli
diff --git a/src/main/ipc-handlers.test.ts b/src/main/ipc-handlers.test.ts
index 4483d74..6d13b82 100644
--- a/src/main/ipc-handlers.test.ts
+++ b/src/main/ipc-handlers.test.ts
@@ -46,6 +46,7 @@ const mock = vi.hoisted(() => {
       detachCloudSandbox: vi.fn(),
       onBrokerEvent: vi.fn()
     },
+    isCommandAvailableWithAugmentedPath: vi.fn(),
     integrationsManager: {
       notifyAgentState: vi.fn(async () => undefined),
       initialSpawnInstructions: vi.fn(),
@@ -101,7 +102,8 @@ vi.mock('./store', () => ({
 }))
 
 vi.mock('./broker', () => ({
-  brokerManager: mock.brokerManager
+  brokerManager: mock.brokerManager,
+  isCommandAvailableWithAugmentedPath: mock.isCommandAvailableWithAugmentedPath
 }))
 
 vi.mock('./git', () => ({}))
@@ -197,3 +199,34 @@ describe('registerIpcHandlers broker:spawn-agent', () => {
     expect(() => structuredClone(result)).not.toThrow()
   })
 })
+
+describe('registerIpcHandlers broker:check-cli-available', () => {
+  beforeEach(() => {
+    mock.handlers.clear()
+    mock.ipcMain.handle.mockClear()
+    mock.ipcMain.on.mockClear()
+    mock.isCommandAvailableWithAugmentedPath.mockReset()
+    registerIpcHandlers()
+  })
+
+  it('returns whether the requested CLI can be resolved', () => {
+    const handler = mock.handlers.get('broker:check-cli-available')
+    expect(handler).toBeTypeOf('function')
+    mock.isCommandAvailableWithAugmentedPath.mockReturnValueOnce(true)
+
+    const result = handler?.({}, 'opencode')
+
+    expect(result).toBe(true)
+    expect(mock.isCommandAvailableWithAugmentedPath).toHaveBeenCalledWith('opencode')
+  })
+
+  it('rejects non-string CLI values', () => {
+    const handler = mock.handlers.get('broker:check-cli-available')
+    expect(handler).toBeTypeOf('function')
+
+    const result = handler?.({}, null)
+
+    expect(result).toBe(false)
+    expect(mock.isCommandAvailableWithAugmentedPath).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/ipc-handlers.ts b/src/main/ipc-handlers.ts
index 4276e77..7d48b85 100644
--- a/src/main/ipc-handlers.ts
+++ b/src/main/ipc-handlers.ts
@@ -17,7 +17,7 @@ import {
   addProjectIntegration,
   removeProjectIntegration
 } from './store'
-import { brokerManager, resolveCommandWithAugmentedPath } from './broker'
+import { brokerManager, isCommandAvailableWithAugmentedPath } from './broker'
 import * as git from './git'
 import * as filesystem from './filesystem'
 import * as auth from './auth'
@@ -352,7 +352,7 @@ export function registerIpcHandlers(): void {
   })
 
   ipcMain.handle('broker:check-cli-available', (_, cli: string) => {
-    return Boolean(resolveCommandWithAugmentedPath(cli))
+    return typeof cli === 'string' && isCommandAvailableWithAugmentedPath(cli)
   })
 
   ipcMain.handle('broker:list-details', async () => {
diff --git a/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx b/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx
index 98d2aa5..0f4a51e 100644
--- a/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx
+++ b/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx
@@ -2,7 +2,7 @@ import type React from 'react'
 import { useCallback, useEffect, useRef, useState } from 'react'
 import { Loader2, X } from 'lucide-react'
 import { ClaudeIcon, CodexIcon, OpenCodeIcon } from '@/components/common/AgentIcons'
-import { listProjectPersonas, spawnProjectAgent, spawnProjectPersona, type SpawnAgentCli } from '@/lib/spawn-agent'
+import { SPAWN_AGENT_CLI_INSTALL_COMMANDS, listProjectPersonas, spawnProjectAgent, spawnProjectPersona, type SpawnAgentCli } from '@/lib/spawn-agent'
 import { pear, type WorkforcePersona } from '@/lib/ipc'
 import { useProjectStore, type ProjectRoot } from '@/stores/project-store'
 import { useUIStore } from '@/stores/ui-store'
@@ -230,7 +230,7 @@ export function SpawnAgentDialog(): React.ReactNode {
                     className="flex min-h-[92px] flex-col items-center justify-center gap-2 rounded-lg border border-[var(--pear-border)] text-sm text-[var(--pear-text-dim)] hover:border-[var(--pear-accent-dim)] hover:text-[var(--pear-text)] disabled:cursor-not-allowed disabled:opacity-40"
                     title={
                       !root?.pathExists ? `Path not found: ${root?.path || project.rootPath}`
-                      : cliAvailability[cli] === false ? `${label} is not installed — run: npm install -g ${cli}`
+                      : cliAvailability[cli] === false ? `${label} is not installed - run: ${SPAWN_AGENT_CLI_INSTALL_COMMANDS[cli]}`
                       : `Spawn ${label}`
                     }
                   >
diff --git a/src/renderer/src/components/terminal/TerminalPane.tsx b/src/renderer/src/components/terminal/TerminalPane.tsx
index 270dc50..d28b46b 100644
--- a/src/renderer/src/components/terminal/TerminalPane.tsx
+++ b/src/renderer/src/components/terminal/TerminalPane.tsx
@@ -4,7 +4,7 @@ import { AlertTriangle, ChevronLeft, ChevronRight, Columns2, Loader2, Network, P
 import { AgentHarnessIcon, ClaudeIcon, CodexIcon, OpenCodeIcon } from '@/components/common/AgentIcons'
 import { GraphView } from '@/components/graph/GraphView'
 import { ChatComposerInput } from '@/components/chat/ChatComposerInput'
-import { spawnProjectAgent, type SpawnAgentCli } from '@/lib/spawn-agent'
+import { SPAWN_AGENT_CLI_INSTALL_COMMANDS, spawnProjectAgent, type SpawnAgentCli } from '@/lib/spawn-agent'
 import { formatTokenCount } from '@/lib/format'
 import { pear, type BurnAgentInput, type BurnAgentSummary, type TerminalAttachMode } from '@/lib/ipc'
 import { getAgentKeyForAgent, type Agent, useAgentStore } from '@/stores/agent-store'
@@ -806,7 +806,7 @@ export function TerminalPane(): React.ReactNode {
                 className="flex items-center justify-center gap-2 rounded-lg border border-[var(--pear-border)] px-4 py-3 text-sm text-[var(--pear-text-dim)] hover:border-[var(--pear-accent-dim)] hover:text-[var(--pear-text)] disabled:cursor-not-allowed disabled:opacity-40"
                 title={
                   !activeRoot?.pathExists ? `Path not found: ${activeRoot?.path || activeProject.rootPath}`
-                  : cliAvailability[cli] === false ? `${label} is not installed`
+                  : cliAvailability[cli] === false ? `${label} is not installed - run: ${SPAWN_AGENT_CLI_INSTALL_COMMANDS[cli]}`
                   : `Spawn ${label}`
                 }
               >
diff --git a/src/renderer/src/lib/spawn-agent.ts b/src/renderer/src/lib/spawn-agent.ts
index f908e98..99ae44f 100644
--- a/src/renderer/src/lib/spawn-agent.ts
+++ b/src/renderer/src/lib/spawn-agent.ts
@@ -5,6 +5,12 @@ import { useUIStore } from '@/stores/ui-store'
 
 export type SpawnAgentCli = 'claude' | 'codex' | 'opencode'
 
+export const SPAWN_AGENT_CLI_INSTALL_COMMANDS: Record<SpawnAgentCli, string> = {
+  claude: 'npm install -g @anthropic-ai/claude-code',
+  codex: 'npm install -g @openai/codex',
+  opencode: 'npm install -g opencode-ai'
+}
+
 function nextAgentName(cli: SpawnAgentCli, projectId: string, liveNames: string[]): string {
   const existingNames = new Set([
     ...liveNames,

From daf84ba22a4de68bc6f71189989a8b8ca7ac8109 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 7 Jun 2026 10:11:20 +0000
Subject: [PATCH 4/4] fix: guard cliAvailability setState against unmount

Both SpawnAgentDialog and TerminalPane lacked a cancelled flag in the
CLI availability useEffect, allowing setCliAvailability to fire on an
unmounted component if the user closed the pane before the IPC round
trip completed. Pattern matches the existing loadPersonas/loadBurnSummaries
guards in the same files.

https://claude.ai/code/session_01KXU1uAUwx3L82TMLnAmU4z
---
 check_types.mjs                               | 25 +++++++++++++++++++
 .../components/sidebar/SpawnAgentDialog.tsx   |  4 ++-
 .../src/components/terminal/TerminalPane.tsx  |  4 ++-
 3 files changed, 31 insertions(+), 2 deletions(-)
 create mode 100644 check_types.mjs

diff --git a/check_types.mjs b/check_types.mjs
new file mode 100644
index 0000000..c52fd6f
--- /dev/null
+++ b/check_types.mjs
@@ -0,0 +1,25 @@
+// Check if Object.fromEntries result is assignable to Partial<Record<SpawnAgentCli, boolean>>
+
+// According to TypeScript:
+// Partial<Record<SpawnAgentCli, boolean>> expands to:
+// { claude?: boolean; codex?: boolean; opencode?: boolean }
+
+// Object.fromEntries returns: { [k: string]: any }
+// In the context of:
+// const results: Array<[SpawnAgentCli, boolean]> = [['claude', true], ...]
+// Object.fromEntries(results) is typed as: { [k: string]: boolean }
+
+// The question: is { [k: string]: boolean } assignable to 
+// { claude?: boolean; codex?: boolean; opencode?: boolean }?
+
+// Answer: YES, because:
+// 1. { [k: string]: boolean } is an index signature that matches ANY string key
+// 2. { claude?: boolean; codex?: boolean; opencode?: boolean } only uses specific keys
+// 3. Any value with an index signature { [k: string]: T } satisfies a type with specific optional properties
+
+console.log("Type check analysis:");
+console.log("Object.fromEntries(results) type: { [k: string]: boolean }");
+console.log("setCliAvailability expects: Partial<Record<SpawnAgentCli, boolean>>");
+console.log("Which expands to: { claude?: boolean; codex?: boolean; opencode?: boolean }");
+console.log("");
+console.log("TypeScript assignability: YES - index signature types are assignable to property-specific types");
diff --git a/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx b/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx
index 0f4a51e..29877dc 100644
--- a/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx
+++ b/src/renderer/src/components/sidebar/SpawnAgentDialog.tsx
@@ -48,13 +48,15 @@ export function SpawnAgentDialog(): React.ReactNode {
   }, [project, root?.id, selectedRootId])
 
   useEffect(() => {
+    let cancelled = false
     const clis: SpawnAgentCli[] = ['claude', 'codex', 'opencode']
     void Promise.all(clis.map(async (cli) => {
       const available = await pear.broker.checkCliAvailable(cli).catch(() => false)
       return [cli, available] as const
     })).then((results) => {
-      setCliAvailability(Object.fromEntries(results))
+      if (!cancelled) setCliAvailability(Object.fromEntries(results))
     })
+    return () => { cancelled = true }
   }, [])
 
   useEffect(() => {
diff --git a/src/renderer/src/components/terminal/TerminalPane.tsx b/src/renderer/src/components/terminal/TerminalPane.tsx
index d28b46b..b8a9148 100644
--- a/src/renderer/src/components/terminal/TerminalPane.tsx
+++ b/src/renderer/src/components/terminal/TerminalPane.tsx
@@ -569,13 +569,15 @@ export function TerminalPane(): React.ReactNode {
   }
 
   useEffect(() => {
+    let cancelled = false
     const clis: SpawnAgentCli[] = ['claude', 'codex', 'opencode']
     void Promise.all(clis.map(async (cli) => {
       const available = await pear.broker.checkCliAvailable(cli).catch(() => false)
       return [cli, available] as const
     })).then((results) => {
-      setCliAvailability(Object.fromEntries(results))
+      if (!cancelled) setCliAvailability(Object.fromEntries(results))
     })
+    return () => { cancelled = true }
   }, [])
 
   useEffect(() => {