@specship/specship-win32-arm64 0.12.0 → 0.13.0

package/lib/dist/server/routes/mcp.js

@@ -0,0 +1,510 @@
+/**
+ * MCP servers routes — inventory, live status, and control (REQ-DESKTOP-026).
+ *
+ * Three real sources, merged (this fork is Claude Code only, so Claude
+ * Code's config surfaces ARE the inventory — no other clients are read):
+ *   1. Claude Code's own config — `~/.claude.json` (global `mcpServers` +
+ *      `projects[<root>].mcpServers`) and `<projectRoot>/.mcp.json`, the
+ *      same files `specship install` writes. Disabled servers come from
+ *      `disabledMcpjsonServers` (Claude Code's native mechanism for
+ *      `.mcp.json` entries) and `mcpServersDisabled` (our parking map for
+ *      `~/.claude.json`-owned entries).
+ *   2. The transcript analytics DB — `claude_tool_calls` rows whose
+ *      `tool_name` is `mcp__<server>__<tool>` give real per-server/per-tool
+ *      call counts, result sizes, last-used timestamps, and the example
+ *      call (`input_json`, schema v7).
+ *   3. A liveness probe — stdio entries are spawned and asked to answer an
+ *      MCP `initialize`; `url` entries get a fetch. Results cache ~30 s.
+ *
+ * States use the spec vocabulary (deriveState): `disabled` (parked in
+ * config) → `failed` (probe refused) → `active` (calls in the last 24 h) →
+ * `connected` (probe answered) → `idle`.
+ *
+ * Writes (PATCH enable/disable, POST add) touch the user's LIVE Claude Code
+ * configs, so every write is atomic (write-temp + rename) and preserves
+ * unrelated keys byte-for-byte: key order is kept, and the file's existing
+ * indentation unit + trailing newline are detected and reused. A file that
+ * fails to parse is never overwritten — the edit errors instead.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+function getDb(cg) {
+    const anyCg = cg;
+    if (anyCg.db?.getDb)
+        return anyCg.db.getDb();
+    return anyCg.queries?.db;
+}
+/** Config-write failures the routes translate to HTTP statuses. */
+export class McpConfigError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+}
+function readJson(p) {
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Collect configured servers from Claude Code's three config surfaces.
+ * Precedence on name collision follows Claude Code's own resolution:
+ * user (`~/.claude.json` global) < project-local (`projects[<root>]` entry)
+ * < `.mcp.json` — later wins, matching what the agent actually loads.
+ */
+export function configuredServers(paths) {
+    const out = new Map();
+    const claudeJson = readJson(paths.claudeJsonPath);
+    const add = (name, cfg) => out.set(name, { name, ...cfg });
+    for (const [name, entry] of Object.entries((claudeJson?.['mcpServers'] ?? {}))) {
+        add(name, { scope: 'user', entry, configFile: paths.claudeJsonPath, disabled: false, container: 'user' });
+    }
+    for (const [name, entry] of Object.entries((claudeJson?.['mcpServersDisabled'] ?? {}))) {
+        add(name, { scope: 'user', entry, configFile: paths.claudeJsonPath, disabled: true, container: 'user' });
+    }
+    if (paths.projectRoot) {
+        const proj = claudeJson?.['projects']?.[paths.projectRoot];
+        for (const [name, entry] of Object.entries((proj?.['mcpServers'] ?? {}))) {
+            add(name, { scope: 'project', entry, configFile: paths.claudeJsonPath, disabled: false, container: 'project-local' });
+        }
+        for (const [name, entry] of Object.entries((proj?.['mcpServersDisabled'] ?? {}))) {
+            add(name, { scope: 'project', entry, configFile: paths.claudeJsonPath, disabled: true, container: 'project-local' });
+        }
+        const disabledMcpjson = new Set((proj?.['disabledMcpjsonServers'] ?? []));
+        const mcpJsonPath = path.join(paths.projectRoot, '.mcp.json');
+        const mcpJson = readJson(mcpJsonPath);
+        for (const [name, entry] of Object.entries((mcpJson?.['mcpServers'] ?? {}))) {
+            add(name, { scope: 'project', entry, configFile: mcpJsonPath, disabled: disabledMcpjson.has(name), container: 'mcpjson' });
+        }
+    }
+    return out;
+}
+/**
+ * Spec vocabulary, in precedence order: a parked entry is `disabled` no
+ * matter what; a refused probe is `failed` even with recent calls (the
+ * config broke since); recent usage is `active`; a probe answer without
+ * recent usage is `connected`; otherwise `idle`.
+ */
+export function deriveState(cfg, usage, probe, nowMs = Date.now()) {
+    if (cfg?.disabled)
+        return 'disabled';
+    if (probe === 'failed')
+        return 'failed';
+    if (usage && nowMs - usage.lastMs < 24 * 3600_000)
+        return 'active';
+    if (probe === 'ok')
+        return 'connected';
+    return 'idle';
+}
+const PROBE_CACHE_MS = 30_000;
+const probeCache = new Map();
+/** The MCP initialize request the stdio probe sends (newline-delimited JSON-RPC). */
+const INITIALIZE_REQUEST = JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+        protocolVersion: '2025-06-18',
+        capabilities: {},
+        clientInfo: { name: 'specship-desktop', version: '0.0.0' },
+    },
+}) + '\n';
+function probeStdio(entry, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let child;
+        const done = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                child?.kill();
+            }
+            catch { /* already gone */ }
+            resolve(result);
+        };
+        const timer = setTimeout(() => done('failed'), timeoutMs);
+        try {
+            child = spawn(entry.command, entry.args ?? [], {
+                stdio: ['pipe', 'pipe', 'ignore'],
+                env: { ...process.env, ...(entry.env ?? {}) },
+                shell: process.platform === 'win32',
+                windowsHide: true,
+            });
+        }
+        catch {
+            done('failed');
+            return;
+        }
+        child.on('error', () => done('failed'));
+        child.on('exit', () => done('failed'));
+        let buf = '';
+        child.stdout?.on('data', (chunk) => {
+            buf += chunk.toString('utf8');
+            for (const line of buf.split('\n')) {
+                try {
+                    const msg = JSON.parse(line);
+                    if (msg && msg.id === 1 && msg.result) {
+                        done('ok');
+                        return;
+                    }
+                }
+                catch { /* partial line */ }
+            }
+        });
+        try {
+            child.stdin?.write(INITIALIZE_REQUEST);
+        }
+        catch {
+            done('failed');
+        }
+    });
+}
+async function probeUrl(url, timeoutMs) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+        // Any 4xx/5xx (expired OAuth = 401, dead route = 404) is the failed
+        // treatment — the design's sentry example shows 401 as Failed.
+        return res.ok ? 'ok' : 'failed';
+    }
+    catch {
+        return 'failed';
+    }
+}
+/**
+ * Liveness probe. Never throws and never hangs past `timeoutMs`; a timeout
+ * counts as `failed` (the agent couldn't have used it either). Results are
+ * cached ~30 s per config shape so a page refresh doesn't respawn servers.
+ */
+export async function probeServer(entry, timeoutMs = 2500) {
+    const key = entry.url ?? [entry.command, ...(entry.args ?? [])].join(' ');
+    if (!key)
+        return 'failed';
+    const cached = probeCache.get(key);
+    if (cached && Date.now() - cached.at < PROBE_CACHE_MS)
+        return cached.result;
+    const result = entry.url
+        ? await probeUrl(entry.url, timeoutMs)
+        : entry.command
+            ? await probeStdio(entry, timeoutMs)
+            : 'failed';
+    probeCache.set(key, { at: Date.now(), result });
+    return result;
+}
+// ---- Config writes ----------------------------------------------------------
+/** Write-temp + rename so a crash mid-write can't corrupt a live config. */
+function atomicWriteFileSync(filePath, content) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    const tmpPath = filePath + '.tmp.' + process.pid;
+    try {
+        fs.writeFileSync(tmpPath, content);
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
+/** First indented line's leading whitespace = the file's indent unit. */
+function detectJsonStyle(text) {
+    const m = text.match(/\n([ \t]+)\S/);
+    return {
+        indent: m?.[1] ?? '  ',
+        trailingNewline: text.length === 0 || text.endsWith('\n'),
+    };
+}
+/**
+ * Parse → mutate → re-serialize preserving key order, the detected indent
+ * unit, and the trailing newline — so untouched keys keep their bytes. An
+ * unparseable file throws (500) instead of being clobbered.
+ */
+function editJsonFile(filePath, mutate) {
+    let text = '';
+    try {
+        text = fs.readFileSync(filePath, 'utf8');
+    }
+    catch { /* missing → create */ }
+    let data = {};
+    if (text.trim()) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new McpConfigError(`refusing to edit unparseable ${filePath}: ${msg}`, 500);
+        }
+    }
+    mutate(data);
+    const { indent, trailingNewline } = detectJsonStyle(text);
+    atomicWriteFileSync(filePath, JSON.stringify(data, null, indent) + (trailingNewline ? '\n' : ''));
+}
+/**
+ * Move `data[from][name]` → `data[to][name]`. An emptied `mcpServersDisabled`
+ * (our parking map) is removed; an emptied `mcpServers` is kept in place —
+ * deleting it would re-create it at the END of the object on re-enable,
+ * breaking the byte-for-byte round-trip.
+ */
+function moveEntry(data, from, to, name) {
+    const entry = data[from]?.[name];
+    if (entry === undefined)
+        throw new McpConfigError(`server "${name}" not found under ${from}`, 404);
+    delete data[from][name];
+    if (from === 'mcpServersDisabled' && Object.keys(data[from]).length === 0)
+        delete data[from];
+    data[to] = { ...(data[to] ?? {}), [name]: entry };
+}
+/**
+ * Enable/disable a configured server by editing its owning file.
+ *   - `.mcp.json`-owned → toggle the name in `disabledMcpjsonServers` under
+ *     the project's entry in `~/.claude.json` (Claude Code's own mechanism —
+ *     `.mcp.json` itself is team-shared and never touched).
+ *   - `~/.claude.json`-owned (user or project-local) → move the entry
+ *     between `mcpServers` and the `mcpServersDisabled` parking map.
+ * Idempotent: a no-op toggle returns without writing. Throws McpConfigError
+ * 404 when the name isn't configured anywhere.
+ */
+export function setServerEnabled(paths, name, enabled) {
+    const cfg = configuredServers(paths).get(name);
+    if (!cfg)
+        throw new McpConfigError(`unknown MCP server "${name}"`, 404);
+    if (cfg.disabled === !enabled)
+        return cfg;
+    if (cfg.container === 'mcpjson') {
+        editJsonFile(paths.claudeJsonPath, (data) => {
+            const projects = (data['projects'] = data['projects'] ?? {});
+            const proj = (projects[paths.projectRoot] = projects[paths.projectRoot] ?? {});
+            const list = proj['disabledMcpjsonServers'] ?? [];
+            const next = enabled ? list.filter((n) => n !== name) : [...list, name];
+            if (next.length)
+                proj['disabledMcpjsonServers'] = next;
+            else
+                delete proj['disabledMcpjsonServers'];
+        });
+    }
+    else if (cfg.container === 'user') {
+        editJsonFile(paths.claudeJsonPath, (data) => {
+            if (enabled)
+                moveEntry(data, 'mcpServersDisabled', 'mcpServers', name);
+            else
+                moveEntry(data, 'mcpServers', 'mcpServersDisabled', name);
+        });
+    }
+    else {
+        editJsonFile(paths.claudeJsonPath, (data) => {
+            const proj = data['projects']?.[paths.projectRoot];
+            if (!proj)
+                throw new McpConfigError(`project entry for ${paths.projectRoot} missing`, 404);
+            if (enabled)
+                moveEntry(proj, 'mcpServersDisabled', 'mcpServers', name);
+            else
+                moveEntry(proj, 'mcpServers', 'mcpServersDisabled', name);
+        });
+    }
+    return { ...cfg, disabled: !enabled };
+}
+/**
+ * Add a server: user scope → `~/.claude.json` `mcpServers`; project scope →
+ * `<projectRoot>/.mcp.json`. 409 when the name exists on any surface, 400
+ * on invalid input. Entry shape matches the installer's (`type` explicit).
+ */
+export function addServer(paths, input) {
+    const name = (input.name ?? '').trim();
+    if (!name || /\s/.test(name))
+        throw new McpConfigError('server name must be a non-empty token', 400);
+    if (input.scope !== 'user' && input.scope !== 'project')
+        throw new McpConfigError('scope must be "user" or "project"', 400);
+    if (!input.url && !(input.command ?? '').trim())
+        throw new McpConfigError('either a command or a url is required', 400);
+    if (configuredServers(paths).has(name))
+        throw new McpConfigError(`MCP server "${name}" is already configured`, 409);
+    const entry = input.url
+        ? { type: 'http', url: input.url }
+        : { type: 'stdio', command: input.command.trim(), ...(input.args?.length ? { args: input.args } : {}) };
+    if (input.scope === 'project') {
+        if (!paths.projectRoot)
+            throw new McpConfigError('no project open — cannot write .mcp.json', 400);
+        const mcpJsonPath = path.join(paths.projectRoot, '.mcp.json');
+        editJsonFile(mcpJsonPath, (data) => {
+            data['mcpServers'] = { ...(data['mcpServers'] ?? {}), [name]: entry };
+        });
+        return { name, scope: 'project', entry, configFile: mcpJsonPath, disabled: false, container: 'mcpjson' };
+    }
+    editJsonFile(paths.claudeJsonPath, (data) => {
+        data['mcpServers'] = { ...(data['mcpServers'] ?? {}), [name]: entry };
+    });
+    return { name, scope: 'user', entry, configFile: paths.claudeJsonPath, disabled: false, container: 'user' };
+}
+/** Aggregate claude_tool_calls into per-server usage + the latest example call. */
+function collectUsage(cg) {
+    const byServer = new Map();
+    let usage = [];
+    let examples = [];
+    try {
+        const db = getDb(cg);
+        usage = db.prepare(`
+      SELECT tool_name, COUNT(*) as calls,
+             COALESCE(SUM(result_length), 0) as bytes,
+             MAX(ts) as last
+      FROM claude_tool_calls
+      WHERE tool_name LIKE 'mcp__%'
+      GROUP BY tool_name
+    `).all();
+        // Latest verbatim inputs (schema v7) — first row per server wins below.
+        examples = db.prepare(`
+      SELECT tool_name, input_json
+      FROM claude_tool_calls
+      WHERE tool_name LIKE 'mcp__%' AND input_json IS NOT NULL
+      ORDER BY ts DESC
+      LIMIT 500
+    `).all();
+    }
+    catch { /* analytics tables absent — config-only response */ }
+    const parse = (t) => t.match(/^mcp__(.+?)__(.+)$/);
+    for (const u of usage) {
+        const m = parse(u.tool_name);
+        if (!m)
+            continue;
+        const [, server, tool] = m;
+        if (!byServer.has(server))
+            byServer.set(server, { calls: 0, bytes: 0, last: 0, tools: new Map(), example: null });
+        const s = byServer.get(server);
+        s.calls += u.calls;
+        s.bytes += u.bytes;
+        // `ts` is epoch milliseconds (integer) in the ingest schema.
+        const t = typeof u.last === 'number' ? u.last : u.last ? Date.parse(u.last) : 0;
+        if (Number.isFinite(t) && t > s.last)
+            s.last = t;
+        const tt = s.tools.get(tool) ?? { calls: 0, bytes: 0 };
+        tt.calls += u.calls;
+        tt.bytes += u.bytes;
+        s.tools.set(tool, tt);
+    }
+    for (const row of examples) {
+        const m = parse(row.tool_name);
+        if (!m)
+            continue;
+        const [, server, tool] = m;
+        const s = byServer.get(server);
+        if (!s || s.example)
+            continue;
+        try {
+            s.example = { tool, args: JSON.parse(row.input_json) };
+        }
+        catch { /* skip bad row */ }
+    }
+    // Fallback example: the server's top tool with empty args.
+    for (const s of byServer.values()) {
+        if (s.example)
+            continue;
+        const top = [...s.tools.entries()].sort((a, b) => b[1].calls - a[1].calls)[0];
+        if (top)
+            s.example = { tool: top[0], args: {} };
+    }
+    return byServer;
+}
+export async function registerMcpRoutes(app) {
+    const paths = () => ({
+        claudeJsonPath: path.join(os.homedir(), '.claude.json'),
+        projectRoot: app.primaryCg?.getProjectRoot?.() ?? null,
+    });
+    function requirePrimary(reply) {
+        if (!app.primaryCg) {
+            reply.code(409).send({ error: 'analytics unavailable: no primary project configured', code: 'no_primary' });
+            return null;
+        }
+        return app.primaryCg;
+    }
+    app.get('/api/mcp/servers', async (_req, reply) => {
+        const cg = requirePrimary(reply);
+        if (!cg)
+            return;
+        const p = paths();
+        const config = configuredServers(p);
+        const byServer = collectUsage(cg);
+        // Probe every enabled configured server concurrently; disabled and
+        // usage-only entries have nothing to probe.
+        const probeTargets = [...config.values()].filter((c) => !c.disabled);
+        const probes = new Map(await Promise.all(probeTargets.map(async (c) => [c.name, await probeServer(c.entry)])));
+        const names = new Set([...config.keys(), ...byServer.keys()]);
+        const servers = [...names].map((name) => {
+            const cfg = config.get(name);
+            const use = byServer.get(name);
+            const entry = cfg?.entry ?? {};
+            const transport = entry.url ? 'http' : 'stdio';
+            const command = entry.url ?? [entry.command, ...(entry.args ?? [])].filter(Boolean).join(' ');
+            const state = deriveState(cfg, use?.last ? { lastMs: use.last } : null, probes.get(name) ?? null);
+            return {
+                id: name, name,
+                scope: cfg?.scope ?? 'unknown',
+                state, transport, command,
+                configFile: cfg?.configFile ?? null,
+                disabled: cfg?.disabled ?? false,
+                entry: cfg?.entry ?? null,
+                calls: use?.calls ?? 0,
+                resultBytes: use?.bytes ?? 0,
+                lastUsed: use?.last ? new Date(use.last).toISOString() : null,
+                tools: use ? [...use.tools.entries()]
+                    .map(([tool, t]) => ({ name: tool, calls: t.calls, resultBytes: t.bytes }))
+                    .sort((a, b) => b.calls - a.calls) : [],
+                exampleCall: use?.example ?? null,
+            };
+        }).sort((a, b) => b.calls - a.calls);
+        reply.send({ servers });
+    });
+    app.patch('/api/mcp/servers/:name', async (req, reply) => {
+        const enabled = req.body?.enabled;
+        if (typeof enabled !== 'boolean') {
+            return reply.code(400).send({ error: 'body must be { enabled: boolean }' });
+        }
+        const p = paths();
+        try {
+            const server = setServerEnabled(p, req.params.name, enabled);
+            return reply.send({ ok: true, name: server.name, disabled: server.disabled });
+        }
+        catch (err) {
+            if (err instanceof McpConfigError) {
+                // Usage-only servers show up in transcripts but have no config to
+                // edit — that's a 400 (bad target), not a 404 (unknown name).
+                if (err.statusCode === 404 && app.primaryCg && hasUsage(app.primaryCg, req.params.name)) {
+                    return reply.code(400).send({ error: `"${req.params.name}" appears in transcripts but has no config entry to toggle` });
+                }
+                return reply.code(err.statusCode).send({ error: err.message });
+            }
+            throw err;
+        }
+    });
+    app.post('/api/mcp/servers', async (req, reply) => {
+        try {
+            const server = addServer(paths(), req.body ?? {});
+            return reply.code(201).send({ ok: true, name: server.name, scope: server.scope, configFile: server.configFile });
+        }
+        catch (err) {
+            if (err instanceof McpConfigError)
+                return reply.code(err.statusCode).send({ error: err.message });
+            throw err;
+        }
+    });
+}
+/** True when transcripts contain any mcp__<name>__* call. */
+function hasUsage(cg, name) {
+    try {
+        const db = getDb(cg);
+        const rows = db.prepare(`SELECT 1 FROM claude_tool_calls WHERE tool_name LIKE 'mcp__' || ? || '__%' LIMIT 1`).all(name);
+        return rows.length > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/lib/dist/server/routes/projects.js

@@ -68,7 +68,7 @@ export async function enumerate(claudeRoot, resolverOpts) {
             }
         }
         catch { /* path missing — OK, still surface it so UI can flag it */ }
-        out.push({ slug, path: decoded, exists, initialized, sessionCount, lastModifiedMs });
+        out.push({ slug, path: decoded, exists, initialized, sessionCount, lastModifiedMs, driftCount: null });
     }
     // Recent activity first; ties broken by path.
     out.sort((a, b) => {
@@ -78,6 +78,32 @@ export async function enumerate(claudeRoot, resolverOpts) {
     });
     return out;
 }
