bullswarm 0.10.7 → 0.10.8

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # bullswarm changelog
 
+## 0.10.8 — quieter monitoring and resilient orchestration
+
+- Made `workflow watch` aggregate low-level activity into compact interval
+  heartbeats by default, with event/action deltas, quiet duration, prompt
+  semantic transitions, terminal result handoff, and `--verbose` drill-down.
+- Implemented the documented top-level `run --prompt` form and standardized
+  usage errors as exit 2 across run, workflow drafts/runs, and strategy paths.
+- Added explicit goal-resume orchestrator pin/unpin behavior and strengthened
+  the orchestrator as a control-plane-only decision thread.
+- Recognize Claude's exact `Failed to authenticate` response as an auth failure
+  and migrate the connector signature additively without replacing local
+  connector customization.
+- Expanded non-network CLI, health, release, watch, resume, auth, help, and
+  documentation coverage. The full suite now contains 271 tests.
+
 ## 0.10.7 — clearer orchestration overview
 
 - Replaced the orchestrator trace dump with a summary-first view showing what

package/README.md

@@ -67,6 +67,7 @@ bullswarm setup    # re-run or repair
 bullswarm pools    # meter state, pace position, quarantine status
 bullswarm strategy refresh --apply --yes  # approve capability-aware tier autopilot
 bullswarm run --lane analyze --add-dir ~/some-repo --task-file /tmp/t.md --json
+bullswarm run --lane analyze --add-dir ~/some-repo --prompt "Inspect the parser" --json
 bullswarm workflow goal "Fix the failing tests and verify the change" --cwd ~/some-repo
 bullswarm health   # re-judge saved outputs; catch gate failures
 ```
@@ -84,6 +85,17 @@ bullswarm health   # re-judge saved outputs; catch gate failures
 | `doctor` | Machine-readable readiness report; self-heals on first call |
 | `workflow` | Start an autonomous goal, or run / validate / draft / inspect explicit workflows and their live instances. |
 
+Discover and validate workflow definitions without executing them:
+
+```bash
+bullswarm workflow list
+bullswarm workflow list --json
+bullswarm workflow validate workflows/my-workflow.json
+```
+
+`workflow goal --request <path>` and `--run-id <id>` are internal detached-runner
+resume plumbing. Normal callers should provide a goal or use `--resume <shortId|runId>`.
+
 ## Model strategy and invocation telemetry
 
 Bullswarm can inventory the models exposed by installed agent CLIs and combine
@@ -260,16 +272,20 @@ auditing completed runs.
 
 ### Live workflow dashboard
 
-For ordinary observation, use the non-interactive watcher. It prints only when
-the phase, step, agent action, routing, or status changes, plus a 60-second
-heartbeat while otherwise quiet. Terminal output includes every attempt's
-agent/model, elapsed time, outcome, and tokens, so a slow test is distinguishable
-from a stalled process without writing a polling script.
+For ordinary observation, use the non-interactive watcher. Human output is one
+compact aggregate line per semantic change and a 60-second heartbeat while
+otherwise quiet. Each line reports status/location, events and agent actions
+captured since the preceding sample, and quiet duration. It does not repeat
+command or response excerpts. Use `--verbose` for the detailed per-agent and
+last-action view. Compact terminal output reports the overall attempt count and
+elapsed time; `--verbose` includes every attempt's agent/model, outcome, and
+tokens. This keeps agent monitoring cheap while retaining a drill-down path.
 
 ```bash
 bullswarm workflow watch <shortId>
 bullswarm workflow watch <shortId> --jsonl       # automation-friendly stream
 bullswarm workflow watch <shortId> --once        # one current/terminal snapshot
+bullswarm workflow watch <shortId> --verbose     # detailed agent/action view
 ```
 
 `workflow tui` is the interactive, Claude-style `/workflows` view. For an

package/connectors/claude-code.json

@@ -18,6 +18,7 @@
   "authSignatures": [
     "unauthorized",
     "authentication failed",
+    "failed to authenticate",
     "credit balance",
     "not logged in",
     "please run /login"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.10.7",
+  "version": "0.10.8",
   "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

@@ -59,6 +59,10 @@ bullswarm run --lane <analyze|build|chore> \
   --add-dir <abs/path/to/repo> \
   --task-file <abs/path/to/task.md> \
   --json
+
+# Equivalent explicit prompt form (also accepts trailing task text)
+bullswarm run --lane analyze --add-dir <abs/path/to/repo> \
+  --prompt "Inspect and verify the parser" --json
 ```
 
 The verdict shape:
