[Phase 3.5B] Run Gates: button, trigger, and live gate progress

[frankbria]

Goal

Add a [Run Gates] button to the PROOF9 page that triggers a gate run and streams live progress back to the browser.

Background

POST /api/v2/proof/run already exists and works. The proof page has no way to call it. The PROVE phase is currently inspection-only — users can see requirements and waive them but cannot produce evidence from the browser.

Scope

• [Run Gates] button in the PROOF9 page header (enabled when a workspace is selected)
• Clicking the button calls POST /api/v2/proof/run with { full: true }
• Loading / streaming state: gate list appears immediately showing each gate as pending; poll GET /api/v2/proof/runs/{run_id} every 2 seconds to update individual gate statuses: pending → running → passed / failed
• Final state: on run completion show overall pass/fail banner
• Error state: surface error message with retry button if the request or polling fails
• Button is disabled while a run is in progress (prevent double-submit)

Out of scope

• Evidence artifact display (next issue)
• Run history panel (next issue)
• Triggering from task detail modal

Acceptance criteria

• [Run Gates] button renders on the PROOF9 page
• Clicking triggers a run and each gate transitions through pending → running → passed/failed
• Overall result banner shown on completion
• Button disabled during active run
• npm test and npm run build pass

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The PROOF9 page (file:web-ui/src/app/proof/page.tsx) is a Next.js 19 App Router page using useSWR, axios (via file:web-ui/src/lib/api.ts), and Radix UI / Tailwind components. The proofApi object in api.ts already has listRequirements, waive, etc., but no run or getRun methods. The backend POST /api/v2/proof/run exists in file:codeframe/ui/routers/proof_v2.py and returns { success, run_id, results, message } synchronously — there is no GET /api/v2/proof/runs/{run_id} polling endpoint yet. The run is synchronous on the backend; the "live gate progress" must be simulated via optimistic UI + a final refresh.

Approach

Since POST /api/v2/proof/run is synchronous (runs all gates and returns the full result in one response), there is no real streaming endpoint to poll. The plan adds a GET /api/v2/proof/runs/{run_id} endpoint that returns the cached result of a completed run, enabling the polling pattern described in the ticket. On the frontend, a useProofRun hook manages the full lifecycle: optimistic pending state → POST → poll until complete → final banner. This keeps the page component clean and matches the existing hook pattern (useExecutionMonitor, usePipelineStatus).

sequenceDiagram
    participant UI as ProofPage
    participant Hook as useProofRun
    participant API as proofApi (api.ts)
    participant BE as FastAPI /proof

    UI->>Hook: runGates()
    Hook->>API: proofApi.startRun({ full: true })
    API->>BE: POST /api/v2/proof/run
    Hook-->>UI: gateStatuses = all "pending"
    BE-->>API: { run_id, results }
    API-->>Hook: RunProofResponse
    loop Poll every 2s (simulated via run result)
        Hook->>API: proofApi.getRun(run_id)
        API->>BE: GET /api/v2/proof/runs/{run_id}
        BE-->>API: RunStatusResponse
        Hook-->>UI: update gate statuses
    end
    Hook-->>UI: isComplete=true, passed/failed banner

Loading

---

Implementation Steps

1. Backend — Cache run results and expose a polling endpoint

File: file:codeframe/ui/routers/proof_v2.py

• Add an in-memory (or file-backed) run result store. A simple module-level dict[str, RunProofResponse] keyed by run_id is sufficient for now.
• In run_proof_endpoint, after building RunProofResponse, store it in the cache before returning.
• Add a new Pydantic model RunStatusResponse with fields: run_id: str, status: Literal["running", "complete"], results: dict[str, list[dict]], passed: bool, message: str.
• Add a new route:

  GET /api/v2/proof/runs/{run_id}
  

  decorated with @rate_limit_standard(). It looks up run_id in the cache; if found, returns RunStatusResponse(status="complete", ...). If not found (run still in progress or unknown), return 404 or status="running" with empty results. Since the current backend is synchronous, a completed run will always be in the cache immediately after POST returns.

2. Frontend — Add API methods to proofApi

File: file:web-ui/src/lib/api.ts

