@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/protocol/management.js

@@ -1,4 +1,5 @@
 import { decodeDesktopManagementFrame, parseDesktopJson, DesktopProtocolError } from '../desktopControl/protocol.js';
+import { parseAutomationJson } from '../desktopControl/automationJson.js';
 import { decodeChannelFrame, hasOptional, hasRequired, isBoolean, isBridgeInfoArray, isNullableString, isNumber, isObject, isString, } from './common.js';
 export const MANAGEMENT_WIRE_MIN_VERSION = 1;
 /** Adds the `DRAINING` value to ClientUpdatePhase. */
@@ -14,7 +15,8 @@ export const MANAGEMENT_WIRE_GPU_VERSION = 7;
 /** Adds `keepers` to heartbeats and the `keeper_control` / `keeper_control_result` pair (spec §8.1, Task 26). */
 export const MANAGEMENT_WIRE_KEEPERS_VERSION = 8;
 export const MANAGEMENT_WIRE_DESKTOP_VERSION = 9;
-export const MANAGEMENT_WIRE_VERSION = MANAGEMENT_WIRE_DESKTOP_VERSION;
+export const MANAGEMENT_WIRE_DEVICE_OWNERSHIP_VERSION = 10;
+export const MANAGEMENT_WIRE_VERSION = MANAGEMENT_WIRE_DEVICE_OWNERSHIP_VERSION;
 /** Bounds of one heartbeat's `keepers` (spec §8.1). */
 export const KEEPER_STATUS_MAX_ITEMS = 32;
 export const KEEPER_LABEL_MAX_CHARS = 64;
