pi-herdsman 0.4.0 → 0.5.0

package/docs/agent-api.md

@@ -78,7 +78,7 @@ question.
 
 ## Pass evidence through handoffs
 
-Read [Handoffs and files](guides/handoffs.md) for `files`, result paths, body
+Read [Handoffs and files](guides/handoffs.md) for `files`, result references, body
 references, and coordination artifacts. That guide owns the evidence-transfer
 workflow; the `agent` reference owns the accepted request fields.
 

package/docs/concepts/agents.md

@@ -32,8 +32,9 @@ my-review
 
 Use the exact `agent` value from `agent list` only for
 `steer.agent`, `reply.agent`, or `close.agent` while those actions are listed
-in `available_actions`. An agent label is the live execution identity for one
-assignment, not a continuation handle.
+in `available_actions`. An agent label is the stable logical name across
+sequential generations of one managed session, not a continuation selector.
+It is a control target only for the currently live generation.
 
 Labels must begin with a lowercase letter, contain only lowercase letters,
 digits, `_`, or `-`, and be at most 32 characters.
@@ -43,14 +44,13 @@ digits, `_`, or `-`, and be at most 32 characters.
 Every managed agent has an exact Pi session. The list may expose the session
 ID and path for correlation.
 
-A session path or full UUID can be supplied as `delegate.session` to continue
-historical work. Session delegation creates a new agent generation for one new
-assignment and uses the saved session's cwd and historical context. With
-`delegate.session`, omitting `label` chooses a fresh available label derived
-from the saved definition; supplying one chooses the exact live label for that
-generation. The Pi session remains the continuation identity, not a
-live-control identity. An exact active or unresolved managed representation
-blocks concurrent activation of that session.
+A session path or full UUID can be supplied to the `continue` action to continue
+historical work. Continuation creates a new agent generation for one new
+assignment and uses the saved session's cwd, definition, logical label, and
+historical context. The caller cannot rename the continued session. The Pi
+session remains the continuation identity, not a live-control identity. An
+exact active or unresolved managed representation blocks concurrent activation
+of that session.
 
 ### herdr identities
 
@@ -104,18 +104,17 @@ and runtime state are cleaned up. Failed assignments follow the same terminal
 cleanup path.
 
 The Pi session remains available after agent cleanup. To continue the same
-conversational context, delegate a new assignment 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 definition
-delegation.
+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.
 
 The identities are therefore:
 
 ```text
 agent definition → configuration for new work
 Pi session       → durable conversational context and continuation identity
-agent label     → live control identity for one assignment
+agent label     → stable logical name across sequential generations; live control target only for the current generation
 ```
 
 ## See also

package/docs/concepts/lifecycle.md

@@ -102,11 +102,11 @@ exactly-once delivery for both completed and failed terminal results.
 ## Session continuation
 
 Agent cleanup does not delete the Pi session. To continue completed context,
-use the exact returned session with `delegate.session`; Pi Herdsman starts a new
-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.
+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.
 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/concepts/supervision.md

@@ -60,7 +60,7 @@ correlated `staff reply`; a reply clears the pending ask only after accepted
 follow-up delivery. A replacement chief can answer an existing ask using its
 current lease and unchanged ask ID. Chief and staff message actions accept
 files; their text is prepared with the same canonical attachment renderer and
-configured global byte limits as agent messages, while durable supervision
+configured Herdsman byte limits as agent messages, while durable supervision
 records remain text-only.
 
 ## Supervision state

package/docs/development/documentation.md

@@ -121,7 +121,7 @@ registry, or another synchronization subsystem.
 - One H1 per file.
 - Short descriptive headings.
 - Current behavior only.
-- Spell the visible product name `Pi Herdsman`, the package and repository identifier `pi-herdsman`, the local coordination directory `.pi-herdsman`, the settings namespace `piHerdsman`, and the upstream dependency `herdr`.
+- Spell the visible product name `Pi Herdsman`, the package and repository identifier `pi-herdsman`, the local coordination directory `.pi-herdsman`, the configuration file `config.json`, and the upstream dependency `herdr`.
 - No backlog task numbers in product docs.
 - Keep canonical user and reference pages focused on current behavior.
 - Examples must match current accepted schemas.

