humanish 0.106.1 → 0.108.0

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

@@ -9,12 +9,12 @@
 // The step executor's `page` is typed as the narrow structural ScriptedPageLike instead of
 // playwright's Page (browserPersonaPageState already took { evaluate, url }; E2BDesktopLike is
 // the same seam pattern). playwright's real Page satisfies it; tests inject fakes and run
-// the REAL step executor at $0 with zero browser dependence. playwright-core stays the lazy
+// the real step executor at $0 with zero browser dependence. playwright-core stays the lazy
 // production default behind launchPlaywrightChromium.
 //
-// Spend posture: nothing in this module can spend provider money — no provider client is
+// Spend posture: nothing in this module can spend provider money: no provider client is
 // importable from this code path. tokenUsage on every projected trace records zeros as an
-// affirmative $0 declaration that is TRUE by mechanism.
+// affirmative $0 declaration that is true by mechanism.
 import { stat } from "node:fs/promises";
 import path from "node:path";
 import { CHROMIUM_EVIDENCE_HYGIENE_FLAGS } from "../../evidence/browser-hygiene.js";
@@ -24,7 +24,7 @@ import { ACTOR_TRACE_SCHEMA, SCRIPTED_BROWSER_CAPABILITIES, } from "../contract.
 import { buildBlockedBrowserPersonaSteps, buildBrowserTrace, captureBlockedStepScreenshot, compactBrowserError, executeBrowserPersonaStep, probeAppUrl, sanitizeBrowserEvidenceUrl, screenshotPathForBrowserStep, surfaceScreenshotPath, tracePathForBrowserSurface, } from "./steps.js";
 import { LOOPBACK_EVIDENCE_URL_POLICY, } from "./types.js";
 /** Production default: lazy playwright-core import + chromium.launch, exactly as the driver
- *  always did. Kept in ONE place so the optional peer is touched by exactly one code path. */
+ *  always did. Kept in one place so the optional peer is touched by exactly one code path. */
 async function launchPlaywrightChromium(args) {
     const { chromium } = await import("playwright-core");
     const browser = await chromium.launch({
@@ -50,19 +50,19 @@ class ScriptedJourneyTimeoutError extends Error {
     }
 }
 /**
- * Run the scripted journey for ONE surface and return native capture + ActorTrace projection.
+ * Run the scripted journey for one surface and return native capture + ActorTrace projection.
  *
  * Completion semantics (the contract the projection tests pin):
  * - every step executed, every assertion passed, HTTP probe ok -> passed / goal_satisfied
- *   (the scenario's expect blocks ARE the success predicate; a pass claims "the app still
+ *   (the scenario's expect blocks are the success predicate; a pass claims "the app still
  *   affords this exact journey", nothing about user behavior);
  * - a step's expectation evaluated false, a step target missing/unactionable, or an
- *   unreachable subject -> failed / step_failed (the harness executed faithfully; the SUBJECT
- *   did not satisfy the script — distinct from actor_error/harness_error);
+ *   unreachable subject -> failed / step_failed (the harness executed faithfully; the subject
+ *   did not satisfy the script, distinct from actor_error/harness_error);
  * - journey exceeded timeoutMs -> timed_out / timed_out;
  * - browser launch/import crash -> failed / harness_error;
- * - gave_up / blocked_approval are UNREACHABLE from this actor (no persona patience, no
- *   approvals exist on a deterministic replay) — asserted in tests.
+ * - gave_up / blocked_approval are unreachable from this actor (no persona patience, no
+ *   approvals exist on a deterministic replay), asserted in tests.
  */
 export async function runScriptedBrowserSession(options) {
     assertScriptedSessionPathIds(options);
@@ -107,7 +107,7 @@ export async function runScriptedBrowserSessionInPreparedRoot(options, preparedA
             trace,
         };
     };
-    // Launch FIRST: a browser that cannot start is a harness failure, never subject evidence.
+    // Launch first: a browser that cannot start is a harness failure, never subject evidence.
     let browser;
     try {
         browser = await launch({ browserCommand, timeoutMs: options.timeoutMs });
@@ -289,7 +289,7 @@ async function runScriptedJourney(args) {
     };
 }
 /** Race one step against the journey's remaining wall-clock budget. A hanging step rejects
- *  with the timeout error; the journey's catch path then records honest blocked steps. */
+ *  with the timeout error; the journey's catch path then records the remaining steps as blocked. */
 async function withJourneyDeadline(promise, deadline, timeoutMs) {
     const remaining = deadline - Date.now();
     if (remaining <= 0) {
@@ -353,7 +353,7 @@ async function persistScriptedFailureCapture(args) {
     };
 }
 /** Project one surface capture into humanish.actor-trace.v1. screenshotRefs are attached only
- *  for frames that actually exist on disk (honest counts; blocked-not-executed steps name a
+ *  for frames that actually exist on disk (so counts match disk; blocked-not-executed steps name a
  *  path that was never written). */
 async function projectScriptedActorTrace(args) {
     const writtenScreenshots = new Set();
@@ -371,7 +371,7 @@ async function projectScriptedActorTrace(args) {
     const items = args.capture.steps.map((step) => {
         const assertions = step.assertions ?? [];
         assertionCount += assertions.length;
-        const assertionLines = assertions.map((assertion) => `${assertion.id}: ${assertion.status} — ${assertion.reason}`);
+        const assertionLines = assertions.map((assertion) => `${assertion.id}: ${assertion.status} (${assertion.reason})`);
         return {
             id: step.id,
             kind: "ui_action",
@@ -401,7 +401,7 @@ async function projectScriptedActorTrace(args) {
         status: args.status,
         completionReason: args.completionReason,
         reason: redactText(args.reason),
-        // No session/model ids exist on a deterministic replay — absence declared by omission.
+        // No session/model ids exist on a deterministic replay; absence declared by omission.
         ids: {},
         counts: {
             steps: args.journey.steps.length,
@@ -412,7 +412,7 @@ async function projectScriptedActorTrace(args) {
             screenshots: writtenScreenshots.size,
         },
         items,
-        // Affirmative $0 declaration, TRUE by mechanism: no provider client is importable from
+        // Affirmative $0 declaration, true by mechanism: no provider client is importable from
         // this code path, so zeros are a recorded fact, not an estimate.
         tokenUsage: { input: 0, output: 0, total: 0, costUsd: 0 },
         capabilities: SCRIPTED_BROWSER_CAPABILITIES,

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

@@ -1,5 +1,5 @@
 // Find a Chromium binary on the host for the scripted browser: HUMANISH_BROWSER_COMMAND first, then
-// the macOS Chrome path, then google-chrome, chromium and chromium-browser on PATH. A candidate
+// the macOS Chrome path, then google-chrome, chromium and chromium-browser on `PATH`. A candidate
 // counts only if `--version` runs.
 import { execFile } from "node:child_process";
 import path from "node:path";

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

@@ -1,6 +1,7 @@
 // Parse a scenario's `browser.steps` into a BrowserPersonaJourney: the actions, text assertions and
 // expectations the scripted browser runs. The journey is the actor's whole behavior.
 import path from "node:path";
+import { isRecord } from "../../run/type-guards.js";
 export function parseBrowserPersonaJourneyFromScenario(args) {
     if (!isRecord(args.raw)) {
         return {};
@@ -86,7 +87,16 @@ function parseBrowserPersonaStep(rawStep, index) {
     const selector = stringValue(source.selector);
     const pathValue = stringValue(source.path);
     const value = stringValue(source.value);
+    const key = stringValue(source.key);
     const expectation = browserStepExpectationValue(source.expect ?? source.expectation);
+    if (action === "press" && !key) {
+        return { failure: `${id} press action requires key (for example Enter).` };
+    }
+    if (action !== "press" && "key" in source) {
+        return {
+            failure: `${id} sets key, which only a press step sends. Supported actions: ${SUPPORTED_ACTIONS}.`,
+        };
+    }
     if (action === "fill" && !selector) {
         return { failure: `${id} fill action requires selector.` };
     }
@@ -105,12 +115,14 @@ function parseBrowserPersonaStep(rawStep, index) {
             ...(pathValue === undefined ? {} : { path: pathValue }),
             ...(selector === undefined ? {} : { selector }),
             ...(value === undefined ? {} : { value }),
+            ...(key === undefined ? {} : { key }),
         },
     };
 }
 function hasInlineBrowserSteps(value) {
     return Array.isArray(value) && value.some((entry) => isRecord(entry) && isRecord(entry.browser));
 }
+const SUPPORTED_ACTIONS = "goto, fill, click, press, assertText, waitForText, waitForSelector";
 function browserPersonaActionValue(value) {
     if (typeof value !== "string") {
         return null;
@@ -121,8 +133,10 @@ function browserPersonaActionValue(value) {
         .replace(/[-_\s]+/g, "");
     if (normalized === "goto" || normalized === "open" || normalized === "navigate")
         return "goto";
-    if (normalized === "click" || normalized === "press")
+    if (normalized === "click")
         return "click";
+    if (normalized === "press")
+        return "press";
     if (normalized === "fill" || normalized === "type")
         return "fill";
     if (normalized === "asserttext" || normalized === "expecttext")
@@ -152,9 +166,6 @@ function browserStepExpectationValue(value) {
     };
     return Object.keys(expectation).length === 0 ? undefined : expectation;
 }
-function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
 function stringValue(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }

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) {
@@ -158,7 +176,7 @@ async function waitForPageText(page, expectedText, timeoutMs) {
 }
 export function buildBlockedBrowserPersonaSteps(args) {
     // The journey never ran, so no screenshot was written for these steps. The
-    // failure IS the evidence: keep the blocked status + reason, but omit the
+    // failure is the evidence: keep the blocked status + reason, but omit the
     // screenshot reference so the bundle never claims an artifact that does not
     // exist (otherwise verify's missingLocalEvidenceArtifacts fails closed on
     // evidence that was never meant to exist).

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;
@@ -100,7 +108,7 @@ export interface BrowserPersonaStepCapture {
     /**
      * Path to the step screenshot the producer actually wrote. Omitted for blocked
      * steps where the failure itself is the recorded evidence and no screenshot was
-     * written — the bundle must not reference an artifact that does not exist. A step that
+     * written: the bundle must not reference an artifact that does not exist. A step that
      * ran and attempted a screenshot keeps this even when its assertions failed, so a broken
      * producer still fails verify.
      */
@@ -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.d.ts

@@ -14,7 +14,7 @@ export interface StopWhen {
     any: StopWhenRule[];
 }
 /**
- * A declared observation window (#510): once `when` matches (or at the start, when `when` is
+ * A declared observation window: once `when` matches (or at the start, when `when` is
  * absent), the harness holds the page for `ms`, captures a frame every `everyMs`, takes no action
  * and requests no model turn, then hands control back to the participant (`then: continue`) or
  * ends the session (`then: stop`). Bounded by the session budget: a window that would outlast it

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/codex-config.d.ts

@@ -2,7 +2,11 @@ import type { CodexAnalysisIdentity, AnalysisConfig } from "./types.js";
 export declare const CODEX_ANALYSIS_MODEL: "gpt-6-astra";
 /** Before dispatch, analysis replaces the default release with the detected one. */
 export declare function codexAnalysisIdentity(model: string, cliVersion?: string): CodexAnalysisIdentity;
-/** Execution admission: the identity must name a release qualified on this host. */
+/** Execution admission: an isolated-mode host, and an identity naming a release the launcher starts. */
 export declare function validCodexAnalysisConfig(config: AnalysisConfig, platform?: NodeJS.Platform, arch?: string): boolean;
-/** Reading historical artifacts never inserts defaults or selects a launch policy. */
+/**
+ * Reading historical artifacts never inserts defaults or selects a launch policy: the restricted
+ * analyst's fixed identity, from any recordable release, so a change to launch admission never
+ * invalidates a saved report.
+ */
 export declare function validStoredCodexAnalysisConfig(config: AnalysisConfig): boolean;

package/dist/analysis/codex-config.js

@@ -1,7 +1,7 @@
-import { RECORDED_CODEX_CLI_VERSIONS } from "../actors/contract.js";
-import { defaultCodexCliVersion, qualifiedCodexCliVersions, } from "../actors/codex/qualified-versions.js";
+import { isRecordedCodexCliVersion } from "../actors/contract.js";
+import { admitsCodexCliVersion, defaultCodexCliVersion, supportsIsolatedCodex, } from "../actors/codex/codex-admission.js";
 import { RESTRICTED_CODEX_ANALYSIS_IDENTITY, RESTRICTED_CODEX_ANALYSIS_MODELS, } from "../actors/codex/restricted-policy.js";
-/** This account route is qualified against per-host CLI releases, one model and one tool policy. */
+/** This account route runs the releases codex-admission.ts admits, one model and one tool policy. */
 const CODEX_ANALYSIS_TOOL_POLICY = RESTRICTED_CODEX_ANALYSIS_IDENTITY.toolPolicy;
 export const CODEX_ANALYSIS_MODEL = RESTRICTED_CODEX_ANALYSIS_MODELS[0];
 const CODEX_ANALYSIS_EFFORT = RESTRICTED_CODEX_ANALYSIS_IDENTITY.reasoningEffort;
@@ -26,13 +26,6 @@ export function codexAnalysisIdentity(model, cliVersion = defaultCodexCliVersion
         cliVersion,
     });
 }
-/** Reader profiles are append-only. A new launch qualification must not invalidate a saved report. */
-const storedProfiles = RECORDED_CODEX_CLI_VERSIONS.map((cliVersion) => ({
-    cliVersion,
-    toolPolicy: "restricted-codex-v1",
-    model: "gpt-6-astra",
-    reasoningEffort: "low",
-}));
 function matchesProfile(config, expected) {
     if (config.provider !== "codex")
         return false;
@@ -54,16 +47,31 @@ function matchesProfile(config, expected) {
         Object.keys(config.identity).length === Object.keys(expected).length &&
         Object.entries(expected).every(([key, value]) => config.identity[key] === value));
 }
-/** Execution admission: the identity must name a release qualified on this host. */
+/** Execution admission: an isolated-mode host, and an identity naming a release the launcher starts. */
 export function validCodexAnalysisConfig(config, platform = process.platform, arch = process.arch) {
     if (config.provider !== "codex")
         return false;
     const cliVersion = config.identity?.cliVersion;
     return (config.model === CODEX_ANALYSIS_MODEL &&
-        qualifiedCodexCliVersions(platform, arch).some((version) => version === cliVersion) &&
+        supportsIsolatedCodex(platform, arch) &&
+        typeof cliVersion === "string" &&
+        admitsCodexCliVersion(cliVersion) &&
         matchesProfile(config, codexAnalysisIdentity(config.model, cliVersion)));
 }
-/** Reading historical artifacts never inserts defaults or selects a launch policy. */
+/**
+ * Reading historical artifacts never inserts defaults or selects a launch policy: the restricted
+ * analyst's fixed identity, from any recordable release, so a change to launch admission never
+ * invalidates a saved report.
+ */
 export function validStoredCodexAnalysisConfig(config) {
-    return storedProfiles.some((profile) => matchesProfile(config, identityFor(profile)));
+    if (config.provider !== "codex")
+        return false;
+    const cliVersion = config.identity?.cliVersion;
+    return (isRecordedCodexCliVersion(cliVersion) &&
+        matchesProfile(config, identityFor({
+            cliVersion,
+            toolPolicy: "restricted-codex-v1",
+            model: "gpt-6-astra",
+            reasoningEffort: "low",
+        })));
 }

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>;