@ciphore/radiocli 0.2.2 → 0.2.4

package/dist/alarms/guard.js

@@ -2,11 +2,13 @@ import { spawn as nodeSpawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createServer, request } from 'node:http';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AlarmPowerGuardStore } from './power-guard-store.js';
 import { nextOccurrenceForAlarm } from './schedule.js';
 import { defaultAlarmRuntimeDirectory } from './runner.js';
+import { isLoopbackHost, listenLoopback } from '../platform/loopback.js';
+import { identifyPlatform, nativeAdapters } from '../platform/runtime.js';
 export class AlarmGuardService {
     store;
     nodePath;
@@ -41,6 +43,8 @@ export class AlarmGuardService {
         // A recurring alarm may have been edited/rescheduled while its old guard is
         // alive. Stop that exact process tree before replacing its occurrence state.
         await this.stopOwned(alarm.id);
+        if (this.hasOwnershipRecords(alarm.id))
+            throw new Error('Previous Alarm Guard ownership is unresolved; retain the alarm for repair before starting another guard.');
         this.store.request(alarm.id, occurrenceAt);
         const token = randomBytes(32).toString('hex');
         const child = this.spawn(this.nodePath, [this.cliPath, 'alarm', 'internal-guard-run', alarm.id, occurrenceAt, path, token], process.env);
@@ -73,19 +77,19 @@ export class AlarmGuardService {
             return this.withOwnership(alarmId, () => this.stopOwned(alarmId));
         const ids = [...new Set(this.pidFiles().map(readPid).filter((item) => Boolean(item)).map(item => item.alarmId))];
         const results = await Promise.all(ids.map(id => this.withOwnership(id, () => this.stopOwned(id))));
-        return results.every(Boolean);
+        return results.every(Boolean) && !this.hasOwnershipRecords();
     }
     async stopOwned(alarmId) {
         const targets = this.pidFiles()
-            .map(readPid)
-            .filter((item) => Boolean(item))
-            .filter(item => !alarmId || item.alarmId === alarmId);
+            .map(path => ({ path, owner: readPid(path) }))
+            .filter((item) => Boolean(item.owner))
+            .filter(item => !alarmId || item.owner.alarmId === alarmId);
         if (!targets.length)
             return false;
-        for (const current of targets) {
-            const path = this.path(current.alarmId, current.occurrenceAt);
+        for (const { path, owner: current } of targets) {
             if (!(await this.verify(current))) {
-                rmSync(path, { force: true });
+                if (!isAlive(current.pid))
+                    rmSync(path, { force: true });
                 markIfCurrent(this.store, current, 'Guard ownership challenge failed; the PID was not signaled.');
                 continue;
             }
@@ -108,17 +112,28 @@ export class AlarmGuardService {
                 this.store.markReleased(current.alarmId, new Date(), current.occurrenceAt);
             }
         }
-        return targets.every(item => !isAlive(item.pid));
+        return !this.hasOwnershipRecords(alarmId);
     }
     async status() {
         const guards = [];
+        const unresolvedGuards = [];
         for (const path of this.pidFiles()) {
             const pid = readPid(path);
-            if (!pid)
+            if (!pid) {
+                const alarmId = alarmIdFromPath(path);
+                unresolvedGuards.push({ ...(alarmId ? { alarmId } : {}), message: 'Guard ownership metadata cannot be read; its record was retained for repair.' });
                 continue;
+            }
             if (!(await this.verify(pid))) {
-                rmSync(path, { force: true });
-                markIfCurrent(this.store, pid, 'The guard process exited unexpectedly.');
+                if (isAlive(pid.pid)) {
+                    const message = 'Guard ownership cannot be verified; its record was retained and the PID was not signaled.';
+                    unresolvedGuards.push({ alarmId: pid.alarmId, occurrenceAt: pid.occurrenceAt, pid: pid.pid, message });
+                    markIfCurrent(this.store, pid, message);
+                }
+                else {
+                    rmSync(path, { force: true });
+                    markIfCurrent(this.store, pid, 'The guard process exited unexpectedly.');
+                }
                 continue;
             }
             guards.push({ active: true, alarmId: pid.alarmId, occurrenceAt: pid.occurrenceAt, pid: pid.pid });
@@ -126,7 +141,10 @@ export class AlarmGuardService {
         return {
             active: guards.length > 0,
             guards,
-            message: guards.length ? `${guards.length} alarm guard${guards.length === 1 ? ' is' : 's are'} active.` : 'No alarm guard is active.'
+            unresolvedGuards,
+            message: unresolvedGuards.length
+                ? `${guards.length} alarm guards verified active; ${unresolvedGuards.length} ownership records require repair.`
+                : guards.length ? `${guards.length} alarm guard${guards.length === 1 ? ' is' : 's are'} active.` : 'No alarm guard is active.'
         };
     }
     path(alarmId, occurrenceAt) {
@@ -137,6 +155,13 @@ export class AlarmGuardService {
             return [];
         return readdirSync(this.directory).filter(name => name.endsWith('.json')).map(name => join(this.directory, name));
     }
+    hasOwnershipRecords(alarmId) {
+        return this.pidFiles().some(path => {
+            const ownerId = readPid(path)?.alarmId ?? alarmIdFromPath(path);
+            // Unknown records require global repair, but cannot identify this alarm.
+            return !alarmId || ownerId === alarmId;
+        });
+    }
     async withOwnership(alarmId, work) { const lock = join(this.directory, `.lock-${Buffer.from(alarmId).toString('base64url')}`); mkdirSync(this.directory, { recursive: true, mode: 0o700 }); const deadline = Date.now() + 3000; while (true) {
         try {
             mkdirSync(lock, { mode: 0o700 });
@@ -240,7 +265,7 @@ function readPid(path) {
         return undefined;
     try {
         const value = JSON.parse(readFileSync(path, 'utf8'));
-        if (!Number.isInteger(value.pid) || !Number.isInteger(value.port) || value.port < 1 || value.port > 65535 || !value.alarmId || !/^[a-f0-9]{64}$/.test(value.token) || !/(?:Z|[+-]\d{2}:\d{2})$/.test(value.occurrenceAt) || !Number.isFinite(Date.parse(value.occurrenceAt)))
+        if (!Number.isInteger(value.pid) || value.pid < 1 || !Number.isInteger(value.port) || value.port < 1 || value.port > 65535 || typeof value.alarmId !== 'string' || !value.alarmId || (value.host !== undefined && !isLoopbackHost(value.host)) || !/^[a-f0-9]{64}$/.test(value.token) || !/(?:Z|[+-]\d{2}:\d{2})$/.test(value.occurrenceAt) || !Number.isFinite(Date.parse(value.occurrenceAt)))
             throw new Error();
         return value;
     }
@@ -248,12 +273,20 @@ function readPid(path) {
         return undefined;
     }
 }
+function alarmIdFromPath(path) {
+    const name = basename(path, '.json');
+    const decoded = Buffer.from(name, 'base64url').toString();
+    if (Buffer.from(decoded).toString('base64url') !== name)
+        return undefined;
+    const separator = decoded.indexOf('\0');
+    return separator > 0 ? decoded.slice(0, separator) : undefined;
+}
 function writePrivate(path, value) {
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     const temp = `${path}.tmp-${process.pid}-${randomBytes(6).toString('hex')}`;
     writeFileSync(temp, JSON.stringify(value), { mode: 0o600 });
     renameSync(temp, path);
-    if (process.platform !== 'win32')
+    if (nativeAdapters().posixPermissions)
         chmodSync(path, 0o600);
 }
 function isAlive(pid) {
@@ -261,32 +294,41 @@ function isAlive(pid) {
         process.kill(pid, 0);
         return true;
     }
-    catch {
-        return false;
+    catch (error) {
+        return error.code !== 'ESRCH';
     }
 }
 function ownsArtifact(path, token) {
     return readPid(path)?.token === token;
 }
-async function startGuardControl(path, token, alarmId, occurrenceAt, onStop) { const server = createServer((req, res) => { if (req.headers.authorization !== `Bearer ${token}`) {
-    res.statusCode = 401;
-    res.end('{}');
-    return;
-} if (req.method === 'POST' && req.url === '/stop') {
-    onStop();
-    res.end('{}');
-    return;
-} if (req.method !== 'GET' || req.url !== '/challenge') {
-    res.statusCode = 404;
-    res.end('{}');
-    return;
-} res.setHeader('content-type', 'application/json'); res.end(JSON.stringify({ alarmId, occurrenceAt, pid: process.pid })); }); await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); }); const address = server.address(); if (!address || typeof address === 'string') {
-    server.close();
-    throw new Error('Unable to create Guard ownership endpoint.');
-} writePrivate(path, { alarmId, occurrenceAt, pid: process.pid, port: address.port, token }); return { close: () => new Promise(resolve => server.close(() => resolve())) }; }
+async function startGuardControl(path, token, alarmId, occurrenceAt, onStop) {
+    const server = createServer((req, res) => { if (req.headers.authorization !== `Bearer ${token}`) {
+        res.statusCode = 401;
+        res.end('{}');
+        return;
+    } if (req.method === 'POST' && req.url === '/stop') {
+        onStop();
+        res.end('{}');
+        return;
+    } if (req.method !== 'GET' || req.url !== '/challenge') {
+        res.statusCode = 404;
+        res.end('{}');
+        return;
+    } res.setHeader('content-type', 'application/json'); res.end(JSON.stringify({ alarmId, occurrenceAt, pid: process.pid })); });
+    const close = () => new Promise(resolve => server.close(() => resolve()));
+    try {
+        const { host, port } = await listenLoopback(server);
+        writePrivate(path, { alarmId, occurrenceAt, pid: process.pid, host, port, token });
+        return { close };
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+}
 function challengeGuard(guard) { return callGuard(guard, 'GET', '/challenge', true); }
 function requestGuardStop(guard) { return callGuard(guard, 'POST', '/stop', false); }
-function callGuard(guard, method, path, validateIdentity) { return new Promise(resolve => { const req = request({ host: '127.0.0.1', port: guard.port, path, method, headers: { authorization: `Bearer ${guard.token}` } }, res => { let body = ''; res.on('data', value => body += String(value)); res.on('end', () => { if (!validateIdentity) {
+function callGuard(guard, method, path, validateIdentity) { return new Promise(resolve => { const req = request({ host: guard.host ?? '127.0.0.1', port: guard.port, path, method, agent: false, headers: { authorization: `Bearer ${guard.token}` } }, res => { let body = ''; res.on('data', value => body += String(value)); res.on('end', () => { if (!validateIdentity) {
     resolve(res.statusCode === 200);
     return;
 } try {
@@ -297,9 +339,10 @@ catch {
     resolve(false);
 } }); }); req.once('error', () => resolve(false)); req.setTimeout(500, () => req.destroy()); req.end(); }); }
 export async function terminateGuardTree(pid, ops = { platform: process.platform, isAlive, kill: (target, signal) => process.kill(target, signal), taskkill: taskkillTree, wait: delay }) {
+    const windows = nativeAdapters(identifyPlatform({ platform: ops.platform })).ipc === 'named-pipe';
     // Kill the entire detached tree first on Windows so a dying parent cannot
     // orphan its PowerShell execution-state helper.
-    if (ops.platform === 'win32') {
+    if (windows) {
         await ops.taskkill(pid, false);
     }
     else {
@@ -314,7 +357,7 @@ export async function terminateGuardTree(pid, ops = { platform: process.platform
         await ops.wait(50);
     if (!ops.isAlive(pid))
         return;
-    if (ops.platform === 'win32')
+    if (windows)
         await ops.taskkill(pid, true);
     else {
         // The guard is a detached process-group leader; force-killing the negative

package/dist/alarms/inhibitor.js

@@ -1,34 +1,38 @@
 import { spawn as nodeSpawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { delimiter, join } from 'node:path';
+import { resolveCommandDetails } from '../platform/executables.js';
+import { identifyPlatform, nativeAdapters } from '../platform/runtime.js';
 // The script contains no interpolated data. It keeps one process-level Windows
 // execution-state request alive until the parent terminates it.
 const windowsInhibitorScript = (parentPid) => `$s='[DllImport("kernel32.dll")]public static extern uint SetThreadExecutionState(uint e);';Add-Type -MemberDefinition $s -Name P -Namespace R;[R.P]::SetThreadExecutionState(0x80000001)|Out-Null;try{while(Get-Process -Id ${parentPid} -ErrorAction SilentlyContinue){Start-Sleep -Seconds 2}}finally{[R.P]::SetThreadExecutionState(0x80000000)|Out-Null}`;
 export function createPowerInhibitor(deps = {}) {
     const platform = deps.platform ?? process.platform;
-    const spawn = deps.spawn ?? spawnDetached;
-    const exists = deps.commandExists ?? executableExists;
-    const spec = platform === 'darwin'
+    const env = deps.env ?? process.env;
+    const host = identifyPlatform({ platform, env });
+    const adapter = nativeAdapters(host).inhibitor;
+    const spawn = deps.spawn ?? ((command, args) => spawnDetached(command, args, env));
+    const spec = adapter === 'caffeinate'
         ? { command: 'caffeinate', args: ['-i', '-w', String(process.pid)], message: 'Prevents idle system sleep; the display may sleep.' }
-        : platform === 'linux'
+        : adapter === 'logind'
             ? { command: 'systemd-inhibit', args: ['--what=sleep', '--who=RadioCLI', '--why=Scheduled radio', '--mode=block', 'sh', '-c', 'while kill -0 "$1" 2>/dev/null; do sleep 2; done', 'radiocli-inhibitor', String(process.pid)], message: 'Uses a logind sleep inhibitor; explicit sleep and lid policy may override it.' }
-            : platform === 'win32'
+            : adapter === 'windows'
                 ? { command: 'powershell.exe', args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', windowsInhibitorScript(process.pid)], message: 'Prevents idle system sleep; explicit sleep and lid policy may override it.' }
                 : null;
     let active = false;
-    const supported = Boolean(spec && exists(spec.command));
+    const command = spec ? (deps.commandExists ? (deps.commandExists(spec.command) ? spec.command : null) : resolveCommandDetails(spec.command, { platform, env }).path) : null;
+    const supported = Boolean(command);
+    const message = !spec ? `Power inhibition is unsupported on ${host.id === 'unknown' ? platform : host.id}.` : !command ? `${spec.command} is unavailable; sleep protection cannot be acquired.` : spec.message;
     return {
-        status: () => ({ supported, active, message: spec?.message ?? `Power inhibition is unsupported on ${platform}.` }),
+        status: () => ({ supported, active, message }),
         async acquire(_reason) {
-            if (!spec || !supported)
-                throw new Error(spec?.message ?? `Power inhibition is unsupported on ${platform}.`);
-            const child = spawn(spec.command, spec.args);
-            const exitedEarly = await Promise.race([child.exited.then(() => true), new Promise(resolve => setTimeout(() => resolve(false), 50))]);
+            if (!spec || !command)
+                throw new Error(message);
+            const child = spawn(command, spec.args);
+            const exitedEarly = await exitedWithin(child.exited, 50);
             if (exitedEarly)
                 throw new Error(`${spec.command} exited before sleep inhibition became active.`);
             active = true;
             let released = false;
-            const unexpectedExit = child.exited.then(() => released ? new Promise(() => { }) : new Error(`${spec.command} exited unexpectedly; sleep protection was lost.`));
+            const unexpectedExit = child.exited.then(() => { active = false; return released ? new Promise(() => { }) : new Error(`${spec.command} exited unexpectedly; sleep protection was lost.`); });
             return { unexpectedExit, async release() { if (released)
                     return; released = true; active = false; child.kill('SIGTERM'); if (await exitedWithin(child.exited, 1000))
                     return; child.kill('SIGKILL'); if (!(await exitedWithin(child.exited, 500)))
@@ -36,13 +40,14 @@ export function createPowerInhibitor(deps = {}) {
         }
     };
 }
-function executableExists(command) {
-    if (existsSync(command))
-        return true;
-    return Boolean(process.env.PATH?.split(delimiter).some(path => existsSync(join(path, command)) || (process.platform === 'win32' && existsSync(join(path, `${command}.exe`)))));
-}
-function spawnDetached(command, args) {
-    const child = nodeSpawn(command, args, { stdio: 'ignore', windowsHide: true });
+function spawnDetached(command, args, env) {
+    const child = nodeSpawn(command, args, { env, stdio: 'ignore', windowsHide: true });
     return { pid: child.pid, kill: signal => child.kill(signal), exited: new Promise(resolve => { child.once('exit', resolve); child.once('error', resolve); }) };
 }
-async function exitedWithin(exited, milliseconds) { return Promise.race([exited.then(() => true), new Promise(resolve => setTimeout(() => resolve(false), milliseconds))]); }
+async function exitedWithin(exited, milliseconds) { let timer; try {
+    return await Promise.race([exited.then(() => true), new Promise(resolve => { timer = setTimeout(() => resolve(false), milliseconds); })]);
+}
+finally {
+    if (timer)
+        clearTimeout(timer);
+} }

package/dist/alarms/power-guard-store.js

@@ -1,5 +1,5 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { platformPaths } from '../platform/paths.js';
 import { dirname, join } from 'node:path';
 import { z } from 'zod';
 const instantSchema = z.string()
@@ -123,15 +123,7 @@ export class AlarmPowerGuardStore {
     }
 }
 function defaultAlarmPowerGuardPath() {
-    if (process.env.RADIOCLI_HOME)
-        return join(process.env.RADIOCLI_HOME, 'runtime', 'alarm-power-guards.json');
-    if (process.platform === 'darwin') {
-        return join(homedir(), 'Library', 'Application Support', 'radiocli', 'runtime', 'alarm-power-guards.json');
-    }
-    if (process.platform === 'win32') {
-        return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'RadioCLI', 'runtime', 'alarm-power-guards.json');
-    }
-    return join(process.env.XDG_RUNTIME_DIR ?? join(homedir(), '.local', 'state'), 'radiocli', 'alarm-power-guards.json');
+    return join(platformPaths().alarmRuntime, 'alarm-power-guards.json');
 }
 function validDate(date, label) {
     if (!Number.isFinite(date.getTime()))

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,16 +25,28 @@ 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 = () => { };
     const earlySignal = new Promise(resolve => { resolveEarlySignal = resolve; });
     const unsubscribeSignals = deps.subscribeSignals?.(() => { signalReceived = true; resolveEarlySignal(); onPlaybackSignal(); void deps.player.stop().catch(() => undefined); });
     const finish = (status, message) => ({ status, scheduledAt: scheduledAt.toISOString(), ...(firedAt ? { firedAt: firedAt.toISOString() } : {}), finishedAt: deps.now().toISOString(), ...(message ? { message } : {}) });
+    let action;
+    let keepPlaying = false;
+    let resolveAction = () => { };
+    const actionPromise = new Promise(resolve => { resolveAction = resolve; });
     try {
         if (!alarm || !alarm.enabled)
             return { message: 'Alarm is missing or disabled.' };
@@ -45,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 };
         }
@@ -53,6 +66,22 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
             outcome = finish('missed', 'Alarm was outside its missed-run grace window.');
             return { status: outcome.status, message: outcome.message };
         }
+        const claimingStatus = { alarmId, scheduledAt: scheduledAt.toISOString(), stationName: alarm.station.name, station: alarm.station, startedAt: deps.now().toISOString(), state: 'starting' };
+        const creatingSession = deps.createSession(claimingStatus, {
+            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: 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(() => { });
+        const created = await Promise.race([creatingSession.then(value => ({ value })), earlySignal.then(() => ({ signal: true }))]);
+        if ('signal' in created) {
+            outcome = finish('dismissed', 'Alarm interrupted while local controls were starting.');
+            return { status: 'dismissed', message: outcome.message };
+        }
+        session = created.value;
         const claimed = deps.store.getAlarm(alarmId);
         if (claimed?.enabled && claimed.schedule.type === 'recurring') {
             if (deps.scheduler.syncClaimed)
@@ -60,16 +89,10 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
             else
                 await deps.scheduler.sync(claimed);
         }
-        if (deps.systemVolume)
-            try {
-                systemVolumeLease = await deps.systemVolume.acquireMinimum(alarm.playback.volume);
-                deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: true, active: true, message: systemVolumeLease.message });
-            }
-            catch (error) {
-                deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: false, message: `Alarm will use player volume, but system output could not be raised: ${errorMessage(error)}` });
-            }
         let resolvedStation = alarm.station;
         let lastError;
+        let interactivePreempted = false;
+        let outputPrepared = false;
         const candidates = [alarm.station, alarm.station, alarm.playback.fallbackStation].filter((item) => Boolean(item));
         for (const [candidateIndex, candidate] of candidates.entries()) {
             try {
@@ -78,6 +101,26 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
                     outcome = finish('dismissed', 'Alarm interrupted before playback started.');
                     return { status: 'dismissed', message: outcome.message };
                 }
+                if (!interactivePreempted) {
+                    interactivePreempted = true;
+                    try {
+                        await deps.preemptInteractivePlayback?.();
+                    }
+                    catch (error) {
+                        deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: true, message: `Alarm continued after interactive playback could not be stopped cleanly: ${errorMessage(error)}` });
+                    }
+                }
+                if (!outputPrepared) {
+                    outputPrepared = true;
+                    if (deps.systemVolume)
+                        try {
+                            systemVolumeLease = await deps.systemVolume.acquireMinimum(alarm.playback.volume);
+                            deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: true, active: true, message: systemVolumeLease.message });
+                        }
+                        catch (error) {
+                            deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: false, message: `Alarm will use player volume, but system output could not be raised: ${errorMessage(error)}` });
+                        }
+                }
                 const playPromise = deps.player.play(candidate, resolved.stream.url);
                 const tuned = await Promise.race([playPromise.then(() => ({ played: true })), earlySignal.then(() => ({ signal: true }))]);
                 if ('signal' in tuned || signalReceived) {
@@ -126,32 +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;
-        let action;
-        let keepPlaying = false;
-        let resolveAction = () => { };
-        const actionPromise = new Promise(resolve => { resolveAction = resolve; });
-        const activeStatus = { alarmId, scheduledAt: scheduledAt.toISOString(), stationName: resolvedStation.name, station: resolvedStation, startedAt: startedAt.toISOString(), state: 'playing' };
-        const creatingSession = deps.createSession(activeStatus, {
-            onDismiss: () => { action = 'dismissed'; resolveAction('dismissed'); },
-            onSnooze: minutes => { deps.store.snoozeAlarm(alarmId, new Date(deps.now().getTime() + minutes * 60_000)); preserveNextOverride = true; action = 'snoozed'; resolveAction('snoozed'); },
-            onKeepPlaying: () => { keepPlaying = true; session?.update({ keepPlaying: true }); },
-            onHandoff: () => { preserveSystemVolume = true; action = 'handoff'; resolveAction('handoff'); }
-        });
-        void creatingSession.then(created => { if (signalReceived)
-            void created.close().catch(() => undefined); }).catch(() => { });
-        const created = await Promise.race([creatingSession.then(value => ({ value })), earlySignal.then(() => ({ signal: true }))]);
-        if ('signal' in created) {
-            outcome = finish('dismissed', 'Alarm interrupted while local controls were starting.');
-            return { status: 'dismissed', message: outcome.message };
+        try {
+            deps.store.addRecent(resolvedStation);
         }
-        session = created.value;
-        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 (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)}`);
         }
-        catch { } });
+        const activeStatus = { alarmId, scheduledAt: scheduledAt.toISOString(), stationName: resolvedStation.name, station: resolvedStation, startedAt: startedAt.toISOString(), state: 'playing' };
+        session.update(activeStatus);
+        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();
@@ -194,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();
@@ -209,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();
@@ -233,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)
@@ -250,7 +296,7 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
             }
             catch { }
         try {
-            releaseLock();
+            releaseLock(completeLock);
         }
         catch (error) {
             try {
@@ -258,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()) {
@@ -294,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)) {
@@ -307,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());