livedesk 0.1.460 → 0.1.461

package/README.md

@@ -11,9 +11,15 @@ The `hub/`, `client/`, `runtime-core/`, and `web/` folders in this package are
 generated copies. Edit the source packages and run
 `node packages/livedesk/scripts/sync-web-dist.js` before building or packing
 the product. The published `livedesk` package owns both runtime roles; the
-source-only `@livedesk/client` workspace is not a runtime dependency.
-
-## Unified launch
+source-only `@livedesk/client` workspace is not a runtime dependency.
+
+LiveDesk's top runtime contract is transmission performance together with
+long-running stability. A faster path is not accepted if it permits duplicate
+capture helpers, stale monitor generations, unbounded frame queues, or an
+unproven Direct/P2P/relay transition. Release builds run the same lifecycle,
+transport recovery, and browser H.264 population gates used by CI.
+
+## Unified launch
 
 ```powershell
 npx -y --prefer-online livedesk@latest
@@ -90,9 +96,26 @@ npx -y --prefer-online livedesk@latest diagnose mac-physical --report ./mac-resu
 Use `diagnose mac-physical --help` to inspect requirements without starting a
 runtime or changing cached role/account state.
 
+## Physical transport diagnostic
+
+While the local Hub is running and at least one Client is sending a current
+Mode 3 H.264 stream, run:
+
+```bash
+npx -y --prefer-online livedesk@latest diagnose transport-physical
+```
+
+The diagnostic proves one unchanged stream identity through Direct TCP,
+encrypted UDP P2P, encrypted relay, and Direct recovery. Every phase requires
+an independently decodable SPS/PPS/IDR frame observed by the Hub within a
+bounded deadline. It uses an exact-owner temporary lease, changes no firewall
+or router settings, and writes a redacted report under
+`~/.livedesk/diagnostics`. Use `diagnose transport-physical --help` for
+device, Hub URL, timeout, and report-path options.
+
 ## Frame modes
-
-- Mode 2: independent 320x180 RGB565+LZO tiles for large, stable walls.
+
+- Mode 2: independent 320x180 RGB565+LZO tiles for large, stable walls.
 - Mode 3: direct hardware H.264 for focused remote control up to 4K.
 - Mode 4: client Mode 2 inputs composited by an isolated Hub worker into one
   bounded H.264 Atlas stream, then split by UV into the normal browser slots.

package/bin/livedesk.js

@@ -33,7 +33,11 @@ import {
 } from '../bootstrap/client-process-identity.js';
 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 {
+  consumeDeadWindowsOwnedProcessManifest,
+  readDeadWindowsOwnedProcessManifest,
+  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);
@@ -1012,6 +1016,57 @@ async function exactWindowsRecordsStillRunning(records) {
   return records.filter(record => sameExactWindowsProcess(currentByPid.get(record.pid), record));
 }
 
+async function exactReclaimedWindowsRecordsStillRunning(records) {
+  const targets = (Array.isArray(records) ? records : [])
+    .map(record => normalizeExactWindowsProcessRecord(record, record?.depth))
+    .filter(Boolean);
+  if (targets.length === 0) return [];
+  const targetPids = [...new Set(targets.map(record => record.pid))];
+  const script = [
+    '$ErrorActionPreference = "Stop";',
+    `$targetPids = @(${targetPids.join(',')});`,
+    '$records = @();',
+    'foreach ($targetPidValue in $targetPids) {',
+    '  $targetPid = [int]$targetPidValue;',
+    '  $target = Get-CimInstance Win32_Process -Filter "ProcessId = $targetPid" -Property ProcessId,ParentProcessId,CreationDate -ErrorAction SilentlyContinue | Select-Object -First 1;',
+    '  if (-not $target) { continue };',
+    '  $records += [pscustomobject]@{',
+    '    ProcessId = [int]$target.ProcessId;',
+    '    ParentProcessId = [int]$target.ParentProcessId;',
+    '    CreationUtcTicks = if ($target.CreationDate) { [string]$target.CreationDate.ToUniversalTime().Ticks } else { "" }',
+    '  };',
+    '}',
+    '[pscustomobject]@{ Records = $records } | ConvertTo-Json -Compress -Depth 4'
+  ].join(' ');
+  const result = await runQuiet(
+    'powershell.exe',
+    ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
+    { timeout: 10000, killSignal: 'SIGKILL' }
+  );
+  if (!result.ok || !result.stdout) {
+    throw new Error(
+      'LiveDesk could not revalidate the reclaimed Windows process identities: '
+      + `${result.stderr || result.error?.message || 'targeted CIM query failed'}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch (error) {
+    throw new Error(`LiveDesk could not parse reclaimed Windows process identities: ${error.message}`);
+  }
+  const values = parsed?.Records == null
+    ? []
+    : Array.isArray(parsed.Records) ? parsed.Records : [parsed.Records];
+  const currentByPid = new Map(
+    values
+      .map(item => normalizeExactWindowsProcessRecord(item))
+      .filter(Boolean)
+      .map(record => [record.pid, record])
+  );
+  return targets.filter(record => sameExactWindowsProcess(currentByPid.get(record.pid), record));
+}
+
 async function waitForExactWindowsRecordsExit(records, timeoutMs = 2500) {
   const deadline = Date.now() + timeoutMs;
   let remaining = records;
@@ -1061,6 +1116,124 @@ async function terminateExactWindowsProcesses(recordOrRecords) {
   );
 }
 
