Work on logs, shell exec, debug containers, port-forward, node drain/maintenance, long-running operations, permissions, lifecycle, and cleanup tests
Operations Workflows
Use this when touching logs, shell exec, debug containers, port-forward, node
drain/maintenance, session lifecycle, operation cancellation, permission-gated
actions, or related tests.
Core Contracts
Read:
AGENTS.md
backend/AGENTS.md
frontend/AGENTS.md
docs/workflows/logs/overview.md
docs/workflows/shell-debug.md
docs/architecture/permissions.md
docs/architecture/multi-cluster.md
docs/architecture/auth.md when cluster auth or recovery is involved
docs/workflows/operation-lifecycle.md when touching live operation
registry, cleanup, or status behavior
Backend Entry Points
backend/runtime_operations.go
backend/refresh/containerlogsstream
backend/resources/pods/logs.go
backend/resources/nodes/logs.go
backend/app_logs.go
backend/shell_sessions.go
backend/resources/pods/debug.go
backend/portforward*.go
backend/nodemaintenance
backend/refresh/snapshot/node_maintenance.go
backend/refresh/snapshot/service.go
cluster lifecycle cleanup callers in backend/cluster_clients.go,
backend/kubeconfigs.go, and backend/app_lifecycle.go
Requests and events carry clusterId and full target identity.
Runtime operation entries that target Kubernetes objects carry
clusterId, group, version, kind, and concrete namespace/name
where applicable.
Permission checks and capability reasons are visible in the UI.
Streams, sessions, and long-running operations clean up on close,
disconnect, cluster removal, auth failure, and app shutdown.
Cancellation/stop paths are idempotent.
Frontend cluster-tab close delegates to KubeconfigContext's unified
selection transition; backend selection cleanup handles removed-cluster
runtime operations instead of per-workflow cleanup in UI surfaces.
Shell backlog, port-forward details, and drain history remain owned by
their workflow stores; the runtime registry only owns global presence and
cleanup.
Sessions status renders shell sessions and port forwards only; active
drains may appear in cluster-close warnings but not as Sessions panel
detail rows.
object-maintenance keeps aggregate and node-specific scopes active
concurrently so node drain indicators and an open drain modal do not reset
each other.
object-maintenance remains uncached and singleflight-bypassed in the
backend snapshot service because it represents live app-managed drain
state.
Drain progress and history render in DrainNodeModal; keep the active or
most recent drain attempt visible after a drain starts or completes.
Frontend state resets on cluster/namespace/object changes.
Logs preserve transport-specific behavior documented in the logs docs.
Tests cover lifecycle, permission-denied, and cleanup behavior.
Non-doc changes pass mage qc:prerelease.
Validation
Use focused checks while iterating:
go test ./backend ./backend/resources/pods ./backend/resources/nodes ./backend/nodemaintenance
go test ./backend/refresh/snapshot
npm run typecheck --prefix frontend
npm run test --prefix frontend -- Logs Shell port-forward drain orchestrator
Then run mage qc:prerelease for non-documentation changes.
