@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/core/export-moved-code-shape.d.ts

@@ -21,14 +21,25 @@
  * carry), so the refusal can name the sequence instead of leaving the
  * operator to derive it.
  */
+/** One run of consecutive lines a new file shares with an existing patch. */
+export interface MovedCodeBlock {
+    /** New-file path in the pending diff. */
+    file: string;
+    /** File in the source patch that carries the same run. */
+    sourceFile: string;
+    /** The matched substantive lines, trimmed, in order. */
+    lines: string[];
+}
 /** One existing patch that already carries lines the new files would add. */
 export interface MovedCodeOverlap {
     /** Filename of the patch that still contains the moved lines. */
     sourcePatch: string;
     /** New-file paths in the pending diff whose lines it overlaps. */
     files: string[];
-    /** Count of distinct non-trivial lines shared. */
+    /** Count of substantive lines inside the matched blocks. */
     sharedLines: number;
+    /** The matched blocks, so the claim can be checked line by line. */
+    blocks: MovedCodeBlock[];
 }
 /** Minimal queue view this detector needs. */
 export interface MovedCodeQueueEntry {
@@ -36,9 +47,9 @@ export interface MovedCodeQueueEntry {
     diff: string;
 }
 /**
- * Finds existing patches that still carry substantive lines the pending
- * diff's new files would add, the fingerprint of code moved out of an
- * existing patch into a new file.
+ * Finds existing patches that still carry a block of substantive lines the
+ * pending diff's new files would add, the fingerprint of code moved out of
+ * an existing patch into a new file.
  *
  * Pure. Overlaps are returned strongest-first so the message names the
  * most likely source patch.
@@ -48,13 +59,40 @@ export interface MovedCodeQueueEntry {
  * @returns Overlaps, or an empty list when the shape is not present
  */
 export declare function detectMovedCodeOverlaps(pendingDiff: string, entries: readonly MovedCodeQueueEntry[]): MovedCodeOverlap[];
+/** What the placement projection learned about the pending export. */
+export interface MovedCodeAdviceInput {
+    /** Result of {@link detectMovedCodeOverlaps}. */
+    overlaps: readonly MovedCodeOverlap[];
+    /** The filename the pending export would take. */
+    newPatchName: string;
+    /** The order the pending export would take. */
+    insertionOrder: number;
+    /**
+     * New system modules in the pending diff that no patch registers
+     * (`unregistered-system-module` findings on the new patch).
+     */
+    unregisteredModules?: readonly string[];
+    /**
+     * True when every error in the exported content is a missing
+     * registration: registering is then the whole fix, and adopt-then-split
+     * is not offered at all.
+     */
+    registrationResolvesAll?: boolean;
+    /**
+     * Why adopting the new files into the strongest overlap's source patch
+     * would itself be refused (forward imports, size limit). Empty when the
+     * adopt is clean.
+     */
+    adoptBlockers?: readonly string[];
+}
 /**
- * Renders the adopt-then-split remedy for the strongest overlap, as lines
- * appended to the refusal's detail list.
+ * Renders the remedy lines appended to a placement refusal: "register
+ * first" when new modules lack their moz.build registration, then the
+ * adopt-then-split sequence for a real moved-code block, but only when the
+ * adopt itself would pass. Each claim names its evidence (the matched
+ * lines, the blocking findings) so it can be checked.
  *
- * @param overlaps - Result of {@link detectMovedCodeOverlaps}
- * @param newPatchName - The filename the pending export would take
- * @param insertionOrder - The order the pending export would take
- * @returns Detail lines, or an empty list when the shape is not present
+ * @param input - See {@link MovedCodeAdviceInput}
+ * @returns Detail lines, or an empty list when neither shape is present
  */
-export declare function formatAdoptThenSplitRemedy(overlaps: readonly MovedCodeOverlap[], newPatchName: string, insertionOrder: number): string[];
+export declare function formatMovedCodeAdvice(input: MovedCodeAdviceInput): string[];

package/dist/src/core/export-moved-code-shape.js

@@ -38,12 +38,67 @@ function isSubstantiveLine(line) {
         return false;
     return true;
 }
-/** Minimum shared substantive lines before the shape is claimed. */
-const MOVED_CODE_LINE_THRESHOLD = 3;
 /**
- * Finds existing patches that still carry substantive lines the pending
- * diff's new files would add, the fingerprint of code moved out of an
- * existing patch into a new file.
+ * Minimum run of consecutive substantive lines, in the same order in both
+ * the new file and the source patch, before a block counts as moved code.
+ * Matching scattered single lines instead let a large unrelated patch
+ * "share" a dozen common statements with any new module and sent operators
+ * down an adopt-then-split sequence through a patch that only carried a
+ * `<script>` line for the file.
+ */
+const MOVED_CODE_BLOCK_THRESHOLD = 3;
+function substantiveSequences(diff) {
+    const sequences = new Map();
+    for (const [file, lines] of extractAddedLinesPerFile(diff)) {
+        const substantive = lines.map((line) => line.trim()).filter(isSubstantiveLine);
+        if (substantive.length > 0)
+            sequences.set(file, substantive);
+    }
+    return sequences;
+}
+/**
+ * Longest-first, non-overlapping runs of `pending` that appear contiguously
+ * in one of `sources`' files. Anchored on exact line matches, so the work
+ * is bounded by the number of shared lines, not the product of the sizes.
+ */
+function findBlocks(file, pending, sources) {
+    const positions = new Map();
+    for (const [sourceFile, lines] of sources) {
+        lines.forEach((line, index) => {
+            const list = positions.get(line) ?? [];
+            list.push([sourceFile, index]);
+            positions.set(line, list);
+        });
+    }
+    const blocks = [];
+    let i = 0;
+    while (i < pending.length) {
+        let best;
+        for (const [sourceFile, start] of positions.get(pending[i] ?? '') ?? []) {
+            const source = sources.get(sourceFile) ?? [];
+            let length = 0;
+            while (i + length < pending.length &&
+                start + length < source.length &&
+                pending[i + length] === source[start + length]) {
+                length += 1;
+            }
+            if (best === undefined || length > best.length)
+                best = { sourceFile, length };
+        }
+        if (best !== undefined && best.length >= MOVED_CODE_BLOCK_THRESHOLD) {
+            blocks.push({ file, sourceFile: best.sourceFile, lines: pending.slice(i, i + best.length) });
+            i += best.length;
+        }
+        else {
+            i += 1;
+        }
+    }
+    return blocks;
+}
+/**
+ * Finds existing patches that still carry a block of substantive lines the
+ * pending diff's new files would add, the fingerprint of code moved out of
+ * an existing patch into a new file.
  *
  * Pure. Overlaps are returned strongest-first so the message names the
  * most likely source patch.
@@ -53,59 +108,95 @@ const MOVED_CODE_LINE_THRESHOLD = 3;
  * @returns Overlaps, or an empty list when the shape is not present
  */
 export function detectMovedCodeOverlaps(pendingDiff, entries) {
-    const pendingByFile = extractAddedLinesPerFile(pendingDiff);
-    const pendingLines = new Map();
-    for (const [file, lines] of pendingByFile) {
-        const substantive = new Set(lines.map((line) => line.trim()).filter(isSubstantiveLine));
-        if (substantive.size > 0)
-            pendingLines.set(file, substantive);
-    }
-    if (pendingLines.size === 0)
+    const pending = substantiveSequences(pendingDiff);
+    if (pending.size === 0)
         return [];
     const overlaps = [];
     for (const entry of entries) {
-        const existing = new Set();
-        for (const lines of extractAddedLinesPerFile(entry.diff).values()) {
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (isSubstantiveLine(trimmed))
-                    existing.add(trimmed);
-            }
-        }
-        if (existing.size === 0)
+        const sources = substantiveSequences(entry.diff);
+        if (sources.size === 0)
             continue;
-        const files = [];
-        const shared = new Set();
-        for (const [file, lines] of pendingLines) {
-            let fileShared = 0;
-            for (const line of lines) {
-                if (!existing.has(line))
-                    continue;
-                shared.add(line);
-                fileShared += 1;
-            }
-            if (fileShared > 0)
-                files.push(file);
-        }
-        if (shared.size >= MOVED_CODE_LINE_THRESHOLD && files.length > 0) {
-            overlaps.push({ sourcePatch: entry.filename, files: files.sort(), sharedLines: shared.size });
-        }
+        const blocks = [...pending].flatMap(([file, lines]) => findBlocks(file, lines, sources));
+        if (blocks.length === 0)
+            continue;
+        overlaps.push({
+            sourcePatch: entry.filename,
+            files: [...new Set(blocks.map((block) => block.file))].sort(),
+            sharedLines: blocks.reduce((sum, block) => sum + block.lines.length, 0),
+            blocks,
+        });
     }
     return overlaps.sort((a, b) => b.sharedLines - a.sharedLines || a.sourcePatch.localeCompare(b.sourcePatch));
 }
