v0.25.0

🐑 Pi Herdsman v0.25.0

More customizable orchestration. Safer Agent lifecycles. Smoother development workflows.

v0.25.0 completes Herdsman's role-definition customization model, improves delegation guidance, and automatically names managed Pi sessions.

It also strengthens recursive Agent cleanup across workspaces and introduces optional dependency preparation for newly created development worktrees.

---

Manager and Chief are now configurable

Manager and Chief now have their own bundled Markdown role definitions, joining Herdsman's existing Lead execution profiles.

All five reserved roles can now be inspected through the Definitions interface:

flexible-lead
orchestrator-lead
managed-lead
manager
chief

Previously, Manager and Chief operating instructions and tool defaults were hardcoded.

Now their behavior can be customized through the same layered definition system used elsewhere in Herdsman.

Manager customization

Manager supports trusted project and global overrides.

You can customize its project-coordination instructions, review preferences, decision-making guidance, and ordinary tool selection.

When no explicit tool list is configured, Manager preserves the saved ordinary Lead tool baseline.

Chief customization

Chief supports global overrides only, reflecting its workspace-neutral supervision role.

By default, Chief has no ordinary Pi tools enabled and retains its mandatory staff coordination tools.

You can explicitly enable ordinary tools when needed.

For example, a global chief.md override:

---
name: chief
tools: [read]
bodyMode: append
---

Use read when a supervised decision requires checking a local artifact.

Existing role boundaries remain intact

Both profiles resolve when their respective roles activate or are restored.

Repeating /manager or /chief refreshes the active profile after validation.

An invalid refresh preserves the previous effective configuration. Restoration also preserves independently verified role authority rather than allowing invalid profile settings to redefine it.

Important

Role definitions customize instructions and ordinary tool availability, not authority.

Manager leases, Chief supervision, project assignments, ownership, and mandatory coordination tools remain governed by Herdsman's runtime.

Manager and Chief remain supervisory roles, not delegatable Agents.

Better delegation guidance

Both orchestrator-lead and managed-lead now receive the same explicit dependency-aware delegation guidance.

Orchestration-focused Leads are instructed to:

• Partition delegable work into distinct, non-overlapping execution responsibilities.
• Select suitable Agent definitions.
• Run genuinely independent assignments in parallel.
• Start dependent assignments only after their prerequisites resolve.
• Retain architectural direction, review, integration, and final decisions.

For example:

Lead
├─ Agent A: Investigate API       ─┐
├─ Agent B: Investigate tests      ├─ Parallel
│                                  │
└─ Agent C: Integrate findings  ←──┘
             After prerequisites

This aligns the behavior expected from ordinary Orchestrate Leads and Manager-assigned Leads without merging their independently configurable profiles.

Note

Dependency ordering is model-facing guidance, not a new runtime scheduler or enforced dependency graph. Existing delegation, ownership, and concurrency contracts remain unchanged.

Related: #352, #353
Implementation: #354, #356

---

Managed Pi sessions now receive meaningful names automatically

As Herdsman creates more parallel and nested Agents, finding the right conversation in Pi's session selector becomes increasingly important.

v0.25.0 automatically assigns native Pi session names using verified management identities.

Managed Agents

Managed Agents receive names derived from their definition and logical label.

For example:

implementer · implementer-1
reviewer · reviewer-1

This also applies to nested Agents.

Managed project Leads

Manager-assigned Leads receive names based on their verified project branch.

For example:

Lead · feat/example

Naming occurs only after the relevant Agent identity or project assignment is verified.

Existing managed sessions can receive names when their valid management relationship is restored or established.

Your names remain yours

Herdsman preserves existing Pi session names, including names explicitly cleared by the user.

You can continue using Pi's native /name command to customize them.

Automatically generated names are:

• Persistent Pi session metadata.
• Independent of the live process or pane.
• Best-effort and nonblocking.
• Never used as ownership or authorization evidence.

Ordinary Leads, Managers, and Chiefs are not renamed merely because they participate in supervision.

No additional model calls, background polling, or naming service are required.

Related: #355
Implementation: #358

---

Stopping a Lead now safely stops its entire Agent tree

Previously, stopping a Manager-assigned Lead could leave its delegated Agents running when the Lead occupied another workspace.

The cleanup path did not consistently discover descendants across workspace boundaries, potentially allowing work to continue after its owner had been stopped.

v0.25.0 strengthens recursive Agent cleanup.

Manager
└─ Lead
   ├─ Agent A
   │  └─ Agent C
   └─ Agent B

stop_lead
    ↓

Stop descendants safely
    ↓
Verify owned Agent tree is stopped
    ↓
