jev-agent-tools 0.2.0 → 0.3.0

package/dist/tools/ask.js

@@ -6,6 +6,7 @@ import { collectAskRepository, repositoryPath } from "../adapters/ask-proof.js";
 import { collectProofSyntax } from "../adapters/ask-syntax.js";
 import { canonicalPath } from "../adapters/canonical-path.js";
 import { captureCommand } from "../adapters/command.js";
+import { resolveEvidenceContext, withEvidenceContext, } from "../adapters/evidence-context.js";
 import { collectFiles } from "../adapters/files.js";
 import { shareGitInventory } from "../adapters/git-inventory.js";
 import { hostUsage } from "../adapters/usage.js";
@@ -17,17 +18,20 @@ import { outputChunks, selectOutput } from "../core/command-output.js";
 import { createImportGraphBuilder, } from "../core/imports.js";
 import { checkIntegrity } from "../core/integrity.js";
 import { buildEnvelope } from "../core/output.js";
+import { answerItemFromInput, buildResultReport, contextFromEvidence, known, notApplicable, unknown, } from "../core/result-report.js";
 import { assembleState } from "../core/state.js";
 import { discoverTests } from "../core/test-discovery.js";
 import { describeAsk } from "../describe.js";
-import { renderEnvelope } from "../render.js";
+import { renderResultReport } from "../render.js";
 import { isRecord } from "../result.js";
 import { COMMAND_LIMIT_NOTICE } from "../texts/ask.js";
 import { NOT_CONFIGURED } from "../texts/configuration.js";
