bullswarm 0.1.4

package/src/lib/state.js

@@ -0,0 +1,105 @@
+// bullswarm state — one JSON file at ~/.bullswarm/state.json.
+//
+// Doctrine:
+//   S1. Quarantine always carries a re-probe deadline; a recovered pool
+//       returns to service AUTOMATICALLY (fixes the /offload gap where a
+//       pool benched 30 minutes stayed benched while it had recovered).
+//   S2. Incumbency per lane persists so picks don't flap between runs.
+//   S3. Every run appends to the decision log — routing telemetry is the
+//       substrate for burn-rate learning later.
+//   S4. Recursion depth is owned by the CORE: the guard counter lives in
+//       state, incremented by env var handshake, never trusted from args.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const DEFAULT_STATE = {
+  version: 1,
+  pools: {},        // name -> {enabled, meter:{type,windowStart?,usedPct?,declaredBy}, quarantine:{until,reason}|null}
+  incumbents: {},   // lane -> poolName
+  decisionLog: [],  // {ts, lane, picked, keepOnClaude, ok, why, wallSec}
+  config: {
+    depthLimit: 2,
+    callerName: 'claude',
+  },
+};
+
+export function loadState(bullswarmDir) {
+  const p = join(bullswarmDir, 'state.json');
+  if (!existsSync(p)) return structuredClone(DEFAULT_STATE);
+  try {
+    const raw = JSON.parse(readFileSync(p, 'utf8'));
+    return {
+      ...structuredClone(DEFAULT_STATE),
+      ...raw,
+      config: { ...DEFAULT_STATE.config, ...(raw.config ?? {}) },
+    };
+  } catch {
+    return structuredClone(DEFAULT_STATE);
+  }
+}
+
+export function saveState(bullswarmDir, state) {
+  mkdirSync(bullswarmDir, { recursive: true });
+  writeFileSync(
+    join(bullswarmDir, 'state.json'),
+    `${JSON.stringify(state, null, 2)}\n`,
+  );
+}
+
+// --- quarantine -----------------------------------------------------------
+
+export function quarantinePool(state, poolName, reason, now = Date.now()) {
+  // Re-probe window: 10 minutes by default (not 30) with automatic release.
+  const until = now + 10 * 60_000;
+  state.pools[poolName] ??= {};
+  state.pools[poolName].quarantine = { until, reason };
+  return until;
+}
+
+export function releaseIfProbeDue(state, poolName, now = Date.now()) {
+  const q = state.pools[poolName]?.quarantine;
+  if (!q) return true;
+  if (now >= q.until) {
+    delete state.pools[poolName].quarantine;
+    return true; // automatic return to service
+  }
+  return false;
+}
+
+export function sweepQuarantines(state, now = Date.now()) {
+  const released = [];
+  for (const name of Object.keys(state.pools)) {
+    if (state.pools[name].quarantine && releaseIfProbeDue(state, name, now)) {
+      released.push(name);
+    }
+  }
+  return released;
+}
+
+// --- recursion ------------------------------------------------------------
+
+export const DEPTH_ENV = 'BULLSWARM_DEPTH';
+
+export function currentDepth(env = process.env) {
+  const n = Number.parseInt(env[DEPTH_ENV] ?? '0', 10);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+
+/**
+ * Throws when a delegate would exceed the configured depth limit.
+ * The limit lives in core config — callers cannot widen it via args.
+ */
+export function assertDepthAllowed(state, env = process.env) {
+  const depth = currentDepth(env);
+  if (depth >= (state.config.depthLimit ?? 2)) {
+    throw new Error(
+      `recursion guard: delegate chain already at depth ${depth} ` +
+      `(limit ${state.config.depthLimit}); offload refused`,
+    );
+  }
+}
+
+export function childDepthEnv(env = process.env) {
+  return { ...env, [DEPTH_ENV]: String(currentDepth(env) + 1) };
+}

package/src/lib/verify.js

@@ -0,0 +1,126 @@
+// bullswarm verify gate — judge by CONTENT, not exit code.
+//
+// Doctrine encoded here (each rule earned the hard way):
+//   V1. Exit code alone decides nothing in either direction.
+//   V2. A confident statement of INTENT with no work behind it is a no-op,
+//       not a result. An output that merely OPENS with an announcement is
+//       judged on its remainder; an output made ONLY of announcements is a
+//       no-op regardless of its byte length.
+//   V3. Failure patterns (rate limits, auth errors) only count near the
+//       START of an output. A delegate WRITING ABOUT rate limits is not
+//       rate-limited. Outputs shorter than SHORT_OUTPUT_MAX are judged
+//       whole: they are short enough to be nothing but an error.
+//   V4. Sentence splitting breaks ONLY before a capital letter, digit, or
+//       markdown starter after terminal punctuation + whitespace. Tokens
+//       like ".d.ts", "Node.js", "log.ts" never shred.
+
+export const FAILURE_SCAN_HEAD = 400; // chars scanned for failure patterns
+export const SHORT_OUTPUT_MAX = 600;  // below this, whole output is the head
+export const MIN_SUBSTANCE_CHARS = 80;
+
+// Patterns indicating the DELEGATE ITSELF failed (not that it discusses
+// failure). Case-insensitive against the head slice.
+export const FAILURE_PATTERNS = [
+  /^rate limit/i,
+  /^exceeded.*quota/i,
+  /^\s*(error|fatal|exception)\b/i,
+  /unauthorized/i,
+  /authentication failed/i,
+  /invalid api key/i,
+  /api key expired/i,
+  /permission denied/i,
+  /command not found/,
+  /no such file or directory/,
+  /econnrefused/i,
+  /etimedout/i,
+  /socket hang up/i,
+  /too many requests/i,
+  /service unavailable/i,
+  /bad gateway/i,
+];
+
+// First-person future = intent, not work.
+const INTENT_RE =
+  /\b(?:i'?ll|i will|i'?m going to|i am going to|i plan to|i intend to|let me)\b/i;
+
+// After terminal punctuation, a new sentence starts only at a capital,
+// digit, quote, bracket, or markdown starter — nothing else.
+const NEXT_SENTENCE_START = /[A-Z0-9"'`(#[*\->]/;
+
+/** Split text into sentences using the V4 boundary rule. */
+export function splitSentences(text) {
+  const sentences = [];
+  let start = 0;
+  let i = 0;
+  const push = (end) => {
+    const s = text.slice(start, end).trim();
+    if (s.length > 0) sentences.push(s);
+  };
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '.' || ch === '!' || ch === '?') {
+      let j = i;
+      while (j + 1 < text.length && /[.!?]/.test(text[j + 1])) j++;
+      const k = j + 1;
+      if (k >= text.length) {
+        push(text.length);
+        return sentences;
+      }
+      if (/\s/.test(text[k])) {
+        let m = k;
+        while (m < text.length && /\s/.test(text[m])) m++;
+        if (
+          m >= text.length ||
+          NEXT_SENTENCE_START.test(text[m])
+        ) {
+          push(m);
+          start = m;
+          i = m;
+          continue;
+        }
+      }
+      i = j + 1;
+      continue;
+    }
+    i++;
+  }
+  push(text.length);
+  return sentences;
+}
+
+function scanForFailure(text) {
+  const slice =
+    text.length < SHORT_OUTPUT_MAX ? text : text.slice(0, FAILURE_SCAN_HEAD);
+  return FAILURE_PATTERNS.some((re) => re.test(slice));
+}
+
+/**
+ * Work = non-intent sentences carrying real substance after announcements
+ * are stripped. Byte length alone proves nothing (a 477-byte pure
+ * announcement is still a no-op).
+ */
+export function looksLikeWork(text) {
+  const sentences = splitSentences(text);
+  const substance = sentences.filter((s) => !INTENT_RE.test(s)).join(' ');
+  return substance.trim().length >= MIN_SUBSTANCE_CHARS;
+}
+
+/**
+ * Judge delegate output content.
+ * @param {string} text   full delegate output
+ * @param {object} opts   { exitCode, expectWork=true }
+ * @returns {{verdict:'pass'|'fail'|'intent_only', why:string}}
+ */
+export function judgeContent(text, { exitCode, expectWork = true } = {}) {
+  void exitCode; // content-only judgment; exit handled by the caller
+  if (typeof text !== 'string' || text.trim().length === 0) {
+    return { verdict: 'fail', why: 'empty output' };
+  }
+  if (scanForFailure(text)) {
+    return { verdict: 'fail', why: 'failure pattern at output head' };
+  }
+  if (expectWork && !looksLikeWork(text)) {
+    return { verdict: 'intent_only', why: 'announcement without substance' };
+  }
+  return { verdict: 'pass', why: 'content passed all gates' };
+}

