@ciphore/radiocli 0.2.3 → 0.2.5

package/dist/alarms/scheduler.js

@@ -8,7 +8,12 @@ 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';
+import { identifyOmarchy } from '../platform/omarchy.js';
 export class SchedulerService {
     adapter;
     now;
@@ -94,7 +99,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 +116,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 +137,34 @@ 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 profile = policy.scheduler === 'systemd' ? identifyOmarchy({ ...deps.omarchy, platform, env, home }) : undefined;
+    const inheritDesktop = profile?.kind === 'quattro' && profile.source === 'package' && profile.packageName === 'omarchy';
+    const detectedTerminal = detectGraphicalTerminal(platform, env, undefined, deps.omarchy);
+    // A job registered over SSH may next run inside UWSM's live desktop. Do not
+    // turn the registration-time absence of a display into a permanent selector.
+    const configuredTerminal = env.RADIOCLI_ALARM_TERMINAL?.trim();
+    const terminal = inheritDesktop && detectedTerminal.endsWith(':unsupported') ? configuredTerminal || undefined : detectedTerminal;
+    const common = { platform, home, nodePath, cliPath, env, inheritDesktop, terminal, 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, inheritDesktop: common.inheritDesktop, 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 +180,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 +222,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), { inheritDesktop: common.inheritDesktop })); 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)); }

package/dist/alarms/system-volume-linux.js

