Define ownership and cancellation contracts for readers, PTYs, and output

[stalep]

Review of terminal-detect, terminal-api, and terminal-tty at 859020a6 on 2026-09-28.

Review item: Design 4
Priority: P2
Evidence: Design work motivated by reproduced leaks, hangs, and routing failures.

Problem / scope

Borrowed standard streams, owned device descriptors, daemon readers,
executors, native arenas, and renderer writes currently use inconsistent
lifecycle rules. Some paths cannot detect EOF; others free resources before
reads finish or skip cleanup after restore failure.

Document these contracts and identify the smallest shared implementation
boundaries. This is coordination/design work over the linked concrete bugs,
not another request to fix them in one large change.

Source at the reviewed commit

• terminal-api/src/main/java/org/aesh/terminal/StreamConnection.java:68
• terminal-tty/src/main/java/org/aesh/terminal/tty/TerminalConnection.java:208
• terminal-tty/src/main/java22/org/aesh/terminal/tty/impl/FfmPty.java:270
• terminal-tty/src/main/java/org/aesh/terminal/tty/impl/ExternalTerminal.java:80

Acceptance criteria

• Define owner, close/cancel behavior, EOF/error notification, repeat-open policy, and callback thread for each transport.
• Keep borrowed System.in/out usable and make owned native resources releasable after cancellation.
• Provide a common behavioral test matrix that each implementation can exercise, including output serialization and raw renderer access.

Tracking

Part of #300. Related: #335, #336, #337, #338, #341, #344, #311, #339.