@@ -59,6 +61,7 @@ function isUpdateStatus(value) {
         && hasOptional(value, {
             commandId: isString, version: isString, releaseSha512: isString, force: isBoolean,
             activeShellTasks: isNumber, activeAgentTasks: isNumber, error: isString,
+            remoteForcePolicy: policy => policy === 'drain-only',
         });
 }
 function isOsInfo(value) {
@@ -130,7 +133,7 @@ function isManagementFrame(value) {
         }) && hasOptional(value, { bridges: isBridgeInfoArray });
         case 'management_ready': return hasRequired(value, {
             serverNonce: isString, generation: isString, protocols: isSelectedProtocolMap,
-        }) && hasOptional(value, { release: isNullable(isRelease) });
+        }) && hasOptional(value, { release: isNullable(isRelease), ownerUserId: isString });
         case 'heartbeat': return hasRequired(value, {
             seq: isNumber, sentAtEpochMs: isNumber, clientVersion: isString,
             channels: (channels) => isObject(channels) && Object.entries(channels).every(([kind, state]) => CHANNEL_KINDS.has(kind) && isChannelState(state)),
@@ -148,7 +151,7 @@ function isManagementFrame(value) {
         case 'heartbeat_ack': return hasRequired(value, { seq: isNumber });
         case 'channel_ticket_request': return hasRequired(value, { channel: isChannelKind });
         case 'channel_ticket': return hasRequired(value, { channel: isChannelKind, ticket: isString, expiresAtEpochMs: isNumber });
-        case 'client_update': return hasRequired(value, { commandId: isString, release: isRelease, force: isBoolean });
+        case 'client_update': return hasRequired(value, { commandId: isString, release: isRelease, force: isBoolean }) && hasOptional(value, { remoteForcePolicy: value => value === 'drain-only' });
         case 'client_update_status': return hasRequired(value, { status: isUpdateStatus });
         case 'external_agents_scan': return hasRequired(value, { commandId: isString });
         case 'external_agents_scan_result': return hasRequired(value, { commandId: isString, bridges: isBridgeInfoArray });
@@ -162,6 +165,8 @@ function isManagementFrame(value) {
 }
 export function encodeManagementFrame(frame) {
     const text = JSON.stringify(frame);
+    if (frame.t === 'desktop_automation_prepare')
+        decodeAutomationPrepare(text);
     if (isDesktopManagementType(frame.t))
         decodeDesktopManagementFrame(text);
     return text;
@@ -170,12 +175,22 @@ export function decodeManagementFrame(source) {
     const text = typeof source === 'string' ? source : new TextDecoder('utf-8', { fatal: true }).decode(source);
     // Desktop extensions get the strict lexical/shape guard before any lossy object parsing.
     const parsed = JSON.parse(text);
+    if (isObject(parsed) && parsed.t === 'desktop_automation_prepare')
+        return decodeAutomationPrepare(text);
     if (isObject(parsed) && isDesktopManagementType(parsed.t))
         return decodeDesktopManagementFrame(text);
     if (isObject(parsed) && parsed.t === 'heartbeat' && Object.hasOwn(parsed, 'capabilitiesRevision'))
         validateHeartbeatRevision(text);
     return decodeChannelFrame(text, DISCRIMINATORS, isManagementFrame);
 }
+function decodeAutomationPrepare(text) {
+    const value = parseAutomationJson(text, 49152).value;
+    if (Object.keys(value).sort().join(',') !== 'automationProtocol,binding,deviceGeneration,grant,t' || value.automationProtocol !== 1 ||
+        typeof value.grant !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(value.grant) ||
+        value.binding?.route?.deviceGeneration !== value.deviceGeneration || !value.binding?.native || !value.binding?.preparation || typeof value.binding.executionId !== 'string')
+        throw new DesktopProtocolError('Invalid automation preparation');
+    return value;
+}
 /** Select only the new root field. JSON.parse already validates syntax; legacy nesting, size,
  * unknown fields and duplicate legacy keys keep their established decoder behavior. */
 function validateHeartbeatRevision(text) {
@@ -215,7 +230,7 @@ function validateHeartbeatRevision(text) {
 }
 function isDesktopManagementType(type) {
     return typeof type === 'string' && ['desktop_background', 'desktop_lobby', 'desktop_lobby_result', 'workstation_capabilities', 'workstation_capabilities_request', 'desktop_prepare',
-        'desktop_prepare_result', 'desktop_cancel', 'desktop_session_state'].includes(type);
+        'desktop_prepare_result', 'desktop_cancel', 'desktop_isolation_result', 'desktop_session_state', 'desktop_ownership', 'desktop_ownership_result'].includes(type);
 }
 export class ManagementFrameAdmission {
     isCurrent;
@@ -236,6 +251,10 @@ export class ManagementFrameAdmission {
         }
         if (frame.t === 'heartbeat' && frame.capabilitiesRevision !== undefined)
             return false;
+        if (frame.t === 'desktop_ownership')
+            return !!this.ready && this.ready.protocols.MANAGEMENT >= 10 && frame.deviceGeneration === this.ready.generation;
+        if (frame.t === 'desktop_automation_prepare')
+            return !!this.ready && this.ready.protocols.MANAGEMENT >= MANAGEMENT_WIRE_DESKTOP_VERSION && frame.deviceGeneration === this.ready.generation;
         if (!isDesktopManagementType(frame.t))
             return true;
         if (!this.ready || this.ready.protocols.MANAGEMENT < MANAGEMENT_WIRE_DESKTOP_VERSION)

package/dist/workstation/rd/artifact.js

@@ -7,6 +7,7 @@ import { deploymentDownloadURL } from '../control/serverIdentity.js';
 import { downloadVerified } from '../update/artifact.js';
 import { privateDirectory } from '../keepers/kit/paths.js';
 const legacyRdFiles = ['bin/axom-desktop-keeper', 'bin/axom-input-guardian', 'bin/axom-quic', 'xorg.conf'];
+export const RD_DEVICE_HOST_PLATFORM = 'linux-x64-debian-13-device-host';
 export const rdFiles = [...legacyRdFiles, 'bin/axom-display', 'bin/axom-desktop-session'];
 const sha256 = z.string().regex(/^[a-f0-9]{64}$/);
 export const rdArtifactSchema = z.object({ version: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,127}$/),
@@ -16,15 +17,15 @@ export const rdArtifactSchema = z.object({ version: z.string().regex(/^[a-zA-Z0-
     files: z.record(z.string(), sha256),
 }).refine(artifact => {
     const files = artifact.ipcVersion === 1 ? legacyRdFiles : rdFiles;
-    const licensed = artifact.ipcVersion === 2 && 'opus-LICENSE' in artifact.files;
-    return Object.keys(artifact.files).length === files.length + (licensed ? 1 : 0) && files.every(file => file in artifact.files);
+    const licenses = artifact.ipcVersion === 2 ? ['opus-LICENSE', 'webp-LICENSE'].filter(file => file in artifact.files) : [];
+    return Object.keys(artifact.files).length === files.length + licenses.length && files.every(file => file in artifact.files);
 }, 'RD artifact files do not match its runtime version');
 export function rdPlatform(osRelease, architecture) {
     const values = Object.fromEntries(osRelease.split('\n').map(line => /^([A-Z_]+)=["']?([^"']*)["']?$/.exec(line)).filter(Boolean).map(match => [match[1], match[2]]));
     if (values.ID !== 'debian' || values.VERSION_ID !== '13' || architecture !== 'x64') {
         throw new Error('Remote desktop currently supports Debian 13 amd64; this distribution/architecture has no qualified RD package');
     }
-    return 'linux-x64-debian-13';
+    return RD_DEVICE_HOST_PLATFORM;
 }
 export function unpackRd(bytes, artifact) {
     const archive = gunzipSync(bytes, { maxOutputLength: artifact.unpackedSize + 65536 });

package/dist/workstation/rd/control.js

@@ -38,16 +38,14 @@ export async function configureRd(directory, options) {
         });
         const server = normalizeWorkstationServer(options.server ?? registered?.server ?? resolveServer(await loadConfig()));
         if (options.disableRd) {
-            await writeRdState(directory, previous ? { ...previous, enabled: false } : { schemaVersion: 1, enabled: false, server, session: 'auto' });
+            await writeRdState(directory, previous ? { ...previous, enabled: false } : { schemaVersion: 2, enabled: false, artifactSource: server, session: 'auto' });
             return;
         }
-        if (registered && normalizeWorkstationServer(registered.server) !== server)
-            throw new Error('This workstation is already registered to another server; change its registration before enabling RD');
         const { session, display } = rdSessionSelection(previous, options);
         const platform = rdPlatform(await fs.readFile('/etc/os-release', 'utf8'), process.arch);
         const installed = await installRd(directory, server, platform);
         await ensureDependencies(installed.directory, session, display, installed.artifact);
-        await writeRdState(directory, { schemaVersion: 1, enabled: true, server, session, ...(display ? { display } : {}),
+        await writeRdState(directory, { schemaVersion: 2, enabled: true, artifactSource: server, session, ...(display ? { display } : {}),
             installation: installed.directory, artifact: installed.artifact });
         console.log(`Remote desktop enabled (${session}, ${installed.artifact.version}); capture starts only when an authorized viewer connects`);
     });
@@ -114,6 +112,6 @@ export async function rdStatus(directory) {
         if (error.code !== 'ENOENT')
             throw error;
     }
-    return { enabled: state.enabled, installed: state.installation !== undefined, version: state.artifact?.version, selection: state.session, server: state.server,
+    return { enabled: state.enabled, installed: state.installation !== undefined, version: state.artifact?.version, selection: state.session, artifactSource: state.artifactSource,
         ...(state.display ? { requestedDisplay: state.display } : {}), ...(state.enabled ? { observed, update } : {}) };
 }

package/dist/workstation/rd/host.js

@@ -0,0 +1,213 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { randomBytes, createHash, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createConnection } from 'node:net';
+import { NativeDeviceAdmission } from '../desktopControl/nativeDeviceAdmission.js';
+import { bounded } from '../desktopControl/helperProcess.js';
+import { privateDirectory } from '../keepers/kit/paths.js';
+import { readDeviceHostDescriptor, deviceHostGrantSchema } from '../desktopControl/hostGrant.js';
+export class LinuxDeviceHost {
+    directory;
+    cleanupDescriptor;
+    static pending = new Map();
+    child;
+    owner;
+    exit;
+    stopCommandId = randomUUID();
+    admission;
+    grant;
+    bootstrapGrant;
+    enableAttempted = false;
+    published = false;
+    failed = false;
+    exitObserved = false;
+    constructor(directory, cleanupDescriptor) {
+        this.directory = directory;
+        this.cleanupDescriptor = cleanupDescriptor;
+    }
+    static async recoverPending(root) {
+        const host = this.pending.get(root);
+        if (!host)
+            return;
+        if (host.failed && !host.enableAttempted && !host.published && host.exitObserved) {
+            host.owner?.destroy();
+            await fs.rm(path.join(host.directory, 'launch.json'), { force: true });
+            await fs.rm(path.join(host.directory, 'host.sock'), { force: true });
+            await fs.rmdir(host.directory).catch(error => { if (error.code !== 'ENOENT')
+                throw error; });
+            this.pending.delete(root);
+            return;
+        }
+        if (!host.admission) {
+            const original = host.bootstrapGrant;
+            if (!original)
+                throw Error('native_host_launch_unconfirmed');
+            host.admission = await NativeDeviceAdmission.connect(original);
+            host.grant = { ...original, hostGeneration: host.admission.hostLifetimeId };
+        }
+        return host;
+    }
+    static async launch(root, executable, environment) {
+        if (this.pending.has(root))
+            throw Error('original_native_host_unconfirmed');
+        const cleanup = path.join(root, 'desktop-cleanup');
+        await privateDirectory(cleanup);
+        const directory = await fs.mkdtemp('/tmp/axom-device-host-');
+        await fs.chmod(directory, 0o700);
+        const host = new LinuxDeviceHost(directory, path.join(cleanup, randomBytes(16).toString('hex') + '.json'));
+        const binary = await fs.realpath(executable), sha256 = createHash('sha256').update(await fs.readFile(binary)).digest('hex');
+        const endpoint = { socket: path.join(directory, 'host.sock'), token: randomBytes(32).toString('hex') };
+        host.bootstrapGrant = { schemaVersion: 2, executable: binary, sha256, ...endpoint };
+        const bootstrap = path.join(directory, 'launch.json');
+        await fs.writeFile(bootstrap, JSON.stringify({ ...endpoint, parentPid: process.pid, cleanupDescriptor: host.cleanupDescriptor, executable: binary, sha256 }), { flag: 'wx', mode: 0o600 });
+        this.pending.set(root, host);
+        const child = spawn(binary, ['--device-host', bootstrap], { env: { ...environment, AXOM_ACCESS_TOKEN: undefined }, stdio: 'ignore' });
+        host.child = child;
+        host.exit = new Promise((resolve, reject) => { child.once('exit', () => { host.exitObserved = true; resolve(); }); child.once('error', reject); });
+        void host.exit.catch(() => { });
+        try {
+            const deadline = Date.now() + 5000;
+            while (Date.now() < deadline) {
+                if (child.exitCode !== null)
+                    throw new Error('native_host_launch_failed');
+                try {
+                    await fs.lstat(endpoint.socket);
+                    break;
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+                await new Promise(resolve => setTimeout(resolve, 10));
+            }
+            const owner = createConnection(endpoint.socket);
+            host.owner = owner;
+            await bounded(new Promise((resolve, reject) => {
+                owner.once('error', reject);
+                owner.once('connect', () => owner.write(endpoint.token));
+                owner.once('data', bytes => { if (bytes.length !== 1 || bytes[0] !== 1) {
+                    reject(new Error('native_host_authentication_failed'));
+                    return;
+                } owner.write('owner\n'); resolve(); });
+                owner.once('end', () => reject(new Error('native_host_owner_closed')));
+            }), 5000);
+            host.admission = await NativeDeviceAdmission.connect(endpoint);
+            host.grant = { schemaVersion: 2, hostGeneration: host.admission.hostLifetimeId, executable: binary, sha256, ...endpoint };
+            host.published = true;
+            await host.persistOriginal();
+            await new Promise((resolve, reject) => {
+                const peer = createConnection(endpoint.socket);
+                const timer = setTimeout(() => { peer.destroy(); reject(new Error('native_host_enable_unconfirmed')); }, 5000);
+                let authenticated = false, bytes = Buffer.alloc(0);
+                peer.once('connect', () => peer.write(endpoint.token));
+                peer.once('error', error => { clearTimeout(timer); reject(error); });
+                peer.on('data', chunk => { bytes = Buffer.concat([bytes, chunk]); if (!authenticated) {
+                    if (bytes[0] !== 1) {
+                        clearTimeout(timer);
+                        peer.destroy();
+                        reject(new Error('native_host_authentication_failed'));
+                        return;
+                    }
+                    authenticated = true;
+                    bytes = bytes.subarray(1);
+                    host.enableAttempted = true;
+                    peer.write('enable\n');
+                } if (bytes.includes(10)) {
+                    clearTimeout(timer);
+                    peer.destroy();
+                    try {
+                        if (JSON.stringify(JSON.parse(bytes.subarray(0, bytes.indexOf(10)).toString())) !== '{}')
+                            throw Error();
+                        resolve();
+                    }
+                    catch {
+                        reject(new Error('native_host_enable_unconfirmed'));
+                    }
+                } });
+            });
+            this.pending.delete(root);
+            return host;
+        }
+        catch (error) {
+            host.failed = true;
+            host.owner?.destroy();
+            throw error;
+        }
+    }
+    async persistOriginal() {
+        const expected = deviceHostGrantSchema.parse(this.grant);
+        try {
+            if (JSON.stringify(await readDeviceHostDescriptor(this.cleanupDescriptor)) !== JSON.stringify(expected))
+                throw Error('original_native_host_unconfirmed');
+            return;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const staging = this.cleanupDescriptor + '.writing-' + randomUUID();
+        const file = await fs.open(staging, 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(expected));
+            await file.sync();
+            await file.close();
+            try {
+                await fs.link(staging, this.cleanupDescriptor);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+            if (JSON.stringify(await readDeviceHostDescriptor(this.cleanupDescriptor)) !== JSON.stringify(expected))
+                throw Error('original_native_host_unconfirmed');
+        }
+        finally {
+            await file.close();
+            await fs.unlink(staging);
+        }
+    }
+    async stopOriginal() {
+        let failure;
+        try {
+            await this.persistOriginal();
+        }
+        catch (error) {
+            failure = error;
+        }
+        try {
+            await this.admission.stopHost(this.stopCommandId);
+        }
+        catch (error) {
+            failure ??= error;
+        }
+        if (failure)
+            throw failure;
+    }
+    async finalizeOriginal() {
+        this.owner?.destroy();
+        if (this.exit)
+            try {
+                await bounded(this.exit, 5000);
+            }
+            catch (error) {
+                this.child?.kill('SIGTERM');
+                await bounded(this.exit, 5000);
+            }
+        try {
+            const descriptor = await readDeviceHostDescriptor(this.cleanupDescriptor);
+            if (descriptor.hostGeneration === this.grant.hostGeneration && descriptor.token === this.grant.token && descriptor.socket === this.grant.socket)
+                await fs.unlink(this.cleanupDescriptor);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await fs.rm(path.join(this.directory, 'launch.json'), { force: true });
+        await fs.rmdir(this.directory).catch(error => { if (error.code !== 'ENOENT')
+            throw error; });
+        for (const [root, original] of LinuxDeviceHost.pending)
+            if (original === this)
+                LinuxDeviceHost.pending.delete(root);
+    }
+}

package/dist/workstation/rd/migrationReadiness.js

@@ -0,0 +1,46 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { z } from 'zod';
+import { installRd, rdPlatform, verifyRdInstallation } from './artifact.js';
+import { readRdState } from './state.js';
+import { withPrivateLock } from '../control/locks.js';
+const execute = promisify(execFile);
+const capabilities = z.strictObject({ deviceAdmissionProtocol: z.literal(1), deviceHost: z.literal(true) });
+/** Stage only. The caller must retain the legacy physical fence: qualification is not retirement
+ * of predecessor capture/input authority, and must never activate this state on its own. */
+export async function prepareLegacyRdReadiness(directory, options = {}) {
+    return withPrivateLock(path.join(directory, 'rd', 'install'), async () => {
+        const previous = await readRdState(directory);
+        if (!previous?.enabled)
+            return { kind: 'not-enabled' };
+        const qualify = async (installation) => {
+            await verifyRdInstallation(installation.directory, installation.artifact);
+            const result = await (options.execute ?? execute)(path.join(installation.directory, 'bin/axom-desktop-keeper'), ['--device-capabilities'], {
+                timeout: 5000, maxBuffer: 8192,
+                env: { ...process.env, AXOM_ACCESS_TOKEN: undefined, AXOM_DEVICE_SCOPE: undefined, AXOM_DEVICE_CONTEXT: undefined,
+                    AXOM_KEEPER_SOCKET: undefined, AXOM_KEEPER_TOKEN: undefined },
+            });
+            capabilities.parse(JSON.parse(result.stdout));
+        };
+        try {
+            await qualify({ directory: previous.installation, artifact: previous.artifact });
+            return { kind: 'ready', state: previous };
+        }
+        catch {
+            // A legacy --self-test or IPC version says nothing about device admission support.
+        }
+        try {
+            const platform = options.platform ?? rdPlatform(await fs.readFile('/etc/os-release', 'utf8'), process.arch);
+            const candidate = await (options.install ?? installRd)(directory, previous.artifactSource, platform);
+            await qualify(candidate);
+            if (JSON.stringify(await readRdState(directory)) !== JSON.stringify(previous))
+                throw Error('Remote desktop selection changed during migration staging');
+            return { kind: 'staged', state: { ...previous, installation: candidate.directory, artifact: candidate.artifact } };
+        }
+        catch (error) {
+            return { kind: 'unavailable', reason: `Remote desktop requires a qualified device host: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    });
+}

package/dist/workstation/rd/provider.js

@@ -7,12 +7,12 @@ import { NativeProvider } from '../desktopControl/nativeProvider.js';
 import { HelperProcess, NativeCommandError } from '../desktopControl/helperProcess.js';
 import { desktopCapabilitiesSchema } from '../desktopControl/protocol.js';
 import { captureTargetLabel } from '../desktopControl/captureTargetLabel.js';
-import { normalizeWorkstationServer } from '../control/serverIdentity.js';
 import { privateDirectory } from '../keepers/kit/paths.js';
 import { verifyRdInstallation } from './artifact.js';
 import { readRdState } from './state.js';
 import { chooseSession, discoverSessions, ensureManagedSession, sessionAlive } from './sessions.js';
 import { desktopDisplayControl, parseXrandr } from './display.js';
+import { LinuxDeviceHost } from './host.js';
 const execute = promisify(execFile);
 const sourceAxis = z.number().int().min(2).max(4096);
 const geometrySchema = z.object({ width: sourceAxis, height: sourceAxis, audio: z.boolean().optional() });
@@ -21,6 +21,33 @@ export class LinuxDesktopProvider {
     directory;
     server;
     legacy;
+    host;
+    get deviceAdmission() { return this.host?.admission; }
+    static async connect(directory) {
+        if (!(await readRdState(directory))?.enabled)
+            return;
+        const provider = new LinuxDesktopProvider(directory, '');
+        await provider.initialize();
+        if (!provider.host)
+            throw new NativeCommandError('unavailable');
+        return provider;
+    }
+    async stopOriginal() { if (this.host)
+        await this.host.stopOriginal(); }
+    async finalizeOriginal() { if (this.host)
+        await this.host.finalizeOriginal(); }
+    async retirementRequired() {
+        const current = await readRdState(this.directory);
+        return !current?.enabled || !this.state || current.artifact.sha512 !== this.state.artifact.sha512 || current.session !== this.state.session || current.display !== this.state.display || !this.session || !await sessionAlive(this.session);
+    }
+    async prepareAutomation(binding) {
+        await this.initialize();
+        if (!this.usingLegacy)
+            await this.validate();
+        if (!this.provider?.prepareAutomation)
+            throw new NativeCommandError('unsupported_automation_protocol');
+        return this.provider.prepareAutomation(binding);
+    }
     session;
     provider;
     state;
@@ -47,7 +74,7 @@ export class LinuxDesktopProvider {
         const current = await readRdState(this.directory);
         if (!current?.enabled || !this.state || current.artifact.sha512 !== this.state.artifact.sha512 ||
             current.session !== this.state.session || current.display !== this.state.display ||
-            normalizeWorkstationServer(current.server) !== normalizeWorkstationServer(this.server) || !session || this.session !== session || !await sessionAlive(session)) {
+            !session || this.session !== session || !await sessionAlive(session)) {
             throw new NativeCommandError('unavailable');
         }
     }
@@ -75,8 +102,11 @@ export class LinuxDesktopProvider {
             this.state = undefined;
             return;
         }
-        if (normalizeWorkstationServer(state.server) !== normalizeWorkstationServer(this.server))
-            throw new Error('RD belongs to a different workstation server');
+        if (this.host) {
+            if (await this.retirementRequired())
+                throw new NativeCommandError('unavailable');
+            return;
+        }
         if (this.provider && this.state?.artifact.sha512 === state.artifact.sha512 && this.state.session === state.session && this.state.display === state.display && this.session && await sessionAlive(this.session))
             return;
         this.provider = undefined;
@@ -91,11 +121,15 @@ export class LinuxDesktopProvider {
             session.environment.AXOM_DESKTOP_RUNTIME_DIR : path.join(runtimeRoot, session.identity);
         await privateDirectory(this.runtime);
         const executable = path.join(state.installation, 'bin/axom-desktop-keeper');
+        const originalHost = await LinuxDeviceHost.launch(this.directory, executable, this.environment());
+        this.host = originalHost;
+        const originalEnvironment = { ...this.environment(), AXOM_KEEPER_SOCKET: originalHost.grant.socket, AXOM_KEEPER_TOKEN: originalHost.grant.token };
         this.provider = new NativeProvider({ helperPath: executable, runtimeDir: this.runtime,
-            environment: this.environment(), enumerate: () => this.capabilities(), validateSession: () => this.validate(session),
+            deviceAdmission: originalHost.admission, environment: originalEnvironment, enumerate: () => this.capabilities(), validateSession: () => this.validate(session),
             sessionHelperFactory: async (binding) => {
                 await this.validate(session);
-                const helper = await HelperProcess.launch(executable, { ...this.environment(), AXOM_KEEPER_TARGET: binding.displayId });
+                const helper = await HelperProcess.launch(executable, { ...originalEnvironment, AXOM_KEEPER_TARGET: binding.displayId,
+                    AXOM_DEVICE_CONTEXT: originalHost.admission.context(binding.deviceGrant?.registrationId ?? '', binding.deviceGeneration, binding.sessionId, binding.deviceGrant) });
                 return helper;
             } });
         process.env.AXOM_QUIC_BINARY = path.join(state.installation, 'bin/axom-quic');
@@ -197,19 +231,19 @@ export class LinuxDesktopProvider {
             throw error;
         }
     }
-    async prepare(selection, binding) {
+    async prepare(selection, binding, current) {
         await this.initialize();
         if (!this.provider)
             throw new NativeCommandError('unavailable');
-        return this.provider.prepare(selection, binding);
+        return this.provider.prepare(selection, binding, current);
     }
-    async wallpaper(targetId) {
+    async wallpaper(targetId, pixels = { width: 1920, height: 1080 }) {
         await this.initialize();
         if (!this.usingLegacy)
             await this.validate();
         if (!this.provider)
             throw new NativeCommandError('unavailable');
-        return this.provider.wallpaper(targetId);
+        return this.provider.wallpaper(targetId, pixels);
     }
     async recoverDisplay(binding, reservation) {
         await this.initialize();

package/dist/workstation/rd/state.js

@@ -4,13 +4,25 @@ import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { rdArtifactSchema } from './artifact.js';
 import { privateDirectory } from '../keepers/kit/paths.js';
-const selection = { schemaVersion: z.literal(1), server: z.string().url(),
+const selection = { schemaVersion: z.literal(2), artifactSource: z.string().url(),
     session: z.enum(['auto', 'existing', 'virtual']), display: z.string().regex(/^:\d+(?:\.\d+)?$/).optional(),
 };
-export const rdStateSchema = z.discriminatedUnion('enabled', [
+const currentRdStateSchema = z.discriminatedUnion('enabled', [
     z.strictObject({ ...selection, enabled: z.literal(true), installation: z.string().startsWith('/'), artifact: rdArtifactSchema }),
     z.strictObject({ ...selection, enabled: z.literal(false), installation: z.string().startsWith('/').optional(), artifact: rdArtifactSchema.optional() }),
 ]);
+const legacySelection = { schemaVersion: z.literal(1), server: z.string().url(), session: selection.session, display: selection.display };
+const legacyRdStateSchema = z.discriminatedUnion('enabled', [
+    z.strictObject({ ...legacySelection, enabled: z.literal(true), installation: z.string().startsWith('/'), artifact: rdArtifactSchema }),
+    z.strictObject({ ...legacySelection, enabled: z.literal(false), installation: z.string().startsWith('/').optional(), artifact: rdArtifactSchema.optional() }),
+]);
+export const rdStateSchema = z.preprocess(value => {
+    const legacy = legacyRdStateSchema.safeParse(value);
+    if (!legacy.success)
+        return value;
+    const { server, ...state } = legacy.data;
+    return { ...state, schemaVersion: 2, artifactSource: server };
+}, currentRdStateSchema);
 export async function readRdState(directory) {
     let file;
     try {

package/dist/workstation/rd/update.js

@@ -3,10 +3,9 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { installRd, rdArtifactSchema, rdPlatform, verifyRdInstallation } from './artifact.js';
+import { installRd, rdArtifactSchema, rdPlatform, verifyRdInstallation, RD_DEVICE_HOST_PLATFORM } from './artifact.js';
 import { readRdState, writeRdState } from './state.js';
 import { assertLockOwnership, withPrivateLock } from '../control/locks.js';
-import { normalizeWorkstationServer } from '../control/serverIdentity.js';
 import { privateDirectory } from '../keepers/kit/paths.js';
 import { z } from 'zod';
 import { CLIENT_VERSION } from '../version.js';
@@ -34,9 +33,9 @@ async function adoptBundle(directory, server, options) {
     if (!bundle)
         return;
     const catalog = z.object({ schemaVersion: z.literal(1), artifacts: z.record(z.string(), rdArtifactSchema) }).parse(JSON.parse(await fs.readFile(bundle.manifest, 'utf8')));
-    const artifact = catalog.artifacts['linux-x64-debian-13'];
+    const artifact = catalog.artifacts[RD_DEVICE_HOST_PLATFORM];
     if (!artifact || artifact.ipcVersion !== 2)
-        throw new Error('Bundled RD requires the IPC 2 runtime');
+        throw new Error('Bundled RD requires the device-host platform and IPC 2 runtime');
     if (!bundle.display || !/^:\d+(?:\.\d+)?$/.test(bundle.display))
         throw new Error('Bundled RD requires a local X11 DISPLAY');
     if (!path.isAbsolute(bundle.root))
@@ -44,7 +43,7 @@ async function adoptBundle(directory, server, options) {
     await verifyRdInstallation(bundle.root, artifact);
     await selfTest(bundle.root, artifact, options);
     assertLockOwnership();
-    await writeRdState(directory, { schemaVersion: 1, enabled: true, server, session: 'existing', display: bundle.display, installation: bundle.root, artifact });
+    await writeRdState(directory, { schemaVersion: 2, enabled: true, artifactSource: server, session: 'existing', display: bundle.display, installation: bundle.root, artifact });
 }
 function requireSupportedIpc(artifact) {
     if (artifact.ipcVersion !== 1 && artifact.ipcVersion !== 2)
@@ -73,8 +72,6 @@ export async function synchronizeRd(directory, server, options = {}) {
             if (!previous?.enabled)
                 return;
             requireSupportedIpc(previous.artifact);
-            if (normalizeWorkstationServer(previous.server) !== normalizeWorkstationServer(server))
-                throw new Error('RD belongs to a different workstation server');
         }
         catch (error) {
             await writeStatus(directory, { state: 'blocked', reason: reason(error) });
@@ -95,7 +92,7 @@ export async function synchronizeRd(directory, server, options = {}) {
         let installed;
         try {
             const platform = options.platform ?? rdPlatform(await fs.readFile('/etc/os-release', 'utf8'), process.arch);
-            installed = await (options.install ?? installRd)(directory, server, platform, options.fetch ?? globalThis.fetch);
+            installed = await (options.install ?? installRd)(directory, previous.artifactSource, platform, options.fetch ?? globalThis.fetch);
             requireSupportedIpc(installed.artifact);
             await verifyRdInstallation(installed.directory, installed.artifact);
             await selfTest(installed.directory, installed.artifact, options);