@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * 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.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+import { isLockOwnerAlive, readLockOwner, writeLockOwner } from './file-lock-owner.js';
+/** The directory holding a lock's shared-holder records. */
+export function sharedHoldersDir(lockPath) {
+    return `${lockPath}.shared`;
+}
+/** Holder directories this process registered, for the signal sweep. */
+const heldShares = new Set();
+/**
+ * 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 async function countLiveSharedHolders(lockPath, options = {}) {
+    const dir = sharedHoldersDir(lockPath);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) === 'ENOENT')
+            return 0;
+        if (options.reap === false)
+            return 0;
+        throw toError(error);
+    }
+    let live = 0;
+    for (const entry of entries) {
+        const holder = join(dir, entry);
+        const owner = await readLockOwner(holder);
+        if (owner.present && isLockOwnerAlive(owner)) {
+            live += 1;
+            continue;
+        }
+        // A record still being written has no owner yet; only an owner that
+        // names a dead process is reaped, so a racing registration survives.
+        if (owner.present && options.reap !== false) {
+            verbose(`Reaping shared hold ${holder}: PID ${owner.pid} is gone.`);
+            await rm(holder, { recursive: true, force: true });
+        }
+    }
+    return live;
+}
+/**
+ * Records a shared hold. Call while holding the lock's exclusive turnstile.
+ *
+ * @param lockPath - The lock directory
+ * @param metadata - Owner metadata lines (`command=…`)
+ */
+export async function registerSharedHold(lockPath, metadata) {
+    const holder = join(sharedHoldersDir(lockPath), randomUUID());
+    await mkdir(holder, { recursive: true });
+    await writeLockOwner(holder, randomUUID(), [...(metadata ?? []), 'mode=shared']);
+    heldShares.add(holder);
+    return {
+        async release() {
+            heldShares.delete(holder);
+            try {
+                await rm(holder, { recursive: true, force: true });
+            }
+            catch (error) {
+                verbose(`Could not remove shared hold ${holder}: ${toError(error).message}`);
+            }
+        },
+    };
+}
+/**
+ * Removes every shared hold this process registered, for the signal path.
+ * Never throws.
+ *
+ * @returns The holder paths removed
+ */
+export async function releaseSharedHoldsForSignal() {
+    const removed = [];
+    for (const holder of [...heldShares]) {
+        heldShares.delete(holder);
+        try {
+            await rm(holder, { recursive: true, force: true });
+            removed.push(holder);
+        }
+        catch {
+            // Shutdown path: nothing to do.
+        }
+    }
+    return removed;
+}

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

@@ -1,5 +1,9 @@
 import { LOCK_PID_FILE } from './file-lock-owner.js';
+import { type LockQueueState } from './file-lock-queue.js';
+import { type LockMode } from './file-lock-shared.js';
 export { LOCK_PID_FILE };
