@seanmars/tospec 0.19.0-beta.8 → 0.20.0

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';
@@ -20,50 +15,30 @@ 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 { acceptsAnyHostHeader, assertBindableHost, isAllowedHostHeader, listenFrom, openBrowser, packageAssetsDir, sendJson, serveAsset, } from '../core/local-server.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';
-// The detached child's readiness signal: `runDashboard` writes this to its own
-// stderr once it has actually bound, and only when TOSPEC_DASHBOARD_PIDFILE
-// marks it as a `--detach` child — a normal foreground run never emits it.
+// 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: ` from text a child process already formatted for
- * display, so re-wrapping it does not stack a second prefix. Only the first
- * line is considered — a message whose body legitimately mentions "Error:"
- * further in keeps it.
- */
+/** Drops one leading `Error: ` the child added, so wrapping doesn't stack prefixes. */
 function stripErrorPrefix(text) {
     return text.replace(/^Error:\s*/, '');
 }
-// How long `--detach` waits for that signal. The child emits it immediately
-// after binding, before the registry write and any browser launch, so anything
-// slower than a cold Node start plus a bind means it is stuck, not busy.
+// 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
-// -----------------------------------------------------------------------------
 /**
  * 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` arrives encoded and `decodeURIComponent` turns
- * it back into `../../` — after every URL-level normalization has run and
- * immediately before the caller joins it onto a directory. Without the check, a
- * 200 vs 404 split was an existence oracle over arbitrary directories, and a hit
- * returned that directory read as a change.
- *
- * Malformed escapes (`%zz`) throw `URIError`; that is the client's mistake, so
- * it answers 400 rather than unwinding to the router's outer catch as a 500.
- *
- * Extracted because `handleChangeDetail` and `handleSpec` each carried their own
- * copy and a comment claiming they were "deliberately identical" — by which
- * point only one of them guarded the decode. One implementation is what keeps
- * that claim true; `label` is the only thing that legitimately differs.
+ * 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;
@@ -108,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;
@@ -142,16 +117,11 @@ function resolveTospecFile(projectRoot, file, prefix) {
         return null;
     return resolved;
 }
-/** The directory holding archived changes, one level below `tospec/changes/`. */
 const ARCHIVE_SEGMENT = 'archive';
 /**
- * True for a path inside `tospec/changes/archive/`. Archived changes are
- * immutable by definition, so this is a stronger statement than the sync gate
- * and does not depend on a `sync-report.md` being present or readable.
- *
- * Deliberately not folded into `resolveTospecFile`: `/api/render` shares that
- * helper and legitimately renders archived documents read-only. The rejection
- * belongs on the write path.
+ * 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, '/');
@@ -159,13 +129,9 @@ function isArchivedChangePath(projectRoot, resolvedAbsPath) {
     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".
- *
- * An archived change is one level deeper (`changes/archive/<stamp>-<name>/`), so
- * `parts[2]` there is the literal string `archive` — a directory, not a change.
- * Returning null keeps any future caller from re-deriving that as a change name.
+ * 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, '/');
@@ -177,12 +143,9 @@ function changeNameFromTaskFile(projectRoot, resolvedAbsPath) {
     return parts[2] || null;
 }
 /**
- * Renders a tospec markdown file to HTML.
- *
- * The markup goes through `renderMarkdownSafe`, not `marked.parse`: the client
- * assigns this with `innerHTML`, so anything the renderer passes through runs
- * in the dashboard's origin — inside the CSRF boundary that `handleTaskUpdate`
- * relies on. See `core/markdown-render.ts`.
+ * 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) {
@@ -218,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'] ?? '')) {
@@ -249,30 +210,47 @@ async function handleTaskUpdate(projectRoot, req, res) {
     if (!resolved) {
         return sendJson(res, 403, { error: 'forbidden' });
     }
-    // Archived changes are frozen outright, before the sync gate: that gate asks
-    // whether a change is *becoming* immutable, and an archived one already is.
+    // 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' });
     }
-    // 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.
+    // 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, from the same 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 — including proposal.md and design.md,
-        // the records this whole workflow exists to keep. The dashboard never
-        // offered those edits and never showed them afterwards either: `/api/task`
-        // reports progress from `resolveTaskFiles` alone, so a write outside it
-        // left no trace anywhere in the UI.
+        // 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(path.resolve(resolved))) {
+        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`,
             });
@@ -283,8 +261,7 @@ async function handleTaskUpdate(projectRoot, req, res) {
     }
     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))
@@ -293,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',
@@ -307,27 +280,18 @@ 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
-// -----------------------------------------------------------------------------
 /**
  * Second layer behind `renderMarkdownSafe`, applied to every response.
  *
- * `script-src 'self'` is the load-bearing directive: it refuses inline event
- * handlers and `javascript:` URLs, which is what a markdown file would have to
- * smuggle in to reach `POST /api/task` from inside this origin. Escaping in the
- * renderer already stops that; this catches anything a future renderer change
- * lets through.
- *
- * `style-src` keeps `'unsafe-inline'` deliberately — Chart.js writes inline
- * styles, and a style injection cannot call the write endpoint, so tightening
- * it would trade a working dashboard for no security.
+ * `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', [
@@ -336,7 +300,6 @@ function applyContentSecurityPolicy(res) {
         "style-src 'self' 'unsafe-inline'",
         "img-src 'self' data:",
         "font-src 'self'",
-        // EventSource on /api/events and every fetch of /api/*.
         "connect-src 'self'",
         "base-uri 'none'",
         "form-action 'none'",
@@ -360,8 +323,10 @@ async function handleRequest(projectRoot, req, res, clients, boundHost, acceptAn
         }
         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));
         }
@@ -393,21 +358,14 @@ async function handleRequest(projectRoot, req, res, clients, boundHost, acceptAn
         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, 'Pass --allow-remote to accept that risk.');
-    // Resolved once here so the Host-header policy has a single home, rather than
-    // each request re-deriving it from two separate inputs.
     const acceptAnyHost = acceptsAnyHostHeader(host, opts.allowRemote);
     const clients = new Set();
     const server = http.createServer((req, res) => {
@@ -416,14 +374,13 @@ export async function startDashboardServer(projectRoot, opts = {}) {
     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).
- * Limitation: 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');
@@ -443,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 {
@@ -471,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 {
@@ -487,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.
- *
- * 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.
+ * 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 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 {
@@ -521,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. */
@@ -531,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));
     }
