@quolu/lattice 0.79.3 → 0.79.4

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 };
-}

package/src/todo-dashboard-registry.mjs

@@ -1,4 +1,3 @@
-import { spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
 import {
@@ -9,6 +8,10 @@ import path from 'node:path';
 import packageJson from '../package.json' with { type: 'json' };
 import { isAuditPendingPhaseStatus } from './todo-audit-pending.mjs';
 import { observeStartIdentityEpochMs } from './runtime-os-observation.mjs';
+import { spawnSupervisedDashboard } from './dashboard-supervisor.mjs';
+import { reconcileLifecycleRuns, readDashboardLifecycleStatus,
+  recordDashboardEnsureDecision } from './dashboard-lifecycle-journal.mjs';
+import { observeDashboardProcess } from './dashboard-process-control.mjs';
 
 /**
  * The version of the code in THIS process. A daemon loads its modules once at
@@ -49,6 +52,10 @@ function paths(env) {
   };
 }
 
+export async function readTodoDashboardLifecycleStatus({ env = process.env } = {}) {
+  return readDashboardLifecycleStatus(runtimeDir(env));
+}
+
 function validEntry(entry) {
   return entry !== null && typeof entry === 'object' && !Array.isArray(entry)
     && Object.keys(entry).sort().join(',') === 'display_name,last_seen_at,project_id,repo_root,session_id'
@@ -523,7 +530,7 @@ export async function forgetTodoDashboardDaemonRecord({ env = process.env } = {}
   await rm(daemonRecordRef(paths(env), process.pid), { force: true });
 }
 
-export async function ensureTodoDashboardDaemon({ env = process.env, spawnDaemon = spawn,
+export async function ensureTodoDashboardDaemon({ env = process.env, spawnDaemon = spawnSupervisedDashboard,
   signalProcess = process.kill, isProcessAlive = processIsAlive, startupTimeoutMs = 120_000,
   legacyStopTimeoutMs = 3_000, replacementIsProcessAlive = processIsAlive,
   attestationTimeoutMs = 2_000, strayStopTimeoutMs = 3_000,
@@ -535,15 +542,18 @@ export async function ensureTodoDashboardDaemon({ env = process.env, spawnDaemon
   const reap = (keepPid) => reapStrayDaemons(refs, keepPid,
     { signalProcess, isProcessAlive, timeoutMs: strayStopTimeoutMs });
   return withLock(refs.startupLock, async () => {
+    await reconcileLifecycleRuns(refs.root, observeDashboardProcess);
     const existing = await readJson(refs.descriptor, null);
     const existingAttestation = await daemonAttestation(existing, { timeoutMs: attestationTimeoutMs });
     if (existingAttestation === 'current') {
+      await recordDashboardEnsureDecision(refs.root, 'reuse_current', existing.pid);
       await reap(existing.pid);
       return existing;
     }
     if (validDaemonDescriptor(existing) && existingAttestation === null
       && await isProcessAlive(existing.pid)
       && !await descriptorPidWasReused(existing, { observeProcessStartEpochMs })) {
+      await recordDashboardEnsureDecision(refs.root, 'alive_unresponsive', existing.pid);
       throw dashboardError('DASHBOARD_DAEMON_UNRESPONSIVE', 'dashboard daemon is alive but temporarily unresponsive');
     }
     let legacy = existingAttestation === 'legacy' ? existing : null;
@@ -558,6 +568,7 @@ export async function ensureTodoDashboardDaemon({ env = process.env, spawnDaemon
         // 引き取った相手は生きて応答しているので、descriptorの不変条件を満たす。
         await atomicJson(refs.descriptor, adopted.record);
         if (adopted.attestation === 'current') {
+          await recordDashboardEnsureDecision(refs.root, 'adopt_current', adopted.record.pid);
           await reap(adopted.record.pid);
           return adopted.record;
         }
@@ -569,9 +580,14 @@ export async function ensureTodoDashboardDaemon({ env = process.env, spawnDaemon
       && Number(portText) <= 65_535 ? Number(portText) : DEFAULT_PORT;
     const port = legacy === null ? configuredPort : 0;
     if (legacy === null) await rm(refs.descriptor, { force: true });
-    const child = spawnDaemon(process.execPath, [path.resolve(import.meta.dirname, '../bin/lattice-dashboard.mjs')], {
+    const startupDecision = legacy !== null ? 'replace_legacy'
+      : validDaemonDescriptor(existing) && await isProcessAlive(existing.pid) ? 'pid_reused'
+        : 'start_missing';
+    await recordDashboardEnsureDecision(refs.root, startupDecision, legacy?.pid ?? null);
+    const child = await spawnDaemon(process.execPath, [path.resolve(import.meta.dirname, '../bin/lattice-dashboard.mjs')], {
       detached: true,
       stdio: 'ignore',
+      version: TODO_DASHBOARD_CODE_VERSION,
       env: { ...env, LATTICE_DASHBOARD_RUNTIME_DIR: refs.root, LATTICE_DASHBOARD_PORT: String(port) },
     });
     child.unref();
@@ -584,6 +600,10 @@ export async function ensureTodoDashboardDaemon({ env = process.env, spawnDaemon
     const deadline = Date.now() + startupTimeoutMs;
     while (Date.now() < deadline) {
       await new Promise((resolve) => setTimeout(resolve, 50));
+      if (child.observationError) {
+        child.kill?.('SIGTERM');
+        throw child.observationError;
+      }
       const descriptor = typeof child.pid === 'number'
         ? await readJson(daemonRecordRef(refs, child.pid), null) : null;
       const healthy = await daemonHealthy(descriptor);
@@ -601,6 +621,7 @@ export async function ensureTodoDashboardDaemon({ env = process.env, spawnDaemon
           }
         }
         await atomicJson(refs.descriptor, descriptor);
+        await recordDashboardEnsureDecision(refs.root, startupDecision, descriptor.pid);
         await reap(descriptor.pid);
         return descriptor;
       }