+export { formatLockQueuePosition, type LockQueueState } from './file-lock-queue.js';
+export type { LockMode } from './file-lock-shared.js';
 /**
  * Snapshot of the current lock holder handed to {@link FileLockOptions.onWaitProgress}.
  * `metadata` carries the pid file's human-diagnostic lines (line 3 onward,
@@ -11,20 +15,6 @@ export interface LockHolder {
     alive: boolean;
     metadata: string[];
 }
-/**
- * Live queue state around a contended lock.
- *
- * The lock itself behaves correctly under several concurrent sessions. The
- * gap this closes is visibility. Waiters advertise themselves in a sibling
- * directory so both the wait output and `fireforge status --lock` can say
- * how many are queued and how many are ahead of you.
- */
-export interface LockQueueState {
-    /** Live waiters currently queued for the lock, including this process. */
-    depth: number;
-    /** Live waiters that started waiting before this process. */
-    ahead: number;
-}
 export interface FileLockOptions {
     timeoutMs?: number;
     pollMs?: number;
@@ -32,6 +22,8 @@ export interface FileLockOptions {
      * When set, the poll interval doubles after every contended poll (starting
      * from `pollMs`) up to this cap. When absent, polling stays at the fixed
      * `pollMs` interval, with zero behavior change for existing callers.
+     * Keep it far below `WAITER_STALE_MS` (30 s): a waiter refreshes its queue
+     * ticket between polls, and a ticket left unrefreshed that long is skipped.
      */
     pollMaxMs?: number;
     staleMs?: number;
@@ -94,20 +86,14 @@ export interface FileLockOptions {
     onStaleLockMessage?: (ageMs: number) => string | undefined;
     /** Extra owner-file lines for human diagnostics. Lock mechanics ignore them. */
     ownerMetadata?: readonly string[];
+    /**
+     * `exclusive` (default) or `shared`. Shared holders overlap each other and
+     * exclude exclusive ones; see `file-lock-shared.ts`.
+     */
+    mode?: LockMode | undefined;
 }
 /** Derives the sibling lock-directory path used to guard a file-based resource. */
 export declare function createSiblingLockPath(filePath: string, suffix?: string): string;
-/**
- * Reads the live waiter queue around `lockPath`, dropping entries whose
- * process is gone (a killed waiter must not inflate the depth forever).
- *
- * Advisory and fail-open: an unreadable registry reports an empty queue
- * rather than failing whatever asked.
- *
- * @param lockPath - The lock directory whose queue to inspect
- * @param selfStartedAt - This process's wait start, to compute `ahead`
- */
-export declare function readLockQueue(lockPath: string, selfStartedAt?: number): Promise<LockQueueState>;
 /**
  * Snapshot of a lock for `fireforge status --lock`: who holds
  * it, for how long, and how deep the queue behind it is.
@@ -118,6 +104,8 @@ export interface LockStatusSnapshot {
     /** Milliseconds since the lock directory was created, when held. */
     heldForMs?: number | undefined;
     queueDepth: number;
+    /** Live shared holders (build-less test runs under a shared lock). */
+    sharedHolders?: number | undefined;
 }
 /**
  * Inspects a lock without acquiring it. Read-only and fail-open: a missing

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

@@ -1,14 +1,17 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { randomUUID } from 'node:crypto';
-import { mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { mkdir, rename, rm, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
 import { LockContentionError } from '../errors/base.js';
-import { getNodeErrorCode, isProcessAlive, toError } from '../utils/errors.js';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { ensureDir } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
 import { sleep } from '../utils/sleep.js';
 import { isLockOwnerAlive, LOCK_PID_FILE, readLockOwner, writeLockOwner, } from './file-lock-owner.js';
+import { readLockQueue, registerWaiter, } from './file-lock-queue.js';
+import { countLiveSharedHolders, registerSharedHold, releaseSharedHoldsForSignal, } from './file-lock-shared.js';
 export { LOCK_PID_FILE };
+export { formatLockQueuePosition } from './file-lock-queue.js';
 const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
 const DEFAULT_LOCK_POLL_MS = 50;
 const DEFAULT_STALE_LOCK_MS = 5 * 60_000;
@@ -30,52 +33,14 @@ const WAIT_PROBE_INTERVAL_MS = 5_000;
 export function createSiblingLockPath(filePath, suffix = '.fireforge.lock') {
     return `${filePath}${suffix}`;
 }
-/** Sibling directory in which waiters advertise themselves. */
-function lockWaitersDir(lockPath) {
-    return `${lockPath}.waiters`;
-}
-/** Parsed waiter-file name: `<startedAtMs>-<pid>-<uuid>`. */
-function parseWaiterFileName(name) {
-    const match = /^(\d+)-(\d+)-/.exec(name);
-    const startedAt = match?.[1];
-    const pid = match?.[2];
-    if (startedAt === undefined || pid === undefined)
-        return undefined;
-    return { startedAt: Number.parseInt(startedAt, 10), pid: Number.parseInt(pid, 10) };
-}
-/**
- * Reads the live waiter queue around `lockPath`, dropping entries whose
- * process is gone (a killed waiter must not inflate the depth forever).
- *
- * Advisory and fail-open: an unreadable registry reports an empty queue
- * rather than failing whatever asked.
- *
- * @param lockPath - The lock directory whose queue to inspect
- * @param selfStartedAt - This process's wait start, to compute `ahead`
- */
-export async function readLockQueue(lockPath, selfStartedAt) {
-    let names;
-    try {
-        names = await readdir(lockWaitersDir(lockPath));
-    }
-    catch {
-        return { depth: 0, ahead: 0 };
-    }
-    const live = names
-        .map(parseWaiterFileName)
-        .filter((entry) => entry !== undefined)
-        .filter((entry) => isProcessAlive(entry.pid));
-    const ahead = selfStartedAt === undefined
-        ? 0
-        : live.filter((entry) => entry.startedAt < selfStartedAt).length;
-    return { depth: live.length, ahead };
-}
 /**
  * Inspects a lock without acquiring it. Read-only and fail-open: a missing
  * lock is reported as free, never as an error.
  */
 export async function readLockStatus(lockPath) {
     const queue = await readLockQueue(lockPath);
+    const shared = await countLiveSharedHolders(lockPath, { reap: false });
+    const sharedPart = shared > 0 ? { sharedHolders: shared } : {};
     let heldForMs;
     try {
         // Clamped: filesystem mtime resolution can round a just-created lock
@@ -84,36 +49,13 @@ export async function readLockStatus(lockPath) {
         heldForMs = Math.max(0, Date.now() - (await stat(lockPath)).mtimeMs);
     }
     catch {
-        return { held: false, queueDepth: queue.depth };
+        return { held: false, queueDepth: queue.depth, ...sharedPart };
     }
     const owner = await readLockOwner(lockPath);
     const holder = owner.present
         ? { pid: owner.pid, alive: isLockOwnerAlive(owner), metadata: owner.metadata }
         : undefined;
-    return { held: true, holder, heldForMs, queueDepth: queue.depth };
-}
-/**
- * Registers this process in the lock's waiter queue. Returns a
- * deregistration function that is always safe to call (including when
- * registration itself failed).
- */
-async function registerWaiter(lockPath, startedAt) {
-    const dir = lockWaitersDir(lockPath);
-    const file = join(dir, `${startedAt}-${process.pid}-${randomUUID()}`);
-    try {
-        await ensureDir(dir);
-        await writeFile(file, `${process.pid}\n`, 'utf-8');
-    }
-    catch (error) {
-        // Advisory only. Never fail a lock acquisition over the queue display.
-        verbose(`Could not register lock waiter for ${lockPath}: ${toError(error).message}`);
-        return async () => {
-            /* nothing to remove */
-        };
-    }
-    return async () => {
-        await rm(file, { force: true });
-    };
+    return { held: true, holder, heldForMs, queueDepth: queue.depth, ...sharedPart };
 }
 /**
  * Reads the contended lock's owner and queue in one go. One probe per cycle
@@ -122,12 +64,12 @@ async function registerWaiter(lockPath, startedAt) {
  * degrades to `holder: undefined`, since a diagnostic must never break the
  * wait loop.
  */
-async function probeWaitState(lockPath, startedAt) {
+async function probeWaitState(lockPath, self) {
     const owner = await readLockOwner(lockPath);
     const holder = owner.present
         ? { pid: owner.pid, alive: isLockOwnerAlive(owner), metadata: owner.metadata }
         : undefined;
-    return { holder, queue: await readLockQueue(lockPath, startedAt) };
+    return { holder, queue: await readLockQueue(lockPath, self) };
 }
 /**
  * Reaps a lock directory believed to be stale, safely against concurrent
@@ -345,16 +287,24 @@ function formatQueuePositionReached(queue) {
  * caller asked for it. Split out of the wait loop so the loop stays a
  * readable state machine.
  */
-async function runWaitProbe(lockPath, startedAt, timeoutMs, options) {
-    const { holder, queue } = await probeWaitState(lockPath, startedAt);
+async function runWaitProbe(lockPath, self, timeoutMs, options) {
+    const { holder, queue } = await probeWaitState(lockPath, self);
     options.onWaitProgress?.({
-        waitedMs: Date.now() - startedAt,
+        waitedMs: Date.now() - self.startedAt,
         timeoutMs,
         holder,
         queue,
     });
     return { queue };
 }
+/**
+ * Whether it is this waiter's turn to contend for the lock: no live waiter
+ * arrived before it. Ties and dead or stalled tickets are settled by
+ * {@link readLockQueue}, so every waiter agrees on who is at the head.
+ */
+async function isWaiterTurn(lockPath, startedAt, waiter) {
+    return (await readLockQueue(lockPath, { startedAt, ticket: waiter.ticket })).ahead === 0;
+}
 /**
  * Lock directories this process currently holds.
  *
@@ -387,6 +337,7 @@ export async function forceReleaseHeldLocksForSignal() {
             removed.push(lockPath);
         }
     }
+    removed.push(...(await releaseSharedHoldsForSignal()));
     return removed;
 }
 /** Runs an async operation while holding a directory lock, with stale-lock recovery. */
@@ -404,8 +355,14 @@ export async function withFileLock(lockPath, operation, options = {}) {
     let lastProbeAt = startedAt;
     /** Best (lowest) queue position seen so far. Used to detect an advance. */
     let bestAhead;
-    /** Set on first contention so an uncontended acquire costs nothing. */
-    let deregisterWaiter;
+    /**
+     * This waiter's ticket in the queue. Taken on first contention, or up
+     * front when others are already queued, so an uncontended acquire never
+     * writes one.
+     */
+    let waiter;
+    /** The last `EEXIST`, carried as the cause of a timeout refusal. */
+    let contention;
     // One cadence drives both the progress line and the deadline extension.
     // Either feature alone is enough to want the probe. Neither is worth a
     // second timer.
@@ -414,83 +371,97 @@ export async function withFileLock(lockPath, operation, options = {}) {
         extend !== undefined;
     await ensureDir(dirname(lockPath));
     try {
+        // Arrival order: a newcomer that finds others already queued takes a
+        // ticket behind them instead of racing them for the next free moment.
+        // Without this a fresh command could take the lock in the gap between
+        // the holder's release and the head waiter's next poll.
+        if ((await readLockQueue(lockPath)).depth > 0) {
+            waiter = await registerWaiter(lockPath, startedAt);
+        }
         for (;;) {
-            try {
-                await mkdir(lockPath);
-                break;
-            }
-            catch (error) {
-                if (getNodeErrorCode(error) !== 'EEXIST') {
-                    throw error;
-                }
-                // Advertise this waiter so the queue is visible to the wait output
-                // and to `fireforge status --lock`. Registered lazily:
-                // an uncontended acquisition never touches the registry.
-                deregisterWaiter ??= await registerWaiter(lockPath, startedAt);
-                if (lastStaleProbeAt === undefined || Date.now() - lastStaleProbeAt >= staleReprobeMs) {
-                    lastStaleProbeAt = Date.now();
-                    if (await removeIfStaleLock(lockPath, staleMs, options.onStaleLockMessage)) {
-                        continue;
-                    }
+            // Only the head of the queue contends for the lock. A waiter without
+            // a ticket (no contention seen yet, or a registry that could not be
+            // written) contends as every waiter did before tickets existed.
+            if (waiter?.ticket === undefined || (await isWaiterTurn(lockPath, startedAt, waiter))) {
+                try {
+                    await mkdir(lockPath);
+                    break;
                 }
-                // The probe runs before the deadline check, so a due progress line is
-                // written before the refusal that follows it, never lost to it. On a
-                // slow host (a cold Windows CI runner) the first iteration alone, with
-                // its waiter registration and stale probe, can outlast a short budget;
-                // checked the other way round, the wait timed out having reported
-                // nothing, and an advance that probe would have seen could not extend
-                // the deadline it was about to miss.
-                if (probeWanted && Date.now() - lastProbeAt >= probeIntervalMs) {
-                    lastProbeAt = Date.now();
-                    // Report the budget that is currently in force, not the one
-                    // originally requested: once an extension has been granted, the
-                    // requested figure is stale, and a progress line that keeps
-                    // quoting it reads as a timeout that does not fire.
-                    const probe = await runWaitProbe(lockPath, startedAt, deadline - startedAt, options);
-                    // An advance (someone ahead of us took their turn and finished)
-                    // buys a fresh budget, because the wait is working. Only a queue
-                    // that stops moving starves, which is the case the timeout is for.
-                    //
-                    // The first observation is a seed, never an advance. `bestAhead`
-                    // used to start `undefined`, so the opening probe always satisfied
-                    // this test and handed out a free full budget: a `--wait-lock 300`
-                    // run outlived its 300 s even against a queue that never moved
-                    // once, which is the "it does not reliably give up after N
-                    // seconds" behaviour a downstream fork reported.
-                    if (hardDeadline !== undefined) {
-                        if (bestAhead === undefined) {
-                            bestAhead = probe.queue.ahead;
-                        }
-                        else if (probe.queue.ahead < bestAhead) {
-                            bestAhead = probe.queue.ahead;
-                            deadline = Math.min(Date.now() + timeoutMs, hardDeadline);
-                            options.onWaitExtended?.({
-                                ahead: probe.queue.ahead,
-                                budgetMs: deadline - startedAt,
-                            });
-                        }
+                catch (error) {
+                    if (getNodeErrorCode(error) !== 'EEXIST') {
+                        throw error;
                     }
+                    contention = error;
                 }
-                if (Date.now() >= deadline) {
-                    // The queue is read here, not carried over from the last progress
-                    // probe: the position the wait reached is the one number that says
-                    // whether a larger budget would have helped, and it must not depend
-                    // on a probe having happened to land inside the budget. We are still
-                    // registered at this point. `deregisterWaiter` runs in the `finally`
-                    // below, which is only entered once this refusal has been built.
-                    throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, error, await readLockQueue(lockPath, startedAt));
+            }
+            // Take a ticket so the queue is visible to the wait output and to
+            // `fireforge status --lock`, and so the grant follows arrival order.
+            waiter ??= await registerWaiter(lockPath, startedAt);
+            await waiter.heartbeat();
+            const self = { startedAt, ticket: waiter.ticket };
+            if (lastStaleProbeAt === undefined || Date.now() - lastStaleProbeAt >= staleReprobeMs) {
+                lastStaleProbeAt = Date.now();
+                if (await removeIfStaleLock(lockPath, staleMs, options.onStaleLockMessage)) {
+                    continue;
                 }
-                await sleep(currentPollMs);
-                if (options.pollMaxMs !== undefined) {
-                    currentPollMs = Math.min(currentPollMs * 2, options.pollMaxMs);
+            }
+            // The probe runs before the deadline check, so a due progress line is
+            // written before the refusal that follows it, never lost to it. On a
+            // slow host (a cold Windows CI runner) the first iteration alone, with
+            // its waiter registration and stale probe, can outlast a short budget;
+            // checked the other way round, the wait timed out having reported
+            // nothing, and an advance that probe would have seen could not extend
+            // the deadline it was about to miss.
+            if (probeWanted && Date.now() - lastProbeAt >= probeIntervalMs) {
+                lastProbeAt = Date.now();
+                // Report the budget that is currently in force, not the one
+                // originally requested: once an extension has been granted, the
+                // requested figure is stale, and a progress line that keeps
+                // quoting it reads as a timeout that does not fire.
+                const probe = await runWaitProbe(lockPath, self, deadline - startedAt, options);
+                // An advance (someone ahead of us took their turn and finished)
+                // buys a fresh budget, because the wait is working. Only a queue
+                // that stops moving starves, which is the case the timeout is for.
+                //
+                // The first observation is a seed, never an advance. `bestAhead`
+                // used to start `undefined`, so the opening probe always satisfied
+                // this test and handed out a free full budget: a `--wait-lock 300`
+                // run outlived its 300 s even against a queue that never moved
+                // once, which is the "it does not reliably give up after N
+                // seconds" behaviour a downstream fork reported.
+                if (hardDeadline !== undefined) {
+                    if (bestAhead === undefined) {
+                        bestAhead = probe.queue.ahead;
+                    }
+                    else if (probe.queue.ahead < bestAhead) {
+                        bestAhead = probe.queue.ahead;
+                        deadline = Math.min(Date.now() + timeoutMs, hardDeadline);
+                        options.onWaitExtended?.({
+                            ahead: probe.queue.ahead,
+                            budgetMs: deadline - startedAt,
+                        });
+                    }
                 }
             }
+            if (Date.now() >= deadline) {
+                // The queue is read here, not carried over from the last progress
+                // probe: the position the wait reached is the one number that says
+                // whether a larger budget would have helped, and it must not depend
+                // on a probe having happened to land inside the budget. We are still
+                // registered at this point. The ticket is returned in the `finally`
+                // below, which is only entered once this refusal has been built.
+                throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, contention, await readLockQueue(lockPath, self));
+            }
+            await sleep(currentPollMs);
+            if (options.pollMaxMs !== undefined) {
+                currentPollMs = Math.min(currentPollMs * 2, options.pollMaxMs);
+            }
         }
     }
     finally {
         // Leaving the queue happens the moment we stop waiting, whether we
         // acquired the lock or timed out.
-        await deregisterWaiter?.();
+        await waiter?.deregister();
     }
     // Stamp ownership (PID + per-acquisition token + acquisition time) into
     // the lock directory so stale-lock recovery can check liveness and release
@@ -500,8 +471,36 @@ export async function withFileLock(lockPath, operation, options = {}) {
     // `writeLockOwner` removes the just-created directory before throwing.
     const ownerToken = randomUUID();
     await writeLockOwner(lockPath, ownerToken, options.ownerMetadata);
+    return runWhileHeld(lockPath, ownerToken, operation, options, {
+        deadline: Math.max(deadline, Date.now() + pollMs),
+        pollMs,
+    });
+}
+/**
+ * Runs `operation` once the turnstile is ours: as a shared holder (turnstile
+ * released at once), or exclusively once every shared holder has drained.
+ */
+async function runWhileHeld(lockPath, ownerToken, operation, options, drain) {
+    if (options.mode === 'shared') {
+        // The exclusive lock was only the turnstile: record the shared hold and
+        // let the next waiter in. See file-lock-shared.ts.
+        let hold;
+        try {
+            hold = await registerSharedHold(lockPath, options.ownerMetadata);
+        }
+        finally {
+            await releaseLock(lockPath, ownerToken);
+        }
+        try {
+            return await operation();
+        }
+        finally {
+            await hold.release();
+        }
+    }
     heldLocks.add(lockPath);
     try {
+        await waitForSharedHoldersToDrain(lockPath, drain.deadline, drain.pollMs);
         return await operation();
     }
     finally {
@@ -509,3 +508,27 @@ export async function withFileLock(lockPath, operation, options = {}) {
         await releaseLock(lockPath, ownerToken);
     }
 }
+/**
+ * Holds an exclusive acquisition until every live shared holder has gone.
+ * The turnstile is already ours, so no new shared holder can join meanwhile.
+ *
+ * @throws LockContentionError when shared holders outlast the budget
+ */
+async function waitForSharedHoldersToDrain(lockPath, deadline, pollMs) {
+    let announced = false;
+    for (;;) {
+        const live = await countLiveSharedHolders(lockPath);
+        if (live === 0)
+            return;
+        if (Date.now() >= deadline) {
+            throw new LockContentionError(`Timed out waiting for file lock ${lockPath}: ${live} shared holder(s) (build-less ` +
+                'test runs under a shared lock) still hold it. Wait for them to finish, or retry ' +
+                'with a larger --wait-lock.');
+        }
+        if (!announced) {
+            verbose(`Waiting for ${live} shared holder(s) of ${lockPath} to finish.`);
+            announced = true;
+        }
+        await sleep(Math.max(pollMs, 100));
+    }
+}

package/dist/src/core/furnace-apply-output.d.ts

@@ -2,6 +2,16 @@ import type { ApplyResult, DryRunAction } from '../types/furnace.js';
 type ApplyResultWithActions = ApplyResult & {
     actions?: DryRunAction[];
 };
+/**
+ * The reason breakdown appended to a "skipped N" summary, e.g.
+ * ` (2 already current)`, so `Applied 0, skipped 1` says whether the
+ * component was already current or skipped for another reason without
+ * diffing the deployed files by hand. Empty when nothing was skipped.
+ *
+ * @param skipped - `result.skipped` from applyAllComponents
+ * @returns The parenthesised breakdown with a leading space, or ''
+ */
+export declare function formatSkipBreakdown(skipped: ApplyResult['skipped']): string;
 /**
  * Prints a standard summary of an apply result for both normal and dry-run flows.
  *

package/dist/src/core/furnace-apply-output.js

@@ -1,4 +1,34 @@
 import { error, info, success, warn } from '../utils/logger.js';
+/** Summary label and per-component explanation for each skip kind. */
+const SKIP_KIND_TEXT = {
+    'already-current': {
+        label: 'already current',
+        detail: 'already current: source unchanged since the last recorded apply (from any session) and the engine copy matches it',
+    },
+};
+/** The per-component line text for one skip. */
+function describeSkip(skipped) {
+    return skipped.kind !== undefined ? SKIP_KIND_TEXT[skipped.kind].detail : skipped.reason;
+}
+/**
+ * The reason breakdown appended to a "skipped N" summary, e.g.
+ * ` (2 already current)`, so `Applied 0, skipped 1` says whether the
+ * component was already current or skipped for another reason without
+ * diffing the deployed files by hand. Empty when nothing was skipped.
+ *
+ * @param skipped - `result.skipped` from applyAllComponents
+ * @returns The parenthesised breakdown with a leading space, or ''
+ */
+export function formatSkipBreakdown(skipped) {
+    if (skipped.length === 0)
+        return '';
+    const counts = new Map();
+    for (const entry of skipped) {
+        const label = entry.kind !== undefined ? SKIP_KIND_TEXT[entry.kind].label : entry.reason;
+        counts.set(label, (counts.get(label) ?? 0) + 1);
+    }
+    return ` (${[...counts].map(([label, count]) => `${count} ${label}`).join(', ')})`;
+}
 /**
  * Prints a standard summary of an apply result for both normal and dry-run flows.
  *
@@ -40,7 +70,7 @@ export function logApplyResult(result, isDryRun) {
             success(`${applied.name} (${applied.type}) → ${applied.filesAffected.length} files`);
         }
         for (const skipped of result.skipped) {
-            info(`${skipped.name} — ${skipped.reason}`);
+            info(`${skipped.name} — ${describeSkip(skipped)}`);
         }
         for (const applied of result.applied) {
             if (applied.stepErrors && applied.stepErrors.length > 0) {