sneakoscope 3.1.4 → 3.1.5

package/dist/core/loops/loop-worker-runtime.js

@@ -43,7 +43,8 @@ async function runLoopWorkerNative(input) {
         ? buildLoopMakerPrompt({ plan: input.plan, node: input.node, worktreePath: input.worktree?.path || null })
         : buildLoopCheckerPrompt({ plan: input.plan, node: input.node, makerArtifacts: input.makerArtifacts || [] });
     const workerCount = effectiveLoopWorkerCount(input);
-    const workGraph = buildLoopNarutoWorkGraph(input, workerCount);
+    const executionProfile = await resolveCodexAppExecutionProfile({ root: input.root }).catch(() => null);
+    const workGraph = buildLoopNarutoWorkGraph(input, workerCount, executionProfile);
     // Root-cause-1 fix: keep the ORCHESTRATOR root on the MAIN repo (input.root), not the
     // loop worktree. All zellij/right-column/slot-telemetry state derives from the orchestrator
     // root, so anchoring it on input.root makes the SLOTS snapshot land under
@@ -52,7 +53,6 @@ async function runLoopWorkerNative(input) {
     // The loop worktree is still where workers cwd + write: it is threaded through the per-worker
     // `worktree` opt below, which launchWorker reads as ctx.opts.worktree -> workerCwd.
     const insideZellij = Boolean(process.env.SKS_ZELLIJ_SESSION_NAME || process.env.ZELLIJ);
-    const executionProfile = await resolveCodexAppExecutionProfile({ root: input.root }).catch(() => null);
     const visiblePaneCap = Math.min(resolveLoopVisiblePaneCap(workerCount), Math.max(1, workerCount));
     const zellijPlacementOpts = insideZellij ? {
         workerPlacement: 'zellij-pane',
@@ -99,9 +99,9 @@ async function runLoopWorkerNative(input) {
             fallback_reason: null
         } : null
     });
-    return normalizeNativeResult(input, orchestrator);
+    return normalizeNativeResult(input, orchestrator, executionProfile);
 }
