humanish 0.107.0 → 0.108.0

package/dist/actors/local-agent/readiness.js

@@ -1,8 +1,8 @@
 // Whether a local-agent participant can run on this machine before anything is acquired: its CLI
-// is on PATH and signed in, a hosted Codex CLI is a qualified release on a supported platform, and
+// is on `PATH` and signed in, a hosted Codex CLI is a qualified release on a supported platform, and
 // a ChatGPT-account Codex is not asked to enforce a dollar cap it has no price for. Each route maps
 // the refusal's kind to its own error code.
-import { describeQualifiedCodexCliVersions } from "../codex/qualified-versions.js";
+import { describeCodexCliAdmission } from "../codex/codex-admission.js";
 import { checkHostedCodexCompatibility, detectLocalAgents } from "./cli.js";
 export async function localAgentRefusal(args) {
     const { agent, env, caps } = args;
@@ -19,7 +19,7 @@ export async function localAgentRefusal(args) {
         return {
             kind: "signin-required",
             message: chosen.authStatus === "unauthenticated"
-                ? `${chosen.label} reports not signed in — run \`${chosen.id === "codex" ? "codex login" : "claude auth login"}\`, then retry.`
+                ? `${chosen.label} reports it is not signed in; run \`${chosen.id === "codex" ? "codex login" : "claude auth login"}\`, then retry.`
                 : `${chosen.label} authentication status could not be checked. Run \`${chosen.id === "codex" ? "codex login status" : "claude auth status"}\` and update the CLI if needed. No desktop was launched.`,
         };
     }
@@ -31,7 +31,7 @@ export async function localAgentRefusal(args) {
             kind: "unsupported",
             message: compatibility === "unsupported_platform"
                 ? `Hosted Codex participants require Linux or macOS on x64 or arm64. This host is ${process.platform}/${process.arch}; no desktop was launched.`
-                : `Hosted Codex participants require a qualified Codex CLI (${describeQualifiedCodexCliVersions()}). Run \`codex --version\` and install a qualified version before retrying; no desktop was launched.`,
+                : `Hosted Codex participants need a Codex CLI release humanish runs: ${describeCodexCliAdmission()}. Run \`humanish doctor\` for the release it found and the command that replaces it; no desktop was launched.`,
         };
     }
     if (chosen.billing === "account-unknown" &&

package/dist/actors/reasoning-effort.js

@@ -1,19 +1,19 @@
 // The provider-declared reasoning-effort vocabulary, kept in its own module so the lab schema and
 // the OpenAI provider can share it without the schema depending on a provider.
 //
-// WHY THIS EXISTS AT ALL: effort was reachable in the provider and unreachable from a lab. Every
-// computer-use run humanish had ever done was therefore the provider default — not by decision but
-// by omission (#497). Effort changes who the PARTICIPANT is, the same way a persona prompt does
+// Why this exists: effort was reachable in the provider and unreachable from a lab. Every
+// computer-use run humanish had ever done was therefore the provider default, not by decision but
+// by omission. Effort changes who the participant is, the same way a persona prompt does
 // (docs/principles/actor-fidelity.md: capability settings are recruiting decisions), so pinning it
 // invisibly meant every persona finding was really a finding about that persona at medium, with the
 // second half unsaid.
 //
-// SUPPORT IS MODEL-DEPENDENT. OpenAI documents the vocabulary below as the union across models and
+// Support is model-dependent. OpenAI documents the vocabulary below as the union across models and
 // states plainly that "supported values are model-dependent"; there is no offline way to know which
 // subset a given model id accepts. So this module refuses to pretend: it validates that a lab asked
-// for a REAL effort level, and a model that does not support the one it was asked for fails on the
+// for a real effort level, and a model that does not support the one it was asked for fails on the
 // first turn with the provider's own message rather than being silently downgraded. Silent
-// downgrade is the worse failure — it would record an effort the run did not actually use.
+// downgrade is the worse failure: it would record an effort the run did not actually use.
 /** The documented vocabulary, ordered from least to most reasoning. */
 export const REASONING_EFFORTS = [
     "none",

package/dist/actors/registry.d.ts

@@ -27,27 +27,27 @@ export interface TerminalActorDescriptor extends ActorDescriptorBase {
 }
 export type ActorDescriptor = CodexActorDescriptor | CuaActorDescriptor | ScriptedBrowserActorDescriptor | TerminalActorDescriptor;
 /**
- * REGISTRY CONTRACT: an actor whose capabilities include the "computer-use" lane is a
- * CuaActorDescriptor — its runSession takes CuaActorSessionOptions and returns a CuaLoopResult.
+ * Registry contract: an actor whose capabilities include the "computer-use" run kind is a
+ * CuaActorDescriptor: its runSession takes CuaActorSessionOptions and returns a CuaLoopResult.
  * Any future computer-use provider (e.g. stagehand-cua) must keep that session signature and add
  * its id to CuaActorDescriptor["id"], so code narrowed by this guard can still tell the ids apart.
  * This guard is what lets the lab dispatch on capabilities rather than on hardcoded actor ids.
  */
 export declare function isCuaActorDescriptor(descriptor: ActorDescriptor): descriptor is CuaActorDescriptor;
 /**
- * REGISTRY CONTRACT (mirror of isCuaActorDescriptor): an actor whose capabilities include the
- * "scripted-browser" lane IS a ScriptedBrowserActorDescriptor — runSession takes
+ * Registry contract (mirror of isCuaActorDescriptor): an actor whose capabilities include the
+ * "scripted-browser" run kind is a ScriptedBrowserActorDescriptor; runSession takes
  * ScriptedBrowserSessionOptions and returns ScriptedBrowserSessionResult (trace fully formed,
- * like the CUA shape — no separate toActorTrace). Any future scripted driver (e.g. a HAR
+ * like the CUA shape; no separate toActorTrace). Any future scripted driver (e.g. a HAR
  * replayer) must keep this signature; it is what lets the lab dispatch on capabilities, not ids.
  */
 export declare function isScriptedBrowserActorDescriptor(descriptor: ActorDescriptor): descriptor is ScriptedBrowserActorDescriptor;
 /**
- * REGISTRY CONTRACT (mirror of isCuaActorDescriptor / isScriptedBrowserActorDescriptor): an actor
- * whose capabilities include the "terminal" lane IS a TerminalActorDescriptor. This is the guard
- * the terminal-product lab uses for route selection and capability enforcement. The current
- * descriptor's direct runSession is intentionally unsupported; live execution is route-owned.
- * Any future terminal actor must declare keyPlacement honestly and integrate with that lifecycle.
+ * Registry contract (mirror of isCuaActorDescriptor / isScriptedBrowserActorDescriptor): an actor
+ * whose capabilities include the "terminal" run kind is a TerminalActorDescriptor. This is the
+ * guard the terminal-product route uses for route selection and capability enforcement. The current
+ * descriptor's direct runSession is intentionally unsupported; live execution is route-owned. Any
+ * future terminal actor must declare the keyPlacement it uses and integrate with that lifecycle.
  */
 export declare function isTerminalActorDescriptor(descriptor: ActorDescriptor): descriptor is TerminalActorDescriptor;
 export declare const actorRegistry: Record<ActorId, ActorDescriptor>;

package/dist/actors/registry.js

@@ -6,8 +6,8 @@ import { LOCAL_AGENT_CAPABILITIES } from "./local-agent/cli.js";
 import { OPENAI_RESPONSES_CU_CAPABILITIES } from "./computer-use/openai-provider.js";
 import { runScriptedBrowserSession, } from "./scripted-browser/actor.js";
 /**
- * REGISTRY CONTRACT: an actor whose capabilities include the "computer-use" lane is a
- * CuaActorDescriptor — its runSession takes CuaActorSessionOptions and returns a CuaLoopResult.
+ * Registry contract: an actor whose capabilities include the "computer-use" run kind is a
+ * CuaActorDescriptor: its runSession takes CuaActorSessionOptions and returns a CuaLoopResult.
  * Any future computer-use provider (e.g. stagehand-cua) must keep that session signature and add
  * its id to CuaActorDescriptor["id"], so code narrowed by this guard can still tell the ids apart.
  * This guard is what lets the lab dispatch on capabilities rather than on hardcoded actor ids.
@@ -16,21 +16,21 @@ export function isCuaActorDescriptor(descriptor) {
     return descriptor.capabilities.lanes.includes("computer-use");
 }
 /**
- * REGISTRY CONTRACT (mirror of isCuaActorDescriptor): an actor whose capabilities include the
- * "scripted-browser" lane IS a ScriptedBrowserActorDescriptor — runSession takes
+ * Registry contract (mirror of isCuaActorDescriptor): an actor whose capabilities include the
+ * "scripted-browser" run kind is a ScriptedBrowserActorDescriptor; runSession takes
  * ScriptedBrowserSessionOptions and returns ScriptedBrowserSessionResult (trace fully formed,
- * like the CUA shape — no separate toActorTrace). Any future scripted driver (e.g. a HAR
+ * like the CUA shape; no separate toActorTrace). Any future scripted driver (e.g. a HAR
  * replayer) must keep this signature; it is what lets the lab dispatch on capabilities, not ids.
  */
 export function isScriptedBrowserActorDescriptor(descriptor) {
     return descriptor.capabilities.lanes.includes("scripted-browser");
 }
 /**
- * REGISTRY CONTRACT (mirror of isCuaActorDescriptor / isScriptedBrowserActorDescriptor): an actor
- * whose capabilities include the "terminal" lane IS a TerminalActorDescriptor. This is the guard
- * the terminal-product lab uses for route selection and capability enforcement. The current
- * descriptor's direct runSession is intentionally unsupported; live execution is route-owned.
- * Any future terminal actor must declare keyPlacement honestly and integrate with that lifecycle.
+ * Registry contract (mirror of isCuaActorDescriptor / isScriptedBrowserActorDescriptor): an actor
+ * whose capabilities include the "terminal" run kind is a TerminalActorDescriptor. This is the
+ * guard the terminal-product route uses for route selection and capability enforcement. The current
+ * descriptor's direct runSession is intentionally unsupported; live execution is route-owned. Any
+ * future terminal actor must declare the keyPlacement it uses and integrate with that lifecycle.
  */
 export function isTerminalActorDescriptor(descriptor) {
     return descriptor.capabilities.lanes.includes("terminal");
@@ -43,13 +43,14 @@ export const actorRegistry = {
         runSession: runCodexAppServerSession,
         toActorTrace: codexResultToActorTrace,
     },
-    // The ActorId names the actor slot (keeps the lane open for a future stagehand-cua provider);
-    // the trace's `provider` string stays "openai-responses-cu" (the concrete model adapter).
-    // The operator's own signed-in coding agent as the computer-use brain (Codex on a ChatGPT plan,
-    // Claude Code on a Max plan). Same lane, same loop, same evidence — the only difference is where
-    // the next action comes from, which is exactly why it is a provider swap and not a new lane.
-    // It exists so someone new can watch a persona drive a real desktop without first going to find
-    // an API key; the machine they are on very often already has one of these signed in.
+    // The ActorId names the actor slot (keeps the slot open for a future stagehand-cua
+    // provider); the trace's `provider` string stays "openai-responses-cu" (the concrete model
+    // adapter). The operator's own signed-in coding agent as the computer-use brain (Codex on a
+    // ChatGPT plan, Claude Code on a Max plan). Same run kind, same loop, same evidence; the only
+    // difference is where the next action comes from, which is exactly why it is a provider swap and
+    // not a new run kind. It exists so someone new can watch a persona drive a real desktop
+    // without first going to find an API key; the machine they are on very often already has one of
+    // these signed in.
     "local-agent": {
         id: "local-agent",
         label: "Local coding agent (operator-authenticated)",

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

@@ -10,10 +10,10 @@ export interface ScriptedBrowserSessionOptions {
     urlPolicy?: ScriptedBrowserEvidenceUrlPolicy;
     /** Parsed + validated by the backend (scenario.ref is consumed there, fail-closed). */
     journey: BrowserPersonaJourney;
-    /** ONE session per surface. */
+    /** One session per surface. */
     surface: BrowserSurface;
     /** id = actors[0].persona ?? "scripted-journey"; promptDigest = journey.sourceDigest prefix
-     *  (the step manifest IS the "prompt" — no model prompt exists on this route). */
+     *  (the step manifest is the "prompt"; no model prompt exists on this route). */
     persona: ActorPersonaRef;
     /** Journey wall-clock budget in ms; the lab route passes execution.timeoutMs or 300_000. */
     timeoutMs: number;
@@ -30,19 +30,19 @@ export interface ScriptedBrowserSessionResult extends ActorSessionResult {
     capture: BrowserSurfaceCapture;
 }
 /**
- * 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 declare function runScriptedBrowserSession(options: ScriptedBrowserSessionOptions): Promise<ScriptedBrowserSessionResult>;
 /** Internal lab seam: the run root is already prepared and must stay bound to that identity. */

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/steps.js

@@ -176,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

@@ -108,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.
      */

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/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/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";
@@ -43,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.",
@@ -56,9 +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_incompatible_release: `This Codex CLI release changed app-server protocol fields humanish reads, so no request was sent; the warnings name each change. Install a release humanish was tested with (${describeQualifiedCodexCliVersions()}), then retry.`,
+    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.",

package/dist/cli/commands/analyze.js

@@ -5,7 +5,7 @@ import { analyzeRun, correctAnalysis, dryRunBundleRefusal, showAnalysis, } from
 import { listAnalyses } from "../../analysis/store.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,8 +126,6 @@ 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)
@@ -141,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);
     }

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"}`,