pi-herdsman 0.1.0

package/docs/README.md

@@ -0,0 +1,104 @@
+# Pi Herdsman documentation
+
+[Repository README](../README.md)
+
+This directory is the canonical product documentation for `pi-herdsman`.
+
+Pi Herdsman is built around asynchronous orchestration: managed workers can continue
+independently while the lead Pi session remains the user's interactive session.
+The exact lifecycle semantics live on [Lifecycle](concepts/lifecycle.md).
+
+The documentation follows one-source-of-truth ownership: every public concept
+has one canonical page. Audience pages route readers to those pages instead of
+copying their full contracts.
+
+## Choose your path
+
+### Use Pi Herdsman from the UI
+
+Start with [Getting started](getting-started.md).
+
+This path is for people who want to install Pi Herdsman, delegate work without
+leaving the lead conversation, configure agent definitions and placement,
+observe managed agents, focus their panes, and use lead controls
+without reading the structured model-facing API first.
+
+Continue with:
+
+- [`/workers` commands](reference/commands.md)
+- [Status widget](reference/status-widget.md)
+- [Configuration](reference/configuration.md)
+- [Agent definitions](guides/agent-definitions.md)
+- [Customizing bundled agents](guides/customizing-agents.md)
+- [Agent-definition schema](reference/agent-definition-schema.md)
+- [Recovery](guides/recovery.md)
+
+### Coordinate through agent APIs
+
+Start with [Agent coordination API](agent-api.md).
+
+This path is for model and agent coordination behavior: non-blocking assignment,
+exact worker identity, lifecycle, delegation, owner clarification, handoffs, and
+failure handling.
+
+Continue with:
+
+- [`worker` API](reference/worker.md)
+- [`ask_owner` API](reference/ask-owner.md)
+- [Workers and identity](concepts/workers.md)
+- [Lifecycle](concepts/lifecycle.md)
+- [Delegation](concepts/delegation.md)
+- [Handoffs and files](guides/handoffs.md)
+- [Worker states](reference/worker-states.md)
+- [Errors](reference/errors.md)
+
+For chief supervision of independent leads, read [Supervision](concepts/supervision.md)
+and its [complete reference contract](reference/supervision.md).
+
+### Develop Pi Herdsman
+
+Maintainer-only material stays separate from both product paths:
+
+- [Validation](development/validation.md)
+- [Smoke testing](development/smoke-testing.md)
+- [Documentation maintenance](development/documentation.md)
+
+The repository directories still group pages by content type (`concepts`,
+`guides`, `reference`, and `development`). The documentation index is
+audience-first so readers do not need to understand that internal grouping
+before choosing the material relevant to them.
+
+## Canonical ownership
+
+| Subject                               | Canonical page                                                  |
+| ------------------------------------- | --------------------------------------------------------------- |
+| Human UI first use                    | [Getting started](getting-started.md)                           |
+| Agent/API first use                   | [Agent coordination API](agent-api.md)                          |
+| Asynchronous orchestration            | [Lifecycle](concepts/lifecycle.md)                              |
+| Worker identity                       | [Workers and identity](concepts/workers.md)                     |
+| State transitions                     | [Lifecycle](concepts/lifecycle.md)                              |
+| Delegation model                      | [Delegation](concepts/delegation.md)                            |
+| Creating definitions                  | [Agent definitions](guides/agent-definitions.md)                |
+| Overrides and prompt composition      | [Customizing bundled agents](guides/customizing-agents.md)      |
+| `files`, body references, and results | [Handoffs and files](guides/handoffs.md)                        |
+| Operator recovery                     | [Recovery](guides/recovery.md)                                  |
+| `worker` request contract             | [`worker` API](reference/worker.md)                             |
+| `ask_owner` contract                  | [`ask_owner` API](reference/ask-owner.md)                       |
+| Pi Herdsman supervision concept       | [Supervision](concepts/supervision.md)                          |
+| Chief and staff tools                 | [Supervision reference](reference/supervision.md)               |
+| Frontmatter fields                    | [Agent-definition schema](reference/agent-definition-schema.md) |
+| Public worker states                  | [Worker states](reference/worker-states.md)                     |
+| `/workers` human commands             | [`/workers` commands](reference/commands.md)                    |
+| Settings                              | [Configuration](reference/configuration.md)                     |
+| TUI worker widget                     | [Status widget](reference/status-widget.md)                     |
+| Error categories                      | [Errors](reference/errors.md)                                   |
+| Repository checks                     | [Validation](development/validation.md)                         |
+| Live acceptance                       | [Smoke testing](development/smoke-testing.md)                   |
+
+When another page needs one of these subjects, it summarizes only enough to
+establish context and links to the canonical page instead of restating the full
+contract.
+
+Root `SKILL.md` remains optional model-facing reinforcement of the
+self-contained runtime operational contract plus deeper coordination guidance.
+Runtime remains authoritative and does not depend on the skill.

