workbite 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# workbite
+
+WorkBite installs and opens **Work Stack** (organizes the work) and
+**StackBite** (gets it moving) as one native suite.
+
+```sh
+npm install -g workbite
+workbite install
+workbite open --workspace /abs/path/new-folder --init
+workbite open --workspace /abs/path/existing-workspace
+```
+
+Node.js 20+ on Windows x64 or Linux x64 (glibc 2.28+).
+
+- `workbite install` downloads the pinned bundle for your platform from
+  `github.com/Shinick-Han/WorkBite-releases`, verifies its size and SHA-256 and
+  every file listed in its `bundle.json`, and installs it into an immutable
+  per-user version folder. No auto-update, no install scripts, no dependencies.
+- `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
+  running after the UI exits.
+- Each backend's startup record (private token, launch id, port) is saved in
+  the state folder *before* the process is started. A later `open` reuses
+  that same attempt once it authenticates (also after a slow start), and
+  otherwise refuses: an unreadable, invalid or unreachable record is never
+  cleared, replaced or followed by a second backend, and nothing is stopped.
+  If a refusal names a record and you have confirmed no WorkBite process for
+  that state is running, move that record aside and open again.
+
+WorkBite keeps its own state (`%LOCALAPPDATA%\WorkBite` on Windows,
+`~/.local/share/workbite` and `~/.local/state/workbite` on Linux; override
+with absolute `WORKBITE_HOME` / `WORKBITE_STATE_DIR`) and never touches
+separately installed Work Stack or StackBite apps, their state or ports. It
+never approves provider trust or starts paid agents by itself.
+
+This package is `UNLICENSED` (all rights reserved). Third-party licenses ship
+in each bundle's `licenses/` folder.

package/bin/workbite.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+'use strict';
+const { main } = require('../lib/cli');
+main().then(({ code, signal }) => {
+  if (signal && process.platform !== 'win32') {
+    process.kill(process.pid, signal);
+  } else {
+    process.exitCode = code === null ? 1 : code;
+  }
+}).catch(error => {
+  console.error(`WorkBite: ${error.message}`);
+  process.exitCode = 1;
+});

package/lib/archive.js

@@ -0,0 +1,233 @@
+'use strict';
+// ZIP/TAR structural parsers reused from the StackBite npm bootstrapper (same
+// owner, proprietary): every member is bounded and checked before the OS tar
+// command sees the archive. WorkBite archives have no wrapping root directory.
+const fs = require('node:fs/promises');
+const { createReadStream, createWriteStream } = require('node:fs');
+const { createGunzip, createInflateRaw } = require('node:zlib');
+const { Transform, Writable } = require('node:stream');
+const { pipeline } = require('node:stream/promises');
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+const { LIMITS, fail, memberPath } = require('./common');
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+const crcTable = Uint32Array.from({ length: 256 }, (_, value) => {
+  for (let bit = 0; bit < 8; bit++) value = (value >>> 1) ^ ((value & 1) ? 0xedb88320 : 0);
+  return value >>> 0;
+});
+const TOP_DIRECTORIES = Object.freeze(['workstack', 'stackbite', 'licenses']);
+const BUNDLE = 'bundle.json';
+
+async function readAt(file, offset, length) {
+  const bytes = Buffer.alloc(length);
+  const { bytesRead } = await file.read(bytes, 0, length, offset);
+  if (bytesRead !== length) fail('Truncated release archive');
+  return bytes;
+}
+// Top level is exactly workstack/ stackbite/ licenses/ and one bundle.json file; no links at all.
+function validateEntries(entries, windows) {
+  if (!entries.length || entries.length > LIMITS.members) fail('Invalid archive member count');
+  const names = new Map();
+  let expanded = 0, bundle = false;
+  for (const entry of entries) {
+    entry.name = memberPath(entry.name);
+    if (entry.kind !== 'file' && entry.kind !== 'directory') fail('Archive links and special members are not allowed');
+    const top = entry.name.split('/')[0];
+    if (entry.name === BUNDLE) {
+      if (entry.kind !== 'file') fail('bundle.json must be a regular file');
+      bundle = true;
+    } else if (!TOP_DIRECTORIES.includes(top) || (entry.name === top && entry.kind !== 'directory')) {
+      fail('Archive member is outside the WorkBite layout');
+    }
+    const key = windows ? entry.name.toLowerCase() : entry.name;
+    if (names.has(key)) fail('Duplicate archive member');
+    names.set(key, entry);
+    expanded += entry.size;
+    if (entry.size < 0 || entry.size > LIMITS.member || expanded > LIMITS.expanded) fail('Archive expansion exceeds limit');
+  }
+  if (!bundle) fail('Archive has no bundle.json');
+  for (const entry of entries) {
+    for (let parent = path.posix.dirname(entry.name); parent !== '.'; parent = path.posix.dirname(parent)) {
+      const ancestor = names.get(windows ? parent.toLowerCase() : parent);
+      if (ancestor && ancestor.kind !== 'directory') fail('Archive file is another member parent');
+    }
+  }
+  return entries;
+}
+async function zipEntries(archive) {
+  const file = await fs.open(archive, 'r');
+  const signal = AbortSignal.timeout(LIMITS.timeout);
+  try {
+    const size = (await file.stat()).size;
+    const tailStart = Math.max(0, size - 65557);
+    const tail = await readAt(file, tailStart, size - tailStart);
+    const end = tail.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]));
+    if (end < 0 || end + 22 > tail.length) fail('Invalid ZIP directory');
+    const count = tail.readUInt16LE(end + 10), directorySize = tail.readUInt32LE(end + 12), offset = tail.readUInt32LE(end + 16);
+    if (tail.readUInt16LE(end + 4) || tail.readUInt16LE(end + 6) || tail.readUInt16LE(end + 8) !== count
+        || count === 65535 || count > LIMITS.members || directorySize > 16 * 1024 * 1024
+        || offset + directorySize !== tailStart + end || end + 22 + tail.readUInt16LE(end + 20) !== tail.length) fail('Unsafe ZIP directory');
+    const central = await readAt(file, offset, directorySize);
+    const entries = [], ranges = [];
+    let position = 0, totalExpanded = 0;
+    for (let index = 0; index < count; index++) {
+      signal.throwIfAborted();
+      if (position + 46 > central.length || central.readUInt32LE(position) !== 0x02014b50) fail('Invalid ZIP member');
+      const flags = central.readUInt16LE(position + 8), method = central.readUInt16LE(position + 10);
+      const compressed = central.readUInt32LE(position + 20), expanded = central.readUInt32LE(position + 24);
+      totalExpanded += expanded;
+      if (totalExpanded > LIMITS.expanded) fail('ZIP total expansion exceeds limit');
+      const nameSize = central.readUInt16LE(position + 28), extraSize = central.readUInt16LE(position + 30), commentSize = central.readUInt16LE(position + 32);
+      const localOffset = central.readUInt32LE(position + 42), mode = central.readUInt32LE(position + 38) >>> 16;
+      if (!nameSize || nameSize > 1024 || position + 46 + nameSize + extraSize + commentSize > central.length
+          || central.readUInt16LE(position + 34) || (flags & ~0x080e) || ![0, 8].includes(method)
+          || expanded > LIMITS.member || ![0, 0o100000, 0o040000].includes(mode & 0o170000) || (mode & 0o7000)) fail('Unsupported ZIP member');
+      const rawName = central.subarray(position + 46, position + 46 + nameSize);
+      if (!(flags & 0x0800) && rawName.some(value => value > 127)) fail('Ambiguous ZIP filename encoding');
+      const name = utf8.decode(rawName);
+      const directory = name.endsWith('/');
+      if (directory && (expanded || compressed)) fail('Invalid ZIP directory member');
+      const directoryMode = (mode & 0o170000) === 0o040000 || !!(central.readUInt32LE(position + 38) & 16);
+      if (directoryMode && !directory) fail('ZIP directory identity mismatch');
+      const local = await readAt(file, localOffset, 30);
+      const localNameSize = local.readUInt16LE(26), localExtraSize = local.readUInt16LE(28);
+      const dataStart = localOffset + 30 + localNameSize + localExtraSize;
+      if (local.readUInt32LE(0) !== 0x04034b50 || local.readUInt16LE(6) !== flags || local.readUInt16LE(8) !== method
+          || localNameSize !== nameSize || dataStart + compressed > offset
+          || !(await readAt(file, localOffset + 30, localNameSize)).equals(rawName)) fail('ZIP local/central identity mismatch');
+      if (!(flags & 8) && (local.readUInt32LE(14) !== central.readUInt32LE(position + 16)
+          || local.readUInt32LE(18) !== compressed || local.readUInt32LE(22) !== expanded)) fail('ZIP local size mismatch');
+      if (!directory) {
+        // Bound the actual inflated bytes, not only the central-directory claim,
+        // before handing the same archive to the native extraction command.
+        if (method === 0 && compressed !== expanded) fail('Invalid stored ZIP size');
+        let actualSize = 0, crc = 0xffffffff;
+        const sink = new Writable({ write(chunk, encoding, callback) {
+          actualSize += chunk.length;
+          if (actualSize > expanded) return callback(new Error('ZIP expansion exceeds declared size'));
+          for (const byte of chunk) crc = (crc >>> 8) ^ crcTable[(crc ^ byte) & 255];
+          callback();
+        } });
+        if (compressed) {
+          const input = createReadStream(archive, { start: dataStart, end: dataStart + compressed - 1 });
+          if (method === 8) await pipeline(input, createInflateRaw(), sink, { signal });
+          else await pipeline(input, sink, { signal });
+        }
+        if (actualSize !== expanded || ((crc ^ 0xffffffff) >>> 0) !== central.readUInt32LE(position + 16)) fail('ZIP content size/CRC mismatch');
+      }
+      // Reject Unicode-path/ZIP64 extra fields: native tar must use the same name
+      // and sizes checked here, without a second interpretation of this entry.
+      for (const extra of [central.subarray(position + 46 + nameSize, position + 46 + nameSize + extraSize),
+        await readAt(file, localOffset + 30 + localNameSize, localExtraSize)]) {
+        for (let at = 0; at < extra.length;) {
+          if (at + 4 > extra.length) fail('Invalid ZIP extra field');
+          const kind = extra.readUInt16LE(at), length = extra.readUInt16LE(at + 2);
+          if (![0x5455, 0x7875].includes(kind) || at + 4 + length > extra.length) fail('Unsupported ZIP extension');
+          at += 4 + length;
+        }
+      }
+      ranges.push([localOffset, dataStart + compressed]);
+      entries.push({ name, kind: directory ? 'directory' : 'file', size: expanded });
+      position += 46 + nameSize + extraSize + commentSize;
+    }
+    if (position !== central.length) fail('Extra ZIP directory records');
+    ranges.sort((a, b) => a[0] - b[0]);
+    if (ranges.some((range, index) => index && range[0] < ranges[index - 1][1])) fail('Overlapping ZIP members');
+    return entries;
+  } finally { await file.close(); }
+}
+function tarNumber(bytes) {
+  const value = bytes.toString('ascii').replace(/\0.*$/, '').trim();
+  if (value && !/^[0-7]+$/.test(value)) fail('Unsupported TAR numeric field');
+  const result = Number.parseInt(value || '0', 8);
+  if (!Number.isSafeInteger(result)) fail('Invalid TAR size');
+  return result;
+}
+function tarText(bytes) { return utf8.decode(bytes.subarray(0, bytes.indexOf(0) < 0 ? bytes.length : bytes.indexOf(0))); }
+function paxFields(bytes) {
+  const fields = {};
+  for (let offset = 0; offset < bytes.length;) {
+    const space = bytes.indexOf(32, offset);
+    if (space < 0 || !/^\d+$/.test(bytes.subarray(offset, space).toString())) fail('Invalid TAR PAX length');
+    const length = Number(bytes.subarray(offset, space).toString());
+    if (!Number.isSafeInteger(length) || length <= space - offset + 2 || offset + length > bytes.length || bytes[offset + length - 1] !== 10) fail('Invalid TAR PAX record');
+    const record = utf8.decode(bytes.subarray(space + 1, offset + length - 1));
+    const equal = record.indexOf('=');
+    const key = record.slice(0, equal), value = record.slice(equal + 1);
+    if (equal < 1 || !['path', 'linkpath', 'mtime', 'atime', 'ctime'].includes(key) || Object.hasOwn(fields, key)) fail('Unsupported TAR PAX field');
+    fields[key] = value;
+    offset += length;
+  }
+  return fields;
+}
+async function tarEntries(archive) {
+  const file = await fs.open(archive, 'r');
+  try {
+    const total = (await file.stat()).size;
+    const entries = [];
+    let offset = 0, pax = null, headers = 0;
+    while (offset + 512 <= total) {
+      const header = await readAt(file, offset, 512);
+      offset += 512;
+      if (header.every(value => value === 0)) {
+        if (pax || offset + 512 > total) fail('Truncated TAR trailer');
+        for (let at = offset; at < total; at += 65536) {
+          if (!(await readAt(file, at, Math.min(65536, total - at))).every(value => value === 0)) fail('Extra TAR payload after trailer');
+        }
+        return entries;
+      }
+      if (++headers > LIMITS.members * 2) fail('Too many TAR headers');
+      if (header.subarray(257, 263).toString('ascii') !== 'ustar\0') fail('Unsupported TAR header format');
+      let checksum = 0;
+      for (let index = 0; index < 512; index++) checksum += index >= 148 && index < 156 ? 32 : header[index];
+      if (checksum !== tarNumber(header.subarray(148, 156))) fail('Invalid TAR checksum');
+      const size = tarNumber(header.subarray(124, 136));
+      const kind = String.fromCharCode(header[156]);
+      if (size > (kind === 'x' ? 65536 : LIMITS.member) || offset + Math.ceil(size / 512) * 512 > total
+          || tarNumber(header.subarray(100, 108)) & 0o7000) fail('Unsafe TAR size or permissions');
+      if (kind === 'x') {
+        if (pax) fail('Chained TAR PAX headers');
+        pax = paxFields(await readAt(file, offset, size));
+      } else {
+        if (!['\0', '0', '5', '2'].includes(kind) || (kind !== '0' && kind !== '\0' && size)) fail('Unsupported TAR member');
+        const prefix = tarText(header.subarray(345, 500));
+        const name = pax && Object.hasOwn(pax, 'path') ? pax.path : (prefix ? prefix + '/' : '') + tarText(header.subarray(0, 100));
+        entries.push({ name, kind: kind === '5' ? 'directory' : kind === '2' ? 'link' : 'file', size,
+          link: pax && Object.hasOwn(pax, 'linkpath') ? pax.linkpath : tarText(header.subarray(157, 257)) });
+        pax = null;
+      }
+      offset += Math.ceil(size / 512) * 512;
+    }
+    fail('TAR trailer is missing');
+  } finally { await file.close(); }
+}
+async function boundedGunzip(archive, destination) {
+  let size = 0;
+  const bounded = new Transform({ transform(chunk, encoding, callback) {
+    size += chunk.length;
+    callback(size > LIMITS.expanded ? new Error('TAR expansion exceeds limit') : null, chunk);
+  } });
+  await pipeline(createReadStream(archive), createGunzip(), bounded,
+    createWriteStream(destination, { flags: 'wx', mode: 0o600 }), { signal: AbortSignal.timeout(LIMITS.timeout) });
+}
+function nativeTar() {
+  return process.platform === 'win32' ? path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe') : '/usr/bin/tar';
+}
+async function extractArchive(archive, destination, spec, { spawnImpl = spawn } = {}) {
+  let input = archive;
+  const windows = spec.asset.endsWith('.zip');
+  if (!windows) { input = archive + '.tar'; await boundedGunzip(archive, input); }
+  const entries = windows ? await zipEntries(input) : await tarEntries(input);
+  validateEntries(entries, windows);
+  await new Promise((resolve, reject) => {
+    const child = spawnImpl(nativeTar(), ['-xf', input, '-C', destination, '--no-same-owner', '--no-same-permissions'],
+      { shell: false, stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
+    let errorBytes = 0;
+    const timer = setTimeout(() => { child.kill(); reject(new Error('Native tar extraction timed out')); }, LIMITS.timeout);
+    child.stderr.on('data', chunk => { errorBytes += chunk.length; if (errorBytes > 65536) { child.kill(); } });
+    child.once('error', () => { clearTimeout(timer); reject(new Error('Native tar is unavailable; install the operating system tar command')); });
+    child.once('close', code => { clearTimeout(timer); code === 0 ? resolve() : reject(new Error('Native tar rejected the release archive')); });
+  });
+  return entries;
+}
+module.exports = { validateEntries, zipEntries, tarEntries, extractArchive, nativeTar, TOP_DIRECTORIES, BUNDLE };

package/lib/cli.js

@@ -0,0 +1,74 @@
+'use strict';
+const path = require('node:path');
+const { fail } = require('./common');
+const { locations, releaseSpec, ensureInstalled, stageReporter, packageVersion } = require('./install');
+const { openSuite } = require('./runtime');
+
+const HELP = `WorkBite ${packageVersion} - Work Stack organizes the work. StackBite gets it moving.
+
+Usage:
+  workbite install                       download, verify and install the pinned native suite
+  workbite check                         verify the installed suite (no download, no processes)
+  workbite open --workspace ABS [--init] [--no-ui]
+                                         start or reuse this workspace's Work Stack owner and the
+                                         StackBite backend, then run the Work Stack terminal UI
+  workbite --version | --help
+
+open:
+  --workspace ABS  absolute workspace folder
+  --init           create a new Work Stack workspace in a new or empty folder
+  --no-ui          start or reuse the backends, print one JSON summary and exit
+
+The Work Stack owner and StackBite backend keep running after the UI exits, so
+agents continue. WorkBite never auto-updates, installs dependencies, approves
+provider trust or stops processes it cannot prove are its own.
+
+Locations (override with absolute WORKBITE_HOME / WORKBITE_STATE_DIR):
+  Windows  %LOCALAPPDATA%\\WorkBite\\app\\<version>   %LOCALAPPDATA%\\WorkBite\\state
+  Linux    $XDG_DATA_HOME/workbite/app/<version>  $XDG_STATE_HOME/workbite
+`;
+
+function parseArguments(argv) {
+  if (argv.length === 1 && ['--help', '-h', 'help'].includes(argv[0])) return { command: 'help' };
+  if (!argv.length) return { command: 'help' };
+  if (argv.length === 1 && ['--version', '-v', 'version'].includes(argv[0])) return { command: 'version' };
+  const [command, ...rest] = argv;
+  if ((command === 'install' || command === 'check') && !rest.length) return { command };
+  if (command === 'open') {
+    const options = { command, init: false, ui: true };
+    for (let index = 0; index < rest.length; index++) {
+      const argument = rest[index];
+      if (argument === '--init' && !options.init) options.init = true;
+      else if (argument === '--no-ui' && options.ui) options.ui = false;
+      else if (argument === '--workspace' && options.workspace === undefined && rest[index + 1] !== undefined
+          && !rest[index + 1].startsWith('--')) options.workspace = rest[++index];
+      else fail(`Unknown or repeated open option: ${String(argument).slice(0, 64)}. See workbite --help.`);
+    }
+    if (options.workspace === undefined) fail('workbite open needs --workspace ABS');
+    if (!path.isAbsolute(options.workspace)) fail('--workspace must be an absolute path');
+    return options;
+  }
+  fail(`Unknown command: ${String(command).slice(0, 64)}. See workbite --help.`);
+}
+
+async function main(argv = process.argv.slice(2), options = {}) {
+  const stdout = options.stdout || process.stdout, stderr = options.stderr || process.stderr;
+  const parsed = parseArguments(argv);
+  if (parsed.command === 'help') { stdout.write(HELP); return { code: 0, signal: null }; }
+  if (parsed.command === 'version') { stdout.write(`workbite ${packageVersion}\n`); return { code: 0, signal: null }; }
+  const environment = options.environment || process.env;
+  const platform = options.platform || process.platform;
+  const spec = releaseSpec(options.manifest || require('../release.json'), platform, options.arch || process.arch, options);
+  const where = locations(environment, platform);
+  const installed = await ensureInstalled(spec, { ...options, apps: options.apps || where.apps,
+    checkOnly: parsed.command === 'check', progress: options.progress || stageReporter(stderr) });
+  if (parsed.command === 'install' || parsed.command === 'check') {
+    stdout.write(JSON.stringify({ schema: 'workbite.install.v1', version: spec.version, target: spec.target,
+      home: installed.home, state: options.stateRoot || where.state }) + '\n');
+    return { code: 0, signal: null };
+  }
+  return openSuite({ installed, commands: options.commands, workspace: parsed.workspace, init: parsed.init, ui: parsed.ui,
+    stateRoot: options.stateRoot || where.state, environment, spawnImpl: options.spawnImpl, stdout, timeouts: options.timeouts });
+}
+
+module.exports = { main, parseArguments, HELP };

package/lib/common.js

@@ -0,0 +1,68 @@
+'use strict';
+// Archive/path primitives adapted from the StackBite npm bootstrapper (same
+// owner, proprietary); WorkBite keeps their bounds and refusal behaviour.
+const fs = require('node:fs/promises');
+const { createReadStream } = require('node:fs');
+const path = require('node:path');
+const { createHash, randomBytes } = require('node:crypto');
+
+const LIMITS = Object.freeze({ download: 1024 * 1024 * 1024, expanded: 2048 * 1024 * 1024,
+  member: 256 * 1024 * 1024, metadata: 8 * 1024 * 1024, members: 40000, timeout: 300000 });
+function fail(message) { throw new Error(message); }
+function memberPath(name) {
+  if (typeof name !== 'string' || !name || name.length > 1024 || /[\\:<>"|?*\x00-\x1f\x7f]/.test(name)) fail('Unsafe archive path');
+  const cleaned = name.endsWith('/') ? name.slice(0, -1) : name;
+  const parts = cleaned.split('/');
+  if (parts.some(part => !part || part === '.' || part === '..' || /[ .]$/.test(part)
+      || /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/i.test(part))) fail('Unsafe archive path');
+  return cleaned;
+}
+function inside(root, target) {
+  const relative = path.relative(root, target);
+  return relative !== '' && relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative);
+}
+async function hashFile(filename, maximum = LIMITS.member) {
+  const info = await fs.stat(filename);
+  if (!info.isFile() || info.size > maximum) fail('Release file exceeds its size limit');
+  const hash = createHash('sha256');
+  let size = 0;
+  for await (const chunk of createReadStream(filename)) {
+    size += chunk.length;
+    if (size > maximum) fail('Release file exceeds its size limit');
+    hash.update(chunk);
+  }
+  return hash.digest('hex');
+}
+async function readSmall(filename, maximum = LIMITS.metadata) {
+  const info = await fs.lstat(filename);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > maximum) fail('Unsafe or oversized metadata file');
+  return fs.readFile(filename);
+}
+async function exists(filename) {
+  try { await fs.lstat(filename); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+// Creates missing directories privately; every existing component must be a real directory.
+async function safeDirectory(directory) {
+  const parent = path.dirname(directory);
+  if (parent !== directory) await safeDirectory(parent);
+  if (!await exists(directory)) {
+    try { await fs.mkdir(directory, { mode: 0o700 }); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  }
+  const info = await fs.lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) fail('WorkBite directory path contains a link or non-directory');
+}
+// Same-directory temporary file + rename: readers see the old or the new document, never a partial one.
+async function writeAtomic(filename, bytes) {
+  const temporary = path.join(path.dirname(filename), `.${path.basename(filename)}.${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(); }
+  await fs.rename(temporary, filename);
+}
+async function readJson(filename, maximum = 65536) {
+  return JSON.parse((await readSmall(filename, maximum)).toString('utf8'));
+}
+const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const BACKEND_ID = /^[A-Za-z0-9_-]{1,128}$/;
+module.exports = { LIMITS, fail, memberPath, inside, hashFile, readSmall, exists, safeDirectory, writeAtomic, readJson,
+  sha256, UUID, BACKEND_ID };

