sneakoscope 4.8.7 → 5.3.0

package/dist/core/feature-registry.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { COMMANDS } from '../cli/command-registry.js';
 import { COMMAND_CATALOG, DOLLAR_COMMAND_ALIASES, DOLLAR_COMMANDS, ROUTES } from './routes.js';
 import { FEATURE_QUALITY_LEVELS, fixtureForFeature, fixtureSummary, validateFeatureFixtures } from './feature-fixtures.js';
 import { runFeatureFixture, writeFeatureFixtureReports } from './feature-fixture-runner.js';
@@ -51,6 +52,8 @@ export async function buildFeatureRegistry({ root = packageRoot(), generatedAt =
     }
     features.push(nativeAgentIntakeFeature());
     features.push(agentProofEvidenceFeature());
+    features.push(doctorImagegenRepairFeature());
+    features.push(...imagegenWiringFeatures());
     for (const skillName of skillNames) {
         if (!skillCoveredByRoute(skillName))
             features.push(skillFeature(skillName));
@@ -102,7 +105,8 @@ export function validateFeatureRegistry(registry = {}) {
     const blockers = [
         ...Object.entries(unmapped).flatMap(([kind, values]) => values.map((value) => `${kind}:${value}`)),
         ...duplicateFeatureIds.map((id) => `duplicate_feature_id:${id}`),
-        ...routeMentionsWithoutRoute.map((mention) => `doc_route_mention_without_route:${mention}`)
+        ...routeMentionsWithoutRoute.map((mention) => `doc_route_mention_without_route:${mention}`),
+        ...routeGateConsistencyBlockers()
     ];
     return {
         ok: blockers.length === 0,
@@ -118,6 +122,7 @@ export function validateFeatureRegistry(registry = {}) {
         unmapped,
         duplicate_feature_ids: duplicateFeatureIds,
         doc_route_mentions_without_route: routeMentionsWithoutRoute,
+        route_gate_consistency_blockers: routeGateConsistencyBlockers(),
         blockers,
         nonblocking_known_gaps: [
             'feature fixtures remain progressive',
@@ -127,6 +132,41 @@ export function validateFeatureRegistry(registry = {}) {
         feature_quality_summary: featureQualitySummary(features)
     };
 }
+export function routeGateConsistencyBlockers() {
+    const blockers = [];
+    for (const route of ROUTES) {
+        const cliName = routeCliCommandName(route);
+        if (!cliName)
+            continue;
+        const entry = COMMANDS[cliName];
+        if (!entry?.ownsGates)
+            continue;
+        const routeGates = stopGateFiles(route.stopGate);
+        const owned = new Set((entry.ownedGateFiles || []).map((file) => String(file)));
+        if (!routeGates.length && owned.size > 0)
+            blockers.push(`route_gate_mismatch:${route.id}:routes_none_registry_${[...owned].join('|')}`);
+        for (const gate of routeGates) {
+            if (!owned.has(gate))
+                blockers.push(`route_gate_mismatch:${route.id}:${gate}_not_owned_by_${cliName}`);
+        }
+    }
+    return blockers;
+}
+function routeCliCommandName(route) {
+    const command = String(route.command || '').replace(/^\$/, '').toLowerCase();
+    if (Object.hasOwn(COMMANDS, command))
+        return command;
+    const alias = (route.dollarAliases || [])
+        .map((value) => String(value || '').replace(/^\$/, '').toLowerCase())
+        .find((value) => Object.hasOwn(COMMANDS, value));
+    return alias || null;
+}
+function stopGateFiles(stopGate) {
+    const text = String(stopGate || '');
+    if (!text || text === 'none' || text === 'honest_mode' || text === 'plan-only')
+        return [];
+    return text.split('|').map((part) => part.trim()).filter((part) => part.endsWith('.json'));
+}
 export async function writeFeatureInventoryDocs({ root = packageRoot(), outFile = path.join(root, 'docs', 'feature-inventory.md') } = {}) {
     const registry = await buildFeatureRegistry({ root });
     const markdown = renderFeatureInventoryMarkdown(registry);
@@ -674,6 +714,66 @@ function agentProofEvidenceFeature() {
         }
     });
 }
+function doctorImagegenRepairFeature() {
+    return baseFeature({
+        id: 'doctor:imagegen-repair',
+        commands: ['sks doctor --json', 'sks doctor --fix --json'],
+        aliases: ['repair.imagegen', 'imagegen_repair'],
+        category: 'safety',
+        maturity: 'beta',
+        intent: 'Doctor repair path that detects Codex App imagegen, attempts repair when requested, and reports imagegen_repair evidence without claiming success unless re-detection passes.',
+        voxel_triwiki_integration: 'policy voxel required for visual/image routes that depend on Codex App imagegen',
+        completion_proof_integration: 'doctor report imagegen_repair is consumed by imagegen route blockers before visual route proof',
+        known_gaps: ['live Codex App feature enablement remains environment-dependent and reports manual actions when unavailable'],
+        source_refs: {
+            cli_command_names: ['doctor'],
+            handler_keys: ['doctor'],
+            dollar_commands: [],
+            app_skill_aliases: [],
+            skills: ['imagegen']
+        }
+    });
+}
+function imagegenWiringFeatures() {
+    return [
+        baseFeature({
+            id: 'ux-review:run-wires-imagegen',
+            commands: ['npm run ux-review:run-wires-imagegen', 'sks ux-review run --image <screenshot> --generate-callouts --json'],
+            aliases: ['$Image-UX-Review', '$UX-Review'],
+            category: 'visual-memory',
+            maturity: 'beta',
+            intent: 'Image UX route start gate, shared gpt-image-2 adapter, callout extraction, and Codex App evidence validation wiring.',
+            voxel_triwiki_integration: 'image/source/bbox voxel required',
+            completion_proof_integration: 'image-ux-review-gate and Completion Proof must separate real Codex image evidence from mock/API fallback evidence',
+            known_gaps: ['live Codex App image generation remains environment-dependent'],
+            source_refs: {
+                cli_command_names: ['image-ux-review'],
+                handler_keys: ['image-ux-review', 'ux-review'],
+                dollar_commands: ['$Image-UX-Review', '$UX-Review'],
+                app_skill_aliases: ['$image-ux-review', '$ux-review'],
+                skills: ['image-ux-review', 'ux-review', 'imagegen']
+            }
+        }),
+        baseFeature({
+            id: 'ppt:real-imagegen-wiring',
+            commands: ['npm run ppt:real-imagegen-wiring', 'sks ppt review --deck <pptx> --json'],
+            aliases: ['$PPT'],
+            category: 'visual-memory',
+            maturity: 'beta',
+            intent: 'PPT slide callout review path reuses the shared gpt-image-2 adapter and records imagegen_evidence in PPT gates.',
+            voxel_triwiki_integration: 'image/source/bbox voxel required',
+            completion_proof_integration: 'ppt-imagegen-review-gate and ppt-gate must include Codex App imagegen evidence classes and hashes',
+            known_gaps: ['live deck export and live Codex App image generation remain environment-dependent'],
+            source_refs: {
+                cli_command_names: ['ppt'],
+                handler_keys: ['ppt'],
+                dollar_commands: ['$PPT'],
+                app_skill_aliases: ['$ppt'],
+                skills: ['ppt', 'imagegen']
+            }
+        })
+    ];
+}
 function skillFeature(skillName) {
     return baseFeature({
         id: `skill-${slug(skillName)}`,
@@ -876,7 +976,7 @@ function routeKnownGaps(command) {
     if (command === '$MAD-SKS')
         return ['permission closed by owning gate'];
     if (command === '$MAD-DB')
-        return ['active cycle must execute requested SQL-plane work, read back postconditions, and close the mission-local write profile'];
+        return ['deprecated alias; SQL-plane execution is merged into $MAD-SKS and must still read back postconditions and close the mission-local write profile'];
     return [];
 }
 function checkRow(id, ok, blockers = []) {

package/dist/core/fsx.js

@@ -5,12 +5,42 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-export const PACKAGE_VERSION = '4.8.7';
+export const PACKAGE_VERSION = '5.3.0';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 export function nowIso() {
     return new Date().toISOString();
 }
+export function lastLine(chunk) {
+    const lines = String(chunk || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    return lines[lines.length - 1] || '';
+}
+export function throttleLines(fn, ms = 500) {
+    let lastAt = 0;
+    let pending = null;
+    let timer = null;
+    const flush = () => {
+        timer = null;
+        if (!pending)
+            return;
+        lastAt = Date.now();
+        const line = pending;
+        pending = null;
+        fn(line);
+    };
+    return (chunk) => {
+        const line = lastLine(chunk);
+        if (!line)
+            return;
+        pending = line;
+        const now = Date.now();
+        const wait = Math.max(0, ms - (now - lastAt));
+        if (wait === 0)
+            flush();
+        else if (!timer)
+            timer = setTimeout(flush, wait);
+    };
+}
 export function sha256(input) {
     return crypto.createHash('sha256').update(input).digest('hex');
 }
@@ -109,18 +139,21 @@ export async function writeReceiptRotated(p, data, opts = {}) {
     const rotated = prior
         .filter((entry) => entry.isFile() && entry.name.startsWith(`${base}.`) && entry.name.endsWith('.json'))
         .map((entry) => path.join(path.dirname(p), entry.name));
+    const rotatedFiles = new Set(rotated);
     const existing = await fsp.stat(p).catch(() => null);
     if (existing) {
         const stamp = new Date(existing.mtimeMs).toISOString().replace(/[:.]/g, '-');
-        await fsp.rename(p, path.join(path.dirname(p), `${base}.${stamp}.json`)).catch(() => undefined);
+        const rotatedPath = path.join(path.dirname(p), `${base}.${stamp}.json`);
+        await fsp.rename(p, rotatedPath).catch(() => undefined);
+        rotatedFiles.add(rotatedPath);
     }
     await writeJsonAtomic(p, data);
-    const rows = await Promise.all(rotated.map(async (file) => ({ file, stat: await fsp.stat(file).catch(() => null) })));
-    rows
+    const rows = await Promise.all([...rotatedFiles].map(async (file) => ({ file, stat: await fsp.stat(file).catch(() => null) })));
+    const removable = rows
         .filter((row) => Boolean(row.stat))
         .sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs)
-        .slice(keep)
-        .forEach((row) => void fsp.rm(row.file, { force: true }).catch(() => undefined));
+        .slice(keep);
+    await Promise.all(removable.map((row) => fsp.rm(row.file, { force: true }).catch(() => undefined)));
 }
 export async function writeBinaryAtomic(p, data) {
     await ensureDir(path.dirname(p));

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

@@ -107,6 +107,7 @@ export function createCodexAppImagegenAdapter(opts = {}) {
                     schema: 'sks.image-ux-gpt-image-2-response.v1',
                     created_at: nowIso(),
                     provider: 'codex_app_imagegen',
+                    evidence_class: 'codex_app_imagegen',
                     model: 'gpt-image-2',
                     ok: false,
                     status: 'blocked',
@@ -131,11 +132,13 @@ export function createCodexAppImagegenAdapter(opts = {}) {
                     schema: 'sks.image-ux-gpt-image-2-response.v1',
                     created_at: nowIso(),
                     provider: 'codex_app_imagegen',
+                    evidence_class: 'codex_app_imagegen',
                     model: 'gpt-image-2',
                     ok: true,
                     status: 'generated',
                     output_image_path: dest,
                     output_image_sha256: meta.sha256,
+                    output_sha256: meta.sha256,
                     output_id: meta.output_id,
                     output_source: outputSource,
                     image_artifact_path_contract: imageContract?.artifact_path || null,
@@ -161,6 +164,7 @@ export function createCodexAppImagegenAdapter(opts = {}) {
                 schema: 'sks.image-ux-gpt-image-2-response.v1',
                 created_at: nowIso(),
                 provider: 'codex_app_imagegen',
+                evidence_class: 'codex_app_imagegen',
                 model: 'gpt-image-2',
                 ok: false,
                 status: 'blocked',
@@ -196,6 +200,22 @@ export function createFakeImagegenAdapter(opts = {}) {
             await ensureDir(input.output_dir);
             const requestArtifact = path.join(input.output_dir, 'image-ux-gpt-image-2-request.json');
             const responseArtifact = path.join(input.output_dir, 'image-ux-gpt-image-2-response.json');
+            if (!imagegenMockContext(opts)) {
+                await writeJsonAtomic(responseArtifact, {
+                    schema: 'sks.image-ux-gpt-image-2-response.v1',
+                    created_at: nowIso(),
+                    provider: 'fake_imagegen_adapter',
+                    fake_adapter: true,
+                    execution_class: 'mock_fixture',
+                    evidence_class: 'mock_fixture',
+                    model: 'gpt-image-2',
+                    ok: false,
+                    status: 'blocked',
+                    blocker: 'fake_imagegen_requires_test_or_mock_context',
+                    local_only: true
+                });
+                return { ok: false, status: 'blocked', generated_image_path: null, output_id: null, blocker: 'fake_imagegen_requires_test_or_mock_context', provider: 'fake_imagegen_adapter', request_artifact: null, response_artifact: responseArtifact, latency_ms: Date.now() - started };
+            }
             const validation = await validateGptImage2Request({
                 provider: 'fake_imagegen_adapter',
                 endpoint: 'local hermetic fixture',
@@ -227,6 +247,9 @@ export function createFakeImagegenAdapter(opts = {}) {
                     schema: 'sks.image-ux-gpt-image-2-response.v1',
                     created_at: nowIso(),
                     provider: 'fake_imagegen_adapter',
+                    fake_adapter: true,
+                    execution_class: 'mock_fixture',
+                    evidence_class: 'mock_fixture',
                     model: 'gpt-image-2',
                     ok: false,
                     status: 'blocked',
@@ -251,16 +274,20 @@ export function createFakeImagegenAdapter(opts = {}) {
                 schema: 'sks.image-ux-gpt-image-2-response.v1',
                 created_at: nowIso(),
                 provider: 'fake_imagegen_adapter',
+                fake_adapter: true,
+                execution_class: 'mock_fixture',
+                evidence_class: 'mock_fixture',
                 model: 'gpt-image-2',
                 ok: true,
                 status: 'generated',
                 output_image_path: out,
                 output_image_sha256: meta.sha256,
+                output_sha256: meta.sha256,
                 output_id: meta.output_id,
+                output_source: 'mock_fixture',
                 image_artifact_path_contract: imageContract?.artifact_path || null,
                 dimensions: { width: meta.width, height: meta.height, format: meta.format },
                 latency_ms: Date.now() - started,
-                fake_adapter: true,
                 source: 'mock_like_fixture',
                 real_generated: false,
                 mock: true,
@@ -320,6 +347,7 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
                     schema: 'sks.image-ux-gpt-image-2-response.v1',
                     created_at: nowIso(),
                     provider: 'openai_images_api',
+                    evidence_class: 'non_codex_api_fallback',
                     model: 'gpt-image-2',
                     ok: false,
                     status: 'blocked',
@@ -334,6 +362,7 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
                     schema: 'sks.image-ux-gpt-image-2-response.v1',
                     created_at: nowIso(),
                     provider: 'openai_images_api',
+                    evidence_class: 'non_codex_api_fallback',
                     model: 'gpt-image-2',
                     ok: false,
                     status: 'blocked',
@@ -397,6 +426,7 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
                         schema: 'sks.image-ux-gpt-image-2-response.v1',
                         created_at: nowIso(),
                         provider: 'openai_responses_image_generation',
+                        evidence_class: 'non_codex_api_fallback',
                         model: 'gpt-image-2',
                         responses_model: responsesImagegenModel(opts),
                         auth_source: auth.auth_source,
@@ -404,6 +434,7 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
                         status: 'generated',
                         output_image_path: out,
                         output_image_sha256: meta.sha256,
+                        output_sha256: meta.sha256,
                         output_id: meta.output_id,
                         image_artifact_path_contract: imageContract?.artifact_path || null,
                         dimensions: { width: meta.width, height: meta.height, format: meta.format },
@@ -454,12 +485,14 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
                     schema: 'sks.image-ux-gpt-image-2-response.v1',
                     created_at: nowIso(),
                     provider: 'openai_images_api',
+                    evidence_class: 'non_codex_api_fallback',
                     model: 'gpt-image-2',
                     auth_source: auth.auth_source,
                     ok: true,
                     status: 'generated',
                     output_image_path: out,
                     output_image_sha256: meta.sha256,
+                    output_sha256: meta.sha256,
                     output_id: meta.output_id,
                     image_artifact_path_contract: imageContract?.artifact_path || null,
                     dimensions: { width: meta.width, height: meta.height, format: meta.format },
@@ -511,24 +544,17 @@ async function resolveImageArtifactRoot(input) {
     return projectRoot(input.output_dir || process.cwd()).catch(() => cwdRoot);
 }
 export async function generateGptImage2CalloutReview(input, opts = {}) {
-    if (opts.fake === true || process.env.SKS_TEST_FAKE_IMAGEGEN === '1') {
-        return createFakeImagegenAdapter(opts.fakeAdapter || {}).generateCalloutReview(input);
+    if ((opts.fake === true || process.env.SKS_TEST_FAKE_IMAGEGEN === '1') && imagegenMockContext(opts)) {
+        return createFakeImagegenAdapter({ ...(opts.fakeAdapter || {}), mockContext: true }).generateCalloutReview(input);
     }
     const capability = await detectImagegenCapability(opts.capability || {}).catch(() => null);
-    // Auto-enable the OpenAI direct-key API fallback whenever an OPENAI_API_KEY is
-    // available, so a missing/failed Codex App $imagegen surface still produces a
-    // real image instead of a hard block. Explicit opt-out wins: pass
-    // allowApiFallback:false or SKS_IMAGEGEN_ALLOW_API_FALLBACK=0.
-    const openAiKeyPresent = Boolean(opts.openai?.apiKey || process.env.OPENAI_API_KEY);
-    const explicitDisableApiFallback = opts.allowApiFallback === false || process.env.SKS_IMAGEGEN_ALLOW_API_FALLBACK === '0';
     // codex-lb imagegen is a direct API fallback, not Codex App imagegen evidence.
     // It must be explicitly enabled by the caller or environment.
     const explicitDisableCodexLbFallback = opts.allowCodexLbApiFallback === false || process.env.SKS_IMAGEGEN_ALLOW_CODEX_LB_API_FALLBACK === '0';
     const allowCodexLbApiFallback = !explicitDisableCodexLbFallback && (opts.allowCodexLbApiFallback === true
         || process.env.SKS_IMAGEGEN_ALLOW_CODEX_LB_API_FALLBACK === '1');
-    const allowApiFallback = !explicitDisableApiFallback && (opts.allowApiFallback === true
+    const allowApiFallback = (opts.allowApiFallback === true
         || process.env.SKS_IMAGEGEN_ALLOW_API_FALLBACK === '1'
-        || openAiKeyPresent
         || allowCodexLbApiFallback);
     const openaiOptions = {
         ...(opts.openai || {}),
@@ -544,6 +570,13 @@ export async function generateGptImage2CalloutReview(input, opts = {}) {
         return codexResult;
     return createOpenAIImagesApiAdapter(openaiOptions).generateCalloutReview(input);
 }
+function imagegenMockContext(opts = {}) {
+    return opts.mockContext === true
+        || opts.testContext === true
+        || process.env.NODE_ENV === 'test'
+        || process.env.SKS_SELFTEST_MOCK === '1'
+        || process.env.SKS_MOCK === '1';
+}
 export function imagegenCapabilityBlocker(surface = 'Codex App $imagegen') {
     return {
         schema: 'sks.image-ux-imagegen-blocker.v1',
@@ -705,6 +738,9 @@ export async function generatedImageMetadata(root, imagePath, opts = {}) {
         source_screen_id: opts.source_screen_id || null,
         provider_model: 'gpt-image-2',
         provider_surface: opts.provider_surface || 'codex_app_imagegen',
+        evidence_class: opts.evidence_class || (opts.mock ? 'mock_fixture' : 'codex_app_imagegen'),
+        output_source: opts.output_source || (opts.mock ? 'mock_fixture' : 'manual_attach'),
+        output_sha256: opts.output_sha256 || await sha256File(absolute),
         requested_fidelity: 'high_fidelity_automatic',
         image_input_fidelity_note: 'high_fidelity_automatic',
         privacy: 'local-only',
@@ -729,6 +765,7 @@ function redactedImagegenResponse(payload, ok, latencyMs, provider = 'openai_ima
         schema: 'sks.image-ux-gpt-image-2-response.v1',
         created_at: nowIso(),
         provider,
+        evidence_class: provider === 'codex_app_imagegen' ? 'codex_app_imagegen' : 'non_codex_api_fallback',
         model: 'gpt-image-2',
         ok,
         status: ok ? 'generated' : 'blocked',

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

@@ -790,11 +790,14 @@ function buildImagegenResponseArtifact(generatedReviewLedger = {}) {
         schema: 'sks.image-ux-gpt-image-2-response.v1',
         created_at: nowIso(),
         provider: image?.provider_surface || generatedReviewLedger.provider?.preferred_surface || 'none',
+        evidence_class: image?.evidence_class || (image?.mock ? 'mock_fixture' : image?.real_generated ? 'codex_app_imagegen' : null),
         model: 'gpt-image-2',
         ok: generatedReviewLedger.passed === true,
         status: generatedReviewLedger.passed === true ? 'generated' : 'blocked_or_pending',
         output_image_path: image?.path || null,
         output_image_sha256: image?.sha256 || null,
+        output_sha256: image?.output_sha256 || image?.sha256 || null,
+        output_source: image?.output_source || (image?.mock ? 'mock_fixture' : image?.real_generated ? 'manual_attach' : null),
         output_id: image?.output_id || null,
         dimensions: image ? { width: image.width || null, height: image.height || null, format: image.format || null } : null,
         latency_ms: image?.latency_ms || null,
@@ -863,6 +866,19 @@ function generatedImageEvidenceBlockers(image = {}, evidence = {}) {
     if (image.real_generated !== true || image.mock === true || image.source === 'mock_fixture')
         return [];
     const blockers = [];
+    const evidenceClass = String(image.evidence_class || '');
+    const outputSource = String(image.output_source || '');
+    const outputSha = String(image.output_sha256 || image.output_image_sha256 || '');
+    if (!evidenceClass)
+        blockers.push('generated_review_image_evidence_class_missing');
+    else if (evidenceClass !== 'codex_app_imagegen')
+        blockers.push(`generated_review_image_evidence_class_not_codex_app:${evidenceClass}`);
+    if (outputSource && !['manual_attach', 'auto_discovered_generated_images'].includes(outputSource))
+        blockers.push(`generated_review_image_output_source_invalid:${outputSource}`);
+    if (!outputSha)
+        blockers.push('generated_review_image_output_sha256_missing');
+    else if (evidence.sha256 && outputSha !== evidence.sha256)
+        blockers.push('generated_review_image_output_sha256_mismatch');
     if (!image.path)
         blockers.push('generated_review_image_missing');
     if (!evidence.sha256)

package/dist/core/imagegen/imagegen-capability.js

@@ -18,8 +18,13 @@ export async function detectImagegenCapability(opts = {}) {
     }).catch(() => null);
     const apiFallbackAvailable = openaiApiKeyPresent;
     const fakeAdapterEnabled = opts.fake === true || env.SKS_TEST_FAKE_IMAGEGEN === '1';
-    const realGenerationAvailable = codexAppBuiltInAvailable || apiFallbackAvailable;
-    const routeGenerationAvailable = realGenerationAvailable || fakeAdapterEnabled;
+    const fakeAdapterAcceptedForRoute = fakeAdapterEnabled && (opts.mockContext === true
+        || opts.testContext === true
+        || env.NODE_ENV === 'test'
+        || env.SKS_SELFTEST_MOCK === '1'
+        || env.SKS_MOCK === '1');
+    const realGenerationAvailable = codexAppBuiltInAvailable;
+    const routeGenerationAvailable = codexAppBuiltInAvailable || fakeAdapterAcceptedForRoute;
     const coreReady = codexAppBuiltInAvailable;
     const coreBlockers = coreReady ? [] : ['codex_app_builtin_imagegen_capability_missing'];
     const routeGenerationBlockers = routeGenerationAvailable ? [] : ['imagegen_capability_missing'];
@@ -68,16 +73,17 @@ export async function detectImagegenCapability(opts = {}) {
         },
         fake_adapter: {
             available: fakeAdapterEnabled,
+            accepted_for_route_readiness: fakeAdapterAcceptedForRoute,
             env: 'SKS_TEST_FAKE_IMAGEGEN=1',
             source: 'mock_like_fixture',
             real_generation_claim_allowed: false
         },
-        supports_reference_image: codexAppBuiltInAvailable || apiFallbackAvailable || fakeAdapterEnabled,
+        supports_reference_image: codexAppBuiltInAvailable || fakeAdapterAcceptedForRoute,
         gpt_image_2_input_fidelity_automatic: true,
         input_fidelity_must_be_omitted: true,
         supported_workflows: {
-            ux_review_callouts: codexAppBuiltInAvailable || apiFallbackAvailable || fakeAdapterEnabled,
-            ppt_slide_callouts: codexAppBuiltInAvailable || apiFallbackAvailable || fakeAdapterEnabled,
+            ux_review_callouts: codexAppBuiltInAvailable || fakeAdapterAcceptedForRoute,
+            ppt_slide_callouts: codexAppBuiltInAvailable || fakeAdapterAcceptedForRoute,
             structured_extraction_required_after_generation: true,
             full_verification_requires_codex_app_output: true
         },

package/dist/core/imagegen/require-imagegen.js

@@ -0,0 +1,57 @@
+import { detectImagegenCapability } from './imagegen-capability.js';
+import { repairCodexImagegen } from '../doctor/imagegen-repair.js';
+export async function requireCodexImagegen(root, opts = {}) {
+    const capability = await detectImagegenCapability({
+        codexBin: opts.codexBin || undefined,
+        timeoutMs: opts.timeoutMs || 5000
+    }).catch((err) => ({
+        ok: false,
+        core_ready: false,
+        blockers: [err instanceof Error ? err.message : String(err)]
+    }));
+    if (capability.core_ready === true) {
+        return { ok: true, capability, repair: null, blocker: null, blockers: [] };
+    }
+    const repair = opts.autoRepair === true
+        ? await repairCodexImagegen({
+            root,
+            apply: opts.applyRepair === true,
+            codexBin: opts.codexBin || null,
+            timeoutMs: opts.timeoutMs || 5000
+        }).catch((err) => ({
+            ok: false,
+            recovered: false,
+            blockers: [err instanceof Error ? err.message : String(err)]
+        }))
+        : null;
+    const finalCapability = repair
+        ? repair.after || capability
+        : capability;
+    const ok = finalCapability.core_ready === true || repair?.recovered === true;
+    const blockers = ok ? [] : [
+        ...new Set([
+            ...((finalCapability?.core_blockers || []).map(String)),
+            ...((finalCapability?.blockers || []).map(String)),
+            ...((repair?.blockers || []).map(String)),
+            'codex_imagegen_unavailable'
+        ])
+    ];
+    return {
+        ok,
+        capability: finalCapability,
+        repair,
+        blocker: ok ? null : {
+            schema: 'sks.codex-imagegen-required-blocker.v1',
+            blocker: 'codex_imagegen_unavailable',
+            status: 'blocked',
+            blockers,
+            next_actions: repair?.manual_actions || [
+                'Install/update Codex CLI: npm i -g @openai/codex@latest',
+                'Open Codex App settings and enable image_generation / $imagegen.',
+                'Verify with: codex features list --json'
+            ]
+        },
+        blockers
+    };
+}
+//# sourceMappingURL=require-imagegen.js.map