<Parallel>

import { Parallel } from "smthrs";

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 tasks in this parallel’s innermost group; a nested <Parallel> opens its own group, exempting its tasks from the outer cap. Use for flat children, as in the checks example above.
• subtreeConcurrency (subtree cap, opt-in, int >= 1). Caps direct children in flight at once; each descendant task counts toward its child. A child is in flight from its first task to its last; a freed slot admits the next child in document order, and an in-flight child always finishes (even nested tasks) while over-cap siblings wait. If that child launches a lifecycle-linked workflow, tasks in the child and deeper descendants also draw from this budget; dynamic child-run fan-out therefore stays bounded by the declaring ancestor.

<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 track their nearest <Parallel subtreeConcurrency> ancestor; nesting a second subtree-capped parallel re-scopes its descendants to the inner group.
• Child identity is the child’s explicit key/id when present (<Task id>, <Parallel id>, <Worktree id>), else its ordinal. Keep child order stable (or add ids) so resumed runs re-admit the same children.
• Admission is deterministic, derived from task state in document order, so a resumed run repeats the same decisions from its restored state.

​

Notes

• A group completes when all children finish. continueOnFail on a failing child <Task> (not a <Parallel> prop) lets the group proceed past it.
• Children carry parallelGroupId/parallelMaxConcurrency in their descriptor; under a subtree cap, descendants also get subtreeGroupId, subtreeChildKey, and subtreeMax.
• The run-wide cap layers on top of every group cap. Unpinned, it starts at 4 and grows with demand up to SMITHERS_AUTO_MAX_CONCURRENCY_CEILING (default 16); a declared maxConcurrency/subtreeConcurrency can raise that starting point above the ceiling. --max-concurrency N pins the cap instead, disabling those raises and holding the run at N even above the ceiling. Leaf cap, subtree cap, and run-wide cap must all pass.
• Lifecycle-linked <Subflow> children inherit every ancestor run/subtree admission scope. The awaiting parent task releases its scopes before the child starts and reacquires them after it settles, so inheritance cannot deadlock at --max-concurrency 1. A direct runWorkflow call with only parentRunId records detached lineage and does not inherit.