sneakoscope 2.0.17 → 3.0.0

package/dist/core/codex-plugins/codex-plugin-cache.js

@@ -0,0 +1,38 @@
+import path from 'node:path';
+import { readJson, writeJsonAtomic } from '../fsx.js';
+import { buildCodexPluginInventory } from './codex-plugin-json.js';
+export function codexPluginInventoryCachePath(root) {
+    return path.join(root, '.sneakoscope', 'cache', 'codex-plugin-inventory.json');
+}
+export async function readCodexPluginInventoryCache(root) {
+    const cache = await readJson(codexPluginInventoryCachePath(root), null);
+    return cache?.schema === 'sks.codex-plugin-inventory-cache.v1' ? cache : null;
+}
+export async function writeCodexPluginInventoryCache(root, inventory, ttlMs = defaultTtlMs()) {
+    const generatedAt = new Date();
+    const cache = {
+        schema: 'sks.codex-plugin-inventory-cache.v1',
+        generated_at: generatedAt.toISOString(),
+        expires_at: new Date(generatedAt.getTime() + ttlMs).toISOString(),
+        ttl_ms: ttlMs,
+        inventory
+    };
+    await writeJsonAtomic(codexPluginInventoryCachePath(root), cache);
+    return cache;
+}
+export async function getCodexPluginInventoryCached(root, opts = {}) {
+    const ttlMs = Math.max(1, Number(opts.ttlMs || defaultTtlMs()) || defaultTtlMs());
+    const cachePath = codexPluginInventoryCachePath(root);
+    const existing = opts.forceRefresh ? null : await readCodexPluginInventoryCache(root);
+    if (existing && Date.parse(existing.expires_at) > Date.now()) {
+        return { inventory: existing.inventory, cache_hit: true, cache_path: cachePath, cache: existing };
+    }
+    const inventory = await (opts.inventoryFactory || buildCodexPluginInventory)();
+    const cache = await writeCodexPluginInventoryCache(root, inventory, ttlMs);
+    return { inventory, cache_hit: false, cache_path: cachePath, cache };
+}
+function defaultTtlMs() {
+    const value = Number(process.env.SKS_CODEX_PLUGIN_CACHE_TTL_MS || 10 * 60 * 1000);
+    return Number.isFinite(value) && value > 0 ? value : 10 * 60 * 1000;
+}
+//# sourceMappingURL=codex-plugin-cache.js.map

package/dist/core/codex-plugins/codex-plugin-diff.js

