workbite 0.1.18 → 0.1.20

package/lib/startup-lock.js

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

package/lib/transfer.js

@@ -1,113 +1,113 @@
-'use strict';
-// Files only: the native client/owner owns all transfer HTTP, graph validation and commits.
-const fs = require('node:fs/promises');
-const path = require('node:path');
-const { constants } = require('node:fs');
-const { randomBytes } = require('node:crypto');
-const { fail, UUID } = require('./common');
-
-const MAX_TRANSFER_BYTES = 1024 * 1024;
-const DIGEST = /^sha256:[0-9a-f]{64}$/;
-const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
-function localPath(filename) {
-  if (typeof filename !== 'string' || !filename || /[\x00-\x1f]/.test(filename)
-      || /^[a-z][a-z0-9+.-]*:\/\//i.test(filename) || /^(?:\\\\|\/\/)/.test(filename)) fail('Transfer files must be local filesystem paths');
-  return path.resolve(filename);
-}
-// Fail closed on links in the requested path. Do not create missing output directories.
-async function realDirectory(directory, io = fs) {
-  const parent = path.dirname(directory);
-  if (parent !== directory) await realDirectory(parent, io);
-  const info = await io.lstat(directory);
-  if (!info.isDirectory() || info.isSymbolicLink()) fail('Transfer path contains a link or non-directory');
-}
-async function outputPath(filename, io = fs) {
-  const target = localPath(filename);
-  await realDirectory(path.dirname(target), io);
-  try { await io.lstat(target); } catch (error) { if (error.code === 'ENOENT') return target; throw error; }
-  fail('Transfer output already exists; choose a new file (overwrite is not supported)');
-}
-function archive(value, workspaceUid) {
-  if (!plain(value) || value.format !== 'workbite.task-transfer.v1'
-      || typeof value.source_workspace_uid !== 'string' || !UUID.test(value.source_workspace_uid)
-      || typeof value.source_digest !== 'string' || !DIGEST.test(value.source_digest)
-      || !Array.isArray(value.tasks) || !value.tasks.every(plain)
-      || !Array.isArray(value.objectives) || !value.objectives.every(plain)) fail('Invalid workbite.task-transfer.v1 archive');
-  if (workspaceUid !== undefined && value.source_workspace_uid !== workspaceUid) fail('Export archive does not match the bound source workspace');
-  if (Buffer.byteLength(JSON.stringify(value)) > MAX_TRANSFER_BYTES) fail(`Transfer archive exceeds ${MAX_TRANSFER_BYTES} bytes`);
-  return value;
-}
-async function readArchive(filename, io = fs) {
-  const target = localPath(filename);
-  await realDirectory(path.dirname(target), io);
-  const before = await io.lstat(target);
-  if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_TRANSFER_BYTES) fail('Transfer input must be a regular file of at most 1048576 bytes');
-  const handle = await io.open(target, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
-  try {
-    const info = await handle.stat();
-    if (!info.isFile() || info.size > MAX_TRANSFER_BYTES || info.ino !== before.ino || info.dev !== before.dev) fail('Transfer input changed while opening');
-    // Read at most the bound plus one byte, even if another process grows the file.
-    const bytes = Buffer.alloc(MAX_TRANSFER_BYTES + 1);
-    let size = 0;
-    while (size < bytes.length) {
-      const read = await handle.read(bytes, size, bytes.length - size, null);
-      if (!read.bytesRead) break;
-      size += read.bytesRead;
-    }
-    if (size > MAX_TRANSFER_BYTES) fail(`Transfer archive exceeds ${MAX_TRANSFER_BYTES} bytes`);
-    let text, value;
-    try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, size)); value = JSON.parse(text); }
-    catch { fail('Transfer input must contain valid UTF-8 JSON'); }
-    archive(value);
-    return text;
-  } finally { await handle.close(); }
-}
-// Publish with an atomic hard link: rename would overwrite an existing destination on POSIX.
-// The private temporary file is in the same directory; an unsupported link is a safe refusal.
-async function writePrivate(filename, value, io = fs) {
-  const target = await outputPath(filename, io);
-  const bytes = Buffer.from(JSON.stringify(value));
-  if (bytes.length > MAX_TRANSFER_BYTES) fail(`Transfer output exceeds ${MAX_TRANSFER_BYTES} bytes`);
-  const temporary = path.join(path.dirname(target), `.workbite-transfer-${randomBytes(16).toString('hex')}.tmp`);
-  let handle;
-  try {
-    handle = await io.open(temporary, 'wx', 0o600);
-    await handle.writeFile(bytes);
-    await handle.sync();
-    await handle.close(); handle = null;
-    // Recheck the directory before publishing; link refuses even a raced-in destination.
-    await realDirectory(path.dirname(target), io);
-    await io.link(temporary, target);
-  } finally {
-    if (handle) await handle.close();
-    await io.unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; });
-  }
-  return target;
-}
-function resultData(result, command, uid, intent) {
-  if (typeof result.stdout !== 'string' || Buffer.byteLength(result.stdout) > MAX_TRANSFER_BYTES + 8192) fail('Invalid native transfer output');
-  let envelope;
-  try { envelope = JSON.parse(result.stdout); } catch { fail('Invalid native transfer envelope'); }
-  if (!plain(envelope) || envelope.contract !== 'workstack.cli.v1' || !plain(envelope.data)
-      || envelope.error !== undefined || envelope.meta?.command !== `agent.${command}` || envelope.meta?.workspace_uid !== uid
-      || (intent !== undefined && envelope.meta?.intent_id !== intent)) fail('Native transfer output does not match this workspace, command and intent');
-  return envelope.data;
-}
-function idMap(value) {
-  // The owner emits maps by source authority ID; values are generated target display IDs.
-  if (!plain(value) || Object.keys(value).some(key => !['tasks', 'task_uids', 'objectives', 'key_results'].includes(key))) fail('Invalid native transfer id_map');
-  for (const [kind, mapping] of Object.entries(value)) {
-    if (!plain(mapping)) fail('Invalid native transfer id_map');
-    for (const [source, target] of Object.entries(mapping)) {
-      if (!source || /[\x00-\x1f]/.test(source)) fail(`Invalid native transfer ${kind} mapping`);
-      if (kind === 'key_results') {
-        if (!plain(target) || Object.entries(target).some(([key, id]) => !key || /[\x00-\x1f]/.test(key)
-            || typeof id !== 'string' || !id || /[\x00-\x1f]/.test(id))) fail('Invalid native transfer key_results mapping');
-      } else if (typeof target !== 'string' || !target || /[\x00-\x1f]/.test(target)
-          || (kind === 'task_uids' && !UUID.test(target))) fail(`Invalid native transfer ${kind} mapping`);
-    }
-  }
-  if (!plain(value.tasks)) fail('Native transfer id_map requires tasks');
-  return value;
-}
-module.exports = { MAX_TRANSFER_BYTES, DIGEST, readArchive, archive, outputPath, writePrivate, resultData, idMap };
+'use strict';
+// Files only: the native client/owner owns all transfer HTTP, graph validation and commits.
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { constants } = require('node:fs');
+const { randomBytes } = require('node:crypto');
+const { fail, UUID } = require('./common');
+
+const MAX_TRANSFER_BYTES = 1024 * 1024;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+function localPath(filename) {
+  if (typeof filename !== 'string' || !filename || /[\x00-\x1f]/.test(filename)
+      || /^[a-z][a-z0-9+.-]*:\/\//i.test(filename) || /^(?:\\\\|\/\/)/.test(filename)) fail('Transfer files must be local filesystem paths');
+  return path.resolve(filename);
+}
+// Fail closed on links in the requested path. Do not create missing output directories.
+async function realDirectory(directory, io = fs) {
+  const parent = path.dirname(directory);
+  if (parent !== directory) await realDirectory(parent, io);
+  const info = await io.lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) fail('Transfer path contains a link or non-directory');
+}
+async function outputPath(filename, io = fs) {
+  const target = localPath(filename);
+  await realDirectory(path.dirname(target), io);
+  try { await io.lstat(target); } catch (error) { if (error.code === 'ENOENT') return target; throw error; }
+  fail('Transfer output already exists; choose a new file (overwrite is not supported)');
+}
+function archive(value, workspaceUid) {
+  if (!plain(value) || value.format !== 'workbite.task-transfer.v1'
+      || typeof value.source_workspace_uid !== 'string' || !UUID.test(value.source_workspace_uid)
+      || typeof value.source_digest !== 'string' || !DIGEST.test(value.source_digest)
+      || !Array.isArray(value.tasks) || !value.tasks.every(plain)
+      || !Array.isArray(value.objectives) || !value.objectives.every(plain)) fail('Invalid workbite.task-transfer.v1 archive');
+  if (workspaceUid !== undefined && value.source_workspace_uid !== workspaceUid) fail('Export archive does not match the bound source workspace');
+  if (Buffer.byteLength(JSON.stringify(value)) > MAX_TRANSFER_BYTES) fail(`Transfer archive exceeds ${MAX_TRANSFER_BYTES} bytes`);
+  return value;
+}
+async function readArchive(filename, io = fs) {
+  const target = localPath(filename);
+  await realDirectory(path.dirname(target), io);
+  const before = await io.lstat(target);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_TRANSFER_BYTES) fail('Transfer input must be a regular file of at most 1048576 bytes');
+  const handle = await io.open(target, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > MAX_TRANSFER_BYTES || info.ino !== before.ino || info.dev !== before.dev) fail('Transfer input changed while opening');
+    // Read at most the bound plus one byte, even if another process grows the file.
+    const bytes = Buffer.alloc(MAX_TRANSFER_BYTES + 1);
+    let size = 0;
+    while (size < bytes.length) {
+      const read = await handle.read(bytes, size, bytes.length - size, null);
+      if (!read.bytesRead) break;
+      size += read.bytesRead;
+    }
+    if (size > MAX_TRANSFER_BYTES) fail(`Transfer archive exceeds ${MAX_TRANSFER_BYTES} bytes`);
+    let text, value;
+    try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, size)); value = JSON.parse(text); }
+    catch { fail('Transfer input must contain valid UTF-8 JSON'); }
+    archive(value);
+    return text;
+  } finally { await handle.close(); }
+}
+// Publish with an atomic hard link: rename would overwrite an existing destination on POSIX.
+// The private temporary file is in the same directory; an unsupported link is a safe refusal.
+async function writePrivate(filename, value, io = fs) {
+  const target = await outputPath(filename, io);
+  const bytes = Buffer.from(JSON.stringify(value));
+  if (bytes.length > MAX_TRANSFER_BYTES) fail(`Transfer output exceeds ${MAX_TRANSFER_BYTES} bytes`);
+  const temporary = path.join(path.dirname(target), `.workbite-transfer-${randomBytes(16).toString('hex')}.tmp`);
+  let handle;
+  try {
+    handle = await io.open(temporary, 'wx', 0o600);
+    await handle.writeFile(bytes);
+    await handle.sync();
+    await handle.close(); handle = null;
+    // Recheck the directory before publishing; link refuses even a raced-in destination.
+    await realDirectory(path.dirname(target), io);
+    await io.link(temporary, target);
+  } finally {
+    if (handle) await handle.close();
+    await io.unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  }
+  return target;
+}
+function resultData(result, command, uid, intent) {
+  if (typeof result.stdout !== 'string' || Buffer.byteLength(result.stdout) > MAX_TRANSFER_BYTES + 8192) fail('Invalid native transfer output');
+  let envelope;
+  try { envelope = JSON.parse(result.stdout); } catch { fail('Invalid native transfer envelope'); }
+  if (!plain(envelope) || envelope.contract !== 'workstack.cli.v1' || !plain(envelope.data)
+      || envelope.error !== undefined || envelope.meta?.command !== `agent.${command}` || envelope.meta?.workspace_uid !== uid
+      || (intent !== undefined && envelope.meta?.intent_id !== intent)) fail('Native transfer output does not match this workspace, command and intent');
+  return envelope.data;
+}
+function idMap(value) {
+  // The owner emits maps by source authority ID; values are generated target display IDs.
+  if (!plain(value) || Object.keys(value).some(key => !['tasks', 'task_uids', 'objectives', 'key_results'].includes(key))) fail('Invalid native transfer id_map');
+  for (const [kind, mapping] of Object.entries(value)) {
+    if (!plain(mapping)) fail('Invalid native transfer id_map');
+    for (const [source, target] of Object.entries(mapping)) {
+      if (!source || /[\x00-\x1f]/.test(source)) fail(`Invalid native transfer ${kind} mapping`);
+      if (kind === 'key_results') {
+        if (!plain(target) || Object.entries(target).some(([key, id]) => !key || /[\x00-\x1f]/.test(key)
+            || typeof id !== 'string' || !id || /[\x00-\x1f]/.test(id))) fail('Invalid native transfer key_results mapping');
+      } else if (typeof target !== 'string' || !target || /[\x00-\x1f]/.test(target)
+          || (kind === 'task_uids' && !UUID.test(target))) fail(`Invalid native transfer ${kind} mapping`);
+    }
+  }
+  if (!plain(value.tasks)) fail('Native transfer id_map requires tasks');
+  return value;
+}
+module.exports = { MAX_TRANSFER_BYTES, DIGEST, readArchive, archive, outputPath, writePrivate, resultData, idMap };

