How pi-straw-boss works

The full behavior behind the README. The guides say how to use Straw Boss; this reference says exactly what the code does, one section at a time, so find the section you need below and skip the rest.

Straw Boss is a pi extension. It joins the pi sessions that run in Herdr into one net, gives them a chain of command, lets one tower per workspace coordinate them, and shows the whole net on one page.

flowchart TD
    boss["You"] --> head["Head tower<br/>one per computer"]
    head -->|"tower_send"| tower["Tower<br/>one per workspace"]
    tower -->|"boss_open_main"| main["Main agent<br/>one per tab"]
    member["Member<br/>any other pi in the tab"] -.->|"boss_promote"| main
    main -->|"subagent"| sub["Subagents<br/>worker, scout, planner,<br/>reviewer, watchdog"]
    main -->|"call_tower"| tower
    tower -->|"boss_open_main"| train["Train<br/>one batch of merge cars"]
    server["sb server<br/>one per computer"] -.->|"runs"| tower
    server -.->|"runs"| head

Each solid arrow is a tool from Tools. The dotted ones are not tools: a member becomes a main by promotion, and the sb server runs the towers.

Positions

Position	What it is	How it comes to be
member	a joined pi that is not a main	joins at session start, by itself
main agent	one per tab; plans, dispatches, and asks the boss	promotion (boss_promote, a first subagent call), /boss, or a tower opening it
subagent	a pi-herdr-agents child; it never joins, and its launcher speaks for it	launched by a main or a member
tower	one per workspace; routes work and repairs friction, and never asks the boss	opened when agents start to collide
head tower	the boss’s one entry point, one per computer; hands each instruction to a workspace’s tower	made by the sb server at the boss’s first message
train	a worker that carries one batch of merge cars to the base branch	opened by a tower for the project’s integrator

Kinds of main agent, subagent, and tower run

Kinds of main agent (the page shows the kind word; the GUI says “on watch” for standing)

Kind	What it is for	How it is set
coordinator	the default: splits work, plans, dispatches subagents	by default, or boss_duty
integrator	a project’s merge trains: receives cars, forms trains	boss_duty, or the name integ <project>
standing	minds one system or machine, with no end	boss_duty

Kinds of subagent (read from the role name pi-herdr-agents gave it, which the child records in its session file at its first turn; any other role stays a plain subagent)

Kind	Role names	What it is for	Dispatch by a coordinator
worker	worker	does a task: edits, runs, builds	refused with sb: plan first until its todos name a graph
scout	scout	investigates and reports	passes without a plan
planner	planner	writes a plan or a design	passes without a plan
reviewer	reviewer, visual-tester, adversarial-reviewer	reviews a change or checks the UI	passes without a plan
watchdog	watchdog	watches another session or Herdr state and only reports back	refused like a worker

Kinds of tower run (what wakes a tower; the rules are in Local runs, The boss conversation, and Ally runs)

Run	Woken by	What it is
event run	an event from a session, such as a main’s call_tower or a finished milestone	a fresh pi in the standing pane; ends with tower_done and a handoff note
boss conversation	the boss’s words (the page’s composer, the standing pane, /boss tower)	the run that resumes the boss’s last session
ally run	a Straw Link message from a teammate’s device	a fresh pi in a pane beside the standing pane, at the sender’s trust level

Where to read

You want to know	Read
who joins, who is promoted, when a tower opens	How it works
what a tower knows, how towers talk, what the head tower does	The tower’s digest, Talking between towers, The head tower
teammates’ computers and unattended boxes	Straw Link, Straw Link operate
the work board and auto mode	The work board, Auto mode
opening and closing mains, the settings check	Opening a main, The settings check, Closing an opened main
merging many branches safely	Merge train
the dashboard, and subagents that lost their launcher	Tower dashboard, Orphaned subagents
the browser page: map, comms, alerts, phone, Zen	Browser view
Herdr’s sidebar, worktree cleanup, process cleanup	Sidebar net view, Worktree reaper, Process hygiene and slots
the background server, tower runs, the standing pane, memory, ally runs	The sb server
a command, a file it writes, Windows, developing	Tools, What it writes, From a shell, Windows, Development