@ciphore/radiocli 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -5,7 +5,128 @@ All notable changes to RadioCLI are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.2.4] - 2026-09-17
+
+### Added
+
+- Added a shared platform layer for runtime eligibility, capabilities, executable
+  discovery, package installation, storage paths, networking, IPC, desktop
+  helpers, and terminal launching.
+- Added first-class Node.js 22 and 24 CI coverage for macOS Apple Silicon and
+  Intel, Ubuntu x64 and arm64, Windows x64, and Windows 11 arm64, including
+  packed installation and native mpv IPC playback checks.
+- Added repeatable packed CLI and mpv playback checks in full FreeBSD, OpenBSD,
+  and NetBSD guest kernels, plus explicit installation and capability guidance
+  for additional Unix, WSL, Termux, Haiku, illumos, and AIX environments.
+- Added offline, low-bandwidth, screen-reader, reduced-motion, ASCII, limited-
+  color, and noninteractive terminal modes with deterministic full, compact,
+  and micro rendering coverage.
+- Added automatic HTTP/ICY metadata discovery when importing a direct station
+  URL from the CLI or the TUI command palette.
+
+### Changed
+
+- Centralized native package recipes and guided setup so dry runs and executed
+  commands use the same platform-specific definitions.
+- Expanded `radiocli doctor --json` with host, runtime, network, storage,
+  terminal, playback, desktop, scheduling, and optional-feature capabilities.
+- Reorganized installation, platform, architecture, reliability, privacy, and
+  contributor documentation as stable reference material with explicit support
+  boundaries and troubleshooting paths.
+- Changed TUI `:import` to add custom stream URLs, renamed full-library recovery
+  to `:restore`, and consolidated shell URL additions under `radiocli import`.
+- Placed newest imported stations after favorites and before recently played
+  stations in the Library.
+- Changed resume for live radio to reload the active stream at its current live
+  edge instead of replaying audio accumulated in mpv's paused buffer.
+
+### Fixed
+
+- Kept playback and the TUI usable when optional history, presence, cache, or
+  library writes fail, while preserving recoverable data after interrupted or
+  permission-denied writes.
+- Hardened alarm deletion, native scheduler cleanup, terminal reopening, Alarm
+  Guard ownership, system-volume restoration, and forced-process teardown.
+- Preserved exact arguments, data locations, and supported environment selectors
+  across macOS, Linux, BSD, and Windows child processes without forwarding
+  unrelated shell state.
+- Improved player discovery, mpv readiness and IPC handling, provider timeouts,
+  mirror fallback, offline cache behavior, and degraded terminal rendering.
+- Recovered ARM Linux playback from mpv audio-service initialization failures
+  by retrying once with ALSA first, retained bounded player diagnostics, and
+  stopped system-wide backend failures from skipping through every station.
+- Replaced stale Radio Browser hosts with live DNS service discovery and added
+  a TLS-verified resolver fallback for temporary hostname failures without
+  bypassing configured proxies.
+- Preserved full RGB theme colors when a terminal explicitly advertises
+  truecolor, even when its Node.js stream reports a conservative 256-color
+  depth; explicit 256-color, 16-color, and no-color modes remain unchanged.
+- Kept retained Search results playable after clearing the submitted query and
+  added `Ctrl+F` to favorite the selected result while query input is active,
+  without intercepting an ordinary `f` typed into the search text.
+- Dismissed added and removed favorite confirmations after 4.5 seconds on
+  Overview, Now Playing, Library, Explore, Search, Nearby, and country station
+  views.
+- Marked AirPlay controls as macOS-only, hid the unsupported Settings shortcut,
+  and kept non-macOS users on their current screen with a direct platform notice.
+- Corrected Windows terminal launches to create independent interactive console
+  handles and retain the intended user data location.
+
+### Security
+
+- Updated documentation-site dependencies to patched releases.
+- Limited child-process environments to the settings required for RadioCLI data
+  identity and native integrations, excluding unrelated credentials and proxy
+  secrets.
+- Made native cleanup and ownership checks fail closed when a job, helper,
+  process, or saved state cannot be identified safely.
+
+## [0.2.3] - 2026-09-07
+
+### Added
+
+- Added opt-in local coding-agent control through both a typed stdio MCP server
+  and `radiocli agent` shell commands, covering discovery, playback, favorites,
+  listening stats, appearance, and configurable task-completion actions.
+- Added automatic MCP setup for detected Codex, Claude Code, OpenCode, Cursor,
+  Gemini CLI, VS Code/Copilot Agent Host, and Orca-backed runtimes, plus a
+  portable configuration for other MCP clients.
+- Added typed MCP and voice-accessible alarm management, active ringing
+  controls, and macOS AirPlay discovery, receiver selection, local-output
+  switching, and ephemeral passcode submission.
+- Added `radiocli update --install`, package-manager-aware upgrade commands,
+  an in-app update indicator, read-only MCP update status, and
+  `radiocli mcp repair`.
+- Added Agent settings for installing or repairing MCP integrations and choosing
+  between a visible terminal player and headless playback.
+- Added the animated Gallop receiver as the new default and a color-field
+  Crossfade receiver.
+
+### Fixed
+
+- Agent playback continues to open the terminal TUI by default on every platform,
+  while interactive setup now explains the macOS Automation prompt and offers an
+  explicit headless opt-out. MCP guidance prevents ordinary task-completion radio
+  actions from creating implicit goals or monitors.
+- MCP registrations now use upgrade-stable, directly executable launchers,
+  including a shell-free Node command on Windows, and enabled registrations are
+  repaired after an in-app or CLI update.
+- Active interactive or agent playback now yields cleanly when an alarm begins,
+  preventing overlapping streams while preserving the alarm if TUI handoff fails.
+- Kept the Countries station-count column fixed while scrolling, added focused
+  marquee reading for overlong country and station names across Explore,
+  Library, and Nearby, and aligned Overview descriptions behind a compact
+  separator-free title column.
+
+### Security
+
+- Agent playback uses a single-owner, authenticated loopback session with
+  serialized commands, private discovery files, and strict isolation from
+  active alarm sessions. Agent tools accept saved or RadioCLI-discovered station
+  IDs rather than arbitrary stream URLs.
+- Alarm removal requires an exact ID and explicit confirmation. AirPlay receiver
+  IDs must come from local discovery, and receiver passcodes are never persisted
+  or echoed by agent responses.
 
 ## [0.2.2] - 2026-09-04
 
