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

package/src/local/process-tree-ownership.mjs

@@ -0,0 +1,57 @@
+// @ts-check
+
+import { createSnapshotBudget, processGroupMembers } from "./process-tree-snapshot.mjs";
+export { DEFAULT_PROCESS_OWNERSHIP_CHECK_BUDGET_MS } from "./process-tree-snapshot.mjs";
+/** @typedef {import("./process-tree-ownership-types.d.ts").ChildProcessIdentity} ChildProcessIdentity */
+/** @typedef {import("./process-tree-ownership-types.d.ts").ProcessOwnershipMember} ProcessOwnershipMember */
+/** @typedef {import("./process-tree-ownership-types.d.ts").ProcessOwnershipSnapshot} ProcessOwnershipSnapshot */
+/** @typedef {import("./process-tree-ownership-types.d.ts").ProcessOwnershipOptions} ProcessOwnershipOptions */
+
+export async function captureProcessTreeOwnership(/** @type {ChildProcessIdentity} */ child, /** @type {ProcessOwnershipOptions} */ options = {}) {
+  const pid = positivePid(child?.pid);
+  const platform = String(options.platform || process.platform);
+  if (!pid) return { platform, pid: 0, members: [] };
+  if (platform === "win32") return { platform, pid, members: [{ pid, startedAt: null }] };
+  return { platform, pid, members: await processGroupMembers(pid, options) };
+}
+
+export async function refreshProcessTreeOwnership(/** @type {ProcessOwnershipSnapshot | null | undefined} */ snapshot, /** @type {ProcessOwnershipOptions} */ options = {}) {
+  if (!snapshot?.pid || snapshot.platform === "win32") return snapshot;
+  const members = [...(snapshot.members || [])];
+  for (const observed of await processGroupMembers(snapshot.pid, options)) {
+    if (!members.some((expected) => sameProcessIdentity(expected, observed))) members.push(observed);
+  }
+  return { ...snapshot, members };
+}
+
+export async function processTreeOwnershipStillCurrent(/** @type {ProcessOwnershipSnapshot | null | undefined} */ snapshot, /** @type {ChildProcessIdentity} */ child, /** @type {ProcessOwnershipOptions} */ options = {}) {
+  if (!snapshot?.pid) return false;
+  if (snapshot.platform === "win32") return !childHasExited(child);
+  const members = Array.isArray(snapshot.members) ? snapshot.members : [];
+  if (members.length === 0) return false;
+  const budget = createSnapshotBudget(options);
+  const fullTimeout = budget.take(members.length + 1);
+  if (!fullTimeout) return false;
+  const current = await processGroupMembers(snapshot.pid, options, 0, fullTimeout);
+  if (members.some((expected) => current.some((observed) => sameProcessIdentity(expected, observed)))) return true;
+  for (let index = 0; index < members.length; index += 1) {
+    const timeoutMs = budget.take(members.length - index);
+    if (!timeoutMs) return false;
+    const expected = members[index];
+    const targeted = await processGroupMembers(snapshot.pid, options, expected.pid, timeoutMs);
+    if (targeted.some((observed) => sameProcessIdentity(expected, observed))) return true;
+  }
+  return false;
+}
+
+function sameProcessIdentity(/** @type {ProcessOwnershipMember} */ left, /** @type {ProcessOwnershipMember} */ right) {
+  return left.pid === right.pid && Number.isFinite(left.startedAt) && Number.isFinite(right.startedAt)
+    && left.startedAt === right.startedAt;
+}
+/** @param {unknown} value */
+function positivePid(value) { const parsed = Number(value); return Number.isInteger(parsed) && parsed > 0 ? parsed : 0; }
+/** @param {ChildProcessIdentity} child */
+function childHasExited(child) {
+  return child?.exitCode !== null && child?.exitCode !== undefined
+    || child?.signalCode !== null && child?.signalCode !== undefined;
+}

package/src/local/process-tree-signal.mjs

