pi-herdsman 0.5.2 → 0.6.1

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/concepts/agents.md

@@ -9,9 +9,10 @@ whose assignment lifecycle is coordinated through the extension mailbox.
 
 ### Agent definition
 
-The **agent definition** selects the agent's model, reasoning policy, tools,
-skills, extensions, prompt body, context inheritance, and allowed direct
-agents.
+The **agent definition** may override the agent's model and reasoning policy,
+and selects its tools, skills, extensions, prompt body, context inheritance,
+and allowed direct agents. Fresh agents otherwise inherit model and thinking
+from their spawning controller session.
 
 Example: `reviewer`.
 
@@ -107,9 +108,11 @@ cleanup path.
 
 The Pi session remains available after agent cleanup. To continue the same
 conversational context, use `continue` with the exact session ID or session path
-returned with the result. This creates a new agent generation, which uses the
-current effective authorized configuration for the saved agent definition. To
-derive a separate context instead, use `fork` on a `delegate` action.
+returned with the result. This creates a new agent generation, which restores
+the saved session's model and thinking unless the current definition
+explicitly overrides either field. To derive a separate context instead, use
+`fork` on a `delegate` action; fork is a fresh delegation and inherits from its
+spawning controller when those fields are omitted.
 
 The identities are therefore:
 

package/docs/concepts/lifecycle.md

@@ -106,8 +106,10 @@ Agent cleanup does not delete the Pi session. To continue completed context,
 use the exact returned session with `continue`; Pi Herdsman starts a new agent
 generation for the new assignment. The continuation uses the saved cwd, session
 history, definition, and logical label together with the current effective
-authorized definition configuration. The caller cannot rename the continued
-session. Use `delegate` with `fork` when a separate derived session is required.
+authorized definition configuration. Its omitted model and thinking fields
+restore the saved session settings, while explicit definition fields override
+them. The caller cannot rename the continued session. Use `delegate` with
+`fork` when a separate derived session is required.
 Session continuation does not retain the old Herdr tab. A still-live
 generation may be restored from its exact managed identity, while ordinary
 same-workspace tab movement remains presentation-only and does not change

package/docs/development/smoke-testing.md

@@ -70,7 +70,8 @@ Verify:
 - a new agent generation, run ID, request ID, and pane are created;
 - the saved logical label is reused exactly (there is no continuation label override);
 - the saved conversation context is available;
-- the current effective definition configuration is used;
+- the current effective definition configuration is used, with omitted model and
+  thinking fields restoring the saved session settings;
 - exactly one result reaches the owner;
 - cleanup removes the second agent, pane, mailbox, and runtime.
 
@@ -188,7 +189,7 @@ Verify the native Definitions selector shows:
   (`[project] *` means both layers contribute);
 - compact, aligned name/model/thinking columns, including Unicode names;
 - model, thinking, enabled, and details actions for a selected definition;
-- `Use default` for model and thinking;
+- `Inherit current session` for model and thinking;
 - narrow panes remain width-safe.
 
 Structured `agent list` should still retain exact deterministic metadata.
@@ -198,9 +199,10 @@ model, thinking, and enabled state. Confirm that project discovery requires Pi
 project trust and that these edits write global overrides only, not project
 files.
 
-Verify unrelated frontmatter and body remain unchanged, `Use default` removes
-only the selected field, fresh definition delegations and session continuations
-use the current effective value, and running agents are not mutated.
+Verify unrelated frontmatter and body remain unchanged, `Inherit current session`
+removes only the selected field, fresh definition delegations inherit the
+spawning controller's current value, continuations restore the saved session's
+value, and running agents are not mutated.
 
 ### `/agents placement`
 

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/getting-started.md

@@ -6,7 +6,7 @@ This is the shortest human-facing path from installation to useful Pi Herdsman
 orchestration. You do not need to type structured `agent` requests for this
 path.
 
-## 1. Check requirements
+## 1. Install
 
 You need:
 
@@ -14,26 +14,29 @@ You need:
 - Pi `>=0.84.2 <0.86.0` (supported);
 - Node `>=22.19.0`.
 