package/docs/development/smoke-testing.md

@@ -58,7 +58,7 @@ Use the exact returned session ID or path for a follow-up assignment:
 
 ```json
 {
-  "action": "delegate",
+  "action": "continue",
   "session": "<exact session>",
   "task": "Continue the investigation with one short follow-up."
 }
@@ -68,25 +68,27 @@ Verify:
 
 - the same Pi session and session file are used;
 - 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;
 - exactly one result reaches the owner;
 - cleanup removes the second agent, pane, mailbox, and runtime.
 
-While the continuation assignment is active, submit another
-`delegate.session` request for the same exact session. Verify it fails with
+While the continuation assignment is active, submit another `continue` request
+for the same exact session. Verify it fails with
 `agent_busy`, creates no duplicate agent or pane, and leaves the active
 assignment unchanged. After both assignments finish, `agent list` must show
 no completed idle agent.
 
-## Historical session delegation
+## Historical session continuation
 
 Use an exact saved session path or full UUID.
 
 Verify:
 
 - saved definition and cwd are respected;
-- session delegation uses the saved cwd;
+- the saved logical label is reused exactly;
+- session continuation uses the saved cwd;
 - current effective agent override values are used for the new agent
   generation;
 - the exact session continues.

package/docs/getting-started.md

@@ -126,9 +126,9 @@ See [Status widget](reference/status-widget.md) for exact state, refresh, and
 rendering behavior.
 
 To continue a completed assignment with its existing conversational context,
-use the exact `session_id` returned with its result in a new `delegate.session`
-request. This starts a new agent generation with the saved session and current
-effective definition configuration.
+use the exact `session_id` returned with its result in a new `continue` request.
+This starts a new agent generation with the saved session and current effective
+definition configuration.
 
 ## 7. Recover only when needed
 

package/docs/guides/agent-definitions.md

@@ -102,7 +102,7 @@ referencing a disabled definition can remain discoverable, but is rejected durin
 assignment or fresh agent startup with an explicit disabled-definition reason
 rather than silently dropping that definition.
 
-Definition and session delegations reject disabled definitions with an
+`delegate` and `continue` reject disabled definitions with an
 actionable error. An already active agent may finish and remains controllable
 according to its current available actions; disabling a definition does not
 mutate that assignment.

package/docs/guides/customizing-agents.md

@@ -229,7 +229,7 @@ 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 definition delegations and session continuations, whose
+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.
 

package/docs/guides/handoffs.md

@@ -4,7 +4,7 @@
 
 Pi Herdsman has two text-file mechanisms with different purposes:
 
-- `files` supplies evidence to delegate (definition or session), steer, reply,
+- `files` supplies evidence to delegate, continue, steer, reply,
   or ask_owner.
 - whole-line body `@file` references put definition-owned text into the agent
   system prompt when a new agent generation is built.
@@ -14,7 +14,7 @@ canonical local references and are not copied or snapshotted.
 
 ## Message `files`
 
-For `delegate` with `definition`, `delegate` with `session`, `steer`, and
+For `delegate`, `continue`, `steer`, 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.
@@ -34,7 +34,10 @@ Example:
   "action": "delegate",
   "definition": "reviewer",
   "task": "Review the implementation against the approved plan.",
-  "files": [".pi-herdsman/plan.md", "/tmp/implementation-result"]
+  "files": [
+    ".pi-herdsman/plan.md",
+    "result:550e8400-e29b-41d4-a716-446655440000"
+  ]
 }
 ```
 
