@prismatic-io/lux 0.0.1 → 0.0.2-preview.10

package/src/orchestrator/doctor.ts

@@ -5,6 +5,7 @@ import { glob } from "tinyglobby";
 import { z } from "zod";
 import { RubricConfigSchema } from "../assertions/rubric/index.js";
 import type { EvalCase, Registry } from "../core/index.js";
+import { registryForEvalCase } from "./case-extensions.js";
 import { buildRegistryFromConfig, loadLuxConfig, type ResolvedLuxConfig } from "./config.js";
 import { type DiscoveredCase, type DiscoveryResult, discoverCases } from "./discover.js";
 import { cliIdentity, ExperimentCampaignPlanSchema, planExperimentCampaign } from "./experiment.js";
@@ -559,12 +560,13 @@ const inspectCase = async (
 ): Promise<CliTarget[]> => {
   try {
     const authored = await loadEvalCase(discovered.path);
+    const caseRegistry = registryForEvalCase(registry, authored);
     const drivers = caseDriverReferences(authored.driver, config);
     const answerer = authored.answerer ?? config.defaultAnswerer;
-    validateCaseDrivers(discovered.id, drivers, registry, recorder);
-    validateCaseAnswerer(discovered.id, answerer, registry, recorder);
+    validateCaseDrivers(discovered.id, drivers, caseRegistry, recorder);
+    validateCaseAnswerer(discovered.id, answerer, caseRegistry, recorder);
     return [
-      ...(await validateCaseAssertions(discovered.id, authored, config, registry, recorder)),
+      ...(await validateCaseAssertions(discovered.id, authored, config, caseRegistry, recorder)),
       ...executionTargetsForCase(discovered.id, drivers, answerer),
     ];
   } catch (error) {

package/src/orchestrator/experiment-evaluation.ts

@@ -101,6 +101,23 @@ const evaluationMetrics = (
   ),
 });
 
+const evaluationMetricDefinitions = (summary: SuiteSummary) =>
+  Object.fromEntries(
+    Object.entries(summary.metrics).flatMap(([name, metric]) => {
+      if (!metric.unit && !metric.label && !metric.better) return [];
+      return [
+        [
+          name,
+          {
+            unit: metric.unit ?? "number",
+            better: metric.better ?? "neutral",
+            ...(metric.label ? { label: metric.label } : {}),
+          },
+        ],
+      ];
+    }),
+  );
+
 const summaryUsage = (summary: SuiteSummary) =>
   summary.samples.reduce(
     (usage, sample) =>
@@ -277,6 +294,7 @@ const agentEvaluationFromSuite = (input: {
       summary.cases.map((entry) => [entry.canonicalCaseId, entry.passRate]),
     ),
     metrics: evaluationMetrics(summary, candidate),
+    metricDefinitions: evaluationMetricDefinitions(summary),
     samples: evaluationSamples(summary),
     metricCalls: summary.samples.length,
     judgeCalls: results.reduce(
@@ -352,6 +370,10 @@ const aggregateAgentUnits = (
         .map(([, values]) => average(values)),
     ]),
   );
+  const metricDefinitions = Object.assign(
+    {},
+    ...units.map(({ evaluation }) => evaluation.metricDefinitions ?? {}),
+  );
   return {
     candidateId: candidate.id,
     profileId,
@@ -367,6 +389,7 @@ const aggregateAgentUnits = (
         name === "subject.bytes" ? candidate.sourceBytes : average(values),
       ]),
     ),
+    metricDefinitions,
     samples,
     metricCalls: units.reduce((total, unit) => total + (unit.evaluation.metricCalls ?? 0), 0),
     judgeCalls: units.reduce((total, unit) => total + (unit.evaluation.judgeCalls ?? 0), 0),

package/src/orchestrator/grading.ts

