Add APIs and CLI commands to inspect and terminate stale

[git-shizhipeng]

license sessions
Description
When CloakBrowser is terminated abnormally, the local browser process disappears, but the license server may continue reporting active sessions.
This can happen when:
PyCharm or another IDE forcibly stops the process
the process receives SIGKILL
a container or server is restarted
an OOM kill occurs
the browser crashes
a CI job is cancelled
In these cases, browser.close() and finally cleanup code do not run.
Observed behavior
Environment:
cloakbrowser wrapper: 0.5.5
Python: 3.10
Chromium: 150 Pro
License plan: Solo
Platforms: macOS arm64 and Linux
After an abnormal termination, the session count remained above zero:
from cloakbrowser.license import get_active_session_count
print(get_active_session_count(LICENSE_KEY))
2
No related local processes were running:
ps -eo pid,ppid,etime,cmd | grep -Ei 'cloakbrowser|chromium|chrome|playwright' | grep -v grep
No processes had files open under the CloakBrowser cache directory:
lsof +D ~/.cloakbrowser
The active session count decreased gradually but remained non-zero for some time. During that period, a Solo license may be unable to start a new browser.
Current API
The Python wrapper currently provides:
get_active_session_count(license_key)
This reports only the number of active seats. It does not expose session identifiers, hosts, heartbeat times, or a way to terminate stale sessions.
Requested functionality
Please consider adding APIs such as:
list_active_sessions(license_key)
close_session(license_key, session_id)
close_all_sessions(license_key)
Possible CLI equivalents:
cloakbrowser sessions list
cloakbrowser sessions close SESSION_ID
cloakbrowser sessions close --all
A session record could include:
session ID
anonymized installation or host identifier
platform
browser version
session creation time
last heartbeat time
active or stale status
Expected behavior
Users should be able to identify and terminate stale sessions after confirming that no corresponding browser process is still running.
For safety, close_all_sessions could require an explicit confirmation flag:
cloakbrowser sessions close --all --confirm
Why this is useful
This would:
allow immediate recovery after SIGKILL or browser crashes
prevent unnecessary downtime on Solo licenses
help identify which machine is holding a seat
improve reliability in Docker, CI, IDE debugging and process supervisors
reduce support requests for manual session cleanup
distinguish real active sessions from stale server-side leases
Alternative improvement
If explicit session termination is not desirable, another option would be a shorter lease timeout combined with session details and last-heartbeat information.
Thank you for considering this feature.

[Cloak-HQ]

Thanks for the detailed feature request.

For reliable session cleanup, call browser.close()—or context.close() for a persistent context—in a finally block. Async close calls must also be awaited. Graceful SIGINT/SIGTERM shutdown allows the session to be released immediately.

SIGKILL, OOM termination, IDE force-stop, browser crashes, and sudden container shutdown cannot execute cleanup code. Those sessions are released automatically after their lease expires.

We’ll evaluate the proposed session inspection and termination APIs as a feature request. If sessions remain after a normal graceful close or handled exception, please share a minimal launch and cleanup snippet so we can investigate that path separately.