Stop Lead

Exact ownership across workspaces

Herdsman now discovers and revalidates owned Agent generations across relevant workspaces.

Cleanup is constrained to the exact target Lead and its verified descendant hierarchy.

Unrelated Agents, other projects, and similarly named Agents in different workspaces remain protected.

Safer concurrent operations

Delegation and stopping now share the relevant lifecycle synchronization boundary.

This prevents new delegation activity from escaping the intended stop while cleanup is underway.

Successful cleanup is established through structured results and a final authoritative Agent inventory, rather than inferring success from formatted output.

If ownership, mailbox state, or descendant cleanup cannot be verified, the stop operation fails safely instead of reporting a misleading success.

Important

stop_lead still pauses managed project execution.

It does not retire the project assignment, delete the worktree or branch, or erase the Pi session.

The existing resume_project workflow remains available.

Related: #333
Implementation: #349

---

More reliable development workflows

Two improvements make development and validation more predictable, particularly when working across multiple Git worktrees.

Optional dependency preparation for new worktrees

Fresh Git worktrees do not inherit node_modules from the original checkout.

For Herdsman development, this previously meant a newly delegated Lead or Agent could be interrupted while requesting authorization to install dependencies before testing or building.

v0.25.0 introduces an optional repository-local Git post-checkout hook.

When explicitly enabled, it runs:

npm ci

synchronously during the creation of a new linked worktree.

This prepares dependencies before delegated execution begins.

To enable the hook, first inspect the repository's existing Git hook configuration. If no existing hook setup would be displaced, run the following from the trusted primary checkout:

git config --local core.hooksPath "$(pwd -P)/.githooks"

The hook is not enabled automatically.

Important

Enabling the hook explicitly authorizes npm ci during future linked-worktree creation, including dependency lifecycle scripts.

Only enable it for trusted repository content. Existing worktrees are unaffected.

If installation fails, Git may leave the new checkout behind. Resolve the installation failure in that checkout before retrying delegation.

Herdsman also extends the worktree-creation timeout to 180 seconds to accommodate dependency installation.

Other Herdr operations retain their existing timeout behavior.

Reproducible formatting

Prettier is now pinned as a development dependency:

prettier 3.9.10

Two npm commands provide a consistent formatting workflow:

npm run format
npm run format:check

format applies changes, while format:check verifies formatting without modifying files.

Formatting verification is now part of:

npm run validate

GitHub Actions also includes a dedicated required formatting check.

This ensures developers, coding Agents, and CI use the same declared formatting tool and can independently verify compliance.

Related: #345, #346
Implementation: #351, #357

---

Validation and compatibility

The contributing PRs report successful focused tests, full validation, build and package audits, and relevant smoke scenarios.

The automatic session-naming changes passed:

• 946 tests, 1 skipped.
• Build and package audit.
• Core, continuation, and Manager-recovery smoke scenarios.

Manager/Chief profile changes also passed Chief-tree and Manager-recovery smoke testing.

The formatting changes passed cross-platform CI.

Remaining validation limitations include:

• No live model-run proof that the new delegation guidance consistently changes Agent scheduling decisions.
• No live cross-workspace recursive-stop smoke test for the specific reported scenario.
• No live Her...

v0.24.0

🐑 Pi Herdsman v0.24.0

Navigate the herd directly. Coordinate with greater reliability.

v0.24.0 introduces clickable status widgets and improves Manager-to-Lead communication reliability.

You can now navigate directly between Agents, Leads, and Managers from the status hierarchy, while supervision messages are retained until their delivery is confirmed.

---

Interactive status widgets

Herdsman's status widgets are no longer just passive displays.

In Pi's fullscreen TUI, clicking a visible Agent, Lead, or Manager can now focus its live Herdr pane.

Navigate through the hierarchy

Click-to-focus supports:

• Chief: Navigate to direct Managers and Leads, including Leads nested beneath Managers.
• Manager: Navigate to active project Leads and other visible live Leads.
• Lead: Navigate to owned Agents.
• Delegating Agent: Navigate to directly or transitively owned Agents.
• Agent breadcrumbs: Click any verified ancestor to navigate to that parent Agent or Lead.
• Managed Lead: Click the managed status marker to navigate directly to its current Manager.

For example:

● lead → implementer → scout
  ^          ^
  |          └─ Focus parent Agent
  └──────────── Focus Lead

Or from a managed Lead:

● lead · managed
         ^^^^^^^
         Click to focus Manager

Navigation without compromising authority

Herdsman doesn't trust displayed names, stale pane IDs, or cached hierarchy information when navigating.

