@volter/world-core 3.0.155 → 3.0.157

package/src/world-store.ts

@@ -30,6 +30,8 @@ import {
   existsSync,
   fsyncSync,
   fstatSync,
+  linkSync,
+  ftruncateSync,
   lstatSync,
   mkdirSync,
   openSync,
@@ -42,16 +44,87 @@ import {
   statSync,
   unlinkSync,
   writeFileSync,
+  writeSync,
 } from 'node:fs';
+import type { Dirent, Stats } from 'node:fs';
 import { hostname } from 'node:os';
+import { randomUUID } from 'node:crypto';
 import { refuseReadOnlyWrite } from './request-scope.ts';
 import { basename, dirname, join, resolve } from 'node:path';
 
+// WHAT A LOCK HOLD ASKS (architecture, "What a hold asks is counted"): the file
+// store's questions counted inside an outermost lock hold and outside one, said at each outermost release where
+// VOLTER_TWIN_LOG=1 (storage.ts twinLog's gate and line), and not counted otherwise. Each counter counts the calls of
+// its own method: a readKept that misses its kept text, or meets a link, also counts the read it makes. A hold's
+// `heldMs` is the time of the hold's body, run once the lock is taken and before it is released, as the lock's release
+// line times its hold; the wait before the take is the wait line's `waitedMs`.
+const QUESTION_KINDS = ['generation', 'read', 'readKept', 'stat', 'exists', 'list', 'append'] as const;
+type QuestionCounts = Record<(typeof QUESTION_KINDS)[number], number>;
+// Read once, where a process is: a realm with none counts nothing.
+const questionsCounted = typeof process !== 'undefined' && process.env?.VOLTER_TWIN_LOG === '1';
+const noQuestions = (): QuestionCounts => ({ generation: 0, read: 0, readKept: 0, stat: 0, exists: 0, list: 0, append: 0 });
+let lockHoldDepth = 0;
+let questionsHeld = noQuestions();
+let questionsUnheld = noQuestions();
+function asked(kind: (typeof QUESTION_KINDS)[number]): void {
+  if (questionsCounted) (lockHoldDepth > 0 ? questionsHeld : questionsUnheld)[kind] += 1;
+}
+function countedHold<T>(operation: string, fn: () => T): () => T {
+  if (!questionsCounted) return fn;
+  return () => {
+    const began = Date.now();
+    lockHoldDepth += 1;
+    try { return fn(); }
+    finally {
+      lockHoldDepth -= 1;
+      if (lockHoldDepth === 0) {
+        const held = questionsHeld, before = questionsUnheld;
+        questionsHeld = noQuestions(); questionsUnheld = noQuestions();
+        try { console.error('[twin:store-lock]', JSON.stringify({ operation, heldMs: Date.now() - began, held, before })); } catch { /* an instrument */ }
+      }
+    }
+  };
+}
+
 /** Metadata a caller needs about a stored path. `isDirectory` distinguishes a JSON
  *  sidecar from a per-service subdir (validate/scrub walk on it); `size`+`mtimeMs`
  *  drive the append-dedupe index's cache-validity check in storage.ts. */
 export type WorldStat = { size: number; mtimeMs: number; isDirectory: boolean; isSymbolicLink?: boolean };
 
+/** Diagnostic context only; it does not change lock acquisition or stale-owner policy. */
+export type WorldLockOptions = { retainLiveOwner?: boolean; operation?: string; caller?: string };
+
+/**
+ * Capture at the outermost lock helper, then carry the same caller through nested helpers.
+ * LIMIT THE CAPTURE TO THE FRAMES READ (browser-substrate S2 R44, AC-LC3): V8's third frame supplies the caller,
+ * while new Error().stack normally collects up to Error.stackTraceLimit frames (ten by default).
+ * Retained browser-substrate LibreChat World-realm warm-up profiles 73/74 from runs 36c6d279 and 991f63e7e
+ * attributed about 10-57 ms self/inclusive to storageLockScope over each full 13.3-13.4 second profile window.
+ * Samples are about 5 ms apart. Those totals include this helper's capture, string and regex work; they are
+ * neither isolated capture time nor the credential doors' share. The co-located host serves doors on one loop.
+ * Original profiles are under /Users/aaronclaw/heavy-lead/librechat/logs-kept/:
+ * librechat-sn-36c6d279-e9e2632a-004051/cpuprofile/ (SHA256 prefixes 04dfc4fe, 77df6e8e) and
+ * librechat-sn-991f63e7e/cpuprofile/ (be6c6a93, 2fe80e7c), realms 73 and 74 respectively.
+ * The limit is lowered to three only for Error's own writable numeric data property above three, and restored
+ * only when lowered. Absent, accessor, non-writable and lower limits receive no writes. Existing constructor
+ * and user stack-formatter failure paths remain; this diagnostic optimization changes no lock ownership rule.
+ */
+export function storageLockScope(options: WorldLockOptions = {}): WorldLockOptions & { operation: string; caller: string } {
+  let frame: string | undefined;
+  if (!options.caller) {
+    const held = Object.getOwnPropertyDescriptor(Error, 'stackTraceLimit');
+    const lowered = held !== undefined && 'value' in held && held.writable === true
+      && typeof held.value === 'number' && held.value > 3;
+    if (lowered) Error.stackTraceLimit = 3;
+    try { frame = new Error().stack?.split('\n')[3]; }
+    finally { if (lowered) Error.stackTraceLimit = held!.value as number; }
+  }
+  const location = frame?.slice(frame.lastIndexOf('(') + 1).trim().replace(/^at\s+/, '');
+  const site = location?.match(/^(.*):(\d+):\d+\)?$/);
+  const caller = options.caller ?? (site ? `${site[1]!.replace(/^file:\/\//, '')}:${site[2]}` : 'unknown:0');
+  return { ...options, caller, operation: options.operation ?? caller };
+}
+
 /**
  * The synchronous persistence seam. Every path is an ABSOLUTE key the caller already
  * computed (via `worldPaths`/`worldStateRoot`); the store treats it as an opaque key,
@@ -92,12 +165,31 @@ export interface WorldStore {
   readRange?(path: string, start: number): string | null;
   /** Resolve filesystem aliases for durable ownership; absent on opaque-key stores. */
   canonicalPath?(path: string): string;
+  /** `read`, for a small file every operation needs and few change (a branch's pointer, the World's clock): the text
+   *  kept from the last read while the path's own facts stand, so an unchanged file costs one check and no read.
+   *  Optional: a store without it is read. */
+  readKept?(path: string): string | null;
+  /** The facts of the generation kept beside a tree's files in `dirPath` (TREE_FILES): one string that differs after
+   *  any write of one of them through a store, by this process or another; `null` where the directory has none yet,
+   *  which says nothing. Optional: a store without it is asked for each file's own facts. */
+  generation?(dirPath: string): string | null;
+  /** The generation in `dirPath` now, when exactly one write of a tree's file through a store has moved it since
+   *  `before` (a generation this store answered for it); `null` when it cannot say so. A writer that read `before` just
+   *  ahead of its own write, holding the directory's history lock, learns that its write was the only one (log.ts
+   *  appendToBranchLog). Optional, beside `generation`. */
+  generationAfterOwnWrite?(dirPath: string, before: string): string | null;
   /** Run `fn` holding an exclusive lock on `lockPath`, releasing it afterwards. The fs
    *  backend uses the historical cross-process reclaimable file lock; an in-memory,
    *  single-instance backend is a synchronous pass-through. */
