[Feature] : API ENDPOINTS PR 3 : System Status and Run Management Endpoints

[pulk17]

[FEATURE]

In raising this pull request, I confirm the following (please check boxes):

• I have read and understood the contributors guide.
• I have checked that another pull request for this purpose does not exist.
• I have considered, and confirmed that this submission will be valuable to others.
• I accept that this submission may not be used, and the pull request closed at the will of the maintainer.
• I give this submission freely, and claim no ownership to its content.

My familiarity with the project is as follows (check one):

• I have never used the project.
• I have used the project briefly.
• I have used the project extensively, but have not contributed previously.
• I am an active contributor to the project.

---

System status and run management endpoints (PR 3/6)

Summary

Part 3 of 6 (supersedes #1117). Adds health/queue endpoints and the CI run
lifecycle, and restores the global middleware integration tests deferred from
PR 1 now that there are endpoints to test against.

Stacking: stacked on PR 2 (#1131). Please review #1131 first.

System (mod_api/routes/system.py)

• GET /system/health — unauthenticated; DB / local-storage / GCS status
  (503 only when down).
• GET /system/queue — system:read; queued + running jobs with
  queue_depth/running_count, ?platform/?status filters.
• GET /runs/{id}/artifacts — results:read; lists run artifacts across local
  disk and GCS. Path traversal blocked by safe_resolve. (Binary/coredump/
  combined-stdout artifacts are produced by the CI-VM work; until that ships
  they report storage_status: "missing".)

Runs (mod_api/routes/runs.py)

• POST /runs — runs:write; creates a run for a commit + platform. Main-repo
  runs need contributor/tester/admin; fork runs require the caller to own the
  fork (see dependency note). Rejects commits with no build artifact up front
  (fails open if GitHub is unreachable).
• GET /runs — runs:read; filter by platform/branch/commit/repo/date,
  sortable, paginated. Status filtering covers queued/running/canceled at
  the DB level; terminal-state filtering is intentionally not offered and
  returns a clear 400.
• GET /runs/{id} · /summary · /progress · /config — detail, aggregate
  pass/fail/skip/missing/error counts, progress timeline, launch config.
• POST /runs/{id}/cancel — runs:write + contributor/tester/admin; writes a
  canceled progress row that the worker honours. Idempotent. Any runs:write
  user may cancel any run by design in this shared CI.

Services

storage.py (local/GCS resolution + signed URLs), error_service.py (derives
structured + infra errors), utils.safe_resolve (realpath traversal guard).

Dependency note (please read)

Fork-run permission uses user.github_login, which is populated in PR 6
(OAuth callback + a lazy fallback in this endpoint). This stack should therefore
be merged/deployed together; pre-existing users populate github_login on their
next GitHub login.

Testing

137 tests across tests/api, including the restored middleware integration
tests and permission-boundary assertions. Lint/type clean.

Next

PR 4 (#1133): samples and regression-test endpoints.

[cfsmp3]

HIGH:

• H2 — the C1 fix is only half-wired. The expected_outputs fix went into batch_get_run_data (run status), but get_run_summary and error_service still call the legacy is_dummy_row path (never matches). So for a run with missing output: derive_run_status says fail (right), but /summary counts it as pass with missing_output_count: 0, and /errors omits it. The endpoints contradict each other, and the headline bug resurfaces in the two endpoints users actually read. No test catches it.
• H3 — arbitrary-repo CI trigger (carryover #1117 H2). POST /runs: is_staff short-circuits ownership, repository is only regex-checked → a contributor can make the build VM clone+build any GitHub repo = arbitrary-code exec on CI infra. Gated by contributor role, but a real privilege expansion.
• H1 — migration still absent (3 PRs deep; all these routes are auth-gated so they need the token table too).

MEDIUM: cancel race (no row lock); status-filter 1000-cap drops rows + inconsistent total; summary total_samples never reconciles; _get_output_artifacts N+1 + paginates after full build; GCS signed URLs without blob.exists.

LOW/NIT: RunSummarySchema unused (raw dict, no contract); step:None dead field; queue hand-builds pagination; generic-exception→JSON path still untested.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud