spectoflow 0.24.0 → 0.27.1

package/README.md

@@ -11,7 +11,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/spectoflow"><img src="https://img.shields.io/npm/v/spectoflow.svg?color=e6a54b" alt="npm version"></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D18-5fb2cc" alt="node >= 18">
+  <img src="https://img.shields.io/badge/node-%3E%3D22-5fb2cc" alt="node >= 22">
   <img src="https://img.shields.io/badge/dependencies-0-4caf72" alt="zero dependencies">
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
 </p>
@@ -186,24 +186,36 @@ spectoflow dashboard                     # → http://localhost:4319 (or --port=
 dashboard already running on the port). `spectoflow status` tells you whether one is up. Zero
 dependencies, updates live via SSE + file watching.
 
+Want your own hosted, online dashboard instead of (or alongside) the local one? `server/` is a
+separate, self-hostable relay with a ready-made Docker deployment path — see
+[`server/docs/deploy-vps.md`](server/docs/deploy-vps.md).
+
 The header bar always shows the brand, the **active agent**, autonomy mode, language, a global-progress
-meter, a sync dot, and a **Run** quick-action. Ten tabs:
+meter, a sync dot, and a **Run** quick-action. Thirteen tabs — and **which ones you see, and in what
+order, is up to you** (Personalize → *Navigation tabs*: enable / disable / reorder; two of them ship
+off by default):
 
 - **Board** — the control-room Overview (compact KPI cards, a status donut, a **scope-vs-delivered
   area curve**, a workflow-at-a-glance strip, per-phase progress bars, filter chips + search) plus the
-  phase board.
-- **Chat** — a full-height group-chat panel with **Summarize** / **Clear**.
+  phase board, as a **List** or a **Kanban** whose columns you can show/hide and that pages long
+  columns instead of scrolling them.
+- **Chat** — a full-height group-chat panel with **Summarize** / **Clear** and **slash commands** (see
+  below).
 - **Requests** — tasks awaiting you (`to_validate` / `to_analyze`).
 - **Attention** — points the agent raised (a `::spectoflow attention msg=…` sentinel) or that you
   noted yourself — edit / resolve / delete, or **validate → task**.
 - **Backlog** — a flat sortable/filterable, paginated table of every task, defaulting to open work.
 - **Workflow** — the pipeline as step cards; click one to enable/disable it, which edits `workflow.md`.
 - **Agents & Skills** — enriched cards that open a full-body markdown drawer.
+- **Files** — a project file tree with read / write / create, syntax-highlighted (self-hosted Prism.js).
+- **Bloc note** *(off by default)* — a per-project post-it Markdown scratchpad.
+- **Daily meeting** *(off by default)* — dated notes (`.spectoflow/meetings/<date>.md`), written by
+  hand or generated by the active agent.
 - **Info** — a project-at-a-glance summary.
 - **Documentation** — the live supported-agents table (your own install status + links) plus the CLI
   command reference.
-- **Personalize** — autonomy mode, language, design, the active agent, and **Extend spectoflow** (see
-  *Customize* below).
+- **Personalize** — autonomy mode, language, design, the active agent, **navigation tabs**, **slash
+  commands**, and **Extend spectoflow** (see *Customize* below).
 
 URLs are real routes (`/board`, `/backlog/T-012`, …). Charts are zero-dep, hand-rolled SVG in
 `lib/dashboard/public/charts.js` (donut/area/bars/ring, animated, `prefers-reduced-motion`-aware), and
@@ -232,6 +244,16 @@ drawer is served by the one read-only endpoint, `GET /api/agentfile?path=` (scop
 `.spectoflow/agents/**` + `.spectoflow/skills/**`, path-traversal-safe) — the framework's only other
 server surface is unchanged.
 
+### Slash commands
+
+Type `/` in either chat surface to open an autocomplete of reusable **prompt macros** — pick one,
+type your text, send. Five ship built-in (`/spec`, `/plan`, `/revue`, `/resume`, `/rapport_jour`);
+add your own from **Personalize → Commands** (a trigger, a short description, and the instruction the
+agent receives — put `{{input}}` where your text should land, or it's appended). Expansion happens
+**client-side**, so it's fully agent-agnostic: the agent never sees the `/`, it gets the full
+instruction, while the chat log keeps the short `/rapport_jour focus bugs` you typed. Commands persist
+in `config.json` (the DB online), so they survive a refresh and travel with the project.
+
 ### Customize
 
 Personalize → **Extend spectoflow** lets you extend the project's own spectoflow install: add a

package/bin/spectoflow.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const http = require('http');
+const os = require('os');
 const readline = require('readline');
 const { spawn } = require('child_process');
 const store = require('../lib/store');
@@ -212,7 +213,6 @@ function dashboardInit() {
   } catch (e) { console.log(`${c.y('!')} ${e.message}`); process.exitCode = 1; }
 }
 