• Add two methods to the proofApi object:
  • startRun(workspacePath, body: { full: boolean }) — POST /api/v2/proof/run with workspace_path query param, returns RunProofResponse.
  • getRun(workspacePath, runId) — GET /api/v2/proof/runs/{runId} with workspace_path query param, returns RunStatusResponse.

3. Frontend — Add TypeScript types

File: file:web-ui/src/types/index.ts

Add the following interfaces (mirroring the new backend models):

• RunProofResponse — { success: boolean; run_id: string; results: Record<string, Array<{ gate: string; satisfied: boolean }>>; message: string }
• RunStatusResponse — { run_id: string; status: 'running' | 'complete'; results: Record<string, Array<{ gate: string; satisfied: boolean }>>; passed: boolean; message: string }
• GateRunStatus — 'pending' | 'running' | 'passed' | 'failed' (UI-only type for per-gate display)
• GateRunEntry — { gate: string; status: GateRunStatus } (UI-only, for the live gate list)

4. Frontend — Create useProofRun hook

New file: file:web-ui/src/hooks/useProofRun.ts

Model this after useExecutionMonitor. The hook manages:

• State: runState: 'idle' | 'starting' | 'polling' | 'complete' | 'error', runId: string | null, gateEntries: GateRunEntry[], passed: boolean | null, errorMessage: string | null.
• startRun(workspacePath) callback:
  1. Set runState = 'starting', clear previous results.
  2. Call proofApi.startRun(workspacePath, { full: true }).
  3. On success: set runId, set runState = 'polling', populate gateEntries from the returned results with status 'running' for each gate (optimistic — since the backend is synchronous, results are already final, but the UI shows the transition).
  4. Start a setInterval (2 s) that calls proofApi.getRun(workspacePath, runId).
  5. On each poll response: update gateEntries statuses to 'passed' or 'failed' based on results, set passed, set runState = 'complete', clear the interval.
  6. On error (POST or poll): set runState = 'error', errorMessage, clear interval.
• retry() callback: resets state to idle.
• Clean up interval on unmount via useEffect return.
• Export the hook from file:web-ui/src/hooks/index.ts.

5. Frontend — Add GateRunPanel component

New file: file:web-ui/src/components/proof/GateRunPanel.tsx

A presentational component that receives gateEntries: GateRunEntry[] and renders a compact list showing each gate name alongside a status indicator:

Gate	Status
unit	🔄 running
sec	✅ passed
contract	⏳ pending

• Use Badge (already used in ProofStatusBadge) with appropriate colour classes:
  • pending → muted/gray
  • running → blue with a animate-pulse spinner
  • passed → green
  • failed → red/destructive
• Export from file:web-ui/src/components/proof/index.ts.

6. Frontend — Add result banner component

New file: file:web-ui/src/components/proof/GateRunBanner.tsx

A simple banner that accepts passed: boolean and message: string:

• passed=true → green success banner ("All gates passed")
• passed=false → red failure banner ("Some gates failed") with a Retry button that calls an onRetry prop.
• Export from file:web-ui/src/components/proof/index.ts.

7. Frontend — Wire everything into the PROOF9 page

File: file:web-ui/src/app/proof/page.tsx

In ProofPageContent:

1. Import and call useProofRun() at the top of the component.
2. Header area — add a [Run Gates] button next to the h1 title:
   • disabled when workspacePath is null OR runState is 'starting' or 'polling'.
   • onClick calls startRun(workspacePath).
   • While runState === 'starting' | 'polling', show a loading spinner inside the button (use animate-spin on an icon, consistent with existing patterns).
3. Below the filter controls (or above the table) — conditionally render:
   • <GateRunPanel gateEntries={gateEntries} /> when runState is 'starting' | 'polling' | 'complete' | 'error' and gateEntries.length > 0.
   • <GateRunBanner passed={passed} message={...} onRetry={retry} /> when runState === 'complete'.
   • An error message with a Retry button when runState === 'error'.
4. After a successful run completes (runState === 'complete'), call mutate() to refresh the requirements list so updated statuses (satisfied/open) are reflected in the table.

8. Export new components

File: file:web-ui/src/components/proof/index.ts

