Detect desktop sessions and resolve metadata strategies #61

Merged

lost-rob0t merged 29 commits from agent/issue-13-session-resolution into agent/issue-12-audit-hardening

2026-07-21 23:30:16 +00:00

lost-rob0t commented

2026-07-19 06:53:02 +00:00

(Migrated from github.com)

Stack

Depends on PR #59 / issue #12.
Base is agent/issue-12-audit-hardening so issue order and code dependencies remain intact.
Implements issue #13 only. The new Zara integration issues remain backlog work.

What changed

Added normalized environment snapshots that discard arbitrary environment values.
Added deterministic Xorg/Wayland detection using XDG_SESSION_TYPE plus required display evidence.
Refuses to infer Xorg from DISPLAY alone and rejects contradictory Xorg/Wayland evidence.
Added recognized desktop identifiers for Qtile, GNOME, KDE/Plasma, Sway, XFCE, and COSMIC.
Added closed probe outcomes, reason codes, capabilities, and sanitized session resolution models.
Added a fixed metadata probe registry with finite deadlines and no dynamic imports.
Added ordered composition of healthy configured sources.
Added generic Xorg fallback only when specialized configured sources are unavailable; an empty source configuration does not enable fallback.
Added Qtile and ActivityWatch capability/health-check seams without implementing their collectors ahead of issues #15 and #16.
Added deterministic metadata conflict resolution using confidence, configured source order, newest observation, and stable source ID.
Added deterministic JSON rendering for SessionResolution and wired local-recall status to current-session resolution.
Added documentation and tests for detection, probing, fallback, unsupported sessions, sanitization, provenance retention, status output, and environment-value non-disclosure.

Security behavior

Unknown or unsupported sessions remain non-recording.
Wayland never selects the Xorg capture backend.
Probe timeout and exception text are replaced with fixed content-free results.
Unknown configured source IDs do not trigger imports, command execution, or network lookup.
Arbitrary desktop/session environment strings, display addresses, and Wayland socket paths are not rendered by the status command.
The status command is read-only and does not start capture.
Metadata conflicts retain all unique provenance records.

Validation

GitHub Actions CI run #258 passed on head ab300d98af312414aaf0699ec4af1dfc5f785e6c.

The authoritative CPython 3.14 matrix passed:

formatting;
Ruff lint;
shell checks;
strict Pyright;
unit tests;
contract tests;
integration tests;
security tests and scans;
failure-propagation verification.

Closes #13

## Stack - Depends on PR #59 / issue #12. - Base is `agent/issue-12-audit-hardening` so issue order and code dependencies remain intact. - Implements issue #13 only. The new Zara integration issues remain backlog work. ## What changed - Added normalized environment snapshots that discard arbitrary environment values. - Added deterministic Xorg/Wayland detection using `XDG_SESSION_TYPE` plus required display evidence. - Refuses to infer Xorg from `DISPLAY` alone and rejects contradictory Xorg/Wayland evidence. - Added recognized desktop identifiers for Qtile, GNOME, KDE/Plasma, Sway, XFCE, and COSMIC. - Added closed probe outcomes, reason codes, capabilities, and sanitized session resolution models. - Added a fixed metadata probe registry with finite deadlines and no dynamic imports. - Added ordered composition of healthy configured sources. - Added generic Xorg fallback only when specialized configured sources are unavailable; an empty source configuration does not enable fallback. - Added Qtile and ActivityWatch capability/health-check seams without implementing their collectors ahead of issues #15 and #16. - Added deterministic metadata conflict resolution using confidence, configured source order, newest observation, and stable source ID. - Added deterministic JSON rendering for `SessionResolution` and wired `local-recall status` to current-session resolution. - Added documentation and tests for detection, probing, fallback, unsupported sessions, sanitization, provenance retention, status output, and environment-value non-disclosure. ## Security behavior - Unknown or unsupported sessions remain non-recording. - Wayland never selects the Xorg capture backend. - Probe timeout and exception text are replaced with fixed content-free results. - Unknown configured source IDs do not trigger imports, command execution, or network lookup. - Arbitrary desktop/session environment strings, display addresses, and Wayland socket paths are not rendered by the status command. - The status command is read-only and does not start capture. - Metadata conflicts retain all unique provenance records. ## Validation GitHub Actions CI run #258 passed on head `ab300d98af312414aaf0699ec4af1dfc5f785e6c`. The authoritative CPython 3.14 matrix passed: - formatting; - Ruff lint; - shell checks; - strict Pyright; - unit tests; - contract tests; - integration tests; - security tests and scans; - failure-propagation verification. Closes #13