machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/src/local/security-audit-warning.mjs

@@ -0,0 +1,31 @@
+const DEFAULT_WARNING_INTERVAL_MS = 60_000;
+
+export function createSecurityAuditFailureReporter(logger, options = {}) {
+  const now = typeof options.now === "function" ? options.now : Date.now;
+  const intervalMs = positiveInteger(options.intervalMs, DEFAULT_WARNING_INTERVAL_MS);
+  const state = new Map();
+  return {
+    report(event, fields, message) {
+      if (typeof logger?.event !== "function") return false;
+      const key = String(event || "security.audit.failure");
+      const current = Number(now()) || 0;
+      const previous = state.get(key);
+      if (previous && current - previous.lastAt < intervalMs) {
+        previous.suppressed += 1;
+        return false;
+      }
+      const suppressed = previous?.suppressed || 0;
+      state.set(key, { lastAt: current, suppressed: 0 });
+      logger.event("warn", key, {
+        ...(fields && typeof fields === "object" ? fields : {}),
+        ...(suppressed > 0 ? { suppressed } : {}),
+      }, message);
+      return true;
+    },
+  };
+}
+
+function positiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}

package/src/local/security-audit-worker.mjs

@@ -0,0 +1,87 @@
+import { parentPort, workerData } from "node:worker_threads";
+import {
+  auditErrorClass,
+  createAuditStorageSession,
+  unhealthyAuditSnapshot,
+} from "./security-audit-storage.mjs";
+
+const root = String(workerData?.root || "");
+const MAX_BATCH = 128;
+const BATCH_DELAY_MS = 5;
+const storage = createAuditStorageSession(root);
+const pending = [];
+let timer = null;
+let draining = false;
+let closeRequested = false;
+
+try {
+  parentPort.postMessage({ type: "ready", snapshot: storage.snapshot() });
+} catch (error) {
+  parentPort.postMessage({ type: "ready", snapshot: unhealthyAuditSnapshot(error) });
+}
+
+parentPort.on("message", (message) => {
+  if (message?.type === "record") {
+    pending.push(message);
+    scheduleDrain();
+    return;
+  }
+  if (message?.type === "flush") {
+    pending.push({ type: "barrier", id: message.id });
+    scheduleDrain(true);
+    return;
+  }
+  if (message?.type === "close") {
+    closeRequested = true;
+    pending.push({ type: "barrier", id: message.id, close: true });
+    scheduleDrain(true);
+  }
+});
+
+function scheduleDrain(immediate = false) {
+  if (draining || timer) return;
+  timer = setTimeout(() => {
+    timer = null;
+    void drain();
+  }, immediate ? 0 : BATCH_DELAY_MS);
+  timer.unref?.();
+}
+
+async function drain() {
+  if (draining) return;
+  draining = true;
+  try {
+    while (pending.length > 0) {
+      const records = [];
+      const barriers = [];
+      while (pending.length > 0 && records.length < MAX_BATCH) {
+        const item = pending.shift();
+        if (item.type === "record") records.push(item);
+        else barriers.push(item);
+        if (barriers.length > 0 && records.length === 0) break;
+      }
+      if (records.length > 0) {
+        try {
+          const snapshot = await storage.recordBatch(records.map(({ input, nowMs }) => ({ input, nowMs })));
+          parentPort.postMessage({
+            type: "record_batch_result", ids: records.map((item) => item.id), recorded: true, snapshot,
+          });
+        } catch (error) {
+          const errorClass = auditErrorClass(error);
+          const snapshot = unhealthyAuditSnapshot(error);
+          parentPort.postMessage({
+            type: "record_batch_result", ids: records.map((item) => item.id), recorded: false,
+            error_class: errorClass, snapshot,
+          });
+        }
+      }
+      for (const barrier of barriers) {
+        parentPort.postMessage({ type: barrier.close ? "closed" : "flushed", id: barrier.id });
+      }
+    }
+  } finally {
+    draining = false;
+    if (pending.length > 0) scheduleDrain(true);
+    else if (closeRequested) parentPort.close();
+  }
+}

package/src/local/service-convergence.mjs

@@ -1,14 +1,55 @@
 const DEFAULT_ATTEMPTS = 20;
 const DEFAULT_DELAY_MS = 100;
 
