@riddledc/riddle-proof 0.7.201 → 0.7.203

package/README.md

@@ -202,6 +202,48 @@ generic inline-script warning threshold. Use `--strict=true` when you
 deliberately want Riddle's non-critical script-safety warnings to block the run.
 Critical script-safety violations remain blocked by Riddle either way.
 
+Use `--viewport-name <name>` to run only one named viewport from a
+multi-viewport profile while preserving viewport-scoped setup actions and
+checks:
+
+```sh
+riddle-proof-loop run-profile \
+  --profile .riddle-proof/profiles/pricing.json \
+  --url https://example.com \
+  --viewport-name ipad-mini \
+  --output artifacts/riddle-proof/pricing-ipad-mini
+```
+
+When `--output` / `--output-dir` is set, hosted profile runs write
+`riddle-job.json` as soon as Riddle returns a job id. If the local process is
+interrupted or pruned, recover the profile artifacts from the hosted job:
+
+```sh
+riddle-proof-loop run-profile recover \
+  --profile .riddle-proof/profiles/pricing.json \
+  --url https://example.com \
+  --job job_abc123 \
+  --viewport-name ipad-mini \
+  --output artifacts/riddle-proof/pricing-ipad-mini-recovered
+```
+
+When a matrix run is executed as separate named-viewport jobs, aggregate the
+saved child outputs back into one profile judgment:
+
+```sh
+riddle-proof-loop run-profile aggregate \
+  --profile .riddle-proof/profiles/pricing.json \
+  --url https://example.com \
+  --input-dir artifacts/riddle-proof/pricing-matrix \
+  --output artifacts/riddle-proof/pricing-matrix
+```
+
+`--input-dir` reads child `*/profile-result.json` files such as
+`desktop/profile-result.json` and `ipad-mini/profile-result.json`, then writes
+the combined `profile-result.json` and `summary.md`. Use `--inputs` with a
+comma-separated list of files or directories when the child outputs do not
+share one parent directory.
+
 When promoting proof artifacts into a durable public profile, avoid guessing
 which backend or runner tokens are preserved inside `proof.json`. Derive the
 `body_contains` fragments from the artifact body first:

package/dist/cli.cjs

@@ -16223,7 +16223,9 @@ function usage() {
     "  riddle-proof-loop respond --state-path <path> --response-json <file|json|->",
     "  riddle-proof-loop respond --state-path <path> --decision <decision> --summary <text> [--payload-json <file|json|->]",
     "  riddle-proof-loop status --state-path <path>",
-    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--strict true|false; default false] [--split-viewports true|false; default false] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json] [--quiet]",
+    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--viewport-name <name[,name...]>] [--strict true|false; default false] [--split-viewports true|false; default false] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json] [--quiet]",
+    "  riddle-proof-loop run-profile aggregate --profile <file|json|-> --url <base-url> --input-dir <dir>|--inputs <path[,path...]> [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
+    "  riddle-proof-loop run-profile recover --profile <file|json|-> --url <base-url> --job <job-id> [--viewport-name <name[,name...]>] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
     "  riddle-proof-loop profile-body-assertions --artifact <file|url|-> --candidates-json <file|json|-> [--required-json <file|json|->] [--format json|body-contains]",
     "  riddle-proof-loop profile-http-status-preflight --profile <file|json|-> --url <base-url> [--format json|summary]",
     "  riddle-proof-loop riddle-preview-deploy <build-dir> <label> [--framework spa|static]",
@@ -16283,6 +16285,11 @@ function runProfileStrictOption(options) {
 function runProfileSplitViewportsOption(options) {
   return optionBoolean(options, "splitViewports") ?? false;
 }
+function runProfileViewportNamesOption(options) {
+  const raw = optionString(options, "viewportName") ?? optionString(options, "viewportNames");
+  if (!raw) return [];
+  return raw.split(",").map((part) => part.trim()).filter(Boolean);
+}
 var DEFAULT_PROFILE_UNSUBMITTED_RETRY_TIMEOUT_MS = 9e4;
 var DEFAULT_PROFILE_UNSUBMITTED_RETRIES = 2;
 function optionNumber(options, ...keys) {
@@ -16883,6 +16890,61 @@ function profileHasRouteExitAffordanceReceipt(receipts) {
     return routeFields.some((name) => setupReturnSummaryValue(receipt, [name]) !== void 0) || haystack.includes("route=") || haystack.includes("browserpath=");
   });
 }
+function profileCleanupLabelMatches(value) {
+  if (!value) return false;
+  return /\b(cleanup|clean|clear|reset|undo|discard|new)\b/i.test(value);
+}
+function profileHasCleanupBoundaryAffordanceReceipt(receipts) {
+  const visibleFields = [
+    "cleanupControlVisible",
+    "cleanupVisible",
+    "clearControlVisible",
+    "resetControlVisible",
+    "undoVisible",
+    "discardVisible",
+    "newControlVisible",
+    "exitControlVisible"
+  ];
+  const textFields = [
+    "cleanupControlText",
+    "cleanupText",
+    "clearControlText",
+    "resetControlText",
+    "undoText",
+    "discardText",
+    "newControlText",
+    "exitControlText",
+    "controlText",
+    "affordanceText"
+  ];
+  return receipts.some((receipt) => {
+    const storedTo = cliString(receipt.return_stored_to) || "";
+    const label = cliString(receipt.label) || "";
+    const path7 = cliString(receipt.path) || cliString(receipt.function_name) || "";
+    const summary = cliReturnSummaryLabel(receipt.return_summary) || "";
+    const haystack = `${storedTo} ${label} ${path7} ${summary}`.toLowerCase();
+    const mentionsCleanupBoundary = haystack.includes("cleanup") || haystack.includes("precleanup") || haystack.includes("pre-cleanup") || haystack.includes("boundary") || haystack.includes("undo") || haystack.includes("clear") || haystack.includes("reset") || haystack.includes("discard");
+    const visibleControl = visibleFields.some((name) => setupReturnSummaryValue(receipt, [name]) === true);
+    const controlText = textFields.map((name) => cliString(setupReturnSummaryValue(receipt, [name]))).find((value) => profileCleanupLabelMatches(value));
+    return mentionsCleanupBoundary && (visibleControl || Boolean(controlText));
+  });
+}
+function profileVisibleCleanupActionCount(setupViewports) {
+  const keys = /* @__PURE__ */ new Set();
+  const clickedReceipts = setupViewports.flatMap((viewport) => [
+    ...setupReceiptArray(viewport, "clicked"),
+    ...setupReceiptArray(viewport, "tap"),
+    ...setupReceiptArray(viewport, "tap_until")
+  ]);
+  clickedReceipts.forEach((receipt, index) => {
+    if (receipt.ok === false) return;
+    const text = cliString(receipt.text) || cliString(receipt.label) || cliString(receipt.target) || cliString(receipt.selector);
+    if (!profileCleanupLabelMatches(text)) return;
+    const ordinal = cliFiniteNumber(receipt.ordinal);
+    keys.add(ordinal === void 0 ? `idx:${index}:${text}` : `ord:${ordinal}:${text}`);
+  });
+  return keys.size;
+}
 function profileHasOfflineAudioMetricsReceipt(receipts) {
   const metricFields = [
     "mixPeak",
@@ -16984,17 +17046,51 @@ function profileHasRecoveredStateReceipt(receipts) {
     const path7 = cliString(receipt.path) || cliString(receipt.function_name) || "";
     const summary = cliReturnSummaryLabel(receipt.return_summary) || "";
     const haystack = `${storedTo} ${label} ${path7} ${summary}`.toLowerCase();
-    const labelsRecovery = haystack.includes("recover") || haystack.includes("repaired") || haystack.includes("repair") || haystack.includes("try fix") || haystack.includes("tryfix") || haystack.includes("after-fix") || haystack.includes("fixed");
+    const labelsRecovery = haystack.includes("recover") || haystack.includes("repaired") || haystack.includes("repair") || haystack.includes("retry") || haystack.includes("restart") || haystack.includes("play again") || haystack.includes("playagain") || haystack.includes("play-again") || haystack.includes("try fix") || haystack.includes("tryfix") || haystack.includes("after-fix") || haystack.includes("fixed");
     if (!labelsRecovery) return false;
     const status = profileLowerSummaryValue(receipt, ["status", "state", "phase"]);
-    const outcome = profileLowerSummaryValue(receipt, ["lastOutcome", "outcome", "result"]);
-    const hasRecoveredState = ["valid", "success", "recovered", "fixed", "ready"].includes(status) || ["valid", "success", "recovered", "fixed", "ready"].includes(outcome);
+    const outcome = profileLowerSummaryValue(receipt, ["lastOutcome", "outcome", "result", "retryOutcome", "retry_outcome"]);
+    const hasRecoveredState = ["valid", "success", "recovered", "fixed", "ready"].includes(status) || ["valid", "success", "recovered", "fixed", "ready", "running_after_retry", "ready_after_retry"].includes(outcome);
     const hasValid = setupReturnSummaryValue(receipt, ["hasValid", "valid", "isValid"]) === true;
     const hasInvalid = setupReturnSummaryValue(receipt, ["hasInvalid", "invalid", "isInvalid"]);
     const success = setupReturnSummaryValue(receipt, ["success", "recovered", "fixed"]) === true;
-    return hasRecoveredState || success || hasValid && hasInvalid === false;
+    const leftTerminalState = setupReturnSummaryValue(receipt, ["leftTerminalState", "left_terminal_state"]) === true;
+    const retrySurfaceReady = setupReturnSummaryValue(receipt, ["retrySurfaceReady", "retry_surface_ready"]) === true;
+    return hasRecoveredState || success || hasValid && hasInvalid === false || leftTerminalState && retrySurfaceReady;
   });
 }
