@ciphore/radiocli 0.2.4 → 0.2.5

package/dist/setup-playback.js

@@ -0,0 +1,152 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resolveCommand } from './platform/executables.js';
+/** Exercise local decoders without sending audio to an output device or receiver. */
+export async function verifyLocalPlayback(backends, options = {}) {
+    options.signal?.throwIfAborted();
+    const local = [...new Set(backends)].filter((value) => ['mpv', 'ffplay', 'vlc'].includes(value));
+    if (!local.length)
+        return [];
+    const result = (backend, status, message) => ({
+        backend, status, source: 'local-wav', output: backend === 'mpv' ? 'null' : 'dummy', physicalOutput: 'unverified', message
+    });
+    if (options.platform && options.platform !== process.platform && !options.execute) {
+        return local.map(backend => result(backend, 'unverified', 'The requested platform differs from the current runtime. Run the rehearsal on that device.'));
+    }
+    const directory = await mkdtemp(join(tmpdir(), 'radiocli-setup-'));
+    try {
+        const fixture = join(directory, 'local silence.wav');
+        await writeFile(fixture, silentWav(), { mode: 0o600 });
+        const resolve = options.resolve ?? resolveCommand;
+        const execute = options.execute ?? runDecoderProcess;
+        const results = [];
+        for (const backend of local) {
+            options.signal?.throwIfAborted();
+            const command = backend === 'vlc' ? resolve('cvlc') ?? resolve('vlc') : resolve(backend);
+            if (!command) {
+                results.push(result(backend, 'failed', 'The executable was detected earlier but could not be resolved for the rehearsal.'));
+                continue;
+            }
+            const args = backend === 'mpv'
+                ? ['--no-config', '--no-video', '--ao=null', '--ao-null-untimed', '--idle=no', '--term-status-msg=', '--term-playing-msg=RADIOCLI_DECODER_READY', fixture]
+                : backend === 'ffplay'
+                    ? ['-nodisp', '-autoexit', '-hide_banner', '-loglevel', 'info', fixture]
+                    : ['--ignore-config', '--intf', 'dummy', '--no-video', '--aout=dummy', '--no-one-instance', '--no-media-library', '--no-repeat', '--no-loop', '--play-and-exit', '--verbose=2', fixture];
+            let completed;
+            try {
+                completed = await execute(command, args, {
+                    env: { ...options.env ?? process.env, LC_ALL: 'C', ...(backend === 'ffplay' ? { SDL_AUDIODRIVER: 'dummy', SDL_AUDIO_DRIVER: 'dummy', SDL_VIDEODRIVER: 'dummy', SDL_VIDEO_DRIVER: 'dummy' } : {}) },
+                    timeoutMs: Math.max(250, Math.min(options.timeoutMs ?? 8000, 30_000)), signal: options.signal
+                });
+            }
+            catch {
+                options.signal?.throwIfAborted();
+                completed = { code: null, output: '', failure: 'The playback process could not be started.' };
+            }
+            options.signal?.throwIfAborted();
+            const fatal = hasPlaybackFailure(backend, completed.output);
+            const observed = backend === 'mpv' ? completed.output.includes('RADIOCLI_DECODER_READY')
+                : backend === 'ffplay' ? /Audio:\s*pcm_s16le/i.test(completed.output)
+                    : /using audio output module "(?:adummy|dummy)"/i.test(completed.output) && /(?:end of file|EOF)/i.test(completed.output);
+            results.push(completed.failure || completed.code !== 0 || fatal
+                ? result(backend, 'failed', completed.failure ?? `Local WAV playback failed${completed.code !== null ? ` (exit ${completed.code})` : ''}. Run radiocli doctor and check this backend's native dependencies.`)
+                : observed ? result(backend, 'passed', 'Local WAV playback completed with a null or dummy audio output.')
+                    : result(backend, 'unverified', 'The process exited successfully, but it did not expose the expected playback evidence.'));
+        }
+        return results;
+    }
+    finally {
+        await rm(directory, { force: true, recursive: true });
+    }
+}
+function hasPlaybackFailure(backend, output) {
+    return output.split(/\r?\n/).some(line => {
+        if (!/\b(?:error|failed|could not|cannot|invalid data)\b/i.test(line))
+            return false;
+        // The null-output rehearsal does not render OSD text. Minimal Linux installs
+        // can lack fonts while the audio decoder and output complete successfully.
+        if (backend === 'mpv' && /^\[osd(?:\/[^\]]+)?\]/i.test(line))
+            return false;
+        if (backend === 'vlc') {
+            // VLC logs rejected optional modules and build flags at debug level, and
+            // starts desktop interfaces even with a dummy playback interface. Neither
+            // proves failure of the isolated audio pipeline; readiness is checked below.
+            if (/\bdebug:/i.test(line))
+                return false;
+            if (/\b(?:dbus|interface)\b/i.test(line) && !/\b(?:audio output|decoder|demux|input|access|stream)\b/i.test(line))
+                return false;
+        }
+        return true;
+    });
+}
+function runDecoderProcess(command, args, options) {
+    return new Promise((resolve, reject) => {
+        options.signal?.throwIfAborted();
+        const child = spawn(command, args, { env: options.env, stdio: ['ignore', 'pipe', 'pipe'], shell: false, windowsHide: true });
+        let output = '';
+        let failure;
+        let force;
+        let deadline;
+        let settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            clearTimeout(force);
+            clearTimeout(deadline);
+            options.signal?.removeEventListener('abort', abort);
+            options.signal?.aborted ? reject(options.signal.reason) : resolve({ code, output, failure });
+        };
+        const stop = (message) => {
+            if (settled || failure)
+                return;
+            failure = message;
+            try {
+                child.kill();
+            }
+            catch { /* The force deadline also covers failed termination. */ }
+            force = setTimeout(() => { try {
+                child.kill('SIGKILL');
+            }
+            catch { /* Report through the cleanup deadline. */ } }, 250);
+            deadline = setTimeout(() => {
+                // A failed native termination must not hang setup or retain stdio handles.
+                child.stdout?.destroy();
+                child.stderr?.destroy();
+                child.unref();
+                failure = 'The playback process did not acknowledge termination. Check for a remaining native player process.';
+                finish(null);
+            }, 1500);
+        };
+        const abort = () => stop('The rehearsal was cancelled.');
+        const timeout = setTimeout(() => stop('Local WAV playback exceeded its deadline.'), options.timeoutMs);
+        const collect = (chunk) => { output = `${output}${chunk.toString()}`.slice(-64 * 1024); };
+        child.stdout?.on('data', collect);
+        child.stderr?.on('data', collect);
+        child.once('error', () => { failure = 'The playback process could not be started.'; finish(null); });
+        child.once('close', code => finish(code));
+        options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+    });
+}
+function silentWav() {
+    const dataBytes = 44_100; // 250 ms, stereo, signed 16-bit PCM.
+    const buffer = Buffer.alloc(44 + dataBytes);
+    buffer.write('RIFF');
+    buffer.writeUInt32LE(36 + dataBytes, 4);
+    buffer.write('WAVEfmt ', 8);
+    buffer.writeUInt32LE(16, 16);
+    buffer.writeUInt16LE(1, 20);
+    buffer.writeUInt16LE(2, 22);
+    buffer.writeUInt32LE(44_100, 24);
+    buffer.writeUInt32LE(44_100 * 4, 28);
+    buffer.writeUInt16LE(4, 32);
+    buffer.writeUInt16LE(16, 34);
+    buffer.write('data', 36);
+    buffer.writeUInt32LE(dataBytes, 40);
+    return buffer;
+}