Every click revalidates the relevant identity, ownership, assignment, role generation, and current Herdr placement before focusing.

Targets that are stale, ambiguous, unavailable, or no longer safely identifiable remain non-interactive.

Chief-visible nested Leads remain observational. Navigating to a Lead does not grant Chief additional control authority over it.

The implementation also handles truncated status rows conservatively and includes regression coverage for managed-Lead-to-Manager navigation.

Note

Click navigation is available in Pi's fullscreen TUI. Existing keyboard commands and management menus remain supported.

Navigation is presentation-only and never changes ownership, supervision, or authorization.

Related: #340 · Implementation: #342, #344

---

More reliable Manager supervision

v0.24.0 strengthens two related parts of Manager supervision: message delivery and role identity.

Supervision messages are retained until delivery

Previously, a Manager could successfully queue a message_staff instruction that disappeared before the assigned Lead actually received it.

Herdsman now retains supervision messages until their exact delivery is confirmed in the recipient's Pi session history.

Manager queues message
        ↓
Durable inbox
        ↓
Pi receives message
        ↓
Delivery confirmed in Pi history
        ↓
Inbox record consumed

Unconfirmed messages remain available for recovery and retry.

The improved delivery path:

• Rechecks message identity and authorization before submission.
• Avoids duplicate submission while Pi is busy or has pending input.
• Retries unconfirmed messages after settlement or a conservative fallback.
• Preserves messages when Manager or project-scope verification is inconclusive.
• Retains existing lease, generation, and assignment safeguards.

This makes Manager-to-Lead coordination more resilient to asynchronous Pi execution and recovery timing.

Important

A successful message_staff call confirms durable queuing, not recipient delivery.

Delivery remains recoverable rather than strictly exactly-once. Very late Pi persistence can still cause rare message replay.

Manager identity stays consistent

Manager role restoration now also updates Herdr's presentation metadata to reflect the verified effective role.

Previously, Herdr could continue displaying a session as an ordinary Lead even after Herdsman had restored it as Manager.

Herdsman now:

• Reasserts Manager identity after verified session restoration.
• Clears obsolete Lead-specific metadata.
• Ignores stale queued role reports.
• Records metadata publication failures without affecting role authority.

Manager authority continues to come from verified Herdsman role, lease, and assignment state, never Herdr display metadata.

Related: #311, #338 · Implementation: #339

---

Validation and compatibility

Automated regression coverage includes click navigation, identity replacement, ownership changes, message delivery, retry handling, Manager restoration, and failure recovery.

The final release changes passed:

• 937 tests passed, 1 skipped
• Build and package audit
• Git diff validation

The supervision changes also passed Manager-recovery smoke testing and cross-platform CI.

Live fullscreen click-through testing remains outstanding. The native Herdr focus operation also cannot make identity verification and focusing fully atomic.

The tested runtime baseline remains:

Pi      1.1.0
Herdr   0.9.3

---

Release

Full changelog: v0.23.0...v0.24.0

v0.23.0

🐑 Pi Herdsman v0.23.0

Independent Agents. Shared project knowledge.

v0.23.0 introduces optional context sharing for managed Agents through Pi Codex Conversion (PCC).

Agents can participate in shared notes and history while Herdsman continues to manage their independent sessions, ownership, delegation, and result delivery.

Optional PCC context sharing

Herdsman now ships an adapter for PCC's context-sharing API.

When enabled, participating managed Agents can access shared context without requiring their Lead to copy relevant notes into every delegated task.

The integration preserves Herdsman's existing architecture:

• Independent sessions: Agents retain their own Pi conversations and histories.
• Existing ownership: Delegation, authorization, ask_owner, and result delivery remain unchanged.
• Nested delegation: Participating Agents can establish child context bindings through the same integration.
• Continuation: Existing context identity is restored by PCC rather than rebound by Herdsman.
• No required dependency: PCC remains entirely optional.

Reliable initialization before execution

This release also introduces a generic managed-Agent bootstrap boundary.

Participating extensions can prepare initialization data in the parent and initialize the fresh child before its first delegated task runs.

The bootstrap validates exact Agent identity and runtime compatibility, with bounded durable metadata and explicit failure handling.

No new model-facing tools or ownership protocols are introduced.

Configuration

The supplied PCC adapter supports Remote storage only.

It must be loaded in both the delegating controller and participating fresh managed children:

dist/integrations/pi-codex-context-sharing.js

PCC's existing shareSubagentContext setting controls whether sharing is enabled.

Local and Tree storage are not supported because they require additional ongoing context routing.

Important

The adapter is not loaded automatically.

PCC must be configured separately, including compatible Remote storage and account access. Explicit Agent tool restrictions still apply.

