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

Feature Specification: Operation Run Active-State Visibility & Stale Escalation

Feature Branch: 233-stale-run-visibility
Created: 2026-04-23
Status: Draft
Input: User description: "Operation Run Active-State Visibility & Stale Escalation"

Spec Candidate Check (mandatory — SPEC-GATE-001)

• Problem: OperationRun lifecycle truth already exists, but compact operator surfaces still under-communicate when active work is past expectation or likely stuck.
• Today's failure: A run can be visibly stale on the canonical monitoring detail yet still read like ordinary Queued or Running work on tenant cards, dashboard attention surfaces, or list rows. Operators then receive false reassurance until they drill into monitoring.
• User-visible improvement: Active runs that are healthy, late, or likely stuck become visibly distinct across tenant and workspace surfaces, so operators can see unhealthy work in one scan without losing the canonical run detail as the diagnostic source of truth.
• Smallest enterprise-capable version: Add one bounded active-state presentation contract derived from existing lifecycle, freshness, and reconciliation truth, then apply it consistently to tenant dashboard activity surfaces, tenant-local active-run cards, the workspace operations list, and the canonical run detail summary.
• Explicit non-goals: No new OperationRun status values, no retry or cancel actions, no queue or worker redesign, no new notification channel, no full operations hub redesign, no cross-workspace fleet monitoring, and no parallel UI-only stale heuristic that bypasses existing lifecycle truth.
• Permanent complexity imported: One bounded derived active-state category family over existing run truth, one shared cross-surface presentation contract, focused operator copy updates on existing monitoring surfaces, and regression coverage for fresh versus stale semantics across tenant and workspace entry points.
• Why now: This is an active near-term operator-trust hardening item in the roadmap, and it becomes more urgent as more governance, evidence, and review workflows depend on OperationRun. Spec 232 now hardens link continuity into canonical monitoring, so the next high-leverage gap is what those linked surfaces actually communicate about unhealthy active work.
• Why not local: Fixing one widget or one row badge would still leave contradictory lifecycle meaning across cards, list rows, dashboard attention, and run detail. The problem is cross-surface truth drift, not one local rendering bug.
• Approval class: Core Enterprise
• Red flags triggered: Cross-cutting interaction-class scope plus one new derived presentation category family. Defense: the feature derives entirely from existing lifecycle and freshness truth, avoids persistence or backend-state expansion, and stays bounded to existing admin-plane surfaces.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace, tenant, canonical-view
• Primary Routes:
  • /admin/t/{tenant} for tenant dashboard activity and attention surfaces
  • Existing tenant-local active-run cards linked from tenant-scoped admin surfaces that already summarize active work
  • /admin/operations as the canonical workspace monitoring list
  • /admin/operations/{run} as the canonical run detail surface