+function normalizeReclaimedWindowsClientOwner(value) {
+  const pid = Number(value?.pid || 0);
+  const ownerToken = String(value?.ownerToken || '').trim();
+  const ownerInstanceMarker = String(value?.ownerInstanceMarker || '').trim();
+  const ownerStartOrder = String(value?.ownerStartOrder || '').trim();
+  if (String(value?.role || '').trim().toLowerCase() !== 'client'
+      || !Number.isInteger(pid)
+      || pid <= 1
+      || !/^[a-f0-9]{32}$/i.test(ownerToken)
+      || !ownerInstanceMarker.startsWith(`${pid}:`)
+      || !/^\d+$/.test(ownerStartOrder)) {
+    return null;
+  }
+  return { pid, ownerToken, ownerInstanceMarker, ownerStartOrder };
+}
+
+async function observeExactWindowsRecordsEmptyTwice(records) {
+  let emptyObservations = 0;
+  while (emptyObservations < 2) {
+    const remaining = await exactReclaimedWindowsRecordsStillRunning(records);
+    if (remaining.length > 0) {
+      return { confirmed: false, remaining, emptyObservations };
+    }
+    emptyObservations += 1;
+    if (emptyObservations < 2) {
+      await waitMilliseconds(PORT_CLEANUP_POLL_MS);
+    }
+  }
+  return { confirmed: true, remaining: [], emptyObservations };
+}
+
+async function drainReclaimedWindowsClientManifest(reclaimedOwner, {
+  maxAttempts = 4
+} = {}) {
+  if (os.platform() !== 'win32') return { handled: false, reason: 'not-windows' };
+  const exactOwner = normalizeReclaimedWindowsClientOwner(reclaimedOwner);
+  if (!exactOwner) {
+    return { handled: false, reason: 'legacy-or-incomplete-owner' };
+  }
+
+  const inheritedManifest = readDeadWindowsOwnedProcessManifest({
+    stateDir: MANAGER_STATE_DIR,
+    owner: exactOwner
+  });
+  if (!inheritedManifest.ok) {
+    if (inheritedManifest.missing === true) {
+      if (process.env.LIVEDESK_DEBUG === '1') {
+        console.log(
+          `[LiveDesk] Reclaimed Windows Client generation ${exactOwner.pid} `
+          + 'has no exact process manifest; continuing legacy cleanup.'
+        );
+      }
+      return { handled: false, reason: 'manifest-missing' };
+    }
+    throw new Error(
+      'The reclaimed Windows Client process manifest was preserved because '
+      + `its exact owner, timestamp, or records could not be verified: ${
+        inheritedManifest.error?.message || 'manifest validation failed'
+      }`
+    );
+  }
+
+  const tracked = inheritedManifest.records
+    .map(record => normalizeExactWindowsProcessRecord(record, record?.depth))
+    .filter(Boolean);
+  if (tracked.some(record => record.pid === process.pid)) {
+    throw new Error(
+      'The reclaimed Windows Client process manifest unexpectedly named the '
+      + 'new launcher; every recorded process was preserved.'
+    );
+  }
+
+  const attempts = Math.max(1, Number(maxAttempts) || 4);
+  let lastTerminationError = null;
+  for (let attempt = 0; attempt <= attempts; attempt += 1) {
+    const observation = await observeExactWindowsRecordsEmptyTwice(tracked);
+    if (observation.confirmed) {
+      const consumedManifest = consumeDeadWindowsOwnedProcessManifest({
+        stateDir: MANAGER_STATE_DIR,
+        owner: exactOwner,
+        revision: inheritedManifest.revision
+      });
+      if (!consumedManifest.ok) {
+        throw new Error(
+          'The reclaimed Windows Client process manifest was preserved after '
+          + `drain because its exact revision could not be consumed safely: ${
+            consumedManifest.error?.message || 'manifest consumption failed'
+          }`
+        );
+      }
+      if (process.env.LIVEDESK_DEBUG === '1') {
+        console.log(
+          `[LiveDesk] Reclaimed Windows Client generation ${exactOwner.pid} `
+          + `drained ${tracked.length} exact process record(s) and consumed its manifest.`
+        );
+      }
+      return { handled: true, records: tracked, consumedManifest };
+    }
+    if (attempt === attempts) break;
+
+    const descendantFirst = [...observation.remaining].sort((left, right) => (
+      Number(right.depth || 0) - Number(left.depth || 0)
+    ));
+    const result = await terminateExactWindowsProcesses(descendantFirst);
+    if (!result.ok) {
+      lastTerminationError = result.error || new Error(result.stderr || 'termination failed');
+    }
+    await waitMilliseconds(PORT_CLEANUP_POLL_MS);
+  }
+
+  const finalRemaining = await exactReclaimedWindowsRecordsStillRunning(tracked);
+  throw new Error(
+    'The reclaimed Windows Client generation retained exact pid(s): '
+    + `${finalRemaining.map(record => record.pid).join(', ') || 'unknown'}`
+    + `${lastTerminationError?.message ? ` (${lastTerminationError.message})` : ''}`
+  );
+}
+
 async function terminateExactWindowsProcessTree(rootDetails, {
   label = 'LiveDesk process tree',
   maxAttempts = 4,
@@ -3095,6 +3268,21 @@ async function main() {
   }
 
   if (resolvedRole.role === 'client') {
+    // A launcher and Agent can both die while an independently spawned FFmpeg
+    // survives. Before any new Client process starts, consume only the exact
+    // manifest generation returned by the stale-lock compare-and-swap. No
+    // process-name scan participates in this recovery path.
+    const reclaimedManifestDrain = await drainReclaimedWindowsClientManifest(lock.reclaimedOwner);
+    const testHoldAfterDrainMs = Number(
+      process.env.LIVEDESK_TEST_HOLD_AFTER_RECLAIMED_WINDOWS_DRAIN_MS || 0
+    );
+    if (reclaimedManifestDrain.handled
+        && process.env.LIVEDESK_DEBUG === '1'
+        && Number.isFinite(testHoldAfterDrainMs)
+        && testHoldAfterDrainMs > 0) {
+      console.log('[LiveDesk test] Holding after reclaimed manifest drain before Client startup.');
+      await waitMilliseconds(Math.min(60_000, Math.round(testHoldAfterDrainMs)));
+    }
     const clientRuntimePort = normalizePort(
       process.env.LIVEDESK_CLIENT_RUNTIME_PORT || process.env.LIVEDESK_LOCAL_RUNTIME_PORT,
       DEFAULT_MANAGER_HTTP_PORT

package/bootstrap/runtime-lock.js

@@ -300,6 +300,7 @@ export function acquireRuntimeLock({
       acquired: true,
       path,
       payload,
+      reclaimedOwner: null,
       release,
       updateRole: nextRole => updateOwnedLockRole(path, payload, nextRole)
     };
@@ -352,10 +353,15 @@ export function acquireRuntimeLock({
           released = true;
           releaseOwnedLock(path, payload);
         };
+        // Preserve the exact generation that this compare-and-swap replaced.
+        // Windows Client startup uses only this immutable tuple to consume the
+        // prior generation's exact PID + CreationDate child manifest.
+        const reclaimedOwner = Object.freeze({ ...existing });
         return {
           acquired: true,
           path,
           payload,
+          reclaimedOwner,
           release,
           updateRole: nextRole => updateOwnedLockRole(path, payload, nextRole)
         };

package/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.213",
+  "version": "0.1.214",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -10,9 +10,10 @@
     "livedesk-client-fast": "bin/livedesk-client-fast.js"
   },
   "files": [
-    "bin/",
-    "src/",
-    "README.md",
+    "bin/",
+    "src/",
+    "tests/",
+    "README.md",
     "THIRD_PARTY_NOTICES.md"
   ],
   "scripts": {
@@ -40,10 +41,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.417",
-    "@livedesk/fast-osx-arm64": "0.1.417",
-    "@livedesk/fast-osx-x64": "0.1.417",
-    "@livedesk/fast-win-x64": "0.1.417"
+    "@livedesk/fast-linux-x64": "0.1.419",
+    "@livedesk/fast-osx-arm64": "0.1.419",
+    "@livedesk/fast-osx-x64": "0.1.419",
+    "@livedesk/fast-win-x64": "0.1.419"
   },
   "publishConfig": {
     "access": "public"

package/client/src/runtime/windows-owned-process-manifest.js

@@ -1,6 +1,7 @@
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import {
     chmodSync,
+    linkSync,
     mkdirSync,
     readFileSync,
     renameSync,
@@ -85,6 +86,10 @@ function normalizeRecords(values) {
     return [...unique.values()];
 }
 
+function sourceRevision(sourceText) {
+    return createHash('sha256').update(String(sourceText || ''), 'utf8').digest('hex');
+}
+
 function writeJsonAtomic(path, value) {
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     const temporaryPath = `${path}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
@@ -157,19 +162,16 @@ export function writeWindowsOwnedProcessManifest({
     }
 }
 
-/**
- * Reads only a fresh manifest belonging to the exact runtime-lock generation.
- * Owner mismatch, malformed identity, expiry, and PID reuse all fail closed.
- */
-export function readWindowsOwnedProcessManifest({
+function readExactWindowsOwnedProcessManifest({
     stateDir,
     owner,
-    maxAgeMs = DEFAULT_WINDOWS_OWNED_PROCESS_MANIFEST_MAX_AGE_MS,
+    maxAgeMs = null,
+    includeRevision = false,
     now
 } = {}) {
     const exactOwner = normalizeOwner(owner);
     const nowMs = resolveNow(now);
-    const maximumAge = Number(maxAgeMs);
+    const maximumAge = maxAgeMs === null ? null : Number(maxAgeMs);
     const path = getWindowsOwnedProcessManifestPath(stateDir);
     if (!exactOwner) {
         return {
@@ -179,8 +181,8 @@ export function readWindowsOwnedProcessManifest({
         };
     }
     if (!Number.isFinite(nowMs)
-        || !Number.isFinite(maximumAge)
-        || maximumAge < 0) {
+        || (maximumAge !== null
+            && (!Number.isFinite(maximumAge) || maximumAge < 0))) {
         return {
             ok: false,
             records: [],
@@ -189,10 +191,17 @@ export function readWindowsOwnedProcessManifest({
     }
 
     let parsed;
+    let sourceText;
     try {
-        parsed = JSON.parse(readFileSync(path, 'utf8'));
+        sourceText = readFileSync(path, 'utf8');
+        parsed = JSON.parse(sourceText);
     } catch (error) {
-        return { ok: false, records: [], error };
+        return {
+            ok: false,
+            records: [],
+            missing: error?.code === 'ENOENT',
+            error
+        };
     }
     const updatedAt = String(parsed?.updatedAt || '');
     const updatedAtMs = Date.parse(updatedAt);
@@ -214,7 +223,7 @@ export function readWindowsOwnedProcessManifest({
     }
     if (!Number.isFinite(updatedAtMs)
         || updatedAtMs > nowMs + MAX_FUTURE_CLOCK_SKEW_MS
-        || nowMs - updatedAtMs > maximumAge) {
+        || (maximumAge !== null && nowMs - updatedAtMs > maximumAge)) {
         return {
             ok: false,
             records: [],
@@ -231,5 +240,163 @@ export function readWindowsOwnedProcessManifest({
             error: resultError('Windows LiveDesk process manifest contains an invalid process identity.')
         };
     }
-    return { ok: true, records: exactRecords, updatedAt };
+    return {
+        ok: true,
+        records: exactRecords,
+        updatedAt,
+        ...(includeRevision ? { revision: sourceRevision(sourceText) } : {})
+    };
+}
+
+/**
+ * Reads only a fresh manifest belonging to the exact runtime-lock generation.
+ * Owner mismatch, malformed identity, expiry, and PID reuse all fail closed.
+ */
+export function readWindowsOwnedProcessManifest({
+    stateDir,
+    owner,
+    maxAgeMs = DEFAULT_WINDOWS_OWNED_PROCESS_MANIFEST_MAX_AGE_MS,
+    now
+} = {}) {
+    return readExactWindowsOwnedProcessManifest({
+        stateDir,
+        owner,
+        maxAgeMs,
+        now
+    });
+}
+
+/**
+ * Recovers only the exact manifest generation returned by a successful
+ * stale-lock compare-and-swap. Its age is intentionally unbounded because a
+ * machine can be restarted long after the launcher and Agent died. Malformed,
+ * mismatched, or future-dated manifests still fail closed.
+ */
+export function readDeadWindowsOwnedProcessManifest({
+    stateDir,
+    owner,
+    now
+} = {}) {
+    return readExactWindowsOwnedProcessManifest({
+        stateDir,
+        owner,
+        maxAgeMs: null,
+        includeRevision: true,
+        now
+    });
+}
+
+/**
+ * Atomically quarantines and consumes only the exact dead-owner manifest
+ * revision that was drained. If another generation replaces the canonical
+ * path between validation and rename, the moved file is restored or preserved
+ * instead of ever being deleted.
+ */
+export function consumeDeadWindowsOwnedProcessManifest({
+    stateDir,
+    owner,
+    revision,
+    now
+} = {}) {
+    const exactOwner = normalizeOwner(owner);
+    const expectedRevision = String(revision || '').trim().toLowerCase();
+    const nowMs = resolveNow(now);
+    const path = getWindowsOwnedProcessManifestPath(stateDir);
+    if (!exactOwner || !/^[a-f0-9]{64}$/.test(expectedRevision)) {
+        return {
+            ok: false,
+            error: resultError('An exact Windows manifest owner and revision are required for consumption.')
+        };
+    }
+    if (!Number.isFinite(nowMs)) {
+        return { ok: false, error: resultError('A valid manifest consumption time is required.') };
+    }
+
+    const current = readDeadWindowsOwnedProcessManifest({
+        stateDir,
+        owner: exactOwner,
+        now: nowMs
+    });
+    if (!current.ok) {
+        return current.missing === true
+            ? { ok: true, path, consumed: false, missing: true }
+            : { ...current, path, consumed: false };
+    }
+    if (current.revision !== expectedRevision) {
+        return {
+            ok: false,
+            path,
+            consumed: false,
+            error: resultError('Windows LiveDesk process manifest changed after its exact process set was drained.')
+        };
+    }
+
+    const quarantinePath = `${path}.consume.${process.pid}.${randomBytes(8).toString('hex')}`;
+    try {
+        renameSync(path, quarantinePath);
+    } catch (error) {
+        return { ok: false, path, quarantinePath, consumed: false, error };
+    }
+
+    let movedSourceText = '';
+    let movedParsed = null;
+    try {
+        movedSourceText = readFileSync(quarantinePath, 'utf8');
+        movedParsed = JSON.parse(movedSourceText);
+    } catch {
+        // The exact post-rename validation below restores or preserves this
+        // file; unreadable content is never evidence that deletion is safe.
+    }
+    const movedUpdatedAtMs = Date.parse(String(movedParsed?.updatedAt || ''));
+    const movedRecords = normalizeRecords(movedParsed?.records);
+    const movedIsExact = movedParsed?.protocolVersion === WINDOWS_OWNED_PROCESS_MANIFEST_VERSION
+        && ownersMatch(movedParsed?.owner, exactOwner)
+        && Number.isFinite(movedUpdatedAtMs)
+        && movedUpdatedAtMs <= nowMs + MAX_FUTURE_CLOCK_SKEW_MS
+        && movedRecords !== null
+        && sourceRevision(movedSourceText) === expectedRevision;
+    if (!movedIsExact) {
+        let restored = false;
+        let restoreError = null;
+        try {
+            // Hard-link publication is create-if-absent. Unlike rename, it
+            // can never overwrite a newer canonical generation that appears
+            // during restoration.
+            linkSync(quarantinePath, path);
+            restored = true;
+            try { unlinkSync(quarantinePath); } catch { /* both exact links safely preserve the file */ }
+        } catch (error) {
+            restoreError = error;
+        }
+        return {
+            ok: false,
+            path,
+            quarantinePath: restored ? undefined : quarantinePath,
+            consumed: false,
+            error: resultError(
+                'Windows LiveDesk process manifest changed during consumption; '
+                + `${restored ? 'the moved generation was restored.' : 'the moved generation was preserved.'}`
+                + `${restoreError?.message ? ` ${restoreError.message}` : ''}`
+            )
+        };
+    }
+
+    try {
+        unlinkSync(quarantinePath);
+        return {
+            ok: true,
+            path,
+            revision: expectedRevision,
+            records: movedRecords,
+            consumed: true
+        };
+    } catch (error) {
+        return {
+            ok: false,
+            path,
+            quarantinePath,
+            consumed: false,
+            error
+        };
+    }
 }