Tools

Straw Boss gives agents a set of tools (boss_*, tower_*, call_tower, board_*) and gives the boss the /boss slash commands. Which session may call which tool depends on its role. The tables list who each tool is available to and what it does, then every /boss command.

Details

Tool	Available to	What it does
boss_promote	joined sessions that are not the tower	Become this tab’s main agent; refused while the tab has a live main.
boss_status	joined sessions and towers	The main agent of each tab, this workspace’s tower, the head tower, and the other towers.
boss_open_main	towers only	Open a new tab in the tower’s workspace with a new pi as its main agent and hand it a request no session owns, once per request (see Opening a main). With role: "train" it opens a train; with role: "integrator", in a run of the sb server, it sends a car slip to the project’s one integrator, opening it as the tower’s own main when none runs.
boss_close_main	towers only	Ask a main this tower opened (by intercom name or session id) to quit as /boss close does. Refused for a main the boss opened, one in another workspace, one Herdr reports working, and one with a turn, a queued message, a dialog, a monitor, or a subagent running (see Closing an opened main).
tower_list	towers only	Every workspace’s tower or, without one, its mains or members: reach, state, head and self marks, and each tab’s main and members by name (see Talking between towers).
tower_send	towers only	One message to another tower (workspace id or exact label, default every other tower), under a header; with device, to the tower of a teammate’s computer over Straw Link (the link holder); a workspace without a tower is reached through its mains, else its members. reply says whether an answer is expected. In a head tower run it takes only workspace and message (it opens that workspace’s tower), and in a workspace tower’s run head: true with inReplyTo (an ask id) answers the head tower (The head tower). In a tower run, for (a live main of the workspace; with device and reply) sends the device’s answer to that main (left out, the server takes the one main that called the tower for this; Who the tower sends for), and in an ally run inReplyTo (an ask id) answers an ask for a main (Ally runs).

| tower_reply | tower runs only (not the head’s) | Answer one local session (a main or a member) by intercom name or session id, under the tower’s header. reply says whether you wait for an answer; basis names what a blocked call_tower is answered from in auto mode; forward is the car-slip route (Merge train). | | tower_done | tower runs only | End the run with a handoff note for the next one: one item per line, 1 to 1,200 characters. wakeAfter (5 to 240 minutes) asks for a follow-up run, local runs only. The run stays open while the boss is in it (The boss in a run). | | board_read | towers only | The work board: each main’s one line of current work and checklist on this computer and, with Straw Link, on teammates’ computers, as JSON (see The work board). | | board_set | joined sessions that are not towers (only a tab’s main may write) | Override the main’s own board entry (it fills itself from the todo list and the name): now and up to 8 checklist items, or auto: true to hand it back; the answer says where it goes. | | link_request | every session on an attended computer, and a local tower run | Ask for a Straw Link action (create, invite, invite-unattended, join, trust, leave, remove, role, rotate) with a reason. The boss approves each one in a dialog showing the action, every argument, the reason, and this session; nothing runs unasked. Refused on an unattended device and in a remote turn. | | call_tower | joined sessions and towers | Send a message to this workspace’s tower, or another workspace’s by id or exact label, under a header. Opens the tower tab when none runs. why (required in pi: milestone, shared, or blocked) is written into the header. reply (default true) says whether the tower is expected to answer. | | boss_duty | a tab’s main (members, trains, towers, and subagents get a refusal or no tool) | Sets the main’s kind: coordinator, integrator (left out while integration is off), or standing, with a one-line reason (at most 200 characters). Refused for the same kind, for a switch away from integrator while train todos are pending or in progress, and in a Straw Link remote turn. Writes the kind entry, rebriefs (one steer), publishes sb_duty, and notes the tower’s digest. | | boss_rename | joined sessions, not towers | Sets the session’s name (pi.setSessionName) to a short phrase for its current work, trimmed, at most 40 characters (16 fit a tab label). The net and the GUI show the session by its name, and a main agent labels its Herdr tab with it (cut at 16 characters as pi-auto-tab-name cuts it, so that extension, when loaded, takes the label as its own and keeps it through compactions as a chosen name). The main renames the tab itself because pi-auto-tab-name leaves alone a tab someone else labelled, such as a tab the boss named or a tower opened with a label; a member leaves its main’s tab alone. A main agent’s prompt has it call this when its work turns to another task. A tower has no such tool: the net recognises it by its name. A name that is the label of a tower’s or a train’s tab (the tower glyph, the head glyph, train <MMDDx>) is refused: that label is what proves the role after a restore. | | boss_broadcast | joined sessions and towers | One message to every other session in a scope, under a header naming every recipient. tab, workspace and towers reach only sessions that joined the net (nearly every pi in Herdr, not sub workspace sessions; towers reaches a workspace without a tower through its mains, else its members); all reaches every pi session on the machine, joined or not (for notices such as going to sleep). Default workspace. Towers use tower_send for other towers. | | boss_server | every joined session with a screen in Herdr | status of the sb server (also with it down), logs, or restart with a reason (see The sb server). Not in a remote turn. | | tower_memory | local tower runs only | Keep what outlives the run: a standing instruction or a decision as a verbatim quote of a boss message the run took (the server checks it), the same proof to retire one, and the tower’s own waits (add, resolve, drop; a wait for the boss is a card with fields, see Tower memory). Refused to an ally run. See Tower memory. |