@@ -0,0 +1,73 @@
+import path from 'node:path';
+import { writeJsonAtomic } from '../fsx.js';
+export function diffCodexPluginInventories(previous, current) {
+    const prev = pluginMap(previous);
+    const next = pluginMap(current);
+    const added = [...next.keys()].filter((id) => !prev.has(id)).sort();
+    const removed = [...prev.keys()].filter((id) => !next.has(id)).sort();
+    const shared = [...next.keys()].filter((id) => prev.has(id));
+    const changedRemote = [];
+    const changedTemplates = [];
+    const changedPrompts = [];
+    const changedMetadata = [];
+    for (const id of shared) {
+        const before = prev.get(id);
+        const after = next.get(id);
+        if (!sameJson(normalizePluginMetadata(before), normalizePluginMetadata(after)))
+            changedMetadata.push(id);
+        if (!sameJson(normalizeRemoteServers(before?.remote_mcp_servers), normalizeRemoteServers(after?.remote_mcp_servers)))
+            changedRemote.push(id);
+        if (!sameJson(sorted(before?.unavailable_app_templates), sorted(after?.unavailable_app_templates)))
+            changedTemplates.push(id);
+        if (!sameJson(sorted(before?.default_prompts), sorted(after?.default_prompts)))
+            changedPrompts.push(id);
+    }
+    const changedCount = added.length + removed.length + changedMetadata.length + changedRemote.length + changedTemplates.length + changedPrompts.length;
+    return {
+        schema: 'sks.codex-plugin-inventory-diff.v1',
+        generated_at: new Date().toISOString(),
+        ok: true,
+        added_plugins: added,
+        removed_plugins: removed,
+        changed_remote_mcp_servers: changedRemote.sort(),
+        changed_unavailable_app_templates: changedTemplates.sort(),
+        changed_default_prompts: changedPrompts.sort(),
+        changed_plugin_metadata: changedMetadata.sort(),
+        changed_count: changedCount
+    };
+}
+export async function writeCodexPluginInventoryDiff(root, previous, current) {
+    const diff = diffCodexPluginInventories(previous, current);
+    const artifact = path.join(root, '.sneakoscope', 'codex-plugin-inventory.diff.json');
+    await writeJsonAtomic(artifact, diff);
+    return { diff, artifact };
+}
+function pluginMap(inventory) {
+    const map = new Map();
+    for (const plugin of inventory?.plugins || [])
+        map.set(String(plugin.id || plugin.name), plugin);
+    return map;
+}
+function normalizeRemoteServers(rows) {
+    return (rows || []).map((row) => ({
+        name: row.name,
+        url: row.url,
+        auth_type: row.auth_type
+    })).sort((a, b) => `${a.name}:${a.url}:${a.auth_type}`.localeCompare(`${b.name}:${b.url}:${b.auth_type}`));
+}
+function normalizePluginMetadata(row) {
+    return {
+        id: row?.id || null,
+        name: row?.name || null,
+        source: row?.source || null,
+        installed: row?.installed === true,
+        enabled: row?.enabled === true
+    };
+}
+function sorted(rows) {
+    return [...(rows || [])].map(String).sort();
+}
+function sameJson(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+//# sourceMappingURL=codex-plugin-diff.js.map

package/dist/core/codex-plugins/codex-plugin-json.js

@@ -0,0 +1,176 @@
+import path from 'node:path';
+import { findCodexBinary } from '../codex-adapter.js';
+import { detectCodex0138Capability } from '../codex-control/codex-0138-capability.js';
+import { nowIso, runProcess, writeJsonAtomic } from '../fsx.js';
+export async function runCodexPluginListJson() {
+    if (process.env.SKS_CODEX_PLUGIN_JSON_FAKE === '1')
+        return fakePluginList();
+    const bin = await findCodexBinary();
+    if (!bin)
+        return { plugins: [], blockers: ['codex_cli_missing'] };
+    return runCodexJson(bin, ['plugin', 'list', '--json']);
+}
+export async function runCodexPluginDetailJson(pluginId) {
+    if (process.env.SKS_CODEX_PLUGIN_JSON_FAKE === '1')
+        return fakePluginDetail(pluginId);
+    const bin = await findCodexBinary();
+    if (!bin)
+        return { blockers: ['codex_cli_missing'] };
+    return runCodexJson(bin, ['plugin', 'detail', pluginId, '--json']);
+}
+export async function buildCodexPluginInventory() {
+    const started = Date.now();
+    const capability = await detectCodex0138Capability();
+    const listJson = await runCodexPluginListJson();
+    const summaries = normalizePluginList(listJson);
+    const concurrency = Math.max(1, Number(process.env.SKS_CODEX_PLUGIN_DETAIL_CONCURRENCY || 6) || 6);
+    let failed = 0;
+    const plugins = await mapWithConcurrency(summaries, concurrency, async (summary) => {
+        const detail = await runCodexPluginDetailJson(summary.id || summary.name).catch((err) => ({ error: err?.message || String(err) }));
+        if (detail?.error || normalizeList(detail?.blockers).length > 0)
+            failed += 1;
+        return normalizePlugin(summary, detail);
+    });
+    const blockers = [
+        ...(capability.supports_plugin_json ? [] : ['codex_0_138_plugin_json_unavailable']),
+        ...normalizeList(listJson?.blockers)
+    ];
+    return {
+        schema: 'sks.codex-plugin-inventory.v1',
+        generated_at: nowIso(),
+        codex_0138_capability: capability,
+        fetch_concurrency: concurrency,
+        detail_fetch_count: summaries.length,
+        detail_fetch_failed_count: failed,
+        duration_ms: Date.now() - started,
+        plugins,
+        marketplace_available: plugins.some((plugin) => plugin.source === 'marketplace' || plugin.source === 'remote') || Boolean(listJson?.marketplace_available || listJson?.marketplaceAvailable),
+        blockers
+    };
+}
+export async function mapWithConcurrency(items, concurrency, fn) {
+    const limit = Math.max(1, Math.floor(concurrency || 1));
+    const results = new Array(items.length);
+    let next = 0;
+    async function worker() {
+        while (next < items.length) {
+            const index = next;
+            next += 1;
+            results[index] = await fn(items[index]);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, items.length || 1) }, () => worker()));
+    return results;
+}
+export async function writeCodexPluginInventoryArtifacts(root, inventory = null) {
+    const report = inventory || await buildCodexPluginInventory();
+    const artifact = path.join(root, '.sneakoscope', 'codex-plugin-inventory.json');
+    await writeJsonAtomic(artifact, report);
+    return { report, artifact };
+}
+export function pluginAppTemplatePolicy(inventory) {
+    const unavailable = inventory.plugins.flatMap((plugin) => plugin.unavailable_app_templates.map((template) => ({
+        plugin: plugin.id,
+        template
+    })));
+    return {
+        schema: 'sks.codex-plugin-app-template-policy.v1',
+        ok: true,
+        unavailable_app_templates: unavailable,
+        qa_loop_app_handoff_recommended: unavailable.length > 0,
+        doctor_warnings: unavailable.map((row) => `plugin_app_template_unavailable:${row.plugin}`)
+    };
+}
+async function runCodexJson(bin, args) {
+    const result = await runProcess(bin, args, { timeoutMs: 20_000, maxOutputBytes: 256 * 1024 }).catch((err) => ({
+        code: 1,
+        stdout: '',
+        stderr: err?.message || String(err)
+    }));
+    const text = `${result.stdout || ''}${result.stderr || ''}`.trim();
+    try {
+        return text ? JSON.parse(text) : {};
+    }
+    catch {
+        return { raw_text: text, blockers: [`codex_plugin_json_parse_failed:${args.join(' ')}`] };
+    }
+}
+function normalizePluginList(value) {
+    if (Array.isArray(value))
+        return value;
+    for (const key of ['plugins', 'installed_plugins', 'installedPlugins', 'items']) {
+        if (Array.isArray(value?.[key]))
+            return value[key];
+    }
+    return [];
+}
+function normalizePlugin(summary, detail) {
+    const raw = { summary, detail };
+    const id = String(detail?.id || summary?.id || summary?.plugin_id || summary?.name || 'unknown');
+    const name = String(detail?.name || summary?.name || id);
+    const sourceText = String(detail?.source || detail?.marketplaceSource || summary?.source || summary?.marketplaceSource || '').toLowerCase();
+    const source = sourceText.includes('marketplace') ? 'marketplace'
+        : sourceText.includes('remote') ? 'remote'
+            : sourceText.includes('local') ? 'local'
+                : 'unknown';
+    return {
+        id,
+        name,
+        source,
+        installed: boolish(detail?.installed ?? summary?.installed, true),
+        enabled: boolish(detail?.enabled ?? summary?.enabled, true),
+        default_prompts: normalizeList(detail?.default_prompts || detail?.defaultPrompts || detail?.prompts),
+        remote_mcp_servers: normalizeMcpServers(detail?.remote_mcp_servers || detail?.remoteMcpServers || detail?.mcp_servers || detail?.mcpServers),
+        unavailable_app_templates: normalizeList(detail?.unavailable_app_templates || detail?.unavailableAppTemplates || detail?.app_templates_unavailable),
+        raw
+    };
+}
+function normalizeMcpServers(value) {
+    const rows = Array.isArray(value) ? value : value && typeof value === 'object' ? Object.entries(value).map(([name, row]) => ({ name, ...(row || {}) })) : [];
+    return rows.map((row, index) => ({
+        name: String(row?.name || row?.id || `remote-mcp-${index + 1}`),
+        url: stringOrNull(row?.url || row?.endpoint),
+        auth_type: stringOrNull(row?.auth_type || row?.authType || row?.auth)
+    }));
+}
+function normalizeList(value) {
+    return Array.isArray(value) ? value.filter(Boolean).map(String) : value ? [String(value)] : [];
+}
+function stringOrNull(value) {
+    const text = String(value || '').trim();
+    return text ? text : null;
+}
+function boolish(value, fallback = false) {
+    if (value === true || value === 'true')
+        return true;
+    if (value === false || value === 'false')
+        return false;
+    return fallback;
+}
+function fakePluginList() {
+    const count = Math.max(1, Number(process.env.SKS_CODEX_PLUGIN_JSON_FAKE_COUNT || 1) || 1);
+    return {
+        marketplace_available: true,
+        plugins: Array.from({ length: count }, (_, index) => ({
+            id: 'fixture-plugin',
+            name: index === 0 ? 'Fixture Plugin' : `Fixture Plugin ${index + 1}`,
+            ...(index === 0 ? {} : { id: `fixture-plugin-${index + 1}` }),
+            source: 'marketplace',
+            installed: true,
+            enabled: true
+        }))
+    };
+}
+function fakePluginDetail(pluginId) {
+    return {
+        id: pluginId,
+        name: pluginId,
+        source: 'marketplace',
+        installed: true,
+        enabled: true,
+        default_prompts: ['Use the fixture plugin safely.'],
+        remote_mcp_servers: [{ name: 'fixture-db-docs', url: 'https://mcp.example.test', auth_type: 'oauth' }],
+        unavailable_app_templates: ['fixture-desktop-template']
+    };
+}
+//# sourceMappingURL=codex-plugin-json.js.map

