NeoMux ProofRunner

ProofRunner is an autonomous, evidence-backed release auditor for the Taskmaster track of the All Things Agentic Hackathon. A signed GitHub or GitLab event starts the workflow; no operator has to open a chat, copy a mission ID, or keep a browser session alive.

1. Cloud Run verifies the provider webhook and deduplicates its delivery ID.
2. Cloud Tasks asks Gemini 3.5 Flash for a dependency-aware audit plan.
3. Deterministic policy validates the DAG, role allowlist, and risk level.
4. A background host leases approved work, fetches the event ref, and checks out the exact SHA.
5. The host runs only exact allowlisted executable/argument arrays without a shell.
6. READY or BLOCKED is written back to the originating GitHub/GitLab commit.
7. Firestore retains the plan, lease attempts, exit codes, redacted previews, output hashes, and provider writeback evidence.

Live dashboard: https://proofrunner-u4sdedturq-uc.a.run.app/

Standalone source: https://github.com/Yesol-Pilot/neomux-proofrunner

Verified against the standalone repository from real GitHub branch-creation push webhooks:

• Tests + build + lint → READY → GitHub success
• Tests pass + release fixture fails → BLOCKED → GitHub failure

Why this is agentic

The user supplies policy once. After a release event, Gemini plans the audit, deterministic code constrains it, Cloud Tasks carries it across sessions, and a leased host completes the work in the background. Human approval appears only when policy identifies a genuinely high-risk action. Routine verification completes unattended.

Trust boundaries

• Source code and provider status credentials stay on the registered host.
• Gemini receives the goal, constraints, command names, repository label, and commit SHA—not source.
• Webhooks require GitHub HMAC-SHA256 or GitLab token verification.
• Provider delivery IDs become deterministic mission IDs, making retries idempotent.
• Leases expire and can be reclaimed; three expired attempts end in an explicit failed receipt.
• A dirty registered checkout is rejected even when it already points at the requested SHA.
• Commit and clean-tree state are revalidated before and after every approved command.
• Completion is rejected unless every approved command has commit-bound evidence.
• Full output is hashed locally; stored previews redact repository paths, home paths, and tokens.

Bearer tokens are the prototype host identity boundary, not remote attestation.

Run locally

Prerequisites: Node.js 24, pnpm 10, a Google Cloud project, and Application Default Credentials with Vertex AI access.

pnpm install
$env:GOOGLE_CLOUD_PROJECT = "your-project"
$env:VERTEX_AI_LOCATION = "global"
$env:LOCAL_DEMO = "1"
pnpm dev

Create a mission from the dashboard or POST /v1/missions. For a one-off strict checkout:

$env:PROOFRUNNER_API_URL = "http://localhost:8080"
$env:HOST_API_TOKEN = "unused-in-local-demo"
$env:PROOFRUNNER_ALLOWED_COMMANDS = '[{"executable":"pnpm","args":["test"]}]'
pnpm host -- MISSION_ID PATH_TO_REPOSITORY

For unattended execution, register dedicated clean checkout paths and start the daemon:

$env:PROOFRUNNER_REPOSITORIES = '[{"label":"proofrunner","path":"C:\\repos\\proofrunner"}]'
$env:GITHUB_STATUS_TOKEN = "host-only-status-token"
pnpm host -- --watch

The daemon fetches the event ref and uses detached checkout only when its registered path is clean.

Provider event policy

Set PROOFRUNNER_REPOSITORY_POLICIES to a JSON array. Exact ref entries override a repository default, so protected branches can use different commands and status names.

[
  {
    "provider": "github",
    "repository": "example/proofrunner",
    "ref": "refs/heads/main",
    "statusName": "proofrunner/release-audit",
    "repositoryLabel": "proofrunner",
    "goal": "Audit this release candidate and return an evidence-backed verdict.",
    "constraints": ["Never deploy"],
    "verificationCommands": [
      { "executable": "pnpm", "args": ["test"], "evidenceKind": "test" },
      { "executable": "pnpm", "args": ["build"], "evidenceKind": "build" }
    ]
  }
]

Configure the provider to send push and pull/merge-request events to:

• GitHub: POST /v1/webhooks/github
• GitLab: POST /v1/webhooks/gitlab

The Cloud Run service needs only the matching webhook secret. GitHub/GitLab status tokens belong on the host and are never sent to Google Cloud.

Deploy to Google Cloud

Create a Firestore Native database and these Secret Manager entries:

• proofrunner-internal-task-token
• proofrunner-api-token
• proofrunner-owner-token
• proofrunner-host-token
• proofrunner-github-webhook-secret when GitHub intake is enabled
• proofrunner-gitlab-webhook-secret when GitLab intake is enabled

Then run:

$env:GOOGLE_CLOUD_PROJECT = "your-project"
$env:ENABLE_GITHUB_WEBHOOK = "1"
$env:PROOFRUNNER_REPOSITORY_POLICIES = Get-Content policies.json -Raw
pnpm deploy:gcp

The deployment enables required APIs, builds the package as a standalone Docker context, deploys Cloud Run, connects Cloud Tasks and Firestore, injects named secrets, and verifies /health.

With the demo policy deployed, pnpm prove:live temporarily installs a real GitHub push webhook, creates READY and BLOCKED proof branches at the current SHA, waits for commit status writeback, and removes both the webhook and branches in finally.

API

Method	Path	Purpose
GET	/	Public dashboard
GET	/health	Health check
POST	/v1/webhooks/github	Signed GitHub event intake
POST	/v1/webhooks/gitlab	Signed GitLab event intake
POST	/v1/missions	Authenticated manual mission intake
GET	/v1/missions/{id}	Durable receipt
POST	/v1/missions/{id}/approval	High-risk owner approval
POST	/v1/host/claim-next	Atomic background lease
POST	/v1/missions/{id}/heartbeat	Lease renewal
POST	/v1/missions/{id}/completion	Evidence and verdict

Verify

pnpm test
pnpm build
pnpm lint
pnpm format:check

Prior-work disclosure

NeoMux Desktop predates the hackathon and can appear only as the local repository environment. ProofRunner—the standalone service, Gemini planner, deterministic policy, webhook intake, lease protocol, host daemon, provider writeback, evidence contract, and dashboard—is contest-period work.

Submission assets are in submission/all-things-agentic.