+/**
+ * Bound on how many projects get a live driftCount per request. Mirrors the
+ * /api/events sweep: every lookup opens the project's graph through the
+ * registry LRU (maxOpen 16), so an unbounded pass over a large project list
+ * churns open/close cycles on every GET. enumerate() sorts by recency, so
+ * the bounded prefix is exactly what the switcher surfaces first; the rest
+ * stay `null` (unknown), which the UI renders as no pill.
+ */
+const DRIFT_SWEEP_LIMIT = 10;
+/** Fill `driftCount` in place for the most-recent initialized projects. */
+export async function attachDriftCounts(list, source, limit = DRIFT_SWEEP_LIMIT) {
+    let budget = limit;
+    for (const p of list) {
+        if (!p.initialized || budget <= 0)
+            continue;
+        budget--;
+        try {
+            const cg = await source(p.slug);
+            if (!cg)
+                continue; // open failed — leave null
+            p.driftCount = cg.getSpecQueries().getLinksByState(['drifted', 'broken', 'orphaned']).length;
+        }
+        catch { /* graph unreadable — leave null */ }
+    }
+    return list;
+}
 // --- Watcher (singleton across the process) ---------------------------------
 let watcher = null;
 let lastSlugs = new Set();
@@ -144,8 +170,10 @@ export async function registerProjectsRoutes(app) {
     const claudeRoot = path.join(os.homedir(), '.claude', 'projects');
     startWatcher(claudeRoot, false);
     app.addHook('onClose', async () => { stopWatcher(); });
+    const driftSource = (slug) => app.projects.getBySlug(slug);
     app.get('/api/projects', async () => {
-        return { claudeRoot, projects: await enumerate(claudeRoot) };
+        const projects = await attachDriftCounts(await enumerate(claudeRoot), driftSource);
+        return { claudeRoot, projects };
     });
     app.get('/api/projects/events', async (req, reply) => {
         writeSseHead(req, reply);
@@ -169,7 +197,7 @@ export async function registerProjectsRoutes(app) {
                 closed = true;
             }
         };
-        const initial = await enumerate(claudeRoot);
+        const initial = await attachDriftCounts(await enumerate(claudeRoot), driftSource);
         lastSlugs = new Set(initial.map((p) => p.slug));
         writeEvent('snapshot', { claudeRoot, projects: initial });
         const onChange = (payload) => {

package/lib/dist/server/routes/status.js

@@ -13,6 +13,7 @@
  * (no `?project=`, no primary), returns a 409 with `code: 'no_project'`
  * so the UI can show the picker without blowing up.
  */
+import { productVersion } from '../product-version.js';
 export async function registerStatusRoutes(app) {
     app.get('/api/status', async (req, reply) => {
         const cg = await app.activeCg(req);
@@ -28,6 +29,7 @@ export async function registerStatusRoutes(app) {
             projectPath: cg.getProjectRoot ? cg.getProjectRoot() : '',
             backend: cg.getBackend(),
             journalMode: cg.getJournalMode(),
+            version: productVersion(),
             nodeCount: stats.nodeCount,
             edgeCount: stats.edgeCount,
             fileCount: stats.fileCount,
@@ -98,6 +100,7 @@ export async function registerStatusRoutes(app) {
                 projectPath: cg.getProjectRoot ? cg.getProjectRoot() : '',
                 backend: cg.getBackend(),
                 journalMode: cg.getJournalMode(),
+                version: productVersion(),
                 nodeCount: stats.nodeCount,
                 edgeCount: stats.edgeCount,
                 fileCount: stats.fileCount,

package/lib/dist/server/routes/workflow.js

@@ -36,7 +36,7 @@ export async function registerWorkflowRoutes(app) {
     //      the bundled tarball stages the specship core without a resolvable
     //      `@specship/specship` package on Node's module graph (offline
     //      installs hit this — see scripts/offline-install.sh).
-    //   2. **Workspace / dev** — the `file:../..` workspace dep resolves the
+    //   2. **Workspace / dev** — the `file:..` workspace dep resolves the
     //      named import via Node's normal package resolution.
     let discovery;
     let executorMod;
@@ -99,13 +99,53 @@ export async function registerWorkflowRoutes(app) {
         startPromise.catch(() => { });
         return { runId: result.run.id, status: result.run.status };
     });
+    // Estimated time-to-completion for in-flight runs (WORKFLOW-ETA-DOC).
+    // Guarded so a stale core build without the method degrades to "no
+    // estimate" instead of failing the runs surfaces.
+    function etaFor(cg, runId) {
+        try {
+            const fn = cg.estimateWorkflowRunEta;
+            return typeof fn === 'function' ? fn.call(cg, runId) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Roll a run's per-node stats (from `step_completed` events) into
+     * list-level `totalCostUsd` / `model` fields so the Runs list can render
+     * its cost/model columns without N+1 detail fetches (REQ-DESKTOP-023).
+     * Additive + best-effort: runs recorded before stats existed simply get
+     * nulls.
+     */
+    function statsRollup(sq, runId) {
+        let totalCostUsd = null;
+        let model = null;
+        try {
+            for (const e of sq.getEventsByRun(runId, 1000)) {
+                if (e.eventType !== 'step_completed')
+                    continue;
+                const stats = e.data?.stats;
+                if (typeof stats?.costUsd === 'number')
+                    totalCostUsd = (totalCostUsd ?? 0) + stats.costUsd;
+                if (!model && typeof stats?.model === 'string')
+                    model = stats.model;
+            }
+        }
+        catch { /* stats are decorative — never fail the list */ }
+        return { totalCostUsd, model };
+    }
     app.get('/api/workflows/runs', async (req, reply) => {
         const cg = await resolveCg(app, req, reply);
         if (!cg)
             return;
         const { sq } = executorFor(cg);
         const limit = Math.min(parseInt(req.query.limit ?? '50', 10) || 50, 500);
-        return { runs: sq.getAllWorkflowRuns(limit) };
+        const runs = sq.getAllWorkflowRuns(limit).map((r) => ({
+            ...(r.status === 'running' || r.status === 'paused' ? { ...r, eta: etaFor(cg, r.id) } : r),
+            ...statsRollup(sq, r.id),
+        }));
+        return { runs };
     });
     app.get('/api/workflows/runs/:id', async (req, reply) => {
         const cg = await resolveCg(app, req, reply);
@@ -116,7 +156,8 @@ export async function registerWorkflowRoutes(app) {
         if (!run)
             return reply.code(404).send({ error: 'run not found' });
         const events = sq.getEventsByRun(req.params.id, 500);
-        return { run, events };
+        const eta = run.status === 'running' || run.status === 'paused' ? etaFor(cg, run.id) : undefined;
+        return { run: eta === undefined ? run : { ...run, eta }, events };
     });
     /**
      * Read-only artifacts for a run. The executor writes each completed node's