sneakoscope 3.1.1 → 3.1.2

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

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { printJson } from '../../cli/output.js';
 import { createMission, findLatestMission, loadMission, setCurrent } from '../mission.js';
 import { readJson, sksRoot } from '../fsx.js';
-import { loopLatestCheckpointPath, loopPlanPath, loopProofPath, loopRoot } from '../loops/loop-artifacts.js';
+import { loopActiveWorkerHandlesPath, loopIntegrationMergePath, loopLatestCheckpointPath, loopPlanPath, loopProofPath, loopRoot, loopSideEffectReportPath } from '../loops/loop-artifacts.js';
 import { finalizeLoopGraph } from '../loops/loop-finalizer.js';
 import { readLoopGraphProof } from '../loops/loop-observability.js';
 import { planLoopsFromRequest } from '../loops/loop-planner.js';
@@ -83,7 +83,10 @@ async function loopStatus(args) {
     const states = await Promise.all((plan?.graph.nodes || []).map((node) => readJson(path.join(loopRoot(root, missionId), node.loop_id, 'loop-state.json'), null)));
     const proofs = await Promise.all((plan?.graph.nodes || []).map((node) => readJson(loopProofPath(root, missionId, node.loop_id), null)));
     const checkpoints = await Promise.all((plan?.graph.nodes || []).map((node) => readJson(loopLatestCheckpointPath(root, missionId, node.loop_id), null)));
-    const result = { schema: 'sks.loop-status-command.v1', mission_id: missionId, plan_ok: Boolean(plan && plan.blockers.length === 0), graph: proof, states, proofs, checkpoints };
+    const activeWorkerHandles = await readJsonl(loopActiveWorkerHandlesPath(root, missionId));
+    const merge = await readJson(loopIntegrationMergePath(root, missionId), null);
+    const sideEffects = await readJson(loopSideEffectReportPath(root, missionId), null);
+    const result = { schema: 'sks.loop-status-command.v1', mission_id: missionId, plan_ok: Boolean(plan && plan.blockers.length === 0), graph: proof, states, proofs, checkpoints, active_worker_handles: activeWorkerHandles, merge, side_effects: sideEffects };
     if (flag(args, '--json'))
         return printJson(result);
     console.log(`Loop status: ${missionId}`);
@@ -95,8 +98,16 @@ async function loopStatus(args) {
         const gates = nodeProof?.gate_result ? `${nodeProof.gate_result.passed_gates.length}/${nodeProof.gate_result.selected_gates.length}` : '-';
         const worktree = nodeProof?.worktree?.id || state.acting_on?.worktree_id || '-';
         const resumable = checkpoint?.resumable ? `resumable:${checkpoint.phase}` : 'resumable:-';
-        console.log(`  ${loopId.padEnd(18)} ${String(state.status).padEnd(10)} backend ${String(backend).padEnd(24)} gates ${gates.padEnd(5)} worktree ${String(worktree).padEnd(18)} ${resumable}`);
+        const active = activeWorkerHandles.filter((row) => row.loop_id === loopId && row.status === 'running').length;
+        const mergeStatus = merge?.merge_attempts?.[loopId]?.selected_strategy || '-';
+        console.log(`  ${loopId.padEnd(18)} ${String(state.status).padEnd(10)} backend ${String(backend).padEnd(24)} workers ${String(active).padEnd(2)} gates ${gates.padEnd(5)} worktree ${String(worktree).padEnd(18)} merge ${String(mergeStatus).padEnd(14)} ${resumable}`);
     }
+    if (merge)
+        console.log(`Merge: ${merge.ok ? 'passed' : 'blocked'} strategy=${JSON.stringify(merge.strategy_summary || {})}`);
+    if (sideEffects)
+        console.log(`Side effects: ${sideEffects.ok ? 'passed' : 'blocked'} blockers=${sideEffects.blockers?.length || 0}`);
+    if (proof?.gpt_final_arbiter)
+        console.log(`Final arbiter: ${proof.gpt_final_arbiter.verdict || 'unknown'} handled_by=${proof.gpt_final_arbiter.handled_by || 'loop-finalizer'}`);
 }
 async function loopProof(args) {
     const root = await sksRoot();
@@ -109,6 +120,12 @@ async function loopProof(args) {
     if (flag(args, '--json'))
         return printJson(proof);
     console.log(renderLoopProofSummary(proof));
+    if (proof.integration_merge)
+        console.log(`Merge: ${proof.integration_merge.ok ? 'passed' : 'blocked'} ${JSON.stringify(proof.integration_merge.strategy_summary || {})}`);
+    if (proof.side_effect_report)
+        console.log(`Side effects: ${proof.side_effect_report.ok ? 'passed' : 'blocked'} ${proof.side_effect_report.blockers?.join(', ') || 'none'}`);
+    if (proof.gpt_final_arbiter)
+        console.log(`Final arbiter: ${proof.gpt_final_arbiter.verdict || 'unknown'} contract=${proof.gpt_final_arbiter.gate_contract_path || 'missing'}`);
 }
 async function loopGraph(args) {
     const root = await sksRoot();
@@ -173,4 +190,19 @@ async function resolveLoopMission(root, arg) {
 function normalizeParallelism(value) {
     return value === 'safe' || value === 'extreme' ? value : 'balanced';
 }
+async function readJsonl(file) {
+    const text = await import('node:fs/promises').then((fs) => fs.readFile(file, 'utf8')).catch(() => '');
+    return String(text).split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter(Boolean);
+}
 //# sourceMappingURL=loop-command.js.map

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

@@ -5,6 +5,7 @@ import { runNativeAgentOrchestrator } from '../agents/agent-orchestrator.js';
 import { classifyOllamaWorkerSlice } from '../agents/agent-runner-ollama.js';
 import { buildNarutoCloneRoster, systemSafeNarutoConcurrency } from '../agents/agent-roster.js';
 import { DEFAULT_NARUTO_CLONES, MAX_NARUTO_AGENT_COUNT } from '../agents/agent-schema.js';
+import { normalizeServiceTier } from '../agents/fast-mode-policy.js';
 import { resolveOllamaWorkerConfig } from '../agents/ollama-worker-config.js';
 import { attachZellijSessionInteractive, launchZellijLayout } from '../zellij/zellij-launcher.js';
 import { maybePromptZellijUpdateForLaunch } from '../zellij/zellij-update.js';
@@ -380,10 +381,9 @@ async function narutoRun(parsed) {
         workerPlacement: parsed.json || parsed.noOpenZellij ? 'process' : 'zellij-pane',
         zellijPaneWorker: true,
         zellijVisiblePaneCap: zellijVisiblePanes,
-        // Shadow clones ALWAYS run in fast service tier — never honor --no-fast/standard.
-        fastMode: true,
-        serviceTier: 'fast',
-        noFast: false,
+        ...(parsed.fastMode === undefined ? {} : { fastMode: parsed.fastMode }),
+        ...(parsed.serviceTier === undefined ? {} : { serviceTier: parsed.serviceTier }),
+        noFast: parsed.noFast,
         writeMode: writeCapable ? parsed.writeMode || 'parallel' : 'off',
         applyPatches: parsed.applyPatches,
         dryRunPatches: parsed.dryRunPatches,
@@ -797,6 +797,10 @@ function parseNarutoArgs(args = []) {
     const applyPatches = hasFlag(args, '--apply-patches');
     const dryRunPatches = hasFlag(args, '--dry-run-patches') || hasFlag(args, '--dry-run-patch');
     const maxWriteAgents = Math.max(0, Math.floor(Number(readOption(args, '--max-write-agents', '0')) || 0));
+    const explicitServiceTier = String(readOption(args, '--service-tier', '') || '');
+    const serviceTier = normalizeServiceTier(explicitServiceTier, null) || undefined;
+    const fastMode = hasFlag(args, '--no-fast') || serviceTier === 'standard' ? false : hasFlag(args, '--fast') ? true : undefined;
+    const noFast = hasFlag(args, '--no-fast');
     const positionalMission = action === 'dashboard' || action === 'workers' || action === 'status' || action === 'proof'
         ? positionalArgs(rest, new Set()).find((arg) => /^latest$|^M-/.test(arg))
         : null;
@@ -808,9 +812,9 @@ function parseNarutoArgs(args = []) {
     const smoke = hasFlag(args, '--smoke');
     const parallelism = normalizeParallelism(readOption(args, '--parallelism', 'extreme'));
     const messages = normalizeMessages(readOption(args, '--messages', '8'));
-    const valueFlags = new Set(['--clones', '--agents', '--work-items', '--concurrency', '--target-active-slots', '--backend', '--write-mode', '--max-write-agents', '--mission', '--mission-id', '--ollama-model', '--local-model-model', '--ollama-base-url', '--local-model-base-url', '--parallelism', '--messages']);
+    const valueFlags = new Set(['--clones', '--agents', '--work-items', '--concurrency', '--target-active-slots', '--backend', '--write-mode', '--max-write-agents', '--service-tier', '--mission', '--mission-id', '--ollama-model', '--local-model-model', '--ollama-base-url', '--local-model-base-url', '--parallelism', '--messages']);
     const prompt = positionalArgs(rest, valueFlags).join(' ').trim() || 'Naruto shadow clone swarm run';
-    return { action, prompt, clones, workItems, concurrency, backend, backendExplicit, mock, real, readonly, ollamaEnabled: useOllama && !noOllama, noOllama, ollamaModel, ollamaBaseUrl, writeMode, applyPatches, dryRunPatches, maxWriteAgents, json, missionId, noOpenZellij, attach, smoke, parallelism, messages };
+    return { action, prompt, clones, workItems, concurrency, backend, backendExplicit, mock, real, readonly, ollamaEnabled: useOllama && !noOllama, noOllama, ollamaModel, ollamaBaseUrl, writeMode, applyPatches, dryRunPatches, maxWriteAgents, fastMode, serviceTier, noFast, json, missionId, noOpenZellij, attach, smoke, parallelism, messages };
 }
 function normalizeParallelism(value) {
     const text = String(value || 'extreme').toLowerCase();

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

@@ -120,7 +120,17 @@ export async function wikiCommand(sub, args = []) {
             const { id, dir } = await createMission(root, { mode: 'wiki', prompt: 'sks wiki refresh' });
             const gate = { schema_version: 1, passed: validation.result.ok, ok: validation.result.ok, context_pack: '.sneakoscope/wiki/context-pack.json', anchors: wikiAnchorCount(pack.wiki), voxels: wikiVoxelRowCount(pack.wiki) };
             await writeJsonAtomic(path.join(dir, 'wiki-gate.json'), gate);
-            await maybeFinalizeRoute(root, { missionId: id, route: '$Wiki', gateFile: 'wiki-gate.json', gate, artifacts: ['wiki-gate.json', 'completion-proof.json'], statusHint: validation.result.ok ? 'verified_partial' : 'blocked', blockers: validation.result.ok ? [] : validation.result.issues, command: { cmd: 'sks wiki refresh', status: exitCode } });
+            await maybeFinalizeRoute(root, {
+                missionId: id,
+                route: '$Wiki',
+                gateFile: 'wiki-gate.json',
+                gate,
+                artifacts: ['wiki-gate.json', 'completion-proof.json'],
+                statusHint: validation.result.ok ? 'verified_partial' : 'blocked',
+                blockers: validation.result.ok ? [] : validation.result.issues,
+                command: { cmd: 'sks wiki refresh', status: exitCode },
+                failureAnalysis: wikiRefreshFailureAnalysis(validation.result, gate)
+            });
         }
         if (flag(args, '--json')) {
             process.exitCode = exitCode;
@@ -197,6 +207,30 @@ export async function wikiCommand(sub, args = []) {
     console.error('Usage: sks wiki coords|pack|refresh|publish|rebuild-index|rebuild-summary|validate|validate-shared|wrongness|image-ingest|anchor-add|relation-add|image-validate|image-summary');
     process.exitCode = 1;
 }
+function wikiRefreshFailureAnalysis(validationResult, gate = {}) {
+    if (validationResult?.ok) {
+        return {
+            status: 'complete',
+            root_cause: 'Wiki refresh intentionally finalizes as verified_partial because a context-pack refresh can verify TriWiki schema and anchors, but active wrongness memory may still prevent full trust verification.',
+            corrective_action: 'The Wiki route records the fresh context-pack validation, wiki gate counts, and completion-proof evidence while keeping the route below full verified status until wrongness memory is separately resolved.',
+            evidence: [
+                '.sneakoscope/wiki/context-pack.json',
+                'wiki-gate.json',
+                { anchors: gate.anchors || 0, voxels: gate.voxels || 0 }
+            ]
+        };
+    }
+    return {
+        status: 'complete',
+        root_cause: `Wiki context-pack validation failed during refresh: ${(validationResult?.issues || []).join(', ') || 'unknown validation issue'}.`,
+        corrective_action: 'The Wiki route finalized as blocked and preserved validation issues in the completion proof so the context pack can be corrected before any completion claim.',
+        evidence: [
+            '.sneakoscope/wiki/context-pack.json',
+            'wiki-gate.json',
+            ...(validationResult?.issues || [])
+        ]
+    };
+}
 async function wikiImageIngest(args = []) {
     const root = await sksRoot();
     const imagePath = args.find((arg, i) => i >= 0 && !String(arg).startsWith('--'));

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

package/dist/core/init.js

@@ -591,7 +591,6 @@ export async function initProject(root, opts = {}) {
         // upgrade never clobbers a user's chosen model/service_tier. model_reasoning_effort
         // is intentionally left untouched at the top level.
         next = upsertTopLevelTomlStringIfAbsent(next, 'model', 'gpt-5.5');
-        next = upsertTopLevelTomlStringIfAbsent(next, 'service_tier', 'fast');
         next = upsertTopLevelTomlBooleanIfAbsent(next, 'suppress_unstable_features_warning', true);
         // Codex App feature flags: SET-IF-ABSENT only (see note above).
         for (const flag of MANAGED_CODEX_FEATURE_FLAGS) {
@@ -599,7 +598,7 @@ export async function initProject(root, opts = {}) {
         }
         next = upsertTomlTableKeyIfAbsent(next, 'user.fast_mode', 'visible = true');
         next = upsertTomlTableKeyIfAbsent(next, 'user.fast_mode', 'enabled = true');
-        next = upsertTomlTableKeyIfAbsent(next, 'user.fast_mode', 'default_profile = "sks-fast-high"');
+        next = removeTomlTableKey(next, 'user.fast_mode', 'default_profile');
         next = upsertTomlTableKeyIfAbsent(next, 'agents', 'max_threads = 6');
         next = upsertTomlTableKeyIfAbsent(next, 'agents', 'max_depth = 1');
         for (const block of managedCodexConfigBlocks()) {

package/dist/core/loops/loop-artifacts.js

@@ -36,6 +36,27 @@ export function loopIntegrationMergePath(root, missionId) {
 export function loopGptFinalArbiterPath(root, missionId) {
     return path.join(loopRoot(root, missionId), 'loop-gpt-final-arbiter.json');
 }
+export function loopFinalArbiterGateContractPath(root, missionId) {
+    return path.join(loopRoot(root, missionId), 'gpt-final-arbiter-gate-contract.json');
+}
+export function loopFixturePolicyPath(root, missionId) {
+    return path.join(loopRoot(root, missionId), 'fixture-policy.json');
+}
+export function loopMutationLedgerPath(root, missionId) {
+    return path.join(loopRoot(root, missionId), 'mutation-ledger.jsonl');
+}
+export function loopSideEffectReportPath(root, missionId) {
+    return path.join(loopRoot(root, missionId), 'loop-side-effect-report.json');
+}
+export function loopActiveWorkerHandlesPath(root, missionId) {
+    return path.join(loopRoot(root, missionId), 'active-worker-handles.jsonl');
+}
+export function loopInterruptResultPath(root, missionId) {
+    return path.join(loopRoot(root, missionId), 'interrupt-result.json');
+}
+export function loopConcurrencyBudgetPath(root, missionId) {
+    return path.join(loopRoot(root, missionId), 'concurrency-budget.json');
+}
 export function loopKillRequestPath(root, missionId) {
     return path.join(loopRoot(root, missionId), 'kill-request.json');
 }

package/dist/core/loops/loop-concurrency-budget.js

@@ -0,0 +1,55 @@
+import os from 'node:os';
+import { writeJsonAtomic } from '../fsx.js';
+import { loopConcurrencyBudgetPath } from './loop-artifacts.js';
+export function computeLoopConcurrencyBudget(input) {
+    const env = input.env || process.env;
+    const cores = Math.max(1, os.cpus().length || 1);
+    const requestedLoops = input.parallelism === 'safe' ? 2 : input.parallelism === 'extreme' ? Math.min(16, cores) : Math.min(8, cores);
+    const envLoops = positiveInt(env.SKS_LOOP_MAX_ACTIVE_LOOPS);
+    const envWorkers = positiveInt(env.SKS_LOOP_MAX_ACTIVE_WORKERS);
+    const envModelCalls = positiveInt(env.SKS_LOOP_MAX_MODEL_CALLS);
+    const maxActiveLoops = envLoops || requestedLoops;
+    const maxActiveWorkers = envWorkers || (input.parallelism === 'safe' ? Math.min(8, cores) : input.parallelism === 'extreme' ? Math.min(32, Math.max(4, cores * 2)) : Math.min(16, Math.max(4, cores)));
+    const maxModelCalls = envModelCalls || Math.max(1, Math.min(maxActiveWorkers, input.plan.global_budget.max_model_calls || maxActiveWorkers));
+    let remainingWorkers = maxActiveWorkers;
+    let remainingModelCalls = maxModelCalls;
+    const perLoop = input.plan.graph.nodes.map((node) => {
+        const requested = Math.max(1, node.maker.worker_count + node.checker.worker_count);
+        const fairShare = Math.max(1, Math.floor(maxActiveWorkers / Math.max(1, input.plan.graph.nodes.length)));
+        const allocation = Math.min(requested, Math.max(1, fairShare), Math.max(1, remainingWorkers));
+        const maker = Math.min(node.maker.worker_count, Math.max(1, Math.ceil(allocation / 2)));
+        const checker = Math.min(node.checker.worker_count, Math.max(0, allocation - maker));
+        const modelCalls = Math.min(Math.max(1, node.budget.max_model_calls), Math.max(1, remainingModelCalls));
+        remainingWorkers = Math.max(0, remainingWorkers - maker - checker);
+        remainingModelCalls = Math.max(0, remainingModelCalls - modelCalls);
+        return {
+            loop_id: node.loop_id,
+            maker_workers: maker,
+            checker_workers: checker,
+            model_call_budget: modelCalls
+        };
+    });
+    return {
+        schema: 'sks.loop-concurrency-budget.v1',
+        mission_id: input.plan.mission_id,
+        max_active_loops: maxActiveLoops,
+        max_active_workers: maxActiveWorkers,
+        max_model_calls: maxModelCalls,
+        per_loop_worker_budget: perLoop,
+        headroom_workers: Math.max(0, maxActiveWorkers - perLoop.reduce((sum, row) => sum + row.maker_workers + row.checker_workers, 0)),
+        blockers: []
+    };
+}
+export async function writeLoopConcurrencyBudget(root, budget) {
+    await writeJsonAtomic(loopConcurrencyBudgetPath(root, budget.mission_id), { ...budget, generated_at: new Date().toISOString() });
+}
+export function loopWorkerBudgetFor(budget, loopId, phase, requested) {
+    const row = budget.per_loop_worker_budget.find((item) => item.loop_id === loopId);
+    const allowed = phase === 'maker' ? row?.maker_workers : row?.checker_workers;
+    return Math.max(1, Math.min(Math.max(1, requested), Math.max(1, allowed || requested)));
+}
+function positiveInt(value) {
+    const number = Number(value);
+    return Number.isFinite(number) && number >= 1 ? Math.floor(number) : null;
+}
+//# sourceMappingURL=loop-concurrency-budget.js.map

package/dist/core/loops/loop-final-arbiter-contract.js

@@ -0,0 +1,28 @@
+import { writeJsonAtomic } from '../fsx.js';
+import { loopFinalArbiterGateContractPath, loopGptFinalArbiterPath } from './loop-artifacts.js';
+export async function writeLoopFinalArbiterGateContract(root, missionId) {
+    const contract = buildLoopFinalArbiterGateContract(root, missionId);
+    await writeJsonAtomic(loopFinalArbiterGateContractPath(root, missionId), { ...contract, generated_at: new Date().toISOString() });
+    return contract;
+}
+export function buildLoopFinalArbiterGateContract(root, missionId) {
+    return {
+        schema: 'sks.loop-final-arbiter-gate-contract.v1',
+        mission_id: missionId,
+        gate_id: 'gpt:final-arbiter',
+        handled_by: 'loop-finalizer',
+        gate_runner_status: 'deferred',
+        finalizer_artifact_path: relativeMissionArtifact(root, loopGptFinalArbiterPath(root, missionId)),
+        required_when: ['source_mutation_exists', 'selected_gates_include_gpt_final_arbiter'],
+        production_fixture_allowed: false
+    };
+}
+export function loopFinalArbiterGateContractRelativePath(missionId) {
+    return `.sneakoscope/missions/${missionId}/loops/gpt-final-arbiter-gate-contract.json`;
+}
+function relativeMissionArtifact(root, absolute) {
+    const normalizedRoot = root.replace(/\\/g, '/').replace(/\/+$/, '');
+    const normalized = absolute.replace(/\\/g, '/');
+    return normalized.startsWith(`${normalizedRoot}/`) ? normalized.slice(normalizedRoot.length + 1) : normalized;
+}
+//# sourceMappingURL=loop-final-arbiter-contract.js.map

package/dist/core/loops/loop-finalizer.js

@@ -1,8 +1,10 @@
 import { readJson, writeJsonAtomic } from '../fsx.js';
 import { loopGraphProofPath, loopProofPath } from './loop-artifacts.js';
+import { writeLoopFinalArbiterGateContract } from './loop-final-arbiter-contract.js';
 import { runLoopGptFinalArbiter } from './loop-gpt-final-arbiter.js';
 import { mergeLoopWorktrees } from './loop-integration-merge.js';
 import { graphProofFromLoopProofs } from './loop-scheduler.js';
+import { buildLoopSideEffectReport } from './loop-side-effect-scanner.js';
 export async function finalizeLoopGraph(input) {
     const proofs = input.proofs || await Promise.all(input.plan.graph.nodes.map((node) => readJson(loopProofPath(input.root, input.plan.mission_id, node.loop_id), null)));
     const realProofs = proofs.filter((proof) => Boolean(proof));
@@ -20,14 +22,26 @@ export async function finalizeLoopGraph(input) {
     });
     const anyHandoff = realProofs.some((proof) => proof.handoff.required);
     const anySourceMutation = realProofs.some((proof) => proof.changed_files.some((file) => !file.startsWith('.sneakoscope/')));
+    const selectedGptFinal = graph.gates.selected.includes('gpt:final-arbiter');
+    const contract = anySourceMutation || selectedGptFinal
+        ? await writeLoopFinalArbiterGateContract(input.root, input.plan.mission_id)
+        : null;
+    const sideEffectReport = await buildLoopSideEffectReport({
+        root: input.root,
+        missionId: input.plan.mission_id,
+        proofs: realProofs,
+        integrationMerge
+    });
     const arbiter = anySourceMutation
-        ? await runLoopGptFinalArbiter({ root: input.root, plan: input.plan, proofs: realProofs, integrationMerge })
+        ? await runLoopGptFinalArbiter({ root: input.root, plan: input.plan, proofs: realProofs, integrationMerge, sideEffectReport })
         : null;
     const blockers = [
         ...graph.blockers,
         ...(anyHandoff ? ['loop_handoff_required'] : []),
         ...(integrationMerge.ok ? [] : integrationMerge.blockers),
+        ...(sideEffectReport.ok ? [] : sideEffectReport.blockers),
         ...(anySourceMutation && !arbiter ? ['gpt_final_arbiter_missing'] : []),
+        ...(selectedGptFinal && anySourceMutation && (!contract || !arbiter) ? ['gpt_final_arbiter_contract_unfulfilled'] : []),
         ...(arbiter && !arbiter.ok ? ['gpt_final_arbiter_not_approved', ...arbiter.blockers] : [])
     ];
     const finalGraph = {
@@ -38,13 +52,21 @@ export async function finalizeLoopGraph(input) {
             ok: integrationMerge.ok,
             artifact_path: `.sneakoscope/missions/${input.plan.mission_id}/loops/integration-merge.json`,
             applied_loops: integrationMerge.applied_loops,
-            conflict_loops: integrationMerge.conflict_loops
+            conflict_loops: integrationMerge.conflict_loops,
+            ...(integrationMerge.strategy_summary ? { strategy_summary: integrationMerge.strategy_summary } : {})
+        },
+        side_effect_report: {
+            ok: sideEffectReport.ok,
+            artifact_path: `.sneakoscope/missions/${input.plan.mission_id}/loops/loop-side-effect-report.json`,
+            blockers: sideEffectReport.blockers
         },
         ...(arbiter ? {
             gpt_final_arbiter: {
                 ok: arbiter.ok,
                 artifact_path: arbiter.artifact_path,
-                verdict: arbiter.verdict
+                verdict: arbiter.verdict,
+                gate_contract_path: `.sneakoscope/missions/${input.plan.mission_id}/loops/gpt-final-arbiter-gate-contract.json`,
+                handled_by: 'loop-finalizer'
             }
         } : {})
     };

package/dist/core/loops/loop-fixture-policy.js

@@ -0,0 +1,58 @@
+import os from 'node:os';
+import path from 'node:path';
+import { writeJsonAtomic } from '../fsx.js';
+import { loopFixturePolicyPath } from './loop-artifacts.js';
+export function decideLoopFixturePolicy(input) {
+    const env = input.env || process.env;
+    const argv = input.argv || process.argv;
+    const scriptPath = argv.find((arg) => /(?:^|[\\/])(?:dist|src)[\\/]scripts[\\/]/.test(arg)) || argv[1] || '';
+    const scriptName = path.basename(scriptPath);
+    const scriptIsCheck = /(?:^|[\\/])(?:dist|src)[\\/]scripts[\\/]/.test(scriptPath)
+        && /(check|blackbox)/.test(scriptName);
+    const missionIsCheck = /^M-check-/.test(input.missionId);
+    const tempRoot = isUnderTempRoot(input.root);
+    const explicitTestEnv = env.NODE_ENV === 'test'
+        || env.SKS_TEST_RUNTIME_FIXTURE_ALLOWED === '1'
+        || env.VITEST_WORKER_ID !== undefined
+        || env.JEST_WORKER_ID !== undefined
+        || env.NODE_V8_COVERAGE !== undefined;
+    const commandText = argv.join(' ');
+    const productionCommand = /\bsks\s+(?:loop\s+run|goal|naruto)\b/.test(commandText);
+    const requestedByEnv = env.SKS_LOOP_GATE_FIXTURE === '1'
+        || env.SKS_LOOP_RUNTIME_FIXTURE === '1'
+        || env.SKS_LOOP_GPT_FINAL_FIXTURE === '1';
+    const allowReasons = [
+        scriptIsCheck ? 'release_check_script' : null,
+        missionIsCheck ? 'check_mission_id' : null,
+        tempRoot ? 'temp_project_root' : null,
+        explicitTestEnv ? 'test_environment' : null
+    ].filter((value) => Boolean(value));
+    const allowed = input.requested && allowReasons.length > 0 && !productionCommand;
+    const productionLike = !scriptIsCheck && !missionIsCheck && !tempRoot && !explicitTestEnv;
+    const blockers = input.requested && !allowed
+        ? [
+            'loop_fixture_forbidden_in_production',
+            `loop_${input.mode.replace(/-/g, '_')}_fixture_forbidden_in_production`,
+            ...(productionCommand ? ['loop_fixture_forbidden_for_production_command'] : []),
+            ...(requestedByEnv && productionLike ? ['loop_fixture_env_without_allowed_reason'] : [])
+        ]
+        : [];
+    return {
+        schema: 'sks.loop-fixture-policy-decision.v1',
+        allowed,
+        mode: input.mode,
+        requested: input.requested,
+        production_like: productionLike || productionCommand,
+        reason: allowed ? allowReasons.join('+') : input.requested ? 'fixture_requires_check_or_test_context' : 'fixture_not_requested',
+        blockers: [...new Set(blockers)]
+    };
+}
+export async function writeLoopFixturePolicyDecision(root, missionId, decision) {
+    await writeJsonAtomic(loopFixturePolicyPath(root, missionId), { ...decision, generated_at: new Date().toISOString() });
+}
+export function isUnderTempRoot(root) {
+    const normalizedRoot = path.resolve(root);
+    const tempRoot = path.resolve(os.tmpdir());
+    return normalizedRoot === tempRoot || normalizedRoot.startsWith(`${tempRoot}${path.sep}`);
+}
+//# sourceMappingURL=loop-fixture-policy.js.map

package/dist/core/loops/loop-gate-runner.js

@@ -4,6 +4,8 @@ import { readJson, runProcess, writeJsonAtomic } from '../fsx.js';
 import { allGateIds } from './loop-schema.js';
 import { loopBudgetPath, loopGatePath, loopStatePath } from './loop-artifacts.js';
 import { resolveLoopGate } from './loop-gate-registry.js';
+import { decideLoopFixturePolicy, writeLoopFixturePolicyDecision } from './loop-fixture-policy.js';
+import { loopFinalArbiterGateContractRelativePath, writeLoopFinalArbiterGateContract } from './loop-final-arbiter-contract.js';
 export async function runLoopGates(input) {
     const selected = allGateIds(input.gates);
     const failed = [];
@@ -35,10 +37,20 @@ async function runOneGate(input, gateId) {
     const fullReleaseCheckInsideLoop = gateId === 'release:check' && input.node.route !== '$Integration';
     const unknown = !definition;
     const packageJson = unknown ? await readJson(path.join(input.root, 'package.json'), null) : null;
-    const skipUnknownFixtureGate = unknown && !packageJson;
+    const fixtureMode = process.env.SKS_LOOP_GATE_FIXTURE === '1';
+    const fixtureDecision = decideLoopFixturePolicy({
+        root: input.root,
+        missionId: input.missionId,
+        mode: 'gate',
+        requested: fixtureMode || (unknown && !packageJson)
+    });
+    if (fixtureDecision.requested)
+        await writeLoopFixturePolicyDecision(input.root, input.missionId, fixtureDecision).catch(() => undefined);
+    const skipUnknownFixtureGate = unknown && !packageJson && fixtureDecision.allowed;
     const blockers = [
         ...(unknown && !skipUnknownFixtureGate ? [`unknown_loop_gate:${gateId}`] : []),
-        ...(fullReleaseCheckInsideLoop ? ['full_release_check_inside_non_integration_loop'] : [])
+        ...(fullReleaseCheckInsideLoop ? ['full_release_check_inside_non_integration_loop'] : []),
+        ...(fixtureMode && !fixtureDecision.allowed ? [...fixtureDecision.blockers, 'loop_gate_fixture_forbidden_in_production'] : [])
     ];
     let ok = blockers.length === 0;
     let skipped = skipUnknownFixtureGate;
@@ -46,9 +58,14 @@ async function runOneGate(input, gateId) {
     let stdoutTail = '';
     let stderrTail = '';
     let timedOut = false;
-    const fixtureMode = process.env.SKS_LOOP_GATE_FIXTURE === '1';
+    let handledBy;
+    let deferredContractPath;
+    let deferredReason;
     if (definition && ok) {
-        if (fixtureMode && definition.source !== 'builtin-pseudo') {
+        if (fixtureMode && !fixtureDecision.allowed) {
+            ok = false;
+        }
+        else if (fixtureMode && definition.source !== 'builtin-pseudo') {
             ok = true;
         }
         else if (definition.source === 'builtin-pseudo') {
@@ -56,6 +73,9 @@ async function runOneGate(input, gateId) {
             ok = builtin.ok;
             skipped = builtin.skipped;
             blockers.push(...builtin.blockers);
+            handledBy = builtin.handled_by;
+            deferredContractPath = builtin.deferred_contract_path;
+            deferredReason = builtin.deferred_reason;
         }
         else {
             const command = definition.command;
@@ -91,7 +111,12 @@ async function runOneGate(input, gateId) {
         stderr_tail: stderrTail,
         cached_allowed: definition?.cache_allowed ?? false,
         fixture_mode: fixtureMode,
+        fixture_policy: fixtureDecision,
+        fixture_allowed_reason: fixtureDecision.allowed ? fixtureDecision.reason : null,
         skipped,
+        handled_by: handledBy,
+        deferred_contract_path: deferredContractPath,
+        deferred_reason: deferredReason,
         deferred_unknown_fixture_gate: skipUnknownFixtureGate,
         timed_out: timedOut,
         full_release_check_inside_loop: fullReleaseCheckInsideLoop,
@@ -99,11 +124,27 @@ async function runOneGate(input, gateId) {
         blockers
     };
     await writeJsonAtomic(loopGatePath(input.root, input.missionId, input.node.loop_id, gateId), artifact);
-    return { ok, skipped, blockers };
+    return {
+        ok,
+        skipped,
+        blockers,
+        ...(handledBy ? { handled_by: handledBy } : {}),
+        ...(deferredContractPath ? { deferred_contract_path: deferredContractPath } : {}),
+        ...(deferredReason ? { deferred_reason: deferredReason } : {})
+    };
 }
 async function runBuiltinGate(root, missionId, loopId, definition, checkerArtifacts) {
-    if (definition.id === 'gpt:final-arbiter')
-        return { ok: true, skipped: true, blockers: [] };
+    if (definition.id === 'gpt:final-arbiter') {
+        await writeLoopFinalArbiterGateContract(root, missionId);
+        return {
+            ok: true,
+            skipped: true,
+            blockers: [],
+            handled_by: 'loop-finalizer',
+            deferred_contract_path: loopFinalArbiterGateContractRelativePath(missionId),
+            deferred_reason: 'gpt_final_arbiter_runs_after_integration_merge'
+        };
+    }
     if (definition.id === 'human:handoff-required')
         return { ok: false, skipped: false, blockers: ['human_handoff_required'] };
     if (definition.id === 'loop:state-valid') {

package/dist/core/loops/loop-gpt-final-arbiter.js

@@ -1,6 +1,7 @@
 import { runGptFinalArbiter } from '../codex-control/gpt-final-arbiter.js';
 import { nowIso, writeJsonAtomic } from '../fsx.js';
 import { loopGptFinalArbiterPath } from './loop-artifacts.js';
+import { decideLoopFixturePolicy, writeLoopFixturePolicyDecision } from './loop-fixture-policy.js';
 export async function runLoopGptFinalArbiter(input) {
     const artifactPath = loopGptFinalArbiterPath(input.root, input.plan.mission_id);
     const changedFiles = [...new Set([
@@ -8,10 +9,29 @@ export async function runLoopGptFinalArbiter(input) {
             ...input.proofs.flatMap((proof) => proof.changed_files)
         ])];
     const reviewedLoopIds = input.proofs.map((proof) => proof.loop_id);
-    if (process.env.SKS_LOOP_GPT_FINAL_FIXTURE === '1' || input.forceVerdict) {
+    const fixtureRequested = process.env.SKS_LOOP_GPT_FINAL_FIXTURE === '1' || Boolean(input.forceVerdict);
+    const fixtureDecision = decideLoopFixturePolicy({
+        root: input.root,
+        missionId: input.plan.mission_id,
+        mode: 'gpt-final',
+        requested: fixtureRequested
+    });
+    if (fixtureRequested)
+        await writeLoopFixturePolicyDecision(input.root, input.plan.mission_id, fixtureDecision).catch(() => undefined);
+    if (fixtureRequested && !fixtureDecision.allowed) {
+        const result = buildResult(input.plan.mission_id, reviewedLoopIds, changedFiles, 'reject', [], artifactPath, [...fixtureDecision.blockers, 'loop_gpt_final_fixture_forbidden_in_production']);
+        await writeJsonAtomic(artifactPath, { ...result, generated_at: nowIso(), backend: 'fixture-forbidden', fixture_policy: fixtureDecision });
+        return result;
+    }
+    if (fixtureRequested) {
         const verdict = input.forceVerdict || (process.env.SKS_LOOP_GPT_FINAL_REJECT === '1' ? 'reject' : 'approve');
         const result = buildResult(input.plan.mission_id, reviewedLoopIds, changedFiles, verdict, verdict === 'approve' ? [] : ['fixture_revision_required'], artifactPath, []);
-        await writeJsonAtomic(artifactPath, { ...result, generated_at: nowIso(), backend: 'fixture' });
+        await writeJsonAtomic(artifactPath, { ...result, generated_at: nowIso(), backend: 'fixture', fixture_policy: fixtureDecision, fixture_allowed_reason: fixtureDecision.reason, side_effect_report: input.sideEffectReport || null });
+        return result;
+    }
+    if (input.sideEffectReport && !input.sideEffectReport.ok) {
+        const result = buildResult(input.plan.mission_id, reviewedLoopIds, changedFiles, 'reject', [], artifactPath, input.sideEffectReport.blockers);
+        await writeJsonAtomic(artifactPath, { ...result, generated_at: nowIso(), backend: 'side-effect-block', side_effect_report: input.sideEffectReport });
         return result;
     }
     const arbiter = await runGptFinalArbiter({
@@ -27,17 +47,17 @@ export async function runLoopGptFinalArbiter(input) {
             changed_files: proof.changed_files,
             blockers: proof.blockers
         })),
-        candidate_diff: JSON.stringify({ changed_files: changedFiles, integration_merge: input.integrationMerge }),
+        candidate_diff: JSON.stringify({ changed_files: changedFiles, integration_merge: input.integrationMerge, side_effect_report: input.sideEffectReport || null }),
         verification_results: input.proofs.map((proof) => ({ id: proof.loop_id, ok: proof.status === 'completed', blockers: proof.blockers })),
-        side_effect_report: { schema: 'sks.loop-side-effect-report.v1', ok: true, changed_files: changedFiles },
-        mutation_ledger: { schema: 'sks.loop-mutation-ledger.v1', proofs: input.proofs },
+        side_effect_report: input.sideEffectReport || { schema: 'sks.loop-side-effect-report.v1', ok: true, changed_files: changedFiles },
+        mutation_ledger: { schema: 'sks.loop-mutation-ledger.v1', proofs: input.proofs, path: input.sideEffectReport?.mutation_ledger_path || null },
         rollback_plan: { schema: 'sks.loop-rollback-plan.v1', strategy: 'git-worktree-or-human-handoff' }
     }, { cwd: input.root, mutationLedgerRoot: `${input.root}/.sneakoscope/missions/${input.plan.mission_id}/loops/gpt-final-arbiter` });
     const status = String(arbiter.result?.status || '');
     const verdict = status === 'approved' || status === 'modified' ? 'approve' : status === 'needs_more_work' ? 'revise' : 'reject';
     const blockers = stringArray(arbiter.blockers);
     const result = buildResult(input.plan.mission_id, reviewedLoopIds, changedFiles, verdict, stringArray(arbiter.result?.required_followup_work), artifactPath, blockers);
-    await writeJsonAtomic(artifactPath, { ...result, generated_at: nowIso(), backend: arbiter.backend || null, arbiter });
+    await writeJsonAtomic(artifactPath, { ...result, generated_at: nowIso(), backend: arbiter.backend || null, side_effect_report: input.sideEffectReport || null, arbiter });
     return result;
 }
 function buildResult(missionId, reviewedLoopIds, changedFiles, verdict, revisions, artifactPath, blockers) {