@hcu-lab.me/mcp-device 1.0.5 → 1.0.6

package/dist/config-manager.js

@@ -1,3 +1,4 @@
+import { randomBytes } from 'crypto';
 import fs from 'fs/promises';
 import path from 'path';
 import { existsSync } from 'fs';
@@ -49,29 +50,47 @@ class ConfigManager {
             if (!existsSync(configDir)) {
                 await mkdir(configDir, { recursive: true });
             }
-            // Check if config file exists
+            let configData = null;
             try {
-                await fs.access(this.configPath);
-                // Load existing config
-                const configData = await fs.readFile(this.configPath, 'utf8');
-                this.config = JSON.parse(configData);
-                this._isFirstRun = false;
-                // Configs created before this marker existed must not receive the
-                // welcome page retroactively when client eligibility changes later.
-                // New configs get this field from getDefaultConfig() and remain
-                // eligible across restarts until their first initialization.
-                if (this.config['welcomeOnboardingEligible'] === undefined) {
-                    this.config['welcomeOnboardingEligible'] = false;
-                    this.config['pendingWelcomeOnboarding'] = false;
-                    await this.saveConfig();
-                }
+                configData = await fs.readFile(this.configPath, 'utf8');
             }
             catch (error) {
-                // Config file doesn't exist, create default
+                if (error?.code !== 'ENOENT')
+                    throw error;
+            }
+            if (configData === null) {
+                // Only a genuinely missing file creates and persists defaults.
                 this.config = this.getDefaultConfig();
-                this._isFirstRun = true; // This is a first run!
+                this._isFirstRun = true;
                 await this.saveConfig();
             }
+            else {
+                try {
+                    this.config = JSON.parse(configData);
+                    this._isFirstRun = false;
+                }
+                catch (error) {
+                    // Preserve corrupt evidence rather than silently replacing user
+                    // settings with defaults. The remote execution plane can continue
+                    // safely with in-memory defaults.
+                    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+                    const corruptPath = path.join(path.dirname(this.configPath), `config.corrupt-${stamp}.json`);
+                    await fs.rename(this.configPath, corruptPath);
+                    console.warn(`Invalid MCP Device config preserved at ${corruptPath}: ${error?.message || error}`);
+                    this.config = this.getDefaultConfig();
+                    this._isFirstRun = false;
+                }
+                // Legacy onboarding-marker migration is local-client state. Remote
+                // device children normalize it in memory only so parent/child startup
+                // does not create a second writer for config.json.
+                if (this.config['welcomeOnboardingEligible'] === undefined) {
+                    this.config['welcomeOnboardingEligible'] = false;
+                    this.config['pendingWelcomeOnboarding'] = false;
+                    if (process.env.MCP_DEVICE_REMOTE !== 'true') {
+                        await this.saveConfig();
+                    }
+                }
+            }
             this.config['version'] = VERSION;
             this.initialized = true;
         }
