workbite 0.1.2 → 0.1.4

package/README.md

@@ -3,6 +3,10 @@
 WorkBite installs and opens **Work Stack** (organizes the work) and
 **StackBite** (gets it moving) as one native suite.
 
+Version 0.1.4 opens the unified Rust UI: select a Task, start its agent, and
+use `9 Execution` to see and control its native terminal in the same window.
+The existing 1–8 menus remain available. Task completion stays an explicit action.
+
 ```sh
 npm install -g workbite
 workbite install
@@ -19,7 +23,7 @@ Node.js 20+ on Windows x64 or Linux x64 (glibc 2.28+).
 - `workbite check` re-verifies the installed bundle without downloading.
 - `workbite open --workspace ABS [--init] [--no-ui]` starts or reuses the
   workspace's Work Stack owner and a StackBite backend (only processes it can
-  prove it started), then runs the Work Stack terminal UI. Backends keep
+  prove it started), then runs the unified WorkBite terminal UI. Backends keep
   running after the UI exits.
 - `workbite` (or `workbite open` without `--workspace`) reopens the last
   workspace that opened successfully; an explicit `--workspace` always wins.

package/lib/cli.js

@@ -237,7 +237,7 @@ async function main(argv = process.argv.slice(2), options = {}) {
     return { code: 0, signal: null };
   }
   return openSuite({ installed, commands: options.commands, workspace: parsed.workspace, init: parsed.init, ui: parsed.ui,
-    stateRoot, environment, spawnImpl: options.spawnImpl, stdout, timeouts: options.timeouts });
+    stateRoot, environment, spawnImpl: options.spawnImpl, execImpl: options.execImpl, stdout, timeouts: options.timeouts });
 }
 
 module.exports = { main, parseArguments, HELP };

package/lib/install.js

@@ -15,6 +15,14 @@ const EXECUTABLES = Object.freeze({
   workstack_tui: 'workstack/workstack-tui',
   stackbite: 'stackbite/stackbite',
 });
+// Exact executable roster per bundle schema: v1 keeps the four legacy entries; v2 adds only the
+// same-window execution UI (proprietary assembly binary workstack-native-tui). Any other schema is refused.
+const BUNDLE_V1 = 'workbite.bundle.v1';
+const BUNDLE_V2 = 'workbite.bundle.v2';
+const ROSTERS = Object.freeze({
+  [BUNDLE_V1]: EXECUTABLES,
+  [BUNDLE_V2]: Object.freeze({ ...EXECUTABLES, workbite_tui: 'workstack/workstack-native-tui' }),
+});
 
 function absoluteOverride(environment, name) {
   const value = environment[name];
@@ -75,9 +83,10 @@ function releaseSpec(manifest, platform = process.platform, arch = process.arch,
     platform, target, version: manifest.version };
 }
 
-function expectedExecutables(spec) {
+function expectedExecutables(spec, schema = BUNDLE_V1) {
+  if (!Object.hasOwn(ROSTERS, schema)) fail('bundle.json identity or executable layout mismatch');
   const suffix = spec.platform === 'win32' ? '.exe' : '';
-  return Object.fromEntries(Object.entries(EXECUTABLES).map(([name, file]) => [name, file + suffix]));
+  return Object.fromEntries(Object.entries(ROSTERS[schema]).map(([name, file]) => [name, file + suffix]));
 }
 function plainObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
 function sameKeys(value, keys) {
@@ -93,8 +102,9 @@ async function validateBundle(directory, spec) {
   if (sha256(bundleBytes) !== spec.bundleSha256) fail('Pinned bundle.json SHA-256 mismatch');
   let bundle;
   try { bundle = JSON.parse(bundleBytes.toString('utf8')); } catch { fail('bundle.json is not valid JSON'); }
-  const executables = expectedExecutables(spec);
-  if (!plainObject(bundle) || bundle.schema !== 'workbite.bundle.v1' || bundle.product !== 'WorkBite'
+  if (!plainObject(bundle) || !Object.hasOwn(ROSTERS, bundle.schema)) fail('bundle.json identity or executable layout mismatch');
+  const executables = expectedExecutables(spec, bundle.schema);
+  if (bundle.product !== 'WorkBite'
       || bundle.version !== spec.version || bundle.target !== spec.target || !plainObject(bundle.components)
       || !sameKeys(bundle.executables, Object.keys(executables))
       || Object.entries(executables).some(([name, file]) => bundle.executables[name] !== file)
@@ -220,5 +230,5 @@ function stageReporter(stderr) {
   return stage => stderr.write(`WorkBite: ${messages[stage]}\n`);
 }
 
-module.exports = { REPOSITORY, TARGETS, EXECUTABLES, locations, platformTarget, releaseSpec, expectedExecutables,
+module.exports = { REPOSITORY, TARGETS, EXECUTABLES, BUNDLE_V1, BUNDLE_V2, ROSTERS, locations, platformTarget, releaseSpec, expectedExecutables,
   validateBundle, ensureInstalled, installName, stageReporter, packageVersion };

package/lib/private-state.js

@@ -0,0 +1,116 @@
+'use strict';
+// Private Windows state for the v2 execution UI: the native TUI intent directory and the
+// deploy journal must be owned by the current user and grant mutating access only to that
+// user, SYSTEM and Administrators (the Work Stack TUI's private-parent check), but a folder
+// created under %LOCALAPPDATA% inherits whatever its parents grant (sandbox groups included).
+// One bounded Windows PowerShell child replaces exactly the named directories' DACLs with a
+// protected private one; owner, contents and file identities are kept. Linux keeps 0700.
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const { fail } = require('./common');
+
+const RESULT_SCHEMA = 'workbite.private-directories.v1';
+const MAXIMUM = 8;
+// Constant script, no interpolation: paths arrive only as WORKBITE_PRIVATE_DIRECTORY_<n>.
+// .NET types only (no cmdlets), so a foreign PSModulePath cannot change what runs.
+const SCRIPT = String.raw`
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+try {
+  $count = [int]$env:WORKBITE_PRIVATE_DIRECTORY_COUNT
+  if ($count -lt 1 -or $count -gt ${MAXIMUM}) { throw 'invalid directory count' }
+  $me = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+  $allowed = @($me.Value, 'S-1-5-18', 'S-1-5-32-544')
+  $sid = [System.Security.Principal.SecurityIdentifier]
+  $sections = [System.Security.AccessControl.AccessControlSections]'Access, Owner'
+  $results = @()
+  for ($index = 0; $index -lt $count; $index++) {
+    $target = [Environment]::GetEnvironmentVariable('WORKBITE_PRIVATE_DIRECTORY_' + $index)
+    if (-not $target -or -not [System.IO.Path]::IsPathRooted($target)) { throw ('directory ' + $index + ' is not an absolute path') }
+    $info = [System.IO.DirectoryInfo]::new($target)
+    $info.Refresh()
+    if (-not $info.Exists) { throw ('directory ' + $index + ' is missing or not a directory') }
+    if (($info.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) { throw ('directory ' + $index + ' is a link or reparse point') }
+    $current = $info.GetAccessControl($sections)
+    if ($current.GetOwner($sid).Value -ne $me.Value) { throw ('directory ' + $index + ' is not owned by the current Windows user') }
+    $rules = @($current.GetAccessRules($true, $true, $sid))
+    $private = $current.AreAccessRulesProtected -and $rules.Count -gt 0
+    $mine = $false
+    foreach ($rule in $rules) {
+      if ($rule.IsInherited -or $rule.AccessControlType -ne 'Allow' -or $allowed -notcontains $rule.IdentityReference.Value) { $private = $false }
+      if ($rule.IdentityReference.Value -eq $me.Value -and ($rule.FileSystemRights -band [System.Security.AccessControl.FileSystemRights]::FullControl) -eq [System.Security.AccessControl.FileSystemRights]::FullControl) { $mine = $true }
+    }
+    if ($private -and $mine) { $results += 'kept'; continue }
+    $security = [System.Security.AccessControl.DirectorySecurity]::new()
+    $security.SetAccessRuleProtection($true, $false)
+    foreach ($principal in $allowed) {
+      $security.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new($sid::new($principal),
+        [System.Security.AccessControl.FileSystemRights]::FullControl,
+        [System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit',
+        [System.Security.AccessControl.PropagationFlags]::None, [System.Security.AccessControl.AccessControlType]::Allow))
+    }
+    # Only the DACL section is written; the owner is left as verified above.
+    $info.SetAccessControl($security)
+    $info.Refresh()
+    if (($info.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) { throw ('directory ' + $index + ' changed while protecting it') }
+    $after = $info.GetAccessControl($sections)
+    if ($after.GetOwner($sid).Value -ne $me.Value -or -not $after.AreAccessRulesProtected) { throw ('directory ' + $index + ' did not keep a protected private DACL') }
+    foreach ($rule in @($after.GetAccessRules($true, $true, $sid))) {
+      if ($rule.IsInherited -or $rule.AccessControlType -ne 'Allow' -or $allowed -notcontains $rule.IdentityReference.Value) { throw ('directory ' + $index + ' still grants another principal access') }
+    }
+    $results += 'protected'
+  }
+  [Console]::Out.Write('{"schema":"${RESULT_SCHEMA}","results":["' + ($results -join '","') + '"]}')
+  exit 0
+} catch {
+  $message = ($_.Exception.Message -replace '[\x00-\x1f\x7f]', ' ')
+  if ($message.Length -gt 300) { $message = $message.Substring(0, 300) }
+  [Console]::Error.Write($message)
+  exit 3
+}
+`;
+const ENCODED = Buffer.from(SCRIPT, 'utf16le').toString('base64');
+
+function windowsPowerShell(environment) {
+  const root = environment.SystemRoot || environment.SYSTEMROOT || environment.windir || 'C:\\Windows';
+  if (!/^[A-Za-z]:\\[^\x00-\x1f"*?<>|]*$/.test(root)) fail('Cannot locate Windows PowerShell: SystemRoot is not an absolute local path.');
+  return path.win32.join(root, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+}
+const bounded = text => String(text || '').replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, 300);
+
+// Windows only: each directory must already exist (created by safeDirectory). Returns 'kept'
+// or 'protected' per directory; anything else refuses and nothing that uses them is started.
+// No-op elsewhere: Linux directories are created 0700 and checked by the native TUI itself.
+async function protectPrivateDirectories(directories, { platform = process.platform, environment = process.env,
+  execImpl = execFile, timeout = 60000 } = {}) {
+  if (platform !== 'win32') return null;
+  if (!Array.isArray(directories) || !directories.length || directories.length > MAXIMUM
+      || directories.some(value => typeof value !== 'string' || !path.win32.isAbsolute(value) || /^[\\/]{2}|[\x00-\x1f]/.test(value))) {
+    fail('WorkBite private state directories must be absolute local paths.');
+  }
+  const childEnvironment = {};
+  for (const [key, value] of Object.entries(environment)) {
+    // Windows PowerShell must not load another PowerShell's modules; earlier helper values are replaced.
+    if (value !== undefined && key.toUpperCase() !== 'PSMODULEPATH' && !/^WORKBITE_PRIVATE_DIRECTORY_/i.test(key)) childEnvironment[key] = value;
+  }
+  childEnvironment.WORKBITE_PRIVATE_DIRECTORY_COUNT = String(directories.length);
+  directories.forEach((value, index) => { childEnvironment[`WORKBITE_PRIVATE_DIRECTORY_${index}`] = path.win32.resolve(value); });
+  const file = windowsPowerShell(environment);
+  const result = await new Promise(resolve => {
+    execImpl(file, ['-NoLogo', '-NoProfile', '-NonInteractive', '-EncodedCommand', ENCODED],
+      { env: childEnvironment, shell: false, windowsHide: true, timeout, maxBuffer: 64 * 1024, encoding: 'utf8' },
+      (error, stdout, stderr) => resolve({ error, stdout: stdout || '', stderr: stderr || '' }));
+  });
+  let record = null;
+  try { record = JSON.parse(result.stdout.trim()); } catch { record = null; }
+  if (result.error || record === null || typeof record !== 'object' || Array.isArray(record)
+      || Object.keys(record).length !== 2 || record.schema !== RESULT_SCHEMA || !Array.isArray(record.results)
+      || record.results.length !== directories.length || record.results.some(value => value !== 'kept' && value !== 'protected')) {
+    fail(`WorkBite could not make its private execution state private (${bounded(result.stderr) || 'no result'}); `
+      + `nothing that uses ${directories.join(', ')} was started. Each must be a real directory owned by the current `
+      + 'Windows user; WorkBite does not take ownership or follow links.');
+  }
+  return record.results;
+}
+
+module.exports = { protectPrivateDirectories, RESULT_SCHEMA };

package/lib/runtime.js

@@ -12,6 +12,8 @@ const path = require('node:path');
 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 { BUNDLE_V2 } = require('./install');
+const { protectPrivateDirectories } = require('./private-state');
 
 const BACKEND_SCHEMA = 'stackbite.workstack-backend.v1';
 const CONNECTION_SCHEMA = 'workstack.helm-connection.v1';
@@ -48,7 +50,11 @@ function stateLayout(root) {
     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') };
+    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,
@@ -292,7 +298,29 @@ const isRecord = value => value !== null && typeof value === 'object' && !Array.
   && (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');
 
-async function ensureEngine({ commands, workspace, uid, layout, environment, spawnImpl, timeout = 60000 }) {
+// 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 }) {
   const key = workspaceKey(workspace);
   const recordPath = path.join(layout.owners, `${key}.json`);
   const logFor = launch => path.join(layout.logs, `workstack-engine-${key}-${launch}.log`);
@@ -303,6 +331,7 @@ async function ensureEngine({ commands, workspace, uid, layout, environment, spa
         || typeof saved.token !== 'string' || !/^[0-9a-f]{64}$/.test(saved.token)) {
       fail(`The Work Stack owner record ${recordPath} is invalid for this workspace; WorkBite does not replace it. ${RECOVERY}`);
     }
+    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));
@@ -315,7 +344,7 @@ async function ensureEngine({ commands, workspace, uid, layout, environment, spa
     return { endpoint, reused: true, pid: saved.pid };
   }
   const intent = { schema: OWNER_SCHEMA, state: 'starting', workspace, workspace_uid: uid,
-    launch: randomBytes(8).toString('hex'), token: randomBytes(32).toString('hex') };
+    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,
@@ -329,7 +358,7 @@ async function ensureEngine({ commands, workspace, uid, layout, environment, spa
   return { endpoint: ready.endpoint, reused: false, pid: child.pid };
 }
 
-async function ensureStackbite({ commands, layout, backendId, environment, spawnImpl, timeout = 120000 }) {
+async function ensureStackbite({ commands, layout, backendId, environment, spawnImpl, timeout = 120000, execution = null }) {
   const recordPath = layout.stackbiteRecord;
   const logFor = launch => path.join(layout.logs, `stackbite-backend-${launch}.log`);
   const saved = await savedRecord(recordPath, 'StackBite backend');
@@ -338,6 +367,7 @@ async function ensureStackbite({ commands, layout, backendId, environment, spawn
         || typeof saved.url !== 'string' || LOOPBACK.exec(saved.url)?.[1] !== String(saved.port)) {
       fail(`The StackBite backend record ${recordPath} is invalid for this state; WorkBite does not replace it. ${RECOVERY}`);
     }
+    requireExecutionMarker(saved, execution, recordPath, 'StackBite backend', NATIVE_LAUNCH);
     if (!await stackbiteIdentity(saved.url, layout.stackbite, backendId)) {
       fail(`The StackBite backend recorded in ${recordPath} could not be authenticated (still starting, or stopped). ${RECOVERY}`);
     }
@@ -346,17 +376,21 @@ async function ensureStackbite({ commands, layout, backendId, environment, spawn
   }
   const port = await freePort();
   const url = `http://127.0.0.1:${port}`;
-  const intent = { schema: STACKBITE_SCHEMA, state: 'starting', backend_id: backendId, launch: randomBytes(8).toString('hex'), url, port };
+  const intent = { 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' }, home),
+      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(() => stackbiteIdentity(url, layout.stackbite, backendId), exited, timeout, 'StackBite backend', log);
@@ -364,6 +398,36 @@ async function ensureStackbite({ commands, layout, backendId, environment, spawn
   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 new Promise(resolve => {
+    execImpl(file, [...prefix, '--workbite-native-init'], {
+      env: withPath({ ...environment, STACKBITE_HOME: home, STACKBITE_STATE_DIR: layout.stackbite,
+        STACKBITE_BRIDGE_URL: url, STACKBITE_ROOM_BRIDGE_URL: url, STACKBITE_WORKBITE_NATIVE_LAUNCH: '1',
+        PYINSTALLER_RESET_ENVIRONMENT: '1' }, home),
+      cwd: home, shell: false, windowsHide: true, timeout, maxBuffer: 64 * 1024, encoding: 'utf8',
+    }, (error, stdout, stderr) => resolve({ error, stdout: stdout || '', stderr: stderr || '' }));
+  });
+  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;
@@ -397,12 +461,65 @@ async function withLock(file, action, { wait = 180000, stale = 300000 } = {}) {
   }
 }
 
-function uiEnvironment(base, { executables, layout, endpoint, uid, backendId }) {
+// 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';
+}
+
+function uiEnvironment(base, { executables, layout, endpoint, uid, backendId, execution = 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 }, home);
+    WORKSTACK_DEPLOY_JOURNAL_DIR: layout.journal, WORKSTACK_STACKBITE_EXECUTABLE: executables.stackbite,
+    ...(execution ? { WORKSTACK_TUI_STATE: layout.tuiIntent, WORKSTACK_TUI_SETTINGS: layout.tuiSettings } : {}) }, home);
 }
 
 function runForeground(command, args, environment, { spawnImpl = spawn, signalSource = process } = {}) {
@@ -423,13 +540,23 @@ function runForeground(command, args, environment, { spawnImpl = spawn, signalSo
 
 // 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, spawnImpl = spawn, stdout = process.stdout, timeouts = {} }) {
+  ui = true, spawnImpl = spawn, execImpl = execFile, platform = process.platform, stdout = process.stdout, timeouts = {} }) {
   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 always runs its execution UI; a v1 bundle keeps the legacy UI. There is no fallback between them.
+  const execution = installed.bundle?.schema === BUNDLE_V2 ? { bundleVersion: installed.bundle.version } : null;
+  if (execution && !(Array.isArray(commands.workbite_tui) && commands.workbite_tui.length)) {
+    fail('This WorkBite bundle has no verified execution UI executable; nothing was started.');
+  }
   const layout = stateLayout(path.resolve(stateRoot));
   await prepareState(layout);
   const base = cleanEnvironment(environment);
+  if (execution) {
+    // The execution UI's intent parent and deploy journal, made private (Windows DACL) before any file in them is written.
+    await safeDirectory(layout.nativeTui);
+    await protectPrivateDirectories([layout.nativeTui, layout.journal], { platform, environment: base, execImpl });
+  }
   const engineEnvironment = { ...base, WORK_STACK_RUNTIME: layout.workstackRuntime };
   const session = await withLock(layout.lock, async () => {
     let remembered = null;
@@ -437,29 +564,40 @@ async function openSuite({ installed, commands, workspace, init = false, stateRo
       remembered = await rememberedWorkspace(layout);
       workspace = checkedWorkspace(remembered.workspace);
     }
+    // Settings are settled before any workspace init or backend start, so a refused file changes nothing else.
+    const executionUi = execution ? await ensureExecutionSettings(layout.tuiSettings) : null;
     const uid = init ? await initializeWorkspace(commands, workspace, engineEnvironment) : await readWorkspaceUid(workspace);
     if (remembered && uid !== remembered.uid) fail(`The workspace ${workspace} changed while opening. ${EXPLICIT}`);
     const backendId = await ensureBackendId(layout);
-    const engine = await ensureEngine({ commands, workspace, uid, layout, environment: engineEnvironment, spawnImpl, timeout: timeouts.engine });
-    const stackbite = await ensureStackbite({ commands, layout, backendId, environment: base, spawnImpl, timeout: timeouts.stackbite });
+    const engine = await ensureEngine({ commands, workspace, uid, layout, environment: engineEnvironment, spawnImpl,
+      timeout: timeouts.engine, execution });
+    const stackbite = await ensureStackbite({ commands, layout, backendId, environment: base, spawnImpl,
+      timeout: timeouts.stackbite, execution });
+    if (execution) {
+      await initializeNativeRuntime({ commands, layout, url: stackbite.url, environment: base, execImpl,
+        timeout: timeouts.nativeInit });
+    }
     await writeDockConfig(layout, stackbite.url);
     // Only after the owner, StackBite and dock config are proven ready, and before the UI.
     await rememberWorkspace(layout, workspace, uid);
-    return { uid, backendId, engine, stackbite };
+    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 };
+    backend_id: session.backendId, state: layout.root,
+    ...(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 });
-  const result = await runForeground(commands.workstack_tui, [], environmentForUi, { spawnImpl });
+    uid: session.uid, backendId: session.backendId, execution });
+  // Exactly one foreground child in this terminal (inherited stdio, never detached or a new console).
+  const result = await runForeground(execution ? commands.workbite_tui : commands.workstack_tui, [], environmentForUi, { spawnImpl });
   return { ...result, summary };
 }
 
 module.exports = { cleanEnvironment, stateLayout, prepareState, ensureBackendId, workspaceKey, readWorkspaceUid,
   initializeWorkspace, engineIdentity, stackbiteIdentity, freePort, ensureEngine, ensureStackbite, writeDockConfig,
-  withLock, uiEnvironment, openSuite, rememberedWorkspace, RESERVED_PORTS, SELECTION_SCHEMA };
+  withLock, uiEnvironment, openSuite, rememberedWorkspace, ensureExecutionSettings, initializeNativeRuntime, RESERVED_PORTS,
+  SELECTION_SCHEMA, EXECUTION_UI_DEFAULT, NATIVE_INIT_SCHEMA };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workbite",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "WorkBite (Work Stack + StackBite) verified native suite installer and launcher",
   "license": "UNLICENSED",
   "engines": {

package/release.json

@@ -1,24 +1,24 @@
 {
   "schema": "workbite.release.v1",
   "product": "WorkBite",
-  "version": "0.1.0",
-  "launcherVersion": "0.1.2",
+  "version": "0.1.4",
+  "launcherVersion": "0.1.4",
   "repository": "Shinick-Han/WorkBite-releases",
-  "tag": "v0.1.0",
+  "tag": "v0.1.4",
   "platforms": {
     "windows-x64": {
-      "asset": "workbite-0.1.0-windows-x64.zip",
-      "url": "https://github.com/Shinick-Han/WorkBite-releases/releases/download/v0.1.0/workbite-0.1.0-windows-x64.zip",
-      "sha256": "345cc42f025203da75ac17d048f6103f098a3fa98f795a03857f53788b8e2a21",
-      "size": 92677172,
-      "bundleSha256": "f62351c975f153ae1d0843403150a4d6079ac39ab0d5ab7afcd739c72487c34b"
+      "asset": "workbite-0.1.4-windows-x64.zip",
+      "sha256": "82150e6731bbe2cc00b08265ea5f97f12dc92e6213d32fc53ba4cd3bb1f98c50",
+      "size": 97936126,
+      "bundleSha256": "77efe214a312c14f4565075574541777a96e541ce3d0065d3e85184b0c4a2568",
+      "url": "https://github.com/Shinick-Han/WorkBite-releases/releases/download/v0.1.4/workbite-0.1.4-windows-x64.zip"
     },
     "linux-x64": {
-      "asset": "workbite-0.1.0-linux-x64.tar.gz",
-      "url": "https://github.com/Shinick-Han/WorkBite-releases/releases/download/v0.1.0/workbite-0.1.0-linux-x64.tar.gz",
-      "sha256": "e96e7c75bfce493ebf0ffd7009f67c44c1b312d5ebfda3467e8b47720a1aff32",
-      "size": 77250118,
-      "bundleSha256": "52764882937a214a7c2519ea542782abb55894d7660e0a1a6706a9e99de0392d"
+      "asset": "workbite-0.1.4-linux-x64.tar.gz",
+      "sha256": "f349f8c0eebbcf171a488bd1108d74b123cb57633ec6fc54c55c79532b47ae12",
+      "size": 81647804,
+      "bundleSha256": "aa37923f4dd74e8a12ceac09d26cea956a960ea6d34939be1bef303c79042222",
+      "url": "https://github.com/Shinick-Han/WorkBite-releases/releases/download/v0.1.4/workbite-0.1.4-linux-x64.tar.gz"
     }
   }
 }