stitchkit 0.94.0 → 0.94.1

package/dist/{index-cq4qfycf.js → index-79z7m7dt.js}

@@ -3,6 +3,7 @@ import { z } from "zod";
 var DURABILITY_STEP_EVENT_KIND = "durability/step";
 var DURABILITY_PARK_EVENT_KIND = "durability/park";
 var DURABILITY_EVENT_EVENT_KIND = "durability/event";
+var DURABILITY_EFFECT_EVENT_KIND = "durability/effect";
 var StepEventPayloadSchema = z.object({
   runId: z.string().min(1),
   stepName: z.string().min(1),
@@ -30,6 +31,17 @@ var DeliveredEventPayloadSchema = z.object({
   id: z.string().min(1),
   encoded: z.string()
 });
+var EffectIdentity = { runId: z.string().min(1), effectName: z.string().min(1) };
+var EffectEventPayloadSchema = z.discriminatedUnion("phase", [
+  z.object({ ...EffectIdentity, phase: z.literal("intent") }),
+  z.object({
+    ...EffectIdentity,
+    phase: z.literal("accepted"),
+    encoded: z.string(),
+    via: z.enum(["run", "reconcile"])
+  }),
+  z.object({ ...EffectIdentity, phase: z.literal("uncertain") })
+]);
 
 class StepResultDecodeError extends Error {
   constructor(message, options) {
@@ -54,6 +66,17 @@ class StepAbortedError extends Error {
   }
 }
 
+class EffectUnresolvedError extends Error {
+  effectName;
+  reason;
+  constructor(effectName, reason, options) {
+    super(`Effect "${effectName}" is unresolved (${reason}); its intent stands`, options);
+    this.effectName = effectName;
+    this.reason = reason;
+    this.name = "EffectUnresolvedError";
+  }
+}
+
 class ParkRecordDecodeError extends Error {
   constructor(message, options) {
     super(message, options);
@@ -113,6 +136,9 @@ var DurableJsonSchema = z2.custom((value) => losslessJson(value), "Expected loss
 function stepKey(conversationId, runId, stepName) {
   return JSON.stringify([conversationId, runId, stepName]);
 }
+function effectKey(conversationId, runId, effectName) {
+  return JSON.stringify([conversationId, runId, "effect", effectName]);
+}
 function sleepParkKey(conversationId, runId, name) {
   return JSON.stringify([conversationId, runId, "sleep", name]);
 }
@@ -183,8 +209,25 @@ function decodeDeliveredResult(payload, event) {
     throw new ParkRecordDecodeError(`Delivered payload for "${payload.event}#${payload.id}" (run ${payload.runId}, ` + `event ${event.eventId}) is not decodable JSON`, { cause });
   }
 }
+function decodeEffect(event) {
+  const parsed = EffectEventPayloadSchema.safeParse(event.payload);
+  if (!parsed.success) {
+    throw new StepResultDecodeError(`Recorded effect event ${event.eventId} in conversation ${event.conversationId} is malformed`, { cause: parsed.error });
+  }
+  const payload = parsed.data;
+  if (payload.phase === "intent")
+    return { payload, record: { outcome: undefined } };
+  if (payload.phase === "uncertain")
+    return { payload, record: { outcome: "uncertain" } };
+  try {
+    const proof = DurableJsonSchema.parse(JSON.parse(payload.encoded));
+    return { payload, record: { outcome: "accepted", proof } };
+  } catch (cause) {
+    throw new StepResultDecodeError(`Recorded proof for effect "${payload.effectName}" (run ${payload.runId}, ` + `event ${event.eventId}) is not decodable JSON`, { cause });
+  }
+}
 async function readDurabilityLedger(store, conversationId, view) {
-  const { steps, parks, deliveries } = view;
+  const { steps, effects, parks, deliveries } = view;
   let fromSeq = view.nextSeq;
   for (;; ) {
     const page = await store.readEvents({
@@ -199,6 +242,11 @@ async function readDurabilityLedger(store, conversationId, view) {
       } else if (event.kind === DURABILITY_PARK_EVENT_KIND) {
         const payload = decodeParkPayload(event);
         parks.set(parkEventKey(event.conversationId, payload), payload);
+      } else if (event.kind === DURABILITY_EFFECT_EVENT_KIND) {
+        const { payload, record } = decodeEffect(event);
+        const key = effectKey(event.conversationId, payload.runId, payload.effectName);
+        if (effects.get(key)?.outcome === undefined)
+          effects.set(key, record);
       } else if (event.kind === DURABILITY_EVENT_EVENT_KIND) {
         const payload = decodeDeliveredPayload(event);
         const key = waitParkKey(event.conversationId, payload.runId, payload.event, payload.id);
@@ -216,6 +264,95 @@ async function readDurabilityLedger(store, conversationId, view) {
   return view;
 }
 
+// src/durability/effect.ts
+var DEFAULT_RECONCILE_TIMEOUT_MS = 30000;
+var MAX_PROOF_BYTES = 64 * 1024;
+function encodeProof(name, proof) {
+  let encoded;
+  try {
+    encoded = encodeStepResult(name, proof);
+  } catch (cause) {
+    throw new EffectUnresolvedError(name, "proof-rejected", { cause });
+  }
+  const bytes = new TextEncoder().encode(encoded).byteLength;
+  if (bytes > MAX_PROOF_BYTES) {
+    throw new EffectUnresolvedError(name, "proof-rejected", {
+      cause: new RangeError(`the proof is ${bytes} bytes; at most ${MAX_PROOF_BYTES} are kept`)
+    });
+  }
+  return encoded;
+}
+function outcomeOf(encoded) {
+  return { outcome: "accepted", proof: JSON.parse(encoded) };
+}
+async function append(context, payload, name) {
+  await context.store.appendEvent({
+    conversationId: context.conversationId,
+    kind: DURABILITY_EFFECT_EVENT_KIND,
+    payload: { runId: context.runId, effectName: name, ...payload }
+  });
+}
+async function reconcile(context, name, handlers, timeoutMs) {
+  const controller = new AbortController;
+  let timer;
+  const deadline = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort(new Error(`reconcile did not finish within ${timeoutMs} ms`));
+      resolve("timeout");
+    }, timeoutMs);
+  });
+  let found;
+  try {
+    found = await Promise.race([
+      Promise.resolve().then(() => handlers.reconcile(controller.signal)),
+      deadline
+    ]);
+  } catch (cause) {
+    throw new EffectUnresolvedError(name, "reconcile-failed", { cause });
+  } finally {
+    clearTimeout(timer);
+  }
+  if (found === "timeout") {
+    throw new EffectUnresolvedError(name, "reconcile-timeout", {
+      cause: controller.signal.reason
+    });
+  }
+  if (found === null) {
+    await append(context, { phase: "uncertain" }, name);
+    return { outcome: "uncertain" };
+  }
+  const encoded = encodeProof(name, found);
+  await append(context, { phase: "accepted", encoded, via: "reconcile" }, name);
+  return outcomeOf(encoded);
+}
+async function executeEffect(context, name, handlers, options) {
+  const timeoutMs = options?.reconcileTimeoutMs ?? DEFAULT_RECONCILE_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new TypeError(`reconcileTimeoutMs must be a positive finite number, got ${timeoutMs}`);
+  }
+  const key = effectKey(context.conversationId, context.runId, name);
+  const recorded = (await context.readLedger()).effects.get(key);
+  if (recorded?.outcome === "uncertain")
+    return { outcome: "uncertain" };
+  if (recorded?.outcome === "accepted") {
+    return outcomeOf(JSON.stringify(recorded.proof));
+  }
+  if (options?.signal?.aborted || context.signal?.aborted)
+    throw new StepAbortedError(name);
+  if (recorded)
+    return reconcile(context, name, handlers, timeoutMs);
+  await append(context, { phase: "intent" }, name);
+  let proof;
+  try {
+    proof = await handlers.run();
+  } catch (cause) {
+    throw new EffectUnresolvedError(name, "run-failed", { cause });
+  }
+  const encoded = encodeProof(name, proof);
+  await append(context, { phase: "accepted", encoded, via: "run" }, name);
+  return outcomeOf(encoded);
+}
+
 // src/durability/scheduler.ts
 var systemClock = {
   now: () => Date.now(),
@@ -300,6 +437,64 @@ function createParkWaiter(parkWaiters, key, signal) {
   return { outcome, cancel: cleanup };
 }
 
+// src/durability/parks.ts
+async function executeSleep(park, name, seconds, runOptions) {
+  const key = sleepParkKey(park.conversationId, park.runId, name);
+  const signal = park.signal && runOptions?.signal ? AbortSignal.any([park.signal, runOptions.signal]) : runOptions?.signal ?? park.signal;
+  const ledger = await park.readLedger();
+  const existing = ledger.parks.get(key);
+  let deadline;
+  if (existing) {
+    if (existing.kind !== "sleep") {
+      throw new ParkRecordDecodeError(`Recorded park "${name}" is not a sleep record`);
+    }
+    deadline = existing.deadline;
+  } else {
+    deadline = park.clock.now() + seconds * 1000;
+    if (!Number.isSafeInteger(Math.ceil(deadline)))
+      throw new TypeError("Sleep deadline exceeds the supported clock range");
+    await park.store.appendEvent({
+      conversationId: park.conversationId,
+      kind: DURABILITY_PARK_EVENT_KIND,
+      payload: { runId: park.runId, kind: "sleep", name, deadline }
+    });
+  }
+  if (signal?.aborted)
+    throw new ParkAbortedError(name);
+  await waitForDeadline(park.clock, deadline, name, signal);
+}
+async function executeWait(park, eventName, id, runOptions) {
+  const key = waitParkKey(park.conversationId, park.runId, eventName, id);
+  const label = `${eventName}#${id}`;
+  const signal = park.signal && runOptions?.signal ? AbortSignal.any([park.signal, runOptions.signal]) : runOptions?.signal ?? park.signal;
+  for (;; ) {
+    if (signal?.aborted)
+      throw new ParkAbortedError(label);
+    const waiter = createParkWaiter(park.waiters, key, signal);
+    let unsubscribe;
+    try {
+      unsubscribe = park.subscribe?.(() => notifyWaiters(park.waiters, key));
+      const ledger = await park.readLedger();
+      if (ledger.deliveries.has(key)) {
+        return JSON.parse(JSON.stringify(ledger.deliveries.get(key)));
+      }
+      if (!ledger.parks.has(key)) {
+        await park.store.appendEvent({
+          conversationId: park.conversationId,
+          kind: DURABILITY_PARK_EVENT_KIND,
+          payload: { runId: park.runId, kind: "wait", event: eventName, id }
+        });
+      }
+      const outcome = await waiter.outcome;
+      if (outcome === "aborted")
+        throw new ParkAbortedError(label);
+    } finally {
+      waiter.cancel();
+      unsubscribe?.();
+    }
+  }
+}
+
 // src/durability/engine.ts
 function releaseSettled(registry, key, pending) {
   const release = () => {
@@ -315,14 +510,21 @@ function createLocalStepDurability(options) {
   const { store, conversationId, runId } = options;
   const inFlight = stores.get(store) ?? {
     steps: new Map,
+    effects: new Map,
     parks: new Map,
     waiters: new Map
   };
   stores.set(store, inFlight);
-  const { steps: inFlightSteps, parks: inFlightParks, waiters: parkWaiters } = inFlight;
+  const {
+    steps: inFlightSteps,
+    effects: inFlightEffects,
+    parks: inFlightParks,
+    waiters: parkWaiters
+  } = inFlight;
   const clock = options.clock ?? systemClock;
   const view = {
     steps: new Map,
+    effects: new Map,
     parks: new Map,
     deliveries: new Map,
     nextSeq: 1
@@ -332,6 +534,16 @@ function createLocalStepDurability(options) {
     reading = reading.catch(() => view).then(() => readDurabilityLedger(store, conversationId, view));
     return reading;
   };
+  const park = {
+    store,
+    conversationId,
+    runId,
+    signal: options.signal,
+    subscribe: options.subscribe,
+    clock,
+    waiters: parkWaiters,
+    readLedger
+  };
   const readRecordedStep = async (name) => {
     const key = stepKey(conversationId, runId, name);
     const records = await readLedger();
@@ -365,30 +577,16 @@ function createLocalStepDurability(options) {
     releaseSettled(inFlightSteps, key, pending);
     return detachedResult(pending);
   };
-  const executeSleep = async (name, seconds, runOptions) => {
-    const key = sleepParkKey(conversationId, runId, name);
-    const signal = options.signal && runOptions?.signal ? AbortSignal.any([options.signal, runOptions.signal]) : runOptions?.signal ?? options.signal;
-    const ledger = await readLedger();
-    const existing = ledger.parks.get(key);
-    let deadline;
+  const effect = (name, handlers, runOptions) => {
+    const key = effectKey(conversationId, runId, name);
+    const existing = inFlightEffects.get(key);
     if (existing) {
-      if (existing.kind !== "sleep") {
-        throw new ParkRecordDecodeError(`Recorded park "${name}" is not a sleep record`);
-      }
-      deadline = existing.deadline;
-    } else {
-      deadline = clock.now() + seconds * 1000;
-      if (!Number.isSafeInteger(Math.ceil(deadline)))
-        throw new TypeError("Sleep deadline exceeds the supported clock range");
-      await store.appendEvent({
-        conversationId,
-        kind: DURABILITY_PARK_EVENT_KIND,
-        payload: { runId, kind: "sleep", name, deadline }
-      });
+      return detachedResult(existing);
     }
-    if (signal?.aborted)
-      throw new ParkAbortedError(name);
-    await waitForDeadline(clock, deadline, name, signal);
+    const pending = executeEffect({ store, conversationId, runId, signal: options.signal, readLedger }, name, handlers, runOptions);
+    inFlightEffects.set(key, pending);
+    releaseSettled(inFlightEffects, key, pending);
+    return detachedResult(pending);
   };
   const sleep = (input, runOptions) => {
     const { seconds } = input;
@@ -401,49 +599,18 @@ function createLocalStepDurability(options) {
     if (existing) {
       return existing;
     }
-    const pending = executeSleep(name, seconds, runOptions);
+    const pending = executeSleep(park, name, seconds, runOptions);
     inFlightParks.set(key, pending);
     releaseSettled(inFlightParks, key, pending);
     return pending;
   };
-  const executeWait = async (eventName, id, runOptions) => {
-    const key = waitParkKey(conversationId, runId, eventName, id);
-    const park = `${eventName}#${id}`;
-    const signal = options.signal && runOptions?.signal ? AbortSignal.any([options.signal, runOptions.signal]) : runOptions?.signal ?? options.signal;
-    for (;; ) {
-      if (signal?.aborted)
-        throw new ParkAbortedError(park);
-      const waiter = createParkWaiter(parkWaiters, key, signal);
-      let unsubscribe;
-      try {
-        unsubscribe = options.subscribe?.(() => notifyWaiters(parkWaiters, key));
-        const ledger = await readLedger();
-        if (ledger.deliveries.has(key)) {
-          return JSON.parse(JSON.stringify(ledger.deliveries.get(key)));
-        }
-        if (!ledger.parks.has(key)) {
-          await store.appendEvent({
-            conversationId,
-            kind: DURABILITY_PARK_EVENT_KIND,
-            payload: { runId, kind: "wait", event: eventName, id }
-          });
-        }
-        const outcome = await waiter.outcome;
-        if (outcome === "aborted")
-          throw new ParkAbortedError(park);
-      } finally {
-        waiter.cancel();
-        unsubscribe?.();
-      }
-    }
-  };
   const waitFor = (input, runOptions) => {
     const key = waitParkKey(conversationId, runId, input.event, input.id);
     const existing = inFlightParks.get(key);
     if (existing) {
       return detachedResult(existing);
     }
-    const pending = executeWait(input.event, input.id, runOptions);
+    const pending = executeWait(park, input.event, input.id, runOptions);
     inFlightParks.set(key, pending);
     releaseSettled(inFlightParks, key, pending);
     return detachedResult(pending);
@@ -467,7 +634,8 @@ function createLocalStepDurability(options) {
     hasRecordedStep: async (name) => await readRecordedStep(name) !== undefined,
     sleep,
     waitFor,
-    deliver
+    deliver,
+    effect
   };
 }
 
@@ -504,4 +672,4 @@ function resolveToolDurability(context, callId, signal) {
   return contexts.get(context)?.(callId, signal);
 }
 
-export { DURABILITY_STEP_EVENT_KIND, StepResultDecodeError, StepResultNotSerializableError, StepAbortedError, ParkRecordDecodeError, ParkAbortedError, createLocalStepDurability, AgentToolError, isAgentToolError, createToolDurabilityContext, resolveToolDurability };
+export { DURABILITY_STEP_EVENT_KIND, StepResultDecodeError, StepResultNotSerializableError, StepAbortedError, EffectUnresolvedError, ParkRecordDecodeError, ParkAbortedError, createLocalStepDurability, AgentToolError, isAgentToolError, createToolDurabilityContext, resolveToolDurability };

package/dist/{index-97ac4gph.js → index-7f68ghdn.js}

@@ -16,7 +16,7 @@ import {
   createToolChronology,
   isAssistantHistoryEvidence,
   isCompleteAgentHistoryTurn
-} from "./index-1nd48tm9.js";
+} from "./index-gxrt5h6v.js";
 import {
   AgentAssistantPlaceholderSchema,
   AgentJsonObjectSchema,
@@ -33,11 +33,11 @@ import {
   createLocalStepDurability,
   createToolDurabilityContext,
   isAgentToolError
-} from "./index-cq4qfycf.js";
+} from "./index-79z7m7dt.js";
 import {
   ToolExecutionControlError,
   isToolExecutionControlError
-} from "./index-j05z5gn4.js";
+} from "./index-55hkhm67.js";
 import {
   isRecord,
   transportResult

package/dist/{index-r7nmqpsg.js → index-7p1f0vp2.js}

@@ -4,7 +4,7 @@ import {
 } from "./index-rxfy4cq7.js";
 import {
   defineContract
-} from "./index-gyr48nzg.js";
+} from "./index-k30h66yd.js";
 import {
   AppError,
   STITCH_ERROR_STATUS,

package/dist/{index-dcpdvjsc.js → index-863ea9jb.js}

@@ -1,19 +1,19 @@
 import {
   AgentToolError,
   resolveToolDurability
-} from "./index-cq4qfycf.js";
+} from "./index-79z7m7dt.js";
 import {
   collectToolSurface
-} from "./index-vcvkq30w.js";
+} from "./index-hmp4800j.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-2cr1cqhn.js";
+} from "./index-khtgb21r.js";
 import {
   isToolExecutionControlError,
   toolCauseFromResult,
   toolResultFromError
-} from "./index-j05z5gn4.js";
+} from "./index-55hkhm67.js";
 import {
   isRecord
 } from "./index-hffjpmq9.js";

package/dist/index-8p52kd5p.js

@@ -0,0 +1,242 @@
+import {
+  isRecord
+} from "./index-hffjpmq9.js";
+
+// src/internal/exclusive-lock.ts
+import { constants } from "node:fs";
+import { lstat, open, unlink } from "node:fs/promises";
+import { hostname } from "node:os";
+
+// src/internal/process-identity.ts
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { platform } from "node:os";
+import { promisify } from "node:util";
+var detectedIdentity;
+async function firstReadableLine(paths) {
+  for (const path of paths) {
+    try {
+      const text = (await readFile(path, "utf8")).trim();
+      if (text.length > 0)
+        return text;
+    } catch {}
+  }
+  return null;
+}
+var run = promisify(execFile);
+function parsePlatformUuid(dump) {
+  return /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(dump)?.[1] ?? null;
+}
+async function readDarwinPlatformUuid(command = "ioreg") {
+  try {
+    const { stdout } = await run(command, ["-rd1", "-c", "IOPlatformExpertDevice"], {
+      timeout: 2000,
+      maxBuffer: 1 << 20,
+      encoding: "utf8"
+    });
+    return parsePlatformUuid(stdout);
+  } catch {
+    return null;
+  }
+}
+async function machineIdentity(declared) {
+  if (declared !== undefined)
+    return declared;
+  if (detectedIdentity !== undefined)
+    return detectedIdentity;
+  detectedIdentity = platform() === "darwin" ? await readDarwinPlatformUuid() : await firstReadableLine(["/etc/machine-id", "/var/lib/dbus/machine-id"]);
+  return detectedIdentity;
+}
+async function probeLiveness(pid) {
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    return isRecord(error) && error.code === "ESRCH" ? "gone" : "alive";
+  }
+  return await isZombieProcess(pid) ? "gone" : "alive";
+}
+async function isZombieProcess(pid, seam = {}) {
+  const { procRoot = "/proc", psCommand = "ps" } = seam;
+  try {
+    const stat = await readFile(`${procRoot}/${pid}/stat`, "utf8");
+    return stat.slice(stat.lastIndexOf(")") + 1).trimStart().startsWith("Z");
+  } catch {}
+  try {
+    const { stdout } = await run(psCommand, ["-o", "state=", "-p", String(pid)], {
+      timeout: 2000,
+      maxBuffer: 1 << 16,
+      encoding: "utf8"
+    });
+    return stdout.trim().startsWith("Z");
+  } catch {
+    return false;
+  }
+}
+
+// src/internal/exclusive-lock.ts
+function isCode(error, code) {
+  return isRecord(error) && error.code === code;
+}
+function readOwner(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return;
+  }
+  if (!isRecord(parsed))
+    return;
+  const { pid, host, acquiredAt, machine } = parsed;
+  if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0)
+    return;
+  if (typeof host !== "string" || host.length === 0)
+    return;
+  if (typeof acquiredAt !== "string")
+    return;
+  const identified = typeof machine === "string" && machine.length > 0 ? { machine } : {};
+  return { pid, host, acquiredAt, ...identified };
+}
+function attribute(owner, identity) {
+  if (identity !== null && owner.machine !== undefined) {
+    return owner.machine === identity ? "this-machine" : "another-machine";
+  }
+  return owner.host === hostname() ? "this-machine" : "unattributable";
+}
+async function diagnose(owner, declaredIdentity) {
+  if (!owner)
+    return { attribution: "unattributable", liveness: "not-probed", owner: null };
+  const attribution = attribute(owner, await machineIdentity(declaredIdentity));
+  if (attribution !== "this-machine")
+    return { attribution, liveness: "not-probed", owner };
+  return { attribution, liveness: await probeLiveness(owner.pid), owner };
+}
+async function readLockFile(path) {
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const info = await handle.stat();
+    return {
+      owner: readOwner(await handle.readFile("utf8")),
+      ino: info.ino,
+      mtimeMs: info.mtimeMs
+    };
+  } catch {
+    return;
+  } finally {
+    await handle?.close().catch(() => {
+      return;
+    });
+  }
+}
+async function unlinkIfSame(path, ino) {
+  try {
+    if ((await lstat(path)).ino !== ino)
+      return;
+    await unlink(path);
+  } catch (error) {
+    if (!isCode(error, "ENOENT"))
+      throw error;
+  }
+}
+async function createOwned(path, options, reclaimed) {
+  const identity = await machineIdentity(options.machineIdentity);
+  const handle = await open(path, "wx", options.mode);
+  const owner = {
+    pid: process.pid,
+    host: hostname(),
+    acquiredAt: new Date().toISOString(),
+    ...identity !== null && { machine: identity }
+  };
+  let ino;
+  try {
+    await handle.writeFile(`${JSON.stringify(owner)}
+`, "utf8");
+    ino = (await handle.stat()).ino;
+  } catch (error) {
+    await handle.close().catch(() => {
+      return;
+    });
+    await unlink(path).catch(() => {
+      return;
+    });
+    throw error;
+  }
+  let released = false;
+  return {
+    path,
+    owner,
+    reclaimed,
+    async release() {
+      if (released)
+        return;
+      released = true;
+      try {
+        await handle.close();
+      } finally {
+        await unlinkIfSame(path, ino);
+      }
+    }
+  };
+}
+function reclaimable(state, diagnosis, graceMs) {
+  if (state.owner)
+    return diagnosis.liveness === "gone";
+  return graceMs !== undefined && Date.now() - state.mtimeMs >= graceMs;
+}
+async function reclaimUnderGuard(path, options) {
+  const guardPath = `${path}.reclaim`;
+  let guard;
+  try {
+    guard = await createOwned(guardPath, options, false);
+  } catch (error) {
+    if (!isCode(error, "EEXIST"))
+      throw error;
+    const stale = await readLockFile(guardPath);
+    if (stale) {
+      const verdict = await diagnose(stale.owner, options.machineIdentity);
+      if (reclaimable(stale, verdict, options.ownerlessGraceMs ?? 5000)) {
+        await unlinkIfSame(guardPath, stale.ino);
+      }
+    }
+    return;
+  }
+  try {
+    const state = await readLockFile(path);
+    if (state) {
+      const diagnosis = await diagnose(state.owner, options.machineIdentity);
+      if (!reclaimable(state, diagnosis, options.ownerlessGraceMs))
+        return "refused";
+      await unlinkIfSame(path, state.ino);
+    }
+    return await createOwned(path, options, state !== undefined).catch((error) => {
+      if (isCode(error, "EEXIST"))
+        return "refused";
+      throw error;
+    });
+  } finally {
+    await guard.release().catch(() => {
+      return;
+    });
+  }
+}
+async function attemptExclusiveLock(path, options) {
+  try {
+    return { held: await createOwned(path, options, false) };
+  } catch (error) {
+    if (!isCode(error, "EEXIST"))
+      throw error;
+    if (!options.reclaim)
+      return { error };
+    const state = await readLockFile(path);
+    const diagnosis = await diagnose(state?.owner, options.machineIdentity);
+    if (!state || !reclaimable(state, diagnosis, options.ownerlessGraceMs)) {
+      return { error, diagnosis };
+    }
+    const reclaimed = await reclaimUnderGuard(path, options);
+    if (reclaimed !== undefined && reclaimed !== "refused")
+      return { held: reclaimed };
+    return { error, diagnosis };
+  }
+}
+
+export { attemptExclusiveLock };