Live PCC Remote acceptance has not yet been verified.

See Customizing Agents for configuration details.

Reported by: @FireTheDevil · Issue: #232
Contributor: @boadij · PR: #329

---

Validation

The implementation passed:

• 107 focused tests
• Full checks: 911 passed, 1 skipped
• Build and package audit
• Core and continuation smoke tests

Both smoke scenarios completed cleanup successfully.

Live PCC Remote integration testing remains outstanding.

The tested runtime baseline remains:

Pi      1.1.0
Herdr   0.9.3

---

Release

Full changelog: v0.22.2...v0.23.0

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

v0.22.1

🐑 Pi Herdsman v0.22.1

Less background work. Same orchestration.

v0.22.1 focuses on making Herdsman more efficient as the number of Agents, Leads, and supervised projects grows.

Instead of repeatedly checking for changes that haven't happened, Herdsman now relies more on native event notifications, reduces unnecessary fleet observations, and avoids repeated work when building Agent snapshots.

The release also updates the README with a live Manager → Lead → Agent demo.

---

Mailbox observation is now event-driven

Managed Agents previously checked their durable mailboxes every 250 milliseconds, including when nothing was happening.

Owner-side result and question observers used similarly frequent filesystem polling.

v0.22.1 replaces these long-lived polling loops with native filesystem notifications.

Herdsman now:

• Watches mailbox directories using Node's native fs.watch().
• Reacts to relevant changes without waiting for the next polling interval.
• Coalesces notifications to avoid redundant reconciliation.
• Uses a one-second fallback to recover from missed filesystem events.
• Reattaches failed watchers and cleans them up when no longer needed.

The durable mailbox remains authoritative. Filesystem events are only hints that something may have changed.

Note

In an idle observer test, the new implementation performed 10 reconciliations over roughly 10 seconds. The previous 250 ms schedule would perform approximately 40 checks over the same period.

These are callback counts, not measured CPU or filesystem-I/O savings.

Existing request delivery, Agent results, questions, cancellation, recovery, and acknowledgement behavior are preserved.

Reported by: @boadij · Issue: #319
Contributor: @boadij · PR: #325

---

Supervision no longer constantly rescans an unchanged fleet

Lead status and Chief/Manager supervision previously performed substantial observation work every two seconds, even when the underlying fleet had not changed.

That could involve repeated Herdr queries, workspace inspection, and Agent identity reconciliation.

v0.22.1 changes how those observations are scheduled.

Herdsman now subscribes to relevant Herdr lifecycle and presentation events and refreshes the affected state when changes occur.

Routine authoritative reconciliation moves from every 2 seconds to every 10 seconds.

Presentation-only updates are coalesced, while lifecycle changes and explicit refresh requests remain responsive.

Manager's elapsed-time display continues updating every two seconds using its existing snapshot, without requiring a full supervision scan.

The implementation also handles lost events, connection failures, and reconnection through authoritative reconciliation.

Important

Events trigger refreshes; they do not establish authority.

Exact identity, ownership, role, lease, and project-assignment checks remain authoritative. Operations that require fresh validation continue to perform it.

Headless sessions also avoid starting UI-only periodic supervision observation.

This reduces unnecessary observation work without adding another cache, scheduler, or persistent state.

Reported by: @boadij · Issue: #320
Contributor: @boadij · PR: #326

---

Agent snapshots do less repeated work

Even when a snapshot is necessary, its construction should not repeatedly inspect the same information.

An audit identified several avoidable costs in Agent status and ownership projections:

• Repeated Agent and pane inventory searches.
• Repeated traversal of ownership ancestry.
• Repeated completed-result checks.
• Duplicate mailbox scans for state and diagnostics.
• Redundant Agent-definition discovery.

v0.22.1 consolidates these operations.

Agent and workspace identity indexes are now built once for a snapshot, reducing repeated searches as herds grow.

Direct-child pending work and completed-result information are also aggregated and reused rather than recalculated separately for each Agent.

Mailbox diagnostics travel alongside the state snapshot, and configuration menus reuse effective definition discovery within an interaction.

Correctness remains unchanged

The optimized paths preserve the existing ownership and identity rules.

Ambiguous, missing, cyclic, and cross-workspace ancestry still fail closed rather than being guessed.

Unreadable child results remain pending, and destructive operations continue performing independent fresh validation.

Note

These changes remove redundant scans and improve traversal behavior, but no end-to-end timing benchmark was performed for this PR. The actual performance improvement will depend on herd size and workload.

No persistent snapshot cache or new dependency was introduced.

Reported by: @boadij · Issue: #321
Contributor: @boadij · PR: #328

---

Updated live demo

The README now includes an updated live demonstration of the complete:

Manager
  └─ Lead
      └─ Agent

workflow.

The demo illustrates how project-level orchestration, Lead coordination, and Agent execution fit together in practice.

Contributor: @boadij · PR: #322

---

What stays the same

These are performance and presentation improvements, not changes to Herdsman's orchestration model.

• Durable mailbox records remain authoritative.
• Agent ownership and supervision boundaries are unchanged.
• Exact session identity and fail-closed validation remain intact.
• Project assignment and recovery semantics are preserved.
• Explicit operations continue obtaining fresh evidence where required.
• No new dependencies, persistent caches, or configuration settings are introduced.

The tested runtime baseline remains:

Pi      1.1.0
Herdr   0.9.3

Validation

The contributing PRs passed their reported automated test, build, and package-audit checks.

The mailbox observer changes additionally passed isolated core and continuation smoke tests.

Performance validation primarily measured scheduled callbacks and simulated snapshot calls. Full CPU, memory, filesystem-I/O, and scaled-fleet benchmarks were not performed.

---

Release

Full changelog: v0.22.0...v0.22.1

v0.22.0

🐑 Pi Herdsman v0.22.0

More control over how the herd works. Less complexity to get started.

v0.22.0 introduces configurable Lead execution profiles, makes /herdsman the main entry point, and establishes a clearer boundary between Manager-controlled project work and ordinary Lead sessions.

It also simplifies the coordination-tool vocabulary, improves context-retirement handling, and adopts Pi 1.1.0.

Important

Breaking change: Model-facing coordination tools now use verb-first names. Existing agent instructions, integrations, and workflows referencing the previous tool names need updating.

---

Lead execution is now configurable

Ordinary Leads can now operate in two explicit execution modes:

Flexible

A normal Pi session with Herdsman coordination capabilities. The default profile preserves Pi's ordinary tools and supports both direct work and delegation.

Orchestrate

An orchestration-focused Lead that delegates bounded work to Agents while retaining coordination, direction, integration, and decisions.

The bundled Orchestrate profile starts with read-oriented tools, but both profiles can be customized.

Each mode has its own standalone definition:

Ordinary Lead
├─ Flexible     → flexible-lead
└─ Orchestrate  → orchestrator-lead

Manager-assigned Lead
└─ Managed      → managed-lead

These profiles do not inherit from or compose with one another.

Switch ordinary execution modes through:

/lead
/lead flexible
/lead orchestrate

The /herdsman menu also provides an Execution selector.

A new defaultLeadExecution setting controls the initial mode for future ordinary Lead sessions. The default is flexible.

Execution preferences persist across session continuation, and navigation through Pi's conversation tree restores the appropriate execution state.

Note

Lead execution profiles control instructions and ordinary tool availability, not ownership or supervision authority. Manager-assigned Leads continue using their separate managed-lead definition.

Contributor: @boadij · PR: #304 · Issue: #294

---

/herdsman becomes the main entry point

Herdsman has grown beyond background Agents. The human-facing interface now reflects that broader scope.

Run:

/herdsman

to access:

• Execution
• Agents
• Project manager
• Session stats
• Definitions
• Settings
• Advanced controls

The interface progressively exposes more powerful workflows without requiring users to understand the entire orchestration hierarchy first.

Existing /agents commands remain fully supported as aliases, including their arguments and expert shortcuts.

Tip

You can start with normal Pi usage, add background Agents when useful, and move into dedicated Lead or Manager workflows without changing tools or adopting a prescribed development process.

This also establishes progressive capability disclosure as an explicit product-design principle: simple workflows should remain simple even as more advanced orchestration becomes available.

Contributor: @boadij · PRs: #300, #299

---

Manager authority is now tied to exact project assignments

Manager supervision is now explicitly limited to Leads named by current durable project assignments.

Sharing a workspace or worktree scope no longer implies Manager authority.

Manager
  └─ assigned Lead       → Manager authority

Unassigned ordinary Lead → no implicit Manager authority

Unassigned Leads remain eligible for Chief supervision.

This makes the project-control boundary clearer and avoids treating physical proximity as ownership.

Automatic handoffs from managed Leads

Every completed direct turn from an assigned Lead can now return a nonterminal report to Manager.

When a managed Agent herd run owns the work, herd settlement remains the single automatic handoff boundary.

This closes the gap where a Lead could perform multi-turn direct work without reliably returning its result to Manager.

Routine coordination through message_supervisor remains asynchronous and nonblocking.

Explicit /takeover