@@ -52,17 +55,35 @@ A reference-only file uses a self-closing tag:
 <file name="/absolute/canonical/path" bytes="123" />
 ```
 
-`name` is the canonical absolute path and `bytes` is the observed file size.
-A body means the complete submission-time UTF-8 snapshot was embedded; a
-self-closing tag means only the path and size reference was supplied. File
-content remains raw text. This markup frames evidence for the model and is not
-a security boundary.
+For an ordinary file, `name` is the canonical absolute path and `bytes` is the
+observed file size. For a result reference, an embedded file uses the exact
+`result:<request-id>` as `name`:
 
-`files` is supported by `delegate` with `definition`, `delegate` with `session`,
+```xml
+<file name="result:550e8400-e29b-41d4-a716-446655440000" bytes="123">
+contents
+</file>
+```
+
+A result that is supplied by reference keeps both identities in its
+self-closing envelope:
+
+```xml
+<file name="result:550e8400-e29b-41d4-a716-446655440000" path="/absolute/canonical/path" bytes="123" />
+```
+
+A body means the complete submission-time UTF-8 snapshot was embedded. For an
+ordinary file, a self-closing tag carries its canonical path and observed byte
+size; for a result reference, it carries the logical result name, the physical
+path attribute, and observed byte size. File content remains raw text. This
+markup frames evidence for the model and is not a security boundary.
+
+`files` is supported by `delegate`, `continue`,
 `steer`, `reply`, and `ask_owner`. For
 controller actions, relative paths resolve from the calling controller's cwd;
-for `ask_owner`, they resolve from the managed agent's cwd. Every accepted
-path is displayed using its canonical absolute path.
+for `ask_owner`, they resolve from the managed agent's cwd. Accepted ordinary
+filesystem paths retain canonical absolute-path names; `result:<request-id>`
+inputs retain the logical result reference as the model-facing name.
 
 Supplied paths must resolve to readable regular files. Missing, broken,
 unreadable, and non-regular paths reject the whole operation. Canonical
@@ -79,8 +100,10 @@ For each regular file:
 
 - complete strict UTF-8 text without NUL bytes is embedded when the complete
   message fits the effective configured `mailboxPayloadLimitBytes` boundary;
-- invalid UTF-8, NUL-containing, binary, and non-fitting files are represented
-  only by a canonical local path and observed byte size.
+- invalid UTF-8, NUL-containing, binary, and non-fitting ordinary files are
+  represented only by their canonical local path and observed byte size;
+  result references retain their logical name and carry the physical path and
+  observed byte size.
 
 The fixed 1 MiB mailbox protocol safety ceiling is a separate read limit for
 mailbox records; it does not replace the configured admission limit for new
@@ -92,7 +115,10 @@ or disappear after submission, and the recipient must already have local
 filesystem/tool access to inspect them. `files` supplies evidence and does not
 grant runtime capabilities.
 
-Files are read through their canonical `realpath` target.
+Files are read through their canonical `realpath` target. Ordinary file inputs
+are rendered with that canonical path; result references retain the
+`result:<request-id>` name so recipients can pass the same reference through
+`files` again.
 
 ## Canonical deduplication
 
@@ -184,22 +210,30 @@ definition configuration while preserving the saved Pi session context.
 
 ## Result handoff
 
-Successful agent completion may expose a private `resultPath`.
+Successful agent completion exposes a canonical `resultRef` such as
+`result:550e8400-e29b-41d4-a716-446655440000`.
 
-For dependent work, pass the exact result path through `files` rather than
-copying a large result manually:
+Pass the exact result reference directly through `files` rather than copying a
+large result or reconstructing its physical path:
 
 ```json
 {
   "action": "delegate",
   "definition": "reviewer",
   "task": "Review the implementation described in the supplied result.",
-  "files": ["/exact/resultPath"]
+  "files": ["result:550e8400-e29b-41d4-a716-446655440000"]
 }
 ```
 
-Successful agent completions persist their complete output at the canonical
-`resultPath`; they do not receive a separate completion overflow path.
+`files` accepts ordinary readable regular local file paths and result
+references. A result reference resolves internally to the normal private
+result file under Pi Herdsman's durable data directory; it is still validated,
+canonicalized, and deduplicated like any other file. Copy the exact reference
+returned by completion. Do not guess or reconstruct the underlying path.
+Completion results live under Pi's agent data directory
+(`~/.pi/agent/pi-herdsman/results` by default, respecting Pi's configured agent
+directory) rather than the OS temporary directory, so result handoffs are not
+subject to temporary-directory cleanup.
 Oversized non-completion registered-tool output may additionally expose
 `full_output_path` when overflow persistence succeeds. Model-visible content
 remains bounded in both cases.

package/docs/guides/recovery.md

@@ -65,7 +65,7 @@ Do not close solely because of inactivity.
 
 ## Startup failure
 
-Fresh and historical-session delegation startup is bounded.
+Fresh delegation and historical-session continuation startup is bounded.
 
 When herdr returns a structured failure, Pi Herdsman preserves it. When startup
 returns empty or malformed output and no better structured error is available,
@@ -116,16 +116,17 @@ not the normal model orchestration interface.
 
 ## Historical session failure
 
-A `delegate` with `session` requires an exact session path or full UUID.
+A `continue` requires an exact session path or full UUID.
 
 The saved session header must contain a non-empty working directory. Session
-delegation uses that saved cwd and does not accept a caller-supplied `cwd`.
+continuation uses that saved cwd and does not accept a caller-supplied `cwd`.
 
-The saved agent-definition name is resolved against the current effective
-definition roster. If it no longer exists, session delegation fails instead of guessing a
-replacement. The definition must also be enabled and authorized for the current
+The saved agent-definition name and logical label are restored from the managed
+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.
+generation. 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

@@ -65,7 +65,7 @@ All effective definitions are sorted and validated together, including every
 
 `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. Definition and session delegations reject a disabled definition. An already
