@livedesk/client 0.1.239 → 0.1.241

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

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