@@ -0,0 +1,34 @@
+import { spawn } from "node:child_process";
+
+export function terminateProcessTree(child, signal = "SIGTERM", options = {}) {
+  if (!child?.pid) return false;
+  const platform = options.platform || process.platform;
+  if (platform === "win32") {
+    try {
+      const spawnProcess = typeof options.spawnProcess === "function" ? options.spawnProcess : spawn;
+      const force = signal === "SIGKILL";
+      const killer = spawnProcess("taskkill.exe", ["/PID", String(child.pid), "/T", ...(force ? ["/F"] : [])], {
+        stdio: "ignore", windowsHide: true, shell: false,
+      });
+      let fallbackUsed = false;
+      const fallback = () => {
+        if (fallbackUsed) return;
+        fallbackUsed = true;
+        try { child.kill(signal); }
+        catch { /* Callers that require proof wait for process settlement instead of trusting this best-effort fallback. */ }
+      };
+      killer?.once?.("error", fallback);
+      killer?.once?.("exit", (code) => { if (code !== 0) fallback(); });
+      killer?.unref?.();
+      return true;
+    } catch {
+      // Fall through to ChildProcess.kill for environments without taskkill.
+    }
+  }
+  const killProcess = typeof options.killProcess === "function" ? options.killProcess : process.kill.bind(process);
+  try { killProcess(-child.pid, signal); return true; }
+  catch {
+    try { return child.kill(signal) !== false; }
+    catch { return false; }
+  }
+}

package/src/local/process-tree-snapshot.mjs

@@ -0,0 +1,77 @@
+// @ts-check
+
+import { execFile } from "node:child_process";
+import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
+
+export const DEFAULT_PROCESS_OWNERSHIP_CHECK_BUDGET_MS = 3000;
+/** @typedef {import("./process-tree-ownership-types.d.ts").ProcessGroupEntry} ProcessGroupEntry */
+/** @typedef {import("./process-tree-ownership-types.d.ts").ProcessOwnershipOptions} ProcessOwnershipOptions */
+
+/** @param {number} groupId @param {ProcessOwnershipOptions} [options] @param {number} [pid] @param {number} [timeoutMs] */
+export async function processGroupMembers(groupId, options = {}, pid = 0, timeoutMs = snapshotTimeout(options)) {
+  const entries = typeof options.listProcessGroups === "function"
+    ? await options.listProcessGroups(options, pid, timeoutMs)
+    : await listProcessGroups(options, pid, timeoutMs, groupId);
+  return (Array.isArray(entries) ? entries : [])
+    .filter((entry) => entry.pgid === groupId)
+    .map(({ pid: memberPid, startedAt }) => ({ pid: memberPid, startedAt }));
+}
+
+/** @param {ProcessOwnershipOptions} [options] */
+export function createSnapshotBudget(options = {}) {
+  const total = boundedPositive(options.ownershipCheckBudgetMs, DEFAULT_PROCESS_OWNERSHIP_CHECK_BUDGET_MS);
+  const deadline = createMonotonicDeadline(total, options.monotonicNow);
+  let unallocated = total;
+  return {
+    /** @param {number} slots */
+    take(slots) {
+      const remaining = Math.min(unallocated, Math.floor(deadline.remainingMs()));
+      if (remaining < 1) return 0;
+      const value = Math.max(1, Math.min(DEFAULT_PROCESS_OWNERSHIP_CHECK_BUDGET_MS, Math.floor(remaining / Math.max(1, slots))));
+      unallocated -= value;
+      return value;
+    },
+  };
+}
+
+/** @param {ProcessOwnershipOptions} options @param {number} pid @param {number} timeoutMs @param {number} groupId */
+async function listProcessGroups(options, pid, timeoutMs, groupId) {
+  const run = typeof options.execFileProcess === "function" ? options.execFileProcess : defaultExecFileProcess;
+  const platform = String(options.platform || process.platform);
+  const args = pid ? ["-p", String(pid), "-o", "pid=,pgid=,lstart="]
+    : platform === "darwin" ? ["-g", String(groupId), "-o", "pid=,pgid=,lstart="] : ["-axo", "pid=,pgid=,lstart="];
+  const result = await run("ps", args, {
+    encoding: "utf8", timeout: timeoutMs, killSignal: "SIGKILL", maxBuffer: 512 * 1024,
+    windowsHide: true, env: { PATH: "/usr/bin:/bin", LC_ALL: "C", LANG: "C" },
+  });
+  if (result?.error || result?.status !== 0) return [];
+  return String(result.stdout || "").split(/\r?\n/).map(parseProcessRow).filter(isProcessGroupEntry);
+}
+
+/** @param {string} command @param {string[]} args @param {Record<string, any>} options */
+function defaultExecFileProcess(command, args, options) {
+  return new Promise((resolvePromise) => {
+    execFile(command, args, options, (error, stdout) => resolvePromise({ error, status: error ? 1 : 0, stdout }));
+  });
+}
+/** @param {ProcessOwnershipOptions} options */
+function snapshotTimeout(options) {
+  return boundedPositive(options.processSnapshotTimeoutMs, DEFAULT_PROCESS_OWNERSHIP_CHECK_BUDGET_MS);
+}
+/** @param {unknown} value @param {number} fallback */
+function boundedPositive(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 1 ? Math.min(DEFAULT_PROCESS_OWNERSHIP_CHECK_BUDGET_MS, Math.floor(parsed)) : fallback;
+}
+/** @param {unknown} line */
+function parseProcessRow(line) {
+  const match = /^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/.exec(String(line || ""));
+  if (!match) return null;
+  const pid = positivePid(match[1]);
+  const pgid = positivePid(match[2]);
+  const startedAt = Date.parse(match[3]);
+  return pid && pgid && Number.isFinite(startedAt) ? { pid, pgid, startedAt } : null;
+}
+function isProcessGroupEntry(/** @type {ProcessGroupEntry | null} */ value) { return value !== null; }
+/** @param {unknown} value */
+function positivePid(value) { const parsed = Number(value); return Number.isInteger(parsed) && parsed > 0 ? parsed : 0; }

