rea-agents 6.4.0 → 6.7.0

package/dist/firmware/FirmwareProvider.js

@@ -1,10 +1,9 @@
 import { join, isAbsolute } from "node:path";
-import { z } from "zod";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { firmwareResultSchemas, } from "../domain/firmware/firmwareAnalysis.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
-import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
@@ -14,23 +13,33 @@ import { publishFirmwareExtraction } from "./FirmwarePublication.js";
 import { FIRMWARE_LIMITS, BINWALK_PROVIDER_IDENTITY, UNBLOB_PROVIDER_IDENTITY, } from "./FirmwareRelease.js";
 import { admitFirmwareVersion } from "./FirmwareVersion.js";
 import { firmwareToolUnavailable, resolveFirmwareCommand, runFirmwareCommand, readFirmwareCommandReport, } from "./FirmwareCommand.js";
-import { inventoryFirmwareOutput, snapshotFirmware } from "./FirmwareFiles.js";
+import { inventoryFirmwareOutput, FirmwareFileAccess, } from "./FirmwareFiles.js";
 import { normalizeBinwalkReport, normalizeUnblobReport, } from "./FirmwareReports.js";
+import { firmwareFailure, firmwareCancellation } from "./FirmwareFailures.js";
+import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
+const bindWorkspaceFailure = (pending, failure) => {
+    pending.rootLease.bindCleanupError(failure);
+    return failure;
+};
 const combineCleanupFailures = (failures) => {
     if (failures.length < 2)
         return failures[0];
     return new ProviderCleanupError("firmware", failures.flatMap((failure) => [...failure.cleanupResources]), {
         reason: "Multiple owned firmware resources could not be cleaned",
         failures: failures.map((failure) => ({
-            engine: failure.providerId,
-            operation: failure.operation,
+            engine: failure instanceof ProviderAdapterError
+                ? failure.providerId
+                : "firmware",
+            operation: failure instanceof ProviderAdapterError
+                ? failure.operation
+                : "close_firmware",
             resources: [...failure.cleanupResources],
             reason: failure.diagnostics?.reason ?? failure.message,
         })),
-    }, { operation: "close_firmware", cause: new AggregateError(failures) });
+    }, { operation: "close_firmware", cause: new AggregateError(failures) }).bindCleanupDependencies(failures);
 };
 const waitForPredecessor = (predecessor, operation, signal) => new Promise((resolve, reject) => {
-    const abort = () => reject(new AnalysisCancelledError(operation));
+    const abort = () => reject(new AnalysisCancelledError(operation, { cause: signal?.reason }));
     signal?.addEventListener("abort", abort, { once: true });
     if (signal?.aborted === true)
         abort();
@@ -43,6 +52,7 @@ const limitations = [
     "Signature matches and reported sizes do not establish partition validity, encryption or runtime mappings. Binwalk may infer unknown lengths before emitting its report.",
     "Only Linux is supported by this integration. One worker, inherited per-process address-space/file-size/CPU limits and a deadline constrain execution; staging byte and entry budgets are polled and may transiently overshoot. Limits are not aggregate process-memory or filesystem quotas.",
     "Unblob's default sandbox and skip rules remain enabled. Missing external extractors, unknown chunks, encrypted chunks and depth limits yield partial coverage. Extracted code is never executed; only regular files are published, without executable permission bits.",
+    "extraction_gaps lists regions that were carved or left unextracted and names extractor dependencies the producer reported as missing. A listed gap does not mean the target is corrupt or that a retained region is empty.",
     "The actual launcher executable is hashed. Interpreter, shared libraries and installed Python package dependencies are not independently attested; source revision remains unknown for caller-supplied builds.",
 ];
 /** Queued bring-your-own firmware adapters with private snapshots and owned cleanup. */
@@ -51,6 +61,8 @@ export class FirmwareProvider {
     launcher;
     #tail = Promise.resolve();
     #closed = false;
+    #closing;
+    #files = new FirmwareFileAccess();
     #pendingCleanup = new Map();
     constructor(environment = process.env, launcher) {
         this.environment = environment;
@@ -79,7 +91,7 @@ export class FirmwareProvider {
             if (this.#closed)
                 return err(new AnalysisCancelledError(request.operation));
             const cleanup = await this.#retryCleanup();
-            if (cleanup.processUnverified && cleanup.failure !== undefined)
+            if (cleanup.executionBlocked && cleanup.failure !== undefined)
                 return err(cleanup.failure);
             return await this.#execute(request, options);
         }
@@ -88,55 +100,95 @@ export class FirmwareProvider {
         }
     }
     /** Retry every retained owner, reporting failures without discarding other roots. */
-    async close() {
+    close() {
         this.#closed = true;
+        return (this.#closing ??= this.#close().finally(() => {
+            this.#closing = undefined;
+        }));
+    }
+    async #close() {
         await this.#tail;
-        const cleanup = await this.#retryCleanup();
-        if (cleanup.failure !== undefined)
-            throw cleanup.failure;
+        const failures = [];
+        try {
+            await this.#files.close();
+        }
+        catch (cause) {
+            failures.push(firmwareFailure(cause, "firmware", "close_firmware"));
+        }
+        const workspace = await this.#retryWorkspaceCleanup();
+        if (workspace.failure !== undefined)
+            failures.push(workspace.failure);
+        const failure = combineCleanupFailures(failures);
+        if (failure !== undefined)
+            throw failure;
     }
     async #retryCleanup() {
+        let fileFailure;
+        try {
+            await this.#files.retryCleanup();
+        }
+        catch (cause) {
+            fileFailure = firmwareFailure(cause, "firmware", "close_firmware");
+        }
+        const workspace = await this.#retryWorkspaceCleanup();
+        return {
+            failure: combineCleanupFailures([
+                ...(fileFailure === undefined ? [] : [fileFailure]),
+                ...(workspace.failure === undefined ? [] : [workspace.failure]),
+            ]),
+            executionBlocked: fileFailure !== undefined || workspace.executionBlocked,
+        };
+    }
+    async #retryWorkspaceCleanup() {
         const failures = [];
-        let processUnverified = false;
+        let executionBlocked = false;
         for (const [path, pending] of this.#pendingCleanup) {
             try {
                 const stopped = await pending.supervisor?.stop();
                 if (stopped?.status === "incomplete") {
-                    processUnverified = true;
-                    failures.push(new ProviderCleanupError(pending.engine, [path], { reason: stopped.reason }, { operation: pending.operation }));
+                    executionBlocked = true;
+                    failures.push(bindWorkspaceFailure(pending, new ProviderCleanupError(pending.engine, [path], { reason: stopped.reason }, { operation: pending.operation })));
                     continue;
                 }
                 delete pending.supervisor;
             }
             catch (cause) {
-                processUnverified = true;
-                failures.push(new ProviderCleanupError(pending.engine, [path], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation: pending.operation, cause }));
+                executionBlocked = true;
+                failures.push(bindWorkspaceFailure(pending, new ProviderCleanupError(pending.engine, [path], {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                }, { operation: pending.operation, cause })));
                 continue;
             }
             try {
                 if (pending.tree !== undefined) {
-                    await pending.tree.rollback();
+                    await pending.tree.lease.release();
                     delete pending.tree;
                 }
             }
             catch (cause) {
-                failures.push(new ProviderCleanupError(pending.engine, [path, pending.tree?.outputRoot ?? path], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation: pending.operation, cause }));
+                failures.push(bindWorkspaceFailure(pending, new ProviderCleanupError(pending.engine, [path, pending.tree?.tree.outputRoot ?? path], {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                }, { operation: pending.operation, cause })));
             }
