bullswarm 0.10.4 → 0.10.6

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,19 @@
 # bullswarm changelog
 
+## 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/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.6",
   "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

@@ -353,8 +353,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 +376,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);