• Data Ownership: operation_runs remain the only source of lifecycle and freshness truth. Tenant-local cards, dashboard signals, and workspace monitoring rows remain derived read models over existing run records, lifecycle policy, and stale-detection truth. No new persisted visibility flag, summary mirror, or auxiliary active-run table is introduced.
• RBAC: Admin-plane workspace membership remains required for /admin/operations and run detail visibility. Tenant-scoped surfaces remain constrained by current tenant entitlement. Non-members and out-of-scope tenant requests remain deny-as-not-found. This feature does not introduce new capability strings, new roles, or new mutation permissions.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: When operators enter /admin/operations from a tenant-scoped surface, the canonical monitoring list may preserve the active tenant as a default prefilter while retaining the same workspace-level route and clearing behavior used by existing canonical monitoring links.
• Explicit entitlement checks preventing cross-tenant leakage: Tenant-local cards and dashboard signals may summarize only runs already visible to the current operator within that tenant. The canonical operations list and run detail continue to re-check workspace membership and tenant entitlement before rendering. No stale or past-lifecycle signal may reveal the existence of hidden runs or tenants.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes
• Interaction class(es): status messaging, dashboard signals/cards, monitoring list presentation, canonical run detail summary
• Systems touched: tenant dashboard activity surfaces, tenant-local active-run cards, workspace monitoring list rows, canonical monitoring detail, and existing canonical drill-through links into /admin/operations
• Existing pattern(s) to extend: current OperationRun lifecycle policies, freshness/stale detection, canonical monitoring pages, shared badge semantics, and existing tenant-to-monitoring drill-through patterns
• Shared contract / presenter / builder / renderer to reuse: OperationRunService remains the sole owner of lifecycle transitions; App\Support\OperationCatalog remains the canonical operation label source; existing central badge rendering remains the status-like rendering path; existing canonical operations links remain the navigation path into /admin/operations
• Why the existing shared path is sufficient or insufficient: Existing lifecycle, freshness, and reconciliation truth are sufficient and must remain authoritative. Existing compact-surface presentation is insufficient because it compresses unhealthy active work too aggressively and can contradict the canonical run detail.
• Allowed deviation and why: Same meaning, different density is allowed. Tenant cards, dashboard signals, list rows, and run detail may vary in information density, but they may not disagree about whether active work is healthy, late, or likely stuck.
• Consistency impact: Active-state language, status emphasis, badge meaning, next-step cues, and drill-through expectations must stay aligned across tenant dashboards, tenant cards, monitoring rows, and canonical detail.
• Review focus: Reviewers must verify that no compact surface presents a run as ordinary active work when the canonical monitoring detail presents it as past expectation or likely stuck, and that no new page-local stale heuristic bypasses the shared lifecycle truth.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Tenant dashboard activity and attention surfaces	yes	Native Filament dashboard widgets and shared summary primitives	Same tenant-home signal family as existing attention and activity summaries	summary, attention cues, drill-through links	no	Existing surfaces only; no new dashboard page
Tenant-local active-run cards and progress summaries	yes	Native Filament widgets/cards and shared run primitives	Same tenant-scoped activity family as existing recent-run and progress hints	compact active-state presentation, drill-through links	no	Existing cards only; no new card family
Workspace operations list / monitoring rows	yes	Native Filament table and shared run presentation primitives	Same canonical monitoring family as existing /admin/operations list	row-level active-state emphasis, filter continuity, list scanability	no	Existing registry surface only
Canonical operation run detail summary	yes	Native Filament detail surface and shared run summary primitives	Same canonical monitoring detail family	top-level active-state explanation, diagnostics separation	no	Detail remains diagnostic-first, not a new page

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Tenant dashboard activity and attention surfaces	Secondary Context Surface	An operator lands on the tenant dashboard and decides whether current tenant activity needs immediate follow-up	Whether active work is healthy, needs attention, or likely stuck, plus one drill-through into monitoring	Full run history, raw run context, and extended diagnostics on the canonical monitoring surfaces	Secondary because the dashboard signals attention but should not replace the monitoring register	Follows tenant-home to monitoring workflow instead of creating a second workbench	Removes the need to open monitoring just to learn that active work is already stale or late
Tenant-local active-run cards and progress summaries	Secondary Context Surface	An operator inspects one tenant-scoped active-work summary and decides whether to open monitoring now	Current run identity, active-state category, and whether the work is merely active or needs attention	Full lifecycle history, stale-cause detail, and related diagnostics on run detail	Secondary because the card summarizes active work inside a broader tenant workflow	Follows tenant-scoped operational follow-up without duplicating monitoring detail	Prevents misleading neutral Queued or Running summaries from hiding unhealthy work
Workspace operations list / monitoring rows	Primary Decision Surface	A workspace operator scans the active operations register and decides which run needs inspection first	Whether active runs are normal, past expectation, or likely stuck, together with run identity and scope context	Full run diagnostics, raw context, and related artifacts on run detail	Primary because this is the canonical list where operators prioritize run follow-up	Follows monitoring and triage workflow instead of forcing row-by-row drill-in	Makes unhealthy active runs scanable without opening every row
Canonical operation run detail summary	Tertiary Evidence / Diagnostics Surface	After choosing one run, the operator confirms what kind of active-state problem exists and what it means	Clear top-level explanation of active-state category, lifecycle expectation status, and why diagnostics matter	Raw payloads, stack traces, reconciliation context, and deep technical detail	Tertiary because the operator first decides to inspect the run elsewhere; this page then provides the authoritative diagnosis	Preserves the existing monitoring-detail workflow	Reduces back-and-forth between list rows and diagnostics to understand whether the run is merely active or likely stuck

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Tenant dashboard activity and attention surfaces	Monitoring / Queue / Workbench	Read-only Registry / Report Surface	Open the tenant-scoped monitoring slice or the highlighted run	Explicit drill-through CTA or linked run summary	forbidden	Dashboard CTAs remain limited to monitoring follow-up	none	/admin/t/{tenant}	/admin/operations/{run}	Tenant context, activity state, attention weighting	Operations / Operation	Whether tenant-visible active work is healthy, late, or likely stuck	Embedded summary drill-in only
Tenant-local active-run cards and progress summaries	Monitoring / Queue / Workbench	Read-only Registry / Report Surface	Open the run detail or canonical monitoring list	Explicit linked run summary	forbidden	Card CTA stays secondary to the active-state summary	none	/admin/t/{tenant}	/admin/operations/{run}	Tenant context, active work scope, active-state emphasis	Active operations / Operation	Whether the highlighted active work is ordinary progress or already needs attention	Embedded compact summary; no new surface family
Workspace operations list / monitoring rows	List / Table / Bulk	Read-only Registry / Report Surface	Open the run most likely to need follow-up	Full-row open to canonical run detail	required	Existing filters and list controls stay in table chrome, not row noise	none	/admin/operations	/admin/operations/{run}	Workspace scope, optional tenant prefilter, active-state emphasis	Operations / Operation	Which active runs are healthy versus problematic without opening every row	none
Canonical operation run detail summary	Record / Detail / Edit	Detail-first Operational Surface	Inspect one run's active-state explanation and diagnostics	Canonical run detail page	n/a	Related links and secondary diagnostics stay below the top-level summary	Existing dangerous follow-up actions remain wherever already governed; none are added here	/admin/operations	/admin/operations/{run}	Workspace scope, tenant context when applicable, active-state explanation	Operation run	Why the run is healthy, late, or likely stuck before raw diagnostics appear	canonical evidence detail

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Tenant dashboard activity and attention surfaces	Tenant operator	Decide whether tenant-visible activity already needs monitoring follow-up	Summary drill-in	Is anything actively happening on this tenant that is already late or likely stuck?	Active-state category, tenant-visible run identity, and one drill-through path	Full run diagnostics and raw lifecycle context remain in monitoring	execution lifecycle, freshness, attention state	none	Open monitoring or run detail	none
Tenant-local active-run cards and progress summaries	Tenant operator	Decide whether the highlighted active run is still ordinary progress	Compact run summary	Is this active work still healthy, or does it already need attention?	Run identity, active-state category, elapsed-state emphasis	Deep diagnostics, raw context, and reconciliation detail remain on run detail	execution lifecycle, freshness, active-state interpretation	none	Open run detail	none
Workspace operations list / monitoring rows	Workspace operator	Prioritize which active run deserves inspection first	Read-only monitoring registry	Which active runs are normal, and which are already late or likely stuck?	Run identity, scope, high-level lifecycle, and active-state emphasis	Raw payloads and detailed run history remain on run detail	lifecycle, freshness, problem emphasis	none	Open run detail, apply filters	none
Canonical operation run detail summary	Workspace operator	Confirm the meaning of the active-state issue before deeper diagnosis	Diagnostic detail surface	Why does this active run read as late or likely stuck, and what should I inspect next?	Top-level active-state explanation, scope, and summary guidance	Raw payloads, stack traces, and extended technical details	lifecycle, freshness, diagnostic readiness	none	Open related context or diagnostics	none

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: yes — one bounded derived active-state presentation contract expressed through existing presenter and active-run helpers rather than a standalone framework
• New enum/state/reason family?: yes — one derived operator-facing category family for active / normal, active / past expectation, stale / likely stuck, and terminal / no longer active, composed from existing freshness and problem-class truth
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: Operators cannot trust compact active-work surfaces because they can understate or hide the difference between healthy progress and likely stuck work.
• Existing structure is insufficient because: Existing lifecycle truth lives in monitoring detail and backend services, but compact surfaces can still render active work as neutral Queued or Running states without exposing that the lifecycle expectation has already been exceeded.
• Narrowest correct implementation: Keep all backend lifecycle truth as-is, add one derived presentation contract, and retrofit only the existing tenant/dashboard/monitoring surfaces that already summarize active work.
• Ownership cost: Ongoing maintenance for one small presentation category family, cross-surface wording alignment, and regression coverage for fresh versus stale semantics.
• Alternative intentionally rejected: Introducing new OperationRun statuses or page-local stale heuristics was rejected because both would either widen persistence and lifecycle scope or create contradictory truth outside the existing lifecycle policy.
• Release truth: Current-release truth. This feature makes existing active-run observability honest now rather than preparing a future intervention framework.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Feature
• Validation lane(s): fast-feedback, confidence
• Why this classification and these lanes are sufficient: The proof burden is operator-visible active-state semantics across existing admin surfaces. Focused feature coverage is sufficient to prove fresh versus stale differentiation, tenant/workspace visibility boundaries, cross-surface consistency, and no false escalation without needing browser or heavy-governance lanes.
• New or expanded test families: Extend tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php, tests/Feature/OpsUx/ProgressWidgetFiltersTest.php, tests/Feature/OpsUx/ProgressWidgetOverflowTest.php, 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, tests/Feature/RunAuthorizationTenantIsolationTest.php, and tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php.
• Fixture / helper cost impact: Moderate. Tests need representative OperationRun fixtures for healthy queued/running work, past-expectation work, likely stuck work, terminal transitions during navigation, mixed tenant visibility, and hidden-tenant/non-member isolation boundaries.
• Heavy-family visibility / justification: none
• Special surface test profile: monitoring-state-page
• Standard-native relief or required special coverage: Ordinary feature coverage is sufficient, plus explicit proof that healthy active runs do not escalate falsely and that stale semantics remain consistent after drill-through from tenant surfaces into canonical monitoring.
• Reviewer handoff: Reviewers must confirm that the same active-state meaning appears on tenant cards, dashboard attention, operations rows, and canonical run detail; that no new backend status values or UI-only stale heuristics are introduced; and that hidden or out-of-scope runs do not influence visible summaries.
• Budget / baseline / trend impact: none
• Escalation needed: none
• Active feature PR close-out entry: Guardrail
• Planned 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

