<Parallel>

import { Parallel } from "smithers-orchestrator";

type ParallelProps = {
  id?: string;
  label?: string; // display name for this group in run views (graph, /workflows mirror)
  maxConcurrency?: number; // default: no per-group cap; effective concurrency is bounded by the run-level cap
  subtreeConcurrency?: number; // opt-in: cap DIRECT CHILDREN (whole subtrees) in flight, not leaf tasks
  priority?: number; // inherited default for descendant tasks
  failurePolicy?: "halt" | "quarantine";
  skipIf?: boolean;
  children?: ReactNode;
};

<Workflow name="checks">
  <Parallel maxConcurrency={2}>
    <Task id="lint" output={outputs.lint}>
      {{ errors: 0 }}
    </Task>
    <Task id="typecheck" output={outputs.typecheck}>
      {{ passed: true }}
    </Task>
    <Task id="test" output={outputs.test}>
      {{ passed: true }}
    </Task>
  </Parallel>
</Workflow>

​

Two concurrency semantics

• maxConcurrency (leaf-task cap). Caps the tasks whose innermost enclosing group is this parallel. A nested <Parallel> starts its own group, so its tasks do not count against the outer cap. Use it when the children are flat tasks (like the checks example above).
• subtreeConcurrency (subtree cap, opt-in, int >= 1). Caps how many direct children of this parallel are in flight at once, where every descendant task counts toward the child it descends from. A child is in flight from its first started task until all of its tasks finish; when a child finishes, the freed slot admits the next child in document order. An in-flight child may always finish its remaining tasks (even the ones in nested parallels) while over-cap siblings wait.

<Workflow name="kanban">
  <Parallel id="tickets" subtreeConcurrency={2}>
    {tickets.map((ticket) => (
      <Sequence key={ticket.id} label={ticket.title}>
        <Task id={`${ticket.id}-implement`} agent={coder} output={outputs.impl}>
          Implement {ticket.title}
        </Task>
        {/* Nested parallel: 3 reviewers per ticket. Still counts toward the
            ticket's in-flight slot; its own cap bounds simultaneous reviews. */}
        <Parallel id={`${ticket.id}-reviews`} maxConcurrency={3}>
          {reviewers.map((reviewer) => (
            <Task
              key={reviewer.id}
              id={`${ticket.id}-review-${reviewer.id}`}
              agent={reviewer.agent}
              output={outputs.review}
            >
              Review the implementation of {ticket.title}
            </Task>
          ))}
        </Parallel>
      </Sequence>
    ))}
  </Parallel>
</Workflow>

​

Subtree cap notes

• Descendant tasks record their nearest ancestor <Parallel subtreeConcurrency>: nesting a second subtree-capped parallel inside a child re-scopes its descendants to the inner group.
• Child identity is the direct child’s explicit key/id prop when the element carries one through (e.g. <Task id>, <Parallel id>, <Worktree id>), otherwise its child ordinal. Keep direct-child order stable (or give ids) so resumed runs re-admit the same children.
• Admission is deterministic in document order and derived purely from task states, so a resumed run makes the same decisions from a restored state map.

​

Notes

• Group completes when all children finish. To let the group proceed past a failing child, set continueOnFail on that individual child <Task>. It is not a <Parallel> prop.
• Children receive parallelGroupId and parallelMaxConcurrency in their descriptor; under a subtree cap every descendant task also receives subtreeGroupId, subtreeChildKey, and subtreeMax.
• The run-wide cap applies on top of every group. With no --max-concurrency pin, it starts at 4 and automatically grows with queued demand up to SMITHERS_AUTO_MAX_CONCURRENCY_CEILING (16 by default). A declared maxConcurrency or subtreeConcurrency width can also raise the initial run-wide cap above that automatic ceiling. --max-concurrency N pins the cap instead: it disables those raises and the run never exceeds N, but N itself may be larger than the automatic ceiling. subtreeConcurrency composes the same way: leaf-group cap, subtree cap, and the run-wide cap must all pass.