Concurrent Command Runner

Run multiple shell commands concurrently with bounded parallelism, per-command timeouts, and optional fail-fast cancellation.

Capabilities

Runs commands concurrently with limits

• Given two short commands and max_concurrency=2 with no timeout, both commands finish, no more than the limit run at once, and outputs are returned in the same order as the input list. @test

Enforces per-command timeouts

• A command that exceeds its timeout is terminated, marked as timed out with return_code=None, and does not block faster commands from completing normally. @test

Cancels remaining work on failure

• When fail_fast=True, the first command that exits with a non-zero status causes any still-running commands to be cancelled (reported with return_code=None and timed_out=False), while completed results are preserved. @test

Implementation

@generates

API

from dataclasses import dataclass
from typing import List, Sequence

@dataclass
class CommandResult:
    command: Sequence[str]  # argv tokens for the command
    return_code: int | None  # None when cancelled or timed out
    stdout: str
    stderr: str
    timed_out: bool

def run_commands(
    commands: List[Sequence[str]],
    *,
    max_concurrency: int,
    timeout_seconds: float | None = None,
    fail_fast: bool = False,
) -> List[CommandResult]:
    """Executes shell commands concurrently with a concurrency limit and optional per-command timeout."""

Dependencies { .dependencies }

python (stdlib) { .dependency }

Provides concurrency primitives, async subprocess handling, and synchronization utilities. @satisfied-by