Add exports for GateRunPanel and GateRunBanner.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The PROOF9 page (`file:web-ui/src/app/proof/page.tsx`) is a Next.js 19 App Router page using `useSWR`, `axios` (via `file:web-ui/src/lib/api.ts`), and Radix UI / Tailwind components. The `proofApi` object in `api.ts` already has `listRequirements`, `waive`, etc., but **no `run` or `getRun` methods**. The backend `POST /api/v2/proof/run` exists in `file:codeframe/ui/routers/proof_v2.py` and returns `{ success, run_id, results, message }` synchronously — there is **no** `GET /api/v2/proof/runs/{run_id}` polling endpoint yet. The run is synchronous on the backend; the "live gate progress" must be simulated via optimistic UI + a final refresh.

## Approach

Since `POST /api/v2/proof/run` is synchronous (runs all gates and returns the full result in one response), there is no real streaming endpoint to poll. The plan adds a `GET /api/v2/proof/runs/{run_id}` endpoint that returns the cached result of a completed run, enabling the polling pattern described in the ticket. On the frontend, a `useProofRun` hook manages the full lifecycle: optimistic `pending` state → POST → poll until complete → final banner. This keeps the page component clean and matches the existing hook pattern (`useExecutionMonitor`, `usePipelineStatus`).

```mermaid
sequenceDiagram
    participant UI as ProofPage
    participant Hook as useProofRun
    participant API as proofApi (api.ts)
    participant BE as FastAPI /proof

    UI->>Hook: runGates()
    Hook->>API: proofApi.startRun({ full: true })
    API->>BE: POST /api/v2/proof/run
    Hook-->>UI: gateStatuses = all "pending"
    BE-->>API: { run_id, results }
    API-->>Hook: RunProofResponse
    loop Poll every 2s (simulated via run result)
        Hook->>API: proofApi.getRun(run_id)
        API->>BE: GET /api/v2/proof/runs/{run_id}
        BE-->>API: RunStatusResponse
        Hook-->>UI: update gate statuses
    end
    Hook-->>UI: isComplete=true, passed/failed banner
```

---

## Implementation Steps

### 1. Backend — Cache run results and expose a polling endpoint

**File: `file:codeframe/ui/routers/proof_v2.py`**

- Add an in-memory (or file-backed) run result store. A simple module-level `dict[str, RunProofResponse]` keyed by `run_id` is sufficient for now.
- In `run_proof_endpoint`, after building `RunProofResponse`, store it in the cache before returning.
- Add a new Pydantic model `RunStatusResponse` with fields: `run_id: str`, `status: Literal["running", "complete"]`, `results: dict[str, list[dict]]`, `passed: bool`, `message: str`.
- Add a new route:
  ```
  GET /api/v2/proof/runs/{run_id}
  ```
  decorated with `@rate_limit_standard()`. It looks up `run_id` in the cache; if found, returns `RunStatusResponse(status="complete", ...)`. If not found (run still in progress or unknown), return 404 or `status="running"` with empty results. Since the current backend is synchronous, a completed run will always be in the cache immediately after POST returns.

### 2. Frontend — Add API methods to `proofApi`

**File: `file:web-ui/src/lib/api.ts`**

- Add two methods to the `proofApi` object:
  - `startRun(workspacePath, body: { full: boolean })` — `POST /api/v2/proof/run` with `workspace_path` query param, returns `RunProofResponse`.
  - `getRun(workspacePath, runId)` — `GET /api/v2/proof/runs/{runId}` with `workspace_path` query param, returns `RunStatusResponse`.

### 3. Frontend — Add TypeScript types

**File: `file:web-ui/src/types/index.ts`**

Add the following interfaces (mirroring the new backend models):

- `RunProofResponse` — `{ success: boolean; run_id: string; results: Record<string, Array<{ gate: string; satisfied: boolean }>>; message: string }`
- `RunStatusResponse` — `{ run_id: string; status: 'running' | 'complete'; results: Record<string, Array<{ gate: string; satisfied: boolean }>>; passed: boolean; message: string }`
- `GateRunStatus` — `'pending' | 'running' | 'passed' | 'failed'` (UI-only type for per-gate display)
- `GateRunEntry` — `{ gate: string; status: GateRunStatus }` (UI-only, for the live gate list)

### 4. Frontend — Create `useProofRun` hook

