PTY and shell integration

PTY sessions are long-lived interactive processes managed by Rust and rendered by xterm.js.

Session lifecycle

  1. The terminal bridge requests a spawn with a workspace environment, cwd, dimensions and output channel.
  2. Rust validates the cwd against the workspace authorization registry.
  3. The shell is launched with platform-specific integration scripts.
  4. A reader thread forwards output through the channel and tracks OSC state.
  5. Resize and input calls are forwarded to the PTY.
  6. Closing a tab kills the session and its process descendants according to the platform lifecycle.

Shell startup

The injected scripts live under src-tauri/src/modules/pty/scripts/.

Platform Shells Integration
Unix zsh, bash, fish OSC 7 cwd and OSC 133 command boundaries.
Windows PowerShell 7, Windows PowerShell Profile wrapper preserving the user prompt plus OSC markers.
Windows cmd.exe Interactive shell without full marker integration.

The frontend normalizes OSC paths to forward-slash canonical form. The native boundary accepts the platform path form needed by the OS.

OSC protocol

  • OSC 7 identifies the current working directory.
  • OSC 133 A marks prompt start.
  • OSC 133 B marks command input.
  • OSC 133 C marks command execution.
  • OSC 133 D marks command completion and exit status.
  • OSC 777 carries named coding-agent state transitions.

The agent detector uses OSC sequences only. It does not infer state from arbitrary terminal output, which prevents repainting TUIs from generating false notifications.

Windows lifecycle

ConPTY spawns are serialized by SPAWN_LOCK because concurrent openpty and process creation can leave an output pipe stalled under fast tab creation. Each session receives a Job Object with kill-on-close behavior so descendants such as a development server do not survive a closed terminal.

Input contract

Voktty sends carriage return (\\r) for Enter. PowerShell on Windows requires this distinction from line feed input. Input paths and shell arguments are escaped at the boundary that creates them.

Invariants

  • A spawn cwd must be authorized.
  • Windows ConPTY spawn locking must remain around the native spawn sequence.
  • Closing a session must terminate its descendant tree on Windows.
  • OSC parsing must remain independent from raw output heuristics.
  • Terminal input must use CR for Enter.