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

package/README.md

@@ -1,90 +1,26 @@
 # MCP Device
 
-`@hcu-lab.me/mcp-device` connects a user-owned computer to the authenticated MCP Gateway. The device opens the outbound connection; no inbound device port is required.
-
 The gateway owns accounts, OAuth, device ownership, MCP tool contracts, routing, and usage aggregation. MCP Device owns local device identity, pairing, reconnect lifecycle, bounded execution, background registration, and local status.
 
-## Quick start
-
-Canonical production gateway: https://device.hcu-lab.me
-
-- Dashboard: https://device.hcu-lab.me/dashboard
-- Pair device: https://device.hcu-lab.me/pair
-- Live setup/help: https://device.hcu-lab.me/help
-
-Install the current release:
+## Install
 
 ```powershell
-npm install -g @hcu-lab.me/mcp-device
+npm install -g @hcu-lab.me/mcp-device@1.0.7
 mcp-device login
 mcp-device install
 mcp-device status
 ```
 
-`mcp-device login` stays terminal-only: it prints the pairing URL, user code, and QR code, and never opens a browser automatically.
-
-## Limited hosted access
-
-The public source package remains MIT licensed, but access to the hosted `device.hcu-lab.me` gateway is intentionally limited. New hosted accounts are admitted through a small, controlled supply of invite codes rather than open registration. Invite availability may be capped, paused, expired, or revoked as the service capacity and security policy change. Installing the package does not by itself grant a hosted-service account or guarantee that an invite code will be available.
-
-The hosted Pair/Help pages render their gateway URL and navigation from the deployment that served the page, so staging or custom deployments do not need a production-host rewrite. For the canonical package, `https://device.hcu-lab.me` is the default gateway; `MCP_GATEWAY_URL` is only needed when intentionally using another gateway.
-
 ## Commands
 
 ```text
 mcp-device              start in the foreground
 mcp-device start        start in the foreground
-mcp-device login        explicitly link or switch the gateway account
+mcp-device login        link or switch the gateway account
 mcp-device logout       unlink the gateway account from this device
-mcp-device status       show runtime, manager, connection, security, proxy, usage, and schema state
-mcp-device install      pair if needed, then install and start a background runtime
-mcp-device stop         stop the current runtime without deleting identity/account state
-mcp-device uninstall    remove background registration while preserving identity/account state
+mcp-device status       show device and runtime status
+mcp-device install      pair if needed, then install and start the background runtime
+mcp-device stop         stop the current runtime
+mcp-device uninstall    remove background registration while preserving device identity
 mcp-device --help       show command help
 ```