@@ -202,8 +206,15 @@ bullswarm workflow runs --historical --since yesterday --until today
 bullswarm workflow runs show <shortId>        # state + report + summary
 bullswarm workflow runs result <shortId> --json # stable delivery for the caller
 bullswarm workflow runs delete <shortId> --yes
+
+bullswarm workflow list
+bullswarm workflow validate workflows/demo.json
 ```
 
+`workflow goal --request <path>` and `--run-id <id>` are internal detached-runner
+plumbing. Ordinary callers should provide a goal or resume with
+`--resume <shortId|runId>`.
+
 Historical time ranges filter the workflow's initiation time (`startedAt`),
 not completion time. `--since` is inclusive and `--until` is exclusive, with
 `--from`/`--to` and `--started-after`/`--started-before` aliases. Bounds accept
@@ -279,9 +290,13 @@ reason, and child-process termination evidence. `workflow tui` displays the
 same information interactively. `workflow events` supports replay after a
 monotonic sequence cursor.
 
-Prefer `workflow watch` for ordinary monitoring; it prints semantic changes and
-a periodic heartbeat, then a per-attempt timing/token breakdown at terminal
-status. `workflow steer` is an optional durable queue for autonomous workflows:
+Prefer `workflow watch` for ordinary monitoring; default human text is a compact
+aggregate heartbeat with status/location, interval event and agent-action counts,
+and quiet duration. It does not repeat command or response excerpts. Add
+`--verbose` for the detailed agent and last-action view. `--jsonl` keeps the
+machine-readable snapshot stream. Compact terminal text includes overall timing
+and the exact `workflow runs result <shortId> --json` next command; `--verbose`
+adds per-attempt timing and token details. `workflow steer` is an optional durable queue for autonomous workflows:
 it never changes the active worker and is delivered only to the next
 not-yet-started decision gate. Steering cannot expand the original authority,
 weaken verification, or bypass proposal validation.

package/src/cli.js

@@ -96,6 +96,34 @@ async function cmdRun(opts) {
   }
   const targetDir = resolve(opts['add-dir'] ?? process.cwd());
 
+  // Validate task input before routing so malformed invocations never fall
+  // through to the caller-session path.
+  if (opts['task-file'] === true || opts.prompt === true ||
+      (opts['task-file'] != null && typeof opts['task-file'] !== 'string') ||
+      (opts.prompt != null && typeof opts.prompt !== 'string')) {
+    console.error('usage: --prompt and --task-file require a value');
+    return 2;
+  }
+  if (opts['task-file'] && opts.prompt != null) {
+    console.error('usage: choose one of --prompt, --task-file, or trailing task text');
+    return 2;
+  }
+  if (opts['task-file'] && opts.rest.length) {
+    console.error('usage: choose one of --task-file or trailing task text');
+    return 2;
+  }
+  if (opts.prompt != null && opts.rest.length) {
+    console.error('usage: choose one of --prompt or trailing task text');
+    return 2;
+  }
+  const taskText = opts['task-file']
+    ? readFileSync(opts['task-file'], 'utf8')
+    : opts.prompt ?? opts.rest.join(' ');
+  if (!taskText.trim()) {
+    console.error('empty task: pass --task-file, --prompt, or the task as arguments');
+    return 2;
+  }
+
   // Recursion guard FIRST — core-owned, env handshake.
   let state = loadState(getBullswarmDir());
   try {
@@ -166,15 +194,6 @@ async function cmdRun(opts) {
     subscription: poolView.subscription ?? connector.subscription ?? null,
   };
 
-  // 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(getBullswarmDir(), 'runs');
   mkdirSync(runDir, { recursive: true });

package/src/help.js

@@ -35,7 +35,7 @@ const HELP = {
     'retire-legacy': { _text: leaf('bullswarm integrate retire-legacy --yes [--json]',
       'Recoverably archive the retired Claude offload skill.') },
   },
-  run: { _text: leaf('bullswarm run --lane <analyze|build|chore> --add-dir <dir> (--task-file <file> | --prompt <text>) [options]',
+  run: { _text: leaf('bullswarm run --lane <analyze|build|chore> --add-dir <dir> (--task-file <file> | --prompt <text> | <task text...>) [options]',
     'Options: --effort <high|medium|low>, --timeout <seconds>, --json. Routes one task and verifies its content.') },
   health: { _text: leaf('bullswarm health [--json]', 'Re-judge saved outputs and report failed gates or quarantine clusters.') },
   pools: { _text: leaf('bullswarm pools [--force] [--json]', 'Show live meter, quota-surplus, burst-gate, and quarantine state.') },
@@ -100,7 +100,7 @@ Run bullswarm workflow <command> --help for complete command options.`),
     inspect: { _text: leaf('bullswarm workflow inspect <file-or-name>') },
     tui: { _text: leaf('bullswarm workflow tui [<runId>] [--json] [--all] [--show <runId>] [--cancel <runId>]',
       'Interactive mode opens a full-screen phase → agent → step/detail browser. Up/down selects, Enter drills in, Esc goes back, q detaches without stopping work, and c requests explicit cancellation confirmation.') },
