bullswarm 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.3.0",
+  "version": "0.4.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

@@ -14,6 +14,7 @@ import { getAllMeterReadings } from './meters/registry.js';
 import { judgeContent } from './lib/verify.js';
 import { getVersion } from './lib/version.js';
 import { release } from './lib/release.js';
+import { cmdWorkflow } from './workflow/cli.js';
 
 export const BULLSWARM_DIR = join(homedir(), '.bullswarm');
 
@@ -99,7 +100,7 @@ async function cmdRun(opts) {
 
   const route = pickPool(lane, eligiblePools, {
     callerEligible: opts['no-caller'] !== true,
-    callerName: state.config.callerName ?? 'claude',
+    callerName: state.config.callerName ?? 'claude-code',
     now,
   });
   if (gated.length && route.pick) {
@@ -360,6 +361,8 @@ export async function main(argv) {
       return cmdPools(opts);
     case 'doctor':
       return cmdDoctor(opts);
+    case 'workflow':
+      return cmdWorkflow(rest);
     case 'version':
       console.log(getVersion());
       return 0;
@@ -367,7 +370,7 @@ export async function main(argv) {
       return cmdRelease(opts);
     default:
       console.error(
-        `unknown verb "${verb}". try: setup | run | health | pools | doctor | version | release`,
+        `unknown verb "${verb}". try: setup | run | health | pools | doctor | workflow | version | release`,
       );
       return 2;
   }

package/src/lib/route.js

@@ -84,7 +84,7 @@ export function isExhausted(pool) {
 export function pickPool(lane, pools, opts = {}) {
   const {
     callerEligible = true,
-    callerName = 'claude',
+    callerName = 'claude-code',
     now = Date.now(),
   } = opts;
 
@@ -158,7 +158,18 @@ export function pickPool(lane, pools, opts = {}) {
 
   // R5: the caller wins its lane only when no eligible delegate remains —
   // or when the caller's own pool entry genuinely wins on merit. Dispatching
-  // the caller to itself as a subprocess is always wrong.
+  // the caller to itself as a subprocess is always wrong — BUT only when a
+  // caller session actually exists. In workflow/batch contexts every pool is
+  // just a worker; opts.callerSession (default: callerEligible) controls it.
+  const hasCallerSession = opts.callerSession ?? callerEligible;
+  if (!hasCallerSession) {
+    return {
+      pick: { pool: winnerEntry.pool.name, connector: winnerEntry.pool },
+      keepOnClaude: false,
+      why: `most-behind capable pool (surplus ${Math.round(winnerEntry.pace * 10) / 10})`,
+      candidates,
+    };
+  }
   const isCaller =
     winnerEntry.pool.isCaller === true ||
     winnerEntry.pool.connector?.flags?.isCaller === true ||

package/src/lib/state.js

@@ -20,7 +20,7 @@ export const DEFAULT_STATE = {
   decisionLog: [],  // {ts, lane, picked, keepOnClaude, ok, why, wallSec}
   config: {
     depthLimit: 2,
-    callerName: 'claude',
+    callerName: 'claude-code',
   },
 };
 

package/src/workflow/cli.js

@@ -0,0 +1,172 @@
+// bullswarm workflow CLI — run | validate | list.
+
+import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { loadWorkflow, runWorkflow } from './runner.js';
+import { validateWorkflow, WorkflowValidationError } from './validate.js';
+import { buildPoolsLive } from '../lib/config.js';
+import { getAllMeterReadings } from '../meters/registry.js';
+import { WorkflowTui } from './tui.js';
+
+export const BULLSWARM_DIR = join(homedir(), '.bullswarm');
+
+function workflowDirs() {
+  return [
+    join(process.cwd(), 'workflows'),
+    join(BULLSWARM_DIR, 'workflows'),
+  ];
+}
+
+function discover() {
+  const found = [];
+  for (const dir of workflowDirs()) {
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir).sort()) {
+      const p = join(dir, f);
+      if (!statSync(p).isFile() || !f.endsWith('.json')) continue;
+      try {
+        const doc = JSON.parse(readFileSync(p, 'utf8'));
+        found.push({ name: doc.name ?? f.replace(/\.json$/, ''), path: p, valid: null });
+      } catch (err) {
+        found.push({ name: f.replace(/\.json$/, ''), path: p, valid: `parse error: ${err.message}` });
+      }
+    }
+  }
+  return found;
+}
+
+export async function cmdWorkflow(args) {
+  const [sub, ...rest] = args;
+  const opts = parseFlags(rest);
+
+  switch (sub) {
+    case 'run':
+      return wfRun(opts);
+    case 'validate':
+      return wfValidate(opts);
+    case 'list':
+      return wfList(opts);
+    default:
+      console.error('usage: bullswarm workflow <run|validate|list> [file|name] [--input k=v] [--resume id] [--json] [--quiet]');
+      return 2;
+  }
+}
+
+function parseFlags(argv) {
+  const out = { inputs: {}, rest: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') out.json = true;
+    else if (a === '--quiet') out.quiet = true;
+    else if (a === '--resume') out.resume = argv[++i];
+    else if (a === '--input') {
+      const kv = argv[++i] ?? '';
+      const eq = kv.indexOf('=');
+      if (eq > 0) out.inputs[kv.slice(0, eq)] = kv.slice(eq + 1);
+    } else if (a.startsWith('--')) {
+      out[a.slice(2)] = true;
+    } else out.rest.push(a);
+  }
+  return out;
+}
+
+async function wfValidate(opts) {
+  const target = opts.rest[0];
+  if (!target) {
+    console.error('usage: bullswarm workflow validate <file-or-name>');
+    return 2;
+  }
+  let doc, path;
+  try {
+    ({ doc, path } = loadWorkflow(target, workflowDirs()));
+  } catch (err) {
+    console.error(`✗ ${err.message}`);
+    return 1;
+  }
+  const poolsInfo = await livePoolNames();
+  try {
+    const r = validateWorkflow(doc, { poolNames: poolsInfo.names });
+    console.log(`✓ ${path} is valid (${doc.phases?.length ?? 0} phases)`);
+    for (const w of r.warnings) console.log(`  ⚠ ${w}`);
+    return 0;
+  } catch (err) {
+    if (err instanceof WorkflowValidationError) {
+      console.error(`✗ ${path}:`);
+      for (const issue of err.issues) console.error(`  - ${issue}`);
+      return 1;
+    }
+    throw err;
+  }
+}
+
+async function livePoolNames() {
+  try {
+    const { pools } = await buildPoolsLive(BULLSWARM_DIR, Date.now(), {
+      getReadings: getAllMeterReadings,
+    });
+    return { names: pools.map((p) => p.name), pools };
+  } catch {
+    return { names: [], pools: [] };
+  }
+}
+
+async function wfRun(opts) {
+  const target = opts.rest[0];
+  if (!target) {
+    console.error('usage: bullswarm workflow run <file-or-name> [--input k=v] [--resume runId]');
+    return 2;
+  }
+
+  let doc, path;
+  try {
+    ({ doc, path } = loadWorkflow(target, workflowDirs()));
+  } catch (err) {
+    console.error(`✗ ${err.message}`);
+    return 1;
+  }
+
+  const { names, pools } = await livePoolNames();
+  try {
+    validateWorkflow(doc, { poolNames: names });
+  } catch (err) {
+    if (err instanceof WorkflowValidationError) {
+      console.error(`✗ workflow invalid (nothing ran):`);
+      for (const issue of err.issues) console.error(`  - ${issue}`);
+      return 1;
+    }
+    throw err;
+  }
+
+  const tui = new WorkflowTui({ quiet: opts.quiet, json: opts.json });
+  const result = await runWorkflow({
+    bullswarmDir: BULLSWARM_DIR,
+    doc,
+    pools,
+    inputs: opts.inputs,
+    resumeRunId: opts.resume,
+    onEvent: (ev) => tui.handle(ev),
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(result.report, null, 2));
+  }
+  return result.report.status === 'completed' ? 0 : 1;
+}
+
+function wfList(opts) {
+  const found = discover();
+  if (opts.json) {
+    console.log(JSON.stringify({ workflows: found }, null, 2));
+    return 0;
+  }
+  if (found.length === 0) {
+    console.log(`no workflows found in: ${workflowDirs().join(', ')}`);
+    return 0;
+  }
+  for (const w of found) {
+    const mark = w.valid ? `✗ ${w.valid}` : '✓';
+    console.log(`${mark}  ${w.name.padEnd(24)} ${w.path}`);
+  }
+  return 0;
+}

package/src/workflow/runner.js

@@ -0,0 +1,195 @@
+// bullswarm workflow runner — load, validate, execute phases, report.
+//
+// Phase semantics:
+//   step onError: continue | fail (abort whole run) | skip-phase
+//   settings.stopOnPhaseFailure: abort after a phase with any failure
+// Resume: steps whose recorded verdict is ok:true are skipped (R2).
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { validateWorkflow } from './validate.js';
+import { WorkflowRuntime } from './runtime.js';
+
+export function loadWorkflow(pathOrName, searchDirs) {
+  let path = pathOrName;
+  if (!path.endsWith('.json')) {
+    const candidates = searchDirs.flatMap((d) => [
+      join(d, `${pathOrName}.json`),
+      join(d, pathOrName, 'workflow.json'),
+    ]);
+    path = candidates.find((p) => existsSync(p));
+    if (!path) {
+      throw new Error(`workflow "${pathOrName}" not found in: ${searchDirs.join(', ')}`);
+    }
+  }
+  if (!existsSync(path)) throw new Error(`workflow file not found: ${path}`);
+  return {
+    doc: JSON.parse(readFileSync(path, 'utf8')),
+    path,
+  };
+}
+
+function newRunId() {
+  return `wf-${Date.now().toString(36)}-${randomBytes(3).toString('hex')}`;
+}
+
+/**
+ * Execute a workflow.
+ * @param {object} opts
+ * @param {string} opts.bullswarmDir
+ * @param {object} opts.doc           validated workflow document
+ * @param {object} opts.pools         live pools (buildPoolsLive)
+ * @param {object} opts.inputs        runtime inputs (CLI --input k=v)
+ * @param {string} [opts.resumeRunId]
+ * @param {function} opts.onEvent     UX event sink
+ */
+export async function runWorkflow(opts) {
+  const { bullswarmDir, doc, pools, inputs = {} } = opts;
+  const runsRoot = join(bullswarmDir, 'workflows');
+  mkdirSync(runsRoot, { recursive: true });
+
+  const resuming = Boolean(opts.resumeRunId);
+  const runId = resuming ? opts.resumeRunId : newRunId();
+  const runDir = join(runsRoot, runId);
+  mkdirSync(runDir, { recursive: true });
+
+  let state;
+  if (resuming && existsSync(join(runDir, 'state.json'))) {
+    state = JSON.parse(readFileSync(join(runDir, 'state.json'), 'utf8'));
+    state.resumed = true;
+  } else {
+    if (resuming) {
+      throw new Error(`cannot resume: no state.json for run ${runId}`);
+    }
+    state = {
+      runId,
+      workflow: doc.name,
+      inputs: { ...Object.fromEntries(
+        Object.entries(doc.inputs ?? {}).map(([k, v]) => [k, v.default]),
+      ), ...inputs },
+      settings: { escalateOnFail: true, concurrency: 4, ...(doc.settings ?? {}) },
+      outputs: {},
+      steps: [],   // linear log: {phase, stepId, type, verdict summary}
+      startedAt: new Date().toISOString(),
+      resumed: false,
+    };
+  }
+  if (opts.inputs && Object.keys(opts.inputs).length) {
+    state.inputs = { ...state.inputs, ...opts.inputs };
+  }
+
+  const runtime = new WorkflowRuntime({
+    bullswarmDir,
+    pools,
+    state,
+    runDir,
+    onEvent: opts.onEvent,
+  });
+  runtime.persist();
+
+  opts.onEvent?.({ type: 'workflow.started', runId, workflow: doc.name, phases: doc.phases.length, resumed: state.resumed });
+
+  let aborted = false;
+  let abortReason = null;
+
+  for (let pi = 0; pi < doc.phases.length && !aborted; pi++) {
+    const phase = doc.phases[pi];
+    opts.onEvent?.({ type: 'phase.started', index: pi, total: doc.phases.length, name: phase.name });
+    let phaseFailed = false;
+
+    for (const step of phase.steps ?? []) {
+      if (resuming && state.outputs[step.id]?.ok === true && step.type === 'run') {
+        opts.onEvent?.({ type: 'step.skipped', stepId: step.id });
+        continue;
+      }
+      let r;
+      try {
+        r = await runtime.runStep(step);
+      } catch (err) {
+        // Step-level errors (bad template refs, unparseable fanout items, …)
+        // are step failures under onError semantics — never crashes.
+        r = { ok: false, why: err.message };
+        state.outputs[step.id] = { ok: false, why: err.message };
+      }
+      state.steps.push({
+        phase: phase.name,
+        stepId: step.id,
+        type: step.type,
+        ok: r.ok,
+        why: r.why ?? null,
+      });
+      runtime.persist();
+
+      if (!r.ok) {
+        phaseFailed = true;
+        const onError = step.onError ?? 'continue';
+        if (onError === 'fail') {
+          aborted = true;
+          abortReason = `step ${step.id} failed (onError: fail): ${r.why ?? 'unknown'}`;
+          break;
+        }
+        if (onError === 'skip-phase') {
+          opts.onEvent?.({ type: 'phase.skipped-rest', phase: phase.name, stepId: step.id });
+          break;
+        }
+        // 'continue' — record and move on
+      }
+    }
+
+    if (!aborted && phaseFailed && (doc.settings?.stopOnPhaseFailure || state.settings.stopOnPhaseFailure)) {
+      aborted = true;
+      abortReason = `phase ${phase.name} had failures (stopOnPhaseFailure)`;
+    }
+    opts.onEvent?.({ type: 'phase.completed', index: pi, name: phase.name, failed: phaseFailed });
+  }
+
+  const finishedAt = new Date().toISOString();
+  state.finishedAt = finishedAt;
+  state.status = aborted ? 'failed' : 'completed';
+  if (abortReason) state.abortReason = abortReason;
+  runtime.persist();
+
+  const report = buildReport(state, doc, runDir);
+  writeFileSync(join(runDir, 'report.json'), `${JSON.stringify(report, null, 2)}\n`);
+  opts.onEvent?.({ type: 'workflow.completed', runId, status: state.status, report: report.summary });
+
+  return { runId, runDir, state, report };
+}
+
+export function buildReport(state, doc, runDir) {
+  const stepResults = state.steps ?? [];
+  const fanoutSteps = Object.entries(state.outputs ?? {}).filter(
+    ([, v]) => v && typeof v === 'object' && 'items' in v,
+  );
+  let fanoutOk = 0;
+  let fanoutFailed = 0;
+  for (const [, v] of fanoutSteps) {
+    fanoutOk += v.ok ?? 0;
+    fanoutFailed += v.failed ?? 0;
+  }
+  const simpleOk = stepResults.filter((s) => s.ok).length;
+  const simpleFailed = stepResults.filter((s) => s.ok === false).length;
+
+  return {
+    schemaVersion: 'bullswarm.workflow.report.v1',
+    runId: state.runId,
+    workflow: state.workflow,
+    status: state.status,
+    startedAt: state.startedAt,
+    finishedAt: state.finishedAt,
+    resumed: state.resumed === true,
+    abortReason: state.abortReason ?? null,
+    summary: {
+      stepsTotal: stepResults.length,
+      stepsOk: simpleOk,
+      stepsFailed: simpleFailed,
+      fanoutSteps: fanoutSteps.length,
+      fanoutOk,
+      fanoutFailed,
+    },
+    steps: stepResults,
+    outputs: state.outputs,
+    artifactsDir: runDir,
+  };
+}

package/src/workflow/runtime.js

@@ -0,0 +1,258 @@
+// bullswarm workflow runtime — executes a validated workflow document.
+//
+// Doctrine:
+//   R1. Dispatch reuses watchOnce verbatim — same verdict contract, same
+//       quarantine side effects, same meter accounting as single runs.
+//   R2. State persists to disk after EVERY step; resume = skip ok:true.
+//   R3. Escalation is verdict-driven: failed step retries once on next pool
+//       by surplus (never the same pool, never more than once).
+//   R4. Concurrency limiter is global across fanout expansions.
+//   R5. onError: continue | fail (abort run) | skip-phase (rest of phase).
+
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pickPool } from '../lib/route.js';
+import { watchOnce } from '../lib/watch.js';
+import { renderDeep, extractItems } from './template.js';
+
+export class WorkflowRuntime {
+  /**
+   * @param {object} opts
+   * @param {string} opts.bullswarmDir  ~/.bullswarm
+   * @param {object} opts.pools         buildPoolsLive result pools array
+   * @param {object} opts.state         loaded workflow state (mutable)
+   * @param {string} opts.runDir        artifact dir for this run
+   * @param {function} opts.onEvent     (event) => void for UX rendering
+   */
+  constructor(opts) {
+    this.bullswarmDir = opts.bullswarmDir;
+    this.pools = opts.pools;
+    this.state = opts.state;
+    this.runDir = opts.runDir;
+    this.onEvent = opts.onEvent ?? (() => {});
+    this.limiter = null; // set from settings at run()
+  }
+
+  persist() {
+    writeFileSync(join(this.runDir, 'state.json'), `${JSON.stringify(this.state, null, 2)}\n`);
+  }
+
+  emit(type, payload) {
+    this.onEvent({ type, ...payload });
+  }
+
+  scopeFor(step) {
+    return {
+      inputs: this.state.inputs,
+      outputs: this.state.outputs,
+      runId: this.state.runId,
+      wfDir: this.runDir,
+    };
+  }
+
+  /**
+   * Execute one dispatch (run or single fanout expansion).
+   * Returns verdict. Applies escalation per R3.
+   */
+  async dispatch(step, taskText, targetDir, paths, opts = {}) {
+    const attemptPools = this.preparePools(step);
+    let lastVerdict = null;
+
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const route = pickPool(step.lane ?? 'chore', attemptPools, {
+        callerEligible: false,
+        callerSession: false, // workflow context: every pool is a worker
+        now: Date.now(),
+      });
+      if (!route.pick) {
+        return {
+          ok: false,
+          keepOnClaude: false,
+          why: `no eligible pool (${route.why})`,
+          pick: { pool: null },
+          meta: { exitCode: null },
+        };
+      }
+      const connector = route.pick.connector?.connector ?? route.pick.connector;
+
+      // Pin pool if requested (validation already checked existence)
+      const chosen = step.pool
+        ? attemptPools.find((p) => p.name === step.pool)
+        : connector;
+      const conn = (chosen?.connector) ? chosen.connector : chosen;
+
+      this.emit('step.started', {
+        stepId: step.id,
+        item: opts.item,
+        pool: conn.name,
+        attempt,
+      });
+
+      const verdict = await watchOnce(conn, taskText, targetDir, paths, {
+        timeoutSec: step.timeoutSec ?? conn.timeoutSec ?? 900,
+      });
+
+      if (verdict.ok || step.pool) {
+        // pinned pools don't escalate — you asked for THIS pool
+        return verdict;
+      }
+      lastVerdict = verdict;
+      // Escalate: drop the pool that just failed from this step's candidates.
+      const failedName = conn.name;
+      const idx = attemptPools.findIndex((p) => p.name === failedName);
+      if (idx >= 0) attemptPools.splice(idx, 1);
+      if (!opts.escalate || attemptPools.length === 0) break;
+      this.emit('step.escalate', {
+        stepId: step.id, item: opts.item,
+        from: failedName, why: verdict.why,
+      });
+    }
+    return lastVerdict;
+  }
+
+  preparePools(step) {
+    // Fresh eligible list per dispatch: enabled, not quarantined/exhausted.
+    return this.pools.filter((p) => p.enabled !== false && !p.quarantine);
+  }
+
+  async runStep(step) {
+    const scope = this.scopeFor(step);
+    if (step.type === 'run') {
+      return this.runSingle(step, scope);
+    }
+    if (step.type === 'fanout') {
+      return this.runFanout(step, scope);
+    }
+    throw new Error(`unknown step type ${step.type}`);
+  }
+
+  async runSingle(step, scope) {
+    const rendered = renderDeep(
+      {
+        lane: step.lane ?? 'chore',
+        addDir: step.addDir,
+        prompt: step.prompt,
+        taskFile: step.taskFile,
+      },
+      scope,
+    );
+    const taskText = rendered.prompt
+      ?? readFileSync(rendered.taskFile, 'utf8');
+    const targetDir = rendered.addDir ? String(rendered.addDir).replace(/^~/, process.env.HOME ?? '') : process.cwd();
+
+    const stamp = `${step.id}-${Date.now().toString(36)}`;
+    const paths = {
+      taskFile: join(this.runDir, `task-${stamp}.md`),
+      outFile: join(this.runDir, `out-${stamp}.md`),
+    };
+
+    const verdict = await this.dispatch(step, taskText, targetDir, paths, {
+      escalate: this.state.settings.escalateOnFail !== false,
+    });
+    this.recordOutput(step.id, verdict, paths);
+    return verdict;
+  }
+
+  async runFanout(step, scope) {
+    const items = extractItems(this.state, renderTemplate0(step.itemsFrom, scope));
+    const concurrency = Math.max(1, Math.min(
+      step.concurrency ?? this.state.settings.concurrency ?? 4,
+      this.state.settings.concurrency ?? Infinity,
+    ));
+    const results = new Array(items.length).fill(null);
+    let cursor = 0;
+    let failures = 0;
+    const resumed = this.state.outputs?.[step.id]?.items ?? [];
+
+    const worker = async () => {
+      while (cursor < items.length) {
+        const i = cursor++;
+        const item = items[i];
+
+        // Resume: skip items whose saved verdict is ok:true (R2)
+        const prev = resumed[i];
+        if (prev?.verdict?.ok === true) {
+          results[i] = prev;
+          this.emit('item.skipped', { stepId: step.id, index: i, item });
+          continue;
+        }
+
+        const itemScope = { ...scope, item };
+        let template;
+        try {
+          template = renderDeep(step.stepTemplate, itemScope);
+        } catch (err) {
+          results[i] = { verdict: { ok: false, why: err.message }, pool: null };
+          failures++;
+          this.emit('item.failed', { stepId: step.id, index: i, item, why: err.message });
+          continue;
+        }
+
+        const stamp = `${step.id}-${i}-${Date.now().toString(36)}`;
+        const paths = {
+          taskFile: join(this.runDir, `task-${stamp}.md`),
+          outFile: join(this.runDir, `out-${stamp}.md`),
+        };
+
+        const targetDir = template.addDir
+          ? String(template.addDir).replace(/^~/, process.env.HOME ?? '')
+          : process.cwd();
+        const taskText = template.prompt
+          ?? readFileSync(String(template.taskFile), 'utf8');
+
+        this.emit('item.started', { stepId: step.id, index: i, total: items.length, item });
+        const verdict = await this.dispatch(
+          { ...step, id: `${step.id}[${i}]` },
+          taskText, targetDir, paths,
+          { item, escalate: this.state.settings.escalateOnFail !== false },
+        );
+        results[i] = { item, verdict, outFile: paths.outFile };
+        if (verdict.ok) {
+          this.emit('item.completed', { stepId: step.id, index: i, pool: verdict.pick?.pool, wall: verdict.meta?.wallSec });
+        } else {
+          failures++;
+          this.emit('item.failed', { stepId: step.id, index: i, why: verdict.why, pool: verdict.pick?.pool });
+        }
+        this.persist();
+      }
+    };
+
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+
+    const oks = results.filter((r) => r?.verdict?.ok === true).length;
+    this.state.outputs[step.id] = {
+      total: items.length,
+      ok: oks,
+      failed: items.length - oks,
+      items: results,
+    };
+    this.persist();
+    return { ok: failures === 0, results };
+  }
+
+  recordOutput(stepId, verdict, paths) {
+    let outputText = null;
+    try {
+      if (paths.outFile && existsSync(paths.outFile)) {
+        outputText = readFileSync(paths.outFile, 'utf8');
+      }
+    } catch { /* non-fatal */ }
+    this.state.outputs[stepId] = {
+      ok: verdict.ok,
+      pool: verdict.pick?.pool ?? null,
+      why: verdict.why,
+      outFile: paths.outFile,
+      wallSec: verdict.meta?.wallSec,
+      outputText,
+    };
+    this.persist();
+  }
+}
+
+function renderTemplate0(str, scope) {
+  return str.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_, ref) => {
+    const v = ref.trim().split('.').reduce((acc, k) => (acc == null ? undefined : acc[k]), scope);
+    if (v === undefined) throw new Error(`unresolved ref {{${ref.trim()}}}`);
+    return typeof v === 'string' ? v : JSON.stringify(v);
+  });
+}

