humanish 0.111.2 → 0.111.4

package/dist/routes/terminal/trace.js

@@ -4,50 +4,45 @@ import { TAIL_CHARS } from "./types.js";
 /**
  * Per-chunk sanitization cannot recognize a value split across deliveries. Redact those complete
  * known values before persistence without collapsing events or changing stdout/stderr ordering.
- * Work backwards through matches so edits to later text leave earlier offsets valid.
+ * `spansOf` finds them in the joined text: RunSecrets.spans, which also finds a value in an
+ * encoded form or split by a terminal escape sequence. Work backwards through the spans so edits
+ * to later text leave earlier offsets valid.
  */
-export function scrubSplitKnownValues(events, knownValues, discardedPrefixes) {
+export function scrubSplitKnownValues(events, spansOf, discardedPrefixes) {
     for (const order of ["stdout", "stderr", "combined"]) {
         const chunks = order === "combined" ? [...events] : events.filter((event) => event.stream === order);
         // A virtual final chunk makes a key crossing the capture cap recognizable. Edits to retained
         // events redact evidence; the raw overlap and this virtual chunk are never persisted.
         if (discardedPrefixes[order])
             chunks.push({ chunk: discardedPrefixes[order] });
-        for (const value of knownValues) {
-            if (!value)
+        let offset = 0;
+        const starts = chunks.map((event) => {
+            const start = offset;
+            offset += event.chunk.length;
+            return start;
+        });
+        const text = chunks.map((event) => event.chunk).join("");
+        for (const [at, end] of [...spansOf(text)].reverse()) {
+            let first = 0;
+            while (first + 1 < starts.length && (starts[first + 1] ?? Infinity) <= at)
+                first += 1;
+            let last = first;
+            while (last + 1 < starts.length && (starts[last + 1] ?? Infinity) < end)
+                last += 1;
+            const firstChunk = chunks[first];
+            const lastChunk = chunks[last];
+            if (!firstChunk || !lastChunk)
                 continue;
-            let offset = 0;
-            const starts = chunks.map((event) => {
-                const start = offset;
-                offset += event.chunk.length;
-                return start;
-            });
-            const text = chunks.map((event) => event.chunk).join("");
-            const matches = [];
-            for (let at = text.indexOf(value); at !== -1; at = text.indexOf(value, at + value.length))
-                matches.push(at);
-            for (const at of matches.reverse()) {
-                let first = 0;
-                while (first + 1 < starts.length && (starts[first + 1] ?? Infinity) <= at)
-                    first += 1;
-                let last = first;
-                while (last + 1 < starts.length && (starts[last + 1] ?? Infinity) < at + value.length)
-                    last += 1;
-                const firstChunk = chunks[first];
-                const lastChunk = chunks[last];
-                if (!firstChunk || !lastChunk)
-                    continue;
-                const before = firstChunk.chunk.slice(0, at - (starts[first] ?? 0));
-                const after = lastChunk.chunk.slice(at + value.length - (starts[last] ?? 0));
-                firstChunk.chunk = `${before}[REDACTED_SECRET]${first === last ? after : ""}`;
-                for (let index = first + 1; index < last; index += 1) {
-                    const middle = chunks[index];
-                    if (middle)
-                        middle.chunk = "";
-                }
-                if (first !== last)
-                    lastChunk.chunk = after;
+            const before = firstChunk.chunk.slice(0, at - (starts[first] ?? 0));
+            const after = lastChunk.chunk.slice(end - (starts[last] ?? 0));
+            firstChunk.chunk = `${before}[REDACTED_SECRET]${first === last ? after : ""}`;
+            for (let index = first + 1; index < last; index += 1) {
+                const middle = chunks[index];
+                if (middle)
+                    middle.chunk = "";
             }
+            if (first !== last)
+                lastChunk.chunk = after;
         }
     }
 }

package/dist/routes/terminal/types.d.ts

@@ -8,7 +8,7 @@ import type { TerminalPlan } from "../../study/plan-types.js";
 import type { StudyDeps } from "../../study/study-deps.js";
 import type { ObserverResult } from "../../observer/render.js";
 import { type RunAdapterScore, type RunBundle, type RunFeedbackCandidate, type RunScorerProvenance } from "../../run/bundle.js";
-import { type StudyResultIdentity } from "../../run/study-result.js";
+import { type StudyResultErrorCode, type StudyResultIdentity } from "../../run/study-result.js";
 /** Provider-neutral metadata constant: the route's non-secret tag (mirrors CUA_ACTOR_STUDY_PROVIDER_METADATA). */
 export declare const TERMINAL_PRODUCT_STUDY_PROVIDER_METADATA: {
     readonly mode: "terminal-product-lab";
@@ -172,7 +172,7 @@ export interface TerminalProductStudyResult extends AutomaticAnalysisResult, Stu
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_TERMINAL_FAILED" | "HUMANISH_TERMINAL_ACTOR_UNSUPPORTED" | "HUMANISH_TERMINAL_SUBJECT_INVALID" | "HUMANISH_TERMINAL_KEYPLACEMENT_INVALID" | "HUMANISH_TERMINAL_RUNTIME_AUTH_MISSING" | "HUMANISH_TERMINAL_KEYS_MISSING" | "HUMANISH_TERMINAL_CAPS_MISSING" | "HUMANISH_TERMINAL_CAPS_INVALID" | "HUMANISH_TERMINAL_UNPRICED_CAP" | "HUMANISH_TERMINAL_CAPS_EXCEEDED" | "HUMANISH_TERMINAL_CREDENTIAL_DENIED" | "HUMANISH_TERMINAL_CLEANUP_UNPROVEN" | "HUMANISH_RUN_ID_IN_USE";
+        code: StudyResultErrorCode | "HUMANISH_TERMINAL_FAILED" | "HUMANISH_TERMINAL_ACTOR_UNSUPPORTED" | "HUMANISH_TERMINAL_SUBJECT_INVALID" | "HUMANISH_TERMINAL_KEYPLACEMENT_INVALID" | "HUMANISH_TERMINAL_RUNTIME_AUTH_MISSING" | "HUMANISH_TERMINAL_KEYS_MISSING" | "HUMANISH_TERMINAL_CAPS_MISSING" | "HUMANISH_TERMINAL_CAPS_INVALID" | "HUMANISH_TERMINAL_UNPRICED_CAP" | "HUMANISH_TERMINAL_CAPS_EXCEEDED" | "HUMANISH_TERMINAL_CREDENTIAL_DENIED" | "HUMANISH_TERMINAL_CLEANUP_UNPROVEN";
         message: string;
     };
 }

package/dist/run/run.d.ts

@@ -2,6 +2,7 @@ import { renderObserver, type ObserverResult } from "../observer/render.js";
 import { type RunBundle } from "./bundle.js";
 import { type ExecutionFailure, type ExecutionOutcome, type OutcomePolicy } from "./judge.js";
 import { type PreparedRunArtifactPaths, type RunIdInUse } from "./paths.js";
+import { RunSecrets } from "./secrets.js";
 import type { RunStudyProvenance } from "./study-provenance.js";
 interface StartRunOptions {
     /** Project directory, in the form the route resolved it. */
@@ -24,6 +25,41 @@ interface StartRunOptions {
     now?: (() => number) | undefined;
     /** Warnings about the study's own fields. Every bundle write records each as a warn event. */
     warnings?: readonly string[] | undefined;
+    /** The route's known values, created before the run so a refusal before it is scrubbed too. */
+    secrets?: RunSecrets | undefined;
+}
+/** The prefix of the run ids each recorded route mints. Preview mints its own `dryrun-` ids. */
+type RunIdPrefix = "cua" | "concurrent-shared-world" | "scripted" | "terminal";
+/** What a recorded route's plan holds for its run's start. */
+interface StartRunPlan {
+    readonly dryRun: boolean;
+    readonly study?: RunStudyProvenance | undefined;
+    readonly warnings?: readonly string[] | undefined;
+}
+/** What a recorded route's input holds for its run's start. */
+interface StartRunInput {
+    /** Caller-supplied id (`--run-id`, library `runId`); one is minted from the prefix when absent. */
+    readonly runId?: string | undefined;
+    /** Open the Observer page once it renders. */
+    readonly open?: boolean | undefined;
+    /** `renderObserver` is the seam FinishedRun.renderObserver calls. */
+    readonly deps?: {
+        readonly renderObserver?: typeof renderObserver | undefined;
+    } | undefined;
+}
+/** What a recorded route passes to startRun besides its plan and input. */
+interface RouteRunOptions {
+    /** Project directory, in the form the route resolved it. */
+    cwd: string;
+    prefix: RunIdPrefix;
+    /** review.md for the published bundle. */
+    renderReview: (bundle: RunBundle) => string;
+    /** `none` when the route creates no sandbox for this run; status.json records it for reclaim. */
+    sandboxes?: "none" | undefined;
+    /** Clock for `createdAt` and the latest pointer. The minted id reads the wall clock. */
+    now?: (() => number) | undefined;
+    /** The route's known values, created before the run so a refusal before it is scrubbed too. */
+    secrets?: RunSecrets | undefined;
 }
 /** How a run ended as an execution, as run.json records it: the result's ok and execution outcome. */
 interface RecordedOutcome {
@@ -46,6 +82,8 @@ interface Run {
     readonly study?: RunStudyProvenance;
     /** Routes write their evidence files through these and hand them to participants. */
     readonly paths: PreparedRunArtifactPaths;
+    /** The literal values the route scrubs from this run's evidence; a value found later is added here. */
+    readonly secrets: RunSecrets;
     /**
      * Publish an in-progress bundle: run.json, review.json, review.md, events.ndjson and
      * observer/observer-data.json, plus the latest pointer until one pointer write has succeeded,
@@ -74,11 +112,27 @@ interface Run {
      */
     finish(bundle: RunBundle, outcome: FinishOutcome): Promise<FinishedRun>;
 }
+/** A recorded route's run, with the source its bundle records. */
+interface RecordedRun extends Run {
+    /** The package and the project's git state, captured once the run exists, at its createdAt. */
+    readonly source: RunBundle["source"];
+}
 export interface RunScope {
+    /**
+     * Start a recorded route's run from its plan and input: the input's run id or one minted from
+     * `prefix`, the plan's mode, study and warnings, and an Observer that opens when the input says
+     * `open` and renders through the input's `deps.renderObserver`. Then capture the run's source.
+     * The run starts as the form below does.
+     */
+    startRun(plan: StartRunPlan, input: StartRunInput, options: RouteRunOptions): Promise<{
+        ok: true;
+        run: RecordedRun;
+    } | RunIdInUse>;
     /**
      * Create `.humanish/runs/<id>` exclusively, begin status.json and wait for its first write, so
      * a run that got past this point has a status record before any sandbox exists. An id whose
-     * directory exists is refused before any write. A scope starts at most one run.
+     * directory exists is refused before any write. A scope starts at most one run. Preview calls
+     * this form, since it builds its source before the run and mints its own id.
      */
     startRun(options: StartRunOptions): Promise<{
         ok: true;

package/dist/run/run.js

@@ -2,16 +2,18 @@
 // token that lets the Observer and automatic analysis read it. Routes build bundles and write
 // their own evidence files; this module owns when the run starts, how it is published, and how it
 // is closed on every exit.
+import { randomBytes } from "node:crypto";
 import { redactText } from "../evidence/redaction.js";
 import { buildObserverData } from "../observer/data.js";
 import { renderObserver } from "../observer/render.js";
-import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD, } from "./bundle.js";
+import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD, buildRunSource, } from "./bundle.js";
 import { judgeExecution, } from "./judge.js";
 import {} from "./results.js";
 import { createRunArtifactPaths, validatePreparedRunArtifactPaths, } from "./paths.js";
 import { registerActiveRun } from "./active-runs.js";
 import { writeContainedOutputFile, writePreparedRunLatestPointer } from "./contained-output.js";
 import { scrubRunSandboxIds, withPublicSandboxIds } from "./sandbox-ids.js";
+import { RunSecrets } from "./secrets.js";
 import { beginRunStatus, runStatusOutcome, } from "./status.js";
 /** An entry point called in a state that does not admit it. */
 class RunLifecycleError extends Error {
@@ -239,7 +241,7 @@ export async function runScope(fn) {
         return operation;
     };
     const refuse = (message) => Promise.reject(new RunLifecycleError(message));
-    const startRun = (options) => {
+    const startRunWith = (options) => {
         if (closed)
             return refuse("The run scope has closed.");
         if (started)
@@ -277,6 +279,9 @@ export async function runScope(fn) {
             return { ok: true, run: run.run };
         })());
     };
+    function startRun(...args) {
+        return args.length === 1 ? startRunWith(args[0]) : startRecordedRun(startRunWith, ...args);
+    }
     const openRun = (options, runId, paths, runStatus) => {
         const now = options.now ?? Date.now;
         const createdAt = new Date(now()).toISOString();
@@ -301,6 +306,7 @@ export async function runScope(fn) {
             mode: options.mode,
             ...(options.study === undefined ? {} : { study: options.study }),
             paths,
+            secrets: options.secrets ?? new RunSecrets([]),
             participantStarted() {
                 participantsRan = true;
             },
@@ -348,3 +354,33 @@ export async function runScope(fn) {
     }
     return { result: outcome.result, finished };
 }
+/** Start a recorded route's run through `start`, the scope's own form, then capture its source. */
+async function startRecordedRun(start, plan, input, route) {
+    const started = await start({
+        cwd: route.cwd,
+        runId: input.runId,
+        mintRunId: () => mintRunId(route.prefix),
+        mode: plan.dryRun ? "dry-run" : "live",
+        study: plan.study,
+        warnings: plan.warnings,
+        sandboxes: route.sandboxes,
+        renderReview: route.renderReview,
+        observer: { open: input.open === true, render: input.deps?.renderObserver },
+        now: route.now,
+        secrets: route.secrets,
+    });
+    if (!started.ok)
+        return started;
+    const source = await buildRunSource({
+        cwd: route.cwd,
+        capturedAt: started.run.createdAt,
+        humanishSource: "present",
+        packageName: "humanish",
+    });
+    return { ok: true, run: { ...started.run, source } };
+}
+/** `<prefix>-<wall-clock time, with : and . as ->-<8 hex>`. */
+function mintRunId(prefix) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return `${prefix}-${stamp}-${randomBytes(4).toString("hex")}`;
+}

package/dist/run/secrets.d.ts

@@ -0,0 +1,35 @@
+/** Each route's seed list, marker and floor are its own; the defaults are what most routes use. */
+interface RunSecretsOptions {
+    /** The text that replaces each value. */
+    readonly marker?: string;
+    /** The shortest value scrubbed. A shorter value is ordinary text often enough to leave alone. */
+    readonly minLength?: number;
+}
+export declare class RunSecrets {
+    #private;
+    /**
+     * Replaces every held value with the marker, as written, in each encoded form, and where a URL
+     * carries it partly percent-encoded or a terminal escape sequence splits it. It reads the values
+     * on each call, so a value added after the scrub was handed to a participant or a subject is
+     * scrubbed from then on.
+     */
+    readonly scrub: (text: string) => string;
+    /** `seed` keeps its order; values shorter than the floor are dropped. */
+    constructor(seed: readonly string[], options?: RunSecretsOptions);
+    /** Holds each value the run learns while it runs, unless it is under the floor or already held. */
+    add(values: readonly string[]): void;
+    /** The held values, seed first, in one array that later `add` calls extend. */
+    values(): readonly string[];
+    /**
+     * Every held value as written and in each encoded form, longest first, in one array that later
+     * `add` calls extend. The terminal recorder sizes the output it keeps past its cap from these.
+     */
+    forms(): readonly string[];
+    /**
+     * Where `text` holds a held value: each encoded form as written, and each form in the text's
+     * view without terminal escape sequences and with percent escapes decoded. Sorted, with
+     * overlapping spans merged. A scrub that replaces across chunk boundaries reads these.
+     */
+    spans(text: string): Array<[number, number]>;
+}
+export {};

package/dist/run/secrets.js

@@ -0,0 +1,158 @@
+// The literal values one run scrubs from what it writes: the provider keys and subject env values
+// its route reads, and the values the run provisions while it runs, such as the addresses email
+// receiving registers. These have no secret shape for pattern redaction to find, so each is
+// replaced as written and in the encoded forms a URL, a JSON body or a log line gives it;
+// redactText runs after the scrub and finds secrets by shape.
+import { scrubLiterals } from "../evidence/redaction.js";
+import { encodedForms } from "../evidence/secret-scrub.js";
+export class RunSecrets {
+    // Private fields stay out of JSON.stringify and object spread, so a Run that reaches a writer
+    // whole cannot carry the values with it.
+    #held = [];
+    /** Every held value as written and encoded, longest first. */
+    #forms = [];
+    #minLength;
+    /**
+     * Replaces every held value with the marker, as written, in each encoded form, and where a URL
+     * carries it partly percent-encoded or a terminal escape sequence splits it. It reads the values
+     * on each call, so a value added after the scrub was handed to a participant or a subject is
+     * scrubbed from then on.
+     */
+    scrub;
+    /** `seed` keeps its order; values shorter than the floor are dropped. */
+    constructor(seed, options = {}) {
+        // An empty value would match between every character.
+        this.#minLength = Math.max(1, options.minLength ?? 4);
+        this.add(seed);
+        const marker = options.marker ?? "[REDACTED_SECRET]";
+        // Longest first, so a form that holds a shorter one, such as a JSON-escaped value ending in a
+        // backslash, is replaced whole and leaves no stray escape behind.
+        const literal = scrubLiterals(this.#forms, marker);
+        this.scrub = (text) => {
+            const scrubbed = literal(text);
+            return replaceSpans(scrubbed, viewSpans(scrubbed, this.#forms), marker);
+        };
+    }
+    /** Holds each value the run learns while it runs, unless it is under the floor or already held. */
+    add(values) {
+        for (const value of values) {
+            if (value.length < this.#minLength || this.#held.includes(value))
+                continue;
+            this.#held.push(value);
+            for (const form of encodedForms(value))
+                if (!this.#forms.includes(form))
+                    this.#forms.push(form);
+        }
+        this.#forms.sort((left, right) => right.length - left.length);
+    }
+    /** The held values, seed first, in one array that later `add` calls extend. */
+    values() {
+        return this.#held;
+    }
+    /**
+     * Every held value as written and in each encoded form, longest first, in one array that later
+     * `add` calls extend. The terminal recorder sizes the output it keeps past its cap from these.
+     */
+    forms() {
+        return this.#forms;
+    }
+    /**
+     * Where `text` holds a held value: each encoded form as written, and each form in the text's
+     * view without terminal escape sequences and with percent escapes decoded. Sorted, with
+     * overlapping spans merged. A scrub that replaces across chunk boundaries reads these.
+     */
+    spans(text) {
+        const found = viewSpans(text, this.#forms);
+        for (const form of this.#forms)
+            for (let at = text.indexOf(form); at !== -1; at = text.indexOf(form, at + form.length))
+                found.push([at, at + form.length]);
+        return mergeSpans(found);
+    }
+}
+// What a terminal draws with (operating-system commands, control sequences and two-byte escapes,
+// as written or JSON-escaped, as a JSON event carries a command's colored output) and what a URL
+// encodes with (runs of percent escapes). The view a value is looked for in drops the first and
+// decodes the second.
+const VIEW_SEQUENCE = new RegExp([
+    "\\x1b\\][^\\x07]*(?:\\x07|\\x1b\\\\)",
+    "\\x1b\\[[0-?]*[ -/]*[@-~]",
+    "\\x1b[78=>]",
+    "\\\\u001b\\][^\\\\]*(?:\\\\u0007|\\\\u001b\\\\\\\\)",
+    "\\\\u001b\\[[0-?]*[ -/]*[@-~]",
+    "(?:%[0-9A-Fa-f]{2})+",
+].join("|"), "g");
+/**
+ * Where a value is found in the text's view. A browser encodes a space or a quote in a URL path
+ * and leaves a `/` or a `:` as written, so a value with both matches no single encoded form, and a
+ * color code inside a value splits it. Each found value maps back to the span of `text` it came
+ * from, so the text keeps every other character as written.
+ */
+function viewSpans(text, values) {
+    if (!text.includes("%") && !text.includes("\x1b") && !text.includes("\\u001b"))
+        return [];
+    // The view, and for each of its characters the span of `text` it came from. A character decoded
+    // from an escape run maps to the whole run.
+    let view = "";
+    const starts = [];
+    const ends = [];
+    const copy = (from, to) => {
+        for (let at = from; at < to; at += 1) {
+            starts.push(at);
+            ends.push(at + 1);
+        }
+        view += text.slice(from, to);
+    };
+    let cursor = 0;
+    let changed = false;
+    for (const sequence of text.matchAll(VIEW_SEQUENCE)) {
+        let plain = "";
+        if (sequence[0].startsWith("%")) {
+            try {
+                plain = decodeURIComponent(sequence[0]);
+            }
+            catch {
+                // Not UTF-8: the run stays as written and is copied with the text after it.
+                continue;
+            }
+        }
+        copy(cursor, sequence.index);
+        cursor = sequence.index + sequence[0].length;
+        for (let unit = 0; unit < plain.length; unit += 1) {
+            starts.push(sequence.index);
+            ends.push(cursor);
+        }
+        view += plain;
+        changed = true;
+    }
+    if (!changed)
+        return [];
+    copy(cursor, text.length);
+    const spans = [];
+    for (const value of values)
+        for (let at = view.indexOf(value); at !== -1; at = view.indexOf(value, at + value.length))
+            spans.push([starts[at] ?? 0, ends[at + value.length - 1] ?? text.length]);
+    return spans;
+}
+/** Sorted, with overlapping spans merged; spans that only touch stay apart. */
+function mergeSpans(spans) {
+    const merged = [];
+    for (const [from, to] of [...spans].sort((left, right) => left[0] - right[0])) {
+        const last = merged.at(-1);
+        if (last !== undefined && from < last[1])
+            last[1] = Math.max(last[1], to);
+        else
+            merged.push([from, to]);
+    }
+    return merged;
+}
+function replaceSpans(text, spans, marker) {
+    if (spans.length === 0)
+        return text;
+    let replaced = "";
+    let written = 0;
+    for (const [from, to] of mergeSpans(spans)) {
+        replaced += `${text.slice(written, from)}${marker}`;
+        written = to;
+    }
+    return `${replaced}${text.slice(written)}`;
+}

package/dist/run/study-result.d.ts

@@ -7,5 +7,39 @@ export interface StudyResultIdentity<R extends string> {
     /** The study's `id`. */
     studyId: string;
 }
+/**
+ * The error codes every recorded route's result can carry besides its own: a study, option or
+ * analysis refusal from before the route's checks, and a run id that is already taken. Each route's
+ * error-code union is this set plus the codes named for that route.
+ */
+export type StudyResultErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_RUN_ID_IN_USE";
 /** The identity fields for a result of route `route` from the study `studyId`. */
 export declare function studyResultIdentity<R extends string>(route: R, studyId: string): StudyResultIdentity<R>;
+/** What every refused study's result carries besides its identity and its route's own fields. */
+export interface RefusalBase<C extends string> {
+    /** The study's `id`. */
+    studyId: string;
+    cwd: string;
+    /** The caller's warnings array, kept by reference so warnings added later still show. Empty when omitted. */
+    warnings?: string[];
+    error: {
+        code: C;
+        message: string;
+    };
+}
+/**
+ * A refused study's result on route `route`: its identity, `ok: false` and `cwd`, then `fields`
+ * in the caller's order, then `warnings` and `error`. A result is written as JSON, so the key order
+ * is part of the output; a site whose order differs spreads its remaining fields after this. The
+ * caller keeps runId, actor, dryRun and the route's fields, whose values and order differ by site.
+ */
+export declare function refusedResult<R extends string, C extends string, F extends object>(route: R, base: RefusalBase<C>, fields: F): StudyResultIdentity<R> & {
+    ok: false;
+    cwd: string;
+} & F & {
+    warnings: string[];
+    error: {
+        code: C;
+        message: string;
+    };
+};

package/dist/run/study-result.js

@@ -7,3 +7,19 @@ export const STUDY_RESULT_SCHEMA = "humanish.study-result.v1";
 export function studyResultIdentity(route, studyId) {
     return { schema: STUDY_RESULT_SCHEMA, route, studyId };
 }
+/**
+ * A refused study's result on route `route`: its identity, `ok: false` and `cwd`, then `fields`
+ * in the caller's order, then `warnings` and `error`. A result is written as JSON, so the key order
+ * is part of the output; a site whose order differs spreads its remaining fields after this. The
+ * caller keeps runId, actor, dryRun and the route's fields, whose values and order differ by site.
+ */
+export function refusedResult(route, base, fields) {
+    return {
+        ...studyResultIdentity(route, base.studyId),
+        ok: false,
+        cwd: base.cwd,
+        ...fields,
+        warnings: base.warnings ?? [],
+        error: base.error,
+    };
+}

package/dist/study/requirements.d.ts

@@ -1,8 +1,5 @@
-import type { StudyPlan, Requirement } from "./plan-types.js";
-/** The `key` requirements whose value `env` lacks, OPENAI_API_KEY before E2B_API_KEY. */
-export declare function missingKeys(requirements: readonly Requirement[], env: Record<string, string | undefined>): string[];
-/** The subject env names the requirements list and `env` lacks, in declaration order. */
-export declare function missingSubjectEnv(requirements: readonly Requirement[], env: Record<string, string | undefined>): string[];
+import { type LocalAgentRefusal } from "../actors/local-agent/readiness.js";
+import type { Brain, StudyPlan, Requirement } from "./plan-types.js";
 /**
  * The provider keys the requirements name, in plan order. A `key-one-of` names the first of its
  * keys that `isPresent` reports, else OPENAI_API_KEY.
@@ -18,3 +15,61 @@ export declare function requiredSubjectEnv(requirements: readonly Requirement[])
  * a declared scorer's host code, are not in the plan.
  */
 export declare function keyNamesOf(plan: StudyPlan): ReadonlySet<string>;
+/** A live check's refusal, in its route's error code. */
+export interface LiveRefusal<C extends string> {
+    readonly code: C;
+    readonly message: string;
+}
+/** One live check: its refusal, or undefined when this machine passes it. */
+export type LiveCheck<C extends string> = () => LiveRefusal<C> | undefined | Promise<LiveRefusal<C> | undefined>;
+/**
+ * The first refusal of `checks`, run one at a time in the order given. Which check comes first
+ * decides which error a run with two problems reports, so each route keeps its own order.
+ */
+export declare function firstLiveRefusal<C extends string>(checks: readonly LiveCheck<C>[]): Promise<LiveRefusal<C> | undefined>;
+/**
+ * Refuses a run whose environment lacks a provider key the requirements list. `need` writes the
+ * route's sentence for the missing names ("OPENAI_API_KEY and E2B_API_KEY"); the message goes on
+ * to say where discovery looked and what fills each key. With `suggestLocalAgent`, a missing
+ * OPENAI_API_KEY also names each coding agent signed in on this machine: someone new meets this
+ * refusal first, and an agent they already use runs the participants without a key.
+ */
+export declare function keysCheck<C extends string>(args: {
+    readonly requirements: readonly Requirement[];
+    readonly env: Record<string, string | undefined>;
+    readonly code: C;
+    readonly need: (names: string) => string;
+    readonly suggestLocalAgent?: boolean;
+}): Promise<LiveRefusal<C> | undefined>;
+/**
+ * Refuses a local-agent brain whose CLI is missing, signed out, too old, or cannot honor the
+ * caps, before any sandbox is paid for. `codes` names the route's code for each kind of refusal.
+ */
+export declare function localAgentCheck<C extends string>(args: {
+    readonly brain: Brain;
+    readonly env: Record<string, string | undefined>;
+    readonly caps: {
+        readonly maxUsd?: number;
+        readonly maxTotalUsd?: number;
+    };
+    readonly codes: Readonly<Record<LocalAgentRefusal["kind"], C>>;
+}): Promise<LiveRefusal<C> | undefined>;
+/** Refuses a run whose environment lacks a subject env name the requirements list. */
+export declare function subjectEnvCheck<C extends string>(args: {
+    readonly requirements: readonly Requirement[];
+    readonly env: Record<string, string | undefined>;
+    readonly code: C;
+}): LiveRefusal<C> | undefined;
+/**
+ * Refuses a maxUsd or maxTotalUsd cap on a model with no rate in src/run/pricing.ts. The loop
+ * could not measure spend against the cap, and running uncapped would drop the protection the
+ * cap promised; the operator picks a priced model or removes the cap.
+ */
+export declare function unpricedCapCheck<C extends string>(args: {
+    readonly caps: {
+        readonly maxUsd?: number;
+        readonly maxTotalUsd?: number;
+    };
+    readonly model: string;
+    readonly code: C;
+}): LiveRefusal<C> | undefined;