super-backlog 1.0.3 → 1.1.1

package/README.md

@@ -45,15 +45,14 @@ sbl init --models
 
 # Local install
 npm install super-backlog
-node ./node_modules/super-backlog/dist/cli.js init
+node ./node_modules/super-backlog/dist/bin.js init
 ```
 
 After installation:
 
 ```bash
 npm run board                   # open the Backlog.md kanban board
-sbl serve                       # dashboard server + Backlog browser with live reload
-sbl dashboard --serve             # live Project Dashboard on http://localhost:6428
+sbl dashboard                   # live Project Dashboard on http://localhost:6428
 ```
 
 `init` is idempotent — safe to re-run any time; re-running with a newer kit version is the upgrade path for all injected files.
@@ -74,7 +73,7 @@ sbl dashboard --serve             # live Project Dashboard on http://localhost:6
 | `dashboard.html` | generated Project Dashboard | not installed in user projects; generated on demand by `sbl dashboard` |
 | `.git/hooks/pre-commit` | integrity guard hook — only with `--guard` (opt-in) | appended marker block |
 
-Commands: `sbl init` · `sbl models` · `sbl doctor` · `sbl uninstall [--with-backlog]` · `sbl update` · `sbl dashboard [--port <n>] [--no-open]` · `sbl serve [--port <n>] [--no-open]`. See `sbl help` for every flag.
+Commands: `sbl init` · `sbl models` · `sbl doctor` · `sbl uninstall [--with-backlog]` · `sbl update` · `sbl dashboard [--port <n>] [--no-open]`. See `sbl help` for every flag.
 
 ## Model router (opt-in)
 
@@ -92,17 +91,17 @@ When enabled:
 
 - **OpenCode** — the plugin `sbl-model-router.js` rewrites `chat.params` for the `sbl-worker` (workhorse) and `sbl-worker-cheap` / `explore` (budget) agents.
 - **Claude Code** — agent files carry a `model:` placeholder that is updated by a `SessionStart` hook based on your current main model.
-- **Dashboard** — `sbl dashboard --serve` exposes `/api/models` and `/api/models/discover`.
+- **Dashboard** — `sbl dashboard` exposes `/api/models` and `/api/models/discover`.
 
 The router is fully owned by super-backlog and removed by `sbl uninstall`. See the [model router design](docs/superpowers/specs/2026-08-26-sbl-model-router-design.md) for details.
 
 ## Project Dashboard
 
-`sbl dashboard` starts a local server that serves a dark, HTS-style cockpit rendered from your Backlog data in seven sections — Board & Quick Actions, Status (donut), Milestones, Tasks (sortable/filterable table; click a row to open a modal detail view with acceptance criteria and dependencies), Feature Cycle (pipeline stepper plus an Up Next / Blocked flow view from task dependencies), Activity (30-day sparkline), and Decisions & Docs. Glossary tooltips explain domain terms inline; extend or override them project-wide via `backlog/docs/glossary.md` (`## Term` heading plus the text below it). No CDNs, no external fonts — works offline when served locally. The server watches `backlog/`, regenerates on change, and serves on port `6428`; connected browser tabs reload automatically via Server-Sent Events. `sbl serve` is a deprecated alias that behaves identically. `sbl dashboard` also launches the Backlog browser alongside the server so you can edit tasks while the dashboard updates.
+`sbl dashboard` starts a local hub that serves a dark, HTS-style cockpit rendered from your Backlog data in seven sections — Board & Quick Actions, Status (donut), Milestones, Tasks (sortable/filterable table; click a row to open a modal detail view with acceptance criteria and dependencies), Feature Cycle (pipeline stepper plus an Up Next / Blocked flow view from task dependencies), Activity (30-day sparkline), and Decisions & Docs. Glossary tooltips explain domain terms inline; extend or override them project-wide via `backlog/docs/glossary.md` (`## Term` heading plus the text below it). No CDNs, no external fonts — works offline when served locally. Bookmark `http://127.0.0.1:6428/p/<project_name>/`. The hub watches `backlog/`, regenerates on change, and serves on port `6428`; connected browser tabs reload automatically via Server-Sent Events. A second repo's `sbl dashboard` attaches to the same hub. `Ctrl+C` in the hub terminal stops all projects.
 
 ### Keeping it fresh
 
-Run `sbl dashboard` whenever you want a live view of the board. The server regenerates the dashboard while it runs; stop it with `Ctrl+C`. There is no static `dashboard.html` installed in your project.
+Run `sbl dashboard` whenever you want a live view of the board. The hub regenerates the dashboard while it runs; stop it with `Ctrl+C` in the hub terminal. There is no static `dashboard.html` installed in your project.
 
 ![Project Dashboard](docs/assets/dashboard.png)
 

package/dist/bin.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// src/bin.ts
+// Always-run CLI entry. Unlike src/cli.ts (a plain module that only exports
+// HELP/runCli for tests), this file self-executes unconditionally so it
+// works when invoked via a symlink (npm's POSIX global/npx/npm-link bins are
+// symlinks, so comparing process.argv[1] against the module's own realpath
+// -- as the old cli.ts guard did -- is false for every such install).
+import process from 'node:process';
+import { runCli } from './cli.js';
+import { assertNode20 } from './lib/version.js';
+assertNode20();
+runCli(process.argv.slice(2))
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+});

package/dist/cli.js

@@ -1,17 +1,18 @@
-#!/usr/bin/env node
 // src/cli.ts