+export async function waitForStableActiveStatus(
+  readStatus,
+  { attempts = DEFAULT_ATTEMPTS, delayMs = DEFAULT_DELAY_MS, stableSamples = 5, sleep = delay, identity = stableIdentity } = {},
+) {
+  if (typeof readStatus !== "function") throw new TypeError("readStatus must be a function");
+  if (typeof identity !== "function") throw new TypeError("identity must be a function");
+  const maximum = Number.isInteger(attempts) && attempts > 0 ? attempts : DEFAULT_ATTEMPTS;
+  const required = Number.isInteger(stableSamples) && stableSamples > 0 ? stableSamples : 5;
+  let status = null;
+  let consecutive = 0;
+  let priorIdentity = null;
+  for (let attempt = 1; attempt <= maximum; attempt += 1) {
+    status = await readStatus();
+    const currentIdentity = status?.active === true ? identity(status) : null;
+    const identityChanged = consecutive > 0
+      && (priorIdentity !== null || currentIdentity !== null)
+      && currentIdentity !== priorIdentity;
+    if (status?.active === true && !identityChanged) consecutive += 1;
+    else consecutive = status?.active === true ? 1 : 0;
+    priorIdentity = currentIdentity;
+    if (consecutive >= required) return { stable: true, status, samples: consecutive, attempts: attempt };
+    if (attempt < maximum) await sleep(delayMs);
+  }
+  return { stable: false, status, samples: consecutive, attempts: maximum };
+}
+
+function stableIdentity(status) {
+  if (Number.isInteger(status?.pid) && status.pid > 0) return `pid:${status.pid}`;
+  if (typeof status?.last_run_time === "string" && status.last_run_time) return `run:${status.last_run_time}`;
+  return null;
+}
+
 export async function waitForInactiveStatus(
   readStatus,
   { attempts = DEFAULT_ATTEMPTS, delayMs = DEFAULT_DELAY_MS, sleep = delay } = {},
+) {
+  return waitForStatus(readStatus, (status) => status?.active !== true, { attempts, delayMs, sleep });
+}
+
+export async function waitForStatus(
+  readStatus,
+  predicate,
+  { attempts = DEFAULT_ATTEMPTS, delayMs = DEFAULT_DELAY_MS, sleep = delay } = {},
 ) {
   if (typeof readStatus !== "function") throw new TypeError("readStatus must be a function");
+  if (typeof predicate !== "function") throw new TypeError("predicate must be a function");
   const maximum = Number.isInteger(attempts) && attempts > 0 ? attempts : DEFAULT_ATTEMPTS;
   let status = await readStatus();
-  for (let attempt = 1; status?.active === true && attempt < maximum; attempt += 1) {
+  for (let attempt = 1; !predicate(status) && attempt < maximum; attempt += 1) {
     await sleep(delayMs);
     status = await readStatus();
   }

package/src/local/service-definition.mjs

@@ -0,0 +1,24 @@
+import { lstatSync } from "node:fs";
+import { readBoundedRegularFileWithInfoSync, unlinkRegularFileIfIdentitySync } from "./secure-file.mjs";
+
+const MAX_SERVICE_DEFINITION_BYTES = 256 * 1024;
+
+export function snapshotServiceDefinition(file, label = "service definition") {
+  try {
+    return readBoundedRegularFileWithInfoSync(file, MAX_SERVICE_DEFINITION_BYTES, label, {
+      verifyPathIdentity: true,
+      rejectMultipleLinks: true,
+    }).identity;
+  } catch (error) {
+    if (error?.code === "ENOENT" || error?.cause?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export function removeServiceDefinitionIfCurrent(file, expectedIdentity, label = "service definition") {
+  if (!expectedIdentity) {
+    try { lstatSync(file, { bigint: true }); return false; }
+    catch (error) { if (error?.code === "ENOENT") return true; throw error; }
+  }
+  return unlinkRegularFileIfIdentitySync(file, expectedIdentity, label);
+}

package/src/local/service-environment.mjs

@@ -1,7 +1,6 @@
-import { existsSync } from "node:fs";
 import path from "node:path";
 import { replaceFileAtomicallySync } from "./exclusive-file.mjs";
-import { readBoundedRegularFileSync } from "./secure-file.mjs";
+import { inspectPathIfPresentSync, readBoundedRegularFileSync } from "./secure-file.mjs";
 
 const SERVICE_ENVIRONMENT_SCHEMA = 1;
 const MAX_SERVICE_ENVIRONMENT_BYTES = 64 * 1024;
@@ -38,9 +37,10 @@ export function captureServiceEnvironment(environment = process.env) {
   return captured;
 }
 
-export function writeServiceEnvironment(stateRoot, environment = process.env) {
+export function writeServiceEnvironment(stateRoot, environment = process.env, options = {}) {
   const file = serviceEnvironmentPath(stateRoot);
-  const previous = existsSync(file) ? parseServiceEnvironment(file).environment : {};
+  const previousPayload = serviceEnvironmentIfPresent(file, options);
+  const previous = previousPayload ? previousPayload.environment : {};
   const captured = captureServiceEnvironment(environment);
   const merged = { ...previous };
   for (const [key, value] of Object.entries(captured)) {
@@ -64,8 +64,8 @@ export function writeServiceEnvironment(stateRoot, environment = process.env) {
 
 export function loadServiceEnvironment(stateRoot, targetEnvironment = process.env, options = {}) {
   const file = serviceEnvironmentPath(stateRoot);
-  if (!existsSync(file)) return { path: file, keys: [], loaded: false };
-  const payload = parseServiceEnvironment(file);
+  const payload = serviceEnvironmentIfPresent(file, options);
+  if (!payload) return { path: file, keys: [], loaded: false };
   const platform = String(options.platform || process.platform);
   const loaded = [];
   for (const [key, rawValue] of Object.entries(payload.environment)) {
@@ -77,15 +77,23 @@ export function loadServiceEnvironment(stateRoot, targetEnvironment = process.en
   return { path: file, keys: loaded.sort(), loaded: true };
 }
 
-export function serviceEnvironmentSummary(stateRoot) {
+export function serviceEnvironmentSummary(stateRoot, options = {}) {
   const file = serviceEnvironmentPath(stateRoot);
-  if (!existsSync(file)) return { configured: false, keys: [] };
-  const payload = parseServiceEnvironment(file);
+  const payload = serviceEnvironmentIfPresent(file, options);
+  if (!payload) return { configured: false, keys: [] };
   return { configured: true, keys: Object.keys(payload.environment).sort() };
 }
 
+function serviceEnvironmentIfPresent(file, options = {}) {
+  const inspect = options.inspectPathIfPresentSync || inspectPathIfPresentSync;
+  const info = inspect(file, "service environment file");
+  if (!info) return null;
+  if (info.isSymbolicLink() || !info.isFile()) throw new Error("service environment file must be a regular file and not a symbolic link");
+  return parseServiceEnvironment(file);
+}
+
 function parseServiceEnvironment(file) {
-  const content = readBoundedRegularFileSync(file, MAX_SERVICE_ENVIRONMENT_BYTES, "service environment file");
+  const content = readBoundedRegularFileSync(file, MAX_SERVICE_ENVIRONMENT_BYTES, "service environment file", { verifyPathIdentity: true, rejectMultipleLinks: true });
   let payload;
   try {
     payload = JSON.parse(content.toString("utf8"));

package/src/local/service-owner.mjs

@@ -0,0 +1,146 @@
+// @ts-check
+import { randomBytes } from "node:crypto";
+import { realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { removeOwnedJsonFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
+import { inspectPathIfPresentSync, readBoundedRegularFileSync, readBoundedRegularFileWithInfoSync, unlinkRegularFileIfIdentitySync } from "./secure-file.mjs";
+import { machineServiceControlRoot } from "./state.mjs";
+import { ensureOwnerOnlyDir } from "./secure-file.mjs";
+const SCHEMA_VERSION = 1;
+const MAX_BYTES = 64 * 1024;
+const FILE_NAME = "service-owner.json";
+const VERSION = /^[0-9A-Za-z.+_-]{1,64}$/;
+const TRANSACTION = /^[A-Za-z0-9_-]{20,128}$/;
+/** @typedef {{ schemaVersion: 1, status: "pending" | "committed", transactionId: string, workspace: string, stateRoot: string, entryScript: string, version: string, createdAt: string, committedAt: string | null }} ServiceOwner */
+/** @typedef {{ workspace?: unknown, stateRoot?: unknown, entryScript?: unknown, version?: unknown }} ServiceOwnerSpec */
+/** @typedef {{ controlRoot?: string, inspectPathIfPresentSync?: typeof inspectPathIfPresentSync }} ServiceOwnerOptions */
+/** @param {ServiceOwnerOptions} [options] */ export function serviceOwnerPath(options = {}) {
+  return path.join(machineServiceControlRoot(options), FILE_NAME);
+}
+/** @param {ServiceOwnerSpec} spec @param {ServiceOwnerOptions} [options] */ export function beginServiceOwnerUpdate(spec, options = {}) {
+  const file = serviceOwnerPath(options);
+  ensureOwnerOnlyDir(path.dirname(file));
+  const previous = readOwnerSnapshotIfPresent(file, options);
+  const transactionId = randomBytes(24).toString("base64url");
+  const createdAt = new Date().toISOString();
+  const pending = normalizeOwner({
+    schemaVersion: SCHEMA_VERSION,
+    status: "pending",
+    transactionId,
+    workspace: spec?.workspace,
+    stateRoot: spec?.stateRoot,
+    entryScript: spec?.entryScript,
+    version: spec?.version,
+    createdAt,
+    committedAt: null,
+  });
+  writeOwner(file, pending);
+  let closed = false;
+  return {
+    path: file,
+    owner: pending,
+    commit() {
+      if (closed) throw new Error("service owner transaction is already closed");
+      assertCurrentTransaction(file, transactionId, "pending");
+      const committed = normalizeOwner({ ...pending, status: "committed", committedAt: new Date().toISOString() });
+      writeOwner(file, committed);
+      closed = true;
+      return committed;
+    },
+    rollback() {
+      if (closed) return false;
+      assertCurrentTransaction(file, transactionId, "pending");
+      if (previous) replaceFileAtomicallySync(file, previous.raw, { mode: 0o600 });
+      else if (!removeOwnedJsonFileSync(file, { transactionId, status: "pending" }, { maxBytes: MAX_BYTES })) {
+        throw new Error("machine service owner transaction changed before rollback");
+      }
+      closed = true;
+      return true;
+    },
+  };
+}
+/** @param {ServiceOwnerOptions} [options] @returns {ServiceOwner | null} */ export function loadServiceOwner(options = {}) {
+  const file = serviceOwnerPath(options);
+  return readOwnerSnapshotIfPresent(file, options)?.owner || null;
+}
+/** @param {ServiceOwnerOptions} [options] @returns {ServiceOwner | null} */ export function loadCommittedServiceOwner(options = {}) {
+  const owner = loadServiceOwner(options);
+  if (!owner) return null;
+  if (owner.status !== "committed") {
+    throw new Error("machine service owner transition is incomplete; reinstall the service before starting it");
+  }
+  return owner;
+}
+/** @param {ServiceOwnerOptions} [options] */ export function removeServiceOwner(options = {}) {
+  const file = serviceOwnerPath(options);
+  const inspect = options.inspectPathIfPresentSync || inspectPathIfPresentSync;
+  const info = inspect(file, "machine service owner file");
+  if (!info) return false;
+  if (info.isSymbolicLink() || !info.isFile()) throw new Error("machine service owner file must be a regular file and not a symbolic link");
+  const opened = readBoundedRegularFileWithInfoSync(file, MAX_BYTES, "machine service owner file", {
+    verifyPathIdentity: true, rejectMultipleLinks: true,
+  });
+  if (!unlinkRegularFileIfIdentitySync(file, opened.identity, "machine service owner file")) {
+    throw new Error("machine service owner changed before removal");
+  }
+  return true;
+}
+/** @param {string} file @param {ServiceOwnerOptions} [options] @returns {{ owner: ServiceOwner, raw: Buffer } | null} */ function readOwnerSnapshotIfPresent(file, options = {}) {
+  const inspect = options.inspectPathIfPresentSync || inspectPathIfPresentSync;
+  const info = inspect(file, "machine service owner file");
+  if (!info) return null;
+  if (info.isSymbolicLink() || !info.isFile()) throw new Error("machine service owner file must be a regular file and not a symbolic link");
+  return readOwnerSnapshot(file);
+}
+/** @param {string} file @returns {{ owner: ServiceOwner, raw: Buffer }} */ function readOwnerSnapshot(file) {
+  const raw = readBoundedRegularFileSync(file, MAX_BYTES, "machine service owner file", { verifyPathIdentity: true, rejectMultipleLinks: true });
+  let parsed;
+  try { parsed = JSON.parse(raw.toString("utf8")); }
+  catch (error) { throw new Error("machine service owner file is not valid JSON", { cause: error }); }
+  return { owner: normalizeOwner(parsed), raw };
+}
+/** @param {string} file @param {ServiceOwner} owner */ function writeOwner(file, owner) {
+  const content = `${JSON.stringify(owner, null, 2)}\n`;
+  if (Buffer.byteLength(content) > MAX_BYTES) throw new Error("machine service owner record exceeds the size limit");
+  replaceFileAtomicallySync(file, content, { mode: 0o600 });
+}
+/** @param {string} file @param {string} transactionId @param {"pending" | "committed"} status */ function assertCurrentTransaction(file, transactionId, status) {
+  const current = readOwnerSnapshot(file).owner;
+  if (current.transactionId !== transactionId || current.status !== status) {
+    throw new Error("machine service owner transaction changed before completion");
+  }
+}
+/** @param {unknown} value @returns {ServiceOwner} */ function normalizeOwner(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("machine service owner must be an object");
+  const record = /** @type {Record<string, unknown>} */ (value);
+  if (record.schemaVersion !== SCHEMA_VERSION) throw new Error("machine service owner schema is unsupported");
+  if (record.status !== "pending" && record.status !== "committed") throw new Error("machine service owner status is invalid");
+  if (typeof record.transactionId !== "string" || !TRANSACTION.test(record.transactionId)) throw new Error("machine service owner transaction id is invalid");
+  if (typeof record.version !== "string" || !VERSION.test(record.version)) throw new Error("machine service owner version is invalid");
+  const workspace = canonicalDirectory(record.workspace, "workspace");
+  const stateRoot = canonicalDirectory(record.stateRoot, "state root");
+  const entryScript = canonicalFile(record.entryScript, "entry script");
+  const createdAt = isoTimestamp(record.createdAt, "createdAt");
+  const committedAt = record.status === "committed" ? isoTimestamp(record.committedAt, "committedAt") : null;
+  return { schemaVersion: SCHEMA_VERSION, status: record.status, transactionId: record.transactionId,
+    workspace, stateRoot, entryScript, version: record.version, createdAt, committedAt };
+}
+/** @param {unknown} value @param {string} label */ function canonicalDirectory(value, label) {
+  const canonical = canonicalPath(value, label);
+  if (!statSync(canonical).isDirectory()) throw new Error(`machine service owner ${label} is not a directory`);
+  return canonical;
+}
+/** @param {unknown} value @param {string} label */ function canonicalFile(value, label) {
+  const canonical = canonicalPath(value, label);
+  if (!statSync(canonical).isFile()) throw new Error(`machine service owner ${label} is not a file`);
+  return canonical;
+}
+/** @param {unknown} value @param {string} label */ function canonicalPath(value, label) {
+  if (typeof value !== "string" || !path.isAbsolute(value)) throw new Error(`machine service owner ${label} must be absolute`);
+  try { return realpathSync.native ? realpathSync.native(value) : realpathSync(value); }
+  catch (error) { throw new Error(`machine service owner ${label} is unavailable`, { cause: error }); }
+}
+/** @param {unknown} value @param {string} label */ function isoTimestamp(value, label) {
+  if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) throw new Error(`machine service owner ${label} is invalid`);
+  return value;
+}

package/src/local/service-ownership.mjs

@@ -0,0 +1,17 @@
+export async function stopOwnedPlatformService({
+  state,
+  inspectWorkspaceDaemon,
+  ownsPlatformAutostart,
+  stopPlatformService,
+} = {}) {
+  if (!state) throw new TypeError("service ownership check requires state");
+  if (typeof inspectWorkspaceDaemon !== "function") throw new TypeError("service ownership check requires inspectWorkspaceDaemon");
+  if (typeof ownsPlatformAutostart !== "function") throw new TypeError("service ownership check requires ownsPlatformAutostart");
+  if (typeof stopPlatformService !== "function") throw new TypeError("service ownership check requires stopPlatformService");
+  const daemon = inspectWorkspaceDaemon(state);
+  if (!ownsPlatformAutostart(daemon)) {
+    return { owned: false, stopped: false, daemon, provider: null };
+  }
+  const provider = await stopPlatformService();
+  return { owned: true, stopped: provider?.ok !== false, daemon, provider };
+}

package/src/local/service-restart-handoff.mjs

@@ -0,0 +1,64 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { restartOwnedServiceRuntime } from "./service-runtime.mjs";
+import { createLogger } from "./log.mjs";
+import { acquireMachineServiceLockWithWait } from "./state.mjs";
+
+const DEFAULT_DELAY_MS = 300;
+const MAX_DELAY_MS = 5_000;
+
+export async function runServiceRestartHandoff(options = {}) {
+  const delayMs = boundedDelay(options.delayMs ?? process.argv[2]);
+  const restart = typeof options.restartServiceRuntime === "function"
+    ? options.restartServiceRuntime
+    : typeof options.restartAutostart === "function" ? options.restartAutostart : restartOwnedServiceRuntime;
+  const sleep = typeof options.sleep === "function" ? options.sleep : delay;
+  const logger = options.logger || createLogger({ component: "service-restart", level: "warn", format: "json", stderrOnly: true });
+  const acquireLock = typeof options.acquireServiceLock === "function"
+    ? options.acquireServiceLock
+    : () => acquireMachineServiceLockWithWait({ operation: "service-restart", logger, ...(options.serviceLockOptions || {}) });
+  await sleep(delayMs);
+  const lock = await acquireLock();
+  if (!lock?.acquired || typeof lock.release !== "function") {
+    throw new Error("machine-service operation lock could not be acquired for restart");
+  }
+  try {
+    const result = await restart({ logger });
+    if (result?.ok !== true) {
+      const error = new Error(`service restart handoff failed (${result?.reason || result?.provider || "unknown"})`);
+      error.result = result;
+      throw error;
+    }
+    return result;
+  } finally {
+    lock.release();
+  }
+}
+
+export async function serviceRestartHandoffMain(options = {}) {
+  const run = typeof options.run === "function"
+    ? options.run
+    : () => runServiceRestartHandoff(options.handoffOptions);
+  const logger = options.logger || createLogger({ component: "service-restart", level: "error", format: "json", stderrOnly: true });
+  try {
+    await run();
+    return 0;
+  } catch (error) {
+    logger.error("service restart handoff failed", { error_class: error?.code || error?.name || "execution_failed" });
+    return 1;
+  }
+}
+
+function boundedDelay(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return DEFAULT_DELAY_MS;
+  return Math.min(MAX_DELAY_MS, Math.max(50, Math.floor(parsed)));
+}
+
+function delay(milliseconds) {
+  return new Promise((resolvePromise) => { setTimeout(resolvePromise, milliseconds); });
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  process.exitCode = await serviceRestartHandoffMain();
+}

package/src/local/service-restart-scheduler.mjs

@@ -0,0 +1,49 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { BridgeError } from "./errors.mjs";
+
+const DEFAULT_HANDOFF_DELAY_MS = 300;
+
+export function scheduleServiceRestart(options = {}) {
+  const platform = String(options.platform || process.platform);
+  if (platform === "win32") {
+    throw new BridgeError("unavailable", "in-process Windows service restart is not behavior-verified; run `machine-mcp service stop` and then `machine-mcp service start` from an independent terminal");
+  }
+  const spawnProcess = typeof options.spawnProcess === "function" ? options.spawnProcess : spawn;
+  const node = String(options.node || process.execPath);
+  const helper = String(options.helper || fileURLToPath(new URL("./service-restart-handoff.mjs", import.meta.url)));
+  const delayMs = boundedPositiveInteger(options.delayMs, DEFAULT_HANDOFF_DELAY_MS);
+  const child = spawnProcess(node, [helper, String(delayMs)], {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    shell: false,
+    env: serviceControlEnvironment(options.env || process.env),
+  });
+  return new Promise((resolvePromise, rejectPromise) => {
+    let settled = false;
+    const settle = (callback) => {
+      if (settled) return;
+      settled = true;
+      callback();
+    };
+    child.once("spawn", () => settle(() => {
+      child.unref?.();
+      resolvePromise({ ok: true, scheduled: true, delay_ms: delayMs });
+    }));
+    child.once("error", (error) => settle(() => rejectPromise(error)));
+  });
+}
+
+export function serviceControlEnvironment(source = {}) {
+  const env = {};
+  for (const key of ["PATH", "HOME", "USERPROFILE", "SystemRoot", "WINDIR", "COMSPEC", "PATHEXT", "LANG", "LC_ALL", "LC_CTYPE"]) {
+    if (typeof source[key] === "string" && source[key]) env[key] = source[key];
+  }
+  return env;
+}
+
+function boundedPositiveInteger(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}

package/src/local/service-runtime-convergence.mjs

@@ -0,0 +1,52 @@
+// @ts-check
+
+/** @typedef {Record<string, unknown> & { alive?: boolean, verified_service_daemon?: boolean, mode?: string, startup_readiness_verified?: boolean, identity_reason?: string, pid?: number | null }} DaemonStatus */
+/** @typedef {{ inspectDaemon?: () => DaemonStatus, attempts?: number, delayMs?: number, sleep?: (milliseconds: number) => Promise<void>, replacementPid?: number | null }} OwnedWaitOptions */
+
+const DEFAULT_ATTEMPTS = 900;
+const DEFAULT_DELAY_MS = 100;
+
+/** @param {OwnedWaitOptions} [options] */
+export async function waitForOwnedServiceDaemon(options = {}) {
+  const { inspectDaemon, attempts = DEFAULT_ATTEMPTS, delayMs = DEFAULT_DELAY_MS, sleep = delay } = options;
+  if (typeof inspectDaemon !== "function") throw new TypeError("owned service convergence requires inspectDaemon");
+  const maximum = boundedAttempts(attempts);
+  const replacementPid = positivePid(options.replacementPid);
+  let replacementPending = false;
+  /** @type {DaemonStatus | null} */
+  let daemon = null;
+  for (let attempt = 1; attempt <= maximum; attempt += 1) {
+    daemon = inspectDaemon();
+    if (readyOwnedDaemon(daemon)) {
+      replacementPending = Boolean(replacementPid && Number(daemon.pid) === replacementPid);
+      if (!replacementPending) return { ok: true, attempts: attempt, daemon, reason: null };
+    }
+    if (daemon?.alive === true && daemon.verified_service_daemon !== true) {
+      return { ok: false, attempts: attempt, daemon,
+        reason: `daemon_identity_${daemon.identity_reason || "unverified"}` };
+    }
+    if (attempt < maximum) await sleep(delayMs);
+  }
+  return { ok: false, attempts: maximum, daemon,
+    reason: replacementPending ? "daemon_replacement_not_observed"
+      : daemon?.alive ? "daemon_readiness_not_verified" : "daemon_not_running" };
+}
+
+/** @param {DaemonStatus | null | undefined} daemon */
+export function readyOwnedDaemon(daemon) {
+  return daemon?.alive === true
+    && daemon.verified_service_daemon === true
+    && daemon.mode === "service"
+    && daemon.startup_readiness_verified === true;
+}
+
+/** @param {unknown} value */
+function boundedAttempts(value) {
+  const parsed = value === undefined ? DEFAULT_ATTEMPTS : Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 1800) {
+    throw new Error("owned service convergence attempts must be between 1 and 1800");
+  }
+  return parsed;
+}
+function positivePid(/** @type {unknown} */ value) { const parsed = Number(value); return Number.isInteger(parsed) && parsed > 0 ? parsed : null; }
+function delay(/** @type {number} */ milliseconds) { return new Promise(resolve => { setTimeout(resolve, milliseconds); }); }