package/lib/download.js

@@ -0,0 +1,53 @@
+'use strict';
+const https = require('node:https');
+const { createWriteStream } = require('node:fs');
+const { Transform } = require('node:stream');
+const { pipeline } = require('node:stream/promises');
+const { LIMITS, fail, hashFile } = require('./common');
+
+// GitHub release assets redirect to these hosts only; nothing else is followed.
+function secureURL(value) {
+  const url = new URL(value);
+  if (url.protocol !== 'https:' || url.username || url.password || (url.port && url.port !== '443')
+      || !['github.com', 'release-assets.githubusercontent.com', 'objects.githubusercontent.com'].includes(url.hostname)) {
+    fail('Release redirect is not an approved HTTPS origin');
+  }
+  return url;
+}
+async function download(spec, destination, { request = https.get, timeout = LIMITS.timeout } = {}) {
+  if (!Number.isSafeInteger(spec.size) || spec.size <= 0 || spec.size > LIMITS.download) fail('Invalid pinned download size');
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  let current = secureURL(spec.url);
+  try {
+    for (let redirects = 0; redirects <= 5; redirects++) {
+      const response = await new Promise((resolve, reject) => {
+        const req = request(current, { signal: controller.signal, headers: {
+          'User-Agent': 'WorkBite-npm-installer', 'Accept-Encoding': 'identity', Accept: 'application/octet-stream'
+        } }, resolve);
+        req.once('error', () => reject(new Error('Release download failed or timed out')));
+      });
+      if ([301, 302, 303, 307, 308].includes(response.statusCode)) {
+        const location = response.headers.location;
+        response.destroy();
+        if (redirects === 5 || typeof location !== 'string' || location.length > 4096) fail('Invalid release redirect');
+        current = secureURL(new URL(location, current).href);
+        continue;
+      }
+      if (response.statusCode !== 200 || (response.headers['content-encoding'] && response.headers['content-encoding'] !== 'identity')) {
+        response.destroy(); fail('Release download was not available');
+      }
+      const length = response.headers['content-length'];
+      if (length !== undefined && String(spec.size) !== length) { response.destroy(); fail('Release download size mismatch'); }
+      let size = 0;
+      const bounded = new Transform({ transform(chunk, encoding, callback) {
+        size += chunk.length;
+        callback(size > spec.size ? new Error('Release download exceeds pinned size') : null, chunk);
+      } });
+      await pipeline(response, bounded, createWriteStream(destination, { flags: 'wx', mode: 0o600 }), { signal: controller.signal });
+      if (size !== spec.size || await hashFile(destination, LIMITS.download) !== spec.sha256) fail('Release SHA-256 or size mismatch');
+      return;
+    }
+  } finally { clearTimeout(timer); }
+}
+module.exports = { download, secureURL };

