jev-agent-tools 0.1.3 → 0.2.0

package/dist/tools/docs-check.js

@@ -0,0 +1,299 @@
+import { createAnalysisContext } from "../adapters/analysis-context.js";
+import { collectDocsInventory, docsDeclarationSearch, } from "../adapters/docs.js";
+import { collectUnits } from "../adapters/git.js";
+import { resolveBase } from "../adapters/git-base.js";
+import { shareGitInventory } from "../adapters/git-inventory.js";
+import { CHOICE_MAX_OPTIONS, DOCS_COLLECT_BUDGET_MS, DOCS_DISPLAY_MAX_SECTIONS, DOCS_MAX_SECTIONS, STATE_MAX_CHARS, } from "../constants.js";
+import { collectDocsCandidates } from "../core/docs.js";
+import { buildEnvelope, } from "../core/output.js";
+import { prepareDocsCheck, readDocsJudgment, } from "../presets/docs.js";
+import { NOT_CONFIGURED } from "../texts/configuration.js";
+/** Shared judgment seam: no guide delivery, rendering, or session answer recording. */
+export async function runDocsCheck(deps, input) {
+    const started = performance.now();
+    deps = { ...deps, exec: shareGitInventory(deps.exec) };
+    const timeout = input.budgetMs === undefined
+        ? undefined
+        : AbortSignal.timeout(Math.max(0, Math.ceil(input.budgetMs)));
+    const signals = [input.signal, timeout].filter((value) => value !== undefined);
+    const signal = signals.length ? AbortSignal.any(signals) : undefined;
+    const judgments = [];
+    const findings = [];
+    const unchecked = [];
+    let unjudged;
+    let collection;
+    const limitations = [
+        {
+            fact: "Measured D22 limit: 2/45 documentation obligations found across 180 partial got/zod commits.",
+            next: "Also review missing documentation: this check evaluates existing sentences, not documentation completeness.",
+        },
+    ];
+    let budget;
+    let sent = 0;
+    let emptyBase;
+    const finish = (refusal) => {
+        if (unchecked.length > 5) {
+            unjudged = {
+                count: unchecked.length,
+                sections: unchecked.slice(0, DOCS_MAX_SECTIONS),
+                truncated: unchecked.length > DOCS_MAX_SECTIONS,
+            };
+            limitations.push({
+                fact: `${unchecked.length} matching sections unjudged.`,
+                next: "Narrow the diff with base=… or rerun on the relevant documentation.",
+            });
+        }
+        const answers = findings.map((finding) => ({
+            label: `${finding.section.path}:${finding.section.start}-${finding.section.end} § ${finding.section.heading} — ${finding.sentence ? JSON.stringify(finding.sentence.text) : "sentence not identified"} — ${finding.band === "verdict" ? "now false" : "needs checking"} after ${finding.units.map((unit) => `${unit.name} (${unit.file})`).join(", ")}`,
+            value: { head: "now_false", p: finding.probability },
+            band: finding.band,
+            reason: finding.reason,
+        }));
+        const envelope = buildEnvelope({
+            answers,
+            limitations: emptyBase !== undefined && !refusal
+                ? [
+                    ...limitations,
+                    {
+                        fact: `no changed units against ${emptyBase}`,
+                        next: "nothing judged; pass base= or check the working directory",
+                    },
+                ]
+                : limitations,
+            ...(collection || unjudged
+                ? {
+                    lines: [
+                        ...(collection
+                            ? [
+                                {
+                                    type: "collection",
+                                    title: "anchored documentation unexplored; directly cited sections were checked",
+                                    count: collection.count,
+                                    items: collection.sections.slice(0, DOCS_DISPLAY_MAX_SECTIONS),
+                                    next: "Read these sections; narrow the diff with base=… to target their dependency.",
+                                },
+                            ]
+                            : []),
+                        ...(unjudged
+                            ? [
+                                {
+                                    type: "collection",
+                                    title: "matching documentation unjudged",
+                                    count: unjudged.count,
+                                    items: unjudged.sections.slice(0, DOCS_DISPLAY_MAX_SECTIONS),
+                                    next: "Read these sections or rerun on the relevant documentation.",
+                                },
+                            ]
+                            : []),
+                    ],
+                }
+                : {}),
+            unchecked: unjudged ? [] : unchecked,
+            budget,
+            refusal,
+            ...(!refusal &&
+                !budget &&
+                !collection &&
+                !unchecked.length &&
+                !findings.length &&
+                emptyBase === undefined
+                ? {
+                    lines: [
+                        {
+                            type: "list",
+                            title: "docs: no stale sentences reported",
+                            items: [],
+                        },
+                    ],
+                }
+                : {}),
+            yield: {
+                calls: judgments.reduce((n, j) => n + (j.calls ?? 0), 0),
+                questions: judgments.reduce((n, j) => n + (j.questions ?? 0), 0),
+                costUsd: judgments.reduce((n, j) => n + (j.usage?.costUsd ?? 0), 0),
+                cacheHits: judgments.reduce((n, j) => n + (j.cacheHits ?? 0), 0),
+                cacheRequests: judgments.reduce((n, j) => n + (j.cacheRequests ?? 0), 0),
+                elapsedMs: performance.now() - started,
+            },
+        });
+        return {
+            ok: !refusal,
+            status: timeout?.aborted
+                ? "budget_exceeded"
+                : refusal
+                    ? "refused"
+                    : collection
+                        ? "collect_budget_reached"
+                        : "completed",
+            envelope,
+            judgments,
+            findings,
+            ...(collection ? { collection } : {}),
+            ...(unjudged ? { unjudged } : {}),
+        };
+    };
+    const client = deps.client;
+    if (!client)
+        return finish(NOT_CONFIGURED);
+    const sessionRefusal = deps.runtime.session.refusal();
+    if (sessionRefusal)
+        return finish(sessionRefusal);
+    try {
+        const comparison = await resolveBase(deps.exec, input.cwd, input.base, signal);
+        if (!comparison.ok)
+            return finish(comparison.error);
+        const base = comparison.base;
+        const analysis = await createAnalysisContext();
+        const [collected, inventory] = await Promise.all([
+            collectUnits(deps.exec, { cwd: input.cwd, base, signal }, analysis.parser),
+            collectDocsInventory(deps.exec, input.cwd, signal),
+        ]);
+        if (!collected.ok)
+            return finish(collected.error);
+        if (!inventory.ok)
+            return finish(inventory.error);
+        for (const limit of collected.limits)
+            limitations.push({
+                fact: `${limit.file} : ${limit.kind}`,
+                next: "Read the complete change before concluding.",
+            });
+        if (!collected.units.length) {
+            emptyBase = base;
+            return finish();
+        }
+        const collectDeadline = performance.now() + DOCS_COLLECT_BUDGET_MS;
+        const candidates = await collectDocsCandidates(inventory.files, collected.units, {
+            known: inventory.tracked,
+            read: inventory.read,
+            declarations: docsDeclarationSearch(deps.exec, inventory, signal),
+            changedFiles: collected.files,
+            lexical: analysis,
+            shouldStop: () => performance.now() >= collectDeadline || !!signal?.aborted,
+        });
+        for (const limit of inventory.limits)
+            limitations.push({
+                fact: `${limit.path} : ${limit.reason}`,
+                next: "Read the omitted file; its documentation or imports are unchecked.",
+            });
+        for (const limit of candidates.limits) {
+            if (limit.kind === "collection_budget") {
+                const changedParts = collected.units.map((unit) => unit.file.split("/"));
+                const sections = (limit.sections ?? [])
+                    .map((section) => {
+                    const parts = (section.split(" § ")[0] ?? "").split("/");
+                    const proximity = changedParts.reduce((best, changed) => {
+                        let common = 0;
+                        while (common < parts.length &&
+                            common < changed.length &&
+                            parts[common] === changed[common])
+                            common++;
+                        return Math.max(best, common);
+                    }, 0);
+                    return { section, proximity };
+                })
+                    .sort((a, b) => b.proximity - a.proximity);
+                collection = {
+                    kind: limit.kind,
+                    count: sections.length,
+                    sections: sections
+                        .slice(0, DOCS_MAX_SECTIONS)
+                        .map((item) => item.section),
+                    truncated: sections.length > DOCS_MAX_SECTIONS,
+                };
+            }
+            else
+                limitations.push({
+                    fact: `${limit.path} : ${limit.reason}`,
+                    next: "Read the unresolved dependency; closure follows static imports only.",
+                });
+        }
+        for (const omitted of candidates.omitted)
+            unchecked.push(`${omitted.path} § ${omitted.heading} (DOCS_MAX_SECTIONS)`);
+        await Promise.all(candidates.candidates.map(async (candidate) => {
+            const label = `${candidate.path} § ${candidate.heading}`;
+            if (candidate.units.some((unit) => unit.before === null && unit.after === null)) {
+                unchecked.push(`${label} (changed source unavailable)`);
+                return;
+            }
+            if (budget?.kind === "session") {
+                unchecked.push(`${label} (${budget.message})`);
+                return;
+            }
+            const prepared = prepareDocsCheck(candidate);
+            if (JSON.stringify(prepared.state).length > STATE_MAX_CHARS ||
+                candidate.sentences.length + 1 > CHOICE_MAX_OPTIONS) {
+                unchecked.push(`${label} (state or pointer too large)`);
+                return;
+            }
+            if (signal?.aborted) {
+                unchecked.push(`${label} (budget exceeded or canceled)`);
+                return;
+            }
+            const judgment = await client.judge(prepared.state, prepared.questions, {
+                signal,
+                ...deps.runtime.session.requestGate(),
+                beforeRequest(questionCount) {
+                    if (budget?.kind === "session")
+                        return { ok: false, error: budget.message };
+                    if (signal?.aborted)
+                        return {
+                            ok: false,
+                            error: "Budget exceeded or call canceled.",
+                        };
+                    if (input.maxCalls !== undefined && sent >= input.maxCalls) {
+                        budget = {
+                            kind: "max_calls",
+                            message: `max_calls=${input.maxCalls} reached`,
+                        };
+                        return { ok: false, error: budget.message };
+                    }
+                    const admitted = deps.runtime.session.admit(questionCount);
+                    if (!admitted.ok)
+                        budget = { kind: "session", message: admitted.error };
+                    else
+                        sent++;
+                    return admitted;
+                },
+                onUsage: (usage) => deps.runtime.session.recordUsage(usage),
+            });
+            judgments.push(judgment);
+            if (!judgment.ok) {
+                unchecked.push(`${label} (${judgment.error})`);
+                return;
+            }
+            if (!judgment.answers.status ||
+                !judgment.answers.sentence ||
+                Object.values(judgment.answers).some((answer) => answer.type === "unjudged")) {
+                unchecked.push(`${label} (unjudged question)`);
+                const finding = readDocsJudgment(candidate, judgment.answers);
+                if (finding)
+                    findings.push({
+                        ...finding,
+                        band: "unsure",
+                        reason: "unjudged question: read the section",
+                    });
+                return;
+            }
+            const finding = readDocsJudgment(candidate, judgment.answers);
+            if (finding) {
+                const incomplete = candidate.units.some((unit) => collected.limits.some((limit) => limit.file === unit.file));
+                findings.push(incomplete
+                    ? {
+                        ...finding,
+                        band: "unsure",
+                        reason: "incomplete change evidence: read the omitted pieces",
+                    }
+                    : finding);
+            }
+        }));
+        findings.sort((a, b) => a.section.path.localeCompare(b.section.path) ||
+            a.section.start - b.section.start);
+        unchecked.sort();
+        return finish();
+    }
+    catch (error) {
+        if (signal?.aborted)
+            return finish(timeout?.aborted ? "Docs budget exceeded." : "Docs check canceled.");
+        throw error;
+    }
+}

