sneakoscope 4.8.6 → 5.1.2

package/dist/core/hooks-runtime.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { projectRoot, readJson, readText, writeJsonAtomic, appendJsonl, readStdin, nowIso, runProcess, sha256, packageRoot, tmpdir } from './fsx.js';
 import { looksInteractiveCommand, interactiveCommandReason } from './no-question-guard.js';
-import { missionDir, setCurrent, stateFile } from './mission.js';
+import { loadStateForSession, missionDir, setCurrent } from './mission.js';
 import { checkDbOperation, dbBlockReason, handleMadSksUserConfirmation } from './db-safety.js';
 import { maybeRecordMadDbToolResultFromToolUse } from './mad-db/mad-db-result-lifecycle.js';
 import { checkHarnessModification, harnessGuardBlockReason, isHarnessSourceProject } from './harness-guard.js';
@@ -16,6 +16,8 @@ import { leanEngineeringCompactText } from './lean-engineering-policy.js';
 import { appendMissionStatus } from './recallpulse.js';
 import { scanAgentTextForRecursion } from './agents/agent-recursion-guard.js';
 import { evaluateLoopContinuation } from './loops/loop-continuation-enforcer.js';
+import { diagnosticPromptAllowedDuringNoQuestions } from './routes/diagnostic-allowlist.js';
+import { maybeReconcileProjectSkillsPreflight } from './hooks-runtime/skill-reconcile-preflight.js';
 import { buildCompactContinue, buildPermissionRequestAllow, buildPermissionRequestDeny, buildPostToolUseBlock, buildPostToolUseContinue, buildPreToolUseContinue, buildPreToolUseDeny, buildSessionStartContinue, buildStopBlock, buildStopContinue, buildSubagentStartContinue, buildSubagentStopBlock, buildSubagentStopContinue, buildUserPromptSubmitBlock, buildUserPromptSubmitContinue } from './codex-compat/codex-hook-output-builders.js';
 import { joinSystemMessages, teamLiveDigest } from './hooks-runtime/team-digest.js';
 const STOP_REPEAT_GUARD_ARTIFACT = 'stop-hook-repeat-guard.json';
@@ -38,8 +40,8 @@ async function loadHookPayload() {
         return { raw };
     }
 }
