@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -10,6 +10,7 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { elapsedSince } from '../utils/elapsed.js';
 import { toError } from '../utils/errors.js';
 import { cancel, info, intro, isCancel, outro, spinner, success, warn, } from '../utils/logger.js';
+import { ADJACENT_MEANS, buildAdjacentUnmanagedContext, reportAdjacentCarveOutUsage, } from './re-export-adjacent.js';
 import { loadScanFilesAssignments, withDryRunPurityGuard, withDryRunReExportLock, } from './re-export-bulk-scan.js';
 import { warnUnseenExpectedDrift } from './re-export-drift.js';
 import { reExportFilesInPlace } from './re-export-files.js';
@@ -17,7 +18,9 @@ import { buildReExportLintContext, finishReExportLint } from './re-export-lint.j
 import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations, } from './re-export-options.js';
 import { validateExpectedRemovals } from './re-export-removed.js';
 import { normalizeEngineRelativeInput, normalizeScanFiles } from './re-export-scan.js';
-import { reExportSinglePatchWithIndexLockRetry } from './re-export-single.js';
+import { assignScanFileOwners, scanOptionsForPatch } from './re-export-scan-owner.js';
+import { reExportSinglePatchWithIndexLockRetry, } from './re-export-single.js';
+import { formatReExportRunSummary } from './re-export-summary.js';
 async function resolveSelectedPatches(patches, options, manifest) {
     if (options.all) {
         return [...manifest.patches];
@@ -56,6 +59,27 @@ async function resolveSelectedPatches(patches, options, manifest) {
     const selectedFilenames = selected;
     return manifest.patches.filter((p) => selectedFilenames.includes(p.filename));
 }
+/** Refreshes each selected patch in turn, collecting which wrote and which failed. */
+async function reExportEach(args) {
+    const { selectedPatches, options, scanAssignments, progress, startedAt, shared } = args;
+    const written = [];
+    const failed = [];
+    for (const [index, patch] of selectedPatches.entries()) {
+        const patchOptions = scanOptionsForPatch(options, patch.filename, scanAssignments);
+        progress.message(`Re-exporting ${index + 1}/${selectedPatches.length}: ${patch.filename} (${patch.filesAffected.length} file(s), ${elapsedSince(startedAt)} elapsed)...`);
+        try {
+            if (await reExportSinglePatchWithIndexLockRetry({ ...shared, patch, options: patchOptions })) {
+                written.push(patch.filename);
+            }
+        }
+        catch (error) {
+            failed.push(patch.filename);
+            warn(`Failed to re-export ${patch.filename}`);
+            warn(toError(error).message);
+        }
+    }
+    return { written, failed };
+}
 /**
  * Runs the re-export command to regenerate existing patches from current engine state.
  * @param projectRoot - Root directory of the project
@@ -73,7 +97,9 @@ export async function reExportCommand(projectRoot, patches, options) {
         options = cleanedOptions;
     }
     const isDryRun = options.dryRun === true;
-    intro(isDryRun ? 'FireForge Re-export (dry run)' : 'FireForge Re-export');
+    // The banner says which mode is in force: a path flag that swallowed
+    // `--dry-run` as its value once turned a preview into a write unnoticed.
+    intro(isDryRun ? 'FireForge Re-export (DRY RUN)' : 'FireForge Re-export (WRITING)');
     // Accept export-style space-separated paths after --files by folding
     // path-shaped extra positionals into the file list.
     ({ patches, options } = applyReExportFilesPositionalFolding(patches, options));
@@ -94,12 +120,13 @@ export async function reExportCommand(projectRoot, patches, options) {
         : await resolveSelectedPatches(patches, options, manifest);
     if (!selectedPatches)
         return;
+    const scanAssignments = scanFilesByPatch ?? assignScanFileOwners(options.scanFiles, selectedPatches, manifest);
     if (selectedPatches.length === 0) {
         warn('No patches selected');
         outro('Nothing to re-export');
         return;
     }
-    const expectedRemovals = await validateExpectedRemovals(paths, selectedPatches, options);
+    const expectedRemovals = await validateExpectedRemovals(paths, selectedPatches, options, manifest.patches);
     if (expectedRemovals.length > 0)
         options = { ...options, expectRemoved: expectedRemovals };
     if (scanFilesByPatch !== undefined) {
@@ -119,20 +146,13 @@ export async function reExportCommand(projectRoot, patches, options) {
     // we write anything.
     if (options.files !== undefined) {
         const filesConfig = await loadConfig(projectRoot);
-        await withDryRunReExportLock(paths.fireforgeDir, isDryRun, () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, () => reExportFilesInPlace(paths, selectedPatches, options, filesConfig)));
+        await withDryRunReExportLock(paths.fireforgeDir, isDryRun, () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, () => reExportFilesInPlace(paths, selectedPatches, options, filesConfig), { patches: selectedPatches }));
         return;
     }
     const config = await loadConfig(projectRoot);
     // Classification inputs for the scan-less adjacency advisory, computed
     // once for the whole run.
-    const adjacentCtx = {
-        binaryName: config.binaryName,
-        furnacePrefixes: await collectFurnaceManagedPrefixes(paths.root),
-        refuseAdjacentUnmanaged: options.refuseAdjacentUnmanaged === true,
-        approvedUnmanaged: new Set((options.expectUnmanaged ?? []).map((file) => normalizeEngineRelativeInput(file, '--expect-unmanaged'))),
-        approvedSeen: new Set(),
-        refusals: [],
-    };
+    const adjacentCtx = buildAdjacentUnmanagedContext(options, config.binaryName, await collectFurnaceManagedPrefixes(paths.root));
     const driftCtx = buildForeignDriftContext(options);
     // Hoisted lint context, one per run: queue context + checkJs
     // program + per-patch result cache, shared across every loop iteration.
@@ -140,42 +160,31 @@ export async function reExportCommand(projectRoot, patches, options) {
     // reports includes it.
     const startedAt = Date.now();
     const lintCtx = await buildReExportLintContext(projectRoot, paths, config, options.noCache === true, new Set(selectedPatches.map((patch) => patch.filename)));
-    let reExported = 0;
-    const reExportedFilenames = [];
-    const failedFilenames = [];
     const progress = spinner('Preparing re-export...');
-    await withDryRunReExportLock(paths.fireforgeDir, isDryRun, async () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, async () => {
-        for (const [index, patch] of selectedPatches.entries()) {
-            const assignedScanFiles = scanFilesByPatch?.get(patch.filename);
-            const patchOptions = assignedScanFiles !== undefined ? { ...options, scanFiles: assignedScanFiles } : options;
-            progress.message(`Re-exporting ${index + 1}/${selectedPatches.length}: ${patch.filename} (${patch.filesAffected.length} file(s), ${elapsedSince(startedAt)} elapsed)...`);
-            try {
-                const exported = await reExportSinglePatchWithIndexLockRetry({
-                    patch,
-                    paths,
-                    manifest,
-                    options: patchOptions,
-                    isDryRun,
-                    config,
-                    adjacentCtx,
-                    driftCtx,
-                    lintCtx,
-                });
-                if (exported) {
-                    reExported++;
-                    reExportedFilenames.push(patch.filename);
-                }
-            }
-            catch (error) {
-                failedFilenames.push(patch.filename);
-                warn(`Failed to re-export ${patch.filename}`);
-                warn(toError(error).message);
-            }
-        }
-    }));
+    const outcome = await withDryRunReExportLock(paths.fireforgeDir, isDryRun, () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, () => reExportEach({
+        selectedPatches,
+        options,
+        scanAssignments,
+        progress,
+        startedAt,
+        shared: { paths, manifest, isDryRun, config, adjacentCtx, driftCtx, lintCtx },
+    }), { patches: selectedPatches }));
+    const reExportedFilenames = outcome.written;
+    const failedFilenames = outcome.failed;
+    const reExported = reExportedFilenames.length;
     await finishReExportLint(lintCtx);
     warnUnseenExpectedDrift(driftCtx);
     warnUnseenApprovedUnmanaged(adjacentCtx);
+    const summary = formatReExportRunSummary({
+        selected: selectedPatches.map((patch) => patch.filename),
+        written: reExportedFilenames,
+        failed: failedFilenames,
+        refusedAdjacent: adjacentCtx.refusals.map((r) => r.patchFilename),
+        refusedDrift: driftCtx.refusals.map((r) => r.patchFilename),
+        isDryRun,
+    });
+    if (summary !== undefined)
+        info(summary);
     throwRunLevelRefusals(adjacentCtx, driftCtx, progress);
     if (reExported === 0 && selectedPatches.length > 0) {
         progress.error('Re-export failed');
@@ -198,6 +207,7 @@ export async function reExportCommand(projectRoot, patches, options) {
         selectedCount: selectedPatches.length,
         reExportedFilenames,
         failedFilenames,
+        selectedFilenames: selectedPatches.map((patch) => patch.filename),
         shouldStamp,
         stampRequested: options.stamp === true,
         config,
@@ -224,9 +234,11 @@ function buildForeignDriftContext(options) {
  * admit, and reads as an approval that is in force when it is not.
  * A warning rather than a refusal: an approved path legitimately goes unmet
  * when the reviewed file has since been adopted into a patch, which is the
- * outcome the carve-out exists to be retired by.
+ * outcome the carve-out exists to be retired by. The `--expect-new` and
+ * `--adjacent-ignore` accounting is reported first, alongside.
  */
 function warnUnseenApprovedUnmanaged(adjacentCtx) {
+    reportAdjacentCarveOutUsage(adjacentCtx);
     const unseen = [...adjacentCtx.approvedUnmanaged].filter((file) => !adjacentCtx.approvedSeen.has(file));
     if (unseen.length === 0)
         return;
@@ -244,17 +256,18 @@ function warnUnseenApprovedUnmanaged(adjacentCtx) {
 function throwRunLevelRefusals(adjacentCtx, driftCtx, progress) {
     if (adjacentCtx.refusals.length > 0) {
         progress.error('Re-export refused');
-        // Each offender is named with the owned directory that made it
-        // adjacent: an unattended run reads only this line, and without the
-        // anchor it cannot tell which of a multi-directory patch's locations
-        // the file sits beside.
+        // Each offender is named with the owned directory (or registering
+        // carrier) that made it adjacent: an unattended run reads only this
+        // line, and without the anchor it cannot tell which of a
+        // multi-directory patch's locations the file belongs to.
         const offenders = adjacentCtx.refusals
             .map((r) => `${r.patchFilename} (${r.anchored.join(', ')})`)
             .join('; ');
         throw new GeneralError(`Refused ${adjacentCtx.refusals.length} patch(es) with adjacent unmanaged files ` +
-            `(--refuse-adjacent-unmanaged): ${offenders}. Adjacent means the file sits in a ` +
-            `directory the patch already owns a file in. Adopt reviewed files with ` +
-            `--scan --scan-file, or export them as a new patch.`);
+            `(--refuse-adjacent-unmanaged): ${offenders}. ${ADJACENT_MEANS} ` +
+            `Adopt reviewed files with --scan --scan-file, or export them as a new patch ` +
+            `(name a file your next export adopts with --expect-new, and a reviewed, deliberately ` +
+            `unmanaged file with --expect-unmanaged or --adjacent-ignore).`);
     }
     if (driftCtx.refusals.length > 0) {
         progress.error('Re-export refused');
@@ -263,11 +276,11 @@ function throwRunLevelRefusals(adjacentCtx, driftCtx, progress) {
         const unreadablePart = unreadable.length > 0
             ? ` ${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 ${driftCtx.refusals.length} patch(es) whose refreshed body would absorb ` +
-            `engine edits not present in the old patch body (--refuse-foreign-drift): ${names}.${unreadablePart}\n\n` +
+        throw new GeneralError(`Refused ${driftCtx.refusals.length} patch(es) whose refreshed body would add or drop ` +
+            `lines relative to 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 ' +
+            '  - Lines you changed 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 " +
@@ -305,9 +318,10 @@ function reportReExportOutcome(args) {
         outro('Re-export complete');
     }
     if (reExported < selectedCount) {
-        const skippedCount = selectedCount - reExported - args.failedFilenames.length;
         const failedPart = args.failedFilenames.length > 0 ? ` Failed: ${args.failedFilenames.join(', ')}.` : '';
-        const skippedPart = skippedCount > 0 ? ` Skipped: ${skippedCount} patch(es) (see warnings above).` : '';
+        const accounted = new Set([...args.reExportedFilenames, ...args.failedFilenames]);
+        const skipped = args.selectedFilenames.filter((name) => !accounted.has(name));
+        const skippedPart = skipped.length > 0 ? ` Skipped: ${skipped.join(', ')} (see warnings above).` : '';
         throw new GeneralError(`${isDryRun ? '[dry-run] Would re-export' : 'Re-exported'} only ${reExported} of ` +
             `${selectedCount} selected patch(es).${failedPart}${skippedPart} ` +
             'Partial re-export exits non-zero so it cannot pass as success in scripts; ' +

package/dist/src/commands/rebase/index.js

@@ -19,12 +19,13 @@ import { discoverPatches } from '../../core/patch-files.js';
 import { loadPatchesManifest } from '../../core/patch-manifest.js';
 import { getPatchSourceVersion } from '../../core/patch-source-metadata.js';
 import { replayQueueIndexOnly } from '../../core/rebase-dry-run.js';
+import { formatPatchStampSpread, readCommittedFirefoxPin, resolveRebaseFromVersion, tallyPatchStamps, } from '../../core/rebase-from-version.js';
 import { getRebaseSessionPath, readRebaseSession, saveRebaseSession, } from '../../core/rebase-session.js';
 import { GeneralError } from '../../errors/base.js';
 import { CorruptRebaseSessionError, RebaseDryRunRejectError, RebaseSessionExistsError, } from '../../errors/rebase.js';
 import { info, intro, outro, spinner, warn } from '../../utils/logger.js';
 import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../../utils/options.js';
-import { compareFirefoxVersions, parsePositiveIntegerFlag } from '../../utils/validation.js';
+import { parsePositiveIntegerFlag } from '../../utils/validation.js';
 import { handleAbort } from './abort.js';
 import { confirmDirtyEngineReset } from './confirm.js';
 import { handleContinue } from './continue.js';
@@ -58,27 +59,26 @@ async function handleFreshStart(projectRoot, options) {
     if (!manifest || manifest.patches.length === 0) {
         throw new GeneralError('No patches found in manifest. Nothing to rebase.');
     }
-    // Determine the "from" version from the patch stamps. A queue can carry
-    // several: patches re-exported since the last hop are stamped newer than
-    // untouched ones. The oldest stamp is "from", compared semantically (a
-    // lexical sort put 153.10.0esr before 153.2.0esr).
-    const versionCounts = new Map();
-    for (const patch of manifest.patches) {
-        const version = getPatchSourceVersion(patch);
-        versionCounts.set(version, (versionCounts.get(version) ?? 0) + 1);
-    }
-    const sortedVersions = [...versionCounts.keys()].sort(compareFirefoxVersions);
-    const fromVersion = sortedVersions[0] ?? currentVersion;
-    const fromProduct = manifest.patches.find((p) => getPatchSourceVersion(p) === fromVersion)?.sourceProduct ??
-        config.firefox.product;
-    if (versionCounts.size === 1 && fromVersion === currentVersion) {
+    // The queue can carry several stamps: patches re-exported since the last
+    // hop are stamped newer than untouched ones. "Nothing to rebase" is a fact
+    // about the stamps; the "from" label is the previous pin (the committed
+    // `firefox.version`), with the oldest stamp only as the fallback.
+    const spread = tallyPatchStamps(manifest.patches.map((p) => getPatchSourceVersion(p)));
+    const oldestStamp = spread.versions[0] ?? currentVersion;
+    const from = resolveRebaseFromVersion(currentVersion, await readCommittedFirefoxPin(projectRoot), spread, manifest.patches.find((p) => getPatchSourceVersion(p) === oldestStamp)?.sourceProduct);
+    const fromVersion = from.version;
+    const fromProduct = from.product ?? config.firefox.product;
+    if (spread.versions.length === 1 && oldestStamp === currentVersion) {
         info('All patches already match the current Firefox version. Nothing to rebase.');
         outro('Rebase not needed');
         return;
     }
     info(`Rebasing patches: ${fromVersion} → ${currentVersion}`);
-    if (versionCounts.size > 1) {
-        info(`Patch stamps: ${sortedVersions.map((v) => `${versionCounts.get(v)} at ${v}`).join(', ')}`);
+    if (from.origin === 'patch-stamps') {
+        info('From-version is the oldest patch stamp: no committed fireforge.json pin precedes the target.');
+    }
+    if (from.origin === 'committed-pin' || spread.versions.length > 1) {
+        info(`Patch stamps: ${formatPatchStampSpread(spread)}`);
     }
     // The rebase replays onto whatever engine/ holds. The pin is the target,
     // so an engine still on another version means the download step has not

package/dist/src/commands/run.js

@@ -9,7 +9,7 @@ import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { hasBuildArtifacts, hasRunnableBundle, run, runMachSmoke } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { resolveRunProfile, sweepAbandonedRunProfiles, } from '../core/run-profile.js';
-import { compileAllowlistFromFile, compileAllowlistFromStrings, findOverCapAllowlistEntries, matchAllowlist, matchesSmokeError, } from '../core/smoke-patterns.js';
+import { compileAllowlistFromFile, compileAllowlistFromStrings, findOverCapAllowlistEntries, isBrowserConsoleLine, matchAllowlist, matchesSmokeError, } from '../core/smoke-patterns.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { ExitCode } from '../errors/codes.js';
@@ -105,6 +105,7 @@ export async function runCommand(projectRoot, options = {}) {
     const profile = await resolveRunProfile({
         profile: options.profile,
         tempProfile: options.tempProfile,
+        purgeCaches: options.purgeCaches,
         smoke: options.smokeExit !== undefined,
     });
     try {
@@ -188,6 +189,7 @@ async function runSmokeExit(engineDir, options, profile) {
         warn(`--capture-console stream error: ${err.message}`);
     });
     const findings = [];
+    let browserConsoleLines = 0;
     let allowlistedErrorHits = 0;
     let allowlistedTotalHits = 0;
     const allowlistHits = new Array(allowlist.length).fill(0);
@@ -197,6 +199,8 @@ async function runSmokeExit(engineDir, options, profile) {
         // mirror preserves stdout/stderr separation for downstream piping.
         const sink = stream === 'stdout' ? process.stdout : process.stderr;
         sink.write(`${line}\n`);
+        if (isBrowserConsoleLine(line))
+            browserConsoleLines += 1;
         // Count allowlist hits up-front, regardless of error-pattern match.
         // Incrementing only when the line also matches an error pattern makes an
         // allowlist regex that visibly matches `console.warn: RSLoader:` report 0
@@ -269,6 +273,15 @@ async function runSmokeExit(engineDir, options, profile) {
         return;
     }
     if (result.exitCode === 0 || result.exitCode === 130 || result.exitCode === 143) {
+        // A clean status before the window with no browser output at all is a
+        // launch that never reached a window (a profile lock, a startup-crash
+        // streak's silent exit, a self-restart), not a clean run.
+        if (browserConsoleLines === 0) {
+            throw new SmokeRunError(`Browser exited with code ${result.exitCode} after ${(elapsedMs / 1000).toFixed(1)}s, ` +
+                'before the smoke-exit window elapsed, without any console output. A silent early ' +
+                'exit means the launch never reached a window: check the profile for a stale ' +
+                '.parentlock or a startup-crash streak (toolkit.startup.recent_crashes).', ExitCode.SMOKE_LAUNCH_FAILURE);
+        }
         return;
     }
     throw new SmokeRunError(`Browser exited with code ${result.exitCode} before smoke-exit window elapsed.`, ExitCode.SMOKE_LAUNCH_FAILURE);
@@ -392,7 +405,8 @@ export function registerRun(program, { getProjectRoot, withErrorHandling }) {
         .option('--console-allow-file <path>', 'Newline-delimited allowlist regex file. Blank lines and # comments are ignored. A "# max-hits: N" comment directly above an entry caps how many lines it may match in one run; more than that fails the run with exit 12.')
         .option('--capture-console <file>', 'Mirror captured console output to <file> for post-exit inspection.')
         .option('--headless', 'Launch the browser with --headless. Recommended for --smoke-exit on a shared desktop: input into a headed smoke window contaminates the console capture.')
-        .option('--profile <path>', 'Launch with this profile directory (passed to Firefox as -profile). Left in place after the run. With --smoke-exit it replaces the default fresh profile.')
+        .option('--profile <path>', 'Launch with this profile directory (passed to Firefox as -profile). Left in place after the run. With --smoke-exit it replaces the default fresh profile. Firefox gets -purgecaches too, so the profile does not run chrome scripts an earlier build cached.')
+        .option('--no-purge-caches', 'With --profile, keep the profile startup cache (do not pass -purgecaches).')
         .option('--temp-profile', 'Launch with a fresh temporary profile that is removed when the run ends. The default for --smoke-exit.')
         .action(withErrorHandling(
     // `args` is the variadic positional, not a Commander flag, so it

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

@@ -3,46 +3,85 @@
  * 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.
+ * `--allow <class,...>` names classes that never fail, and
+ * `--fail-on-unknown` fails every present class that neither list names,
+ * so a gate keeps failing closed when FireForge adds a classification.
+ * `ownership-conflict` is a check class beside the file classifications:
+ * a path claimed by more than one patch, judged from the same rows as
+ * `--include-ownership`.
  *
  * Helper module consumed by status.ts, which sits at the max-lines budget.
  * No top-level registrar is exported and none is wanted.
  */
 import type { ClassifiedFile, FileClassification } from '../core/status-classify.js';
+/**
+ * A class `--fail-on`/`--allow` can name: every file classification, plus
+ * `ownership-conflict`, which is judged from the ownership rows rather
+ * than from a file's classification.
+ */
+export type StatusCheckClass = FileClassification | 'ownership-conflict';
 /** Resolved `--check`/`--fail-on` policy for one status invocation. */
 export interface StatusCheckPolicy {
     checkEnabled: boolean;
-    failOn: readonly FileClassification[];
+    /** Classes that fail: `--fail-on` (or the default set) minus `--allow`. */
+    failOn: readonly StatusCheckClass[];
+    /** `--allow`: classes that never fail. Set only when the flag was given. */
+    allow?: readonly StatusCheckClass[];
+    /** `--fail-on-unknown`: a present class named by neither list fails. */
+    failOnUnknown?: boolean;
 }
 /**
- * Resolves the enforcement policy from the raw flags: `--fail-on` implies
- * `--check` and replaces the default set. Both are refused alongside the
- * modes that skip (or elide) classification.
+ * Resolves the enforcement policy from the raw flags. `--fail-on`,
+ * `--allow` and `--fail-on-unknown` each imply `--check`. `--fail-on`
+ * replaces the default set and `--allow` subtracts from it (naming one
+ * class in both is refused). `--fail-on-unknown` needs `--allow`: without
+ * an allow list every class the caller did not name, `patch-backed`
+ * included, would fail. All of them are refused alongside the modes that
+ * skip (or elide) classification.
  */
 export declare function resolveStatusCheckPolicy(options: {
     check?: boolean;
     failOn?: string;
+    allow?: string;
+    failOnUnknown?: boolean;
     raw?: boolean;
     unmanaged?: boolean;
     ownership?: boolean;
     testCoverage?: boolean;
 }): StatusCheckPolicy;
-/** One fail-set classification with a non-empty file list. */
+/**
+ * True when the policy can fail on `ownership-conflict`, so the caller has
+ * to build the ownership rows even without `--include-ownership`.
+ */
+export declare function policyNeedsOwnership(policy: StatusCheckPolicy): boolean;
+/** One failing class with a non-empty file list. */
 export interface StatusCheckOffender {
-    classification: FileClassification;
+    classification: StatusCheckClass;
     count: number;
     files: string[];
+    /**
+     * Set when the class failed only through `--fail-on-unknown`: neither
+     * `--fail-on` nor `--allow` named it.
+     */
+    unnamed?: true;
 }
 /**
- * Collects the fail-set classifications that have offending files, in
- * policy order with full file lists. Shared by the human `--check`
- * verdict and the `--json --summary` payload so the two views can never
- * disagree about what failed.
+ * Collects the failing classes that have offending files, with full file
+ * lists: the fail set in policy order, then (under `--fail-on-unknown`)
+ * every other present class neither list names, in first-seen order.
+ * Shared by the human `--check` verdict and the JSON `check` block so the
+ * two views can never disagree about what failed.
+ *
+ * @param classified - Classified worktree entries
+ * @param policy - Resolved policy
+ * @param ownershipConflicts - Paths claimed by more than one patch. Only
+ *   read for the `ownership-conflict` class
  */
-export declare function collectStatusCheckOffenders(classified: readonly ClassifiedFile[], policy: StatusCheckPolicy): StatusCheckOffender[];
+export declare function collectStatusCheckOffenders(classified: readonly ClassifiedFile[], policy: StatusCheckPolicy, ownershipConflicts?: readonly string[]): StatusCheckOffender[];
 /**
- * Throws a GeneralError (exit 1) when the policy is enabled and any of
- * its classifications is non-empty, naming each offending classification
- * with its first few files. A disabled policy or a fully tool-covered
- * tree passes silently.
+ * Throws a GeneralError (exit 1) when the policy is enabled and any
+ * failing class is non-empty, naming each offending class with its first
+ * few files. A disabled policy or a fully tool-covered tree passes
+ * silently.
  */
-export declare function runStatusCheck(classified: readonly ClassifiedFile[], policy: StatusCheckPolicy): void;
+export declare function runStatusCheck(classified: readonly ClassifiedFile[], policy: StatusCheckPolicy, ownershipConflicts?: readonly string[]): void;