# pi backend notes (the extension)

- **Worktree isolation**: native — the runner creates the worktree and delivers
  a handoff artifact (default for every worker dispatch). Workers never touch
  the main checkout.
- **Ticks**: custom-role messages (`sendMessage`, NON-triggering `followUp` —
  AUTOPILOT-125) gated on the interactive TUI session, `/orchestrate` loaded,
  not busy, not compacting, plus a cooldown. A tick is **RECORDED in the
  transcript and reaches your next turn; it does NOT start one** (it cannot
  claim the agent, so it can neither be refused nor cost the user a prompt). If
  the session sits idle nothing wakes it — re-check state yourself rather than
  waiting to be nudged. **`followUp` only delivers at a turn boundary
  (AUTOPILOT-65)**: a tick or a worker/reviewer completion notification cannot
  interrupt a turn that is still issuing tool calls — it queues until the turn
  ends. The queue store and `status.json` update immediately and correctly
  regardless; only the NOTIFICATION is delivery-gated. A long, uninterrupted
  stretch of your own tool calls (observed: 45–60 min of a multi-step git
  operation) can leave completed workers unreported and fleet-occupancy beliefs
  stale. Do not wait for the tick: after any such stretch, proactively re-check
  `queue_list` + `subagent status fleet` before trusting or reporting capacity
  (see `prompts/orchestrate.md`'s loop section,
  `docs/AUTOPILOT-65-completion-delivery-yield-gap.md`, and
  `docs/AUTOPILOT-51-tick-audit-gap.md`, "The NON-TRIGGERING tick").
- **Steering**: available for headless detached workers. Requests are written
  to the flat `<asyncDir>/control/steer-requests/<ts13>-<base64url id>.json`
  (there is no per-child `steer-targets/<index>` inbox directory — that was
  AUTOPILOT-62's disproven belief); the ack signal is
  `<asyncDir>/status.json`'s `.steering.recent[]` array, not a
  `steer-acks/<index>/` directory. This is this repo's own hand-rolled
  reimplementation of pi-subagents' internal, unversioned on-disk protocol
  (pi-subagents exports no public steering API). See `src/backends/pi.ts`'s
  "Ack protocol" header comment for the canonical wire-format trace — don't
  re-describe the format here independently; update that comment first if the
  protocol is re-traced, then point back to it.
- **Flagging**: `flag_for_review` is registered by the extension; it appends to
  the reviews log + sends a desktop notification.
- **Per-session toggle**: `/autopilot on|off [in <duration>]|status|capacity`
  gates ticks per session. `off in <duration>` (e.g. `off in 1h30m`, max 24h)
  SCHEDULES the shutdown: autopilot stays ON until the deadline, then flips
  OFF by itself; any explicit on/off cancels; status shows the pending
  deadline; the deadline survives a restart (the enable-gate backstop fires
  it late but never loses it). The queue tools are always available.
- **Detection**: the host marker in the queue-tool descriptions
  (`(pi host)`) is the signal — the `/autopilot` command is just the
  per-session toggle (the opencode plugin registers no commands).