NeoMux ProofRunner

An autonomous release agent that intercepts Git events, plans and executes verified work on trusted hosts, and writes READY or BLOCKED evidence back to GitHub and GitLab.

Comment

ProofRunner — the agent that audits other agents

Coding agents say “tests passed.” ProofRunner turns that claim into a commit status backed by execution evidence. A signed GitHub or GitLab event starts an unattended release audit: Gemini plans it, deterministic policy constrains it, a leased host checks out the exact SHA, and READY or BLOCKED returns to the originating commit.

Why I built it

While building NeoMux with coding agents across worktrees and terminal sessions, I kept repeating the same release chore after an agent said it was done: find the exact SHA, determine which checks actually ran, rerun them, interpret failures, and leave a durable result for the next session. ProofRunner automates that handoff. Its twist is that one agent does not write more code—it audits the claims made by other agents.

What it does

  1. Verifies a GitHub HMAC or GitLab webhook token and maps the delivery ID to an idempotent mission.
  2. Uses Gemini 3.5 Flash to create an evidence-aware, dependency-ordered audit plan.
  3. Applies deterministic policy to reject cycles, unknown roles, unsupported capabilities, and unsafe model risk labels.
  4. Persists the lifecycle in Firestore and continues planning asynchronously through Cloud Tasks.
  5. Lets a background host atomically lease approved work, heartbeat it, and recover expired leases.
  6. Rejects dirty checkouts and revalidates the clean tree and exact event SHA around every command.
  7. Runs only host-allowlisted executable/argument arrays without a shell.
  8. Produces READY only when every approved command has matching zero-exit evidence; otherwise it produces BLOCKED.
  9. Writes pending/success/failure to the source GitHub or GitLab commit using host-only credentials.
  10. Publishes a sanitized proof URL without requester data or command-output previews.

After repository policy and the host daemon are configured, the release event requires zero human steps unless deterministic policy identifies a high-risk action.

Verified live evidence

The public deployment includes receipts from real GitHub branch-creation push webhooks. The READY run passed tests, build, and lint with distinct output hashes and wrote GitHub success. The BLOCKED run passed tests, then an approved blocker exited 1 and GitHub received failure. Both receipts bind execution to the exact public source commit. The deployed Cloud Run revision serves 100% of traffic in us-central1, built by Cloud Build from the standalone package context.

Google technology

  • Gemini 3.5 Flash via the Google GenAI SDK on Vertex AI creates the bounded mission DAG and expected evidence plan.
  • Cloud Run hosts signed event intake, policy-controlled APIs, dashboard, and public proof.
  • Cloud Tasks makes planning asynchronous and independent of a user session.
  • Firestore transactions provide durable receipts, optimistic state transitions, and atomic host leasing.
  • Cloud Build and Artifact Registry build and retain the standalone deployment image.
  • Secret Manager provides separate API, owner, host, internal-task, and webhook boundaries to a least-privilege runtime service account.

Architectural decisions

Gemini plans; code authorizes. Model output never becomes permission by itself. Zod validates the shape, while deterministic code validates graph integrity, roles, unsupported claims, and risk.

Cloud coordinates; the host holds authority. Source, local filesystem access, and provider status tokens never enter the cloud control plane.

Failure is evidence, not an agent failure. A failed approved check creates a successful audit mission with a BLOCKED verdict. Infrastructure loss instead expires a lease, retries at most three times, and becomes an explicit failed receipt.

Challenges and learnings

Vertex AI rejected a nested enum-array response schema, so the planner combines explicit structured instructions, tolerant normalization, retry, and final deterministic validation. Windows package-manager shims require explicit cmd.exe invocation while normal commands remain shell-free. Webhook retries and crashed hosts also required separating idempotent event identity from time-bound execution leases.

Prior-work disclosure

NeoMux Desktop predates the hackathon and may appear only as the local repository environment in the demo. ProofRunner is the contest-period work: the standalone service, Gemini planner, deterministic policy, webhook intake, host leasing and recovery, background execution, provider writeback, public evidence receipt, deployment, and dashboard. Judging claims apply to ProofRunner, not to pre-existing NeoMux features.

What is next

Workload identity and hardware-backed host attestation; GitHub App and GitLab OAuth installation flows; organization policy packs, retention controls, and signed evidence bundles; and real pilot measurement of reviewer time saved and false READY prevention.

Judge the live proof

Built With

  • cloud-build
  • firestore
  • gemini-3.5-flash
  • google-cloud-run
  • google-cloud-tasks
  • google-genai-sdk
  • secret-manager
  • typescript
  • vertex-ai
Share this project:

Updates