Module http_pty_shell 

PTY shell HTTP handlers. Split out of server/mod.rs unchanged (SPEC_LARGE_FILE_MODULE_ANALYSIS_2026_09_30.md §4.1).

Functions

answer_conpty_handshake_if_seen 🔒

Answer Windows ConPTY’s own startup handshake, if seen, before the caller proceeds. Discovered live (not assumed): the moment a Windows ConPTY is created, it queries the cursor position (ESC[6n, Device Status Report) and blocks its own internal state — and therefore every later write — until it sees a ESC[<row>;<col>R reply. A human-facing term pane gets this for free because xterm.js, running in the browser, answers real cursor queries as part of being an actual terminal emulator; this headless facility has nothing playing that role, so without this the PTY would sit permanently stuck before printing even its first prompt — confirmed by a live round trip that hung indefinitely until this was added. ESC[1;1R (cursor at row 1, col 1) is a plausible-enough fixed answer: nothing here has rendered anything yet, so “top-left” is as true as any other coordinate, and ConPTY only wants to reconcile its internal buffer, not validate the value against anything a person would see.

handle_pty_shell_create 🔒

POST /api/v1/ptyshell/create — attach to (creating if needed) “this pane’s one shell.”

handle_pty_shell_input 🔒

POST /api/v1/ptyshell/input — write raw text to the PTY, as if typed. Unlike /api/v1/shell/input, no newline is appended: a real terminal doesn’t add one either, and PTY programs (readline, Sharprompt) expect the caller to send exactly what a keyboard would (e.g. "y\n" to answer a prompt and press Enter, or "\x03" for Ctrl+C — the OS PTY layer translates that raw byte into a real interrupt delivered to the foreground process, same as a human pressing Ctrl+C in a real terminal, without ending the shell).

handle_pty_shell_read 🔒

POST /api/v1/ptyshell/read — read back the shell’s raw output tail.

handle_pty_shell_resize 🔒

POST /api/v1/ptyshell/resize — resize the PTY. Some TUIs render differently or wrap badly at the fallback geometry (25x200).

handle_pty_shell_status 🔒

POST /api/v1/ptyshell/status — query whether the shell is still running.

handle_pty_shell_stop 🔒

POST /api/v1/ptyshell/stop — release the agent’s lock immediately, without waiting for AGENT_LOCK_WINDOW_MS to lapse on its own.

lock_shell_for_agent 🔒

Lock shell_id out from human keyboard input for AGENT_LOCK_WINDOW_MS from now — called BEFORE every agent write (input/resize), not after (see the call sites’ own comment for why the ordering matters). Best-effort: a failure to write the lock meta just means the human’s input isn’t blocked this time, not that the agent’s write itself failed.

running_shell_conflict 🔒

The 409 for a pane whose agent shell is running (or starting, created by this run) on another connection than connection, checked without touching the shell; the same cases try_attach_to_existing_shell refuses.