@seanmars/tospec 0.23.0 → 0.24.0

package/dist/commands/dashboard.js

@@ -1,172 +1,47 @@
 /**
- * `tospec dashboard` — a `node:http` server over the aggregators in
- * `core/dashboard-data.ts`. Reads are GET-only; the sole write is
- * `POST /api/task`. `/api/render` and `/api/task` are trust boundaries: the
- * path must resolve under the tospec root (D5).
+ * `tospec dashboard start|stop|status` — one local hub for every tospec
+ * project. It reads no project files: Claude Code sessions push snapshots and
+ * activity through the `tospec-dashboard` mod (see `core/dashboard-hub.ts`),
+ * and the browser reads those. A task checkbox is relayed to a live session,
+ * which applies it with the checks in `core/dashboard-routes.ts`. Beyond that
+ * the page can only answer a question a session asked (an AskUserQuestion, a
+ * permission), and only from a hub bound to loopback; it never types a prompt.
  */
 import * as http from 'node:http';
-import { promises as fs, readdirSync, readFileSync, rmSync, unlinkSync, watch, } from 'node:fs';
+import { promises as fs, readdirSync, rmSync } from 'node:fs';
 import * as path from 'node:path';
-import * as os from 'node:os';
-import * as crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { MarkdownParser } from '../core/parsers/markdown-parser.js';
-import { renderMarkdownSafe } from '../core/markdown-render.js';
-import { collectOverview, collectChangeDetail, collectArchive, collectDecisions, readSyncConclusion, } from '../core/dashboard-data.js';
-import { collectActivity } from '../core/dashboard-activity.js';
+import { DashboardHub, HubRequestError, } from '../core/dashboard-hub.js';
+import { DASHBOARD_PROTOCOL } from '../core/dashboard-routes.js';
 import { getGlobalConfigDir } from '../core/global-config.js';
-import { acceptsAnyHostHeader, assertBindableHost, connectableUrl, isAllowedHostHeader, listenFrom, openBrowser, packageAssetsDir, sendJson, serveAsset, } from '../core/local-server.js';
-import { resolveTaskFiles, setTaskDone } from '../utils/task-progress.js';
-const DEFAULT_PORT = 5620;
+import { LOOPBACK_HOSTS, acceptsAnyHostHeader, assertBindableHost, connectableUrl, isAllowedHostHeader, listenOnce, normalizeHost, openBrowser, packageAssetsDir, sendJson, serveAsset, } from '../core/local-server.js';
+export const DEFAULT_PORT = 5620;
 const DEFAULT_HOST = '127.0.0.1';
 // Readiness signal the detached child writes to stderr once bound; emitted only
-// when TOSPEC_DASHBOARD_PIDFILE marks it as a `--detach` child.
+// when TOSPEC_DASHBOARD_DETACHED marks it as the child `dashboard start` spawned.
 const LISTENING_PREFIX = 'LISTENING ';
-/** Drops one leading `Error: ` the child added, so wrapping doesn't stack prefixes. */
-function stripErrorPrefix(text) {
-    return text.replace(/^Error:\s*/, '');
-}
+const DETACHED_ENV = 'TOSPEC_DASHBOARD_DETACHED';
 // The child signals right after binding, so slower than a cold start plus a
 // bind means it is stuck, not busy.
 const READINESS_TIMEOUT_MS = 10_000;
+// `status` asks a hub on this machine; one that takes longer is not answering.
+const STATUS_TIMEOUT_MS = 3_000;
+// How often online/offline transitions are checked and broadcast.
+const SWEEP_INTERVAL_MS = 5_000;
+// A browser POST carries one task tick or one answer (up to four questions of
+// CJK text); a mod push carries a whole project.
+const BROWSER_BODY_LIMIT = 64 * 1024;
+const SNAPSHOT_BODY_LIMIT = 64 * 1024 * 1024;
+const REPLY_BODY_LIMIT = 16 * 1024 * 1024;
+const ACTIVITY_BODY_LIMIT = 1024 * 1024;
 /** This command's shipped frontend; `serveAsset` is confined to it. */
 const ASSETS_DIR = packageAssetsDir('dashboard');
