docs(04-02): complete AgentManager port & events plan

Tasks completed: 2/2
- Define AgentManager port interface and domain types
- Add agent lifecycle events to events module

SUMMARY: .planning/phases/04-agent-lifecycle/04-02-SUMMARY.md

.planning/ROADMAP.md

@@ -90,9 +90,10 @@ Plans:
 **Plans**: TBD
 
 Plans:
-- [ ] 04-01: TBD
-- [ ] 04-02: TBD
-- [ ] 04-03: TBD
+- [ ] 04-01: Agent Schema & Repository (Wave 1)
+- [x] 04-02: AgentManager Port & Events (Wave 1)
+- [ ] 04-03: AgentManager Adapter (Wave 2)
+- [ ] 04-04: tRPC Integration & CLI Commands (Wave 3)
 
 ### Phase 5: Task Dispatch
 **Goal**: Task status visibility, dependency-ordered dispatch, work queue, agent message queue
@@ -138,7 +139,7 @@ Phases execute in numeric order: 1 → 1.1 → 2 → 3 → 4 → 5 → 6 → 7
 | 1.1. Hexagonal Architecture | 6/6 | Complete | 2026-01-30 |
 | 2. Data Layer | 2/2 | Complete | 2026-01-30 |
 | 3. Git Integration | 2/2 | Complete | 2026-01-30 |
-| 4. Agent Lifecycle | 0/? | Not started | - |
+| 4. Agent Lifecycle | 1/4 | In progress | - |
 | 5. Task Dispatch | 0/? | Not started | - |
 | 6. Coordination | 0/? | Not started | - |
 | 7. File System UI | 0/? | Not started | - |

.planning/STATE.md

@@ -5,23 +5,23 @@
 See: .planning/PROJECT.md (updated 2026-01-30)
 
 **Core value:** Coordinate multiple Claude Code agents without losing track or stepping on each other.
-**Current focus:** Phase 3 — Git Integration
+**Current focus:** Phase 4 — Agent Lifecycle
 
 ## Current Position
 
-Phase: 3 of 8 (Git Integration)
-Plan: 2 of 2 in current phase
-Status: Phase complete
-Last activity: 2026-01-30 — Completed 03-02-PLAN.md
+Phase: 4 of 8 (Agent Lifecycle)
+Plan: 1 of 4 in current phase
+Status: In progress
+Last activity: 2026-01-30 — Completed 04-02-PLAN.md
 
-Progress: ███████░ 55%
+Progress: ███████░ 57%
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 15
+- Total plans completed: 16
 - Average duration: 3 min
-- Total execution time: 45 min
+- Total execution time: 47 min
 
 **By Phase:**
 
@@ -31,9 +31,10 @@ Progress: ███████░ 55%
 | 1.1 | 6/6 | 15 min | 3 min |
 | 2 | 2/2 | 8 min | 4 min |
 | 3 | 2/2 | 7 min | 4 min |
+| 4 | 1/4 (04-02) | 2 min | 2 min |
 
 **Recent Trend:**
-- Last 5 plans: 02-01 (3 min), 02-02 (5 min), 03-01 (2 min), 03-02 (5 min)
+- Last 5 plans: 02-02 (5 min), 03-01 (2 min), 03-02 (5 min), 04-02 (2 min)
 - Trend: Steady
 
 ## Accumulated Context
@@ -63,6 +64,10 @@ Recent decisions affecting current work:
 - 03-01: Four git events for full worktree lifecycle (create, remove, merge, conflict)
 - 03-02: Worktrees stored in .cw-worktrees directory within repository
 - 03-02: createTestRepo() helper for git integration tests
+- 04-02: AgentManager as PORT interface following hexagonal pattern
+- 04-02: Human-readable agent names (gastown, chinatown) in addition to IDs
+- 04-02: AgentStatus includes 'waiting_for_input' for AskUserQuestion pauses
+- 04-02: Five agent events covering full lifecycle
 
 ### Pending Todos
 
@@ -81,5 +86,5 @@ None yet.
 ## Session Continuity
 
 Last session: 2026-01-30
-Stopped at: Completed 03-02-PLAN.md — WorktreeManager adapter with tests
+Stopped at: Completed 04-02-PLAN.md — AgentManager port interface and events
 Resume file: None

.planning/phases/04-agent-lifecycle/04-02-SUMMARY.md

@@ -0,0 +1,106 @@
+---
+phase: 04-agent-lifecycle
+plan: 02
+subsystem: agent
+tags: [agent, port, interface, events, hexagonal]
+
+# Dependency graph
+requires:
+  - phase: 03-git-integration
+    provides: WorktreeManager port interface pattern
+provides:
+  - AgentManager port interface
+  - Agent lifecycle domain events (spawned, stopped, crashed, resumed, waiting)
+  - AgentInfo, AgentResult, SpawnAgentOptions types
+affects: [04-agent-lifecycle, 05-task-dispatch]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - Port interface pattern for AgentManager (same as EventBus, WorktreeManager)
+
+key-files:
+  created:
+    - src/agent/types.ts
+    - src/agent/index.ts
+  modified:
+    - src/events/types.ts
+    - src/events/index.ts
+
+key-decisions:
+  - "AgentManager as PORT interface following hexagonal pattern"
+  - "Human-readable agent names (gastown, chinatown) in addition to IDs"
+  - "AgentStatus includes 'waiting_for_input' for AskUserQuestion pauses"
+  - "Five agent events covering full lifecycle"
+
+patterns-established:
+  - "Port interface pattern for AgentManager - same as EventBus and WorktreeManager"
+
+# Metrics
+duration: 2 min
+completed: 2026-01-30
+---
+
+# Phase 4 Plan 02: AgentManager Port & Events Summary
+
+**AgentManager port interface and 5 agent lifecycle events following hexagonal architecture pattern**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-01-30T18:58:13Z
+- **Completed:** 2026-01-30T18:59:55Z
+- **Tasks:** 2
+- **Files modified:** 4
+
+## Accomplishments
+
+- AgentManager port interface with spawn, stop, list, get, getByName, resume, getResult methods
+- AgentInfo type with session persistence support (sessionId for CLI resume)
+- SpawnAgentOptions with human-readable names and task assignment
+- Five agent lifecycle events: AgentSpawned, AgentStopped, AgentCrashed, AgentResumed, AgentWaiting
+- All types properly exported from barrel files
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Define AgentManager port interface and domain types** - `8888970` (feat)
+2. **Task 2: Add agent lifecycle events to events module** - `ddc6f3b` (feat)
+
+## Files Created/Modified
+
+- `src/agent/types.ts` - AgentManager port interface, AgentInfo, AgentResult, SpawnAgentOptions types
+- `src/agent/index.ts` - Barrel export for agent module
+- `src/events/types.ts` - Five agent lifecycle events added to DomainEventMap
+- `src/events/index.ts` - Export new agent event types
+
+## Decisions Made
+
+1. **AgentManager as PORT interface** - Follows same hexagonal pattern as EventBus and WorktreeManager
+2. **Human-readable agent names** - Agents have names (e.g., 'gastown') in addition to UUIDs for better UX
+3. **AgentStatus includes 'waiting_for_input'** - Distinct status when agent pauses on AskUserQuestion
+4. **Five agent events** - AgentSpawned, AgentStopped, AgentCrashed, AgentResumed, AgentWaiting cover full lifecycle
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+- Port interface ready for adapter implementation in 04-03
+- Events ready for emission from AgentManager adapter
+- All types align with DISCOVERY.md research findings
+
+---
+*Phase: 04-agent-lifecycle*
+*Completed: 2026-01-30*