TenantAtlas/specs/268-operationrun-activity-feedback/spec.md

# Feature Specification: OperationRun Activity Feedback v1

**Feature Branch**: `268-operationrun-activity-feedback`  
**Created**: 2026-05-03  
**Status**: Ready for implementation  
**Input**: Manual promotion from `docs/product/spec-candidates.md` after the 2026-05-03 repo-based next-best-prep re-audit.

## Spec Candidate Check *(mandatory - SPEC-GATE-001)*

- **Problem**: `OperationRun` is already the repo-real execution truth, but the current tenant-shell activity hint drops the feedback loop as soon as work becomes terminal, so operators can see work running and then lose the confirmation/follow-up state immediately.
- **Today's failure**: Operators can queue work and still get feedback that can cover primary actions. Once a run finishes, the current `BulkOperationProgress` shell widget disappears immediately and does not provide a short terminal-success confirmation or an explicit unresolved follow-up state in the same surface.
- **User-visible improvement**: Operators get one calm, truthful activity hint on tenant-scoped start surfaces, with at most three visible items, canonical `View operation` links, honest progress treatment, a brief terminal-success confirmation, and unresolved terminal follow-up states that do not disappear silently.
- **Smallest enterprise-capable version**: refactor the current tenant-shell activity hint to align with the existing Ops-UX 3-surface contract, add a bounded terminal-success/follow-up phase to the same surface, and update the UI standards so future hosts do not drift.
- **Explicit non-goals**: no activity tray v2, no DB-backed hide preferences, no new `OperationRun` types or status families, no notification lifecycle rewrite, no permanent terminal inbox, and no host-widget migration beyond the current global activity widget.
- **Permanent complexity imported**: no new persisted model; one browser-session rule set for active hide plus terminal dismiss/acknowledge affordances, focused Pest/browser coverage, one standards-document addition, and only a tiny local helper if the existing shell component cannot stay readable without it.
- **Why now**: the overlap bug is already verified, and the constitution already defines a non-negotiable three-surface contract for `OperationRun`. The shell hint needs to align before more local run snippets drift from that contract.
- **Why not local**: a pure CSS tweak would not encode the terminal feedback-loop, honest-progress, canonical-link, and calmness rules in either the implementation or the standards guidance.
- **Approval class**: Workflow Compression
- **Red flags triggered**: shared interaction family, shell-level surface, session-local UI state
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: tenant
- **Primary Routes**:
  - `/admin/t/{tenant}/...` tenant-scoped start surfaces that currently receive the shared activity hint from the tenant-panel shell
  - `/admin/operations` and `/admin/operations/{run}` remain the diagnostics drill-through targets and canonical collection/detail routes; shell overflow opens `/admin/operations` with the selected tenant as a contextual `tenant_id` prefilter, and that query-param prefilter wins over session/default state on initial mount
- **Data Ownership**: existing `OperationRun` truth with tenant-bound operational ownership semantics enforced through workspace + tenant entitlement checks; the current nullable-tenant exception remains limited to canonical workspace-context monitoring views; no new persisted projection or preference store
- **RBAC**: existing `OperationRun` policies remain authoritative. Non-members or out-of-scope tenant contexts remain hidden (`404` semantics through the current tenant/admin boundaries); in-scope actors only see hints for runs they can already view.

## Cross-Cutting / Shared Pattern Reuse *(mandatory)*