User Scenarios & Testing (mandatory)

User Story 1 - See unhealthy tenant activity without opening monitoring first (Priority: P1)

As a tenant operator, I want tenant-scoped activity surfaces to distinguish healthy active work from late or likely stuck work, so that I can notice unhealthy runs before manually opening the monitoring register.

Why this priority: Tenant cards and dashboard attention surfaces are the highest-frequency compact summaries for active work. If they remain misleading, the rest of the monitoring model is harder to trust.

Independent Test: Can be fully tested by seeding healthy and stale tenant-visible active runs, rendering the tenant dashboard and active-run cards, and verifying that only late or likely stuck work escalates while healthy work stays calm.

Acceptance Scenarios:

1. Given a tenant-visible run is queued or running within its expected lifecycle, When the tenant dashboard or active-run card renders, Then the run appears as healthy active work and does not escalate as stale or likely stuck.
2. Given a tenant-visible run is queued or running well past its expected lifecycle, When the same compact surfaces render, Then the run is visibly and linguistically distinct from healthy active work.
3. Given a run becomes terminal, When the tenant-scoped compact surfaces refresh, Then the run no longer appears as active work.

---

User Story 2 - Scan problematic active runs in the canonical operations list (Priority: P1)

As a workspace operator, I want the canonical operations list to make problematic active runs obvious at row level, so that I can prioritize follow-up without opening each run.

