@ciphore/radiocli 0.2.4 → 0.2.5

package/dist/agent/service.js

@@ -1,13 +1,17 @@
 import { randomInt } from 'node:crypto';
 import { defaultAgentControlSettings, themeNames, receiverStyleNames } from '../types.js';
+import { LibraryRepository } from '../storage/repository.js';
 import { JsonLibraryStore, stationKey } from '../storage/store.js';
+import { parseRadioCommand } from './command-schema.js';
+import { matchesStationId } from '../storage/station-identity.js';
 import { ProviderManager } from '../providers/provider-manager.js';
 import { computeListeningStats } from '../activity/stats.js';
 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 { airPlayMacOSOnlyMessage, detectPlaybackBackends, isAirPlayPlatformSupported } from '../player/backend-install.js';
+import { airPlayPolicy } from '../player/airplay-policy.js';
+import { detectPlaybackBackends } from '../player/backend-install.js';
 import { AgentAlarmService } from './alarm-service.js';
 import { appVersion } from '../version.js';
 import { checkForUpdate, updateCommandForInstall } from '../update-check.js';
@@ -15,22 +19,29 @@ export class AgentRadioService {
     runtime;
     store;
     providers;
+    source;
     stationCache = new Map();
     alarms;
-    constructor(runtime, store = new JsonLibraryStore(), providers = new ProviderManager()) {
+    constructor(runtime, store = new JsonLibraryStore(), providers = new ProviderManager(), 
+    // Local shell commands do not enable or register agent/MCP integrations.
+    source = 'agent') {
         this.runtime = runtime;
         this.store = store;
         this.providers = providers;
+        this.source = source;
         this.alarms = new AgentAlarmService(this.store, id => this.resolveStationId(id), undefined, status => this.handoffAlarm(status));
     }
-    settings() { return this.store.snapshot().settings; }
+    async refresh() { if (this.store instanceof LibraryRepository)
+        await this.store.readFresh(); }
+    settings() { return this.store.settings(); }
+    connect() { return connectRadioSession(undefined, { source: this.source }); }
     appearance() {
         this.assertEnabled();
         return { themes: themeNames, receiverStyles: receiverStyleNames, current: this.settings() };
     }
     async status() {
         this.assertEnabled();
-        const client = await connectRadioSession();
+        const client = await this.connect();
         const state = this.store.snapshot();
         return {
             connected: Boolean(client),
@@ -106,21 +117,27 @@ export class AgentRadioService {
             : queue[input.random ? randomInt(queue.length) : Math.max(0, input.index ?? 0)];
         if (!station)
             throw new Error(input.stationId ? `Unknown station ID: ${input.stationId}. Search or browse first.` : 'No station is available for that request.');
-        const ordered = [station, ...queue.filter(item => stationKey(item) !== stationKey(station))];
+        return this.playStation(station, queue, input);
+    }
+    async playStation(station, queue = [station], options = {}) {
+        this.assertEnabled();
+        if ((await connectActiveAlarms()).length > 0)
+            throw new Error('An alarm is currently active. Dismiss or keep the alarm from its ringing controls before starting interactive playback.');
+        const ordered = queue.some(item => stationKey(item) === stationKey(station)) ? queue : [station, ...queue];
         return this.send({
             type: 'play',
             station,
             queue: ordered,
-            openNowPlaying: this.agentSettings().focusNowPlaying,
-            ifPlaying: input.ifPlaying ?? 'replace'
-        }, input.openUi);
+            openNowPlaying: this.source === 'agent' && this.agentSettings().focusNowPlaying,
+            ifPlaying: options.ifPlaying ?? 'replace'
+        }, options.openUi);
     }
     async control(command, openUi) {
         this.assertEnabled();
-        const client = await connectRadioSession();
+        const client = await this.connect();
         if (!client && command.type === 'set-volume') {
             const volume = Math.min(100, Math.max(0, command.volume));
-            this.store.updateSettings({ volume });
+            await this.store.updateSettings({ volume });
             return idleResult(`Saved volume ${volume}; no playback session is active.`);
         }
         if (!client && ['stop', 'pause', 'resume', 'next', 'previous', 'set-volume', 'set-muted'].includes(command.type)) {
@@ -132,17 +149,24 @@ export class AgentRadioService {
     }
     async setFavorite(favorite, stationId) {
         this.assertEnabled();
-        const client = await connectRadioSession();
+        const client = await this.connect();
         if (!stationId && client)
             return client.call({ type: 'set-favorite', favorite });
         const station = stationId ? await this.findStation(stationId, this.savedStations()) : undefined;
         if (!station)
             throw new Error('No station was supplied and no active station is available.');
+        return this.favoriteStation(station, favorite);
+    }
+    async favoriteStation(station, favorite) {
+        this.assertEnabled();
+        const client = await this.connect();
+        if (client)
+            return client.call({ type: 'set-favorite', favorite, station });
         const isFavorite = this.store.isFavorite(station);
         if (isFavorite !== favorite)
-            this.store.toggleFavorite(station);
+            await this.store.toggleFavorite(station);
         if (favorite && !isFavorite && this.store.snapshot().settings.shareDirectoryVotes)
-            void this.providers.vote(station);
+            void this.providers.vote(station).catch(() => undefined);
         return { ok: true, message: `${favorite ? 'Favorited' : 'Removed favorite'}: ${station.name}`, station };
     }
     async updateAppearance(input) {
@@ -151,10 +175,10 @@ export class AgentRadioService {
             throw new Error(`Unknown theme: ${input.theme}`);
         if (input.receiverStyle && !receiverStyleNames.includes(input.receiverStyle))
             throw new Error(`Unknown receiver style: ${input.receiverStyle}`);
-        const client = await connectRadioSession();
+        const client = await this.connect();
         if (client)
             return client.call({ type: 'update-settings', settings: input });
-        return this.store.updateSettings(input).settings;
+        return (await this.store.updateSettings(input)).settings;
     }
     async runCompletionPreset() {
         const preset = this.agentSettings().completionPreset;
@@ -162,7 +186,7 @@ export class AgentRadioService {
             return this.play({ source: preset.source, countryCode: preset.countryCode, random: preset.source !== 'recent', openUi: preset.openUi, ifPlaying: preset.ifPlaying });
         return this.control({ type: preset.action }, preset.openUi);
     }
-    configureCompletionPreset(input) {
+    async configureCompletionPreset(input) {
         this.assertEnabled();
         const agentControl = this.agentSettings();
         const completionPreset = { ...agentControl.completionPreset, ...input };
@@ -170,15 +194,15 @@ export class AgentRadioService {
             throw new Error('A two-letter countryCode is required for the country preset source.');
         if (completionPreset.countryCode)
             completionPreset.countryCode = completionPreset.countryCode.toUpperCase();
-        return this.store.updateSettings({ agentControl: { ...agentControl, completionPreset } }).settings.agentControl;
+        return (await this.store.updateSettings({ agentControl: { ...agentControl, completionPreset } })).settings.agentControl;
     }
     async updateAgentPreferences(input) {
         this.assertEnabled();
         const agentControl = { ...this.agentSettings(), ...input };
-        const client = await connectRadioSession();
+        const client = await this.connect();
         if (client)
             return client.call({ type: 'update-settings', settings: { agentControl } });
-        return this.store.updateSettings({ agentControl }).settings.agentControl;
+        return (await this.store.updateSettings({ agentControl })).settings.agentControl;
     }
     alarmList() { this.assertEnabled(); return this.alarms.list(); }
     alarmStatus() { this.assertEnabled(); return this.alarms.status(); }
@@ -191,13 +215,17 @@ export class AgentRadioService {
     async listAirPlayDevices() {
         this.assertEnabled();
         this.assertAirPlayPlatform();
-        const client = await connectRadioSession();
-        if (client)
-            return (await client.call({ type: 'airplay-list' })).data ?? [];
+        const client = await this.connect();
+        if (client) {
+            const result = await client.call({ type: 'airplay-list' });
+            if (!result.ok)
+                throw new Error(result.message);
+            return result.data ?? [];
+        }
         const player = new PlayerController(() => this.store.snapshot().settings);
         const backends = player.refreshDetectedBackends();
         if (!backends.includes('airplay'))
-            throw new Error('AirPlay is unavailable on this Mac. Run radiocli doctor to check ffmpeg, dns-sd, and the sender package.');
+            throw new Error('AirPlay is unavailable on this device. Run radiocli doctor to check FFmpeg, discovery, and the optional sender.');
         return player.refreshAirPlayDevices();
     }
     async selectAirPlayDevice(deviceId, openUi) {
@@ -209,17 +237,17 @@ export class AgentRadioService {
             throw new Error('Unknown AirPlay receiver ID. Refresh the receiver list and use an exact returned ID.');
         if (device.local)
             return this.useLocalOutput(openUi);
-        this.store.updateSettings({ preferredAirPlayDevice: device.id });
+        await this.store.updateSettings({ preferredAirPlayDevice: device.id });
         return this.send({ type: 'airplay-select', deviceId: device.id }, openUi);
     }
     async useLocalOutput(openUi) {
         this.assertEnabled();
-        const client = await connectRadioSession();
+        const client = await this.connect();
         if (!client) {
             const backend = preferredLocalBackend(detectPlaybackBackends());
             if (!backend)
                 throw new Error('No local playback backend is available. Run radiocli setup to install mpv.');
-            this.store.updateSettings({ preferredBackend: backend });
+            await this.store.updateSettings({ preferredBackend: backend });
             return idleResult(`Audio output set to this device (${backend}).`);
         }
         return this.send({ type: 'airplay-local' }, openUi);
@@ -227,7 +255,7 @@ export class AgentRadioService {
     async submitAirPlayPasscode(code) {
         this.assertEnabled();
         this.assertAirPlayPlatform();
-        const client = await connectRadioSession();
+        const client = await this.connect();
         if (!client)
             throw new Error('No active AirPlay session is waiting for a receiver code.');
         return client.call({ type: 'airplay-passcode', code });
@@ -252,19 +280,18 @@ export class AgentRadioService {
     async send(command, openUi, allowActiveAlarm = false) {
         const settings = this.settings();
         const agentControl = settings.agentControl ?? defaultAgentControlSettings;
-        if (!agentControl.enabled)
-            throw new Error('Agent control is disabled. Run radiocli mcp enable or enable it in Settings.');
-        let client = await connectRadioSession();
+        this.assertEnabled();
+        let client = await this.connect();
         if (!client) {
             if (!allowActiveAlarm && (await connectActiveAlarms()).length > 0)
                 throw new Error('An alarm is currently active. Dismiss or keep the alarm from its ringing controls before starting interactive playback.');
-            const shouldOpen = openUi ?? agentControl.openUiOnPlay;
+            const shouldOpen = openUi ?? (this.source === 'agent' && agentControl.openUiOnPlay);
             client = await ensureRadioSession(async () => {
                 if (shouldOpen)
                     await launchRadioTui(this.runtime.nodePath, this.runtime.cliPath, encodeAgentCommand({ type: 'status' }));
                 else
                     await launchHeadlessHost(this.runtime.nodePath, this.runtime.cliPath);
-            });
+            }, undefined, { source: this.source });
         }
         return client.call(command);
     }
@@ -290,8 +317,10 @@ export class AgentRadioService {
     }
     async findStation(id, candidates) {
         const normalized = id.trim();
-        const local = this.stationCache.get(normalized)
-            ?? candidates.find(station => opaqueStationId(station) === normalized || station.id === normalized);
+        const matches = new Map(candidates.filter(station => matchesStationId(station, normalized)).map(station => [stationKey(station), station]));
+        if (matches.size > 1)
+            throw new Error('This legacy station ID is ambiguous. Search or browse again and use the current station ID.');
+        const local = this.stationCache.get(normalized) ?? [...matches.values()][0];
         if (local)
             return local;
         const separator = normalized.indexOf(':');
@@ -305,20 +334,26 @@ export class AgentRadioService {
         return station ?? undefined;
     }
     remember(stations) {
-        for (const station of stations)
-            this.stationCache.set(opaqueStationId(station), station);
+        for (const station of stations) {
+            const key = opaqueStationId(station);
+            this.stationCache.delete(key);
+            this.stationCache.set(key, station);
+        }
+        while (this.stationCache.size > 1024)
+            this.stationCache.delete(this.stationCache.keys().next().value);
         return stations;
     }
     agentSettings() {
         return this.settings().agentControl ?? defaultAgentControlSettings;
     }
     assertEnabled() {
-        if (!this.agentSettings().enabled)
+        if (this.source === 'agent' && !this.agentSettings().enabled)
             throw new Error('Agent control is disabled. Run radiocli mcp enable or enable it in Settings.');
     }
     assertAirPlayPlatform() {
-        if (!isAirPlayPlatformSupported())
-            throw new Error(airPlayMacOSOnlyMessage);
+        const policy = airPlayPolicy(this.settings());
+        if (!policy.enabled)
+            throw new Error(policy.message);
     }
 }
 function opaqueStationId(station) { return `${station.provider}:${station.id}`; }
@@ -337,7 +372,7 @@ export function stationForAgent(station) {
     };
 }
 function encodeAgentCommand(command) { return Buffer.from(JSON.stringify(command)).toString('base64url'); }
-export function decodeAgentCommand(value) { return JSON.parse(Buffer.from(value, 'base64url').toString('utf8')); }
+export function decodeAgentCommand(value) { return parseRadioCommand(JSON.parse(Buffer.from(value, 'base64url').toString('utf8'))); }
 function clampLimit(value, max = 30) { return Math.min(max, Math.max(1, Math.round(value))); }
 function idleResult(message) {
     return { ok: true, message, status: { owner: 'headless', station: null, queue: [], playback: { backend: 'none', state: 'idle', volume: 70, muted: false, ready: false } } };

package/dist/agent/session.js

@@ -1,14 +1,123 @@
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { parseRadioCommand, parseRadioRequest } from './command-schema.js';
 import { chmodSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { createServer, request } from 'node:http';
 import { platformPaths } from '../platform/paths.js';
 import { dirname, join } from 'node:path';
 import { isLoopbackHost, listenLoopback } from '../platform/loopback.js';
-export async function startRadioSession(handle, filePath = radioSessionPath()) {
+/** The wire protocol accepts appearance/MCP preferences, never experimental-output consent. */
+export function allowedRadioSessionSettings(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        && Object.keys(value).every(key => ['theme', 'receiverStyle', 'agentControl'].includes(key));
+}
+/** Resolve desktop intent at the owner queue boundary, after earlier commands
+ * have completed. In particular, Play/PlayPause must not use a stale snapshot. */
+export function resolveDesktopTransport(action, status) {
+    const { playback, station, queue } = status;
+    const stopped = ['idle', 'stopped'].includes(playback.state);
+    if (action === 'play') {
+        if (playback.state === 'paused')
+            return { type: 'resume' };
+        return stopped && station ? { type: 'resume', restartStopped: true } : null;
+    }
+    if (action === 'pause')
+        return playback.state === 'playing' && playback.backend === 'mpv' ? { type: 'pause' } : null;
+    if (action === 'toggle') {
+        if (!station || playback.backend !== 'mpv')
+            throw new Error('This output cannot toggle pause.');
+        return playback.state === 'playing' ? { type: 'pause' } : playback.state === 'paused' ? { type: 'resume' } : stopped ? { type: 'resume', restartStopped: true } : null;
+    }
+    // Even an idle backend can have an unresolved tune or delayed retry to cancel.
+    if (action === 'stop')
+        return { type: 'stop', retainSelection: true };
+    return station && queue.length > 1 && (stopped || playback.state === 'playing' || playback.state === 'paused')
+        ? { type: action, preservePause: true, preserveStop: true } : null;
+}
+/** Agent and desktop controls must use the same owner queue. A failed command
+ * cannot strand the queue or allow a later command to overtake an active one. */
+export function serializeRadioCommands(handle, options = {}) {
+    let pending = Promise.resolve();
+    let tuning = Promise.resolve();
+    let admitted = 0;
+    const tunes = new Set();
+    return (input, permitted) => {
+        let command;
+        try {
+            command = parseRadioCommand(input);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const priority = command.type === 'stop' || command.type === 'alarm-preempt' || command.type === 'tui-cancel'
+            || command.type === 'desktop-transport' && command.action === 'stop';
+        const checkPermission = async () => { if (permitted && !await permitted())
+            throw new Error('Desktop media controls are suspended.'); };
+        if (options.responsive && command.type === 'status')
+            return Promise.resolve().then(async () => { await checkPermission(); return handle(command); });
+        if (options.responsive && priority) {
+            const interrupted = [...tunes];
+            const priorPending = pending;
+            const priorTuning = tuning;
+            const work = checkPermission().then(() => {
+                for (const controller of interrupted)
+                    controller.abort(new DOMException('Tuning canceled by Stop or alarm.', 'AbortError'));
+                return handle(command);
+            });
+            pending = work.then(() => undefined, () => priorPending);
+            tuning = work.then(() => undefined, () => priorTuning);
+            return work;
+        }
+        if (admitted >= (options.limit ?? 128))
+            return Promise.reject(new Error('RadioCLI control queue is busy. Status and Stop remain available.'));
+        admitted++;
+        const replacesTune = ['play', 'airplay-select', 'airplay-local'].includes(command.type);
+        const transport = replacesTune || ['pause', 'resume', 'next', 'previous', 'desktop-transport'].includes(command.type);
+        const long = options.responsive && (['play', 'resume', 'next', 'previous', 'airplay-select', 'airplay-local'].includes(command.type) || command.type === 'desktop-transport' && ['play', 'next', 'previous'].includes(command.action));
+        const replaced = options.responsive && replacesTune ? [...tunes] : [];
+        const priorTuning = tuning;
+        let executing = false;
+        const controller = new AbortController();
+        if (options.responsive && transport)
+            tunes.add(controller);
+        const fence = options.responsive && transport && !replacesTune ? Promise.all([pending, tuning]).then(() => undefined) : pending;
+        const start = abortableControl(fence, controller.signal).then(async () => {
+            await checkPermission();
+            controller.signal.throwIfAborted();
+            for (const earlier of replaced)
+                earlier.abort(new DOMException('Tuning canceled by a replacement.', 'AbortError'));
+            executing = true;
+            const result = handle(command, controller.signal);
+            return { result };
+        });
+        const result = abortableControl(start.then(({ result }) => result), controller.signal).finally(() => { admitted--; tunes.delete(controller); });
+        // Tune completion is separate from command admission. A later tune replaces
+        // an active one, while Stop and status bypass both queues entirely.
+        pending = (long ? start : result).then(() => undefined, () => undefined);
+        if (long)
+            tuning = result.then(() => undefined, () => executing ? undefined : priorTuning);
+        // Cancellation is an expected control outcome. Keep the rejection available
+        // to the caller without leaking it while another transport action is awaited.
+        void result.catch(() => undefined);
+        return result;
+    };
+}
+function abortableControl(work, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const abort = () => { signal.removeEventListener('abort', abort); reject(signal.reason); };
+        signal.addEventListener('abort', abort, { once: true });
+        void work.then(value => { signal.removeEventListener('abort', abort); resolve(value); }, error => { signal.removeEventListener('abort', abort); reject(error); });
+    });
+}
+/** Use queue: 'owner' only when handle submits directly to the owner's shared
+ * serialized dispatcher. Other callers retain the session's own FIFO. */
+export async function startRadioSession(handle, filePath = radioSessionPath(), options = {}) {
     const ownerPath = `${filePath}.owner`;
     acquireOwner(ownerPath);
     const token = randomBytes(32).toString('hex');
     let serial = Promise.resolve();
+    const requests = new Map();
     const server = createServer((req, res) => {
         res.setHeader('content-type', 'application/json');
         if (req.headers.authorization !== `Bearer ${token}`) {
@@ -21,11 +130,40 @@ export async function startRadioSession(handle, filePath = radioSessionPath()) {
             res.end('{}');
             return;
         }
-        const work = serial.then(async () => {
+        const accept = async () => {
             const body = await readBody(req);
-            return handle(JSON.parse(body));
-        });
-        serial = work.then(() => undefined, () => undefined);
+            const { command, requestId } = parseRadioRequest(JSON.parse(body));
+            const execute = () => handle(command, req.headers['x-radiocli-client'] === 'cli' ? 'cli' : 'agent');
+            if (!requestId || command.type === 'status')
+                return execute();
+            const fingerprint = createHash('sha256').update(JSON.stringify(command)).digest('hex');
+            const existing = requests.get(requestId);
+            if (existing) {
+                if (existing.fingerprint !== fingerprint)
+                    throw new Error('This request ID was already used for a different command.');
+                return existing.result;
+            }
+            for (const [id, entry] of requests)
+                if (entry.settledAt && (Date.now() - entry.settledAt > 300_000 || requests.size >= 256))
+                    requests.delete(id);
+            if (requests.size >= 256) {
+                // Stop/preemption are intrinsically idempotent and must remain available
+                // even when ordinary requests occupy the entire bounded outcome cache.
+                if (command.type === 'stop' || command.type === 'alarm-preempt' || command.type === 'desktop-transport' && command.action === 'stop')
+                    return execute();
+                throw new Error('RadioCLI has too many active control requests.');
+            }
+            const entry = { fingerprint, result: Promise.resolve().then(execute) };
+            requests.set(requestId, entry);
+            void entry.result.then(() => { entry.settledAt = Date.now(); }, () => { entry.settledAt = Date.now(); });
+            return entry.result;
+        };
+        // An owner shared with desktop controls already serializes accepted work.
+        // Submit each authenticated, complete request directly to that queue so a
+        // later desktop action cannot overtake an earlier HTTP request here.
+        const work = options.queue === 'owner' ? accept() : serial.then(accept);
+        if (options.queue !== 'owner')
+            serial = work.then(() => undefined, () => undefined);
         void work.then(result => res.end(JSON.stringify(result))).catch(error => {
             res.statusCode = 400;
             res.end(JSON.stringify({ error: error instanceof Error ? error.message : 'Radio control failed.' }));
@@ -35,6 +173,7 @@ export async function startRadioSession(handle, filePath = radioSessionPath()) {
         const address = await listenLoopback(server);
         const discovery = {
             version: 1,
+            protocol: 2,
             host: address.host,
             port: address.port,
             token,
@@ -56,7 +195,8 @@ export async function startRadioSession(handle, filePath = radioSessionPath()) {
         throw error;
     }
 }
-export async function connectRadioSession(filePath = radioSessionPath()) {
+export async function connectRadioSession(filePath = radioSessionPath(), options = {}) {
+    options.signal?.throwIfAborted();
     if (!existsSync(filePath))
         return null;
     let discovery;
@@ -70,41 +210,59 @@ export async function connectRadioSession(filePath = radioSessionPath()) {
         rmSync(filePath, { force: true });
         return null;
     }
-    const call = async (command) => {
-        const payload = JSON.stringify(command);
+    const call = async (command, requestId = randomUUID()) => {
+        const validated = parseRadioCommand(command);
+        const payload = JSON.stringify(discovery.protocol === 2 ? { version: 2, requestId, command: validated } : validated);
         return new Promise((resolve, reject) => {
             const req = request({
                 host: discovery.host,
                 // Local control tokens must never be forwarded by an environment proxy.
                 agent: false,
+                signal: options.signal,
                 port: discovery.port,
                 path: '/command',
                 method: 'POST',
                 headers: {
                     authorization: `Bearer ${discovery.token}`,
+                    'x-radiocli-client': options.source ?? 'agent',
                     'content-type': 'application/json',
                     'content-length': Buffer.byteLength(payload)
                 }
             }, res => {
                 let text = '';
-                res.on('data', value => { text += String(value); });
+                res.setEncoding('utf8');
+                res.on('data', value => { text += String(value); if (Buffer.byteLength(text) > 8 * 1024 * 1024)
+                    res.destroy(new Error('RadioCLI response too large.')); });
+                res.once('error', reject);
                 res.on('end', () => {
-                    if (res.statusCode && res.statusCode < 300)
-                        resolve(JSON.parse(text));
-                    else
-                        reject(new Error(parseError(text)));
+                    try {
+                        if (res.statusCode && res.statusCode < 300) {
+                            const parsed = JSON.parse(text);
+                            if (typeof parsed.ok !== 'boolean' || typeof parsed.message !== 'string' || !parsed.status?.playback || !Array.isArray(parsed.status.queue))
+                                throw new Error('Invalid RadioCLI control response.');
+                            resolve(parsed);
+                        }
+                        else
+                            reject(new Error(parseError(text)));
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
                 });
             });
             req.once('error', reject);
-            req.setTimeout(15_000, () => req.destroy(new Error('RadioCLI control request timed out.')));
+            const timeout = command.type === 'status' ? 5000 : ['stop', 'alarm-preempt'].includes(command.type) ? 15_000 : 120_000;
+            req.setTimeout(timeout, () => req.destroy(new Error(`RadioCLI control request timed out. Request ID: ${requestId}. Retry with the same ID to retrieve its outcome.`)));
             req.end(payload);
         });
     };
     try {
         await call({ type: 'status' });
+        options.signal?.throwIfAborted();
         return { call, status: async () => (await call({ type: 'status' })).status };
     }
     catch {
+        options.signal?.throwIfAborted();
         // A slow command does not prove that a playback host is dead. Retain both
         // ownership records while its PID is alive so a second host cannot start.
         if (!processAlive(discovery.pid)) {
@@ -114,8 +272,10 @@ export async function connectRadioSession(filePath = radioSessionPath()) {
         return null;
     }
 }
-export async function ensureRadioSession(start, timeoutMs = 15_000) {
-    const existing = await connectRadioSession();
+export async function ensureRadioSession(start, timeoutMs = 15_000, options = {}) {
+    options.signal?.throwIfAborted();
+    const existing = await connectRadioSession(undefined, options);
+    options.signal?.throwIfAborted();
     if (existing)
         return existing;
     const lockPath = `${radioSessionPath()}.launch`;
@@ -123,16 +283,18 @@ export async function ensureRadioSession(start, timeoutMs = 15_000) {
     try {
         acquireOwner(lockPath);
         ownsLaunch = true;
-        const appeared = await connectRadioSession();
+        const appeared = await connectRadioSession(undefined, options);
+        options.signal?.throwIfAborted();
         if (appeared)
             return appeared;
         await start();
-        return await waitForSession(timeoutMs);
+        options.signal?.throwIfAborted();
+        return await waitForSession(timeoutMs, options);
     }
     catch (error) {
         if (ownsLaunch || !(error instanceof Error) || !error.message.includes('already active'))
             throw error;
-        return waitForSession(timeoutMs);
+        return waitForSession(timeoutMs, options);
     }
     finally {
         if (ownsLaunch)
@@ -142,16 +304,43 @@ export async function ensureRadioSession(start, timeoutMs = 15_000) {
 function radioSessionPath() {
     return join(runtimeDirectory(), 'agent-session.json');
 }
-async function waitForSession(timeoutMs) {
+/** Optional terminal recovery may fall back to inline playback only when no
+ * live or unknown owner could already be using this library's audio session. */
+export function radioSessionMayBeActive() {
+    for (const path of [`${radioSessionPath()}.owner`, `${radioSessionPath()}.launch`, radioSessionPath()]) {
+        try {
+            const text = readFileSync(path, 'utf8');
+            const pid = path.endsWith('.json') ? JSON.parse(text).pid : Number(text.trim());
+            if (!Number.isSafeInteger(pid) || pid <= 0 || processAlive(pid))
+                return true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                return true;
+        }
+    }
+    return false;
+}
+async function waitForSession(timeoutMs, options) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        const client = await connectRadioSession();
+        options.signal?.throwIfAborted();
+        const client = await connectRadioSession(undefined, options);
+        options.signal?.throwIfAborted();
         if (client)
             return client;
-        await new Promise(resolve => setTimeout(resolve, 100));
+        await controlPollDelay(options.signal);
     }
     throw new Error('RadioCLI was launched but its control session did not become ready.');
 }
+function controlPollDelay(signal) {
+    signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const abort = () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); reject(signal?.reason); };
+        const timer = setTimeout(() => { signal?.removeEventListener('abort', abort); resolve(); }, 100);
+        signal?.addEventListener('abort', abort, { once: true });
+    });
+}
 function runtimeDirectory() {
     return platformPaths().runtime;
 }
@@ -212,9 +401,10 @@ function processAlive(pid) {
 function readBody(req) {
     return new Promise((resolve, reject) => {
         let body = '';
+        req.setEncoding('utf8');
         req.on('data', value => {
             body += String(value);
-            if (body.length > 1_000_000)
+            if (Buffer.byteLength(body) > 4 * 1024 * 1024)
                 req.destroy(new Error('Request too large.'));
         });
         req.on('end', () => resolve(body));