@ciphore/radiocli 0.2.3 → 0.2.4

package/dist/alarms/runner.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { platformPaths } from '../platform/paths.js';
 import { dirname, join } from 'node:path';
 import { assessScheduledOccurrence, NATIVE_DISPATCH_TOLERANCE_MS, nextOccurrenceForAlarm } from './schedule.js';
 import { startActiveAlarmSession } from './active-session.js';
@@ -25,10 +25,18 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
     let lease;
     let systemVolumeLease;
     let listening = false;
+    let historyStarted = false;
     let firedAt;
+    const runnerWarnings = new Set();
+    const recordRunnerWarning = (message) => { runnerWarnings.add(message); try {
+        deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: listening, message: [...runnerWarnings].join(' ') });
+    }
+    catch { } };
     let preserveNextOverride = false;
     let preserveSystemVolume = false;
+    let handoffOutput;
     let validTerminalOccurrence = false;
+    let completeLock = true;
     let signalReceived = false;
     let resolveEarlySignal = () => { };
     let onPlaybackSignal = () => { };
@@ -49,6 +57,7 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
         }
         const assessment = assessScheduledOccurrence(scheduledAt, deps.now(), alarm.reliability.missedRunGraceMinutes);
         if (assessment === 'pending') {
+            completeLock = false;
             outcome = finish('failed', 'Scheduler launched the alarm before its occurrence.');
             return { status: outcome.status, message: outcome.message };
         }
@@ -62,8 +71,8 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
             onDismiss: () => { action = 'dismissed'; resolveAction('dismissed'); resolveEarlySignal(); },
             onSnooze: minutes => { deps.store.snoozeAlarm(alarmId, new Date(deps.now().getTime() + minutes * 60_000)); preserveNextOverride = true; action = 'snoozed'; resolveAction('snoozed'); resolveEarlySignal(); },
             onKeepPlaying: () => { keepPlaying = true; session?.update({ keepPlaying: true }); },
-            onHandoff: () => { if (!listening)
-                throw new Error('Alarm playback is still starting.'); preserveSystemVolume = true; action = 'handoff'; resolveAction('handoff'); }
+            onHandoff: async () => { if (!listening)
+                throw new Error('Alarm playback is still starting.'); handoffOutput = (systemVolumeLease?.release({ preserve: true }) ?? Promise.resolve()).then(() => { preserveSystemVolume = true; }); await handoffOutput; action = 'handoff'; resolveAction('handoff'); }
         });
         void creatingSession.then(created => { if (signalReceived)
             void created.close().catch(() => undefined); }).catch(() => { });
@@ -160,15 +169,24 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
             deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'power', healthy: false, active: false, message: `Playback continues without sleep protection: ${errorMessage(error)}` });
         }
         const startedAt = deps.now();
-        deps.store.addRecent(resolvedStation);
-        deps.store.startListeningSession(resolvedStation, startedAt);
         listening = true;
+        try {
+            deps.store.addRecent(resolvedStation);
+        }
+        catch (error) {
+            recordRunnerWarning(`Recent listening history could not be saved: ${errorMessage(error)}`);
+        }
+        try {
+            deps.store.startListeningSession(resolvedStation, startedAt);
+            historyStarted = true;
+        }
+        catch (error) {
+            recordRunnerWarning(`Listening history could not be started: ${errorMessage(error)}`);
+        }
         const activeStatus = { alarmId, scheduledAt: scheduledAt.toISOString(), stationName: resolvedStation.name, station: resolvedStation, startedAt: startedAt.toISOString(), state: 'playing' };
         session.update(activeStatus);
-        void deps.openControls?.(activeStatus).catch(error => { try {
-            deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: true, message: `Alarm is playing, but RadioCLI controls could not open automatically: ${errorMessage(error)}` });
-        }
-        catch { } });
+        void deps.openControls?.(activeStatus).then(result => { if (result && !result.opened && result.terminal !== 'existing-tui')
+            recordRunnerWarning(`RadioCLI controls are unavailable or unverified: ${result.message}`); }).catch(error => { recordRunnerWarning(`RadioCLI controls could not open automatically: ${errorMessage(error)}`); });
         onPlaybackSignal = () => { action = 'signal'; resolveAction('signal'); };
         if (signalReceived)
             onPlaybackSignal();
