bullswarm 0.10.2 → 0.10.4

package/AGENTS.md

@@ -37,7 +37,7 @@ content. Published as `bullswarm` on npm.
 ## Development
 
 ```bash
-npm test            # 232 tests, no network needed (meters read from cache)
+npm test            # 256 tests, no network needed (meters read from cache)
 node bin/bullswarm.js doctor --json   # readiness report
 node bin/bullswarm.js workflow list   # discover workflows
 node bin/bullswarm.js workflow runs   # ongoing workflow instances

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # bullswarm changelog
 
+## 0.10.4 — durable interactive workflow viewer
+
+- Added `workflow runs result <id> [--json]`, a stable
+  `bullswarm.workflow.result.v1` handoff for parent agents. It selects the final
+  successful delivery rather than the last orchestrator response, pairs it with
+  its dependent verification verdict, and reports progress, step logs, token
+  usage, and honest complete-or-partial tool-call counts.
+- Goal launches now return and print a four-part operating handoff for agentic
+  inspection, low-noise watching, the human TUI, and terminal result retrieval.
+- Plain `workflow goal` now launches independently, prints that handoff, and
+  returns. The new explicit `--watch` flag follows low-noise progress until the
+  terminal state; the human TUI is opened from the printed command.
+- `--foreground` retains terminal-owned execution and `--detach` remains an
+  explicit backward-compatible spelling of the new default.
+- Rebuilt interactive workflow inspection as a responsive Phase → Agent →
+  Agent-activity browser: desktop uses two contextual panes while mobile and
+  narrow SSH terminals use one full-width level. It includes arrow/Enter/Esc
+  navigation, numbered semantic actions, active-agent following, scrolling,
+  completed-agent outcomes, total semantic-action counts, terminal agent
+  progress, resize handling, safe detach, and confirmed stopping.
+- Made the autonomous orchestrator a compact selectable control-plane panel
+  stacked above the phase tree. Arrow/Enter or `o` opens its
+  durable session, checkpoint decisions, semantic
+  activity, usage, prompt, outcomes, and artifacts without counting planner
+  turns as phase workers.
+- Standardized workflow TUI state marks across orchestrator, phases, agents,
+  and semantic activity: `○` pending, animated Braille spinner active, `⧖`
+  waiting, `✓` complete, and `✗` failed or interrupted.
+- Made `maxExpansionRounds` an advisory convergence target instead of a hard
+  failure boundary. Near the target the orchestrator is told to consolidate
+  existing evidence and avoid marginal expansion; essential bounded work may
+  exceed it and the overage is recorded.
+- Added truthful qualified terminal outcomes: planner `stop` now yields
+  `completed_with_concerns` with a ready best-effort delivery when useful work
+  exists, or `blocked` when it does not. Result envelopes expose `verified`,
+  the stopping reason, and unresolved concerns without relabeling failed
+  verification as success.
+- Made phase and agent status derive from semantic output verdicts, so a
+  verifier process that successfully returns `ok:false` is displayed as a
+  failed verification rather than a completed check.
+- Added persisted `strategy exclude-model` / `include-model` policy. Excluded
+  models are removed from strategy recommendations and dispatch assignments;
+  connectors pin an allowed same-tier fallback or become ineligible when they
+  cannot guarantee the exclusion.
+- Let the CLI process drain stdout before exiting, preventing large
+  `workflow tui --json` snapshots from being truncated around the platform
+  pipe-buffer boundary.
+- Expanded `workflow --help` into an operational map for building, observing,
+  controlling, and auditing workflows.
+
+## 0.10.3 — contextual help everywhere
+
+- Added side-effect-free `-h` / `--help` handling for the top-level CLI and
+  every command and nested subcommand, including workflow drafts, run history,
+  approvals, actions, integrations, and strategy policy controls.
+- Added a centralized command help tree so contextual help is consistent and
+  intercepted before setup, provider discovery, state writes, or destructive
+  command execution.
+
 ## 0.10.2 — cross-agent skill integration
 
 - Added explicit `bullswarm integrate status|install|remove` support for Codex,

package/README.md

@@ -5,6 +5,24 @@ orchestrator, build and expand the plan, route bounded worker actions by quota,
 verify the result, and finish without an initiating agent authoring a graph.
 Every delegate output is judged by content before it counts.
 
+Every command and nested subcommand supports contextual `-h` / `--help`
+without initializing state or executing the command:
+
+```bash
+bullswarm --help
+bullswarm workflow run --help
+bullswarm workflow draft step add --help
+```
+
+`workflow goal` launches a durable background runner, prints operating commands,
+and returns by default. Add `--watch` to immediately follow low-noise progress
+until terminal, or `--foreground` to keep execution owned by the initiating
+terminal. Open the full-screen Phase → Agent → Activity viewer at any time with
+`bullswarm workflow tui <shortId>`; use Up/Down, Enter, Esc, and `q` to detach.
+Wide terminals use two
+contextual panes (phases + agents, then agents + activity); narrow and mobile
+terminals give each level the full screen automatically.
+
 ## The doctrine (non-negotiable)
 
 1. **Judge by CONTENT, not exit code.** Every delegate CLI can exit 0 while
@@ -79,6 +97,7 @@ bullswarm strategy auto status
 bullswarm strategy set-subscription command-code \
   --plan GOAT --monthly-usd 10 --included-usd 70 --quota-window monthly
 bullswarm strategy assign high --pool claude-code --model claude-opus-4-6
+bullswarm strategy exclude-model claude-fable-5
 bullswarm run --effort high --lane analyze --task-file /tmp/task.md --json
 ```
 