+// Pure library module: exports HELP/runCli for the always-run entry
+// (src/bin.ts) and for tests. Never self-executes -- see src/bin.ts for why.
+import { homedir } from 'node:os';
 import { parseArgs } from 'node:util';
 import process from 'node:process';
 import { runDashboard } from './commands/dashboard.js';
-import { runBacklogSubcommand } from './commands/backlog-alias.js';
 import { runDoctor } from './commands/doctor.js';
 import { runInit } from './commands/init.js';
 import { runModels } from './commands/models.js';
-import { runServe } from './commands/serve.js';
 import { runUninstall } from './commands/uninstall.js';
 import { runUpdate } from './commands/update.js';
-import { assertNode20, KIT_VERSION } from './lib/version.js';
-const HELP = `super-backlog (sbl) - equip any project with Backlog.md + Superpowers
+import { KIT_VERSION } from './lib/version.js';
+import { applyVersionHint, defaultFetchLatest } from './lib/version-check.js';
+export const HELP = `super-backlog (sbl) - equip any project with Backlog.md + Superpowers
 
 Usage: sbl <command> [options]
 
@@ -19,10 +20,7 @@ Commands:
   init        Install the kit into the current project
   uninstall   Remove kit-managed files (project data kept unless --with-backlog)
   update      Refresh kit-managed files and report upstream versions
-  dashboard   Start the project dashboard server (live-reload + Backlog browser)
-  serve       Deprecated alias for 'sbl dashboard'
-  browser     Open the Backlog.md browser (delegates to backlog browser)
-  board       Show the Backlog.md board (delegates to backlog board)
+  dashboard   Start the project dashboard server (live-reload)
   models      Manage the model router (show, enable, disable, discover)
   doctor      Check the environment (node, PowerShell policy, backlog CLI)
 
@@ -42,11 +40,7 @@ uninstall options:
 update options:
   (none)                          Refreshes injected files, skills, hook; prints upstream versions
 
- dashboard options:
-   --port <n>                      Port for the dashboard server (default: 6428)
-   --no-open                       Do not open the dashboard browser automatically
-
-serve options:
+dashboard options:
   --port <n>                      Port for the dashboard server (default: 6428)
   --no-open                       Do not open the dashboard browser automatically
 