@@ -160,7 +179,25 @@ class ConfigManager {
      * own independent fs.writeFile of the same path.
      */
     async writeConfigToDisk() {
-        await fs.writeFile(this.configPath, JSON.stringify(this.config, null, 2), 'utf8');
+        const directory = path.dirname(this.configPath);
+        await fs.mkdir(directory, { recursive: true });
+        const temporary = path.join(directory, `.${path.basename(this.configPath)}.${process.pid}.${Date.now()}.${randomBytes(6).toString('hex')}.tmp`);
+        try {
+            await fs.writeFile(temporary, JSON.stringify(this.config, null, 2), {
+                encoding: 'utf8',
+                mode: 0o600,
+                flag: 'wx'
+            });
+            await fs.rename(temporary, this.configPath);
+            try {
+                await fs.chmod(this.configPath, 0o600);
+            }
+            catch { /* Windows ACLs inherit from the user profile. */ }
+        }
+        catch (error) {
+            await fs.rm(temporary, { force: true }).catch(() => { });
+            throw error;
+        }
     }
     /**
      * Awaitable save, serialized on writeChain. Use for explicit, user-driven

package/dist/device/device-state.d.ts

@@ -5,6 +5,8 @@ export interface DeviceStatePaths {
     identity: string;
     config: string;
     status: string;
+    runtime: string;
+    update: string;
 }
 export declare function deviceStatePaths(home?: string): DeviceStatePaths;
 export declare function migrateLegacyDeviceState(paths?: DeviceStatePaths): Promise<{

package/dist/device/device-state.js

@@ -14,7 +14,9 @@ export function deviceStatePaths(home = os.homedir()) {
         legacyRoot,
         identity: path.join(root, 'gateway-identity.json'),
         config: path.join(root, 'gateway-config.json'),
-        status: path.join(root, 'gateway-status.json')
+        status: path.join(root, 'gateway-status.json'),
+        runtime: path.join(root, 'runtime'),
+        update: path.join(root, 'update')
     };
 }
 async function readJsonIfExists(filePath) {

package/dist/device/device.js

@@ -11,8 +11,9 @@ import { bootstrapOfficialGatewayTrust } from './official-trust.js';
 import { GatewayDeviceStatusStore } from './device-status.js';
 import { GatewayToolAdapter } from './gateway-tool-adapter.js';
 import { RuntimeOwner, acquireRuntimeOwner } from './runtime-owner.js';
-import { installDevicePackageUpdate, scheduleDeviceRuntimeRestart } from './self-update.js';
+import { assertDeviceStartupAllowedDuringUpdate, launchDeviceUpdateHelper, prepareDevicePackageUpdate, reconcileDeviceUpdateAfterStart, retireDeviceUpdateState, signalDeviceUpdateHandoff } from './self-update.js';
 import { captureRemote } from '../utils/capture.js';
+import { VERSION } from '../version.js';
 export class MCPDevice {
     constructor() {
         this.isShuttingDown = false;
@@ -62,6 +63,9 @@ export class MCPDevice {
             console.log('🚀 Starting MCP Device...');
             if (process.env.DEBUG_MODE === 'true')
                 console.log('  - 🐞 DEBUG_MODE');
+            // A fresh external update helper owns the package lifecycle.
+            // Refuse a competing runtime until it completes or becomes stale.
+            await assertDeviceStartupAllowedDuringUpdate(VERSION);
             const managerArg = process.argv.find(value => value.startsWith('--manager='));
             const manager = managerArg?.slice('--manager='.length);
             const mode = process.argv.includes('--service')
@@ -113,10 +117,37 @@ export class MCPDevice {
                 appCaPem: gatewayConfig.appCaPem || undefined,
                 adapter: new GatewayToolAdapter(this.desktop, { allowedRoots: gatewayConfig.allowedRoots }),
                 agentVersion: process.env.npm_package_version,
-                onUpdateRequest: async (targetVersion) => {
+                onUpdateRequest: async (targetVersion, { requestId }) => {
                     const record = await identity.loadOrCreate();
-                    await installDevicePackageUpdate(targetVersion);
-                    scheduleDeviceRuntimeRestart({ deviceId: record.deviceId });
+                    const prepared = await prepareDevicePackageUpdate({
+                        targetVersion,
+                        requestId,
+                        deviceId: record.deviceId,
+                        childPid: this.desktop.getChildPid(),
+                        fromVersion: VERSION
+                    });
+                    try {
+                        // Launch the helper while the service is healthy. The
+                        // helper remains inert until the explicit handoff marker.
+                        await launchDeviceUpdateHelper(prepared);
+                    }
+                    catch (error) {
+                        await retireDeviceUpdateState(prepared.state).catch(() => { });
+                        throw error;
+                    }
+                    return {
+                        mode: 'detached',
+                        handoff: async () => {
+                            // Capture the last live child PID, then complete graceful
+                            // shutdown and RuntimeOwner release before arming the helper.
+                            // This preserves G5.6: no destructive update work may begin
+                            // until the old runtime has finished releasing package handles.
+                            const childPid = this.desktop.getChildPid();
+                            await this.shutdown();
+                            await signalDeviceUpdateHandoff({ childPid });
+                            process.exit(0);
+                        }
+                    };
                 },
                 onStatus: async (payload) => {
                     const record = await identity.loadOrCreate();
@@ -138,6 +169,34 @@ export class MCPDevice {
                 }
             });
             await this.gatewayChannel.start();
+            const updateReconciliation = await reconcileDeviceUpdateAfterStart(VERSION);
+            if (updateReconciliation.action === 'success') {
+                // Successful reconnect already advertised the target package_version
+                // in auth_hello; that reconnect is the authoritative completion proof.
+                // Do not send a late "installed" status: the gateway completes the
+                // update from the authenticated reconnect itself.
+                try {
+                    await retireDeviceUpdateState(updateReconciliation.state);
+                }
+                catch (error) {
+                    // A transient Windows EPERM/EBUSY while the detached helper is
+                    // exiting must not turn a healthy target reconnect into startup failure.
+                    console.warn('Update cleanup deferred:', error?.message || error);
+                }
+            }
+            else if (updateReconciliation.action === 'report-failed') {
+                try {
+                    await this.gatewayChannel.reportUpdateFailure(updateReconciliation.state.requestId, updateReconciliation.state.targetVersion, updateReconciliation.state.errorCode || 'DEVICE_UPDATE_FAILED', updateReconciliation.state.message || 'MCP Device update rolled back.');
+                    await retireDeviceUpdateState(updateReconciliation.state).catch((error) => {
+                        console.warn('Failed update cleanup deferred:', error?.message || error);
+                    });
+                }
+                catch (error) {
+                    // Keep durable failed state for a later reporting attempt; do not
+                    // make the restored runtime unavailable because reporting raced.
+                    console.warn('Failed update report deferred:', error?.message || error);
+                }
+            }
             console.log('✓ Device ready through direct Gateway channel');
         }
         catch (error) {

package/dist/device/execution-engine.d.ts

@@ -10,6 +10,7 @@ export declare class DesktopCommanderIntegration {
     private isReady;
     initialize(): Promise<void>;
     resolveMcpConfig(): Promise<McpConfig | null>;
+    getChildPid(): number | null;
     callClientTool(toolName: string, args: any, metadata?: any): Promise<{
         [x: string]: unknown;
         content: ({

package/dist/device/execution-engine.js

@@ -5,6 +5,7 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { fileURLToPath } from 'url';
 import { captureRemote } from '../utils/capture.js';
+import { deviceStatePaths } from './device-state.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 export class DesktopCommanderIntegration {
@@ -68,10 +69,12 @@ export class DesktopCommanderIntegration {
         try {
             await fs.access(devPath);
             console.debug(' - 🔍 Found local MCP server at:', devPath);
+            const runtimeDir = deviceStatePaths().runtime;
+            await fs.mkdir(runtimeDir, { recursive: true, mode: 0o700 });
             return {
                 command: process.execPath, // Use the current node executable
                 args: [devPath],
-                cwd: path.dirname(devPath)
+                cwd: runtimeDir
             };
         }
         catch {
@@ -110,6 +113,9 @@ export class DesktopCommanderIntegration {
         console.debug('[DEBUG] No MCP config resolved');
         return null;
     }
+    getChildPid() {
+        return this.mcpTransport?.pid ?? null;
+    }
     async callClientTool(toolName, args, metadata) {
         if (!this.isReady || !this.mcpClient) {
             console.debug('[DEBUG] callClientTool() failed - not ready or no client');

package/dist/device/gateway-channel.d.ts

@@ -1,6 +1,10 @@
 import type { Agent } from 'http';
 import { GatewayDeviceIdentity } from './gateway-identity.js';
 import { GatewayToolAdapter } from './gateway-tool-adapter.js';
+export type GatewayUpdateRequestOutcome = {
+    mode: 'detached';
+    handoff: () => Promise<void>;
+};
 export interface GatewayChannelOptions {
     gatewayUrl: string;
     enrollmentToken?: string;
@@ -12,7 +16,9 @@ export interface GatewayChannelOptions {
     adapter: GatewayToolAdapter;
     agentVersion?: string;
     onStatus?: (payload: any) => void | Promise<void>;
-    onUpdateRequest?: (targetVersion: string) => void | Promise<void>;
+    onUpdateRequest?: (targetVersion: string, context: {
+        requestId: string;
+    }) => GatewayUpdateRequestOutcome | Promise<GatewayUpdateRequestOutcome>;
 }
 export declare class GatewayDeviceChannel {
     private options;
@@ -32,6 +38,7 @@ export declare class GatewayDeviceChannel {
     private protocolVersion;
     private secureSocket?;
     private authMode;
+    private updateInFlight?;
     constructor(options: GatewayChannelOptions);
     start(): Promise<void>;
     private startV2Transport;
@@ -40,11 +47,16 @@ export declare class GatewayDeviceChannel {
     private sendHelloV2;
     private handleMessage;
     logoutAccount(timeoutMs?: number): Promise<any>;
+    private updateStatusMessage;
+    private sendUpdateStatus;
+    private sendUpdateStatusFlushed;
+    reportUpdateFailure(requestId: string, targetVersion: string, code: string, message: string): Promise<void>;
     private handleUpdateRequest;
     private handleToolCall;
     private scheduleReconnect;
     private startHeartbeat;
     private stopHeartbeat;
     private send;
+    private sendFlushed;
     private fail;
 }

package/dist/device/gateway-channel.js

@@ -55,10 +55,15 @@ export class GatewayDeviceChannel {
         socket.once('error', error => this.fail(error));
         socket.once('close', (code, reason) => {
             this.stopHeartbeat();
+            const reasonText = reason.toString();
+            const forgotten = code === 4003 && /(?:unknown or revoked device|revoked device|device revoked)/i.test(reasonText);
+            const error = new Error(`Gateway connection closed (${code}): ${reasonText}`);
+            if (forgotten)
+                error.code = 'DEVICE_FORGOTTEN';
             if (!this.shuttingDown && this.readyReject) {
-                this.fail(new Error(`Gateway connection closed (${code}): ${reason.toString()}`));
+                this.fail(error);
             }
-            else if (!this.shuttingDown) {
+            else if (!this.shuttingDown && !forgotten) {
                 this.scheduleReconnect();
             }
         });
@@ -297,40 +302,83 @@ export class GatewayDeviceChannel {
             clearTimeout(timer);
         }
     }
+    updateStatusMessage(requestId, targetVersion, state, extra = {}) {
+        if (this.connectionEpoch === undefined || !this.authenticatedDeviceId) {
+            throw new Error('Gateway update status cannot be sent before authentication.');
+        }
+        return {
+            protocol_version: this.protocolVersion,
+            type: 'device_update_status',
+            request_id: requestId,
+            device_id: this.authenticatedDeviceId,
+            connection_epoch: this.connectionEpoch,
+            timestamp: Date.now(),
+            payload: { state, target_version: targetVersion, package_version: VERSION, ...extra }
+        };
+    }
+    sendUpdateStatus(requestId, targetVersion, state, extra = {}) {
+        try {
+            this.send(this.updateStatusMessage(requestId, targetVersion, state, extra));
+        }
+        catch {
+            // Best-effort path used only when the socket may already be closing.
+        }
+    }
+    async sendUpdateStatusFlushed(requestId, targetVersion, state, extra = {}) {
+        await this.sendFlushed(this.updateStatusMessage(requestId, targetVersion, state, extra));
+    }
+    async reportUpdateFailure(requestId, targetVersion, code, message) {
+        // Failed update state is retired only after this awaited send succeeds.
+        await this.sendUpdateStatusFlushed(requestId, targetVersion, 'failed', {
+            code: String(code || 'DEVICE_UPDATE_FAILED').slice(0, 64),
+            message: String(message || 'Device update failed.').slice(0, 240)
+        });
+    }
     async handleUpdateRequest(message) {
         if (this.connectionEpoch === undefined || !this.authenticatedDeviceId)
             return;
         const requestId = String(message.request_id || '').trim();
         const targetVersion = String(message.payload?.target_version || '').trim();
-        const sendStatus = (state, extra = {}) => {
-            try {
-                this.send({
-                    protocol_version: this.protocolVersion,
-                    type: 'device_update_status',
-                    request_id: requestId,
-                    device_id: this.authenticatedDeviceId,
-                    connection_epoch: this.connectionEpoch,
-                    timestamp: Date.now(),
-                    payload: { state, target_version: targetVersion, package_version: VERSION, ...extra }
+        if (!requestId || !/^\d+\.\d+\.\d+$/.test(targetVersion) || typeof this.options.onUpdateRequest !== 'function') {
+            this.sendUpdateStatus(requestId, targetVersion, 'failed', {
+                code: 'DEVICE_UPDATE_UNSUPPORTED',
+                message: 'Device update request is unsupported or invalid.'
+            });
+            return;
+        }
+        if (this.updateInFlight) {
+            if (this.updateInFlight !== requestId) {
+                this.sendUpdateStatus(requestId, targetVersion, 'failed', {
+                    code: 'DEVICE_UPDATE_IN_PROGRESS',
+                    message: 'Another MCP Device update is already in progress.'
                 });
             }
-            catch { /* reconnect state will make the final version authoritative */ }
-        };
-        if (!requestId || !/^\d+\.\d+\.\d+$/.test(targetVersion) || typeof this.options.onUpdateRequest !== 'function') {
-            sendStatus('failed', { code: 'DEVICE_UPDATE_UNSUPPORTED', message: 'Device update request is unsupported or invalid.' });
             return;
         }