@@ -94,6 +113,12 @@ prices, and benchmarks stay `null` rather than being guessed. An assignment is
 only a preference: quarantine, exhaustion, burst gates, and capability checks
 still win.
 
+Model exclusions are hard routing policy. An excluded model is removed from
+recommendations and assignments, and Bullswarm pins a same-tier allowed model
+through the connector-owned model flag whenever the provider default could be
+excluded. A pool that cannot guarantee the exclusion is ineligible for that
+dispatch. Reverse the policy with `bullswarm strategy include-model <model>`.
+
 Every run and workflow attempt reports its selected agent/model and estimated
 usage. When a delegate does not expose counters, Bullswarm labels its UTF-8
 byte/4 token estimate. The breakdown separates standard read, cache read,
@@ -107,26 +132,33 @@ phase/step/attempt tree.
 For normal multi-step work, give Bullswarm the goal—not a JSON graph:
 
 ```bash
-# Foreground: streams progress and returns when terminal.
+# Default: starts independently, prints observation/result commands, and returns.
 bullswarm workflow goal \
   "Fix the failing tests with the smallest correct change and verify them" \
   --cwd ~/some-repo
 
-# Detached: the initiating CLI exits; the workflow continues independently.
+# Follow low-noise semantic progress immediately after launch.
 bullswarm workflow goal \
   "Audit and repair the parser, then run its acceptance tests" \
-  --cwd ~/some-repo --detach --json
+  --cwd ~/some-repo --watch
 ```
 
 Bullswarm first honors an approved high-tier provider/model assignment when it
 remains eligible, otherwise it selects an eligible `workflow-planning`
-orchestrator by live quota surplus. The orchestrator observes durable evidence, proposes bounded actions,
+orchestrator by live quota surplus. The orchestrator is one durable control-plane
+conversation: Grok and Claude resume the same provider session at later
+checkpoints, while Bullswarm keeps each turn separately auditable for routing,
+usage, and recovery. It observes durable evidence, proposes bounded actions,
 and decides when another expansion or verification is necessary. Bullswarm
 validates the proposal, owns agent/process selection, routes workers, and calls
 the orchestrator again until completion, cancellation, failure, approval, or a
 hard graph-growth safeguard. No initial phases, prompts, JSON schema, or agent choice are
 required from the user.
 
