Subagents and units

A coordinator holds the loop while workers do the work, and the book follows each worker’s edits, runs, and landings back to the ticket it serves. A todo that carries coordination metadata is a unit with phases of its own.

flowchart TD
  coord["Coordinator's loop book"] -->|"todo with observe, kind,<br/>lands, or agents"| unit["Unit"]
  coord -->|"link entry: session file,<br/>cwd, worktree, landing ref"| child["Child<br/>pi-herdr-agents"]
  unit -->|"binds by agents,<br/>else by ticket id"| child
  unit -->|"anchor inherited"| child
  child -->|"passing run of that anchor<br/>on the tree the unit holds"| verify["Unit verify<br/>adopted"]
  child -->|"branch"| ref["Integration ref<br/>unit lands"]
  ref -->|"ancestor, patch id,<br/>or same content"| land["land entry<br/>counts as the act"]
  notice["anchorloop_stage landed<br/>sha, ref, task"] -.->|"checked the same way"| land

Links, the host adapter, and a child's own book

A child is linked only through pi-herdr-agents: PI_SUBAGENT_ID in the child, details.id on the parent’s subagent result. pi itself has no subagents. A linked child’s edits are the parent’s act. Its anchor runs, recorded as check, carry the working-state tree of each repo it works in: tracked and untracked files, with ignored files and scratch/ left out.

For a main session that only coordinates, a delegation-host adapter feeds the book. The adapter is pi-herdr-agents, env-only markers, or none, chosen from the environment. A link records the child’s session file, cwd, worktree, and the integration ref its work lands on. It adds a base for the child’s repo so the diff includes the worker’s change. Spawns made before the first todo are linked when the loop opens.

A child opens its own book from its first edit, commit, or run of its parent’s anchor, with no todo.

read and session_start name each child with no result, with its process, book, and worktree state.

Units: what makes one, how a child binds, and what a unit's checks compare

A todo with observe, kind, lands, or agents metadata is a unit. An anchor alone is the task’s own check and makes none. Two or more units get one phase line each in read, the widget, and Jev’s task list.

A child binds to a unit by agents, else by the ticket id in its name or brief when exactly one open todo holds it.

A unit’s trees are its workers’ worktrees (or checkouts), else the loop’s own repos. An edit counts for the units whose trees hold it, and for every unit when none does. A unit’s checks compare only its trees, so one unit’s change leaves another’s check standing.

With two or more units:

• verify without task is refused, with the units listed.
• back and skip with task reach only that unit and take that unit’s kind.
• A child inherits its unit’s anchor, and its returned passing run of that anchor is recorded as its unit’s verify.
• Each subagent_send to a persistent reviewer is its own dispatch, and its verdict counts for the unit its brief names.