-
-`md` is an alias of `mcp-device` on POSIX shells. On Windows, use `mcp-device`; bare `md` has a shell collision with built-in directory-creation commands/aliases and is not the supported invocation.
-
-On Windows, `install` uses current-user background registration. On Linux, every `install` asks whether to use `systemd --user` or an already configured PM2 installation. MCP Device does not install PM2, run `pm2 startup`, or use `sudo` automatically.
-
-## Dashboard updates
-
-Starting with MCP Device 1.0.5, an installed background device reports its package version to the authenticated gateway and can accept a per-device update requested by its owning account from the dashboard. The control is intentionally narrow: the gateway supplies only an exact stable version, and the device installs only `@hcu-lab.me/mcp-device@<version>`, verifies the installed version, then restarts through its existing Windows, systemd-user, or PM2 lifecycle.
-
-Installations older than 1.0.5 do not understand this update control. Upgrade those devices to 1.0.5 once with npm; subsequent releases can be applied from the dashboard. Offline devices remain unchanged until they are online and explicitly updated.
-
-## First run and trust
-
-The official gateway base URL is `https://device.hcu-lab.me`. The official package pins the independently distributed application CA and requires protocol v2 before the first network connection. If that CA is absent or invalid, MCP Device fails closed instead of learning trust from the gateway it is about to contact or falling back to protocol v1.
-
-For a custom gateway, set `MCP_GATEWAY_URL` and provision its application CA through an independent trusted channel before enabling protocol v2. Proxy selection is captured during interactive provisioning and reused by the background runtime.
-
-## Local state and 1.0.2 migration
-
-Canonical state is stored under `~/.mcp-device/`. Existing `~/.hcu-device/` identity/config/status state is migrated non-destructively under serialized runtime ownership. A conflicting canonical and legacy identity fails closed rather than creating a second device identity.
-
-The device identity is Ed25519. MCP Device 1.0.2 does not use Windows DPAPI for the device private key or proxy configuration. A legacy protected 1.0.1 identity is archived without decrypting it, a fresh local identity is generated, and the device must be paired once again. A legacy protected proxy configuration must be supplied again during `mcp-device login`. The gateway stores only the public device identity and account ownership.
-
-## Development
-
-```powershell
-git clone https://github.com/Hiroshimeow/agent-mcp-device.git
-cd agent-mcp-device
-npm ci
-npm run build
-node dist/mcp-device.js --help
-```
-
-Normal development pushes do not publish npm. After reviewed development work is committed on a clean `main`, a release is intentionally created with:
-
-```powershell
-npm run release
-```
-
-That command runs the test suite, bumps the patch version, synchronizes project version files, creates the release commit and `vX.Y.Z` tag, then atomically pushes `main` and the tag. The tag-triggered GitHub Actions workflow performs the npm publish through trusted OIDC publishing. Use `npm run release:minor` or `npm run release:major` only when that version change is intentional.
-
-For a custom development gateway, set `MCP_GATEWAY_URL`. Supply `MCP_GATEWAY_APP_CA_PATH` from an independent trusted source when using protocol v2. Non-loopback plaintext gateway URLs are rejected.
-
-## Upstream execution engine
-
-The local execution engine is derived from [Desktop Commander MCP](https://github.com/wonderwhy-er/DesktopCommanderMCP). Desktop Commander is MIT licensed; its copyright and MIT license are preserved in this repository's `LICENSE`. The MCP Device product identity, gateway protocol, account/device lifecycle, security layer, and packaging are maintained separately in this repository.

package/dist/bootstrap.js

@@ -7,7 +7,7 @@
  * slow or cloud-synced filesystem — 4 stalled operations exhaust the pool, and
  * because a stalled syscall keeps its thread until the OS returns (a JS-level
  * timeout does not cancel it), every subsequent fs op queues for minutes. That
- * surfaced as multi-minute tool-call hangs under parallel `claude -p` load.
+ * surfaced as multi-minute tool-call hangs under parallel agent load.
  *
  * Raising the pool size gives enough headroom that a burst of slow reads no
  * longer starves the rest. libuv reads UV_THREADPOOL_SIZE only when the pool is

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;
         }
@@ -139,7 +158,7 @@ class ConfigManager {
                 }
                 // Use user's actual shell from environment
                 // On macOS, default to zsh (default since Catalina) since process.env.SHELL
-                // may not be set when running inside Claude Desktop
+                // may not be set when launched by a desktop host
                 const fallbackShell = os.platform() === 'darwin' ? '/bin/zsh' : '/bin/sh';
                 const userShell = process.env.SHELL || fallbackShell;
                 // Return just the shell path - we'll handle login shell flag elsewhere
@@ -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/config.js

@@ -2,7 +2,7 @@ import path from 'path';
 import os from 'os';
 // MCP Device owns one canonical per-user state/config root.
 export const USER_HOME = os.homedir();
-export const CONFIG_DIR = path.resolve(process.env.MCP_DEVICE_CONFIG_DIR || process.env.DESKTOP_COMMANDER_CONFIG_DIR || path.join(USER_HOME, '.mcp-device'));
+export const CONFIG_DIR = path.resolve(process.env.MCP_DEVICE_CONFIG_DIR || path.join(USER_HOME, '.mcp-device'));
 // Paths relative to the config directory.
 export const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 export const TOOL_CALL_FILE = path.join(CONFIG_DIR, 'logs', 'tool-calls.log');

package/dist/custom-stdio.js

