sneakoscope 2.0.17 → 2.0.18

package/dist/core/commands/naruto-command.js

@@ -20,6 +20,7 @@ import { planNarutoZellijDashboard } from '../zellij/zellij-naruto-dashboard.js'
 import { checkPromptPlaceholders } from '../prompt/prompt-placeholder-guard.js';
 import { evaluateGitWorktreeCapability } from '../git/git-worktree-capability.js';
 import { buildRuntimeProofSummary, renderRuntimeProofSummary } from '../agents/runtime-proof-summary.js';
+import { writeCodex0138CapabilityArtifacts } from '../codex-control/codex-0138-capability.js';
 const NARUTO_RESULT_SCHEMA = 'sks.naruto-command-result.v1';
 const NARUTO_ROUTE = '$Naruto';
 // $Naruto — Shadow Clone Swarm (影分身 / Kage Bunshin no Jutsu).
@@ -73,6 +74,7 @@ async function narutoRun(parsed) {
         maxAgentCount: MAX_NARUTO_AGENT_COUNT
     });
     const mission = await createMission(root, { mode: 'naruto', prompt: parsed.prompt });
+    await writeCodex0138CapabilityArtifacts(root, { missionId: mission.id }).catch(() => null);
     const gitWorktreeCapability = writeCapable
         ? await evaluateGitWorktreeCapability({ root, missionId: mission.id })
         : null;
