livedesk 0.1.455 → 0.1.456

package/README.md

@@ -51,7 +51,7 @@ Pass `--no-clean` to disable the startup cleanup explicitly. If a child Hub
 still loses a startup race with `EADDRINUSE`, the launcher performs one cleanup
 and startup retry, then exits without looping.
 
-## Client compatibility
+## Client compatibility
 
 ```powershell
 npx -y --prefer-online livedesk@latest client 3
@@ -61,9 +61,36 @@ The `client` form remains as a legacy compatibility alias. It records the
 Client role and uses the same unified runtime lock. The client signs in with
 Google, discovers the active Hub, and connects to the wall. On Windows, enable
 **Start with Windows** on the connection page to reconnect automatically after
-reboot; the generated startup command uses the unified launcher.
-
-## Frame modes
+reboot; the generated startup command uses the unified launcher.
+
+## macOS physical diagnostic
+
+On a Mac with two connected displays, stop every running LiveDesk runtime,
+show visibly different content on the two displays, grant Screen Recording and
+Accessibility permissions, then run:
+
+```bash
+npx -y --prefer-online livedesk@latest diagnose mac-physical
+```
+
+This command branches before role resolution, state migration, and the normal
+runtime lock. It refuses to overlap an existing LiveDesk runtime or capture
+helper, and normal macOS startup reciprocally refuses an active diagnostic
+lease. It starts only an isolated loopback Hub and temporary RemoteFast Client
+and stops only the exact children it created. Ctrl+C and termination signals
+join the same owned cleanup before exit. The default JSON report is written to
+one final path after cleanup, and run/cleanup errors always produce a failed
+result. It is written under `~/.livedesk/diagnostics`. To select a path relative
+to the directory where the command was invoked:
+
+```bash
+npx -y --prefer-online livedesk@latest diagnose mac-physical --report ./mac-result.json
+```
+
+Use `diagnose mac-physical --help` to inspect requirements without starting a
+runtime or changing cached role/account state.
+
+## Frame modes
 
 - Mode 2: independent 320x180 RGB565+LZO tiles for large, stable walls.
 - Mode 3: direct hardware H.264 for focused remote control up to 4K.

package/bin/livedesk.js

@@ -34,6 +34,7 @@ import {
 import { runLegacyClientUpdateSupervisorCli } from '../bootstrap/legacy-client-update.js';
 import { transferSavedClientSessionToHub } from '../bootstrap/hub-auth-handoff.js';
 import { readWindowsOwnedProcessManifest } from '../client/src/runtime/windows-owned-process-manifest.js';
+import { inspectMacDiagnosticLease } from '../diagnostics/livedesk-mac-physical-isolation.mjs';
 
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -143,6 +144,22 @@ function isPidAlive(pid) {
   }
 }
 
+async function assertNoActiveMacPhysicalDiagnosticLease() {
+  if (os.platform() !== 'darwin') return;
+  const lease = await inspectMacDiagnosticLease();
+  if (lease.status === 'missing' || lease.status === 'stale') return;
+  if (lease.status === 'active') {
+    throw new Error(
+      `Mac physical diagnostic is running (pid ${lease.pid}); normal LiveDesk startup was not started. `
+      + 'Wait for its owned cleanup to finish or stop the diagnostic with Ctrl+C.'
+    );
+  }
+  throw new Error(
+    `Mac physical diagnostic ownership is unreadable at ${lease.path}; normal LiveDesk startup was not started `
+    + 'to avoid overlapping a capture runtime.'
+  );
+}
+
 function canClaimHubUpdateResult(current, next) {
   const currentOperationId = String(current?.operationId || '');
   const nextOperationId = String(next?.operationId || '');
@@ -312,15 +329,18 @@ function printHelp() {
   process.stdout.write(`
 LiveDesk
 