-async function loadState(root) {
-    return readJson(stateFile(root), {});
+async function loadState(root, payload = {}) {
+    return loadStateForSession(root, conversationId(payload));
 }
 function isNoQuestionRunning(state) {
     return (state.mode === 'RESEARCH' && state.phase === 'RESEARCH_RUNNING_NO_QUESTIONS')
@@ -61,6 +63,9 @@ function extractUserPrompt(payload) {
 function conversationId(payload) {
     return String(payload.conversation_id || payload.thread_id || payload.session_id || payload.chat_id || payload.cwd || 'default');
 }
+function explicitConversationId(payload = {}) {
+    return payload.conversation_id || payload.thread_id || payload.session_id || payload.chat_id || null;
+}
 function extractCommand(payload) {
     return payload.command || payload.tool_input?.command || payload.toolInput?.command || payload.input?.command || payload.tool?.input?.command || '';
 }
@@ -176,27 +181,39 @@ export async function hookMain(name) {
 }
 export async function evaluateHookPayload(name, payload = {}, opts = {}) {
     const root = opts.root || await projectRoot(payload.cwd || process.cwd());
-    const state = opts.state || payload.state || await loadState(root);
+    const sessionKey = conversationId(payload);
+    if (!explicitConversationId(payload)) {
+        await appendJsonl(path.join(root, '.sneakoscope', 'state', 'session-id-fallback-warning.jsonl'), {
+            ts: nowIso(),
+            warning: 'hook_payload_missing_explicit_session_id',
+            conversation_id: sessionKey,
+            cwd_hash: sha256(String(payload.cwd || root)).slice(0, 12),
+            hook: name
+        }).catch(() => null);
+    }
+    const loadedState = opts.state || payload.state || await loadState(root, payload);
+    const state = { ...loadedState, _session_key: loadedState?._session_key || sessionKey };
     const noQuestion = isNoQuestionRunning(state);
     if (name === 'user-prompt-submit') {
         const modelBlock = blockForbiddenClientModel(payload);
         if (modelBlock)
             return modelBlock;
-        return hookUserPrompt(root, state, payload, noQuestion);
+        return hookUserPrompt(root, state, payload, noQuestion, sessionKey);
     }
     if (name === 'pre-tool')
-        return hookPreTool(root, state, payload, noQuestion);
+        return hookPreTool(root, state, payload, noQuestion, sessionKey);
     if (name === 'post-tool')
-        return hookPostTool(root, state, payload, noQuestion);
+        return hookPostTool(root, state, payload, noQuestion, sessionKey);
     if (name === 'permission-request')
-        return hookPermission(root, state, payload, noQuestion);
+        return hookPermission(root, state, payload, noQuestion, sessionKey);
     if (name === 'stop')
-        return hookStop(root, state, payload, noQuestion);
+        return hookStop(root, state, payload, noQuestion, sessionKey);
     if (name === 'subagent-start')
-        return hookSubagentStart(root, state);
+        return hookSubagentStart(root, state, sessionKey);
     return { continue: true };
 }
-async function hookSubagentStart(root, state) {
+async function hookSubagentStart(root, state, sessionKey = null) {
+    void sessionKey;
     const active = await activeRouteContext(root, state).catch(() => '');
     const additionalContext = [leanEngineeringCompactText(), active].filter(Boolean).join('\n\n');
     return { continue: true, additionalContext };
@@ -265,7 +282,7 @@ function clientModelCandidates(value, depth = 0) {
     }
     return out;
 }
-async function hookUserPrompt(root, state, payload, noQuestion) {
+async function hookUserPrompt(root, state, payload, noQuestion, sessionKey = null) {
     if (looksLikeCodexGitAction(payload)) {
         await armCodexGitActionStopBypass(root, payload).catch(() => null);
         return {
@@ -279,6 +296,7 @@ async function hookUserPrompt(root, state, payload, noQuestion) {
             systemMessage: 'SKS: Codex App settings/profile event ignored; route gates unchanged.'
         };
     }
+    await maybeReconcileProjectSkillsPreflight(root).catch(() => null);
     if (!noQuestion) {
         const prompt = stripVisibleDecisionAnswerBlocks(extractUserPrompt(payload));
         const madSksConfirmation = await handleMadSksUserConfirmation(root, state, prompt);
@@ -311,12 +329,13 @@ async function hookUserPrompt(root, state, payload, noQuestion) {
             return { continue: true, additionalContext, systemMessage: joinSystemMessages(visibleHookMessage('user-prompt-submit', additionalContext), teamDigest?.system) };
         }
         const teamDigest = (bypassActiveRoute || command || prepareFreshRoute) ? null : await teamLiveDigest(root, state);
-        const activeContext = await activeRouteContext(root, state);
+        const shouldLoadActiveContext = !command && !bypassActiveRoute && !goalOverlay && !prepareFreshRoute;
+        const activeContext = shouldLoadActiveContext ? await activeRouteContext(root, state) : '';
         const contexts = [updateContext];
-        if (activeContext && !command && !bypassActiveRoute && !goalOverlay && !prepareFreshRoute)
+        if (activeContext && shouldLoadActiveContext)
             contexts.push(routePipelineContext(prompt), activeContext);
         else
-            contexts.push((await prepareRoute(root, prompt, state)).additionalContext);
+            contexts.push((await prepareRoute(root, prompt, state, { sessionKey })).additionalContext);
         if (goalOverlay)
             contexts.push(goalOverlay);
         if (teamDigest?.context)
@@ -324,6 +343,13 @@ async function hookUserPrompt(root, state, payload, noQuestion) {
         const additionalContext = contexts.filter(Boolean).join('\n\n');
         return { continue: true, additionalContext, systemMessage: joinSystemMessages(visibleHookMessage('user-prompt-submit', additionalContext), teamDigest?.system) };
     }
+    const prompt = stripVisibleDecisionAnswerBlocks(extractUserPrompt(payload));
+    if (diagnosticPromptAllowedDuringNoQuestions(prompt)) {
+        return {
+            continue: true,
+            systemMessage: 'SKS: diagnostic command allowed during no-question mode by command registry contract.'
+        };
+    }
     const id = state.mission_id;
     if (id)
         await appendJsonl(path.join(missionDir(root, id), 'user_queue.jsonl'), { ts: nowIso(), payload });
@@ -380,18 +406,21 @@ function activeGoalOverlayContext(state = {}, route = null) {
         `Goal artifact: .sneakoscope/missions/${state.mission_id}/goal-workflow.json. Use Codex native /goal controls only if the user explicitly returns to $Goal.`
     ].join('\n');
 }
-async function hookPreTool(root, state, payload, noQuestion) {
-    const madSksImmutableDecision = await checkMadSksImmutableModification(root, state, payload);
-    if (madSksImmutableDecision.action === 'block') {
-        return { decision: 'block', permissionDecision: 'deny', reason: madSksImmutableBlockReason(madSksImmutableDecision) };
-    }
-    const harnessDecision = await checkHarnessModification(root, payload, { phase: 'pre-tool' });
-    if (harnessDecision.action === 'block') {
-        return { decision: 'block', permissionDecision: 'deny', reason: harnessGuardBlockReason(harnessDecision) };
-    }
-    const dbDecision = await checkDbOperation(root, state, payload, { duringNoQuestion: noQuestion });
-    if (dbDecision.action === 'block' || dbDecision.action === 'confirm') {
-        return { decision: 'block', permissionDecision: 'deny', reason: dbBlockReason(dbDecision) };
+async function hookPreTool(root, state, payload, noQuestion, sessionKey = null) {
+    void sessionKey;
+    if (needsMutationSafetyCheck(payload)) {
+        const madSksImmutableDecision = await checkMadSksImmutableModification(root, state, payload);
+        if (madSksImmutableDecision.action === 'block') {
+            return { decision: 'block', permissionDecision: 'deny', reason: madSksImmutableBlockReason(madSksImmutableDecision) };
+        }
+        const harnessDecision = await checkHarnessModification(root, payload, { phase: 'pre-tool' });
+        if (harnessDecision.action === 'block') {
+            return { decision: 'block', permissionDecision: 'deny', reason: harnessGuardBlockReason(harnessDecision) };
+        }
+        const dbDecision = await checkDbOperation(root, state, payload, { duringNoQuestion: noQuestion });
+        if (dbDecision.action === 'block' || dbDecision.action === 'confirm') {
+            return { decision: 'block', permissionDecision: 'deny', reason: dbBlockReason(dbDecision) };
+        }
     }
     if (clarificationGateLocked(state) && !clarificationAnswerToolAllowed(payload)) {
         return { decision: 'block', permissionDecision: 'deny', reason: clarificationPauseBlockReason(state) };
@@ -430,12 +459,14 @@ function agentWorkerHookContext(state = {}, payload = {}) {
         || payload.agent_worker === true
         || payload.agentWorker === true);
 }
-async function hookPostTool(root, state, payload, noQuestion) {
-    await recordMadDbPostToolLifecycle(root, state, payload).catch(() => null);
-    await recordContext7Evidence(root, state, payload).catch(() => null);
-    await recordSubagentEvidence(root, state, payload).catch(() => null);
-    if (toolFailed(payload))
-        await recordToolErrorTaxonomy(root, state, payload).catch(() => null);
+async function hookPostTool(root, state, payload, noQuestion, sessionKey = null) {
+    state = { ...state, _session_key: state?._session_key || sessionKey };
+    await Promise.all([
+        recordMadDbPostToolLifecycle(root, state, payload).catch(() => null),
+        recordContext7Evidence(root, state, payload).catch(() => null),
+        recordSubagentEvidence(root, state, payload).catch(() => null),
+        toolFailed(payload) ? recordToolErrorTaxonomy(root, state, payload).catch(() => null) : Promise.resolve(null)
+    ]);
     const teamDigest = await teamLiveDigest(root, state);
     if (!noQuestion) {
         return teamDigest?.context
@@ -455,6 +486,17 @@ async function hookPostTool(root, state, payload, noQuestion) {
         ? { continue: true, additionalContext: teamDigest.context, systemMessage: joinSystemMessages(visibleHookMessage('post-tool'), teamDigest.system) }
         : { continue: true };
 }
+function needsMutationSafetyCheck(payload = {}) {
+    const toolName = String(payload.tool_name || payload.toolName || payload.name || payload.tool?.name || '');
+    const knownReadOnly = /^(Read|Grep|Glob|LS|TodoRead|WebFetch|WebSearch|BashOutput|NotebookRead|ListMcpResources|ReadMcpResource)$/i;
+    if (knownReadOnly.test(toolName))
+        return /\b(sql|supabase|db|migration)\b/i.test(JSON.stringify(payload || {}));
+    if (/^(Edit|Write|MultiEdit|NotebookEdit|Bash|Shell|ApplyPatch)$/i.test(toolName))
+        return true;
+    if (/\b(sql|supabase|db|migration)\b/i.test(toolName))
+        return true;
+    return true;
+}
 async function recordMadDbPostToolLifecycle(root, state = {}, payload = {}) {
     if (!state?.mission_id)
         return null;
@@ -508,7 +550,8 @@ async function recordToolErrorTaxonomy(root, state = {}, payload = {}) {
     await appendJsonl(path.join(missionDir(root, state.mission_id), 'tool-errors.jsonl'), record);
     return record;
 }
-async function hookPermission(root, state, payload, noQuestion) {
+async function hookPermission(root, state, payload, noQuestion, sessionKey = null) {
+    void sessionKey;
     const madSksImmutableDecision = await checkMadSksImmutableModification(root, state, payload);
     if (madSksImmutableDecision.action === 'block') {
         return { decision: 'deny', permissionDecision: 'deny', reason: madSksImmutableBlockReason(madSksImmutableDecision) };
@@ -610,7 +653,7 @@ function clarificationPauseBlockReason(state = {}) {
     const route = state.route_command || state.route || state.mode || 'route';
     return `SKS ${route} ambiguity gate is paused and waiting for explicit user answers. Do not run implementation, tests, route materialization, or unrelated tools yet. The only allowed action is sealing the user's reply with "sks pipeline answer ${id} --stdin"; elapsed time or repeated hook resumes never count as answers.`;
 }
-async function hookStop(root, state, payload, noQuestion) {
+async function hookStop(root, state, payload, noQuestion, sessionKey = null) {
     const last = extractLastMessage(payload);
     if (state?.mode === 'LOOP' || state?.route === 'Loop' || state?.route_command === '$Loop') {
         const missionId = state?.mission_id;
@@ -664,14 +707,14 @@ async function hookStop(root, state, payload, noQuestion) {
             };
         }
         if (shouldLoopBackAfterHonestMode(state) && hasHonestModeUnresolvedGap(last)) {
-            const loopback = await recordHonestModeLoopback(root, state, last);
+            const loopback = await recordHonestModeLoopback(root, state, last, sessionKey);
             return {
                 decision: 'block',
                 reason: `${localizedFinalizationReason('honest_loopback', languageBasis)} Loopback: ${loopback.relative_file}`
             };
         }
         if (state?.honest_loop_required)
-            await resolveHonestModeLoopback(root, state);
+            await resolveHonestModeLoopback(root, state, sessionKey);
         return { continue: true };
     }
     return {
@@ -691,7 +734,7 @@ async function consumeLightRouteStop(root, payload = {}) {
     if (!Number.isFinite(expiresMs) || expiresMs < nowMs)
         return false;
     const currentConversation = conversationId(payload);
-    if (record.conversation_id && explicitConversationId(payload) && record.conversation_id !== currentConversation)
+    if (record.conversation_id && record.conversation_id !== currentConversation)
         return false;
     await writeJsonAtomic(file, {
         ...record,
@@ -712,9 +755,6 @@ function hasDfixLightCompletion(text) {
     const gap = /(미검증|남은|문제|gap|remaining|not verified|not run|blocker|차단|불가|없음|none)/i.test(s);
     return verification && gap;
 }
-function explicitConversationId(payload = {}) {
-    return payload.conversation_id || payload.thread_id || payload.session_id || payload.chat_id || null;
-}
 function looksLikeCodexGitAction(payload = {}) {
     const prompt = stripVisibleDecisionAnswerBlocks(extractUserPrompt(payload));
     const metadataText = codexGitActionMetadataText(payload);
@@ -824,7 +864,7 @@ async function consumeCodexGitActionStopBypass(root, payload = {}) {
     if (!Number.isFinite(expiresMs) || expiresMs < Date.now())
         return false;
     const currentConversation = conversationId(payload);
-    if (record.conversation_id && explicitConversationId(payload) && record.conversation_id !== currentConversation)
+    if (record.conversation_id && record.conversation_id !== currentConversation)
         return false;
     await writeJsonAtomic(file, {
         ...record,
@@ -971,7 +1011,7 @@ function shouldLoopBackAfterHonestMode(state = {}) {
         return false;
     return Boolean(state.ambiguity_gate_passed || state.clarification_passed || /CONTRACT_SEALED|HONEST_LOOPBACK/i.test(String(state.phase || '')));
 }
-async function recordHonestModeLoopback(root, state = {}, lastMessage = '') {
+async function recordHonestModeLoopback(root, state = {}, lastMessage = '', sessionKey = null) {
     const id = state.mission_id;
     const dir = missionDir(root, id);
     const previousPhase = state.phase || null;
@@ -999,10 +1039,10 @@ async function recordHonestModeLoopback(root, state = {}, lastMessage = '') {
         questions_allowed: false,
         ambiguity_gate_required: true,
         ambiguity_gate_passed: true
-    });
+    }, { sessionKey: sessionKey || state._session_key });
     return { file, relative_file: path.relative(root, file).split(path.sep).join('/') };
 }
-async function resolveHonestModeLoopback(root, state = {}) {
+async function resolveHonestModeLoopback(root, state = {}, sessionKey = null) {
     const id = state.mission_id;
     const mode = String(state.mode || state.route || 'SKS').toUpperCase();
     if (id)
@@ -1012,7 +1052,7 @@ async function resolveHonestModeLoopback(root, state = {}) {
         honest_loop_required: false,
         honest_loop_resolved_at: nowIso(),
         questions_allowed: true
-    });
+    }, { sessionKey: sessionKey || state._session_key });
 }
 export async function emitHook(name) {
     const result = await hookMain(name);

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