@hominis/fireforge 0.41.0 → 0.43.0

package/dist/src/core/display-state.d.ts

@@ -0,0 +1,52 @@
+/**
+ * macOS display power-state probe for the headed no-output stall.
+ *
+ * `TIMEOUT … application timed out after N seconds with no output` /
+ * `Ran 0 checks` has three recorded causes, and one of them is purely
+ * environmental: a HEADED run on an unattended machine whose display is
+ * asleep or locked. A headed Firefox on a sleeping display never paints,
+ * never reaches its first test, and dies at the no-output timeout —
+ * indistinguishable, from the log alone, from a product hang.
+ *
+ * `caffeinate -disu` does not cure it. It PREVENTS sleep; it cannot WAKE a
+ * display that is already asleep, so wrapping the run changes nothing once
+ * the machine has already dimmed. `fireforge test` defaults to headed, so
+ * an unattended run walks straight into this and the operator burns whole
+ * cycles hunting a product cause.
+ *
+ * The probe is advisory and fail-open: anything unexpected reports
+ * `'unknown'` and the caller degrades to the generic triage list rather
+ * than asserting an environment it could not measure.
+ */
+/** Measured display power state, or `'unknown'` when nothing was measured. */
+export type DisplaySleepState = 'asleep' | 'awake' | 'unknown';
+/**
+ * Parses `pmset -g powerstate IODisplayWrangler` output.
+ *
+ * The command prints a header row and then one row per driver, e.g.
+ *
+ * ```
+ * Current power states:
+ *   IODisplayWrangler             4       12    -1
+ * ```
+ *
+ * Only the `IODisplayWrangler` row matters, and only its first numeric
+ * column (the current power state). Any other shape — no such row, a
+ * non-numeric column, an error message — is `'unknown'`, never a guess.
+ *
+ * Pure; exported for direct unit testing.
+ *
+ * @param stdout - Raw `pmset -g powerstate IODisplayWrangler` output
+ * @returns The measured state, or `'unknown'`
+ */
+export declare function parseDisplayPowerState(stdout: string): DisplaySleepState;
+/**
+ * Probes the display's power state. Non-darwin platforms report
+ * `'unknown'` without spawning anything — the stall shape this serves is
+ * a macOS field report and no equivalent single-command probe is wired for
+ * other platforms.
+ *
+ * @param platform - `process.platform`-style id (injected for testability)
+ * @returns The measured state, or `'unknown'` when unmeasurable
+ */
+export declare function probeDisplaySleepState(platform: string): Promise<DisplaySleepState>;

