Module core 

Shared helpers used by all block controllers (persistent, subprocess, acp).

Extracted to avoid copy-paste across the four controller files. Each controller keeps only its transport-specific logic (PTY / stream-json / ACP) and delegates the common mechanics here.

Constants

META_LAST_FAILURE 🔒

Block metadata key for the last classified agent failure. Written on every non-zero / in-band-error exit; cleared on clean success. The frontend reads this on pane mount so the recovery banner survives tab switches and page reloads without requiring the WPS event to be received in real time.

META_SESSION_ID 🔒

Block metadata key for the persisted agent session ID. Used by the “My Agents” reattach path on the frontend: after a tab reload the picker reads block.meta["agent:sessionid"] and passes it as the --resume value so the CLI picks up the prior conversation.

Functions

apply_working_dir 🔒

Expand the working directory, create it if missing, set it on cmd, and apply all env-var overrides from env_vars.

expand_home_dir 🔒

Expand a leading ~/ or bare ~ to the user’s home directory.

persist_last_failure 🔒

Persist or clear the last agent failure in block metadata.

persist_session_id 🔒

Persist a newly captured session ID to block metadata and broadcast the waveobj:update event so the frontend reflects the change immediately.

spawn_health_watchdog 🔒

Spawn the health-watchdog background task for a turn.