@fml-inc/fml 0.7.0 → 0.8.0-rc.2

package/dist/chunk-WZLLO563.js

@@ -0,0 +1,953 @@
+import {
+  OBSERVER_SERVICE_NAME
+} from "./chunk-56TPYMNK.js";
+import {
+  FML_OBSERVER_LOCK_FILE,
+  FML_OBSERVER_PORT,
+  FML_OBSERVER_STATE_FILE
+} from "./chunk-A6HAEVJX.js";
+
+// src/observer/state.ts
+import { randomUUID } from "crypto";
+import { execFileSync } from "child_process";
+import fs from "fs";
+import path from "path";
+var OBSERVER_STATE_SCHEMA_VERSION = 1;
+var OBSERVER_HEARTBEAT_STALE_MS = 2 * 60 * 1e3;
+var OBSERVER_RECLAIM_GUARD_STALE_MS = 3e4;
+var OBSERVER_RECLAIM_GUARD_UNVERIFIED_TTL_MS = 5 * 6e4;
+var MAX_RECLAIM_GUARD_RECOVERIES = 2;
+var MAX_RECLAIM_GUARD_RACE_RETRIES = 16;
+var MAX_INITIAL_STATE_PUBLICATION_RETRIES = 2;
+var EXCLUSIVE_LINK_UNSUPPORTED_ERROR_CODES = /* @__PURE__ */ new Set([
+  "ENOSYS",
+  "ENOTSUP",
+  "EOPNOTSUPP",
+  "EPERM",
+  "EXDEV"
+]);
+var TRANSIENT_OBSERVER_FILE_ERROR_CODES = /* @__PURE__ */ new Set([
+  "EACCES",
+  "EAGAIN",
+  "EBUSY",
+  "EPERM"
+]);
+var reclaimProcessNonce = randomUUID();
+var activeReclaimGuardIds = /* @__PURE__ */ new Set();
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isObserverPhase(value) {
+  return value === "starting" || value === "syncing" || value === "idle" || value === "waiting_for_auth" || value === "backing_off" || value === "stopping";
+}
+function optionalNumber(record, key) {
+  const value = record[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function optionalString(record, key) {
+  const value = record[key];
+  return typeof value === "string" ? value : void 0;
+}
+function parseObserverState(value) {
+  if (!isRecord(value)) return null;
+  if (value.schemaVersion !== OBSERVER_STATE_SCHEMA_VERSION || value.service !== OBSERVER_SERVICE_NAME || typeof value.pid !== "number" || !Number.isInteger(value.pid) || value.pid <= 0 || typeof value.port !== "number" || !Number.isInteger(value.port) || value.port <= 0 || value.port > 65535 || typeof value.instanceId !== "string" || value.instanceId.length === 0 || typeof value.startedAtMs !== "number" || typeof value.heartbeatAtMs !== "number" || !isObserverPhase(value.phase)) {
+    return null;
+  }
+  return {
+    schemaVersion: OBSERVER_STATE_SCHEMA_VERSION,
+    service: OBSERVER_SERVICE_NAME,
+    pid: value.pid,
+    port: value.port,
+    instanceId: value.instanceId,
+    startedAtMs: value.startedAtMs,
+    heartbeatAtMs: value.heartbeatAtMs,
+    phase: value.phase,
+    processIdentity: optionalString(value, "processIdentity"),
+    environment: optionalString(value, "environment"),
+    lastAttemptAtMs: optionalNumber(value, "lastAttemptAtMs"),
+    lastSuccessAtMs: optionalNumber(value, "lastSuccessAtMs"),
+    nextAttemptAtMs: optionalNumber(value, "nextAttemptAtMs"),
+    lastOutcome: optionalString(value, "lastOutcome"),
+    lastError: optionalString(value, "lastError")
+  };
+}
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function readObserverState(stateFile = FML_OBSERVER_STATE_FILE) {
+  try {
+    return parseObserverState(
+      JSON.parse(fs.readFileSync(stateFile, "utf8"))
+    );
+  } catch {
+    return null;
+  }
+}
+function readObserverStateStatus(opts = {}) {
+  const stateFile = opts.stateFile ?? FML_OBSERVER_STATE_FILE;
+  const exists = fs.existsSync(stateFile);
+  const state = readObserverState(stateFile);
+  if (!state) {
+    return { exists, valid: false, running: false, responsive: false, state };
+  }
+  const running = (opts.pidAlive ?? isPidAlive)(state.pid);
+  return {
+    exists,
+    valid: true,
+    running,
+    responsive: running && (opts.nowMs ?? Date.now()) - state.heartbeatAtMs <= OBSERVER_HEARTBEAT_STALE_MS,
+    state
+  };
+}
+function createInitialObserverState(opts = {}) {
+  const nowMs = opts.nowMs ?? Date.now();
+  return {
+    schemaVersion: OBSERVER_STATE_SCHEMA_VERSION,
+    service: OBSERVER_SERVICE_NAME,
+    pid: process.pid,
+    port: opts.port ?? FML_OBSERVER_PORT,
+    instanceId: randomUUID(),
+    startedAtMs: nowMs,
+    heartbeatAtMs: nowMs,
+    phase: "starting",
+    processIdentity: getCurrentProcessIdentity() ?? void 0
+  };
+}
+function serializeState(state) {
+  return `${JSON.stringify(state, null, 2)}
+`;
+}
+var ObserverStateMutationBusyError = class extends Error {
+  constructor() {
+    super("observer lease mutation is already in progress");
+    this.name = "ObserverStateMutationBusyError";
+  }
+};
+function parseObserverLeaseOwner(value) {
+  try {
+    const parsed = JSON.parse(value);
+    return typeof parsed.pid === "number" && Number.isInteger(parsed.pid) && parsed.pid > 0 && typeof parsed.instanceId === "string" && parsed.instanceId.length > 0 ? { pid: parsed.pid, instanceId: parsed.instanceId } : null;
+  } catch {
+    return null;
+  }
+}
+function readObserverLeaseOwner(lockFile = FML_OBSERVER_LOCK_FILE) {
+  try {
+    return parseObserverLeaseOwner(fs.readFileSync(lockFile, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function inspectObserverFile(file) {
+  try {
+    return {
+      raw: fs.readFileSync(file, "utf8"),
+      exists: true,
+      busy: false
+    };
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { raw: null, exists: false, busy: false };
+    }
+    if (isTransientObserverFileError(error)) {
+      return { raw: null, exists: true, busy: true };
+    }
+    throw error;
+  }
+}
+function inspectObserverLease(opts = {}) {
+  const stateResult = inspectObserverFile(
+    opts.stateFile ?? FML_OBSERVER_STATE_FILE
+  );
+  const lockResult = inspectObserverFile(
+    opts.lockFile ?? FML_OBSERVER_LOCK_FILE
+  );
+  let state = null;
+  if (stateResult.raw !== null) {
+    try {
+      state = parseObserverState(JSON.parse(stateResult.raw));
+    } catch {
+      state = null;
+    }
+  }
+  return {
+    state,
+    owner: lockResult.raw === null ? null : parseObserverLeaseOwner(lockResult.raw),
+    stateExists: stateResult.exists,
+    lockExists: lockResult.exists,
+    stateBusy: stateResult.busy,
+    lockBusy: lockResult.busy,
+    busy: stateResult.busy || lockResult.busy
+  };
+}
+function observerLeaseIsOwned(instanceId, lockFile = FML_OBSERVER_LOCK_FILE) {
+  return readObserverLeaseOwner(lockFile)?.instanceId === instanceId;
+}
+function getProcessIdentity(pid) {
+  try {
+    if (process.platform === "linux") {
+      const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+      const fieldsAfterCommand = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+      const startTimeTicks = fieldsAfterCommand[19];
+      return startTimeTicks ? `linux:${startTimeTicks}` : null;
+    }
+    if (process.platform === "darwin") {
+      const startedAt = execFileSync(
+        "ps",
+        ["-p", String(pid), "-o", "lstart="],
+        {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+          timeout: 1e3
+        }
+      ).trim();
+      return startedAt ? `darwin:${startedAt}` : null;
+    }
+    if (process.platform === "win32") {
+      const startedAt = execFileSync(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          `(Get-Process -Id ${pid}).StartTime.ToUniversalTime().Ticks`
+        ],
+        {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+          timeout: 1e3
+        }
+      ).trim();
+      return startedAt ? `win32:${startedAt}` : null;
+    }
+  } catch {
+  }
+  return null;
+}
+var currentProcessIdentityCache;
+function getCurrentProcessIdentity() {
+  if (currentProcessIdentityCache === void 0) {
+    currentProcessIdentityCache = getProcessIdentity(process.pid);
+  }
+  return currentProcessIdentityCache;
+}
+function parseObserverReclaimGuardOwner(value) {
+  try {
+    const parsed = JSON.parse(value);
+    if (typeof parsed.pid !== "number" || !Number.isInteger(parsed.pid) || parsed.pid <= 0 || typeof parsed.instanceId !== "string" || parsed.instanceId.length === 0 || typeof parsed.guardId !== "string" || parsed.guardId.length === 0 || typeof parsed.createdAtMs !== "number" || parsed.processIdentity !== void 0 && typeof parsed.processIdentity !== "string" || parsed.processNonce !== void 0 && typeof parsed.processNonce !== "string") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function isTransientObserverFileError(error) {
+  const code = error?.code;
+  return code !== void 0 && TRANSIENT_OBSERVER_FILE_ERROR_CODES.has(code);
+}
+function readObserverMutationFile(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    if (isTransientObserverFileError(error)) {
+      throw new ObserverStateMutationBusyError();
+    }
+    throw error;
+  }
+}
+function readObserverStateForMutation(stateFile) {
+  const raw = readObserverMutationFile(stateFile);
+  if (raw === null) return null;
+  try {
+    return parseObserverState(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+function assertObserverStateMutationOwnership(instanceId, stateFile, lockFile, errorMessage) {
+  const leaseOwner = readObserverMutationFile(lockFile);
+  if (leaseOwner === null || parseObserverLeaseOwner(leaseOwner)?.instanceId !== instanceId) {
+    throw new Error(errorMessage);
+  }
+  if (readObserverStateForMutation(stateFile)?.instanceId !== instanceId) {
+    throw new Error(errorMessage);
+  }
+}
+function isRetryableReclaimGuardRace(error) {
+  return error.code === "ENOENT" || isTransientObserverFileError(error);
+}
+function removeReclaimTombstone(tombstone) {
+  try {
+    fs.rmSync(tombstone, { force: true });
+  } catch (error) {
+    if (!isRetryableReclaimGuardRace(error)) throw error;
+  }
+}
+function restoreDisplacedReclaimGuard(tombstone, reclaimFile, fallbackRaw) {
+  let canonicalReserved = false;
+  let tombstoneRestored = false;
+  let fallbackPublished = false;
+  try {
+    fs.linkSync(tombstone, reclaimFile);
+    canonicalReserved = true;
+    tombstoneRestored = true;
+  } catch (error) {
+    if (error.code === "EEXIST") {
+      canonicalReserved = true;
+    } else if (!isRetryableReclaimGuardRace(error)) {
+      throw error;
+    }
+  }
+  if (!canonicalReserved) {
+    try {
+      fs.copyFileSync(tombstone, reclaimFile, fs.constants.COPYFILE_EXCL);
+      canonicalReserved = true;
+      tombstoneRestored = true;
+    } catch (error) {
+      if (error.code === "EEXIST") {
+        canonicalReserved = true;
+      } else if (!isRetryableReclaimGuardRace(error)) {
+        throw error;
+      }
+    }
+  }
+  if (!canonicalReserved) {
+    let fd;
+    try {
+      fd = fs.openSync(reclaimFile, "wx", 384);
+      canonicalReserved = true;
+    } catch (error) {
+      if (error.code === "EEXIST") {
+        canonicalReserved = true;
+      } else if (isTransientObserverFileError(error)) {
+        return false;
+      } else {
+        throw error;
+      }
+      fd = -1;
+    }
+    if (fd >= 0) {
+      let publicationError;
+      try {
+        fs.writeFileSync(fd, fallbackRaw ?? "");
+      } catch (error) {
+        publicationError = error;
+      }
+      try {
+        fs.closeSync(fd);
+      } catch (error) {
+        if (publicationError === void 0 || !isTransientObserverFileError(error)) {
+          publicationError = error;
+        }
+      }
+      if (publicationError !== void 0 && !isTransientObserverFileError(publicationError)) {
+        throw publicationError;
+      }
+      fallbackPublished = publicationError === void 0 && fallbackRaw !== void 0;
+    }
+  }
+  if (canonicalReserved && (fallbackPublished || tombstoneRestored)) {
+    removeReclaimTombstone(tombstone);
+  }
+  return canonicalReserved;
+}
+function sameFileIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+function removeCreatedFileByIdentity(file, created) {
+  let observed;
+  try {
+    observed = fs.statSync(file);
+  } catch (error) {
+    if (!isRetryableReclaimGuardRace(error)) throw error;
+    return error.code === "ENOENT";
+  }
+  if (!sameFileIdentity(observed, created)) return true;
+  const tombstone = `${file}.failed-${process.pid}-${randomUUID()}`;
+  try {
+    fs.renameSync(file, tombstone);
+  } catch (error) {
+    if (!isRetryableReclaimGuardRace(error)) throw error;
+    return error.code === "ENOENT";
+  }
+  let displaced;
+  try {
+    displaced = fs.statSync(tombstone);
+  } catch (error) {
+    if (!isRetryableReclaimGuardRace(error)) throw error;
+    return restoreDisplacedReclaimGuard(tombstone, file);
+  }
+  let displacedRaw;
+  try {
+    displacedRaw = fs.readFileSync(tombstone, "utf8");
+  } catch (error) {
+    if (!isRetryableReclaimGuardRace(error)) throw error;
+  }
+  if (sameFileIdentity(displaced, created)) {
+    removeReclaimTombstone(tombstone);
+    return true;
+  }
+  return restoreDisplacedReclaimGuard(tombstone, file, displacedRaw);
+}
+function rewriteExclusiveFileBody(fd, contents) {
+  const body = Buffer.from(contents, "utf8");
+  fs.ftruncateSync(fd, 0);
+  let offset = 0;
+  while (offset < body.length) {
+    const written = fs.writeSync(
+      fd,
+      body,
+      offset,
+      body.length - offset,
+      offset
+    );
+    if (written === 0) {
+      throw Object.assign(
+        new Error("observer guard rewrite made no progress"),
+        {
+          code: "EBUSY"
+        }
+      );
+    }
+    offset += written;
+  }
+}
+function publishExclusiveLease(lockFile, serializedOwner) {
+  const stagingFile = `${lockFile}.${process.pid}.${randomUUID()}.tmp`;
+  let fd = null;
+  let staged = null;
+  let publicationError;
+  try {
+    fd = fs.openSync(stagingFile, "wx", 384);
+    fs.writeFileSync(fd, serializedOwner);
+    fs.fsyncSync(fd);
+    staged = fs.fstatSync(fd);
+    const stagedFd = fd;
+    fd = null;
+    fs.closeSync(stagedFd);
+    try {
+      fs.linkSync(stagingFile, lockFile);
+    } catch (error) {
+      if (error.code === "EEXIST") return null;
+      let linkedDespiteError = false;
+      try {
+        const published2 = fs.statSync(lockFile);
+        linkedDespiteError = sameFileIdentity(published2, staged) && fs.readFileSync(lockFile, "utf8") === serializedOwner;
+      } catch {
+      }
+      if (!linkedDespiteError) {
+        const code = error.code;
+        if (code !== void 0 && EXCLUSIVE_LINK_UNSUPPORTED_ERROR_CODES.has(code)) {
+          throw new Error(
+            `The filesystem containing ${lockFile} does not support atomic FML observer leases; choose an FML state or observer directory on a filesystem with hard-link support`,
+            { cause: error }
+          );
+        }
+        throw error;
+      }
+    }
+    const published = fs.statSync(lockFile);
+    if (fs.readFileSync(lockFile, "utf8") !== serializedOwner) {
+      try {
+        removeCreatedFileByIdentity(lockFile, published);
+      } catch {
+      }
+      throw new Error(`FML observer lease publication was incomplete`);
+    }
+    return published;
+  } catch (error) {
+    publicationError = error;
+    throw error;
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch (closeError) {
+        if (publicationError === void 0) throw closeError;
+      }
+    }
+    try {
+      fs.rmSync(stagingFile, { force: true });
+    } catch {
+    }
+  }
+}
+function ownsReclaimGuard(reclaimFile, guardId) {
+  try {
+    return parseObserverReclaimGuardOwner(fs.readFileSync(reclaimFile, "utf8"))?.guardId === guardId;
+  } catch {
+    return false;
+  }
+}
+function ownsReclaimGuardForMutation(reclaimFile, guardId) {
+  const raw = readObserverMutationFile(reclaimFile);
+  return raw !== null && parseObserverReclaimGuardOwner(raw)?.guardId === guardId;
+}
+function writeLeaseAndState(state, stateFile, lockFile, reclaimFile, reclaimGuardId) {
+  const serializedOwner = `${JSON.stringify({
+    pid: state.pid,
+    instanceId: state.instanceId
+  })}
+`;
+  const created = publishExclusiveLease(lockFile, serializedOwner);
+  if (!created) return false;
+  if (!ownsReclaimGuard(reclaimFile, reclaimGuardId) || !observerLeaseIsOwned(state.instanceId, lockFile)) {
+    removeCreatedFileByIdentity(lockFile, created);
+    return false;
+  }
+  try {
+    writeObserverState(state, stateFile);
+  } catch (error) {
+    try {
+      removeCreatedFileByIdentity(lockFile, created);
+    } catch {
+    }
+    throw error;
+  }
+  const coherent = ownsReclaimGuard(reclaimFile, reclaimGuardId) && observerLeaseIsOwned(state.instanceId, lockFile) && readObserverState(stateFile)?.instanceId === state.instanceId;
+  if (!coherent) {
+    try {
+      removeCreatedFileByIdentity(lockFile, created);
+    } catch {
+    }
+  }
+  return coherent;
+}
+function leaseCanBeReclaimed(opts) {
+  const owner = parseObserverLeaseOwner(opts.rawOwner);
+  if (!owner) {
+    if (opts.liveOwnerPolicy === "process_identity") {
+      return false;
+    }
+    return opts.nowMs - opts.lockMtimeMs >= OBSERVER_RECLAIM_GUARD_STALE_MS;
+  }
+  if (!opts.pidAlive(owner.pid)) return true;
+  const ownerState = readObserverState(opts.stateFile);
+  if (opts.liveOwnerPolicy === "process_identity") {
+    if (ownerState?.pid !== owner.pid || ownerState.instanceId !== owner.instanceId) {
+      return false;
+    }
+    if (ownerState.processIdentity === void 0) {
+      return false;
+    }
+    const currentIdentity = opts.processIdentity(owner.pid);
+    return currentIdentity !== null && currentIdentity !== ownerState.processIdentity;
+  }
+  if (ownerState?.pid === owner.pid && ownerState.instanceId === owner.instanceId) {
+    return opts.nowMs - ownerState.heartbeatAtMs > OBSERVER_HEARTBEAT_STALE_MS;
+  }
+  return opts.nowMs - opts.lockMtimeMs > OBSERVER_HEARTBEAT_STALE_MS;
+}
+function acquireReclaimGuard(owner, reclaimFile, nowMs, opts = {}) {
+  const guardId = randomUUID();
+  const processIdentity = opts.processIdentity ?? ((pid) => pid === process.pid ? getCurrentProcessIdentity() : getProcessIdentity(pid));
+  let recoveryAttempts = 0;
+  let raceRetries = 0;
+  while (recoveryAttempts < MAX_RECLAIM_GUARD_RECOVERIES && raceRetries <= MAX_RECLAIM_GUARD_RACE_RETRIES) {
+    try {
+      const fd = fs.openSync(reclaimFile, "wx", 384);
+      let created = null;
+      const serializedGuard = `${JSON.stringify({
+        pid: process.pid,
+        instanceId: owner.instanceId,
+        guardId,
+        createdAtMs: nowMs,
+        processIdentity: processIdentity(process.pid) ?? void 0,
+        processNonce: reclaimProcessNonce
+      })}
+`;
+      let publicationError;
+      let publicationFailed = false;
+      let cleanupBlocked = false;
+      try {
+        created = fs.fstatSync(fd);
+        fs.writeFileSync(fd, serializedGuard);
+      } catch (error) {
+        if (isTransientObserverFileError(error)) {
+          try {
+            rewriteExclusiveFileBody(fd, serializedGuard);
+          } catch (retryError) {
+            publicationFailed = true;
+            publicationError = retryError;
+          }
+        } else {
+          publicationFailed = true;
+          publicationError = error;
+        }
+        if (publicationFailed && created) {
+          try {
+            cleanupBlocked = !removeCreatedFileByIdentity(reclaimFile, created);
+          } catch (cleanupError) {
+            publicationError = cleanupError;
+          }
+        }
+      }
+      let displacedAfterPublication = false;
+      if (!publicationFailed) {
+        try {
+          displacedAfterPublication = parseObserverReclaimGuardOwner(fs.readFileSync(reclaimFile, "utf8"))?.guardId !== guardId;
+        } catch (error) {
+          if (error.code === "ENOENT") {
+            displacedAfterPublication = true;
+          } else {
+            publicationFailed = true;
+            publicationError = error;
+            if (isTransientObserverFileError(error) && created) {
+              try {
+                cleanupBlocked = !removeCreatedFileByIdentity(
+                  reclaimFile,
+                  created
+                );
+              } catch (cleanupError) {
+                publicationError = cleanupError;
+              }
+            }
+          }
+        }
+      }
+      try {
+        fs.closeSync(fd);
+      } catch (error) {
+        if (!publicationFailed) publicationError = error;
+        publicationFailed = true;
+      }
+      if (publicationFailed) {
+        if (cleanupBlocked) return null;
+        if (isTransientObserverFileError(publicationError)) {
+          if (ownsReclaimGuard(reclaimFile, guardId)) {
+            activeReclaimGuardIds.add(guardId);
+            return guardId;
+          }
+          raceRetries += 1;
+          continue;
+        }
+        throw publicationError;
+      }
+      if (displacedAfterPublication) return null;
+      activeReclaimGuardIds.add(guardId);
+      return guardId;
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        if (isTransientObserverFileError(error)) return null;
+        throw error;
+      }
+      let observedRaw;
+      let observed;
+      try {
+        observedRaw = fs.readFileSync(reclaimFile, "utf8");
+        observed = fs.statSync(reclaimFile);
+      } catch (readError) {
+        if (readError.code === "ENOENT") {
+          raceRetries += 1;
+          continue;
+        }
+        if (isTransientObserverFileError(readError)) return null;
+        throw readError;
+      }
+      const observedOwner = parseObserverReclaimGuardOwner(observedRaw);
+      if (observedOwner) {
+        const alive = (opts.pidAlive ?? isPidAlive)(observedOwner.pid);
+        const abandonedByThisProcess = observedOwner.processNonce === reclaimProcessNonce && !activeReclaimGuardIds.has(observedOwner.guardId);
+        if (alive && !abandonedByThisProcess) {
+          const currentIdentity = observedOwner.processIdentity === void 0 ? null : processIdentity(observedOwner.pid);
+          if (currentIdentity !== null && currentIdentity === observedOwner.processIdentity) {
+            return null;
+          }
+          if (currentIdentity === null && nowMs - observedOwner.createdAtMs < OBSERVER_RECLAIM_GUARD_UNVERIFIED_TTL_MS) {
+            return null;
+          }
+        }
+      } else if (nowMs - observed.mtimeMs < OBSERVER_RECLAIM_GUARD_STALE_MS) {
+        return null;
+      }
+      const tombstone = `${reclaimFile}.stale-${process.pid}-${randomUUID()}`;
+      try {
+        fs.renameSync(reclaimFile, tombstone);
+      } catch (renameError) {
+        if (renameError.code === "ENOENT") {
+          raceRetries += 1;
+          continue;
+        }
+        if (isTransientObserverFileError(renameError)) return null;
+        throw renameError;
+      }
+      recoveryAttempts += 1;
+      let displacedRaw;
+      try {
+        displacedRaw = fs.readFileSync(tombstone, "utf8");
+      } catch (error2) {
+        if (!isRetryableReclaimGuardRace(error2)) throw error2;
+        restoreDisplacedReclaimGuard(tombstone, reclaimFile, observedRaw);
+        return null;
+      }
+      let displaced;
+      try {
+        displaced = fs.statSync(tombstone);
+      } catch (error2) {
+        if (!isRetryableReclaimGuardRace(error2)) throw error2;
+        restoreDisplacedReclaimGuard(tombstone, reclaimFile, displacedRaw);
+        return null;
+      }
+      if (displacedRaw !== observedRaw || displaced.dev !== observed.dev || displaced.ino !== observed.ino || displaced.mtimeMs !== observed.mtimeMs || !observedOwner && nowMs - displaced.mtimeMs < OBSERVER_RECLAIM_GUARD_STALE_MS) {
+        restoreDisplacedReclaimGuard(tombstone, reclaimFile, displacedRaw);
+        return null;
+      }
+      removeReclaimTombstone(tombstone);
+    }
+  }
+  return null;
+}
+function releaseReclaimGuard(reclaimFile, guardId) {
+  try {
+    let observedRaw;
+    let observed;
+    try {
+      observedRaw = fs.readFileSync(reclaimFile, "utf8");
+      observed = fs.statSync(reclaimFile);
+    } catch (error) {
+      if (error.code === "ENOENT" || isTransientObserverFileError(error)) {
+        return;
+      }
+      throw error;
+    }
+    if (parseObserverReclaimGuardOwner(observedRaw)?.guardId !== guardId) {
+      return;
+    }
+    const tombstone = `${reclaimFile}.release-${process.pid}-${randomUUID()}`;
+    fs.renameSync(reclaimFile, tombstone);
+    let displacedRaw;
+    try {
+      displacedRaw = fs.readFileSync(tombstone, "utf8");
+    } catch (error) {
+      if (!isRetryableReclaimGuardRace(error)) throw error;
+      restoreDisplacedReclaimGuard(tombstone, reclaimFile, observedRaw);
+      return;
+    }
+    let displaced;
+    try {
+      displaced = fs.statSync(tombstone);
+    } catch (error) {
+      if (!isRetryableReclaimGuardRace(error)) throw error;
+      restoreDisplacedReclaimGuard(tombstone, reclaimFile, displacedRaw);
+      return;
+    }
+    if (displacedRaw !== observedRaw || displaced.dev !== observed.dev || displaced.ino !== observed.ino || displaced.mtimeMs !== observed.mtimeMs) {
+      restoreDisplacedReclaimGuard(tombstone, reclaimFile, displacedRaw);
+      return;
+    }
+    removeReclaimTombstone(tombstone);
+  } catch (error) {
+    if (error.code !== "ENOENT" && !isTransientObserverFileError(error)) {
+      throw error;
+    }
+  } finally {
+    activeReclaimGuardIds.delete(guardId);
+  }
+}
+function claimObserverState(state, opts = {}) {
+  const stateFile = opts.stateFile ?? FML_OBSERVER_STATE_FILE;
+  const lockFile = opts.lockFile ?? FML_OBSERVER_LOCK_FILE;
+  fs.mkdirSync(path.dirname(lockFile), { recursive: true, mode: 448 });
+  const nowMs = opts.nowMs ?? Date.now();
+  const reclaimFile = `${lockFile}.reclaim`;
+  let initialPublicationRetries = 0;
+  while (!fs.existsSync(lockFile)) {
+    const initialGuardId = acquireReclaimGuard(state, reclaimFile, nowMs, {
+      pidAlive: opts.pidAlive,
+      processIdentity: opts.processIdentity
+    });
+    if (!initialGuardId) return false;
+    let retryPublication = false;
+    try {
+      try {
+        if (writeLeaseAndState(
+          state,
+          stateFile,
+          lockFile,
+          reclaimFile,
+          initialGuardId
+        )) {
+          return true;
+        }
+      } catch (error) {
+        if (!isTransientObserverFileError(error) || initialPublicationRetries >= MAX_INITIAL_STATE_PUBLICATION_RETRIES) {
+          throw error;
+        }
+        initialPublicationRetries += 1;
+        retryPublication = true;
+      }
+    } finally {
+      releaseReclaimGuard(reclaimFile, initialGuardId);
+    }
+    if (!retryPublication) break;
+  }
+  let observedRaw;
+  let observedStat;
+  try {
+    observedRaw = fs.readFileSync(lockFile, "utf8");
+    observedStat = fs.statSync(lockFile);
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+  const reclaimable = leaseCanBeReclaimed({
+    rawOwner: observedRaw,
+    lockMtimeMs: observedStat.mtimeMs,
+    stateFile,
+    nowMs,
+    pidAlive: opts.pidAlive ?? isPidAlive,
+    processIdentity: opts.processIdentity ?? getProcessIdentity,
+    liveOwnerPolicy: opts.liveOwnerPolicy ?? "heartbeat"
+  });
+  if (!reclaimable) return false;
+  const reclaimGuardId = acquireReclaimGuard(state, reclaimFile, nowMs, {
+    pidAlive: opts.pidAlive,
+    processIdentity: opts.processIdentity
+  });
+  if (!reclaimGuardId) return false;
+  try {
+    const currentRaw = fs.readFileSync(lockFile, "utf8");
+    const currentStat = fs.statSync(lockFile);
+    if (!ownsReclaimGuard(reclaimFile, reclaimGuardId) || currentRaw !== observedRaw || currentStat.dev !== observedStat.dev || currentStat.ino !== observedStat.ino || currentStat.mtimeMs !== observedStat.mtimeMs || !leaseCanBeReclaimed({
+      rawOwner: currentRaw,
+      lockMtimeMs: currentStat.mtimeMs,
+      stateFile,
+      nowMs,
+      pidAlive: opts.pidAlive ?? isPidAlive,
+      processIdentity: opts.processIdentity ?? getProcessIdentity,
+      liveOwnerPolicy: opts.liveOwnerPolicy ?? "heartbeat"
+    })) {
+      return false;
+    }
+    fs.unlinkSync(lockFile);
+    return writeLeaseAndState(
+      state,
+      stateFile,
+      lockFile,
+      reclaimFile,
+      reclaimGuardId
+    );
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  } finally {
+    releaseReclaimGuard(reclaimFile, reclaimGuardId);
+  }
+}
+function writeObserverState(state, stateFile = FML_OBSERVER_STATE_FILE) {
+  fs.mkdirSync(path.dirname(stateFile), { recursive: true, mode: 448 });
+  const tempFile = `${stateFile}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(tempFile, serializeState(state), { mode: 384 });
+    fs.renameSync(tempFile, stateFile);
+  } catch (error) {
+    try {
+      fs.rmSync(tempFile, { force: true });
+    } catch {
+    }
+    throw error;
+  }
+  try {
+    fs.chmodSync(stateFile, 384);
+  } catch {
+  }
+}
+function updateObserverState(state, update, stateFile = FML_OBSERVER_STATE_FILE, lockFile = FML_OBSERVER_LOCK_FILE) {
+  const reclaimFile = `${lockFile}.reclaim`;
+  const reclaimGuardId = acquireReclaimGuard(state, reclaimFile, Date.now());
+  if (!reclaimGuardId) {
+    assertObserverStateMutationOwnership(
+      state.instanceId,
+      stateFile,
+      lockFile,
+      "observer lease ownership was lost"
+    );
+    throw new ObserverStateMutationBusyError();
+  }
+  try {
+    assertObserverStateMutationOwnership(
+      state.instanceId,
+      stateFile,
+      lockFile,
+      "observer lease ownership was lost"
+    );
+    if (!ownsReclaimGuardForMutation(reclaimFile, reclaimGuardId)) {
+      throw new ObserverStateMutationBusyError();
+    }
+    const next = { ...state, ...update };
+    try {
+      writeObserverState(next, stateFile);
+    } catch (error) {
+      if (isTransientObserverFileError(error)) {
+        assertObserverStateMutationOwnership(
+          state.instanceId,
+          stateFile,
+          lockFile,
+          "observer lease ownership was lost during state update"
+        );
+        if (!ownsReclaimGuardForMutation(reclaimFile, reclaimGuardId)) {
+          throw new ObserverStateMutationBusyError();
+        }
+        throw new ObserverStateMutationBusyError();
+      }
+      throw error;
+    }
+    assertObserverStateMutationOwnership(
+      state.instanceId,
+      stateFile,
+      lockFile,
+      "observer lease ownership was lost during state update"
+    );
+    if (!ownsReclaimGuardForMutation(reclaimFile, reclaimGuardId)) {
+      throw new ObserverStateMutationBusyError();
+    }
+    return next;
+  } finally {
+    releaseReclaimGuard(reclaimFile, reclaimGuardId);
+  }
+}
+function removeObserverStateIfOwned(instanceId, opts = {}) {
+  const stateFile = opts.stateFile ?? FML_OBSERVER_STATE_FILE;
+  const lockFile = opts.lockFile ?? FML_OBSERVER_LOCK_FILE;
+  const reclaimFile = `${lockFile}.reclaim`;
+  const reclaimGuardId = acquireReclaimGuard(
+    { pid: process.pid, instanceId },
+    reclaimFile,
+    Date.now()
+  );
+  if (!reclaimGuardId) {
+    return;
+  }
+  try {
+    if (!ownsReclaimGuard(reclaimFile, reclaimGuardId) || !observerLeaseIsOwned(instanceId, lockFile) || readObserverState(stateFile)?.instanceId !== instanceId) {
+      return;
+    }
+    fs.rmSync(stateFile, { force: true });
+    if (ownsReclaimGuard(reclaimFile, reclaimGuardId) && observerLeaseIsOwned(instanceId, lockFile)) {
+      fs.rmSync(lockFile, { force: true });
+    }
+  } finally {
+    releaseReclaimGuard(reclaimFile, reclaimGuardId);
+  }
+}
+
+export {
+  OBSERVER_HEARTBEAT_STALE_MS,
+  isPidAlive,
+  readObserverStateStatus,
+  createInitialObserverState,
+  ObserverStateMutationBusyError,
+  inspectObserverLease,
+  observerLeaseIsOwned,
+  getProcessIdentity,
+  claimObserverState,
+  updateObserverState,
+  removeObserverStateIfOwned
+};