package/src/local/process-tree-supervisor.mjs

@@ -0,0 +1,69 @@
+import {
+  captureProcessTreeOwnership,
+  processTreeOwnershipStillCurrent,
+  refreshProcessTreeOwnership,
+} from "./process-tree-ownership.mjs";
+import { terminateProcessTree } from "./process-tree-signal.mjs";
+import { createSnapshotBudget } from "./process-tree-snapshot.mjs";
+
+export const DEFAULT_PROCESS_TERMINATION_GRACE_MS = 2000;
+
+export function terminateProcessTreeWithEscalation(child, options = {}) {
+  const graceMs = Number.isFinite(Number(options.graceMs))
+    ? Math.max(0, Number(options.graceMs))
+    : DEFAULT_PROCESS_TERMINATION_GRACE_MS;
+  const schedule = typeof options.setTimeout === "function" ? options.setTimeout : setTimeout;
+  const terminate = typeof options.terminate === "function" ? options.terminate : terminateProcessTree;
+  const capture = typeof options.captureOwnership === "function"
+    ? options.captureOwnership : captureProcessTreeOwnership;
+  const refresh = typeof options.refreshOwnership === "function"
+    ? options.refreshOwnership : refreshProcessTreeOwnership;
+  const isOwned = typeof options.isTerminationTargetOwned === "function"
+    ? options.isTerminationTargetOwned : processTreeOwnershipStillCurrent;
+
+  const snapshotBudget = createSnapshotBudget(options);
+  let ownershipBeforeSignal;
+  try {
+    const captureOptions = boundedSnapshotOptions(snapshotBudget, options, 2);
+    ownershipBeforeSignal = captureOptions
+      ? Promise.resolve(capture(child, captureOptions)).catch(() => null)
+      : Promise.resolve(null);
+  } catch { ownershipBeforeSignal = Promise.resolve(null); }
+  try { terminate(child, "SIGTERM", options); }
+  catch { /* Ownership-checked forced escalation remains available after the grace period. */ }
+  const refreshedOwnership = ownershipBeforeSignal
+    .then((snapshot) => {
+      if (!snapshot) return null;
+      const refreshOptions = boundedSnapshotOptions(snapshotBudget, options, 1);
+      return refreshOptions ? refresh(snapshot, refreshOptions) : null;
+    })
+    .catch(() => null);
+
+  return schedule(() => superviseEscalation({
+    child, options, terminate, isOwned, refreshedOwnership,
+  }), graceMs);
+}
+
+async function superviseEscalation({ child, options, terminate, isOwned, refreshedOwnership }) {
+  try {
+    const ownership = await refreshedOwnership;
+    if (!ownership) return;
+    let owned = false;
+    try { owned = await isOwned(ownership, child, options); } catch { return; }
+    if (!owned) return;
+    try { terminate(child, "SIGKILL", options); } catch { return; }
+    try { options.onEscalated?.(); } catch { /* Observer failure must not suppress termination settlement. */ }
+  } finally {
+    try { options.onTerminationSettled?.(); } catch { /* Observer failure cannot change settled supervision. */ }
+  }
+}
+
+function boundedSnapshotOptions(budget, options, slots) {
+  const remainingMs = budget.take(slots);
+  if (!remainingMs) return null;
+  const configuredMs = Number(options.processSnapshotTimeoutMs);
+  const processSnapshotTimeoutMs = Number.isFinite(configuredMs) && configuredMs >= 1
+    ? Math.min(remainingMs, Math.floor(configuredMs))
+    : remainingMs;
+  return { ...options, processSnapshotTimeoutMs };
+}