-  withLock<T>(lockPath: string, fn: () => T, options?: { retainLiveOwner?: boolean }): T;
+  withLock<T>(lockPath: string, fn: () => T, options?: WorldLockOptions): T;
 }
 
+/** The files a service's tree is folded from, by name in its state directory (log.ts: the parent log, the branch log,
+ *  the branch's pointer), and the generation a store keeps beside them. */
+export const TREE_FILES = { parent: 'events.jsonl', branch: 'actions.jsonl', pointer: 'branch.json' } as const;
+export const TREE_GENERATION = 'tree.generation';
+const TREE_FILE_NAMES: ReadonlySet<string> = new Set(Object.values(TREE_FILES));
+
 // ── FsWorldStore — the DEFAULT, byte-identical to the historical node:fs behavior ────
 
 let fsAtomicSequence = 0;
@@ -105,17 +197,359 @@ let fsAtomicSequence = 0;
 /** How long a lock may live before an acquirer treats it as abandoned. Above the 10s
  *  wait timeout so a live-but-slow holder is never reclaimed out from under itself. */
 const LOCK_STALE_MS = 60_000;
+/**
+ * How long an EMPTY lock file is a taker's, between its exclusive create and its holder's record (S2 R13). A taker
+ * writes the record in the call after the create (in a tab's file step, in the same request), and one whose record is
+ * not written gives the lock up and takes it again (withLock), so no live holder holds a lock with an empty record past
+ * that moment. An empty file older than this is a taker's that ended between the two calls (a process killed there,
+ * or a state directory copied while one was there), and it is no one's: before, it was waited on until its file was
+ * 60 s old, and a lock taken to keep its live owner (the ancestry coordinator) waited on it for ever. Twenty e946aa4c
+ * dry-run1: a 0-byte branch-ancestry.lock, the Redis twin's every write waiting 10 s on it inside its history lock,
+ * and Twenty's Redis client's 5 s connect timing out (FindAllViews 500, the walk's step 7).
+ */
+// Five seconds: in a tab without the kernel's file step the create and the record are two requests of the kernel,
+// and Twenty's Redis-twin handoffs have exceeded 1 s; and under the 10 s a
+// waiter waits before it gives up, so a waiter reclaims such a file rather than timing out on it.
+const EMPTY_RECORD_GRACE_MS = 5_000;
+/** How many takes whose record could not be written are made before the failure is the caller's. */
+const RECORD_ATTEMPTS = 3;
+
+type LockHolder = {
+  pid: number; hostname: string; at: string; token?: string;
+  operation?: string; caller?: string;
+  waitingFor?: { path: string; operation: string; since: number };
+};
+
+/** The locks this process holds now, by path, and the token each was recorded with (withLock). */
+const ownLocks = new Map<string, string>();
 
-type LockHolder = { pid: number; hostname: string; at: string };
+type LockReading = {
+  /** The take's descriptor; null where a kernel's file step took it (fileSteps) and kept none. */
+  path: string; fd: number | null; holder: LockHolder;
+  /** The bytes of the record the descriptor last wrote: a shorter one is padded to it (recordLockReading). */
+  recordBytes?: number;
+  nestedWaits: Map<string, { path: string; operation: string; waitedMs: number }>;
+};
+const lockReadings: LockReading[] = [];
+
+/**
+ * A KERNEL'S FILE STEPS (S2 R17d), where this process runs in a tab: browser-substrate's KernelVirtualFS offers them
+ * on the run's tree (`process[Symbol.for('tabnode.run.vfs')]`, under `Symbol.for('browser-substrate.kernel-file-steps')`),
+ * each one request of the kernel's worker that makes, by its own calls in the same order, what this store made as
+ * requests of their own: a lock's take (an exclusive create, its holder's record, a close), its release (the record
+ * read, its token compared, the unlink: SYS_unlink's, with the parent's permission and sticky-bit checks the path
+ * unlink it replaces did not make) and a tree file's append between its generation's two bytes. A write of a
+ * twin took three locks and an append, about thirty requests; these make it seven. Each step answers undefined where
+ * it is not taken (a path the tab keeps outside the kernel, parts too large for one request), and this store then
+ * makes its own calls. Absent on a host's filesystem, which is asked as before.
+ */
+type KernelFileSteps = {
+  createExclusive(path: string, data: string, mode: number): boolean | undefined;
+  changeHolding(path: string, needle: string, replacement: string | undefined): { changed: true } | { changed: false; observed: string | null } | undefined;
+  appendBetween(markerPath: string, marker: string, path: string, data: string): boolean;
+};
+function fileSteps(): KernelFileSteps | undefined {
+  const tree = (process as unknown as Record<symbol, unknown>)[Symbol.for('tabnode.run.vfs')] as Record<symbol, unknown> | null | undefined;
+  const offered = tree?.[Symbol.for('browser-substrate.kernel-file-steps')];
+  return offered && typeof offered === 'object' ? offered as KernelFileSteps : undefined;
+}
+/** The bytes a holder's record holds for its token, as JSON.stringify writes them: a key and a string, no space. */
+const tokenNeedle = (token: string): string => `"token":${JSON.stringify(token)}`;
+
+/** A two-call take whose path did not hold its own record after it: another reclaimed it between the calls. */
+const RECLAIMED_BEFORE_RECORD = 'VOLTER_LOCK_RECLAIMED';
+/** A take whose record could not be written whole: nothing of it is held. */
+const RECORD_NOT_WRITTEN = 'VOLTER_LOCK_UNRECORDED';
+/** Where link(2) is not an exclusive create the store can use: the take falls back to two calls. */
+const LINK_UNSUPPORTED = new Set(['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EXDEV', 'EMLINK', 'EINVAL']);
+
+/**
+ * A FILE MADE EXCLUSIVELY WITH ITS RECORD ALREADY IN IT (S2 R13): a lock, or a lock's reclaim record, is never seen
+ * empty while its taker lives, so an empty one is always a dead taker's and is reclaimed (lockIsStale, recoveryIsStale).
+ *  - In a tab: the kernel's file step makes it and writes the record in one request (fileSteps, S2 R17d).
+ *  - On a host: the record is written whole to a private file of the same directory, which link(2) puts at the path,
+ *    an exclusive create that fails EEXIST; the private name is then removed. The lock is opened for its descriptor.
+ *    Never in a tab: tabnode's link copies over the path (no EEXIST), so it is no exclusive create there.
+ *  - Neither (a tab whose kernel offers no step for the path, a host filesystem without link): two calls, the
+ *    exclusive create and the record, and the path read back: held only if it holds this take's token. A record that
+ *    is not written leaves the file removed only where it is still empty or this take's (read before it is removed).
+ * EEXIST is thrown as the create's; RECLAIMED_BEFORE_RECORD and RECORD_NOT_WRITTEN say a take not held.
+ */
+function createRecorded(path: string, text: string, token: string, operation: string | undefined): { fd: number | null; bytes: number } {
+  const bytes = Buffer.byteLength(text);
+  const steps = fileSteps();
+  const stepped = steps?.createExclusive(path, text, 0o666);
+  if (stepped === true) return { fd: null, bytes };
+  if (stepped === false) {
+    // made in that one request and its record short. Removed only while the path still holds that short record (a
+    // prefix of this take's own text) or nothing: a stall past the grace may have let another reclaim it and take it
+    lockRecordLine('publish-failed', path, { operation });
+    let held: string | undefined;
+    try { held = readFileSync(path, 'utf8'); } catch { held = undefined; }
+    if (held !== undefined && (held === '' || text.startsWith(held))) { try { unlinkSync(path); } catch { /* gone */ } }
+    throw Object.assign(new Error(`${path}: its record was not written whole`), { code: RECORD_NOT_WRITTEN });
+  }
+  const inTab = (process as unknown as Record<symbol, unknown>)[Symbol.for('tabnode.run.vfs')] !== undefined;
+  if (!inTab) {
+    const temporary = `${path}.take.${process.pid}.${randomUUID()}`;
+    let linked = false;
+    try {
+      writeFileSync(temporary, text, { flag: 'wx' });
+      try { linkSync(temporary, path); linked = true; }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'EEXIST') sweepTakeFiles(path);
+        if (!LINK_UNSUPPORTED.has((error as NodeJS.ErrnoException).code ?? '')) throw error;
+      }
+    } finally { try { unlinkSync(temporary); } catch { /* not made, or gone */ } }
+    if (linked) {
+      let fd: number | null = null;
+      try { fd = openSync(path, 'r+'); } catch { fd = null; /* held; its record is then not rewritten */ }
+      return { fd, bytes };
+    }
+  }
+  const fd = openSync(path, 'wx');
+  try { writeFileSync(fd, text); }
+  catch (error) {
+    lockRecordLine('publish-failed', path, { fd, operation }, error);
+    try { closeSync(fd); } catch { /* not held */ }
+    let held = '';
+    try { held = readFileSync(path, 'utf8'); } catch { held = 'gone'; }
+    if (held === '' || held.includes(tokenNeedle(token))) { try { unlinkSync(path); } catch { /* gone */ } }
+    throw Object.assign(new Error(`${path}: its record could not be written`), { code: RECORD_NOT_WRITTEN, cause: error });
+  }
+  if (readLockHolder(path)?.token !== token) {
+    lockRecordLine('take-reclaimed-before-record', path, { fd, operation });
+    try { closeSync(fd); } catch { /* not held */ }
+    throw Object.assign(new Error(`${path}: reclaimed before its record`), { code: RECLAIMED_BEFORE_RECORD });
+  }
+  return { fd, bytes };
+}
 