Command	Effect
/boss	Take over as this tab’s main agent, even when it has one.
/boss status	Show boss_status.
/boss tower	Open this workspace’s tower if none runs, then focus its tab.
/boss tower -w <workspace|head> [--answers W3] <command|message>	Another workspace’s tower, or the head: a write asks first and names it; see Another tower, the head, and answering a wait.
/boss send <name|key> [--after] <text>, /boss stop <name|key>	Write to a session as the boss, or press Esc in it; see /boss send and /boss stop.
/boss answer, /boss answer <name|key> [<choice number | text> | --cancel]	List the dialogs other sessions wait on, or answer one through the page’s route; a secret is listed and never answered; see /boss answer.
/boss head [status|retry|parked|deliver <id>|drop <id>|leave|new|close|[--answers W3] <message>]	Talk to the head tower from any pi session with a screen: a message posts as the boss’s own, a bare /boss head makes the head workspace and focuses its tab, and status, retry, parked, deliver, drop, leave, new, and close mirror /boss tower’s (The head tower).
/boss memory [-w workspace] [list|confirm P1|reject P1|add standing|decision <text>|edit S1 <text>|delete D1|resolve W1 [outcome]]	Read and change the tower’s memory, and answer the tower’s proposals; the GUI’s Memory panel is the same operation. See Tower memory.
/boss gui	Open the whole net in the browser (any session; joins nothing). It asks the sb server, which starts if it is down, and prints the URL. /boss gui stop stops the GUI, from any session, and it stays stopped until the next /boss gui or cli.mjs up (/boss stash and /boss close all do not start it). /boss gui rotate (after a confirm) gives the GUI a new token and CSRF secret and unpairs every phone, Wi-Fi ones included; the Wi-Fi certificate stays.
/boss gui lan, /boss gui lan off, /boss gui lan reset	Reach the GUI from a phone on the same Wi-Fi, without Tailscale (Wi-Fi access). lan shows the risk and makes the computer’s certificate on the first run (after you answer y), turns Wi-Fi access on, and opens a screen with the certificate steps and the pairing QR; you allow each new phone by typing the number it shows. lan off closes the listeners and forgets the wish; paired phones stay paired. lan reset asks whether to renew the certificate and keep the pairings, or make a new one and unpair every Wi-Fi device.
/boss gui view, /boss gui view auto|standard|geek|zen|raven	Show or set the GUI’s default view (gui-view over the control socket, kept in gui-prefs.json). zen is one waiting item at a time, then a session for company; a device on Auto follows it and a device that chose its own view keeps it. See View: Auto, Standard, Geek, Zen in the browser view. Only this command sets it: no page, a paired phone’s included.
/boss server [stop|restart [--downgrade] [reason]]	Show the sb server and start it when it is down; stop it on purpose; restart it. See The sb server.
/boss close all	Quit this base’s tower, mains, and members and close it, or nothing; see Stash and pop.
/boss close <name|key>, /boss close all <workspace>	Quit another unit, squad, or base after a confirm in pi, by posting close/unit, close/tab, or close/all {workspace} to the sb server’s GUI (what the page’s Quit posts). Boss-typed only: the command is refused in a tower run or an ally run, and no tool reaches it.
/boss stash [name]	Put this base away under name (the workspace label by default) and close it; see Stash and pop.
/boss stash [name] --workspace <label|id>	Put another base away after a confirm (close/stash {workspace, name}).
/boss dismiss [all|<name>]	Hide finished subagents (dismiss {all} or {key}).
/boss open base <dir> [label], open member [dir], open main <dir> [prompt]	The page’s + Base, + Member, + Main (open/base, open/member, open/main, posted with a deploy id like the page’s; src/bosspaths.ts). The folder resolves against the session’s cwd; a member with no folder is {workspace, tab} of this session’s tab, with one {workspace, dir}. While the open request is on its way the command polls open/progress; a trust in the progress is asked once per id and digest with the session’s select and answered with trust/answer {id, digest, choice, answerId} (no pi screen: left to the GUI or the terminal). A failure words the step and reason; a silent server says the unit may still open. The prompt rides the same body the page sends, so the gate on a paired device’s first message is the same (open route, BOSS_LOCAL); the remote composer’s /boss open <kind> <dir> <text> is tested too, at any depth, because the new pane would run <text> from this computer (localOnlyText in control.ts). A failure names the step as the page does (Create the base, Open a tab, Split a pane, Start the agent, …), and a member with no folder is named by its base’s label. The trust question’s select ends with the open (its signal).
/boss link [status], link decide <id> approve|refuse	link/state read for the teams and joinRequests, and link/decide for the verdict. An id is the request’s hash or a unique start of four or more characters. Approve asks in pi first: an attended request through a select of its word sets ({id, pick}; “none of these” is {id, approve: false}), an unattended one through a confirm ({id, approve: true}); refuse sends {id, approve: false} without asking. link decide is in BOSS_LOCAL because the route refuses a paired device (REMOTE_LINK is state and confirm-answer only); link and open are not. The word-set select and the unattended confirm are asked hereOnly (every choice, hereOnlyOpts() in src/intercept.ts): the ctx.ui wrap still relays a dialog opened while exactly one tool call runs, but a paired device sees it and cannot answer it. The confirms of the other BOSS_LOCAL commands (gui rotate, gui unpair all, server stop and restart) are hereOnly the same way, and each of these screens holds the pane’s overlay mark meanwhile (src/heremark.ts), so the key pad of a paired device sends Escape only to it; close and stash --workspace stay answerable from a paired device, as the page lets it close and stash.
/boss link confirms, link confirm <id> allow|deny, link asks, link answer <id> <number | text>, link invite show|cancel <hash>, link join cancel, link leave <team> [--force], link create <relay> <dir>, link join <invite | @file>, link invite <team> [unattended <device id>], link trust <device> <level>, link role <team> <device> admin|member, link remove <team> <device>, link rotate <team>	The Straw Link operations the page alone could do, posted to link/confirm-answer, link/dialog-answer, link/invite-text, link/invite-cancel, link/join-cancel, link/leave, link/create, link/join-start, link/join-project, link/invite, link/trust, link/role, link/remove, and link/rotate; the details, the hereOnly confirms, and how the relay token and an invite text stay off the transcript are under In pi in Team settings in the GUI. All of them are in BOSS_LINK_LOCAL.
/boss link units [box], link stop <box> <main | handle start> [--interrupt] [reason]	link/state read for the boxes’ units and mains, and link/unit-stop {team, device, handle, mode, reason} for the stop, after a hereOnly confirm that names the box, the main, its dispatcher and the mode. The main is found by name (any case) or the start of its handle among the mains the box’s freshest status row lists; a reason is at most 200 bytes. What a teammate wrote is shown with control and bidi characters as escapes.
/boss gui devices, /boss gui unpair <id|all>	List the paired devices (remote/devices) and unpair one or all (remote/unpair, remote/unpair-all; all after a confirm); the address does not change.
/boss server logs [n]	The last n (at most 200) lines of the server’s log, as boss_server logs.
/boss pop [name]	Open a stashed base again (any session; with no name, the only stash or one picked from the list).

