pi-herdsman 0.22.0 → 0.22.2

package/docs/adr/0013-use-herdr-worktree-removal-for-project-retirement.md

@@ -1,6 +1,6 @@
 # Use Herdr worktree removal for project retirement
 
-> **Superseded in part by [ADR 0017](0017-use-project-assignments-for-managed-lead-authority.md):** explicit user `/takeover` is an additional assignment-release path. This ADR continues to define successful Herdr worktree removal as a separate retirement event.
+> **Historical decision; superseded in part.** [ADR 0017](0017-use-project-assignments-for-managed-lead-authority.md) adds confirmed `/takeover` as a separate assignment-release path. [ADR 0019](0019-retire-project-assignments-when-worktrees-are-absent.md) supersedes the event-only retirement rule and the decision to recover assignments after verified worktree absence; the current runtime implements both retirement authorities.
 
 ## Decision
 

package/docs/adr/0015-use-reserved-definition-for-managed-project-leads.md

@@ -11,8 +11,11 @@ reserved name is excluded from the Agent roster and cannot be delegated to or
 referenced through an Agent `agents` allowlist.
 
 The definition owns configurable launch behavior such as prompt body, model,
-thinking, ordinary tools, skills, extensions, and context inheritance. Herdsman
-still owns and enforces project identity, supervision, durable Agent ownership,
+thinking, ordinary tools, skills, extensions, and context inheritance. The
+bundled default selects no ordinary tools (`tools: []`); mandatory Lead
+coordination tools are injected at launch, and overlays can enable direct
+tools explicitly. Herdsman still owns and enforces project identity,
+supervision, durable Agent ownership,
 mandatory Lead coordination tools, handoff behavior, and project/worktree
 lifecycle.
 

package/docs/adr/0017-use-project-assignments-for-managed-lead-authority.md

@@ -1,5 +1,7 @@
 # Use project assignments for managed-Lead authority
 
+> **Lifecycle update:** [ADR 0019](0019-retire-project-assignments-when-worktrees-are-absent.md) adds authoritative missing-checkout reconciliation as an assignment-retirement condition. The exact-assignment authority rule and confirmed `/takeover` remain unchanged; the current runtime implements the update.
+
 ## Status
 
 Accepted

package/docs/adr/0018-use-standalone-lead-execution-profiles.md

@@ -10,8 +10,8 @@ Ordinary Lead execution has two modes: `Flexible` and `Orchestrate`. Each maps
 one-to-one to a standalone reserved definition: `flexible-lead` and
 `orchestrator-lead`. The definitions do not compose or inherit from one
 another. Flexible's bundled definition leaves ordinary tools unspecified so
-Pi's normal selection remains the baseline; Orchestrate provides
-orchestration-first instructions and a conservative ordinary-tool policy.
+Pi's normal selection remains the baseline; Orchestrate uses `tools: []` to
+leave only mandatory coordination tools available by default.
 
 Manager-assigned Leads use only the standalone `managed-lead` launch
 definition. Ordinary execution preference is session state separate from
@@ -49,6 +49,8 @@ Manager authority.
 
 ## Consequences
 
+- Bundled Orchestrate and managed Leads have no ordinary tools by default;
+  project/global definition overlays may explicitly enable them.
 - Runtime profiles may change execution instructions and ordinary active-tool
   selection, but not launch-time model, thinking, extensions, skills, or
   context inheritance.

package/docs/adr/0019-retire-project-assignments-when-worktrees-are-absent.md