@@ -351,6 +472,8 @@ Initial public release.
 [0.2.0]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.0
 [0.2.1]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.1
 [0.2.2]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.2
+[0.2.3]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.3
+[0.2.4]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.4
 [0.1.4]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.4
 [0.1.3]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.3
 [0.1.2]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.2

package/CONTRIBUTING.md

@@ -12,19 +12,22 @@ npm run build
 npm run test
 ```
 
-Install `mpv` for playback controls, metadata polling, and the best playback
-experience:
+Install `mpv` for playback controls and metadata polling. On a macOS
+configuration supported by Homebrew:
 
 ```bash
 brew install mpv
 ```
 
-On Linux, use your package manager's `mpv` package. On Windows, use:
+On Linux, use your package manager's `mpv` package. On Windows x64, use:
 
 ```powershell
 winget install --id shinchiro.mpv -e
 ```
 
+Use the [platform installation routes](apps/docs/content/docs/platforms.mdx#installation-and-playback-prerequisites)
+for Windows arm64 and other package managers.
+
 ## Verification
 
 Run these before opening a PR:
@@ -34,11 +37,19 @@ npm run check
 npm run lint
 npm run test
 npm run build
+npm run pack:check
+npm run fresh:check -- --require-mpv
+npm run check:package
+npm run smoke:mcp
+npm run docs:check
+npm run docs:build
 ```
 
-Run `npm run smoke:playback` when changing playback code. It opens a public
-stream briefly, so do not run it in environments where audio/network access is
-not acceptable.
+Install documentation dependencies with `npm --prefix apps/docs ci` first.
+Run `npm run smoke:playback` when changing playback code. Its default fixture is
+a local WAV file; mpv uses null audio in deterministic package
+checks. These checks exercise the player process and controls, and do not prove
+speaker output. `npm run smoke:data` intentionally contacts public providers.
 
 Live provider checks are useful before releases, but ordinary pull requests
 should stay deterministic. Run `npm run verify:release` for a full maintainer
