humanish 0.104.3 → 0.106.0

package/dist/run/git-workspace.js

@@ -0,0 +1,450 @@
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { isNodeError } from "./type-guards.js";
+const GIT_METADATA_INSPECTION_FAILED_NOTE = "Git metadata could not be inspected safely.";
+const GIT_METADATA_CONTAINMENT_FAILED_NOTE = "Git metadata failed containment validation.";
+/**
+ * Resolve one physical Git worktree without trusting ambient Git discovery.
+ *
+ * A regular `.git` file is accepted only for Git's exact linked-worktree
+ * topology: `<common>/.git/worktrees/<name>` plus single-link `commondir` and
+ * `gitdir` backpointer files. Arbitrary `gitdir:` redirects (including valid
+ * separate-git-dir repositories) are deliberately unavailable because they
+ * delegate metadata authority outside the selected project without a
+ * verifiable backlink.
+ */
+export async function inspectVerifiedGitWorkspace(cwdInput) {
+    let current;
+    try {
+        current = await realpath(path.resolve(cwdInput));
+        const cwdStats = await lstat(current);
+        if (cwdStats.isSymbolicLink() || !cwdStats.isDirectory()) {
+            return unsafeInspection(current, GIT_METADATA_INSPECTION_FAILED_NOTE);
+        }
+    }
+    catch {
+        return unsafeInspection(path.resolve(cwdInput), GIT_METADATA_INSPECTION_FAILED_NOTE);
+    }
+    while (true) {
+        const dotGitPath = path.join(current, ".git");
+        let dotGitStats;
+        try {
+            dotGitStats = await lstat(dotGitPath, { bigint: true });
+        }
+        catch (error) {
+            if (!isNodeError(error) || error.code !== "ENOENT") {
+                return unsafeInspection(current, GIT_METADATA_INSPECTION_FAILED_NOTE);
+            }
+            const parent = path.dirname(current);
+            if (parent === current) {
+                return { status: "missing" };
+            }
+            current = parent;
+            continue;
+        }
+        if (dotGitStats.isSymbolicLink()) {
+            return unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+        }
+        if (dotGitStats.isDirectory()) {
+            try {
+                if ((await realpath(dotGitPath)) !== dotGitPath) {
+                    return unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+                }
+                // A normal worktree does not need commondir. Accepting one here would
+                // let a contained `.git/` silently redirect config, refs, and objects.
+                if (await pathExists(path.join(dotGitPath, "commondir"))) {
+                    return unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+                }
+                const configOverrides = [];
+                const workspace = {
+                    commonDir: dotGitPath,
+                    configOverrides,
+                    gitDir: dotGitPath,
+                    kind: "directory",
+                    trustRoot: current,
+                    worktreeRoot: current,
+                };
+                return (await validateCriticalGitMetadata(workspace))
+                    ? { status: "verified", workspace: freezeVerifiedWorkspace(workspace, configOverrides) }
+                    : unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+            }
+            catch {
+                return unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+            }
+        }
+        if (!dotGitStats.isFile() || dotGitStats.nlink !== 1n) {
+            return unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+        }
+        try {
+            const dotGit = await readSingleLinkRegularFile(dotGitPath);
+            const declaredGitDir = dotGit ? parseGitdirFile(dotGit.text) : null;
+            if (!dotGit || !declaredGitDir) {
+                return unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+            }
+            const gitDir = await realpath(path.isAbsolute(declaredGitDir) ? declaredGitDir : path.resolve(current, declaredGitDir));
+            if (!(await isPhysicalDirectory(gitDir))) {
+                return unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+            }
+            const commondir = await readSingleLinkRegularFile(path.join(gitDir, "commondir"));
+            const backpointer = await readSingleLinkRegularFile(path.join(gitDir, "gitdir"));
+            const declaredCommonDir = commondir ? parseSinglePathLine(commondir.text) : null;
+            const declaredBackpointer = backpointer ? parseSinglePathLine(backpointer.text) : null;
+            if (!commondir || !backpointer || !declaredCommonDir || !declaredBackpointer) {
+                return unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+            }
+            const commonDir = await realpath(path.resolve(gitDir, declaredCommonDir));
+            if (!(await isPhysicalDirectory(commonDir)) ||
+                path.basename(commonDir) !== ".git" ||
+                path.dirname(gitDir) !== path.join(commonDir, "worktrees") ||
+                path.basename(gitDir).length === 0) {
+                return unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+            }
+            const physicalBackpointer = await realpath(path.isAbsolute(declaredBackpointer)
+                ? declaredBackpointer
+                : path.resolve(gitDir, declaredBackpointer));
+            if (physicalBackpointer !== dotGitPath) {
+                return unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+            }
+            const trustRoot = path.dirname(commonDir);
+            if (!(await isPhysicalDirectory(trustRoot)) ||
+                (await realpath(path.join(trustRoot, ".git"))) !== commonDir ||
+                !(await stillSameSingleLinkFile(dotGitPath, dotGit.identity)) ||
+                !(await stillSameSingleLinkFile(path.join(gitDir, "commondir"), commondir.identity)) ||
+                !(await stillSameSingleLinkFile(path.join(gitDir, "gitdir"), backpointer.identity))) {
+                return unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+            }
+            const configOverrides = [];
+            const workspace = {
+                commonDir,
+                configOverrides,
+                gitDir,
+                kind: "linked-worktree",
+                trustRoot,
+                worktreeRoot: current,
+            };
+            return (await validateCriticalGitMetadata(workspace))
+                ? { status: "verified", workspace: freezeVerifiedWorkspace(workspace, configOverrides) }
+                : unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+        }
+        catch {
+            return unsafeInspection(current, GIT_METADATA_CONTAINMENT_FAILED_NOTE);
+        }
+    }
+}
+async function validateCriticalGitMetadata(workspace) {
+    if (!(await isPhysicalDirectory(workspace.gitDir)) ||
+        !(await isPhysicalDirectory(workspace.commonDir)) ||
+        !(await isPhysicalDirectory(workspace.worktreeRoot))) {
+        return false;
+    }
+    const criticalFiles = new Set([
+        path.join(workspace.gitDir, "HEAD"),
+        path.join(workspace.gitDir, "index"),
+        path.join(workspace.gitDir, "config.worktree"),
+        path.join(workspace.commonDir, "config"),
+        path.join(workspace.commonDir, "config.worktree"),
+        path.join(workspace.commonDir, "info", "attributes"),
+        path.join(workspace.commonDir, "info", "exclude"),
+        path.join(workspace.commonDir, "packed-refs"),
+    ]);
+    for (const filePath of criticalFiles) {
+        if (!(await isSingleLinkRegularFileOrMissing(filePath))) {
+            return false;
+        }
+    }
+    // Split indexes are selected by the contained index but read as sibling
+    // metadata. Do not let one redirect Git through a symlink or hardlink.
+    const gitDirEntries = await readdir(workspace.gitDir).catch(() => []);
+    for (const entry of gitDirEntries) {
+        if (/^sharedindex\.[0-9a-f]+$/i.test(entry)) {
+            if (!(await isSingleLinkRegularFileOrMissing(path.join(workspace.gitDir, entry)))) {
+                return false;
+            }
+        }
+    }
+    for (const directory of [
+        path.join(workspace.commonDir, "objects"),
+        path.join(workspace.commonDir, "refs"),
+    ]) {
+        if (!(await isPhysicalDirectoryOrMissing(directory))) {
+            return false;
+        }
+    }
+    const head = await readSingleLinkRegularFile(path.join(workspace.gitDir, "HEAD"), true);
+    if (head && !(await validateHeadReference(workspace, head.text))) {
+        return false;
+    }
+    const alternatesPath = path.join(workspace.commonDir, "objects", "info", "alternates");
+    if (!(await isSingleLinkRegularFileOrMissing(alternatesPath))) {
+        return false;
+    }
+    const alternates = await readSingleLinkRegularFile(alternatesPath, true);
+    if (alternates && !(await alternatesStayInsideCommonDir(workspace.commonDir, alternates.text))) {
+        return false;
+    }
+    const overrides = await collectExecutableConfigOverrides(workspace);
+    if (!overrides) {
+        return false;
+    }
+    workspace.configOverrides.push(...overrides);
+    return true;
+}
+async function collectExecutableConfigOverrides(workspace) {
+    const filters = new Set();
+    const diffs = new Set();
+    for (const configPath of new Set([
+        path.join(workspace.commonDir, "config"),
+        path.join(workspace.gitDir, "config.worktree"),
+    ])) {
+        const config = await readSingleLinkRegularFile(configPath, true);
+        if (!config)
+            continue;
+        for (const line of config.text.split(/\r?\n/)) {
+            if (/^\s*\[\s*include(?:\s*\]|if\b)/i.test(line)) {
+                // Includes can introduce executable config from an unbound path after
+                // this file was inspected. Provenance capture does not need them.
+                return null;
+            }
+            const sectionStart = /^\s*\[\s*(filter|diff)\b/i.exec(line);
+            if (!sectionStart)
+                continue;
+            const section = /^\s*\[\s*(filter|diff)\s+(?:"((?:\\.|[^"\\])*)"|\.\s*([^\]\s]+))\s*\]\s*(?:[#;].*)?$/i.exec(line);
+            if (!section)
+                return null;
+            const rawDriver = section[2] === undefined ? section[3] : unescapeGitConfigSubsection(section[2]);
+            if (!rawDriver || !/^[A-Za-z0-9_.-]+$/.test(rawDriver))
+                return null;
+            if (section[1]?.toLowerCase() === "filter")
+                filters.add(rawDriver);
+            else
+                diffs.add(rawDriver);
+        }
+    }
+    const overrides = [];
+    for (const driver of [...filters].sort()) {
+        overrides.push(`filter.${driver}.clean=`, `filter.${driver}.smudge=`, `filter.${driver}.process=`, `filter.${driver}.required=false`);
+    }
+    for (const driver of [...diffs].sort()) {
+        overrides.push(`diff.${driver}.command=`, `diff.${driver}.textconv=`);
+    }
+    return overrides;
+}
+function unescapeGitConfigSubsection(value) {
+    let result = "";
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        if (char !== "\\") {
+            result += char;
+            continue;
+        }
+        const escaped = value[index + 1];
+        if (escaped !== "\\" && escaped !== '"')
+            return null;
+        result += escaped;
+        index += 1;
+    }
+    return result;
+}
+function freezeVerifiedWorkspace(workspace, configOverrides) {
+    Object.freeze(configOverrides);
+    return Object.freeze(workspace);
+}
+async function validateHeadReference(workspace, headText) {
+    const value = headText.trim();
+    if (/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/i.test(value)) {
+        return true;
+    }
+    if (!value.startsWith("ref: ")) {
+        return false;
+    }
+    const ref = value.slice("ref: ".length);
+    if (!isSafeGitRef(ref)) {
+        return false;
+    }
+    // Normal branch refs live under the common directory. Per-worktree refs may
+    // live under the admin directory. Validate either existing path without
+    // requiring an unborn branch to have a loose ref.
+    const candidates = [path.join(workspace.commonDir, ...ref.split("/"))];
+    if (workspace.gitDir !== workspace.commonDir) {
+        candidates.push(path.join(workspace.gitDir, ...ref.split("/")));
+    }
+    for (const candidate of candidates) {
+        if (!(await validateOptionalContainedFileChain(candidate.startsWith(`${workspace.gitDir}${path.sep}`)
+            ? workspace.gitDir
+            : workspace.commonDir, candidate))) {
+            return false;
+        }
+    }
+    return true;
+}
+async function validateOptionalContainedFileChain(root, filePath) {
+    const relative = path.relative(root, filePath);
+    if (!relative ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        return false;
+    }
+    let current = root;
+    const segments = relative.split(path.sep);
+    for (const [index, segment] of segments.entries()) {
+        current = path.join(current, segment);
+        let stats;
+        try {
+            stats = await lstat(current, { bigint: true });
+        }
+        catch (error) {
+            return isNodeError(error) && error.code === "ENOENT";
+        }
+        if (stats.isSymbolicLink())
+            return false;
+        if (index < segments.length - 1) {
+            if (!stats.isDirectory())
+                return false;
+        }
+        else if (!stats.isFile() || stats.nlink !== 1n) {
+            return false;
+        }
+    }
+    return true;
+}
+async function alternatesStayInsideCommonDir(commonDir, text) {
+    const objectDir = path.join(commonDir, "objects");
+    for (const line of text
+        .split(/\r?\n/)
+        .map((value) => value.trim())
+        .filter(Boolean)) {
+        const candidate = path.isAbsolute(line) ? line : path.resolve(objectDir, line);
+        let physical;
+        try {
+            physical = await realpath(candidate);
+        }
+        catch {
+            return false;
+        }
+        const relative = path.relative(commonDir, physical);
+        if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            return false;
+        }
+    }
+    return true;
+}
+function parseGitdirFile(text) {
+    const match = /^gitdir:\s*([^\r\n]+)\r?\n?$/.exec(text);
+    return match?.[1]?.trim() || null;
+}
+function parseSinglePathLine(text) {
+    const match = /^([^\r\n]+)\r?\n?$/.exec(text);
+    return match?.[1]?.trim() || null;
+}
+function isSafeGitRef(value) {
+    return (value.startsWith("refs/") &&
+        !value.includes("\\") &&
+        !value.includes("\0") &&
+        !value.includes("//") &&
+        value.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== ".."));
+}
+async function readSingleLinkRegularFile(filePath, allowMissing = false) {
+    let before;
+    try {
+        before = await lstat(filePath, { bigint: true });
+    }
+    catch (error) {
+        if (allowMissing && isNodeError(error) && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+    if (before.isSymbolicLink() || !before.isFile() || before.nlink !== 1n) {
+        return null;
+    }
+    const handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const opened = await handle.stat({ bigint: true });
+        if (!opened.isFile() ||
+            opened.nlink !== 1n ||
+            opened.dev !== before.dev ||
+            opened.ino !== before.ino) {
+            return null;
+        }
+        const text = await handle.readFile("utf8");
+        return Object.freeze({
+            identity: Object.freeze({ dev: opened.dev, ino: opened.ino }),
+            text,
+        });
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function isSingleLinkRegularFileOrMissing(filePath) {
+    let before;
+    try {
+        before = await lstat(filePath, { bigint: true });
+    }
+    catch (error) {
+        return isNodeError(error) && error.code === "ENOENT";
+    }
+    if (before.isSymbolicLink() || !before.isFile() || before.nlink !== 1n) {
+        return false;
+    }
+    const handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW).catch(() => null);
+    if (!handle)
+        return false;
+    try {
+        const opened = await handle.stat({ bigint: true });
+        return (opened.isFile() &&
+            opened.nlink === 1n &&
+            opened.dev === before.dev &&
+            opened.ino === before.ino);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function stillSameSingleLinkFile(filePath, identity) {
+    try {
+        const stats = await lstat(filePath, { bigint: true });
+        return (!stats.isSymbolicLink() &&
+            stats.isFile() &&
+            stats.nlink === 1n &&
+            stats.dev === identity.dev &&
+            stats.ino === identity.ino);
+    }
+    catch {
+        return false;
+    }
+}
+async function isPhysicalDirectory(directory) {
+    try {
+        const stats = await lstat(directory);
+        return (!stats.isSymbolicLink() && stats.isDirectory() && (await realpath(directory)) === directory);
+    }
+    catch {
+        return false;
+    }
+}
+async function isPhysicalDirectoryOrMissing(directory) {
+    try {
+        const stats = await lstat(directory);
+        return (!stats.isSymbolicLink() && stats.isDirectory() && (await realpath(directory)) === directory);
+    }
+    catch (error) {
+        return isNodeError(error) && error.code === "ENOENT";
+    }
+}
+async function pathExists(filePath) {
+    try {
+        await lstat(filePath);
+        return true;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function unsafeInspection(worktreeRoot, note) {
+    return { note, status: "unsafe", worktreeRoot };
+}

package/dist/run/judge.d.ts

@@ -0,0 +1,210 @@
+import type { ActorCompletionReason, ActorStatus, ParticipantDeclaredOutcome } from "../actors/contract.js";
+import type { ReviewSummary } from "./bundle.js";
+export type Verdict = ReviewSummary["verdict"];
+/** How a finished session ended, as the blocker rule reads it. */
+export interface BlockerFacts {
+    completionReason: ActorCompletionReason;
+    /** A harness-owned stop condition ended the session: a matched stopWhen or a completed dwell window. */
+    stopConditionMatched: boolean;
+    /** What the participant declared in a field, when its provider has one (#570). */
+    declaredOutcome?: ParticipantDeclaredOutcome;
+    /** The route's reading of the closing report: it describes a blocker or asks for instructions. */
+    closingReportReadsBlocked: boolean;
+}
+/** How a finished session ended, as the engagement and blocker rules read it. */
+export interface SessionEnding extends BlockerFacts {
+    actions: number;
+    messages: number;
+}
+/**
+ * The participant said it reached the goal having taken no action and said nothing, and no stop
+ * condition ended the session. It most likely saw a blank or loading screen, so it is not a pass.
+ */
+export declare function hollowCompletion(ending: SessionEnding): boolean;
+/**
+ * The participant said it reached the goal but reported a blocker. A declared outcome is its own
+ * word and wins (#570). Without one, the closing report is read, unless a stop condition ended the
+ * session: a matched stopWhen is structured completion evidence and overrides the text.
+ */
+export declare function selfReportedBlocker(ending: BlockerFacts): boolean;
+/** What a participant's pass reads: its session's end, or why it has none, and the two judgments above. */
+export interface ParticipantFacts {
+    /** Absent when no session reached a terminal status. */
+    status?: ActorStatus;
+    completionReason?: ActorCompletionReason;
+    /** The harness failed before the session reached a terminal status. */
+    sessionError?: string;
+    /** The pipeline gate or fail-fast skipped the participant. */
+    skipped: boolean;
+    /** hollowCompletion held for its session. */
+    noEngagement: boolean;
+    /** selfReportedBlocker held for its session. */
+    selfReportedBlocker: boolean;
+}
+/**
+ * The status a participant is judged under. A harness failure is failed, and a skipped participant
+ * is blocked, as the fan-out bundle and the result write it. Otherwise it is the tallied
+ * participantStatus of its session, or undefined when no session reached a terminal status.
+ * participantPassed and judgeOneParticipant's verdict both read it, so the two cannot disagree.
+ */
+export declare function judgedStatus(participant: ParticipantFacts): ActorStatus | undefined;
+/** A participant passed: its session passed without a harness error, engaged, and reported no blocker. */
+export declare function participantPassed(participant: ParticipantFacts): boolean;
+/**
+ * The participant's session failed in the harness: it threw before a terminal status, or it ended
+ * in a harness error. That is an execution failure, apart from what the participant experienced.
+ */
+export declare function participantHarnessFailed(participant: ParticipantFacts): boolean;
+/**
+ * The status a participant is tallied under, given what the route made of the session. A
+ * goal_satisfied claim with zero engagement is a session that ran out before anything happened;
+ * one whose final message describes a blocker is a participant who could not proceed and said so.
+ * Both keep their trace status (the claim is evidence); neither is a participant who reached the
+ * goal. One rule for the single lane and the fan-out roll-up (#476).
+ */
+export declare function participantStatus(status: ActorStatus, judgments: {
+    noEngagement: boolean;
+    selfReportedBlocker: boolean;
+} | undefined): ActorStatus;
+/** The review verdict for one participant's status. */
+export declare function verdictForStatus(status: ActorStatus): Verdict;
+declare const judged: unique symbol;
+/**
+ * A run's judgment: the review verdict, and whether the run met its route's pass rule. Only
+ * judgmentOf builds one, so passed always follows from the verdict.
+ */
+export interface Judgment {
+    readonly verdict: Verdict;
+    /**
+     * The run met its route's pass rule: every expected participant passed and, on shared-world,
+     * the seats showed the concurrency verify requires. A dry run passes as a contract.
+     */
+    readonly passed: boolean;
+    /** A type-only mark that judgmentOf made this judgment; it does not exist at runtime. */
+    readonly [judged]: true;
+}
+/** The judgment for a verdict: a run passes when its verdict is pass, and a dry run passes. */
+export declare function judgmentOf(verdict: Verdict, dryRun: boolean): Judgment;
+/** What kind of execution failure a run recorded. */
+type ExecutionFailureKind = "harness" | "provider-cleanup" | "sandbox-cleanup" | "evidence" | "cap" | "run";
+/** One way the run failed as an execution. The message is scrubbed; status.json shows it. */
+export interface ExecutionFailure {
+    kind: ExecutionFailureKind;
+    message: string;
+}
+/** Whether the run worked as an execution, apart from what its participants experienced. */
+export interface ExecutionOutcome {
+    /** True when no failure of a kind the route's policy counts was recorded. */
+    succeeded: boolean;
+    /** The failures the policy counts, in the order the route recorded them. */
+    failures: ExecutionFailure[];
+}
+/**
+ * How a route turns the facts into its result's ok. A gate route needs every participant to
+ * pass. On an evidence route a participant that failed, was blocked or timed out is captured
+ * evidence, and only the execution and the scorer fail the result. Each of the two policy kinds
+ * says whether that kind of failure fails the execution or stays a warning.
+ */
+export interface OutcomePolicy {
+    participants: "gate" | "evidence";
+    sandboxCleanup: "fails" | "warns";
+    evidence: "fails" | "warns";
+}
+/** The routes a run is judged on. */
+export type JudgedRoute = "computer-use" | "shared-world" | "terminal" | "scripted" | "preview";
+/** Each route's outcome policy, in one place. */
+export declare const OUTCOME_POLICIES: Readonly<Record<JudgedRoute, OutcomePolicy>>;
+/** What a shared-world run observed about its one world, beside how each seat ended. */
+export interface SharedWorldFacts {
+    /** Two or more seats were live at the same time. */
+    overlap: boolean;
+    /** Provisioned plane only: the shared state changed at or after the first overlap started. */
+    stateChangedUnderOverlap?: boolean;
+    /** External-public plane only: every seat reached one lobby. */
+    lobbyConvergence?: boolean;
+}
+/** A shared-world run's judgment, with the world facts its review and result also report. */
+export interface SharedWorldJudgment extends Judgment {
+    world: SharedWorldFacts;
+}
+/**
+ * A run with one participant: its tallied status is the verdict, so a hollow pass fails and a
+ * self-reported blocker reads as blocked. Without a session, a harness failure fails the run and
+ * a dry run is a contract. A run still in progress is a contract until it finishes. Computer-use
+ * calls it for one lane with no rerun, and terminal calls it through judgeTerminal.
+ */
+export declare function judgeOneParticipant(args: {
+    dryRun: boolean;
+    inProgress: boolean;
+    participant: ParticipantFacts | undefined;
+}): Judgment;
+/**
+ * A run with several participants: it passes only when every expected participant passed. When
+ * one did not, a timeout among them makes the run timed_out; otherwise it fails. A dry run and a
+ * run still in progress are contracts. Computer-use calls it for a fan-out or a rerun.
+ */
+export declare function judgeParticipants(args: {
+    dryRun: boolean;
+    inProgress: boolean;
+    expected: number;
+    participants: ParticipantFacts[];
+}): Judgment;
+/**
+ * Why a shared-world run whose seats all passed still fails, or undefined when its world facts
+ * meet what verify's shared-world check requires of a pass: two seats live at the same time and,
+ * on the provisioned plane, a shared-state change at or after the first overlap started.
+ */
+export declare function sharedWorldShortfall(world: SharedWorldFacts): string | undefined;
+/**
+ * A shared-world run: it passes only when every expected seat passed and the world facts have no
+ * shortfall, and otherwise fails (this route has no timed_out verdict). A dry run and a run still
+ * in progress are contracts. Lobby convergence is recorded but not read.
+ */
+export declare function judgeSharedWorld(args: {
+    dryRun: boolean;
+    inProgress: boolean;
+    expected: number;
+    participants: ParticipantFacts[];
+    world: SharedWorldFacts;
+}): SharedWorldJudgment;
+/**
+ * A terminal run: one agent session judged as a one-participant run. It has no engagement or
+ * blocker rule; the agent's nonce-verified marker is its declared outcome.
+ */
+export declare function judgeTerminal(args: {
+    dryRun: boolean;
+    participant: ParticipantFacts | undefined;
+}): Judgment;
+/**
+ * A scripted run: the worst surface decides the verdict. A harness error or a failed step fails
+ * the run, then a timeout makes it timed_out. Otherwise it passes when every expected surface
+ * passed, and fails when one did not. A session error fails it and a run with no surface results
+ * is a contract.
+ */
+export declare function judgeScripted(args: {
+    dryRun: boolean;
+    sessionError: string | undefined;
+    expected: number;
+    surfaces: ParticipantFacts[];
+}): Judgment;
+/** The preview: a synthetic contract with no participants. */
+export declare function judgePreview(): Judgment;
+/**
+ * The run's final review after scoring. Each scorer failure is recorded as a gap, and the first
+ * turns a pass or a contract into a fail with that failure as the summary. Every other verdict
+ * stays as it was, so scoring can never improve a verdict. No failures returns the review as is.
+ */
+export declare function foldScorerFailures(review: ReviewSummary, failures: readonly string[]): ReviewSummary;
+/** The run's execution outcome under its route's policy. A failure of a kind the policy lets warn is dropped. */
+export declare function judgeExecution(failures: readonly ExecutionFailure[], policy: OutcomePolicy): ExecutionOutcome;
+/**
+ * The result's ok: the run worked as an execution, no scorer failed it, and on a gate route every
+ * participant passed. An evidence route ignores how its participants did.
+ */
+export declare function resultOk(args: {
+    judgment: Judgment;
+    execution: ExecutionOutcome;
+    scorerFailures: readonly string[];
+    policy: OutcomePolicy;
+}): boolean;
+export {};