The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
#!/usr/bin/env python3
"""Enqueue an already-reviewed PR and retain evidence for its actual merged tree.
The exact reviewed head is bound to GitHub's enqueue mutation. Main may advance;
the required merge-group CI tests that combined candidate. No mutation is retried
after an uncertain response, and this command never publishes a release.
"""
import importlib.util
import json
from pathlib import Path
import re
import subprocess
import time
spec = importlib.util.spec_from_file_location("queue_ci_evidence", Path(__file__).with_name("record-ci-validation.py"))
ci = importlib.util.module_from_spec(spec)
spec.loader.exec_module(ci)
planner_spec = importlib.util.spec_from_file_location("queue_ci_plan", Path(__file__).with_name("ci-plan.py"))
planner = importlib.util.module_from_spec(planner_spec)
planner_spec.loader.exec_module(planner)
STATE_QUERY = """query($owner:String!,$name:String!,$number:Int!) {
repository(owner:$owner,name:$name) { pullRequest(number:$number) {
id number state isDraft headRefOid baseRefName mergedAt
mergeCommit { oid tree { oid } }
mergeQueueEntry { id state position enqueuedAt headCommit { oid tree { oid } } }
} }
}"""
ENQUEUE = """mutation($id:ID!,$head:GitObjectID!) {
enqueuePullRequest(input:{pullRequestId:$id,expectedHeadOid:$head,jump:false}) {
mergeQueueEntry { id }
}
}"""
def graphql(client, query, **variables):
args = ["api", "graphql", "-f", "query=" + query]
for key, value in variables.items():
args += ["-F" if isinstance(value, int) else "-f", f"{key}={value}"]
result = client.command(*args)
if result.get("errors") or not isinstance(result.get("data"), dict):
raise ValueError("GitHub queue lookup failed: " + json.dumps(result.get("errors", [])))
return result["data"]
def state(client, number, head, branch):
owner, name = client.repository.split("/")
pr = graphql(client, STATE_QUERY, owner=owner, name=name, number=number)["repository"]["pullRequest"]
if (pr.get("number") != number or pr.get("headRefOid") != head or pr.get("baseRefName") != branch
or pr.get("isDraft") is not False):
raise ValueError("PR head, target or draft state differs from the reviewed source")
return pr
def gate_evidence(client, run, output, root=None, base=None):
receipt, artifact, archive = planner.read_gate(client, run)
reused = receipt.get("reused") or {}
if reused:
# PR CI ran the PR's own planner. Re-derive its reuse with main's copy, from the reviewed checkout.
if root is None or base is None or run.get("event") != "pull_request":
raise ValueError("reused CI results can only be verified for a PR run against the reviewed checkout")
main = planner.main_planner(root, base)
main.verify_reuse(root, receipt, base, main.GitHubEvidence(client))
output.mkdir(parents=True, exist_ok=True)
(output / "ci-required.zip").write_bytes(archive)
(output / "receipt.json").write_text(json.dumps(receipt, indent=2) + "\n")
return dict(run_id=run["id"], run_attempt=run["run_attempt"], url=run["html_url"],
source_sha=receipt["source_sha"], source_tree=receipt["source_tree"],
suites=receipt["suites"], reused=reused, artifact_id=artifact["id"], artifact_digest=artifact["digest"])
def pr_run(client, head):
runs = client.pages("actions/workflows/ci.yml/runs?event=pull_request&head_sha=" + head, "workflow_runs")
candidates = sorted((r for r in runs if r.get("head_sha") == head and r.get("event") == "pull_request"),
key=lambda r: r["id"], reverse=True)
if not candidates:
raise ValueError("automatic CI has not run for the reviewed PR head")
return candidates[0]
def pr_gate(client, head, output, root=None, base=None):
return gate_evidence(client, pr_run(client, head), output, root, base)
def merged_gate(client, tree, branch, started_at, output):
# A merge may finish between polls, so don't depend on having seen its queue
# ref. Search the automatic candidate runs and verify the immutable tree.
path = "actions/workflows/ci.yml/runs?event=merge_group&created=%3E%3D" + started_at[:19] + "Z"
runs = client.pages(path, "workflow_runs")
candidates = sorted(runs, key=lambda r: r["id"], reverse=True)
for run in candidates:
if (run.get("status") != "completed" or run.get("conclusion") != "success"
or not run.get("head_branch", "").startswith(f"gh-readonly-queue/{branch}/")):
continue
commit = client.api(f"git/commits/{run['head_sha']}")
if commit.get("sha") == run["head_sha"] and commit.get("tree", {}).get("sha") == tree:
return gate_evidence(client, run, output)
raise ValueError("merged tree lacks verified successful merge-group CI; inspect this same PR")
def finish(client, root, number, head, base, output, *, merge=False, wait_timeout=1800, timeout=90, branch="main"):
output.mkdir(parents=True, exist_ok=False)
record = dict(schema=1, kind="queued-pr-merge", repository=client.repository, pr=number,
reviewed_head=head, reviewed_base=base, target_branch=branch, merge_authorized=merge,
started_at=ci.utc_now(), status="not_queued", phases={})
def save():
temporary = output / "receipt.tmp"
temporary.write_text(json.dumps(record, indent=2) + "\n")
temporary.replace(output / "receipt.json")
def phase(name, action):
started = time.monotonic()
detail = record["phases"][name] = dict(started_at=ci.utc_now())
save()
try:
return action()
finally:
detail.update(finished_at=ci.utc_now(), duration_seconds=round(time.monotonic() - started, 3))
save()
try:
client.deadline = time.monotonic() + timeout
local = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=root, text=True, timeout=15).strip()
dirty = subprocess.check_output(["git", "status", "--porcelain", "--untracked-files=normal"], cwd=root, text=True, timeout=15).strip()
if local != head or dirty:
raise ValueError("the local checkout must remain clean at the reviewed head")
subprocess.run(["git", "merge-base", "--is-ancestor", base, head], cwd=root, check=True, timeout=15)
pr = phase("preflight", lambda: state(client, number, head, branch))
if pr["state"] != "OPEN":
raise ValueError("PR is not open")
record["pr_evidence"] = phase("pr_validation", lambda: pr_gate(client, head, output / "pr-ci", root, base))
pr = state(client, number, head, branch)
if pr["state"] != "OPEN":
raise ValueError("PR state changed before enqueueing")
entry = pr.get("mergeQueueEntry")
# Resuming a queued PR must include the candidate created by its earlier
# enqueue. A fresh command's start time would exclude that valid run.
record["candidate_search_since"] = entry["enqueuedAt"] if entry else record["started_at"]
if entry:
record["queue_entry"] = entry
record["status"] = "ready_for_queue"
save()
if merge:
if not pr["mergeQueueEntry"]:
record.update(status="enqueue_requested", enqueue_requested_at=ci.utc_now())
save()
try:
record["enqueue_response"] = phase("enqueue", lambda: graphql(client, ENQUEUE, id=pr["id"], head=head))
except (OSError, RuntimeError, subprocess.SubprocessError, ValueError) as error:
record["enqueue_error"] = str(error)
# Observe the same PR even after a lost enqueue response. Never
# silently issue a second mutation or substitute a newer PR head.
client.deadline = time.monotonic() + wait_timeout
def follow():
announced = None
while time.monotonic() < client.deadline:
current = state(client, number, head, branch)
if current["state"] == "MERGED":
merged = current["mergeCommit"]
ci_sha = merged["oid"]
tree = merged["tree"]["oid"]
if not all(re.fullmatch(r"[0-9a-f]{40}", v or "") for v in [ci_sha, tree]):
raise ValueError("merged PR has an invalid commit/tree")
client.deadline = time.monotonic() + timeout
evidence = merged_gate(client, tree, branch, record["candidate_search_since"], output / "candidate-ci")
return dict(commit=ci_sha, tree=tree, merged_at=current["mergedAt"], evidence=evidence)
entry = current["mergeQueueEntry"]
if current["state"] != "OPEN" or not entry:
raise ValueError("PR left the merge queue or enqueue was not confirmed; inspect this same PR")
summary = (entry["id"], entry["state"], entry["position"])
if summary != announced:
print(f"PR #{number}: queue position {entry['position']}, {entry['state']}", flush=True)
announced = summary
record.update(status="queued", queue_entry=entry)
save()
time.sleep(min(10, max(0, client.deadline - time.monotonic())))
raise TimeoutError("queue wait deadline exceeded; PR remains queued, follow the same PR")
record["merge"] = phase("queue_wait_and_verification", follow)
record["status"] = "merged"
except (OSError, RuntimeError, ValueError, KeyError, TypeError, subprocess.SubprocessError, ci.zipfile.BadZipFile) as error:
record["error"] = str(error)
if "enqueue_requested_at" in record or record.get("queue_entry"):
record["status"] = "queue_outcome_not_confirmed"
record["finished_at"] = ci.utc_now()
save()
text = f"PR #{number}: **{record['status']}**.\nReviewed head `{head}`; review base `{base}`.\n"
if "merge" in record:
evidence = record["merge"]["evidence"]
text += f"Merged `{record['merge']['commit']}`; its full tree matches verified [candidate CI]({evidence['url']}).\n"
if "error" in record:
text += record["error"] + "\n"
(output / "merge.md").write_text(text)
return record