npm - pi-straw-boss - Versions diffs - 0.1.0 → 0.3.1 - Mend

pi-straw-boss 0.1.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md +34 -62
package/dist/gui/assets/index-BP87OlaT.css +1 -0
package/dist/gui/assets/index-CH3266oL.js +1 -0
package/dist/gui/index.html +59 -0
package/package.json +12 -4
package/src/dashboard.ts +181 -0
package/src/gui.ts +170 -0
package/src/herdr.ts +44 -10
package/src/index.ts +95 -23
package/src/net.ts +56 -0

package/README.md CHANGED Viewed

@@ -1,14 +1,23 @@
 # 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.
-## Requirements
+![The straw net in the browser: three workspaces with their towers, agents, a subagent, and an outpost, with live states](docs/straw-net-gui.png)
-- 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
+<p align="center"><sub><code>/boss gui</code>: every workspace of the net, live, in your browser. <a href="docs/straw-net-gui.gif">Watch it move</a>.</sub></p>
-Outside Herdr the extension does nothing.
+![The tower's dashboard in the terminal: this net's tabs, agents, and subagents, and the other towers](docs/tower-dashboard.png)
+## 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.
+- **A browser view** of the whole net, `/boss gui`: every workspace as a base with its tower, agents, and subagents, animated and read-only.
+- **Broadcast** to a tab, a workspace, every tower, or every session.
 ## Install
@@ -16,70 +25,33 @@ 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.
+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.
-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.
+## Quick start
-| 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 |
+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.
+4. Type `/boss gui` from any session to see the whole net in your browser.
-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 and commands
-## 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 |
+| 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.
+| `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. |
+| `/boss gui`, `/boss gui stop` | Open the net in the browser (any session, joins nothing); stop its server. |
-The tower tab is labelled `tower` and its Herdr agent is named `tower-<workspace id>` in lowercase (Herdr agent names are unique per server).
+Subagents and sessions in Herdr worktree workspaces never join: the session that launched them speaks for them. Outside Herdr the extension does nothing.
-## 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
-```
+## 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, the browser view, what the extension writes, and how Claude Code or Codex agents can find a tower.
 ## License
-MIT
+MIT. The browser view's icons come from [game-icons.net](https://game-icons.net) (Lorc and Delapouite, [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)); see [gui/ICONS.md](gui/ICONS.md).

package/dist/gui/assets/index-BP87OlaT.css ADDED Viewed

@@ -0,0 +1 @@

