super-backlog 0.9.0 → 1.0.0

package/README.md

@@ -52,6 +52,7 @@ 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
 ```
 
@@ -70,11 +71,10 @@ sbl dashboard --serve             # live Project Dashboard on http://localhost:6
 | `.opencode/skill/<skill>/SKILL.md` (3 glue skills) | skill templates | fingerprint header line |
 | `.claude/skills/<skill>/SKILL.md` | same templates | fingerprint header line |
 | `package.json` scripts | `tasks` → `backlog task list`, `board` → `backlog board`, `browser` → `backlog browser`, `dashboard` → `super-backlog dashboard` (never overwrite existing values) | merged, add-only-if-absent |
-| `dashboard.html` | generated Project Dashboard | regenerated wholesale |
-| `.git/hooks/post-commit` | dashboard freshness block — regenerates `dashboard.html` after commits that touch `backlog/` (default; opt out with `--no-refresh-hook`) | appended marker block |
+| `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 [--serve] [--port <n>] [--no-open] [--out <file>]`. 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]` · `sbl serve [--port <n>] [--no-open]`. See `sbl help` for every flag.
 
 ## Model router (opt-in)
 
@@ -98,11 +98,11 @@ The router is fully owned by super-backlog and removed by `sbl uninstall`. See t
 
 ## Project Dashboard
 