Why this priority: The canonical operations list is the primary monitoring surface for run triage. If unhealthy active runs are not scanable there, operators lose the central prioritization surface.

Independent Test: Can be fully tested by seeding a mix of fresh and stale active runs across visible tenants and verifying that the operations list highlights problematic rows without falsely escalating healthy rows.

Acceptance Scenarios:

1. Given the operations list contains a mix of healthy active runs and likely stuck runs, When the workspace operator opens /admin/operations, Then the problematic active runs are immediately distinguishable at row level.
2. Given the operator enters /admin/operations from a tenant-scoped surface, When the canonical list opens with tenant context preserved, Then the same active-state semantics remain visible within that filtered monitoring slice.
3. Given an active run is fresh, When the operations list renders, Then it does not inherit the same escalation treatment as a late or likely stuck run.

---

User Story 3 - Keep compact surfaces aligned with canonical run detail (Priority: P2)

As a workspace operator, I want canonical run detail to confirm the same active-state meaning that I saw on tenant and list surfaces, so that I can trust compact summaries without losing diagnostic depth.

Why this priority: The canonical detail page is the authoritative diagnostic surface. It must confirm, not contradict, the meaning shown elsewhere.

Independent Test: Can be fully tested by navigating from tenant-scoped or list surfaces into run detail for both healthy and stale runs and verifying that the same active-state meaning holds after drill-through.