package/src/lib/version.js

@@ -0,0 +1,17 @@
+// bullswarm version — single source of truth is package.json.
+// Resolved relative to this module so it works identically from a repo
+// checkout and a global npm install.
+
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_PATH = join(resolve(dirname(fileURLToPath(import.meta.url)), '../..'), 'package.json');
+
+let cached;
+
+export function getVersion() {
+  if (cached) return cached;
+  cached = JSON.parse(readFileSync(PKG_PATH, 'utf8')).version;
+  return cached;
+}

package/src/lib/watch.js

@@ -0,0 +1,167 @@
+// bullswarm watch — spawn a delegate directly, capture everything, judge.
+//
+// Doctrine:
+//   W1. Spawn the binary DIRECTLY (no shell) so no pipeline can swallow a
+//       real non-zero exit.
+//   W2. PWD quirk: connectors declaring cwdMode "pwd" get env.PWD set to
+//       the target dir AND are spawned with cwd = target dir. Otherwise
+//       they silently analyse the WRONG repository and exit 0.
+//   W3. Timeout kills the process tree; partial output is still judged.
+//   W4. A non-zero exit is never a success — but when content verification
+//       passes anyway, report contentUsableDespiteExit instead of
+//       discarding completed work.
+
+import { spawn } from 'node:child_process';
+import { writeFileSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { judgeContent } from './verify.js';
+
+const BULLSWARM_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+export function substituteArgv(cmdTemplate, { taskFile, cwd }) {
+  return cmdTemplate.map((a) =>
+    a
+      .replaceAll('{taskFile}', taskFile)
+      .replaceAll('{bullswarmDir}', BULLSWARM_DIR)
+      .replaceAll('{cwd}', cwd),
+  );
+}
+
+/**
+ * Run one delegate and return the raw observation.
+ * @returns Promise<{exitCode, signal, stdout, stderr, timedOut}>
+ */
+export function runDelegate(connector, taskFile, targetDir, opts = {}) {
+  const timeoutMs = (opts.timeoutSec ?? connector.timeoutSec ?? 900) * 1000;
+  const argv = substituteArgv(connector.spawn.cmd, {
+    taskFile,
+    cwd: resolve(targetDir),
+  });
+  const usePwdMode = connector.spawn.cwdMode === 'pwd';
+  // realpath: getcwd() resolves symlinks (macOS /var -> /private/var), so an
+  // unresolved PWD would disagree with cwd and defeat wrong-repo detection.
+  const resolvedDir = realpathSync(resolve(targetDir));
+
+  return new Promise((resolvePromise) => {
+    const child = spawn(argv[0], argv.slice(1), {
+      cwd: resolvedDir,
+      // ALWAYS sync PWD to the spawned cwd (not only for declared pwd-mode
+      // connectors): an inherited stale PWD is the wrong-repo hazard.
+      env: { ...process.env, PWD: resolvedDir },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), 2000);
+    }, timeoutMs);
+
+    child.stdout.on('data', (d) => (stdout += d));
+    child.stderr.on('data', (d) => (stderr += d));
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      resolvePromise({
+        exitCode: null,
+        signal: null,
+        stdout,
+        stderr: `${stderr}\n${err.message}`,
+        timedOut,
+        spawnError: true,
+      });
+    });
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      resolvePromise({ exitCode: code, signal, stdout, stderr, timedOut });
+    });
+  });
+}
+
+function extractOutput(connector, obs) {
+  switch (connector.outputExtraction?.strategy ?? 'stdout') {
+    case 'stdout':
+      return obs.stdout || obs.stderr || '';
+    case 'stdout-tail':
+      return (obs.stdout || '').split('\n').slice(-80).join('\n') || obs.stderr;
+    default:
+      return obs.stdout || obs.stderr || '';
+  }
+}
+
+function matchAuthSignature(connector, text) {
+  const sigs = connector.authSignatures ?? [];
+  return sigs.find((s) => text.toLowerCase().includes(s.toLowerCase())) ?? null;
+}
+
+/**
+ * Watch one delegation end-to-end. Returns the standard verdict.
+ */
+export async function watchOnce(connector, taskText, targetDir, paths, opts = {}) {
+  writeFileSync(paths.taskFile, taskText);
+  const startedAt = Date.now();
+  const obs = await runDelegate(connector, paths.taskFile, targetDir, opts);
+  const wallSec = Math.round((Date.now() - startedAt) / 100) / 10;
+
+  const output = extractOutput(connector, obs);
+  writeFileSync(paths.outFile, output);
+
+  // Gate order matters:
+  //   timeout / spawn failure -> fail (nothing to trust)
+  //   auth signature anywhere in the first 2000 chars -> fail + quarantine
+  //     hint (checked BEFORE generic failure patterns so the specific cause
+  //     wins; codex-style CLIs log auth errors after banner noise, so a
+  //     fixed 400-char head misses them).
+  //   else content judge decides; exit code only modulates flags.
+  const authHit = matchAuthSignature(connector, output.slice(0, 2000));
+
+  let verdict;
+  if (obs.timedOut) {
+    verdict = { ok: false, why: `timeout after ${opts.timeoutSec ?? connector.timeoutSec}s` };
+  } else if (obs.spawnError) {
+    verdict = { ok: false, why: `spawn failed: ${obs.stderr.trim().split('\n')[0]}` };
+  } else if (authHit) {
+    verdict = { ok: false, why: `auth/throttle signature: "${authHit}"`, quarantineHint: true };
+  } else {
+    const j = judgeContent(output, { exitCode: obs.exitCode });
+    if (j.verdict === 'pass') {
+      verdict = {
+        ok: obs.exitCode === 0,
+        why: obs.exitCode === 0
+          ? 'verified'
+          : 'verified content but non-zero exit',
+      };
+    } else {
+      verdict = { ok: false, why: j.why };
+    }
+  }
+
+  const usableDespite =
+    !verdict.ok &&
+    !obs.spawnError &&
+    !obs.timedOut &&
+    !authHit &&
+    obs.exitCode !== 0 &&
+    judgeContent(output, { expectWork: true }).verdict === 'pass';
+
+  return {
+    ...verdict,
+    ok: verdict.ok,
+    keepOnClaude: false,
+    pick: { pool: connector.name, command: connector.spawn.cmd },
+    contentUsableDespiteExit: usableDespite,
+    meta: {
+      pool: connector.name,
+      exitCode: obs.exitCode,
+      signal: obs.signal,
+      timedOut: obs.timedOut,
+      wallSec,
+      outBytes: output.length,
+    },
+    outFile: paths.outFile,
+    taskFile: paths.taskFile,
+  };
+}