+Planner actions carry forward-only kebab-case phase names. A finished phase is
+sealed: later planner turns must create a new phase for repair or verification,
+so the TUI cannot jump backward or append work beneath a completed phase.
+
 The detached response includes a short ID and exact observation commands:
 
 ```bash
@@ -146,8 +178,9 @@ bullswarm workflow goal --resume <shortId> --json
 
 `--orchestrator <pool>` exists for controlled testing; ordinary use should
 leave selection on `auto`. `--max-agents` and `--max-workflow-seconds` are
-advisory planning targets; hard graph-growth safeguards are adjusted with
-`--max-expansion-rounds`, `--max-actions`, and `--max-items-per-expansion`.
+advisory planning targets; `--max-expansion-rounds` is also an advisory
+convergence target. Hard structural safeguards are adjusted with
+`--max-actions` and `--max-items-per-expansion`.
 Interactive setup also records a worktree-isolation
 preference (`agent-decides`, `off`, or `required`); Bullswarm communicates that
 policy to the orchestrator without imposing repository topology itself.
@@ -196,6 +229,7 @@ bullswarm workflow runs --historical --since yesterday --until today
 bullswarm workflow runs --all --from 2026-08-20 --to 2026-08-27
 bullswarm workflow runs --limit 20         # cap the result count
 bullswarm workflow runs show <shortId>     # state + report + summary
+bullswarm workflow runs result <shortId> --json  # stable result for the calling agent
 bullswarm runs show <shortId>              # top-level shorthand
 bullswarm workflow runs delete <shortId> --yes    # remove the run dir
 
@@ -208,6 +242,19 @@ Run-history time filters always compare when the workflow was initiated
 exclusive; `--started-after`/`--from` and `--started-before`/`--to` are aliases.
 Values accept ISO timestamps, local `YYYY-MM-DD` dates, `today`, `yesterday`,
 `tomorrow`, `now`, or relative durations such as `30m`, `24h`, `7d`, and `2w`.
+
+After a workflow reaches a terminal state, agents should consume
+`workflow runs result <id> --json` instead of probing `state.json`, task files,
+or provider-specific output. The versioned `bullswarm.workflow.result.v1`
+envelope identifies the final delivery artifact and its matching verification
+verdict, and includes progress, step logs, tokens, and an explicitly
+complete-or-partial tool-call total. `runs show` remains the low-level debugging
+surface.
+Goal launch output includes an `instructions` handoff with four named paths:
+`agentInspect` for a machine-readable snapshot, `watch` for low-noise progress,
+`humanTui` for the interactive browser, and `result` for the terminal delivery.
+Use `--watch` when the initiating terminal should immediately follow progress;
+otherwise the command returns after printing this handoff.
 Time filters preserve the existing scope, so use `--all` or `--historical` when
 auditing completed runs.
 
@@ -225,9 +272,20 @@ bullswarm workflow watch <shortId> --jsonl       # automation-friendly stream
 bullswarm workflow watch <shortId> --once        # one current/terminal snapshot
 ```
 
-`workflow tui` is the interactive, Claude-style `/workflows` view. It watches
-ongoing runs from disk and supports `j`/`k` or arrow-key selection, Enter for
-details, `c` to request a cooperative stop, `r` to refresh, and `q` to quit.
+`workflow tui` is the interactive, Claude-style `/workflows` view. For an
+autonomous goal its left navigation stacks a compact Orchestrator panel above
+the Phases panel; internal planner turns never appear as workers or phases.
+Select Orchestration and press Enter, or press `o`
+anywhere, to inspect the logical orchestration conversation: provider session,
+checkpoint turns and decisions, recent semantic actions, usage, prompt, and
+artifacts. Status marks are consistent throughout the tree: `○` not started,
+an animated Braille spinner for active work, `⧖` waiting, `✓` finished, and
+`✗` failed or interrupted. The non-emoji `⧖` avoids the inconsistent cell
+width of `⌛` across terminal fonts. It watches ongoing runs from disk and supports `j`/`k` or arrow-key selection, Enter for
+details, Esc to go back, `c` to request a confirmed cooperative stop, `r` to
+refresh, and `q` to detach. Its responsive drill-down fits both desktop and
+mobile SSH terminals without squeezing phase, agent, and activity into three
+narrow columns.
 
 ```bash
 bullswarm workflow tui
@@ -272,12 +330,18 @@ declaratively map provider events into a common semantic action record:
 {"id":"provider-action-id","at":"...","kind":"shell_command|read_file|edit|response","status":"running|completed|failed","summary":"safe scalar preview"}
 ```
 