@@ -64,8 +64,7 @@ export class FilteredStdioServerTransport extends StdioServerTransport {
         this.clientName = clientName.toLowerCase();
         // Detect Cline and disable notifications
         if (this.clientName.includes('cline') ||
-            this.clientName.includes('vscode') ||
-            this.clientName === 'claude-dev') {
+            this.clientName.includes('vscode')) {
             this.disableNotifications = true;
             process.stderr.write(`[INFO] MCP Device: Notifications disabled for ${clientName}\n`);
         }

package/dist/data/onboarding-prompts.json

@@ -1,18 +1,20 @@
 {
   "version": "2.0.0",
-  "description": "Desktop Commander onboarding prompts - V2 simplified (5 prompts only)",
+  "description": "MCP Device local onboarding prompts",
   "prompts": [
     {
       "id": "onb2_01",
       "title": "Organize my Downloads folder",
       "description": "Clean up and organize your messy Downloads folder into relevant subfolders automatically.",
       "prompt": "Let's organize your Downloads folder! \n\nFirst, let me check what we're working with. I'll look at your Downloads folder to see how many files are there and what types.\n\nShould I start by analyzing your Downloads folder?",
-      "categories": ["onboarding"],
+      "categories": [
+        "onboarding"
+      ],
       "secondaryTag": "Quick Start",
       "votes": 0,
       "gaClicks": 0,
       "icon": "FolderOpen",
-      "author": "DC team",
+      "author": "MCP Device",
       "verified": true
     },
     {
@@ -20,11 +22,14 @@
       "title": "Explain codebase or repository to me",
       "description": "Analyze and explain any codebase - local project or GitHub repository - including architecture, dependencies, and how it works.",
       "prompt": "I'll analyze and explain any codebase for you! 🔍\n\n**What should I analyze?**\n\n*Local project:* `~/work/my-project` (replace with your path)\n*GitHub repo:* `https://github.com/user/repo`\n\nI'll break down the architecture, dependencies, and how everything works together!",
-      "categories": ["onboarding"],      "secondaryTag": "Code Analysis",
+      "categories": [
+        "onboarding"
+      ],
+      "secondaryTag": "Code Analysis",
       "votes": 0,
       "gaClicks": 0,
       "icon": "Code",
-      "author": "DC team",
+      "author": "MCP Device",
       "verified": true
     },
     {
@@ -32,12 +37,14 @@
       "title": "Create organized knowledge/documents folder",
       "description": "Set up a well-structured knowledge base or document organization system with templates and suggested categories.",
       "prompt": "Let's create an organized knowledge base! 📚\n\n**Where should I set it up?**\n\n*I suggest: `~/Documents/Knowledge-Base` (replace with your path) or give me a different location.*\n\nI'll create a clean folder structure with templates and organize any existing documents you have!",
-      "categories": ["onboarding"],
+      "categories": [
+        "onboarding"
+      ],
       "secondaryTag": "Quick Start",
       "votes": 0,
       "gaClicks": 0,
       "icon": "BookOpen",
-      "author": "DC team",
+      "author": "MCP Device",
       "verified": true
     },
     {
@@ -45,12 +52,14 @@
       "title": "Analyze my data file",
       "description": "Upload or point to any data file (CSV, JSON, Excel, etc.) and get comprehensive analysis including patterns, insights, and summary reports.",
       "prompt": "I'll help you analyze your data file! \n\nWhat's the path to your data file? (e.g., `/Users/yourname/data.csv`)\n\nOnce you give me the path, I'll start by checking what type of file it is and show you a quick preview, then we can dive deeper step by step.",
-      "categories": ["onboarding"],
+      "categories": [
+        "onboarding"
+      ],
       "secondaryTag": "Quick Start",
       "votes": 0,
       "gaClicks": 0,
       "icon": "BarChart3",
-      "author": "DC team",
+      "author": "MCP Device",
       "verified": true
     },
     {
@@ -58,12 +67,14 @@
       "title": "Check system health and resources",
       "description": "Analyze your system's health, resource usage, running processes, and generate a comprehensive system status report.",
       "prompt": "Let me check your system health and resources!\n\nI'll start by looking at your CPU, memory, and disk usage, then check for any performance issues.\n\nShould I begin the system analysis?",
-      "categories": ["onboarding"],
+      "categories": [
+        "onboarding"
+      ],
       "secondaryTag": "Quick Start",
       "votes": 0,
       "gaClicks": 0,
       "icon": "Activity",
-      "author": "DC team",
+      "author": "MCP Device",
       "verified": true
     }
   ]

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

@@ -1,13 +1,10 @@
 export declare const DEVICE_STATE_FILES: readonly string[];
 export interface DeviceStatePaths {
     root: string;
-    legacyRoot: string;
     identity: string;
     config: string;
     status: string;
+    runtime: string;
+    update: string;
 }
 export declare function deviceStatePaths(home?: string): DeviceStatePaths;
-export declare function migrateLegacyDeviceState(paths?: DeviceStatePaths): Promise<{
-    migrated: string[];
-    legacyStateSeen: boolean;
-}>;

package/dist/device/device-state.js

@@ -1,4 +1,3 @@
-import fs from 'fs/promises';
 import os from 'os';
 import path from 'path';
 export const DEVICE_STATE_FILES = Object.freeze([
@@ -8,93 +7,12 @@ export const DEVICE_STATE_FILES = Object.freeze([
 ]);
 export function deviceStatePaths(home = os.homedir()) {
     const root = path.resolve(home, '.mcp-device');
-    const legacyRoot = path.resolve(home, '.hcu-device');
     return {
         root,
-        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) {
-    try {
-        return JSON.parse(await fs.readFile(filePath, 'utf8'));
-    }
-    catch (error) {
-        if (error?.code === 'ENOENT')
-            return null;
-        throw new Error(`Invalid MCP Device state file ${filePath}: ${error?.message || error}`);
-    }
-}
-async function copyAtomic(source, target) {
-    const content = await fs.readFile(source);
-    await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
-    const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
-    await fs.writeFile(temporary, content, { mode: 0o600, flag: 'wx' });
-    await fs.rename(temporary, target);
-    try {
-        await fs.chmod(target, 0o600);
-    }
-    catch { /* Windows ACLs inherit from the user profile. */ }
-}
-function identityFingerprint(value) {
-    if (!value)
-        return null;
-    const deviceId = String(value.deviceId || '').trim();
-    const publicKeyPem = String(value.publicKeyPem || '').trim();
-    return deviceId && publicKeyPem ? `${deviceId}\n${publicKeyPem}` : null;
-}
-export async function migrateLegacyDeviceState(paths = deviceStatePaths()) {
-    await fs.mkdir(paths.root, { recursive: true, mode: 0o700 });
-    const legacyIdentityPath = path.join(paths.legacyRoot, 'gateway-identity.json');
-    const canonicalIdentity = await readJsonIfExists(paths.identity);
-    const legacyIdentity = await readJsonIfExists(legacyIdentityPath);
-    const legacyPresence = await Promise.all(DEVICE_STATE_FILES.map(async (name) => {
-        try {
-            await fs.access(path.join(paths.legacyRoot, name));
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }));
-    const legacyStateSeen = legacyPresence.some(Boolean);
-    if (canonicalIdentity && legacyIdentity) {
-        const canonicalFingerprint = identityFingerprint(canonicalIdentity);
-        const legacyFingerprint = identityFingerprint(legacyIdentity);
-        if (!canonicalFingerprint || !legacyFingerprint || canonicalFingerprint !== legacyFingerprint) {
-            throw new Error('MCP Device migration conflict: canonical and legacy device identities differ.');
-        }
-    }
-    if (legacyStateSeen && !legacyIdentity && !canonicalIdentity) {
-        throw new Error('MCP Device migration failed closed: legacy state exists without a device identity.');
-    }
-    const migrated = [];
-    for (const name of DEVICE_STATE_FILES) {
-        const source = path.join(paths.legacyRoot, name);
-        const target = path.join(paths.root, name);
-        let sourceExists = true;
-        try {
-            await fs.access(source);
-        }
-        catch {
-            sourceExists = false;
-        }
-        if (!sourceExists)
-            continue;
-        await readJsonIfExists(source);
-        let targetExists = true;
-        try {
-            await fs.access(target);
-        }
-        catch {
-            targetExists = false;
-        }
-        if (!targetExists) {
-            await copyAtomic(source, target);
-            migrated.push(name);
-        }
-    }
-    return { migrated, legacyStateSeen };
-}

package/dist/device/device.d.ts

@@ -2,7 +2,7 @@
 import { type RuntimeOwnerStatus } from './runtime-owner.js';
 export declare class MCPDevice {
     private isShuttingDown;
-    private desktop;
+    private executionEngine;
     private gatewayChannel?;
     private gatewayProxyAgent?;
     private runtimeOwner?;

package/dist/device/device.js

@@ -2,7 +2,7 @@
 import { fileURLToPath } from 'url';
 import os from 'os';
 import path from 'path';
-import { DesktopCommanderIntegration } from './execution-engine.js';
+import { LocalExecutionEngine } from './execution-engine.js';
 import { GatewayDeviceChannel } from './gateway-channel.js';
 import { GatewayDeviceConfigStore, createGatewayProxyAgent } from './gateway-config.js';
 import { GatewayDeviceIdentity } from './gateway-identity.js';
@@ -11,12 +11,13 @@ 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;
-        this.desktop = new DesktopCommanderIntegration();
+        this.executionEngine = new LocalExecutionEngine();
         this.setupShutdownHandlers();
     }
     setupShutdownHandlers() {
@@ -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')
@@ -71,7 +75,7 @@ export class MCPDevice {
             await acquireRuntimeOwner(this.runtimeOwner, { confirmTakeover: options.confirmTakeover });
             await this.runtimeOwner.bootstrap();
             await bootstrapOfficialGatewayTrust(new GatewayDeviceConfigStore());
-            await this.desktop.initialize();
+            await this.executionEngine.initialize();
             const gatewayStatus = new GatewayDeviceStatusStore();
             const storedGatewayStatus = await gatewayStatus.load();
             const gatewayConfig = await new GatewayDeviceConfigStore().load();
@@ -111,12 +115,40 @@ export class MCPDevice {
                 proxyAgent: proxy.agent,
                 securityProtocolFloor: gatewayConfig.securityProtocolFloor,
                 appCaPem: gatewayConfig.appCaPem || undefined,
-                adapter: new GatewayToolAdapter(this.desktop, { allowedRoots: gatewayConfig.allowedRoots }),
+                adapter: new GatewayToolAdapter(this.executionEngine, { allowedRoots: gatewayConfig.allowedRoots }),
+                runtimeState: () => this.executionEngine.getRuntimeState(),
                 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.executionEngine.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.executionEngine.getChildPid();
+                            await this.shutdown();
+                            await signalDeviceUpdateHandoff({ childPid });
+                            process.exit(0);
+                        }
+                    };
                 },
                 onStatus: async (payload) => {
                     const record = await identity.loadOrCreate();
@@ -138,6 +170,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) {
@@ -165,7 +225,7 @@ export class MCPDevice {
                 this.gatewayProxyAgent = undefined;
             }
             await new GatewayDeviceStatusStore().markOffline().catch(() => { });
-            await this.desktop.shutdown();
+            await this.executionEngine.shutdown();
             if (this.runtimeOwner) {
                 await this.runtimeOwner.release().catch(() => { });
                 this.runtimeOwner = undefined;

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

@@ -4,12 +4,22 @@ interface McpConfig {
     cwd?: string;
     env?: Record<string, string>;
 }
-export declare class DesktopCommanderIntegration {
+export declare class LocalExecutionEngine {
     private mcpClient;
     private mcpTransport;
     private isReady;
+    private runtimeReason;
+    private runtimeGeneration;
+    private markUnavailable;
     initialize(): Promise<void>;
     resolveMcpConfig(): Promise<McpConfig | null>;
+    getChildPid(): number | null;
+    getRuntimeState(): {
+        runtime_ready: boolean;
+        runtime_reason: string | null;
+        execution_runtime_generation: string | null;
+    };
+    assertReady(): void;
     callClientTool(toolName: string, args: any, metadata?: any): Promise<{
         [x: string]: unknown;
         content: ({