@@ -59,7 +53,7 @@ Global options:
 Exit codes:
   0 ok | 1 usage/detection failure | 2 ownership or merge refusal
   3 upstream command failure | 4 success with warnings`;
-async function main(argv) {
+export async function runCli(argv) {
     const [command, ...rest] = argv;
     if (command === '--version' || command === '-v') {
         console.log(KIT_VERSION);
@@ -69,6 +63,13 @@ async function main(argv) {
         console.log(HELP);
         return 0;
     }
+    await applyVersionHint(KIT_VERSION, {
+        home: homedir(),
+        now: () => new Date(),
+        fetchLatest: defaultFetchLatest,
+        log: (line) => console.error(line),
+        env: { ...process.env, SBL_SKIP_UPDATE_CHECK: process.env.SBL_SKIP_UPDATE_CHECK },
+    });
     switch (command) {
         case 'init': {
             const parsed = parseArgs({
@@ -121,24 +122,11 @@ async function main(argv) {
                 positionals: parsed.positionals,
             });
         }
-        case 'serve': {
-            const parsed = parseArgs({
-                args: rest,
-                allowPositionals: true,
-                options: {
-                    port: { type: 'string' },
-                    'no-open': { type: 'boolean' },
-                },
-            });
-            return await runServe(process.cwd(), {
-                values: parsed.values,
-                positionals: parsed.positionals,
-            });
-        }
+        case 'serve':
         case 'browser':
-            return await runBacklogSubcommand(process.cwd(), 'browser', rest);
         case 'board':
-            return await runBacklogSubcommand(process.cwd(), 'board', rest);
+            console.error(`error: "sbl ${command}" was removed; the live dashboard is \`sbl dashboard\``);
+            return 1;
         case 'models': {
             const parsed = parseArgs({ args: rest, allowPositionals: true, options: {} });
             return await runModels(process.cwd(), {
@@ -154,12 +142,3 @@ async function main(argv) {
             return 1;
     }
 }
-assertNode20();
-main(process.argv.slice(2))
-    .then((code) => {
-    process.exitCode = code;
-})
-    .catch((err) => {
-    console.error(err instanceof Error ? err.message : String(err));
-    process.exitCode = 1;
-});

package/dist/commands/dashboard.js

@@ -1,39 +1,140 @@
-import { tmpdir } from 'node:os';
+import { spawn } from 'node:child_process';
+import { request as httpRequest } from 'node:http';
+import { homedir as osHomedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
-import spawn from 'cross-spawn';
+import process from 'node:process';
 import { collectDashboardData } from '../dashboard/data.js';
+import { startHubServer } from '../dashboard/hub.js';
 import { renderDashboard } from '../dashboard/render.js';
-import { DASHBOARD_PORT, startServeServer } from '../dashboard/server.js';
+import { DASHBOARD_PORT } from '../dashboard/server.js';
 import { atomicWrite } from '../lib/atomic.js';
-import { resolveBacklogBin } from '../lib/run.js';
+import { clearHubState, isPidAlive, newHubToken, readHubState, writeHubState } from '../lib/hub-state.js';
+import { projectSlug } from '../lib/slug.js';
 import { KIT_VERSION } from '../lib/version.js';
 async function regenerateInto(outPath, cwd) {
     const data = collectDashboardData(cwd, { kitVersion: KIT_VERSION });
     atomicWrite(outPath, renderDashboard(data));
 }
-function spawnBacklogBrowser(cwd) {
-    const bin = resolveBacklogBin(cwd);
-    if (!bin) {
-        console.warn('warning: backlog CLI not found; dashboard will serve without the Backlog browser');
-        return;
+function defaultOpenBrowser(url) {
+    try {
+        if (process.platform === 'win32') {
+            spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' })
+                .on('error', () => { })
+                .unref();
+        }
+        else if (process.platform === 'darwin') {
+            spawn('open', [url], { detached: true, stdio: 'ignore' })
+                .on('error', () => { })
+                .unref();
+        }
+        else {
+            spawn('xdg-open', [url], { detached: true, stdio: 'ignore' })
+                .on('error', () => { })
+                .unref();
+        }
     }
+    catch {
+    }
+}
+function defaultAttach(url, body) {
+    return new Promise((resolve, reject) => {
+        const u = new URL(url);
+        const payload = body === undefined ? undefined : JSON.stringify(body);
+        const req = httpRequest({
+            host: u.hostname,
+            port: u.port,
+            path: `${u.pathname}${u.search}`,
+            method: payload === undefined ? 'GET' : 'POST',
+            headers: payload === undefined
+                ? {}
+                : {
+                    'content-type': 'application/json',
+                    'content-length': Buffer.byteLength(payload),
+                },
+        }, (res) => {
+            let b = '';
+            res.setEncoding('utf8');
+            res.on('data', (c) => {
+                b += c;
+            });
+            res.on('end', () => {
+                let json = b;
+                try {
+                    json = JSON.parse(b);
+                }
+                catch {
+                }
+                resolve({ status: res.statusCode ?? 0, json });
+            });
+        });
+        req.on('error', reject);
+        if (payload !== undefined)
+            req.write(payload);
+        req.end();
+    });
+}
+function isEaddrinuse(err) {
+    return typeof err === 'object' && err !== null && 'code' in err && err.code === 'EADDRINUSE';
+}
+function waitForClose(hub) {
+    return new Promise((resolve) => {
+        hub.server.once('close', () => resolve());
+    });
+}
+/**
+ * Builds the hub shutdown routine: close the hub handle, then clear the
+ * on-disk hub.json owned by `pid`. The returned function is idempotent --
+ * calling it more than once (e.g. once from a signal handler, once from the
+ * caller's own cleanup) only runs the underlying work once and every caller
+ * observes the same result.
+ */
+export function createShutdown(hub, home, pid) {
+    let done = null;
+    return function shutdown() {
+        if (done === null) {
+            done = (async () => {
+                await hub.close();
+                clearHubState(home, pid);
+            })();
+        }
+        return done;
+    };
+}
+async function attachToHub(opts) {
+    let res;
     try {
-        const child = spawn(bin, ['browser', '--no-open', '--non-interactive'], {
-            cwd,
-            detached: true,
-            stdio: 'ignore',
+        res = await opts.attach(`http://127.0.0.1:${opts.port}/api/hub/register`, {
+            cwd: opts.cwd,
+            token: opts.token,
         });
-        child.on('error', () => { });
-        child.unref();
-        console.log('started Backlog browser (dashboard still serves if browser fails)');
     }
-    catch {
-        console.warn('warning: failed to start Backlog browser; dashboard still serves');
+    catch (err) {
+        console.error(`error: dashboard serve failed (${err instanceof Error ? err.message : String(err)})`);
+        return 1;
+    }
+    if (res.status === 401) {
+        console.error('error: hub token mismatch; stop the other hub or delete stale hub.json');
+        return 1;
+    }
+    if (res.status === 409) {
+        const json = res.json;
+        console.error(`error: slug collision between ${json.existingCwd ?? ''} and ${json.incomingCwd ?? ''}; change project_name in one backlog/config.yml`);
+        return 1;
+    }
+    if (res.status !== 200) {
+        console.error(`error: dashboard serve failed (register ${res.status})`);
+        return 1;
+    }
+    const json = res.json;
+    if (json.ok !== true || typeof json.url !== 'string') {
+        console.error('error: dashboard serve failed (invalid register response)');
+        return 1;
     }
+    if (!opts.noOpen)
+        opts.openBrowser(json.url);
+    return 0;
 }
-/** CLI entry for `sbl dashboard [--port N] [--no-open]`. Starts a local server
- * that watches backlog/ and regenerates a temp dashboard file on changes. */
-export async function runDashboard(cwd, args) {
+export async function runDashboard(cwd, args, deps = {}) {
     const values = args.values;
     let port = DASHBOARD_PORT;
     if (values['port'] !== undefined) {
@@ -45,23 +146,95 @@ export async function runDashboard(cwd, args) {
         port = parsed;
     }
     const noOpen = values['no-open'] === true;
-    const outPath = join(tmpdir(), `sbl-dashboard-${Date.now()}.html`);
+    const home = (deps.homedir ?? osHomedir)();
+    const startHub = deps.startHub ?? startHubServer;
+    const attach = deps.attach ?? defaultAttach;
+    const openBrowser = deps.openBrowser ?? defaultOpenBrowser;
+    const pid = (deps.nowPid ?? (() => process.pid))();
+    let slugResult;
     try {
-        await regenerateInto(outPath, cwd);
-        console.log(`dashboard written: ${outPath}`);
-        console.log(`serving dashboard at http://127.0.0.1:${port}/ (press Ctrl+C to stop)`);
-        // Start backlog browser in parallel; don't await so the dashboard server can listen immediately.
-        spawnBacklogBrowser(cwd);
-        await startServeServer(cwd, {
-            port,
-            file: outPath,
-            regenerate: () => regenerateInto(outPath, cwd),
-            openBrowser: !noOpen,
-        });
-        return 0;
+        slugResult = projectSlug(cwd);
+    }
+    catch {
+        console.error('error: set project_name in backlog/config.yml');
+        return 1;
+    }
+    if (!slugResult.ok) {
+        console.error('error: set project_name in backlog/config.yml');
+        return 1;
+    }
+    const slug = slugResult.slug;
+    const state = readHubState(home);
+    if (state !== null && isPidAlive(state.pid)) {
+        try {
+            const status = await attach(`http://127.0.0.1:${state.port}/api/hub/status?token=${encodeURIComponent(state.token)}`, undefined);
+            if (status.status === 200) {
+                if (values['port'] !== undefined && port !== state.port) {
+                    console.error(`error: a hub is already running on ${state.port}`);
+                    return 1;
+                }
+                return await attachToHub({
+                    cwd,
+                    port: state.port,
+                    token: state.token,
+                    attach,
+                    openBrowser,
+                    noOpen,
+                });
+            }
+        }
+        catch {
+        }
+    }
+    if (values['port'] !== undefined) {
+        console.warn('warning: default bookmarks (:6428) will miss this hub');
+    }
+    const token = newHubToken();
+    const outPath = join(tmpdir(), `sbl-dashboard-${Date.now()}-${slug}.html`);
+    const regenerate = () => regenerateInto(outPath, cwd);
+    let hub;
+    try {
+        await regenerate();
+        hub = await startHub({ port, token });
     }
     catch (err) {
+        if (isEaddrinuse(err)) {
+            console.error(`error: port ${port} is in use`);
+            console.error('hint: pass --port as emergency only');
+            return 1;
+        }
         console.error(`error: dashboard serve failed (${err instanceof Error ? err.message : String(err)})`);
         return 1;
     }
+    writeHubState(home, { pid, port: hub.port, token });
+    const result = hub.register({ cwd, file: outPath, regenerate });
+    if (!result.ok) {
+        await hub.close();
+        clearHubState(home, pid);
+        if (result.code === 409) {
+            console.error(`error: slug collision between ${result.existingCwd} and ${result.incomingCwd}; change project_name in one backlog/config.yml`);
+            return 1;
+        }
+        console.error(`error: dashboard serve failed (${result.message})`);
+        return 1;
+    }
+    console.log(`dashboard written: ${outPath}`);
+    console.log(`serving dashboard at ${result.url} (press Ctrl+C to stop)`);
+    if (!noOpen)
+        openBrowser(result.url);
+    const shutdown = createShutdown(hub, home, pid);
+    const onSignal = () => {
+        void shutdown();
+    };
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    try {
+        await waitForClose(hub);
+        return 0;
+    }
+    finally {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+        await shutdown();
+    }
 }

package/dist/dashboard/hub.js

@@ -0,0 +1,287 @@
+import { watch } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
+import { collectDashboardData } from './data.js';
+import { renderDashboard } from './render.js';
+import { createDebouncedReloader, createReloadBroker, createRunApiHandler, DASHBOARD_PORT, recursiveWatchSupported, } from './server.js';
+import { atomicWrite } from '../lib/atomic.js';
+import { projectSlug, realpathKey } from '../lib/slug.js';
+import { KIT_VERSION } from '../lib/version.js';
+import { createModelApiHandler } from '../models/dashboard-api.js';
+const WATCH_WARN = 'warning: live reload is disabled because Node 24+ on Windows cannot reliably watch directories recursively (libuv fs-event bug); use Node 22 or Linux/macOS for live reload';
+const ALLOWED_HOST = /^(127\.0\.0\.1|localhost)(:\d+)?$/;
+function isAllowedHost(headerValue) {
+    const value = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+    if (typeof value !== 'string')
+        return false;
+    return ALLOWED_HOST.test(value.trim().toLowerCase());
+}
+function hasJsonContentType(req) {
+    const value = req.headers['content-type'];
+    const ct = Array.isArray(value) ? value[0] : value;
+    return typeof ct === 'string' && ct.toLowerCase().startsWith('application/json');
+}
+function projectUrl(port, slug) {
+    return `http://127.0.0.1:${port}/p/${slug}/`;
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+function sendText(res, status, body) {
+    res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end(body);
+}
+function serveFile(file, res) {
+    readFile(file)
+        .then((bytes) => {
+        res.writeHead(200, {
+            'content-type': 'text/html; charset=utf-8',
+            'cache-control': 'no-store',
+        });
+        res.end(bytes);
+    })
+        .catch(() => {
+        sendText(res, 404, 'dashboard not generated yet');
+    });
+}
+function generateDashboard(cwd, file) {
+    const data = collectDashboardData(cwd, { kitVersion: KIT_VERSION });
+    atomicWrite(file, renderDashboard(data));
+}
+export async function startHubServer(opts) {
+    const projects = new Map();
+    const token = opts.token;
+    let port = 0;
+    let watchWarned = false;
+    function watchBacklog(cwd, reloader) {
+        const backlogDir = join(cwd, 'backlog');
+        if (recursiveWatchSupported(process.platform, process.versions.node)) {
+            try {
+                const watcher = watch(backlogDir, { persistent: true, recursive: true }, () => reloader.trigger());
+                watcher.on('error', () => { });
+                return watcher;
+            }
+            catch {
+                return null;
+            }
+        }
+        if (!watchWarned) {
+            watchWarned = true;
+            console.warn(WATCH_WARN);
+        }
+        return null;
+    }
+    function disposeEntry(entry) {
+        entry.reloader.cancel();
+        entry.broker.close();
+        entry.watcher?.close();
+    }
+    function register(project) {
+        let computed;
+        try {
+            computed = projectSlug(project.cwd);
+        }
+        catch {
+            return { ok: false, code: 400, message: 'invalid cwd' };
+        }
+        if (!computed.ok) {
+            return { ok: false, code: 400, message: 'empty slug' };
+        }
+        const slug = computed.slug;
+        if (slug === '') {
+            return { ok: false, code: 400, message: 'empty slug' };
+        }
+        let key;
+        try {
+            key = realpathKey(project.cwd);
+        }
+        catch {
+            return { ok: false, code: 400, message: 'invalid cwd' };
+        }
+        const existing = projects.get(slug);
+        if (existing && existing.realpath !== key) {
+            return { ok: false, code: 409, existingCwd: existing.cwd, incomingCwd: project.cwd };
+        }
+        const url = projectUrl(port, slug);
+        if (existing && existing.realpath === key) {
+            existing.cwd = project.cwd;
+            existing.file = project.file;
+            existing.reloader.cancel();
+            existing.watcher?.close();
+            existing.reloader = createDebouncedReloader(project.regenerate, () => existing.broker.broadcast('reload'), 300);
+            existing.watcher = watchBacklog(project.cwd, existing.reloader);
+            existing.modelApi = createModelApiHandler(project.cwd);
+            return { ok: true, slug, url };
+        }
+        const broker = createReloadBroker();
+        const reloader = createDebouncedReloader(project.regenerate, () => broker.broadcast('reload'), 300);
+        const entry = {
+            cwd: project.cwd,
+            realpath: key,
+            file: project.file,
+            broker,
+            reloader,
+            watcher: watchBacklog(project.cwd, reloader),
+            runApi: createRunApiHandler(project.cwd),
+            modelApi: createModelApiHandler(project.cwd),
+        };
+        projects.set(slug, entry);
+        return { ok: true, slug, url };
+    }
+    async function handle(req, res) {
+        if (!isAllowedHost(req.headers.host)) {
+            sendText(res, 403, 'forbidden');
+            return;
+        }
+        const method = req.method ?? 'GET';
+        if (method === 'POST' && !hasJsonContentType(req)) {
+            sendText(res, 415, 'unsupported media type: expected application/json');
+            return;
+        }
+        const parsed = new URL(req.url ?? '/', 'http://127.0.0.1');
+        const pathname = parsed.pathname;
+        if (pathname === '/' && method === 'GET') {
+            const links = [...projects.keys()]
+                .map((s) => `<li><a href="/p/${s}/">${s}</a></li>`)
+                .join('\n');
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+            res.end(`<!doctype html><title>sbl hub</title><ul>${links}</ul>`);
+            return;
+        }
+        if (pathname === '/api/hub/status' && method === 'GET') {
+            if (parsed.searchParams.get('token') !== token) {
+                sendText(res, 401, 'unauthorized');
+                return;
+            }
+            sendJson(res, 200, { pid: process.pid, port });
+            return;
+        }
+        if (pathname === '/api/hub/register' && method === 'POST') {
+            let body;
+            try {
+                body = await readBody(req);
+            }
+            catch {
+                sendJson(res, 400, { error: 'failed to read body' });
+                return;
+            }
+            let payload;
+            try {
+                payload = JSON.parse(body);
+            }
+            catch {
+                sendJson(res, 400, { error: 'invalid json' });
+                return;
+            }
+            if (typeof payload !== 'object' || payload === null) {
+                sendJson(res, 400, { error: 'invalid json' });
+                return;
+            }
+            const rec = payload;
+            if (rec.token !== token) {
+                sendText(res, 401, 'unauthorized');
+                return;
+            }
+            if (typeof rec.cwd !== 'string') {
+                sendJson(res, 400, { ok: false, code: 400, message: 'cwd required' });
+                return;
+            }
+            const cwd = rec.cwd;
+            const slugResult = (() => {
+                try {
+                    return projectSlug(cwd);
+                }
+                catch {
+                    return { ok: false, reason: 'empty' };
+                }
+            })();
+            const slug = slugResult.ok ? slugResult.slug : 'project';
+            const file = join(tmpdir(), `sbl-dashboard-${Date.now()}-${slug}.html`);
+            const regenerate = () => generateDashboard(cwd, file);
+            try {
+                regenerate();
+            }
+            catch {
+                // still register; GET may 404 until a later refresh
+            }
+            const result = register({ cwd, file, regenerate });
+            sendJson(res, result.ok ? 200 : result.code, result);
+            return;
+        }
+        const scoped = /^\/p\/([^/]+)(\/.*)?$/.exec(pathname);
+        if (!scoped) {
+            sendText(res, 404, 'not found');
+            return;
+        }
+        const slug = scoped[1] ?? '';
+        const rest = scoped[2];
+        const entry = projects.get(slug);
+        if (!entry) {
+            sendText(res, 404, 'not found');
+            return;
+        }
+        if (rest === undefined) {
+            res.writeHead(302, { location: `/p/${slug}/` });
+            res.end();
+            return;
+        }
+        if (rest.startsWith('/api/')) {
+            req.url = rest;
+            if (rest === '/api/run') {
+                await entry.runApi(req, res);
+                return;
+            }
+            if (entry.broker.handler(req, res)) {
+                return;
+            }
+            await entry.modelApi(req, res);
+            return;
+        }
+        if (method === 'GET' && (rest === '/' || rest === '/index.html')) {
+            serveFile(entry.file, res);
+            return;
+        }
+        sendText(res, 404, 'not found');
+    }
+    const server = createServer((req, res) => {
+        void handle(req, res);
+    });
+    const requestedPort = opts.port ?? DASHBOARD_PORT;
+    port = await new Promise((resolvePort, rejectPort) => {
+        server.once('error', rejectPort);
+        server.listen(requestedPort, '127.0.0.1', () => {
+            const addr = server.address();
+            if (addr !== null && typeof addr === 'object')
+                resolvePort(addr.port);
+            else
+                resolvePort(requestedPort);
+        });
+    });
+    return {
+        server,
+        port,
+        register,
+        triggerReload(slug) {
+            projects.get(slug)?.reloader.trigger();
+        },
+        close() {
+            for (const entry of projects.values())
+                disposeEntry(entry);
+            projects.clear();
+            return new Promise((resolveClose) => {
+                server.close(() => resolveClose());
+            });
+        },
+    };
+}

package/dist/dashboard/server.js

@@ -1,12 +1,8 @@
 // src/dashboard/server.ts
 import { spawn } from 'node:child_process';
-import { watch } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { createServer } from 'node:http';
 import { isAbsolute, join } from 'node:path';
 import process from 'node:process';
 import crossSpawn from 'cross-spawn';
-import { createModelApiHandler } from '../models/dashboard-api.js';
 import { resolveBacklogBin } from '../lib/run.js';
 export const DASHBOARD_PORT = 6428;
 const WHITELIST = new Map([
@@ -167,21 +163,6 @@ export function createDebouncedReloader(regenerate, onReload, delayMs) {
     }
     return { trigger, cancel };
 }
-function createApiHandler(cwd, broker) {
-    const modelApi = createModelApiHandler();
-    const runApi = createRunApiHandler(cwd);
-    return async (req, res) => {
-        const url = req.url ?? '/';
-        if (url === '/api/run') {
-            await runApi(req, res);
-            return;
-        }
-        if (broker.handler(req, res)) {
-            return;
-        }
-        await modelApi(req, res);
-    };
-}
 export function recursiveWatchSupported(platform, nodeVersion) {
     // Node 24 on Windows triggers a libuv assertion in recursive fs.watch:
     // https://github.com/nodejs/node/issues/xxx (fs-event.c line 72)
@@ -211,80 +192,31 @@ function openInBrowser(url) {
     }
 }
 /**
- * Serve the latest dashboard bytes; changes inside <cwd>/backlog trigger
- * `regenerate()` debounced by 300ms. Pass port 0 for an ephemeral port (tests).
+ * Serve the latest dashboard bytes via the hub at `/p/<slug>/`.
+ * Pass port 0 for an ephemeral port (tests).
  */
 export async function startServeServer(cwd, opts = {}) {
+    const { startHubServer } = await import('./hub.js');
     const file = opts.file ?? 'dashboard.html';
     const filePath = isAbsolute(file) ? file : join(cwd, file);
-    const regenerate = opts.regenerate;
-    const broker = createReloadBroker();
-    const reloader = createDebouncedReloader(regenerate, () => broker.broadcast('reload'), 300);
-    let watcher = null;
-    const backlogDir = join(cwd, 'backlog');
-    if (recursiveWatchSupported(process.platform, process.versions.node)) {
-        try {
-            // recursive so subdirectory writes (e.g. backlog/tasks/*.md) fire on every platform
-            watcher = watch(backlogDir, { persistent: true, recursive: true }, () => reloader.trigger());
-            watcher.on('error', () => { }); // e.g. watched dir removed mid-session
-        }
-        catch {
-            watcher = null; // no backlog dir -> no live reload; serving still works
-        }
-    }
-    else {
-        console.warn('warning: live reload is disabled because Node 24+ on Windows cannot reliably watch directories recursively (libuv fs-event bug); use Node 22 or Linux/macOS for --serve');
-    }
-    const apiHandler = createApiHandler(cwd, broker);
-    const server = createServer((req, res) => {
-        if (req.url?.startsWith('/api/')) {
-            void apiHandler(req, res);
-            return;
-        }
-        const url = req.url ?? '/';
-        const method = req.method ?? 'GET';
-        if (method !== 'GET' || !(url === '/' || url === '/index.html')) {
-            res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
-            res.end('not found');
-            return;
-        }
-        readFile(filePath)
-            .then((bytes) => {
-            res.writeHead(200, {
-                'content-type': 'text/html; charset=utf-8',
-                'cache-control': 'no-store',
-            });
-            res.end(bytes);
-        })
-            .catch(() => {
-            res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
-            res.end('dashboard not generated yet');
-        });
-    });
-    const requestedPort = opts.port ?? DASHBOARD_PORT;
-    const port = await new Promise((resolvePort, rejectPort) => {
-        server.once('error', rejectPort);
-        server.listen(requestedPort, '127.0.0.1', () => {
-            const addr = server.address();
-            if (addr !== null && typeof addr === 'object')
-                resolvePort(addr.port);
-            else
-                resolvePort(requestedPort);
-        });
+    const hub = await startHubServer({ port: opts.port ?? DASHBOARD_PORT, token: 'serve' });
+    const result = hub.register({
+        cwd,
+        file: filePath,
+        regenerate: opts.regenerate ?? (() => { }),
     });
+    if (!result.ok) {
+        await hub.close();
+        const message = result.code === 400 ? result.message : `register failed (${result.code})`;
+        throw new Error(message);
+    }
     if (opts.openBrowser)
-        openInBrowser(`http://127.0.0.1:${port}/`);
+        openInBrowser(result.url);
     return {
-        server,
-        port,
+        server: hub.server,
+        port: hub.port,
         close() {
-            reloader.cancel();
-            broker.close();
-            watcher?.close();
-            watcher = null;
-            return new Promise((resolveClose) => {
-                server.close(() => resolveClose());
-            });
+            return hub.close();
         },
     };
 }

package/dist/lib/hub-state.js

@@ -0,0 +1,53 @@
+import { randomBytes } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+import { atomicWrite } from './atomic.js';
+export function hubStatePath(home) {
+    return join(home, '.super-backlog', 'hub.json');
+}
+export function readHubState(home) {
+    try {
+        const parsed = JSON.parse(readFileSync(hubStatePath(home), 'utf8'));
+        if (parsed === null ||
+            typeof parsed !== 'object' ||
+            typeof parsed.pid !== 'number' ||
+            typeof parsed.port !== 'number' ||
+            typeof parsed.token !== 'string') {
+            return null;
+        }
+        const { pid, port, token } = parsed;
+        return { pid, port, token };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeHubState(home, state) {
+    mkdirSync(join(home, '.super-backlog'), { recursive: true });
+    const path = hubStatePath(home);
+    atomicWrite(path, JSON.stringify(state));
+    // hub.json carries the hub's auth token; keep it off other local accounts.
+    // win32 has no POSIX mode bits (ACLs govern access there instead).
+    if (process.platform !== 'win32') {
+        chmodSync(path, 0o600);
+    }
+}
+export function clearHubState(home, pid) {
+    const current = readHubState(home);
+    if (current === null || current.pid !== pid)
+        return;
+    rmSync(hubStatePath(home), { force: true });
+}
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function newHubToken() {
+    return randomBytes(16).toString('hex');
+}

package/dist/lib/slug.js

@@ -0,0 +1,25 @@
+import { realpathSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import process from 'node:process';
+import { readSimpleKeys } from './yamlmini.js';
+export function realpathKey(cwd) {
+    const resolved = realpathSync(cwd);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+export function sanitizeSlug(raw) {
+    const nk = raw.normalize('NFKD').replace(/\p{M}/gu, '');
+    return nk
+        .toLowerCase()
+        .replace(/[_\s]+/g, '-')
+        .replace(/[^a-z0-9-]/g, '')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+export function projectSlug(cwd) {
+    const cfg = readSimpleKeys(join(cwd, 'backlog', 'config.yml'), ['project_name']);
+    const raw = (cfg.project_name && cfg.project_name.trim() !== '' ? cfg.project_name : basename(realpathSync(cwd)));
+    const slug = sanitizeSlug(raw);
+    if (slug === '')
+        return { ok: false, reason: 'empty' };
+    return { ok: true, slug };
+}

package/dist/lib/version-check.js

@@ -0,0 +1,122 @@
+// src/lib/version-check.ts
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+import spawn from 'cross-spawn';
+const DAY_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 2000;
+function cachePath(home) {
+    return join(home, '.super-backlog', 'version-check.json');
+}
+function isNewer(latest, installed) {
+    const a = latest.split('.').slice(0, 3).map(Number);
+    const b = installed.split('.').slice(0, 3).map(Number);
+    if (a.length < 3 || b.length < 3)
+        return false;
+    if (a.some((n) => !Number.isFinite(n)) || b.some((n) => !Number.isFinite(n)))
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] > b[i])
+            return true;
+        if (a[i] < b[i])
+            return false;
+    }
+    return false;
+}
+function readCache(home) {
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath(home), 'utf8'));
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const rec = parsed;
+        if (typeof rec.checkedAt !== 'string' || typeof rec.latest !== 'string')
+            return null;
+        return { checkedAt: rec.checkedAt, latest: rec.latest };
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(home, cache) {
+    mkdirSync(join(home, '.super-backlog'), { recursive: true });
+    writeFileSync(cachePath(home), JSON.stringify(cache));
+}
+function isStale(checkedAt, now) {
+    const t = Date.parse(checkedAt);
+    if (Number.isNaN(t))
+        return true;
+    const nowMs = now.getTime();
+    if (t > nowMs)
+        return true; // clock skew: a future checkedAt can never be trusted
+    return nowMs - t > DAY_MS;
+}
+// child.stdout is typed as Readable, but the underlying pipe stream (a
+// net.Socket on POSIX, a Pipe wrap on Windows) always exposes unref() at
+// runtime; the DOM/Node stream typings just don't declare it.
+function unrefStream(stream) {
+    stream?.unref?.();
+}
+export async function defaultFetchLatest() {
+    const work = new Promise((resolvePromise) => {
+        let child;
+        try {
+            child = spawn('npm', ['view', 'super-backlog', 'version'], {
+                cwd: process.cwd(),
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+        }
+        catch {
+            resolvePromise(null);
+            return;
+        }
+        let out = '';
+        unrefStream(child.stdout);
+        child.stdout?.on('data', (chunk) => {
+            out += chunk.toString('utf8');
+        });
+        child.on('error', () => resolvePromise(null));
+        child.on('close', (code) => {
+            if (code !== 0) {
+                resolvePromise(null);
+                return;
+            }
+            const line = out.split(/\r?\n/).find((l) => l.trim() !== '');
+            const v = line?.trim();
+            resolvePromise(v === undefined || v === '' ? null : v);
+        });
+        child.unref();
+    });
+    let timer;
+    const timeout = new Promise((resolveTimeout) => {
+        timer = setTimeout(() => resolveTimeout(null), FETCH_TIMEOUT_MS);
+        timer.unref();
+    });
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+export async function applyVersionHint(installed, deps) {
+    if (deps.env.SBL_SKIP_UPDATE_CHECK)
+        return;
+    const cache = readCache(deps.home);
+    if (cache && isNewer(cache.latest, installed)) {
+        deps.log(`super-backlog ${cache.latest} is available (installed ${installed}). Update: npm i -g super-backlog`);
+    }
+    if (!cache || isStale(cache.checkedAt, deps.now())) {
+        void deps
+            .fetchLatest()
+            .then((latest) => {
+            if (latest == null || latest === '')
+                return;
+            writeCache(deps.home, { checkedAt: deps.now().toISOString(), latest });
+        })
+            .catch(() => { });
+    }
+}

package/dist/models/dashboard-api.js

@@ -1,25 +1,16 @@
-import process from 'node:process';
 import { loadConfig } from './config.js';
 import { discoverModels } from './discovery.js';
-function currentCwd() {
-    try {
-        return process.cwd();
-    }
-    catch {
-        return '.';
-    }
-}
-export function createModelApiHandler() {
+export function createModelApiHandler(cwd) {
     return async (req, res) => {
         const url = req.url ?? '/';
         const method = req.method ?? 'GET';
         if (method === 'GET' && url === '/api/models') {
             res.writeHead(200, { 'content-type': 'application/json' });
-            res.end(JSON.stringify({ config: loadConfig(currentCwd()), status: 'ok' }));
+            res.end(JSON.stringify({ config: loadConfig(cwd), status: 'ok' }));
             return;
         }
         if (method === 'POST' && url === '/api/models/discover') {
-            const result = await discoverModels(currentCwd());
+            const result = await discoverModels(cwd);
             res.writeHead(200, { 'content-type': 'application/json' });
             res.end(JSON.stringify(result ?? { error: 'discovery failed' }));
             return;

package/dist/templates/dashboard.html

@@ -526,7 +526,7 @@
       var copy = b.getAttribute('data-copy');
       if (copy) { copyCommand(b, copy); return; }
       var cmd = b.getAttribute('data-cmd');
-      fetch('/api/run', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ command: cmd }) })
+      fetch('api/run', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ command: cmd }) })
         .then(function (res) { if (!res.ok) throw new Error('run failed'); cmdFeedback(b, 'started \u2713'); })
         .catch(function () {});
     });
@@ -975,7 +975,7 @@
 <script>
 (function () {
   if (!window.EventSource || (location.protocol !== 'http:' && location.protocol !== 'https:')) return;
-  var es = new EventSource('/api/events');
+  var es = new EventSource('api/events');
   es.addEventListener('reload', function () { location.reload(); });
   es.addEventListener('error', function () {});
 })();

package/dist/templates/skill-backlog-status-report.md

@@ -21,7 +21,7 @@ Read-only summary of the Backlog.md data in this project.
    - Every In Progress task: ID, title, open acceptance criteria
    - Milestones with done/total
    - Blocked or stale items worth flagging
-4. Point to the visual surfaces: `sbl dashboard --serve` (live dashboard) or
+4. Point to the visual surfaces: `sbl dashboard` (live dashboard) or
    `backlog browser` (interactive Kanban).
 
 ## Boundaries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-backlog",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "description": "One command to equip any project with Backlog.md + Superpowers, plus a Project Dashboard.",
   "license": "MIT",
   "repository": {
@@ -12,8 +12,8 @@
     "node": ">=20"
   },
   "bin": {
-    "sbl": "dist/cli.js",
-    "super-backlog": "dist/cli.js"
+    "sbl": "dist/bin.js",
+    "super-backlog": "dist/bin.js"
   },
   "files": [
     "dist",

package/dist/commands/backlog-alias.js

@@ -1,18 +0,0 @@
-import spawn from 'cross-spawn';
-import { resolveBacklogBin } from '../lib/run.js';
-/** Run a backlog.md subcommand by delegating to the resolved backlog binary. */
-export function runBacklogSubcommand(cwd, subcommand, args = []) {
-    const bin = resolveBacklogBin(cwd);
-    if (!bin) {
-        console.error('error: backlog CLI not found; is backlog.md installed?');
-        return Promise.resolve(1);
-    }
-    return new Promise((resolve) => {
-        const child = spawn(bin, [subcommand, ...args], {
-            cwd,
-            stdio: 'inherit',
-        });
-        child.on('error', () => resolve(1));
-        child.on('exit', (code) => resolve(code ?? 1));
-    });
-}

package/dist/commands/serve.js

@@ -1,3 +0,0 @@
-// src/commands/serve.ts
-// Deprecated alias: `sbl serve` behaves exactly like `sbl dashboard`.
-export { runDashboard as runServe } from './dashboard.js';