super-backlog 1.3.0 → 1.3.2

package/README.md

@@ -73,7 +73,9 @@ sbl dashboard                   # live Project Dashboard on http://localhost:642
 | `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]`. 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]` (alias: `sbl db`). See `sbl help` for every flag.
+
+`sbl update` first self-updates a globally installed CLI to the latest npm version and re-runs itself (opt out with `--no-self` or `SBL_SKIP_UPDATE_CHECK`), then refreshes injected files.
 
 ## Model router (opt-in)
 
@@ -97,7 +99,7 @@ The router is fully owned by super-backlog and removed by `sbl uninstall`. See t
 
 ## Project Dashboard
 
-`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.
+`sbl dashboard` starts a local hub that serves an HTS-style cockpit (light/dark theme toggle) rendered from your Backlog data in eight sections — Board & Quick Actions, Status (KPI tiles, donut, and an aging strip for open tasks), Feature Cycle (pipeline stepper plus an Up Next / Blocked flow view from task dependencies), Milestones, Drafts (click a card for details), Tasks (sortable/filterable table; click a row to open a modal detail view with acceptance criteria and dependencies), Activity (a 26-week calendar heatmap; click a day for its tasks), 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). Typefaces load from Google Fonts with full system fallbacks — the one external resource; everything else is inline, and the dashboard still renders offline. 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
 

package/dist/cli.js

@@ -20,7 +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)
+  dashboard   Start the project dashboard server (live-reload) (alias: db)
   models      Manage the model router (show, enable, disable, discover)
   doctor      Check the environment (node, PowerShell policy, backlog CLI)
 
@@ -38,7 +38,7 @@ uninstall options:
   --fix-all                       Also remove the global npm package (no prompts)
 
 update options:
-  (none)                          Refreshes injected files, skills, hook; prints upstream versions
+  --no-self                       Skip self-updating the CLI before refreshing
 
 dashboard options:
   --port <n>                      Port for the dashboard server (default: 6428)
@@ -102,12 +102,17 @@ export async function runCli(argv) {
             });
         }
         case 'update': {
-            const parsed = parseArgs({ args: rest, allowPositionals: true, options: {} });
+            const parsed = parseArgs({
+                args: rest,
+                allowPositionals: true,
+                options: { 'no-self': { type: 'boolean' } },
+            });
             return await runUpdate(process.cwd(), {
                 values: parsed.values,
                 positionals: parsed.positionals,
             });
         }
