bullswarm 0.10.4 → 0.10.7

package/AGENTS.md

@@ -37,7 +37,7 @@ content. Published as `bullswarm` on npm.
 ## Development
 
 ```bash
-npm test            # 256 tests, no network needed (meters read from cache)
+npm test            # 261 tests, no network needed (meters read from cache)
 node bin/bullswarm.js doctor --json   # readiness report
 node bin/bullswarm.js workflow list   # discover workflows
 node bin/bullswarm.js workflow runs   # ongoing workflow instances

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # bullswarm changelog
 
+## 0.10.7 — clearer orchestration overview
+
+- Replaced the orchestrator trace dump with a summary-first view showing what
+  it is doing now, the latest decision and reason, the next action, worker
+  progress, and the last three semantic events.
+- Added `v` progressive disclosure for provider sessions, checkpoint prompts,
+  per-turn usage, full decisions, and artifact paths, keeping audit detail
+  available without making it the default human experience.
+
+## 0.10.6 — safe setup and boolean flags
+
+- Marked the deterministic `echo` connector as a test fixture and excluded it
+  from automatic setup, routing suggestions, connector readiness, and delegate
+  readiness. Existing installations receive a one-time migration that disables
+  an accidentally enabled fixture while preserving later explicit choices.
+- Interactive setup labels test fixtures and defaults them to disabled;
+  `doctor` now requires at least one real enabled delegate instead of treating
+  canned fixture output as offload capability.
+- Made top-level boolean flags explicit so options such as `--no-caller`,
+  `--force`, and `--dry-run` cannot swallow a following positional task.
+- Thanks to @kwunlokng for reporting both defect classes and supplying focused
+  reproductions in #1, #2, and #3.
+
 ## 0.10.4 — durable interactive workflow viewer
 
 - Added `workflow runs result <id> [--json]`, a stable

package/README.md

@@ -276,9 +276,11 @@ bullswarm workflow watch <shortId> --once        # one current/terminal snapshot
 autonomous goal its left navigation stacks a compact Orchestrator panel above
 the Phases panel; internal planner turns never appear as workers or phases.
 Select Orchestration and press Enter, or press `o`
-anywhere, to inspect the logical orchestration conversation: provider session,
-checkpoint turns and decisions, recent semantic actions, usage, prompt, and
-artifacts. Status marks are consistent throughout the tree: `○` not started,
+anywhere, to open a summary-first orchestration overview: what it is doing now,
+its latest decision in plain language, why it chose that path, what happens
+next, progress, and the last three semantic actions. Press `v` to toggle the
+technical view with provider session, every checkpoint turn, usage, prompt,
+and artifact paths. Status marks are consistent throughout the tree: `○` not started,
 an animated Braille spinner for active work, `⧖` waiting, `✓` finished, and
 `✗` failed or interrupted. The non-emoji `⧖` avoids the inconsistent cell
 width of `⌛` across terminal fonts. It watches ongoing runs from disk and supports `j`/`k` or arrow-key selection, Enter for

package/connectors/echo.json

@@ -23,6 +23,6 @@
     "pricingSource": "local deterministic fixture",
     "pricingUpdatedAt": "2026-08-27"
   }],
-  "flags": { "stealth": false },
+  "flags": { "stealth": false, "testFixture": true },
   "$comment-timeout": "No implicit wall-clock timeout; callers may opt in with --timeout or workflow step.timeoutSec"
 }

package/package.json

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

package/skill/SKILL.md

@@ -263,8 +263,10 @@ cannot be guaranteed. Restore eligibility with `strategy include-model`.
 
 In the human TUI, the autonomous orchestrator has a compact selectable panel
 stacked above the phase tree. Select it and press Enter, or press
-`o`, to inspect its durable provider session, checkpoint turns and decisions,
-recent semantic actions, usage, prompt, and artifacts. Esc returns to phases.
+`o`, to see a summary-first overview of its current role, latest decision,
+reason, next action, progress, and recent semantic activity. Press `v` for the
+durable provider session, checkpoint prompts and turns, usage, and artifact
+paths; `v` returns to the overview and Esc returns to phases.
 The shared state marks are `○` not started, animated Braille spinner active,
 `⧖` waiting, `✓` finished, and `✗` failed or interrupted.
 
@@ -353,8 +355,8 @@ work*: "In 200 words: (1) the top 3 risks, (2) cited file paths,
 You do NOT need to set up bullswarm. Every verb self-initializes:
 
 - Missing `~/.bullswarm/`? Created on first call.
-- No enabled pools? `autoSetup` enables every installed agent CLI plus
-  the deterministic `echo` pool (so offload works on a fresh machine).
+- No enabled pools? `autoSetup` enables every installed real agent CLI. The
+  deterministic `echo` connector is a test fixture and is never auto-enabled.
 - `bullswarm doctor --json` returns a readiness report; non-zero exit
   only on a real problem. The first call to `doctor` self-heals.
 
@@ -376,7 +378,7 @@ of exact commands to fix anything missing.
 ### "Audit every file in this directory"
 
 A discover-based fanout requires the discover delegate to return a bare
-JSON array in its output file. The built-in `echo` pool is a verifier
+JSON array in its output file. The built-in `echo` pool is a disabled test
 fixture and deliberately returns prose, so use a real provider for this
 variant:
 

package/src/cli.js

@@ -29,14 +29,18 @@ export function getBullswarmDir() {
 // call getBullswarmDir() so BULLSWARM_HOME is honored at invocation time.
 export const BULLSWARM_DIR = getBullswarmDir();
 
-function parseArgs(argv) {
+const BOOLEAN_FLAGS = new Set([
+  'json', 'force', 'no-caller', 'yes', 'strategy', 'integrate', 'dry-run',
+]);
+
+export function parseArgs(argv) {
   const args = {};
   const rest = [];
   for (let i = 0; i < argv.length; i++) {
     if (argv[i].startsWith('--')) {
       const eq = argv[i].indexOf('=');
       const key = argv[i].slice(2, eq > 0 ? eq : undefined);
-      if (key === 'json') args.json = true;
+      if (BOOLEAN_FLAGS.has(key)) args[key] = true;
       else if (eq > 0) args[key] = argv[i].slice(eq + 1);
       else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) args[key] = argv[++i];
       else args[key] = true;
@@ -355,12 +359,12 @@ async function cmdDoctor(opts) {
   }
 
   const discovered = discoverConnectors();
-  const found = discovered.filter((d) => d.discovered && !d.broken);
+  const found = discovered.filter((d) => d.discovered && !d.broken && !d.testFixture);
   checks.push({
     id: 'connectors',
     ok: found.length > 0,
     detail: `${found.length} agent CLI(s) found: ${found.map((d) => d.name).join(', ') || '(none)'}`,
-    fix: found.length ? null : 'install at least one agent CLI (codex, grok, opencode…) — echo pool still works',
+    fix: found.length ? null : 'install at least one agent CLI (codex, grok, opencode…)',
   });
 
   try {
@@ -369,6 +373,7 @@ async function cmdDoctor(opts) {
     });
     const live = pools.filter((p) => p.meterSource === 'live' || p.meterSource === 'cache');
     const enabled = pools.filter((p) => p.enabled);
+    const delegates = enabled.filter((p) => !p.testFixture);
     checks.push({
       id: 'meters',
       ok: enabled.length > 0,
@@ -377,9 +382,9 @@ async function cmdDoctor(opts) {
     });
     checks.push({
       id: 'offload-capable',
-      ok: enabled.some((p) => p.name !== 'echo') || enabled.length > 0,
-      detail: `enabled pools: ${enabled.map((p) => p.name).join(', ') || 'none'}`,
-      fix: null,
+      ok: delegates.length > 0,
+      detail: `enabled delegate pools: ${delegates.map((p) => p.name).join(', ') || 'none'}`,
+      fix: delegates.length ? null : 'install an agent CLI and run bullswarm setup --yes',
     });
   } catch (err) {
     checks.push({ id: 'meters', ok: false, detail: err.message, fix: 'check network / re-run' });

package/src/lib/config.js

@@ -45,7 +45,8 @@ export function buildPools(bullswarmDir, now = Date.now(), readings = {}) {
     const pool = {
       name,
       connector: conn,
-      enabled: ps.enabled !== false,
+      testFixture: conn.flags?.testFixture === true,
+      enabled: conn.flags?.testFixture === true ? ps.enabled === true : ps.enabled !== false,
       costRank: conn.costRank ?? 5,
       lanes: conn.lanes,
       capabilities: conn.capabilities ?? [],

package/src/setup.js

@@ -97,6 +97,7 @@ export function discoverConnectors() {
       meter: conn.meter?.type ?? 'none',
       costRank: conn.costRank,
       lanes: conn.lanes,
+      testFixture: conn.flags?.testFixture === true,
     });
   }
   return found;
@@ -187,6 +188,10 @@ export function upgradeConnectorMetadata(bullswarmDir) {
         installed.model = packaged.model;
         changed = true;
       }
+      if (packaged.flags?.testFixture === true && installed.flags?.testFixture !== true) {
+        installed.flags = { ...(installed.flags ?? {}), testFixture: true };
+        changed = true;
+      }
       if (installed.eventStream == null && packaged.eventStream != null) {
         installed.eventStream = packaged.eventStream;
         // Older packaged connectors used stdout extraction. Once JSONL flags
@@ -218,6 +223,34 @@ export function upgradeConnectorMetadata(bullswarmDir) {
   return upgraded;
 }
 
+// One-time safety migration for installations created before connectors could
+// identify deterministic test fixtures. Explicit choices made after this
+// migration remain respected.
+export function migrateTestFixturePools(bullswarmDir) {
+  const state = loadState(bullswarmDir);
+  state.config ??= {};
+  if (state.config.testFixturesMigrated === true) return [];
+
+  const connectorsDir = join(bullswarmDir, 'connectors');
+  const disabled = [];
+  if (existsSync(connectorsDir)) {
+    for (const file of readdirSync(connectorsDir)) {
+      if (!file.endsWith('.json') || file.startsWith('_')) continue;
+      try {
+        const connector = JSON.parse(readFileSync(join(connectorsDir, file), 'utf8'));
+        if (connector.flags?.testFixture !== true) continue;
+        state.pools ??= {};
+        state.pools[connector.name] ??= {};
+        if (state.pools[connector.name].enabled !== false) disabled.push(connector.name);
+        state.pools[connector.name].enabled = false;
+      } catch { /* connector repair owns malformed files */ }
+    }
+  }
+  state.config.testFixturesMigrated = true;
+  saveState(bullswarmDir, state);
+  return disabled;
+}
+
 // --- auto-setup ---------------------------------------------------------------
 // Zero-touch initialization: enable every discovered pool, write config,
 // never prompt. Used by `setup --yes`, by any verb on first use, and by
@@ -229,13 +262,12 @@ export function autoSetup(bullswarmDir, { reason = 'auto' } = {}) {
   const discovered = discoverConnectors();
   const repaired = repairConnectors(bullswarmDir);
 
-  const usable = discovered.filter((d) => !d.broken && d.discovered);
-  // Always include the deterministic echo pool so offloading works even on
-  // a machine with zero other agent CLIs installed.
+  const usable = discovered.filter((d) => !d.broken && d.discovered && !d.testFixture);
   const enabled = new Set(usable.map((d) => d.name));
-  enabled.add('echo');
 
   state.pools ??= {};
+  state.config ??= {};
+  state.config.testFixturesMigrated = true;
   for (const d of discovered.filter((x) => !x.broken)) {
     state.pools[d.name] ??= {};
     state.pools[d.name].enabled = enabled.has(d.name);
@@ -275,6 +307,7 @@ export function isConfigured(bullswarmDir) {
 export function ensureSetup(bullswarmDir) {
   if (isConfigured(bullswarmDir)) {
     upgradeConnectorMetadata(bullswarmDir);
+    migrateTestFixturePools(bullswarmDir);
     return null;
   }
   return autoSetup(bullswarmDir, { reason: 'first-use' });
@@ -306,7 +339,7 @@ export async function runWizard(bullswarmDir, opts = {}) {
         ? 'quota: unmetered'
         : `quota: ${d.meter} window (burn rate: learning)`;
     console.log(
-      `  ${d.name.padEnd(14)} ${d.discovered ? 'found' : 'not found'}  ${meter}`,
+      `  ${d.name.padEnd(14)} ${d.discovered ? 'found' : 'not found'}  ${meter}${d.testFixture ? '  TEST FIXTURE' : ''}`,
     );
   }
   console.log('');
@@ -314,8 +347,11 @@ export async function runWizard(bullswarmDir, opts = {}) {
   // 2. Toggle pools
   const enabled = [];
   for (const d of discovered.filter((x) => !x.broken && x.discovered)) {
-    const ans = (await rl.question(`enable ${d.name}? [Y/n] `)).trim().toLowerCase();
-    if (ans !== 'n') enabled.push(d.name);
+    const prompt = d.testFixture
+      ? `enable ${d.name} test fixture? [y/N] `
+      : `enable ${d.name}? [Y/n] `;
+    const ans = (await rl.question(prompt)).trim().toLowerCase();
+    if (d.testFixture ? (ans === 'y' || ans === 'yes') : ans !== 'n') enabled.push(d.name);
   }
 
   if (enabled.length === 0) {
@@ -332,6 +368,8 @@ export async function runWizard(bullswarmDir, opts = {}) {
   mkdirSync(join(bullswarmDir, 'connectors'), { recursive: true });
   const repaired = repairConnectors(bullswarmDir);
   state.pools ??= {};
+  state.config ??= {};
+  state.config.testFixturesMigrated = true;
   for (const d of discovered.filter((x) => !x.broken)) {
     state.pools[d.name] ??= {};
     state.pools[d.name].enabled = enabled.includes(d.name);

package/src/workflow/dashboard.js

@@ -345,7 +345,8 @@ export function workflowPanelModel(row, {
 export function renderWorkflowTui(row, {
   width = 120, height = 36, focus = 0, phaseIndex = null, agentIndex = null,
   detailScroll = 0, message = null, confirmCancel = false,
-  controlSelected = false, orchestratorDetail = false, spinnerFrame = 0,
+  controlSelected = false, orchestratorDetail = false, orchestratorVerbose = false,
+  spinnerFrame = 0,
 } = {}) {
   width = Math.max(38, Number(width) || 120);
   height = Math.max(18, Number(height) || 36);
@@ -367,10 +368,12 @@ export function renderWorkflowTui(row, {
   ];
   const footer = confirmCancel
     ? ' Stop this workflow? y confirm · n/Esc keep running'
-    : ` ↑/↓ select · Enter drill in · Esc back · o orchestrator · c stop · q detach`;
+    : orchestratorDetail
+      ? ` ↑/↓ scroll · v ${orchestratorVerbose ? 'overview' : 'technical details'} · Esc back · c stop · q detach`
+      : ` ↑/↓ select · Enter drill in · Esc back · o orchestrator · c stop · q detach`;
   const rawMessageLine = message
     ? ` ${truncate(message, width - 2)}`
-    : ` ${orchestratorDetail ? 'Orchestrator thread' : focus === 0 ? 'Phases' : focus === 1 ? 'Agents' : 'Agent activity'} · r refresh · workflow continues after detach`;
+    : ` ${orchestratorDetail ? `Orchestrator ${orchestratorVerbose ? 'technical details' : 'overview'}` : focus === 0 ? 'Phases' : focus === 1 ? 'Agents' : 'Agent activity'} · r refresh · workflow continues after detach`;
   const messageLine = truncate(rawMessageLine, width);
   const bodyHeight = Math.max(10, height - header.length - 3);
 
@@ -409,6 +412,7 @@ export function renderWorkflowTui(row, {
     model,
     Math.max(20, (orchestratorDetail ? width : rightWidth) - 4),
     spinnerFrame,
+    { verbose: orchestratorVerbose },
   );
   const detail = orchestratorDetail
     ? orchestrationLines
@@ -444,7 +448,7 @@ export function renderWorkflowTui(row, {
 
   let body;
   if (orchestratorDetail) {
-    body = renderPanel('Orchestrator thread · control plane', visibleDetail, width, bodyHeight);
+    body = renderPanel(`Orchestrator · ${orchestratorVerbose ? 'technical details' : 'overview'}`, visibleDetail, width, bodyHeight);
   } else if (narrow) {
     const mobile = focus === 0
       ? {
@@ -495,7 +499,7 @@ function joinPanels(left, right) {
   return left.map((line, index) => `${line}${right[index] ?? ''}`);
 }
 
-function orchestratorDetailLines(model, width, spinnerFrame) {
+function orchestratorDetailLines(model, width, spinnerFrame, { verbose = false } = {}) {
   const { orchestrator, state } = model;
   if (!orchestrator.autonomous) {
     return wrapLines(['This workflow has no autonomous orchestrator thread.'], width);
@@ -505,10 +509,57 @@ function orchestratorDetailLines(model, width, spinnerFrame) {
   const liveActions = active?.lastActions ?? latest?.lastActions ?? [];
   const totalActions = active?.actionCount ?? latest?.actionCount ?? liveActions.length;
   const conversations = Object.entries(state.orchestration?.conversations ?? {});
+  const decisions = state.decisions ?? [];
+  const latestDecision = decisions.at(-1);
+  const workerAttempts = (state.attempts ?? []).filter((attempt) => attempt.actionId !== orchestrator.actionId);
+  const completedWorkers = workerAttempts.filter((attempt) => TERMINAL_ACTIONS.has(attempt.status)).length;
+  const activeWorkers = Object.values(state.activeAgents ?? {})
+    .filter((agent) => agent.stepId !== orchestrator.actionId);
+  const nextActions = latestDecision?.actions?.map((action) => action.id).filter(Boolean) ?? [];
+  const stateLabel = active
+    ? 'Choosing the next smallest useful action'
+    : activeWorkers.length
+      ? `Waiting for ${activeWorkers.length} worker${activeWorkers.length === 1 ? '' : 's'} to finish`
+      : state.finishedAt
+        ? 'Workflow finished'
+        : 'Reviewing completed evidence';
   const lines = [
     `${statusIcon(active ? 'running' : latest?.status ?? orchestrator.status, spinnerFrame)} ${orchestrator.status} · ${orchestrator.pool} · ${orchestrator.model}`,
-    `Logical thread · ${orchestrator.attempts.length} checkpoint turn${orchestrator.attempts.length === 1 ? '' : 's'}`,
+    '',
+    `Now · ${stateLabel}`,
+    `Progress · ${completedWorkers}/${workerAttempts.length} worker attempts finished · ${orchestrator.attempts.length} planning checkpoint${orchestrator.attempts.length === 1 ? '' : 's'}`,
   ];
+  if (latestDecision) {
+    lines.push(`Latest decision · ${decisionLabel(latestDecision.decision)}`);
+    if (latestDecision.reason) lines.push(`Why · ${sentencePreview(latestDecision.reason)}`);
+    lines.push(`Next · ${nextActions.length ? nextActions.join(', ') : latestDecision.decision === 'complete' ? 'Return the verified result' : 'Wait for current work, then reassess'}`);
+  } else {
+    lines.push('Latest decision · Planning has not completed its first checkpoint yet');
+  }
+  if (active?.stall?.status === 'suspected_stalled') {
+    lines.push(`Attention · No new evidence for ${active.stall.silentForSec}s; the agent has not been auto-killed`);
+  }
+
+  if (!verbose) {
+    if (state.finishedAt) {
+      const verified = state.outcome?.verified === true;
+      lines.push('', `Result · ${verified ? 'Verified delivery is ready' : state.status === 'completed_with_concerns' ? 'Best useful delivery is ready with concerns' : state.status === 'blocked' ? 'No useful delivery could be completed' : 'Workflow is terminal'}`);
+      const concernCount = state.outcome?.concerns?.length ?? 0;
+      if (concernCount) lines.push(`Concerns · ${concernCount} recorded in the result envelope`);
+    }
+    lines.push('', 'Recent activity');
+    if (!liveActions.length) lines.push('· waiting for semantic action events');
+    const firstVisibleActionNumber = Math.max(1, totalActions - liveActions.length + 1);
+    liveActions.slice(-3).forEach((action, index, visible) => {
+      const number = Math.max(firstVisibleActionNumber, totalActions - visible.length + 1) + index;
+      lines.push(`#${number} ${statusIcon(action.status, spinnerFrame)} ${friendlyActionKind(action.kind)}${action.summary ? ` · ${friendlyActionSummary(action)}` : ''}`);
+    });
+    lines.push('', 'Press v for checkpoint prompts, sessions, usage, and artifact paths.');
+    return wrapLines(lines, width);
+  }
+
+  lines.push('', 'Technical thread');
+  lines.push(`Logical thread · ${orchestrator.attempts.length} checkpoint turn${orchestrator.attempts.length === 1 ? '' : 's'}`);
   for (const [pool, thread] of conversations) {
     lines.push(`Session · ${pool} · ${thread.sessionId ?? '—'}${thread.started ? ' · resumable' : ' · pending first turn'}`);
   }