package/src/local/process-tree.mjs

@@ -1,53 +1,11 @@
-import { spawn } from "node:child_process";
-
-export const DEFAULT_PROCESS_TERMINATION_GRACE_MS = 2000;
-
-export function terminateProcessTree(child, signal = "SIGTERM", options = {}) {
-  if (!child?.pid) return false;
-  const platform = options.platform || process.platform;
-  if (platform === "win32") {
-    try {
-      const spawnProcess = typeof options.spawnProcess === "function" ? options.spawnProcess : spawn;
-      const force = signal === "SIGKILL";
-      const killer = spawnProcess("taskkill.exe", ["/PID", String(child.pid), "/T", ...(force ? ["/F"] : [])], {
-        stdio: "ignore",
-        windowsHide: true,
-        shell: false,
-      });
-      const fallback = () => {
-        try { child.kill(signal); } catch {}
-      };
-      killer?.once?.("error", fallback);
-      killer?.once?.("exit", (code) => { if (code !== 0) fallback(); });
-      killer?.unref?.();
-      return true;
-    } catch {
-      // Fall through to ChildProcess.kill for environments without taskkill.
-    }
-  }
-
-  const killProcess = typeof options.killProcess === "function" ? options.killProcess : process.kill.bind(process);
-  try {
-    killProcess(-child.pid, signal);
-    return true;
-  } catch {
-    try {
-      return child.kill(signal) !== false;
-    } catch {
-      return false;
-    }
-  }
-}
-
-export function terminateProcessTreeWithEscalation(child, options = {}) {
-  const graceMs = Number.isFinite(Number(options.graceMs))
-    ? Math.max(0, Number(options.graceMs))
-    : DEFAULT_PROCESS_TERMINATION_GRACE_MS;
-  const schedule = typeof options.setTimeout === "function" ? options.setTimeout : setTimeout;
-  const terminate = typeof options.terminate === "function" ? options.terminate : terminateProcessTree;
-  terminate(child, "SIGTERM", options);
-  return schedule(() => {
-    terminate(child, "SIGKILL", options);
-    options.onEscalated?.();
-  }, graceMs);
-}
+export { terminateProcessTree } from "./process-tree-signal.mjs";
+export {
+  DEFAULT_PROCESS_TERMINATION_GRACE_MS,
+  terminateProcessTreeWithEscalation,
+} from "./process-tree-supervisor.mjs";
+export {
+  DEFAULT_PROCESS_OWNERSHIP_CHECK_BUDGET_MS,
+  captureProcessTreeOwnership,
+  processTreeOwnershipStillCurrent,
+  refreshProcessTreeOwnership,
+} from "./process-tree-ownership.mjs";

package/src/local/project-metadata.mjs

@@ -2,6 +2,7 @@
 
 import { constants as fsConstants } from "node:fs";
 import { lstat, open } from "node:fs/promises";
+import { filesystemIdentity, sameFilesystemIdentity } from "./filesystem-identity.mjs";
 
 const SKIPPABLE_METADATA_CODES = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM", "ELOOP", "EBUSY"]);
 
@@ -22,23 +23,35 @@ export async function isRegularNonSymlink(filePath) {
   return Boolean(info && !info.isSymbolicLink() && info.isFile());
 }
 