-        sendStatus('accepted');
+        this.updateInFlight = requestId;
         try {
-            await this.options.onUpdateRequest(targetVersion);
-            sendStatus('installed');
+            // Pre-stage and verify the target before acknowledging the update.
+            // If this throws, the currently running device stays healthy.
+            const outcome = await this.options.onUpdateRequest(targetVersion, { requestId });
+            if (!outcome || outcome.mode !== 'detached') {
+                throw Object.assign(new Error('Device update handler did not provide a detached handoff.'), { code: 'DEVICE_UPDATE_INVALID_HANDOFF' });
+            }
+            // Do not tear down the socket until the gateway has accepted
+            // the frame into the transport write path.
+            await this.sendUpdateStatusFlushed(requestId, targetVersion, 'accepted');
+            await outcome.handoff();
+            return;
         }
         catch (error) {
-            sendStatus('failed', {
+            this.sendUpdateStatus(requestId, targetVersion, 'failed', {
                 code: String(error?.code || 'DEVICE_UPDATE_FAILED').slice(0, 64),
                 message: String(error?.message || error).slice(0, 240)
             });
         }
+        finally {
+            if (this.updateInFlight === requestId)
+                this.updateInFlight = undefined;
+        }
     }
     async handleToolCall(message) {
         if (this.connectionEpoch === undefined || !this.authenticatedDeviceId)
@@ -411,6 +459,29 @@ export class GatewayDeviceChannel {
         }
         this.socket.send(encoded);
     }
+    async sendFlushed(message) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
+            throw new Error('Gateway socket is not open');
+        const encoded = JSON.stringify(message);
+        if (Buffer.byteLength(encoded, 'utf8') > MAX_OUTBOUND_MESSAGE_BYTES) {
+            const error = new Error('Gateway device response exceeds the outbound message limit');
+            error.code = 'DEVICE_OUTPUT_TOO_LARGE';
+            throw error;
+        }
+        if (this.protocolVersion === PROTOCOL_VERSION_V2) {
+            if (!this.secureSocket || this.secureSocket.destroyed)
+                throw new Error('Gateway v2 inner TLS socket is not open');
+            const secureSocket = this.secureSocket;
+            await new Promise((resolve, reject) => {
+                secureSocket.write(encodeJsonFrame(message), error => error ? reject(error) : resolve());
+            });
+            return;
+        }
+        const socket = this.socket;
+        await new Promise((resolve, reject) => {
+            socket.send(encoded, error => error ? reject(error) : resolve());
+        });
+    }
     fail(error) {
         const reject = this.readyReject;
         this.readyResolve = undefined;

package/dist/device/gateway-identity.d.ts

@@ -13,6 +13,7 @@ export declare class GatewayDeviceIdentity {
     });
     loadOrCreate(): Promise<GatewayIdentityRecord>;
     markEnrolled(): Promise<void>;
