micro-models-agent 2.10.0 → 2.12.0

package/dist/modules/execution/tracker.js

@@ -1,36 +1,48 @@
+// Трекер плана: указатель текущего шага, статусы, прогресс-строка.
+// Двигает указатель мимо уже settled (skipped/done) шагов, не мутируя их —
+// перезапись "skipped" в "in_progress" дедлочит план (модель не возьмётся за
+// шаг, который осознанно пропустила).
 import { PlanCreator, getPlanProgress } from "./planner";
+/** Трекер плана: указатель, статусы шагов, прогресс. */
 export class PlanTracker {
     plan;
     currentStepIndex = 0;
     constructor(plan) {
         this.plan = plan;
     }
+    /** План целиком. */
     getPlan() {
         return this.plan;
     }
+    /** Индекс текущего шага. */
     getCurrentStepIndex() {
         return this.currentStepIndex;
     }
+    /** Текущий шаг (по указателю). */
     getCurrentStep() {
         return this.plan.steps[this.currentStepIndex];
     }
+    /** Шаг по id. */
     getStep(id) {
         return this.plan.steps.find((s) => s.id === id);
     }
+    /** Ставит статус шагу. */
     updateStepStatus(id, status) {
         const step = this.getStep(id);
         if (step)
             step.status = status;
     }
+    /** Добавляет заметку к шагу. */
     addNote(id, note) {
         const step = this.getStep(id);
         if (step)
             step.note = note;
     }
+    /**
+     * Двигает указатель к следующему незакрытому шагу (мимо done/skipped без
+     * мутаций). False, если шагов не осталось.
+     */
     advance() {
-        // Move past any already-settled (skipped/done) steps without mutating
-        // them — overwriting a "skipped" step with "in_progress" deadlocks the
-        // plan (the model will never work on a step it deliberately skipped).
         let idx = this.currentStepIndex + 1;
         while (idx < this.plan.steps.length &&
             (this.plan.steps[idx].status === "skipped" || this.plan.steps[idx].status === "done")) {
@@ -45,11 +57,10 @@ export class PlanTracker {
         return true;
     }
     /**
-     * Advance the pointer past any done/skipped steps without mutating their
-     * status. Keeps currentStepIndex in sync when the model marks steps done via
-     * the `plan update` tool (which never calls advance()). Without this,
-     * getCurrentStep() stays on the first step forever and the stuck detector
-     * accumulates false-positive "no progress" warnings.
+     * Подтягивает указатель мимо done/skipped шагов без смены статусов.
+     * Синхронизирует currentStepIndex, когда модель маркит шаги через тул
+     * `plan update` (он advance() не зовёт). Без этого getCurrentStep() вечно
+     * стоит на первом шаге и stuck-детектор копит ложные "no progress".
      */
     syncCurrentStep() {
         while (this.currentStepIndex < this.plan.steps.length - 1 &&
@@ -58,9 +69,11 @@ export class PlanTracker {
             this.currentStepIndex++;
         }
     }
+    /** True, если все шаги done/skipped. */
     isComplete() {
         return this.plan.steps.every((s) => s.status === "done" || s.status === "skipped");
     }
+    /** Строка прогресса: `[id] title settled/total (skipped) bar pct`. */
     getProgressString() {
         const p = getPlanProgress(this.plan);
         const total = p.total;
@@ -72,6 +85,7 @@ export class PlanTracker {
         const skippedPart = p.skipped > 0 ? ` (${p.skipped} skipped)` : "";
         return `[${this.plan.id}] ${this.plan.title}  ${settled}/${total}${skippedPart}  ${bar}  ${pct}%`;
     }
+    /** Промпт-блок плана с текущей позиции указателя. */
     toPromptBlock() {
         return PlanCreator.toPromptBlock(this.plan, this.currentStepIndex);
     }

package/dist/modules/execution/verifier.js

@@ -1,3 +1,4 @@
+// Верификатор шагов: файлы, синтаксис, скрипты, typecheck, success_criteria.
 import { existsSync, readFileSync } from "fs";
 import { resolve, extname, dirname, join } from "path";
 import { spawn } from "child_process";
@@ -6,19 +7,27 @@ import { validateExpertConfig } from "../../config/experts";
 import { findProjectRoot, resolveTscCommand } from "../lsp/project-root";
 import { extractFileLikeTokens, stripUrls } from "../hallucination/js-identifiers";
 import { findExistingFile } from "./auditor";
+import { findTypecheckRoot } from "./audit-runners";
+import { killTree } from "../processes/kill-tree";
+import { settleChildClose } from "../../utils/child-run";
+/** Верификатор шагов и MoE-планов: файлы, синтаксис, скрипты, tsc, критерии. */
 export class StepVerifier {
     baseDir;
     constructor(baseDir) {
         this.baseDir = baseDir;
     }
+    /** Проверяет существование файла (с nested-резолвером findExistingFile). */
     async checkFileExists(path) {
-        const resolved = resolve(this.baseDir, path);
-        const exists = existsSync(resolved);
+        // Nested-aware (тот же резолвер, что в verifyStep): проект в
+        // `baseDir/proj/` нельзя репортить пропавшим, если файл ниже.
+        const resolved = findExistingFile(this.baseDir, path);
+        const exists = !!resolved;
         return {
             passed: exists,
             message: exists ? t("verify.file_exists", { path }) : t("verify.file_not_found", { path }),
         };
     }
+    /** Запускает `bun run <script>` (60s), возвращает пункт проверки. */
     async runScript(scriptName) {
         try {
             await this.runAsync(`bun run ${scriptName}`, this.baseDir, 60_000);
@@ -31,75 +40,88 @@ export class StepVerifier {
             };
         }
     }
-    async runTypeCheck() {
-        const tsconfigPath = resolve(this.baseDir, "tsconfig.json");
+    /** Проектный typecheck (tsc --noEmit); без tsconfig/tsc — пропуск, не фейл. */
+    async runTypeCheck(existingFiles = []) {
+        // Корень проекта резолвим и по артефактам: проект во вложенном
+        // `baseDir/proj/` надо типчекать, а не скипать ("No tsconfig.json found") —
+        // старый поиск только от baseDir его не видел.
+        const root = findTypecheckRoot(this.baseDir, existingFiles) ?? this.baseDir;
+        const tsconfigPath = join(root, "tsconfig.json");
         if (!existsSync(tsconfigPath)) {
-            return { passed: true, message: "No tsconfig.json found — skipping type check" };
+            return { passed: true, message: t("verify.typecheck_skipped_no_tsconfig") };
         }
-        const tsc = resolveTscCommand(this.baseDir);
+        const tsc = resolveTscCommand(root);
         if (!tsc)
-            return { passed: true, message: "tsc not installed — skipping type check" };
+            return { passed: true, message: t("verify.typecheck_skipped_no_tsc") };
         try {
-            await this.runAsync(`${tsc} --noEmit`, this.baseDir, 60_000);
-            return { passed: true, message: "TypeScript type check passed" };
+            await this.runAsync(`${tsc} --noEmit`, root, 60_000);
+            return { passed: true, message: t("verify.typecheck_passed") };
         }
         catch (e) {
             const stderr = e.stderr?.toString() || e.stdout?.toString() || e.message;
-            return { passed: false, message: `TypeScript type check failed: ${stderr.slice(0, 500)}` };
+            return {
+                passed: false,
+                message: t("verify.typecheck_failed", { error: stderr.slice(0, 500) }),
+            };
         }
     }
     /**
-     * Type-check a specific file, resolving the project root from the FILE's
-     * location (not the agent baseDir). For nested layouts (`baseDir/proj/` with
-     * its own tsconfig.json) the old baseDir-based check silently skipped every
-     * type error (observed in ses_mst2r0r5: zero type feedback for the whole
-     * session). Markers mirror the TypeScript LSP server config.
+     * Типчекает конкретный файл, резолвя корень проекта от РАСПОЛОЖЕНИЯ ФАЙЛА
+     * (не от baseDir агента). Для вложенных раскладок (`baseDir/proj/` со своим
+     * tsconfig.json) старая проверка от baseDir молча скипала каждую ошибку типов
+     * (было в ses_mst2r0r5: ноль type feedback за всю сессию). Маркеры зеркалят
+     * конфиг TypeScript LSP-сервера.
      */
     async runTypeCheckForFile(filePath) {
         const projectRoot = findProjectRoot(filePath, this.baseDir, ["tsconfig.json", "package.json"]);
         const tsconfigPath = join(projectRoot, "tsconfig.json");
         if (!existsSync(tsconfigPath)) {
-            return { passed: true, message: "No tsconfig.json found — skipping type check" };
+            return { passed: true, message: t("verify.typecheck_skipped_no_tsconfig") };
         }
         const tsc = resolveTscCommand(projectRoot);
         if (!tsc)
-            return { passed: true, message: "tsc not installed — skipping type check" };
+            return { passed: true, message: t("verify.typecheck_skipped_no_tsc") };
         try {
             await this.runAsync(`${tsc} --noEmit --skipLibCheck`, projectRoot, 60_000);
-            return { passed: true, message: "TypeScript type check passed" };
+            return { passed: true, message: t("verify.typecheck_passed") };
         }
         catch (e) {
             const stderr = e.stderr?.toString() || e.stdout?.toString() || e.message;
-            return { passed: false, message: `TypeScript type check failed: ${stderr.slice(0, 500)}` };
+            return {
+                passed: false,
+                message: t("verify.typecheck_failed", { error: stderr.slice(0, 500) }),
+            };
         }
     }
+    /** Запускает `test`-скрипт проекта; без package.json/скрипта — пропуск. */
     async runTests() {
         const pkgPath = resolve(this.baseDir, "package.json");
         if (!existsSync(pkgPath)) {
-            return { passed: true, message: "No package.json found — skipping tests" };
+            return { passed: true, message: t("verify.tests_skipped_no_package") };
         }
         try {
             const pkg = JSON.parse(require("fs").readFileSync(pkgPath, "utf-8"));
             if (!pkg.scripts?.test) {
-                return { passed: true, message: "No test script defined — skipping tests" };
+                return { passed: true, message: t("verify.tests_skipped_no_script") };
             }
         }
         catch {
-            /* fall through — attempt to run */
+            /* fall through — пробуем запустить */
         }
         return this.runScript("test");
     }
+    /** Проверяет существование списка файлов-артефактов (параллельно). */
     async verifyArtifactFiles(files) {
         return Promise.all(files.map((f) => this.checkFileExists(f)));
     }
     /**
-     * Check a subtask's machine-readable success_criteria BEFORE the merge
-     * decision (Plan 5.1). Supported forms:
+     * Проверяет machine-readable success_criteria подзадачи ДО решения о merge
+     * (Plan 5.1). Поддержаны формы:
      * - `file-exists:<path>`
      * - `substring-in-file:<path>:<text>`
      * - `command-exit-0:<command>`
-     * Anything else is treated as an LLM-only criterion and reported as a
-     * warning (never an error) so the Router still sees it in context.
+     * Остальное — LLM-only критерий: варнинг (не ошибка), чтобы Router всё равно
+     * видел его в контексте.
      */
     async verifySubtaskCriteria(subtask) {
         const errors = [];
@@ -161,6 +183,7 @@ export class StepVerifier {
         }
         return { errors, warnings, details };
     }
+    /** Верифицирует MoE-манифест: эксперты, typecheck, файлы и критерии подзадач. */
     async verifyMoEManifest(plan, config, allToolTags) {
         const errors = [];
         const warnings = [];
@@ -170,7 +193,11 @@ export class StepVerifier {
             errors.push(err);
             details.push({ passed: false, message: err });
         }
-        const tscResult = await this.runTypeCheck();
+        const existingArtifacts = plan.subtasks
+            .flatMap((s) => s.allowed_files || [])
+            .map((f) => findExistingFile(this.baseDir, f))
+            .filter((f) => !!f);
+        const tscResult = await this.runTypeCheck(existingArtifacts);
         details.push(tscResult);
         if (!tscResult.passed) {
             errors.push(tscResult.message);
@@ -183,7 +210,7 @@ export class StepVerifier {
                     errors.push(check.message);
                 }
             }
-            // Machine-readable success_criteria (Plan 5.1) — checked before merge.
+            // Machine-readable success_criteria (Plan 5.1) — проверяются до merge.
             const criteria = await this.verifySubtaskCriteria(sub);
             errors.push(...criteria.errors);
             warnings.push(...criteria.warnings);
@@ -196,11 +223,12 @@ export class StepVerifier {
             details,
         };
     }
+    /** Верифицирует шаг: файлы из описания существуют (+синтаксис; delete — наоборот). */
     async verifyStep(stepDescription, kind) {
         const fileMatches = extractFileLikeTokens(stripUrls(stepDescription));
-        // No named files — this step cannot be verified by file existence. Do NOT
-        // trivially pass (empty every() = true); signal noFiles so the tool guides
-        // the model to run a real check instead.
+        // Нет именованных файлов — шаг непроверяем по существованию. НЕ пропускаем
+        // тривиально (пустой every() = true); сигналим noFiles, чтобы тул вёл
+        // модель к настоящей проверке.
         if (fileMatches.length === 0) {
             return { passed: false, syntaxValid: true, failed: [], noFiles: true };
         }
@@ -210,17 +238,17 @@ export class StepVerifier {
             const resolved = findExistingFile(this.baseDir, filePath);
             const exists = !!resolved;
             if (kind === "delete") {
-                // For delete steps: file NOT existing is a pass
+                // Для delete-шагов: отсутствие файла — pass
                 results.push({
                     passed: !exists,
                     message: exists
                         ? t("verify.file_still_exists", { path: filePath })
                         : t("verify.file_not_found", { path: filePath }),
                 });
-                // Don't syntax-check a deleted file
+                // Удалённый файл синтаксически не проверяем
                 continue;
             }
-            // Create steps: file must exist + valid syntax
+            // Create-шаги: файл обязан существовать + валидный синтаксис
             if (!exists) {
                 results.push({ passed: false, message: t("verify.file_not_found", { path: filePath }) });
                 continue;
@@ -248,7 +276,7 @@ export class StepVerifier {
             if (!tsc)
                 return true;
             try {
-                // Quote the path — commands run through a shell and break on spaces.
+                // Путь в кавычках — команды идут через shell и ломаются на пробелах.
                 await this.runAsync(`${tsc} --noEmit --skipLibCheck "${filePath}"`, this.baseDir, 20000);
                 return true;
             }
@@ -277,8 +305,8 @@ export class StepVerifier {
         return true;
     }
     /**
-     * Run a command asynchronously (non-blocking event loop) and resolve when it
-     * exits. Rejects with the captured stderr/stdout on non-zero exit or timeout.
+     * Запускает команду асинхронно (не блокируя event loop) и резолвится на
+     * выходе. На ненулевой exit или таймаут — reject с захваченными stderr/stdout.
      */
     runAsync(command, cwd, timeoutMs) {
         return new Promise((resolve, reject) => {
@@ -297,7 +325,9 @@ export class StepVerifier {
                 stderr += d.toString();
             });
             const timer = setTimeout(() => {
-                child.kill();
+                // Убиваем всё дерево: при shell:true child.kill() останавливает только
+                // shell, а реальный внук tsc/node продолжает висеть.
+                killTree(child);
                 reject(new Error(`Command timed out after ${timeoutMs}ms`));
             }, timeoutMs);
             child.on("error", (err) => {
@@ -306,16 +336,7 @@ export class StepVerifier {
             });
             child.on("close", (code) => {
                 clearTimeout(timer);
-                if (code === 0) {
-                    resolve({ stdout, stderr });
-                }
-                else {
-                    const err = new Error(`Command failed with exit code ${code}`);
-                    err.stdout = stdout;
-                    err.stderr = stderr;
-                    err.status = code;
-                    reject(err);
-                }
+                settleChildClose(code, stdout, stderr, `Command failed with exit code ${code}`, resolve, reject);
             });
         });
     }

package/dist/modules/execution/windows-commands.js

@@ -1,17 +1,17 @@
 /**
- * Unix commands that do not exist (or have incompatible semantics) in Windows
- * cmd.exe. The 9B model keeps reaching for grep/sed/ls/find via the bash tool;
- * each failure returns a hint, but the model retries.
+ * Unix-команды, которых нет в Windows cmd.exe (или семантика несовместима).
+ * 9B-модель тянется к grep/sed/ls/find через тул bash; каждый фейл возвращает
+ * хинт, но модель ретраит.
  *
- * This is a session-level, module-side companion to the bash tool's own
- * per-command hard-stop (`UNIX_TO_WIN_HINTS` / `FAILING_FIRST_WORDS` /
- * `HARD_BLOCK_THRESHOLD` in src/tools/bash.ts). That mechanism injects
- * "STOP using X" INTO the tool output, which a 9B model tends to ignore; this
- * one, gated to win32 like bash.ts, queues a <system-summary> that lands
- * before the next model call. Keep the two command lists consistent.
+ * Сессионный модульный компаньон пер-командного hard-stop самого тула bash
+ * (`UNIX_TO_WIN_HINTS` / `FAILING_FIRST_WORDS` / `HARD_BLOCK_THRESHOLD` в
+ * src/tools/bash.ts). Тот механизм инжектит "STOP using X" В вывод тула,
+ * который 9B-модель склонна игнорировать; этот, гейченный на win32 как bash.ts,
+ * кладёт <system-summary> перед следующим вызовом модели. Списки команд держим
+ * синхронно.
  *
- * This is a command allow/deny list (like the security module's command
- * blacklist), NOT task classification (rule #10).
+ * Это allow/deny-список команд (как чёрный список команд security-модуля),
+ * НЕ классификация задач (правило #10).
  */
 const FORBIDDEN_COMMANDS = new Set([
     "grep",
@@ -40,7 +40,7 @@ function firstWord(command) {
     const segs = command.trim().split(/[\s;|&]+/);
     return (segs[0] || "").replace(/[^\w-]/g, "").toLowerCase();
 }
-/** The forbidden command name if `command` starts with one (handles `cd x && …`). */
+/** Имя запрещённой команды, если `command` с неё начинается (понимает `cd x && …`). */
 export function forbiddenWindowsCommand(command) {
     const m = command.match(/^\s*cd\s+\S+\s*&&\s*(\S+)/);
     if (m)

package/dist/modules/hallucination/artifact-claim.js

@@ -0,0 +1,93 @@
+/**
+ * Проверки заявлений об артефактах (ses_mul5pepu_9mdq90): qwen3.5-9b записала fizzbuzz.py,
+ * не смогла запустить (python в чёрном списке), затем вставила "ожидаемый" вывод
+ * программы с неверными значениями как якобы реальный; также записала schema.drawio
+ * с битым `<diagram/>` + висячим `</diagram>` и заявила "валидный XML".
+ * Проверка success-claim срабатывает только на сигналы ошибок в выводах тулов,
+ * поэтому оба случая прошли молча.
+ *
+ * Две детерминированные проверки (regex + состояние диска от вызывающего, без LLM):
+ * - `checkArtifactClaims`: ответ подаёт файл как созданный/валидный, а на диске
+ *   его нет или он не парсится.
+ * - `checkUnverifiedOutput`: ответ подаёт кодовый блок как реальный вывод
+ *   программы, но ни один тул в окне доказательств ничего успешно не исполнял.
+ *
+ * Чистые функции — состояние диска (`ArtifactState[]`) резолвит вызывающий
+ * (цикл агента, владелец baseDir), модуль остаётся тестируемым.
+ * Точность смещена в сторону recall, как в success-claim.ts: ложное срабатывание
+ * стоит одну ограниченную re-check итерацию, пропуск — статус-кво.
+ */
+const WORD = "A-Za-zА-Яа-яЁё0-9_";
+const wb = (body) => new RegExp(`(?<![${WORD}])(?:${body})(?![${WORD}])`, "i");
+/** Язык успеха про файл (любая локаль, на которой говорит агент). */
+const ARTIFACT_SUCCESS_RE = wb("создан[а-яё]*|записан[а-яё]*|сохран[её]н[а-яё]*|готов[а-яё]*|валид[а-яё]*|проверен[а-яё]*|существует|valid(?:ated)?|verified|checked|written|saved|created|exists?|ready");
+/**
+ * Каким словом успеха (если есть) ответ описывает упоминание файла.
+ * Возвращает найденное слово для точного retry-сообщения.
+ */
+function claimedAs(response, path) {
+    const idx = response.toLowerCase().indexOf(path.toLowerCase());
+    if (idx === -1)
+        return null;
+    // Смотрим окно вокруг упоминания — заявление обычно в том же
+    // предложении ("Файл schema.drawio создан и валиден").
+    const window = response.slice(Math.max(0, idx - 160), idx + path.length + 160);
+    const m = window.match(ARTIFACT_SUCCESS_RE);
+    return m ? m[0] : null;
+}
+/**
+ * Возвращает противоречие, если ответ подаёт резолвленный артефакт как
+ * созданный/валидный, а на диске его нет или он не парсится.
+ */
+export function checkArtifactClaims(response, artifacts) {
+    if (!response)
+        return null;
+    for (const a of artifacts) {
+        const claim = a.claim ?? claimedAs(response, a.path);
+        if (!claim)
+            continue;
+        if (!a.exists) {
+            return {
+                tool: "disk",
+                path: a.path,
+                snippet: `${a.path}: file not found on disk, claimed "${claim}"`,
+            };
+        }
+        if (a.parseError) {
+            return {
+                tool: "disk",
+                path: a.path,
+                snippet: `${a.path}: ${a.parseError}, claimed "${claim}"`,
+            };
+        }
+    }
+    return null;
+}
+/** Фразы, подающие кодовый блок как РЕАЛЬНЫЙ вывод исполнения (не пример). */
+const OUTPUT_AS_RESULT_RE = wb("вывод программы|вывод команды|результат запуска|результат выполнения|program output|command output|execution result|запустил[а-яё]*.*вывод|покажу вывод|actual output");
+/** Хеджирование, понижающее блок до ожидания/примера — честно, пропускаем. */
+const OUTPUT_HEDGE_RE = wb("ожидаем[а-яё]*|expected|пример[а-яё]*|example|для справки|sample|например|предполагаем[а-яё]*|должен быть|should be");
+const FENCE_RE = /```/;
+/** Тулы, чей успех означает "что-то реально исполнилось". */
+const EXEC_TOOLS = new Set(["bash", "process_wait", "pipeline_run"]);
+/**
+ * Возвращает противоречие, если ответ показывает вывод как результат запуска,
+ * но ни один exec-тул в окне доказательств успешно не отработал.
+ */
+export function checkUnverifiedOutput(response, tools) {
+    if (!response || !OUTPUT_AS_RESULT_RE.test(response))
+        return null;
+    if (OUTPUT_HEDGE_RE.test(response))
+        return null;
+    if (!FENCE_RE.test(response))
+        return null;
+    const recent = tools.filter((t) => t.text?.trim()).slice(-10);
+    const executed = recent.some((t) => t.ok === true && t.name !== undefined && EXEC_TOOLS.has(t.name));
+    if (executed)
+        return null;
+    const m = response.match(OUTPUT_AS_RESULT_RE);
+    return {
+        tool: "no-execution",
+        snippet: `claimed "${m?.[0] ?? "output"}" with no successful execution tool in evidence`,
+    };
+}

package/dist/modules/hallucination/confidence.js

@@ -1,17 +1,19 @@
 import { t } from "../../i18n/index";
 const MIN_CHARS = 1;
-/** Both responses must be this long before repetition applies — a short
- *  honest answer ("Done." / "The build passes.") repeated twice is not
- *  degeneration and must not burn a hallucination retry. */
+/** Оба ответа должны быть не короче — короткий честный ответ ("Готово.") дважды
+ *  подряд не деградация и не должен жечь hallucination-retry. */
 const MIN_REPEAT_CHARS = 120;
 const MIN_REPEAT_WORDS = 20;
-/** Word-overlap above this threshold counts as repetition (was 0.5). */
+/** Пересечение слов выше порога считается повтором (было 0.5). */
 const REPEAT_OVERLAP_THRESHOLD = 0.8;
+/** Проверка уверенности: пустой ответ, дословный повтор, низкая diversity. */
 export class ConfidenceCheck {
     previousResponse = "";
+    /** Запоминает предыдущий ответ для детекции повторов. */
     setPreviousResponse(response) {
         this.previousResponse = response;
     }
+    /** Валидирует ответ: retry на пустоту/повтор, warn на низкую diversity, иначе pass. */
     validate(response) {
         if (!response || response.length < MIN_CHARS) {
             return {
@@ -20,13 +22,13 @@ export class ConfidenceCheck {
                 reason: t("hall.short_response"),
             };
         }
-        // Short replies are not flagged: a greeting, a terse acknowledgement or a
-        // one-line confirmation is a valid answer. Real truncation is caught by the
-        // provider's finish_reason ("length"), and emptiness by the retry above.
+        // Короткие реплики не флагуются: приветствие, скупое подтверждение или
+        // однострочник — валидный ответ. Реальное усечение ловит finish_reason
+        // провайдера ("length"), пустоту — retry выше.
         const wordCount = response.split(/\s+/).filter(Boolean).length;
-        // Language-agnostic: repetition detection via word overlap. Only flag when
-        // BOTH the current and the previous response are substantive — a short
-        // answer after a long one (or two short answers) is not a loop.
+        // Языконезависимо: детекция повторов по пересечению слов. Флагуем только
+        // если ОБА ответа содержательные — короткий ответ после длинного (или два
+        // коротких) не цикл.
         if (this.previousResponse) {
             const prevWords = this.previousResponse.split(/\s+/).filter(Boolean).length;
             const bothSubstantive = response.length >= MIN_REPEAT_CHARS &&
@@ -44,7 +46,7 @@ export class ConfidenceCheck {
                 }
             }
         }
-        // Language-agnostic: very low word diversity (same words repeated)
+        // Языконезависимо: очень низкая diversity слов (одни и те же слова по кругу)
         const words = response
             .toLowerCase()
             .split(/\s+/)

package/dist/modules/hallucination/consistency.js

@@ -1,28 +1,36 @@
+/** Проверка консистентности: решения, созданные/удалённые файлы сессии. */
 export class ConsistencyCheck {
     decisions = [];
     createdFiles = new Set();
     deletedFiles = new Set();
+    /** Запоминает решение агента. */
     trackDecision(decision, location) {
         this.decisions.push({ decision, location });
     }
+    /** Отмечает созданный файл (снимает с него флаг удалённого). */
     trackCreatedFile(path) {
         this.createdFiles.add(path);
-        // A delete followed by a re-create un-deletes the file — otherwise
-        // wasFileDeleted() keeps reporting it as gone after delete+create.
+        // Удаление с последующим пересозданием снимает флаг — иначе wasFileDeleted()
+        // считает файл пропавшим и после delete+create.
         this.deletedFiles.delete(path);
     }
+    /** Отмечает удалённый файл. */
     trackDeletedFile(path) {
         this.deletedFiles.add(path);
     }
+    /** Все созданные файлы. */
     getCreatedFiles() {
         return Array.from(this.createdFiles);
     }
+    /** Все удалённые файлы. */
     getDeletedFiles() {
         return Array.from(this.deletedFiles);
     }
+    /** Все отслеживаемые решения. */
     getDecisions() {
         return this.decisions;
     }
+    /** True, если есть хоть одно решение. */
     hasDecisions() {
         return this.decisions.length > 0;
     }

package/dist/modules/hallucination/detector.js

@@ -1,7 +1,9 @@
+// Оркестратор проверок галлюцинаций: confidence → factual → LLM-судья.
 import { ConsistencyCheck } from "./consistency";
 import { ConfidenceCheck } from "./confidence";
 import { FactualCheck } from "./factual";
 import { LLMJudge } from "./llm-judge";
+/** Детектор галлюцинаций: объединяет проверки уверенности, фактов и LLM-судью. */
 export class HallucinationDetector {
     consistency;
     confidence;
@@ -11,22 +13,25 @@ export class HallucinationDetector {
         this.consistency = new ConsistencyCheck();
         this.confidence = new ConfidenceCheck();
         this.factual = baseDir ? new FactualCheck(baseDir) : null;
-        // The judge is opt-out: it only runs when a provider is supplied AND the
-        // caller did not explicitly disable it (the main agent disables it by
-        // default via config.hallucination.judge.enabled).
+        // Судья opt-out: работает только если передан провайдер И вызывающий явно
+        // его не отключил (главный агент отключает по умолчанию через
+        // config.hallucination.judge.enabled).
         const judgeEnabled = options?.judgeEnabled ?? true;
         this.judge = llmProvider && judgeEnabled ? new LLMJudge(llmProvider) : null;
     }
+    /** Доступ к проверке консистентности (решения, созданные/удалённые файлы). */
     getConsistencyCheck() {
         return this.consistency;
     }
+    /** Доступ к проверке уверенности (повторы, diversity). */
     getConfidenceCheck() {
         return this.confidence;
     }
-    /** Add files known from compaction summaries to the factual checker. */
+    /** Добавляет файлы, известные из сводок компакции, в фактическую проверку. */
     addKnownFiles(files) {
         this.factual?.addKnownFiles(files);
     }
+    /** Валидирует ответ: retry/block уверенности → факты → LLM-судья + warn-агрегация. */
     async validate(response) {
         const confidenceResult = this.confidence.validate(response);
         if (confidenceResult.status === "retry" || confidenceResult.status === "block") {
@@ -37,7 +42,7 @@ export class HallucinationDetector {
         if (factualResult && factualResult.status !== "pass") {
             return factualResult;
         }
-        // LLM-as-judge consistency: fast path (no decisions) skips any LLM call.
+        // Судья по консистентности (LLM): быстрый путь (нет решений) — без LLM-вызова.
         const judgeResult = this.judge ? await this.judge.validate(response, this.consistency) : null;
         const warnings = [];
         if (judgeResult && judgeResult.status === "warn")