package/lib/install.js

@@ -0,0 +1,215 @@
+'use strict';
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const { LIMITS, fail, memberPath, inside, hashFile, readSmall, exists, safeDirectory, sha256 } = require('./common');
+const { download } = require('./download');
+const { extractArchive, TOP_DIRECTORIES, BUNDLE } = require('./archive');
+const packageVersion = require('../package.json').version;
+
+const REPOSITORY = 'Shinick-Han/WorkBite-releases';
+const TARGETS = Object.freeze({ 'win32-x64': 'windows-x64', 'linux-x64': 'linux-x64' });
+const EXECUTABLES = Object.freeze({
+  workstack_engine: 'workstack/workstack-native-engine',
+  workstack_client: 'workstack/workstack-native-client',
+  workstack_tui: 'workstack/workstack-tui',
+  stackbite: 'stackbite/stackbite',
+});
+
+function absoluteOverride(environment, name) {
+  const value = environment[name];
+  if (value === undefined || value === '') return undefined;
+  if (!path.isAbsolute(value) || /[\x00-\x1f]/.test(value)) fail(`${name} must be an absolute path`);
+  return path.resolve(value);
+}
+// Per-user locations owned by WorkBite only; existing Work Stack/StackBite locations are never used.
+function locations(environment = process.env, platform = process.platform, home = os.homedir()) {
+  const windows = platform === 'win32';
+  const local = windows ? (environment.LOCALAPPDATA || path.join(home, 'AppData', 'Local')) : undefined;
+  const data = absoluteOverride(environment, 'WORKBITE_HOME') || (windows ? path.resolve(local, 'WorkBite')
+    : path.resolve(environment.XDG_DATA_HOME || path.join(environment.HOME || home, '.local', 'share'), 'workbite'));
+  const state = absoluteOverride(environment, 'WORKBITE_STATE_DIR') || (windows ? path.resolve(local, 'WorkBite', 'state')
+    : path.resolve(environment.XDG_STATE_HOME || path.join(environment.HOME || home, '.local', 'state'), 'workbite'));
+  return { apps: path.join(data, 'app'), state };
+}
+
+function platformTarget(platform = process.platform, arch = process.arch, runtime = {}) {
+  const key = `${platform}-${arch}`;
+  const target = TARGETS[key];
+  if (!target) fail(`WorkBite has no native release for ${key}; supported platforms are Windows x64 and Linux x64 (glibc 2.28+). Nothing was downloaded.`);
+  if (platform === 'linux' && (process.platform === 'linux' || Object.hasOwn(runtime, 'glibcVersionRuntime'))) {
+    const glibc = Object.hasOwn(runtime, 'glibcVersionRuntime')
+      ? runtime.glibcVersionRuntime : process.report.getReport().header.glibcVersionRuntime;
+    const match = typeof glibc === 'string' ? /^(\d+)\.(\d+)/.exec(glibc) : null;
+    if (!match) fail('WorkBite requires Linux x64 with glibc; Alpine/musl Linux is unsupported. Nothing was downloaded.');
+    if (Number(match[1]) < 2 || (Number(match[1]) === 2 && Number(match[2]) < 28)) {
+      fail(`WorkBite requires glibc 2.28 or newer; this system has ${glibc}. Nothing was downloaded.`);
+    }
+  }
+  return target;
+}
+
+function releaseSpec(manifest, platform = process.platform, arch = process.arch, runtime = {}) {
+  const target = platformTarget(platform, arch, runtime);
+  if (manifest.schema !== 'workbite.release.v1' || manifest.product !== 'WorkBite' || manifest.version !== packageVersion
+      || manifest.repository !== REPOSITORY || manifest.tag !== `v${manifest.version}`) fail('Invalid pinned WorkBite release identity');
+  const spec = manifest.platforms?.[target];
+  const asset = `workbite-${manifest.version}-${target}${platform === 'win32' ? '.zip' : '.tar.gz'}`;
+  if (!spec || spec.asset !== asset
+      || spec.url !== `https://github.com/${manifest.repository}/releases/download/${manifest.tag}/${asset}`) fail('Invalid pinned release asset');
+  if (spec.sha256 === null || spec.size === null || spec.bundleSha256 === null) {
+    fail(`This workbite ${manifest.version} package has no sealed ${target} release artifact yet. Nothing was downloaded.`);
+  }
+  if (![spec.sha256, spec.bundleSha256].every(value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value))
+      || !Number.isSafeInteger(spec.size) || spec.size <= 0 || spec.size > LIMITS.download) fail('Invalid pinned release asset');
+  return { asset, url: spec.url, sha256: spec.sha256, size: spec.size, bundleSha256: spec.bundleSha256,
+    platform, target, version: manifest.version };
+}
+
+function expectedExecutables(spec) {
+  const suffix = spec.platform === 'win32' ? '.exe' : '';
+  return Object.fromEntries(Object.entries(EXECUTABLES).map(([name, file]) => [name, file + suffix]));
+}
+function plainObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function sameKeys(value, keys) {
+  return plainObject(value) && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+
+// Full payload proof: pinned bundle.json bytes, then every regular file against its map, with no extras.
+async function validateBundle(directory, spec) {
+  const info = await fs.lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) fail('Installed WorkBite root is not a regular directory');
+  const root = await fs.realpath(directory);
+  const bundleBytes = await readSmall(path.join(root, BUNDLE));
+  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'
+      || 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)
+      || !plainObject(bundle.files)) fail('bundle.json identity or executable layout mismatch');
+  const expected = new Map();
+  for (const [name, digest] of Object.entries(bundle.files)) {
+    if (memberPath(name) !== name || name === BUNDLE || !TOP_DIRECTORIES.includes(name.split('/')[0])
+        || !name.includes('/') || typeof digest !== 'string' || !/^[a-f0-9]{64}$/.test(digest)) fail('Invalid bundle file entry');
+    const key = spec.platform === 'win32' ? name.toLowerCase() : name;
+    if (expected.has(key)) fail('Duplicate bundle file entry');
+    expected.set(key, { name, digest });
+  }
+  if (!expected.size || expected.size > LIMITS.members) fail('Invalid bundle file map');
+  for (const file of Object.values(executables)) if (!Object.hasOwn(bundle.files, file)) fail('Bundle executable is not in its file map');
+  let total = 0, entries = 0, seen = 0;
+  async function visit(current) {
+    for (const name of await fs.readdir(current)) {
+      if (++entries > LIMITS.members * 2) fail('Installed WorkBite has too many entries');
+      const target = path.join(current, name);
+      const relative = path.relative(root, target).split(path.sep).join('/');
+      memberPath(relative);
+      const entry = await fs.lstat(target);
+      if (entry.isSymbolicLink() || (!entry.isDirectory() && !entry.isFile())) fail('Installed WorkBite contains a link or special file');
+      if (entry.isDirectory()) {
+        if (current === root && !TOP_DIRECTORIES.includes(name)) fail('Installed WorkBite has an unexpected top-level directory');
+        await visit(target); continue;
+      }
+      if (relative === BUNDLE) continue;
+      const record = expected.get(spec.platform === 'win32' ? relative.toLowerCase() : relative);
+      if (!record || record.name !== relative) fail(`Installed file is not in bundle.json: ${relative}`);
+      total += entry.size;
+      if (total > LIMITS.expanded) fail('Installed WorkBite exceeds expansion limit');
+      if (await hashFile(target) !== record.digest) fail(`Installed file SHA-256 mismatch: ${relative}`);
+      seen++;
+    }
+  }
+  await visit(root);
+  if (seen !== expected.size) fail('Installed files disagree with bundle.json');
+  const paths = {};
+  for (const [name, file] of Object.entries(executables)) {
+    const executable = path.join(root, ...file.split('/'));
+    const handle = await fs.open(executable, 'r');
+    try {
+      const magic = Buffer.alloc(4);
+      if ((await handle.read(magic, 0, 4, 0)).bytesRead !== 4
+          || !(spec.platform === 'win32' ? magic.subarray(0, 2).equals(Buffer.from('MZ')) : magic.equals(Buffer.from([0x7f, 69, 76, 70])))) {
+        fail(`Invalid native executable identity: ${file}`);
+      }
+    } finally { await handle.close(); }
+    if (spec.platform === 'linux' && process.platform !== 'win32' && !((await fs.stat(executable)).mode & 0o111)) {
+      fail(`Native executable has no execute permission: ${file}`);
+    }
+    paths[name] = executable;
+  }
+  return { home: root, executables: paths, bundle };
+}
+
+function installName(spec) { return `${spec.version}-${spec.target}-${spec.sha256.slice(0, 16)}`; }
+
+// Windows cannot start bundle executables (or load their files) past MAX_PATH.
+const WINDOWS_MAX_PATH = 259;
+function checkPathBudget(target, bundle, spec) {
+  if (spec.platform !== 'win32') return;
+  const longest = Object.keys(bundle.files).reduce((best, name) => (name.length > best.length ? name : best), '');
+  if (path.join(target, longest).length > WINDOWS_MAX_PATH) {
+    fail(`WorkBite app folder path is too long for Windows (${path.join(target, longest).length} > ${WINDOWS_MAX_PATH} characters); set WORKBITE_HOME to a shorter absolute folder.`);
+  }
+}
+
+// A version directory is published once by rename and never rewritten; reuse revalidates it fully.
+async function ensureInstalled(spec, { apps, downloadImpl = download, extractImpl = extractArchive,
+  checkOnly = false, progress = () => {} } = {}) {
+  apps = path.resolve(apps);
+  const target = path.join(apps, installName(spec));
+  if (await exists(target)) {
+    progress('validate');
+    const installed = await validateBundle(target, spec);
+    checkPathBudget(target, installed.bundle, spec);
+    progress('ready');
+    return installed;
+  }
+  if (checkOnly) fail('WorkBite is not installed for this package version; run workbite install.');
+  await safeDirectory(apps);
+  const staging = await fs.mkdtemp(path.join(apps, '.staging-'));
+  try {
+    const archive = path.join(staging, spec.asset), extraction = path.join(staging, 'payload');
+    await fs.mkdir(extraction, { mode: 0o700 });
+    progress('download');
+    await downloadImpl(spec, archive);
+    progress('archive');
+    if ((await fs.stat(archive)).size !== spec.size || await hashFile(archive, LIMITS.download) !== spec.sha256) fail('Pinned archive SHA-256 or size mismatch');
+    progress('extract');
+    await extractImpl(archive, extraction, spec);
+    progress('validate');
+    checkPathBudget(target, (await validateBundle(extraction, spec)).bundle, spec);
+    progress('publish');
+    try { await fs.rename(extraction, target); }
+    catch (error) {
+      // A concurrent installer may have published the same immutable version first.
+      if (!await exists(target)) throw error;
+    }
+    progress('validate-published');
+    const installed = await validateBundle(target, spec);
+    progress('ready');
+    return installed;
+  } finally {
+    // Only this invocation's mkdtemp staging directory is ever removed.
+    if (!inside(apps, staging) || path.dirname(staging) !== apps) fail('Unsafe staging cleanup path');
+    await fs.rm(staging, { recursive: true, force: true });
+  }
+}
+
+function stageReporter(stderr) {
+  const messages = {
+    download: 'Downloading pinned WorkBite release...',
+    archive: 'Verifying archive...',
+    extract: 'Extracting...',
+    validate: 'Validating installed files...',
+    publish: 'Publishing version directory...',
+    'validate-published': 'Validating published version...',
+    ready: 'Verified WorkBite release is ready.',
+  };
+  return stage => stderr.write(`WorkBite: ${messages[stage]}\n`);
+}
+
+module.exports = { REPOSITORY, TARGETS, EXECUTABLES, locations, platformTarget, releaseSpec, expectedExecutables,
+  validateBundle, ensureInstalled, installName, stageReporter, packageVersion };

