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

broadcast_block_update 🔒

Broadcast the block’s current state as a waveobj:update on block:<id>, so an open pane sees a meta write live. Does nothing if the block can’t be read.

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.

sync_instance_session_id 🔒

Write sid into the db_agent_instances row for block_id, if one exists. Best-effort — no-ops (with a debug log, not a warn — most turns on a block with no matching instance row are expected, e.g. terminal panes never have one) when there’s nothing to update.