-Install or refresh the herdr Pi integration:
+Install the package and herdr Pi integration:
 
 ```sh
+pi install npm:pi-herdsman
 herdr integration install pi
-herdr integration status
 ```
 
-Install the package from npm:
+## 2. Start Herdr and Pi
+
+Start Herdr in your project:
 
 ```sh
-pi install npm:pi-herdsman
+herdr
 ```
 
-Pi reads the package manifest and loads the extension plus the optional
-`agents` skill.
+Then run Pi in the Herdr pane:
 
-## 2. Start the lead Pi session inside herdr
+```sh
+pi
+```
 
-The lead Pi session must run inside herdr. A lead Pi session started outside herdr
-cannot safely manage herdr agents.
+Pi reads the package manifest and loads the extension plus the optional `agents`
+skill. A lead Pi session started outside Herdr cannot safely manage Herdr agents.
 
 The extension distinguishes a lead Pi session, valid managed agents, and
 unmanaged or invalid environments. Only supported managed environments receive
@@ -41,10 +44,10 @@ Pi Herdsman controls and status UI.
 
 ## 3. Delegate work without leaving the conversation
 
-Ask the lead Pi agent in ordinary language, for example:
+Ask Pi normally:
 
 ```text
-Use an implementer agent to implement the approved change.
+Use scout to inspect this repository.
 ```
 
 Pi Herdsman starts the work asynchronously. Once the assignment is accepted, the

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`,
@@ -248,8 +253,9 @@ The human `Definitions` menu includes bundled, project, and global
 participation. Project participation is marked `[project]`; a global override
 adds `*`, so `[project] *` means both layers contribute. Model, thinking, and
 enabled settings can be changed through the menu, but edits always write global
-overrides. `Use default` removes only that field and inherits the next lower
-layer or Pi's normal default.
+overrides. `Inherit current session` removes only that field. Unset model and
+thinking fields inherit the spawning controller for fresh delegation, while
+continuation restores the saved session's settings.
 
 ## Override an existing bundled role
 

package/docs/guides/customizing-agents.md

@@ -115,8 +115,9 @@ The path is resolved relative to the declaring project or global file before
 body composition, so each layer preserves its own declaring-file provenance.
 
 References expand when each new agent generation is constructed. A session
-continuation keeps the saved Pi history but uses the current effective
-definition configuration for its new generation.
+continuation keeps the saved Pi history and uses the current effective
+definition configuration for its new generation; omitted model and thinking
+fields retain the saved session's settings.
 
 The Definitions details view re-resolves the selected name when opened, so
 metadata and body references reflect current overlays even if configuration
@@ -207,11 +208,10 @@ Model
 Thinking
 Enabled
 Details…
-Back
 ```
 
-Model and thinking each offer `Use default` plus their available values.
-Selecting `Use default` removes only that field. The model chooser stores the
+Model and thinking each offer `Inherit current session` plus their available
+values. Selecting `Inherit current session` removes only that field. The model chooser stores the
 canonical provider/model token; thinking uses the selected model's supported
 levels when available. `Enabled` toggles the definition.
 
@@ -221,17 +221,18 @@ edited through the same flow.
 It changes only the selected top-level line in the global Markdown override and
 preserves unrelated frontmatter, line endings, and body content.
 
-Removing a saved field from a bundled definition restores its bundled value.
-Removing a field from a standalone definition uses Pi's normal default. The
-override file is not deleted.
+Removing a saved model or thinking field inherits the spawning controller for a
+fresh delegation, or the saved session for a continuation. The override file
+is not deleted.
 
 Enable and disable write the scalar `enabled` field in the same global override.
 Removing that field inherits the bundled value, or `true` when no source
 declares it.
 