-function readLockHolder(lockPath: string): LockHolder | null {
+/**
+ * A take's private file a process left at a crash between its link and its removal (`<lock>.take.<pid>.<uuid>`):
+ * removed where older than the grace, once a process per lock, when its take meets the lock held. It holds nothing.
+ */
+const sweptTakes = new Set<string>();
+function sweepTakeFiles(path: string): void {
+  if (sweptTakes.has(path)) return;
+  sweptTakes.add(path);
+  const prefix = `${basename(path)}.take.`;
   try {
-    return JSON.parse(readFileSync(lockPath, 'utf8')) as LockHolder;
-  } catch {
+    for (const name of readdirSync(dirname(path))) {
+      if (!name.startsWith(prefix)) continue;
+      const at = join(dirname(path), name);
+      try { if (Date.now() - statSync(at).mtimeMs > EMPTY_RECORD_GRACE_MS) unlinkSync(at); } catch { /* gone, or another's to remove */ }
+    }
+  } catch { /* an instrument of tidiness: nothing waits on it */ }
+}
+
+/** A file createRecorded made, let go: its descriptor closed, and the path removed only while it holds the token. */
+function releaseRecorded(path: string, token: string, fd: number | null): void {
+  if (fd !== null) { try { closeSync(fd); } catch { /* released below */ } }
+  try {
+    const released = fd === null ? fileSteps()?.changeHolding(path, tokenNeedle(token), undefined) : undefined;
+    if (released?.changed) return;
+    if (released === undefined && readLockHolder(path)?.token === token) unlinkSync(path);
+  } catch (error) { lockRecordLine('release-failed', path, {}, error); }
+}
+
+/**
+ * A leftover reclaim record (`.recovery`) no reclaimer is behind (S2 R13 review): empty, or recorded by a process of
+ * this host that is not alive, and older than EMPTY_RECORD_GRACE_MS. It held every waiter of its lock until each
+ * timed out, as an empty lock file did.
+ */
+function recoveryIsStale(recoveryPath: string): boolean {
+  let file: Stats;
+  try { file = statSync(recoveryPath); } catch { return false; }
+  if (Date.now() - file.mtimeMs <= EMPTY_RECORD_GRACE_MS) return false;
+  if (file.size === 0) return true;
+  const holder = readLockHolder(recoveryPath);
+  return holder !== null && holder.hostname === ownHostname() && Number.isInteger(holder.pid) && !pidAlive(holder.pid);
+}
+
+/**
+ * A WORLD'S CARRIED LOCKS, REMOVED AT ITS OPEN (S2 K4). A World booted over its kept state (`up --keep-state`, a
+ * tab's restored archive) carries whatever lock files its last life left in its services' state directories. One whose
+ * holder record cannot be read is no holder's once its taker has gone, and a restore gives it the restore's file time,
+ * so the empty-record grace and the 60 s age ran from the restore: every waiter waited them, or gave up at 10 s (Twenty
+ * e946aa4c run 2: anthropic's projection.lock, "holder record unreadable", 10,086 ms, then its credentials 500 and the
+ * server 10 s late). A carried `.recovery` that is not empty and does not parse was never ended by R13's rule at all.
+ *
+ * A file is carried only when all of these hold: it is a world-core lock or its reclaim record (`*.lock`,
+ * `*.lock.recovery`) in a service's state directory (`<root>/<service>/<stateDir>/world`, never a yarn.lock or any
+ * project file); its text is empty or a holder record's beginning (`{"pid"`) that does not parse; and its file time is
+ * before `before`, the start of this boot's claim. A restore sets the time before the claim; a taker that is live now
+ * (a CLI's changeset rebase, a branch World keeping this one as its parent's storage, a two-call taker between its
+ * create and its record) made its file after it. Each removal is still a reclaimer's: a lock's under its `.recovery`,
+ * taken with its record (createRecorded), a held `.recovery` skipped; the file read again, renamed aside, the aside copy
+ * read again and linked back where it now holds a record (EEXIST there is the path taken since, left to its holder).
+ * A record that parses is kept, under its rules (a dead holder's, our own pid's, the 60 s age, which a restore resets:
+ * not this rule's). Answers the paths removed.
+ */
+export function removeCarriedLocks(roots: readonly string[], options: { stateDir: string; before: number }): string[] {
+  const removed: string[] = [];
+  const isHolder = (text: string): boolean => Number.isInteger(lockHolderOf('', text)?.pid);
+  const carriedText = (text: string): boolean => {
+    const trimmed = text.trim();
+    return trimmed === '' || (trimmed.startsWith('{"pid"') && !isHolder(trimmed));
+  };
+  /** The file's text where it is carried now (small, older than the claim, unreadable as a record); else undefined. */
+  const carriedNow = (path: string): string | undefined => {
+    try {
+      const file = statSync(path);
+      if (file.size > 1024 || !(file.mtimeMs < options.before)) return undefined;
+      const text = readFileSync(path, 'utf8');
+      return carriedText(text) ? text : undefined;
+    } catch { return undefined; }
+  };
+  /** Renamed aside, read again, put back where a taker recorded itself meanwhile; true when it is gone. */
+  const setAside = (path: string, text: string): boolean => {
+    const aside = `${path}.carried.${process.pid}.${randomUUID()}`;
+    try { renameSync(path, aside); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') lockRecordLine('carried-rename-failed', path, {}, error); return false; }
+    let after: string | undefined;
+    try { after = readFileSync(aside, 'utf8'); } catch { after = undefined; }
+    if (after !== undefined && isHolder(after)) {
+      try { linkSync(aside, path); lockRecordLine('carried-restored', path, {}); }
+      catch (error) { lockRecordLine((error as NodeJS.ErrnoException).code === 'EEXIST' ? 'carried-retaken' : 'carried-restore-failed', path, {}, error); }
+      try { unlinkSync(aside); } catch (error) { lockRecordLine('carried-unlink-failed', aside, {}, error); }
+      return false;
+    }
+    storageLockLine(`[world] carried storage lock renamed aside at open path=${path} bytes=${Buffer.byteLength(text)}`);
+    try { unlinkSync(aside); } catch (error) { lockRecordLine('carried-unlink-failed', aside, {}, error); }
+    return true;
+  };
+  const removeLock = (path: string): void => {
+    const recoveryPath = `${path}.recovery`, recoveryToken = randomUUID();
+    let recovery: { fd: number | null };
+    try { recovery = createRecorded(recoveryPath, `${JSON.stringify({ pid: process.pid, hostname: ownHostname(), at: new Date().toISOString(), token: recoveryToken })}\n`, recoveryToken, 'carried lock removal'); }
+    catch { return; } // a reclaimer is at work, or the recovery is carried too and goes first (visit)
+    try {
+      const text = carriedNow(path);
+      if (text !== undefined && setAside(path, text)) removed.push(path);
+    } finally { releaseRecorded(recoveryPath, recoveryToken, recovery.fd); }
+  };
+  const visit = (directory: string, depth: number): void => {
+    let entries: Dirent[];
+    try { entries = readdirSync(directory, { withFileTypes: true }); } catch { return; }
+    // A directory's carried reclaim records go first: a lock's removal is made under its `.recovery`.
+    const files = entries.filter((entry) => entry.isFile()).map((entry) => entry.name);
+    for (const name of files.filter((name) => name.endsWith('.lock.recovery'))) {
+      const path = join(directory, name), text = carriedNow(path);
+      if (text !== undefined && setAside(path, text)) removed.push(path);
+    }
+    for (const name of files.filter((name) => name.endsWith('.lock'))) {
+      const path = join(directory, name);
+      if (carriedNow(path) !== undefined) removeLock(path);
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory() && depth < 8 && entry.name !== 'node_modules' && entry.name !== '.git') visit(join(directory, entry.name), depth + 1);
+    }
+  };
+  // Only the services' state directories (`<root>/<service>/<stateDir>/world`, and `<root>/<stateDir>/world`): never a
+  // service's own data beside them (a PostgreSQL cluster, a project tree).
+  for (const root of roots) {
+    const states = [join(root, options.stateDir, 'world')];
+    try { for (const entry of readdirSync(root, { withFileTypes: true })) if (entry.isDirectory()) states.push(join(root, entry.name, options.stateDir, 'world')); }
+    catch { continue; }
+    for (const state of states) if (existsSync(state)) visit(state, 0);
+  }
+  return removed;
+}
+
+/** This host's name. In a tab (where the kernel's file steps are offered) it is read once per process: every take
+ *  records it, and each read was a request of the kernel (its UTS); a tab's process renamed while it runs keeps
+ *  recording, and comparing, the name it started with. On a host it is read live, as before: there a rename
+ *  (name.local -> name-2.local on macOS) must reach lockIsStale's comparison, or a dead holder recorded under the new
+ *  name is never reclaimed, and the read costs no request. */
+let hostnameRead: string | undefined;
+const ownHostname = (): string => (fileSteps() ? (hostnameRead ??= hostname()) : hostname());
+
+function recordLockReading(reading: LockReading): void {
+  try {
+    const text = `${JSON.stringify(reading.holder)}\n`;
+    // a take with no descriptor rewrites its record by path, and only while the file still holds its token: a file a
+    // stale sweep reclaimed and another made is never written over (the descriptor wrote the reclaimed file's own)
+    if (reading.fd === null) { fileSteps()?.changeHolding(reading.path, tokenNeedle(reading.holder.token!), text); return; }
+    // Padded with spaces to the record it replaces, which JSON allows after a value: a write that ends early leaves the
+    // new record's text over the old one's, never a shorter file with the old one's tail (malformed, and a malformed
+    // record keeps the 60 s rule, which a coordinator's live-owner lock never reaches).
+    const bytes = Buffer.byteLength(text), padded = reading.recordBytes !== undefined && bytes < reading.recordBytes
+      ? `${text.slice(0, -1)}${' '.repeat(reading.recordBytes - bytes)}\n` : text;
+    writeSync(reading.fd, padded, 0, 'utf8');
+    ftruncateSync(reading.fd, Buffer.byteLength(padded));
+    reading.recordBytes = Buffer.byteLength(padded);
+  } catch (error) {
+    lockRecordLine('rewrite-failed', reading.path, { fd: reading.fd, operation: reading.holder.operation }, error);
+  }
+}
+
+function storageLockLine(line: string): void {
+  try { console.warn(`${line.replace(/[\r\n]/g, ' ')} at=${Date.now()}`); } catch { /* an instrument */ }
+}
+
+/** Failure-only ownership evidence, on the same channel as the existing hold and reclaim warnings. */
+function lockRecordLine(stage: string, path: string, fields: Record<string, unknown>, error?: unknown): void {
+  try {
+    const cause = error as { name?: unknown; code?: unknown } | null | undefined;
+    console.warn('[world-storage-lock]', JSON.stringify({
+      at: Date.now(), stage, path, pid: process.pid, hostname: ownHostname(), ...fields,
+      ...(typeof cause?.name === 'string' ? { error: cause.name } : {}),
+      ...(typeof cause?.code === 'string' ? { code: cause.code } : {}),
+    }));
+  } catch { /* an instrument must not change the lock's result */ }
+}
+
+/** Name a bookkeeping phase within an existing acquisition; never acquire another lock. */
+export function withStorageLockOperation<T>(path: string, operation: string, fn: () => T): T {
+  let reading: LockReading | undefined;
+  for (let i = lockReadings.length - 1; i >= 0; i -= 1) {
+    if (lockReadings[i].path === path) { reading = lockReadings[i]; break; }
+  }
+  if (!reading) return fn();
+  const previous = reading.holder.operation;
+  reading.holder.operation = operation;
+  recordLockReading(reading);
+  try { return fn(); }
+  finally { reading.holder.operation = previous; recordLockReading(reading); }
+}
+
+/** A path that is not there: no such entry, or a part of it that is not a directory. */
+const absent = (error: unknown): boolean => { const code = (error as NodeJS.ErrnoException | null)?.code; return code === 'ENOENT' || code === 'ENOTDIR'; };
+
+function readLockHolder(lockPath: string, diagnostic?: 'timeout' | 'release'): LockHolder | null {
+  let text: string;
+  try {
+    text = readFileSync(lockPath, 'utf8');
+  } catch (error) {
+    if (diagnostic) lockRecordLine('read-failed', lockPath, { during: diagnostic }, error);
+    return null;
+  }
+  return lockHolderOf(lockPath, text, diagnostic);
+}
+
+/** A record's text as its holder (readLockHolder's parse); `null` text is no file, read as readLockHolder reads one. */
+function lockHolderOf(lockPath: string, text: string | null, diagnostic?: 'timeout' | 'release'): LockHolder | null {
+  if (text === null) {
+    if (diagnostic) lockRecordLine('read-failed', lockPath, { during: diagnostic, code: 'ENOENT' });
+    return null;
+  }
+  try {
+    return JSON.parse(text) as LockHolder;
+  } catch (error) {
+    if (diagnostic) lockRecordLine('parse-failed', lockPath, { during: diagnostic, bytes: Buffer.byteLength(text) }, error);
     return null; // missing, empty (mid-write), or malformed
   }
 }
 
+/** The same ownership account reaches a timeout's client as the storage trace. */
+function lockHolderMessage(holder: LockHolder | null): string {
+  if (!holder) return ' (holder record unreadable)';
+  const since = typeof holder.at === 'string' ? Date.parse(holder.at) : NaN;
+  const wait = holder.waitingFor;
+  return ` (held by pid ${holder.pid} on ${holder.hostname}${Number.isFinite(since) ? ` for ${Date.now() - since}ms` : ''}; token=${holder.token ?? '?'} operation=${holder.operation ?? 'unknown'} caller=${holder.caller ?? 'unknown'}${wait ? ` waitingFor=${wait.path} waitingOperation=${wait.operation} waitingSince=${wait.since}` : ''})`;
+}
+
 function pidAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
@@ -126,16 +560,28 @@ function pidAlive(pid: number): boolean {
   }
 }
 