package/dist/core/commands/mad-sks-command.js

@@ -20,6 +20,7 @@ import { runCodexLaunchPreflight } from '../preflight/parallel-preflight-engine.
 import { diffCodexAppUiSnapshots, writeCodexAppUiSnapshot } from '../codex-app/codex-app-ui-state-snapshot.js';
 import { checkSksUpdateNotice } from '../update/update-notice.js';
 import { createMadDbCapability, MAD_DB_ACK } from '../mad-db/mad-db-capability.js';
+import { writeCodex0138CapabilityArtifacts } from '../codex-control/codex-0138-capability.js';
 export async function madHighCommand(args = [], deps = {}) {
     const subcommand = firstSubcommand(args);
     if (subcommand)
@@ -36,6 +37,10 @@ export async function madHighCommand(args = [], deps = {}) {
         process.exitCode = 1;
         return;
     }
+    // Zellij is checked the same way Codex is, but it stays NON-blocking: a
+    // failed or skipped zellij upgrade never prevents the MAD launch.
+    const zellijUpdate = deps.maybePromptZellijUpdateForLaunch ? await deps.maybePromptZellijUpdateForLaunch(args, { label: 'MAD launch' }).catch(() => ({ status: 'error' })) : { status: 'skipped' };
+    void zellijUpdate;
     const depStatus = deps.ensureMadLaunchDependencies ? await deps.ensureMadLaunchDependencies(args) : { ready: true, actions: [] };
     if (!depStatus.ready) {
         console.error('SKS MAD launch blocked by missing dependencies.');
@@ -379,6 +384,7 @@ async function activateMadZellijPermissionState(cwd = process.cwd(), args = [])
     const has = (scope) => allowedScopes.has(scope);
     const dbWriteAllowed = has('db_write');
     const { id, dir } = await createMission(root, { mode: 'mad-sks', prompt: 'sks --mad Zellij scoped high-power maintenance session' });
+    await writeCodex0138CapabilityArtifacts(root, { missionId: id }).catch(() => null);
     const protectedCore = resolveProtectedCore({ packageRoot: packageRoot(), targetRoot: cwd });
     // The interactive launch 'before' snapshot is only persisted (env + policy json)
     // and is never compared against an 'after' snapshot during the session, so the
@@ -564,6 +570,7 @@ function codexLbImmediateLaunchOpts(args = [], lb = {}, opts = {}) {
 }
 export async function madSksFixture(root) {
     const { id, dir } = await createMission(root, { mode: 'mad-sks', prompt: '$MAD-SKS fixture permission gate' });
+    await writeCodex0138CapabilityArtifacts(root, { missionId: id }).catch(() => null);
     const gate = { schema_version: 1, passed: true, mad_sks_permission_active: true, permissions_deactivated: true, catastrophic_safety_guard_active: true, permission_profile: permissionGateSummary(), fixture: true };
     await writeJsonAtomic(path.join(dir, 'mad-sks-gate.json'), gate);
     return { mission_id: id, dir, gate };
@@ -738,6 +745,7 @@ async function materializeMadSksRun(root, targetRoot, permission, userIntent, js
     if (!(await exists(path.join(root, '.sneakoscope'))))
         await initProject(root, {});
     const { id, dir } = await createMission(root, { mode: 'mad-sks', prompt: userIntent });
+    await writeCodex0138CapabilityArtifacts(root, { missionId: id }).catch(() => null);
     const before = await snapshotProtectedCore(packageRoot(), 'before');
     const authorization = opts.authorizationManifest || createMadSksAuthorizationManifest({ permission, userIntent });
     const authorizationPath = opts.authorizationManifestPath || path.join(dir, 'mad-sks-authorization.json');

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

@@ -7,6 +7,7 @@ import { buildNarutoCloneRoster, systemSafeNarutoConcurrency } from '../agents/a
 import { DEFAULT_NARUTO_CLONES, MAX_NARUTO_AGENT_COUNT } from '../agents/agent-schema.js';
 import { resolveOllamaWorkerConfig } from '../agents/ollama-worker-config.js';
 import { attachZellijSessionInteractive, launchZellijLayout } from '../zellij/zellij-launcher.js';
+import { maybePromptZellijUpdateForLaunch } from '../zellij/zellij-update.js';
 import { buildNarutoWorkGraph } from '../naruto/naruto-work-graph.js';
 import { buildNarutoRoleDistribution } from '../naruto/naruto-role-policy.js';
 import { decideNarutoConcurrency } from '../naruto/naruto-concurrency-governor.js';
@@ -15,11 +16,13 @@ import { collectActualNarutoWorker, spawnActualNarutoWorker } from '../naruto/na
 import { allocateNarutoTasksToWorkers } from '../naruto/naruto-allocation-policy.js';
 import { rebalanceNarutoReadyWork } from '../naruto/naruto-rebalance-policy.js';
 import { buildNarutoVerificationDag } from '../naruto/naruto-verification-dag.js';
+import { evaluateNarutoFinalizer } from '../naruto/naruto-finalizer.js';
 import { buildNarutoGptFinalPack } from '../naruto/naruto-gpt-final-pack.js';
 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).
@@ -40,6 +43,12 @@ export async function narutoCommand(commandOrArgs = 'naruto', maybeArgs = []) {
         return narutoWorkers(parsed);
     if (parsed.action === 'proof')
         return narutoProof(parsed);
+    // Like the Codex CLI update prompt: check the installed zellij version and
+    // offer an upgrade to the latest stable release before the live session
+    // opens. Never blocks the run.
+    if (!parsed.json && !parsed.mock && !parsed.noOpenZellij) {
+        await maybePromptZellijUpdateForLaunch(args, { label: '$Naruto launch' }).catch(() => undefined);
+    }
     return narutoRun(parsed);
 }
 async function narutoRun(parsed) {
@@ -73,6 +82,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;
@@ -297,6 +307,10 @@ async function narutoRun(parsed) {
         console.log('  parallelism mode: ' + parsed.parallelism);
         if (activeSlots < roster.agent_count)
             console.log('  cap reasons: ' + (governor.reasons.join(', ') || 'host safety cap'));
+        // Backpressure used to throttle silently (50% when throttled, 25% when
+        // saturated); always tell the operator when host pressure reduced workers.
+        if (governor.backpressure !== 'normal')
+            console.log('  backpressure: ' + governor.backpressure + ' — host resource pressure reduced active workers (memory/cpu/fd/disk thresholds)');
         if (parsed.parallelism !== 'safe' && activeSlots < 10)
             console.log('  warning: active workers below 10 in non-safe mode');
     }
@@ -382,7 +396,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,
@@ -416,6 +430,18 @@ async function narutoRun(parsed) {
     });
     const clones = result.roster?.agent_count ?? roster.agent_count;
     const localWorkerSummary = summarizeNarutoLocalWorkerResult(localWorker, result);
+    // Finalizer policy: when local LLM workers contributed patches, the GPT
+    // final arbiter must have accepted before patches are considered final.
+    const finalizer = evaluateNarutoFinalizer({
+        localParticipated: Number(localWorkerSummary?.selected_worker_count || 0) > 0,
+        gptFinalStatus: result.proof?.gpt_final_status || null,
+        applyPatches: writeCapable
+    });
+    await writeJsonAtomic(path.join(mission.dir, 'naruto-finalizer.json'), {
+        ...finalizer,
+        generated_at: nowIso(),
+        mission_id: mission.id
+    });
     const summary = {
         schema: NARUTO_RESULT_SCHEMA,
         ok: result.ok === true,
@@ -475,6 +501,7 @@ async function narutoRun(parsed) {
             passed: parallelRuntime.passed
         } : null,
         local_worker: localWorkerSummary,
+        finalizer,
         proof: result.proof?.status || 'missing',
         run: compactNarutoRunResult(result),
         zellij: null
@@ -487,6 +514,8 @@ async function narutoRun(parsed) {
         console.log('Backend: ' + result.backend);
         console.log('Roles: ' + roleDistribution.entries.map((entry) => `${entry.role}:${entry.count}`).join(', '));
         console.log('Proof: ' + summary.proof);
+        if (!finalizer.ok)
+            console.log('Finalizer: blocked — ' + finalizer.blockers.join(', '));
         if (summary.parallel_runtime) {
             console.log('$Naruto parallel proof:');
             console.log('  max active workers: ' + summary.parallel_runtime.max_observed_active_workers);

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

@@ -13,9 +13,17 @@ 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 { writeCodexModelEffortCapabilityArtifact } from '../codex-control/codex-model-capabilities.js';
+import { discoverImageArtifactsInDir, writeImageArtifactPathContract } from '../image/image-artifact-path-contract.js';
+import { pluginAppTemplatePolicy } from '../codex-plugins/codex-plugin-json.js';
+import { confirmQaLoopAppHandoff } from '../qa-loop/qa-loop-app-handoff-confirmation.js';
 import fsp from 'node:fs/promises';
 export async function qaLoopCommand(sub, args = []) {
-    const known = new Set(['prepare', 'answer', 'run', 'status', 'help', '--help', '-h']);
+    const known = new Set(['prepare', 'answer', 'run', 'status', 'app-confirm', 'help', '--help', '-h']);
     const action = known.has(sub) ? sub : 'prepare';
     const actionArgs = action === 'prepare' && sub && !known.has(sub) ? [sub, ...args] : args;
     if (action === 'prepare')
@@ -26,13 +34,16 @@ export async function qaLoopCommand(sub, args = []) {
         return qaLoopRun(actionArgs);
     if (action === 'status')
         return qaLoopStatus(actionArgs);
+    if (action === 'app-confirm')
+        return qaLoopAppConfirm(actionArgs);
     console.log(`SKS QA-LOOP
 
 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] [--app-handoff-launch] [--app-handoff-artifact-only]
+  sks qa-loop app-confirm <mission-id|latest> --verdict pass|fail --notes "..."
+  sks qa-loop status <mission-id|latest> [--desktop]
 `);
 }
 function qaRoute() {
@@ -136,6 +147,101 @@ 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 effortCapabilityArtifact = await writeCodexModelEffortCapabilityArtifact(root, { missionId: id }).catch((err) => ({ error: err?.message || String(err), capability: null }));
+    const effortEscalation = selectQaLoopEscalatedEffort({
+        failureCount: Number(qaGate.safe_fix_attempts || qaGate.failure_count || 0),
+        currentEffort: String(profile || 'high').replace(/^sks-(?:logic|agent)-/, '').replace(/-fast$/, '') || 'high',
+        capability: effortCapabilityArtifact?.capability || undefined
+    });
+    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 launchMode = flag(args, '--app-handoff-launch') || process.env.SKS_QA_LOOP_APP_HANDOFF_LAUNCH === '1'
+        ? 'attempt-launch'
+        : 'artifact-only';
+    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',
+            launch_mode: flag(args, '--app-handoff-artifact-only') ? 'artifact-only' : launchMode
+        }).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,
+            launch_attempt: null
+        }))
+        : 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_confirmed: latestGate.desktop_app_handoff_confirmed === true,
+            desktop_app_handoff_verdict: latestGate.desktop_app_handoff_verdict || null,
+            desktop_app_handoff_launch_attempt: appHandoff ? appHandoff.launch_attempt || null : null,
+            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'] : []),
+                ...(appHandoffRequired && latestGate.desktop_app_handoff_confirmed !== true ? ['desktop_app_handoff_confirmation_missing'] : []),
+                ...(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 +343,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 +382,11 @@ 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);
+    const desktopConfirmation = await readJson(path.join(dir, 'qa-loop', 'app-handoff-confirmation.json'), null);
+    const desktopReviewComplete = desktopConfirmation?.verdict === 'pass';
     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, desktop_app_confirmation: desktopConfirmation, desktop_review_complete: desktopReviewComplete, 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 +395,38 @@ 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'}`);
+        console.log(`  launch:       ${desktop?.launch_attempt?.attempted ? desktop?.launch_attempt?.launched ? 'launched' : 'attempted_fallback' : 'not_attempted'}`);
+        console.log(`  confirmation: ${desktopConfirmation?.verdict || 'missing'}`);
+        console.log(`  complete:     ${desktopReviewComplete ? 'yes' : 'no'}`);
+        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 qaLoopAppConfirm(args) {
+    const root = await sksRoot();
+    const id = await resolveMissionId(root, args[0]);
+    const verdict = String(readFlagValue(args, '--verdict', '') || '').trim();
+    const notes = String(readFlagValue(args, '--notes', '') || '');
+    if (!id || !['pass', 'fail'].includes(verdict))
+        throw new Error('Usage: sks qa-loop app-confirm <mission-id|latest> --verdict pass|fail --notes "..."');
+    const result = await confirmQaLoopAppHandoff(root, { missionId: id, verdict: verdict, notes });
+    const evaluated = await evaluateQaGate(path.join(root, '.sneakoscope', 'missions', id));
+    if (flag(args, '--json'))
+        return console.log(JSON.stringify({ schema: 'sks.qa-loop-app-confirm.v1', ok: verdict === 'pass', mission_id: id, confirmation: result.confirmation, artifact_path: result.artifact_path, gate: result.gate, evaluated }, null, 2));
+    console.log(`QA-LOOP Desktop app handoff confirmation recorded: ${id} (${verdict})`);
+    console.log(path.relative(root, result.artifact_path));
+}
+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