Users can now release a Lead from Manager control without destroying its working environment.

After confirmation, /takeover:

• removes the current project assignment and pending project messages
• preserves the Pi session and conversation
• preserves the branch, worktree, and running process
• preserves the Lead's owned Agents
• transitions the Lead to ordinary Orchestrate execution

This is an authority transition, not project completion.

Important

A managed Lead remains managed until its assignment is explicitly released. Merely continuing the same Pi session manually does not revoke Manager authority.

Contributor: @boadij · PR: #284 · Issues: #277, #278

---

Breaking: coordination tools now use verb-first names

The model-facing API now follows a consistent:

<verb>_<target>

naming convention.

Agent tools

agent_list       → list_agents
agent_delegate   → delegate_agent
agent_continue   → continue_agent
agent_steer      → steer_agent
agent_interrupt  → interrupt_agent
agent_reply      → reply_agent
agent_close      → close_agent
agent_inspect    → inspect_agent
agent_transcript → read_agent_transcript

Peer and supervisor tools

peer_list          → list_peers
peer_message       → message_peer
supervisor_message → message_supervisor

Staff and project tools

staff_list       → list_staff
staff_inspect    → inspect_staff
staff_transcript → read_staff_transcript
staff_message    → message_staff

staff_delegate   → delegate_project
staff_resume     → resume_project
staff_stop       → stop_lead

The existing ask_owner tool keeps its name.

Human-readable tool presentation, documentation, bundled instructions, and runtime registration have been updated accordingly.

Manager/Lead messaging also remains intentionally distinct from managed-Agent questions: supervisor coordination is nonblocking, while ask_owner remains the direct-owner question mechanism.

Contributor: @boadij · PR: #297 · Issue: #289

---

Pi 1.1.0 and cancellation-safe settlement

The tested runtime baseline is now:

Pi      1.1.0
Herdr   0.9.3

Pi 1.1.0 provides explicit cancellation information through agent_settled.aborted.

Herdsman now respects that signal when classifying managed-Agent results.

A cancelled run can no longer be reported as successfully completed merely because its last assistant message looked successful.

Cancelled Lead turns likewise produce factual, nonterminal reporting instead of implying verified completion.

This preserves existing assignment ownership, child-work reconciliation, and durable result delivery.

The update also keeps Agent-definition tool policies closed by rejecting Pi's new +name and -name modifiers in explicit tool allowlists.

Contributor: @boadij · PR: #305 · Issue: #301

---

Context retirement reaches the next provider request

Context retirement now delivers its guidance more reliably when an active managed Agent reaches the automatic compaction threshold.

Pi can defer durable messages until a safe turn boundary. Previously, this meant retirement could be recorded before the next provider request actually received the instruction.

Herdsman now uses a one-request bridge to make the guidance available immediately while retaining the durable message in Pi history.

Preventive threshold compaction remains cancelled, and overflow recovery retains its existing behavior.

Retired Agents also cannot start new Agent delegations or continuations, although they may still coordinate already-running children.

Note

This fixes timely instruction delivery, not guaranteed model compliance. Adversarial testing still demonstrated additional ordinary tool calls after guidance was delivered. Further work on reliable post-retirement convergence remains necessary.

Contributor: @boadij · PR: #310 · Issue: #303

---

Clearer project reports and evidence boundaries

Manager handoffs now distinguish between information present in a project report and evidence actually available on the current Pi conversation branch.

Automatic project reports preserve their text without silently attaching or inventing result bindings.

A semantic Agent result reference is forwardable only when the relevant direct completion or imported result binding exists on the current branch.

Merely mentioning a reference does not make its underlying artifact available.

Explicit files handoffs remain the supported mechanism for transferring evidence between coordination boundaries.

Contributor: @boadij · PR: #315 · Issue: #313

---

Execution mode is visible in the status widget

The Lead status widget now shows its verified effective execution mode:

● lead · flexible
● lead · orchestrate
● lead · managed

This helps distinguish ordinary interactive work, orchestration-focused Leads, and Manager-assigned project work without opening a menu.

Unknown or unverified execution state is omitted rather than guessed. Narrow terminals preserve the Lead identity before optional metadata.

Contributor: @boadij · PR: #318 · Issue: #317

---

Additional polish

Agent Definition details now support individual click-to-expand behavior, consistent with other expandable Herdsman transcript entries.

Editing Agent-definition settings preserves the original frontmatter key order instead of moving edited properties to the bottom. Bundled definitions have also received consistent frontmatter formatting.

Test coverage now recognizes ...

v0.21.3

🐑 Pi Herdsman v0.21.3

A small UI and packaging follow-up.