-/**
- * Decodes one URL path segment and confines it to a single directory name, or
- * answers the request and returns null.
- *
- * WHATWG URL normalizes a literal `..` out of the pathname but does not
- * percent-decode, so `%2e%2e%2f` survives until `decodeURIComponent` turns it
- * back into `../../` — a traversal. Malformed escapes (`%zz`) are the client's
- * mistake, so 400 rather than a 500 from the router.
- */
-function decodePathSegment(raw, label, res) {
-    let decoded;
-    try {
-        decoded = decodeURIComponent(raw);
-    }
-    catch {
-        sendJson(res, 400, { error: `malformed ${label}` });
-        return null;
-    }
-    if (!decoded || decoded.includes('/') || decoded.includes('\\') || decoded.includes('..')) {
-        sendJson(res, 403, { error: 'forbidden' });
-        return null;
-    }
-    return decoded;
-}
-async function handleChangeDetail(projectRoot, rawName, res) {
-    const name = decodePathSegment(rawName, 'change name', res);
-    if (name === null)
-        return;
-    try {
-        sendJson(res, 200, await collectChangeDetail(projectRoot, name));
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        sendJson(res, /not found/i.test(message) ? 404 : 500, { error: message });
-    }
-}
-async function handleSpec(projectRoot, rawId, res) {
-    const id = decodePathSegment(rawId, 'spec id', res);
-    if (id === null)
-        return;
-    const specPath = path.join(projectRoot, 'tospec', 'specs', id, 'spec.md');
-    let content;
-    try {
-        content = await fs.readFile(specPath, 'utf-8');
-    }
-    catch {
-        return sendJson(res, 404, { error: 'not found' });
-    }
-    const spec = new MarkdownParser(content).parseSpec(id);
-    sendJson(res, 200, { id, requirements: spec.requirements });
-}
-/**
- * Git activity + health signals (ADR 001). `change` feeds a `git log` path
- * filter, so reject anything that could escape `tospec/changes/` before it
- * reaches git. `days` is capped at 3650 to bound the zero-filled series.
- */
-async function handleActivity(projectRoot, changeParam, daysParam, res) {
-    const change = changeParam ?? undefined;
-    if (change && (change.includes('/') || change.includes('\\') || change.includes('..'))) {
-        return sendJson(res, 403, { error: 'forbidden' });
-    }
-    // Absent or garbage stays undefined → collectActivity's default.
-    let window;
-    if (daysParam === 'all') {
-        window = 'all';
-    }
-    else {
-        const parsed = Number(daysParam);
-        if (Number.isInteger(parsed) && parsed >= 1)
-            window = Math.min(parsed, 3650);
-    }
-    sendJson(res, 200, await collectActivity(projectRoot, change, window));
-}
-/**
- * Trust boundary (D5): resolves a client-supplied path to an absolute `.md` file
- * under `<root>/<prefix>`, or null when it escapes.
- */
-function resolveTospecFile(projectRoot, file, prefix) {
-    const resolved = path.resolve(projectRoot, file.replace(/\\/g, '/'));
-    if (!resolved.startsWith(path.resolve(projectRoot) + path.sep))
-        return null;
-    const posixRel = path.relative(projectRoot, resolved).replace(/\\/g, '/');
-    if (!posixRel.startsWith(prefix) || !posixRel.endsWith('.md'))
-        return null;
-    return resolved;
-}
-const ARCHIVE_SEGMENT = 'archive';
-/**
- * True for a path inside `tospec/changes/archive/`. Not folded into
- * `resolveTospecFile`: `/api/render` shares that helper and legitimately renders
- * archived documents, so the rejection belongs on the write path.
- */
-function isArchivedChangePath(projectRoot, resolvedAbsPath) {
-    const posixRel = path.relative(projectRoot, resolvedAbsPath).replace(/\\/g, '/');
-    const parts = posixRel.split('/');
-    return parts[0] === 'tospec' && parts[1] === 'changes' && parts[2] === ARCHIVE_SEGMENT;
-}
-/**
- * Maps a resolved task-file path (`tospec/changes/<name>/...`) back to its
- * change name, or null when it doesn't match. An archived change is one level
- * deeper, so `parts[2]` is the literal `archive`, never a change name.
- */
-function changeNameFromTaskFile(projectRoot, resolvedAbsPath) {
-    const posixRel = path.relative(projectRoot, resolvedAbsPath).replace(/\\/g, '/');
-    const parts = posixRel.split('/');
-    if (parts.length < 4 || parts[0] !== 'tospec' || parts[1] !== 'changes')
-        return null;
-    if (parts[2] === ARCHIVE_SEGMENT)
-        return null;
-    return parts[2] || null;
-}
-/**
- * Renders through `renderMarkdownSafe`, not `marked.parse`: the client assigns
- * this with `innerHTML`, so anything the renderer passes through runs inside
- * the CSRF boundary `handleTaskUpdate` relies on.
- */
-async function handleRender(projectRoot, fileParam, res) {
-    if (!fileParam) {
-        return sendJson(res, 400, { error: 'missing file parameter' });
-    }
-    const resolved = resolveTospecFile(projectRoot, fileParam, 'tospec/');
-    if (!resolved) {
-        return sendJson(res, 403, { error: 'forbidden' });
-    }
-    let content;
-    try {
-        content = await fs.readFile(resolved, 'utf-8');
-    }
-    catch {
-        return sendJson(res, 404, { error: 'not found' });
-    }
-    const html = await renderMarkdownSafe(content);
-    sendJson(res, 200, { html });
+/** Drops one leading `Error: ` the child added, so wrapping doesn't stack prefixes. */
+function stripErrorPrefix(text) {
+    return text.replace(/^Error:\s*/, '');
 }
 /** Reads a JSON request body, capped so a stray client can't exhaust memory. */
-async function readJsonBody(req, limit = 8192) {
+async function readJsonBody(req, limit) {
     // Bytes first, decoded once: `string += chunk` decodes each chunk alone, so a
     // multi-byte character split across two chunks (a CJK filename) came out as
     // U+FFFD and the request addressed a file that does not exist.
@@ -176,7 +51,7 @@ async function readJsonBody(req, limit = 8192) {
         const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
         size += buffer.length;
         if (size > limit)
-            throw new Error('body too large');
+            throw new HubRequestError('body too large', 413);
         chunks.push(buffer);
     }
     const raw = Buffer.concat(chunks).toString('utf-8');
@@ -184,103 +59,9 @@ async function readJsonBody(req, limit = 8192) {
         return JSON.parse(raw);
     }
     catch {
-        throw new Error('invalid json');
+        throw new HubRequestError('invalid json', 400);
     }
 }
-/**
- * Ticks a task checkbox: `{ file, line, done }`, `file` root-relative and `line`
- * 1-based. Writes are confined to `<root>/tospec/changes/`, so the dashboard can
- * never edit specs.
- *
- * Requiring `content-type: application/json` is load-bearing: it pushes any
- * cross-origin POST into a CORS preflight this server does not answer.
- */
-async function handleTaskUpdate(projectRoot, req, res) {
-    if (!/^application\/json\b/.test(req.headers['content-type'] ?? '')) {
-        return sendJson(res, 415, { error: 'expected application/json' });
-    }
-    let body;
-    try {
-        body = await readJsonBody(req);
-    }
-    catch (err) {
-        return sendJson(res, 400, { error: err instanceof Error ? err.message : 'bad request' });
-    }
-    const { file, line, done } = (body ?? {});
-    if (typeof file !== 'string' || !Number.isInteger(line) || line < 1) {
-        return sendJson(res, 400, { error: 'expected { file: string, line: int >= 1, done: bool }' });
-    }
-    if (typeof done !== 'boolean') {
-        return sendJson(res, 400, { error: 'expected { file: string, line: int >= 1, done: bool }' });
-    }
-    const resolved = resolveTospecFile(projectRoot, file, 'tospec/changes/');
-    if (!resolved) {
-        return sendJson(res, 403, { error: 'forbidden' });
-    }
-    // Before the sync gate: that gate asks whether a change is *becoming*
-    // immutable; an archived one already is.
-    if (isArchivedChangePath(projectRoot, resolved)) {
-        return sendJson(res, 403, { error: 'change is archived; tasks are immutable' });
-    }
-    // The checks above are lexical. A task file that is itself a symlink out of
-    // the project passes both, and the write would land outside the root, so the
-    // fence is re-checked on the real path. Before the tracked-file check below:
-    // that check canonicalizes its own side, so the symlink used to fail there
-    // as "not the tracked file" — refused, but for the wrong reason. A file that
-    // is gone by now is the 404 the write would have reported.
-    let realFile;
-    try {
-        const realRoot = await fs.realpath(projectRoot);
-        realFile = await fs.realpath(resolved);
-        if (!realFile.startsWith(realRoot + path.sep)) {
-            return sendJson(res, 403, { error: 'forbidden' });
-        }
-    }
-    catch (err) {
-        if (err.code === 'ENOENT')
-            return sendJson(res, 404, { error: 'not found' });
-        throw err;
-    }
-    // A file directly under tospec/changes/ belongs to no change, so neither the
-    // sync gate nor the tracked-file check below can apply to it. Skipping both
-    // left any markdown there writable by a raw POST.
-    const changeName = changeNameFromTaskFile(projectRoot, resolved);
-    if (!changeName) {
-        return sendJson(res, 403, { error: 'forbidden' });
-    }
-    // Freeze task edits once a change is sync certified. The frontend disable is
-    // only UX; this gate is what protects certified content from a raw POST. A
-    // read error reads as not certified.
-    const changeDir = path.join(projectRoot, 'tospec', 'changes', changeName);
-    if ((await readSyncConclusion(changeDir)) === 'PASS') {
-        return sendJson(res, 409, { error: 'change is archiving; tasks are frozen' });
-    }
-    // Confined to the schema's tracked task file, via the resolver the read
-    // side uses. The path check above only proves the file sits inside a change
-    // directory, so any other markdown there with a checkbox on the addressed
-    // line was writable too, invisibly. The resolver canonicalizes the files it
-    // finds and leaves its `tasks.md` fallback as joined, so both spellings of
-    // the request path are compared.
-    const tracked = resolveTaskFiles(changeDir, projectRoot).map((file) => path.resolve(file));
-    if (!tracked.includes(realFile) && !tracked.includes(path.resolve(resolved))) {
-        return sendJson(res, 409, {
-            error: `${path.basename(resolved)} is not this change's tracked task file`,
-        });
-    }
-    try {
-        await setTaskDone(resolved, line, done);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        // Stale client view or a deleted file — neither is a server fault, so no 500.
-        if (/not a task/.test(message))
-            return sendJson(res, 409, { error: message });
-        if (/ENOENT/.test(message))
-            return sendJson(res, 404, { error: 'not found' });
-        throw err;
-    }
-    sendJson(res, 200, { file, line, done });
-}
 function handleEvents(req, res, clients) {
     res.writeHead(200, {
         'content-type': 'text/event-stream',
@@ -291,18 +72,22 @@ function handleEvents(req, res, clients) {
     clients.add(res);
     req.on('close', () => clients.delete(res));
 }
-function broadcastChange(clients) {
-    for (const client of clients) {
-        client.write('event: change\ndata: {}\n\n');
-    }
+function broadcast(clients, event) {
+    const { type, ...data } = event;
+    const line = `event: ${type}\ndata: ${JSON.stringify(data)}\n\n`;
+    for (const client of clients)
+        client.write(line);
 }
 /**
  * Second layer behind `renderMarkdownSafe`, applied to every response.
  *
  * `script-src 'self'` is the load-bearing directive: it refuses the inline
- * handlers and `javascript:` URLs a markdown file would need to reach
- * `POST /api/task` from inside this origin. `style-src` keeps `'unsafe-inline'`
- * for Chart.js — a style injection cannot call the write endpoint.
+ * handlers and `javascript:` URLs a markdown file would need to reach the task
+ * relay from inside this origin. `style-src` still carries `'unsafe-inline'`,
+ * added for Chart.js, which the dashboard no longer loads (its charts are SVG
+ * styled from the stylesheet, and the app sets styles through the CSSOM).
+ * Dropping it is a separate hardening step; a style injection cannot call the
+ * write endpoint either way.
  */
 function applyContentSecurityPolicy(res) {
     res.setHeader('content-security-policy', [
@@ -317,7 +102,104 @@ function applyContentSecurityPolicy(res) {
         "frame-ancestors 'none'",
     ].join('; '));
 }
-async function handleRequest(projectRoot, req, res, clients, boundHost, acceptAnyHost) {
+/** `/api/p/<key>/<rest>` → the project key and the per-project path `/api/<rest>?…`. */
+function matchProjectPath(url) {
+    const match = /^\/api\/p\/([0-9a-f]{12})(\/.*)$/.exec(url.pathname);
+    if (!match)
+        return null;
+    return { key: match[1], inner: `/api${match[2]}${url.search}` };
+}
+/**
+ * `/api/p/<key>/sessions/<id>/<action>`: the hub's own answers about one
+ * session, matched before the per-project relay, which would otherwise carry
+ * them to the project as a file read.
+ */
+function matchSessionPath(url) {
+    const match = /^\/api\/p\/([0-9a-f]{12})\/sessions\/([^/]+)\/(log|answer)$/.exec(url.pathname);
+    if (!match)
+        return null;
+    try {
+        return { key: match[1], session: decodeURIComponent(match[2]), action: match[3] };
+    }
+    catch {
+        return null;
+    }
+}
+function fieldsOf(body) {
+    return typeof body === 'object' && body !== null ? body : {};
+}
+/**
+ * Every POST must be JSON. That is the CSRF fence for the whole write surface:
+ * a cross-origin page can only send `application/json` through a CORS preflight
+ * this server never answers, so no web page can push a snapshot, take a queued
+ * command, tick a task, or answer for a session.
+ */
+async function handlePost(hub, req, res, url) {
+    if (!/^application\/json\b/.test(req.headers['content-type'] ?? '')) {
+        return sendJson(res, 415, { error: 'expected application/json' });
+    }
+    const pathname = url.pathname;
+    if (pathname === '/api/mod/snapshot') {
+        const body = fieldsOf(await readJsonBody(req, SNAPSHOT_BODY_LIMIT));
+        return sendJson(res, 200, { project: hub.acceptSnapshot(body.session, body.snapshot) });
+    }
+    if (pathname === '/api/mod/poll') {
+        const body = fieldsOf(await readJsonBody(req, BROWSER_BODY_LIMIT));
+        const hangUp = new AbortController();
+        res.on('close', () => hangUp.abort());
+        const commands = await hub.poll(body.project, body.session, hangUp.signal);
+        if (commands === null)
+            return sendJson(res, 404, { error: 'unknown project' });
+        return sendJson(res, 200, { commands });
+    }
+    if (pathname === '/api/mod/reply') {
+        const body = fieldsOf(await readJsonBody(req, REPLY_BODY_LIMIT));
+        const settled = hub.reply(body.id, { status: body.status, body: body.body });
+        return sendJson(res, settled ? 200 : 404, settled ? { ok: true } : { error: 'no such request' });
+    }
+    if (pathname === '/api/mod/leave') {
+        const body = fieldsOf(await readJsonBody(req, BROWSER_BODY_LIMIT));
+        hub.leave(body.project, body.session);
+        return sendJson(res, 200, { ok: true });
+    }
+    if (pathname === '/api/mod/activity') {
+        const body = fieldsOf(await readJsonBody(req, ACTIVITY_BODY_LIMIT));
+        const known = hub.reportActivity(body.project, body.session, body);
+        return sendJson(res, known ? 200 : 404, known ? { ok: true } : { error: 'unknown project' });
+    }
+    if (pathname === '/api/mod/ask') {
+        const body = fieldsOf(await readJsonBody(req, ACTIVITY_BODY_LIMIT));
+        return sendJson(res, 200, hub.openAsk(body.project, body.session, body.ask));
+    }
+    if (pathname === '/api/mod/ask/wait') {
+        const body = fieldsOf(await readJsonBody(req, BROWSER_BODY_LIMIT));
+        const hangUp = new AbortController();
+        res.on('close', () => hangUp.abort());
+        return sendJson(res, 200, await hub.waitAsk(body.id, hangUp.signal));
+    }
+    if (pathname === '/api/mod/ask/close') {
+        const body = fieldsOf(await readJsonBody(req, BROWSER_BODY_LIMIT));
+        hub.closeAsk(body.id);
+        return sendJson(res, 200, { ok: true });
+    }
+    const session = matchSessionPath(url);
+    if (session && session.action === 'answer') {
+        const body = fieldsOf(await readJsonBody(req, BROWSER_BODY_LIMIT));
+        const answer = hub.answerAsk(session.key, session.session, body.id, body.answer);
+        return sendJson(res, answer.status, answer.body);
+    }
+    const scoped = matchProjectPath(url);
+    if (scoped && scoped.inner === '/api/task') {
+        const body = await readJsonBody(req, BROWSER_BODY_LIMIT);
+        const answer = await hub.write(scoped.key, { method: 'POST', path: '/api/task', body });
+        return sendJson(res, answer.status, answer.body);
+    }
+    if (scoped && scoped.inner === '/api/refresh') {
+        return sendJson(res, 202, { queued: hub.requestRefresh(scoped.key) });
+    }
+    sendJson(res, 404, { error: 'not found' });
+}
+async function handleRequest(hub, req, res, clients, boundHost, acceptAnyHost) {
     try {
         // Host allowlist runs before any route (DNS-rebinding guard).
         if (!isAllowedHostHeader(req.headers.host, boundHost, acceptAnyHost)) {
@@ -326,14 +208,29 @@ async function handleRequest(projectRoot, req, res, clients, boundHost, acceptAn
         applyContentSecurityPolicy(res);
         const url = new URL(req.url ?? '/', 'http://localhost');
         const pathname = url.pathname;
-        if (req.method === 'POST' && pathname === '/api/task') {
-            return await handleTaskUpdate(projectRoot, req, res);
+        if (req.method === 'POST') {
+            return await handlePost(hub, req, res, url);
         }
         if (req.method !== 'GET') {
             return sendJson(res, 405, { error: 'method not allowed' });
         }
         if (pathname === '/api/events')
             return handleEvents(req, res, clients);
+        // The mod's cheap reachability probe, so a session with no hub to talk to
+        // does not run the tospec CLI just to find that out.
+        if (pathname === '/api/health')
+            return sendJson(res, 200, { protocol: DASHBOARD_PROTOCOL });
+        // `interactive` tells the page whether to offer the answer controls.
+        if (pathname === '/api/projects') {
+            return sendJson(res, 200, { projects: hub.listProjects(), interactive: hub.interactive });
+        }
+        const session = matchSessionPath(url);
+        if (session) {
+            if (session.action !== 'log')
+                return sendJson(res, 405, { error: 'method not allowed' });
+            const log = hub.sessionLog(session.key, session.session);
+            return log ? sendJson(res, 200, log) : sendJson(res, 404, { error: 'That session is not connected to this dashboard.' });
+        }
         // `/index.html` alongside `/`: nothing links to it, but typing it 404'd.
         if (pathname === '/' || pathname === '/index.html') {
             return await serveAsset(res, ASSETS_DIR, 'index.html');
@@ -341,89 +238,76 @@ async function handleRequest(projectRoot, req, res, clients, boundHost, acceptAn
         if (pathname.startsWith('/assets/')) {
             return await serveAsset(res, ASSETS_DIR, pathname.slice('/assets/'.length));
         }
-        if (pathname === '/api/overview') {
-            return sendJson(res, 200, await collectOverview(projectRoot));
-        }
-        if (pathname === '/api/archive') {
-            return sendJson(res, 200, await collectArchive(projectRoot));
-        }
-        if (pathname === '/api/decisions') {
-            return sendJson(res, 200, await collectDecisions(projectRoot));
-        }
-        if (pathname === '/api/activity') {
-            return await handleActivity(projectRoot, url.searchParams.get('change'), url.searchParams.get('days'), res);
-        }
-        if (pathname.startsWith('/api/changes/')) {
-            return await handleChangeDetail(projectRoot, pathname.slice('/api/changes/'.length), res);
-        }
-        if (pathname.startsWith('/api/specs/')) {
-            return await handleSpec(projectRoot, pathname.slice('/api/specs/'.length), res);
-        }
-        if (pathname === '/api/render') {
-            return await handleRender(projectRoot, url.searchParams.get('file'), res);
+        const scoped = matchProjectPath(url);
+        if (scoped) {
+            const answer = await hub.read(scoped.key, scoped.inner);
+            return sendJson(res, answer.status, answer.body);
         }
         sendJson(res, 404, { error: 'not found' });
     }
     catch (err) {
+        if (err instanceof HubRequestError)
+            return sendJson(res, err.status, { error: err.message });
         // A single handler failure must never crash the server.
         sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
     }
 }
 /**
- * Starts the server, advancing past `EADDRINUSE` until a port is free (D6) so
- * dashboards for different projects coexist. Side-effect free (no logging,
- * signal handlers or registry) so tests can drive it directly.
+ * Starts the hub on exactly the requested port. Unlike the per-project servers
+ * this replaced, it never advances past `EADDRINUSE`: mods find the hub at a
+ * fixed address, so a hub that moved would be one no session could reach.
+ * Side-effect free (no logging, signal handlers or registry) so tests can drive
+ * it directly.
  */
-export async function startDashboardServer(projectRoot, opts = {}) {
+export async function startDashboardServer(opts = {}) {
     const host = opts.host ?? DEFAULT_HOST;
     assertBindableHost(host, 'dashboard', opts.allowRemote, 'Pass --allow-remote to accept that risk.');
     const acceptAnyHost = acceptsAnyHostHeader(host, opts.allowRemote);
     const clients = new Set();
+    const hub = new DashboardHub({
+        // Driving a session from the page runs tools in it, so only a hub that
+        // nobody else can reach may do so; `--allow-remote` leaves it read-only.
+        interactive: LOOPBACK_HOSTS.has(normalizeHost(host)),
+        ...opts.hub,
+    });
+    const unsubscribe = hub.subscribe((event) => broadcast(clients, event));
     const server = http.createServer((req, res) => {
-        void handleRequest(projectRoot, req, res, clients, host, acceptAnyHost);
+        void handleRequest(hub, req, res, clients, host, acceptAnyHost);
     });
-    const actualPort = await listenFrom(server, opts.port ?? DEFAULT_PORT, host);
-    const watcher = watchTospec(projectRoot, () => broadcastChange(clients));
-    server.once('close', () => watcher?.close());
-    return { server, url: connectableUrl(host, actualPort), port: actualPort };
-}
-/**
- * Watches `<root>/tospec` recursively and calls `onChange` (debounced), or null
- * if the directory can't be watched. `fs.watch` uses OS change notifications,
- * so it never locks the watched files — agents and users stay free to edit or
- * delete them (D2). Recursive watch is native on win32/macOS, Node 20+ on Linux.
- */
-function watchTospec(projectRoot, onChange) {
-    const dir = path.join(projectRoot, 'tospec');
-    let timer = null;
+    const requestedPort = opts.port ?? DEFAULT_PORT;
     try {
-        const watcher = watch(dir, { recursive: true }, () => {
-            if (timer)
-                clearTimeout(timer);
-            timer = setTimeout(onChange, 200);
-        });
-        watcher.on('close', () => timer && clearTimeout(timer));
-        watcher.on('error', () => { }); // transient watch errors must not crash the server
-        return watcher;
+        await listenOnce(server, requestedPort, host);
     }
-    catch {
-        return null;
+    catch (err) {
+        if (err.code === 'EADDRINUSE') {
+            throw new Error(`Port ${requestedPort} is already in use. Another dashboard may be running: see tospec dashboard status.`);
+        }
+        throw err;
     }
+    const address = server.address();
+    const port = typeof address === 'object' && address ? address.port : requestedPort;
+    const sweep = setInterval(() => hub.sweep(), SWEEP_INTERVAL_MS);
+    sweep.unref();
+    const close = async () => {
+        clearInterval(sweep);
+        unsubscribe();
+        hub.close();
+        // Held polls and SSE streams would otherwise keep close() from draining.
+        server.closeAllConnections?.();
+        await new Promise((resolve) => server.close(() => resolve()));
+    };
+    return { server, url: connectableUrl(host, port), port, hub, close };
 }
-/**
- * PID-file location, keyed by project root so `--detach` and `--stop` derive the
- * same path. In the OS temp dir, not the repo, so it never gets committed.
- */
-export function pidFilePath(projectRoot) {
-    const hash = crypto.createHash('sha1').update(path.resolve(projectRoot)).digest('hex').slice(0, 12);
-    return path.join(os.tmpdir(), `tospec-dashboard-${hash}.json`);
+function registryDir() {
+    // Derived from the one config resolver, so relocating the config directory
+    // moves the registry with it.
+    return path.join(getGlobalConfigDir(), 'dashboards');
 }
 /** True if a process with this PID exists (signal 0 probes without killing). */
 function isProcessAlive(pid) {
-    // Every record's pid arrives here, so the sign check guards the module: on
-    // POSIX `kill(0, sig)` signals our own process group and `kill(-n, sig)` a
-    // named one, so a corrupt record in the shared temp dir would make `--stop`
-    // terminate the user's own shell.
+    // On POSIX `kill(0, sig)` signals our own process group and `kill(-n, sig)` a
+    // named one, so a corrupt marker would make `stop` terminate the user's own
+    // shell.
     if (!Number.isInteger(pid) || pid <= 0)
         return false;
     try {
@@ -435,67 +319,6 @@ function isProcessAlive(pid) {
         return err.code === 'EPERM';
     }
 }
-/**
- * This project's dashboard PID record, or null if absent or corrupt. `pid` is
- * the only required field — a truncated record still names a process to reap.
- */
-async function readPidRecord(pidFile) {
-    try {
-        const rec = JSON.parse(await fs.readFile(pidFile, 'utf-8'));
-        return typeof rec?.pid === 'number' ? rec : null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Records this dashboard so `--stop` can find it. Reads tolerate the missing
- * optional fields of pre-0.13 records; writes do not, since the root is what
- * attributes a scanned record to its project.
- */
-async function writePidRecord(pidFile, rec) {
-    await fs.writeFile(pidFile, JSON.stringify(rec), 'utf-8');
-}
-/**
- * Removes a pid record only if it still names `pid`: the path is keyed by
- * project, not process, so two sibling dashboards share this file and either
- * clearer would otherwise delete the other's record.
- *
- * Limitation: one record per project, so only the later writer is tracked by
- * pid file; both stay reachable through their registry markers.
- *
- * Sync so it completes before the `process.exit` its signal-handler caller
- * races — hence not reusing the async `readPidRecord`.
- */
-export function clearPidRecordOwnedBy(pidFile, pid) {
-    try {
-        const rec = JSON.parse(readFileSync(pidFile, 'utf-8'));
-        if (rec?.pid === pid)
-            unlinkSync(pidFile);
-    }
-    catch {
-        // Absent: nothing to do. Corrupt: left alone — it names no process, and a
-        // half-written record may belong to one that is starting up.
-    }
-}
-/** Every project's pid file, not just this one's — they all live in the temp dir. */
-async function pidFilePaths() {
-    const dir = os.tmpdir();
-    try {
-        return (await fs.readdir(dir))
-            // Exactly the shape pidFilePath() generates — never wider than we write.
-            .filter((name) => /^tospec-dashboard-[0-9a-f]{12}\.json$/.test(name))
-            .map((name) => path.join(dir, name));
-    }
-    catch {
-        return [];
-    }
-}
-function registryDir() {
-    // Derived from the one config resolver, so relocating the config directory
-    // moves the registry with it.
-    return path.join(getGlobalConfigDir(), 'dashboards');
-}
 /**
  * Lists live dashboards sorted by port, reaping any marker whose process has
  * died. A missing or unreadable dir means no dashboards are running.
@@ -515,6 +338,7 @@ export async function listDashboards() {
         if (!m)
             continue;
         const pid = Number(m[1]);
+        const port = Number(m[2]);
         const file = path.join(dir, name);
         if (!isProcessAlive(pid)) {
             // Best-effort: failing to unlink one stale marker must not take down a
@@ -522,112 +346,27 @@ export async function listDashboards() {
             await fs.rm(file, { force: true }).catch(() => { });
             continue;
         }
-        let projectRoot = '';
+        let url = '';
         try {
-            projectRoot = (await fs.readFile(file, 'utf-8')).trim();
+            url = (await fs.readFile(file, 'utf-8')).trim();
         }
         catch {
-            /* marker without content (pre-upgrade) → leave path blank */
+            /* unreadable marker → fall back to loopback below */
         }
-        running.push({ pid, port: Number(m[2]), projectRoot });
+        // A marker from before the hub held a project root, not a URL.
+        if (!/^https?:\/\//.test(url))
+            url = connectableUrl(DEFAULT_HOST, port);
+        running.push({ pid, port, url });
     }
     return running.sort((a, b) => a.port - b.port);
 }
-/**
- * One line describing a running dashboard, for `--list` and `--stop`'s picker.
- * The URL assumes loopback — `RunningDashboard` doesn't record the bound host.
- */
-export function formatRunningDashboard(d, sep = '\t') {
-    const url = `http://${DEFAULT_HOST}:${d.port}`;
-    return `pid ${d.pid}${sep}${url}${sep}${d.projectRoot || '(unknown project)'}`;
-}
-/**
- * `--stop` found dashboards but cannot ask which to stop (no terminal). Carries
- * its own diagnostic so the shared failure sink renders it.
- */
-export class DashboardStopError extends Error {
-    diagnostic;
-    constructor(message, fix) {
-        super(message);
-        this.name = 'DashboardStopError';
-        this.diagnostic = { severity: 'error', code: 'dashboard_stop_needs_selection', message, fix };
-    }
+/** One line describing a running dashboard, for `start`'s refusal. */
+export function formatRunningDashboard(d) {
+    return `pid ${d.pid}  ${d.url}`;
 }
-/**
- * The detached child neither reported itself listening nor exited. It may still
- * be coming up, so the message reports what was not observed rather than
- * claiming failure.
- */
-export class DashboardReadinessTimeoutError extends Error {
-    diagnostic;
-    constructor(timeoutMs) {
-        const message = `The background dashboard process did not report that it is listening within ${Math.round(timeoutMs / 1000)}s. ` +
-            'It was started and has not exited, so it may still be coming up.';
-        super(message);
-        this.name = 'DashboardReadinessTimeoutError';
-        this.diagnostic = {
-            severity: 'error',
-            code: 'dashboard_detach_readiness_timeout',
-            message,
-            fix: 'Check whether it came up with: tospec dashboard --list (then tospec dashboard --stop to stop it).',
-        };
-    }
-}
-/**
- * Every dashboard `--stop` can reach: the registry unioned with every project's
- * pid file, keyed by pid, reaping dead records along the way.
- *
- * The registry alone is not enough — `listDashboards()` reaps any marker whose
- * pid looks dead, so a live server can lose its marker and become unstoppable
- * while its pid file still names it.
- *
- * `ownRootHint` names records written before pid files carried their own root;
- * it never restricts the result.
- */
-export async function collectStoppableDashboards(ownRootHint) {
-    const byPid = new Map();
-    for (const d of await listDashboards())
-        byPid.set(d.pid, d);
-    const ownPidFile = ownRootHint ? pidFilePath(ownRootHint) : null;
-    for (const file of await pidFilePaths()) {
-        const rec = await readPidRecord(file);
-        if (!rec)
-            continue;
-        // Reap like the marker reaper does: a crashed dashboard's record would
-        // otherwise linger until the OS recycled its pid, then read as alive again —
-        // a phantom `--stop` would kill an unrelated process for. Unlink is
-        // best-effort: the POSIX temp dir is shared with other users.
-        if (!isProcessAlive(rec.pid)) {
-            await fs.rm(file, { force: true }).catch(() => { });
-            continue;
-        }
-        // Live, but we cannot name a port to report or reach it by.
-        if (typeof rec.port !== 'number')
-            continue;
-        const root = rec.projectRoot ?? (file === ownPidFile && ownRootHint ? path.resolve(ownRootHint) : '');
-        const known = byPid.get(rec.pid);
-        if (!known) {
-            byPid.set(rec.pid, { pid: rec.pid, port: rec.port, projectRoot: root });
-            continue;
-        }
-        // A content-less registry marker never matches its project; the pid file may
-        // still know the root.
-        if (!known.projectRoot && root)
-            byPid.set(rec.pid, { ...known, projectRoot: root });
-    }
-    return [...byPid.values()].sort((a, b) => a.port - b.port);
-}
-/**
- * Ports held by live dashboards, reaping dead markers as a side effect. Runs at
- * every startup so a crashed dashboard's port frees up.
- */
-async function reapAndCollectPorts() {
-    return new Set((await listDashboards()).map((d) => d.port));
-}
-/** Creates the `{pid}_{port}` marker for this dashboard, holding its project root. */
-async function registerDashboard(pid, port, projectRoot) {
+async function registerDashboard(pid, port, url) {
     await fs.mkdir(registryDir(), { recursive: true });
-    await fs.writeFile(path.join(registryDir(), `${pid}_${port}`), projectRoot, 'utf-8');
+    await fs.writeFile(path.join(registryDir(), `${pid}_${port}`), url, 'utf-8');
 }
 /** Removes any marker for this pid (port-agnostic, so callers needn't know it). */
 async function unregisterDashboard(pid) {
@@ -666,42 +405,45 @@ function unregisterDashboardSync(pid) {
     }
 }
 /**
- * Launches the dashboard as a detached background process: re-runs this CLI
- * without `--detach` (the child is the actual server), then waits for the
- * child's `LISTENING` report, so the URL printed is one the child actually
- * bound — including after an EADDRINUSE fallback moved it off the predicted
- * port. Order: spawn → wait for the report → write the PID record → print.
- *
- * Refuses if any live dashboard already serves this project, asking the shared
- * candidate set because either record can be the only one left (a foreground
- * dashboard writes no pid file; a background one can lose its registry marker).
- *
- * This process and the child both write the PID record, with identical fields.
- * The child's is all that remains if this process dies mid-handshake; this one
- * makes a record exist by the time the call returns, since the child writes only
- * after signalling.
+ * The detached child neither reported itself listening nor exited. It may still
+ * be coming up, so the message reports what was not observed rather than
+ * claiming failure.
+ */
+export class DashboardReadinessTimeoutError extends Error {
+    diagnostic;
+    constructor(timeoutMs) {
+        const message = `The background dashboard process did not report that it is listening within ${Math.round(timeoutMs / 1000)}s. ` +
+            'It was started and has not exited, so it may still be coming up.';
+        super(message);
+        this.name = 'DashboardReadinessTimeoutError';
+        this.diagnostic = {
+            severity: 'error',
+            code: 'dashboard_detach_readiness_timeout',
+            message,
+            fix: 'Check whether it came up with: tospec dashboard status (then tospec dashboard stop to stop it).',
+        };
+    }
+}
+/**
+ * `tospec dashboard start`: launches the hub as a detached background process
+ * by re-running this CLI as the hidden `dashboard serve` (the child is the
+ * actual server), then waits for the child's `LISTENING` report, so the URL
+ * printed is one the child actually bound.
  *
- * This is the only guarded start path: nothing stops a second foreground
- * `tospec dashboard`, so "one dashboard per project" is not machine-wide.
+ * Refuses while any hub is running: one hub serves every project, and a second
+ * one could only bind another port that no mod looks at. Limitation: no
+ * cross-process lock, so two simultaneous `start` could both pass the guard;
+ * the loser then fails on the port.
  */
-export async function detachDashboard(projectRoot, cliEntry, opts) {
-    const pidFile = pidFilePath(projectRoot);
-    const running = shouldRefuseDetach(await collectStoppableDashboards(projectRoot), projectRoot);
+export async function detachDashboard(cliEntry, opts) {
+    const running = (await listDashboards())[0];
     if (running) {
-        // Same fields and separator as `--list` and `--stop`'s picker.
-        console.log('Dashboard already running for this project.');
-        console.log(`  ${formatRunningDashboard(running, '  ')}`);
-        console.log('Stop it with: tospec dashboard --stop');
+        console.log('Dashboard already running.');
+        console.log(`  ${formatRunningDashboard(running)}`);
+        console.log('Stop it with: tospec dashboard stop');
         return;
     }
-    // Predict the port to hand the child, skipping ones live dashboards hold. The
-    // child re-checks and binds, so a race for this port just shifts it upward;
-    // what gets reported is the URL the child confirms, never this prediction.
-    const used = await reapAndCollectPorts();
-    let port = opts.port;
-    while (used.has(port))
-        port++;
-    const args = [cliEntry, 'dashboard', opts.targetPath, '--port', String(port), '--host', opts.host];
+    const args = [cliEntry, 'dashboard', 'serve', '--port', String(opts.port), '--host', opts.host];
     if (opts.open)
         args.push('--open');
     if (opts.allowRemote)
@@ -713,15 +455,13 @@ export async function detachDashboard(projectRoot, cliEntry, opts) {
         stdio: ['ignore', 'ignore', 'pipe'],
         // On Windows, detached: true otherwise pops a new console window.
         windowsHide: true,
-        env: { ...process.env, TOSPEC_DASHBOARD_PIDFILE: pidFile },
+        env: { ...process.env, [DETACHED_ENV]: '1' },
     });
-    // No pid means the spawn itself failed; reporting success would leave a record
-    // `--stop` could never use.
+    // No pid means the spawn itself failed; reporting success would point at a
+    // process `--stop` could never reach.
     if (child.pid === undefined) {
         throw new Error('Could not start the background dashboard process.');
     }
-    // Everything that can go wrong after a successful spawn happens inside the
-    // child and is only observable through this handshake.
     let confirmedUrl;
     try {
         confirmedUrl = await waitForListening(child);
@@ -731,31 +471,14 @@ export async function detachDashboard(projectRoot, cliEntry, opts) {
         // un-unref'd handle would keep this process's event loop alive.
         child.unref();
     }
-    // Derived from the URL the child reported, so this record and the child's own
-    // agree whichever lands last. Limitation: no cross-process lock, so two
-    // simultaneous --detach could both pass the guard.
-    await writePidRecord(pidFile, {
-        pid: child.pid,
-        port: portFromUrl(confirmedUrl) ?? port,
-        url: confirmedUrl,
-        projectRoot: path.resolve(projectRoot),
-    });
     console.log(`Dashboard starting in background at ${confirmedUrl}`);
-    console.log('Stop it with: tospec dashboard --stop');
-}
-/** `http://host:5621` -> `5621`, or null if the URL carries no parseable port. */
-function portFromUrl(url) {
-    const match = /:(\d+)$/.exec(url);
-    return match ? Number(match[1]) : null;
+    console.log('Stop it with: tospec dashboard stop');
 }
 /**
  * Races the child's outcome: resolves with the confirmed URL on
  * `LISTENING <url>`, rejects with its captured stderr if it exits first, and
  * rejects on timeout if it does neither. Closes the stderr pipe once settled so
  * our end cannot keep this process's event loop alive.
- *
- * The timeout is a real third outcome: a child that binds then wedges emits
- * neither event, and `--detach` would hang with no output.
  */
 function waitForListening(child, timeoutMs = READINESS_TIMEOUT_MS) {
     return new Promise((resolve, reject) => {
@@ -804,44 +527,13 @@ function waitForListening(child, timeoutMs = READINESS_TIMEOUT_MS) {
         }, timeoutMs);
     });
 }
-/** Case-correct path equality (the Windows filesystem is case-insensitive). */
-export function samePath(a, b) {
-    const na = path.resolve(a);
-    const nb = path.resolve(b);
-    return process.platform === 'win32' ? na.toLowerCase() === nb.toLowerCase() : na === nb;
-}
-/**
- * The dashboards `--stop` may terminate without asking. Empty is the caller's
- * cue to offer the pick-from-all list. A candidate with no recorded project
- * never matches: `path.resolve('')` is the cwd, so a blank root would claim it.
- */
-export function selectStopTargets(candidates, projectRoot) {
-    if (!projectRoot)
-        return [];
-    return candidates.filter((d) => d.projectRoot && samePath(d.projectRoot, projectRoot));
-}
-/**
- * The dashboard already serving this project, or null to go ahead and start one.
- * One dashboard per project, foreground or background — see
- * `tospec/decisions/20260727_232950-one-dashboard-per-project.md`.
- *
- * Deliberately the same question `--stop` asks, over the same candidate set, so
- * the two can never disagree about what is running.
- */
-export function shouldRefuseDetach(candidates, projectRoot) {
-    // First match only: one is enough to refuse and point at.
-    return selectStopTargets(candidates, projectRoot)[0] ?? null;
-}
 /**
- * Terminates a running dashboard and clears its registry marker, plus the
- * per-project pid file if that still names this pid. A dead pid counts as
- * already stopped.
- *
- * Returns null on success, or the reason the signal was refused — the POSIX temp
- * dir is shared, so a candidate can belong to another user.
+ * Terminates a running dashboard and clears its registry marker. A dead pid
+ * counts as already stopped. Returns null on success, or the reason the signal
+ * was refused.
  *
  * Limitation: SIGTERM; Windows maps it to TerminateProcess (hard kill), so the
- * target's own cleanup won't run — we clear its files here.
+ * target's own cleanup won't run — we clear its marker here.
  */
 export async function stopRunningDashboard(d) {
     try {
@@ -849,71 +541,145 @@ export async function stopRunningDashboard(d) {
     }
     catch (err) {
         // ESRCH means it exited between listing and now: already stopped, so still
-        // clear its records. Anything else (EPERM) is a real refusal.
+        // clear its marker. Anything else (EPERM) is a real refusal.
         const { code, message } = err;
         if (code !== 'ESRCH')
             return code ?? message;
     }
     await unregisterDashboard(d.pid);
-    // Only this dashboard's record: the path is per-project, so stopping one of
-    // two siblings must not clear the other's.
-    if (d.projectRoot)
-        clearPidRecordOwnedBy(pidFilePath(d.projectRoot), d.pid);
     return null;
 }
 /**
- * CLI entry: allocates a free port, starts the server, prints the URL, and stays
- * up until terminated. Port allocation reaps dead registry markers and skips
- * ports live dashboards hold; the bind then advances past any the registry
- * didn't know about.
+ * `tospec dashboard stop`: stops every hub, not a pick. One serves all
+ * projects, so there is no "this project's dashboard" left to choose.
+ */
+export async function dashboardStopCommand() {
+    const running = await listDashboards();
+    if (running.length === 0) {
+        console.log('No dashboards are running.');
+        return;
+    }
+    for (const d of running) {
+        const refusal = await stopRunningDashboard(d);
+        if (refusal === null) {
+            console.log(`Stopped dashboard (pid ${d.pid}) at ${d.url}.`);
+        }
+        else {
+            console.error(`Could not stop dashboard (pid ${d.pid}) at ${d.url}: ${refusal}.`);
+            process.exitCode = 1;
+        }
+    }
+}
+/**
+ * Asks a running hub which projects it serves. Sessions live only in the hub's
+ * memory, so the registry marker can say a hub is running but not whom it
+ * serves.
+ */
+export async function fetchHubProjects(d, timeoutMs = STATUS_TIMEOUT_MS) {
+    const res = await fetch(`${d.url}/api/projects`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok)
+        throw new Error(`it answered HTTP ${res.status}`);
+    const body = (await res.json());
+    if (!Array.isArray(body.projects))
+        throw new Error('its answer had no project list');
+    return body.projects;
+}
+function plural(n, noun) {
+    return `${n} ${noun}${n === 1 ? '' : 's'}`;
+}
+/**
+ * The `status` block for one hub. Projects with no live session stay listed as
+ * offline: the hub still serves their last snapshot.
+ */
+export function formatDashboardStatus(d, projects) {
+    const sessionCount = projects.reduce((sum, p) => sum + p.sessions.length, 0);
+    const lines = [`Dashboard running at ${d.url} (pid ${d.pid}).`, `Sessions: ${sessionCount}`];
+    if (projects.length === 0) {
+        lines.push('Projects: none');
+        return lines;
+    }
+    lines.push(`Projects: ${projects.length}`);
+    const counts = projects.map((p) => (p.sessions.length === 0 ? 'offline' : plural(p.sessions.length, 'session')));
+    const nameWidth = Math.max(...projects.map((p) => p.name.length));
+    const countWidth = Math.max(...counts.map((c) => c.length));
+    projects.forEach((p, i) => {
+        // Root last: two projects can share a directory name, and the root is what
+        // tells them apart.
+        lines.push(`  ${p.name.padEnd(nameWidth)}  ${counts[i].padEnd(countWidth)}  ${p.root}`);
+    });
+    return lines;
+}
+/** `tospec dashboard status`: whether a hub runs, and the sessions it serves. */
+export async function dashboardStatusCommand() {
+    const running = await listDashboards();
+    if (running.length === 0) {
+        console.log('Dashboard is not running.');
+        console.log('Start it with: tospec dashboard start');
+        return;
+    }
+    for (const [i, d] of running.entries()) {
+        if (i > 0)
+            console.log('');
+        let projects;
+        try {
+            projects = await fetchHubProjects(d);
+        }
+        catch (err) {
+            // The process is alive but not answering: still binding, wedged, or a
+            // reused pid that is not a hub at all. Saying "running" would claim the
+            // one thing this could not confirm.
+            const reason = err instanceof Error ? err.message : String(err);
+            console.error(`Error: Dashboard process ${d.pid} is registered at ${d.url} but did not answer: ${reason}.`);
+            console.error('Fix: Retry in a moment; if it still does not answer, run tospec dashboard stop, then tospec dashboard start.');
+            process.exitCode = 1;
+            continue;
+        }
+        for (const line of formatDashboardStatus(d, projects))
+            console.log(line);
+    }
+}
+/**
+ * `tospec dashboard serve` (hidden), the process `start` spawns: starts the
+ * hub, records it, prints the URL, and stays up until terminated.
  */
-export async function runDashboard(projectRoot, opts = {}) {
-    const used = await reapAndCollectPorts();
-    let start = opts.port ?? DEFAULT_PORT;
-    while (used.has(start))
-        start++;
-    const { server, url, port } = await startDashboardServer(projectRoot, { ...opts, port: start });
+export async function runDashboard(opts = {}) {
+    const started = await startDashboardServer(opts);
+    const { url, port } = started;
+    // Recorded before the readiness line, so a `status` right after `start`
+    // returns already sees it.
+    try {
+        await registerDashboard(process.pid, port, url);
+    }
+    catch (err) {
+        await started.close();
+        throw err;
+    }
     console.log(`Dashboard running at ${url} (Ctrl+C to stop)`);
+    console.log('Claude Code sessions in tospec projects register through the tospec-dashboard mod.');
     // Detached child only: `detachDashboard` waits on stderr for exactly this line
-    // before it reports anything. A foreground run has no parent watching.
-    if (process.env.TOSPEC_DASHBOARD_PIDFILE) {
+    // before it reports anything. A `serve` run by hand has no parent watching.
+    if (process.env[DETACHED_ENV]) {
         // The parent closes its end of this pipe once it reads the line below and
-        // then exits, so every later stderr write (a config warning on
-        // /api/activity, a failed --open) hits EPIPE. Unhandled, that error killed
-        // the background dashboard a few writes in; handled, the writes are dropped.
+        // then exits, so every later stderr write hits EPIPE. Unhandled, that error
+        // killed the background dashboard a few writes in; handled, the writes are
+        // dropped.
         process.stderr.on('error', () => { });
         console.error(`${LISTENING_PREFIX}${url}`);
     }
-    await registerDashboard(process.pid, port, path.resolve(projectRoot));
-    // Every dashboard records itself, foreground included: `--detach` can only
-    // refuse for one that left a record, and a registry marker alone can be
-    // reaped out from under a live server. The child is handed its parent's path
-    // so the two cannot disagree about where the file lives.
-    const pidFile = process.env.TOSPEC_DASHBOARD_PIDFILE ?? pidFilePath(projectRoot);
-    await writePidRecord(pidFile, {
-        pid: process.pid,
-        port,
-        url,
-        projectRoot: path.resolve(projectRoot),
-    });
     if (opts.open) {
         openBrowser(url);
     }
-    // Normal termination removes this dashboard's own records. Windows hard-kills
-    // on `--stop`, so there `stopRunningDashboard` clears them instead.
+    // Normal termination removes this dashboard's marker. Windows hard-kills on
+    // `stop`, so there `stopRunningDashboard` clears it instead.
     const cleanup = () => {
-        // SSE keep-alive sockets would otherwise block close() from ever draining.
-        server.closeAllConnections?.();
-        // Sync, like clearPidRecordOwnedBy: fired and forgotten, the async
-        // readdir + rm could lose the race with process.exit, and a marker
-        // outliving its process reads as alive again once the OS reuses the pid —
-        // which `--stop` would then kill.
+        // Sync: fired and forgotten, the async readdir + rm could lose the race
+        // with process.exit, and a marker outliving its process reads as alive
+        // again once the OS reuses the pid — which `stop` would then kill.
         unregisterDashboardSync(process.pid);
-        clearPidRecordOwnedBy(pidFile, process.pid);
-        server.close(() => process.exit(0));
+        void started.close().then(() => process.exit(0));
     };
     process.on('SIGINT', cleanup);
     process.on('SIGTERM', cleanup);
-    return server;
+    return started;
 }
 //# sourceMappingURL=dashboard.js.map