Files
kandev/docs/plans/sidebar-executor-status/plan.md
T

168 lines
8.0 KiB
Markdown

---
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.