package/dist/setup.js

@@ -5,10 +5,15 @@ import { createInterface } from 'node:readline/promises';
 import { clearCommandCache, commandExists, resolveCommand } from './platform/executables.js';
 import { detectPlaybackBackends, playbackBackendStatusLines } from './player/backend-install.js';
 import { configureMcpIntegrations } from './agent/mcp-install.js';
-import { JsonLibraryStore } from './storage/store.js';
+import { defaultLibraryPath, JsonLibraryStore } from './storage/store.js';
 import { defaultAgentControlSettings } from './types.js';
 import { resolveTerminalCapabilities } from './platform/terminal.js';
+import { isAirPlayPlatformSupported } from './player/airplay-policy.js';
+import { probeAirPlayReadiness } from './player/airplay-readiness.js';
+import { airPlaySetupVerification, hasSystemdSystemManager, linuxAirPlaySetupPlan } from './player/airplay-setup.js';
+import { readSettingsWithoutMigration } from './storage/read-settings.js';
 import { identifyPlatform, readLinuxOsRelease } from './platform/runtime.js';
+import { verifyLocalPlayback } from './setup-playback.js';
 const components = ['mpv', 'ffmpeg', 'vlc'];
 export async function runSetup(options = {}) {
     const platform = options.platform ?? process.platform;
@@ -19,6 +24,12 @@ export async function runSetup(options = {}) {
     const output = options.output ?? process.stdout;
     const hasCommand = options.hasCommand ?? commandExists;
     const parsed = parseSetupArgs(options.args ?? []);
+    const linuxAirPlayEligible = platform === 'linux' && isAirPlayPlatformSupported(platform, env, host.release);
+    if (parsed.airplay !== null && !linuxAirPlayEligible)
+        throw new Error('--airplay and --no-airplay configure experimental native Linux AirPlay only. macOS keeps its existing AirPlay setup; this environment has no Linux opt-in.');
+    const prompt = options.prompt ?? ((question, defaultValue) => promptYesNo(input, output, question, defaultValue));
+    const libraryPath = () => options.libraryPath ?? defaultLibraryPath({ platform, env, home: env.HOME ?? env.USERPROFILE });
+    const probe = options.probeAirPlay ?? ((loadSender) => probeAirPlayReadiness({ platform, env, release: host.release, hasCommand, ...(loadSender ? {} : { sender: async () => ({ loaded: false, message: 'Not probed before approval.' }) }) }));
     if (parsed.packageManager)
         validateNativePackageManager(parsed.packageManager, host);
     const installed = detectInstalledComponents(hasCommand);
@@ -28,36 +39,64 @@ export async function runSetup(options = {}) {
     output.write(`Manager ${packageManager ?? 'not detected'}\n\n`);
     let selected = parsed.only ?? defaultComponents(platform, parsed.all);
     if (!parsed.yes && !parsed.only && isInteractive(input, output)) {
-        selected = await promptForComponents({ platform, installed, input, output });
+        selected = await promptForComponents({ platform, installed, output, prompt });
+    }
+    let airplay = parsed.airplay;
+    if (linuxAirPlayEligible && airplay === null && !parsed.yes && !parsed.only && isInteractive(input, output)) {
+        const enabled = readSettingsWithoutMigration(libraryPath())?.linuxAirPlayEnabled === true;
+        const choice = await prompt('  AirPlay — experimental (FFmpeg, shared Avahi network discovery)', enabled);
+        // Declining the default on a new install leaves the library untouched.
+        if (choice || enabled)
+            airplay = choice;
     }
     let mcp = parsed.mcp;
     if (mcp === null && !parsed.yes && isInteractive(input, output)) {
-        mcp = await promptYesNo(input, output, '  Agent control via MCP (detected coding agents)', true);
+        mcp = await prompt('  Agent control via MCP (detected coding agents)', true);
     }
     let agentUi = parsed.agentUi;
     if (mcp === true && agentUi === null && !parsed.yes && isInteractive(input, output)) {
         const note = platform === 'darwin'
             ? ' (macOS will ask the agent app to control Terminal on first use)'
             : ' (opens a separate terminal window)';
-        agentUi = await promptYesNo(input, output, `  Open the RadioCLI TUI for agent playback${note}`, true);
+        agentUi = await prompt(`  Open the RadioCLI TUI for agent playback${note}`, true);
     }
     const isRoot = (options.getUid ?? process.getuid)?.() === 0;
     const elevation = packageManagerElevation(hasCommand, isRoot);
     const plan = createSetupPlan({ platform, osRelease, env, packageManager, installed, selected, elevation });
+    const airPlayPlan = airplay === true ? linuxAirPlaySetupPlan({ manager: packageManager, elevation, hasCommand,
+        systemd: (options.isSystemd ?? hasSystemdSystemManager)(),
+        serviceReady: parsed.dryRun ? false : (await probe(false).catch(() => null))?.discoveryService === 'ready', existingCommands: plan.commands }) : null;
+    if (airPlayPlan)
+        plan.commands.push(...airPlayPlan.commands);
     printPlan(plan, output);
+    if (airplay !== null)
+        output.write(`  Linux AirPlay: ${airplay ? 'enable for this library after accepted setup; verify sender and discovery' : 'disable for this library; keep installed packages and shared services'}\n`);
+    for (const note of airPlayPlan?.notes ?? [])
+        output.write(`  Note: ${note}\n`);
     if (packageManager && packageManagerNeedsRoot(packageManager) && !isRoot && !elevation) {
         output.write('  Note: Run package commands as root; sudo/doas unavailable.\n');
     }
     for (const note of packageManagerNotes(packageManager, host))
         output.write(`  Note: ${note}\n`);
+    const verify = async () => {
+        let linuxAirPlayEnabled = airplay === true;
+        if (platform === 'linux' && airplay === null) {
+            try {
+                linuxAirPlayEnabled = readSettingsWithoutMigration(libraryPath())?.linuxAirPlayEnabled === true;
+            }
+            catch { /* Unreadable consent stays disabled. */ }
+        }
+        await printVerification(output, { platform, osRelease, env, release: host.release, hasCommand, getUid: options.getUid, linuxAirPlayEnabled, verifyPlayback: options.verifyPlayback });
+    };
     const missing = plan.selected.filter(component => !plan.installed[component]);
-    if (missing.length === 0) {
+    if (missing.length === 0 && airplay === null) {
         output.write(plan.selected.length === 0 ? '\nNo components selected.\n' : '\nEverything selected is already installed.\n');
         await finishMcpSetup(mcp, agentUi, parsed.dryRun, output);
-        printVerification(output);
+        if (!parsed.dryRun)
+            await verify();
         return;
     }
-    if (!plan.packageManager) {
+    if (!plan.packageManager && missing.length > 0) {
         if (parsed.dryRun) {
             output.write('\nDry run complete. Install the missing components manually; no system packages were changed.\n');
             await finishMcpSetup(mcp, agentUi, true, output);
@@ -75,15 +114,15 @@ export async function runSetup(options = {}) {
         throw new Error(`No verified automatic installation command for ${manual.join(', ')} with ${plan.packageManager}. Install these components manually or select --only=mpv.`);
     if (plan.packageManager === 'termux-pkg' && isRoot)
         throw new Error('Run setup as the normal Termux app user. Termux pkg refuses root execution.');
-    if (packageManagerNeedsRoot(plan.packageManager) && !isRoot && !elevation) {
+    if ((plan.packageManager && packageManagerNeedsRoot(plan.packageManager) || airPlayPlan?.commands.length) && plan.commands.length > 0 && !isRoot && !elevation) {
         throw new Error('System package installation requires root, sudo, or doas. Review the dry-run plan and install prerequisites with your administrator.');
     }
-    if (parsed.packageManager && !hasCommand(packageManagerProgram(parsed.packageManager))) {
+    if (plan.commands.length > 0 && parsed.packageManager && !hasCommand(packageManagerProgram(parsed.packageManager))) {
         const program = packageManagerProgram(parsed.packageManager);
         throw new Error(`Requested package manager is not available: ${parsed.packageManager}${program !== parsed.packageManager ? ` (${program})` : ''}.`);
     }
     if (!parsed.yes && isInteractive(input, output)) {
-        const confirmed = await promptYesNo(input, output, '\nInstall these components?', true);
+        const confirmed = await prompt(airplay === null ? '\nInstall these components?' : '\nApply this setup plan and Linux AirPlay preference?', true);
         if (!confirmed) {
             output.write('Setup cancelled. No system packages were changed.\n');
             return;
@@ -92,19 +131,32 @@ export async function runSetup(options = {}) {
     else if (!parsed.yes) {
         throw new Error('Setup needs an interactive terminal. Use --yes to approve the displayed commands or --dry-run to inspect them.');
     }
-    if (plan.commands.some(command => command.program === 'sudo')) {
+    if (!options.runCommand && plan.commands.some(command => command.program === 'sudo')) {
         output.write('\nRadioCLI needs administrator approval for the system package manager.\n');
         await runVisibleCommand(resolveCommand('sudo') ?? 'sudo', ['-v']);
     }
     const execute = options.runCommand ?? ((command, destination) => runInstallCommand(command, destination, platform));
-    output.write('\nInstalling\n');
+    if (plan.commands.length)
+        output.write('\nInstalling\n');
     for (const command of plan.commands) {
         await execute(command, output);
     }
     clearCommandCache();
+    if (airplay !== null) {
+        if (options.saveLinuxAirPlayEnabled)
+            options.saveLinuxAirPlayEnabled(airplay);
+        else
+            new JsonLibraryStore(libraryPath()).updateSettings({ linuxAirPlayEnabled: airplay });
+        output.write(`\nLinux AirPlay ${airplay ? 'enabled' : 'disabled'} for this library. Restart active RadioCLI sessions to apply this preference.\n`);
+        if (airplay) {
+            const readiness = await probe(true).catch(() => ({ eligible: true, discoveryExecutable: false, discoveryService: 'unverified', senderLoaded: false, ffmpeg: false, ready: false, message: 'Readiness could not be verified. Run radiocli doctor.' }));
+            for (const line of airPlaySetupVerification(readiness))
+                output.write(`  ${line}\n`);
+        }
+    }
     output.write('\nSetup complete.\n');
     await finishMcpSetup(mcp, agentUi, false, output);
-    printVerification(output);
+    await verify();
 }
 export function createSetupPlan({ platform, osRelease = '', env = process.env, packageManager, installed, selected, elevation = 'sudo' }) {
     if (packageManager)
@@ -141,6 +193,7 @@ export function parseSetupArgs(args) {
     let packageManager = null;
     let mcp = null;
     let agentUi = null;
+    let airplay = null;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (arg === '--all')
@@ -149,6 +202,12 @@ export function parseSetupArgs(args) {
             dryRun = true;
         else if (arg === '--yes' || arg === '-y')
             yes = true;
+        else if (arg === '--airplay' || arg === '--no-airplay') {
+            const enabled = arg === '--airplay';
+            if (airplay !== null && airplay !== enabled)
+                throw new Error('Use either --airplay or --no-airplay, not both.');
+            airplay = enabled;
+        }
         else if (arg === '--mcp') {
             if (mcp === false)
                 throw new Error('Use either --mcp or --no-mcp, not both.');
@@ -184,7 +243,7 @@ export function parseSetupArgs(args) {
         throw new Error('Use either --all or --only, not both.');
     if (agentUi !== null && mcp !== true)
         throw new Error('--agent-ui and --headless-agent require --mcp.');
-    return { all, dryRun, yes, only, packageManager, mcp, agentUi };
+    return { all, dryRun, yes, only, packageManager, mcp, agentUi, airplay };
 }
 async function finishMcpSetup(enabled, agentUi, dryRun, output) {
     if (enabled === null)
@@ -238,14 +297,14 @@ function detectInstalledComponents(hasCommand) {
         vlc: hasCommand('vlc') || hasCommand('cvlc')
     };
 }
-async function promptForComponents({ platform, installed, input, output }) {
+async function promptForComponents({ platform, installed, output, prompt }) {
     output.write('Choose components (installed items will be skipped):\n');
     const selected = [];
-    if (await promptYesNo(input, output, `  mpv      Full playback controls${installed.mpv ? ` ${separator(output)} installed` : ''}`, true))
+    if (await prompt(`  mpv      Full playback controls${installed.mpv ? ` ${separator(output)} installed` : ''}`, true))
         selected.push('mpv');
-    if (await promptYesNo(input, output, `  FFmpeg   ${platform === 'darwin' ? 'AirPlay + ' : ''}ffplay fallback${installed.ffmpeg ? ` ${separator(output)} installed` : ''}`, platform === 'darwin'))
+    if (await prompt(`  FFmpeg   ${platform === 'darwin' ? 'AirPlay + ' : ''}ffplay fallback${installed.ffmpeg ? ` ${separator(output)} installed` : ''}`, platform === 'darwin'))
         selected.push('ffmpeg');
-    if (await promptYesNo(input, output, `  VLC      Additional playback fallback${installed.vlc ? ` ${separator(output)} installed` : ''}`, false))
+    if (await prompt(`  VLC      Additional playback fallback${installed.vlc ? ` ${separator(output)} installed` : ''}`, false))
         selected.push('vlc');
     return selected;
 }
@@ -328,13 +387,21 @@ function progressFrame(label, frame, elapsedMs, output) {
     const bar = Array.from({ length: width }, (_, index) => index >= start && index < start + segment ? (unicode ? '█' : '#') : (unicode ? '░' : '.')).join('');
     return `  ${accent(output, unicode ? '◒' : '*')} ${accent(output, `[${bar}]`)} Installing ${label} ${formatElapsed(elapsedMs)}`;
 }
-function printVerification(output) {
+async function printVerification(output, { platform, osRelease, env, release, hasCommand, getUid, linuxAirPlayEnabled, verifyPlayback = verifyLocalPlayback }) {
     clearCommandCache();
-    const backends = detectPlaybackBackends();
+    const backends = detectPlaybackBackends({ platform, env, release, hasCommand, settings: { linuxAirPlayEnabled } });
     output.write('\nVerification\n');
     output.write(`  Playback backends: ${backends.join(', ') || 'none'}\n`);
-    for (const line of playbackBackendStatusLines(backends).slice(0, 3))
+    for (const line of playbackBackendStatusLines(backends, platform, osRelease, { hasCommand, getUid }).slice(0, 3))
         output.write(`  ${line}\n`);
+    const rehearsals = await verifyPlayback(backends, { platform, env });
+    for (const rehearsal of rehearsals)
+        output.write(`  decoder_${rehearsal.backend}=${rehearsal.status} ${rehearsal.message}\n`);
+    if (rehearsals.length === 0)
+        output.write('  decoder=unverified No local playback backend is available for a rehearsal.\n');
+    output.write('  physical_output=unverified Play a station on your intended speakers, headphones, or AirPlay receiver to verify that path.\n');
+    if (rehearsals.some(item => item.status !== 'passed'))
+        output.write('  Playback needs attention. Run radiocli doctor --playback for a repeatable local check.\n');
     output.write('\nRun radiocli to start listening.\n');
 }
 function writeHeader(output) {

package/dist/storage/file-lock.js

@@ -0,0 +1,113 @@
+import { mkdirSync, readdirSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+/** An owner is never evicted for being slow. Only a positively dead PID or an
+ * explicitly released generation can be reclaimed. Unknown/legacy locks fail
+ * closed; their age cannot distinguish a crashed writer from a suspended one. */
+export function acquireFileLock(directory, timeoutMs = 1000) {
+    const marker = `owner-${process.pid}-${randomUUID()}`;
+    const deadline = performance.now() + timeoutMs;
+    while (true) {
+        let acquired = false;
+        try {
+            mkdirSync(directory, { mode: 0o700 });
+            acquired = true;
+        }
+        catch (error) {
+            if (codeOf(error) !== 'EEXIST')
+                throw error;
+        }
+        if (acquired) {
+            try {
+                writeFileSync(join(directory, marker), '', { mode: 0o600, flag: 'wx' });
+            }
+            catch (error) {
+                // A failed write can leave its newly created marker behind. Remove only
+                // our unique file; never clear a directory belonging to a later writer.
+                try {
+                    unlinkSync(join(directory, marker));
+                }
+                catch { /* May not have been created. */ }
+                try {
+                    rmdirSync(directory);
+                }
+                catch { /* Never remove another generation. */ }
+                throw error;
+            }
+            let released = false;
+            return () => { if (!released) {
+                released = true;
+                finishLock(directory, marker);
+            } };
+        }
+        try {
+            const entries = readdirSync(directory);
+            const owner = entries.length === 1 ? entries[0] : '';
+            const match = /^(owner|released)-([1-9]\d*)-([a-f\d]{8}(?:-[a-f\d]{4}){3}-[a-f\d]{12})$/.exec(owner);
+            if (match && Number.isSafeInteger(Number(match[2])) && (match[1] === 'released' || isDead(Number(match[2])))) {
+                // Compare and claim the exact marker, never rename/delete the lock
+                // directory after an observation: a different writer may now own it.
+                const reaper = `owner-${process.pid}-${randomUUID()}`;
+                renameSync(join(directory, owner), join(directory, reaper));
+                finishLock(directory, reaper);
+            }
+        }
+        catch (error) {
+            if (codeOf(error) !== 'ENOENT')
+                throw error;
+        }
+        if (performance.now() >= deadline) {
+            throw Object.assign(new Error('The library lock has a live or unknown owner.'), { code: 'EBUSY' });
+        }
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+}
+function isDead(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    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 { /* Preserve the transaction result. */ }
+        return;
+    }
+    // Publish completion before cleanup so a failed unlink is recoverable even
+    // while this process is alive. Cleanup must not turn a commit into a failure.
+    try {
+        removeOwnedLock(directory, released);
+    }
+    catch { /* Recover on the next acquisition. */ }
+}
+function removeOwnedLock(directory, marker) {
+    try {
+        unlinkSync(join(directory, marker));
+    }
+    catch (error) {
+        if (codeOf(error) === 'ENOENT')
+            return;
+        throw error;
+    }
+    // An empty directory can be concurrently replaced only by a legacy writer.
+    // rmdir cannot remove a new nonempty generation, unlike recursive rm.
+    try {
+        rmdirSync(directory);
+    }
+    catch (error) {
+        if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(codeOf(error) ?? ''))
+            throw error;
+    }
+}
+function codeOf(error) { return error?.code; }

package/dist/storage/read-settings.js

@@ -0,0 +1,33 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from 'node:fs';
+/** Bounded, read-only preference inspection. Never creates or repairs a library. */
+export function readSettingsWithoutMigration(path) {
+    if (!path)
+        return undefined;
+    let descriptor;
+    const limit = 2 * 1024 * 1024;
+    try {
+        descriptor = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+        const info = fstatSync(descriptor);
+        if (!info.isFile() || info.size > limit)
+            return undefined;
+        const buffer = Buffer.alloc(limit + 1);
+        const size = readSync(descriptor, buffer, 0, buffer.length, 0);
+        if (size > limit)
+            return undefined;
+        const data = JSON.parse(buffer.toString('utf8', 0, size));
+        if (!record(data))
+            return undefined;
+        return data.settings === undefined ? {} : record(data.settings) ? data.settings : undefined;
+    }
+    catch (error) {
+        return error.code === 'ENOENT' ? {} : undefined;
+    }
+    finally {
+        if (descriptor !== undefined)
+            try {
+                closeSync(descriptor);
+            }
+            catch { /* Read-only best effort. */ }
+    }
+}
+function record(value) { return Boolean(value && typeof value === 'object' && !Array.isArray(value)); }

package/dist/storage/replace-file.js

@@ -0,0 +1,20 @@
+import { renameSync } from 'node:fs';
+/** Keep the destination intact until the replacement succeeds. Windows readers
+ * and virus scanners can briefly deny replacement even in a writable folder. */
+export function replaceFileSync(source, destination, platform = process.platform) {
+    const pause = new Int32Array(new SharedArrayBuffer(4));
+    for (let retry = 0;; retry++) {
+        try {
+            renameSync(source, destination);
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            if (platform !== 'win32' || !['EACCES', 'EPERM', 'EBUSY'].includes(code ?? '') || retry >= 10)
+                throw error;
+            // At most 550 ms in total, while retaining the writer lock and flushed
+            // temporary file. Never unlink the destination to work around a lock.
+            Atomics.wait(pause, 0, 0, (retry + 1) * 10);
+        }
+    }
+}