spectoflow 0.23.4 → 0.24.0

package/lib/{hub-server.js → dashboard/hub-server.js}

@@ -1,11 +1,11 @@
 'use strict';
 /*
  * The multi-project hub's server process — global (ships under lib/, never vendored into a
- * project's .spectoflow/). Registry-driven: resolves a project's root + route logic on demand from
+ * project's .spectoflow/). Registry-driven: resolves a project's root on demand from
  * ~/.spectoflow/projects.json (see lib/registry.js), keyed by the opaque id in /p/<id>/... URLs.
- * Each project's own vendored handlers.js is require()'d dynamically by absolute path — Node's
- * require cache keys by resolved path, so two different projects' identically-named handlers.js
- * files are cached and run completely independently (see docs/multi-project-hub-design.md).
+ * The route logic is THIS package's own handlers.js (./handlers.js), shared by every project (D64):
+ * nothing is ever require()'d from a project, so a project that has never run `spectoflow update`
+ * opens exactly like a fresh one (see docs/multi-project-hub-design.md).
  *
  * URL scheme (settled in the design doc): pages use a path prefix (/p/<id>/board, bookmarkable on
  * their own); every /api/* call instead takes a ?p=<id> query param (smaller client diff, and
@@ -21,74 +21,65 @@ const http = require('http');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const registry = require('./registry');
-
-const PORT = process.env.SPECTOFLOW_PORT ? Number(process.env.SPECTOFLOW_PORT) : 4319;
-const PUBLIC = path.join(__dirname, '..', 'templates', 'dashboard', 'public');
-const TEMPLATES = path.join(__dirname, '..', 'templates');
-const VERSION = require('../package.json').version;
+const registry = require('../registry');
+const workspace = require('../workspace');
+const { createHandlers } = require('./handlers');
+const store = require('../store');
+
+const migrated = workspace.migrateLegacyHome();
+if (!workspace.exists()) workspace.init({});
+const PORT = process.env.SPECTOFLOW_PORT ? Number(process.env.SPECTOFLOW_PORT) : workspace.settings().port;
+const PUBLIC = path.join(__dirname, 'public');
+const TEMPLATES = path.join(__dirname, '..', '..', 'templates');
+const VERSION = require('../../package.json').version;
 const MIME = { '.html':'text/html; charset=utf-8', '.css':'text/css; charset=utf-8', '.js':'application/javascript; charset=utf-8', '.png':'image/png', '.svg':'image/svg+xml', '.ico':'image/x-icon', '.woff2':'font/woff2', '.woff':'font/woff' };
 function sendJSON(res,code,obj){ res.writeHead(code,{'Content-Type':'application/json; charset=utf-8'}); res.end(JSON.stringify(obj)); }
 function body(req) { return new Promise((r) => { let b = ''; req.on('data', (c) => b += c); req.on('end', () => { try { r(JSON.parse(b || '{}')); } catch { r({}); } }); }); }
 
-// id -> { id, root, handlers, clients:Set, emit }, populated lazily on first request for that id and
-// kept alive for the process's life (registries are small; no need to tear down on last-tab-close).
+// id -> { id, root, handlers, clients:Set, emit, watchers:[] }. The route logic is THIS package's
+// handlers.js for every project (D64): nothing is ever require()'d from a project, so a project that
+// has never run `spectoflow update` opens exactly like a fresh one.
 const projects = new Map();
 function getProject(id) {
   if (projects.has(id)) return projects.get(id);
   const entry = registry.listProjects().find((p) => p.id === id);
-  if (!entry) return null;
-  const handlersPath = path.join(entry.path, '.spectoflow', 'dashboard', 'handlers.js');
-  let createHandlers;
-  try { ({ createHandlers } = require(handlersPath)); }
-  catch { return null; } // project's folder moved/deleted, or predates the handlers.js split
+  if (!entry || !fs.existsSync(entry.path)) return null;
   const handlers = createHandlers(entry.path);
   const clients = new Set();
   const emit = (obj) => { const line = 'data: ' + JSON.stringify(obj) + '\n\n'; for (const res of clients) res.write(line); };
   handlers.onBoot();
+  const watchers = [];
   handlers.watchDirs.forEach((d) => {
     const dir = path.join(entry.path, d);
-    if (fs.existsSync(dir)) { try { fs.watch(dir, { recursive: false }, () => emit({ type: 'change' })); } catch (_) {} }
+    if (fs.existsSync(dir)) { try { watchers.push(fs.watch(dir, { recursive: false }, () => emit({ type: 'change' }))); } catch (_) {} }
   });
-  const proj = { id, root: entry.path, handlers, clients, emit };
+  const proj = { id, root: entry.path, handlers, clients, emit, watchers };
   projects.set(id, proj);
   return proj;
 }
 
-// Only called after getProject(id) already returned null — figures out WHY, so the 404 points the
-// user at the right fix instead of a bare "unknown project". The two common real causes: never
-// registered at all, vs. registered but this project predates handlers.js (needs `spectoflow
-// update`) or its folder moved/was deleted.
+// Only called after getProject(id) returned null. Two causes remain (D64 removed "needs an update").
 function projectErrorMessage(id) {
   const entry = registry.listProjects().find((p) => p.id === id);
   if (!entry) return 'Unknown project.';
-  if (!fs.existsSync(entry.path)) return `Project "${entry.name}" is registered, but its folder no longer exists at ${entry.path}.`;
-  const handlersPath = path.join(entry.path, '.spectoflow', 'dashboard', 'handlers.js');
-  if (!fs.existsSync(handlersPath)) return `Project "${entry.name}" needs an update — run \`spectoflow update\` inside it, then reload this page.`;
-  return `Project "${entry.name}" is registered, but its dashboard code failed to load — check its .spectoflow/dashboard/handlers.js for errors.`;
+  return `Project "${entry.name}" is registered, but its folder no longer exists at ${entry.path}.`;
 }
 
-// Clears every require.cache entry under this project's own .spectoflow/ tree (its vendored
-// handlers.js and everything IT requires — orchestrator.js, runner.js, files.js, summarize.js,
-// lib/store.js, lib/agents-registry.js) and drops its cached Map entry. The require cache keys by
-// absolute path, so this can never touch another project's identically-named files. Returns false
-// (a harmless no-op, not an error) if this id was never loaded — nothing to invalidate.
+// Re-opens a project: drops its cached entry and closes its watchers so the next request re-runs
+// onBoot and re-watches (a project's dirs may have changed after `spectoflow update`). Returns false
+// (a harmless no-op) if this id was never loaded.
 function reloadProject(id) {
   const proj = projects.get(id);
   if (!proj) return false;
-  const prefix = path.join(proj.root, '.spectoflow') + path.sep;
-  for (const key of Object.keys(require.cache)) {
-    if (key.startsWith(prefix)) delete require.cache[key];
-  }
+  proj.watchers.forEach((w) => { try { w.close(); } catch (_) {} });
+  require('./orchestrator').clearPending(proj.root);
   projects.delete(id);
   return true;
 }
 
 // ---- hub API: list/add/remove registered projects, browse the filesystem to find one ----
 function projectStats(root) {
-  // Best-effort — a moved/deleted/corrupt project must never break the whole listing.
   try {
-    const store = require(path.join(root, '.spectoflow', 'lib', 'store.js'));
     const plans = store.readPlans(root);
     let total = 0, done = 0;
     for (const pl of plans) for (const ph of pl.phases) for (const t of ph.tasks) { total++; if (t.status === 'done') done++; }
@@ -130,10 +121,10 @@ function addHubProject(rawPath) {
   if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return { error: 'That folder does not exist.' };
   const hasSpectoflow = fs.existsSync(path.join(abs, '.spectoflow'));
   if (!hasSpectoflow) {
-    const { runInit } = require('./init');
+    const { runInit } = require('../init');
     runInit({ target: abs, templatesDir: TEMPLATES, version: VERSION });
   }
-  const entry = registry.addProject(abs);
+  const entry = workspace.registerProject(abs);
   return { entry, initialized: !hasSpectoflow };
 }
 async function handleHubApi(req, res, u) {
@@ -168,8 +159,8 @@ async function handleHubApi(req, res, u) {
 }
 
 // Serves one static asset (or the SPA index.html fallback for an extensionless path) from the
-// shared, globally-installed PUBLIC dir — identical logic to templates/dashboard/server.js's own,
-// just factored into a function since both the root-level and /p/<id>/-prefixed requests need it.
+// shared, globally-installed PUBLIC dir — factored into a function since both the root-level and
+// /p/<id>/-prefixed requests need it.
 function serveStatic(reqPath, req, res) {
   const file = reqPath === '/' ? '/index.html' : reqPath;
   const full = path.join(PUBLIC, path.normalize(file).replace(/^(\.\.[/\\])+/, ''));
@@ -193,7 +184,7 @@ function serveStatic(reqPath, req, res) {
 
 const PROJECT_PREFIX = /^\/p\/([0-9a-f]{6})(\/.*)?$/;
 
-const LOCK = registry.hubLockPath();
+const LOCK = workspace.lockPath();
 function writeLock(){ try{ fs.mkdirSync(path.dirname(LOCK),{recursive:true}); fs.writeFileSync(LOCK, JSON.stringify({ pid:process.pid, port:PORT, url:`http://localhost:${PORT}`, startedAt:new Date().toISOString() })+'\n'); }catch{} }
 function clearLock(){ try{ const l=JSON.parse(fs.readFileSync(LOCK,'utf8')); if(l.pid===process.pid) fs.unlinkSync(LOCK); }catch{} }
 process.on('exit', clearLock);
@@ -255,4 +246,4 @@ const server = http.createServer(async (req, res) => {
   } catch (e) { sendJSON(res, 500, { error: String(e && e.message || e) }); }
 });
 
-server.listen(PORT, () => { writeLock(); console.log(`spectoflow · hub → http://localhost:${PORT}`); });
+server.listen(PORT, () => { writeLock(); console.log(`spectoflow · hub → http://localhost:${PORT}${migrated.movedRegistry ? '  (moved your project list into the workspace)' : ''}`); });

package/lib/dashboard/ops.js

@@ -0,0 +1,176 @@
+'use strict';
+/*
+ * The dashboard's operations — one pure function per action, (root, args, ctx) → result, with no
+ * HTTP in sight. handlers.js maps HTTP routes onto this table; the online dashboard (sub-project C)
+ * will map WebSocket messages onto the very same table. ctx.emit broadcasts SSE events to every
+ * client of this project; ops call it themselves after a successful mutation so any caller gets
+ * the same live behaviour. Errors are OpError(status, message) — the transport turns status into
+ * its own vocabulary (HTTP status code today).
+ */
+const fs = require('fs');
+const path = require('path');
+const store = require('../store');
+const files = require('./files');
+const { startRun } = require('./runner');
+const { runSummarize } = require('./summarize');
+const orchestrator = require('./orchestrator');
+const adapters = require('../adapters');
+const detect = require('../detect');
+
+const PKG_VERSION = require('../../package.json').version;
+
+class OpError extends Error {
+  constructor(status, message) { super(message); this.status = status; }
+}
+const bad = (msg) => { throw new OpError(400, msg); };
+const notFound = (msg) => { throw new OpError(404, msg); };
+const text = (v, msg) => { if (!v || !String(v).trim()) bad(msg); return String(v).trim(); };
+
+function frameworkVersion(root) {
+  try { return JSON.parse(fs.readFileSync(path.join(root, '.spectoflow', '.manifest.json'), 'utf8')).version || PKG_VERSION; } catch { return PKG_VERSION; }
+}
+function findPlanFileForTask(root, id) {
+  for (const pl of store.readPlans(root)) for (const ph of pl.phases) if (ph.tasks.find((t) => t.id === id)) return pl.file;
+  return null;
+}
+function readAgentFile(root, rel) {
+  const base = path.join(root, '.spectoflow');
+  const aDir = path.join(base, 'agents'), sDir = path.join(base, 'skills');
+  const abs = path.resolve(base, rel || '');
+  const okDir = abs.startsWith(aDir + path.sep) || abs.startsWith(sDir + path.sep);
+  if (!okDir || !abs.endsWith('.md') || !fs.existsSync(abs) || fs.statSync(abs).isDirectory()) bad('not an agent/skill file');
+  let real; try { real = fs.realpathSync(abs); } catch { real = null; }
+  const realA = (() => { try { return fs.realpathSync(aDir); } catch { return aDir; } })();
+  const realS = (() => { try { return fs.realpathSync(sDir); } catch { return sDir; } })();
+  const okReal = real && (real.startsWith(realA + path.sep) || real.startsWith(realS + path.sep));
+  if (!okReal || !real.endsWith('.md') || fs.statSync(real).isDirectory()) bad('not an agent/skill file');
+  return { content: fs.readFileSync(real, 'utf8') };
+}
+function writeConfig(root, patch, detectOpts) {
+  const cp = path.join(root, '.spectoflow', 'config.json');
+  const cfg = JSON.parse(fs.readFileSync(cp, 'utf8'));
+  if (patch.mode && ['autopilot', 'semi', 'manual'].includes(patch.mode)) cfg.mode = patch.mode;
+  if (typeof patch.language === 'string' && patch.language.trim()) cfg.language = patch.language.trim();
+  if (typeof patch.design === 'string' && /^[a-z0-9-]{1,40}$/.test(patch.design)) cfg.design = patch.design;
+  if (typeof patch.agent === 'string' && patch.agent.trim()) {
+    const id = patch.agent.trim();
+    const known = adapters.knownAgents().find((a) => a.id === id);
+    // Never activate an agent whose CLI isn't actually there — it would just fail silently later.
+    if (!detect.isAgentInstalled(id, root, detectOpts)) bad(`${known ? known.label : id} isn't installed here (its command wasn't found on PATH). Install it, then try again.`);
+    cfg.agent = id;
+    if (known && known.runner) { cfg.runners = cfg.runners || {}; if (!cfg.runners[id]) cfg.runners[id] = known.runner; }
+  }
+  fs.writeFileSync(cp, JSON.stringify(cfg, null, 2) + '\n');
+  return cfg;
+}
+const filesResult = (r) => { if (r.error) bad(r.error); return r; };
+const changed = (ctx, result) => { ctx.emit({ type: 'change' }); return result; };
+
+const ops = {
+  'project.read': async (root) => {
+    const p = store.readProject(root);
+    p.version = frameworkVersion(root);
+    p.projectName = path.basename(root);
+    p.knownAgents = adapters.knownAgents().map((a) => ({ id: a.id, label: a.label, headless: a.headless, docsUrl: a.docsUrl }));
+    p.installedAgents = detect.installedAgents(root);
+    return p;
+  },
+  'agentfile.read': async (root, { path: rel }) => readAgentFile(root, rel),
+
+  'files.tree': async (root) => ({ tree: files.tree(root) }),
+  'files.read': async (root, { path: rel }) => filesResult(files.readFile(root, rel || '')),
+  'files.write': async (root, { path: rel, content }, ctx) => changed(ctx, filesResult(files.writeFile(root, rel, content))),
+  'files.mkdir': async (root, { path: rel }, ctx) => changed(ctx, filesResult(files.mkdir(root, rel))),
+
+  'task.add': async (root, { title, phase, file, owner, level }, ctx) => {
+    const t = store.addTask(root, { title: text(title, 'A title is required.'), phase, file, owner, level });
+    return changed(ctx, { task: t });
+  },
+  'task.update': async (root, { id, patch }, ctx) => {
+    const file = findPlanFileForTask(root, id); if (!file) notFound(`Task ${id} not found.`);
+    store.updateTaskLine(root, file, id, patch || {});
+    return changed(ctx, { ok: true });
+  },
+  'task.comment': async (root, { id, text: body, action }, ctx) => {
+    const msg = text(body, 'Empty comment.');
+    const file = findPlanFileForTask(root, id); if (!file) notFound(`Task ${id} not found.`);
+    store.addTaskComment(root, file, id, msg, 'me');
+    if (action === 'analyze') store.updateTaskLine(root, file, id, { status: 'to_analyze' });
+    return changed(ctx, { ok: true });
+  },
+  'workflow.toggle': async (root, { name }, ctx) => {
+    const wf = path.join(root, '.spectoflow', 'workflow.md');
+    const lines = fs.readFileSync(wf, 'utf8').split('\n');
+    // Strip the trailing {cap:... skill:... policy} annotation BEFORE "(optional)" — the same order as
+    // store.readWorkflow(), which is what the client's step names come from (D60).
+    const stepName = (rest) => { const ann = rest.match(/\{([^}]*)\}\s*$/); if (ann) rest = rest.slice(0, ann.index).trim(); return rest.replace(/\s*\(optional\)\s*$/i, '').trim(); };
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(/^(\s*- \[)( |x|X)(\]\s+)(.*)$/);
+      if (m && stepName(m[4]) === name) lines[i] = m[1] + (m[2].trim() ? ' ' : 'x') + m[3] + m[4];
+    }
+    fs.writeFileSync(wf, lines.join('\n'));
+    return changed(ctx, { ok: true });
+  },
+
+  'run.start': async (root, { prompt, agent }, ctx) => {
+    text(prompt, 'Empty request.');
+    const r = startRun(root, { prompt, agent }, ctx.emit);
+    if (r.error) bad(r.error);
+    return { runId: r.runId };
+  },
+  'chat.summarize': async (root, { agent }, ctx) => {
+    const r = runSummarize(root, { agent }, ctx.emit);
+    if (r.error) bad(r.error);
+    return { ok: true };
+  },
+  'chat.clear': async (root, _args, ctx) => {
+    const rt = store.readRuntime(root); rt.messages = []; store.writeRuntime(root, rt);
+    return changed(ctx, { ok: true });
+  },
+  'orchestrate.start': async (root, { request }, ctx) => {
+    const req = text(request, 'Empty request.');
+    const active = store.readRuntime(root).orchestration;
+    if (active && ['running', 'awaiting_approval'].includes(active.status)) throw new OpError(409, 'An orchestration is already active.');
+    const mode = store.readConfig(root).mode || 'semi';
+    orchestrator.runOrchestration({ root, request: req, mode, runStep: orchestrator.defaultRunStep, confirm: orchestrator.defaultConfirm }, ctx.emit)
+      .catch((e) => ctx.emit({ type: 'message', message: { role: 'orchestrator', kind: 'status', text: 'orchestration error: ' + e.message } }));
+    const o = store.readRuntime(root).orchestration;
+    return { orchestrationId: o && o.id };
+  },
+  'orchestrate.approve': async (root, { decision, note }) => {
+    if (!orchestrator.submitDecision(decision, note, root)) throw new OpError(409, 'No pending approval.');
+    return { ok: true };
+  },
+
+  'settings.save': async (root, patch, ctx) => changed(ctx, { config: writeConfig(root, patch || {}, ctx.env ? { env: ctx.env } : undefined) }),
+
+  'attention.add': async (root, { text: body }, ctx) => {
+    const msg = text(body, 'Empty note.');
+    const rt = store.readRuntime(root); rt.attention = rt.attention || [];
+    const item = { id: 'att' + Date.now().toString(36), at: new Date().toISOString(), by: 'me', source: 'user', status: 'open', text: msg };
+    rt.attention.unshift(item); store.writeRuntime(root, rt);
+    return changed(ctx, { item });
+  },
+  'attention.promote': async (root, { id }, ctx) => {
+    const rt = store.readRuntime(root); const it = (rt.attention || []).find((x) => x.id === id);
+    if (!it) notFound('Note not found.');
+    const t = store.addTask(root, { phase: 'Attention', title: it.text, owner: 'user' });
+    it.status = 'resolved'; it.promotedTo = t.id; store.writeRuntime(root, rt);
+    return changed(ctx, { task: t });
+  },
+  'attention.update': async (root, { id, patch }, ctx) => {
+    const rt = store.readRuntime(root); const it = (rt.attention || []).find((x) => x.id === id);
+    if (!it) notFound('Note not found.');
+    const p = patch || {};
+    if (typeof p.text === 'string' && p.text.trim()) it.text = p.text.trim();
+    if (p.status && ['open', 'resolved'].includes(p.status)) it.status = p.status;
+    store.writeRuntime(root, rt);
+    return changed(ctx, { item: it });
+  },
+  'attention.remove': async (root, { id }, ctx) => {
+    const rt = store.readRuntime(root); rt.attention = (rt.attention || []).filter((x) => x.id !== id); store.writeRuntime(root, rt);
+    return changed(ctx, { ok: true });
+  },
+};
+
+module.exports = { ops, OpError };

