[hhff]

Spec: docs/superpowers/specs/2026-11-04-devteam-hub-design.md. Plan: docs/superpowers/plans/2026-11-04-devteam-hub.md.

What

• scripts/devteam.mjs, tmux: tmux_session defaults to null. The resolved name is devteam-<project>, saved to run/tmux-session when the kit first creates the session; read-only commands and CI write nothing. A project whose live sessions already sit in a devteam session keeps that name. Every tmux target matches the session exactly (=name), because tmux otherwise takes a prefix (devteam would find devteam-stacks). settings --get tmux_session and whoami print the resolved name.
• scripts/devteam.mjs, dashboard port: dashboard_port defaults to null. A checkout reuses the port it saved in run/dashboard-port. Otherwise it takes the one after the highest instance answering in 4321–4345, skipping ports held by anything else, and falls back to the lowest free one. A pinned port outside the block warns that the hub won't list it.
• scripts/devteam.mjs, hello and /api/hello: hello is a light fold (open questions, fleet mode, live sessions, and the kit version, with +local when the running kit differs from main's, by blob, offline). The dashboard refreshes it every 30 s, and /api/hello answers from the last run at once.
• scripts/devteam.mjs, startHub, and dashboard/hub.html: every dashboard tries to serve 127.0.0.1:4320. The one that gets it scans the block for /api/hello on each page load and lists what answers, each card linking to that instance's own origin. The others retry every 30 s, so the hub moves when its dashboard stops.
• Dashboard Host check: it now runs first, for every route. Before this, GET / and GET /api/data answered any Host, so a page that rebound its own name to 127.0.0.1 could read the whole dashboard. Owner actions were already guarded.
• README, supervisor.md: one session and port per project, the hub, and restart commands that name the project's own session.
• test/kit.test.mjs: tests for the per-project session (including the legacy case and a foreign devteam session), the ports (save and reuse, +1, held ports, pinned outside the block), hello with the Host guard, and the hub (list, +1, +local, CSP, own Host, GET only, failover). Every test dashboard uses test-owned ports (DEVTEAM_HUB_PORT, DEVTEAM_PORT_BASE), never the machine's.

Why

The owner wants to run several devteam projects on one machine and reach them all from one page. Two projects on one machine collided: they shared the devteam tmux session, so send <id> could type into the other project's worker and a restart could kill the other's dashboard, and they fought over port 4321, so one could show the other's Inbox.

Authority

The hub can't act for the owner. It has no POST route and no proxy, answers only to its own Host, and its page has connect-src 'self' and frame-ancestors 'none'. Each card is a link to the instance's own origin, where the dashboard's existing owner checks apply. Instance discovery reads /api/hello, which carries counts, not log content. The Host fix narrows what any page can read.

Migration

None for a running project. Stacks resolves devteam, because its workers' windows are there, and, with no dashboard answering in the block when it restarts, takes 4321 and saves it. New projects get devteam-<project> and the next port. The owner's new bookmark is http://127.0.0.1:4320.

Tests

See the PR comments for the local runs on Node 18.20.4, 20.19.6 and 24.14.1. CI runs 18/20/22/24.

🤖 Generated with Claude Code

[hhff]

Review (upstream loop). The author's PR, so a fresh reviewer agent reviewed it adversarially, in three passes:

• Pass 1, CHANGES, 3 blockers:

  • tmuxSession() recursed through liveSessions();
  • lost-Enter recovery looked up the wrong key;
  • the tmux tests couldn't be trusted.

  Also 13 should-fixes and nits. All were fixed: ports held on ::1 or wildcard addresses, the start-up race, the session name hashed per checkout, the legacy name saved on detection, a light hello, coalesced hub scans with a cross-site refusal, the hub port's holder classified, quoted targets, untracked kit files, the version rule, and stronger tests.

• Pass 2, CHANGES, 1 blocker: matching windows by name let one project adopt another's devteam session permanently. Windows are now ours only when a pane started under this checkout's .worktrees/, compared after resolving symlinks. Also fixed: the hub page opens from any link, and only /instances.json refuses cross-site requests.

• Pass 3, APPROVE. Nits addressed: every pane counts, not only the active one. tmux without pane_start_path is noted as a limit.

• Authority: the hub has no POST and no proxy, answers only to its own Host, and its page has connect-src 'self'. The dashboard's Host check now covers every route; before, GET / and /api/data were readable through DNS rebinding.

• Tests at 352565d: CI 18/20/22/24 green. Local 24.14.1 47/47, 20.19.6 47/47. Local 18.20.4: one failure, in the review test's review-answer POST ('fetch failed'). The same intermittent macOS + Node 18 dashboard death hit this exact test before this PR (in v0.18.1-era runs); I'm tracking it separately.