---
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*
