Module 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.

Structs

CmdEnvOverrides 🔒

The cmd:env part of an interactive shell’s environment, computed from the global settings and the block’s own metadata. See cmd_env_overrides.

PtyReadChunk 🔒

One PTY read’s worth of already-OSC-cleaned output, on its way from the blocking read loop to the coalescing flusher (start(), below). See docs/reports/REPORT_RENDERER_CPU_UNBATCHED_PTY_OUTPUT_2026_09_11.md.

Functions

cmd_env_overrides 🔒

Compute an interactive shell’s cmd:env overrides.

flush_barrier 🔒

Ask the output flusher to confirm that everything enqueued so far has been committed, bounded by timeout.

flush_pty_batch 🔒

Do the actual per-batch work the read loop used to do per-read: write through to the FileStore, broadcast the raw bytes, publish any OSC activity, and (for agent panes) feed the JSON-stream translator. Called once per coalesced batch instead of once per (up to 4KB) PTY read.

is_global_cmd_env_injectable 🔒

Whether key may be injected into a pane’s actual OS environment from the global settings’ cmd_env defaults (cmd_env_overrides, lowest priority — the block’s own cmd:env override, highest priority, is never filtered by this and can always set either key explicitly). Identity keys are excluded (reagentx P1, round 2 on #2694): without this, a global cmd_env.AGENTMUX_AGENT_ID setting would still land in every pane’s real environment even though resolve_agent_id_for_jekt never reads it for registration — shell integration echoes an injected AGENTMUX_AGENT_ID back via OSC 16162, and the frontend’s own POST /agentmux/reactive/register path (triggered by that OSC) would pick it up and register the pane under the shared value anyway, silently reopening the same-host identity collision this PR removes from the backend auto-register path specifically.

release_lease_if_current 🔒

Release block_id’s PtyShell agent lease — both copies — but ONLY if inner still identifies the controller currently registered for that block. Returns whether it released.

resolve_agent_id_for_jekt 🔒

Resolve the effective AGENTMUX_AGENT_ID for jekt auto-registration from a block’s own spawn metadata — both the canonical key and the legacy WAVEMUX_AGENT_ID alias, checked in the SAME block-scoped cmd:env map. Deliberately does NOT fall back to std::env::var for either key: that reads THIS SRV PROCESS’s own environment, shared by every block/pane this instance spawns — reintroducing exactly the same collision as the global-settings fallback below (#2694). Nor does it fall back to the global settings’ cmd_env.AGENTMUX_AGENT_ID: that value is shared across every pane in the instance/channel, so a pane spawned without its own explicit per-block ID would silently inherit whatever another pane happened to configure there — and register_agent_with_nonce unconditionally evicts whoever previously held that agent_key, so the second such pane to register silently steals the first’s jekt identity (same-host cross-instance jekt misdelivery). See cmd_env_overrides below (its settings.cmd_env loop) for the matching fix that keeps this global value out of the pane’s OWN environment too — otherwise a pane could still pick it up via OSC 16162 and re-register through the frontend’s /agentmux/reactive/register path instead, even with THIS function never reading it directly. A pane with no block-scoped identity is simply not jekt-registered, matching persistent/mod.rs’s muxbus_agent_id_from_env, which never had either fallback.

run_pty_output_flusher 🔒

Drain rx, coalescing into batches whatever is already queued at the moment each batch is assembled — never waiting on output that has not arrived, and bounded by PTY_COALESCE_MAX_BYTES — then flushing each batch through flush_pty_batch. Runs until rx closes (the PTY read loop’s sender dropped, i.e. the PTY hit EOF or an error), flushing any final partial batch before returning.