@myagentroam/node 0.13.11 → 0.13.12

package/dist/connection/direct-transfer-service.js

@@ -2,6 +2,7 @@ import { createSocket } from 'node:dgram';
 import { isIP } from 'node:net';
 import { directDataControlFrameSchema, directNodeCommandSchema } from '@myagentroam/protocol';
 import { TerminalDirectService } from '../service/terminal-direct-service.js';
+import { DirectDesktopService } from '../remote-desktop/direct-desktop-service.js';
 import { IceUdpMuxListener as NativeIceUdpMuxListener } from 'node-datachannel';
 import { RTCPeerConnection } from 'node-datachannel/polyfill';
 const MAX_HOST_CANDIDATES = 32;
@@ -23,6 +24,7 @@ export class DirectTransferService {
     leaseGraceMs;
     leaseCheckMs;
     terminalDirect;
+    desktopDirect;
     disposed = false;
     static async create(options) {
         const range = options.udpPortRange?.() ?? { begin: 49_152, end: 49_215 };
@@ -62,6 +64,26 @@ export class DirectTransferService {
                     command.browserFingerprint === fingerprint(peer.remoteDescription?.sdp) &&
                     command.nodeFingerprint === fingerprint(peer.localDescription?.sdp));
             }, this.now);
+        if (options.desktop) {
+            this.desktopDirect = new DirectDesktopService({
+                ...options.desktop,
+                nodeGeneration: options.nodeGeneration,
+                peer: (command) => {
+                    const transport = this.transports.get(command.transportSessionId);
+                    const peer = transport?.peer;
+                    return peer &&
+                        transport.command.workbenchConnectionId === command.workbenchConnectionId &&
+                        transport.command.nodeGeneration === command.nodeGeneration &&
+                        command.nodeGeneration === options.nodeGeneration() &&
+                        peer.connectionState === 'connected' &&
+                        command.browserFingerprint === fingerprint(peer.remoteDescription?.sdp) &&
+                        command.nodeFingerprint === fingerprint(peer.localDescription?.sdp)
+                        ? peer
+                        : undefined;
+                },
+                ...(options.now ? { now: options.now } : {})
+            });
+        }
     }
     handle(value) {
         const parsed = directNodeCommandSchema.safeParse(value);
@@ -82,7 +104,24 @@ export class DirectTransferService {
     handleTerminal(value) {
         return this.terminalDirect?.handle(value, (id) => this.transports.get(id)?.peer) ?? false;
     }
+    handleDesktop(value) {
+        return this.desktopDirect?.handle(value) ?? false;
+    }
+    invalidateDesktop(code) {
+        this.desktopDirect?.invalidate(code);
+    }
+    /** Pause only Remote Desktop; the RTC transport remains owned by Direct Transfer. */
+    suspendDesktop(signal) {
+        return this.desktopDirect?.suspend(signal) ?? Promise.resolve();
+    }
+    canResumeDesktop() {
+        return this.desktopDirect?.canResume() ?? true;
+    }
+    resumeDesktop() {
+        return this.desktopDirect?.resume() ?? true;
+    }
     close(code = 'DIRECT_NODE_STOPPED') {
+        this.desktopDirect?.invalidate('DESKTOP_TRANSPORT_ERROR');
         this.terminalDirect?.close();
         for (const transfer of [...this.transfers.values()])
             void this.removeTransfer(transfer, code);
@@ -93,10 +132,17 @@ export class DirectTransferService {
         if (this.disposed)
             return;
         this.disposed = true;
+        // Preserve the shutdown reason before closing the shared RTC transport.
+        this.desktopDirect?.dispose();
         this.close();
         this.terminalDirect?.dispose();
         this.iceUdpMuxListener.stop();
     }
+    /** Stop transport admission immediately, then join Remote-owned native cleanup. */
+    shutdown(signal) {
+        this.dispose();
+        return this.desktopDirect?.shutdown(signal) ?? Promise.resolve();
+    }
     async dispatch(command) {
         if (command.type === 'direct.prepare') {
             if (command.purpose === 'TRANSPORT')
@@ -158,6 +204,7 @@ export class DirectTransferService {
             command,
             peer,
             sentCandidateKeys: new Set(),
+            pendingChannels: new Set(),
             lastLeaseAliveAt: this.now(),
             leaseExpiresAt: command.expiresAt,
             leaseTimer: undefined
@@ -283,12 +330,21 @@ export class DirectTransferService {
         });
     }
     attachPendingChannel(transport, channel) {
+        if (this.transports.get(transport.command.directSessionId) !== transport) {
+            channel.close();
+            return;
+        }
+        transport.pendingChannels.add(channel);
+        channel.addEventListener('close', () => transport.pendingChannels.delete(channel), {
+            once: true
+        });
         channel.binaryType = 'arraybuffer';
         let attached = false;
         channel.onmessage = (event) => {
             if (attached)
                 return;
             attached = true;
+            transport.pendingChannels.delete(channel);
             if (channel.label.startsWith('mar-terminal-')) {
                 this.terminalDirect?.open(transport.command.directSessionId, channel, event.data);
                 if (this.terminalDirect === undefined)
@@ -480,9 +536,13 @@ export class DirectTransferService {
             return;
         clearInterval(transport.leaseTimer);
         this.terminalDirect?.removeTransport(transport.command.directSessionId);
+        this.desktopDirect?.removeTransport(transport.command.directSessionId);
         for (const transfer of [...this.transfers.values()])
             if (transfer.command.transportSessionId === transport.command.directSessionId)
                 void this.removeTransfer(transfer, code ?? 'DIRECT_CONNECTION_FAILED');
+        for (const channel of transport.pendingChannels)
+            channel.close();
+        transport.pendingChannels.clear();
         transport.peer.close();
         if (code !== undefined)
             this.options.send('direct.error', {

package/dist/connection/endpoints.js

@@ -30,3 +30,19 @@ export function nodeTerminalConnectEndpoint(serverUrl) {
     endpoint.hash = '';
     return endpoint.toString();
 }
+export function nodeDesktopRelayEndpoint(serverUrl) {
+    const endpoint = new URL(serverUrl);
+    if (endpoint.username || endpoint.password)
+        throw new Error('SERVER_URL_INVALID');
+    if (endpoint.protocol === 'http:')
+        endpoint.protocol = 'ws:';
+    if (endpoint.protocol === 'https:')
+        endpoint.protocol = 'wss:';
+    if (endpoint.protocol !== 'ws:' && endpoint.protocol !== 'wss:') {
+        throw new Error('SERVER_URL_INVALID');
+    }
+    endpoint.pathname = `${endpoint.pathname.replace(/\/$/, '')}/api/node/desktop-relay`;
+    endpoint.search = '';
+    endpoint.hash = '';
+    return endpoint.toString();
+}

package/dist/connector.js

@@ -12,7 +12,8 @@ import { ModelUsageOutbox } from './service/model-usage-outbox.js';
 import { NodeModelUsageService } from './service/model-usage-service.js';
 import { dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { createEnvelope, directNodeCommandSchema } from '@myagentroam/protocol';
+import WebSocket from 'ws';
+import { createEnvelope, directNodeCommandSchema, remoteDesktopDescriptionSchema } from '@myagentroam/protocol';
 import { loadNodeConfig, computerUseRuntimeExecutable, directTransferUdpPortRange, nodeDataDirectory, nodeDatabasePath } from './config.js';
 import { NodeMetrics, nodeLog } from './operational.js';
 import { assertLocalSqlitePath } from './storage.js';
@@ -44,6 +45,16 @@ import { TerminalService } from './service/terminal-service.js';
 import { GitExecutionService } from './service/git-execution-service.js';
 import { GitOperationService } from './service/git-operation-service.js';
 import { DirectTransferService } from './connection/direct-transfer-service.js';
+import { nodeDesktopRelayEndpoint } from './connection/endpoints.js';
+import { RelayDesktopService } from './remote-desktop/relay-desktop-service.js';
+import { DesktopAttachmentRegistry } from './remote-desktop/desktop-service-core.js';
+import { X11RemoteDesktopRuntime } from './remote-desktop/x11-remote-desktop-runtime.js';
+import { WindowsRemoteDesktopRuntime } from './remote-desktop/windows-remote-desktop-runtime.js';
+import { windowsManagedDesktopBinaries } from './remote-desktop/windows-managed-binaries.js';
+import { MacosRemoteDesktopRuntime } from './remote-desktop/macos-remote-desktop-runtime.js';
+import { macosManagedDesktopBinaries } from './remote-desktop/macos-managed-binaries.js';
+import { linuxManagedDesktopBinaries } from './remote-desktop/linux-managed-binaries.js';
+import { RemoteDesktopError } from './remote-desktop/desktop-error.js';
 import { WorkspaceChangeService } from './workspace/workspace-change-service.js';
 import { WorkbenchEventService } from './service/workbench-event-service.js';
 import { RecentRunProjectionService } from './service/recent-run-projection-service.js';
@@ -166,6 +177,7 @@ export class NodeConnector {
     usageOutbox;
     modelUsage = new NodeModelUsageService(() => this.usageOutbox, () => this.config?.nodeId);
     nodeGeneration = crypto.randomUUID().replace(/-/g, '');
+    nodeGenerationRetired = false;
     controlChannel;
     controlMessages;
     scheduledRunAuthorization;
@@ -247,6 +259,7 @@ export class NodeConnector {
     marAgentClient;
     marAgentRunController;
     computerUseProvider;
+    desktopAttachmentRegistry = new DesktopAttachmentRegistry();
     computerUseEnablement;
     configMutations = new NodeConfigMutations();
     managedComputerUseRuntime;
@@ -314,6 +327,12 @@ export class NodeConnector {
     workspaceUploadService;
     invalidateWorkspaceFiles;
     directTransferService;
+    relayDesktopService;
+    desktopRuntime;
+    desktopDiscovery;
+    desktopStarting;
+    desktopDiscoveryAbort;
+    desktopDiscoveryEpoch = 0;
     attachmentTemporaryRoot() {
         if (this.config === undefined)
             throw new Error('NODE_CONFIG_UNAVAILABLE');
@@ -410,10 +429,12 @@ export class NodeConnector {
         const detect = options.capabilityDetector ?? detectCapabilitiesAsync;
         this.capabilityDetector = async () => {
             const capabilities = await detect();
-            return this.projectComputerUseCapability(await this.conversationHosting.project({
+            if (!this.stopped)
+                await this.initializeDesktopRuntime();
+            return this.projectRemoteDesktopCapability(this.projectComputerUseCapability(await this.conversationHosting.project({
                 ...capabilities,
                 metadata: upgradeMetadata(capabilities.metadata, this.upgradeCoordinator.snapshot(), options.supervisorUpgradeHandoff !== undefined)
-            }));
+            })));
         };
         this.reconnect = options.reconnect ?? true;
         const composedRunners = composeRunners(options);
@@ -1244,6 +1265,7 @@ export class NodeConnector {
                 this.promptCompletion?.disconnect();
                 this.usageOutbox?.disconnected();
                 this.directTransferService?.close('DIRECT_TRANSFER_CONTROL_UNAVAILABLE');
+                this.relayDesktopService?.invalidate('DESKTOP_TRANSPORT_ERROR');
                 this.runtimeCredentials.disconnected();
                 this.chatgptLogins.close();
                 this.scheduledRunAuthorization.disconnected();
@@ -1312,6 +1334,8 @@ export class NodeConnector {
             handleUpgradeCredentialResponse: (envelope) => this.upgradeCredentials.handle(envelope),
             handleDirectTransfer: (envelope) => this.handleDirectTransfer(envelope),
             handleTerminalDirect: (envelope) => this.handleTerminalDirect(envelope),
+            handleDesktopDirect: (envelope) => this.handleDesktopDirect(envelope),
+            handleDesktopRelay: (envelope) => this.handleDesktopRelay(envelope),
             runners: this.runners,
             deliverSessionChannelMessage: (envelope) => this.runnerChannelMessages.handle(envelope),
             completeUncontrolledCancellation: (runId) => {
@@ -1405,10 +1429,10 @@ export class NodeConnector {
             detectCapabilities: this.capabilityDetector,
             capabilitiesProvided: this.capabilitiesProvided,
             stopped: () => this.stopped,
-            setCapabilities: (capabilities) => (this.capabilities = {
+            setCapabilities: (capabilities) => (this.capabilities = this.projectRemoteDesktopCapability({
                 ...capabilities,
                 metadata: upgradeMetadata(capabilities.metadata, this.upgradeCoordinator.snapshot(), options.supervisorUpgradeHandoff !== undefined)
-            }),
+            })),
             control: this.controlChannel,
             terminal: this.terminalChannel,
             metrics: this.metrics,
@@ -1418,6 +1442,9 @@ export class NodeConnector {
                 await this.conversationHosting.initialize();
                 this.capabilities = await this.conversationHosting.project(this.capabilities);
                 this.computerUseEnablement.initialize();
+                if (!this.stopped)
+                    this.initializeDesktopRelay();
+                this.capabilities = this.projectRemoteDesktopCapability(this.capabilities);
             },
             onConnected: () => {
                 this.runtimeCredentials.connected();
@@ -1523,6 +1550,18 @@ export class NodeConnector {
             service: this.agentNetworkService,
             observations: this.agentNetworkObservations
         }));
+        this.operationRouter.register('desktop.describe', async () => {
+            const runtime = this.desktopRuntime;
+            if (!runtime)
+                throw new RemoteDesktopError('DESKTOP_UNAVAILABLE');
+            if (runtime instanceof WindowsRemoteDesktopRuntime ||
+                runtime instanceof MacosRemoteDesktopRuntime)
+                await runtime.refresh(AbortSignal.timeout(10_000));
+            const description = remoteDesktopDescriptionSchema.safeParse(runtime.describe());
+            if (!description.success)
+                throw new RemoteDesktopError('DESKTOP_TOPOLOGY_UNAVAILABLE');
+            return description.data;
+        });
         this.operationRouter.registerAll(this.promptCompletion.operations());
         for (const operation of CONVERSATION_TEMPLATE_OPERATIONS)
             this.operationRouter.register(operation, (data) => {
@@ -1642,15 +1681,62 @@ export class NodeConnector {
         });
     }
     projectComputerUseCapability(capabilities) {
-        return {
+        return this.projectRemoteDesktopCapability({
             ...capabilities,
             computerUse: this.computerUseEnablement.capability()
+        });
+    }
+    projectRemoteDesktopCapability(capabilities) {
+        try {
+            if (this.desktopRuntime && (this.directTransferService || this.relayDesktopService)) {
+                this.desktopRuntime.describe();
+                const transports = [];
+                if (this.directTransferService)
+                    transports.push('DIRECT');
+                if (this.relayDesktopService)
+                    transports.push('RELAY');
+                return {
+                    ...capabilities,
+                    remoteDesktop: {
+                        apiVersion: 1,
+                        available: true,
+                        nodeGeneration: this.nodeGeneration,
+                        backend: this.desktopRuntime instanceof WindowsRemoteDesktopRuntime
+                            ? 'ULTRAVNC'
+                            : this.desktopRuntime instanceof MacosRemoteDesktopRuntime
+                                ? 'MACVNC'
+                                : 'TIGERVNC_X0',
+                        supportsView: true,
+                        supportsControl: true,
+                        supportsMultiDisplay: !(this.desktopRuntime instanceof MacosRemoteDesktopRuntime),
+                        supportsUnicodePaste: !(this.desktopRuntime instanceof MacosRemoteDesktopRuntime),
+                        transports
+                    }
+                };
+            }
+        }
+        catch {
+            // A temporarily unavailable topology is not a usable desktop.
+        }
+        return {
+            ...capabilities,
+            remoteDesktop: {
+                apiVersion: 1,
+                available: false,
+                nodeGeneration: this.nodeGeneration,
+                reasonCode: 'DESKTOP_UNAVAILABLE'
+            }
         };
     }
     start() {
         return this.lifecycle.start();
     }
     async startResources() {
+        if (this.nodeGenerationRetired) {
+            this.nodeGeneration = crypto.randomUUID().replace(/-/g, '');
+            this.nodeGenerationRetired = false;
+        }
+        this.capabilities = this.projectRemoteDesktopCapability(this.capabilities);
         this.workspaceSessionService.resume();
         this.continuousRunCoordinator.resumeScheduling();
         this.sessionMessageService.setAccepting(true);
@@ -1676,16 +1762,132 @@ export class NodeConnector {
         await this.conversationHosting.initialize();
         this.capabilities = await this.conversationHosting.project(this.capabilities);
         this.computerUseEnablement.initialize();
+        await this.initializeDesktopRuntime();
         this.directTransferService ??= await this.createDirectTransferService();
+        this.initializeDesktopRelay();
+        this.capabilities = this.projectRemoteDesktopCapability(this.capabilities);
         await this.terminalManager.warmup();
         this.connectionLifecycle.start();
         this.controlChannel.connect();
     }
+    /** Discover the current process's existing GUI using only packaged native resources. */
+    initializeDesktopRuntime() {
+        if (this.desktopDiscovery)
+            return this.desktopDiscovery;
+        const epoch = this.desktopDiscoveryEpoch;
+        const cancel = new AbortController();
+        this.desktopDiscoveryAbort = cancel;
+        const discovery = this.discoverDesktopRuntime(epoch, cancel.signal).finally(() => {
+            if (this.desktopDiscovery === discovery)
+                this.desktopDiscovery = undefined;
+            if (this.desktopDiscoveryAbort === cancel)
+                this.desktopDiscoveryAbort = undefined;
+        });
+        this.desktopDiscovery = discovery;
+        return discovery;
+    }
+    async discoverDesktopRuntime(epoch, signal) {
+        const display = process.env.DISPLAY;
+        const cancelled = () => signal.aborted || this.stopped || epoch !== this.desktopDiscoveryEpoch;
+        if (cancelled() ||
+            (process.platform !== 'linux' &&
+                process.platform !== 'win32' &&
+                process.platform !== 'darwin'))
+            return;
+        if (process.platform === 'linux' && !display)
+            return;
+        try {
+            const previous = this.desktopRuntime;
+            if (previous) {
+                try {
+                    if (previous instanceof WindowsRemoteDesktopRuntime ||
+                        previous instanceof MacosRemoteDesktopRuntime)
+                        await previous.refresh(signal);
+                    previous.describe();
+                    return;
+                }
+                catch {
+                    // Keep ownership on cleanup failure; a later refresh can retry disposal.
+                    await previous.dispose();
+                    if (this.desktopRuntime === previous)
+                        this.desktopRuntime = undefined;
+                }
+            }
+            if (cancelled())
+                return;
+            const binaries = process.platform === 'win32'
+                ? await windowsManagedDesktopBinaries()
+                : process.platform === 'darwin'
+                    ? await macosManagedDesktopBinaries()
+                    : await linuxManagedDesktopBinaries();
+            if (!binaries || cancelled())
+                return;
+            const starting = (async () => {
+                let runtime;
+                try {
+                    const fence = (code) => {
+                        this.directTransferService?.invalidateDesktop(code);
+                        this.relayDesktopService?.invalidate(code);
+                    };
+                    const deadline = AbortSignal.any([signal, AbortSignal.timeout(10_000)]);
+                    runtime =
+                        process.platform === 'win32'
+                            ? await WindowsRemoteDesktopRuntime.start({ binaryPath: binaries.binaryPath, maxPixels: 67_108_864, fence }, deadline)
+                            : process.platform === 'darwin'
+                                ? await MacosRemoteDesktopRuntime.start({
+                                    binaryPath: binaries.binaryPath,
+                                    topologyBinary: 'topologyBinary' in binaries && typeof binaries.topologyBinary === 'string'
+                                        ? binaries.topologyBinary
+                                        : '',
+                                    maxPixels: 67_108_864,
+                                    fence
+                                }, deadline)
+                                : await X11RemoteDesktopRuntime.start({
+                                    ...binaries,
+                                    topologyBinary: 'topologyBinary' in binaries && typeof binaries.topologyBinary === 'string'
+                                        ? binaries.topologyBinary
+                                        : '',
+                                    display: display,
+                                    xAuthority: resolve(process.env.XAUTHORITY || resolve(homedir(), '.Xauthority')),
+                                    maxPixels: 67_108_864,
+                                    fence
+                                }, deadline);
+                }
+                catch (error) {
+                    if (cancelled())
+                        return;
+                    throw error;
+                }
+                if (cancelled() || this.desktopRuntime)
+                    await runtime.dispose();
+                else
+                    this.desktopRuntime = runtime;
+            })();
+            this.desktopStarting = starting;
+            try {
+                await starting;
+            }
+            finally {
+                if (this.desktopStarting === starting)
+                    this.desktopStarting = undefined;
+            }
+        }
+        catch {
+            // No accessible existing GUI or managed backend: advertise unavailable.
+        }
+    }
     async createDirectTransferService() {
+        const nodeGeneration = this.nodeGeneration;
         try {
             return await DirectTransferService.create({
-                nodeGeneration: () => this.nodeGeneration,
+                nodeGeneration: () => nodeGeneration,
                 send: (type, payload) => this.send(type, payload),
+                desktop: {
+                    registry: this.desktopAttachmentRegistry,
+                    isCurrent: (command) => this.isCurrentDesktop(command, nodeGeneration),
+                    createAttachment: (command, stream, callbacks) => this.createDesktopAttachment(command, stream, callbacks, nodeGeneration),
+                    emit: (event) => this.emitDesktopEvent(event, nodeGeneration)
+                },
                 terminalManager: this.terminalManager,
                 sendTerminalReady: (directSessionId, phase) => this.send('terminal.direct.ready', { directSessionId, ...(phase ? { phase } : {}) }),
                 udpPortRange: () => directTransferUdpPortRange(this.config),
@@ -1727,6 +1929,57 @@ export class NodeConnector {
             return undefined;
         }
     }
+    /** Owns both path adapters; a real runtime and capability must independently permit admission. */
+    initializeDesktopRelay() {
+        const config = this.config;
+        if (this.relayDesktopService || !config?.nodeId || !config.credential || this.stopped)
+            return;
+        const nodeId = config.nodeId;
+        const nodeGeneration = this.nodeGeneration;
+        this.relayDesktopService = new RelayDesktopService({
+            registry: this.desktopAttachmentRegistry,
+            nodeId,
+            nodeGeneration: () => nodeGeneration,
+            connect: () => new WebSocket(nodeDesktopRelayEndpoint(config.serverUrl), {
+                maxPayload: 16_384,
+                perMessageDeflate: false
+            }),
+            credential: () => {
+                if (this.config?.nodeId !== nodeId ||
+                    this.config.serverUrl !== config.serverUrl ||
+                    this.config.credential !== config.credential)
+                    throw new RemoteDesktopError('DESKTOP_UNAVAILABLE');
+                return config.credential;
+            },
+            isCurrent: (command) => this.config?.nodeId === nodeId &&
+                this.config.serverUrl === config.serverUrl &&
+                this.config.credential === config.credential &&
+                this.isCurrentDesktop(command, nodeGeneration),
+            createAttachment: (command, stream, callbacks) => this.createDesktopAttachment(command, stream, callbacks, nodeGeneration),
+            emit: (event) => this.emitDesktopEvent(event, nodeGeneration)
+        });
+    }
+    isCurrentDesktop(command, nodeGeneration) {
+        return (!this.stopped &&
+            this.nodeGeneration === nodeGeneration &&
+            command.nodeGeneration === nodeGeneration &&
+            this.capabilities.remoteDesktop?.available === true &&
+            this.capabilities.remoteDesktop.nodeGeneration === nodeGeneration &&
+            this.controlChannel.connected() &&
+            this.desktopRuntime?.isCurrent(command) === true);
+    }
+    createDesktopAttachment(command, stream, callbacks, nodeGeneration) {
+        const runtime = this.desktopRuntime;
+        if (!runtime || !this.isCurrentDesktop(command, nodeGeneration))
+            throw new RemoteDesktopError('DESKTOP_UNAVAILABLE');
+        return runtime.createAttachment(command, stream, callbacks);
+    }
+    emitDesktopEvent(event, nodeGeneration) {
+        if (this.nodeGeneration !== nodeGeneration || !this.controlChannel.connected())
+            return false;
+        this.send(event.type, event);
+        return true;
+    }
     handleDirectTransfer(envelope) {
         const command = {
             type: envelope.type,
@@ -1752,10 +2005,32 @@ export class NodeConnector {
         };
         return this.directTransferService?.handleTerminal(command) ?? false;
     }
+    handleDesktopDirect(envelope) {
+        const command = {
+            ...(typeof envelope.payload === 'object' && envelope.payload !== null
+                ? envelope.payload
+                : {}),
+            type: envelope.type
+        };
+        return this.directTransferService?.handleDesktop(command) ?? false;
+    }
+    handleDesktopRelay(envelope) {
+        const command = {
+            ...(typeof envelope.payload === 'object' && envelope.payload !== null
+                ? envelope.payload
+                : {}),
+            type: envelope.type
+        };
+        return this.relayDesktopService?.handle(command) ?? false;
+    }
     stop(options = {}) {
+        this.desktopDiscoveryEpoch++;
+        this.desktopDiscoveryAbort?.abort();
         return this.lifecycle.stop(options.handoff === true);
     }
     disposeRuntime() {
+        this.nodeGenerationRetired = true;
+        this.controlChannel.muteInbound();
         // Earlier shutdown stages may fail; disposal must still join internal reads before DB release.
         const workspaceSessionDrain = this.workspaceSessionService.stop();
         this.recentRunProjectionService.dispose();
@@ -1797,9 +2072,21 @@ export class NodeConnector {
         this.upgradeCredentials.disconnect();
         const notificationMcpDrain = this.notificationMcpBridge.close();
         const webToolDrain = this.webToolService.close();
-        this.directTransferService?.dispose();
+        const desktopShutdown = AbortSignal.timeout(10_000);
+        const directDrain = this.directTransferService?.shutdown(desktopShutdown);
+        const relayDrain = this.relayDesktopService?.shutdown(desktopShutdown);
+        const desktopRuntime = this.desktopRuntime;
         this.directTransferService = undefined;
-        this.controlChannel.stop();
+        this.relayDesktopService = undefined;
+        this.desktopRuntime = undefined;
+        const controlDrain = Promise.allSettled([directDrain, relayDrain, this.desktopStarting])
+            .then(async (results) => {
+            const runtime = await Promise.allSettled([desktopRuntime?.dispose()]);
+            const failure = [...results, ...runtime].find((result) => result.status === 'rejected');
+            if (failure)
+                throw failure.reason;
+        })
+            .finally(() => this.controlChannel.stop());
         const database = this.database;
         const drains = Promise.allSettled([
             workspaceSessionDrain,
@@ -1811,7 +2098,8 @@ export class NodeConnector {
             goalMcpDrain,
             scheduleMcpDrain,
             notificationMcpDrain,
-            webToolDrain
+            webToolDrain,
+            controlDrain
         ]);
         return (async () => {
             const hosting = await Promise.allSettled([conversationHostingDrain]);

package/dist/ctags-binary.js

@@ -1,6 +1,7 @@
 import { chmod } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { createRequire } from 'node:module';
+import { managedBinariesPlatformDirectory } from './managed-binaries.js';
 export const BUNDLED_CTAGS_VERSION = '6.2.0-ab95af1';
 const TARGETS = {
     'linux-x64': ['linux-x64', 'ctags'],
@@ -18,7 +19,10 @@ export function bundledCtagsPath(platform = process.platform, architecture = pro
     const target = TARGETS[`${platform}-${architecture}`];
     if (target === undefined)
         throw new Error('CTAGS_PLATFORM_UNSUPPORTED');
-    return resolve(bundledCtagsDirectory(packageRoot), ...target);
+    const directory = packageRoot === undefined
+        ? resolve(managedBinariesPlatformDirectory(platform, architecture), 'vendor/ctags')
+        : bundledCtagsDirectory(packageRoot);
+    return resolve(directory, ...target);
 }
 /**
  * Restores the execute bit when an installation mechanism lost the bundled

package/dist/managed-binaries.js

@@ -0,0 +1,8 @@
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+/** Resolve platform assets from the unified binaries package's own dependencies. */
+export function managedBinariesPlatformDirectory(platform, architecture) {
+    const require = createRequire(import.meta.url);
+    const entry = require.resolve('@myagentroam/binaries/package.json');
+    return dirname(createRequire(entry).resolve(`@myagentroam/binaries-${platform}-${architecture}/package.json`));
+}

package/dist/marctl/package.json

@@ -1 +1 @@
-{"type":"module","version":"0.13.11"}
+{"type":"module","version":"0.13.12"}