Restack desktop session and metadata strategy resolution #64

Merged

lost-rob0t merged 1 commit from agent/issue-13-session-resolution-restack into main

2026-08-12 00:26:25 +00:00

lost-rob0t commented

2026-08-12 00:25:00 +00:00

(Migrated from github.com)

Summary

Issue #13 already had a complete implementation in historical PR #61, but that PR was stacked on agent/issue-12-audit-hardening and merged only into that feature branch. Modern main contains issue #12 through PR #59 plus later work, while issue #13 remained open, so the old branch could not be merged mechanically without reintroducing divergent history.

This PR restacks and reconciles the issue #13 slice directly onto current main.

Reconciliation with PR #61

Reused from PR #61:

normalized, value-discarding environment snapshots;
deterministic Xorg/Wayland and recognized-desktop detection;
typed session/probe/resolution models;
fixed in-process metadata probe registry and bounded probe execution;
Qtile, ActivityWatch, and generic-Xorg capability/health seams;
ordered multi-source selection and generic-Xorg fallback;
deterministic metadata conflict resolution with confidence and provenance;
sanitized JSON status rendering and the read-only local-recall status command;
session-resolution documentation and the original unit coverage.

Adapted for current main:

applied the implementation file-by-file rather than merging the historical stacked branch;
retained current-main CLI and README content added after PR #61, inserting only the status command and documentation link;
formatted with the current locked Ruff toolchain;
expanded tests for unknown protocol values, ambiguous recognized desktops, explicit ActivityWatch and generic-Xorg selection, no probe execution on unsupported sessions, malicious source-ID sanitization, mismatched probe identity, timestamp/stable-name conflict tie-breaks, and actor-registry preservation by status.

The current typed metadata models and lifecycle boundaries remained compatible, so the core PR #61 session implementation did not require an alternate lifecycle or collector rewrite.

Architecture and scope

Session resolution is synchronous startup/status decision logic with finite async probe deadlines. It creates no detached tasks, queues, subprocesses, dynamic imports, or persistence paths. Actual collectors for generic Xorg, Qtile, and ActivityWatch remain deferred to issues #14, #15, and #16; capture policy remains issue #17.

Security and privacy

DISPLAY alone never proves Xorg.
Contradictory Xorg/Wayland evidence fails closed.
Unknown and unsupported sessions select no capture backend.
Unknown source identifiers cannot trigger imports or command execution.
Probe timeouts, exceptions, malformed identities, and unknown sources map to fixed reason codes.
Arbitrary environment values and probe exception text are never retained or rendered.
Status reports normalized classifications only and does not start lifecycle actors or recording.
Metadata values retain per-source confidence and provenance; conflicts resolve deterministically.

Validation

Red phase on current main:

uv run --no-sync pytest tests/unit/session tests/unit/test_package.py -q
failed during collection with four ModuleNotFoundError: No module named 'local_recall.session' errors.

Green phase:

uv run --no-sync pytest tests/unit/session tests/unit/test_package.py -q
37 passed in 0.25s

Canonical gate:

./scripts/check
formatting: 173 files already formatted
Ruff lint: passed
shell checks: passed
strict Pyright: 0 errors, 0 warnings
test suite: 265 passed in 2.21s
failure propagation: 8 failure modes verified
security scans and repository policy checks: passed

Closes #13

## Summary Issue #13 already had a complete implementation in historical PR #61, but that PR was stacked on `agent/issue-12-audit-hardening` and merged only into that feature branch. Modern `main` contains issue #12 through PR #59 plus later work, while issue #13 remained open, so the old branch could not be merged mechanically without reintroducing divergent history. This PR restacks and reconciles the issue #13 slice directly onto current `main`. ## Reconciliation with PR #61 Reused from PR #61: - normalized, value-discarding environment snapshots; - deterministic Xorg/Wayland and recognized-desktop detection; - typed session/probe/resolution models; - fixed in-process metadata probe registry and bounded probe execution; - Qtile, ActivityWatch, and generic-Xorg capability/health seams; - ordered multi-source selection and generic-Xorg fallback; - deterministic metadata conflict resolution with confidence and provenance; - sanitized JSON status rendering and the read-only `local-recall status` command; - session-resolution documentation and the original unit coverage. Adapted for current `main`: - applied the implementation file-by-file rather than merging the historical stacked branch; - retained current-main CLI and README content added after PR #61, inserting only the status command and documentation link; - formatted with the current locked Ruff toolchain; - expanded tests for unknown protocol values, ambiguous recognized desktops, explicit ActivityWatch and generic-Xorg selection, no probe execution on unsupported sessions, malicious source-ID sanitization, mismatched probe identity, timestamp/stable-name conflict tie-breaks, and actor-registry preservation by status. The current typed metadata models and lifecycle boundaries remained compatible, so the core PR #61 session implementation did not require an alternate lifecycle or collector rewrite. ## Architecture and scope Session resolution is synchronous startup/status decision logic with finite async probe deadlines. It creates no detached tasks, queues, subprocesses, dynamic imports, or persistence paths. Actual collectors for generic Xorg, Qtile, and ActivityWatch remain deferred to issues #14, #15, and #16; capture policy remains issue #17. ## Security and privacy - `DISPLAY` alone never proves Xorg. - Contradictory Xorg/Wayland evidence fails closed. - Unknown and unsupported sessions select no capture backend. - Unknown source identifiers cannot trigger imports or command execution. - Probe timeouts, exceptions, malformed identities, and unknown sources map to fixed reason codes. - Arbitrary environment values and probe exception text are never retained or rendered. - Status reports normalized classifications only and does not start lifecycle actors or recording. - Metadata values retain per-source confidence and provenance; conflicts resolve deterministically. ## Validation Red phase on current `main`: - `uv run --no-sync pytest tests/unit/session tests/unit/test_package.py -q` - failed during collection with four `ModuleNotFoundError: No module named 'local_recall.session'` errors. Green phase: - `uv run --no-sync pytest tests/unit/session tests/unit/test_package.py -q` - **37 passed in 0.25s** Canonical gate: - `./scripts/check` - formatting: 173 files already formatted - Ruff lint: passed - shell checks: passed - strict Pyright: 0 errors, 0 warnings - test suite: **265 passed in 2.21s** - failure propagation: **8 failure modes verified** - security scans and repository policy checks: passed Closes #13