RailWarden – Safely run parallel agent harnesses in a single Git repo.

RailWarden, a deterministic execution and integration control plane for multi-agent software development, has been released, enabling safe parallel agent harnesses in a single Git repository. The tool supervises coding agents across isolated Git worktrees, records validation evidence, and blocks integration until mechanical gates pass, addressing issues like provider crashes, malformed data, and conflicting edits. It is available via uvx or pipx, and includes a credential-free demo for evaluation.

RailWarden is a deterministic execution and integration control plane for multi-agent software development. It turns approved plans into isolated work packages, supervises coding agents across Git worktrees, records validation evidence, and permits integration only after mechanical gates pass. Complex software work needs more than an agent claiming it is done. Agent chat history loses context; provider processes can crash, fail authentication, or exhaust quota; result data can be malformed; and unrestricted concurrent edits create dirty worktrees and conflicting changes. Prompts and skill frameworks help an agent reason, but they do not own durable facts. Task managers can track intent, but generally cannot prove commits, validate ownership, or block an unsafe merge. Ordinary CI validates a branch after the fact; it does not supervise the work package, preserve recovery state, or decide whether an agent’s report is credible. RailWarden owns execution facts: approved work-package contracts, dependency state, isolated worktrees, worker process facts, validation evidence, checkpoints, events, review readiness, and integration decisions. A task is complete only when its scoped changes are committed, mechanically validated, pass the applicable review and merge gates, and are integrated—not when a worker self-certifies. The implemented runtime provides durable file-backed execution state, dependency-aware packages, isolated Git worktrees, allowed/forbidden-path checks, supervised provider processes, structured worker-result normalization, validation evidence, checkpoints, append-only event logs, quota-aware handoffs, recovery paths, integration gates, and secret redaction in persisted runtime artifacts. Runtime state is independent of agent chat history. These are controlled-repository mechanisms, not an absolute safety or production-safety promise. See evidence /advaith-1212/railwarden/blob/main/docs/evidence.md , contracts /advaith-1212/railwarden/blob/main/docs/contracts/README.md , and safe adoption /advaith-1212/railwarden/blob/main/docs/safety.md for the verification boundary. Future goals are explicitly separated in architecture /advaith-1212/railwarden/blob/main/ARCHITECTURE.md . - Multiple coding agents work concurrently across packages, branches, or ownership boundaries. - Provider failure, handoff, recovery, auditability, validation evidence, and merge gates matter. - Work must survive restarts and run in isolated Git worktrees. - Several providers or harnesses participate in a controlled repository workflow. - One developer or one agent can safely finish a small change in a single session. - A feature branch plus ordinary CI is sufficient. - The operational complexity outweighs the benefit, or the repository cannot tolerate generated runtime state and worktrees. RailWarden is for serious multi-agent workflows, not every coding task. php flowchart TD A "Approved specification or plan" -- B "Frozen work packages and dependency DAG" B -- C "Parallel workers in isolated worktrees" C -- D "Mechanical validation and evidence" D -- E "Review and merge gates" E -- F "Integration branch" php flowchart TD A "Worker or provider failure" -- B "Event + checkpoint + handoff" B -- C "Retry, reassignment, model swap, or human decision" After a tagged release is published, the supported public install paths are: uvx railwarden --help or pipx install railwarden warden --help From a disposable repository, run the credential-free deterministic demo. scripted-fake is demo/test infrastructure only; it is not a production provider adapter. mkdir railwarden-demo cd railwarden-demo git init -b main git config user.name demo git config user.email demo@example.invalid warden init --yes --demo warden demo run The demo creates a frozen two-package dependency DAG and isolated worktrees, makes two commits, records an intentional validation failure and handoff, retries, validates, integrates, writes .railwarden-runtime/reports/demo-acceptance.json , and safely removes its generated worktrees. It needs no provider credentials. See acceptance testing /advaith-1212/railwarden/blob/main/docs/acceptance-testing.md . RailWarden = deterministic state and mechanics Hermes = supervisor and decision-maker Workers = scoped implementers Hermes is the currently supported and recommended supervisor. RailWarden owns durable facts and execution mechanics; Hermes owns interpretation, planning, assignment, diagnosis, and orchestration decisions; workers own scoped implementation. Hermes is intentionally retained. RailWarden does not currently promise interchangeable supervisors. A generic supervisor contract is only a future design direction if another ecosystem demonstrates maturity, adoption, trust, and compatibility. | Capability | Prompt/skill frameworks | Task managers | RailWarden | |---|---|---|---| | Specification approval | Common | Sometimes | Yes | | Dependency-aware tasks | Sometimes | Common | Yes | | Dedicated Git worktrees | Sometimes | Limited | Yes | | Provider process supervision | Rare | Limited | Yes | | Durable execution ledger | Rare | Partial | Yes | | Path ownership enforcement | Rare | Rare | Yes | | Validation evidence | Process-based | Partial | Mechanical | | Crash recovery | Limited | Limited | Yes | | Agent handoff state | Limited | Sometimes | Yes | | Merge gates | Advisory | Limited | Enforced | These are broad categories; individual tools vary. RailWarden is actively evolving and ready for developers to evaluate, extend, and use in controlled repositories. The core runtime is functional and appropriate for controlled evaluation. Important repositories should use protected branches, backups, required CI, restricted path ownership, and human review. Provider compatibility varies by environment. The core kernel is machine-readable contracts, the durable state machine, dependency/task state, worktree creation, path ownership, process supervision, event recording, structured results, validation evidence, review gates, and integration/merge gates. Supporting surfaces are tmux presentation, dashboards/Kanban projections, adapters, quota UI, context templates, planning helpers, skills, MCP transport, and observability views. php flowchart TB subgraph K "Indispensable kernel" C "Contracts" -- S "Durable state + events" -- G "Validation, review, merge gates" W "Worktrees + path ownership" -- S P "Process supervision" -- S end subgraph X "Adapters and interfaces" H "Hermes supervisor" A "Provider adapters" U "CLI, MCP, tmux, dashboard, Kanban" end H -- K A -- K U -- K Read ARCHITECTURE.md /advaith-1212/railwarden/blob/main/ARCHITECTURE.md for module boundaries, data flow, and lifecycle detail. Development /advaith-1212/railwarden/blob/main/DEVELOPMENT.md · Contributing /advaith-1212/railwarden/blob/main/CONTRIBUTING.md · Testing /advaith-1212/railwarden/blob/main/docs/testing.md Provider adapters /advaith-1212/railwarden/blob/main/docs/provider-adapters.md · CLI development /advaith-1212/railwarden/blob/main/docs/cli-development.md Contracts /advaith-1212/railwarden/blob/main/docs/contracts/README.md · Compatibility /advaith-1212/railwarden/blob/main/docs/compatibility-policy.md · Release process /advaith-1212/railwarden/blob/main/docs/release-process.md Evidence /advaith-1212/railwarden/blob/main/docs/evidence.md · Safe adoption /advaith-1212/railwarden/blob/main/docs/safety.md · Governance /advaith-1212/railwarden/blob/main/docs/governance.md MIT. See LICENSE /advaith-1212/railwarden/blob/main/LICENSE .