pi-straw-boss 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wayne930242
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# pi-straw-boss
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Many pi agents, one project, no collisions.** pi-straw-boss gives the agents you run across [Herdr](https://herdr.dev) tabs a light chain of command: a main agent per tab, a tower per workspace, and a live view of who is doing what.
+
+<!-- /boss gui screenshot goes here -->
+
+```text
+╭─ ⠸ tower · Alpha ─────────────────────────────────────────── head tower ─╮
+│ this net                                                                 │
+│ ├─ tab api-main                                                          │
+│ │  ├─ ○ api-main        main                                             │
+│ │  │  └─ ⠏ psb-sleeper  subagent  bash                                   │
+│ │  └─ ○ docs-member     member                                           │
+│ └─ tab other                                                             │
+│    └─ ? ops-main        main      waiting on a question                  │
+│ other towers                                                             │
+│ ✓ Beta                  tower                                            │
+╰──────────────────────────────────────────────────────────────────────────╯
+```
+
+## Why
+
+Run a few agents on the same project and they start stepping on each other: two dev servers on one port, two branches editing the same migration, and no agent knows the others exist. pi-straw-boss lets them find each other and coordinate, without a scheduler or a new service.
+
+- **Opt-in net.** Each session is asked once whether its work shares resources or needs to collaborate. Only those that say yes join.
+- **A main agent per tab.** The first to join a tab coordinates it; `/boss` takes over.
+- **A tower per workspace.** It opens on demand in its own tab, pinned first, and coordinates the main agents and the other towers. You don't need to talk to it.
+- **A live dashboard** in the tower: who joined, and what they and their subagents are doing.
+- **Broadcast** to a tab, a workspace, every tower, or every session.
+
+## Install
+
+```bash
+pi install npm:pi-straw-boss
+```
+
+You need pi running inside Herdr 0.9.4 or newer, and [pi-intercom](https://www.npmjs.com/package/pi-intercom) 0.17.1 or newer. [pi-herdr-agents](https://github.com/giuseppecrj/pi-herdr-agents) is optional: with it, subagents show up under the session that launched them.
+
+## Quick start
+
+1. Open pi in a Herdr tab and give it work. When the work needs to share or coordinate, the agent joins the net. You can also type `/boss`.
+2. Type `/boss status` to see each tab's main agent and the towers.
+3. Type `/boss tower` to open the workspace's tower and watch its dashboard. Agents open it themselves when they call it.
+
+## Tools and commands
+
+| Name | What it does |
+|---|---|
+| `boss_join` | Join this tab's net. |
+| `boss_status` | Main agents, this workspace's tower, and the other towers. |
+| `call_tower` | Message this workspace's tower, or another workspace's. |
+| `boss_broadcast` | Message a tab, a workspace, all towers, or every session. |
+| `/boss` | Join and become this tab's main agent. |
+| `/boss status`, `/boss tower` | Show the status; open and focus the tower. |
+
+Subagents and sessions in Herdr worktree workspaces never join: the session that launched them speaks for them. Outside Herdr the extension does nothing.
+
+## Learn more
+
+[How it works](docs/how-it-works.md) covers roles, the tower, the dashboard, what the extension writes, and how Claude Code or Codex agents can find a tower.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "pi-straw-boss",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Straw Boss coordination for pi in Herdr: sessions join a tab's net by choice, the first joiner is its main agent, a workspace tower opens on demand with a live monitoring dashboard, and boss_broadcast reaches the rest",
+  "type": "module",
+  "license": "MIT",
+  "author": "wayne930242",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wayne930242/pi-straw-boss.git"
+  },
+  "homepage": "https://github.com/wayne930242/pi-straw-boss#readme",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "herdr",
+    "intercom",
+    "orchestration"
+  ],
+  "files": [
+    "src",
+    "prompts",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --test tests/*.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-tui": "1.3.0",
+    "@types/node": "26.6.5",
+    "typebox": "1.3.27",
+    "typescript": "7.0.2"
+  }
+}

package/prompts/apps-config.md

@@ -0,0 +1,16 @@
+# Apps configuration
+
+The project's managed apps live in `.straw-boss/apps.json` at the git root, or in `.claude/straw-boss/apps.json` when the first is absent. Without either file, a repository holding one codebase is its own single app; with several plausible apps, ask which one the request targets.
+
+```json
+{"apps": [{"name": "api", "dir": "apps/api", "match": ["backend", "rest api"]}]}
+```
+
+| Field | Meaning |
+|---|---|
+| `name`, `dir`, `match` | Required: the app's name, its checkout relative to the git root, and phrases that name it in a request. |
+| `redirectTo`, `note` | A retired app: route new work to the named app and tell the user the `note`. |
+| `forbidDirectCommit` | `true`: changes reach the base branch only through a worktree branch and MR. |
+| `gitWorkflowSkill` | The app's own skill for commit, MR, and release steps; the worker follows it. |
+| `localFiles` | Gitignored files a new worktree needs, each with `path` relative to `dir`; copy them before launch. A `sensitive: true` file is copied only under the user's authorization, and an entry without `optional: true` that is missing blocks the launch. |
+| `crossAppSkills` | `withApp` and `skill`: an existing skill that handles this app depending on `withApp`; name it in the brief. |

package/prompts/main.md

@@ -0,0 +1,7 @@
+You are the main agent of Herdr tab {{tab}}: the boss (the user) works with you here. Your workspace tower is {{tower}}.
+
+- Split work by owning app ({{dir}}/apps-config.md). A task is one worker's end-to-end work in one app; parallel writers in an app each get a worktree; dependent tasks wait.
+- Brief each worker in English: required behavior, the Reality anchor, the boss's authorizations quoted; leave cause and location to the worker. End with: "When you need a decision these authorizations do not cover, call `caller_ping` and stop." Answer pings through the boss, then `subagent_resume` the worker.
+- Check each result against its brief. Merging to a shared branch or deploying needs the boss's authorization.
+- boss_status finds coordinators, call_tower reaches the tower (report coordination friction there), boss_broadcast broadcasts to the net.
+- Done when every task has landed or is reported blocked and its worktree is removed.

package/prompts/member.md

@@ -0,0 +1 @@
+Straw Boss: you joined the net of tab {{tab}}, whose main agent is {{main}}. The tower of workspace {{workspace}} is {{tower}}. Take shared-resource and collaboration questions to the main agent through intercom. Report coordination friction, such as an agent, endpoint, or shared resource you cannot reach, with call_tower.

package/prompts/reminder.md

@@ -0,0 +1 @@
+Straw Boss: before you start, decide whether your current work competes with other work in this Herdr workspace for resources (ports, databases, files, branches) or needs to collaborate with it. If so, call `boss_join` now; you become the coordinator of this tab, or a member if another session already is. If not, ignore this and do not mention it. You can still call `boss_join` later if the need appears.

package/prompts/tower.md

@@ -0,0 +1,8 @@
+You are the tower of Herdr workspace {{workspace}}; agents talk to you, the boss does not.
+
+Main agents, members, and other towers message you through intercom: answer the sender with intercom send (reply works only for asks).
+
+- Coordinate: route each request to the main agent that owns it, relaying with boss_status, call_tower, and boss_broadcast. Towers coordinate through the head tower, the tower of workspace {{head}}.
+- Boss assistant: a friction report gives expected versus actual behavior, the blocked step, and evidence. Find the owner and the broken relationship (registration, endpoint, dependency, shared resource, checkpoint, cleanup); have the owner repair it, read the state back, and have the reporter re-run its step. Return a Straw Boss source defect as a finding with evidence.
+- Never ask the boss (no ask_user, robot_hand, focus changes); decisions for the boss go back to the owning main agent.
+- Do no app work yourself.

package/src/dashboard.ts

@@ -0,0 +1,178 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { headOf, type HerdrRun, isSub, type Pane, panes, parentOf, type Session, workspaces, type Workspace } from "./herdr.ts";
+
+// The tower's monitoring screen: a widget above the editor, never focused, redrawn only while something is working.
+//
+// Data sources, all read-only:
+//  - pi-intercom listSessions(): every live session, its status (idle, thinking, tool:<name>), and its Herdr location.
+//    presence_update, session_joined, and session_left events on the tower's channel only trigger an early re-read.
+//  - `herdr pane list`: per pane the `sb_role` token (main, member), the pi session file, and Herdr's agent_status
+//    (blocked means the agent waits on a question); `herdr workspace list`: workspace status, `tower` token, worktree.
+//  - pi-herdr-agents subagents: a child's activity file lives at <sessions dir>/artifacts/<parent session id>/
+//    subagent-activity/<child id>.json, and its pane's session file name starts with `<timestamp>_<child id>`.
+//    The parent pane's own session file names the artifacts directory, so children group under the session that launched them.
+
+export type Mark = "working" | "waiting" | "idle" | "done" | "error" | "unknown";
+/** One line of the tree. `net` rows are tab (0) > session (1) > subagent (2); `towers` rows are flat. */
+export interface Row { group: "net" | "towers"; depth: number; mark: Mark; text: string; kind?: string; note?: string; workspace?: string }
+export interface Snapshot { title: string; mark: Mark; head: boolean; rows: Row[] }
+export type Tone = "accent" | "warning" | "muted" | "success" | "dim" | "error" | "border" | "title";
+export type Paint = (tone: Tone, text: string) => string;
+export interface Sources { run: HerdrRun; sessions(): Promise<Session[]>; workspaceId: string; now?: number }
+
+const KEY = "straw-boss-dashboard";
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+// One glyph and one theme color per state; a working row shows the animated spinner instead of a fixed glyph.
+const GLYPH: Record<Exclude<Mark, "working">, string> = { waiting: "?", idle: "○", done: "✓", error: "✗", unknown: "·" };
+const TONE: Record<Mark, Tone> = { working: "accent", waiting: "warning", idle: "dim", done: "success", error: "error", unknown: "muted" };
+const HERDR_MARK: Record<string, Mark> = { working: "working", blocked: "waiting", idle: "idle", done: "done" };
+const RECENT_MS = 10 * 60_000;
+const MAX_ROWS = 18;
+const MAX_WIDTH = 76;
+const MAX_CHILDREN = 8;
+
+const markOf = (status?: string): Mark => HERDR_MARK[status ?? ""] ?? "unknown";
+const pad = (text: string, width: number) => text + " ".repeat(Math.max(0, width - visibleWidth(text)));
+
+/** The pure half: a snapshot in, a framed tree out. One shared spinner frame animates every working row. */
+export function render({ title, mark, head, rows }: Snapshot, frame: number, width: number, paint: Paint): string[] {
+	const total = Math.min(width, MAX_WIDTH), inner = Math.max(8, total - 4);
+	const glyph = (m: Mark) => paint(TONE[m], m === "working" ? SPINNER[frame % SPINNER.length]! : GLYPH[m as Exclude<Mark, "working">]);
+	const shown = rows.slice(0, MAX_ROWS);
+	// A row is the last child when the next row at its depth or above is shallower (or there is none).
+	const last = (i: number) => i < 0 || shown.slice(i + 1).find((r) => r.group === shown[i]!.group && r.depth <= shown[i]!.depth)?.depth !== shown[i]!.depth;
+	const ancestor = (i: number, depth: number) => shown.findLastIndex((r, k) => k < i && r.group === shown[i]!.group && r.depth === depth);
+	const prefix = (i: number) => (shown[i]!.group === "net" ? Array.from({ length: shown[i]!.depth }, (_, d) => (last(ancestor(i, d)) ? "   " : "│  ")).join("") + (last(i) ? "└─ " : "├─ ") : "");
+	const cells = shown.map((r, i) => paint("border", prefix(i)) + (r.mark === "unknown" && !r.kind ? "" : `${glyph(r.mark)} `) + r.text);
+	const [w1, w2] = [Math.max(...cells.map(visibleWidth), 0), Math.max(...shown.map((r) => r.kind?.length ?? 0))];
+	const line = (i: number) => `${pad(cells[i]!, w1)}  ${paint("muted", (shown[i]!.kind ?? "").padEnd(w2))}  ${paint("dim", shown[i]!.note ?? "")}`.trimEnd();
+	const section = (group: Row["group"], name: string, empty?: string) => {
+		const at = shown.flatMap((r, i) => (r.group === group ? [i] : []));
+		return at.length || empty ? [paint("muted", name), ...(at.length ? at.map(line) : [paint("dim", `  ${empty}`)])] : [];
+	};
+	const body = [...section("net", "this net", "nothing has joined yet"), ...section("towers", "other towers"), ...(rows.length > MAX_ROWS ? [paint("muted", `… ${rows.length - MAX_ROWS} more`)] : [])];
+	const [name, tag] = [` ${glyph(mark)} ${paint("title", `tower · ${title}`)} `, head ? ` ${paint("accent", "head tower")} ` : ""];
+	const dashes = "─".repeat(Math.max(1, total - 4 - visibleWidth(name) - visibleWidth(tag)));
+	const frameLine = (text: string) => paint("border", "│ ") + pad(truncateToWidth(text, inner), inner) + paint("border", " │");
+	return [paint("border", "╭─") + name + paint("border", dashes) + tag + paint("border", "─╮"), ...body.map(frameLine), paint("border", `╰${"─".repeat(total - 2)}╯`)].map((l) => truncateToWidth(l, width));
+}
+
+function readJson(path: string): Record<string, unknown> {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return {};
+	}
+}
+
+/** The subagents a pi session launched: live ones, plus those that finished in the last 10 minutes. */
+function subagents(parent: Pane | undefined, all: Pane[], now: number): Row[] {
+	const file = parent?.agent_session?.value;
+	if (!file) return [];
+	const dir = join(dirname(file), "artifacts", basename(file, ".jsonl").split("_").pop()!);
+	let files: string[] = [];
+	try {
+		files = readdirSync(join(dir, "subagent-activity"));
+	} catch {} // no subagents were ever launched from this session
+	return files
+		.map((name) => {
+			const id = name.replace(/\.json$/, "");
+			const path = join(dir, "subagent-activity", name);
+			return { id, path, pane: all.find((p) => p.agent_session?.value.includes(`_${id}`)), age: now - statSync(path).mtimeMs };
+		})
+		.filter((c) => c.pane || c.age < RECENT_MS)
+		.map(({ id, path, pane }) => {
+			const activity = readJson(path);
+			// A child whose pane is gone, or back at a shell prompt, has finished.
+			const mark: Mark = pane?.agent === "pi" ? markOf(pane.agent_status) : "done";
+			let script: string | undefined;
+			try {
+				script = readdirSync(join(dir, "subagent-scripts")).find((f) => f.endsWith(`-${id}.sh`));
+			} catch {} // the launch script is only a fallback source for the name
+			const name = pane?.label ?? script?.slice(0, -`-${id}.sh`.length) ?? id.slice(0, 8);
+			const doing = activity.toolActive ? String(activity.toolName) : String(activity.phase ?? "");
+			return { group: "net" as const, depth: 2, mark, text: name, kind: "subagent", workspace: pane?.workspace_id, note: { working: doing, waiting: "waiting on a question", done: "finished" }[mark as "working"] };
+		})
+		.sort((a, b) => Number(a.mark === "done") - Number(b.mark === "done") || a.text.localeCompare(b.text))
+		.slice(0, MAX_CHILDREN);
+}
+
+/**
+ * One reading of the world as rows: this tower's own net in detail (each tab's joined sessions with their subagents, then its
+ * sub workspaces), and one summary line for every other tower. Other workspaces' sessions, and sessions that did not join, are not listed.
+ */
+export async function collect({ run, sessions, workspaceId, now = Date.now() }: Sources): Promise<Snapshot> {
+	const [live, ps, all] = [await sessions(), await panes(run), await workspaces(run)];
+	const head = headOf(all);
+	const mine = all.find((w) => w.workspace_id === workspaceId);
+	const sessionRow = (s: Session, role: string): Row => {
+		const pane = ps.find((p) => p.pane_id === s.herdrLocation?.paneId);
+		const busy = s.status ? s.status !== "idle" : undefined;
+		const mark: Mark = pane?.agent_status === "blocked" ? "waiting" : busy === undefined ? markOf(pane?.agent_status) : busy ? "working" : "idle";
+		return { group: "net", depth: 1, mark, text: s.name ?? s.id, kind: role, note: { working: s.status, waiting: "waiting on a question" }[mark as "working"] };
+	};
+	const joined = live.filter((s) => s.herdrLocation?.workspace?.id === workspaceId).flatMap((s) => {
+		const pane = ps.find((p) => p.pane_id === s.herdrLocation?.paneId);
+		const role = pane?.tokens?.sb_role;
+		return role === "main" || role === "member" ? [{ s, pane, role, tab: s.herdrLocation!.tab! }] : [];
+	});
+	const rows: Row[] = [];
+	for (const group of Object.values(Object.groupBy(joined, (j) => j.tab.id))) {
+		rows.push({ group: "net", depth: 0, mark: "unknown", text: `tab ${group![0]!.tab.label}` });
+		for (const { s, pane, role } of group!.sort((a, b) => Number(b.role === "main") - Number(a.role === "main"))) rows.push(sessionRow(s, role), ...subagents(pane, ps, now));
+	}
+	// Sub workspaces are linked worktrees: they hang under this tower like subagents, and their sessions never join. One that
+	// already shows as a launched subagent (pi-herdr-agents runs worktree children there) is not listed a second time.
+	const claimed = new Set(rows.map((r) => r.workspace));
+	for (const sub of all.filter((x) => isSub(x) && mine && parentOf(all, x) === mine && !claimed.has(x.workspace_id))) rows.push({ group: "net", depth: 0, mark: markOf(sub.agent_status), text: sub.label, kind: "sub workspace" });
+	for (const w of all.filter((x) => x !== mine && !isSub(x) && live.some((s) => s.id === x.tokens?.tower))) rows.push({ group: "towers", depth: 0, mark: markOf(w.agent_status), text: w.label, kind: w === head ? "head tower" : "tower" });
+	// The title shows what needs attention most: a waiting row, then a working one, else the workspace's own status.
+	const attention = (["waiting", "working"] as const).find((m) => rows.some((r) => r.mark === m));
+	return { title: mine?.label ?? workspaceId, mark: attention ?? markOf(mine?.agent_status), head: Boolean(mine) && mine === head, rows };
+}
+
+export interface Dashboard { poke(): void; stop(): void }
+export interface Timing { frameMs?: number; pollMs?: number; minGapMs?: number }
+
+/**
+ * Shows the dashboard in a tower's TUI. The spinner timer (8 fps) runs only while a row is working; the data poll (3 s)
+ * runs while the widget exists. stop() clears both timers and the widget, and pi disposing the widget does the same.
+ */
+export function startDashboard({ ui, collect: read, frameMs = 125, pollMs = 3000, minGapMs = 500 }: { ui: ExtensionContext["ui"]; collect(): Promise<Snapshot> } & Timing): Dashboard {
+	let live: Dashboard | undefined;
+	ui.setWidget(KEY, (tui, theme) => {
+		let snap: Snapshot = { title: "", mark: "unknown", head: false, rows: [] }, frame = 0, busy = false, stopped = false, last = 0;
+		let spinner: ReturnType<typeof setInterval> | undefined;
+		const refresh = async () => {
+			if (busy || stopped) return;
+			busy = true;
+			try {
+				snap = await read();
+			} catch (error) {
+				snap = { ...snap, mark: "error", rows: [{ group: "net", depth: 0, mark: "error", text: `dashboard unavailable: ${(error as Error).message}` }] };
+			}
+			busy = false;
+			last = Date.now();
+			if (stopped) return;
+			const working = snap.mark === "working" || snap.rows.some((r) => r.mark === "working");
+			if (working && !spinner) spinner = setInterval(() => (frame++, tui.requestRender()), frameMs).unref();
+			if (!working && spinner) spinner = void clearInterval(spinner);
+			tui.requestRender();
+		};
+		const poll = setInterval(() => void refresh(), pollMs).unref();
+		const stop = () => {
+			stopped = true;
+			clearInterval(poll);
+			clearInterval(spinner);
+			spinner = undefined;
+		};
+		live = { poke: () => void (Date.now() - last >= minGapMs && refresh()), stop };
+		void refresh();
+		const paint: Paint = (tone, text) => (tone === "title" ? theme.bold(theme.fg("accent", text)) : theme.fg(tone, text));
+		return { render: (width) => render(snap, frame, width, paint), invalidate() {}, dispose: stop };
+	});
+	return { poke: () => live?.poke(), stop: () => (ui.setWidget(KEY, undefined), live?.stop(), (live = undefined), undefined) };
+}