+it. `delegate` and `continue` reject a disabled definition. An already
 active agent may finish and remains controllable according to its current
 available actions; disabling a definition does not mutate that assignment.
 
@@ -74,7 +74,7 @@ available actions; disabling a definition does not mutate that assignment.
 | Field                   | Accepted value                                                        | Omitted/default behavior                                          | Runtime/composition behavior                                                                           |
 | ----------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
 | `name`                  | non-empty string                                                      | required                                                          | Effective definition identity.                                                                         |
-| `enabled`               | boolean                                                               | `true`                                                            | `false` makes definition and session delegation unavailable; it does not mutate an active agent.       |
+| `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`.                                                                             |

package/docs/reference/agent.md

@@ -2,11 +2,12 @@
 
 [Documentation index](../README.md) · [supervision reference](supervision.md)
 
-`agent` is the structured model-facing API for managed agents. It has exactly six actions:
+`agent` is the structured model-facing API for managed agents. It has seven actions:
 
 ```text
 list
 delegate
+continue
 steer
 reply
 close
@@ -19,12 +20,6 @@ controllers.
 
 ## `delegate`
 
-Delegation has exactly two strict variants. The required field (`definition` or
-`session`) selects the variant; there is no target discriminator.
-Every variant rejects additional properties.
-
-### Definition
-
 ```json
 {
   "action": "delegate",
@@ -42,39 +37,38 @@ the source for a new derived context; otherwise a new Pi session is launched.
 Each accepted definition delegation creates one agent generation for one
 assignment. The terminal result is delivered once and the agent is cleaned up.
 
-### Session
+## `continue`
 
 ```json
 {
-  "action": "delegate",
+  "action": "continue",
   "session": "<exact .jsonl path or full UUID>",
   "task": "Continue the investigation"
 }
 ```
 
-Allowed fields are `action`, `session`, `task`, optional `label`, `files`, and
-`timeoutMs`. The exact saved session supplies its cwd, definition identity, and
-historical Pi context. Session delegation always creates a new agent generation
+Allowed fields are `action`, `session`, `task`, optional `files`, and
+`timeoutMs`. The exact saved session path or full UUID supplies its cwd,
+definition identity, and historical Pi context. Continuation always creates a new agent generation
 for one assignment with a live label; it never assigns work to an existing
-agent. The saved definition must currently resolve to an enabled, authorized
-effective definition, whose current configuration is used for the new
-generation.
+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.
 Concurrent or otherwise conflicting managed representations of the exact
-session fail closed. The controller's own active Pi session cannot be delegated
-to itself; use definition delegation with `fork` when a separate derived
-context is required.
-
-`label` is optional on both delegation variants and identifies the live
-generation, not the continuation session. When omitted, Herdsman chooses a
-fresh available label derived from the effective agent definition. An explicit
-label is used exactly as the live label; if that label is occupied, delegation
-fails with `agent_label_exists`.
-
-All successful delegation results use `action: "delegate"` and include
-`agent`, `definition`, request, session, and startup evidence where available.
-Delegation returns after durable acceptance, not completion. A terminal result
-also makes the exact session identity prominent so it can be used with a later
-`delegate.session` call.
+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
+required.
+
+The saved session's logical label is inherited exactly for the continued
+generation. A caller cannot provide a continuation label; if the inherited
+label is occupied, continuation fails with `agent_label_exists`.
+
+Successful `delegate` results use `action: "delegate"`; successful `continue`
+results use `action: "continue"`. Both include `agent`, `definition`, request,
+session, and startup evidence where available. Both return after durable
+acceptance, not completion. A terminal result makes the exact session identity
+prominent for a later `continue` call.
 
 ## `list`
 
@@ -105,8 +99,9 @@ Each actionable live agent record includes:
 `available_actions` is authoritative model guidance for the current snapshot.
 Do not infer eligibility from `state`. Active work may list `steer`; a valid
 correlated pending `ask_owner` may list `reply`; exact direct ownership may list
-`close`. `available_actions` never lists `delegate`: an agent cannot receive a
-second assignment. Descendant visibility does not grant control. Lead orphan
+`close`. `available_actions` never lists `delegate` or `continue`: these are
+controller operations, not controls on an already-live agent. An agent cannot
+receive a second assignment. Descendant visibility does not grant control. Lead orphan
 recovery may expose only `close`. Unknown and recovery-only records are
 non-actionable. Every operation rechecks identity, ownership, mailbox state, and
 lifecycle immediately before mutation.
@@ -146,15 +141,15 @@ mailbox records, lifecycle, or available controls.
 
 ## `files` and `timeoutMs`
 
-`files` is valid on all `delegate` variants and on `steer` and `reply`; it is not
+`files` is valid on `delegate` and `continue`, and on `steer` and `reply`; it is not
 valid on `list` or `close`. Paths are resolved from the controller cwd, checked
 as readable regular files, canonicalized with `realpath`, and embedded only
 when the exact message limit permits. Otherwise they remain canonical references.
 
-`timeoutMs` is valid on definition and session delegation and must be an integer
+`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 global/default
-settings and the fixed mailbox protocol ceiling. Managed mailbox records use
+window. 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__:`.
 
@@ -216,7 +211,7 @@ and has one correlated final result. Delivery goes to the exact owning Pi
 session and occurs exactly once. Model-visible completion wording uses
 `agent=<agent>`, `definition=<definition>`, `session=<id>`,
 `request=<id>`, and status. Details retain durable `agentLabel`,
-`agentDefinition`, `piSessionId`, `piSessionFile`, result paths, elapsed time,
+`agentDefinition`, `piSessionId`, `piSessionFile`, result references, elapsed time,
 context usage, truncation, and persistence-error evidence. The agent is cleaned
 up after the terminal result is delivered; the Pi session remains available for
 continuation.

package/docs/reference/commands.md

@@ -19,8 +19,8 @@ Commands require a lead Pi session with UI.
 
 The plain command opens a native Pi selection menu with `Running`,
 `Definitions`, `Layout`, `Message limits`, and `Stop all…` destinations. The
-Message limits view edits the independent global inline attachment and mailbox
-payload limits. It is available only to a lead Pi session with UI. Current
+Message limits view edits the user-wide inline attachment and mailbox payload
+limits. It is available only to a lead Pi session with UI. Current
 values and presets show a rough token equivalent using four UTF-8 bytes per
 token. The enforced limits are bytes, not tokens.
 
@@ -78,7 +78,7 @@ 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 definition delegations and session continuations, not
+Changes apply to future `delegate` assignments and `continue` assignments, not
 already-running agents or the lead Pi session.
 
 Standalone global definitions are editable too. Removing a field from one uses