Opens a persistent SSH connection and returns a session_id for use with
`execute`. The connection stays open until `disconnect`. Host keys are
auto-accepted. For local commands, call `execute` directly — no session needed.

PARAMETER GUIDANCE: Reuse session_id across multiple execute calls —
each connect_ssh opens a new TCP connection. key_filepath is tried
first when both key and password are provided; password acts as
fallback. With neither, SSH agent and system defaults are used. The
username defaults to the OS user if omitted. host is resolved at
connect time; unresolvable names raise an error. banner_timeout
controls MOTD capture — if exceeded, banner returns "" (not an error);
set to 0 to skip capture entirely.

SIDE EFFECTS: Opens a TCP socket with a 30-second keepalive. Leaks
the socket if `disconnect` is never called.

ERRORS: Raises on auth failure, unresolvable host, refused connection,
or network timeout.

RETURNS: {"session_id": str, "banner": str}

Execute a command locally or over SSH in an isolated channel.
Local: just pass command (defaults to cmd.exe/bash).
SSH: also pass session_id from connect_ssh.

PARAMETER GUIDANCE: session_id selects SSH vs local; shell only
applies to local. Chain with && for multi-step; use Zellij
for persistent state. Raise pause_timeout (not total_timeout) for
quiet jobs. Raises ValueError if session_id is invalid.

WHEN NOT TO USE: respond (stdin), send_control (keys), read_output (poll).

SIDE EFFECTS: Spawns a process. Partial commands live until finished
or interrupted. TUI apps MUST start in foreground — never use &.

RETURNS:
- {"status": "completed", "output": str, "exit_code": int}
- {"status": "partial", "output": str, "command_id": str}

Write text to a running command's stdin. Works for prompts (y/n,
passwords), shell input, or any text the process expects.

PARAMETER GUIDANCE: text auto-appends \n if missing. For control
keys use send_control — AI frameworks strip control bytes. Raise
pause_timeout (not total_timeout) for slow responses after input.
Raises ValueError if command_id is invalid or completed.

WHEN NOT TO USE: Inside zellij, prefer multiplexer CLI via execute.

SIDE EFFECTS: Writes to stdin; may trigger output, state change, or exit.

RETURNS:
- {"status": "partial", "output": str, "command_id": str}
- {"status": "completed", "output": str, "exit_code": int}

Poll new output from a running command without sending input. Use after
execute returns status="partial" for non-interactive commands (builds,
training loops, long searches).

Each call returns only output produced since the last read. When the
command finishes, status changes to "completed" and the command_id is
retired — further calls raise ValueError.

WHEN NOT TO USE: If the command expects input, use respond. If you
need to interrupt or send keys, use send_control.

PARAMETER GUIDANCE: pause_timeout is the primary dial — it controls
how long to wait when the command is silent. total_timeout only caps
actively streaming output and has no effect during silence.

ERRORS: Raises ValueError if command_id is invalid or already completed.

RETURNS:
- {"status": "partial", "output": str, "command_id": str}
- {"status": "completed", "output": str, "exit_code": int}

Send a control key or escape sequence to a running command. Use for
interrupts (ctrl+c), TUI navigation (arrows, F-keys), or any
non-printable input. Prefer this over `respond` for control keys —
AI frameworks strip raw control bytes from string arguments.

SIGNAL HANDLING: The signal parameter accepts any key name from the
supported list (case-insensitive, whitespace-tolerant — "Ctrl + C"
works). Common signals: ctrl+c (SIGINT/interrupt), ctrl+z (SIGTSTP/
suspend), ctrl+d (EOF), ctrl+\ (SIGQUIT). Local non-PTY subprocesses
only react to ctrl+c, ctrl+z, ctrl+\; SSH and PTY channels accept all.

SIDE EFFECTS: The signal may terminate the command (e.g. ctrl+c),
making the command_id invalid on the next read.

TIMEOUT INTERACTION: pause_timeout controls how long to wait for
output after the signal. Raise it for slow TUI repaints over
high-latency SSH; total_timeout only binds during active streaming.

ERRORS: Raises ValueError if command_id is invalid, already completed,
or signal name is unrecognized.

RETURNS: Same format as execute —
{"status": "completed"|"partial", "output": str, ...}

Close an SSH session and release all associated resources. NOT needed
for local commands — those clean up automatically.

SESSION_ID LIFECYCLE: The id is an opaque UUID created by connect_ssh,
used with execute, and retired by this call. Each connect_ssh produces
a unique id — reconnecting the same host gives a new one. After
disconnect, execute() with the old id raises ValueError. Calling
disconnect on an already-closed or unknown id is a safe no-op
(idempotent), so cleanup logic never needs to guard against double-close.

SIDE EFFECTS: Terminates all running commands on this session (their
command_ids become invalid), closes SSH channels and TCP socket.

WHEN NOT TO USE: To stop a single command without closing the session,
use send_control with "ctrl+c" instead.

RETURNS: true (always succeeds).