package/src/herdr.ts

@@ -0,0 +1,144 @@
+import { execFile } from "node:child_process";
+import { createConnection } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type HerdrRun = (args: string[], timeoutMs?: number) => Promise<string>;
+/** One request on Herdr's socket API; rejects with the error Herdr answered. */
+export type HerdrApi = (method: string, params: object) => Promise<void>;
+export type Sleep = (ms: number) => Promise<void>;
+export interface Place { paneId: string; tabId: string; workspaceId: string }
+export interface Workspace { workspace_id: string; label: string; agent_status?: string; tokens?: Record<string, string>; worktree?: { checkout_path?: string; is_linked_worktree?: boolean; repo_key?: string } }
+export interface Pane { pane_id: string; tab_id: string; workspace_id?: string; agent?: string; agent_status?: string; agent_session?: { value: string }; label?: string; tokens?: Record<string, string> }
+export interface Location { status: string; workspace?: { id: string; label: string }; tab?: { id: string; label: string }; paneId?: string }
+/** A live pi-intercom session; `status` is idle, thinking, or tool:<name>. */
+export interface Session { id: string; name?: string; status?: string; herdrLocation?: Location }
+export interface TowerEnv { run: HerdrRun; sleep: Sleep; live(sessionId: string): Promise<boolean>; moveFirst(tabId: string): Promise<void> }
+
+const TTL_MS = 10 * 60_000;
+const START_MS = 30_000;
+const TOWER_WAIT_MS = 60_000;
+const START_ATTEMPTS = 20;
+const opening = new Map<string, Promise<{ id: string; opened: boolean }>>();
+
+export const herdrRun: HerdrRun = (args, timeoutMs = 5000) =>
+	new Promise((resolve, reject) => {
+		execFile(process.env.HERDR_BIN_PATH || "herdr", args, { timeout: timeoutMs }, (error, stdout, stderr) => {
+			if (error) reject(new Error(`herdr ${args.join(" ")} failed: ${stderr.trim() || error.message}`));
+			else resolve(stdout);
+		});
+	});
+
+// Every herdr reply wraps its payload in `result`.
+async function result(run: HerdrRun, args: string[], timeoutMs?: number) {
+	const output = await run(args, timeoutMs);
+	try {
+		return JSON.parse(output).result;
+	} catch {
+		throw new Error(`herdr ${args.join(" ")} returned invalid JSON: ${output.slice(0, 200)}`);
+	}
+}
+
+export async function place(run: HerdrRun): Promise<Place> {
+	const pane = (await result(run, ["pane", "current"])).pane;
+	return { paneId: pane.pane_id, tabId: pane.tab_id, workspaceId: pane.workspace_id };
+}
+
+/** A sub workspace is a linked git worktree that Herdr opened as its own workspace: it is treated like a subagent of its parent. */
+export const isSub = (w: Workspace) => w.worktree?.is_linked_worktree === true;
+export const parentOf = (all: Workspace[], w: Workspace) => all.find((p) => !isSub(p) && p.worktree?.repo_key !== undefined && p.worktree.repo_key === w.worktree?.repo_key);
+/** The head tower's workspace: the first one in list order that is not a sub workspace. */
+export const headOf = (all: Workspace[]) => all.find((w) => !isSub(w));
+
+export const workspaces = async (run: HerdrRun): Promise<Workspace[]> => (await result(run, ["workspace", "list"])).workspaces;
+
+export async function panes(run: HerdrRun, workspace?: string): Promise<Pane[]> {
+	return (await result(run, ["pane", "list", ...(workspace ? ["--workspace", workspace] : [])])).panes;
+}
+
+export const herdrApi = (socketPath = process.env.HERDR_SOCKET_PATH || join(homedir(), ".config", "herdr", "herdr.sock")): HerdrApi => (method, params) =>
+	new Promise((resolve, reject) => {
+		const socket = createConnection(socketPath).setTimeout(5000);
+		let reply = "";
+		const end = (error?: Error) => (socket.destroy(), error ? reject(error) : resolve());
+		socket.on("connect", () => socket.write(`${JSON.stringify({ id: "straw-boss", method, params })}\n`));
+		socket.on("data", (chunk) => {
+			reply += chunk;
+			if (!reply.includes("\n")) return;
+			const { error } = JSON.parse(reply.split("\n")[0]!) as { error?: { code?: string; message?: string } };
+			end(error && new Error(`herdr ${method} failed: ${error.code ?? ""} ${error.message ?? ""}`.trim()));
+		});
+		socket.on("timeout", () => end(new Error(`herdr ${method} timed out`)));
+		socket.on("error", (error) => end(new Error(`herdr ${method} failed: ${error.message}`)));
+	});
+
+/** Writes display-and-discovery tokens (null clears one). Herdr takes the positional id before the options. */
+export function report(run: HerdrRun, kind: "pane" | "workspace", id: string, tokens: Record<string, string | null>) {
+	const flags = Object.entries(tokens).flatMap(([name, value]) => (value === null ? ["--clear-token", name] : ["--token", `${name}=${value}`]));
+	const ttl = flags.includes("--token") ? ["--ttl-ms", String(TTL_MS)] : [];
+	return run([kind, "report-metadata", id, "--source", "straw-boss", ...ttl, ...flags]);
+}
+
+/** Polls until `check` returns something truthy, or `ms` have passed. */
+export async function waitFor<T>(sleep: Sleep, check: () => T | Promise<T>, ms: number, step = 100): Promise<Awaited<T> | undefined> {
+	for (let waited = 0; waited <= ms; waited += step) {
+		const value = await check();
+		if (value) return value;
+		await sleep(step);
+	}
+}
+
+/** The live tower of a workspace, opening its `tower` tab when there is none. One opening at a time per workspace. */
+export function ensureTower(env: TowerEnv, workspace: Workspace, cwd: string) {
+	const existing = opening.get(workspace.workspace_id);
+	if (existing) return existing;
+	const pending = open(env, workspace, cwd).finally(() => opening.delete(workspace.workspace_id));
+	opening.set(workspace.workspace_id, pending);
+	return pending;
+}
+
+async function open({ run, sleep, live, moveFirst }: TowerEnv, workspace: Workspace, cwd: string) {
+	const ws = workspace.workspace_id;
+	const held = async () => {
+		const id = (await workspaces(run)).find((w) => w.workspace_id === ws)?.tokens?.tower;
+		return id && (await live(id)) ? id : undefined;
+	};
+	const current = await held();
+	if (current) return { id: current, opened: false };
+
+	// A leftover tower tab is reused: a pane already running pi only needs its token awaited, a shell prompt gets pi started.
+	// The tab is told apart by the `sb_role=tower` pane token that only Straw Boss writes; a tab merely labelled "tower"
+	// (a pi-herdr-agents subagent can be named so) is someone else's.
+	let paneId: string;
+	let running = false;
+	const marked = (await panes(run, ws)).find((p) => p.tokens?.sb_role === "tower");
+	if (marked) {
+		paneId = marked.pane_id;
+		running = marked.agent === "pi";
+		await moveFirst(marked.tab_id);
+	} else {
+		const dir = workspace.worktree?.checkout_path ?? cwd;
+		const created = await result(run, ["tab", "create", "--workspace", ws, "--label", "tower", "--cwd", dir, "--no-focus", "--env", "STRAW_BOSS_ROLE=tower"]);
+		paneId = created.root_pane.pane_id;
+		// Marked at once, so a tab left without pi is recognised (while the marker lasts) and the label stays display only.
+		await report(run, "pane", paneId, { sb_role: "tower" });
+		await moveFirst(created.tab.tab_id);
+	}
+	if (!running) {
+		// Herdr agent names are unique across workspaces and lowercase only, so the name carries the lowercased workspace id.
+		const start = ["agent", "start", `tower-${ws.toLowerCase()}`, "--kind", "pi", "--pane", paneId, "--timeout", String(START_MS), "--", "--name", `tower · ${workspace.label}`];
+		// A new tab's shell may not be at its prompt yet: herdr answers agent_pane_busy until it is, and any other failure is final.
+		for (let attempt = 1; ; attempt++) {
+			try {
+				await run(start, START_MS + 5000);
+				break;
+			} catch (error) {
+				if (attempt === START_ATTEMPTS || !(error as Error).message.includes("agent_pane_busy")) throw error;
+				await sleep(500);
+			}
+		}
+	}
+	const id = await waitFor(sleep, held, TOWER_WAIT_MS, 1000);
+	if (!id) throw new Error(`The tower of ${workspace.label} did not publish its token within ${TOWER_WAIT_MS / 1000} s (pane ${paneId})`);
+	return { id, opened: true };
+}

