humanish 0.106.0 → 0.107.0

package/dist/actors/scripted-browser/steps.js

@@ -52,6 +52,24 @@ export async function executeBrowserPersonaStep(args) {
         await target.click({ timeout: stepTimeoutMs });
         await args.page.waitForTimeout(300);
     }
+    else if (args.step.action === "press") {
+        if (!args.step.key) {
+            throw new Error(`${args.step.id} press step is missing key`);
+        }
+        // With a selector, Playwright focuses that element first; without one, the key goes to
+        // whatever has focus, such as the input a fill step just typed into.
+        if (args.step.selector) {
+            const target = args.page.locator(args.step.selector).first();
+            if ((await target.count()) === 0) {
+                throw new Error(`${args.step.id} press step found no target`);
+            }
+            await target.press(args.step.key, { timeout: stepTimeoutMs });
+        }
+        else {
+            await args.page.keyboard.press(args.step.key);
+        }
+        await args.page.waitForTimeout(300);
+    }
     else if (args.step.action === "assertText" || args.step.action === "waitForText") {
         const expectedText = args.step.expectation?.text ?? args.step.value;
         if (!expectedText) {

package/dist/actors/scripted-browser/types.d.ts

@@ -6,6 +6,10 @@ export interface ScriptedLocatorLike {
     click(options?: {
         timeout?: number;
     }): Promise<void>;
+    /** Focuses the element and presses the key, as Playwright's Locator.press does. */
+    press(key: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
     count(): Promise<number>;
     waitFor(options?: {
         state?: "visible";
@@ -21,6 +25,10 @@ export interface ScriptedPageLike {
         timeout?: number;
     }): Promise<unknown>;
     locator(selector: string): ScriptedLocatorLike;
+    /** Presses a key on whatever element has focus. */
+    keyboard: {
+        press(key: string): Promise<void>;
+    };
     waitForTimeout(ms: number): Promise<void>;
     waitForFunction(fn: string, arg: unknown, options?: {
         timeout?: number;
@@ -83,7 +91,7 @@ export interface BrowserSurfaceCapture {
     surface: BrowserSurface;
     tracePath: string;
 }
-export type BrowserPersonaAction = "goto" | "click" | "fill" | "assertText" | "waitForText" | "waitForSelector";
+export type BrowserPersonaAction = "goto" | "click" | "press" | "fill" | "assertText" | "waitForText" | "waitForSelector";
 export interface BrowserPersonaAssertionCapture {
     id: string;
     reason: string;
@@ -122,6 +130,8 @@ export interface BrowserPersonaStepManifest {
     path?: string;
     selector?: string;
     value?: string;
+    /** A press step's key, in Playwright's key syntax ("Enter", "Tab", "Control+A"). */
+    key?: string;
 }
 export interface BrowserPersonaJourney {
     goal: string;

package/dist/actors/stop-conditions.js

@@ -1,3 +1,4 @@
+import { isRecord } from "../run/type-guards.js";
 export function evaluateStopWhen(stopWhen, observation) {
     if (!stopWhen)
         return undefined;
@@ -60,6 +61,3 @@ function valueAtPath(source, path) {
     }
     return current;
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/dist/analysis/automatic-completion.d.ts

@@ -1,13 +1,16 @@
 import { FinishedRun } from "../run/run.js";
 import type { AnalysisConfig } from "./types.js";
-import { runAutomaticStudyAnalysis, type AutomaticAnalysisDeps } from "./automatic.js";
+import type { LabDeps } from "../lab/lab-deps.js";
+import type { LabEvent } from "../lab/run-lab-events.js";
+import { type AutomaticAnalysisDeps } from "./automatic.js";
 import type { AutomaticAnalysisOutcome } from "./job.js";
-export interface AutomaticAnalysisHooks {
-    /** Provider/test dependencies apply only to analysis, never to the participant. */
-    deps?: AutomaticAnalysisDeps;
-    /** Called after the source is finalized; the returned cleanup always runs. */
-    onStart?: () => void | (() => void);
-    run?: typeof runAutomaticStudyAnalysis;
+/** What a route's input gives its analysis: the test's runner and deps, the signal and onEvent. */
+export interface AnalysisInput {
+    readonly deps?: Pick<LabDeps, "analysis">;
+    /** Cancels the analysis only. */
+    readonly analysisSignal?: AbortSignal;
+    /** Receives analysis-started and analysis-finished. */
+    readonly emit?: (event: LabEvent) => void;
 }
 export interface AutomaticAnalysisResult {
     automaticAnalysis?: AutomaticAnalysisOutcome;
@@ -23,11 +26,13 @@ export declare function completeAutomaticAnalysis<T extends {
     cwd: string;
     runId: string;
     dryRun: boolean;
-}>(result: T, finished: FinishedRun | undefined, config: AnalysisConfig | undefined, hooks?: AutomaticAnalysisHooks, { trigger, preferLargerOutput, }?: {
+}>(result: T, finished: FinishedRun | undefined, config: AnalysisConfig | undefined, input: AnalysisInput | undefined, { trigger, preferLargerOutput, refusal, }?: {
     /** "default" when the lab declared no analysis; its missing-key skip is not a failure. */
     trigger?: "default" | "explicit";
     /** The lab omitted an output limit, so a larger one may be used within the admission budget. */
     preferLargerOutput?: boolean;
+    /** The route's reason not to analyze this run; see AutomaticAnalysisDeps.refusal. */
+    refusal?: AutomaticAnalysisDeps["refusal"];
 }): Promise<T & AutomaticAnalysisResult>;
 /**
  * True when an analysis the lab never declared was refused because its conservative estimate is

package/dist/analysis/automatic-completion.js

@@ -1,12 +1,12 @@
 import { physicalCwdOf, validatePreparedRunRootIdentity } from "../run/paths.js";
 import { FinishedRun } from "../run/run.js";
-import { runAutomaticStudyAnalysis } from "./automatic.js";
+import { runAutomaticAnalysis } from "./automatic.js";
 /**
  * One post-completion boundary shared by all live recording producers. `finished` is the token
  * the producer's run scope issued when the run published its final bundle; without it, or when it
  * names another run than the result, there is no source to analyze.
  */
-export async function completeAutomaticAnalysis(result, finished, config, hooks, { trigger = "explicit", preferLargerOutput = false, } = {}) {
+export async function completeAutomaticAnalysis(result, finished, config, input, { trigger = "explicit", preferLargerOutput = false, refusal, } = {}) {
     if (config === undefined)
         return result;
     const origin = trigger === "default" ? { automaticAnalysisTrigger: trigger } : {};
@@ -26,9 +26,12 @@ export async function completeAutomaticAnalysis(result, finished, config, hooks,
         };
     }
     const prepared = finished.paths;
-    let cleanup = undefined;
+    const seams = input?.deps?.analysis;
+    const signal = input?.analysisSignal;
+    let started = false;
     try {
-        cleanup = hooks?.onStart?.();
+        input?.emit?.({ type: "analysis-started" });
+        started = true;
         try {
             await validatePreparedRunRootIdentity(prepared);
         }
@@ -40,8 +43,10 @@ export async function completeAutomaticAnalysis(result, finished, config, hooks,
             };
         }
         const sourceCwd = physicalCwdOf(prepared);
-        const automaticAnalysis = await (hooks?.run ?? runAutomaticStudyAnalysis)(sourceCwd, finished.runId, config, {
-            ...hooks?.deps,
+        const automaticAnalysis = await (seams?.run ?? runAutomaticAnalysis)(sourceCwd, finished.runId, config, {
+            ...seams?.deps,
+            ...(signal === undefined ? {} : { signal }),
+            ...(refusal === undefined ? {} : { refusal }),
             preferLargerOutput,
             ...(trigger === "default" ? { defaultRequest: true } : {}),
             expectedRun: prepared,
@@ -58,10 +63,11 @@ export async function completeAutomaticAnalysis(result, finished, config, hooks,
     }
     finally {
         try {
-            cleanup?.();
+            if (started)
+                input?.emit?.({ type: "analysis-finished" });
         }
         catch {
-            /* Cleanup cannot erase accounting or the completed recording. */
+            /* A report cannot erase accounting or the completed recording. */
         }
     }
 }

package/dist/analysis/automatic-config.d.ts

@@ -19,7 +19,7 @@ export type LabAnalysis = LabAnalysisSettings & ({
 });
 /** The spend cap on an analysis the lab did not declare. */
 export declare const DEFAULT_ANALYSIS_MAX_COST_USD = 3;
-/** Called for parsed manifests AND direct library configs, before participant execution. */
+/** Called for parsed manifests and direct library configs, before participant execution. */
 export declare function resolveAutomaticAnalysis(raw: unknown): {
     ok: true;
     config: AnalysisConfig | undefined;

package/dist/analysis/automatic-config.js

@@ -24,7 +24,7 @@ const SENSITIVE_QUESTION = {
 };
 /** The spend cap on an analysis the lab did not declare. */
 export const DEFAULT_ANALYSIS_MAX_COST_USD = 3;
-/** Called for parsed manifests AND direct library configs, before participant execution. */
+/** Called for parsed manifests and direct library configs, before participant execution. */
 export function resolveAutomaticAnalysis(raw) {
     if (raw === false)
         return { ok: true, config: undefined };
@@ -131,5 +131,5 @@ export function automaticAnalysisBudget(raw, route) {
 export function formatAutomaticAnalysisBudget(budget) {
     if (budget.provider === "codex")
         return `After live runs: Codex account analysis · ${budget.model} · separate restricted analyst with remote inference. Account limits apply; dollar cost and output-token ceiling are unknown. Set review.analysis: false to disable.`;
-    return `After live runs: ${budget.trigger} analysis · ${budget.model} · separate $${budget.maxCostUsd} admission estimate limit (not a provider billing cap). Set review.analysis: false to disable.`;
+    return `After live runs: ${budget.trigger} analysis · ${budget.model} · refused before it starts if its estimate is over $${budget.maxCostUsd}; this is not a billing cap. Set review.analysis: false to disable.`;
 }

package/dist/analysis/automatic.d.ts

@@ -1,17 +1,23 @@
 import { type AnalyzeDeps } from "./service.js";
-import { type AutomaticAnalysisView, type AutomaticAnalysisOutcome, type AutomaticAnalysisCancellation } from "./job.js";
+import { type AutomaticAnalysisView, type AutomaticAnalysisOutcome, type AutomaticAnalysisRefusal, type AutomaticAnalysisCancellation } from "./job.js";
 import { type AnalysisConfig } from "./types.js";
 export type { AutomaticAnalysisView, AutomaticAnalysisOutcome, AutomaticAnalysisCancellation, } from "./job.js";
 export type AutomaticAnalysisDeps = Omit<AnalyzeDeps, "analysisId" | "beforeDispatch"> & {
     /** A missing default key records a skip before admission, preserving a successful recording. */
     defaultRequest?: boolean;
+    /**
+     * A route's reason not to analyze this run, such as a local study whose cleanup is unconfirmed.
+     * It is checked after the job is claimed, so the skip is recorded where the CLI, the TUI and the
+     * Observer read it.
+     */
+    refusal?: () => AutomaticAnalysisRefusal | undefined;
     /** Expand an omitted output limit only within the existing admission budget. */
     preferLargerOutput?: boolean;
 };
 /** Small read-only TUI/CLI projection. Neither this nor Observer can resume a job. */
-export declare function readAutomaticStudyAnalysis(cwd: string, runId: string): Promise<AutomaticAnalysisView | undefined>;
-export declare function requestAutomaticStudyAnalysisCancellation(cwd: string, runId: string): Promise<AutomaticAnalysisCancellation>;
+export declare function readAutomaticAnalysis(cwd: string, runId: string): Promise<AutomaticAnalysisView | undefined>;
+export declare function requestAutomaticAnalysisCancellation(cwd: string, runId: string): Promise<AutomaticAnalysisCancellation>;
 /** One permanent claim per completed run, consumed even when preparation/cancellation fails.
  * Only the original producer calls this after all recording writes return.
  * No file reader, restart recovery, Observer poll or export calls this function. */
-export declare function runAutomaticStudyAnalysis(cwdInput: string, runId: string, configInput: AnalysisConfig, deps?: AutomaticAnalysisDeps): Promise<AutomaticAnalysisOutcome>;
+export declare function runAutomaticAnalysis(cwdInput: string, runId: string, configInput: AnalysisConfig, deps?: AutomaticAnalysisDeps): Promise<AutomaticAnalysisOutcome>;

package/dist/analysis/automatic.js

@@ -5,10 +5,10 @@ import { refreshObserver, analyzeRun, readCompletedAnalysisSource, resolveAnalys
 import { preferLargerAnalysisOutput, ANALYSIS_PROMPT_VERSION } from "./execute.js";
 import { captureEvidence } from "./evidence.js";
 import { hashAnalysisValue } from "./validation.js";
-import { claimAutomaticStudyAnalysis, readAutomaticStudyAnalysisPrepared, requestAutomaticStudyAnalysisCancellationPrepared, } from "./job.js";
+import { claimAutomaticAnalysis, readAutomaticAnalysisPrepared, requestAutomaticAnalysisCancellationPrepared, } from "./job.js";
 import { ANALYSIS_ID_PATTERN } from "./types.js";
-import { readStudyAnalysisVersion } from "./store.js";
-import { readStudyAnalysisExecution } from "./store-executions.js";
+import { readAnalysisVersion } from "./store.js";
+import { readAnalysisExecution } from "./store-executions.js";
 import { physicalCwdOf, resolvePhysicalCwd } from "../run/paths.js";
 const CANCELLATION_POLL_MS = 250;
 // Well inside AUTOMATIC_ANALYSIS_STALE_MS, so a live owner never reads as stale.
@@ -26,18 +26,18 @@ function hasParticipantEvidence(bundle) {
     });
 }
 /** Small read-only TUI/CLI projection. Neither this nor Observer can resume a job. */
-export async function readAutomaticStudyAnalysis(cwd, runId) {
+export async function readAutomaticAnalysis(cwd, runId) {
     if (!exactId(runId))
         return undefined;
     const prepared = await resolveRunPath(await resolvePhysicalCwd(cwd), runId).catch(() => null);
-    return prepared ? readAutomaticStudyAnalysisPrepared(prepared) : undefined;
+    return prepared ? readAutomaticAnalysisPrepared(prepared) : undefined;
 }
-export async function requestAutomaticStudyAnalysisCancellation(cwd, runId) {
+export async function requestAutomaticAnalysisCancellation(cwd, runId) {
     if (!exactId(runId))
         return { requested: false, reason: "AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE" };
     const prepared = await resolveRunPath(await resolvePhysicalCwd(cwd), runId).catch(() => null);
     return prepared
-        ? requestAutomaticStudyAnalysisCancellationPrepared(prepared)
+        ? requestAutomaticAnalysisCancellationPrepared(prepared)
         : { requested: false, reason: "AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE" };
 }
 /** The job reason for an analysis that reached a status. */
@@ -114,8 +114,8 @@ async function persistOutcome(job, prepared, outcome) {
         const analysisId = outcome.result?.analysisId;
         const [entry, receipt] = analysisId
             ? await Promise.all([
-                readStudyAnalysisVersion(prepared, analysisId),
-                readStudyAnalysisExecution(prepared, analysisId),
+                readAnalysisVersion(prepared, analysisId),
+                readAnalysisExecution(prepared, analysisId),
             ])
             : [null, null];
         await job.update({
@@ -131,7 +131,7 @@ async function persistOutcome(job, prepared, outcome) {
                 }),
             ...(entry?.analysis ? { analysisSha256: hashAnalysisValue(entry.analysis) } : {}),
         });
-        const persisted = await readAutomaticStudyAnalysisPrepared(prepared);
+        const persisted = await readAutomaticAnalysisPrepared(prepared);
         return persisted?.state === "unknown"
             ? { ...outcome, state: "unknown", reason: persisted.reason }
             : outcome;
@@ -143,7 +143,7 @@ async function persistOutcome(job, prepared, outcome) {
 /** One permanent claim per completed run, consumed even when preparation/cancellation fails.
  * Only the original producer calls this after all recording writes return.
  * No file reader, restart recovery, Observer poll or export calls this function. */
-export async function runAutomaticStudyAnalysis(cwdInput, runId, configInput, deps = {}) {
+export async function runAutomaticAnalysis(cwdInput, runId, configInput, deps = {}) {
     if (!exactId(runId))
         return skipped("AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE");
     let cwd = path.resolve(cwdInput);
@@ -162,7 +162,7 @@ export async function runAutomaticStudyAnalysis(cwdInput, runId, configInput, de
         config = await (await import("./restricted-codex.js")).bindCodexAnalysisCliVersion(config, deps.detectCodexCliVersion);
     let job;
     try {
-        const claimed = await claimAutomaticStudyAnalysis(prepared, {
+        const claimed = await claimAutomaticAnalysis(prepared, {
             configDigest: hashAnalysisValue(config),
             promptVersion: ANALYSIS_PROMPT_VERSION,
         });
@@ -211,7 +211,11 @@ export async function runAutomaticStudyAnalysis(cwdInput, runId, configInput, de
     try {
         await poll();
         const missingKey = config.provider !== "codex" && !hasKey;
-        if (deps.defaultRequest === true && (missingKey || !participantEvidence)) {
+        const refused = deps.refusal?.();
+        if (refused !== undefined) {
+            outcome = skipped(refused);
+        }
+        else if (deps.defaultRequest === true && (missingKey || !participantEvidence)) {
             outcome = signal.aborted
                 ? { state: "cancelled", reason: "AUTOMATIC_ANALYSIS_CANCELLED" }
                 : skipped(missingKey

package/dist/analysis/diagnostics.d.ts

@@ -0,0 +1,23 @@
+/** How many rejected outputs are kept across all runs; older ones are removed on each write. */
+export declare const MAX_ANALYSIS_DIAGNOSTICS = 20;
+export interface RejectedAnalysisOutput {
+    /** The allowlisted code the analysis artifact records. */
+    error: string;
+    /** Every failed validation rule, when validation ran. */
+    errors: string[];
+    /** The response after the narrative scrub when validation ran, else the parsed response. */
+    output: unknown;
+}
+export interface RejectedAnalysisRecord {
+    runId: string;
+    analysisId: string;
+    model: string;
+    promptVersion: string;
+}
+/** Internal fault-injection seam for tests. */
+export interface AnalysisDiagnosticsHooks {
+    /** Runs after pruning has listed the records and before it removes any. */
+    beforeRemove?: () => Promise<void>;
+}
+/** Write one rejected output and prune to the newest MAX_ANALYSIS_DIAGNOSTICS. Returns its path relative to cwd. */
+export declare function keepRejectedAnalysisOutput(cwd: string, record: RejectedAnalysisRecord, rejected: RejectedAnalysisOutput, hooks?: AnalysisDiagnosticsHooks): Promise<string>;

package/dist/analysis/diagnostics.js

@@ -0,0 +1,112 @@
+import { lstat, readdir, rmdir, unlink } from "node:fs/promises";
+import path from "node:path";
+import { decodeEscapes } from "../evidence/encoded-text.js";
+import { redactText } from "../evidence/redaction.js";
+import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, bindExistingManagedHumanishOutputDirectory, prepareManagedHumanishOutputDirectory, writeContainedOutputFile, } from "../run/contained-output.js";
+import { scrubTransientCommsText, transientCommsEncodedScrub, } from "../run/transient-comms-secrets.js";
+import { ANALYSIS_ID_PATTERN } from "./types.js";
+// A rejected analyst response is kept for diagnosis under .humanish/analysis-diagnostics/<run>/,
+// outside every run directory. Export, verify and the Observer read run directories only, so the
+// file never reaches a bundle, an export or a served page. The analysis artifact itself still
+// records only the allowlisted code.
+const ANALYSIS_DIAGNOSTICS_DIRECTORY = "analysis-diagnostics";
+const ANALYSIS_DIAGNOSTIC_SCHEMA = "humanish.analysis-rejected-output.v1";
+/** How many rejected outputs are kept across all runs; older ones are removed on each write. */
+export const MAX_ANALYSIS_DIAGNOSTICS = 20;
+const REDACTED = "[REDACTED_SECRET]";
+const markers = (text) => text.split(REDACTED).length - 1;
+/**
+ * Scrub every string, key and scalar in the output. The encoded scrub finds a known value written
+ * percent-encoded, escaped or base64-encoded and returns decoded text; a string where it finds
+ * nothing keeps its original spelling, so an escape in a rejected quote stays visible, and still
+ * gets the literal scrub. A number or boolean equal to a known value becomes the marker.
+ */
+function scrubber() {
+    const encoded = transientCommsEncodedScrub();
+    const text = (value) => {
+        const found = encoded(value);
+        return redactText(markers(found) > markers(decodeEscapes(value)) ? found : scrubTransientCommsText(value));
+    };
+    const scrub = (value) => {
+        if (typeof value === "string")
+            return text(value);
+        if (typeof value === "number" || typeof value === "boolean")
+            return text(String(value)) === String(value) ? value : REDACTED;
+        if (Array.isArray(value))
+            return value.map(scrub);
+        if (value !== null && typeof value === "object")
+            return Object.fromEntries(Object.entries(value).map(([key, entry]) => [text(key), scrub(entry)]));
+        return value;
+    };
+    return scrub;
+}
+/** Write one rejected output and prune to the newest MAX_ANALYSIS_DIAGNOSTICS. Returns its path relative to cwd. */
+export async function keepRejectedAnalysisOutput(cwd, record, rejected, hooks = {}) {
+    assertSafeOutputPathSegment(record.runId, "Run id");
+    if (!ANALYSIS_ID_PATTERN.test(record.analysisId))
+        throw new Error("Unsafe analysis id.");
+    const root = await prepareManagedHumanishOutputDirectory(cwd, ANALYSIS_DIAGNOSTICS_DIRECTORY, record.runId);
+    const file = `${record.analysisId}.json`;
+    const document = {
+        schema: ANALYSIS_DIAGNOSTIC_SCHEMA,
+        ...record,
+        recordedAt: new Date().toISOString(),
+        error: rejected.error,
+        errors: rejected.errors,
+        output: scrubber()(rejected.output),
+    };
+    await writeContainedOutputFile(root, file, `${JSON.stringify(document, null, 2)}\n`, "utf8");
+    // A failed prune leaves extra files that the next write removes.
+    await pruneAnalysisDiagnostics(cwd, hooks).catch(() => undefined);
+    return path.join(".humanish", ANALYSIS_DIAGNOSTICS_DIRECTORY, record.runId, file);
+}
+/**
+ * Remove one record, or with no name one emptied run directory, only while the directory is still
+ * the one listed: its path resolves to the same physical directory with the same identity, so a
+ * directory swapped for a symlink after listing is refused. The record must be a regular file.
+ */
+async function removeListed(root, name) {
+    try {
+        await assertPreparedSelectedOutputDirectory(root);
+        if (name === undefined) {
+            await rmdir(root.physicalPath);
+            return;
+        }
+        const file = path.join(root.physicalPath, name);
+        if (!(await lstat(file)).isFile())
+            return;
+        await unlink(file);
+    }
+    catch {
+        // A changed directory, a vanished file or a directory that still holds a file is left alone.
+    }
+}
+async function pruneAnalysisDiagnostics(cwd, hooks) {
+    const parent = await bindExistingManagedHumanishOutputDirectory(cwd, ANALYSIS_DIAGNOSTICS_DIRECTORY);
+    if (!parent)
+        return;
+    const files = [];
+    for (const run of await readdir(parent.physicalPath, { withFileTypes: true })) {
+        if (!run.isDirectory())
+            continue;
+        const root = await bindExistingManagedHumanishOutputDirectory(cwd, ANALYSIS_DIAGNOSTICS_DIRECTORY, run.name);
+        if (!root)
+            continue;
+        for (const entry of await readdir(root.physicalPath, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith(".json"))
+                continue;
+            const modified = (await lstat(path.join(root.physicalPath, entry.name))).mtimeMs;
+            files.push({ root, name: entry.name, modified });
+        }
+    }
+    files.sort((a, b) => b.modified - a.modified ||
+        path.join(b.root.physicalPath, b.name).localeCompare(path.join(a.root.physicalPath, a.name)));
+    const removed = files.slice(MAX_ANALYSIS_DIAGNOSTICS);
+    if (removed.length === 0)
+        return;
+    await hooks.beforeRemove?.();
+    for (const { root, name } of removed)
+        await removeListed(root, name);
+    for (const root of new Set(removed.map((entry) => entry.root)))
+        await removeListed(root);
+}

package/dist/analysis/evidence-sources.js

@@ -3,7 +3,7 @@ import { eventRecordIdOf, recordIdOf, streamParticipantIdOf } from "../run/parti
 import { cuaGoalSource } from "../actors/goal-source.js";
 import { isRecord } from "../run/type-guards.js";
 import { ACTION_CAPTURE_VERSION, } from "./types.js";
-import { decodesToPlainRelativePath, isStudyEvidencePath } from "../run/study-files.js";
+import { decodesToPlainRelativePath, isEvidencePath } from "../run/evidence-files.js";
 // How a run bundle becomes analysis sources: each participant's recorded provenance and assignment,
 // the evidence entries its trace offers, and the order in which entries are admitted under the
 // count and byte budgets. captureEvidence selects from these, and validateAnalysisEvidence
@@ -127,7 +127,7 @@ export function sourceEntries(bundle, stream, captureVersion) {
         const capturePath = isCaptureItem(item, captureVersion) &&
             isRecord(item.screenshotRef) &&
             typeof item.screenshotRef.path === "string" &&
-            isStudyEvidencePath(item.screenshotRef.path)
+            isEvidencePath(item.screenshotRef.path)
             ? item.screenshotRef.path
             : null;
         if (frameIds.has(item.id))

package/dist/analysis/evidence.js

@@ -7,7 +7,7 @@ import { RUN_BUNDLE_FILE } from "../run/bundle.js";
 import { ACTION_CAPTURE_VERSION, } from "./types.js";
 import { digestAnalysisInput, hashAnalysisValue, validateAnalysisInputMetadata, } from "./validation.js";
 import { boundedText, fairShares, hasUnmappedCaptures, participantAssignment, participantSource, sourceEntries, sourceOrder, } from "./evidence-sources.js";
-import { readBoundedStudyFile, readBoundedStudyFileResult } from "../run/study-files.js";
+import { readBoundedFile, readBoundedFileResult } from "../run/evidence-files.js";
 export const EVIDENCE_LIMITS = Object.freeze({
     participants: 16,
     evidence: 800,
@@ -96,7 +96,7 @@ export async function captureEvidence(prepared, bundleBytes, requested = {}) {
     }
     if (bundleBytes.length > limits.sourceBytes)
         throw new Error("ANALYSIS_SOURCE_TOO_LARGE");
-    const current = await readBoundedStudyFile(prepared, RUN_BUNDLE_FILE, limits.sourceBytes);
+    const current = await readBoundedFile(prepared, RUN_BUNDLE_FILE, limits.sourceBytes);
     if (!current || !current.equals(bundleBytes))
         throw new Error("ANALYSIS_SOURCE_CHANGED");
     const bundle = parseSource(prepared, bundleBytes);
@@ -164,7 +164,7 @@ export async function captureEvidence(prepared, bundleBytes, requested = {}) {
     };
     result.inputDigest = digestAnalysisInput(result);
     validateAnalysisInputMetadata(result);
-    const after = await readBoundedStudyFile(prepared, RUN_BUNDLE_FILE, limits.sourceBytes);
+    const after = await readBoundedFile(prepared, RUN_BUNDLE_FILE, limits.sourceBytes);
     if (!after || !after.equals(bundleBytes))
         throw new Error("ANALYSIS_SOURCE_CHANGED");
     return result;
@@ -229,7 +229,7 @@ async function selectCaptures(prepared, packings, sel, omissions) {
             packing.attempts++;
             sel.attemptedReads++;
             const source = sel.captureOrders[index][packing.captureCursor];
-            const result = await readBoundedStudyFileResult(prepared, source.capturePath, allowance);
+            const result = await readBoundedFileResult(prepared, source.capturePath, allowance);
             if (result.state === "limit" &&
                 result.size <= BigInt(limits.imageBytes) &&
                 result.size <= BigInt(limits.totalImageBytes - sel.imageBytes) &&
@@ -458,7 +458,7 @@ export async function validateAnalysisEvidence(prepared, artifact, bundleBytes)
                 throw new Error("ANALYSIS_CAPTURE_REFERENCE_INVALID");
             let hash = checkedCaptures.get(source.capturePath);
             if (hash === undefined) {
-                const bytes = await readBoundedStudyFile(prepared, source.capturePath, EVIDENCE_LIMITS.imageBytes);
+                const bytes = await readBoundedFile(prepared, source.capturePath, EVIDENCE_LIMITS.imageBytes);
                 if (!bytes || screenshotEvidenceError(source.capturePath, bytes) !== null)
                     throw new Error("ANALYSIS_CAPTURE_UNAVAILABLE");
                 checkedImageBytes += bytes.length;
@@ -476,7 +476,7 @@ export async function validateAnalysisEvidence(prepared, artifact, bundleBytes)
             artifact.evidence.length) {
         throw new Error("ANALYSIS_COVERAGE_INCOMPLETE");
     }
-    const current = await readBoundedStudyFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
+    const current = await readBoundedFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
     if (!current?.equals(bundleBytes))
         throw new Error("ANALYSIS_SOURCE_CHANGED");
 }

package/dist/analysis/execute.d.ts

@@ -1,5 +1,6 @@
 import { type AnalysisArtifact, type AnalysisConfig, type AnalysisInput } from "./types.js";
 import { type AnalysisFetch, type AnalysisProvider } from "./provider.js";
+import type { RejectedAnalysisOutput } from "./diagnostics.js";
 export declare const ANALYSIS_PROMPT_VERSION = "study-evidence-6";
 export declare const isSupportedAnalysisModel: (model: string) => boolean;
 /** The OpenAI output limit when a lab omits maxOutputTokens, and the most it may ask for. */
@@ -21,7 +22,7 @@ export interface AnalysisProgress {
     status?: AnalysisArtifact["status"];
 }
 /**
- * Local admission ESTIMATE, not a provider-enforced billed-spend guarantee. No token-count API
+ * Local admission estimate, not a provider-enforced billed-spend guarantee. No token-count API
  * call, credential, or network access. One UTF-8 byte/token for all text/schema plus framing is
  * intentionally conservative. Each high-detail image is priced from its PNG size by the vision
  * guide's patch formula (see image-tokens.ts), or at the 3,000-token ceiling when its size or the
@@ -46,6 +47,11 @@ interface RunAnalysisOptions {
     /** Set by automatic analysis to its job attempt id, claimed before any provider call. */
     analysisId?: string;
     beforeDispatch?: (context: AnalysisDispatchContext) => Promise<void>;
+    /** Receives the provider's run warnings, such as Codex notification methods humanish does not know. */
+    warnings?: string[];
+    /** Receives a completed response that failed validation, for local diagnosis only. The
+     *  artifact still records only the allowlisted code. */
+    onRejectedOutput?: (rejected: RejectedAnalysisOutput) => void;
 }
 /** Explicit invocation or an opted-in post-run owner; Observer readers never call this. */
 export declare function runAnalysis(input: AnalysisInput, config: AnalysisConfig, options: RunAnalysisOptions): Promise<AnalysisArtifact>;