pi-herdsman 0.13.0 → 0.13.2

package/docs/concepts/delegation.md

@@ -89,8 +89,20 @@ Do not:
 - continue work that depends on an active agent result;
 - inspect, transcript, list, or steer active agents merely to check progress or completion.
 
-Direct ownership grants lifecycle and control authority. It does not make the
-owner a second executor of an active delegated assignment.
+Each unresolved unit of work has exactly one executor.
+
+Delegating a scope transfers execution ownership of that scope to the delegated
+agent until the assignment resolves. The delegator retains responsibility for
+coordination and may continue work it still owns, but it does not execute the
+delegated scope or assign substantially overlapping work elsewhere.
+
+After delegation succeeds, the delegated scope is no longer part of the
+controller's execution scope. The controller may continue only concrete,
+necessary work clearly outside that scope that it still owns; otherwise it ends
+the turn and waits for automatic result or attention delivery.
+
+After the assignment resolves, the delegator may integrate, validate,
+synthesize, or assign follow-up work from the result.
 
 A useful parallel pattern is:
 

package/docs/concepts/lifecycle.md

@@ -77,9 +77,16 @@ 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.
 
-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.
+During an active delegated assignment, the delegated agent is its executor. The
+owner retains lifecycle and control authority; see [Delegation](delegation.md)
+for the execution-ownership boundary.
+
+Result delivery resolves that delegated execution ownership and enables the
+owner to integrate the result before reassessing the remaining work.
+
+After starting an assignment, remove its delegated scope from the controller's
+execution scope immediately. Continue only necessary work the controller still
+owns; otherwise end the turn.
 
 After starting an agent assignment or receiving an agent result or attention
 event, the owner reassesses the remaining work:
@@ -87,19 +94,24 @@ 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.
+3. Continue only necessary work the controller still owns when the controller
+   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.
+necessary independent work remains, it ends the turn. Agent results or attention
+will resume the session automatically.
 
 The owner does not invent side work merely because agents are running. It does
 not poll, sleep, inspect or transcript merely for progress, send status steering, or use
 another mechanism to keep the turn alive.
 
+Routine progress checking remains prohibited. A stale health-attention event is
+different: it is an unsolicited diagnostic boundary. Use its attached evidence
+first; if that evidence is absent or insufficient, perform at most one bounded
+diagnostic read before passive waiting.
+
 Health reconciliation follows the same boundary. It is event-driven, with a
 30-second fallback scan for durable and physical state that has not emitted a
 separate event. Each scan reconciles fresh mailbox and Herdr evidence for the
@@ -128,14 +140,25 @@ blocked while waiting for direct children is progress-capable and is not the
 same as Herdr reporting that the managed child runtime is blocked.
 
 When attention arrives, the owner handles a required action before ending the
-turn. For evidence, use `transcript` for persisted Pi conversation and tool
-history, and `inspect` for live terminal/process state. Leave healthy or
-legitimately long-running stale work alone. Use `steer` for a cooperative
-non-preemptive correction, `interrupt` to cancel the current operation,
-supersede earlier undelivered steering, and continue the same assignment,
-`close` to abandon an assignment, and
-`reply` only for the exact pending owner question. Do not poll or keep the turn
-alive solely to wait for agent progress.
+turn. For stale attention:
+
+1. Read the bounded evidence supplied with the first stale attention.
+2. If that evidence is absent or insufficient, use one bounded diagnostic read:
+   `transcript` for persisted history or `inspect` for live terminal/process
+   state.
+3. If healthy or legitimately long-running, leave the agent alone.
+4. Use `steer` for a cooperative non-preemptive correction.
+5. Use `interrupt` only when the current operation must be abandoned; it cancels
+   the operation, supersedes earlier undelivered steering, and continues the
+   same assignment.
+6. Use `close` only when abandoning the assignment is intended.
+7. Do not repeat reads merely because the same stale episode was reminded
+   again.
+
+For other attention, use `transcript` for persisted Pi conversation and tool
+history and `inspect` for live terminal/process state as needed. Use `reply` only
+for the exact pending owner question. Do not poll or keep the turn alive solely
+to wait for agent progress.
 
 Conceptually:
 

