v1.1 — agent-first surface

The post-launch follow-up that completes Praetor's intended agent-orchestration story. Everything in v1.0 still works the same way; this release adds the primary structured surface for agents and the operational ergonomics for long-running drains.

What's new since v1.0.0

Agent-first interfaces

MCP server (`praetor mcp`) — Praetor now exposes its core operations as MCP tools via the official Anthropic Python SDK. 9 tools cover the full task lifecycle: `init_workspace`, `list_tasks`, `get_task`, `next_ready`, `add_task`, `start_drain`, `merge_task`, `merge_all_pending`, `get_logs`. Each tool is a thin shim over existing core services — no business logic in the MCP layer, so the CLI and MCP can never drift apart.

Claude Code plugin bundle (`plugin/` in the repo) — install Praetor as a Claude Code plugin and a long-running orchestrator session can drive the queue without shelling out. Plugin manifest validated by `claude plugin validate`.

`praetor status --json` — structured task output for scripts, CI pipelines, and non-MCP callers. Same 14-key shape per task that MCP `list_tasks` returns; both code paths share the serializer so output is byte-identical.

Watch mode

`praetor loop` — long-running command that continuously drains the queue and picks up new task files as they appear. Uses `watchdog` for filesystem events with a polling fallback. Graceful SIGINT (Ctrl-C) finishes in-flight tasks and stops dispatching new ones. `--once` for "drain everything then quit even if more tasks arrive later."

Recovery + visibility

`praetor reset ` — recover tasks stuck in `running`, `failed`, `blocked`, or `merge_failed` by transitioning them back to `pending`. With `--clean-worktree`, also removes the associated `.praetor/worktrees//` directory and the `praetor/` branch. With `--all-stale`, finds every task currently in `running` state and resets them (handy after a crash). Closes #6.

Progress events — `drain_queue` now accepts an `on_event: EventCallback` parameter and emits typed `RunnerEvent` objects at every transition: `drain_started`, `task_dispatched`, `task_completed`, `task_failed`, `task_pending_merge`, `merge_started`, `merge_succeeded`, `merge_failed`, `drain_finished`. CLI subscribes by default and prints to stderr — `praetor run --max-parallel 4` and `praetor loop` now show live progress instead of going silent. Closes #10.

Schema and bug-fix follow-ups

• Forward-compat schema additions — `tokens_used`, `cost_usd` on `TaskResult`; `retry`, `priority`, `env`, `context_files` on `Task`; `cancelled` in `TaskStatus`. All runner-ignored, all defaulted. Lands now so any task file written today survives v2+ feature work without migration. (Issues #13 secrets, #15 run history, #16 `praetor cancel`, #17 cost/tokens still open as runtime wiring.)
• ClaudeCodeAdapter passes `--permission-mode auto` — the previous version silently hung in non-interactive mode because Claude refused to write files without permission grants. Surfaced by dogfood against real `claude -p`.
• `praetor init` manages `.gitignore` — automatically writes `.praetor/` to the repo's `.gitignore` and prints a follow-up note telling the user to commit it. Without this, the first parallel run fails because the merge service correctly refuses a dirty base repo. Surfaced by dogfood.

Backward compatibility

All changes are additive. v1.0.0 task files load and run unchanged in v1.1. Sequential mode (`--max-parallel 1`, the default) preserves its v0/v1.0 behavior exactly — no worktrees, no runner-owned commits, no merge step. The event callback is optional; existing callers that don't pass `on_event` see no change.

Install

```bash

PyPI

pipx install praetor-cli # gets 1.1.0

Homebrew (macOS)

brew tap sid-valecha/praetor
brew install praetor # gets 1.1.0
```

Tests

115 → 158 tests passing on Python 3.11 + 3.12 (v1.0.0 shipped with 115).

Still open for future work

These are tracked but not landed in v1.1:

• #4 P14 conflict detection at dispatch time
• #5 post-merge verification on the base branch
• #7 worktree disk-pressure cleanup flag
• #8 multi-OS CI matrix (Linux only today)
• #9 coverage reporting
• #13 secrets / env runtime wiring (schema field exists)
• #14 blocked task auto-unblock on dep retry
• #15 run history (`.praetor/runs/`)
• #16 `praetor cancel` command (status enum exists)
• #17 cost/tokens runner integration (TaskResult fields exist)

Acknowledgements

Bugs found by Haiku subagent dogfood sessions against real `claude -p` — caught two shipping bugs that 158 unit tests with MockAdapter never could have. Engineering work coordinated through the agent-driven workflow that Praetor itself is built for.

v1.0 — parallel execution + merge strategy

The first stable milestone. Praetor now drains task DAGs in parallel using per-task git worktrees, with verify-gated commits and configurable merge strategy.

What's new

Parallel execution

• praetor run --max-parallel N drains eligible siblings concurrently
• Each task gets its own git worktree at .praetor/worktrees/<task-id>/
• parallel_ok: false tasks run alone (pool drains first)
• Worktree-collision recovery: failed tasks don't crash the run
• Stale-running detection at startup (fails closed with recovery guidance)

Merge strategy

• manual default — verified tasks park as pending_merge for human integration
• auto opt-in via --merge-strategy auto on praetor run, or per-task via frontmatter
• praetor merge [TASK_ID...] [--all] [--retry] for selective or batch integration
• git merge --no-ff --no-edit with deterministic merge message
• Idempotent (already-merged branches return success); abort hygiene on conflict

Other

• New TaskStatus values: pending_merge, merge_failed (recoverable; does not cascade)
• praetor status shows new statuses with distinct styles
• praetor add --parallel-ok/--no-parallel-ok --merge-strategy auto|manual
• Runner now owns task commits (git add -A && git commit after verify passes, in the worktree)
• GitHub Actions CI on Python 3.11 + 3.12 + Docker build
• 115 tests across unit + integration + e2e
• Design spec published in roadmap.md

Backward compatibility

Sequential mode (--max-parallel 1, the default) preserves v0 behavior exactly — no worktrees, no runner-owned commits, no merge step. Existing v0 workflows continue to work without changes.

Install

PyPI publication is the next polish step. For now, install from source:

```bash
pipx install git+https://github.com/sid-valecha/praetor.git@v1.0
```

Then verify:

```bash
praetor --help
```

Honest limitations

These items are intentionally not in v1; each tracked as a GitHub issue:

• Conflict detection at dispatch time (#4)
• Post-merge verification on the base branch (#5)
• Recovery UX (`praetor reset`) for stale-running tasks (#6)
• Worktree cleanup flag for disk-pressure management (#7)
• Multi-OS CI matrix (#8)
• Code coverage reporting (#9)
• CLI progress / event callback API (#10)

Acknowledgements

v1's design picks were sharpened through Codex-based consultation passes (model: gpt-5.5, effort: high) before each implementation phase — auto-vs-manual merge default, worktree model expansion, and the runner-owned-commit pattern all came from those reviews. Implementation dispatches were verified independently before commit.