@quolu/lattice 0.79.2 → 0.79.4

package/src/dashboard-lifecycle-journal.mjs

@@ -0,0 +1,235 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, readFile, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+const SCHEMA = 'lattice.dashboard_lifecycle.v1';
+export const LIFECYCLE_MAX_RUNS = 64;
+export const LIFECYCLE_MAX_BYTES = 16 * 1024;
+const PHASES = new Set(['spawn', 'import', 'registry', 'store', 'listen', 'ready',
+  'periodic_sync', 'empty_shutdown', 'shutdown_request', 'sync_failed', 'store_read_failed',
+  'cleanup_failed', 'close_failed', 'close', 'closed']);
+const RUN_ID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/u;
+const WINDOWS_REPLACE_WAIT_MS = 500;
+const REPLACE_MAX_ATTEMPTS = 32;
+
+export function lifecycleError(code) {
+  return Object.assign(new Error(code), { code,
+    detail: { reason: code.toLowerCase(), next_action: 'lattice todo dashboard ensure --json' } });
+}
+
+function directory(root) { return path.join(root, 'lifecycle'); }
+function terminationTime(run) {
+  return run.exit_observed_at ?? run.observer_loss_observed_at ?? run.started_at;
+}
+function reference(root, id) {
+  if (!RUN_ID.test(id)) throw lifecycleError('DASHBOARD_LIFECYCLE_INVALID');
+  return path.join(directory(root), `${id}.json`);
+}
+
+async function checkOwned(ref, type) {
+  const info = await lstat(ref);
+  if (info.isSymbolicLink() || (type === 'directory' ? !info.isDirectory() : !info.isFile())
+    || (typeof process.getuid === 'function' && info.uid !== process.getuid())
+    || (process.platform !== 'win32' && (info.mode & 0o077) !== 0)) {
+    throw lifecycleError('DASHBOARD_LIFECYCLE_UNSAFE_PATH');
+  }
+  return info;
+}
+
+export async function prepareLifecycleDirectory(root) {
+  // The runtime root is already private and owned by the dashboard registry.
+  await checkOwned(root, 'directory');
+  await mkdir(directory(root), { mode: 0o700 }).catch((error) => {
+    if (error.code !== 'EEXIST') throw error;
+  });
+  await checkOwned(directory(root), 'directory');
+  // Interrupted atomic writes contain no body data either, but must not grow forever.
+  const pending = /^(?:[a-f0-9-]{36}\.json|ensure\.json)\.([1-9][0-9]*)\.[a-f0-9-]{36}\.tmp$/u;
+  for (const name of await readdir(directory(root))) {
+    const match = pending.exec(name);
+    if (!match) continue;
+    let alive = true;
+    try { process.kill(Number(match[1]), 0); } catch (error) {
+      if (error.code !== 'ESRCH') throw error;
+      alive = false;
+    }
+    if (!alive) {
+      const ref = path.join(directory(root), name);
+      await checkOwned(ref, 'file');
+      await rm(ref);
+    }
+  }
+}
+
+export async function readLifecycleRuns(root) {
+  try { await checkOwned(directory(root), 'directory'); } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+  const runs = [];
+  for (const name of (await readdir(directory(root))).sort()) {
+    if (!name.endsWith('.json') || !RUN_ID.test(name.slice(0, -5))) continue;
+    const ref = path.join(directory(root), name);
+    const info = await checkOwned(ref, 'file');
+    if (info.size > LIFECYCLE_MAX_BYTES) throw lifecycleError('DASHBOARD_LIFECYCLE_INVALID');
+    const handle = await open(ref, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    let value;
+    try { value = JSON.parse(await handle.readFile('utf8')); }
+    catch { throw lifecycleError('DASHBOARD_LIFECYCLE_INVALID'); }
+    finally { await handle.close(); }
+    if (value?.schema !== SCHEMA || value.run_id !== name.slice(0, -5)
+      || !['active', 'closed', 'supervisor_lost'].includes(value.state)) {
+      throw lifecycleError('DASHBOARD_LIFECYCLE_INVALID');
+    }
+    runs.push(value);
+  }
+  return runs.sort((a, b) => a.started_at.localeCompare(b.started_at));
+}
+
+/** Publish only after a real atomic replacement; Windows delete-sharing can be transient. */
+async function publishLifecycleJson(ref, bytes) {
+  const parent = path.dirname(ref);
+  await checkOwned(parent, 'directory');
+  // At most 64 live writers can race this check, so even orphaned temporary files
+  // have a finite bound. Refuse another write rather than discard an active run.
+  if ((await readdir(parent)).length >= 256) throw lifecycleError('DASHBOARD_LIFECYCLE_CAPACITY');
+  if (Buffer.byteLength(bytes) > LIFECYCLE_MAX_BYTES) throw lifecycleError('DASHBOARD_LIFECYCLE_CAPACITY');
+  try { await checkOwned(ref, 'file'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const temporary = `${ref}.${process.pid}.${randomUUID()}.tmp`;
+  const handle = await open(temporary, 'wx', 0o600);
+  try {
+    await handle.writeFile(bytes, 'utf8');
+    await handle.sync();
+  } finally { await handle.close(); }
+  // Failed private temporaries stay bounded for dead-writer cleanup. Never delete
+  // the old receipt to make replacement succeed, or let cleanup mask its error.
+  const deadline = performance.now() + WINDOWS_REPLACE_WAIT_MS;
+  let attempts = 0;
+  for (;;) {
+    await checkOwned(parent, 'directory');
+    await checkOwned(temporary, 'file');
+    try { await checkOwned(ref, 'file'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    attempts++;
+    try {
+      await rename(temporary, ref);
+      return;
+    } catch (error) {
+      const busy = process.platform === 'win32' && ['EPERM', 'EACCES', 'EBUSY'].includes(error.code);
+      if (!busy) throw error;
+      if (performance.now() >= deadline || attempts >= REPLACE_MAX_ATTEMPTS) {
+        const failure = lifecycleError('DASHBOARD_LIFECYCLE_PUBLISH_FAILED');
+        failure.cause = error;
+        failure.detail = { ...failure.detail, operation: 'atomic_replace',
+          fs_code: error.code, attempts, temporary_retained: true };
+        throw failure;
+      }
+      await new Promise((resolve) => setTimeout(resolve,
+        Math.min(10 * 2 ** Math.min(attempts - 1, 3), 50, Math.max(1, deadline - performance.now()))));
+    }
+  }
+}
+
+export async function writeLifecycleRun(root, run) {
+  await publishLifecycleJson(reference(root, run.run_id), `${JSON.stringify(run)}\n`);
+}
+
+/** Call under the existing dashboard startup lock, before spawning anything. */
+export async function createLifecycleRun(root, version) {
+  await prepareLifecycleDirectory(root);
+  const runs = await readLifecycleRuns(root);
+  while (runs.length >= LIFECYCLE_MAX_RUNS) {
+    const oldest = runs.filter((run) => run.state !== 'active'
+      && !run.child_at_reconciliation?.startsWith('present'))
+      .sort((a, b) => terminationTime(a).localeCompare(terminationTime(b)))[0];
+    if (!oldest) throw lifecycleError('DASHBOARD_LIFECYCLE_CAPACITY');
+    const index = runs.findIndex((run) => run.run_id === oldest.run_id);
+    const [old] = runs.splice(index, 1);
+    await rm(reference(root, old.run_id));
+  }
+  const run = { schema: SCHEMA, run_id: randomUUID(), version, platform: process.platform,
+    state: 'active', started_at: new Date().toISOString(), supervisor: null, child: null,
+    phase: 'spawn', ready_at: null, exit_observed_at: null,
+    observed_exit: { status: 'unknown' }, termination_request: null,
+    stderr: { bytes: 0, hashed_bytes: 0, sha256: null, truncated: false }, events: [] };
+  await writeLifecycleRun(root, run);
+  return run;
+}
+
+export function recordLifecyclePhase(run, phase) {
+  if (!PHASES.has(phase) || phase === run.phase) return false;
+  run.phase = phase;
+  if (['empty_shutdown', 'shutdown_request', 'sync_failed', 'cleanup_failed', 'close_failed'].includes(phase)) {
+    run.exit_stage = phase;
+  }
+  const at = new Date().toISOString();
+  if (phase === 'ready' && run.ready_at === null) run.ready_at = at;
+  if (['store_read_failed', 'sync_failed', 'cleanup_failed', 'close_failed'].includes(phase)) {
+    run.last_failure_observed = { at, phase };
+  }
+  run.events.push({ at, phase });
+  if (run.events.length > 64) run.events.shift();
+  return true;
+}
+
+/** No fabricated exit time/value when the observer itself disappeared. */
+export async function reconcileLifecycleRuns(root, observeIdentity) {
+  const runs = await readLifecycleRuns(root);
+  for (const run of runs) {
+    if (run.state === 'closed') continue;
+    const supervisor = run.supervisor === null ? null : await observeIdentity(run.supervisor.pid);
+    if (run.state === 'active' && supervisor !== null && supervisor.birth !== null
+      && supervisor.birth === run.supervisor.birth) continue;
+    // Unknown birth cannot establish observer loss. Do not overwrite its receipt.
+    if (run.state === 'active' && supervisor !== null
+      && (supervisor.birth === null || run.supervisor.birth === null)) continue;
+    const previousState = run.state;
+    const previousPresence = run.child_at_reconciliation;
+    run.state = 'supervisor_lost';
+    run.observer_loss_observed_at ??= new Date().toISOString();
+    const child = run.child === null ? null : await observeIdentity(run.child.pid);
+    run.child_at_reconciliation = run.child === null ? 'not_observed' : child === null ? 'absent'
+      : child.birth !== null && child.birth === run.child.birth ? 'present_identity_matched'
+        : child.birth !== null && run.child.birth !== null ? 'absent_identity_reused'
+          : 'present_identity_unconfirmed';
+    run.observed_exit = { status: 'unknown', reason: 'supervisor_lost' };
+    if (previousState !== run.state || previousPresence !== run.child_at_reconciliation) {
+      run.child_presence_observed_at = new Date().toISOString();
+      await writeLifecycleRun(root, run);
+    }
+  }
+  return runs;
+}
+
+/** One bounded decision receipt, serialized by the registry's existing startup lock. */
+export async function recordDashboardEnsureDecision(root, decision, childPid) {
+  if (!['reuse_current', 'adopt_current', 'replace_legacy', 'start_missing',
+    'pid_reused', 'alive_unresponsive'].includes(decision)) throw new TypeError('invalid dashboard decision');
+  await prepareLifecycleDirectory(root);
+  const matching = (await readLifecycleRuns(root)).filter((run) => run.child?.pid === childPid
+    && (run.state === 'active' || run.child_at_reconciliation?.startsWith('present'))).at(-1);
+  const supervision = childPid === null ? 'not_started' : matching?.state === 'active' ? 'supervised'
+    : matching?.state === 'supervisor_lost' ? 'supervisor_lost' : 'legacy_unsupervised';
+  const ref = path.join(directory(root), 'ensure.json');
+  await publishLifecycleJson(ref, `${JSON.stringify({ schema: 'lattice.dashboard_ensure.v1',
+    observed_at: new Date().toISOString(), decision, child_pid: childPid,
+    supervision, run_id: matching?.run_id ?? null })}\n`);
+}
+
+export async function readDashboardLifecycleStatus(root) {
+  const runs = await readLifecycleRuns(root);
+  const terminal = runs.filter((run) => run.state !== 'active').sort((a, b) =>
+    terminationTime(a).localeCompare(terminationTime(b)));
+  let ensure = null;
+  try {
+    const ref = path.join(directory(root), 'ensure.json');
+    const info = await checkOwned(ref, 'file');
+    if (info.size > LIFECYCLE_MAX_BYTES) throw lifecycleError('DASHBOARD_LIFECYCLE_INVALID');
+    try { ensure = JSON.parse(await readFile(ref, 'utf8')); }
+    catch { throw lifecycleError('DASHBOARD_LIFECYCLE_INVALID'); }
+    if (ensure.schema !== 'lattice.dashboard_ensure.v1') throw lifecycleError('DASHBOARD_LIFECYCLE_INVALID');
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  return { schema: 'lattice.dashboard_lifecycle_status.v1',
+    last_ensure: ensure, active: runs.filter((run) => run.state === 'active'),
+    last_termination: terminal.at(-1) ?? null };
+}

package/src/dashboard-process-control.mjs

@@ -0,0 +1,74 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+const execute = promisify(execFile);
+
+/** A missing process and an unavailable birth observation are different. */
+export async function observeDashboardProcess(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) throw new TypeError('invalid dashboard pid');
+  try { process.kill(pid, 0); } catch (error) {
+    if (error.code === 'ESRCH') return null;
+    throw error;
+  }
+  try {
+    if (process.platform === 'linux') {
+      const [stat, boot] = await Promise.all([readFile(`/proc/${pid}/stat`, 'utf8'),
+        readFile('/proc/sys/kernel/random/boot_id', 'utf8')]);
+      const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+      if (fields[0] === 'Z') return null;
+      return { pid, birth: `linux:${boot.trim()}:${fields[19]}` };
+    }
+    const { stdout } = process.platform === 'win32'
+      ? await execute('pwsh.exe', ['-NoProfile', '-NonInteractive', '-Command',
+        `[System.Diagnostics.Process]::GetProcessById(${pid}).StartTime.ToUniversalTime().ToFileTimeUtc()`],
+      { encoding: 'utf8', timeout: 5_000, windowsHide: true })
+      : await execute('/bin/ps', ['-o', 'lstart=', '-p', String(pid)],
+        { encoding: 'utf8', timeout: 5_000, env: { ...process.env, LC_ALL: 'C' } });
+    return { pid, birth: stdout.trim() || null };
+  } catch (error) {
+    // Recheck death after a racing exit. An observation failure never licenses a kill.
+    try { process.kill(pid, 0); } catch (probeError) {
+      if (probeError.code === 'ESRCH') return null;
+      throw probeError;
+    }
+    return { pid, birth: null, observation: 'unavailable' };
+  }
+}
+
+export function observedDashboardExit(code, signal, platform = process.platform) {
+  if (platform === 'win32') {
+    if (!Number.isInteger(code)) return { status: 'unknown', signal: 'not_applicable' };
+    const uint32 = code >>> 0;
+    return { status: 'observed', uint32, hex: `0x${uint32.toString(16).padStart(8, '0').toUpperCase()}`,
+      signal: 'not_applicable', source: 'node_child_wait', origin: 'unknown' };
+  }
+  if (Number.isInteger(code)) return { status: 'observed', code, signal: null, source: 'node_child_wait' };
+  if (typeof signal === 'string') return { status: 'observed', code: null, signal, source: 'node_child_wait' };
+  return { status: 'unknown' };
+}
+
+/** Use the same authenticated handle for birth check, termination and exit read. */
+export async function terminateOwnedWindowsDashboard(identity, exitCode = 1) {
+  if (!identity || !Number.isSafeInteger(identity.pid) || !/^[0-9]+$/u.test(identity.birth ?? '')) {
+    throw Object.assign(new Error('dashboard process birth is unavailable'),
+      { code: 'DASHBOARD_CHILD_IDENTITY_UNAVAILABLE' });
+  }
+  const script = fileURLToPath(new URL('./dashboard-windows-process-control.ps1', import.meta.url));
+  const { stdout } = await execute('pwsh.exe', ['-NoProfile', '-NonInteractive', '-File', script,
+    '-ChildPid', String(identity.pid), '-BirthFileTime', identity.birth, '-RequestedExitCode', String(exitCode)],
+  { encoding: 'utf8', timeout: 12_000, windowsHide: true, maxBuffer: 16_384 });
+  const result = JSON.parse(stdout.trim());
+  if (result.schema !== 'lattice.dashboard_process_control.v1'
+    || result.pid !== identity.pid || result.birth_filetime !== identity.birth
+    || typeof result.termination_requested !== 'boolean' || result.requested_exit_code !== exitCode
+    || !Number.isInteger(result.actual_exit_code) || result.actual_exit_code < 0
+    || result.actual_exit_code > 0xFFFFFFFF
+    || result.actual_exit_hex !== `0x${result.actual_exit_code.toString(16).padStart(8, '0').toUpperCase()}`
+    || result.source !== 'GetExitCodeProcess') {
+    throw Object.assign(new Error('dashboard process control result invalid'),
+      { code: 'DASHBOARD_CHILD_CONTROL_INVALID' });
+  }
+  return result;
+}

package/src/dashboard-supervisor.mjs

@@ -0,0 +1,180 @@
+// This module deliberately has no dashboard, bridge or sensor dependency.
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { createLifecycleRun, lifecycleError, readLifecycleRuns, recordLifecyclePhase,
+  writeLifecycleRun } from './dashboard-lifecycle-journal.mjs';
+import { observeDashboardProcess, observedDashboardExit,
+  terminateOwnedWindowsDashboard } from './dashboard-process-control.mjs';
+
+function notify(message) {
+  if (process.connected) process.send(message, () => {});
+}
+
+/** The sole owner of one child: spawn, wait, forward stop, persist receipts. */
+export async function superviseDashboard({ executable = process.execPath, args, env,
+  root, runId, graceMs = 3_000 }) {
+  const run = (await readLifecycleRuns(root)).find((value) => value.run_id === runId);
+  if (!run || run.state !== 'active') throw lifecycleError('DASHBOARD_LIFECYCLE_INVALID');
+  run.supervisor = await observeDashboardProcess(process.pid);
+  await writeLifecycleRun(root, run);
+  // libuv assigns non-detached Windows children to its parent's kill-on-close Job.
+  // The observer-loss contract keeps this child serving after supervisor death.
+  const child = spawn(executable, args, { env, windowsHide: true, detached: process.platform === 'win32',
+    stdio: ['ignore', 'ignore', 'pipe', 'ipc'] });
+  child.once('spawn', () => { run.child_spawn_observed_at = new Date().toISOString(); });
+  recordLifecyclePhase(run, 'import');
+  const digest = createHash('sha256');
+  let writeQueue = Promise.resolve();
+  let persistenceFailure = null;
+  let stopTimer = null;
+  let controlPending = Promise.resolve();
+  let finished = false;
+  const persist = () => {
+    writeQueue = writeQueue.then(() => writeLifecycleRun(root, run));
+    writeQueue.catch((error) => {
+      if (persistenceFailure) return;
+      persistenceFailure = error;
+      notify({ type: 'supervisor_error', code: 'DASHBOARD_LIFECYCLE_WRITE_FAILED' });
+      requestStop('receipt_failure');
+    });
+    return writeQueue;
+  };
+  const requestStop = (reason, force = false) => {
+    if (finished || (run.termination_request !== null && !force)) return;
+    if (run.termination_request === null) {
+      run.termination_request = { at: new Date().toISOString(), reason, mechanism: 'ipc_shutdown',
+        child: run.child, os_request: null };
+      recordLifecyclePhase(run, 'shutdown_request');
+      if (!persistenceFailure) persist();
+      if (child.connected) child.send({ type: 'dashboard_shutdown' }, () => {});
+    }
+    clearTimeout(stopTimer);
+    stopTimer = setTimeout(() => {
+      if (finished) return;
+      controlPending = (async () => {
+        if (process.platform === 'win32') {
+          const result = await terminateOwnedWindowsDashboard(run.child);
+          run.termination_request.os_request = { mechanism: 'TerminateProcess',
+            requested_exit_code: result.requested_exit_code,
+            api_succeeded: result.termination_requested,
+            actual_exit_code: result.actual_exit_code, source: result.source };
+        } else {
+          run.termination_request.os_request = { mechanism: 'child_signal', signal: 'SIGKILL',
+            api_succeeded: child.kill('SIGKILL') };
+        }
+        if (!persistenceFailure) await persist();
+      })();
+      controlPending.catch((error) => {
+        notify({ type: 'supervisor_error', code: error.code ?? 'DASHBOARD_CHILD_CONTROL_FAILED' });
+        // Cannot authenticate/control the child: leave it available, with unknown exit.
+        process.exitCode = 1;
+      });
+    }, force ? 0 : graceMs);
+  };
+  const term = () => requestStop('supervisor_SIGTERM');
+  const interrupt = () => requestStop('supervisor_SIGINT');
+  const parentMessage = (message) => {
+    if (message?.type === 'dashboard_supervisor_stop') requestStop('owner_stop', message.force === true);
+  };
+  process.on('SIGTERM', term);
+  process.on('SIGINT', interrupt);
+  process.on('message', parentMessage);
+  // A parent IPC disconnect is expected when ensure exits. The child remains serving.
+  process.channel?.unref();
+  child.stderr.on('data', (bytes) => {
+    run.stderr.bytes = Math.min(Number.MAX_SAFE_INTEGER, run.stderr.bytes + bytes.length);
+    const remaining = 65_536 - run.stderr.hashed_bytes;
+    if (remaining > 0) {
+      const part = bytes.subarray(0, remaining);
+      digest.update(part); run.stderr.hashed_bytes += part.length;
+    }
+    run.stderr.truncated = run.stderr.bytes > run.stderr.hashed_bytes;
+  });
+  child.on('message', (message) => {
+    if (message?.type === 'dashboard_phase' && recordLifecyclePhase(run, message.phase)) persist();
+  });
+  let spawnFailure = false;
+  child.once('error', () => { spawnFailure = true; });
+  const ended = new Promise((resolve) => child.once('close', (code, signal) =>
+    resolve({ code, signal, observedAt: new Date().toISOString() })));
+  if (Number.isSafeInteger(child.pid)) {
+    run.child = await observeDashboardProcess(child.pid) ?? { pid: child.pid, birth: null };
+    await persist();
+    notify({ type: 'dashboard_child_started', pid: child.pid, run_id: runId });
+  }
+  const exit = await ended;
+  finished = true;
+  clearTimeout(stopTimer);
+  try { await controlPending; } catch { /* Typed control failure was delivered above; exit is independently observed. */ }
+  run.stderr.sha256 = digest.digest('hex');
+  run.exit_observed_at = exit.observedAt;
+  run.state = 'closed';
+  run.observed_exit = spawnFailure ? { status: 'unknown', reason: 'spawn_failed' }
+    : observedDashboardExit(exit.code, exit.signal);
+  if (process.platform === 'win32' && run.termination_request?.os_request?.api_succeeded) {
+    run.observed_exit.origin = 'owned_terminate_request';
+  }
+  // phase is the last child/control stage, not an invented successful close.
+  try {
+    if (persistenceFailure) throw persistenceFailure;
+    await persist();
+    notify({ type: 'dashboard_child_exited', pid: child.pid, code: exit.code, signal: exit.signal });
+  } finally {
+    process.off('SIGTERM', term); process.off('SIGINT', interrupt);
+    process.off('message', parentMessage);
+    if (process.connected) process.disconnect();
+  }
+  process.exitCode = run.observed_exit.status !== 'observed' ? 1
+    : process.platform === 'win32' ? run.observed_exit.uint32
+      : run.observed_exit.code ?? 1;
+  return run;
+}
+
+/** ChildProcess-compatible seam used by the existing registry readiness/rollback. */
+export async function spawnSupervisedDashboard(executable, args, options) {
+  const root = options.env.LATTICE_DASHBOARD_RUNTIME_DIR;
+  const run = await createLifecycleRun(root, options.version);
+  const supervisor = spawn(executable,
+    [path.resolve(import.meta.dirname, '../bin/lattice-dashboard-supervisor.mjs'), root], {
+      detached: true, windowsHide: true, stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+      env: { ...options.env, LATTICE_DASHBOARD_LIFECYCLE_RUN: run.run_id },
+    });
+  // The daemon command is fixed by the product entry, never accepted from env/IPC.
+  const facade = { pid: null, exitCode: null, signalCode: null, lifecycleRunId: run.run_id,
+    unref() { supervisor.unref(); supervisor.channel?.unref(); },
+    kill(signal = 'SIGTERM') {
+      if (supervisor.connected) supervisor.send({ type: 'dashboard_supervisor_stop',
+        force: signal === 'SIGKILL' }, () => {});
+      return supervisor.connected;
+    },
+  };
+  supervisor.once('exit', (code, signal) => {
+    facade.supervisorExit = { code, signal };
+    if (facade.exitCode === null && facade.signalCode === null) {
+      facade.observationError = lifecycleError('DASHBOARD_SUPERVISOR_LOST');
+    }
+  });
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      facade.kill(); reject(lifecycleError('DASHBOARD_SUPERVISOR_START_TIMEOUT'));
+    }, 15_000);
+    const fail = (error) => { clearTimeout(timer); reject(error); };
+    supervisor.once('error', fail);
+    supervisor.once('exit', () => fail(lifecycleError('DASHBOARD_SUPERVISOR_UNAVAILABLE')));
+    supervisor.on('message', (message) => {
+      if (message?.type === 'dashboard_child_exited' && message.pid === facade.pid) {
+        facade.exitCode = message.code; facade.signalCode = message.signal;
+      }
+      if (message?.type === 'supervisor_error') {
+        facade.observationError = lifecycleError(message.code);
+        fail(facade.observationError);
+      }
+      if (message?.type === 'dashboard_child_started' && message.run_id === run.run_id
+        && Number.isSafeInteger(message.pid) && message.pid > 0) {
+        clearTimeout(timer); facade.pid = message.pid; resolve();
+      }
+    });
+  });
+  return facade;
+}

package/src/dashboard-windows-process-control.ps1

@@ -0,0 +1,40 @@
+param(
+  [Parameter(Mandatory=$true)][int]$ChildPid,
+  [Parameter(Mandatory=$true)][string]$BirthFileTime,
+  [uint32]$RequestedExitCode = 1
+)
+$ErrorActionPreference = 'Stop'
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+public static class DashboardOwnedProcess {
+  [DllImport("kernel32.dll", SetLastError=true)] public static extern IntPtr OpenProcess(uint access, bool inherit, int pid);
+  [DllImport("kernel32.dll", SetLastError=true)] public static extern bool GetProcessTimes(IntPtr h, out long birth, out long exit, out long kernel, out long user);
+  [DllImport("kernel32.dll", SetLastError=true)] public static extern bool TerminateProcess(IntPtr h, uint exit);
+  [DllImport("kernel32.dll", SetLastError=true)] public static extern uint WaitForSingleObject(IntPtr h, uint ms);
+  [DllImport("kernel32.dll", SetLastError=true)] public static extern bool GetExitCodeProcess(IntPtr h, out uint exit);
+  [DllImport("kernel32.dll")] public static extern bool CloseHandle(IntPtr h);
+}
+'@
+# PROCESS_QUERY_LIMITED_INFORMATION | SYNCHRONIZE | PROCESS_TERMINATE. No debug privilege.
+$handle = [DashboardOwnedProcess]::OpenProcess(0x101001, $false, $ChildPid)
+if ($handle -eq [IntPtr]::Zero) { throw 'DASHBOARD_CHILD_OPEN_FAILED' }
+try {
+  [long]$birth=0; [long]$ended=0; [long]$kernel=0; [long]$user=0
+  if (-not [DashboardOwnedProcess]::GetProcessTimes($handle,[ref]$birth,[ref]$ended,[ref]$kernel,[ref]$user)) { throw 'DASHBOARD_CHILD_BIRTH_FAILED' }
+  if ($birth.ToString() -cne $BirthFileTime) { throw 'DASHBOARD_CHILD_IDENTITY_MISMATCH' }
+  $alreadyExited = [DashboardOwnedProcess]::WaitForSingleObject($handle,0) -eq 0
+  $requested = $false
+  if (-not $alreadyExited) {
+    if (-not [DashboardOwnedProcess]::TerminateProcess($handle,$RequestedExitCode)) {
+      # A racing natural exit may win. Verify it with this handle, never invent the requested value.
+      if ([DashboardOwnedProcess]::WaitForSingleObject($handle,0) -ne 0) { throw 'DASHBOARD_CHILD_TERMINATE_FAILED' }
+    } else { $requested = $true }
+  }
+  if ([DashboardOwnedProcess]::WaitForSingleObject($handle,5000) -ne 0) { throw 'DASHBOARD_CHILD_WAIT_FAILED' }
+  [uint32]$actual=0
+  if (-not [DashboardOwnedProcess]::GetExitCodeProcess($handle,[ref]$actual)) { throw 'DASHBOARD_CHILD_EXIT_READ_FAILED' }
+  [ordered]@{schema='lattice.dashboard_process_control.v1';pid=$ChildPid;birth_filetime=$BirthFileTime;
+    termination_requested=$requested;requested_exit_code=$RequestedExitCode;actual_exit_code=$actual;
+    actual_exit_hex=('0x{0:X8}' -f $actual);source='GetExitCodeProcess'} | ConvertTo-Json -Compress
+} finally { [void][DashboardOwnedProcess]::CloseHandle($handle) }

package/src/factory-diagnostics.mjs

@@ -1,6 +1,7 @@
 import { readFile, lstat } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { evaluateNodeVersionGuard } from './node-version-guard.mjs';
 
 /**
  * dotagents工場の native factory diagnostics 面（親plan L6要件）。
@@ -17,7 +18,7 @@ const MAX_DETAIL_LENGTH = 256;
 const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 const UNKNOWN_VERSION_SENTINEL = '0.0.0-unknown';
 const NODE_VERSION_PATTERN = /^v(\d+)\.(\d+)\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
-const ENGINES_FLOOR_RANGE_PATTERN = /^(>=(\d+)(?:\.(\d+))?(?:\.\d+)?)(?: +<25(?:\.0\.0)? +\|\| +>=26(?:\.0\.0)?)$/;
+const ENGINE_COMPARATOR = /^(>=|<)(\d+)(?:\.(\d+))?(?:\.(\d+))?$/u;
 const CHECK_IDS = Object.freeze([
   'package_version',
   'node_runtime',
@@ -70,18 +71,30 @@ function checkNodeRuntime(nodeVersion, enginesNode) {
   if (!runtime) {
     return check('node_runtime', false, 'node version is unreadable');
   }
-  const floor = ENGINES_FLOOR_RANGE_PATTERN.exec(enginesNode ?? '');
-  if (!floor) {
-    return check('node_runtime', false, 'package.json engines.node floor is unreadable');
+  // Lattice declares disjunctions of numeric >= floors and optional < ceilings.
+  // Parse the entire declared contract; a floor-only check silently accepts holes.
+  const alternatives = typeof enginesNode === 'string' ? enginesNode.split(' || ') : [];
+  const ranges = alternatives.map((range) => range.split(' ').map((part) => ENGINE_COMPARATOR.exec(part)));
+  if (ranges.length === 0 || ranges.some((range) => range.length < 1 || range.length > 2
+    || range.some((part) => part === null) || range[0][1] !== '>='
+    || (range.length === 2 && range[1][1] !== '<'))) {
+    return check('node_runtime', false, 'package.json engines.node range is unreadable');
   }
-  const [major, minor] = [Number(runtime[1]), Number(runtime[2])];
-  const [floorMajor, floorMinor] = [Number(floor[2]), Number(floor[3] ?? '0')];
-  const satisfied = major > floorMajor || (major === floorMajor && minor >= floorMinor);
+  const actual = nodeVersion.slice(1).split(/[.+-]/u).slice(0, 3).map(Number);
+  const compare = (bound) => {
+    const version = bound.slice(2, 5).map((part) => Number(part ?? 0));
+    for (let index = 0; index < 3; index += 1) {
+      if (actual[index] !== version[index]) return actual[index] < version[index] ? -1 : 1;
+    }
+    return 0;
+  };
+  const satisfied = ranges.some((range) => range.every((bound) =>
+    bound[1] === '>=' ? compare(bound) >= 0 : compare(bound) < 0))
+    && !evaluateNodeVersionGuard(nodeVersion.slice(1), false).blocked;
   return check(
     'node_runtime',
     satisfied,
-    satisfied ? `${nodeVersion} satisfies engines.node floor ${floor[1]}`
-      : `${nodeVersion} is below engines.node floor ${floor[1]}`,
+    `${nodeVersion} ${satisfied ? 'satisfies' : 'does not satisfy'} engines.node ${enginesNode}`,
   );
 }
 

package/src/node-version-guard.mjs

@@ -1,44 +1,5 @@
-/**
- * lattice-mcp bin向けNode versionガード（ADR 0049 wave2レビューでのスコープ外
- * 発見の修理 — bin/lattice-mcp.mjs が sensor/dist/index.js を直import して
- * MCPServer を起動する経路には、sensor CLI (sensor/src/bin/sensor.ts) が
- * 持つNode versionガードが一切通っていなかった）。
- *
- * 閾値・banner文言は複製せず、sensor CLI と同じ
- * `sensor/dist/bin/node-version-check.js`（Node 25.x のV8 turboshaft WASM JIT
- * Zone allocatorバグと、MIN_NODE_MAJOR未満のfloorを扱う）から再利用する。
- *
- * 判定ロジックだけをここに切り出し、process.versions.node / env を直接
- * 読まない純関数にすることで、境界値（MIN_NODE_MAJOR-1 / MIN_NODE_MAJOR /
- * 24 / 25 / 26、override有無）をunit testで固定できるようにする。
- */
-
-import {
+/** Shared sensor/MCP runtime compatibility policy; no bootstrap side effects. */
+export {
   MIN_NODE_MAJOR,
-  buildNode25BlockBanner,
-  buildNodeTooOldBanner,
-  isNode25Affected,
+  evaluateNodeVersionGuard,
 } from '../sensor/dist/bin/node-version-check.js';
-
-export { MIN_NODE_MAJOR };
-
-/**
- * @param {string} nodeVersion - process.versions.node相当の文字列 (例: "26.5.0")
- * @param {boolean} overrideActive - LATTICE_SENSOR_ALLOW_UNSAFE_NODE が設定されているか
- * @returns {{ blocked: boolean, banner: string | null }}
- *   banner: 表示すべきbanner文言（sensor CLIと同一文言）。null ならサポート
- *     対象内で表示不要。
- *   blocked: true なら呼び出し側は起動を止める（exit 1 相当）。
- *     override有効時は nodeMajor が範囲外でも blocked は false になるが、
- *     banner は「表示のみ」で non-null のまま返る（sensor CLIと同一意味論）。
- */
-export function evaluateNodeVersionGuard(nodeVersion, overrideActive) {
-  const nodeMajor = parseInt(nodeVersion.split('.')[0] ?? '0', 10);
-  if (isNode25Affected(nodeMajor)) {
-    return { blocked: !overrideActive, banner: buildNode25BlockBanner(nodeVersion) };
-  }
-  if (nodeMajor < MIN_NODE_MAJOR) {
-    return { blocked: !overrideActive, banner: buildNodeTooOldBanner(nodeVersion) };
-  }
-  return { blocked: false, banner: null };
-}