package/docs/agent-api.md

@@ -0,0 +1,103 @@
+# Agent coordination API
+
+[Documentation index](README.md) · [Human UI path](getting-started.md) · [supervision reference](reference/supervision.md)
+
+This is the entry point for model and agent-facing Pi Herdsman coordination.
+Pi Herdsman is opinionated about coordination semantics, not the workflow built on
+top of them. The API provides assignment, control, lifecycle, clarification, and
+handoff primitives without prescribing a planning, implementation, or review
+process.
+
+Exact request schemas, states, lifecycle rules, and error behavior remain on
+their canonical pages.
+
+If you only want to configure, observe, focus, or stop agents from Pi's TUI,
+begin with [Getting started](getting-started.md) instead.
+
+For an active chief supervising independent leads, use the [`staff` and
+`chief` contracts](reference/supervision.md).
+
+## Prerequisites
+
+Installation and supported versions are owned by
+[Getting started](getting-started.md#1-check-requirements). The lead Pi session
+must run inside [herdr](https://github.com/herdrdev/herdr).
+
+## First use
+
+The exact controller contract is the [`worker` API](reference/worker.md).
+Start by inspecting the current roster and authoritative visible workers:
+
+```json
+{ "action": "list" }
+```
+
+Then delegate to a fresh worker by definition:
+
+```json
+{
+  "action": "delegate",
+  "definition": "implementer",
+  "task": "Implement the approved change"
+}
+```
+
+`delegate` is non-blocking orchestration. It returns after the worker has accepted
+the assignment, not when the worker finishes.
+
+The owner remains free to make useful progress, coordinate other independent
+work, or end its turn normally. It must not poll the worker. Completion or an
+`ask_owner` question is delivered back to the exact owner asynchronously.
+
+The detailed lifecycle contract, including result delivery, one-assignment
+cleanup, blocked work, settling, and delegating-worker completion, is owned by
+[Lifecycle](concepts/lifecycle.md).
+
+The examples above establish the first-use path only. Use the
+[`worker` API](reference/worker.md) for exact accepted fields, validation,
+control eligibility, session continuation, fork behavior, and return shapes.
+
+## Understand worker identity
+
+Read [Workers and identity](concepts/workers.md) for the identity model behind
+controller operations. The logical worker identity is exposed as `worker` for
+live control; physical herdr and Pi identifiers are validation evidence.
+
+For the exact public state vocabulary, see
+[Worker states](reference/worker-states.md).
+
+## Delegate deliberately
+
+Read [Delegation](concepts/delegation.md) for lead and delegating-worker
+ownership and delegation limits.
+
+A worker that genuinely needs an owner decision uses the separate
+[`ask_owner` API](reference/ask-owner.md). The exact owner answers through the
+controller's `reply` action; ordinary active worker work is not an owner
+question.
+
+## Pass evidence through handoffs
+
+Read [Handoffs and files](guides/handoffs.md) for `files`, result paths, body
+references, and coordination artifacts. That guide owns the evidence-transfer
+workflow; the `worker` reference owns the accepted request fields.
+
+## Handle failures conservatively
+
+Use [Errors](reference/errors.md) for exact public error categories and
+[Recovery](guides/recovery.md) for operator recovery procedures. Do not infer
+control authority from the status widget or from stale physical-process
+observations.
+
+## Human UI is a separate surface
+
+The lead TUI exposes `/workers`, the status widget, definition
+configuration, layout selection, focus navigation, and emergency Stop all.
+Those are human-facing surfaces and are documented separately:
+
+- [`/workers` commands](reference/commands.md)
+- [Status widget](reference/status-widget.md)
+- [Configuration](reference/configuration.md)
+- [Getting started](getting-started.md)
+
+They do not replace the structured agent coordination contracts linked above.

package/docs/concepts/delegation.md

@@ -0,0 +1,100 @@
+# Delegation
+
+[Documentation index](../README.md)
+
+Delegation is bounded, direct, and ownership-local.
+
+## Lead
+
+The lead Pi session may delegate to any discovered effective agent definition.
+The lead retains architecture, global scope, acceptance, integration, and final
+decision authority.
+
+## Delegating worker
+
+A lead-launched worker becomes delegation-enabled when its effective definition
+has a non-empty `workers` list and its tool policy permits the `worker` tool.
+The worker receives only the definitions named by its effective `workers` list.
+
+A delegating worker:
+
+- delegates only to its permitted worker definitions;
+- owns only its direct workers;
+- integrates direct worker results into its own assignment;
+- remains subordinate to the lead's approved objective.
+
+Worker-started workers are leaves. Their effective metadata and launch policy
+remove the `workers` allowlist and `worker` capability. This keeps the supported
+structure bounded:
+
+```text
+lead
+└── delegating worker
+    └── worker
+```
+
+A lead may have many direct workers, and each direct worker that is explicitly
+delegation-enabled may have its own direct workers. A delegation-capable worker
+remains a worker at every depth; it is not a separate public role.
+
+## Inferred `worker` capability
+
+A non-empty `workers` field implies the `worker` tool when the definition uses
+an explicit non-empty `tools` allowlist. An omitted tool allowlist keeps Pi's
+default tool policy rather than creating a `worker`-only list.
+
+Explicit denial wins:
+
+- `excludeTools: ["worker"]` prevents inference.
+- `noTools: true` prevents inferred `worker` unless `worker` is explicitly
+  present in `tools`.
+- An explicit exclusion wins over an explicit allow.
+
+The exact field semantics live in the
+[agent-definition schema](../reference/agent-definition-schema.md).
+
+## Parallelism
+
+Delegate genuinely independent or context-heavy work. Prefer workers for broad
+file inspection, large logs or command output, and dataset analysis. Keep small,
+tightly coupled work local.
+
+Do not:
+
+- delegate overlapping writers to one worktree;
+- delegate review before the writer finishes;
+- duplicate supplied reconnaissance;
+- continue dependent work while a required worker is active.
+
+A useful pattern is:
+
+```text
+delegating worker
+├── scout: bounded reconnaissance
+└── local independent analysis
+
+worker result arrives
+↓
+delegating worker integrates both
+```
+
+## Clarification across ownership edges
+
+A worker may ask its exact direct owner through `ask_owner`.
+
+A delegating worker may ask its own direct owner when its unresolved direct
+workers are themselves validly blocked on owner questions. Ordinary active
+worker work or an undelivered worker result still blocks escalation. Questions
+are not automatically forwarded through an ownership chain.
+
+## Closing
+
+Closing a delegating worker cascades through its directly owned workers first.
+Cleanup remains ownership-safe: if a required worker cannot be proved or
+closed, the delegating worker is preserved rather than destructively guessing.
+
+## See also
+
+- [`ask_owner` API](../reference/ask-owner.md)
+- [Lifecycle](lifecycle.md)
+- [Handoffs and files](../guides/handoffs.md)

package/docs/concepts/lifecycle.md

@@ -0,0 +1,149 @@
+# Lifecycle
+
+[Documentation index](../README.md)
+
+The public lifecycle is assignment-centric. It deliberately does not mirror raw
+herdr process states one-for-one.
+
+## Assignment flow
+
+A normal assignment moves conceptually through:
+
+```text
+accepted
+  ↓
+working
+  ↓
+worker completes
+  ↓
+settling
+  ↓ result delivered once
+cleanup
+  ↓
+gone
+```
+
+The authoritative final result is correlated to the accepted assignment request
+ID.
+
+## Clarification flow
+
+A worker that requires an owner decision stays on the same assignment:
+
+```text
+working
+  ↓ ask_owner
+blocked
+  ↓ owner reply
+working
+  ↓ completion
+settling
+  ↓ result delivery
+cleanup → gone
+```
+
+`reply` is not a new assignment and does not create another final result.
+
+## Public state is a safe-control projection
+
+The public states are:
+
+- `working`
+- `blocked`
+- `settling`
+- `unknown`
+
+See [Worker states](../reference/worker-states.md) for their exact control
+meaning.
+
+Raw herdr lifecycle alone is insufficient. Mailbox handoff, pending result
+delivery, pending owner questions, and cleanup may make a worker unsafe to
+control until convergence is complete.
+
+## Asynchronous orchestration
+
+Delegation does not suspend the owning controller until a worker finishes.
+
+`delegate` returns after the task has been durably accepted. The worker then runs
+independently in its managed Pi session while the owner remains available for
+other useful work and, for a lead Pi session, continued user interaction.
+
+The owner must not poll for completion. It may continue with work that does not
+depend on the result or end its turn normally. Worker completion or an
+`ask_owner` question is delivered back to that same owner when attention is
+required.
+
+Conceptually:
+
+```text
+assignment accepted
+       ↓
+owner remains available
+       ↓
+worker runs independently
+       ↓
+result or question returns to the owner
+```
+
+This is asynchronous but not fire-and-forget. The owner retains explicit
+assignment ownership, can steer eligible active work, receives clarification
+requests, and remains responsible for result delivery and lifecycle control.
+
+## Exactly-once assignment result
+
+Each accepted task request maps to one final assignment result. Each managed
+worker generation receives exactly one assignment; a completed worker is not
+available for another task.
+
+Result publication and cleanup are separate convergence steps. A worker may
+therefore appear `settling` after its model has finished. Cleanup follows
+exactly-once delivery for both completed and failed terminal results.
+
+## Session continuation
+
+Worker cleanup does not delete the Pi session. To continue completed context,
+use the exact returned session with `delegate.session`; Pi Herdsman starts a new
+worker 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.
+
+## Steering is different
+
+`steer` changes the current active assignment. It does not create an independent
+result.
+
+Steering is at-least-once at the worker boundary: a worker can apply a steer
+before its acknowledgement write becomes durable. If that acknowledgement
+write fails, retrying the same request may apply the steer again.
+
+Use `steer` only when `worker list` reports `steer` in `available_actions`.
+
+## Delegating worker completion
+
+Direct worker work is a completion gate for a delegating worker.
+
+A delegating worker cannot publish its own final result while:
+
+- a direct worker has ordinary active work; or
+- a completed direct-worker result has not yet been delivered to the delegating worker.
+
+This completion gate does not create a separate public delegating-worker state.
+The delegating worker's own state projection remains authoritative.
+
+## Restart and recovery
+
+Durable mailbox state allows exact managed workers to be reconstructed after a
+controller restart. Live metadata can be rebuilt only when exact herdr and Pi
+identity still match.
+
+Unknown evidence remains `unknown`; recovery never rebinds stale metadata to a
+different worker generation.
+
+## See also
+
+- [Pi Herdsman](supervision.md) for lead supervision that does not alter worker
+  assignment ownership.
+- [Workers and identity](workers.md)
+- [Worker states](../reference/worker-states.md)
+- [Recovery](../guides/recovery.md)

package/docs/concepts/supervision.md

@@ -0,0 +1,77 @@
+# Supervision
+
+[Documentation index](../README.md) · [Supervision reference](../reference/supervision.md)
+
+Pi Herdsman supervision lets one chief observe and communicate with independent
+lead sessions. Each lead owns one herd: itself and its complete worker tree.
+The chief supervises leads but never takes ownership of their workers.
+
+## Authority and lead state
+
+Herdr proves live process, pane, workspace, and native Pi session identity.
+Pi Herdsman's validated worker snapshots prove managed-worker identity and
+ownership. A supervised lead must be one exact live Pi agent with a matching
+private lead-coordination record; it must not be the chief or a managed worker.
+Missing, stale, duplicate, or ambiguous evidence fails closed.
+
+Each lead has one private atomic record under the supervision runtime, keyed by
+the SHA-256 hash of its exact Pi session ID. The latest matching
+`pi-herdsman-lead-state` session entry supplies its persisted coordination
+state. A fresh `instanceId` on initialization protects against stale writers
+and publication races. The record is bounded to 2 KiB; its optional pending
+question is limited to 1,024 characters and 1,024 UTF-8 bytes.
+
+The record does not represent scheduling, capacity, permission, or message
+readiness. Herdr lifecycle observation is normalized to
+`idle|working|blocked|done|unknown`. A pending ask is separate attention state
+and gives the lead `needs_you` plus a correlated `reply` action.
+
+Metadata is presentation-only. It never grants lead eligibility, chief
+authority, or message authority.
+
+## Chief mode
+
+Chief is a mode of an ordinary lead session, not a separate worker identity.
+The persisted `pi-herdsman-role` entry contains either `role: "lead"` or
+`role: "chief"`. Chief mode is workspace-neutral and supervision-only. Its
+model exposes exactly the `staff` tool and excludes project/workspace context
+files and skills. Leaving chief restores the session's ordinary tool set.
+
+There is at most one active chief for an exact `HERDR_SOCKET_PATH`. The chief
+lease and descriptor identify the same process-lock generation. A resumed
+Chief session whose lease is occupied becomes suspended; an ordinary lead that
+loses an activation race remains an ordinary lead.
+
+## Communication
+
+Chief transport records are bounded, atomic inbox messages bound to exact
+sender, target lead session, and chief lease. Chief messages use Pi follow-up
+delivery and may remain queued while a lead is working. Records are ordered by
+`createdAt` and ID, survive same-session restart, and are retried after
+transient delivery failures. An individual quarantined record is excluded from
+delivery but does not block a new message to that lead.
+
+The `chief` tool sends reports, events, results, and genuine decision questions
+from an ordinary lead to the active chief. The `staff` tool lets the active
+chief list, inspect, message, and reply to supervised leads. A lead's message
+does not require an automatic chief reply. A `lead_ask` requires the exact
+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.
+
+## Supervision state
+
+The automatic `<supervision_state>` provider context is ephemeral, bounded, and
+state-only. It contains `leads`, with each lead's exact session ID,
+presentation `display_name`, runtime observation, `worker_counts`, `workers`,
+and available actions. The `staff list` result uses the same presentation field,
+`display_name`. The `workers` collection represents all validated descendants
+assigned to that lead, not only direct workers. Its values and metadata are
+untrusted observations and cannot authorize an action.
+
+Use the exact full session ID in a lead's `lead` field when calling `staff`.
+Never target a lead by its display label. `staff` revalidates identity,
+ownership, lifecycle, and the current chief lease before mutation.
+
+See the [Supervision reference](../reference/supervision.md) for the complete
+current contract.

package/docs/concepts/workers.md

@@ -0,0 +1,124 @@
+# Workers and identity
+
+[Documentation index](../README.md)
+
+A managed worker is a Pi session whose physical lifecycle is owned by herdr and
+whose assignment lifecycle is coordinated through the extension mailbox.
+
+## The identities are intentionally different
+
+### Agent definition
+
+The **agent definition** selects the worker's model, reasoning policy, tools,
+skills, extensions, prompt body, context inheritance, and allowed direct
+workers.
+
+Example: `reviewer`.
+
+Definitions are configuration, not live worker identity.
+
+### Logical worker identity
+
+The internal label is projected publicly as the `worker` identity for a live
+worker.
+
+Examples:
+
+```text
+reviewer
+reviewer-2
+my-review
+```
+
+Use the exact `worker` value from `worker list` only for
+`steer.worker`, `reply.worker`, or `close.worker` while those actions are listed
+in `available_actions`. A worker label is the live execution identity for one
+assignment, not a continuation handle.
+
+Labels must begin with a lowercase letter, contain only lowercase letters,
+digits, `_`, or `-`, and be at most 32 characters.
+
+### Pi session identity
+
+Every managed worker 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. It is the continuation identity, not a live-control identity.
+Session delegation creates a new worker generation for one new assignment and
+uses the saved session's cwd and historical context. An exact active or
+unresolved managed representation blocks concurrent activation of that session.
+
+### herdr identities
+
+Workspace, tab, pane, generated herdr-agent alias, run ID, and process evidence
+exist to prove physical ownership and safe cleanup.
+
+They are not public alternatives to the `worker` identity.
+
+## Ownership
+
+Each worker has one exact direct owner Pi session.
+
+A lead Pi session owns its direct workers.
+
+A delegating worker may own direct workers when its effective definition has
+allowed `workers`.
+
+Public list visibility follows this ownership boundary. Lead recovery may expose
+a proven orphan descendant only when durable ownership and exact absence of its
+former delegating worker are established.
+
+## Authority boundaries
+
+Different systems answer different questions:
+
+| Authority     | Owns                                                                                     |
+| ------------- | ---------------------------------------------------------------------------------------- |
+| herdr         | Physical process/pane lifecycle, placement, live agent observations                      |
+| Mailbox       | Assignment acknowledgement, active/completed request identity, pending ask, final result |
+| Pi            | Session history, turns, messages, model interaction                                      |
+| Logical label | Internal durable worker identity, projected publicly as `worker`                         |
+
+The mailbox `ResultRecord` is the persisted completion record and carries the
+identity needed to match its worker state. The owner-session delivery entry is
+a separate, wider record: it also carries delivery metadata such as `cwd` and
+the Pi session file. Those records are checked against their respective
+identity requirements; `ResultRecord` is not intended to mirror the complete
+delivery-entry shape.
+
+If a result cannot be persisted after bounded retries, the worker state carries
+a correlated `result_error` recovery condition instead of becoming assignable.
+
+A safe control operation requires these sources to agree. Missing or conflicting
+evidence fails closed rather than guessing.
+
+## Worker generations and continuation
+
+Every managed worker generation executes exactly one delegated assignment. Its
+terminal result is delivered once, then the worker's pane, process, mailbox,
+and runtime state are cleaned up. Failed assignments follow the same terminal
+cleanup path.
+
+The Pi session remains available after worker 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 worker 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.
+
+The identities are therefore:
+
+```text
+agent definition → configuration for new work
+Pi session       → durable conversational context and continuation identity
+worker label     → live control identity for one assignment
+```
+
+## See also
+
+- [Pi Herdsman](supervision.md) for the separate supervision model.
+- [Lifecycle](lifecycle.md)
+- [Delegation](delegation.md)
+- [Worker states](../reference/worker-states.md)
+- [`worker` API](../reference/worker.md)