-const REMOTE_NOTE = 'This version manages local dashboards. Remote dashboards (login with a token) come in a later release — continuing with your local dashboard.';
 function isLocalUrl(u) { try { return ['localhost', '127.0.0.1', '::1'].includes(new URL(u).hostname); } catch { return true; } }
 // The one-time question every dashboard-starting command answers before doing anything else: which
 // dashboard should this project talk to? `--url` answers it without prompting. Otherwise, only when
@@ -241,7 +241,6 @@ async function resolveDashboardUrl() {
     globalConfig.set('dashboard.url', answer || globalConfig.get('dashboard.url').value);
   }
   const url = globalConfig.get('dashboard.url').value;
-  if (!isLocalUrl(url)) console.log(`${c.y('!')} ${REMOTE_NOTE}`);
   return url;
 }
 
@@ -250,7 +249,10 @@ async function resolveDashboardUrl() {
 async function dashboard() {
   const sub = argv[1];
   if (sub === 'init') return dashboardInit();
-  if (sub === 'login') { console.log(REMOTE_NOTE); return; }
+  if (sub === 'login') return dashboardLogin();
+  if (sub === 'logout') return dashboardLogout();
+  if (sub === 'publish') return dashboardPublish(true);
+  if (sub === 'unpublish') return dashboardPublish(false);
   if (sub === 'stop') return stopDashboard();
   if (sub === 'status') return dashboardStatus();
   if (sub === 'restart') return restartDashboard();
@@ -259,6 +261,80 @@ async function dashboard() {
   return startDashboard();
 }
 
+// ---- online dashboard (C1): login / logout / publish / unpublish ----
+// The machine token authenticates this machine to a hosted dashboard (server/). `login` checks it
+// against POST /connector/whoami, stores it in the workspace's remote.json (0600) and points
+// dashboard.url at the server; the hub — running or next started — opens the outbound connection.
+async function fetchJSON(url, init = {}, timeoutMs = 10000) {
+  const res = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+  let data = {}; try { data = await res.json(); } catch {}
+  return { status: res.status, ok: res.ok, data };
+}
+// Best-effort call on the running local hub; null when no hub is up (the caller says "next start will").
+async function hubCall(pathname, payload) {
+  const info = workspace.readLock();
+  if (!info || !info.port || !(await probeDashboard(info.port))) return null;
+  try { return await fetchJSON(`http://localhost:${info.port}${pathname}`, payload === undefined ? {} : { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }); }
+  catch { return null; }
+}
+function fail(msg) { console.log(`${c.y('!')} ${msg}`); process.exitCode = 1; }
+async function dashboardLogin() {
+  const url = flag('url'), token = flag('token'), transport = flag('transport') || 'ws';
+  if (!url || !token) { console.log(`Usage: spectoflow dashboard login --url=<https://…> --token=<spf_…> ${c.dim('[--name=<machine name>] [--transport=ws|http]')}`); process.exitCode = 1; return; }
+  let base;
+  try { base = new URL(url); if (!/^https?:$/.test(base.protocol)) throw new Error(); } catch { return fail('--url must be an http(s) URL, e.g. https://dashboard.example.com'); }
+  if (!['ws', 'http'].includes(transport)) return fail('--transport must be ws or http');
+  const clean = base.toString().replace(/\/+$/, '');
+  let who;
+  try { who = await fetchJSON(`${clean}/connector/whoami`, { method: 'POST', headers: { Authorization: `Bearer ${token}` } }); }
+  catch (e) { return fail(`could not reach ${clean} (${e.cause && e.cause.code ? e.cause.code : e.name === 'TimeoutError' ? 'timeout' : e.message})`); }
+  if (who.status === 401) return fail(`${clean} rejected this token — create one on the server: node cli.js token create --name="${os.hostname()}"`);
+  if (!who.ok) return fail(`${clean} answered HTTP ${who.status} — is that the spectoflow server?`);
+  const machineName = flag('name') || os.hostname();
+  workspace.migrateLegacyHome(); if (!workspace.exists()) workspace.init({});
+  workspace.writeRemote({ url: clean, token, machineName, transport });
+  globalConfig.set('dashboard.url', clean);
+  console.log(`${c.g('✓')} logged in to ${c.bold(clean)} as ${c.bold(machineName)} ${c.dim(`(machine ${who.data.machineId || '?'}, ${transport})`)}`);
+  const r = await hubCall('/api/hub/remote/reconnect', {});
+  console.log(`  ${c.dim(r ? 'the running hub is connecting now' : 'the next `spectoflow dashboard` will connect')}`);
+  console.log(`  publish a project from inside it:  ${c.g('spectoflow dashboard publish')}`);
+}
+async function dashboardLogout() {
+  const had = workspace.clearRemote();
+  globalConfig.set('dashboard.url', `http://localhost:${resolvePort(argv)}`);
+  await hubCall('/api/hub/remote/reconnect', {});
+  console.log(had ? `${c.g('✓')} logged out — this machine no longer connects to an online dashboard` : `${c.dim('○')} not logged in to any online dashboard`);
+}
+async function dashboardPublish(published) {
+  let id = flag('id');
+  if (!id) {
+    const entry = registry.findByPath(process.cwd());
+    if (!entry) return fail(`this folder isn't registered in the dashboard yet — run ${c.g('spectoflow dashboard')} here first, or pass --id=<id> (see ${c.g('spectoflow projects')})`);
+    id = entry.id;
+  }
+  const meta = workspace.setPublished(id, published);
+  if (!meta) return fail(`no project registered with id ${id}`);
+  await hubCall(`/api/hub/projects/${encodeURIComponent(id)}/publish`, { published });
+  if (!published) return console.log(`${c.g('✓')} ${id} is no longer published`);
+  console.log(`${c.g('✓')} ${id} is published`);
+  const remote = workspace.readRemote();
+  if (remote) console.log(`  online: ${c.bold(remote.url)}`);
+  else console.log(`  ${c.dim('not logged in yet —')} ${c.g('spectoflow dashboard login --url=… --token=…')}`);
+}
+// The one-line "online" status under the local one — used by `dashboard` and `dashboard status`.
+async function printOnlineLine(port, running) {
+  const remote = workspace.readRemote();
+  if (remote) {
+    let s = null;
+    if (running) { try { s = (await fetchJSON(`http://localhost:${port}/api/hub/remote`)).data; } catch {} }
+    if (s && s.connected) return console.log(`${c.g('●')} online → ${c.bold(remote.url)} ${c.dim(`(connected via ${s.transport}, machine "${remote.machineName}")`)}`);
+    const why = !running ? 'hub not running' : s && s.lastError ? `not connected: ${s.lastError}` : 'connecting…';
+    return console.log(`${c.dim('○')} online → ${c.bold(remote.url)} ${c.dim(`(${why})`)}`);
+  }
+  const url = globalConfig.get('dashboard.url').value;
+  if (!isLocalUrl(url)) console.log(`${c.dim('○')} online → ${url} ${c.dim('— not logged in:')} ${c.g('spectoflow dashboard login --url=… --token=…')}`);
+}
+
 // ---- projects: the multi-project registry's CLI surface (the workspace's projects.json) ----
 function projectsCmd() {
   const sub = argv[1];
@@ -361,6 +437,7 @@ async function startDashboard() {
   const info = workspace.readLock();
   if (info && info.port && await probeDashboard(info.port)) {
     console.log(`${c.g('●')} hub already running → ${c.bold(boardUrl(info.port))}`);
+    await printOnlineLine(info.port, true);
     return printDashboardCommands();
   }
   const port = resolvePort(argv);
@@ -374,6 +451,7 @@ async function startDashboard() {
   for (let i = 0; i < 20 && !up; i++) { await new Promise((r) => setTimeout(r, 250)); up = await probeDashboard(port, 300); }
   if (up) console.log(`${c.g('✓')} hub started → ${c.bold(boardUrl(port))}  ${c.dim('(pid ' + child.pid + ')')}`);
   else console.log(`${c.y('!')} spawned (pid ${child.pid}) but it isn't responding on http://localhost:${port} yet — check ${c.g('spectoflow dashboard status')} in a moment, or its own output if something's wrong.`);
+  await printOnlineLine(port, up);
   printDashboardCommands();
 }
 
@@ -392,6 +470,7 @@ async function dashboardStatus() {
   const running = await probeDashboard(port);
   if (running) console.log(`${c.g('●')} hub running → ${c.bold('http://localhost:' + port)}${info && info.pid ? c.dim(' (pid ' + info.pid + ')') : ''}`);
   else console.log(`${c.dim('○')} hub not running`);
+  await printOnlineLine(port, running);
 }
 
 async function restartDashboard() {
@@ -504,7 +583,7 @@ ${c.bold('Dashboard')}
   ${c.g('dashboard status')}             is it running? (url + pid)
   ${c.g('dashboard stop')}               stop it ${c.dim('(alias: stop)')}
   ${c.g('dashboard restart')}            stop then start
-  ${c.g('dashboard login')}               connect to a remote dashboard ${c.dim('(coming in a later release)')}
+  ${c.g('dashboard login')} ${c.dim('--url=<u> --token=<t>')}  connect this machine to an online dashboard ${c.dim('(logout · publish · unpublish)')}
   ${c.g('projects')} ${c.dim('[remove <id>]')}     list every project seen so far
 
 ${c.bold('Customize')} ${c.dim('— same as Settings → Customize, from the terminal')}
@@ -542,7 +621,7 @@ const HELP = {
   ${c.g('--force')} (${c.g('-f')}) overwrites a diverged file in place instead of dropping a ${c.dim('*.new')}
   — use it when you know you have no local edits worth keeping (e.g. a file stuck diverged from an
   earlier update). It never touches config.json, workflow.md, specs/ or plans/.`,
-  dashboard: `${c.bold('spectoflow dashboard')} ${c.dim('[--port=NNNN] [--url=<u>] [init|status|stop|restart|create|validate|login]')}\n
+  dashboard: `${c.bold('spectoflow dashboard')} ${c.dim('[--port=NNNN] [--url=<u>] [init|status|stop|restart|create|validate|login|logout|publish|unpublish]')}\n
   Start the local control plane in the ${c.bold('background')} (default ${c.dim('4319')} or
   ${c.dim('$SPECTOFLOW_PORT')}) and hand the prompt back. ${c.g('--url=<u>')} sets which dashboard this
   project talks to (${c.dim('~/.spectoflow/config.json → dashboard.url')}) — asked once, interactively,
@@ -553,7 +632,10 @@ const HELP = {
     ${c.g('restart')}   stop then start
     ${c.g('create')}    generate a custom dashboard, e.g. ${c.dim('spectoflow dashboard create "..." --auto')}
     ${c.g('validate <file>')}  check a custom-view JSON against the block schema
-    ${c.g('login')}     connect to a remote dashboard ${c.dim('(coming in a later release)')}`,
+    ${c.g('login')}     connect this machine to an online dashboard: ${c.dim('--url=<https://…> --token=<spf_…> [--name=<machine>] [--transport=ws|http]')}
+    ${c.g('logout')}    forget it (remote.json removed, dashboard.url back to local)
+    ${c.g('publish')}   make the current project (or ${c.dim('--id=<id>')}) visible online — nothing is published by default
+    ${c.g('unpublish')} take it back offline`,
   projects: `${c.bold('spectoflow projects')} ${c.dim('[remove <id>]')}\n
   List every registered project in the global registry (the dashboard workspace's projects.json) (stored by
   ${c.g('spectoflow dashboard')}) — id, name, path. ${c.g('remove <id>')} drops one (e.g. a project that moved

package/lib/dashboard/connector.js

@@ -0,0 +1,193 @@
+'use strict';
+/*
+ * The local hub's outbound connector to an online dashboard (docs/online-dashboard-connector-design.md §2).
+ * One connection per machine; JSON frames, identical on both transports:
+ *   up:   auth {token,version} · hello {machineName,projects} · event {p,event} · snapshot {p,project} · reply {reqId,result|error} · pong
+ *   down: auth-ok {machineId} · op {reqId,p,op,args} · ping
+ * Transport 1 is Node's native WebSocket client (zero-dep, Node ≥ 22); transport 2 is HTTP long-poll
+ * (POST batches + GET held ≤ 25 s) for hosts that don't pass WebSockets (cPanel/Passenger). The hub
+ * decides nothing here: it hands in listPublished/readSnapshot/execOp and tees its emit into
+ * pushEvent/pushSnapshot. Reconnection: exponential backoff 1 s → 30 s with jitter; after an upgrade
+ * failure or 3 drops in 60 s the connector falls back to HTTP and retries WebSocket every 10 min.
+ * The token travels in-band (auth frame / Authorization header) — never in a URL, never logged.
+ */
+const DEFAULT_TIMING = { backoffMin: 1000, backoffMax: 30000, dropWindow: 60000, dropLimit: 3, wsRetryEvery: 600000, pollTimeout: 35000, wsOpenTimeout: 15000 };
+const REJECTED = 'token rejected by the server — run `spectoflow dashboard login` again';
+
+function createConnector(opts) {
+  const { token, machineName, listPublished, readSnapshot, execOp } = opts;
+  const version = opts.version || '0.0.0';
+  const base = String(opts.url || '').replace(/\/+$/, '');
+  const preferred = opts.transport === 'http' ? 'http' : 'ws';
+  const timing = { ...DEFAULT_TIMING, ...(opts.timing || {}) };
+  const log = opts.log || (() => {});
+
+  const state = { connected: false, lastError: null, machineId: null, attempts: 0, since: null };
+  let mode = preferred;          // transport in use ('ws' | 'http'); may fall back to 'http'
+  let stopped = true;
+  let active = null;             // the live transport: { send(frame), close() }
+  let generation = 0;            // bumps on every connect/stop so a stale transport's callbacks are ignored
+  const drops = [];
+  let reconnectTimer = null, wsRetryTimer = null;
+
+  function status() {
+    return { url: base, machineName, connected: state.connected, transport: mode, lastError: state.lastError, machineId: state.machineId, since: state.since };
+  }
+
+  // ---- frames ----
+  async function handleDownward(frame, send) {
+    if (!frame || typeof frame !== 'object') return;
+    if (frame.type === 'auth-ok') { state.machineId = frame.machineId || null; onConnected(); return; }
+    if (frame.type === 'ping') { send({ type: 'pong' }); return; }
+    if (frame.type === 'op') {
+      let reply;
+      try {
+        const result = await execOp(frame.p, frame.op, frame.args || {});
+        reply = { type: 'reply', reqId: frame.reqId, result: result === undefined ? {} : result };
+      } catch (e) {
+        reply = { type: 'reply', reqId: frame.reqId, error: { status: Number(e && e.status) || 500, message: String(e && e.message || e) } };
+      }
+      send(reply);
+    }
+  }
+  function onConnected() {
+    state.connected = true; state.lastError = null; state.attempts = 0; state.since = new Date().toISOString();
+    log(`online dashboard: connected to ${base} (${mode})`);
+    announce();
+  }
+  async function announce() {
+    const t = active;
+    if (!t || !state.connected) return;
+    const projects = listPublished();
+    t.send({ type: 'hello', machineName, projects });
+    for (const p of projects) {
+      try { const project = await readSnapshot(p.localId); if (project && t === active) t.send({ type: 'snapshot', p: p.localId, project }); }
+      catch (e) { log(`online dashboard: snapshot of ${p.localId} failed: ${e.message}`); }
+    }
+  }
+  function pushEvent(localId, event) { if (active && state.connected) active.send({ type: 'event', p: localId, event }); }
+  function pushSnapshot(localId, project) { if (active && state.connected) active.send({ type: 'snapshot', p: localId, project }); }
+
+  // ---- lifecycle ----
+  function onDisconnected(gen, err, { upgradeFailed = false } = {}) {
+    if (gen !== generation) return;           // a transport we already replaced
+    const was = state.connected;
+    state.connected = false; active = null;
+    if (err) state.lastError = String(err.message || err);
+    if (was) log(`online dashboard: disconnected from ${base}${err ? ' — ' + state.lastError : ''}`);
+    if (stopped) return;
+    if (mode === 'ws' && preferred === 'ws') {
+      const now = Date.now();
+      drops.push(now); while (drops.length && now - drops[0] > timing.dropWindow) drops.shift();
+      if (upgradeFailed || drops.length >= timing.dropLimit) {
+        mode = 'http'; drops.length = 0;
+        log('online dashboard: WebSocket unavailable, falling back to HTTP long-poll');
+        scheduleWsRetry();
+      }
+    }
+    scheduleReconnect();
+  }
+  function backoff() {
+    const exp = Math.min(timing.backoffMax, timing.backoffMin * 2 ** Math.min(state.attempts, 10));
+    state.attempts++;
+    return Math.round(exp * (0.75 + Math.random() * 0.5));
+  }
+  function scheduleReconnect() { clearTimeout(reconnectTimer); reconnectTimer = setTimeout(connect, backoff()); }
+  function scheduleWsRetry() {
+    clearTimeout(wsRetryTimer);
+    wsRetryTimer = setTimeout(() => { if (!stopped && mode === 'http') { mode = 'ws'; forceReconnect(); } }, timing.wsRetryEvery);
+  }
+  function connect() {
+    if (stopped) return;
+    clearTimeout(reconnectTimer);
+    const gen = ++generation;
+    active = mode === 'http' ? httpTransport(gen) : wsTransport(gen);
+  }
+  function start() { if (!stopped) return; stopped = false; mode = preferred; state.attempts = 0; connect(); }
+  function stop() {
+    stopped = true; generation++;
+    clearTimeout(reconnectTimer); clearTimeout(wsRetryTimer);
+    const t = active; active = null; state.connected = false;
+    if (t) t.close();
+  }
+  function forceReconnect() {
+    if (stopped) return;
+    const t = active; generation++; active = null; state.connected = false; state.attempts = 0;
+    if (t) t.close();
+    connect();
+  }
+
+  // ---- transport 1: native WebSocket ----
+  // A handshake that never resolves (no open/error/close at all — observed on some platforms when
+  // the server rejects the upgrade with a plain HTTP response) must still fail: wsOpenTimeout bounds
+  // it so the connector always falls back to HTTP instead of hanging forever in 'ws' mode.
+  function wsTransport(gen) {
+    let ws, opened = false, settled = false, lastErr = null;
+    const settle = (err, opts) => { if (settled) return; settled = true; clearTimeout(openTimer); onDisconnected(gen, err, opts); };
+    try { ws = new WebSocket(base.replace(/^http/, 'ws') + '/connector/ws'); }
+    catch (e) { setImmediate(() => settle(e, { upgradeFailed: true })); return { send() {}, close() {} }; }
+    const openTimer = setTimeout(() => {
+      try { ws.close(); } catch (_) {}
+      settle(new Error('WebSocket handshake timed out'), { upgradeFailed: true });
+    }, timing.wsOpenTimeout);
+    const send = (frame) => { if (ws.readyState === 1) ws.send(JSON.stringify(frame)); };
+    ws.addEventListener('open', () => { opened = true; clearTimeout(openTimer); send({ type: 'auth', token, version }); });
+    ws.addEventListener('message', (ev) => { let f; try { f = JSON.parse(String(ev.data)); } catch { return; } handleDownward(f, send); });
+    ws.addEventListener('error', (ev) => { lastErr = new Error((ev && ev.message) || 'websocket error'); });
+    ws.addEventListener('close', (ev) => {
+      const code = ev && ev.code;
+      const err = code === 4401 ? new Error(REJECTED) : lastErr || (code && code !== 1000 && code !== 1005 ? new Error(`connection closed (${code}${ev.reason ? ' ' + ev.reason : ''})`) : null);
+      settle(err, { upgradeFailed: !opened });
+    });
+    return { send, close: () => { clearTimeout(openTimer); try { ws.close(1000); } catch (_) {} } };
+  }
+
+  // ---- transport 2: HTTP long-poll ----
+  // Upward frames are POSTed in batches, strictly one batch in flight at a time (ordering). Downward
+  // frames arrive in the POST responses and through a GET loop the server holds open ≤ 25 s. The first
+  // batch carries `auth` so the frame sequence is the same as on WebSocket; the Authorization header is
+  // what actually authenticates every request.
+  function httpTransport(gen) {
+    const ac = new AbortController();
+    const headers = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };
+    let queue = [{ type: 'auth', token, version }];
+    let flushing = false, closed = false;
+    const alive = () => !closed && gen === generation;
+    const signal = () => AbortSignal.any([ac.signal, AbortSignal.timeout(timing.pollTimeout)]);
+    const fail = (e) => { if (!alive()) return; closed = true; ac.abort(); onDisconnected(gen, e); };
+    const check = (res, what) => {
+      if (res.status === 401) throw new Error(REJECTED);
+      if (!res.ok) throw new Error(`${what} /connector/frames → HTTP ${res.status}`);
+      return res.json();
+    };
+    async function flush() {
+      if (flushing) return;
+      flushing = true;
+      try {
+        while (alive() && queue.length) {
+          const batch = queue; queue = [];
+          const res = await fetch(base + '/connector/frames', { method: 'POST', headers, body: JSON.stringify(batch), signal: signal() });
+          const down = await check(res, 'POST');
+          for (const f of down) handleDownward(f, send);   // not awaited: a slow op must not stall the batch loop
+        }
+      } catch (e) { fail(e); } finally { flushing = false; }
+    }
+    async function poll() {
+      try {
+        while (alive()) {
+          const res = await fetch(base + '/connector/frames', { headers: { Authorization: headers.Authorization }, signal: signal() });
+          if (!alive()) return;
+          const down = await check(res, 'GET');
+          for (const f of down) handleDownward(f, send);   // not awaited: a slow op must not stall the batch loop
+        }
+      } catch (e) { fail(e); }
+    }
+    function send(frame) { if (!alive()) return; queue.push(frame); flush(); }
+    flush(); poll();
+    return { send, close: () => { closed = true; ac.abort(); } };
+  }
+
+  return { start, stop, status, announce, pushEvent, pushSnapshot, forceReconnect };
+}
+
+module.exports = { createConnector, DEFAULT_TIMING };

package/lib/dashboard/handlers.js

@@ -18,37 +18,12 @@ const orchestrator = require('./orchestrator');
 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({}); } }); }); }
 