+/** Lines shown per matched block, and blocks shown per overlap. */
+const SHOWN_BLOCK_LINES = 4;
+const SHOWN_BLOCKS = 3;
+/** Renders the matched blocks of one overlap, capped, as detail lines. */
+function formatMatchedBlocks(overlap) {
+    const lines = [];
+    for (const block of overlap.blocks.slice(0, SHOWN_BLOCKS)) {
+        lines.push(`  ${block.file} ← ${overlap.sourcePatch} (${block.sourceFile}), ${block.lines.length} line(s):`);
+        for (const line of block.lines.slice(0, SHOWN_BLOCK_LINES))
+            lines.push(`    | ${line}`);
+        if (block.lines.length > SHOWN_BLOCK_LINES) {
+            lines.push(`    | … ${block.lines.length - SHOWN_BLOCK_LINES} more`);
+        }
+    }
+    if (overlap.blocks.length > SHOWN_BLOCKS) {
+        lines.push(`  … ${overlap.blocks.length - SHOWN_BLOCKS} more block(s)`);
+    }
+    return lines;
+}
+/**
+ * Renders the remedy lines appended to a placement refusal: "register
+ * first" when new modules lack their moz.build registration, then the
+ * adopt-then-split sequence for a real moved-code block, but only when the
+ * adopt itself would pass. Each claim names its evidence (the matched
+ * lines, the blocking findings) so it can be checked.
+ *
+ * @param input - See {@link MovedCodeAdviceInput}
+ * @returns Detail lines, or an empty list when neither shape is present
+ */
+export function formatMovedCodeAdvice(input) {
+    const lines = [];
+    const unregistered = input.unregisteredModules ?? [];
+    if (unregistered.length > 0) {
+        lines.push('', `Register first: ${unregistered.join(', ')} ${unregistered.length === 1 ? 'is a new system module' : 'are new system modules'} ` +
+            'no patch registers in moz.build. Add the moz.build line in the patch that owns that ' +
+            'moz.build; when its line is already in the working tree but unexported, declare it as a ' +
+            'staged registration on that patch, re-run this export, then re-export that patch.' +
+            (input.registrationResolvesAll === true
+                ? ' The exported content has no other cross-patch error, so once registered the new ' +
+                    'files need no adoption into another patch.'
+                : ''));
+    }
+    const strongest = input.overlaps[0];
+    if (strongest === undefined || input.registrationResolvesAll === true)
+        return lines;
+    const blockers = input.adoptBlockers ?? [];
+    const claim = `${strongest.sharedLines} substantive line(s) the new file(s) would add, in ` +
+        `${strongest.blocks.length} matching block(s), are still carried by ${strongest.sourcePatch}:`;
+    if (blockers.length > 0) {
+        lines.push('', claim, ...formatMatchedBlocks(strongest), `Adopting the new files into ${strongest.sourcePatch} first (adopt-then-split) would be refused too, so it is not offered:`, ...blockers.map((blocker) => `  - ${blocker}`));
+        return lines;
+    }
+    const adopt = formatAdoptThenSplitRemedy(strongest, input.newPatchName, input.insertionOrder);
+    if (unregistered.length > 0) {
+        adopt.splice(1, 0, 'Only if the export still fails once those modules are registered:');
+    }
+    lines.push(...adopt, `Matched lines: ${claim}`, ...formatMatchedBlocks(strongest));
+    return lines;
+}
 /**
  * Renders the adopt-then-split remedy for the strongest overlap, as lines
  * appended to the refusal's detail list.
  *
- * @param overlaps - Result of {@link detectMovedCodeOverlaps}
+ * @param strongest - The strongest overlap {@link detectMovedCodeOverlaps} found
  * @param newPatchName - The filename the pending export would take
  * @param insertionOrder - The order the pending export would take
- * @returns Detail lines, or an empty list when the shape is not present
+ * @returns Detail lines
  */