**New file: `file:web-ui/src/hooks/useProofRun.ts`**

Model this after `useExecutionMonitor`. The hook manages:

- **State**: `runState: 'idle' | 'starting' | 'polling' | 'complete' | 'error'`, `runId: string | null`, `gateEntries: GateRunEntry[]`, `passed: boolean | null`, `errorMessage: string | null`.
- **`startRun(workspacePath)`** callback:
  1. Set `runState = 'starting'`, clear previous results.
  2. Call `proofApi.startRun(workspacePath, { full: true })`.
  3. On success: set `runId`, set `runState = 'polling'`, populate `gateEntries` from the returned `results` with status `'running'` for each gate (optimistic — since the backend is synchronous, results are already final, but the UI shows the transition).
  4. Start a `setInterval` (2 s) that calls `proofApi.getRun(workspacePath, runId)`.
  5. On each poll response: update `gateEntries` statuses to `'passed'` or `'failed'` based on `results`, set `passed`, set `runState = 'complete'`, clear the interval.
  6. On error (POST or poll): set `runState = 'error'`, `errorMessage`, clear interval.
- **`retry()`** callback: resets state to `idle`.
- Clean up interval on unmount via `useEffect` return.
- Export the hook from `file:web-ui/src/hooks/index.ts`.

### 5. Frontend — Add `GateRunPanel` component

**New file: `file:web-ui/src/components/proof/GateRunPanel.tsx`**

A presentational component that receives `gateEntries: GateRunEntry[]` and renders a compact list showing each gate name alongside a status indicator:

| Gate | Status |
|------|--------|
| unit | 🔄 running |
| sec  | ✅ passed |
| contract | ⏳ pending |

- Use `Badge` (already used in `ProofStatusBadge`) with appropriate colour classes:
  - `pending` → muted/gray
  - `running` → blue with a `animate-pulse` spinner
  - `passed` → green
  - `failed` → red/destructive
- Export from `file:web-ui/src/components/proof/index.ts`.

### 6. Frontend — Add result banner component

**New file: `file:web-ui/src/components/proof/GateRunBanner.tsx`**

A simple banner that accepts `passed: boolean` and `message: string`:
- `passed=true` → green success banner ("All gates passed")
- `passed=false` → red failure banner ("Some gates failed") with a **Retry** button that calls an `onRetry` prop.
- Export from `file:web-ui/src/components/proof/index.ts`.

### 7. Frontend — Wire everything into the PROOF9 page

**File: `file:web-ui/src/app/proof/page.tsx`**

In `ProofPageContent`:

1. Import and call `useProofRun()` at the top of the component.
2. **Header area** — add a `[Run Gates]` button next to the `h1` title:
   - `disabled` when `workspacePath` is null OR `runState` is `'starting'` or `'polling'`.
   - `onClick` calls `startRun(workspacePath)`.
   - While `runState === 'starting' | 'polling'`, show a loading spinner inside the button (use `animate-spin` on an icon, consistent with existing patterns).
3. **Below the filter controls** (or above the table) — conditionally render:
   - `<GateRunPanel gateEntries={gateEntries} />` when `runState` is `'starting' | 'polling' | 'complete' | 'error'` and `gateEntries.length > 0`.
   - `<GateRunBanner passed={passed} message={...} onRetry={retry} />` when `runState === 'complete'`.
   - An error message with a **Retry** button when `runState === 'error'`.
4. After a successful run completes (`runState === 'complete'`), call `mutate()` to refresh the requirements list so updated statuses (satisfied/open) are reflected in the table.

### 8. Export new components

**File: `file:web-ui/src/components/proof/index.ts`**

Add exports for `GateRunPanel` and `GateRunBanner`.

---

Execution Information

Branch: main
Commit: ea0de0a

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#491 - feat(web-ui): surface PROOF9 gate link in execution completion banner (#469) [merged]
#494 - feat(web-ui): auto-run gates on execution completion, show summary in banner (#472) [merged]
#496 - feat(web-ui): link failed tasks to PROOF9 gate failure for root cause (#474) [merged]
#526 - feat(web-ui): sort and filter controls for Proof requirements table [merged]
#528 - feat(web-ui): filter, search, and sort for proof evidence history table [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!