+            if (pending.tree !== undefined)
+                continue;
             try {
-                await pending.root.close();
-                if (pending.tree === undefined)
-                    this.#pendingCleanup.delete(path);
+                await pending.rootLease.release();
+                this.#pendingCleanup.delete(path);
             }
             catch (cause) {
                 // A verified stopped process cannot use this root. Keep ownership for
                 // later removal without blocking a new operation's disjoint workspace.
-                failures.push(new ProviderCleanupError(pending.engine, [path], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation: pending.operation, cause }));
+                failures.push(bindWorkspaceFailure(pending, new ProviderCleanupError(pending.engine, [path], {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                }, { operation: pending.operation, cause })));
             }
         }
-        return { failure: combineCleanupFailures(failures), processUnverified };
+        return { failure: combineCleanupFailures(failures), executionBlocked };
     }
     async #execute(request, options) {
         let root;
+        let rootLease;
         const engineName = request.operation === "inspect_firmware_regions" ? "binwalk" : "unblob";
         const deadline = AbortSignal.timeout(FIRMWARE_LIMITS.timeoutMs);
         const signal = options?.signal === undefined
@@ -145,11 +197,15 @@ export class FirmwareProvider {
         let outcome;
         try {
             if (signal.aborted)
-                throw new AnalysisCancelledError(request.operation);
-            const command = await resolveFirmwareCommand(this.environment, engineName, request.operation);
+                throw new AnalysisCancelledError(request.operation, {
+                    cause: signal.reason,
+                });
+            const command = await resolveFirmwareCommand(this.environment, engineName, request.operation, this.#files, signal);
             root = await PrivateRuntimeRoot.create({ prefix: "rea-firmware-" });
             const ownedRoot = root;
-            const target = await snapshotFirmware(request, root.path, signal);
+            const ownedRootLease = new AnalysisCleanupLease(() => ownedRoot.close());
+            rootLease = ownedRootLease;
+            const target = await this.#files.snapshot(request, root.path, signal);
             const run = (args, outputBudget) => runFirmwareCommand({
                 engine: engineName,
                 operation: request.operation,
@@ -162,6 +218,7 @@ export class FirmwareProvider {
                     this.#pendingCleanup.set(ownedRoot.path, {
                         supervisor,
                         root: ownedRoot,
+                        rootLease: ownedRootLease,
                         engine: engineName,
                         operation: request.operation,
                     });
@@ -204,6 +261,8 @@ export class FirmwareProvider {
                     engine: engineName,
                     operation: request.operation,
                     execution: processRun,
+                    files: this.#files,
+                    signal,
                 });
                 result = firmwareResultSchemas.inspect_firmware_regions.parse({
                     engine,
@@ -247,6 +306,8 @@ export class FirmwareProvider {
                     engine: engineName,
                     operation: request.operation,
                     execution: processRun,
+                    files: this.#files,
+                    signal,
                 });
                 const normalized = normalizeUnblobReport(report, {
                     inputPath: target.inputPath,
@@ -258,19 +319,25 @@ export class FirmwareProvider {
                     throw new AnalysisOutputError(request.operation, "Unblob failed without a reported extraction diagnostic");
                 const entries = await inventoryFirmwareOutput(outputRoot, request.input.max_output_bytes, request.input.max_output_files, request.operation, signal);
                 result = await publishFirmwareExtraction({
+                    files: this.#files,
+                    workspacePath: root.path,
+                    deadline,
                     outputDirectory: request.input.output_directory,
                     entries,
                     normalized,
                     selection: target.selection,
+                    maxDepth: request.input.max_depth,
                     engine,
                     signal,
-                    retainCleanup: (tree) => {
+                    retainCleanup: (tree, lease, failure) => {
+                        ownedRootLease.bindCleanupError(failure);
                         const pending = this.#pendingCleanup.get(ownedRoot.path) ?? {
                             root: ownedRoot,
+                            rootLease: ownedRootLease,
                             engine: engineName,
                             operation: request.operation,
                         };
-                        pending.tree = tree;
+                        pending.tree = { tree, lease };
                         this.#pendingCleanup.set(ownedRoot.path, pending);
                     },
                 });
@@ -298,56 +365,40 @@ export class FirmwareProvider {
             }));
         }
         catch (cause) {
-            outcome = err(cause instanceof ProviderCleanupError
-                ? cause
-                : options?.signal?.aborted === true
-                    ? new AnalysisCancelledError(request.operation)
-                    : deadline.aborted
-                        ? new AnalysisTimeoutError(request.operation, FIRMWARE_LIMITS.timeoutMs)
-                        : cause instanceof AnalysisError
-                            ? cause
-                            : cause instanceof z.ZodError
-                                ? new AnalysisOutputError(request.operation, "Tool report violated the pinned producer protocol", { cause })
-                                : new ProviderAdapterError(engineName, request.operation, {
-                                    cause,
-                                    diagnostics: {
-                                        reason: cause instanceof Error
-                                            ? cause.message
-                                            : String(cause),
-                                    },
-                                }));
+            const failure = firmwareFailure(cause, engineName, request.operation, deadline);
+            outcome = err(failure);
         }
-        const finished = await finishFirmwareWorkspace(root, outcome, engineName, request);
+        const finished = await finishFirmwareWorkspace(root, outcome, engineName, request, rootLease, signal, deadline);
         if (!finished.ok &&
             finished.error.cleanupIncomplete &&
             root !== undefined &&
+            rootLease !== undefined &&
+            finished.error.cleanupResources.includes(root.path) &&
             !this.#pendingCleanup.has(root.path))
             this.#pendingCleanup.set(root.path, {
                 root,
+                rootLease,
                 engine: engineName,
                 operation: request.operation,
             });
+        if (!finished.ok &&
+            root !== undefined &&
+            rootLease !== undefined &&
+            finished.error.cleanupResources.includes(root.path))
+            rootLease.bindCleanupError(finished.error);
+        if (finished.ok && signal.aborted)
+            return err(firmwareCancellation(request.operation, signal.reason, deadline).retainPartialObservation(completedFirmwareObservation(finished.value)));
         return finished;
     }
 }
 /** Keep a completed extraction beside cleanup failure, or skip removal when ownership is uncertain. */
-export const finishFirmwareWorkspace = async (root, outcome, engineName, request) => {
-    if (!outcome.ok && outcome.error.cleanupIncomplete) {
-        if (root === undefined ||
-            outcome.error.cleanupResources.includes(root.path))
-            return outcome;
-        return err(new ProviderCleanupError(engineName, [...outcome.error.cleanupResources, root.path], outcome.error instanceof ProviderAdapterError
-            ? (outcome.error.diagnostics ?? { reason: outcome.error.message })
-            : { reason: outcome.error.message }, {
-            cause: outcome.error,
-            operation: request.operation,
-            ...(outcome.error.partialObservation === undefined
-                ? {}
-                : { partialObservation: outcome.error.partialObservation }),
-        }));
-    }
+const finishFirmwareWorkspace = async (root, outcome, engineName, request, rootLease, signal, deadline) => {
+    if (!outcome.ok &&
+        outcome.error.cleanupIncomplete &&
+        (root === undefined || outcome.error.cleanupResources.includes(root.path)))
+        return outcome;
     try {
-        await root?.close();
+        await rootLease?.release();
     }
     catch (cause) {
         const cleanup = new ProviderCleanupError(engineName, [
@@ -366,9 +417,15 @@ export const finishFirmwareWorkspace = async (root, outcome, engineName, request
                     ? {}
                     : { partialObservation: outcome.error.partialObservation }),
         });
+        rootLease?.bindCleanupError(cleanup);
+        if (outcome.ok && signal.aborted) {
+            const primary = firmwareCancellation(request.operation, signal.reason, deadline);
+            primary.retainPartialObservation(completedFirmwareObservation(outcome.value));
+            return err(analysisErrorWithCleanupFailure(primary, cleanup, request.operation).bindCleanupDependencies([cleanup]));
+        }
         return err(outcome.ok
             ? cleanup
-            : analysisErrorWithCleanupFailure(outcome.error, cleanup, request.operation));
+            : analysisErrorWithCleanupFailure(outcome.error, cleanup, request.operation).bindCleanupDependencies([outcome.error, cleanup]));
     }
     return outcome;
 };

package/dist/firmware/FirmwarePublication.js

@@ -1,12 +1,57 @@
-import { createReadStream } from "node:fs";
+import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { firmwareFailure } from "./FirmwareFailures.js";
+import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { SafeOutputTree } from "../artifacts/SafeOutputTree.js";
 import { SafeOutputTreeCreationFailure } from "../artifacts/SafeOutputTreeCreationFailure.js";
-import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
+import { AnalysisOutputError, AnalysisCancelledError, } from "../domain/analysisErrorCore.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { firmwareResultSchemas } from "../domain/firmware/firmwareAnalysis.js";
-import { hashFirmwareFile } from "./FirmwareFiles.js";
+/** Static, truthful continuations that use already configured capabilities. */
+const GAP_CONTINUATIONS = {
+    "missing-extractor-dependency": "REA installs nothing. Add the named dependency to your own environment and rerun extract_firmware on the same immutable input with a fresh output_directory to re-evaluate the affected region; otherwise it stays unextracted.",
+    "unknown-chunk-handler": "If Binwalk is configured with REA_BINWALK_COMMAND, run inspect_firmware_regions on the same input for signature hypotheses. Without configured Binwalk that inspection is unavailable. Alternatively, select a materially narrower range with extract_firmware and a fresh output_directory; the region is not decoded content.",
+    "encrypted-chunk": "No static extraction continues past encryption; treat the region as unexamined rather than empty or corrupt.",
+    "extractor-failure": "The producer retained this chunk's extraction problem in diagnostics. Review the reported failure, then rerun extract_firmware on the same immutable input with a fresh output_directory; the region is not decoded content.",
+    "depth-limited": "Rerun extract_firmware with a higher max_depth (up to 10) and a fresh output_directory to descend into this path.",
+    "unpublished-entry": "The entry is retained as metadata; only regular files are published, without executable permission bits.",
+};
+const UNNAMED_DEPENDENCY_CONTINUATION = "The producer reported a missing extractor dependency without naming it; its identity is unavailable in this evidence. No specific installation or rerun can be prescribed from this report. Retain the gap as unextracted unless additional provider evidence establishes the dependency. REA installs nothing.";
+import { FIRMWARE_LIMITS } from "./FirmwareRelease.js";
+/** The depth ceiling cannot be raised past the input schema maximum. */
+const MAX_EXTRACTION_DEPTH = 10;
+const depthContinuation = (maxDepth, publishedChildPaths) => maxDepth < MAX_EXTRACTION_DEPTH
+    ? GAP_CONTINUATIONS["depth-limited"]
+    : publishedChildPaths.length > 0
+        ? `This extraction already ran at the lane's maximum depth. To continue, rerun extract_firmware with path set to any eligible published child below this path and a fresh output directory; each child listed here restarts the depth budget: ${publishedChildPaths.map((path) => JSON.stringify(path)).join(", ")}.`
+        : `This extraction already ran at the lane's maximum depth, and no published child under this path is both nonempty and within the ${FIRMWARE_LIMITS.inputBytes}-byte firmware input limit, so the depth budget cannot be restarted from this output. Treat the region below this path as unexamined.`;
+// Use a different analyzer on the actual published child; repeating the same
+// whole-child extraction with unchanged handlers would reproduce this gap.
+const nestedUnknownContinuation = (publishedFile) => {
+    const base = "This unknown chunk was carved from a nested extraction, so its range is relative to the published child named by this gap's input_path, not to the original input.";
+    return publishedFile !== undefined &&
+        publishedFile.size > 0 &&
+        publishedFile.size <= FIRMWARE_LIMITS.inputBytes
+        ? `${base} Run inspect_firmware_regions with path set to that published child for signature hypotheses only if Binwalk is configured with REA_BINWALK_COMMAND. This inspection step is unavailable without configured Binwalk; retain the region as unexamined. Repeating the same whole-child extraction with unchanged handlers would not advance analysis.`
+        : `${base} That published child is not a nonempty file within the ${FIRMWARE_LIMITS.inputBytes}-byte firmware input limit, so inspect_firmware_regions cannot accept it as a fresh input; treat the region as unexamined.`;
+};
+const emptyGap = {
+    relative_path: null,
+    handler: null,
+    provider_id: null,
+    range: null,
+    root_file_range: null,
+    dependencies: [],
+};
+const gapSortKey = (gap) => [
+    gap.input_path,
+    gap.kind,
+    gap.provider_id ?? "",
+    gap.relative_path ?? "",
+].join("\u0000");
 /** Publish verified regular files, preserving links as metadata and rolling back failed writes. */
 export const publishFirmwareExtraction = async (context) => {
     let tree;
@@ -33,14 +78,14 @@ export const publishFirmwareExtraction = async (context) => {
             }
             const logicalPath = `$output/${entry.relativePath}`;
             const reported = context.normalized.files.get(logicalPath);
-            const sha256 = await hashFirmwareFile(entry.path, context.signal);
+            const sha256 = await context.files.hash(entry.path, context.signal);
             if ((reported?.sha256 !== null &&
                 reported?.sha256 !== undefined &&
                 reported.sha256 !== sha256) ||
                 (context.normalized.sizes.has(logicalPath) &&
                     context.normalized.sizes.get(logicalPath) !== entry.size))
                 throw new AnalysisOutputError("extract_firmware", `Extracted bytes disagree with provider report: ${entry.relativePath}`);
-            await tree.write(entry.relativePath, createReadStream(entry.path), { sha256, bytes: entry.size }, context.signal);
+            await context.files.publish(entry, sha256, tree, context.signal);
             files.push({
                 relative_path: entry.relativePath,
                 path: join(tree.outputRoot, entry.relativePath),
@@ -64,28 +109,37 @@ export const publishFirmwareExtraction = async (context) => {
             derivations: context.normalized.derivations,
             depth_limited_paths: context.normalized.depth_limited_paths,
             diagnostics: context.normalized.diagnostics,
+            ...extractionGaps(unpublished, files, context.normalized, context.maxDepth),
             published_bytes: files.reduce((sum, file) => sum + file.size, 0),
         });
-        context.signal.throwIfAborted();
-        await tree.commit();
+        if (context.signal.aborted)
+            throw new AnalysisCancelledError("extract_firmware", {
+                cause: context.signal.reason,
+            });
+        await tree.commit(context.signal);
         return result;
     }
     catch (cause) {
         if (cause instanceof SafeOutputTreeCreationFailure)
             tree = cause.tree;
+        const ownedTree = tree;
+        const treeLease = ownedTree === undefined
+            ? undefined
+            : new AnalysisCleanupLease(async () => {
+                await ownedTree.rollback();
+            });
+        const primary = firmwareFailure(cause, "unblob", "extract_firmware", context.deadline, treeLease);
         try {
-            await tree?.rollback();
+            await treeLease?.release();
         }
         catch (cleanupCause) {
-            if (tree !== undefined)
-                context.retainCleanup(tree);
             const publishedResult = tree?.published === true && result !== undefined
                 ? {
                     kind: "firmware",
                     result: jsonValueSchema.parse(result),
                 }
                 : undefined;
-            throw new ProviderCleanupError("unblob", [context.outputDirectory], {
+            const cleanup = new ProviderCleanupError("unblob", [context.outputDirectory, context.workspacePath], {
                 reason: cleanupCause instanceof Error
                     ? cleanupCause.message
                     : String(cleanupCause),
@@ -97,9 +151,187 @@ export const publishFirmwareExtraction = async (context) => {
                     ? {}
                     : { partialObservation: publishedResult }),
             });
+            if (tree !== undefined && treeLease !== undefined)
+                context.retainCleanup(tree, treeLease, cleanup);
+            if (publishedResult !== undefined)
+                primary.retainPartialObservation(publishedResult);
+            throw analysisErrorWithCleanupFailure(primary, cleanup, "extract_firmware").bindCleanupDependencies([primary, cleanup]);
         }
         if (tree?.published === true && result !== undefined)
             return result;
-        throw cause;
+        throw primary;
     }
 };
+/** Derive explicit recovery rows from retained report facts; no new claims. */
+/** Gap rows for missing-dependency reports: chunk-nested rows keep their owning chunk. */
+const dependencyExtractionGaps = (normalized, continuation) => {
+    // Chunk-nested dependency reports name the chunk that could not extract;
+    // task-wide reports (standalone or multi-file) attach to the task.
+    // One index over the chunk list keeps dependency-row resolution linear.
+    const chunksByKey = new Map(normalized.chunks.map((chunk) => [
+        JSON.stringify([chunk.input_path, chunk.provider_id]),
+        chunk,
+    ]));
+    return [
+        ...normalized.chunk_missing_dependencies.flatMap(({ input_path, provider_id, dependencies }) => {
+            const affected = chunksByKey.get(JSON.stringify([input_path, provider_id]));
+            return [
+                {
+                    kind: "missing-extractor-dependency",
+                    input_path,
+                    ...emptyGap,
+                    ...(affected === undefined
+                        ? {}
+                        : {
+                            handler: affected.handler,
+                            provider_id,
+                            range: affected.range,
+                            root_file_range: affected.root_file_range,
+                        }),
+                    dependencies: [...dependencies],
+                    continuation_id: continuation(dependencies.length > 0
+                        ? GAP_CONTINUATIONS["missing-extractor-dependency"]
+                        : UNNAMED_DEPENDENCY_CONTINUATION),
+                },
+            ];
+        }),
+        ...normalized.failed_extraction_stages
+            .filter(({ kind }) => kind === "missing-extractor-dependency")
+            .map(({ input_path, provider_id, handler, dependencies, }) => ({
+            kind: "missing-extractor-dependency",
+            input_path,
+            ...emptyGap,
+            handler,
+            provider_id,
+            dependencies: [...dependencies],
+            continuation_id: continuation(dependencies.length > 0
+                ? GAP_CONTINUATIONS["missing-extractor-dependency"]
+                : UNNAMED_DEPENDENCY_CONTINUATION),
+        })),
+        // Standalone reports name only the task; do not borrow another stage's id.
+        ...normalized.missing_dependencies.map(({ input_path, dependencies }) => ({
+            kind: "missing-extractor-dependency",
+            input_path,
+            ...emptyGap,
+            dependencies: [...dependencies],
+            continuation_id: continuation(dependencies.length > 0
+                ? GAP_CONTINUATIONS["missing-extractor-dependency"]
+                : UNNAMED_DEPENDENCY_CONTINUATION),
+        })),
+    ];
+};
+const extractionGaps = (unpublished, files, normalized, maxDepth) => {
+    // Intern before row construction: N gaps retain N identities, while K unique
+    // recovery instructions consume prose only K times in the public result.
+    const instructions = new Map();
+    const continuation = (instruction) => {
+        const known = instructions.get(instruction);
+        if (known !== undefined)
+            return known;
+        const id = createHash("sha256").update(instruction).digest("hex");
+        instructions.set(instruction, id);
+        return id;
+    };
+    const dependencyGaps = dependencyExtractionGaps(normalized, continuation);
+    const publishedFiles = new Map(files.map((file) => [`$output/${file.relative_path}`, file]));
+    const nestedContinuationId = (inputPath) => {
+        return continuation(nestedUnknownContinuation(publishedFiles.get(inputPath)));
+    };
+    const chunkGaps = (kind, matches) => normalized.chunks.filter(matches).map((chunk) => ({
+        kind,
+        input_path: chunk.input_path,
+        ...emptyGap,
+        handler: chunk.handler,
+        provider_id: chunk.provider_id,
+        range: chunk.range,
+        root_file_range: chunk.root_file_range,
+        dependencies: [],
+        continuation_id: kind === "unknown-chunk-handler" &&
+            chunk.input_path.startsWith("$output/")
+            ? nestedContinuationId(chunk.input_path)
+            : continuation(GAP_CONTINUATIONS[kind]),
+    }));
+    // Chunks whose failure a dependency row already covers stay out of the
+    // generic extractor-failure emission.
+    const dependencyChunkKeys = new Set(normalized.chunk_missing_dependencies.map(({ input_path, provider_id }) => JSON.stringify([input_path, provider_id])));
+    // A depth ceiling can only be re-rooted through a published child that a
+    // fresh firmware input could actually accept; the index is only needed
+    // when a depth row will actually consult it.
+    const ceilingReached = maxDepth >= MAX_EXTRACTION_DEPTH &&
+        normalized.depth_limited_paths.length > 0;
+    const reRootablePaths = new Map();
+    if (ceilingReached)
+        for (const [filePath, file] of [...publishedFiles].sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))) {
+            const size = file.size;
+            if (size <= 0 || size > FIRMWARE_LIMITS.inputBytes)
+                continue;
+            // The published file itself can re-root a fresh run; so can every
+            // directory containing it.
+            const segments = filePath.split("/");
+            while (segments.length > 1) {
+                const ancestor = segments.join("/");
+                const childPaths = reRootablePaths.get(ancestor) ?? new Set();
+                childPaths.add(file.path);
+                reRootablePaths.set(ancestor, childPaths);
+                segments.pop();
+            }
+        }
+    const depthContinuationIds = new Map();
+    const depthContinuationId = (inputPath) => {
+        const existing = depthContinuationIds.get(inputPath);
+        if (existing !== undefined)
+            return existing;
+        const id = continuation(depthContinuation(maxDepth, [...(reRootablePaths.get(inputPath) ?? [])].sort()));
+        depthContinuationIds.set(inputPath, id);
+        return id;
+    };
+    const gaps = [
+        ...dependencyGaps,
+        ...normalized.failed_extraction_stages
+            .filter(({ kind }) => kind === "extractor-failure")
+            .map(({ input_path, provider_id, handler }) => ({
+            kind: "extractor-failure",
+            input_path,
+            ...emptyGap,
+            handler,
+            provider_id,
+            dependencies: [],
+            continuation_id: continuation("The producer retained this extraction stage's failure in diagnostics. Review the stage report and correct the reported cause before rerunning extract_firmware on the same immutable input with a fresh output_directory; this report establishes no byte-region ownership."),
+        })),
+        ...chunkGaps("unknown-chunk-handler", (chunk) => chunk.handler === null),
+        ...chunkGaps("encrypted-chunk", (chunk) => chunk.encrypted === true),
+        ...chunkGaps("extractor-failure", (chunk) => chunk.extraction_failed === true &&
+            chunk.handler !== null &&
+            chunk.encrypted !== true &&
+            // The chunk's own dependency row already carries its recovery; a
+            // task-wide dependency names no region and replaces nothing.
+            !dependencyChunkKeys.has(JSON.stringify([chunk.input_path, chunk.provider_id]))),
+        ...normalized.depth_limited_paths.map((input_path) => ({
+            kind: "depth-limited",
+            input_path,
+            ...emptyGap,
+            dependencies: [],
+            continuation_id: depthContinuationId(input_path),
+        })),
+        ...unpublished.map((entry) => ({
+            kind: "unpublished-entry",
+            input_path: `$output/${entry.relative_path}`,
+            ...emptyGap,
+            relative_path: entry.relative_path,
+            dependencies: [],
+            continuation_id: continuation(GAP_CONTINUATIONS["unpublished-entry"]),
+        })),
+    ];
+    gaps.sort((left, right) => gapSortKey(left) < gapSortKey(right)
+        ? -1
+        : gapSortKey(left) > gapSortKey(right)
+            ? 1
+            : 0);
+    return {
+        extraction_gaps: gaps,
+        extraction_continuations: [...instructions].map(([instruction, id]) => ({
+            id,
+            instruction,
+        })),
+    };
+};