-const seg = (p, i) => decodeURIComponent(p.split('/')[i] || '');
-const q = (u, k) => u.searchParams.get(k) || '';
-// [method, matcher, op, args(u, body, pathname)]
-const ROUTES = [
-  ['GET', '/api/project', 'project.read', () => ({})],
-  ['GET', '/api/agentfile', 'agentfile.read', (u) => ({ path: q(u, 'path') })],
-  ['GET', '/api/files/tree', 'files.tree', () => ({})],
-  ['GET', '/api/files/read', 'files.read', (u) => ({ path: q(u, 'path') })],
-  ['POST', '/api/files/write', 'files.write', (_u, b) => b],
-  ['POST', '/api/files/mkdir', 'files.mkdir', (_u, b) => b],
-  ['POST', '/api/task', 'task.add', (_u, b) => b],
-  ['PATCH', /^\/api\/task\/[^/]+$/, 'task.update', (_u, b, p) => ({ id: seg(p, 3), patch: b })],
-  ['POST', /^\/api\/task\/[^/]+\/comment$/, 'task.comment', (_u, b, p) => ({ id: seg(p, 3), text: b.text, action: b.action })],
-  ['POST', '/api/workflow/toggle', 'workflow.toggle', (_u, b) => b],
-  ['POST', '/api/run', 'run.start', (_u, b) => b],
-  ['POST', '/api/chat/summarize', 'chat.summarize', (_u, b) => b],
-  ['POST', '/api/chat/clear', 'chat.clear', () => ({})],
-  ['POST', '/api/orchestrate', 'orchestrate.start', (_u, b) => b],
-  ['POST', '/api/orchestrate/approve', 'orchestrate.approve', (_u, b) => b],
-  ['POST', '/api/settings', 'settings.save', (_u, b) => b],
-  ['POST', '/api/attention', 'attention.add', (_u, b) => b],
-  ['POST', /^\/api\/attention\/[^/]+\/promote$/, 'attention.promote', (_u, _b, p) => ({ id: seg(p, 3) })],
-  ['PATCH', /^\/api\/attention\/[^/]+$/, 'attention.update', (_u, b, p) => ({ id: seg(p, 3), patch: b })],
-  ['DELETE', /^\/api\/attention\/[^/]+$/, 'attention.remove', (_u, _b, p) => ({ id: seg(p, 3) })],
-];
-const matches = (m, p) => (typeof m === 'string' ? m === p : m.test(p));
+const { ROUTES, findRoute } = require('./routes');
 
 function createHandlers(root) {
   async function handleApi(req, res, u, emit) {
     const p = u.pathname;
-    const route = ROUTES.find(([method, m]) => method === req.method && matches(m, p));
+    const route = findRoute(req.method, p);
     if (!route) return false;
     const [, , opName, args] = route;
     const b = req.method === 'GET' ? {} : await body(req);