Add an authenticated cross-process recorder control channel

[abrichr]

Problem

openadapt-capture exposes Recorder.stop() and internal stop events inside the recorder process. It does not expose a cross-process control contract. The launcher therefore cannot stop a recorder that another terminal started.

The launcher formerly printed a success-shaped message for openadapt capture stop even though it did not stop anything. The launcher fix now returns non-success and directs the operator to Ctrl+C in the recorder terminal. This is a truthful interim result, not the target product behavior.

Target contract

Add a local, authenticated, owner-only control channel for an active Capture session.

• Create the channel before the recorder reports ready.
• Bind each request to the exact session identifier and recorder instance. Prevent PID-reuse and stale-descriptor confusion.
• Authenticate the local operating-system user. Keep any capability token out of command-line arguments, process listings, logs, and recording artifacts.
• Use local IPC, such as a protected Unix-domain socket on macOS/Linux and a protected named pipe on Windows. Do not expose an unauthenticated TCP listener or a writable global stop file.
• Make stop idempotent. A repeated request for the same terminal session must not corrupt or duplicate finalization.
• On a graceful stop, flush the event stream and media, write complete terminal metadata atomically, and return success only after the saved session passes its integrity checks.
• If finalization times out or the recorder disconnects, return non-success and retain explicit incomplete-session metadata. Do not report a complete recording.
• Remove the control endpoint on normal exit. Detect and remove a stale endpoint only after proving that its bound recorder instance is no longer live.
• Expose a small public client API so the launcher does not read private Capture database or process state.

Acceptance

• Subprocess tests prove ready -> status -> stop -> complete session on macOS, Windows, and Linux.
• Tests prove wrong-user or wrong-token requests, stale endpoints, repeated stop, recorder crash, and finalization timeout fail closed.
• openadapt capture stop calls the public client API and returns success only for a confirmed, complete stop.
• Flow and Desktop can reuse the same control contract without implementing a second native recorder.

Current workaround

Use Ctrl+C in the terminal that owns the active raw Capture session. Use openadapt flow record for a compile-ready recording.

[abrichr]

Implemented in draft PR #79: #79

The implementation adds the real cross-process Capture control contract requested here:

• loopback-only ephemeral endpoint
• authenticated requests and responses with an unguessable per-session capability
• current-user-only runtime descriptor (0700/0600 on POSIX; protected current-user DACL on Windows)
• exact session, PID, process-start, request-ID, freshness, and replay binding
• fail-closed handling for stale, replaced, ambiguous, malformed, or unauthenticated sessions
• idempotent stop with one finalization result
• success only after the finalized SQLite database and replay-relevant events pass integrity checks
• atomic incomplete terminal metadata for timeout, worker failure, and crash recovery
• exact endpoint cleanup on normal exit, abort, direct stop, and proven-stale discovery
• public Python status_recording() / stop_recording() APIs
• public capture status / capture stop CLI commands
• real subprocess integration coverage, plus a focused macOS and Windows hosted matrix

Local validation passed: 45 focused tests, 399 standard non-slow tests, Ruff, wheel/sdist verification, and source-boundary checks. The PR remains draft while hosted CI proves the Windows DACL code and the macOS path. I did not weaken authentication or substitute a best-effort Windows permission check.

[abrichr]

Final implementation evidence is available in draft PR #79:

#79

Exact head: 5fcb2ce

The implementation now includes:

• authenticated loopback status and idempotent stop operations
• exact session, PID, process-start, request, freshness, and replay binding
• an unguessable capability stored only in a current-user-only runtime descriptor
• POSIX owner modes, macOS extended-ACL removal, and an exact protected current-user Windows DACL
• conservative rejection of stale, replaced, malformed, unauthenticated, PID-reused, and ambiguous sessions
• direct Windows kernel process-signal checks for crash recovery
• cleanup after normal exit, abort, server-start failure, and authenticated stale discovery
• terminal success only after finalized SQLite and replay-event integrity checks
• stable Python status_recording() / stop_recording() APIs
• stable capture status / capture stop CLI commands for the launcher

Final evidence:

• local standard suite: 414 passed, 2 skipped, 8 deselected
• local focused control/launcher suite: 60 passed, 1 skipped
• Ruff, distribution verification, and tree/archive source-boundary checks: passed
• independent security review of the final production implementation: no findings
• exact-head macOS control contract: passed
• exact-head Windows control contract: passed
• hosted run: https://github.com/OpenAdaptAI/openadapt-capture/actions/runs/32168642948

The Windows crash test also found and corrected a test assumption. On that runner, the Popen PID belonged to a launcher wrapper and differed from the authenticated recorder PID. The final test kills the exact descriptor-bound recorder process. It does not accept wrapper exit as recorder-exit evidence.

The pull request remains draft and unmerged.

[abrichr]

Merge-order note: PR #79 remains draft because its base predates the Capture Beta lifecycle update. The required order is Flow #364, then Capture #76, then rebase #79 onto the resulting Capture main and rerun all exact-head checks and review. PR #79 must not restore stale Experimental or Pre-Alpha lifecycle text. Capture #78 must rebase after #79 reaches main.