-/** @param {string} filePath @param {number} maxBytes */
-export async function readOptionalRegularUtf8(filePath, maxBytes) {
-  const handle = await open(filePath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0))
+/**
+ * @param {string} filePath
+ * @param {number} maxBytes
+ * @param {{openFile?: typeof open, inspectPath?: typeof lstat}} [options]
+ */
+export async function readOptionalRegularUtf8(filePath, maxBytes, options = {}) {
+  const limit = Number(maxBytes);
+  if (!Number.isSafeInteger(limit) || limit < 0) throw new TypeError("project metadata byte limit must be a non-negative safe integer");
+  const openFile = options.openFile || open;
+  const inspectPath = options.inspectPath || lstat;
+  const handle = await openFile(filePath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0), 0o600)
     .catch((error) => skippableMetadataError(error) ? null : Promise.reject(error));
   if (!handle) return null;
   try {
     let pathInfo;
     let current;
     try {
-      [pathInfo, current] = await Promise.all([lstat(filePath), handle.stat()]);
+      [pathInfo, current] = await Promise.all([
+        inspectPath(filePath, { bigint: true }),
+        handle.stat({ bigint: true }),
+      ]);
     } catch (error) {
       if (skippableMetadataError(error)) return null;
       throw error;
     }
     if (pathInfo.isSymbolicLink() || !pathInfo.isFile() || !current.isFile()
-        || pathInfo.dev !== current.dev || pathInfo.ino !== current.ino || current.size > maxBytes) return null;
-    const buffer = Buffer.alloc(current.size);
+        || !sameFilesystemIdentity(filesystemIdentity(pathInfo, "project metadata"), filesystemIdentity(current, "project metadata"))
+        || current.size > BigInt(limit)) return null;
+    const buffer = Buffer.alloc(Number(current.size));
     let offset = 0;
     while (offset < buffer.length) {
       const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);

package/src/local/relay-call-recovery.mjs

@@ -1,5 +1,7 @@
 // @ts-check
 
+import relayContract from "../shared/relay-contract.json" with { type: "json" };
+
 /** @typedef {{id?: unknown, [key: string]: unknown}} RelayResult */
 /** @typedef {{event?: (level: string, name: string, fields: Record<string, unknown>, message: string) => void, warn?: (message: string) => void}} RecoveryLogger */
 /** @typedef {{setTimeout: (callback: () => void, delay: number) => any, clearTimeout: (handle: any) => void}} RecoveryScheduler */
@@ -17,7 +19,7 @@
  * }} RelayCallRecoveryOptions
  */
 
