Repository navigation
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
