Module http_shell 

Shell drawer HTTP handlers and the agent shell lock. Split out of server/mod.rs unchanged (SPEC_LARGE_FILE_MODULE_ANALYSIS_2026_09_30.md §4.1).

Constants

AGENT_LOCK_WINDOW_MS 🔒

META_KEY_AGENT_LOCK_UNTIL 🔒

META_KEY_PTYSHELL_BOOT_ID 🔒

Block meta on a PtyShell block: the srv boot id of the run that created it.

Functions

broadcast_meta_update 🔒

Merge meta_update into block_id’s meta and broadcast a waveobj:update WS event so every subscribed frontend (the drawer, if open) picks it up immediately — the same two steps the setmeta WS handler performs (websocket.rs’s COMMAND_SET_META handler), factored out since ptyshell/* needs the identical pattern from a plain HTTP handler with no WshRpcEngine in scope.

clear_shell_pointer_if 🔒

Clear the agent block’s shell pointer, if it still names id (see the exited-shell branch of try_attach_to_existing_shell for why it is compare-before-clear), so the next create claims a fresh shell.

connection_conflict 🔒

409 when the pane’s running shell is on another connection than wanted. PtyShellStop releases the keyboard lock and leaves the shell running, so ending the shell is the way to switch.

handle_shell_create 🔒

POST /api/v1/shell/create — start a persistent background shell.

handle_shell_input 🔒

POST /api/v1/shell/input — write text to a running shell’s stdin (Phase 3b).

handle_shell_status 🔒

POST /api/v1/shell/status — query a shell’s running state (Phase 3b).

handle_shell_stop 🔒

POST /api/v1/shell/stop — stop a running persistent shell.

is_owned_by_agent 🔒

Whether shell_id is a real view:"term" sub-block PARENTED TO agent_block_id — the actual safety property Codex asked for (PR #3177): shell_id lives in the same block-id namespace as every other pane, and Layout exposes block ids for ordinary panes, so without this check an agent could point PtyShellInput/PtyShellStop/etc. at any controller-backed block (another agent’s own CLI pane, a human’s terminal pane) and inject input into it or tear it down. Framed as parentage rather than “did PtyShell create it” (the original, narrower check) specifically so it also covers the reuse case above: a shell the HUMAN created via the drawer is just as legitimate a target as one PtyShell created itself, as long as it’s this agent’s own pane.

try_attach_to_existing_shell 🔒

Shared by both the top-level reuse check and the “lost the atomic claim” fallback in handle_pty_shell_create: resync id’s controller and reply, or return None if id doesn’t resolve to a real block (stale pointer), OR if its shell has already exited, so the caller falls through to creating a fresh one. A pane has one agent shell: asking for it, while it runs, on another connection than its own is refused (409), not answered with the shell on the wrong machine. An exited one is replaced whatever its connection was.