@ciphore/radiocli 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -5,6 +5,82 @@ 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).
 
+## [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
@@ -397,6 +473,7 @@ Initial public release.
 [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 |
 
@@ -118,9 +150,9 @@ 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
@@ -137,7 +169,15 @@ 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 `.m3u`, `.pls`, and `.xspf` playlists. It exports favorites
+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**,
@@ -214,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
@@ -231,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
 
@@ -244,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/headless-host.js

@@ -2,7 +2,7 @@ import { PlayerController } from '../player/player-controller.js';
 import { ProviderManager } from '../providers/provider-manager.js';
 import { JsonLibraryStore, stationKey } from '../storage/store.js';
 import { startRadioSession } from './session.js';
-import { detectPlaybackBackends } from '../player/backend-install.js';
+import { airPlayMacOSOnlyMessage, detectPlaybackBackends, isAirPlayPlatformSupported } from '../player/backend-install.js';
 export async function runHeadlessAgentHost() {
     const store = new JsonLibraryStore();
     const providers = new ProviderManager();
@@ -10,23 +10,43 @@ export async function runHeadlessAgentHost() {
     player.refreshDetectedBackends();
     let station = null;
     let queue = [];
-    const status = () => ({ owner: 'headless', playback: player.getState(), station, queue, output: {
+    let persistenceWarning;
+    const persistHistory = (write) => {
+        try {
+            write();
+        }
+        catch (error) {
+            const code = error?.code;
+            const detail = typeof code === 'string' && /^[A-Z][A-Z0-9_]+$/.test(code) ? ` (${code})` : '';
+            persistenceWarning = `Listening history was not saved${detail}. Check storage permissions or set RADIOCLI_HOME to a private writable directory.`;
+        }
+    };
+    const saveLibrary = (write) => {
+        write();
+        // Optional writes can be no-ops, so only an explicit successful save clears
+        // a prior warning. Explicit failures still reject the control request.
+        persistenceWarning = undefined;
+    };
+    const status = () => ({ owner: 'headless', playback: player.getState(), station, queue, persistenceWarning, output: {
             preferredBackend: store.snapshot().settings.preferredBackend,
             preferredAirPlayDevice: store.snapshot().settings.preferredAirPlayDevice
         } });
     const result = (message, ok = true, data) => ({ ok, message, status: status(), ...(data ? { data } : {}) });
     const play = async (next, nextQueue = [next]) => {
-        store.finishActiveListeningSession();
+        persistHistory(() => store.finishActiveListeningSession());
         await player.stop();
         const resolved = await providers.resolve(next);
         await player.play(next, resolved.url);
         station = next;
         queue = nextQueue.length ? nextQueue : [next];
-        store.addRecent(next);
-        store.startListeningSession(next);
+        persistHistory(() => store.addRecent(next));
+        persistHistory(() => store.startListeningSession(next));
         return result(`Playing ${next.name}.`);
     };
     const handle = async (command) => {
+        if (['airplay-list', 'airplay-select', 'airplay-passcode'].includes(command.type) && !isAirPlayPlatformSupported()) {
+            return result(airPlayMacOSOnlyMessage, false, command.type === 'airplay-list' ? [] : undefined);
+        }
         if (command.type === 'status')
             return result(station ? `${player.getState().state}: ${station.name}` : 'RadioCLI is idle.');
         if (command.type === 'play') {
@@ -37,17 +57,17 @@ export async function runHeadlessAgentHost() {
         if (command.type === 'pause') {
             const control = await player.pause();
             if (control.ok)
-                store.finishActiveListeningSession();
+                persistHistory(() => store.finishActiveListeningSession());
             return result(control.message ?? 'Paused.', control.ok);
         }
         if (command.type === 'resume') {
             const control = await player.resume();
             if (control.ok && station)
-                store.startListeningSession(station);
+                persistHistory(() => store.startListeningSession(station));
             return result(control.message ?? 'Resumed.', control.ok);
         }
         if (command.type === 'stop') {
-            store.finishActiveListeningSession();
+            persistHistory(() => store.finishActiveListeningSession());
             await player.stop();
             station = null;
             queue = [];
@@ -55,7 +75,7 @@ export async function runHeadlessAgentHost() {
             return result('Stopped RadioCLI.');
         }
         if (command.type === 'alarm-preempt') {
-            store.finishActiveListeningSession();
+            persistHistory(() => store.finishActiveListeningSession());
             await player.stop();
             station = null;
             queue = [];
@@ -64,7 +84,7 @@ export async function runHeadlessAgentHost() {
         if (command.type === 'set-volume') {
             const control = await player.setVolume(command.volume);
             if (control.ok)
-                store.updateSettings({ volume: player.getState().volume });
+                saveLibrary(() => store.updateSettings({ volume: player.getState().volume }));
             return result(control.message ?? `Volume ${player.getState().volume}.`, control.ok);
         }
         if (command.type === 'set-muted') {
@@ -77,7 +97,7 @@ export async function runHeadlessAgentHost() {
                 return result('No active station to favorite.', false);
             const current = store.isFavorite(target);
             if (current !== command.favorite)
-                store.toggleFavorite(target);
+                saveLibrary(() => store.toggleFavorite(target));
             if (command.favorite && !current && store.snapshot().settings.shareDirectoryVotes)
                 void providers.vote(target);
             return result(`${command.favorite ? 'Favorited' : 'Removed favorite'}: ${target.name}.`);
@@ -95,8 +115,10 @@ export async function runHeadlessAgentHost() {
                 return switchToLocal();
             if (!detectPlaybackBackends().includes('airplay'))
                 return result('AirPlay playback is unavailable; run radiocli doctor.', false);
-            store.updateSettings({ preferredAirPlayDevice: device.id });
-            store.updateSettings({ preferredBackend: 'airplay' });
+            saveLibrary(() => {
+                store.updateSettings({ preferredAirPlayDevice: device.id });
+                store.updateSettings({ preferredBackend: 'airplay' });
+            });
             if (station && ['playing', 'paused', 'loading'].includes(player.getState().state))
                 return play(station, queue);
             return result(`Audio output set to AirPlay receiver ${device.name}.`);
@@ -108,7 +130,7 @@ export async function runHeadlessAgentHost() {
             return result(control.message ?? 'AirPlay code sent.', control.ok);
         }
         if (command.type === 'update-settings') {
-            store.updateSettings(command.settings);
+            saveLibrary(() => store.updateSettings(command.settings));
             return result('RadioCLI settings updated.');
         }
         const currentIndex = station ? queue.findIndex(item => stationKey(item) === stationKey(station)) : -1;
@@ -121,7 +143,7 @@ export async function runHeadlessAgentHost() {
         const backend = backends.includes('mpv') ? 'mpv' : backends.includes('ffplay') ? 'ffplay' : backends.includes('vlc') ? 'vlc' : null;
         if (!backend)
             return result('No local playback backend is available. Run radiocli setup to install mpv.', false);
-        store.updateSettings({ preferredBackend: backend });
+        saveLibrary(() => store.updateSettings({ preferredBackend: backend }));
         if (station && ['playing', 'paused', 'loading'].includes(player.getState().state))
             return play(station, queue);
         return result(`Audio output set to this device (${backend}).`);
@@ -129,11 +151,11 @@ export async function runHeadlessAgentHost() {
     const session = await startRadioSession(handle);
     const checkpoint = setInterval(() => {
         if (player.getState().state === 'playing')
-            store.checkpointActiveListeningSession();
+            persistHistory(() => store.checkpointActiveListeningSession());
     }, 30_000);
     const shutdown = async () => {
         clearInterval(checkpoint);
-        store.finishActiveListeningSession();
+        persistHistory(() => store.finishActiveListeningSession());
         await player.stop();
         await session.close();
     };

package/dist/agent/launcher.js

@@ -1,71 +1,10 @@
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { basename, join } from 'node:path';
-import { detectAlarmTerminal } from '../alarms/terminal-launcher.js';
-const linuxTerminals = new Set(['alacritty', 'foot', 'ghostty', 'gnome-terminal', 'kitty', 'konsole', 'mate-terminal', 'qterminal', 'terminator', 'tilix', 'wezterm', 'xfce4-terminal', 'x-terminal-emulator']);
-export async function launchRadioTui(nodePath, cliPath, encodedCommand) {
-    const terminal = detectAlarmTerminal();
-    const direct = environmentCommand(nodePath, cliPath, ['agent-ui', encodedCommand]);
-    const command = `${direct.map(shellQuote).join(' ')}`;
-    if (terminal === 'darwin:apple-terminal')
-        await launched(spawnDetached('/usr/bin/osascript', appleTerminalScript(command)));
-    else if (terminal === 'darwin:iterm')
-        await launched(spawnDetached('/usr/bin/osascript', iTermScript(command)));
-    else if (terminal === 'darwin:wezterm')
-        await launched(spawnDetached('/usr/bin/open', ['-na', 'WezTerm', '--args', 'start', '--always-new-process', '--', ...direct]));
-    else if (terminal === 'darwin:ghostty')
-        await launched(spawnDetached('/usr/bin/open', ['-na', 'Ghostty', '--args', '-e', ...direct]));
-    else if (terminal === 'darwin:kitty')
-        await launched(spawnDetached('/usr/bin/open', ['-na', 'kitty', '--args', '--detach', ...direct]));
-    else if (terminal === 'win32:windows-terminal')
-        await launched(spawnDetached('wt.exe', ['-w', 'new', 'new-tab', '--title', 'RadioCLI', ...direct]));
-    else if (terminal === 'win32:console')
-        await launched(spawnDetached('cmd.exe', ['/d', '/c', 'start', 'RadioCLI', 'cmd.exe', '/k', windowsCommand(direct)]));
-    else if (terminal.startsWith('linux:')) {
-        const executable = terminal.slice('linux:'.length);
-        if (!linuxTerminals.has(basename(executable)))
-            throw new Error('Saved Linux terminal is not supported.');
-        const name = basename(executable);
-        const prefix = name === 'gnome-terminal' || name === 'mate-terminal' || name === 'xfce4-terminal'
-            ? ['--']
-            : name === 'wezterm' ? ['start', '--always-new-process', '--'] : ['-e'];
-        await launched(spawnDetached(executable, [...prefix, ...direct]));
-    }
-    else {
-        throw new Error('No supported graphical terminal was found. Set agentControl.openUiOnPlay to false or open radiocli manually.');
-    }
+import { launchTerminalCommand } from '../platform/terminals.js';
+import { waitForLaunch } from '../platform/launch-command.js';
+/** The agent service verifies the authenticated session after this request. */
+export async function launchRadioTui(nodePath, cliPath, encodedCommand, options = {}) {
+    await launchTerminalCommand({ ...options, nodePath, args: [cliPath, 'agent-ui', encodedCommand], title: 'RadioCLI' });
 }
 export async function launchHeadlessHost(nodePath, cliPath) {
-    await launched(spawnDetached(nodePath, [cliPath, 'agent-host']));
-}
-function environmentCommand(nodePath, cliPath, args) {
-    const command = [nodePath, cliPath, ...args];
-    const radioCliHome = process.env.RADIOCLI_HOME;
-    if (!radioCliHome)
-        return command;
-    if (process.platform === 'win32') {
-        return ['cmd.exe', '/d', '/c', `set "RADIOCLI_HOME=${cmdEscape(radioCliHome)}" && ${windowsCommand(command)}`];
-    }
-    return ['/usr/bin/env', `RADIOCLI_HOME=${radioCliHome}`, ...command];
-}
-function shellQuote(value) { return `'${value.replaceAll("'", `'\\''`)}'`; }
-function windowsCommand(values) { return values.map(value => `"${value.replaceAll('"', '""')}"`).join(' '); }
-function cmdEscape(value) { return value.replaceAll('%', '%%').replaceAll('"', '""').replaceAll('^', '^^').replaceAll('&', '^&').replaceAll('|', '^|').replaceAll('<', '^<').replaceAll('>', '^>'); }
-function appleTerminalScript(command) { return ['-e', 'on run argv', '-e', 'tell application "Terminal"', '-e', 'activate', '-e', 'do script (item 1 of argv)', '-e', 'end tell', '-e', 'end run', command]; }
-function iTermScript(command) { return ['-e', 'on run argv', '-e', 'tell application "iTerm"', '-e', 'activate', '-e', 'set w to (create window with default profile)', '-e', 'tell current session of w to write text (item 1 of argv)', '-e', 'end tell', '-e', 'end run', command]; }
-function spawnDetached(command, args) { return spawn(command, [...args], { detached: true, stdio: 'ignore', windowsHide: false }); }
-function launched(child) { return new Promise((resolve, reject) => { child.once('error', reject); child.once('spawn', () => { child.unref(); resolve(); }); }); }
-export function resolveExecutable(input, env = process.env, platform = process.platform) {
-    if ((input.includes('/') || input.includes('\\')) && existsSync(input))
-        return input;
-    const suffixes = platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
-    const pathDelimiter = platform === 'win32' ? ';' : ':';
-    for (const directory of (env.PATH ?? '').split(pathDelimiter)) {
-        for (const suffix of suffixes) {
-            const path = join(directory, `${input}${suffix}`);
-            if (existsSync(path))
-                return path;
-        }
-    }
-    return undefined;
+    await waitForLaunch(spawn(nodePath, [cliPath, 'agent-host'], { detached: true, stdio: 'ignore', windowsHide: false }));
 }

package/dist/agent/mcp-install.js

@@ -5,7 +5,7 @@ import { dirname, join } from 'node:path';
 import { applyEdits, modify, parse } from 'jsonc-parser';
 import { JsonLibraryStore } from '../storage/store.js';
 import { defaultAgentControlSettings } from '../types.js';
-import { resolveExecutable } from './launcher.js';
+import { resolveCommandDetails } from '../platform/executables.js';
 const formatting = { insertSpaces: true, tabSize: 2, eol: '\n' };
 export async function configureMcpIntegrations(enabled, runtime, output = process.stdout) {
     const store = new JsonLibraryStore();
@@ -31,7 +31,7 @@ export async function configureMcpIntegrations(enabled, runtime, output = proces
     }
     else
         results.push(notFound('Codex'));
-    const claude = resolveExecutable('claude');
+    const claude = resolveCommandDetails('claude', { env: process.env }).path;
     if (claude) {
         results.push(await configureCliClient('Claude Code', claude, enabled
             ? ['mcp', 'add', '--scope', 'user', 'radiocli', '--', ...command]
@@ -40,7 +40,7 @@ export async function configureMcpIntegrations(enabled, runtime, output = proces
     else
         results.push(notFound('Claude Code'));
     const openCodePath = openCodeConfigPath();
-    if (resolveExecutable('opencode') || existsSync(openCodePath)) {
+    if (resolveCommandDetails('opencode', { env: process.env }).path || existsSync(openCodePath)) {
         try {
             updateOpenCodeConfig(openCodePath, enabled, command);
             results.push({ client: 'OpenCode', status: enabled ? 'configured' : 'removed', detail: openCodePath });
@@ -54,13 +54,13 @@ export async function configureMcpIntegrations(enabled, runtime, output = proces
     configureJsonClient(results, 'Cursor', cursorDetected(), join(homedir(), '.cursor', 'mcp.json'), ['mcpServers', 'radiocli'], enabled, {
         command: command[0], args: command.slice(1)
     });
-    configureJsonClient(results, 'Gemini CLI', Boolean(resolveExecutable('gemini')), join(homedir(), '.gemini', 'settings.json'), ['mcpServers', 'radiocli'], enabled, {
+    configureJsonClient(results, 'Gemini CLI', Boolean(resolveCommandDetails('gemini', { env: process.env }).path), join(homedir(), '.gemini', 'settings.json'), ['mcpServers', 'radiocli'], enabled, {
         command: command[0], args: command.slice(1)
     });
     configureJsonClient(results, 'VS Code / Copilot Agent Host', vsCodeDetected(), join(homedir(), '.copilot', 'mcp-config.json'), ['servers', 'radiocli'], enabled, {
         type: 'stdio', command: command[0], args: command.slice(1)
     });
-    if (resolveExecutable('orca')) {
+    if (resolveCommandDetails('orca', { env: process.env }).path) {
         results.push({ client: 'Orca', status: 'inherited', detail: 'Orca exposes MCP integrations through its configured Codex/Claude agent runtimes.' });
     }
     else
@@ -182,7 +182,7 @@ export function probeMcpServer(command, timeoutMs = 5_000) {
     });
 }
 function matchingRadioCliShim(runtime, platform) {
-    const candidate = resolveExecutable('radiocli', process.env, platform);
+    const candidate = resolveCommandDetails('radiocli', { env: process.env, platform }).path;
     if (!candidate)
         return undefined;
     if (!usableDirectLauncher(candidate, platform))
@@ -204,16 +204,16 @@ async function mcpClientStates(command) {
     const vscodePath = join(homedir(), '.copilot', 'mcp-config.json');
     return {
         codex: await codexClientState(resolveCodexExecutable(), command),
-        claude: await claudeClientState(resolveExecutable('claude'), command),
-        opencode: jsonClientState(Boolean(resolveExecutable('opencode') || existsSync(openCodePath)), openCodePath, [
+        claude: await claudeClientState(resolveCommandDetails('claude', { env: process.env }).path, command),
+        opencode: jsonClientState(Boolean(resolveCommandDetails('opencode', { env: process.env }).path || existsSync(openCodePath)), openCodePath, [
             ['mcp', 'servers', 'radiocli'], ['mcp', 'radiocli']
         ], command),
         cursor: jsonClientState(cursorDetected(), cursorPath, [['mcpServers', 'radiocli']], command),
-        gemini: jsonClientState(Boolean(resolveExecutable('gemini')), geminiPath, [['mcpServers', 'radiocli']], command),
+        gemini: jsonClientState(Boolean(resolveCommandDetails('gemini', { env: process.env }).path), geminiPath, [['mcpServers', 'radiocli']], command),
         vscode: jsonClientState(vsCodeDetected(), vscodePath, [['servers', 'radiocli']], command),
         orca: {
-            detected: Boolean(resolveExecutable('orca')),
-            state: resolveExecutable('orca') ? 'managed-by-client' : 'not-found',
+            detected: Boolean(resolveCommandDetails('orca', { env: process.env }).path),
+            state: resolveCommandDetails('orca', { env: process.env }).path ? 'managed-by-client' : 'not-found',
             detail: 'inherits MCP configuration from its Codex or Claude runtime'
         },
         portable: jsonClientState(true, portableConfigPath(), [['mcpServers', 'radiocli']], command)
@@ -226,7 +226,7 @@ export function resolveCodexExecutable(env = process.env, platform = process.pla
     const configured = env.CODEX_CLI_PATH;
     if (configured && existsSync(configured))
         return configured;
-    const pathExecutable = resolveExecutable('codex', env, platform);
+    const pathExecutable = resolveCommandDetails('codex', { env, platform, home }).path;
     if (pathExecutable)
         return pathExecutable;
     const candidates = platform === 'darwin'
@@ -243,14 +243,14 @@ export function resolveCodexExecutable(env = process.env, platform = process.pla
     return candidates.find(candidate => existsSync(candidate));
 }
 function cursorDetected() {
-    return Boolean(resolveExecutable('cursor') ||
-        resolveExecutable('cursor-agent') ||
+    return Boolean(resolveCommandDetails('cursor', { env: process.env }).path ||
+        resolveCommandDetails('cursor-agent', { env: process.env }).path ||
         existsSync(join(homedir(), '.cursor')) ||
         (process.platform === 'darwin' && existsSync('/Applications/Cursor.app')) ||
         (process.platform === 'win32' && existsSync(join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'Programs', 'cursor', 'Cursor.exe'))));
 }
 function vsCodeDetected() {
-    return Boolean(resolveExecutable('code') ||
+    return Boolean(resolveCommandDetails('code', { env: process.env }).path ||
         (process.platform === 'darwin' && existsSync('/Applications/Visual Studio Code.app')) ||
         (process.platform === 'win32' && existsSync(join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'Programs', 'Microsoft VS Code', 'Code.exe'))));
 }

package/dist/agent/service.js

@@ -7,7 +7,7 @@ import { connectActiveAlarms } from '../alarms/active-session.js';
 import { connectRadioSession, ensureRadioSession } from './session.js';
 import { launchHeadlessHost, launchRadioTui } from './launcher.js';
 import { PlayerController } from '../player/player-controller.js';
-import { detectPlaybackBackends } from '../player/backend-install.js';
+import { airPlayMacOSOnlyMessage, detectPlaybackBackends, isAirPlayPlatformSupported } from '../player/backend-install.js';
 import { AgentAlarmService } from './alarm-service.js';
 import { appVersion } from '../version.js';
 import { checkForUpdate, updateCommandForInstall } from '../update-check.js';
@@ -317,8 +317,8 @@ export class AgentRadioService {
             throw new Error('Agent control is disabled. Run radiocli mcp enable or enable it in Settings.');
     }
     assertAirPlayPlatform() {
-        if (process.platform !== 'darwin')
-            throw new Error('AirPlay control is available only on macOS.');
+        if (!isAirPlayPlatformSupported())
+            throw new Error(airPlayMacOSOnlyMessage);
     }
 }
 function opaqueStationId(station) { return `${station.provider}:${station.id}`; }