sneakoscope 3.0.4 → 3.1.1

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

@@ -0,0 +1,176 @@
+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 { finalizeLoopGraph } from '../loops/loop-finalizer.js';
+import { readLoopGraphProof } from '../loops/loop-observability.js';
+import { planLoopsFromRequest } from '../loops/loop-planner.js';
+import { renderLoopProofSummary } from '../loops/loop-proof-summary.js';
+import { runLoopNode, runLoopPlan } from '../loops/loop-runtime.js';
+import { scheduleLoopGraph } from '../loops/loop-scheduler.js';
+import { writeLoopKillRequest } from '../loops/loop-runtime-control.js';
+import { flag, promptOf, readFlagValue } from './command-utils.js';
+export async function loopCommand(subcommand = 'help', args = []) {
+    const action = subcommand || 'help';
+    if (action === 'plan')
+        return loopPlan(args);
+    if (action === 'run')
+        return loopRun(args);
+    if (action === 'status')
+        return loopStatus(args);
+    if (action === 'proof')
+        return loopProof(args);
+    if (action === 'kill')
+        return loopKill(args);
+    if (action === 'resume')
+        return loopResume(args);
+    if (action === 'graph')
+        return loopGraph(args);
+    console.log(`SKS Loop
+
+Usage:
+  sks loop plan "<request>" [--json]
+  sks loop run latest [--parallelism safe|balanced|extreme] [--json]
+  sks loop status latest [--json]
+  sks loop proof latest [--json]
+  sks loop kill <loop-id|all>
+  sks loop resume latest [--rerun-completed]
+  sks loop graph latest
+`);
+}
+async function loopPlan(args) {
+    const root = await sksRoot();
+    const request = promptOf(args);
+    if (!request)
+        throw new Error('Usage: sks loop plan "<request>" [--json]');
+    const { id } = await createMission(root, { mode: 'loop', prompt: request });
+    const plan = await planLoopsFromRequest({ root, missionId: id, request, sourceCommand: 'loop' });
+    await setCurrent(root, { mission_id: id, mode: 'LOOP', route: 'Loop', route_command: '$Loop', phase: 'LOOP_PLANNED', stop_gate: 'loop-graph-proof.json' }, { replace: true });
+    if (flag(args, '--json'))
+        return printJson({ schema: 'sks.loop-plan-command.v1', ok: plan.blockers.length === 0, mission_id: id, plan });
+    console.log(`Loop plan: ${id}`);
+    console.log('Loops:');
+    for (const node of plan.graph.nodes) {
+        const owner = [...node.owner_scope.files, ...node.owner_scope.directories][0] || 'integration';
+        console.log(`  ${node.loop_id.padEnd(18)} ${node.level.padEnd(12)} owner ${owner.padEnd(28)} gates ${[...node.gates.triage, ...node.gates.local, ...node.gates.checker, ...node.gates.integration, ...node.gates.final].length}`);
+    }
+}
+async function loopRun(args) {
+    const root = await sksRoot();
+    const missionId = await resolveLoopMission(root, args[0]);
+    if (!missionId)
+        throw new Error('No loop plan exists. Run: sks loop plan "<request>"');
+    const plan = await readJson(loopPlanPath(root, missionId));
+    if (plan.blockers.length) {
+        console.log(`Loop plan blocked: ${plan.blockers.join(', ')}`);
+        return;
+    }
+    const parallelism = normalizeParallelism(readFlagValue(args, '--parallelism', 'balanced'));
+    const result = await runLoopPlan({ root, plan, parallelism });
+    await setCurrent(root, { mission_id: missionId, mode: 'LOOP', route: 'Loop', route_command: '$Loop', phase: result.ok ? 'LOOP_COMPLETED' : 'LOOP_BLOCKED', stop_gate: 'loop-graph-proof.json' });
+    if (flag(args, '--json'))
+        return printJson({ schema: 'sks.loop-run-command.v1', ...result });
+    console.log(renderLoopProofSummary(result.graph_proof));
+}
+async function loopStatus(args) {
+    const root = await sksRoot();
+    const missionId = await resolveLoopMission(root, args[0]);
+    if (!missionId)
+        throw new Error('Usage: sks loop status <mission-id|latest>');
+    const plan = await readJson(loopPlanPath(root, missionId), null);
+    const proof = await readLoopGraphProof(root, missionId);
+    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 };
+    if (flag(args, '--json'))
+        return printJson(result);
+    console.log(`Loop status: ${missionId}`);
+    for (const state of states.filter(Boolean)) {
+        const loopId = String(state.loop_id);
+        const nodeProof = proofs.find((row) => row?.loop_id === loopId);
+        const checkpoint = checkpoints.find((row) => row?.loop_id === loopId);
+        const backend = nodeProof?.maker_result?.backend || 'blocked';
+        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}`);
+    }
+}
+async function loopProof(args) {
+    const root = await sksRoot();
+    const missionId = await resolveLoopMission(root, args[0]);
+    if (!missionId)
+        throw new Error('Usage: sks loop proof <mission-id|latest>');
+    const proof = await readLoopGraphProof(root, missionId);
+    if (!proof)
+        throw new Error(`Loop graph proof missing: ${missionId}`);
+    if (flag(args, '--json'))
+        return printJson(proof);
+    console.log(renderLoopProofSummary(proof));
+}
+async function loopGraph(args) {
+    const root = await sksRoot();
+    const missionId = await resolveLoopMission(root, args[0]);
+    if (!missionId)
+        throw new Error('Usage: sks loop graph <mission-id|latest>');
+    const plan = await readJson(loopPlanPath(root, missionId));
+    printJson({ schema: 'sks.loop-graph-command.v1', mission_id: missionId, graph: plan.graph });
+}
+async function loopKill(args) {
+    const root = await sksRoot();
+    const missionId = await findLatestMission(root);
+    const target = args[0];
+    if (!missionId || !target)
+        throw new Error('Usage: sks loop kill <loop-id|all>');
+    await writeLoopKillRequest(root, missionId, target);
+    console.log(`Loop kill requested: ${target}`);
+}
+async function loopResume(args) {
+    const root = await sksRoot();
+    const missionId = await resolveLoopMission(root, args[0]);
+    if (!missionId)
+        throw new Error('Usage: sks loop resume <mission-id|latest> [--rerun-completed]');
+    const plan = await readJson(loopPlanPath(root, missionId));
+    const rerunCompleted = flag(args, '--rerun-completed');
+    const existingProofs = await Promise.all(plan.graph.nodes.map((node) => readJson(loopProofPath(root, missionId, node.loop_id), null)));
+    const completed = new Set(existingProofs.filter((proof) => proof !== null && proof.status === 'completed').map((proof) => proof.loop_id));
+    const runnable = rerunCompleted ? plan.graph.nodes : plan.graph.nodes.filter((node) => !completed.has(node.loop_id));
+    const schedule = scheduleLoopGraph(runnable, normalizeParallelism(readFlagValue(args, '--parallelism', 'balanced')));
+    const started = Date.now();
+    const resumedProofs = [];
+    for (const batch of schedule.batches) {
+        const batchProofs = await Promise.all(batch.map((node) => runLoopNode({ root, plan, node })));
+        resumedProofs.push(...batchProofs);
+    }
+    const mergedProofs = [
+        ...existingProofs.filter((proof) => proof !== null && proof.status === 'completed' && !rerunCompleted),
+        ...resumedProofs
+    ];
+    const graphProof = await finalizeLoopGraph({
+        root,
+        plan,
+        proofs: mergedProofs,
+        maxActiveLoops: schedule.max_active_loops,
+        maxActiveWorkers: Math.max(1, mergedProofs.reduce((sum, proof) => sum + proof.maker_result.worker_count + proof.checker_result.worker_count, 0)),
+        wallMs: Math.max(1, Date.now() - started)
+    });
+    await setCurrent(root, { mission_id: missionId, mode: 'LOOP', route: 'Loop', route_command: '$Loop', phase: graphProof.ok ? 'LOOP_COMPLETED' : 'LOOP_BLOCKED', stop_gate: 'loop-graph-proof.json' });
+    if (flag(args, '--json'))
+        return printJson({ schema: 'sks.loop-resume-command.v1', ok: graphProof.ok, mission_id: missionId, resumed_loops: resumedProofs.map((proof) => proof.loop_id), skipped_completed: [...completed], graph_proof: graphProof });
+    console.log(renderLoopProofSummary(graphProof));
+}
+async function resolveLoopMission(root, arg) {
+    if (arg && arg !== 'latest')
+        return arg;
+    const latest = await findLatestMission(root);
+    if (!latest)
+        return null;
+    const loaded = await loadMission(root, latest).catch(() => null);
+    return loaded?.mission?.mode === 'loop' || await readJson(loopPlanPath(root, latest), null) ? latest : null;
+}
+function normalizeParallelism(value) {
+    return value === 'safe' || value === 'extreme' ? value : 'balanced';
+}
+//# sourceMappingURL=loop-command.js.map

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

@@ -385,6 +385,9 @@ async function narutoRun(parsed) {
         serviceTier: 'fast',
         noFast: false,
         writeMode: writeCapable ? parsed.writeMode || 'parallel' : 'off',
+        applyPatches: parsed.applyPatches,
+        dryRunPatches: parsed.dryRunPatches,
+        maxWriteAgents: parsed.maxWriteAgents,
         gitWorktreePolicy: worktreePolicy,
         narutoWorkGraph: workGraph,
         narutoAllocationPolicy: allocationPolicy,
@@ -418,18 +421,6 @@ async function narutoRun(parsed) {
         blockers: [...(result.proof?.blockers || []), ...(parallelRuntimeOk ? [] : ['naruto_parallel_runtime_proof_below_gate'])],
         updated_at: nowIso()
     });
-    await setCurrent(root, {
-        mission_id: mission.id,
-        route: 'Naruto',
-        route_command: '$Naruto',
-        mode: 'NARUTO',
-        phase: result.ok === true ? 'NARUTO_COMPLETE_OR_REVIEW' : 'NARUTO_BLOCKED',
-        native_sessions_verified: nativeProofOk,
-        subagents_verified: nativeProofOk,
-        naruto_gate_file: 'naruto-gate.json',
-        stop_gate: 'naruto-gate.json',
-        prompt: parsed.prompt
-    });
     const clones = result.roster?.agent_count ?? roster.agent_count;
     const localWorkerSummary = summarizeNarutoLocalWorkerResult(localWorker, result);
     // Finalizer policy: when local LLM workers contributed patches, the GPT
@@ -437,16 +428,29 @@ async function narutoRun(parsed) {
     const finalizer = evaluateNarutoFinalizer({
         localParticipated: Number(localWorkerSummary?.selected_worker_count || 0) > 0,
         gptFinalStatus: result.proof?.gpt_final_status || null,
-        applyPatches: writeCapable
+        applyPatches: parsed.applyPatches
     });
     await writeJsonAtomic(path.join(mission.dir, 'naruto-finalizer.json'), {
         ...finalizer,
         generated_at: nowIso(),
         mission_id: mission.id
     });
+    const summaryOk = result.ok === true && (parsed.applyPatches === true ? finalizer.ok === true : finalizer.run_ok === true);
+    await setCurrent(root, {
+        mission_id: mission.id,
+        route: 'Naruto',
+        route_command: '$Naruto',
+        mode: 'NARUTO',
+        phase: summaryOk ? 'NARUTO_COMPLETE_OR_REVIEW' : 'NARUTO_BLOCKED',
+        native_sessions_verified: nativeProofOk,
+        subagents_verified: nativeProofOk,
+        naruto_gate_file: 'naruto-gate.json',
+        stop_gate: 'naruto-gate.json',
+        prompt: parsed.prompt
+    });
     const summary = {
         schema: NARUTO_RESULT_SCHEMA,
-        ok: result.ok === true,
+        ok: summaryOk,
         mode: 'NARUTO',
         jutsu: 'kage_bunshin_no_jutsu',
         mission_id: result.mission_id,
@@ -502,6 +506,7 @@ async function narutoRun(parsed) {
             headless_workers: parallelRuntime.headless_workers,
             passed: parallelRuntime.passed
         } : null,
+        parallel_write_policy: result.parallel_write_policy || null,
         local_worker: localWorkerSummary,
         finalizer,
         proof: result.proof?.status || 'missing',
@@ -538,6 +543,7 @@ function compactNarutoRunResult(result) {
         mission_id: result?.mission_id || null,
         route: result?.route || NARUTO_ROUTE,
         backend: result?.backend || null,
+        parallel_write_policy: result?.parallel_write_policy || null,
         target_active_slots: result?.target_active_slots ?? null,
         proof: result?.proof ? {
             ok: result.proof.ok === true,
@@ -754,7 +760,7 @@ async function narutoHelp(parsed) {
         mode: 'NARUTO',
         description: 'Shadow Clone Swarm: fan out up to ' + MAX_NARUTO_AGENT_COUNT + ' parallel clone sessions.',
         usage: [
-            'sks naruto run "<task>" [--clones N] [--backend codex-sdk|fake|ollama] [--local-model|--no-ollama] [--work-items N] [--real] [--readonly] [--json]',
+            'sks naruto run "<task>" [--clones N] [--backend codex-sdk|fake|ollama] [--local-model|--no-ollama] [--work-items N] [--write-mode parallel|serial|off] [--apply-patches] [--dry-run-patches] [--real] [--readonly] [--json]',
             'sks naruto status [--mission <id>] [--json]',
             'sks naruto proof latest [--messages 20] [--json]'
         ],
@@ -788,6 +794,9 @@ function parseNarutoArgs(args = []) {
     const readonly = hasFlag(args, '--readonly') || hasFlag(args, '--read-only');
     const writeModeRaw = String(readOption(args, '--write-mode', hasFlag(args, '--parallel-write') ? 'parallel' : '') || '');
     const writeMode = (['proof-safe', 'parallel', 'serial', 'off'].includes(writeModeRaw) ? writeModeRaw : null);
+    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 positionalMission = action === 'dashboard' || action === 'workers' || action === 'status' || action === 'proof'
         ? positionalArgs(rest, new Set()).find((arg) => /^latest$|^M-/.test(arg))
         : null;
@@ -799,9 +808,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', '--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', '--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, 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, json, missionId, noOpenZellij, attach, smoke, parallelism, messages };
 }
 function normalizeParallelism(value) {
     const text = String(value || 'extreme').toLowerCase();

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

@@ -25,6 +25,7 @@ async function redirectTeamCreateToNaruto(args = []) {
             redirected_to: 'sks naruto run',
             route_command: '$Naruto',
             deprecated_route: '$Team',
+            parallel_write_policy: result?.parallel_write_policy || result?.run?.parallel_write_policy || null,
             created_at: nowIso(),
             args: list
         });

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.0.4';
+export const PACKAGE_VERSION = '3.1.1';
 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

@@ -603,6 +603,8 @@ export async function initProject(root, opts = {}) {
         next = upsertTomlTableKeyIfAbsent(next, 'agents', 'max_threads = 6');
         next = upsertTomlTableKeyIfAbsent(next, 'agents', 'max_depth = 1');
         for (const block of managedCodexConfigBlocks()) {
+            if (block.preserveExisting === true && hasTomlTable(next, block.table))
+                continue;
             next = upsertTomlTable(next, block.table, block.text);
         }
         // Plugin tables broke the Codex App UI by force-reverting user `enabled=false`.
@@ -797,7 +799,10 @@ export async function initProject(root, opts = {}) {
     }
     function managedCodexConfigBlocks() {
         return [
-            { table: 'mcp_servers.context7', text: context7ConfigToml().trim() },
+            // Context7 credentials may live directly in this table as args/env/headers/url
+            // depending on the user's MCP client setup. Seed the default only when absent;
+            // never replace an existing Context7 block during setup/update.
+            { table: 'mcp_servers.context7', text: context7ConfigToml().trim(), preserveExisting: true },
             { table: 'agents.native_agent', text: agentConfigBlock('native_agent', 'Read-only SKS analysis agent.', './agents/native-agent-intake.toml', ['Analysis', 'Mapper']) },
             { table: 'agents.team_consensus', text: agentConfigBlock('team_consensus', 'SKS planning/debate agent.', './agents/team-consensus.toml', ['Consensus', 'Atlas']) },
             { table: 'agents.implementation_worker', text: agentConfigBlock('implementation_worker', 'SKS bounded implementation worker.', './agents/implementation-worker.toml', ['Builder', 'Mason']) },

package/dist/core/locks/file-lock.js

@@ -0,0 +1,88 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { ensureDir, nowIso, randomId, writeJsonAtomic } from '../fsx.js';
+import { guardedRm, guardContextForRoute } from '../safety/mutation-guard.js';
+import { CONFIRMATION_REQUIRED, REQUESTED_SCOPE_CONTRACT_SCHEMA } from '../safety/requested-scope-contract.js';
+export async function withFileLock(input, fn) {
+    const lockPath = path.resolve(input.lockPath);
+    const timeoutMs = Math.max(1, input.timeoutMs);
+    const staleMs = Math.max(1, input.staleMs);
+    const started = Date.now();
+    const owner = `${process.pid}-${randomId(8)}`;
+    await ensureDir(path.dirname(lockPath));
+    while (true) {
+        try {
+            await fsp.mkdir(lockPath);
+            await writeJsonAtomic(path.join(lockPath, 'owner.json'), {
+                schema: 'sks.file-lock-owner.v1',
+                owner,
+                pid: process.pid,
+                acquired_at: nowIso(),
+                stale_ms: staleMs
+            });
+            break;
+        }
+        catch (err) {
+            const code = errorCode(err);
+            if (code !== 'EEXIST')
+                throw err;
+            await recoverStaleLock(lockPath, staleMs);
+            if (Date.now() - started > timeoutMs) {
+                throw new Error(`file_lock_timeout:${lockPath}`);
+            }
+            await sleep(jitterDelay());
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await removeLockDir(lockPath).catch(() => undefined);
+    }
+}
+async function recoverStaleLock(lockPath, staleMs) {
+    try {
+        const stat = await fsp.stat(lockPath);
+        if (Date.now() - stat.mtimeMs > staleMs) {
+            await removeLockDir(lockPath);
+        }
+    }
+    catch { }
+}
+async function removeLockDir(lockPath) {
+    await guardedRm(guardContextForRoute(process.cwd(), lockScopeContract(lockPath), 'remove SKS file lock directory'), lockPath, {
+        recursive: true,
+        force: true
+    });
+}
+function lockScopeContract(lockPath) {
+    const resolved = path.resolve(lockPath);
+    return {
+        schema: REQUESTED_SCOPE_CONTRACT_SCHEMA,
+        route: 'internal:file-lock',
+        user_request: 'Remove only the current SKS file-lock directory.',
+        allowed_mutations: {
+            project_files: true,
+            global_codex_config: false,
+            codex_app_process: false,
+            codex_lb_auth: false,
+            package_install: false,
+            zellij_install: false,
+            network: false,
+            skill_snapshot_promotion: false
+        },
+        allowed_paths: [resolved, `${resolved}/**`],
+        forbidden_paths: ['~/.codex/config.toml', '/Applications/**'],
+        requires_explicit_confirmation: [...CONFIRMATION_REQUIRED]
+    };
+}
+function jitterDelay() {
+    return 15 + Math.floor(Math.random() * 45);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function errorCode(err) {
+    return err && typeof err === 'object' && 'code' in err ? String(err.code) : '';
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/core/loops/goal-to-loop-compat.js

@@ -0,0 +1,23 @@
+import path from 'node:path';
+import { writeJsonAtomic } from '../fsx.js';
+import { planLoopsFromRequest } from './loop-planner.js';
+export async function compileGoalToLoopPlan(input) {
+    const plan = await planLoopsFromRequest({
+        root: input.root,
+        missionId: input.missionId,
+        request: input.goalText,
+        sourceCommand: 'goal'
+    });
+    await writeJsonAtomic(path.join(input.root, '.sneakoscope', 'missions', input.missionId, 'goal-compat.json'), {
+        schema: 'sks.goal-loop-compat.v1',
+        legacy_goal_text: input.goalText,
+        legacy_goal_options: input.legacyGoalOptions,
+        loop_plan_path: `.sneakoscope/missions/${input.missionId}/loops/loop-plan.json`,
+        loop_graph_proof_path: `.sneakoscope/missions/${input.missionId}/loops/loop-graph-proof.json`,
+        runtime: 'loop-graph',
+        compat_mode: true,
+        generated_at: new Date().toISOString()
+    });
+    return plan;
+}
+//# sourceMappingURL=goal-to-loop-compat.js.map

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

@@ -0,0 +1,72 @@
+import path from 'node:path';
+export function loopRoot(root, missionId) {
+    const missionsRoot = path.resolve(root, '.sneakoscope', 'missions');
+    return containedJoin(missionsRoot, safeArtifactId('mission', missionId), 'loops');
+}
+export function loopNodeRoot(root, missionId, loopId) {
+    return containedJoin(loopRoot(root, missionId), safeArtifactId('loop', loopId));
+}
+export function loopPlanPath(root, missionId) {
+    return path.join(loopRoot(root, missionId), 'loop-plan.json');
+}
+export function loopStatePath(root, missionId, loopId) {
+    return path.join(loopNodeRoot(root, missionId, loopId), 'loop-state.json');
+}
+export function loopRunLogPath(root, missionId, loopId) {
+    return path.join(loopNodeRoot(root, missionId, loopId), 'loop-run-log.jsonl');
+}
+export function loopProofPath(root, missionId, loopId) {
+    return path.join(loopNodeRoot(root, missionId, loopId), 'loop-proof.json');
+}
+export function loopBudgetPath(root, missionId, loopId) {
+    return path.join(loopNodeRoot(root, missionId, loopId), 'loop-budget.json');
+}
+export function loopCheckpointPath(root, missionId, loopId, iteration, phase) {
+    return path.join(loopNodeRoot(root, missionId, loopId), 'checkpoints', `${String(Math.max(1, Math.floor(iteration))).padStart(4, '0')}-${sanitizeArtifactPart(phase)}.json`);
+}
+export function loopLatestCheckpointPath(root, missionId, loopId) {
+    return path.join(loopNodeRoot(root, missionId, loopId), 'checkpoint-latest.json');
+}
+export function loopGraphProofPath(root, missionId) {
+    return path.join(loopRoot(root, missionId), 'loop-graph-proof.json');
+}
+export function loopIntegrationMergePath(root, missionId) {
+    return path.join(loopRoot(root, missionId), 'integration-merge.json');
+}
+export function loopGptFinalArbiterPath(root, missionId) {
+    return path.join(loopRoot(root, missionId), 'loop-gpt-final-arbiter.json');
+}
+export function loopKillRequestPath(root, missionId) {
+    return path.join(loopRoot(root, missionId), 'kill-request.json');
+}
+export function loopGatePath(root, missionId, loopId, gateId) {
+    return path.join(loopNodeRoot(root, missionId, loopId), 'gates', `${sanitizeArtifactPart(gateId)}.json`);
+}
+export function loopPatchPath(root, missionId, loopId, name) {
+    return path.join(loopNodeRoot(root, missionId, loopId), 'patches', `${sanitizeArtifactPart(name)}.json`);
+}
+export function loopHandoffPath(root, missionId, loopId) {
+    return path.join(loopNodeRoot(root, missionId, loopId), 'handoff.md');
+}
+export function loopOwnerLedgerPath(root, missionId) {
+    return path.join(loopRoot(root, missionId), 'loop-owner-ledger.json');
+}
+export function sanitizeArtifactPart(value) {
+    return String(value || 'artifact').replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 96) || 'artifact';
+}
+function safeArtifactId(kind, value) {
+    const text = String(value || '').trim();
+    const sanitized = sanitizeArtifactPart(text);
+    if (!text || sanitized !== text)
+        throw new Error(`invalid_loop_${kind}_id:${text || 'empty'}`);
+    return sanitized;
+}
+function containedJoin(base, ...parts) {
+    const resolvedBase = path.resolve(base);
+    const target = path.resolve(resolvedBase, ...parts);
+    if (target !== resolvedBase && !target.startsWith(`${resolvedBase}${path.sep}`)) {
+        throw new Error(`loop_artifact_path_escape:${target}`);
+    }
+    return target;
+}
+//# sourceMappingURL=loop-artifacts.js.map

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

@@ -0,0 +1,22 @@
+import { readJson, writeJsonAtomic } from '../fsx.js';
+import { loopCheckpointPath, loopLatestCheckpointPath } from './loop-artifacts.js';
+export async function writeLoopCheckpoint(input) {
+    const checkpoint = {
+        schema: 'sks.loop-checkpoint.v1',
+        mission_id: input.mission_id,
+        loop_id: input.loop_id,
+        iteration: input.iteration,
+        phase: input.phase,
+        state_path: input.state_path,
+        proof_path: input.proof_path,
+        resumable: input.resumable,
+        created_at: new Date().toISOString()
+    };
+    await writeJsonAtomic(loopCheckpointPath(input.root, input.mission_id, input.loop_id, input.iteration, input.phase), checkpoint);
+    await writeJsonAtomic(loopLatestCheckpointPath(input.root, input.mission_id, input.loop_id), checkpoint);
+    return checkpoint;
+}
+export async function readLatestLoopCheckpoint(root, missionId, loopId) {
+    return readJson(loopLatestCheckpointPath(root, missionId, loopId), null);
+}
+//# sourceMappingURL=loop-checkpoint.js.map

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

@@ -0,0 +1,56 @@
+export const LOOP_DOMAIN_RULES = [
+    { id: 'zellij', dirs: ['src/core/zellij', 'src/scripts/zellij-'], gates: ['zellij:*'] },
+    { id: 'release', dirs: ['src/core/release', 'src/scripts/release-', 'release-gates.v2.json'], gates: ['release:*'] },
+    { id: 'research', dirs: ['src/core/research', 'src/scripts/research-'], gates: ['research:*'] },
+    { id: 'qa-loop', dirs: ['src/core/qa-loop', 'src/core/commands/qa-loop-command.ts'], gates: ['qa-loop:*'] },
+    { id: 'naruto', dirs: ['src/core/naruto', 'src/core/commands/naruto-command.ts'], gates: ['naruto:*'] },
+    { id: 'codex-control', dirs: ['src/core/codex-control', 'src/scripts/codex-'], gates: ['codex:*', 'codex-sdk:*'] },
+    { id: 'image', dirs: ['src/core/image', 'src/core/image-generation'], gates: ['image:*'] },
+    { id: 'mad-db', dirs: ['src/core/mad-db', 'src/core/db-safety.ts'], gates: ['mad-db:*'] },
+    { id: 'docs', dirs: ['docs', 'README.md', 'CHANGELOG.md'], gates: ['docs:*', 'changelog:check'] }
+];
+export function decomposeRequestIntoLoopDomains(request, changedFiles = []) {
+    const text = `${request} ${changedFiles.join(' ')}`.toLowerCase();
+    const explicitFiles = extractFilePaths(request).concat(changedFiles).filter(Boolean);
+    const selected = new Map();
+    for (const rule of LOOP_DOMAIN_RULES) {
+        const matchedByText = [rule.id, ...domainAliases(rule.id)].some((needle) => text.includes(needle))
+            || rule.dirs.some((dir) => text.includes(dir.toLowerCase()) || text.includes(lastPart(dir)));
+        const matchedFiles = explicitFiles.filter((file) => rule.dirs.some((dir) => file === dir || file.startsWith(dir.replace(/\*+$/, ''))));
+        if (!matchedByText && matchedFiles.length === 0)
+            continue;
+        selected.set(rule.id, {
+            id: rule.id,
+            dirs: rule.dirs.filter((dir) => !dir.includes('*')),
+            files: matchedFiles,
+            gates: rule.gates
+        });
+    }
+    if (selected.size === 0 && explicitFiles.length) {
+        selected.set('loop-general-coding', { id: 'loop-general-coding', dirs: [], files: explicitFiles, gates: ['loop:affected'] });
+    }
+    if (selected.size === 0) {
+        selected.set('loop-general-coding', { id: 'loop-general-coding', dirs: ['src'], files: [], gates: ['loop:affected'] });
+    }
+    return [...selected.values()];
+}
+function extractFilePaths(request) {
+    return [...request.matchAll(/(?:^|\s)([A-Za-z0-9_.@/-]+\.(?:ts|tsx|js|mjs|json|md|toml|yml|yaml))(?:\s|$)/g)]
+        .map((match) => match[1])
+        .filter((value) => Boolean(value));
+}
+function lastPart(value) {
+    return value.split('/').at(-1)?.replace(/[^a-z0-9-]/gi, '').toLowerCase() || value.toLowerCase();
+}
+function domainAliases(id) {
+    if (id === 'codex-control')
+        return ['codex', 'probe', 'capability'];
+    if (id === 'release')
+        return ['cache', 'gate', 'dag'];
+    if (id === 'docs')
+        return ['doc', 'docs', 'readme', 'changelog'];
+    if (id === 'qa-loop')
+        return ['qa'];
+    return [];
+}
+//# sourceMappingURL=loop-decomposer.js.map

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

@@ -0,0 +1,54 @@
+import { readJson, writeJsonAtomic } from '../fsx.js';
+import { loopGraphProofPath, loopProofPath } from './loop-artifacts.js';
+import { runLoopGptFinalArbiter } from './loop-gpt-final-arbiter.js';
+import { mergeLoopWorktrees } from './loop-integration-merge.js';
+import { graphProofFromLoopProofs } from './loop-scheduler.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));
+    const graph = graphProofFromLoopProofs({
+        missionId: input.plan.mission_id,
+        proofs: realProofs,
+        maxActiveLoops: input.maxActiveLoops || 1,
+        maxActiveWorkers: input.maxActiveWorkers || Math.max(1, realProofs.reduce((sum, proof) => sum + proof.maker_result.worker_count + proof.checker_result.worker_count, 0)),
+        wallMs: input.wallMs || 1
+    });
+    const integrationMerge = await mergeLoopWorktrees({
+        root: input.root,
+        plan: input.plan,
+        proofs: realProofs
+    });
+    const anyHandoff = realProofs.some((proof) => proof.handoff.required);
+    const anySourceMutation = realProofs.some((proof) => proof.changed_files.some((file) => !file.startsWith('.sneakoscope/')));
+    const arbiter = anySourceMutation
+        ? await runLoopGptFinalArbiter({ root: input.root, plan: input.plan, proofs: realProofs, integrationMerge })
+        : null;
+    const blockers = [
+        ...graph.blockers,
+        ...(anyHandoff ? ['loop_handoff_required'] : []),
+        ...(integrationMerge.ok ? [] : integrationMerge.blockers),
+        ...(anySourceMutation && !arbiter ? ['gpt_final_arbiter_missing'] : []),
+        ...(arbiter && !arbiter.ok ? ['gpt_final_arbiter_not_approved', ...arbiter.blockers] : [])
+    ];
+    const finalGraph = {
+        ...graph,
+        ok: graph.ok && blockers.length === 0,
+        blockers: [...new Set(blockers)],
+        integration_merge: {
+            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
+        },
+        ...(arbiter ? {
+            gpt_final_arbiter: {
+                ok: arbiter.ok,
+                artifact_path: arbiter.artifact_path,
+                verdict: arbiter.verdict
+            }
+        } : {})
+    };
+    await writeJsonAtomic(loopGraphProofPath(input.root, input.plan.mission_id), finalGraph);
+    return finalGraph;
+}
+//# sourceMappingURL=loop-finalizer.js.map