package/lib/update.js

@@ -0,0 +1,86 @@
+'use strict';
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const { execFile } = require('node:child_process');
+const { fail, readJson } = require('./common');
+const { platformTarget, locations, releaseSpec, ensureInstalled, stageReporter } = require('./install');
+
+const REGISTRY = '--registry=https://registry.npmjs.org/';
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const NEXT = 'Running owners, Seats and Phone were not switched or stopped; their versions were not inspected. Next run workbite status --json and workbite doctor --json. Before workbite open, ask the operator to identify the exact owners/backend/host/boot and account for active Seats, preserve private records, then perform the authenticated component-specific handover. See docs/STARTUP-TROUBLESHOOTING.md#operator-handover-and-preserved-evidence (ask your maintainer for this guide if unavailable). Never clear locks or unknown intents; closing the UI leaves backends running.';
+function compare(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string' || !VERSION.test(a) || !VERSION.test(b)) fail('Update requires canonical stable versions (major.minor.patch).');
+  const left = a.split('.').map(BigInt), right = b.split('.').map(BigInt);
+  for (let i = 0; i < 3; i++) if (left[i] !== right[i]) return left[i] > right[i] ? 1 : -1;
+  return 0;
+}
+
+// Only fixed words and validated stable versions enter cmd.exe; paths/output never do.
+// npm.cmd needs cmd.exe on Windows; never pass it directly to execFile.
+async function npm(args, { platform, environment, npmExecImpl = execFile }) {
+  if (args.some(value => !/^[a-zA-Z0-9@./:=_-]+$/.test(value))) fail('Unsafe internal npm argument');
+  const windows = platform === 'win32';
+  const command = windows ? path.join(environment.SystemRoot || 'C:\\Windows', 'System32', 'cmd.exe') : 'npm';
+  const argv = windows ? ['/d', '/s', '/c', `npm.cmd ${args.join(' ')}`] : args;
+  return new Promise((resolve, reject) => {
+    npmExecImpl(command, argv, { cwd: os.tmpdir(), env: environment, shell: false, windowsHide: true,
+      timeout: args[0] === 'install' ? 300000 : 30000, killSignal: 'SIGKILL', maxBuffer: 64 * 1024,
+      encoding: 'utf8' }, (error, stdout) => {
+      if (error) reject(new Error(`npm ${args[0]} failed or timed out. Check npm availability, permissions, network and certificate trust. No automatic retry was made.`));
+      else resolve(String(stdout).trim());
+    });
+  });
+}
+
+async function runUpdate(options = {}) {
+  const { environment = process.env, platform = process.platform, arch = process.arch,
+    stdout = process.stdout, stderr = process.stderr, launcherRoot = path.join(__dirname, '..') } = options;
+  platformTarget(platform, arch, options);
+  const run = args => npm(args, { ...options, environment, platform });
+  let latest;
+  try { latest = JSON.parse(await run(['view', 'workbite@latest', 'version', '--json', REGISTRY])); }
+  catch { fail('Could not resolve official npm workbite@latest. Check npm/network/certificate trust; nothing was installed.'); }
+  if (typeof latest !== 'string' || !VERSION.test(latest)) fail('Official npm latest is not a canonical stable version; nothing was installed.');
+  const current = (await readJson(path.join(launcherRoot, 'package.json'), 16384)).version;
+  if (compare(latest, current) < 0) fail(`Official latest ${latest} is older than this launcher ${current}; refusing downgrade.`);
+  if (latest === current) {
+    stdout.write(`WorkBite launcher ${current} is already official latest; no installation performed. Running runtime version was not inspected or changed.\n`);
+    return { code: 0, signal: null };
+  }
+  const globalRoot = await run(['root', '--global']);
+  if (!path.isAbsolute(globalRoot) || /[\r\n\x00]/.test(globalRoot)) fail('npm returned an invalid global root; nothing was installed.');
+  const destination = path.join(globalRoot, 'workbite');
+  let globalHome;
+  try { globalHome = await fs.realpath(destination); } catch { /* local/npx install */ }
+  if (!globalHome || globalHome !== await fs.realpath(launcherRoot)) {
+    fail(`This is a local/npx/source launcher. No global package was changed. To install globally, run npm install -g workbite@${latest} --registry=https://registry.npmjs.org/, then use that global workbite install and workbite check. Local project copies require an explicit project dependency update.`);
+  }
+  const oldManifest = await readJson(path.join(launcherRoot, 'release.json'));
+  const oldSpec = releaseSpec(oldManifest, platform, arch, options, current);
+  const apps = options.apps || locations(environment, platform).apps;
+  stderr.write(`Updating global launcher ${current} to ${latest}; running runtime remains unchanged.\n`);
+  try {
+    await run(['install', '--global', `workbite@${latest}`, REGISTRY, '--ignore-scripts', '--no-audit', '--no-fund', '--fetch-retries=0']);
+  } catch (error) {
+    fail(`${error.message} Global npm installation outcome may be partial or unknown (a child may still finish). Inspect npm ls -g workbite --depth=0 and workbite --version before any retry. ${NEXT}`);
+  }
+  try {
+    const installedPackage = await readJson(path.join(destination, 'package.json'), 16384);
+    if (installedPackage.name !== 'workbite' || installedPackage.version !== latest) fail('Global package does not match the requested version; possible concurrent update.');
+    const manifest = await readJson(path.join(destination, 'release.json'));
+    // Validate both pins, including launcher-only releases reusing an older native artifact.
+    for (const host of ['win32', 'linux']) releaseSpec(manifest, host, 'x64', { glibcVersionRuntime: '2.28' }, latest);
+    const spec = releaseSpec(manifest, platform, arch, options, latest);
+    if (compare(spec.version, oldSpec.version) < 0) fail('New launcher pins an older native suite; refusing native downgrade.');
+    const installed = await ensureInstalled(spec, { ...options, apps,
+      progress: options.progress || stageReporter(stderr) });
+    const finalPackage = await readJson(path.join(destination, 'package.json'), 16384);
+    if (finalPackage.name !== 'workbite' || finalPackage.version !== latest) fail('Global launcher changed during staging; inspect the concurrent update.');
+    stdout.write(`Installed global launcher ${latest}; verified native suite ${spec.version} staged at ${installed.home}.\n${NEXT}\n`);
+    return { code: 0, signal: null };
+  } catch (error) {
+    fail(`npm installation finished, but matching native staging/verification failed: ${error.message} Inspect workbite --version and npm ls -g workbite --depth=0. After resolving the cause, use the global workbite install then workbite check; do not open it yet. ${NEXT}`);
+  }
+}
+module.exports = { runUpdate, compare, npm };

