workbite 0.1.22 → 0.1.24

package/lib/common.js

@@ -1,68 +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 };
+'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/diagnostics.js

@@ -1,238 +1,238 @@
-'use strict';
-// Read-only snapshots, never lifecycle authority. Do not authenticate endpoints,
-// read token files, acquire locks, install binaries or replay pending intents here.
-const fs = require('node:fs/promises');
-const { constants } = require('node:fs');
-const path = require('node:path');
-const { locations, releaseSpec, installName } = require('./install');
-const { stateLayout } = require('./runtime');
-const { bootIdentity, validBoot, previousBoot } = require('./boot-provenance');
-const { UUID } = require('./common');
-
-const MAX_BYTES = 65536, MAX_OWNERS = 32, MAX_ENTRIES = 128;
-const LAUNCH = /^[0-9a-f]{16}$/;
-const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
-const pidValue = value => Number.isSafeInteger(value) && value > 0 && value <= 2147483647;
-const NO_DELETE = 'Do not auto-delete, move or replace locks, owner/backend records, native intent or flock files. '
-  + 'Unverified ownership requires manual inspection on the recorded host; keep the original evidence.';
-
-// Reject links in ancestors as well as the leaf; never follow record-provided paths.
-// This is a snapshot, not a pinned filesystem authority: concurrent replacement
-// and NFS visibility can still make evidence incomplete.
-async function checkedStat(file) {
-  const parents = [];
-  for (let parent = path.dirname(file); ; parent = path.dirname(parent)) {
-    if (parents.length >= 128) throw new Error('unsafe');
-    parents.push(parent);
-    if (parent === path.dirname(parent)) break;
-  }
-  for (const parent of parents.reverse()) {
-    const info = await fs.lstat(parent);
-    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('unsafe');
-  }
-  const info = await fs.lstat(file);
-  if (info.isSymbolicLink()) throw new Error('unsafe');
-  return info;
-}
-async function bytes(file, maximum = MAX_BYTES) {
-  const info = await checkedStat(file);
-  if (!info.isFile() || info.size > maximum) throw new Error('unsafe');
-  const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
-  try {
-    const opened = await handle.stat();
-    if (!opened.isFile() || opened.size > maximum || opened.ino !== info.ino || opened.dev !== info.dev) throw new Error('unsafe');
-    const buffer = Buffer.alloc(maximum + 1);
-    let size = 0;
-    while (size < buffer.length) {
-      const result = await handle.read(buffer, size, buffer.length - size, null);
-      if (!result.bytesRead) break;
-      size += result.bytesRead;
-    }
-    if (size > maximum) throw new Error('unsafe');
-    return buffer.subarray(0, size);
-  } finally { await handle.close(); }
-}
-async function metadata(file, directory = false) {
-  try {
-    const info = await checkedStat(file);
-    return { path: file, status: (directory ? info.isDirectory() : info.isFile()) ? 'present' : 'unsafe' };
-  } catch (error) { return { path: file, status: error.code === 'ENOENT' ? 'absent' : 'unreadable-or-unsafe' }; }
-}
-async function readRecord(file, legacy = false) {
-  try {
-    const text = new TextDecoder('utf-8', { fatal: true }).decode(await bytes(file));
-    if (legacy && /^[1-9][0-9]{0,9}\s*$/.test(text) && pidValue(Number(text))) {
-      return { path: file, status: 'legacy-pid', value: { pid: Number(text) } };
-    }
-    const value = JSON.parse(text);
-    if (!object(value)) return { path: file, status: 'malformed' };
-    return { path: file, status: 'parsed', value };
-  } catch (error) {
-    return { path: file, status: error.code === 'ENOENT' ? 'absent'
-      : error instanceof SyntaxError || error instanceof TypeError ? 'malformed' : 'unreadable-or-unsafe' };
-  }
-}
-function provenance(saved, current) {
-  if (!validBoot(saved) || !validBoot(current)) return { host: 'unknown', boot: 'unknown' };
-  if (saved.host !== current.host) return { host: 'foreign', boot: 'not-comparable' };
-  if (saved.source !== current.source) return { host: 'local', boot: 'unknown' };
-  return { host: 'local', boot: saved.id === current.id ? 'current' : previousBoot(saved, current) ? 'previous' : 'unknown' };
-}
-function nativeBoot(value) {
-  if (!object(value) || Object.keys(value).length !== 3 || !Object.hasOwn(value, 'boot')) return null;
-  if (value.source === 'linux-boot-id') return { source: value.source, host: value.host, id: value.boot };
-  if (value.source === 'windows-cim-boot-time' && typeof value.host === 'string'
-      && /^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(value.host)) {
-    return { source: 'windows-wmi-boot-time', host: value.host.replace(/-/g, ''), id: value.boot };
-  }
-  return null;
-}
-function probePid(pid) {
-  try { process.kill(pid, 0); return 'exists'; } catch (error) {
-    return error.code === 'ESRCH' ? 'missing' : error.code === 'EPERM' ? 'exists-permission-denied' : 'unknown';
-  }
-}
-function summarize(record, kind, current, pidProbe) {
-  const { value, ...result } = record;
-  result.kind = kind;
-  if (!value) return result;
-  // Only closed enums and validated integers leave the record. Never emit free
-  // text errors, endpoints, descriptors, tokens, bindings or intent payloads.
-  const knownSchema = kind === 'owner' ? value.schema === 'workbite.owner.v2'
-    : kind === 'backend' ? value.schema === 'workbite.stackbite-backend.v2'
-      : kind === 'native-daemon' ? value.schema === 'stackbite-rust-daemon-startup-v1'
-        : kind === 'native-ui' ? value.schema === 'workstack.tui-intent.v1'
-          : kind === 'selection' ? value.schema === 'workbite.workspace-selection.v1'
-            : kind === 'backend-identity' ? value.schema === 'stackbite.workstack-backend.v1' : false;
-  result.format = record.status === 'legacy-pid' ? 'legacy-pid' : knownSchema ? 'recognized-schema' : 'unknown-schema';
-  const stage = kind === 'native-daemon' ? value.phase : value.state;
-  result.stage = ['starting', 'ready', 'attempted', 'descriptor', 'selected', 'unknown'].includes(stage) ? stage : 'unknown';
-  result.provenance = provenance(kind === 'native-daemon' ? nativeBoot(value.owner_boot) : value.boot, current);
-  result.pid = pidValue(value.pid) ? value.pid : null;
-  result.pidEvidence = 'not-probed';
-  if (result.pid && result.provenance.host === 'local' && result.provenance.boot === 'current') {
-    try {
-      const evidence = pidProbe(result.pid);
-      result.pidEvidence = ['exists', 'missing', 'exists-permission-denied'].includes(evidence) ? evidence : 'unknown';
-    } catch { result.pidEvidence = 'unknown'; }
-  }
-  result.identity = 'unverified';
-  result.cleanupSafe = false;
-  if (['owner', 'backend'].includes(kind) && typeof value.launch === 'string' && LAUNCH.test(value.launch)) {
-    result.logHint = path.join(path.dirname(kind === 'owner' ? path.dirname(record.path) : record.path),
-      'logs', `${kind === 'owner' ? 'workstack-engine-' + path.basename(record.path, '.json') : 'stackbite-backend'}-${value.launch}.log`);
-  }
-  if (kind === 'native-daemon') result.savedLogHints = typeof value.log_file === 'string' || typeof value.stderr_log_file === 'string';
-  if (kind === 'native-ui') result.pendingIntent = knownSchema && UUID.test(value.intent || '') ? 'retained-do-not-replay' : 'unknown-do-not-replay';
-  return result;
-}
-async function ownerRecords(directory) {
-  const records = [];
-  let handle, entries = 0, limited = false, status = 'present';
-  try {
-    if (!(await checkedStat(directory)).isDirectory()) throw new Error('unsafe');
-    handle = await fs.opendir(directory, { bufferSize: 16 });
-    while (entries < MAX_ENTRIES && records.length < MAX_OWNERS) {
-      const entry = await handle.read();
-      if (!entry) break;
-      entries++;
-      if (/^[0-9a-f]{24}\.json$/.test(entry.name)) records.push(await readRecord(path.join(directory, entry.name)));
-    }
-    limited = entries === MAX_ENTRIES || records.length === MAX_OWNERS;
-  } catch (error) { status = error.code === 'ENOENT' ? 'absent' : 'unreadable-or-unsafe'; }
-  finally { if (handle) await handle.close(); }
-  return { path: directory, status, entriesExamined: entries, limited, records };
-}
-
-async function inspectStartup(options = {}) {
-  const environment = options.environment || process.env, platform = options.platform || process.platform;
-  const where = locations(environment, platform);
-  const state = path.resolve(options.stateRoot || where.state), apps = path.resolve(options.apps || where.apps);
-  const layout = stateLayout(state);
-  const paths = { workbiteHome: path.dirname(where.apps), apps, state, logs: layout.logs,
-    lock: layout.lock, owners: layout.owners, backend: layout.stackbiteRecord, selection: layout.selection,
-    nativeIntent: path.join(layout.stackbite, '.stackbite-rust-daemon', 'intent.json'), uiIntent: layout.tuiIntent };
-  // Linux bootIdentity is file-only. Windows' implementation invokes WMI through
-  // PowerShell, so leave boot provenance unknown here to keep diagnostics process-free.
-  let boot = null;
-  try {
-    if (options.bootImpl) boot = await options.bootImpl();
-    else if (platform === 'linux') boot = await bootIdentity({ platform, environment,
-      readImpl: async file => (await bytes(file, 4096)).toString('utf8') });
-  } catch { /* unavailable provenance stays unknown */ }
-  const pidProbe = options.pidProbe || probePid;
-  const owners = await ownerRecords(layout.owners);
-  const records = [
-    summarize(await readRecord(layout.lock, true), 'open-lock', boot, pidProbe),
-    ...owners.records.map(record => summarize(record, 'owner', boot, pidProbe)),
-    summarize(await readRecord(layout.stackbiteRecord), 'backend', boot, pidProbe),
-    summarize(await readRecord(path.join(layout.stackbite, 'workstack-backend.json')), 'backend-identity', boot, pidProbe),
-    summarize(await readRecord(layout.selection), 'selection', boot, pidProbe),
-    summarize(await readRecord(paths.nativeIntent), 'native-daemon', boot, pidProbe),
-    summarize(await readRecord(layout.tuiIntent), 'native-ui', boot, pidProbe),
-  ];
-  let installation = { status: 'pinned-target-unavailable', integrity: 'not-checked' };
-  try {
-    const spec = releaseSpec(options.manifest || require('../release.json'), platform, options.arch || process.arch, options);
-    paths.installation = path.join(apps, installName(spec));
-    installation = { ...await metadata(paths.installation, true), integrity: 'not-checked',
-      bundle: await metadata(path.join(paths.installation, 'bundle.json')) };
-  } catch { /* Diagnostics must still work when release pins/platform are unavailable. */ }
-  const stateInfo = await metadata(state, true);
-  const present = records.filter(record => record.status !== 'absent');
-  const uncertain = present.some(record => record.status !== 'parsed' || record.format !== 'recognized-schema'
-    || (!['selection', 'backend-identity', 'native-ui'].includes(record.kind)
-      && (record.stage === 'unknown' || record.provenance?.host !== 'local')));
-  const stage = stateInfo.status === 'absent' ? 'state-absent'
-    : stateInfo.status !== 'present' || uncertain || owners.limited || owners.status === 'unreadable-or-unsafe' ? 'inspection-required'
-      : !present.length ? 'no-startup-records' : 'records-present-unverified';
-  return { schema: 'workbite.startup-diagnostics.v1', readOnly: true, stage, paths,
-    workbiteHomeSource: environment.WORKBITE_HOME ? 'WORKBITE_HOME' : 'platform-default', state: stateInfo,
-    installation, bootIdentity: validBoot(boot) ? 'available' : 'unavailable',
-    owners: { path: owners.path, status: owners.status, entriesExamined: owners.entriesExamined, limited: owners.limited }, records,
-    limits: { bytesPerRecord: MAX_BYTES, ownerRecords: MAX_OWNERS, directoryEntries: MAX_ENTRIES },
-    limitations: [
-      'Snapshot only: records may change concurrently and NFS visibility may lag. Schema recognition is not authentication or full validation.',
-      'No endpoints are probed. No credential files or log contents are read. Saved ready/selected stages do not prove current health.',
-      'Foreign or unknown host PIDs are never tested locally or declared dead. A local missing PID is an observation, not cleanup authority.',
-      'Local PID existence alone never proves process identity, ownership or safe cleanup. Prior-boot evidence does not authorize deletion.',
-      'Windows boot provenance remains unknown because diagnostics never launches the WMI helper process.',
-      'Install presence is not integrity verification; use workbite check for the existing integrity check.',
-    ],
-    guidance: [NO_DELETE, 'workbite open --no-ui starts or reuses backends only; it does not prove that a terminal UI can open.',
-      'doctor/status inspect saved startup records passively. inspection-required means provenance needs review; it is not an authenticated agent admission failure.',
-      'workbite agent status ready means authenticated workspace command admission at that observation, not provider readiness, turn completion or Task completion.',
-      'To check workspace admission, explicitly run workbite agent status in the intended workspace. To inspect an assigned execution seat, refresh stackbite-room context; compare its current generation and runtime evidence.',
-      'Configured provider labels, installed binaries and saved ready records do not verify the running provider or its lifecycle hooks. A Taskless standalone Room is normal; an unassigned seat must wait for assignment.',
-      'Inspect the selected record paths and private logs locally with credentials redacted; do not publish raw files.',
-      'For native daemon logs, consult log_file and stderr_log_file in the retained native intent locally; untrusted saved paths are not followed here.',
-      'For foreign-host records, inspect the recorded host. If ownership remains unknown, retain the state and seek operator review.',
-      'A pending native intent may have applied already. Reauthenticate the original owner and resolve its operation status; do not replay it.'],
-  };
-}
-async function runDiagnostics(parsed, options = {}) {
-  const report = await inspectStartup(options);
-  report.command = parsed.command;
-  if (parsed.command === 'recover') report.recovery = { dryRun: true, mutated: false, repaired: false,
-    plan: ['Retain the original state and logs; review the diagnostic evidence and limitations.',
-      'Establish the recorded host, boot and authenticated process ownership through operator review before considering any repair.',
-      'Resolve retained native intent with the original owner; do not replay unknown outcomes.',
-      'No automatic recovery action is supported by this command.'], guidance: NO_DELETE };
-  const stdout = options.stdout || process.stdout;
-  if (parsed.json) stdout.write(JSON.stringify(report) + '\n');
-  else {
-    const lines = [`WorkBite ${parsed.command}: ${report.stage} (read-only)`,
-      `WORKBITE_HOME: ${report.paths.workbiteHome} (${report.workbiteHomeSource})`,
-      ...Object.entries(report.paths).filter(([name]) => name !== 'workbiteHome').map(([name, file]) => `${name}: ${file}`),
-      `installation: ${report.installation.status}; integrity not checked (workbite check)`,
-      `owners: ${report.owners.status}; ${report.owners.entriesExamined} entries examined; limited=${report.owners.limited}`,
-      ...report.records.map(record => `${record.kind}: ${record.status}; stage=${record.stage || 'unknown'}; `
-        + `host=${record.provenance?.host || 'unknown'}; boot=${record.provenance?.boot || 'unknown'}; `
-        + `pid=${record.pid ?? 'unknown'} (${record.pidEvidence || 'not-probed'}); ${record.path}`
-        + (record.logHint ? `; log hint=${record.logHint}` : '')),
-      ...report.limitations, ...report.guidance, ...(report.recovery?.plan || [])];
-    stdout.write(lines.join('\n') + '\n');
-  }
-  return { code: 0, signal: null };
-}
-module.exports = { inspectStartup, runDiagnostics };
+'use strict';
+// Read-only snapshots, never lifecycle authority. Do not authenticate endpoints,
+// read token files, acquire locks, install binaries or replay pending intents here.
+const fs = require('node:fs/promises');
+const { constants } = require('node:fs');
+const path = require('node:path');
+const { locations, releaseSpec, installName } = require('./install');
+const { stateLayout } = require('./runtime');
+const { bootIdentity, validBoot, previousBoot } = require('./boot-provenance');
+const { UUID } = require('./common');
+
+const MAX_BYTES = 65536, MAX_OWNERS = 32, MAX_ENTRIES = 128;
+const LAUNCH = /^[0-9a-f]{16}$/;
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const pidValue = value => Number.isSafeInteger(value) && value > 0 && value <= 2147483647;
+const NO_DELETE = 'Do not auto-delete, move or replace locks, owner/backend records, native intent or flock files. '
+  + 'Unverified ownership requires manual inspection on the recorded host; keep the original evidence.';
+
+// Reject links in ancestors as well as the leaf; never follow record-provided paths.
+// This is a snapshot, not a pinned filesystem authority: concurrent replacement
+// and NFS visibility can still make evidence incomplete.
+async function checkedStat(file) {
+  const parents = [];
+  for (let parent = path.dirname(file); ; parent = path.dirname(parent)) {
+    if (parents.length >= 128) throw new Error('unsafe');
+    parents.push(parent);
+    if (parent === path.dirname(parent)) break;
+  }
+  for (const parent of parents.reverse()) {
+    const info = await fs.lstat(parent);
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('unsafe');
+  }
+  const info = await fs.lstat(file);
+  if (info.isSymbolicLink()) throw new Error('unsafe');
+  return info;
+}
+async function bytes(file, maximum = MAX_BYTES) {
+  const info = await checkedStat(file);
+  if (!info.isFile() || info.size > maximum) throw new Error('unsafe');
+  const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+  try {
+    const opened = await handle.stat();
+    if (!opened.isFile() || opened.size > maximum || opened.ino !== info.ino || opened.dev !== info.dev) throw new Error('unsafe');
+    const buffer = Buffer.alloc(maximum + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const result = await handle.read(buffer, size, buffer.length - size, null);
+      if (!result.bytesRead) break;
+      size += result.bytesRead;
+    }
+    if (size > maximum) throw new Error('unsafe');
+    return buffer.subarray(0, size);
+  } finally { await handle.close(); }
+}
+async function metadata(file, directory = false) {
+  try {
+    const info = await checkedStat(file);
+    return { path: file, status: (directory ? info.isDirectory() : info.isFile()) ? 'present' : 'unsafe' };
+  } catch (error) { return { path: file, status: error.code === 'ENOENT' ? 'absent' : 'unreadable-or-unsafe' }; }
+}
+async function readRecord(file, legacy = false) {
+  try {
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(await bytes(file));
+    if (legacy && /^[1-9][0-9]{0,9}\s*$/.test(text) && pidValue(Number(text))) {
+      return { path: file, status: 'legacy-pid', value: { pid: Number(text) } };
+    }
+    const value = JSON.parse(text);
+    if (!object(value)) return { path: file, status: 'malformed' };
+    return { path: file, status: 'parsed', value };
+  } catch (error) {
+    return { path: file, status: error.code === 'ENOENT' ? 'absent'
+      : error instanceof SyntaxError || error instanceof TypeError ? 'malformed' : 'unreadable-or-unsafe' };
+  }
+}
+function provenance(saved, current) {
+  if (!validBoot(saved) || !validBoot(current)) return { host: 'unknown', boot: 'unknown' };
+  if (saved.host !== current.host) return { host: 'foreign', boot: 'not-comparable' };
+  if (saved.source !== current.source) return { host: 'local', boot: 'unknown' };
+  return { host: 'local', boot: saved.id === current.id ? 'current' : previousBoot(saved, current) ? 'previous' : 'unknown' };
+}
+function nativeBoot(value) {
+  if (!object(value) || Object.keys(value).length !== 3 || !Object.hasOwn(value, 'boot')) return null;
+  if (value.source === 'linux-boot-id') return { source: value.source, host: value.host, id: value.boot };
+  if (value.source === 'windows-cim-boot-time' && typeof value.host === 'string'
+      && /^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(value.host)) {
+    return { source: 'windows-wmi-boot-time', host: value.host.replace(/-/g, ''), id: value.boot };
+  }
+  return null;
+}
+function probePid(pid) {
+  try { process.kill(pid, 0); return 'exists'; } catch (error) {
+    return error.code === 'ESRCH' ? 'missing' : error.code === 'EPERM' ? 'exists-permission-denied' : 'unknown';
+  }
+}
+function summarize(record, kind, current, pidProbe) {
+  const { value, ...result } = record;
+  result.kind = kind;
+  if (!value) return result;
+  // Only closed enums and validated integers leave the record. Never emit free
+  // text errors, endpoints, descriptors, tokens, bindings or intent payloads.
+  const knownSchema = kind === 'owner' ? value.schema === 'workbite.owner.v2'
+    : kind === 'backend' ? value.schema === 'workbite.stackbite-backend.v2'
+      : kind === 'native-daemon' ? value.schema === 'stackbite-rust-daemon-startup-v1'
+        : kind === 'native-ui' ? value.schema === 'workstack.tui-intent.v1'
+          : kind === 'selection' ? value.schema === 'workbite.workspace-selection.v1'
+            : kind === 'backend-identity' ? value.schema === 'stackbite.workstack-backend.v1' : false;
+  result.format = record.status === 'legacy-pid' ? 'legacy-pid' : knownSchema ? 'recognized-schema' : 'unknown-schema';
+  const stage = kind === 'native-daemon' ? value.phase : value.state;
+  result.stage = ['starting', 'ready', 'attempted', 'descriptor', 'selected', 'unknown'].includes(stage) ? stage : 'unknown';
+  result.provenance = provenance(kind === 'native-daemon' ? nativeBoot(value.owner_boot) : value.boot, current);
+  result.pid = pidValue(value.pid) ? value.pid : null;
+  result.pidEvidence = 'not-probed';
+  if (result.pid && result.provenance.host === 'local' && result.provenance.boot === 'current') {
+    try {
+      const evidence = pidProbe(result.pid);
+      result.pidEvidence = ['exists', 'missing', 'exists-permission-denied'].includes(evidence) ? evidence : 'unknown';
+    } catch { result.pidEvidence = 'unknown'; }
+  }
+  result.identity = 'unverified';
+  result.cleanupSafe = false;
+  if (['owner', 'backend'].includes(kind) && typeof value.launch === 'string' && LAUNCH.test(value.launch)) {
+    result.logHint = path.join(path.dirname(kind === 'owner' ? path.dirname(record.path) : record.path),
+      'logs', `${kind === 'owner' ? 'workstack-engine-' + path.basename(record.path, '.json') : 'stackbite-backend'}-${value.launch}.log`);
+  }
+  if (kind === 'native-daemon') result.savedLogHints = typeof value.log_file === 'string' || typeof value.stderr_log_file === 'string';
+  if (kind === 'native-ui') result.pendingIntent = knownSchema && UUID.test(value.intent || '') ? 'retained-do-not-replay' : 'unknown-do-not-replay';
+  return result;
+}
+async function ownerRecords(directory) {
+  const records = [];
+  let handle, entries = 0, limited = false, status = 'present';
+  try {
+    if (!(await checkedStat(directory)).isDirectory()) throw new Error('unsafe');
+    handle = await fs.opendir(directory, { bufferSize: 16 });
+    while (entries < MAX_ENTRIES && records.length < MAX_OWNERS) {
+      const entry = await handle.read();
+      if (!entry) break;
+      entries++;
+      if (/^[0-9a-f]{24}\.json$/.test(entry.name)) records.push(await readRecord(path.join(directory, entry.name)));
+    }
+    limited = entries === MAX_ENTRIES || records.length === MAX_OWNERS;
+  } catch (error) { status = error.code === 'ENOENT' ? 'absent' : 'unreadable-or-unsafe'; }
+  finally { if (handle) await handle.close(); }
+  return { path: directory, status, entriesExamined: entries, limited, records };
+}
+
+async function inspectStartup(options = {}) {
+  const environment = options.environment || process.env, platform = options.platform || process.platform;
+  const where = locations(environment, platform);
+  const state = path.resolve(options.stateRoot || where.state), apps = path.resolve(options.apps || where.apps);
+  const layout = stateLayout(state);
+  const paths = { workbiteHome: path.dirname(where.apps), apps, state, logs: layout.logs,
+    lock: layout.lock, owners: layout.owners, backend: layout.stackbiteRecord, selection: layout.selection,
+    nativeIntent: path.join(layout.stackbite, '.stackbite-rust-daemon', 'intent.json'), uiIntent: layout.tuiIntent };
+  // Linux bootIdentity is file-only. Windows' implementation invokes WMI through
+  // PowerShell, so leave boot provenance unknown here to keep diagnostics process-free.
+  let boot = null;
+  try {
+    if (options.bootImpl) boot = await options.bootImpl();
+    else if (platform === 'linux') boot = await bootIdentity({ platform, environment,
+      readImpl: async file => (await bytes(file, 4096)).toString('utf8') });
+  } catch { /* unavailable provenance stays unknown */ }
+  const pidProbe = options.pidProbe || probePid;
+  const owners = await ownerRecords(layout.owners);
+  const records = [
+    summarize(await readRecord(layout.lock, true), 'open-lock', boot, pidProbe),
+    ...owners.records.map(record => summarize(record, 'owner', boot, pidProbe)),
+    summarize(await readRecord(layout.stackbiteRecord), 'backend', boot, pidProbe),
+    summarize(await readRecord(path.join(layout.stackbite, 'workstack-backend.json')), 'backend-identity', boot, pidProbe),
+    summarize(await readRecord(layout.selection), 'selection', boot, pidProbe),
+    summarize(await readRecord(paths.nativeIntent), 'native-daemon', boot, pidProbe),
+    summarize(await readRecord(layout.tuiIntent), 'native-ui', boot, pidProbe),
+  ];
+  let installation = { status: 'pinned-target-unavailable', integrity: 'not-checked' };
+  try {
+    const spec = releaseSpec(options.manifest || require('../release.json'), platform, options.arch || process.arch, options);
+    paths.installation = path.join(apps, installName(spec));
+    installation = { ...await metadata(paths.installation, true), integrity: 'not-checked',
+      bundle: await metadata(path.join(paths.installation, 'bundle.json')) };
+  } catch { /* Diagnostics must still work when release pins/platform are unavailable. */ }
+  const stateInfo = await metadata(state, true);
+  const present = records.filter(record => record.status !== 'absent');
+  const uncertain = present.some(record => record.status !== 'parsed' || record.format !== 'recognized-schema'
+    || (!['selection', 'backend-identity', 'native-ui'].includes(record.kind)
+      && (record.stage === 'unknown' || record.provenance?.host !== 'local')));
+  const stage = stateInfo.status === 'absent' ? 'state-absent'
+    : stateInfo.status !== 'present' || uncertain || owners.limited || owners.status === 'unreadable-or-unsafe' ? 'inspection-required'
+      : !present.length ? 'no-startup-records' : 'records-present-unverified';
+  return { schema: 'workbite.startup-diagnostics.v1', readOnly: true, stage, paths,
+    workbiteHomeSource: environment.WORKBITE_HOME ? 'WORKBITE_HOME' : 'platform-default', state: stateInfo,
+    installation, bootIdentity: validBoot(boot) ? 'available' : 'unavailable',
+    owners: { path: owners.path, status: owners.status, entriesExamined: owners.entriesExamined, limited: owners.limited }, records,
+    limits: { bytesPerRecord: MAX_BYTES, ownerRecords: MAX_OWNERS, directoryEntries: MAX_ENTRIES },
+    limitations: [
+      'Snapshot only: records may change concurrently and NFS visibility may lag. Schema recognition is not authentication or full validation.',
+      'No endpoints are probed. No credential files or log contents are read. Saved ready/selected stages do not prove current health.',
+      'Foreign or unknown host PIDs are never tested locally or declared dead. A local missing PID is an observation, not cleanup authority.',
+      'Local PID existence alone never proves process identity, ownership or safe cleanup. Prior-boot evidence does not authorize deletion.',
+      'Windows boot provenance remains unknown because diagnostics never launches the WMI helper process.',
+      'Install presence is not integrity verification; use workbite check for the existing integrity check.',
+    ],
+    guidance: [NO_DELETE, 'workbite open --no-ui starts or reuses backends only; it does not prove that a terminal UI can open.',
+      'doctor/status inspect saved startup records passively. inspection-required means provenance needs review; it is not an authenticated agent admission failure.',
+      'workbite agent status ready means authenticated workspace command admission at that observation, not provider readiness, turn completion or Task completion.',
+      'To check workspace admission, explicitly run workbite agent status in the intended workspace. To inspect an assigned execution seat, refresh stackbite-room context; compare its current generation and runtime evidence.',
+      'Configured provider labels, installed binaries and saved ready records do not verify the running provider or its lifecycle hooks. A Taskless standalone Room is normal; an unassigned seat must wait for assignment.',
+      'Inspect the selected record paths and private logs locally with credentials redacted; do not publish raw files.',
+      'For native daemon logs, consult log_file and stderr_log_file in the retained native intent locally; untrusted saved paths are not followed here.',
+      'For foreign-host records, inspect the recorded host. If ownership remains unknown, retain the state and seek operator review.',
+      'A pending native intent may have applied already. Reauthenticate the original owner and resolve its operation status; do not replay it.'],
+  };
+}
+async function runDiagnostics(parsed, options = {}) {
+  const report = await inspectStartup(options);
+  report.command = parsed.command;
+  if (parsed.command === 'recover') report.recovery = { dryRun: true, mutated: false, repaired: false,
+    plan: ['Retain the original state and logs; review the diagnostic evidence and limitations.',
+      'Establish the recorded host, boot and authenticated process ownership through operator review before considering any repair.',
+      'Resolve retained native intent with the original owner; do not replay unknown outcomes.',
+      'No automatic recovery action is supported by this command.'], guidance: NO_DELETE };
+  const stdout = options.stdout || process.stdout;
+  if (parsed.json) stdout.write(JSON.stringify(report) + '\n');
+  else {
+    const lines = [`WorkBite ${parsed.command}: ${report.stage} (read-only)`,
+      `WORKBITE_HOME: ${report.paths.workbiteHome} (${report.workbiteHomeSource})`,
+      ...Object.entries(report.paths).filter(([name]) => name !== 'workbiteHome').map(([name, file]) => `${name}: ${file}`),
+      `installation: ${report.installation.status}; integrity not checked (workbite check)`,
+      `owners: ${report.owners.status}; ${report.owners.entriesExamined} entries examined; limited=${report.owners.limited}`,
+      ...report.records.map(record => `${record.kind}: ${record.status}; stage=${record.stage || 'unknown'}; `
+        + `host=${record.provenance?.host || 'unknown'}; boot=${record.provenance?.boot || 'unknown'}; `
+        + `pid=${record.pid ?? 'unknown'} (${record.pidEvidence || 'not-probed'}); ${record.path}`
+        + (record.logHint ? `; log hint=${record.logHint}` : '')),
+      ...report.limitations, ...report.guidance, ...(report.recovery?.plan || [])];
+    stdout.write(lines.join('\n') + '\n');
+  }
+  return { code: 0, signal: null };
+}
+module.exports = { inspectStartup, runDiagnostics };