pan-start git:20261101.4758883A

Immutable. This exact content never changes and is served at /api/v1/blob/5a84cea527c1bf44.

---
name: pan-start
description: "pan start <id> — 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 <issue-id>
```

## 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 <id>` 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 <id>` 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 <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 <id>` refuses to spawn until you run `pan unpause <id>`.
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 <id>` refuses until you
run `pan untroubled <id>`; `--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 <label|auto>` 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 <tags>` 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 <id>` (continue that session) or `pan reset-session <id>` (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 <id>` — create an execution plan before starting
- `pan show <id>` — inspect agent state while it works
- `pan tell <id>` — send a message to the running agent
- `pan done <id>` — signal the agent has completed its work