@@ -52,9 +63,28 @@ checks.
 - Never make location lookup implicit.
 - Prefer clear terminal text over decorative filler.
 - Keep command-line and TUI behavior aligned.
+- Put OS decisions in `src/platform`; keep capability availability separate from
+  runtime eligibility and recorded platform verification.
 - Add tests for parsing, storage, layout, or provider transformations when the
   behavior can be checked without live audio.
 
+## Platform verification
+
+The required Node 22/24 CI matrix tests x64 and arm64 installations and real mpv
+control. Weekly or manually triggered BSD checks execute the packed JavaScript
+in guest kernels. Changes to script harnesses
+also require `node --test scripts/packed-smoke.test-node.mjs scripts/install-smoke-mpv.test-node.mjs`.
+
+Record OS release, CPU, endianness, libc, Node/npm versions, artifact hash, and
+whether execution was native, virtualized, emulated, or mocked. An installation
+test, native command mock, or foreign binary inspection alone cannot promote a
+platform to supported. Follow the [support tiers](apps/docs/content/docs/platforms.mdx).
+
+The deterministic visual fixtures cover full, compact, and micro layouts, all
+major screens, and receiver styles. Preserve Unicode captures. When rendering
+changes intentionally, describe the visible effect in the pull request and do
+not update snapshots merely to hide failures.
+
 ## Issue Triage
 
 Playback issues should include station name, country, backend, and

package/README.md

