pi-herdsman 0.2.0 → 0.3.0

package/docs/concepts/delegation.md

@@ -37,6 +37,27 @@ A lead may have many direct agents, and each direct agent that is explicitly
 delegation-enabled may have its own direct agents. A delegation-capable agent
 remains an agent at every depth; it is not a separate public role.
 
+Physical placement is presentation only and never determines ownership. The
+lead's placement setting controls direct agents: `tab` shares one tab per lead,
+`subtree` gives each direct agent a fresh tab, and `split` stays in the caller's
+tab. Nested delegation always splits inside the owner's current tab, regardless
+of the setting.
+
+For example, the logical ownership tree and a subtree layout are separate:
+
+```text
+logical ownership             physical subtree layout
+
+lead                          [lead]
+├── implementer        →      [implementer]
+│   └── scout                  ├─ implementer
+└── reviewer                    │  └─ scout
+                               └─ [reviewer]
+```
+
+Physical layout never determines ownership; the durable owner/session
+relationships do.
+
 ## Inferred `agent` capability
 
 A non-empty `agents` field implies the `agent` tool when the definition uses

package/docs/concepts/lifecycle.md

@@ -107,6 +107,10 @@ agent generation for the new assignment. The continuation uses the saved cwd
 and session history together with the current effective authorized definition
 configuration. Use `delegate.definition` 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
+assignment ownership.
 
 ## Steering is different
 

package/docs/getting-started.md

@@ -99,8 +99,11 @@ global override. Definition Details shows the effective metadata and can
 expand the resolved definition instructions with Pi's native `Ctrl+O`
 behavior. These edits always write global overrides, never project files.
 
-Use `Layout` to choose the current `tab` or `split` placement for newly started
-agents.
+Use `Layout` to choose the current placement for newly started lead-direct
+agents: `subtree` is the default and gives each lead-direct agent one tab;
+`tab` uses one lead-owned agents tab; `split` stays in the caller's tab. Nested
+delegation always splits inside the owner's current tab. Placement changes
+affect future starts only.
 
 For complete configuration ownership, see:
 

package/docs/guides/agent-definitions.md

@@ -164,8 +164,8 @@ Coordinate the assigned analysis and integrate direct agent results.
 ```
 
 The effective roster is validated atomically. Every `agents` name must exist.
-Bundled role descriptions and bodies describe role behavior only; orchestration
-guidance comes from the active controller contract.
+Bundled role descriptions communicate each role's purpose and selection boundary;
+the active controller contract remains authoritative for delegation behavior.
 
 With a non-empty explicit `tools` allowlist, `agent` is inferred unless
 explicitly denied. See [Delegation](../concepts/delegation.md).

package/docs/reference/commands.md

@@ -13,7 +13,7 @@ Commands require a lead Pi session with UI.
 ```text
 /agents
 /agents definitions
-/agents placement [tab|split]
+/agents placement [tab|subtree|split]
 /agents stop
 ```
 
@@ -95,10 +95,12 @@ is sent.
 ## `/agents placement`
 
 Selecting Layout opens a native selector showing the effective setting.
+When unset, the effective setting is `subtree`.
 Explicit values continue to set directly:
 
 ```text
 /agents placement tab
+/agents placement subtree
 /agents placement split
 ```
 

package/docs/reference/configuration.md

@@ -14,7 +14,7 @@ Settings shape:
 ```json
 {
   "piHerdsman": {
-    "spawnPlacement": "tab"
+    "spawnPlacement": "subtree"
   }
 }
 ```
@@ -23,19 +23,26 @@ Supported values:
 
 ```text
 tab
+subtree
 split
 ```
 
 Default:
 
 ```text
-tab
+subtree
 ```
 
-`tab` places future agents in the managed agent-tab workflow.
+When no `spawnPlacement` value is configured, it resolves to `subtree`.
+Unrecognized values remain invalid and resolve to `tab`.
+
+`tab` places future direct agents owned by a lead in one dedicated agents tab.
+
+`subtree` gives each future lead-direct agent its own tab. Descendants always
+split inside their owner's current tab.
 
-`split` places future agents by splitting from the caller's tab/pane placement
-boundary.
+`split` places future lead-direct agents by splitting from the caller's current
+pane. Descendants always split inside their owner's current tab.
 
 This affects future starts, not existing agents.
 
@@ -83,12 +90,12 @@ Project settings are stored in:
 A project placement value is effective only when:
 
 - the project is trusted by Pi; and
-- the project setting is `tab` or `split`.
+- the project setting is `tab`, `subtree`, or `split`.
 
 If no valid trusted project placement is active, the global value is used.
 
 `/agents placement` opens a native selector showing the effective value and
-offering `tab` or `split`. Selecting a value writes to the current effective
+offering `tab`, `subtree`, or `split`. Selecting a value writes to the current effective
 scope and verifies the value after writing; the confirmation reports whether
 that scope is `project` or `global`.
 

package/package.json

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