@ciphore/radiocli 0.2.1 → 0.2.3

package/dist/alarms/scheduler.js

@@ -0,0 +1,250 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { nextOccurrenceForAlarm } from './schedule.js';
+import { AlarmRuntimeHealthStore } from './runtime-health.js';
+import { AlarmGuardService } from './guard.js';
+import { AlarmPowerGuardStore } from './power-guard-store.js';
+import { detectAlarmTerminal } from './terminal-launcher.js';
+export class SchedulerService {
+    adapter;
+    now;
+    health;
+    guard;
+    constructor(adapter, now = () => new Date(), health = new AlarmRuntimeHealthStore(), guard) {
+        this.adapter = adapter;
+        this.now = now;
+        this.health = health;
+        this.guard = guard;
+    }
+    async sync(alarm) {
+        const occurrence = nextOccurrenceForAlarm(alarm, this.now());
+        try {
+            if (!occurrence) {
+                const native = await settledOperation(() => this.adapter.remove(alarm.id));
+                const guard = await settledOperation(() => this.reconcileGuard(alarm));
+                if (native.error)
+                    this.health.record({ alarmId: alarm.id, component: 'scheduler', healthy: false, message: `Native job removal failed: ${native.error}` });
+                else
+                    this.health.record({ alarmId: alarm.id, component: 'scheduler', healthy: true, message: 'No enabled future occurrence; native job removed.' });
+                const failures = [native.error, guard.error].filter((value) => Boolean(value));
+                if (failures.length)
+                    throw new Error(failures.join(' '));
+                return null;
+            }
+            const capability = this.adapter.capabilities();
+            if (!capability.supported)
+                throw new Error(capability.message);
+            await this.adapter.install(alarm, occurrence);
+            this.health.record({ alarmId: alarm.id, component: 'scheduler', healthy: true, message: 'Native job registered.', nextOccurrence: occurrence.toISOString() });
+            await this.reconcileGuard(alarm);
+            return occurrence;
+        }
+        catch (error) {
+            if (!(error instanceof GuardReconcileError))
+                this.health.record({ alarmId: alarm.id, component: 'scheduler', healthy: false, message: errorMessage(error), ...(occurrence ? { nextOccurrence: occurrence.toISOString() } : {}) });
+            throw error;
+        }
+    }
+    async syncAll(alarms) {
+        return mapConcurrent(alarms, 4, async (alarm) => {
+            try {
+                return { id: alarm.id, occurrence: await this.sync(alarm) };
+            }
+            catch (error) {
+                return { id: alarm.id, occurrence: null, error: errorMessage(error) };
+            }
+        });
+    }
+    doctor() { return this.adapter.capabilities(); }
+    async syncClaimed(alarm, currentOccurrence) { const occurrence = nextOccurrenceForAlarm(alarm, this.now()); try {
+        if (!occurrence) {
+            if (this.adapter.removeFromRunner)
+                await this.adapter.removeFromRunner(alarm.id, currentOccurrence);
+            else
+                await this.adapter.remove(alarm.id);
+            await this.ensureGuardAbsent(alarm.id);
+            this.health.record({ alarmId: alarm.id, component: 'scheduler', healthy: true, message: 'Claimed occurrence has no enabled future native job.' });
+            return null;
+        }
+        const capability = this.adapter.capabilities();
+        if (!capability.supported)
+            throw new Error(capability.message);
+        if (this.adapter.installFromRunner)
+            await this.adapter.installFromRunner(alarm, occurrence, currentOccurrence);
+        else
+            await this.adapter.install(alarm, occurrence);
+        this.health.record({ alarmId: alarm.id, component: 'scheduler', healthy: true, message: 'Next native occurrence registered by active runner.', nextOccurrence: occurrence.toISOString() });
+        await this.reconcileGuard(alarm);
+        return occurrence;
+    }
+    catch (error) {
+        this.health.record({ alarmId: alarm.id, component: 'scheduler', healthy: false, message: errorMessage(error), ...(occurrence ? { nextOccurrence: occurrence.toISOString() } : {}) });
+        throw error;
+    } }
+    async completeOccurrence(alarmId, occurrence) { await this.adapter.completeOccurrence?.(alarmId, occurrence); }
+    async remove(alarmId) { await this.ensureGuardAbsent(alarmId); try {
+        await this.adapter.remove(alarmId);
+    }
+    catch (error) {
+        this.health.record({ alarmId, component: 'scheduler', healthy: false, message: `Native job removal failed; the alarm definition was retained: ${errorMessage(error)}` });
+        throw error;
+    } this.health.remove(alarmId); }
+    async statusAll(alarms) { return mapConcurrent(alarms, 4, async (alarm) => { const occurrence = nextOccurrenceForAlarm(alarm, this.now()); return { alarmId: alarm.id, nextOccurrence: occurrence?.toISOString() ?? null, native: occurrence ? await this.adapter.status(alarm.id) : { installed: false, healthy: true, message: 'No enabled future occurrence; no native job is expected.' }, health: this.health.get(alarm.id) }; }); }
+    async runtimeStatus(alarms = []) { return { capabilities: this.doctor(), entries: this.health.list(), alarms: await this.statusAll(alarms) }; }
+    async reconcileGuard(alarm) { if (!this.guard)
+        return; try {
+        const requested = alarm.enabled && alarm.reliability.keepAwakeUntilAlarm;
+        if (requested)
+            await this.guard.start(alarm);
+        else
+            await this.ensureGuardAbsent(alarm.id);
+        this.health.record({ alarmId: alarm.id, component: 'power', healthy: true, active: requested, message: requested ? 'Alarm Guard reconciled.' : 'Alarm Guard verified absent.' });
+    }
+    catch (error) {
+        const message = `Alarm Guard reconciliation failed: ${errorMessage(error)}`;
+        this.health.record({ alarmId: alarm.id, component: 'power', healthy: false, active: true, message });
+        throw new GuardReconcileError(message);
+    } }
+    async ensureGuardAbsent(alarmId) { if (!this.guard)
+        return; const stopped = await this.guard.stop(alarmId); if (stopped)
+        return; const status = await this.guard.status?.(); if (status && !status.guards.some(item => item.alarmId === alarmId))
+        return; const message = 'Alarm Guard teardown could not be verified; the alarm definition was retained for repair.'; this.health.record({ alarmId, component: 'power', healthy: false, active: true, message }); throw new GuardReconcileError(message); }
+}
+class GuardReconcileError extends Error {
+}
+async function settledOperation(work) { try {
+    await work();
+    return {};
+}
+catch (error) {
+    return { error: errorMessage(error) };
+} }
+export function createSchedulerService(deps = {}) {
+    return new SchedulerService(createSchedulerAdapter(deps), () => new Date(), new AlarmRuntimeHealthStore(), new AlarmGuardService(new AlarmPowerGuardStore()));
+}
+export function createSchedulerAdapter(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const home = deps.home ?? homedir();
+    const nodePath = deps.nodePath ?? process.execPath;
+    const cliPath = deps.cliPath ?? join(dirname(fileURLToPath(import.meta.url)), '..', 'cli.js');
+    const env = deps.env ?? process.env;
+    const write = deps.writeFile ?? ((path, contents) => { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, contents, { encoding: 'utf8', mode: 0o600 }); });
+    const removeFile = deps.removeFile ?? (path => rmSync(path, { force: true }));
+    const run = deps.run ?? runCommand;
+    const commandExists = deps.commandExists ?? (command => existsSync(command) || Boolean(process.env.PATH?.split(platform === 'win32' ? ';' : ':').some(path => existsSync(join(path, command)))));
+    const common = { home, nodePath, cliPath, env, terminal: detectAlarmTerminal(platform, env), write, removeFile, run };
+    if (platform === 'darwin')
+        return launchdAdapter(common);
+    if (platform === 'win32')
+        return windowsAdapter(common);
+    if (platform === 'linux' && commandExists('systemctl'))
+        return systemdAdapter(common);
+    return unsupportedAdapter(platform === 'linux'
+        ? 'User scheduling requires systemd. This Linux session is unsupported; RadioCLI will not claim the alarm is registered.'
+        : `Alarm scheduling is not supported on ${platform}.`);
+}
+function runtimeEnvironment(common) {
+    const result = { RADIOCLI_ALARM_TERMINAL: common.terminal };
+    for (const key of ['RADIOCLI_HOME', 'DISPLAY', 'WAYLAND_DISPLAY', 'DBUS_SESSION_BUS_ADDRESS', 'XDG_RUNTIME_DIR']) {
+        const value = common.env[key];
+        if (value)
+            result[key] = value;
+    }
+    return result;
+}
+const jobName = (id) => `io.radiocli.alarm.${createHash('sha256').update(id).digest('hex').slice(0, 20)}`;
+const invocationArgs = (common, id, occurrence, internalCommand = 'internal-run') => [common.cliPath, 'alarm', internalCommand, id, occurrence.toISOString()];
+export function shouldRunLaunchdOccurrence(scheduledAt, now) { if (!/(?:Z|[+-]\d{2}:\d{2})$/.test(scheduledAt))
+    throw new Error('Launchd occurrence gate requires an absolute instant.'); const scheduled = new Date(scheduledAt); if (!Number.isFinite(scheduled.getTime()) || !Number.isFinite(now.getTime()))
+    throw new Error('Invalid launchd occurrence gate time.'); return now.getTime() >= scheduled.getTime(); }
+function launchdAdapter(common) {
+    const directory = join(common.home, 'Library', 'LaunchAgents');
+    const pathFor = (id) => join(directory, `${jobName(id)}.plist`);
+    const occurrenceLabel = (id, occurrence) => `${jobName(id)}.${createHash('sha256').update(occurrence.toISOString()).digest('hex').slice(0, 12)}`;
+    const occurrencePath = (id, occurrence) => join(directory, `${occurrenceLabel(id, occurrence)}.plist`);
+    const pathsFor = (id) => { const prefix = `${jobName(id)}.`; let extras = []; try {
+        extras = readdirSync(directory).filter(name => name.startsWith(prefix) && name.endsWith('.plist')).map(name => join(directory, name));
+    }
+    catch { } return [pathFor(id), ...extras]; };
+    const installJob = async (alarm, occurrence, label, path, replace) => { const local = localParts(occurrence); const entries = Object.entries(runtimeEnvironment(common)).map(([key, value]) => `<key>${xml(key)}</key><string>${xml(value)}</string>`).join(''); const envArgs = `<key>EnvironmentVariables</key><dict>${entries}</dict>`; const args = [common.nodePath, ...invocationArgs(common, alarm.id, occurrence, 'internal-launchd')].map(value => `<string>${xml(value)}</string>`).join(''); common.write(path, `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>${label}</string><key>ProgramArguments</key><array>${args}</array>${envArgs}<key>StartCalendarInterval</key><dict><key>Month</key><integer>${local.month}</integer><key>Day</key><integer>${local.day}</integer><key>Hour</key><integer>${local.hour}</integer><key>Minute</key><integer>${local.minute}</integer></dict><key>ProcessType</key><string>Interactive</string><key>StandardOutPath</key><string>/dev/null</string><key>StandardErrorPath</key><string>/dev/null</string><!-- launchd repeats this calendar pattern annually; the idempotent runner gates, removes, or reschedules it. --></dict></plist>\n`); if (replace)
+        await common.run('launchctl', ['bootout', `gui/${process.getuid?.() ?? ''}`, path]).catch(() => undefined); ensureSuccess(await common.run('launchctl', ['bootstrap', `gui/${process.getuid?.() ?? ''}`, path]), 'launchctl bootstrap'); };
+    return {
+        capabilities: () => ({ supported: true, exactWake: false, catchUpAfterWake: true, message: 'launchd runs after wake when possible; exact wake is unavailable. Resync after changing the host timezone.' }),
+        async install(alarm, occurrence) { await installJob(alarm, occurrence, jobName(alarm.id), pathFor(alarm.id), true); },
+        async installFromRunner(alarm, occurrence) { const label = occurrenceLabel(alarm.id, occurrence); const existing = await common.run('launchctl', ['print', `gui/${process.getuid?.() ?? ''}/${label}`]); if (existing.code === 0)
+            return; await installJob(alarm, occurrence, label, occurrencePath(alarm.id, occurrence), false); },
+        async removeFromRunner() { },
+        async completeOccurrence(id, occurrence) { const specific = occurrencePath(id, occurrence); const path = existsSync(specific) ? specific : pathFor(id); const label = path.split('/').at(-1).slice(0, -6); let failure; try {
+            const result = await common.run('launchctl', ['bootout', `gui/${process.getuid?.() ?? ''}`, path]);
+            if (result.code !== 0)
+                failure = new Error(`launchctl bootout failed: ${(result.stderr || result.stdout || `exit ${result.code}`).trim()}`);
+        }
+        catch (error) {
+            failure = error;
+        } if (failure) {
+            let status;
+            try {
+                status = await common.run('launchctl', ['print', `gui/${process.getuid?.() ?? ''}/${label}`]);
+            }
+            catch (error) {
+                throw new Error(`Unable to verify completed launchd job removal: ${errorMessage(error)}`);
+            }
+            if (status.code === 0)
+                throw new Error(`Completed launchd job is still loaded: ${errorMessage(failure)}`);
+            if (!isLaunchdServiceNotFound(status, label))
+                throw new Error(`Unable to verify completed launchd job absence: ${(status.stderr || status.stdout || `exit ${status.code}`).trim()}`);
+        } common.removeFile(path); },
+        async remove(id) { for (const path of pathsFor(id)) {
+            await common.run('launchctl', ['bootout', `gui/${process.getuid?.() ?? ''}`, path]).catch(() => undefined);
+            common.removeFile(path);
+        } },
+        async status(id) { const paths = pathsFor(id).filter(existsSync); const executable = existsSync(common.nodePath) && existsSync(common.cliPath); if (!paths.length)
+            return { installed: false, healthy: false, message: 'LaunchAgent artifact missing' }; const results = await Promise.all(paths.map(path => common.run('launchctl', ['print', `gui/${process.getuid?.() ?? ''}/${path.split('/').at(-1).slice(0, -6)}`]))); const registered = results.some(result => result.code === 0); return { installed: registered, healthy: registered && executable, message: !registered ? 'launchd registration missing' : !executable ? 'RadioCLI executable missing' : 'registered and executable' }; }
+    };
+}
+function systemdAdapter(common) {
+    const base = join(common.home, '.config', 'systemd', 'user');
+    const names = (id) => ({ service: `${jobName(id)}.service`, timer: `${jobName(id)}.timer` });
+    return {
+        capabilities: () => ({ supported: true, exactWake: false, catchUpAfterWake: true, message: 'systemd user timers catch up after login/wake; WakeSystem is not claimed without system privileges.' }),
+        async install(alarm, occurrence) { const n = names(alarm.id); const env = Object.entries(runtimeEnvironment(common)).map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}\n`).join(''); const cmd = [common.nodePath, ...invocationArgs(common, alarm.id, occurrence)].map(systemdQuote).join(' '); common.write(join(base, n.service), `[Unit]\nDescription=RadioCLI alarm ${unitText(alarm.label)}\n[Service]\nType=exec\n${env}ExecStart=${cmd}\n`); common.write(join(base, n.timer), `[Unit]\nDescription=RadioCLI scheduled radio ${unitText(alarm.label)}\n[Timer]\nOnCalendar=${systemdCalendar(occurrence)}\nPersistent=true\nAccuracySec=1s\nUnit=${n.service}\n[Install]\nWantedBy=timers.target\n`); ensureSuccess(await common.run('systemctl', ['--user', 'daemon-reload']), 'systemctl daemon-reload'); ensureSuccess(await common.run('systemctl', ['--user', 'enable', '--now', n.timer]), 'systemctl enable'); },
+        async remove(id) { const n = names(id); await common.run('systemctl', ['--user', 'disable', '--now', n.timer]).catch(() => undefined); common.removeFile(join(base, n.timer)); common.removeFile(join(base, n.service)); await common.run('systemctl', ['--user', 'daemon-reload']).catch(() => undefined); },
+        async status(id) { const n = names(id); const result = await common.run('systemctl', ['--user', 'is-enabled', n.timer]); const artifact = existsSync(join(base, n.timer)) && existsSync(join(base, n.service)); const executable = existsSync(common.nodePath) && existsSync(common.cliPath); return { installed: result.code === 0 && artifact, healthy: result.code === 0 && artifact && executable, message: result.code !== 0 ? 'user timer not enabled' : !artifact ? 'systemd unit artifact missing' : !executable ? 'RadioCLI executable missing' : 'enabled and executable' }; }
+    };
+}
+function windowsAdapter(common) {
+    const xmlPath = (id) => join(common.env.LOCALAPPDATA ?? join(common.home, 'AppData', 'Local'), 'RadioCLI', 'scheduler', `${jobName(id)}.xml`);
+    return {
+        capabilities: () => ({ supported: true, exactWake: false, catchUpAfterWake: true, message: 'Task Scheduler can request wake when hardware and policy permit, but exact wake cannot be guaranteed. Resync after changing the host timezone; a logged-in audio session is required. Alarm playback has no scheduler execution-time cutoff.' }),
+        async install(alarm, occurrence) { const name = `\\RadioCLI\\${jobName(alarm.id)}`; const command = windowsCommandLine(common.nodePath, invocationArgs(common, alarm.id, occurrence)); const environment = Object.entries(runtimeEnvironment(common)).map(([key, value]) => `set "${key}=${cmdEscape(value)}"`).join(' && '); const raw = `${environment} && ${command}`; const body = `<?xml version="1.0" encoding="UTF-8"?><Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task"><RegistrationInfo><Description>${xml(alarm.label)}</Description></RegistrationInfo><Triggers><TimeTrigger><StartBoundary>${windowsLocalBoundary(occurrence)}</StartBoundary><Enabled>true</Enabled></TimeTrigger></Triggers><Principals><Principal id="Author"><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals><Settings><StartWhenAvailable>true</StartWhenAvailable><WakeToRun>${alarm.reliability.wakeIfSupported}</WakeToRun><DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries><StopIfGoingOnBatteries>false</StopIfGoingOnBatteries><ExecutionTimeLimit>PT0S</ExecutionTimeLimit><MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy></Settings><Actions Context="Author"><Exec><Command>cmd.exe</Command><Arguments>/d /s /c &quot;${xml(raw)}&quot;</Arguments></Exec></Actions></Task>`; const path = xmlPath(alarm.id); common.write(path, body); ensureSuccess(await common.run('schtasks.exe', ['/Create', '/TN', name, '/XML', path, '/F']), 'schtasks create'); },
+        async remove(id) { await common.run('schtasks.exe', ['/Delete', '/TN', `\\RadioCLI\\${jobName(id)}`, '/F']).catch(() => undefined); common.removeFile(xmlPath(id)); },
+        async status(id) { const result = await common.run('schtasks.exe', ['/Query', '/TN', `\\RadioCLI\\${jobName(id)}`]); const artifact = existsSync(xmlPath(id)); const executable = existsSync(common.nodePath) && existsSync(common.cliPath); return { installed: result.code === 0 && artifact, healthy: result.code === 0 && artifact && executable, message: result.code !== 0 ? 'task not registered' : !artifact ? 'task XML artifact missing' : !executable ? 'RadioCLI executable missing' : 'registered and executable' }; }
+    };
+}
+function unsupportedAdapter(message) { return { capabilities: () => ({ supported: false, exactWake: false, catchUpAfterWake: false, message }), install: async () => { throw new Error(message); }, remove: async () => { }, status: async () => ({ installed: false, healthy: false, message }) }; }
+function runCommand(command, args) { return new Promise(resolve => { const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true }); let stdout = ''; let stderr = ''; child.stdout.on('data', v => stdout += String(v)); child.stderr.on('data', v => stderr += String(v)); child.on('error', e => resolve({ code: 127, stdout, stderr: e.message })); child.on('close', code => resolve({ code: code ?? 1, stdout, stderr })); }); }
+function ensureSuccess(result, label) { if (result.code !== 0)
+    throw new Error(`${label} failed: ${(result.stderr || result.stdout || `exit ${result.code}`).trim()}`); }
+function xml(value) { return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;'); }
+function systemdQuote(value) { if (/[\r\n\0]/.test(value))
+    throw new Error('Scheduler arguments cannot contain control characters.'); return `"${value.replaceAll('%', '%%').replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`; }
+function cmdEscape(value) { return value.replaceAll('%', '%%').replaceAll('"', '""').replaceAll('^', '^^').replaceAll('&', '^&').replaceAll('|', '^|').replaceAll('<', '^<').replaceAll('>', '^>'); }
+function windowsCommandLine(command, args) { return [command, ...args].map(windowsArg).join(' '); }
+function windowsArg(value) { return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`; }
+function localParts(date) { return { year: date.getFullYear(), month: date.getMonth() + 1, day: date.getDate(), hour: date.getHours(), minute: date.getMinutes(), second: date.getSeconds() }; }
+function systemdCalendar(date) { return `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, '0')}-${String(date.getUTCDate()).padStart(2, '0')} ${String(date.getUTCHours()).padStart(2, '0')}:${String(date.getUTCMinutes()).padStart(2, '0')}:${String(date.getUTCSeconds()).padStart(2, '0')} UTC`; }
+function windowsLocalBoundary(date) { const p = localParts(date); return `${p.year}-${String(p.month).padStart(2, '0')}-${String(p.day).padStart(2, '0')}T${String(p.hour).padStart(2, '0')}:${String(p.minute).padStart(2, '0')}:${String(p.second).padStart(2, '0')}`; }
+function unitText(value) { return value.replace(/[\r\n\0]/g, ' ').replaceAll('%', '%%').slice(0, 200); }
+function errorMessage(error) { return error instanceof Error ? error.message : String(error); }
+function isLaunchdServiceNotFound(result, label) { const output = `${result.stderr}\n${result.stdout}`; return result.code !== 0 && output.includes(label) && /could not find service\b/i.test(output) && /\bin domain for\b/i.test(output); }
+async function mapConcurrent(items, limit, work) { const results = new Array(items.length); let next = 0; await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => { while (true) {
+    const index = next;
+    next += 1;
+    if (index >= items.length)
+        return;
+    results[index] = await work(items[index]);
+} })); return results; }

package/dist/alarms/setup-verification.js

@@ -0,0 +1,187 @@
+import { randomUUID } from 'node:crypto';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PlayerController } from '../player/player-controller.js';
+import { detectPlaybackBackends } from '../player/backend-install.js';
+import { ProviderManager } from '../providers/provider-manager.js';
+import { connectActiveAlarm, startActiveAlarmSession } from './active-session.js';
+import { createPowerInhibitor } from './inhibitor.js';
+import { createSystemVolumeController } from './system-volume.js';
+import { verifyAlarmTerminalLaunch } from './terminal-launcher.js';
+const definitions = [
+    { id: 'scheduler', label: 'Native scheduler', critical: true },
+    { id: 'wake', label: 'Wake and catch-up policy', critical: false },
+    { id: 'terminal', label: 'Ringing terminal', critical: true },
+    { id: 'controls', label: 'Dismiss and snooze controls', critical: true },
+    { id: 'playback', label: 'Station and audio backend', critical: true },
+    { id: 'volume', label: 'System output volume', critical: false },
+    { id: 'power', label: 'Sleep protection', critical: false },
+    { id: 'cleanup', label: 'Verification cleanup', critical: true }
+];
+export async function verifyAlarmSetup(scheduler, alarm, settings, onUpdate = () => { }, deps = {}) {
+    const now = deps.now ?? (() => new Date());
+    const startedAt = now().toISOString();
+    let report = { state: 'running', alarmLabel: alarm?.label, startedAt, steps: definitions.map(item => ({ ...item, state: 'pending', detail: 'Waiting…' })) };
+    const publish = () => { report = { ...report, steps: report.steps.map(step => ({ ...step })) }; onUpdate(report); };
+    const set = (id, state, detail) => { const step = report.steps.find(item => item.id === id); if (step) {
+        step.state = state;
+        step.detail = detail;
+    } publish(); };
+    publish();
+    const target = alarm?.playback.volume ?? settings.volume;
+    let temporary;
+    let schedulerInstalled = false;
+    let powerLease;
+    let volumeLease;
+    try {
+        set('scheduler', 'running', 'Installing a disposable native job…');
+        try {
+            const capability = scheduler.doctor();
+            if (!capability.supported)
+                throw new Error(capability.message);
+            temporary = temporaryAlarm(alarm, now(), deps.id?.() ?? randomUUID());
+            const occurrence = await scheduler.sync(temporary);
+            if (!occurrence)
+                throw new Error('The disposable alarm did not receive a future occurrence.');
+            schedulerInstalled = true;
+            const [status] = await scheduler.statusAll([temporary]);
+            if (!status?.native.installed || !status.native.healthy)
+                throw new Error(status?.native.message ?? 'The native job could not be verified.');
+            set('scheduler', 'passed', `Registered and queried a disposable ${platformSchedulerName()} job.`);
+            if (alarm?.reliability.wakeIfSupported)
+                set('wake', capability.exactWake ? 'passed' : 'warning', capability.exactWake ? 'This scheduler reports exact wake support.' : `The OS accepted the job, but wake remains hardware and policy dependent. ${capability.message}`);
+            else
+                set('wake', 'passed', capability.catchUpAfterWake ? 'Wake was not requested; the native scheduler supports catch-up after the machine wakes.' : 'Wake was not requested for this alarm.');
+        }
+        catch (error) {
+            set('scheduler', 'failed', messageOf(error));
+            set('wake', 'warning', 'Wake behavior could not be assessed because native scheduler verification failed.');
+        }
+        set('terminal', 'running', 'Opening the saved terminal and waiting for its authenticated response…');
+        try {
+            const terminal = await (deps.terminalProbe ?? (() => verifyAlarmTerminalLaunch()))();
+            set('terminal', 'passed', `Opened ${friendlyTerminal(terminal)} and received its private loopback response.`);
+        }
+        catch (error) {
+            set('terminal', 'failed', messageOf(error));
+        }
+        set('controls', 'running', 'Testing the same authenticated local channel used by dismiss and snooze…');
+        try {
+            await (deps.controlProbe ?? probeControlChannel)();
+            set('controls', 'passed', 'Authenticated local ringing controls connected successfully.');
+        }
+        catch (error) {
+            set('controls', 'failed', messageOf(error));
+        }
+        const inhibitor = deps.inhibitor ?? createPowerInhibitor();
+        set('power', 'running', 'Acquiring a real sleep-inhibition lease…');
+        try {
+            const capability = inhibitor.status();
+            if (!capability.supported)
+                throw new Error(capability.message);
+            powerLease = await inhibitor.acquire('RadioCLI alarm setup verification');
+            set('power', 'passed', capability.message);
+            void powerLease.unexpectedExit?.then(error => set('power', 'warning', `Sleep protection exited during the rehearsal: ${error.message}`)).catch(() => { });
+        }
+        catch (error) {
+            set('power', 'warning', `Playback can continue, but sleep protection was not verified: ${messageOf(error)}`);
+        }
+        const volume = deps.systemVolume ?? createSystemVolumeController();
+        set('volume', 'running', `Raising and unmuting local output to at least ${target}%…`);
+        try {
+            volumeLease = await volume.acquireMinimum(target);
+            set('volume', 'passed', `${volumeLease.message} The previous setting will be restored after the sample.`);
+        }
+        catch (error) {
+            set('volume', 'warning', `Player volume will still be applied, but OS output control was not verified: ${messageOf(error)}`);
+        }
+        set('playback', 'running', alarm ? `Playing a short sample of ${alarm.station.name}…` : 'Waiting for a configured alarm station…');
+        if (!alarm)
+            set('playback', 'failed', 'Create at least one alarm so verification can test its real station, backend, and configured volume.');
+        else
+            try {
+                const backends = (deps.backends ?? (() => detectPlaybackBackends()))();
+                if (!backends.length)
+                    throw new Error('No local playback backend is installed. Install mpv, ffplay, or VLC.');
+                const runtimeSettings = { ...settings, volume: target, preferredBackend: 'auto', preferredAirPlayDevice: undefined, tuneTimeoutSeconds: Math.min(5, settings.tuneTimeoutSeconds) };
+                const player = (deps.player ?? (value => new PlayerController(() => value)))(runtimeSettings);
+                player.refreshDetectedBackends();
+                const resolver = deps.resolve ?? (station => new ProviderManager().resolve(station));
+                try {
+                    const stream = await bounded(resolver(alarm.station), 8_000, 'Station resolution timed out.');
+                    await bounded(player.play(alarm.station, stream.url), 8_000, 'Audio backend did not become ready.');
+                    await (deps.wait ?? wait)(3_000);
+                    set('playback', 'passed', `Played a 3-second sample using an available local backend at the configured ${target}% alarm volume.`);
+                }
+                finally {
+                    try {
+                        await bounded(player.stop(), 2_000, 'Audio preview cleanup timed out.');
+                    }
+                    catch (error) {
+                        set('playback', 'failed', `The sample started, but audio cleanup failed: ${messageOf(error)}`);
+                    }
+                }
+            }
+            catch (error) {
+                set('playback', 'failed', messageOf(error));
+            }
+    }
+    finally {
+        try {
+            await volumeLease?.release();
+        }
+        catch (error) {
+            set('volume', 'warning', `The sample ran, but the previous system volume could not be restored: ${messageOf(error)}`);
+        }
+        try {
+            await powerLease?.release();
+        }
+        catch (error) {
+            set('power', 'warning', `Sleep protection was acquired, but release could not be verified: ${messageOf(error)}`);
+        }
+        set('cleanup', 'running', 'Removing disposable native scheduler artifacts…');
+        if (temporary)
+            try {
+                await scheduler.remove(temporary.id);
+                schedulerInstalled = false;
+                set('cleanup', 'passed', 'Disposable scheduler job and local verification artifacts were removed.');
+            }
+            catch (error) {
+                set('cleanup', 'failed', `Manual repair is required because disposable job cleanup failed: ${messageOf(error)}`);
+            }
+        else
+            set('cleanup', 'passed', 'No disposable native job was created.');
+        if (schedulerInstalled)
+            set('cleanup', 'failed', 'The disposable native job may still be installed; run Alarm Repair before relying on alarms.');
+    }
+    const failed = report.steps.some(step => step.state === 'failed' && step.critical);
+    const warning = report.steps.some(step => step.state === 'warning' || step.state === 'failed');
+    report = { ...report, state: failed ? 'failed' : warning ? 'warning' : 'passed', finishedAt: now().toISOString() };
+    publish();
+    return report;
+}
+function temporaryAlarm(source, now, id) { const at = new Date(Math.ceil((now.getTime() + 10 * 60_000) / 60_000) * 60_000); return { id: `setup-verification-${id}`, label: 'RadioCLI setup verification', enabled: true, station: source?.station ?? { id: 'verification', provider: 'playlist', name: 'RadioCLI verification', tags: [], streamUrl: 'https://127.0.0.1/' }, schedule: { type: 'once', at: at.toISOString() }, playback: { volume: source?.playback.volume ?? 40, fadeSeconds: 0, stopAfterMinutes: 1 }, reliability: { missedRunGraceMinutes: 1, wakeIfSupported: false }, createdAt: now.toISOString(), updatedAt: now.toISOString() }; }
+async function probeControlChannel() { const root = mkdtempSync(join(tmpdir(), 'radiocli-alarm-verify-')); const file = join(root, 'probe.json'); const server = await startActiveAlarmSession({ alarmId: 'setup-verification', scheduledAt: new Date().toISOString(), stationName: 'RadioCLI verification', startedAt: new Date().toISOString() }, { filePath: file, onDismiss: () => { }, onSnooze: () => { }, onKeepPlaying: () => { } }); try {
+    const client = await connectActiveAlarm(file);
+    if (!client)
+        throw new Error('The ringing control channel was not discoverable.');
+    const status = await client.status();
+    if (status.alarmId !== 'setup-verification')
+        throw new Error('The ringing control channel returned the wrong alarm identity.');
+}
+finally {
+    await server.close();
+    rmSync(root, { recursive: true, force: true });
+} }
+function platformSchedulerName() { return process.platform === 'darwin' ? 'launchd' : process.platform === 'win32' ? 'Task Scheduler' : 'systemd'; }
+function friendlyTerminal(value) { return value.replace(/^darwin:/, '').replace(/^win32:/, '').replace(/^linux:/, ''); }
+function messageOf(error) { return error instanceof Error ? error.message : String(error); }
+function wait(milliseconds) { return new Promise(resolve => setTimeout(resolve, milliseconds)); }
+async function bounded(promise, milliseconds, message) { let timer; try {
+    return await Promise.race([promise, new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(message)), milliseconds); })]);
+}
+finally {
+    if (timer)
+        clearTimeout(timer);
+} }

package/dist/alarms/system-volume.js

@@ -0,0 +1,43 @@
+import { spawn } from 'node:child_process';
+import { resolveCommand } from '../player/command.js';
+export function createSystemVolumeController(platform = process.platform, run = runCommand, resolve = resolveCommand) {
+    const backend = platform === 'darwin' ? macBackend(run) : platform === 'linux' ? linuxBackend(run, resolve) : platform === 'win32' ? windowsBackend(run, resolve) : undefined;
+    return { async acquireMinimum(volume) { if (!backend)
+            throw new Error(`System output volume control is unavailable on ${platform}.`); const target = clamp(volume); const before = await backend.read(); const applied = Math.max(before.volume, target); if (before.muted || before.volume < target)
+            await backend.write({ volume: applied, muted: false }); let released = false; return { message: before.muted || before.volume < target ? `Local output raised to at least ${target}% and unmuted for the alarm.` : `Local output was already at least ${target}% and unmuted.`, async release() { if (released)
+                return; released = true; if (before.muted || before.volume < target)
+                await backend.write(before); } }; } };
+}
+function macBackend(run) { return { async read() { const result = await checked(run('/usr/bin/osascript', ['-e', 'set s to get volume settings', '-e', 'return (output volume of s as text) & "," & (output muted of s as text)']), 'read macOS output volume'); const match = /^(\d+)\s*,\s*(true|false)/i.exec(result.stdout.trim()); if (!match)
+        throw new Error('macOS returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1])), muted: match[2]?.toLowerCase() === 'true' }; }, async write(value) { await checked(run('/usr/bin/osascript', ['-e', `set volume output volume ${clamp(value.volume)} ${value.muted ? 'with' : 'without'} output muted`]), 'set macOS output volume'); } }; }
+function linuxBackend(run, resolve) {
+    const wpctl = resolve('wpctl');
+    if (wpctl)
+        return { async read() { const result = await checked(run(wpctl, ['get-volume', '@DEFAULT_AUDIO_SINK@']), 'read PipeWire output volume'); const match = /Volume:\s*([\d.]+)/i.exec(result.stdout); if (!match)
+                throw new Error('wpctl returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1]) * 100), muted: /\[MUTED\]/i.test(result.stdout) }; }, async write(value) { await checked(run(wpctl, ['set-volume', '@DEFAULT_AUDIO_SINK@', `${clamp(value.volume)}%`]), 'set PipeWire output volume'); await checked(run(wpctl, ['set-mute', '@DEFAULT_AUDIO_SINK@', value.muted ? '1' : '0']), 'set PipeWire mute state'); } };
+    const pactl = resolve('pactl');
+    if (pactl)
+        return { async read() { const [volume, mute] = await Promise.all([checked(run(pactl, ['get-sink-volume', '@DEFAULT_SINK@']), 'read PulseAudio output volume'), checked(run(pactl, ['get-sink-mute', '@DEFAULT_SINK@']), 'read PulseAudio mute state')]); const match = /(\d+)%/.exec(volume.stdout); if (!match)
+                throw new Error('pactl returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1])), muted: /yes/i.test(mute.stdout) }; }, async write(value) { await checked(run(pactl, ['set-sink-volume', '@DEFAULT_SINK@', `${clamp(value.volume)}%`]), 'set PulseAudio output volume'); await checked(run(pactl, ['set-sink-mute', '@DEFAULT_SINK@', value.muted ? '1' : '0']), 'set PulseAudio mute state'); } };
+    const amixer = resolve('amixer');
+    if (amixer)
+        return { async read() { const result = await checked(run(amixer, ['get', 'Master']), 'read ALSA output volume'); const matches = [...result.stdout.matchAll(/\[(\d+)%\]/g)]; const last = matches.at(-1); if (!last)
+                throw new Error('amixer returned an unreadable output-volume state.'); return { volume: clamp(Number(last[1])), muted: /\[off\]/i.test(result.stdout) }; }, async write(value) { await checked(run(amixer, ['set', 'Master', `${clamp(value.volume)}%`, value.muted ? 'mute' : 'unmute']), 'set ALSA output volume'); } };
+    return undefined;
+}
+function windowsBackend(run, resolve) { const powershell = resolve('powershell.exe') ?? resolve('pwsh.exe'); if (!powershell)
+    return undefined; return { async read() { const result = await checked(run(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', `${windowsCoreAudio}; [RadioCliVolume]::Get()`]), 'read Windows output volume'); const match = /^(\d+)\s*,\s*(true|false)/im.exec(result.stdout); if (!match)
+        throw new Error('Windows returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1])), muted: match[2]?.toLowerCase() === 'true' }; }, async write(value) { await checked(run(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', `${windowsCoreAudio}; [RadioCliVolume]::Set(${clamp(value.volume)}, $${value.muted ? 'true' : 'false'})`]), 'set Windows output volume'); } }; }
+const windowsCoreAudio = String.raw `Add-Type -TypeDefinition @'
+using System; using System.Runtime.InteropServices;
+public enum EDataFlow { eRender, eCapture, eAll } public enum ERole { eConsole, eMultimedia, eCommunications }
+[ComImport, Guid("BCDE0395-E52F-467C-8E3D-C4579291692E")] class MMDeviceEnumerator {}
+[ComImport, Guid("A95664D2-9614-4F35-A746-DE8DB63617E6"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] interface IMMDeviceEnumerator { int EnumAudioEndpoints(EDataFlow a,uint b,out object c); int GetDefaultAudioEndpoint(EDataFlow a,ERole b,out IMMDevice c); }
+[ComImport, Guid("D666063F-1587-4E43-81F1-B948E807363F"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] interface IMMDevice { int Activate(ref Guid id,uint context,IntPtr parameters,[MarshalAs(UnmanagedType.IUnknown)] out object result); }
+[ComImport, Guid("5CDF2C82-841E-4546-9722-0CF74078229A"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] interface IAudioEndpointVolume { int RegisterControlChangeNotify(IntPtr p); int UnregisterControlChangeNotify(IntPtr p); int GetChannelCount(out uint c); int SetMasterVolumeLevel(float l,Guid g); int SetMasterVolumeLevelScalar(float l,Guid g); int GetMasterVolumeLevel(out float l); int GetMasterVolumeLevelScalar(out float l); int SetChannelVolumeLevel(uint c,float l,Guid g); int SetChannelVolumeLevelScalar(uint c,float l,Guid g); int GetChannelVolumeLevel(uint c,out float l); int GetChannelVolumeLevelScalar(uint c,out float l); int SetMute([MarshalAs(UnmanagedType.Bool)] bool m,Guid g); int GetMute(out bool m); }
+public static class RadioCliVolume { static IAudioEndpointVolume Endpoint(){IMMDevice d;((IMMDeviceEnumerator)new MMDeviceEnumerator()).GetDefaultAudioEndpoint(EDataFlow.eRender,ERole.eMultimedia,out d);object o;Guid id=typeof(IAudioEndpointVolume).GUID;d.Activate(ref id,23,IntPtr.Zero,out o);return(IAudioEndpointVolume)o;} public static string Get(){float v;bool m;var e=Endpoint();e.GetMasterVolumeLevelScalar(out v);e.GetMute(out m);return Math.Round(v*100)+","+m.ToString().ToLower();} public static void Set(int v,bool m){var e=Endpoint();e.SetMasterVolumeLevelScalar(Math.Max(0,Math.Min(100,v))/100f,Guid.Empty);e.SetMute(m,Guid.Empty);} }
+'@`;
+function clamp(value) { return Math.max(0, Math.min(100, Math.round(Number.isFinite(value) ? value : 0))); }
+async function checked(promise, label) { const result = await promise; if (result.code !== 0)
+    throw new Error(`${label} failed: ${(result.stderr || result.stdout || `exit ${result.code}`).trim()}`); return result; }
+function runCommand(command, args) { return new Promise(resolve => { const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true }); let stdout = ''; let stderr = ''; child.stdout.on('data', value => stdout += String(value)); child.stderr.on('data', value => stderr += String(value)); child.on('error', error => resolve({ code: 127, stdout, stderr: error.message })); child.on('close', code => resolve({ code: code ?? 1, stdout, stderr })); }); }