@ciphore/radiocli 0.2.3 → 0.2.5

package/dist/alarms/active-session.js

@@ -1,8 +1,9 @@
 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 { homedir } from 'node:os';
+import { platformPaths } from '../platform/paths.js';
 import { dirname, join } from 'node:path';
+import { isLoopbackHost, listenLoopback } from '../platform/loopback.js';
 export async function startActiveAlarmSession(initial, handlers) {
     const filePath = handlers.filePath ?? defaultActiveAlarmPath(initial.alarmId, initial.scheduledAt);
     const token = randomBytes(32).toString('hex');
@@ -85,11 +86,8 @@ export async function startActiveAlarmSession(initial, handlers) {
             res.end(JSON.stringify({ error: error instanceof Error ? error.message : 'request failed' }));
         }
     });
-    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')
-        throw new Error('Unable to create alarm control endpoint.');
-    const discovery = { version: 1, host: '127.0.0.1', port: address.port, token, pid: process.pid, alarmId: initial.alarmId, createdAt: new Date().toISOString() };
+    const address = await listenLoopback(server);
+    const discovery = { version: 1, host: address.host, port: address.port, token, pid: process.pid, alarmId: initial.alarmId, createdAt: new Date().toISOString() };
     const temp = `${filePath}.tmp-${process.pid}-${randomBytes(6).toString('hex')}`;
     try {
         mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
@@ -116,13 +114,15 @@ export async function connectActiveAlarm(filePath) {
     let discovery;
     try {
         discovery = JSON.parse(readFileSync(filePath, 'utf8'));
-        if (discovery.version !== 1 || discovery.host !== '127.0.0.1' || !Number.isInteger(discovery.port) || !discovery.token)
+        if (discovery.version !== 1 || !isLoopbackHost(discovery.host) || !Number.isInteger(discovery.port) || !discovery.token)
             throw new Error('invalid');
     }
     catch {
         return null;
     }
-    const call = async (method, path, body) => { const payload = body === undefined ? '' : JSON.stringify(body); return new Promise((resolve, reject) => { const req = request({ host: '127.0.0.1', port: discovery.port, path, method, headers: { authorization: `Bearer ${discovery.token}`, 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) } }, res => { let text = ''; res.on('data', value => text += String(value)); res.on('end', () => res.statusCode && res.statusCode < 300 ? resolve(text ? JSON.parse(text) : {}) : reject(new Error('Alarm control request failed.'))); }); req.once('error', reject); req.setTimeout(1000, () => req.destroy(new Error('Alarm control request timed out.'))); req.end(payload); }); };
+    // A fresh direct agent keeps local control tokens out of environment proxies.
+    // Handoff can wait for the shared output lock (30s); discovery keeps its short deadline.
+    const call = async (method, path, body) => { const payload = body === undefined ? '' : JSON.stringify(body); return new Promise((resolve, reject) => { const req = request({ host: discovery.host, agent: false, port: discovery.port, path, method, headers: { authorization: `Bearer ${discovery.token}`, 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) } }, res => { let text = ''; res.on('data', value => text += String(value)); res.on('end', () => res.statusCode && res.statusCode < 300 ? resolve(text ? JSON.parse(text) : {}) : reject(new Error('Alarm control request failed.'))); }); req.once('error', reject); req.setTimeout(path === '/handoff' ? 35_000 : 1000, () => req.destroy(new Error('Alarm control request timed out.'))); req.end(payload); }); };
     try {
         await call('GET', '/status');
     }
@@ -135,10 +135,7 @@ export async function connectActiveAlarm(filePath) {
 }
 export async function connectActiveAlarms(directory = defaultActiveAlarmDirectory()) { if (!existsSync(directory))
     return []; const paths = readdirSync(directory).filter(name => name.endsWith('.json')).map(name => join(directory, name)); const clients = await Promise.all(paths.map(path => connectActiveAlarm(path))); return clients.filter((client) => Boolean(client)); }
-function defaultActiveAlarmDirectory() { if (process.env.RADIOCLI_HOME)
-    return join(process.env.RADIOCLI_HOME, 'runtime', 'active-alarms'); if (process.platform === 'darwin')
-    return join(homedir(), 'Library', 'Application Support', 'radiocli', 'runtime', 'active-alarms'); if (process.platform === 'win32')
-    return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'RadioCLI', 'runtime', 'active-alarms'); return join(process.env.XDG_RUNTIME_DIR ?? join(homedir(), '.local', 'state'), 'radiocli', 'active-alarms'); }
+function defaultActiveAlarmDirectory() { return join(platformPaths().alarmRuntime, 'active-alarms'); }
 function defaultActiveAlarmPath(alarmId = 'active', occurrenceAt = 'current') { return join(defaultActiveAlarmDirectory(), `${Buffer.from(`${alarmId}\0${occurrenceAt}`).toString('base64url')}.json`); }
 function readBody(req) { return new Promise((resolve, reject) => { let body = ''; req.on('data', value => { body += String(value); if (body.length > 4096)
     req.destroy(new Error('Request too large.')); }); req.on('end', () => resolve(body)); req.on('error', reject); }); }

package/dist/alarms/cli.js

@@ -1,5 +1,7 @@
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { LibraryRepository } from '../storage/repository.js';
+import { matchesStationId } from '../storage/station-identity.js';
 import { JsonLibraryStore, stationKey } from '../storage/store.js';
 import { ProviderManager } from '../providers/provider-manager.js';
 import { PlayerController } from '../player/player-controller.js';
@@ -74,6 +76,7 @@ export async function runAlarmCommand(args, dependencies = {}) {
     if (sub === 'remove') {
         const id = requiredPos(rest, 0);
         requireAlarm(store, id);
+        store.toggleAlarm(id, false);
         await scheduler.remove(id);
         if (!store.removeAlarm(id))
             throw new Error(`Alarm not found: ${id}`);
@@ -157,7 +160,13 @@ export async function runAlarmCommand(args, dependencies = {}) {
     if (sub === 'internal-run') {
         const id = requiredPos(rest, 0);
         const at = requiredPos(rest, 1);
-        await runAlarm(id, at, createRuntimeDeps(store, scheduler, id));
+        const repository = new LibraryRepository(store, { worker: !dependencies.store });
+        try {
+            await runAlarm(id, at, createRuntimeDeps(repository, scheduler, id));
+        }
+        finally {
+            await repository.close();
+        }
         return;
     }
     if (sub === 'internal-launchd') {
@@ -165,7 +174,13 @@ export async function runAlarmCommand(args, dependencies = {}) {
         const at = requiredPos(rest, 1);
         if (!shouldRunLaunchdOccurrence(at, new Date()))
             return;
-        await runAlarm(id, at, createRuntimeDeps(store, scheduler, id));
+        const repository = new LibraryRepository(store, { worker: !dependencies.store });
+        try {
+            await runAlarm(id, at, createRuntimeDeps(repository, scheduler, id));
+        }
+        finally {
+            await repository.close();
+        }
         return;
     }
     if (sub === 'internal-guard-run') {
@@ -238,7 +253,8 @@ function parseDays(value) { if (value === 'daily')
     return [1, 2, 3, 4, 5, 6, 7]; if (value === 'weekdays')
     return [1, 2, 3, 4, 5]; if (value === 'weekends')
     return [6, 7]; return canonicalizeIsoWeekdays(value.split(',').map(Number)); }
-function resolveStation(store, key) { const state = store.snapshot(); const stations = [...state.favorites, ...state.imported, ...state.recent.map(item => item.station), ...state.alarms.flatMap(alarm => [alarm.station, ...(alarm.playback.fallbackStation ? [alarm.playback.fallbackStation] : [])])]; const station = stations.find(item => stationKey(item) === key); if (!station)
+function resolveStation(store, key) { const state = store.snapshot(); const stations = [...state.favorites, ...state.imported, ...state.recent.map(item => item.station), ...state.alarms.flatMap(alarm => [alarm.station, ...(alarm.playback.fallbackStation ? [alarm.playback.fallbackStation] : [])])]; const matches = new Map(stations.filter(item => matchesStationId(item, key)).map(item => [stationKey(item), item])); if (matches.size > 1)
+    throw new Error('This legacy station ID is ambiguous. List stations and use the current ID.'); const station = [...matches.values()][0]; if (!station)
     throw new Error(`Station not found: ${key}. Add it to favorites/imports/recents first.`); return station; }
 function parseOptions(args) { const allowed = new Set(['station', 'once', 'time', 'days', 'timezone', 'label', 'volume', 'fade', 'stop-after', 'fallback', 'grace', 'disabled', 'wake', 'no-wake', 'guard', 'no-guard', 'clear-fallback']); const values = new Map(); const positionals = []; for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];

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/occurrence-cache.js

@@ -0,0 +1,25 @@
+import { nextOccurrenceForAlarm } from './schedule.js';
+/** Reuse civil-time work until its result expires; clock reversals invalidate it. */
+export class AlarmOccurrenceCache {
+    limit;
+    entries = new Map();
+    constructor(limit = 512) {
+        this.limit = limit;
+    }
+    next(alarm, now) {
+        const time = now.getTime();
+        const fingerprint = JSON.stringify([alarm.enabled, alarm.schedule, alarm.nextOverride?.at]);
+        const cached = this.entries.get(alarm.id);
+        if (cached && cached.fingerprint === fingerprint && time >= cached.computedAt && (cached.at === null || cached.at > time)) {
+            this.entries.delete(alarm.id);
+            this.entries.set(alarm.id, cached);
+            return cached.at === null ? null : new Date(cached.at);
+        }
+        const occurrence = nextOccurrenceForAlarm(alarm, now);
+        this.entries.delete(alarm.id);
+        this.entries.set(alarm.id, { fingerprint, computedAt: time, at: occurrence?.getTime() ?? null });
+        while (this.entries.size > this.limit)
+            this.entries.delete(this.entries.keys().next().value);
+        return occurrence;
+    }
+}

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()))