Acceptance Scenarios:

1. Given a run reads as likely stuck on a tenant surface or list row, When the operator opens canonical run detail, Then the detail summary confirms that the run is past expectation or likely stuck before exposing raw diagnostics.
2. Given a run changes from active to terminal while the operator navigates between surfaces, When the compact surface and run detail refresh, Then neither surface continues to present the run as active.
3. Given a scheduled or initiator-null run becomes late, When the operator inspects it through monitoring, Then the active-state semantics remain truthful without implying a new notification channel or mutation behavior.

Edge Cases

• A run may move from healthy to late or likely stuck between two page loads; the presentation contract must tolerate state changes without requiring a manual semantic reset.
• An operator may open the canonical run detail from a tenant-filtered monitoring slice; the run detail must remain authoritative while preserving scope context where already allowed.
• Multiple active runs may exist for one tenant; compact surfaces must not imply that all tenant activity is stale because one run is problematic.
• A run may become terminal while the operator is on a tenant dashboard or monitoring list; compact surfaces and run detail must converge on non-active presentation after refresh.
• Initiator-null scheduled work may become stale without producing a terminal DB notification; monitoring semantics must remain truthful without inventing a new scheduled-run notification contract.

Requirements (mandatory)

Constitution alignment (required): This feature adds no Microsoft Graph calls, no new write flow, and no new OperationRun. It changes only how existing run lifecycle and freshness truth are interpreted on admin-plane operator surfaces.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): The feature introduces one derived active-state presentation contract because current-release operator trust requires it now. A narrower local patch is insufficient because the same truth must remain aligned across tenant cards, dashboard signals, list rows, and canonical detail. The addition stays derived, not persisted.

Constitution alignment (XCUT-001): This feature is cross-cutting across status messaging and dashboard/monitoring surfaces. It reuses the existing lifecycle, freshness, badge, and canonical monitoring paths, and it allows only one bounded deviation: same meaning, different density.

Constitution alignment (TEST-GOV-001): Focused feature tests on tenant dashboard surfaces, tenant active-run cards, monitoring rows, and run detail are the narrowest sufficient proof. No browser or heavy-governance lane is required.

Constitution alignment (OPS-UX): Existing Ops-UX 3-surface feedback remains unchanged. Toasts stay intent-only, progress surfaces remain the existing active-work surfaces, and terminal DB notifications stay unchanged. OperationRun.status and OperationRun.outcome transitions remain service-owned exclusively through OperationRunService. This feature must not introduce new summary_counts keys or any new scheduled-run notification semantics.

Constitution alignment (RBAC-UX): The feature operates only in the admin plane (/admin and /admin/t/{tenant}/...). Tenant-scoped compact surfaces remain tenant-entitlement safe, while canonical monitoring routes continue to enforce workspace membership and tenant entitlement on tenant-owned runs. No cross-plane visibility or raw capability checks may be added.

Constitution alignment (BADGE-001): Any changed status-like emphasis must continue to use centralized badge or status rendering. No page-local mapping from stale-detection inputs to color or label semantics is allowed.

Constitution alignment (UI-FIL-001): Touched surfaces must use native Filament widgets, tables, summaries, and existing shared status primitives. No custom local status markup or page-local color systems may replace shared run presentation.

Constitution alignment (UI-NAMING-001): Operator-facing language must use one canonical vocabulary for active-state meaning: healthy active work, past expected lifecycle, likely stuck, and no longer active. Implementation-first phrases or raw stale heuristics must not become primary labels.

Constitution alignment (DECIDE-001): The operations list remains the primary decision surface for run triage. Tenant dashboard surfaces remain secondary context surfaces, and canonical run detail remains the diagnostic surface. This feature must make those roles calmer and clearer, not create a new workbench.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001): No new route, no new inspect model, and no new destructive action family are introduced. The canonical inspect model remains the run detail page. Compact surfaces may add emphasis and drill-through clarity only.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): Direct mapping from queued and running alone is insufficient because lifecycle expectation and freshness change the operator meaning of active work. The feature adds one bounded derived interpretation layer and must prove business consequences across surfaces rather than only unit-testing one presenter.

Functional Requirements

