pi-herdsman 0.7.1 → 0.7.3

package/docs/concepts/delegation.md

@@ -84,21 +84,35 @@ Do not:
 
 - delegate overlapping writers to one worktree;
 - delegate review before the writer finishes;
-- duplicate supplied reconnaissance;
-- continue dependent work while a required agent is active.
+- repeat work already assigned to an active agent;
+- delegate substantially overlapping work to multiple active agents;
+- continue work that depends on an active agent result;
+- inspect, list, or steer active agents merely to check progress or completion.
 
-A useful pattern is:
+Direct ownership grants lifecycle and control authority. It does not make the
+owner a second executor of an active delegated assignment.
+
+A useful parallel pattern is:
 
 ```text
-delegating agent
-├── scout: bounded reconnaissance
-└── local independent analysis
+controller
+├── agent A: independent reconnaissance
+├── agent B: separate independent analysis
+└── local: bounded independent controller work
+
+local work becomes sufficiently complete
+↓
+controller ends its turn
 
-agent result arrives
+agent result or attention resumes the controller
 ↓
-delegating agent integrates both
+controller integrates and reassesses
 ```
 
+Parallelism is optional. Do not create additional assignments or local side work
+merely to keep the controller active. For the full turn-navigation model, see
+[Asynchronous orchestration](lifecycle.md#asynchronous-orchestration).
+
 ## Clarification across ownership edges
 
 An agent may ask its exact direct owner through `ask_owner`.

package/docs/concepts/lifecycle.md

@@ -77,26 +77,49 @@ restart recovery. The agent then runs independently in its managed Pi session
 while the owner remains available for other useful work and, for a lead Pi
 session, continued user interaction.
 
-The owner must not poll for completion. It may continue with work that does not
-depend on the result or end its turn normally. Agent completion or an
-`ask_owner` question is delivered back to that same owner when attention is
-required.
+Each active delegated assignment has one executor: that agent. The owner retains
+lifecycle and control authority but does not repeat the delegated assignment
+locally or assign substantially overlapping work elsewhere.
+
+After starting an agent assignment or receiving an agent result or attention
+event, the owner reassesses the remaining work:
+
+1. Handle required agent control when needed.
+2. Delegate another concrete, necessary objective when it is independent of
+   active assignments and an authorized agent is the right owner.
+3. Continue concrete, necessary independent work locally when the owner is the
+   right owner and doing it now materially advances the task.
+4. Otherwise end the turn.
+
+After control, delegation, or local parallel work, the owner reassesses again.
+Once further useful progress depends on active agents, or no other concrete,
+necessary independent work remains, it ends the turn. Agent results,
+clarifications, and recovery attention resume the session automatically.
+
+The owner does not invent side work merely because agents are running. It does
+not poll, sleep, inspect merely for progress, send status steering, or use
+another mechanism to keep the turn alive.
 
 Conceptually:
 
 ```text
-assignment accepted
-       ↓
-owner remains available
-       ↓
-agent runs independently
-       ↓
-result or question returns to the owner
+assignment or agent event
+          ↓
+reassess remaining work
+    ↙        ↓        ↘
+ control   parallel   no useful
+            work      action
+          ↙     ↘        ↓
+      delegate  local  end turn
+          \      /        ↓
+           reassess   agent event resumes
 ```
 
-This is asynchronous but not fire-and-forget. The owner retains explicit
-assignment ownership, can steer eligible active work, receives clarification
-requests, and remains responsible for result delivery and lifecycle control.
+This is asynchronous but not fire-and-forget. The owner retains lifecycle and
+control authority: it can steer eligible active work when the assignment
+actually changes, receives clarification requests, and remains responsible for
+result delivery and cleanup. The delegated agent remains the executor of its
+active assignment.
 
 ## Exactly-once assignment result
 

package/docs/development/smoke-testing.md

@@ -155,25 +155,42 @@ Verify:
 6. agent produces exactly one final result;
 7. no agent/mailbox leak remains.
 
-## Delegating-agent natural waiting
+## Delegating-agent turn ending
 
-Ask a delegating agent to delegate required reconnaissance when no useful independent
-local work remains.
+Ask a delegation-enabled controller to delegate required reconnaissance when no
+other concrete, necessary independent work is known.
 
 Inspect the actual transcript and verify the delegating agent:
 
-- ends its turn normally after the assignment;
+- ends its turn after the assignment when nothing else useful is independently actionable;
+- does not repeat the delegated reconnaissance locally;
+- does not manufacture adjacent analysis merely to remain active;
+- does not delegate substantially overlapping reconnaissance to another agent;
 - does not poll `agent list`;
-- does not sleep or use a separate wait mechanism;
-- wakes when the agent result is delivered;
+- does not use `agent inspect` or `agent steer` merely to check progress;
+- does not send "finish", "status", or equivalent progress nudges to a healthy
+  agent;
+- does not sleep or use another mechanism to keep the turn alive;
+- the agent result resumes the controller session;
 - integrates the result into one final delegating agent outcome.
 
 ## Useful concurrency
 
-Give a delegating agent one delegated task A and independent local task B.
+Delegate bounded task A and give the controller concrete, necessary independent
+local task B.
 
-Verify it can work on B while A is active, then ends its turn when no useful
-independent work remains and integrates A after result delivery.
+Verify:
+
+- B proceeds while A is active;
+- B does not repeat A's assigned scope;
+- once B is sufficiently complete, the controller reassesses instead of
+  manufacturing more work;
+- if further useful progress depends on A, the controller ends its turn;
+- A's result resumes the controller and is integrated.
+
+Also verify a controller with two already-known independent delegated objectives
+may delegate A and B before ending its turn. It must not create a third
+assignment merely to increase concurrency.
 
 ## Lead `/agents` commands
 

package/docs/guides/recovery.md

@@ -101,6 +101,27 @@ The normal response is to inspect the returned stage/diagnostic and the current
 herdr environment. Do not add client-side polling or arbitrary sleeps as an
 operator workaround.
 
+Managed Herdr panes must be able to reach their interactive shell prompt
+without requiring human input. Shell startup that waits for a question,
+confirmation, first-run wizard, credential prompt, or similar interaction can
+prevent agent startup.
+
+Herdr sets `HERDR_ENV=1` in pane processes, so shell configuration can use that
+marker to disable interactive startup behavior only inside Herdr.
+
+For example, with Oh My Zsh, place this before sourcing Oh My Zsh:
+
+```zsh
+[[ ${HERDR_ENV:-} == 1 ]] && zstyle ':omz:update' mode disabled
+```
+
+Normal terminals keep their configured update behavior; Herdr panes skip
+automatic Oh My Zsh update checks. Run `omz update` manually when desired.
+
+If startup still fails, inspect the returned `pane_readiness` stage and bounded
+pane diagnostic rather than adding arbitrary sleeps or automatically answering
+terminal prompts.
+
 ## Cleanup or rollback failure
 
 A `rollback_failure` can contain both:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdsman",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "type": "module",
   "description": "Asynchronous Pi subagents and agent fleet orchestration with nested delegation, parallel execution, and supervision in herdr.",
   "license": "Apache-2.0",