@@ -211,11 +229,13 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
         return { status: 'failed', message: outcome.message };
     }
     finally {
+        listening = false;
         unsubscribeSignals?.();
         try {
             await deps.player.stop();
         }
         catch { }
+        await handoffOutput?.catch(() => undefined);
         if (!preserveSystemVolume)
             try {
                 await systemVolumeLease?.release();
@@ -226,12 +246,19 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
                 }
                 catch { }
             }
-        if (listening) {
+        if (historyStarted) {
             try {
                 deps.store.checkpointActiveListeningSession(deps.now());
+            }
+            catch (error) {
+                recordRunnerWarning(`Listening history could not be checkpointed: ${errorMessage(error)}`);
+            }
+            try {
                 deps.store.finishActiveListeningSession(deps.now());
             }
-            catch { }
+            catch (error) {
+                recordRunnerWarning(`Listening history could not be finished: ${errorMessage(error)}`);
+            }
         }
         try {
             await lease?.release();
@@ -250,12 +277,14 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
         catch { }
         if (alarm && outcome) {
             try {
-                deps.store.recordAlarmOutcome(alarmId, outcome, { clearNextOverride: !preserveNextOverride });
+                deps.store.recordAlarmOutcome(alarmId, outcome, { clearNextOverride: validTerminalOccurrence && !preserveNextOverride });
                 const latest = deps.store.getAlarm(alarmId);
                 if (alarm.schedule.type === 'once' && latest?.schedule.type === 'once' && latest.schedule.at === alarm.schedule.at && validTerminalOccurrence && !preserveNextOverride)
                     deps.store.toggleAlarm(alarmId, false);
             }
-            catch { }
+            catch (error) {
+                recordRunnerWarning(`Alarm outcome or completion state could not be saved: ${errorMessage(error)}`);
+            }
         }
         alarm = deps.store.getAlarm(alarmId);
         if (alarm)
@@ -267,7 +296,7 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
             }
             catch { }
         try {
-            releaseLock();
+            releaseLock(completeLock);
         }
         catch (error) {
             try {
@@ -275,15 +304,16 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
             }
             catch { }
         }
-        try {
-            await deps.scheduler.completeOccurrence?.(alarmId, scheduledAt);
-        }
-        catch (error) {
+        if (completeLock)
             try {
-                deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'scheduler', healthy: false, message: `Completed launch job cleanup failed: ${errorMessage(error)}` });
+                await deps.scheduler.completeOccurrence?.(alarmId, scheduledAt);
+            }
+            catch (error) {
+                try {
+                    deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'scheduler', healthy: false, message: `Completed launch job cleanup failed: ${errorMessage(error)}` });
+                }
+                catch { }
             }
-            catch { }
-        }
     }
 }
 export function acquireOccurrenceLock(alarmId, scheduledAt, root = defaultAlarmRuntimeDirectory()) {
@@ -311,7 +341,10 @@ export function acquireOccurrenceLock(alarmId, scheduledAt, root = defaultAlarmR
         }
     }
     writeFileSync(join(path, 'running'), String(process.pid), { mode: 0o600 });
-    return () => { rmSync(join(path, 'running'), { force: true }); writeFileSync(join(path, 'completed'), new Date().toISOString(), { mode: 0o600 }); };
+    return (completed = true) => { if (!completed) {
+        rmSync(path, { recursive: true, force: true });
+        return;
+    } rmSync(join(path, 'running'), { force: true }); writeFileSync(join(path, 'completed'), new Date().toISOString(), { mode: 0o600 }); };
 }
 export function pruneCompletedOccurrenceLocks(root = defaultAlarmRuntimeDirectory(), olderThanMs = 30 * 24 * 60 * 60_000, now = Date.now()) { const directory = join(root, 'locks'); if (!existsSync(directory))
     return 0; let removed = 0; for (const name of readdirSync(directory)) {
@@ -324,9 +357,7 @@ export function pruneCompletedOccurrenceLocks(root = defaultAlarmRuntimeDirector
     }
     catch { }
 } return removed; }