-Changes affect future `delegate` assignments and `continue` assignments, whose
-runtime configuration comes from the current effective definition. They do not
-mutate an already-running agent or the lead Pi session.
+Changes affect future assignments. Fresh `delegate` assignments inherit unset
+execution fields from their spawning controller; `continue` restores saved
+session settings. They do not mutate an already-running agent or the lead Pi
+session.
 
 ## See also
 

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
@@ -206,7 +210,9 @@ Original body source paths are never handed to Pi as system-prompt paths.
 
 Each agent generation builds its system prompt once for its single assignment.
 Session continuation builds a new generation with the current effective
-definition configuration while preserving the saved Pi session context.
+definition configuration while preserving the saved Pi session context. Its
+omitted model and thinking fields restore the saved session settings; explicit
+definition overrides still apply.
 
 ## Result handoff
 

package/docs/guides/recovery.md

@@ -126,7 +126,9 @@ session identity. If the definition no longer exists, continuation fails instead
 of guessing a replacement; a missing or malformed session identity also fails
 closed. The definition must also be enabled and authorized for the current
 controller, and its current effective configuration is used for the new agent
-generation. Continuation cannot override or regenerate its saved label.
+generation. Omitted model and thinking fields restore the saved session
+settings; explicit definition fields override them. Continuation cannot
+override or regenerate its saved label.
 
 An exact session that is already represented by active or unresolved managed
 work cannot be activated concurrently. The session-start exclusion applies to

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

@@ -63,6 +63,25 @@ Precedence is `bundled < project < global`.
 All effective definitions are sorted and validated together, including every
 `agents` reference.
 
+## Execution settings
+
+`model` and `thinking` are independent optional overrides. An omitted field is
+inherited according to this precedence:
+
+| Operation                                       | Omitted `model` or `thinking`          |
+| ----------------------------------------------- | -------------------------------------- |
+| fresh `delegate`                                | current spawning controller session    |
+| `delegate` with `fork`                          | current spawning controller session    |
+| nested fresh `delegate`                         | current spawning managed-agent session |
+| `continue`                                      | saved Pi session                       |
+| any operation with an explicit definition field | explicit definition value              |
+
+Model and thinking resolve independently, so either field can be explicit while
+the other inherits. A nested agent inherits from its managed parent, not from
+the root lead. Pi clamps a thinking level to the selected model's capabilities.
+Fresh-delegation settings are snapshotted at launch; changing the controller
+does not change an active agent.
+
 `enabled` controls definition availability. A disabled definition remains in the
 lead roster so it can be enabled again, but owner-visible definition lists omit
 it. `delegate` and `continue` reject a disabled definition. An already
@@ -71,28 +90,28 @@ available actions; disabling a definition does not mutate that assignment.
 
 ## Fields
 