@@ -0,0 +1,88 @@
+# Retire project assignments when worktrees are absent
+
+[Documentation index](../README.md)
+
+## Status
+
+Accepted on 2026-10-09 and implemented. Matching Herdr removal events and
+verified Git worktree inventory now retire exact assignments when their
+checkout is removed; incomplete or ambiguous evidence preserves them.
+
+## Context
+
+A `ProjectAssignment` is a durable Manager-to-Lead authority edge, but it is
+not a long-term backlog or record of finished project work. On 2026-10-09,
+four assignments remained `paused` after the user removed their worktrees
+using Herdr's Remove Worktree action. The exact failure boundary was not
+established.
+
+[ADR 0013](0013-use-herdr-worktree-removal-for-project-retirement.md) relies
+on observing a successful Herdr removal event and intentionally preserves
+assignments when a checkout is otherwise missing, allowing
+`resume_project` to recreate it. Herdr events are not durable, so a missed
+notification can leave an assignment indefinitely, even after the checkout
+has been deleted. That recovery policy does not match the intended meaning
+of project assignments as _currently managed work_.
+
+## Decision
+
+A project assignment remains managed only while its associated Git worktree
+exists. A stopped Lead, closed Herdr workspace, or replaced Manager does
+not end the assignment while the checkout still exists. Lead settlement,
+review, and ordinary conversation are also nonterminal.
+
+Retire the matching assignment and its still-pending project messages when
+either of these is authoritative:
+
+- Herdr reports successful removal of the matching linked worktree.
+- Complete, trustworthy repository/worktree evidence establishes that the
+  assignment's checkout no longer exists, even if a removal event was missed
+  or the checkout was removed outside Herdr.
+
+A missing _open workspace_ is not a missing _worktree_. A failed or partial
+inventory, disconnected Herdr instance, ambiguous repository or branch
+identity, or out-of-scope machine is not proof of deletion. In-flight
+worktree creation or restoration must not be mistaken for an abandoned
+checkout. Until absence is verified, preserve the assignment and fail
+closed rather than deleting it speculatively.
+
+Retirement must target the exact current assignment; concurrent replacement
+assignments and unrelated projects remain protected. It ends Manager
+authority for that assignment without deleting its Git branch, Pi session,
+conversation, or unrelated work. It does not imply that the task was
+completed, accepted, merged, or discarded.
+
+After authoritative checkout absence retires an assignment,
+`resume_project` cannot reconstruct that _retired assignment_. A later
+delegation can start new managed work from the remaining Git branch. The
+branch and historical conversation are not erased.
+
+## Rationale
+
+Checkout existence expresses whether the user is still maintaining that
+branch as a managed working area. Treating the assignment as current work,
+rather than a durable project archive, makes the Manager overview useful
+and repairs orphaned assignments after missed lifecycle notifications,
+restarts, and manual checkout removal.
+
+This deliberately gives up automatic recovery of an old assignment after
+confirmed checkout deletion. Retaining Git history and Pi conversations
+preserves useful work without retaining obsolete Manager authority.
+
+## Alternatives and boundaries
+
+- **Require an observed Herdr removal event:** insufficient because events
+  can be lost and external checkout removal has no Herdsman notification.
+- **Retire on workspace closure or observation failure:** unsafe because the
+  checkout may still exist or evidence may be temporarily unavailable.
+- **Require manual orphan cleanup:** useful as a separate user-control
+  capability if needed, but not a substitute for correct automatic lifecycle
+  reconciliation.
+
+This supersedes ADR 0013's event-only retirement and missing-checkout
+recovery decisions, and extends the retirement boundary in
+[ADR 0017](0017-use-project-assignments-for-managed-lead-authority.md).
+ADR 0017's exact-session authority checks and confirmed `/takeover` path
+remain unchanged. The existing user-facing guides and runtime contracts
+must be updated alongside the implementation; this ADR alone does not
+change shipped behavior.

package/docs/concepts/coordination.md

@@ -123,9 +123,9 @@ should go through the automatic result; timely questions, clarifications, or
 warnings may use nonblocking `message_supervisor`. This is ordinary
 coordination, not assignment state; there is no deduplication between a
 message and a later result.
-Project assignments end only on explicit events, not settlement or review:
-successful Herdr worktree removal or user-confirmed `/takeover` by the assigned
-Lead. Takeover removes the assignment and pending project messages while
+Project assignments end on successful Herdr worktree removal, verified Git
+checkout absence, or user-confirmed `/takeover` by the assigned Lead—not on
+settlement or review. Takeover removes the assignment and pending project messages while
 preserving the session, conversation, branch, worktree,
 running process, and Lead-owned Agents; it does not imply completion or
 acceptance. See
@@ -133,14 +133,18 @@ acceptance. See
 
 `stop_lead` pauses assigned execution while preserving the assignment, Pi
 session, branch, and worktree; `resume_project` resumes the existing
-assignment. These operations do not change project authority. Successful
-Herdr worktree removal retires the matching assignment and any still-pending
-project messages while preserving the Git branch. Explicit `/takeover` by the
+assignment while its checkout exists. These operations do not change project
+authority. Successful Herdr worktree removal or verified checkout absence
+retires the matching assignment and any still-pending project messages while
+preserving the Git branch. Explicit `/takeover` by the
 assigned Lead is a separate assignment-release path. Manually continuing the
 exact assigned Pi session remains managed; `managed-lead` is launch policy,
 not authority.