package/package.json

@@ -1,30 +1,35 @@
-{
-  "name": "workbite",
-  "version": "0.1.18",
-  "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/",
-    "skills/",
-    "release.json",
-    "README.md"
-  ],
-  "scripts": {
-    "test": "node --test test/*.test.js"
-  },
-  "homepage": "https://github.com/Shinick-Han/WorkBite-releases"
-}
+{
+  "name": "workbite",
+  "version": "0.1.20",
+  "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/",
+    "skills/",
+    "release.json",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "homepage": "https://github.com/Shinick-Han/WorkBite-releases",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Shinick-Han/WorkBite.git",
+    "directory": "packaging/npm"
+  }
+}

package/release.json

@@ -1,17 +1,24 @@
-{
-  "launcherVersion": "0.1.18",
-  "platforms": {
-    "windows-x64": {
-      "asset": "workbite-0.1.18-windows-x64.zip",
-      "bundleSha256": "393ac3190fbea00abc3ac21cd5a11caa9e867633970d3cde5897aec99fea5314",
-      "sha256": "805e65e6ea2f9818582c1b6122ecffff098cb7545ea34284145c59e75be6e53c",
-      "size": 136269760,
-      "url": "https://github.com/Shinick-Han/WorkBite-releases/releases/download/v0.1.18/workbite-0.1.18-windows-x64.zip"
-    }
-  },
-  "product": "WorkBite",
-  "repository": "Shinick-Han/WorkBite-releases",
-  "schema": "workbite.release.v1",
-  "tag": "v0.1.18",
-  "version": "0.1.18"
-}
+{
+  "launcherVersion": "0.1.20",
+  "platforms": {
+    "linux-x64": {
+      "asset": "workbite-0.1.20-linux-x64.tar.gz",
+      "bundleSha256": "6ed4e117291ce31035c6d9238687d8fe831980a73005d744d11c8dd26adc42b2",
+      "sha256": "888a9554fd40130384b0359193f908338536134cb130fb27a9f57886d7abe38e",
+      "size": 82456456,
+      "url": "https://github.com/Shinick-Han/WorkBite-releases/releases/download/v0.1.20/workbite-0.1.20-linux-x64.tar.gz"
+    },
+    "windows-x64": {
+      "asset": "workbite-0.1.20-windows-x64.zip",
+      "bundleSha256": "2fe008903450407bae8a966eb48cb8a8fc69942fe6d9739f115421693cbd8a53",
+      "sha256": "8a2b85cebed50cacf725d65db221b241c388639e1eebb26d36efaac90e8c7a9d",
+      "size": 136389662,
+      "url": "https://github.com/Shinick-Han/WorkBite-releases/releases/download/v0.1.20/workbite-0.1.20-windows-x64.zip"
+    }
+  },
+  "product": "WorkBite",
+  "repository": "Shinick-Han/WorkBite-releases",
+  "schema": "workbite.release.v1",
+  "tag": "v0.1.20",
+  "version": "0.1.20"
+}