package/lib/runtime.js

@@ -0,0 +1,402 @@
+'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 { 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 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 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') };
+}
+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);
+}
+function runOnce(file, args, environment, timeout = 120000, execImpl = execFile) {
+  return new Promise(resolve => {
+    execImpl(file, args, { env: environment, shell: false, windowsHide: true, timeout, maxBuffer: 1024 * 1024, encoding: 'utf8' },
+      (error, stdout, stderr) => resolve({ error, stdout: stdout || '', stderr: stderr || '' }));
+  });
+}
+async function initializeWorkspace(commands, workspace, environment) {
+  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);
+  let record;
+  try { record = JSON.parse(result.stdout.trim()); } catch { record = null; }
+  if (result.error || record?.state !== 'initialized' || record.workspace_uid !== uid) {
+    fail(`Work Stack init refused this folder: ${boundedText(result.stderr) || 'no ready record'}`);
+  }
+  return uid;
+}
+
+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) => {
+    const payload = body === undefined ? undefined : Buffer.from(JSON.stringify(body));
+    const req = http.request(url, { method, agent: false, timeout,
+      headers: { ...headers, ...(payload ? { 'Content-Type': 'application/json', 'Content-Length': payload.length } : {}) } },
+    response => {
+      const chunks = [];
+      let size = 0;
+      response.on('data', chunk => { size += chunk.length; if (size > 1024 * 1024) req.destroy(); else chunks.push(chunk); });
+      response.on('end', () => {
+        let parsed = null;
+        try { parsed = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { parsed = null; }
+        resolve({ status: response.statusCode, body: parsed });
+      });
+      response.on('error', reject);
+    });
+    req.on('timeout', () => req.destroy(new Error('request timed out')));
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+// Owner identity is proven only by the private lifecycle token this WorkBite generated.
+async function engineIdentity(endpoint, token, workspaceUid) {
+  if (typeof endpoint !== 'string' || !LOOPBACK.test(endpoint) || typeof token !== 'string' || !token) return false;
+  try {
+    const answer = await request(new URL('/api/v1/native-runtime/identity', endpoint), { headers: { 'X-WorkStack-Native-Token': token } });
+    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) {
+  if (typeof url !== 'string' || !LOOPBACK.test(url)) return false;
+  const token = await stackbiteToken(stateDir);
+  if (!token) return false;
+  try {
+    const answer = await request(new URL('/api/backend/status', url), { headers: { 'X-Office-Token': token } });
+    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) {
+  let ended = false;
+  exited.then(() => { ended = true; });
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const value = await probe();
+    if (value) return value;
+    if (ended) fail(`${what} exited during startup; see ${log}`);
+    await new Promise(resolve => setTimeout(resolve, 150));
+  }
+  fail(`${what} did not become ready in time; it was left running. See ${log}`);
+}
+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. Records are never cleared and 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 { return await readJson(file); } 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');
+
+async function ensureEngine({ commands, workspace, uid, layout, environment, spawnImpl, 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 saved = await savedRecord(recordPath, 'Work Stack owner');
+  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)) {
+      fail(`The Work Stack owner record ${recordPath} is invalid for this workspace; WorkBite does not replace it. ${RECOVERY}`);
+    }
+    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 engineIdentity(endpoint, saved.token, uid)) {
+      fail(`The Work Stack owner recorded in ${recordPath} could not be authenticated (still starting, or stopped). ${RECOVERY}`);
+    }
+    if (saved.state === 'starting') await writeAtomic(recordPath, recordBytes({ ...saved, state: 'ready', endpoint }));
+    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') };
+  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 ready = await waitFor(() => readyRecord(log), exited, timeout, 'Work Stack native owner', log);
+  if (ready.workspace_uid !== uid || ready.protocol_version !== 1 || !LOOPBACK.test(ready.endpoint)
+      || !await engineIdentity(ready.endpoint, intent.token, uid)) fail(`Work Stack native owner identity was not proven; 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 }) {
+  const recordPath = layout.stackbiteRecord;
+  const logFor = launch => path.join(layout.logs, `stackbite-backend-${launch}.log`);
+  const saved = await savedRecord(recordPath, 'StackBite backend');
+  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}`);
+    }
+    if (!await stackbiteIdentity(saved.url, layout.stackbite, backendId)) {
+      fail(`The StackBite backend recorded in ${recordPath} could not be authenticated (still starting, or stopped). ${RECOVERY}`);
+    }
+    if (saved.state === 'starting') await writeAtomic(recordPath, recordBytes({ ...saved, state: 'ready' }));
+    return { url: saved.url, reused: true, pid: saved.pid };
+  }
+  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 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.
+  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),
+    cwd: home, log, spawnImpl });
+  await writeAtomic(recordPath, recordBytes({ ...intent, pid: child.pid }));
+  await waitFor(() => stackbiteIdentity(url, layout.stackbite, backendId), exited, timeout, 'StackBite backend', log);
+  await writeAtomic(recordPath, recordBytes({ ...intent, pid: child.pid, state: 'ready' }));
+  return { url, reused: false, pid: child.pid };
+}
+
+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);
+}
+
+// One opener at a time per state; a lock older than the startup bound is set aside, never deleted.
+async function withLock(file, action, { wait = 180000, stale = 300000 } = {}) {
+  const deadline = Date.now() + wait;
+  let handle;
+  for (;;) {
+    try { handle = await fs.open(file, 'wx', 0o600); break; } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      try {
+        if (Date.now() - (await fs.stat(file)).mtimeMs > stale) {
+          await fs.rename(file, `${file}.stale-${randomBytes(6).toString('hex')}`);
+          continue;
+        }
+      } catch (inner) { if (inner.code !== 'ENOENT') throw inner; continue; }
+      if (Date.now() > deadline) fail('Another WorkBite open is still starting this state; try again shortly.');
+      await new Promise(resolve => setTimeout(resolve, 200));
+    }
+  }
+  try {
+    await handle.writeFile(`${process.pid}\n`);
+    return await action();
+  } finally {
+    await handle.close();
+    await fs.unlink(file).catch(() => {});
+  }
+}
+
+function uiEnvironment(base, { executables, layout, endpoint, uid, backendId }) {
+  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);
+}
+
+function runForeground(command, args, environment, { spawnImpl = spawn, signalSource = process } = {}) {
+  return new Promise((resolve, reject) => {
+    const [file, ...prefix] = command;
+    const child = spawnImpl(file, [...prefix, ...args], { env: environment, stdio: 'inherit', shell: false });
+    const handlers = new Map();
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+      const handler = () => child.kill(signal);
+      handlers.set(signal, handler);
+      signalSource.on(signal, handler);
+    }
+    const cleanup = () => { for (const [signal, handler] of handlers) signalSource.removeListener(signal, handler); };
+    child.once('error', () => { cleanup(); reject(new Error('Cannot start the verified Work Stack terminal UI')); });
+    child.once('exit', (code, signal) => { cleanup(); resolve({ code, signal }); });
+  });
+}
+
+// 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 = {} }) {
+  workspace = checkedWorkspace(workspace);
+  commands = commands || Object.fromEntries(Object.entries(installed.executables).map(([name, file]) => [name, [file]]));
+  const layout = stateLayout(path.resolve(stateRoot));
+  await prepareState(layout);
+  const base = cleanEnvironment(environment);
+  const engineEnvironment = { ...base, WORK_STACK_RUNTIME: layout.workstackRuntime };
+  const session = await withLock(layout.lock, async () => {
+    const uid = init ? await initializeWorkspace(commands, workspace, engineEnvironment) : await readWorkspaceUid(workspace);
+    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 });
+    await writeDockConfig(layout, stackbite.url);
+    return { uid, backendId, engine, stackbite };
+  });
+  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 };
+  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 });
+  return { ...result, summary };
+}
+
+module.exports = { cleanEnvironment, stateLayout, prepareState, ensureBackendId, workspaceKey, readWorkspaceUid,
+  initializeWorkspace, engineIdentity, stackbiteIdentity, freePort, ensureEngine, ensureStackbite, writeDockConfig,
+  withLock, uiEnvironment, openSuite, RESERVED_PORTS };

package/package.json

@@ -1,6 +1,29 @@
-{
-  "name": "workbite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "workbite",
+  "version": "0.1.0",
+  "description": "WorkBite (Work Stack + StackBite) verified native suite installer and launcher",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [
+    "win32",
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "bin": {
+    "workbite": "bin/workbite.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "release.json",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "homepage": "https://github.com/Shinick-Han/WorkBite-releases"
+}

package/release.json

@@ -0,0 +1,23 @@
+{
+  "schema": "workbite.release.v1",
+  "product": "WorkBite",
+  "version": "0.1.0",
+  "repository": "Shinick-Han/WorkBite-releases",
+  "tag": "v0.1.0",
+  "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"
+    },
+    "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"
+    }
+  }
+}