sneakoscope 7.3.0 → 7.6.0

package/dist/core/image-ux-review/imagegen-adapter.js

@@ -12,9 +12,11 @@ import { discoverCodexAppGeneratedImage } from './codex-app-generated-image-disc
 import { writeImageArtifactPathContract } from '../image/image-artifact-path-contract.js';
 import { registerImageArtifact } from '../image/image-artifact-registry.js';
 const DEFAULT_OPENAI_IMAGE_EDITS_ENDPOINT = 'https://api.openai.com/v1/images/edits';
+export const DEFAULT_IMAGEGEN_FETCH_TIMEOUT_MS = 180000;
+const responseDeadlines = new WeakMap();
 export function buildCalloutPrompt(sourceScreenId, context = {}) {
     return [
-        'Review this UI screenshot as a senior product design lead.',
+        'Review this UI screenshot as a senior Toss UI/UX product designer.',
         `Screenshot source id: ${sourceScreenId}.`,
         'Output must be a new image artifact, not prose.',
         'Text-only response is invalid.',
@@ -322,7 +324,7 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
             const responsesOutputSource = codexLbProviderSelected ? CODEX_LB_PROVIDER_OUTPUT_SOURCE : null;
             const validation = await validateGptImage2Request({
                 provider: 'openai_images_api',
-                endpoint: effectiveEndpoint,
+                endpoint: String(effectiveEndpoint || ''),
                 model: 'gpt-image-2',
                 prompt: input.prompt,
                 source_image_path: sourcePath,
@@ -362,7 +364,7 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
                 });
                 return { ok: false, status: 'blocked', generated_image_path: null, output_id: null, blocker: 'gpt_image_2_request_validation_failed', provider: 'openai_images_api', request_artifact: requestArtifact, response_artifact: responseArtifact, latency_ms: Date.now() - started };
             }
-            if (!auth.apiKey) {
+            if (auth.blocker || !auth.apiKey) {
                 const blocked = {
                     schema: 'sks.image-ux-gpt-image-2-response.v1',
                     created_at: nowIso(),
@@ -373,7 +375,7 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
                     status: 'blocked',
                     blocker: auth.blocker,
                     setup_guidance: auth.auth_source === 'CODEX_LB_API_KEY'
-                        ? 'CODEX_LB_API_KEY is only a non-Codex API fallback when explicitly enabled; it does not satisfy Codex App $imagegen evidence. Attach a real Codex App $imagegen output image for full SKS verification.'
+                        ? 'Repair the selected codex-lb credential binding. Completed output from a selected provider can satisfy full evidence; codex-lb used only as a fallback while another provider is selected cannot.'
                         : 'Set OPENAI_API_KEY only for an explicit non-Codex Images API fallback, or attach a real Codex App $imagegen output image for full SKS verification.',
                     local_only: true
                 };
@@ -463,6 +465,8 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
                         output_id: meta.output_id,
                         output_source: responsesOutputSource,
                         image_output_recovered_from_stream: payload?.image_output_recovered_from_stream === true,
+                        image_output_provenance: payload?.image_output_provenance || 'response.output',
+                        image_output_partial_frame: false,
                         image_artifact_path_contract: imageContract?.artifact_path || null,
                         dimensions: { width: meta.width, height: meta.height, format: meta.format },
                         latency_ms: Date.now() - started,
@@ -605,6 +609,8 @@ function codexLbTargetInputs(source = {}) {
     const inputs = {};
     if (source?.home)
         inputs.home = source.home;
+    if (source?.codexHome)
+        inputs.codexHome = source.codexHome;
     if (source?.env)
         inputs.env = source.env;
     if (typeof source?.configText === 'string')
@@ -625,15 +631,22 @@ export function imagegenCapabilityBlocker(surface = 'Codex App $imagegen') {
         blocker: 'imagegen_capability_missing',
         surface,
         model: 'gpt-image-2',
-        guidance: 'Run the request in Codex App with $imagegen/gpt-image-2 and attach the generated annotated review image path. OPENAI_API_KEY or CODEX_LB_API_KEY may be used only for an explicitly requested non-Codex API fallback, and that fallback does not satisfy Codex App imagegen evidence. SKS must not fabricate or substitute a text-only review.'
+        guidance: 'Run the request with gpt-image-2 through Codex App $imagegen or a selected, ready codex-lb provider and bind the completed generated image path. OPENAI_API_KEY, or codex-lb used while another provider is selected, remains non-Codex fallback evidence. SKS must not fabricate or substitute a text-only review.'
     };
 }
 async function resolveImagesApiAuth(opts = {}) {
+    const codexLb = opts.codexLb?.available === true ? opts.codexLb : null;
+    const target = opts.codexLbTarget || (codexLb
+        ? await resolveCodexLbImagegenTarget(codexLbTargetInputs(opts)).catch(() => null)
+        : null);
+    if (target?.selected === true)
+        return codexLbImagesApiAuth(opts, codexLb, target);
     const openAiKey = String(opts.apiKey || process.env.OPENAI_API_KEY || '').trim();
     if (openAiKey) {
         return {
             apiKey: openAiKey,
             auth_source: 'OPENAI_API_KEY',
+            api_key_source: null,
             responses_model: responsesImagegenModel(opts),
             responses_model_source: responsesImagegenModel(opts) ? 'explicit' : null,
             endpoint: imageEditsEndpoint(opts.baseUrl || 'https://api.openai.com/v1'),
@@ -641,11 +654,11 @@ async function resolveImagesApiAuth(opts = {}) {
             blocker: null
         };
     }
-    const codexLb = opts.codexLb?.available === true ? opts.codexLb : null;
     if (!codexLb) {
         return {
             apiKey: null,
             auth_source: null,
+            api_key_source: null,
             responses_model: responsesImagegenModel(opts),
             responses_model_source: null,
             endpoint: imageEditsEndpoint(opts.baseUrl || 'https://api.openai.com/v1'),
@@ -653,19 +666,26 @@ async function resolveImagesApiAuth(opts = {}) {
             blocker: 'openai_api_key_missing'
         };
     }
-    const envKey = codexLb.env_key || 'CODEX_LB_API_KEY';
-    const target = opts.codexLbTarget || await resolveCodexLbImagegenTarget(codexLbTargetInputs(opts)).catch(() => null);
+    return codexLbImagesApiAuth(opts, codexLb, target);
+}
+function codexLbImagesApiAuth(opts, codexLb, target) {
+    const envKey = codexLb?.env_key || 'CODEX_LB_API_KEY';
     const codexLbKey = String(opts.codexLbApiKey || target?.api_key || '').trim();
-    const baseUrl = target?.base_url || codexLb.base_url || opts.baseUrl || '';
+    const baseUrl = target?.base_url || codexLb?.base_url || opts.baseUrl || '';
+    const blocker = !baseUrl
+        ? 'codex_lb_base_url_missing'
+        : codexLbKey
+            ? null
+            : target?.blocker || 'codex_lb_api_key_missing';
     return {
         apiKey: codexLbKey || null,
         auth_source: envKey,
         api_key_source: target?.api_key_source || null,
         responses_model: responsesImagegenModel(opts) || target?.model || '',
         responses_model_source: responsesImagegenModel(opts) ? 'explicit' : target?.model_source || null,
-        endpoint: imageEditsEndpoint(baseUrl),
-        responses_endpoint: responsesEndpoint(baseUrl),
-        blocker: codexLbKey ? null : target?.blocker || 'codex_lb_api_key_missing'
+        endpoint: baseUrl ? imageEditsEndpoint(baseUrl) : null,
+        responses_endpoint: baseUrl ? responsesEndpoint(baseUrl) : null,
+        blocker
     };
 }
 function imageEditsEndpoint(baseUrl = '') {
@@ -677,23 +697,27 @@ function responsesEndpoint(baseUrl = '') {
     return /\/responses$/i.test(base) ? base : `${base}/responses`;
 }
 function responsesImagegenModel(opts = {}) {
-    return String(opts.responsesModel || process.env.SKS_IMAGEGEN_RESPONSES_MODEL || process.env.OPENAI_MODEL || '').trim();
+    return String(opts.responsesModel || process.env.SKS_IMAGEGEN_RESPONSES_MODEL || '').trim();
 }
 function imagegenFetchTimeoutMs(opts = {}) {
-    const value = Number(opts.fetchTimeoutMs || process.env.SKS_IMAGEGEN_FETCH_TIMEOUT_MS || 90000);
-    return Number.isFinite(value) && value > 0 ? value : 90000;
+    const value = Number(opts.fetchTimeoutMs || process.env.SKS_IMAGEGEN_FETCH_TIMEOUT_MS || DEFAULT_IMAGEGEN_FETCH_TIMEOUT_MS);
+    return Number.isFinite(value) && value > 0 ? value : DEFAULT_IMAGEGEN_FETCH_TIMEOUT_MS;
 }
 async function fetchWithTimeout(url, init, timeoutMs) {
     const controller = new AbortController();
+    const startedAt = Date.now();
     const timeout = setTimeout(() => controller.abort(new Error(`imagegen_fetch_timeout_${timeoutMs}ms`)), timeoutMs);
     try {
-        return await fetch(url, { ...init, signal: controller.signal });
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        responseDeadlines.set(response, { controller, startedAt, timeoutMs, timer: timeout });
+        return response;
     }
-    finally {
+    catch (err) {
         clearTimeout(timeout);
+        throw err;
     }
 }
-async function readResponsePayload(response, timeoutMs = 90000) {
+async function readResponsePayload(response, timeoutMs = DEFAULT_IMAGEGEN_FETCH_TIMEOUT_MS) {
     const text = await textWithTimeout(response, timeoutMs);
     if (!text)
         return {};
@@ -708,23 +732,39 @@ async function readResponsePayload(response, timeoutMs = 90000) {
     }
 }
 async function textWithTimeout(response, timeoutMs) {
+    const deadline = responseDeadlines.get(response);
+    if (deadline)
+        clearTimeout(deadline.timer);
+    const remainingMs = deadline
+        ? Math.max(1, deadline.timeoutMs - (Date.now() - deadline.startedAt))
+        : timeoutMs;
     let timeout = null;
     try {
         return await Promise.race([
             response.text(),
             new Promise((_, reject) => {
-                timeout = setTimeout(() => reject(new Error(`imagegen_response_read_timeout_${timeoutMs}ms`)), timeoutMs);
+                timeout = setTimeout(() => {
+                    const error = new Error(`imagegen_response_read_timeout_${timeoutMs}ms`);
+                    deadline?.controller.abort(error);
+                    void response.body?.cancel(error).catch(() => { });
+                    reject(error);
+                }, remainingMs);
             })
         ]);
     }
     finally {
         if (timeout)
             clearTimeout(timeout);
+        responseDeadlines.delete(response);
     }
 }
 function findResponsesImageGenerationOutput(payload) {
+    if (payload?.image_output_partial_frame === true)
+        return null;
     for (const output of Array.isArray(payload?.output) ? payload.output : []) {
         if (String(output?.type || '') === 'image_generation_call') {
+            if (String(output?.status || '') === 'partial')
+                continue;
             const b64 = typeof output?.result === 'string' ? output.result : output?.result?.b64_json || output?.b64_json || null;
             if (b64)
                 return { b64: String(b64), id: output?.id || payload?.id || null };
@@ -813,10 +853,8 @@ function imagegenRetryOptions(opts = {}) {
     return {
         sleep: opts.retrySleep,
         classifyError: (err) => {
-            const code = String(err?.code
-                || err?.name
-                || err?.message
-                || '');
+            const row = err;
+            const code = [row?.code, row?.name, row?.message].filter(Boolean).join(' ');
             if (/AbortError|timeout|abort/i.test(code))
                 return { code: 'ETIMEDOUT', status: null };
             if (/ECONNRESET|EAI_AGAIN|ETIMEDOUT|ENOTFOUND|ECONNREFUSED|fetch failed/i.test(code))
@@ -834,6 +872,9 @@ function summarizeImagegenPayload(payload) {
         model: payload?.model || null,
         error_type: payload?.error?.type || null,
         error_code: payload?.error?.code || null,
+        image_output_partial_frame: payload?.image_output_partial_frame === true,
+        partial_image_output_present: payload?.partial_image_output_present === true,
+        image_output_provenance: payload?.image_output_provenance || null,
         output_count: outputs.length,
         output: outputs.slice(0, 8).map((output) => ({
             id: output?.id || null,

package/dist/core/image-ux-review/real-callout-extractor.js

@@ -130,6 +130,7 @@ export function buildRealCalloutExtractionPrompt(input) {
     const source = input.sourceScreenshot || {};
     return [
         'Analyze the generated UX review image pixels directly.',
+        'The source screenshot is context only; do not analyze it instead of the generated annotated image.',
         'Return only visible numbered callouts from the generated image.',
         'Do not invent issues, requirements, or invisible callouts.',
         'Return bbox coordinates in the generated image coordinate system as [x,y,width,height].',

package/dist/core/image-ux-review.js

@@ -12,7 +12,7 @@ import { buildIssueLedgerFromGeneratedCallouts } from './image-ux-review/callout
 import { planImageUxFixTasks } from './image-ux-review/fix-task-planner.js';
 import { runImageUxFixLoop } from './image-ux-review/fix-loop.js';
 import { buildRecapturePlan } from './image-ux-review/recapture.js';
-import { addVisualAnchor, ingestImage } from './wiki-image/image-voxel-ledger.js';
+import { addImageRelation, addVisualAnchor, ingestImage } from './wiki-image/image-voxel-ledger.js';
 import { validateFinalHonestModeReport } from './artifact-schemas.js';
 import { imagegenEvidenceClassBlockers, isFullImagegenOutputSource } from './imagegen/imagegen-evidence.js';
 export const IMAGE_UX_REVIEW_GATE_ARTIFACT = 'image-ux-review-gate.json';
@@ -69,6 +69,35 @@ export function imageUxReviewGateAllowsReferenceCloseout(gate = {}) {
         && gate?.verified_level === 'verified_partial'
         && gate?.full_review_passed !== true;
 }
+export function imageUxReviewCommandOutcome(gate = {}, proofOk = false, opts = {}) {
+    const reviewReportCompleted = gate?.review_report_completed === true;
+    const reviewOnlyCompletionAllowed = opts.allowReviewOnlyCompletion === true;
+    const reviewOnlyCompleted = reviewOnlyCompletionAllowed && reviewReportCompleted;
+    const gateAndProofPassed = gate?.passed === true && proofOk === true;
+    const fullReviewPassed = gate?.full_review_passed === true && gateAndProofPassed;
+    return {
+        ok: gateAndProofPassed || reviewOnlyCompleted,
+        status: fullReviewPassed
+            ? 'passed'
+            : reviewOnlyCompleted
+                ? 'review_completed'
+                : gateAndProofPassed
+                    ? gate?.status || 'passed'
+                    : 'blocked',
+        completion_scope: fullReviewPassed
+            ? 'full_review_and_optional_fix_verification'
+            : reviewOnlyCompleted
+                ? 'capture_imagegen_ocr_and_ux_report'
+                : null,
+        review_report_completed: reviewReportCompleted,
+        review_only_completion_allowed: reviewOnlyCompletionAllowed,
+        full_review_passed: gate?.full_review_passed === true,
+        requires_human_review: gate?.requires_human_review === true,
+        unresolved_p0_p1_count: Number(gate?.unresolved_p0_p1_count || 0),
+        safety_blockers: Array.isArray(gate?.blockers) ? gate.blockers : [],
+        proof_ok: proofOk === true
+    };
+}
 function cleanText(value, fallback = '') {
     const text = String(value ?? '').replace(/\s+/g, ' ').trim();
     return text || fallback;
@@ -257,9 +286,21 @@ export async function hydrateImageUxScreenInventory(root, inventory) {
 export function buildImageUxGeneratedReviewLedger(contract = {}, inventory = buildImageUxScreenInventory(contract), existing = null, opts = {}) {
     const existingImages = Array.isArray(existing?.generated_review_images) ? existing.generated_review_images : [];
     const sourceScreens = inventory.source_screens || [];
-    const normalizedImages = existingImages.map((image, index) => normalizeGeneratedReviewImage(image, sourceScreens[index] || {}, opts));
+    const normalizedImages = existingImages.map((image, index) => {
+        const declaredSourceId = image.source_screen_id
+            || (Array.isArray(image.source_screen_ids) ? image.source_screen_ids[0] : null);
+        const sourceScreen = sourceScreens.find((screen) => screen.id === declaredSourceId)
+            || sourceScreens[index]
+            || {};
+        return normalizeGeneratedReviewImage(image, sourceScreen, opts);
+    });
     const realGeneratedCount = normalizedImages.filter((image) => image.real_generated === true && image.mock !== true).length;
-    const missingRealGeneratedScreens = sourceScreens.filter((screen) => !normalizedImages.some((image) => image.source_screen_id === screen.id && image.real_generated === true && image.mock !== true));
+    const coveredSourceScreenIds = sourceScreens
+        .filter((screen) => normalizedImages.some((image) => generatedImageCoversScreen(image, screen.id)
+        && image.real_generated === true
+        && image.mock !== true))
+        .map((screen) => screen.id);
+    const missingRealGeneratedScreens = sourceScreens.filter((screen) => !coveredSourceScreenIds.includes(screen.id));
     const nonRealGeneratedCount = normalizedImages.filter((image) => image.real_generated !== true || image.mock === true).length;
     const textOnlyCount = normalizedImages.filter((image) => image.text_only === true).length;
     const evidenceBlockers = Array.from(new Set(normalizedImages.flatMap((image) => image.evidence_blockers || []).map((blocker) => String(blocker))));
@@ -295,7 +336,7 @@ export function buildImageUxGeneratedReviewLedger(contract = {}, inventory = bui
             source_screen_id: screen.id,
             source_sha256: screen.sha256 || null,
             prompt: buildCalloutPrompt(screen.id, { target: inventory.target }),
-            status: normalizedImages.some((image) => image.source_screen_id === screen.id) ? 'generated_or_attached' : 'pending_imagegen',
+            status: normalizedImages.some((image) => generatedImageCoversScreen(image, screen.id)) ? 'generated_or_attached' : 'pending_imagegen',
             required_output: 'annotated_review_image_with_numbered_callouts_severity_labels_markers_arrows_and_mini_comp',
             requested_fidelity: 'high_fidelity_automatic',
             image_input_fidelity_note: 'gpt-image-2 processes image inputs at high fidelity automatically; SKS omits unsupported input_fidelity.',
@@ -303,6 +344,8 @@ export function buildImageUxGeneratedReviewLedger(contract = {}, inventory = bui
         })),
         generated_count: normalizedImages.length,
         real_generated_count: realGeneratedCount,
+        covered_source_screen_count: coveredSourceScreenIds.length,
+        covered_source_screen_ids: coveredSourceScreenIds,
         non_real_generated_count: nonRealGeneratedCount,
         required_count: sourceScreens.length,
         text_only_count: textOnlyCount,
@@ -313,7 +356,9 @@ export function buildImageUxGeneratedReviewLedger(contract = {}, inventory = bui
             && textOnlyCount === 0
             && missingRealGeneratedScreens.length > 0,
         blockers: uniqueBlockers,
-        passed: sourceScreens.length > 0 && blockers.length === 0 && realGeneratedCount === sourceScreens.length,
+        passed: sourceScreens.length > 0
+            && blockers.length === 0
+            && coveredSourceScreenIds.length === sourceScreens.length,
         imagegen_blocker: uniqueBlockers.includes('imagegen_capability_missing')
             ? imagegenCapabilityBlocker()
             : uniqueBlockers.includes('generated_review_image_missing')
@@ -340,6 +385,17 @@ export function buildImageUxIssueLedger(contract = {}, generatedReviewLedger = b
     };
 }
 export function buildImageUxIterationReport(contract = {}, policy = buildImageUxReviewPolicy(contract), generatedReviewLedger = buildImageUxGeneratedReviewLedger(contract), issueLedger = buildImageUxIssueLedger(contract, generatedReviewLedger), fixTaskPlan = planImageUxFixTasks(issueLedger), fixLoop = runImageUxFixLoop(issueLedger, fixTaskPlan), recapturePlan = buildRecapturePlan(fixLoop)) {
+    const generatedImage = (generatedReviewLedger.generated_review_images || [])[0] || null;
+    const issues = Array.isArray(issueLedger.issues) ? issueLedger.issues : [];
+    const basedOnGeneratedImage = issueLedger.extracted_from_generated_callout === true
+        && issues.length > 0
+        && issues.every((issue) => issue.extracted_from_generated_image === true
+            && issue.generated_image_sha256 === generatedImage?.sha256);
+    const requiresHumanReview = (fixTaskPlan.tasks || []).some((task) => task.requires_human_review === true);
+    const severityCounts = Object.fromEntries(['P0', 'P1', 'P2', 'P3'].map((severity) => [
+        severity,
+        issues.filter((issue) => issue.severity === severity).length
+    ]));
     const passed = generatedReviewLedger.passed === true
         && issueLedger.passed === true
         && fixLoop.passed === true
@@ -351,6 +407,43 @@ export function buildImageUxIterationReport(contract = {}, policy = buildImageUx
         schema_version: 2,
         created_at: nowIso(),
         contract_hash: contract.sealed_hash || null,
+        report_type: 'ux_ui_change_report',
+        review_report_completed: generatedReviewLedger.passed === true
+            && issueLedger.validation?.ok === true
+            && basedOnGeneratedImage,
+        full_review_passed: passed,
+        requires_human_review: requiresHumanReview,
+        unresolved_p0_p1_count: Number(issueLedger.blocking_issue_count || 0),
+        analysis_basis: {
+            primary_evidence: 'generated_annotated_review_image',
+            generated_image_path: generatedImage?.path || null,
+            generated_image_sha256: generatedImage?.sha256 || null,
+            generated_image_id: generatedImage?.id || null,
+            source_screen_id: generatedImage?.source_screen_id || 'screen-1',
+            issue_extraction_source: issueLedger.extraction_source || IMAGE_UX_REVIEW_GENERATED_REVIEW_LEDGER_ARTIFACT,
+            based_on_generated_image: basedOnGeneratedImage
+        },
+        executive_summary: {
+            issue_count: issues.length,
+            severity_counts: severityCounts,
+            highest_priority: issues.find((issue) => ['P0', 'P1'].includes(issue.severity))?.severity
+                || issues[0]?.severity
+                || null
+        },
+        recommendations: issues.map((issue) => ({
+            issue_id: issue.id,
+            callout_id: issue.callout_id,
+            severity: issue.severity,
+            title: issue.title,
+            observed_problem: issue.detail,
+            likely_cause: issue.likely_cause,
+            recommended_ux_ui_change: issue.fix_action,
+            target_surface: issue.target_surface,
+            generated_image_bbox: issue.bbox,
+            generated_image_sha256: issue.generated_image_sha256,
+            confidence: issue.confidence,
+            verification_status: issue.fix_verification_status
+        })),
         loop_policy: {
             max_full_surface_passes: policy.max_full_surface_passes,
             max_screen_retries: policy.max_screen_retries,
@@ -416,6 +509,15 @@ export function defaultImageUxReviewGate(contract = {}, parts = {}) {
     const wrongnessChecked = parts.wrongnessChecked === true || generatedReviewLedger.blockers?.length === 0;
     const honestModeEvidence = parts.honestModeEvidence || null;
     const honestModeComplete = parts.honestModeComplete === true && (honestModeEvidence?.ok === true || parts.honestModeEvidenceRequired !== true);
+    const requiresHumanReview = (fixTaskPlan.tasks || []).some((task) => task.requires_human_review === true);
+    const reviewReportCompleted = realSourceScreenshotPresent
+        && officialOrUserScreenshotSource
+        && generatedReviewLedger.passed === true
+        && realGeneratedCount > 0
+        && calloutExtractionSchemaValid
+        && issueLedger.extracted_from_generated_callout === true
+        && iterationReport.review_report_completed === true
+        && iterationReport.analysis_basis?.based_on_generated_image === true;
     const referenceCloseoutPassed = generatedImageUnavailable
         && realSourceScreenshotPresent
         && officialOrUserScreenshotSource
@@ -436,6 +538,10 @@ export function defaultImageUxReviewGate(contract = {}, parts = {}) {
         status: 'blocked',
         verified_level: 'blocked',
         full_review_passed: false,
+        review_report_completed: reviewReportCompleted,
+        completion_scope: reviewReportCompleted ? 'capture_imagegen_ocr_and_ux_report' : null,
+        requires_human_review: requiresHumanReview,
+        unresolved_p0_p1_count: Number(issueLedger.blocking_issue_count || 0),
         reference_only: false,
         real_source_screenshot_present: realSourceScreenshotPresent,
         computer_use_or_user_screenshot_source: officialOrUserScreenshotSource,
@@ -448,7 +554,8 @@ export function defaultImageUxReviewGate(contract = {}, parts = {}) {
         fix_loop_executed_or_not_needed: fixLoopExecutedOrNotNeeded,
         changed_screens_rechecked: changedScreensRechecked,
         image_voxel_reference_anchor_created: imageVoxelReferenceAnchorCreated,
-        image_voxel_relations_created: parts.imageVoxelRelationsCreated === true || realGeneratedImages.some((image) => image.image_voxel_relation === 'generated_callout_review_of') === true,
+        image_voxel_relations_created: parts.imageVoxelRelationsCreated === true,
+        image_voxel_relation_evidence: parts.imageVoxelRelationEvidence || null,
         wrongness_checked: wrongnessChecked,
         honest_mode_complete: honestModeComplete,
         required_artifacts: [
@@ -497,8 +604,18 @@ export function defaultImageUxReviewGate(contract = {}, parts = {}) {
     return {
         ...gate,
         passed: fullPassed || referenceCloseoutPassed,
-        status: fullPassed ? 'passed' : referenceCloseoutPassed ? 'verified_partial_reference' : 'blocked',
-        verified_level: fullPassed ? 'verified' : referenceCloseoutPassed ? 'verified_partial' : 'blocked',
+        status: fullPassed
+            ? 'passed'
+            : referenceCloseoutPassed
+                ? 'verified_partial_reference'
+                : reviewReportCompleted
+                    ? 'review_completed'
+                    : 'blocked',
+        verified_level: fullPassed
+            ? 'verified'
+            : referenceCloseoutPassed || reviewReportCompleted
+                ? 'verified_partial'
+                : 'blocked',
         full_review_passed: fullPassed,
         reference_only: referenceCloseoutPassed
     };
@@ -513,12 +630,14 @@ export async function writeImageUxReviewRouteArtifacts(dir, contract = {}, opts
     const extractionReport = await readExistingJson(dir, IMAGE_UX_REVIEW_CALLOUT_EXTRACTION_REPORT_ARTIFACT);
     const existingImagegenRequest = await readExistingJson(dir, IMAGE_UX_REVIEW_GPT_IMAGE_2_REQUEST_ARTIFACT);
     const existingImagegenResponse = await readExistingJson(dir, IMAGE_UX_REVIEW_GPT_IMAGE_2_RESPONSE_ARTIFACT);
+    const existingRecapture = await readExistingJson(dir, IMAGE_UX_REVIEW_RECAPTURE_ARTIFACT);
     const generatedReviewLedger = buildImageUxGeneratedReviewLedger(contract, inventory, existingGenerated, { root });
     const sourceReferenceEvidence = await ensureImageUxSourceReferenceEvidence(root, dir, inventory);
+    const imageVoxelRelationEvidence = await ensureImageUxGeneratedRelationEvidence(root, dir, inventory, generatedReviewLedger, sourceReferenceEvidence);
     const issueLedger = buildImageUxIssueLedger(contract, generatedReviewLedger, existingIssues);
     const fixTaskPlan = planImageUxFixTasks(issueLedger);
     const fixLoop = runImageUxFixLoop(issueLedger, fixTaskPlan, opts.fixLoop || {});
-    const recapturePlan = buildRecapturePlan(fixLoop, opts.recapture || {});
+    const recapturePlan = selectImageUxRecapturePlan(fixLoop, opts, existingRecapture);
     const iterationReport = buildImageUxIterationReport(contract, policy, generatedReviewLedger, issueLedger, fixTaskPlan, fixLoop, recapturePlan);
     const outputSchema = await detectCodexExecResumeOutputSchema().catch((err) => ({ ok: true, status: 'integration_optional', warnings: [err.message] }));
     const honestModeEvidence = await ensureImageUxHonestModeEvidence(dir, {
@@ -540,7 +659,8 @@ export async function writeImageUxReviewRouteArtifacts(dir, contract = {}, opts
         recapturePlan,
         iterationReport,
         imageVoxelReferenceAnchorCreated: sourceReferenceEvidence.ok === true,
-        imageVoxelRelationsCreated: opts.imageVoxelRelationsCreated === true,
+        imageVoxelRelationsCreated: opts.imageVoxelRelationsCreated === true || imageVoxelRelationEvidence.ok === true,
+        imageVoxelRelationEvidence,
         wrongnessChecked: opts.wrongnessChecked === true,
         honestModeComplete: honestModeEvidence.ok === true,
         honestModeEvidenceRequired: true,
@@ -567,6 +687,7 @@ export async function writeImageUxReviewRouteArtifacts(dir, contract = {}, opts
         policy,
         inventory,
         imagegen_request: imagegenRequest,
+        gpt_image_2_request: imagegenRequest,
         imagegen_response: imagegenResponse,
         generated_review_ledger: generatedReviewLedger,
         issue_ledger: issueLedger,
@@ -580,6 +701,12 @@ export async function writeImageUxReviewRouteArtifacts(dir, contract = {}, opts
         gate
     };
 }
+export function selectImageUxRecapturePlan(fixLoop = {}, opts = {}, existing = null) {
+    if (opts.preserveExistingRecapture === true && existing?.schema === 'sks.image-ux-recapture-plan.v2') {
+        return existing;
+    }
+    return buildRecapturePlan(fixLoop, opts.recapture || {});
+}
 export function imageUxReviewProofEvidence(gate = {}, artifacts = {}) {
     const issueLedger = artifacts.issue_ledger || {};
     const generated = artifacts.generated_review_ledger || {};
@@ -599,7 +726,11 @@ export function imageUxReviewProofEvidence(gate = {}, artifacts = {}) {
         open_p0_p1_count: issueLedger.blocking_issue_count || 0,
         fixed_p0_p1_count: (issueLedger.issues || []).filter((issue) => ['P0', 'P1'].includes(issue.severity) && issue.status === 'fixed').length,
         recapture_re_review_status: artifacts.recapture_plan?.changed_screens_rechecked_or_not_applicable ? 'complete_or_not_applicable' : 'blocked',
-        image_voxel_relation_count: referenceOnly ? 0 : realGeneratedImages.filter((image) => image.image_voxel_relation).length,
+        image_voxel_relation_count: referenceOnly
+            ? 0
+            : gate.image_voxel_relations_created === true
+                ? Number(gate.image_voxel_relation_evidence?.relations || generated.covered_source_screen_count || realGeneratedImages.length)
+                : 0,
         computer_use_evidence_mode: artifacts.inventory?.source_screens?.some((screen) => screen.capture_source === 'codex_native_computer_use_screenshot' || screen.capture_source === 'codex_computer_use_screenshot') ? 'native_computer_use_source_screenshot' : artifacts.inventory?.source_screens?.some((screen) => screen.capture_source === 'codex_chrome_extension_screenshot') ? 'chrome_extension_source_screenshot' : 'user_or_static_screenshot',
         claims: {
             ux_review_source_screenshot_verified: artifacts.inventory?.passed === true,
@@ -609,7 +740,7 @@ export function imageUxReviewProofEvidence(gate = {}, artifacts = {}) {
             ux_review_changed_screens_rechecked: artifacts.recapture_plan?.changed_screens_rechecked_or_not_applicable === true,
             ux_review_image_voxel_relations_verified: referenceOnly
                 ? gate.source_reference_evidence?.ok === true
-                : realGeneratedImages.some((image) => image.image_voxel_relation)
+                : gate.image_voxel_relations_created === true
         },
         full_verification_blockers: gate.full_verification_blockers || gate.blockers || [],
         blockers: gate.blockers || []
@@ -668,6 +799,77 @@ async function ensureImageUxSourceReferenceEvidence(root, dir, inventory = {}) {
         issues
     };
 }
+async function ensureImageUxGeneratedRelationEvidence(root, dir, inventory = {}, generatedReviewLedger = {}, sourceReferenceEvidence = {}) {
+    const missionId = path.basename(String(dir));
+    const sourceScreens = (inventory.source_screens || []).filter((screen) => screen.status === 'captured' && screen.source);
+    const generatedImages = (generatedReviewLedger.generated_review_images || [])
+        .filter((image) => image.real_generated === true && image.mock !== true && image.path);
+    if (!missionId || !sourceScreens.length || !generatedImages.length || sourceReferenceEvidence.ok !== true) {
+        return {
+            schema: 'sks.image-ux-generated-relation-evidence.v1',
+            ok: false,
+            reason: !missionId
+                ? 'mission_id_missing'
+                : !sourceScreens.length
+                    ? 'captured_source_screenshot_missing'
+                    : !generatedImages.length
+                        ? 'real_generated_image_missing'
+                        : 'source_reference_anchor_missing',
+            relations: 0,
+            issues: []
+        };
+    }
+    const anchorIds = Array.isArray(sourceReferenceEvidence.anchor_ids) ? sourceReferenceEvidence.anchor_ids : [];
+    const relationIds = [];
+    const issues = [];
+    let expectedRelations = 0;
+    for (const image of generatedImages) {
+        const generatedImageId = `${missionId}-${image.id}`;
+        try {
+            const ingested = await ingestImage(root, image.path, {
+                missionId,
+                source: 'image-ux-review:gpt-image-2-generated-callout',
+                id: generatedImageId
+            });
+            if (!ingested.ok) {
+                issues.push(...(ingested.validation?.issues || [`generated_image_ingest_failed:${image.id}`]));
+                continue;
+            }
+            const coveredScreens = sourceScreens.filter((screen) => generatedImageCoversScreen(image, screen.id));
+            expectedRelations += coveredScreens.length;
+            for (const sourceScreen of coveredScreens) {
+                const sourceImageId = `${missionId}-${sourceScreen.id}-source`;
+                const relation = await addImageRelation(root, {
+                    missionId,
+                    route: '$Image-UX-Review',
+                    type: 'generated_callout_review_of',
+                    beforeImageId: sourceImageId,
+                    afterImageId: generatedImageId,
+                    sourceImageId,
+                    generatedImageId,
+                    anchors: anchorIds.filter((anchorId) => String(anchorId).startsWith(`${sourceImageId}-`)),
+                    status: 'verified_partial',
+                    verification: 'gpt-image-2-generated-callout-bound-to-source'
+                });
+                if (relation.ok)
+                    relationIds.push(`${sourceImageId}->${generatedImageId}`);
+                else
+                    issues.push(...(relation.validation?.issues || [`generated_image_relation_failed:${image.id}:${sourceScreen.id}`]));
+            }
+        }
+        catch (err) {
+            issues.push(err instanceof Error ? err.message : String(err));
+        }
+    }
+    return {
+        schema: 'sks.image-ux-generated-relation-evidence.v1',
+        ok: expectedRelations > 0 && relationIds.length === expectedRelations && issues.length === 0,
+        relations: relationIds.length,
+        relation_ids: relationIds,
+        anchor_ids: anchorIds,
+        issues
+    };
+}
 async function ensureImageUxHonestModeEvidence(dir, parts = {}, opts = {}) {
     const missionId = path.basename(String(dir));
     const existing = await readExistingJson(dir, IMAGE_UX_REVIEW_HONEST_MODE_ARTIFACT);
@@ -744,6 +946,10 @@ export async function buildImageUxCalloutExtractionReport(root, extraction = {},
         schema: 'sks.image-ux-callout-extraction-report.v1',
         created_at: nowIso(),
         provider: extraction.provider || opts.provider || 'unknown',
+        analysis_input: 'generated_annotated_review_image',
+        generated_image_is_primary_evidence: true,
+        source_screenshot_used_for_extraction: false,
+        generated_image_id: opts.generatedImageId || ledger.generated_image_id || issues[0]?.generated_review_image_id || null,
         generated_image_path: generatedPath,
         generated_image_sha256: generatedSha,
         source_screenshot_sha256: sourceSha,
@@ -819,6 +1025,10 @@ function generatedReviewImageMissingBlocker() {
 }
 function normalizeGeneratedReviewImage(image = {}, screen = {}, opts = {}) {
     const sourceScreenId = image.source_screen_id || screen.id || 'screen-1';
+    const sourceScreenIds = [...new Set([
+            ...(Array.isArray(image.source_screen_ids) ? image.source_screen_ids : []),
+            sourceScreenId
+        ].map((id) => String(id || '').trim()).filter(Boolean))];
     const fileEvidence = generatedImageFileEvidence(opts.root, image);
     const sha256 = fileEvidence.sha256 || image.sha256 || null;
     const width = Number(image.width || 0) > 0 ? Number(image.width) : null;
@@ -832,6 +1042,7 @@ function normalizeGeneratedReviewImage(image = {}, screen = {}, opts = {}) {
         ...image,
         id: image.id || compactId('generated-review', `${sourceScreenId}:${image.path || nowIso()}`),
         source_screen_id: sourceScreenId,
+        source_screen_ids: sourceScreenIds,
         path: image.path || null,
         sha256,
         width,
@@ -863,6 +1074,13 @@ function normalizeGeneratedReviewImage(image = {}, screen = {}, opts = {}) {
         image_voxel_relation: image.image_voxel_relation || (image.id && sourceScreenId ? 'generated_callout_review_of' : null)
     };
 }
+function generatedImageCoversScreen(image = {}, screenId) {
+    const id = String(screenId || '');
+    if (!id)
+        return false;
+    return image.source_screen_id === id
+        || (Array.isArray(image.source_screen_ids) && image.source_screen_ids.includes(id));
+}
 function generatedImageEvidenceBlockers(image = {}, evidence = {}) {
     if (image.real_generated !== true || image.mock === true || image.source === 'mock_fixture')
         return [];