@seanmars/tospec 0.19.0-beta.1 → 0.19.0-beta.13

package/dist/commands/dashboard.js

@@ -1,13 +1,8 @@
 /**
- * `tospec dashboard` — local web dashboard.
- *
- * A `node:http` server (no web framework) that serves the static frontend from
- * `assets/dashboard/` and exposes JSON APIs backed by the pure aggregation
- * functions in `core/dashboard-data.ts`. Reads are GET-only; the sole write is
- * `POST /api/task`, which ticks a task checkbox back into its markdown file.
- * Both file-addressing endpoints (`/api/render`, `/api/task`) are trust
- * boundaries: the requested path must resolve under the tospec root (design
- * decision D5).
+ * `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).
  */
 import * as http from 'node:http';
 import { promises as fs, readFileSync, unlinkSync, watch } from 'node:fs';
@@ -15,40 +10,55 @@ 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 { marked } from 'marked';
 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 { getGlobalConfigDir } from '../core/global-config.js';
-import { assertBindableHost, isAllowedHostHeader, listenFrom, openBrowser, packageAssetsDir, sendJson, serveAsset, } from '../core/local-server.js';
-import { setTaskDone } from '../utils/task-progress.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;
 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.
+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*/, '');
+}
+// 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;
 /** This command's shipped frontend; `serveAsset` is confined to it. */
 const ASSETS_DIR = packageAssetsDir('dashboard');