- **Cross-cutting feature?**: yes
- **Interaction class(es)**: status messaging, navigation links, shell active-awareness hints
- **Systems touched**: `BulkOperationProgress`, tenant-panel render-hook shell feedback, canonical run links, current queued toasts, current activity poller, UI standards
- **Existing pattern(s) to extend**: `OperationUxPresenter`, `OperationStatusNormalizer`, `OperationRunLinks`, `OperationRunUrl`, `ActiveRuns`, `OpsUxBrowserEvents`, current active-ops shell widget
- **Shared contract / presenter / builder / renderer to reuse**: `App\Support\OpsUx\OperationUxPresenter`, `App\Support\OpsUx\OperationStatusNormalizer`, `App\Support\OperationRunLinks`, `App\Support\OpsUx\OperationRunUrl`, `App\Support\OpsUx\ActiveRuns`, `apps/platform/resources/views/livewire/bulk-operation-progress.blade.php`
- **Why the existing shared path is sufficient or insufficient**: the repo already has truthful run-state, guidance, badge, and link semantics. What is missing is a constitution-aligned implementation of the shell contract: honest progress while active, a bounded terminal-success/follow-up handoff, canonical links, and non-obstructive placement.
- **Allowed deviation and why**: none by default. Keep the refactor local to the current shell component and its views; only extract a tiny helper if the existing component cannot remain readable otherwise.
- **Consistency impact**: `View operation` wording, overflow/`Show all operations` affordances, progressbar eligibility, lifecycle-sensitive tertiary action labels, bounded terminal success/follow-up visibility, and browser-session hide/dismiss/acknowledge behavior must stay aligned with the Ops-UX constitution and the standards doc.
- **Review focus**: verify that the shell keeps queued/running truth, shows only bounded terminal-success/follow-up states, never shows fake progress after completion, introduces no raw route strings, and remains non-obstructive.

## OperationRun UX Impact *(mandatory)*

- **Touches OperationRun start/completion/link UX?**: yes
- **Shared OperationRun UX contract/layer reused**: current Ops-UX start contract through `OperationUxPresenter`, `OperationRunLinks`, `OperationRunUrl`, `OpsUxBrowserEvents`, and current DB-notification lifecycle
- **Delegated start/completion UX behaviors**: current queued toast wording, canonical `View operation` link generation, tenant-safe URL resolution, current `run-enqueued` browser event, and existing terminal DB-notification lifecycle all remain delegated to the shared path
- **Local surface-owned behavior that remains**: the shell surface owns bounded layout, recent terminal-success/follow-up visibility, and browser-session hide/dismiss/acknowledge affordances only; it does not own lifecycle truth, severity mapping, or run-link routing
- **Queued DB-notification policy**: `N/A` - unchanged, explicit opt-in policy remains as-is
- **Terminal notification path**: unchanged central lifecycle mechanism
- **Exception required?**: none

## Provider Boundary / Platform Core Check *(mandatory)*

- **Shared provider/platform boundary touched?**: no
- **Boundary classification**: `N/A`
- **Seams affected**: `N/A`
- **Neutral platform terms preserved or introduced**: `Operation`, `View operation`, `Show all operations`, `queued`, `running`, `active`
- **Provider-specific semantics retained and why**: none
- **Why this does not deepen provider coupling accidentally**: the feature only reshapes execution feedback over existing platform-owned `OperationRun` truth and current link helpers
- **Follow-up path**: none

## UI / Surface Guardrail Impact *(mandatory)*

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Tenant shell activity hint | yes | Native Filament + existing Livewire/Blade surface | Ops UX start feedback, terminal handoff, canonical run links | shell, page, browser-session | no | Must stop covering primary actions on row-action-heavy pages and must keep terminal success/follow-up bounded |

## Decision-First Surface Role *(mandatory)*

| 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 shell activity hint | Primary Decision Surface | Decide whether an active or just-finished operation needs immediate inspection or no further action | Operation label, lifecycle state, one next-step cue, `View operation`, progress only when valid, and brief terminal confirmation/follow-up | Full run detail, logs, evidence, diagnostics stay in Operations pages | Primary because it appears immediately after a start action and must support the next operator decision without opening Monitoring first | Follows start-surface workflow, not storage structure | Replaces a floating overlay and closes the feedback loop without turning the shell into a monitoring page |

## Audience-Aware Disclosure *(mandatory)*

