bug: sandbox detach fails with Kitty keyboard protocol and leaks terminal state

[johnnygreco]

User Story

As a user running an interactive terminal application in a reconnectable sandbox, I want to disconnect without terminating the application, so that I can safely return to my local shell and reconnect to the same live session later.

Problem Statement

The documented Ctrl-P, then Ctrl-Q sandbox detach sequence does not work when the attached application enables the Kitty keyboard protocol (CSI-u keyboard encoding).

In this state, pressing Ctrl-P is observed by the attached application instead of initiating OpenShell's detach sequence. The application may handle it as one of its own shortcuts, and the connection remains attached.

Using the SSH transport's escape mechanism as a fallback closes the connection, but the local terminal can remain in the extended keyboard mode enabled by the still-running remote application. After control returns to the local shell, normal keystrokes appear as CSI-u fragments and control or navigation keys no longer behave normally.

The application remains alive by design, so it does not run its normal terminal cleanup. A subsequent reconnect must also leave the terminal and application in compatible input modes without restarting the application.

Impact / Why This Matters

This blocks the intended reconnectable-session workflow for interactive terminal applications that use modern keyboard protocols. Pi is one known reproducer, but the behavior is not specific to a particular agent or application.

Users currently have to either terminate the application cleanly, losing the live session they intended to preserve, or forcibly disconnect and then manually reset or reopen their local terminal. The detach keystroke can also trigger an unintended application action because it is delivered to the remote process.

These workarounds defeat the purpose of a persistent, reconnectable main process and make it unsafe or disruptive to leave an interactive session running.

Acceptance Criteria

• The documented detach workflow succeeds while the attached application has enabled the Kitty keyboard protocol.
• Input used to request detach is not delivered to the attached application.
• Detaching does not terminate, suspend, send EOF to, or otherwise disrupt the sandbox's canonical main process.
• Returning from the attachment leaves the local shell in a usable terminal state without visible CSI-u fragments or broken control and navigation keys.
• Reconnecting attaches to the same running process and provides the keyboard/input mode expected by the application without requiring an application restart.
• Detach continues to work with terminals and applications that use traditional control-byte input.
• Published documentation describes the supported detach behavior for interactive, reconnectable sessions.
• Regression coverage exercises both traditional control-byte input and Kitty-encoded input where practical.

Reproduction Steps

1. From a CSI-u-capable terminal, start a reconnectable sandbox whose retained main process is an interactive terminal application that enables the Kitty keyboard protocol.
2. Attach to the retained process and confirm that the application is interactive.
3. Press OpenShell's documented detach sequence.
4. Observe that the first keystroke is handled by the application and the session remains attached.
5. Disconnect using the SSH transport's escape mechanism so that the remote application remains running.
6. At the restored local shell prompt, type normally.
7. Observe CSI-u fragments in the input or incorrectly behaving control and navigation keys.

Environment

• OpenShell: observed with a recent Homebrew installation; exact affected version was not captured
• Latest release checked before filing: v0.0.116
• OS: macOS
• Host shell: zsh
• Runtime: local Homebrew gateway with a Docker-backed sandbox
• Integration: interactive TUI that enables the Kitty keyboard protocol; Pi is a known reproducer
• Terminal: CSI-u-capable terminal; exact emulator and version were not captured

Logs

08;5:1u08;5:3u7;5:

The excerpt is representative text appearing at the local shell prompt after disconnecting. No credentials or request data are included.

Related Work

• #2710 defines the reconnectable canonical-main-process behavior.
• #2726 implements retained sessions and detach behavior.
• #2392 discusses terminal-state pollution after returning from an interactive sandbox shell.
• earendil-works/pi#5724 reports terminal corruption when Kitty keyboard mode is not disabled during cleanup.
• earendil-works/pi#1204 describes Kitty keyboard events leaking across an SSH session.
• earendil-works/pi#3918 reports CSI-u input reaching the parent shell when terminal cleanup does not run.