+        case 'db':
         case 'dashboard': {
             const parsed = parseArgs({
                 args: rest,

package/dist/commands/dashboard.js

@@ -11,6 +11,9 @@ import { atomicWrite } from '../lib/atomic.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';
+/** Max time to wait for an outdated hub to exit after killPid, in 100ms polls. */
+const STOP_POLL_MAX_ATTEMPTS = 50;
+const STOP_POLL_INTERVAL_MS = 100;
 async function regenerateInto(outPath, cwd) {
     const data = collectDashboardData(cwd, { kitVersion: KIT_VERSION });
     atomicWrite(outPath, renderDashboard(data));
@@ -151,6 +154,9 @@ export async function runDashboard(cwd, args, deps = {}) {
     const attach = deps.attach ?? defaultAttach;
     const openBrowser = deps.openBrowser ?? defaultOpenBrowser;
     const pid = (deps.nowPid ?? (() => process.pid))();
+    const isAlive = deps.isAlive ?? isPidAlive;
+    const killPid = deps.killPid ?? ((p) => { process.kill(p); });
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     let slugResult;
     try {
         slugResult = projectSlug(cwd);
@@ -165,22 +171,44 @@ export async function runDashboard(cwd, args, deps = {}) {
     }
     const slug = slugResult.slug;
     const state = readHubState(home);
-    if (state !== null && isPidAlive(state.pid)) {
+    if (state !== null && isAlive(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}`);
+                const statusJson = typeof status.json === 'object' && status.json !== null
+                    ? status.json
+                    : undefined;
+                const liveVersion = typeof statusJson?.version === 'string' ? statusJson.version : undefined;
+                const effectiveVersion = liveVersion ?? state.version;
+                if (effectiveVersion === KIT_VERSION) {
+                    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,
+                    });
+                }
+                console.error(`hub v${effectiveVersion ?? 'unknown'} does not match this CLI (v${KIT_VERSION}) — restarting it`);
+                killPid(state.pid);
+                let dead = !isAlive(state.pid);
+                for (let attempt = 0; !dead && attempt < STOP_POLL_MAX_ATTEMPTS; attempt++) {
+                    await sleep(STOP_POLL_INTERVAL_MS);
+                    dead = !isAlive(state.pid);
+                }
+                if (dead) {
+                    clearHubState(home, state.pid);
+                    // fall through to the fresh-start path below
+                }
+                else {
+                    console.error(`error: could not stop the outdated hub (pid ${state.pid}) — stop it manually and re-run`);
                     return 1;
                 }
-                return await attachToHub({
-                    cwd,
-                    port: state.port,
-                    token: state.token,
-                    attach,
-                    openBrowser,
-                    noOpen,
-                });
             }
         }
         catch {
@@ -206,7 +234,7 @@ export async function runDashboard(cwd, args, deps = {}) {
         console.error(`error: dashboard serve failed (${err instanceof Error ? err.message : String(err)})`);
         return 1;
     }
-    writeHubState(home, { pid, port: hub.port, token });
+    writeHubState(home, { pid, port: hub.port, token, version: KIT_VERSION });
     const result = hub.register({ cwd, file: outPath, regenerate });
     if (!result.ok) {
         await hub.close();

package/dist/commands/update.js

@@ -1,13 +1,86 @@
 // src/commands/update.ts
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import process from 'node:process';
+import spawn from 'cross-spawn';
 import { executeActions, findGitDir, InvalidJsonError, validateJsonFile, RefusalError, UpstreamError } from '../init/execute.js';
 import { planInit } from '../init/planner.js';
 import { GUARD_RE } from '../lib/hooks.js';
 import { detectPackageManager } from '../lib/pm.js';
 import { resolveBacklogBin, runCapture } from '../lib/run.js';
+import { detectInstallKind, runSelfUpdate } from '../lib/self-update.js';
 import { KIT_VERSION } from '../lib/version.js';
+import { fetchLatestVersion } from '../lib/version-check.js';
+/** Longer than the startup version-hint fetch: this one blocks `sbl update` directly. */
+const SELF_UPDATE_FETCH_TIMEOUT_MS = 10000;
+function resolveGlobalRoot(cwd) {
+    const r = runCapture('npm', ['root', '-g'], cwd);
+    if (r.status !== 0)
+        return null;
+    const line = firstLine(r.stdout);
+    return line === '' ? null : line;
+}
+function resolveBinRealPath() {
+    const argvBin = process.argv[1];
+    if (!argvBin)
+        return null;
+    try {
+        return realpathSync(argvBin);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Runs the self-update check/install and, when a new version was installed,
+ * re-execs the new binary once (env-guarded via SBL_SELF_UPDATED) and
+ * returns its exit code. Returns null when the caller should fall through
+ * to the normal refresh (no update available, offline, install failed, or
+ * the update was skipped entirely).
+ */
+async function maybeSelfUpdate(cwd, args, override) {
+    const skip = args.values['no-self'] === true ||
+        Boolean(process.env.SBL_SELF_UPDATED) ||
+        Boolean(process.env.SBL_SKIP_UPDATE_CHECK) ||
+        Boolean(process.env.SBL_FORCE_OFFLINE);
+    if (skip)
+        return null;
+    const binRealPath = override.binRealPath !== undefined ? override.binRealPath : resolveBinRealPath();
+    const globalRoot = override.globalRoot !== undefined ? override.globalRoot : resolveGlobalRoot(cwd);
+    const installKind = binRealPath === null ? 'unknown' : detectInstallKind(binRealPath, cwd, globalRoot);
+    const fetchLatest = override.fetchLatest ?? (() => fetchLatestVersion(SELF_UPDATE_FETCH_TIMEOUT_MS));
+    const npmInstallGlobal = override.npmInstallGlobal ?? ((spec) => runCapture('npm', ['i', '-g', spec], cwd));
+    const result = await runSelfUpdate({
+        installed: KIT_VERSION,
+        fetchLatest,
+        installKind,
+        npmInstallGlobal,
+        log: (line) => console.log(line),
+        warn: (line) => console.warn(`warning: ${line}`),
+    });
+    if (result.kind !== 'updated')
+        return null;
+    // npm rewrites the global package's files in place, so process.argv[1]
+    // still points at a valid path after the install -- re-resolve anyway in
+    // case the realpath target moved (e.g. a version-pinned symlink).
+    const updatedBinPath = override.binRealPath !== undefined ? override.binRealPath : resolveBinRealPath();
+    if (updatedBinPath === null)
+        return null; // can't re-exec without a bin path; fall through on the old version
+    const spawnSelf = override.spawnSelf ??
+        ((binPath, rArgs, execCwd, env) => {
+            const r = spawn.sync(process.execPath, [binPath, 'update', ...rArgs], {
+                cwd: execCwd,
+                stdio: 'inherit',
+                env,
+            });
+            return { status: r.status ?? 1 };
+        });
+    const res = spawnSelf(updatedBinPath, args.positionals, cwd, {
+        ...process.env,
+        SBL_SELF_UPDATED: '1',
+    });
+    return res.status ?? 1;
+}
 const REFRESH_KINDS = new Set([
     'inject-agents-block',
     'write-claude-pointer',
@@ -29,7 +102,10 @@ function guardHookInstalled(cwd) {
         return false;
     return GUARD_RE.test(readFileSync(hookPath, 'utf8'));
 }
-export async function runUpdate(cwd, _args) {
+export async function runUpdate(cwd, args, selfUpdateOverride = {}) {
+    const selfUpdateExitCode = await maybeSelfUpdate(cwd, args, selfUpdateOverride);
+    if (selfUpdateExitCode !== null)
+        return selfUpdateExitCode;
     // Up-front detection-failure check (mirrors uninstall): refuse before mutating anything.
     for (const f of ['package.json', 'opencode.json']) {
         const p = join(cwd, f);
@@ -100,14 +176,17 @@ export async function runUpdate(cwd, _args) {
             warnings.push(`\`${bin} --version\` failed with exit code ${local.status}`);
         }
     }
+    const probePublished = selfUpdateOverride.probePublished ??
+        (() => {
+            // test seam: SBL_FORCE_OFFLINE makes e2e runs take the offline path deterministically
+            if (process.env.SBL_FORCE_OFFLINE)
+                throw new Error('forced offline');
+            const view = runCapture('npm', ['view', 'backlog.md', 'version'], cwd);
+            return view.status === 0 ? firstLine(view.stdout) : null;
+        });
     let published = null;
     try {
-        // test seam: SBL_FORCE_OFFLINE makes e2e runs take the offline path deterministically
-        if (process.env.SBL_FORCE_OFFLINE)
-            throw new Error('forced offline');
-        const view = runCapture('npm', ['view', 'backlog.md', 'version'], cwd);
-        if (view.status === 0)
-            published = firstLine(view.stdout);
+        published = probePublished();
     }
     catch {
         published = null;

package/dist/dashboard/data.js

@@ -5,6 +5,7 @@ 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';
+import { computeKpis } from './metrics.js';
 function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -70,6 +71,7 @@ export function normalizeTasks(rawTasks) {
         status: asString(t['status']) ?? 'Unknown',
         priority: asString(t['priority']),
         assignee: firstAssignee(t),
+        created: asString(t['createdAt']) ?? asString(t['created_at']) ?? asString(t['created']),
         updated: asString(t['updatedAt']) ?? asString(t['updated_at']) ?? asString(t['updated']),
         milestone: asString(t['milestone']),
         description: asString(t['description']),
@@ -140,20 +142,24 @@ function shiftDay(day, deltaDays) {
     const [y, mo, d] = day.split('-').map(Number);
     return new Date(Date.UTC(y, mo - 1, d) + deltaDays * 86400000).toISOString().slice(0, 10);
 }
-/** Bucket tasks into exactly 30 UTC daily buckets ending at `today`, oldest first. */
+export const ACTIVITY_DAYS = 182;
+/** Bucket tasks into exactly ACTIVITY_DAYS UTC daily buckets ending at `today`, oldest first. */
 export function computeActivity(rawTasks, today) {
-    const counts = new Map();
+    const byDay = new Map();
     for (const t of rawTasks) {
-        const day = isoDay(asString(t['updated_at']) ?? asString(t['updated'])) ??
-            isoDay(asString(t['created_at'])) ??
+        const day = isoDay(asString(t['updatedAt']) ?? asString(t['updated_at']) ?? asString(t['updated'])) ??
+            isoDay(asString(t['createdAt']) ?? asString(t['created_at'])) ??
             today;
-        counts.set(day, (counts.get(day) ?? 0) + 1);
+        const ids = byDay.get(day) ?? [];
+        ids.push(asString(t['id']) ?? '');
+        byDay.set(day, ids);
     }
-    const start = shiftDay(today, -29);
+    const start = shiftDay(today, -(ACTIVITY_DAYS - 1));
     const out = [];
-    for (let i = 0; i < 30; i++) {
+    for (let i = 0; i < ACTIVITY_DAYS; i++) {
         const date = shiftDay(start, i);
-        out.push({ date, count: counts.get(date) ?? 0 });
+        const ids = byDay.get(date) ?? [];
+        out.push({ date, count: ids.length, ids });
     }
     return out;
 }
@@ -230,13 +236,33 @@ function readProjectGlossary(cwd) {
     }
 }
 function readDraftFile(path) {
-    const keys = readSimpleKeys(path, ['id', 'title', 'status']);
+    const keys = readSimpleKeys(path, [
+        'id', 'title', 'status', 'priority', 'assignee',
+        'created_date', 'updated_date', 'created', 'updated',
+    ]);
     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 };
+    let detail = { acs: [] };
+    try {
+        detail = parseTaskFile(readFileSync(path, 'utf8'));
+    }
+    catch {
+        // keys-only draft when the file cannot be re-read
+    }
+    return {
+        id,
+        title,
+        status,
+        description: detail.description,
+        priority: asString(keys.priority),
+        assignee: asString(keys.assignee),
+        created: asString(keys['created_date']) ?? asString(keys['created']),
+        updated: asString(keys['updated_date']) ?? asString(keys['updated']),
+        acs: detail.acs,
+    };
 }
 export function readDrafts(cwd) {
     const draftsDir = join(cwd, 'backlog', 'drafts');
@@ -353,6 +379,7 @@ export function collectDashboardData(cwd, opts) {
     const today = opts.today && /^\d{4}-\d{2}-\d{2}$/.test(opts.today.trim())
         ? opts.today.trim()
         : new Date().toISOString().slice(0, 10);
+    const activity = computeActivity([], today);
     const base = {
         project: readProjectIdentity(cwd),
         generatedAt: new Date().toISOString(),
@@ -363,8 +390,9 @@ export function collectDashboardData(cwd, opts) {
         tasks: [],
         deps: [],
         drafts: readDrafts(cwd),
-        activity: computeActivity([], today),
+        activity,
         glossary: mergeGlossary(readProjectGlossary(cwd)),
+        kpis: computeKpis([], [], activity, today),
         source: 'fallback-empty',
     };
     try {
@@ -376,13 +404,16 @@ export function collectDashboardData(cwd, opts) {
             return base;
         const rawTasks = parseTasksJson(res.stdout);
         const tasks = enrichTasksFromFiles(cwd, normalizeTasks(rawTasks));
+        const deps = computeDeps(rawTasks);
+        const taskActivity = computeActivity(rawTasks, today);
         return {
             ...base,
             tasks,
             statuses: computeStatuses(tasks),
             milestones: computeMilestones(tasks),
-            deps: computeDeps(rawTasks),
-            activity: computeActivity(rawTasks, today),
+            deps,
+            activity: taskActivity,
+            kpis: computeKpis(tasks, deps, taskActivity, today),
             source: 'backlog-json',
         };
     }

package/dist/dashboard/hub.js

@@ -166,7 +166,7 @@ export async function startHubServer(opts) {
                 sendText(res, 401, 'unauthorized');
                 return;
             }
-            sendJson(res, 200, { pid: process.pid, port });
+            sendJson(res, 200, { pid: process.pid, port, version: KIT_VERSION });
             return;
         }
         if (pathname === '/api/hub/register' && method === 'POST') {

package/dist/dashboard/metrics.js

@@ -0,0 +1,97 @@
+function isDone(status) {
+    const s = status.toLowerCase();
+    return s === 'done' || s === 'complete' || s === 'completed';
+}
+function isWip(status) {
+    const s = status.toLowerCase();
+    return s.includes('progress') || s.includes('review');
+}
+function utcDay(value) {
+    if (!value)
+        return null;
+    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(value.trim());
+    if (m)
+        return Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    const t = Date.parse(value);
+    if (Number.isNaN(t))
+        return null;
+    const d = new Date(t);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+}
+const DAY_MS = 86_400_000;
+export function computeKpis(tasks, deps, activity, today) {
+    const todayMs = utcDay(today) ?? Date.UTC(1970, 0, 1);
+    const total = tasks.length;
+    const doneTasks = tasks.filter((t) => isDone(t.status));
+    const done = doneTasks.length;
+    const open = total - done;
+    const progressPct = total > 0 ? Math.round((done / total) * 100) : 0;
+    const doneInWindow = (fromDaysAgo, toDaysAgo) => doneTasks.filter((t) => {
+        const d = utcDay(t.updated);
+        if (d === null)
+            return false;
+        const age = (todayMs - d) / DAY_MS;
+        return age >= toDaysAgo && age < fromDaysAgo;
+    }).length;
+    const velocity7 = doneInWindow(7, 0);
+    const velocityPrev7 = doneInWindow(14, 7);
+    let forecastDate = null;
+    if (velocity7 > 0 && open > 0) {
+        const daysNeeded = Math.ceil((open / velocity7) * 7);
+        forecastDate = new Date(todayMs + daysNeeded * DAY_MS).toISOString().slice(0, 10);
+    }
+    const byId = new Map(tasks.map((t) => [t.id, t]));
+    const unresolved = new Set();
+    for (const dep of deps) {
+        const from = byId.get(dep.from);
+        const to = byId.get(dep.to);
+        if (from && !isDone(from.status) && to && !isDone(to.status))
+            unresolved.add(dep.from);
+    }
+    const openTasks = tasks.filter((t) => !isDone(t.status));
+    const wip = openTasks.filter((t) => isWip(t.status)).length;
+    const blocked = openTasks.filter((t) => t.status.toLowerCase().includes('block') || unresolved.has(t.id)).length;
+    const ages = [];
+    for (const t of openTasks) {
+        const d = utcDay(t.created) ?? utcDay(t.updated);
+        if (d === null)
+            continue;
+        ages.push({ id: t.id, days: Math.max(0, Math.round((todayMs - d) / DAY_MS)) });
+    }
+    ages.sort((a, b) => b.days - a.days);
+    const oldest = ages[0] ?? null;
+    let medianOpenAgeDays = null;
+    if (ages.length > 0) {
+        const mid = Math.floor(ages.length / 2);
+        medianOpenAgeDays =
+            ages.length % 2 === 1 ? ages[mid].days : Math.round((ages[mid - 1].days + ages[mid].days) / 2);
+    }
+    const activityTotal30 = activity.slice(-30).reduce((sum, b) => sum + b.count, 0);
+    const windowTotal = activity.reduce((sum, b) => sum + b.count, 0);
+    const activityAvgPerWeek = activity.length > 0 ? Math.round((windowTotal / (activity.length / 7)) * 10) / 10 : 0;
+    const perWeekday = [0, 0, 0, 0, 0, 0, 0];
+    for (const b of activity) {
+        const d = utcDay(b.date);
+        if (d !== null)
+            perWeekday[new Date(d).getUTCDay()] += b.count;
+    }
+    const maxWeekday = Math.max(...perWeekday);
+    const busiestWeekday = maxWeekday > 0 ? perWeekday.indexOf(maxWeekday) : null;
+    let streakDays = 0;
+    let i = activity.length - 1;
+    if (i >= 0 && activity[i].count === 0)
+        i--; // today may still be empty
+    while (i >= 0 && activity[i].count > 0) {
+        streakDays++;
+        i--;
+    }
+    return {
+        total, done, open, progressPct,
+        velocity7, velocityPrev7, forecastDate,
+        wip, blocked,
+        oldestOpenId: oldest ? oldest.id : null,
+        oldestOpenDays: oldest ? oldest.days : null,
+        medianOpenAgeDays,
+        activityTotal30, activityAvgPerWeek, busiestWeekday, streakDays,
+    };
+}

package/dist/lib/hub-state.js

@@ -16,8 +16,8 @@ export function readHubState(home) {
             typeof parsed.token !== 'string') {
             return null;
         }
-        const { pid, port, token } = parsed;
-        return { pid, port, token };
+        const { pid, port, token, version } = parsed;
+        return typeof version === 'string' ? { pid, port, token, version } : { pid, port, token };
     }
     catch {
         return null;

package/dist/lib/self-update.js

@@ -0,0 +1,57 @@
+// src/lib/self-update.ts
+import { join } from 'node:path';
+import process from 'node:process';
+import { isNewerVersion } from './version-check.js';
+/**
+ * Normalizes separators for prefix comparison and, on win32, case as well:
+ * `npm root -g` and `realpathSync` can disagree on drive-letter/path casing
+ * (`C:\` vs `c:\`) even for the same install, and Windows paths are
+ * case-insensitive anyway, so comparing case-sensitively there would
+ * misclassify a real global install as `unknown`. Takes an optional
+ * `caseInsensitive` override (default: `process.platform === 'win32'`) so
+ * the function stays pure and testable for both platforms' behavior.
+ */
+function normalizeForCompare(p, caseInsensitive) {
+    const withForwardSlashes = p.replace(/\\/g, '/');
+    return caseInsensitive ? withForwardSlashes.toLowerCase() : withForwardSlashes;
+}
+function isUnder(path, root) {
+    return path === root || path.startsWith(`${root}/`);
+}
+/**
+ * Classifies the running binary's real path as a local (project
+ * node_modules) install, a global npm install, or unknown (treated the
+ * same as local: never mutated, hint only). Pure function -- callers
+ * gather binRealPath (from `process.argv[1]` + `realpathSync`) and
+ * globalRoot (from `npm root -g`, captured once, null on failure).
+ */
+export function detectInstallKind(binRealPath, cwd, globalRoot, caseInsensitive = process.platform === 'win32') {
+    const bin = normalizeForCompare(binRealPath, caseInsensitive);
+    const localRoot = normalizeForCompare(join(cwd, 'node_modules'), caseInsensitive);
+    if (isUnder(bin, localRoot))
+        return 'local';
+    if (globalRoot !== null && isUnder(bin, normalizeForCompare(globalRoot, caseInsensitive)))
+        return 'global';
+    return 'unknown';
+}
+export async function runSelfUpdate(deps) {
+    const latest = await deps.fetchLatest();
+    if (latest === null) {
+        deps.warn('could not check for a newer super-backlog (offline?)');
+        return { kind: 'unavailable' };
+    }
+    if (!isNewerVersion(latest, deps.installed)) {
+        return { kind: 'current' };
+    }
+    if (deps.installKind !== 'global') {
+        deps.log(`a newer super-backlog (${latest}) is available; update the dependency yourself, e.g. npm i -D super-backlog@${latest}`);
+        return { kind: 'skipped-local', latest };
+    }
+    const result = deps.npmInstallGlobal(`super-backlog@${latest}`);
+    if (result.status === 0) {
+        deps.log(`self-updated to ${latest}, re-running update...`);
+        return { kind: 'updated', latest };
+    }
+    deps.warn(`self-update to ${latest} failed (npm install exited ${String(result.status)}); continuing with ${deps.installed}`);
+    return { kind: 'failed', latest };
+}

package/dist/lib/version-check.js

@@ -57,7 +57,8 @@ function isStale(checkedAt, now) {
 function unrefStream(stream) {
     stream?.unref?.();
 }
-export async function defaultFetchLatest() {
+/** Queries the npm registry for the latest published version, racing a timeout. */
+export async function fetchLatestVersion(timeoutMs = FETCH_TIMEOUT_MS) {
     const work = new Promise((resolvePromise) => {
         let child;
         try {
@@ -89,7 +90,7 @@ export async function defaultFetchLatest() {
     });
     let timer;
     const timeout = new Promise((resolveTimeout) => {
-        timer = setTimeout(() => resolveTimeout(null), FETCH_TIMEOUT_MS);
+        timer = setTimeout(() => resolveTimeout(null), timeoutMs);
         timer.unref();
     });
     try {
@@ -103,12 +104,15 @@ export async function defaultFetchLatest() {
             clearTimeout(timer);
     }
 }
+export async function defaultFetchLatest() {
+    return fetchLatestVersion(FETCH_TIMEOUT_MS);
+}
 export async function applyVersionHint(installed, deps) {
     if (deps.env.SBL_SKIP_UPDATE_CHECK)
         return;
     const cache = readCache(deps.home);
     if (cache && isNewerVersion(cache.latest, installed)) {
-        deps.log(`super-backlog ${cache.latest} is available (installed ${installed}). Update: npm i -g super-backlog`);
+        deps.log(`super-backlog ${cache.latest} is available (installed ${installed}). Update: sbl update (or npm i -g super-backlog)`);
     }
     if (!cache || isStale(cache.checkedAt, deps.now())) {
         void deps