@@ -540,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();
@@ -567,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;
         }
@@ -586,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}`;
@@ -595,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;
@@ -607,11 +543,9 @@ export class DashboardStopError extends Error {
     }
 }
 /**
- * The detached child neither reported itself listening nor exited. Distinct
- * from an early-exit failure: the child may well still be coming up, so the
- * message says what was not observed rather than claiming a startup failure,
- * and points at `--list`, which can still find it via the record the child
- * writes for itself.
+ * 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;
@@ -629,14 +563,12 @@ export class DashboardReadinessTimeoutError 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.
+ * 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.
@@ -650,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;
@@ -671,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() {
@@ -702,59 +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. Re-runs this same
- * CLI without `--detach` (the child is the actual server), then waits for the
- * child's own `LISTENING` report before doing anything else, so the URL it
- * prints is one the child actually bound — including after an EADDRINUSE
- * fallback moved it off the port this process predicted. Order is therefore:
- * spawn → wait for the child's report → write the PID record → print the URL.
+ * 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, 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.
+ * 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).
  *
- * Both this process and the child write that PID record, with identical fields
- * by construction. They are not redundant — each is the only record that exists
- * in one failure mode:
- *   - The child's (`runDashboard`) is the record *every* dashboard writes for
- *     itself, foreground included, and is all that remains if this process is
- *     killed mid-handshake or gives up on the readiness timeout.
- *   - This one is what makes a record exist by the time the call returns. The
- *     child writes its own only *after* it has signalled, so without this a
- *     rapid second `--detach` could find nothing to refuse against, and a child
- *     that wedges after binding would be an untrackable orphan.
- * Both use `fs.writeFile`, so a concurrent truncate-then-write is two processes
- * laying down the same bytes; a reader that catches it mid-write falls back to
- * the registry marker (`readPidRecord` returns null on a parse failure).
+ * 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))
@@ -767,41 +676,32 @@ export async function detachDashboard(projectRoot, cliEntry, opts) {
         args.push('--allow-remote');
     const child = spawn(process.execPath, args, {
         detached: true,
-        // stderr is piped so the parent can wait for the child's own report of
-        // success (LISTENING) or read its error text on an early exit — see
-        // waitForListening. stdout stays ignored; it is human text for a
-        // foreground run, not this handshake's concern.
+        // 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 },
     });
-    // 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.');
     }
-    // Wait for the child to actually confirm it is listening before reporting
-    // anything: everything that can go wrong after a successful spawn — the
-    // --allow-remote refusal, EADDRINUSE, a permission error — happens inside
-    // the child and was previously unobservable behind stdio: 'ignore'.
+    // 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 after the
-        // error has already been reported.
+        // un-unref'd handle would keep this process's event loop alive.
         child.unref();
     }
-    // The child writes this same record for itself (see the docstring for why
-    // both writers are kept); these fields are derived from the URL it reported,
-    // so the two agree whichever lands last.
-    //
-    // Limitation: 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.
+    // 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,
@@ -817,16 +717,13 @@ function portFromUrl(url) {
     return match ? Number(match[1]) : null;
 }
 /**
- * Races the child's own outcome: resolves with the confirmed URL once it
- * reports `LISTENING <url>` on stderr, rejects with the child's captured stderr
- * (or a fallback message) if it exits first, and rejects on timeout if it does
- * neither. Closes the stderr pipe once settled so an unref'd, still-running
- * child cannot keep this process's event loop alive on our end of it.
+ * 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 the third outcome, not a nicety: `LISTENING` and `exit` do not
- * cover a child that binds and then wedges, nor one whose readiness line stops
- * being emitted — and with only those two listeners either case left
- * `tospec dashboard --detach` hanging with no output at all.
+ * 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) => {
@@ -855,11 +752,8 @@ function waitForListening(child, timeoutMs = READINESS_TIMEOUT_MS) {
             settled = true;
             cleanup();
             reject(new Error(
-            // The child already formatted its failure as `Error: <message>` on
-            // stderr. Carrying that prefix into a new Error made the parent's own
-            // `Error: ` formatter print it twice, so the same refusal read as
-            // "Error: Error: Refusing to bind..." under --detach and correctly in
-            // the foreground. Strip the child's prefix, not the parent's.
+            // 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}).`));
         };
@@ -881,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)
@@ -899,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) {
-    // Limitation: 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.
  *
- * Limitation: 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();
@@ -956,19 +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: this is `detachDashboard`'s readiness handshake — its
-    // parent is waiting on stderr for exactly this line before it reports
-    // anything. A direct foreground run has no parent watching, so it stays quiet.
+    // 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,
@@ -979,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?.();