@@ -551,6 +602,38 @@ function orchestratorDetailLines(model, width, spinnerFrame) {
   return wrapLines(lines, width);
 }
 
+function decisionLabel(decision) {
+  return ({
+    needs_more_work: 'Continue with bounded work',
+    complete: 'Finish and deliver',
+    stop: 'Stop with the best useful outcome',
+  })[decision] ?? String(decision ?? 'Pending');
+}
+
+function sentencePreview(value, maxChars = 420) {
+  const text = String(value ?? '').replace(/\s+/g, ' ').trim();
+  const sentences = text.match(/.*?[.!?](?:\s|$)/g)?.slice(0, 2).map((part) => part.trim()).join(' ') ?? text;
+  return truncate(sentences || text, maxChars);
+}
+
+function friendlyActionKind(kind) {
+  return ({
+    read_file: 'Read file',
+    write_file: 'Write file',
+    response: 'Response',
+    tool: 'Tool',
+    bash: 'Command',
+  })[kind] ?? String(kind ?? 'Action').replaceAll('_', ' ');
+}
+
+function friendlyActionSummary(action) {
+  const summary = String(action.summary ?? '').replace(/\s+/g, ' ').trim();
+  if (action.kind === 'response' && /workflow\.decision|"decision"|needs_more_work/.test(summary)) {
+    return 'Planner decision recorded';
+  }
+  return truncate(summary, 180);
+}
+
 function agentDetailLines(model, width, spinnerFrame) {
   const agent = model.selectedAgent;
   if (!agent) {
@@ -751,6 +834,7 @@ export async function runDashboard(bullswarmDir, {
     confirmCancel: false,
     controlSelected: false,
     orchestratorDetail: false,
+    orchestratorVerbose: false,
     spinnerFrame: 0,
   };
   const paint = () => {
@@ -866,6 +950,7 @@ export async function runDashboard(bullswarmDir, {
       if (key === '\u001b' || key === 'b') {
         if (ui.orchestratorDetail) {
           ui.orchestratorDetail = false;
+          ui.orchestratorVerbose = false;
           ui.focus = 0;
           ui.controlSelected = true;
           ui.detailScroll = 0;
@@ -891,6 +976,7 @@ export async function runDashboard(bullswarmDir, {
         const model = workflowPanelModel(row, { phaseIndex: ui.phaseIndex, agentIndex: ui.agentIndex });
         if (model.orchestrator.autonomous) {
           ui.orchestratorDetail = true;
+          ui.orchestratorVerbose = false;
           ui.controlSelected = true;
           ui.detailScroll = 0;
           message = null;
@@ -900,6 +986,12 @@ export async function runDashboard(bullswarmDir, {
       if (key === '1' && detail) { ui.focus = 0; return paint(); }
       if (key === '2' && detail) { ui.focus = 1; return paint(); }
       if (key === '3' && detail) { ui.focus = 2; return paint(); }
+      if (key === 'v' && ui.orchestratorDetail) {
+        ui.orchestratorVerbose = !ui.orchestratorVerbose;
+        ui.detailScroll = 0;
+        message = null;
+        return paint();
+      }
       if (key === '\r' || key === '\n') {
         if (!detail) {
           selectedRunId = rows[selected]?.runId ?? selectedRunId;
@@ -909,6 +1001,7 @@ export async function runDashboard(bullswarmDir, {
         } else if (ui.focus === 0) {
           if (ui.controlSelected) {
             ui.orchestratorDetail = true;
+            ui.orchestratorVerbose = false;
             ui.detailScroll = 0;
           } else ui.focus = 1;
         } else if (ui.focus === 1) {