Affected Repositories

• PyAutoBrain (primary)
• PyAutoMind

Branch Survey

Suggested branch: feature/autonomous-orchestrators-p3b (both repos); worktree root ~/Code/PyAutoLabs-wt/autonomous-orchestrators-p3b/

Implementation Steps

1. agents/conductors/batch/worker_template.md (new) — the worker prompt with {task_path}, {brief_path}, {lease_dir}, {task} placeholders: /start_dev <path> --auto; end at the deliverable (no timers); read the brief record; never commit to PyAutoMind directly (3c); write <lease_dir>/<task>.done with the PR URLs on finish.
2. _orchestrator.py — session_command(task, prompt_path, brief_path, lease_dir, mode) → argv (claude --bg --name shift:<task> --session-id <uuid> --permission-mode <mode> <prompt>); RealSpawner.spawn runs it from the workspace root, parses the printed short id, returns agent_id + session_id (no pid).
3. Liveness backend: one claude agents --json --all call per tick (AgentsView); _reap consults it for real leases (running → heartbeat; blocked → stalled_since, parked after STALL_GRACE_S; done → .done marker decides released vs crashed; absent → gone/crashed), pid liveness kept for fake leases.
4. Token accounting: transcript_tokens(session_id) sums usage (input, output, cache-creation) from ~/.claude/projects/*/<session_id>.jsonl; counters gain tokens; spawn refused once tokens >= token-budget.
5. _brief.py — optional worker-mode: ∈ {auto, dontAsk, acceptEdits} (default auto; bypassPermissions refused by name) and sandbox: yes; real spawn refused unless sandbox: yes (lifted by 3c).
6. Docs: conductor AGENTS.md "The watcher" (real mode, stall parking, token budget); PyAutoMind batches/AGENTS.md documents worker-mode: / sandbox:.
7. Tests: template/argv never bare; fake AgentsView drives running/blocked/done/gone transitions; token refusal; validator rules. Live witness (opt-in PYAUTO_ORCHESTRATOR_LIVE=1): one sandbox worker end to end, then claude rm.

Key Files

• PyAutoBrain/agents/conductors/batch/_orchestrator.py, _brief.py, new worker_template.md, AGENTS.md
• PyAutoBrain/tests/test_orchestrator_dispatch.py (new)
• PyAutoMind/batches/AGENTS.md

Autonomous orchestrators phase 3b: real dispatch — session template, claude --bg workers, liveness, token budget

Type: feature
Target: PyAutoBrain
Repos:

• PyAutoBrain
• PyAutoMind
  Difficulty: medium
  Autonomy: human-required
  Priority: high
  Status: formalised
  Filed: 2026-11-03
  Epic: autonomous-orchestrators
  Phase: 3
  Consequence: judge
  Witness: batch dispatch builds the worker command from the orchestrator's session template (sources, bootstrap, brief path, /start_dev <path> --auto, the end-at-deliverable contract) and a unit test asserts it is never bare; with PYAUTO_ORCHESTRATOR_FAKE=0 on the laptop one claude --bg worker is spawned against a no-op sandbox prompt, appears in claude agents --json, is attachable, and its lease heartbeat follows its liveness; the brief's token-budget: is decremented from the worker's final usage and the N+1th spawn past it is refused; the worker permission mode is declared (decided with the human) and a worker that hits a prompt is reported, not left stalled; pytest PyAutoBrain/tests -q green
  Review-minutes: 20
  Unattended: never
  Lane: local-dev

Parent: draft/feature/pyautobrain/autonomous_orchestrators_epic.md; slice of phase 3 (slicing: complete/2026/11/autonomous-orchestrators-p3a.md, prompt section "Slicing"; 3a shipped as PyAutoBrain#556).

Real workers on top of the 3a watcher core. Decide with the human, at plan time, the worker permission mode (a --bg worker that hits a permission prompt stalls silently: auto mode plus the repo allowlists is the starting proposal). Recheck the CLI facts first (claude --help, claude agents --help; 2.1.316 on 2026-11-03 had --bg, attach, logs, stop, rm, respawn, and agents --json [--all] [--cwd]). Whether --bg sessions show in the desktop app is phase 4's first witness, not this one.