+function profileMetadataHasGeneratedOutputContract(metadata) {
+  const contract = cliRecord(metadata.declared_state_contract);
+  if (!contract) return false;
+  const keys = Object.keys(contract).join(" ").toLowerCase();
+  const values = Object.values(contract).map((value) => cliString(value)?.toLowerCase() || "").join(" ");
+  const haystack = `${keys} ${values}`;
+  return haystack.includes("generated_output") || haystack.includes("generated output") || haystack.includes("output-size") || haystack.includes("output size") || haystack.includes("output result") || haystack.includes("optimizer size");
+}
+function profileHasGeneratedOutputReceipt(receipts) {
+  let outputReady = false;
+  let outputChanged = false;
+  for (const receipt of receipts) {
+    const storedTo = cliString(receipt.return_stored_to) || "";
+    const label = cliString(receipt.label) || "";
+    const path7 = cliString(receipt.path) || cliString(receipt.function_name) || "";
+    const summary = cliReturnSummaryLabel(receipt.return_summary) || "";
+    const haystack = `${storedTo} ${label} ${path7} ${summary}`.toLowerCase();
+    const readySignal = setupReturnSummaryValue(receipt, ["outputReady", "outputStillReady"]) === true || cliFiniteNumber(setupReturnSummaryValue(receipt, ["surfaceCount", "before.surfaceCount", "after.surfaceCount"])) !== void 0 || setupReturnSummaryValue(receipt, ["size", "before.size", "after.size", "size.text", "before.size.text", "after.size.text"]) !== void 0;
+    if (readySignal && (haystack.includes("output") || haystack.includes("size") || haystack.includes("result"))) {
+      outputReady = true;
+    }
+    const beforeBytes = cliFiniteNumber(setupReturnSummaryValue(receipt, ["before.size.outputBytes", "before.outputBytes", "beforeBytes"]));
+    const afterBytes = cliFiniteNumber(setupReturnSummaryValue(receipt, ["after.size.outputBytes", "after.outputBytes", "afterBytes"]));
+    const beforeText = cliString(setupReturnSummaryValue(receipt, ["before.size.text", "before.outputText", "beforeText"]));
+    const afterText = cliString(setupReturnSummaryValue(receipt, ["after.size.text", "after.outputText", "afterText"]));
+    const explicitChange = setupReturnSummaryValue(receipt, ["sizeChanged", "outputChanged", "resultChanged"]) === true;
+    const byteChange = beforeBytes !== void 0 && afterBytes !== void 0 && beforeBytes !== afterBytes;
+    const textChange = Boolean(beforeText && afterText && beforeText !== afterText);
+    if (explicitChange || byteChange || textChange) outputChanged = true;
+  }
+  return outputReady && outputChanged;
+}
 function profilePackReceiptStatus(result, metadata, receipt) {
   const text = receipt.toLowerCase();
   const setupSummary = profileSetupSummaryRecord(result);
@@ -17025,6 +17121,7 @@ function profilePackReceiptStatus(result, metadata, receipt) {
   const clickFallbackTapCount = clickFallbackTapKeys.size;
   const tapUntilCount = profileSetupReceiptTotal(setupViewports, "tap_until");
   const visibleUiActionCount = clickCount + profileSetupReceiptTotal(setupViewports, "tap") + tapUntilCount;
+  const visibleCleanupActionCount = profileVisibleCleanupActionCount(setupViewports);
   const setupFailureCount = profileSetupFailureCount(setupViewports);
   const setupObstructionCount = profileSetupObstructionCount(setupViewports);
   const inputDispatchCount = profileSetupReceiptTotal(setupViewports, "drag") + profileSetupReceiptTotal(setupViewports, "tap") + tapUntilCount + profileSetupReceiptTotal(setupViewports, "press") + profileSetupReceiptTotal(setupViewports, "keyboard_sequence");
@@ -17060,6 +17157,7 @@ function profilePackReceiptStatus(result, metadata, receipt) {
   const hasTextAbsence = profileHasPassedCheck(result, ["text_absent", "selector_text_absent"]);
   const hasMeasuredStateChange = hasNaturalInput || hasCanvasChange || valueReceipts.some((item) => setupReturnSummaryValue(item, ["changed"]) === true || setupReturnSummaryValue(item, ["nonWhiteDelta", "darkDelta", "pixelDelta", "movementDelta"]) !== void 0);
   const hasRouteExitAffordanceReceipt = profileHasRouteExitAffordanceReceipt(valueReceipts);
+  const hasCleanupBoundaryAffordanceReceipt = profileHasCleanupBoundaryAffordanceReceipt(valueReceipts);
   const hasOfflineAudioMetricsReceipt = profileHasOfflineAudioMetricsReceipt(valueReceipts);
   const hasActiveRouteLocalProofReceipt = profileHasActiveRouteLocalProofReceipt(valueReceipts);
   const hasTerminalLossReceipt = profileHasTerminalLossReceipt(valueReceipts);
@@ -17068,6 +17166,8 @@ function profilePackReceiptStatus(result, metadata, receipt) {
   const hasControlledSuccessLaunchReceipt = profileHasControlledLaunchReceipt(valueReceipts, "success");
   const hasRouteContinuationReceipt = profileHasRouteContinuationReceipt(valueReceipts);
   const hasRecoveredStateReceipt = profileHasRecoveredStateReceipt(valueReceipts);
+  const hasGeneratedOutputContract = profileMetadataHasGeneratedOutputContract(metadata);
+  const hasGeneratedOutputReceipt = profileHasGeneratedOutputReceipt(valueReceipts);
   const failedCleanupInventoryReason = profileFailedCleanupInventoryReason(setupViewports);
   const passedCleanupInventoryReason = profilePassedCleanupInventoryReason(setupViewports);
   if (text.includes("artifact link") || text.includes("artifact path")) {
@@ -17121,6 +17221,13 @@ function profilePackReceiptStatus(result, metadata, receipt) {
     }
     return profileReceiptSignalStatus(hasTextAbsence, "absence check passed", "absence check missing");
   }
+  if (text.includes("generated-output") || text.includes("generated output") || text.includes("output-size") || text.includes("output size") || (text.includes("output") || text.includes("result")) && (text.includes("mutation") || text.includes("final"))) {
+    return profileReceiptSignalStatus(
+      hasGeneratedOutputContract && hasGeneratedOutputReceipt,
+      "generated-output mutation receipt present",
+      "generated-output mutation receipt missing"
+    );
+  }
   if (text.includes("recovered") || text.includes("final state")) {
     return profileReceiptSignalStatus(hasStateContract || hasTextVisibility, "final state receipt present", "final state receipt missing");
   }
@@ -17177,6 +17284,13 @@ function profilePackReceiptStatus(result, metadata, receipt) {
       "route continuation receipt missing"
     );
   }
+  if (text.includes("cleanup") && text.includes("action") && (text.includes("visible ui") || text.includes("visible"))) {
+    return profileReceiptSignalStatus(
+      visibleCleanupActionCount > 0,
+      `visible cleanup action receipt present (${visibleCleanupActionCount})`,
+      "visible cleanup action receipt missing"
+    );
+  }
   if (text.includes("through visible ui") || text.includes("visible ui action") || text.includes("ui-routed") || text.includes("ui routed") || text.includes("visible") && text.includes("route") && text.includes("exit") && text.includes("action") || text.includes("visible") && text.includes("mode") && text.includes("exit") && text.includes("action")) {
     return profileReceiptSignalStatus(
       visibleUiActionCount > 0,
@@ -17191,6 +17305,13 @@ function profilePackReceiptStatus(result, metadata, receipt) {
       "affordance receipt missing"
     );
   }
+  if (text.includes("cleanup") && (text.includes("affordance") || text.includes("control") || text.includes("boundary") || text.includes("inventory"))) {
+    return profileReceiptSignalStatus(
+      hasCleanupBoundaryAffordanceReceipt,
+      "visible cleanup affordance receipt present",
+      "visible cleanup affordance receipt missing"
+    );
+  }
   if (text.includes("retry") || text.includes("repair") || text.includes("reset") || text.includes("affordance")) {
     return profileReceiptSignalStatus(hasStateContract || clickCount > 0, "affordance or transition receipt present", "affordance receipt missing");
   }
@@ -18528,6 +18649,21 @@ function writeProfileOutput(outputDir, result) {
   if (result.evidence?.dom_summary) (0, import_node_fs6.writeFileSync)(import_node_path6.default.join(outputDir, "dom-summary.json"), `${JSON.stringify(result.evidence.dom_summary, null, 2)}
 `);
 }
+function writeRiddleJobReceipt(outputDir, input) {
+  if (!outputDir) return;
+  (0, import_node_fs6.mkdirSync)(outputDir, { recursive: true });
+  (0, import_node_fs6.writeFileSync)(import_node_path6.default.join(outputDir, "riddle-job.json"), `${JSON.stringify({
+    version: "riddle-proof.riddle-job-receipt.v1",
+    profile_name: input.profile.name,
+    job_id: input.jobId,
+    target_url: input.targetUrl,
+    viewport: input.viewport || null,
+    captured_at: (/* @__PURE__ */ new Date()).toISOString(),
+    created: input.created || null,
+    recovery_command: `riddle-proof-loop run-profile recover --profile <profile> --job ${input.jobId} --output-dir ${outputDir}`
+  }, null, 2)}
+`);
+}
 async function readArtifactJson(artifact) {
   const target = artifact.url || artifact.path;
   if (!target) return void 0;
@@ -18731,6 +18867,43 @@ function profileForSplitViewport(profile, viewport) {
     }
   };
 }
+function profileItemAppliesToAnySelectedViewport(item, viewports) {
+  if (!item.viewports?.length) return true;
+  const names = new Set(viewports.map((viewport) => viewport.name).filter(Boolean));
+  return item.viewports.some((name) => names.has(name));
+}
+function profileForSelectedViewports(profile, viewports) {
+  const suffix = viewports.map((viewport) => viewport.name || `${viewport.width}x${viewport.height}`).join("-");
+  const setupActions = profile.target.setup_actions?.filter((action) => profileItemAppliesToAnySelectedViewport(action, viewports));
+  return {
+    ...profile,
+    name: `${profile.name}-${suffix}`,
+    checks: profile.checks.filter((check) => profileItemAppliesToAnySelectedViewport(check, viewports)),
+    target: {
+      ...profile.target,
+      viewports,
+      ...setupActions ? { setup_actions: setupActions } : {}
+    },
+    metadata: {
+      ...profile.metadata || {},
+      selected_parent_profile: profile.name,
+      selected_viewports: viewports.map((viewport) => viewport.name || `${viewport.width}x${viewport.height}`)
+    }
+  };
+}
+function profileWithSelectedViewportNamesForCli(profile, options) {
+  const names = runProfileViewportNamesOption(options);
+  if (!names.length) return profile;
+  const requested = new Set(names);
+  const viewports = profile.target.viewports.filter((viewport) => viewport.name && requested.has(viewport.name));
+  const matched = new Set(viewports.map((viewport) => viewport.name).filter(Boolean));
+  const missing = names.filter((name) => !matched.has(name));
+  if (missing.length) {
+    const available = profile.target.viewports.map((viewport) => viewport.name).filter(Boolean).join(", ") || "none";
+    throw new Error(`Unknown --viewport-name ${missing.join(", ")}. Available viewport names: ${available}.`);
+  }
+  return profileForSelectedViewports(profile, viewports);
+}
 function safeProfileOutputSegment(value) {
   const safe = value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
   return safe || "viewport";
@@ -18741,6 +18914,78 @@ function splitViewportOutputDir(outputDir, viewportName, seen) {
   seen.set(base, count + 1);
   return import_node_path6.default.join(outputDir, count ? `${base}-${count + 1}` : base);
 }
+function profileResultPathFromInput(inputPath) {
+  if (!(0, import_node_fs6.existsSync)(inputPath)) throw new Error(`Profile aggregate input path does not exist: ${inputPath}`);
+  const stat = (0, import_node_fs6.statSync)(inputPath);
+  if (stat.isFile()) return [inputPath];
+  if (!stat.isDirectory()) throw new Error(`Profile aggregate input path must be a file or directory: ${inputPath}`);
+  const childProfileResults = (0, import_node_fs6.readdirSync)(inputPath, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => import_node_path6.default.join(inputPath, entry.name, "profile-result.json")).filter((candidate) => (0, import_node_fs6.existsSync)(candidate));
+  if (childProfileResults.length) return childProfileResults;
+  const directProfileResult = import_node_path6.default.join(inputPath, "profile-result.json");
+  if ((0, import_node_fs6.existsSync)(directProfileResult)) return [directProfileResult];
+  throw new Error(`Profile aggregate input directory has no child profile-result.json files: ${inputPath}`);
+}
+function runProfileAggregateInputPathsOption(options) {
+  const rawInputs = [
+    optionString(options, "input"),
+    optionString(options, "inputs"),
+    optionString(options, "inputFile"),
+    optionString(options, "inputFiles")
+  ].filter((value) => Boolean(value));
+  const explicitInputs = rawInputs.flatMap((raw) => raw.split(",").map((part) => part.trim()).filter(Boolean));
+  const inputDir = optionString(options, "inputDir") ?? optionString(options, "resultsDir") ?? optionString(options, "runDir");
+  const discoveredInputs = inputDir ? profileResultPathFromInput(inputDir) : [];
+  const paths = [...explicitInputs.flatMap(profileResultPathFromInput), ...discoveredInputs];
+  const uniquePaths = [...new Set(paths.map((inputPath) => import_node_path6.default.resolve(inputPath)))];
+  if (!uniquePaths.length) {
+    throw new Error("run-profile aggregate requires --input-dir <dir> or --inputs <path[,path...]>.");
+  }
+  return uniquePaths;
+}
+function readProfileResultForAggregate(resultPath) {
+  const parsed = readJsonValue(resultPath, resultPath);
+  if (parsed.version !== "riddle-proof.profile-result.v1" || !Array.isArray(parsed.checks)) {
+    throw new Error(`Profile aggregate input is not a riddle-proof.profile-result.v1 result: ${resultPath}`);
+  }
+  return parsed;
+}
+function profileResultIsAggregateParent(result) {
+  const mode = cliString(cliRecord(result.riddle)?.mode);
+  return (mode === "split-viewports" || mode === "named-viewport-aggregate") && (result.evidence?.viewports?.length || 0) > 1;
+}
+function aggregateProfileResultViewportName(result) {
+  const evidenceViewports = result.evidence?.viewports || [];
+  if (evidenceViewports.length === 1) return evidenceViewports[0].name;
+  const metadata = cliRecord(result.metadata);
+  const splitViewport = cliString(metadata?.split_viewport);
+  if (splitViewport) return splitViewport;
+  const selectedViewports = Array.isArray(metadata?.selected_viewports) ? metadata.selected_viewports.map(cliString).filter((name) => Boolean(name)) : [];
+  if (selectedViewports.length === 1) return selectedViewports[0];
+  return void 0;
+}
+function aggregateProfileResultViewport(profile, result, resultPath) {
+  const viewportName = aggregateProfileResultViewportName(result);
+  const parentViewport = viewportName ? profile.target.viewports.find((viewport) => viewport.name === viewportName) : void 0;
+  if (parentViewport) return parentViewport;
+  const evidenceViewport = result.evidence?.viewports?.length === 1 ? result.evidence.viewports[0] : void 0;
+  if (evidenceViewport && typeof evidenceViewport.name === "string" && typeof evidenceViewport.width === "number" && Number.isFinite(evidenceViewport.width) && typeof evidenceViewport.height === "number" && Number.isFinite(evidenceViewport.height)) {
+    return {
+      name: evidenceViewport.name,
+      width: evidenceViewport.width,
+      height: evidenceViewport.height
+    };
+  }
+  throw new Error(`Profile aggregate input must be a single named viewport result or include selected viewport metadata: ${resultPath}`);
+}
+function sortAggregateChildRuns(profile, childRuns) {
+  const viewportOrder = new Map(profile.target.viewports.map((viewport, index) => [viewport.name, index]));
+  return [...childRuns].sort((a, b) => {
+    const aIndex = viewportOrder.get(a.viewport.name) ?? Number.MAX_SAFE_INTEGER;
+    const bIndex = viewportOrder.get(b.viewport.name) ?? Number.MAX_SAFE_INTEGER;
+    if (aIndex !== bIndex) return aIndex - bIndex;
+    return a.viewport.name.localeCompare(b.viewport.name);
+  });
+}
 function splitViewportArtifactRefs(input) {
   return (input.result.artifacts.riddle_artifacts || []).map((artifact) => ({
     ...artifact,
@@ -18751,7 +18996,7 @@ function sumDefinedNumbers(values) {
   const numbers = values.filter((value) => typeof value === "number" && Number.isFinite(value));
   return numbers.length ? numbers.reduce((sum, value) => sum + value, 0) : void 0;
 }
-function splitViewportRiddleMetadata(childRuns) {
+function splitViewportRiddleMetadata(childRuns, mode = "split-viewports") {
   const splitJobs = childRuns.map(({ viewport, result }) => ({
     viewport: viewport.name,
     job_id: result.riddle?.job_id,
@@ -18768,9 +19013,9 @@ function splitViewportRiddleMetadata(childRuns) {
     artifact_recovery: result.riddle?.artifact_recovery
   }));
   return {
-    mode: "split-viewports",
+    mode,
     job_count: childRuns.length,
-    status: "split-viewports",
+    status: mode,
     terminal: childRuns.every(({ result }) => result.riddle?.terminal !== false),
     artifact_recovery: childRuns.some(({ result }) => result.riddle?.artifact_recovery === true),
     queue_elapsed_ms: sumDefinedNumbers(splitJobs.map((job) => job.queue_elapsed_ms)),
@@ -18919,6 +19164,13 @@ async function runSingleRiddleProfileForCli(profile, options, input) {
       const directResult = extractRiddleProofProfileResult(created);
       return directResult ? withRiddleMetadata(withProfileMetadata(profile, directResult), { artifacts: collectRiddleProfileArtifactRefs(created) }) : createRiddleProofProfileInsufficientResult({ profile, runner, error: "Riddle run response was missing job_id.", artifacts: collectRiddleProfileArtifactRefs(created) });
     }
+    writeRiddleJobReceipt(input.outputDir, {
+      profile,
+      jobId,
+      targetUrl,
+      viewport: profile.target.viewports[0],
+      created
+    });
     poll = await client.pollJob(jobId, pollOptions);
     if (attempt < retryLimit && shouldRetryUnsubmittedRiddleJob(poll)) {
       const recoveredResult = await recoverProfileResultFromRiddleArtifacts(profile, {
@@ -18995,10 +19247,9 @@ async function runSplitViewportProfileForCli(profile, options, input) {
   const childRuns = [];
   for (const viewport of profile.target.viewports) {
     const childProfile = profileForSplitViewport(profile, viewport);
-    const result2 = await runSingleRiddleProfileForCli(childProfile, options, input);
-    if (outputDir) {
-      writeProfileOutput(splitViewportOutputDir(outputDir, viewport.name, seenOutputNames), result2);
-    }
+    const childOutputDir = outputDir ? splitViewportOutputDir(outputDir, viewport.name, seenOutputNames) : void 0;
+    const result2 = await runSingleRiddleProfileForCli(childProfile, options, { ...input, outputDir: childOutputDir });
+    if (childOutputDir) writeProfileOutput(childOutputDir, result2);
     childRuns.push({ viewport, profile: childProfile, result: result2 });
   }
   const artifacts = childRuns.flatMap(splitViewportArtifactRefs);
@@ -19020,6 +19271,85 @@ async function runSplitViewportProfileForCli(profile, options, input) {
   });
   return withSplitViewportWarnings(profile, withSplitViewportChildStatusCheck(profile, result, childRuns));
 }
+async function aggregateProfileResultsForCli(profile, options) {
+  const resultPaths = runProfileAggregateInputPathsOption(options);
+  const seenViewports = /* @__PURE__ */ new Set();
+  const childInputs = resultPaths.map((resultPath) => ({ resultPath, result: readProfileResultForAggregate(resultPath) })).filter(({ result: result2 }) => !profileResultIsAggregateParent(result2));
+  if (!childInputs.length) {
+    throw new Error("run-profile aggregate found no single-viewport child profile results.");
+  }
+  const childRuns = sortAggregateChildRuns(profile, childInputs.map(({ resultPath, result: result2 }) => {
+    const viewport = aggregateProfileResultViewport(profile, result2, resultPath);
+    if (seenViewports.has(viewport.name)) {
+      throw new Error(`Profile aggregate received more than one result for viewport ${viewport.name}.`);
+    }
+    seenViewports.add(viewport.name);
+    return { viewport, profile: profileForSplitViewport(profile, viewport), result: result2 };
+  }));
+  const artifacts = childRuns.flatMap(splitViewportArtifactRefs);
+  const blocked = childRuns.filter(({ result: result2 }) => !result2.evidence || result2.status === "environment_blocked" || result2.status === "configuration_error");
+  if (blocked.length) {
+    return createRiddleProofProfileEnvironmentBlockedResult({
+      profile,
+      runner: "riddle",
+      error: splitViewportBlockedMessage(childRuns),
+      riddle: splitViewportRiddleMetadata(childRuns, "named-viewport-aggregate"),
+      artifacts
+    });
+  }
+  const evidence = aggregateSplitViewportEvidence(profile, childRuns);
+  const result = assessRiddleProofProfileEvidence(profile, evidence, {
+    runner: "riddle",
+    riddle: splitViewportRiddleMetadata(childRuns, "named-viewport-aggregate"),
+    artifacts
+  });
+  return withSplitViewportWarnings(profile, withSplitViewportChildStatusCheck(profile, result, childRuns));
+}
+async function recoverProfileForCli(profile, options) {
+  const runner = optionString(options, "runner") || "riddle";
+  if (runner !== "riddle") {
+    throw new Error(`Unsupported --runner ${runner}. The current CLI supports --runner riddle.`);
+  }
+  const jobId = optionString(options, "job") ?? optionString(options, "jobId");
+  if (!jobId) throw new Error("run-profile recover requires --job <job-id>.");
+  const client = createRiddleApiClient(riddleClientConfig(options));
+  let artifactPayload;
+  try {
+    artifactPayload = await client.requestJson(`/v1/jobs/${jobId}/artifacts`);
+  } catch (error) {
+    return createRiddleProofProfileEnvironmentBlockedResult({
+      profile,
+      runner,
+      error,
+      riddle: { job_id: jobId, terminal: false }
+    });
+  }
+  const artifacts = collectRiddleProfileArtifactRefs(artifactPayload);
+  const artifactStatus = riddleArtifactsPayloadStatus(artifactPayload);
+  const terminal = artifactStatus ? isTerminalRiddleJobStatus(artifactStatus) : artifacts.length > 0;
+  const recovered = await profileResultFromRiddleArtifacts(profile, artifacts, [artifactPayload]);
+  if (recovered) {
+    return withRiddleMetadata(recovered, {
+      job_id: jobId,
+      status: artifactStatus,
+      terminal,
+      artifacts,
+      artifactRecovery: true
+    });
+  }
+  return createRiddleProofProfileInsufficientResult({
+    profile,
+    runner,
+    error: artifacts.length ? `Riddle job ${jobId} artifacts were recovered without a proof result.` : `Riddle job ${jobId} had no recoverable artifacts.`,
+    riddle: {
+      job_id: jobId,
+      status: artifactStatus,
+      terminal,
+      artifact_recovery: artifacts.length > 0
+    },
+    artifacts
+  });
+}
 async function runProfileForCli(profile, options) {
   const runner = optionString(options, "runner") || "riddle";
   if (runner !== "riddle") {
@@ -19029,7 +19359,7 @@ async function runProfileForCli(profile, options) {
   if (runProfileSplitViewportsOption(options) && profile.target.viewports.length > 1) {
     return runSplitViewportProfileForCli(profile, options, { client, runner });
   }
-  return runSingleRiddleProfileForCli(profile, options, { client, runner });
+  return runSingleRiddleProfileForCli(profile, options, { client, runner, outputDir: profileOutputDirOption(options) });
 }
 function requestForRun(options) {
   const statePath = optionString(options, "statePath");
@@ -19078,8 +19408,8 @@ async function main() {
     return;
   }
   if (command === "run-profile") {
-    const profile = normalizeProfileForCli(options);
-    const result = await runProfileForCli(profile, options);
+    const profile = profileWithSelectedViewportNamesForCli(normalizeProfileForCli(options), options);
+    const result = positional[1] === "recover" ? await recoverProfileForCli(profile, options) : positional[1] === "aggregate" ? await aggregateProfileResultsForCli(profile, options) : await runProfileForCli(profile, options);
     writeProfileOutput(profileOutputDirOption(options), result);
     const diagnosticLine = profileCliDiagnosticLine(result);
     if (diagnosticLine && optionBoolean(options, "quiet") !== true) {

package/dist/cli.js

@@ -38,7 +38,7 @@ import {
 import "./chunk-VY4Y5U57.js";
 
 // src/cli.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "fs";
 import path from "path";
 function usage() {
   return [
@@ -48,7 +48,9 @@ function usage() {
     "  riddle-proof-loop respond --state-path <path> --response-json <file|json|->",
     "  riddle-proof-loop respond --state-path <path> --decision <decision> --summary <text> [--payload-json <file|json|->]",
     "  riddle-proof-loop status --state-path <path>",
-    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--strict true|false; default false] [--split-viewports true|false; default false] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json] [--quiet]",
+    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--viewport-name <name[,name...]>] [--strict true|false; default false] [--split-viewports true|false; default false] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json] [--quiet]",
+    "  riddle-proof-loop run-profile aggregate --profile <file|json|-> --url <base-url> --input-dir <dir>|--inputs <path[,path...]> [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
+    "  riddle-proof-loop run-profile recover --profile <file|json|-> --url <base-url> --job <job-id> [--viewport-name <name[,name...]>] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
     "  riddle-proof-loop profile-body-assertions --artifact <file|url|-> --candidates-json <file|json|-> [--required-json <file|json|->] [--format json|body-contains]",
     "  riddle-proof-loop profile-http-status-preflight --profile <file|json|-> --url <base-url> [--format json|summary]",
     "  riddle-proof-loop riddle-preview-deploy <build-dir> <label> [--framework spa|static]",
@@ -108,6 +110,11 @@ function runProfileStrictOption(options) {
 function runProfileSplitViewportsOption(options) {
   return optionBoolean(options, "splitViewports") ?? false;
 }
+function runProfileViewportNamesOption(options) {
+  const raw = optionString(options, "viewportName") ?? optionString(options, "viewportNames");
+  if (!raw) return [];
+  return raw.split(",").map((part) => part.trim()).filter(Boolean);
+}
 var DEFAULT_PROFILE_UNSUBMITTED_RETRY_TIMEOUT_MS = 9e4;
 var DEFAULT_PROFILE_UNSUBMITTED_RETRIES = 2;
 function optionNumber(options, ...keys) {
@@ -708,6 +715,61 @@ function profileHasRouteExitAffordanceReceipt(receipts) {
     return routeFields.some((name) => setupReturnSummaryValue(receipt, [name]) !== void 0) || haystack.includes("route=") || haystack.includes("browserpath=");
   });
 }
+function profileCleanupLabelMatches(value) {
+  if (!value) return false;
+  return /\b(cleanup|clean|clear|reset|undo|discard|new)\b/i.test(value);
+}
+function profileHasCleanupBoundaryAffordanceReceipt(receipts) {
+  const visibleFields = [
+    "cleanupControlVisible",
+    "cleanupVisible",
+    "clearControlVisible",
+    "resetControlVisible",
+    "undoVisible",
+    "discardVisible",
+    "newControlVisible",
+    "exitControlVisible"
+  ];
+  const textFields = [
+    "cleanupControlText",
+    "cleanupText",
+    "clearControlText",
+    "resetControlText",
+    "undoText",
+    "discardText",
+    "newControlText",
+    "exitControlText",
+    "controlText",
+    "affordanceText"
+  ];
+  return receipts.some((receipt) => {
+    const storedTo = cliString(receipt.return_stored_to) || "";
+    const label = cliString(receipt.label) || "";
+    const path2 = cliString(receipt.path) || cliString(receipt.function_name) || "";
+    const summary = cliReturnSummaryLabel(receipt.return_summary) || "";
+    const haystack = `${storedTo} ${label} ${path2} ${summary}`.toLowerCase();
+    const mentionsCleanupBoundary = haystack.includes("cleanup") || haystack.includes("precleanup") || haystack.includes("pre-cleanup") || haystack.includes("boundary") || haystack.includes("undo") || haystack.includes("clear") || haystack.includes("reset") || haystack.includes("discard");
+    const visibleControl = visibleFields.some((name) => setupReturnSummaryValue(receipt, [name]) === true);
+    const controlText = textFields.map((name) => cliString(setupReturnSummaryValue(receipt, [name]))).find((value) => profileCleanupLabelMatches(value));
+    return mentionsCleanupBoundary && (visibleControl || Boolean(controlText));
+  });
+}
+function profileVisibleCleanupActionCount(setupViewports) {
+  const keys = /* @__PURE__ */ new Set();
+  const clickedReceipts = setupViewports.flatMap((viewport) => [
+    ...setupReceiptArray(viewport, "clicked"),
+    ...setupReceiptArray(viewport, "tap"),
+    ...setupReceiptArray(viewport, "tap_until")
+  ]);
+  clickedReceipts.forEach((receipt, index) => {
+    if (receipt.ok === false) return;
+    const text = cliString(receipt.text) || cliString(receipt.label) || cliString(receipt.target) || cliString(receipt.selector);
+    if (!profileCleanupLabelMatches(text)) return;
+    const ordinal = cliFiniteNumber(receipt.ordinal);
+    keys.add(ordinal === void 0 ? `idx:${index}:${text}` : `ord:${ordinal}:${text}`);
+  });
+  return keys.size;
+}
 function profileHasOfflineAudioMetricsReceipt(receipts) {
   const metricFields = [
     "mixPeak",
@@ -809,17 +871,51 @@ function profileHasRecoveredStateReceipt(receipts) {
     const path2 = cliString(receipt.path) || cliString(receipt.function_name) || "";
     const summary = cliReturnSummaryLabel(receipt.return_summary) || "";
     const haystack = `${storedTo} ${label} ${path2} ${summary}`.toLowerCase();
-    const labelsRecovery = haystack.includes("recover") || haystack.includes("repaired") || haystack.includes("repair") || haystack.includes("try fix") || haystack.includes("tryfix") || haystack.includes("after-fix") || haystack.includes("fixed");
+    const labelsRecovery = haystack.includes("recover") || haystack.includes("repaired") || haystack.includes("repair") || haystack.includes("retry") || haystack.includes("restart") || haystack.includes("play again") || haystack.includes("playagain") || haystack.includes("play-again") || haystack.includes("try fix") || haystack.includes("tryfix") || haystack.includes("after-fix") || haystack.includes("fixed");
     if (!labelsRecovery) return false;
     const status = profileLowerSummaryValue(receipt, ["status", "state", "phase"]);
-    const outcome = profileLowerSummaryValue(receipt, ["lastOutcome", "outcome", "result"]);
-    const hasRecoveredState = ["valid", "success", "recovered", "fixed", "ready"].includes(status) || ["valid", "success", "recovered", "fixed", "ready"].includes(outcome);
+    const outcome = profileLowerSummaryValue(receipt, ["lastOutcome", "outcome", "result", "retryOutcome", "retry_outcome"]);
+    const hasRecoveredState = ["valid", "success", "recovered", "fixed", "ready"].includes(status) || ["valid", "success", "recovered", "fixed", "ready", "running_after_retry", "ready_after_retry"].includes(outcome);
     const hasValid = setupReturnSummaryValue(receipt, ["hasValid", "valid", "isValid"]) === true;
     const hasInvalid = setupReturnSummaryValue(receipt, ["hasInvalid", "invalid", "isInvalid"]);
     const success = setupReturnSummaryValue(receipt, ["success", "recovered", "fixed"]) === true;
-    return hasRecoveredState || success || hasValid && hasInvalid === false;
+    const leftTerminalState = setupReturnSummaryValue(receipt, ["leftTerminalState", "left_terminal_state"]) === true;
+    const retrySurfaceReady = setupReturnSummaryValue(receipt, ["retrySurfaceReady", "retry_surface_ready"]) === true;
+    return hasRecoveredState || success || hasValid && hasInvalid === false || leftTerminalState && retrySurfaceReady;
   });
 }
+function profileMetadataHasGeneratedOutputContract(metadata) {
+  const contract = cliRecord(metadata.declared_state_contract);
+  if (!contract) return false;
+  const keys = Object.keys(contract).join(" ").toLowerCase();
+  const values = Object.values(contract).map((value) => cliString(value)?.toLowerCase() || "").join(" ");
+  const haystack = `${keys} ${values}`;
+  return haystack.includes("generated_output") || haystack.includes("generated output") || haystack.includes("output-size") || haystack.includes("output size") || haystack.includes("output result") || haystack.includes("optimizer size");
+}
+function profileHasGeneratedOutputReceipt(receipts) {
+  let outputReady = false;
+  let outputChanged = false;
+  for (const receipt of receipts) {
+    const storedTo = cliString(receipt.return_stored_to) || "";
+    const label = cliString(receipt.label) || "";
+    const path2 = cliString(receipt.path) || cliString(receipt.function_name) || "";
+    const summary = cliReturnSummaryLabel(receipt.return_summary) || "";
+    const haystack = `${storedTo} ${label} ${path2} ${summary}`.toLowerCase();
+    const readySignal = setupReturnSummaryValue(receipt, ["outputReady", "outputStillReady"]) === true || cliFiniteNumber(setupReturnSummaryValue(receipt, ["surfaceCount", "before.surfaceCount", "after.surfaceCount"])) !== void 0 || setupReturnSummaryValue(receipt, ["size", "before.size", "after.size", "size.text", "before.size.text", "after.size.text"]) !== void 0;
+    if (readySignal && (haystack.includes("output") || haystack.includes("size") || haystack.includes("result"))) {
+      outputReady = true;
+    }
+    const beforeBytes = cliFiniteNumber(setupReturnSummaryValue(receipt, ["before.size.outputBytes", "before.outputBytes", "beforeBytes"]));
+    const afterBytes = cliFiniteNumber(setupReturnSummaryValue(receipt, ["after.size.outputBytes", "after.outputBytes", "afterBytes"]));
+    const beforeText = cliString(setupReturnSummaryValue(receipt, ["before.size.text", "before.outputText", "beforeText"]));
+    const afterText = cliString(setupReturnSummaryValue(receipt, ["after.size.text", "after.outputText", "afterText"]));
+    const explicitChange = setupReturnSummaryValue(receipt, ["sizeChanged", "outputChanged", "resultChanged"]) === true;
+    const byteChange = beforeBytes !== void 0 && afterBytes !== void 0 && beforeBytes !== afterBytes;
+    const textChange = Boolean(beforeText && afterText && beforeText !== afterText);
+    if (explicitChange || byteChange || textChange) outputChanged = true;
+  }
+  return outputReady && outputChanged;
+}
 function profilePackReceiptStatus(result, metadata, receipt) {
   const text = receipt.toLowerCase();
   const setupSummary = profileSetupSummaryRecord(result);
@@ -850,6 +946,7 @@ function profilePackReceiptStatus(result, metadata, receipt) {
   const clickFallbackTapCount = clickFallbackTapKeys.size;
   const tapUntilCount = profileSetupReceiptTotal(setupViewports, "tap_until");
   const visibleUiActionCount = clickCount + profileSetupReceiptTotal(setupViewports, "tap") + tapUntilCount;
+  const visibleCleanupActionCount = profileVisibleCleanupActionCount(setupViewports);
   const setupFailureCount = profileSetupFailureCount(setupViewports);
   const setupObstructionCount = profileSetupObstructionCount(setupViewports);
   const inputDispatchCount = profileSetupReceiptTotal(setupViewports, "drag") + profileSetupReceiptTotal(setupViewports, "tap") + tapUntilCount + profileSetupReceiptTotal(setupViewports, "press") + profileSetupReceiptTotal(setupViewports, "keyboard_sequence");
@@ -885,6 +982,7 @@ function profilePackReceiptStatus(result, metadata, receipt) {
   const hasTextAbsence = profileHasPassedCheck(result, ["text_absent", "selector_text_absent"]);
   const hasMeasuredStateChange = hasNaturalInput || hasCanvasChange || valueReceipts.some((item) => setupReturnSummaryValue(item, ["changed"]) === true || setupReturnSummaryValue(item, ["nonWhiteDelta", "darkDelta", "pixelDelta", "movementDelta"]) !== void 0);
   const hasRouteExitAffordanceReceipt = profileHasRouteExitAffordanceReceipt(valueReceipts);
+  const hasCleanupBoundaryAffordanceReceipt = profileHasCleanupBoundaryAffordanceReceipt(valueReceipts);
   const hasOfflineAudioMetricsReceipt = profileHasOfflineAudioMetricsReceipt(valueReceipts);
   const hasActiveRouteLocalProofReceipt = profileHasActiveRouteLocalProofReceipt(valueReceipts);
   const hasTerminalLossReceipt = profileHasTerminalLossReceipt(valueReceipts);
@@ -893,6 +991,8 @@ function profilePackReceiptStatus(result, metadata, receipt) {
   const hasControlledSuccessLaunchReceipt = profileHasControlledLaunchReceipt(valueReceipts, "success");
   const hasRouteContinuationReceipt = profileHasRouteContinuationReceipt(valueReceipts);
   const hasRecoveredStateReceipt = profileHasRecoveredStateReceipt(valueReceipts);
+  const hasGeneratedOutputContract = profileMetadataHasGeneratedOutputContract(metadata);
+  const hasGeneratedOutputReceipt = profileHasGeneratedOutputReceipt(valueReceipts);
   const failedCleanupInventoryReason = profileFailedCleanupInventoryReason(setupViewports);
   const passedCleanupInventoryReason = profilePassedCleanupInventoryReason(setupViewports);
   if (text.includes("artifact link") || text.includes("artifact path")) {
@@ -946,6 +1046,13 @@ function profilePackReceiptStatus(result, metadata, receipt) {
     }
     return profileReceiptSignalStatus(hasTextAbsence, "absence check passed", "absence check missing");
   }
+  if (text.includes("generated-output") || text.includes("generated output") || text.includes("output-size") || text.includes("output size") || (text.includes("output") || text.includes("result")) && (text.includes("mutation") || text.includes("final"))) {
+    return profileReceiptSignalStatus(
+      hasGeneratedOutputContract && hasGeneratedOutputReceipt,
+      "generated-output mutation receipt present",
+      "generated-output mutation receipt missing"
+    );
+  }
   if (text.includes("recovered") || text.includes("final state")) {
     return profileReceiptSignalStatus(hasStateContract || hasTextVisibility, "final state receipt present", "final state receipt missing");
   }
@@ -1002,6 +1109,13 @@ function profilePackReceiptStatus(result, metadata, receipt) {
       "route continuation receipt missing"
     );
   }
+  if (text.includes("cleanup") && text.includes("action") && (text.includes("visible ui") || text.includes("visible"))) {
+    return profileReceiptSignalStatus(
+      visibleCleanupActionCount > 0,
+      `visible cleanup action receipt present (${visibleCleanupActionCount})`,
+      "visible cleanup action receipt missing"
+    );
+  }
   if (text.includes("through visible ui") || text.includes("visible ui action") || text.includes("ui-routed") || text.includes("ui routed") || text.includes("visible") && text.includes("route") && text.includes("exit") && text.includes("action") || text.includes("visible") && text.includes("mode") && text.includes("exit") && text.includes("action")) {
     return profileReceiptSignalStatus(
       visibleUiActionCount > 0,
@@ -1016,6 +1130,13 @@ function profilePackReceiptStatus(result, metadata, receipt) {
       "affordance receipt missing"
     );
   }
+  if (text.includes("cleanup") && (text.includes("affordance") || text.includes("control") || text.includes("boundary") || text.includes("inventory"))) {
+    return profileReceiptSignalStatus(
+      hasCleanupBoundaryAffordanceReceipt,
+      "visible cleanup affordance receipt present",
+      "visible cleanup affordance receipt missing"
+    );
+  }
   if (text.includes("retry") || text.includes("repair") || text.includes("reset") || text.includes("affordance")) {
     return profileReceiptSignalStatus(hasStateContract || clickCount > 0, "affordance or transition receipt present", "affordance receipt missing");
   }
@@ -2353,6 +2474,21 @@ function writeProfileOutput(outputDir, result) {
   if (result.evidence?.dom_summary) writeFileSync(path.join(outputDir, "dom-summary.json"), `${JSON.stringify(result.evidence.dom_summary, null, 2)}
 `);
 }
+function writeRiddleJobReceipt(outputDir, input) {
+  if (!outputDir) return;
+  mkdirSync(outputDir, { recursive: true });
+  writeFileSync(path.join(outputDir, "riddle-job.json"), `${JSON.stringify({
+    version: "riddle-proof.riddle-job-receipt.v1",
+    profile_name: input.profile.name,
+    job_id: input.jobId,
+    target_url: input.targetUrl,
+    viewport: input.viewport || null,
+    captured_at: (/* @__PURE__ */ new Date()).toISOString(),
+    created: input.created || null,
+    recovery_command: `riddle-proof-loop run-profile recover --profile <profile> --job ${input.jobId} --output-dir ${outputDir}`
+  }, null, 2)}
+`);
+}
 async function readArtifactJson(artifact) {
   const target = artifact.url || artifact.path;
   if (!target) return void 0;
@@ -2556,6 +2692,43 @@ function profileForSplitViewport(profile, viewport) {
     }
   };
 }
+function profileItemAppliesToAnySelectedViewport(item, viewports) {
+  if (!item.viewports?.length) return true;
+  const names = new Set(viewports.map((viewport) => viewport.name).filter(Boolean));
+  return item.viewports.some((name) => names.has(name));
+}
+function profileForSelectedViewports(profile, viewports) {
+  const suffix = viewports.map((viewport) => viewport.name || `${viewport.width}x${viewport.height}`).join("-");
+  const setupActions = profile.target.setup_actions?.filter((action) => profileItemAppliesToAnySelectedViewport(action, viewports));
+  return {
+    ...profile,
+    name: `${profile.name}-${suffix}`,
+    checks: profile.checks.filter((check) => profileItemAppliesToAnySelectedViewport(check, viewports)),
+    target: {
+      ...profile.target,
+      viewports,
+      ...setupActions ? { setup_actions: setupActions } : {}
+    },
+    metadata: {
+      ...profile.metadata || {},
+      selected_parent_profile: profile.name,
+      selected_viewports: viewports.map((viewport) => viewport.name || `${viewport.width}x${viewport.height}`)
+    }
+  };
+}
+function profileWithSelectedViewportNamesForCli(profile, options) {
+  const names = runProfileViewportNamesOption(options);
+  if (!names.length) return profile;
+  const requested = new Set(names);
+  const viewports = profile.target.viewports.filter((viewport) => viewport.name && requested.has(viewport.name));
+  const matched = new Set(viewports.map((viewport) => viewport.name).filter(Boolean));
+  const missing = names.filter((name) => !matched.has(name));
+  if (missing.length) {
+    const available = profile.target.viewports.map((viewport) => viewport.name).filter(Boolean).join(", ") || "none";
+    throw new Error(`Unknown --viewport-name ${missing.join(", ")}. Available viewport names: ${available}.`);
+  }
+  return profileForSelectedViewports(profile, viewports);
+}
 function safeProfileOutputSegment(value) {
   const safe = value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
   return safe || "viewport";
@@ -2566,6 +2739,78 @@ function splitViewportOutputDir(outputDir, viewportName, seen) {
   seen.set(base, count + 1);
   return path.join(outputDir, count ? `${base}-${count + 1}` : base);
 }
+function profileResultPathFromInput(inputPath) {
+  if (!existsSync(inputPath)) throw new Error(`Profile aggregate input path does not exist: ${inputPath}`);
+  const stat = statSync(inputPath);
+  if (stat.isFile()) return [inputPath];
+  if (!stat.isDirectory()) throw new Error(`Profile aggregate input path must be a file or directory: ${inputPath}`);
+  const childProfileResults = readdirSync(inputPath, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => path.join(inputPath, entry.name, "profile-result.json")).filter((candidate) => existsSync(candidate));
+  if (childProfileResults.length) return childProfileResults;
+  const directProfileResult = path.join(inputPath, "profile-result.json");
+  if (existsSync(directProfileResult)) return [directProfileResult];
+  throw new Error(`Profile aggregate input directory has no child profile-result.json files: ${inputPath}`);
+}
+function runProfileAggregateInputPathsOption(options) {
+  const rawInputs = [
+    optionString(options, "input"),
+    optionString(options, "inputs"),
+    optionString(options, "inputFile"),
+    optionString(options, "inputFiles")
+  ].filter((value) => Boolean(value));
+  const explicitInputs = rawInputs.flatMap((raw) => raw.split(",").map((part) => part.trim()).filter(Boolean));
+  const inputDir = optionString(options, "inputDir") ?? optionString(options, "resultsDir") ?? optionString(options, "runDir");
+  const discoveredInputs = inputDir ? profileResultPathFromInput(inputDir) : [];
+  const paths = [...explicitInputs.flatMap(profileResultPathFromInput), ...discoveredInputs];
+  const uniquePaths = [...new Set(paths.map((inputPath) => path.resolve(inputPath)))];
+  if (!uniquePaths.length) {
+    throw new Error("run-profile aggregate requires --input-dir <dir> or --inputs <path[,path...]>.");
+  }
+  return uniquePaths;
+}
+function readProfileResultForAggregate(resultPath) {
+  const parsed = readJsonValue(resultPath, resultPath);
+  if (parsed.version !== "riddle-proof.profile-result.v1" || !Array.isArray(parsed.checks)) {
+    throw new Error(`Profile aggregate input is not a riddle-proof.profile-result.v1 result: ${resultPath}`);
+  }
+  return parsed;
+}
+function profileResultIsAggregateParent(result) {
+  const mode = cliString(cliRecord(result.riddle)?.mode);
+  return (mode === "split-viewports" || mode === "named-viewport-aggregate") && (result.evidence?.viewports?.length || 0) > 1;
+}
+function aggregateProfileResultViewportName(result) {
+  const evidenceViewports = result.evidence?.viewports || [];
+  if (evidenceViewports.length === 1) return evidenceViewports[0].name;
+  const metadata = cliRecord(result.metadata);
+  const splitViewport = cliString(metadata?.split_viewport);
+  if (splitViewport) return splitViewport;
+  const selectedViewports = Array.isArray(metadata?.selected_viewports) ? metadata.selected_viewports.map(cliString).filter((name) => Boolean(name)) : [];
+  if (selectedViewports.length === 1) return selectedViewports[0];
+  return void 0;
+}
+function aggregateProfileResultViewport(profile, result, resultPath) {
+  const viewportName = aggregateProfileResultViewportName(result);
+  const parentViewport = viewportName ? profile.target.viewports.find((viewport) => viewport.name === viewportName) : void 0;
+  if (parentViewport) return parentViewport;
+  const evidenceViewport = result.evidence?.viewports?.length === 1 ? result.evidence.viewports[0] : void 0;
+  if (evidenceViewport && typeof evidenceViewport.name === "string" && typeof evidenceViewport.width === "number" && Number.isFinite(evidenceViewport.width) && typeof evidenceViewport.height === "number" && Number.isFinite(evidenceViewport.height)) {
+    return {
+      name: evidenceViewport.name,
+      width: evidenceViewport.width,
+      height: evidenceViewport.height
+    };
+  }
+  throw new Error(`Profile aggregate input must be a single named viewport result or include selected viewport metadata: ${resultPath}`);
+}
+function sortAggregateChildRuns(profile, childRuns) {
+  const viewportOrder = new Map(profile.target.viewports.map((viewport, index) => [viewport.name, index]));
+  return [...childRuns].sort((a, b) => {
+    const aIndex = viewportOrder.get(a.viewport.name) ?? Number.MAX_SAFE_INTEGER;
+    const bIndex = viewportOrder.get(b.viewport.name) ?? Number.MAX_SAFE_INTEGER;
+    if (aIndex !== bIndex) return aIndex - bIndex;
+    return a.viewport.name.localeCompare(b.viewport.name);
+  });
+}
 function splitViewportArtifactRefs(input) {
   return (input.result.artifacts.riddle_artifacts || []).map((artifact) => ({
     ...artifact,
@@ -2576,7 +2821,7 @@ function sumDefinedNumbers(values) {
   const numbers = values.filter((value) => typeof value === "number" && Number.isFinite(value));
   return numbers.length ? numbers.reduce((sum, value) => sum + value, 0) : void 0;
 }
-function splitViewportRiddleMetadata(childRuns) {
+function splitViewportRiddleMetadata(childRuns, mode = "split-viewports") {
   const splitJobs = childRuns.map(({ viewport, result }) => ({
     viewport: viewport.name,
     job_id: result.riddle?.job_id,
@@ -2593,9 +2838,9 @@ function splitViewportRiddleMetadata(childRuns) {
     artifact_recovery: result.riddle?.artifact_recovery
   }));
   return {
-    mode: "split-viewports",
+    mode,
     job_count: childRuns.length,
-    status: "split-viewports",
+    status: mode,
     terminal: childRuns.every(({ result }) => result.riddle?.terminal !== false),
     artifact_recovery: childRuns.some(({ result }) => result.riddle?.artifact_recovery === true),
     queue_elapsed_ms: sumDefinedNumbers(splitJobs.map((job) => job.queue_elapsed_ms)),
@@ -2744,6 +2989,13 @@ async function runSingleRiddleProfileForCli(profile, options, input) {
       const directResult = extractRiddleProofProfileResult(created);
       return directResult ? withRiddleMetadata(withProfileMetadata(profile, directResult), { artifacts: collectRiddleProfileArtifactRefs(created) }) : createRiddleProofProfileInsufficientResult({ profile, runner, error: "Riddle run response was missing job_id.", artifacts: collectRiddleProfileArtifactRefs(created) });
     }
+    writeRiddleJobReceipt(input.outputDir, {
+      profile,
+      jobId,
+      targetUrl,
+      viewport: profile.target.viewports[0],
+      created
+    });
     poll = await client.pollJob(jobId, pollOptions);
     if (attempt < retryLimit && shouldRetryUnsubmittedRiddleJob(poll)) {
       const recoveredResult = await recoverProfileResultFromRiddleArtifacts(profile, {
@@ -2820,10 +3072,9 @@ async function runSplitViewportProfileForCli(profile, options, input) {
   const childRuns = [];
   for (const viewport of profile.target.viewports) {
     const childProfile = profileForSplitViewport(profile, viewport);
-    const result2 = await runSingleRiddleProfileForCli(childProfile, options, input);
-    if (outputDir) {
-      writeProfileOutput(splitViewportOutputDir(outputDir, viewport.name, seenOutputNames), result2);
-    }
+    const childOutputDir = outputDir ? splitViewportOutputDir(outputDir, viewport.name, seenOutputNames) : void 0;
+    const result2 = await runSingleRiddleProfileForCli(childProfile, options, { ...input, outputDir: childOutputDir });
+    if (childOutputDir) writeProfileOutput(childOutputDir, result2);
     childRuns.push({ viewport, profile: childProfile, result: result2 });
   }
   const artifacts = childRuns.flatMap(splitViewportArtifactRefs);
@@ -2845,6 +3096,85 @@ async function runSplitViewportProfileForCli(profile, options, input) {
   });
   return withSplitViewportWarnings(profile, withSplitViewportChildStatusCheck(profile, result, childRuns));
 }
+async function aggregateProfileResultsForCli(profile, options) {
+  const resultPaths = runProfileAggregateInputPathsOption(options);
+  const seenViewports = /* @__PURE__ */ new Set();
+  const childInputs = resultPaths.map((resultPath) => ({ resultPath, result: readProfileResultForAggregate(resultPath) })).filter(({ result: result2 }) => !profileResultIsAggregateParent(result2));
+  if (!childInputs.length) {
+    throw new Error("run-profile aggregate found no single-viewport child profile results.");
+  }
+  const childRuns = sortAggregateChildRuns(profile, childInputs.map(({ resultPath, result: result2 }) => {
+    const viewport = aggregateProfileResultViewport(profile, result2, resultPath);
+    if (seenViewports.has(viewport.name)) {
+      throw new Error(`Profile aggregate received more than one result for viewport ${viewport.name}.`);
+    }
+    seenViewports.add(viewport.name);
+    return { viewport, profile: profileForSplitViewport(profile, viewport), result: result2 };
+  }));
+  const artifacts = childRuns.flatMap(splitViewportArtifactRefs);
+  const blocked = childRuns.filter(({ result: result2 }) => !result2.evidence || result2.status === "environment_blocked" || result2.status === "configuration_error");
+  if (blocked.length) {
+    return createRiddleProofProfileEnvironmentBlockedResult({
+      profile,
+      runner: "riddle",
+      error: splitViewportBlockedMessage(childRuns),
+      riddle: splitViewportRiddleMetadata(childRuns, "named-viewport-aggregate"),
+      artifacts
+    });
+  }
+  const evidence = aggregateSplitViewportEvidence(profile, childRuns);
+  const result = assessRiddleProofProfileEvidence(profile, evidence, {
+    runner: "riddle",
+    riddle: splitViewportRiddleMetadata(childRuns, "named-viewport-aggregate"),
+    artifacts
+  });
+  return withSplitViewportWarnings(profile, withSplitViewportChildStatusCheck(profile, result, childRuns));
+}
+async function recoverProfileForCli(profile, options) {
+  const runner = optionString(options, "runner") || "riddle";
+  if (runner !== "riddle") {
+    throw new Error(`Unsupported --runner ${runner}. The current CLI supports --runner riddle.`);
+  }
+  const jobId = optionString(options, "job") ?? optionString(options, "jobId");
+  if (!jobId) throw new Error("run-profile recover requires --job <job-id>.");
+  const client = createRiddleApiClient(riddleClientConfig(options));
+  let artifactPayload;
+  try {
+    artifactPayload = await client.requestJson(`/v1/jobs/${jobId}/artifacts`);
+  } catch (error) {
+    return createRiddleProofProfileEnvironmentBlockedResult({
+      profile,
+      runner,
+      error,
+      riddle: { job_id: jobId, terminal: false }
+    });
+  }
+  const artifacts = collectRiddleProfileArtifactRefs(artifactPayload);
+  const artifactStatus = riddleArtifactsPayloadStatus(artifactPayload);
+  const terminal = artifactStatus ? isTerminalRiddleJobStatus(artifactStatus) : artifacts.length > 0;
+  const recovered = await profileResultFromRiddleArtifacts(profile, artifacts, [artifactPayload]);
+  if (recovered) {
+    return withRiddleMetadata(recovered, {
+      job_id: jobId,
+      status: artifactStatus,
+      terminal,
+      artifacts,
+      artifactRecovery: true
+    });
+  }
+  return createRiddleProofProfileInsufficientResult({
+    profile,
+    runner,
+    error: artifacts.length ? `Riddle job ${jobId} artifacts were recovered without a proof result.` : `Riddle job ${jobId} had no recoverable artifacts.`,
+    riddle: {
+      job_id: jobId,
+      status: artifactStatus,
+      terminal,
+      artifact_recovery: artifacts.length > 0
+    },
+    artifacts
+  });
+}
 async function runProfileForCli(profile, options) {
   const runner = optionString(options, "runner") || "riddle";
   if (runner !== "riddle") {
@@ -2854,7 +3184,7 @@ async function runProfileForCli(profile, options) {
   if (runProfileSplitViewportsOption(options) && profile.target.viewports.length > 1) {
     return runSplitViewportProfileForCli(profile, options, { client, runner });
   }
-  return runSingleRiddleProfileForCli(profile, options, { client, runner });
+  return runSingleRiddleProfileForCli(profile, options, { client, runner, outputDir: profileOutputDirOption(options) });
 }
 function requestForRun(options) {
   const statePath = optionString(options, "statePath");
@@ -2903,8 +3233,8 @@ async function main() {
     return;
   }
   if (command === "run-profile") {
-    const profile = normalizeProfileForCli(options);
-    const result = await runProfileForCli(profile, options);
+    const profile = profileWithSelectedViewportNamesForCli(normalizeProfileForCli(options), options);
+    const result = positional[1] === "recover" ? await recoverProfileForCli(profile, options) : positional[1] === "aggregate" ? await aggregateProfileResultsForCli(profile, options) : await runProfileForCli(profile, options);
     writeProfileOutput(profileOutputDirOption(options), result);
     const diagnosticLine = profileCliDiagnosticLine(result);
     if (diagnosticLine && optionBoolean(options, "quiet") !== true) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof",
-  "version": "0.7.201",
+  "version": "0.7.203",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",