Ticket 2: Agent runner design (resolved)

Status: resolved (planning decision)

Isolation: one git worktree and one branch per ticket, branch named from the ticket key.
Runner: a separate local process that starts one agent process per ticket through each agent's native driver, and tracks and reports events.
Concurrency: up to 5 agents in parallel. A 6th ticket queues with a visible label. The cap is a setting.
Shared packages (npm): worktrees share one node_modules through a symlink. Installs through the symlink are blocked and the agent asks first. On approval, that worktree gets a private copy of node_modules for the install, and the others keep the shared set. pnpm is a possible later simplification, not part of v1.
Pause: stops the agent but keeps the worktree, conversation ID, and handoff note, so it can resume.
Cancel: kills the process and deletes the worktree and branch, after a confirmation dialog.
Persistence: a per-ticket state file on disk (ticket state, agent status, conversation ID, worktree path, handoff note).
Restart recovery: agents are marked interrupted on restart and are not resumed automatically. The user restarts them one at a time, to avoid burning the usage limit with several simultaneous restarts.
Cleanup: a done ticket's worktree is kept until its PR is merged, then removed.

Related issues

Step 9: Runner behavior #23: Step 9 builds the worktrees, the five-agent limit, pause, cancel, and restart recovery
Step 5: Ticket state store #19: Step 5 saves the per-ticket state file this decision describes

Generated by Claude Code