-`sbl dashboard` generates a single self-contained `dashboard.html`: a dark, HTS-style cockpit rendered from your Backlog data in seven sections — Board & Quick Actions, Status (donut), Milestones, Tasks (sortable/filterable table with a click-in detail panel per task), Feature Cycle (pipeline stepper), Activity (30-day sparkline), and Decisions & Docs. A layered dependency graph maps task `depends-on` relations (cycle- and dangling-ref-tolerant): hover highlights edges, click opens the task. 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, diffs cleanly in git, hostable anywhere. Use `--serve` for live mode: it watches `backlog/`, regenerates on change, and serves on port 6428 by default.
+`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.
 
 ### Keeping it fresh
 
-By default `init` installs a `post-commit` hook block that regenerates `dashboard.html` whenever the commit touched `backlog/`. The block is marker-delimited, so it composes with the guard hook and foreign hook content, `uninstall` removes exactly that block, and `update` refreshes it. It never blocks a commit: failures print a one-line stderr note and the exit status stays 0. Opt out with `--no-refresh-hook`.
+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.
 
 ![Project Dashboard](docs/assets/dashboard.png)
 

package/dist/cli.js

@@ -3,9 +3,11 @@
 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';
@@ -17,18 +19,19 @@ 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   Generate the single-file project dashboard (--serve for live mode)
+  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)
   models      Manage the model router (show, enable, disable, discover)
   doctor      Check the environment (node, PowerShell policy, backlog CLI)
 
-init options:
+  init options:
   --pm <auto|npm|pnpm|bun|skip>   Package manager to use (default: auto)
   --harness <opencode|claude>     Target harness; repeatable or comma-separated (default: both)
   --guard                         Install the integrity pre-commit hook (opt-in)
   --models                        Install the model router config during init (opt-in)
   --no-models                     Explicitly opt out of the model router
-  --no-dashboard                  Skip generating the project dashboard
-  --no-refresh-hook               Skip the post-commit dashboard freshness hook
   --fix-all                       Repair environment problems automatically (no prompts)
   --dry-run                       Show what would be done without writing anything
 
@@ -39,11 +42,13 @@ uninstall options:
 update options:
   (none)                          Refreshes injected files, skills, hook; prints upstream versions
 
-dashboard options:
-  --serve                         Live mode: watch backlog/ and regenerate on changes
-  --port <n>                      Port for --serve (default: 6428)
-  --no-open                       With --serve: do not open the browser automatically
-  --out <file>                    Output file name or path (default: dashboard.html)
+ dashboard options:
+   --port <n>                      Port for the dashboard server (default: 6428)
+   --no-open                       Do not open the dashboard browser automatically
+
+serve options:
+  --port <n>                      Port for the dashboard server (default: 6428)
+  --no-open                       Do not open the dashboard browser automatically
 
 doctor options:
   (none)                          Prints one [ok]/[warn]/[skip] line per check; exit 4 on any warn
@@ -75,8 +80,6 @@ async function main(argv) {
                     guard: { type: 'boolean' },
                     models: { type: 'boolean' },
                     'no-models': { type: 'boolean' },
-                    'no-dashboard': { type: 'boolean' },
-                    'no-refresh-hook': { type: 'boolean' },
                     'fix-all': { type: 'boolean' },
                     'dry-run': { type: 'boolean' },
                 },
@@ -109,10 +112,8 @@ async function main(argv) {
                 args: rest,
                 allowPositionals: true,
                 options: {
-                    serve: { type: 'boolean' },
                     port: { type: 'string' },
                     'no-open': { type: 'boolean' },
-                    out: { type: 'string' },
                 },
             });
             return await runDashboard(process.cwd(), {
@@ -120,6 +121,24 @@ 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 'browser':
+            return await runBacklogSubcommand(process.cwd(), 'browser', rest);
+        case 'board':
+            return await runBacklogSubcommand(process.cwd(), 'board', rest);
         case 'models': {
             const parsed = parseArgs({ args: rest, allowPositionals: true, options: {} });
             return await runModels(process.cwd(), {

package/dist/commands/backlog-alias.js

@@ -0,0 +1,21 @@
+// src/commands/backlog-alias.ts
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+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',
+            shell: process.platform === 'win32',
+        });
+        child.on('error', () => resolve(1));
+        child.on('exit', (code) => resolve(code ?? 1));
+    });
+}

package/dist/commands/dashboard.js

@@ -1,38 +1,41 @@
 // src/commands/dashboard.ts
-import { isAbsolute, join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
 import { collectDashboardData } from '../dashboard/data.js';
 import { renderDashboard } from '../dashboard/render.js';
 import { DASHBOARD_PORT, startServeServer } from '../dashboard/server.js';
 import { atomicWrite } from '../lib/atomic.js';
+import { resolveBacklogBin } from '../lib/run.js';
 import { KIT_VERSION } from '../lib/version.js';
 async function regenerateInto(outPath, cwd) {
     const data = collectDashboardData(cwd, { kitVersion: KIT_VERSION });
     atomicWrite(outPath, renderDashboard(data));
 }
-/**
- * Generate dashboard.html for the project; with `{ serve: true }`, start the
- * live-reload server afterwards (the listening socket keeps the process up).
- * Called by `sbl init` with serve disabled.
- */
-export async function generateDashboard(cwd, o) {
-    const outPath = join(cwd, 'dashboard.html');
-    await regenerateInto(outPath, cwd);
-    if (o.serve) {
-        // Dynamic import keeps init resilient if the serve module is unavailable.
-        const specifier = '../dashboard/server.js';
-        const mod = (await import(specifier));
-        if (typeof mod.startServeServer !== 'function') {
-            throw new Error('serve module does not export startServeServer');
-        }
-        await mod.startServeServer(cwd, {
-            port: DASHBOARD_PORT,
-            regenerate: () => regenerateInto(outPath, cwd),
-            openBrowser: true,
+function spawnBacklogBrowser(cwd) {
+    const bin = resolveBacklogBin(cwd);
+    if (!bin) {
+        console.warn('warning: backlog CLI not found; dashboard will serve without the Backlog browser');
+        return;
+    }
+    try {
+        const child = spawn(bin, ['browser', '--no-open', '--non-interactive'], {
+            cwd,
+            detached: true,
+            stdio: 'ignore',
+            shell: process.platform === 'win32',
         });
+        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');
     }
-    return outPath;
 }
-/** CLI entry for `sbl dashboard [--serve] [--port N] [--no-open] [--out FILE]`. */
+/** 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) {
     const values = args.values;
     let port = DASHBOARD_PORT;
@@ -44,26 +47,24 @@ export async function runDashboard(cwd, args) {
         }
         port = parsed;
     }
-    const serve = values['serve'] === true;
     const noOpen = values['no-open'] === true;
-    const outFile = values['out'] === undefined ? 'dashboard.html' : String(values['out']);
-    const outPath = isAbsolute(outFile) ? outFile : resolve(cwd, outFile);
+    const outPath = join(tmpdir(), `sbl-dashboard-${Date.now()}.html`);
     try {
         await regenerateInto(outPath, cwd);
         console.log(`dashboard written: ${outPath}`);
-        if (serve) {
-            console.log(`serving dashboard at http://127.0.0.1:${port}/ (press Ctrl+C to stop)`);
-            await startServeServer(cwd, {
-                port,
-                file: outPath,
-                regenerate: () => regenerateInto(outPath, cwd),
-                openBrowser: !noOpen,
-            });
-        }
+        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;
     }
     catch (err) {
-        console.error(`error: dashboard generation failed (${err instanceof Error ? err.message : String(err)})`);
+        console.error(`error: dashboard serve failed (${err instanceof Error ? err.message : String(err)})`);
         return 1;
     }
 }