@@ -382,7 +384,7 @@ async function narutoRun(parsed) {
         && Number(parallelRuntime.max_observed_active_workers || 0) >= Math.min(16, activeSlots));
     await writeJsonAtomic(path.join(mission.dir, 'naruto-gate.json'), {
         schema: 'sks.naruto-gate.v1',
-        passed: result.ok === true && nativeProofOk && finalAccepted,
+        passed: result.ok === true && nativeProofOk && finalAccepted && parallelRuntimeOk,
         mission_id: mission.id,
         clone_roster_built: true,
         clone_count: roster.agent_count,

package/dist/core/commands/qa-loop-command.js

@@ -13,6 +13,12 @@ import { scanDbSafety } from '../db-safety.js';
 import { maybeFinalizeRoute } from '../proof/auto-finalize.js';
 import { runNativeAgentOrchestrator } from '../agents/agent-orchestrator.js';
 import { flag, promptOf, readBoundedIntegerFlag, readFlagValue, readMaxCycles, resolveMissionId, safeReadTextFile } from './command-utils.js';
+import { runCodexAppHandoff, qaLoopShouldRequestAppHandoff } from '../codex-app/codex-app-handoff.js';
+import { writeCodex0138CapabilityArtifacts } from '../codex-control/codex-0138-capability.js';
+import { writeCodexAccountUsageArtifacts } from '../usage/codex-account-usage.js';
+import { buildQaLoopBudgetPolicy, selectQaLoopEscalatedEffort } from '../qa-loop/qa-loop-budget-policy.js';
+import { discoverImageArtifactsInDir, writeImageArtifactPathContract } from '../image/image-artifact-path-contract.js';
+import { pluginAppTemplatePolicy } from '../codex-plugins/codex-plugin-json.js';
 import fsp from 'node:fs/promises';
 export async function qaLoopCommand(sub, args = []) {
     const known = new Set(['prepare', 'answer', 'run', 'status', 'help', '--help', '-h']);
@@ -31,8 +37,8 @@ export async function qaLoopCommand(sub, args = []) {
 Usage:
   sks qa-loop prepare "target"
   sks qa-loop answer <mission-id|latest> <answers.json>
-  sks qa-loop run <mission-id|latest> [--mock] [--max-cycles N]
-  sks qa-loop status <mission-id|latest>
+  sks qa-loop run <mission-id|latest> [--mock] [--max-cycles N] [--app-handoff] [--app-handoff-required]
+  sks qa-loop status <mission-id|latest> [--desktop]
 `);
 }
 function qaRoute() {
@@ -136,6 +142,90 @@ async function qaLoopRun(args) {
     const qaGate = await readJson(path.join(dir, 'qa-gate.json'), {});
     const reportFile = qaGate.qa_report_file;
     const uiRequired = qaUiRequired(contract.answers || {});
+    const capabilityArtifact = await writeCodex0138CapabilityArtifacts(root, { missionId: id }).catch((err) => ({ error: err?.message || String(err), report: null }));
+    const usageArtifact = await writeCodexAccountUsageArtifacts(root, { missionId: id }).catch((err) => ({ error: err?.message || String(err), snapshot: null }));
+    const budgetPolicy = buildQaLoopBudgetPolicy({ usage: usageArtifact?.snapshot || null, provider: 'codex-sdk' });
+    await writeJsonAtomic(path.join(dir, 'qa-loop', 'qa-loop-budget-policy.json'), budgetPolicy);
+    const effortEscalation = selectQaLoopEscalatedEffort({
+        failureCount: Number(qaGate.safe_fix_attempts || qaGate.failure_count || 0),
+        currentEffort: String(profile || 'high').replace(/^sks-(?:logic|agent)-/, '').replace(/-fast$/, '') || 'high'
+    });
+    await writeJsonAtomic(path.join(dir, 'qa-loop', 'qa-loop-effort-escalation.json'), effortEscalation);
+    const discoveredImages = await discoverImageArtifactsInDir(dir).catch(() => []);
+    const imagePathContract = discoveredImages.length
+        ? await writeQaLoopImagePathContract(root, dir, id, discoveredImages)
+        : null;
+    const pluginInventory = await readJson(path.join(root, '.sneakoscope', 'codex-plugin-inventory.json'), null);
+    const pluginPolicy = pluginInventory?.schema === 'sks.codex-plugin-inventory.v1' ? pluginAppTemplatePolicy(pluginInventory) : null;
+    const appHandoffRequired = flag(args, '--app-handoff-required') || process.env.SKS_QA_LOOP_APP_HANDOFF_REQUIRED === '1';
+    const appHandoffRequested = qaLoopShouldRequestAppHandoff({
+        args,
+        uiRequired,
+        visualArtifactsPresent: discoveredImages.length > 0,
+        pluginAppTemplateUnavailable: Boolean(pluginPolicy?.unavailable_app_templates?.length),
+        userRequestedDesktopReview: appHandoffRequired
+    });
+    const appHandoff = appHandoffRequested || appHandoffRequired
+        ? await runCodexAppHandoff(root, {
+            schema: 'sks.codex-app-handoff-request.v1',
+            mission_id: id,
+            route: '$QA-LOOP',
+            reason: appHandoffRequired ? 'desktop_app_review_required' : 'desktop_app_review_requested',
+            thread_ref: null,
+            workspace_path: root,
+            artifacts: [
+                'decision-contract.json',
+                'qa-gate.json',
+                'qa-ledger.json',
+                reportFile,
+                capabilityArtifact && !capabilityArtifact.error ? 'codex-0138-capability.json' : '',
+                imagePathContract ? 'qa-loop/image-artifact-path-contract.json' : ''
+            ].filter(Boolean),
+            prompt: mission.prompt || 'QA-LOOP desktop handoff',
+            require_desktop: appHandoffRequired,
+            capability_required: 'codex-0.138'
+        }).catch((err) => ({
+            ok: false,
+            status: 'blocked_for_desktop_review',
+            artifact_path: path.join(dir, 'qa-loop', 'app-handoff.json'),
+            blockers: [`codex_app_handoff_failed:${err?.message || String(err)}`],
+            desktop_handoff_supported: false
+        }))
+        : null;
+    if (appHandoff || imagePathContract) {
+        const latestGate = await readJson(path.join(dir, 'qa-gate.json'), qaGate);
+        const nextGate = {
+            ...latestGate,
+            desktop_app_handoff_required: appHandoffRequired,
+            desktop_app_handoff_status: appHandoff ? appHandoff.status : 'not_requested',
+            desktop_app_handoff_artifact: appHandoff ? path.relative(dir, appHandoff.artifact_path) : null,
+            desktop_app_handoff_supported: appHandoff ? appHandoff.desktop_handoff_supported === true : false,
+            desktop_app_handoff_is_web_ui_evidence: false,
+            image_artifact_path_contract_present: Boolean(imagePathContract),
+            image_artifact_path_contract_artifact: imagePathContract ? 'qa-loop/image-artifact-path-contract.json' : null,
+            image_artifact_path_contract_blockers: imagePathContract?.contract?.blockers || [],
+            blockers: Array.from(new Set([
+                ...(latestGate.blockers || []),
+                ...(appHandoffRequired && appHandoff && appHandoff.ok !== true ? ['blocked_for_desktop_review'] : []),
+                ...(imagePathContract?.contract?.blockers || [])
+            ])),
+            notes: [
+                ...(latestGate.notes || []),
+                ...(appHandoff ? ['Codex Desktop /app handoff is tracked separately and is not web UI verification evidence.'] : []),
+                ...(imagePathContract ? ['Image artifacts expose real saved file paths for follow-up visual edits.'] : [])
+            ]
+        };
+        await writeJsonAtomic(path.join(dir, 'qa-gate.json'), nextGate);
+        if (appHandoffRequired && appHandoff && appHandoff.ok !== true) {
+            await maybeFinalizeRoute(root, { missionId: id, route: '$QA-LOOP', gateFile: 'qa-gate.json', gate: nextGate, artifacts: ['qa-gate.json', 'qa-ledger.json', reportFile, 'qa-loop/app-handoff.json', 'completion-proof.json'], statusHint: 'blocked', blockers: nextGate.blockers, command: { cmd: `sks qa-loop run ${id} --app-handoff-required`, status: 2 } });
+            await setCurrent(root, { mission_id: id, mode: 'QALOOP', phase: 'QALOOP_BLOCKED_DESKTOP_APP_HANDOFF', questions_allowed: true });
+            if (flag(args, '--json'))
+                return console.log(JSON.stringify({ schema: 'sks.qa-loop-run.v1', ok: false, status: 'blocked_for_desktop_review', mission_id: id, app_handoff: appHandoff, gate: nextGate }, null, 2));
+            console.error('QA-LOOP blocked: Codex Desktop /app handoff is required but unavailable or still pending.');
+            process.exitCode = 2;
+            return;
+        }
+    }
     if (uiRequired && !mock) {
         const chrome = await codexChromeExtensionStatus();
         if (!chrome.ok) {
@@ -237,7 +327,7 @@ async function qaLoopRun(args) {
     for (let cycle = 1; cycle <= maxCycles; cycle += 1) {
         const cycleDir = path.join(dir, 'qa-loop', `cycle-${cycle}`);
         const outputFile = path.join(cycleDir, 'final.md');
-        const prompt = buildQaLoopPrompt({ id, mission, contract, cycle, previous: last, reportFile });
+        const prompt = buildQaLoopPrompt({ id, mission, contract, cycle, previous: last, reportFile, imagePathContract: imagePathContract?.contract || null, appHandoff });
         await appendJsonlBounded(path.join(dir, 'events.jsonl'), { ts: nowIso(), type: 'qaloop.cycle.start', cycle });
         const result = await runCodexExec({ root, prompt, outputFile, json: true, profile, logDir: cycleDir });
         await writeJsonAtomic(path.join(cycleDir, 'process.json'), { code: result.code, stdout_tail: result.stdout, stderr_tail: result.stderr, stdout_bytes: result.stdoutBytes, stderr_bytes: result.stderrBytes, truncated: result.truncated, timed_out: result.timedOut });
@@ -276,8 +366,9 @@ async function qaLoopStatus(args) {
     const status = await qaStatus(dir);
     const nativeAgentPlan = await readJson(path.join(dir, 'qa-agent-plan.json'), null);
     const agentSessions = await readJson(path.join(dir, 'agents', 'agent-sessions.json'), null);
+    const desktop = await readJson(path.join(dir, 'qa-loop', 'app-handoff.json'), null);
     if (flag(args, '--json'))
-        return console.log(JSON.stringify({ mission, state, qa: status, native_agent_plan: nativeAgentPlan, agent_sessions: agentSessions?.sessions || null }, null, 2));
+        return console.log(JSON.stringify({ mission, state, qa: status, desktop_app_handoff: desktop, native_agent_plan: nativeAgentPlan, agent_sessions: agentSessions?.sessions || null }, null, 2));
     console.log('SKS QA-LOOP Status\n');
     console.log(`Mission:   ${id}`);
     console.log(`Phase:     ${state.phase || mission.phase}`);
@@ -286,5 +377,21 @@ async function qaLoopStatus(args) {
     console.log(`Gate:      ${status.gate?.passed ? 'passed' : 'not passed'}`);
     if (status.gate?.reasons?.length)
         console.log(`Reasons:   ${status.gate.reasons.join(', ')}`);
+    if (flag(args, '--desktop')) {
+        console.log('Desktop:');
+        console.log(`  /app handoff: ${desktop?.status || 'not_requested'}`);
+        if (desktop?.operator_instruction?.prompt_artifact)
+            console.log(`  prompt:       ${desktop.operator_instruction.prompt_artifact}`);
+        console.log('  web evidence: not a substitute for Codex Chrome Extension web UI verification');
+    }
+}
+async function writeQaLoopImagePathContract(root, dir, missionId, images) {
+    const primary = await writeImageArtifactPathContract(root, {
+        missionId,
+        images,
+        artifactPath: path.join(dir, 'image-artifact-path-contract.json')
+    });
+    await writeJsonAtomic(path.join(dir, 'qa-loop', 'image-artifact-path-contract.json'), primary.contract);
+    return primary;
 }
 //# sourceMappingURL=qa-loop-command.js.map

package/dist/core/doctor/codex-0138-doctor.js

@@ -0,0 +1,104 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { detectCodex0138Capability } from '../codex-control/codex-0138-capability.js';
+import { nowIso, writeJsonAtomic } from '../fsx.js';
+export async function runCodex0138Doctor(root, input = {}) {
+    const capability = await detectCodex0138Capability();
+    const fixed = [];
+    const checks = {
+        bash_fallback: await bashFallbackCheck(),
+        linux_proxy_socket_path: linuxProxySocketCheck(root),
+        oauth_mcp_prerefresh: oauthMcpPrerefreshCheck(capability),
+        agents_logical_path: await agentsLogicalPathCheck(root),
+        plugin_discovery_cache: await pluginDiscoveryCacheCheck(root, input.fix === true, fixed)
+    };
+    const warnings = [
+        ...(capability.ok ? [] : ['codex_0_138_not_detected']),
+        ...Object.values(checks).flatMap((check) => Array.isArray(check.warnings) ? check.warnings : [])
+    ];
+    const blockers = Object.values(checks).flatMap((check) => Array.isArray(check.blockers) ? check.blockers : []);
+    const report = {
+        schema: 'sks.codex-0138-doctor.v1',
+        generated_at: nowIso(),
+        ok: blockers.length === 0,
+        codex_0138_capability: capability,
+        checks,
+        fixed,
+        warnings,
+        blockers
+    };
+    await writeJsonAtomic(path.join(root, '.sneakoscope', 'codex-0138-doctor.json'), report);
+    return report;
+}
+async function bashFallbackCheck() {
+    const candidates = ['/bin/bash', '/usr/bin/bash'];
+    const existing = [];
+    for (const candidate of candidates) {
+        try {
+            await fs.access(candidate);
+            existing.push(candidate);
+        }
+        catch { }
+    }
+    return {
+        ok: existing.length > 0,
+        candidates,
+        existing,
+        blockers: existing.length ? [] : ['bash_fallback_missing'],
+        warnings: []
+    };
+}
+function linuxProxySocketCheck(root) {
+    if (process.platform !== 'linux')
+        return { ok: true, status: 'not_linux', warnings: [], blockers: [] };
+    const candidate = path.join(os.tmpdir(), 'sks-proxy', path.basename(root), 'proxy.sock');
+    return {
+        ok: candidate.length < 100,
+        candidate,
+        length: candidate.length,
+        warnings: candidate.length < 100 ? [] : ['linux_proxy_socket_path_long'],
+        blockers: []
+    };
+}
+function oauthMcpPrerefreshCheck(capability) {
+    return {
+        ok: true,
+        supported: capability.supports_oauth_mcp_prerefresh === true,
+        warnings: capability.supports_oauth_mcp_prerefresh ? [] : ['oauth_mcp_prerefresh_requires_codex_0_138'],
+        blockers: []
+    };
+}
+async function agentsLogicalPathCheck(root) {
+    const agents = path.join(root, 'AGENTS.md');
+    const realRoot = await fs.realpath(root).catch(() => root);
+    const exists = await fs.stat(agents).then((st) => st.isFile()).catch(() => false);
+    return {
+        ok: exists,
+        logical_path: agents,
+        real_root: realRoot,
+        warnings: exists ? [] : ['agents_md_missing_or_unreadable'],
+        blockers: []
+    };
+}
+async function pluginDiscoveryCacheCheck(root, fix, fixed) {
+    const cacheDir = path.join(root, '.sneakoscope', 'cache', 'codex-plugin-discovery');
+    const exists = await fs.stat(cacheDir).then((st) => st.isDirectory()).catch(() => false);
+    if (!exists && fix) {
+        await fs.mkdir(cacheDir, { recursive: true });
+        await writeJsonAtomic(path.join(cacheDir, 'README.json'), {
+            schema: 'sks.codex-plugin-discovery-cache.v1',
+            repaired_at: nowIso(),
+            purpose: 'Codex 0.138 plugin discovery cache placeholder; safe to refresh from codex plugin list --json.'
+        });
+        fixed.push('plugin_discovery_cache');
+    }
+    const after = exists || fix;
+    return {
+        ok: after,
+        path: cacheDir,
+        warnings: after ? [] : ['plugin_discovery_cache_missing_repair_available'],
+        blockers: []
+    };
+}
+//# sourceMappingURL=codex-0138-doctor.js.map

package/dist/core/doctor/doctor-readiness-matrix.js

@@ -52,6 +52,14 @@ export function buildDoctorReadinessMatrix(input = {}) {
         blockers.add('codex_app_fast_ui_repair_requires_confirmation');
     if (input.codex_app_ui?.fast_selector === 'repaired')
         warnings.add('codex_app_fast_selector_repaired_restart_app_if_needed');
+    const codex0138Doctor = input.codex_0138_doctor || null;
+    if (codex0138Doctor?.ok === false)
+        for (const blocker of normalizeList(codex0138Doctor.blockers))
+            warnings.add(blocker);
+    for (const warning of normalizeList(codex0138Doctor?.warnings))
+        warnings.add(warning);
+    for (const warning of normalizeList(input.codex_plugin_app_template_policy?.doctor_warnings))
+        warnings.add(warning);
     if (input.codex_lb?.ok === false)
         warnings.add(`codex_lb_${input.codex_lb?.circuit?.state || 'blocked'}`);
     const localModel = input.local_model || {};
@@ -107,6 +115,9 @@ export function buildDoctorReadinessMatrix(input = {}) {
             replacement: 'zellij'
         },
         codex_doctor: codexDoctor || null,
+        codex_0138_doctor: codex0138Doctor,
+        codex_plugin_inventory: input.codex_plugin_inventory || null,
+        codex_plugin_app_template_policy: input.codex_plugin_app_template_policy || null,
         fast_mode_ready: input.fast_mode_ready !== false,
         codex_app_ui: input.codex_app_ui || null,
         hooks_ready: input.hooks_ready !== false,

package/dist/core/effort-orchestrator.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { nowIso, writeJsonAtomic } from './fsx.js';
 import { ARTIFACT_FILES } from './artifact-schemas.js';
+import { codexModelEffortCapability, modelEffortAtLeast } from './codex-control/codex-model-capabilities.js';
 export const EFFORT_POLICY_VERSION = 1;
 export function selectEffort(task = {}) {
     const route = String(task.route || task.command || '').toLowerCase();
@@ -39,11 +40,19 @@ export function selectEffort(task = {}) {
         selected = 'medium';
         reasonCodes.push('default_medium');
     }
+    const modelCapability = codexModelEffortCapability({
+        model: task.model || task.model_id,
+        advertisedEfforts: task.advertised_efforts || task.model_advertised_efforts,
+        defaultEffort: task.model_reasoning_effort || task.default_effort
+    });
+    const modelReasoningEffort = modelEffortAtLeast(selected, modelCapability);
     return {
         schema_version: EFFORT_POLICY_VERSION,
         mission_id: task.mission_id || 'unassigned',
         task_id: task.task_id || 'TASK-001',
         selected_effort: selected,
+        model_reasoning_effort: modelReasoningEffort,
+        model_effort_capability: modelCapability,
         reason_codes: reasonCodes,
         risk_scores: risks,
         demotion_allowed_after: demotionPolicy(selected),

package/dist/core/fsx.js

@@ -5,7 +5,7 @@ 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 = '2.0.17';
+export const PACKAGE_VERSION = '2.0.18';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 export function nowIso() {

package/dist/core/hooks-runtime.js

@@ -3,7 +3,7 @@ import { projectRoot, readJson, readText, writeJsonAtomic, appendJsonl, readStdi
 import { looksInteractiveCommand, interactiveCommandReason } from './no-question-guard.js';
 import { missionDir, setCurrent, stateFile } from './mission.js';
 import { checkDbOperation, dbBlockReason, handleMadSksUserConfirmation } from './db-safety.js';
-import { readLatestPendingMadDbLifecycleHook, recordMadDbToolResult } from './mad-db/mad-db-result-lifecycle.js';
+import { maybeRecordMadDbToolResultFromToolUse } from './mad-db/mad-db-result-lifecycle.js';
 import { checkHarnessModification, harnessGuardBlockReason, isHarnessSourceProject } from './harness-guard.js';
 import { isMadSksRouteState } from './permission-gates.js';
 import { classifyMadSksShellCommand } from './mad-sks/write-guard.js';
@@ -163,6 +163,8 @@ function toolFailed(payload = {}) {
         if (Number.isFinite(n))
             return n !== 0;
     }
+    if (payload.isError === true || payload.tool_response?.isError === true || payload.toolResponse?.isError === true || payload.result?.isError === true)
+        return true;
     if (payload.success === false || payload.tool_response?.success === false || payload.toolResponse?.success === false || payload.result?.success === false)
         return true;
     if (payload.executed === false)
@@ -450,16 +452,11 @@ async function hookPostTool(root, state, payload, noQuestion) {
 async function recordMadDbPostToolLifecycle(root, state = {}, payload = {}) {
     if (!state?.mission_id)
         return null;
-    const hook = await readLatestPendingMadDbLifecycleHook(root, String(state.mission_id), payload);
-    if (!hook)
-        return null;
-    return recordMadDbToolResult({
+    return maybeRecordMadDbToolResultFromToolUse({
         root,
         missionId: String(state.mission_id),
-        hook,
-        ok: !toolFailed(payload),
-        rowCount: extractRowCount(payload),
-        error: toolFailed(payload) ? extractToolError(payload) : null
+        toolCallPayload: payload,
+        toolResult: payload
     });
 }
 function extractRowCount(payload = {}) {

package/dist/core/image/image-artifact-path-contract.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { nowIso, writeJsonAtomic } from '../fsx.js';
+import { imageDimensions } from '../wiki-image/image-hash.js';
+export async function buildImageArtifactPathContract(root, input) {
+    const images = [];
+    const blockers = [];
+    for (const [index, image] of input.images.entries()) {
+        const filePath = path.resolve(root, image.filePath || '');
+        const exists = await fileExists(filePath);
+        if (!exists)
+            blockers.push(`${image.kind}_file_path_missing:${image.id || index + 1}`);
+        const dims = exists ? await imageDimensions(filePath).catch(() => null) : null;
+        images.push({
+            id: image.id || `image-${index + 1}`,
+            kind: image.kind,
+            file_path: filePath,
+            relative_path: path.relative(root, filePath),
+            exists,
+            mime_type: mimeForPath(filePath),
+            width: dims?.width ?? null,
+            height: dims?.height ?? null,
+            model_visible_path: filePath,
+            followup_edit_hint: exists
+                ? `Use this saved local path for follow-up image edits: ${filePath}`
+                : 'Image file path missing; do not run visual QA until a real saved file path exists.'
+        });
+    }
+    if (images.some((image) => image.kind === 'generated_image' && !image.exists))
+        blockers.push('image_generated_file_path_missing');
+    return {
+        schema: 'sks.image-artifact-path-contract.v1',
+        mission_id: input.missionId,
+        generated_at: nowIso(),
+        images,
+        blockers: [...new Set(blockers)]
+    };
+}
+export async function writeImageArtifactPathContract(root, input) {
+    const contract = await buildImageArtifactPathContract(root, input);
+    const artifactPath = input.artifactPath || path.join(root, '.sneakoscope', 'missions', input.missionId, 'image-artifact-path-contract.json');
+    await writeJsonAtomic(artifactPath, contract);
+    return { contract, artifact_path: artifactPath };
+}
+export async function discoverImageArtifactsInDir(dir) {
+    const out = [];
+    await walk(dir, async (file) => {
+        if (!/\.(png|jpe?g|webp|gif)$/i.test(file))
+            return;
+        out.push({
+            id: path.basename(file).replace(/[^0-9A-Za-z._-]/g, '_'),
+            kind: /generated|gpt-image|callout/i.test(file) ? 'generated_image' : 'visual_qa_snapshot',
+            filePath: file
+        });
+    });
+    return out;
+}
+function mimeForPath(file) {
+    const ext = path.extname(file).toLowerCase();
+    if (ext === '.png')
+        return 'image/png';
+    if (ext === '.jpg' || ext === '.jpeg')
+        return 'image/jpeg';
+    if (ext === '.webp')
+        return 'image/webp';
+    if (ext === '.gif')
+        return 'image/gif';
+    return null;
+}
+async function fileExists(file) {
+    try {
+        const st = await fs.stat(file);
+        return st.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function walk(dir, visit) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (['node_modules', '.git', 'dist'].includes(entry.name))
+                continue;
+            await walk(full, visit);
+        }
+        else {
+            await visit(full);
+        }
+    }
+}
+//# sourceMappingURL=image-artifact-path-contract.js.map

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

@@ -7,6 +7,7 @@ import { detectImagegenCapability } from '../imagegen/imagegen-capability.js';
 import { validateGptImage2Request } from '../imagegen/gpt-image-2-request-validator.js';
 import { withResponsesRetry } from '../responses-retry-policy.js';
 import { discoverCodexAppGeneratedImage } from './codex-app-generated-image-discovery.js';
+import { writeImageArtifactPathContract } from '../image/image-artifact-path-contract.js';
 const DEFAULT_OPENAI_IMAGE_EDITS_ENDPOINT = 'https://api.openai.com/v1/images/edits';
 export function buildCalloutPrompt(sourceScreenId, context = {}) {
     return [
@@ -124,6 +125,7 @@ export function createCodexAppImagegenAdapter(opts = {}) {
                     real_generated: true
                 });
                 const outputSource = manualOutput ? 'manual_attach' : 'auto_discovered_generated_images';
+                const imageContract = await writeGeneratedImagePathContract(input, dest, 'codex_app_imagegen').catch(() => null);
                 await writeJsonAtomic(responseArtifact, {
                     schema: 'sks.image-ux-gpt-image-2-response.v1',
                     created_at: nowIso(),
@@ -135,6 +137,7 @@ export function createCodexAppImagegenAdapter(opts = {}) {
                     output_image_sha256: meta.sha256,
                     output_id: meta.output_id,
                     output_source: outputSource,
+                    image_artifact_path_contract: imageContract?.artifact_path || null,
                     discovered_from: discovery?.selected?.path || null,
                     discovery: discovery ? { candidates_considered: discovery.candidates_considered, since_ms: discovery.since_ms, max_age_ms: discovery.max_age_ms } : null,
                     local_only: true
@@ -149,6 +152,7 @@ export function createCodexAppImagegenAdapter(opts = {}) {
                     output_source: outputSource,
                     request_artifact: requestArtifact,
                     response_artifact: responseArtifact,
+                    image_artifact_path_contract: imageContract?.artifact_path || null,
                     latency_ms: null
                 };
             }
@@ -241,6 +245,7 @@ export function createFakeImagegenAdapter(opts = {}) {
                 real_generated: false,
                 mock: true
             });
+            const imageContract = await writeGeneratedImagePathContract(input, out, 'fake_imagegen_adapter').catch(() => null);
             await writeJsonAtomic(responseArtifact, {
                 schema: 'sks.image-ux-gpt-image-2-response.v1',
                 created_at: nowIso(),
@@ -251,6 +256,7 @@ export function createFakeImagegenAdapter(opts = {}) {
                 output_image_path: out,
                 output_image_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 },
                 latency_ms: Date.now() - started,
                 fake_adapter: true,
@@ -259,7 +265,7 @@ export function createFakeImagegenAdapter(opts = {}) {
                 mock: true,
                 local_only: true
             });
-            return { ok: true, status: 'generated', generated_image_path: out, output_id: meta.output_id, blocker: null, provider: 'fake_imagegen_adapter', request_artifact: requestArtifact, response_artifact: responseArtifact, latency_ms: Date.now() - started };
+            return { ok: true, status: 'generated', generated_image_path: out, output_id: meta.output_id, blocker: null, provider: 'fake_imagegen_adapter', request_artifact: requestArtifact, response_artifact: responseArtifact, image_artifact_path_contract: imageContract?.artifact_path || null, latency_ms: Date.now() - started };
         }
     };
 }
@@ -385,6 +391,7 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
                         output_id: generated.id || payload?.id || null,
                         real_generated: true
                     });
+                    const imageContract = await writeGeneratedImagePathContract(input, out, 'openai_responses_image_generation').catch(() => null);
                     await writeJsonAtomic(responseArtifact, {
                         schema: 'sks.image-ux-gpt-image-2-response.v1',
                         created_at: nowIso(),
@@ -397,12 +404,13 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
                         output_image_path: out,
                         output_image_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 },
                         latency_ms: Date.now() - started,
                         token_cost_metadata: payload?.usage || null,
                         local_only: true
                     });
-                    return { ok: true, status: 'generated', generated_image_path: out, output_id: meta.output_id, blocker: null, provider: 'openai_responses_image_generation', request_artifact: requestArtifact, response_artifact: responseArtifact, latency_ms: Date.now() - started };
+                    return { ok: true, status: 'generated', generated_image_path: out, output_id: meta.output_id, blocker: null, provider: 'openai_responses_image_generation', request_artifact: requestArtifact, response_artifact: responseArtifact, image_artifact_path_contract: imageContract?.artifact_path || null, latency_ms: Date.now() - started };
                 }
                 const sourceBytes = await fsp.readFile(sourcePath);
                 const qualityParam = imagegenQualityParam(opts);
@@ -440,6 +448,7 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
                     output_id: image?.id || payload?.id || null,
                     real_generated: true
                 });
+                const imageContract = await writeGeneratedImagePathContract(input, out, 'openai_images_api').catch(() => null);
                 await writeJsonAtomic(responseArtifact, {
                     schema: 'sks.image-ux-gpt-image-2-response.v1',
                     created_at: nowIso(),
@@ -451,12 +460,13 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
                     output_image_path: out,
                     output_image_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 },
                     latency_ms: Date.now() - started,
                     token_cost_metadata: payload?.usage || null,
                     local_only: true
                 });
-                return { ok: true, status: 'generated', generated_image_path: out, output_id: meta.output_id, blocker: null, provider: 'openai_images_api', request_artifact: requestArtifact, response_artifact: responseArtifact, latency_ms: Date.now() - started };
+                return { ok: true, status: 'generated', generated_image_path: out, output_id: meta.output_id, blocker: null, provider: 'openai_images_api', request_artifact: requestArtifact, response_artifact: responseArtifact, image_artifact_path_contract: imageContract?.artifact_path || null, latency_ms: Date.now() - started };
             }
             catch (err) {
                 const provider = useResponsesImageTool ? 'openai_responses_image_generation' : 'openai_images_api';
@@ -468,6 +478,17 @@ export function createOpenAIImagesApiAdapter(opts = {}) {
         }
     };
 }
+async function writeGeneratedImagePathContract(input, outputPath, provider) {
+    return writeImageArtifactPathContract(process.cwd(), {
+        missionId: input.mission_id || 'unassigned',
+        images: [{
+                id: `${provider}-${input.source_screen_id || 'screen'}`,
+                kind: 'generated_image',
+                filePath: outputPath
+            }],
+        artifactPath: path.join(input.output_dir, 'image-artifact-path-contract.json')
+    });
+}
 export async function generateGptImage2CalloutReview(input, opts = {}) {
     if (opts.fake === true || process.env.SKS_TEST_FAKE_IMAGEGEN === '1') {
         return createFakeImagegenAdapter(opts.fakeAdapter || {}).generateCalloutReview(input);