-const DEFAULT_RECONNECT_GRACE_MS = 30_000;
+const DEFAULT_RECONNECT_GRACE_MS = relayContract.reconnectGraceMs;
 
 export class RelayCallRecovery {
   /** @param {RelayCallRecoveryOptions} [options] */
@@ -41,44 +43,56 @@ export class RelayCallRecovery {
   /** @param {RelayResult} response */
   deliver(response) {
     const callId = String(response?.id || "");
-    if (this.send(response)) {
-      if (callId) this.pendingResults.delete(callId);
-      return true;
-    }
-    if (callId && this.isRecoverable()) {
-      this.pendingResults.set(callId, response);
-      this.scheduleExpiry();
-      this.logger.event?.("debug", "relay.tool_result.queued", {
-        call_id: shortCallId(callId), queued_results: this.pendingResults.size,
-      }, "Queued a completed tool result while the relay reconnects");
+    if (!callId) return this.send(response);
+    if (!this.isRecoverable()) {
+      this.logger.event?.("debug", "relay.tool_result.discarded", {
+        call_id: shortCallId(callId), reason: "transport_unavailable",
+      }, "Discarded a tool result because the relay is no longer recoverable");
       return false;
     }
-    this.logger.event?.("debug", "relay.tool_result.discarded", {
-      call_id: shortCallId(callId), reason: "transport_unavailable",
-    }, "Discarded a tool result because the relay is no longer recoverable");
+
+    // Retain sent results until the Worker commits and acknowledges them.
+    this.pendingResults.set(callId, response);
+    const sent = this.send(response);
+    if (sent) {
+      this.logger.event?.("debug", "relay.tool_result.awaiting_ack", {
+        call_id: shortCallId(callId), unacknowledged_results: this.pendingResults.size,
+      }, "Delivered a tool result and retained it until Worker acknowledgement");
+      return true;
+    }
+
+    this.scheduleExpiry();
+    this.logger.event?.("debug", "relay.tool_result.queued", {
+      call_id: shortCallId(callId), queued_results: this.pendingResults.size,
+    }, "Queued a completed tool result while the relay reconnects");
     return false;
   }
 
   /** @param {unknown} callId */
-  discard(callId) {
-    return this.pendingResults.delete(String(callId));
-  }
+  acknowledge(callId) { return this.pendingResults.delete(String(callId)); }
+
+  /** @param {unknown} callId */
+  discard(callId) { return this.pendingResults.delete(String(callId)); }
+
+  ownedCallIds() { return [...new Set([...this.activeCallIds(), ...this.pendingResults.keys()])]; }
 
   /** @param {Iterable<string>} resumedCallIds @param {(callId: string) => boolean} cancelCall */
   reconcile(resumedCallIds, cancelCall) {
     const resumed = new Set(resumedCallIds);
-    let cancelled = 0;
-    let discarded = 0;
-    for (const callId of this.activeCallIds()) {
-      if (!resumed.has(callId) && cancelCall(callId)) cancelled += 1;
-    }
+    const active = [...this.activeCallIds()];
+    const locallyOwned = new Set(this.ownedCallIds());
+    const missing = [...resumed].filter((callId) => !locallyOwned.has(callId));
+    let cancelled = 0; let discarded = 0;
+    for (const callId of active) if (!resumed.has(callId) && cancelCall(callId)) cancelled += 1;
     for (const callId of [...this.pendingResults.keys()]) {
       if (!resumed.has(callId) && this.pendingResults.delete(callId)) discarded += 1;
     }
-    if (cancelled > 0 || discarded > 0) {
-      this.logger.event?.("debug", "relay.calls.reconciled", { cancelled_calls: cancelled, discarded_results: discarded },
-        "Cancelled relay work that no longer had a waiting client after reconnect");
-    }
+    if (cancelled > 0 || discarded > 0 || missing.length > 0) this.logger.event?.(
+      "debug", "relay.calls.reconciled",
+      { cancelled_calls: cancelled, discarded_results: discarded, missing_resumed_calls: missing.length },
+      "Reconciled local relay-call ownership against the Worker reconnect set",
+    );
+    return missing;
   }
 
   disconnected() {
@@ -90,20 +104,26 @@ export class RelayCallRecovery {
     }, "Keeping in-flight tool calls alive during a brief relay interruption");
   }
 
-  ready() {
-    this.clearTimer();
+  ready() { this.clearTimer(); this.retryUnacknowledged("reconnected"); }
+
+  pulse() { this.retryUnacknowledged("heartbeat"); }
+
+  /** @param {string} reason */
+  retryUnacknowledged(reason) {
     let delivered = 0;
-    for (const [callId, response] of [...this.pendingResults]) {
+    for (const response of this.pendingResults.values()) {
       if (!this.send(response)) {
         this.scheduleExpiry();
         break;
       }
-      this.pendingResults.delete(callId);
       delivered += 1;
     }
     if (delivered > 0) {
-      this.logger.event?.("info", "relay.tool_results.replayed", { delivered_results: delivered },
-        "Delivered completed tool results after the relay reconnected");
+      this.logger.event?.(reason === "reconnected" ? "info" : "debug", "relay.tool_results.redelivered", {
+        delivered_results: delivered,
+        reason,
+        unacknowledged_results: this.pendingResults.size,
+      }, "Redelivered completed tool results awaiting Worker acknowledgement");
     }
   }
 
@@ -120,9 +140,12 @@ export class RelayCallRecovery {
       const cancelled = this.cancelOrigin("remote relay reconnect grace expired");
       const discarded = this.pendingResults.size;
       this.pendingResults.clear();
-      this.terminate();
+      if (cancelled > 0) this.terminate();
       if (cancelled > 0 || discarded > 0) {
-        this.logger.warn?.(`remote relay did not recover within ${this.graceMs / 1000} seconds; cancelled ${cancelled} call(s) and discarded ${discarded} queued result(s)`);
+        const message = `remote relay did not recover within ${this.graceMs / 1000} seconds; cancelled ${cancelled} call(s) and discarded ${discarded} queued result(s)`;
+        this.logger.event
+          ? this.logger.event("warn", "relay.calls.reconnect_expired", { cancelled_calls: cancelled, discarded_results: discarded, grace_ms: this.graceMs }, message)
+          : this.logger.warn?.(message);
       }
     }, this.graceMs);
     this.reconnectTimer?.unref?.();
@@ -136,10 +159,7 @@ export class RelayCallRecovery {
 }
 
 /** @param {unknown} value @param {number} fallback */
-function positiveInteger(value, fallback) {
-  const number = Number(value);
-  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
-}
+function positiveInteger(value, fallback) { const number = Number(value); return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback; }
 
 /** @param {unknown} value */
 function shortCallId(value) {

package/src/local/relay-connection-classification.mjs

@@ -0,0 +1,131 @@
+const MAX_PROTOCOL_ERROR_CODE_CHARS = 64;
+
+export function relayServerErrorReconnectCategory(errorCode, state = {}) {
+  const code = sanitizeProtocolErrorCode(errorCode);
+  const authenticated = state?.authenticated === true;
+  const ready = state?.ready === true;
+  if (code === "daemon_hello_timeout" && !authenticated) return "relay_handshake_timeout";
+  if (code === "daemon_ready_timeout" && authenticated && !ready) return "relay_readiness_timeout";
+  if (code === "daemon_transport_error") return "relay_transport_error";
+  if (code === "daemon_liveness_timeout") return "relay_heartbeat_timeout";
+  return "";
+}
+
+export function relayCloseCategory(code, reason = "") {
+  const numeric = Number(code);
+  const reasonText = String(reason || "");
+  if (isSupersededClose(numeric, reasonText)) return "superseded";
+  if (numeric === 1008 && reasonText === "daemon hello timeout") return "relay_handshake_timeout";
+  if (numeric === 1008 && reasonText === "daemon ready timeout") return "relay_readiness_timeout";
+  if ([1008, 1012].includes(numeric) && ["daemon pong failed", "daemon send failed"].includes(reasonText)) return "relay_transport_error";
+  if ([1008, 1012].includes(numeric) && reasonText === "daemon liveness timeout") return "relay_heartbeat_timeout";
+  if (numeric === 1008 && ["stale daemon candidate", "expired daemon candidate"].includes(reasonText)) return "relay_restarting_or_unavailable";
+  if (numeric === 1008 && ["daemon hello required", "missing daemon attachment", "invalid daemon candidate timestamp"].includes(reasonText)) return "relay_protocol_error";
+  if (numeric === 1000) return "normal_close";
+  if (numeric === 1001 || numeric === 1012 || numeric === 1013) return "relay_restarting_or_unavailable";
+  if (numeric === 1006) return "connection_interrupted";
+  if (numeric === 1002) return "relay_protocol_error";
+  if (numeric === 1007) return "invalid_transport_payload";
+  if (numeric === 1008) return "relay_policy_rejected";
+  if (numeric === 1009) return "message_too_large";
+  if (numeric === 1011) return "relay_internal_error";
+  return "unexpected_close";
+}
+
+export function relayOutageUserAction(category, outageMs) {
+  if (Number(outageMs) < 5 * 60_000) return "";
+  if (String(category || "") === "local_authority_revocation_retry") {
+    return " If this persists, inspect local authority, process-session, and managed-job state; the retained revocation will retry automatically.";
+  }
+  return " If this persists, check internet access and the deployed Worker.";
+}
+
+export function relayFatalMessage(category) {
+  if (category === "relay_protocol_mismatch") {
+    return "remote relay identity or version does not match this daemon; upgrade and redeploy both components";
+  }
+  if (category === "relay_protocol_error") {
+    return "remote relay protocol error; upgrade and redeploy both components, then restart the daemon";
+  }
+  if (category === "relay_proxy_configuration") {
+    return "remote relay proxy configuration is invalid; check HTTP_PROXY, HTTPS_PROXY, and NO_PROXY";
+  }
+  return "remote relay rejected the daemon connection; verify credentials or redeploy the Worker";
+}
+
+export function relayCloseUserCause(category) {
+  const causes = {
+    connection_interrupted: "connection interrupted",
+    local_authority_revocation_retry: "local authority revocation requires retry",
+    relay_restarting_or_unavailable: "relay restarting or temporarily unavailable",
+    relay_policy_rejected: "relay rejected the connection",
+    relay_internal_error: "relay internal error",
+    relay_protocol_mismatch: "relay identity or version mismatch",
+    relay_authentication_failed: "relay authentication failed",
+    relay_connect_timeout: "relay connection attempt timed out",
+    relay_handshake_timeout: "relay authentication acknowledgement timed out",
+    relay_readiness_timeout: "end-to-end relay readiness verification timed out",
+    relay_heartbeat_timeout: "relay stopped responding",
+    relay_transport_timeout: "relay transport stopped responding",
+    relay_transport_error: "relay transport error",
+    relay_protocol_error: "relay protocol error",
+    relay_proxy_configuration: "relay proxy configuration invalid",
+    invalid_transport_payload: "invalid transport payload",
+    message_too_large: "message exceeded the relay limit",
+    normal_close: "connection closed",
+    unexpected_close: "unexpected connection close",
+    superseded: "connection superseded",
+  };
+  return causes[String(category || "")] || "connection interrupted";
+}
+
+export function welcomeMismatch(message, expectedServer = "", expectedVersion = "") {
+  if (!message || typeof message !== "object" || Array.isArray(message)) return "invalid_welcome";
+  if (message.type !== "welcome") return "unexpected_welcome_type";
+  if (expectedServer && message.server !== expectedServer) return "server_identity_mismatch";
+  if (expectedVersion && message.version !== expectedVersion) return "server_version_mismatch";
+  if (typeof message.server !== "string" || !message.server || typeof message.version !== "string" || !message.version) return "incomplete_welcome";
+  return "";
+}
+
+export function acknowledgementMismatch(message, expectedServer = "", expectedVersion = "") {
+  if (!message || typeof message !== "object" || Array.isArray(message)) return "invalid_acknowledgement";
+  if (message.type !== "hello_ack") return "unexpected_acknowledgement_type";
+  if (expectedServer && message.server !== expectedServer) return "server_identity_mismatch";
+  if (expectedVersion && message.version !== expectedVersion) return "server_version_mismatch";
+  if (typeof message.server !== "string" || !message.server || typeof message.version !== "string" || !message.version) return "incomplete_acknowledgement";
+  return "";
+}
+
+export function readinessMismatch(message, expectedServer = "", expectedVersion = "") {
+  if (!message || typeof message !== "object" || Array.isArray(message)) return "invalid_readiness_acknowledgement";
+  if (message.type !== "ready_ack") return "unexpected_readiness_acknowledgement_type";
+  if (expectedServer && message.server !== expectedServer) return "server_identity_mismatch";
+  if (expectedVersion && message.version !== expectedVersion) return "server_version_mismatch";
+  if (typeof message.server !== "string" || !message.server || typeof message.version !== "string" || !message.version) return "incomplete_readiness_acknowledgement";
+  return "";
+}
+
+export function isRelayReadyContext(relayContext = {}, relay = null) {
+  if (relayContext?.ready === true) return true;
+  if (relayContext?.ready === false) return false;
+  return Number(relayContext?.sessionId) > 0 && relay?.status?.()?.ready === true;
+}
+
+export function isSupersededClose(code, reason) {
+  return Number(code) === 1012 && String(reason || "") === "replaced by verified daemon";
+}
+
+export function reconnectDelay(attempt, random = Math.random, previousAttemptDurationMs = 0, connectTimeoutMs = 15_000) {
+  const safeAttempt = Math.max(0, Number.isFinite(Number(attempt)) ? Number(attempt) : 0);
+  const base = Math.min(1000 * (2 ** Math.min(safeAttempt, 4)), 15_000);
+  const spent = Math.max(0, Number(previousAttemptDurationMs) || 0);
+  const connectBudget = Math.max(1, Number(connectTimeoutMs) || 15_000);
+  const remaining = spent >= connectBudget * 0.8 ? Math.max(250, base - spent) : base;
+  return remaining + Math.floor((typeof random === "function" ? random() : Math.random()) * 500);
+}
+
+export function sanitizeProtocolErrorCode(value) {
+  const code = String(value || "unknown_error").replace(/[^A-Za-z0-9_-]/g, "_").slice(0, MAX_PROTOCOL_ERROR_CODE_CHARS);
+  return code || "unknown_error";
+}