Run Engine

Implement the Control Panel's Python worker. I should be able to start a saved pipeline, watch a real agent work, inspect its checks, and understand why execution continued or stopped.

Create A Run

Accept a request to create a run from a pipeline id, repository path, Git revision, and optional implementation-profile override. Validate these inputs, resolve the commit, and freeze the definition and profiles into a pending run. Return the new run's record.

Isolate The Workspace

Create a branch and Git worktree for each run from its selected commit. Leave the original checkout intact and identify uncommitted changes that will not be included. Give tests separate data and ports where needed. Retain failed worktrees for inspection.

Queue The Start Request

Let a client durably request execution of a pending run, and acknowledge the request at once. Let one worker claim it transactionally while the API remains responsive. Reject a duplicate start. Show whether a pending run needs Start or is waiting for the worker.

Connect A Real Agent

Implement an adapter for an installed coding agent. Give it the role, prompt, workspace, profile, and deadline. Check the tool's supported invocation and document the version tested. Use argument arrays and its supported prompt input mechanism.

Normal runs must use the real adapter. Provide a separately selected test adapter for controlled failures, with simulated runs clearly labeled.

Enforce Role Permissions

Use supported tool permissions or operating-system controls to keep reviewers read-only and writers within scope. Keep control records outside writable workspaces. A worktree alone does not restrict access. Reject profiles that cannot enforce a required boundary.

Supply One Stage's Context

Start each stage in a fresh session with its requirement, master plan, workspace, repository instructions, and specification index. Include the named documentation and accepted dependency output. Resolve paths inside the workspace and report missing required files.

Create an initial specification index if the repository has none. Save each assembled prompt with its attempt, and keep older logs available by reference.

Record Each Attempt

Before launch, persist the stage, operation, attempt number, deadline, and starting artifact. Capture output while the process runs. Save its exit status, elapsed time, usage when reported, and resulting patch. Redact credentials from stored and displayed output.

Enforce Process Deadlines

Terminate the process and its children when its deadline expires, retaining partial output. Record missing executables, authentication failures, timeouts, and malformed results explicitly. Persist active execution time across restarts; waiting for a person does not consume the run budget.

Run The Gates

After implementation, run baseline checks, the stage's non-human gates, and any health checks due. Use frozen commands in the worktree. Record command, directory, timestamps, exit code, logs, and artifact reference. Only an actual zero exit status passes a script gate.

Request An Independent Review

Give a fresh read-only reviewer the requirement, patch, criteria, and check results. Require a structured verdict of pass, repair, or escalate with supporting findings. Invalid responses and unavailable reviewers stop for review. Model approval cannot waive a failed command.

Protect The Checks

Preserve agreed tests and configuration outside the writable worktree, then compare their contents after agent work. Unauthorized changes stop the run with their diff retained. Agents may add tests, but cannot weaken the acceptance checks they must satisfy.

Identify The Tested Files

Use a content manifest covering deliverable files, including additions and deletions. Keep a documented exclusion list for transient data. Preserve each manifest and patch. If files change during verification, require new results for the changed artifact.

Make A Bounded Repair

For an implementation defect, consume a repair attempt before launching a fresh session with the requirement, patch, and failure evidence. Rerun checks afterward. A successful repair continues from verification, without repeating the original implementation.

Share the repair allowance across all gates in a stage. Exhaustion, repeated unchanged failure, missing access, or an unresolved requirement moves the run to waiting_review. Restarting or rechecking must not reset limits.

Update The Documentation

After checks pass, give a separate documentation agent the verified diff and knowledge base. Restrict its changes to the configured documentation paths. Update the index and affected notes with implemented behavior and verification commands.

Reject out-of-scope edits. Rerun checks and reviews on the updated artifact before presenting a human gate. Stop for review if documentation fails.

Checkpoint The Stage

After all gates pass, have the engine commit the accepted files and record the hash. Reuse the current commit when nothing changed. Journal the operation before Git runs so recovery can detect an existing checkpoint. Only then advance to the next stage.

Approve A Human Gate

Accept an approval for a human gate, requiring the pending decision id, artifact reference, and reviewer name. Match them to the current decision and files before continuing. Reject a stale or repeated decision. Approval cannot bypass missing or failed checks.

Recheck A Corrected Result

Accept a recheck request, requiring a note about the correction. Invalidate affected approvals and rerun verification without resetting limits. Request new approval when files changed. A recheck cannot skip an implementation that never produced a result.

Recover An Interruption

On startup, reconcile queued requests and unfinished attempts. Mark uncertain work interrupted and set waiting_review. Preserve completed stages. Confirm the old process has stopped and inspect its effects before repeating anything.

Accept a recovery request, requiring the decision id and a recovery note. Allow explicit retry or verification of an existing result within saved limits. An exhausted execution budget requires a new run.

End An Unsuccessful Run

Accept a request to fail a run, requiring a reason. Stop and reap owned processes before recording the failure, retain the evidence, and reject late results. Expose Approve, Recheck, Recover, and Fail on the detail page only when applicable.

Verify Execution And Recovery

Run two stages through a real agent and confirm the second receives accepted output and updated documentation. Use the test adapter to exercise repair, exhaustion, unavailable commands, and invalid reviews. Keep simulated evidence distinct.

Send simultaneous Start requests and interrupt an active worker. Confirm neither creates duplicate execution, and that recovery preserves evidence and frozen requirements. After the last stage, continue to Verify It Works.

September, 2026