devcontour-harness 0.0.0-stage → 0.1.0-alpha.6

package/lib/contracts/version.js

@@ -0,0 +1,17 @@
+/**
+ * Версии договоров. Они независимы: смена формата состояния не обязана
+ * менять API, а новая версия пакета не меняет формат молча.
+ *
+ * - `apiVersion` — формат публичных входов/выходов (WorkOrder, RunResult...).
+ * - `stateVersion` — формат сохранённого состояния исполнения.
+ * - `policyVersion` — формат ExecutionPolicy; входит в digest политики.
+ *
+ * Пакет читает только перечисленные версии. Неизвестная версия отклоняется
+ * до любой мутации состояния и до выдачи claim.
+ */
+export const API_VERSION = 'devcontour-harness/v1alpha1';
+export const SUPPORTED_API_VERSIONS = [API_VERSION];
+export const STATE_VERSION = 1;
+export const SUPPORTED_STATE_VERSIONS = [STATE_VERSION];
+export const POLICY_VERSION = 1;
+export const SUPPORTED_POLICY_VERSIONS = [POLICY_VERSION];

package/lib/contracts/work.d.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+import type { ErrorIssue } from './errors.ts';
+/**
+ * Откуда пришло поручение: коннектор, ключ записи в нём и её редакция.
+ * Результат всегда относится к этой редакции; более новая редакция в
+ * источнике старым результатом не закрывается.
+ */
+export declare const sourceRefSchema: z.ZodObject<{
+    connector: z.ZodString;
+    ref: z.ZodString;
+    revision: z.ZodString;
+}, z.core.$strict>;
+export type SourceRef = z.infer<typeof sourceRefSchema>;
+export declare const propertyIdSchema: z.ZodString;
+/** Требование, закреплённое за поручением: текст, digest источника и проверяющий gate. */
+export declare const requirementSchema: z.ZodObject<{
+    id: z.ZodString;
+    source: z.ZodString;
+    digest: z.ZodString;
+    text: z.ZodString;
+    gate: z.ZodString;
+    scenario: z.ZodString;
+    testId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Ссылка на закреплённый контракт: исполнение идёт против этого digest. */
+export declare const contractRefSchema: z.ZodObject<{
+    id: z.ZodString;
+    digest: z.ZodString;
+}, z.core.$strict>;
+/** Проверка потребителя: компонент и его gates против integration результата. */
+export declare const consumerSchema: z.ZodObject<{
+    repositoryId: z.ZodString;
+    gates: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Исполняемое поручение. Это снимок постановки, а не редактируемая задача:
+ * изменение любого поля — новая редакция источника и новый digest, и прежнее
+ * согласование к ней не относится.
+ */
+export declare const workOrderSchema: z.ZodObject<{
+    apiVersion: z.ZodLiteral<"devcontour-harness/v1alpha1">;
+    id: z.ZodString;
+    source: z.ZodObject<{
+        connector: z.ZodString;
+        ref: z.ZodString;
+        revision: z.ZodString;
+    }, z.core.$strict>;
+    title: z.ZodString;
+    goal: z.ZodString;
+    acceptance: z.ZodArray<z.ZodString>;
+    role: z.ZodString;
+    repositoryId: z.ZodString;
+    relatedRepositories: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    writeScope: z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<".">, z.ZodString]>>;
+    dependsOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    gates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    consumers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        repositoryId: z.ZodString;
+        gates: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+    properties: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    resources: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requirements: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        source: z.ZodString;
+        digest: z.ZodString;
+        text: z.ZodString;
+        gate: z.ZodString;
+        scenario: z.ZodString;
+        testId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    contracts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>>;
+    context: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type WorkOrder = z.infer<typeof workOrderSchema>;
+export type WorkOrderInput = z.input<typeof workOrderSchema>;
+/**
+ * Выполненная внешняя предпосылка. Принимается, только если её подтвердил
+ * сам движок (`engine`) либо доверенный получателем receipt; в обоих случаях
+ * result SHA обязан быть доступен в целевой ветке. Отметка `done` без SHA
+ * доказательством не является.
+ */
+export declare const prerequisiteSchema: z.ZodObject<{
+    id: z.ZodString;
+    repositoryId: z.ZodString;
+    resultSha: z.ZodString;
+    receipt: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"engine">;
+        runId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"trusted">;
+        issuer: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+export type Prerequisite = z.infer<typeof prerequisiteSchema>;
+/** Неизменяемый снимок состава и зависимостей поручений одного согласования. */
+export declare const workGraphSchema: z.ZodObject<{
+    apiVersion: z.ZodLiteral<"devcontour-harness/v1alpha1">;
+    id: z.ZodString;
+    source: z.ZodObject<{
+        connector: z.ZodString;
+        ref: z.ZodString;
+        revision: z.ZodString;
+    }, z.core.$strict>;
+    orders: z.ZodArray<z.ZodObject<{
+        apiVersion: z.ZodLiteral<"devcontour-harness/v1alpha1">;
+        id: z.ZodString;
+        source: z.ZodObject<{
+            connector: z.ZodString;
+            ref: z.ZodString;
+            revision: z.ZodString;
+        }, z.core.$strict>;
+        title: z.ZodString;
+        goal: z.ZodString;
+        acceptance: z.ZodArray<z.ZodString>;
+        role: z.ZodString;
+        repositoryId: z.ZodString;
+        relatedRepositories: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        writeScope: z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<".">, z.ZodString]>>;
+        dependsOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        gates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        consumers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            repositoryId: z.ZodString;
+            gates: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>>;
+        properties: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        resources: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        requirements: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            source: z.ZodString;
+            digest: z.ZodString;
+            text: z.ZodString;
+            gate: z.ZodString;
+            scenario: z.ZodString;
+            testId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        contracts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            digest: z.ZodString;
+        }, z.core.$strict>>>;
+        context: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    prerequisites: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        repositoryId: z.ZodString;
+        resultSha: z.ZodString;
+        receipt: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"engine">;
+            runId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"trusted">;
+            issuer: z.ZodString;
+            digest: z.ZodString;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type WorkGraph = z.infer<typeof workGraphSchema>;
+export type WorkGraphInput = z.input<typeof workGraphSchema>;
+export declare const workOrderDigest: (order: WorkOrder) => string;
+/** Digest графа закрепляет согласование: смена состава или поручения — новый digest. */
+export declare const workGraphDigest: (graph: WorkGraph) => string;
+/**
+ * Структурная проверка графа до любой записи: повтор ID, неизвестная
+ * зависимость, цикл. Зависимость разрешается поручением этого графа либо
+ * подтверждённой предпосылкой; другого способа считать её выполненной нет.
+ */
+export declare function graphIssues(graph: WorkGraph): (ErrorIssue & {
+    code: string;
+})[];

package/lib/contracts/work.js

@@ -0,0 +1,178 @@
+import { z } from 'zod';
+import { API_VERSION } from "./version.js";
+import { digestSchema, gateRefSchema, gitShaSchema, idSchema, relativePathSchema, roleIdSchema, trimmedText, } from "./primitives.js";
+import { digestOf } from "./digest.js";
+/**
+ * Откуда пришло поручение: коннектор, ключ записи в нём и её редакция.
+ * Результат всегда относится к этой редакции; более новая редакция в
+ * источнике старым результатом не закрывается.
+ */
+export const sourceRefSchema = z.strictObject({
+    connector: idSchema,
+    ref: z.string().min(1).max(300),
+    revision: z.string().min(1).max(200),
+});
+export const propertyIdSchema = z
+    .string()
+    .regex(/^[A-Za-z0-9_.:-]{1,200}$/, 'property ID без пробелов');
+/** Требование, закреплённое за поручением: текст, digest источника и проверяющий gate. */
+export const requirementSchema = z.strictObject({
+    id: z.string().regex(/^REQ-[A-Za-z0-9_-]{1,64}$/),
+    source: relativePathSchema,
+    digest: digestSchema,
+    text: z.string().min(3).max(12000),
+    gate: idSchema,
+    scenario: z.string().min(3).max(1500),
+    /** testcase отчёта, который проверяет сценарий (`classname.name` в JUnit). */
+    testId: z.string().min(1).max(300).optional(),
+});
+/** Ссылка на закреплённый контракт: исполнение идёт против этого digest. */
+export const contractRefSchema = z.strictObject({ id: idSchema, digest: digestSchema });
+/** Проверка потребителя: компонент и его gates против integration результата. */
+export const consumerSchema = z.strictObject({
+    repositoryId: idSchema,
+    gates: z.array(gateRefSchema).min(1).max(20),
+});
+/**
+ * Исполняемое поручение. Это снимок постановки, а не редактируемая задача:
+ * изменение любого поля — новая редакция источника и новый digest, и прежнее
+ * согласование к ней не относится.
+ */
+export const workOrderSchema = z.strictObject({
+    apiVersion: z.literal(API_VERSION),
+    id: idSchema,
+    source: sourceRefSchema,
+    title: trimmedText(3, 180),
+    goal: trimmedText(10, 12000),
+    acceptance: z.array(trimmedText(3, 1500)).min(1).max(30),
+    role: roleIdSchema,
+    repositoryId: idSchema,
+    /** Связанные репозитории поручения уровня workspace; пусто — один репозиторий. */
+    relatedRepositories: z.array(idSchema).max(10).default([]),
+    /**
+     * Область записи: изменения вне неё отклоняют попытку. `["."]` — весь
+     * репозиторий (защищённые и генерируемые пути и область роли по-прежнему
+     * ограничивают запись); `.` допустим только как единственный элемент.
+     */
+    writeScope: z
+        .array(z.union([z.literal('.'), relativePathSchema]))
+        .min(1)
+        .max(100)
+        .refine((paths) => !paths.includes('.') || paths.length === 1, {
+        message: 'Весь репозиторий (".") — единственный элемент области записи',
+    }),
+    dependsOn: z.array(idSchema).max(100).default([]),
+    /** Область доказательства: подмножество gates/групп политики. Нет поля — все gates репозитория. */
+    gates: z.array(gateRefSchema).max(20).optional(),
+    consumers: z.array(consumerSchema).max(10).optional(),
+    /** Свойства договора проверки, которые поручение подтверждает сейчас. */
+    properties: z.array(propertyIdSchema).max(30).optional(),
+    resources: z.array(idSchema).max(20).optional(),
+    requirements: z.array(requirementSchema).max(30).default([]),
+    contracts: z.array(contractRefSchema).max(30).default([]),
+    /** Обязательные источники контекста по ID ContextSnapshot. */
+    context: z.array(idSchema).max(30).default([]),
+});
+/**
+ * Выполненная внешняя предпосылка. Принимается, только если её подтвердил
+ * сам движок (`engine`) либо доверенный получателем receipt; в обоих случаях
+ * result SHA обязан быть доступен в целевой ветке. Отметка `done` без SHA
+ * доказательством не является.
+ */
+export const prerequisiteSchema = z.strictObject({
+    id: idSchema,
+    repositoryId: idSchema,
+    resultSha: gitShaSchema,
+    receipt: z.discriminatedUnion('kind', [
+        z.strictObject({ kind: z.literal('engine'), runId: z.string().min(1).max(200) }),
+        z.strictObject({
+            kind: z.literal('trusted'),
+            issuer: idSchema,
+            digest: digestSchema,
+        }),
+    ]),
+});
+/** Неизменяемый снимок состава и зависимостей поручений одного согласования. */
+export const workGraphSchema = z.strictObject({
+    apiVersion: z.literal(API_VERSION),
+    id: idSchema,
+    source: sourceRefSchema,
+    orders: z.array(workOrderSchema).min(1).max(500),
+    prerequisites: z.array(prerequisiteSchema).max(500).default([]),
+});
+export const workOrderDigest = (order) => digestOf(order);
+/** Digest графа закрепляет согласование: смена состава или поручения — новый digest. */
+export const workGraphDigest = (graph) => digestOf(graph);
+/**
+ * Структурная проверка графа до любой записи: повтор ID, неизвестная
+ * зависимость, цикл. Зависимость разрешается поручением этого графа либо
+ * подтверждённой предпосылкой; другого способа считать её выполненной нет.
+ */
+export function graphIssues(graph) {
+    const issues = [];
+    const ids = new Map();
+    graph.orders.forEach((order, index) => {
+        if (ids.has(order.id))
+            issues.push({
+                code: 'GRAPH_DUPLICATE_ID',
+                path: ['orders', index, 'id'],
+                message: 'Повтор ID поручения: ' + order.id,
+            });
+        else
+            ids.set(order.id, index);
+    });
+    const external = new Set();
+    graph.prerequisites.forEach((p, index) => {
+        if (ids.has(p.id) || external.has(p.id))
+            issues.push({
+                code: 'GRAPH_DUPLICATE_ID',
+                path: ['prerequisites', index, 'id'],
+                message: 'Предпосылка повторяет ID: ' + p.id,
+            });
+        external.add(p.id);
+    });
+    graph.orders.forEach((order, index) => order.dependsOn.forEach((dep, d) => {
+        if (dep === order.id)
+            issues.push({
+                code: 'GRAPH_CYCLE',
+                path: ['orders', index, 'dependsOn', d],
+                message: 'Поручение зависит от себя: ' + dep,
+            });
+        else if (!ids.has(dep) && !external.has(dep))
+            issues.push({
+                code: 'GRAPH_UNKNOWN_DEPENDENCY',
+                path: ['orders', index, 'dependsOn', d],
+                message: `Неизвестная зависимость ${order.id} → ${dep}`,
+            });
+    }));
+    // Цикл ищется обходом в глубину с цветами; путь цикла называется в сообщении.
+    const color = new Map();
+    const byId = new Map(graph.orders.map((o) => [o.id, o]));
+    const reported = new Set();
+    const visit = (id, path) => {
+        color.set(id, 1);
+        for (const dep of byId.get(id)?.dependsOn ?? []) {
+            if (dep === id || !byId.has(dep))
+                continue;
+            if (color.get(dep) === 1) {
+                const cycle = [...path.slice(path.indexOf(dep)), dep];
+                const key = [...cycle].sort().join(',');
+                if (!reported.has(key)) {
+                    reported.add(key);
+                    issues.push({
+                        code: 'GRAPH_CYCLE',
+                        path: ['orders', ids.get(dep), 'dependsOn'],
+                        message: 'Цикл зависимостей: ' + cycle.join(' → '),
+                    });
+                }
+            }
+            else if (!color.has(dep))
+                visit(dep, [...path, dep]);
+        }
+        color.set(id, 2);
+    };
+    for (const order of graph.orders)
+        if (!color.has(order.id))
+            visit(order.id, [order.id]);
+    return issues;
+}

package/lib/control/base-move.d.ts

@@ -0,0 +1,44 @@
+import type { ExecutionPolicy, ExecutionStore, ExecutionView } from '../contracts/index.ts';
+/** Сдвиг ref: репозиторий, ref, новое и ожидаемое прежнее значение. */
+export type RefMove = (repoPath: string, target: string, to: string, from: string) => void | Promise<void>;
+/**
+ * Сдвиг ref внутри транзакции проверки владения операцией: проверка и
+ * `git update-ref` неразделимы — отмена или перехват операции либо видны
+ * проверке, либо происходят уже после сдвига. Внутри транзакции не
+ * исполняется чужой код: hook `reference-transaction`, ждущий ту же базу,
+ * ждал бы её, а она — его; срок Git ограничен, зависший Git не держит базу.
+ */
+export declare function fencedRefMove(store: ExecutionStore, fence: (view: ExecutionView) => void, timeoutMs?: number): RefMove;
+export declare namespace fencedRefMove {
+    var timeoutMs: number;
+}
+export interface BaseMoved {
+    repositoryId: string;
+    targetRef: string;
+    from: string;
+    to: string;
+    commits: number;
+    kind: 'fast-forward' | 'merge';
+}
+/**
+ * Перенос базы: target ref каждого репозитория сводится с рабочей линией
+ * (HEAD checkout или переданный точный SHA). Цель — предок рабочей линии:
+ * fast-forward; обе линии несут работу — слияние без hooks в отдельном
+ * worktree. Прежнее значение ref проверяется CAS. `only` — переносить только
+ * эти репозитории и ровно на эти SHA: операция, проверившая одну редакцию,
+ * не переносит ту, что появилась позже. Очередь при этом должна стоять —
+ * это решает операция, а не перенос.
+ */
+export declare function moveBase(input: {
+    policy: ExecutionPolicy;
+    baseDir: string;
+    stateDir: string;
+    only?: Record<string, string>;
+    move?: RefMove;
+}): Promise<{
+    workingBehind?: {
+        repositoryId: string;
+        commits: number;
+    }[] | undefined;
+    updated: BaseMoved[];
+}>;

package/lib/control/base-move.js

@@ -0,0 +1,90 @@
+import { execFileSync } from 'node:child_process';
+import { isAbsolute, join, resolve } from 'node:path';
+import { git } from "../environment/process.js";
+/**
+ * Сдвиг ref внутри транзакции проверки владения операцией: проверка и
+ * `git update-ref` неразделимы — отмена или перехват операции либо видны
+ * проверке, либо происходят уже после сдвига. Внутри транзакции не
+ * исполняется чужой код: hook `reference-transaction`, ждущий ту же базу,
+ * ждал бы её, а она — его; срок Git ограничен, зависший Git не держит базу.
+ */
+export function fencedRefMove(store, fence, timeoutMs = fencedRefMove.timeoutMs) {
+    return (repoPath, target, to, from) => store.transact('base.moved', (tx) => {
+        fence(tx);
+        execFileSync('git', ['-c', 'core.hooksPath=/dev/null', 'update-ref', target, to, from], {
+            cwd: repoPath,
+            timeout: timeoutMs,
+            stdio: 'pipe',
+        });
+    });
+}
+/** Предел git update-ref внутри транзакции; конечный и короче lease. */
+fencedRefMove.timeoutMs = 15000;
+/**
+ * Перенос базы: target ref каждого репозитория сводится с рабочей линией
+ * (HEAD checkout или переданный точный SHA). Цель — предок рабочей линии:
+ * fast-forward; обе линии несут работу — слияние без hooks в отдельном
+ * worktree. Прежнее значение ref проверяется CAS. `only` — переносить только
+ * эти репозитории и ровно на эти SHA: операция, проверившая одну редакцию,
+ * не переносит ту, что появилась позже. Очередь при этом должна стоять —
+ * это решает операция, а не перенос.
+ */
+export async function moveBase(input) {
+    const move = input.move ??
+        ((repoPath, target, to, from) => git(repoPath, 'update-ref', target, to, from).then(() => undefined));
+    const path = (p) => (isAbsolute(p) ? p : resolve(input.baseDir, p));
+    const updated = [];
+    for (const repo of input.policy.repositories.filter((r) => !input.only || r.id in input.only)) {
+        const repoPath = path(repo.path);
+        const head = input.only?.[repo.id] ?? (await git(repoPath, 'rev-parse', 'HEAD'));
+        const tip = await git(repoPath, 'rev-parse', repo.targetRef);
+        if (head === tip)
+            continue;
+        const behind = Number(await git(repoPath, 'rev-list', '--count', `${repo.targetRef}..${head}`));
+        if (!behind)
+            continue;
+        const ahead = Number(await git(repoPath, 'rev-list', '--count', `${head}..${repo.targetRef}`));
+        if (!ahead) {
+            // Цель — предок рабочей линии: история не теряется и не переписывается.
+            await move(repoPath, repo.targetRef, head, tip);
+            updated.push({
+                repositoryId: repo.id,
+                targetRef: repo.targetRef,
+                from: tip,
+                to: head,
+                commits: behind,
+                kind: 'fast-forward',
+            });
+            continue;
+        }
+        // Обе линии несут работу: сводятся слиянием в отдельном worktree — target
+        // ref checkout-веткой быть не может и продвигается только через CAS.
+        const cwd = join(input.stateDir, 'worktrees', `base-${repo.id}-${Date.now()}`);
+        await git(repoPath, 'worktree', 'add', '--detach', cwd, tip);
+        try {
+            await git(cwd, '-c', 'core.hooksPath=/dev/null', 'merge', '--no-ff', '--no-edit', '--no-gpg-sign', head);
+            const merged = await git(cwd, 'rev-parse', 'HEAD');
+            await move(repoPath, repo.targetRef, merged, tip);
+            updated.push({
+                repositoryId: repo.id,
+                targetRef: repo.targetRef,
+                from: tip,
+                to: merged,
+                commits: behind,
+                kind: 'merge',
+            });
+        }
+        finally {
+            await git(repoPath, 'worktree', 'remove', '--force', cwd).catch(() => undefined);
+        }
+    }
+    // Обратное направление: принятая работа, которой нет в рабочей линии.
+    // Слияния не считаются: сам перенос оставляет коммит слияния без новой работы.
+    const workingBehind = [];
+    for (const repo of input.policy.repositories) {
+        const commits = Number(await git(path(repo.path), 'rev-list', '--no-merges', '--count', `HEAD..${repo.targetRef}`));
+        if (commits)
+            workingBehind.push({ repositoryId: repo.id, commits });
+    }
+    return { updated, ...(workingBehind.length ? { workingBehind } : {}) };
+}

package/lib/control/doctor.d.ts

@@ -0,0 +1,50 @@
+import { type ExecutionPolicy, type RuntimeAdapter, type RuntimeName } from '../contracts/index.ts';
+import type { ToolchainReport } from '../toolchains/inspect.ts';
+/** Диагностика toolchain политики (см. `inspectPolicy` в `./toolchains`). */
+export type ToolchainInspect = (policy: ExecutionPolicy, baseDir: string) => Promise<ToolchainReport[]>;
+/**
+ * Проверка среды без live-вызова модели: версия пакета и Node, наличие
+ * runtime (по `--version`) и их возможности, OS-sandbox, совместимость
+ * каталога состояния. Каталог состояния открывается только если он есть;
+ * для совместимого состояния называются версии движка, встреченные в нём
+ * (роль controller и попытки), — перед обновлением и откатом видно, какая
+ * версия последней писала состояние.
+ */
+export declare function doctor(policy: ExecutionPolicy | undefined, adapters: Partial<Record<RuntimeName, RuntimeAdapter>>, stateDir?: string, 
+/**
+ * Диагностика toolchain репозиториев (инструменты и версии, lockfiles,
+ * scripts/tasks, cwd, отчёты) — только чтением и ограниченными пробами
+ * версий. Передаётся явно (CLI — `inspectPolicy` из `./toolchains`): корень
+ * пакета не тянет модуль toolchains сам.
+ */
+toolchain?: {
+    baseDir: string;
+    inspect: ToolchainInspect;
+}): Promise<{
+    problems: string[];
+    toolchains?: ToolchainReport[] | undefined;
+    state?: {
+        stateVersion: number;
+        compatible: boolean;
+        engineVersions?: {
+            controller?: string;
+            attempts: string[];
+        };
+    } | undefined;
+    harness: string;
+    apiVersion: "devcontour-harness/v1alpha1";
+    node: string;
+    platform: string;
+    runtimes: {
+        reason?: string | undefined;
+        structuredOutput: boolean;
+        cancellation: boolean;
+        version?: string | undefined;
+        runtime: "codex" | "claude";
+        available: boolean;
+    }[];
+    sandbox: {
+        reason?: string | undefined;
+        os: boolean;
+    };
+}>;

package/lib/control/doctor.js

@@ -0,0 +1,113 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { API_VERSION, HarnessError, STATE_VERSION, } from "../contracts/index.js";
+import { isolationSupport } from "../environment/isolation.js";
+import { HARNESS_VERSION } from "../package.js";
+import { SqliteExecutionStore } from "../storage/sqlite.js";
+/** Runtime, которые политика действительно назначает writer или reviewer. */
+function usedRuntimes(policy) {
+    const used = new Set();
+    const rule = (r) => {
+        if (!r)
+            return;
+        used.add(r.reviewer.runtime);
+        for (const a of r.alternates ?? [])
+            used.add(a.runtime);
+    };
+    for (const k of ['code', 'plan', 'contract'])
+        rule(policy.review[k]);
+    const roles = [
+        ...Object.values(policy.roles),
+        ...policy.repositories.flatMap((r) => Object.values(r.roles ?? {})),
+    ];
+    for (const b of roles) {
+        used.add(b.writer.runtime);
+        rule(b.review);
+    }
+    for (const r of policy.repositories)
+        rule(r.review);
+    return used;
+}
+/**
+ * Проверка среды без live-вызова модели: версия пакета и Node, наличие
+ * runtime (по `--version`) и их возможности, OS-sandbox, совместимость
+ * каталога состояния. Каталог состояния открывается только если он есть;
+ * для совместимого состояния называются версии движка, встреченные в нём
+ * (роль controller и попытки), — перед обновлением и откатом видно, какая
+ * версия последней писала состояние.
+ */
+export async function doctor(policy, adapters, stateDir, 
+/**
+ * Диагностика toolchain репозиториев (инструменты и версии, lockfiles,
+ * scripts/tasks, cwd, отчёты) — только чтением и ограниченными пробами
+ * версий. Передаётся явно (CLI — `inspectPolicy` из `./toolchains`): корень
+ * пакета не тянет модуль toolchains сам.
+ */
+toolchain) {
+    const problems = [];
+    const runtimes = [];
+    // С политикой обязательны только назначенные ею runtime: сценарий одного
+    // вендора или fixture не требует второго CLI.
+    const required = policy ? usedRuntimes(policy) : new Set(['codex', 'claude']);
+    for (const runtime of ['codex', 'claude']) {
+        const caps = required.has(runtime)
+            ? await adapters[runtime]?.capabilities().catch(() => undefined)
+            : undefined;
+        if (!caps?.version && required.has(runtime))
+            problems.push(`${runtime}: не найден или не отвечает на --version`);
+        runtimes.push({
+            runtime,
+            available: Boolean(caps?.version),
+            ...(caps?.version ? { version: caps.version } : {}),
+            structuredOutput: caps?.structuredOutput ?? false,
+            cancellation: caps?.cancellation ?? false,
+            ...(required.has(runtime) ? {} : { reason: 'не назначен политикой' }),
+        });
+    }
+    const sandbox = isolationSupport();
+    if (!sandbox.ok && policy?.isolation.mode === 'os')
+        problems.push(sandbox.detail);
+    let state;
+    if (stateDir && existsSync(join(stateDir, 'state.sqlite'))) {
+        try {
+            const store = new SqliteExecutionStore(join(stateDir, 'state.sqlite'), 'devcontour-harness@' + HARNESS_VERSION, 
+            // Диагностика не становится писателем: автор, PRAGMA и данные прежние.
+            { readOnly: true });
+            let engineVersions;
+            try {
+                engineVersions = store.read((view) => {
+                    const controller = view.controller()?.engineVersion;
+                    return {
+                        ...(controller ? { controller } : {}),
+                        attempts: [
+                            ...new Set(view.attempts().flatMap((a) => (a.engineVersion ? [a.engineVersion] : []))),
+                        ].sort(),
+                    };
+                });
+            }
+            finally {
+                store.close();
+            }
+            state = { stateVersion: STATE_VERSION, compatible: true, engineVersions };
+        }
+        catch (error) {
+            state = { stateVersion: -1, compatible: false };
+            problems.push(error instanceof HarnessError ? error.message : String(error));
+        }
+    }
+    const toolchains = policy && toolchain ? await toolchain.inspect(policy, toolchain.baseDir) : undefined;
+    for (const r of toolchains ?? [])
+        for (const p of r.problems)
+            problems.push(`toolchain ${r.repositoryId}: ${p.code} ${p.field.join('.')}${p.path ? ` (${p.path})` : ''}: ${p.message}`);
+    return {
+        harness: HARNESS_VERSION,
+        apiVersion: API_VERSION,
+        node: process.version,
+        platform: `${process.platform}-${process.arch}`,
+        runtimes,
+        sandbox: { os: sandbox.ok, ...(sandbox.ok ? {} : { reason: sandbox.detail }) },
+        ...(state ? { state } : {}),
+        ...(toolchains ? { toolchains } : {}),
+        problems,
+    };
+}