@hominis/fireforge 0.42.0 → 0.43.0

package/dist/src/commands/re-export-drift.js

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Foreign-drift preview + `--refuse-foreign-drift` gate for `re-export`
- * (FORGE J2).
+ * Foreign-drift preview + `--refuse-foreign-drift` gate for `re-export`.
  *
  * A scan-less re-export rebuilds each patch body as a whole-file
  * `git diff HEAD` over the owned files — so a CONCURRENT session's
@@ -21,6 +20,7 @@
  * payload lines — because a refresh legitimately shifts hunk offsets and
  * context without changing what the patch does.
  */
+import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parseDiffSections } from '../core/patch-parse.js';
 import { toError } from '../utils/errors.js';
@@ -160,7 +160,7 @@ export function computeForeignDrift(oldBody, newBody, previousFilesAffected) {
  * records a refusal and returns `true` so the caller skips the write.
  */
 export async function reportForeignDrift(args) {
-    const { patch, patchesDir, newDiffContent, ctx } = args;
+    const { patch, patchesDir, engineDir, newDiffContent, ctx } = args;
     const oldPath = join(patchesDir, patch.filename);
     let oldBody;
     try {
@@ -181,16 +181,20 @@ export async function reportForeignDrift(args) {
         if (ctx.expectedDriftFiles.has(entry.file))
             ctx.expectedSeen.add(entry.file);
     }
+    const recentlyEdited = await findFilesEditedSinceLastExport(engineDir, oldPath, drift.map((d) => d.file));
     const totalLines = drift.reduce((sum, d) => sum + d.addedLines + d.removedLines, 0);
     const lineNoun = totalLines === 1 ? 'line' : 'lines';
     warn(`${patch.filename}: refreshed body absorbs ${String(totalLines)} ${lineNoun} not present in the old patch body (${String(drift.length)} file(s)):`);
     for (const entry of drift.slice(0, MAX_FILES_REPORTED)) {
         const expectedTag = ctx.expectedDriftFiles.has(entry.file) ? ' (expected via --expect)' : '';
+        const authorshipTag = recentlyEdited.has(entry.file)
+            ? ' [edited since your last export]'
+            : ' [unchanged since your last export — another session may own it]';
         if (entry.binaryChanged) {
-            info(`  ${entry.file}: binary content changed${expectedTag}`);
+            info(`  ${entry.file}: binary content changed${expectedTag}${authorshipTag}`);
             continue;
         }
-        info(`  ${entry.file}: +${String(entry.addedLines)}/-${String(entry.removedLines)} newly captured line(s)${expectedTag}`);
+        info(`  ${entry.file}: +${String(entry.addedLines)}/-${String(entry.removedLines)} newly captured line(s)${expectedTag}${authorshipTag}`);
         for (const summary of entry.hunkSummaries) {
             info(`    ${summary}`);
         }
@@ -212,12 +216,47 @@ export async function reportForeignDrift(args) {
         return true;
     }
     warn('  If these are intentional engine edits, this is the normal re-export flow. ' +
-        'FireForge cannot infer authorship; if another session owns them, re-run with ' +
-        "--refuse-foreign-drift, or commit/stash that session's edits first.");
+        "FireForge cannot PROVE authorship; the per-file tags above compare each file's " +
+        'modification time against this patch\'s last export, so "edited since your last ' +
+        'export" marks lines you most likely wrote yourself. If another session owns them, ' +
+        "re-run with --refuse-foreign-drift, or commit/stash that session's edits first.");
     return false;
 }
 /**
- * Fail-closed baseline handling (FORGE L6): a missing or unreadable old
+ * Splits the drifting files into "you probably wrote this" and "this
+ * predates your last export". `--refuse-foreign-drift` calls every
+ * absorbed line "foreign" — including the operator's OWN additions
+ * from the same session — and "foreign" reads as "another session's",
+ * which is precisely the case where proceeding would be wrong. Authorship
+ * is unknowable, but RECENCY is not: a file whose mtime is newer than the
+ * patch body this run is refreshing changed after the last export, which
+ * on a single-operator slice is the operator's own edit. Returns the
+ * subset of `files` that qualifies; an unstattable path is reported as
+ * NOT recently edited, so the cautious wording is the fallback.
+ */
+async function findFilesEditedSinceLastExport(engineDir, patchBodyPath, files) {
+    const recent = new Set();
+    let patchMtimeMs;
+    try {
+        patchMtimeMs = (await stat(patchBodyPath)).mtimeMs;
+    }
+    catch (error) {
+        verbose(`Could not stat ${patchBodyPath} for drift recency: ${toError(error).message}`);
+        return recent;
+    }
+    for (const file of files) {
+        try {
+            if ((await stat(join(engineDir, file))).mtimeMs > patchMtimeMs)
+                recent.add(file);
+        }
+        catch (error) {
+            verbose(`Could not stat ${file} for drift recency: ${toError(error).message}`);
+        }
+    }
+    return recent;
+}
+/**
+ * Fail-closed baseline handling: a missing or unreadable old
  * patch body means the drift comparison CANNOT run, so under
  * `--refuse-foreign-drift` the patch is refused rather than written on the
  * strength of a check that never happened. Without the flag this stays the

package/dist/src/commands/re-export-lint.d.ts

@@ -1,5 +1,5 @@
 /**
- * Hoisted + cached lint context for `re-export` (FORGE J1).
+ * Hoisted + cached lint context for `re-export`.
  *
  * The per-patch loop used to rebuild the whole patch-queue context AND a
  * fresh queue-wide checkJs TypeScript program for every patch — ~37 s of
@@ -8,7 +8,7 @@
  *
  * - builds the queue context and the {@link PerRunCheckJs} program
  *   controller ONCE per invocation (`buildReExportLintContext`) and slices
- *   per-patch findings out of it (the FORGE I3 shape `move-files`/`split`
+ * per-patch findings out of it (the shape `move-files`/`split`
  *   already use, plus the program-level hoist `lint --per-patch` has);
  * - reuses the existing per-patch lint RESULT cache
  *   (`.fireforge/lint-cache/per-patch-v1.json`) across invocations —
@@ -17,7 +17,7 @@
  *   hashes engine HEAD, per-file content, patch body, config, shims, and
  *   ownership, so a repeat single re-export is a warm hit (~4 s instead
  *   of ~41 s). `--no-cache` opts out; run-level checkJs globals are
- *   never cached (FORGE F5) and are emitted once per invocation;
+ * never cached and are emitted once per invocation;
  * - keeps the in-memory queue context honest after each write
  *   (`refreshQueueCtxEntry`), so later iterations of an `--all` run lint
  *   against the just-refreshed body instead of the stale one.
@@ -34,7 +34,7 @@ export interface ReExportLintContext {
     paths: ReturnType<typeof getProjectPaths>;
     config: FireForgeConfig;
     /** Whole-queue context, built WITH config so the forward-import hints
-     *  match `lint --per-patch` (FORGE F14); undefined when no patches dir. */
+     * match `lint --per-patch`; undefined when no patches dir. */
     patchQueueCtx: PatchQueueContext | undefined;
     /** Queue-wide checkJs controller; undefined when checkJs is off. */
     checkJs: PerRunCheckJs | undefined;
@@ -46,13 +46,15 @@ export interface ReExportLintContext {
     /** Run-level checkJs globals are emitted once per invocation. */
     globalsEmitted: boolean;
 }
-/** Builds the once-per-invocation lint context (FORGE J1). */
+/** Builds the once-per-invocation lint context. */
 export declare function buildReExportLintContext(projectRoot: string, paths: ReturnType<typeof getProjectPaths>, config: Awaited<ReturnType<typeof loadConfig>>, noCache: boolean): Promise<ReExportLintContext>;
 /** Fresh lint payload carried to the post-write cache store. */
 export interface ReExportLintResult {
     issues: PatchLintIssue[];
     suppressed: PatchLintIssue[];
     lineCount: number;
+    /** Waiver ids in force for this lint run. */
+    lintIgnore: string[];
 }
 /**
  * Lints one re-exported patch body using the hoisted context: cache hit →

package/dist/src/commands/re-export-lint.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Hoisted + cached lint context for `re-export` (FORGE J1).
+ * Hoisted + cached lint context for `re-export`.
  *
  * The per-patch loop used to rebuild the whole patch-queue context AND a
  * fresh queue-wide checkJs TypeScript program for every patch — ~37 s of
@@ -9,7 +9,7 @@
  *
  * - builds the queue context and the {@link PerRunCheckJs} program
  *   controller ONCE per invocation (`buildReExportLintContext`) and slices
- *   per-patch findings out of it (the FORGE I3 shape `move-files`/`split`
+ * per-patch findings out of it (the shape `move-files`/`split`
  *   already use, plus the program-level hoist `lint --per-patch` has);
  * - reuses the existing per-patch lint RESULT cache
  *   (`.fireforge/lint-cache/per-patch-v1.json`) across invocations —
@@ -18,7 +18,7 @@
  *   hashes engine HEAD, per-file content, patch body, config, shims, and
  *   ownership, so a repeat single re-export is a warm hit (~4 s instead
  *   of ~41 s). `--no-cache` opts out; run-level checkJs globals are
- *   never cached (FORGE F5) and are emitted once per invocation;
+ * never cached and are emitted once per invocation;
  * - keeps the in-memory queue context honest after each write
  *   (`refreshQueueCtxEntry`), so later iterations of an `--all` run lint
  *   against the just-refreshed body instead of the stale one.
@@ -33,7 +33,7 @@ import { pathExists } from '../utils/fs.js';
 import { info } from '../utils/logger.js';
 import { reportPatchLintOutcome } from './export-shared.js';
 import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
-/** Builds the once-per-invocation lint context (FORGE J1). */
+/** Builds the once-per-invocation lint context. */
 export async function buildReExportLintContext(projectRoot, paths, config, noCache) {
     const patchQueueCtx = (await pathExists(paths.patches))
         ? await buildPatchQueueContext(paths.patches, config)
@@ -93,7 +93,7 @@ export async function lintReExportedPatch(args) {
             : 'Lint: branding threshold tier applied (patch is all under browser/branding/ plus registration siblings).');
     }
     // Run-level checkJs globals surface exactly once per invocation, never
-    // from the cache (FORGE F5). On an all-warm run this is a cheap probe,
+    // from the cache. On an all-warm run this is a cheap probe,
     // not a program build.
     let globalIssues = [];
     if (checkJs && !lintCtx.globalsEmitted) {
@@ -111,7 +111,7 @@ export async function lintReExportedPatch(args) {
             queueContext: patchQueueCtx,
             ...(lintCtx.engineHeadSha === undefined ? {} : { engineHeadSha: lintCtx.engineHeadSha }),
         });
-        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey);
+        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey, args.ignoreChecks);
         if (cached) {
             lintCtx.reusedCacheEntries++;
             reportPatchLintOutcome([...globalIssues, ...cached.issues], args.skipLint);
@@ -131,7 +131,7 @@ export async function lintReExportedPatch(args) {
         else {
             // Fresh `--scan` adoption created checkJs-relevant files the hoisted
             // program has never seen — fall back to a per-patch build with the
-            // usual report scope so nothing is silently unchecked (FORGE F5).
+            // usual report scope so nothing is silently unchecked.
             lintOptions.checkJsReportScope = resolvePatchOwnedSysMjs(detectNewFilesInDiff(diffContent));
         }
     }
@@ -144,6 +144,7 @@ export async function lintReExportedPatch(args) {
         issues,
         suppressed: suppressedIssues,
         lineCount: countNonBinaryDiffLines(diffContent).textLines,
+        lintIgnore: [...(args.ignoreChecks ?? [])],
     };
 }
 /**
@@ -166,7 +167,7 @@ export async function storeReExportLintResult(lintCtx, patchFilename, projectedM
         queueContext: patchQueueCtx,
         ...(lintCtx.engineHeadSha === undefined ? {} : { engineHeadSha: lintCtx.engineHeadSha }),
     });
-    setCachedPerPatchLintIssues(cache, patchFilename, cacheKey, result.issues, result.suppressed, result.lineCount);
+    setCachedPerPatchLintIssues(cache, patchFilename, cacheKey, result.issues, result.suppressed, result.lineCount, result.lintIgnore);
     lintCtx.cacheDirty = true;
 }
 /**

package/dist/src/commands/re-export-single.d.ts

@@ -1,6 +1,6 @@
 /**
  * Single-patch refresh core for `fireforge re-export`, split out of
- * `re-export.ts` (at the per-file line budget after the FORGE J1/J2
+ * `re-export.ts` (at the per-file line budget after the
  * hoisted-lint and foreign-drift wiring). The orchestrator loop calls
  * {@link reExportSinglePatchWithIndexLockRetry} per selected patch.
  */

