android-watcher 1.0.0__tar.gz → 1.0.1__tar.gz

{android_watcher-1.0.0 → android_watcher-1.0.1}/.github/workflows/release.yml

@@ -1,8 +1,9 @@
 name: release
 
 # Manual, bump-driven release. Pick the semver part to bump; the job computes the
-# new version from the current one, commits it to main, publishes to PyPI, refreshes
-# the Homebrew formula, and tags the release last.
+# new version from the current one, commits it to main, publishes to PyPI, tags and
+# publishes a GitHub release, then refreshes the Homebrew formula as a best-effort,
+# non-blocking step.
 on:
   workflow_dispatch:
     inputs:
@@ -33,6 +34,11 @@ jobs:
         with:
           ref: main
           fetch-depth: 0   # full history so we can push back and tag
+          # Push to main as the repo owner (a ruleset bypass actor) rather than the
+          # ambient GITHUB_TOKEN / github-actions[bot], which the main ruleset blocks.
+          # On a user-owned repo the GitHub Actions integration cannot be added to the
+          # bypass list, so a fine-grained PAT (contents: write) is used instead.
+          token: ${{ secrets.RELEASE_TOKEN }}
 
       - name: Configure git as the release bot
         run: |
@@ -72,7 +78,33 @@ jobs:
         with:
           password: ${{ secrets.PYPI_TOKEN }}
 
+      # Tag and publish a GitHub release right after the publish succeeds, before
+      # the best-effort Homebrew step. A formula hiccup must never leave a
+      # published version untagged or unreleased. --generate-notes builds the
+      # changelog from merged PRs and commits since the previous release.
+      - name: Tag and publish GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ steps.bump.outputs.version }}"
+          git tag "v${VERSION}"
+          git push origin "v${VERSION}"
+          gh release create "v${VERSION}" \
+            --title "v${VERSION}" \
+            --generate-notes \
+            --verify-tag \
+            --latest
+
+      - name: Set up Homebrew
+        uses: Homebrew/actions/setup-homebrew@master
+
+      # Best-effort and non-blocking: `brew update-python-resources` can fail to
+      # resolve a same-day PyPI upload (its reproducibility cutoff predates the
+      # publish) and requires a tap on newer Homebrew. Never let that fail the
+      # release; regenerate the resource blocks out-of-band once PyPI indexing
+      # settles, then commit the refreshed formula.
       - name: Update Homebrew formula
+        continue-on-error: true
         run: |
           VERSION="${{ steps.bump.outputs.version }}"
           # PyPI's JSON index lags publish by a few seconds; poll until the release shows up.
@@ -105,8 +137,3 @@ jobs:
           git add Formula/android-watcher.rb
           git commit -m "chore: update homebrew formula for v${VERSION}"
           git push origin HEAD:main
-
-      - name: Tag the release
-        run: |
-          git tag "v${{ steps.bump.outputs.version }}"
-          git push origin "v${{ steps.bump.outputs.version }}"

{android_watcher-1.0.0 → android_watcher-1.0.1}/Formula/android-watcher.rb

@@ -6,8 +6,8 @@ class AndroidWatcher < Formula
   # url + sha256 point at the PyPI sdist for the released version. The release
   # workflow rewrites both on every version bump, then regenerates the `resource`
   # blocks below with `brew update-python-resources`. Do not hand-edit.
-  url "https://files.pythonhosted.org/packages/source/a/android-watcher/android_watcher-0.0.0.tar.gz"
-  sha256 "0000000000000000000000000000000000000000000000000000000000000000"
+  url "https://files.pythonhosted.org/packages/31/5c/0ac31004a57aaa32b117c1d318cb5c8256adae9f95b7c874187335f47b3b/android_watcher-1.0.0.tar.gz"
+  sha256 "0844583243b9d94ef4211c80a8be6e5b0efac44d21bdb224aa6b02a5670cc7c3"
   license "MIT"
 
   depends_on "python@3.11"