package/dist/tools/find.js

@@ -0,0 +1,389 @@
+import { Type } from "@sinclair/typebox";
+import { canonicalPath } from "../adapters/canonical-path.js";
+import { collectSearchExcerpts } from "../adapters/files.js";
+import { prefilter } from "../adapters/find.js";
+import { shareGitInventory } from "../adapters/git-inventory.js";
+import { hostUsage } from "../adapters/usage.js";
+import * as C from "../constants.js";
+import { contentWords, findKeywords, rankFiles, retainFiles, } from "../core/find.js";
+import { buildEnvelope, } from "../core/output.js";
+import { needsReverse, pointerQuestion, readPointer } from "../core/pointer.js";
+import { interpolate } from "../describe.js";
+import { renderEnvelope } from "../render.js";
+import { NOT_CONFIGURED } from "../texts/configuration.js";
+import { FIND_DESCRIPTION } from "../texts/find.js";
+export const findParameters = Type.Object({
+    goal: Type.String({ minLength: 1 }),
+    keywords: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    scope: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())])),
+    exclude: Type.Optional(Type.Array(Type.String())),
+    effort: Type.Optional(Type.Union([
+        Type.Literal("quick"),
+        Type.Literal("default"),
+        Type.Literal("thorough"),
+    ])),
+    max_calls: Type.Optional(Type.Integer({ minimum: 0 })),
+}, { additionalProperties: false });
+export function createFindFilesTool(dependencies) {
+    const { host, runtime, exec: execute } = dependencies;
+    return {
+        name: "jev_find_files",
+        label: "Jev find files",
+        description: interpolate(FIND_DESCRIPTION, host.names),
+        parameters: findParameters,
+        ...(host.isOmp
+            ? {
+                approval: "read",
+                loadMode: "essential",
+                defaultInactive: true,
+            }
+            : {
+                promptSnippet: "Find the files for a goal described in plain words, ranked, with an entry point",
+                promptGuidelines: [
+                    "jev_find_files: describe the behavior in one sentence of five words or more, not a guessed identifier",
+                ],
+            }),
+        async execute(_id, args, signal, _update, ctx) {
+            const client = dependencies.client;
+            const cwd = await canonicalPath(ctx.cwd);
+            const started = performance.now();
+            const exec = shareGitInventory(execute);
+            const totals = {
+                calls: 0,
+                questions: 0,
+                cacheHits: 0,
+                cacheRequests: 0,
+                usage: { inputTokens: 0, costUsd: 0 },
+            };
+            const limitations = [];
+            const unchecked = [];
+            let budget;
+            let sent = 0;
+            const finish = (input) => {
+                const envelope = buildEnvelope({
+                    ...input,
+                    limitations: [...limitations, ...(input.limitations ?? [])],
+                    ...(budget ? { budget, unchecked: [...new Set(unchecked)] } : {}),
+                    yield: {
+                        ...totals,
+                        costUsd: totals.usage.costUsd,
+                        elapsedMs: performance.now() - started,
+                    },
+                });
+                runtime.session.record(envelope);
+                runtime.guide.deliver(ctx);
+                return {
+                    content: [{ type: "text", text: renderEnvelope(envelope) }],
+                    details: totals,
+                    ...hostUsage(host.isOmp, totals.usage),
+                };
+            };
+            if (!client)
+                return finish({ refusal: NOT_CONFIGURED });
+            const words = contentWords(args.goal);
+            const short = words.length < C.FIND_GOAL_MIN_WORDS;
+            if (short)
+                limitations.push({
+                    fact: `goal has ${words.length} content words: verdicts are capped at unsure`,
+                    next: "describe the behavior in one sentence",
+                });
+            const keywords = findKeywords(args.goal, args.keywords);
+            const candidateLimit = args.effort === "quick"
+                ? C.FIND_QUICK_CANDIDATES
+                : args.effort === "thorough"
+                    ? C.FIND_THOROUGH_CANDIDATES
+                    : C.FIND_NAME_CANDIDATES;
+            const readLimit = args.effort === "quick"
+                ? C.FIND_QUICK_READ
+                : args.effort === "thorough"
+                    ? C.FIND_THOROUGH_READ
+                    : C.FIND_FILES_READ;
+            const candidates = await prefilter(exec, cwd, keywords, candidateLimit, args.scope, args.exclude, signal);
+            if (!candidates.ok)
+                return finish({ refusal: candidates.error });
+            const entry = (path, p, band, alternatives = [], orderDependent = false, orderProbabilities, relevant = []) => ({
+                type: "entry",
+                candidate: { label: path, value: { head: path, p } },
+                band,
+                candidates: alternatives.map((item) => ({
+                    label: item.path,
+                    value: { head: item.path, p: item.p },
+                })),
+                orderDependent,
+                orderProbabilities,
+                relevant: relevant.map((item) => ({
+                    label: item.path,
+                    value: { head: item.path, p: item.p },
+                })),
+                nextRead: path === "none"
+                    ? []
+                    : [
+                        path,
+                        ...(band === "unsure"
+                            ? alternatives
+                                .map((item) => item.path)
+                                .filter((path) => path !== "none")
+                            : []),
+                    ],
+            });
+            if (!candidates.paths.length) {
+                limitations.push({
+                    fact: candidates.scopeFiles === 0
+                        ? "scope matched 0 files"
+                        : "no file shares a word with the goal",
+                    next: "rephrase goal or widen scope",
+                });
+                return finish({
+                    lines: [entry("none", 1, short ? "unsure" : "verdict")],
+                });
+            }
+            const judge = async (state, questions) => {
+                const result = await client.judge(state, questions, {
+                    signal,
+                    ...runtime.session.requestGate(),
+                    beforeRequest: (count) => {
+                        if (args.max_calls !== undefined && sent >= args.max_calls) {
+                            budget = {
+                                kind: "max_calls",
+                                message: `max_calls=${args.max_calls} reached`,
+                            };
+                            return { ok: false, error: budget.message };
+                        }
+                        const admission = runtime.session.admit(count);
+                        if (!admission.ok) {
+                            budget = { kind: "session", message: admission.error };
+                            return admission;
+                        }
+                        sent++;
+                        return admission;
+                    },
+                    onUsage: (usage) => runtime.session.recordUsage(usage),
+                });
+                for (const key of [
+                    "calls",
+                    "questions",
+                    "cacheHits",
+                    "cacheRequests",
+                ])
+                    totals[key] += result[key] ?? 0;
+                totals.usage.inputTokens += result.usage?.inputTokens ?? 0;
+                totals.usage.costUsd += result.usage?.costUsd ?? 0;
+                return result;
+            };
+            const boolQuestions = (paths, content) => Object.fromEntries(paths.map((path) => [
+                path,
+                {
+                    type: "bool",
+                    instructions: content
+                        ? `Does the passage from ${path} implement or document behavior that helps with this goal: ${args.goal}?`
+                        : `Could the file ${path} help with this goal: ${args.goal}?`,
+                    criteria: {
+                        true: "The file could help with the goal",
+                        false: "The file does not help with the goal",
+                    },
+                },
+            ]));
+            const names = [];
+            const nameBatches = Array.from({ length: Math.ceil(candidates.paths.length / C.FIND_NAME_BATCH) }, (_, index) => candidates.paths.slice(index * C.FIND_NAME_BATCH, (index + 1) * C.FIND_NAME_BATCH));
+            const nameResults = await Promise.all(nameBatches.map(async (paths) => ({
+                paths,
+                result: await judge({ goal: args.goal, paths }, boolQuestions(paths, false)),
+            })));
+            for (const { paths, result } of nameResults) {
+                if (!result.ok && !budget)
+                    return finish({ refusal: result.error });
+                for (const path of paths) {
+                    const answer = result.ok ? result.answers[path] : undefined;
+                    if (answer?.type === "bool")
+                        names.push({ path, p: answer.p });
+                    else
+                        unchecked.push(path);
+                }
+            }
+            const rankedNames = rankFiles(names);
+            let bestRanking = rankedNames;
+            const fallback = () => {
+                const top = bestRanking.slice(0, 2);
+                return finish({
+                    lines: [
+                        entry(top[0]?.path ?? "none", top[0]?.p ?? 0, "unsure", top.slice(1)),
+                    ],
+                    answers: bestRanking.map((item) => ({
+                        label: item.path,
+                        value: { head: "relevant", p: item.p },
+                        band: "unsure",
+                    })),
+                });
+            };
+            if (budget) {
+                unchecked.push(...candidates.paths.filter((path) => !names.some((item) => item.path === path)));
+                return fallback();
+            }
+            const readPaths = rankedNames
+                .slice(0, readLimit)
+                .map((item) => item.path);
+            const files = {};
+            const content = [];
+            const contentBatches = Array.from({ length: Math.ceil(readPaths.length / C.FIND_READ_PER_CALL) }, (_, index) => readPaths.slice(index * C.FIND_READ_PER_CALL, (index + 1) * C.FIND_READ_PER_CALL));
+            const contentResults = await Promise.all(contentBatches.map(async (paths) => {
+                const read = await collectSearchExcerpts(cwd, paths, keywords, signal, exec);
+                if (!read.ok)
+                    return { paths, result: read };
+                Object.assign(files, read.pointers);
+                limitations.push(...read.limits.map((limit) => ({
+                    fact: `${limit.path}: ${limit.reason}`,
+                    next: "provide a UTF-8 text file",
+                })));
+                if (read.ignored.length)
+                    limitations.push({
+                        fact: `${read.ignored.length} binary, empty or unreadable paths ignored: ${read.ignored.join(", ")}`,
+                        next: "narrow scope to text files",
+                    });
+                const textPaths = paths.filter((path) => read.files[path] !== undefined);
+                if (!textPaths.length)
+                    return { paths: [], result: { ok: true, answers: {} } };
+                return {
+                    paths: textPaths,
+                    result: await judge({
+                        goal: args.goal,
+                        files: Object.fromEntries(Object.entries(read.files).sort(([a], [b]) => a.localeCompare(b))),
+                    }, boolQuestions(textPaths, true)),
+                };
+            }));
+            for (const { paths, result } of contentResults) {
+                if (!result.ok && !budget)
+                    return finish({ refusal: result.error });
+                for (const path of paths) {
+                    const answer = result.ok ? result.answers[path] : undefined;
+                    if (answer?.type === "bool")
+                        content.push({ path, p: answer.p });
+                    else
+                        unchecked.push(path);
+                }
+            }
+            if (content.length)
+                bestRanking = rankFiles(content);
+            if (budget) {
+                unchecked.push(...readPaths.filter((path) => !content.some((item) => item.path === path)));
+                return fallback();
+            }
+            const retained = retainFiles(content, rankedNames);
+            limitations.push({
+                fact: `cascade: ${names.length} names judged → ${content.length} files read → ${retained.length} shown to the pointer`,
+                next: "",
+            });
+            const relevant = rankFiles(content).filter((item) => retained.some((file) => file.path === item.path));
+            const output = (path, p, band, alternatives = [], orderDependent = false, orderProbabilities) => finish({
+                lines: [
+                    entry(path, p, band, alternatives, orderDependent, orderProbabilities, relevant),
+                ],
+            });
+            if (!retained.length) {
+                limitations.push({
+                    fact: "no file retained by content or names guard",
+                    next: "rephrase goal or widen scope",
+                });
+                return output("none", 1, short ? "unsure" : "verdict");
+            }
+            const idByPath = Object.fromEntries(retained.map((item, index) => [item.path, `c${index + 1}`]));
+            const pathById = Object.fromEntries(retained.map((item, index) => [`c${index + 1}`, item.path]));
+            const pointer = async (paths) => {
+                return judge({
+                    goal: args.goal,
+                    candidates: paths.map((path) => ({
+                        id: idByPath[path] ?? "",
+                        path,
+                        excerpt: files[path] ?? "",
+                    })),
+                }, {
+                    entry: pointerQuestion({
+                        instructions: `Which candidate is the best entry point for this goal: ${args.goal}? Choose none if no passage helps.`,
+                        noneLabel: "No candidate implements or documents the goal",
+                        candidates: paths.map((path) => ({
+                            id: idByPath[path] ?? "",
+                            label: `Candidate ${idByPath[path]}`,
+                        })),
+                    }),
+                });
+            };
+            const paths = retained.map((item) => item.path);
+            const firstResult = await pointer(paths);
+            if (!firstResult.ok && !budget)
+                return finish({ refusal: firstResult.error });
+            const first = firstResult.ok ? firstResult.answers.entry : undefined;
+            if (first?.type !== "choice") {
+                unchecked.push("entry");
+                return fallback();
+            }
+            const ranked = (probabilities) => readPointer(probabilities).ranked.map(({ id, p }) => ({ path: id, p }));
+            const firstRanks = ranked(first.probabilities);
+            const firstTop = firstRanks[0];
+            if (!firstTop)
+                return finish({ refusal: "Pointer returned no probabilities." });
+            let ranks = firstRanks;
+            let band = firstTop.p >= C.ORDER_REVERSE_BELOW ? "verdict" : "unsure";
+            let disagreement = false;
+            let orderDependent = false;
+            let orderProbabilities;
+            if (retained.length > 1 &&
+                (args.effort === "thorough" ||
+                    (args.effort !== "quick" &&
+                        needsReverse(first.probabilities, retained.length)))) {
+                const secondResult = await pointer([...paths].reverse());
+                if (!secondResult.ok && !budget)
+                    return finish({ refusal: secondResult.error });
+                const second = secondResult.ok ? secondResult.answers.entry : undefined;
+                if (second?.type !== "choice") {
+                    unchecked.push("entry confirmation");
+                    band = "unsure";
+                }
+                else {
+                    const secondRanks = ranked(second.probabilities);
+                    const combined = readPointer(first.probabilities, second.probabilities);
+                    ranks = combined.ranked.map(({ id, p }) => ({ path: id, p }));
+                    disagreement = firstTop.path !== secondRanks[0]?.path;
+                    const chosen = ranks[0]?.path ?? firstTop.path;
+                    orderProbabilities = [
+                        first.probabilities[chosen] ?? 0,
+                        second.probabilities[chosen] ?? 0,
+                    ];
+                    orderDependent = combined.orderDependent;
+                    band =
+                        !disagreement && (ranks[0]?.p ?? 0) >= C.FIND_CONFIRM_MIN
+                            ? "verdict"
+                            : "unsure";
+                }
+            }
+            if (disagreement)
+                limitations.push({
+                    fact: "the two orders disagree",
+                    next: ranks.slice(0, 2).every((item) => item.path !== "none")
+                        ? "read both"
+                        : "read the named file if present; rephrase goal or widen scope",
+                });
+            else if (band === "unsure")
+                limitations.push({
+                    fact: "entry probability below confirmation threshold",
+                    next: ranks.slice(0, 2).every((item) => item.path !== "none")
+                        ? "read both"
+                        : "read the named file if present; rephrase goal or widen scope",
+                });
+            const top = ranks[0];
+            if (!top)
+                return finish({ refusal: "Pointer returned no probabilities." });
+            if (top.path === "none")
+                limitations.push({
+                    fact: "pointer chose none",
+                    next: "rephrase goal or widen scope",
+                });
+            return output(top.path === "none" ? "none" : (pathById[top.path] ?? top.path), top.p, short || budget ? "unsure" : band, band === "unsure" || short
+                ? ranks.slice(1, 2).map((item) => ({
+                    path: item.path === "none"
+                        ? "none"
+                        : (pathById[item.path] ?? item.path),
+                    p: item.p,
+                }))
+                : [], orderDependent, orderProbabilities);
+        },
+    };
+}