-The live workflow pane retains the latest three logical actions per agent.
+The live workflow pane retains and numbers the latest three logical actions per agent.
 Repeated updates for the same tool call replace its status, and streaming text
 chunks coalesce into one response action. Heartbeats, token/thought deltas,
 usage messages, hooks, and unparsed output remain liveness evidence but do not
-occupy the action pane. Connector-specific flags, paths, and mappings live in
+occupy the action pane. The viewer tracks the total logical-action count so it
+can display `last 3 of N`, and completed-agent detail includes a scrollable
+Outcome read from the durable output artifact. Connector-specific flags, paths, and mappings live in
 `connectors/*.json` under `eventStream`; core contains no provider event names.
+Raw structured stdout is treated as an agent transcript, not a provider error
+channel, so reading source text such as an auth-signature matcher cannot falsely
+quarantine Grok or Command Code. Error-shaped semantic results and stderr
+diagnostics still trigger the auth/quota guard.
 
 After ten minutes without transport, parsed-event, or semantic-action evidence,
 an active child is labeled `suspected_stalled`. This is an inspection signal,
@@ -326,13 +390,22 @@ limits:
 }
 ```
 
-`maxAgents` and `maxWorkflowSeconds` are advisory inputs to the orchestrator.
-Crossing either target is recorded in durable state but never stops a worker,
-skips verification, or fails a run. `maxExpansionRounds`, `maxActions`, and
-`maxItemsPerExpansion` remain hard graph-growth safeguards. Delegates have no
+`maxAgents`, `maxWorkflowSeconds`, and `maxExpansionRounds` are advisory inputs
+to the orchestrator. Approaching them strongly biases the planner toward
+consolidating existing artifacts and returning the best useful outcome;
+crossing them is recorded but never stops a worker, skips verification, or
+fails a run. `maxActions` and `maxItemsPerExpansion` remain hard structural
+safeguards. Reaching one returns a qualified outcome when useful work exists,
+rather than discarding the run as a blanket failure. Delegates have no
 implicit wall-clock timeout; set a step's `timeoutSec` (or direct-run
 `--timeout`) only when an operator explicitly wants a hard termination timer.
 
+An autonomous `complete` remains strictly verified. A planner `stop` produces
+`completed_with_concerns` when a useful delivery exists, including unresolved
+verification concerns and the stopping reason; it produces `blocked` only
+when no useful delivery exists. `workflow runs result` treats the qualified
+delivery as ready while reporting `verified:false`.
+
 The planner returns versioned JSON. It may propose `needs_more_work` with
 bounded `run`, inline-`fanout`, or `verify` actions. The deterministic runtime
 validates IDs, dependencies, operation types, capabilities, and budgets before

package/bin/bullswarm.js

@@ -4,9 +4,9 @@
 import { main } from '../src/cli.js';
 
 main(process.argv.slice(2)).then(
-  (code) => process.exit(code),
+  (code) => { process.exitCode = code; },
   (err) => {
     console.error(err?.message ?? err);
-    process.exit(1);
+    process.exitCode = 1;
   },
 );

package/connectors/claude-code.json

@@ -53,6 +53,10 @@
   "capabilities": ["strong-analysis", "code-reading", "file-editing", "workflow-planning"],
   "knownModels": ["claude-fable-5", "claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5"],
   "modelSelection": { "flag": "--model", "mode": "replace-or-append" },
+  "conversation": {
+    "newArgs": ["--session-id", "{sessionId}"],
+    "resumeArgs": ["--resume", "{sessionId}"]
+  },
   "modelProfiles": [
     { "match": "^claude-fable-5$", "tier": "high", "qualityRank": 6, "pricing": { "inputUsdPerMillion": 10, "cacheReadUsdPerMillion": 1, "outputUsdPerMillion": 50 }, "pricingSource": "https://platform.claude.com/docs/en/about-claude/pricing", "pricingUpdatedAt": "2026-08-27" },
     { "match": "^claude-opus-(5|4-[5-8])$", "tier": "high", "qualityRank": 5, "pricing": { "inputUsdPerMillion": 5, "cacheReadUsdPerMillion": 0.5, "outputUsdPerMillion": 25 }, "pricingSource": "https://platform.claude.com/docs/en/about-claude/pricing", "pricingUpdatedAt": "2026-08-27" },

package/connectors/grok.json

@@ -48,6 +48,10 @@
   "knownModels": ["grok-4.6", "grok-4.5"],
   "model": "grok-4.6",
   "modelSelection": { "flag": "--model", "mode": "replace-or-append" },
+  "conversation": {
+    "newArgs": ["--session-id", "{sessionId}"],
+    "resumeArgs": ["--resume", "{sessionId}"]
+  },
   "modelProfiles": [
     { "match": "^grok-4\\.6$", "tier": "high", "qualityRank": 5, "pricing": { "inputUsdPerMillion": 2, "cacheReadUsdPerMillion": 0.5, "outputUsdPerMillion": 6 }, "pricingSource": "https://docs.x.ai/developers/models/grok-4.6", "pricingUpdatedAt": "2026-08-27" },
     { "match": "^grok-4\\.5$", "tier": "medium", "qualityRank": 4 }

package/package.json

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

@@ -10,6 +10,10 @@ CLI subscription has the most quota headroom. Every delegate output is
 judged by **content**, not exit code. A non-zero exit is never a success; a
 `verified` output is.
 
+Every command and nested subcommand supports side-effect-free `-h` / `--help`.
+When a flag or argument is uncertain, inspect the exact surface before acting,
+for example `bullswarm workflow draft step add --help`.
+
 This skill is registered globally by:
 
 ```bash
