livedesk 0.1.593 → 0.1.595

package/electron/bounded-desktop-log.mjs

@@ -1,609 +1,609 @@
-import {
-  createWriteStream,
-  existsSync,
-  mkdirSync,
-  statSync,
-  truncateSync
-} from 'node:fs';
-import {
-  rename,
-  rm
-} from 'node:fs/promises';
-import { dirname } from 'node:path';
-
-export const DEFAULT_DESKTOP_LOG_MAX_FILE_BYTES = 512 * 1024;
-export const DEFAULT_DESKTOP_LOG_FILE_COUNT = 3;
-export const DEFAULT_DESKTOP_LOG_MAX_PENDING_ENTRIES = 24;
-export const DEFAULT_DESKTOP_LOG_MAX_PENDING_BYTES = 64 * 1024;
-export const DEFAULT_DESKTOP_LOG_STREAM_HIGH_WATER_BYTES = 32 * 1024;
-export const DEFAULT_DESKTOP_LOG_CLOSE_TIMEOUT_MS = 1_000;
-export const DEFAULT_DESKTOP_LOG_LOW_PRIORITY_RECORDS_PER_SECOND = 40;
-export const DEFAULT_DESKTOP_LOG_LOW_PRIORITY_BYTES_PER_SECOND = 128 * 1024;
-export const DEFAULT_DESKTOP_LOG_MAX_MESSAGE_BYTES = 16 * 1024;
-
-function boundedInteger(value, fallback, minimum, maximum) {
-  const numeric = Number(value);
-  return Number.isFinite(numeric)
-    ? Math.max(minimum, Math.min(maximum, Math.trunc(numeric)))
-    : fallback;
-}
-
-function byteLength(value) {
-  return Buffer.byteLength(String(value || ''), 'utf8');
-}
-
-function rawByteLength(value) {
-  if (Buffer.isBuffer(value)) return value.byteLength;
-  if (typeof ArrayBuffer !== 'undefined') {
-    if (value instanceof ArrayBuffer) return value.byteLength;
-    if (ArrayBuffer.isView(value)) return value.byteLength;
-  }
-  return byteLength(value);
-}
-
-function truncateUtf8(value, maximumBytes) {
-  const source = String(value ?? '');
-  if (byteLength(source) <= maximumBytes) return source;
-  const suffix = '…[truncated]';
-  const suffixBytes = byteLength(suffix);
-  const sourceBuffer = Buffer.from(source, 'utf8');
-  const retainedBytes = Math.max(0, maximumBytes - suffixBytes);
-  return `${sourceBuffer.subarray(0, retainedBytes).toString('utf8').replace(/\uFFFD+$/g, '')}${suffix}`;
-}
-
-function encodeRecordWithin(record, maximumBytes) {
-  let encoded = `${JSON.stringify(record)}\n`;
-  if (byteLength(encoded) <= maximumBytes) return encoded;
-  const sourceBytes = byteLength(record.message);
-  let low = 0;
-  let high = sourceBytes;
-  let best = `${JSON.stringify({ ...record, message: '' })}\n`;
-  while (low <= high) {
-    const middle = Math.trunc((low + high) / 2);
-    const candidate = `${JSON.stringify({
-      ...record,
-      message: truncateUtf8(record.message, middle)
-    })}\n`;
-    if (byteLength(candidate) <= maximumBytes) {
-      best = candidate;
-      low = middle + 1;
-    } else {
-      high = middle - 1;
-    }
-  }
-  return best;
-}
-
-function finishStreamWithin(
-  stream,
-  timeoutMs,
-  onForcedClose,
-  onTimerStarted = () => {},
-  onTimerStopped = () => {}
-) {
-  if (!stream || stream.destroyed || stream.closed) return Promise.resolve();
-  return new Promise(resolveFinish => {
-    let settled = false;
-    const finish = () => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      onTimerStopped();
-      stream.off?.('error', finish);
-      stream.off?.('close', finish);
-      resolveFinish();
-    };
-    onTimerStarted();
-    const timer = setTimeout(() => {
-      onForcedClose();
-      try { stream.destroy(); } catch { /* exact stream already closed */ }
-      finish();
-    }, Math.max(1, timeoutMs));
-    stream.once?.('error', finish);
-    stream.once?.('close', finish);
-    try {
-      stream.end(finish);
-    } catch {
-      finish();
-    }
-  });
-}
-
-export function createBoundedDesktopLogger(options = {}) {
-  const logPath = String(options.logPath || '').trim();
-  if (!logPath) throw new Error('desktop-log-path-required');
-
-  const maxFileBytes = boundedInteger(
-    options.maxFileBytes,
-    DEFAULT_DESKTOP_LOG_MAX_FILE_BYTES,
-    1024,
-    16 * 1024 * 1024
-  );
-  const fileCount = boundedInteger(
-    options.fileCount,
-    DEFAULT_DESKTOP_LOG_FILE_COUNT,
-    2,
-    8
-  );
-  const maxPendingEntries = boundedInteger(
-    options.maxPendingEntries,
-    DEFAULT_DESKTOP_LOG_MAX_PENDING_ENTRIES,
-    1,
-    128
-  );
-  const maxPendingBytes = boundedInteger(
-    options.maxPendingBytes,
-    DEFAULT_DESKTOP_LOG_MAX_PENDING_BYTES,
-    1024,
-    512 * 1024
-  );
-  const streamHighWaterBytes = boundedInteger(
-    options.streamHighWaterBytes,
-    DEFAULT_DESKTOP_LOG_STREAM_HIGH_WATER_BYTES,
-    1024,
-    256 * 1024
-  );
-  const closeTimeoutMs = boundedInteger(
-    options.closeTimeoutMs,
-    DEFAULT_DESKTOP_LOG_CLOSE_TIMEOUT_MS,
-    25,
-    5_000
-  );
-  const lowPriorityRecordsPerSecond = boundedInteger(
-    options.lowPriorityRecordsPerSecond,
-    DEFAULT_DESKTOP_LOG_LOW_PRIORITY_RECORDS_PER_SECOND,
-    1,
-    1_000
-  );
-  const lowPriorityBytesPerSecond = boundedInteger(
-    options.lowPriorityBytesPerSecond,
-    DEFAULT_DESKTOP_LOG_LOW_PRIORITY_BYTES_PER_SECOND,
-    1024,
-    4 * 1024 * 1024
-  );
-  const maxMessageBytes = Math.min(
-    maxFileBytes - 256,
-    boundedInteger(
-      options.maxMessageBytes,
-      DEFAULT_DESKTOP_LOG_MAX_MESSAGE_BYTES,
-      256,
-      256 * 1024
-    )
-  );
-  const now = typeof options.now === 'function' ? options.now : Date.now;
-  const streamFactory = typeof options.streamFactory === 'function'
-    ? options.streamFactory
-    : (targetPath, streamOptions) => createWriteStream(targetPath, streamOptions);
-  const rotateFile = typeof options.rename === 'function' ? options.rename : rename;
-  const removeFile = typeof options.rm === 'function' ? options.rm : rm;
-
-  let stream = null;
-  let streamDrainHandler = null;
-  let currentBytes = 0;
-  let blocked = false;
-  let rotatingPromise = null;
-  let rotationEpoch = 0;
-  let closePromise = null;
-  let closing = false;
-  let closed = false;
-  let lowWindowStartedAt = now();
-  let lowWindowRecords = 0;
-  let lowWindowBytes = 0;
-  let activeCloseTimers = 0;
-  let activeIdleWaitTimers = 0;
-  const pending = [];
-  const idleWaiters = new Set();
-  const counters = {
-    acceptedEntries: 0,
-    writtenEntries: 0,
-    writtenBytes: 0,
-    rotationCount: 0,
-    streamOpenCount: 0,
-    backpressureSignalCount: 0,
-    droppedBackpressureEntries: 0,
-    droppedBackpressureBytes: 0,
-    droppedRateLimitedEntries: 0,
-    droppedRateLimitedBytes: 0,
-    droppedPendingLimitEntries: 0,
-    droppedPendingLimitBytes: 0,
-    droppedClosingEntries: 0,
-    droppedClosingBytes: 0,
-    lowPriorityPreAdmissionAcceptedEntries: 0,
-    lowPriorityMaterializedEntries: 0,
-    streamErrorCount: 0,
-    forcedCloseCount: 0,
-    rotationDeadlineCount: 0,
-    startupOversizeResetCount: 0,
-    maximumPendingEntries: 0,
-    maximumPendingBytes: 0,
-    maximumWritableBytes: 0
-  };
-  let pendingBytes = 0;
-
-  try {
-    mkdirSync(dirname(logPath), { recursive: true });
-  } catch {
-    // The desktop shell must still start when its diagnostic directory is not writable.
-  }
-  for (let index = 0; index < fileCount; index += 1) {
-    const candidatePath = index === 0 ? logPath : `${logPath}.${index}`;
-    try {
-      const candidateBytes = existsSync(candidatePath)
-        ? Math.max(0, Number(statSync(candidatePath).size || 0))
-        : 0;
-      if (candidateBytes > maxFileBytes) {
-        truncateSync(candidatePath, 0);
-        counters.startupOversizeResetCount += 1;
-      } else if (index === 0) {
-        currentBytes = candidateBytes;
-      }
-    } catch {
-      if (index === 0) currentBytes = 0;
-    }
-  }
-
-  const rotationPath = index => index === 0 ? logPath : `${logPath}.${index}`;
-
-  function snapshot() {
-    const writableBytes = Math.max(0, Number(stream?.writableLength || 0));
-    return {
-      ...counters,
-      logPath,
-      maxFileBytes,
-      fileCount,
-      maxPendingEntries,
-      maxPendingBytes,
-      streamHighWaterBytes,
-      closeTimeoutMs,
-      lowPriorityRecordsPerSecond,
-      lowPriorityBytesPerSecond,
-      currentBytes,
-      pendingEntries: pending.length,
-      pendingBytes,
-      writableBytes,
-      blocked,
-      rotating: Boolean(rotatingPromise),
-      closing,
-      closed,
-      activeCloseTimers,
-      activeIdleWaitTimers
-    };
-  }
-
-  function notifyIdle() {
-    if (rotatingPromise || blocked || pending.length > 0) return;
-    for (const resolveIdle of idleWaiters) resolveIdle(snapshot());
-    idleWaiters.clear();
-  }
-
-  function recordDrop(reason, lineBytes) {
-    const bytes = Math.max(0, Number(lineBytes || 0));
-    if (reason === 'rate') {
-      counters.droppedRateLimitedEntries += 1;
-      counters.droppedRateLimitedBytes += bytes;
-    } else if (reason === 'pending') {
-      counters.droppedPendingLimitEntries += 1;
-      counters.droppedPendingLimitBytes += bytes;
-    } else if (reason === 'closing') {
-      counters.droppedClosingEntries += 1;
-      counters.droppedClosingBytes += bytes;
-    } else {
-      counters.droppedBackpressureEntries += 1;
-      counters.droppedBackpressureBytes += bytes;
-    }
-  }
-
-  function enqueue(line, priority) {
-    const lineBytes = byteLength(line);
-    if (pending.length >= maxPendingEntries || pendingBytes + lineBytes > maxPendingBytes) {
-      recordDrop('pending', lineBytes);
-      return false;
-    }
-    pending.push({ line, priority, bytes: lineBytes });
-    pendingBytes += lineBytes;
-    counters.maximumPendingEntries = Math.max(counters.maximumPendingEntries, pending.length);
-    counters.maximumPendingBytes = Math.max(counters.maximumPendingBytes, pendingBytes);
-    return true;
-  }
-
-  function handleStreamError() {
-    counters.streamErrorCount += 1;
-    blocked = false;
-    if (streamDrainHandler && stream) stream.off?.('drain', streamDrainHandler);
-    streamDrainHandler = null;
-    try { stream?.destroy(); } catch { /* already failed */ }
-    stream = null;
-    notifyIdle();
-  }
-
-  function ensureStream() {
-    if (stream || closing || closed) return stream;
-    try {
-      mkdirSync(dirname(logPath), { recursive: true });
-      stream = streamFactory(logPath, {
-        flags: 'a',
-        highWaterMark: streamHighWaterBytes
-      });
-      counters.streamOpenCount += 1;
-      stream.on?.('error', handleStreamError);
-      return stream;
-    } catch {
-      counters.streamErrorCount += 1;
-      stream = null;
-      return null;
-    }
-  }
-
-  async function rotateCurrentFile() {
-    if (rotatingPromise || closing || closed) return rotatingPromise;
-    const ownerEpoch = ++rotationEpoch;
-    const pending = (async () => {
-      const ownedStream = stream;
-      stream = null;
-      blocked = false;
-      if (streamDrainHandler && ownedStream) ownedStream.off?.('drain', streamDrainHandler);
-      streamDrainHandler = null;
-      await finishStreamWithin(ownedStream, closeTimeoutMs, () => {
-        counters.forcedCloseCount += 1;
-      }, () => {
-        activeCloseTimers += 1;
-      }, () => {
-        activeCloseTimers -= 1;
-      });
-      if (ownerEpoch !== rotationEpoch || closing || closed) return;
-      for (let index = fileCount - 1; index >= 1; index -= 1) {
-        if (ownerEpoch !== rotationEpoch || closing || closed) return;
-        const sourcePath = rotationPath(index - 1);
-        const destinationPath = rotationPath(index);
-        try { await removeFile(destinationPath, { force: true }); } catch { /* bounded best effort */ }
-        if (ownerEpoch !== rotationEpoch || closing || closed) return;
-        try {
-          await rotateFile(sourcePath, destinationPath);
-        } catch (error) {
-          if (error?.code !== 'ENOENT') counters.streamErrorCount += 1;
-        }
-        if (ownerEpoch !== rotationEpoch || closing || closed) return;
-      }
-      if (ownerEpoch !== rotationEpoch || closing || closed) return;
-      currentBytes = 0;
-      counters.rotationCount += 1;
-    })();
-    const tracked = pending.finally(() => {
-      if (rotatingPromise === tracked) rotatingPromise = null;
-      if (ownerEpoch === rotationEpoch && !closing && !closed) pump();
-      notifyIdle();
-    });
-    rotatingPromise = tracked;
-    return tracked;
-  }
-
-  function handleDrain() {
-    blocked = false;
-    streamDrainHandler = null;
-    pump();
-    notifyIdle();
-  }
-
-  function writeNow(line, priority) {
-    const lineBytes = byteLength(line);
-    if (currentBytes > 0 && currentBytes + lineBytes > maxFileBytes) {
-      enqueue(line, priority);
-      void rotateCurrentFile();
-      return true;
-    }
-    const target = ensureStream();
-    if (!target) {
-      recordDrop('backpressure', lineBytes);
-      return false;
-    }
-    let accepted;
-    try {
-      accepted = target.write(line);
-    } catch {
-      handleStreamError();
-      recordDrop('backpressure', lineBytes);
-      return false;
-    }
-    currentBytes += lineBytes;
-    counters.writtenEntries += 1;
-    counters.writtenBytes += lineBytes;
-    counters.maximumWritableBytes = Math.max(
-      counters.maximumWritableBytes,
-      Math.max(0, Number(target.writableLength || 0))
-    );
-    if (!accepted) {
-      counters.backpressureSignalCount += 1;
-      blocked = true;
-      streamDrainHandler = handleDrain;
-      target.once?.('drain', streamDrainHandler);
-    }
-    if (currentBytes >= maxFileBytes && !rotatingPromise) void rotateCurrentFile();
-    return true;
-  }
-
-  function pump() {
-    if (closing || closed || rotatingPromise || blocked) return;
-    while (pending.length > 0 && !blocked && !rotatingPromise && !closing && !closed) {
-      const entry = pending.shift();
-      pendingBytes -= entry.bytes;
-      if (pendingBytes < 0) pendingBytes = 0;
-      writeNow(entry.line, entry.priority);
-    }
-    notifyIdle();
-  }
-
-  function withinLowPriorityBudget(lineBytes) {
-    const timestamp = now();
-    if (timestamp - lowWindowStartedAt >= 1_000 || timestamp < lowWindowStartedAt) {
-      lowWindowStartedAt = timestamp;
-      lowWindowRecords = 0;
-      lowWindowBytes = 0;
-    }
-    if (lowWindowRecords >= lowPriorityRecordsPerSecond
-      || lowWindowBytes + lineBytes > lowPriorityBytesPerSecond) {
-      return false;
-    }
-    lowWindowRecords += 1;
-    lowWindowBytes += lineBytes;
-    return true;
-  }
-
-  function write(message, metadata = {}) {
-    const priority = metadata.priority === 'low' ? 'low' : 'normal';
-    const preAdmitted = metadata.lowPriorityAdmissionToken === lowPriorityAdmissionToken;
-    const record = {
-      timestamp: new Date(now()).toISOString(),
-      level: String(metadata.level || 'info').slice(0, 16),
-      source: String(metadata.source || 'desktop').slice(0, 64),
-      message: truncateUtf8(message, maxMessageBytes)
-    };
-    const line = encodeRecordWithin(record, Math.min(maxFileBytes, streamHighWaterBytes));
-    const lineBytes = byteLength(line);
-    if (closing || closed) {
-      recordDrop('closing', lineBytes);
-      return false;
-    }
-    if (priority === 'low' && !preAdmitted && !withinLowPriorityBudget(lineBytes)) {
-      recordDrop('rate', lineBytes);
-      return false;
-    }
-    counters.acceptedEntries += 1;
-    if (rotatingPromise || blocked) {
-      if (priority === 'low') {
-        recordDrop('backpressure', lineBytes);
-        return false;
-      }
-      return enqueue(line, priority);
-    }
-    return writeNow(line, priority);
-  }
-
-  const lowPriorityAdmissionToken = Object.freeze({});
-
-  function writeLowPriority(message, metadata = {}, materialize = value => value) {
-    const messageBytes = rawByteLength(message);
-    if (closing || closed) {
-      recordDrop('closing', messageBytes);
-      return false;
-    }
-    if (rotatingPromise || blocked) {
-      recordDrop('backpressure', messageBytes);
-      return false;
-    }
-    if (!withinLowPriorityBudget(messageBytes)) {
-      recordDrop('rate', messageBytes);
-      return false;
-    }
-    counters.lowPriorityPreAdmissionAcceptedEntries += 1;
-    let materialized;
-    try {
-      materialized = materialize(message);
-    } catch {
-      counters.streamErrorCount += 1;
-      return false;
-    }
-    counters.lowPriorityMaterializedEntries += 1;
-    return write(materialized, {
-      ...metadata,
-      priority: 'low',
-      lowPriorityAdmissionToken
-    });
-  }
-
-  function settleWithin(promise, timeoutMs) {
-    if (!promise) return Promise.resolve(true);
-    return new Promise(resolve => {
-      let settled = false;
-      const finish = value => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        activeCloseTimers -= 1;
-        resolve(value);
-      };
-      activeCloseTimers += 1;
-      const timer = setTimeout(() => finish(false), Math.max(1, timeoutMs));
-      promise.then(
-        () => finish(true),
-        () => finish(true)
-      );
-    });
-  }
-
-  function whenIdle(timeoutMs = closeTimeoutMs) {
-    if (!rotatingPromise && !blocked && pending.length === 0) {
-      return Promise.resolve(snapshot());
-    }
-    return new Promise(resolveIdle => {
-      let settled = false;
-      const finish = value => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        activeIdleWaitTimers -= 1;
-        idleWaiters.delete(onIdle);
-        resolveIdle(value);
-      };
-      const onIdle = value => finish(value);
-      idleWaiters.add(onIdle);
-      activeIdleWaitTimers += 1;
-      const timer = setTimeout(() => finish(snapshot()), Math.max(1, timeoutMs));
-    });
-  }
-
-  async function close(request = {}) {
-    if (closePromise) return closePromise;
-    const requestedTimeoutMs = boundedInteger(
-      typeof request === 'number' ? request : request.timeoutMs,
-      closeTimeoutMs,
-      25,
-      5_000
-    );
-    closePromise = (async () => {
-      const deadline = now() + requestedTimeoutMs;
-      closing = true;
-      while (pending.length > 0) {
-        const entry = pending.shift();
-        pendingBytes -= entry.bytes;
-        recordDrop('closing', entry.bytes);
-      }
-      pendingBytes = 0;
-      if (rotatingPromise) {
-        const rotationFinished = await settleWithin(
-          rotatingPromise,
-          Math.max(1, deadline - now())
-        );
-        if (!rotationFinished) {
-          counters.rotationDeadlineCount += 1;
-          rotationEpoch += 1;
-          rotatingPromise = null;
-        }
-      }
-      const ownedStream = stream;
-      stream = null;
-      blocked = false;
-      if (streamDrainHandler && ownedStream) ownedStream.off?.('drain', streamDrainHandler);
-      streamDrainHandler = null;
-      await finishStreamWithin(
-        ownedStream,
-        Math.max(1, deadline - now()),
-        () => { counters.forcedCloseCount += 1; },
-        () => { activeCloseTimers += 1; },
-        () => { activeCloseTimers -= 1; }
-      );
-      closed = true;
-      closing = false;
-      notifyIdle();
-      return snapshot();
-    })();
-    return closePromise;
-  }
-
-  return Object.freeze({
-    write,
-    writeLowPriority,
-    whenIdle,
-    close,
-    getStats: snapshot
-  });
-}
+import {
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  statSync,
+  truncateSync
+} from 'node:fs';
+import {
+  rename,
+  rm
+} from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+export const DEFAULT_DESKTOP_LOG_MAX_FILE_BYTES = 512 * 1024;
+export const DEFAULT_DESKTOP_LOG_FILE_COUNT = 3;
+export const DEFAULT_DESKTOP_LOG_MAX_PENDING_ENTRIES = 24;
+export const DEFAULT_DESKTOP_LOG_MAX_PENDING_BYTES = 64 * 1024;
+export const DEFAULT_DESKTOP_LOG_STREAM_HIGH_WATER_BYTES = 32 * 1024;
+export const DEFAULT_DESKTOP_LOG_CLOSE_TIMEOUT_MS = 1_000;
+export const DEFAULT_DESKTOP_LOG_LOW_PRIORITY_RECORDS_PER_SECOND = 40;
+export const DEFAULT_DESKTOP_LOG_LOW_PRIORITY_BYTES_PER_SECOND = 128 * 1024;
+export const DEFAULT_DESKTOP_LOG_MAX_MESSAGE_BYTES = 16 * 1024;
+
+function boundedInteger(value, fallback, minimum, maximum) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric)
+    ? Math.max(minimum, Math.min(maximum, Math.trunc(numeric)))
+    : fallback;
+}
+
+function byteLength(value) {
+  return Buffer.byteLength(String(value || ''), 'utf8');
+}
+
+function rawByteLength(value) {
+  if (Buffer.isBuffer(value)) return value.byteLength;
+  if (typeof ArrayBuffer !== 'undefined') {
+    if (value instanceof ArrayBuffer) return value.byteLength;
+    if (ArrayBuffer.isView(value)) return value.byteLength;
+  }
+  return byteLength(value);
+}
+
+function truncateUtf8(value, maximumBytes) {
+  const source = String(value ?? '');
+  if (byteLength(source) <= maximumBytes) return source;
+  const suffix = '…[truncated]';
+  const suffixBytes = byteLength(suffix);
+  const sourceBuffer = Buffer.from(source, 'utf8');
+  const retainedBytes = Math.max(0, maximumBytes - suffixBytes);
+  return `${sourceBuffer.subarray(0, retainedBytes).toString('utf8').replace(/\uFFFD+$/g, '')}${suffix}`;
+}
+
+function encodeRecordWithin(record, maximumBytes) {
+  let encoded = `${JSON.stringify(record)}\n`;
+  if (byteLength(encoded) <= maximumBytes) return encoded;
+  const sourceBytes = byteLength(record.message);
+  let low = 0;
+  let high = sourceBytes;
+  let best = `${JSON.stringify({ ...record, message: '' })}\n`;
+  while (low <= high) {
+    const middle = Math.trunc((low + high) / 2);
+    const candidate = `${JSON.stringify({
+      ...record,
+      message: truncateUtf8(record.message, middle)
+    })}\n`;
+    if (byteLength(candidate) <= maximumBytes) {
+      best = candidate;
+      low = middle + 1;
+    } else {
+      high = middle - 1;
+    }
+  }
+  return best;
+}
+
+function finishStreamWithin(
+  stream,
+  timeoutMs,
+  onForcedClose,
+  onTimerStarted = () => {},
+  onTimerStopped = () => {}
+) {
+  if (!stream || stream.destroyed || stream.closed) return Promise.resolve();
+  return new Promise(resolveFinish => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      onTimerStopped();
+      stream.off?.('error', finish);
+      stream.off?.('close', finish);
+      resolveFinish();
+    };
+    onTimerStarted();
+    const timer = setTimeout(() => {
+      onForcedClose();
+      try { stream.destroy(); } catch { /* exact stream already closed */ }
+      finish();
+    }, Math.max(1, timeoutMs));
+    stream.once?.('error', finish);
+    stream.once?.('close', finish);
+    try {
+      stream.end(finish);
+    } catch {
+      finish();
+    }
+  });
+}
+
+export function createBoundedDesktopLogger(options = {}) {
+  const logPath = String(options.logPath || '').trim();
+  if (!logPath) throw new Error('desktop-log-path-required');
+
+  const maxFileBytes = boundedInteger(
+    options.maxFileBytes,
+    DEFAULT_DESKTOP_LOG_MAX_FILE_BYTES,
+    1024,
+    16 * 1024 * 1024
+  );
+  const fileCount = boundedInteger(
+    options.fileCount,
+    DEFAULT_DESKTOP_LOG_FILE_COUNT,
+    2,
+    8
+  );
+  const maxPendingEntries = boundedInteger(
+    options.maxPendingEntries,
+    DEFAULT_DESKTOP_LOG_MAX_PENDING_ENTRIES,
+    1,
+    128
+  );
+  const maxPendingBytes = boundedInteger(
+    options.maxPendingBytes,
+    DEFAULT_DESKTOP_LOG_MAX_PENDING_BYTES,
+    1024,
+    512 * 1024
+  );
+  const streamHighWaterBytes = boundedInteger(
+    options.streamHighWaterBytes,
+    DEFAULT_DESKTOP_LOG_STREAM_HIGH_WATER_BYTES,
+    1024,
+    256 * 1024
+  );
+  const closeTimeoutMs = boundedInteger(
+    options.closeTimeoutMs,
+    DEFAULT_DESKTOP_LOG_CLOSE_TIMEOUT_MS,
+    25,
+    5_000
+  );
+  const lowPriorityRecordsPerSecond = boundedInteger(
+    options.lowPriorityRecordsPerSecond,
+    DEFAULT_DESKTOP_LOG_LOW_PRIORITY_RECORDS_PER_SECOND,
+    1,
+    1_000
+  );
+  const lowPriorityBytesPerSecond = boundedInteger(
+    options.lowPriorityBytesPerSecond,
+    DEFAULT_DESKTOP_LOG_LOW_PRIORITY_BYTES_PER_SECOND,
+    1024,
+    4 * 1024 * 1024
+  );
+  const maxMessageBytes = Math.min(
+    maxFileBytes - 256,
+    boundedInteger(
+      options.maxMessageBytes,
+      DEFAULT_DESKTOP_LOG_MAX_MESSAGE_BYTES,
+      256,
+      256 * 1024
+    )
+  );
+  const now = typeof options.now === 'function' ? options.now : Date.now;
+  const streamFactory = typeof options.streamFactory === 'function'
+    ? options.streamFactory
+    : (targetPath, streamOptions) => createWriteStream(targetPath, streamOptions);
+  const rotateFile = typeof options.rename === 'function' ? options.rename : rename;
+  const removeFile = typeof options.rm === 'function' ? options.rm : rm;
+
+  let stream = null;
+  let streamDrainHandler = null;
+  let currentBytes = 0;
+  let blocked = false;
+  let rotatingPromise = null;
+  let rotationEpoch = 0;
+  let closePromise = null;
+  let closing = false;
+  let closed = false;
+  let lowWindowStartedAt = now();
+  let lowWindowRecords = 0;
+  let lowWindowBytes = 0;
+  let activeCloseTimers = 0;
+  let activeIdleWaitTimers = 0;
+  const pending = [];
+  const idleWaiters = new Set();
+  const counters = {
+    acceptedEntries: 0,
+    writtenEntries: 0,
+    writtenBytes: 0,
+    rotationCount: 0,
+    streamOpenCount: 0,
+    backpressureSignalCount: 0,
+    droppedBackpressureEntries: 0,
+    droppedBackpressureBytes: 0,
+    droppedRateLimitedEntries: 0,
+    droppedRateLimitedBytes: 0,
+    droppedPendingLimitEntries: 0,
+    droppedPendingLimitBytes: 0,
+    droppedClosingEntries: 0,
+    droppedClosingBytes: 0,
+    lowPriorityPreAdmissionAcceptedEntries: 0,
+    lowPriorityMaterializedEntries: 0,
+    streamErrorCount: 0,
+    forcedCloseCount: 0,
+    rotationDeadlineCount: 0,
+    startupOversizeResetCount: 0,
+    maximumPendingEntries: 0,
+    maximumPendingBytes: 0,
+    maximumWritableBytes: 0
+  };
+  let pendingBytes = 0;
+
+  try {
+    mkdirSync(dirname(logPath), { recursive: true });
+  } catch {
+    // The desktop shell must still start when its diagnostic directory is not writable.
+  }
+  for (let index = 0; index < fileCount; index += 1) {
+    const candidatePath = index === 0 ? logPath : `${logPath}.${index}`;
+    try {
+      const candidateBytes = existsSync(candidatePath)
+        ? Math.max(0, Number(statSync(candidatePath).size || 0))
+        : 0;
+      if (candidateBytes > maxFileBytes) {
+        truncateSync(candidatePath, 0);
+        counters.startupOversizeResetCount += 1;
+      } else if (index === 0) {
+        currentBytes = candidateBytes;
+      }
+    } catch {
+      if (index === 0) currentBytes = 0;
+    }
+  }
+
+  const rotationPath = index => index === 0 ? logPath : `${logPath}.${index}`;
+
+  function snapshot() {
+    const writableBytes = Math.max(0, Number(stream?.writableLength || 0));
+    return {
+      ...counters,
+      logPath,
+      maxFileBytes,
+      fileCount,
+      maxPendingEntries,
+      maxPendingBytes,
+      streamHighWaterBytes,
+      closeTimeoutMs,
+      lowPriorityRecordsPerSecond,
+      lowPriorityBytesPerSecond,
+      currentBytes,
+      pendingEntries: pending.length,
+      pendingBytes,
+      writableBytes,
+      blocked,
+      rotating: Boolean(rotatingPromise),
+      closing,
+      closed,
+      activeCloseTimers,
+      activeIdleWaitTimers
+    };
+  }
+
+  function notifyIdle() {
+    if (rotatingPromise || blocked || pending.length > 0) return;
+    for (const resolveIdle of idleWaiters) resolveIdle(snapshot());
+    idleWaiters.clear();
+  }
+
+  function recordDrop(reason, lineBytes) {
+    const bytes = Math.max(0, Number(lineBytes || 0));
+    if (reason === 'rate') {
+      counters.droppedRateLimitedEntries += 1;
+      counters.droppedRateLimitedBytes += bytes;
+    } else if (reason === 'pending') {
+      counters.droppedPendingLimitEntries += 1;
+      counters.droppedPendingLimitBytes += bytes;
+    } else if (reason === 'closing') {
+      counters.droppedClosingEntries += 1;
+      counters.droppedClosingBytes += bytes;
+    } else {
+      counters.droppedBackpressureEntries += 1;
+      counters.droppedBackpressureBytes += bytes;
+    }
+  }
+
+  function enqueue(line, priority) {
+    const lineBytes = byteLength(line);
+    if (pending.length >= maxPendingEntries || pendingBytes + lineBytes > maxPendingBytes) {
+      recordDrop('pending', lineBytes);
+      return false;
+    }
+    pending.push({ line, priority, bytes: lineBytes });
+    pendingBytes += lineBytes;
+    counters.maximumPendingEntries = Math.max(counters.maximumPendingEntries, pending.length);
+    counters.maximumPendingBytes = Math.max(counters.maximumPendingBytes, pendingBytes);
+    return true;
+  }
+
+  function handleStreamError() {
+    counters.streamErrorCount += 1;
+    blocked = false;
+    if (streamDrainHandler && stream) stream.off?.('drain', streamDrainHandler);
+    streamDrainHandler = null;
+    try { stream?.destroy(); } catch { /* already failed */ }
+    stream = null;
+    notifyIdle();
+  }
+
+  function ensureStream() {
+    if (stream || closing || closed) return stream;
+    try {
+      mkdirSync(dirname(logPath), { recursive: true });
+      stream = streamFactory(logPath, {
+        flags: 'a',
+        highWaterMark: streamHighWaterBytes
+      });
+      counters.streamOpenCount += 1;
+      stream.on?.('error', handleStreamError);
+      return stream;
+    } catch {
+      counters.streamErrorCount += 1;
+      stream = null;
+      return null;
+    }
+  }
+
+  async function rotateCurrentFile() {
+    if (rotatingPromise || closing || closed) return rotatingPromise;
+    const ownerEpoch = ++rotationEpoch;
+    const pending = (async () => {
+      const ownedStream = stream;
+      stream = null;
+      blocked = false;
+      if (streamDrainHandler && ownedStream) ownedStream.off?.('drain', streamDrainHandler);
+      streamDrainHandler = null;
+      await finishStreamWithin(ownedStream, closeTimeoutMs, () => {
+        counters.forcedCloseCount += 1;
+      }, () => {
+        activeCloseTimers += 1;
+      }, () => {
+        activeCloseTimers -= 1;
+      });
+      if (ownerEpoch !== rotationEpoch || closing || closed) return;
+      for (let index = fileCount - 1; index >= 1; index -= 1) {
+        if (ownerEpoch !== rotationEpoch || closing || closed) return;
+        const sourcePath = rotationPath(index - 1);
+        const destinationPath = rotationPath(index);
+        try { await removeFile(destinationPath, { force: true }); } catch { /* bounded best effort */ }
+        if (ownerEpoch !== rotationEpoch || closing || closed) return;
+        try {
+          await rotateFile(sourcePath, destinationPath);
+        } catch (error) {
+          if (error?.code !== 'ENOENT') counters.streamErrorCount += 1;
+        }
+        if (ownerEpoch !== rotationEpoch || closing || closed) return;
+      }
+      if (ownerEpoch !== rotationEpoch || closing || closed) return;
+      currentBytes = 0;
+      counters.rotationCount += 1;
+    })();
+    const tracked = pending.finally(() => {
+      if (rotatingPromise === tracked) rotatingPromise = null;
+      if (ownerEpoch === rotationEpoch && !closing && !closed) pump();
+      notifyIdle();
+    });
+    rotatingPromise = tracked;
+    return tracked;
+  }
+
+  function handleDrain() {
+    blocked = false;
+    streamDrainHandler = null;
+    pump();
+    notifyIdle();
+  }
+
+  function writeNow(line, priority) {
+    const lineBytes = byteLength(line);
+    if (currentBytes > 0 && currentBytes + lineBytes > maxFileBytes) {
+      enqueue(line, priority);
+      void rotateCurrentFile();
+      return true;
+    }
+    const target = ensureStream();
+    if (!target) {
+      recordDrop('backpressure', lineBytes);
+      return false;
+    }
+    let accepted;
+    try {
+      accepted = target.write(line);
+    } catch {
+      handleStreamError();
+      recordDrop('backpressure', lineBytes);
+      return false;
+    }
+    currentBytes += lineBytes;
+    counters.writtenEntries += 1;
+    counters.writtenBytes += lineBytes;
+    counters.maximumWritableBytes = Math.max(
+      counters.maximumWritableBytes,
+      Math.max(0, Number(target.writableLength || 0))
+    );
+    if (!accepted) {
+      counters.backpressureSignalCount += 1;
+      blocked = true;
+      streamDrainHandler = handleDrain;
+      target.once?.('drain', streamDrainHandler);
+    }
+    if (currentBytes >= maxFileBytes && !rotatingPromise) void rotateCurrentFile();
+    return true;
+  }
+
+  function pump() {
+    if (closing || closed || rotatingPromise || blocked) return;
+    while (pending.length > 0 && !blocked && !rotatingPromise && !closing && !closed) {
+      const entry = pending.shift();
+      pendingBytes -= entry.bytes;
+      if (pendingBytes < 0) pendingBytes = 0;
+      writeNow(entry.line, entry.priority);
+    }
+    notifyIdle();
+  }
+
+  function withinLowPriorityBudget(lineBytes) {
+    const timestamp = now();
+    if (timestamp - lowWindowStartedAt >= 1_000 || timestamp < lowWindowStartedAt) {
+      lowWindowStartedAt = timestamp;
+      lowWindowRecords = 0;
+      lowWindowBytes = 0;
+    }
+    if (lowWindowRecords >= lowPriorityRecordsPerSecond
+      || lowWindowBytes + lineBytes > lowPriorityBytesPerSecond) {
+      return false;
+    }
+    lowWindowRecords += 1;
+    lowWindowBytes += lineBytes;
+    return true;
+  }
+
+  function write(message, metadata = {}) {
+    const priority = metadata.priority === 'low' ? 'low' : 'normal';
+    const preAdmitted = metadata.lowPriorityAdmissionToken === lowPriorityAdmissionToken;
+    const record = {
+      timestamp: new Date(now()).toISOString(),
+      level: String(metadata.level || 'info').slice(0, 16),
+      source: String(metadata.source || 'desktop').slice(0, 64),
+      message: truncateUtf8(message, maxMessageBytes)
+    };
+    const line = encodeRecordWithin(record, Math.min(maxFileBytes, streamHighWaterBytes));
+    const lineBytes = byteLength(line);
+    if (closing || closed) {
+      recordDrop('closing', lineBytes);
+      return false;
+    }
+    if (priority === 'low' && !preAdmitted && !withinLowPriorityBudget(lineBytes)) {
+      recordDrop('rate', lineBytes);
+      return false;
+    }
+    counters.acceptedEntries += 1;
+    if (rotatingPromise || blocked) {
+      if (priority === 'low') {
+        recordDrop('backpressure', lineBytes);
+        return false;
+      }
+      return enqueue(line, priority);
+    }
+    return writeNow(line, priority);
+  }
+
+  const lowPriorityAdmissionToken = Object.freeze({});
+
+  function writeLowPriority(message, metadata = {}, materialize = value => value) {
+    const messageBytes = rawByteLength(message);
+    if (closing || closed) {
+      recordDrop('closing', messageBytes);
+      return false;
+    }
+    if (rotatingPromise || blocked) {
+      recordDrop('backpressure', messageBytes);
+      return false;
+    }
+    if (!withinLowPriorityBudget(messageBytes)) {
+      recordDrop('rate', messageBytes);
+      return false;
+    }
+    counters.lowPriorityPreAdmissionAcceptedEntries += 1;
+    let materialized;
+    try {
+      materialized = materialize(message);
+    } catch {
+      counters.streamErrorCount += 1;
+      return false;
+    }
+    counters.lowPriorityMaterializedEntries += 1;
+    return write(materialized, {
+      ...metadata,
+      priority: 'low',
+      lowPriorityAdmissionToken
+    });
+  }
+
+  function settleWithin(promise, timeoutMs) {
+    if (!promise) return Promise.resolve(true);
+    return new Promise(resolve => {
+      let settled = false;
+      const finish = value => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        activeCloseTimers -= 1;
+        resolve(value);
+      };
+      activeCloseTimers += 1;
+      const timer = setTimeout(() => finish(false), Math.max(1, timeoutMs));
+      promise.then(
+        () => finish(true),
+        () => finish(true)
+      );
+    });
+  }
+
+  function whenIdle(timeoutMs = closeTimeoutMs) {
+    if (!rotatingPromise && !blocked && pending.length === 0) {
+      return Promise.resolve(snapshot());
+    }
+    return new Promise(resolveIdle => {
+      let settled = false;
+      const finish = value => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        activeIdleWaitTimers -= 1;
+        idleWaiters.delete(onIdle);
+        resolveIdle(value);
+      };
+      const onIdle = value => finish(value);
+      idleWaiters.add(onIdle);
+      activeIdleWaitTimers += 1;
+      const timer = setTimeout(() => finish(snapshot()), Math.max(1, timeoutMs));
+    });
+  }
+
+  async function close(request = {}) {
+    if (closePromise) return closePromise;
+    const requestedTimeoutMs = boundedInteger(
+      typeof request === 'number' ? request : request.timeoutMs,
+      closeTimeoutMs,
+      25,
+      5_000
+    );
+    closePromise = (async () => {
+      const deadline = now() + requestedTimeoutMs;
+      closing = true;
+      while (pending.length > 0) {
+        const entry = pending.shift();
+        pendingBytes -= entry.bytes;
+        recordDrop('closing', entry.bytes);
+      }
+      pendingBytes = 0;
+      if (rotatingPromise) {
+        const rotationFinished = await settleWithin(
+          rotatingPromise,
+          Math.max(1, deadline - now())
+        );
+        if (!rotationFinished) {
+          counters.rotationDeadlineCount += 1;
+          rotationEpoch += 1;
+          rotatingPromise = null;
+        }
+      }
+      const ownedStream = stream;
+      stream = null;
+      blocked = false;
+      if (streamDrainHandler && ownedStream) ownedStream.off?.('drain', streamDrainHandler);
+      streamDrainHandler = null;
+      await finishStreamWithin(
+        ownedStream,
+        Math.max(1, deadline - now()),
+        () => { counters.forcedCloseCount += 1; },
+        () => { activeCloseTimers += 1; },
+        () => { activeCloseTimers -= 1; }
+      );
+      closed = true;
+      closing = false;
+      notifyIdle();
+      return snapshot();
+    })();
+    return closePromise;
+  }
+
+  return Object.freeze({
+    write,
+    writeLowPriority,
+    whenIdle,
+    close,
+    getStats: snapshot
+  });
+}