pi-herdsman 0.6.0 → 0.6.2

package/docs/agent-api.md

@@ -20,7 +20,7 @@ For an active chief supervising independent leads, use the [`staff` and
 ## Prerequisites
 
 Installation and supported versions are owned by
-[Getting started](getting-started.md#1-check-requirements). The lead Pi session
+[Getting started](getting-started.md#1-install). The lead Pi session
 must run inside [herdr](https://github.com/herdrdev/herdr).
 
 ## First use

package/docs/development/validation.md

@@ -31,10 +31,10 @@ git diff HEAD --check
 
 ## What `npm run check` does
 
-The repository check command runs the complete Node test set in one detached,
-isolated process group with a bounded suite deadline. Node's native TypeScript
-support strips types while loading the source, and the test runner discovers
-the `.test.ts` files automatically.
+The repository check command runs the complete Node test set in one isolated
+process tree with a bounded suite deadline. Node's native TypeScript support
+strips types while loading the source, and the test runner discovers the
+`.test.ts` files automatically.
 
 The test runner uses:
 
@@ -45,19 +45,24 @@ The test runner uses:
 
 ## Process containment
 
-The test runner runs in a detached POSIX process group.
+On POSIX systems the test runner runs in a detached process group. On Windows
+it runs as a normal child process and uses the native `taskkill.exe /PID <pid>
+/T /F` process-tree operation for timeout cleanup.
 
-On the suite deadline, the runner attempts:
+On POSIX suite deadline, the runner attempts:
 
 1. `SIGTERM`;
 2. a bounded grace period;
 3. `SIGKILL` when required;
-4. bounded proof that the process group disappeared.
+4. bounded proof that the process tree disappeared.
 
-A test runner that leaks descendants after normal exit is reported as a failure
-and cleaned through the same group boundary.
+On Windows, the runner invokes `taskkill.exe /PID <pid> /T /F` and waits for
+the runner process to disappear.
 
-Windows is not supported by this process-group validation runner.
+A test runner that leaks descendants after normal exit is reported as a failure
+on POSIX and cleaned through the same process-group boundary. Windows timeout
+cleanup covers the runner tree; post-parent descendant leak accounting would
+require a Job Object and is not implemented.
 
 ## Focused tests
 
@@ -97,8 +102,8 @@ the read-only verification step:
 npm run check
 ```
 
-`npm run check` remains the bounded full check, including process-group cleanup
-when the test runner times out or leaks descendants.
+`npm run check` remains the bounded full check, including platform-appropriate
+process-tree cleanup when the test runner times out or leaks descendants.
 
 ## Dependency availability
 

package/docs/guides/agent-definitions.md

@@ -219,6 +219,11 @@ Supported forms:
 @~/home-relative.md
 ```
 
+On Windows, the native backslash forms are also supported, including
+`@.\relative.md`, `@..\relative.md`, `@~\home-relative.md`, rooted paths,
+drive-rooted paths, and UNC paths. References use the host platform's native
+path resolution rules.
+
 References are resolved from the Markdown file that declares them.
 
 The bundled definitions are `generalist`, `implementer`, `researcher`,

package/docs/guides/handoffs.md

@@ -150,6 +150,10 @@ line has one of these shapes:
 @~/home-relative.md
 ```
 
+On Windows, native backslash forms are also supported, including `@.\relative.md`,
+`@..\relative.md`, `@~\home-relative.md`, rooted paths, drive-rooted paths,
+and UNC paths. References use the host platform's native path resolution rules.
+
 These remain literal text:
 
 ```text

package/docs/guides/recovery.md

@@ -50,7 +50,9 @@ recovery error is present, inspect its exact details.
 ## Inactivity advisory
 
 A `working` agent with an exact active assignment can become advisory `stale`
-after ten minutes without observed Pi turn, message, or tool activity.
+after ten minutes without qualifying execution progress. Model streaming,
+turn/message boundaries, and tool execution start/end boundaries count;
+streaming tool updates alone do not reset progress.
 
 Possible list fields:
 

package/docs/reference/agent-definition-schema.md

@@ -225,13 +225,18 @@ A body line is a reference only when the complete trimmed line matches:
 @~/home-relative/path
 ```
 
+On Windows, native backslash forms are also accepted, including `@.\relative`,
+`@..\relative`, `@~\home-relative`, rooted paths, drive-rooted paths, and UNC
+paths. References use the host platform's native path classification and
+resolution rules.
+
 Before bundled/global body composition, relative references are resolved from
 the definition file that declared them.
 
 When a new agent generation is constructed:
 
-1. references are processed in body order; `~/` is resolved beneath the
-   current user's home directory;
+1. references are processed in body order; `~/` (or `~\` on Windows) is
+   resolved beneath the current user's home directory;
 2. targets are canonicalized with `realpath`;
 3. each canonical file is included once;
 4. a caller `delegate.files` canonical overlap wins and removes the body copy;

package/docs/reference/agent-states.md

@@ -48,7 +48,11 @@ model metadata, missing activity, a guessed session, or an old agent identity.
 ## Inactivity fields
 
 A qualifying `working` agent may also report `stale`, `inactive_ms`, and
-`last_activity_at`. This advisory does not change the state or prove a hang.
+`last_activity_at`. Qualifying progress includes model streaming and tool
+execution boundaries (`tool_execution_start` and `tool_execution_end`), along
+with the surrounding turn and message boundaries. Streaming tool updates alone
+do not advance `last_activity_at`. This advisory does not change the state or
+prove a hang.
 
 ## See also
 

package/docs/reference/agent.md

@@ -150,8 +150,11 @@ when the exact message limit permits. Otherwise they remain canonical references
 
 `timeoutMs` is valid on `delegate` and `continue` and must be an integer
 from `5001` through `300000`. The startup budget reserves one bounded diagnostic
-window. Current message limits are governed by the Herdsman config file and its
-defaults, plus the fixed mailbox protocol ceiling. Managed mailbox records use
+window; it is unrelated to managed-agent Pi shell execution. Direct calls from
+a managed agent to the Pi built-in `bash` or `powershell` tool receive a default
+600-second timeout when the call omits `timeout`; an explicit timeout is kept
+unchanged. Current message limits are governed by the Herdsman config file and
+its defaults, plus the fixed mailbox protocol ceiling. Managed mailbox records use
 protocol V4 in the `mailboxes-v4` namespace, and control requests use the marker prefix
 `__PI_HERDSMAN_AGENT_V4__:`.
 

package/docs/reference/status-widget.md

@@ -75,9 +75,9 @@ Example:
 
 The header reports exact non-zero lifecycle states in the order `working`,
 `blocked`, `settling`, `starting`, and `unknown`. `starting` is a
-presentation-only count for assignments whose final label and mailbox claim
-are known but whose authoritative agent startup has not completed. It is not
-mailbox state, control authority, or Running inventory.
+presentation-only count for controller-local assignments that have begun
+startup but have not yet become active or terminal. It is not mailbox state,
+control authority, or Running inventory.
 
 Before the first successful refresh, the header says `unavailable`.
 
@@ -103,10 +103,13 @@ useful room before it is truncated.
 
 Working rows use `● working`, blocked rows use `◐ blocked`, settling rows use
 `◌ settling`, starting rows use `◌ starting`, and unknown rows use `? unknown`.
-Working, settling, and starting animate; blocked and unknown rows are static. A
-starting row is reconciled away
-when authoritative agent evidence replaces it, and is removed on startup
-failure, rollback, repeated session start, or shutdown.
+Working, settling, and starting animate; blocked and unknown rows are static.
+While a controller-local start remains pending, an authoritative `settling`
+row is presented as `starting` so launch and request handoff remain visually
+continuous. `working`, `blocked`, and `unknown` authoritative states are never
+overridden. A starting row is removed when its exact request becomes active or
+terminal, its local runtime is removed, startup fails or rolls back, the
+controller session restarts, or shutdown clears transient state.
 
 `Running` inspection shows every authoritative agent row and excludes
 presentation-only starting rows. A terminal result is followed by cleanup; the

package/package.json

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