livedesk 0.1.446 → 0.1.447

package/bin/livedesk.js

@@ -18,9 +18,13 @@ import {
 } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import os from 'node:os';
-import { resolveDeviceRole, writeRoleCache } from '../bootstrap/device-role.js';
-import { acquireRuntimeLock } from '../bootstrap/runtime-lock.js';
-import { migrateLegacyClientState } from '../bootstrap/state-migration.js';
+import { resolveDeviceRole, writeRoleCache } from '../bootstrap/device-role.js';
+import { acquireRuntimeLock, getRuntimeLockPath } from '../bootstrap/runtime-lock.js';
+import {
+  requestCooperativeRuntimeShutdown,
+  startRuntimeShutdownWatcher
+} from '../bootstrap/runtime-shutdown.js';
+import { migrateLegacyClientState } from '../bootstrap/state-migration.js';
 import { createRoleBootstrapServer } from '../bootstrap/role-bootstrap-server.js';
 import { parseLsofPids } from '../bootstrap/port-inspection.js';
 import {
@@ -29,6 +33,7 @@ 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';
 
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -710,6 +715,7 @@ async function getProcessDetails(pid) {
       executablePath = '';
     }
   }
+  const nativeStartOrder = readLinuxProcessStartMarker(processId) || startResult.stdout;
   return {
     processId,
     parentProcessId: Number(parentResult.stdout || 0),
@@ -717,7 +723,8 @@ async function getProcessDetails(pid) {
     commandLine: commandResult.stdout,
     executablePath,
     processGroupId: Number(groupResult.stdout || 0),
-    startMarker: readLinuxProcessStartMarker(processId) || startResult.stdout
+    startMarker: nativeStartOrder,
+    startOrder: nativeStartOrder
   };
 }
 
@@ -796,77 +803,490 @@ async function waitForProcessExit(pid, timeoutMs = EXISTING_RUNTIME_STOP_TIMEOUT
   throw new Error(`Existing LiveDesk runtime ${processId} did not exit before the restart deadline.`);
 }
 
