@herbertgao/pi-extensions 2026.9.5 → 2026.9.7

package/node_modules/@luxusai/pi-hindsight/extensions/operations/reflect-presenter.ts

@@ -1,35 +0,0 @@
-function summarizeReflectTrace(trace: unknown): string {
-  if (!trace || typeof trace !== "object") return "";
-  const record = trace as Record<string, unknown>;
-  const toolCalls = Array.isArray(record.tool_calls) ? record.tool_calls : [];
-  const llmCalls = Array.isArray(record.llm_calls) ? record.llm_calls : [];
-  if (toolCalls.length === 0 && llmCalls.length === 0) return "";
-  const toolNames = toolCalls
-    .map((call) =>
-      call && typeof call === "object" ? (call as Record<string, unknown>).tool : undefined,
-    )
-    .filter((name): name is string => typeof name === "string");
-  const toolPart = toolCalls.length
-    ? `${toolCalls.length} tool call${toolCalls.length === 1 ? "" : "s"}${
-        toolNames.length ? ` (${[...new Set(toolNames)].join(", ")})` : ""
-      }`
-    : "";
-  const llmPart = llmCalls.length
-    ? `${llmCalls.length} LLM call${llmCalls.length === 1 ? "" : "s"}`
-    : "";
-  return `Trace: ${[toolPart, llmPart].filter(Boolean).join("; ")}`;
-}
-
-export function formatReflectResult(result: unknown): string {
-  if (typeof result === "string") return result;
-  if (!result || typeof result !== "object") return JSON.stringify(result, null, 2);
-  const record = result as Record<string, unknown>;
-  const parts: string[] = [];
-  if (typeof record.text === "string" && record.text.trim()) parts.push(record.text.trim());
-  if (record.structured_output && typeof record.structured_output === "object") {
-    parts.push(`Structured output:\n${JSON.stringify(record.structured_output, null, 2)}`);
-  }
-  const traceSummary = summarizeReflectTrace(record.trace);
-  if (traceSummary) parts.push(traceSummary);
-  return parts.length ? parts.join("\n\n") : JSON.stringify(result, null, 2);
-}

package/node_modules/@luxusai/pi-hindsight/extensions/operations/scope-migrate.ts