package/src/index.ts

@@ -0,0 +1,349 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type, type Static, type TSchema } from "typebox";
+import { collect, startDashboard } from "./dashboard.ts";
+import { ensureTower, headOf, herdrApi, type HerdrApi, herdrRun, type HerdrRun, isSub, type Pane, panes, parentOf, place, type Place, report, type Session, type Sleep, waitFor, workspaces, type Workspace } from "./herdr.ts";
+
+// pi-intercom's extension API as constants and minimal types: intercom is a runtime requirement, not an import.
+const REGISTER = "intercom:extension-register";
+const OUTBOX = "intercom:outbox-request";
+const OUTBOX_RESULT = "intercom:outbox-result";
+const NAMESPACE = /^[a-z0-9][a-z0-9._/-]{0,63}$/;
+const ENTRY = "straw-boss";
+const PROMPTS = ["main", "tower", "member", "reminder"];
+const REFRESH_MS = 4 * 60_000;
+const CLAIM_MS = 5000;
+const CONNECT_MS = 15_000;
+const SEND_MS = 30_000;
+const SETTLE_MS = 2000;
+
+interface Channel {
+	snapshot(): { connected: boolean; supported: boolean; owner?: { sessionId: string }; state?: { payload: unknown } };
+	publish(payload: unknown, options?: { audience?: "owner" | "capable" }): void;
+	commitState(payload: unknown, expectedRevision?: number): void;
+	listSessions(): Promise<Session[]>;
+}
+interface SendResult { requestId?: string; status: string; code?: string; detail?: string }
+interface Saved { asked?: boolean; joined?: boolean; tower?: boolean }
+type Role = "tower" | "main" | "member";
+type Scope = "tab" | "workspace" | "towers" | "all";
+type Member = ReturnType<typeof netMembers>[number];
+export interface Deps { run?: HerdrRun; api?: HerdrApi; env?: NodeJS.ProcessEnv; sleep?: Sleep; promptDir?: string }
+
+/** Live sessions whose pane carries an `sb_role` token: the sessions that joined the net, and towers. */
+function netMembers(sessions: Session[], ps: Pane[]) {
+	return sessions.flatMap((s) => {
+		const { workspace, tab, paneId } = s.herdrLocation ?? {};
+		const role = ps.find((p) => p.pane_id === paneId)?.tokens?.sb_role;
+		return workspace && tab && role ? [{ s, role, tab, workspace }] : [];
+	});
+}
+const nameOf = (s?: Session) => (s ? (s.name ?? s.id) : "");
+
+export function createStrawBoss({ run = herdrRun, api = herdrApi(), env = process.env, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), promptDir = fileURLToPath(new URL("../prompts", import.meta.url)) }: Deps = {}) {
+	return function strawBoss(pi: ExtensionAPI): void {
+		// Outside Herdr there is no tab to coordinate. A pi-herdr-agents worker never joins: its parent represents it.
+		if (!env.HERDR_PANE_ID || env.PI_SUBAGENT_ID) return;
+		let isTower = env.STRAW_BOSS_ROLE === "tower";
+		let asked = false, joined = false, isMain = false, holdsTower = false, requests = 0;
+		// Why this session cannot join: it sits in a sub workspace, or Herdr could not say whether it does.
+		let barred: string | undefined, dashboard: ReturnType<typeof startDashboard> | undefined, hasUI = false;
+		let prompts: Record<string, string> = {}, info: Record<string, string> = {}, saved: Saved = {};
+		let c!: Channel, at!: Place, ui: ExtensionContext["ui"] | undefined, timer: ReturnType<typeof setInterval> | undefined;
+		let queue: Promise<void> = Promise.resolve();
+		const me = () => env.PI_INTERCOM_SESSION_ID ?? "";
+		const role = (): Role | undefined => {
+			if (isTower) return "tower";
+			if (!joined) return undefined;
+			return isMain ? "main" : "member";
+		};
+		const tell = (text: string, level: "info" | "warning" | "error" = "info") => ui?.notify(text, level);
+		const render = (text = "") => text.replace(/\{\{(\w+)\}\}/g, (_, key: string) => ({ dir: promptDir, ...info })[key] || "none yet");
+		const tool = <P extends TSchema>(name: string, description: string, parameters: P, body: (params: Static<P>) => Promise<{ text: string; details?: unknown }>) =>
+			pi.registerTool({
+				name, label: name, description, parameters,
+				execute: async (_id, params) => {
+					const { text, details } = await body(params);
+					return { content: [{ type: "text", text }], details };
+				},
+			});
+		const connect = (eligible: boolean) => {
+			const namespace = `straw-boss/tab/${Buffer.from(at.tabId).toString("hex")}`;
+			if (!NAMESPACE.test(namespace)) throw new Error(`Tab id ${at.tabId} is too long for an intercom namespace (limit 24 characters)`);
+			pi.events.emit(REGISTER, { namespace, ownerEligible: eligible, onReady: (channel: Channel) => (c = channel), onEvent });
+			if (!c) throw new Error("pi-intercom is not loaded (Straw Boss needs pi-intercom >= 0.17.1)");
+		};
+
+		// Tokens are display and discovery only: a failed write waits for the next refresh, liveness comes from intercom.
+		const publish = async () => {
+			const sbRole = role();
+			if (sbRole) await report(run, "pane", at.paneId, { sb_role: sbRole }).catch(() => {});
+			if (holdsTower) await report(run, "workspace", at.workspaceId, { tower: me() }).catch(() => {});
+		};
+		const keepFresh = () => {
+			timer ??= setInterval(() => void publish(), REFRESH_MS);
+			timer.unref();
+		};
+
+		// The owner records who is main. The first joiner pins itself, so a later owner change never swaps the main agent.
+		const pin = (main?: string) => {
+			if (main && c.snapshot().owner?.sessionId === me()) c.commitState({ v: 1, main, since: Date.now() });
+		};
+		const onEvent = (event: { type: string; fromSessionId?: string; payload?: { type?: string } }) => {
+			if (event.type === "message" && event.payload?.type === "claim") pin(event.fromSessionId);
+			else if (["connection", "owner", "state", "session_left"].includes(event.type)) void sync();
+			if (["presence_update", "session_joined", "session_left"].includes(event.type)) dashboard?.poke();
+		};
+		const refresh = async () => {
+			if (!joined) return;
+			try {
+				const snap = c.snapshot();
+				const sessions = await c.listSessions();
+				let main = (snap.state?.payload as { main?: string } | undefined)?.main;
+				if (!sessions.some((s) => s.id === main)) {
+					// The pinned main is gone: the owner is main until it pins itself.
+					main = snap.owner?.sessionId;
+					pin(main);
+				}
+				const ws = (await workspaces(run)).find((w) => w.workspace_id === at.workspaceId);
+				const tab = sessions.find((s) => s.id === me())?.herdrLocation?.tab?.label ?? at.tabId;
+				info = { tab, workspace: ws?.label ?? at.workspaceId, main: nameOf(sessions.find((s) => s.id === main)), tower: nameOf(sessions.find((s) => s.id === ws?.tokens?.tower)) };
+				const wasMain = isMain;
+				isMain = main === me();
+				if (isMain !== wasMain) tell(`This session is ${isMain ? "now" : "no longer"} the main agent of ${info.tab}`);
+				await publish();
+			} catch (error) {
+				tell(`Straw Boss: ${(error as Error).message}`, "warning");
+			}
+		};
+		const sync = () => (queue = queue.then(refresh));
+		// A session that has just started connects to the broker a moment after session_start.
+		const connected = async () => {
+			if (await waitFor(sleep, () => c.snapshot().connected && c.snapshot().supported, CONNECT_MS)) return;
+			throw new Error(c.snapshot().connected ? "The intercom broker lacks extension-bus-v1" : "pi-intercom is not connected");
+		};
+		const joinNet = async (restored = false) => {
+			if (joined) return;
+			if (barred) throw new Error(barred);
+			at = await place(run);
+			connect(true);
+			await connected();
+			if (!(await waitFor(sleep, () => c.snapshot().owner, CLAIM_MS))) throw new Error("No intercom owner was elected for this tab");
+			joined = true;
+			if (!restored) pi.appendEntry(ENTRY, { asked: true, joined: true });
+			addNetTools();
+			keepFresh();
+			await sync();
+		};
+		const takeover = async () => {
+			await joinNet();
+			if (!isMain) {
+				if (c.snapshot().owner?.sessionId === me()) pin(me());
+				else c.publish({ type: "claim" }, { audience: "owner" });
+				if (!(await waitFor(sleep, () => isMain, CLAIM_MS))) throw new Error("The owner did not confirm the takeover within 5 s");
+			}
+			return `This session is the main agent of tab ${info.tab}`;
+		};
+		const send = (to: string, message: string) =>
+			new Promise<SendResult>((resolve) => {
+				const requestId = `straw-boss-${me()}-${++requests}`;
+				const done = (result: SendResult) => {
+					off();
+					clearTimeout(timeout);
+					resolve(result);
+				};
+				const off = pi.events.on(OUTBOX_RESULT, (data) => (data as SendResult).requestId === requestId && done(data as SendResult));
+				const timeout = setTimeout(() => done({ status: "failed", detail: `no result within ${SEND_MS / 1000} s` }), SEND_MS);
+				pi.events.emit(OUTBOX, { version: 1, requestId, extensionId: "pi-straw-boss", extensionName: "Pi Straw Boss", to, message });
+			});
+		const openTower = async (query?: string) => {
+			const all = await workspaces(run);
+			const found = all.filter((w) => (query ? w.workspace_id === query || w.label === query : w.workspace_id === at.workspaceId));
+			if (found.length !== 1) {
+				throw new Error(`${found.length ? "Several workspaces match" : "No workspace matches"} "${query}". Workspaces: ${all.map((w) => `${w.workspace_id} (${w.label})`).join(", ")}`);
+			}
+			// A sub workspace never has a tower: its parent workspace's tower serves it.
+			const asked = found[0]!;
+			const target = isSub(asked) ? parentOf(all, asked) : asked;
+			if (!target) throw new Error(`${asked.label} is a sub workspace with no open parent workspace, so it has no tower; open the parent workspace first`);
+			if (isTower && target.workspace_id === at.workspaceId) throw new Error("This session is the tower of that workspace");
+			const live = async (id: string) => (await c.listSessions()).some((s) => s.id === id);
+			const moveFirst = (tabId: string) => api("tab.move", { tab_id: tabId, insert_index: 0 }).catch((error: Error) => tell(`Straw Boss: could not move the tower tab first: ${error.message}`, "warning"));
+			return { target, routed: target !== asked ? asked : undefined, ...(await ensureTower({ run, sleep, live, moveFirst }, target, process.cwd())) };
+		};
+		const status = async () => {
+			const sessions = await c.listSessions();
+			const [ps, all] = [await panes(run), await workspaces(run)];
+			const mine = all.find((w) => w.workspace_id === at.workspaceId);
+			const towerOf = (w?: Workspace) => {
+				const s = sessions.find((x) => x.id === w?.tokens?.tower);
+				return s && w && { workspace: w.label, id: s.id, name: nameOf(s), head: w === headOf(all) };
+			};
+			const own = netMembers(sessions, ps).filter((m) => m.workspace.id === at.workspaceId && m.role !== "tower");
+			const tabs = Object.values(Object.groupBy(own, (m) => m.tab.id)).map((group = []) => ({
+				id: group[0]?.tab.id,
+				label: group[0]?.tab.label,
+				main: group.find((m) => m.role === "main")?.s.id ?? null,
+				sessions: group.length,
+			}));
+			return {
+				me: { id: me(), role: role() },
+				workspace: { id: at.workspaceId, label: mine?.label },
+				head: headOf(all)?.workspace_id,
+				tower: towerOf(mine) ?? null,
+				tabs,
+				towers: all.filter((w) => w !== mine).flatMap((w) => towerOf(w) ?? []),
+			};
+		};
+		const broadcast = async (message: string, scope: Scope) => {
+			const others = (await c.listSessions()).filter((s) => s.id !== me());
+			const inScope = (m: Member) => ({ tab: m.tab.id === at.tabId, workspace: m.workspace.id === at.workspaceId, towers: m.role === "tower" })[scope as Exclude<Scope, "all">];
+			// tab, workspace, and towers reach the net only; all reaches every other pi session on the machine.
+			const targets = scope === "all" ? others : netMembers(others, await panes(run)).filter(inScope).map((m) => m.s);
+			const results = await Promise.all(targets.map(async (s) => ({ id: s.id, name: nameOf(s), ...(await send(s.id, message)) })));
+			const summary = results.map((r) => `${r.name}: ${r.status}${r.code ? ` (${r.code})` : ""}`).join("\n") || "no recipients";
+			if (results.some((r) => r.status !== "sent")) throw new Error(`Not every recipient received it:\n${summary}`);
+			return { text: `Broadcast to ${results.length} session(s):\n${summary}`, details: { scope, results } };
+		};
+		function addNetTools() {
+			tool("boss_status", "Show this workspace's Straw Boss coordinators: each tab's main agent, this workspace's tower, the head tower, and the other towers.", Type.Object({}), async () => {
+				const result = await status();
+				return { text: JSON.stringify(result, null, 2), details: result };
+			});
+			tool("call_tower", "Send a message to the tower of your workspace, or of another workspace by id or exact label. Opens the tower tab when none is running; the tower replies through intercom.",
+				Type.Object({
+					message: Type.String({ description: "What the tower needs to know or do: at most two sentences, details by reference." }),
+					workspace: Type.Optional(Type.String({ description: "Another workspace's id or exact label. Omit for your own." })),
+				}),
+				async ({ message, workspace }) => {
+					const tower = await openTower(workspace);
+					const result = await send(tower.id, message);
+					if (result.status !== "sent") throw new Error(`The tower of ${tower.target.label} did not take the message: ${result.status} ${result.code ?? ""} ${result.detail ?? ""}`.trim());
+					const via = tower.routed ? ` (${tower.routed.label} is a sub workspace)` : "";
+					const text = `Sent to the tower of ${tower.target.label}${via}${tower.opened ? " (opened it)" : ""}. It replies through intercom.`;
+					return { text, details: { workspace: tower.target.workspace_id, towerId: tower.id, opened: tower.opened, status: result.status } };
+				});
+			tool("boss_broadcast", "Send one message to every other session in a scope. tab, workspace, and towers reach only sessions that joined the net; all reaches every pi session on this machine (for notices such as the boss going to sleep).",
+				Type.Object({
+					message: Type.String({ description: "The message, once; receivers do not re-broadcast it." }),
+					scope: Type.Optional(Type.Union([Type.Literal("tab"), Type.Literal("workspace"), Type.Literal("towers"), Type.Literal("all")], { description: "Default workspace." })),
+				}),
+				({ message, scope }) => broadcast(message, scope ?? "workspace"));
+		}
+		const startTower = async () => {
+			at = await place(run);
+			connect(false);
+			await connected();
+			if (!saved.tower) pi.appendEntry(ENTRY, { tower: true, workspaceId: at.workspaceId });
+			await report(run, "pane", at.paneId, { sb_role: "tower" });
+			await sleep(SETTLE_MS);
+			const all = await workspaces(run);
+			const [ps, sessions] = [await panes(run, at.workspaceId), await c.listSessions()];
+			const ws = all.find((w) => w.workspace_id === at.workspaceId);
+			const holder = ws?.tokens?.tower;
+			const rival = ps.find((p) => p.pane_id !== at.paneId && p.agent === "pi" && p.tokens?.sb_role === "tower");
+			// A second tower in one workspace yields before it publishes: the live token holder wins, otherwise the lower tab id.
+			if ((holder && holder !== me() && sessions.some((s) => s.id === holder)) || (rival && rival.tab_id < at.tabId)) {
+				await report(run, "pane", at.paneId, { sb_role: null });
+				await run(["tab", "close", at.tabId]);
+				return;
+			}
+			holdsTower = true;
+			info = { workspace: ws?.label ?? at.workspaceId, head: headOf(all)?.label ?? "" };
+			addNetTools();
+			keepFresh();
+			await publish();
+			// The dashboard lives exactly as long as this session holds the tower role.
+			if (hasUI) dashboard = startDashboard({ ui: ui!, collect: () => collect({ run, sessions: () => c.listSessions(), workspaceId: at.workspaceId }) });
+		};
+
+		// A session in a sub workspace (a linked git worktree) acts like a subagent: it never joins. Failing to tell bars it too.
+		const barReason = async () => {
+			try {
+				const { workspaceId } = await place(run);
+				const all = await workspaces(run);
+				const sub = all.find((w) => w.workspace_id === workspaceId);
+				return sub && isSub(sub) ? { text: `${sub.label} is a sub workspace, so this session cannot join the net; the main agent of its parent workspace represents it`, level: "info" as const } : undefined;
+			} catch (error) {
+				return { text: `Straw Boss could not tell whether this is a sub workspace: ${(error as Error).message}`, level: "error" as const };
+			}
+		};
+
+		pi.on("session_start", async (_event, ctx) => {
+			ui = ctx.ui;
+			hasUI = ctx.hasUI;
+			prompts = Object.fromEntries(PROMPTS.map((name) => [name, readFileSync(join(promptDir, `${name}.md`), "utf8").trim()]));
+			saved = Object.assign({}, ...ctx.sessionManager.getBranch().flatMap((e) => (e.type === "custom" && e.customType === ENTRY ? [e.data] : [])));
+			asked = Boolean(saved.asked);
+			isTower ||= Boolean(saved.tower);
+			// Starting runs in the background: pi awaits session_start handlers in turn, and pi-intercom connects in its own, after this one.
+			let starting: Promise<void> | undefined;
+			if (isTower) {
+				starting = startTower();
+			} else {
+				const bar = await barReason();
+				barred = bar?.text;
+				if (bar) {
+					tell(bar.text, bar.level);
+				} else {
+					tool("boss_join", "Join this Herdr workspace's Straw Boss net when your current work competes for resources with, or collaborates with, other work in the workspace. The first session of a tab to join becomes its main agent; later ones are members.", Type.Object({}), async () => {
+						await joinNet();
+						const text = isMain ? `Joined as the main agent of tab ${info.tab}.` : `Joined tab ${info.tab} as a member; its main agent is ${info.main}.`;
+						return { text, details: { role: role() } };
+					});
+					if (saved.joined) starting = joinNet(true);
+				}
+			}
+			starting?.catch((error: Error) => tell(`Straw Boss: ${error.message}`, "error"));
+		});
+
+		pi.on("before_agent_start", (event) => {
+			const current = role();
+			// A session outside the net is asked once, at its first run, whether it should join.
+			const first = !current && !asked && !barred;
+			if (first) {
+				asked = true;
+				pi.appendEntry(ENTRY, { asked: true });
+			}
+			let text: string | undefined;
+			if (current) text = render(prompts[current]);
+			else if (first) text = render(prompts.reminder);
+			if (text) event.systemPromptOptions.sections[ENTRY] = text;
+			else delete event.systemPromptOptions.sections[ENTRY];
+		});
+
+		pi.on("session_shutdown", async () => {
+			dashboard?.stop();
+			dashboard = undefined;
+			clearInterval(timer);
+			timer = undefined;
+			const held = holdsTower;
+			holdsTower = false;
+			if (!role() || !at) return;
+			await report(run, "pane", at.paneId, { sb_role: null }).catch(() => {});
+			if (held) await report(run, "workspace", at.workspaceId, { tower: null }).catch(() => {});
+		});
+
+		pi.registerCommand("boss", {
+			description: "Join this tab's Straw Boss net and become its main agent. /boss status shows the coordinators; /boss tower opens and focuses the workspace tower.",
+			handler: async (args, ctx) => {
+				ui = ctx.ui;
+				try {
+					if (args.trim() === "status") return tell(joined || isTower ? JSON.stringify(await status(), null, 2) : "Not in the net. /boss joins it.");
+					if (isTower) throw new Error("This session is the tower, not a main agent");
+					if (args.trim() !== "tower") return tell(await takeover());
+					await joinNet();
+					const tower = await openTower();
+					const where = (await c.listSessions()).find((s) => s.id === tower.id)?.herdrLocation;
+					if (where?.tab) await run(["tab", "focus", where.tab.id]);
+				} catch (error) {
+					tell((error as Error).message, "error");
+				}
+			},
+		});
+	};
+}
+
+export default createStrawBoss();