package/dist/src/core/display-state.js

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * macOS display power-state probe for the headed no-output stall.
+ *
+ * `TIMEOUT … application timed out after N seconds with no output` /
+ * `Ran 0 checks` has three recorded causes, and one of them is purely
+ * environmental: a HEADED run on an unattended machine whose display is
+ * asleep or locked. A headed Firefox on a sleeping display never paints,
+ * never reaches its first test, and dies at the no-output timeout —
+ * indistinguishable, from the log alone, from a product hang.
+ *
+ * `caffeinate -disu` does not cure it. It PREVENTS sleep; it cannot WAKE a
+ * display that is already asleep, so wrapping the run changes nothing once
+ * the machine has already dimmed. `fireforge test` defaults to headed, so
+ * an unattended run walks straight into this and the operator burns whole
+ * cycles hunting a product cause.
+ *
+ * The probe is advisory and fail-open: anything unexpected reports
+ * `'unknown'` and the caller degrades to the generic triage list rather
+ * than asserting an environment it could not measure.
+ */
+import { toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+import { exec } from '../utils/process.js';
+/** Bound on the probe so a wedged `pmset` cannot extend a failing run. */
+const DISPLAY_PROBE_TIMEOUT_MS = 5_000;
+/**
+ * IOKit power state at which `IODisplayWrangler` is fully lit. Lower
+ * states are dimmed or off; macOS reports 4 for a live display.
+ */
+const DISPLAY_AWAKE_POWER_STATE = 4;
+/**
+ * Parses `pmset -g powerstate IODisplayWrangler` output.
+ *
+ * The command prints a header row and then one row per driver, e.g.
+ *
+ * ```
+ * Current power states:
+ *   IODisplayWrangler             4       12    -1
+ * ```
+ *
+ * Only the `IODisplayWrangler` row matters, and only its first numeric
+ * column (the current power state). Any other shape — no such row, a
+ * non-numeric column, an error message — is `'unknown'`, never a guess.
+ *
+ * Pure; exported for direct unit testing.
+ *
+ * @param stdout - Raw `pmset -g powerstate IODisplayWrangler` output
+ * @returns The measured state, or `'unknown'`
+ */
+export function parseDisplayPowerState(stdout) {
+    for (const line of stdout.split(/\r?\n/)) {
+        if (!line.includes('IODisplayWrangler'))
+            continue;
+        const match = /IODisplayWrangler\s+(\d+)/.exec(line);
+        const state = match?.[1];
+        if (state === undefined)
+            continue;
+        return Number.parseInt(state, 10) >= DISPLAY_AWAKE_POWER_STATE ? 'awake' : 'asleep';
+    }
+    return 'unknown';
+}
+/**
+ * Probes the display's power state. Non-darwin platforms report
+ * `'unknown'` without spawning anything — the stall shape this serves is
+ * a macOS field report and no equivalent single-command probe is wired for
+ * other platforms.
+ *
+ * @param platform - `process.platform`-style id (injected for testability)
+ * @returns The measured state, or `'unknown'` when unmeasurable
+ */
+export async function probeDisplaySleepState(platform) {
+    if (platform !== 'darwin')
+        return 'unknown';
+    try {
+        const result = await exec('pmset', ['-g', 'powerstate', 'IODisplayWrangler'], {
+            timeout: DISPLAY_PROBE_TIMEOUT_MS,
+        });
+        if (result.exitCode !== 0) {
+            verbose(`Display power-state probe failed (pmset exit ${result.exitCode}).`);
+            return 'unknown';
+        }
+        return parseDisplayPowerState(result.stdout);
+    }
+    catch (error) {
+        verbose(`Display power-state probe failed: ${toError(error).message}`);
+        return 'unknown';
+    }
+}

package/dist/src/core/engine-session-lock.d.ts

@@ -1,3 +1,4 @@
+import { type LockStatusSnapshot } from './file-lock.js';
 export interface EngineSessionLockOptions {
     /**
      * Wait up to this many seconds for the engine session lock instead of the
@@ -12,6 +13,19 @@ export interface EngineSessionLockOptions {
  * one engine-mutating FireForge command touches `engine/` at a time.
  */
 export declare function withEngineSessionLock<T>(projectRoot: string, command: string, operation: () => Promise<T>, options?: EngineSessionLockOptions): Promise<T>;
+/**
+ * Inspects the project's engine-session lock without acquiring it —
+ * backing `fireforge status --lock`.
+ *
+ * @param projectRoot - Project root containing `.fireforge/`
+ * @returns Holder identity, hold duration, and queue depth
+ */
+export declare function readEngineSessionLockStatus(projectRoot: string): Promise<LockStatusSnapshot>;
+/**
+ * Renders the engine-session lock snapshot as operator-facing lines.
+ * Pure, so the wording is unit-testable without a lock on disk.
+ */
+export declare function formatEngineSessionLockStatus(snapshot: LockStatusSnapshot): string[];
 /**
  * Captures an opaque token describing the engine's current commit and working
  * tree, for comparison by {@link assertEngineGenerationUnchanged}.
@@ -21,6 +35,12 @@ export declare function withEngineSessionLock<T>(projectRoot: string, command: s
  * because a probe failure means "nothing was measured", not "nothing changed".
  */
 export declare function snapshotEngineGeneration(engineDir: string): Promise<string>;
+/**
+ * True when a git failure is the transient index-lock contention shape
+ * (`Unable to create '…/.git/index.lock': File exists`) rather than a
+ * durable problem with the checkout. Exported for direct unit testing.
+ */
+export declare function isIndexLockError(error: unknown): boolean;
 /**
  * True when a generation token records a failed probe — i.e. nothing was
  * measured, so the token must never be compared (or hashed) as if it

package/dist/src/core/engine-session-lock.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { info, warn } from '../utils/logger.js';
-import { withFileLock } from './file-lock.js';
+import { readLockStatus, withFileLock } from './file-lock.js';
 import { git } from './git-base.js';
 const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
 /**
@@ -12,13 +12,20 @@ const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
  * the lock's owner-metadata lines (`command=…`, `started=…`); an unreadable
  * owner file degrades to the anonymous form.
  */
-function formatWaitProgressLine(waitedMs, timeoutMs, holder) {
+function formatWaitProgressLine(waitedMs, timeoutMs, holder, queue) {
     const progress = `${String(Math.round(waitedMs / 1000))}s of up to ${String(Math.round(timeoutMs / 1000))}s`;
+    // Queue position: under several concurrent sessions the wait
+    // line alone left operators inferring their place from `ps`.
+    const position = queue === undefined || queue.depth === 0
+        ? ''
+        : queue.ahead === 0
+            ? ` You are next in a queue of ${String(queue.depth)}.`
+            : ` ${String(queue.ahead)} ahead of you (queue of ${String(queue.depth)}).`;
     if (holder === undefined) {
-        return `Waiting for the FireForge engine lock — ${progress}.`;
+        return `Waiting for the FireForge engine lock — ${progress}.${position}`;
     }
     const details = holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '';
-    return `Waiting for the FireForge engine lock held by PID ${String(holder.pid)}${details} — ${progress}.`;
+    return `Waiting for the FireForge engine lock held by PID ${String(holder.pid)}${details} — ${progress}.${position}`;
 }
 /**
  * Runs `operation` while holding the project's engine-session lock, so only
@@ -43,13 +50,13 @@ export async function withEngineSessionLock(projectRoot, command, operation, opt
                 pollMs: 100,
                 pollMaxMs: 2000,
                 waitProgressMs: 5000,
-                onWaitProgress: ({ waitedMs, timeoutMs, holder }) => {
-                    info(formatWaitProgressLine(waitedMs, timeoutMs, holder));
+                onWaitProgress: ({ waitedMs, timeoutMs, holder, queue }) => {
+                    info(formatWaitProgressLine(waitedMs, timeoutMs, holder, queue));
                 },
             }
             : {}),
         ownerMetadata: [`command=${command}`, `started=${new Date().toISOString()}`],
-        // Reason first, remedy second (FORGE H5) — the no-flag default waits
+        // Reason first, remedy second — the no-flag default waits
         // only ~1 s, so contention is the common case and `--wait-lock` is the
         // genuine remedy. withFileLock appends the holder identification from
         // the lock's owner metadata. The leading sentence is a message contract
@@ -60,6 +67,37 @@ export async function withEngineSessionLock(projectRoot, command, operation, opt
         onStaleLockMessage: (ageMs) => `Removed stale FireForge engine session lock (${Math.round(ageMs / 1000)}s old).`,
     });
 }
+/**
+ * Inspects the project's engine-session lock without acquiring it —
+ * backing `fireforge status --lock`.
+ *
+ * @param projectRoot - Project root containing `.fireforge/`
+ * @returns Holder identity, hold duration, and queue depth
+ */
+export async function readEngineSessionLockStatus(projectRoot) {
+    return readLockStatus(join(projectRoot, ENGINE_SESSION_LOCK_PATH));
+}
+/**
+ * Renders the engine-session lock snapshot as operator-facing lines.
+ * Pure, so the wording is unit-testable without a lock on disk.
+ */
+export function formatEngineSessionLockStatus(snapshot) {
+    if (!snapshot.held) {
+        return ['Engine session lock: free (no FireForge engine-mutating command is running).'];
+    }
+    const elapsed = snapshot.heldForMs === undefined
+        ? 'unknown duration'
+        : `${String(Math.round(snapshot.heldForMs / 1000))}s`;
+    const holder = snapshot.holder;
+    const identity = holder === undefined
+        ? 'held by an unidentified process (no readable owner record)'
+        : `held by PID ${String(holder.pid)}${holder.alive ? '' : ' (NOT RUNNING — stale lock)'}` +
+            (holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '');
+    return [
+        `Engine session lock: ${identity}, for ${elapsed}.`,
+        `Queue depth: ${String(snapshot.queueDepth)} waiter(s).`,
+    ];
+}
 /** Prefix marking a generation token whose probe failed. */
 const UNAVAILABLE_PREFIX = 'unavailable:';
 /**
@@ -71,14 +109,46 @@ const UNAVAILABLE_PREFIX = 'unavailable:';
  * because a probe failure means "nothing was measured", not "nothing changed".
  */
 export async function snapshotEngineGeneration(engineDir) {
-    try {
-        const head = (await git(['rev-parse', 'HEAD'], engineDir)).trim();
-        const status = await git(['status', '--porcelain=v1', '-z'], engineDir);
-        return `${head}\0${status}`;
-    }
-    catch (error) {
-        return `${UNAVAILABLE_PREFIX}${toError(error).message}`;
+    let lastError;
+    for (let attempt = 0; attempt < GENERATION_PROBE_ATTEMPTS; attempt += 1) {
+        try {
+            const head = (await git(['rev-parse', 'HEAD'], engineDir)).trim();
+            const status = await git(['status', '--porcelain=v1', '-z'], engineDir);
+            return `${head}\0${status}`;
+        }
+        catch (error) {
+            lastError = error;
+            // A contended `.git/index.lock` is TRANSIENT, not a state: some
+            // other writer held the index for the instant we looked.
+            // Treating it as "unmeasurable" turns a perfectly good suite into
+            // `FAIL reason=inconclusive` on a one-sided probe failure, which is
+            // exactly the false alarm this guard must not raise. Anything else
+            // — an unreadable `.git`, a non-git `engine/` — is a real state and
+            // is reported immediately.
+            if (!isIndexLockError(error) || attempt === GENERATION_PROBE_ATTEMPTS - 1)
+                break;
+            await delay(GENERATION_PROBE_RETRY_MS);
+        }
     }
+    return `${UNAVAILABLE_PREFIX}${toError(lastError).message}`;
+}
+/** Probe attempts before an engine generation is declared unmeasurable. */
+const GENERATION_PROBE_ATTEMPTS = 3;
+/** Pause between generation-probe attempts. */
+const GENERATION_PROBE_RETRY_MS = 250;
+function delay(ms) {
+    return new Promise((resolveDelay) => {
+        setTimeout(resolveDelay, ms);
+    });
+}
+/**
+ * True when a git failure is the transient index-lock contention shape
+ * (`Unable to create '…/.git/index.lock': File exists`) rather than a
+ * durable problem with the checkout. Exported for direct unit testing.
+ */
+export function isIndexLockError(error) {
+    const message = toError(error).message;
+    return /index\.lock/i.test(message);
 }
 /**
  * True when a generation token records a failed probe — i.e. nothing was

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

@@ -0,0 +1,60 @@
+/**
+ * Detects the new-file-plus-moved-code slice shape and names the working
+ * sequence through it.
+ *
+ * A slice that ADDS new files and MOVES lines into them from an existing
+ * patch has no path through the two refusal flags:
+ *
+ *  - `re-export --refuse-adjacent-unmanaged` refuses while the new files
+ *    are still unmanaged; and
+ *  - exporting the new files as their own patch fails cross-patch lint,
+ *    because at the projected placement the OLD patch still contains the
+ *    moved code.
+ *
+ * Each guard is individually correct. Together they dead-end, and the way
+ * out is non-obvious: adopt the new files into the OLD patch first
+ * (`re-export --scan --scan-file`), then split them out into a patch of
+ * their own (`patch move-files --create --order N`).
+ *
+ * This module recognises the shape from evidence FireForge already has —
+ * the pending diff's new-file content versus the added lines the existing
+ * patches carry — so the refusal can name the sequence instead of leaving
+ * the operator to derive it.
+ */
+/** 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. */
+    sharedLines: number;
+}
+/** Minimal queue view this detector needs. */
+export interface MovedCodeQueueEntry {
+    filename: string;
+    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.
+ *
+ * Pure. Overlaps are returned strongest-first so the message names the
+ * most likely source patch.
+ *
+ * @param pendingDiff - The diff the export would write
+ * @param entries - The existing queue's patches
+ * @returns Overlaps, or an empty list when the shape is not present
+ */
+export declare function detectMovedCodeOverlaps(pendingDiff: string, entries: readonly MovedCodeQueueEntry[]): MovedCodeOverlap[];
+/**
+ * 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 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
+ */
+export declare function formatAdoptThenSplitRemedy(overlaps: readonly MovedCodeOverlap[], newPatchName: string, insertionOrder: number): string[];

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

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Detects the new-file-plus-moved-code slice shape and names the working
+ * sequence through it.
+ *
+ * A slice that ADDS new files and MOVES lines into them from an existing
+ * patch has no path through the two refusal flags:
+ *
+ *  - `re-export --refuse-adjacent-unmanaged` refuses while the new files
+ *    are still unmanaged; and
+ *  - exporting the new files as their own patch fails cross-patch lint,
+ *    because at the projected placement the OLD patch still contains the
+ *    moved code.
+ *
+ * Each guard is individually correct. Together they dead-end, and the way
+ * out is non-obvious: adopt the new files into the OLD patch first
+ * (`re-export --scan --scan-file`), then split them out into a patch of
+ * their own (`patch move-files --create --order N`).
+ *
+ * This module recognises the shape from evidence FireForge already has —
+ * the pending diff's new-file content versus the added lines the existing
+ * patches carry — so the refusal can name the sequence instead of leaving
+ * the operator to derive it.
+ */
+import { extractAddedLinesPerFile } from './patch-lint-diff.js';
+/**
+ * Lines too generic to be evidence of a move: closing braces, blank
+ * lines, bare keywords, import punctuation. Requiring substance keeps the
+ * detector from firing on every patch that happens to contain a `}`.
+ */
+function isSubstantiveLine(line) {
+    const trimmed = line.trim();
+    if (trimmed.length < 12)
+        return false;
+    if (/^[)\]};,]+$/.test(trimmed))
+        return false;
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*'))
+        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.
+ *
+ * Pure. Overlaps are returned strongest-first so the message names the
+ * most likely source patch.
+ *
+ * @param pendingDiff - The diff the export would write
+ * @param entries - The existing queue's patches
+ * @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)
+        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)
+            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 });
+        }
+    }
+    return overlaps.sort((a, b) => b.sharedLines - a.sharedLines || a.sourcePatch.localeCompare(b.sourcePatch));
+}
+/**
+ * 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 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
+ */
+export function formatAdoptThenSplitRemedy(overlaps, newPatchName, insertionOrder) {
+    const strongest = overlaps[0];
+    if (strongest === undefined)
+        return [];
+    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
+    // filename: strip the order prefix and the `.patch` suffix so the
+    // suggested command is copy-pasteable.
+    const suggestedName = newPatchName.replace(/^\d+-/, '').replace(/\.patch$/, '');
+    return [
+        '',
+        `This looks like a new-file + moved-code slice: ${String(strongest.sharedLines)} substantive ` +
+            `line(s) the new file(s) would add are still carried by ${strongest.sourcePatch}. ` +
+            'Exporting them as their own patch cannot pass cross-patch lint while the source patch ' +
+            'still owns the same code, and re-exporting cannot adopt them while they are unmanaged — ' +
+            'each guard is right, and together they dead-end.',
+        'Working sequence (adopt, then split):',
+        `  1. fireforge re-export ${strongest.sourcePatch} --scan ${fileArgs}`,
+        `  2. fireforge patch move-files ${strongest.sourcePatch} ${suggestedName} --create --order ${String(insertionOrder)} ${moveArgs}`,
+        'Step 1 adopts the new files into the patch that already owns the moved lines; step 2 ' +
+            'splits them back out as one transaction, so the queue is never in a state where two ' +
+            'patches own the same code.',
+    ];
+}

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