package/{templates → lib}/dashboard/orchestrator.js

@@ -1,7 +1,7 @@
 'use strict';
 const fs = require('fs');
 const path = require('path');
-const store = require('../lib/store');
+const store = require('../store');
 const { startRun } = require('./runner');
 
 // step (from store.readWorkflow) -> { agent, skill } or { error }
@@ -54,7 +54,7 @@ async function runOrchestration({ root, request, mode, runStep, confirm, resume
     if (needConfirm) {
       st.status = 'awaiting_approval'; o.status = 'awaiting_approval'; saveState(root, o, emit);
       post(root, 'orchestrator', 'question', `Approve step "${step.name}" (${r.agent})${policyGated ? ' — policy gate' : ''}?`, emit);
-      const dec = await confirm(step, { policy: policyGated });
+      const dec = await confirm(step, { policy: policyGated, root });
       post(root, 'orchestrator', 'status', `decision: ${dec.decision}${dec.note ? ' — ' + dec.note : ''}`, emit);
       if (dec.decision === 'cancel') { st.status = 'skipped'; o.status = 'cancelled'; saveState(root, o, emit); return o; }
       o.status = 'running'; saveState(root, o, emit);
@@ -94,12 +94,21 @@ function defaultRunStep({ root, step, agent, skill, request }, emit) {
   });
 }
 
-let pending = null;
-function defaultConfirm(step, reason) { return new Promise((resolve) => { pending = { resolve }; }); }
-function submitDecision(decision, note) {
-  if (!pending) return false;
-  const p = pending; pending = null; p.resolve({ decision, note }); return true;
+// Keyed by project root — before this hub shared one orchestrator.js instance across every project
+// (D64), a single module-level `pending` here was a real cross-project leak: approving in one
+// project could resolve (or silently overwrite) another project's pending gate.
+const pending = new Map(); // root -> { resolve }
+function defaultConfirm(step, reason) { return new Promise((resolve) => { pending.set(reason && reason.root, { resolve }); }); }
+function submitDecision(decision, note, root) {
+  const p = pending.get(root);
+  if (!p) return false;
+  pending.delete(root);
+  p.resolve({ decision, note });
+  return true;
 }
+// Drops any pending approval for `root` — called when a project is reloaded (its whole in-flight
+// session is considered gone) so a stale resolver can never be sitting around after the fact.
+function clearPending(root) { pending.delete(root); }
 
 // Boot-time reconcile: a process restart loses any in-flight orchestration (the runOrchestration
 // call stack, and the in-memory `pending` approval) even though runtime.json still records it as
@@ -116,4 +125,4 @@ function reconcileOnBoot(root) {
   return true;
 }
 
-module.exports = { resolveStep, runOrchestration, defaultRunStep, defaultConfirm, submitDecision, reconcileOnBoot };
+module.exports = { resolveStep, runOrchestration, defaultRunStep, defaultConfirm, submitDecision, clearPending, reconcileOnBoot };

package/{templates → lib}/dashboard/public/app.js

@@ -17,9 +17,8 @@ let attnFilter = 'open';                          // attention tab filter — cl
 
 // The project this dashboard tab is showing — derived once from the URL's /p/<id>/... prefix. The
 // hub-server's legacy-route redirect (sub-project 3) guarantees a bookmark without this prefix never
-// reaches this file directly; it 302s to a /p/<id>/... URL first. Null when served by the older
-// single-project templates/dashboard/server.js (no prefix at all) — every helper below no-ops in
-// that case, preserving today's exact single-project behavior.
+// reaches this file directly; it 302s to a /p/<id>/... URL first. Null defensively (no prefix at
+// all) — every helper below no-ops in that case rather than assuming the prefix is always present.
 const PROJECT_ID = (() => { const m = location.pathname.match(/^\/p\/([0-9a-f]{6})(?:\/|$)/); return m ? m[1] : null; })();
 // Every /api/* fetch/EventSource call funnels its URL through this — the one place a project id gets
 // attached, so no call site can forget it. Handles both "no query string yet" (?p=) and "already has
@@ -363,17 +362,26 @@ function renderOverview(){
   topRow.append(ocard(t('chart.scopeVsDelivered'), area));
   box.append(topRow);
 
-  // Workflow-at-a-glance strip (reuses the wf-arrow flow animation)
+  // Workflow-at-a-glance strip (reuses the wf-arrow flow animation) — clicking a step opens the same
+  // enable/disable popover as the dedicated Workflow tab (openWfPop/renderWfPop), so a step can be
+  // toggled right from the Board without switching tabs.
   const strip=el('div','wf-strip');
   const steps=P.workflow||[];
   steps.forEach((st,i)=>{
-    const node=el('div','wf-mini'+(st.enabled?'':' off'));
+    const node=el('div','wf-mini'+(st.enabled?'':' off')+(st.name===wfPopStep?' is-selected':''));
+    node.dataset.name=st.name;
+    node.tabIndex=0; node.setAttribute('role','button'); node.setAttribute('aria-expanded',String(st.name===wfPopStep));
+    node.title=st.name;
     node.append(el('span','dot')); node.append(el('span','nm',st.name));
+    const sel=(e)=>{ e.stopPropagation(); if(wfPopStep===st.name) closeWfPop(); else openWfPop(st.name); };
+    node.addEventListener('click',sel);
+    node.addEventListener('keydown',e=>{ if(e.key==='Enter'||e.key===' '){ e.preventDefault(); sel(e); } });
     strip.append(node);
     if(i<steps.length-1){ const a=el('div','wf-arrow'+(st.enabled&&steps[i+1].enabled?'':' off')); strip.append(a); }
   });
   if(!steps.length) strip.append(el('div','empty',t('board.noWorkflow')));
   box.append(ocard(t('board.workflowGlance'), strip));
+  if(wfPopStep) renderWfPop(); // re-anchor an open popover after a live re-render of this strip too
 
   // Per-phase progress bars — only phases that actually hold tasks (headings with no checkbox tasks
   // are noise, not phases), and cap the list height with an internal scroll so a big project with
@@ -675,16 +683,27 @@ function wfPopFill(pop, s, idx){
   const actions=el('div','wf-pop-actions'); actions.append(btn); pop.append(actions);
 }
 function openWfPop(name){ wfPopStep=name; renderWfPop(); }
-function closeWfPop(){ wfPopStep=null; const p=$('#wfPop'); if(p) p.hidden=true; $$('#wfDiagram .wf-step2.is-selected').forEach(x=>x.classList.remove('is-selected')); }
+function closeWfPop(){ wfPopStep=null; const p=$('#wfPop'); if(p) p.hidden=true; $$('#wfDiagram .wf-step2.is-selected,.wf-mini.is-selected').forEach(x=>x.classList.remove('is-selected')); }
+// The workflow popover has two possible triggers now: the dedicated Workflow tab's own pipeline
+// (#wfDiagram .wf-step2), and the Board's "at a glance" strip (.wf-mini). Both stay mounted in the
+// DOM at all times (every .panel renders every tick; only CSS hides the inactive ones), so anchoring
+// always prefers whichever one sits on the currently VISIBLE panel — a hidden panel's element has a
+// zero-size getBoundingClientRect() and would position the popover at the top-left corner.
+function findWfAnchor(name){
+  const boardActive=document.querySelector('.panel[data-panel="board"].is-active');
+  if(boardActive){ const m=boardActive.querySelector('.wf-mini[data-name="'+CSS.escape(name)+'"]'); if(m) return m; }
+  const idx=(P.workflow||[]).findIndex(s=>s.name===name);
+  return $('#wfDiagram .wf-step2[data-idx="'+idx+'"]');
+}
 function renderWfPop(){
   const p=$('#wfPop'); if(!p) return;
   const steps=P.workflow||[]; const idx=steps.findIndex(s=>s.name===wfPopStep);
   if(idx<0){ closeWfPop(); return; }
-  const anchor=$('#wfDiagram .wf-step2[data-idx="'+idx+'"]');
+  const anchor=findWfAnchor(wfPopStep);
   if(!anchor){ p.hidden=true; return; }
-  $$('#wfDiagram .wf-step2.is-selected').forEach(x=>x.classList.remove('is-selected')); anchor.classList.add('is-selected');
+  $$('#wfDiagram .wf-step2.is-selected,.wf-mini.is-selected').forEach(x=>x.classList.remove('is-selected')); anchor.classList.add('is-selected');
   wfPopFill(p, steps[idx], idx);
-  positionWfPop(anchor.querySelector('.wf-circle')||anchor, p);
+  positionWfPop(anchor.classList.contains('wf-step2')?(anchor.querySelector('.wf-circle')||anchor):anchor, p);
 }
 function positionWfPop(anchorEl, pop){
   const r=anchorEl.getBoundingClientRect();
@@ -886,12 +905,12 @@ async function saveSettings(){
 }
 
 // ---- Custom dashboards (Customize page → generate-dashboard skill) ---------------------------
-// A custom dashboard is a DECLARATIVE block spec (.spectoflow/dashboard/custom/<id>.json, embedded
+// A custom dashboard is a DECLARATIVE block spec (.spectoflow/dashboards/<id>.json, embedded
 // in P.customDashboards by the server) — never raw HTML/CSS/JS. Every block below reuses the exact
 // same components the built-in Board renders with (kpiCard/ocard/bars/donut/statTile/mdLite/el), so a
 // generated dashboard automatically matches the active design — and any design switched to later —
-// with zero page-specific styling. Mirrors the schema in .spectoflow/lib/custom-dashboard.js (the
-// Node-side validator); this is the independent browser-side reader for the same shape.
+// with zero page-specific styling. The block schema is enforced by `spectoflow dashboard validate`
+// (Node-side validator); this is the independent browser-side reader for the same shape.
 function resolveBind(s,bindPath,fallback){
   if(bindPath==null) return fallback;
   let v=s;
@@ -1070,6 +1089,7 @@ function tabFromPath(){
 }
 function taskFromPath(){ const s=pathSegments(); return (ROUTES.includes(s[0])&&s[1])?decodeURIComponent(s[1]):null; }
 function navigateTab(tabId,push){
+  closeWfPop(); // an open popover is anchored to whichever panel is currently active — never carry it across
   activeTab=tabId; try{ localStorage.setItem('spf-tab',tabId); }catch{}
   if(push!==false){
     const isCustom=tabId.indexOf('custom:')===0;
@@ -1711,7 +1731,7 @@ document.addEventListener('click',e=>{ if(!document.body.classList.contains('nav
 document.addEventListener('keydown',e=>{ if(e.key==='Escape') closeNav(); });
 // workflow step popover — close on outside click / Esc / resize. (No scroll-to-close: a capture
 // scroll listener also fires on the popover's own internal scroll, which would slam it shut.)
-document.addEventListener('click',e=>{ if(wfPopStep && !e.target.closest('#wfPop') && !e.target.closest('.wf-step2')) closeWfPop(); });
+document.addEventListener('click',e=>{ if(wfPopStep && !e.target.closest('#wfPop') && !e.target.closest('.wf-step2') && !e.target.closest('.wf-mini')) closeWfPop(); });
 document.addEventListener('keydown',e=>{ if(e.key==='Escape') closeWfPop(); });
 window.addEventListener('resize',()=>{ if(wfPopStep) closeWfPop(); });
 // keep the URL and the path in sync when the user uses the browser back/forward buttons

package/{templates → lib}/dashboard/public/styles.css

@@ -142,7 +142,12 @@ body { background:var(--bg); color:var(--ink); font-family:var(--sans); font-siz
 .legend-count { font-family:var(--mono); color:var(--ink); font-weight:600; }
 
 .wf-strip { display:flex; flex-wrap:wrap; align-items:center; gap:0; }
-.wf-mini { display:flex; align-items:center; gap:6px; padding:6px 11px; border:1px solid var(--line); border-radius:999px; background:var(--surface-2); font-size:11.5px; font-weight:600; white-space:nowrap; }
+/* Clickable — opens the same enable/disable popover as the dedicated Workflow tab (see
+   findWfAnchor/openWfPop in app.js), so a step can be toggled right from this Board glance strip. */
+.wf-mini { display:flex; align-items:center; gap:6px; padding:6px 11px; border:1px solid var(--line); border-radius:999px; background:var(--surface-2); font-size:11.5px; font-weight:600; white-space:nowrap; cursor:pointer; transition:border-color .15s,transform .15s,box-shadow .15s; }
+.wf-mini:hover { border-color:var(--signal); transform:translateY(-1px); }
+.wf-mini:focus-visible { outline:2px solid var(--signal); outline-offset:1px; }
+.wf-mini.is-selected { border-color:var(--signal); border-style:solid; box-shadow:0 0 0 3px color-mix(in srgb,var(--signal) 20%,transparent); }
 .wf-mini .dot { width:6px; height:6px; border-radius:50%; background:var(--s-done); }
 .wf-mini.off { opacity:.42; border-style:dashed; }
 .wf-mini.off .dot { background:var(--faint); }

package/{templates → lib}/dashboard/runner.js

@@ -5,11 +5,12 @@
  * printing sentinel lines (::spectoflow role=… kind=… msg=…) which become structured messages;
  * any other output streams raw as run-line events. `emit` publishes SSE events to the dashboard.
  *
- * Kept separate from server.js so the pipeline is unit-testable without an HTTP server.
+ * Kept separate from the HTTP layer so the pipeline is unit-testable without a server.
  */
 const { spawn } = require('child_process');
-const store = require('../lib/store');
-const agentsRegistry = require('../lib/agents-registry');
+const store = require('../store');
+const adapters = require('../adapters');
+const detect = require('../detect');
 
 // The command to run `which`: config.json's own runners map first (an explicit user choice always
 // wins), falling back to the registry's default for a known, headless-capable, genuinely-installed
@@ -17,8 +18,8 @@ const agentsRegistry = require('../lib/agents-registry');
 // the project's "active agent" and had a runner seeded into config.json for it.
 function resolveRunnerCommand(root, cfg, which, opts) {
   if (cfg.runners && cfg.runners[which]) return cfg.runners[which];
-  const known = agentsRegistry.KNOWN_AGENTS.find((a) => a.id === which);
-  if (known && known.runner && agentsRegistry.isAgentInstalled(which, root, opts)) return known.runner;
+  const known = adapters.knownAgents().find((a) => a.id === which);
+  if (known && known.runner && detect.isAgentInstalled(which, root, opts)) return known.runner;
   return null;
 }
 

package/{templates → lib}/dashboard/summarize.js

@@ -7,7 +7,7 @@
  * sitting right below it doesn't condense anything — it just adds noise on top of noise.
  */
 const { spawn } = require('child_process');
-const store = require('../lib/store');
+const store = require('../store');
 const { resolveRunnerCommand } = require('./runner');
 
 const DEFAULT_LIMIT = 40;

package/lib/detect.js

@@ -31,4 +31,19 @@ function detectAgents(projectRoot, opts = {}) {
   }).map((a) => a.id);
 }
 
-module.exports = { binOnPath, detectAgents };
+// True if `id` looks genuinely installed: its bin resolves on PATH, or the project already has its
+// config dir (a project can be set up for an agent whose bin isn't on THIS machine's PATH, e.g. a
+// remote/CI runner). Unknown ids are never "installed".
+function isAgentInstalled(id, projectRoot, opts) {
+  const a = REGISTRY.find((x) => x.id === id);
+  if (!a) return false;
+  if (a.detect.bin && binOnPath(a.detect.bin, opts)) return true;
+  return (a.detect.dirs || []).some((d) => fs.existsSync(path.join(projectRoot, d)));
+}
+
+// ids of every known agent actually installed for this project, in REGISTRY (priority) order.
+function installedAgents(projectRoot, opts) {
+  return REGISTRY.filter((a) => isAgentInstalled(a.id, projectRoot, opts)).map((a) => a.id);
+}
+
+module.exports = { binOnPath, detectAgents, isAgentInstalled, installedAgents };