@@ -82,16 +86,26 @@ Prefer this for ordinary goal-driven work. The caller supplies intent only:
 ```bash
 bullswarm workflow goal \
   "Fix the failing parser tests with the smallest correct change and verify them" \
-  --cwd=<abs/path/to/repo> --detach --json
+  --cwd=<abs/path/to/repo> --json
 ```
 
 The returned JSON contains `runId`, `shortId`, logs, and exact observation
-commands. Bullswarm chooses a capable orchestrator by quota surplus, supplies
+commands. Its `instructions` object separates `agentInspect`, low-noise `watch`,
+interactive `humanTui`, and terminal `result` retrieval. Bullswarm chooses a capable orchestrator by quota surplus, supplies
 the internal planning contract, validates every proposed graph expansion,
 routes workers independently, requires verification evidence, and replans until
 a truthful terminal state. The initiating agent does not create phases, action
 IDs, dependency JSON, planner prompts, or pool assignments.
 
+The autonomous orchestrator is one durable control-plane conversation, separate
+from execution phases. Connectors that declare conversation continuation (Grok
+and Claude Code) resume the provider session at later evidence checkpoints;
+individual turns remain visible in JSON audit state for spend and recovery, but
+the human TUI displays one orchestrator thread rather than several agents.
+Planner-created actions also have forward-only named phases. Once a phase has
+executed, a later turn must use a new phase name; Bullswarm rejects attempts to
+append new work beneath a completed phase.
+
 Observe from any other shell or agent:
 
 ```bash
@@ -102,6 +116,13 @@ bullswarm workflow events --json <shortId> --after 0
 bullswarm workflow action show --json <shortId> <actionId>
 ```
 