package/src/workflow/template.js

@@ -0,0 +1,76 @@
+// bullswarm workflow — {{ref}} templating + JSON-path access.
+//
+// Scope precedence: loop item > inputs > outputs.<stepId> > run metadata.
+// A missing reference throws (validation should have caught static cases;
+// this catches runtime-only gaps like fanout item field typos).
+
+export function getPath(obj, path) {
+  return path.split('.').reduce((acc, key) => (acc == null ? undefined : acc[key]), obj);
+}
+
+/**
+ * Expand {{ref}} tokens in a string against a scope object.
+ * Supports {{item}}, {{item.path.to.field}}, {{inputs.x}}, {{outputs.stepId}},
+ * {{runId}}, {{wfDir}}. Non-string values are JSON-stringified.
+ */
+export function renderTemplate(str, scope) {
+  if (typeof str !== 'string') return str;
+  return str.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_, ref) => {
+    const v = getPath(scope, ref.trim());
+    if (v === undefined) {
+      throw new Error(`template ref "{{${ref.trim()}}}" unresolved at render time`);
+    }
+    return typeof v === 'string' ? v : JSON.stringify(v);
+  });
+}
+
+/** Deep-render every string in a step-like object. */
+export function renderDeep(obj, scope) {
+  if (typeof obj === 'string') return renderTemplate(obj, scope);
+  if (Array.isArray(obj)) return obj.map((v) => renderDeep(v, scope));
+  if (obj && typeof obj === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) out[k] = renderDeep(v, scope);
+    return out;
+  }
+  return obj;
+}
+
+/**
+ * Extract the items array for a fanout from workflow state by dotted path.
+ * Accepts:
+ *   - a real array (inputs.files, outputs.step.items)
+ *   - an outputs entry with outputText containing a JSON array
+ *     (the common case: a discover step returns "[\"a.json\", ...]")
+ */
+export function extractItems(state, itemsFrom) {
+  const v = getPath(state, itemsFrom);
+  if (v === undefined) {
+    throw new Error(`fanout itemsFrom "${itemsFrom}" not found in workflow state`);
+  }
+  if (Array.isArray(v)) return v;
+
+  // outputs.<stepId> envelope: try its recorded output text
+  if (v && typeof v === 'object' && typeof v.outputText === 'string') {
+    const parsed = parseJsonArray(v.outputText);
+    if (parsed) return parsed;
+    throw new Error(
+      `fanout itemsFrom "${itemsFrom}": step output is not a JSON array. ` +
+      'The discover step must return ONLY a JSON array of items.',
+    );
+  }
+  throw new Error(`fanout itemsFrom "${itemsFrom}" must resolve to an array (got ${typeof v})`);
+}
+
+/** Parse the first JSON array found in a text blob, tolerating prose around it. */
+export function parseJsonArray(text) {
+  const start = text.indexOf('[');
+  const end = text.lastIndexOf(']');
+  if (start === -1 || end <= start) return null;
+  try {
+    const arr = JSON.parse(text.slice(start, end + 1));
+    return Array.isArray(arr) ? arr : null;
+  } catch {
+    return null;
+  }
+}

