humanish 0.106.1 → 0.108.0

package/dist/analysis/service.js

@@ -1,4 +1,4 @@
-import { describeQualifiedCodexCliVersions } from "../actors/codex/qualified-versions.js";
+import { defaultCodexCliVersion, describeCodexCliAdmission, } from "../actors/codex/codex-admission.js";
 import { validCodexAnalysisConfig } from "./codex-config.js";
 import { randomUUID } from "node:crypto";
 import { lstat, mkdir, realpath, rmdir } from "node:fs/promises";
@@ -10,11 +10,12 @@ import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
 import { physicalCwdOf, runIdOf, resolvePhysicalCwd, validatePreparedRunRootIdentity, } from "../run/paths.js";
 import { isRunStatusRecord, RUN_STATUS_FILE } from "../run/status.js";
 import { captureEvidence, EVIDENCE_LIMITS } from "./evidence.js";
-import { pathMissing, readBoundedStudyFile } from "../run/study-files.js";
+import { pathMissing, readBoundedFile } from "../run/evidence-files.js";
 import { estimateAnalysisAdmission, preferLargerAnalysisOutput, runAnalysis, ANALYSIS_PROMPT_VERSION, } from "./execute.js";
-import { appendStudyAnalysisCorrection, assertAnalysisPublicationCapacity, listAnalyses, writeStudyAnalysis, } from "./store.js";
-import { beginStudyAnalysisExecution, writeStudyAnalysisExecutionReceipt, } from "./store-executions.js";
-import { loadStudyAnalysis } from "./load.js";
+import { appendAnalysisCorrection, assertAnalysisPublicationCapacity, listAnalyses, writeAnalysis, } from "./store.js";
+import { beginAnalysisExecution, writeAnalysisExecutionReceipt } from "./store-executions.js";
+import { keepRejectedAnalysisOutput } from "./diagnostics.js";
+import { loadAnalysis } from "./load.js";
 import { hashAnalysisValue } from "./validation.js";
 import { ANALYSIS_CORRECTION_SCHEMA, } from "./types.js";
 import { RUN_BUNDLE_FILE } from "../run/bundle.js";
@@ -42,7 +43,7 @@ const messages = {
     ANALYSIS_VERIFY_FAILED: "The run must pass verification before analysis.",
     ANALYSIS_RUN_ACTIVE: "Analysis requires a completed recording. Wait for the study to finish.",
     ANALYSIS_NO_PARTICIPANTS: "This run contains no participant evidence to analyze.",
-    ANALYSIS_REQUIRES_LIVE_RUN: "A dry-run proves harness contracts, not participant behavior. Select a completed live study for analysis.",
+    ANALYSIS_REQUIRES_LIVE_RUN: "A dry run has no participant behavior to analyze. Select a completed live run.",
     ANALYSIS_SOURCE_UNAVAILABLE: "The source recording is missing, unsafe, or exceeds the input limit.",
     ANALYSIS_SOURCE_CHANGED: "The source recording changed during analysis. The result cannot be published against different evidence.",
     ANALYSIS_BUSY: "Another analysis holds this run's .analysis-lock directory. If it was interrupted, confirm it has stopped before removing that empty directory.",
@@ -55,8 +56,9 @@ const messages = {
 };
 const codexRecovery = {
     analysis_codex_busy: "Another restricted Codex analyst or setup check is active in this process. Wait for it to finish, then explicitly retry.",
-    analysis_codex_unavailable: `The qualified Codex CLI is unavailable. Install a qualified Codex CLI (${describeQualifiedCodexCliVersions()}) and sign in with a ChatGPT account, then retry --provider codex.`,
-    analysis_codex_unsupported_version: `Codex account analysis requires a qualified CLI version (${describeQualifiedCodexCliVersions()}). Other versions have not passed this tool-policy contract.`,
+    analysis_codex_unavailable: `The Codex CLI is unavailable. Install one (${describeCodexCliAdmission()}) and sign in with a ChatGPT account, then retry --provider codex.`,
+    analysis_codex_unsupported_version: `This Codex CLI release is refused: ${describeCodexCliAdmission()}. \`humanish doctor\` names the release it found, why, and the command that replaces it.`,
+    analysis_codex_incompatible_release: `This Codex CLI release changed app-server protocol fields humanish reads, so no request was sent; the warnings name each change. Install the last tested release (${defaultCodexCliVersion()}), then retry.`,
     analysis_codex_unsupported_platform: "This platform has not qualified the restricted Codex account launcher.",
     analysis_codex_login_required: "Sign in to Codex with a ChatGPT account, then retry humanish analyze --provider codex --rerun.",
     analysis_codex_unsupported_auth: "Codex analysis requires ChatGPT account authentication; API-key and custom provider authentication are not used as fallbacks.",
@@ -140,7 +142,7 @@ export async function withAnalysisLock(prepared, action) {
 }
 /** The completion gate: the run verifies, is live and finished, and has participants. */
 export async function readCompletedAnalysisSource(cwd, prepared) {
-    const bytes = await readBoundedStudyFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
+    const bytes = await readBoundedFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
     if (!bytes)
         throw new Error("ANALYSIS_SOURCE_UNAVAILABLE");
     const verified = await verifyRunPrepared(cwd, runIdOf(prepared), prepared);
@@ -151,7 +153,7 @@ export async function readCompletedAnalysisSource(cwd, prepared) {
         throw new Error("ANALYSIS_NO_PARTICIPANTS");
     if (loaded.bundle.mode !== "live")
         throw new Error("ANALYSIS_REQUIRES_LIVE_RUN");
-    const statusBytes = await readBoundedStudyFile(prepared, RUN_STATUS_FILE, MAX_STATUS_BYTES);
+    const statusBytes = await readBoundedFile(prepared, RUN_STATUS_FILE, MAX_STATUS_BYTES);
     if (!statusBytes) {
         const missing = await pathMissing(path.join(prepared.physicalRunRoot, RUN_STATUS_FILE)).catch(() => {
             throw new Error("ANALYSIS_SOURCE_UNAVAILABLE");
@@ -258,9 +260,9 @@ async function publishAttempt(prepared, analysis, result, finalizeExecution) {
         if (finalizeExecution)
             await finalizeExecution(analysis);
         else
-            await writeStudyAnalysisExecutionReceipt(prepared, analysis);
+            await writeAnalysisExecutionReceipt(prepared, analysis);
         result.executionReceiptPath = path.join(prepared.relativeRunRoot, "analysis-attempts", analysis.id, "receipt.json");
-        await writeStudyAnalysis(prepared, analysis);
+        await writeAnalysis(prepared, analysis);
         result.artifactPath = path.join(prepared.relativeRunRoot, "analysis", analysis.id, "analysis.json");
         return true;
     }
@@ -308,19 +310,36 @@ async function executeAnalysis(attempt) {
     if (config.provider !== "codex" && !apiKey.trim())
         return { ...fail(input.runId, false, "ANALYSIS_API_KEY_MISSING"), admission };
     let finalizeExecution;
+    const rejection = {};
     const analysis = await runAnalysis(input, config, {
         apiKey,
         ...(deps.codexProvider === undefined ? {} : { codexProvider: deps.codexProvider }),
         ...(deps.analysisId === undefined ? {} : { analysisId: deps.analysisId }),
         beforeDispatch: async (context) => {
             await deps.beforeDispatch?.(context);
-            finalizeExecution = await beginStudyAnalysisExecution(prepared, context);
+            finalizeExecution = await beginAnalysisExecution(prepared, context);
         },
         ...(deps.signal === undefined ? {} : { signal: deps.signal }),
         ...(deps.onProgress === undefined ? {} : { onProgress: deps.onProgress }),
         ...(deps.fetch === undefined ? {} : { fetch: deps.fetch }),
+        warnings: base.warnings,
+        onRejectedOutput: (output) => {
+            rejection.output = output;
+        },
     });
     const result = attemptResult(base, analysis);
+    if (rejection.output)
+        try {
+            result.rejectedOutputPath = await keepRejectedAnalysisOutput(cwd, {
+                runId: analysis.runId,
+                analysisId: analysis.id,
+                model: config.model,
+                promptVersion: analysis.promptVersion,
+            }, rejection.output);
+        }
+        catch {
+            result.warnings.push("The rejected analyst output could not be kept under .humanish/analysis-diagnostics.");
+        }
     if (!(await publishAttempt(prepared, analysis, result, finalizeExecution)))
         return {
             ...result,
@@ -365,7 +384,7 @@ export async function analyzeRun(cwdInput, run, options, deps = {}) {
 export async function showAnalysis(cwd, run, id) {
     const prepared = await resolveRunPath(await resolvePhysicalCwd(cwd), run).catch(() => null);
     return prepared
-        ? loadStudyAnalysis(prepared, id)
+        ? loadAnalysis(prepared, id)
         : { state: "invalid", analysis: null, corrections: [], warnings: ["ANALYSIS_RUN_NOT_FOUND"] };
 }
 export async function correctAnalysis(cwd, run, options) {
@@ -373,7 +392,7 @@ export async function correctAnalysis(cwd, run, options) {
     if (!prepared)
         throw new Error("ANALYSIS_RUN_NOT_FOUND");
     return withAnalysisLock(prepared, async () => {
-        const loaded = await loadStudyAnalysis(prepared, options.analysisId);
+        const loaded = await loadAnalysis(prepared, options.analysisId);
         const analysis = loaded.analysis;
         const finding = analysis?.result?.findings.find((item) => item.id === options.findingId);
         if (loaded.state !== "ready" || !analysis || !finding)
@@ -392,7 +411,7 @@ export async function correctAnalysis(cwd, run, options) {
             reason: options.reason,
             replacementClaim: options.replacementClaim ?? null,
         };
-        await appendStudyAnalysisCorrection(prepared, correction);
+        await appendAnalysisCorrection(prepared, correction);
         await refreshObserver(cwd, runIdOf(prepared), prepared);
         return correction;
     });

package/dist/analysis/sharing.d.ts

@@ -1,9 +1,9 @@
 import type { LoadedAnalysis } from "./types.js";
 /** True for the analysis record files, matched by name inside their directories. Any other file
  * under analysis/ is ordinary evidence and follows the ordinary evidence policy. */
-export declare function isStudyAnalysisRecordPath(relativePath: string): boolean;
+export declare function isAnalysisRecordPath(relativePath: string): boolean;
 /** Check the exact in-memory snapshot being projected; a prior filesystem scan cannot approve a later write. */
-export declare function studyAnalysisSharingProblems(loaded: LoadedAnalysis): {
+export declare function analysisSharingProblems(loaded: LoadedAnalysis): {
     sensitive: boolean;
     unverified: boolean;
 };

package/dist/analysis/sharing.js

@@ -1,9 +1,9 @@
 import { containsSensitive } from "../evidence/redaction.js";
-import { AUTOMATIC_ANALYSIS_DIRECTORY, projectAutomaticStudyAnalysisView } from "./job.js";
+import { AUTOMATIC_ANALYSIS_DIRECTORY, projectAutomaticAnalysisView } from "./job.js";
 import { ANALYSIS_DIRECTORY, ANALYSIS_EXECUTION_DIRECTORY } from "./store.js";
 /** True for the analysis record files, matched by name inside their directories. Any other file
  * under analysis/ is ordinary evidence and follows the ordinary evidence policy. */
-export function isStudyAnalysisRecordPath(relativePath) {
+export function isAnalysisRecordPath(relativePath) {
     const parts = relativePath.split("/");
     const leaf = parts.at(-1);
     const directory = parts[0];
@@ -14,7 +14,7 @@ export function isStudyAnalysisRecordPath(relativePath) {
             leaf.startsWith(".humanish-write-")));
 }
 /** Check the exact in-memory snapshot being projected; a prior filesystem scan cannot approve a later write. */
-export function studyAnalysisSharingProblems(loaded) {
+export function analysisSharingProblems(loaded) {
     // Job metadata never approves evidence, nor does uncertain liveness revoke its approval.
     const { automatic: _automatic, ...evidence } = loaded;
     const benignAttempt = loaded.analysis?.result === null &&
@@ -30,9 +30,9 @@ export function studyAnalysisSharingProblems(loaded) {
 /** Unsafe generated text is quarantined without hiding the original recording. */
 export function projectShareCheckedAnalysis(loaded) {
     const { automatic: _automatic, ...evidence } = loaded;
-    const automatic = projectAutomaticStudyAnalysisView(loaded.automatic);
+    const automatic = projectAutomaticAnalysisView(loaded.automatic);
     const safe = automatic === undefined ? evidence : { ...evidence, automatic };
-    return studyAnalysisSharingProblems(safe).sensitive
+    return analysisSharingProblems(safe).sensitive
         ? {
             state: "invalid",
             analysis: null,

package/dist/analysis/store-executions.d.ts

@@ -2,15 +2,15 @@ import { type PreparedRunArtifactPaths } from "../run/paths.js";
 import { type AnalysisExecutionReceipt, type AnalysisExecutionStart } from "./validation.js";
 import type { AnalysisArtifact } from "./types.js";
 /** Exact bounded receipt lookup for an already claimed execution, never a dispatch decision. */
-export declare function readStudyAnalysisExecution(prepared: PreparedRunArtifactPaths, id: string): Promise<AnalysisExecutionReceipt | null>;
+export declare function readAnalysisExecution(prepared: PreparedRunArtifactPaths, id: string): Promise<AnalysisExecutionReceipt | null>;
 /**
  * Publish accounting first. Unlike a usable report, this receipt does not claim
  * the source still matches; its digests name the exact input that was attempted.
  */
-export declare function writeStudyAnalysisExecutionReceipt(prepared: PreparedRunArtifactPaths, value: AnalysisArtifact): Promise<void>;
+export declare function writeAnalysisExecutionReceipt(prepared: PreparedRunArtifactPaths, value: AnalysisArtifact): Promise<void>;
 /** The returned closure owns one exact directory; persisted IDs never authorize overwriting it. */
-export declare function beginStudyAnalysisExecution(prepared: PreparedRunArtifactPaths, context: Omit<AnalysisExecutionStart, "schema" | "createdAt">): Promise<(value: AnalysisArtifact) => Promise<void>>;
-export declare function listStudyAnalysisExecutions(prepared: PreparedRunArtifactPaths): Promise<{
+export declare function beginAnalysisExecution(prepared: PreparedRunArtifactPaths, context: Omit<AnalysisExecutionStart, "schema" | "createdAt">): Promise<(value: AnalysisArtifact) => Promise<void>>;
+export declare function listAnalysisExecutions(prepared: PreparedRunArtifactPaths): Promise<{
     receipts: AnalysisExecutionReceipt[];
     warnings: string[];
 }>;
@@ -21,7 +21,7 @@ export interface AnalysisAccountingRecord {
     legacy: boolean;
 }
 /** Accounting is independent of source freshness and findings validation. No evidence is opened. */
-export declare function readStudyAnalysisAccountingRecords(prepared: PreparedRunArtifactPaths): Promise<{
+export declare function readAnalysisAccountingRecords(prepared: PreparedRunArtifactPaths): Promise<{
     records: AnalysisAccountingRecord[];
     warnings: string[];
 }>;

package/dist/analysis/store-executions.js

@@ -3,7 +3,7 @@
 import path from "node:path";
 import { runIdOf } from "../run/paths.js";
 import { assertPreparedSelectedOutputDirectory, prepareContainedOutputDirectoryRoot, writeContainedOutputFile, } from "../run/contained-output.js";
-import { pathMissing, readBoundedStudyFile } from "../run/study-files.js";
+import { pathMissing, readBoundedFile } from "../run/evidence-files.js";
 import { ANALYSIS_MAX_BYTES, MAX_VERSIONS, ANALYSIS_DIRECTORY, ANALYSIS_EXECUTION_DIRECTORY, claimDirectory, directoryIds, existingRoot, safeId, } from "./store.js";
 import { hashAnalysisValue, analysisExecutionStartSchema, validateAnalysisArtifact, validateAnalysisExecutionReceipt, } from "./validation.js";
 /** receipt.json and start.json in an execution directory. */
@@ -17,14 +17,14 @@ const EXECUTION_BINDING_KEYS = [
     "promptVersion",
 ];
 /** Exact bounded receipt lookup for an already claimed execution, never a dispatch decision. */
-export async function readStudyAnalysisExecution(prepared, id) {
+export async function readAnalysisExecution(prepared, id) {
     if (!safeId(id))
         return null;
     try {
         const root = await existingRoot(prepared, ANALYSIS_EXECUTION_DIRECTORY);
         if (!root)
             return null;
-        const bytes = await readBoundedStudyFile(root, `${id}/receipt.json`, MAX_EXECUTION_RECORD_BYTES);
+        const bytes = await readBoundedFile(root, `${id}/receipt.json`, MAX_EXECUTION_RECORD_BYTES);
         if (!bytes)
             return null;
         const receipt = validateAnalysisExecutionReceipt(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
@@ -38,7 +38,7 @@ export async function readStudyAnalysisExecution(prepared, id) {
  * Publish accounting first. Unlike a usable report, this receipt does not claim
  * the source still matches; its digests name the exact input that was attempted.
  */
-export async function writeStudyAnalysisExecutionReceipt(prepared, value) {
+export async function writeAnalysisExecutionReceipt(prepared, value) {
     const receipt = executionReceipt(value, prepared);
     const root = await prepareContainedOutputDirectoryRoot(prepared, ANALYSIS_EXECUTION_DIRECTORY);
     const claimed = await claimDirectory(root, receipt.id);
@@ -68,7 +68,7 @@ function executionReceipt(value, prepared) {
     return receipt;
 }
 /** The returned closure owns one exact directory; persisted IDs never authorize overwriting it. */
-export async function beginStudyAnalysisExecution(prepared, context) {
+export async function beginAnalysisExecution(prepared, context) {
     const start = analysisExecutionStartSchema.parse({
         ...context,
         schema: "humanish.analysis-execution-start.v1",
@@ -92,7 +92,7 @@ export async function beginStudyAnalysisExecution(prepared, context) {
         await writeContainedOutputFile(claimed, "receipt.json", `${JSON.stringify(receipt, null, 2)}\n`);
     };
 }
-export async function listStudyAnalysisExecutions(prepared) {
+export async function listAnalysisExecutions(prepared) {
     const receipts = [];
     const warnings = [];
     try {
@@ -102,7 +102,7 @@ export async function listStudyAnalysisExecutions(prepared) {
         const inventory = await directoryIds(root, MAX_VERSIONS);
         warnings.push(...inventory.warnings);
         for (const id of inventory.ids) {
-            const bytes = await readBoundedStudyFile(root, `${id}/receipt.json`, MAX_EXECUTION_RECORD_BYTES);
+            const bytes = await readBoundedFile(root, `${id}/receipt.json`, MAX_EXECUTION_RECORD_BYTES);
             if (!bytes) {
                 if (!(await pathMissing(path.join(root.physicalPath, id, "receipt.json")).catch(() => false)))
                     warnings.push("ANALYSIS_RECEIPT_UNREADABLE");
@@ -128,7 +128,7 @@ export async function listStudyAnalysisExecutions(prepared) {
     return { receipts, warnings: [...new Set(warnings)] };
 }
 /** Accounting is independent of source freshness and findings validation. No evidence is opened. */
-export async function readStudyAnalysisAccountingRecords(prepared) {
+export async function readAnalysisAccountingRecords(prepared) {
     const records = new Map();
     const warnings = [];
     for (const directory of [ANALYSIS_EXECUTION_DIRECTORY, ANALYSIS_DIRECTORY]) {
@@ -145,7 +145,7 @@ export async function readStudyAnalysisAccountingRecords(prepared) {
                     records.set(id, record);
                 }
                 if (directory === ANALYSIS_EXECUTION_DIRECTORY) {
-                    const startBytes = await readBoundedStudyFile(root, `${id}/start.json`, MAX_EXECUTION_RECORD_BYTES);
+                    const startBytes = await readBoundedFile(root, `${id}/start.json`, MAX_EXECUTION_RECORD_BYTES);
                     if (startBytes) {
                         try {
                             const start = analysisExecutionStartSchema.parse(JSON.parse(startBytes.toString("utf8")));
@@ -159,7 +159,7 @@ export async function readStudyAnalysisAccountingRecords(prepared) {
                     }
                 }
                 const legacy = directory === ANALYSIS_DIRECTORY;
-                const bytes = await readBoundedStudyFile(root, `${id}/${legacy ? "analysis.json" : "receipt.json"}`, legacy ? ANALYSIS_MAX_BYTES : MAX_EXECUTION_RECORD_BYTES);
+                const bytes = await readBoundedFile(root, `${id}/${legacy ? "analysis.json" : "receipt.json"}`, legacy ? ANALYSIS_MAX_BYTES : MAX_EXECUTION_RECORD_BYTES);
                 if (!bytes)
                     continue;
                 try {
@@ -169,7 +169,7 @@ export async function readStudyAnalysisAccountingRecords(prepared) {
                     // A historical report may have stale captures or invalid findings. Its strictly checked
                     // accounting metadata still records incurred usage; it never approves those findings.
                     const candidate = legacy
-                        ? Object.fromEntries(Object.keys(studyAnalysisExecutionReceiptKeys).map((key) => [key, raw[key]]))
+                        ? Object.fromEntries(Object.keys(analysisExecutionReceiptKeys).map((key) => [key, raw[key]]))
                         : raw;
                     if (legacy)
                         Object.assign(candidate, {
@@ -208,7 +208,7 @@ export async function readStudyAnalysisAccountingRecords(prepared) {
     }
     return { records: [...records.values()], warnings: [...new Set(warnings)] };
 }
-const studyAnalysisExecutionReceiptKeys = {
+const analysisExecutionReceiptKeys = {
     id: true,
     runId: true,
     status: true,

package/dist/analysis/store.d.ts

@@ -18,14 +18,14 @@ export declare function assertAnalysisPublicationCapacity(prepared: PreparedRunA
 export declare function existingRoot(prepared: PreparedRunArtifactPaths, directory?: string): Promise<PreparedSelectedOutputDirectory | null>;
 export declare function claimDirectory(parent: PreparedSelectedOutputDirectory, id: string): Promise<PreparedSelectedOutputDirectory>;
 /** A claimed version is never reused, including after interruption before publication. */
-export declare function writeStudyAnalysis(prepared: PreparedRunArtifactPaths, value: AnalysisArtifact): Promise<void>;
+export declare function writeAnalysis(prepared: PreparedRunArtifactPaths, value: AnalysisArtifact): Promise<void>;
 export declare function directoryIds(root: PreparedSelectedOutputDirectory, limit: number, ignoreLegacyFiles?: boolean): Promise<{
     ids: string[];
     warnings: string[];
 }>;
 /** Read one exact result without reading automatic job state or unrelated history. */
-export declare function readStudyAnalysisVersion(prepared: PreparedRunArtifactPaths, id: string): Promise<AnalysisListEntry | null>;
+export declare function readAnalysisVersion(prepared: PreparedRunArtifactPaths, id: string): Promise<AnalysisListEntry | null>;
 /** Includes failed attempts; callers must not equate the newest attempt with usable findings. */
 export declare function listAnalyses(prepared: PreparedRunArtifactPaths): Promise<AnalysisListEntry[]>;
-export declare function loadStudyAnalysisRecord(prepared: PreparedRunArtifactPaths, id?: string): Promise<LoadedAnalysis>;
-export declare function appendStudyAnalysisCorrection(prepared: PreparedRunArtifactPaths, value: AnalysisCorrection): Promise<void>;
+export declare function loadAnalysisRecord(prepared: PreparedRunArtifactPaths, id?: string): Promise<LoadedAnalysis>;
+export declare function appendAnalysisCorrection(prepared: PreparedRunArtifactPaths, value: AnalysisCorrection): Promise<void>;

package/dist/analysis/store.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { physicalCwdOf, runIdOf, validatePreparedRunRootIdentity, } from "../run/paths.js";
 import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, prepareContainedOutputDirectoryRoot, writeContainedOutputFile, } from "../run/contained-output.js";
 import { EVIDENCE_LIMITS, validateAnalysisEvidence } from "./evidence.js";
-import { pathMissing, isStudyEvidencePath, readBoundedStudyFile } from "../run/study-files.js";
+import { pathMissing, isEvidencePath, readBoundedFile } from "../run/evidence-files.js";
 import { hashAnalysisValue, validateAnalysisArtifact, validateAnalysisCorrection, } from "./validation.js";
 import { ANALYSIS_ID_PATTERN, } from "./types.js";
 import { RUN_BUNDLE_FILE } from "../run/bundle.js";
@@ -61,9 +61,9 @@ export async function claimDirectory(parent, id) {
     return prepareContainedOutputDirectoryRoot(parent, id);
 }
 /** A claimed version is never reused, including after interruption before publication. */
-export async function writeStudyAnalysis(prepared, value) {
+export async function writeAnalysis(prepared, value) {
     const artifact = validateAnalysisArtifact(value);
-    const source = await readBoundedStudyFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
+    const source = await readBoundedFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
     if (!source)
         throw new Error("ANALYSIS_SOURCE_UNAVAILABLE");
     await validateAnalysisEvidence(prepared, artifact, source);
@@ -73,7 +73,7 @@ export async function writeStudyAnalysis(prepared, value) {
     const root = await prepareContainedOutputDirectoryRoot(prepared, ANALYSIS_DIRECTORY);
     const claimed = await claimDirectory(root, artifact.id);
     // Recheck source immediately before publishing the immutable record.
-    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(source))
         throw new Error("ANALYSIS_SOURCE_CHANGED");
     await writeContainedOutputFile(claimed, "analysis.json", bytes);
@@ -100,7 +100,7 @@ export async function directoryIds(root, limit, ignoreLegacyFiles = false) {
             if (entry.name.startsWith(".humanish-write-"))
                 continue;
             if (ignoreLegacyFiles &&
-                isStudyEvidencePath(entry.name) &&
+                isEvidencePath(entry.name) &&
                 !["analysis.json", "correction.json", "receipt.json"].includes(entry.name))
                 continue;
             warnings.push("ANALYSIS_UNSAFE_ENTRY_IGNORED");
@@ -118,7 +118,7 @@ export async function directoryIds(root, limit, ignoreLegacyFiles = false) {
 async function readVersion(prepared, root, id, source) {
     if (!safeId(id))
         return { id: "invalid", state: "invalid", analysis: null, warnings: ["ANALYSIS_ID_INVALID"] };
-    const bytes = await readBoundedStudyFile(root, `${id}/analysis.json`, ANALYSIS_MAX_BYTES);
+    const bytes = await readBoundedFile(root, `${id}/analysis.json`, ANALYSIS_MAX_BYTES);
     // A claimed directory without a published record is an interrupted write, not a report.
     if (bytes === null) {
         if (await pathMissing(path.join(root.physicalPath, id, "analysis.json")).catch(() => false))
@@ -159,14 +159,14 @@ async function readVersion(prepared, root, id, source) {
     return { id, state: "ready", analysis, warnings: [] };
 }
 /** Read one exact result without reading automatic job state or unrelated history. */
-export async function readStudyAnalysisVersion(prepared, id) {
+export async function readAnalysisVersion(prepared, id) {
     if (!safeId(id))
         return null;
     try {
         const root = await existingRoot(prepared);
         if (!root)
             return null;
-        return await readVersion(prepared, root, id, await readBoundedStudyFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes));
+        return await readVersion(prepared, root, id, await readBoundedFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes));
     }
     catch {
         return null;
@@ -179,7 +179,7 @@ export async function listAnalyses(prepared) {
         if (!root)
             return [];
         const inventory = await directoryIds(root, MAX_VERSIONS, true);
-        const source = await readBoundedStudyFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
+        const source = await readBoundedFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
         const results = [];
         for (const id of inventory.ids) {
             const entry = await readVersion(prepared, root, id, source);
@@ -219,7 +219,7 @@ async function readCorrections(prepared, root, analysis) {
         const inventory = await directoryIds(bound, MAX_CORRECTIONS);
         warnings.push(...inventory.warnings);
         for (const id of inventory.ids) {
-            const bytes = await readBoundedStudyFile(root, `${analysis.id}/corrections/${id}/correction.json`, MAX_CORRECTION_BYTES);
+            const bytes = await readBoundedFile(root, `${analysis.id}/corrections/${id}/correction.json`, MAX_CORRECTION_BYTES);
             if (!bytes) {
                 // An unpublished claim directory is harmless; a present record that
                 // cannot be checked must not silently erase a prior review decision.
@@ -246,7 +246,7 @@ async function readCorrections(prepared, root, analysis) {
     corrections.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
     return { corrections, warnings };
 }
-export async function loadStudyAnalysisRecord(prepared, id) {
+export async function loadAnalysisRecord(prepared, id) {
     if (id !== undefined && !safeId(id))
         return empty("invalid", ["ANALYSIS_ID_INVALID"]);
     try {
@@ -290,9 +290,9 @@ function assertCorrectionBinding(analysis, correction) {
         Date.parse(correction.createdAt) < Date.parse(analysis.completedAt))
         throw new Error("ANALYSIS_CORRECTION_BINDING_INVALID");
 }
-export async function appendStudyAnalysisCorrection(prepared, value) {
+export async function appendAnalysisCorrection(prepared, value) {
     const correction = validateAnalysisCorrection(value);
-    const loaded = await loadStudyAnalysisRecord(prepared, correction.analysisId);
+    const loaded = await loadAnalysisRecord(prepared, correction.analysisId);
     if (loaded.state !== "ready" || !loaded.analysis)
         throw new Error("ANALYSIS_CORRECTION_SOURCE_UNAVAILABLE");
     assertCorrectionBinding(loaded.analysis, correction);

package/dist/cli/commands/analysis-signals.d.ts

@@ -2,6 +2,7 @@ import type { RunLabOptions } from "../../run-lab.js";
 import type { CliIo } from "../io.js";
 /**
  * Post-run analysis cancellation for the CLI: while analysis runs, SIGINT, SIGTERM and SIGHUP abort
- * it. The listeners exist only during analysis, so actor signal behavior is unchanged.
+ * it. The listeners exist only during analysis; before it, the run's own handlers
+ * (run-signals.ts) hold the signals and hand them over here.
  */
 export declare function cliAnalysisOptions(io: Pick<CliIo, "writeErr">): Pick<RunLabOptions, "onEvent" | "analysisSignal">;

package/dist/cli/commands/analysis-signals.js

@@ -1,6 +1,8 @@
+import { handOverRunSignals } from "./run-signals.js";
 /**
  * Post-run analysis cancellation for the CLI: while analysis runs, SIGINT, SIGTERM and SIGHUP abort
- * it. The listeners exist only during analysis, so actor signal behavior is unchanged.
+ * it. The listeners exist only during analysis; before it, the run's own handlers
+ * (run-signals.ts) hold the signals and hand them over here.
  */
 export function cliAnalysisOptions(io) {
     const controller = new AbortController();
@@ -13,6 +15,7 @@ export function cliAnalysisOptions(io) {
         onEvent: (event) => {
             if (event.type === "analysis-started") {
                 io.writeErr("Participants finished; preparing analysis…\n");
+                handOverRunSignals();
                 for (const signal of signals)
                     process.on(signal, cancel);
             }

package/dist/cli/commands/analyze.js

@@ -3,9 +3,9 @@ import { Command, Option } from "commander";
 import { forTerminal } from "../../routes/terminal/encoding.js";
 import { analyzeRun, correctAnalysis, dryRunBundleRefusal, showAnalysis, } from "../../analysis/service.js";
 import { listAnalyses } from "../../analysis/store.js";
-import { listStudyAnalysisExecutions } from "../../analysis/store-executions.js";
+import { listAnalysisExecutions } from "../../analysis/store-executions.js";
 import { resolveRunPath } from "../../run/locate.js";
-import { discoverCliKeys, JSON_OPTION_DESCRIPTION, writeResult } from "../io.js";
+import { CWD_OPTION_DESCRIPTION, discoverCliKeys, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
 import { resolvePhysicalCwd } from "../../run/paths.js";
 /** Commander may collect a shared flag on the parent; only explicit values override leaf defaults. */
 function analysisSelection(options, command) {
@@ -24,11 +24,11 @@ export function registerAnalyzeCommand(parent, io) {
         .command("analyze")
         .enablePositionalOptions()
         .description("Analyze retained participant evidence into versioned findings. Selected text and captures go to the chosen remote analyst. Opening Observer never starts analysis.")
-        .summary("Generate evidence-linked study findings.")
-        .option("--run <id>", "Completed run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .summary("Analyze a live run into evidence-linked findings.")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--provider <name>", "Analyst: openai (default) or restricted codex account. No provider fallback.")
-        .option("--max-cost <usd>", "Required for OpenAI, including dry-run: USD admission estimate ceiling, not a billing cap. Unsupported for Codex.")
+        .option("--max-cost <usd>", "Required for OpenAI, also with --dry-run: send nothing when the estimated cost in USD is above this. The estimate is not a billing cap. Unsupported for Codex.")
         .option("--model <id>", "Supported vision model. OpenAI uses high effort; qualified Codex account analysis uses low effort.", DEFAULT_ANALYSIS_MODEL)
         .option("--question <text>", "Additional reviewer question; does not change participant instructions.")
         .option("--timeout-ms <ms>", "Request timeout, at most 600000 ms.", String(DEFAULT_ANALYSIS_TIMEOUT_MS))
@@ -40,23 +40,23 @@ export function registerAnalyzeCommand(parent, io) {
     analyze
         .command("list")
         .description("List immutable analysis versions, including failed attempts.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleAnalyzeList(io, options, command));
     analyze
         .command("show")
         .description("Read validated analysis and correction history. Defaults to the latest usable version.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .option("--id <id>", "Exact analysis version.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleAnalyzeShow(io, options, command));
     analyze
         .command("correct")
         .description("Append a human review note bound to one exact finding version; original claims remain intact.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .requiredOption("--analysis <id>", "Analysis version to review.")
         .requiredOption("--finding <id>", "Finding to review.")
         .addOption(new Option("--status <status>", "Review disposition.")
@@ -83,7 +83,7 @@ async function handleAnalyze(io, options, command) {
     if (!selected.ok || !selected.config) {
         const refusal = await dryRunBundleRefusal(await resolvePhysicalCwd(options.cwd), options.run, options.dryRun === true);
         if (refusal) {
-            writeResult(command, io, refusal, (value) => forTerminal(`${value.error?.message ?? ""}\n${value.error?.code ?? ""}\n`));
+            writeResult(command, io, refusal, (value) => humanError(value.error));
             io.setExitCode(2);
             return;
         }
@@ -99,7 +99,7 @@ async function handleAnalyze(io, options, command) {
                 message: selected.ok ? "Analysis is disabled." : selected.message,
             },
         };
-        writeResult(command, io, result, (value) => `${value.error.message}\n`);
+        writeResult(command, io, result, (value) => humanError(value.error));
         io.setExitCode(2);
         return;
     }
@@ -126,12 +126,12 @@ async function handleAnalyze(io, options, command) {
             if (value.ok && value.dryRun)
                 return `Admission estimate: $${value.admission?.estimatedCostUsd ?? "unknown"}; output allowance: ${value.admission?.outputTokenAllowance ?? "unknown"} tokens including reasoning. No request sent.\n`;
             const lines = [];
-            if (!value.ok)
-                lines.push(value.error?.message ?? "Analysis unavailable.", value.error?.code ?? "");
             if (value.artifactPath)
                 lines.push(`${value.reused ? "Reused" : "Saved"} ${value.status} analysis: ${value.artifactPath}`);
             if (value.executionReceiptPath)
                 lines.push(`Execution receipt: ${value.executionReceiptPath}`);
+            if (value.rejectedOutputPath)
+                lines.push(`Rejected output, kept locally for diagnosis: ${value.rejectedOutputPath}`);
             if (value.usage) {
                 lines.push(`Recorded attempt usage${value.usage.usageComplete ? "" : " (incomplete)"}: ${value.usage.inputTokens ?? "unknown"} input tokens, ${value.usage.outputTokens ?? "unknown"} output tokens.`);
                 lines.push(`Estimated attempt cost: ${value.usage.estimatedCostUsd === null ? "unknown" : `$${value.usage.estimatedCostUsd}`}.`);
@@ -139,7 +139,12 @@ async function handleAnalyze(io, options, command) {
             if (value.reused)
                 lines.push("No new request sent.");
             lines.push(...value.warnings);
-            return forTerminal(lines.filter(Boolean).join("\n") + "\n");
+            const stdout = lines.length === 0 ? "" : forTerminal(lines.join("\n") + "\n");
+            // A failed analysis keeps its artifact and usage lines on stdout; the error goes to stderr.
+            if (value.ok)
+                return stdout;
+            const error = value.error ?? { message: "Analysis unavailable." };
+            return { ...(stdout ? { stdout } : {}), error };
         });
         io.setExitCode(result.ok ? 0 : 2);
     }
@@ -152,7 +157,7 @@ async function handleAnalyzeList(io, options, command) {
     const prepared = await resolveRunPath(await resolvePhysicalCwd(options.cwd), options.run).catch(() => null);
     const versions = prepared ? await listAnalyses(prepared) : [];
     const executions = prepared
-        ? await listStudyAnalysisExecutions(prepared)
+        ? await listAnalysisExecutions(prepared)
         : { receipts: [], warnings: [] };
     const result = {
         schema: "humanish.analysis-history.v1",

package/dist/cli/commands/codex.js

@@ -3,22 +3,23 @@ import { resolve } from "node:path";
 import { Command, Option } from "commander";
 import { startCodexAppServerUi } from "../../actors/codex/app-server-ui.js";
 import { redactText } from "../../evidence/redaction.js";
-import { JSON_OPTION_DESCRIPTION, parseObserverPort, parseTimeoutMs, writeResult, } from "../io.js";
+import { CWD_OPTION_DESCRIPTION, freePortOption, JSON_OPTION_DESCRIPTION, parseObserverPort, parseTimeoutMs, writeResult, humanError, } from "../io.js";
 export function registerCodexCommands(parent, io) {
+    // Hidden from --help and the CLI reference: it drives a Codex app-server session directly and
+    // is not a step in running or reviewing a study.
     const codex = parent
-        .command("codex")
-        .description("Run Codex-native humanish integration surfaces.")
-        .summary("Run Codex-native humanish integration surfaces.");
+        .command("codex", { hidden: true })
+        .description("Run Codex-native humanish integration surfaces.");
     codex
         .command("app-server")
         .description("Run a browser-visible Codex app-server actor surface and write redacted protocol artifacts.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--prompt <text>", "Prompt to submit to Codex app-server.")
         .option("--prompt-file <path>", "Read the Codex app-server prompt from a file.")
         .option("--run-root <path>", "Artifact directory for redacted app-server evidence.")
         .option("--state-file <path>", "State JSON file for external observers.")
         .option("--timeout-ms <ms>", "Actor timeout in milliseconds.", String(900_000))
-        .option("--port <port>", "Local browser UI port.", "0")
+        .addOption(freePortOption())
         .option("--model <model>", "Optional Codex model override.")
         .addOption(new Option("--sandbox <mode>", "Turn sandbox policy.")
         .choices(["read-only", "workspace-write", "danger-full-access"])
@@ -101,9 +102,8 @@ export function registerCodexCommands(parent, io) {
     });
 }
 function formatCodexAppServerUiHuman(result) {
-    if (!result.ok) {
-        return `${result.error?.code}: ${result.error?.message}\n`;
-    }
+    if (!result.ok)
+        return humanError(result.error);
     return ([
         "humanish codex app-server",
         `url: ${result.url ?? "not-started"}`,