+`workflow goal` starts the durable runner in the background, prints operating
+instructions, and returns by default. Add `--watch` to immediately follow
+low-noise progress until terminal. Open the full-screen Phase → Agent →
+Agent-steps viewer with the printed `humanTui` command; Up/Down, Enter, Esc, and
+`q` navigate or detach while work continues. `--foreground` explicitly restores
+terminal-owned execution.
+
 The detached runner does not depend on the initiating CLI remaining alive.
 Resume a process-interrupted run from its persisted definition with
 `bullswarm workflow goal --resume <shortId> --json`. Leave orchestrator
@@ -179,6 +200,7 @@ bullswarm workflow runs --name <workflow>     # filter by workflow name
 bullswarm workflow runs --all --since 7d      # initiated in the last 7 days
 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
 ```
 
@@ -189,6 +211,12 @@ ISO timestamps, local dates, today/yesterday/tomorrow/now, or durations such as
 `7d`. Add `--all` or `--historical`; time filters do not silently change the
 normal ongoing-only scope.
 
+When the run is terminal, use `workflow runs result <id> --json` as the
+handoff contract. Its versioned result envelope points to the selected delivery
+artifact, the dependent verification verdict, progress, and usage. Do not guess
+the output schema by scraping task files or assume the last provider response is
+the deliverable; `runs show` is for low-level debugging.
+
 Before authoring or choosing a workflow, agents can inspect the live execution
 fabric and the workflow document itself:
 
@@ -215,6 +243,7 @@ bullswarm strategy show --json
 bullswarm strategy apply --yes --refresh-hours 24
 bullswarm strategy auto status
 bullswarm strategy assign high --pool <pool> --model <model>
+bullswarm strategy exclude-model <model>
 ```
 
 Connector-declared discovery, dated benchmark/pricing evidence, live quota,
@@ -226,6 +255,19 @@ an assignment, but it never bypasses capability, quarantine, exhaustion, or
 burst-gate safety. Each attempt records the chosen agent/model and labeled
 token, cost, and normalized-quota estimates in the workflow tree.
 
+`exclude-model` is a persisted hard policy, not a prompt hint. Excluded models
+are removed from recommendations and ignored in assignments. When a connector
+supports explicit model selection, Bullswarm pins an allowed model in the same
+effort tier; otherwise that pool is excluded because its implicit default
+cannot be guaranteed. Restore eligibility with `strategy include-model`.
+
+In the human TUI, the autonomous orchestrator has a compact selectable panel
+stacked above the phase tree. Select it and press Enter, or press
+`o`, to inspect its durable provider session, checkpoint turns and decisions,
+recent semantic actions, usage, prompt, and artifacts. Esc returns to phases.
+The shared state marks are `○` not started, animated Braille spinner active,
+`⧖` waiting, `✓` finished, and `✗` failed or interrupted.
+
 Run state also exposes the versioned plan, action ledger, aggregate usage, every attempt,
 planner decisions and reasons, budgets, `currentPhase`, `currentStep`, and
 `activeAgents` in `workflow tui --json <shortId>`. Each attempt includes its
@@ -261,11 +303,13 @@ blocks into the same action shape and retains the latest three. Ten minutes
 without any transport/event/action evidence becomes `suspected_stalled` with
 `autoTerminate:false`; it is deliberately not treated as proof of death.
 