Herdsman messages now expand on click

Expandable Herdsman custom messages now behave more like Pi tool executions in the fullscreen TUI.

Previously, a collapsed delegation block could be clicked to expand individually, while a received Herdsman message relied on Pi's global expansion control.

v0.21.3 adds native Pi MouseRegion handling so expandable coordination messages can now toggle independently on left click.

collapsed message
      click
        ↓
expanded message

Each message keeps its own transient expansion state, while Pi's global expand/collapse behavior still works normally.

Note

This is presentation-only. Message content, delivery, persistence, lifecycle, authority, and model-facing semantics are unchanged.

Reported by: @boadij · Issue: #265
Contributor: @boadij · PR: #290

---

Agent-definition skill gets the shorter name

The bundled Agent-definition skill directory has been renamed from:

pi-herdsman-agent-definitions

to:

agent-definitions

The skill contents are unchanged.

A follow-up also corrected the package audit paths so npm packaging and container CI use the renamed location correctly.

Contributor: @boadij · Commit: 41d5c02
Contributor: @boadij · PR: #292

---

Release

Full changelog: v0.21.2...v0.21.3

v0.21.2

🐑 Pi Herdsman v0.21.2

A context-retirement cleanup focused on making managed-Agent history more durable and cache-friendly.

Retirement guidance is now persisted

When a managed Agent approaches Pi's automatic context-compaction threshold, Herdsman already retires that session before preventive compaction so the Agent can finish with its original context intact.

The retirement instruction itself was still being injected transiently into every later provider request.

v0.21.2 changes that.

Herdsman now persists the retirement guidance into the Pi session as durable model-visible history instead of repeatedly reconstructing it through the context hook.

threshold pressure
→ persist retirement state
→ persist retirement guidance
→ cancel preventive compaction
→ continue with stable session history

Note

This preserves the existing retirement lifecycle. Threshold compaction is still cancelled, manual compaction remains inert, and retired sessions remain ineligible for continuation while context retirement is enabled.

Overflow recovery stays intact

Overflow is different from preventive threshold retirement: Pi still needs to perform its native recovery compaction.

If retirement guidance is queued while the Agent is already streaming, Herdsman now bridges that guidance into only the immediate overflow retry request so the retry sees the correct instruction without waiting for the durable message to become visible.

That transient bridge is consumed once and discarded if the retry never happens.

Important

Ordinary later requests do not receive transient retirement injection. Durable Pi history remains the normal source of model-visible guidance.

This better aligns the runtime with Herdsman's prompt-cache continuity rules: preserve the existing prefix where possible, append durable guidance, and avoid rebuilding context unnecessarily.

Reported by: @boadij · Issue: #192
Contributor: @boadij · PR: #280

---

Release

Full changelog: v0.21.1...v0.21.2

v0.21.1

🐑 Pi Herdsman v0.21.1

A focused compatibility and ownership-context release.

Pi 1.0.4 support without widening Agent capabilities

Pi Herdsman's tested Pi baseline moves to:

Pi      1.0.4
Herdr   0.9.3

Pi 1.0.4 changed native --tools / --exclude-tools behavior, including how MCP tools remain exposed.

Herdsman now adapts to that contract while preserving the existing Agent-definition policy:

tools omitted
→ inherit Pi's normal configured tool environment

tools explicitly present
→ closed capability set
   + required Herdsman coordination tools

That means a constrained managed Agent does not silently gain unrelated ambient MCP tools simply because they are configured on the host.

Important

Explicit Agent-definition tool allowlists remain closed capability policies. This update adopts Pi's native 1.0.4 mechanisms rather than introducing a separate Herdsman tool registry.

The diagnostic coverage now also understands Pi 1.0.4's provider tool payload shapes, including Anthropic-style tools.

Reported by: @boadij · Issue: #279
Contributor: @boadij · PR: #286

---

Managed Agents now know who directly owns them

Herdsman already had an exact durable ownership graph for every managed Agent, but that relationship was not projected clearly into the Agent's own context.

v0.21.1 now provides semantic ownership context separately from authorization:

Lead
└─ Agent
   └─ Agent

A managed Agent can understand:

• its own managed identity
• its immediate direct owner
• its current ownership relationship

Exact Pi session identity remains authoritative for routing, authorization, and ask_owner.

Note

Ownership and supervision remain different relationships.

Managed Agents are owned by a Lead or another Agent. They are not directly supervised by Manager or Chief.

The generic <active_agent .../> signal is also preserved for compatible extensions that use it to select per-Agent behavior.

Reported by: @boadij · Issue: #282
Contributor: @boadij · PR: #287

---