-| Field                   | Accepted value                                                        | Omitted/default behavior                                          | Runtime/composition behavior                                                                           |
-| ----------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `name`                  | non-empty string                                                      | required                                                          | Effective definition identity.                                                                         |
-| `enabled`               | boolean                                                               | `true`                                                            | `false` makes `delegate` and `continue` unavailable; it does not mutate an active agent.               |
-| `description`           | string                                                                | absent                                                            | Display/selection description.                                                                         |
-| `model`                 | non-empty string                                                      | Pi default/current launch behavior                                | Passed as Pi model selection.                                                                          |
-| `thinking`              | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or `false` | Pi default/current launch behavior                                | `false` launches as `off`.                                                                             |
-| `systemPromptMode`      | `append` or `replace`                                                 | `append` only for definition name `delegate`; otherwise `replace` | Controls effective body versus Pi base system prompt.                                                  |
-| `bodyMode`              | `append` or `replace`                                                 | `replace` for non-empty matching overlay body                     | Valid only when overlaying an existing lower-precedence definition; consumed during body composition.  |
-| `noTools`               | boolean                                                               | Pi normal tool policy                                             | `true` emits `--no-tools`; managed `ask_owner` remains infrastructure.                                 |
-| `noBuiltinTools`        | boolean                                                               | Pi normal built-in tool policy                                    | `true` emits `--no-builtin-tools`.                                                                     |
-| `tools`                 | array of non-empty strings                                            | no explicit allowlist                                             | Passed to Pi as a source-agnostic tool-name allowlist; matching overlay replaces whole array.          |
-| `excludeTools`          | array of non-empty strings                                            | no explicit exclusions                                            | Passed to Pi as source-agnostic tool-name exclusions; matching override replaces whole array.          |
-| `permission`            | mapping                                                               | absent                                                            | Opaque interoperability policy for permission-aware extensions; Pi Herdsman does not evaluate it.      |
-| `noSkills`              | boolean                                                               | skills disabled unless `inheritSkills: true`                      | Controls Pi native skill discovery; explicit `skills` values are still passed separately.              |
-| `inheritSkills`         | boolean                                                               | does not enable by itself unless `true`                           | `true` changes omitted `noSkills` default so native skills remain available. Explicit `noSkills` wins. |
-| `skills`                | array of non-empty strings                                            | no explicit skill arguments                                       | Each value is passed unchanged as a Pi skill path/resource.                                            |
-| `noExtensions`          | boolean                                                               | Pi normal extension policy                                        | `true` emits `--no-extensions`. Required herdr agent infrastructure remains injected by the launcher.  |
-| `extensions`            | array of non-empty strings                                            | no extra extension arguments                                      | Each value is passed unchanged to Pi.                                                                  |
-| `agents`                | array of unique non-empty definition names                            | no direct agents                                                  | Names direct definitions this agent may delegate to; every name must exist.                            |
-| `inheritProjectContext` | boolean                                                               | `true` only for definition name `delegate`; otherwise `false`     | Controls project context-file inheritance.                                                             |
-| `inheritGlobalContext`  | boolean                                                               | follows effective `inheritProjectContext`                         | Controls global context-file inheritance.                                                              |
+| Field                   | Accepted value                                                        | Omitted/default behavior                                               | Runtime/composition behavior                                                                           |
+| ----------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `name`                  | non-empty string                                                      | required                                                               | Effective definition identity.                                                                         |
+| `enabled`               | boolean                                                               | `true`                                                                 | `false` makes `delegate` and `continue` unavailable; it does not mutate an active agent.               |
+| `description`           | string                                                                | absent                                                                 | Display/selection description.                                                                         |
+| `model`                 | non-empty string                                                      | spawning controller for fresh `delegate`; saved session for `continue` | Explicit value is passed as Pi model selection.                                                        |
+| `thinking`              | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or `false` | spawning controller for fresh `delegate`; saved session for `continue` | Explicit value wins; `false` launches as `off`.                                                        |
+| `systemPromptMode`      | `append` or `replace`                                                 | `append` only for definition name `delegate`; otherwise `replace`      | Controls effective body versus Pi base system prompt.                                                  |
+| `bodyMode`              | `append` or `replace`                                                 | `replace` for non-empty matching overlay body                          | Valid only when overlaying an existing lower-precedence definition; consumed during body composition.  |
+| `noTools`               | boolean                                                               | Pi normal tool policy                                                  | `true` emits `--no-tools`; managed `ask_owner` remains infrastructure.                                 |
+| `noBuiltinTools`        | boolean                                                               | Pi normal built-in tool policy                                         | `true` emits `--no-builtin-tools`.                                                                     |
+| `tools`                 | array of non-empty strings                                            | no explicit allowlist                                                  | Passed to Pi as a source-agnostic tool-name allowlist; matching overlay replaces whole array.          |
+| `excludeTools`          | array of non-empty strings                                            | no explicit exclusions                                                 | Passed to Pi as source-agnostic tool-name exclusions; matching override replaces whole array.          |
+| `permission`            | mapping                                                               | absent                                                                 | Opaque interoperability policy for permission-aware extensions; Pi Herdsman does not evaluate it.      |
+| `noSkills`              | boolean                                                               | skills disabled unless `inheritSkills: true`                           | Controls Pi native skill discovery; explicit `skills` values are still passed separately.              |
+| `inheritSkills`         | boolean                                                               | does not enable by itself unless `true`                                | `true` changes omitted `noSkills` default so native skills remain available. Explicit `noSkills` wins. |
+| `skills`                | array of non-empty strings                                            | no explicit skill arguments                                            | Each value is passed unchanged as a Pi skill path/resource.                                            |
+| `noExtensions`          | boolean                                                               | Pi normal extension policy                                             | `true` emits `--no-extensions`. Required herdr agent infrastructure remains injected by the launcher.  |
+| `extensions`            | array of non-empty strings                                            | no extra extension arguments                                           | Each value is passed unchanged to Pi.                                                                  |
+| `agents`                | array of unique non-empty definition names                            | no direct agents                                                       | Names direct definitions this agent may delegate to; every name must exist.                            |
+| `inheritProjectContext` | boolean                                                               | `true` only for definition name `delegate`; otherwise `false`          | Controls project context-file inheritance.                                                             |
+| `inheritGlobalContext`  | boolean                                                               | follows effective `inheritProjectContext`                              | Controls global context-file inheritance.                                                              |
 
 `permission` is reserved for compatible permission extensions. Pi Herdsman
 accepts and preserves the mapping but does not validate its internal policy
