pi-herdsman 0.9.0 → 0.10.1

package/SKILL.md

@@ -45,15 +45,26 @@ State describes what is happening; available_actions describes current control
 eligibility. Every operation revalidates exact state and identity before
 mutation.
 
-The live-agent control actions are `steer`, `reply`, and `close`; these mutate
+The live-agent control actions are `steer`, `interrupt`, `reply`, and `close`;
+these mutate
 live agent execution and are available only when listed. Read-only `inspect`
 captures bounded live terminal/process evidence. Read-only `transcript` captures
 bounded persisted Pi conversation and tool evidence when listed. Neither changes
 agent state. A completed agent does not remain available for another assignment.
 
-Use steer only to change active work. Use reply only to answer a valid
-outstanding ask_owner question. Use close only for intentional teardown or
-abandonment.
+Use steer only to change active work non-preemptively. Steering does not cancel
+an in-flight model or tool operation; Pi may queue it until the current
+operation reaches a safe boundary.
+
+Use interrupt only when the current in-flight operation itself must be
+abandoned. Interrupt is preemptive: it cancels the current Pi operation,
+supersedes any earlier steering that Pi has not yet delivered, and continues
+the same assignment with the required replacement message. Do not interrupt
+merely because an agent is slow or marked stale; inactivity is advisory and
+does not prove a hang.
+
+Use reply only to answer a valid outstanding ask_owner question. Use close only
+for intentional teardown or abandonment.
 
 A lost agent is a managed assignment whose exact physical execution is proven
 gone before a durable terminal result resolved it. Loss is not completion or
@@ -97,7 +108,7 @@ If list reports result_error, do not start a new delegation over unresolved
 work. Resolve mailbox persistence first, then close the exact agent before
 starting another assignment; follow the stored recovery nextAction.
 
-Before delegate, continue, steer, or reply, make the message self-contained.
+Before delegate, continue, steer, interrupt, or 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
@@ -293,6 +304,42 @@ retry destructive cleanup blindly, or silently take over delegated work.
 See [Recovery](docs/guides/recovery.md) for operator procedures and the
 [`agent` API](docs/reference/agent.md) for the exact machine contract.
 
+## Health attention and turn completion
+
+End a turn with unresolved agent work only when that work can still make
+progress without the owner, or Herdsman is reconciling a durable transition
+that can produce a future result or attention event. If an attention event
+requires owner action, handle it before returning to passive waiting. If an
+inactivity advisory appears healthy or legitimately long-running, leave it
+alone and end the turn; Herdsman will reconcile it again.
+
+Health reconciliation is event-driven with a 30-second fallback scan. Actionable
+health attention is sent only to the exact direct owner and is based on freshly
+reconciled state. Persistent state-specific attention may repeat while the
+condition remains unresolved. Reminder timing is process-local and advisory;
+restarting Herdsman can cause an unresolved condition to be reminded again.
+
+The first stale advisory remains at ten minutes without qualifying execution
+progress. Persistent attention repeats approximately `5m → 2m30s → 1m15s →
+1m` with 30-second scan granularity. Stale attention is advisory, not proof of
+a hang. Lost and delivered `ask_owner` attention retain their existing message
+identity, while `result_error`, external runtime `blocked`, old unacknowledged
+handoffs, and physical `unknown` use generic attention. An unresolved
+unacknowledged request must not be duplicated or resubmitted: retained work is
+not proof of non-delivery.
+
+Use the event's current `available_actions` as advisory snapshot authority;
+every action revalidates identity, ownership, and lifecycle. Use `transcript`
+for persisted conversation and tool evidence, and `inspect` for live
+terminal/process evidence. `steer` is cooperative and non-preemptive;
+`interrupt` cancels the current operation, supersedes earlier steering Pi has
+not yet delivered, and continues the same assignment.
+Do not add automatic interrupt, close, restart, or redelegation. Physical
+`unknown` remains fail-closed, has no mutation actions, and receives at most one
+attention event per unresolved episode. `settling` alone is not a generic
+attention condition. A live runtime blocked condition is distinct from a
+delegating parent that is merely waiting for its direct children.
+
 ## Chief and staff
 
 Ordinary leads own their complete herd, including every agent beneath them. The