@@ -9,6 +9,21 @@ export interface LockHolder {
     alive: boolean;
     metadata: string[];
 }
+/**
+ * Live queue state around a contended lock.
+ *
+ * Under several concurrent sessions the lock itself behaved correctly; the
+ * gap was VISIBILITY — operators inferred queue state from `ps` and their
+ * own wait lines. 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;
@@ -40,6 +55,8 @@ export interface FileLockOptions {
         waitedMs: number;
         timeoutMs: number;
         holder: LockHolder | undefined;
+        /** Queue state at this poll, when the waiter registry is available. */
+        queue?: LockQueueState | undefined;
     }) => void;
     onTimeoutMessage?: string;
     onStaleLockMessage?: (ageMs: number) => string | undefined;
@@ -55,5 +72,32 @@ export declare function createSiblingLockPath(filePath: string, suffix?: string)
  * re-spelling `'pid'`; the file *format* is documented on {@link readLockOwner}.
  */
 export declare const LOCK_PID_FILE = "pid";
+/**
+ * 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.
+ */
+export interface LockStatusSnapshot {
+    held: boolean;
+    holder?: LockHolder | undefined;
+    /** Milliseconds since the lock directory was created, when held. */
+    heldForMs?: number | undefined;
+    queueDepth: number;
+}
+/**
+ * Inspects a lock without acquiring it. Read-only and fail-open: a missing
+ * lock is reported as free, never as an error.
+ */
+export declare function readLockStatus(lockPath: string): Promise<LockStatusSnapshot>;
 /** Runs an async operation while holding a directory lock, with stale-lock recovery. */
 export declare function withFileLock<T>(lockPath: string, operation: () => Promise<T>, options?: FileLockOptions): Promise<T>;