@livedesk/client 0.1.200 → 0.1.202

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.200",
+  "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.407",
-    "@livedesk/fast-osx-arm64": "0.1.407",
-    "@livedesk/fast-osx-x64": "0.1.407",
-    "@livedesk/fast-win-x64": "0.1.407"
+    "@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"

package/src/runtime/agent-process-lifecycle.js

@@ -30,6 +30,14 @@ function windowsTicksForUnixMilliseconds(milliseconds) {
     return BigInt(Math.trunc(Number(milliseconds) || 0)) * 10_000n + 621_355_968_000_000_000n;
 }
 
+function unixMillisecondsForWindowsTicks(ticks) {
+    try {
+        return Number((BigInt(ticks) - 621_355_968_000_000_000n) / 10_000n);
+    } catch {
+        return 0;
+    }
+}
+
 function windowsRecordIsWithinLifetime(record, spawnedAtMs, exitedAtMs = null) {
     if (!record?.startOrder) return false;
     try {
@@ -72,7 +80,7 @@ export async function queryWindowsProcessTable({
 } = {}) {
     const script = [
         '$ErrorActionPreference = "Stop";',
-        '@(Get-CimInstance Win32_Process | ForEach-Object {',
+        '@(Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate | ForEach-Object {',
         '  $creation = [string]$_.CreationDate;',
         '  $ticks = if ($_.CreationDate) { [string]$_.CreationDate.ToUniversalTime().Ticks } else { "" };',
         '  [pscustomobject]@{ ProcessId = [int]$_.ProcessId; ParentProcessId = [int]$_.ParentProcessId; CreationDate = $creation; CreationUtcTicks = $ticks }',
@@ -102,31 +110,42 @@ export async function queryWindowsProcessTable({
 }
 
 /**
- * Rechecks CreationDate inside the same PowerShell process immediately before
- * taskkill. PID reuse therefore becomes a harmless identity mismatch instead
- * of terminating the replacement process.
+ * Rechecks CreationDate and force-stops the single PID inside the same
+ * PowerShell process. PID reuse therefore becomes a harmless identity mismatch
+ * instead of terminating the replacement process.
  */
-export async function terminateExactWindowsProcessTree(record, {
-    includeTree = true,
+export async function terminateExactWindowsProcessTree(recordOrRecords, {
     execFileImpl = execFile
 } = {}) {
-    const target = normalizeWindowsProcessRecord(record);
-    if (!target) {
-        return { ok: false, error: new Error('An immutable Windows process record is required.') };
+    const targets = (Array.isArray(recordOrRecords) ? recordOrRecords : [recordOrRecords])
+        .map(normalizeWindowsProcessRecord)
+        .filter(Boolean);
+    if (targets.length === 0) {
+        return { ok: false, error: new Error('At least one immutable Windows process record is required.') };
     }
-    const expectedStartTicks = target.startOrder;
-    const treeArgument = includeTree ? ', "/T"' : '';
+    const targetsJson = JSON.stringify(targets.map(target => ({
+        pid: target.pid,
+        startOrder: target.startOrder
+    }))).replaceAll("'", "''");
     const script = [
         '$ErrorActionPreference = "Stop";',
-        `$targetPid = ${target.pid};`,
-        `$expectedStartTicks = '${expectedStartTicks}';`,
-        '$target = Get-CimInstance Win32_Process -Filter "ProcessId = $targetPid" -ErrorAction SilentlyContinue | Select-Object -First 1;',
-        'if (-not $target) { exit 0 };',
-        '$targetStartTicks = if ($target.CreationDate) { [string]$target.CreationDate.ToUniversalTime().Ticks } else { "" };',
-        'if ($targetStartTicks -ne $expectedStartTicks) { exit 0 };',
-        `$arguments = @("/PID", [string]$targetPid${treeArgument}, "/F");`,
-        '$taskkill = Start-Process -FilePath "taskkill.exe" -ArgumentList $arguments -NoNewWindow -Wait -PassThru;',
-        'exit $taskkill.ExitCode'
+        `$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 runExecFile(
         'powershell.exe',
@@ -148,7 +167,11 @@ export function createWindowsProcessTreeTracker(child, {
     snapshotIntervalMs = DEFAULT_WINDOWS_TREE_SNAPSHOT_MS,
     spawnedAtMs = Date.now(),
     setIntervalImpl = setInterval,
-    clearIntervalImpl = clearInterval
+    clearIntervalImpl = clearInterval,
+    publishTrackedRecords = null,
+    reportPublisherError = error => console.warn(
+        `[LiveDesk Client] Windows owned-process manifest warning: ${error?.message || error}`
+    )
 } = {}) {
     const rootPid = Number(child?.pid || 0);
     const enabled = platform === 'win32' && Number.isInteger(rootPid) && rootPid > 1;
@@ -164,19 +187,33 @@ export function createWindowsProcessTreeTracker(child, {
     let lastSnapshotHadRootPid = false;
     let successfulSnapshotAfterExit = false;
     let ambiguousRootReuse = false;
+    let lastPublisherError = null;
 
     const mergeSnapshot = snapshot => {
         const records = (Array.isArray(snapshot) ? snapshot : [])
             .map(normalizeWindowsProcessRecord)
             .filter(Boolean);
         lastSnapshot = records;
-        if (rootExitedAtMs !== null) successfulSnapshotAfterExit = true;
         const currentByPid = new Map(records.map(record => [record.pid, record]));
         const currentRoot = currentByPid.get(rootPid) || null;
         lastSnapshotHadRootPid = Boolean(currentRoot);
-        if (rootRecord && currentRoot && !sameWindowsProcess(currentRoot, rootRecord)) {
+        const rootWasReused = Boolean(
+            rootRecord && currentRoot && !sameWindowsProcess(currentRoot, rootRecord)
+        );
+        if (rootWasReused) {
             ambiguousRootReuse = true;
         }
+        if (rootRecord && rootExitedAtMs === null && (!currentRoot || rootWasReused)) {
+            // The exit event can trail the first CIM snapshot that proves the
+            // exact root is gone. Use that proof immediately so a surviving
+            // child first observed in this same snapshot is still owned.
+            // For PID reuse, cap the old lifetime just before the replacement
+            // CreationDate so replacement-root children remain excluded.
+            rootExitedAtMs = rootWasReused
+                ? unixMillisecondsForWindowsTicks(currentRoot.startOrder) - 1
+                : Date.now();
+        }
+        if (rootExitedAtMs !== null) successfulSnapshotAfterExit = true;
         if (!rootRecord
             && currentRoot
             && windowsRecordIsWithinLifetime(currentRoot, spawnedAtMs, rootExitedAtMs)) {
@@ -202,9 +239,11 @@ export function createWindowsProcessTreeTracker(child, {
             }
         }
 
-        // If the root PID is absent, Windows retains ParentProcessId on its
-        // surviving direct children. If the PID has already been reused, do
-        // not infer any new lineage through that ambiguous numeric PID.
+        // Windows retains ParentProcessId on surviving direct children after
+        // the root exits. A reused root PID is also safe to bridge only for a
+        // direct child whose immutable creation time is inside the original
+        // root lifetime; children created by the replacement root are rejected
+        // by windowsRecordIsWithinLifetime.
         const rootAbsent = !currentRoot;
         let changed = true;
         while (changed) {
@@ -215,7 +254,7 @@ export function createWindowsProcessTreeTracker(child, {
                 let parent = exactCurrentByPid.get(record.parentPid) || null;
                 if (!parent
                     && rootExitedAtMs !== null
-                    && rootAbsent
+                    && (rootAbsent || rootWasReused)
                     && record.parentPid === rootPid) {
                     parent = rootRecord || { pid: rootPid, depth: 0 };
                 }
@@ -233,10 +272,34 @@ export function createWindowsProcessTreeTracker(child, {
         if (inFlight) return inFlight;
         inFlight = Promise.resolve()
             .then(() => queryProcessTableImpl())
-            .then(snapshot => {
+            .then(async snapshot => {
                 mergeSnapshot(snapshot);
                 lastError = null;
-                return { ok: true, records: lastSnapshot };
+                if (typeof publishTrackedRecords === 'function') {
+                    try {
+                        await publishTrackedRecords(
+                            [...tracked.values()].map(record => ({ ...record })),
+                            {
+                                rootPid,
+                                rootRecord: rootRecord ? { ...rootRecord } : null,
+                                snapshot: lastSnapshot.map(record => ({ ...record })),
+                                terminal: stopped
+                            }
+                        );
+                        lastPublisherError = null;
+                    } catch (error) {
+                        // Manifest publication must never break the in-memory
+                        // cleanup proof. Keep tracking, surface diagnostics,
+                        // and retry on the next cadence/terminal refresh.
+                        lastPublisherError = error;
+                        try { reportPublisherError(error); } catch { /* diagnostics cannot own lifecycle */ }
+                    }
+                }
+                return {
+                    ok: true,
+                    records: lastSnapshot,
+                    publisherError: lastPublisherError
+                };
             })
             .catch(error => {
                 lastError = error;
@@ -285,7 +348,8 @@ export function createWindowsProcessTreeTracker(child, {
                 .filter(record => sameWindowsProcess(currentByPid.get(record.pid), record))
                 .map(record => ({ ...record }));
         },
-        getLastError: () => lastError
+        getLastError: () => lastError,
+        getLastPublisherError: () => lastPublisherError
     };
 }
 
@@ -345,17 +409,18 @@ export async function drainOwnedWindowsAgentTree(child, {
             } else {
                 const remaining = tracker.getCurrentExactRecords();
                 if (remaining.length === 0
-                    && tracker.hasSafeFinalSnapshot?.()
-                    && !tracker.hasAmbiguousRootReuse?.()) {
+                    && tracker.hasSafeFinalSnapshot?.()) {
                     return { ok: true, remaining: [] };
                 }
                 const ordered = [...remaining].sort((left, right) => (
-                    Number(left.depth || 0) - Number(right.depth || 0)
+                    Number(right.depth || 0) - Number(left.depth || 0)
                 ));
-                for (const record of ordered) {
-                    const termination = await terminateExactTreeImpl(record, { includeTree: true });
-                    if (termination?.ok === false) lastError = termination.error || lastError;
-                }
+                // One PowerShell invocation receives the descendant-first
+                // immutable snapshot, then rechecks every PID CreationDate
+                // immediately before its own Stop-Process. No taskkill /T
+                // traversal can follow an unverified stale PPID edge.
+                const termination = await terminateExactTreeImpl(ordered, { includeTree: false });
+                if (termination?.ok === false) lastError = termination.error || lastError;
             }
             if (attempt < attempts) {
                 await waitImpl(Math.max(25, Number(retryMs) || 100));
@@ -366,8 +431,7 @@ export async function drainOwnedWindowsAgentTree(child, {
         const remaining = finalRefresh.ok ? tracker.getCurrentExactRecords() : tracker.getTrackedRecords();
         if (finalRefresh.ok
             && remaining.length === 0
-            && tracker.hasSafeFinalSnapshot?.()
-            && !tracker.hasAmbiguousRootReuse?.()) {
+            && tracker.hasSafeFinalSnapshot?.()) {
             return { ok: true, remaining: [] };
         }
         const error = finalRefresh.error || lastError || new Error(
@@ -384,6 +448,55 @@ export async function drainOwnedWindowsAgentTree(child, {
     return child.livedeskWindowsDrainPromise;
 }
 
+/**
+ * Fail-closed wrapper for lifecycle replacement and terminal shutdown.
+ * A bounded drain attempt can fail because CIM/taskkill is temporarily busy;
+ * that must never let the launcher exit and orphan an owned FFmpeg descendant.
+ */
+export async function drainOwnedWindowsAgentTreeUntilStopped(child, {
+    platform = process.platform,
+    retryForeverMs = 1000,
+    waitImpl = waitMilliseconds,
+    reportTerminationFailure = message => console.error(message),
+    ...drainOptions
+} = {}) {
+    if (platform !== 'win32') return { ok: true, remaining: [] };
+    if (child?.livedeskWindowsDrainUntilStoppedPromise) {
+        return child.livedeskWindowsDrainUntilStoppedPromise;
+    }
+
+    child.livedeskWindowsDrainUntilStoppedPromise = (async () => {
+        let attempt = 0;
+        while (true) {
+            attempt += 1;
+            // drainOwnedWindowsAgentTree memoizes one bounded proof attempt.
+            // Clear only that completed attempt; the immutable tracker remains
+            // attached to the exact child and is refreshed on every retry.
+            child.livedeskWindowsDrainPromise = null;
+            let result;
+            try {
+                result = await drainOwnedWindowsAgentTree(child, {
+                    platform,
+                    waitImpl,
+                    reportTerminationFailure,
+                    ...drainOptions
+                });
+            } catch (error) {
+                result = { ok: false, error, remaining: [] };
+            }
+            if (result?.ok !== false) {
+                return result;
+            }
+            reportTerminationFailure(
+                `[LiveDesk Client] Exact Windows Agent tree is not drained yet `
+                + `(attempt ${attempt}); the launcher will remain alive and retry.`
+            );
+            await waitImpl(Math.max(100, Number(retryForeverMs) || 1000));
+        }
+    })();
+    return child.livedeskWindowsDrainUntilStoppedPromise;
+}
+
 export function isOwnedUnixProcessGroupAlive(child, platform = process.platform, signalProcess = (pid, signal) => process.kill(pid, signal)) {
     const processId = Number(child?.pid || 0);
     if (platform === 'win32'
@@ -513,7 +626,7 @@ export function installAgentTerminationHandlers({
     shutdownTimeoutMs = 8000,
     platform = process.platform,
     signalProcess = (pid, signal) => process.kill(pid, signal),
-    drainWindowsTree = drainOwnedWindowsAgentTree,
+    drainWindowsTree = drainOwnedWindowsAgentTreeUntilStopped,
     windowsTerminateAttemptLimit = 3,
     windowsTerminateRetryMs = 100,
     unixTerminateRetryMs = 1000,
@@ -553,12 +666,14 @@ export function installAgentTerminationHandlers({
             let poll = null;
             let timeout = null;
             let unixRetryTimer = null;
+            let windowsRetryTimer = null;
             const finish = () => {
                 if (finished) return;
                 finished = true;
                 if (poll) clearInterval(poll);
                 if (timeout) clearTimeout(timeout);
                 if (unixRetryTimer) clearTimeout(unixRetryTimer);
+                if (windowsRetryTimer) clearTimeout(windowsRetryTimer);
                 exitProcess(exitCode);
             };
             const processId = Number(child?.pid || 0);
@@ -571,25 +686,37 @@ export function installAgentTerminationHandlers({
                 // restarts and unexpected Agent exits. The promise is stored
                 // on the child so spawnAgent cannot race ahead and launch a
                 // replacement while terminal shutdown is still draining.
-                if (!child.livedeskTreeStopPromise) {
-                    child.livedeskTreeStopPromise = Promise.resolve().then(() => drainWindowsTree(child, {
-                        platform,
-                        maxAttempts: windowsTerminateAttemptLimit,
-                        retryMs: windowsTerminateRetryMs,
-                        reportTerminationFailure
-                    }));
-                }
-                child.livedeskTreeStopPromise
-                    .catch(error => ({ ok: false, error }))
-                    .then(result => {
-                        if (result?.ok === false) {
+                const drainUntilStopped = () => {
+                    if (finished) return;
+                    if (!child.livedeskTreeStopPromise) {
+                        child.livedeskTreeStopPromise = Promise.resolve().then(() => drainWindowsTree(child, {
+                            platform,
+                            maxAttempts: windowsTerminateAttemptLimit,
+                            retryMs: windowsTerminateRetryMs,
+                            retryForeverMs: windowsTerminateRetryMs,
+                            reportTerminationFailure
+                        }));
+                    }
+                    child.livedeskTreeStopPromise
+                        .catch(error => ({ ok: false, error }))
+                        .then(result => {
+                            if (result?.ok !== false) {
+                                finish();
+                                return;
+                            }
                             reportTerminationFailure(
-                                `[LiveDesk Client] Terminal shutdown preserved an undrained exact Windows Agent tree: `
-                                + `${result.error?.message || 'bounded drain failed'}`
+                                `[LiveDesk Client] Terminal shutdown retained an exact Windows Agent tree: `
+                                + `${result.error?.message || 'bounded drain failed'}. Retrying before exit.`
                             );
-                        }
-                        finish();
-                    });
+                            child.livedeskTreeStopPromise = null;
+                            child.livedeskWindowsDrainPromise = null;
+                            windowsRetryTimer = setTimeout(
+                                drainUntilStopped,
+                                Math.max(100, Number(windowsTerminateRetryMs) || 100)
+                            );
+                        });
+                };
+                drainUntilStopped();
                 return;
             }
             const finishWhenTreeStops = () => {
@@ -654,9 +781,18 @@ export function installAgentTerminationHandlers({
         hostProcess.on(signal, handler);
     }
 
-    return () => {
+    const dispose = () => {
         for (const [signal, handler] of handlers) {
             hostProcess.removeListener(signal, handler);
         }
     };
+    // Windows process.kill(pid, 'SIGTERM') can terminate a process without
+    // dispatching its JavaScript SIGTERM listener. Replacement startup must
+    // enter this exact cleanup state machine directly instead of simulating an
+    // operating-system signal.
+    dispose.requestTermination = (signal = 'SIGTERM') => {
+        const normalizedSignal = signal === 'SIGINT' ? 'SIGINT' : 'SIGTERM';
+        handlers.get(normalizedSignal)?.();
+    };
+    return dispose;
 }

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

@@ -0,0 +1,235 @@
+import { randomBytes } from 'node:crypto';
+import {
+    chmodSync,
+    mkdirSync,
+    readFileSync,
+    renameSync,
+    unlinkSync,
+    writeFileSync
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import os from 'node:os';
+
+export const WINDOWS_OWNED_PROCESS_MANIFEST_VERSION = 1;
+export const DEFAULT_WINDOWS_OWNED_PROCESS_MANIFEST_MAX_AGE_MS = 30_000;
+
+const WINDOWS_OWNED_PROCESS_MANIFEST_FILE_NAME = 'client-owned-windows-processes.json';
+const MAX_FUTURE_CLOCK_SKEW_MS = 5_000;
+
+function resultError(message) {
+    return new Error(message);
+}
+
+function resolveNow(now) {
+    const value = typeof now === 'function' ? now() : now;
+    const milliseconds = value === undefined ? Date.now() : Number(value);
+    return Number.isFinite(milliseconds) ? milliseconds : NaN;
+}
+
+function normalizeOwner(value) {
+    const owner = {
+        pid: Number(value?.pid || 0),
+        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.startsWith(`${owner.pid}:`)
+        || !/^\d+$/.test(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 normalizeRecord(value) {
+    const record = {
+        pid: Number(value?.pid ?? value?.ProcessId ?? 0),
+        parentPid: Number(value?.parentPid ?? value?.ParentProcessId ?? 0),
+        startMarker: String(value?.startMarker ?? value?.CreationDate ?? '').trim(),
+        startOrder: String(value?.startOrder ?? value?.CreationUtcTicks ?? '').trim(),
+        depth: Math.max(0, Math.trunc(Number(value?.depth || 0)))
+    };
+    if (!Number.isInteger(record.pid)
+        || record.pid <= 1
+        || !Number.isInteger(record.parentPid)
+        || record.parentPid < 0
+        || !record.startMarker
+        || !/^\d+$/.test(record.startOrder)
+        || !Number.isFinite(record.depth)) {
+        return null;
+    }
+    return record;
+}
+
+function normalizeRecords(values) {
+    if (!Array.isArray(values)) return null;
+    const records = values.map(normalizeRecord);
+    if (records.some(record => !record)) return null;
+    const unique = new Map();
+    for (const record of records) {
+        unique.set(`${record.pid}:${record.startOrder}`, record);
+    }
+    return [...unique.values()];
+}
+
+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);
+        // Existing state directories can have been created by older versions;
+        // enforce the owner-only contract after every atomic replacement too.
+        try { chmodSync(path, 0o600); } catch { /* Windows ACLs remain authoritative */ }
+        published = true;
+    } finally {
+        if (!published) {
+            try { unlinkSync(temporaryPath); } catch { /* temporary file was never published */ }
+        }
+    }
+}
+
+export function getWindowsOwnedProcessManifestPath(
+    stateDir = join(os.homedir(), '.livedesk')
+) {
+    return join(stateDir, WINDOWS_OWNED_PROCESS_MANIFEST_FILE_NAME);
+}
+
+/**
+ * Publishes one immutable launcher generation and all exact Agent records.
+ * Every record retains PID + full-precision CreationDate ticks so a later
+ * launcher can harmlessly ignore a PID that has since been reused.
+ */
+export function writeWindowsOwnedProcessManifest({
+    stateDir,
+    owner,
+    records,
+    now
+} = {}) {
+    const exactOwner = normalizeOwner(owner);
+    const exactRecords = normalizeRecords(records);
+    const nowMs = resolveNow(now);
+    if (!exactOwner) {
+        return {
+            ok: false,
+            error: resultError('An exact Windows LiveDesk launcher owner is required.')
+        };
+    }
+    if (!exactRecords) {
+        return {
+            ok: false,
+            error: resultError('Every Windows LiveDesk process record requires exact PID and CreationDate identity.')
+        };
+    }
+    if (!Number.isFinite(nowMs)) {
+        return { ok: false, error: resultError('A valid manifest publication time is required.') };
+    }
+    const path = getWindowsOwnedProcessManifestPath(stateDir);
+    const updatedAt = new Date(nowMs).toISOString();
+    try {
+        writeJsonAtomic(path, {
+            protocolVersion: WINDOWS_OWNED_PROCESS_MANIFEST_VERSION,
+            owner: exactOwner,
+            updatedAt,
+            records: exactRecords
+        });
+        return { ok: true, path, records: exactRecords, updatedAt };
+    } catch (error) {
+        return { ok: false, path, records: [], error };
+    }
+}
+
+/**
+ * Reads only a fresh manifest belonging to the exact runtime-lock generation.
+ * Owner mismatch, malformed identity, expiry, and PID reuse all fail closed.
+ */
+export function readWindowsOwnedProcessManifest({
+    stateDir,
+    owner,
+    maxAgeMs = DEFAULT_WINDOWS_OWNED_PROCESS_MANIFEST_MAX_AGE_MS,
+    now
+} = {}) {
+    const exactOwner = normalizeOwner(owner);
+    const nowMs = resolveNow(now);
+    const maximumAge = Number(maxAgeMs);
+    const path = getWindowsOwnedProcessManifestPath(stateDir);
+    if (!exactOwner) {
+        return {
+            ok: false,
+            records: [],
+            error: resultError('An exact Windows LiveDesk launcher owner is required.')
+        };
+    }
+    if (!Number.isFinite(nowMs)
+        || !Number.isFinite(maximumAge)
+        || maximumAge < 0) {
+        return {
+            ok: false,
+            records: [],
+            error: resultError('A valid manifest time and maximum age are required.')
+        };
+    }
+
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    } catch (error) {
+        return { ok: false, records: [], error };
+    }
+    const updatedAt = String(parsed?.updatedAt || '');
+    const updatedAtMs = Date.parse(updatedAt);
+    if (parsed?.protocolVersion !== WINDOWS_OWNED_PROCESS_MANIFEST_VERSION) {
+        return {
+            ok: false,
+            records: [],
+            updatedAt,
+            error: resultError('Unsupported Windows LiveDesk process-manifest version.')
+        };
+    }
+    if (!ownersMatch(parsed?.owner, exactOwner)) {
+        return {
+            ok: false,
+            records: [],
+            updatedAt,
+            error: resultError('Windows LiveDesk process manifest belongs to another launcher generation.')
+        };
+    }
+    if (!Number.isFinite(updatedAtMs)
+        || updatedAtMs > nowMs + MAX_FUTURE_CLOCK_SKEW_MS
+        || nowMs - updatedAtMs > maximumAge) {
+        return {
+            ok: false,
+            records: [],
+            updatedAt,
+            error: resultError('Windows LiveDesk process manifest is stale or has an invalid timestamp.')
+        };
+    }
+    const exactRecords = normalizeRecords(parsed?.records);
+    if (!exactRecords) {
+        return {
+            ok: false,
+            records: [],
+            updatedAt,
+            error: resultError('Windows LiveDesk process manifest contains an invalid process identity.')
+        };
+    }
+    return { ok: true, records: exactRecords, updatedAt };
+}