package/src/workflow/tui.js

@@ -0,0 +1,236 @@
+// bullswarm workflow terminal UX — renders runtime events Claude-style.
+//
+// Marks: ✓ ok · ✗ fail · ⟡ running · ⋈ blocked · ⏭ skipped · ⏳ phase
+// Non-TTY: emits compact JSONL lines instead (machine-consumable).
+// Zero dependencies: plain ANSI, cursor-rewrites only for the spinner.
+
+const MARK = {
+  ok: '✓',
+  fail: '✗',
+  running: '⟡',
+  blocked: '⋈',
+  skipped: '⏭',
+  pending: '·',
+};
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const RESET = '\x1b[0m';
+
+function c(code, s) { return `${code}${s}${RESET}`; }
+function fmtSecs(ms) {
+  if (ms == null) return '—';
+  const s = ms / 1000;
+  return s >= 60 ? `${Math.floor(s / 60)}m ${Math.round(s % 60)}s` : `${s.toFixed(1)}s`;
+}
+
+export class WorkflowTui {
+  constructor({ quiet = false, json = false } = {}) {
+    this.quiet = quiet;
+    this.json = json;
+    this.isTTY = process.stdout.isTTY === true;
+    this.phaseIndex = 0;
+    this.phaseTotal = 0;
+    this.phaseName = '';
+    this.spinnerTimer = null;
+    this.spinFrame = 0;
+    this.liveLine = null;      // current in-flight line to rewrite
+    this.counts = { ok: 0, fail: 0 };
+    this.startedAt = null;
+    if (!this.json && !this.isTTY) {
+      // Non-TTY human mode: no ANSI colors (plain marks still readable)
+      this.color = false;
+    }
+  }
+
+  c(code, s) { return this.isTTY ? c(code, s) : s; }
+
+  startSpinner() {
+    if (!this.isTTY || this.json || this.spinnerTimer) return;
+    this.spinnerTimer = setInterval(() => {
+      this.spinFrame = (this.spinFrame + 1) % SPINNER_FRAMES.length;
+      if (this.liveLine) this.rewriteLive(this.liveLine.render());
+    }, 120);
+  }
+
+  stopSpinner() {
+    if (this.spinnerTimer) { clearInterval(this.spinnerTimer); this.spinnerTimer = null; }
+  }
+
+  rewriteLive(line) {
+    if (!this.isTTY) return;
+    process.stdout.write(`\r\x1b[K${line}`);
+  }
+
+  commitLive() {
+    if (this.liveLine) {
+      if (this.isTTY) process.stdout.write('\n');
+      this.liveLine = null;
+    }
+  }
+
+  print(line) {
+    if (this.json) return;
+    if (this.quiet && !line.includes('summary')) return;
+    this.commitLive();
+    console.log(line);
+  }
+
+  handle(event) {
+    switch (event.type) {
+      case 'workflow.started': {
+        this.startedAt = Date.now();
+        if (this.json) {
+          console.log(JSON.stringify({ ev: 'workflow.started', ...event }));
+          return;
+        }
+        const resumed = event.resumed ? this.c(YELLOW, ' (resumed)') : '';
+        this.print('');
+        this.print(this.c(BOLD, `bullswarm workflow · ${event.workflow} · run ${event.runId}`) + resumed);
+        this.print(this.c(DIM, `─`.repeat(58)));
+        break;
+      }
+      case 'phase.started': {
+        this.phaseIndex = event.index + 1;
+        this.phaseTotal = event.total;
+        this.phaseName = event.name;
+        if (this.json) {
+          console.log(JSON.stringify({ ev: 'phase.started', ...event }));
+          return;
+        }
+        this.print('');
+        this.print(this.c(CYAN, `▐ phase ${event.index + 1}/${event.total} · ${event.name}`));
+        break;
+      }
+      case 'step.started': {
+        if (this.json) {
+          console.log(JSON.stringify({ ev: 'step.started', ...event }));
+          return;
+        }
+        const label = event.item != null ? `${event.stepId}[${labelOf(event.item)}]` : event.stepId;
+        this.commitLive();
+        this.liveLine = makeLiveLine(MARK.running, label, event.pool, this);
+        this.rewriteLive(this.liveLine.render());
+        this.startSpinner();
+        break;
+      }
+      case 'item.started': {
+        if (this.json) {
+          console.log(JSON.stringify({ ev: 'item.started', ...event }));
+          return;
+        }
+        const idx = `${event.index + 1}/${event.total ?? '?'}`;
+        const label = `${event.stepId}[${idx}]`;
+        this.commitLive();
+        this.liveLine = makeLiveLine(MARK.running, label, event.pool ?? '…', this, itemPreview(event.item));
+        this.rewriteLive(this.liveLine.render());
+        this.startSpinner();
+        break;
+      }
+      case 'item.completed': {
+        this.counts.ok++;
+        if (this.json) {
+          console.log(JSON.stringify({ ev: 'item.completed', ...event }));
+          return;
+        }
+        const label = `${event.stepId}[${event.index + 1}]`;
+        this.commitLive();
+        this.print(
+          `  ${this.c(GREEN, MARK.ok)} ${label.padEnd(34)} ${this.c(DIM, String(event.pool ?? '').padEnd(14))} ${fmtSecs(event.wall * 1000)}   ok`
+        );
+        break;
+      }
+      case 'item.failed': {
+        this.counts.fail++;
+        if (this.json) {
+          console.log(JSON.stringify({ ev: 'item.failed', ...event }));
+          return;
+        }
+        const label = `${event.stepId}[${event.index + 1}]`;
+        this.commitLive();
+        const pool = event.pool ? `${event.pool}` : '—';
+        this.print(
+          `  ${this.c(RED, MARK.fail)} ${label.padEnd(34)} ${pool.padEnd(14)} fail · ${(event.why ?? '').slice(0, 48)}`
+        );
+        break;
+      }
+      case 'step.escalate': {
+        if (this.json) {
+          console.log(JSON.stringify({ ev: 'step.escalate', ...event }));
+          return;
+        }
+        this.commitLive();
+        this.print(`    ${this.c(YELLOW, '↳ escalate')} ${event.from} → next surplus pool (${(event.why ?? '').slice(0, 40)})`);
+        break;
+      }
+      case 'step.skipped': {
+        if (this.json) { console.log(JSON.stringify({ ev: 'step.skipped', ...event })); return; }
+        this.print(`  ${this.c(YELLOW, MARK.skipped)} ${event.stepId.padEnd(34)} ${this.c(DIM, 'ok from previous run (resume)')}`);
+        break;
+      }
+      case 'phase.skipped-rest': {
+        if (this.json) { console.log(JSON.stringify({ ev: 'phase.skipped-rest', ...event })); return; }
+        this.commitLive();
+        this.print(`  ${this.c(YELLOW, MARK.skipped)} rest of phase "${event.phase}" skipped after ${event.stepId}`);
+        break;
+      }
+      case 'phase.completed': {
+        this.stopSpinner();
+        this.commitLive();
+        if (this.json) { console.log(JSON.stringify({ ev: 'phase.completed', ...event })); return; }
+        const mark = event.failed ? this.c(RED, MARK.fail) : this.c(GREEN, MARK.ok);
+        this.print(`${mark} phase ${this.phaseIndex}/${this.phaseTotal} · ${event.name} done${event.failed ? this.c(YELLOW, ' (with failures)') : ''}`);
+        break;
+      }
+      case 'workflow.completed': {
+        this.stopSpinner();
+        this.commitLive();
+        if (this.json) {
+          console.log(JSON.stringify({ ev: 'workflow.completed', ...event }));
+          return;
+        }
+        const elapsed = this.startedAt ? fmtSecs(Date.now() - this.startedAt) : '—';
+        const s = event.report ?? {};
+        this.print('');
+        this.print(this.c(DIM, '─'.repeat(58)));
+        const status = event.status === 'completed'
+          ? this.c(GREEN, '✓ completed')
+          : this.c(RED, '✗ failed');
+        this.print(
+          `${status}  steps ✓${s.stepsOk ?? 0}/✗${s.stepsFailed ?? 0} · fanout ✓${s.fanoutOk ?? 0}/✗${s.fanoutFailed ?? 0} · elapsed ${elapsed}`
+        );
+        if (event.runId) this.print(this.c(DIM, `report: ~/.bullswarm/workflows/${event.runId}/report.json`));
+        break;
+      }
+      default:
+        if (this.json) console.log(JSON.stringify({ ev: event.type, ...event }));
+    }
+  }
+}
+
+function makeLiveLine(markChar, label, pool, tui, preview) {
+  const start = Date.now();
+  const render = () => {
+    const frame = tui.isTTY ? SPINNER_FRAMES[tui.spinFrame] : MARK.pending;
+    const secs = ((Date.now() - start) / 1000).toFixed(0);
+    const pv = preview ? ` ${tui.c(DIM, preview)}` : '';
+    return `  ${tui.c(CYAN, frame)} ${String(label).padEnd(34)} ${String(pool).padEnd(14)} ${secs}s running${pv}`;
+  };
+  return { render };
+}
+
+function itemPreview(item) {
+  if (item == null) return '';
+  const s = typeof item === 'string' ? item : JSON.stringify(item);
+  return s.length > 40 ? `${s.slice(0, 38)}…` : s;
+}
+
+function labelOf(item) {
+  const s = typeof item === 'string' ? item : JSON.stringify(item);
+  return s.length > 20 ? `${s.slice(0, 18)}…]` : s;
+}

