/overseer

argument-hint: "[--pilot <epic> [<epic> ...] [--autonomy L0|L1|L2|L3] [--max-agents N] | --auto | mission-context | path/to/prd.md]"

Batch-review all agents in review/complete state, or pilot one or many epics end-to-end as a continuous loop under a single global agent budget.

/jat:overseer — Batch Agent Review + Multi-Epic Pilot

> **CRITICAL: NEVER report task state from memory.** Before ANY status report, decision, banner, or state assertion, run `jt epic-status <epic> --json` to get ground-truth state. The overseer's context window compresses — your memory of what happened is unreliable. The DB + signal files + tmux are the source of truth.

> **CRITICAL: review detection needs THREE sources OR'd together — any one firing is enough. Never make one of them primary.** > Each source fails independently, and each failure is silent: > - **Signal file** — a `jat-signal review` emit can silently fail, leaving the file reading `working` while the worker sits done (DeepPebble: idle 20h that way). > - **Pane text** — `tmux capture-pane` grep for `READY FOR REVIEW|Run /jat:complete` only sees the *visible* pane. ANY later output scrolls the banner away and the agent becomes undetectable. On 2026-07-30 an overseer's own steer message pushed the banner out of view; the completer polled a live agent for 30+ min and never fired. **Steering an agent must not make it uncompletable.** Scan deep scrollback (`-S -200`), and once an agent is *observed* at review, LATCH it until its task leaves review — do not re-derive from a volatile pane every poll. > - **DB status** — `jt show <id> --json` is authoritative for "is it still in_progress", but says nothing about whether the worker is done and waiting. > > So: **(signal says review) OR (pane says review) OR (task in_progress + agent idle)** → treat as review-ready. Cross-check DB status before acting, never as the gate for noticing. This applies to the pilot poll loop (Step 3D/3E) and batch review (Step 2/3) below. > > **Corollary — a claim you cannot act on is worse than no claim.** `jat-wave-complete` takes a wave-ownership claim, and `jat-close-guard` then blocks the worker's own `jt close` until the claim holder sends a `kind=complete` approval. If the holder cannot *detect* review, it never approves and the worker can never self-close: a hard deadlock in which the agent looks idle, the completer looks healthy, and nothing moves (live specimen 2026-07-30, MistySlate383/jat-htt4z — resolved only by killing the completer to release the claim). A manual `jat-send <Agent> --complete` may NOT rescue it: the approval is matched against the claim's recorded actor string, and a mismatch fails silently. Check with `jat-close-guard <task> --agent <Agent>` (exit 0 = clear) before assuming your approval landed.

**Usage:**

• `/jat:overseer` — scan all sessions, review pending cards, recommend actions
• `/jat:overseer --auto` — same but auto-execute approvals (only escalations pause for human)
• `/jat:overseer ~/code/myproject/docs/PRD.md` — load a PRD as mission context
• `/jat:overseer "We're shipping the payments module this sprint."` — inline mission context
• `/jat:overseer --pilot <epic>` — engage agent-driven pilot; run continuous loop until epic complete
• `/jat:overseer --pilot <epic> --autonomy L1` — pilot at L1 (auto-approve clean tasks)
• `/jat:overseer --pilot <epicA> <epicB> <epicC>` — ONE pilot session drives MANY epics under one global budget
• `/jat:overseer --pilot <epicA> <epicB> --autonomy L2 --max-agents 6` — multi-epic pilot, global cap of 6 live workers
• `--max-agents N` — GLOBAL live-worker cap across ALL piloted epics (default 6; the pilot session itself is +1 and excluded). `--max-sessions` is a legacy alias.

---

--pilot <epic> [<epic> ...] — Agent-Driven Multi-Epic Pilot Loop

When invoked as `/jat:overseer --pilot <epic> [<epic> ...]` (with optional `--autonomy` and `--max-agents`):

**The agent (you) IS the overseer pilot — for the whole SET of epics.** This mode runs a full continuous decision loop across every piloted epic at once: rank the global ready set → spawn workers at Sonnet under one GLOBAL budget → wait for review signals → research & judge → accept/redirect/escalate → verify each epic as its children finish → repeat until ALL epics are done. **Do NOT engage the server-side trigger loop** — engaging it alongside the agent loop causes double-spawning. The agent drives the epics end-to-end using Fable-tier judgment and optional WebSearch/WebFetch research.

**Three load-bearing properties (the make-or-break requirements):**

1. **One GLOBAL budget.** `--max-agents` caps live workers across ALL piloted epics combined — never per-epic. The fleet ceiling is a global constraint; this is the one place it's enforced. 2. **Stateless per iteration.** Every loop re-derives the ready set, in-flight workers, and budget usage from `jt` + tmux + lease state — NEVER from cached memory. A killed pilot session resumes cleanly by re-running the same `/jat:overseer --pilot ...` invocation. 3. **Lease-conflict-skip.** A spawn refused with `File lease conflict` means SKIP that task and try the next ranked ready task. Never stall the loop on a conflicted task — it re-enters the ready set on a later iteration once the conflicting lease is released.

> **How it differs from batch `/jat:overseer`:** The batch mode reviews agents that are already running. > The pilot loop spawns each wave itself, waits via an inline poll loop (30s intervals, single Bash call), > then judges each worker with the full `assembleEpicPilotContext` bundle.

---

Step 1: Parse arguments

Extract from the invocation args:

• `<epic> [<epic> ...]` — ONE OR MORE epic task IDs, positional (e.g. `jst-fxport jat-jt054 jat-9qg68`)
• `--autonomy <level>` — L0 (default), L1, L2, or L3
• `--max-agents <n>` — GLOBAL live-worker cap across all piloted epics (default 6). The pilot

session itself is +1 on top of this and is NOT counted against the ca