-For adaptive work, declare a `decide` step plus `maxExpansionRounds` and the
-other graph-growth safeguards (`maxActions` and `maxItemsPerExpansion`).
-`maxAgents` and `maxWorkflowSeconds` are advisory planning targets: they expose
-remaining headroom and overage to the orchestrator but never stop a worker or
-skip required verification. The loop is durable:
+For adaptive work, declare a `decide` step plus advisory
+`maxExpansionRounds` and the hard structural safeguards (`maxActions` and
+`maxItemsPerExpansion`). `maxAgents`, `maxWorkflowSeconds`, and
+`maxExpansionRounds` expose remaining headroom and overage to the orchestrator
+but never stop a worker or skip required verification. Near the targets the
+planner is instructed to converge, consolidate existing artifacts, and avoid
+optional work. The loop is durable:
 
 ```text
 execute -> observe -> decide -> validate proposal -> append -> execute -> observe
@@ -274,6 +318,9 @@ execute -> observe -> decide -> validate proposal -> append -> execute -> observ
 Allowed planner decisions are `proceed`, `complete`, `needs_more_work`,
 `retry`, `escalate`, `wait_for_approval`, and `stop`. Expansion decisions must
 contain bounded actions; malformed or over-budget output executes nothing.
+`complete` still requires successful delivery and verification. `stop` returns
+`completed_with_concerns` with a ready best-effort artifact when useful work
+exists, or `blocked` when it does not; neither hides failed verification.
 Use `workflows/adaptive-code-review.json` as the starting template.
 Planner proposals cannot choose `pool`, `addDir`, or `taskFile`. Those fields
 are runtime-owned. An initiator may constrain them with a decide step's

package/src/cli.js

@@ -17,6 +17,8 @@ import { release } from './lib/release.js';
 import { cmdWorkflow } from './workflow/cli.js';
 import { cmdStrategy, maybeRefreshStrategy } from './strategy-cli.js';
 import { cmdIntegrate, installIntegration } from './integrate.js';
+import { helpForArgs } from './help.js';
+import { resolveDispatchModel } from './lib/strategy.js';
 
 export function getBullswarmDir() {
   const h = process.env.BULLSWARM_HOME?.trim();
@@ -117,7 +119,15 @@ async function cmdRun(opts) {
   // Burst gate (M3): a pool whose 5h window is >=90% used is excluded from
   // dispatch entirely this run — it paces nothing, it's just out of burst room.
   const gated = pools.filter((p) => p.burstGate);
-  const eligiblePools = gated.length ? pools.filter((p) => !p.burstGate) : pools;
+  const ungatedPools = gated.length ? pools.filter((p) => !p.burstGate) : pools;
+  const assignment = state.strategy?.assignments?.[effortTier] ?? null;
+  const eligiblePools = ungatedPools.map((pool) => ({
+    ...pool,
+    modelPolicy: resolveDispatchModel(pool.connector ?? pool, effortTier, {
+      assignment,
+      excludedModels: state.strategy?.excludedModels ?? [],
+    }),
+  })).filter((pool) => pool.modelPolicy.eligible);
 
   const route = pickPool(lane, eligiblePools, {
     callerEligible: opts['no-caller'] !== true,
@@ -145,8 +155,8 @@ async function cmdRun(opts) {
   // connector spec lives one level down.
   const poolView = route.pick.connector ?? { name: route.pick.pool };
   const connector = poolView.connector ?? poolView;
-  const assignment = state.strategy?.assignments?.[effortTier] ?? null;
-  const selectedModel = assignment?.pool === connector.name ? assignment.model : null;
+  const selectedModel = poolView.modelPolicy?.model
+    ?? (assignment?.pool === connector.name ? assignment.model : null);
   const runtimeConnector = {
     ...connector,
     subscription: poolView.subscription ?? connector.subscription ?? null,
@@ -236,6 +246,8 @@ function emit(verdict, opts) {
 
 function cmdHealth(opts) {
   const state = loadState(getBullswarmDir());
+  const released = sweepQuarantines(state, Date.now());
+  if (released.length) saveState(getBullswarmDir(), state);
   const runsDir = join(getBullswarmDir(), 'runs');
   const findings = [];
 
@@ -394,6 +406,11 @@ async function cmdDoctor(opts) {
 // --- main ---------------------------------------------------------------------
 
 export async function main(argv) {
+  const help = helpForArgs(argv);
+  if (help) {
+    console.log(help);
+    return 0;
+  }
   const [verb, ...rest] = argv;
   const opts = parseArgs(rest);
   const { ensureSetup } = await import('./setup.js');