+ :root{--bg:#060a14;--panel:#0e1628e0;--line:#7a98e033;--text:#dbe6ff;--dim:#8b99ba;--gold:#ffd166;--mono:ui-monospace, "SF Mono", Menlo, Consolas, monospace;--sans:ui-rounded, "Avenir Next", "Trebuchet MS", system-ui, -apple-system, "Segoe UI", sans-serif}*{box-sizing:border-box;margin:0}html{--lightningcss-light: ;--lightningcss-dark:initial;color-scheme:dark}body{min-height:100vh;color:var(--text);font:14px/1.4 var(--sans);background:radial-gradient(1100px 640px at 12% -10%, #38e0ff1c, transparent 62%), radial-gradient(900px 600px at 98% 8%, #966eff1c, transparent 60%), linear-gradient(var(--bg), #0a1020);background-attachment:fixed}svg{display:block}[data-mark=working]{--c:#38e0ff}[data-mark=waiting]{--c:#ffb02e}[data-mark=idle]{--c:#7184ad}[data-mark=done]{--c:#3ddc97}[data-mark=error]{--c:#ff5470}[data-mark=unknown]{--c:#4f5c7c}.shell{max-width:1480px;margin:0 auto;padding:18px 22px 40px}.hud{border:1px solid var(--line);background:var(--panel);-webkit-backdrop-filter:blur(10px);backdrop-filter:blur(10px);z-index:5;border-radius:18px;align-items:center;gap:24px;padding:12px 18px;display:flex;position:sticky;top:12px}.brand{align-items:center;gap:12px;margin-right:auto;display:flex}.logo{color:#38e0ff;border:1px solid var(--line);background:radial-gradient(circle at 30% 25%,#38e0ff4d,#0a1020e6);border-radius:14px;place-items:center;width:44px;height:44px;display:grid}.logo svg{filter:drop-shadow(0 0 6px #38e0ff);width:28px;height:28px}h1{letter-spacing:.14em;text-transform:uppercase;font-size:20px}.brand p{color:var(--dim);font-size:12px}.stats{gap:10px;display:flex}.stats div{background:#ffffff0a;border:1px solid #ffffff0f;border-radius:12px;min-width:78px;padding:6px 12px}.stats dt{color:var(--dim);letter-spacing:.08em;text-transform:uppercase;font-size:11px}.stats dd{font:600 20px/1.1 var(--mono)}.stats [data-mark] dd{color:var(--c)}.link{color:var(--dim);text-transform:uppercase;letter-spacing:.08em;align-items:center;gap:8px;font-size:12px;display:flex}.link i{background:#4f5c7c;border-radius:50%;width:9px;height:9px}.link[data-state=live] i{background:#3ddc97;animation:2.4s ease-in-out infinite blink}.link[data-state=live]{color:#3ddc97}.link[data-state=reconnecting] i,.link[data-state=connecting] i{background:#ffb02e;animation:1s ease-in-out infinite blink}.link[data-state=offline] i{background:#ff5470}.banner{color:#c9d6f5;background:#7184ad29;border-radius:14px;margin:14px 0 0;padding:10px 16px;font-size:13px}.banner[hidden]{display:none}.banner b{font-family:var(--mono);font-weight:600}.stage{grid-template-columns:minmax(0,1fr) 280px;align-items:start;gap:20px;margin-top:18px;transition:opacity .4s;display:grid}.stage[data-stale=true] .map,body[data-stale=true] .stats{opacity:.4}.stage[data-stale=true] *{animation-play-state:paused!important}.map{border:1px solid var(--line);background:linear-gradient(#82a0ff0d 1px,#0000 1px) 0 0/44px 44px,linear-gradient(90deg,#82a0ff0d 1px,#0000 1px) 0 0/44px 44px,#080d1a8c;border-radius:22px;min-height:420px;padding:26px;transition:opacity .4s;position:relative}.links{pointer-events:none;width:100%;height:100%;position:absolute;inset:0}.wire{fill:none;stroke:#38e0ff4d;stroke-width:1.5px;stroke-dasharray:3 7;stroke-linecap:round}.packet{fill:#38e0ff;opacity:.9}.bases{grid-template-columns:repeat(auto-fill,minmax(300px,1fr));align-items:start;gap:30px;display:grid;position:relative}.empty{color:var(--dim);text-align:center;padding:120px 0;position:relative}.base{border:1px solid var(--line);background:linear-gradient(#16213c,#0c1324);border-radius:18px;padding:16px;position:relative;box-shadow:0 18px 40px #00000059}.base.head{background:linear-gradient(#ffd1661a,#0000 38%),linear-gradient(#16213c,#0c1324)}.base[data-mark=waiting]{box-shadow:0 18px 40px #00000059,inset 0 0 0 999px #ffb02e0b}.base>header{align-items:center;gap:14px;margin-bottom:14px;display:flex}.title{justify-items:start;min-width:0;margin-right:auto;display:grid}.title h2{white-space:nowrap;text-overflow:ellipsis;max-width:100%;font-size:17px;overflow:hidden}.title p{max-width:100%;color:var(--dim);white-space:nowrap;text-overflow:ellipsis;font-size:12px;overflow:hidden}.crown{letter-spacing:.12em;text-transform:uppercase;color:var(--gold);background:#ffd1661f;border-radius:999px;align-items:center;gap:5px;margin-bottom:3px;padding:2px 9px 2px 6px;font-size:10px;display:inline-flex}.crown svg{width:14px;height:14px}.base:not(.head) .crown{display:none}.tower{width:80px;height:80px;color:var(--c);flex:none;place-items:center;display:grid;position:relative}.tower:before{content:"";background:radial-gradient(circle at 35% 30%, color-mix(in srgb, var(--c) 24%, #101a2e), #0b1222 70%);border:1px solid color-mix(in srgb, var(--c) 45%, transparent);border-radius:50%;position:absolute;inset:0}.tower svg{width:48px;height:48px;filter:drop-shadow(0 0 6px color-mix(in srgb, var(--c) 70%, transparent));position:relative}.tower.ghost{opacity:.45}.tower.ghost:before{border-style:dashed}.sweep,.pulse{opacity:0;pointer-events:none;border-radius:50%;position:absolute;inset:0}.sweep{background:conic-gradient(from 0deg, transparent 0 70%, color-mix(in srgb, var(--c) 55%, transparent) 100%)}.pulse{border:2px solid var(--c)}.tower[data-mark=working] .sweep{opacity:1;animation:3.2s linear infinite spin}.tower[data-mark=waiting] .pulse{animation:1.5s ease-out infinite ping}.tower>.badge{position:absolute;bottom:-2px;right:-2px}.tabs{gap:12px;display:grid}.tab{background:#ffffff06;border:1px solid #ffffff0d;border-radius:14px;padding:10px}.tab h3{color:var(--dim);letter-spacing:.12em;text-transform:uppercase;margin-bottom:8px;font-size:11px;font-weight:600}.units,.subs{gap:8px;display:grid}.outposts{gap:8px;margin-top:12px;display:grid}.outposts:empty{display:none}.outposts:before{content:"Outposts";color:var(--dim);letter-spacing:.12em;text-transform:uppercase;font-size:11px}.card{background:#ffffff09;border:1px solid #ffffff0f;border-radius:12px;align-items:center;gap:10px;padding:8px 10px;transition:background-color .4s;display:flex}.unit[data-mark=waiting]>.card{background:#ffb02e1c}.unit[data-mark=error]>.card{background:#ff54701c}.unit[data-mark=working]>.card{background:#38e0ff12}.plate{width:40px;height:40px;color:var(--c);background:radial-gradient(circle at 35% 30%, color-mix(in srgb, var(--c) 26%, #101a2e), #0b1222 72%);border-radius:50%;flex:none;place-items:center;transition:color .4s;display:grid;position:relative}.plate svg{width:22px;height:22px}.ring,.plate:after{pointer-events:none;border-radius:50%;position:absolute;inset:-3px}.ring{opacity:0;background:conic-gradient(from 0deg, transparent 0 55%, var(--c));-webkit-mask:radial-gradient(farthest-side,#0000 calc(100% - 3px),#000 calc(100% - 2px));mask:radial-gradient(farthest-side,#0000 calc(100% - 3px),#000 calc(100% - 2px))}.plate[data-mark=working]>.ring{opacity:1;animation:1.1s linear infinite spin}.plate:after{content:"";border:2px solid var(--c);opacity:0}.plate[data-mark=waiting]:after{animation:1.5s ease-out infinite ping}.badge{width:16px;height:16px;font:700 10px/1 var(--mono);color:#06101e;background:var(--c);border-radius:50%;place-items:center;transition:background-color .4s;display:grid}.plate>.badge{position:absolute;bottom:-4px;right:-4px}[data-mark=waiting]>.badge:after{content:"?"}[data-mark=idle]>.badge:after{content:"z"}[data-mark=done]>.badge:after{content:"✓"}[data-mark=error]>.badge:after{content:"!"}[data-mark=unknown]>.badge:after{content:"·"}[data-mark=working]>.badge:after{content:"";border:2px solid #06101e;border-right-color:#0000;border-radius:50%;width:8px;height:8px;animation:.8s linear infinite spin}[data-mark=waiting]>.badge{animation:1.2s ease-in-out infinite hop}.meta{min-width:0;display:grid}.name{white-space:nowrap;text-overflow:ellipsis;font-weight:600;overflow:hidden}.line{color:var(--dim);align-items:baseline;gap:8px;min-width:0;font-size:12px;display:flex}.role{letter-spacing:.1em;text-transform:uppercase;color:color-mix(in srgb, var(--c) 70%, var(--dim));font-size:10px;font-style:normal}.note{white-space:nowrap;text-overflow:ellipsis;overflow:hidden}.unit[data-mark=idle]>.card{opacity:.85}.subs{margin:6px 0 0 22px;padding-left:18px;position:relative}.subs:empty{display:none}.subs:before{content:"";background:repeating-linear-gradient(#7a98e080 0 4px,#0000 4px 8px);width:1px;position:absolute;top:-4px;bottom:22px;left:3px}.subs>.unit>.card:before{content:"";background:repeating-linear-gradient(90deg,#7a98e080 0 4px,#0000 4px 8px);width:15px;height:1px;position:absolute;top:50%;left:-15px}.subs>.unit{position:relative}.subs .plate{width:30px;height:30px}.subs .plate svg{width:17px;height:17px}.subs .name{font-size:13px}.side{gap:16px;display:grid;position:sticky;top:96px}.panel{border:1px solid var(--line);background:var(--panel);border-radius:18px;padding:14px 16px}.panel h2{color:var(--dim);letter-spacing:.14em;text-transform:uppercase;margin-bottom:10px;font-size:11px}.log{gap:7px;max-height:360px;padding:0;list-style:none;display:grid;overflow:hidden}.log:empty:before{content:"Waiting for changes…";color:var(--dim);font-size:12px}.log li{grid-template-columns:auto 1fr;gap:2px 8px;font-size:12px;animation:.4s ease-out both slide;display:grid}.log li:before{content:"";background:var(--c);border-radius:50%;width:8px;height:8px;margin-top:5px}.log time{font:11px var(--mono);color:var(--dim);grid-column:2}.credit{color:var(--dim);padding:0 6px;font-size:11px}.legend{gap:8px;padding:0;font-size:12px;list-style:none;display:grid}.legend li{align-items:center;gap:9px;display:flex}.enter{animation:.5s cubic-bezier(.2,.9,.3,1.15) both pop}.leaving{pointer-events:none;animation:.35s ease-in both out}.flash>.card>.plate,.flash.tower{animation:.6s ease-out flash}@keyframes spin{to{transform:rotate(360deg)}}@keyframes ping{0%{opacity:.6;transform:scale(1)}to{opacity:0;transform:scale(1.7)}}@keyframes hop{50%{transform:translateY(-3px)}}@keyframes blink{50%{opacity:.35}}@keyframes pop{0%{opacity:0;transform:scale(.92)translateY(8px)}}@keyframes out{to{opacity:0;transform:scale(.94)}}@keyframes flash{40%{transform:scale(1.12)}}@keyframes slide{0%{opacity:0;transform:translate(10px)}}html.paused *,html.paused :before,html.paused :after{animation-play-state:paused!important}@media (width<=1100px){.stage{grid-template-columns:1fr}.side{position:static}.stats{display:none}}@media (prefers-reduced-motion:reduce){*,:before,:after{transition:none!important;animation:none!important}}

package/dist/gui/assets/index-CH3266oL.js ADDED Viewed

@@ -0,0 +1 @@

package/dist/gui/index.html ADDED Viewed

@@ -0,0 +1,59 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="no-referrer">
+<title>Straw Net</title>
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='8' fill='%230b1220'/%3E%3Cpath d='M16 5l9 7h-4v13h-10V12H7z' fill='%2338e0ff'/%3E%3C/svg%3E">
+  <script type="module" crossorigin src="./assets/index-CH3266oL.js"></script>
+  <link rel="stylesheet" crossorigin href="./assets/index-BP87OlaT.css">
+</head>
+<body>
+<!-- Icons: game-icons.net, CC BY 3.0 (Lorc, Delapouite); see gui/ICONS.md -->
+<svg width="0" height="0" style="position:absolute" aria-hidden="true"><defs>
+<symbol id="i-tower" viewBox="0 0 512 512" fill="currentColor"><path d="M352 21v18h39v16h18V39h39V21h-96zm35 52l-40 30h106l-40-30h-26zM69.48 120.5l-8.96 15.6 110.98 63.7 35.6 20.4 33.6-58.7-77 13.1-94.22-54.1zM329 121v30h30v-30h-30zm48 0v30h46v-30h-46zm64 0v30h30v-30h-30zm-103 48l34.5 46h55l34.5-46H338zm39 64v30h46v-30h-46zm0 48v206h46V281h-46zM68.52 329L34.3 375H359v-46H68.52zM25 393v94h30v-64h66v64h238v-94H25zm416 .5V487h46v-65.9l-46-27.6zM160 439h48v18h-48v-18zm96 0h48v18h-48v-18zm-183 2v46h30v-46H73z"/></symbol>
+<symbol id="i-crown" viewBox="0 0 512 512" fill="currentColor"><path d="M408.256 119.46l-37.7 52.165 19.57 44.426 34.8-37.214-16.67-59.375zm86.074 12.513L384.44 249.498 334.01 135.02l-75.162 132.947-86.948-131.78-33.334 114.122L17.922 132.83l39.3 127.6c1.945-.348 3.94-.54 5.98-.54 18.812 0 34.26 15.452 34.26 34.262 0 13.823-8.346 25.822-20.235 31.22l5.337 17.33c12.425 25.466 71.863 45.152 176.582 47.206 110.805 2.174 178.12-17.54 189.854-47.207h-.002l4.357-20.26c-16.836-2.114-30.02-16.612-30.02-33.986 0-18.81 15.45-34.262 34.263-34.262 3.513 0 6.91.54 10.11 1.54l26.622-123.762zm-391.77 2.04l1.22 56.337 25.56 24.89 9.592-32.842-36.37-48.386zm150.585 2.91l-24.483 51.36 28.955 43.885 24.922-44.08-29.395-51.166zm204.453 135.962c-8.712 0-15.575 6.862-15.575 15.572 0 8.71 6.863 15.574 15.575 15.574s15.572-6.863 15.572-15.573-6.86-15.572-15.572-15.572zM63.2 278.58c-8.71 0-15.573 6.864-15.573 15.574s6.862 15.573 15.574 15.573c8.713 0 15.573-6.862 15.573-15.573 0-8.71-6.86-15.574-15.572-15.574zm130.33 17.842c18.812 0 34.26 15.45 34.26 34.262 0 18.81-15.448 34.26-34.26 34.26-18.813 0-34.262-15.45-34.262-34.26s15.45-34.262 34.26-34.262zm131.234 0c18.812 0 34.26 15.45 34.26 34.262 0 18.81-15.448 34.26-34.26 34.26-18.813 0-34.262-15.45-34.262-34.26s15.45-34.262 34.262-34.262zm-131.235 18.69c-8.713 0-15.573 6.86-15.573 15.572 0 8.71 6.86 15.574 15.572 15.574 8.71 0 15.572-6.864 15.572-15.574s-6.86-15.573-15.573-15.573zm131.234 0c-8.712 0-15.573 6.86-15.573 15.572 0 8.71 6.862 15.574 15.574 15.574s15.574-6.864 15.574-15.574-6.862-15.573-15.574-15.573z"/></symbol>
+<symbol id="i-main" viewBox="0 0 512 512" fill="currentColor"><path d="M256 19c-13.8 0-27.9 3.02-41.5 8.48L256 79.44l41.5-51.96C283.9 22.02 269.8 19 256 19zm-59.4 16.96c-18.5 10.27-35.9 24.69-50.9 41.74-10.8 12.21-20.2 25.7-24.8 32.4l-64.8 87.1 59.1 83L95.9 348l71.6 64.2-6.9-27.3 36.1-108.2-40.7 27.1-75.98-106.3 42.28-56.3 97.4 48.7h72.7l97.4-48.7 42.3 56.3-76 106.3-40.8-27.2 1 3.2 35.2 105.1-6.9 27.3 71.5-64.2-19.4-67.8 59.2-83-64.8-87.1c-4.6-6.7-14-20.19-24.8-32.4-15-17.05-32.4-31.47-50.9-41.74L256 110.2zm15.1 256.44l-5 15h98.6l-5-15zm-11.5 34.2l-16.3 49.1h144.2l-16.4-49.1zm-17.3 68.3l12.3 49.2h121.6l12.2-49.2zm33.6 68.4L256 493l39.5-29.7z"/></symbol>
+<symbol id="i-member" viewBox="0 0 512 512" fill="currentColor"><path d="M255.875 19.47c-33.142 0-59.844 26.822-59.844 60.186 0 33.364 26.703 60.156 59.845 60.156 33.142 0 59.875-26.792 59.875-60.156S289.017 19.47 255.875 19.47zm-50.688 120.343c-2.908 1.23-5.658 2.53-8.187 3.937-14.467 8.046-21.47 17.86-21.47 27.094 0 9.234 7.003 19.08 21.47 27.125 14.467 8.044 35.51 13.436 58.875 13.436 23.365 0 44.408-5.392 58.875-13.437 14.467-8.047 21.47-17.892 21.47-27.126 0-9.234-7.003-19.048-21.47-27.094-2.53-1.406-5.28-2.708-8.188-3.938-13.696 11.647-31.392 18.688-50.687 18.688-19.3 0-36.996-7.034-50.688-18.688zm78.875 87.906c-8.948 1.54-18.394 2.374-28.187 2.374-9.315 0-18.316-.758-26.875-2.156 2.69 6.923 4.36 14.186 4.906 21.656 2.456 33.554-17.04 69.573-58.47 93.594l-.155.093-.155.095c-20.062 10.653-30.28 24.056-30.28 36.97 0 12.9 10.28 26.46 30.343 37.217 20.062 10.76 48.86 17.844 80.75 17.844s60.687-7.085 80.75-17.844c20.062-10.758 30.343-24.318 30.343-37.218 0-13.127-10.773-26.656-31.655-37.406l-.22-.125-.186-.094c-40.344-23.394-58.705-59.676-55.908-93.22.626-7.497 2.31-14.813 5-21.78zM128.845 395.655c-5.592 3.72-10.256 7.61-13.875 11.53-6.9 7.48-9.94 14.64-9.94 21.845 0 7.206 3.04 14.397 9.94 21.876 6.898 7.48 17.6 14.852 31.28 21.125 27.36 12.547 66.42 20.69 109.625 20.69 43.206 0 82.295-8.143 109.656-20.69 13.682-6.27 24.352-13.644 31.25-21.124 6.9-7.48 9.97-14.67 9.97-21.875 0-7.204-3.07-14.363-9.97-21.842-3.597-3.902-8.238-7.767-13.78-11.47-5.638 15.6-19.584 28.706-37.5 38.313-23.533 12.62-54.947 20.095-89.563 20.095-34.615 0-66.06-7.474-89.593-20.094-17.94-9.62-31.887-22.747-37.5-38.374z"/></symbol>
+<symbol id="i-subagent" viewBox="0 0 512 512" fill="currentColor"><path d="M407 24.98v14.04h16V25zM88.99 25v14.03H105V25zM487 57H344.9v15.96H487zm-320 0H25v15.98h142zm256 33.93h-16.1v27.97l13.7.1h2.4zm-318 .1H88.97v28.07H105zm272 45.87l-.1 32.1h-78.5l-16-32h-52.8l-16 32.1-78.6-.1v-32H55.03l-12.04 48L199 214.4V208c.1-31.4 25.7-56.9 57.1-57 31.3 0 57 25.6 56.9 57 0 4.1.1 6.4.1 6.4L469 185.1 457 137zM256.1 169c-21.6 0-39 17.4-39.1 39.1.1 21.5 17.5 38.9 39.1 38.9s39-17.4 38.9-39c.1-21.5-17.3-39-38.9-39zm-.2 14c13.8 0 25 11.3 25.1 25 0 13.7-11.3 25.1-25 25-13.7 0-25.1-11.3-25-24.9 0-13.8 11.3-25 24.9-25.1zm-54.7 40.5L215 279h82l13.9-55.4c-6.8 23.9-28.8 41.4-54.8 41.4-26.1 0-48.1-17.6-54.9-41.5zm-35.8 4.2L60.35 321.1l83.85 107.7c5-5 11.3-8.8 18.2-11.1L100.2 318l87.9-73-3.4-13.4zm181.3.2l-19.4 3.8-3.3 13.4 87.8 73-62.2 99.6c7 2.3 13.2 6.2 18.3 11.3l83.8-107.8zM176 433.6c-15 0-26.9 11.9-26.9 26.7 0 14.9 11.9 26.7 27 26.8 14.9-.1 26.9-12 26.9-26.8-.1-14.8-11.9-26.7-27-26.7zm159.9 0c-14.9.1-27 11.9-26.9 26.8 0 14.7 11.9 26.6 27 26.6 15 0 27-11.8 26.9-26.7.1-14.8-11.9-26.7-27-26.7z"/></symbol>
+<symbol id="i-outpost" viewBox="0 0 512 512" fill="currentColor"><path d="M361.155 91.245l-18 .193.42 38.98c-45.773 13.285-108.533 19.738-166.474 23.573 35.097 96.284 99.357 173.77 157.845 257.13 20.718-19.655 51.11-31.983 83.46-36.01-20.8-18.109-36.634-27.966-58.833-70.438 31.27 37.085 52.579 48.467 77.623 62.006 3.263-13.094 8.938-24.638 18.721-32.674 8.667-7.12 20.026-10.654 33.53-10.344-46.874-59.763-101.67-117.054-127.83-189.435l-.462-42.98zM163.25 102.92l-17.998.244s.25 18.34.56 36.97c.156 9.316.325 18.703.489 25.929.06 2.636.117 4.58.174 6.542-34.378 83.733-69.154 160.993-123.92 233.442 33.635-1.387 66.326-1.203 98.552-.041 22.263-62.617 23.346-134.855 35.627-202.006 11.417 68.562 10.566 139.445 33.483 205.83 42.962 3.082 85.69 7.198 129.35 10.926-55.67-79.151-118.213-155.037-155.118-249.365-.05-1.782-.1-3.396-.152-5.737-.162-7.156-.333-16.523-.488-25.82-.31-18.594-.559-36.914-.559-36.914z"/></symbol>
+</defs></svg>
+<div class="shell">
+  <header class="hud">
+    <div class="brand">
+      <span class="logo"><svg><use href="#i-tower"/></svg></span>
+      <div><h1>Straw Net</h1><p>read-only live view</p></div>
+    </div>
+    <dl class="stats" aria-label="Net totals">
+      <div><dt>Bases</dt><dd id="s-bases">0</dd></div>
+      <div><dt>Agents</dt><dd id="s-agents">0</dd></div>
+      <div data-mark="working"><dt>Working</dt><dd id="s-working">0</dd></div>
+      <div data-mark="waiting"><dt>Waiting</dt><dd id="s-waiting">0</dd></div>
+    </dl>
+    <div class="link" id="link" data-state="connecting"><i></i><span id="link-text">connecting</span></div>
+  </header>
+  <div class="banner" id="banner" role="status" hidden></div>
+  <div class="stage" id="stage">
+    <main class="map" id="map">
+      <svg class="links" id="links" aria-hidden="true"></svg>
+      <div class="bases" id="bases"></div>
+      <p class="empty" id="empty" hidden>No workspaces yet. Open a pi session in Herdr and the net appears here.</p>
+    </main>
+    <aside class="side">
+      <section class="panel"><h2>Net log</h2><ol class="log" id="log"></ol></section>
+      <section class="panel"><h2>States</h2>
+        <ul class="legend">
+          <li data-mark="working"><b class="badge"></b>working</li>
+          <li data-mark="waiting"><b class="badge"></b>waiting on a question</li>
+          <li data-mark="idle"><b class="badge"></b>idle</li>
+          <li data-mark="done"><b class="badge"></b>finished</li>
+          <li data-mark="error"><b class="badge"></b>error</li>
+        </ul>
+      </section>
+      <p class="credit">Icons from game-icons.net by Lorc and Delapouite, CC BY 3.0.</p>
+    </aside>
+  </div>
+</div>
+</body>
+</html>

package/package.json CHANGED Viewed

@@ -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.3.1",
+  "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",
@@ -21,6 +21,7 @@
   ],
   "files": [
     "src",
+    "dist/gui",
     "prompts",
     "README.md",
     "LICENSE"
@@ -31,17 +32,24 @@
     ]
   },
   "scripts": {
-    "check": "tsc --noEmit",
+    "check": "tsc --noEmit && tsc --noEmit -p gui",
+    "gui:build": "vite build gui",
+    "gui:dev": "vite gui",
+    "prepack": "npm run gui:build",
+    "pretest": "npm run gui:build",
     "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"
+    "typescript": "7.0.2",
+    "vite": "8.3.4"
   }
 }