package/src/workflow/validate.js

@@ -0,0 +1,205 @@
+// bullswarm workflow — schema validation for dynamic workflow documents.
+//
+// Doctrine:
+//   W1. A workflow is a JSON document, validated fully BEFORE anything runs.
+//   W2. Template references must resolve at validation time, except
+//       {{item}} / {{item.*}} inside fanout stepTemplate (per-expansion).
+//   W3. Lanes and pinned pools are checked against the live registry so a
+//       typo never burns quota discovering itself mid-run.
+
+const LANES = ['analyze', 'build', 'chore'];
+const ON_ERROR = ['continue', 'fail', 'skip-phase'];
+const STEP_TYPES = ['run', 'fanout'];
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+export class WorkflowValidationError extends Error {
+  constructor(issues) {
+    super(`workflow invalid: ${issues.length} problem(s)`);
+    this.issues = issues;
+  }
+}
+
+function collect(issues, ok, msg) {
+  if (!ok) issues.push(msg);
+  return ok;
+}
+
+/** Extract {{ref}} tokens from a string. */
+export function templateRefs(str) {
+  const out = [];
+  const re = /\{\{\s*([^}]+?)\s*\}\}/g;
+  let m;
+  while ((m = re.exec(str)) !== null) out.push(m[1].trim());
+  return out;
+}
+
+function walkStrings(value, fn) {
+  if (typeof value === 'string') {
+    fn(value);
+  } else if (Array.isArray(value)) {
+    for (const v of value) walkStrings(v, fn);
+  } else if (value && typeof value === 'object') {
+    for (const v of Object.values(value)) walkStrings(v, fn);
+  }
+}
+
+/**
+ * Validate a workflow document against the known lanes/pools.
+ * @param {object} wf parsed workflow JSON
+ * @param {{lanes?: string[], poolNames?: string[]}} env live registry info
+ * @returns {{name: string, warnings: string[]}} normalized doc
+ * @throws WorkflowValidationError with .issues[] on any problem
+ */
+export function validateWorkflow(wf, { lanes = LANES, poolNames = [] } = {}) {
+  const issues = [];
+  const warnings = [];
+  const validLanes = new Set(lanes);
+  const validPools = new Set(poolNames);
+
+  if (!wf || typeof wf !== 'object' || Array.isArray(wf)) {
+    throw new WorkflowValidationError(['document is not a JSON object']);
+  }
+
+  collect(issues, typeof wf.name === 'string' && NAME_RE.test(wf.name),
+    `name "${wf.name}" must be kebab-case (letters/digits/dashes)`);
+  collect(issues, typeof wf.description === 'string' && wf.description.length > 0,
+    'description is required');
+  collect(issues, Array.isArray(wf.phases) && wf.phases.length > 0,
+    'phases must be a non-empty array');
+
+  // inputs
+  const inputs = wf.inputs ?? {};
+  if (!collect(issues, inputs && typeof inputs === 'object' && !Array.isArray(inputs),
+    'inputs must be an object')) {
+    throw new WorkflowValidationError(issues);
+  }
+  for (const [k, v] of Object.entries(inputs)) {
+    collect(issues, v && typeof v === 'object', `input "${k}" must be an object`);
+  }
+
+  // phases
+  const phaseNames = new Set();
+  const stepIds = new Set();
+  const outputs = new Set(); // step ids that produce outputs
+
+  (wf.phases ?? []).forEach((phase, pi) => {
+    const at = `phases[${pi}]`;
+    collect(issues, phase && typeof phase === 'object', `${at} must be an object`);
+    if (!phase || typeof phase !== 'object') return;
+    collect(issues, typeof phase.name === 'string' && NAME_RE.test(phase.name),
+      `${at}.name must be kebab-case`);
+    if (phase.name) {
+      collect(issues, !phaseNames.has(phase.name), `duplicate phase name "${phase.name}"`);
+      phaseNames.add(phase.name);
+    }
+    collect(issues, Array.isArray(phase.steps), `${at}.steps must be an array`);
+
+    (phase.steps ?? []).forEach((step, si) => {
+      const sat = `${at}.steps[${si}]`;
+      if (!collect(issues, step && typeof step === 'object', `${sat} must be an object`)) return;
+      collect(issues, typeof step.id === 'string' && NAME_RE.test(step.id),
+        `${sat}.id must be kebab-case`);
+      if (step.id) {
+        collect(issues, !stepIds.has(step.id), `duplicate step id "${step.id}"`);
+        stepIds.add(step.id);
+        outputs.add(step.id);
+      }
+      collect(issues, STEP_TYPES.includes(step.type),
+        `${sat}.type must be one of ${STEP_TYPES.join('|')} (got "${step.type}")`);
+      collect(issues, ON_ERROR.includes(step.onError ?? 'continue'),
+        `${sat}.onError must be one of ${ON_ERROR.join('|')}`);
+
+      if (step.lane != null) {
+        collect(issues, validLanes.has(step.lane),
+          `${sat}.lane "${step.lane}" is not a lane (${[...validLanes].join(', ')})`);
+      }
+      if (step.pool != null) {
+        collect(issues, validPools.has(step.pool),
+          `${sat}.pool "${step.pool}" is not a known pool (${[...validPools].join(', ') || 'none discovered'})`);
+      }
+
+      if (step.type === 'fanout') {
+        collect(issues, typeof step.itemsFrom === 'string' && step.itemsFrom.length > 0,
+          `${sat}.itemsFrom is required for fanout steps`);
+        // itemsFrom must reference declared inputs or a prior step's output
+        if (typeof step.itemsFrom === 'string' && step.itemsFrom.includes('.')) {
+          const [root, target] = step.itemsFrom.split('.');
+          collect(issues, root === 'inputs' || (root === 'outputs' && outputs.has(target)),
+            `${sat}.itemsFrom "${step.itemsFrom}" cannot resolve (use inputs.<name> or outputs.<priorStepId>)`);
+        } else if (typeof step.itemsFrom === 'string') {
+          collect(issues, false,
+            `${sat}.itemsFrom "${step.itemsFrom}" must be a dotted path (inputs.<name> or outputs.<priorStepId>)`);
+        }
+        collect(issues, step.stepTemplate && typeof step.stepTemplate === 'object',
+          `${sat}.stepTemplate is required for fanout steps`);
+        if (step.concurrency != null) {
+          collect(issues, Number.isInteger(step.concurrency) && step.concurrency >= 1,
+            `${sat}.concurrency must be a positive integer`);
+        }
+      } else if (step.type === 'run') {
+        collect(issues,
+          typeof step.taskFile === 'string' || typeof step.prompt === 'string',
+          `${sat} needs taskFile or prompt`);
+      }
+
+      if (step.timeoutSec != null) {
+        collect(issues, Number.isFinite(step.timeoutSec) && step.timeoutSec > 0,
+          `${sat}.timeoutSec must be a positive number`);
+      }
+    });
+  });
+
+  if (issues.length) throw new WorkflowValidationError(issues);
+
+  // ---- template reference resolution (W2) --------------------------------
+  // Scope available at validation: inputs.*, outputs.<stepId> for PRIOR
+  // steps, runId/wfDir metadata. {{item}} allowed only inside fanout
+  // stepTemplate. We do a second pass now that all step ids are known.
+
+  const resolvable = (ref, inTemplate) => {
+    const root = ref.split('.')[0];
+    if (root === 'item') return inTemplate;
+    if (root === 'inputs') return true; // presence checked at runtime vs declared inputs? keep lenient, warn below
+    if (root === 'outputs') {
+      const target = ref.split('.')[1];
+      return target ? outputs.has(target) : false;
+    }
+    return root === 'runId' || root === 'wfDir';
+  };
+
+  const checkRefs = (obj, inTemplate, label) => {
+    walkStrings(obj, (s) => {
+      for (const ref of templateRefs(s)) {
+        if (!resolvable(ref, inTemplate)) {
+          issues.push(`${label}: template ref "{{${ref}}}" cannot resolve` +
+            (inTemplate ? '' : ` (known roots: inputs, outputs.<stepId>, runId, wfDir)`));
+        }
+      }
+    });
+  };
+
+  (wf.phases ?? []).forEach((phase, pi) => {
+    (phase.steps ?? []).forEach((step, si) => {
+      const sat = `phases[${pi}].steps[${si}](${step.id ?? '?'})`;
+      const { stepTemplate, ...rest } = step;
+      checkRefs(rest, false, sat);
+      if (stepTemplate) checkRefs(stepTemplate, true, `${sat}.stepTemplate`);
+    });
+  });
+
+  // undeclared input usage → warning only (inputs may be passed at runtime)
+  const usedInputs = new Set();
+  walkStrings(wf, (s) => {
+    for (const ref of templateRefs(s)) {
+      if (ref.startsWith('inputs.')) usedInputs.add(ref.slice('inputs.'.length));
+    }
+  });
+  for (const u of usedInputs) {
+    if (!(u in inputs)) {
+      warnings.push(`template uses inputs.${u} but it is not declared under "inputs" (pass --input ${u}=…)`);
+    }
+  }
+
+  if (issues.length) throw new WorkflowValidationError(issues);
+  return { name: wf.name, warnings };
+}