package/dist/src/commands/re-export-single.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Single-patch refresh core for `fireforge re-export`, split out of
- * `re-export.ts` (at the per-file line budget after the FORGE J1/J2
+ * `re-export.ts` (at the per-file line budget after the
  * hoisted-lint and foreign-drift wiring). The orchestrator loop calls
  * {@link reExportSinglePatchWithIndexLockRetry} per selected patch.
  */
@@ -133,7 +133,7 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
         warn(`Skipped ${patch.filename}: no changes (files unchanged from HEAD)`);
         return false;
     }
-    // Foreign-drift preview + optional hard stop (FORGE J2): show which
+    // Foreign-drift preview + optional hard stop: show which
     // payload lines are about to enter the body that the old body did not
     // carry — the case where a concurrent session's uncommitted edits in
     // OWNED files would be silently absorbed. Always previews (including
@@ -141,6 +141,7 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
     if (await reportForeignDrift({
         patch,
         patchesDir: paths.patches,
+        engineDir: paths.engine,
         newDiffContent: diffContent,
         ctx: driftCtx,
     })) {
@@ -155,7 +156,7 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
     });
     // Lint against the ONCE-per-invocation hoisted context (queue context +
     // queue-wide checkJs program + per-patch result cache) instead of
-    // rebuilding ~37 s of setup for every patch in the loop (FORGE J1).
+    // rebuilding ~37 s of setup for every patch in the loop.
     const projectedMetadata = { ...patch, ...updates };
     const lintResult = await lintReExportedPatch({
         lintCtx,
@@ -200,7 +201,7 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
  * leave body and `filesAffected` disagreeing), then keeps the run's
  * in-memory state honest: the queue context entry is refreshed and the
  * fresh lint result is stored keyed against the just-written body — the
- * state a repeat invocation will observe (FORGE J1) — and the in-memory
+ * state a repeat invocation will observe — and the in-memory
  * manifest row mirrors the on-disk write for later loop iterations
  * (notably `--all --scan`, where `getClaimedFiles` reads this manifest).
  */

package/dist/src/commands/re-export.js

@@ -3,6 +3,7 @@ import { multiselect } from '@clack/prompts';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { isGitRepository } from '../core/git.js';
+import { formatPatchNotFoundError } from '../core/patch-identifier-suggest.js';
 import { loadPatchesManifest, resolvePatchIdentifier, stampPatchVersions, } from '../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { elapsedSince } from '../utils/elapsed.js';
@@ -24,8 +25,9 @@ async function resolveSelectedPatches(patches, options, manifest) {
         for (const identifier of patches) {
             const match = resolvePatchIdentifier(identifier, manifest.patches);
             if (!match) {
-                const available = manifest.patches.map((p) => p.filename).join(', ');
-                throw new InvalidArgumentError(`Patch "${identifier}" not found in manifest.\n\nAvailable patches: ${available}`, identifier);
+                // Suggest, never dump: a wrong guess used to print the
+                // whole ~300-entry manifest, burying the error it was reporting.
+                throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
             }
             selectedPatches.push(match);
         }
@@ -123,7 +125,7 @@ export async function reExportCommand(projectRoot, patches, options) {
     }
     const config = await loadConfig(projectRoot);
     // Classification inputs for the scan-less adjacency advisory, computed
-    // once for the whole run (FORGE G2).
+    // once for the whole run.
     const adjacentCtx = {
         binaryName: config.binaryName,
         furnacePrefixes: await collectFurnaceManagedPrefixes(paths.root),
@@ -131,7 +133,7 @@ export async function reExportCommand(projectRoot, patches, options) {
         refusals: [],
     };
     const driftCtx = buildForeignDriftContext(options);
-    // Hoisted lint context, one per run (FORGE J1): queue context + checkJs
+    // Hoisted lint context, one per run: queue context + checkJs
     // program + per-patch result cache, shared across every loop iteration.
     const lintCtx = await buildReExportLintContext(projectRoot, paths, config, options.noCache === true);
     let reExported = 0;
@@ -189,8 +191,8 @@ export async function reExportCommand(projectRoot, patches, options) {
     });
 }
 /**
- * Foreign-drift guard context, one per run (FORGE J2). `--expect` paths
- * (FORGE L6) are normalized once here so the per-patch comparison matches
+ * Foreign-drift guard context, one per run. `--expect` paths
+ * are normalized once here so the per-patch comparison matches
  * them against engine-relative diff-section paths.
  */
 function buildForeignDriftContext(options) {
@@ -203,7 +205,7 @@ function buildForeignDriftContext(options) {
     };
 }
 /**
- * Names `--expect` paths that never drifted this run (FORGE L6). A typo'd
+ * Names `--expect` paths that never drifted this run. A typo'd
  * `--expect` path silently degrades the flag back to refusing the slice it
  * was meant to admit, so surface the mismatch — but only as a warning: an
  * expected file legitimately shows no drift when the slice was already
@@ -217,11 +219,16 @@ function warnUnseenExpectedDrift(driftCtx) {
         warn(`--expect path(s) were not evaluated because no selected patch reached the drift check (for example, an earlier refusal): ${unseen.join(', ')}`);
         return;
     }
-    warn(`--expect path(s) showed no drift this run (typo, or already captured?): ${unseen.join(', ')}`);
+    warn('--expect path(s) showed no drift this run: ' +
+        `${unseen.join(', ')}. ` +
+        'Causes, in rough order of likelihood: a typo in the path; the slice was already ' +
+        'captured by an earlier export in this session; or the engine content already matches ' +
+        'the patch body — a concurrent session may have exported the same change, so the drift ' +
+        'converged before this run looked.');
 }
 /**
- * Turns the run's collected `--refuse-adjacent-unmanaged` (FORGE G2) and
- * `--refuse-foreign-drift` (FORGE J2) refusals into the non-zero exit,
+ * Turns the run's collected `--refuse-adjacent-unmanaged` and
+ * `--refuse-foreign-drift` refusals into the non-zero exit,
  * naming every refused patch and the remedy.
  */
 function throwRunLevelRefusals(adjacentCtx, driftCtx, progress) {
@@ -240,13 +247,18 @@ function throwRunLevelRefusals(adjacentCtx, driftCtx, progress) {
             ? ` ${String(unreadable.length)} of these refused because the old patch body was missing or unreadable, so the drift comparison could not run (fail-closed).`
             : '';
         throw new GeneralError(`Refused ${String(driftCtx.refusals.length)} patch(es) whose refreshed body would absorb ` +
-            `engine edits not present in the old patch body (--refuse-foreign-drift): ${names}.${unreadablePart} ` +
-            `Commit or stash the foreign edits (another session may own them), name the slice's ` +
-            `intended files with --expect <path>, or re-run without the flag to capture them intentionally.`);
+            `engine edits not present in the old patch body (--refuse-foreign-drift): ${names}.${unreadablePart}\n\n` +
+            'The flag cannot tell WHO wrote those lines, and the two populations have opposite ' +
+            'remedies:\n' +
+            '  - Lines you added yourself since the last export (the per-file report tags these ' +
+            '"edited since your last export"): name them with --expect <path> so this run captures ' +
+            'them, or re-run without the flag to capture every drifting file.\n' +
+            "  - Lines another session owns: do NOT proceed — commit or stash that session's work " +
+            'first, then re-run.');
     }
 }
 /**
- * Prints the end-of-run summary and enforces the FORGE H8 exit contract:
+ * Prints the end-of-run summary and enforces the exit contract:
  * a partial run exits non-zero BY DEFAULT (adjudicated for 0.41.0, per the
  * follow-up 0.40.0's G7 recorded). "Re-exported 2 of 3" used to print and
  * exit 0, letting a partial refresh ride an `&&` chain as success. The

package/dist/src/commands/reset.js

@@ -70,7 +70,7 @@ export async function resetCommand(projectRoot, options) {
         s.stop('Changes reset');
         // The reset may have moved components.conf away from what the last full
         // build compiled in — surface that now instead of at the next test
-        // refusal (FORGE F13).
+        // refusal.
         await warnIfStaticComponentsStale(projectRoot, paths.engine);
         outro('Working tree restored to clean state');
     }

package/dist/src/commands/run.js

@@ -312,7 +312,7 @@ function reportSmokeSummary(args) {
     info(`  Allowlisted error hits (suppressed): ${String(args.allowlistedErrorHits)}`);
     info(`  Allowlisted lines total: ${String(args.allowlistedTotalHits)}`);
     info(`  Child exit code:  ${String(args.exitCode)}`);
-    // Per-entry attribution (FORGE G8): first-match credit per line, with
+    // Per-entry attribution: first-match credit per line, with
     // zero-hit entries always visible — an allowlist entry whose suppressed
     // shape changed upstream is only detectable as a 0× row.
     if (args.allowlist.length > 0) {

package/dist/src/commands/source.js

@@ -4,15 +4,14 @@ import { configExists, loadRawConfigDocument, validateConfig, withConfigFileLock
 import { resolveArchive } from '../core/firefox-archive.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { info, intro, outro, success } from '../utils/logger.js';
-import { FIREFOX_PRODUCTS, isValidFirefoxCandidate, isValidFirefoxProduct, } from '../utils/validation.js';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
+import { FIREFOX_PRODUCTS, isJsonObject, isObject, isValidFirefoxCandidate, isValidFirefoxProduct, } from '../utils/validation.js';
 function cloneRawConfig(raw) {
     const cloned = structuredClone(raw);
-    if (!isRecord(cloned)) {
+    if (!isObject(cloned)) {
         throw new GeneralError('Cannot update fireforge.json: config clone was not an object.');
     }
+    // A structured clone of a JSON document is itself a JSON document; the
+    // object check above is the only invariant left to establish.
     return cloned;
 }
 function parseSourceProduct(product) {
@@ -44,7 +43,8 @@ export async function sourceSetCommand(projectRoot, options) {
     const written = await withConfigFileLock(projectRoot, async () => {
         const raw = await loadRawConfigDocument(projectRoot);
         const updated = cloneRawConfig(raw);
-        const firefox = isRecord(updated['firefox']) ? { ...updated['firefox'] } : {};
+        const existingFirefox = updated['firefox'];
+        const firefox = isJsonObject(existingFirefox) ? { ...existingFirefox } : {};
         firefox['version'] = options.version;
         firefox['product'] = options.product;
         if (options.clearSha256 === true) {

package/dist/src/commands/status-check.d.ts

@@ -1,5 +1,5 @@
 /**
- * `status --check` enforcement policy (FORGE G1). Turns the classified
+ * `status --check` enforcement policy. Turns the classified
  * status view into a CI-enforceable non-zero exit: the default policy
  * fails on any classification outside {patch-backed, branding, furnace},
  * and `--fail-on <class,...>` replaces that set for finer control.

package/dist/src/commands/status-check.js

@@ -12,7 +12,7 @@ const ALL_CLASSIFICATIONS = [
  * Default `--check` policy: everything outside {patch-backed, branding,
  * furnace, binary-unsupported} fails. `binary-unsupported` is deliberately
  * excluded — an honest "cannot compare" must not keep the gate permanently
- * red (FORGE J3); strict CI can opt in via `--fail-on binary-unsupported`.
+ * red; strict CI can opt in via `--fail-on binary-unsupported`.
  */
 const DEFAULT_FAIL_CLASSIFICATIONS = [
     'unmanaged',

package/dist/src/commands/status-json.d.ts

@@ -5,7 +5,7 @@
  *
  * Two shapes share one counting pass:
  * - the full payload (`renderJsonStatus`) with the per-file `files[]` list;
- * - the `--summary` gate payload (`renderJsonSummaryStatus`, FORGE K8),
+ * - the `--summary` gate payload (`renderJsonSummaryStatus`),
  *   which omits `files[]` entirely — engine-clean gates need the verdict,
  *   per-class counts, and offender names, not a payload that grows with
  *   the queue (175 KB+ observed on a 290-patch consumer).
@@ -15,7 +15,7 @@ import { type StatusCheckPolicy } from './status-check.js';
 import type { OwnershipJsonBlock } from './status-ownership.js';
 /**
  * Full `--json` payload: summary plus the per-file `files[]` list, and —
- * under `--include-ownership` (FORGE L3) — the additive `ownership` block.
+ * under `--include-ownership` — the additive `ownership` block.
  * Additive within schemaVersion 1: a consumer that does not ask for the
  * block never sees the key.
  */

package/dist/src/commands/status-json.js

@@ -16,7 +16,7 @@ function countByClassification(classified) {
 }
 /**
  * Full `--json` payload: summary plus the per-file `files[]` list, and —
- * under `--include-ownership` (FORGE L3) — the additive `ownership` block.
+ * under `--include-ownership` — the additive `ownership` block.
  * Additive within schemaVersion 1: a consumer that does not ask for the
  * block never sees the key.
  */

package/dist/src/commands/status-output.d.ts

@@ -14,7 +14,7 @@ export declare function renderUnmanagedOnly(unmanagedFiles: ClassifiedFile[], to
 /** Renders the default classified status buckets. */
 export declare function renderDefaultStatus(totalModified: number, buckets: ClassifiedBuckets, projectRoot: string, binaryName: string): Promise<void>;
 /**
- * Renders `fireforge status --test-coverage` (FORGE F11): a READ-ONLY view
+ * Renders `fireforge status --test-coverage`: a READ-ONLY view
  * of the last build baseline's test-packaging coverage. Before this
  * existed, the only way to learn the recorded coverage scope — which
  * concurrent sessions sharing one engine tree overwrite constantly — was

package/dist/src/commands/status-output.js

@@ -191,7 +191,7 @@ export async function renderDefaultStatus(totalModified, buckets, projectRoot, b
     outro(parts.join(', '));
 }
 /**
- * Renders `fireforge status --test-coverage` (FORGE F11): a READ-ONLY view
+ * Renders `fireforge status --test-coverage`: a READ-ONLY view
  * of the last build baseline's test-packaging coverage. Before this
  * existed, the only way to learn the recorded coverage scope — which
  * concurrent sessions sharing one engine tree overwrite constantly — was

package/dist/src/commands/status.js

@@ -2,6 +2,7 @@
 import { Command } from 'commander';
 import { readBuildBaseline } from '../core/build-baseline.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { formatEngineSessionLockStatus, readEngineSessionLockStatus, } from '../core/engine-session-lock.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getHead, getStatusWithCodes, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { getUntrackedFilesInDir, resolveMaxUntrackedFilesPerDir } from '../core/git-status.js';
@@ -96,7 +97,7 @@ async function classifyStatusFiles(files, paths, projectRoot, binaryName) {
  * The one worktree scan every classifying mode shares: porcelain status,
  * collapsed-directory expansion, atomic-temp-file filtering, and the
  * truncation banner. `--ownership` used to carry its own copy of this
- * block (FORGE L3); a non-git engine degrades to an empty list there,
+ * block; a non-git engine degrades to an empty list there,
  * which is why the git probe is a parameter rather than a hard guard.
  * @param engineDir - Path to the engine directory
  * @param requireGitRepository - When false, a non-git engine yields `[]`
@@ -114,7 +115,7 @@ async function scanEngineStatusFiles(engineDir, requireGitRepository) {
  * Emits the `--json` payload (full or `--summary`) and applies the
  * `--check` policy, which stays the SOLE exit driver on this path.
  *
- * `--include-ownership` (FORGE L3) is a MODIFIER, not a mode: it appends an
+ * `--include-ownership` is a MODIFIER, not a mode: it appends an
  * ownership block without touching exit semantics, so an ownership conflict
  * still fails only the human `--ownership` mode.
  * @param classified - Classified worktree entries
@@ -201,27 +202,39 @@ async function runStatusCommandBody(projectRoot, options) {
         options.ownership,
         options.testCoverage,
         options.json,
+        options.lock,
     ].filter((v) => v === true).length;
     if (modeCount > 1) {
-        throw new GeneralError('Cannot use --raw, --unmanaged, --ownership, --test-coverage, and --json together. Pick at most one.');
+        throw new GeneralError('Cannot use --raw, --unmanaged, --ownership, --test-coverage, --lock, and --json together. Pick at most one.');
     }
-    // --summary elides the files[] payload for gate consumers (FORGE K8);
+    // --summary elides the files[] payload for gate consumers;
     // it only makes sense on the JSON shape.
     if (options.summary === true && options.json !== true) {
         throw new InvalidArgumentError('--summary requires --json.', '--summary');
     }
     // --include-ownership adds a block to the JSON payload; it is meaningless
     // on the human views, where --ownership is the mode that renders the
-    // table (FORGE L3).
+    // table.
     if (options.includeOwnership === true && options.json !== true) {
         throw new InvalidArgumentError('--include-ownership requires --json. Use --ownership for the human table.', '--include-ownership');
     }
-    // --check / --fail-on enforcement policy (FORGE G1). Applies only
+    // --check / --fail-on enforcement policy. Applies only
     // where classification runs (the default view and --json).
     const checkPolicy = resolveStatusCheckPolicy(options);
     if (!options.raw && !options.json) {
         intro('FireForge Status');
     }
+    // Lock visibility. Placed before every engine/git guard: the
+    // whole point is to answer "who is holding this?" on a checkout that a
+    // concurrent command is busy with, and that answer must not depend on
+    // engine/ being readable.
+    if (options.lock === true) {
+        for (const line of formatEngineSessionLockStatus(await readEngineSessionLockStatus(projectRoot))) {
+            info(line);
+        }
+        outro('Lock status');
+        return;
+    }
     // Test-coverage mode needs only the project root (the baseline lives
     // in .fireforge/), so it short-circuits before any engine/git guards.
     if (options.testCoverage) {
@@ -247,7 +260,7 @@ async function runStatusCommandBody(projectRoot, options) {
         }
         const manifest = await loadPatchesManifest(paths.patches);
         // Same scan and the SAME classification pass as every other mode
-        // (FORGE L3). This branch keeps its historical guard shape on purpose:
+        //. This branch keeps its historical guard shape on purpose:
         // no baseline-commit assertion, and a non-git engine degrades to an
         // empty table rather than the recovery banner.
         const rawFilesOwnership = await scanEngineStatusFiles(paths.engine, false);
@@ -336,6 +349,7 @@ export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
         .command('status')
         .description('Show modified files in engine/')
         .option('--raw', 'Show raw worktree status without patch classification')
+        .option('--lock', 'Report the engine session lock instead of file status: holder pid, its command, how long it has held the lock, and how many waiters are queued behind it (read-only; never acquires it)')
         .option('--unmanaged', 'Show only unmanaged changes (not covered by patches or tools)')
         .option('--ownership', 'Show a flat path → owning patch table (flags files claimed by multiple patches)')
         .option('--test-coverage', 'Show what the last recorded build covers for test packaging (full or scoped paths)')

package/dist/src/commands/test-build-phase.d.ts

@@ -1,7 +1,7 @@
 /**
  * Pre-test build phase for `fireforge test`, split out of `test.ts` (at
  * the per-file line budget): the incremental protected mach build with
- * its baseline write, and the FORGE J9 `--build-only` union-build shape.
+ * its baseline write, and the `--build-only` union-build shape.
  */
 import type { getProjectPaths, loadConfig } from '../core/config.js';
 import type { TestOptions } from '../types/commands/index.js';
@@ -9,7 +9,7 @@ import type { HarnessClassification } from './test-modes.js';
 /**
  * Runs the pre-test build (or the stale-build gate when no build was
  * requested). Returns `true` when the run is COMPLETE — the `--build-only`
- * union-build shape (FORGE J9), which packages every requested path
+ * union-build shape, which packages every requested path
  * (mixed harnesses legal, nothing dispatches), prints the per-harness
  * next steps, and emits the run's single `PASS` verdict.
  */