+import { ASK_GUIDELINE } from "../texts/instructions.js";
 import { asksParameter } from "./ask-schema.js";
 export const askParameters = Type.Object({
+    root: Type.Optional(Type.String()),
     state: Type.Optional(Type.String({ maxLength: ASK_NOTE_MAX_CHARS })),
-    paths: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { maxItems: ASK_MAX_FILES })),
+    paths: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
     base: Type.Optional(Type.String({ minLength: 1 })),
     command: Type.Optional(Type.String({ minLength: 1 })),
     timeout_s: Type.Optional(Type.Number({
@@ -57,14 +61,49 @@ export function createAskTool(dependencies) {
             }
             : {
                 promptSnippet: "Typed answers about one situation built from a note, files and a command's output",
-                promptGuidelines: [
-                    "jev_ask: before you conclude that a failure is a bug in the code, a wrong test or the environment, or that a plan matches the docs, pass the files to jev_ask and weigh its answer against your own reading",
-                ],
+                promptGuidelines: [ASK_GUIDELINE],
             }),
         async execute(_id, args, signal, _update, ctx) {
             const client = dependencies.client;
-            const cwd = await canonicalPath(ctx.cwd);
+            const evidence = await resolveEvidenceContext(ctx.cwd, args.root, {
+                exec: execute,
+                signal,
+                origin: dependencies.evidenceOrigin,
+            });
+            const evidenceContext = evidence.context;
+            const cwd = evidence.ok ? evidence.cwd : evidenceContext.authority.path;
             const started = performance.now();
+            const evidenceFacts = {
+                omissions: [],
+                blockedGroups: [],
+                inventory: [],
+            };
+            evidenceContext.requestedBase = args.base;
+            const asks = compileAsks(args.asks, { surface: "ask" });
+            let commandContext = args.command
+                ? {
+                    execution: "not_started",
+                    cwd: evidence.ok
+                        ? known(cwd)
+                        : unknown("effective root not established"),
+                    exitCode: unknown("command not started"),
+                    timedOut: unknown("command not started"),
+                }
+                : {
+                    execution: "not_requested",
+                    cwd: notApplicable("no command"),
+                    exitCode: notApplicable("no command"),
+                    timedOut: notApplicable("no command"),
+                };
+            let refusalCause = "invalid_arguments";
+            let inventoryCollected = false;
+            const auxiliary = {
+                controls: { fresh: 0, cache: 0, notJudged: 0, static: 0 },
+                passages: { fresh: 0, cache: 0, notJudged: 0 },
+            };
+            const attributionAnswers = {};
+            const attributionMissing = new Set();
+            const findResults = [];
             const exec = shareGitInventory(execute);
             const finish = (result, input) => {
                 const envelope = buildEnvelope({
@@ -79,15 +118,246 @@ export function createAskTool(dependencies) {
                     },
                 });
                 runtime.session.record(envelope);
+                const diagnostics = [];
+                const actions = [];
+                const globalMissing = new Map();
+                const diagnose = (cause, fact, scope, target, origin, effect = "blocking", next) => {
+                    const id = `diagnostic:${diagnostics.length}`;
+                    const actionId = `action:${actions.length}`;
+                    const code = cause === "invalid_root" || cause === "invalid_base"
+                        ? "correct_context"
+                        : cause === "forbidden_path"
+                            ? "correct_reference"
+                            : cause === "missing_required" || cause === "empty_required"
+                                ? "provide_evidence"
+                                : cause === "not_configured"
+                                    ? "configure_client"
+                                    : "inspect_native";
+                    actions.push({
+                        id: actionId,
+                        code,
+                        target: target === undefined
+                            ? unknown("target not established")
+                            : known(target),
+                        scope,
+                        condition: "Only if materially new evidence or corrected context is available",
+                        instruction: next ??
+                            (code === "provide_evidence"
+                                ? `Provide the actually missing evidence${target ? `: ${target}` : ""}; do not repeat an already captured command.`
+                                : "Inspect the supplied evidence natively; correct the named cause before any useful new Jev call."),
+                        repeatUnchanged: false,
+                    });
+                    diagnostics.push({
+                        id,
+                        cause,
+                        fact,
+                        target: target === undefined
+                            ? unknown("target not established")
+                            : known(target),
+                        origin,
+                        scope,
+                        effect,
+                        material: true,
+                        omittedMembers: [],
+                        memberCount: known(0),
+                        actionIds: [actionId],
+                    });
+                    return { diagnosticIds: [id], actionIds: [actionId] };
+                };
+                const items = asks.ok
+                    ? asks.readings.map((reading, index) => {
+                        const groupId = `group:${asks.groups.findIndex((group) => group.includes(reading.id))}`;
+                        const target = asks.asks[reading.askIndex]?.about ?? "state";
+                        const pieces = [
+                            {
+                                target,
+                                canonicalPath: unknown("selector does not establish a canonical file identity"),
+                                aliases: [],
+                                side: target === "output" ? "output" : "state",
+                                revision: notApplicable("non-file evidence"),
+                            },
+                        ];
+                        for (const [alias, path] of Object.entries(evidenceFacts.references?.aliases ?? {})) {
+                            const before = evidenceFacts.references?.additions.some((addition) => addition.reference === alias &&
+                                addition.side === "files_before") || target.includes("files_before");
+                            pieces.push({
+                                target: alias,
+                                canonicalPath: evidenceContext.effectiveRoot
+                                    ? known(resolve(evidenceContext.effectiveRoot.path, path))
+                                    : unknown("effective root unavailable"),
+                                aliases: [alias],
+                                side: before ? "before" : "current",
+                                revision: before && evidenceContext.resolvedBase
+                                    ? known(evidenceContext.resolvedBase)
+                                    : unknown("working tree evidence"),
+                            });
+                        }
+                        const common = {
+                            id: reading.id,
+                            kind: reading.kind === "verify"
+                                ? "claim"
+                                : "question",
+                            label: reading.label,
+                            groupId,
+                            evidence: pieces,
+                            diagnosticIds: [],
+                            actionIds: [],
+                        };
+                        const originalAnswer = input.answers?.[index];
+                        const attributionControls = attributionAnswers[reading.id];
+                        const answer = originalAnswer && attributionMissing.has(reading.id)
+                            ? {
+                                ...originalAnswer,
+                                unjudged: true,
+                                reason: "Required attribution control is incomplete",
+                            }
+                            : originalAnswer && attributionControls
+                                ? {
+                                    ...originalAnswer,
+                                    reportControls: [
+                                        ...(originalAnswer.reportControls ?? []),
+                                        ...attributionControls,
+                                    ],
+                                }
+                                : originalAnswer;
+                        if (answer &&
+                            !answer.unjudged &&
+                            (answer.source || answer.answer?.source))
+                            return answerItemFromInput(common, input.controls?.length
+                                ? {
+                                    ...answer,
+                                    band: "unsure",
+                                    reason: input.controls
+                                        .map((control) => control.fact)
+                                        .join("; "),
+                                }
+                                : answer);
+                        const blocked = evidenceFacts.blockedGroups.find((group) => group.ids.includes(reading.id));
+                        const omission = evidenceFacts.omissions.find((item) => item.required &&
+                            (item.origin === "note" || item.scope === reading.id));
+                        const groupFailure = result.ok
+                            ? (asks.groups.find((group) => group.includes(reading.id)) ??
+                                [])
+                                .map((id) => result.answers[id])
+                                .find((answer) => answer?.type === "unjudged" && answer.cause)
+                            : undefined;
+                        const cause = blocked
+                            ? (blocked.cause ?? "missing_required")
+                            : groupFailure?.type === "unjudged" && groupFailure.cause
+                                ? groupFailure.cause
+                                : input.budget
+                                    ? input.budget.kind === "session"
+                                        ? "session_budget"
+                                        : "call_budget"
+                                    : (result.failureCause ??
+                                        (input.refusal ? refusalCause : "control_failure"));
+                        const globalKey = omission?.origin === "note" ? omission.reference : undefined;
+                        const existingLinks = globalKey
+                            ? globalMissing.get(globalKey)
+                            : undefined;
+                        const links = existingLinks ??
+                            diagnose(cause, blocked?.reason ??
+                                answer?.reason ??
+                                (result.ok
+                                    ? "Required judgment group incomplete or response provenance not established"
+                                    : result.error), omission?.origin === "note"
+                                ? { kind: "call" }
+                                : { kind: "group", groupIds: [groupId] }, omission?.reference, omission?.origin === "note"
+                                ? "note"
+                                : blocked
+                                    ? "ask"
+                                    : input.budget
+                                        ? "budget"
+                                        : "provider");
+                        if (globalKey)
+                            globalMissing.set(globalKey, links);
+                        return {
+                            ...common,
+                            ...links,
+                            treatment: "not_judged",
+                            source: "none",
+                        };
+                    })
+                    : [];
+                if (!items.length)
+                    diagnose(input.refusal ? refusalCause : "collection_empty", input.refusal ?? "No requested results collected", { kind: "call" }, undefined, "input");
+                for (const control of input.controls ?? [])
+                    diagnose("control_failure", control.fact, { kind: "call" }, undefined, "control", "reservation", control.next);
+                for (const limitation of input.limitations ?? [])
+                    diagnose("evidence_limit", limitation.fact, { kind: "call" }, limitation.path, "closure", "reservation", limitation.next);
+                const report = buildResultReport({
+                    tool: "jev_ask",
+                    context: contextFromEvidence(evidenceContext, {
+                        command: commandContext,
+                        inventories: inventoryCollected
+                            ? [
+                                {
+                                    id: "repository",
+                                    kind: "repository",
+                                    rules: ["Git tracked and admitted repository evidence"],
+                                    restrictions: args.paths ?? [],
+                                    discovered: known(evidenceFacts.inventory.length),
+                                    considered: known(evidenceFacts.inventory.length),
+                                    scopeRestricted: false,
+                                    criteria: [],
+                                },
+                            ]
+                            : [],
+                    }),
+                    items,
+                    diagnostics,
+                    actions,
+                    metrics: {
+                        calls: result.calls ?? 0,
+                        questions: result.questions ?? 0,
+                        cacheHits: result.cacheHits ?? 0,
+                        cacheRequests: result.cacheRequests ?? 0,
+                        costUsd: result.usage?.costUsd,
+                        elapsedMs: performance.now() - started,
+                    },
+                    auxiliary,
+                    total: known(items.length),
+                    refused: !!input.refusal &&
+                        refusalCause !== "not_configured" &&
+                        !result.failureCause,
+                });
                 runtime.guide.deliver(ctx);
                 return {
-                    content: [{ type: "text", text: renderEnvelope(envelope) }],
-                    details: result,
+                    content: [
+                        {
+                            type: "text",
+                            text: renderResultReport(report, { details: envelope }),
+                        },
+                    ],
+                    details: {
+                        ...result,
+                        result: report,
+                        evidenceContext,
+                        evidenceFacts,
+                    },
                 };
             };
-            const textResult = (text) => finish({ ok: false, error: text }, { refusal: text });
+            const textResult = (text, cause = "invalid_arguments") => {
+                refusalCause = cause;
+                const technical = findResults.reduce((totals, judgment) => ({
+                    calls: totals.calls + (judgment.calls ?? 0),
+                    questions: totals.questions + (judgment.questions ?? 0),
+                    cacheHits: totals.cacheHits + (judgment.cacheHits ?? 0),
+                    cacheRequests: totals.cacheRequests + (judgment.cacheRequests ?? 0),
+                }), { calls: 0, questions: 0, cacheHits: 0, cacheRequests: 0 });
+                return finish({ ok: false, error: text, ...technical }, { refusal: text });
+            };
+            if (!evidence.ok)
+                return textResult(evidence.error, evidence.cause ?? "invalid_root");
+            if (!asks.ok)
+                return textResult(asks.error);
+            const preliminary = resolveAskReferences(asks, args.state, {}, []);
+            if (preliminary.invalid.length) {
+                evidenceFacts.references = preliminary;
+                return textResult(preliminary.invalid.map((item) => item.reason).join("; "), "forbidden_path");
+            }
             if (!client)
-                return textResult(NOT_CONFIGURED);
+                return textResult(NOT_CONFIGURED, "not_configured");
             if (args.command && !allowCommand)
                 return textResult("command disabled by JEV_TOOLS_ALLOW_COMMAND=0");
             if (args.timeout_s !== undefined &&
@@ -97,48 +367,80 @@ export function createAskTool(dependencies) {
                 return textResult(`timeout_s must be between 1 and ${ASK_TIMEOUT_MAX_S}`);
             if (args.state === undefined && !args.paths?.length && !args.command)
                 return textResult("Provide state, command or at least one path.");
-            const asks = compileAsks(args.asks, { surface: "ask" });
-            if (!asks.ok)
-                return textResult(asks.error);
             const files = await collectFiles(cwd, args.paths ?? [], signal, {
                 exec,
                 allowEmpty: true,
                 skipInvalidUtf8: true,
             });
             if (!files.ok)
-                return textResult(files.error);
+                return textResult(files.error, files.cause ?? "file_unavailable");
             if (!Object.keys(files.files).length &&
                 args.state === undefined &&
                 !args.command &&
                 files.skipped.length)
-                return textResult(`No readable evidence: ${files.skipped.join("; ")}`);
+                return textResult(`No readable evidence: ${files.skipped.join("; ")}`, "collection_empty");
             const proofLimitations = files.skipped.map((fact) => ({
                 fact,
                 next: "Provide this file as UTF-8 text if the judgment needs it.",
             }));
             let repository = await collectAskRepository(exec, cwd, args.base, signal);
+            inventoryCollected = repository.ok;
+            if (repository.ok) {
+                evidenceFacts.inventory = [...repository.known];
+                evidenceContext.resolvedBase = repository.baseSha;
+            }
             if (!repository.ok && args.base)
-                return textResult(repository.error);
+                return textResult(repository.error, "invalid_base");
             if (!repository.ok)
                 proofLimitations.push({
                     fact: `closure unavailable: ${repository.error}`,
                     next: "pass dependencies explicitly in paths",
                 });
+            if (args.command)
+                commandContext = {
+                    ...commandContext,
+                    execution: "started",
+                    cwd: known(repository.ok ? repository.root : cwd),
+                };
             const command = args.command
-                ? await captureCommand(exec, repository.ok ? repository.root : cwd, args.command, args.timeout_s, signal)
+                ? await captureCommand(exec, repository.ok ? repository.root : cwd, args.command, args.timeout_s, signal, dependencies.apiKey ?? process.env.JEV_TOOLS_API_KEY)
                 : undefined;
-            if (command && !command.ok)
-                return textResult(command.error);
+            if (command?.ok)
+                commandContext = {
+                    execution: "finished",
+                    cwd: known(repository.ok ? repository.root : cwd),
+                    exitCode: known(command.output.exit_code),
+                    timedOut: known(command.output.timed_out),
+                };
+            if (command && !command.ok) {
+                commandContext = {
+                    // Reported execution states are not_requested, not_started, started
+                    // and finished. A spawn whose completion was not observed (adapter
+                    // "unknown") did start, so it reports "started" with unknown exit
+                    // code and timeout.
+                    execution: command.commandExecution === "unknown"
+                        ? "started"
+                        : command.commandExecution,
+                    cwd: known(repository.ok ? repository.root : cwd),
+                    exitCode: command.commandExitCode !== undefined
+                        ? known(command.commandExitCode)
+                        : unknown("command completion not observed"),
+                    timedOut: command.commandTimedOut !== undefined
+                        ? known(command.commandTimedOut)
+                        : unknown("command completion not observed"),
+                };
+                return textResult(command.error, command.cause ?? "file_unavailable");
+            }
             if (command?.ok) {
                 repository = await collectAskRepository(exec, cwd, args.base, signal);
                 if (!repository.ok && args.base)
-                    return textResult(repository.error);
+                    return textResult(repository.error, "invalid_base");
             }
             const initialState = assembleState(args.state, files.files);
             if (!initialState.ok)
                 return textResult(initialState.error);
             if (command?.ok && Object.hasOwn(initialState.state, "output"))
-                return textResult("state contains reserved key output when command is supplied; rename it in your note");
+                return textResult("state contains reserved key output when command is supplied; rename it in your note", "reserved_key");
             let outputNotIdentifiable = false;
             if (command?.ok && repository.ok) {
                 for (const target of command.targets) {
@@ -211,11 +513,42 @@ export function createAskTool(dependencies) {
                 (!command.targets.length || !repository.ok) &&
                 !discoverTests(Object.entries(files.files).map(([path, text]) => ({ path, text }))).entries.length)
                 outputNotIdentifiable = true;
-            const references = resolveAskReferences(asks, args.state, files.files, repository?.ok ? [...repository.known] : []);
+            const references = resolveAskReferences(asks, args.state, repository.ok
+                ? {
+                    files: Object.fromEntries(Object.entries(files.files).map(([path, text]) => [
+                        repositoryPath(repository.root, cwd, path),
+                        text,
+                    ])),
+                    beforeInventory: args.base ? [...repository.beforeKnown] : [],
+                }
+                : files.files, repository?.ok ? [...repository.known] : []);
+            evidenceFacts.references = references;
+            evidenceFacts.inventory = repository.ok ? [...repository.known] : [];
+            if (references.invalid.length)
+                return textResult(references.invalid.map((item) => item.reason).join("; "), "forbidden_path");
             const unresolved = [...references.unresolved];
+            const historical = {};
+            if (repository.ok && args.base) {
+                for (const reference of references.additions.filter((reference) => reference.side === "files_before" && reference.required)) {
+                    const before = await repository.readBefore(reference.path);
+                    if (before.ok)
+                        historical[reference.path] = before.text;
+                    else {
+                        if (before.cause === "forbidden_path")
+                            return textResult(before.error, before.cause);
+                        unresolved.push({
+                            ...reference,
+                            reason: before.error,
+                            ...(before.cause ? { cause: before.cause } : {}),
+                        });
+                    }
+                }
+            }
             if (repository?.ok) {
                 const root = repository.root;
-                const additions = await Promise.all(references.additions.map(async (addition) => ({
+                const additions = await Promise.all(references.additions
+                    .filter((addition) => addition.side !== "files_before")
+                    .map(async (addition) => ({
                     addition,
                     added: await collectFiles(root, [addition.path], signal, {
                         allowEmpty: true,
@@ -225,16 +558,18 @@ export function createAskTool(dependencies) {
                 })));
                 for (const { addition, added } of additions) {
                     if (added.ok) {
-                        files.files[addition.reference] = added.files[addition.path] ?? "";
+                        const local = repositoryPath(cwd, root, addition.path);
+                        files.files[local] = added.files[addition.path] ?? "";
                         files.identities.push(...added.identities.map((identity) => ({
                             ...identity,
-                            requestedPath: addition.reference,
+                            requestedPath: local,
                         })));
                     }
                     else
                         unresolved.push({
-                            reference: addition.reference,
+                            ...addition,
                             reason: added.error,
+                            ...(added.cause ? { cause: added.cause } : {}),
                         });
                 }
             }
@@ -242,36 +577,48 @@ export function createAskTool(dependencies) {
             if (!state.ok)
                 return textResult(state.error);
             if (command?.ok && Object.hasOwn(state.state, "output"))
-                return textResult("state contains reserved key output when command is supplied; rename it in your note");
+                return textResult("state contains reserved key output when command is supplied; rename it in your note", "reserved_key");
             if (command?.ok)
                 state.state.output = { ...command.output };
             if (repository?.ok) {
+                if (evidenceContext.effectiveRoot)
+                    evidenceContext.effectiveRoot.path = repository.root;
+                evidenceContext.requestedBase = args.base;
+                evidenceContext.resolvedBase = repository.baseSha;
                 const canonical = Object.fromEntries(Object.entries(files.files).map(([path, text]) => [
                     repositoryPath(repository.root, cwd, path),
                     text,
                 ]));
-                for (const addition of references.additions)
-                    canonical[addition.path] = files.files[addition.reference] ?? "";
+                state.state.files = canonical;
+                state.state.evidence = {
+                    context: evidenceContext,
+                    aliases: Object.fromEntries(Object.entries(references.aliases)
+                        .map(([alias, path]) => [
+                        alias,
+                        repository.known.has(path) || repository.beforeKnown.has(path)
+                            ? path
+                            : repositoryPath(repository.root, cwd, path),
+                    ])
+                        .sort(([a], [b]) => a.localeCompare(b))),
+                };
+                // Canonical repository paths are the sole serialized content keys.
                 const sources = Object.entries(canonical).map(([path, text]) => ({ path, text }));
-                const before = {};
+                const before = { ...historical };
                 if (args.base) {
                     for (const path of Object.keys(canonical)) {
                         const old = await repository.readBefore(path);
                         if (!old.ok)
-                            return textResult(old.error);
+                            return textResult(old.error, old.cause ?? "file_unavailable");
                         before[path] = old.text;
                     }
                     state.state.base_sha = repository.baseSha ?? "";
-                    state.state.files_before = Object.fromEntries(Object.keys(files.files).map((path) => {
-                        const canonicalPath = references.additions.find((addition) => addition.reference === path)?.path ?? repositoryPath(repository.root, cwd, path);
-                        return [path, before[canonicalPath] ?? null];
-                    }));
-                    const stateSize = JSON.stringify(state.state).length;
+                    state.state.files_before = before;
+                    const stateSize = JSON.stringify(command?.ok ? { ...state.state, output: undefined } : state.state).length;
                     if (stateSize > STATE_MAX_CHARS) {
                         const partSizes = Object.entries(state.state)
                             .map(([part, value]) => `${part} ${JSON.stringify(value).length}`)
                             .join(", ");
-                        return textResult(`serialized state including files_before exceeds ${STATE_MAX_CHARS} chars (${stateSize}); serialized parts: ${partSizes}; split the situation into smaller states.`);
+                        return textResult(`serialized state including files_before exceeds ${STATE_MAX_CHARS} chars (${stateSize}); serialized parts: ${partSizes}; split the situation into smaller states.`, "evidence_too_large");
                     }
                 }
                 const configuration = [];
@@ -360,14 +707,19 @@ export function createAskTool(dependencies) {
                     sources,
                     ...(args.base ? { before } : {}),
                 };
+                const closureState = { ...state.state };
+                if (command?.ok)
+                    delete closureState.output;
                 const closure = buildAskClosure({
                     graph: { edges, limits },
                     syntax,
                     paths: Object.keys(canonical),
                     intentions: JSON.stringify(asks.asks),
-                    state: state.state,
+                    state: closureState,
                 });
                 state.state = closure.state;
+                if (command?.ok)
+                    state.state.output = { ...command.output };
                 proofLimitations.push(...closure.limitations.filter((limit) => !limit.fact.startsWith("Import closure only,")));
                 proofLimitations.push({
                     fact: `closure: +${closure.added.length}${closure.added.length ? ` (${closure.added.map((piece) => `${piece.path} ${piece.name}, ${piece.chars} chars`).join("; ")})` : ""}; imports only, depth 1; files with no import link are not checked`,
@@ -379,14 +731,27 @@ export function createAskTool(dependencies) {
                     fact: "closure: +0; imports only, depth 1; repository inventory unavailable",
                     next: "pass dependencies explicitly in paths",
                 });
+            if (!repository.ok)
+                state.state.evidence = {
+                    context: evidenceContext,
+                    aliases: references.aliases,
+                };
+            // Command output has its own passage-selection budget below. Only immutable
+            // file/note evidence can refuse here, before selection has had a chance.
+            const serializedSize = JSON.stringify(command?.ok ? { ...state.state, output: undefined } : state.state).length;
+            if (serializedSize > STATE_MAX_CHARS)
+                return textResult(`serialized state exceeds ${STATE_MAX_CHARS} chars (${serializedSize}); files and versions are never truncated`, "evidence_too_large");
+            evidenceFacts.omissions = unresolved;
             const blocked = blockedAskReadings(asks, state.state, unresolved, args.state);
             const inserted = isRecord(state.state.files) ? state.state.files : {};
             const identities = files.identities.map((file) => {
-                const content = inserted[file.requestedPath];
-                const insertedPath = Object.keys(inserted).find((path) => resolve(cwd, path) === file.resolvedPath);
+                const insertedPath = repository.ok
+                    ? repositoryPath(repository.root, cwd, file.requestedPath)
+                    : file.requestedPath;
+                const content = inserted[insertedPath];
                 return {
                     ...file,
-                    insertedPath: insertedPath ? resolve(cwd, insertedPath) : "",
+                    insertedPath: resolve(repository.ok ? repository.root : cwd, insertedPath),
                     content: typeof content === "string" ? content : "",
                     insertedSha256: createHash("sha256")
                         .update(typeof content === "string" ? content : "")
@@ -396,15 +761,32 @@ export function createAskTool(dependencies) {
             const blockedMembers = new Set(asks.groups
                 .filter((group) => group.some((id) => blocked.has(id)))
                 .flat());
+            evidenceFacts.blockedGroups = asks.groups
+                .filter((group) => group.some((id) => blocked.has(id)))
+                .map((ids) => {
+                const reason = ids
+                    .map((id) => blocked.get(id))
+                    .find((reason) => reason !== undefined) ??
+                    "Required evidence unavailable";
+                // A secret refusal stays named as such instead of missing_required.
+                const secret = unresolved.some((item) => item.reason === reason && item.cause === "secret_pattern");
+                return {
+                    ids,
+                    reason,
+                    ...(secret ? { cause: "secret_pattern" } : {}),
+                };
+            });
             const questions = Object.fromEntries(Object.entries(asks.questions).filter(([id]) => !blockedMembers.has(id)));
             const integrity = checkIntegrity(state.state, asks.asks, identities.filter((identity) => identity.content.trim().length > 0));
             let sent = 0;
             let refusal;
-            const findResults = [];
             const options = {
                 signal,
                 cache: !args.command,
                 ...runtime.session.requestGate(),
+                admissionCause: () => refusal?.kind === "session"
+                    ? "session_budget"
+                    : "call_budget",
                 beforeRequest: (questionCount) => {
                     if (args.max_calls !== undefined && sent >= args.max_calls) {
                         refusal = {
@@ -434,9 +816,12 @@ export function createAskTool(dependencies) {
                     if (command.compressedChars >
                         OUTPUT_CHUNK_CHARS * OUTPUT_FIND_MAX_CALLS ||
                         chunks.length > OUTPUT_FIND_MAX_CALLS)
-                        return textResult(`output requires more than ${OUTPUT_FIND_MAX_CALLS} find calls: ${command.originalBytes} bytes before, ${command.compressedChars} chars after compression; narrow command (remove verbosity or filter)`);
-                    const found = await Promise.all(chunks.map(async (chunk) => {
-                        const judgment = await client.judge({ output: chunk.text }, {
+                        return textResult(`output requires more than ${OUTPUT_FIND_MAX_CALLS} find calls: ${command.originalBytes} bytes before, ${command.compressedChars} chars after compression; narrow command (remove verbosity or filter)`, "evidence_too_large");
+                    const chunkStates = chunks.map((chunk) => withEvidenceContext({ output: chunk.text }, evidenceContext));
+                    if (chunkStates.some((chunkState) => JSON.stringify(chunkState).length > STATE_MAX_CHARS))
+                        return textResult(`serialized output chunk including evidence context exceeds ${STATE_MAX_CHARS} chars; narrow command`, "evidence_too_large");
+                    const found = await Promise.all(chunkStates.map(async (chunkState) => {
+                        const judgment = await client.judge(chunkState, {
                             find: {
                                 type: "bool",
                                 instructions: "Does this excerpt of a command's output show something failing (a failed test or assertion, a compiler error, a crash, an error message) with its details?",
@@ -458,7 +843,7 @@ export function createAskTool(dependencies) {
                     }).length;
                     const budget = STATE_MAX_CHARS - emptySize - 16;
                     if (budget < 100)
-                        return textResult("No space for command output; reduce paths or state.");
+                        return textResult("No space for command output; reduce paths or state.", "evidence_too_large");
                     const stderrSize = JSON.stringify(output.stderr).length;
                     const stdoutSize = JSON.stringify(output.stdout).length;
                     const stdoutBudget = !output.stderr
@@ -496,7 +881,7 @@ export function createAskTool(dependencies) {
                 integrity.controls.push(...checked.controls);
                 integrity.notes.push(...checked.notes);
                 if (JSON.stringify(state.state).length > STATE_MAX_CHARS)
-                    return textResult("serialized command output exceeds state budget; narrow command or reduce paths");
+                    return textResult("serialized command output exceeds state budget; narrow command or reduce paths", "evidence_too_large");
                 if (outputNotIdentifiable)
                     integrity.controls.push({
                         fact: "not identifiable: the output shows an assertion failure and the failing test is absent; a wrong test and a bug look alike",
@@ -542,11 +927,12 @@ export function createAskTool(dependencies) {
                         questions: (first.questions ?? 0) + (reversed.questions ?? 0),
                         cacheHits: (first.cacheHits ?? 0) + (reversed.cacheHits ?? 0),
                         cacheRequests: (first.cacheRequests ?? 0) + (reversed.cacheRequests ?? 0),
-                        usage: {
-                            inputTokens: (first.usage?.inputTokens ?? 0) +
-                                (reversed.usage?.inputTokens ?? 0),
-                            costUsd: (first.usage?.costUsd ?? 0) + (reversed.usage?.costUsd ?? 0),
-                        },
+                        usage: first.usage && reversed.usage
+                            ? {
+                                inputTokens: first.usage.inputTokens + reversed.usage.inputTokens,
+                                costUsd: first.usage.costUsd + reversed.usage.costUsd,
+                            }
+                            : undefined,
                     };
                 }
             }
@@ -555,11 +941,14 @@ export function createAskTool(dependencies) {
                     ...result,
                     calls: (result.calls ?? 0) + (found.calls ?? 0),
                     questions: (result.questions ?? 0) + (found.questions ?? 0),
-                    usage: {
-                        inputTokens: (result.usage?.inputTokens ?? 0) +
-                            (found.usage?.inputTokens ?? 0),
-                        costUsd: (result.usage?.costUsd ?? 0) + (found.usage?.costUsd ?? 0),
-                    },
+                    cacheHits: (result.cacheHits ?? 0) + (found.cacheHits ?? 0),
+                    cacheRequests: (result.cacheRequests ?? 0) + (found.cacheRequests ?? 0),
+                    usage: result.usage && found.usage
+                        ? {
+                            inputTokens: result.usage.inputTokens + found.usage.inputTokens,
+                            costUsd: result.usage.costUsd + found.usage.costUsd,
+                        }
+                        : undefined,
                 };
             const attribution = [];
             if (result.ok) {
@@ -572,6 +961,8 @@ export function createAskTool(dependencies) {
                             fact: `attribution ${reading.label}: no designated candidate`,
                             next: "provide decisive candidate evidence before acting",
                         });
+                        attributionMissing.add(reading.id);
+                        auxiliary.controls.notJudged++;
                         continue;
                     }
                     if (!Object.hasOwn(inserted, selected)) {
@@ -579,6 +970,8 @@ export function createAskTool(dependencies) {
                             fact: `attribution ${reading.label}: designated piece ${selected} is absent`,
                             next: `add ${selected} to paths before acting`,
                         });
+                        attributionMissing.add(reading.id);
+                        auxiliary.controls.notJudged++;
                         continue;
                     }
                     const selectedPath = repository?.ok
@@ -609,6 +1002,38 @@ export function createAskTool(dependencies) {
                         continue;
                     const control = await client.judge(ablated, { [reading.id]: question }, options);
                     const answer = control.ok ? control.answers[reading.id] : undefined;
+                    if (answer && answer.type !== "unjudged" && answer.source)
+                        attributionAnswers[reading.id] = [
+                            {
+                                id: `${reading.id}:attribution`,
+                                kind: "attribution",
+                                source: answer.source,
+                                outcome: answer.type === "choice"
+                                    ? answer.choice === selected
+                                        ? "does not rest on it"
+                                        : "attributed"
+                                    : "invalid attribution response",
+                                rawValues: answer.type === "bool"
+                                    ? [
+                                        {
+                                            label: "attribution",
+                                            value: answer.p >= 0.5,
+                                            probability: known(answer.p),
+                                        },
+                                    ]
+                                    : Object.entries(answer.probabilities).map(([label, value]) => ({
+                                        label,
+                                        value: label,
+                                        probability: known(value),
+                                    })),
+                            },
+                        ];
+                    if (answer?.type !== "choice")
+                        attributionMissing.add(reading.id);
+                    if (answer && answer.type !== "unjudged" && answer.source)
+                        auxiliary.controls[answer.source]++;
+                    else
+                        auxiliary.controls.notJudged++;
                     attribution.push(answer?.type === "choice"
                         ? {
                             fact: `attribution ${reading.label}: ${answer.choice === selected ? "does not rest on it" : "attributed"} (${selected})`,
@@ -624,11 +1049,12 @@ export function createAskTool(dependencies) {
                         questions: (result.questions ?? 0) + (control.questions ?? 0),
                         cacheHits: (result.cacheHits ?? 0) + (control.cacheHits ?? 0),
                         cacheRequests: (result.cacheRequests ?? 0) + (control.cacheRequests ?? 0),
-                        usage: {
-                            inputTokens: (result.usage?.inputTokens ?? 0) +
-                                (control.usage?.inputTokens ?? 0),
-                            costUsd: (result.usage?.costUsd ?? 0) + (control.usage?.costUsd ?? 0),
-                        },
+                        usage: result.usage && control.usage
+                            ? {
+                                inputTokens: result.usage.inputTokens + control.usage.inputTokens,
+                                costUsd: result.usage.costUsd + control.usage.costUsd,
+                            }
+                            : undefined,
                     };
                 }
             }
@@ -641,6 +1067,33 @@ export function createAskTool(dependencies) {
                 ].some((id) => !result.answers[id] || result.answers[id]?.type === "unjudged") ||
                 (reversed?.ok && reversed.answers[reading.id]?.type === "unjudged"))
                 .map((reading) => reading.label);
+            for (const reading of asks.readings) {
+                for (const id of [
+                    reading.twin,
+                    ...Object.values(reading.controls ?? {}),
+                ].filter((id) => !!id)) {
+                    const answer = result.ok ? result.answers[id] : undefined;
+                    if (answer && answer.type !== "unjudged" && answer.source)
+                        auxiliary.controls[answer.source]++;
+                    else
+                        auxiliary.controls.notJudged++;
+                }
+                if (reversed &&
+                    Object.hasOwn(reversed.ok ? reversed.answers : {}, reading.id)) {
+                    const answer = reversed.ok ? reversed.answers[reading.id] : undefined;
+                    if (answer && answer.type !== "unjudged" && answer.source)
+                        auxiliary.controls[answer.source]++;
+                    else
+                        auxiliary.controls.notJudged++;
+                }
+            }
+            for (const found of findResults) {
+                const answer = found.ok ? found.answers.find : undefined;
+                if (answer && answer.type !== "unjudged" && answer.source)
+                    auxiliary.passages[answer.source]++;
+                else
+                    auxiliary.passages.notJudged++;
+            }
             const output = finish(result, {
                 ...(result.ok
                     ? {
@@ -666,6 +1119,14 @@ export function createAskTool(dependencies) {
                             },
                         ]
                         : []),
+                    ...(command?.ok && command.redactions
+                        ? [
+                            {
+                                fact: `output: ${command.redactions} occurrence${command.redactions === 1 ? "" : "s"} of the configured Jev API key replaced with [redacted]`,
+                                next: "remove the key from the command's output; it is never sent to Jev",
+                            },
+                        ]
+                        : []),
                     ...(command?.ok && command.shapeLimitExceeded
                         ? [
                             {