livedesk 0.1.288 → 0.1.290

package/README.md

@@ -1,12 +1,30 @@
-# LiveDesk
-
-Local screen wall Hub and remote client launcher.
-
-## Hub
+# LiveDesk
+
+One-command LiveDesk application. The same launcher resolves this computer's
+Hub or Client role, then starts only the runtime required by that role.
+
+## Unified launch
+
+```powershell
+npx -y --prefer-online livedesk@latest
+```
+
+The first interactive launch asks whether this computer is a Hub or Client.
+The selected role and stable device identity are cached in
+`~/.livedesk/device-role.json` and `~/.livedesk/device.json`. When a Supabase
+device role is available, it takes precedence over the offline cache.
+
+For development and migration checks, the role can be forced for one run:
+
+```powershell
+npx -y --prefer-online livedesk@latest --force-role hub
+npx -y --prefer-online livedesk@latest --force-role client
+```
+
+## Hub
 
 ```powershell
-npx -y --prefer-online livedesk@latest
-npx -y --prefer-online livedesk@latest hub
+npx -y --prefer-online livedesk@latest hub
 ```
 
 This starts the LiveDesk Hub, opens the local screen wall, and accepts clients.
@@ -23,16 +41,17 @@ Pass `--no-clean` to disable the startup cleanup explicitly. If a child Hub
 still loses a startup race with `EADDRINUSE`, the launcher performs one cleanup
 and startup retry, then exits without looping.
 
-## Client
+## Client compatibility
 
 ```powershell
-npx -y --prefer-online livedesk@latest client
-npx -y --prefer-online livedesk@latest client 3
-```
-
-The client signs in with Google, discovers the active Hub, and connects to the wall.
-On Windows, enable **Start with Windows** on the connection page to reconnect
-automatically after reboot.
+npx -y --prefer-online livedesk@latest client 3
+```
+
+The `client` form remains as a legacy compatibility alias. It records the
+Client role and uses the same unified runtime lock. The client signs in with
+Google, discovers the active Hub, and connects to the wall. On Windows, enable
+**Start with Windows** on the connection page to reconnect automatically after
+reboot; the generated startup command uses the unified launcher.
 
 ## Frame modes
 

package/bin/livedesk.js

@@ -4,10 +4,14 @@ import { createRequire } from 'node:module';
 import net from 'node:net';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execFile, spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { randomBytes } from 'node:crypto';
-import os from 'node:os';
+import { randomBytes } from 'node:crypto';
+import os from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { resolveDeviceRole, writeRoleCache } from '../bootstrap/device-role.js';
+import { acquireRuntimeLock } from '../bootstrap/runtime-lock.js';
 
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -22,21 +26,21 @@ const HUB_UPDATE_POLL_MS = 250;
 const MANAGER_STATE_DIR = join(os.homedir(), '.livedesk');
 const MANAGER_STATE_PATH = join(MANAGER_STATE_DIR, 'manager.json');
 
-function printHelp() {
-  process.stdout.write(`
-LiveDesk
-
-Usage:
-  npx -y --prefer-online livedesk@latest
-  npx -y --prefer-online livedesk@latest hub
-  npx -y --prefer-online livedesk@latest client
-  npx -y --prefer-online livedesk@latest client 3
-
-Commands:
-  hub            Start the local LiveDesk Hub. Default.
-  client         Connect this workstation to the Hub.
-
-Hub options:
+function printHelp() {
+  process.stdout.write(`
+LiveDesk
+
+Usage:
+  npx -y --prefer-online livedesk@latest
+  npx -y --prefer-online livedesk@latest --force-role hub
+  npx -y --prefer-online livedesk@latest --force-role client
+
+Commands:
+  No command     Resolve the signed-in device role and start the matching runtime.
+  hub            Legacy alias for --force-role hub.
+  client         Legacy alias for --force-role client.
+
+Hub options:
   --no-open      Do not open the browser automatically.
   --url <url>    Browser URL to open. Default: ${DEFAULT_MANAGER_URL}
   --host <host>  Hub HTTP host. Default: 127.0.0.1
@@ -45,11 +49,15 @@ Hub options:
                  Client connection port. Default: 5197.
   --no-clean     Do not stop existing processes on the Hub ports.
 
-Common:
-  --help         Show this help.
-  --version      Show version.
-`.trimStart());
-}
+Common:
+  --force-role <hub|client>
+                 Force a runtime role for development or migration checks.
+  --no-role-prompt
+                 Do not ask for a role on first run; fail if no role is known.
+  --help         Show this help.
+  --version      Show version.
+`.trimStart());
+}
 
 function printClientHelp() {
   process.stdout.write(`