-async function normalizeNativeResult(input, result) {
+async function normalizeNativeResult(input, result, executionProfile) {
     const artifacts = collectArtifactPaths(result);
     const changedFiles = stringArray(result?.changed_files || result?.proof?.changed_files || result?.results?.flatMap?.((row) => row?.changed_files || []));
     const blockers = [
@@ -124,7 +124,15 @@ async function normalizeNativeResult(input, result) {
         blockers: [...new Set(blockers)],
         runtime_proof_path: proofPath,
         worker_ids: stringArray(result?.results?.map?.((row) => row?.agent_id || row?.id)),
-        session_ids: stringArray(result?.results?.map?.((row) => row?.session_id))
+        session_ids: stringArray(result?.results?.map?.((row) => row?.session_id)),
+        ...(executionProfile ? {
+            codex_app_execution_profile: {
+                mode: executionProfile.mode,
+                agent_role_strategy: executionProfile.agent_role_strategy,
+                artifact_path: executionProfile.artifact_path,
+                agent_type_probe_artifact_path: executionProfile.agent_type_probe_artifact_path
+            }
+        } : {})
     };
     await writeJsonAtomic(proofPath, { ...normalized, native_result_summary: summarizeNativeResult(result), generated_at: nowIso() });
     return normalized;
@@ -189,7 +197,13 @@ async function runLoopWorkerFixture(input) {
         fixture_allowed_reason: fixturePolicy.allowed ? fixturePolicy.reason : null
     };
 }
-function buildLoopNarutoWorkGraph(input, workerCount) {
+function buildLoopNarutoWorkGraph(input, workerCount, executionProfile) {
+    const profilePayload = executionProfile ? {
+        mode: executionProfile.mode,
+        agent_role_strategy: executionProfile.agent_role_strategy,
+        artifact_path: executionProfile.artifact_path,
+        agent_type_probe_artifact_path: executionProfile.agent_type_probe_artifact_path
+    } : undefined;
     const workItems = Array.from({ length: Math.max(1, workerCount) }, (_, index) => {
         const id = `${input.node.loop_id}-${input.phase}-${index + 1}`;
         const writeAllowed = input.phase === 'maker';
@@ -218,7 +232,8 @@ function buildLoopNarutoWorkGraph(input, workerCount) {
                 mode: input.worktree?.path ? 'patch-envelope-only' : 'git-worktree',
                 required: input.node.worktree.required,
                 allocation_required: false
-            }
+            },
+            ...(profilePayload ? { codex_app_execution_profile: profilePayload } : {})
         };
     });
     return {
@@ -239,6 +254,7 @@ function buildLoopNarutoWorkGraph(input, workerCount) {
             worktree_root: null,
             fallback_reason: input.worktree?.path ? 'loop_worktree_already_allocated' : null
         },
+        ...(profilePayload ? { codex_app_execution_profile: profilePayload } : {}),
         blockers: [],
         ok: true
     };

package/dist/core/naruto/naruto-loop-worker-router.js

@@ -1,7 +1,9 @@
-export function routeNarutoLoopWorker(node, role) {
+export function routeNarutoLoopWorker(node, role, profile) {
     const domain = node.loop_id.replace(/^loop-/, '');
     const roles = roleLabels(domain);
     const gates = [...node.gates.triage, ...node.gates.local, ...node.gates.checker, ...node.gates.integration, ...node.gates.final];
+    const roleName = role === 'maker' ? roles.maker : roles.checker;
+    const strategy = profile?.agent_role_strategy || 'message-role';
     return {
         schema: 'sks.naruto-loop-worker-route.v1',
         loop_id: node.loop_id,
@@ -9,7 +11,10 @@ export function routeNarutoLoopWorker(node, role) {
         checker_role: roles.checker,
         prompt: [
             `loop purpose: ${node.purpose}`,
-            `role: ${role === 'maker' ? roles.maker : roles.checker}`,
+            `role: ${roleName}`,
+            `agent role strategy: ${strategy}`,
+            `agent_type: ${strategy === 'agent_type' ? roleName.replace(/\s+/g, '-') : '-'}`,
+            `message role prefix: ${strategy === 'message-role' ? `Role: ${roleName}.` : '-'}`,
             `owner files: ${node.owner_scope.files.join(', ') || '-'}`,
             `owner directories: ${node.owner_scope.directories.join(', ') || '-'}`,
             `gates: ${gates.join(', ') || '-'}`,
@@ -21,6 +26,10 @@ export function routeNarutoLoopWorker(node, role) {
         allowed_files: node.owner_scope.files,
         allowed_directories: node.owner_scope.directories,
         gates,
+        agent_role_strategy: strategy,
+        agent_type: strategy === 'agent_type' ? roleName.replace(/\s+/g, '-') : null,
+        message_role_prefix: strategy === 'message-role' ? `Role: ${roleName}.` : null,
+        execution_profile_artifact: profile?.artifact_path || null,
         mutation_outside_owner_scope_allowed: false
     };
 }

package/dist/core/qa-loop.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { exists, nowIso, readJson, readText, writeJsonAtomic, writeTextAtomic, PACKAGE_VERSION } from './fsx.js';
 import { CODEX_WEB_VERIFICATION_EVIDENCE_SOURCE, CODEX_WEB_VERIFICATION_POLICY, evidenceMentionsForbiddenBrowserAutomation, evidenceMentionsForbiddenWebComputerUseEvidence } from './routes.js';
 import { appendAgentLedgerEvent, initializeAgentCentralLedger } from './agents/agent-central-ledger.js';
+import { resolveCodexAppExecutionProfile } from './codex-app/codex-app-execution-profile.js';
 export const QA_LOOP_ROUTE = 'QALoop';
 const QA_REPORT_SUFFIX = 'qa-report.md';
 const UI_CHROME_EXTENSION_FIRST_ACK = 'use_codex_chrome_extension_first_no_computer_use_for_web_ui_or_mark_unverified';
@@ -320,6 +321,10 @@ export function defaultQaGate(contract = {}, opts = {}) {
         image_artifact_path_contract_present: false,
         image_artifact_path_contract_artifact: null,
         image_artifact_path_contract_blockers: [],
+        codex_app_execution_profile: opts.executionProfile ? compactExecutionProfile(opts.executionProfile) : null,
+        codex_app_execution_profile_artifact: opts.executionProfile ? 'qa-loop/execution-profile.json' : null,
+        codex_app_hooks_approval_required: opts.executionProfile?.hooks_approval_required === true,
+        codex_app_agent_role_strategy: opts.executionProfile?.agent_role_strategy || null,
         api_e2e_required: apiRequired,
         unsafe_external_side_effects: false,
         corrective_loop_enabled: corrective,
@@ -338,16 +343,21 @@ export async function writeQaLoopArtifacts(dir, mission, contract) {
     const a = contract.answers || {};
     const checklist = qaChecklist(a);
     const reportFile = qaReportFilename();
+    const root = missionRootFromDir(dir);
+    const executionProfile = root ? await resolveCodexAppExecutionProfile({ root }).catch(() => null) : null;
+    if (executionProfile)
+        await writeJsonAtomic(path.join(dir, 'qa-loop', 'execution-profile.json'), executionProfile).catch(() => undefined);
     await writeJsonAtomic(path.join(dir, 'qa-ledger.json'), {
         schema_version: 1,
         generated_at: nowIso(),
         mission_id: mission.id,
         qa_report_file: reportFile,
+        codex_app_execution_profile: executionProfile ? compactExecutionProfile(executionProfile) : null,
         target: { scope: a.QA_SCOPE, environment: a.TARGET_ENVIRONMENT, base_url: a.TARGET_BASE_URL, api_base_url: a.API_BASE_URL },
         safety: { mutation_policy: a.QA_MUTATION_POLICY, deployed_destructive_tests_allowed: 'never', credentials: 'temp_only_never_saved', ui_evidence: 'codex_chrome_extension_first_required_for_web_ui_e2e' },
         checklist
     });
-    await writeJsonAtomic(path.join(dir, 'qa-gate.json'), defaultQaGate(contract, { reportFile }));
+    await writeJsonAtomic(path.join(dir, 'qa-gate.json'), defaultQaGate(contract, { reportFile, executionProfile }));
     await writeTextAtomic(path.join(dir, reportFile), qaReportTemplate(mission, contract, checklist));
     return { checklist_count: checklist.length, report_file: reportFile };
 }
@@ -432,6 +442,10 @@ export async function writeMockQaResult(dir, mission, contract) {
         image_artifact_path_contract_present: previousGate.image_artifact_path_contract_present === true,
         image_artifact_path_contract_artifact: previousGate.image_artifact_path_contract_artifact || null,
         image_artifact_path_contract_blockers: previousGate.image_artifact_path_contract_blockers || [],
+        codex_app_execution_profile: previousGate.codex_app_execution_profile || null,
+        codex_app_execution_profile_artifact: previousGate.codex_app_execution_profile_artifact || null,
+        codex_app_hooks_approval_required: previousGate.codex_app_hooks_approval_required === true,
+        codex_app_agent_role_strategy: previousGate.codex_app_agent_role_strategy || null,
         blockers: previousGate.blockers || [],
         passed: !uiRequired,
         qa_report_written: true,
@@ -453,7 +467,7 @@ export async function writeMockQaResult(dir, mission, contract) {
     });
     return evaluateQaGate(dir);
 }
-export function buildQaLoopPrompt({ id, mission, contract, cycle, previous, reportFile, imagePathContract, appHandoff }) {
+export function buildQaLoopPrompt({ id, mission, contract, cycle, previous, reportFile, imagePathContract, appHandoff, executionProfile }) {
     const report = reportFile && isQaReportFilename(reportFile) ? reportFile : 'the date/version-prefixed report named by qa-gate.json.qa_report_file';
     const imageContractText = imagePathContract
         ? `\nIMAGE PATH CONTRACT:\n${JSON.stringify(imagePathContract, null, 2)}\nUse model_visible_path values for follow-up image edits; do not invent generated image paths.\n`
@@ -461,6 +475,9 @@ export function buildQaLoopPrompt({ id, mission, contract, cycle, previous, repo
     const appHandoffText = appHandoff
         ? `\nCODEX DESKTOP /app HANDOFF:\n${JSON.stringify(appHandoff, null, 2)}\nThis is desktop-app review status only and is not web UI evidence.\n`
         : '';
+    const executionProfileText = executionProfile
+        ? `\nCODEX APP EXECUTION PROFILE:\n${JSON.stringify(compactExecutionProfile(executionProfile), null, 2)}\nUse this routing profile for agent role strategy and app/headless assumptions.\n`
+        : '';
     return `SKS QA-LOOP
 MISSION: ${id}
 TASK: ${mission.prompt}
@@ -473,7 +490,7 @@ GATE: passed=false while unresolved_findings or unresolved_fixable_findings > 0,
 ARTIFACTS: update qa-ledger.json, ${report}, qa-gate.json, and qa-loop/cycle-${cycle}/.
 CONTRACT:
 ${JSON.stringify(contract, null, 2)}
-${imageContractText}${appHandoffText}
+${imageContractText}${appHandoffText}${executionProfileText}
 Previous tail:
 ${String(previous || '').slice(-2500)}
 `;
@@ -486,7 +503,8 @@ export async function qaStatus(dir) {
     const imagePathContract = await readJson(path.join(dir, 'qa-loop', 'image-artifact-path-contract.json'), null);
     const reportFile = qaReportFileFromGate(gate?.gate || gate || {}) || ledger?.qa_report_file || null;
     const report = reportFile && isQaReportFilename(reportFile) ? await readText(path.join(dir, reportFile), '') : '';
-    return { gate, checklist_count: ledger?.checklist?.length ?? null, report_file: reportFile, report_written: Boolean(report.trim()), desktop_app_handoff: appHandoff, desktop_app_confirmation: appConfirmation, desktop_review_complete: appConfirmation?.verdict === 'pass', image_path_contract: imagePathContract };
+    const executionProfile = await readJson(path.join(dir, 'qa-loop', 'execution-profile.json'), null);
+    return { gate, checklist_count: ledger?.checklist?.length ?? null, report_file: reportFile, report_written: Boolean(report.trim()), desktop_app_handoff: appHandoff, desktop_app_confirmation: appConfirmation, desktop_review_complete: appConfirmation?.verdict === 'pass', image_path_contract: imagePathContract, codex_app_execution_profile: executionProfile };
 }
 function qaChecklist(a) {
     const cases = [
@@ -504,6 +522,23 @@ function qaChecklist(a) {
     cases.push(['report.evidence', 'Record pass/fail/blocked/skipped with evidence.'], ['report.corrective_loop', 'Record fixes, rechecks, unresolved findings, deferred blockers.'], ['report.honest', 'Run Honest Mode.']);
     return cases.map(([id, title]) => ({ id, title, status: 'pending', evidence: [] }));
 }
+function missionRootFromDir(dir) {
+    const normalized = path.resolve(String(dir || ''));
+    const marker = `${path.sep}.sneakoscope${path.sep}missions${path.sep}`;
+    const idx = normalized.indexOf(marker);
+    return idx > 0 ? normalized.slice(0, idx) : null;
+}
+function compactExecutionProfile(profile) {
+    return profile ? {
+        mode: profile.mode || 'unknown',
+        agent_role_strategy: profile.agent_role_strategy || 'message-role',
+        hooks_approval_required: profile.hooks_approval_required === true,
+        hook_approval_state: profile.hook_approval_state || 'unknown',
+        app_handoff_ready: profile.app_handoff_ready === true,
+        plugin_mcp_inventory_ready: profile.plugin_mcp_inventory_ready === true,
+        artifact_path: profile.artifact_path || '.sneakoscope/reports/codex-app-execution-profile.json'
+    } : null;
+}
 function qaReportTemplate(mission, contract, checklist) {
     const a = contract.answers || {};
     return `# QA-LOOP Report\n\nMission: ${mission.id}\nTarget: ${a.TARGET_BASE_URL || 'unset'}\nScope: ${a.QA_SCOPE || 'unset'}\nEnvironment: ${a.TARGET_ENVIRONMENT || 'unset'}\n\n## Safety\n\n- Deployed destructive tests: never\n- Credentials: temp-only, never saved\n- UI evidence: ${CODEX_WEB_VERIFICATION_POLICY}\n\n## Checklist\n\n${checklist.map((item) => `- [ ] ${item.id}: ${item.title}`).join('\n')}\n\n## Findings\n\nTBD\n\n## Corrections And Rechecks\n\nTBD\n\n## Honest Mode\n\nTBD\n`;

package/dist/core/research/research-cycle-runner.js

@@ -63,6 +63,7 @@ export async function runResearchCycle(inputOrDir, legacyGraph = null, legacyOpt
         blockers: [...new Set(blockers)],
         stages: stageResults.map((stage) => stage.stage_id),
         stage_results: stageResults,
+        codex_app_execution_profile: input.plan?.codex_app_execution_profile || null,
         parallelism: {
             max_parallel_stages: maxParallel,
             max_observed_parallel: maxObservedParallel,

package/dist/core/research/research-stage-runner.js

@@ -91,7 +91,7 @@ async function runSourceShardStage(input, startedAt) {
         const validation = validateResearchSourceShardOutput(output);
         await writeJsonAtomic(path.join(input.dir, artifact), output);
         await writeTextAtomic(path.join(input.dir, 'research', `cycle-${input.cycle}`, 'source-notes', `${layer.id}.md`), `# Source shard: ${layer.label}\n\n${output.sources.map((source) => `- ${source.id}: ${source.title}`).join('\n')}\n`);
-        return baseResult(input, startedAt, 'source_shard', validation.ok ? 'passed' : 'blocked', [artifact, `research/cycle-${input.cycle}/source-notes/${layer.id}.md`], validation.blockers, { layer_id: layer.id, source_count: output.sources.length });
+        return baseResult(input, startedAt, 'source_shard', validation.ok ? 'passed' : 'blocked', [artifact, `research/cycle-${input.cycle}/source-notes/${layer.id}.md`], validation.blockers, { layer_id: layer.id, source_count: output.sources.length, source_tool_route: researchSourceToolRoute(input.plan) });
     }
     const codex = await runResearchCodexStage({
         root: input.root,
@@ -333,9 +333,16 @@ function baseResult(input, startedAt, stageKind, status, outputArtifacts, blocke
         backend: input.backend,
         worker_result_path: typeof metrics.worker_result_path === 'string' ? metrics.worker_result_path : null,
         blockers: [...new Set(blockers.map(String).filter(Boolean))],
-        metrics
+        metrics: {
+            ...metrics,
+            codex_app_execution_profile: input.plan?.codex_app_execution_profile || null,
+            source_tool_route: metrics.source_tool_route || researchSourceToolRoute(input.plan)
+        }
     };
 }
+function researchSourceToolRoute(plan) {
+    return plan?.web_research_policy?.source_tool_routing?.mode || (plan?.codex_app_execution_profile?.plugin_mcp_inventory_ready ? 'plugin-mcp-inventory-first' : 'codex-cli-or-web-fallback');
+}
 async function buildResearchGateSeed(dir, plan) {
     const sourceLedger = await readJson(path.join(dir, 'source-ledger.json'), null);
     const claimMatrix = await readJson(path.join(dir, 'claim-evidence-matrix.json'), null);

package/dist/core/research.js

@@ -17,6 +17,7 @@ import { writeResearchHandoffArtifacts } from './research/research-handoff.js';
 import { RESEARCH_WORK_GRAPH_ARTIFACT, writeResearchWorkGraph } from './research/research-work-graph.js';
 import { researchPromptContractText, validateResearchPromptContract } from './research/research-prompt-contract.js';
 import { buildRealisticResearchPaper, buildRealisticResearchReport } from './research/research-realistic-report.js';
+import { resolveCodexAppExecutionProfile } from './codex-app/codex-app-execution-profile.js';
 export const RESEARCH_PAPER_ARTIFACT = 'research-paper.md';
 export const RESEARCH_SOURCE_SKILL_ARTIFACT = 'research-source-skill.md';
 export const RESEARCH_GENIUS_SUMMARY_ARTIFACT = 'genius-opinion-summary.md';
@@ -252,6 +253,7 @@ export function createResearchPlan(prompt, opts = {}) {
     const createdAt = nowIso();
     const paperArtifact = researchPaperArtifactName(prompt, createdAt, opts);
     const nativeAgentPlan = researchNativeAgentPlan(prompt, { paperArtifact, missionId: opts.missionId });
+    const executionProfile = opts.executionProfile || null;
     return {
         schema_version: 1,
         mission_id: opts.missionId || null,
@@ -262,6 +264,7 @@ export function createResearchPlan(prompt, opts = {}) {
         paper_artifact: paperArtifact,
         quality_contract: DEFAULT_RESEARCH_QUALITY_CONTRACT,
         native_agent_plan: nativeAgentPlan,
+        codex_app_execution_profile: executionProfile ? compactExecutionProfile(executionProfile) : null,
         agent_sessions: nativeAgentPlan.personas,
         agent_batches: nativeAgentPlan.batches,
         autoresearch_cycle_policy: nativeAgentPlan.autoresearch_cycle_policy,
@@ -318,6 +321,12 @@ export function createResearchPlan(prompt, opts = {}) {
         web_research_policy: {
             mode: 'layered_source_retrieval_and_triangulation',
             requirement: 'Use every safely available public web/source route before synthesis, separated into source layers so the final claim is not dominated by one corpus or platform.',
+            source_tool_routing: {
+                mode: executionProfile?.plugin_mcp_inventory_ready ? 'plugin-mcp-inventory-first' : 'codex-cli-or-web-fallback',
+                plugin_mcp_inventory_ready: executionProfile?.plugin_mcp_inventory_ready === true,
+                execution_profile_artifact: executionProfile?.artifact_path || '.sneakoscope/reports/codex-app-execution-profile.json',
+                rule: 'Prefer verified plugin/MCP inventory when available; otherwise record source-tool blockers instead of assuming live search coverage.'
+            },
             query_sets: [
                 'first-principles and theory sources',
                 'plain-language explanations and empirical examples',
@@ -417,6 +426,9 @@ export function researchPlanMarkdown(plan) {
     lines.push(`Depth: ${plan.depth}`);
     lines.push(`Methodology: ${plan.methodology}`);
     lines.push(`Research paper: ${researchPaperArtifactForPlan(plan)}`);
+    if (plan.codex_app_execution_profile) {
+        lines.push(`Execution profile: ${plan.codex_app_execution_profile.mode}; agent role strategy ${plan.codex_app_execution_profile.agent_role_strategy}`);
+    }
     if (plan.execution_policy) {
         lines.push(`Execution: ${plan.execution_policy.normal_run}; default cycle timeout ${plan.execution_policy.default_cycle_timeout_minutes} minutes`);
         if (plan.execution_policy.default_max_cycles)
@@ -468,6 +480,8 @@ export function researchPlanMarkdown(plan) {
         lines.push('## Web Research Policy');
         lines.push(`Mode: ${plan.web_research_policy.mode}`);
         lines.push(`Requirement: ${plan.web_research_policy.requirement}`);
+        if (plan.web_research_policy.source_tool_routing)
+            lines.push(`Source tool routing: ${plan.web_research_policy.source_tool_routing.mode}`);
         for (const querySet of plan.web_research_policy.query_sets || [])
             lines.push(`- query set: ${querySet}`);
         if (plan.web_research_policy.skill_creator?.artifact)
@@ -537,7 +551,9 @@ export function countGeniusOpinionSummaries(text = '') {
     }).length;
 }
 export async function writeResearchPlan(dir, prompt, opts = {}) {
-    const plan = createResearchPlan(prompt, opts);
+    const root = opts.root || missionRootFromDir(String(dir || ''));
+    const executionProfile = opts.executionProfile || (root ? await resolveCodexAppExecutionProfile({ root }).catch(() => null) : null);
+    const plan = createResearchPlan(prompt, { ...opts, executionProfile });
     const noveltyLedger = {
         schema_version: 1,
         entries: [],
@@ -553,6 +569,8 @@ export async function writeResearchPlan(dir, prompt, opts = {}) {
     const experimentPlan = defaultExperimentPlan(plan);
     const replicationPack = defaultReplicationPack(plan);
     await writeJsonAtomic(path.join(dir, 'research-plan.json'), plan);
+    if (executionProfile)
+        await writeJsonAtomic(path.join(dir, 'research', 'execution-profile.json'), executionProfile).catch(() => undefined);
     await writeTextAtomic(path.join(dir, 'research-plan.md'), researchPlanMarkdown(plan));
     await writeTextAtomic(path.join(dir, RESEARCH_SOURCE_SKILL_ARTIFACT), researchSourceSkillMarkdown(plan));
     await writeResearchQualityContract(dir, plan.quality_contract);
@@ -575,6 +593,22 @@ export async function writeResearchPlan(dir, prompt, opts = {}) {
     await appendJsonlBounded(path.join(dir, 'events.jsonl'), { ts: nowIso(), type: 'research.plan.created', depth: plan.depth });
     return plan;
 }
+function missionRootFromDir(dir) {
+    const normalized = path.resolve(String(dir || ''));
+    const marker = `${path.sep}.sneakoscope${path.sep}missions${path.sep}`;
+    const idx = normalized.indexOf(marker);
+    return idx > 0 ? normalized.slice(0, idx) : null;
+}
+function compactExecutionProfile(profile) {
+    return profile ? {
+        mode: profile.mode || 'unknown',
+        agent_role_strategy: profile.agent_role_strategy || 'message-role',
+        hooks_approval_required: profile.hooks_approval_required === true,
+        hook_approval_state: profile.hook_approval_state || 'unknown',
+        plugin_mcp_inventory_ready: profile.plugin_mcp_inventory_ready === true,
+        artifact_path: profile.artifact_path || '.sneakoscope/reports/codex-app-execution-profile.json'
+    } : null;
+}
 export async function writeResearchNativeAgentLedger(dir, plan, opts = {}) {
     const missionId = opts.missionId || plan?.mission_id;
     if (!missionId)

package/dist/core/version.js

@@ -1,2 +1,2 @@
-export const PACKAGE_VERSION = '3.1.4';
+export const PACKAGE_VERSION = '3.1.5';
 //# sourceMappingURL=version.js.map

package/dist/core/zellij/homebrew-policy.js

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import readline from 'node:readline';
 export const HOMEBREW_INSTALL_COMMAND = '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"';
 export function resolveHomebrewInstallPolicy(input = {}) {

package/dist/core/zellij/zellij-self-heal-types.js

@@ -0,0 +1,45 @@
+import { nowIso } from '../fsx.js';
+export function isZellijSelfHealResult(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const row = value;
+    return row.schema === 'sks.zellij-self-heal.v1'
+        && typeof row.ok === 'boolean'
+        && typeof row.requested_by === 'string'
+        && typeof row.strategy === 'string'
+        && row.before !== null
+        && typeof row.before === 'object'
+        && row.after !== null
+        && typeof row.after === 'object'
+        && Array.isArray(row.blockers)
+        && Array.isArray(row.warnings);
+}
+export function normalizeZellijSelfHealResult(value) {
+    if (isZellijSelfHealResult(value)) {
+        return {
+            ...value,
+            dry_run: value.dry_run === true,
+            planned_mutations: Array.isArray(value.planned_mutations) ? value.planned_mutations : []
+        };
+    }
+    return {
+        schema: 'sks.zellij-self-heal.v1',
+        ok: false,
+        requested_by: 'setup',
+        fix_requested: false,
+        auto_approved: false,
+        install_homebrew_allowed: false,
+        dry_run: false,
+        planned_mutations: [],
+        before: { status: 'unknown', version: null, bin: null },
+        latest_version: null,
+        strategy: 'failed',
+        command: null,
+        after: { status: 'unknown', version: null, bin: null },
+        mutation_guard_artifact: null,
+        homebrew: { present: false, bin: null, install_attempted: false, install_allowed: false },
+        blockers: ['invalid_zellij_self_heal_result'],
+        warnings: [`normalized_at:${nowIso()}`]
+    };
+}
+//# sourceMappingURL=zellij-self-heal-types.js.map

package/dist/core/zellij/zellij-self-heal.js

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { ensureDir, nowIso, runProcess, writeJsonAtomic } from '../fsx.js';
@@ -12,6 +11,7 @@ export async function repairZellijForSks(input) {
     const root = path.resolve(input.root || process.cwd());
     const env = input.env || process.env;
     const autoApproved = input.autoApprove === true;
+    const dryRun = input.dryRun === true;
     const beforeReport = await capabilitySnapshot(root, env, 'before');
     const before = compactCapability(beforeReport);
     const latest = await latestZellijVersion(env);
@@ -41,6 +41,9 @@ export async function repairZellijForSks(input) {
     if (input.fixRequested !== true) {
         return manualResult(root, input, env, before, latest, brew, 'fix_not_requested');
     }
+    if (dryRun) {
+        return dryRunResult(root, input, env, before, latest, brew, mutationArtifact);
+    }
     if (!autoApproved && input.interactive !== true) {
         return input.allowHeadlessFallback === true
             ? headlessResult(root, input, before, latest, brew, 'noninteractive_without_auto_approval')
@@ -183,10 +186,10 @@ async function capabilitySnapshot(root, env, phase, fallbackVersion) {
         require_zellij: false,
         min_version: ZELLIJ_MIN_VERSION,
         version: null,
-        bin: null,
+        bin: 'zellij',
         command: ['zellij', '--version'],
         docs_evidence: [],
-        blockers: [`zellij_capability_check_failed:${tail(err?.message || String(err))}`],
+        blockers: [`zellij_capability_check_failed:${tail(errorMessage(err))}`],
         warnings: [],
         operator_actions: ['Resolve the Zellij capability check failure, then rerun `sks doctor --fix --yes`.']
     }));
@@ -261,7 +264,7 @@ async function runZellijBrew(root, env, brewBin, args, command) {
         env,
         timeoutMs: 180000,
         maxOutputBytes: 256 * 1024
-    }).catch((err) => ({ code: 1, stdout: '', stderr: err?.message || String(err) }));
+    }).catch((err) => ({ code: 1, stdout: '', stderr: errorMessage(err) }));
 }
 async function runHomebrewInstall(root, env) {
     if (env.SKS_ZELLIJ_SELF_HEAL_FAKE_RUN === '1') {
@@ -281,7 +284,7 @@ async function runHomebrewInstall(root, env) {
         env,
         timeoutMs: 600000,
         maxOutputBytes: 256 * 1024
-    }).catch((err) => ({ code: 1, stdout: '', stderr: err?.message || String(err) }));
+    }).catch((err) => ({ code: 1, stdout: '', stderr: errorMessage(err) }));
 }
 async function appendFakeBrewLog(env, args) {
     if (!env.SKS_FAKE_BREW_LOG)
@@ -289,6 +292,56 @@ async function appendFakeBrewLog(env, args) {
     await ensureDir(path.dirname(env.SKS_FAKE_BREW_LOG));
     await fs.appendFile(env.SKS_FAKE_BREW_LOG, `${args.join(' ')}\n`, 'utf8');
 }
+async function dryRunResult(root, input, env, before, latest, brew, mutationArtifact) {
+    const policy = !brew.present
+        ? resolveHomebrewInstallPolicy({
+            env,
+            installHomebrew: input.installHomebrew === true,
+            autoApprove: input.autoApprove === true,
+            interactiveAccepted: false
+        })
+        : null;
+    if (!brew.present && policy?.allowed !== true) {
+        return input.allowHeadlessFallback === true
+            ? headlessResult(root, input, before, latest, brew, policy?.blockers[0] || 'homebrew_missing')
+            : manualResult(root, input, env, before, latest, brew, policy?.blockers[0] || 'homebrew_missing');
+    }
+    const planned = [];
+    if (!brew.present) {
+        planned.push({
+            command: HOMEBREW_INSTALL_COMMAND,
+            reason: 'homebrew_missing_for_zellij_repair'
+        });
+    }
+    const install = before.status === 'missing';
+    const zellijCommand = install ? 'brew install zellij' : 'brew upgrade zellij';
+    planned.push({
+        command: zellijCommand,
+        reason: install ? 'zellij_missing' : 'zellij_too_old_or_stale'
+    });
+    const strategy = !brew.present ? 'brew-install-homebrew-then-zellij'
+        : install ? 'brew-install-zellij'
+            : 'brew-upgrade-zellij';
+    return persistSelfHeal(root, input.missionDir, {
+        schema: 'sks.zellij-self-heal.v1',
+        ok: true,
+        requested_by: input.requestedBy,
+        fix_requested: true,
+        auto_approved: input.autoApprove === true,
+        install_homebrew_allowed: policy?.allowed === true,
+        dry_run: true,
+        planned_mutations: planned,
+        before,
+        latest_version: latest,
+        strategy,
+        command: planned.map((row) => row.command).join(' && '),
+        after: before,
+        mutation_guard_artifact: `${mutationArtifact}#planned`,
+        homebrew: { present: brew.present, bin: brew.bin, install_attempted: false, install_allowed: policy?.allowed === true },
+        blockers: [],
+        warnings: ['dry_run_no_mutation_performed']
+    });
+}
 async function manualResult(root, input, env, before, latest, brew, reason) {
     const command = brew.present ? 'sks doctor --fix --yes' : 'sks doctor --fix --install-homebrew --yes';
     return persistSelfHeal(root, input.missionDir, {
@@ -329,10 +382,15 @@ async function headlessResult(root, input, before, latest, brew, reason) {
     });
 }
 async function persistSelfHeal(root, missionDir, result) {
-    await writeJsonAtomic(path.join(root, '.sneakoscope', 'reports', 'zellij-self-heal.json'), result).catch(() => undefined);
+    const normalized = {
+        ...result,
+        dry_run: result.dry_run === true,
+        planned_mutations: result.planned_mutations || []
+    };
+    await writeJsonAtomic(path.join(root, '.sneakoscope', 'reports', 'zellij-self-heal.json'), normalized).catch(() => undefined);
     if (missionDir)
-        await writeJsonAtomic(path.join(missionDir, 'zellij-self-heal.json'), result).catch(() => undefined);
-    return result;
+        await writeJsonAtomic(path.join(missionDir, 'zellij-self-heal.json'), normalized).catch(() => undefined);
+    return normalized;
 }
 async function askZellijRepairAllowed(question) {
     if (!(process.stdin.isTTY && process.stdout.isTTY))
@@ -347,6 +405,9 @@ async function askZellijRepairAllowed(question) {
         rl.close();
     }
 }
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 function tail(value, limit = 1000) {
     return String(value || '').replace(/\s+/g, ' ').trim().slice(-limit);
 }

package/dist/core/zellij/zellij-update.js

@@ -232,17 +232,25 @@ export async function maybePromptZellijUpdateForLaunch(args = [], opts = {}) {
                 interactive: mode === 'interactive-prompt',
                 installHomebrew: opts.installHomebrew === true || list.includes('--install-homebrew'),
                 allowHeadlessFallback: opts.allowHeadlessFallback === true,
+                dryRun: opts.dryRun === true || list.includes('--dry-run'),
                 missionDir: opts.missionDir || null,
                 env
             });
             if (repaired.strategy === 'headless-fallback')
                 console.log('Zellij repair: headless fallback selected (live_panes=false).');
+            else if (repaired.dry_run)
+                console.log(`Zellij repair: dry_run planned ${repaired.command || 'none'}`);
             else if (repaired.ok && repaired.command)
                 console.log(`Zellij repair: ${repaired.strategy} via ${repaired.command}`);
             else if (!repaired.ok)
                 console.log(`Zellij repair required. Run: ${repaired.command || notice.upgrade_command}`);
+            const repairedStatus = repaired.strategy === 'headless-fallback' ? 'headless_fallback'
+                : !repaired.ok || repaired.strategy === 'manual-required' ? 'repair_required'
+                    : repaired.strategy === 'brew-upgrade-zellij' ? 'upgraded'
+                        : repaired.strategy === 'none-current' ? 'noop'
+                            : 'installed';
             return {
-                status: repaired.ok ? (repaired.strategy === 'headless-fallback' ? 'missing' : 'installed') : 'manual_required',
+                status: repairedStatus,
                 current: repaired.after.version || repaired.before.version,
                 latest: repaired.latest_version,
                 command: repaired.command,