-// -----------------------------------------------------------------------------
-// API handlers
-// -----------------------------------------------------------------------------
-async function handleChangeDetail(projectRoot, rawName, res) {
-    // The same check handleSpec applies, deliberately identical. WHATWG URL
-    // normalizes a literal `..` out of the pathname but does not percent-decode
-    // it, so `%2e%2e%2f` reaches here encoded and decodeURIComponent turns it back
-    // into `../../` — after every URL-level normalization has already run and
-    // immediately before collectChangeDetail joins it onto the changes directory.
-    // Without this, a 200 vs 404 split was an existence oracle over arbitrary
-    // directories, and a hit returned that directory read as a change.
-    let name;
+/**
+ * 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 {
-        name = decodeURIComponent(rawName);
+        decoded = decodeURIComponent(raw);
     }
     catch {
-        // Malformed percent-encoding (`%zz`). The router's outer catch would report
-        // this as a 500; it is a bad request.
-        return sendJson(res, 400, { error: 'malformed change name' });
+        sendJson(res, 400, { error: `malformed ${label}` });
+        return null;
     }
-    if (!name || name.includes('/') || name.includes('\\') || name.includes('..')) {
-        return sendJson(res, 403, { error: 'forbidden' });
+    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));
     }
@@ -58,10 +68,9 @@ async function handleChangeDetail(projectRoot, rawName, res) {
     }
 }
 async function handleSpec(projectRoot, rawId, res) {
-    const id = decodeURIComponent(rawId);
-    if (!id || id.includes('/') || id.includes('\\') || id.includes('..')) {
-        return sendJson(res, 403, { error: 'forbidden' });
-    }
+    const id = decodePathSegment(rawId, 'spec id', res);
+    if (id === null)
+        return;
     const specPath = path.join(projectRoot, 'tospec', 'specs', id, 'spec.md');
     let content;
     try {
@@ -74,32 +83,32 @@ async function handleSpec(projectRoot, rawId, res) {
     sendJson(res, 200, { id, requirements: spec.requirements });
 }
 /**
- * Git activity + health signals (ADR 001). `change` narrows the tospec series
- * to one change's directory; the name feeds a `git log` path filter, so reject
- * anything that could escape `tospec/changes/` before it reaches git.
- * `days` widens the window: a day count (capped at 3650 to bound the
- * zero-filled series) or 'all' for the full history.
+ * 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' });
     }
-    const parsed = Number(daysParam);
-    const window = daysParam === 'all'
-        ? 'all'
-        : Number.isInteger(parsed) && parsed >= 1
-            ? Math.min(parsed, 3650)
-            : undefined; // absent or garbage → collectActivity's default
+    // 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. Both callers pass paths that
- * originate from our own API payloads, so anything else is an attack or a bug.
+ * under `<root>/<prefix>`, or null when it escapes.
  */
 function resolveTospecFile(projectRoot, file, prefix) {
-    // Windows-safe: normalise backslashes before resolving.
     const resolved = path.resolve(projectRoot, file.replace(/\\/g, '/'));
     if (!resolved.startsWith(path.resolve(projectRoot) + path.sep))
         return null;
@@ -108,19 +117,36 @@ function resolveTospecFile(projectRoot, file, prefix) {
         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 back to its change name, expecting the shape
- * `tospec/changes/<name>/...`. Returns null when the path doesn't match, so
- * callers treat "no change" as "not archiving".
+ * 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 a tospec markdown file to HTML. */
+/**
+ * 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' });
@@ -136,7 +162,7 @@ async function handleRender(projectRoot, fileParam, res) {
     catch {
         return sendJson(res, 404, { error: 'not found' });
     }
-    const html = await marked.parse(content);
+    const html = await renderMarkdownSafe(content);
     sendJson(res, 200, { html });
 }
 /** Reads a JSON request body, capped so a stray client can't exhaust memory. */
@@ -155,14 +181,12 @@ async function readJsonBody(req, limit = 8192) {
     }
 }
 /**
- * Ticks a task checkbox in its markdown file: `{ file, line, done }`, where
- * `file` is a root-relative path from `/api/overview` and `line` its 1-based
- * line. Writes are confined to `<root>/tospec/changes/`, so the dashboard can
- * never edit specs or anything outside the tospec tree.
+ * 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, not cosmetic: it
- * pushes any cross-origin POST into a CORS preflight that this server does not
- * answer, so a random web page cannot drive the loopback dashboard.
+ * 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'] ?? '')) {
@@ -186,23 +210,58 @@ async function handleTaskUpdate(projectRoot, req, res) {
     if (!resolved) {
         return sendJson(res, 403, { error: 'forbidden' });
     }
-    // Freeze task edits once a change is archiving (sync certified). The
-    // frontend disable is only UX; this server-side gate is what actually protects
-    // the certified content from a raw POST. A read error → null → not blocked.
+    // 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;
+    }
+    // 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 changeName = changeNameFromTaskFile(projectRoot, resolved);
     if (changeName) {
         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);
-        // 'not a task' means the client's view of the file is stale; ENOENT means it
-        // is gone. Neither is a server fault, so don't 500.
+        // 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))
@@ -211,10 +270,6 @@ async function handleTaskUpdate(projectRoot, req, res) {
     }
     sendJson(res, 200, { file, line, done });
 }
-// -----------------------------------------------------------------------------
-// Live updates (SSE)
-// -----------------------------------------------------------------------------
-/** Registers an SSE client and streams `change` events until it disconnects. */
 function handleEvents(req, res, clients) {
     res.writeHead(200, {
         'content-type': 'text/event-stream',
@@ -225,21 +280,39 @@ function handleEvents(req, res, clients) {
     clients.add(res);
     req.on('close', () => clients.delete(res));
 }
-/** Pushes a `change` event to every connected SSE client. */
 function broadcastChange(clients) {
     for (const client of clients) {
         client.write('event: change\ndata: {}\n\n');
     }
 }
-// -----------------------------------------------------------------------------
-// Router
-// -----------------------------------------------------------------------------
-async function handleRequest(projectRoot, req, res, clients, boundHost) {
+/**
+ * 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.
+ */
+function applyContentSecurityPolicy(res) {
+    res.setHeader('content-security-policy', [
+        "default-src 'none'",
+        "script-src 'self'",
+        "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' data:",
+        "font-src 'self'",
+        "connect-src 'self'",
+        "base-uri 'none'",
+        "form-action 'none'",
+        "frame-ancestors 'none'",
+    ].join('; '));
+}
+async function handleRequest(projectRoot, req, res, clients, boundHost, acceptAnyHost) {
     try {
         // Host allowlist runs before any route (DNS-rebinding guard).
-        if (!isAllowedHostHeader(req.headers.host, boundHost)) {
+        if (!isAllowedHostHeader(req.headers.host, boundHost, acceptAnyHost)) {
             return sendJson(res, 403, { error: 'forbidden host' });
         }
+        applyContentSecurityPolicy(res);
         const url = new URL(req.url ?? '/', 'http://localhost');
         const pathname = url.pathname;
         if (req.method === 'POST' && pathname === '/api/task') {
@@ -250,8 +323,10 @@ async function handleRequest(projectRoot, req, res, clients, boundHost) {
         }
         if (pathname === '/api/events')
             return handleEvents(req, res, clients);
-        if (pathname === '/')
+        // `/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');
+        }
         if (pathname.startsWith('/assets/')) {
             return await serveAsset(res, ASSETS_DIR, pathname.slice('/assets/'.length));
         }
@@ -283,34 +358,29 @@ async function handleRequest(projectRoot, req, res, clients, boundHost) {
         sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
     }
 }
-// -----------------------------------------------------------------------------
-// Lifecycle
-// -----------------------------------------------------------------------------
 /**
- * Starts the dashboard HTTP server, binding at `opts.port` and advancing to the
- * next port on `EADDRINUSE` until one is free (D6) — so dashboards for different
- * projects coexist. `port: 0` asks the OS for a random port and never conflicts.
- * Returns the server, its URL, and the actual port. Side-effect free (no
- * logging, no signal handlers, no registry) so tests can drive it directly.
+ * 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.
  */
 export async function startDashboardServer(projectRoot, opts = {}) {
     const host = opts.host ?? DEFAULT_HOST;
-    assertBindableHost(host, 'dashboard', opts.allowRemote);
+    assertBindableHost(host, 'dashboard', opts.allowRemote, 'Pass --allow-remote to accept that risk.');
+    const acceptAnyHost = acceptsAnyHostHeader(host, opts.allowRemote);
     const clients = new Set();
     const server = http.createServer((req, res) => {
-        void handleRequest(projectRoot, req, res, clients, host);
+        void handleRequest(projectRoot, 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: `http://${host}:${actualPort}`, port: actualPort };
+    return { server, url: connectableUrl(host, actualPort), port: actualPort };
 }
 /**
- * Watches `<root>/tospec` recursively and calls `onChange` (debounced) on any
- * edit. `fs.watch` uses OS change notifications, so it never opens or locks the
- * watched files — agents and users stay free to edit or delete them (D2).
- * Returns null if the directory can't be watched (e.g. missing).
- * ponytail: recursive watch; native on win32/macOS, Node 20+ on Linux.
+ * 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');
@@ -330,22 +400,19 @@ function watchTospec(projectRoot, onChange) {
     }
 }
 /**
- * PID-file location for a project's dashboard, keyed by the project root so one
- * dashboard is tracked per project. Lives in the OS temp dir (not the repo) so
- * it never gets committed; `--detach` and `--stop` both derive the same path.
+ * 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`);
 }
-/** True if a process with this PID currently exists (signal 0 probes without killing). */
+/** True if a process with this PID exists (signal 0 probes without killing). */
 function isProcessAlive(pid) {
-    // Guard the whole module here, where every record's pid arrives: on POSIX
-    // `kill(0, sig)` signals our own process group and `kill(-n, sig)` a named
-    // one, so a record carrying 0 or a negative pid — which nothing we write ever
-    // does, but a corrupt or planted file in the shared temp dir could — would
-    // make `--stop` terminate the user's own shell. Treated as not alive, so such
-    // a record is reaped instead of ever reaching `process.kill`.
+    // 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.
     if (!Number.isInteger(pid) || pid <= 0)
         return false;
     try {
@@ -358,11 +425,8 @@ function isProcessAlive(pid) {
     }
 }
 /**
- * Reads this project's dashboard PID record, or null if absent or corrupt.
- * The pid is what identifies the record, so it is the only field required here —
- * a truncated record still names a process to reap. Callers that need to reach
- * the dashboard check `port` themselves — see `shouldRefuseDetach` for why that
- * matters to `--detach`.
+ * 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 {
@@ -374,32 +438,23 @@ async function readPidRecord(pidFile) {
     }
 }
 /**
- * Records this dashboard so `--stop` can find it. Reads are lenient about the
- * optional fields (pre-0.13 records lack them); writes are not, since recording
- * the root is what lets a scanned record be attributed to its project.
+ * 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 if it still names `pid`, so neither caller deletes a
- * record describing a different dashboard.
+ * 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.
  *
- * The path is keyed by project, not by process, and nothing guards a second
- * foreground start — so two dashboards for one project share this file. Both
- * places that clear it (a dashboard's own exit, and `--stop` once it has killed
- * one) would otherwise delete whichever record happened to be there.
- *
- * ponytail: one record per project, so of two sibling dashboards only the later
- * writer is tracked by pid file at all. This keeps the tracked one from being
- * deleted by the other's exit; it cannot hand the earlier dashboard a record
- * back. Both stay reachable through their registry markers, which is what the
- * guard reads. Per-process pid files only if a second foreground start ever
- * becomes something we support. The read and the delete are also not one atomic
- * step, so this is best-effort like every other tidy-up here.
+ * 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 — which is why it does not reuse the async `readPidRecord`.
+ * races — hence not reusing the async `readPidRecord`.
  */
 export function clearPidRecordOwnedBy(pidFile, pid) {
     try {
@@ -408,9 +463,8 @@ export function clearPidRecordOwnedBy(pidFile, pid) {
             unlinkSync(pidFile);
     }
     catch {
-        // Absent or already gone: nothing to do. Corrupt: left alone deliberately —
-        // it names no process, so no command mistakes it for a dashboard, and a
-        // half-written record could still belong to one that is starting up.
+        // 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. */
@@ -418,7 +472,7 @@ async function pidFilePaths() {
     const dir = os.tmpdir();
     try {
         return (await fs.readdir(dir))
-            // Exactly the shape pidFilePath() generates — never a wider set than we write.
+            // 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));
     }
@@ -427,15 +481,13 @@ async function pidFilePaths() {
     }
 }
 function registryDir() {
-    // Derived, not assembled: config, schema overrides and these markers all hang
-    // off the one resolver, so relocating the config directory moves the registry
-    // with it instead of leaving the two in different trees.
+    // Derived from the one config resolver, so relocating the config directory
+    // moves the registry with it.
     return path.join(getGlobalConfigDir(), 'dashboards');
 }
 /**
- * Lists live dashboards, reaping any marker whose process has died along the
- * way. Each marker is named `{pid}_{port}` and holds its project root as
- * content. A missing/unreadable dir → no dashboards running. Sorted by port.
+ * Lists live dashboards sorted by port, reaping any marker whose process has
+ * died. A missing or unreadable dir means no dashboards are running.
  */
 export async function listDashboards() {
     const dir = registryDir();
@@ -454,9 +506,8 @@ export async function listDashboards() {
         const pid = Number(m[1]);
         const file = path.join(dir, name);
         if (!isProcessAlive(pid)) {
-            // Best-effort, like every other record tidy-up here: `force` only swallows
-            // ENOENT, and failing to unlink one stale marker must not take down the
-            // command that merely wanted to list what is running.
+            // Best-effort: failing to unlink one stale marker must not take down a
+            // command that only wanted to list.
             await fs.rm(file, { force: true }).catch(() => { });
             continue;
         }
@@ -473,8 +524,7 @@ export async function listDashboards() {
 }
 /**
  * One line describing a running dashboard, for `--list` and `--stop`'s picker.
- * The URL assumes the default loopback host — `RunningDashboard` doesn't record
- * the host a `--allow-remote` dashboard was bound to.
+ * The URL assumes loopback — `RunningDashboard` doesn't record the bound host.
  */
 export function formatRunningDashboard(d, sep = '\t') {
     const url = `http://${DEFAULT_HOST}:${d.port}`;
@@ -482,8 +532,7 @@ export function formatRunningDashboard(d, sep = '\t') {
 }
 /**
  * `--stop` found dashboards but cannot ask which to stop (no terminal). Carries
- * its own diagnostic so the shared failure sink renders it, like
- * `RootSelectionError` and `ArchiveBlockedError`.
+ * its own diagnostic so the shared failure sink renders it.
  */
 export class DashboardStopError extends Error {
     diagnostic;
@@ -494,14 +543,32 @@ export class DashboardStopError extends Error {
     }
 }
 /**
- * Every dashboard `--stop` can reach: the registry union every project's pid
- * file, keyed by pid, reaping any record whose process has died along the way.
+ * 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 correctly. Scanning every pid file rather
- * than only this project's is what makes that reachable from any directory,
- * which is the case `--stop`'s pick-from-all list exists for.
+ * while its pid file still names it.
  *
  * `ownRootHint` names records written before pid files carried their own root;
  * it never restricts the result.
@@ -515,14 +582,10 @@ export async function collectStoppableDashboards(ownRootHint) {
         const rec = await readPidRecord(file);
         if (!rec)
             continue;
-        // Reap like the marker reaper does. A record left by a crashed dashboard
-        // would otherwise sit in the temp dir forever, and once the OS recycled its
-        // pid it would read as alive again — a phantom dashboard, attributed to a
-        // real project, that `--stop` would kill an unrelated process for.
-        //
-        // Tidying is best-effort: `force` only swallows ENOENT, and the temp dir is
-        // shared between users on POSIX, so another user's stale file would fail to
-        // unlink. Losing that race must not take the whole command down with it.
+        // 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;
@@ -536,15 +599,15 @@ export async function collectStoppableDashboards(ownRootHint) {
             byPid.set(rec.pid, { pid: rec.pid, port: rec.port, projectRoot: root });
             continue;
         }
-        // A registry marker can be content-less; the pid file may know the root, and
-        // without it this dashboard would never match the project it belongs to.
+        // 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 (reaps dead markers as a side effect). Runs at
+ * 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() {
@@ -567,45 +630,40 @@ async function unregisterDashboard(pid) {
     }
     await Promise.all(names
         .filter((n) => n.startsWith(`${pid}_`))
-        // Best-effort: a marker we cannot unlink must not abort the stop loop and
-        // leave the dashboards after this one running.
+        // Best-effort: a marker we cannot unlink must not abort the stop loop.
         .map((n) => fs.rm(path.join(dir, n), { force: true }).catch(() => { })));
 }
 /**
- * Launches the dashboard as a detached background process and returns
- * immediately. Re-runs this same CLI without `--detach` (the child is the
- * actual server); the child rewrites the PID file once it knows the real URL,
- * so an EADDRINUSE port fallback is still recorded correctly.
+ * 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).
  *
- * Refuses if any live dashboard already serves this project, foreground or
- * background, rather than spawning a second orphaned server. The guard asks the
- * shared candidate set rather than this project's pid file alone, because
- * either record can be the only one left: a foreground dashboard used to write
- * no pid file at all, and a background one can lose the one it wrote. Both made
- * the old guard see nothing and spawn a second server. The PID is written
- * before this returns, so a rapid second `--detach` sees it even before the
- * child has bound (the child writes late).
+ * 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.
  *
  * This is the only guarded start path: nothing stops a second foreground
- * `tospec dashboard`, so "one dashboard per project" holds for `--detach` and
- * not as a machine-wide invariant.
+ * `tospec dashboard`, so "one dashboard per project" is not machine-wide.
  */
 export async function detachDashboard(projectRoot, cliEntry, opts) {
     const pidFile = pidFilePath(projectRoot);
-    // Reaps every dead record along the way, including the stale pid file a
-    // crashed dashboard of this project left behind.
     const running = shouldRefuseDetach(await collectStoppableDashboards(projectRoot), projectRoot);
     if (running) {
-        // Same fields as `--list`, same separator as `--stop`'s picker, so the
-        // dashboard named here is recognisably the row those commands show.
+        // 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');
         return;
     }
-    // Pick the likely port up front (reaping dead markers) so the message and
-    // provisional record are accurate. The child re-checks and binds, so a race
-    // that grabs this port between now and then just shifts the child upward.
+    // Predict the port so the message and provisional record are accurate. The
+    // child re-checks and binds, so a race for this port just shifts it upward.
     const used = await reapAndCollectPorts();
     let port = opts.port;
     while (used.has(port))
@@ -618,29 +676,98 @@ export async function detachDashboard(projectRoot, cliEntry, opts) {
         args.push('--allow-remote');
     const child = spawn(process.execPath, args, {
         detached: true,
-        stdio: 'ignore',
+        // stderr is piped so the parent can read the child's LISTENING report or
+        // its error text on an early exit (waitForListening).
+        stdio: ['ignore', 'ignore', 'pipe'],
         // On Windows, detached: true otherwise pops a new console window.
         windowsHide: true,
         env: { ...process.env, TOSPEC_DASHBOARD_PIDFILE: pidFile },
     });
-    child.unref();
-    // No pid means the spawn itself failed; say so rather than report success and
-    // leave behind a record `--stop` could never use.
+    // No pid means the spawn itself failed; reporting success would leave a record
+    // `--stop` could never use.
     if (child.pid === undefined) {
         throw new Error('Could not start the background dashboard process.');
     }
-    // ponytail: no cross-process lock; two --detach in the same instant could
-    // still both pass the guard. A human running the command twice is sequential,
-    // so this synchronous write is enough — add a lockfile only if that changes.
+    // 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);
+    }
+    finally {
+        // Unconditional: on the timeout path the child is still running, and an
+        // 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,
-        url,
+        port: portFromUrl(confirmedUrl) ?? port,
+        url: confirmedUrl,
         projectRoot: path.resolve(projectRoot),
     });
-    console.log(`Dashboard starting in background at ${url}`);
+    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;
+}
+/**
+ * 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) => {
+        let stderr = '';
+        let settled = false;
+        let timer;
+        const cleanup = () => {
+            if (timer)
+                clearTimeout(timer);
+            child.stderr?.removeListener('data', onData);
+            child.removeListener('exit', onExit);
+            child.stderr?.destroy();
+        };
+        const onData = (chunk) => {
+            stderr += chunk.toString();
+            const line = stderr.split('\n').find((l) => l.startsWith(LISTENING_PREFIX));
+            if (line && !settled) {
+                settled = true;
+                cleanup();
+                resolve(line.slice(LISTENING_PREFIX.length).trim());
+            }
+        };
+        const onExit = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(new Error(
+            // The child already formatted its failure as `Error: <message>`;
+            // carrying that through made the parent print "Error: Error: ...".
+            stripErrorPrefix(stderr.trim()) ||
+                `The background dashboard process exited before it started listening (code ${code}).`));
+        };
+        child.stderr?.on('data', onData);
+        child.on('exit', onExit);
+        timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(new DashboardReadinessTimeoutError(timeoutMs));
+        }, timeoutMs);
+    });
+}
 /** Case-correct path equality (the Windows filesystem is case-insensitive). */
 export function samePath(a, b) {
     const na = path.resolve(a);
@@ -648,12 +775,9 @@ export function samePath(a, b) {
     return process.platform === 'win32' ? na.toLowerCase() === nb.toLowerCase() : na === nb;
 }
 /**
- * The dashboards `--stop` may terminate without asking. Empty means "nothing
- * here is mine" — 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 silently claim it. Pure, so this is testable
- * without touching the registry.
+ * 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)
@@ -666,55 +790,46 @@ export function selectStopTargets(candidates, projectRoot) {
  * `tospec/decisions/20260727_232950-one-dashboard-per-project.md`.
  *
  * Deliberately the same question `--stop` asks, over the same candidate set, so
- * the two commands can never disagree about what is running. That also settles
- * the record `--stop` cannot reach: a live but truncated record carries no port,
- * so `collectStoppableDashboards` drops it and it never blocks a start it could
- * not tell the user how to unblock.
+ * the two can never disagree about what is running.
  */
 export function shouldRefuseDetach(candidates, projectRoot) {
-    // ponytail: names the first match only, though `selectStopTargets` can return
-    // several (a project that already had two before this guard existed). One is
-    // enough to refuse and to point at; `--stop` still clears all of them.
+    // 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 is treated as
+ * 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 — on POSIX the
- * temp dir is shared, so a candidate can belong to another user. Reporting that
- * as stopped would be this ticket's own bug all over again, so we hand the
- * caller what actually happened and leave that dashboard's records alone.
+ * 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.
  *
- * ponytail: SIGTERM; on Windows Node maps this to TerminateProcess (hard kill),
- * so the target's own cleanup won't run — we clear its files here.
+ * Limitation: SIGTERM; Windows maps it to TerminateProcess (hard kill), so the
+ * target's own cleanup won't run — we clear its files here.
  */
 export async function stopRunningDashboard(d) {
     try {
         process.kill(d.pid);
     }
     catch (err) {
-        // ESRCH means it exited between listing and now: already stopped, so its
-        // records should still be cleared. Anything else (EPERM) is a real refusal.
+        // ESRCH means it exited between listing and now: already stopped, so still
+        // clear its records. 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. Same reason the exit path checks.
+    // 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,
- * optionally opens a browser, and stays up until terminated.
- *
- * Port allocation: reap dead registry markers, skip ports live dashboards hold
- * (so each project lands on its own port off the 5620 base), then bind — which
- * confirms the port and advances past any the registry didn't know about.
+ * 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.
  */
 export async function runDashboard(projectRoot, opts = {}) {
     const used = await reapAndCollectPorts();
@@ -723,13 +838,16 @@ export async function runDashboard(projectRoot, opts = {}) {
         start++;
     const { server, url, port } = await startDashboardServer(projectRoot, { ...opts, port: start });
     console.log(`Dashboard running at ${url} (Ctrl+C to stop)`);
+    // 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) {
+        console.error(`${LISTENING_PREFIX}${url}`);
+    }
     await registerDashboard(process.pid, port, path.resolve(projectRoot));
-    // Every dashboard records itself, foreground included — `--detach` can only
-    // refuse for a foreground dashboard if one leaves a record, and the registry
-    // marker alone can be reaped out from under a live server. `--detach`'s child
-    // is handed the path its parent already derived, so the two cannot disagree
-    // about the file's location even though the child re-resolves the root for
-    // the record's own contents.
+    // 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,
@@ -740,10 +858,8 @@ export async function runDashboard(projectRoot, opts = {}) {
     if (opts.open) {
         openBrowser(url);
     }
-    // Normal termination (Ctrl+C → SIGINT, `--stop` → SIGTERM on POSIX) removes
-    // this dashboard's own records. Windows hard-kills on `--stop` specifically,
-    // so this does not run for that path and stopRunningDashboard clears them
-    // instead; a dead one is reaped on next start either way.
+    // Normal termination removes this dashboard's own records. Windows hard-kills
+    // on `--stop`, so there `stopRunningDashboard` clears them instead.
     const cleanup = () => {
         // SSE keep-alive sockets would otherwise block close() from ever draining.
         server.closeAllConnections?.();