package/docs/development/documentation.md

@@ -85,34 +85,32 @@ Do not mix these procedures into normal user setup.
 
 ### `SKILL.md`
 
-Optional model-facing reinforcement of the self-contained runtime operational
-contract plus deeper strategy, rationale, examples, and recovery guidance.
+Optional model-facing reinforcement of the runtime operational contract plus
+deeper strategy, rationale, examples, and recovery guidance.
 
 It does not own product API schemas or runtime behavior.
 
-## Runtime and skill synchronization
+## Runtime and skill authority
 
-Pi Herdsman has one deliberate instruction duplication.
+Runtime behavior and runtime model contracts own operational semantics.
 
-The runtime controller and managed agent instructions are the authoritative,
-self-contained operational contract. Root `SKILL.md` intentionally mirrors
-those mandatory operational instructions so loading the skill can reinforce
-them in a long model context.
+`SKILL.md` may reinforce high-salience runtime invariants and add strategy,
+rationale, examples, and recovery detail, but it is not a second normative
+owner.
 
-Therefore:
+When runtime guidance changes:
 
-- every mandatory operational rule must exist at runtime;
-- corresponding operational guidance must remain represented in `SKILL.md`;
-- `SKILL.md` may add strategy, rationale, examples, and deeper explanation;
-- no capability or normal workflow may depend on loading `SKILL.md`;
-- runtime wins if the two surfaces conflict;
-- a change to either mirrored runtime or skill instructions requires checking
-  the other side in the same change.
+- update the authoritative runtime contract first;
+- update affected skill or documentation projections;
+- remove obsolete reinforcement rather than preserving historical wording;
+- keep the runtime sufficient when `SKILL.md` is not loaded.
 
-This is intentional reinforcement, not competing authority.
+A behavioral invariant may be reinforced at multiple model-facing decision
+points when timing or salience materially affects reliability. Those projections
+must preserve one meaning and must not evolve into independent rules.
 
-Do not replace it with runtime skill loading, generated prompt files, a prompt
-registry, or another synchronization subsystem.
+Do not add runtime skill loading, prompt generation, or another synchronization
+framework merely to keep prose copies aligned.
 
 ## Style
 

package/docs/guides/handoffs.md

@@ -14,10 +14,19 @@ canonical local references and are not copied or snapshotted.
 
 ## Message `files`
 