• FR-001: The system MUST derive one active-state presentation category for visible runs using existing lifecycle, freshness, and reconciliation truth.
• FR-002: The derived presentation contract MUST distinguish at least active / normal, active / past expected lifecycle, stale / likely stuck, and terminal / no longer active.
• FR-003: The feature MUST NOT introduce new OperationRun.status or OperationRun.outcome values to express those categories.
• FR-004: Tenant dashboard activity and attention surfaces MUST visibly and linguistically distinguish healthy active work from active work that is late or likely stuck.
• FR-005: Tenant-local active-run cards and progress summaries MUST surface the same active-state meaning as the tenant dashboard attention layer for the same run.
• FR-006: The workspace operations list MUST make late or likely stuck active runs distinguishable at row level without requiring drill-in.
• FR-007: Canonical run detail MUST explain the active-state category before exposing raw diagnostics, and that explanation MUST remain consistent with the compact surfaces that linked into it.
• FR-008: A run that is presented as late or likely stuck on canonical run detail MUST NOT appear as ordinary healthy active work on any covered tenant or monitoring surface.
• FR-009: Healthy active runs MUST NOT inherit stale or likely-stuck emphasis solely because they are queued or running.
• FR-010: When a run becomes terminal, covered compact surfaces MUST stop presenting it as active work on the next refresh cycle.
• FR-011: Existing lifecycle, freshness, and reconciliation logic MUST remain the source of truth; covered surfaces MUST NOT implement separate page-local stale heuristics.
• FR-012: When operators enter canonical monitoring from tenant context, existing tenant-prefilter continuity MAY be preserved, but the active-state semantics MUST remain identical to the unfiltered canonical list.
• FR-013: Covered surfaces MUST remain tenant-safe and workspace-safe; hidden runs or hidden tenants MUST NOT influence visible active-state summaries.
• FR-014: Scheduled or initiator-null runs MUST use the same active-state presentation rules as user-initiated runs where lifecycle and freshness truth are comparable.
• FR-015: This feature MUST NOT add retry, cancel, force-fail, reconcile-now, or other intervention actions to any covered surface.
• FR-016: Existing Ops-UX toast, progress-surface, and terminal-notification behavior MUST remain unchanged.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Tenant dashboard activity and attention surfaces	/admin/t/{tenant}	none added by this feature	Explicit dashboard CTA or linked run summary	none	none	none	n/a	n/a	No new mutation audit because the surface remains read-only	Action Surface Contract satisfied. Dashboard remains a signal surface, not a second workbench. UI-FIL-001 satisfied through native widgets and shared status primitives.
Tenant-local active-run cards and progress summaries	Tenant-scoped admin surfaces that already summarize active work	none added by this feature	Explicit linked run summary	none	none	none	n/a	n/a	No new mutation audit because the surface remains read-only	One primary inspect model remains the run detail. No redundant View action is added.
Workspace operations list	/admin/operations	Existing filters only; none added by this feature	Full-row open to run detail	none added by this feature	none	Existing list empty state unchanged	n/a	n/a	No new mutation audit because the surface remains read-only	Action Surface Contract satisfied. Row click stays the only primary inspect model.
Canonical operation run detail summary	/admin/operations/{run}	Existing safe/context actions unchanged	n/a	n/a	n/a	n/a	Existing detail/header actions unchanged	n/a	No new mutation audit because the feature changes summary semantics only	No exemption needed. This feature changes top-level explanation, not the action layout.

Key Entities (include if feature involves data)

• Active-state presentation category: A derived operator-facing category that explains whether visible active work is healthy, late, likely stuck, or no longer active.
• Lifecycle expectation window: The existing timing and policy truth that determines when active work has exceeded its normal expected lifecycle.
• Stale active run: An existing OperationRun whose lifecycle and freshness truth indicate that active work is likely stuck rather than merely still in progress.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: In acceptance review, an operator can distinguish healthy tenant-visible active work from likely stuck work in one scan of the covered tenant surfaces.
• SC-002: 100% of covered fresh-versus-stale automated scenarios show the correct active-state category on the tenant dashboard, tenant active-run cards, and workspace operations list.
• SC-003: 100% of covered drill-through scenarios preserve the same active-state meaning between compact surfaces and canonical run detail.
• SC-004: 100% of covered healthy-active scenarios avoid false escalation when lifecycle expectation has not yet been exceeded.