+function normalizeExactWindowsProcessRecord(value, depth = 0) {
+  const pid = Number(value?.pid ?? value?.processId ?? value?.ProcessId ?? 0);
+  const parentPid = Number(
+    value?.parentPid ?? value?.parentProcessId ?? value?.ParentProcessId ?? 0
+  );
+  const startOrder = String(
+    value?.startOrder ?? value?.CreationUtcTicks ?? ''
+  ).trim();
+  if (!Number.isInteger(pid) || pid <= 1 || !/^\d+$/.test(startOrder)) return null;
+  return {
+    pid,
+    parentPid: Number.isInteger(parentPid) && parentPid >= 0 ? parentPid : 0,
+    startOrder,
+    depth: Math.max(0, Number(depth) || 0)
+  };
+}
+
+function sameExactWindowsProcess(left, right) {
+  return Number(left?.pid || 0) === Number(right?.pid || 0)
+    && String(left?.startOrder || '') === String(right?.startOrder || '');
+}
+
+function windowsProcessStartedWithinParentLifetime(record, parent, parentExitedAtMs = null) {
+  try {
+    const childStart = BigInt(record.startOrder);
+    if (childStart < BigInt(parent.startOrder)) return false;
+    if (parentExitedAtMs === null) return true;
+    const parentExitTicks = BigInt(Math.trunc(parentExitedAtMs)) * 10_000n
+      + 621_355_968_000_000_000n;
+    return childStart <= parentExitTicks;
+  } catch {
+    return false;
+  }
+}
+
+async function queryExactWindowsProcessSnapshot() {
+  const script = [
+    '$ErrorActionPreference = "Stop";',
+    '$records = @(Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate | ForEach-Object {',
+    '  $creationUtcTicks = if ($_.CreationDate) { [string]$_.CreationDate.ToUniversalTime().Ticks } else { "" };',
+    '  [pscustomobject]@{ ProcessId = [int]$_.ProcessId; ParentProcessId = [int]$_.ParentProcessId; CreationUtcTicks = $creationUtcTicks }',
+    '});',
+    '[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 establish an immutable Windows process snapshot: '
+      + `${result.stderr || result.error?.message || 'CIM query failed'}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch (error) {
+    throw new Error(`LiveDesk could not parse the immutable Windows process snapshot: ${error.message}`);
+  }
+  const records = parsed?.Records == null
+    ? []
+    : Array.isArray(parsed.Records) ? parsed.Records : [parsed.Records];
+  return records.map(item => normalizeExactWindowsProcessRecord(item)).filter(Boolean);
+}
+
+async function captureExactWindowsProcessTree(rootDetails, { rootExitedAtMs = null } = {}) {
+  const rootRecord = normalizeExactWindowsProcessRecord(rootDetails, 0);
+  if (!rootRecord) {
+    throw new Error('LiveDesk could not establish the launcher CreationDate identity; it was preserved.');
+  }
+  const snapshot = await queryExactWindowsProcessSnapshot();
+  const currentByPid = new Map(snapshot.map(record => [record.pid, record]));
+  const currentRoot = currentByPid.get(rootRecord.pid) || null;
+  if (currentRoot && !sameExactWindowsProcess(currentRoot, rootRecord)) {
+    throw new Error(
+      `Windows pid=${rootRecord.pid} was reused before its exact tree could be captured; `
+      + 'the replacement process was preserved.'
+    );
+  }
+  if (!currentRoot && rootExitedAtMs === null) return [];
+
+  const childrenByParent = new Map();
+  for (const record of snapshot) {
+    if (!childrenByParent.has(record.parentPid)) childrenByParent.set(record.parentPid, []);
+    childrenByParent.get(record.parentPid).push(record);
+  }
+  const records = currentRoot ? [{ ...currentRoot, depth: 0 }] : [];
+  const queue = [{
+    record: currentRoot || rootRecord,
+    depth: 0,
+    exitedAtMs: currentRoot ? null : rootExitedAtMs
+  }];
+  const seen = new Set([rootRecord.pid]);
+  while (queue.length > 0) {
+    const parent = queue.shift();
+    for (const child of childrenByParent.get(parent.record.pid) || []) {
+      if (seen.has(child.pid)) continue;
+      if (!windowsProcessStartedWithinParentLifetime(
+        child,
+        parent.record,
+        parent.exitedAtMs
+      )) continue;
+      seen.add(child.pid);
+      const descendant = { ...child, depth: parent.depth + 1 };
+      records.push(descendant);
+      queue.push({ record: descendant, depth: descendant.depth, exitedAtMs: null });
+    }
+  }
+  return records;
+}
+
+async function exactWindowsRecordsStillRunning(records) {
+  if (!Array.isArray(records) || records.length === 0) return [];
+  const snapshot = await queryExactWindowsProcessSnapshot();
+  const currentByPid = new Map(snapshot.map(record => [record.pid, record]));
+  return records.filter(record => sameExactWindowsProcess(currentByPid.get(record.pid), record));
+}
+
+async function waitForExactWindowsRecordsExit(records, timeoutMs = 2500) {
+  const deadline = Date.now() + timeoutMs;
+  let remaining = records;
+  while (remaining.length > 0 && Date.now() < deadline) {
+    remaining = await exactWindowsRecordsStillRunning(remaining);
+    if (remaining.length === 0) return [];
+    await waitMilliseconds(Math.min(100, Math.max(1, deadline - Date.now())));
+  }
+  return exactWindowsRecordsStillRunning(remaining);
+}
+
+async function terminateExactWindowsProcesses(recordOrRecords) {
+  const targets = (Array.isArray(recordOrRecords) ? recordOrRecords : [recordOrRecords])
+    .map(record => normalizeExactWindowsProcessRecord(record, record?.depth))
+    .filter(Boolean);
+  if (targets.length === 0) {
+    throw new Error('LiveDesk refused to terminate Windows processes without immutable CreationDates.');
+  }
+  const targetsJson = JSON.stringify(targets.map(target => ({
+    pid: target.pid,
+    startOrder: target.startOrder
+  }))).replaceAll("'", "''");
+  const script = [
+    '$ErrorActionPreference = "Stop";',
+    `$targets = ConvertFrom-Json -InputObject '${targetsJson}';`,
+    '$failures = [System.Collections.Generic.List[string]]::new();',
+    'foreach ($item in $targets) {',
+    '  $targetPid = [int]$item.pid;',
+    '  $expectedStartTicks = [string]$item.startOrder;',
+    '  try {',
+    '    $target = Get-CimInstance Win32_Process -Filter "ProcessId = $targetPid" -Property ProcessId,CreationDate -ErrorAction SilentlyContinue | Select-Object -First 1;',
+    '    if (-not $target) { continue };',
+    '    $targetStartTicks = if ($target.CreationDate) { [string]$target.CreationDate.ToUniversalTime().Ticks } else { "" };',
+    '    if ($targetStartTicks -ne $expectedStartTicks) { continue };',
+    '    Stop-Process -Id $targetPid -Force -ErrorAction Stop;',
+    '  } catch {',
+    '    $failures.Add("pid=$targetPid $($_.Exception.Message)");',
+    '  }',
+    '}',
+    'if ($failures.Count -gt 0) { [Console]::Error.WriteLine(($failures -join "; ")); exit 1 };',
+    'exit 0;'
+  ].join(' ');
+  return runQuiet(
+    'powershell.exe',
+    ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
+    { timeout: 15000, killSignal: 'SIGKILL' }
+  );
+}
+
+async function terminateExactWindowsProcessTree(rootDetails, {
+  label = 'LiveDesk process tree',
+  maxAttempts = 4,
+  additionalRecords = []
+} = {}) {
+  const rootRecord = normalizeExactWindowsProcessRecord(rootDetails, 0);
+  if (!rootRecord) {
+    throw new Error(`Cannot terminate ${label} without an immutable Windows CreationDate.`);
+  }
+  const tracked = new Map();
+  const mergeRecords = records => {
+    for (const record of records) {
+      const normalized = normalizeExactWindowsProcessRecord(record, record?.depth);
+      if (normalized) tracked.set(`${normalized.pid}:${normalized.startOrder}`, normalized);
+    }
+  };
+  let rootExitedAtMs = null;
+  // A Client persists every immutable Agent/capture descendant it has
+  // observed. Seed that exact handoff before walking the still-live PPID tree:
+  // an FFmpeg whose Agent parent already exited is no longer discoverable by
+  // ancestry, but PID + CreationDate still makes it safe to terminate.
+  mergeRecords(additionalRecords);
+  mergeRecords(await captureExactWindowsProcessTree(rootRecord));
+  if (tracked.size === 0) {
+    rootExitedAtMs = Date.now();
+    mergeRecords(await captureExactWindowsProcessTree(rootRecord, { rootExitedAtMs }));
+  }
+
+  const attempts = Math.max(1, Number(maxAttempts) || 4);
+  let lastTaskkillError = null;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    let remaining = await exactWindowsRecordsStillRunning([...tracked.values()]);
+    if (!remaining.some(record => sameExactWindowsProcess(record, rootRecord))
+        && rootExitedAtMs === null) {
+      rootExitedAtMs = Date.now();
+    }
+    mergeRecords(await captureExactWindowsProcessTree(rootRecord, { rootExitedAtMs }));
+    remaining = await exactWindowsRecordsStillRunning([...tracked.values()]);
+    if (remaining.length === 0) return;
+
+    const descendantFirst = [...remaining].sort((left, right) => (
+      Number(right.depth || 0) - Number(left.depth || 0)
+    ));
+    // The whole descendant-first batch uses one PowerShell invocation. Each
+    // target is still rechecked immediately before its own Stop-Process.
+    // Never use taskkill /T: its descendants are not identity-checked.
+    const result = await terminateExactWindowsProcesses(descendantFirst);
+    if (!result.ok) lastTaskkillError = result.error || new Error(result.stderr || 'termination failed');
+    remaining = await waitForExactWindowsRecordsExit(remaining);
+    if (remaining.length === 0) {
+      if (rootExitedAtMs === null) rootExitedAtMs = Date.now();
+      const lateDescendants = await captureExactWindowsProcessTree(rootRecord, { rootExitedAtMs });
+      mergeRecords(lateDescendants);
+      remaining = await exactWindowsRecordsStillRunning([...tracked.values()]);
+      if (remaining.length === 0) return;
+    }
+    if (attempt < attempts) await waitMilliseconds(100);
+  }
+
+  const remaining = await exactWindowsRecordsStillRunning([...tracked.values()]);
+  throw new Error(
+    `${label} retained exact pid(s): ${remaining.map(record => record.pid).join(', ') || 'unknown'}`
+    + `${lastTaskkillError?.message ? ` (${lastTaskkillError.message})` : ''}`
+  );
+}
+
 async function stopExistingRuntime(existing) {
   const processId = Number(existing?.pid);
-  if (!Number.isInteger(processId) || processId <= 1 || processId === process.pid) {
+  if (!Number.isInteger(processId) || processId <= 1) {
     throw new Error('Existing LiveDesk runtime has an invalid process id; it was preserved.');
   }
+  const storedOwnerToken = String(existing?.ownerToken || '').trim();
+  const storedOwnerInstanceMarker = String(existing?.ownerInstanceMarker || '').trim();
+  const storedOwnerStartOrder = String(existing?.ownerStartOrder || '').trim();
+  const hasCompleteStoredOwner = storedOwnerToken.length >= 16
+    && !!storedOwnerInstanceMarker
+    && !!storedOwnerStartOrder;
+  const canRequestCooperativeStop = /^[a-f0-9]{32}$/i.test(storedOwnerToken)
+    && !!storedOwnerInstanceMarker
+    && !!storedOwnerStartOrder;
+  const exactStaleOwnerProof = hasCompleteStoredOwner
+    ? {
+        pid: processId,
+        ownerToken: storedOwnerToken,
+        ownerInstanceMarker: storedOwnerInstanceMarker,
+        ownerStartOrder: storedOwnerStartOrder
+      }
+    : null;
+  if (processId === process.pid) {
+    throw new Error('Existing LiveDesk runtime resolves to this launcher without an exact stale-owner proof; it was preserved.');
+  }
 
-  const details = await getProcessDetails(processId);
-  if (!details) {
-    return null;
+  // The mailbox is non-destructive and authenticates the current lock token.
+  // Try it before command-line/API proof: on macOS an npx shim can be opaque
+  // and the local status API can be busy, while the exact live owner can still
+  // acknowledge and drain its own capture tree safely.
+  const existingRole = String(existing?.role || '').trim().toLowerCase();
+  const cooperativeTimeoutMs = existingRole === 'hub' ? 16_000 : 14_000;
+  // Calling the requester publishes the atomic mailbox file synchronously
+  // before its first await. Start it before process inspection so a blocked
+  // CIM/ps query cannot delay the old launcher seeing the request.
+  const cooperativeStopPromise = canRequestCooperativeStop
+    ? requestCooperativeRuntimeShutdown({
+        stateDir: MANAGER_STATE_DIR,
+        target: existing,
+        reason: 'replacement-launch',
+        timeoutMs: cooperativeTimeoutMs,
+        ackTimeoutMs: 2_000,
+        pollMs: 100,
+        // A cheap PID probe is sufficient while waiting: every destructive
+        // fallback below rechecks the immutable CreationDate/start marker.
+        isTargetAlive: async () => isPidAlive(processId)
+      })
+    : Promise.resolve({
+        requested: false,
+        acknowledged: false,
+        exited: false,
+        timedOut: false,
+        ackStatus: ''
+      });
+  const detailsPromise = getProcessDetails(processId).catch(() => null);
+  const cooperativeStop = await cooperativeStopPromise;
+  if (cooperativeStop.exited) {
+    console.log(
+      `[LiveDesk] Existing ${existing?.role || 'runtime'} launcher pid ${processId} `
+      + 'accepted cooperative cleanup and exited before replacement (identity=exact-owner-mailbox).'
+    );
+    return { runtimeProof: null, staleOwnerProof: null };
+  }
+  let details = await detailsPromise;
+
+  const fallbackDetails = await getProcessDetails(processId);
+  if (!fallbackDetails) {
+    if (!isPidAlive(processId)) {
+      return { runtimeProof: null, staleOwnerProof: null };
+    }
+    throw new Error(
+      `Existing runtime pid ${processId} remained alive but its process identity could not be revalidated; `
+      + 'it was preserved.'
+    );
   }
+  if (details
+    && (processInstanceMarker(fallbackDetails) !== processInstanceMarker(details)
+      || String(fallbackDetails.startOrder || '') !== String(details.startOrder || ''))) {
+    console.warn(
+      `[LiveDesk] Launcher pid ${processId} changed identity while cooperative cleanup was pending; `
+      + 'the reused process was preserved.'
+    );
+    if (exactStaleOwnerProof) {
+      return { runtimeProof: null, staleOwnerProof: exactStaleOwnerProof };
+    }
+    throw new Error(`Existing runtime pid ${processId} was reused during shutdown; the current process was preserved.`);
+  }
+  details = fallbackDetails;
+  const currentOwnerStartOrder = String(details?.startOrder || '').trim();
+  if (hasCompleteStoredOwner
+    && currentOwnerStartOrder
+    && storedOwnerStartOrder !== currentOwnerStartOrder) {
+    console.warn(
+      `[LiveDesk] Runtime lock pid ${processId} was reused by a different process instance; `
+      + 'the current process was preserved and only the exact stale lock may be reclaimed.'
+    );
+    return { runtimeProof: null, staleOwnerProof: exactStaleOwnerProof };
+  }
+
   const commandLineConfirmed = isKnownLiveDeskLauncherProcess(details.processName, details.commandLine);
-  const lockInstanceConfirmed = String(existing?.ownerToken || '').trim().length >= 16
-    && String(existing?.ownerInstanceMarker || '').trim()
-      === processInstanceMarker(details);
-  const legacyClientTreeConfirmed = !String(existing?.ownerToken || '').trim()
-    && String(existing?.role || '').trim().toLowerCase() === 'client'
+  const preciseOwnerStartOrderSupported = os.platform() === 'win32' || os.platform() === 'linux';
+  const lockInstanceConfirmed = storedOwnerToken.length >= 16
+    && storedOwnerInstanceMarker === processInstanceMarker(details)
+    && preciseOwnerStartOrderSupported
+    && storedOwnerStartOrder.length > 0
+    && storedOwnerStartOrder === currentOwnerStartOrder;
+  const legacyClientTreeConfirmed = !storedOwnerToken
+    && existingRole === 'client'
     && await hasKnownLiveDeskClientAgentDescendant(processId);
   const runtimeProof = commandLineConfirmed || lockInstanceConfirmed || legacyClientTreeConfirmed
     ? null
     : await probeExistingRuntimeIdentity(existing);
-  if (!commandLineConfirmed && !lockInstanceConfirmed && !legacyClientTreeConfirmed && !runtimeProof) {
+  const cooperativeOwnerConfirmed = cooperativeStop.acknowledged === true;
+  if (!commandLineConfirmed
+    && !lockInstanceConfirmed
+    && !legacyClientTreeConfirmed
+    && !runtimeProof
+    && !cooperativeOwnerConfirmed) {
     throw new Error(`Existing runtime pid ${processId} is not a confirmed LiveDesk launcher; it was preserved.`);
   }
 
-  const identityProof = commandLineConfirmed
-    ? 'command-line'
-    : lockInstanceConfirmed
-      ? 'lock-instance'
-      : legacyClientTreeConfirmed
-        ? 'legacy-lock-exact-client-descendant'
-        : `runtime-api:${runtimeProof.port}:${runtimeProof.appVersion || 'unknown'}`;
+  const identityProof = cooperativeOwnerConfirmed
+    ? `cooperative-ack:${cooperativeStop.ackStatus || 'accepted'}`
+    : commandLineConfirmed
+      ? 'command-line'
+      : lockInstanceConfirmed
+        ? 'lock-instance'
+        : legacyClientTreeConfirmed
+          ? 'legacy-lock-exact-client-descendant'
+          : `runtime-api:${runtimeProof.port}:${runtimeProof.appVersion || 'unknown'}`;
+  if (os.platform() === 'darwin'
+    && !cooperativeOwnerConfirmed
+    && !runtimeProof) {
+    throw new Error(
+      `Existing macOS runtime pid ${processId} did not acknowledge its exact lock generation; `
+      + 'coarse ps start time is insufficient for destructive fallback, so it was preserved.'
+    );
+  }
+  if (hasCompleteStoredOwner) {
+    const currentLock = readJsonFile(getRuntimeLockPath(MANAGER_STATE_DIR));
+    if (!currentLock) {
+      return { runtimeProof: null, staleOwnerProof: null };
+    }
+    if (Number(currentLock.pid) !== processId
+      || currentLock.ownerToken !== storedOwnerToken
+      || currentLock.ownerInstanceMarker !== storedOwnerInstanceMarker
+      || currentLock.ownerStartOrder !== storedOwnerStartOrder) {
+      throw new Error(
+        `LiveDesk runtime-lock ownership changed before fallback for pid ${processId}; `
+        + 'the current process and newer lock generation were preserved.'
+      );
+    }
+  }
+  let inheritedWindowsProcessRecords = [];
+  if (os.platform() === 'win32'
+    && existingRole === 'client'
+    && hasCompleteStoredOwner) {
+    const inheritedManifest = readWindowsOwnedProcessManifest({
+      stateDir: MANAGER_STATE_DIR,
+      owner: exactStaleOwnerProof,
+      maxAgeMs: 60_000
+    });
+    if (inheritedManifest.ok) {
+      inheritedWindowsProcessRecords = inheritedManifest.records;
+    } else if (cooperativeOwnerConfirmed) {
+      throw new Error(
+        `Existing Client pid ${processId} acknowledged cleanup but its exact Windows child manifest `
+        + `could not be inherited (${inheritedManifest.error || 'missing-or-stale'}); `
+        + 'the cleanup coordinator was preserved to avoid orphaning FFmpeg.'
+      );
+    }
+  }
+  if (cooperativeStop.requested) {
+    const status = cooperativeStop.acknowledged
+      ? `ack=${cooperativeStop.ackStatus || 'accepted'}`
+      : 'no-ack';
+    console.warn(
+      `[LiveDesk] Existing ${existing?.role || 'runtime'} launcher pid ${processId} `
+      + `did not finish cooperative cleanup within its ${cooperativeTimeoutMs / 1000}-second `
+      + `maximum window (${status}); `
+      + 'continuing with exact process-identity fallback.'
+    );
+  }
   console.log(`[LiveDesk] Stopping existing ${existing?.role || 'runtime'} launcher pid ${processId} before starting a fresh runtime (identity=${identityProof}).`);
   if (os.platform() === 'win32') {
-    await runQuiet('taskkill.exe', ['/PID', String(processId), '/T', '/F']);
+    await terminateExactWindowsProcessTree(details, {
+      label: `existing LiveDesk ${existing?.role || 'runtime'} launcher pid=${processId}`,
+      additionalRecords: inheritedWindowsProcessRecords
+    });
   } else {
     try { process.kill(processId, 'SIGTERM'); } catch (error) {
       if (error?.code !== 'ESRCH') throw error;
     }
-  }
-  try {
-    await waitForProcessExit(processId);
-  } catch (error) {
-    if (os.platform() === 'win32') throw error;
-    console.warn(
-      `[LiveDesk] Confirmed launcher pid ${processId} did not finish graceful Client cleanup; `
-      + 'force-stopping that launcher only. Verified orphan agents/helpers will be audited before restart.'
-    );
-    try { process.kill(processId, 'SIGKILL'); } catch (killError) {
-      if (killError?.code !== 'ESRCH') throw killError;
+    try {
+      await waitForProcessExit(processId);
+    } catch (error) {
+      console.warn(
+        `[LiveDesk] Confirmed launcher pid ${processId} did not finish graceful Client cleanup; `
+        + 'force-stopping that launcher only. Verified orphan agents/helpers will be audited before restart.'
+      );
+      try { process.kill(processId, 'SIGKILL'); } catch (killError) {
+        if (killError?.code !== 'ESRCH') throw killError;
+      }
+      await waitForProcessExit(processId, 2000);
     }
-    await waitForProcessExit(processId, 2000);
   }
-  return runtimeProof;
+  return { runtimeProof, staleOwnerProof: null };
 }
 
 async function restartExistingRuntime(existing, role) {
-  const runtimeProof = await stopExistingRuntime(existing);
+  const stopResult = await stopExistingRuntime(existing);
+  const runtimeProof = stopResult?.runtimeProof || null;
   const runtimePort = Number(runtimeProof?.port || existingRuntimeProbePorts()[0] || DEFAULT_MANAGER_HTTP_PORT);
-  if (role === 'hub' || String(existing?.role || '').trim().toLowerCase() === 'hub') {
-    const remotePort = normalizePort(process.env.REMOTE_HUB_PORT, DEFAULT_REMOTE_HUB_PORT);
-    await stopProcessesOnPorts([runtimePort, remotePort]);
-  } else {
-    await stopProcessesOnPorts([runtimePort]);
-  }
+  return {
+    runtimePort,
+    staleOwnerProof: stopResult?.staleOwnerProof || null,
+    role: role || existing?.role || ''
+  };
 }
 
-function waitMilliseconds(milliseconds) {
-  return new Promise(resolve => setTimeout(resolve, milliseconds));
-}
-
-function probePortBind(port, host = '0.0.0.0') {
+function waitMilliseconds(milliseconds) {
+  return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+
+function startOwnedRuntimeShutdownWatcher(runtimeOwner, onShutdown) {
+  const exactOwnerIsComplete = Number(runtimeOwner?.pid) === process.pid
+    && /^[a-f0-9]{32}$/i.test(String(runtimeOwner?.ownerToken || '').trim())
+    && String(runtimeOwner?.ownerInstanceMarker || '').trim()
+    && String(runtimeOwner?.ownerStartOrder || '').trim();
+  if (!exactOwnerIsComplete) {
+    if (runtimeOwner?.ownerToken) {
+      console.warn(
+        '[LiveDesk] Cooperative shutdown watcher is unavailable because the launcher '
+        + 'could not establish a complete process-start identity. Exact fallback remains enabled.'
+      );
+    }
+    return null;
+  }
+  const watcher = startRuntimeShutdownWatcher({
+    stateDir: MANAGER_STATE_DIR,
+    owner: runtimeOwner,
+    pollMs: 100,
+    onShutdown
+  });
+  process.once('exit', () => watcher.stop());
+  return watcher;
+}
+
+function probePortBind(port, host = '0.0.0.0') {
   return new Promise(resolve => {
     const server = net.createServer();
     let settled = false;
@@ -913,7 +1333,7 @@ function isKnownLiveDeskProcess(processName, commandLine) {
     return false;
   }
 
-  const isKnownHubServer = /(?:node_modules\/livedesk|packages\/livedesk)\/hub\/src\/server\.js/i.test(normalizedCommandLine);
+  const isKnownHubServer = /(?:packages\/(?:livedesk\/)?hub|node_modules\/@?livedesk\/hub)\/src\/server\.js/i.test(normalizedCommandLine);
   const isUnifiedLauncher = /(?:node_modules\/livedesk|packages\/livedesk)\/bin\/livedesk\.js/i.test(normalizedCommandLine);
   const isLegacyClient = /(?:node_modules\/@livedesk\/client|packages\/client|packages\/livedesk\/client)\/bin\/livedesk-client\.js/i.test(normalizedCommandLine);
   return isKnownHubServer || isUnifiedLauncher || isLegacyClient;
@@ -927,7 +1347,7 @@ function formatPortOwner(record) {
   return `${record?.Pid || 'unknown'}:${record?.ProcessName || 'unknown'} cmd=${String(record?.CommandLine || 'unavailable').replace(/\s+/g, ' ').slice(0, 240)}`;
 }
 
-function assertPortCleanupReady(finalRecords, portStates) {
+function assertPortCleanupReady(finalRecords, portStates) {
   const blockedPorts = portStates.filter(port => port?.Ready !== true);
   if (blockedPorts.length === 0) {
     return;
@@ -939,10 +1359,118 @@ function assertPortCleanupReady(finalRecords, portStates) {
       .map(formatPortOwner);
     return `TCP ${port.Port}[available=${port.PortAvailable === true},bindable=${port.PortBindable === true},bind-error=${port.BindError || 'none'},owners=${owners.length ? owners.join('; ') : 'owner not visible'}`;
   }).join('], ');
-  throw new Error(`LiveDesk Hub startup cleanup could not release the configured port(s): ${summary}]. Unrelated processes are preserved; stop the owning process manually or choose an explicit --port/--remote-port value.`);
-}
-
-async function collectUnixPortRecords(ports) {
+  throw new Error(`LiveDesk Hub startup cleanup could not release the configured port(s): ${summary}]. Unrelated processes are preserved; stop the owning process manually or choose an explicit --port/--remote-port value.`);
+}
+
+async function collectWindowsPortRecords(ports) {
+  const script = [
+    '$ErrorActionPreference = "SilentlyContinue";',
+    `$ports = @(${ports.join(',')});`,
+    `$currentNodePid = ${process.pid};`,
+    'function Get-ListenConnections($port) {',
+    '  $connections = @(Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue);',
+    '  if ($connections.Count -gt 0) { return $connections }',
+    '  $pattern = "^\\s*TCP\\s+\\S+:" + $port + "\\s+\\S+\\s+LISTENING\\s+(\\d+)\\s*$";',
+    '  foreach ($line in @(netstat -ano -p tcp)) {',
+    '    $match = [regex]::Match([string]$line, $pattern);',
+    '    if ($match.Success) {',
+    '      [pscustomobject]@{ LocalPort = [int]$port; OwningProcess = [int]$match.Groups[1].Value }',
+    '    }',
+    '  }',
+    '}',
+    '$records = @();',
+    'foreach ($port in $ports) {',
+    '  $connections = @(Get-ListenConnections $port | Where-Object { $_.OwningProcess -and $_.OwningProcess -ne $currentNodePid -and $_.OwningProcess -ne $PID });',
+    '  foreach ($connection in $connections) {',
+    '    $owner = [int]$connection.OwningProcess;',
+    '    $proc = Get-CimInstance Win32_Process -Filter "ProcessId = $owner" -Property ProcessId,Name,CommandLine,CreationDate -ErrorAction SilentlyContinue;',
+    '    $processName = if ($proc) { [string]$proc.Name } else { "" };',
+    '    $commandLine = if ($proc) { [string]$proc.CommandLine } else { "" };',
+    '    $creationUtcTicks = if ($proc -and $proc.CreationDate) { [string]$proc.CreationDate.ToUniversalTime().Ticks } else { "" };',
+    '    $isNodeProcess = $processName -match "(?i)^node(?:\\.exe)?$";',
+    '    $hasKnownLiveDeskHubPath = $commandLine -match "(?i)(?:packages[\\\\/](?:livedesk[\\\\/])?hub|node_modules[\\\\/]@?livedesk[\\\\/]hub)[\\\\/]src[\\\\/]server\\.js";',
+    '    $hasUnifiedLauncherPath = $commandLine -match "(?i)(?:node_modules[\\\\/]livedesk|packages[\\\\/]livedesk)[\\\\/]bin[\\\\/]livedesk\\.js";',
+    '    $hasLegacyClientPath = $commandLine -match "(?i)(?:node_modules[\\\\/]@livedesk[\\\\/]client|packages[\\\\/]client|packages[\\\\/]livedesk[\\\\/]client)[\\\\/]bin[\\\\/]livedesk-client\\.js";',
+    '    $knownLiveDesk = [bool]($isNodeProcess -and ($hasKnownLiveDeskHubPath -or $hasUnifiedLauncherPath -or $hasLegacyClientPath));',
+    '    $records += [pscustomobject]@{ Port = [int]$port; Pid = $owner; ProcessName = $processName; CommandLine = $commandLine; CreationUtcTicks = $creationUtcTicks; KnownLiveDesk = $knownLiveDesk; Action = "preserved"; KillAttempted = $false };',
+    '  }',
+    '}',
+    '$records = @($records | Sort-Object Port,Pid -Unique);',
+    '[pscustomobject]@{ Records = $records } | ConvertTo-Json -Compress -Depth 5'
+  ].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(
+      `Could not inspect existing LiveDesk Windows ports: `
+      + `${result.stderr || result.error?.message || 'PowerShell failed'}`
+    );
+  }
+  if (!result.stdout) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch {
+    throw new Error(`Could not parse existing LiveDesk Windows port state: ${result.stdout}`);
+  }
+  const records = parsed?.Records == null
+    ? []
+    : Array.isArray(parsed.Records) ? parsed.Records : [parsed.Records];
+  return records;
+}
+
+async function stopWindowsProcessesOnPorts(ports) {
+  const records = await collectWindowsPortRecords(ports);
+  const stoppedPids = new Set();
+  for (const record of records) {
+    const pid = Number(record?.Pid || 0);
+    if (record?.KnownLiveDesk !== true || stoppedPids.has(pid)) continue;
+    const details = await getProcessDetails(pid);
+    if (!details
+        || String(details.startOrder || '') !== String(record?.CreationUtcTicks || '')
+        || !isKnownLiveDeskProcess(details.processName, details.commandLine)) {
+      continue;
+    }
+    await terminateExactWindowsProcessTree(details, {
+      label: `verified LiveDesk port owner pid=${pid}`
+    });
+    stoppedPids.add(pid);
+    for (const matching of records.filter(candidate => Number(candidate?.Pid) === pid)) {
+      matching.Action = 'stopped';
+      matching.KillAttempted = true;
+    }
+  }
+
+  const probes = await Promise.all(ports.map(port => waitForPortBindable(port)));
+  const finalRecords = await collectWindowsPortRecords(ports);
+  const portStates = ports.map((port, index) => {
+    const busy = finalRecords.some(record => Number(record?.Port) === Number(port));
+    return {
+      Port: Number(port),
+      PortAvailable: !busy,
+      PortBindable: probes[index].ok,
+      BindError: probes[index].error || '',
+      Ready: !busy && probes[index].ok
+    };
+  });
+  const stopped = records.filter(record => record?.Action === 'stopped');
+  if (stopped.length > 0) {
+    const stoppedOwners = new Map();
+    for (const record of stopped) {
+      if (!stoppedOwners.has(String(record.Pid))) stoppedOwners.set(String(record.Pid), record);
+    }
+    const summary = [...stoppedOwners.values()]
+      .map(record => `${record.Pid}:${record.ProcessName || 'node'}`)
+      .join(', ');
+    console.log(`Restarting LiveDesk Hub. Stopped stale LiveDesk owner(s) once: ${summary}`);
+  }
+  assertPortCleanupReady(finalRecords, portStates);
+}
+
+async function collectUnixPortRecords(ports) {
   const records = [];
   for (const port of ports) {
     const lsof = await runQuiet('lsof', ['-nP', '-ti', `tcp:${port}`, '-sTCP:LISTEN']);
@@ -1216,121 +1744,12 @@ async function stopStaleClientAgents() {
     }
   };
 
-  const enumerateWindowsParentPairs = async () => {
-    const script = '$ErrorActionPreference = "Stop"; @(Get-CimInstance Win32_Process | ForEach-Object { [pscustomobject]@{ ProcessId = [int]$_.ProcessId; ParentProcessId = [int]$_.ParentProcessId } }) | ConvertTo-Json -Compress';
-    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 Client lifecycle audit could not snapshot the Windows process tree: `
-        + `${result.stderr || result.error?.message || 'CIM query failed'}`
-      );
-    }
-    const parsed = JSON.parse(result.stdout);
-    return (Array.isArray(parsed) ? parsed : [parsed]).map(item => ({
-      pid: Number(item?.ProcessId || 0),
-      parentPid: Number(item?.ParentProcessId || 0)
-    }));
-  };
-
-  const captureWindowsTreeRecords = async rootRecord => {
-    const pairs = await enumerateWindowsParentPairs();
-    const descendantsByParent = new Map();
-    for (const pair of pairs) {
-      if (!descendantsByParent.has(pair.parentPid)) descendantsByParent.set(pair.parentPid, []);
-      descendantsByParent.get(pair.parentPid).push(pair.pid);
-    }
-    const processIds = [];
-    const queue = [rootRecord.pid];
-    const seen = new Set();
-    while (queue.length > 0) {
-      const pid = queue.shift();
-      if (!Number.isInteger(pid) || pid <= 1 || seen.has(pid)) continue;
-      seen.add(pid);
-      processIds.push(pid);
-      queue.push(...(descendantsByParent.get(pid) || []));
-    }
-    const records = [];
-    for (const pid of processIds) {
-      const details = await getProcessDetails(pid);
-      if (!details) continue;
-      const instanceMarker = processInstanceMarker(details);
-      if (!instanceMarker) {
-        throw new Error(`Windows process-tree verification could not establish a start marker for pid=${pid}.`);
-      }
-      if (pid !== rootRecord.pid && rootRecord.startOrder && details.startOrder) {
-        const rootStart = BigInt(rootRecord.startOrder);
-        const descendantStart = BigInt(details.startOrder);
-        if (descendantStart < rootStart) {
-          throw new Error(
-            `Windows process-tree verification found pid=${pid} with reused parent pid=${rootRecord.pid}; `
-            + 'the older process was preserved instead of passing an ambiguous tree to taskkill.'
-          );
-        }
-      }
-      records.push(pid === rootRecord.pid
-        ? rootRecord
-        : {
-            pid,
-            type: 'descendant',
-            instanceMarker,
-            startOrder: String(details.startOrder || '')
-          });
-    }
-    if (!records.some(record => (
-      record.pid === rootRecord.pid && record.instanceMarker === rootRecord.instanceMarker
-    ))) {
-      return [];
-    }
-    return records;
-  };
-
-  const taskkillExactWindowsRecord = async (record, includeTree) => {
+  const terminateWindowsAgentTree = async record => {
     const details = await getMatchingDetails(record);
     if (!details) return;
-    const expectedStart = String(details.startMarker || '').replaceAll("'", "''");
-    const treeArgument = includeTree ? ', "/T"' : '';
-    const script = [
-      '$ErrorActionPreference = "Stop";',
-      `$targetPid = ${record.pid};`,
-      `$expectedStart = '${expectedStart}';`,
-      '$target = Get-CimInstance Win32_Process -Filter "ProcessId = $targetPid" -ErrorAction SilentlyContinue | Select-Object -First 1;',
-      'if (-not $target) { exit 0 };',
-      'if ([string]$target.CreationDate -ne $expectedStart) { exit 3 };',
-      `$arguments = @("/PID", [string]$targetPid${treeArgument}, "/F");`,
-      '$taskkill = Start-Process -FilePath "taskkill.exe" -ArgumentList $arguments -NoNewWindow -Wait -PassThru;',
-      'exit $taskkill.ExitCode'
-    ].join(' ');
-    await runQuiet(
-      'powershell.exe',
-      ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
-      { timeout: 15000, killSignal: 'SIGKILL' }
-    );
-  };
-
-  const terminateWindowsAgentTree = async record => {
-    if (!await getMatchingDetails(record)) return;
-    const treeRecords = await captureWindowsTreeRecords(record);
-    if (treeRecords.length === 0) return;
-    await taskkillExactWindowsRecord(record, true);
-    let remaining = await waitForExactRecordsExit(treeRecords, 4000);
-    if (remaining.length > 0) {
-      // These are immutable pre-taskkill descendants of the exact Agent tree,
-      // not globally matched ffmpeg processes.
-      for (const descendant of [...remaining].reverse()) {
-        await taskkillExactWindowsRecord(descendant, true);
-      }
-      remaining = await waitForExactRecordsExit(remaining, 4000);
-    }
-    if (remaining.length > 0) {
-      throw new Error(
-        `verified stale Windows Agent tree pid=${record.pid} retained exact descendant(s): `
-        + remaining.map(item => item.pid).join(', ')
-      );
-    }
+    await terminateExactWindowsProcessTree(details, {
+      label: `verified stale Windows Agent tree pid=${record.pid}`
+    });
   };
 
   const stoppedProcesses = new Map();
@@ -1376,118 +1795,17 @@ async function stopStaleClientAgents() {
 
 async function stopProcessesOnPorts(ports) {
   const uniquePorts = [...new Set(ports.map(port => normalizePort(port, 0)).filter(Boolean))];
-  if (uniquePorts.length === 0) {
-    return;
-  }
-
-  if (os.platform() === 'win32') {
-    const script = [
-      '$ErrorActionPreference = "SilentlyContinue";',
-      `$ports = @(${uniquePorts.join(',')});`,
-      `$currentNodePid = ${process.pid};`,
-      'function Get-ListenConnections($port) {',
-      '  $connections = @(Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue);',
-      '  if ($connections.Count -gt 0) { return $connections }',
-      '  $pattern = "^\\s*TCP\\s+\\S+:" + $port + "\\s+\\S+\\s+LISTENING\\s+(\\d+)\\s*$";',
-      '  foreach ($line in @(netstat -ano -p tcp)) {',
-      '    $match = [regex]::Match([string]$line, $pattern);',
-      '    if ($match.Success) {',
-      '      [pscustomobject]@{ LocalPort = [int]$port; OwningProcess = [int]$match.Groups[1].Value }',
-      '    }',
-      '  }',
-      '}',
-      'function Get-PortRecords($port) {',
-      '  $connections = @(Get-ListenConnections $port | Where-Object { $_.OwningProcess -and $_.OwningProcess -ne $currentNodePid -and $_.OwningProcess -ne $PID });',
-      '  foreach ($connection in $connections) {',
-      '    $owner = [int]$connection.OwningProcess;',
-      '    $proc = Get-CimInstance Win32_Process -Filter "ProcessId = $owner" -ErrorAction SilentlyContinue;',
-      '    $processName = if ($proc) { [string]$proc.Name } else { "" };',
-      '    $commandLine = if ($proc) { [string]$proc.CommandLine } else { "" };',
-      '    $isNodeProcess = $processName -match "(?i)^node(?:\\.exe)?$";',
-      '    $hasKnownLiveDeskHubPath = $commandLine -match "(?i)(?:packages[\\\\/](?:livedesk[\\\\/])?hub|node_modules[\\\\/]@?livedesk[\\\\/]hub)[\\\\/]src[\\\\/]server\\.js";',
-      '    $hasUnifiedLauncherPath = $commandLine -match "(?i)(?:node_modules[\\\\/]livedesk|packages[\\\\/]livedesk)[\\\\/]bin[\\\\/]livedesk\\.js";',
-      '    $hasLegacyClientPath = $commandLine -match "(?i)(?:node_modules[\\\\/]@livedesk[\\\\/]client|packages[\\\\/]client|packages[\\\\/]livedesk[\\\\/]client)[\\\\/]bin[\\\\/]livedesk-client\\.js";',
-      '    $knownLiveDesk = [bool]($isNodeProcess -and ($hasKnownLiveDeskHubPath -or $hasUnifiedLauncherPath -or $hasLegacyClientPath));',
-      '    [pscustomobject]@{ Port = [int]$port; Pid = $owner; ProcessName = $processName; CommandLine = $commandLine; KnownLiveDesk = $knownLiveDesk; Action = "preserved"; KillAttempted = $false }',
-      '  }',
-      '}',
-      '$records = @($ports | ForEach-Object { Get-PortRecords $_ } | Sort-Object Port,Pid -Unique);',
-      '$killableOwners = @($records | Where-Object { $_.KnownLiveDesk } | Group-Object Pid | ForEach-Object { @($_.Group)[0] });',
-      'foreach ($owner in $killableOwners) {',
-      '  & taskkill.exe /PID $owner.Pid /T /F | Out-Null;',
-      '  Stop-Process -Id $owner.Pid -Force -ErrorAction SilentlyContinue;',
-      '  foreach ($record in @($records | Where-Object { [int]$_.Pid -eq [int]$owner.Pid })) {',
-      '    $record.Action = "stopped";',
-      '    $record.KillAttempted = $true;',
-      '  }',
-      '}',
-      `$deadline = (Get-Date).ToUniversalTime().AddMilliseconds(${PORT_CLEANUP_TIMEOUT_MS});`,
-      '$finalRecords = @();',
-      '$portStates = @();',
-      'do {',
-      '  $finalRecords = @($ports | ForEach-Object { Get-PortRecords $_ });',
-      '  $busyPorts = @($finalRecords | Select-Object -ExpandProperty Port -Unique);',
-      '  $portStates = @($ports | ForEach-Object {',
-      '    $port = [int]$_;',
-      '    $busy = $busyPorts -contains $port;',
-      '    $bindable = [bool](-not $busy);',
-      '    [pscustomobject]@{ Port = $port; PortAvailable = [bool](-not $busy); PortBindable = $bindable; Ready = [bool](-not $busy) }',
-      '  });',
-      '  if ((@($portStates | Where-Object { -not $_.Ready }).Count -eq 0) -or (Get-Date).ToUniversalTime() -ge $deadline) { break }',
-      `  Start-Sleep -Milliseconds ${PORT_CLEANUP_POLL_MS};`,
-      '} while ($true);',
-      '[pscustomobject]@{ Records = @($records); FinalRecords = @($finalRecords); Ports = @($portStates) } | ConvertTo-Json -Compress -Depth 8'
-    ].join(' ');
-    const result = await runQuiet('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', script]);
-    if (!result.ok && !result.stdout) {
-      throw new Error(`Could not inspect existing LiveDesk Hub ports: ${result.stderr || result.error?.message || 'PowerShell failed'}`);
-    }
-    let payload = { Records: [], FinalRecords: [], Ports: [] };
-    if (result.stdout) {
-      try {
-        const parsed = JSON.parse(result.stdout);
-        payload = Array.isArray(parsed)
-          ? { Records: parsed, FinalRecords: parsed, Ports: [] }
-          : parsed;
-      } catch {
-        throw new Error(`Could not parse existing LiveDesk Hub port state: ${result.stdout}`);
-      }
-    }
-    const records = Array.isArray(payload?.Records) ? payload.Records : [];
-    const finalRecords = Array.isArray(payload?.FinalRecords) ? payload.FinalRecords : [];
-    const rawPortStates = Array.isArray(payload?.Ports) ? payload.Ports : [];
-    const rawStatesByPort = new Map(rawPortStates.map(state => [Number(state?.Port), state]));
-    const portStates = [];
-    for (const port of uniquePorts) {
-      const rawState = rawStatesByPort.get(Number(port)) || {};
-      const probe = rawState.PortAvailable === true
-        ? await waitForPortBindable(port)
-        : { ok: false, error: 'port-in-use' };
-      portStates.push({
-        ...rawState,
-        Port: Number(port),
-        PortBindable: probe.ok,
-        BindError: probe.error || '',
-        Ready: rawState.PortAvailable === true && probe.ok
-      });
-    }
-    const stopped = records.filter(record => record?.Action === 'stopped');
-    if (stopped.length > 0) {
-      const stoppedOwners = new Map();
-      for (const record of stopped) {
-        if (!stoppedOwners.has(String(record.Pid))) {
-          stoppedOwners.set(String(record.Pid), record);
-        }
-      }
-      const summary = [...stoppedOwners.values()].map(record => `${record.Pid}:${record.ProcessName || 'node'}`).join(', ');
-      console.log(`Restarting LiveDesk Hub. Stopped stale LiveDesk owner(s) once: ${summary}`);
-    }
-    assertPortCleanupReady(finalRecords, portStates);
-    return;
-  }
-
-  await stopUnixProcessesOnPorts(uniquePorts);
-}
+  if (uniquePorts.length === 0) {
+    return;
+  }
+
+  if (os.platform() === 'win32') {
+    await stopWindowsProcessesOnPorts(uniquePorts);
+    return;
+  }
+
+  await stopUnixProcessesOnPorts(uniquePorts);
+}
 
 async function waitForManager(url = DEFAULT_MANAGER_URL, timeoutMs = 10000) {
   const startedAt = Date.now();
@@ -1579,6 +1897,13 @@ function buildHubRestartBootstrapScript() {
     'const isGroupAlive = pid => { try { process.kill(-pid, 0); return true; } catch (error) { return error?.code !== "ESRCH"; } };',
     'const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));',
     'const numberFromEnv = (name, fallback, minimum) => { const value = Number(process.env[name]); return Number.isFinite(value) && value >= minimum ? Math.round(value) : fallback; };',
+    'const runWindowsPowerShell = script => new Promise((resolve, reject) => { execFile("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script], { windowsHide: true, timeout: 15000, killSignal: "SIGKILL", maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => { if (error) { reject(new Error(String(stderr || error.message || "PowerShell failed").trim())); return; } resolve(String(stdout || "").trim()); }); });',
+    'const queryWindowsProcessTable = async () => { if (process.platform !== "win32") return []; const stdout = await runWindowsPowerShell(`$ErrorActionPreference = "Stop"; $records = @(Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate | ForEach-Object { $ticks = if ($_.CreationDate) { [string]$_.CreationDate.ToUniversalTime().Ticks } else { "" }; [pscustomobject]@{ ProcessId = [int]$_.ProcessId; ParentProcessId = [int]$_.ParentProcessId; CreationUtcTicks = $ticks } }); [pscustomobject]@{ Records = $records } | ConvertTo-Json -Compress -Depth 4`); if (!stdout) throw new Error("Windows process snapshot returned no data"); const parsed = JSON.parse(stdout); const values = parsed?.Records == null ? [] : (Array.isArray(parsed.Records) ? parsed.Records : [parsed.Records]); return values.map(item => ({ pid: Number(item?.ProcessId || 0), parentPid: Number(item?.ParentProcessId || 0), startOrder: String(item?.CreationUtcTicks || "") })).filter(item => Number.isInteger(item.pid) && item.pid > 1 && /^\\d+$/.test(item.startOrder)); };',
+    'const sameWindowsIdentity = (left, right) => Number(left?.pid || 0) === Number(right?.pid || 0) && String(left?.startOrder || "") === String(right?.startOrder || "");',
+    'const captureWindowsIdentity = async pid => { const processId = Number(pid || 0); const deadline = Date.now() + 2500; let lastError = null; do { try { const snapshot = await queryWindowsProcessTable(); const identity = snapshot.find(item => item.pid === processId) || null; if (identity) return identity; } catch (error) { lastError = error; } if (Date.now() < deadline) await sleep(50); } while (Date.now() < deadline); throw new Error(`Could not capture immutable Windows CreationDate for pid=${processId}: ${lastError?.message || "process not visible"}`); };',
+    'const captureExactWindowsTrees = (identities, snapshot) => { const currentByPid = new Map(snapshot.map(item => [item.pid, item])); const childrenByParent = new Map(); for (const item of snapshot) { if (!childrenByParent.has(item.parentPid)) childrenByParent.set(item.parentPid, []); childrenByParent.get(item.parentPid).push(item); } const tracked = new Map(); for (const root of identities) { const currentRoot = currentByPid.get(Number(root?.pid || 0)); if (!sameWindowsIdentity(currentRoot, root)) continue; const queue = [{ record: currentRoot, depth: 0 }]; const seen = new Set(); while (queue.length > 0) { const current = queue.shift(); if (seen.has(current.record.pid)) continue; seen.add(current.record.pid); const key = `${current.record.pid}:${current.record.startOrder}`; const previous = tracked.get(key); if (!previous || current.depth > previous.depth) tracked.set(key, { ...current.record, depth: current.depth }); for (const child of childrenByParent.get(current.record.pid) || []) { try { if (BigInt(child.startOrder) < BigInt(current.record.startOrder)) continue; } catch { continue; } queue.push({ record: child, depth: current.depth + 1 }); } } } return [...tracked.values()].sort((left, right) => Number(right.depth || 0) - Number(left.depth || 0)); };',
+    'const stopExactWindowsRecords = async records => { if (!Array.isArray(records) || records.length === 0) return; const encoded = Buffer.from(JSON.stringify(records.map(record => ({ pid: record.pid, startOrder: record.startOrder }))), "utf8").toString("base64"); const script = `$ErrorActionPreference = "Stop"; $targetsJson = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String("${encoded}")); $targets = ConvertFrom-Json -InputObject $targetsJson; $failures = [System.Collections.Generic.List[string]]::new(); foreach ($item in $targets) { $targetPid = [int]$item.pid; $expectedStartTicks = [string]$item.startOrder; try { $target = Get-CimInstance Win32_Process -Filter "ProcessId = $targetPid" -Property ProcessId,CreationDate -ErrorAction SilentlyContinue | Select-Object -First 1; if (-not $target) { continue }; $targetStartTicks = if ($target.CreationDate) { [string]$target.CreationDate.ToUniversalTime().Ticks } else { "" }; if ($targetStartTicks -ne $expectedStartTicks) { continue }; Stop-Process -Id $targetPid -Force -ErrorAction Stop } catch { $failures.Add("pid=$targetPid $($_.Exception.Message)") } }; if ($failures.Count -gt 0) { [Console]::Error.WriteLine(($failures -join "; ")); exit 1 }`; await runWindowsPowerShell(script); };',
+    'const terminateExactWindowsOwnedTrees = async (identities, { skipStop = false } = {}) => { const roots = (Array.isArray(identities) ? identities : []).filter(identity => Number(identity?.pid || 0) > 1 && /^\\d+$/.test(String(identity?.startOrder || ""))); if (roots.length === 0) throw new Error("No immutable Windows replacement identity is available"); const snapshot = await queryWindowsProcessTable(); const targets = captureExactWindowsTrees(roots, snapshot); if (!skipStop) await stopExactWindowsRecords(targets); const finalSnapshot = await queryWindowsProcessTable(); const currentByPid = new Map(finalSnapshot.map(item => [item.pid, item])); const remaining = targets.filter(target => sameWindowsIdentity(currentByPid.get(target.pid), target)); if (remaining.length > 0) throw new Error(`${skipStop ? "simulated exact stop no-op; " : ""}exact pid(s) still alive: ${remaining.map(item => item.pid).join(", ")}`); };',
     'const waitForExit = async (pid, timeoutMs) => { const deadline = Date.now() + timeoutMs; while (pid > 1 && Date.now() < deadline) { if (!isAlive(pid)) return; await sleep(250); } if (pid > 1 && isAlive(pid)) throw new Error(`Previous LiveDesk Hub launcher pid=${pid} did not exit within ${timeoutMs}ms.`); };',
     'const decodeArgs = name => JSON.parse(Buffer.from(process.env[name] || "", "base64").toString("utf8"));',
     'const primary = { command: process.env.LIVEDESK_RESTART_COMMAND || "", args: decodeArgs("LIVEDESK_RESTART_ARGS_BASE64") };',
@@ -1601,14 +1926,118 @@ function buildHubRestartBootstrapScript() {
     'const probeRemotePort = () => new Promise((resolve, reject) => { const socket = net.createConnection({ host: remoteHost, port: remotePort }); const timer = setTimeout(() => socket.destroy(new Error("TCP probe timed out")), Math.min(1500, healthTimeoutMs)); timer.unref?.(); socket.once("connect", () => { clearTimeout(timer); socket.destroy(); resolve(); }); socket.once("error", error => { clearTimeout(timer); reject(error); }); });',
     'const probeReplacement = async requiredVersion => { const [status, health] = await Promise.all([requestJson("/api/runtime/status"), requestJson("/api/health")]); const runtimePid = Number(status?.runtimePid || 0); if (status?.role !== "hub" || status?.runtimeStarted !== true || runtimePid <= 1) throw new Error("replacement runtime status is not ready"); if (previousRuntimePid > 1 && runtimePid === previousRuntimePid) throw new Error(`old runtime pid=${runtimePid} is still answering`); if (requiredVersion && String(status?.appVersion || "") !== requiredVersion) throw new Error(`version mismatch expected=${requiredVersion} actual=${status?.appVersion || "unknown"}`); if (health?.ok !== true || health?.product !== "LiveDesk") throw new Error("replacement health response is invalid"); await probeRemotePort(); return { runtimePid, appVersion: String(status?.appVersion || "") }; };',
     'const terminationError = (pid, detail) => { const error = new Error(`Unverified replacement pid=${pid} could not be terminated${detail ? `: ${detail}` : ""}`); error.code = "LIVEDESK_HUB_RESTART_TERMINATION_FAILED"; return error; };',
-    'const terminateTree = async (child, runtimePid = 0) => { const pid = Number(child?.pid || 0); const observedRuntimePid = Number(runtimePid || 0); if (pid <= 1) return; const rootsAlive = () => isAlive(pid) || (observedRuntimePid > 1 && isAlive(observedRuntimePid)); log(`terminating unverified replacement pid=${pid} runtimePid=${observedRuntimePid || 0}`); if (process.platform === "win32") { let taskkillError = null; if (terminationFailureOperationId === operationId) { taskkillError = new Error("simulated taskkill no-op"); } else if (rootsAlive()) { await new Promise(resolve => execFile("taskkill.exe", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, timeout: 10000, killSignal: "SIGKILL" }, error => { taskkillError = error || null; resolve(); })); } const deadline = Date.now() + 2000; while (Date.now() < deadline && rootsAlive()) await sleep(100); if (rootsAlive()) throw terminationError(pid, taskkillError?.message || `launcher/runtime still alive after taskkill (${observedRuntimePid || "no runtime pid"})`); return; } if (terminationFailureOperationId !== operationId) { try { process.kill(-pid, "SIGTERM"); } catch { try { child.kill("SIGTERM"); } catch {} } } const gracefulDeadline = Date.now() + 2000; while (Date.now() < gracefulDeadline && (isGroupAlive(pid) || rootsAlive())) await sleep(100); if (isGroupAlive(pid) || rootsAlive()) { if (terminationFailureOperationId !== operationId) { log(`unverified replacement pid=${pid} ignored SIGTERM; sending SIGKILL to process group`); try { process.kill(-pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch {} } } const hardDeadline = Date.now() + 1000; while (Date.now() < hardDeadline && (isGroupAlive(pid) || rootsAlive())) await sleep(100); } if (isGroupAlive(pid) || rootsAlive()) throw terminationError(pid, `launcher/process group/runtime still alive (${observedRuntimePid || "no runtime pid"})`); };',
-    'const launchAndVerify = async (invocation, label, requiredVersion, attempt) => { if (!invocation.command || !Array.isArray(invocation.args)) throw new Error(`${label} restart command is unavailable`); const isFallback = label === "fallback"; if (!isFallback) prepareNeutralCwd(); const launchCwd = isFallback ? fallbackCwd : neutralCwd; if (!launchCwd) throw new Error(`${label} restart working directory is unavailable`); const launchEnv = isFallback ? { ...process.env } : buildLaunchEnv(); assertResultOwnership(); log(`${label} attempt=${attempt} stage=spawning command=${invocation.command} target=${requiredVersion || "current"} cwd=${launchCwd}`); let exit = null; let lastRuntimePid = 0; let stableRuntimePid = 0; let stableSince = 0; const child = spawn(invocation.command, invocation.args, { cwd: launchCwd, env: launchEnv, detached: true, stdio: "ignore", windowsHide: true }); await new Promise((resolve, reject) => { child.once("error", reject); child.once("spawn", resolve); }); log(`${label} attempt=${attempt} stage=spawned pid=${child.pid || 0}`); child.once("exit", (code, signal) => { exit = { code, signal }; log(`${label} attempt=${attempt} stage=exited code=${code ?? "none"} signal=${signal || "none"}`); }); const deadline = Date.now() + healthTimeoutMs; let lastError = null; while (Date.now() < deadline) { try { assertResultOwnership(); if (exit || !isAlive(Number(child.pid || 0))) throw new Error(`launcher pid=${child.pid || 0} exited before stability proof`); const status = await probeReplacement(requiredVersion); lastRuntimePid = Number(status.runtimePid || 0); if (!isAlive(Number(child.pid || 0))) throw new Error(`launcher pid=${child.pid || 0} exited during stability proof`); if (!isAlive(lastRuntimePid)) throw new Error(`runtime pid=${lastRuntimePid || 0} exited during stability proof`); assertResultOwnership(); if (stableRuntimePid !== lastRuntimePid) { stableRuntimePid = lastRuntimePid; stableSince = Date.now(); log(`${label} attempt=${attempt} stage=stability-start launcherPid=${child.pid || 0} runtimePid=${lastRuntimePid} requiredMs=${stabilityMs}`); } if (Date.now() - stableSince >= stabilityMs) { log(`${label} attempt=${attempt} stage=verified launcherPid=${child.pid || 0} runtimePid=${status.runtimePid} version=${status.appVersion || "unknown"} stableMs=${Date.now() - stableSince} http=${healthBaseUrl} remote=${remoteHost}:${remotePort}`); child.unref(); return { ...status, launcherPid: Number(child.pid || 0) }; } } catch (error) { if (error?.code === "LIVEDESK_HUB_UPDATE_SUPERSEDED") { await terminateTree(child, lastRuntimePid); throw error; } lastError = error; stableRuntimePid = 0; stableSince = 0; } if (exit) break; await sleep(pollMs); } await terminateTree(child, lastRuntimePid); throw new Error(`${label} attempt=${attempt} did not remain healthy for ${stabilityMs}ms: ${lastError?.message || (exit ? `command exited code=${exit.code ?? "none"} signal=${exit.signal || "none"}` : "health deadline expired")}`); };',
+    'const terminateTree = async (child, runtimePid = 0) => {',
+    '  const pid = Number(child?.pid || 0);',
+    '  const observedRuntimePid = Number(runtimePid || 0);',
+    '  if (pid <= 1) return;',
+    '  log(`terminating unverified replacement pid=${pid} runtimePid=${observedRuntimePid || 0}`);',
+    '  if (process.platform === "win32") {',
+    '    const identities = [child?.livedeskWindowsLauncherIdentity, child?.livedeskWindowsRuntimeIdentity].filter(Boolean);',
+    '    if (!child?.livedeskWindowsLauncherIdentity) {',
+    '      if (observedRuntimePid <= 1 && (child?.livedeskObservedExit || child?.exitCode !== null || child?.signalCode !== null)) return;',
+    '      throw terminationError(pid, "immutable launcher CreationDate was not captured");',
+    '    }',
+    '    try {',
+    '      await terminateExactWindowsOwnedTrees(identities, { skipStop: terminationFailureOperationId === operationId });',
+    '    } catch (error) {',
+    '      throw terminationError(pid, error?.message || String(error));',
+    '    }',
+    '    return;',
+    '  }',
+    '  const rootsAlive = () => isAlive(pid) || (observedRuntimePid > 1 && isAlive(observedRuntimePid));',
+    '  if (terminationFailureOperationId !== operationId) {',
+    '    try { process.kill(-pid, "SIGTERM"); } catch { try { child.kill("SIGTERM"); } catch {} }',
+    '  }',
+    '  const gracefulDeadline = Date.now() + 2000;',
+    '  while (Date.now() < gracefulDeadline && (isGroupAlive(pid) || rootsAlive())) await sleep(100);',
+    '  if (isGroupAlive(pid) || rootsAlive()) {',
+    '    if (terminationFailureOperationId !== operationId) {',
+    '      log(`unverified replacement pid=${pid} ignored SIGTERM; sending SIGKILL to process group`);',
+    '      try { process.kill(-pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch {} }',
+    '    }',
+    '    const hardDeadline = Date.now() + 1000;',
+    '    while (Date.now() < hardDeadline && (isGroupAlive(pid) || rootsAlive())) await sleep(100);',
+    '  }',
+    '  if (isGroupAlive(pid) || rootsAlive()) throw terminationError(pid, `launcher/process group/runtime still alive (${observedRuntimePid || "no runtime pid"})`);',
+    '};',
+    'const launchAndVerify = async (invocation, label, requiredVersion, attempt) => {',
+    '  if (!invocation.command || !Array.isArray(invocation.args)) throw new Error(`${label} restart command is unavailable`);',
+    '  const isFallback = label === "fallback";',
+    '  if (!isFallback) prepareNeutralCwd();',
+    '  const launchCwd = isFallback ? fallbackCwd : neutralCwd;',
+    '  if (!launchCwd) throw new Error(`${label} restart working directory is unavailable`);',
+    '  const launchEnv = isFallback ? { ...process.env } : buildLaunchEnv();',
+    '  assertResultOwnership();',
+    '  log(`${label} attempt=${attempt} stage=spawning command=${invocation.command} target=${requiredVersion || "current"} cwd=${launchCwd}`);',
+    '  let exit = null;',
+    '  let lastRuntimePid = 0;',
+    '  let stableRuntimePid = 0;',
+    '  let stableSince = 0;',
+    '  const child = spawn(invocation.command, invocation.args, { cwd: launchCwd, env: launchEnv, detached: true, stdio: "ignore", windowsHide: true });',
+    '  child.once("exit", (code, signal) => {',
+    '    exit = { code, signal };',
+    '    child.livedeskObservedExit = exit;',
+    '    log(`${label} attempt=${attempt} stage=exited code=${code ?? "none"} signal=${signal || "none"}`);',
+    '  });',
+    '  await new Promise((resolve, reject) => { child.once("error", reject); child.once("spawn", resolve); });',
+    '  if (process.platform === "win32") {',
+    '    try {',
+    '      child.livedeskWindowsLauncherIdentity = await captureWindowsIdentity(child.pid);',
+    '    } catch (error) {',
+    '      if (!(exit || child.exitCode !== null || child.signalCode !== null || !isAlive(Number(child.pid || 0)))) {',
+    '        try { child.kill("SIGKILL"); } catch {}',
+    '        throw terminationError(Number(child.pid || 0), `immutable launcher identity capture failed: ${error?.message || error}`);',
+    '      }',
+    '      log(`${label} attempt=${attempt} stage=exited-before-identity pid=${child.pid || 0}`);',
+    '    }',
+    '  }',
+    '  log(`${label} attempt=${attempt} stage=spawned pid=${child.pid || 0}`);',
+    '  const deadline = Date.now() + healthTimeoutMs;',
+    '  let lastError = null;',
+    '  while (Date.now() < deadline) {',
+    '    try {',
+    '      assertResultOwnership();',
+    '      if (exit || !isAlive(Number(child.pid || 0))) throw new Error(`launcher pid=${child.pid || 0} exited before stability proof`);',
+    '      const status = await probeReplacement(requiredVersion);',
+    '      lastRuntimePid = Number(status.runtimePid || 0);',
+    '      if (!isAlive(Number(child.pid || 0))) throw new Error(`launcher pid=${child.pid || 0} exited during stability proof`);',
+    '      if (!isAlive(lastRuntimePid)) throw new Error(`runtime pid=${lastRuntimePid || 0} exited during stability proof`);',
+    '      if (process.platform === "win32" && Number(child.livedeskWindowsRuntimeIdentity?.pid || 0) !== lastRuntimePid) {',
+    '        child.livedeskWindowsRuntimeIdentity = await captureWindowsIdentity(lastRuntimePid);',
+    '      }',
+    '      assertResultOwnership();',
+    '      if (stableRuntimePid !== lastRuntimePid) {',
+    '        stableRuntimePid = lastRuntimePid;',
+    '        stableSince = Date.now();',
+    '        log(`${label} attempt=${attempt} stage=stability-start launcherPid=${child.pid || 0} runtimePid=${lastRuntimePid} requiredMs=${stabilityMs}`);',
+    '      }',
+    '      if (Date.now() - stableSince >= stabilityMs) {',
+    '        log(`${label} attempt=${attempt} stage=verified launcherPid=${child.pid || 0} runtimePid=${status.runtimePid} version=${status.appVersion || "unknown"} stableMs=${Date.now() - stableSince} http=${healthBaseUrl} remote=${remoteHost}:${remotePort}`);',
+    '        child.unref();',
+    '        return { ...status, launcherPid: Number(child.pid || 0) };',
+    '      }',
+    '    } catch (error) {',
+    '      if (error?.code === "LIVEDESK_HUB_UPDATE_SUPERSEDED") {',
+    '        await terminateTree(child, lastRuntimePid);',
+    '        throw error;',
+    '      }',
+    '      lastError = error;',
+    '      stableRuntimePid = 0;',
+    '      stableSince = 0;',
+    '    }',
+    '    if (exit) break;',
+    '    await sleep(pollMs);',
+    '  }',
+    '  await terminateTree(child, lastRuntimePid);',
+    '  throw new Error(`${label} attempt=${attempt} did not remain healthy for ${stabilityMs}ms: ${lastError?.message || (exit ? `command exited code=${exit.code ?? "none"} signal=${exit.signal || "none"}` : "health deadline expired")}`);',
+    '};',
     '(async () => { const targetErrors = []; const fallbackErrors = []; if (exitBeforeHandshakeOperationId === operationId) { log("stage=test-exit-before-handshake"); process.exitCode = 86; return; } if (delayHandshakeOperationId === operationId) { const claimDelayMs = numberFromEnv("LIVEDESK_TEST_HUB_RESTART_HANDSHAKE_DELAY_MS", 2000, 1); log(`stage=test-delay-before-handshake delayMs=${claimDelayMs}`); await sleep(claimDelayMs); } writeResult("waiting-for-old-launcher", { outcome: "in-progress" }); log(`stage=waiting-for-old-launcher pid=${waitPid} supervisorPid=${process.pid}`); if (exitAfterHandshakeOperationId === operationId) { log("stage=test-exit-after-handshake"); process.exitCode = 87; return; } await waitForExit(waitPid, 60000); writeResult("old-launcher-exited", { outcome: "in-progress" }); log("stage=old-launcher-exited"); for (let attempt = 1; attempt <= attemptLimit; attempt += 1) { writeResult("target-attempt", { outcome: "in-progress", attempt }); try { const status = await launchAndVerify(primary, "target", expectedVersion, attempt); writeResult("updated", { outcome: "updated", attempt, runtimePid: status.runtimePid, launcherPid: status.launcherPid, appVersion: status.appVersion, completedAt: new Date().toISOString(), error: undefined }); log("stage=completed"); return; } catch (error) { if (["LIVEDESK_HUB_UPDATE_SUPERSEDED", "LIVEDESK_HUB_RESTART_TERMINATION_FAILED"].includes(error?.code)) throw error; targetErrors.push(error.message); writeResult("target-failed", { outcome: "in-progress", attempt, error: error.message }); log(`target attempt=${attempt} stage=failed error=${error.message}`); } } log(`stage=fallback-start target=${fallbackVersion || "current"}`); for (let attempt = 1; attempt <= 2; attempt += 1) { writeResult("fallback-attempt", { outcome: "in-progress", attempt, error: targetErrors.join(" | ") }); try { const status = await launchAndVerify(fallback, "fallback", fallbackVersion, attempt); writeResult("restored", { outcome: "restored", attempt, runtimePid: status.runtimePid, launcherPid: status.launcherPid, appVersion: status.appVersion, completedAt: new Date().toISOString(), error: `Target Hub ${expectedVersion} failed verification: ${targetErrors.join(" | ")}` }); log("stage=completed-with-fallback"); return; } catch (error) { if (["LIVEDESK_HUB_UPDATE_SUPERSEDED", "LIVEDESK_HUB_RESTART_TERMINATION_FAILED"].includes(error?.code)) throw error; fallbackErrors.push(error.message); writeResult("fallback-failed", { outcome: "in-progress", attempt, error: [...targetErrors, ...fallbackErrors].join(" | ") }); log(`fallback attempt=${attempt} stage=failed error=${error.message}`); } } throw new Error(`No verified LiveDesk Hub replacement could be started. Target failures: ${targetErrors.join(" | ") || "none"}. Fallback failures: ${fallbackErrors.join(" | ") || "none"}. Inspect ${logPath || "the Hub restart log"} and start the frozen local LiveDesk Hub manually.`); })().catch(error => { if (error?.code === "LIVEDESK_HUB_UPDATE_SUPERSEDED") { log("stage=bootstrap-superseded error=" + error.message); return; } try { writeResult("failed", { outcome: "failed", completedAt: new Date().toISOString(), error: error.message }); } catch (writeError) { log("stage=result-write-failed resultStage=failed error=" + writeError.message); } log("stage=bootstrap-failed error=" + error.message); process.exitCode = 1; });',
     ''
   ].join('\n');
 }
 
-async function runManager(args, resolvedRole = null) {
+async function runManager(args, resolvedRole = null, runtimeLock = null) {
+  const runtimeOwner = runtimeLock?.payload || null;
   const options = parseManagerArgs(args);
   const httpPort = normalizePort(
     options.port || process.env.LIVEDESK_HUB_HTTP_PORT || process.env.PORT,
@@ -1697,6 +2126,91 @@ async function runManager(args, resolvedRole = null) {
   let updatePollId = null;
   let updateStopTimer = null;
   let updateHardStopTimer = null;
+  let launcherShutdownSignal = '';
+  let launcherShutdownHardStopTimer = null;
+  let runtimeShutdownWatcher = null;
+  const launcherSignalHandlers = new Map();
+
+  const removeLauncherSignalHandlers = () => {
+    for (const [signal, handler] of launcherSignalHandlers) {
+      process.removeListener(signal, handler);
+    }
+    launcherSignalHandlers.clear();
+  };
+
+  const requestLauncherShutdown = signal => {
+    if (launcherShutdownSignal) return;
+    launcherShutdownSignal = signal;
+    restartRequest = null;
+    if (updatePollId) {
+      clearInterval(updatePollId);
+      updatePollId = null;
+    }
+    if (updateStopTimer) {
+      clearTimeout(updateStopTimer);
+      updateStopTimer = null;
+    }
+    if (updateHardStopTimer) {
+      clearTimeout(updateHardStopTimer);
+      updateHardStopTimer = null;
+    }
+    const child = activeChild;
+    if (!child || child.exitCode !== null || child.signalCode) {
+      try { hubLogStream?.end(); } catch {}
+      process.exit(0);
+      return;
+    }
+    reportLauncherUpdate(
+      `[LiveDesk Hub] Launcher received ${signal}; requesting graceful Hub shutdown for pid=${child.pid || 'unknown'}.`
+    );
+    void (async () => {
+      const gracefulDeadline = Date.now() + 2_000;
+      let lastError = null;
+      while (child.exitCode === null
+        && !child.signalCode
+        && Date.now() < gracefulDeadline) {
+        try {
+          const response = await fetch(`${hubProbeBaseUrl}/api/runtime/shutdown`, {
+            method: 'POST',
+            signal: AbortSignal.timeout(750)
+          });
+          if (!response.ok) throw new Error(`HTTP ${response.status}`);
+          reportLauncherUpdate(
+            `[LiveDesk Hub] Owned Hub pid=${child.pid || 'unknown'} acknowledged graceful shutdown.`
+          );
+          return;
+        } catch (error) {
+          lastError = error;
+          await waitMilliseconds(100);
+        }
+      }
+      if (child.exitCode !== null || child.signalCode) return;
+      reportLauncherUpdate(
+        `[LiveDesk Hub] Graceful shutdown API remained unavailable for pid=${child.pid || 'unknown'}`
+        + `${lastError?.message ? ` (${lastError.message})` : ''}; exact child fallback remains armed.`,
+        true
+      );
+      if (process.platform !== 'win32') {
+        try { child.kill('SIGTERM'); } catch { /* exact owned child already exited */ }
+      }
+    })();
+    launcherShutdownHardStopTimer = setTimeout(() => {
+      if (child.exitCode !== null || child.signalCode) return;
+      reportLauncherUpdate(
+        `[LiveDesk Hub] Owned Hub pid=${child.pid || 'unknown'} exceeded graceful shutdown; `
+        + 'force-stopping that exact child root.',
+        true
+      );
+      try { child.kill('SIGKILL'); } catch { /* exact owned child already exited */ }
+    }, 12_000);
+    launcherShutdownHardStopTimer.unref?.();
+  };
+
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    const handler = () => requestLauncherShutdown(signal);
+    launcherSignalHandlers.set(signal, handler);
+    process.on(signal, handler);
+  }
 
   const restartWithLatest = async request => {
     const requestedVersion = normalizeExactUpdateVersion(request?.latestVersion);
@@ -1892,13 +2406,16 @@ async function runManager(args, resolvedRole = null) {
           try { updateChild.kill('SIGTERM'); } catch { /* child already exited */ }
           updateHardStopTimer = setTimeout(() => {
             if (!updateChild || updateChild.exitCode !== null || updateChild.signalCode) return;
-            reportLauncherUpdate(`[LiveDesk Hub] Update shutdown hard fallback: Hub pid=${requestPid} ignored graceful termination; force-stopping its process tree.`, true);
+            reportLauncherUpdate(`[LiveDesk Hub] Update shutdown hard fallback: Hub pid=${requestPid} ignored graceful termination; force-stopping the owned Hub process.`, true);
             if (process.platform === 'win32') {
-              execFile('taskkill.exe', ['/PID', String(requestPid), '/T', '/F'], { windowsHide: true }, error => {
-                if (error && updateChild.exitCode === null && !updateChild.signalCode) {
-                  reportLauncherUpdate(`[LiveDesk Hub] taskkill fallback failed for pid=${requestPid}: ${error.message}`, true);
+              // updateChild is the exact ChildProcess instance spawned by this
+              // launcher. Stop only that owned Hub root; never let taskkill /T
+              // follow unverified PPID descendants.
+              try { updateChild.kill('SIGKILL'); } catch (error) {
+                if (updateChild.exitCode === null && !updateChild.signalCode) {
+                  reportLauncherUpdate(`[LiveDesk Hub] hard-stop fallback failed for pid=${requestPid}: ${error.message}`, true);
                 }
-              });
+              }
             } else {
               try { updateChild.kill('SIGKILL'); } catch { /* child already exited */ }
             }
@@ -1952,6 +2469,17 @@ async function runManager(args, resolvedRole = null) {
     });
     child.once('exit', (code, signal) => {
       const startupOutput = stderrChunks.join('');
+      if (launcherShutdownSignal) {
+        if (launcherShutdownHardStopTimer) {
+          clearTimeout(launcherShutdownHardStopTimer);
+          launcherShutdownHardStopTimer = null;
+        }
+        runtimeShutdownWatcher?.stop();
+        removeLauncherSignalHandlers();
+        try { hubLogStream?.end(); } catch {}
+        process.exit(0);
+        return;
+      }
       if (restartRequest) {
         const request = restartRequest;
         restartRequest = null;
@@ -2002,23 +2530,38 @@ async function runManager(args, resolvedRole = null) {
         });
         return;
       }
-      if (!signal && code === ROLE_TRANSITION_EXIT_CODE) {
+      if (!signal && code === ROLE_TRANSITION_EXIT_CODE) {
         if (updatePollId) {
           clearInterval(updatePollId);
           updatePollId = null;
         }
-        writeRoleCache({
+        try {
+          runtimeLock?.updateRole?.('client');
+        } catch (error) {
+          console.error(
+            `[LiveDesk Hub] The shared runtime lock could not transition to Client: ${error?.message || error}. `
+            + 'The launcher will exit so a clean invocation can recover.'
+          );
+          runtimeShutdownWatcher?.stop();
+          removeLauncherSignalHandlers();
+          try { hubLogStream?.end(); } catch {}
+          process.exit(1);
+          return;
+        }
+        writeRoleCache({
           role: 'client',
           deviceId: resolvedRole?.deviceId || process.env.LIVEDESK_DEVICE_ID || '',
           deviceName: resolvedRole?.deviceName || os.hostname(),
           source: 'supabase',
           isOfflineFallback: false
-        }, { stateDir: MANAGER_STATE_DIR });
-        console.log('[LiveDesk Hub] Role transition accepted. Starting the Client runtime.');
-        void runClient([], { ...resolvedRole, role: 'client', source: 'supabase', roleTransition: true }).catch(error => {
-          console.error(`Failed to start LiveDesk Client runtime: ${error?.message || error}`);
-          process.exitCode = 1;
-        });
+        }, { stateDir: MANAGER_STATE_DIR });
+        console.log('[LiveDesk Hub] Role transition accepted. Starting the Client runtime.');
+        runtimeShutdownWatcher?.stop();
+        removeLauncherSignalHandlers();
+        void runClient([], { ...resolvedRole, role: 'client', source: 'supabase', roleTransition: true }, runtimeLock).catch(error => {
+          console.error(`Failed to start LiveDesk Client runtime: ${error?.message || error}`);
+          process.exitCode = 1;
+        });
         return;
       }
       if (!signal
@@ -2047,8 +2590,19 @@ async function runManager(args, resolvedRole = null) {
       }
       process.exit(code ?? 0);
     });
-  };
-
+  };
+
+  runtimeShutdownWatcher = startOwnedRuntimeShutdownWatcher(runtimeOwner, async request => {
+    reportLauncherUpdate(
+      `[LiveDesk Hub] Cooperative replacement request accepted `
+      + `request=${request.requestId} reason=${request.reason}.`
+    );
+    requestLauncherShutdown('COOPERATIVE_REPLACEMENT');
+    // The launcher signal handler keeps ownership until the Hub child has
+    // closed its sockets, host lease, and HTTP server. Process exit is the
+    // requester's completion proof; do not publish a premature completed ACK.
+    await new Promise(() => undefined);
+  });
   startHubProcess();
   updatePollId = setInterval(pollUpdateRequest, HUB_UPDATE_POLL_MS);
 
@@ -2080,7 +2634,8 @@ async function runManager(args, resolvedRole = null) {
   }
 }
 
-async function runClient(args, resolvedRole = null) {
+async function runClient(args, resolvedRole = null, runtimeLock = null) {
+  const runtimeOwner = runtimeLock?.payload || null;
   const internalClientEntry = resolve(packageRoot, 'client', 'bin', 'livedesk-client.js');
   if (!existsSync(internalClientEntry)) {
     throw new Error('The published livedesk package is missing its internal Client runtime. Rebuild the package with npm run build.');
@@ -2105,14 +2660,35 @@ async function runClient(args, resolvedRole = null) {
       ? '1'
       : String(process.env.LIVEDESK_SKIP_BROWSER_OPEN || ''),
     LIVEDESK_DEVICE_ID: String(resolvedRole?.deviceId || process.env.LIVEDESK_DEVICE_ID || ''),
-    LIVEDESK_ROLE_SOURCE: String(resolvedRole?.source || process.env.LIVEDESK_ROLE_SOURCE || '')
-  });
+    LIVEDESK_ROLE_SOURCE: String(resolvedRole?.source || process.env.LIVEDESK_ROLE_SOURCE || ''),
+    LIVEDESK_RUNTIME_OWNER_PID: String(runtimeOwner?.pid || ''),
+    LIVEDESK_RUNTIME_OWNER_TOKEN: String(runtimeOwner?.ownerToken || ''),
+    LIVEDESK_RUNTIME_OWNER_INSTANCE_MARKER: String(runtimeOwner?.ownerInstanceMarker || ''),
+    LIVEDESK_RUNTIME_OWNER_START_ORDER: String(runtimeOwner?.ownerStartOrder || '')
+  });
   const clientModule = await import(pathToFileURL(clientEntry).href);
-  if (typeof clientModule.runClientRuntime !== 'function') {
-    throw new Error('The unified Client runtime module does not expose runClientRuntime().');
-  }
-  await clientModule.runClientRuntime(clientArgs);
-}
+  if (typeof clientModule.runClientRuntime !== 'function') {
+    throw new Error('The unified Client runtime module does not expose runClientRuntime().');
+  }
+  const runtimeShutdownWatcher = startOwnedRuntimeShutdownWatcher(runtimeOwner, async request => {
+    console.log(
+      `[LiveDesk Client] Cooperative replacement request accepted `
+      + `request=${request.requestId} reason=${request.reason}. Draining the owned capture tree.`
+    );
+    if (typeof clientModule.requestClientRuntimeShutdown !== 'function') {
+      throw new Error('The unified Client runtime does not expose direct graceful shutdown.');
+    }
+    clientModule.requestClientRuntimeShutdown('SIGTERM');
+    // installAgentTerminationHandlers owns the terminal cleanup contract and
+    // exits only after RemoteFast/Node plus SCK/FFmpeg descendants are gone.
+    await new Promise(() => undefined);
+  });
+  try {
+    await clientModule.runClientRuntime(clientArgs);
+  } finally {
+    runtimeShutdownWatcher?.stop();
+  }
+}
 
 async function runDesktopRoleBootstrap() {
   const bootstrap = createRoleBootstrapServer({
@@ -2208,6 +2784,7 @@ async function main() {
   }
   const launcherProcessDetails = await getProcessDetails(process.pid);
   const launcherInstanceMarker = processInstanceMarker(launcherProcessDetails);
+  const launcherStartOrder = String(launcherProcessDetails?.startOrder || '').trim();
   const reportExistingRuntime = existing => {
     const port = DEFAULT_MANAGER_HTTP_PORT;
     openBrowser(`http://127.0.0.1:${port}`);
@@ -2219,17 +2796,21 @@ async function main() {
       stateDir: MANAGER_STATE_DIR,
       role: resolvedRole.role,
       ownerInstanceMarker: launcherInstanceMarker,
+      ownerStartOrder: launcherStartOrder,
       openExisting: () => undefined
     });
+  let replacementCleanup = null;
 
   const sameRoleRuntimeIsRunning = !lock.acquired
     && String(lock.existing?.role || '').trim().toLowerCase() === String(resolvedRole.role || '').trim().toLowerCase();
   if (!lock.acquired && sameRoleRuntimeIsRunning && !topLevel.noRestartExisting) {
-    await restartExistingRuntime(lock.existing, resolvedRole.role);
+    replacementCleanup = await restartExistingRuntime(lock.existing, resolvedRole.role);
     lock = acquireRuntimeLock({
       stateDir: MANAGER_STATE_DIR,
       role: resolvedRole.role,
       ownerInstanceMarker: launcherInstanceMarker,
+      ownerStartOrder: launcherStartOrder,
+      staleOwnerProof: replacementCleanup?.staleOwnerProof || null,
       openExisting: () => undefined
     });
   }
@@ -2242,6 +2823,7 @@ async function main() {
         stateDir: MANAGER_STATE_DIR,
         role: resolvedRole.role,
         ownerInstanceMarker: launcherInstanceMarker,
+        ownerStartOrder: launcherStartOrder,
         openExisting: () => undefined
       });
     }
@@ -2252,6 +2834,14 @@ async function main() {
   }
   process.once('exit', lock.release);
 
+  // Only the contender that won the replacement lock may clean residual
+  // listener ports. A simultaneous losing launcher must never kill the newly
+  // acquired replacement generation.
+  if (replacementCleanup && resolvedRole.role === 'hub') {
+    const remotePort = normalizePort(process.env.REMOTE_HUB_PORT, DEFAULT_REMOTE_HUB_PORT);
+    await stopProcessesOnPorts([replacementCleanup.runtimePort, remotePort]);
+  }
+
   if (resolvedRole.role === 'client') {
     const clientRuntimePort = normalizePort(
       process.env.LIVEDESK_CLIENT_RUNTIME_PORT || process.env.LIVEDESK_LOCAL_RUNTIME_PORT,
@@ -2272,7 +2862,7 @@ async function main() {
       printClientHelp();
       return;
     }
-    await runClient(runtimeArgs, resolvedRole);
+    await runClient(runtimeArgs, resolvedRole, lock);
     return;
   }
   if (command === 'hub' || command === 'manager') {
@@ -2280,14 +2870,14 @@ async function main() {
       printHelp();
       return;
     }
-    await runManager(runtimeArgs, resolvedRole);
+    await runManager(runtimeArgs, resolvedRole, lock);
     return;
   }
   if (resolvedRole.role === 'client') {
-    await runClient(runtimeArgs, resolvedRole);
+    await runClient(runtimeArgs, resolvedRole, lock);
     return;
   }
-  await runManager(runtimeArgs, resolvedRole);
+  await runManager(runtimeArgs, resolvedRole, lock);
 }
 
 main().catch(error => {