@@ -0,0 +1,160 @@
+/** Never persist or mutate a default-sink alias: it can change during an alarm. */
+export function linuxVolumeBackend(run, resolve) {
+    const wpctl = resolve('wpctl');
+    if (wpctl) {
+        const identity = async (id) => {
+            const [status, detail] = await Promise.all([
+                checked(run(wpctl, ['status']), 'identify the PipeWire server'),
+                checked(run(wpctl, ['inspect', id]), 'identify the PipeWire output')
+            ]);
+            const server = /^PipeWire .+cookie:\s*(\d{1,20})\]/m.exec(status)?.[1];
+            const node = /^id (\d{1,20}), type PipeWire:Interface:Node\s*$/m.exec(detail)?.[1];
+            const property = (name) => new RegExp(`^\\s*\\*?\\s*${name.replaceAll('.', '\\.')} = "([^"\\r\\n]+)"\\s*$`, 'm').exec(detail)?.[1];
+            const serial = property('object.serial');
+            const name = property('node.name');
+            if (!server || !node || !serial || !/^\d{1,20}$/.test(serial) || !validName(name) || property('media.class') !== 'Audio/Sink')
+                throw new Error('PipeWire returned an unreadable output identity; no default-output mutation is safe.');
+            return { kind: 'pipewire', server, id: node, serial, name };
+        };
+        const verify = async (output) => {
+            if (!output || output.kind === 'pulse')
+                throw changedOutput();
+            const id = output.kind === 'pipewire' ? output.id : output.nodeId;
+            const current = await identity(id);
+            if (current.server !== output.server || current.id !== id || current.serial !== output.serial || current.name !== output.name)
+                throw changedOutput();
+            return id;
+        };
+        return {
+            select: () => identity('@DEFAULT_AUDIO_SINK@'),
+            async read(output) {
+                const id = await verify(output);
+                const text = await checked(run(wpctl, ['get-volume', id]), 'read PipeWire output volume');
+                const match = /Volume:\s*(\d+(?:\.\d+)?)(?:\s|$)/i.exec(text);
+                if (!match)
+                    throw new Error('wpctl returned an unreadable output-volume state.');
+                await verify(output);
+                return { volume: clamp(Number(match[1]) * 100), muted: /\[MUTED\]/i.test(text) };
+            },
+            async write(value, execute = run, output) {
+                const id = await verify(output);
+                await checked(execute(wpctl, ['set-volume', id, `${clamp(value.volume)}%`]), 'set PipeWire output volume');
+                // A hot-unplug between the two commands must not unmute a reused ID.
+                await verify(output);
+                await checked(execute(wpctl, ['set-mute', id, value.muted ? '1' : '0']), 'set PipeWire mute state');
+            }
+        };
+    }
+    const pactl = resolve('pactl');
+    if (pactl) {
+        // The C-locale textual interface also supports PulseAudio versions predating
+        // pactl's JSON output. Its public server cookie changes across restarts.
+        const info = async () => {
+            const text = await checked(run(pactl, ['info']), 'identify the PulseAudio server');
+            const server = /^Cookie:\s*([\da-f]+(?::[\da-f]+)*)\s*$/im.exec(text)?.[1]?.toLowerCase();
+            const name = /^Default Sink:\s*(.+)\s*$/m.exec(text)?.[1]?.trim();
+            if (!validName(server))
+                throw new Error('PulseAudio returned an unreadable server identity; no default-output mutation is safe.');
+            const pipewire = /^Server Name: PulseAudio \(on PipeWire [\w.+-]+\)\s*$/m.test(text);
+            const cookie = /^([\da-f]{1,4}):([\da-f]{1,4})$/.exec(server);
+            if (pipewire && !cookie)
+                throw new Error('PulseAudio returned an unreadable PipeWire server cookie.');
+            // PipeWire's Pulse server exposes the same core cookie as wpctl, rendered
+            // as two hexadecimal words. Classic PulseAudio stays in a separate domain.
+            return { pipewire, server: pipewire ? Number.parseInt(`${cookie[1].padStart(4, '0')}${cookie[2].padStart(4, '0')}`, 16).toString() : server, name: validName(name) ? name : undefined };
+        };
+        const sinks = async (server) => {
+            const text = await checked(run(pactl, server.pipewire ? ['list', 'sinks'] : ['list', 'short', 'sinks']), 'identify PulseAudio outputs');
+            const outputs = server.pipewire ? parsePipeWireSinks(text, server.server) : text.split(/\r?\n/).filter(Boolean).map(line => {
+                const [id, name] = line.split('\t');
+                if (!id || !/^\d{1,20}$/.test(id) || !validName(name))
+                    throw new Error('PulseAudio returned an unreadable output identity.');
+                return { kind: 'pulse', server: server.server, id, name };
+            });
+            if (new Set(outputs.map(item => item.id)).size !== outputs.length || new Set(outputs.map(item => item.name)).size !== outputs.length)
+                throw new Error('PulseAudio returned ambiguous output identities.');
+            return outputs;
+        };
+        const verify = async (output) => {
+            if (!output)
+                throw changedOutput();
+            const server = await info();
+            const outputs = await sinks(server);
+            if (server.server !== output.server)
+                throw changedOutput();
+            const current = outputs.find(item => {
+                if (output.kind === 'pulse')
+                    return item.kind === 'pulse' && item.id === output.id && item.name === output.name;
+                if (item.kind !== 'pulse-pipewire' || item.serial !== output.serial || item.name !== output.name)
+                    return false;
+                return output.kind === 'pipewire' ? item.nodeId === output.id : item.nodeId === output.nodeId && item.id === output.id && item.sinkName === output.sinkName;
+            });
+            if (!current)
+                throw changedOutput();
+            return current.id;
+        };
+        return {
+            async select() {
+                const server = await info();
+                const outputs = await sinks(server);
+                const output = outputs.find(item => (item.kind === 'pulse-pipewire' ? item.sinkName : item.name) === server.name);
+                if (!output)
+                    throw new Error('The default PulseAudio output is unavailable.');
+                return output;
+            },
+            async read(output) {
+                const id = await verify(output);
+                const [volume, mute] = await Promise.all([
+                    checked(run(pactl, ['get-sink-volume', id]), 'read PulseAudio output volume'),
+                    checked(run(pactl, ['get-sink-mute', id]), 'read PulseAudio mute state')
+                ]);
+                const match = /(\d+)%/.exec(volume);
+                const muted = /^Mute:\s*(yes|no)\s*$/im.exec(mute);
+                if (!match || !muted)
+                    throw new Error('pactl returned an unreadable output-volume state.');
+                await verify(output);
+                return { volume: clamp(Number(match[1])), muted: muted[1].toLowerCase() === 'yes' };
+            },
+            async write(value, execute = run, output) {
+                const id = await verify(output);
+                await checked(execute(pactl, ['set-sink-volume', id, `${clamp(value.volume)}%`]), 'set PulseAudio output volume');
+                await verify(output);
+                await checked(execute(pactl, ['set-sink-mute', id, value.muted ? '1' : '0']), 'set PulseAudio mute state');
+            }
+        };
+    }
+    const amixer = resolve('amixer');
+    if (amixer)
+        return {
+            async read() {
+                const text = await checked(run(amixer, ['get', 'Master']), 'read ALSA output volume');
+                const last = [...text.matchAll(/\[(\d+)%\]/g)].at(-1);
+                if (!last)
+                    throw new Error('amixer returned an unreadable output-volume state.');
+                return { volume: clamp(Number(last[1])), muted: /\[off\]/i.test(text) };
+            },
+            async write(value, execute = run) { await checked(execute(amixer, ['set', 'Master', `${clamp(value.volume)}%`, value.muted ? 'mute' : 'unmute']), 'set ALSA output volume'); }
+        };
+    return undefined;
+}
+function parsePipeWireSinks(text, server) {
+    if (!text.trim())
+        return [];
+    return text.split(/(?=^Sink #)/m).filter(block => block.trim()).map(block => {
+        const id = /^Sink #(\d{1,20})\s*$/m.exec(block)?.[1];
+        const sinkName = /^\s+Name:\s*(.+)\s*$/m.exec(block)?.[1]?.trim();
+        const property = (name) => new RegExp(`^\\s+${name.replaceAll('.', '\\.')} = "([^"\\r\\n]+)"\\s*$`, 'm').exec(block)?.[1];
+        const nodeId = property('object.id');
+        const serial = property('object.serial');
+        const name = property('node.name');
+        if (!id || !nodeId || !/^\d{1,20}$/.test(nodeId) || !serial || !/^\d{1,20}$/.test(serial) || !validName(name) || !validName(sinkName))
+            throw new Error('PulseAudio returned an unreadable PipeWire output identity.');
+        return { kind: 'pulse-pipewire', server, id, nodeId, serial, name, sinkName };
+    });
+}
+function changedOutput() { return new Error('The original alarm output disconnected or its audio-server identity changed. Its saved volume was retained; no replacement output was changed.'); }
+function validName(value) { return typeof value === 'string' && value.length > 0 && value.length <= 1024 && !/[\u0000-\u001f\u007f]/.test(value); }
+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()}`); if (Buffer.byteLength(result.stdout) > 64 * 1024)
+    throw new Error(`${label} returned too much data.`); return result.stdout; }