--- name: pan-start description: "pan start — spawn a work agent for an issue in its own terminal-backend pane and workspace" triggers: - pan start - start working on - work on issue - spawn agent - create workspace allowed-tools: - Bash - Read --- # pan start Run the command now: ```bash pan start ``` ## Usage ``` pan start PAN-123 # Spawn agent for issue PAN-123 pan start MIN-456 # Works with any tracker prefix pan start PAN-123 --force # Clear a paused agent gate and start anyway pan start PAN-123 --host # Break-glass: bypass workspace Docker stack-health gate pan reset-session PAN-123 # Clear mutable saved-session pointers before a fresh start pan start PAN-123 --fresh # Start fresh only when no resumable session remains pan start PAN-123 --harness codex # Explicitly use the Codex harness pan start PAN-123 --model gpt-5.6-sol --effort high # Pin the work model and Claude Code effort pan start PAN-123 --plan-model k3 --model k3 # Auto-plan AND work on Kimi k3 pan start PAN-123 --remote --tier durable # Remote Fly.io workspace with persistent volume pan start PAN-123 --remote --tier ephemeral # Remote Fly.io workspace that winds down on stale heartbeat pan start PAN-123 --machine desk # Start the issue agent on the linked machine "desk" pan start PAN-123 --machine auto --needs docker --push-first # Auto placement by load, docker required ``` ## What It Does `pan start ` is the single paved-road entry point: it takes an issue from whatever state it is in to running work. - **No plan exists** — `pan start` auto-plans (non-interactive), materializes xBRIEF tasks, and starts the work agent when planning finalizes. - **Plan exists** — `pan start` creates the workspace if needed and spawns the work agent from the existing xBRIEF and xBRIEF tasks. - **Already running** — `pan start` exits 0 with a no-op message naming `pan tell ` for messaging and the attach command for the agent's backend (Herdr or tmux). - **Swarm active** — the bare parent agent is the foreman. `pan start` attaches to or restores that foreman instead of refusing because slot agents exist; it never creates a competing serial parent. Planning depth is controlled by `--plan`: ```bash pan start PAN-1071 --plan interactive # Q&A planning first, then work pan start PAN-1071 --plan auto # non-interactive planning, then work (default) pan start PAN-1071 --plan skip # synthesize a minimal xBRIEF and xBRIEF tasks, then work ``` The default planning mode comes from `planning.default_mode` in `~/.overdeck/config.yaml`; the shipped default is `auto`. The legacy `--auto` flag is deprecated and is now an alias for `--plan skip`. `--model` and `--harness` apply to this run only (PAN-3917: the per-issue policy record they used to persist to is gone, and nothing is derivable from it). When this start also kicks off planning, the auto-start handoff — including the deferred retry and stack-rebuild paths — runs the work agent on that `--model`: it is stored with that planning cycle's own auto-start consent (PAN-3022) and is not reused once the handoff spends the consent claim. A later bare `pan start` restart keeps that model as resume continuity (same as any other restart); only `--fresh` or a pending `pan reset-session` drops it back to the project/global config default. Swarm policy (foreman vs. serial work) and review mode (`quick`/`full`/`none`) are likewise project/global `config.yaml` settings now, not per-issue overrides or `pan start` flags. When this start also kicks off planning (no plan exists yet), `--plan-model ` overrides the planning agent's model for that session only — it is a one-shot override, not persisted policy, and it never changes the work agent's model (`--model`). On that same unplanned path, `--harness` and `--effort` configure the planning agent, not the work agent the auto-start handoff later spawns. If an agent is paused, `pan start ` refuses to spawn until you run `pan unpause `. Use `--force` only when you intentionally want to clear that pause gate and start anyway. If an agent is troubled (three failures in ten minutes), `pan start ` refuses until you run `pan untroubled `; `--force` clears the troubled gate and starts anyway. For projects with workspace Docker configured, `pan start` checks stack health before spawning. Use `--host` only as an explicit break-glass override; interactive shells always prompt, while non-interactive callers must pass `--yes` to confirm. `--machine ` starts the issue agent on a linked machine instead (PAN-4651): that machine needs a project with the same repository and starts from its view of `origin`, so unpushed commits in the issue's local workspace refuse the start unless you pass `--push-first` or `--ignore-unpushed`. `--machine auto` picks a machine by load (`--needs ` restricts it to machines with those capability tags) and prints the choice; when it picks this machine the normal local start runs. `--machine fly` is refused until PAN-4652. If a stopped agent has a saved Claude session, `pan start` refuses and points you to `pan resume ` (continue that session) or `pan reset-session ` (clear mutable session pointers before a new start). `--fresh` runs the lifecycle guard before it wipes local agent state, so a refused command leaves the state directory intact. Append-only durable session records are not abandoned by either command; if one still makes the session resumable, resume it rather than deleting or inventing durable-plane markers. ## Slow or hanging workspace prep Workspace preparation bounds its slow external phases with these default budgets: | Phase | Budget | Timeout behavior | | --- | ---: | --- | | `state-reconcile` | 60s | Fail fast | | `sync-main` | 240s | Warn and continue to spawn | | `tracker-context` | 60s | Warn, use empty tracker context, and continue to spawn | | `spawn` | 600s | Fail fast | Ora spinner text updates render only on a TTY, so non-interactive callers receive plain progress lines and a heartbeat every 15 seconds while a phase is still running: ```text [prep] still running: sync-main (45s elapsed) ``` A fail-fast timeout exits with the step name and budget. A degraded timeout warns and keeps preparation moving toward agent spawn. Supervisors that invoke `pan start` non-interactively should allow an outer budget of at least 300 seconds under load; RUN-35 completed after earlier 120-second and 200-second supervisors timed out while workspace preparation was still making progress. ## When to Use - Starting work on a new issue - Launching an agent after planning is complete ## See Also - `pan plan ` — create an execution plan before starting - `pan show ` — inspect agent state while it works - `pan tell ` — send a message to the running agent - `pan done ` — signal the agent has completed its work