@@ -206,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;
@@ -223,7 +247,8 @@ When a new agent generation is constructed:
 
 Every new agent generation expands the effective body and its file references
 once at launch. Session continuation preserves the Pi session history while
-using the current effective definition configuration.
+using the current effective definition configuration; model and thinking follow
+the execution-settings precedence above.
 
 ## Runtime prompt order
 

package/docs/reference/agent.md

@@ -54,7 +54,8 @@ for one assignment with a live label; it never assigns work to an existing
 agent. `continue` does not accept `cwd` or `fork`; the cwd comes from the saved
 session. The saved definition is resolved again from current configuration and
 must currently be enabled and authorized; its current effective configuration
-is used for the new generation.
+is used for the new generation. Omitted model and thinking fields restore the
+saved session settings, while explicit definition fields override them.
 Concurrent or otherwise conflicting managed representations of the exact
 session fail closed. The controller's own active Pi session cannot be continued
 to itself; use `delegate` with `fork` when a separate derived context is

package/docs/reference/commands.md

@@ -6,7 +6,8 @@
 
 It is separate from the structured model-facing `agent` API.
 
-Commands require a lead Pi session with UI.
+Agent-management commands require a lead Pi session with UI. Outside Herdr,
+plain `/agents` remains available as a setup diagnostic.
 
 ## Usage
 
@@ -35,7 +36,7 @@ overrides only.
 The details view can show:
 
 - name and description;
-- configured model and thinking;
+- configured or inherited model and thinking;
 - declared tool policy represented by definition metadata (not a complete
   runtime capability probe);
 - named skills;
@@ -57,12 +58,13 @@ Model
 Thinking
 Enabled
 Details…
-Back
 ```
 
 Model selection refreshes Pi's registry and stores the canonical provider/model
-token. `Use default` removes the selected field. Thinking uses Pi's supported
-levels when the selected model is known.
+token. `Inherit current session` removes the selected field. Unset model and
+thinking rows display `inherit · <current session value>` when the current
+value is available. Thinking uses Pi's supported levels when the selected
+model is known.
 
 When Pi provides an explicit scoped-model list, that scope is used. Otherwise
 available models are offered.
@@ -78,12 +80,14 @@ Details re-resolves the selected definition when opened, so it reflects current
 overlays and body references even if the menu remained open while configuration
 changed.
 
-Changes apply to future `delegate` assignments and `continue` assignments, not
-already-running agents or the lead Pi session.
+Changes apply to future assignments, not already-running agents or the lead Pi
+session. Fresh `delegate` assignments inherit the spawning controller's
+current settings when fields are unset; `continue` restores the saved
+session's settings.
 
-Standalone global definitions are editable too. Removing a field from one uses
-Pi's normal default; removing a field from a bundled override restores the
-bundled value.
+Standalone global definitions are editable too. Removing a model or thinking
+field selects `Inherit current session`; removing any other field inherits its
+lower-precedence value.
 
 ## `/agents` Running
 

package/package.json

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