-    watch: { _text: leaf('bullswarm workflow watch <runId> [--interval <seconds>] [--heartbeat <seconds>] [--jsonl] [--once]') },
+    watch: { _text: leaf('bullswarm workflow watch <runId> [--interval <seconds>] [--heartbeat <seconds>] [--jsonl] [--once] [--verbose]', 'Human output is compact by default; --verbose preserves per-agent action details.') },
     events: { _text: leaf('bullswarm workflow events <runId> [--after <sequence>] [--json]') },
     steer: { _text: leaf('bullswarm workflow steer <runId> --message <guidance> [--json]') },
     action: {

package/src/lib/release.js

@@ -25,17 +25,18 @@ export function bumpVersion(version, kind) {
   return `${maj}.${min}.${pat}`;
 }
 
-function git(args) {
-  return execSync(`git ${args}`, { cwd: REPO_ROOT, encoding: 'utf8' }).trim();
+function git(args, repoRoot = REPO_ROOT) {
+  return execSync(`git ${args}`, { cwd: repoRoot, encoding: 'utf8' }).trim();
 }
 
-export function release(kind, { dryRun = false } = {}) {
-  const pkg = JSON.parse(readFileSync(PKG_PATH, 'utf8'));
+export function release(kind, { dryRun = false, repoRoot = REPO_ROOT } = {}) {
+  const pkgPath = repoRoot === REPO_ROOT ? PKG_PATH : join(repoRoot, 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, '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');
+  const status = git('status --porcelain', repoRoot);
   if (status.trim()) {
     throw new Error(
       `working tree is dirty — commit first before releasing:\n${status}`,
@@ -47,9 +48,9 @@ export function release(kind, { dryRun = false } = {}) {
   }
 
   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}"`);
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  git('add package.json', repoRoot);
+  git(`commit -m "release v${next}"`, repoRoot);
+  git(`tag -a v${next} -m "v${next}"`, repoRoot);
   return { from: prev, to: next, tag: `v${next}`, dryRun: false };
 }

package/src/lib/watch.js

@@ -223,7 +223,7 @@ function matchLikelyAuthFailure(connector, text) {
   const line = lower.slice(lineStart, lineEnd < 0 ? lower.length : lineEnd).trim();
   // A semantic result may legitimately discuss auth handling. Require the
   // matched line to look like a provider failure instead of source/report text.
-  const errorShaped = /^(?:error|fatal)(?:\b|:)|^(?:authentication failed|not authenticated|invalid api key|rate limit(?:ed| exceeded)?|cmd login)(?:[.!:]|$)|\b(?:http\s*(?:401|403|429)|status\s*(?:401|403|429)|login required|please login|access denied|quota exceeded)\b/i.test(line);
+  const errorShaped = /^(?:error|fatal)(?:\b|:)|^(?:authentication failed|failed to authenticate|not authenticated|invalid api key|rate limit(?:ed| exceeded)?|cmd login)(?:[.!:]|$)|\b(?:http\s*(?:401|403|429)|status\s*(?:401|403|429)|login required|please login|access denied|quota exceeded)\b/i.test(line);
   return errorShaped ? hit : null;
 }
 

package/src/setup.js

@@ -184,6 +184,14 @@ export function upgradeConnectorMetadata(bullswarmDir) {
           changed = true;
         }
       }
+      if (Array.isArray(packaged.authSignatures)) {
+        const existing = Array.isArray(installed.authSignatures) ? installed.authSignatures : [];
+        const merged = [...new Set([...existing, ...packaged.authSignatures])];
+        if (JSON.stringify(merged) !== JSON.stringify(existing)) {
+          installed.authSignatures = merged;
+          changed = true;
+        }
+      }
       if (installed.model == null && packaged.model != null) {
         installed.model = packaged.model;
         changed = true;

package/src/strategy-cli.js

@@ -262,6 +262,7 @@ export async function cmdStrategy(args, { bullswarmDir }) {
     throw new Error(strategyUsage());
   } catch (err) {
     console.error(`✗ ${err.message}`);
-    return 1;
+    const usage = /^(usage:|missing |assignment needs |--apply changes|strategy (?:apply|auto off) changes|refresh-hours must be|.* must be a non-negative number|unknown phase|unknown command|unknown pool)/i.test(err.message);
+    return usage ? 2 : 1;
   }
 }

package/src/workflow/cli.js

@@ -310,6 +310,26 @@ export function shouldAutoWatchGoal(opts) {
     opts.json !== true && opts.resume == null && opts.request == null;
 }
 
+export function applyResumeOrchestratorOverride(doc, requested) {
+  if (!requested) return doc;
+  const pool = requested === 'auto' ? null : requested;
+  doc.intent ??= {};
+  doc.orchestration ??= {};
+  doc.intent.requestedOrchestrator = pool ?? 'auto';
+  doc.orchestration.requestedPool = pool;
+  doc.orchestration.selection = pool
+    ? 'user-pinned-for-testing'
+    : 'capability-strategy-and-quota';
+  for (const phase of doc.phases ?? []) {
+    for (const step of phase.steps ?? []) {
+      if (step.type !== 'decide') continue;
+      if (pool) step.pool = pool;
+      else delete step.pool;
+    }
+  }
+  return doc;
+}
+
 async function wfGoal(opts) {
   if (opts.help) {
     console.log(goalUsage());
@@ -340,6 +360,7 @@ async function wfGoal(opts) {
       console.error(`✗ cannot load durable workflow for ${resumeRunId}: ${err.message}`);
       return 1;
     }
+    applyResumeOrchestratorOverride(doc, opts.orchestrator);
   } else if (opts.request) {
     try {
       const request = JSON.parse(readFileSync(resolve(opts.request), 'utf8'));
@@ -488,7 +509,7 @@ function wfEvents(opts) {
 async function wfWatch(opts) {
   const token = opts.rest[0];
   if (!token) {
-    console.error('usage: bullswarm workflow watch <runId> [--interval <seconds>] [--heartbeat <seconds>] [--jsonl] [--once]');
+    console.error('usage: bullswarm workflow watch <runId> [--interval <seconds>] [--heartbeat <seconds>] [--jsonl] [--once] [--verbose]');
     return 2;
   }
   const intervalSec = Number(opts.interval ?? 2);
@@ -504,6 +525,7 @@ async function wfWatch(opts) {
       heartbeatMs: heartbeatSec * 1000,
       once: opts.once === true,
       jsonl: opts.jsonl === true,
+      verbose: opts.verbose === true,
     });
   } catch (err) {
     console.error(`✗ ${err.message}`);

package/src/workflow/draft-cli.js

@@ -107,7 +107,9 @@ function jsonOut(obj, opts) {
   if (opts.json) console.log(JSON.stringify(obj, null, 2));
 }
 
-function err(msg) { console.error(msg); return 1; }
+function err(msg, code = 1) { console.error(msg); return code; }
+
+function usageErr(msg) { return err(msg, 2); }
 
 // --- subcommand dispatch ---------------------------------------------------
 
@@ -173,7 +175,7 @@ async function livePoolNames() {
 
 function draftCreate(opts) {
   const [name] = opts._positional;
-  if (!name) return err('usage: bullswarm workflow draft create <name>');
+  if (!name) return usageErr('usage: bullswarm workflow draft create <name>');
   if (draftExists(BULLSWARM_DIR(), name)) {
     return err(`draft "${name}" already exists (delete it first or use 'show')`);
   }
@@ -206,7 +208,7 @@ function draftCreate(opts) {
 
 function draftShow(opts) {
   const [name] = opts._positional;
-  if (!name) return err('usage: bullswarm workflow draft show <name>');
+  if (!name) return usageErr('usage: bullswarm workflow draft show <name>');
   const { doc, meta } = loadDraft(BULLSWARM_DIR(), name);
   if (opts.json) {
     jsonOut({ doc, meta }, opts);
@@ -247,7 +249,7 @@ function draftList(opts) {
 function draftPhase(opts) {
   const [action, name, phaseName] = opts._positional;
   if (!action || !name || !phaseName) {
-    return err('usage: bullswarm workflow draft phase <add|remove> <draft> <phase>');
+    return usageErr('usage: bullswarm workflow draft phase <add|remove> <draft> <phase>');
   }
   if (action === 'add') {
     if (!draftExists(BULLSWARM_DIR(), name)) return err(`draft "${name}" does not exist`);
@@ -266,13 +268,13 @@ function draftPhase(opts) {
     else { console.log(`✓ removed phase "${phaseName}" from draft "${name}"`); reportValidation(r.validation); }
     return r.validation?.ok === false ? 1 : 0;
   }
-  return err(`unknown phase action "${action}"`);
+  return usageErr(`unknown phase action "${action}"`);
 }
 
 function draftStep(opts) {
   const [action, name, phaseName, stepId] = opts._positional;
   if (!action || !name || !phaseName || !stepId) {
-    return err('usage: bullswarm workflow draft step <add|remove|set> <draft> <phase> <step-id> [options]');
+    return usageErr('usage: bullswarm workflow draft step <add|remove|set> <draft> <phase> <step-id> [options]');
   }
   if (action === 'add') {
     const f = opts._flags;
@@ -314,8 +316,8 @@ function draftStep(opts) {
   }
   if (action === 'set') {
     const field = opts._positional[4];
-    if (!field) return err('usage: bullswarm workflow draft step set <draft> <phase> <step> <field> --value <text>');
-    if (!f_has(opts._flags, 'value')) return err('missing --value');
+    if (!field) return usageErr('usage: bullswarm workflow draft step set <draft> <phase> <step> <field> --value <text>');
+    if (!f_has(opts._flags, 'value')) return usageErr('missing --value');
     const r = setStepField(BULLSWARM_DIR(), name, {
       phaseName, stepId, field, value: opts._flags.value,
     });
@@ -323,7 +325,7 @@ function draftStep(opts) {
     else { console.log(`✓ set ${field} on step "${stepId}" in draft "${name}"`); reportValidation(r.validation); }
     return r.validation?.ok === false ? 1 : 0;
   }
-  return err(`unknown step action "${action}"`);
+  return usageErr(`unknown step action "${action}"`);
 }
 
 function f_has(flags, name) {
@@ -332,8 +334,8 @@ function f_has(flags, name) {
 
 function draftSet(opts) {
   const [name, field] = opts._positional;
-  if (!name || !field) return err('usage: bullswarm workflow draft set <draft> <field> --value <text>');
-  if (!f_has(opts._flags, 'value')) return err('missing --value');
+  if (!name || !field) return usageErr('usage: bullswarm workflow draft set <draft> <field> --value <text>');
+  if (!f_has(opts._flags, 'value')) return usageErr('missing --value');
   const r = setField(BULLSWARM_DIR(), name, { field, value: opts._flags.value });
   if (opts.json) jsonOut({ ok: true, action: 'set', name, field, validation: r.validation }, opts);
   else { console.log(`✓ set ${field} on draft "${name}"`); reportValidation(r.validation); }
@@ -342,7 +344,7 @@ function draftSet(opts) {
 
 async function draftValidate(opts) {
   const [name] = opts._positional;
-  if (!name) return err('usage: bullswarm workflow draft validate <name>');
+  if (!name) return usageErr('usage: bullswarm workflow draft validate <name>');
   if (!draftExists(BULLSWARM_DIR(), name)) return err(`draft "${name}" does not exist`);
   const { doc } = loadDraft(BULLSWARM_DIR(), name);
   const { names } = await livePoolNames();
@@ -371,7 +373,7 @@ async function draftValidate(opts) {
 
 function draftExport(opts) {
   const [name, outFile] = opts._positional;
-  if (!name || !outFile) return err('usage: bullswarm workflow draft export <name> <out-file>');
+  if (!name || !outFile) return usageErr('usage: bullswarm workflow draft export <name> <out-file>');
   if (!draftExists(BULLSWARM_DIR(), name)) return err(`draft "${name}" does not exist`);
   const { outPath } = exportDraft(BULLSWARM_DIR(), name, outFile);
   if (opts.json) jsonOut({ ok: true, name, outPath }, opts);
@@ -381,10 +383,10 @@ function draftExport(opts) {
 
 function draftDelete(opts) {
   const [name] = opts._positional;
-  if (!name) return err('usage: bullswarm workflow draft delete <name>');
+  if (!name) return usageErr('usage: bullswarm workflow draft delete <name>');
   if (!f_has(opts._flags, 'yes') && !opts._flags.y) {
     // Refuse without --yes for safety.
-    return err(`refusing to delete draft "${name}" without --yes`);
+    return usageErr(`refusing to delete draft "${name}" without --yes`);
   }
   const ok = deleteDraft(BULLSWARM_DIR(), name);
   if (opts.json) jsonOut({ ok, name }, opts);
@@ -394,7 +396,7 @@ function draftDelete(opts) {
 
 async function draftRun(opts) {
   const [name] = opts._positional;
-  if (!name) return err('usage: bullswarm workflow draft run <name> [--input k=v]...');
+  if (!name) return usageErr('usage: bullswarm workflow draft run <name> [--input k=v]...');
   if (!draftExists(BULLSWARM_DIR(), name)) return err(`draft "${name}" does not exist`);
   // Build a synthetic path inside the drafts dir so the existing
   // loadWorkflow + runWorkflow paths work without modification.

package/src/workflow/goal.js

@@ -11,6 +11,7 @@ export const AUTONOMOUS_ORCHESTRATOR_PROMPT = [
   'You are the autonomous orchestrator for the user goal in the durable workflow context.',
   'Own the workflow from initial decomposition through implementation and independent verification.',
   'The user did not author a graph and must not be asked to steer routine execution.',
+  'This is a control-plane decision thread, not a worker assignment. Do not invoke Bullswarm, run shell commands, call tools, or modify repository files. Use only the durable context supplied below and return the requested decision JSON; delegate all inspection, implementation, and verification as bounded actions.',
   '',
   'At every checkpoint:',
   '1. Observe the intent, completed actions, artifacts, failures, verification results, available capabilities, and remaining budget.',

package/src/workflow/runner.js

@@ -213,6 +213,13 @@ export async function runWorkflow(opts) {
   // Always keep a reference to the doc on the state so the runtime can
   // enforce inputs.<k>.required (R-run-time-required).
   state._doc = doc;
+  if (resuming) {
+    state.intent = doc.intent ?? state.intent;
+    state.orchestration = doc.orchestration
+      ? { ...(state.orchestration ?? {}), ...doc.orchestration }
+      : state.orchestration;
+    writeFileSync(join(runDir, 'workflow.json'), `${JSON.stringify(doc, null, 2)}\n`);
+  }
   if (opts.inputs && Object.keys(opts.inputs).length) {
     state.inputs = { ...state.inputs, ...opts.inputs };
   }

package/src/workflow/runs-cli.js

@@ -20,7 +20,7 @@ import { BULLSWARM_DIR } from './cli.js';
 import { buildWorkflowResult } from './result.js';
 
 function jsonOut(obj, opts) { if (opts.json) console.log(JSON.stringify(obj, null, 2)); }
-function err(msg) { console.error(msg); return 1; }
+function err(msg, code = 1) { console.error(msg); return code; }
 
 export function cmdRuns(args) {
   const opts = parseRunsFlags(args);
@@ -89,7 +89,7 @@ function runsList(opts) {
   try {
     initiatedRange = resolveInitiatedRange(opts);
   } catch (error) {
-    return err(error.message);
+    return err(error.message, 2);
   }
   const all = listRuns(BULLSWARM_DIR());
   let filtered = all;
@@ -165,7 +165,7 @@ function runsList(opts) {
 }
 
 function runsShow(idToken, opts) {
-  if (!idToken) return err('usage: bullswarm workflow runs show <id>');
+  if (!idToken) return err('usage: bullswarm workflow runs show <id>', 2);
   const resolved = resolveRunId(BULLSWARM_DIR(), idToken);
   if (!resolved) return err(`no run found for "${idToken}"`);
 
@@ -195,7 +195,7 @@ function runsShow(idToken, opts) {
 }
 
 function runsResult(idToken, opts) {
-  if (!idToken) return err('usage: bullswarm workflow runs result <id> [--json]');
+  if (!idToken) return err('usage: bullswarm workflow runs result <id> [--json]', 2);
   const resolved = resolveRunId(BULLSWARM_DIR(), idToken);
   if (!resolved) return err(`no run found for "${idToken}"`);
 
@@ -248,8 +248,8 @@ function runsResult(idToken, opts) {
 const MAX_HUMAN_RESULT_CHARS = 64 * 1024;
 
 function runsDelete(idToken, opts, rest) {
-  if (!idToken) return err('usage: bullswarm workflow runs delete <id> --yes');
-  if (!opts.yes) return err(`refusing to delete run "${idToken}" without --yes`);
+  if (!idToken) return err('usage: bullswarm workflow runs delete <id> --yes', 2);
+  if (!opts.yes) return err(`refusing to delete run "${idToken}" without --yes`, 2);
   const resolved = resolveRunId(BULLSWARM_DIR(), idToken);
   if (!resolved) return err(`no run found for "${idToken}"`);
 

package/src/workflow/watch-cli.js

@@ -7,6 +7,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveRunId } from './short-id.js';
 import { readSteering } from './steering.js';
+import { readEvents } from './events.js';
 import { isDeliveredWorkflowStatus, isTerminalWorkflowStatus } from './status.js';
 
 function readJson(path) {
@@ -81,6 +82,7 @@ export function watchSnapshot(runDir, state, now = new Date()) {
     tokens: state.usage?.tokens?.totalKnown ?? null,
     pendingSteering: queuedSteering.length,
     deliveredSteering: state.steering?.length ?? 0,
+    quietForSec: 0,
     agents: Object.values(state.activeAgents ?? {}).map((agent) => ({
       stepId: agent.stepId,
       pool: agent.pool ?? null,
@@ -119,9 +121,37 @@ export function snapshotFingerprint(snapshot) {
   });
 }
 
-export function renderWatchSnapshot(snapshot, { heartbeat = false } = {}) {
+function humanTransitionFingerprint(snapshot) {
+  return JSON.stringify({
+    status: snapshot.status,
+    stage: snapshot.stage,
+    phase: snapshot.phase,
+    step: snapshot.step,
+    dispatchesUsed: snapshot.dispatchesUsed,
+    pendingSteering: snapshot.pendingSteering,
+    agents: snapshot.agents.map((agent) => ({
+      stepId: agent.stepId,
+      pool: agent.pool,
+      model: agent.model,
+      status: agent.status,
+      stall: agent.stall,
+    })),
+  });
+}
+
+export function renderWatchSnapshot(snapshot, { heartbeat = false, verbose = false, events = [] } = {}) {
   const target = snapshot.dispatchTarget == null ? '∞' : snapshot.dispatchTarget;
   const location = [snapshot.phase, snapshot.step].filter(Boolean).join('/') || 'starting';
+  if (!verbose) {
+    const actions = events.filter((event) => event.type === 'attempt.agent_action').length;
+    const line = `${snapshot.terminal ? '■' : heartbeat ? '♡' : '●'} +${formatDuration(snapshot.elapsedSec)} ` +
+      `${snapshot.status}/${snapshot.stage ?? '?'} ${location} · ${events.length} events, ${actions} actions · ` +
+      `quiet ${formatDuration(snapshot.quietForSec)}`;
+    if (snapshot.terminal && snapshot.timing) {
+      return `${line}\n  timing: ${snapshot.timing.attempts.length} attempts in ${formatDuration(snapshot.timing.workflowElapsedSec)}`;
+    }
+    return line;
+  }
   const marker = snapshot.terminal ? '■' : heartbeat ? '♡' : '●';
   const lines = [
     `${marker} +${formatDuration(snapshot.elapsedSec)} ${snapshot.status}/${snapshot.stage ?? '?'} ` +
@@ -152,6 +182,7 @@ export async function runWorkflowWatch(bullswarmDir, token, {
   heartbeatMs = 60000,
   once = false,
   jsonl = false,
+  verbose = false,
   output = process.stdout,
 } = {}) {
   const resolved = resolveRunId(bullswarmDir, token);
@@ -159,21 +190,71 @@ export async function runWorkflowWatch(bullswarmDir, token, {
   const statePath = join(resolved.runDir, 'state.json');
   if (!existsSync(statePath)) throw new Error(`run "${token}" has no state.json`);
   let priorFingerprint = null;
+  let priorHumanFingerprint = null;
   let lastPrintedAt = 0;
+  let priorSequence = null;
+  let pendingEvents = [];
+  let lastActivityAt = null;
   while (true) {
     const state = readJson(statePath);
     if (state) {
       const snapshot = watchSnapshot(resolved.runDir, state);
+      if (priorSequence == null) {
+        // A newly attached watcher has no preceding interval. Start at the
+        // durable high-water mark instead of replaying the run lifetime.
+        priorSequence = state.eventSequence ?? 0;
+        lastActivityAt = Math.max(
+          Date.parse(state.lastEvent?.committedAt ?? '') || 0,
+          Date.parse(state.finishedAt ?? '') || 0,
+          ...Object.values(state.attempts ?? []).map((attempt) => Math.max(
+            Date.parse(attempt.lastActivityAt ?? '') || 0,
+            Date.parse(attempt.lastHeartbeatAt ?? '') || 0,
+            Date.parse(attempt.finishedAt ?? '') || 0,
+          )),
+          ...Object.values(state.activeAgents ?? {}).map((agent) => Math.max(
+            Date.parse(agent.lastActivityAt ?? '') || 0,
+            Date.parse(agent.lastActionAt ?? '') || 0,
+            Date.parse(agent.startedAt ?? '') || 0,
+          )),
+          Date.parse(state.startedAt ?? '') || Date.now(),
+        );
+      }
+      const newEvents = readEvents(resolved.runDir, { after: priorSequence });
+      if (newEvents.length) {
+        pendingEvents.push(...newEvents);
+        lastActivityAt = Math.max(
+          lastActivityAt,
+          ...newEvents.map((event) => Date.parse(event.committedAt ?? '') || Date.now()),
+        );
+        priorSequence = newEvents.at(-1)?.sequence ?? state.eventSequence ?? priorSequence;
+      }
+      snapshot.quietForSec = Math.max(0, Math.floor((Date.now() - lastActivityAt) / 1000));
       const fingerprint = snapshotFingerprint(snapshot);
+      const humanFingerprint = humanTransitionFingerprint(snapshot);
       const heartbeat = Date.now() - lastPrintedAt >= heartbeatMs;
-      if (fingerprint !== priorFingerprint || heartbeat || once) {
+      const changed = jsonl || verbose
+        ? fingerprint !== priorFingerprint
+        : humanFingerprint !== priorHumanFingerprint;
+      if (changed || heartbeat || once) {
         output.write(jsonl
           ? `${JSON.stringify({ type: heartbeat && fingerprint === priorFingerprint ? 'heartbeat' : 'progress', ...snapshot })}\n`
-          : `${renderWatchSnapshot(snapshot, { heartbeat: heartbeat && fingerprint === priorFingerprint })}\n`);
+          : `${renderWatchSnapshot(snapshot, {
+            heartbeat: heartbeat && !changed,
+            verbose,
+            events: pendingEvents,
+          })}\n`);
         priorFingerprint = fingerprint;
+        priorHumanFingerprint = humanFingerprint;
         lastPrintedAt = Date.now();
+        pendingEvents = [];
+      }
+      if (snapshot.terminal || once) {
+        if (!jsonl && snapshot.terminal) {
+          output.write(`outcome: ${snapshot.status}\n`);
+          output.write(`next: bullswarm workflow runs result ${snapshot.shortId ?? snapshot.runId} --json\n`);
+        }
+        return isDeliveredWorkflowStatus(snapshot.status) || once ? 0 : 1;
       }
-      if (snapshot.terminal || once) return isDeliveredWorkflowStatus(snapshot.status) || once ? 0 : 1;
     }
     await new Promise((resolve) => setTimeout(resolve, Math.max(100, intervalMs)));
   }