@volter/world-core 3.0.155 → 3.0.157

package/dist/src/world-store.js

@@ -23,23 +23,548 @@
 // runs on the serve path. Its bespoke inode-identity lock and reservation semantics
 // cannot be expressed through this generic seam without weakening them, so it stays on
 // `node:fs`. See its module header.
-import { appendFileSync, chmodSync, closeSync, existsSync, fsyncSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { appendFileSync, chmodSync, closeSync, existsSync, fsyncSync, fstatSync, linkSync, ftruncateSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync, } from 'node:fs';
 import { hostname } from 'node:os';
+import { randomUUID } from 'node:crypto';
 import { refuseReadOnlyWrite } from "./request-scope.js";
 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'];
+// 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 = () => ({ 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) {
+    if (questionsCounted)
+        (lockHoldDepth > 0 ? questionsHeld : questionsUnheld)[kind] += 1;
+}
+function countedHold(operation, fn) {
+    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 */ }
+            }
+        }
+    };
+}
+/**
+ * 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 = {}) {
+    let frame;
+    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;
+        }
+    }
+    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 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' };
+export const TREE_GENERATION = 'tree.generation';
+const TREE_FILE_NAMES = new Set(Object.values(TREE_FILES));
 // ── FsWorldStore — the DEFAULT, byte-identical to the historical node:fs behavior ────
 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;
-function readLockHolder(lockPath) {
+/**
+ * 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;
+/** The locks this process holds now, by path, and the token each was recorded with (withLock). */
+const ownLocks = new Map();
+const lockReadings = [];
+function fileSteps() {
+    const tree = process[Symbol.for('tabnode.run.vfs')];
+    const offered = tree?.[Symbol.for('browser-substrate.kernel-file-steps')];
+    return offered && typeof offered === 'object' ? offered : 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) => `"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, text, token, operation) {
+    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;
+        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[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.code === 'EEXIST')
+                    sweepTakeFiles(path);
+                if (!LINK_UNSUPPORTED.has(error.code ?? ''))
+                    throw error;
+            }
+        }
+        finally {
+            try {
+                unlinkSync(temporary);
+            }
+            catch { /* not made, or gone */ }
+        }
+        if (linked) {
+            let fd = 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 };
+}
+/**
+ * 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();
+function sweepTakeFiles(path) {
+    if (sweptTakes.has(path))
+        return;
+    sweptTakes.add(path);
+    const prefix = `${basename(path)}.take.`;
     try {
-        return JSON.parse(readFileSync(lockPath, 'utf8'));
+        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, token, fd) {
+    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) {
+    let file;
+    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, options) {
+    const removed = [];
+    const isHolder = (text) => Number.isInteger(lockHolderOf('', text)?.pid);
+    const carriedText = (text) => {
+        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) => {
+        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, text) => {
+        const aside = `${path}.carried.${process.pid}.${randomUUID()}`;
+        try {
+            renameSync(path, aside);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                lockRecordLine('carried-rename-failed', path, {}, error);
+            return false;
+        }
+        let after;
+        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.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) => {
+        const recoveryPath = `${path}.recovery`, recoveryToken = randomUUID();
+        let recovery;
+        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, depth) => {
+        let entries;
+        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;
+const ownHostname = () => (fileSteps() ? (hostnameRead ??= hostname()) : hostname());
+function recordLockReading(reading) {
+    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) {
+    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, path, fields, error) {
+    try {
+        const cause = error;
+        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(path, operation, fn) {
+    let reading;
+    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) => { const code = error?.code; return code === 'ENOENT' || code === 'ENOTDIR'; };
+function readLockHolder(lockPath, diagnostic) {
+    let text;
+    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, text, diagnostic) {
+    if (text === null) {
+        if (diagnostic)
+            lockRecordLine('read-failed', lockPath, { during: diagnostic, code: 'ENOENT' });
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    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) {
+    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) {
     try {
         process.kill(pid, 0);
@@ -50,16 +575,34 @@ function pidAlive(pid) {
         return error.code === 'EPERM';
     }
 }
-/** 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, retainLiveOwner = false) {
     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;
@@ -84,15 +627,141 @@ function sleepSync(ms) {
  * file lock — so the existing twins and the conformance suite are unaffected.
  */
 export class FsWorldStore {
+    // 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) {
-        if (!existsSync(path))
+        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.
+     */
+    kept = new Map();
+    readKept(path) {
+        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;
+        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;
-        return readFileSync(path, 'utf8');
+        }
+        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) {
+        asked('generation');
+        let own;
+        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, before) {
+        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. */
+    moved(path) {
+        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. */
+    writing(path, write) {
+        this.moved(path);
+        try {
+            write();
+        }
+        finally {
+            this.moved(path);
+        }
     }
     readLines(path) {
-        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, start) {
         let fd;
@@ -123,63 +792,98 @@ export class FsWorldStore {
         }
     }
     append(path, data) {
+        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, data, options = {}) {
         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, data, options = {}) {
         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) {
+        asked('exists');
         return existsSync(path);
     }
     remove(path) {
         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) {
         mkdirSync(dirPath, { recursive: true });
     }
     list(dirPath) {
-        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.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. */
+    canonical = new Map();
     canonicalPath(path) {
         const absolute = resolve(path);
+        const known = this.canonical.get(absolute);
+        if (known !== undefined)
+            return known;
         try {
-            return realpathSync(absolute);
+            const real = realpathSync(absolute);
+            this.canonical.set(absolute, real);
+            return real;
         }
         catch (error) {
             if (error.code !== 'ENOENT' || dirname(absolute) === absolute)
@@ -188,98 +892,250 @@ export class FsWorldStore {
         }
     }
     stat(path) {
-        if (!existsSync(path))
+        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;
+        try {
+            own = lstatSync(path, { throwIfNoEntry: false });
+        }
+        catch (error) {
+            if (!absent(error))
+                throw error;
+        }
+        if (!own)
             return null;
-        const s = statSync(path);
-        return { size: s.size, mtimeMs: s.mtimeMs, isDirectory: s.isDirectory(), ...(lstatSync(path).isSymbolicLink() ? { isSymbolicLink: true } : {}) };
+        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.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(lockPath, fn, options = {}) {
-        mkdirSync(dirname(lockPath), { recursive: true });
         const started = Date.now();
+        const scope = storageLockScope(options);
+        fn = countedHold(scope.operation, fn);
         let fd = null;
-        while (fd === null) {
-            try {
-                fd = openSync(lockPath, 'wx');
+        // 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 = () => ({ pid: process.pid, hostname: ownHostname(), at: new Date().toISOString(), token, operation: scope.operation, caller: scope.caller });
+        let record;
+        let taken = false;
+        let unrecordedTakes = 0;
+        let recordBytes;
+        let made = false;
+        let reported = false;
+        let attempts = 0;
+        let sleeps = 0;
+        let sleepMs = 0;
+        let waitedOn = null;
+        let nestedWait;
+        const finishNestedWait = () => {
+            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);
             }
-            catch (error) {
-                const code = error.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;
-                    try {
-                        recovery = openSync(recoveryPath, 'wx');
+            nestedWait = undefined;
+        };
+        const reportWait = () => {
+            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) => {
+            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.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;
                     }
-                    catch (error) {
-                        if (error.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);
+                    // 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);
+                    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;
+                        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.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.code !== 'ENOENT')
+                                        throw cause;
+                                }
+                                continue;
                             }
-                            catch (error) {
-                                if (error.code !== 'ENOENT')
-                                    throw error;
+                            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;
+                        }
+                        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.code !== 'ENOENT')
+                                        throw error;
+                                }
                             }
                         }
+                        finally {
+                            releaseRecorded(recoveryPath, recoveryToken, recovery.fd);
+                        }
+                        continue;
                     }
-                    finally {
-                        closeSync(recovery);
-                        unlinkSync(recoveryPath);
+                    if (Date.now() - started > 10_000) {
+                        const holder = readLockHolder(lockPath, 'timeout');
+                        throw new Error(`Timed out waiting for world storage lock: ${lockPath}${lockHolderMessage(holder)}`);
                     }
-                    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` : ''})` : ''}`);
+                    slept();
                 }
-                sleepSync(25);
             }
         }
-        // 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() })}\n`);
+        finally {
+            finishNestedWait();
+            if (sleeps > 0) {
+                const waitedMs = Date.now() - started;
+                const first = waitedOn;
+                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 ?? '?'}`);
+            }
         }
-        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 = { 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);
+                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);
             }
-            catch { /* already reclaimed by a stale-lock sweep */ }
         }
     }
 }