Repository navigation
v0.22.2
🐑 Pi Herdsman v0.22.2
Cleaner project lifecycles. Clearer orchestration boundaries.
v0.22.2 fixes stale Manager project assignments after worktree removal and makes orchestration-focused Leads coordination-only by default.
It also formalizes Herdsman's performance and efficiency principles.
Manager now reconciles project assignments with Git worktrees
Previously, removing a project's worktree could leave its Manager assignment behind.
In one reported case, four removed worktrees remained visible as paused projects, even though their checkouts no longer existed.
The underlying problem was that project retirement relied on observing Herdr's removal event. Those events are transient, so a missed notification could leave stale assignments indefinitely.
v0.22.2 makes checkout existence the authoritative lifecycle boundary.
Herdsman now reconciles project assignments against Git's verified worktree inventory during Manager startup, project inspection, resume, and worktree-removal handling.
An assignment is retired when either:
- Herdr confirms successful removal of its worktree.
- Authoritative Git evidence establishes that its checkout no longer exists.
This also allows previously orphaned assignments to be cleaned up after restarting Manager.
What remains protected
A stopped Lead, closed workspace, or replaced Manager does not end an assignment while its worktree still exists.
Similarly, incomplete inventory, ambiguous repository identity, unavailable topology, or an in-progress worktree operation cannot justify deletion.
Retirement targets only the exact assignment and its pending project messages.
Git branches, Pi sessions, conversation history, and unrelated projects are preserved.
Important
Project recovery semantics have changed.
Once a worktree is confirmed absent and its assignment is retired, resume_project no longer recreates that old assignment.
You can still delegate new managed work from the remaining Git branch.
An unavailable or temporarily unobservable worktree is not treated as deleted.
The implementation preserves exact identity checks and uses the existing assignment lock to protect concurrent changes.
No new polling service, cleanup command, or persistent project-tracking subsystem was introduced.
Reported by: @boadij · Issue: #330
Contributor: @boadij · PR: #334
Architecture: ADR 0019, introduced in #331
Orchestrator Leads are now coordination-only by default
Herdsman's Lead execution profiles were introduced in v0.22.0.
This release makes their default responsibilities more explicit.
Both bundled orchestration-focused definitions now use:
tools: []This applies to:
orchestrator-lead
managed-lead
Ordinary file inspection, editing, and execution tools are no longer included by default.
Instead, these Leads coordinate work through Herdsman's required Agent, peer, and supervisor tools.
The distinction is now:
Flexible Lead
→ normal Pi tools + Herdsman coordination
Orchestrate Lead
→ Herdsman coordination tools by default
Managed Lead
→ Herdsman coordination tools by default
Still fully configurable
The new defaults do not prevent direct execution when it is useful.
Project or global definition overrides can explicitly enable ordinary tools:
---
name: orchestrator-lead
tools: [read, ls, find, grep, bash]
---The important distinction is:
- Omitted
tools: preserve or inherit the existing tool selection. - Explicit
tools: []: select no ordinary tools. - Explicit tool list: select the specified ordinary tools.
Mandatory Herdsman coordination tools remain available independently of these ordinary tool policies.
The flexible-lead definition remains unchanged and continues to preserve Pi's normal tool environment.
Note
These defaults intentionally favor delegation over direct execution.
Even small inspection tasks may now require an Agent call. Users who prefer hybrid workflows can enable the ordinary tools they need through definition overrides.
This change does not alter Manager authority, Agent ownership, or the underlying orchestration runtime.
Contributor: @boadij · PR: #336
Performance and efficiency become explicit product principles
Recent performance work reduced unnecessary mailbox polling, redundant fleet observation, and repeated Agent snapshot traversal.
v0.22.2 records the broader principle behind those improvements in Herdsman's product philosophy.
Performance and efficiency should be considered across:
- Runtime resource consumption.
- Model-facing interactions and unnecessary turns.
- Development and maintenance workflows.
The guiding preference is to eliminate avoidable work before introducing optimization machinery.
Performance improvements should remain proportional to demonstrated costs and must not compromise correctness, reliability, security, or recovery.
This is a documentation change, not another runtime optimization.
Contributor: @boadij · PR: #335
Architecture: worktree-backed project assignments
ADR 0019 formalizes the updated Manager project lifecycle.
A ProjectAssignment represents currently managed checkout-backed work, not a permanent record of every project previously undertaken.
The decision distinguishes three important conditions:
Worktree exists
→ Assignment remains active or paused
Worktree absence is verified
→ Retire assignment and pending messages
Worktree status is uncertain
→ Preserve assignment
This supersedes the event-only retirement and missing-checkout recovery decisions previously documented in ADR 0013.
The existing exact-session Manager authority model and explicit /takeover mechanism remain unchanged.
Contributor: @boadij · PR: #331
Compatibility and validation
The tested runtime baseline remains:
Pi 1.1.0
Herdr 0.9.3
The Manager reconciliation changes include regression coverage for missing checkouts, ambiguous identity, concurrent assignment changes, and deferred cleanup.
The final implementation passed:
- 906 tests passed, 1 skipped
- Build and package audit
- Ubuntu, macOS, and Windows CI
- Container CI
The PR also reports an earlier native worktree-removal smoke test. The original incident's precise event-callback failure mechanism remains unproven.
Release
Full changelog: v0.22.1...v0.22.2