@@ -1,177 +0,0 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import {
-  deriveProjectBankId,
-  legacyRepoScopeTag,
-  projectScopeTag,
-  resolveProjectIdentity,
-} from "../banks/banking.js";
-import type { ResolvedConfig } from "../types.js";
-
-export interface ScopeMigratePlan {
-  dryRun: true;
-  /** Never rewrites banks/tags from this plan alone. */
-  rewrite: "none";
-  bankId: string;
-  pathDerivedBank: boolean;
-  scopeMode: ResolvedConfig["scope"]["mode"];
-  projectTag: string;
-  legacyRepoTag: string;
-  projectId: string;
-  projectIdBasis: "pin" | "remote" | "basename";
-  projectIdSource: string;
-  dualTagWindow: true;
-  /**
-   * True while retain still stamps legacy repo:<slug>-<path-hash>.
-   * That legacy tag always depends on absolute path; dual-tag project: is the stable recovery path.
-   */
-  legacyPathHashTag: true;
-  /**
-   * True when project id itself is weak (basename only). Remote/pin identities are stable;
-   * do not conflate them with path-hash legacy tags.
-   */
-  identityBasisWeak: boolean;
-  findings: string[];
-  guidance: string[];
-  /** Optional remote tag sample counts when listTags results were provided. */
-  remoteTagCounts?: {
-    projectTagHits: number;
-    legacyRepoTagHits: number;
-    otherRepoTags: string[];
-    sampleSize: number;
-  };
-  createdAt: string;
-}
-
-export interface ScopeMigrateReceipt extends ScopeMigratePlan {
-  receiptPath: string;
-}
-
-/**
- * Build a dry-run scope migration plan. Never mutates Hindsight banks or tags.
- * Dual-tag retain/recall already covers the live window; this plan documents risk and next steps.
- */
-export function buildScopeMigratePlan(args: {
-  cwd: string;
-  config: ResolvedConfig;
-  projectBankId?: string;
-  bankTags?: string[];
-  now?: Date;
-}): ScopeMigratePlan {
-  const identity = resolveProjectIdentity(args.cwd, args.config);
-  const bankId = args.projectBankId ?? deriveProjectBankId(args.cwd, args.config);
-  const pathDerivedBank = !args.config.banks.project.bankId;
-  const projectTag = projectScopeTag(identity.projectId);
-  const legacyRepoTag = legacyRepoScopeTag(identity.legacyRepoKey);
-  const identityBasisWeak = identity.basis === "basename";
-
-  const findings: string[] = [];
-  const guidance: string[] = [];
-
-  findings.push(
-    `Active dual-tag window: retain writes ${projectTag} and ${legacyRepoTag}; recall any_strict matches either.`,
-  );
-  findings.push(`Project id basis=${identity.basis} source=${identity.source} → ${projectTag}.`);
-  findings.push(
-    `Legacy tag ${legacyRepoTag} is path-hash based (machine/path moves change the hash). Stable project: tag is the recovery path for new writes.`,
-  );
-
-  if (pathDerivedBank) {
-    findings.push(
-      `Coding bank is path-derived (${bankId}); domain-tagged mode requires banks.project.bankId for a shared coding bank.`,
-    );
-    guidance.push(
-      "Set banks.project.bankId (and setupComplete) so repos share one coding bank; do not rely on path-hash bank ids.",
-    );
-  }
-
-  if (identityBasisWeak) {
-    findings.push(
-      "Project id is basename-derived; remotes or pins are more stable across clones and renames.",
-    );
-    guidance.push(
-      'Prefer scope.projectId pin or projectIdStrategy "remote" when a git origin exists.',
-    );
-  } else {
-    findings.push(
-      `Project id basis is ${identity.basis} (stable across absolute path moves when dual-tag project: is present).`,
-    );
-  }
-
-  let remoteTagCounts: ScopeMigratePlan["remoteTagCounts"];
-  if (args.bankTags?.length) {
-    const otherRepoTags = [
-      ...new Set(args.bankTags.filter((t) => t.startsWith("repo:") && t !== legacyRepoTag)),
-    ].sort();
-    const projectTagHits = args.bankTags.filter((t) => t === projectTag).length;
-    const legacyRepoTagHits = args.bankTags.filter((t) => t === legacyRepoTag).length;
-    remoteTagCounts = {
-      projectTagHits,
-      legacyRepoTagHits,
-      otherRepoTags,
-      sampleSize: args.bankTags.length,
-    };
-    findings.push(
-      `Remote tag sample (${args.bankTags.length}): project hits=${projectTagHits}, legacy hits=${legacyRepoTagHits}, other repo:* tags=${otherRepoTags.length}.`,
-    );
-    if (legacyRepoTagHits > 0 && projectTagHits === 0) {
-      findings.push(
-        "Sample has legacy repo tags without the stable project tag — reimport or dual-tag new retains before dropping dual-tag.",
-      );
-    }
-    if (otherRepoTags.length > 0) {
-      findings.push(
-        `Other path-hash repo tags present (likely other machines/paths): ${otherRepoTags.slice(0, 5).join(", ")}${otherRepoTags.length > 5 ? "…" : ""}.`,
-      );
-      guidance.push(
-        "Other repo:* path-hashes are expected after path moves; dual-tag project: is the recovery path for new retains.",
-      );
-    }
-  } else {
-    guidance.push(
-      "Optional: pass bank tag inventory (listTags) into dry-run for remote counts; this local plan never rewrites.",
-    );
-  }
-
-  guidance.push(
-    "No silent rewrite: this dry-run only writes a local receipt under .pi/hindsight/.",
-  );
-  guidance.push(
-    "When dual-tag can end: every active project memory carries project:<id> (or you completed export/import rebuild).",
-  );
-
-  return {
-    dryRun: true,
-    rewrite: "none",
-    bankId,
-    pathDerivedBank,
-    scopeMode: args.config.scope.mode,
-    projectTag,
-    legacyRepoTag,
-    projectId: identity.projectId,
-    projectIdBasis: identity.basis,
-    projectIdSource: identity.source,
-    dualTagWindow: true,
-    legacyPathHashTag: true,
-    identityBasisWeak,
-    findings,
-    guidance,
-    ...(remoteTagCounts ? { remoteTagCounts } : {}),
-    createdAt: (args.now ?? new Date()).toISOString(),
-  };
-}
-
-export function resolveScopeMigrateReceiptPath(cwd: string): string {
-  return join(cwd, ".pi", "hindsight", "scope-migrate-receipt.json");
-}
-
-export async function writeScopeMigrateReceipt(
-  cwd: string,
-  plan: ScopeMigratePlan,
-): Promise<ScopeMigrateReceipt> {
-  const receiptPath = resolveScopeMigrateReceiptPath(cwd);
-  await mkdir(dirname(receiptPath), { recursive: true });
-  const receipt: ScopeMigrateReceipt = { ...plan, receiptPath };
-  await writeFile(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`, "utf8");
-  return receipt;
-}

package/node_modules/@luxusai/pi-hindsight/extensions/operations/tools.ts

@@ -1,7 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { MemoryOperationsDeps } from "./memory-operation-service.js";
-import { createOperationCatalog } from "./operation-catalog.js";
-
-export function registerTools(pi: ExtensionAPI, deps: MemoryOperationsDeps) {
-  for (const tool of createOperationCatalog(deps).tools) pi.registerTool(tool);
-}

package/node_modules/@luxusai/pi-hindsight/extensions/queue/flush-presenter.ts

@@ -1,21 +0,0 @@
-import type { RetainOutcome } from "../types.js";
-import type { FlushRetainQueueResult } from "./queue.js";
-
-export function formatRetainOutcome(outcome: RetainOutcome | undefined): string {
-  if (!outcome) return "";
-  const parts: string[] = [];
-  if (outcome.itemsCount !== undefined) parts.push(`${outcome.itemsCount} items`);
-  if (outcome.operations !== undefined) parts.push(`${outcome.operations} operations`);
-  if (outcome.tokens !== undefined) parts.push(`${outcome.tokens} tokens`);
-  return parts.join(", ");
-}
-
-export function formatFlushRetainQueueResult(result: FlushRetainQueueResult): string {
-  const base = `Hindsight flushed ${result.sent}; dead-lettered ${result.deadLettered}; remaining ${result.remaining}`;
-  const outcome = formatRetainOutcome(result.outcome);
-  return outcome ? `${base}; retained ${outcome}` : base;
-}
-
-export function flushRetainQueueNotifyLevel(result: FlushRetainQueueResult): "info" | "warning" {
-  return result.remaining || result.deadLettered || result.malformed ? "warning" : "info";
-}

package/node_modules/@luxusai/pi-hindsight/extensions/queue/jsonl-queue-store.ts

@@ -1,112 +0,0 @@
-import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
-
-export interface JsonlQueueFileSummary {
-  path: string;
-  valid: number;
-  malformed: number;
-  error: string | null;
-}
-
-export interface ParsedJsonlQueue<T> {
-  jobs: T[];
-  malformedLines: string[];
-}
-
-export class JsonlQueueStore<T> {
-  constructor(
-    readonly path: string,
-    private readonly isItem: (value: unknown) => value is T,
-  ) {}
-
-  async count(): Promise<number> {
-    try {
-      return (await readFile(this.path, "utf8")).split("\n").filter(Boolean).length;
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") return 0;
-      throw error;
-    }
-  }
-
-  async append(items: T[]): Promise<void> {
-    if (items.length === 0) return;
-    await mkdir(dirname(this.path), { recursive: true });
-    await appendFile(
-      this.path,
-      items.map((item) => JSON.stringify(item)).join("\n") + "\n",
-      "utf8",
-    );
-  }
-
-  async readStrict(): Promise<T[]> {
-    const parsed = await this.readTolerant();
-    if (parsed.malformedLines.length > 0) {
-      throw new Error(
-        `Malformed queue file ${this.path}: ${parsed.malformedLines.length} invalid line(s)`,
-      );
-    }
-    return parsed.jobs;
-  }
-
-  async readTolerant(): Promise<ParsedJsonlQueue<T>> {
-    try {
-      const text = await readFile(this.path, "utf8");
-      const jobs: T[] = [];
-      const malformedLines: string[] = [];
-      for (const line of text.split("\n").filter(Boolean)) {
-        try {
-          const parsed = JSON.parse(line) as unknown;
-          if (this.isItem(parsed)) jobs.push(parsed);
-          else malformedLines.push(line);
-        } catch {
-          malformedLines.push(line);
-        }
-      }
-      return { jobs, malformedLines };
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-        return { jobs: [], malformedLines: [] };
-      }
-      throw error;
-    }
-  }
-
-  async summarize(): Promise<JsonlQueueFileSummary> {
-    try {
-      const text = await readFile(this.path, "utf8");
-      let valid = 0;
-      let malformed = 0;
-      for (const line of text.split("\n").filter(Boolean)) {
-        try {
-          const parsed = JSON.parse(line) as unknown;
-          if (this.isItem(parsed)) valid += 1;
-          else malformed += 1;
-        } catch {
-          malformed += 1;
-        }
-      }
-      return { path: this.path, valid, malformed, error: null };
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-        return { path: this.path, valid: 0, malformed: 0, error: null };
-      }
-      return {
-        path: this.path,
-        valid: 0,
-        malformed: 0,
-        error: error instanceof Error ? error.message : String(error),
-      };
-    }
-  }
-
-  async replace(items: T[]): Promise<void> {
-    await mkdir(dirname(this.path), { recursive: true });
-    const tmp = `${this.path}.tmp`;
-    await writeFile(
-      tmp,
-      items.map((item) => JSON.stringify(item)).join("\n") + (items.length ? "\n" : ""),
-      "utf8",
-    );
-    await rename(tmp, this.path);
-  }
-}

package/node_modules/@luxusai/pi-hindsight/extensions/queue/queue-delivery.ts

@@ -1,111 +0,0 @@
-import type { HindsightLikeClient, RetainJob } from "../types.js";
-
-export interface RetainDeliveryOutcome {
-  itemsCount?: number;
-  operationIds: string[];
-  tokens?: number;
-}
-
-export function redactQueueError(error: unknown): string {
-  const message = error instanceof Error ? error.message : String(error);
-  const text = message
-    .replace(/\b(Bearer\s+)[A-Za-z0-9._~+/=-]{12,}/gi, "$1[REDACTED]")
-    .replace(/\b(sk-[A-Za-z0-9_-]{12,})\b/g, "[REDACTED_API_KEY]")
-    .replace(/\b(ghp_[A-Za-z0-9_]{12,})\b/g, "[REDACTED_GITHUB_TOKEN]")
-    .replace(
-      /\b([A-Z0-9_]*(?:API_KEY|TOKEN|SECRET|PASSWORD)[A-Z0-9_]*\s*=\s*)[^\s\n"',}]+/gi,
-      "$1[REDACTED]",
-    )
-    .replace(
-      /\b((?:api[_-]?key|token|secret|password|authorization)\s*:\s*)["']?[^\s\n"',}]+["']?/gi,
-      "$1[REDACTED]",
-    )
-    .replace(
-      /(["'](?:api[_-]?key|token|secret|password|authorization)["']\s*:\s*)["'][^"']+["']/gi,
-      '$1"[REDACTED]"',
-    )
-    .replace(/\b((?:Cookie|Set-Cookie)\s*:\s*)[^\r\n]+/gi, "$1[REDACTED]")
-    .replace(/(https?:\/\/)([^\s/@]+):([^\s/@]+)@/gi, "$1[REDACTED]@");
-  return text.replace(/https?:\/\/[^\s"'<>]+/gi, (url) =>
-    url.replace(/([?&])([^=&#\s]+)=([^&#\s]+)/g, (match, separator, key) => {
-      if (!/(?:token|key|secret|password|api[_-]?key|apikey)/i.test(String(key))) {
-        return String(match);
-      }
-      return `${String(separator)}${String(key)}=[REDACTED]`;
-    }),
-  );
-}
-
-export function retainOptionsForJob(job: RetainJob) {
-  const async = job.item.async;
-  return {
-    context: job.item.context,
-    ...(job.item.timestamp ? { timestamp: job.item.timestamp } : {}),
-    ...(job.item.metadata ? { metadata: job.item.metadata } : {}),
-    ...(async !== undefined ? { async } : {}),
-    // Stable per queue job so async retain retries are idempotent (Hindsight operation_id).
-    ...(async === true ? { operationId: job.id } : {}),
-    ...(job.item.entities?.length ? { entities: job.item.entities } : {}),
-    ...(job.item.tags ? { tags: job.item.tags } : {}),
-    ...(job.item.observationScopes ? { observationScopes: job.item.observationScopes } : {}),
-    ...(job.item.documentTags ? { documentTags: job.item.documentTags } : {}),
-    ...(job.item.strategy ? { strategy: job.item.strategy } : {}),
-    documentId: job.documentId,
-    updateMode: job.updateMode,
-  };
-}
-
-export function operationIdsFromResponse(response: unknown): string[] {
-  if (!response || typeof response !== "object") return [];
-  const record = response as Record<string, unknown>;
-  const candidates = [record.operation_id, record.operationId, record.id];
-  const operationIds = candidates.filter(
-    (candidate): candidate is string => typeof candidate === "string" && candidate.length > 0,
-  );
-  const nested = record.operations;
-  if (Array.isArray(nested)) {
-    for (const item of nested) {
-      if (typeof item === "string") operationIds.push(item);
-      else if (item && typeof item === "object") {
-        const id =
-          (item as Record<string, unknown>).id ?? (item as Record<string, unknown>).operation_id;
-        if (typeof id === "string") operationIds.push(id);
-      }
-    }
-  }
-  const operationIdsArray = record.operation_ids ?? record.operationIds;
-  if (Array.isArray(operationIdsArray)) {
-    for (const item of operationIdsArray) {
-      if (typeof item === "string" && item.length > 0) operationIds.push(item);
-    }
-  }
-  return [...new Set(operationIds)];
-}
-
-function positiveNumber(value: unknown): number | undefined {
-  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
-}
-
-export function parseRetainOutcome(response: unknown): RetainDeliveryOutcome {
-  const operationIds = operationIdsFromResponse(response);
-  if (!response || typeof response !== "object") return { operationIds };
-  const record = response as Record<string, unknown>;
-  const usage =
-    record.usage && typeof record.usage === "object"
-      ? (record.usage as Record<string, unknown>)
-      : undefined;
-  const itemsCount = positiveNumber(record.items_count ?? record.itemsCount);
-  const tokens = usage ? positiveNumber(usage.total_tokens) : undefined;
-  return {
-    operationIds,
-    ...(itemsCount !== undefined ? { itemsCount } : {}),
-    ...(tokens !== undefined ? { tokens } : {}),
-  };
-}
-
-export async function deliverRetainJob(
-  client: HindsightLikeClient,
-  job: RetainJob,
-): Promise<unknown> {
-  return client.retain(job.bankId, job.item.content, retainOptionsForJob(job));
-}

package/node_modules/@luxusai/pi-hindsight/extensions/queue/queue-lock.ts

@@ -1,214 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
-
-const queueLocks = new Map<string, Promise<void>>();
-
-const LOCK_RETRY_MS = 25;
-const LOCK_TIMEOUT_MS = 5_000;
-const LOCK_STALE_MS = 30_000;
-
-export const RETAIN_QUEUE_LOCK = {
-  retryMs: LOCK_RETRY_MS,
-  timeoutMs: LOCK_TIMEOUT_MS,
-  staleMs: LOCK_STALE_MS,
-};
-
-export interface QueueLockOwner {
-  pid?: number;
-  acquiredAt?: string;
-  token?: string;
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-async function removeDirectory(path: string): Promise<void> {
-  await rm(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 10 });
-}
-
-async function writeQueueHeartbeat(lockPath: string, token: string): Promise<void> {
-  const heartbeatPath = `${lockPath}/heartbeat-${token}`;
-  const tmpPath = `${heartbeatPath}.${process.pid}.tmp`;
-  await writeFile(tmpPath, new Date().toISOString(), "utf8");
-  await rename(tmpPath, heartbeatPath);
-}
-
-async function writeQueueLockOwner(lockPath: string, token: string): Promise<void> {
-  const ownerPath = `${lockPath}/owner`;
-  const tmpPath = `${ownerPath}.${process.pid}.${token}.tmp`;
-  await writeFile(
-    tmpPath,
-    JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString(), token }),
-    "utf8",
-  );
-  await rename(tmpPath, ownerPath);
-  await writeQueueHeartbeat(lockPath, token);
-}
-
-function startQueueLockHeartbeat(lockPath: string, token: string): NodeJS.Timeout {
-  const heartbeatMs = Math.max(1, Math.min(5_000, Math.floor(RETAIN_QUEUE_LOCK.staleMs / 2)));
-  const heartbeat = setInterval(() => {
-    void writeQueueHeartbeat(lockPath, token).catch(() => undefined);
-  }, heartbeatMs);
-  heartbeat.unref?.();
-  return heartbeat;
-}
-
-export function isQueueLockOwnerStale(
-  owner: QueueLockOwner | undefined,
-  now = Date.now(),
-  staleMs = RETAIN_QUEUE_LOCK.staleMs,
-): boolean {
-  if (!owner) return true;
-  const acquiredAt = owner.acquiredAt ? Date.parse(owner.acquiredAt) : Number.NaN;
-  return !Number.isFinite(acquiredAt) || now - acquiredAt > staleMs;
-}
-
-async function readQueueLockOwner(lockPath: string): Promise<QueueLockOwner | undefined> {
-  try {
-    return JSON.parse(await readFile(`${lockPath}/owner`, "utf8")) as QueueLockOwner;
-  } catch {
-    return undefined;
-  }
-}
-
-async function isOwnerlessLockDirectoryStale(lockPath: string): Promise<boolean> {
-  try {
-    const info = await stat(lockPath);
-    return Date.now() - info.mtimeMs > RETAIN_QUEUE_LOCK.staleMs;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
-    return true;
-  }
-}
-
-async function isQueueLockStale(lockPath: string, owner: QueueLockOwner): Promise<boolean> {
-  if (!owner.token) return isQueueLockOwnerStale(owner);
-  try {
-    const heartbeat = await stat(`${lockPath}/heartbeat-${owner.token}`);
-    return Date.now() - heartbeat.mtimeMs > RETAIN_QUEUE_LOCK.staleMs;
-  } catch {
-    return isQueueLockOwnerStale(owner);
-  }
-}
-
-async function removeLockIfOwned(lockPath: string, token: string): Promise<void> {
-  const owner = await readQueueLockOwner(lockPath);
-  if (owner?.token === token) await removeDirectory(lockPath);
-}
-
-export function isQueueLockRaceError(error: unknown): boolean {
-  const code = (error as NodeJS.ErrnoException).code;
-  return code === "EEXIST" || code === "EPERM" || code === "ENOTEMPTY" || code === "EBUSY";
-}
-
-function staleClaimPath(lockPath: string): string {
-  return `${lockPath}.stale-claim`;
-}
-
-async function isStaleCleanupClaimActive(lockPath: string): Promise<boolean> {
-  const claimPath = staleClaimPath(lockPath);
-  try {
-    const info = await stat(claimPath);
-    if (Date.now() - info.mtimeMs <= RETAIN_QUEUE_LOCK.staleMs) return true;
-    await removeDirectory(claimPath);
-    return false;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
-    throw error;
-  }
-}
-
-async function withStaleCleanupClaim<T>(
-  lockPath: string,
-  fn: () => Promise<T>,
-): Promise<T | undefined> {
-  const claimPath = staleClaimPath(lockPath);
-  try {
-    await mkdir(claimPath, { recursive: false });
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "EEXIST") return undefined;
-    throw error;
-  }
-  try {
-    return await fn();
-  } finally {
-    await removeDirectory(claimPath);
-  }
-}
-
-async function removeLockIfStillStale(lockPath: string): Promise<boolean> {
-  return (
-    (await withStaleCleanupClaim(lockPath, async () => {
-      const owner = await readQueueLockOwner(lockPath);
-      const stale = owner
-        ? await isQueueLockStale(lockPath, owner)
-        : await isOwnerlessLockDirectoryStale(lockPath);
-      if (!stale) return false;
-      await removeDirectory(lockPath);
-      return true;
-    })) ?? false
-  );
-}
-
-async function acquireFileLock(path: string): Promise<() => Promise<void>> {
-  const lockPath = `${path}.lock`;
-  const started = Date.now();
-  await mkdir(dirname(path), { recursive: true });
-  while (true) {
-    if (await isStaleCleanupClaimActive(lockPath)) {
-      if (Date.now() - started > RETAIN_QUEUE_LOCK.timeoutMs)
-        throw new Error(`Timed out waiting for retain queue lock ${lockPath}`);
-      await sleep(RETAIN_QUEUE_LOCK.retryMs);
-      continue;
-    }
-    const token = randomUUID();
-    try {
-      await mkdir(lockPath, { recursive: false });
-      try {
-        await writeQueueLockOwner(lockPath, token);
-      } catch (error) {
-        await removeDirectory(lockPath);
-        if (["ENOENT", "EINVAL"].includes((error as NodeJS.ErrnoException).code ?? "")) continue;
-        throw error;
-      }
-      const heartbeat = startQueueLockHeartbeat(lockPath, token);
-      return async () => {
-        clearInterval(heartbeat);
-        await removeLockIfOwned(lockPath, token);
-      };
-    } catch (error) {
-      const code = (error as NodeJS.ErrnoException).code;
-      if (!isQueueLockRaceError(error)) throw error;
-      if (code === "EEXIST" && (await removeLockIfStillStale(lockPath))) continue;
-      if (Date.now() - started > RETAIN_QUEUE_LOCK.timeoutMs)
-        throw new Error(`Timed out waiting for retain queue lock ${lockPath}`);
-      await sleep(RETAIN_QUEUE_LOCK.retryMs);
-    }
-  }
-}
-
-export async function withQueueLock<T>(path: string, fn: () => Promise<T>): Promise<T> {
-  const previous = queueLocks.get(path) ?? Promise.resolve();
-  let release!: () => void;
-  const next = new Promise<void>((resolve) => {
-    release = resolve;
-  });
-  const lock = previous.catch(() => undefined).then(() => next);
-  queueLocks.set(path, lock);
-  await previous.catch(() => undefined);
-  let releaseFileLock: (() => Promise<void>) | undefined;
-  try {
-    releaseFileLock = await acquireFileLock(path);
-    return await fn();
-  } finally {
-    try {
-      if (releaseFileLock) await releaseFileLock();
-    } finally {
-      release();
-      if (queueLocks.get(path) === lock) queueLocks.delete(path);
-    }
-  }
-}