workbite 0.1.22 → 0.1.24

package/lib/runtime.js

@@ -1,775 +1,775 @@
-'use strict';
-// WorkBite suite supervisor: starts or reuses the verified Work Stack native
-// owner and the StackBite room backend in WorkBite's own state, then runs the
-// Work Stack terminal UI in the foreground. Backends outlive the UI so agents
-// keep running; nothing here stops, adopts or kills a process it cannot
-// authenticate as its own.
-const fs = require('node:fs/promises');
-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');
-
-const BACKEND_SCHEMA = 'stackbite.workstack-backend.v1';
-const CONNECTION_SCHEMA = 'workstack.helm-connection.v1';
-const OWNER_SCHEMA = 'workbite.owner.v2';
-const STACKBITE_SCHEMA = 'workbite.stackbite-backend.v2';
-const SELECTION_SCHEMA = 'workbite.workspace-selection.v1';
-// Foreground UI per open: the familiar TypeScript Work Stack UI by default, the unified Rust UI on request.
-const FRONTENDS = Object.freeze(['typescript', 'rust']);
-const LOOPBACK = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})$/;
-// Ports of the existing official StackBite and its previews are never chosen.
-const RESERVED_PORTS = new Set([8089, 8090, 8091, 54036, 54039, 54236, 54239]);
-// Display preferences a child may keep (as Work Stack's viewer environment does);
-// every other STACKBITE_/HELM_/OFFICE_ variable is caller Room/Seat routing or auth.
-const PREFERENCES = new Set(['STACKBITE_CHROME_PROFILE', 'STACKBITE_CLIPBOARD_OSC52', 'STACKBITE_FRONTEND',
-  'STACKBITE_SCROLLBACK_LINES', 'STACKBITE_TERMINAL_CORE', 'STACKBITE_UPDATE_CHECK']);
-
-function cleanEnvironment(source = process.env) {
-  const result = {};
-  for (const [key, value] of Object.entries(source)) {
-    const upper = key.toUpperCase();
-    if (!key || value === undefined) continue;
-    if (/^(STACKBITE_|HELM_|OFFICE_)/.test(upper) && !PREFERENCES.has(upper)) continue;
-    if (/^(WORKSTACK_|WORK_STACK_|WORKBITE_)/.test(upper) || upper === 'PYINSTALLER_RESET_ENVIRONMENT') continue;
-    result[key] = value;
-  }
-  return result;
-}
-function withPath(environment, directory) {
-  const key = Object.keys(environment).find(name => name.toUpperCase() === 'PATH') || 'PATH';
-  const current = environment[key];
-  return { ...environment, [key]: current ? directory + path.delimiter + current : directory };
-}
-
-function stateLayout(root) {
-  return { root, stackbite: path.join(root, 'stackbite'), workstackRuntime: path.join(root, 'workstack-runtime'),
-    journal: path.join(root, 'deploy-journal'), tuiState: path.join(root, 'workstack-tui'), owners: path.join(root, 'owners'),
-    logs: path.join(root, 'logs'), dock: path.join(root, 'execution-dock.json'),
-    stackbiteRecord: path.join(root, 'stackbite-backend.json'), lock: path.join(root, 'open.lock'),
-    selection: path.join(root, 'last-workspace.json'),
-    // v2 execution UI only: its private intent journal and device settings, never under a workspace.
-    nativeTui: path.join(root, 'workstack-native-tui'),
-    tuiIntent: path.join(root, 'workstack-native-tui', 'intent.json'),
-    tuiSettings: path.join(root, 'workstack-native-tui', 'tui.json') };
-}
-async function prepareState(layout) {
-  for (const directory of [layout.root, layout.stackbite, layout.workstackRuntime, layout.journal, layout.tuiState,
-    layout.owners, layout.logs]) await safeDirectory(directory);
-}
-
-// The operator pin StackBite reads from <state>/workstack-backend.json; generated once, never replaced.
-async function ensureBackendId(layout) {
-  const file = path.join(layout.stackbite, 'workstack-backend.json');
-  if (!await exists(file)) {
-    const backendId = `workbite-${randomBytes(12).toString('hex')}`;
-    const bytes = Buffer.from(JSON.stringify({ schema: BACKEND_SCHEMA, backend_id: backendId }) + '\n');
-    try {
-      const handle = await fs.open(file, 'wx', 0o600);
-      try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
-    } catch (error) { if (error.code !== 'EEXIST') throw error; }
-  }
-  let document;
-  try { document = await readJson(file, 4096); } catch { fail('WorkBite StackBite backend identity file is unreadable; inspect it rather than replacing it.'); }
-  if (document === null || typeof document !== 'object' || Array.isArray(document) || Object.keys(document).length !== 2
-      || document.schema !== BACKEND_SCHEMA || typeof document.backend_id !== 'string' || !BACKEND_ID.test(document.backend_id)) {
-    fail('WorkBite StackBite backend identity file is invalid; inspect it rather than replacing it.');
-  }
-  return document.backend_id;
-}
-
-function workspaceKey(workspace, platform = process.platform) {
-  return sha256(Buffer.from(platform === 'win32' ? workspace.toLowerCase() : workspace)).slice(0, 24);
-}
-function checkedWorkspace(value) {
-  if (typeof value !== 'string' || !path.isAbsolute(value) || /[\x00-\x1f]/.test(value)
-      || (process.platform === 'win32' && /^[\\/](?![\\/])/.test(value))) fail('--workspace must be an absolute path');
-  return path.resolve(value);
-}
-// The genuine Work Stack descriptor: workspace.json "id". Nothing is fabricated or repaired.
-async function readWorkspaceUid(workspace) {
-  const descriptor = path.join(workspace, 'workspace.json');
-  if (!await exists(descriptor)) fail('This folder is not a Work Stack workspace (no workspace.json). Use --init only for a new or empty folder.');
-  let document;
-  try { document = await readJson(descriptor, 1024 * 1024); } catch { fail('workspace.json is unreadable or not JSON; WorkBite does not repair it.'); }
-  const uid = document?.id;
-  if (typeof uid !== 'string' || !UUID.test(uid)) fail('workspace.json has no canonical workspace UUID id.');
-  return uid;
-}
-
-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);
-}
-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 => {
-    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, { 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, 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: ${result.error?.killed ? 'timed out; outcome unknown; inspect the workspace before opening again' : boundedText(result.stderr) || 'no ready record'}`);
-  }
-  return uid;
-}
-
-// The workspace a bare `workbite` reopens: the last one opened successfully, or, for
-// state from 0.1.0 with no saved selection, the single owner record it holds. It is
-// never guessed (no CWD, mtime or default folder) and never silently replaced by
-// another workspace; the genuine workspace.json id must still match.
-const EXPLICIT = 'Open it once with: workbite open --workspace ABS';
-async function currentUid(workspace, what) {
-  try { return await readWorkspaceUid(workspace); } catch (error) {
-    fail(`The ${what} ${workspace} is missing, moved or no longer a valid Work Stack workspace (${error.message}) ${EXPLICIT}`);
-  }
-}
-async function rememberedWorkspace(layout) {
-  let saved;
-  try { saved = await readJson(layout.selection, 8192); } catch (error) {
-    if (error.code !== 'ENOENT') fail(`The saved workspace selection ${layout.selection} is unreadable. ${EXPLICIT}`);
-    return ownerWorkspace(layout);
-  }
-  if (saved === null || typeof saved !== 'object' || Array.isArray(saved) || Object.keys(saved).length !== 3
-      || saved.schema !== SELECTION_SCHEMA || typeof saved.workspace !== 'string' || !path.isAbsolute(saved.workspace)
-      || typeof saved.workspace_uid !== 'string' || !UUID.test(saved.workspace_uid)) {
-    fail(`The saved workspace selection ${layout.selection} is invalid. ${EXPLICIT}`);
-  }
-  if (await currentUid(saved.workspace, 'last opened workspace') !== saved.workspace_uid) {
-    fail(`The last opened workspace ${saved.workspace} was replaced (its workspace.json id changed); WorkBite does not open it silently. ${EXPLICIT}`);
-  }
-  return { workspace: saved.workspace, uid: saved.workspace_uid };
-}
-async function ownerWorkspace(layout) {
-  let names = [];
-  try { names = (await fs.readdir(layout.owners)).filter(name => /^[0-9a-f]{24}\.json$/.test(name)); } catch (error) {
-    if (error.code !== 'ENOENT') fail(`WorkBite owner records are unreadable. ${EXPLICIT}`);
-  }
-  if (!names.length) fail(`No workspace has been opened yet. ${EXPLICIT} (add --init for a new or empty folder).`);
-  if (names.length > 1) fail(`WorkBite has ${names.length} workspace owner records and will not guess which one to open. ${EXPLICIT}`);
-  const file = path.join(layout.owners, names[0]);
-  let record;
-  try { record = await readJson(file); } catch { fail(`The Work Stack owner record ${file} is unreadable. ${EXPLICIT}`); }
-  if (!isRecord(record) || record.schema !== OWNER_SCHEMA || typeof record.workspace !== 'string' || !path.isAbsolute(record.workspace)
-      || `${workspaceKey(record.workspace)}.json` !== names[0] || typeof record.workspace_uid !== 'string' || !UUID.test(record.workspace_uid)) {
-    fail(`The Work Stack owner record ${file} is not a valid owner record. ${EXPLICIT}`);
-  }
-  if (await currentUid(record.workspace, 'workspace recorded in the owner record') !== record.workspace_uid) {
-    fail(`The workspace recorded in ${file} was replaced (its workspace.json id changed); WorkBite does not open it silently. ${EXPLICIT}`);
-  }
-  return { workspace: record.workspace, uid: record.workspace_uid };
-}
-async function rememberWorkspace(layout, workspace, uid) {
-  const bytes = Buffer.from(JSON.stringify({ schema: SELECTION_SCHEMA, workspace, workspace_uid: uid }, null, 2) + '\n');
-  let current = null;
-  try { current = await readSmall(layout.selection, 8192); } catch { current = null; }
-  if (!current || !current.equals(bytes)) await writeAtomic(layout.selection, bytes);
-}
-
-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,
-      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) 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; }
-        finish(null, { status: response.statusCode, body: parsed });
-      });
-      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')); });
-    });
-    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, { 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), { 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; }
-}
-async function stackbiteToken(stateDir) {
-  for (const name of ['.stackbite_secret_token', '.office_secret_token']) {
-    try {
-      const token = (await readSmall(path.join(stateDir, name), 4096)).toString('utf8').trim();
-      if (token && /^[\x20-\x7e]+$/.test(token)) return token;
-    } catch (error) { if (error.code !== 'ENOENT') return null; }
-  }
-  return null;
-}
-async function stackbiteIdentity(url, stateDir, backendId, { timeout = 5000 } = {}) {
-  const deadline = performance.now() + finiteTimeout(timeout, 5000);
-  if (typeof url !== 'string' || !LOOPBACK.test(url)) return false;
-  try {
-    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; }
-}
-
-async function freePort(excluded = RESERVED_PORTS) {
-  for (let attempt = 0; attempt < 20; attempt++) {
-    const port = await new Promise((resolve, reject) => {
-      const server = net.createServer();
-      server.once('error', reject);
-      server.listen(0, '127.0.0.1', () => { const { port: chosen } = server.address(); server.close(() => resolve(chosen)); });
-    });
-    if (!excluded.has(port)) return port;
-  }
-  fail('No free loopback port is available');
-}
-
-function spawnDetached(command, args, { env, cwd, log, spawnImpl = spawn }) {
-  const output = fsSync.openSync(log, 'a', 0o600);
-  try {
-    const [file, ...prefix] = command;
-    const child = spawnImpl(file, [...prefix, ...args], { env, cwd, detached: true, windowsHide: true, shell: false,
-      stdio: ['ignore', output, output] });
-    const exited = new Promise(resolve => {
-      child.once('exit', code => resolve({ code }));
-      child.once('error', () => resolve({ code: null }));
-    });
-    child.unref();
-    return { child, exited };
-  } finally { fsSync.closeSync(output); }
-}
-async function waitFor(probe, exited, timeout, what, log, deadline = performance.now() + timeout) {
-  let ended = false;
-  exited.then(() => { ended = true; });
-  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, Math.min(150, remaining(deadline))));
-  }
-  fail(unknown);
-}
-async function readyRecord(log) {
-  let text;
-  try { text = (await readSmall(log, 1024 * 1024)).toString('utf8'); } catch { return null; }
-  for (const line of text.split(/\r?\n/)) {
-    try {
-      const value = JSON.parse(line);
-      if (value?.state === 'ready') return value;
-    } catch { /* not the ready line */ }
-  }
-  return null;
-}
-
-// Startup intent (private token, launch id, port) is saved before any child is
-// spawned, so an attempt that timed out or crashed is never followed by a second
-// manager on the same state: a later open either authenticates that same attempt
-// or refuses. Proven previous-boot records are archived; nothing is stopped automatically.
-const RECOVERY = 'WorkBite never starts a second one on the same state. If it is still starting, open again shortly; '
-  + 'if you have confirmed no process from this state is running, move that record aside and open again.';
-const LAUNCH = /^[0-9a-f]{16}$/;
-// Distinct from every JSON value (including null): only an absent file is "missing".
-const MISSING = Symbol('missing record');
-async function savedRecord(file, what) {
-  try {
-    const bytes = await readSmall(file, 65536);
-    return { record: JSON.parse(bytes.toString('utf8')), bytes };
-  } catch (error) {
-    if (error.code === 'ENOENT') return MISSING;
-    fail(`The ${what} record ${file} is unreadable; WorkBite does not replace it. ${RECOVERY}`);
-  }
-}
-const isRecord = value => value !== null && typeof value === 'object' && !Array.isArray(value)
-  && (value.state === 'starting' || value.state === 'ready') && typeof value.launch === 'string' && LAUNCH.test(value.launch);
-const recordBytes = value => Buffer.from(JSON.stringify(value, null, 2) + '\n');
-
-// Called under open.lock. Compare the exact bytes, retain a private backup before
-// renaming the record, and refuse if it changed. Logs and native intent stay put.
-async function archivePreviousRecord(file, saved, original, boot) {
-  if (!previousBoot(saved.boot, boot)) return false;
-  const current = await readSmall(file, 65536);
-  if (!current.equals(original)) fail('Startup record changed during recovery; refusing another launch.');
-  const backup = `${file}.previous-boot-${randomBytes(12).toString('hex')}`;
-  await fs.copyFile(file, backup, fsSync.constants.COPYFILE_EXCL);
-  if (!(await readSmall(backup, 65536)).equals(original)
-      || !(await readSmall(file, 65536)).equals(original)) {
-    fail('Startup record changed during recovery; backup retained, launch refused.');
-  }
-  // The rename retains the original record's ACL. A separate backup survives a
-  // crash before the new current-boot intent is persisted.
-  await fs.rename(file, `${backup}.record`);
-  if (!(await readSmall(`${backup}.record`, 65536)).equals(original)) {
-    fail('Startup record changed during quarantine; archived evidence retained, launch refused.');
-  }
-  return true;
-}
-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
-// startup). A matching token or UID alone is not that proof. Checked from the record before any
-// network contact; the record is kept and nothing is stopped. A v1 bundle never checks or writes it.
-const HANDOVER = 'Operator handover needed: WorkBite never stops, adopts or replaces it. Close the UIs using it, '
-  + 'stop that process yourself (its pid is in the record), move the record aside and open again; WorkBite then '
-  + 'starts a new one from this bundle.';
-const shown = value => (typeof value === 'string' ? JSON.stringify(value.slice(0, 40)) : value === undefined ? 'absent' : 'invalid');
-function requireExecutionMarker(saved, execution, recordPath, what, extra = {}) {
-  if (!execution) return;
-  const missing = saved.execution_bundle_version !== execution.bundleVersion
-    || Object.entries(extra).some(([key, value]) => saved[key] !== value);
-  if (missing) {
-    fail(`The ${what} recorded in ${recordPath} was not started by the WorkBite ${execution.bundleVersion} execution bundle `
-      + `(execution_bundle_version ${shown(saved.execution_bundle_version)}`
-      + Object.keys(extra).map(key => `, ${key} ${saved[key] === undefined ? 'absent' : JSON.stringify(saved[key])}`).join('')
-      + `), so it cannot serve 9 Execution. ${HANDOVER}`);
-  }
-}
-const executionFields = (execution, extra = {}) => (execution ? { execution_bundle_version: execution.bundleVersion, ...extra } : {});
-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`);
-  const snapshot = await savedRecord(recordPath, 'Work Stack owner');
-  const saved = snapshot === MISSING ? MISSING : snapshot.record;
-  const original = snapshot === MISSING ? null : snapshot.bytes;
-  if (saved !== MISSING) {
-    if (!isRecord(saved) || saved.schema !== OWNER_SCHEMA || typeof saved.workspace !== 'string'
-        || workspaceKey(saved.workspace) !== key || saved.workspace_uid !== uid
-        || typeof saved.token !== 'string' || !/^[0-9a-f]{64}$/.test(saved.token)
-        || (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, 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 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 {
-      if (saved.state === 'starting' || validBoot(boot))
-        await writeAtomic(recordPath, recordBytes({ ...saved, ...(validBoot(boot) ? { boot } : {}), state: 'ready', endpoint }));
-      return { endpoint, reused: true, pid: saved.pid };
-    }
-  }
-  if (!validBoot(boot)) fail('Trusted OS boot provenance is unavailable; no owner was started.');
-  const intent = { boot, schema: OWNER_SCHEMA, state: 'starting', workspace, workspace_uid: uid,
-    launch: randomBytes(8).toString('hex'), token: randomBytes(32).toString('hex'), ...executionFields(execution) };
-  const log = logFor(intent.launch);
-  await writeAtomic(recordPath, recordBytes(intent));
-  const { child, exited } = spawnDetached(commands.workstack_engine,
-    ['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 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 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');
-  const saved = snapshot === MISSING ? MISSING : snapshot.record;
-  const original = snapshot === MISSING ? null : snapshot.bytes;
-  if (saved !== MISSING) {
-    if (!isRecord(saved) || saved.schema !== STACKBITE_SCHEMA || saved.backend_id !== backendId
-        || 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, boot);
-    requireExecutionMarker(saved, execution, recordPath, 'StackBite backend', NATIVE_LAUNCH);
-    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 {
-      if (saved.state === 'starting' || validBoot(boot))
-        await writeAtomic(recordPath, recordBytes({ ...saved, ...(validBoot(boot) ? { boot } : {}), state: 'ready' }));
-      return { url: saved.url, reused: true, pid: saved.pid };
-    }
-  }
-  if (!validBoot(boot)) fail('Trusted OS boot provenance is unavailable; no backend was started.');
-  const port = await freePort();
-  const url = `http://127.0.0.1:${port}`;
-  const intent = { boot, schema: STACKBITE_SCHEMA, state: 'starting', backend_id: backendId, launch: randomBytes(8).toString('hex'), url, port,
-    ...executionFields(execution, NATIVE_LAUNCH) };
-  const log = logFor(intent.launch);
-  const home = path.dirname(commands.stackbite[commands.stackbite.length - 1]);
-  await writeAtomic(recordPath, recordBytes(intent));
-  // The private Python terminal core and this backend's own loopback bridge are
-  // mandatory for the room backend (taskrooms reads STACKBITE_BRIDGE_URL; the agent
-  // CLI and frontend read STACKBITE_ROOM_BRIDGE_URL); caller values are overridden here only.
-  // A v2 bundle also starts it with the WorkBite native launch opt-in (cleanEnvironment drops any
-  // caller value, so a v1 backend never gets it); STACKBITE_HOME lets it resolve the bundle's native assets.
-  const { child, exited } = spawnDetached(commands.stackbite, ['--room-backend', '--port', String(port)], {
-    env: withPath({ ...environment, STACKBITE_HOME: home, STACKBITE_STATE_DIR: layout.stackbite,
-      STACKBITE_PTY_BACKEND: 'private', STACKBITE_ROOM_BACKEND: '1', STACKBITE_TERMINAL_CORE: 'python',
-      STACKBITE_BRIDGE_URL: url, STACKBITE_ROOM_BRIDGE_URL: url, PYINSTALLER_RESET_ENVIRONMENT: '1',
-      ...(execution ? { STACKBITE_WORKBITE_NATIVE_LAUNCH: '1' } : {}) }, home),
-    cwd: home, log, spawnImpl });
-  await writeAtomic(recordPath, recordBytes({ ...intent, pid: child.pid }));
-  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 };
-}
-
-// v2 only, after this backend's identity is proven: one headless `stackbite --workbite-native-init`
-// selects (or, through StackBite's own durable coordinator, reuses) the native terminal daemon for
-// this backend. No UI, window, Room or Seat; exactly one exit-0 selected record is accepted.
-// Anything else (refused, Unknown, malformed, timed out) refuses the open: WorkBite never retries,
-// starts another daemon or falls back, and a later open asks the same coordinator again.
-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 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),
-      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; } }
-  if (result.error || record === null || typeof record !== 'object' || Array.isArray(record) || Object.keys(record).length !== 2
-      || record.schema !== NATIVE_INIT_SCHEMA || record.status !== 'selected') {
-    const exit = result.error ? (result.error.killed ? 'timed out' : `exit ${result.error.code ?? 'unknown'}`) : 'no selected record';
-    fail(`StackBite native runtime initialization did not select a native runtime (${exit}: ${boundedText(result.stderr) || 'no reason'}); `
-      + 'the execution UI was not started. WorkBite does not retry, start another daemon or fall back; '
-      + 'if the outcome is unknown, open again later and StackBite looks the same selection up.');
-  }
-  return record.status;
-}
-
-async function writeDockConfig(layout, url) {
-  const bytes = Buffer.from(JSON.stringify({ schema: CONNECTION_SCHEMA, base_url: url, state_dir: layout.stackbite }, null, 2) + '\n');
-  let current = null;
-  try { current = await readSmall(layout.dock, 65536); } catch { current = null; }
-  if (!current || !current.equals(bytes)) await writeAtomic(layout.dock, bytes);
-}
-
-// 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.
-const EXECUTION_UI_SCHEMA = 'workbite.execution-ui-settings.v1';
-const EXECUTION_UI_DEFAULT = Object.freeze({ schema: EXECUTION_UI_SCHEMA, enabled: true, prefix: 'ctrl+]', last_view_execution: false });
-const SETTINGS_FIX = 'WorkBite does not repair or replace it; fix it or move it aside and open again.';
-function validExecutionUi(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 4
-    && value.schema === EXECUTION_UI_SCHEMA && typeof value.enabled === 'boolean' && typeof value.prefix === 'string'
-    && typeof value.last_view_execution === 'boolean';
-}
-// Same-directory temporary file published by hard link: never replaces a file another writer created.
-async function publishNew(file, bytes) {
-  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${randomBytes(8).toString('hex')}.tmp`);
-  const handle = await fs.open(temporary, 'wx', 0o600);
-  try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
-  try { await fs.link(temporary, file); return true; } catch (error) {
-    if (error.code !== 'EEXIST') throw error;
-    return false;
-  } finally { await fs.unlink(temporary); }
-}
-async function ensureExecutionSettings(file, attempt = 0) {
-  let bytes = null;
-  try { bytes = await readSmall(file, 1024 * 1024); } catch (error) {
-    if (error.code !== 'ENOENT') fail(`The execution UI settings ${file} are unreadable. ${SETTINGS_FIX}`);
-  }
-  if (bytes === null) {
-    const created = await publishNew(file, Buffer.from(JSON.stringify({ execution_ui: EXECUTION_UI_DEFAULT }, null, 2) + '\n'));
-    if (created) return 'initialized';
-    if (attempt) fail(`The execution UI settings ${file} keep changing while opening. ${SETTINGS_FIX}`);
-    return ensureExecutionSettings(file, attempt + 1);
-  }
-  let document;
-  try {
-    const text = bytes.toString('utf8');
-    document = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
-  } catch { fail(`The execution UI settings ${file} are not valid JSON. ${SETTINGS_FIX}`); }
-  if (document === null || typeof document !== 'object' || Array.isArray(document)) {
-    fail(`The execution UI settings ${file} are not a JSON object. ${SETTINGS_FIX}`);
-  }
-  if (!Object.hasOwn(document, 'execution_ui')) {
-    // Other settings are kept; only the missing opt-in is added.
-    await writeAtomic(file, Buffer.from(JSON.stringify({ ...document, execution_ui: EXECUTION_UI_DEFAULT }, null, 2) + '\n'));
-    return 'initialized';
-  }
-  if (!validExecutionUi(document.execution_ui)) {
-    fail(`The execution UI settings ${file} hold an execution_ui value that is not the exact four-key opt-in object `
-      + `(schema "${EXECUTION_UI_SCHEMA}", enabled, prefix, last_view_execution). ${SETTINGS_FIX}`);
-  }
-  return document.execution_ui.enabled ? 'enabled' : 'disabled';
-}
-
-// The TypeScript UI's same-window 9 Execution (docs/WORKBITE-TYPESCRIPT-EXECUTION-CONFIG.md): set only by
-// this launcher for a verified v2 bundle whose device opt-in is enabled. The bridge is the bundle's own
-// verified workbite_tui (run by the UI with its fixed --workbite-execution-bridge argv), never a caller,
-// receipt or PATH value; the UI keeps its own WORKSTACK_TUI_SETTINGS, so these names carry the private
-// execution settings and intent paths separately. cleanEnvironment drops any caller WORKBITE_ value first.
-function typescriptExecutionEnvironment(layout, bridge) {
-  return { WORKBITE_EXECUTION_UI: '1', WORKBITE_EXECUTION_BRIDGE: bridge,
-    WORKBITE_EXECUTION_SETTINGS: layout.tuiSettings, WORKBITE_EXECUTION_INTENT: layout.tuiIntent };
-}
-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, 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) : {}),
-    ...(mobile ? { WORKBITE_MOBILE_EXECUTABLE: executables.workbite_mobile,
-      WORKBITE_MOBILE_HOST: JSON.stringify(mobile) } : {}) }, home);
-}
-
-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 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, 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');
-  commands = commands || Object.fromEntries(Object.entries(installed.executables).map(([name, file]) => [name, [file]]));
-  // A v2 bundle keeps its owner/backend markers and native init whichever frontend runs; only the
-  // foreground UI differs. TypeScript is the default; rust needs a v2 bundle. There is no fallback between them.
-  const execution = installed.bundle?.schema === BUNDLE_V2 ? { bundleVersion: installed.bundle.version } : null;
-  if (frontend === 'rust' && !execution) {
-    fail('--frontend rust needs a WorkBite execution (v2) bundle; this installed bundle has only the TypeScript UI. Nothing was started.');
-  }
-  const uiCommand = frontend === 'rust' ? 'workbite_tui' : 'workstack_tui';
-  if (!(Array.isArray(commands[uiCommand]) && commands[uiCommand].length)) {
-    fail(frontend === 'rust' ? 'This WorkBite bundle has no verified execution UI executable; nothing was started.'
-      : 'This WorkBite bundle has no verified TypeScript UI executable; nothing was started.');
-  }
-  // A verified v2 bundle always holds the execution bridge; anything else is refused, never probed for.
-  const bridge = execution && frontend === 'typescript' ? installed.executables?.workbite_tui : null;
-  if (execution && frontend === 'typescript' && !verifiedPath(bridge)) {
-    fail('This WorkBite execution bundle has no verified execution bridge executable; nothing was started.');
-  }
-  const layout = stateLayout(path.resolve(stateRoot));
-  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 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 stage('startup lock', () => withLock(layout.lock, async () => {
-    let remembered = null;
-    if (workspace === undefined) {
-      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 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 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 stage('native runtime selection', () => initializeNativeRuntime({ commands, layout, url: stackbite.url, environment: base, execImpl,
-        timeout: timeouts.nativeInit }));
-    }
-    await stage('execution connection', () => writeDockConfig(layout, stackbite.url));
-    // Only after the owner, StackBite and dock config are proven ready, and before the UI.
-    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,
-    ...(execution ? { execution_ui: session.executionUi, execution_bundle_version: execution.bundleVersion } : {}) };
-  if (!ui) {
-    stdout.write(JSON.stringify(summary) + '\n');
-    return { code: 0, signal: null, summary };
-  }
-  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.
-  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, runForeground };
+'use strict';
+// WorkBite suite supervisor: starts or reuses the verified Work Stack native
+// owner and the StackBite room backend in WorkBite's own state, then runs the
+// Work Stack terminal UI in the foreground. Backends outlive the UI so agents
+// keep running; nothing here stops, adopts or kills a process it cannot
+// authenticate as its own.
+const fs = require('node:fs/promises');
+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');
+
+const BACKEND_SCHEMA = 'stackbite.workstack-backend.v1';
+const CONNECTION_SCHEMA = 'workstack.helm-connection.v1';
+const OWNER_SCHEMA = 'workbite.owner.v2';
+const STACKBITE_SCHEMA = 'workbite.stackbite-backend.v2';
+const SELECTION_SCHEMA = 'workbite.workspace-selection.v1';
+// Foreground UI per open: the familiar TypeScript Work Stack UI by default, the unified Rust UI on request.
+const FRONTENDS = Object.freeze(['typescript', 'rust']);
+const LOOPBACK = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})$/;
+// Ports of the existing official StackBite and its previews are never chosen.
+const RESERVED_PORTS = new Set([8089, 8090, 8091, 54036, 54039, 54236, 54239]);
+// Display preferences a child may keep (as Work Stack's viewer environment does);
+// every other STACKBITE_/HELM_/OFFICE_ variable is caller Room/Seat routing or auth.
+const PREFERENCES = new Set(['STACKBITE_CHROME_PROFILE', 'STACKBITE_CLIPBOARD_OSC52', 'STACKBITE_FRONTEND',
+  'STACKBITE_SCROLLBACK_LINES', 'STACKBITE_TERMINAL_CORE', 'STACKBITE_UPDATE_CHECK']);
+
+function cleanEnvironment(source = process.env) {
+  const result = {};
+  for (const [key, value] of Object.entries(source)) {
+    const upper = key.toUpperCase();
+    if (!key || value === undefined) continue;
+    if (/^(STACKBITE_|HELM_|OFFICE_)/.test(upper) && !PREFERENCES.has(upper)) continue;
+    if (/^(WORKSTACK_|WORK_STACK_|WORKBITE_)/.test(upper) || upper === 'PYINSTALLER_RESET_ENVIRONMENT') continue;
+    result[key] = value;
+  }
+  return result;
+}
+function withPath(environment, directory) {
+  const key = Object.keys(environment).find(name => name.toUpperCase() === 'PATH') || 'PATH';
+  const current = environment[key];
+  return { ...environment, [key]: current ? directory + path.delimiter + current : directory };
+}
+
+function stateLayout(root) {
+  return { root, stackbite: path.join(root, 'stackbite'), workstackRuntime: path.join(root, 'workstack-runtime'),
+    journal: path.join(root, 'deploy-journal'), tuiState: path.join(root, 'workstack-tui'), owners: path.join(root, 'owners'),
+    logs: path.join(root, 'logs'), dock: path.join(root, 'execution-dock.json'),
+    stackbiteRecord: path.join(root, 'stackbite-backend.json'), lock: path.join(root, 'open.lock'),
+    selection: path.join(root, 'last-workspace.json'),
+    // v2 execution UI only: its private intent journal and device settings, never under a workspace.
+    nativeTui: path.join(root, 'workstack-native-tui'),
+    tuiIntent: path.join(root, 'workstack-native-tui', 'intent.json'),
+    tuiSettings: path.join(root, 'workstack-native-tui', 'tui.json') };
+}
+async function prepareState(layout) {
+  for (const directory of [layout.root, layout.stackbite, layout.workstackRuntime, layout.journal, layout.tuiState,
+    layout.owners, layout.logs]) await safeDirectory(directory);
+}
+
+// The operator pin StackBite reads from <state>/workstack-backend.json; generated once, never replaced.
+async function ensureBackendId(layout) {
+  const file = path.join(layout.stackbite, 'workstack-backend.json');
+  if (!await exists(file)) {
+    const backendId = `workbite-${randomBytes(12).toString('hex')}`;
+    const bytes = Buffer.from(JSON.stringify({ schema: BACKEND_SCHEMA, backend_id: backendId }) + '\n');
+    try {
+      const handle = await fs.open(file, 'wx', 0o600);
+      try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+    } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  }
+  let document;
+  try { document = await readJson(file, 4096); } catch { fail('WorkBite StackBite backend identity file is unreadable; inspect it rather than replacing it.'); }
+  if (document === null || typeof document !== 'object' || Array.isArray(document) || Object.keys(document).length !== 2
+      || document.schema !== BACKEND_SCHEMA || typeof document.backend_id !== 'string' || !BACKEND_ID.test(document.backend_id)) {
+    fail('WorkBite StackBite backend identity file is invalid; inspect it rather than replacing it.');
+  }
+  return document.backend_id;
+}
+
+function workspaceKey(workspace, platform = process.platform) {
+  return sha256(Buffer.from(platform === 'win32' ? workspace.toLowerCase() : workspace)).slice(0, 24);
+}
+function checkedWorkspace(value) {
+  if (typeof value !== 'string' || !path.isAbsolute(value) || /[\x00-\x1f]/.test(value)
+      || (process.platform === 'win32' && /^[\\/](?![\\/])/.test(value))) fail('--workspace must be an absolute path');
+  return path.resolve(value);
+}
+// The genuine Work Stack descriptor: workspace.json "id". Nothing is fabricated or repaired.
+async function readWorkspaceUid(workspace) {
+  const descriptor = path.join(workspace, 'workspace.json');
+  if (!await exists(descriptor)) fail('This folder is not a Work Stack workspace (no workspace.json). Use --init only for a new or empty folder.');
+  let document;
+  try { document = await readJson(descriptor, 1024 * 1024); } catch { fail('workspace.json is unreadable or not JSON; WorkBite does not repair it.'); }
+  const uid = document?.id;
+  if (typeof uid !== 'string' || !UUID.test(uid)) fail('workspace.json has no canonical workspace UUID id.');
+  return uid;
+}
+
+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);
+}
+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 => {
+    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, { 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, 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: ${result.error?.killed ? 'timed out; outcome unknown; inspect the workspace before opening again' : boundedText(result.stderr) || 'no ready record'}`);
+  }
+  return uid;
+}
+
+// The workspace a bare `workbite` reopens: the last one opened successfully, or, for
+// state from 0.1.0 with no saved selection, the single owner record it holds. It is
+// never guessed (no CWD, mtime or default folder) and never silently replaced by
+// another workspace; the genuine workspace.json id must still match.
+const EXPLICIT = 'Open it once with: workbite open --workspace ABS';
+async function currentUid(workspace, what) {
+  try { return await readWorkspaceUid(workspace); } catch (error) {
+    fail(`The ${what} ${workspace} is missing, moved or no longer a valid Work Stack workspace (${error.message}) ${EXPLICIT}`);
+  }
+}
+async function rememberedWorkspace(layout) {
+  let saved;
+  try { saved = await readJson(layout.selection, 8192); } catch (error) {
+    if (error.code !== 'ENOENT') fail(`The saved workspace selection ${layout.selection} is unreadable. ${EXPLICIT}`);
+    return ownerWorkspace(layout);
+  }
+  if (saved === null || typeof saved !== 'object' || Array.isArray(saved) || Object.keys(saved).length !== 3
+      || saved.schema !== SELECTION_SCHEMA || typeof saved.workspace !== 'string' || !path.isAbsolute(saved.workspace)
+      || typeof saved.workspace_uid !== 'string' || !UUID.test(saved.workspace_uid)) {
+    fail(`The saved workspace selection ${layout.selection} is invalid. ${EXPLICIT}`);
+  }
+  if (await currentUid(saved.workspace, 'last opened workspace') !== saved.workspace_uid) {
+    fail(`The last opened workspace ${saved.workspace} was replaced (its workspace.json id changed); WorkBite does not open it silently. ${EXPLICIT}`);
+  }
+  return { workspace: saved.workspace, uid: saved.workspace_uid };
+}
+async function ownerWorkspace(layout) {
+  let names = [];
+  try { names = (await fs.readdir(layout.owners)).filter(name => /^[0-9a-f]{24}\.json$/.test(name)); } catch (error) {
+    if (error.code !== 'ENOENT') fail(`WorkBite owner records are unreadable. ${EXPLICIT}`);
+  }
+  if (!names.length) fail(`No workspace has been opened yet. ${EXPLICIT} (add --init for a new or empty folder).`);
+  if (names.length > 1) fail(`WorkBite has ${names.length} workspace owner records and will not guess which one to open. ${EXPLICIT}`);
+  const file = path.join(layout.owners, names[0]);
+  let record;
+  try { record = await readJson(file); } catch { fail(`The Work Stack owner record ${file} is unreadable. ${EXPLICIT}`); }
+  if (!isRecord(record) || record.schema !== OWNER_SCHEMA || typeof record.workspace !== 'string' || !path.isAbsolute(record.workspace)
+      || `${workspaceKey(record.workspace)}.json` !== names[0] || typeof record.workspace_uid !== 'string' || !UUID.test(record.workspace_uid)) {
+    fail(`The Work Stack owner record ${file} is not a valid owner record. ${EXPLICIT}`);
+  }
+  if (await currentUid(record.workspace, 'workspace recorded in the owner record') !== record.workspace_uid) {
+    fail(`The workspace recorded in ${file} was replaced (its workspace.json id changed); WorkBite does not open it silently. ${EXPLICIT}`);
+  }
+  return { workspace: record.workspace, uid: record.workspace_uid };
+}
+async function rememberWorkspace(layout, workspace, uid) {
+  const bytes = Buffer.from(JSON.stringify({ schema: SELECTION_SCHEMA, workspace, workspace_uid: uid }, null, 2) + '\n');
+  let current = null;
+  try { current = await readSmall(layout.selection, 8192); } catch { current = null; }
+  if (!current || !current.equals(bytes)) await writeAtomic(layout.selection, bytes);
+}
+
+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,
+      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) 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; }
+        finish(null, { status: response.statusCode, body: parsed });
+      });
+      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')); });
+    });
+    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, { 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), { 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; }
+}
+async function stackbiteToken(stateDir) {
+  for (const name of ['.stackbite_secret_token', '.office_secret_token']) {
+    try {
+      const token = (await readSmall(path.join(stateDir, name), 4096)).toString('utf8').trim();
+      if (token && /^[\x20-\x7e]+$/.test(token)) return token;
+    } catch (error) { if (error.code !== 'ENOENT') return null; }
+  }
+  return null;
+}
+async function stackbiteIdentity(url, stateDir, backendId, { timeout = 5000 } = {}) {
+  const deadline = performance.now() + finiteTimeout(timeout, 5000);
+  if (typeof url !== 'string' || !LOOPBACK.test(url)) return false;
+  try {
+    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; }
+}
+
+async function freePort(excluded = RESERVED_PORTS) {
+  for (let attempt = 0; attempt < 20; attempt++) {
+    const port = await new Promise((resolve, reject) => {
+      const server = net.createServer();
+      server.once('error', reject);
+      server.listen(0, '127.0.0.1', () => { const { port: chosen } = server.address(); server.close(() => resolve(chosen)); });
+    });
+    if (!excluded.has(port)) return port;
+  }
+  fail('No free loopback port is available');
+}
+
+function spawnDetached(command, args, { env, cwd, log, spawnImpl = spawn }) {
+  const output = fsSync.openSync(log, 'a', 0o600);
+  try {
+    const [file, ...prefix] = command;
+    const child = spawnImpl(file, [...prefix, ...args], { env, cwd, detached: true, windowsHide: true, shell: false,
+      stdio: ['ignore', output, output] });
+    const exited = new Promise(resolve => {
+      child.once('exit', code => resolve({ code }));
+      child.once('error', () => resolve({ code: null }));
+    });
+    child.unref();
+    return { child, exited };
+  } finally { fsSync.closeSync(output); }
+}
+async function waitFor(probe, exited, timeout, what, log, deadline = performance.now() + timeout) {
+  let ended = false;
+  exited.then(() => { ended = true; });
+  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, Math.min(150, remaining(deadline))));
+  }
+  fail(unknown);
+}
+async function readyRecord(log) {
+  let text;
+  try { text = (await readSmall(log, 1024 * 1024)).toString('utf8'); } catch { return null; }
+  for (const line of text.split(/\r?\n/)) {
+    try {
+      const value = JSON.parse(line);
+      if (value?.state === 'ready') return value;
+    } catch { /* not the ready line */ }
+  }
+  return null;
+}
+
+// Startup intent (private token, launch id, port) is saved before any child is
+// spawned, so an attempt that timed out or crashed is never followed by a second
+// manager on the same state: a later open either authenticates that same attempt
+// or refuses. Proven previous-boot records are archived; nothing is stopped automatically.
+const RECOVERY = 'WorkBite never starts a second one on the same state. If it is still starting, open again shortly; '
+  + 'if you have confirmed no process from this state is running, move that record aside and open again.';
+const LAUNCH = /^[0-9a-f]{16}$/;
+// Distinct from every JSON value (including null): only an absent file is "missing".
+const MISSING = Symbol('missing record');
+async function savedRecord(file, what) {
+  try {
+    const bytes = await readSmall(file, 65536);
+    return { record: JSON.parse(bytes.toString('utf8')), bytes };
+  } catch (error) {
+    if (error.code === 'ENOENT') return MISSING;
+    fail(`The ${what} record ${file} is unreadable; WorkBite does not replace it. ${RECOVERY}`);
+  }
+}
+const isRecord = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+  && (value.state === 'starting' || value.state === 'ready') && typeof value.launch === 'string' && LAUNCH.test(value.launch);
+const recordBytes = value => Buffer.from(JSON.stringify(value, null, 2) + '\n');
+
+// Called under open.lock. Compare the exact bytes, retain a private backup before
+// renaming the record, and refuse if it changed. Logs and native intent stay put.
+async function archivePreviousRecord(file, saved, original, boot) {
+  if (!previousBoot(saved.boot, boot)) return false;
+  const current = await readSmall(file, 65536);
+  if (!current.equals(original)) fail('Startup record changed during recovery; refusing another launch.');
+  const backup = `${file}.previous-boot-${randomBytes(12).toString('hex')}`;
+  await fs.copyFile(file, backup, fsSync.constants.COPYFILE_EXCL);
+  if (!(await readSmall(backup, 65536)).equals(original)
+      || !(await readSmall(file, 65536)).equals(original)) {
+    fail('Startup record changed during recovery; backup retained, launch refused.');
+  }
+  // The rename retains the original record's ACL. A separate backup survives a
+  // crash before the new current-boot intent is persisted.
+  await fs.rename(file, `${backup}.record`);
+  if (!(await readSmall(`${backup}.record`, 65536)).equals(original)) {
+    fail('Startup record changed during quarantine; archived evidence retained, launch refused.');
+  }
+  return true;
+}
+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
+// startup). A matching token or UID alone is not that proof. Checked from the record before any
+// network contact; the record is kept and nothing is stopped. A v1 bundle never checks or writes it.
+const HANDOVER = 'Operator handover needed: WorkBite never stops, adopts or replaces it. Close the UIs using it, '
+  + 'stop that process yourself (its pid is in the record), move the record aside and open again; WorkBite then '
+  + 'starts a new one from this bundle.';
+const shown = value => (typeof value === 'string' ? JSON.stringify(value.slice(0, 40)) : value === undefined ? 'absent' : 'invalid');
+function requireExecutionMarker(saved, execution, recordPath, what, extra = {}) {
+  if (!execution) return;
+  const missing = saved.execution_bundle_version !== execution.bundleVersion
+    || Object.entries(extra).some(([key, value]) => saved[key] !== value);
+  if (missing) {
+    fail(`The ${what} recorded in ${recordPath} was not started by the WorkBite ${execution.bundleVersion} execution bundle `
+      + `(execution_bundle_version ${shown(saved.execution_bundle_version)}`
+      + Object.keys(extra).map(key => `, ${key} ${saved[key] === undefined ? 'absent' : JSON.stringify(saved[key])}`).join('')
+      + `), so it cannot serve 9 Execution. ${HANDOVER}`);
+  }
+}
+const executionFields = (execution, extra = {}) => (execution ? { execution_bundle_version: execution.bundleVersion, ...extra } : {});
+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`);
+  const snapshot = await savedRecord(recordPath, 'Work Stack owner');
+  const saved = snapshot === MISSING ? MISSING : snapshot.record;
+  const original = snapshot === MISSING ? null : snapshot.bytes;
+  if (saved !== MISSING) {
+    if (!isRecord(saved) || saved.schema !== OWNER_SCHEMA || typeof saved.workspace !== 'string'
+        || workspaceKey(saved.workspace) !== key || saved.workspace_uid !== uid
+        || typeof saved.token !== 'string' || !/^[0-9a-f]{64}$/.test(saved.token)
+        || (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, 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 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 {
+      if (saved.state === 'starting' || validBoot(boot))
+        await writeAtomic(recordPath, recordBytes({ ...saved, ...(validBoot(boot) ? { boot } : {}), state: 'ready', endpoint }));
+      return { endpoint, reused: true, pid: saved.pid };
+    }
+  }
+  if (!validBoot(boot)) fail('Trusted OS boot provenance is unavailable; no owner was started.');
+  const intent = { boot, schema: OWNER_SCHEMA, state: 'starting', workspace, workspace_uid: uid,
+    launch: randomBytes(8).toString('hex'), token: randomBytes(32).toString('hex'), ...executionFields(execution) };
+  const log = logFor(intent.launch);
+  await writeAtomic(recordPath, recordBytes(intent));
+  const { child, exited } = spawnDetached(commands.workstack_engine,
+    ['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 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 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');
+  const saved = snapshot === MISSING ? MISSING : snapshot.record;
+  const original = snapshot === MISSING ? null : snapshot.bytes;
+  if (saved !== MISSING) {
+    if (!isRecord(saved) || saved.schema !== STACKBITE_SCHEMA || saved.backend_id !== backendId
+        || 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, boot);
+    requireExecutionMarker(saved, execution, recordPath, 'StackBite backend', NATIVE_LAUNCH);
+    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 {
+      if (saved.state === 'starting' || validBoot(boot))
+        await writeAtomic(recordPath, recordBytes({ ...saved, ...(validBoot(boot) ? { boot } : {}), state: 'ready' }));
+      return { url: saved.url, reused: true, pid: saved.pid };
+    }
+  }
+  if (!validBoot(boot)) fail('Trusted OS boot provenance is unavailable; no backend was started.');
+  const port = await freePort();
+  const url = `http://127.0.0.1:${port}`;
+  const intent = { boot, schema: STACKBITE_SCHEMA, state: 'starting', backend_id: backendId, launch: randomBytes(8).toString('hex'), url, port,
+    ...executionFields(execution, NATIVE_LAUNCH) };
+  const log = logFor(intent.launch);
+  const home = path.dirname(commands.stackbite[commands.stackbite.length - 1]);
+  await writeAtomic(recordPath, recordBytes(intent));
+  // The private Python terminal core and this backend's own loopback bridge are
+  // mandatory for the room backend (taskrooms reads STACKBITE_BRIDGE_URL; the agent
+  // CLI and frontend read STACKBITE_ROOM_BRIDGE_URL); caller values are overridden here only.
+  // A v2 bundle also starts it with the WorkBite native launch opt-in (cleanEnvironment drops any
+  // caller value, so a v1 backend never gets it); STACKBITE_HOME lets it resolve the bundle's native assets.
+  const { child, exited } = spawnDetached(commands.stackbite, ['--room-backend', '--port', String(port)], {
+    env: withPath({ ...environment, STACKBITE_HOME: home, STACKBITE_STATE_DIR: layout.stackbite,
+      STACKBITE_PTY_BACKEND: 'private', STACKBITE_ROOM_BACKEND: '1', STACKBITE_TERMINAL_CORE: 'python',
+      STACKBITE_BRIDGE_URL: url, STACKBITE_ROOM_BRIDGE_URL: url, PYINSTALLER_RESET_ENVIRONMENT: '1',
+      ...(execution ? { STACKBITE_WORKBITE_NATIVE_LAUNCH: '1' } : {}) }, home),
+    cwd: home, log, spawnImpl });
+  await writeAtomic(recordPath, recordBytes({ ...intent, pid: child.pid }));
+  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 };
+}
+
+// v2 only, after this backend's identity is proven: one headless `stackbite --workbite-native-init`
+// selects (or, through StackBite's own durable coordinator, reuses) the native terminal daemon for
+// this backend. No UI, window, Room or Seat; exactly one exit-0 selected record is accepted.
+// Anything else (refused, Unknown, malformed, timed out) refuses the open: WorkBite never retries,
+// starts another daemon or falls back, and a later open asks the same coordinator again.
+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 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),
+      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; } }
+  if (result.error || record === null || typeof record !== 'object' || Array.isArray(record) || Object.keys(record).length !== 2
+      || record.schema !== NATIVE_INIT_SCHEMA || record.status !== 'selected') {
+    const exit = result.error ? (result.error.killed ? 'timed out' : `exit ${result.error.code ?? 'unknown'}`) : 'no selected record';
+    fail(`StackBite native runtime initialization did not select a native runtime (${exit}: ${boundedText(result.stderr) || 'no reason'}); `
+      + 'the execution UI was not started. WorkBite does not retry, start another daemon or fall back; '
+      + 'if the outcome is unknown, open again later and StackBite looks the same selection up.');
+  }
+  return record.status;
+}
+
+async function writeDockConfig(layout, url) {
+  const bytes = Buffer.from(JSON.stringify({ schema: CONNECTION_SCHEMA, base_url: url, state_dir: layout.stackbite }, null, 2) + '\n');
+  let current = null;
+  try { current = await readSmall(layout.dock, 65536); } catch { current = null; }
+  if (!current || !current.equals(bytes)) await writeAtomic(layout.dock, bytes);
+}
+
+// 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.
+const EXECUTION_UI_SCHEMA = 'workbite.execution-ui-settings.v1';
+const EXECUTION_UI_DEFAULT = Object.freeze({ schema: EXECUTION_UI_SCHEMA, enabled: true, prefix: 'ctrl+]', last_view_execution: false });
+const SETTINGS_FIX = 'WorkBite does not repair or replace it; fix it or move it aside and open again.';
+function validExecutionUi(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 4
+    && value.schema === EXECUTION_UI_SCHEMA && typeof value.enabled === 'boolean' && typeof value.prefix === 'string'
+    && typeof value.last_view_execution === 'boolean';
+}
+// Same-directory temporary file published by hard link: never replaces a file another writer created.
+async function publishNew(file, bytes) {
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${randomBytes(8).toString('hex')}.tmp`);
+  const handle = await fs.open(temporary, 'wx', 0o600);
+  try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+  try { await fs.link(temporary, file); return true; } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    return false;
+  } finally { await fs.unlink(temporary); }
+}
+async function ensureExecutionSettings(file, attempt = 0) {
+  let bytes = null;
+  try { bytes = await readSmall(file, 1024 * 1024); } catch (error) {
+    if (error.code !== 'ENOENT') fail(`The execution UI settings ${file} are unreadable. ${SETTINGS_FIX}`);
+  }
+  if (bytes === null) {
+    const created = await publishNew(file, Buffer.from(JSON.stringify({ execution_ui: EXECUTION_UI_DEFAULT }, null, 2) + '\n'));
+    if (created) return 'initialized';
+    if (attempt) fail(`The execution UI settings ${file} keep changing while opening. ${SETTINGS_FIX}`);
+    return ensureExecutionSettings(file, attempt + 1);
+  }
+  let document;
+  try {
+    const text = bytes.toString('utf8');
+    document = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+  } catch { fail(`The execution UI settings ${file} are not valid JSON. ${SETTINGS_FIX}`); }
+  if (document === null || typeof document !== 'object' || Array.isArray(document)) {
+    fail(`The execution UI settings ${file} are not a JSON object. ${SETTINGS_FIX}`);
+  }
+  if (!Object.hasOwn(document, 'execution_ui')) {
+    // Other settings are kept; only the missing opt-in is added.
+    await writeAtomic(file, Buffer.from(JSON.stringify({ ...document, execution_ui: EXECUTION_UI_DEFAULT }, null, 2) + '\n'));
+    return 'initialized';
+  }
+  if (!validExecutionUi(document.execution_ui)) {
+    fail(`The execution UI settings ${file} hold an execution_ui value that is not the exact four-key opt-in object `
+      + `(schema "${EXECUTION_UI_SCHEMA}", enabled, prefix, last_view_execution). ${SETTINGS_FIX}`);
+  }
+  return document.execution_ui.enabled ? 'enabled' : 'disabled';
+}
+
+// The TypeScript UI's same-window 9 Execution (docs/WORKBITE-TYPESCRIPT-EXECUTION-CONFIG.md): set only by
+// this launcher for a verified v2 bundle whose device opt-in is enabled. The bridge is the bundle's own
+// verified workbite_tui (run by the UI with its fixed --workbite-execution-bridge argv), never a caller,
+// receipt or PATH value; the UI keeps its own WORKSTACK_TUI_SETTINGS, so these names carry the private
+// execution settings and intent paths separately. cleanEnvironment drops any caller WORKBITE_ value first.
+function typescriptExecutionEnvironment(layout, bridge) {
+  return { WORKBITE_EXECUTION_UI: '1', WORKBITE_EXECUTION_BRIDGE: bridge,
+    WORKBITE_EXECUTION_SETTINGS: layout.tuiSettings, WORKBITE_EXECUTION_INTENT: layout.tuiIntent };
+}
+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, 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) : {}),
+    ...(mobile ? { WORKBITE_MOBILE_EXECUTABLE: executables.workbite_mobile,
+      WORKBITE_MOBILE_HOST: JSON.stringify(mobile) } : {}) }, home);
+}
+
+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 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, 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');
+  commands = commands || Object.fromEntries(Object.entries(installed.executables).map(([name, file]) => [name, [file]]));
+  // A v2 bundle keeps its owner/backend markers and native init whichever frontend runs; only the
+  // foreground UI differs. TypeScript is the default; rust needs a v2 bundle. There is no fallback between them.
+  const execution = installed.bundle?.schema === BUNDLE_V2 ? { bundleVersion: installed.bundle.version } : null;
+  if (frontend === 'rust' && !execution) {
+    fail('--frontend rust needs a WorkBite execution (v2) bundle; this installed bundle has only the TypeScript UI. Nothing was started.');
+  }
+  const uiCommand = frontend === 'rust' ? 'workbite_tui' : 'workstack_tui';
+  if (!(Array.isArray(commands[uiCommand]) && commands[uiCommand].length)) {
+    fail(frontend === 'rust' ? 'This WorkBite bundle has no verified execution UI executable; nothing was started.'
+      : 'This WorkBite bundle has no verified TypeScript UI executable; nothing was started.');
+  }
+  // A verified v2 bundle always holds the execution bridge; anything else is refused, never probed for.
+  const bridge = execution && frontend === 'typescript' ? installed.executables?.workbite_tui : null;
+  if (execution && frontend === 'typescript' && !verifiedPath(bridge)) {
+    fail('This WorkBite execution bundle has no verified execution bridge executable; nothing was started.');
+  }
+  const layout = stateLayout(path.resolve(stateRoot));
+  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 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 stage('startup lock', () => withLock(layout.lock, async () => {
+    let remembered = null;
+    if (workspace === undefined) {
+      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 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 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 stage('native runtime selection', () => initializeNativeRuntime({ commands, layout, url: stackbite.url, environment: base, execImpl,
+        timeout: timeouts.nativeInit }));
+    }
+    await stage('execution connection', () => writeDockConfig(layout, stackbite.url));
+    // Only after the owner, StackBite and dock config are proven ready, and before the UI.
+    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,
+    ...(execution ? { execution_ui: session.executionUi, execution_bundle_version: execution.bundleVersion } : {}) };
+  if (!ui) {
+    stdout.write(JSON.stringify(summary) + '\n');
+    return { code: 0, signal: null, summary };
+  }
+  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.
+  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, runForeground };