-export function defaultAlarmRuntimeDirectory() { if (process.env.RADIOCLI_HOME)
-    return join(process.env.RADIOCLI_HOME, 'runtime'); if (process.platform === 'win32')
-    return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'RadioCLI', 'runtime'); return join(process.env.XDG_RUNTIME_DIR ?? join(homedir(), '.local', 'state'), 'radiocli'); }
+export function defaultAlarmRuntimeDirectory() { return platformPaths().runtime; }
 export const defaultRunnerUtilities = { acquireLock: acquireOccurrenceLock, createSession: startActiveAlarmSession, wait: (milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds)), subscribeSignals: (handler) => { process.once('SIGTERM', handler); process.once('SIGHUP', handler); process.once('SIGINT', handler); return () => { process.off('SIGTERM', handler); process.off('SIGHUP', handler); process.off('SIGINT', handler); }; } };
 function errorMessage(error) { return error instanceof Error ? error.message : String(error); }
 function processAlive(pid) { try {

package/dist/alarms/schedule.js

@@ -11,10 +11,17 @@ export function isValidTimeZone(timezone) {
 }
 export function canonicalizeTimeZone(timezone) {
     const value = timezone.trim();
-    if (!isValidTimeZone(value)) {
+    try {
+        if (!value)
+            throw new Error('Empty timezone.');
+        // The constructor validates the zone and resolves its canonical name.
+        // Constructing twice made large-library validation expensive on Node 22
+        // Intel hosts; keep one native validation for every supplied value.
+        return new Intl.DateTimeFormat('en-US', { timeZone: value }).resolvedOptions().timeZone;
+    }
+    catch {
         throw new Error(`Invalid IANA timezone: ${timezone}`);
     }
-    return new Intl.DateTimeFormat('en-US', { timeZone: value }).resolvedOptions().timeZone;
 }
 export function canonicalizeAlarmTime(time) {
     const match = /^(\d{1,2}):(\d{2})$/.exec(time.trim());

package/dist/alarms/scheduler.js

@@ -8,7 +8,11 @@ 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';
+import { detectGraphicalTerminal } from '../platform/terminals.js';
+import { identifyPlatform, nativeAdapters } from '../platform/runtime.js';
+import { resolveCommandDetails } from '../platform/executables.js';
+import { launchEnvironment, nodeLaunchCommand } from '../platform/launch-command.js';
+import { powershellCommand } from '../platform/shell.js';
 export class SchedulerService {
     adapter;
     now;
@@ -94,7 +98,7 @@ export class SchedulerService {
         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 runtimeStatus(alarms = []) { const [capabilities, status] = await Promise.all([this.adapter.probeCapabilities?.() ?? this.doctor(), this.statusAll(alarms)]); return { capabilities, entries: this.health.list(), alarms: status }; }
     async reconcileGuard(alarm) { if (!this.guard)
         return; try {
         const requested = alarm.enabled && alarm.reliability.keepAwakeUntilAlarm;
@@ -111,7 +115,7 @@ export class SchedulerService {
     } }
     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 status = await this.guard.status?.(); if (status && !status.guards.some(item => item.alarmId === alarmId) && !status.unresolvedGuards?.some(item => !item.alarmId || 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 {
@@ -132,29 +136,27 @@ export function createSchedulerAdapter(deps = {}) {
     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 host = identifyPlatform({ platform, env });
+    const policy = nativeAdapters(host);
     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')
+    const resolve = (command) => resolveCommandDetails(command, { platform, env, home }).path;
+    const run = deps.run ?? ((command, args) => runCommand(resolve(command) ?? command, args));
+    const commandExists = deps.commandExists ?? (command => resolve(command) !== null);
+    const common = { platform, home, nodePath, cliPath, env, terminal: detectGraphicalTerminal(platform, env), write, removeFile, run };
+    if (policy.scheduler === 'launchd')
         return launchdAdapter(common);
-    if (platform === 'win32')
+    if (policy.scheduler === 'task-scheduler')
         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}.`);
+    if (policy.scheduler === 'systemd') {
+        if (commandExists('systemctl'))
+            return systemdAdapter(common);
+        return unavailableAdapter('systemctl is unavailable; systemd job registration and removal cannot be verified. Repair artifacts were retained.');
+    }
+    return unsupportedAdapter(`Alarm scheduling is not supported on ${host.id === 'unknown' ? host.platform : host.id}.`);
 }
 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;
+    return launchEnvironment(common.env, { platform: common.platform, includeDesktop: true, terminal: common.terminal });
 }
 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()];
@@ -170,38 +172,41 @@ function launchdAdapter(common) {
         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)
+    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 = nodeLaunchCommand(common.nodePath, invocationArgs(common, alarm.id, occurrence, 'internal-launchd'), runtimeEnvironment(common)).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()}`);
+    const removeJob = async (path) => {
+        const label = path.split('/').at(-1).slice(0, -6);
+        let failure;
+        try {
+            ensureSuccess(await common.run('launchctl', ['bootout', `gui/${process.getuid?.() ?? ''}`, path]), 'launchctl bootout');
         }
         catch (error) {
             failure = error;
-        } if (failure) {
+        }
+        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)}`);
+                throw new Error(`Unable to verify launchd job removal: ${errorMessage(error)}`);
             }
             if (status.code === 0)
-                throw new Error(`Completed launchd job is still loaded: ${errorMessage(failure)}`);
+                throw new Error(`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);
-        } },
+                throw new Error(`Unable to verify launchd job absence: ${commandMessage(status)}`);
+        }
+        common.removeFile(path);
+    };
+    return {
+        capabilities: () => ({ name: 'launchd', 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); await removeJob(existsSync(specific) ? specific : pathFor(id)); },
+        async remove(id) { for (const path of pathsFor(id))
+            await removeJob(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' }; }
     };
@@ -209,38 +214,175 @@ function launchdAdapter(common) {
 function systemdAdapter(common) {
     const base = join(common.home, '.config', 'systemd', 'user');
     const names = (id) => ({ service: `${jobName(id)}.service`, timer: `${jobName(id)}.timer` });
+    const capabilities = () => ({ name: 'systemd', supported: true, exactWake: false, catchUpAfterWake: true, message: 'systemd tooling detected; user-manager readiness is checked during registration and diagnostics. Persistent user timers can catch up after login/wake; WakeSystem is not claimed without system privileges.' });
+    const probeCapabilities = async () => {
+        try {
+            const result = await boundedProbe(common.run('systemctl', ['--user', 'show', '--property=Version', '--value']));
+            ensureSuccess(result, 'systemd user manager probe');
+            return { ...capabilities(), message: 'The systemd user manager is reachable. Persistent timers can catch up after login/wake; WakeSystem is not claimed without system privileges.' };
+        }
+        catch (error) {
+            return { ...capabilities(), supported: false, catchUpAfterWake: false, message: `The systemd user manager is unavailable: ${errorMessage(error)}` };
+        }
+    };
     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' }; }
+        capabilities,
+        probeCapabilities,
+        async install(alarm, occurrence) { const readiness = await probeCapabilities(); if (!readiness.supported)
+            throw new Error(readiness.message); const n = names(alarm.id); const env = Object.entries(runtimeEnvironment(common)).map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}\n`).join(''); const cmd = systemdExecCommand(nodeLaunchCommand(common.nodePath, invocationArgs(common, alarm.id, occurrence), runtimeEnvironment(common))); 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 removeWithVerification(() => common.run('systemctl', ['--user', 'disable', '--now', n.timer]), () => common.run('systemctl', ['--user', 'show', n.timer, '--property=LoadState', '--property=ActiveState']), result => /^LoadState=not-found\r?$/m.test(result.stdout) && /^ActiveState=inactive\r?$/m.test(result.stdout), 'systemd timer');
+            common.removeFile(join(base, n.timer));
+            common.removeFile(join(base, n.service));
+            ensureSuccess(await common.run('systemctl', ['--user', 'daemon-reload']), 'systemctl daemon-reload after removal');
+        },
+        async status(id) { const readiness = await probeCapabilities(); if (!readiness.supported)
+            return { installed: false, healthy: false, message: readiness.message }; const n = names(id); const [enabled, active] = await Promise.all([common.run('systemctl', ['--user', 'is-enabled', n.timer]), common.run('systemctl', ['--user', 'is-active', n.timer])]); const artifact = existsSync(join(base, n.timer)) && existsSync(join(base, n.service)); const executable = existsSync(common.nodePath) && existsSync(common.cliPath); return { installed: enabled.code === 0 && artifact, healthy: enabled.code === 0 && active.code === 0 && artifact && executable, message: enabled.code !== 0 ? 'user timer not enabled' : active.code !== 0 ? 'user timer is not active' : !artifact ? 'systemd unit artifact missing' : !executable ? 'RadioCLI executable missing' : 'enabled, active, 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)); },
+        capabilities: () => ({ name: 'Task Scheduler', 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 direct = nodeLaunchCommand(common.nodePath, invocationArgs(common, alarm.id, occurrence), runtimeEnvironment(common));
+            // Task Scheduler expands %NAME% in Path and Arguments itself. Only its
+            // standard PowerShell path and fixed flags/encoded data cross that boundary.
+            const command = '%SystemRoot%\\System32\\WindowsPowerShell\\v1.0\\powershell.exe';
+            const args = powershellCommand(direct).join(' ');
+            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>${xml(command)}</Command><Arguments>${xml(args)}</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) {
+            const name = `\\RadioCLI\\${jobName(id)}`;
+            const removal = await settledOperation(async () => {
+                const result = await boundedWindowsCommand(() => common.run('schtasks.exe', ['/Delete', '/TN', name, '/F']), 'deletion');
+                if (result.code !== 0)
+                    throw new Error(`Task Scheduler job removal failed: ${windowsCommandMessage(result)}`);
+            });
+            let state;
+            try {
+                const result = await boundedWindowsCommand(() => common.run('powershell.exe', windowsTaskLookupCommand(name)), 'absence lookup');
+                state = windowsTaskState(result, name);
+            }
+            catch (error) {
+                throw new Error(`Unable to verify Task Scheduler job removal; repair artifacts were retained. ${removal.error ?? ''} ${errorMessage(error)}`);
+            }
+            if (state.state !== 'absent')
+                throw new Error(`Unable to verify Task Scheduler job absence; repair artifacts were retained. ${removal.error ?? ''} ${state.message}`);
+            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 windowsTaskLookupCommand(taskPath) {
+    // Only GetTask failures can establish absence. A missing COM service or root
+    // folder must remain a repairable error, regardless of the UI language.
+    const encodedPath = Buffer.from(taskPath, 'utf8').toString('base64');
+    const script = [
+        "$ErrorActionPreference='Stop'",
+        "$ProgressPreference='SilentlyContinue'",
+        '[Console]::OutputEncoding=[Text.UTF8Encoding]::new($false)',
+        `$radiocliTaskPath=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPath}'))`,
+        "$radiocliResult=@{taskPath=$radiocliTaskPath;stage='connect';status='error';hresult=0;message=''}",
+        "try{$radiocliService=New-Object -ComObject 'Schedule.Service';$null=$radiocliService.Connect();$radiocliResult.stage='root';$radiocliFolder=$radiocliService.GetFolder('\\');$radiocliResult.stage='lookup';$null=$radiocliFolder.GetTask($radiocliTaskPath);$radiocliResult.status='present'}catch{$radiocliException=$_.Exception;$radiocliResult.message=$radiocliException.ToString();for($radiocliDepth=0;$null -ne $radiocliException.InnerException -and $radiocliDepth -lt 16;$radiocliDepth++){$radiocliException=$radiocliException.InnerException};$radiocliResult.hresult=$radiocliException.HResult}",
+        '[Console]::WriteLine(($radiocliResult | ConvertTo-Json -Compress))',
+        'exit 0'
+    ].join(';');
+    return ['-NoLogo', '-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')];
+}
+function windowsTaskState(result, taskPath) {
+    const unknown = (message) => ({ state: 'unknown', message: `${message} ${windowsCommandMessage(result)}` });
+    if (result.code !== 0)
+        return unknown('Task Scheduler lookup process failed.');
+    let value;
+    try {
+        value = JSON.parse(result.stdout);
+    }
+    catch {
+        return unknown('Malformed Task Scheduler lookup response.');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return unknown('Malformed Task Scheduler lookup response.');
+    const response = value;
+    if (response.taskPath !== taskPath || !['connect', 'root', 'lookup'].includes(String(response.stage)) ||
+        !['present', 'error'].includes(String(response.status)) || typeof response.hresult !== 'number' ||
+        !Number.isInteger(response.hresult) || response.hresult < -2147483648 || response.hresult > 2147483647 || typeof response.message !== 'string') {
+        return unknown('Invalid or unrelated Task Scheduler lookup response.');
+    }
+    if (response.status === 'present' && response.stage === 'lookup' && response.hresult === 0)
+        return { state: 'present', message: 'Task Scheduler job is still registered.' };
+    // HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND / ERROR_PATH_NOT_FOUND), from the
+    // exact GetTask lookup. Never interpret schtasks exit 1 or localized text.
+    if (response.status === 'error' && response.stage === 'lookup' && [-2147024894, -2147024893].includes(response.hresult))
+        return { state: 'absent', message: response.message };
+    return unknown(`Task Scheduler ${response.stage} HRESULT 0x${(response.hresult >>> 0).toString(16).padStart(8, '0')}: ${response.message}`);
+}
+function windowsCommandMessage(result) { return [`exit ${result.code}`, result.stderr.trim(), result.stdout.trim()].filter(Boolean).join(' '); }
+async function boundedWindowsCommand(work, label) {
+    let timer;
+    try {
+        return await Promise.race([Promise.resolve().then(work), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`Task Scheduler ${label} timed out.`)), 10_000); })]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 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 unavailableAdapter(message) {
+    return { ...unsupportedAdapter(message), remove: async () => { throw new Error(message); } };
+}
+function runCommand(command, args) { return new Promise(resolve => { const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, timeout: 10_000 }); 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 })); }); }
+async function boundedProbe(probe) { let timer; try {
+    return await Promise.race([probe, new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('User-manager probe timed out.')), 3_000); })]);
+}
+finally {
+    if (timer)
+        clearTimeout(timer);
+} }
+async function removeWithVerification(remove, query, isAbsent, label) {
+    let failure;
+    try {
+        ensureSuccess(await remove(), `${label} removal`);
+    }
+    catch (error) {
+        failure = error;
+    }
+    if (!failure)
+        return;
+    let result;
+    try {
+        result = await query();
+    }
+    catch (error) {
+        throw new Error(`Unable to verify ${label} removal: ${errorMessage(error)}`);
+    }
+    if (isAbsent(result))
+        return;
+    throw new Error(`Unable to verify ${label} absence; repair artifacts were retained. ${errorMessage(failure)} ${commandMessage(result)}`);
+}
+function commandMessage(result) { return (result.stderr || result.stdout || `exit ${result.code}`).trim(); }
 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 systemdExecCommand(values) {
+    // ':' disables $VAR/${VAR} expansion for ExecStart. Environment= has
+    // different syntax: its dollar signs are already literal and must stay so.
+    return `:${values.map(systemdQuote).join(' ')}`;
+}
 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); }
+function isLaunchdServiceNotFound(result, label) { const output = `${result.stderr}\n${result.stdout}`; const match = /could not find service "([^"]+)" in domain for\b/i.exec(output); return result.code !== 0 && match?.[1] === label; }
 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;

package/dist/alarms/setup-verification.js

@@ -48,7 +48,7 @@ export async function verifyAlarmSetup(scheduler, alarm, settings, onUpdate = ()
             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.`);
+            set('scheduler', 'passed', `Registered and queried a disposable ${capability.name ?? 'native scheduler'} 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
@@ -174,7 +174,6 @@ 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)); }