pi-straw-boss 0.1.0 → 0.2.0

package/README.md

@@ -1,14 +1,32 @@
 # pi-straw-boss
 
-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.
+**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                                            │
+╰──────────────────────────────────────────────────────────────────────────╯
+```
 
-## Requirements
+## Why
 
-- 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
+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.
 
-Outside Herdr the extension does nothing.
+- **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
 
@@ -16,69 +34,30 @@ Outside Herdr the extension does nothing.
 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.
+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.
 
-| 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 |
+## Quick start
 
-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.
+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
+## Tools and commands
 
-| 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 |
+| Name | What it does |
 |---|---|
-| `/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).
+| `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. |
 
-## From Claude Code or Codex
+Subagents and sessions in Herdr worktree workspaces never join: the session that launched them speaks for them. Outside Herdr the extension does nothing.
 
-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
-```
+## Learn more
 
-Prompts are plain markdown in `prompts/`, read at session start, so an edit applies after `/reload`.
+[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
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-straw-boss",
-  "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",
+  "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",
@@ -36,10 +36,12 @@
   },
   "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/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

@@ -1,11 +1,19 @@
 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; 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> }
+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;
@@ -36,12 +44,34 @@ export async function place(run: HerdrRun): Promise<Place> {
 	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}`]));
@@ -67,7 +97,7 @@ export function ensureTower(env: TowerEnv, workspace: Workspace, cwd: string) {
 	return pending;
 }
 
-async function open({ run, sleep, live }: TowerEnv, workspace: Workspace, cwd: string) {
+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;
@@ -77,18 +107,22 @@ async function open({ run, sleep, live }: TowerEnv, workspace: Workspace, cwd: s
 	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 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";
+	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.

package/src/index.ts

@@ -3,7 +3,8 @@ 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";
+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";
@@ -18,8 +19,6 @@ 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;
@@ -31,7 +30,7 @@ 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 }
+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[]) {
@@ -43,12 +42,14 @@ function netMembers(sessions: Session[], ps: Pane[]) {
 }
 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 = {}) {
+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();
@@ -93,6 +94,7 @@ export function createStrawBoss({ run = herdrRun, env = process.env, sleep = (ms
 		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;
@@ -124,6 +126,7 @@ export function createStrawBoss({ run = herdrRun, env = process.env, sleep = (ms
 		};
 		const joinNet = async (restored = false) => {
 			if (joined) return;
+			if (barred) throw new Error(barred);
 			at = await place(run);
 			connect(true);
 			await connected();
@@ -158,13 +161,17 @@ export function createStrawBoss({ run = herdrRun, env = process.env, sleep = (ms
 		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(", ")}`);
 			}
+			// 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);
-			return { target, ...(await ensureTower({ run, sleep, live }, target, process.cwd())) };
+			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();
@@ -172,7 +179,7 @@ export function createStrawBoss({ run = herdrRun, env = process.env, sleep = (ms
 			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] };
+				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 = []) => ({
@@ -184,7 +191,7 @@ export function createStrawBoss({ run = herdrRun, env = process.env, sleep = (ms
 			return {
 				me: { id: me(), role: role() },
 				workspace: { id: at.workspaceId, label: mine?.label },
-				head: all[0]?.workspace_id,
+				head: headOf(all)?.workspace_id,
 				tower: towerOf(mine) ?? null,
 				tabs,
 				towers: all.filter((w) => w !== mine).flatMap((w) => towerOf(w) ?? []),
@@ -214,7 +221,8 @@ export function createStrawBoss({ run = herdrRun, env = process.env, sleep = (ms
 					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.`;
+					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).",
@@ -243,14 +251,29 @@ export function createStrawBoss({ run = herdrRun, env = process.env, sleep = (ms
 				return;
 			}
 			holdsTower = true;
-			info = { workspace: ws?.label ?? at.workspaceId, head: all[0]?.label ?? "" };
+			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 }) });
 		};
 
-		pi.on("session_start", (_event, ctx) => {
+		// 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);
@@ -260,12 +283,18 @@ export function createStrawBoss({ run = herdrRun, env = process.env, sleep = (ms
 			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);
+				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"));
 		});
@@ -273,7 +302,7 @@ export function createStrawBoss({ run = herdrRun, env = process.env, sleep = (ms
 		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;
+			const first = !current && !asked && !barred;
 			if (first) {
 				asked = true;
 				pi.appendEntry(ENTRY, { asked: true });
@@ -286,6 +315,8 @@ export function createStrawBoss({ run = herdrRun, env = process.env, sleep = (ms
 		});
 
 		pi.on("session_shutdown", async () => {
+			dashboard?.stop();
+			dashboard = undefined;
 			clearInterval(timer);
 			timer = undefined;
 			const held = holdsTower;