spectoflow 0.23.5 → 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
@@ -906,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;

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 };

package/lib/global-config.js

@@ -0,0 +1,65 @@
+'use strict';
+/*
+ * Global config — ~/.spectoflow/config.json (or $SPECTOFLOW_HOME/config.json). Settings that apply
+ * to every project on this machine: where the dashboard workspace lives, which dashboard URL
+ * projects talk to, and the defaults `spectoflow init` seeds a new project's config.json with.
+ * Layering, lowest to highest: kit templates < these defaults < the project's own config.json.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { REGISTRY } = require('./adapters');
+
+const KEYS = ['dashboard.url', 'dashboard.path', 'defaults.agent', 'defaults.language', 'defaults.mode', 'defaults.design'];
+const MODES = ['autopilot', 'semi', 'manual'];
+
+function homeDir() { return process.env.SPECTOFLOW_HOME || path.join(os.homedir(), '.spectoflow'); }
+function configPath() { return path.join(homeDir(), 'config.json'); }
+function defaultDashboardPath() { return path.join(homeDir(), 'dashboard'); }
+function expandHome(p) { return p.startsWith('~') ? path.join(os.homedir(), p.slice(1)) : p; }
+
+function defaults() {
+  return { dashboard: { url: 'http://localhost:4319', path: defaultDashboardPath() }, defaults: { agent: 'claude', language: 'en', mode: 'semi', design: 'console' } };
+}
+function readRaw() {
+  try { return JSON.parse(fs.readFileSync(configPath(), 'utf8')) || {}; } catch { return {}; }
+}
+function writeRaw(obj) {
+  fs.mkdirSync(homeDir(), { recursive: true });
+  fs.writeFileSync(configPath(), JSON.stringify(obj, null, 2) + '\n');
+}
+const getPath = (obj, key) => key.split('.').reduce((o, k) => (o && o[k] !== undefined ? o[k] : undefined), obj);
+const setPath = (obj, key, value) => { const ks = key.split('.'); let o = obj; for (const k of ks.slice(0, -1)) o = (o[k] = o[k] || {}); o[ks[ks.length - 1]] = value; };
+
+function read() {
+  const d = defaults(), raw = readRaw();
+  return { dashboard: { ...d.dashboard, ...(raw.dashboard || {}) }, defaults: { ...d.defaults, ...(raw.defaults || {}) } };
+}
+function get(key) {
+  if (!KEYS.includes(key)) throw new Error(`unknown key "${key}" — valid keys: ${KEYS.join(', ')}`);
+  const raw = getPath(readRaw(), key);
+  return raw !== undefined ? { value: raw, source: 'set' } : { value: getPath(defaults(), key), source: 'default' };
+}
+function list() { return KEYS.map((key) => ({ key, ...get(key) })); }
+
+function validate(key, value) {
+  const v = String(value).trim();
+  switch (key) {
+    case 'dashboard.url': { let u; try { u = new URL(v); } catch { throw new Error('dashboard.url must be a URL, e.g. http://localhost:4319'); } if (!/^https?:$/.test(u.protocol)) throw new Error('dashboard.url must start with http:// or https://'); return u.origin; }
+    case 'dashboard.path': { if (!v) throw new Error('dashboard.path must be a folder path'); return path.resolve(expandHome(v)); }
+    case 'defaults.agent': { if (!REGISTRY.some((a) => a.id === v)) throw new Error(`unknown agent "${v}" — one of: ${REGISTRY.map((a) => a.id).join(', ')}`); return v; }
+    case 'defaults.language': { if (!/^[a-z]{2}$/.test(v)) throw new Error('defaults.language must be a 2-letter code (en, fr, es, de, pt, it…)'); return v; }
+    case 'defaults.mode': { if (!MODES.includes(v)) throw new Error(`defaults.mode must be one of: ${MODES.join(', ')}`); return v; }
+    case 'defaults.design': { if (!/^[a-z0-9-]{1,40}$/.test(v)) throw new Error('defaults.design must be a design id (console, orbit, …)'); return v; }
+    default: throw new Error(`unknown key "${key}" — valid keys: ${KEYS.join(', ')}`);
+  }
+}
+function set(key, value) {
+  const v = validate(key, value);
+  const raw = readRaw(); setPath(raw, key, v); writeRaw(raw);
+  return v;
+}
+// Creates the file (empty object) if it doesn't exist — never touches an existing one.
+function ensure() { if (!fs.existsSync(configPath())) writeRaw({}); }
+
+module.exports = { KEYS, homeDir, configPath, defaultDashboardPath, expandHome, read, get, set, list, ensure };

package/lib/init.js

@@ -12,7 +12,8 @@ const adapters = require('./adapters');
 const ownership = require('./ownership');
 const manifest = require('./manifest');
 const mcp = require('./mcp');
-const store = require('../templates/lib/store');
+const store = require('./store');
+const globalConfig = require('./global-config');
 
 function copyDir(src, dst) {
   fs.mkdirSync(dst, { recursive: true });
@@ -47,7 +48,7 @@ function normalizePlans(root, config) {
   return added;
 }
 
-function runInit({ target, templatesDir, version, agentsArg }) {
+function runInit({ target, templatesDir, version, agentsArg, defaults }) {
   fs.mkdirSync(target, { recursive: true });
   const notes = [];
 
@@ -79,7 +80,12 @@ function runInit({ target, templatesDir, version, agentsArg }) {
 
   const cfgPath = path.join(spectoflowDir, 'config.json');
   const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
-  cfg.agent = agents[0];
+  const d = defaults || globalConfig.read().defaults;
+  cfg.mode = d.mode; cfg.language = d.language; cfg.design = d.design;
+  // The active agent: an explicit --agent wins; else the global default when it's actually detected
+  // here (or nothing is); else the first detected one.
+  cfg.agent = agentsArg ? agents[0] : ((detected.includes(d.agent) || !detected.length) ? d.agent : detected[0]);
+  if (!agents.includes(cfg.agent)) agents.unshift(cfg.agent);
   cfg.runners = { ...cfg.runners, ...adapters.defaultRunners(agents) };
   fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
 
@@ -106,7 +112,7 @@ function runInit({ target, templatesDir, version, agentsArg }) {
 
   const gi = path.join(target, '.gitignore');
   const giText = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
-  for (const line of ['.spectoflow/runtime.json', '.spectoflow/.dashboard.lock']) {
+  for (const line of ['.spectoflow/runtime.json']) {
     if (!giText.includes(line)) fs.appendFileSync(gi, ((fs.existsSync(gi) && fs.readFileSync(gi, 'utf8').length) ? '\n' : '') + line + '\n');
   }
 

package/lib/registry.js

@@ -1,21 +1,20 @@
 'use strict';
 /*
- * The project registry — ~/.spectoflow/projects.json. Tracks every project spectoflow has seen (via
- * `spectoflow dashboard`, wired in a later sub-project), so the multi-project hub knows what to list
- * and switch between. This module owns only the registry file itself; it has no opinion about
- * dashboards, ports, or servers, and nothing else in the codebase calls it yet.
+ * The project registry — projects.json inside the dashboard workspace (see lib/workspace.js; default
+ * ~/.spectoflow/dashboard/). Tracks every project spectoflow has seen (via `spectoflow dashboard`), so
+ * the multi-project hub knows what to list and switch between. This module owns only the registry
+ * file itself; it has no opinion about ports or servers.
  */
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
 const crypto = require('crypto');
 
 const REGISTRY_FILE = 'projects.json';
 
-// Resolution order: an explicit baseDir (unit tests) > SPECTOFLOW_HOME (CLI-level test isolation,
-// same convention as SPECTOFLOW_ROOT/SPECTOFLOW_PORT elsewhere in this codebase) > the real home dir.
+// The registry lives inside the dashboard workspace (D64). An explicit baseDir (unit tests) wins;
+// otherwise the workspace is wherever the global config says (default $SPECTOFLOW_HOME/dashboard).
 function registryDir(baseDir) {
-  return baseDir || process.env.SPECTOFLOW_HOME || path.join(os.homedir(), '.spectoflow');
+  return baseDir || require('./global-config').read().dashboard.path;
 }
 function registryPath(baseDir) {
   return path.join(registryDir(baseDir), REGISTRY_FILE);
@@ -62,6 +61,7 @@ function addProject(projectPath, baseDir) {
       path: target,
       name: path.basename(target),
       lastOpened: new Date().toISOString(),
+      kind: 'spectoflow',
     };
     reg.projects.push(entry);
   } else {