@hominis/fireforge 0.43.1 → 0.44.0

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

@@ -1,11 +1,19 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
-import { GeneralError } from '../errors/base.js';
+import { InconclusiveVerdictError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { info, warn } from '../utils/logger.js';
 import { readLockStatus, withFileLock } from './file-lock.js';
 import { git } from './git-base.js';
 const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
+/**
+ * How much longer than the requested budget a wait may run while its queue
+ * position keeps improving, and the absolute ceiling on that. The ceiling
+ * matches `--wait-lock`'s own upper bound: an operator who asked for a wait
+ * never gets one longer than the largest wait they could have asked for.
+ */
+const WAIT_EXTENSION_FACTOR = 4;
+const MAX_WAIT_LOCK_MS = 3600 * 1000;
 /**
  * Formats the periodic operator-facing waiting line printed while `--wait-lock`
  * polls a contended engine session lock. The holder identification comes from
@@ -27,6 +35,22 @@ function formatWaitProgressLine(waitedMs, timeoutMs, holder, queue) {
     const details = holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '';
     return `Waiting for the FireForge engine lock held by PID ${String(holder.pid)}${details} — ${progress}.${position}`;
 }
+/**
+ * Formats the notice printed when the wait budget is EXTENDED because the
+ * queue advanced.
+ *
+ * Exported for direct unit testing. It names both figures — the requested
+ * budget and the one now in force — because the whole point is that the two
+ * have diverged, and an operator comparing the elapsed time against the
+ * number they typed would otherwise conclude the timeout is broken.
+ */
+export function formatWaitExtendedLine(ahead, budgetMs, requestedMs) {
+    const position = ahead === 0 ? 'you are now next' : `${String(ahead)} still ahead of you`;
+    return (`The queue advanced (${position}), so the engine-lock wait was extended to ` +
+        `${String(Math.round(budgetMs / 1000))}s total (you asked for ` +
+        `${String(Math.round(requestedMs / 1000))}s). A queue that stops moving still ` +
+        `gives up on the budget you asked for.`);
+}
 /**
  * Runs `operation` while holding the project's engine-session lock, so only
  * one engine-mutating FireForge command touches `engine/` at a time.
@@ -35,9 +59,9 @@ export async function withEngineSessionLock(projectRoot, command, operation, opt
     // The lock is bypassed under test by default, and that is deliberate: the
     // suite runs many engine-mutating commands in-process, which would either
     // serialise on this lock or deadlock outright.
-    // `FIREFORGE_ENABLE_ENGINE_SESSION_LOCK_IN_TEST=1` is what lets the lock's
-    // own tests opt back in. Do not delete this branch — it is the reason the
-    // suite completes, not an oversight.
+    // `FIREFORGE_ENABLE_ENGINE_SESSION_LOCK_IN_TEST=1` lets the lock's own
+    // tests opt back in. Do not delete this branch — it is the reason the
+    // suite completes.
     if (process.env['FIREFORGE_ENABLE_ENGINE_SESSION_LOCK_IN_TEST'] !== '1' &&
         (process.env['NODE_ENV'] === 'test' || process.env['VITEST'] !== undefined)) {
         return operation();
@@ -53,6 +77,22 @@ export async function withEngineSessionLock(projectRoot, command, operation, opt
                 onWaitProgress: ({ waitedMs, timeoutMs, holder, queue }) => {
                     info(formatWaitProgressLine(waitedMs, timeoutMs, holder, queue));
                 },
+                // Say it out loud. An extension is the moment the budget the
+                // operator asked for stops being the budget in force, and a wait
+                // that silently outlives its own stated timeout is
+                // indistinguishable from a broken one — which is how a downstream
+                // fork read it.
+                onWaitExtended: ({ ahead, budgetMs }) => {
+                    info(formatWaitExtendedLine(ahead, budgetMs, waitLockSeconds * 1000));
+                },
+                // A budget that expires one position from the head pays the whole
+                // wait for nothing. While the queue is still MOVING the wait is
+                // working, so each advance renews the budget — up to a hard
+                // ceiling, so a pathological queue cannot wait forever. The
+                // no-flag fail-fast path deliberately gets none of this.
+                extendWhileAdvancing: {
+                    maxWaitMs: Math.min(waitLockSeconds * 1000 * WAIT_EXTENSION_FACTOR, MAX_WAIT_LOCK_MS),
+                },
             }
             : {}),
         ownerMetadata: [`command=${command}`, `started=${new Date().toISOString()}`],
@@ -63,7 +103,8 @@ export async function withEngineSessionLock(projectRoot, command, operation, opt
         // (pinned by engine-session-lock tests); extend, don't reword.
         onTimeoutMessage: `Another FireForge engine-mutating command is already running. ` +
             `Wait for it to finish, then retry \`${command}\` — or pass --wait-lock [seconds] ` +
-            `to wait for the lock (bare --wait-lock waits up to 60 seconds).`,
+            `to wait for the lock (bare --wait-lock waits up to 60 seconds). ` +
+            `Set FIREFORGE_WAIT_LOCK=<seconds> to apply a budget to every command in a session.`,
         onStaleLockMessage: (ageMs) => `Removed stale FireForge engine session lock (${Math.round(ageMs / 1000)}s old).`,
     });
 }
@@ -81,7 +122,7 @@ export async function readEngineSessionLockStatus(projectRoot) {
  * 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) {
+export function formatEngineSessionLockStatus(snapshot, holderCpuSeconds) {
     if (!snapshot.held) {
         return ['Engine session lock: free (no FireForge engine-mutating command is running).'];
     }
@@ -93,10 +134,25 @@ export function formatEngineSessionLockStatus(snapshot) {
         ? '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 [
+    const lines = [
         `Engine session lock: ${identity}, for ${elapsed}.`,
         `Queue depth: ${String(snapshot.queueDepth)} waiter(s).`,
     ];
+    // Liveness answers "does the process exist"; it does not answer "is it
+    // getting anywhere". A holder alive for minutes having used a fraction of
+    // a second of CPU is the shape of a wedged command, and every waiter
+    // behind it inherits the stall. Stated as an observation with its own
+    // caveat — a holder blocked on I/O is also idle, and this must not be read
+    // as licence to kill anything.
+    if (holder?.alive === true && holderCpuSeconds !== undefined) {
+        const cpu = `${holderCpuSeconds.toFixed(1)}s`;
+        const idle = snapshot.heldForMs !== undefined && snapshot.heldForMs > 60_000 && holderCpuSeconds < 2
+            ? ' — near-zero CPU over a long hold, which is what a WEDGED command looks like; ' +
+                'a holder blocked on I/O looks the same, so confirm before acting'
+            : '';
+        lines.push(`Holder CPU time: ${cpu}${idle}.`);
+    }
+    return lines;
 }
 /** Prefix marking a generation token whose probe failed. */
 const UNAVAILABLE_PREFIX = 'unavailable:';
@@ -118,13 +174,12 @@ export async function snapshotEngineGeneration(engineDir) {
         }
         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.
+            // 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. 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);
@@ -162,31 +217,109 @@ export function isUnavailableGenerationToken(token) {
 export function unavailableGenerationReason(token) {
     return token.slice(UNAVAILABLE_PREFIX.length);
 }
+/** How many changed entries the delta names before truncating. */
+const DELTA_ENTRY_LIMIT = 5;
+/**
+ * Splits a generation token into its HEAD and porcelain halves. The porcelain
+ * body is `-z` output, so it is NUL-separated and never quoted.
+ */
+function splitGenerationToken(token) {
+    const separator = token.indexOf('\0');
+    if (separator < 0)
+        return { head: token, body: '' };
+    return { head: token.slice(0, separator), body: token.slice(separator + 1) };
+}
+/**
+ * Parses `git status --porcelain=v1 -z` into `XY path` records.
+ *
+ * The rename/copy shape is the trap: `R`/`C` entries are followed by a
+ * SECOND NUL-separated field carrying the original path, and consuming only
+ * one desynchronises every record after it — turning a one-file rename into
+ * a report that the whole tree moved. Both fields are consumed and the
+ * record renders as `orig -> new`.
+ */
+function parsePorcelainRecords(body) {
+    const fields = body.split('\0').filter((field) => field.length > 0);
+    const records = [];
+    for (let i = 0; i < fields.length; i++) {
+        const field = fields[i] ?? '';
+        // `XY ` — two status characters and a space — then the path.
+        if (field.length < 4)
+            continue;
+        const status = field.slice(0, 2);
+        const path = field.slice(3);
+        if (status.includes('R') || status.includes('C')) {
+            const origin = fields[i + 1];
+            i += 1;
+            records.push(`${status} ${origin ?? '?'} -> ${path}`);
+            continue;
+        }
+        records.push(`${status} ${path}`);
+    }
+    return records;
+}
+/**
+ * Describes what moved between two generation tokens, in operator terms.
+ *
+ * The refusal used to say only THAT the engine changed, which left the
+ * operator to reconstruct the writer by hand — `find -newermt` against the
+ * run window, minus the objdir, minus git's own bookkeeping. Everything
+ * needed to answer it is already in the two tokens, so the refusal answers
+ * it. Pure and total: an unparseable token yields an empty list rather than
+ * an exception, because a diagnostic must never convert a refusal into a
+ * crash.
+ *
+ * @param before - Token captured before the run
+ * @param after - Token captured after the run
+ * @returns Human-readable lines describing the delta; empty when nothing
+ *   could be attributed
+ */
+export function describeEngineGenerationDelta(before, after) {
+    const lines = [];
+    const from = splitGenerationToken(before);
+    const to = splitGenerationToken(after);
+    if (from.head !== to.head) {
+        lines.push(`HEAD moved: ${from.head} -> ${to.head}`);
+    }
+    const beforeRecords = new Set(parsePorcelainRecords(from.body));
+    const afterRecords = new Set(parsePorcelainRecords(to.body));
+    const appeared = [...afterRecords].filter((record) => !beforeRecords.has(record)).sort();
+    const disappeared = [...beforeRecords].filter((record) => !afterRecords.has(record)).sort();
+    const render = (label, records) => {
+        if (records.length === 0)
+            return;
+        const head = records.slice(0, DELTA_ENTRY_LIMIT);
+        const truncated = records.length - head.length;
+        lines.push(`${label}: ${head.join(', ')}${truncated > 0 ? `, … (+${String(truncated)} more)` : ''}`);
+    };
+    render('Working-tree entries that appeared', appeared);
+    render('Working-tree entries that went away', disappeared);
+    return lines;
+}
 /**
  * Throws when the engine's generation token differs from `before`, i.e. the
  * engine was mutated by another writer while a test run was in flight.
  *
- * **An unmeasurable engine warns rather than throws.** `engine/` is not always
- * a git checkout — `fireforge download` extracts a source tarball — so a
- * failed probe is a legitimate state and must not fail the run.
+ * **An unmeasurable engine warns rather than throws.** `engine/` is not
+ * always a git checkout — `fireforge download` extracts a source tarball —
+ * so a failed probe is a legitimate state and must not fail the run.
  *
- * What it must also not do is pass *silently*. Before 0.41.0 the failure token
- * was `unavailable:<message>` and was compared for equality like any other, so
- * a git failure that reproduced across both probes (unreadable `.git`, a
- * permissions problem, a corrupt index) produced identical tokens, took the
- * `after === before` early return, and blessed a verdict the guard had never
- * verified — the precise outcome this guard exists to prevent. Two *differing*
- * failure messages were worse still: they fell through to the mutation branch
- * and reported a spurious "engine/ changed".
+ * What it must also not do is pass *silently*. A failure token compared for
+ * equality like any other would let a git failure that reproduces across
+ * both probes (unreadable `.git`, a permissions problem, a corrupt index)
+ * take the `after === before` early return and bless a verdict the guard
+ * never verified. Two *differing* failure messages are worse still: they
+ * fall through to the mutation branch and report a spurious
+ * "engine/ changed". Hence the prefix comparison rather than a token
+ * comparison — the token embeds the error message, and two genuine failures
+ * rarely phrase it identically.
  *
  * The tolerance is deliberately limited to a probe that failed *both* times:
  * that is the steady state of a non-git `engine/`, and it warns. A one-sided
- * transition is not that state. `engine/` that was measurable and then was not
- * means the second probe measured nothing about a checkout that demonstrably
- * had something to measure; the reverse means there was never a baseline to
- * compare against. Neither is a run whose verdict can be trusted, so both
- * throw. Compare on the prefix rather than the token, because the token embeds
- * the error message and two genuine failures rarely phrase it identically.
+ * transition is not that state. An `engine/` that was measurable and then
+ * was not means the second probe measured nothing about a checkout that
+ * demonstrably had something to measure; the reverse means there was never a
+ * baseline to compare against. Neither verdict can be trusted, so both throw.
  */
 export async function assertEngineGenerationUnchanged(engineDir, before) {
     const after = await snapshotEngineGeneration(engineDir);
@@ -204,12 +337,14 @@ export async function assertEngineGenerationUnchanged(engineDir, before) {
                 'probed afterwards, so there is no baseline to compare against.'
             : `engine/ was probed before the run but could not be probed afterwards ` +
                 `(${unavailableGenerationReason(after)}), so nothing was measured to compare against.`;
-        throw new GeneralError(`${detail}\n\n` +
+        throw new InconclusiveVerdictError(`${detail}\n\n` +
             'This test verdict is inconclusive. Restore engine/ to a readable state, then rebuild ' +
             'and rerun the affected tests.');
     }
     if (after === before)
         return;
-    throw new GeneralError('engine/ changed while `fireforge test` was running, so this test verdict is invalid/inconclusive.\n\n' +
+    const delta = describeEngineGenerationDelta(before, after);
+    throw new InconclusiveVerdictError('engine/ changed while `fireforge test` was running, so this test verdict is invalid/inconclusive.\n\n' +
+        (delta.length > 0 ? `What moved:\n${delta.map((line) => `  ${line}`).join('\n')}\n\n` : '') +
         'Use one writer per engine checkout, then rebuild and rerun the affected tests.');
 }

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

@@ -5,21 +5,21 @@
  * 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
+ *  - `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`).
+ * 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.
+ * 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 {

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

@@ -6,21 +6,21 @@
  * 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
+ *  - `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`).
+ * 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.
+ * 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';
 /**

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

@@ -12,11 +12,10 @@ export interface LockHolder {
 /**
  * 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.
+ * 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. */
@@ -58,6 +57,37 @@ export interface FileLockOptions {
         /** Queue state at this poll, when the waiter registry is available. */
         queue?: LockQueueState | undefined;
     }) => void;
+    /**
+     * When set, a wait whose QUEUE POSITION is still improving is granted a
+     * fresh `timeoutMs` budget on each advance, up to `maxWaitMs` total.
+     *
+     * A fixed wall-clock budget against a queue whose depth the tool knows is
+     * the wrong shape under several concurrent sessions: a wait that expires
+     * one position from the head pays the entire wait and gets nothing. The
+     * distinction that matters is not "how long have I waited" but "is this
+     * queue moving" — a stalled queue still starves on the original budget,
+     * which is the case the timeout exists for.
+     *
+     * Requires the waiter registry (see {@link LockQueueState}); a lock with
+     * no readable queue never extends, because nothing observed an advance.
+     */
+    extendWhileAdvancing?: {
+        maxWaitMs: number;
+    };
+    /**
+     * Invoked when {@link extendWhileAdvancing} actually grants an extension.
+     *
+     * Separate from {@link onWaitProgress} on purpose: an extension is the one
+     * moment the budget the operator asked for stops being the budget in
+     * force, and a wait that silently outlives its stated timeout is
+     * indistinguishable from a broken one. `budgetMs` is the new TOTAL budget
+     * measured from the start of the wait, so it can be compared directly
+     * against the requested figure.
+     */
+    onWaitExtended?: (extension: {
+        ahead: number;
+        budgetMs: number;
+    }) => void;
     onTimeoutMessage?: string;
     onStaleLockMessage?: (ageMs: number) => string | undefined;
     /** Extra owner-file lines for human diagnostics; ignored by lock mechanics. */
@@ -99,5 +129,32 @@ export interface LockStatusSnapshot {
  * lock is reported as free, never as an error.
  */
 export declare function readLockStatus(lockPath: string): Promise<LockStatusSnapshot>;
+/**
+ * Removes a lock directory only if this process still owns it, for callers
+ * that hold no acquisition token.
+ *
+ * The ownership half of {@link releaseLock}, minus the token check — a
+ * signal-time sweeper knows which lock paths its own operations opened, but
+ * not the per-acquisition UUID those acquisitions minted. The PID check is
+ * still the one that matters: it stops the sweeper deleting a lock a
+ * DIFFERENT process acquired in the window between our operation dying and
+ * the sweep running.
+ *
+ * Never throws: callers are shutdown paths where a slow or failing I/O must
+ * not prevent the process from exiting. Returns whether the directory was
+ * removed so callers can log accurately.
+ *
+ * @param lockPath - Lock directory to remove
+ * @returns True when the lock was removed, false when it was left in place
+ */
+export declare function releaseLockIfOwned(lockPath: string): Promise<boolean>;
+/**
+ * Releases every lock this process still holds, for the signal path.
+ *
+ * Never throws and never rejects: a shutdown path must not be able to keep
+ * the process alive. Returns the paths actually removed so the caller can
+ * report accurately.
+ */
+export declare function forceReleaseHeldLocksForSignal(): Promise<string[]>;
 /** 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>;