-/** A lock is stale when its holder is provably gone (same host + dead pid) or it has
- *  outlived LOCK_STALE_MS. The age falls back to the lockfile's own mtime when the
- *  `at` record is unreadable — so a writer that crashed between creating the lock and
- *  recording itself is still eventually reclaimed, while a freshly-created (recent
- *  mtime) empty lock is left alone, avoiding a race with the live writer. */
+/** A lock is stale when its holder is provably gone (same host + dead pid), when its file is empty past
+ *  EMPTY_RECORD_GRACE_MS (a taker that ended before recording itself; a live holder never holds an empty record), or
+ *  when it has outlived LOCK_STALE_MS. The age falls back to the lockfile's own mtime when the `at` record is
+ *  unreadable, while a freshly-created (recent mtime) empty lock is left alone, avoiding a race with the live writer. */
 function lockIsStale(lockPath: string, retainLiveOwner = false): boolean {
   const holder = readLockHolder(lockPath);
-  if (holder && holder.hostname === hostname() && Number.isInteger(holder.pid) && !pidAlive(holder.pid)) {
+  if (holder && holder.hostname === ownHostname() && Number.isInteger(holder.pid) && !pidAlive(holder.pid)) {
+    return true;
+  }
+  // A lock recorded under THIS process that this process does not hold now is no holder's: a release that could not
+  // remove its file, or an earlier process numbered as this one (a tab numbers its processes the same at each boot,
+  // and a World's state outlives them). Waiting on it was waiting on ourselves: Twenty 46's Redis twin, pid 10013,
+  // timed out on `actions.jsonl.lock` "held by pid 10013" and exited.
+  if (holder && holder.hostname === ownHostname() && holder.pid === process.pid && ownLocks.get(lockPath) !== holder.token) {
     return true;
   }
+  // An empty record past its grace names no holder, alive or not (EMPTY_RECORD_GRACE_MS): asked before the live
+  // owner's rule, which keeps a lock whose record says who holds it, and an empty one says no one.
+  if (!holder) {
+    try { const file = statSync(lockPath); if (file.size === 0 && Date.now() - file.mtimeMs > EMPTY_RECORD_GRACE_MS) return true; }
+    catch { return false; }
+  }
   if (retainLiveOwner) return false;
   const recordedAt = holder && typeof holder.at === 'string' ? Date.parse(holder.at) : NaN;
   let stamp = recordedAt;
@@ -160,14 +606,104 @@ function sleepSync(ms: number): void {
  * file lock — so the existing twins and the conformance suite are unaffected.
  */
 export class FsWorldStore implements WorldStore {
+  // ONE CALL OF THE FILE SYSTEM FOR ONE QUESTION. Each of these asked whether the path exists and then asked again
+  // for what it wanted; `stat` asked three times. A process on a host pays microseconds for that. A twin in a tab
+  // pays a kernel exchange for each, and a tree's stamp is a handful of these on every operation: Twenty's Redis twin
+  // spent 54 s of 136 in `existsSync` and `statSync` under `treeStamp`, and its server's requests waited on it.
   read(path: string): string | null {
-    if (!existsSync(path)) return null;
-    return readFileSync(path, 'utf8');
+    asked('read');
+    try { return readFileSync(path, 'utf8'); }
+    catch (error) { if (absent(error)) return null; throw error; }
+  }
+
+  /**
+   * A small file's text, kept while its own facts stand. THE GUARANTEE: the key is the path's own lstat (device,
+   * inode, size, modification and change times); this process's own writes through the store drop what is kept at
+   * once; another process's write is seen when any of those facts moves. That is the guarantee a tree's stamp
+   * already rests on for its logs (their size and modification time), with the inode and change time added: a
+   * replaced file (writeAtomic) is another inode, a file written in place has another time. What it cannot see is a
+   * rewrite to the same size on the same or a reused inode within one tick of the file system's clock, with no check
+   * between; the logs' stamp has the same limit. A link is read through, and not kept.
+   * A text read after a write that came between the lstat and the read is kept under the OLDER key, so the next
+   * check finds the facts moved and reads again: what is kept is never newer than its key, and never served past it.
+   */
+  private readonly kept = new Map<string, { key: string; text: string }>();
+  readKept(path: string): string | null {
+    asked('readKept');
+    // A missing file is asked for without an error being made of it: a World with no parent has no branch.json, and
+    // every stamp asks.
+    let own: Stats | undefined;
+    try { own = lstatSync(path, { throwIfNoEntry: false }); }
+    catch (error) { if (!absent(error)) throw error; }
+    if (!own) { this.kept.delete(path); return null; }
+    if (own.isSymbolicLink()) return this.read(path);
+    const key = `${own.dev}:${own.ino}:${own.size}:${own.mtimeMs}:${own.ctimeMs}`;
+    const held = this.kept.get(path);
+    if (held && held.key === key) return held.text;
+    const text = this.read(path);
+    if (text === null) { this.kept.delete(path); return null; }
+    this.kept.set(path, { key, text });
+    return text;
+  }
+
+  /**
+   * A TREE'S GENERATION: one file beside a tree's three files, a byte longer after every write of any of them, so a
+   * reader that has the tree's stamp asks ONE question to know it still stands (log.ts treeFacts), where it asked
+   * three, two of them of files a World with no parent does not have.
+   *
+   * WHAT MAKES IT SOUND. A writer appends a byte BEFORE its write and another AFTER it; a reader takes the
+   * generation's facts BEFORE it reads the files' own. The file only grows, so its size never repeats on one inode,
+   * and a replaced or removed file is another inode or none. So for any write W and any reader that kept a stamp S
+   * under generation G: if W's first byte is after G was read, the kept G is behind and S is not served; if it is
+   * before, then either W itself was before S's own reads (S holds it), or W's second byte is after G was read, and
+   * again G is behind. An append is one call the system orders among all writers: each byte is one append of its
+   * own, whole or not at all, on a POSIX filesystem and in a tab's one kernel (browser-substrate
+   * packages/node/src/kernel-virtual-filesystem.ts appendFileSync, an O_APPEND open and writeAll, which sends a write
+   * of at most DATA_BYTES as one SYS_write request the kernel serves whole; or, by a file step, its table's own
+   * O_APPEND open and write of the one byte, filesystem.ts appendFileBytes). The proof rests on that; log.ts
+   * appendToBranchLog's (`generationAfterOwnWrite`: one write is exactly two bytes) as well.
+   *
+   * WHERE THAT STOPS. (1) A writer that dies between its write and its second byte, with a reader's whole check
+   * between its first byte and its write: that reader keeps the older stamp until the next write of the tree. (2) A
+   * writer of these files that does not come through a store of this version (an older package, a copy made over a
+   * live directory by another program): the generation does not move. A directory made or removed whole has no
+   * generation or another's, which serves nothing kept. (3) A stamp that names files outside its own directory (a
+   * World with a parent: its view and its ancestors' logs) is never kept under a generation (log.ts).
+   */
+  generation(dirPath: string): string | null {
+    asked('generation');
+    let own: Stats | undefined;
+    try { own = lstatSync(join(dirPath, TREE_GENERATION), { throwIfNoEntry: false }); }
+    catch (error) { if (!absent(error)) throw error; }
+    if (!own || !own.isFile()) return null;
+    return `${own.dev}:${own.ino}:${own.size}:${own.mtimeMs}:${own.ctimeMs}`;
+  }
+
+  /** One write is `moved` twice, a byte each: the same file, those two bytes longer. */
+  generationAfterOwnWrite(dirPath: string, before: string): string | null {
+    const now = this.generation(dirPath);
+    if (now === null) return null;
+    const [dev, ino, size] = before.split(':'), [nowDev, nowIno, nowSize] = now.split(':');
+    return nowDev === dev && nowIno === ino && Number(nowSize) === Number(size) + 2 ? now : null;
+  }
+
+  /** One more byte on the generation beside `path`, where `path` is one of a tree's files. A directory that is not
+   *  there has no reader to tell: the write that makes it is followed by the byte that makes its generation. */
+  private moved(path: string): void {
+    if (!TREE_FILE_NAMES.has(basename(path))) return;
+    try { appendFileSync(join(dirname(path), TREE_GENERATION), '.'); }
+    catch (error) { if (!absent(error)) throw error; }
+  }
+
+  /** A write of `path`, with the generation beside it moved before and after where it is one of a tree's files. */
+  private writing(path: string, write: () => void): void {
+    this.moved(path);
+    try { write(); } finally { this.moved(path); }
   }
 
   readLines(path: string): string[] {
-    if (!existsSync(path)) return [];
-    return readFileSync(path, 'utf8').split('\n');
+    try { return readFileSync(path, 'utf8').split('\n'); }
+    catch (error) { if (absent(error)) return []; throw error; }
   }
 
   readRange(path: string, start: number): string | null {
@@ -184,50 +720,66 @@ export class FsWorldStore implements WorldStore {
   }
 
   append(path: string, data: string): void {
+    asked('append');
     refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
+    this.kept.delete(path);
+    // A tree's file in a tab: the generation's byte, the append and the byte again as one request of the kernel
+    // (fileSteps), by its own opens, writes and closes in this order. Not where every append is to be fsynced.
+    if (TREE_FILE_NAMES.has(basename(path)) && process.env.VOLTER_DURABLE !== '1'
+      && fileSteps()?.appendBetween(join(dirname(path), TREE_GENERATION), '.', path, data)) return;
     // Historical appendDurable: a completed append syscall survives a process crash;
     // fsync additionally survives kernel-panic/power-loss when VOLTER_DURABLE=1.
-    const fd = openSync(path, 'a');
-    try {
-      appendFileSync(fd, data);
-      if (process.env.VOLTER_DURABLE === '1') fsyncSync(fd);
-    } finally {
-      closeSync(fd);
-    }
+    this.writing(path, () => {
+      const fd = openSync(path, 'a');
+      try {
+        appendFileSync(fd, data);
+        if (process.env.VOLTER_DURABLE === '1') fsyncSync(fd);
+      } finally {
+        closeSync(fd);
+      }
+    });
   }
 
   write(path: string, data: string, options: { secret?: boolean } = {}): void {
     refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
-    if (!options.secret) {
-      mkdirSync(dirname(path), { recursive: true });
-      writeFileSync(path, data);
-      return;
-    }
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    writeFileSync(path, data, { mode: 0o600 });
-    chmodSync(path, 0o600);
+    this.kept.delete(path);
+    this.writing(path, () => {
+      if (!options.secret) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, data);
+        return;
+      }
+      mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+      writeFileSync(path, data, { mode: 0o600 });
+      chmodSync(path, 0o600);
+    });
   }
 
   writeAtomic(path: string, data: string, options: { secret?: boolean } = {}): void {
     refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
+    this.kept.delete(path);
     mkdirSync(dirname(path), { recursive: true });
     const tmp = `${path}.${process.pid}.${Date.now()}.${fsAtomicSequence++}.tmp`;
-    try {
-      writeFileSync(tmp, data, options.secret ? { mode: 0o600 } : undefined);
-      renameSync(tmp, path);
-      if (options.secret) chmodSync(path, 0o600);
-    } finally {
-      rmSync(tmp, { force: true });
-    }
+    this.writing(path, () => {
+      try {
+        writeFileSync(tmp, data, options.secret ? { mode: 0o600 } : undefined);
+        renameSync(tmp, path);
+        if (options.secret) chmodSync(path, 0o600);
+      } finally {
+        rmSync(tmp, { force: true });
+      }
+    });
   }
 
   exists(path: string): boolean {
+    asked('exists');
     return existsSync(path);
   }
 
   remove(path: string): void {
     refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
-    rmSync(path, { recursive: true, force: true });
+    for (const held of this.kept.keys()) if (held === path || held.startsWith(`${path}/`)) this.kept.delete(held);
+    this.writing(path, () => rmSync(path, { recursive: true, force: true }));
   }
 
   mkdir(dirPath: string): void {
@@ -235,13 +787,24 @@ export class FsWorldStore implements WorldStore {
   }
 
   list(dirPath: string): string[] {
-    if (!existsSync(dirPath)) return [];
-    return readdirSync(dirPath);
+    asked('list');
+    try { return readdirSync(dirPath); }
+    catch (error) {
+      // No such directory is an empty one, as before; a path that IS there and is not a directory still fails.
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT' || (code === 'ENOTDIR' && !existsSync(dirPath))) return [];
+      throw error;
+    }
   }
 
+  /** The real path of each path already resolved: a state directory's does not move under a running process, and
+   *  every history lock asked for it again. A path that does not exist yet is not kept. */
+  private readonly canonical = new Map<string, string>();
   canonicalPath(path: string): string {
     const absolute = resolve(path);
-    try { return realpathSync(absolute); }
+    const known = this.canonical.get(absolute);
+    if (known !== undefined) return known;
+    try { const real = realpathSync(absolute); this.canonical.set(absolute, real); return real; }
     catch (error) {
       if ((error as NodeJS.ErrnoException).code !== 'ENOENT' || dirname(absolute) === absolute) throw error;
       return join(this.canonicalPath(dirname(absolute)), basename(absolute));
@@ -249,80 +812,194 @@ export class FsWorldStore implements WorldStore {
   }
 
   stat(path: string): WorldStat | null {
-    if (!existsSync(path)) return null;
-    const s = statSync(path);
-    return { size: s.size, mtimeMs: s.mtimeMs, isDirectory: s.isDirectory(), ...(lstatSync(path).isSymbolicLink() ? { isSymbolicLink: true } : {}) };
+    asked('stat');
+    // The path itself first: where it is no link, that is the whole answer. A link is followed by a second call,
+    // and one that leads nowhere is absent, as it was.
+    // Asked without an error being made of a missing path (a tree's parent log is absent in a World with no parent).
+    let own: Stats | undefined;
+    try { own = lstatSync(path, { throwIfNoEntry: false }); }
+    catch (error) { if (!absent(error)) throw error; }
+    if (!own) return null;
+    if (!own.isSymbolicLink()) return { size: own.size, mtimeMs: own.mtimeMs, isDirectory: own.isDirectory() };
+    try { const s = statSync(path); return { size: s.size, mtimeMs: s.mtimeMs, isDirectory: s.isDirectory(), isSymbolicLink: true }; }
+    catch (error) { if (absent(error) || (error as NodeJS.ErrnoException).code === 'ELOOP') return null; throw error; }
   }
 
   /** Run `fn` holding an exclusive cross-process file lock. The lockfile records
-   *  `{pid, hostname, at}`; a contender that finds a stale lock (dead pid or age >
+   *  identity, operation, caller and any nested wait; a contender that finds a stale lock (dead pid or age >
    *  LOCK_STALE_MS) reclaims it by atomically renaming it aside — so a crashed holder
    *  can't wedge the world forever. Reclaim is race-safe: only the process that wins
    *  the rename clears the stale inode, and the exclusive `wx` create still decides the
    *  winner. (Moved verbatim from storage.ts `withFileLock`.) */
-  withLock<T>(lockPath: string, fn: () => T, options: { retainLiveOwner?: boolean } = {}): T {
-    mkdirSync(dirname(lockPath), { recursive: true });
+  withLock<T>(lockPath: string, fn: () => T, options: WorldLockOptions = {}): T {
     const started = Date.now();
+    const scope = storageLockScope(options);
+    fn = countedHold(scope.operation, fn);
     let fd: number | null = null;
-    while (fd === null) {
-      try {
-        fd = openSync(lockPath, 'wx');
-      } catch (error) {
-        const code = (error as NodeJS.ErrnoException).code;
-        if (code !== 'EEXIST') throw error;
-        if (lockIsStale(lockPath, options.retainLiveOwner)) {
-          // Serialize reclaimers, then re-read: a contender's earlier stale observation
-          // must never rename another contender's newly acquired, live lock.
-          const recoveryPath = `${lockPath}.recovery`;
-          let recovery: number;
-          try { recovery = openSync(recoveryPath, 'wx'); }
-          catch (error) {
-            if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
-            if (Date.now() - started > 10_000) throw new Error(`Lock recovery is active or interrupted: ${recoveryPath}. Inspect its owner before removing the recovery record.`);
-            sleepSync(25); continue;
+    // A kernel's file step takes the lock with its record in one request and keeps no descriptor (fileSteps).
+    const steps = fileSteps();
+    // The token is the take's own: its release removes the file only while it still holds this token, so a file a
+    // stale-lock sweep reclaimed and another process re-created is never removed by the first holder.
+    const token = randomUUID();
+    const holderNow = (): LockHolder => ({ pid: process.pid, hostname: ownHostname(), at: new Date().toISOString(), token, operation: scope.operation, caller: scope.caller });
+    let record: LockHolder | undefined;
+    let taken = false;
+    let unrecordedTakes = 0;
+    let recordBytes: number | undefined;
+    let made = false;
+    let reported = false;
+    let attempts = 0;
+    let sleeps = 0;
+    let sleepMs = 0;
+    let waitedOn: LockHolder | null = null;
+    let nestedWait: { path: string; since: number; holders: LockReading[] } | undefined;
+    const finishNestedWait = (): void => {
+      if (!nestedWait) return;
+      const waitedMs = Date.now() - nestedWait.since;
+      for (const reading of nestedWait.holders) {
+        const key = `${nestedWait.path}\0${scope.operation}`;
+        const previous = reading.nestedWaits.get(key);
+        reading.nestedWaits.set(key, { path: nestedWait.path, operation: scope.operation, waitedMs: (previous?.waitedMs ?? 0) + waitedMs });
+        delete reading.holder.waitingFor;
+        recordLockReading(reading);
+      }
+      nestedWait = undefined;
+    };
+    const reportWait = (): void => {
+      if (reported || !nestedWait || Date.now() - started < 2_000) return;
+      reported = true;
+      const holder = readLockHolder(nestedWait.path);
+      const since = holder && typeof holder.at === 'string' ? Date.parse(holder.at) : NaN;
+      storageLockLine(`[world] storage lock still held path=${nestedWait.path} holder=${holder?.pid ?? '?'}@${holder?.hostname ?? '?'} token=${holder?.token ?? '?'} operation=${holder?.operation ?? holder?.caller ?? 'unknown:0'} holderMs=${Number.isFinite(since) ? Date.now() - since : '?'} waiter=${process.pid} waitingOperation=${scope.operation} caller=${scope.caller}`);
+    };
+    const slept = (path = lockPath): void => {
+      if (sleeps === 0) waitedOn = readLockHolder(path);
+      if (nestedWait?.path !== path) {
+        finishNestedWait();
+        nestedWait = { path, since: Date.now(), holders: [...lockReadings] };
+        for (const reading of nestedWait.holders) {
+          reading.holder.waitingFor = { path, operation: scope.operation, since: nestedWait.since };
+          recordLockReading(reading);
+        }
+      }
+      reportWait();
+      const sleeping = Date.now();
+      sleeps += 1;
+      sleepSync(25);
+      sleepMs += Date.now() - sleeping;
+    };
+    try {
+      while (!taken) {
+        // This runs in the synchronous loop: a blocked holder cannot service a timer.
+        reportWait();
+        try {
+          attempts += 1;
+          // The holder is recorded WITH the take (createRecorded): no other process sees this lock without its record.
+          record = holderNow();
+          const taking = createRecorded(lockPath, `${JSON.stringify(record)}\n`, token, scope.operation);
+          fd = taking.fd;
+          recordBytes = taking.bytes;
+          taken = true;
+        } catch (error) {
+          const code = (error as NodeJS.ErrnoException).code;
+          // The lock's directory is made when it is found missing, once, not before every take: it is there for
+          // every take after a state directory's first.
+          if (code === 'ENOENT' && !made) { made = true; mkdirSync(dirname(lockPath), { recursive: true }); continue; }
+          // A two-call take whose path did not hold its record after it (another reclaimed it between): taken again.
+          if (code === RECLAIMED_BEFORE_RECORD) continue;
+          // A take whose record could not be written: made again, a few times, before the failure is the caller's.
+          if (code === RECORD_NOT_WRITTEN) {
+            unrecordedTakes += 1;
+            if (unrecordedTakes >= RECORD_ATTEMPTS) throw Object.assign(new Error(`World storage lock ${lockPath}: its holder's record could not be written`), { code: 'EIO', cause: error });
+            sleepSync(25 * unrecordedTakes);
+            continue;
           }
-          try {
-            writeFileSync(recovery, JSON.stringify({ pid: process.pid, hostname: hostname() }));
-            if (lockIsStale(lockPath, options.retainLiveOwner)) {
-              const holder = readLockHolder(lockPath);
-              const salvage = `${lockPath}.stale.${process.pid}.${Date.now()}`;
-              try {
-                renameSync(lockPath, salvage);
-                console.warn(`[world] reclaiming stale storage lock ${lockPath} (held by pid ${holder?.pid ?? '?'} on ${holder?.hostname ?? '?'})`);
-                unlinkSync(salvage);
-              } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+          if (code !== 'EEXIST') throw error;
+          if (lockIsStale(lockPath, options.retainLiveOwner)) {
+            // Serialize reclaimers, then re-read: a contender's earlier stale observation
+            // must never rename another contender's newly acquired, live lock. The reclaim record is made as a lock
+            // is, with its record and a token of its own, and released by that token.
+            const recoveryPath = `${lockPath}.recovery`;
+            const recoveryToken = randomUUID();
+            let recovery: { fd: number | null };
+            try { recovery = createRecorded(recoveryPath, `${JSON.stringify({ pid: process.pid, hostname: ownHostname(), at: new Date().toISOString(), token: recoveryToken })}\n`, recoveryToken, 'lock recovery'); }
+            catch (error) {
+              const recoveryCode = (error as NodeJS.ErrnoException).code;
+              if (recoveryCode === RECLAIMED_BEFORE_RECORD || recoveryCode === RECORD_NOT_WRITTEN) continue;
+              if (recoveryCode !== 'EEXIST') throw error;
+              // A reclaim record no reclaimer is behind is reclaimed as an empty lock file is (recoveryIsStale).
+              if (recoveryIsStale(recoveryPath)) {
+                const aside = `${recoveryPath}.stale.${process.pid}.${randomUUID()}`;
+                try { renameSync(recoveryPath, aside); unlinkSync(aside); lockRecordLine('recovery-reclaimed', recoveryPath, {}); }
+                catch (cause) { if ((cause as NodeJS.ErrnoException).code !== 'ENOENT') throw cause; }
+                continue;
+              }
+              if (Date.now() - started > 10_000) throw new Error(`Lock recovery is active or interrupted: ${recoveryPath}${lockHolderMessage(readLockHolder(recoveryPath, 'timeout'))}. Inspect its owner before removing the recovery record.`);
+              slept(recoveryPath); continue;
             }
-          } finally { closeSync(recovery); unlinkSync(recoveryPath); }
-          continue;
-        }
-        if (Date.now() - started > 10_000) {
-          const holder = readLockHolder(lockPath);
-          const since = holder && typeof holder.at === 'string' ? Date.parse(holder.at) : NaN;
-          throw new Error(`Timed out waiting for world storage lock: ${lockPath}${holder ? ` (held by pid ${holder.pid} on ${holder.hostname}${Number.isFinite(since) ? ` for ${Date.now() - since}ms` : ''})` : ''}`);
+            try {
+              if (lockIsStale(lockPath, options.retainLiveOwner)) {
+                const holder = readLockHolder(lockPath);
+                const salvage = `${lockPath}.stale.${process.pid}.${Date.now()}`;
+                try {
+                  renameSync(lockPath, salvage);
+                  console.warn(`[world] reclaiming stale storage lock ${lockPath} (held by pid ${holder?.pid ?? '?'} on ${holder?.hostname ?? '?'}) (reclaimer pid ${process.pid} on ${ownHostname()})`);
+                  unlinkSync(salvage);
+                } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+              }
+            } finally { releaseRecorded(recoveryPath, recoveryToken, recovery.fd); }
+            continue;
+          }
+          if (Date.now() - started > 10_000) {
+            const holder = readLockHolder(lockPath, 'timeout');
+            throw new Error(`Timed out waiting for world storage lock: ${lockPath}${lockHolderMessage(holder)}`);
+          }
+          slept();
         }
-        sleepSync(25);
+      }
+    } finally {
+      finishNestedWait();
+      if (sleeps > 0) {
+        const waitedMs = Date.now() - started;
+        const first = waitedOn as LockHolder | null;
+        storageLockLine(`[world] storage lock wait path=${lockPath} outcome=${taken ? 'acquired' : 'failed'} waiter=${process.pid}@${ownHostname()} operation=${scope.operation} attempts=${attempts} sleeps=${sleeps} requestedSleepMs=${sleeps * 25} sleepMs=${sleepMs} outsideSleepMs=${waitedMs - sleepMs} waitedMs=${waitedMs} firstHolder=${first?.pid ?? '?'}@${first?.hostname ?? '?'} token=${first?.token ?? '?'}`);
       }
     }
 
-    // Record the holder so a later contender can detect staleness. Best-effort: a write
-    // failure here doesn't weaken exclusivity, only staleness diagnostics.
-    try {
-      writeFileSync(fd, `${JSON.stringify({ pid: process.pid, hostname: hostname(), at: new Date().toISOString() } satisfies LockHolder)}\n`);
-    } catch { /* ignore */ }
+    // The holder's record was written with the take, in the loop above: a take whose record could not be written is
+    // never held (EMPTY_RECORD_GRACE_MS).
+    ownLocks.set(lockPath, token);
 
     const acquired = Date.now();
+    const reading: LockReading = { path: lockPath, fd, holder: record!, nestedWaits: new Map(), ...(recordBytes !== undefined ? { recordBytes } : {}) };
+    lockReadings.push(reading);
     try {
       return fn();
     } finally {
       // Every World on the machine waits on some of these locks; a long hold stalls them all.
       const heldMs = Date.now() - acquired;
+      if (heldMs > 2_000) storageLockLine(`[world] releasing storage lock path=${lockPath} operation=${scope.operation} heldMs=${heldMs} nestedWaits=${JSON.stringify([...reading.nestedWaits.values()])}`);
       if (heldMs > 2_000) console.warn(`[world] held storage lock ${lockPath} for ${heldMs}ms (pid ${process.pid})\n${new Error().stack?.split('\n').slice(2, 8).join('\n') ?? ''}`);
-      const held = fstatSync(fd);
-      closeSync(fd);
+      lockReadings.pop();
+      ownLocks.delete(lockPath);
+      if (fd !== null) {
+        try { closeSync(fd); }
+        catch (error) { lockRecordLine('close-failed', lockPath, { fd }, error); throw error; }
+      }
+      // By the token the take wrote, not by inode: a filesystem may answer a descriptor's stat and the path's with
+      // different identities (a tab's, where a committed path is the store's entry), and a lock released by inode
+      // was then never removed, left recorded as this live process's (above). A kernel's file step reads the record,
+      // compares its token and unlinks in one request; its answer is what the read below would have found.
       try {
-        const current = lstatSync(lockPath);
-        if (held.dev === current.dev && held.ino === current.ino) unlinkSync(lockPath);
-      } catch { /* already reclaimed by a stale-lock sweep */ }
+        const released = fd === null ? steps?.changeHolding(lockPath, tokenNeedle(token), undefined) : undefined;
+        if (!released?.changed) {
+          const observed = released === undefined ? readLockHolder(lockPath, 'release') : lockHolderOf(lockPath, released.observed, 'release');
+          if (observed?.token === token) unlinkSync(lockPath);
+          else if (observed) lockRecordLine('release-token-mismatch', lockPath, {
+            token, recordedToken: observed.token, recordedPid: observed.pid, recordedHostname: observed.hostname,
+          });
+        }
+      } catch (error) { lockRecordLine('release-failed', lockPath, { fd }, error); }
     }
   }
 }