@@ -26,7 +26,7 @@ Built with [Ink](https://github.com/vadimdemedes/ink),
 
 ## Quick start
 
-macOS with Homebrew:
+On macOS configurations supported by Homebrew:
 
 ```bash
 brew install ciphore/tap/radiocli
@@ -44,11 +44,43 @@ radiocli
 RadioCLI requires Node.js 22 or newer. The Homebrew formula installs `mpv` and
 FFmpeg. After an npm install, `radiocli setup` detects the operating system and
 package manager, lets you choose `mpv`, FFmpeg, and VLC, installs the selected
-native tools with branded progress feedback, and verifies playback readiness.
+native tools with branded progress feedback, and checks that executables are
+available. Play a station to verify the actual audio path. Intel or older macOS
+installations should consult the platform matrix for alternative package routes.
 
 See the [installation guide](apps/docs/content/docs/getting-started/install.mdx)
 for Windows, Linux distributions, AirPlay prerequisites, and fallback players.
 
+## Platform coverage
+
+RadioCLI separates core playback, storage, terminal rendering, desktop helpers,
+and native alarm services. A missing scheduler or clipboard helper leaves the
+other features available. `radiocli doctor --json` reports each capability,
+terminal and network policy, and runtime eligibility separately.
+
+The [platform matrix](apps/docs/content/docs/platforms.mdx) distinguishes required
+CI targets from verified installations, experimental community paths, and known
+runtime blockers. Node 22 and 24 are the reference test lines. BSD package plans,
+Termux, Haiku and illumos guidance do not imply that every OS/CPU combination has
+been exercised. AIX playback and Haiku's packaged Node 20 remain explicit gaps.
+Linux without a usable systemd user session can still run the player and TUI;
+reliable background alarms require a verified native adapter.
+
+Invocation preferences do not change saved settings:
+
+```bash
+RADIOCLI_ASCII=1 radiocli             # ASCII decoration; station names preserved
+NO_COLOR=1 radiocli                  # no color or background fills
+RADIOCLI_SCREEN_READER=1 radiocli     # readable controls; no visualizer animation
+RADIOCLI_OFFLINE=1 radiocli           # cached directories and saved stations
+RADIOCLI_LOW_BANDWIDTH=1 radiocli     # cached atlas; no automatic receiver scan
+```
+
+Offline mode disables directory, location, update, vote and receiver-discovery
+requests. An external player still needs a connection to listen to a live stream.
+For proxy, SSH, read-only storage and custom-player paths, see
+[troubleshooting](apps/docs/content/docs/troubleshooting.mdx).
+
 ## Visual tour
 
 These recordings come from the built TUI. Generate them locally with
@@ -81,10 +113,10 @@ These recordings come from the built TUI. Generate them locally with
 | `←` / `→` or `Tab` / `Shift+Tab` | Switch screens |
 | `↑` / `↓` or `n` / `p` | Move the selection |
 | `Enter` | Open or tune the selection |
-| `space` or `F8` | Pause or resume with `mpv` |
+| `space` or `F8` | Pause; resume reconnects at the live edge with `mpv` |
 | `,` / `.` or `F7` / `F9` | Previous or next station |
 | `+` / `-` | Change volume |
-| `f` | Save or remove a favorite |
+| `f` (`Ctrl+F` while typing in Search) | Save or remove a favorite |
 | `?` | Open all shortcuts and commands |
 | `q` or `Ctrl+C` twice | Quit cleanly |
 
@@ -94,20 +126,58 @@ covers filters, playback, media-key learning, AirPlay, and every command.
 
 ## CLI
 
+RadioCLI can also be controlled by local coding agents. Run `radiocli setup`
+and opt into MCP, or use `radiocli setup --mcp`, to configure detected Codex,
+Claude, OpenCode, Cursor, Gemini, VS Code/Copilot, and Orca-backed runtimes
+automatically. From the TUI, open **Settings → Agent control & MCP** and turn on
+**Allow local agent control** for the same one-step setup—no terminal command is
+required. The same actions are
+available to non-MCP harnesses through `radiocli agent` and `radiocli alarm`:
+search and play stations, browse recents/favorites/nearby stations, favorite the
+current station, inspect listening stats, create and control alarms, control
+macOS AirPlay, change the receiver look, or run a user-configured completion
+preset. Codex Voice can invoke those same typed MCP tools. Agent playback opens
+the normal RadioCLI TUI in a terminal window by default on macOS, Windows, and
+Linux. Interactive setup explains that macOS may require the agent host to approve
+a one-time Automation prompt; users can explicitly opt into headless playback.
+Scheduled alarms remain isolated and always use local output rather than
+unattended AirPlay. See the
+[CLI guide](apps/docs/content/docs/getting-started/cli.mdx#local-agent-and-mcp-control).
+
 ```bash
 radiocli                 # Start the TUI
 radiocli check           # Check providers, playback tools, and the local store
 radiocli doctor --json   # Create a redacted support report
 radiocli search "japan hits"
 radiocli countries
+radiocli import https://example.com/live.mp3
 radiocli import stations.m3u
 radiocli export favorites.m3u
-radiocli add-url <stream-url> [station name]
 radiocli alarm list
 radiocli alarm doctor
+radiocli update --install # Upgrade and repair enabled MCP registrations
 ```
 
-RadioCLI imports `.m3u`, `.pls`, and `.xspf` playlists. It exports favorites
+Existing installations keep their library and preferences when upgraded. Use
+`radiocli update` to inspect the detected Homebrew, npm, pnpm, or Bun command,
+or `radiocli update --install` to run it. MCP registrations use an
+upgrade-stable launcher so versioned package paths do not break them. On
+Windows this is a shell-free Node command; on Unix it uses the `radiocli` shim.
+Run `radiocli mcp status` to inspect registrations and `radiocli mcp repair`
+after moving an installation or when an agent client reports a stale server;
+fully quit and reopen agent clients after enabling, repairing, or upgrading.
+Until that restart, even a newly created task in an already-running client will
+not have RadioCLI's tools and may incorrectly fall back to browser playback.
+
+RadioCLI imports direct HTTP(S) station streams as well as `.m3u`, `.pls`, and
+`.xspf` playlists. Direct import is useful when a station cannot be found through
+an open radio directory—for example, an iHeartMedia station that is available
+only through its direct stream. Find the station's direct stream URL and run
+`radiocli import <stream-url> [station name]`, or enter
+`:import <stream-url> [station name]` in the TUI. RadioCLI reads available
+HTTP/ICY metadata to discover the name, codec, bitrate, and homepage; the name
+argument is optional and overrides the published name. Imported stations appear
+after favorites and before recently played stations. RadioCLI exports favorites
 and imported streams as `.m3u`.
 
 Alarms are experimental beta functionality and live under **Overview**,
@@ -184,6 +254,8 @@ complete data-flow description.
 - `src/ui` — screens, input, layout, and terminal rendering
 - `src/providers` — station directories, resolution, and caches
 - `src/player` — playback backends, metadata, and AirPlay
+- `src/platform` — host identity, independent capabilities, native command plans,
+  paths, terminal policy, networking and runtime eligibility
 - `src/alarms` — schedules, native registration, Alarm Guard, and active controls
 - `src/storage` — local library persistence and migration
 - `apps/docs` — documentation website and manual
@@ -201,9 +273,10 @@ npm run verify
 npm run dev
 ```
 
-`npm run verify` checks types, lint, tests, the production build, and package
-contents. Playback and live-data smoke tests are available separately because
-they contact public services or start a local player.
+`npm run verify` checks types, lint, tests, the production build, and live provider
+data. `npm run fresh:check -- --require-mpv` tests packed installs with and without
+optional dependencies using a local WAV, real mpv IPC controls and MCP. See
+[contribution checks](CONTRIBUTING.md) for documentation and packaging validation.
 
 ## Contributing
 
@@ -214,9 +287,10 @@ include `radiocli check` output with playback reports.
 
 - [Getting started](apps/docs/content/docs/index.mdx)
 - [Installation](apps/docs/content/docs/getting-started/install.mdx)
+- [Platform matrix](apps/docs/content/docs/platforms.mdx)
+- [Troubleshooting](apps/docs/content/docs/troubleshooting.mdx)
 - [Controls](apps/docs/content/docs/getting-started/tui-controls.mdx)
 - [Architecture](apps/docs/content/docs/architecture.mdx)
-- [Roadmap](apps/docs/content/docs/roadmap.mdx)
 - [Release packaging](apps/docs/content/docs/release-packaging.mdx)
 
 Run the documentation site locally with `npm run docs:dev`.

package/dist/agent/alarm-service.js

@@ -0,0 +1,210 @@
+import { canonicalizeAlarmTime, canonicalizeIsoWeekdays, canonicalizeTimeZone, nextOccurrenceForAlarm } from '../alarms/schedule.js';
+import { connectActiveAlarms } from '../alarms/active-session.js';
+import { createSchedulerService } from '../alarms/scheduler.js';
+export class AgentAlarmService {
+    store;
+    resolveStation;
+    scheduler;
+    handoffToInteractive;
+    constructor(store, resolveStation, scheduler = createSchedulerService(), handoffToInteractive) {
+        this.store = store;
+        this.resolveStation = resolveStation;
+        this.scheduler = scheduler;
+        this.handoffToInteractive = handoffToInteractive;
+    }
+    async list() {
+        return Promise.all(this.store.listAlarms().map(alarm => this.describe(alarm)));
+    }
+    async status() {
+        const alarms = this.store.listAlarms();
+        return {
+            active: await this.activeStatuses(),
+            scheduler: await this.scheduler.runtimeStatus(alarms),
+            alarms: await Promise.all(alarms.map(alarm => this.describe(alarm)))
+        };
+    }
+    async create(input) {
+        const station = await this.requiredStation(input.stationId);
+        const fallbackStation = input.fallbackStationId
+            ? await this.requiredStation(input.fallbackStationId)
+            : undefined;
+        const alarmInput = {
+            label: cleanLabel(input.label ?? station.name),
+            enabled: input.enabled ?? true,
+            station,
+            schedule: normalizeSchedule(input.schedule),
+            playback: {
+                volume: boundedInteger(input.volume ?? 40, 'volume', 0, 100),
+                fadeSeconds: boundedInteger(input.fadeSeconds ?? 0, 'fadeSeconds', 0, 3600),
+                stopAfterMinutes: boundedInteger(input.stopAfterMinutes ?? 60, 'stopAfterMinutes', 1, 10080),
+                ...(fallbackStation ? { fallbackStation } : {})
+            },
+            reliability: {
+                missedRunGraceMinutes: boundedInteger(input.missedRunGraceMinutes ?? 10, 'missedRunGraceMinutes', 0, 10080),
+                wakeIfSupported: input.wakeIfSupported ?? false,
+                keepAwakeUntilAlarm: input.keepAwakeUntilAlarm ?? false
+            }
+        };
+        const alarm = this.store.addAlarm(alarmInput);
+        await this.syncSaved(alarm);
+        return this.describe(alarm);
+    }
+    async update(id, input) {
+        const alarm = this.requiredAlarm(id);
+        const station = input.stationId ? await this.requiredStation(input.stationId) : alarm.station;
+        const fallbackStation = input.clearFallback
+            ? undefined
+            : input.fallbackStationId ? await this.requiredStation(input.fallbackStationId) : alarm.playback.fallbackStation;
+        const updated = this.store.updateAlarm(alarm.id, {
+            label: input.label === undefined ? alarm.label : cleanLabel(input.label),
+            enabled: input.enabled ?? alarm.enabled,
+            station,
+            schedule: input.schedule ? normalizeSchedule(input.schedule) : alarm.schedule,
+            playback: {
+                volume: boundedInteger(input.volume ?? alarm.playback.volume, 'volume', 0, 100),
+                fadeSeconds: boundedInteger(input.fadeSeconds ?? alarm.playback.fadeSeconds, 'fadeSeconds', 0, 3600),
+                stopAfterMinutes: boundedInteger(input.stopAfterMinutes ?? alarm.playback.stopAfterMinutes, 'stopAfterMinutes', 1, 10080),
+                ...(fallbackStation ? { fallbackStation } : {})
+            },
+            reliability: {
+                missedRunGraceMinutes: boundedInteger(input.missedRunGraceMinutes ?? alarm.reliability.missedRunGraceMinutes, 'missedRunGraceMinutes', 0, 10080),
+                wakeIfSupported: input.wakeIfSupported ?? alarm.reliability.wakeIfSupported,
+                keepAwakeUntilAlarm: input.keepAwakeUntilAlarm ?? alarm.reliability.keepAwakeUntilAlarm
+            }
+        });
+        await this.syncSaved(updated);
+        return this.describe(updated);
+    }
+    async setEnabled(id, enabled) {
+        const alarm = this.store.toggleAlarm(this.requiredAlarm(id).id, enabled);
+        await this.syncSaved(alarm);
+        return this.describe(alarm);
+    }
+    async remove(id, confirm) {
+        if (!confirm)
+            throw new Error('Alarm removal requires confirm=true. List alarms first and confirm the exact alarm ID with the user.');
+        const alarm = this.requiredAlarm(id);
+        await this.scheduler.remove(alarm.id);
+        if (!this.store.removeAlarm(alarm.id))
+            throw new Error(`Alarm not found: ${id}`);
+        return { ok: true, removed: alarm.id };
+    }
+    async sync() {
+        return this.scheduler.syncAll(this.store.listAlarms());
+    }
+    async controlActive(input) {
+        const { client, status } = await this.selectActive(input.alarmId, input.occurrenceAt);
+        if (input.action === 'dismiss')
+            await client.dismiss();
+        else if (input.action === 'keep-playing')
+            await client.keepPlaying();
+        else if (input.action === 'handoff') {
+            if (status.state !== 'playing')
+                throw new Error('Alarm playback is still starting.');
+            if (!this.handoffToInteractive)
+                throw new Error('Interactive playback handoff is unavailable.');
+            await this.handoffToInteractive(status);
+            await client.handoff();
+        }
+        else
+            await client.snooze(boundedInteger(input.snoozeMinutes ?? 10, 'snoozeMinutes', 1, 1440));
+        return { ok: true, action: input.action, alarm: activeStatusForAgent(status) };
+    }
+    async describe(alarm) {
+        return {
+            id: alarm.id,
+            label: alarm.label,
+            enabled: alarm.enabled,
+            station: { id: `${alarm.station.provider}:${alarm.station.id}`, name: alarm.station.name },
+            schedule: alarm.schedule,
+            nextOccurrence: nextOccurrenceForAlarm(alarm, new Date())?.toISOString() ?? null,
+            playback: {
+                volume: alarm.playback.volume,
+                fadeSeconds: alarm.playback.fadeSeconds,
+                stopAfterMinutes: alarm.playback.stopAfterMinutes,
+                ...(alarm.playback.fallbackStation ? { fallbackStation: {
+                        id: `${alarm.playback.fallbackStation.provider}:${alarm.playback.fallbackStation.id}`,
+                        name: alarm.playback.fallbackStation.name
+                    } } : {})
+            },
+            reliability: alarm.reliability,
+            lastRun: alarm.lastRun,
+            snoozedUntil: alarm.nextOverride?.at
+        };
+    }
+    async activeStatuses() {
+        return (await Promise.all((await connectActiveAlarms()).map(client => client.status()))).map(activeStatusForAgent);
+    }
+    async selectActive(alarmId, occurrenceAt) {
+        const matches = [];
+        for (const client of await connectActiveAlarms()) {
+            const status = await client.status();
+            if ((!alarmId || status.alarmId === alarmId) && (!occurrenceAt || status.scheduledAt === occurrenceAt))
+                matches.push({ client, status });
+        }
+        if (!matches.length)
+            throw new Error('No matching alarm is currently ringing.');
+        if (matches.length > 1)
+            throw new Error('Multiple alarms are ringing. List alarm status, then provide alarm_id and optionally occurrence_at.');
+        return matches[0];
+    }
+    requiredAlarm(id) {
+        const alarm = this.store.getAlarm(id);
+        if (!alarm)
+            throw new Error(`Alarm not found: ${id}`);
+        return alarm;
+    }
+    async requiredStation(id) {
+        const station = await this.resolveStation(id);
+        if (!station)
+            throw new Error(`Unknown station ID: ${id}. Search or browse first.`);
+        return station;
+    }
+    async syncSaved(alarm) {
+        try {
+            await this.scheduler.sync(alarm);
+        }
+        catch (error) {
+            throw new Error(`Alarm ${alarm.id} was saved, but scheduler setup is degraded: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+function normalizeSchedule(schedule) {
+    if (schedule.type === 'once') {
+        const instant = new Date(schedule.at);
+        if (!/(?:Z|[+-]\d{2}:\d{2})$/.test(schedule.at) || !Number.isFinite(instant.getTime()) || instant.getUTCSeconds() !== 0 || instant.getUTCMilliseconds() !== 0) {
+            throw new Error('One-time alarms require an absolute ISO-8601 minute with an offset or Z and zero seconds.');
+        }
+        if (instant.getTime() <= Date.now())
+            throw new Error('One-time alarms must be scheduled in the future.');
+        return { type: 'once', at: instant.toISOString() };
+    }
+    return {
+        type: 'recurring',
+        time: canonicalizeAlarmTime(schedule.time),
+        weekdays: canonicalizeIsoWeekdays(schedule.weekdays),
+        timezone: canonicalizeTimeZone(schedule.timezone)
+    };
+}
+function boundedInteger(value, label, min, max) {
+    if (!Number.isInteger(value) || value < min || value > max)
+        throw new Error(`${label} must be an integer from ${min} to ${max}.`);
+    return value;
+}
+function cleanLabel(value) {
+    const label = value.trim();
+    if (!label || label.length > 120 || /[\u0000-\u001F\u007F-\u009F]/.test(label))
+        throw new Error('Alarm label must be 1-120 printable characters.');
+    return label;
+}
+function activeStatusForAgent(status) {
+    return {
+        alarmId: status.alarmId,
+        scheduledAt: status.scheduledAt,
+        stationName: status.stationName,
+        ...(status.station ? { station: { id: `${status.station.provider}:${status.station.id}`, name: status.station.name } } : {}),
+        startedAt: status.startedAt,
+        state: status.state,
+        keepPlaying: status.keepPlaying
+    };
+}