livedesk 0.1.457 → 0.1.458

package/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.211",
+  "version": "0.1.212",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -40,10 +40,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.415",
-    "@livedesk/fast-osx-arm64": "0.1.415",
-    "@livedesk/fast-osx-x64": "0.1.415",
-    "@livedesk/fast-win-x64": "0.1.415"
+    "@livedesk/fast-linux-x64": "0.1.416",
+    "@livedesk/fast-osx-arm64": "0.1.416",
+    "@livedesk/fast-osx-x64": "0.1.416",
+    "@livedesk/fast-win-x64": "0.1.416"
   },
   "publishConfig": {
     "access": "public"

package/diagnostics/livedesk-mac-physical-gate-core.mjs

@@ -25,6 +25,36 @@ function parseMacProcessRecords(psOutput) {
   return records;
 }
 
+function parseMacProcessResourceRecords(psOutput) {
+  const records = [];
+  for (const rawLine of String(psOutput || '').split(/\r?\n/)) {
+    const match = rawLine.match(/^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(\S+)\s*(.*)$/);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    const parentPid = Number(match[2]);
+    const cpuPercent = Number(match[4]);
+    const rssKiB = Number(match[5]);
+    if (
+      !Number.isInteger(pid)
+      || pid <= 1
+      || !Number.isInteger(parentPid)
+      || !Number.isFinite(cpuPercent)
+      || !Number.isFinite(rssKiB)
+    ) {
+      continue;
+    }
+    records.push({
+      pid,
+      parentPid,
+      commandName: basenameWithoutQuotes(match[3]),
+      cpuPercent: Math.max(0, cpuPercent),
+      rssBytes: Math.max(0, Math.round(rssKiB * 1024)),
+      commandLine: String(match[6] || '').trim()
+    });
+  }
+  return records;
+}
+
 function isMacCaptureHelperRecord(record) {
   const commandName = String(record?.commandName || '');
   const commandLine = normalizeProcessText(record?.commandLine);
@@ -46,6 +76,64 @@ function finite(value, fallback = 0) {
   return Number.isFinite(parsed) ? parsed : fallback;
 }
 
+export function createAsyncSingleFlightSampler(sampleImpl) {
+  if (typeof sampleImpl !== 'function') {
+    throw new TypeError('An async sample function is required.');
+  }
+
+  let inFlight = null;
+  let requestedCount = 0;
+  let startedCount = 0;
+  let skippedCount = 0;
+
+  const start = args => {
+    startedCount += 1;
+    const current = Promise.resolve().then(() => sampleImpl(...args));
+    const tracked = current.finally(() => {
+      if (inFlight === tracked) {
+        inFlight = null;
+      }
+    });
+    inFlight = tracked;
+    return tracked;
+  };
+
+  return {
+    request(...args) {
+      requestedCount += 1;
+      if (inFlight) {
+        skippedCount += 1;
+        return null;
+      }
+      return start(args);
+    },
+    async run(...args) {
+      requestedCount += 1;
+      while (inFlight) {
+        const pending = inFlight;
+        try {
+          await pending;
+        } catch {
+          // A required sample gets its own attempt after a failed periodic one.
+        }
+      }
+      return start(args);
+    },
+    async waitForIdle() {
+      if (!inFlight) return;
+      await inFlight;
+    },
+    getState() {
+      return {
+        inFlight: inFlight !== null,
+        requestedCount,
+        startedCount,
+        skippedCount
+      };
+    }
+  };
+}
+
 function basenameWithoutQuotes(value) {
   return path.basename(String(value || '').trim().replace(/^["']|["']$/g, ''));
 }
@@ -54,47 +142,56 @@ export function parseMacHelperProcesses(psOutput) {
   return parseMacProcessRecords(psOutput).filter(isMacCaptureHelperRecord);
 }
 
-export function parseMacLiveDeskRuntimeProcesses(psOutput, { ignorePids = [] } = {}) {
+function classifyMacLiveDeskRuntimeRecord(record) {
+  const commandName = String(record?.commandName || '');
+  const commandLine = normalizeProcessText(record?.commandLine);
+  if (isMacCaptureHelperRecord(record)) {
+    return 'capture-helper';
+  }
+  if (
+    /^livedesk-client-fast$/i.test(commandName)
+    || /(?:^|\/|[\s"'])livedesk-client-fast(?:\.dll)?(?:\s|$|["'])/i.test(commandLine)
+  ) {
+    return 'client-agent';
+  }
+  if (
+    /(?:node_modules\/(?:livedesk\/client|@livedesk\/client)|packages\/(?:livedesk\/client|client))\/bin\/livedesk-client(?:-node)?\.js(?:\s|$|["'])/i
+      .test(commandLine)
+  ) {
+    return 'client-runtime';
+  }
+  if (
+    /(?:node_modules\/livedesk|packages\/livedesk)\/bin\/livedesk\.js(?:\s|$|["'])/i
+      .test(commandLine)
+    || /(?:^|[\s"'])[^"'\s]*node_modules\/\.bin\/livedesk(?:\s|$|["'])/i
+      .test(commandLine)
+  ) {
+    return 'unified-runtime';
+  }
+  if (
+    /(?:node_modules\/(?:livedesk\/hub|@livedesk\/hub)|packages\/(?:livedesk\/hub|hub))\/src\/server\.js(?:\s|$|["'])/i
+      .test(commandLine)
+  ) {
+    return 'hub-runtime';
+  }
+  if (
+    /(?:^|\/)LiveDesk\.app\/Contents\/MacOS\/LiveDesk(?:\s|$|["'])/i.test(commandLine)
+  ) {
+    return 'desktop-runtime';
+  }
+  return '';
+}
+
+function identifyMacLiveDeskRuntimeRecords(records, { ignorePids = [] } = {}) {
   const ignored = new Set(
     (Array.isArray(ignorePids) ? ignorePids : [])
       .map(Number)
       .filter(pid => Number.isInteger(pid) && pid > 1)
   );
   const results = [];
-  for (const record of parseMacProcessRecords(psOutput)) {
+  for (const record of records) {
     if (ignored.has(record.pid)) continue;
-    const commandName = String(record.commandName || '');
-    const commandLine = normalizeProcessText(record.commandLine);
-    let kind = '';
-    if (isMacCaptureHelperRecord(record)) {
-      kind = 'capture-helper';
-    } else if (
-      /^livedesk-client-fast$/i.test(commandName)
-      || /(?:^|\/|[\s"'])livedesk-client-fast(?:\.dll)?(?:\s|$|["'])/i.test(commandLine)
-    ) {
-      kind = 'client-agent';
-    } else if (
-      /(?:node_modules\/(?:livedesk\/client|@livedesk\/client)|packages\/(?:livedesk\/client|client))\/bin\/livedesk-client(?:-node)?\.js(?:\s|$|["'])/i
-        .test(commandLine)
-    ) {
-      kind = 'client-runtime';
-    } else if (
-      /(?:node_modules\/livedesk|packages\/livedesk)\/bin\/livedesk\.js(?:\s|$|["'])/i
-        .test(commandLine)
-      || /(?:^|[\s"'])[^"'\s]*node_modules\/\.bin\/livedesk(?:\s|$|["'])/i
-        .test(commandLine)
-    ) {
-      kind = 'unified-runtime';
-    } else if (
-      /(?:node_modules\/(?:livedesk\/hub|@livedesk\/hub)|packages\/(?:livedesk\/hub|hub))\/src\/server\.js(?:\s|$|["'])/i
-        .test(commandLine)
-    ) {
-      kind = 'hub-runtime';
-    } else if (
-      /(?:^|\/)LiveDesk\.app\/Contents\/MacOS\/LiveDesk(?:\s|$|["'])/i.test(commandLine)
-    ) {
-      kind = 'desktop-runtime';
-    }
+    const kind = classifyMacLiveDeskRuntimeRecord(record);
     if (!kind) continue;
     results.push({
       ...record,
@@ -104,6 +201,191 @@ export function parseMacLiveDeskRuntimeProcesses(psOutput, { ignorePids = [] } =
   return results;
 }
 
+export function parseMacLiveDeskRuntimeProcesses(psOutput, options = {}) {
+  return identifyMacLiveDeskRuntimeRecords(parseMacProcessRecords(psOutput), options);
+}
+
+function hasAncestorPid(record, ancestorPid, recordsByPid) {
+  const expectedAncestor = Number(ancestorPid);
+  if (!Number.isInteger(expectedAncestor) || expectedAncestor <= 1) return false;
+  let parentPid = Number(record?.parentPid || 0);
+  const visited = new Set();
+  for (let depth = 0; depth < 16 && parentPid > 1 && !visited.has(parentPid); depth += 1) {
+    if (parentPid === expectedAncestor) return true;
+    visited.add(parentPid);
+    parentPid = Number(recordsByPid.get(parentPid)?.parentPid || 0);
+  }
+  return false;
+}
+
+function normalizedOwnedPids(values) {
+  return new Set(
+    (Array.isArray(values) ? values : [])
+      .map(Number)
+      .filter(pid => Number.isInteger(pid) && pid > 1)
+  );
+}
+
+/**
+ * Returns a report-safe process sample. Command lines and executable paths are
+ * used only in-memory for strict LiveDesk/helper identity and never returned.
+ */
+export function buildMacDiagnosticResourceSample(
+  psOutput,
+  {
+    diagnosticPid = 0,
+    hubPid = 0,
+    agentPid = 0,
+    decoderPids = []
+  } = {}
+) {
+  const records = parseMacProcessResourceRecords(psOutput);
+  const recordsByPid = new Map(records.map(record => [record.pid, record]));
+  const normalizedDiagnosticPid = Number(diagnosticPid);
+  const normalizedHubPid = Number(hubPid);
+  const normalizedAgentPid = Number(agentPid);
+  const ownedDecoderPids = normalizedOwnedPids(decoderPids);
+  const helpers = records.filter(isMacCaptureHelperRecord);
+  // The public `npx livedesk diagnose mac-physical` coordinator is itself
+  // classified as a unified LiveDesk runtime. Exclude only that exact,
+  // caller-owned PID from ownership/drain counts. Descendants and neighboring
+  // LiveDesk runtimes remain visible and therefore continue to fail closed.
+  const liveDeskRecords = identifyMacLiveDeskRuntimeRecords(records, {
+    ignorePids: [normalizedDiagnosticPid]
+  });
+  const hubRecord = recordsByPid.get(normalizedHubPid);
+  const agentRecord = recordsByPid.get(normalizedAgentPid);
+  const hubOwned = classifyMacLiveDeskRuntimeRecord(hubRecord) === 'hub-runtime';
+  const agentOwned = classifyMacLiveDeskRuntimeRecord(agentRecord) === 'client-agent';
+  const ownedLiveDeskPids = new Set();
+  if (hubOwned) ownedLiveDeskPids.add(normalizedHubPid);
+  if (agentOwned) ownedLiveDeskPids.add(normalizedAgentPid);
+  const helperOwnership = new Map();
+  for (const helper of helpers) {
+    const owned = agentOwned && hasAncestorPid(helper, normalizedAgentPid, recordsByPid);
+    helperOwnership.set(helper.pid, owned);
+    if (owned) ownedLiveDeskPids.add(helper.pid);
+  }
+
+  const resourceRecords = [];
+  const addResource = (record, role, ownedByDiagnostic) => {
+    if (!record) return;
+    resourceRecords.push({
+      role,
+      pid: record.pid,
+      ownedByDiagnostic: ownedByDiagnostic === true,
+      cpuPercent: Math.round(record.cpuPercent * 100) / 100,
+      rssBytes: record.rssBytes
+    });
+  };
+  addResource(hubRecord, 'hub', hubOwned);
+  addResource(agentRecord, 'remote-fast', agentOwned);
+  for (const decoderPid of [...ownedDecoderPids].sort((left, right) => left - right)) {
+    addResource(recordsByPid.get(decoderPid), 'decoder', true);
+  }
+  for (const helper of helpers.sort((left, right) => left.pid - right.pid)) {
+    addResource(helper, 'capture-helper', helperOwnership.get(helper.pid) === true);
+  }
+
+  return {
+    sampledAt: new Date().toISOString(),
+    totalLiveDeskProcessCount: liveDeskRecords.length,
+    captureHelperCount: helpers.length,
+    unownedLiveDeskPids: liveDeskRecords
+      .filter(record => !ownedLiveDeskPids.has(record.pid))
+      .map(record => record.pid)
+      .sort((left, right) => left - right),
+    processes: resourceRecords.sort((left, right) =>
+      left.role.localeCompare(right.role) || left.pid - right.pid
+    )
+  };
+}
+
+function percentile95(values) {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((left, right) => left - right);
+  return sorted[Math.max(0, Math.ceil(sorted.length * 0.95) - 1)];
+}
+
+export function summarizeMacDiagnosticResourceSamples(
+  samples = [],
+  { expectedProcesses = [] } = {}
+) {
+  const normalizedSamples = (Array.isArray(samples) ? samples : [])
+    .filter(sample => sample && typeof sample === 'object');
+  const grouped = new Map();
+  for (const record of Array.isArray(expectedProcesses) ? expectedProcesses : []) {
+    const pid = Number(record?.pid);
+    const role = String(record?.role || '').trim();
+    if (!Number.isInteger(pid) || pid <= 1 || !role) continue;
+    grouped.set(`${role}:${pid}`, {
+      role,
+      pid,
+      ownedByDiagnostic: record?.ownedByDiagnostic === true,
+      cpuPercentSamples: [],
+      rssBytesPeak: 0
+    });
+  }
+  for (const sample of normalizedSamples) {
+    for (const record of Array.isArray(sample.processes) ? sample.processes : []) {
+      const pid = Number(record?.pid);
+      const role = String(record?.role || '').trim();
+      if (!Number.isInteger(pid) || pid <= 1 || !role) continue;
+      const key = `${role}:${pid}`;
+      let summary = grouped.get(key);
+      if (!summary) {
+        summary = {
+          role,
+          pid,
+          ownedByDiagnostic: true,
+          cpuPercentSamples: [],
+          rssBytesPeak: 0
+        };
+        grouped.set(key, summary);
+      }
+      summary.ownedByDiagnostic = summary.ownedByDiagnostic && record.ownedByDiagnostic === true;
+      summary.cpuPercentSamples.push(Math.max(0, finite(record.cpuPercent)));
+      summary.rssBytesPeak = Math.max(summary.rssBytesPeak, Math.max(0, finite(record.rssBytes)));
+    }
+  }
+  const processes = [...grouped.values()]
+    .map(summary => {
+      const cpuPercentSamples = summary.cpuPercentSamples
+        .slice(-120)
+        .map(value => Math.round(value * 100) / 100);
+      return {
+        role: summary.role,
+        pid: summary.pid,
+        ownedByDiagnostic: summary.ownedByDiagnostic,
+        sampleCount: summary.cpuPercentSamples.length,
+        cpuPercentSamples,
+        cpuPercentP95: Math.round(percentile95(summary.cpuPercentSamples) * 100) / 100,
+        cpuPercentPeak: Math.round(Math.max(0, ...summary.cpuPercentSamples) * 100) / 100,
+        rssBytesPeak: Math.round(summary.rssBytesPeak)
+      };
+    })
+    .sort((left, right) => left.role.localeCompare(right.role) || left.pid - right.pid);
+  const totalLiveDeskProcessCountSamples = normalizedSamples
+    .map(sample => Math.max(0, Math.round(finite(sample.totalLiveDeskProcessCount))));
+  const captureHelperCountSamples = normalizedSamples
+    .map(sample => Math.max(0, Math.round(finite(sample.captureHelperCount))));
+  const unownedLiveDeskPids = [...new Set(
+    normalizedSamples.flatMap(sample =>
+      (Array.isArray(sample.unownedLiveDeskPids) ? sample.unownedLiveDeskPids : [])
+        .map(Number)
+        .filter(pid => Number.isInteger(pid) && pid > 1)
+    )
+  )].sort((left, right) => left - right);
+  return {
+    sampleCount: normalizedSamples.length,
+    totalLiveDeskProcessCount: totalLiveDeskProcessCountSamples.at(-1) || 0,
+    totalLiveDeskProcessCountPeak: Math.max(0, ...totalLiveDeskProcessCountSamples),
+    captureHelperCountPeak: Math.max(0, ...captureHelperCountSamples),
+    unownedLiveDeskPids,
+    processes
+  };
+}
+
 const MODIFIERS = Object.freeze([
   { code: 'ShiftLeft', key: 'Shift', keyCode: 16, location: 1, flag: 'shiftKey' },
   { code: 'ControlLeft', key: 'Control', keyCode: 17, location: 1, flag: 'ctrlKey' },
@@ -243,6 +525,49 @@ export function classifyMacPhysicalGate(snapshot = {}) {
   const helperPids = Array.isArray(helper.observedPids)
     ? helper.observedPids.map(Number).filter(pid => Number.isInteger(pid) && pid > 1)
     : [];
+  const resources = snapshot.resources || {};
+  const baselineResources = resources.baseline || {};
+  const steadyResources = resources.steadyCapture || {};
+  const cleanupResources = resources.afterCleanup || {};
+  const steadyProcesses = Array.isArray(steadyResources.processes)
+    ? steadyResources.processes
+    : [];
+  const sampledSteadyProcesses = steadyProcesses
+    .filter(processInfo => finite(processInfo?.sampleCount) > 0);
+  const sampledSteadyRoles = new Set(
+    sampledSteadyProcesses.map(processInfo => String(processInfo?.role || ''))
+  );
+  const resourceTelemetryAvailable = finite(baselineResources.sampleCount) > 0
+    && finite(steadyResources.sampleCount) > 0
+    && finite(cleanupResources.sampleCount) > 0;
+  const resourceOwnershipCurrent = finite(baselineResources.totalLiveDeskProcessCountPeak) === 0
+    && sampledSteadyRoles.has('hub')
+    && sampledSteadyRoles.has('remote-fast')
+    && sampledSteadyRoles.has('capture-helper')
+    && sampledSteadyProcesses.every(processInfo => processInfo?.ownedByDiagnostic === true)
+    && (!Array.isArray(steadyResources.unownedLiveDeskPids)
+      || steadyResources.unownedLiveDeskPids.length === 0);
+  const resourceDrained = finite(cleanupResources.totalLiveDeskProcessCount) === 0
+    && finite(cleanupResources.totalLiveDeskProcessCountPeak) === 0
+    && (!Array.isArray(cleanupResources.processes) || cleanupResources.processes.length === 0)
+    && (!Array.isArray(cleanupResources.unownedLiveDeskPids)
+      || cleanupResources.unownedLiveDeskPids.length === 0);
+  const resourceHelperPeak = Math.max(
+    finite(helper.maxConcurrent),
+    finite(steadyResources.captureHelperCountPeak)
+  );
+  const highCpuProcesses = steadyProcesses
+    .filter(processInfo =>
+      finite(processInfo?.cpuPercentP95) >= 80
+      || finite(processInfo?.cpuPercentPeak) >= 100
+    )
+    .map(processInfo => ({
+      role: String(processInfo?.role || ''),
+      pid: Math.max(0, Math.round(finite(processInfo?.pid))),
+      cpuPercentP95: Math.max(0, finite(processInfo?.cpuPercentP95)),
+      cpuPercentPeak: Math.max(0, finite(processInfo?.cpuPercentPeak)),
+      rssBytesPeak: Math.max(0, Math.round(finite(processInfo?.rssBytesPeak)))
+    }));
   const expectedModifierAcks = Math.max(1, finite(modifier.expectedAcks, 8));
   const checks = [
     check(
@@ -301,10 +626,30 @@ export function classifyMacPhysicalGate(snapshot = {}) {
     ),
     check(
       'single-helper',
-      finite(helper.maxConcurrent) <= 1,
-      `max=${finite(helper.maxConcurrent)} pids=${helperPids.join(',') || '-'}`
+      resourceHelperPeak <= 1,
+      `max=${resourceHelperPeak} pids=${helperPids.join(',') || '-'}`
     ),
     check('helper-drained', finite(helper.finalCount) === 0, `final=${finite(helper.finalCount)}`),
+    check(
+      'process-telemetry',
+      resourceTelemetryAvailable,
+      resourceTelemetryAvailable
+        ? `baseline=${finite(baselineResources.sampleCount)} steady=${finite(steadyResources.sampleCount)} cleanup=${finite(cleanupResources.sampleCount)}`
+        : 'baseline, steady-capture, and after-cleanup samples are required'
+    ),
+    check(
+      'resource-ownership',
+      resourceTelemetryAvailable && resourceOwnershipCurrent,
+      `baseline=${finite(baselineResources.totalLiveDeskProcessCountPeak)} `
+        + `steady=${finite(steadyResources.totalLiveDeskProcessCountPeak)} `
+        + `unowned=${Array.isArray(steadyResources.unownedLiveDeskPids) ? steadyResources.unownedLiveDeskPids.join(',') || '-' : '-'}`
+    ),
+    check(
+      'resource-drained',
+      resourceTelemetryAvailable && resourceDrained,
+      `final=${finite(cleanupResources.totalLiveDeskProcessCount)} `
+        + `peak=${finite(cleanupResources.totalLiveDeskProcessCountPeak)}`
+    ),
     check('two-monitors', finite(monitor.count) >= 2, `count=${finite(monitor.count)}`),
     check(
       'monitor-generation',
@@ -350,6 +695,9 @@ export function classifyMacPhysicalGate(snapshot = {}) {
     'delivered-fps': 'agent-or-transport',
     'single-helper': 'duplicate-helper',
     'helper-drained': 'stale-helper',
+    'process-telemetry': 'process-telemetry',
+    'resource-ownership': 'resource-ownership',
+    'resource-drained': 'resource-not-drained',
     'two-monitors': 'monitor-topology',
     'monitor-generation': 'monitor-generation',
     'monitor-pixels': 'monitor-binding',
@@ -360,6 +708,11 @@ export function classifyMacPhysicalGate(snapshot = {}) {
     ok: failed.length === 0,
     idleOptimized,
     bottleneck: failed.length > 0 ? bottleneckByCheck[failed[0].id] || failed[0].id : 'none',
+    processTelemetry: {
+      available: resourceTelemetryAvailable,
+      highLoad: highCpuProcesses.length > 0,
+      highLoadProcesses: highCpuProcesses
+    },
     checks
   };
 }