-A worktree that is merely missing does not retire the assignment; it remains
-recoverable through `resume_project`.
+A complete Git worktree inventory that verifies the checkout is absent retires
+the exact assignment and pending project messages, even when a Herdr removal
+event was missed. Failed or ambiguous inventory preserves the assignment.
+`resume_project` cannot restore a retired assignment; a new delegation may
+reuse the remaining Git branch.
 
 For the task-oriented workflow, see
 [Project orchestration](../guides/project-orchestration.md). Exact operations

package/docs/coordination-api.md

@@ -68,9 +68,10 @@ Successful Herdr worktree removal retires the matching project assignment and
 any still-pending project messages. The assigned Lead can also explicitly
 release Manager control with confirmed `/takeover`, which removes the
 assignment and pending project messages while preserving its session, branch,
-worktree, process, and owned Agents. A missing worktree alone does not retire
-an assignment; `resume_project` can reconstruct the checkout when its branch
-remains available.
+worktree, process, and owned Agents. Verified Git worktree inventory showing
+the checkout absent also retires the assignment. Failed or ambiguous inventory
+preserves it. A retired assignment cannot be resumed, but new work may reuse
+its remaining branch.
 
 An assigned project Lead uses `message_supervisor` for timely Manager
 coordination; an ordinary Lead and a Manager use it to contact Chief. An

package/docs/development/product-philosophy.md

@@ -96,6 +96,13 @@ Optional participation may be absent; participating behavior that cannot be
 initialized correctly should fail explicitly rather than continue in a
 partially valid state.
 
+Treat performance and efficiency as design goals across runtime, model-facing
+interactions, and development workflows. As workloads and Agent counts grow,
+avoid unnecessary latency, token use, computation, I/O, and resource
+consumption. Prefer eliminating work over adding caches or infrastructure,
+and justify optimization complexity with evidence. Never trade correctness,
+reliability, security, or recovery for speed.
+
 ## Decision test
 
 For any proposed feature, ask:

package/docs/development/smoke-testing.md

@@ -56,9 +56,10 @@ managed descendants do not load the probe.
 The available scenarios are `core` (nested delegation and candidate-extension
 propagation), `continuation` (persisted Pi-session continuation across managed
 generations), `chief-tree` (current Chief/session_tree behavior), and
-`manager-recovery` (Manager delegation, review messaging, `stop_lead`, missing
-worktree reconstruction with exact Pi-session continuity, retained project
-messages across Manager turnover, and Herdr-driven project retirement).
+`manager-recovery` (Manager delegation, review messaging, `stop_lead`, verified
+pause/resume with an intact checkout, Manager turnover with a pending project
+message, verified missing-worktree retirement without recreating the assignment,
+and refusal to resume retired work).
 `chief-tree` records ordinary Lead, Chief, and post-`session_tree` tool
 snapshots and verifies Chief differs from Lead while selecting a pre-Chief
 branch restores ordinary Lead tools. It does not
@@ -366,11 +367,11 @@ After every smoke:
 ## Project Manager / Chief supervision live matrix
 
 `manager-recovery` is the canonical automated live Manager lifecycle check. It
-covers fresh delegation, project review messaging, pause/resume, missing
-worktree recovery without an explicit Herdr removal event, exact Pi-session
-continuity, pending project messages across Manager absence and delivery,
-retirement after
-successful Herdr worktree removal, and exact cleanup.
+covers fresh delegation, project review messaging, pause/resume, Manager
+turnover while a project message is pending and its later delivery, missing
+worktree retirement without an explicit Herdr removal event, refusal to resume
+the retired assignment, exact Pi-session continuity before retirement, and
+exact cleanup.
 
 The broader matrix below remains optional exploratory acceptance for supervision
 behavior not covered by the automated scenarios. A NOT RUN entry is not a claim

package/docs/guides/customizing-agents.md

@@ -23,9 +23,9 @@ inheritance, or Agent/permission policy are not supported.
 
 The bundled `flexible-lead` leaves `tools` unspecified, preserving Pi's normal
 ordinary tool baseline, and supplies flexible direct/delegated-work guidance.