| Surface | Audience Modes In Scope | Decision-First Default-Visible Content | Operator Diagnostics | Support / Raw Evidence | One Dominant Next Action | Hidden / Gated By Default | Duplicate-Truth Prevention |
|---|---|---|---|---|---|---|---|
| Tenant shell activity hint | operator-MSP | Operation label, queued/running state, recent terminal-success/follow-up state, elapsed or completion age, canonical open link, honest progress if valid | One concise guidance line only when it clarifies the next step | Raw payloads, failure summaries, logs, debug context | `View operation` | Raw/support detail stays in Operations detail; browser-session hide/dismiss/acknowledge remains local to the shell | The hint states only what is needed for the next decision and does not restate diagnostics-first detail prose |

## UI/UX Surface Classification *(mandatory)*

| 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 shell activity hint | Monitoring hint | Activity shell hint | Open the most relevant active or just-finished operation | One explicit `View operation` link per item | forbidden | Overflow navigation only (`Show all operations`) plus one lifecycle-sensitive tertiary affordance on the grouped action row | none | `/admin/operations?tenant_id={currentTenant}` as a contextual prefilter on initial mount | `/admin/operations/{run}` with current tenant context | Current tenant context from the selected tenant shell | Operations / Operation | Queued/running state, completion/follow-up state, elapsed/completion age, valid progress only while active | none |

## Operator Surface Contract *(mandatory)*

| 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 shell activity hint | Tenant operator | Decide whether a queued/running or just-completed operation needs inspection, acknowledgement, or no action | Start-surface hint | What operation state do I need to react to right now? | Operation label, lifecycle state, elapsed/completion age, canonical open link, valid progress only while active | Detailed run diagnostics and evidence on Operations pages | lifecycle, progress-availability | none | `View operation`, `Show all operations`, lifecycle-sensitive tertiary affordance when needed | none |

**UI Action Matrix**: `N/A - no Filament Resource, RelationManager, or Page action surface is being introduced or reclassified. The changed surface remains a shell/widget hint with one dominant navigation action and no destructive controls.`

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: no by default
- **New enum/state/reason family?**: no
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: queued/running operations do not have one calm, constitution-aligned shell contract today, and the current overlay both blocks primary actions and drops the completion/follow-up loop immediately.
- **Existing structure is insufficient because**: the repo already centralizes links, badges, and guidance semantics, but the current shell implementation does not enforce bounded terminal handoff, honest post-completion semantics, or non-obstructive placement clearly.
- **Narrowest correct implementation**: refactor the existing shell component and views locally, keep `OperationRun` truth authoritative, add a brief terminal-success/follow-up phase plus browser-session hide/dismiss/acknowledge behavior, and update the standards doc.
- **Ownership cost**: one browser-session state rule set, focused Feature/browser coverage, and a standards-doc update.
- **Alternative intentionally rejected**: a shell-only CSS adjustment was rejected because it would not encode the active-only, honest-progress, and canonical-link rules or leave a durable guardrail for future hosts.
- **Release truth**: current-release truth. The repo already owns the active-ops widget and the Ops-UX constitution; this slice aligns the current shell to that truth.

### 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)*