/boss and boss_promote are unavailable in a sub workspace.

Stash and pop

flowchart TD
    s["/boss stash"] --> c{"Every pi idle or done,<br/>with a session file,<br/>and no subagent?"}
    c -->|"no"| r["Refused, naming why"]
    c -->|"yes"| w["Write stash/name.json,<br/>close the base"]
    w --> p["/boss pop"]
    p --> o["New workspace, each pi resumed<br/>with pi --session file"]

/boss stash puts a whole base away and /boss pop opens it again (spec). The stash runs in the sb server’s GUI, which /boss stash asks to run (no browser opens; a GUI stopped on purpose is not started: the command says so, and /boss gui starts it): only the server can ask every session’s bridge.

Details

It first checks, closing nothing: Herdr’s view (every pi pane is a tower, main, or member that is idle or done and has a session file; no subagent in the base or its sub workspaces; no shell with anything but the shell in its foreground; the base is not itself a sub workspace) and each session’s own, through its bridge’s stash-check (no running turn, no queued message, no open dialog, no running monitor). A session that does not answer within three rounds counts as a refusal, so a session on an older pi-straw-boss is never closed by a stash. Every reason is listed in one refusal.

Then it writes stash/<name>.json in the state directory (the label and folder, each tab in order with the tower’s tab first, each pane’s role, session file, name, and folder) and closes the base as Quit on a base does. A batch that stops half way (an agent refuses or stays up) deletes the manifest and names each session’s pi --session file instead, because popping it would run a session file twice.

/boss pop opens a new workspace with the same label and resumes each pi with pi --session <file>: the tower first (its session carries its tower mark), then per tab the main (with the one-time sb_open_main token, as a main the page opens) and then the members, each awaited in its role for up to 60 s; shells reopen in their folders. On success the manifest moves to stash/popped/; on a failure the new workspace closes and the manifest stays for another try. Monitors, pending intercom asks, and pane sizes are not carried over.

/boss close all (POST close/all {by}) closes the base of the session that asks, without stashing (and, like a stash, it does not start a server stopped on purpose); other bases, sub workspaces, and workspaces outside the net are never touched. It uses the stash check without what only a pop needs (session files, folders); any refusal closes nothing and lists every reason. Then the base closes as Quit on a base does, each session quitting only while it can still be stashed. The base is surveyed again just before it closes, and when the server’s own session sits in it, that session (which its batch does not ask) is checked again too.

A session that is not in a base on the net closes nothing; an invoker still alive when the server does not answer is told to check what is still open.