livedesk 0.1.446 → 0.1.447

package/bootstrap/runtime-shutdown.js

@@ -0,0 +1,414 @@
+import { randomBytes } from 'node:crypto';
+import {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import os from 'node:os';
+
+export const RUNTIME_SHUTDOWN_PROTOCOL_VERSION = 1;
+export const DEFAULT_RUNTIME_SHUTDOWN_POLL_MS = 100;
+export const DEFAULT_RUNTIME_SHUTDOWN_TIMEOUT_MS = 8_000;
+export const DEFAULT_RUNTIME_SHUTDOWN_ACK_TIMEOUT_MS = 2_000;
+export const DEFAULT_RUNTIME_SHUTDOWN_TTL_MS = 15_000;
+
+const REQUEST_FILE_NAME = 'livedesk-runtime-shutdown-request.json';
+const ACK_FILE_NAME = 'livedesk-runtime-shutdown-ack.json';
+const MAX_REQUEST_TTL_MS = 60_000;
+const MAX_FUTURE_CLOCK_SKEW_MS = 5_000;
+
+function normalizeOwner(value) {
+  const owner = {
+    pid: Number(value?.pid),
+    ownerToken: String(value?.ownerToken || '').trim(),
+    ownerInstanceMarker: String(value?.ownerInstanceMarker || '').trim(),
+    ownerStartOrder: String(value?.ownerStartOrder || '').trim()
+  };
+  if (!Number.isInteger(owner.pid)
+    || owner.pid <= 1
+    || !/^[a-f0-9]{32}$/i.test(owner.ownerToken)
+    || !owner.ownerInstanceMarker
+    || !owner.ownerStartOrder) {
+    return null;
+  }
+  return owner;
+}
+
+function ownersMatch(leftValue, rightValue) {
+  const left = normalizeOwner(leftValue);
+  const right = normalizeOwner(rightValue);
+  return !!left
+    && !!right
+    && left.pid === right.pid
+    && left.ownerToken === right.ownerToken
+    && left.ownerInstanceMarker === right.ownerInstanceMarker
+    && left.ownerStartOrder === right.ownerStartOrder;
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function fileRevision(path) {
+  try {
+    const stat = statSync(path, { bigint: true });
+    return `${stat.mtimeNs}:${stat.size}`;
+  } catch {
+    return '';
+  }
+}
+
+function writeJsonAtomic(path, value) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporaryPath = `${path}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+  let published = false;
+  try {
+    writeFileSync(temporaryPath, JSON.stringify(value, null, 2), {
+      encoding: 'utf8',
+      mode: 0o600,
+      flag: 'wx'
+    });
+    renameSync(temporaryPath, path);
+    published = true;
+  } finally {
+    if (!published) {
+      try { unlinkSync(temporaryPath); } catch { /* temporary file was never published */ }
+    }
+  }
+}
+
+function isValidRequest(request, nowMs) {
+  const requestedAtMs = Date.parse(String(request?.requestedAt || ''));
+  const expiresAtMs = Date.parse(String(request?.expiresAt || ''));
+  return request?.protocolVersion === RUNTIME_SHUTDOWN_PROTOCOL_VERSION
+    && /^[a-f0-9]{32,128}$/i.test(String(request?.requestId || ''))
+    && !!normalizeOwner(request?.target)
+    && Number.isFinite(requestedAtMs)
+    && Number.isFinite(expiresAtMs)
+    && requestedAtMs <= nowMs + MAX_FUTURE_CLOCK_SKEW_MS
+    && expiresAtMs > nowMs
+    && expiresAtMs > requestedAtMs
+    && expiresAtMs - requestedAtMs <= MAX_REQUEST_TTL_MS;
+}
+
+function isMatchingAck(ack, request) {
+  return ack?.protocolVersion === RUNTIME_SHUTDOWN_PROTOCOL_VERSION
+    && ack?.requestId === request.requestId
+    && ownersMatch(ack?.target, request.target)
+    && ['accepted', 'completed', 'failed'].includes(String(ack?.status || ''));
+}
+
+function isSameOwnerDrainAck(ack, request, nowMs) {
+  const requestedAtMs = Date.parse(String(request?.requestedAt || ''));
+  const acceptedAtMs = Date.parse(String(ack?.acceptedAt || ''));
+  return ack?.protocolVersion === RUNTIME_SHUTDOWN_PROTOCOL_VERSION
+    && ack?.requestId !== request.requestId
+    && /^[a-f0-9]{32,128}$/i.test(String(ack?.requestId || ''))
+    && ownersMatch(ack?.target, request.target)
+    && ['accepted', 'completed', 'failed'].includes(String(ack?.status || ''))
+    && Number.isFinite(requestedAtMs)
+    && Number.isFinite(acceptedAtMs)
+    && acceptedAtMs >= requestedAtMs - MAX_REQUEST_TTL_MS
+    && acceptedAtMs <= nowMs + MAX_FUTURE_CLOCK_SKEW_MS;
+}
+
+function clampMilliseconds(value, fallback, minimum, maximum) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed)
+    ? Math.min(maximum, Math.max(minimum, Math.trunc(parsed)))
+    : fallback;
+}
+
+function wait(milliseconds) {
+  return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+
+export function getRuntimeShutdownPaths(stateDir = join(os.homedir(), '.livedesk')) {
+  return {
+    requestPath: join(stateDir, REQUEST_FILE_NAME),
+    ackPath: join(stateDir, ACK_FILE_NAME)
+  };
+}
+
+/**
+ * Contract:
+ * - One watcher belongs to one immutable launcher-lock owner.
+ * - Only a non-expired request matching all exact owner fields is accepted.
+ * - ACK is published before cleanup starts so a replacement can distinguish
+ *   cooperative shutdown from an unresponsive/stale launcher.
+ * - onShutdown is invoked at most once. Exact process-tree teardown remains the
+ *   caller's fallback if the accepted owner does not actually exit.
+ */
+export function startRuntimeShutdownWatcher({
+  stateDir,
+  owner,
+  onShutdown,
+  pollMs = DEFAULT_RUNTIME_SHUTDOWN_POLL_MS,
+  now = () => Date.now(),
+  reportError = error => console.warn(
+    `[LiveDesk] Cooperative shutdown mailbox warning: ${error?.message || error}`
+  )
+} = {}) {
+  const exactOwner = normalizeOwner(owner);
+  if (!exactOwner) {
+    throw new Error('A cooperative LiveDesk shutdown watcher requires an exact runtime-lock owner.');
+  }
+  if (typeof onShutdown !== 'function') {
+    throw new Error('A cooperative LiveDesk shutdown watcher requires an onShutdown handler.');
+  }
+
+  const paths = getRuntimeShutdownPaths(stateDir);
+  const intervalMs = clampMilliseconds(pollMs, DEFAULT_RUNTIME_SHUTDOWN_POLL_MS, 25, 1_000);
+  let lastRequestRevision = '';
+  let stopped = false;
+  let shutdownAccepted = false;
+  let polling = false;
+  const report = error => {
+    try { reportError(error); } catch { /* diagnostics cannot own runtime liveness */ }
+  };
+
+  const publishAck = (request, status, details = {}) => {
+    writeJsonAtomic(paths.ackPath, {
+      protocolVersion: RUNTIME_SHUTDOWN_PROTOCOL_VERSION,
+      requestId: request.requestId,
+      target: exactOwner,
+      receiverPid: process.pid,
+      status,
+      acceptedAt: details.acceptedAt,
+      completedAt: details.completedAt,
+      error: details.error
+    });
+  };
+
+  const pollNow = async () => {
+    if (stopped || shutdownAccepted || polling) return false;
+    polling = true;
+    try {
+      const revision = fileRevision(paths.requestPath);
+      if (!revision || revision === lastRequestRevision) return false;
+      lastRequestRevision = revision;
+      const request = readJson(paths.requestPath);
+      const observedAtMs = Number(now());
+      if (!isValidRequest(request, observedAtMs)
+        || !ownersMatch(request.target, exactOwner)) {
+        return false;
+      }
+
+      const acceptedAt = new Date(observedAtMs).toISOString();
+      try {
+        // ACK ownership must become durable before cleanup starts. If the
+        // atomic write fails, leave the watcher live and retry this unchanged
+        // request on the next cadence instead of orphaning children.
+        publishAck(request, 'accepted', { acceptedAt });
+      } catch (error) {
+        lastRequestRevision = '';
+        report(error);
+        return false;
+      }
+      shutdownAccepted = true;
+      clearInterval(interval);
+      try {
+        await onShutdown({
+          requestId: request.requestId,
+          reason: String(request.reason || 'replacement-launch'),
+          requesterPid: Number(request.requesterPid || 0),
+          requestedAt: request.requestedAt,
+          acceptedAt,
+          target: exactOwner
+        });
+        try {
+          publishAck(request, 'completed', {
+            acceptedAt,
+            completedAt: new Date(Number(now())).toISOString()
+          });
+        } catch (error) {
+          report(error);
+        }
+      } catch (error) {
+        try {
+          publishAck(request, 'failed', {
+            acceptedAt,
+            completedAt: new Date(Number(now())).toISOString(),
+            error: error instanceof Error ? error.message : String(error)
+          });
+        } catch (ackError) {
+          report(ackError);
+        }
+      }
+      return true;
+    } finally {
+      polling = false;
+    }
+  };
+
+  const interval = setInterval(() => {
+    void pollNow().catch(report);
+  }, intervalMs);
+  interval.unref?.();
+  void pollNow().catch(report);
+
+  return {
+    paths,
+    pollNow,
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(interval);
+    }
+  };
+}
+
+/**
+ * Requests graceful cleanup from an exact launcher generation. The request is
+ * bounded; callers must retain their exact PID/start-time teardown fallback.
+ */
+export async function requestCooperativeRuntimeShutdown({
+  stateDir,
+  target,
+  reason = 'replacement-launch',
+  timeoutMs = DEFAULT_RUNTIME_SHUTDOWN_TIMEOUT_MS,
+  ackTimeoutMs = DEFAULT_RUNTIME_SHUTDOWN_ACK_TIMEOUT_MS,
+  pollMs = DEFAULT_RUNTIME_SHUTDOWN_POLL_MS,
+  ttlMs = DEFAULT_RUNTIME_SHUTDOWN_TTL_MS,
+  isTargetAlive,
+  now = () => Date.now()
+} = {}) {
+  const exactTarget = normalizeOwner(target);
+  if (!exactTarget) {
+    return {
+      requested: false,
+      acknowledged: false,
+      completed: false,
+      exited: false,
+      timedOut: false,
+      error: new Error('An exact runtime-lock owner is required for cooperative shutdown.')
+    };
+  }
+
+  const boundedTimeoutMs = clampMilliseconds(
+    timeoutMs,
+    DEFAULT_RUNTIME_SHUTDOWN_TIMEOUT_MS,
+    100,
+    MAX_REQUEST_TTL_MS - 1_000
+  );
+  const boundedPollMs = clampMilliseconds(
+    pollMs,
+    DEFAULT_RUNTIME_SHUTDOWN_POLL_MS,
+    25,
+    1_000
+  );
+  const boundedAckTimeoutMs = Math.min(
+    boundedTimeoutMs,
+    clampMilliseconds(
+      ackTimeoutMs,
+      Math.min(DEFAULT_RUNTIME_SHUTDOWN_ACK_TIMEOUT_MS, boundedTimeoutMs),
+      100,
+      boundedTimeoutMs
+    )
+  );
+  const boundedTtlMs = clampMilliseconds(
+    ttlMs,
+    Math.max(DEFAULT_RUNTIME_SHUTDOWN_TTL_MS, boundedTimeoutMs + 2_000),
+    boundedTimeoutMs + 1_000,
+    MAX_REQUEST_TTL_MS
+  );
+  const paths = getRuntimeShutdownPaths(stateDir);
+  const requestedAtMs = Number(now());
+  const request = {
+    protocolVersion: RUNTIME_SHUTDOWN_PROTOCOL_VERSION,
+    requestId: randomBytes(24).toString('hex'),
+    target: exactTarget,
+    requesterPid: process.pid,
+    reason: String(reason || 'replacement-launch').slice(0, 200),
+    requestedAt: new Date(requestedAtMs).toISOString(),
+    expiresAt: new Date(requestedAtMs + boundedTtlMs).toISOString()
+  };
+
+  try {
+    writeJsonAtomic(paths.requestPath, request);
+  } catch (error) {
+    return {
+      requested: false,
+      acknowledged: false,
+      completed: false,
+      exited: false,
+      timedOut: false,
+      requestId: request.requestId,
+      error
+    };
+  }
+
+  const deadline = requestedAtMs + boundedTimeoutMs;
+  const ackDeadline = requestedAtMs + boundedAckTimeoutMs;
+  let acknowledged = false;
+  let completed = false;
+  let ackStatus = '';
+  let ackError = '';
+  let sharedOwnerAck = false;
+  while (Number(now()) < deadline) {
+    if (typeof isTargetAlive === 'function') {
+      try {
+        if (!await isTargetAlive(exactTarget)) {
+          return {
+            requested: true,
+            acknowledged,
+            completed,
+            exited: true,
+            timedOut: false,
+            requestId: request.requestId,
+            ackStatus,
+            ackError,
+            sharedOwnerAck
+          };
+        }
+      } catch {
+        // Exact fallback code owns process inspection errors. Keep waiting for
+        // either a valid ACK or its bounded deadline.
+      }
+    }
+
+    const ack = readJson(paths.ackPath);
+    const observedAtMs = Number(now());
+    const exactRequestAck = isMatchingAck(ack, request);
+    const sameOwnerDrainAck = !exactRequestAck
+      && isSameOwnerDrainAck(ack, request, observedAtMs);
+    if (exactRequestAck || sameOwnerDrainAck) {
+      acknowledged = true;
+      sharedOwnerAck = sameOwnerDrainAck;
+      ackStatus = String(ack.status);
+      ackError = String(ack.error || '');
+      completed = ackStatus === 'completed';
+      if (ackStatus === 'failed') break;
+    }
+    if (!acknowledged && Number(now()) >= ackDeadline) break;
+    await wait(Math.min(boundedPollMs, Math.max(1, deadline - Number(now()))));
+  }
+
+  let exited = false;
+  if (typeof isTargetAlive === 'function') {
+    try {
+      exited = !await isTargetAlive(exactTarget);
+    } catch {
+      exited = false;
+    }
+  }
+  return {
+    requested: true,
+    acknowledged,
+    completed,
+    exited,
+    timedOut: !exited && ackStatus !== 'failed',
+    requestId: request.requestId,
+    ackStatus,
+    ackError,
+    sharedOwnerAck
+  };
+}

package/client/bin/livedesk-client-node.js

@@ -1552,7 +1552,7 @@ function remotePolicyAllows(options, command) {
 
 function buildClientUpdateBootstrapScript() {
     return [
-        'const { spawn } = require("node:child_process");',
+        'const { execFile, spawn } = require("node:child_process");',
         'const fs = require("node:fs");',
         'const path = require("node:path");',
         'const operationId = String(process.env.LIVEDESK_CLIENT_UPDATE_OPERATION_ID || "").trim();',
@@ -1569,15 +1569,28 @@ function buildClientUpdateBootstrapScript() {
         'const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));',
         'const isAlive = pid => { try { process.kill(pid, 0); return true; } catch (error) { return error?.code === "EPERM"; } };',
         'const isGroupAlive = pid => { try { process.kill(-pid, 0); return true; } catch (error) { return error?.code === "EPERM"; } };',
+        '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 () => { 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 windowsTicksAtMilliseconds = value => BigInt(Math.trunc(Number(value) || Date.now())) * 10000n + 621355968000000000n;',
+        'const setWindowsRootLifetimeEnd = (child, ticks) => { const candidate = BigInt(ticks); const previous = child.livedeskWindowsRootLifetimeEndTicks; if (!previous || candidate < BigInt(previous)) child.livedeskWindowsRootLifetimeEndTicks = String(candidate); return BigInt(child.livedeskWindowsRootLifetimeEndTicks); };',
+        'const mergeRootAbsentWindowsTree = (child, rootPid, snapshot) => { const tracked = child.livedeskWindowsTrackedRecords || (child.livedeskWindowsTrackedRecords = new Map()); const currentByPid = new Map(snapshot.map(item => [item.pid, item])); const exactCurrentByPid = new Map(); for (const record of tracked.values()) { const current = currentByPid.get(record.pid); if (sameWindowsIdentity(current, record)) exactCurrentByPid.set(record.pid, record); } const lowerBound = windowsTicksAtMilliseconds(Number(child.livedeskWindowsSpawnedAtMs || Date.now()) - 2000); const upperBound = child.livedeskWindowsRootLifetimeEndTicks ? BigInt(child.livedeskWindowsRootLifetimeEndTicks) : null; let changed = true; while (changed) { changed = false; for (const record of snapshot) { const key = `${record.pid}:${record.startOrder}`; if (record.pid === rootPid || tracked.has(key)) continue; let recordStart; try { recordStart = BigInt(record.startOrder); if (recordStart < lowerBound || (upperBound && recordStart > upperBound)) continue; } catch { continue; } const parent = record.parentPid === rootPid ? { depth: 0 } : exactCurrentByPid.get(record.parentPid); if (!parent) continue; const descendant = { ...record, depth: Number(parent.depth || 0) + 1 }; tracked.set(key, descendant); exactCurrentByPid.set(descendant.pid, descendant); changed = true; } } return tracked; };',
+        'const mergeExactWindowsTree = (child, root, snapshot) => { const tracked = child.livedeskWindowsTrackedRecords || (child.livedeskWindowsTrackedRecords = new Map()); const currentByPid = new Map(snapshot.map(item => [item.pid, item])); const currentRoot = currentByPid.get(root.pid) || null; const rootIsExact = sameWindowsIdentity(currentRoot, root); const rootWasReused = Boolean(currentRoot && !rootIsExact); if (rootWasReused) setWindowsRootLifetimeEnd(child, BigInt(currentRoot.startOrder) - 1n); else if (!currentRoot && child.livedeskWindowsRootExitedAtMs) setWindowsRootLifetimeEnd(child, windowsTicksAtMilliseconds(child.livedeskWindowsRootExitedAtMs)); const rootLifetimeClosed = Boolean(child.livedeskWindowsRootLifetimeEndTicks); if (rootIsExact) tracked.set(`${root.pid}:${root.startOrder}`, { ...root, depth: 0 }); const exactCurrentByPid = new Map(); if (rootIsExact) exactCurrentByPid.set(root.pid, { ...root, depth: 0 }); for (const record of tracked.values()) { const current = currentByPid.get(record.pid); if (sameWindowsIdentity(current, record)) exactCurrentByPid.set(record.pid, record); } let changed = true; while (changed) { changed = false; for (const record of snapshot) { const key = `${record.pid}:${record.startOrder}`; if (record.pid === root.pid || tracked.has(key)) continue; let recordStart; try { recordStart = BigInt(record.startOrder); if (recordStart < BigInt(root.startOrder)) continue; if (rootLifetimeClosed && recordStart > BigInt(child.livedeskWindowsRootLifetimeEndTicks)) continue; } catch { continue; } let parent = exactCurrentByPid.get(record.parentPid) || null; if (!parent && !currentRoot && rootLifetimeClosed && record.parentPid === root.pid) parent = { ...root, depth: 0 }; if (!parent) continue; const descendant = { ...record, depth: Number(parent.depth || 0) + 1 }; tracked.set(key, descendant); exactCurrentByPid.set(descendant.pid, descendant); changed = true; } } return tracked; };',
+        'const refreshTrackedWindowsTree = async (child, root = child.livedeskWindowsIdentity || null) => { const snapshot = await queryWindowsProcessTable(); if (root) mergeExactWindowsTree(child, root, snapshot); else mergeRootAbsentWindowsTree(child, Number(child.pid || 0), snapshot); return snapshot; };',
+        '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 trackWindowsChild = child => { if (process.platform !== "win32" || Number(child?.pid || 0) <= 1 || child.livedeskWindowsIdentityPromise) return; child.livedeskWindowsTrackedRecords = new Map(); child.livedeskWindowsSpawnedAtMs = Date.now(); child.livedeskWindowsRootExitedAtMs = null; child.livedeskWindowsTrackingStopped = false; child.once("exit", () => { if (!child.livedeskWindowsRootExitedAtMs) child.livedeskWindowsRootExitedAtMs = Date.now(); setWindowsRootLifetimeEnd(child, windowsTicksAtMilliseconds(child.livedeskWindowsRootExitedAtMs)); }); const refresh = () => { void refreshTrackedWindowsTree(child).then(() => { child.livedeskWindowsTrackingError = null; }).catch(error => { child.livedeskWindowsTrackingError = error; }); }; refresh(); child.livedeskWindowsTrackingTimer = setInterval(refresh, 250); child.livedeskWindowsTrackingTimer.unref?.(); child.livedeskWindowsIdentityPromise = (async () => { while (!child.livedeskWindowsTrackingStopped && !child.livedeskWindowsRootExitedAtMs) { try { const identity = await captureWindowsIdentity(child.pid); child.livedeskWindowsIdentity = identity; refresh(); return identity; } catch (error) { child.livedeskWindowsIdentityError = error; if (!child.livedeskWindowsTrackingStopped && !child.livedeskWindowsRootExitedAtMs) await sleep(250); } } return null; })(); };',
+        'const stopWindowsTracking = child => { child.livedeskWindowsTrackingStopped = true; if (child?.livedeskWindowsTrackingTimer) clearInterval(child.livedeskWindowsTrackingTimer); child.livedeskWindowsTrackingTimer = null; };',
+        'const terminateExactWindowsTrackedTree = (child, root) => { if (child.livedeskWindowsDrainPromise) return child.livedeskWindowsDrainPromise; child.livedeskWindowsDrainPromise = (async () => { let attempt = 0; let emptyPasses = 0; for (;;) { attempt += 1; try { const snapshot = await refreshTrackedWindowsTree(child, root); const currentByPid = new Map(snapshot.map(item => [item.pid, item])); const remaining = [...child.livedeskWindowsTrackedRecords.values()].filter(target => sameWindowsIdentity(currentByPid.get(target.pid), target)).sort((left, right) => Number(right.depth || 0) - Number(left.depth || 0)); if (remaining.length === 0) { emptyPasses += 1; if (emptyPasses >= 2) { stopWindowsTracking(child); return; } } else { emptyPasses = 0; await stopExactWindowsRecords(remaining); } child.livedeskWindowsTrackingError = null; } catch (error) { emptyPasses = 0; child.livedeskWindowsTrackingError = error; if (attempt === 1 || attempt % 10 === 0) process.stderr.write(`LiveDesk update cleanup is retrying exact Windows process-tree drain: ${error?.message || error}\\n`); } await sleep(Math.min(1000, 100 + (attempt * 50))); } })(); return child.livedeskWindowsDrainPromise; };',
         'const stateLockPath = statePath + ".lock"; const lockWaitBuffer = new Int32Array(new SharedArrayBuffer(4));',
         'const waitForStateLock = ms => Atomics.wait(lockWaitBuffer, 0, 0, Math.max(1, ms));',
         'const removeAbandonedStateLock = () => { let owner = null; try { owner = JSON.parse(fs.readFileSync(stateLockPath, "utf8")); } catch {} const ownerPid = Number(owner?.pid || 0); if (Number.isInteger(ownerPid) && ownerPid > 1) { if (isAlive(ownerPid)) return false; } else { try { if (Date.now() - fs.statSync(stateLockPath).mtimeMs < 5000) return false; } catch { return true; } } try { fs.rmSync(stateLockPath); return true; } catch { return false; } };',
         'const withStateLock = callback => { fs.mkdirSync(path.dirname(stateLockPath), { recursive: true }); const deadline = Date.now() + 10000; let descriptor = null; let token = ""; while (descriptor === null) { try { descriptor = fs.openSync(stateLockPath, "wx", 0o600); token = process.pid + "-" + Date.now() + "-" + Math.random().toString(16).slice(2); fs.writeFileSync(descriptor, JSON.stringify({ pid: process.pid, token, acquiredAt: new Date().toISOString() }), "utf8"); } catch (error) { if (descriptor !== null) { try { fs.closeSync(descriptor); } catch {} descriptor = null; try { fs.rmSync(stateLockPath, { force: true }); } catch {} } if (error?.code !== "EEXIST") throw error; if (removeAbandonedStateLock()) continue; if (Date.now() >= deadline) throw new Error("Timed out waiting for the LiveDesk update state lock: " + stateLockPath); waitForStateLock(Math.min(25, Math.max(1, deadline - Date.now()))); } } try { return callback(); } finally { try { fs.closeSync(descriptor); } catch {} try { const owner = JSON.parse(fs.readFileSync(stateLockPath, "utf8")); if (owner?.token === token && Number(owner?.pid) === process.pid) fs.rmSync(stateLockPath, { force: true }); } catch {} } };',
         'const writeFailure = (error, cancelRequested = false) => { try { withStateLock(() => { const previous = readState(); if (previous.operationId && previous.operationId !== operationId) return; if (previous.stage === "preflight-ready" || previous.stage === "waiting-for-shutdown" || previous.stage === "connected" || previous.stage === "restored") return; const now = new Date().toISOString(); const next = { ...previous, operationId, stage: "failed", targetProductVersion, restartVerified: false, cancelRequested: cancelRequested || previous.cancelRequested === true, error: String(error?.message || error).slice(0, 4000), failedAt: now, updatedAt: now }; const temporary = statePath + "." + process.pid + ".handoff.tmp"; fs.writeFileSync(temporary, JSON.stringify(next, null, 2), { encoding: "utf8", mode: 0o600 }); fs.renameSync(temporary, statePath); }); } catch {} process.stderr.write("LiveDesk update handoff failed: " + (error?.message || error) + "\\n"); process.exitCode = 1; };',
         'const writeCancellation = error => withStateLock(() => { const previous = readState(); if (previous.operationId && previous.operationId !== operationId) return "superseded"; if (previous.operationId !== operationId) return false; if (previous.stage === "preflight-ready" || previous.stage === "waiting-for-shutdown") return "ready"; if (previous.stage === "failed") return previous.cancelRequested === true ? "cancelled" : "failed"; const now = new Date().toISOString(); const next = { ...previous, operationId, stage: "failed", targetProductVersion, restartVerified: false, cancelRequested: true, error: String(error?.message || error).slice(0, 4000), cancelledAt: now, failedAt: now, updatedAt: now }; const temporary = statePath + "." + process.pid + ".cancel.tmp"; fs.writeFileSync(temporary, JSON.stringify(next, null, 2), { encoding: "utf8", mode: 0o600 }); fs.renameSync(temporary, statePath); return "cancelled"; });',
-        'const terminateTree = async child => { const pid = Number(child?.pid || 0); if (pid <= 1) return; if (process.platform === "win32") { await new Promise(resolve => { const killer = spawn("taskkill.exe", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" }); let done = false; const finish = () => { if (done) return; done = true; clearTimeout(timer); resolve(); }; const timer = setTimeout(() => { try { killer.kill("SIGKILL"); } catch {} finish(); }, 10000); killer.once("error", finish); killer.once("exit", finish); }); if (isAlive(pid)) { try { child.kill("SIGKILL"); } catch {} } return; } try { process.kill(-pid, "SIGTERM"); } catch { try { child.kill("SIGTERM"); } catch {} } const gracefulDeadline = Date.now() + 2000; while (Date.now() < gracefulDeadline && (isGroupAlive(pid) || isAlive(pid))) await sleep(100); if (isGroupAlive(pid) || isAlive(pid)) { try { process.kill(-pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch {} } } };',
+        'const terminateTree = async child => { const pid = Number(child?.pid || 0); if (pid <= 1) return; if (process.platform === "win32") { const root = child.livedeskWindowsIdentity || await child.livedeskWindowsIdentityPromise; if (!root && !child.livedeskWindowsRootExitedAtMs) { child.livedeskWindowsTrackingError = child.livedeskWindowsIdentityError || new Error(`No immutable Windows identity is available for pid=${pid}`); while (!child.livedeskWindowsRootExitedAtMs && !child.livedeskWindowsIdentity) await sleep(250); } await terminateExactWindowsTrackedTree(child, child.livedeskWindowsIdentity || root || null); return; } try { process.kill(-pid, "SIGTERM"); } catch { try { child.kill("SIGTERM"); } catch {} } const gracefulDeadline = Date.now() + 2000; while (Date.now() < gracefulDeadline && (isGroupAlive(pid) || isAlive(pid))) await sleep(100); if (isGroupAlive(pid) || isAlive(pid)) { try { process.kill(-pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch {} } } };',
         'const writeHandoffStarted = () => withStateLock(() => { if (deadlineExpired()) throw new Error("The absolute LiveDesk Client update deadline expired before handoff."); const previous = readState(); if (previous.operationId !== operationId) throw new Error("LiveDesk update handoff was superseded before exact-package launch."); const now = new Date().toISOString(); const next = { ...previous, operationId, stage: "handoff-started", starterPid: process.pid, updateDeadlineEpochMs, restartVerified: false, error: "", updatedAt: now }; const temporary = statePath + "." + process.pid + ".handoff-started.tmp"; fs.writeFileSync(temporary, JSON.stringify(next, null, 2), { encoding: "utf8", mode: 0o600 }); fs.renameSync(temporary, statePath); });',
-        'const monitorPreflight = child => { let settled = false; const finish = (error, preserveFailure = false) => { if (settled) return; settled = true; clearInterval(poll); clearTimeout(timeout); child.unref(); if (preserveFailure) process.exitCode = 1; else if (error) writeFailure(error); }; const inspect = () => { const state = readState(); if (state.operationId !== operationId) return; if (state.stage === "preflight-ready" || state.stage === "waiting-for-shutdown") finish(); else if (state.stage === "failed") finish(null, true); }; const cancelTimedOutHandoff = async () => { const error = new Error(deadlineExpired() ? "The absolute LiveDesk Client update deadline expired before exact-package preflight." : "Timed out waiting for exact-package update preflight."); while (!settled) { inspect(); if (settled) return; let outcome; try { outcome = writeCancellation(error); } catch (lockError) { finish(lockError); return; } if (outcome === "ready" || outcome === "failed") { inspect(); if (settled) return; } else if (outcome === "cancelled" || outcome === "superseded") { await terminateTree(child); finish(null, true); return; } await sleep(25); } }; const poll = setInterval(inspect, 100); const timeoutMs = Math.max(1, Math.min(Math.max(1000, Number(process.env.LIVEDESK_CLIENT_UPDATE_HANDOFF_TIMEOUT_MS || 140000)), updateDeadlineEpochMs - Date.now())); const timeout = setTimeout(() => { void cancelTimedOutHandoff(); }, timeoutMs); child.once("exit", (code, signal) => { inspect(); if (!settled) finish(new Error("Exact-package update supervisor exited before preflight (code=" + (code ?? "none") + ", signal=" + (signal || "none") + ").")); }); inspect(); };',
+        'const monitorPreflight = child => { let settled = false; let draining = false; let drainPromise = null; const finish = (error, preserveFailure = false) => { if (settled) return; settled = true; clearInterval(poll); clearTimeout(timeout); stopWindowsTracking(child); child.unref(); if (preserveFailure) process.exitCode = 1; else if (error) writeFailure(error); }; const drainAndFinish = (error, preserveFailure = false) => { if (settled) return Promise.resolve(); draining = true; if (!drainPromise) drainPromise = terminateTree(child).then(() => finish(error, preserveFailure)); return drainPromise; }; const inspect = () => { if (draining) return; const state = readState(); if (state.operationId !== operationId) return; if (state.stage === "preflight-ready" || state.stage === "waiting-for-shutdown") finish(); else if (state.stage === "failed") void drainAndFinish(null, true); }; const cancelTimedOutHandoff = async () => { const error = new Error(deadlineExpired() ? "The absolute LiveDesk Client update deadline expired before exact-package preflight." : "Timed out waiting for exact-package update preflight."); draining = true; while (!settled) { let outcome; try { outcome = writeCancellation(error); } catch (lockError) { await drainAndFinish(lockError); return; } if (outcome === "ready") { draining = false; inspect(); return; } if (outcome === "failed" || outcome === "cancelled" || outcome === "superseded") { await drainAndFinish(null, true); return; } await sleep(25); } }; const poll = setInterval(inspect, 100); const timeoutMs = Math.max(1, Math.min(Math.max(1000, Number(process.env.LIVEDESK_CLIENT_UPDATE_HANDOFF_TIMEOUT_MS || 140000)), updateDeadlineEpochMs - Date.now())); const timeout = setTimeout(() => { void cancelTimedOutHandoff().catch(error => { void drainAndFinish(error); }); }, timeoutMs); child.once("exit", (code, signal) => { inspect(); if (settled || draining) return; const error = new Error("Exact-package update supervisor exited before preflight (code=" + (code ?? "none") + ", signal=" + (signal || "none") + ")."); void drainAndFinish(error); }); inspect(); };',
         'const prepareNeutralCwd = () => { if (!neutralCwd) throw new Error("LiveDesk update neutral working directory is unavailable"); fs.mkdirSync(neutralCwd, { recursive: true }); const unexpectedEntry = fs.readdirSync(neutralCwd)[0]; if (unexpectedEntry) { const shadow = path.join(neutralCwd, unexpectedEntry); throw new Error("LiveDesk update neutral working directory is shadowed by " + shadow + ": " + neutralCwd); } };',
         'if (!operationId || !versionPattern.test(targetProductVersion) || deadlineExpired()) { writeFailure(new Error("Invalid or expired LiveDesk exact-package update handoff."), true); } else { try { prepareNeutralCwd(); writeHandoffStarted();',
         'const env = { ...process.env, LIVEDESK_UPDATE_STARTER_PID: String(process.pid) }; const isolated = new Set(["init_cwd", "npm_config_local_prefix", "npm_config_workspace", "npm_config_workspaces", "npm_config_include_workspace_root", "npm_package_json", "npm_lifecycle_event", "npm_lifecycle_script"]); for (const key of Object.keys(env)) if (isolated.has(key.toLowerCase())) delete env[key]; env.INIT_CWD = neutralCwd; env.npm_config_local_prefix = neutralCwd; env.npm_config_workspaces = "false"; env.npm_config_include_workspace_root = "false";',
@@ -1587,7 +1600,7 @@ function buildClientUpdateBootstrapScript() {
         'const args = ["-y", "--prefer-online", "--prefix", neutralCwd, "--workspaces=false", "livedesk@" + targetProductVersion, "--internal-legacy-client-update"];',
         'const quoteCmd = value => "\\"" + String(value).replaceAll("%", "%%").replaceAll("\\"", "\\"\\"") + "\\"";',
         'const invocation = npxCli ? { command: process.execPath, args: [npxCli, ...args] } : process.platform === "win32" ? { command: env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", "call " + quoteCmd(npx) + " " + args.map(quoteCmd).join(" ")] } : { command: npx, args };',
-        'if (!npxCli && path.isAbsolute(npx) && !fs.existsSync(npx)) { writeFailure(new Error("LiveDesk npx executable was not found: " + npx)); } else { try { const child = spawn(invocation.command, invocation.args, { cwd: neutralCwd, env, detached: true, stdio: "ignore", windowsHide: true }); child.once("error", writeFailure); child.once("spawn", () => monitorPreflight(child)); } catch (error) { writeFailure(error); } }',
+        'if (!npxCli && path.isAbsolute(npx) && !fs.existsSync(npx)) { writeFailure(new Error("LiveDesk npx executable was not found: " + npx)); } else { try { const child = spawn(invocation.command, invocation.args, { cwd: neutralCwd, env, detached: true, stdio: "ignore", windowsHide: true }); trackWindowsChild(child); child.once("error", writeFailure); child.once("spawn", () => { trackWindowsChild(child); monitorPreflight(child); }); } catch (error) { writeFailure(error); } }',
         '} catch (error) { writeFailure(error, deadlineExpired()); } }',
         ''
     ].join('\n');

package/client/bin/livedesk-client.js

@@ -18,6 +18,7 @@ import {
     installAgentTerminationHandlers,
     signalAgentTree
 } from '../src/runtime/agent-process-lifecycle.js';
+import { writeWindowsOwnedProcessManifest } from '../src/runtime/windows-owned-process-manifest.js';
 import { createHubWakeListener } from '../src/runtime/hub-wake-listener.js';
 import {
     inspectLinuxVideoAcceleration,
@@ -73,7 +74,69 @@ let linuxVideoAccelerationStatus = null;
 let discoveryWakeController = new AbortController();
 let networkChangeMonitor = null;
 const sessionRefreshesInFlight = new WeakMap();
-installAgentTerminationHandlers({ getAgentProcess: () => activeAgentProcess });
+const disposeAgentTerminationHandlers = installAgentTerminationHandlers({
+    getAgentProcess: () => activeAgentProcess
+});
+
+function readWindowsManifestOwnerFromEnvironment(env = process.env) {
+    if (process.platform !== 'win32') return null;
+    const rawOwner = {
+        pid: String(env.LIVEDESK_RUNTIME_OWNER_PID || '').trim(),
+        ownerToken: String(env.LIVEDESK_RUNTIME_OWNER_TOKEN || '').trim(),
+        ownerInstanceMarker: String(env.LIVEDESK_RUNTIME_OWNER_INSTANCE_MARKER || '').trim(),
+        ownerStartOrder: String(env.LIVEDESK_RUNTIME_OWNER_START_ORDER || '').trim()
+    };
+    const hasAnyOwnerField = Object.values(rawOwner).some(Boolean);
+    if (!hasAnyOwnerField) return null;
+    const owner = {
+        ...rawOwner,
+        pid: Number(rawOwner.pid)
+    };
+    if (owner.pid !== process.pid
+        || !/^[a-f0-9]{32}$/i.test(owner.ownerToken)
+        || !owner.ownerInstanceMarker.startsWith(`${process.pid}:`)
+        || !/^\d+$/.test(owner.ownerStartOrder)) {
+        console.warn(
+            '[LiveDesk Client] Windows process-manifest publication is disabled because '
+            + 'the unified launcher owner tuple is incomplete or does not name this exact process.'
+        );
+        return null;
+    }
+    return owner;
+}
+
+const WINDOWS_PROCESS_MANIFEST_OWNER = readWindowsManifestOwnerFromEnvironment();
+
+function publishWindowsOwnedAgentRecords(records, {
+    rootRecord,
+    snapshot
+} = {}) {
+    if (!WINDOWS_PROCESS_MANIFEST_OWNER || !rootRecord || records.length === 0) return;
+    const ownerRecord = (Array.isArray(snapshot) ? snapshot : []).find(
+        record => Number(record?.pid || 0) === WINDOWS_PROCESS_MANIFEST_OWNER.pid
+    );
+    const exactOwnerGeneration = ownerRecord
+        && ownerRecord.startOrder === WINDOWS_PROCESS_MANIFEST_OWNER.ownerStartOrder
+        && `${ownerRecord.pid}:${ownerRecord.startMarker}`
+            === WINDOWS_PROCESS_MANIFEST_OWNER.ownerInstanceMarker;
+    if (!exactOwnerGeneration) {
+        throw new Error(
+            'The Windows process snapshot did not confirm the unified launcher owner generation.'
+        );
+    }
+    const publication = writeWindowsOwnedProcessManifest({
+        stateDir: UNIFIED_CLIENT_STATE_DIR,
+        owner: WINDOWS_PROCESS_MANIFEST_OWNER,
+        records
+    });
+    if (!publication.ok) {
+        throw publication.error || new Error('Windows owned-process manifest publication failed.');
+    }
+}
+
+export function requestClientRuntimeShutdown(signal = 'SIGTERM') {
+    disposeAgentTerminationHandlers.requestTermination(signal);
+}
 
 function requestActiveAgentStop(signal = 'SIGTERM') {
     const child = activeAgentProcess;
@@ -3233,8 +3296,8 @@ async function chooseClientConnection(supabase, options = {}) {
                 }, 150);
                 return { ...result, slotNumber, saved: true, restarting: true };
             },
-            onRestart: () => process.kill(process.pid, 'SIGTERM'),
-            onShutdown: () => process.kill(process.pid, 'SIGTERM'),
+            onRestart: () => requestClientRuntimeShutdown('SIGTERM'),
+            onShutdown: () => requestClientRuntimeShutdown('SIGTERM'),
             onDisconnect: () => requestActiveAgentStop(),
             // Ending the current Agent causes the unified lifecycle loop to
             // discard its old manager/pair token and start Supabase discovery
@@ -4308,7 +4371,10 @@ function spawnAgent(command, args, env = process.env, onStart = null) {
     });
     child.livedeskOwnsProcessGroup = ownsProcessGroup;
     child.livedeskWindowsTreeTracker = createWindowsProcessTreeTracker(child, {
-        spawnedAtMs: agentSpawnedAtMs
+        spawnedAtMs: agentSpawnedAtMs,
+        publishTrackedRecords: WINDOWS_PROCESS_MANIFEST_OWNER
+            ? publishWindowsOwnedAgentRecords
+            : null
     });
     activeAgentProcess = child;
     if (typeof onStart === 'function') {

package/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.201",
+  "version": "0.1.202",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -41,10 +41,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.409",
-    "@livedesk/fast-osx-arm64": "0.1.409",
-    "@livedesk/fast-osx-x64": "0.1.409",
-    "@livedesk/fast-win-x64": "0.1.409"
+    "@livedesk/fast-linux-x64": "0.1.410",
+    "@livedesk/fast-osx-arm64": "0.1.410",
+    "@livedesk/fast-osx-x64": "0.1.410",
+    "@livedesk/fast-win-x64": "0.1.410"
   },
   "publishConfig": {
     "access": "public"