Skip to content

Expose alternate-screen and slave input modes in PTY status #130

Description

@myobie

Problem

A live PTY can remain in a Vim/Codex-like full-screen and raw-input state after detach. PTY already tracks DEC alternate-screen entry/exit internally (altScreenActive) plus mouse, cursor, and Kitty keyboard modes, but live stats omit alternate-screen. PTY does not expose the slave TTY termios state, so consumers cannot distinguish canonical input from noncanonical/raw input through a stable API.

TERMINAL_SANITIZE restores the attaching operator's host terminal on detach; it does not change the child PTY's alternate buffer or slave line discipline.

Read-only contract

Extend existing live status diagnostics without making them an idle oracle:

modes: {
  alternateScreen: boolean;
  bracketedPaste: boolean;
  applicationCursor: boolean;
  sgrMouse: boolean;
  cursorHidden: boolean;
  kittyKeyboard: boolean;
  kittyKeyboardFlags: number[];
  input: {
    state: "canonical" | "noncanonical" | "raw" | "unknown";
    canonical: boolean | null;
    echo: boolean | null;
    signals: boolean | null;
    extended: boolean | null;
    min?: number;
    time?: number;
  };
}
  • alternateScreen comes from the daemon's existing DECSET/DECRST tracking, cross-checked with xterm's active buffer.
  • Exact Unix input state must come from tcgetattr on the PTY slave/master through a supported node-pty/native boundary; do not parse screen text or infer raw mode from Kitty/mouse/cursor sequences.
  • Unsupported platforms return unknown, never a guessed safe value.
  • These are diagnostics/policy inputs, not semantic idle. Codex can legitimately be idle at its prompt while alternate-screen and raw input remain active; a generic unknown-harness policy may still choose to withhold typing.

Current observed proof

The live Codex PTY remained process-alive with no attached viewers while its slave TTY reported -icanon -isig -iexten -echo, min=1, time=0, raw-style input/output flags, and CS8. Live PTY stats simultaneously reported Kitty keyboard protocol active. That proves the child PTY stays in a raw application-input mode; current public stats cannot prove alternate-screen because the tracked flag is omitted.

Model-free acceptance tests

Use stable ASCII screen plus termios/mode fixtures for:

  • alternate-screen enter and retained state after detach;
  • raw/noncanonical slave mode and long-running child;
  • terminal restore (DECRST plus canonical termios);
  • clear/compaction without false restoration;
  • child crash while modes remain diagnosable until daemon cleanup;
  • daemon restart resets output-mode trackers and reports input unknown until observed;
  • stale screen/event logs cannot populate live mode state.

No deployment. Keep harness-specific idle decisions outside PTY core.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions