@ciphore/radiocli 0.2.3 → 0.2.5

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

@@ -0,0 +1,335 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+/** The output device belongs to the OS account, not a RADIOCLI_HOME/XDG profile. */
+export function defaultSystemVolumeDirectory() {
+    const home = userInfo().homedir;
+    if (!home || !isAbsolute(home))
+        throw new Error('The OS account home is unavailable for shared output-volume ownership.');
+    return join(home, '.radiocli', 'system-volume');
+}
+/** One short transaction covers both the saved baseline and native mixer writes. */
+export class SystemVolumeOwnership {
+    directory;
+    timeoutMs;
+    output;
+    constructor(directory, timeoutMs = 30_000, output) {
+        this.directory = directory;
+        this.timeoutMs = timeoutMs;
+        this.output = output;
+    }
+    async transaction(work) {
+        const release = await this.lock();
+        try {
+            return await work();
+        }
+        finally {
+            release();
+        }
+    }
+    read() {
+        const value = this.readDocument();
+        if (!value)
+            return undefined;
+        if (value.version === 1) {
+            if (!this.output)
+                return value;
+            this.checkLegacy(value);
+            return undefined;
+        }
+        if (!this.output)
+            throw new Error('Saved output-volume ownership belongs to an identified Linux audio device; its recovery state was left intact.');
+        return value.outputs.find(item => sameOutput(item.identity, this.output))?.lease;
+    }
+    /** Enumerate other recovery records while holding the shared root lock. */
+    otherOutputs() {
+        const value = this.readDocument();
+        return this.output && value?.version === 2 ? value.outputs.map(item => item.identity).filter(identity => !sameOutput(identity, this.output)) : [];
+    }
+    readDocument() {
+        let text;
+        try {
+            text = readFileSync(join(this.directory, 'state.json'), 'utf8');
+        }
+        catch (error) {
+            if (codeOf(error) === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+        try {
+            const value = JSON.parse(text);
+            if (value?.version === 2) {
+                if (!Array.isArray(value.outputs) || value.outputs.length > 128 || !value.outputs.every(item => item && validOutput(item.identity) && validLease(item.lease)) || new Set(value.outputs.map(item => outputKey(item.identity))).size !== value.outputs.length)
+                    throw new Error();
+            }
+            else if (!validLease(value))
+                throw new Error();
+            return value;
+        }
+        catch {
+            throw new Error('Shared output-volume ownership state is unreadable; the saved output state was left intact.');
+        }
+    }
+    save(value) {
+        if (!this.output) {
+            this.writeDocument(value);
+            return;
+        }
+        const existing = this.readDocument();
+        if (existing?.version === 1)
+            this.checkLegacy(existing);
+        const outputs = existing?.version === 2 ? existing.outputs.filter(item => !sameOutput(item.identity, this.output)) : [];
+        if (outputs.length >= 128)
+            throw new Error('Too many unresolved output-volume recovery records; saved output states were retained.');
+        this.writeDocument({ version: 2, outputs: [...outputs, { identity: this.output, lease: value }] });
+    }
+    writeDocument(value) {
+        const temporary = join(this.directory, `.state-${process.pid}-${randomUUID()}`);
+        try {
+            writeFileSync(temporary, JSON.stringify(value), { mode: 0o600, flag: 'wx' });
+            renameSync(temporary, join(this.directory, 'state.json'));
+        }
+        catch (error) {
+            try {
+                rmSync(temporary, { force: true });
+            }
+            catch { }
+            throw error;
+        }
+    }
+    clear() {
+        if (this.output) {
+            const value = this.readDocument();
+            if (value?.version === 1)
+                this.checkLegacy(value);
+            if (value?.version === 2) {
+                const outputs = value.outputs.filter(item => !sameOutput(item.identity, this.output));
+                if (outputs.length) {
+                    this.writeDocument({ version: 2, outputs });
+                    return;
+                }
+            }
+        }
+        try {
+            unlinkSync(join(this.directory, 'state.json'));
+        }
+        catch (error) {
+            if (codeOf(error) !== 'ENOENT')
+                throw error;
+        }
+    }
+    checkLegacy(value) {
+        // Older Linux jobs recorded only the default sink's volume. That baseline
+        // cannot safely be assigned to whichever device happens to be default now.
+        if (value.changed || value.participants.some(item => item.phase === 'active' && volumeProcessAlive(item.pid)))
+            throw new Error('An earlier alarm saved output-volume ownership without a device identity. Finish its active alarms or repair the saved state.json after checking the original output; the saved state was retained and no output was changed.');
+    }
+    /** A null PID is intentional: a crash before PID persistence is ambiguous. */
+    beginNativeWrite() { this.saveNativeWrite(null); }
+    recordNativeWritePid(pid) { if (!validPid(pid))
+        throw new Error('The system-output helper did not report a valid process ID.'); this.saveNativeWrite(pid); }
+    finishNativeWrite() { try {
+        unlinkSync(join(this.directory, 'native-write.json'));
+    }
+    catch (error) {
+        if (codeOf(error) !== 'ENOENT')
+            throw error;
+    } }
+    saveNativeWrite(helperPid) {
+        const temporary = join(this.directory, `.native-write-${process.pid}-${randomUUID()}`);
+        try {
+            writeFileSync(temporary, JSON.stringify({ version: 1, ownerPid: process.pid, helperPid }), { mode: 0o600, flag: 'wx' });
+            renameSync(temporary, join(this.directory, 'native-write.json'));
+        }
+        catch (error) {
+            try {
+                rmSync(temporary, { force: true });
+            }
+            catch { }
+            throw error;
+        }
+    }
+    nativeWriteSettled() {
+        const path = join(this.directory, 'native-write.json');
+        let value;
+        try {
+            value = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch (error) {
+            if (codeOf(error) === 'ENOENT')
+                return true;
+            throw this.unknownNativeWrite(path);
+        }
+        if (value?.version !== 1 || !validPid(value.ownerPid) || !validPid(value.helperPid))
+            throw this.unknownNativeWrite(path);
+        if (volumeProcessAlive(value.helperPid))
+            return false;
+        // Removal is only allowed after acquiring the lock, so an old observer
+        // cannot remove a newer owner's journal.
+        this.finishNativeWrite();
+        return true;
+    }
+    unknownNativeWrite(path) { return new Error(`An interrupted system-output helper could not be identified; the saved volume was retained. Restart the computer, then remove ${path} before retrying system output control.`); }
+    async waitForNativeWrite(deadline) { while (!this.nativeWriteSettled()) {
+        if (Date.now() >= deadline)
+            throw new Error('A system-output helper is still running; the saved volume will be recovered after it exits.');
+        await pause();
+    } }
+    async lock() {
+        mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        const marker = `owner-${process.pid}-${randomUUID()}`;
+        const candidate = join(this.directory, `.lock-${marker}`);
+        const lock = join(this.directory, 'lock');
+        mkdirSync(candidate, { mode: 0o700 });
+        let published = false;
+        try {
+            writeFileSync(join(candidate, marker), '', { mode: 0o600, flag: 'wx' });
+            const deadline = Date.now() + this.timeoutMs;
+            while (true) {
+                let acquired = false;
+                try {
+                    renameSync(candidate, lock);
+                    published = true;
+                    acquired = true;
+                }
+                catch (error) {
+                    if (!['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES'].includes(codeOf(error) ?? ''))
+                        throw error;
+                }
+                if (acquired) {
+                    try {
+                        await this.waitForNativeWrite(deadline);
+                    }
+                    catch (error) {
+                        finishLock(lock, marker);
+                        throw error;
+                    }
+                    return () => finishLock(lock, marker);
+                }
+                if (Date.now() >= deadline)
+                    throw new Error('Shared output-volume ownership is busy; its live owner was left intact.');
+                let owners;
+                try {
+                    owners = readdirSync(lock);
+                }
+                catch (error) {
+                    if (codeOf(error) === 'ENOENT') {
+                        await pause();
+                        continue;
+                    }
+                    throw error;
+                }
+                if (owners.length === 0) {
+                    removeEmptyLock(lock);
+                    continue;
+                }
+                const owner = owners[0];
+                const match = /^(owner|released)-([1-9]\d*)-([a-f\d-]{36})$/.exec(owner);
+                if (owners.length !== 1 || !match || !validPid(Number(match[2])) || !validId(match[3]))
+                    throw new Error('Shared output-volume ownership lock is unreadable; it was left intact.');
+                if (match[1] === 'released' || !volumeProcessAlive(Number(match[2]))) {
+                    // Claim this exact dead generation, never rename/remove a replacement
+                    // lock directory. A reaper that dies is recovered by the same protocol.
+                    const reaper = `owner-${process.pid}-${randomUUID()}`;
+                    try {
+                        renameSync(join(lock, owner), join(lock, reaper));
+                    }
+                    catch (error) {
+                        if (codeOf(error) === 'ENOENT')
+                            continue;
+                        throw error;
+                    }
+                    try {
+                        await this.waitForNativeWrite(deadline);
+                    }
+                    catch (error) {
+                        try {
+                            renameSync(join(lock, reaper), join(lock, owner));
+                        }
+                        catch {
+                            finishLock(lock, reaper);
+                        }
+                        throw error;
+                    }
+                    finishLock(lock, reaper);
+                    await pause();
+                    continue;
+                }
+                await pause();
+            }
+        }
+        finally {
+            if (!published)
+                try {
+                    rmSync(candidate, { recursive: true, force: true });
+                }
+                catch { }
+        }
+    }
+}
+export function volumeProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return codeOf(error) !== 'ESRCH';
+    }
+}
+function finishLock(directory, marker) {
+    const released = `released-${process.pid}-${randomUUID()}`;
+    try {
+        renameSync(join(directory, marker), join(directory, released));
+    }
+    catch {
+        try {
+            removeOwnedLock(directory, marker);
+        }
+        catch { }
+        return;
+    }
+    // Do not lose a returned lease or replace a mixer failure with cleanup errors.
+    // A published completion can be reclaimed even while this PID remains alive.
+    try {
+        removeOwnedLock(directory, released);
+    }
+    catch { }
+}
+function removeOwnedLock(directory, marker) {
+    try {
+        unlinkSync(join(directory, marker));
+    }
+    catch (error) {
+        if (codeOf(error) === 'ENOENT')
+            return;
+        throw error;
+    }
+    removeEmptyLock(directory);
+}
+function removeEmptyLock(directory) {
+    // Another process may already have published a new nonempty generation.
+    try {
+        rmdirSync(directory);
+    }
+    catch (error) {
+        if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(codeOf(error) ?? ''))
+            throw error;
+    }
+}
+function validPid(value) { return Number.isSafeInteger(value) && Number(value) > 0; }
+function validId(value) { return typeof value === 'string' && /^[a-f\d]{8}(?:-[a-f\d]{4}){3}-[a-f\d]{12}$/.test(value); }
+function validSnapshot(value) { if (!value || typeof value !== 'object')
+    return false; const state = value; return Number.isInteger(state.volume) && state.volume >= 0 && state.volume <= 100 && typeof state.muted === 'boolean'; }
+function validLease(value) { if (!value || typeof value !== 'object')
+    return false; const state = value; return state.version === 1 && validId(state.generation) && typeof state.changed === 'boolean' && (state.baseline === null ? !state.changed : validSnapshot(state.baseline)) && Array.isArray(state.participants) && state.participants.every(item => item && validId(item.id) && validPid(item.pid) && (item.phase === 'pending' || item.phase === 'active')) && new Set(state.participants.map(item => item.id)).size === state.participants.length; }
+function validOutput(value) { if (!value || typeof value !== 'object')
+    return false; const output = value; return ['pipewire', 'pulse', 'pulse-pipewire'].includes(output.kind) && validLabel(output.server) && validLabel(output.name) && decimalId(output.id) && (output.kind === 'pulse' || decimalId(output.serial)) && (output.kind !== 'pulse-pipewire' || decimalId(output.nodeId) && validLabel(output.sinkName)); }
+function validLabel(value) { return typeof value === 'string' && value.length > 0 && value.length <= 1024 && !/[\u0000-\u001f\u007f]/.test(value); }
+function decimalId(value) { return typeof value === 'string' && /^\d{1,20}$/.test(value); }
+// The PipeWire core, object serial and name identify a sink across both CLIs.
+// Backend-specific IDs remain in the record for independent mutation checks.
+function outputKey(value) { return JSON.stringify(value.kind === 'pulse' ? ['pulse', value.server, value.id, value.name] : ['pipewire', value.server, value.serial, value.name]); }
+function sameOutput(first, second) { return outputKey(first) === outputKey(second); }
+function codeOf(error) { return error?.code; }
+function pause() { return new Promise(resolve => setTimeout(resolve, 20)); }

package/dist/alarms/system-volume.js

@@ -1,33 +1,133 @@
 import { spawn } from 'node:child_process';
-import { resolveCommand } from '../player/command.js';
-export function createSystemVolumeController(platform = process.platform, run = runCommand, resolve = resolveCommand) {
-    const backend = platform === 'darwin' ? macBackend(run) : platform === 'linux' ? linuxBackend(run, resolve) : platform === 'win32' ? windowsBackend(run, resolve) : undefined;
-    return { async acquireMinimum(volume) { if (!backend)
-            throw new Error(`System output volume control is unavailable on ${platform}.`); const target = clamp(volume); const before = await backend.read(); const applied = Math.max(before.volume, target); if (before.muted || before.volume < target)
-            await backend.write({ volume: applied, muted: false }); let released = false; return { message: before.muted || before.volume < target ? `Local output raised to at least ${target}% and unmuted for the alarm.` : `Local output was already at least ${target}% and unmuted.`, async release() { if (released)
-                return; released = true; if (before.muted || before.volume < target)
-                await backend.write(before); } }; } };
+import { randomUUID } from 'node:crypto';
+import { resolveCommand } from '../platform/executables.js';
+import { identifyPlatform, nativeAdapters } from '../platform/runtime.js';
+import { defaultSystemVolumeDirectory, SystemVolumeOwnership, volumeProcessAlive } from './system-volume-ownership.js';
+import { linuxVolumeBackend } from './system-volume-linux.js';
+export function createSystemVolumeController(platform = process.platform, run = runCommand, resolve = resolveCommand, options = {}) {
+    const host = identifyPlatform({ platform });
+    const adapter = nativeAdapters(host).volume;
+    const backend = adapter === 'macos' ? macBackend(run) : adapter === 'unix-audio' ? linuxVolumeBackend(run, resolve) : adapter === 'windows' ? windowsBackend(run, resolve) : undefined;
+    return { async acquireMinimum(volume) {
+            if (!backend)
+                throw new Error(`System output volume control is unavailable on ${host.id === 'unknown' ? platform : host.id}.`);
+            const output = await backend.select?.();
+            const directory = options.directory ?? defaultSystemVolumeDirectory();
+            const ownership = new SystemVolumeOwnership(directory, options.lockTimeoutMs, output);
+            const execute = run === runCommand ? (command, args) => runCommand(command, args, ownership) : run;
+            const write = (value) => backend.write(value, execute, output);
+            return ownership.transaction(async () => {
+                let state = ownership.read();
+                let pendingRecovery = 0;
+                // Recover dead owners on their still-connected original outputs even if
+                // the default has moved. An unplugged output remains repairable without
+                // preventing a different output from ringing.
+                for (const identity of ownership.otherOutputs()) {
+                    const priorOutput = new SystemVolumeOwnership(directory, options.lockTimeoutMs, identity);
+                    const prior = priorOutput.read();
+                    if (!prior || prior.participants.some(activeParticipant))
+                        continue;
+                    if (prior.changed && prior.baseline) {
+                        try {
+                            await backend.write(prior.baseline, execute, identity);
+                        }
+                        catch {
+                            pendingRecovery += 1;
+                            continue;
+                        }
+                    }
+                    priorOutput.clear();
+                }
+                if (state) {
+                    state.participants = state.participants.filter(activeParticipant);
+                    if (state.participants.length === 0) {
+                        // A crashed owner or failed final restore must not turn the raised
+                        // output into the next alarm's baseline.
+                        if (state.changed && state.baseline)
+                            await write(state.baseline);
+                        ownership.clear();
+                        state = undefined;
+                    }
+                }
+                const target = clamp(volume);
+                const before = await backend.read(output);
+                const changed = before.muted || before.volume < target;
+                const prior = state;
+                const id = randomUUID();
+                const joined = { version: 1, generation: state?.generation ?? randomUUID(), baseline: state?.baseline ?? before, changed: Boolean(state?.changed) || changed, participants: [...state?.participants ?? [], { id, pid: process.pid, phase: 'pending' }] };
+                // Persist the original state before any mixer command can partly succeed.
+                ownership.save(joined);
+                try {
+                    if (changed)
+                        await write({ volume: Math.max(before.volume, target), muted: false });
+                    // Until this commit succeeds, a later transaction can discard the
+                    // pending participant even if failed cleanup left its PID alive.
+                    ownership.save({ ...joined, participants: joined.participants.map(item => item.id === id ? { ...item, phase: 'active' } : item) });
+                }
+                catch (error) {
+                    let restoreError;
+                    if (changed)
+                        try {
+                            await write(before);
+                        }
+                        catch (cause) {
+                            restoreError = cause;
+                        }
+                    try {
+                        if (restoreError)
+                            ownership.save({ ...joined, participants: joined.participants.filter(item => item.id !== id) });
+                        else if (prior)
+                            ownership.save(prior);
+                        else
+                            ownership.clear();
+                    }
+                    catch (saveError) {
+                        throw new Error(`${messageOf(error)}${restoreError ? `; restoring the previous output state also failed: ${messageOf(restoreError)}` : ''}; output-volume recovery state could not be updated: ${messageOf(saveError)}`);
+                    }
+                    if (restoreError)
+                        throw new Error(`${messageOf(error)}; restoring the previous output state also failed: ${messageOf(restoreError)}`);
+                    throw error;
+                }
+                let released = false;
+                return {
+                    message: (changed ? `Local output raised to at least ${target}% and unmuted for the alarm.` : `Local output was already at least ${target}% and unmuted.`) + (pendingRecovery ? ` ${pendingRecovery} earlier output recovery record${pendingRecovery === 1 ? ' remains' : 's remain'} unresolved and retained; its original device must be checked.` : ''),
+                    async release({ preserve = false } = {}) {
+                        if (released)
+                            return;
+                        await ownership.transaction(async () => {
+                            if (released)
+                                return;
+                            const current = ownership.read();
+                            if (!current || current.generation !== joined.generation) {
+                                released = true;
+                                return;
+                            }
+                            current.participants = current.participants.filter(item => item.id !== id && activeParticipant(item));
+                            if (preserve) {
+                                // Handoff commits the current output as the user's new baseline.
+                                // A later acquisition samples it before making another adjustment.
+                                current.baseline = null;
+                                current.changed = false;
+                            }
+                            ownership.save(current);
+                            if (current.participants.length === 0) {
+                                if (current.changed && current.baseline)
+                                    await write(current.baseline);
+                                ownership.clear();
+                            }
+                            released = true;
+                        });
+                    }
+                };
+            });
+        } };
 }
+function activeParticipant(item) { return item.phase === 'active' && volumeProcessAlive(item.pid); }
 function macBackend(run) { return { async read() { const result = await checked(run('/usr/bin/osascript', ['-e', 'set s to get volume settings', '-e', 'return (output volume of s as text) & "," & (output muted of s as text)']), 'read macOS output volume'); const match = /^(\d+)\s*,\s*(true|false)/i.exec(result.stdout.trim()); if (!match)
-        throw new Error('macOS returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1])), muted: match[2]?.toLowerCase() === 'true' }; }, async write(value) { await checked(run('/usr/bin/osascript', ['-e', `set volume output volume ${clamp(value.volume)} ${value.muted ? 'with' : 'without'} output muted`]), 'set macOS output volume'); } }; }
-function linuxBackend(run, resolve) {
-    const wpctl = resolve('wpctl');
-    if (wpctl)
-        return { async read() { const result = await checked(run(wpctl, ['get-volume', '@DEFAULT_AUDIO_SINK@']), 'read PipeWire output volume'); const match = /Volume:\s*([\d.]+)/i.exec(result.stdout); if (!match)
-                throw new Error('wpctl returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1]) * 100), muted: /\[MUTED\]/i.test(result.stdout) }; }, async write(value) { await checked(run(wpctl, ['set-volume', '@DEFAULT_AUDIO_SINK@', `${clamp(value.volume)}%`]), 'set PipeWire output volume'); await checked(run(wpctl, ['set-mute', '@DEFAULT_AUDIO_SINK@', value.muted ? '1' : '0']), 'set PipeWire mute state'); } };
-    const pactl = resolve('pactl');
-    if (pactl)
-        return { async read() { const [volume, mute] = await Promise.all([checked(run(pactl, ['get-sink-volume', '@DEFAULT_SINK@']), 'read PulseAudio output volume'), checked(run(pactl, ['get-sink-mute', '@DEFAULT_SINK@']), 'read PulseAudio mute state')]); const match = /(\d+)%/.exec(volume.stdout); if (!match)
-                throw new Error('pactl returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1])), muted: /yes/i.test(mute.stdout) }; }, async write(value) { await checked(run(pactl, ['set-sink-volume', '@DEFAULT_SINK@', `${clamp(value.volume)}%`]), 'set PulseAudio output volume'); await checked(run(pactl, ['set-sink-mute', '@DEFAULT_SINK@', value.muted ? '1' : '0']), 'set PulseAudio mute state'); } };
-    const amixer = resolve('amixer');
-    if (amixer)
-        return { async read() { const result = await checked(run(amixer, ['get', 'Master']), 'read ALSA output volume'); const matches = [...result.stdout.matchAll(/\[(\d+)%\]/g)]; const last = matches.at(-1); if (!last)
-                throw new Error('amixer returned an unreadable output-volume state.'); return { volume: clamp(Number(last[1])), muted: /\[off\]/i.test(result.stdout) }; }, async write(value) { await checked(run(amixer, ['set', 'Master', `${clamp(value.volume)}%`, value.muted ? 'mute' : 'unmute']), 'set ALSA output volume'); } };
-    return undefined;
-}
+        throw new Error('macOS returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1])), muted: match[2]?.toLowerCase() === 'true' }; }, async write(value, execute = run) { await checked(execute('/usr/bin/osascript', ['-e', `set volume output volume ${clamp(value.volume)} ${value.muted ? 'with' : 'without'} output muted`]), 'set macOS output volume'); } }; }
 function windowsBackend(run, resolve) { const powershell = resolve('powershell.exe') ?? resolve('pwsh.exe'); if (!powershell)
     return undefined; return { async read() { const result = await checked(run(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', `${windowsCoreAudio}; [RadioCliVolume]::Get()`]), 'read Windows output volume'); const match = /^(\d+)\s*,\s*(true|false)/im.exec(result.stdout); if (!match)
-        throw new Error('Windows returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1])), muted: match[2]?.toLowerCase() === 'true' }; }, async write(value) { await checked(run(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', `${windowsCoreAudio}; [RadioCliVolume]::Set(${clamp(value.volume)}, $${value.muted ? 'true' : 'false'})`]), 'set Windows output volume'); } }; }
+        throw new Error('Windows returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1])), muted: match[2]?.toLowerCase() === 'true' }; }, async write(value, execute = run) { await checked(execute(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', `${windowsCoreAudio}; [RadioCliVolume]::Set(${clamp(value.volume)}, $${value.muted ? 'true' : 'false'})`]), 'set Windows output volume'); } }; }
 const windowsCoreAudio = String.raw `Add-Type -TypeDefinition @'
 using System; using System.Runtime.InteropServices;
 public enum EDataFlow { eRender, eCapture, eAll } public enum ERole { eConsole, eMultimedia, eCommunications }
@@ -38,6 +138,68 @@ public enum EDataFlow { eRender, eCapture, eAll } public enum ERole { eConsole,
 public static class RadioCliVolume { static IAudioEndpointVolume Endpoint(){IMMDevice d;((IMMDeviceEnumerator)new MMDeviceEnumerator()).GetDefaultAudioEndpoint(EDataFlow.eRender,ERole.eMultimedia,out d);object o;Guid id=typeof(IAudioEndpointVolume).GUID;d.Activate(ref id,23,IntPtr.Zero,out o);return(IAudioEndpointVolume)o;} public static string Get(){float v;bool m;var e=Endpoint();e.GetMasterVolumeLevelScalar(out v);e.GetMute(out m);return Math.Round(v*100)+","+m.ToString().ToLower();} public static void Set(int v,bool m){var e=Endpoint();e.SetMasterVolumeLevelScalar(Math.Max(0,Math.Min(100,v))/100f,Guid.Empty);e.SetMute(m,Guid.Empty);} }
 '@`;
 function clamp(value) { return Math.max(0, Math.min(100, Math.round(Number.isFinite(value) ? value : 0))); }
+function messageOf(error) { return error instanceof Error ? error.message : String(error); }
 async function checked(promise, label) { const result = await promise; if (result.code !== 0)
     throw new Error(`${label} failed: ${(result.stderr || result.stdout || `exit ${result.code}`).trim()}`); return result; }
-function runCommand(command, args) { return new Promise(resolve => { const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true }); let stdout = ''; let stderr = ''; child.stdout.on('data', value => stdout += String(value)); child.stderr.on('data', value => stderr += String(value)); child.on('error', error => resolve({ code: 127, stdout, stderr: error.message })); child.on('close', code => resolve({ code: code ?? 1, stdout, stderr })); }); }
+function runCommand(command, args, ownership) {
+    return new Promise(resolve => {
+        ownership?.beginNativeWrite();
+        let child;
+        try {
+            child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, timeout: 10_000, killSignal: 'SIGKILL', env: { ...process.env, LC_ALL: 'C' } });
+        }
+        catch (error) {
+            let message = messageOf(error);
+            try {
+                ownership?.finishNativeWrite();
+            }
+            catch (cleanupError) {
+                message += `; system-output command journal cleanup failed: ${messageOf(cleanupError)}`;
+            }
+            resolve({ code: 127, stdout: '', stderr: message });
+            return;
+        }
+        let stdout = '';
+        let stderr = '';
+        let failure;
+        const append = (value, output) => { const text = String(value); if (output === 'stdout')
+            stdout += text;
+        else
+            stderr += text; if (Buffer.byteLength(stdout) + Buffer.byteLength(stderr) > 64 * 1024) {
+            stdout = stdout.slice(0, 32768);
+            stderr = stderr.slice(0, 32768);
+            failure = 'The output-volume command returned too much data.';
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { }
+        } };
+        child.stdout.on('data', value => append(value, 'stdout'));
+        child.stderr.on('data', value => append(value, 'stderr'));
+        // Spawn/kill errors do not prove the helper has closed. Keep ownership until
+        // close, including when recording its PID fails after the process starts.
+        child.on('error', error => { failure = error.message; });
+        child.on('close', (code, signal) => {
+            try {
+                ownership?.finishNativeWrite();
+            }
+            catch (error) {
+                failure = `${failure ? `${failure}; ` : ''}system-output command journal cleanup failed: ${messageOf(error)}`;
+            }
+            resolve({ code: failure ? 1 : code ?? 1, stdout, stderr: failure || stderr || (signal ? 'The output-volume command was interrupted or timed out.' : '') });
+        });
+        if (ownership && child.pid)
+            try {
+                ownership.recordNativeWritePid(child.pid);
+            }
+            catch (error) {
+                failure = `The system-output helper PID could not be saved: ${messageOf(error)}`;
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch (killError) {
+                    failure += `; stopping the helper failed: ${messageOf(killError)}`;
+                }
+            }
+    });
+}