@@ -91,6 +99,48 @@ function readClientVersion() {
     return '';
   }
 }
+
+function parseTopLevelArgs(args) {
+  const forwarded = [];
+  let forcedRole = '';
+  let noRolePrompt = false;
+  let noSingleInstance = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--force-role' || arg === '--role') {
+      forcedRole = String(args[index + 1] || '').trim().toLowerCase();
+      index += 1;
+      continue;
+    }
+    if (arg === '--no-role-prompt') {
+      noRolePrompt = true;
+      continue;
+    }
+    if (arg === '--no-single-instance') {
+      noSingleInstance = true;
+      continue;
+    }
+    forwarded.push(arg);
+  }
+  return { forwarded, forcedRole, noRolePrompt, noSingleInstance };
+}
+
+async function promptForDeviceRole(identity) {
+  if (!input.isTTY || !output.isTTY) {
+    return '';
+  }
+  const readline = createInterface({ input, output });
+  try {
+    console.log(`\nLiveDesk first run on ${identity.deviceName || os.hostname()}.`);
+    console.log('Choose how this computer will be used:');
+    console.log('  1. Hub    Manage and control other computers');
+    console.log('  2. Client  Share this computer with an existing Hub');
+    const answer = String(await readline.question('Select 1 or 2: ')).trim().toLowerCase();
+    return answer === '1' || answer === 'hub' ? 'hub' : answer === '2' || answer === 'client' ? 'client' : '';
+  } finally {
+    readline.close();
+  }
+}
 
 function parseManagerArgs(args) {
   const forwarded = [];
@@ -532,7 +582,7 @@ function buildHubRestartBootstrapScript() {
   ].join('\n');
 }
 
-async function runManager(args) {
+async function runManager(args, resolvedRole = null) {
   const options = parseManagerArgs(args);
   const httpPort = normalizePort(
     options.port || process.env.LIVEDESK_HUB_HTTP_PORT || process.env.PORT,
@@ -571,7 +621,12 @@ async function runManager(args) {
     LIVEDESK_HUB_UPDATE_REQUEST_PATH: updateRequestPath,
     REMOTE_HUB_PORT: String(remotePort),
     REMOTE_HUB_PAIR_TOKEN: pairToken,
-    LIVEDESK_WEB_DIST: existsSync(resolve(packagedWebDist, 'index.html')) ? packagedWebDist : (process.env.LIVEDESK_WEB_DIST || '')
+    LIVEDESK_WEB_DIST: existsSync(resolve(packagedWebDist, 'index.html')) ? packagedWebDist : (process.env.LIVEDESK_WEB_DIST || ''),
+    LIVEDESK_RUNTIME_ROLE: 'hub',
+    LIVEDESK_DEVICE_ID: String(resolvedRole?.deviceId || process.env.LIVEDESK_DEVICE_ID || ''),
+    LIVEDESK_DEVICE_NAME: String(resolvedRole?.deviceName || process.env.LIVEDESK_DEVICE_NAME || os.hostname()),
+    LIVEDESK_ROLE_CACHE_PATH: join(MANAGER_STATE_DIR, 'device-role.json'),
+    LIVEDESK_ROLE_SOURCE: String(resolvedRole?.source || process.env.LIVEDESK_ROLE_SOURCE || '')
   };
 
   let startupRetryCount = 0;
@@ -581,7 +636,7 @@ async function runManager(args) {
 
   const restartWithLatest = () => {
     const npxCommand = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-    const nextArgs = ['-y', '--prefer-online', 'livedesk@latest', 'hub', ...args];
+    const nextArgs = ['-y', '--prefer-online', 'livedesk@latest', '--force-role', 'hub', ...args];
     const command = process.platform === 'win32' ? (process.env.ComSpec || 'cmd.exe') : npxCommand;
     const commandArgs = process.platform === 'win32'
       ? ['/d', '/s', '/c', `call ${quoteWindowsCommandArg(npxCommand)} ${nextArgs.map(quoteWindowsCommandArg).join(' ')}`]
@@ -697,14 +752,21 @@ async function runManager(args) {
   }
 }
 
-function runClient(args) {
-  const clientEntry = require.resolve('@livedesk/client/bin/livedesk-client.js');
-  const child = spawn(process.execPath, [clientEntry, ...args], {
-    env: {
-      ...process.env,
-      LIVEDESK_NPM_LAUNCHER_NAME: 'livedesk',
-      LIVEDESK_NPM_LAUNCHER_VERSION: readVersion()
-    },
+function runClient(args, resolvedRole = null) {
+  const clientEntry = require.resolve('@livedesk/client/bin/livedesk-client.js');
+  const hasDeviceId = args.some(arg => arg === '--device-id' || arg.startsWith('--device-id='));
+  const clientArgs = hasDeviceId || !resolvedRole?.deviceId
+    ? args
+    : [...args, '--device-id', resolvedRole.deviceId];
+  const child = spawn(process.execPath, [clientEntry, ...clientArgs], {
+    env: {
+      ...process.env,
+      LIVEDESK_NPM_LAUNCHER_NAME: 'livedesk',
+      LIVEDESK_NPM_LAUNCHER_VERSION: readVersion(),
+      LIVEDESK_RUNTIME_ROLE: 'client',
+      LIVEDESK_DEVICE_ID: String(resolvedRole?.deviceId || process.env.LIVEDESK_DEVICE_ID || ''),
+      LIVEDESK_ROLE_SOURCE: String(resolvedRole?.source || process.env.LIVEDESK_ROLE_SOURCE || '')
+    },
     stdio: 'inherit',
     windowsHide: false
   });
@@ -721,10 +783,12 @@ function runClient(args) {
   });
 }
 
-async function main() {
-  const args = process.argv.slice(2);
-  const command = String(args[0] || 'hub').toLowerCase();
-  if (command === '--help' || command === '-h' || command === 'help') {
+async function main() {
+  const rawArgs = process.argv.slice(2);
+  const topLevel = parseTopLevelArgs(rawArgs);
+  const args = topLevel.forwarded;
+  const command = String(args[0] || '').toLowerCase();
+  if (command === '--help' || command === '-h' || command === 'help') {
     printHelp();
     return;
   }
@@ -732,24 +796,70 @@ async function main() {
     console.log(readVersion());
     return;
   }
-  if (command === 'client') {
-    if (args.slice(1).some(arg => arg === '--help' || arg === '-h' || arg === 'help')) {
-      printClientHelp();
-      return;
-    }
-    runClient(args.slice(1));
-    return;
-  }
-  if (command === 'hub' || command === 'manager') {
+  const explicitRoleCommand = command === 'hub' || command === 'manager' || command === 'client';
+  let resolvedRole;
+  let runtimeArgs = args;
+  if (explicitRoleCommand) {
+    const role = command === 'client' ? 'client' : 'hub';
+    resolvedRole = await resolveDeviceRole({ forcedRole: role });
+    writeRoleCache({ ...resolvedRole, source: 'local-cache', isOfflineFallback: false });
+    runtimeArgs = args.slice(1);
+    if (command === 'client') {
+      console.warn('[LiveDesk] Legacy client command detected. Use `npx -y --prefer-online livedesk@latest` for automatic role selection.');
+    }
+  } else {
+    resolvedRole = await resolveDeviceRole({
+      forcedRole: topLevel.forcedRole || process.env.LIVEDESK_FORCE_ROLE,
+      promptRole: topLevel.noRolePrompt ? undefined : promptForDeviceRole
+    });
+    if (!resolvedRole.role) {
+      if (resolvedRole.disabled) {
+        throw new Error(`LiveDesk device ${resolvedRole.deviceId} is disabled for this account.`);
+      }
+      throw new Error('LiveDesk device role is not assigned. Run once interactively to choose Hub or Client, or use --force-role hub|client.');
+    }
+  }
+
+  if (topLevel.noSingleInstance || process.env.LIVEDESK_DISABLE_SINGLE_INSTANCE === '1') {
+    console.warn('[LiveDesk] Single-instance lock disabled for this run.');
+  }
+  const lock = topLevel.noSingleInstance || process.env.LIVEDESK_DISABLE_SINGLE_INSTANCE === '1'
+    ? { acquired: true, release: () => undefined }
+    : acquireRuntimeLock({
+      role: resolvedRole.role,
+      openExisting: existing => {
+        const port = existing.role === 'client' ? 5198 : DEFAULT_MANAGER_HTTP_PORT;
+        openBrowser(`http://127.0.0.1:${port}`);
+        console.log(`[LiveDesk] An existing ${existing.role || 'runtime'} is already running (pid ${existing.pid}). Opened its local page.`);
+      }
+    });
+  if (!lock.acquired) {
+    return;
+  }
+  process.once('exit', lock.release);
+
+  if (command === 'client') {
+    if (args.slice(1).some(arg => arg === '--help' || arg === '-h' || arg === 'help')) {
+      printClientHelp();
+      return;
+    }
+    runClient(runtimeArgs, resolvedRole);
+    return;
+  }
+  if (command === 'hub' || command === 'manager') {
     if (args.slice(1).some(arg => arg === '--help' || arg === '-h' || arg === 'help')) {
       printHelp();
       return;
     }
-    await runManager(args.slice(1));
-    return;
-  }
-  await runManager(args);
-}
+    await runManager(runtimeArgs, resolvedRole);
+    return;
+  }
+  if (resolvedRole.role === 'client') {
+    runClient(runtimeArgs, resolvedRole);
+    return;
+  }
+  await runManager(runtimeArgs, resolvedRole);
+}
 
 main().catch(error => {
   console.error(error?.message || error);

package/bootstrap/device-role.js

@@ -0,0 +1,265 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import os from 'node:os';
+
+export const DEVICE_ROLES = Object.freeze(['hub', 'client']);
+export const DEFAULT_SUPABASE_URL = 'https://otbyfkjxrkngvjziawki.supabase.co';
+export const DEFAULT_SUPABASE_PUBLISHABLE_KEY = 'sb_publishable_NpUs0RDJH2YnllsqTKO6TQ_1jTdSsNQ';
+
+function safeString(value, maxLength = 256) {
+  return String(value ?? '').replace(/[\r\n\t]/g, ' ').trim().slice(0, maxLength);
+}
+
+function normalizeRole(value) {
+  const role = safeString(value, 20).toLowerCase();
+  return DEVICE_ROLES.includes(role) ? role : '';
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(value, null, 2));
+}
+
+function normalizeDeviceId(value) {
+  return safeString(value, 128).replace(/[^a-zA-Z0-9_.:-]/g, '-');
+}
+
+export function getRoleStatePaths(options = {}) {
+  const stateDir = options.stateDir || join(os.homedir(), '.livedesk');
+  const legacyClientStateDir = options.legacyClientStateDir || join(os.homedir(), '.livedesk-client');
+  return {
+    stateDir,
+    rolePath: join(stateDir, 'device-role.json'),
+    identityPath: join(stateDir, 'device.json'),
+    managerPath: join(stateDir, 'manager.json'),
+    legacyClientStateDir,
+    legacyClientIdentityPath: join(legacyClientStateDir, 'device.json'),
+    legacyClientAuthPath: join(legacyClientStateDir, 'auth.json'),
+    legacyClientPinPath: join(legacyClientStateDir, 'pin.json')
+  };
+}
+
+export function getStableDeviceIdentity(options = {}) {
+  const paths = getRoleStatePaths(options);
+  const existing = readJson(paths.identityPath);
+  const legacy = readJson(paths.legacyClientIdentityPath);
+  const deviceId = normalizeDeviceId(existing?.deviceId || legacy?.deviceId) || `livedesk-${randomUUID()}`;
+  const identity = {
+    deviceId,
+    deviceName: safeString(existing?.deviceName || legacy?.deviceName || os.hostname(), 160) || os.hostname(),
+    platform: process.platform,
+    arch: process.arch,
+    osVersion: safeString(os.release(), 160),
+    createdAt: existing?.createdAt || legacy?.createdAt || new Date().toISOString()
+  };
+
+  if (!existing || normalizeDeviceId(existing.deviceId) !== deviceId) {
+    writeJson(paths.identityPath, identity);
+  }
+  return identity;
+}
+
+export function readRoleCache(options = {}) {
+  const paths = getRoleStatePaths(options);
+  const cache = readJson(paths.rolePath);
+  const role = normalizeRole(cache?.role);
+  if (!role) {
+    return null;
+  }
+  return {
+    role,
+    deviceId: normalizeDeviceId(cache.deviceId),
+    deviceName: safeString(cache.deviceName, 160),
+    assignedHubId: safeString(cache.assignedHubId, 128),
+    roleVersion: Number.isInteger(cache.roleVersion) ? cache.roleVersion : 0,
+    source: cache.source === 'supabase' ? 'supabase' : 'local-cache',
+    verifiedAt: safeString(cache.verifiedAt, 64),
+    isOfflineFallback: cache.isOfflineFallback === true
+  };
+}
+
+export function writeRoleCache(resolved, options = {}) {
+  const role = normalizeRole(resolved?.role);
+  const deviceId = normalizeDeviceId(resolved?.deviceId);
+  if (!role || !deviceId) {
+    throw new Error('A valid device role and device id are required to write the LiveDesk role cache.');
+  }
+  const paths = getRoleStatePaths(options);
+  writeJson(paths.rolePath, {
+    deviceId,
+    deviceName: safeString(resolved.deviceName, 160),
+    role,
+    assignedHubId: safeString(resolved.assignedHubId, 128) || null,
+    roleVersion: Number.isInteger(resolved.roleVersion) ? resolved.roleVersion : 0,
+    source: resolved.source === 'supabase' ? 'supabase' : 'local-cache',
+    verifiedAt: safeString(resolved.verifiedAt, 64) || new Date().toISOString(),
+    isOfflineFallback: resolved.isOfflineFallback === true
+  });
+}
+
+function readSavedClientAccessToken(paths) {
+  const state = readJson(paths.legacyClientAuthPath);
+  const raw = state?.['livedesk.client.supabase.auth'];
+  if (typeof raw !== 'string' || !raw.trim()) {
+    return '';
+  }
+  const session = readJsonValue(raw);
+  return safeString(session?.access_token, 4096);
+}
+
+function readJsonValue(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+export async function querySupabaseDeviceRole({
+  deviceId,
+  accessToken,
+  fetchImpl = globalThis.fetch,
+  supabaseUrl = process.env.LIVEDESK_SUPABASE_URL || DEFAULT_SUPABASE_URL,
+  publishableKey = process.env.LIVEDESK_SUPABASE_PUBLISHABLE_KEY || DEFAULT_SUPABASE_PUBLISHABLE_KEY
+} = {}) {
+  const normalizedDeviceId = normalizeDeviceId(deviceId);
+  const token = safeString(accessToken, 4096);
+  if (!normalizedDeviceId || !token || typeof fetchImpl !== 'function') {
+    return { state: 'unavailable', reason: 'supabase-session-unavailable' };
+  }
+
+  const baseUrl = String(supabaseUrl || DEFAULT_SUPABASE_URL).replace(/\/+$/, '');
+  const query = new URLSearchParams({
+    select: 'device_id,device_name,role,assigned_hub_id,role_version,enabled',
+    device_id: `eq.${normalizedDeviceId}`,
+    limit: '1'
+  });
+  try {
+    const response = await fetchImpl(`${baseUrl}/rest/v1/livedesk_devices?${query.toString()}`, {
+      headers: {
+        apikey: publishableKey,
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json'
+      }
+    });
+    if (!response.ok) {
+      return { state: 'unavailable', reason: `supabase-device-query-${response.status}` };
+    }
+    const rows = await response.json();
+    const record = Array.isArray(rows) ? rows[0] : null;
+    if (!record || record.enabled === false) {
+      return { state: 'missing', reason: record ? 'device-disabled' : 'device-not-registered' };
+    }
+    const role = normalizeRole(record.role);
+    if (!role) {
+      return { state: 'unavailable', reason: 'invalid-server-role' };
+    }
+    return {
+      state: 'resolved',
+      role,
+      deviceId: normalizeDeviceId(record.device_id) || normalizedDeviceId,
+      deviceName: safeString(record.device_name, 160),
+      assignedHubId: safeString(record.assigned_hub_id, 128),
+      roleVersion: Number.isInteger(record.role_version) ? record.role_version : 0
+    };
+  } catch (error) {
+    return { state: 'unavailable', reason: safeString(error?.message || error, 240) };
+  }
+}
+
+export async function resolveDeviceRole({
+  forcedRole = '',
+  promptRole,
+  fetchImpl = globalThis.fetch,
+  accessToken = '',
+  ...pathOptions
+} = {}) {
+  const paths = getRoleStatePaths(pathOptions);
+  const identity = getStableDeviceIdentity(pathOptions);
+  const forced = normalizeRole(forcedRole);
+  if (forced) {
+    return {
+      role: forced,
+      deviceId: identity.deviceId,
+      deviceName: identity.deviceName,
+      roleVersion: 0,
+      source: 'forced',
+      isOfflineFallback: false,
+      identity
+    };
+  }
+
+  const token = safeString(accessToken, 4096)
+    || safeString(process.env.LIVEDESK_SUPABASE_ACCESS_TOKEN, 4096)
+    || readSavedClientAccessToken(paths);
+  const remote = await querySupabaseDeviceRole({ deviceId: identity.deviceId, accessToken: token, fetchImpl });
+  if (remote.state === 'resolved') {
+    const resolved = {
+      ...remote,
+      identity,
+      source: 'supabase',
+      isOfflineFallback: false,
+      verifiedAt: new Date().toISOString()
+    };
+    writeRoleCache(resolved, pathOptions);
+    return resolved;
+  }
+
+  if (remote.state === 'missing' && remote.reason === 'device-disabled') {
+    return {
+      role: '',
+      deviceId: identity.deviceId,
+      deviceName: identity.deviceName,
+      roleVersion: 0,
+      source: 'supabase',
+      isOfflineFallback: false,
+      disabled: true,
+      identity
+    };
+  }
+
+  const cached = readRoleCache(pathOptions);
+  if (cached && (!cached.deviceId || cached.deviceId === identity.deviceId)) {
+    return { ...cached, deviceId: identity.deviceId, deviceName: cached.deviceName || identity.deviceName, identity, isOfflineFallback: true };
+  }
+
+  const managerState = readJson(paths.managerPath);
+  if (safeString(managerState?.pairToken, 128)) {
+    const resolved = { role: 'hub', deviceId: identity.deviceId, deviceName: identity.deviceName, roleVersion: 0, source: 'local-cache', isOfflineFallback: true, identity };
+    writeRoleCache(resolved, pathOptions);
+    return resolved;
+  }
+
+  if (existsSync(paths.legacyClientAuthPath) || existsSync(paths.legacyClientPinPath)) {
+    const resolved = { role: 'client', deviceId: identity.deviceId, deviceName: identity.deviceName, roleVersion: 0, source: 'local-cache', isOfflineFallback: true, identity };
+    writeRoleCache(resolved, pathOptions);
+    return resolved;
+  }
+
+  const selectedRole = normalizeRole(typeof promptRole === 'function' ? await promptRole(identity) : '');
+  if (selectedRole) {
+    const resolved = { role: selectedRole, deviceId: identity.deviceId, deviceName: identity.deviceName, roleVersion: 0, source: 'local-cache', isOfflineFallback: false, identity };
+    writeRoleCache(resolved, pathOptions);
+    return resolved;
+  }
+
+  return {
+    role: '',
+    deviceId: identity.deviceId,
+    deviceName: identity.deviceName,
+    roleVersion: 0,
+    source: 'local-cache',
+    isOfflineFallback: remote.state === 'unavailable',
+    needsSelection: true,
+    identity
+  };
+}

package/bootstrap/runtime-lock.js

@@ -0,0 +1,59 @@
+import { existsSync, openSync, readFileSync, closeSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import os from 'node:os';
+
+function readLock(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 1) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== 'ESRCH';
+  }
+}
+
+export function getRuntimeLockPath(stateDir = join(os.homedir(), '.livedesk')) {
+  return join(stateDir, 'livedesk-runtime.lock');
+}
+
+export function acquireRuntimeLock({ stateDir, role = '', openExisting } = {}) {
+  const path = getRuntimeLockPath(stateDir);
+  const payload = {
+    pid: process.pid,
+    role: String(role || '').trim(),
+    startedAt: new Date().toISOString()
+  };
+
+  try {
+    const descriptor = openSync(path, 'wx');
+    writeFileSync(descriptor, JSON.stringify(payload, null, 2));
+    closeSync(descriptor);
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      try { unlinkSync(path); } catch { /* already released */ }
+    };
+    return { acquired: true, path, payload, release };
+  } catch (error) {
+    const existing = readLock(path);
+    if (!existing || !isProcessAlive(Number(existing.pid))) {
+      try { unlinkSync(path); } catch { /* another process may repair it */ }
+      return acquireRuntimeLock({ stateDir, role, openExisting });
+    }
+    if (typeof openExisting === 'function') {
+      openExisting(existing);
+    }
+    return { acquired: false, path, existing, error };
+  }
+}