# Quickstart: Operation Run Active-State Visibility & Stale Escalation

## Preconditions

1. Start the application stack:
   - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail up -d`
2. Work from branch `233-stale-run-visibility`.
3. Keep the scope bounded to existing admin-plane monitoring and progress surfaces.

## Primary Files To Review First

- `apps/platform/app/Models/OperationRun.php`
- `apps/platform/app/Support/Operations/OperationRunFreshnessState.php`
- `apps/platform/app/Support/OpsUx/OperationUxPresenter.php`
- `apps/platform/app/Support/OpsUx/ActiveRuns.php`
- `apps/platform/app/Livewire/BulkOperationProgress.php`
- `apps/platform/app/Filament/Widgets/Tenant/RecentOperationsSummary.php`
- `apps/platform/app/Filament/Widgets/Dashboard/RecentOperations.php`
- `apps/platform/app/Filament/Resources/OperationRunResource.php`
- `apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php`
- `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`

## Recommended Implementation Order

1. **Lock the truth source**
   - Confirm no surface-local stale thresholds exist outside `OperationRunFreshnessState` and `OperationRun::problemClass()`.
   - Reuse `OperationUxPresenter::decisionZoneTruth()`, `lifecycleAttentionSummary()`, and `surfaceGuidance()` wherever possible.

2. **Fix tenant progress visibility first**
   - Update `ActiveRuns` and `BulkOperationProgress` so stale-active runs still count as active work for visibility and polling.
   - Keep terminal runs disappearing on the next refresh cycle.
   - Render stale-active elevation through the shared operation status badge and `OperationUxPresenter` guidance path.

3. **Converge tenant and workspace summary surfaces**
   - Align `RecentOperationsSummary`, `Dashboard\RecentOperations`, `Dashboard\NeedsAttention`, `DashboardKpis`, and `WorkspaceOverviewBuilder` on the same compact/detailed stale-active semantics.
   - Do not create a new dashboard surface family.

4. **Tighten canonical monitoring consistency last**
   - Preserve `OperationRunResource` and `TenantlessOperationRunViewer` as the authoritative diagnostic surfaces.
   - Adjust top-level explanation or row emphasis only where it improves consistency with the compact surfaces.

5. **Update focused tests in the same slice**
   - Flip stale-hidden assertions in the tenant progress tests.
   - Extend monitoring, widget, and visibility-safety tests to prove fresh versus stale boundaries, terminal transitions, and hidden-tenant/non-member isolation.

## Focused Test Matrix

| Scenario | Expected Result | Likely Test Family |
|---|---|---|
| Fresh queued/running run on tenant surface | Visible as healthy active work, no stale escalation | `tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php`, `tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php` |
| Stale queued/running run on tenant surface | Still visible as active work, but clearly elevated | `tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php`, `tests/Feature/OpsUx/ProgressWidgetFiltersTest.php` |
| Stale run on workspace summaries | Scanable as attention-worthy, not collapsed into calm recency | `tests/Feature/Filament/WorkspaceOverviewOperationsTest.php`, `tests/Feature/Monitoring/MonitoringOperationsTest.php` |
| Stale run on canonical list/detail | Same active-state meaning preserved after drill-through | `tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php`, `tests/Feature/Operations/TenantlessOperationRunViewerTest.php`, `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php` |
| Terminal transition after refresh | Removed from active-only overlays and no longer presented as active | `tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php` |
| Hidden or out-of-scope runs during summary rendering | Remain invisible and do not alter visible active-state summaries | `tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php`, `tests/Feature/RunAuthorizationTenantIsolationTest.php` |

## Minimum Validation Commands

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php tests/Feature/OpsUx/ProgressWidgetFiltersTest.php tests/Feature/OpsUx/ProgressWidgetOverflowTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php tests/Feature/Filament/DashboardKpisWidgetTest.php tests/Feature/Filament/NeedsAttentionWidgetTest.php tests/Feature/Filament/WorkspaceOverviewOperationsTest.php tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php tests/Feature/Monitoring/MonitoringOperationsTest.php tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/RunAuthorizationTenantIsolationTest.php tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
```

## Manual Smoke Checklist

1. Seed one fresh running run and one stale queued/running run for the same tenant.
2. Open the tenant dashboard and confirm the stale run is visible and clearly elevated without making the fresh run look unhealthy.
3. Confirm the tenant progress surface keeps polling while only stale-active work remains.
4. Open `/admin/operations` and verify the same run is distinguishable at row level.
5. Drill into `/admin/operations/{run}` and confirm the top summary preserves the same active-state meaning before raw diagnostics.

## Out Of Scope Guardrails

- Do not add retry, cancel, reconcile-now, or worker-control actions.
- Do not add new notifications or queued/running DB notifications.
- Do not add new persisted run summary data or new `OperationRun` status values.
- Do not widen the work into a new operations workbench or cross-workspace fleet view.
