Module blockcontroller 

Block controller: manages lifecycle of each block (terminal, command, web app). Port of Go’s pkg/blockcontroller/blockcontroller.go.

Architecture:

• Global controller registry maps block_id → Controller
• Each controller manages the lifecycle of one block
• ShellController handles “shell” and “cmd” block types
• Controllers dispatch I/O between the user and the process/service

Modules

acp

AcpController: manages agent CLIs that speak the Agent Client Protocol (ACP).

health

Agent health/liveness monitoring.

persistent

PersistentSubprocessController: manages agent CLI as a long-running process with bidirectional NDJSON streaming via stdin/stdout.

pidregistry

Block PID registry: maps blockId → OS process ID for per-pane metrics collection. Used by the sysinfo loop to query per-process CPU/memory stats.

process_tree

Process tree traversal: BFS from a root PID to collect all descendant PIDs. Used by the sysinfo loop to aggregate CPU/memory across entire process trees.

session_recovery

Session recovery after unclean shutdown (Phase 4.2 — ultra-long-sessions).

session_stats

Session metadata tracking for agent panes (Phase 1.4 — ultra-long-sessions).

shell

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

subprocess

SubprocessController: manages agent CLI as stateless per-turn subprocess invocations.

watchdog

Agent process watchdog: kills agent panes that exceed max-runtime or idle-output limits.

Structs

BlockControllerRuntimeStatus

Runtime status of a block controller, sent to the UI.

BlockInputUnion

Input sent to a block controller. Can be raw terminal data, a signal, or a resize event.

Constants

BLOCK_CONTROLLER_ACP

BLOCK_CONTROLLER_CMD

BLOCK_CONTROLLER_PERSISTENT

BLOCK_CONTROLLER_SHELL

BLOCK_CONTROLLER_SUBPROCESS

BLOCK_CONTROLLER_TSUNAMI

DEFAULT_GRACEFUL_KILL_WAIT_MS

Grace period before forceful kill in milliseconds.

DEFAULT_TIMEOUT_MS

Default controller operation timeout in milliseconds.

META_KEY_CMD

META_KEY_CMD_ARGS

META_KEY_CMD_CLEAR_ON_START

META_KEY_CMD_CLOSE_ON_EXIT

META_KEY_CMD_CLOSE_ON_EXIT_DELAY

META_KEY_CMD_CLOSE_ON_EXIT_FORCE

META_KEY_CMD_CWD

META_KEY_CMD_ENV

META_KEY_CMD_INIT_SCRIPT

META_KEY_CMD_INIT_SCRIPT_BASH

META_KEY_CMD_INIT_SCRIPT_FISH

META_KEY_CMD_INIT_SCRIPT_PWSH

META_KEY_CMD_INIT_SCRIPT_ZSH

META_KEY_CMD_JWT

META_KEY_CMD_RUN_ONCE

META_KEY_CMD_RUN_ON_START

META_KEY_CMD_SHELL

META_KEY_CONNECTION

META_KEY_CONTROLLER

META_KEY_TERM_LOCAL_SHELL_OPTS

META_KEY_TERM_LOCAL_SHELL_PATH

STATUS_DONE

STATUS_INIT

STATUS_RUNNING

Statics

CONTROLLER_REGISTRY 🔒

Thread-safe global controller registry. Maps block_id → Arc.

Traits

Controller

Trait for block controllers. Each block type has its own implementation. Port of Go’s blockcontroller.Controller interface.

Functions

delete_controller

Unregister (delete) a controller by block ID, stopping it first. Removes from the registry before calling stop() so no new callers can reach it.

get_all_controllers

Get all controllers (snapshot).

get_block_controller_status

Get the runtime status for a block’s controller. Returns None if no controller is registered.

get_controller

Get a controller by block ID.

is_false 🔒

publish_controller_status

Publish a controller status event via WPS broker.

register_controller

Register a controller, stopping any previous one for the same block.

resync_controller

Resync a block’s controller — the main entry point for starting/restarting blocks. Port of Go’s ResyncController.

send_input

Send input to a block’s controller.

stop_all_controllers

Stop all running controllers gracefully.

stop_block_controller

Stop a block’s controller gracefully.