+    forget(): Promise<void>;
     signChallenge(nonce: string): Promise<string>;
     signChallengeV2(options: {
         mode: 'reconnect' | 'enroll' | 'pair';

package/dist/device/gateway-identity.js

@@ -82,6 +82,10 @@ export class GatewayDeviceIdentity {
         this.record = { ...current, enrolled: true };
         await this.persist();
     }
+    async forget() {
+        this.record = undefined;
+        await fs.rm(this.identityPath, { force: true });
+    }
     async signChallenge(nonce) {
         const current = await this.loadOrCreate();
         const challenge = Buffer.from(`mcp-device-auth-v1\n${current.deviceId}\n${nonce}`, 'utf8');

package/dist/device/linux-service.d.ts

@@ -1,3 +1,5 @@
+export declare const SYSTEMD_UNIT = "mcp-device.service";
+export declare const PM2_NAME = "mcp-device";
 type ExecFileResult = {
     stdout: string;
     stderr: string;

package/dist/device/linux-service.js

@@ -5,9 +5,9 @@ import path from 'path';
 import readline from 'readline/promises';
 import { promisify } from 'util';
 const execFileAsync = promisify(execFileCallback);
-const SYSTEMD_UNIT = 'mcp-device.service';
+export const SYSTEMD_UNIT = 'mcp-device.service';
 const SYSTEMD_OWNER_MARKER = '# Managed by MCP Device';
-const PM2_NAME = 'mcp-device';
+export const PM2_NAME = 'mcp-device';
 async function defaultExecFile(file, args) {
     const result = await execFileAsync(file, args, { windowsHide: true, encoding: 'utf8' });
     return { stdout: String(result.stdout || ''), stderr: String(result.stderr || '') };

package/dist/device/runtime-owner.d.ts

@@ -9,6 +9,7 @@ export interface RuntimeOwnerStatus {
     entrypoint: string;
     deviceId: string | null;
 }
+export declare function runtimeOwnerControlFileFor(paths: DeviceStatePaths): string;
 export declare function probeRuntimeOwner(paths?: DeviceStatePaths, platform?: NodeJS.Platform | string): Promise<RuntimeOwnerStatus | null>;
 export declare class RuntimeOwner {
     readonly paths: DeviceStatePaths;

package/dist/device/runtime-owner.js

@@ -9,7 +9,7 @@ function endpointFor(paths, platform = process.platform) {
         return `\\\\.\\pipe\\mcp-device-${digest}`;
     return path.join(paths.root, `runtime-${digest}.sock`);
 }
-function controlFileFor(paths) {
+export function runtimeOwnerControlFileFor(paths) {
     return path.join(paths.root, 'runtime-control.json');
 }
 async function request(endpoint, message, timeoutMs = 800) {
@@ -103,7 +103,7 @@ export class RuntimeOwner {
             this.server.once('error', reject);
             this.server.listen(this.endpoint, resolve);
         });
-        await fs.writeFile(controlFileFor(this.paths), JSON.stringify({ endpoint: this.endpoint, nonce: this.nonce }, null, 2), { mode: 0o600 });
+        await fs.writeFile(runtimeOwnerControlFileFor(this.paths), JSON.stringify({ endpoint: this.endpoint, nonce: this.nonce }, null, 2), { mode: 0o600 });
     }
     async bootstrap() {
         await migrateLegacyDeviceState(this.paths);
@@ -118,7 +118,7 @@ export class RuntimeOwner {
             await new Promise(resolve => server.close(() => resolve()));
         }
         try {
-            await fs.unlink(controlFileFor(this.paths));
+            await fs.unlink(runtimeOwnerControlFileFor(this.paths));
         }
         catch (error) {
             if (error?.code !== 'ENOENT')
@@ -138,7 +138,7 @@ export class RuntimeOwner {
 export async function stopRuntimeOwner(paths = deviceStatePaths(), platform = process.platform) {
     let control;
     try {
-        control = JSON.parse(await fs.readFile(controlFileFor(paths), 'utf8'));
+        control = JSON.parse(await fs.readFile(runtimeOwnerControlFileFor(paths), 'utf8'));
     }
     catch (error) {
         if (error?.code === 'ENOENT')