super-backlog 1.1.0 → 1.2.0

package/README.md

@@ -45,7 +45,7 @@ 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:

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,9 +1,8 @@
-#!/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 { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 import { runDashboard } from './commands/dashboard.js';
 import { runDoctor } from './commands/doctor.js';
@@ -11,7 +10,7 @@ import { runInit } from './commands/init.js';
 import { runModels } from './commands/models.js';
 import { runUninstall } from './commands/uninstall.js';
 import { runUpdate } from './commands/update.js';
-import { assertNode20, KIT_VERSION } from './lib/version.js';
+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
 
@@ -64,7 +63,7 @@ export async function runCli(argv) {
         console.log(HELP);
         return 0;
     }
-    void applyVersionHint(KIT_VERSION, {
+    await applyVersionHint(KIT_VERSION, {
         home: homedir(),
         now: () => new Date(),
         fetchLatest: defaultFetchLatest,
@@ -143,15 +142,3 @@ export async function runCli(argv) {
             return 1;
     }
 }
-assertNode20();
-const entry = process.argv[1];
-if (entry && fileURLToPath(import.meta.url) === resolve(entry)) {
-    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/commands/dashboard.js

@@ -81,6 +81,25 @@ function waitForClose(hub) {
         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 {
@@ -150,6 +169,10 @@ export async function runDashboard(cwd, args, deps = {}) {
         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,
@@ -199,8 +222,9 @@ export async function runDashboard(cwd, args, deps = {}) {
     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 hub.close();
+        void shutdown();
     };
     process.once('SIGINT', onSignal);
     process.once('SIGTERM', onSignal);
@@ -211,6 +235,6 @@ export async function runDashboard(cwd, args, deps = {}) {
     finally {
         process.removeListener('SIGINT', onSignal);
         process.removeListener('SIGTERM', onSignal);
-        clearHubState(home, pid);
+        await shutdown();
     }
 }

package/dist/dashboard/backlog-browser.js

@@ -0,0 +1,98 @@
+// src/dashboard/backlog-browser.ts
+import { request } from 'node:http';
+import { createServer } from 'node:net';
+import crossSpawn from 'cross-spawn';
+import { resolveBacklogBin } from '../lib/run.js';
+function defaultSpawn(bin, args, cwd) {
+    const child = crossSpawn(bin, args, { cwd, stdio: 'ignore' });
+    return child;
+}
+function defaultGetFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.once('error', reject);
+        srv.listen(0, '127.0.0.1', () => {
+            const addr = srv.address();
+            const port = addr !== null && typeof addr === 'object' ? addr.port : 0;
+            srv.close(() => resolve(port));
+        });
+    });
+}
+function defaultProbe(url) {
+    return new Promise((resolve) => {
+        const r = request(url, { method: 'GET' }, (res) => {
+            res.resume();
+            resolve((res.statusCode ?? 500) < 500);
+        });
+        r.on('error', () => resolve(false));
+        r.end();
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Manages one `backlog browser` process for one project cwd. */
+export function createBrowserManager(cwd, deps = {}) {
+    const resolveBin = deps.resolveBin ?? resolveBacklogBin;
+    const spawnFn = deps.spawnFn ?? defaultSpawn;
+    const getFreePort = deps.getFreePort ?? defaultGetFreePort;
+    const probe = deps.probe ?? defaultProbe;
+    const timeoutMs = deps.timeoutMs ?? 10_000;
+    const intervalMs = deps.intervalMs ?? 200;
+    let child = null;
+    let url = '';
+    let starting = null;
+    function alive() {
+        return child !== null && child.exitCode === null;
+    }
+    async function start() {
+        const bin = resolveBin(cwd);
+        if (!bin)
+            return { ok: false, code: 503, message: 'backlog cli not found' };
+        let port;
+        try {
+            port = await getFreePort();
+        }
+        catch {
+            return { ok: false, code: 500, message: 'no free port for the backlog browser' };
+        }
+        url = `http://127.0.0.1:${port}/`;
+        const spawned = spawnFn(bin, ['browser', '--port', String(port), '--no-open'], cwd);
+        let spawnFailed = false;
+        spawned.on('error', () => {
+            spawnFailed = true;
+            if (child === spawned)
+                child = null;
+        });
+        child = spawned;
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (spawnFailed || spawned.exitCode !== null)
+                break;
+            if (await probe(url))
+                return { ok: true, url };
+            await sleep(intervalMs);
+        }
+        spawned.kill();
+        if (child === spawned)
+            child = null;
+        return { ok: false, code: 500, message: 'backlog browser did not start' };
+    }
+    return {
+        ensure() {
+            if (alive() && url !== '')
+                return Promise.resolve({ ok: true, url });
+            if (starting === null) {
+                starting = start().finally(() => {
+                    starting = null;
+                });
+            }
+            return starting;
+        },
+        close() {
+            if (alive())
+                child?.kill();
+            child = null;
+        },
+    };
+}

package/dist/dashboard/data.js

@@ -1,7 +1,9 @@
 // src/dashboard/data.ts
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 import { resolveBacklogBin, runCapture } from '../lib/run.js';
+import { isNewerVersion } from '../lib/version-check.js';
 import { readSimpleKeys } from '../lib/yamlmini.js';
 function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
@@ -263,6 +265,18 @@ function readProjectIdentity(cwd) {
     const description = asString(cfg['description']) ?? asString(pkg?.['description']) ?? '';
     return { name, description };
 }
+function readLatestVersion(home, kitVersion) {
+    try {
+        const raw = readFileSync(join(home, '.super-backlog', 'version-check.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed) || typeof parsed.latest !== 'string')
+            return null;
+        return isNewerVersion(parsed.latest, kitVersion) ? parsed.latest : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function collectDashboardData(cwd, opts) {
     const today = opts.today && /^\d{4}-\d{2}-\d{2}$/.test(opts.today.trim())
         ? opts.today.trim()
@@ -271,6 +285,7 @@ export function collectDashboardData(cwd, opts) {
         project: readProjectIdentity(cwd),
         generatedAt: new Date().toISOString(),
         kitVersion: opts.kitVersion,
+        latestVersion: readLatestVersion(opts.home ?? homedir(), opts.kitVersion),
         statuses: [],
         milestones: [],
         tasks: [],

package/dist/dashboard/hub.js

@@ -4,28 +4,26 @@ import { createServer } from 'node:http';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import process from 'node:process';
+import { createBrowserManager } from './backlog-browser.js';
 import { collectDashboardData } from './data.js';
 import { renderDashboard } from './render.js';
-import { createDebouncedReloader, createReloadBroker, createRunApiHandler, DASHBOARD_PORT, recursiveWatchSupported, } from './server.js';
+import { createDebouncedReloader, createReloadBroker, 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';
-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;
-        }
-    }
-    console.warn(WATCH_WARN);
-    return null;
+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}/`;
@@ -66,10 +64,30 @@ 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();
+        entry.browser.close();
     }
     function register(project) {
         let computed;
@@ -82,7 +100,7 @@ export async function startHubServer(opts) {
         if (!computed.ok) {
             return { ok: false, code: 400, message: 'empty slug' };
         }
-        const slug = project.slug ?? computed.slug;
+        const slug = computed.slug;
         if (slug === '') {
             return { ok: false, code: 400, message: 'empty slug' };
         }
@@ -117,14 +135,22 @@ export async function startHubServer(opts) {
             broker,
             reloader,
             watcher: watchBacklog(project.cwd, reloader),
-            runApi: createRunApiHandler(project.cwd),
+            browser: createBrowserManager(project.cwd, opts.browserDeps),
             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') {
@@ -214,8 +240,9 @@ export async function startHubServer(opts) {
         }
         if (rest.startsWith('/api/')) {
             req.url = rest;
-            if (rest === '/api/run') {
-                await entry.runApi(req, res);
+            if (rest === '/api/backlog-browser' && method === 'POST') {
+                const result = await entry.browser.ensure();
+                sendJson(res, result.ok ? 200 : result.code, result);
                 return;
             }
             if (entry.broker.handler(req, res)) {

package/dist/dashboard/render.js

@@ -5,14 +5,14 @@ import { fileURLToPath } from 'node:url';
 /** The nine pipeline phases; must stay consistent with src/templates/workflow-block.md. */
 export const PIPELINE_PHASES = [
     { n: 1, name: 'Idea', gate: 'User states a need; capture it before doing anything else' },
-    { n: 2, name: 'Brainstorming', gate: 'Explore intent, requirements and design before any creative work' },
+    { n: 2, name: 'Brainstorming', gate: 'Explore intent, requirements and design before any creative work', command: '/superpowers:brainstorming' },
     { n: 3, name: 'Design gate', gate: 'Human approves the design document' },
-    { n: 4, name: 'Spec-to-backlog', gate: 'Decompose the approved design into reviewed tasks with acceptance criteria' },
-    { n: 5, name: 'Review gate', gate: 'Human reviews specs and acceptance criteria before any code exists' },
-    { n: 6, name: 'Plan-before-code', gate: 'A written implementation plan is approved by the human' },
-    { n: 7, name: 'TDD implementation', gate: 'Failing test first, then code; one task per session/PR' },
-    { n: 8, name: 'Verification & final summary', gate: 'Run tests/lint/typecheck; verification evidence before success claims' },
-    { n: 9, name: 'Merge & archive', gate: 'Merge the branch, then close/archive the task via the backlog CLI' },
+    { n: 4, name: 'Spec-to-backlog', gate: 'Decompose the approved design into reviewed tasks with acceptance criteria', command: '/spec-to-backlog' },
+    { n: 5, name: 'Review gate', gate: 'Human reviews specs and acceptance criteria before any code exists', command: '/task-review-gate' },
+    { n: 6, name: 'Plan-before-code', gate: 'A written implementation plan is approved by the human', command: '/superpowers:writing-plans' },
+    { n: 7, name: 'TDD implementation', gate: 'Failing test first, then code; one task per session/PR', command: '/superpowers:subagent-driven-development' },
+    { n: 8, name: 'Verification & final summary', gate: 'Run tests/lint/typecheck; verification evidence before success claims', command: '/superpowers:verification-before-completion' },
+    { n: 9, name: 'Merge & archive', gate: 'Merge the branch, then close/archive the task via the backlog CLI', command: 'backlog task archive <id>' },
 ];
 function readTemplate() {
     const here = dirname(fileURLToPath(import.meta.url)); // src/dashboard at dev time, dist/dashboard at runtime

package/dist/dashboard/server.js

@@ -2,83 +2,7 @@
 import { spawn } from 'node:child_process';
 import { isAbsolute, join } from 'node:path';
 import process from 'node:process';
-import crossSpawn from 'cross-spawn';
-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 = crossSpawn(bin, args, {
-                cwd,
-                detached: true,
-                stdio: 'ignore',
-            });
-            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();

package/dist/lib/hub-state.js

@@ -1,5 +1,5 @@
 import { randomBytes } from 'node:crypto';
-import { mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { chmodSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import process from 'node:process';
 import { atomicWrite } from './atomic.js';
@@ -25,7 +25,13 @@ export function readHubState(home) {
 }
 export function writeHubState(home, state) {
     mkdirSync(join(home, '.super-backlog'), { recursive: true });
-    atomicWrite(hubStatePath(home), JSON.stringify(state));
+    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);

package/dist/lib/version-check.js

@@ -2,13 +2,14 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import process from 'node:process';
-import { runCapture } from './run.js';
+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) {
+/** Triple-numeric semver compare; non-numeric parts are treated as not newer. */
+export function isNewerVersion(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)
@@ -45,23 +46,50 @@ function isStale(checkedAt, now) {
     const t = Date.parse(checkedAt);
     if (Number.isNaN(t))
         return true;
-    return now.getTime() - t > DAY_MS;
+    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 npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-    const work = Promise.resolve().then(() => {
-        const r = runCapture(npm, ['view', 'super-backlog', 'version'], process.cwd());
-        if (r.status !== 0)
-            return null;
-        const line = r.stdout.split(/\r?\n/).find((l) => l.trim() !== '');
-        if (!line)
-            return null;
-        const v = line.trim();
-        return v === '' ? null : v;
+    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((resolve) => {
-        timer = setTimeout(() => resolve(null), FETCH_TIMEOUT_MS);
+    const timeout = new Promise((resolveTimeout) => {
+        timer = setTimeout(() => resolveTimeout(null), FETCH_TIMEOUT_MS);
         timer.unref();
     });
     try {
@@ -79,7 +107,7 @@ 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)) {
+    if (cache && isNewerVersion(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())) {

package/dist/templates/dashboard.html

@@ -122,6 +122,38 @@
     #task-dialog[open] { animation: none; }
   }
   @keyframes sbl-dialog-in { from { transform: scale(.96); opacity: 0; } to { transform: none; opacity: 1; } }
+
+  /* ---------- Backlog browser overlay ---------- */
+  #backlog-dialog {
+    width: 96vw; height: 94vh; max-width: none; max-height: none; padding: 0;
+    display: none; flex-direction: column;
+    border: 1px solid var(--line-strong); border-radius: 14px;
+    background: var(--surface); color: var(--text);
+    box-shadow: 0 24px 80px rgba(0,0,0,.55);
+  }
+  #backlog-dialog[open] { display: flex; animation: sbl-dialog-in .18s ease-out; }
+  #backlog-dialog::backdrop { background: rgba(4,7,12,.65); backdrop-filter: blur(2px); }
+  @media (prefers-reduced-motion: reduce) {
+    #backlog-dialog[open] { animation: none; }
+  }
+  .backlog-dialog-bar {
+    display: flex; align-items: center; gap: 14px; padding: 8px 14px;
+    border-bottom: 1px solid var(--line-strong); background: var(--surface-2);
+  }
+  .backlog-dialog-title { font-weight: 700; font-size: .9rem; }
+  .backlog-dialog-bar a {
+    margin-left: auto; font-family: var(--mono); font-size: .72rem;
+    color: var(--muted); text-decoration: none;
+  }
+  .backlog-dialog-bar a:hover { color: var(--accent); }
+  #backlog-close {
+    font: inherit; font-size: 1.1rem; line-height: 1; cursor: pointer;
+    color: var(--muted); background: none; border: 1px solid transparent;
+    border-radius: 8px; padding: 4px 10px;
+  }
+  #backlog-close:hover { color: var(--text); border-color: var(--line); }
+  #backlog-close:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+  #backlog-frame { flex: 1; width: 100%; border: 0; background: var(--bg); }
   .dialog-content { padding: 22px 24px 28px; }
   .detail-head { display: flex; align-items: center; gap: 10px; margin-bottom: 10px; }
   .detail-id { font-family: var(--mono); color: var(--accent); font-weight: 700; }
@@ -245,23 +277,75 @@
   .spark-axis { fill: var(--dim); font-size: 10px; font-family: var(--mono); }
 
   /* ---------- Pipeline stepper ---------- */
-  .stepper { display: grid; grid-template-columns: repeat(9, minmax(0, 1fr)); margin: 4px 0 8px; }
-  .step { position: relative; min-width: 0; padding: 0 3px; text-align: center; }
+  .stepper { display: grid; grid-template-columns: repeat(9, minmax(0, 1fr)); gap: 2px; margin: 4px 0 6px; }
+  .step {
+    position: relative; min-width: 0; padding: 10px 4px 12px; text-align: center;
+    background: none; border: 1px solid transparent; border-radius: 10px; cursor: pointer;
+    font: inherit; color: inherit; transition: background .15s ease, border-color .15s ease;
+  }
   .step::before {
-    content: ""; position: absolute; top: 15px; left: -50%; width: 100%; height: 2px;
+    content: ""; position: absolute; top: 27px; left: -50%; width: 100%; height: 2px;
     background: var(--line-strong); z-index: 0;
   }
   .step:first-child::before { display: none; }
+  .step:hover { background: var(--surface-2); border-color: var(--line); }
+  .step:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+  .step[aria-expanded="true"] { background: var(--accent-dim); border-color: var(--accent); }
+  .step[aria-expanded="true"].gate { border-color: var(--warn); background: var(--warn-bg); }
   .step-num {
-    position: relative; z-index: 1; width: 32px; height: 32px; margin: 0 auto 8px;
+    position: relative; z-index: 1; width: 34px; height: 34px; margin: 0 auto 10px;
     display: flex; align-items: center; justify-content: center;
-    border-radius: 50%; font-family: var(--mono); font-size: .82rem; font-weight: 700;
+    border-radius: 50%; font-family: var(--mono); font-size: .9rem; font-weight: 700;
     background: var(--surface-2); border: 2px solid var(--line-strong); color: var(--muted);
   }
   .step.gate .step-num { border-color: var(--warn); color: var(--warn); background: var(--warn-bg); box-shadow: 0 0 14px rgba(255,180,84,.25); }
-  .step-label { font-size: .63rem; color: var(--muted); line-height: 1.35; }
-  .step-label b { display: block; color: var(--text); font-size: .71rem; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-  .step.gate .step-label b { color: var(--warn); }
+  .step-label {
+    display: block; font-size: .8rem; font-weight: 600; color: var(--text); line-height: 1.3;
+    overflow-wrap: break-word;
+  }
+  .step.gate .step-label { color: var(--warn); }
+
+  /* ---------- Phase detail panel ---------- */
+  #phase-detail {
+    margin: 2px 0 12px; padding: 14px 18px; border: 1px solid var(--line-strong);
+    border-left: 3px solid var(--accent); border-radius: 10px; background: var(--surface);
+  }
+  #phase-detail.open { animation: phasein .18s ease; }
+  #phase-detail.gate { border-left-color: var(--warn); }
+  @keyframes phasein { from { opacity: 0; transform: translateY(-4px); } to { opacity: 1; transform: none; } }
+  .phase-detail-head { display: flex; align-items: baseline; gap: 10px; margin-bottom: 6px; }
+  .phase-detail-num { font-family: var(--mono); font-size: .85rem; font-weight: 700; color: var(--accent); }
+  #phase-detail.gate .phase-detail-num { color: var(--warn); }
+  .phase-detail-name { font-size: 1rem; font-weight: 700; }
+  .phase-detail-gate { margin: 0 0 10px; font-size: .88rem; line-height: 1.55; color: var(--muted); }
+  .phase-cmd {
+    display: inline-flex; align-items: center; gap: 10px; padding: 7px 12px;
+    font: inherit; cursor: pointer; border-radius: 8px;
+    background: var(--surface-2); border: 1px solid var(--line-strong); color: var(--text);
+    transition: border-color .15s ease;
+  }
+  .phase-cmd:hover { border-color: var(--accent); }
+  .phase-cmd:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+  .phase-cmd .cmd-line { font-family: var(--mono); font-size: .8rem; color: var(--accent); }
+  .phase-cmd .cmd-title { font-size: .72rem; color: var(--dim); text-transform: uppercase; letter-spacing: .06em; }
+  @media (prefers-reduced-motion: reduce) {
+    .step, .phase-cmd { transition: none; }
+    #phase-detail.open { animation: none; }
+  }
+
+  /* ---------- Sidebar version + update badge ---------- */
+  .side-version {
+    display: flex; align-items: center; gap: 8px; margin: 6px 0 2px;
+    font-family: var(--mono); font-size: .78rem; color: var(--dim);
+  }
+  .update-badge {
+    font: inherit; font-family: var(--mono); font-size: .68rem; cursor: pointer;
+    color: var(--warn); background: var(--warn-bg); border: 1px solid var(--warn);
+    border-radius: 999px; padding: 2px 9px; transition: box-shadow .15s ease;
+  }
+  .update-badge:hover { box-shadow: 0 0 10px rgba(255,180,84,.3); }
+  .update-badge:focus-visible { outline: 2px solid var(--warn); outline-offset: 2px; }
+  .update-badge .cmd-title { font-size: inherit; font-weight: 600; color: inherit; }
 
   /* ---------- Dependency flow ---------- */
   .sub-head {
@@ -302,6 +386,7 @@
 <aside class="sbl-side">
   <div class="brand"><span class="brand-glyph">●</span><b>__PROJECT_NAME__</b></div>
   <div class="kicker">SUPERPOWERS × BACKLOG.MD</div>
+  <div class="side-version" id="side-version"><span>v__KIT_VERSION__</span></div>
   <nav aria-label="Dashboard sections">
     <a href="#sec-01"><span class="n">01</span>Board &amp; Quick Actions</a>
     <a href="#sec-02"><span class="n">02</span>Status</a>
@@ -322,14 +407,12 @@
 <main>
 
 <section id="sec-01">
-  <div class="sec-head"><span class="sec-num">01</span><h2>Board &amp; Quick Actions</h2><span class="tagline">commands &middot; board mirror only</span></div>
+  <div class="sec-head"><span class="sec-num">01</span><h2>Board &amp; Quick Actions</h2><span class="tagline">the full Backlog.md UI &middot; one click away</span></div>
   <div id="quickactions" class="mount">
     <div class="cmd-row" id="cmd-buttons">
-      <button type="button" class="cmd-btn" data-cmd="browser"><span class="cmd-title">Backlog Browser</span><span class="cmd-line">backlog browser</span></button>
-      <button type="button" class="cmd-btn" data-cmd="board"><span class="cmd-title">Backlog Board</span><span class="cmd-line">backlog board</span></button>
-      <button type="button" class="cmd-btn" data-copy="sbl dashboard"><span class="cmd-title">Live Dashboard</span><span class="cmd-line">sbl dashboard</span></button>
+      <button type="button" class="cmd-btn" id="backlog-btn"><span class="cmd-title">Backlog</span><span class="cmd-line">board &middot; tasks &middot; docs &middot; decisions</span></button>
     </div>
-    <p class="hint">The board mirrors Backlog.md &mdash; it never writes execution state.</p>
+    <p class="hint">Opens the Backlog.md browser in an overlay &mdash; served locally per project, started on demand.</p>
   </div>
   <div id="drafts" class="mount">
     <h3 class="sub-head">Drafts</h3>
@@ -373,8 +456,9 @@
 </section>
 
 <section id="sec-05">
-  <div class="sec-head"><span class="sec-num">05</span><h2>Feature Cycle</h2><span class="tagline">idea &rarr; merge &middot; every <span class="term" data-term="Review Gate">Review Gate</span> included</span></div>
+  <div class="sec-head"><span class="sec-num">05</span><h2>Feature Cycle</h2><span class="tagline">idea &rarr; merge &middot; every <span class="term" data-term="Review Gate">Review Gate</span> included &middot; click a step for details</span></div>
   <div id="stepper" class="mount"></div>
+  <div id="phase-detail" hidden></div>
   <h3 class="sub-head">Flow</h3>
   <div id="depgraph" class="mount"></div>
 </section>
@@ -399,6 +483,15 @@
 </div>
 
 <dialog id="task-dialog" aria-label="Task details"></dialog>
+
+<dialog id="backlog-dialog" aria-label="Backlog browser">
+  <div class="backlog-dialog-bar">
+    <span class="backlog-dialog-title">Backlog</span>
+    <a id="backlog-open-tab" href="#" target="_blank" rel="noopener">open in new tab</a>
+    <button type="button" id="backlog-close" aria-label="Close">&#215;</button>
+  </div>
+  <iframe id="backlog-frame" title="Backlog.md browser"></iframe>
+</dialog>
 <div id="sbl-tip" role="tooltip" hidden></div>
 
 <script type="application/json" id="sbl-data">__SBL_DATA_JSON__</script>
@@ -421,6 +514,16 @@
     badge.textContent = data.source === 'fallback-empty' ? 'no live data' : 'live backlog data';
   }
 
+  var sideVersion = $('#side-version');
+  if (sideVersion && data.latestVersion) {
+    var upd = el('button', 'update-badge');
+    upd.type = 'button';
+    upd.appendChild(el('span', 'cmd-title', 'v' + data.latestVersion + ' available'));
+    upd.setAttribute('data-tip', 'Update: npm i -g super-backlog (click to copy)');
+    upd.addEventListener('click', function () { copyCommand(upd, 'npm i -g super-backlog'); });
+    sideVersion.appendChild(upd);
+  }
+
   var KEYS = ['id', 'title', 'status', 'milestone', 'priority', 'assignee', 'updated'];
   var state = { key: 'id', dir: 1, query: '', status: null, hoverStatus: null };
   function field(task, key) {
@@ -511,26 +614,51 @@
   /* ---------- Quick action buttons ---------- */
   function cmdFeedback(btn, text) {
     var title = btn.querySelector('.cmd-title');
-    if (!title || btn.getAttribute('data-busy')) return;
-    btn.setAttribute('data-busy', '1');
-    var orig = title.textContent;
+    if (!title) return;
+    if (btn.__sblFbTimer) {
+      clearTimeout(btn.__sblFbTimer); /* newer feedback overrides the pending one */
+    } else {
+      btn.__sblFbOrig = title.textContent;
+    }
     title.textContent = text;
-    setTimeout(function () { title.textContent = orig; btn.removeAttribute('data-busy'); }, 1200);
+    btn.__sblFbTimer = setTimeout(function () {
+      title.textContent = btn.__sblFbOrig;
+      btn.__sblFbTimer = null;
+    }, 1200);
   }
   function copyCommand(btn, command) {
     if (navigator.clipboard) navigator.clipboard.writeText(command).catch(function () {});
     cmdFeedback(btn, 'copied \u2713');
   }
-  document.querySelectorAll('#cmd-buttons .cmd-btn').forEach(function (b) {
-    b.addEventListener('click', function () {
-      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 }) })
-        .then(function (res) { if (!res.ok) throw new Error('run failed'); cmdFeedback(b, 'started \u2713'); })
-        .catch(function () {});
+  var backlogBtn = document.getElementById('backlog-btn');
+  var backlogDialog = document.getElementById('backlog-dialog');
+  var backlogFrame = document.getElementById('backlog-frame');
+  var backlogTab = document.getElementById('backlog-open-tab');
+  function openBacklog(url) {
+    if (!backlogDialog || !backlogFrame) return;
+    if (backlogFrame.getAttribute('src') !== url) backlogFrame.setAttribute('src', url);
+    if (backlogTab) backlogTab.setAttribute('href', url);
+    backlogDialog.showModal();
+  }
+  if (backlogBtn) {
+    backlogBtn.addEventListener('click', function () {
+      cmdFeedback(backlogBtn, 'starting\u2026');
+      fetch('api/backlog-browser', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' })
+        .then(function (res) { return res.json().then(function (data) { return { ok: res.ok, data: data }; }); })
+        .then(function (r) {
+          if (!r.ok || !r.data || !r.data.url) throw new Error('start failed');
+          openBacklog(r.data.url);
+        })
+        .catch(function () { cmdFeedback(backlogBtn, 'failed \u2717'); });
     });
-  });
+  }
+  var backlogClose = document.getElementById('backlog-close');
+  if (backlogClose && backlogDialog) {
+    backlogClose.addEventListener('click', function () { backlogDialog.close(); });
+    backlogDialog.addEventListener('click', function (e) {
+      if (e.target === backlogDialog) backlogDialog.close();
+    });
+  }
 
   /* ---------- Drafts ---------- */
   function renderDrafts(drafts) {
@@ -702,23 +830,60 @@
     mount.appendChild(svg);
   }
 
+  function renderPhaseDetail(panel, p, isGate) {
+    panel.textContent = '';
+    panel.classList.toggle('gate', isGate);
+    var head = el('div', 'phase-detail-head');
+    head.appendChild(el('span', 'phase-detail-num', String(p.n).padStart(2, '0')));
+    head.appendChild(el('span', 'phase-detail-name', p.name));
+    panel.appendChild(head);
+    panel.appendChild(el('p', 'phase-detail-gate', p.gate));
+    if (p.command) {
+      var cmd = el('button', 'phase-cmd');
+      cmd.type = 'button';
+      cmd.appendChild(el('span', 'cmd-line', p.command));
+      cmd.appendChild(el('span', 'cmd-title', 'copy'));
+      cmd.addEventListener('click', function () { copyCommand(cmd, p.command); });
+      panel.appendChild(cmd);
+    }
+    panel.hidden = false;
+    panel.classList.remove('open');
+    void panel.offsetWidth; /* restart the open animation on re-render */
+    panel.classList.add('open');
+  }
+
   function renderStepper(mount, phases) {
     mount.textContent = '';
     if (!phases || phases.length === 0) {
       mount.appendChild(el('p', 'hint', 'Pipeline unavailable.'));
       return;
     }
+    var panel = document.getElementById('phase-detail');
     var wrap = el('div', 'stepper');
+    var current = null;
     phases.forEach(function (p) {
-      var step = el('div', 'step' + (/gate/i.test(String(p.name)) ? ' gate' : ''));
+      var isGate = /gate/i.test(String(p.name));
+      var step = el('button', 'step' + (isGate ? ' gate' : ''));
+      step.type = 'button';
       step.setAttribute('data-phase', p.n);
+      step.setAttribute('aria-expanded', 'false');
+      step.setAttribute('aria-controls', 'phase-detail');
       step.appendChild(el('div', 'step-num', String(p.n)));
-      var lab = el('div', 'step-label');
-      var b = document.createElement('b');
-      b.textContent = p.name;
-      lab.appendChild(b);
-      lab.appendChild(document.createTextNode(p.gate));
-      step.appendChild(lab);
+      step.appendChild(el('span', 'step-label', p.name));
+      step.addEventListener('click', function () {
+        if (!panel) return;
+        var wasOpen = current === step;
+        wrap.querySelectorAll('.step').forEach(function (s) { s.setAttribute('aria-expanded', 'false'); });
+        if (wasOpen) {
+          panel.hidden = true;
+          panel.classList.remove('open');
+          current = null;
+          return;
+        }
+        step.setAttribute('aria-expanded', 'true');
+        current = step;
+        renderPhaseDetail(panel, p, isGate);
+      });
       wrap.appendChild(step);
     });
     mount.appendChild(wrap);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-backlog",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "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));
-    });
-}