package/src/dashboard.ts ADDED Viewed

@@ -0,0 +1,181 @@
+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;
+export const markOf = (status?: string): Mark => HERDR_MARK[status ?? ""] ?? "unknown";
+/** A session is waiting when its pane is blocked on a question, else working or idle by its intercom status, else by Herdr's own. */
+export function sessionMark(s: Session, pane?: Pane): Mark {
+	const busy = s.status ? s.status !== "idle" : undefined;
+	return pane?.agent_status === "blocked" ? "waiting" : busy === undefined ? markOf(pane?.agent_status) : busy ? "working" : "idle";
+}
+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. */
+export 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 mark = sessionMark(s, ps.find((p) => p.pane_id === s.herdrLocation?.paneId));
+		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/gui.ts ADDED Viewed

@@ -0,0 +1,170 @@
+import { execFile } from "node:child_process";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createReadStream, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createServer, type IncomingMessage, request, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { extname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Net } from "./net.ts";
+// The browser view's server: serves the built page and one live stream of the net, read-only, on 127.0.0.1 only.
+// Every URL starts with a random token (/<token>/index.html, /<token>/events) and a request without it, or with another Host
+// header, is refused, so other local pages cannot read the net. The stream sends the full snapshot on connect and on every
+// change, plus a `ping` event every 15 s so a client can tell a silent drop from a quiet net. It polls only while someone listens.
+export const BUNDLE = fileURLToPath(new URL("../dist/gui", import.meta.url));
+const TYPES: Record<string, string> = { ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".css": "text/css; charset=utf-8", ".svg": "image/svg+xml", ".json": "application/json" };
+const HEADERS = {
+	"cache-control": "no-store",
+	"referrer-policy": "no-referrer",
+	"x-content-type-options": "nosniff",
+	"content-security-policy": "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'",
+};
+export interface Gui { url: string; port: number; token: string; stop(): Promise<void> }
+export interface GuiOptions { read(): Promise<Net>; dir?: string; port?: number; token?: string; pollMs?: number; pingMs?: number }
+/** Starts the server. A preferred `port` (and `token`) is reused when free, so a restarted server keeps the URL an open page already has. */
+export async function startGui({ read, dir = BUNDLE, port = 0, token = randomBytes(16).toString("hex"), pollMs = 2000, pingMs = 15_000 }: GuiOptions): Promise<Gui> {
+	try {
+		if (!statSync(join(dir, "index.html")).isFile()) throw new Error();
+	} catch {
+		throw new Error(`The GUI bundle is missing (${dir}); build it with npm run gui:build`);
+	}
+	const clients = new Set<ServerResponse>();
+	let last: string | undefined, problem: string | undefined, busy = false;
+	let poll: ReturnType<typeof setInterval> | undefined, beat: ReturnType<typeof setInterval> | undefined;
+	const push = (data: string, event?: string) => clients.forEach((c) => c.write(`${event ? `event: ${event}\n` : ""}data: ${data}\n\n`));
+	const tick = async () => {
+		if (busy) return;
+		busy = true;
+		try {
+			const json = JSON.stringify(await read());
+			if (json !== last || problem) push((last = json));
+			problem = undefined;
+		} catch (error) {
+			// The stream stays up and says why the net is unreadable, once per distinct reason.
+			const message = (error as Error).message;
+			if (message !== problem) push(JSON.stringify(message), "problem");
+			problem = message;
+		}
+		busy = false;
+	};
+	const listen = (at: number) => new Promise<void>((done, fail) => {
+		server.once("error", fail);
+		server.listen(at, "127.0.0.1", () => (server.off("error", fail), done()));
+	});
+	const allowed = (req: IncomingMessage, given: string | undefined) => {
+		const [a, b] = [Buffer.from(given ?? ""), Buffer.from(token)];
+		return req.method === "GET" && req.headers.host === `127.0.0.1:${(server.address() as AddressInfo).port}` && a.length === b.length && timingSafeEqual(a, b);
+	};
+	const events = (req: IncomingMessage, res: ServerResponse) => {
+		res.writeHead(200, { ...HEADERS, "content-type": "text/event-stream", connection: "keep-alive" });
+		clients.add(res);
+		if (last) res.write(`data: ${last}\n\n`);
+		if (clients.size === 1) {
+			poll = setInterval(() => void tick(), pollMs).unref();
+			beat = setInterval(() => push("", "ping"), pingMs).unref();
+			void tick();
+		}
+		req.on("close", () => {
+			clients.delete(res);
+			if (!clients.size) (clearInterval(poll), clearInterval(beat));
+		});
+	};
+	const server = createServer((req, res) => {
+		const pathname = new URL(req.url ?? "/", "http://local").pathname;
+		const [, given, ...path] = pathname.split("/");
+		const fail = (code: number) => res.writeHead(code, { ...HEADERS, "content-type": "text/plain" }).end(code === 403 ? "forbidden" : "not found");
+		if (!allowed(req, given)) return void fail(403);
+		// The page loads its assets and the stream relative to its own URL, so that URL must end with a slash.
+		if (path.length === 0) return void res.writeHead(308, { ...HEADERS, location: `${pathname}/` }).end();
+		if (path.join("/") === "events") return events(req, res);
+		let file: string;
+		try {
+			file = resolve(dir, decodeURIComponent(path.join("/")) || "index.html");
+			if (!file.startsWith(resolve(dir) + sep) || !statSync(file).isFile()) throw new Error();
+		} catch {
+			return void fail(404);
+		}
+		res.writeHead(200, { ...HEADERS, "content-type": TYPES[extname(file)] ?? "application/octet-stream" });
+		createReadStream(file).pipe(res);
+	});
+	try {
+		await listen(port);
+	} catch (error) {
+		if (!port || (error as NodeJS.ErrnoException).code !== "EADDRINUSE") throw error;
+		await listen(0);
+	}
+	const bound = (server.address() as AddressInfo).port;
+	return {
+		url: `http://127.0.0.1:${bound}/${token}/`, port: bound, token,
+		stop: () => new Promise<void>((done) => {
+			clearInterval(poll);
+			clearInterval(beat);
+			clients.forEach((c) => c.end());
+			server.close(() => done());
+			server.closeAllConnections();
+		}),
+	};
+}
+// One server per machine. gui.json in the state directory records the running server (pid, port, token, owner session), and
+// gui.lock makes the check-and-start atomic, so a second /boss gui, from this session or another, opens the running server
+// instead of starting one. A dead server's port and token are reused, so a page left open reconnects to its successor.
+export interface GuiRecord { pid: number; port: number; token: string; owner: string }
+export interface Shared { url: string; owner: string; mine?: Gui }
+const urlOf = (r: GuiRecord) => `http://127.0.0.1:${r.port}/${r.token}/`;
+export function readRecord(dir: string): GuiRecord | undefined {
+	try {
+		return JSON.parse(readFileSync(join(dir, "gui.json"), "utf8")) as GuiRecord;
+	} catch {
+		return undefined;
+	}
+}
+/** Whether a recorded server answers its own page. */
+export const answers = (r: GuiRecord) =>
+	new Promise<boolean>((done) => {
+		const req = request({ host: "127.0.0.1", port: r.port, path: `/${r.token}/`, headers: { host: `127.0.0.1:${r.port}` }, agent: false, timeout: 1000 }, (res) => {
+			res.resume();
+			done(res.statusCode === 200);
+		});
+		req.on("error", () => done(false)).on("timeout", () => (req.destroy(), done(false)));
+		req.end();
+	});
+export async function sharedGui(dir: string, owner: string, start: (prefer: { port?: number; token?: string }) => Promise<Gui>, sleep: (ms: number) => Promise<void>): Promise<Shared> {
+	mkdirSync(dir, { recursive: true, mode: 0o700 });
+	const lock = join(dir, "gui.lock");
+	for (let tries = 0; ; tries++) {
+		try {
+			writeFileSync(lock, String(process.pid), { flag: "wx" });
+			break;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			// A lock older than 10 s was left by a session that died while starting the server.
+			const age = Date.now() - (statSync(lock, { throwIfNoEntry: false })?.mtimeMs ?? Date.now());
+			if (age > 10_000) rmSync(lock, { force: true });
+			else if (tries >= 50) throw new Error("Another session is starting the straw net GUI; try again");
+			else await sleep(200);
+		}
+	}
+	try {
+		const record = readRecord(dir);
+		if (record && (await answers(record))) return { url: urlOf(record), owner: record.owner };
+		const gui = await start(record ? { port: record.port, token: record.token } : {});
+		writeFileSync(join(dir, "gui.json"), JSON.stringify({ pid: process.pid, port: gui.port, token: gui.token, owner }), { mode: 0o600 });
+		return { url: gui.url, owner, mine: gui };
+	} finally {
+		rmSync(lock, { force: true });
+	}
+}
+/** Opens the default browser; rejects when the platform command fails, so the caller can show the URL instead. */
+export const openBrowser = (url: string) =>
+	new Promise<void>((done, fail) => {
+		const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+		execFile(cmd!, args as string[], (error) => (error ? fail(error) : done()));
+	});

