Module shell 

ShellController: manages lifecycle of shell and command blocks. Port of Go’s pkg/blockcontroller/shellcontroller.go.

State machine: INIT ─(start)─> RUNNING ─(exit/stop)─> DONE DONE ─(resync+force)─> RUNNING

I/O model (3 async tasks when running):

1. PTY read loop: process stdout → FileStore + MPS event
2. Input loop: input channel → process stdin
3. Wait loop: monitor process exit, update status

Module layout

This was one 2,394-line file; it is now a submodule directory (pure reorganization, no logic changes). The impl Controller for ShellController block is kept whole in lifecycle — a trait impl cannot be split across files — and it calls the free-function helpers extracted into pty, file_ops, indexing, and translation. The struct definitions, constructor, and small accessor/meta helpers live in controller.

The pub use re-exports below preserve the pre-split flat paths (shell::<item>) that callers elsewhere in the crate already import, so the reorganization changed no call site.

Re-exports

pub use controller::ShellController;

pub use file_ops::append_output_line;

pub use file_ops::handle_append_block_file;

pub use file_ops::persist_user_line;

pub use file_ops::publish_transcript_changed;

pub use file_ops::with_transcript_order;

Modules

controller 🔒

ShellController struct + inner state definitions, constructor, and the small accessor / lock / meta helpers. The Controller trait impl and the spawn/IO orchestration live in super::lifecycle.

file_ops 🔒

Block-file append/persist helpers and global-transcript mirroring.

indexing 🔒

output.idx rebuild: a lazily-built, self-validating line-offset cache.

lifecycle 🔒

The impl Controller for ShellController block: start/stop/send_input/ get_runtime_status. Kept whole in one file (a trait impl cannot be split across modules); it orchestrates the helpers extracted into the sibling pty, file_ops, and translation modules.

pty 🔒

PTY geometry resolution and platform-specific shell detection.

spawn_cwd 🔒

ssh_pane 🔒

How a plain SSH pane ends (remote terminals spec §5.2; #4513).

stamps 🔒

Receive-time stamps for a range of transcript lines, from the output.tsidx sidecar — without loading the sidecar whole.

translation 🔒

Agent-event extraction and translation (Phase 1.5 PR 1). Feeds agent-pane stdout through the Claude stream-json translator and publishes AgentEvents.