-The bundled `orchestrator-lead` selects `read`, `ls`, `find`, and `grep` and
-guides the Lead to delegate bounded execution whenever an Agent can reasonably
-own it. Example user overlay:
+The bundled `orchestrator-lead` sets `tools: []`, leaving only mandatory
+Herdsman coordination tools available. Inspection and execution are delegated
+to Agents by default. Example user overlay to opt into direct tools:
 
 ```markdown
 ---
@@ -38,8 +38,11 @@ Use the repository's documented smoke command when validating integration work.
 ```
 
 An explicit tool list selects registered ordinary tools; exclusions are then
-applied. Herdsman-owned tools cannot be enabled through a profile, and required
-Lead coordination tools are retained. A configured tool that is not registered
+applied. At the effective-definition level, `tools: []` disables ordinary
+tools, whereas an absent `tools` field preserves Pi's normal selection.
+Overlays that omit `tools` still inherit the bundled `[]`. Herdsman-owned
+tools cannot be enabled through a profile, and required Lead coordination
+tools are retained. A configured tool that is not registered
 is simply unavailable. Profile resolution respects project trust. Definition
 changes take effect when the profile is next resolved: at session start/resume,
 or when a user explicitly selects an execution mode with `/lead` (including
@@ -61,10 +64,11 @@ and cannot be delegated to. It appears first in the flat Definitions list, with
 Model, Thinking, and Details settings but no `Enabled` action. These settings
 do not add it to Agent discovery or delegation.
 
-The bundled default is orchestration-focused: it gives the Lead read-only
-inspection tools plus mandatory Herdsman coordination tools. Executable project work is delegated to managed
-Agents by default. Manager owns project supervision and assignment
-boundaries; the Lead owns technical decisions and execution orchestration.
+The bundled default is coordination-only (`tools: []`): mandatory Herdsman
+coordination tools remain available, while ordinary inspection and execution
+are delegated to managed Agents. Manager owns project supervision and
+assignment boundaries; the Lead owns technical decisions and execution
+orchestration.
 Herdsman automatically hands off the normal assignment response, deferring it
 until delegated Agent work settles. See [Project orchestration](project-orchestration.md)
 for the automatic result and `message_supervisor` coordination contract.

package/docs/guides/project-orchestration.md

@@ -55,10 +55,11 @@ Pi Herdsman can generate one. The first delegation can create the first linked
 worktree, and an unoccupied existing worktree for the branch is reused.
 
 Start new work with `delegate_project`. Resume existing work with
-`resume_project` using its branch. If its worktree is missing, Herdsman recreates
-it from the existing branch and resumes the exact persisted Pi session when
-available. The saved session cwd is used when history exists; if the branch
-itself is unavailable, recreation fails closed.
+`resume_project` using its branch. A verified Git inventory showing the
+assignment's worktree checkout is absent retires that assignment and its
+pending project messages; failed or ambiguous inventory preserves it. A retired
+assignment cannot be resumed, but a new delegation may start managed work from
+the remaining Git branch. Retirement does not delete branches or Pi sessions.
 
 Whenever Herdsman actually launches the project Lead process, it resolves the
 current `managed-lead` definition from the target worktree plus the global
@@ -135,10 +136,10 @@ See [`stop_lead`](../reference/staff.md#stop_lead) and
 
 ## Retire project work
 
-Successful Herdr worktree removal retires the matching project assignment,
-any still-pending messages; the Git branch remains. A worktree that is merely
-missing does not imply retirement, so the assignment remains recoverable with
-`resume_project` when its branch is available. An assigned Lead can explicitly
+Successful Herdr worktree removal or verified checkout absence retires the
+matching project assignment and any still-pending messages; the Git branch
+remains. Failed or ambiguous inventory does not imply absence, so the
+assignment is preserved until authoritative evidence is available. An assigned Lead can explicitly
 release Manager control with `/takeover`; after confirmation, the assignment
 and pending project messages are removed while its Pi session, conversation,
 branch, worktree, running process, and owned Agents remain. The continuing

package/docs/reference/commands.md

@@ -238,8 +238,9 @@ live assigned Lead. Manager staff reports contain only live exact Leads named
 by current project assignments; physical worktree scope alone grants no
 authority. Project assignments survive Manager replacement and manual
 continuation of the exact assigned Pi session. `managed-lead` is launch policy,
-not authority. Successful Herdr worktree removal retires an assignment; a
-missing worktree alone leaves it recoverable with `resume_project`.
+not authority. Successful Herdr worktree removal or verified checkout absence
+retires an assignment; failed or ambiguous inventory preserves it. A retired
+assignment cannot be resumed, though new work may use the remaining Git branch.
 
 An eligible ordinary Lead can activate runtime Chief mode with `/chief`.
 While Chief, `/chief` opens the overview and `/chief leave` exits the mode.

package/docs/reference/staff.md

@@ -40,9 +40,9 @@ Returns a fresh direct-report projection and fresh `available_tools`. For
 Manager, `work` lists durable project assignments by branch with derived status
 and a bounded task summary. Status is `active`, `paused`, or `conflict`; active
 work may include the live Lead's separate `runtime_state`. Paused work remains
-listed without a running Lead. A missing worktree can be reconstructed when
-resuming the assignment and its branch remains available. Work items do not
-expose assignment session IDs, workspace IDs, or pane IDs.
+listed without a running Lead. Verified checkout absence retires the assignment;
+unavailable or ambiguous Git inventory preserves it. Work items do not expose
+assignment session IDs, workspace IDs, or pane IDs.
 
 For Manager, `open_workspaces` separately reports current Herdr topology. It is
 not assignment ownership. A branch is the project-work handle; a report's
@@ -122,11 +122,10 @@ Manager only. Resume existing unresolved project work using its exact branch:
 
 The assignment must already exist; resume does not create or replace it.
 Resuming already-running work returns the current exact Lead instead of
-starting another. A stopped Lead is relaunched with the same assignment. If
-the worktree is missing, Herdsman recreates it from the existing branch and
-resumes the exact saved Pi session; its saved cwd is used when available. If
-the branch no longer exists, recovery fails closed rather than creating it
-from the current default branch.
+starting another. A stopped Lead is relaunched with the same assignment while
+its worktree exists. Verified checkout absence retires the assignment rather
+than recreating it. A retired assignment cannot be resumed; new work may use
+`delegate_project` with the remaining branch.
 
 ## `stop_lead`
 
@@ -139,9 +138,9 @@ execution tree. The assignment, Pi session, Git branch, and worktree are
 preserved. Resume the work with
 `resume_project` using its branch. An unassigned Lead is not a Manager staff-stop
 target. Failed or ambiguous cleanup does not retire an assignment. Successful
-Herdr worktree removal retires the assignment and removes pending project
-messages; a missing worktree alone leaves the assignment recoverable with
-`resume_project`. The
+Herdr worktree removal or verified checkout absence retires the assignment and
+removes pending project messages. Failed or ambiguous inventory preserves the
+assignment. The
 assigned Lead may separately release Manager authority through confirmed
 `/takeover`, which removes the assignment and pending project messages without
 stopping the session or owned Agents.

package/docs/reference/status-widget.md

@@ -96,12 +96,19 @@ Unmanaged or invalid agent environments do not receive the managed widget.
 
 ## Refresh
 
-The widget refreshes managed herdr data plus mailbox state every two seconds.
-
-Refresh performs a bounded herdr pane-list lookup to validate the lead
-boundary. It does not add a socket transport or another agent-control protocol.
-
-A refresh failure never mutates mailbox/control eligibility.
+Ordinary status refreshes on explicit requests and controller or Herdr
+invalidations, with a 10-second reconciliation while its TUI widget is active.
+Herdr events invalidate the view; presentation-only events refresh status but
+do not trigger health scans.
+
+Full Chief/Manager supervision observation is event- and local-invalidation-
+driven, with a 10-second reconciliation while active TUI supervision is
+enabled. The Manager elapsed-time widget redraws every two seconds for
+presentation, without acquiring a new authoritative snapshot.
+
+Headless mode has no UI-only periodic supervision observation. Explicit and
+model-context refreshes still acquire fresh state. A refresh failure never
+mutates mailbox/control eligibility.
 
 ## Lead execution
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdsman",
-  "version": "0.22.0",
+  "version": "0.22.2",
   "type": "module",
   "description": "Asynchronous Pi subagents and agent fleet orchestration for parallel coding agents with nested delegation, background work, and supervision in herdr.",
   "license": "Apache-2.0",