bullswarm 0.1.4

package/src/cli.js

@@ -0,0 +1,307 @@
+// bullswarm CLI — verbs: setup (wizard), run, health, pools.
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { pickPool } from './lib/route.js';
+import { watchOnce } from './lib/watch.js';
+import {
+  loadState, saveState, quarantinePool, sweepQuarantines,
+  assertDepthAllowed, childDepthEnv,
+} from './lib/state.js';
+import { buildPools, buildPoolsLive } from './lib/config.js';
+import { getAllMeterReadings } from './meters/registry.js';
+import { judgeContent } from './lib/verify.js';
+import { getVersion } from './lib/version.js';
+import { release } from './lib/release.js';
+
+export const BULLSWARM_DIR = join(homedir(), '.bullswarm');
+
+function parseArgs(argv) {
+  const args = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      if (key === 'json') args.json = true;
+      else if (i + 1 < argv.length) args[key] = argv[++i];
+      else args[key] = true;
+    } else rest.push(argv[i]);
+  }
+  return { ...args, rest };
+}
+
+// --- pools ----------------------------------------------------------------
+
+async function cmdPools(opts) {
+  const now = Date.now();
+  const { state, pools } = await buildPoolsLive(BULLSWARM_DIR, now, {
+    force: opts.force === true,
+    getReadings: getAllMeterReadings,
+  });
+  const released = sweepQuarantines(state, now);
+  if (released.length && !opts.json) {
+    console.error(`quarantine expired, returned to service: ${released.join(', ')}`);
+  }
+  saveState(BULLSWARM_DIR, state);
+  if (opts.json) {
+    console.log(JSON.stringify({ pools }, null, 2));
+    return 0;
+  }
+  for (const p of pools) {
+    const src = p.meterSource;
+    const meter = src === 'none'
+      ? 'unmetered'
+      : `used ${p.usedPct ?? '?'}% elapsed ${p.elapsedPct ?? '?'}% [${src}]`;
+    const burst = p.burstGate ? ' BURST-GATED' : '';
+    const status = !p.enabled
+      ? 'disabled'
+      : p.quarantine
+        ? `QUARANTINED until ${new Date(p.quarantine.until).toLocaleTimeString()} (${p.quarantine.reason})`
+        : `ready${burst}`;
+    console.log(
+      `${p.name.padEnd(14)} cost=${p.costRank} lanes=${p.lanes.join('/')} ${meter} surplus=${p.pace ?? '-'} ${status}`,
+    );
+  }
+  return 0;
+}
+
+// --- run --------------------------------------------------------------------
+
+async function cmdRun(opts) {
+  const now = Date.now();
+  const lane = opts.lane;
+  const targetDir = resolve(opts['add-dir'] ?? process.cwd());
+
+  // Recursion guard FIRST — core-owned, env handshake.
+  let state = loadState(BULLSWARM_DIR);
+  try {
+    assertDepthAllowed(state);
+  } catch (err) {
+    const verdict = { ok: false, keepOnClaude: true, why: err.message };
+    console.log(JSON.stringify(verdict, null, 2));
+    return 1;
+  }
+
+  sweepQuarantines(state, now);
+
+  const { pools } = await buildPoolsLive(BULLSWARM_DIR, now, {
+    getReadings: getAllMeterReadings,
+  });
+  for (const p of pools) {
+    p.incumbent = state.incumbents?.[lane] === p.name;
+  }
+
+  // Burst gate (M3): a pool whose 5h window is >=90% used is excluded from
+  // dispatch entirely this run — it paces nothing, it's just out of burst room.
+  const gated = pools.filter((p) => p.burstGate);
+  const eligiblePools = gated.length ? pools.filter((p) => !p.burstGate) : pools;
+
+  const route = pickPool(lane, eligiblePools, {
+    callerEligible: opts['no-caller'] !== true,
+    callerName: state.config.callerName ?? 'claude',
+    now,
+  });
+  if (gated.length && route.pick) {
+    route.why += ` (burst-gated: ${gated.map((g) => g.name).join(', ')})`;
+  }
+
+  if (!route.pick && route.keepOnClaude) {
+    logDecision(state, { lane, picked: null, keepOnClaude: true, ok: null, why: route.why });
+    saveState(BULLSWARM_DIR, state);
+    emit({ ok: true, keepOnClaude: true, why: route.why, pick: { pool: null, command: null } }, opts);
+    return 0;
+  }
+  if (!route.pick) {
+    emit({ ok: false, keepOnClaude: false, why: route.why }, opts);
+    return 1;
+  }
+
+  // pick.connector is the pool VIEW (config.js buildPools entry); the real
+  // connector spec lives one level down.
+  const poolView = route.pick.connector ?? { name: route.pick.pool };
+  const connector = poolView.connector ?? poolView;
+
+  // Task text: --task-file content or stdin string.
+  const taskText = opts['task-file']
+    ? readFileSync(opts['task-file'], 'utf8')
+    : opts.rest.join(' ');
+  if (!taskText.trim()) {
+    console.error('empty task: pass --task-file or the task as arguments');
+    return 2;
+  }
+
+  const stamp = `${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+  const runDir = join(BULLSWARM_DIR, 'runs');
+  mkdirSync(runDir, { recursive: true });
+  const paths = {
+    taskFile: join(runDir, `task-${stamp}.md`),
+    outFile: join(runDir, `out-${stamp}.md`),
+  };
+
+  const verdict = await watchOnce(connector, taskText, targetDir, paths, {
+    timeoutSec: Number(opts.timeout ?? connector.timeoutSec ?? 900),
+    env: childDepthEnv(process.env),
+  });
+
+  // Persist incumbency on success; quarantine hint on auth failure.
+  if (verdict.ok) {
+    state.incumbents ??= {};
+    state.incumbents[lane] = connector.name;
+  } else if (verdict.quarantineHint) {
+    quarantinePool(state, connector.name, verdict.why, now);
+    verdict.quarantinedUntil = state.pools[connector.name]?.quarantine?.until;
+  }
+
+  logDecision(state, {
+    lane,
+    picked: connector.name,
+    keepOnClaude: false,
+    ok: verdict.ok,
+    why: verdict.why,
+    wallSec: verdict.meta?.wallSec,
+    outFile: paths.outFile,
+  });
+  saveState(BULLSWARM_DIR, state);
+
+  emit(verdict, opts);
+  return verdict.ok ? 0 : 1;
+}
+
+function logDecision(state, d) {
+  state.decisionLog ??= [];
+  state.decisionLog.push({ ts: new Date().toISOString(), ...d });
+  if (state.decisionLog.length > 500) {
+    state.decisionLog = state.decisionLog.slice(-500);
+  }
+}
+
+function emit(verdict, opts) {
+  if (opts.json) console.log(JSON.stringify(verdict, null, 2));
+  else {
+    const line = [
+      verdict.ok ? 'OK' : 'FAIL',
+      verdict.keepOnClaude ? '(keep-on-caller)' : '',
+      verdict.pick?.pool ? `[${verdict.pick.pool}]` : '',
+      verdict.why ?? '',
+    ].filter(Boolean).join(' ');
+    console.log(line);
+    if (verdict.outFile) console.log(`output: ${verdict.outFile}`);
+  }
+}
+
+// --- health -----------------------------------------------------------------
+
+function cmdHealth(opts) {
+  const state = loadState(BULLSWARM_DIR);
+  const runsDir = join(BULLSWARM_DIR, 'runs');
+  const findings = [];
+
+  // Correlate each logged decision with its saved output: the doctrine
+  // signal is "verdict said FAIL but the file re-judges OK" — that means
+  // the verify gate ate real work. Verdict-FAIL files that still re-judge
+  // pass are exactly the planted case; verdict-OK files are expected passes.
+  if (existsSync(runsDir)) {
+    const byOut = new Map(
+      (state.decisionLog ?? [])
+        .filter((d) => d.outFile)
+        .map((d) => [d.outFile, d]),
+    );
+    for (const f of readdirSync(runsDir)) {
+      if (!f.startsWith('out-')) continue;
+      const outPath = join(runsDir, f);
+      const out = readFileSync(outPath, 'utf8');
+      if (!out.trim()) continue;
+      const j = judgeContent(out);
+      const decision = byOut.get(outPath);
+      findings.push({
+        file: f,
+        savedVerdict: decision ? (decision.ok ? 'OK' : 'FAIL') : 'unlogged',
+        rejudge: j.verdict,
+        gateAteWork:
+          decision != null && decision.ok === false && j.verdict === 'pass',
+      });
+    }
+  }
+
+  const quarantined = Object.entries(state.pools ?? {})
+    .filter(([, v]) => v.quarantine)
+    .map(([k, v]) => ({ pool: k, until: v.quarantine.until, reason: v.quarantine.reason }));
+
+  const report = {
+    healthy:
+      findings.every((f) => !f.gateAteWork) &&
+      quarantined.length < 2 &&
+      (state.decisionLog?.length ?? 0) > 0,
+    gateFailures: findings.filter((f) => f.gateAteWork),
+    quarantineCluster: quarantined.length >= 2 ? quarantined : [],
+    quarantined,
+    decisionLogSize: state.decisionLog?.length ?? 0,
+  };
+  console.log(JSON.stringify(report, null, 2));
+  return report.healthy ? 0 : 1;
+}
+
+// --- setup ------------------------------------------------------------------
+
+async function cmdSetup(opts) {
+  const { runWizard } = await import('./setup.js');
+  return runWizard(BULLSWARM_DIR, opts);
+}
+
+// --- main ---------------------------------------------------------------------
+
+export async function main(argv) {
+  const [verb, ...rest] = argv;
+  const opts = parseArgs(rest);
+
+  if (!verb || verb === 'setup') {
+    if (!existsSync(join(BULLSWARM_DIR, 'state.json')) || verb === 'setup') {
+      return cmdSetup(opts);
+    }
+  }
+  switch (verb) {
+    case undefined:
+      return cmdSetup(opts); // bare bullswarm with config present still guides
+    case 'setup':
+      return cmdSetup(opts);
+    case 'run':
+      return cmdRun(opts);
+    case 'health':
+      return cmdHealth(opts);
+    case 'pools':
+      return cmdPools(opts);
+    case 'version':
+      console.log(getVersion());
+      return 0;
+    case 'release':
+      return cmdRelease(opts);
+    default:
+      console.error(
+        `unknown verb "${verb}". try: setup | run | health | pools | version | release`,
+      );
+      return 2;
+  }
+}
+
+// --- release -----------------------------------------------------------------
+
+function cmdRelease(opts) {
+  const kind = opts.rest[0];
+  if (!['patch', 'minor', 'major'].includes(kind)) {
+    console.error('usage: bullswarm release patch|minor|major [--dry-run]');
+    return 2;
+  }
+  try {
+    const r = release(kind, { dryRun: opts['dry-run'] === true });
+    const label = r.dryRun ? 'would release' : 'released';
+    console.log(`${label}: ${r.from} → ${r.to} (tag ${r.tag})`);
+    if (!r.dryRun) {
+      console.log('next: npm publish (or: npm publish --access public)');
+    }
+    return 0;
+  } catch (err) {
+    console.error(err.message);
+    return 1;
+  }
+}

package/src/lib/config.js

@@ -0,0 +1,107 @@
+// bullswarm config — merge connectors + state into runtime pool views.
+//
+// Meter precedence (doctrine M1):
+//   1. live/cached provider reading (meter reader exists)
+//   2. declared meter from state.json (labeled "declared")
+//   3. unmetered (pace 0, neutral)
+//
+// Pace source (doctrine M2): the pacing object carries elapsed% computed
+// from the provider's resets_at. Declared meters fall back to the local
+// elapsed estimate and are visibly labeled.
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadState } from './state.js';
+import { paceScore, isQuarantined } from './route.js';
+
+export function loadConnectors(bullswarmDir) {
+  const dir = join(bullswarmDir, 'connectors');
+  if (!existsSync(dir)) return {};
+  const out = {};
+  for (const f of readdirSync(dir).sort()) {
+    if (!f.endsWith('.json') || f.startsWith('_')) continue;
+    try {
+      const c = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+      out[c.name] = c;
+    } catch {
+      // broken connector files surface in `bullswarm setup` repair,
+      // never crash a run
+    }
+  }
+  return out;
+}
+
+/**
+ * Build the runtime pool list: connector + state + meter reading.
+ * Meter readings are injected by the caller (async — readers poll the
+ * network); this function stays sync so tests can build pools without I/O.
+ */
+export function buildPools(bullswarmDir, now = Date.now(), readings = {}) {
+  const state = loadState(bullswarmDir);
+  const connectors = loadConnectors(bullswarmDir);
+  const pools = [];
+  for (const [name, conn] of Object.entries(connectors)) {
+    const ps = state.pools[name] ?? {};
+    const pool = {
+      name,
+      connector: conn,
+      enabled: ps.enabled !== false,
+      costRank: conn.costRank ?? 5,
+      lanes: conn.lanes,
+      quarantine: ps.quarantine ?? null,
+      incumbentLane: Object.entries(state.incumbents ?? {})
+        .filter(([, v]) => v === name)
+        .map(([k]) => k),
+      // meter fields filled below
+      meterSource: 'none',
+      usedPct: null,
+      elapsedPct: null,
+      pace: null,
+      burstGate: false,
+    };
+    pools.push(pool);
+  }
+
+  for (const p of pools) {
+    if (!p.enabled || isQuarantined(p, now)) continue;
+    const ps = state.pools[p.name] ?? {};
+
+    const reading = readings[p.name];
+    if (reading?.pacing) {
+      // Provider-truth path (M1/M2)
+      p.meterSource = reading.source; // live | cache | stale
+      p.usedPct = reading.pacing.usedPct;
+      p.elapsedPct = reading.pacing.elapsedPct;
+      p.pace = reading.pacing.surplus; // surplus = elapsed − used
+      p.paceResetsAt = reading.pacing.resetsAt;
+      p.burstGate = reading.burstGate === true;
+    } else {
+      // Declared / unmetered fallback
+      const meter = { ...(p.connector.meter ?? {}), ...(ps.meter ?? {}) };
+      if (meter.type !== 'none' && meter.usedPct != null) {
+        p.meterSource = 'declared';
+        p.usedPct = meter.usedPct;
+        // Without resets_at, elapsed is unknown → surplus is just −used,
+        // which still ranks pools by remaining headroom honestly.
+        p.pace = -meter.usedPct;
+      } else {
+        p.meterSource = 'none';
+        p.pace = 0;
+      }
+    }
+  }
+  return { state, connectors, pools };
+}
+
+/**
+ * Async variant that fetches live readings for pools with readers.
+ */
+export async function buildPoolsLive(bullswarmDir, now = Date.now(), { force = false, getReadings } = {}) {
+  const state = loadState(bullswarmDir);
+  const connectors = loadConnectors(bullswarmDir);
+  const names = Object.keys(connectors);
+  const readings = getReadings
+    ? await getReadings(names, { force, nowMs: now })
+    : {};
+  return buildPools(bullswarmDir, now, readings);
+}

package/src/lib/release.js

@@ -0,0 +1,55 @@
+// bullswarm release — version bumping + git tagging.
+// Usage: bullswarm release patch|minor|major [--dry-run]
+//
+// Semver discipline:
+//   patch — connector flag fixes, verify-gate fixes, meter corrections
+//   minor — new verbs, new connectors, new meters, behavior additions
+//   major — verdict-contract or config-format breaking changes
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const PKG_PATH = join(REPO_ROOT, 'package.json');
+
+export function bumpVersion(version, kind) {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+  if (!m) throw new Error(`current version "${version}" is not strict semver`);
+  let [maj, min, pat] = [Number(m[1]), Number(m[2]), Number(m[3])];
+  if (kind === 'major') { maj += 1; min = 0; pat = 0; }
+  else if (kind === 'minor') { min += 1; pat = 0; }
+  else if (kind === 'patch') { pat += 1; }
+  else throw new Error(`unknown bump kind "${kind}" (use patch|minor|major)`);
+  return `${maj}.${min}.${pat}`;
+}
+
+function git(args) {
+  return execSync(`git ${args}`, { cwd: REPO_ROOT, encoding: 'utf8' }).trim();
+}
+
+export function release(kind, { dryRun = false } = {}) {
+  const pkg = JSON.parse(readFileSync(PKG_PATH, 'utf8'));
+  const prev = pkg.version;
+  const next = bumpVersion(prev, kind);
+
+  // Dirty-tree guard: a release commit must contain exactly the version change.
+  const status = git('status --porcelain');
+  if (status.trim()) {
+    throw new Error(
+      `working tree is dirty — commit first before releasing:\n${status}`,
+    );
+  }
+
+  if (dryRun) {
+    return { from: prev, to: next, tag: `v${next}`, dryRun: true };
+  }
+
+  pkg.version = next;
+  writeFileSync(PKG_PATH, `${JSON.stringify(pkg, null, 2)}\n`);
+  git('add package.json');
+  git(`commit -m "release v${next}"`);
+  git(`tag -a v${next} -m "v${next}"`);
+  return { from: prev, to: next, tag: `v${next}`, dryRun: false };
+}

package/src/lib/route.js

@@ -0,0 +1,133 @@
+// bullswarm route brain — pick a pool for a lane at runtime.
+//
+// Doctrine:
+//   R1. Lanes are WORK NATURE: analyze | build | chore. Never a hard-coded
+//       lane→pool map; pools declare capability, runtime selects.
+//   R2. Selection is by time-adjusted pace: surplus = elapsed% − used%.
+//       Most-behind (HIGHEST surplus) wins — quota piling up unspent is
+//       expiring money.
+//   R3. Incumbency margin: an incumbent pool keeps the lane unless a
+//       challenger beats its surplus by MARGIN points — no flapping.
+//   R4. Cost guard (incumbency path only): pace may promote a challenger
+//       over an incumbent only if the challenger is CHEAPER.
+//   R5. The caller wins its lane only when no eligible delegate remains —
+//       it has to WIN, not be protected.
+//   R6. A pool at 100% used is exhausted; quarantined pools are ineligible
+//       until their quarantine expires (the re-probe path).
+
+export const LANES = ['analyze', 'build', 'chore'];
+
+export const INCUMBENCY_MARGIN = 10; // surplus points a challenger must beat
+
+export function elapsedPct(meter, now = Date.now()) {
+  if (!meter || meter.type === 'none') return 0;
+  const start = meter.windowStart ?? 0;
+  const ms =
+    meter.type === '5h' ? 5 * 3600_000 :
+    meter.type === 'weekly' ? 7 * 24 * 3600_000 :
+    0;
+  if (!ms || !start) return 0;
+  return Math.min(100, ((now - start) / ms) * 100);
+}
+
+/** surplus = elapsed% − used%; higher = more quota about to expire. */
+export function paceScore(pool, now = Date.now()) {
+  const meter = pool.meter;
+  if (!meter || meter.type === 'none' || meter.usedPct == null) return 0;
+  return elapsedPct(meter, now) - meter.usedPct;
+}
+
+export function isQuarantined(pool, now = Date.now()) {
+  if (!pool.quarantine) return false;
+  if (pool.quarantine.until == null) return true;
+  return now < pool.quarantine.until;
+}
+
+export function isExhausted(pool) {
+  return pool.meter?.usedPct != null && pool.meter.usedPct >= 100;
+}
+
+/**
+ * Pick a pool for a lane.
+ * @param {string} lane   analyze | build | chore
+ * @param {Array}  pools  enabled pools: {name, costRank, lanes[], meter?,
+ *                        quarantine?, incumbent?}
+ * @param {object} [opts] { callerEligible=true, callerName='claude', now }
+ * @returns {{pick: object|null, keepOnClaude: boolean, why: string,
+ *            candidates: Array}}
+ */
+export function pickPool(lane, pools, opts = {}) {
+  const {
+    callerEligible = true,
+    callerName = 'claude',
+    now = Date.now(),
+  } = opts;
+
+  if (!LANES.includes(lane)) {
+    return {
+      pick: null,
+      keepOnClaude: false,
+      why: `unknown lane ${lane}`,
+      candidates: [],
+    };
+  }
+
+  const eligible = pools.filter(
+    (p) =>
+      p.enabled !== false &&
+      (p.lanes ?? LANES).includes(lane) &&
+      !isQuarantined(p, now) &&
+      !isExhausted(p),
+  );
+
+  const scored = eligible.map((p) => ({
+    pool: p,
+    pace: paceScore(p, now),
+  }));
+  scored.sort((a, b) => b.pace - a.pace); // most-behind first
+
+  const candidates = scored.map((e) => ({
+    pool: e.pool.name,
+    pace: Math.round(e.pace * 10) / 10,
+    costRank: e.pool.costRank ?? null,
+  }));
+
+  if (scored.length === 0) {
+    return callerEligible
+      ? {
+          pick: null,
+          keepOnClaude: true,
+          why: 'no eligible delegate pool; caller takes the lane',
+          candidates,
+        }
+      : {
+          pick: null,
+          keepOnClaude: false,
+          why: 'no eligible pool',
+          candidates,
+        };
+  }
+
+  const incumbentEntry = scored.find((e) => e.pool.incumbent === true);
+
+  let winnerEntry;
+  if (incumbentEntry) {
+    // R3+R4: challenger needs margin AND strictly lower costRank.
+    const challenger = scored.find(
+      (e) =>
+        e !== incumbentEntry &&
+        e.pace >= incumbentEntry.pace + INCUMBENCY_MARGIN &&
+        (e.pool.costRank ?? 99) < (incumbentEntry.pool.costRank ?? 99),
+    );
+    winnerEntry = challenger ?? incumbentEntry;
+  } else {
+    winnerEntry = scored[0];
+  }
+
+  return {
+    pick: { pool: winnerEntry.pool.name, connector: winnerEntry.pool },
+    keepOnClaude: false,
+    why: `most-behind capable pool (surplus ${Math.round(winnerEntry.pace * 10) / 10})`,
+    candidates,
+  };
+}