-Usage:
-  npx -y --prefer-online livedesk@latest
-  npx -y --prefer-online livedesk@latest --force-role hub
-  npx -y --prefer-online livedesk@latest --force-role client
-
-Commands:
-  No command     Resolve the signed-in device role and start the matching runtime.
-  hub            Legacy alias for --force-role hub.
-  client         Legacy alias for --force-role client.
+Usage:
+  npx -y --prefer-online livedesk@latest
+  npx -y --prefer-online livedesk@latest --force-role hub
+  npx -y --prefer-online livedesk@latest --force-role client
+  npx -y --prefer-online livedesk@latest diagnose mac-physical
+
+Commands:
+  No command     Resolve the signed-in device role and start the matching runtime.
+  hub            Legacy alias for --force-role hub.
+  client         Legacy alias for --force-role client.
+  diagnose mac-physical
+                 Run the isolated two-display macOS capture/control physical gate.
 
 Hub options:
   --no-open      Do not open the browser automatically.
@@ -342,10 +362,63 @@ Common:
                  Do not ask for a role on first run; fail if no role is known.
   --help         Show this help.
   --version      Show version.
-`.trimStart());
-}
-
-function printClientHelp() {
+`.trimStart());
+}
+
+function printMacPhysicalDiagnosticHelp() {
+  process.stdout.write(`
+LiveDesk macOS physical diagnostic
+
+Usage:
+  npx -y --prefer-online livedesk@latest diagnose mac-physical
+  npx -y --prefer-online livedesk@latest diagnose mac-physical --report ./mac-result.json
+
+Requirements:
+  macOS with two connected displays showing visibly different content.
+  Screen Recording permission for the terminal/LiveDesk capture helper.
+  Accessibility permission for the terminal/LiveDesk input helper.
+  Stop every existing LiveDesk Hub, Client, and desktop runtime first.
+
+Behavior:
+  Starts one isolated loopback Hub and one temporary RemoteFast Client.
+  Refuses to overlap a running LiveDesk runtime or capture helper.
+  Stops only the exact child processes created by this diagnostic.
+  Writes the default report under ~/.livedesk/diagnostics.
+
+Options:
+  --report <path>  Write the JSON report relative to the invocation directory.
+  --monitor <n>    Initial zero-based display index. Default: 0.
+  --width <px>     Requested capture width. Default: 1920.
+  --height <px>    Requested capture height. Default: 1080.
+  --help           Show this help without resolving a role or acquiring a runtime lock.
+`.trimStart());
+}
+
+async function runDiagnosticCommand(args) {
+  const name = String(args[0] || '').trim().toLowerCase();
+  if (!name || name === '--help' || name === '-h' || name === 'help') {
+    printMacPhysicalDiagnosticHelp();
+    return;
+  }
+  if (name !== 'mac-physical') {
+    throw new Error(`Unknown LiveDesk diagnostic: ${name}. Supported diagnostic: mac-physical.`);
+  }
+  if (args.slice(1).some(argument => ['--help', '-h', 'help'].includes(String(argument).toLowerCase()))) {
+    printMacPhysicalDiagnosticHelp();
+    return;
+  }
+  const diagnosticEntry = resolve(
+    packageRoot,
+    'diagnostics',
+    'livedesk-mode3-capture-smoke.mjs'
+  );
+  if (!existsSync(diagnosticEntry)) {
+    throw new Error(`LiveDesk mac-physical diagnostic is missing from this package: ${diagnosticEntry}`);
+  }
+  await import(pathToFileURL(diagnosticEntry).href);
+}
+
+function printClientHelp() {
   process.stdout.write(`
 LiveDesk Client
 
@@ -2847,8 +2920,14 @@ async function runDesktopRoleBootstrap() {
 
 async function main() {
   const rawArgs = process.argv.slice(2);
+  const rawCommand = String(rawArgs[0] || '').trim().toLowerCase();
+  if (rawCommand === 'diagnose') {
+    await runDiagnosticCommand(rawArgs.slice(1));
+    return;
+  }
   restoreUpdateOriginalCwd();
   if (rawArgs.includes('--internal-legacy-client-update')) {
+    await assertNoActiveMacPhysicalDiagnosticLease();
     await runLegacyClientUpdateSupervisorCli();
     return;
   }
@@ -2870,11 +2949,12 @@ async function main() {
     printHelp();
     return;
   }
-  if (command === '--version' || command === '-v' || command === 'version') {
-    console.log(readVersion());
-    return;
-  }
-  const explicitRoleCommand = command === 'hub' || command === 'manager' || command === 'client';
+  if (command === '--version' || command === '-v' || command === 'version') {
+    console.log(readVersion());
+    return;
+  }
+  await assertNoActiveMacPhysicalDiagnosticLease();
+  const explicitRoleCommand = command === 'hub' || command === 'manager' || command === 'client';
   let resolvedRole;
   let runtimeArgs = args;
   if (explicitRoleCommand) {

package/client/bin/livedesk-client.js

@@ -4795,8 +4795,8 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
     const parsed = parseLauncherArgs(argv);
     if (parsed.retiredModelOptionsDiscarded > 0) {
         console.warn(
-            '[LiveDesk Client] Ignored retired Client model-runtime options. '
-            + 'Approved AI computer commands are handled by the Hub Codex Agent.'
+            '[LiveDesk Client] Ignored retired Client options. '
+            + 'Computer commands are handled by the Hub Codex Agent.'
         );
     }
     if (parsed.updateWaitPid) {

package/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.210",
+  "version": "0.1.211",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -9,12 +9,12 @@
     "livedesk-client-node": "bin/livedesk-client-node.js",
     "livedesk-client-fast": "bin/livedesk-client-fast.js"
   },
-  "files": [
-    "bin/",
-    "src/",
-    "README.md",
-    "THIRD_PARTY_NOTICES.md"
-  ],
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
   "scripts": {
     "check": "node --check bin/client-version.js && node --check bin/livedesk-client.js && node --check bin/livedesk-client-node.js && node --check bin/livedesk-client-fast.js",
     "test:version": "node --test tests/client-version.test.mjs",
@@ -31,21 +31,21 @@
   "engines": {
     "node": ">=20"
   },
-  "dependencies": {
-    "@ffmpeg-installer/ffmpeg": "^1.1.0",
-    "ffmpeg-static": "^5.3.0",
-    "@livedesk/runtime-core": "0.1.0",
-    "@supabase/supabase-js": "^2.110.0",
-    "node-screenshots": "^0.2.8",
-    "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"
-  },
-  "publishConfig": {
+  "dependencies": {
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
+    "ffmpeg-static": "^5.3.0",
+    "@livedesk/runtime-core": "0.1.0",
+    "@supabase/supabase-js": "^2.110.0",
+    "node-screenshots": "^0.2.8",
+    "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"
+  },
+  "publishConfig": {
     "access": "public"
   }
 }

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

@@ -0,0 +1,365 @@
+import path from 'node:path';
+
+const MAC_VIDEO_HELPER_NAME = 'livedesk-sck-h264';
+const MAC_AUDIO_HELPER_NAME = 'livedesk-sck-audio';
+
+function normalizeProcessText(value) {
+  return String(value || '').trim().replaceAll('\\', '/');
+}
+
+function parseMacProcessRecords(psOutput) {
+  const records = [];
+  for (const rawLine of String(psOutput || '').split(/\r?\n/)) {
+    const match = rawLine.match(/^\s*(\d+)\s+(\d+)\s+(\S+)\s*(.*)$/);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    const parentPid = Number(match[2]);
+    if (!Number.isInteger(pid) || pid <= 1 || !Number.isInteger(parentPid)) continue;
+    records.push({
+      pid,
+      parentPid,
+      commandName: basenameWithoutQuotes(match[3]),
+      commandLine: String(match[4] || '').trim()
+    });
+  }
+  return records;
+}
+
+function isMacCaptureHelperRecord(record) {
+  const commandName = String(record?.commandName || '');
+  const commandLine = normalizeProcessText(record?.commandLine);
+  const executable = basenameWithoutQuotes(commandLine.split(/\s+/)[0]);
+  const videoPath = /(?:^|\/)\.livedesk\/helpers\/macos-sck-h264\/livedesk-sck-h264(?:\s|$)/i;
+  const audioPath = /(?:^|\/)\.livedesk\/helpers\/macos-sck-audio\/livedesk-sck-audio(?:\s|$)/i;
+  return commandName === MAC_VIDEO_HELPER_NAME
+    || commandName === 'livedesk-sck-h2'
+    || commandName === MAC_AUDIO_HELPER_NAME
+    || commandName === 'livedesk-sck-aud'
+    || executable === MAC_VIDEO_HELPER_NAME
+    || executable === MAC_AUDIO_HELPER_NAME
+    || videoPath.test(commandLine)
+    || audioPath.test(commandLine);
+}
+
+function finite(value, fallback = 0) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function basenameWithoutQuotes(value) {
+  return path.basename(String(value || '').trim().replace(/^["']|["']$/g, ''));
+}
+
+export function parseMacHelperProcesses(psOutput) {
+  return parseMacProcessRecords(psOutput).filter(isMacCaptureHelperRecord);
+}
+
+export function parseMacLiveDeskRuntimeProcesses(psOutput, { 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)) {
+    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';
+    }
+    if (!kind) continue;
+    results.push({
+      ...record,
+      kind
+    });
+  }
+  return results;
+}
+
+const MODIFIERS = Object.freeze([
+  { code: 'ShiftLeft', key: 'Shift', keyCode: 16, location: 1, flag: 'shiftKey' },
+  { code: 'ControlLeft', key: 'Control', keyCode: 17, location: 1, flag: 'ctrlKey' },
+  { code: 'AltLeft', key: 'Alt', keyCode: 18, location: 1, flag: 'altKey' },
+  { code: 'MetaLeft', key: 'Meta', keyCode: 91, location: 1, flag: 'metaKey' }
+]);
+
+export function buildMacModifierProbeSteps(startInputSeq = 1) {
+  const pressed = [];
+  const steps = [];
+  let inputSeq = Math.max(1, Math.floor(finite(startInputSeq, 1)));
+  const snapshot = () => ({
+    pressedCodes: [...pressed],
+    shiftKey: pressed.includes('ShiftLeft'),
+    ctrlKey: pressed.includes('ControlLeft'),
+    altKey: pressed.includes('AltLeft'),
+    metaKey: pressed.includes('MetaLeft')
+  });
+
+  for (const modifier of MODIFIERS) {
+    pressed.push(modifier.code);
+    steps.push({
+      type: 'keydown',
+      key: modifier.key,
+      code: modifier.code,
+      keyCode: modifier.keyCode,
+      location: modifier.location,
+      repeat: false,
+      inputSeq: inputSeq++,
+      ...snapshot()
+    });
+  }
+  for (const modifier of [...MODIFIERS].reverse()) {
+    pressed.splice(pressed.indexOf(modifier.code), 1);
+    steps.push({
+      type: 'keyup',
+      key: modifier.key,
+      code: modifier.code,
+      keyCode: modifier.keyCode,
+      location: modifier.location,
+      repeat: false,
+      inputSeq: inputSeq++,
+      ...snapshot()
+    });
+  }
+  return steps;
+}
+
+export function buildMacModifierReleaseSteps(pressedCodes = [], startInputSeq = 1) {
+  const pressed = MODIFIERS
+    .map(modifier => modifier.code)
+    .filter(code => Array.isArray(pressedCodes) && pressedCodes.includes(code));
+  const steps = [];
+  let inputSeq = Math.max(1, Math.floor(finite(startInputSeq, 1)));
+  for (const modifier of [...MODIFIERS].reverse()) {
+    const pressedIndex = pressed.indexOf(modifier.code);
+    if (pressedIndex < 0) continue;
+    pressed.splice(pressedIndex, 1);
+    steps.push({
+      type: 'keyup',
+      key: modifier.key,
+      code: modifier.code,
+      keyCode: modifier.keyCode,
+      location: modifier.location,
+      repeat: false,
+      inputSeq: inputSeq++,
+      pressedCodes: [...pressed],
+      shiftKey: pressed.includes('ShiftLeft'),
+      ctrlKey: pressed.includes('ControlLeft'),
+      altKey: pressed.includes('AltLeft'),
+      metaKey: pressed.includes('MetaLeft')
+    });
+  }
+  return steps;
+}
+
+export function noteMacModifierBeforeSend(pressedCodes, step = {}) {
+  if (!(pressedCodes instanceof Set)) {
+    throw new TypeError('Mac modifier pressed state must be a Set.');
+  }
+  const code = String(step.code || '').trim();
+  if (step.type === 'keydown' && code) {
+    // A timed-out ACK is ambiguous: the native keydown may already have been
+    // applied. Track it before the send boundary so cleanup remains fail-safe.
+    pressedCodes.add(code);
+  }
+  return pressedCodes;
+}
+
+export function noteMacModifierAfterAppliedAck(pressedCodes, step = {}) {
+  if (!(pressedCodes instanceof Set)) {
+    throw new TypeError('Mac modifier pressed state must be a Set.');
+  }
+  const code = String(step.code || '').trim();
+  if (step.type === 'keyup' && code) {
+    // Only a native applied ACK proves that releasing this key succeeded.
+    pressedCodes.delete(code);
+  }
+  return pressedCodes;
+}
+
+function check(id, ok, detail) {
+  return { id, ok: ok === true, detail: String(detail || '') };
+}
+
+export function classifyMacPhysicalGate(snapshot = {}) {
+  const requestedFps = Math.max(1, finite(snapshot.requestedFps, 30));
+  const minimumFps = requestedFps * 0.8;
+  const telemetry = snapshot.telemetry || {};
+  const helper = snapshot.helper || {};
+  const monitor = snapshot.monitor || {};
+  const modifier = snapshot.modifier || {};
+  const transport = snapshot.transport || {};
+  const diagnostic = snapshot.diagnostic || {};
+  const abortedSignal = String(diagnostic.abortedSignal || '').trim();
+  const runError = String(
+    diagnostic.runError
+    || snapshot.error
+    || (abortedSignal ? `interrupted by ${abortedSignal}` : '')
+    || ''
+  ).trim();
+  const cleanupErrors = Array.isArray(diagnostic.cleanupErrors)
+    ? diagnostic.cleanupErrors.map(value => String(value || '').trim()).filter(Boolean)
+    : [];
+  const captureFps = Math.max(0, finite(telemetry.captureFps));
+  const compressionFps = Math.max(0, finite(telemetry.compressionFps));
+  const stdoutFps = Math.max(0, finite(telemetry.stdoutFps));
+  const idleOptimized = finite(telemetry.idleSkipped) > 0
+    && finite(telemetry.backpressureSkipped) === 0;
+  const captureAtTarget = captureFps >= minimumFps;
+  const compressionKeepsUp = idleOptimized
+    || (captureFps > 0 && compressionFps >= captureFps * 0.8);
+  const stdoutKeepsUp = (idleOptimized && compressionFps <= 0)
+    || (compressionFps > 0 && stdoutFps >= compressionFps * 0.8);
+  const deliveredAtTarget = idleOptimized
+    || finite(snapshot.deliveredFps) >= minimumFps;
+  const helperPids = Array.isArray(helper.observedPids)
+    ? helper.observedPids.map(Number).filter(pid => Number.isInteger(pid) && pid > 1)
+    : [];
+  const expectedModifierAcks = Math.max(1, finite(modifier.expectedAcks, 8));
+  const checks = [
+    check(
+      'diagnostic-run',
+      !runError,
+      runError || 'completed'
+    ),
+    check(
+      'diagnostic-cleanup',
+      cleanupErrors.length === 0,
+      cleanupErrors.length === 0 ? 'completed' : cleanupErrors.join('; ')
+    ),
+    check(
+      'first-frame',
+      finite(snapshot.firstFrameMs) > 0 && finite(snapshot.firstFrameMs) < 8_000,
+      `${Math.round(finite(snapshot.firstFrameMs))}ms`
+    ),
+    check(
+      'monitor-first-frame',
+      finite(snapshot.monitorSwitchFirstFrameMs) > 0
+        && finite(snapshot.monitorSwitchFirstFrameMs) < 8_000,
+      `${Math.round(finite(snapshot.monitorSwitchFirstFrameMs))}ms`
+    ),
+    check(
+      'native-profile',
+      snapshot.platformProfile === 'macos-screencapturekit-nv12-videotoolbox',
+      snapshot.platformProfile || 'missing'
+    ),
+    check(
+      'telemetry-current',
+      finite(telemetry.version) >= 2
+        && Number.isFinite(Number(telemetry.ageMs))
+        && finite(telemetry.ageMs) <= 3_000,
+      `v${finite(telemetry.version)} age=${Number.isFinite(Number(telemetry.ageMs)) ? Math.round(finite(telemetry.ageMs)) : '-'}ms`
+    ),
+    check(
+      'hardware-videotoolbox',
+      telemetry.hardwareAccelerated === true,
+      telemetry.hardwareAccelerated === true ? 'hardware' : 'not-confirmed'
+    ),
+    check('screencapturekit-fps', captureAtTarget, `${captureFps.toFixed(1)}/${requestedFps}`),
+    check(
+      'videotoolbox-fps',
+      compressionKeepsUp,
+      `${compressionFps.toFixed(1)} after ${captureFps.toFixed(1)}${idleOptimized ? ' idle-optimized' : ''}`
+    ),
+    check(
+      'stdout-fps',
+      stdoutKeepsUp,
+      `${stdoutFps.toFixed(1)} after ${compressionFps.toFixed(1)}${idleOptimized ? ' idle-optimized' : ''}`
+    ),
+    check(
+      'delivered-fps',
+      deliveredAtTarget,
+      `${finite(snapshot.deliveredFps).toFixed(1)}/${requestedFps}${idleOptimized ? ' idle-optimized' : ''}`
+    ),
+    check(
+      'single-helper',
+      finite(helper.maxConcurrent) <= 1,
+      `max=${finite(helper.maxConcurrent)} pids=${helperPids.join(',') || '-'}`
+    ),
+    check('helper-drained', finite(helper.finalCount) === 0, `final=${finite(helper.finalCount)}`),
+    check('two-monitors', finite(monitor.count) >= 2, `count=${finite(monitor.count)}`),
+    check(
+      'monitor-generation',
+      finite(monitor.nextGeneration) > finite(monitor.initialGeneration),
+      `${finite(monitor.initialGeneration)} -> ${finite(monitor.nextGeneration)}`
+    ),
+    check(
+      'monitor-pixels',
+      Boolean(monitor.initialHash)
+        && Boolean(monitor.nextHash)
+        && monitor.initialHash !== monitor.nextHash,
+      `${String(monitor.initialHash || '-').slice(0, 12)} -> ${String(monitor.nextHash || '-').slice(0, 12)}`
+    ),
+    check(
+      'modifier-native-ack',
+      finite(modifier.appliedAcks) === expectedModifierAcks
+        && (!Array.isArray(modifier.errors) || modifier.errors.length === 0),
+      `${finite(modifier.appliedAcks)}/${expectedModifierAcks} native ACK`
+    ),
+    check(
+      'active-transport',
+      Boolean(String(transport.active || '').trim()),
+      [
+        String(transport.active || '-'),
+        String(transport.protocol || '-'),
+        String(transport.state || '-')
+      ].join('/')
+    )
+  ];
+
+  const failed = checks.filter(item => !item.ok);
+  const bottleneckByCheck = {
+    'diagnostic-run': 'diagnostic-run',
+    'diagnostic-cleanup': 'diagnostic-cleanup',
+    'first-frame': 'capture-startup',
+    'monitor-first-frame': 'monitor-restart',
+    'native-profile': 'capture-fallback',
+    'telemetry-current': 'native-telemetry-stale',
+    'hardware-videotoolbox': 'videotoolbox-software',
+    'screencapturekit-fps': 'screencapturekit',
+    'videotoolbox-fps': 'videotoolbox',
+    'stdout-fps': 'native-stdout',
+    'delivered-fps': 'agent-or-transport',
+    'single-helper': 'duplicate-helper',
+    'helper-drained': 'stale-helper',
+    'two-monitors': 'monitor-topology',
+    'monitor-generation': 'monitor-generation',
+    'monitor-pixels': 'monitor-binding',
+    'modifier-native-ack': 'remote-input',
+    'active-transport': 'transport-telemetry'
+  };
+  return {
+    ok: failed.length === 0,
+    idleOptimized,
+    bottleneck: failed.length > 0 ? bottleneckByCheck[failed[0].id] || failed[0].id : 'none',
+    checks
+  };
+}