{android_watcher-1.0.0 → android_watcher-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: android-watcher
-Version: 1.0.0
+Version: 1.0.1
 Summary: Self-hosted CLI that watches Google's official Android sites and delivers AI-triaged change digests.
 Project-URL: Homepage, https://github.com/krayong/android-watcher
 Project-URL: Repository, https://github.com/krayong/android-watcher

{android_watcher-1.0.0 → android_watcher-1.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "android-watcher"
-version = "1.0.0"
+version = "1.0.1"
 description = "Self-hosted CLI that watches Google's official Android sites and delivers AI-triaged change digests."
 readme = "README.md"
 license = { text = "MIT" }

{android_watcher-1.0.0 → android_watcher-1.0.1}/src/android_watcher/config.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 import os
 import re
+import shutil
+import sys
 import tomllib
 from dataclasses import dataclass, field
 from typing import Any, Literal
@@ -16,6 +18,7 @@ __all__ = [
 	"AIConfig",
 	"Config",
 	"ConfigError",
+	"DesktopChannel",
 	"DigestConfig",
 	"EmailChannel",
 	"ScheduleConfig",
@@ -24,6 +27,8 @@ __all__ = [
 	"config_path",
 	"data_path",
 	"db_path",
+	"desktop_mechanism_available",
+	"digests_dir",
 	"load_config",
 	"log_path",
 ]
@@ -80,6 +85,12 @@ class TelegramChannel:
 	chat_id: str = ""
 
 
+@dataclass
+class DesktopChannel:
+	enabled: bool = False
+	sound: str = "Glass"  # macOS notification sound name
+
+
 @dataclass
 class Config:
 	schedule: ScheduleConfig
@@ -90,6 +101,9 @@ class Config:
 	slack: SlackChannel
 	telegram: TelegramChannel
 	custom_sources: list[Source]
+	# Defaulted (disabled) so existing Config(...) call sites need no change; a new
+	# optional local channel that is off until the user opts in.
+	desktop: DesktopChannel = field(default_factory=DesktopChannel)
 	enabled_source_ids: set[str] = field(default_factory=set)
 
 
@@ -105,6 +119,30 @@ def db_path() -> str:
 	return os.path.join(data_path(), "state.db")
 
 
+def digests_dir() -> str:
+	"""Directory where the desktop channel writes click-to-open HTML digests."""
+	return os.path.join(data_path(), "digests")
+
+
+def _desktop_binary() -> str | None:
+	"""The required desktop-notification binary for this platform, or None.
+
+	macOS uses terminal-notifier (the only mechanism that opens the digest on
+	click); Linux uses notify-send. Other platforms have no supported mechanism.
+	"""
+	if sys.platform == "darwin":
+		return "terminal-notifier"
+	if sys.platform.startswith("linux"):
+		return "notify-send"
+	return None
+
+
+def desktop_mechanism_available() -> bool:
+	"""True if this platform's required desktop-notification binary is installed."""
+	binary = _desktop_binary()
+	return bool(binary and shutil.which(binary))
+
+
 def log_path() -> str:
 	"""Path to the run log. ~/Library/Logs/android-watcher.log on macOS."""
 	import sys  # noqa: PLC0415 - localized; keeps module import graph lean
@@ -160,6 +198,7 @@ def load_config(path: str | None = None, *, expand: bool = True) -> Config:
 	email = _load_email(channels.get("email", {}), expand=expand)
 	slack = _load_slack(channels.get("slack", {}), expand=expand)
 	telegram = _load_telegram(channels.get("telegram", {}), expand=expand)
+	desktop = _load_desktop(channels.get("desktop", {}))
 	custom_sources = [_load_source(e) for e in raw.get("custom_source", [])]
 	enabled = set(raw.get("enabled_sources", []))
 
@@ -174,6 +213,7 @@ def load_config(path: str | None = None, *, expand: bool = True) -> Config:
 		email=email,
 		slack=slack,
 		telegram=telegram,
+		desktop=desktop,
 		custom_sources=custom_sources,
 		enabled_source_ids=enabled,
 	)
@@ -247,6 +287,14 @@ def _load_telegram(d: dict[str, Any], *, expand: bool) -> TelegramChannel:
 	)
 
 
+def _load_desktop(d: dict[str, Any]) -> DesktopChannel:
+	# No secret-bearing fields, so no ${ENV} interpolation needed.
+	return DesktopChannel(
+		enabled=bool(d.get("enabled", False)),
+		sound=d.get("sound", "Glass"),
+	)
+
+
 def _load_source(e: dict[str, Any]) -> Source:
 	return Source(
 		id=e["id"],

{android_watcher-1.0.0 → android_watcher-1.0.1}/src/android_watcher/doctor.py

@@ -34,6 +34,25 @@ def _check_ai(config: Config) -> Check:
 	return Check("ai-backend", False, "claude not found on PATH")
 
 
+def _check_desktop(config: Config) -> Check:
+	"""Verify the platform's required desktop-notification binary is installed."""
+	from android_watcher.config import (  # noqa: PLC0415 - localized to keep imports lean
+		_desktop_binary,
+		desktop_mechanism_available,
+	)
+
+	binary = _desktop_binary()
+	if binary is None:
+		return Check("desktop", False, "no supported desktop notifier for this platform")
+	if desktop_mechanism_available():
+		return Check("desktop", True, f"{binary} found")
+	return Check(
+		"desktop",
+		False,
+		f"{binary} not found on PATH; install it to enable desktop notifications",
+	)
+
+
 def _check_seed() -> Check:
 	"""Report the imported baseline seed date and snapshot count, if any."""
 	store = Store(db_path())
@@ -121,5 +140,7 @@ def run_doctor(config: Config) -> list[Check]:
 	checks.extend(_check_prefixes(config))
 	checks.append(_check_seed())
 	checks.append(_check_ai(config))
+	if config.desktop.enabled:
+		checks.append(_check_desktop(config))
 	checks.append(_check_schedule())
 	return checks

android_watcher-1.0.1/src/android_watcher/notify/__init__.py

@@ -0,0 +1 @@
+from . import desktop, email, slack, telegram  # noqa: F401

android_watcher-1.0.1/src/android_watcher/notify/desktop.py

@@ -0,0 +1,95 @@
+"""Desktop notifier: a native notification that opens a local HTML digest on click.
+
+macOS uses ``terminal-notifier`` (whose ``-execute`` runs ``open <file>`` on click);
+Linux uses ``notify-send`` (no portable click action, so the digest path is shown in
+the body). Both render the full digest to ``<data_dir>/digests`` first.
+"""
+
+from __future__ import annotations
+
+import logging
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+from android_watcher.config import Config, desktop_mechanism_available, digests_dir
+from android_watcher.models import Digest, DigestGroup, NotifyError
+from android_watcher.notify.base import NOTIFIERS
+from android_watcher.notify.html import render_html
+
+logger = logging.getLogger(__name__)
+
+_TIMEOUT = 30.0
+
+
+def _member_ids(groups: list[DigestGroup]) -> set[int]:
+	return {m.id for g in groups for m in g.members if m.id is not None}
+
+
+def _digest_filename(digest: Digest) -> str:
+	# Local time in the human-facing filename; UTC is kept internally on the digest.
+	local = digest.generated_at.astimezone()
+	return f"android-watcher-digest-{local:%d%m%Y-%H%M%S}.html"
+
+
+def _write_html(digest: Digest) -> Path:
+	out_dir = Path(digests_dir())
+	out_dir.mkdir(parents=True, exist_ok=True)
+	path = out_dir / _digest_filename(digest)
+	path.write_text(render_html(digest), encoding="utf-8")
+	return path
+
+
+def _summary(digest: Digest) -> str:
+	"""Counts only — never raw page titles, which come from untrusted sources."""
+	n = digest.change_count()
+	g = len(digest.groups)
+	return f"{n} change{'' if n == 1 else 's'} across {g} group{'' if g == 1 else 's'}"
+
+
+def _notify(title: str, message: str, path: Path, sound: str) -> None:
+	if sys.platform == "darwin":
+		argv = [
+			"terminal-notifier",
+			"-title",
+			title,
+			"-message",
+			message,
+			"-sound",
+			sound,
+			"-group",
+			"android-watcher",
+			# The path is app-generated; quote it so a space in the data dir is safe.
+			"-execute",
+			f"open {shlex.quote(str(path))}",
+		]
+	elif sys.platform.startswith("linux"):
+		# notify-send has no portable click-to-run action; show the digest URI instead.
+		argv = ["notify-send", title, f"{message}\n{path.as_uri()}"]
+	else:  # pragma: no cover - guarded earlier by desktop_mechanism_available()
+		raise NotifyError(f"desktop notifications unsupported on {sys.platform!r}")
+	try:
+		subprocess.run(argv, check=True, capture_output=True, timeout=_TIMEOUT)
+	except FileNotFoundError as exc:
+		raise NotifyError(f"desktop notifier binary not found: {argv[0]}") from exc
+	except subprocess.CalledProcessError as exc:
+		raise NotifyError(f"{argv[0]} exited {exc.returncode}") from exc
+	except subprocess.TimeoutExpired as exc:
+		raise NotifyError(f"{argv[0]} timed out after {_TIMEOUT}s") from exc
+
+
+@NOTIFIERS.register("desktop")
+class DesktopNotifier:
+	name = "desktop"
+
+	def send(self, digest: Digest, config: Config) -> set[int]:
+		# Notify only when there is something to show; no daily empty-digest pop.
+		if not digest.groups:
+			return set()
+		if not desktop_mechanism_available():
+			raise NotifyError("no desktop notification mechanism available")
+		path = _write_html(digest)
+		logger.info("desktop: wrote digest page %s; firing notification", path)
+		_notify("Android Watcher", _summary(digest), path, config.desktop.sound)
+		return _member_ids(digest.groups)

{android_watcher-1.0.0 → android_watcher-1.0.1}/src/android_watcher/run.py

@@ -97,6 +97,8 @@ def _enabled_channels(config: Config) -> set[str]:
 		channels.add("slack")
 	if config.telegram.enabled:
 		channels.add("telegram")
+	if config.desktop.enabled:
+		channels.add("desktop")
 	return channels
 
 

{android_watcher-1.0.0 → android_watcher-1.0.1}/src/android_watcher/schedule.py

@@ -166,8 +166,18 @@ def _calendar_intervals(sched: ScheduleConfig) -> list[dict[str, int]]:
 	raise ScheduleError(f"unknown interval {sched.interval!r}")
 
 
-def render_plist(label: str, program_args: list[str], sched: ScheduleConfig) -> str:
-	"""Render a launchd plist string for the given label, args, and schedule."""
+def render_plist(
+	label: str,
+	program_args: list[str],
+	sched: ScheduleConfig,
+	path_env: str | None = None,
+) -> str:
+	"""Render a launchd plist string for the given label, args, and schedule.
+
+	A launchd job inherits a bare PATH (``/usr/bin:/bin:/usr/sbin:/sbin``), so
+	when *path_env* is given it is embedded as ``EnvironmentVariables/PATH`` —
+	without it the run cannot reach the ``claude`` CLI for triage.
+	"""
 	intervals = _calendar_intervals(sched)
 	payload: dict[str, object] = {
 		"Label": label,
@@ -175,6 +185,8 @@ def render_plist(label: str, program_args: list[str], sched: ScheduleConfig) ->
 		"RunAtLoad": False,
 		"StartCalendarInterval": intervals[0] if len(intervals) == 1 else intervals,
 	}
+	if path_env:
+		payload["EnvironmentVariables"] = {"PATH": path_env}
 	return plistlib.dumps(payload, sort_keys=True).decode("utf-8")
 
 
@@ -231,15 +243,22 @@ def _on_calendar(sched: ScheduleConfig, tz: str) -> str:
 	raise ScheduleError(f"unknown interval {sched.interval!r}")
 
 
-def render_service(exec_path: str, args: list[str]) -> str:
-	"""Render a systemd .service unit for android-watcher."""
+def render_service(exec_path: str, args: list[str], path_env: str | None = None) -> str:
+	"""Render a systemd .service unit for android-watcher.
+
+	systemd user services start from a minimal PATH, so when *path_env* is given
+	it is embedded as ``Environment=PATH=`` — without it the run cannot reach the
+	``claude`` CLI for triage.
+	"""
 	exec_start = " ".join([exec_path, *args])
+	env_line = f"Environment=PATH={path_env}\n" if path_env else ""
 	return (
 		"[Unit]\n"
 		"Description=android-watcher scheduled run\n"
 		"\n"
 		"[Service]\n"
 		"Type=oneshot\n"
+		f"{env_line}"
 		f"ExecStart={exec_start}\n"
 	)
 
@@ -281,10 +300,18 @@ def _cron_line(sched: ScheduleConfig) -> str:
 	return _cron_lines(sched)[0]
 
 
-def render_crontab(line_command: str, sched: ScheduleConfig, tz: str) -> str:
-	"""Render a marked crontab block for android-watcher (one line per scheduled time)."""
+def render_crontab(
+	line_command: str, sched: ScheduleConfig, tz: str, path_env: str | None = None
+) -> str:
+	"""Render a marked crontab block for android-watcher (one line per scheduled time).
+
+	cron runs with a minimal PATH, so when *path_env* is given a ``PATH=``
+	assignment is emitted ahead of the schedule lines — without it the run cannot
+	reach the ``claude`` CLI for triage.
+	"""
 	body = "\n".join(f"{spec} {line_command}" for spec in _cron_lines(sched))
-	return f"{CRON_BEGIN}\nCRON_TZ={tz}\n{body}\n{CRON_END}\n"
+	path_line = f"PATH={path_env}\n" if path_env else ""
+	return f"{CRON_BEGIN}\nCRON_TZ={tz}\n{path_line}{body}\n{CRON_END}\n"
 
 
 # ---------------------------------------------------------------------------
@@ -319,6 +346,17 @@ def _program_args() -> list[str]:
 	return [exe, "run"]
 
 
+def _env_path() -> str:
+	"""Snapshot the install-time PATH to embed in the scheduled unit.
+
+	Native schedulers (launchd, systemd user, cron) run with a minimal PATH that
+	omits per-user bin dirs like ``~/.local/bin``, so the ``claude`` CLI would be
+	unreachable. Capturing the PATH from the shell that ran the install preserves
+	parity with the environment where ``claude`` was found.
+	"""
+	return os.environ.get("PATH", "")
+
+
 def _launchd_plist_path() -> str:
 	return str(Path.home() / "Library" / "LaunchAgents" / f"{LAUNCHD_LABEL}.plist")
 
@@ -357,7 +395,7 @@ def _run(argv: list[str], *, input: str | None = None) -> subprocess.CompletedPr
 def _install_macos(config: Config) -> None:
 	path = Path(_launchd_plist_path())
 	path.parent.mkdir(parents=True, exist_ok=True)
-	path.write_text(render_plist(LAUNCHD_LABEL, _program_args(), config.schedule))
+	path.write_text(render_plist(LAUNCHD_LABEL, _program_args(), config.schedule, _env_path()))
 	_run(["launchctl", "unload", str(path)])
 	_run(["launchctl", "load", "-w", str(path)])
 	_warn(
@@ -370,7 +408,7 @@ def _install_systemd(config: Config) -> None:
 	d = Path(_systemd_dir())
 	d.mkdir(parents=True, exist_ok=True)
 	exe, *run_args = _program_args()
-	(d / f"{SYSTEMD_UNIT_NAME}.service").write_text(render_service(exe, run_args))
+	(d / f"{SYSTEMD_UNIT_NAME}.service").write_text(render_service(exe, run_args, _env_path()))
 	(d / f"{SYSTEMD_UNIT_NAME}.timer").write_text(render_timer(config.schedule, _local_tz()))
 	_run(["systemctl", "--user", "daemon-reload"])
 	_run(["systemctl", "--user", "enable", "--now", f"{SYSTEMD_UNIT_NAME}.timer"])
@@ -400,7 +438,7 @@ def _strip_cron_block(text: str) -> str:
 
 def _install_crontab(config: Config) -> None:
 	existing = _run(["crontab", "-l"]).stdout
-	block = render_crontab(" ".join(_program_args()), config.schedule, _local_tz())
+	block = render_crontab(" ".join(_program_args()), config.schedule, _local_tz(), _env_path())
 	cleaned = _strip_cron_block(existing)
 	new = (cleaned.rstrip("\n") + "\n" if cleaned.strip() else "") + block
 	_run(["crontab", "-"], input=new)

{android_watcher-1.0.0 → android_watcher-1.0.1}/src/android_watcher/tui/configio.py

@@ -15,12 +15,14 @@ from android_watcher.config import (
 	AIConfig,
 	Config,
 	ConfigError,
+	DesktopChannel,
 	DigestConfig,
 	EmailChannel,
 	ScheduleConfig,
 	SlackChannel,
 	TelegramChannel,
 	config_path,
+	desktop_mechanism_available,
 	load_config,
 )
 from android_watcher.models import Source
@@ -136,6 +138,12 @@ def config_to_toml(config: Config) -> str:
 	lines.append(f"chat_id = {_toml_str(tg.chat_id)}")
 	lines.append("")
 
+	ds = config.desktop
+	lines.append("[channels.desktop]")
+	lines.append(f"enabled = {'true' if ds.enabled else 'false'}")
+	lines.append(f"sound = {_toml_str(ds.sound)}")
+	lines.append("")
+
 	for s in config.custom_sources:
 		lines.append(_source_table("custom_source", s))
 
@@ -173,8 +181,16 @@ def validate_config(config: Config) -> list[str]:
 		errors.append(str(exc))
 	finally:
 		os.unlink(tmp)
-	if not (config.email.enabled or config.slack.enabled or config.telegram.enabled):
-		errors.append("enable at least one delivery channel (Slack or Telegram) to receive digests")
+	if not (
+		config.email.enabled
+		or config.slack.enabled
+		or config.telegram.enabled
+		or config.desktop.enabled
+	):
+		errors.append(
+			"enable at least one delivery channel (Email, Slack, Telegram, or Desktop) "
+			"to receive digests"
+		)
 	sl = config.slack
 	if sl.enabled and not (sl.bot_token and sl.channel):
 		errors.append("slack channel is enabled but bot_token + channel are required")
@@ -183,6 +199,11 @@ def validate_config(config: Config) -> list[str]:
 		errors.append("telegram channel is enabled but bot_token is empty")
 	if tg.enabled and not tg.chat_id:
 		errors.append("telegram channel is enabled but chat_id is empty")
+	if config.desktop.enabled and not desktop_mechanism_available():
+		errors.append(
+			"desktop channel is enabled but no notifier is available "
+			"(install terminal-notifier on macOS or notify-send on Linux)"
+		)
 	if _in_git_worktree(config_path()):
 		errors.append(
 			f"warning: config path {config_path()} is inside a git work tree; "
@@ -209,6 +230,7 @@ def load_or_default() -> tuple[Config, bool]:
 		email=EmailChannel(),
 		slack=SlackChannel(),
 		telegram=TelegramChannel(),
+		desktop=DesktopChannel(),
 		custom_sources=[],
 		enabled_source_ids=set(),
 	)

{android_watcher-1.0.0 → android_watcher-1.0.1}/src/android_watcher/tui/screens.py

@@ -12,7 +12,7 @@ from textual.widgets import Input, OptionList, Static
 from textual.widgets.option_list import Option
 
 from android_watcher.catalog import load_catalog
-from android_watcher.config import Config
+from android_watcher.config import Config, desktop_mechanism_available
 from android_watcher.models import Source
 
 NONE_SENTINEL = "__none__"
@@ -432,7 +432,9 @@ class MainMenuScreen(_Nav):
 	def _summaries(self) -> list[tuple[str, str, str]]:
 		c = self._config
 		channels = [
-			name for name, ch in (("slack", c.slack), ("telegram", c.telegram)) if ch.enabled
+			name
+			for name, ch in (("slack", c.slack), ("telegram", c.telegram), ("desktop", c.desktop))
+			if ch.enabled
 		]
 		sched = c.schedule
 		when = sched.cron if sched.interval == "cron" else f"{sched.interval} {sched.at}".strip()
@@ -746,7 +748,11 @@ class ChannelsScreen(_Nav):
 
 	def _channels(self):
 		c = self._config
-		return (("slack", "Slack", c.slack), ("telegram", "Telegram", c.telegram))
+		return (
+			("slack", "Slack", c.slack),
+			("telegram", "Telegram", c.telegram),
+			("desktop", "Desktop", c.desktop),
+		)
 
 	def compose(self) -> ComposeResult:
 		yield from _heading("Channels", "Where digests are delivered")
@@ -786,6 +792,16 @@ class ChannelsScreen(_Nav):
 		cid = listing.get_option_at_index(listing.highlighted).id
 		for oid, _name, ch in self._channels():
 			if oid == cid:
+				# Desktop click-to-open needs a notifier binary; refuse to enable it
+				# when none is installed (terminal-notifier on macOS, notify-send on Linux).
+				if oid == "desktop" and not ch.enabled and not desktop_mechanism_available():
+					self.app.bell()
+					self.app.notify(
+						"Install terminal-notifier (macOS) or notify-send (Linux) first.",
+						title="Desktop notifications unavailable",
+						severity="error",
+					)
+					return
 				ch.enabled = not ch.enabled
 				self._populate()
 				return
@@ -900,7 +916,11 @@ class ReviewScreen(_Nav):
 		else:
 			when = f"daily at {s.at}"
 		ai = "off" if c.ai.mode == "off" else f"claude ({c.ai.model})"
-		channels = [n for n, ch in (("slack", c.slack), ("telegram", c.telegram)) if ch.enabled]
+		channels = [
+			n
+			for n, ch in (("slack", c.slack), ("telegram", c.telegram), ("desktop", c.desktop))
+			if ch.enabled
+		]
 		channels_str = ", ".join(channels) if channels else "none — pick one to finish!"
 		return [
 			f"Sources    {watched_count(c)} selected",