workbite 0.1.12 → 0.1.14

package/lib/runtime.js

@@ -9,10 +9,12 @@ const fsSync = require('node:fs');
 const http = require('node:http');
 const net = require('node:net');
 const path = require('node:path');
+const { performance } = require('node:perf_hooks');
 const { spawn, execFile } = require('node:child_process');
 const { randomBytes, randomUUID } = require('node:crypto');
 const { fail, exists, safeDirectory, writeAtomic, readJson, readSmall, sha256, UUID, BACKEND_ID } = require('./common');
 const { bootIdentity, validBoot, previousBoot } = require('./boot-provenance');
+const { withLock } = require('./startup-lock');
 const { BUNDLE_V2 } = require('./install');
 const { protectPrivateDirectories } = require('./private-state');
 
@@ -107,24 +109,54 @@ function boundedText(text) {
   const line = String(text).split(/\r?\n/).map(value => value.trim()).filter(Boolean).pop() || '';
   return line.replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 300);
 }
-function runOnce(file, args, environment, timeout = 120000, execImpl = execFile) {
+const finiteTimeout = (value, fallback) => Number.isFinite(value) && value > 0 ? value : fallback;
+const remaining = deadline => Math.max(0, deadline - performance.now());
+// Bounds observation, not kernel filesystem I/O or the lifetime of an owned backend.
+async function beforeDeadline(action, deadline, message) {
+  const left = remaining(deadline);
+  if (!left) throw new Error(message);
+  let timer;
+  try {
+    const result = await Promise.race([Promise.resolve().then(action), new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(message)), left);
+    })]);
+    if (!remaining(deadline)) throw new Error(message);
+    return result;
+  } finally { clearTimeout(timer); }
+}
+function runOnce(file, args, environment, timeout = 120000, execImpl = execFile, options = {}) {
+  timeout = finiteTimeout(timeout, 120000);
   return new Promise(resolve => {
-    execImpl(file, args, { env: environment, shell: false, windowsHide: true, timeout, maxBuffer: 1024 * 1024, encoding: 'utf8' },
-      (error, stdout, stderr) => resolve({ error, stdout: stdout || '', stderr: stderr || '' }));
+    let child, settled = false;
+    const finish = (error, stdout, stderr) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ error, stdout: stdout || '', stderr: stderr || '' });
+    };
+    const timer = setTimeout(() => {
+      // A kill request is not proof of exit. Refuse with an unknown outcome; never retry.
+      finish(Object.assign(new Error('startup command timed out; outcome unknown'), { killed: true, code: 'ETIMEDOUT' }));
+      try { child?.kill('SIGKILL'); } catch { /* outcome remains unknown */ }
+    }, timeout);
+    try {
+      child = execImpl(file, args, { ...options, env: environment, shell: false, windowsHide: true, timeout,
+        maxBuffer: options.maxBuffer || 1024 * 1024, encoding: 'utf8' }, finish);
+    } catch (error) { finish(error); }
   });
 }