package/src/herdr.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,9 +1,13 @@
 import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
 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 { answers, type Gui, openBrowser, readRecord, sharedGui, startGui } from "./gui.ts";
+import { collectNet } from "./net.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 +22,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 +33,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; bundle?: string; openUrl?: (url: string) => Promise<void>; stateDir?: 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,13 +45,17 @@ 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)), bundle, openUrl = openBrowser, stateDir }: 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 gui: Gui | undefined, viewer: Channel | undefined, opening: Promise<string> | undefined;
+		const guiDir = stateDir ?? join(env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"), "straw-boss");
 		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 ?? "";
@@ -93,6 +99,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;
@@ -118,12 +125,13 @@ export function createStrawBoss({ run = herdrRun, env = process.env, sleep = (ms
 		};
 		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 connected = async (channel = c) => {
+			if (await waitFor(sleep, () => channel.snapshot().connected && channel.snapshot().supported, CONNECT_MS)) return;
+			throw new Error(channel.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();
@@ -158,13 +166,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 +184,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 +196,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 +226,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 +256,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 +288,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 +307,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 +320,10 @@ export function createStrawBoss({ run = herdrRun, env = process.env, sleep = (ms
 		});
 		pi.on("session_shutdown", async () => {
+			await gui?.stop();
+			gui = undefined;
+			dashboard?.stop();
+			dashboard = undefined;
 			clearInterval(timer);
 			timer = undefined;
 			const held = holdsTower;
@@ -295,11 +333,45 @@ export function createStrawBoss({ run = herdrRun, env = process.env, sleep = (ms
 			if (held) await report(run, "workspace", at.workspaceId, { tower: null }).catch(() => {});
 		});
+		// /boss gui is a read-only viewer: any session may open it, and it joins nothing and writes no token. A session outside the net
+		// reads the sessions through a channel of its own that never takes part in a tab (no owner, no role).
+		const sessions = async () => {
+			if (!c && !viewer) {
+				const namespace = `straw-boss/view/${Buffer.from(env.HERDR_PANE_ID!).toString("hex")}`;
+				pi.events.emit(REGISTER, { namespace, ownerEligible: false, onReady: (channel: Channel) => (viewer = channel), onEvent: () => {} });
+				if (!viewer) throw new Error("pi-intercom is not loaded (Straw Boss needs pi-intercom >= 0.17.1)");
+				await connected(viewer);
+			}
+			return (c ?? viewer!).listSessions();
+		};
+		const guiCommand = async (stop: boolean) => {
+			if (stop) {
+				const running = gui;
+				gui = undefined;
+				if (running) return (await running.stop(), tell("Straw net GUI stopped"));
+				const record = readRecord(guiDir);
+				if (record && (await answers(record))) return tell(`The straw net GUI runs in session ${record.owner}; stop it there with /boss gui stop`);
+				return tell("The straw net GUI is not running");
+			}
+			// One server per machine: a second /boss gui, here or in another session, opens the one that runs. Two calls in flight
+			// in this session share one start.
+			opening ??= (async () => {
+				if (gui) return gui.url;
+				const shared = await sharedGui(guiDir, `${me() || "unknown"} (pane ${env.HERDR_PANE_ID})`, (prefer) => startGui({ read: () => collectNet({ run, sessions }), dir: bundle, ...prefer }), sleep);
+				gui = shared.mine;
+				return shared.url;
+			})().finally(() => (opening = undefined));
+			const url = await opening;
+			tell(`Straw net GUI: ${url}`);
+			await openUrl(url).catch((error: Error) => tell(`Could not open a browser (${error.message}); open the URL above yourself`, "warning"));
+		};
 		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.",
+			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; /boss gui opens the net in the browser (/boss gui stop closes it).",
 			handler: async (args, ctx) => {
 				ui = ctx.ui;
 				try {
+					if (/^gui( stop)?$/.test(args.trim())) return await guiCommand(args.trim() === "gui stop");
 					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());

package/src/net.ts ADDED Viewed

@@ -0,0 +1,56 @@
+import { type Mark, markOf, type Row, sessionMark, subagents } from "./dashboard.ts";
+import { headOf, type HerdrRun, isSub, type Pane, panes, parentOf, type Session, workspaces, type Workspace } from "./herdr.ts";
+// The whole straw net as one JSON-able snapshot for the browser view: every workspace as a base with its tower, tabs, agents,
+// and subagents (linked to their launcher the way the tower dashboard links them), and sub workspaces as outposts.
+export interface Unit { id: string; name: string; role: "main" | "member" | "subagent"; mark: Mark; note?: string; subs: Unit[] }
+export interface Tab { id: string; label: string; units: Unit[] }
+export interface Outpost { id: string; label: string; mark: Mark }
+export interface Base { id: string; label: string; mark: Mark; head: boolean; tower: { name: string; mark: Mark } | null; tabs: Tab[]; outposts: Outpost[] }
+export interface Net { bases: Base[] }
+export interface NetInput { sessions: Session[]; panes: Pane[]; workspaces: Workspace[]; children(pane: Pane | undefined): Row[] }
+const joinedRole = (token?: string): "main" | "member" | undefined => (token === "main" || token === "member" ? token : undefined);
+/**
+ * The pure half: sessions, panes, and workspaces in, the net out. Sessions that did not join (no main or member token) are left out,
+ * and so are workspaces with no part in the net (no live tower, nobody joined): a base is a workspace the net reaches.
+ */
+export function buildNet({ sessions, panes: ps, workspaces: all, children }: NetInput): Net {
+	const paneOf = (s: Session) => ps.find((p) => p.pane_id === s.herdrLocation?.paneId);
+	const note = (mark: Mark, status?: string) => ({ working: status, waiting: "waiting on a question" })[mark as "working"];
+	const joined = sessions.flatMap((s) => {
+		const pane = paneOf(s), role = joinedRole(pane?.tokens?.sb_role);
+		return role ? [{ s, pane, role, base: s.herdrLocation?.workspace?.id, tab: s.herdrLocation?.tab }] : [];
+	});
+	const rowsOf = new Map(joined.map(({ s, pane }) => [s.id, children(pane)]));
+	// A sub workspace that already shows as a launched subagent is not an outpost as well.
+	const claimed = new Set([...rowsOf.values()].flat().map((r) => r.workspace));
+	const bases = all.filter((w) => !isSub(w)).flatMap((w): Base[] => {
+		const mine = joined.filter((j) => j.base === w.workspace_id && j.tab);
+		const tabs = Object.values(Object.groupBy(mine, (j) => j.tab!.id)).map((group = []): Tab => ({
+			id: group[0]!.tab!.id,
+			label: group[0]!.tab!.label,
+			units: group.toSorted((a, b) => Number(b.role === "main") - Number(a.role === "main")).map(({ s, pane, role }): Unit => {
+				const mark = sessionMark(s, pane);
+				const subs = (rowsOf.get(s.id) ?? []).map((r): Unit => ({ id: `${s.id}/${r.text}`, name: r.text, role: "subagent", mark: r.mark, note: r.note, subs: [] }));
+				return { id: s.id, name: s.name ?? s.id, role, mark, note: note(mark, s.status), subs };
+			}),
+		}));
+		const outposts = all.filter((x) => isSub(x) && parentOf(all, x) === w && !claimed.has(x.workspace_id)).map((x): Outpost => ({ id: x.workspace_id, label: x.label, mark: markOf(x.agent_status) }));
+		const tower = sessions.find((s) => s.id === w.tokens?.tower);
+		const marks = [...tabs.flatMap((t) => t.units.flatMap((u) => [u.mark, ...u.subs.map((c) => c.mark)])), ...outposts.map((o) => o.mark)];
+		// A base shows what needs attention most: a waiting unit, then a working one, else the workspace's own status.
+		const mark = (["waiting", "working"] as const).find((m) => marks.includes(m)) ?? markOf(w.agent_status);
+		if (!tower && !tabs.length) return [];
+		return [{ id: w.workspace_id, label: w.label, mark, head: w === headOf(all), tower: tower ? { name: tower.name ?? tower.id, mark: sessionMark(tower, paneOf(tower)) } : null, tabs, outposts }];
+	});
+	return { bases };
+}
+/** One reading of Herdr and intercom as a net. */
+export async function collectNet({ run, sessions, now = Date.now() }: { run: HerdrRun; sessions(): Promise<Session[]>; now?: number }): Promise<Net> {
+	const [live, ps, all] = [await sessions(), await panes(run), await workspaces(run)];
+	return buildNet({ sessions: live, panes: ps, workspaces: all, children: (pane) => subagents(pane, ps, now) });
+}