#21639: feat(gateway): add ops runtime runs history API
gateway
size: L
Cluster:
Cron Job Stability Fixes
## Summary
- add a read-only gateway method `ops.runtime.runs`
- aggregate cross-job cron run history from run logs
- add failure rollups per job with `consecutiveErrors`, timeout signals, and `needsAction`
- support filter/search/time-range params for history queries
- wire method into gateway handlers, method list, and read scope
- add unit tests for aggregation, filtering, and params validation
## Why
Mission Control v1 needs a fast path to answer:
- what recently ran?
- which jobs are failing repeatedly?
- which failures likely need manual action?
This PR is the PR2 step (runs history + failure aggregation) in issue #21600.
## API
Method: `ops.runtime.runs`
Params:
- `limit`, `perJobLimit`
- `search`
- `fromMs`, `toMs`
- `status` (`ok|error|skipped`, accepts `failed` alias)
- `includeDisabledCron`
- `jobId`
Response:
- `summary` (run counts + failure counts)
- `runs[]` (recent history)
- `failures[]` (job-level failure rollups)
## Validation
- `pnpm vitest src/gateway/server-methods/ops-runtime-runs.test.ts src/gateway/method-scopes.test.ts`
- `pnpm exec oxlint --type-aware src/gateway/server-methods/ops-runtime-runs.ts src/gateway/server-methods/ops-runtime-runs.test.ts src/gateway/server-methods.ts src/gateway/server-methods-list.ts src/gateway/method-scopes.ts`
- `pnpm exec oxfmt --check src/gateway/server-methods/ops-runtime-runs.ts src/gateway/server-methods/ops-runtime-runs.test.ts src/gateway/server-methods.ts src/gateway/server-methods-list.ts src/gateway/method-scopes.ts`
Related: #21600
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR adds a new read-only gateway method `ops.runtime.runs` that aggregates cron job run history from logs and provides failure analysis for Mission Control v1.
The implementation:
- Reads run logs for each job via `readCronRunLogEntries` and aggregates results across all jobs
- Applies filtering by status, search term, time range, and job ID
- Summarizes failures per job with `consecutiveErrors`, timeout detection, and `needsAction` flags
- Correctly maps the `failed` status alias to `error` for backwards compatibility
- Uses the `READ_SCOPE` permission level, allowing read-only access
Test coverage includes cross-job history aggregation, filter validation, status/search/time filtering, and invalid parameter handling. Integration is clean - the handler is properly wired into `coreGatewayHandlers`, added to the method list, and classified under `operator.read` scope.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk.
- The implementation follows established patterns in the codebase, includes comprehensive unit tests covering the main functionality and edge cases, properly integrates with the gateway authorization system, and handles errors gracefully. The code is defensive with input validation, limits on result sizes, and proper error handling.
- No files require special attention.
<sub>Last reviewed commit: 98de572</sub>
<!-- greptile_other_comments_section -->
<sub>(4/5) You can add custom instructions or style guidelines for the agent [here](https://app.greptile.com/review/github)!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#21612: feat(gateway): add ops runtime summary API
by frank8ai · 2026-02-20
88.2%
#21644: feat(control-ui): add runtime runs filters in cron tab
by frank8ai · 2026-02-20
80.3%
#15685: feat(cron): add maxRuns for automatic recurring job cleanup
by snurfer0 · 2026-02-13
73.8%
#17561: fix(cron): add runtime staleness guard for runningAtMs (#17554)
by robbyczgw-cla · 2026-02-15
73.0%
#20329: Fix cron.run WS blocking and harden delivery recovery
by guirguispierre · 2026-02-18
72.2%
#17064: fix(cron): prevent control-plane starvation during startup catch-up...
by donggyu9208 · 2026-02-15
71.7%
#11857: fix: recompute stale cron nextRunAtMs on gateway restart
by Yida-Dev · 2026-02-08
71.3%
#16125: feat(gateway): add stuck session detection
by CyberSinister · 2026-02-14
71.1%
#12747: fix: catch up missed cron-expression job runs on restart
by obin94-commits · 2026-02-09
71.0%
#17664: fix(cron): detect and clear stale runningAtMs marker in manual run ...
by echoVic · 2026-02-16
71.0%