-export function formatAdoptThenSplitRemedy(overlaps, newPatchName, insertionOrder) {
-    const strongest = overlaps[0];
-    if (strongest === undefined)
-        return [];
+function formatAdoptThenSplitRemedy(strongest, newPatchName, insertionOrder) {
     const fileArgs = strongest.files.map((file) => `--scan-file ${file}`).join(' ');
     const moveArgs = strongest.files.map((file) => `--file ${file}`).join(' ');
     // `patch move-files --create` takes the new patch's name, not a

package/dist/src/core/file-lock-queue.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Live queue state around a contended lock: how many are queued and how many
+ * are ahead of you. Waiters are granted the lock in arrival order, so `ahead`
+ * is the number of grants that happen before yours.
+ */
+export interface LockQueueState {
+    /** Live waiters currently queued for the lock, including this process. */
+    depth: number;
+    /** Live waiters that arrived before this process. */
+    ahead: number;
+}
+/**
+ * A ticket not refreshed for this long is skipped when the queue is read.
+ * Six heartbeats of slack: long enough that a loaded host never skips a
+ * waiter that is merely slow, short enough that a stopped waiter does not
+ * hold the head of the queue for more than half a minute.
+ */
+export declare const WAITER_STALE_MS = 30000;
+/** Sibling directory holding the waiter tickets of a lock. */
+export declare function lockWaitersDir(lockPath: string): string;
+/**
+ * This process's view of itself in the queue: its wait start, and its ticket
+ * when it holds one. Without a ticket the position falls back to comparing
+ * wait starts, which is what a waiter whose registration failed can know.
+ */
+export interface QueueSelf {
+    startedAt: number;
+    ticket?: string | undefined;
+}
+/**
+ * Reads the live waiter queue around `lockPath`.
+ *
+ * Advisory and fail-open: an unreadable registry reports an empty queue
+ * rather than failing whatever asked. The caller's own ticket always counts
+ * as live, since this process knows it is waiting.
+ *
+ * @param lockPath - The lock directory whose queue to inspect
+ * @param self - This waiter, to compute `ahead`
+ */
+export declare function readLockQueue(lockPath: string, self?: QueueSelf): Promise<LockQueueState>;
+/** A waiter's place in the queue, from joining it to leaving it. */
+export interface WaiterRegistration {
+    /** Ticket name, or `undefined` when registration failed. */
+    ticket: string | undefined;
+    /** Refreshes the ticket when a heartbeat is due. Never throws. */
+    heartbeat: () => Promise<void>;
+    /** Leaves the queue. Always safe to call. */
+    deregister: () => Promise<void>;
+}
+/**
+ * Takes a ticket in the lock's waiter queue.
+ *
+ * Never fails the acquisition: a registry that cannot be written yields a
+ * registration without a ticket, and the waiter falls back to contending
+ * for the lock without queue order, which is how every waiter behaved
+ * before tickets decided the grant.
+ *
+ * @param lockPath - The contended lock directory
+ * @param startedAt - When this waiter started waiting (its arrival time)
+ */
+export declare function registerWaiter(lockPath: string, startedAt: number): Promise<WaiterRegistration>;
+/**
+ * Renders the queue position for a wait line, with the ordering rule, so the
+ * reader knows the count is a promise and not a snapshot. Empty when nothing
+ * is queued.
+ */
+export declare function formatLockQueuePosition(queue: LockQueueState | undefined): string;

package/dist/src/core/file-lock-queue.js

@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Waiter tickets for `withFileLock`: who is queued for a contended lock, in
+ * what order, and whose turn it is.
+ *
+ * The queue started as a display: waiters advertised themselves so the wait
+ * line could say "You are next", but the grant itself was a free-for-all of
+ * `mkdir` polls. A waiter whose poll interval had backed off to 2 s lost
+ * every free moment to later arrivals polling at 100 ms, so a run told it
+ * was next for twenty minutes watched three later runs take the lock in
+ * turn. The tickets now decide the grant: only the head of the queue may
+ * attempt the lock, so the position printed is the position honoured.
+ *
+ * A ticket is a file in `<lock>.waiters/` named
+ * `<startedAtMs>-<pid>-<uuid>`. Arrival order is the wait start, with the
+ * whole name as a tie-break so every reader sorts the queue identically.
+ * Because a ticket now blocks everyone behind it, a ticket whose owner is
+ * gone must not hold the queue: a dead PID (or a reused one, where the
+ * start-tick check can tell) drops out and its ticket is removed, and a
+ * ticket its owner has stopped refreshing drops out without being removed,
+ * which covers a stopped (^Z) waiter and a reused PID on platforms with no
+ * start tick.
+ */
+import { randomUUID } from 'node:crypto';
+import { readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { ensureDir } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { isLockOwnerAlive, readProcessStartTick } from './file-lock-owner.js';
+/**
+ * How often a waiter refreshes its ticket. Every wait loop iteration
+ * refreshes once this much time has passed, and no caller sleeps longer
+ * than a few seconds between iterations.
+ */
+const WAITER_HEARTBEAT_MS = 5_000;
+/**
+ * A ticket not refreshed for this long is skipped when the queue is read.
+ * Six heartbeats of slack: long enough that a loaded host never skips a
+ * waiter that is merely slow, short enough that a stopped waiter does not
+ * hold the head of the queue for more than half a minute.
+ */
+export const WAITER_STALE_MS = 30_000;
+/** Prefix of the ticket line carrying the waiter's process start tick. */
+const START_TICK_PREFIX = 'start-tick=';
+/** Sibling directory holding the waiter tickets of a lock. */
+export function lockWaitersDir(lockPath) {
+    return `${lockPath}.waiters`;
+}
+/** Parses a ticket name: `<startedAtMs>-<pid>-<uuid>`. */
+function parseTicketName(name) {
+    const match = /^(\d+)-(\d+)-/.exec(name);
+    const startedAt = match?.[1];
+    const pid = match?.[2];
+    if (startedAt === undefined || pid === undefined)
+        return undefined;
+    return { name, startedAt: Number.parseInt(startedAt, 10), pid: Number.parseInt(pid, 10) };
+}
+/** Arrival order: wait start first, then the name, so every reader agrees. */
+function compareTickets(a, b) {
+    if (a.startedAt !== b.startedAt)
+        return a.startedAt - b.startedAt;
+    if (a.name === b.name)
+        return 0;
+    return a.name < b.name ? -1 : 1;
+}
+/** Reads the start tick a ticket recorded, when its writer could record one. */
+async function readTicketStartTick(path) {
+    const content = await readFile(path, 'utf-8');
+    const line = content.split('\n').find((entry) => entry.startsWith(START_TICK_PREFIX));
+    if (line === undefined)
+        return undefined;
+    const tick = Number.parseInt(line.slice(START_TICK_PREFIX.length), 10);
+    return Number.isFinite(tick) ? tick : undefined;
+}
+/**
+ * Whether a ticket still holds a place in the queue. A ticket whose owner is
+ * provably gone is removed so the directory does not accumulate them; one
+ * that has merely stopped being refreshed is skipped but left alone, since
+ * its owner may resume and refresh it.
+ */
+async function isTicketLive(dir, ticket, now) {
+    const path = join(dir, ticket.name);
+    let startTick;
+    let mtimeMs;
+    try {
+        startTick = await readTicketStartTick(path);
+        mtimeMs = (await stat(path)).mtimeMs;
+    }
+    catch {
+        // Deregistered between the listing and this read.
+        return false;
+    }
+    if (!isLockOwnerAlive({ pid: ticket.pid, startTick })) {
+        await rm(path, { force: true }).catch((error) => {
+            verbose(`Could not remove dead lock waiter ticket ${path}: ${toError(error).message}`);
+        });
+        return false;
+    }
+    return now - mtimeMs <= WAITER_STALE_MS;
+}
+/**
+ * Reads the live waiter queue around `lockPath`.
+ *
+ * Advisory and fail-open: an unreadable registry reports an empty queue
+ * rather than failing whatever asked. The caller's own ticket always counts
+ * as live, since this process knows it is waiting.
+ *
+ * @param lockPath - The lock directory whose queue to inspect
+ * @param self - This waiter, to compute `ahead`
+ */
+export async function readLockQueue(lockPath, self) {
+    const dir = lockWaitersDir(lockPath);
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return { depth: 0, ahead: 0 };
+    }
+    const now = Date.now();
+    const tickets = names
+        .map(parseTicketName)
+        .filter((ticket) => ticket !== undefined);
+    const liveFlags = await Promise.all(tickets.map((ticket) => ticket.name === self?.ticket ? Promise.resolve(true) : isTicketLive(dir, ticket, now)));
+    const live = tickets.filter((_, index) => liveFlags[index] === true);
+    if (self === undefined)
+        return { depth: live.length, ahead: 0 };
+    if (self.ticket === undefined) {
+        return {
+            depth: live.length,
+            ahead: live.filter((ticket) => ticket.startedAt < self.startedAt).length,
+        };
+    }
+    const own = parseTicketName(self.ticket);
+    // Our ticket can be missing from the listing only if something removed it;
+    // we still count ourselves, and the next heartbeat recreates it.
+    const listed = live.some((ticket) => ticket.name === self.ticket);
+    return {
+        depth: live.length + (listed ? 0 : 1),
+        ahead: own === undefined
+            ? 0
+            : live.filter((ticket) => ticket.name !== own.name && compareTickets(ticket, own) < 0)
+                .length,
+    };
+}
+/**
+ * Takes a ticket in the lock's waiter queue.
+ *
+ * Never fails the acquisition: a registry that cannot be written yields a
+ * registration without a ticket, and the waiter falls back to contending
+ * for the lock without queue order, which is how every waiter behaved
+ * before tickets decided the grant.
+ *
+ * @param lockPath - The contended lock directory
+ * @param startedAt - When this waiter started waiting (its arrival time)
+ */
+export async function registerWaiter(lockPath, startedAt) {
+    const dir = lockWaitersDir(lockPath);
+    const ticket = `${startedAt}-${process.pid}-${randomUUID()}`;
+    const file = join(dir, ticket);
+    const startTick = readProcessStartTick(process.pid);
+    const content = `${process.pid}\n${startTick !== undefined ? `${START_TICK_PREFIX}${startTick}\n` : ''}`;
+    try {
+        await ensureDir(dir);
+        await writeFile(file, content, 'utf-8');
+    }
+    catch (error) {
+        verbose(`Could not register lock waiter for ${lockPath}: ${toError(error).message}`);
+        return {
+            ticket: undefined,
+            heartbeat: async () => {
+                /* nothing to refresh */
+            },
+            deregister: async () => {
+                /* nothing to remove */
+            },
+        };
+    }
+    let lastBeatAt = Date.now();
+    return {
+        ticket,
+        heartbeat: async () => {
+            if (Date.now() - lastBeatAt < WAITER_HEARTBEAT_MS)
+                return;
+            lastBeatAt = Date.now();
+            try {
+                // A rewrite, not a utimes: it also recreates a ticket that was
+                // removed while this process was stopped long enough to look dead.
+                await ensureDir(dir);
+                await writeFile(file, content, 'utf-8');
+            }
+            catch (error) {
+                verbose(`Could not refresh lock waiter ticket ${file}: ${toError(error).message}`);
+            }
+        },
+        deregister: async () => {
+            try {
+                await rm(file, { force: true });
+            }
+            catch (error) {
+                // A leftover ticket of a process about to exit drops out on its own
+                // (dead PID), so this never needs to fail the caller.
+                verbose(`Could not remove lock waiter ticket ${file}: ${toError(error).message}`);
+            }
+        },
+    };
+}
+/**
+ * Renders the queue position for a wait line, with the ordering rule, so the
+ * reader knows the count is a promise and not a snapshot. Empty when nothing
+ * is queued.
+ */
+export function formatLockQueuePosition(queue) {
+    if (queue === undefined || queue.depth === 0)
+        return '';
+    if (queue.ahead === 0) {
+        return ` You are next in a queue of ${queue.depth} (granted in arrival order).`;
+    }
+    return ` ${queue.ahead} ahead of you (queue of ${queue.depth}, granted in arrival order).`;
+}

package/dist/src/core/file-lock-shared.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared holds on a FireForge directory lock.
+ *
+ * Every lock used to be exclusive, so two build-less `fireforge test` runs
+ * on one objdir, each with its own profile and (under auto ports) its own
+ * ports, still waited for each other: the gate's browser tiers ran strictly
+ * serially on a 14-core host. A shared hold lets such runs overlap while
+ * anything that writes (a build, a re-export, a test run that builds)
+ * still holds the lock alone.
+ *
+ * The scheme reuses the exclusive lock as a turnstile, so arrival order and
+ * stale-holder reaping come from the machinery that already exists:
+ *
+ *  - A shared holder takes the exclusive lock in the ordinary way, records
+ *    itself under `<lock>.shared/<uuid>/` (an owner record like the lock's
+ *    own), and releases the exclusive lock at once.
+ *  - An exclusive holder takes the exclusive lock, then waits until no live
+ *    shared holder is left. While it waits it already holds the turnstile,
+ *    so no new shared holder can slip in ahead of it: a writer queued
+ *    behind readers is served once they finish, never starved by newcomers.
+ *
+ * A shared holder whose process died is reaped by the same PID-first
+ * liveness check the exclusive lock uses.
+ */
+/** How a caller holds a lock. */
+export type LockMode = 'exclusive' | 'shared';
+/** The directory holding a lock's shared-holder records. */
+export declare function sharedHoldersDir(lockPath: string): string;
+/**
+ * Counts the live shared holders of a lock, reaping any whose process is
+ * gone. A missing directory means none.
+ *
+ * @param lockPath - The lock directory
+ * @param options - `reap: false` only counts (status reads)
+ */
+export declare function countLiveSharedHolders(lockPath: string, options?: {
+    reap?: boolean;
+}): Promise<number>;
+/** A registered shared hold. */
+export interface SharedHold {
+    /** Removes the hold. Never throws. */
+    release(): Promise<void>;
+}
+/**
+ * Records a shared hold. Call while holding the lock's exclusive turnstile.
+ *
+ * @param lockPath - The lock directory
+ * @param metadata - Owner metadata lines (`command=…`)
+ */
+export declare function registerSharedHold(lockPath: string, metadata: readonly string[] | undefined): Promise<SharedHold>;
+/**
+ * Removes every shared hold this process registered, for the signal path.
+ * Never throws.
+ *
+ * @returns The holder paths removed
+ */
+export declare function releaseSharedHoldsForSignal(): Promise<string[]>;