Skip to content

Make first-run Accessibility recovery self-explanatory #2

Description

@Singularity-tian

Problem

A daemon can be healthy while producing no useful captures when Accessibility permission was granted to the wrong launcher, changed after a launchd handoff, or has not taken effect yet. persome doctor provides checks, but first-run recovery should make the exact owning process and next action unmistakable.

Scope

Improve owner-local diagnostics and recovery for terminal-launched and LaunchAgent-owned daemons. Do not add telemetry or automate System Settings clicks.

Acceptance criteria

  • Status distinguishes permission missing, no recent capture, paused capture, and an unhealthy watcher.
  • Output identifies whether the terminal or LaunchAgent path currently owns capture.
  • Recovery instructions explain when a restart is required and when it is not.
  • The local status API exposes a stable machine-readable reason code.
  • Unit tests cover each reason without requiring real macOS permission.
  • At least one macos test documents the live manual verification path.
  • README/operations/troubleshooting remain consistent with the implementation.

Privacy boundary

Diagnostics must not print captured text, window titles, URLs, or provider keys.

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedExtra attention is neededmacOSmacOS capture, permissions, packaging, or compatibility

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions