humanish 0.106.1 → 0.108.0

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

package/dist/analysis/execute.js

@@ -8,6 +8,8 @@ import { ANALYSIS_ID_PATTERN, ANALYSIS_SCHEMA, } from "./types.js";
 import { INPUT_IMAGE_DATA_URL, createAnalysisProvider, } from "./provider.js";
 import { checkAnalysisResult, hashAnalysisValue, analysisResponseSchema, analysisResultJsonSchema, validateAnalysisInputMetadata, } from "./validation.js";
 import { EVIDENCE_LIMITS } from "./evidence.js";
+import { truncatedFrameWarning, unknownNotificationsWarning, } from "../actors/codex/restricted-notifications.js";
+import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.js";
 export const ANALYSIS_PROMPT_VERSION = "study-evidence-6";
 const SUPPORTED_ANALYSIS_MODELS = Object.freeze([
     "gpt-6-astra",
@@ -119,7 +121,7 @@ function inputError(input) {
     return null;
 }
 /**
- * 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
@@ -296,26 +298,33 @@ const VALIDATION_FAILURES = Object.freeze({
 function checkProviderAnalysis(input, value) {
     try {
         const parsed = analysisResponseSchema.safeParse(value);
-        if (!parsed.success)
-            return { ok: false, error: VALIDATION_FAILURES.ANALYSIS_RESULT_SCHEMA_INVALID };
+        if (!parsed.success) {
+            const error = VALIDATION_FAILURES.ANALYSIS_RESULT_SCHEMA_INVALID;
+            return { ok: false, error, rejected: { error, errors: [], output: value } };
+        }
         let scrubbed;
         try {
             scrubbed = scrubGeneratedNarrative(parsed.data);
         }
         catch (error) {
+            if (!(error instanceof Error && error.message === "ANALYSIS_TRANSIENT_SECRET_IN_STRUCTURE"))
+                return { ok: false, error: "analysis_validation_failed_unexpected" };
+            const rejected = "analysis_validation_failed_scrub_rejected";
             return {
                 ok: false,
-                error: error instanceof Error && error.message === "ANALYSIS_TRANSIENT_SECRET_IN_STRUCTURE"
-                    ? "analysis_validation_failed_scrub_rejected"
-                    : "analysis_validation_failed_unexpected",
+                error: rejected,
+                rejected: { error: rejected, errors: [], output: value },
             };
         }
         const checked = checkAnalysisResult(input, scrubbed);
-        if (!checked.ok)
+        if (!checked.ok) {
+            const error = VALIDATION_FAILURES[checked.errors[0] ?? ""] ?? "analysis_validation_failed_unexpected";
             return {
                 ok: false,
-                error: VALIDATION_FAILURES[checked.errors[0] ?? ""] ?? "analysis_validation_failed_unexpected",
+                error,
+                rejected: { error, errors: [...checked.errors], output: scrubbed },
             };
+        }
         return checked;
     }
     catch {
@@ -403,14 +412,21 @@ function recordProviderUsage(artifact, config, response) {
 /**
  * Settle a completed response. Parse the bounded shape first, then scrub and validate again.
  * Changed exact quotes or expanded field lengths fail closed under the original validator; source
- * bytes stay intact. Only an allowlisted stage or first rule code survives; rejected output and
- * exceptions do not.
+ * bytes stay intact. Only an allowlisted stage or first rule code reaches the artifact; rejected
+ * output goes to the caller's diagnostic callback and exceptions go nowhere.
  */
-function settleCompletedOutput(artifact, input, config, admission, response) {
+function settleCompletedOutput(artifact, input, config, admission, response, onRejectedOutput) {
     const checked = checkProviderAnalysis(input, response.output);
     if (!checked.ok) {
         artifact.result = null;
         artifact.error = checked.error;
+        if (checked.rejected)
+            try {
+                onRejectedOutput?.(checked.rejected);
+            }
+            catch {
+                /* Diagnosis does not own the attempt's outcome. */
+            }
         return;
     }
     artifact.result = checked.result;
@@ -493,12 +509,23 @@ export async function runAnalysis(input, config, options) {
         ...(options.signal === undefined ? {} : { signal: options.signal }),
     });
     recordProviderUsage(artifact, config, response);
+    if (config.provider === "codex")
+        for (const warning of [
+            response.protocolIncompatibilities === undefined
+                ? undefined
+                : protocolIncompatibilityMessage(config.identity.cliVersion, response.protocolIncompatibilities),
+            protocolAdditionsWarning(config.identity.cliVersion, response.protocolAdditions),
+            unknownNotificationsWarning(response.unknownNotifications, config.identity.cliVersion),
+            truncatedFrameWarning(response.truncatedFrameBytes),
+        ])
+            if (warning !== undefined)
+                options.warnings?.push(warning);
     if (response.status !== "completed") {
         artifact.status = response.status === "cancelled" ? "cancelled" : "failed";
         artifact.error = `analysis_${response.errorCode ?? "provider_failed"}`;
         return finish();
     }
     progress("validating");
-    settleCompletedOutput(artifact, input, config, admission, response);
+    settleCompletedOutput(artifact, input, config, admission, response, options.onRejectedOutput);
     return finish();
 }

package/dist/analysis/job.d.ts

@@ -21,6 +21,8 @@ export interface AutomaticAnalysisCancellation {
     requested: boolean;
     reason: string | null;
 }
+/** A route's reason not to analyze a run it recorded, persisted as the job's skip reason. */
+export type AutomaticAnalysisRefusal = "AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED";
 declare const jobSchema: z.ZodObject<{
     schema: z.ZodLiteral<"humanish.automatic-study-analysis.v1">;
     runId: z.ZodString;
@@ -45,6 +47,7 @@ declare const jobSchema: z.ZodObject<{
         AUTOMATIC_ANALYSIS_BUSY: "AUTOMATIC_ANALYSIS_BUSY";
         AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE: "AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE";
         AUTOMATIC_ANALYSIS_CANCELLED: "AUTOMATIC_ANALYSIS_CANCELLED";
+        AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED: "AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED";
         AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE: "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE";
         AUTOMATIC_ANALYSIS_FAILED: "AUTOMATIC_ANALYSIS_FAILED";
         AUTOMATIC_ANALYSIS_KEY_MISSING: "AUTOMATIC_ANALYSIS_KEY_MISSING";
@@ -69,9 +72,9 @@ declare const jobSchema: z.ZodObject<{
 }, z.core.$strict>;
 type JobRecord = z.infer<typeof jobSchema>;
 /** Also guards direct HTML projection callers, not only the contained-file reader. */
-export declare function projectAutomaticStudyAnalysisView(value: unknown): AutomaticAnalysisView | undefined;
+export declare function projectAutomaticAnalysisView(value: unknown): AutomaticAnalysisView | undefined;
 /** Minimal historical accounting, without source validation, execution or liveness inference. */
-export declare function readAutomaticStudyAnalysisAccounting(prepared: PreparedRunArtifactPaths): Promise<{
+export declare function readAutomaticAnalysisAccounting(prepared: PreparedRunArtifactPaths): Promise<{
     attemptId: string;
     analysisId: string | null;
     started: boolean;
@@ -79,7 +82,7 @@ export declare function readAutomaticStudyAnalysisAccounting(prepared: PreparedR
     uncertain: boolean;
 } | "unknown" | undefined>;
 /** Read-only projection. A stale timestamp or persisted claim never authorizes execution. */
-export declare function readAutomaticStudyAnalysisPrepared(prepared: PreparedRunArtifactPaths, now?: number): Promise<AutomaticAnalysisView | undefined>;
+export declare function readAutomaticAnalysisPrepared(prepared: PreparedRunArtifactPaths, now?: number): Promise<AutomaticAnalysisView | undefined>;
 export interface AutomaticAnalysisJob {
     readonly attemptId: string;
     /** Serialized, awaited durability boundary. A failed write must prevent dispatch. */
@@ -88,10 +91,10 @@ export interface AutomaticAnalysisJob {
     cancellationRequested(): Promise<boolean>;
 }
 /** The directory is permanent, including after interrupted/failed writes. Never re-open it as a writer. */
-export declare function claimAutomaticStudyAnalysis(prepared: PreparedRunArtifactPaths, metadata: {
+export declare function claimAutomaticAnalysis(prepared: PreparedRunArtifactPaths, metadata: {
     configDigest: string;
     promptVersion: string;
 }): Promise<AutomaticAnalysisJob | null>;
 /** A scoped cancellation request, never a PID signal and never permission to create a new job. */
-export declare function requestAutomaticStudyAnalysisCancellationPrepared(prepared: PreparedRunArtifactPaths): Promise<AutomaticAnalysisCancellation>;
+export declare function requestAutomaticAnalysisCancellationPrepared(prepared: PreparedRunArtifactPaths): Promise<AutomaticAnalysisCancellation>;
 export {};

package/dist/analysis/job.js

@@ -4,10 +4,10 @@ import path from "node:path";
 import { z } from "zod";
 import { physicalCwdOf, runIdOf, validatePreparedRunRootIdentity, } from "../run/paths.js";
 import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, prepareContainedOutputDirectoryRoot, writeContainedOutputFile, } from "../run/contained-output.js";
-import { pathMissing, readBoundedStudyFile } from "../run/study-files.js";
+import { pathMissing, readBoundedFile } from "../run/evidence-files.js";
 import { containsSensitive } from "../evidence/redaction.js";
-import { readStudyAnalysisVersion } from "./store.js";
-import { readStudyAnalysisExecution } from "./store-executions.js";
+import { readAnalysisVersion } from "./store.js";
+import { readAnalysisExecution } from "./store-executions.js";
 import { hashAnalysisValue } from "./validation.js";
 import { ANALYSIS_ID_PATTERN, SHA256_HEX_PATTERN } from "./types.js";
 export const AUTOMATIC_ANALYSIS_DIRECTORY = "analysis-automatic";
@@ -47,6 +47,7 @@ const reasons = [
     "AUTOMATIC_ANALYSIS_ADMISSION_EXCEEDED",
     "AUTOMATIC_ANALYSIS_ACTOR_CANCELLED",
     "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE",
+    "AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED",
 ];
 const id = z.string().regex(ANALYSIS_ID_PATTERN);
 const date = z.iso.datetime();
@@ -106,7 +107,7 @@ function parseJob(bytes, runId) {
     return record;
 }
 /** Also guards direct HTML projection callers, not only the contained-file reader. */
-export function projectAutomaticStudyAnalysisView(value) {
+export function projectAutomaticAnalysisView(value) {
     if (value === undefined)
         return undefined;
     const parsed = jobSchema
@@ -123,12 +124,12 @@ async function bindJob(prepared) {
     return root ? Object.freeze({ ...root, parentRun: prepared }) : null;
 }
 /** Minimal historical accounting, without source validation, execution or liveness inference. */
-export async function readAutomaticStudyAnalysisAccounting(prepared) {
+export async function readAutomaticAnalysisAccounting(prepared) {
     try {
         const root = await bindJob(prepared);
         if (!root)
             return undefined;
-        const bytes = await readBoundedStudyFile(root, JOB_FILE, MAX_JOB_BYTES);
+        const bytes = await readBoundedFile(root, JOB_FILE, MAX_JOB_BYTES);
         if (!bytes)
             return "unknown";
         const record = parseJob(bytes, runIdOf(prepared));
@@ -145,14 +146,14 @@ export async function readAutomaticStudyAnalysisAccounting(prepared) {
     }
 }
 /** Read-only projection. A stale timestamp or persisted claim never authorizes execution. */
-export async function readAutomaticStudyAnalysisPrepared(prepared, now = Date.now()) {
+export async function readAutomaticAnalysisPrepared(prepared, now = Date.now()) {
     try {
         const root = await bindJob(prepared);
         if (!root) {
             const missing = await pathMissing(path.join(prepared.physicalRunRoot, AUTOMATIC_ANALYSIS_DIRECTORY));
             return missing ? undefined : unknown();
         }
-        const bytes = await readBoundedStudyFile(root, JOB_FILE, MAX_JOB_BYTES);
+        const bytes = await readBoundedFile(root, JOB_FILE, MAX_JOB_BYTES);
         if (!bytes)
             return unknown();
         const record = parseJob(bytes, runIdOf(prepared));
@@ -185,7 +186,7 @@ async function terminalResultMatches(prepared, record) {
         value.inputDigest === record.inputDigest &&
         value.configDigest === record.configDigest &&
         value.promptVersion === record.promptVersion;
-    const receipt = await readStudyAnalysisExecution(prepared, record.analysisId);
+    const receipt = await readAnalysisExecution(prepared, record.analysisId);
     if (!receipt || !matches(receipt) || hashAnalysisValue(receipt) !== record.receiptSha256)
         return false;
     if (record.state === "failed" && record.reason === "AUTOMATIC_ANALYSIS_PUBLICATION_FAILED")
@@ -194,7 +195,7 @@ async function terminalResultMatches(prepared, record) {
         return false;
     if (record.state === "failed" || record.state === "cancelled")
         return true;
-    const entry = await readStudyAnalysisVersion(prepared, record.analysisId);
+    const entry = await readAnalysisVersion(prepared, record.analysisId);
     return (entry?.state === "ready" &&
         entry.analysis !== null &&
         matches(entry.analysis) &&
@@ -202,7 +203,7 @@ async function terminalResultMatches(prepared, record) {
         hashAnalysisValue(entry.analysis) === record.analysisSha256);
 }
 /** The directory is permanent, including after interrupted/failed writes. Never re-open it as a writer. */
-export async function claimAutomaticStudyAnalysis(prepared, metadata) {
+export async function claimAutomaticAnalysis(prepared, metadata) {
     await validatePreparedRunRootIdentity(prepared);
     const target = path.join(prepared.physicalRunRoot, AUTOMATIC_ANALYSIS_DIRECTORY);
     try {
@@ -271,7 +272,7 @@ export async function claimAutomaticStudyAnalysis(prepared, metadata) {
         touch: () => update({}),
         async cancellationRequested() {
             await assertPreparedSelectedOutputDirectory(root);
-            const bytes = await readBoundedStudyFile(root, CANCEL_FILE, MAX_CANCEL_BYTES);
+            const bytes = await readBoundedFile(root, CANCEL_FILE, MAX_CANCEL_BYTES);
             if (!bytes) {
                 if (!(await pathMissing(path.join(root.physicalPath, CANCEL_FILE))))
                     throw new Error("AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE");
@@ -285,12 +286,12 @@ export async function claimAutomaticStudyAnalysis(prepared, metadata) {
     };
 }
 /** A scoped cancellation request, never a PID signal and never permission to create a new job. */
-export async function requestAutomaticStudyAnalysisCancellationPrepared(prepared) {
+export async function requestAutomaticAnalysisCancellationPrepared(prepared) {
     try {
         const root = await bindJob(prepared);
         if (!root)
             return { requested: false, reason: "AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE" };
-        const bytes = await readBoundedStudyFile(root, JOB_FILE, MAX_JOB_BYTES);
+        const bytes = await readBoundedFile(root, JOB_FILE, MAX_JOB_BYTES);
         if (!bytes)
             throw new Error("Unavailable job.");
         const record = parseJob(bytes, runIdOf(prepared));

package/dist/analysis/load.d.ts

@@ -1,3 +1,3 @@
 import type { PreparedRunArtifactPaths } from "../run/paths.js";
 import type { LoadedAnalysis } from "./types.js";
-export declare function loadStudyAnalysis(prepared: PreparedRunArtifactPaths, id?: string): Promise<LoadedAnalysis>;
+export declare function loadAnalysis(prepared: PreparedRunArtifactPaths, id?: string): Promise<LoadedAnalysis>;

package/dist/analysis/load.js

@@ -1,11 +1,11 @@
 // Loads a run's study analysis together with the automatic analysis job's view of it. The store
 // and the job module each stay importable without the other.
-import { readAutomaticStudyAnalysisPrepared } from "./job.js";
-import { loadStudyAnalysisRecord } from "./store.js";
-export async function loadStudyAnalysis(prepared, id) {
+import { readAutomaticAnalysisPrepared } from "./job.js";
+import { loadAnalysisRecord } from "./store.js";
+export async function loadAnalysis(prepared, id) {
     const [loaded, automatic] = await Promise.all([
-        loadStudyAnalysisRecord(prepared, id),
-        readAutomaticStudyAnalysisPrepared(prepared),
+        loadAnalysisRecord(prepared, id),
+        readAutomaticAnalysisPrepared(prepared),
     ]);
     return automatic === undefined ? loaded : { ...loaded, automatic };
 }

package/dist/analysis/provider.d.ts

@@ -28,8 +28,16 @@ export interface AnalysisProviderResult {
     dispatched: boolean;
     /** Omitted preserves complete API-response accounting; account snapshots must state this. */
     usageComplete?: boolean;
-    errorCode: "invalid_request" | "provider_http_error" | "provider_network_error" | "invalid_response" | "provider_headers_timeout" | "provider_body_timeout" | "provider_connect_timeout" | "provider_connection_reset" | "provider_dns_error" | "codex_busy" | "codex_unavailable" | "codex_unsupported_version" | "codex_unsupported_platform" | "codex_login_required" | "codex_unsupported_auth" | "codex_unsafe_configuration" | "codex_model_unavailable" | "codex_protocol_error" | "codex_tool_call" | "codex_process_failed" | "codex_cleanup_failed" | "response_too_large" | "output_incomplete" | "refusal" | "cancelled" | "timeout" | null;
+    errorCode: "invalid_request" | "provider_http_error" | "provider_network_error" | "invalid_response" | "provider_headers_timeout" | "provider_body_timeout" | "provider_connect_timeout" | "provider_connection_reset" | "provider_dns_error" | "codex_busy" | "codex_unavailable" | "codex_unsupported_version" | "codex_incompatible_release" | "codex_unsupported_platform" | "codex_login_required" | "codex_unsupported_auth" | "codex_unsafe_configuration" | "codex_model_unavailable" | "codex_protocol_error" | "codex_tool_call" | "codex_process_failed" | "codex_cleanup_failed" | "response_too_large" | "output_incomplete" | "refusal" | "cancelled" | "timeout" | null;
     httpStatus?: number;
+    /** Codex only: notification methods humanish does not know that carried no item, by count. */
+    unknownNotifications?: Readonly<Record<string, number>>;
+    /** Codex only: bytes of a last frame cut off when humanish stopped the app-server. */
+    truncatedFrameBytes?: number;
+    /** Codex only: how the release's app-server schema differs from the fields humanish reads. */
+    protocolIncompatibilities?: readonly string[];
+    /** Codex only: schema values beyond the baseline humanish knows. */
+    protocolAdditions?: readonly string[];
 }
 export type AnalysisProvider = (request: AnalysisProviderRequest) => Promise<AnalysisProviderResult>;
 /** An input image the provider accepts; the groups are the image type and its base64 bytes. */

package/dist/analysis/restricted-codex.d.ts

@@ -16,4 +16,6 @@ export declare function checkRestrictedCodexAnalysisReadiness(input?: {
 }, options?: RestrictedCodexSessionOptions): Promise<{
     ready: boolean;
     errorCode: RestrictedCodexAnalysisErrorCode | null;
+    protocolIncompatibilities?: readonly string[];
+    protocolAdditions?: readonly string[];
 }>;

package/dist/analysis/restricted-codex.js

@@ -19,5 +19,14 @@ export async function bindCodexAnalysisCliVersion(config, detect = async () => (
 /** Does not submit a model turn. Readiness is not a quota/access guarantee. */
 export async function checkRestrictedCodexAnalysisReadiness(input = {}, options = {}) {
     const result = await checkRestrictedCodexSessionReadiness(input, options);
-    return { ready: result.status === "completed", errorCode: result.errorCode };
+    return {
+        ready: result.status === "completed",
+        errorCode: result.errorCode,
+        ...(result.protocolIncompatibilities === undefined
+            ? {}
+            : { protocolIncompatibilities: result.protocolIncompatibilities }),
+        ...(result.protocolAdditions === undefined
+            ? {}
+            : { protocolAdditions: result.protocolAdditions }),
+    };
 }

package/dist/analysis/service.d.ts

@@ -19,6 +19,8 @@ export interface AnalyzeResult {
     analysisId?: string;
     artifactPath?: string;
     executionReceiptPath?: string;
+    /** A rejected response kept for local diagnosis, outside the run directory. */
+    rejectedOutputPath?: string;
     status?: AnalysisArtifact["status"];
     usage?: AnalysisArtifact["usage"];
     admission?: AnalysisAdmission;