- **Test purpose / classification**: Feature plus one required browser smoke for the non-obstructive shell contract
- **Validation lane(s)**: fast-feedback, confidence, browser
- **Why this classification and these lanes are sufficient**: the real contract is shell behavior on the existing Livewire/Filament host. Feature tests prove active plus bounded terminal selection, links, progress rules, and lifecycle-sensitive tertiary copy; one browser smoke is the narrowest credible proof that the shell remains non-obstructive.
- **New or expanded test families**: extend `apps/platform/tests/Feature/OpsUx/`, extend `apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php`, and add one named browser smoke
- **Fixture / helper cost impact**: low to moderate. Reuse existing operation-run factories, tenant context helpers, and current Livewire widget tests; do not add provider-heavy browser setup or new default seeds.
- **Heavy-family visibility / justification**: no heavy-governance lane. Browser proof is explicit and limited to the overlap/non-obstruction contract.
- **Special surface test profile**: global-context-shell
- **Standard-native relief or required special coverage**: standard Feature coverage is primary; one browser smoke is required for the row-action overlap contract
- **Reviewer handoff**: reviewers must confirm the shell routes through canonical link helpers, shows no fake percentage or percentage text, keeps successful completion visible briefly, does not silently drop follow-up failures, and passes the named browser smoke.
- **Budget / baseline / trend impact**: small feature-local increase only
- **Escalation needed**: `reject-or-split` if implementation expands into tray v2, notification lifecycle changes, or a new persisted hide/acknowledgement model
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage
- **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/ProgressWidgetOverflowTest.php tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php tests/Feature/Guards/OperationRunLinkContractGuardTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/OpsUx/OperationActivityFeedbackSmokeTest.php`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - See Calm Active-Operations Feedback After Starting Work (Priority: P1)

As a tenant operator, I need the shell-level active-ops hint to surface the most relevant queued/running operations without covering page actions, so I can decide whether to inspect a run immediately or keep working.

**Why this priority**: this is the direct fix for the known overlap seam and the most valuable current-release improvement.

**Independent Test**: create queued/running runs for a tenant, open a tenant-scoped start surface, and verify the shell hint shows at most three active items, preserves one canonical `View operation` link per item, and remains non-obstructive.

**Acceptance Scenarios**:

1. **Given** a tenant has queued and running runs, **When** the operator opens a tenant-scoped start surface, **Then** the shell hint shows at most three active items with one canonical `View operation` link each and an overflow path to `Show all operations`.
2. **Given** a row-action-heavy page is visible while the shell hint is active, **When** the operator targets a primary page action, **Then** the activity hint does not cover or block that action.
3. **Given** an active item needs brief context for the next decision, **When** the shell hint renders it, **Then** it may show at most one concise next-step cue and does not expand into diagnostics prose.

---

### User Story 2 - Keep The Feedback Loop Honest Across Terminal Transitions (Priority: P1)

As a tenant operator, I need the shell hint to stay honest when work becomes terminal, so I see a brief success confirmation or an unresolved follow-up state in the same surface instead of losing the feedback loop immediately.

**Why this priority**: the overlap fix is not sufficient unless the shell also completes the run-state feedback loop without inventing a second lifecycle surface.

**Independent Test**: seed queued/running runs alongside just-completed successful runs and terminal follow-up runs, open a tenant-scoped start surface, and verify the shell keeps recent success visible briefly, keeps unresolved follow-up visible, and never shows fake progress after completion.

**Acceptance Scenarios**:

1. **Given** a queued/running run transitions to successful completion, **When** the shell hint refreshes shortly afterward, **Then** it keeps that run visible briefly with a terminal-success state, `View operation`, `Show all operations`, and a `Dismiss` or `Close` tertiary affordance.
2. **Given** a queued/running run transitions to blocked, partial, failed, or reconciled terminal follow-up, **When** the shell hint refreshes, **Then** it keeps that follow-up visible instead of dropping it silently and uses a lifecycle-appropriate tertiary affordance such as `Acknowledge`.
3. **Given** a run exposes deterministic progress counts while active, **When** the shell hint renders that run, **Then** it may show clamped determinate progress, and **When** the run becomes terminal, **Then** it switches to terminal state copy instead of showing fake progress after completion.

---

### User Story 3 - Keep Hide / Dismiss / Acknowledge Browser-Session Only (Priority: P1)

As a tenant operator, I need queued/running, successful, and unresolved terminal hints to use the right local-only affordance for the current browser session, so the activity surface stays calm without inventing a server-side acknowledgement system.

**Why this priority**: it is the smallest safe calmness control that keeps lifecycle semantics explicit while staying within the existing Ops-UX contract.

**Independent Test**: open a tenant-scoped start surface with active and terminal items, use the lifecycle-sensitive tertiary affordances, and verify active items use `Hide activity`, successful terminal items use `Dismiss`/`Close`, unresolved terminal items use `Acknowledge`, and all of those controls remain browser-session-only.

**Acceptance Scenarios**:

1. **Given** queued/running items are visible, **When** the operator uses the tertiary affordance, **Then** it is labeled `Hide activity` and the current browser session remembers that choice without creating any database-backed preference.
2. **Given** only recent successful terminal items are visible, **When** the operator uses the tertiary affordance, **Then** it is labeled `Dismiss` or `Close` and the shell hint may also auto-dismiss after the short terminal-success grace window.
3. **Given** only unresolved terminal follow-up items are visible, **When** the operator uses the tertiary affordance, **Then** it is labeled `Acknowledge` and remains browser-session-only instead of persisting on the `OperationRun` record.
4. **Given** the shell hint is hidden and a new run is accepted in the current browser session, **When** the shared `run-enqueued` event fires, **Then** the shell hint reappears so the operator does not miss newly started work.

### Edge Cases

- No selected tenant or no `viewAny OperationRun` capability means the shell hint stays inert and does not poll or leak rows.
- More than three qualifying shell-visible rows must produce deterministic ordering and an overflow path that routes through the canonical collection helper.
- Just-completed successful runs remain visible only for the short terminal-success grace window and never keep an active progressbar after completion.
- Terminal follow-up runs (`blocked`, `partial`, `failed`, reconciled terminal failures) must not auto-disappear silently from the shell immediately after transition, even though the canonical dashboard/Operations follow-up surfaces remain authoritative.
- The shell hint must not introduce raw route strings; all run detail/collection links continue to flow through the canonical helper family.
- Browser-session hide, dismiss, or acknowledge state must not persist across browser sessions or mutate the `OperationRun` record.

## Requirements *(mandatory)*

**Constitution alignment summary**: This feature adds no Graph calls, no new write path, no new `OperationRun` lifecycle state, and no new persistence. It reuses the existing Ops-UX start contract, keeps `OperationRun.status` / `OperationRun.outcome` service-owned, leaves terminal DB notifications unchanged, and narrows the current global active-ops shell widget to the constitution-safe active-awareness contract.

### Functional Requirements

- **FR-001**: The implementation MUST derive shell activity items from existing `OperationRun` truth plus current shared helpers such as `OperationUxPresenter`, `OperationStatusNormalizer`, `OperationRunLinks`, and badge semantics. It MUST NOT create a second lifecycle, severity model, or persisted projection.
- **FR-002**: The tenant shell activity hint MUST always surface current active runs (`queued|running`) for the current tenant from existing `OperationRun` truth.
- **FR-003**: When a queued/running run transitions to successful completion, the shell hint MUST keep a compact terminal-success state visible briefly in the same surface instead of removing it immediately.
- **FR-004**: The terminal-success state MUST show the operation label, a success pill such as `Completed successfully`, a completion-recency line, concise no-action-needed guidance, canonical `View operation` and `Show all operations` links, and a tertiary `Dismiss` or `Close` affordance. It MUST NOT show fake active progress after completion.
- **FR-005**: Blocked, partial, failed, and reconciled terminal follow-up runs MUST NOT auto-disappear silently from the shell immediately after transition. The shell hint MUST keep them visible on the existing surface until they are acknowledged or otherwise handled through the canonical follow-up surfaces.
- **FR-006**: The tenant shell activity hint MUST show at most three prioritized items for the current tenant and MUST expose one canonical `View operation` link per item plus one canonical overflow path to `Show all operations` when more qualifying items exist. The overflow path MUST open the canonical Operations collection with the selected tenant encoded as the contextual `tenant_id` prefilter; on initial mount that requested tenant prefilter takes precedence over session/default state, and any restored local filters may only narrow within that tenant scope rather than broaden it.
- **FR-007**: The tenant shell activity hint MUST stop behaving as a fixed overlay that covers primary actions. Non-obstructive placement is part of the contract, not an optional polish step.
- **FR-008**: Determinate progress MUST appear only when `summary_counts.total` and `summary_counts.processed` are valid numeric values while the run is active. Determinate progress MUST be clamped to `0-100`, and the shell hint MUST NOT display fake active progress after terminal transition.
- **FR-009**: The lifecycle-sensitive tertiary affordance MUST use state-matching wording: `Hide activity` for queued/running shell hints, `Dismiss` or `Close` for terminal-success hints, and `Acknowledge` for unresolved terminal follow-up hints.
- **FR-010**: Browser-session hide, dismiss, and acknowledge behavior MUST stay browser-session-only. A newly accepted run in the current session MUST re-open the shell hint.
- **FR-011**: The implementation MUST update `docs/ui/tenantpilot-enterprise-ui-standards.md` with the shell activity-feedback pattern, including canonical links, bounded terminal-success/follow-up scope, progressbar eligibility, item limits, lifecycle-sensitive tertiary actions, hide/dismiss/acknowledge boundaries, and anti-patterns such as fake percentages or overlays that cover actions.
- **FR-012**: Operations collection/detail pages remain diagnostics-first drill-through targets. The shell hint MAY show at most one concise next-step cue when it materially clarifies whether inspection is needed, and it MUST NOT duplicate full diagnostics, logs, raw payloads, or support-only evidence.

### Authorization and Safety Requirements

- **AR-001**: Tenant/admin-plane authorization semantics stay unchanged: out-of-scope tenant access remains deny-as-not-found (`404` semantics through current tenant/admin boundaries), while in-scope visibility continues to reuse server-side `OperationRun` policies.
- **AR-002**: No surface in this slice may emit a run row or link the actor cannot already view through the current canonical Operations routes.
- **AR-003**: No destructive or mutating action is introduced. Existing run start surfaces and existing detail pages remain responsible for initiation/retry behavior and any confirmation requirements they already own.

### Non-Functional Requirements

- **NFR-001**: The slice MUST stay Filament-native and Livewire v4-compatible. No panel-provider registration change is allowed; `apps/platform/bootstrap/providers.php` remains authoritative.
- **NFR-002**: No new panel, no new globally searchable resource, and no new asset registration strategy are allowed.
- **NFR-003**: Polling must remain intentional and bounded. The shell hint may continue to use the current poller family, but the implementation must not add parallel uncoordinated polling loops or additional active-awareness hosts in this slice.
- **NFR-004**: Badge semantics remain centralized through existing badge infrastructure; no host surface may add its own status/outcome color mapping.

## Deferred Follow-Ups / Explicit Non-Goals

- Host-widget migration pass beyond the current global shell activity widget
- Polling and UI calmness standard beyond the v1 scope
- Notification/activity lifecycle standardization beyond the current start contract
- Any permanent inbox or tray treatment for terminal/follow-up operation states beyond the bounded shell grace/follow-up contract
- Activity tray / center v2
- Persistent reviewed / investigated semantics over failed or blocked runs

## Key Entities

- **Shell activity item**: a derived, non-persisted summary of one visible `OperationRun` in the shell, including operation label, lifecycle state, canonical detail/collection links, and progress treatment only when truthful.
- **Terminal success shell item**: a derived, non-persisted shell item for a just-completed successful run that remains visible briefly to close the feedback loop and confirm that no further action is needed.
- **Terminal follow-up shell item**: a derived, non-persisted shell item for a blocked, partial, failed, or reconciled terminal run that remains visible on the shell until the operator acknowledges it locally or handles it on the canonical follow-up surfaces.
- **Browser-session shell state**: a non-persisted shell-level state that remembers hide, dismiss, and acknowledge choices only for the current browser session.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: In the focused validation fixture with more than three qualifying tenant rows, the shell activity hint shows no more than three visible items plus exactly one overflow path to `Show all operations`.
- **SC-002**: On the validated row-action-heavy smoke surface, primary page actions remain clickable while the shell activity hint is visible.
- **SC-003**: In validation coverage where a queued/running run transitions to successful completion, the shell activity hint keeps that run visible briefly with success semantics and no fake active progress after completion.
- **SC-004**: In validation coverage where a queued/running run transitions to blocked, partial, failed, or reconciled terminal follow-up, the shell activity hint does not drop that follow-up silently from the shell immediately after transition.
- **SC-005**: The shell hint routes through the canonical helper family and keeps the guard coverage free of new raw operation-link bypasses.