bullswarm 0.18.4 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # bullswarm changelog
 
+## 0.19.0 — unified workflow dashboard
+
+- Running `bullswarm workflow` on an interactive terminal now opens one
+  full-screen home for active and recent runs, with filtering, safe detach,
+  and direct navigation into each workflow's timeline, planner, phases,
+  agents, and activity.
+- Wide terminals pair the run list with a live selected-run preview. Narrow
+  phone and SSH terminals use a full-width stacked list before opening the
+  selected workflow, preserving readable navigation without duplicating the
+  desktop layout.
+- Non-interactive callers still receive side-effect-free help, existing JSON
+  contracts remain stable, and `workflow tui` remains a compatibility alias.
+- Exact-height mobile repainting now preserves the footer while retaining the
+  no-flash in-place refresh behavior.
+
+## 0.18.5 — no-flash workflow TUI
+
+- Full-screen workflow views repaint rows in place instead of repeatedly
+  clearing the terminal, removing the visible flash on slower mobile and SSH
+  sessions.
+
 ## 0.18.4 — reliable auto-follow tail
 
 - Timestamp-aligned mobile auto-follow now preserves the newest workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.18.4",
+  "version": "0.19.0",
   "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -430,7 +430,13 @@ async function cmdDoctor(opts) {
 // --- main ---------------------------------------------------------------------
 
 export async function main(argv) {
-  const help = helpForArgs(argv);
+  // Bare `bullswarm workflow` is the human workflow home on a terminal.
+  // Non-TTY callers still receive side-effect-free help, exactly as before.
+  const bareWorkflowDashboard = argv.length === 1
+    && argv[0] === 'workflow'
+    && process.stdin.isTTY
+    && process.stdout.isTTY;
+  const help = bareWorkflowDashboard ? null : helpForArgs(argv);
   if (help) {
     console.log(help);
     return 0;

package/src/help.js

@@ -528,10 +528,11 @@ const strategyAutoOffText = rich({
 // them branch on opts.json.
 
 const workflowText = rich({
-  usage: 'bullswarm workflow <command> [options]',
+  usage: 'bullswarm workflow [<command>] [options]',
   purpose: 'Create, execute, observe, and audit durable multi-agent workflows: autonomous '
     + 'goals, fixed workflow files, and incrementally-built drafts all run through the same '
-    + 'durable, resumable execution engine.',
+    + 'durable, resumable execution engine. With no command on a TTY, opens the unified '
+    + 'full-screen workflow dashboard.',
   argsTitle: 'Commands',
   args: [
     { name: 'goal "<goal>"', desc: 'autonomously plan, execute, verify, and replan a goal' },
@@ -551,6 +552,8 @@ const workflowText = rich({
   ],
   options: [],
   safety: [
+    'bare bullswarm workflow opens a read-only active/recent run dashboard only when stdin and '
+      + 'stdout are TTYs; non-interactive callers receive this help text instead',
     'reconcileInterruptedRuns() runs before every workflow subcommand dispatch — including a '
       + 'mistyped bare "help" argument, since only --help/-h/leading "help" bypass dispatch '
       + 'entirely — and can rewrite state.json for any run whose heartbeat looks stale',
@@ -560,6 +563,7 @@ const workflowText = rich({
       + 'their own --help)',
   ],
   examples: [
+    { cmd: 'bullswarm workflow', note: 'open the human workflow home: runs, live preview, timeline, agents, and activity' },
     { cmd: 'bullswarm workflow goal "Audit this repository for TODOs" --cwd .', note: 'autonomous goal, launched independently' },
     { cmd: 'bullswarm workflow runs --all --since 7d', note: 'list every run started in the last week' },
   ],
@@ -681,8 +685,8 @@ const workflowInspectText = rich({
 
 const workflowTuiText = rich({
   usage: 'bullswarm workflow tui [<runId>] [--json] [--all] [--show <runId>] [--cancel <runId>]',
-  purpose: 'Open the interactive full-screen workflow timeline with Workflow Planner, phase, '
-    + 'live-agent, and technical drill-down views for ongoing and historical runs, or print a '
+  purpose: 'Open the interactive full-screen workflow dashboard with an active/recent run list, '
+    + 'selected-run preview, Workflow Planner, phase, live-agent, and technical drill-down views, or print a '
     + 'static/JSON snapshot for a non-interactive caller.',
   args: [{ name: '[<runId>]', desc: 'shortId or runId to open directly in detail view; omit to see the run picker' }],
   options: [
@@ -699,7 +703,7 @@ const workflowTuiText = rich({
     'below 100 columns the timeline remains full-width; press t to toggle Timeline and Phases, then Enter/Esc to drill into agents and activity',
   ],
   examples: [
-    { cmd: 'bullswarm workflow tui', note: 'interactive run picker' },
+    { cmd: 'bullswarm workflow tui', note: 'compatibility alias for the bare workflow dashboard' },
     { cmd: 'bullswarm workflow tui --json --all' },
   ],
   next: 'bullswarm workflow watch <runId> for a low-noise non-interactive follow, or bullswarm workflow approval approve <runId> if it is waiting on a decision gate.',

package/src/workflow/cli.js

@@ -81,11 +81,18 @@ function discover() {
   return found;
 }
 
-export async function cmdWorkflow(args) {
-  reconcileInterruptedRuns(BULLSWARM_DIR());
+export async function cmdWorkflow(args, {
+  bullswarmDir = BULLSWARM_DIR(), input = process.stdin, output = process.stdout,
+} = {}) {
+  reconcileInterruptedRuns(bullswarmDir);
   const [sub, ...rest] = args;
   const opts = parseFlags(rest);
 
+  if (!sub && input.isTTY && output.isTTY) {
+    try { return await runDashboard(bullswarmDir, { input, output }); }
+    catch (err) { console.error(`✗ ${err.message}`); return 1; }
+  }
+
   switch (sub) {
     case 'goal':
       return wfGoal(opts);
@@ -107,7 +114,7 @@ export async function cmdWorkflow(args) {
       try {
         if (opts.json || opts.cancel || opts.show || opts.all) {
           const token = opts.rest[0] ?? opts.show;
-          const result = dashboardJson(BULLSWARM_DIR(), {
+          const result = dashboardJson(bullswarmDir, {
             all: opts.all,
             token,
             cancel: opts.cancel,
@@ -115,7 +122,7 @@ export async function cmdWorkflow(args) {
           console.log(JSON.stringify(result, null, 2));
           return 0;
         }
-        return await runDashboard(BULLSWARM_DIR(), { token: opts.rest[0] ?? null });
+        return await runDashboard(bullswarmDir, { token: opts.rest[0] ?? null, input, output });
       }
       catch (err) { console.error(`✗ ${err.message}`); return 1; }
     case 'events':

package/src/workflow/dashboard.js

@@ -58,10 +58,14 @@ export function requestCancel(bullswarmDir, token) {
   return { ...resolved, state, alreadyFinished: false };
 }
 
-export function dashboardRows(bullswarmDir) {
+export function dashboardRows(bullswarmDir, { all = false } = {}) {
   return listRuns(bullswarmDir)
-    .filter((r) => r.ongoing)
-    .sort((a, b) => String(b.state?.startedAt ?? '').localeCompare(String(a.state?.startedAt ?? '')))
+    .filter((r) => all || r.ongoing)
+    .sort((a, b) => {
+      if (a.ongoing !== b.ongoing) return a.ongoing ? -1 : 1;
+      return String(b.state?.startedAt ?? b.report?.startedAt ?? '')
+        .localeCompare(String(a.state?.startedAt ?? a.report?.startedAt ?? ''));
+    })
     .map((r) => {
       const state = r.state ?? {};
       const steps = state.steps ?? [];
@@ -83,23 +87,154 @@ export function dashboardRows(bullswarmDir) {
     });
 }
 
-export function renderDashboard({ rows, selected = 0, message = null } = {}) {
-  const out = [`${ESC}2J${ESC}H`, ' bullswarm · workflows', ''];
-  if (!rows?.length) {
-    out.push(' No ongoing workflows.', '', ' Press r to refresh · q to quit');
-    return out.join('\n');
+export function renderDashboard({
+  rows, allRows = rows, selected = 0, message = null, width = 120, height = 36,
+  filter = 'active', query = '', filterEditing = false, spinnerFrame = 0,
+  previewRow = null,
+} = {}) {
+  width = Math.max(20, Number(width) || 120);
+  height = Math.max(12, Number(height) || 36);
+  rows = rows ?? [];
+  allRows = allRows ?? rows;
+  const narrow = width < 100;
+  const active = allRows.filter((row) => row.ongoing).length;
+  const waiting = allRows.filter((row) => isWaitingWorkflow(row.state)).length;
+  const historical = Math.max(0, allRows.length - active);
+  const selectedRow = previewRow ?? rows[selected] ?? null;
+  const summary = `${active} active · ${waiting} waiting · ${historical} recent`;
+  const header = [
+    truncate(` bullswarm workflows · ${summary}`, width),
+    selectedRow
+      ? truncate(` ${selectedRow.shortId ?? '------'} · ${workflowRunLabel(selectedRow)}`, width)
+      : truncate(` ${filter === 'active' ? 'Active workflows' : 'All workflows'}`, width),
+  ];
+  const footer = filterEditing
+    ? truncate(` Filter: ${query}█ · Enter apply · Esc clear`, width)
+    : narrow
+      ? truncate(' ↑/↓ select · Enter open · / filter · a active/all · q exit', width)
+      : truncate(' ↑/↓ select · Enter open · / filter · a active/all · r refresh · c stop · q exit', width);
+  const messageLine = message
+    ? truncate(` ${message}`, width)
+    : truncate(` Runs · ${filter}${query ? ` · filter “${query}”` : ''} · workflow continues after dashboard exit`, width);
+  const bodyHeight = Math.max(6, height - header.length - 2);
+  const listLines = dashboardRunLines(rows, selected, narrow, width);
+
+  let body;
+  if (narrow) {
+    body = renderPanel(`Runs · ${filter}`, listWindow(listLines, selected, bodyHeight - 2, true), width, bodyHeight);
+  } else {
+    const leftWidth = Math.max(32, Math.min(46, Math.floor(width * 0.36)));
+    const rightWidth = width - leftWidth;
+    const left = renderPanel(
+      `Runs · ${filter}`,
+      listWindow(listLines, selected, bodyHeight - 2, false),
+      leftWidth,
+      bodyHeight,
+    );
+    let right;
+    if (selectedRow?.state) {
+      const model = workflowPanelModel(selectedRow);
+      right = renderWorkflowOverviewPanel(model, rightWidth, bodyHeight, spinnerFrame, 0);
+    } else {
+      const hint = allRows.length && filter === 'active'
+        ? ['No active workflows.', '', 'Press a to browse recent runs.']
+        : ['No workflow runs yet.', '', 'Start one with:', 'bullswarm workflow goal "…"'];
+      right = renderPanel('Selected workflow', hint, rightWidth, bodyHeight);
+    }
+    body = joinPanels(left, right);
   }
-  out.push(' Select a run with j/k or arrows · Enter details · c stop · r refresh · q quit', '');
-  out.push('    ID       WORKFLOW                 STATUS     PHASE                 PROGRESS');
-  out.push('    ' + '-'.repeat(82));
-  rows.forEach((r, i) => {
-    const mark = i === selected ? '>' : ' ';
-    const progress = `${r.stepsOk}/${r.stepsTotal} steps` + (r.fanout.total ? ` · ${r.fanout.ok}/${r.fanout.total} items` : '');
-    out.push(`${mark}   ${(r.shortId ?? '------').padEnd(8)} ${(r.state?.workflow ?? '?').slice(0, 24).padEnd(24)} ${(r.status ?? 'running').padEnd(10)} ${(r.phase ?? 'starting').slice(0, 20).padEnd(20)} ${progress}`);
+  return [`${ESC}2J${ESC}H`, ...header, ...body, messageLine, footer].join('\n');
+}
+
+function isWaitingWorkflow(state) {
+  const value = String(state?.status ?? state?.stage ?? '').toLowerCase();
+  return value.includes('waiting') || value === 'paused';
+}
+
+function workflowRunLabel(row) {
+  const state = row?.state ?? {};
+  const workflow = String(state.workflow ?? '').trim();
+  if (workflow && !workflow.startsWith('goal-')) return workflow;
+  return String(state.intent?.goal ?? state.intent?.description ?? workflow ?? row?.runId ?? 'workflow')
+    .split('\n')[0]
+    .trim();
+}
+
+function workflowConcernCount(row) {
+  const concerns = row?.state?.outcome?.concerns ?? row?.report?.concerns ?? [];
+  return Array.isArray(concerns) ? concerns.length : 0;
+}
+
+function dashboardRunLines(rows, selected, narrow, width) {
+  if (!rows.length) return [{ selected: false, lines: ['No workflows in this view.'] }];
+  return rows.map((row, index) => {
+    const state = row.state ?? {};
+    const selectedRow = index === selected;
+    const icon = statusIcon(row.ongoing ? (state.status ?? 'running') : (state.status ?? 'completed'));
+    const elapsed = durationText(state.startedAt ?? row.report?.startedAt, state.finishedAt ?? row.report?.finishedAt);
+    const workerAttempts = (state.attempts ?? []).filter((attempt) =>
+      attempt.actionId !== state.orchestration?.actionId && attempt.actionId !== 'orchestrator');
+    const finished = workerAttempts.filter((attempt) => TERMINAL_ACTIONS.has(attempt.status)).length;
+    let progress = workerAttempts.length
+      ? `${finished}/${workerAttempts.length} workers`
+      : `${row.stepsOk ?? 0}/${row.stepsTotal ?? 0} actions`;
+    if (row.fanout?.total) progress += ` · ${row.fanout.ok}/${row.fanout.total} items`;
+    const concerns = workflowConcernCount(row);
+    const status = concerns ? `${concerns} concern${concerns === 1 ? '' : 's'}` : humanWorkflowStatus(state.status, row.ongoing);
+    const name = workflowRunLabel(row);
+    const phase = humanPhaseName(row.phase ?? state.stage ?? 'starting');
+    if (narrow) {
+      const inner = Math.max(1, width - 4);
+      return {
+        selected: selectedRow,
+        lines: [
+          selectLine(`${icon} ${row.shortId ?? '------'} · ${name}`, selectedRow, true, inner),
+          selectLine(`  ${progress} · ${elapsed}`, selectedRow, false, inner),
+          selectLine(`  ${phase} · ${status}`, selectedRow, false, inner),
+          '',
+        ],
+      };
+    }
+    return {
+      selected: selectedRow,
+      lines: [
+        selectLine(`${icon} ${row.shortId ?? '------'} · ${name}`, selectedRow, true, 44),
+        selectLine(`  ${progress} · ${elapsed} · ${status}`, selectedRow, false, 44),
+        '',
+      ],
+    };
+  });
+}
+
+function listWindow(groups, selected, height, narrow) {
+  const linesPerGroup = narrow ? 4 : 3;
+  const capacity = Math.max(1, Math.floor(height / linesPerGroup));
+  const start = clamp(selected - Math.floor(capacity / 2), 0, Math.max(0, groups.length - capacity));
+  return groups.slice(start, start + capacity).flatMap((group) => group.lines).slice(0, height);
+}
+
+function humanWorkflowStatus(status, ongoing) {
+  const value = String(status ?? '').replaceAll('_', ' ');
+  if (ongoing && (!value || value === 'running')) return 'running';
+  if (value === 'completed') return 'finished';
+  if (value === 'completed with concerns') return 'finished with concerns';
+  return value || (ongoing ? 'running' : 'finished');
+}
+
+function humanPhaseName(value) {
+  return String(value ?? 'starting').replaceAll('-', ' ').replaceAll(':', ' › ');
+}
+
+function filterDashboardRows(rows, filter, query) {
+  const needle = String(query ?? '').trim().toLowerCase();
+  return (rows ?? []).filter((row) => {
+    if (filter === 'active' && !row.ongoing) return false;
+    if (!needle) return true;
+    const state = row.state ?? {};
+    return [row.shortId, row.runId, state.workflow, state.intent?.goal, row.phase, state.status]
+      .filter(Boolean)
+      .some((value) => String(value).toLowerCase().includes(needle));
   });
-  if (message) out.push('', ` ${message}`);
-  out.push('', ' Press Enter for details · q to quit');
-  return out.join('\n');
 }
 
 export function renderDetails(row, { interactive = true } = {}) {
@@ -1268,7 +1403,8 @@ function detailRow(bullswarmDir, token) {
 }
 
 export async function runDashboard(bullswarmDir, {
-  input = process.stdin, output = process.stdout, refreshMs = 1000, token = null,
+  input = process.stdin, output = process.stdout, refreshMs = 1000,
+  spinnerMs = 400, token = null,
 } = {}) {
   if ((!input.isTTY || !output.isTTY) && !token) throw new Error('workflow dashboard requires a TTY, or pass a run ID for a static text tree');
   if ((!input.isTTY || !output.isTTY) && token) {
@@ -1280,8 +1416,13 @@ export async function runDashboard(bullswarmDir, {
   let detail = Boolean(token);
   let message = null;
   let lastGoodRow = null;
-  let rows = dashboardRows(bullswarmDir);
+  let dashboardFilter = 'active';
+  let query = '';
+  let filterEditing = false;
+  let allRows = dashboardRows(bullswarmDir, { all: true });
+  let rows = filterDashboardRows(allRows, dashboardFilter, query);
   let selectedRunId = token ? detailRow(bullswarmDir, token).runId : (rows[selected]?.runId ?? null);
+  let lastPaintedFrame = null;
   const ui = {
     focus: 0,
     phaseIndex: null,
@@ -1297,6 +1438,25 @@ export async function runDashboard(bullswarmDir, {
     mobileTimeline: true,
     spinnerFrame: 0,
   };
+  // Clearing the entire alternate screen for every spinner frame produces a
+  // visible blank flash on slower terminals, especially mobile SSH sessions.
+  // Enter/clear the alternate screen once, then repaint each row in place.
+  // Padding to the terminal height also removes remnants when switching from
+  // a taller detail view to a shorter picker view.
+  const writeFrame = (text) => {
+    const clearPrefix = `${ESC}2J${ESC}H`;
+    let source = String(text ?? '').startsWith(clearPrefix)
+      ? String(text ?? '').slice(clearPrefix.length)
+      : String(text ?? '');
+    if (source.startsWith('\n')) source = source.slice(1);
+    const height = Math.max(1, Number(output.rows) || source.split('\n').length);
+    const lines = source.split('\n').slice(0, height);
+    while (lines.length < height) lines.push('');
+    const frame = `${ESC}H${lines.map((line) => `${line}${ESC}K`).join('\n')}`;
+    if (frame === lastPaintedFrame) return;
+    lastPaintedFrame = frame;
+    output.write(frame);
+  };
   const paintUnsafe = () => {
     if (selected >= rows.length) selected = Math.max(0, rows.length - 1);
     if (detail && selectedRunId) {
@@ -1311,7 +1471,7 @@ export async function runDashboard(bullswarmDir, {
       });
       ui.phaseIndex = model.phaseIndex;
       ui.agentIndex = model.agentIndex;
-      output.write(renderWorkflowTui(row, {
+      writeFrame(renderWorkflowTui(row, {
         width: output.columns,
         height: output.rows,
         ...ui,
@@ -1319,7 +1479,27 @@ export async function runDashboard(bullswarmDir, {
       }));
       return;
     }
-    output.write(renderDashboard({ rows, selected, message }));
+    let previewRow = null;
+    if (selectedRunId) {
+      const fresh = detailRow(bullswarmDir, selectedRunId);
+      previewRow = (fresh.state || lastGoodRow?.runId !== fresh.runId) ? fresh : lastGoodRow;
+      if (previewRow === fresh) lastGoodRow = fresh;
+      const selectedListRow = rows[selected];
+      if (previewRow && selectedListRow) previewRow.ongoing = selectedListRow.ongoing;
+    }
+    writeFrame(renderDashboard({
+      rows,
+      allRows,
+      selected,
+      message,
+      width: output.columns,
+      height: output.rows,
+      filter: dashboardFilter,
+      query,
+      filterEditing,
+      spinnerFrame: ui.spinnerFrame,
+      previewRow,
+    }));
   };
   // A render error must never kill the TUI or strand the terminal in
   // alt-screen raw mode (crash observed 2026-08-29 at detailRow via the
@@ -1327,25 +1507,35 @@ export async function runDashboard(bullswarmDir, {
   const paint = () => {
     try { paintUnsafe(); } catch (err) {
       message = `display error: ${err.message}`;
-      try { output.write(renderDashboard({ rows, selected, message })); } catch { /* keep the loop alive */ }
+      try {
+        writeFrame(renderDashboard({
+          rows, allRows, selected, message, width: output.columns, height: output.rows,
+          filter: dashboardFilter, query, filterEditing, spinnerFrame: ui.spinnerFrame,
+        }));
+      } catch { /* keep the loop alive */ }
     }
   };
   const refresh = () => {
     try {
-      rows = dashboardRows(bullswarmDir);
+      const previousRunId = selectedRunId;
+      allRows = dashboardRows(bullswarmDir, { all: true });
+      rows = filterDashboardRows(allRows, dashboardFilter, query);
+      const preserved = rows.findIndex((row) => row.runId === previousRunId);
+      if (preserved >= 0) selected = preserved;
+      else selected = clamp(selected, 0, Math.max(0, rows.length - 1));
     } catch (err) { message = `display error: ${err.message}`; }
-    if (!selectedRunId) selectedRunId = rows[selected]?.runId ?? null;
+    selectedRunId = rows[selected]?.runId ?? null;
     paint();
   };
   input.setRawMode?.(true);
   input.resume();
-  output.write(`${ESC}?1049h${ESC}?25l`);
+  output.write(`${ESC}?1049h${ESC}?25l${ESC}2J${ESC}H`);
   paint();
   const timer = setInterval(refresh, refreshMs);
   const spinnerTimer = setInterval(() => {
     ui.spinnerFrame = (ui.spinnerFrame + 1) % SPINNER_FRAMES.length;
-    if (detail) paint();
-  }, 160);
+    if (detail || rows[selected]?.ongoing) paint();
+  }, Math.max(50, Number(spinnerMs) || 400));
   return new Promise((resolve) => {
     const finish = () => {
       clearInterval(timer);
@@ -1413,6 +1603,28 @@ export async function runDashboard(bullswarmDir, {
     };
     const onDataUnsafe = (buf) => {
       const key = String(buf);
+      if (filterEditing) {
+        if (key === '\r' || key === '\n') {
+          filterEditing = false;
+          message = query ? `Showing workflows matching “${query}”.` : null;
+          return refresh();
+        }
+        if (key === '\u001b' || key === '\u0003') {
+          filterEditing = false;
+          query = '';
+          message = null;
+          return refresh();
+        }
+        if (key === '\u007f' || key === '\b') {
+          query = query.slice(0, -1);
+          return refresh();
+        }
+        if (/^[ -~]+$/.test(key)) {
+          query += key;
+          return refresh();
+        }
+        return;
+      }
       if (ui.confirmCancel) {
         if (key === 'y' || key === 'Y') return requestSelectedCancel();
         if (key === 'n' || key === 'N' || key === '\u001b' || key === '\u0003') {
@@ -1424,6 +1636,16 @@ export async function runDashboard(bullswarmDir, {
       }
       if (key === 'q' || key === '\u0003') return finish();
       if (key === 'r') { message = null; return refresh(); }
+      if (!detail && key === '/') {
+        filterEditing = true;
+        message = null;
+        return paint();
+      }
+      if (!detail && key === 'a') {
+        dashboardFilter = dashboardFilter === 'active' ? 'all' : 'active';
+        message = dashboardFilter === 'active' ? 'Showing active workflows.' : 'Showing active and recent workflows.';
+        return refresh();
+      }
       if (key === '\u001b' || key === 'b') {
         if (ui.orchestratorDetail) {
           ui.orchestratorDetail = false;
@@ -1486,6 +1708,12 @@ export async function runDashboard(bullswarmDir, {
       if (key === '\r' || key === '\n') {
         if (!detail) {
           selectedRunId = rows[selected]?.runId ?? selectedRunId;
+          if (!selectedRunId) {
+            message = dashboardFilter === 'active'
+              ? 'No active workflow selected · press a to browse recent runs.'
+              : 'No workflow selected.';
+            return paint();
+          }
           detail = true;
           ui.followActivePhase = true;
           ui.followActiveAgent = true;