pi-straw-boss 0.0.0-stage → 0.1.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,85 @@
-# 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.
+Straw Boss coordination for [pi](https://pi.dev) sessions that run in [Herdr](https://herdr.dev): a session **joins** a small net when its work competes or collaborates with other work in the workspace, the first to join a tab becomes its **main agent**, one **tower** per workspace opens on demand, and `boss_broadcast` reaches the rest. No tracking, no scheduler, no new service: the extension is glue over pi-intercom and Herdr metadata.
+
+## Requirements
+
+- pi, running inside a Herdr pane
+- [pi-intercom](https://www.npmjs.com/package/pi-intercom) 0.17.1 or newer
+- Herdr 0.9.4 or newer
+
+Outside Herdr the extension does nothing.
+
+## Install
+
+```bash
+pi install npm:pi-straw-boss
+```
+
+While developing: `pi install ~/projects/pi-straw-boss` loads the working tree, and `/reload` picks up edits.
+
+## How it works
+
+Joining is a choice, never forced.
+
+1. A session that is not in the net gets one short reminder at the start of its first task, asking whether its current work competes with other work in the workspace for resources (ports, databases, files, branches) or needs to collaborate with it.
+2. If yes, it calls `boss_join` (or the human types `/boss`). It can also join later, whenever it discovers the need. The reminder is not repeated, and a session that never joins is left alone: no prompt, no listing, no broadcasts (except scope `all`).
+3. The first session of a tab to join is the tab's **main agent**; later joiners are **members**. `/boss` in a member takes the role over.
+4. Subagents launched by pi-herdr-agents (recognised by `PI_SUBAGENT_ID`) never join. Their parent represents them.
+
+| Role | Who | Gets |
+|---|---|---|
+| main agent | first joiner of a tab, or the `/boss` taker-over | a short prompt: split work by app, brief workers, check results, ask the boss before merging or deploying |
+| member | later joiners of a tab | a short prompt naming the main agent and the tower |
+| tower | one per workspace, in its own tab labelled `tower` | a prompt for coordinating agents and repairing coordination friction; it never asks the user |
+
+The tower is opened on demand by `call_tower` (or `/boss tower`), without taking focus, and answers through intercom. If two towers ever race in one workspace, the live token holder wins, otherwise the lower tab id, and the other closes its own tab. Towers of different workspaces reach each other with `call_tower`; the **head tower** is the tower of the first workspace in `herdr workspace list` order, so there is no election.
+
+## Tools
+
+| Tool | Available to | What it does |
+|---|---|---|
+| `boss_join` | sessions not yet in the net | Join this tab's net; the first joiner is main. |
+| `boss_status` | joined sessions and towers | The main agent of each tab, this workspace's tower, the head tower, and the other towers. |
+| `call_tower` | joined sessions and towers | Send a message to this workspace's tower, or another workspace's by id or exact label. Opens the tower tab when none runs. |
+| `boss_broadcast` | joined sessions and towers | 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 the machine, joined or not (for notices such as going to sleep). Default `workspace`. |
+
+| Command | Effect |
+|---|---|
+| `/boss` | Join if needed, then become this tab's main agent. |
+| `/boss status` | Show `boss_status`. |
+| `/boss tower` | Open this workspace's tower if none runs, then focus its tab. |
+
+## What it writes
+
+- Herdr pane token `sb_role` (`main`, `member` or `tower`) and workspace token `tower` (the tower's intercom session id), both refreshed every 4 minutes with a 10 minute TTL and cleared at shutdown.
+- A pi session entry `straw-boss` (`asked`, `joined`, `tower`) so a resumed session keeps its place without a second reminder.
+- One intercom extension channel per tab, `straw-boss/tab/<hex of the tab id>`, registered only by joined sessions and towers. Tab ids over 24 characters are refused.
+
+The tower tab is labelled `tower` and its Herdr agent is named `tower-<workspace id>` in lowercase (Herdr agent names are unique per server).
+
+## From Claude Code or Codex
+
+Read-only discovery works from any shell in a Herdr pane:
+
+```bash
+herdr workspace get "$HERDR_WORKSPACE_ID" | jq -r '.result.workspace.tokens.tower'
+herdr pane list --workspace "$HERDR_WORKSPACE_ID" | jq -r '.result.panes[] | select(.tokens.sb_role) | [.pane_id, .tokens.sb_role] | @tsv'
+node ~/.pi/agent/npm/node_modules/pi-intercom/cli.mjs ask --to "$TOWER_SESSION_ID" --text "<message>"
+```
+
+Opening a missing tower needs a pi session.
+
+## Development
+
+```bash
+npm install
+npm run check   # tsc --noEmit
+npm test        # node --test, against a fake Herdr and a fake intercom broker
+```
+
+Prompts are plain markdown in `prompts/`, read at session start, so an edit applies after `/reload`.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "pi-straw-boss",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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, 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": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "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/herdr.ts

@@ -0,0 +1,110 @@
+import { execFile } from "node:child_process";
+
+export type HerdrRun = (args: string[], timeoutMs?: number) => Promise<string>;
+export type Sleep = (ms: number) => Promise<void>;
+export interface Place { paneId: string; tabId: string; workspaceId: string }
+export interface Workspace { workspace_id: string; label: string; tokens?: Record<string, string>; worktree?: { checkout_path?: string } }
+export interface Pane { pane_id: string; tab_id: string; agent?: string; tokens?: Record<string, string> }
+export interface TowerEnv { run: HerdrRun; sleep: Sleep; live(sessionId: string): Promise<boolean> }
+
+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 };
+}
+
+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;
+}
+
+/** 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 }: 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.
+	let paneId: string;
+	let running = false;
+	const tab = (await result(run, ["tab", "list", "--workspace", ws])).tabs.find((t: { label: string }) => t.label === "tower");
+	if (tab) {
+		const root = (await panes(run, ws)).find((p) => p.tab_id === tab.tab_id);
+		if (!root) throw new Error(`Tower tab ${tab.tab_id} has no pane`);
+		paneId = root.pane_id;
+		running = root.agent === "pi";
+	} 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;
+	}
+	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,318 @@
+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 { ensureTower, herdrRun, type HerdrRun, type Pane, panes, place, type Place, report, 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 Location { status: string; workspace?: { id: string; label: string }; tab?: { id: string; label: string }; paneId?: string }
+interface Session { id: string; name?: string; herdrLocation?: Location }
+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; 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, 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;
+		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();
+		};
+		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;
+			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));
+			const [target] = found;
+			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(", ")}`);
+			}
+			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);
+			return { target, ...(await ensureTower({ run, sleep, live }, 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 === all[0] };
+			};
+			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: all[0]?.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 text = `Sent to the tower of ${tower.target.label}${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: all[0]?.label ?? "" };
+			addNetTools();
+			keepFresh();
+			await publish();
+		};
+
+		pi.on("session_start", (_event, ctx) => {
+			ui = ctx.ui;
+			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 {
+				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;
+			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 () => {
+			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();