@@ -76,6 +76,7 @@ export const graderConfigHash = (input: {
   assertions: readonly AssertionEvaluatorIdentity[];
   validatedAssertionsHash: string;
   graderContext?: unknown;
+  skipJudge?: boolean;
 }): string =>
   valueHash({
     luxVersion: input.luxVersion,
@@ -83,6 +84,7 @@ export const graderConfigHash = (input: {
     assertions: input.assertions,
     validatedAssertionsHash: input.validatedAssertionsHash,
     graderContext: input.graderContext ?? null,
+    skipJudge: input.skipJudge ?? false,
   });
 
 export const validateAssertionPlan = async (
@@ -133,6 +135,7 @@ export const gradeRun = async (
     complete: (attemptIds: readonly string[]) => void | Promise<void>;
   },
   validatedConfigs?: readonly unknown[],
+  skipJudge = false,
 ): Promise<GradingReport> => {
   const guardedObserver = guardRunObserver(observer);
   const assertions = run.case.assertions ?? [];
@@ -141,12 +144,27 @@ export const gradeRun = async (
   }
 
   const entries: GradingAssertionEntry[] = [];
+  const skippedAssertions: Array<{
+    id: string;
+    type: string;
+    name: string;
+    reason: "judge-disabled";
+  }> = [];
   let weightedScoreSum = 0;
   let weightSum = 0;
   let allPassed = true;
   let gradingIncomplete = false;
 
   for (const [index, a] of assertions.entries()) {
+    if (skipJudge && a.type === "rubric") {
+      skippedAssertions.push({
+        id: a.id ?? `${a.type}:${index + 1}`,
+        type: a.type,
+        name: describeAssertion(a),
+        reason: "judge-disabled",
+      });
+      continue;
+    }
     // Grading is the last cancellation point — an LLM judge can run for
     // minutes per assertion. An aborted grade can't claim everything passed.
     if (abortSignal?.aborted) {
@@ -247,12 +265,13 @@ export const gradeRun = async (
   }
 
   let caseScore: number | null = null;
-  if (!gradingIncomplete) caseScore = weightSum > 0 ? weightedScoreSum / weightSum : 0;
+  if (!gradingIncomplete && weightSum > 0) caseScore = weightedScoreSum / weightSum;
   return {
     schemaVersion: 1,
-    casePassed: gradingIncomplete ? null : allPassed,
+    casePassed: gradingIncomplete || weightSum === 0 ? null : allPassed,
     caseScore,
     assertions: entries,
+    ...(skippedAssertions.length > 0 ? { skippedAssertions } : {}),
     ...(gradingIncomplete
       ? { incomplete: { exitReason: "error" as const, phase: "grading" as const } }
       : {}),

package/src/orchestrator/index.ts

@@ -122,6 +122,7 @@ export {
   formatRunsTable,
   type ListedRun,
   listRuns,
+  loadRunArtifacts,
   loadRunDetail,
   type RunDetail,
 } from "./list-runs.js";

package/src/orchestrator/list-runs.ts

@@ -2,6 +2,11 @@ import { existsSync } from "node:fs";
 import { constants, lstat, open, readdir } from "node:fs/promises";
 import { basename, join, relative, sep } from "node:path";
 import {
+  ActionProgressPayloadSchema,
+  AgentCompletedPayloadSchema,
+  AgentSpawnPayloadSchema,
+  type Artifact,
+  ArtifactSchema,
   type GradingReport,
   GradingReportSchema,
   harnessUsage,
@@ -31,6 +36,11 @@ export type ListedRun = {
   startedAt: string | null;
   endedAt: string | null;
   durationMs: number | null;
+  timeToFirstActionMs: number | null;
+  timeToFirstMutationMs: number | null;
+  timeToFirstDurableMutationMs: number | null;
+  driverMetrics: NonNullable<RunMetadata["driverMetrics"]>;
+  subagentCount: number;
   casePassed: boolean | null;
   caseScore: number | null;
   assertionPassed: number;
@@ -63,6 +73,12 @@ const summarizeRun = async (
     startedAt,
     endedAt,
     durationMs,
+    timeToFirstActionMs: meta?.actionTiming?.timeToFirstActionMs ?? null,
+    timeToFirstMutationMs: meta?.actionTiming?.timeToFirstMutationMs ?? null,
+    timeToFirstDurableMutationMs: meta?.actionTiming?.timeToFirstDurableMutationMs ?? null,
+    driverMetrics: meta?.driverMetrics ?? {},
+    subagentCount:
+      meta?.agentActivity?.filter((activity) => activity.agent.role === "subagent").length ?? 0,
     casePassed: grading?.casePassed ?? null,
     caseScore: grading?.caseScore ?? null,
     assertionPassed: passing,
@@ -127,7 +143,7 @@ export const listRuns = async (runsRoot: string): Promise<ListedRun[]> => {
 export const formatRunsTable = (runs: ListedRun[]): string => {
   if (runs.length === 0) return "(no runs found)";
   const rows: string[][] = [
-    ["status", "case", "driver", "ts", "exit", "score", "duration"],
+    ["status", "case", "driver", "agents", "ts", "exit", "score", "duration"],
     ...runs.map((r) => {
       let status = "ungraded";
       if (r.casePassed === true) status = "PASS";
@@ -137,7 +153,8 @@ export const formatRunsTable = (runs: ListedRun[]): string => {
           ? `${(r.caseScore * 100).toFixed(0)}% (${r.assertionPassed}/${r.assertionTotal})`
           : "—";
       const duration = r.durationMs !== null ? `${(r.durationMs / 1000).toFixed(1)}s` : "—";
-      return [status, r.caseSlug, r.driverName, r.ts, r.exitReason ?? "?", score, duration];
+      const agents = r.subagentCount > 0 ? `1+${r.subagentCount}` : "1";
+      return [status, r.caseSlug, r.driverName, agents, r.ts, r.exitReason ?? "?", score, duration];
     }),
   ];
   const header = rows[0] ?? [];
@@ -156,6 +173,9 @@ export type RunDetail = {
   artifacts: string[];
 };
 
+export const loadRunArtifacts = async (runDir: string): Promise<Artifact[]> =>
+  (await safeReadJson(join(runDir, "artifacts.json"), ArtifactSchema.array())) ?? [];
+
 const readEventsJsonl = async (path: string): Promise<RunEvent[]> => {
   if (!existsSync(path)) return [];
   if ((await lstat(path)).isSymbolicLink()) {
@@ -291,6 +311,27 @@ const appendMetadataDetail = (lines: string[], detail: RunDetail): void => {
         `phases: agent=${secs(phases.agent)} collect=${secs(phases.collect)} grading=${secs(phases.grading)}`,
       );
     }
+    const actions = detail.metadata.actionTiming;
+    if (actions) {
+      const value = (ms: number | undefined): string => (ms === undefined ? "—" : `${ms}ms`);
+      lines.push(
+        `first action: any=${value(actions.timeToFirstActionMs)} mutation=${value(actions.timeToFirstMutationMs)} durable-mutation=${value(actions.timeToFirstDurableMutationMs)}`,
+      );
+    }
+    const activities = detail.metadata.agentActivity ?? [];
+    const subagents = activities.filter((activity) => activity.agent.role === "subagent");
+    if (subagents.length > 0) {
+      lines.push(`subagents: ${subagents.length}`);
+      for (const activity of subagents) {
+        const label = activity.agent.name
+          ? `${activity.agent.name} (${activity.agent.id})`
+          : activity.agent.id;
+        const agentActions = activity.actions;
+        lines.push(
+          `  ${label}: ${activity.status}, ${(activity.durationMs / 1000).toFixed(1)}s, events=${activity.eventCount}, tokens=${totalTokens(activity.usage)}, tools=${activity.toolCalls.total} (${activity.toolCalls.succeeded} ok/${activity.toolCalls.failed} failed/${activity.toolCalls.unresolved} unresolved), actions=${agentActions.total}, mutations=${agentActions.mutations}`,
+        );
+      }
+    }
   }
 };
 
@@ -361,17 +402,37 @@ const formatEventLine = (event: RunEvent): string => {
         }`;
       }
       return `responded(custom): ${JSON.stringify(event.payload).slice(0, 80)}`;
-    case "progress":
+    case "progress": {
+      const agent = event.agent?.role === "subagent" ? ` [subagent ${event.agent.id}]` : "";
+      if (event.kind === "agent-spawn") {
+        const payload = AgentSpawnPayloadSchema.safeParse(event.payload).data;
+        return payload
+          ? `agent-spawn: ${payload.agent.name ?? payload.agent.id} (${payload.agent.id})`
+          : "agent-spawn: malformed";
+      }
+      if (event.kind === "agent-completed") {
+        const payload = AgentCompletedPayloadSchema.safeParse(event.payload).data;
+        return payload
+          ? `agent-completed: ${payload.agentId} (${payload.status})`
+          : "agent-completed: malformed";
+      }
+      if (event.kind === "action") {
+        const payload = ActionProgressPayloadSchema.safeParse(event.payload).data;
+        return payload
+          ? `action${agent}: ${payload.name} (${payload.category})`
+          : "action: malformed";
+      }
       if (event.kind === "tool-call") {
         const payload = ToolCallPayloadSchema.safeParse(event.payload).data;
-        return payload ? `tool-call: ${payload.name}` : "tool-call: malformed";
+        return payload ? `tool-call${agent}: ${payload.name}` : "tool-call: malformed";
       }
       if (event.kind === "tool-result") {
         const payload = ToolResultPayloadSchema.safeParse(event.payload).data;
         if (!payload) return "tool-result: malformed";
-        return `tool-result: ${payload.name} (${payload.isError ? "failed" : "succeeded"})`;
+        return `tool-result${agent}: ${payload.name} (${payload.isError ? "failed" : "succeeded"})`;
       }
       return `progress(${event.kind})`;
+    }
     case "lifecycle":
       return `lifecycle: ${event.stage}`;
     case "ready":

package/src/orchestrator/loader.ts

@@ -1,5 +1,6 @@
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { transferEvalCaseExtensions } from "../core/case-authoring-state.js";
 import { type EvalCase, EvalCaseSchema, formatZodIssues } from "../core/index.js";
 
 export const loadEvalCase = async (filePath: string): Promise<EvalCase> => {
@@ -15,5 +16,6 @@ export const loadEvalCase = async (filePath: string): Promise<EvalCase> => {
   if (!result.success) {
     throw new Error(`Invalid eval case at ${absolute}: ${formatZodIssues(result.error)}`);
   }
+  transferEvalCaseExtensions(mod.default as EvalCase, result.data);
   return result.data;
 };

package/src/orchestrator/orchestrator.ts

@@ -18,6 +18,12 @@ import {
   type SuiteLifecycleHookContext,
   valueHash,
 } from "../core/index.js";
+import {
+  fixturesForEvalCase,
+  mergeLifecycleFixtures,
+  registryForEvalCase,
+  valuesForFixtures,
+} from "./case-extensions.js";
 import { evaluatorImplementationHash } from "./evaluator-identity.js";
 import {
   assertionEvaluatorIdentities,
@@ -122,6 +128,8 @@ export type RunRequest = {
   /** Root that relative `fixtures` dir paths resolve against. */
   fixturesRoot?: string | undefined;
   answererOverride?: string | undefined;
+  /** Skip built-in rubric judge assertions without changing subject execution. */
+  skipJudge?: boolean | undefined;
   startedAt?: Date | undefined;
   /** The `runSuite` invocation this case attempt belongs to. */
   suiteId?: string | undefined;
@@ -476,11 +484,6 @@ export class Orchestrator {
   }
 
   async run(request: RunRequest): Promise<RunResult> {
-    if (this.lifecycleFixtures.length > 0 && !request.suiteId) {
-      throw new Error(
-        "Orchestrator.run() cannot execute configured lifecycle fixtures; use runSuite() for a single case",
-      );
-    }
     if (!request.case && !request.casePath) {
       throw new Error("RunRequest requires either 'case' or 'casePath'");
     }
@@ -489,11 +492,24 @@ export class Orchestrator {
     }
     const casePath = request.casePath ? resolve(request.casePath) : INLINE_CASE_PATH;
     const authoredCase = request.case ?? (await loadEvalCase(casePath));
+    const lifecycleFixtures = mergeLifecycleFixtures(
+      this.lifecycleFixtures,
+      fixturesForEvalCase(authoredCase),
+    );
+    if (
+      lifecycleFixtures.some(({ setupSuite, setupCase }) => setupSuite || setupCase) &&
+      !request.suiteId
+    ) {
+      throw new Error(
+        "Orchestrator.run() cannot execute lifecycle fixtures; use runSuite() for a single case",
+      );
+    }
+    const registry = registryForEvalCase(this.registry, authoredCase);
     const evalCase = bindSubjectRoot(authoredCase, request.subjectRoot);
     const caseId = resolveCaseId(casePath, evalCase, request.caseId);
     const validatedAssertionConfigs = await validateAssertionPlan(
       evalCase.assertions ?? [],
-      this.registry,
+      registry,
     );
 
     const driverRef = resolveDriverReference(evalCase, this.defaultDriver);
@@ -506,11 +522,11 @@ export class Orchestrator {
     );
     const answererName = answererNameOf(answererRef);
 
-    const driverPlugin = this.registry.getDriver(driverName);
+    const driverPlugin = registry.getDriver(driverName);
     if (!driverPlugin) {
       throw new Error(`no driver registered for '${driverName}'`);
     }
-    const answererPlugin = this.registry.getAnswerer(answererName);
+    const answererPlugin = registry.getAnswerer(answererName);
     if (!answererPlugin) {
       throw new Error(`no answerer registered for '${answererName}'`);
     }
@@ -544,7 +560,7 @@ export class Orchestrator {
     try {
       const assertionImplementations = assertionEvaluatorIdentities(
         authoredCase.assertions ?? [],
-        this.registry,
+        registry,
       );
       const validatedAssertionsHash = valueHash(validatedAssertionConfigs);
       const implementationHash = await this.evaluatorImplementationIdentity();
@@ -554,34 +570,40 @@ export class Orchestrator {
         assertions: assertionImplementations,
         validatedAssertionsHash,
         graderContext: this.harness,
+        skipJudge: request.skipJudge ?? false,
       });
-      return await this.runWithPlugins({
-        request,
-        casePath,
-        authoredCase,
-        evalCase,
-        validatedAssertionConfigs,
-        caseId,
-        driverName,
-        answererName,
-        answererConfig: answererCfg,
-        driverConfigHash: valueHash(driverCfg),
-        answererConfigHash: valueHash(answererCfg),
-        validatedAssertionsHash,
-        graderConfigHash: graderHash,
-        evaluatorConfigHash: valueHash({
-          luxVersion: LUX_VERSION,
-          implementationHash,
-          harness: this.harness,
-          driver: { name: driverPlugin.name, create: driverPlugin.create },
-          answerer: { name: answererPlugin.name, create: answererPlugin.create },
-          assertions: assertionImplementations,
-          lifecycleFixtures: this.lifecycleFixtures,
+      return await this.runWithPlugins(
+        {
+          request,
+          casePath,
+          authoredCase,
+          evalCase,
+          validatedAssertionConfigs,
+          caseId,
+          driverName,
+          answererName,
+          answererConfig: answererCfg,
+          driverConfigHash: valueHash(driverCfg),
+          answererConfigHash: valueHash(answererCfg),
           validatedAssertionsHash,
-        }),
-        driver,
-        answerer,
-      });
+          graderConfigHash: graderHash,
+          evaluatorConfigHash: valueHash({
+            luxVersion: LUX_VERSION,
+            implementationHash,
+            harness: this.harness,
+            driver: { name: driverPlugin.name, create: driverPlugin.create },
+            answerer: { name: answererPlugin.name, create: answererPlugin.create },
+            assertions: assertionImplementations,
+            lifecycleFixtures,
+            validatedAssertionsHash,
+            skipJudge: request.skipJudge ?? false,
+          }),
+          fixtureValues: valuesForFixtures(lifecycleFixtures),
+          driver,
+          answerer,
+        },
+        registry,
+      );
     } finally {
       await closeQuietly(() => driver.close(), `driver '${driverName}'`);
       await closeQuietly(() => answerer.close(), `answerer '${answererName}'`);
@@ -599,6 +621,7 @@ export class Orchestrator {
       runsRoot: string;
       fixturesRoot?: string | undefined;
       answererOverride?: string | undefined;
+      skipJudge?: boolean | undefined;
       observer?: SuiteObserver | undefined;
       /** Aborts the cases in flight and stops the pool pulling new ones. */
       abortSignal?: AbortSignal | undefined;
@@ -628,6 +651,20 @@ export class Orchestrator {
     const observer = opts.observer;
     const requestedConcurrency = validateSuiteConcurrency(opts.concurrency);
     const concurrency = Math.min(requestedConcurrency, Math.max(items.length, 1));
+    const authoredCases = await Promise.allSettled(items.map((item) => loadEvalCase(item.path)));
+    const localFixtures = authoredCases.map((result) =>
+      result.status === "fulfilled" ? fixturesForEvalCase(result.value) : [],
+    );
+    const lifecycleFixtures = mergeLifecycleFixtures(this.lifecycleFixtures, ...localFixtures);
+    const globalFixtureNames = new Set(this.lifecycleFixtures.map((fixture) => fixture.name));
+    const itemIndexesByFixture = new Map<string, number[]>();
+    for (const [index, fixtures] of localFixtures.entries()) {
+      for (const fixture of fixtures) {
+        const indexes = itemIndexesByFixture.get(fixture.name) ?? [];
+        indexes.push(index);
+        itemIndexesByFixture.set(fixture.name, indexes);
+      }
+    }
     const suite = await openSuiteRun({
       runsRoot: opts.runsRoot,
       concurrency,
@@ -639,7 +676,7 @@ export class Orchestrator {
       ...(opts.variantId ? { variantId: opts.variantId } : {}),
       ...(opts.candidateId ? { candidateId: opts.candidateId } : {}),
       ...(opts.subjectHash ? { subjectHash: opts.subjectHash } : {}),
-      fixtures: this.lifecycleFixtures.map(({ name, pluginVersion }) => ({
+      fixtures: lifecycleFixtures.map(({ name, pluginVersion }) => ({
         name,
         pluginVersion,
       })),
@@ -677,9 +714,16 @@ export class Orchestrator {
     if (!opts.abortSignal?.aborted) {
       try {
         cleanupSuiteHooks = await setupLifecycleHooks(
-          this.lifecycleFixtures,
+          lifecycleFixtures,
           "suite",
-          (hook) => hook.setupSuite?.(hookContext),
+          (hook) => {
+            if (globalFixtureNames.has(hook.name)) return hook.setupSuite?.(hookContext);
+            const indexes = itemIndexesByFixture.get(hook.name) ?? [];
+            return hook.setupSuite?.({
+              ...hookContext,
+              items: indexes.flatMap((index) => hookContext.items[index] ?? []),
+            });
+          },
           opts.abortSignal,
         );
       } catch (error) {
@@ -718,7 +762,7 @@ export class Orchestrator {
         let cleanupCaseHooks: () => void | Promise<void>;
         try {
           cleanupCaseHooks = await setupLifecycleHooks(
-            this.lifecycleFixtures,
+            mergeLifecycleFixtures(this.lifecycleFixtures, localFixtures[index] ?? []),
             "case",
             (hook) =>
               hook.setupCase?.({
@@ -749,6 +793,7 @@ export class Orchestrator {
             runsRoot: opts.runsRoot,
             fixturesRoot: opts.fixturesRoot,
             answererOverride: opts.answererOverride,
+            skipJudge: opts.skipJudge,
             observer: handle ?? observer,
             abortSignal: opts.abortSignal,
             suiteId: suite.manifest.suiteId,
@@ -906,11 +951,12 @@ export class Orchestrator {
 
   private runWithPlugins(
     args: Omit<RunWithPluginsArgs, "luxVersion" | "registry">,
+    registry: Registry = this.registry,
   ): Promise<RunResult> {
     return executeRunWithPlugins({
       ...args,
       luxVersion: LUX_VERSION,
-      registry: this.registry,
+      registry,
     });
   }
 }

package/src/orchestrator/owned-lock.ts

@@ -1,8 +1,6 @@
-import { randomInt, randomUUID } from "node:crypto";
-import { link, lstat, open, readdir, readFile, rm, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { link, lstat, open, readFile, rm, unlink } from "node:fs/promises";
 import { hostname } from "node:os";
-import { basename, dirname, join } from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
 
 export type LockRecoveryClaim = {
   path: string;
@@ -60,36 +58,54 @@ const linkedClaim = (lockPath: string, claimPath: string): LockRecoveryClaim =>
   release: () => rm(claimPath, { force: true }),
 });
 
-const recoveryHost = Buffer.from(hostname()).toString("base64url");
+type RecoveryMutexOwner = {
+  pid: number;
+  hostname: string;
+  lockToken: string;
+};
 
-const localClaimProcessIsDead = (prefix: string, name: string): boolean => {
-  const [claimHost, rawPid, id, extra] = name.slice(prefix.length).split(".");
-  if (claimHost !== recoveryHost || !rawPid || !id || extra !== undefined) return false;
+const recoveryOwnerIsDead = (owner: RecoveryMutexOwner): boolean => {
+  if (owner.hostname !== hostname()) return false;
   try {
-    process.kill(Number(rawPid), 0);
+    process.kill(owner.pid, 0);
     return false;
   } catch (error) {
     return (error as NodeJS.ErrnoException).code === "ESRCH";
   }
 };
 
-const hasCompetingRecoveryClaim = async (lockPath: string, claimPath: string): Promise<boolean> => {
-  const claim = await lstat(claimPath);
-  const directory = dirname(lockPath);
-  const claimName = basename(claimPath);
-  const prefix = `${basename(lockPath)}.recovering-`;
-  for (const name of await readdir(directory)) {
-    if (name === claimName || !name.startsWith(prefix)) continue;
-    const peerPath = join(directory, name);
-    const peer = await missingAsNull(lstat(peerPath));
-    if (!peer || peer.dev !== claim.dev || peer.ino !== claim.ino) continue;
-    if (localClaimProcessIsDead(prefix, name)) {
-      await unlinkIfExists(peerPath);
-      continue;
+const acquireRecoveryMutex = async (
+  lockPath: string,
+): Promise<{ path: string; lockToken: string } | null> => {
+  const path = `${lockPath}.recovery`;
+  while (true) {
+    try {
+      const owner = await publishOwnedLock(path, {
+        pid: process.pid,
+        hostname: hostname(),
+      });
+      return { path, lockToken: owner.lockToken };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
     }
-    return true;
+    let owner: RecoveryMutexOwner;
+    try {
+      const value = JSON.parse(await readFile(path, "utf8")) as Partial<RecoveryMutexOwner>;
+      if (
+        !Number.isSafeInteger(value.pid) ||
+        typeof value.hostname !== "string" ||
+        typeof value.lockToken !== "string"
+      ) {
+        return null;
+      }
+      owner = value as RecoveryMutexOwner;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      return null;
+    }
+    if (!recoveryOwnerIsDead(owner)) return null;
+    await releaseOwnedLock(path, owner.lockToken);
   }
-  return false;
 };
 
 /**
@@ -97,24 +113,28 @@ const hasCompetingRecoveryClaim = async (lockPath: string, claimPath: string): P
  * Foreign claims stay conservative because foreign lock owners do too.
  */
 export const claimLockForRecovery = async (lockPath: string): Promise<LockRecoveryClaim | null> => {
-  const claimPath = `${lockPath}.recovering-${recoveryHost}.${process.pid}.${randomUUID()}`;
+  const mutex = await acquireRecoveryMutex(lockPath);
+  if (!mutex) return null;
+  const claimPath = `${lockPath}.recovering-${mutex.lockToken}`;
   try {
     await link(lockPath, claimPath);
   } catch (error) {
     const code = (error as NodeJS.ErrnoException).code;
+    await releaseOwnedLock(mutex.path, mutex.lockToken);
     if (code === "ENOENT") return null;
     throw error;
   }
   const claim = linkedClaim(lockPath, claimPath);
-  try {
-    if (!(await hasCompetingRecoveryClaim(lockPath, claimPath))) return claim;
-  } catch (error) {
-    await claim.release();
-    throw error;
-  }
-  await claim.release();
-  await delay(randomInt(1, 8));
-  return null;
+  return {
+    ...claim,
+    release: async () => {
+      try {
+        await claim.release();
+      } finally {
+        await releaseOwnedLock(mutex.path, mutex.lockToken);
+      }
+    },
+  };
 };
 
 /** Remove only the canonical lock that still carries this acquisition token. */