-async function initializeWorkspace(commands, workspace, environment) {
+async function initializeWorkspace(commands, workspace, environment, { timeout, execImpl } = {}) {
   if (await exists(path.join(workspace, 'workspace.json'))) fail('This folder is already a Work Stack workspace; open it without --init.');
   if (!await exists(workspace)) {
     try { await fs.mkdir(workspace, { mode: 0o700 }); } catch { fail('Cannot create the workspace folder; its parent folder must exist.'); }
   }
   const uid = randomUUID();
   const [file, ...prefix] = commands.workstack_engine;
-  const result = await runOnce(file, [...prefix, 'init', '--workspace', workspace, '--workspace-uid', uid], environment);
+  const result = await runOnce(file, [...prefix, 'init', '--workspace', workspace, '--workspace-uid', uid], environment, timeout, execImpl);
   let record;
   try { record = JSON.parse(result.stdout.trim()); } catch { record = null; }
   if (result.error || record?.state !== 'initialized' || record.workspace_uid !== uid) {
-    fail(`Work Stack init refused this folder: ${boundedText(result.stderr) || 'no ready record'}`);
+    fail(`Work Stack init refused this folder: ${result.error?.killed ? 'timed out; outcome unknown; inspect the workspace before opening again' : boundedText(result.stderr) || 'no ready record'}`);
   }
   return uid;
 }
@@ -185,31 +217,47 @@ function request(url, { method = 'GET', headers = {}, body, timeout = 5000 } = {
   const match = LOOPBACK.exec(url.origin);
   if (!match) return Promise.reject(new Error('not a loopback origin'));
   return new Promise((resolve, reject) => {
+    timeout = finiteTimeout(timeout, 5000);
+    let timer, responseStream, settled = false;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error) reject(error); else resolve(value);
+    };
     const payload = body === undefined ? undefined : Buffer.from(JSON.stringify(body));
-    const req = http.request(url, { method, agent: false, timeout,
+    const req = http.request(url, { method, agent: false,
       headers: { ...headers, ...(payload ? { 'Content-Type': 'application/json', 'Content-Length': payload.length } : {}) } },
     response => {
+      responseStream = response;
       const chunks = [];
       let size = 0;
-      response.on('data', chunk => { size += chunk.length; if (size > 1024 * 1024) req.destroy(); else chunks.push(chunk); });
+      response.on('data', chunk => {
+        size += chunk.length;
+        if (size > 1024 * 1024) abort(new Error('response too large')); else chunks.push(chunk);
+      });
       response.on('end', () => {
         let parsed = null;
         try { parsed = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { parsed = null; }
-        resolve({ status: response.statusCode, body: parsed });
+        finish(null, { status: response.statusCode, body: parsed });
       });
-      response.on('error', reject);
+      response.on('error', error => finish(error));
+      response.on('aborted', () => finish(new Error('response aborted')));
+      response.on('close', () => { if (!response.complete) finish(new Error('response closed before completion')); });
     });
-    req.on('timeout', () => req.destroy(new Error('request timed out')));
-    req.on('error', reject);
+    const abort = error => { finish(error); responseStream?.destroy(); req.destroy(); };
+    // A socket inactivity timeout can be extended forever by trickled bytes.
+    timer = setTimeout(() => abort(new Error('request timed out')), timeout);
+    req.on('error', error => finish(error));
     req.end(payload);
   });
 }
 
 // Owner identity is proven only by the private lifecycle token this WorkBite generated.
-async function engineIdentity(endpoint, token, workspaceUid) {
+async function engineIdentity(endpoint, token, workspaceUid, { timeout = 5000 } = {}) {
   if (typeof endpoint !== 'string' || !LOOPBACK.test(endpoint) || typeof token !== 'string' || !token) return false;
   try {
-    const answer = await request(new URL('/api/v1/native-runtime/identity', endpoint), { headers: { 'X-WorkStack-Native-Token': token } });
+    const answer = await request(new URL('/api/v1/native-runtime/identity', endpoint), { timeout, headers: { 'X-WorkStack-Native-Token': token } });
     return answer.status === 200 && answer.body?.data?.workspace_uid === workspaceUid && answer.body.data.protocol_version === 1;
   } catch { return false; }
 }
@@ -222,12 +270,14 @@ async function stackbiteToken(stateDir) {
   }
   return null;
 }
-async function stackbiteIdentity(url, stateDir, backendId) {
+async function stackbiteIdentity(url, stateDir, backendId, { timeout = 5000 } = {}) {
+  const deadline = performance.now() + finiteTimeout(timeout, 5000);
   if (typeof url !== 'string' || !LOOPBACK.test(url)) return false;
-  const token = await stackbiteToken(stateDir);
-  if (!token) return false;
   try {
-    const answer = await request(new URL('/api/backend/status', url), { headers: { 'X-Office-Token': token } });
+    const token = await beforeDeadline(() => stackbiteToken(stateDir), deadline, 'token read timed out');
+    if (!token) return false;
+    if (!remaining(deadline)) return false;
+    const answer = await request(new URL('/api/backend/status', url), { timeout: remaining(deadline), headers: { 'X-Office-Token': token } });
     return answer.status === 200 && answer.body?.status === 'ok' && answer.body.backend_id === backendId;
   } catch { return false; }
 }
@@ -258,17 +308,19 @@ function spawnDetached(command, args, { env, cwd, log, spawnImpl = spawn }) {
     return { child, exited };
   } finally { fsSync.closeSync(output); }
 }
-async function waitFor(probe, exited, timeout, what, log) {
+async function waitFor(probe, exited, timeout, what, log, deadline = performance.now() + timeout) {
   let ended = false;
   exited.then(() => { ended = true; });
-  const deadline = Date.now() + timeout;
-  while (Date.now() < deadline) {
-    const value = await probe();
+  const unknown = `${what} did not become ready in time; it was left running; startup outcome unknown, intent retained. See ${log}`;
+  while (remaining(deadline)) {
+    const value = await beforeDeadline(() => Promise.race([probe(remaining(deadline)), exited.then(() => {
+      fail(`${what} exited during startup; see ${log}`);
+    })]), deadline, unknown);
     if (value) return value;
     if (ended) fail(`${what} exited during startup; see ${log}`);
-    await new Promise(resolve => setTimeout(resolve, 150));
+    await new Promise(resolve => setTimeout(resolve, Math.min(150, remaining(deadline))));
   }
-  fail(`${what} did not become ready in time; it was left running. See ${log}`);
+  fail(unknown);
 }
 async function readyRecord(log) {
   let text;
@@ -324,10 +376,14 @@ async function archivePreviousRecord(file, saved, original, boot) {
   }
   return true;
 }
-function checkBoot(saved, recordPath) {
+function checkBoot(saved, recordPath, boot) {
   if (Object.hasOwn(saved, 'boot') && !validBoot(saved.boot)) {
     fail(`The startup boot provenance in ${recordPath} is invalid; WorkBite does not replace it.`);
   }
+  if (validBoot(saved.boot) && validBoot(boot) && saved.boot.host !== boot.host) {
+    fail(`The startup record ${recordPath} belongs to a foreign host; its process state is unknown and could not be authenticated locally. `
+      + 'No local endpoint or PID was probed; the record was retained. ' + RECOVERY);
+  }
 }
 // A v2 (execution UI) bundle reuses only processes its own startup intent marked: the owner needs
 // this bundle's execution commands, the StackBite backend its native launch opt-in (read once at
@@ -352,6 +408,7 @@ const executionFields = (execution, extra = {}) => (execution ? { execution_bund
 const NATIVE_LAUNCH = { native_launch: true };
 
 async function ensureEngine({ commands, workspace, uid, layout, environment, spawnImpl, timeout = 60000, execution = null, boot = null, identityImpl = engineIdentity }) {
+  timeout = finiteTimeout(timeout, 60000);
   const key = workspaceKey(workspace);
   const recordPath = path.join(layout.owners, `${key}.json`);
   const logFor = launch => path.join(layout.logs, `workstack-engine-${key}-${launch}.log`);
@@ -365,14 +422,15 @@ async function ensureEngine({ commands, workspace, uid, layout, environment, spa
         || (saved.state === 'ready' && (typeof saved.endpoint !== 'string' || !LOOPBACK.test(saved.endpoint)))) {
       fail(`The Work Stack owner record ${recordPath} is invalid for this workspace; WorkBite does not replace it. ${RECOVERY}`);
     }
-    checkBoot(saved, recordPath);
+    checkBoot(saved, recordPath, boot);
     requireExecutionMarker(saved, execution, recordPath, 'Work Stack owner');
     let endpoint = saved.state === 'ready' ? saved.endpoint : null;
     if (saved.state === 'starting') {
       const ready = await readyRecord(logFor(saved.launch));
       if (ready?.workspace_uid === uid && ready.protocol_version === 1) endpoint = ready.endpoint;
     }
-    if (!await identityImpl(endpoint, saved.token, uid)) {
+    if (!await beforeDeadline(() => identityImpl(endpoint, saved.token, uid, { timeout: Math.min(5000, timeout) }),
+      performance.now() + timeout, `Work Stack owner authentication timed out; outcome unknown; record retained: ${recordPath}; logs: ${layout.logs}`)) {
       if (!await archivePreviousRecord(recordPath, saved, original, boot))
         fail(`The Work Stack owner recorded in ${recordPath} could not be authenticated (still starting, or stopped). ${RECOVERY}`);
     } else {
@@ -390,14 +448,18 @@ async function ensureEngine({ commands, workspace, uid, layout, environment, spa
     ['serve', '--workspace', workspace, '--workspace-uid', uid, '--host', '127.0.0.1', '--port', '0', '--native-runtime-control'],
     { env: { ...environment, WORKSTACK_NATIVE_RUNTIME_TOKEN: intent.token }, cwd: layout.root, log, spawnImpl });
   await writeAtomic(recordPath, recordBytes({ ...intent, pid: child.pid }));
-  const ready = await waitFor(() => readyRecord(log), exited, timeout, 'Work Stack native owner', log);
+  const deadline = performance.now() + timeout;
+  const ready = await waitFor(() => readyRecord(log), exited, timeout, 'Work Stack native owner', log, deadline);
   if (ready.workspace_uid !== uid || ready.protocol_version !== 1 || !LOOPBACK.test(ready.endpoint)
-      || !await identityImpl(ready.endpoint, intent.token, uid)) fail(`Work Stack native owner identity was not proven; see ${log}`);
+      || !await beforeDeadline(() => identityImpl(ready.endpoint, intent.token, uid, { timeout: Math.min(5000, remaining(deadline)) }),
+        deadline, `Work Stack native owner identity timed out; outcome unknown; intent retained: ${recordPath}; see ${log}`))
+    fail(`Work Stack native owner identity was not proven; intent retained: ${recordPath}; see ${log}`);
   await writeAtomic(recordPath, recordBytes({ ...intent, pid: child.pid, state: 'ready', endpoint: ready.endpoint }));
   return { endpoint: ready.endpoint, reused: false, pid: child.pid };
 }
 
 async function ensureStackbite({ commands, layout, backendId, environment, spawnImpl, timeout = 120000, execution = null, boot = null, identityImpl = stackbiteIdentity }) {
+  timeout = finiteTimeout(timeout, 120000);
   const recordPath = layout.stackbiteRecord;
   const logFor = launch => path.join(layout.logs, `stackbite-backend-${launch}.log`);
   const snapshot = await savedRecord(recordPath, 'StackBite backend');
@@ -408,9 +470,10 @@ async function ensureStackbite({ commands, layout, backendId, environment, spawn
         || typeof saved.url !== 'string' || LOOPBACK.exec(saved.url)?.[1] !== String(saved.port)) {
       fail(`The StackBite backend record ${recordPath} is invalid for this state; WorkBite does not replace it. ${RECOVERY}`);
     }
-    checkBoot(saved, recordPath);
+    checkBoot(saved, recordPath, boot);
     requireExecutionMarker(saved, execution, recordPath, 'StackBite backend', NATIVE_LAUNCH);
-    if (!await identityImpl(saved.url, layout.stackbite, backendId)) {
+    if (!await beforeDeadline(() => identityImpl(saved.url, layout.stackbite, backendId, { timeout: Math.min(5000, timeout) }),
+      performance.now() + timeout, `StackBite backend authentication timed out; outcome unknown; record retained: ${recordPath}; logs: ${layout.logs}`)) {
       if (!await archivePreviousRecord(recordPath, saved, original, boot))
         fail(`The StackBite backend recorded in ${recordPath} could not be authenticated (still starting, or stopped). ${RECOVERY}`);
     } else {
@@ -439,7 +502,8 @@ async function ensureStackbite({ commands, layout, backendId, environment, spawn
       ...(execution ? { STACKBITE_WORKBITE_NATIVE_LAUNCH: '1' } : {}) }, home),
     cwd: home, log, spawnImpl });
   await writeAtomic(recordPath, recordBytes({ ...intent, pid: child.pid }));
-  await waitFor(() => identityImpl(url, layout.stackbite, backendId), exited, timeout, 'StackBite backend', log);
+  await waitFor(left => identityImpl(url, layout.stackbite, backendId, { timeout: Math.min(5000, left) }),
+    exited, timeout, 'StackBite backend', log);
   await writeAtomic(recordPath, recordBytes({ ...intent, pid: child.pid, state: 'ready' }));
   return { url, reused: false, pid: child.pid };
 }
@@ -453,14 +517,11 @@ const NATIVE_INIT_SCHEMA = 'stackbite.workbite-native-init.v1';
 async function initializeNativeRuntime({ commands, layout, url, environment, execImpl = execFile, timeout = 120000 }) {
   const home = path.dirname(commands.stackbite[commands.stackbite.length - 1]);
   const [file, ...prefix] = commands.stackbite;
-  const result = await new Promise(resolve => {
-    execImpl(file, [...prefix, '--workbite-native-init'], {
-      env: withPath({ ...environment, STACKBITE_HOME: home, STACKBITE_STATE_DIR: layout.stackbite,
+  const result = await runOnce(file, [...prefix, '--workbite-native-init'],
+      withPath({ ...environment, STACKBITE_HOME: home, STACKBITE_STATE_DIR: layout.stackbite,
         STACKBITE_BRIDGE_URL: url, STACKBITE_ROOM_BRIDGE_URL: url, STACKBITE_WORKBITE_NATIVE_LAUNCH: '1',
         PYINSTALLER_RESET_ENVIRONMENT: '1' }, home),
-      cwd: home, shell: false, windowsHide: true, timeout, maxBuffer: 64 * 1024, encoding: 'utf8',
-    }, (error, stdout, stderr) => resolve({ error, stdout: stdout || '', stderr: stderr || '' }));
-  });
+      timeout, execImpl, { cwd: home, maxBuffer: 64 * 1024 });
   const text = result.stdout.trim();
   let record = null;
   if (text && !/[\r\n]/.test(text) && text.length <= 4096) { try { record = JSON.parse(text); } catch { record = null; } }
@@ -481,32 +542,6 @@ async function writeDockConfig(layout, url) {
   if (!current || !current.equals(bytes)) await writeAtomic(layout.dock, bytes);
 }
 
-// One opener at a time per state; a lock older than the startup bound is set aside, never deleted.
-async function withLock(file, action, { wait = 180000, stale = 300000 } = {}) {
-  const deadline = Date.now() + wait;
-  let handle;
-  for (;;) {
-    try { handle = await fs.open(file, 'wx', 0o600); break; } catch (error) {
-      if (error.code !== 'EEXIST') throw error;
-      try {
-        if (Date.now() - (await fs.stat(file)).mtimeMs > stale) {
-          await fs.rename(file, `${file}.stale-${randomBytes(6).toString('hex')}`);
-          continue;
-        }
-      } catch (inner) { if (inner.code !== 'ENOENT') throw inner; continue; }
-      if (Date.now() > deadline) fail('Another WorkBite open is still starting this state; try again shortly.');
-      await new Promise(resolve => setTimeout(resolve, 200));
-    }
-  }
-  try {
-    await handle.writeFile(`${process.pid}\n`);
-    return await action();
-  } finally {
-    await handle.close();
-    await fs.unlink(file).catch(() => {});
-  }
-}
-
 // WB-EXEC-UI-V1 §4.4 device opt-in for 9 Execution, in WorkBite's own private settings file.
 // Written only when no execution_ui choice exists; a present choice (enabled or disabled, any
 // prefix) is kept byte for byte, and anything else there is refused, never repaired.
@@ -570,36 +605,50 @@ function typescriptExecutionEnvironment(layout, bridge) {
 }
 const verifiedPath = value => typeof value === 'string' && path.isAbsolute(value) && !/[\x00-\x1f]/.test(value);
 
-function uiEnvironment(base, { executables, layout, endpoint, uid, backendId, execution = null, bridge = null }) {
+function uiEnvironment(base, { executables, layout, endpoint, uid, backendId, execution = null, bridge = null, mobile = null }) {
   const home = path.dirname(executables.stackbite);
   return withPath({ ...base, WORKSTACK_TRANSPORT: 'native', WORKSTACK_NATIVE_CLIENT: executables.workstack_client,
     WORKSTACK_ENDPOINT: endpoint, WORKSTACK_WORKSPACE_UID: uid, WORKSTACK_STATE_DIR: layout.tuiState,
     WORKSTACK_EXECUTION_DOCK_CONFIG: layout.dock, WORKSTACK_EXECUTION_DOCK_BACKEND_ID: backendId,
     WORKSTACK_DEPLOY_JOURNAL_DIR: layout.journal, WORKSTACK_STACKBITE_EXECUTABLE: executables.stackbite,
     ...(execution ? { WORKSTACK_TUI_STATE: layout.tuiIntent, WORKSTACK_TUI_SETTINGS: layout.tuiSettings } : {}),
-    ...(bridge ? typescriptExecutionEnvironment(layout, bridge) : {}) }, home);
+    ...(bridge ? typescriptExecutionEnvironment(layout, bridge) : {}),
+    ...(mobile ? { WORKBITE_MOBILE_EXECUTABLE: executables.workbite_mobile,
+      WORKBITE_MOBILE_HOST: JSON.stringify(mobile) } : {}) }, home);
 }
 
-function runForeground(command, args, environment, { spawnImpl = spawn, signalSource = process } = {}) {
+function runForeground(command, args, environment, { spawnImpl = spawn, signalSource = process,
+  timeout = 30000, onStarted = () => {} } = {}) {
   return new Promise((resolve, reject) => {
     const [file, ...prefix] = command;
     const child = spawnImpl(file, [...prefix, ...args], { env: environment, stdio: 'inherit', shell: false });
+    let settled = false;
     const handlers = new Map();
     for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
       const handler = () => child.kill(signal);
       handlers.set(signal, handler);
       signalSource.on(signal, handler);
     }
-    const cleanup = () => { for (const [signal, handler] of handlers) signalSource.removeListener(signal, handler); };
-    child.once('error', () => { cleanup(); reject(new Error('Cannot start the verified Work Stack terminal UI')); });
-    child.once('exit', (code, signal) => { cleanup(); resolve({ code, signal }); });
+    const timer = setTimeout(() => {
+      settled = true;
+      cleanup();
+      reject(new Error('Work Stack terminal UI launch timed out; outcome unknown. No retry or fallback was attempted.'));
+    }, finiteTimeout(timeout, 30000));
+    const cleanup = () => {
+      clearTimeout(timer);
+      for (const [signal, handler] of handlers) signalSource.removeListener(signal, handler);
+    };
+    // Only launch acknowledgement is bounded. A successfully spawned UI runs until it exits.
+    child.once('spawn', () => { if (!settled) { clearTimeout(timer); onStarted(); } });
+    child.once('error', () => { settled = true; cleanup(); reject(new Error('Cannot start the verified Work Stack terminal UI')); });
+    child.once('exit', (code, signal) => { settled = true; cleanup(); resolve({ code, signal }); });
   });
 }
 
 // commands maps each bundle executable to its argv prefix; tests substitute fixtures.
 async function openSuite({ installed, commands, workspace, init = false, stateRoot, environment = process.env,
   ui = true, frontend = 'typescript', spawnImpl = spawn, execImpl = execFile, platform = process.platform,
-  stdout = process.stdout, timeouts = {}, bootImpl = bootIdentity }) {
+  stdout = process.stdout, stderr = process.stderr, timeouts = {}, bootImpl = bootIdentity, mobileBootstrap = undefined }) {
   if (!FRONTENDS.includes(frontend)) fail(`--frontend must be one of: ${FRONTENDS.join(', ')}`);
   if (workspace !== undefined) workspace = checkedWorkspace(workspace);
   else if (init) fail('--init needs --workspace ABS naming the new or empty folder');
@@ -621,39 +670,65 @@ async function openSuite({ installed, commands, workspace, init = false, stateRo
     fail('This WorkBite execution bundle has no verified execution bridge executable; nothing was started.');
   }
   const layout = stateLayout(path.resolve(stateRoot));
-  await prepareState(layout);
+  const stage = async (name, action) => {
+    stderr.write(`[workbite] ${name}: starting\n`);
+    try {
+      const value = await action();
+      stderr.write(`[workbite] ${name}: ready\n`);
+      return value;
+    } catch (error) {
+      if (error.workbiteStage) throw error;
+      stderr.write(`[workbite] ${name}: failed\n`);
+      const wrapped = new Error(`WorkBite startup stage "${name}" failed: ${error.message}; state: ${layout.root}; logs: ${layout.logs}`,
+        { cause: error });
+      wrapped.workbiteStage = name;
+      throw wrapped;
+    }
+  };
+  // Fixed stage names only: never print child environment, tokens or native stdout.
+  await stage('state preparation', () => prepareState(layout));
   const base = cleanEnvironment(environment);
+  const startupExec = (file, args, options, callback) => {
+    runOnce(file, args, options.env, options.timeout, execImpl, options)
+      .then(result => callback(result.error, result.stdout,
+        result.stderr || (result.error?.killed ? 'startup command timed out; outcome unknown' : '')));
+  };
   if (execution) {
     // The execution UI's intent parent and deploy journal, made private (Windows DACL) before any file in them is written.
-    await safeDirectory(layout.nativeTui);
-    await protectPrivateDirectories([layout.nativeTui, layout.journal], { platform, environment: base, execImpl });
+    await stage('private execution state', async () => {
+      await safeDirectory(layout.nativeTui);
+      await protectPrivateDirectories([layout.nativeTui, layout.journal], { platform, environment: base,
+        execImpl: startupExec, timeout: finiteTimeout(timeouts.privateState, 60000) });
+    });
   }
   const engineEnvironment = { ...base, WORK_STACK_RUNTIME: layout.workstackRuntime };
-  const session = await withLock(layout.lock, async () => {
+  const session = await stage('startup lock', () => withLock(layout.lock, async () => {
     let remembered = null;
     if (workspace === undefined) {
-      remembered = await rememberedWorkspace(layout);
+      remembered = await stage('workspace selection', () => rememberedWorkspace(layout));
       workspace = checkedWorkspace(remembered.workspace);
     }
     // Settings are settled before any workspace init or backend start, so a refused file changes nothing else.
-    const executionUi = execution ? await ensureExecutionSettings(layout.tuiSettings) : null;
-    const uid = init ? await initializeWorkspace(commands, workspace, engineEnvironment) : await readWorkspaceUid(workspace);
+    const executionUi = execution ? await stage('execution settings', () => ensureExecutionSettings(layout.tuiSettings)) : null;
+    const uid = await stage(init ? 'workspace initialization' : 'workspace identity', () => init
+      ? initializeWorkspace(commands, workspace, engineEnvironment, { timeout: timeouts.workspaceInit }) : readWorkspaceUid(workspace));
     if (remembered && uid !== remembered.uid) fail(`The workspace ${workspace} changed while opening. ${EXPLICIT}`);
-    const backendId = await ensureBackendId(layout);
-    const boot = await bootImpl({ platform, environment: base });
-    const engine = await ensureEngine({ commands, workspace, uid, layout, environment: engineEnvironment, spawnImpl,
-      timeout: timeouts.engine, execution, boot });
-    const stackbite = await ensureStackbite({ commands, layout, backendId, environment: base, spawnImpl,
-      timeout: timeouts.stackbite, execution, boot });
+    const backendId = await stage('backend identity', () => ensureBackendId(layout));
+    const boot = await stage('host boot provenance', () => beforeDeadline(() => bootImpl({ platform, environment: base }),
+      performance.now() + finiteTimeout(timeouts.boot, 10000), 'OS boot provenance timed out; no backend was started'));
+    const engine = await stage('Work Stack owner', () => ensureEngine({ commands, workspace, uid, layout, environment: engineEnvironment, spawnImpl,
+      timeout: timeouts.engine, execution, boot }));
+    const stackbite = await stage('StackBite backend', () => ensureStackbite({ commands, layout, backendId, environment: base, spawnImpl,
+      timeout: timeouts.stackbite, execution, boot }));
     if (execution) {
-      await initializeNativeRuntime({ commands, layout, url: stackbite.url, environment: base, execImpl,
-        timeout: timeouts.nativeInit });
+      await stage('native runtime selection', () => initializeNativeRuntime({ commands, layout, url: stackbite.url, environment: base, execImpl,
+        timeout: timeouts.nativeInit }));
     }
-    await writeDockConfig(layout, stackbite.url);
+    await stage('execution connection', () => writeDockConfig(layout, stackbite.url));
     // Only after the owner, StackBite and dock config are proven ready, and before the UI.
-    await rememberWorkspace(layout, workspace, uid);
+    await stage('workspace selection save', () => rememberWorkspace(layout, workspace, uid));
     return { uid, backendId, engine, stackbite, executionUi };
-  });
+  }));
   const summary = { schema: 'workbite.open.v1', workspace, workspace_uid: session.uid, endpoint: session.engine.endpoint,
     owner_reused: session.engine.reused, stackbite_url: session.stackbite.url, stackbite_reused: session.stackbite.reused,
     backend_id: session.backendId, state: layout.root, frontend,
@@ -665,14 +740,36 @@ async function openSuite({ installed, commands, workspace, init = false, stateRo
   const environmentForUi = uiEnvironment(base, { executables: installed.executables, layout, endpoint: session.engine.endpoint,
     uid: session.uid, backendId: session.backendId, execution: frontend === 'rust' ? execution : null,
     bridge: bridge && ['enabled', 'initialized'].includes(session.executionUi) ? bridge : null });
+  if (frontend === 'typescript' && platform === 'win32' && verifiedPath(installed.executables?.workbite_mobile)) {
+    const mobileRoot = path.join(layout.root, 'mobile');
+    await stage('private phone state', async () => {
+      await safeDirectory(mobileRoot);
+      await protectPrivateDirectories([mobileRoot], { platform, environment: base, execImpl: startupExec,
+        timeout: finiteTimeout(timeouts.privateState, 60000) });
+    });
+    environmentForUi.WORKBITE_MOBILE_EXECUTABLE = installed.executables.workbite_mobile;
+    environmentForUi.WORKBITE_MOBILE_HOST = JSON.stringify({
+      directory: path.join(mobileRoot, workspaceKey(workspace)), executable: installed.executables.workbite_mobile,
+      scope: { host_id: session.backendId, workspace_uid: session.uid },
+      native: { executable: installed.executables.workstack_client, cwd: workspace, endpoint: session.engine.endpoint,
+        workspaceUid: session.uid, deployment: { connection: layout.dock, backendId: session.backendId, journalDir: layout.journal } },
+      // Embedding hosts may supply the private operator invitation at first setup; never a token.
+      ...(mobileBootstrap ? { initialInput: mobileBootstrap } : {}),
+    });
+  }
   // Exactly one foreground child in this terminal (inherited stdio, never detached or a new console).
   // The TypeScript UI gets the v1 environment (keeping its own familiar settings file) plus, when the
   // v2 opt-in is enabled, only the WORKBITE_EXECUTION_* names above.
-  const result = await runForeground(commands[uiCommand], [], environmentForUi, { spawnImpl });
+  stderr.write('[workbite] terminal UI launch: starting\n');
+  const result = await runForeground(commands[uiCommand], [], environmentForUi, { spawnImpl, timeout: timeouts.uiLaunch,
+    onStarted: () => stderr.write('[workbite] terminal UI launch: ready\n') }).catch(error => {
+    stderr.write('[workbite] terminal UI launch: failed\n');
+    throw new Error(`WorkBite startup stage "terminal UI launch" failed: ${error.message}; state: ${layout.root}; logs: ${layout.logs}`, { cause: error });
+  });
   return { ...result, summary };
 }
 
 module.exports = { cleanEnvironment, stateLayout, prepareState, ensureBackendId, workspaceKey, readWorkspaceUid,
   initializeWorkspace, engineIdentity, stackbiteIdentity, freePort, ensureEngine, ensureStackbite, writeDockConfig,
   withLock, uiEnvironment, openSuite, rememberedWorkspace, ensureExecutionSettings, initializeNativeRuntime, RESERVED_PORTS,
-  SELECTION_SCHEMA, EXECUTION_UI_DEFAULT, NATIVE_INIT_SCHEMA, FRONTENDS };
+  SELECTION_SCHEMA, EXECUTION_UI_DEFAULT, NATIVE_INIT_SCHEMA, FRONTENDS, runForeground };

package/lib/startup-lock.js

@@ -0,0 +1,71 @@
+'use strict';
+const fs = require('node:fs/promises');
+const fsSync = require('node:fs');
+const os = require('node:os');
+const { randomBytes } = require('node:crypto');
+const { performance } = require('node:perf_hooks');
+
+function sameFile(a, b) {
+  // An unavailable/zero inode is not sufficient evidence to remove anything.
+  return a.isFile() && b.isFile() && a.ino !== 0n && a.ino === b.ino
+    && a.dev === b.dev && a.birthtimeNs === b.birthtimeNs && b.nlink === 1n;
+}
+
+function releaseOwned(file, handle, identity, bytes) {
+  try {
+    // Keep the descriptor open so its inode cannot be recycled. Read through
+    // that descriptor, never a pathname that could now point at a symlink.
+    // Synchronous checks avoid yielding to other JS before the final unlink.
+    // Node has no atomic compare-and-unlink: external actors must not mutate
+    // the lock directory during release. Cooperating callers never reclaim it.
+    if (!sameFile(identity, fsSync.fstatSync(handle.fd, { bigint: true }))) return;
+    const actual = Buffer.alloc(bytes.length + 1);
+    const count = fsSync.readSync(handle.fd, actual, 0, actual.length, 0);
+    if (count !== bytes.length || !actual.subarray(0, count).equals(bytes)) return;
+    if (!sameFile(identity, fsSync.lstatSync(file, { bigint: true }))) return;
+    fsSync.unlinkSync(file);
+  } catch {
+    // Missing, unreadable or unprovable ownership stays closed; cleanup must
+    // not hide the action's result/error or remove another caller's lock.
+  }
+}
+
+// `stale` in older callers' options is intentionally ignored. Neither age nor
+// a locally absent PID proves a lock owner on shared storage has stopped.
+async function withLock(file, action, { wait = 180000 } = {}) {
+  if (!Number.isFinite(wait) || wait < 0) throw new RangeError('Lock wait must be a finite nonnegative number.');
+  const bytes = Buffer.from(JSON.stringify({ pid: process.pid, hostname: os.hostname().slice(0, 255),
+    boot: null, nonce: randomBytes(16).toString('hex') }) + '\n');
+  const deadline = performance.now() + wait;
+  let handle;
+  for (;;) {
+    try {
+      handle = await fs.open(file, 'wx+', 0o600);
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const remaining = deadline - performance.now();
+      if (remaining <= 0) {
+        const timeout = new Error(`Another WorkBite open may still be starting this state (lock: ${file}). `
+          + 'Run workbite status --json to inspect it, and retry after the owner finishes. '
+          + 'An old lock or a PID absent on this host does not prove that a shared-state owner has stopped; '
+          + 'WorkBite leaves the lock in place.');
+        timeout.code = 'WORKBITE_STARTUP_LOCK_TIMEOUT';
+        throw timeout;
+      }
+      await new Promise(resolve => setTimeout(resolve, Math.min(200, remaining)));
+    }
+  }
+
+  let identity;
+  try {
+    identity = await handle.stat({ bigint: true });
+    await handle.writeFile(bytes);
+    return await action();
+  } finally {
+    if (identity) releaseOwned(file, handle, identity, bytes);
+    await handle.close();
+  }
+}
+
+module.exports = { withLock };