package/dist/commands/init.js

@@ -34,10 +34,6 @@ function describeAction(action) {
             return 'install-model-router .super-backlog/models.json';
         case 'install-guard-hook':
             return 'install-guard-hook .git/hooks/pre-commit';
-        case 'install-refresh-hook':
-            return 'install-refresh-hook .git/hooks/post-commit';
-        case 'generate-dashboard':
-            return 'generate-dashboard';
         case 'write':
             return `write ${action.path}`;
     }
@@ -96,8 +92,6 @@ export async function runInit(cwd, args, deps = {}) {
     }
     const pm = rawPm;
     const guard = args.values.guard === true; // opt-in per spec D8
-    const dashboard = args.values['no-dashboard'] !== true;
-    const refreshHook = args.values['no-refresh-hook'] !== true; // default on, opt-out flag
     const dryRun = args.values['dry-run'] === true;
     const models = args.values.models === true ? true : args.values['no-models'] === true ? false : undefined;
     const projectName = args.positionals[0] ?? basename(resolve(cwd));
@@ -121,7 +115,7 @@ export async function runInit(cwd, args, deps = {}) {
         opencodeConfig,
         pkgExists: existsSync(join(cwd, 'package.json')),
     };
-    const opts = { projectName, harnesses, pm, guard, dashboard, refreshHook, skipInstall: false, models };
+    const opts = { projectName, harnesses, pm, guard, skipInstall: false, models };
     const plan = planInit(state, opts, KIT_VERSION);
     if (dryRun) {
         console.log(`dry-run for "${projectName}": ${plan.actions.length} action(s) planned, nothing written`);

package/dist/commands/serve.js

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

package/dist/commands/update.js

@@ -4,7 +4,7 @@ import { basename, join, resolve } from 'node:path';
 import process from 'node:process';
 import { executeActions, findGitDir, InvalidJsonError, validateJsonFile, RefusalError, UpstreamError } from '../init/execute.js';
 import { planInit } from '../init/planner.js';
-import { GUARD_RE, REFRESH_RE } from '../lib/hooks.js';
+import { GUARD_RE } from '../lib/hooks.js';
 import { detectPackageManager } from '../lib/pm.js';
 import { resolveBacklogBin, runCapture } from '../lib/run.js';
 import { KIT_VERSION } from '../lib/version.js';
@@ -13,8 +13,6 @@ const REFRESH_KINDS = new Set([
     'write-claude-pointer',
     'copy-skills',
     'install-guard-hook',
-    'install-refresh-hook',
-    'generate-dashboard',
 ]);
 export function refreshActions(all) {
     return all.filter((action) => REFRESH_KINDS.has(action.kind));
@@ -31,15 +29,6 @@ function guardHookInstalled(cwd) {
         return false;
     return GUARD_RE.test(readFileSync(hookPath, 'utf8'));
 }
-function refreshHookInstalled(cwd) {
-    const gitDir = findGitDir(cwd);
-    if (!gitDir)
-        return false;
-    const hookPath = join(gitDir, 'hooks', 'post-commit');
-    if (!existsSync(hookPath))
-        return false;
-    return REFRESH_RE.test(readFileSync(hookPath, 'utf8'));
-}
 export async function runUpdate(cwd, _args) {
     // Up-front detection-failure check (mirrors uninstall): refuse before mutating anything.
     for (const f of ['package.json', 'opencode.json']) {
@@ -72,8 +61,6 @@ export async function runUpdate(cwd, _args) {
         harnesses: ['opencode', 'claude'],
         pm: 'auto',
         guard: guardHookInstalled(cwd),
-        refreshHook: refreshHookInstalled(cwd),
-        dashboard: existsSync(join(cwd, 'dashboard.html')),
         skipInstall: false,
     };
     const plan = planInit(state, opts, KIT_VERSION);

package/dist/dashboard/data.js

@@ -1,5 +1,5 @@
 // src/dashboard/data.ts
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { resolveBacklogBin, runCapture } from '../lib/run.js';
 import { readSimpleKeys } from '../lib/yamlmini.js';
@@ -159,7 +159,7 @@ export const BUILT_IN_GLOSSARY = [
     { term: 'Backlog.md', definition: 'File-based task management CLI owning specs, statuses and history under backlog/.' },
     { term: 'Superpowers', definition: 'The methodology skill set that decides HOW the work is done.' },
     { term: 'Pipeline', definition: 'The nine workflow phases from Idea to Merge & archive.' },
-    { term: 'Freshness Hook', definition: 'A post-commit git hook that regenerates dashboard.html when commits touch backlog/.' },
+    { term: 'Freshness Hook', definition: 'Run `sbl dashboard` to serve a live dashboard that reloads automatically while the server is running.' },
 ];
 /** Split `## Term` headings plus their following non-heading block into entries; empty sections are skipped. */
 export function parseGlossaryMarkdown(content) {
@@ -216,6 +216,29 @@ function readProjectGlossary(cwd) {
         return [];
     }
 }
+function readDraftFile(path) {
+    const keys = readSimpleKeys(path, ['id', 'title', 'status']);
+    const id = asString(keys.id);
+    const title = asString(keys.title);
+    const status = asString(keys.status);
+    if (!id || !title || !status)
+        return null;
+    return { id, title, status };
+}
+export function readDrafts(cwd) {
+    const draftsDir = join(cwd, 'backlog', 'drafts');
+    if (!existsSync(draftsDir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(draftsDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        const draft = readDraftFile(join(draftsDir, entry.name));
+        if (draft)
+            out.push(draft);
+    }
+    return out.sort((a, b) => a.id.localeCompare(b.id));
+}
 function readProjectIdentity(cwd) {
     const cfg = readSimpleKeys(join(cwd, 'backlog', 'config.yml'), [
         'project_name',
@@ -252,6 +275,7 @@ export function collectDashboardData(cwd, opts) {
         milestones: [],
         tasks: [],
         deps: [],
+        drafts: readDrafts(cwd),
         activity: computeActivity([], today),
         glossary: mergeGlossary(readProjectGlossary(cwd)),
         source: 'fallback-empty',

package/dist/dashboard/server.js

@@ -6,7 +6,182 @@ import { createServer } from 'node:http';
 import { isAbsolute, join } from 'node:path';
 import process from 'node:process';
 import { createModelApiHandler } from '../models/dashboard-api.js';
+import { resolveBacklogBin } from '../lib/run.js';
 export const DASHBOARD_PORT = 6428;
+const WHITELIST = new Map([
+    ['browser', ['browser']],
+    ['board', ['board']],
+]);
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** Safe /api/run handler: only whitelisted backlog subcommands may be spawned. */
+export function createRunApiHandler(cwd) {
+    return async (req, res) => {
+        if (req.url !== '/api/run') {
+            res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end('not found');
+            return;
+        }
+        if (req.method !== 'POST') {
+            res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end('not found');
+            return;
+        }
+        let body;
+        try {
+            body = await readBody(req);
+        }
+        catch {
+            res.writeHead(400, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: 'failed to read body' }));
+            return;
+        }
+        let payload;
+        try {
+            payload = JSON.parse(body);
+        }
+        catch {
+            res.writeHead(400, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: 'invalid json' }));
+            return;
+        }
+        if (!isRecord(payload) || typeof payload.command !== 'string' || !WHITELIST.has(payload.command)) {
+            res.writeHead(400, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: 'unknown command' }));
+            return;
+        }
+        const bin = resolveBacklogBin(cwd);
+        if (!bin) {
+            res.writeHead(503, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: 'backlog cli not found' }));
+            return;
+        }
+        const args = WHITELIST.get(payload.command);
+        try {
+            const child = spawn(bin, args, {
+                cwd,
+                detached: true,
+                stdio: 'ignore',
+                shell: process.platform === 'win32',
+            });
+            child.on('error', () => { });
+            child.unref();
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ ok: true }));
+        }
+        catch (err) {
+            res.writeHead(500, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+        }
+    };
+}
+/** SSE broker: keeps a set of response objects and broadcasts named events. */
+export function createReloadBroker() {
+    const clients = new Set();
+    let closed = false;
+    function handler(req, res) {
+        if (req.url !== '/api/events' || req.method !== 'GET')
+            return false;
+        res.writeHead(200, {
+            'content-type': 'text/event-stream',
+            'cache-control': 'no-cache',
+            connection: 'keep-alive',
+        });
+        res.write(':ok\n\n');
+        clients.add(res);
+        const cleanup = () => {
+            clients.delete(res);
+        };
+        req.on('close', cleanup);
+        req.on('error', cleanup);
+        res.on('close', cleanup);
+        res.on('error', cleanup);
+        return true;
+    }
+    function broadcast(event) {
+        if (closed)
+            return;
+        // A data line is mandatory: per the HTML standard, EventSource never
+        // dispatches an event whose data buffer is empty, so `event: x\n\n`
+        // alone would silently never reach addEventListener('x', ...) clients.
+        const message = `event: ${event}\ndata: {}\n\n`;
+        for (const client of clients) {
+            try {
+                client.write(message);
+            }
+            catch {
+                clients.delete(client);
+            }
+        }
+    }
+    function clientCount() {
+        return clients.size;
+    }
+    function close() {
+        if (closed)
+            return;
+        closed = true;
+        for (const client of clients) {
+            try {
+                client.end();
+            }
+            catch {
+                // ignore
+            }
+        }
+        clients.clear();
+    }
+    return { handler, broadcast, clientCount, close };
+}
+/** Debounced wrapper around a regenerate callback; on success invokes onReload. */
+export function createDebouncedReloader(regenerate, onReload, delayMs) {
+    let timer = null;
+    function trigger() {
+        if (!regenerate)
+            return;
+        if (timer !== null)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            void Promise.resolve()
+                .then(regenerate)
+                .then(() => {
+                onReload();
+            })
+                .catch(() => { });
+        }, delayMs);
+    }
+    function cancel() {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    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)
@@ -43,25 +218,14 @@ export async function startServeServer(cwd, opts = {}) {
     const file = opts.file ?? 'dashboard.html';
     const filePath = isAbsolute(file) ? file : join(cwd, file);
     const regenerate = opts.regenerate;
-    let timer = null;
-    const debouncedRegenerate = () => {
-        if (!regenerate)
-            return;
-        if (timer !== null)
-            clearTimeout(timer);
-        timer = setTimeout(() => {
-            timer = null;
-            void Promise.resolve()
-                .then(regenerate)
-                .catch(() => { }); // regeneration failures never kill the server
-        }, 300);
-    };
+    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 }, debouncedRegenerate);
+            watcher = watch(backlogDir, { persistent: true, recursive: true }, () => reloader.trigger());
             watcher.on('error', () => { }); // e.g. watched dir removed mid-session
         }
         catch {
@@ -71,10 +235,10 @@ export async function startServeServer(cwd, opts = {}) {
     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 modelApi = createModelApiHandler();
+    const apiHandler = createApiHandler(cwd, broker);
     const server = createServer((req, res) => {
         if (req.url?.startsWith('/api/')) {
-            void modelApi(req, res);
+            void apiHandler(req, res);
             return;
         }
         const url = req.url ?? '/';
@@ -114,9 +278,8 @@ export async function startServeServer(cwd, opts = {}) {
         server,
         port,
         close() {
-            if (timer !== null)
-                clearTimeout(timer);
-            timer = null;
+            reloader.cancel();
+            broker.close();
             watcher?.close();
             watcher = null;
             return new Promise((resolveClose) => {