REFERENCE

Terminal compatibility

KubeRich runs in a local terminal, over SSH, or inside tmux. Its default container shell stays inside the Textual interface. Explicit native tools, including Azure login, temporarily receive the terminal and return to the workspace.

The minimum qualified workspace size is 40 columns by 12 rows. Use a UTF-8 locale and a terminal advertising its actual capabilities. The automated tmux fixture uses -u and screen-256color; its configuration is isolated from user settings. Standard 16-color rendering and NO_COLOR input/navigation receive terminal checks. This does not establish compatibility with every terminal emulator, locale, Unicode font, or custom tmux configuration.

Shutdown and reconnection

Normal exits, Ctrl+C, Ctrl+Q, external SIGTERM and external SIGHUP unwind owned processes and streams. SIGTERM returns 143; SIGHUP returns 129. Native handoffs restore foreground ownership and terminal attributes before returning. Embedded shells own a separate PTY and reap their child when closed, including cancellation while the pod preflight is still pending.

Losing SSH without a multiplexer revokes the remote terminal. KubeRich closes its tasks and child processes, then exits 129; the SSH client normally returns 255. The local SSH terminal can be restored, but a revoked remote TTY cannot receive escape sequences. Its attributes may be unavailable; Darwin can retain readable attributes while rejecting output. Evidence preserves the actual observation instead of claiming remote restoration. Only captured output descriptors still identifying that revoked TTY are redirected to /dev/null during hangup. Live terminals, replaced descriptors and file/pipe output remain untouched. This prevents failed buffered shutdown writes from changing the process exit code to 120. A zero-byte write verifies output when the driver still returns attributes; it emits no terminal input or output. The probe temporarily blocks SIGTTOU, restores the previous mask, and surfaces unexpected errors.

Inside tmux, losing SSH detaches the client and keeps the application and an open embedded shell running. Reattaching to the same session restores the workspace; normal shell return and application shutdown still close owned resources.

Tested scope and limits

Source tests cover Ubuntu 24.04 x86_64 and macOS 26 ARM with Python 3.12–3.14; standalone and Homebrew installations have separate native host/architecture checks. See installation scope. Each release candidate needs fresh qualification before its public channels are activated.

Automated PTY tests exercise actual input, output, resize, shutdown and terminal restoration, including local SSH and tmux transports. They do not certify every physical terminal emulator, font, SSH policy or host clipboard. macOS 14 Intel physical trials and real cloud-provider compatibility remain separate limits.

Use :ctx/:ns if your terminal consumes F2/F3, and :back/:forward if Alt navigation is intercepted. The current view's ? help shows available actions. Embedded shells forward ordinary keys to the remote program; local history review has separate keys. Shell controls describes return and session closure. Troubleshooting distinguishes connection, permission and terminal failures.