Skip to content

Limitations and Diagnostics

ExecUnit problems can arise at the compatibility, execution, communication, or application layer. Use these distinctions to describe a failure precisely without treating every symptom as a loading problem.

Establish the supported combination

Record the component role, operating system, process architecture, artifact family, execution context, and relevant runtime dependencies together. A command, listener, and listener-owned command can have different artifact availability even when they belong to the same plugin ecosystem.

The current commercial agent has broader format and context support on Windows than on Linux, FreeBSD, or macOS. Windows relay listeners and their owned commands are managed-only, and Server Message Block (SMB) listener components are Windows-only. Shared source or a shared file suffix does not establish platform parity.

Use Formats and Compatibility and the relevant platform page before interpreting a component's behavior as a defect. Support advertised by a custom payload must agree with what that payload actually implements and what the plugin supplies.

Distinguish the failure boundary

Observation Architectural boundary to assess What the observation does not establish
A suitable artifact is absent Plugin role and platform coverage That the agent cannot support that format in general
A present artifact cannot be used Binary target, process architecture, context, and dependencies That renaming its suffix changes compatibility
Local communication is unavailable The local pipe or FIFO relationship That the listener's network connection is the cause
A listener's network transport is unavailable The listener's external connection and configuration That its local channel or artifact failed
Bytes are exchanged but the expected behavior is absent Command versus listener role and application interpretation That transport connectivity implies semantic compatibility
Output arrives without a final command outcome Command lifetime and completion reporting That output alone means success
A listener remains active Listener lifetime That it should terminate like a finite command
A FIFO path remains after interruption Filesystem endpoint cleanup That a peer is still connected

These categories guide investigation; they do not assign a root cause without evidence. Keep observations from the agent, ExecUnit, and listener transport distinct when describing a failure.

Concurrency and shutdown

The self context shares a process with the agent. An ExecUnit's resource use, process-wide state, and worker lifetime can therefore affect unrelated work in that process. Some command implementations maintain shared state or are designed for long-running activity, so reentrancy and cancellation behavior need component-specific assessment.

Command completion, the end of a worker's activity, and closure of local communication are separate events. Listener lifetime introduces a further distinction because a listener ordinarily participates in repeated exchanges. Do not treat a disconnect as a successful command outcome or assume that a stop request guarantees immediate cleanup.

Existing implementations include platform-specific shutdown behavior and cleanup delays. Treat such behavior as an implementation limitation to describe and validate, rather than as a universal timing guarantee for custom components.

Local communication boundaries

Windows named pipes and Unix first-in, first-out (FIFO) endpoints provide local transport; endpoint access controls and peer trust require separate consideration. Existing pipe terminology should not be read as an authentication guarantee.

Byte-stream transport also leaves application framing, partial input, resource limits, and malformed input handling to the communication layer. A successful connection or a small successful exchange does not establish robustness under interruption, concurrent output, or invalid input.

The command and listener roles use distinct application messages. A listener-owned command follows the command role regardless of where its artifacts are packaged. Keep that distinction visible in diagnostics and documentation reviews.