# StellaOps Console - Runs Workspace > **Audience:** Scheduler Guild, Console UX, operators, support engineers. > **Scope:** Runs dashboard, live progress, queue management, diffs, retries, evidence downloads, observability, troubleshooting, and offline behaviour (Sprint 23). The Runs workspace surfaces Scheduler activity across tenants: upcoming schedules, active runs, progress, deltas, and evidence bundles. It helps operators monitor backlog, drill into run segments, and recover from failures without leaving the console. --- ## 1. Access and prerequisites - **Route:** `/console/runs` (list) with detail drawer `/console/runs/:runId`. SSE stream at `/console/runs/:runId/stream`. - **Scopes:** `runs.read` (baseline), `runs.manage` (cancel/retry), `policy:runs` (view policy deltas), `downloads.read` (evidence bundles). - **Dependencies:** Scheduler WebService (`/runs`, `/schedules`, `/preview`), Scheduler Worker event feeds, Policy Engine run summaries, Scanner WebService evidence endpoints. - **Feature flags:** `runs.dashboard.enabled`, `runs.sse.enabled`, `runs.retry.enabled`, `runs.evidenceBundles`. - **Tenancy:** Tenant selector filters list; cross-tenant admins can pin multiple tenants side-by-side (split view). --- ## 2. Layout overview ``` +-------------------------------------------------------------------+ | Header: Tenant badge - schedule selector - backlog metrics | +-------------------------------------------------------------------+ | Cards: Active runs - Queue depth - New findings - KEV deltas | +-------------------------------------------------------------------+ | Tabs: Active | Completed | Scheduled | Failures | +-------------------------------------------------------------------+ | Runs table (virtualised) | | Columns: Run ID | Trigger | State | Progress | Duration | Deltas | +-------------------------------------------------------------------+ | Detail drawer: Summary | Segments | Deltas | Evidence | Logs | +-------------------------------------------------------------------+ ``` The header integrates the status ticker to show ingestion deltas and planner heartbeat. --- ## 3. Runs table | Column | Description | |--------|-------------| | **Run ID** | Deterministic identifier (`run:::`). Clicking opens detail drawer. | | **Trigger** | `cron`, `manual`, `feedser`, `vexer`, `policy`, `content-refresh`. Tooltip lists schedule and initiator. | | **State** | Badges: `planning`, `queued`, `running`, `completed`, `cancelled`, `error`. Errors include error code (e.g., `ERR_RUN_005`). | | **Progress** | Percentage + processed/total candidates. SSE updates increment in real time. | | **Duration** | Elapsed time (auto-updating). Completed runs show total duration; running runs show timer. | | **Deltas** | Count of findings deltas (`+critical`, `+high`, `-quieted`, etc.). Tooltip expands severity breakdown. | Row badges include `KEV first`, `Content refresh`, `Policy promotion follow-up`, and `Retry`. Selecting multiple rows enables bulk downloads and exports. Filters: trigger type, state, schedule, severity impact (critical/high), policy revision, timeframe, planner shard, error code. --- ## 4. Detail drawer Sections: 1. **Summary** - run metadata (tenant, trigger, linked schedule, planner shard count, started/finished timestamps, correlation ID). 2. **Progress** - segmented progress bar (planner, queue, execution, post-processing). Real-time updates via SSE; includes throughput (targets per minute). 3. **Segments** - table of run segments with state, target count, executor, retry count. Operators can retry failed segments individually (requires `runs.manage`). 4. **Deltas** - summary of findings changes (new findings, resolved findings, severity shifts, KEV additions). Links to Findings view filtered by run ID. 5. **Evidence** - links to evidence bundles (JSON manifest, DSSE attestation), policy run records, and explain bundles. Download buttons use `/console/exports` orchestration. 6. **Logs** - last 50 structured log entries with severity, message, correlation ID; scroll-to-live for streaming logs. `Open in logs` copies query for external log tooling. --- ## 5. Queue and schedule management - Schedule side panel lists upcoming jobs with cron expressions, time zones, and enable toggles. - Queue depth chart shows current backlog per tenant and schedule (planner backlog, executor backlog). - "Preview impact" button opens modal for manual run planning (purls or vuln IDs) and shows impacted image count before launch. CLI parity: `stella runs preview --tenant --file keys.json`. - Manual run form allows selecting mode (`analysis-only`, `content-refresh`), scope, and optional policy snapshot. - Pausing a schedule requires confirmation; UI displays earliest next run after resume. --- ## 6. Live updates and SSE stream - SSE endpoint `/console/runs/{id}/stream` streams JSON events (`stateChanged`, `segmentProgress`, `deltaSummary`, `log`). UI reconnects with exponential backoff and heartbeat. - Global ticker shows planner heartbeat age; banner warns after 90 seconds of silence. - Offline mode disables SSE and falls back to polling every 30 seconds. --- ## 7. Retry and remediation - Failed segments show retry button; UI displays reason and cooldown timers. Retry actions are scope-gated and logged. - Full run retry resets segments while preserving original run metadata; new run ID references previous run in `retryOf` field. - "Escalate to support" button opens incident template pre-filled with run context and correlation IDs. - Troubleshooting quick links: - `ERR_RUN_001` (planner lock) - `ERR_RUN_005` (Scanner timeout) - `ERR_RUN_009` (impact index stale) Each link points to corresponding runbook sections (`docs/ops/scheduler-runbook.md`). - CLI parity: `stella runs retry --run `, `stella runs cancel --run `. --- ## 8. Evidence downloads - Evidence tab aggregates: - Policy run summary (`/policy/runs/{id}`) - Findings delta CSV (`/downloads/findings/{runId}.csv`) - Scanner evidence bundle (compressed JSON with manifest) - Downloads show size, hash, signature status. - "Bundle for offline" packages all evidence into single tarball with manifest/digest; UI notes CLI parity (`stella runs export --run --bundle`). - Completed bundles stored in Downloads workspace for reuse (links provided). --- ## 9. Observability - Metrics cards: `scheduler_queue_depth`, `scheduler_runs_active`, `scheduler_runs_error_total`, `scheduler_runs_duration_seconds`. - Trend charts: queue depth (last 24h), runs per trigger, average duration, determinism score. - Alert banners: planner lag > SLA, queue depth > threshold, repeated error codes. - Telemetry panel lists latest events (e.g., `scheduler.run.started`, `scheduler.run.completed`, `scheduler.run.failed`). --- ## 10. Offline and air-gap behaviour - Offline banner highlights snapshot timestamp and indicates SSE disabled. - Manual run form switches to generate CLI script for offline execution (`stella runs submit --bundle `). - Evidence download buttons output local paths; UI reminds to copy to removable media. - Queue charts use snapshot data; manual refresh button loads latest records from Offline Kit. - Tenants absent from snapshot hidden to avoid partial data. --- ## 11. Screenshot coordination - Placeholders: - `![Runs dashboard placeholder](../assets/ui/runs/dashboard-placeholder.png)` - `![Run detail placeholder](../assets/ui/runs/detail-placeholder.png)` - Coordinate with Scheduler Guild for updated screenshots after Sprint 23 UI stabilises (tracked in `#console-screenshots`, entry 2025-10-26). --- ## 12. References - `/docs/ui/console-overview.md` - shell, SSE ticker. - `/docs/ui/navigation.md` - route map and deep links. - `/docs/ui/findings.md` - findings filtered by run. - `/docs/ui/downloads.md` - download manager, export retention, CLI parity. - `/docs/ARCHITECTURE_SCHEDULER.md` - scheduler architecture and data model. - `/docs/policy/runs.md` - policy run integration. - `/docs/cli/policy.md` and `/docs/cli/policy.md` section 5 for CLI parity (runs commands pending). - `/docs/ops/scheduler-runbook.md` - troubleshooting. --- ## 13. Compliance checklist - [ ] Runs table columns, filters, and states described. - [ ] Detail drawer sections documented (segments, deltas, evidence, logs). - [ ] Queue management, manual run, and preview coverage included. - [ ] SSE and live update behaviour detailed. - [ ] Retry, remediation, and runbook references provided. - [ ] Evidence downloads and bundle workflows documented with CLI parity. - [ ] Offline behaviour and screenshot coordination recorded. - [ ] References validated. --- *Last updated: 2025-10-26 (Sprint 23).*