pycbsdk client: detect shmem owner supersession/close during streaming

[cboulay]

Background

#193 gives ShmemSession::isOwnerAlive() the ability to detect when the NATIVE shared-memory segments a CLIENT is mapped to have gone stale — either the STANDALONE owner crashed (owner_pid dead) or a persistent owner tore down and recreated the segments under the same name (segment_uid mismatch).

But that check is one-shot, at attach only (sdk_session.cpp ~L814). Once a pycbsdk client is streaming, nothing re-evaluates liveness. This issue covers the client-side handling of an owner that closes/recreates mid-session.

Failure scenario

1. Orion (STANDALONE owner) creates the device's shared memory; a pycbsdk client attaches as CLIENT and registers its data/config callbacks.
2. The client is streaming normally.
3. Orion's session closes (or is torn down and a new session recreated under the same name — same PID, new segment_uid).
4. The client keeps its old mapping. Data stops arriving (the receive ring is no longer being written), or worse, the client keeps reading a frozen/stale buffer. Because nothing re-checks liveness, the client has no signal that its session is dead — it just goes quiet.

The symptom is a client that silently stops receiving data with no error, until a human notices.

Proposed direction (mostly docs + opt-in utilities — NOT automatic)

The client should be able to detect this and decide what to do; recovery should not happen automatically behind the user's back.

1. Expose liveness to the client. isOwnerAlive() has no C-API or pycbsdk binding today. Add a C-API entry point and a thin pycbsdk wrapper (e.g. session.is_owner_alive() / is_segment_current()).

2. Tie the check to the heartbeat. The client already has a data/heartbeat cadence. When the expected heartbeat/data callback doesn't fire within a timeout, the client calls the liveness check rather than assuming the device merely went idle.

3. Hand control to the caller. If liveness fails, the client surfaces it (callback/exception/status flag) and the application chooses:

   • close the session, or
   • open a new session and re-register its callbacks.

   Provide a small helper to make the re-open + re-register path easy, but leave the decision explicit — do not auto-reconnect.

4. Document the pattern in pycbsdk (README/example): why a silent data stall can mean owner supersession, how to check liveness, and the close-vs-reopen choice.

Scope

• C-API + pycbsdk binding for the liveness check.
• A supporting utility/example for "heartbeat stalled → check liveness → caller decides".
• Documentation of the failure mode and recommended handling.

Out of scope

• Automatic reconnection.
• Any change to the C++ detection logic (done in Detect superseded shmem segments via per-creation segment_uid #193).

References

• Detect superseded shmem segments via per-creation segment_uid #193 — C++ supersession detection (segment_uid + owner_pid).
• src/cbsdk/src/sdk_session.cpp ~L814 — current one-shot attach-time check.