Delegating Agent breadcrumbs show the Lead again

Delegation-enabled managed Agents could incorrectly show an unknown ancestry root:

● ? → implementer:docs

even when their Lead boundary was fully provable.

That regression is fixed:

● lead → implementer:docs

The fix restores the same validated Lead-boundary proof used by non-delegating managed Agents.

Note

Herdsman still fails closed. If ancestry genuinely cannot be proven, the breadcrumb remains ? rather than guessing.

This is a presentation fix only; durable ownership and authorization were already correct.

Reported by: @boadij · Issue: #281
Contributor: @boadij · PR: #283

---

Release

Full changelog: v0.21.0...v0.21.1

v0.21.0

🐑 Pi Herdsman v0.21.0

Configure the herd. Steer it while it runs.

v0.21.0 makes Herdsman's existing orchestration model easier to operate rather than adding another layer to it.

Agent definitions now have a dedicated bundled skill, active Leads can receive Manager direction while they are still working, and project-message delivery is cleaner across Manager replacement.

Note

The tested runtime baseline remains Pi 1.0.1 + Herdr 0.9.3.

---

Agent definitions get their own skill

Pi Herdsman now ships a dedicated:

agent-definitions

skill for model-assisted Agent-definition management.

Instead of reconstructing definition paths, precedence, schema rules, and managed-lead behavior manually, you can ask Pi to inspect and change the existing definition system directly.

The skill understands:

• bundled, project, and global definition layers
• bundled < project < global precedence
• partial Markdown overlays
• the Agent-definition schema
• trusted project scope
• the reserved managed-lead definition
• launch-time configuration semantics

It deliberately reuses the existing Markdown definition engine and validation instead of introducing another configuration API or tool.

Tip

Pi may select the skill automatically when relevant, or it can be loaded explicitly with /skill:agent-definitions.

Contributor: @boadij · PR: #271

---

Managers can steer active Leads

staff_message no longer has to wait for a busy Lead's entire run to finish.

When a verified direct report is actively working, Manager direction now uses Pi's cooperative steering path and becomes available at the next safe model/tool boundary.

That makes supervision useful during long-running direct work for things like:

• correcting an assumption
• narrowing scope
• supplying new evidence
• changing review direction
• stopping unnecessary work cooperatively

Idle delivery continues to work normally, and other inbox traffic keeps its existing deferral semantics.

Important

This is cooperative steering, not hard interruption. An in-flight tool call may still finish before the Lead sees the new direction.

Reported by: @boadij · Issue: #270
Contributor: @boadij · PR: #272

---

Delivered project messages are now consumed

Project messages now represent pending coordination, not permanent replay history.

Once a Manager has received a project message, the exact message identity in Pi's durable session history proves delivery and Herdsman consumes the pending record.

That means replacing or restarting a Manager no longer replays historical handoffs as fresh events while the project remains open.

Messages created while no Manager is available are still retained and delivered later.

Lead produces handoff
        ↓
pending project message
        ↓
Manager receives it
        ↓
Pi history owns delivered evidence
        ↓
pending record consumed

The project assignment itself remains independent and durable until the existing Herdr worktree-retirement boundary resolves it.

Reported by: @boadij · Issue: #266
Contributor: @boadij · PR: #269

---

Expanded staff views keep project context

Expanded staff_* presentation now preserves more of the project context Herdsman already knows.

In particular:

• staff_resume can show the durable assignment being resumed
• Manager staff_list shows current project work
• available staff actions reflect the actual runtime projection
• successful project operations preserve resolved branch identity

Compact views remain compact. This is presentation only; project ownership, authorization, persistence, and recovery semantics are unchanged.

Reported by: @boadij · Issue: #262
Contributor: @boadij · PR: #268

---

Positive steering is now structural

Herdsman's instruction-design guidance now treats positive steering as more than wording.

The preferred order is to make the intended behavior the natural behavior through:

• capabilities
• schemas
• defaults
• state
• lifecycle boundaries
• validation

Negative instructions remain appropriate for genuine authority, safety, integrity, and destructive-operation boundaries.

Note

The aim is fewer instructions telling an Agent what not to do when the interface can simply make the correct action obvious or structurally available.

Contributor: @boadij · PR: #263

---

Preview releases are reliable again

The PR preview workflow has been updated for current npm behavior:

• prerelease dry-runs now use the PR-specific dist-tag
• downloaded preview tarballs are published explicitly as local files
• the trusted-publishing job uses an npm version that supports non-latest dist-tags

Stable release behavior is unchanged.

Contributor: @boadij · PRs: #275, #276

---

Release

Full changelog: v0.20.1...v0.21.0