--- created: 2026-09-19 status: complete requirements: - REQ-EXECUTORS-TASK-STATUS-001 system_design: - ../../specs/executors/system-design/task-status-indicators.md legacy_specs: - ../../specs/kubernetes-executor/spec.md --- # Implementation Plan: Sidebar executor status ## Overview and evidence Source tracing establishes two defects: `useRemoteExecutorStatus` loads on mount or identity change only, and the resource has no timer or visibility listener. Hover/focus explicitly refreshes, explaining a mounted icon staying stale until interaction. `StatusTrigger` destructures a fixed prop list and drops the Radix DOM ref and injected properties. The component tests mock Tooltip/Drawer as fragments, so they do not verify anchoring or real trigger linkage. This is a confirmed composition defect; its exact rendered symptom still requires E2E. At design time frontend dependencies were absent. Implementation installed them and verified the real primitive linkage and browser behavior below. The earlier completed [preview repair](../kubernetes-executor-task-status-preview-repair/plan.md) introduced eager hydration and explicitly excluded periodic polling. This package supersedes that exclusion for mounted consumers in visible documents and repairs primitive composition. Its historical test results are not evidence for this fix. ## Scope and technical approach One sequential vertical work order repairs the shared resource lifecycle and trigger composition, adds real-primitive and lifecycle regressions, and verifies desktop/mobile flows. Reuse existing summaries, localized labels, exact-scope requests, and safe error projection. No new API, executor lifecycle behavior, settings UI or unrelated tooltip refactor is in scope. ## ASCII UI preview UI-01: Sidebar indicator, desktop hover/focus (AC .1/.3). ```text Task title [executor glyph] +---------------------------+ | Pod / executor name | | State Running | | Restarts 0 | | Workspace Persistent | | Last check just now | +---------------------------+ ``` UI-02: Phone task-list indicator, tapped (AC .4). ```text Task list remains behind drawer +--------------------------------+ | Executor name [X] | fixed header | State / restarts / workspace | scrolling body | Created / last check | | Error or updating, when needed | +--------------------------------+ safe area ``` The anchored desktop surface and short touch drawer are required. Labels and spacing are illustrative and localized. Loading retains facts; failures use a text row. Preserve dense desktop row height and a non-overlapping 44 px touch hit area. No hover is required for ongoing status updates. ## Tests AC .1/.2: extend `remote-executor-status-resource.test.ts` with fake-clock cases for no-interaction refresh, sharing, failed reads, absent transport, visibility, unmount and obsolete scope settlement. Assert request counts as well as outcomes. AC .3/.4: new `remote-cloud-tooltip-primitives.test.tsx` uses actual TooltipProvider, Tooltip and Drawer; asserts trigger aria linkage, focus opening, Escape, content and focus return. Existing mocked tests remain useful for summary projections. ## E2E tests Extend existing `settings/kubernetes-task-environment.spec.ts` and `settings/mobile-kubernetes-task-environment.spec.ts`. Change the exact-session response while mounted, advance controlled time, await the causal request, and assert tone before pointer interaction. Desktop hover/focus must show a panel anchored near the icon, inside the viewport. Mobile taps must open the drawer, show the same facts and preserve task selection on dismissal. Verify hit area, adjacent controls, internal scroll, safe area and no horizontal overflow. ## Work orders - [x] [Task 01: Refresh and disclose executor status](task-01-refresh-and-disclose.md) ## Verification commands ```bash (cd apps && pnpm install --frozen-lockfile) (cd apps/web && pnpm exec vitest run hooks/domains/session/remote-executor-status-transport.test.ts hooks/domains/session/remote-executor-status-resource.test.ts components/task/remote-cloud-tooltip.test.tsx components/task/remote-cloud-tooltip-primitives.test.tsx) (cd apps/web && NODE_OPTIONS=--max-old-space-size=3072 pnpm run typecheck) (cd apps/web && pnpm run i18n:check) (cd apps/web && PATH=/usr/local/go/bin:$PATH pnpm e2e:run --host --project=chromium tests/settings/kubernetes-task-environment.spec.ts -- --retries=0) (cd apps/web && PATH=/usr/local/go/bin:$PATH pnpm e2e:run --host --no-build --project=mobile-chrome tests/settings/mobile-kubernetes-task-environment.spec.ts -- --retries=0) python3 scripts/list-docs.py validate python3 scripts/lint-spec-files.py --all git diff --check ``` ## Verification results Implementation and targeted verification complete. - RED: no-interaction refresh, automatic retry, and visibility-return tests failed on stale/missing status. The real Tooltip regression failed because the DOM trigger had no `aria-describedby` linkage. - GREEN: the listed focused Vitest command passes 29 tests in 4 files. - Changed-file ESLint with `--max-warnings=0` passes. - Fresh managed production build passes. Desktop Chromium E2E: 1/1, 4.3 seconds; mobile Chrome E2E: 1/1, 5.7 seconds; both with `--retries=0`. These verify automatic updates before interaction, anchored desktop details, touch drawer facts, no task selection, focus return, and horizontal containment. - `pnpm run i18n:check` passes. Public-doc validation passes for 47 pages. Catalog validation, specification lint, and `git diff --check` pass. - Full `pnpm run typecheck` could not complete: Node exhausted both its default 2 GB heap and a 3 GB heap in this 4 GB environment. This remains an explicit full-project validation limitation, not a passing check. - Focused typecheck passes with the repository tsconfig, changed production/test roots, actual transitive dependencies, web ambient declaration files, and explicit Node/React ambient types. It used `/tmp/executor-status-tsconfig.json` with incremental checking disabled and a 3 GB heap. No compiler errors were suppressed. This does not replace full-project typecheck evidence. - Ready PR delivery was explicitly requested after user testing. Full-project typecheck remains an explicit validation limitation for CI. Managed E2E instances and the isolated user preview were stopped; the main instance was untouched. Generated typecheck crash dumps were removed. ## Risks - Polling scales with distinct mounted scopes; share requests, stop on hidden documents/unmount, and preserve existing cache bounds. - Real primitives may expose additional focus/portal issues hidden by mocks. - Browser throttling can delay timers; returning to visibility must recover. ## Public documentation At implementation, update `docs/public/k8s.md` and `docs/public/executors.md` with automatic refresh while visible. Preserve their how-to/reference structure. No public claim changes during this design-only turn. ### PR review remediation Greptile identified obsolete queued WebSocket reads during outages. The default requester now treats a disconnected client as unavailable transport. The new transport regression failed with four offline requests before the guard, then passed with zero offline reads and a healthy result after reconnect. All 27 focused tests and changed-file ESLint pass. No UI, API or public-doc contract changed; the system design records the transport guard. Remote CI/review verification remains pending for the remediation commit. CodeRabbit summary findings: unavailable transport now immediately publishes the sanitized unavailable snapshot; primitive classes and touch handlers are composed. The unavailable-state assertion failed before the fix. Actual-drawer coverage now exercises click, Enter and Space, with no task selection. All 29 focused tests and changed-file lint pass; mobile E2E passes 1/1 without retries after a fresh build. Desktop E2E also passes 1/1 without retries, and the focused TypeScript check passes.