-For `delegate`, `continue`, `steer`, `interrupt`, and
-`reply`, make the message self-contained. Do not attach or mention agent
-instruction files such as `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or equivalents
-merely because they exist; rely on normal project or runtime discovery.
+Agent-session context crosses boundaries explicitly.
+
+- task or message text and `files` carry assignment-specific evidence;
+- `fork` and `continue` deliberately select saved Pi history;
+- the caller's conversation and caller-side attachments are not implicitly
+  copied into another agent session.
+
+When a new or updated assignment depends on a caller-visible file, pass that
+file through `files`.
+
+Do not attach or mention agent instruction files such as `AGENTS.md`, `CLAUDE.md`,
+`GEMINI.md`, or equivalents merely because they exist; rely on normal project
+or runtime discovery.
 
 Attach an agent instruction file only when the task requires inspecting,
 modifying, comparing, or transmitting it, the user explicitly requests it, or

package/docs/guides/recovery.md

@@ -13,17 +13,20 @@ and it is published only when the owner is idle. Read the exact condition and
 the event's current `available_actions` before acting; the eventual action
 rechecks identity, ownership, mailbox state, and lifecycle.
 
-Use this decision sequence:
-
-1. Need persisted conversation or tool history? Use `transcript`.
-2. Need live terminal or process evidence? Use `inspect`.
-3. Is the work healthy or legitimately long-running? Leave it alone.
-4. Is a cooperative correction needed? Use `steer`.
-5. Must the current operation itself be abandoned? Use `interrupt`; it cancels
+For stale attention, use this decision sequence:
+
+1. Read the bounded evidence supplied with the first stale attention.
+2. If that evidence is absent or insufficient, use one bounded diagnostic read:
+   `transcript` for persisted history or `inspect` for live terminal/process
+   state.
+3. If healthy or legitimately long-running, leave the agent alone.
+4. Use `steer` for cooperative correction.
+5. Use `interrupt` only when the current operation must be abandoned; it cancels
    that operation, supersedes earlier undelivered steering, and continues the
    same assignment.
-6. Is the assignment being abandoned? Use `close`.
-7. Is an owner decision pending? Use `reply` for the exact pending question.
+6. Use `close` only when abandoning the assignment is intended.
+7. Do not repeat reads merely because the same stale episode was reminded
+   again.
 
 Persistent actionable conditions may repeat approximately `5m → 2m30s →
 1m15s → 1m`, with 30-second scan granularity. Reminder state is process-local

package/docs/reference/agent-states.md

@@ -108,6 +108,9 @@ approximately `5m → 2m30s → 1m15s → 1m`, subject to the 30-second health s
 Leave healthy or legitimately long-running work alone. Use `transcript` for
 persisted evidence and `inspect` for live evidence; stale alone does not justify
 `interrupt` or `close`.
+The stale episode is defined by its active request and last qualifying activity;
+first-attention diagnosis is bounded, and repeated reminders do not automatically
+repeat the live capture.
 
 ## See also
 

package/docs/reference/agent.md

@@ -159,6 +159,12 @@ cadence is approximately `5m → 2m30s → 1m15s → 1m` with 30-second scan
 granularity. The first stale advisory remains eligible after ten minutes
 without qualifying execution progress.
 
+The first stale attention for an episode attempts one bounded live inspect
+capture when inspect is currently authorized. The automatic capture has a short
+health-path deadline and does not change agent state. The stale message may
+carry the same live evidence fields exposed by inspect. Repeated reminders for
+the same episode do not automatically capture again.
+
 Generic attention reasons are:
 
 - `result_error`: a terminal result could not be durably persisted; follow the
@@ -185,11 +191,13 @@ first observes that the original ask was successfully delivered. The reminder
 path never duplicates first ask delivery. Unknown is the exception to repeated
 attention: it is one notification per unresolved physical-identity episode.
 
-For recovery evidence, use `transcript` for persisted Pi conversation and tool
-history, and `inspect` for live terminal/process evidence. Use `steer` for a
-cooperative correction. Use `interrupt` only to cancel the current operation;
-it supersedes earlier undelivered steering and continues the same durable
-assignment. Use `close` only when abandoning the
+For stale recovery, use supplied evidence first. If it is absent or
+insufficient, perform at most one bounded diagnostic read: `transcript` for
+persisted conversation/tool history or `inspect` for live terminal/process
+evidence. Do not repeat a read solely because the same stale episode was
+reminded again. Use `steer` for a cooperative correction. Use `interrupt` only
+to cancel the current operation; it supersedes earlier undelivered steering and
+continues the same durable assignment. Use `close` only when abandoning the
 assignment is intended. Do not poll or create another delivery path for health
 attention.
 
@@ -257,6 +265,11 @@ limit permits. Otherwise they remain canonical references. Semantic direct refs
 are resolved on the current branch, while canonical `result:<request-id>` refs
 remain logical result references. `files` is a `string[]` for all three forms.
 
+`files` is explicit per-message evidence. A fresh delegated session does not
+implicitly receive the caller's conversation or caller-side attachments.
+`fork` and `continue` are the mechanisms that deliberately reuse selected saved
+Pi history.
+
 `timeoutMs` is valid on `delegate` and `continue` and must be an integer
 from `5001` through `300000`. The startup budget reserves one bounded diagnostic
 window; it is unrelated to managed-agent Pi shell execution. Direct calls from

package/package.json

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