hcom pty endpoint can become half-alive: port listens but term returns No response

[zane668]

Summary

hcom pty can enter a half-alive state where the wrapped agent process is still alive and the TCP endpoint is still listening, but the PTY control path no longer responds. In that state, hcom term <name> fails with No response, while the agent still appears listening/idle in hcom.

This looks like an hcom PTY / terminal delivery health-check issue rather than an agent/model hang.

Environment

• hcom: 0.7.23
• herdr: 0.7.3
• terminal preset: herdr-argv0
• macOS: 15.7.7 (arm64)
• agent: Claude Code via hcom pty claude
• install source: Homebrew formula aannoo/hcom/hcom

Observed Behavior

For one Claude agent (muve):

• hcom list muve --json showed the agent as listening.
• The wrapped Claude process was still alive.
• The hcom pty claude wrapper process was still alive.
• The registered TCP endpoints were still listening.
• However, hcom term muve failed with:

No response from 'muve' (port 61159).

The endpoint was still registered in hcom's database:

notify_endpoints:
muve  inject  61159
muve  pty     61256

instances:
muve  status=listening  pid=<wrapped Claude pid>  tool=claude

Process state at the time was consistent with a live wrapper and live child process:

hcom pty claude  -> alive
claude           -> alive
127.0.0.1:61159  -> LISTEN
127.0.0.1:61256  -> LISTEN

From the user side, the pane looked frozen/unusable. From hcom's state, the agent still looked healthy enough to remain listening.

Expected Behavior

If the PTY endpoint is registered and the process/port still exist, but the endpoint no longer responds to hcom term, hcom should detect this as an unhealthy or stale PTY endpoint.

Possible expected behaviors:

• Mark the instance or endpoint as unhealthy/stale.
• Clear or refresh the stale notify_endpoints registration.
• Expose a recovery command for this exact state.
• Include pid / port / pane id / endpoint kind in diagnostics.
• Avoid continuing to route terminal reads or delivery through a known-bad endpoint.

Why this matters

The failure mode is confusing because the normal liveness signals still look healthy:

• the process is alive,
• the port is listening,
• the agent status is listening,
• but the PTY control path is not usable.

That makes it hard to distinguish a real agent/model hang from a dead PTY endpoint.

Suggested Fix

Add endpoint-level health checking for hcom pty / terminal delivery:

1. Treat No response from '<name>' (port <port>) as a health-check failure for that endpoint.
2. Track unhealthy PTY/inject endpoints separately from agent status.
3. On repeated timeout, mark the endpoint stale or force a refresh/rebind.
4. Surface a diagnostic such as:

PTY endpoint unhealthy: instance=muve kind=inject port=61159 pid=... pane=...

Notes

PTY debug logging was not enabled before the failure, so I do not have a low-level PTY debug trace for the exact transition into the bad state. The useful evidence is the externally visible half-alive state: live process + listening port + registered endpoint + hcom term timeout.