TenantAtlas/specs/233-stale-run-visibility/quickstart.md

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

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.