package/src/meters/claude.js

@@ -0,0 +1,126 @@
+// bullswarm claude meter — Anthropic OAuth usage endpoint (same data the
+// /usage slash command shows). Token lives in the macOS Keychain or
+// ~/.claude/.credentials.json; no refresh flow — Claude Code rotates it.
+
+import { execFileSync } from 'node:child_process';
+import { platform } from 'node:os';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const USAGE_ENDPOINT = 'https://api.anthropic.com/api/oauth/usage';
+const BETA_HEADER = 'oauth-2025-04-20';
+const EXPIRY_SKEW_MS = 60_000;
+
+export class ClaudeMeterError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code; // no_token | expired | http | parse | network
+  }
+}
+
+export function readOAuthCredentials() {
+  if (platform() === 'darwin') {
+    return readFromMacKeychain() ?? readFromCredentialsFile();
+  }
+  return readFromCredentialsFile();
+}
+
+function readFromMacKeychain() {
+  try {
+    const blob = execFileSync(
+      'security',
+      ['find-generic-password', '-s', 'Claude Code-credentials', '-w'],
+      { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' },
+    );
+    return extractCredentials(blob);
+  } catch {
+    return null;
+  }
+}
+
+function readFromCredentialsFile() {
+  for (const p of [
+    join(homedir(), '.claude', '.credentials.json'),
+    join(homedir(), '.config', 'claude', 'credentials.json'),
+  ]) {
+    try {
+      return extractCredentials(readFileSync(p, 'utf8'));
+    } catch {
+      /* next candidate */
+    }
+  }
+  return null;
+}
+
+export function extractCredentials(blob) {
+  try {
+    const oauth = JSON.parse(blob)?.claudeAiOauth;
+    const accessToken = typeof oauth?.accessToken === 'string' ? oauth.accessToken : null;
+    const expiresAt = typeof oauth?.expiresAt === 'number' ? oauth.expiresAt : null;
+    if (!accessToken || expiresAt === null) return null;
+    return { accessToken, expiresAt };
+  } catch {
+    return null;
+  }
+}
+
+function normalizeWindow(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  return {
+    utilization: typeof raw.utilization === 'number' ? raw.utilization : null,
+    resets_at: typeof raw.resets_at === 'string' ? raw.resets_at : null,
+  };
+}
+
+export function parseClaudeUsage(body) {
+  if (!body || typeof body !== 'object') {
+    throw new ClaudeMeterError('Claude usage response missing body', 'parse');
+  }
+  return {
+    captured_at: new Date().toISOString(),
+    pool: 'claude-code',
+    five_hour: normalizeWindow(body.five_hour) ?? { utilization: null, resets_at: null },
+    seven_day: normalizeWindow(body.seven_day) ?? { utilization: null, resets_at: null },
+    monthly: null,
+    seven_day_opus: normalizeWindow(body.seven_day_opus),
+    seven_day_sonnet: normalizeWindow(body.seven_day_sonnet),
+    plan_type: null,
+  };
+}
+
+export async function fetchClaudeUsage() {
+  const creds = readOAuthCredentials();
+  if (!creds) {
+    throw new ClaudeMeterError('No Claude Code OAuth token. Run `claude` to log in.', 'no_token');
+  }
+  if (creds.expiresAt - EXPIRY_SKEW_MS <= Date.now()) {
+    throw new ClaudeMeterError(
+      'Claude OAuth token expired; open Claude Code to refresh it.',
+      'expired',
+    );
+  }
+
+  let res;
+  try {
+    res = await fetch(USAGE_ENDPOINT, {
+      headers: {
+        Authorization: `Bearer ${creds.accessToken}`,
+        'anthropic-beta': BETA_HEADER,
+        'User-Agent': 'bullswarm',
+      },
+    });
+  } catch (err) {
+    throw new ClaudeMeterError(`Network error reaching Anthropic: ${err.message}`, 'network');
+  }
+  if (!res.ok) {
+    throw new ClaudeMeterError(`Usage endpoint returned ${res.status}`, 'http');
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch (err) {
+    throw new ClaudeMeterError(`Failed to parse usage response: ${err.message}`, 'parse');
+  }
+  return parseClaudeUsage(body);
+}