humanish 0.106.1 → 0.108.0

package/TELEMETRY.md

@@ -6,26 +6,28 @@ disclosed the first time it happens, and you can switch it off in one command.
 
 This follows the convention the Next.js and Vercel CLIs established, with one
 difference: humanish is stricter about what may be collected, because a study's
-subject is your product and a lab id can name something you have not announced.
+subject is your product and a study id can name something you have not announced.
 
 ## Why
 
 humanish shipped sixty-one releases without being able to answer _"does anyone
 get to a working first run?"_. The answer, when it finally arrived, came from an
 adoption post-mortem: the first live run had been impossible for months, because
-the starter labs shipped with a placeholder URL. Nobody reported it. Without
+the starter studies shipped with a placeholder URL. Nobody reported it. Without
 telemetry, humanish cannot tell whether new users reach a working first run.
 
 ## What is collected
 
-- which command ran (`run`, `lab run`, `init`, …)
+- which command ran (`run`, `init`, …)
 - the humanish version, your OS, your Node major version, whether you are in CI
 - whether the command succeeded (its exit code), and roughly how long it took
   (a bucket such as `1-5m`, never an exact duration)
 - for a study: whether it was a dry run or live, its outcome (one of a fixed
   set of words such as `passed`, `abandoned`, `all_passed`), which brain route
-  ran it (`provider-key`, `local-agent`, or `none` for a dry run), and which lab
-  ran, **only if it is one of the starter labs `humanish init` writes**
+  ran it (`provider-key`, `local-agent`, or `none` for a dry run), and which study
+  ran, **only if it is one of the starter studies `humanish init` writes**. That id is sent as
+  `study`, and also as `lab` (the property's earlier name) with the same value until 0.109.0
+  removes `lab`
 - when a command fails: humanish's own error code (`HUMANISH_…`), never the
   message. Which failure ends a first run is the question this exists to answer.
 - for CUA results with diagnostics: `diagnostic_category` is exactly one of
@@ -58,7 +60,7 @@ HUMANISH_TELEMETRY_DEBUG=1 humanish run first-run
 
 ## What is never collected
 
-Your own lab ids and titles. Your subjects: repos, URLs, app names. Personas,
+Your own study ids and titles. Your subjects: repos, URLs, app names. Personas,
 missions, or any prompt text. Paths, working directories, hostnames, usernames.
 Run ids, evidence, screenshots, traces. Credential names or values. There is no
 field in the payload that could carry any of these. `src/cli/telemetry.ts` enforces

package/dist/actors/affordance.d.ts

@@ -6,7 +6,7 @@ export declare const AFFORDANCE_CLASS_SCHEMA = "humanish.affordance-use.v1";
  * direct navigation, "shortcut" (MAS-Bench) for a non-UI route to the same outcome.
  */
 export type AffordanceClass = 
-/** Pointer or drag interaction with what is rendered on screen — the naturalistic core. */
+/** Pointer or drag interaction with what is rendered on screen: the naturalistic core. */
 "pointer"
 /** Keyboard input into the page: typed text that is not a URL and not script. */
  | "keyboard"
@@ -32,7 +32,7 @@ export declare const SHORTCUT_AFFORDANCE_CLASSES: readonly AffordanceClass[];
 export interface AffordanceObservation {
     affordance: AffordanceClass;
     /**
-     * A public-safe hint about WHY this class was assigned, when one exists — a URL scheme or the
+     * A public-safe hint about why this class was assigned, when one exists: a URL scheme or the
      * devtools chord. Never the typed text, never a full URL (which can carry a session token).
      */
     signal?: string;
@@ -40,7 +40,7 @@ export interface AffordanceObservation {
 /** Aggregate per-run record: how many actions fell into each class. */
 export interface AffordanceUse {
     schema: typeof AFFORDANCE_CLASS_SCHEMA;
-    /** Counts by class; a class with zero actions is omitted so the record stays small and honest. */
+    /** Counts by class. A class with zero actions is omitted, so every listed class was used. */
     counts: Partial<Record<AffordanceClass, number>>;
     /** Total classified actions (the denominator for any rate an adopter computes). */
     total: number;
@@ -48,7 +48,7 @@ export interface AffordanceUse {
     shortcutTotal: number;
 }
 /**
- * Classify one computer-use action. PURE: same action in, same class out, no I/O, no clock. The
+ * Classify one computer-use action. Pure: same action in, same class out, no I/O, no clock. The
  * returned signal is public-safe (a scheme or a chord), never the action's text.
  */
 export declare function classifyCuaAction(action: CuaAction): AffordanceObservation;

package/dist/actors/affordance.js

@@ -1,25 +1,25 @@
-// Affordance classification (#369): WHICH KIND of route an actor took to accomplish a step.
+// Affordance classification: which kind of route an actor took to accomplish a step.
 //
 // Why this exists. A computer-use actor in a human-persona study typed a `javascript:` URL into
 // the address bar to get past a step, and the run finished green: the actor routed around the
 // friction the study existed to measure, and nothing in the evidence said so. Whether that is a
-// defect depends on a question the bundle never recorded — who is this study's user? For a human
-// population it invalidates the run; for an agent-facing product whose users ARE agents the same
+// defect depends on a question the bundle never recorded: who is this study's user? For a human
+// population it invalidates the run; for an agent-facing product whose users are agents the same
 // act is faithful, and the fact the agent reached for it is itself a finding about how legible
-// the surface is. So the harness records the class and bakes NO verdict: the adopter's scorer
+// the surface is. So the harness records the class and bakes no verdict: the adopter's scorer
 // (review.scorer.ref) decides what it means, because that judgment is product semantics.
 //
 // Two design facts drive the shape:
 //
-//  1. The computer-use action space is mouse + keyboard only — there is no `goto` action. Typing a
-//     URL is a `type` action whose TEXT happens to be a URL, and typing script is a `type` action
+//  1. The computer-use action space is mouse + keyboard only; there is no `goto` action. Typing a
+//     URL is a `type` action whose text happens to be a URL, and typing script is a `type` action
 //     whose text happens to start with `javascript:`. Classification therefore has to look at the
 //     typed text, which exists only at dispatch time.
 //  2. Raw typed text is never persisted (describeCuaAction deliberately renders `type [N chars]`),
-//     so this module returns a CLASS and at most a scheme-shaped signal — never the text. The
+//     so this module returns a class and at most a scheme-shaped signal, never the text. The
 //     class is public-safe by construction.
 //
-// Direct URL navigation is deliberately its own class and NOT lumped with script execution:
+// Direct URL navigation is deliberately its own class, separate from script execution:
 // `load(url)` appears in 99.4% of 2,337 real human web demonstrations (WebLINX), so address-bar
 // use is ordinary human behavior. The anomalous classes are script execution and developer
 // tooling. See docs/principles/actor-fidelity.md for the evidence and the scoping of the claim.
@@ -61,7 +61,7 @@ const DEVTOOLS_CHORDS = new Set([
     "meta+alt+c",
 ]);
 /**
- * Classify one computer-use action. PURE: same action in, same class out, no I/O, no clock. The
+ * Classify one computer-use action. Pure: same action in, same class out, no I/O, no clock. The
  * returned signal is public-safe (a scheme or a chord), never the action's text.
  */
 export function classifyCuaAction(action) {
@@ -95,7 +95,7 @@ export function classifyCuaAction(action) {
                 return { affordance: "browser-internal", signal: schemeOf(text) };
             }
             if (HTTP_URL.test(text)) {
-                // Scheme only — a full URL can carry a session token or an identifying path.
+                // Scheme only: a full URL can carry a session token or an identifying path.
                 return { affordance: "url-navigation", signal: schemeOf(text) };
             }
             if (BARE_HOST.test(text)) {
@@ -113,7 +113,7 @@ export function classifyCuaAction(action) {
 }
 /**
  * Normalize a key chord so the same physical shortcut matches however a provider spells it:
- * `Control`/`ctrl`, `Meta`/`Command`/`cmd`, `Option`/`alt` all collapse, and modifier ORDER is
+ * `Control`/`ctrl`, `Meta`/`Command`/`cmd`, `Option`/`alt` all collapse, and modifier order is
  * normalized so ["Shift","Control","J"] and ["Control","Shift","J"] are one chord.
  */
 function normalizeChord(keys) {
@@ -138,7 +138,7 @@ function normalizeChord(keys) {
     const rest = parts.filter((part) => !order.includes(part));
     return [...modifiers, ...rest].join("+");
 }
-/** The scheme alone, lowercased — never the rest of a URL, which can carry a session token. */
+/** The scheme alone, lowercased; never the rest of a URL, which can carry a session token. */
 function schemeOf(text) {
     const trimmed = text.trim();
     const colon = trimmed.indexOf(":");

package/dist/actors/agent-session.d.ts

@@ -1,11 +1,11 @@
 export interface AgentSession {
     /** Human-readable runner name, for the refusal message. */
     runner: string;
-    /** The environment variable that identified it — named so the reader can check us. */
+    /** The environment variable that identified it, named so the reader can check us. */
     marker: string;
 }
 /**
  * The agent runner driving this process, when one identifies itself. `undefined` means nothing
- * claimed to be an agent — which is NOT proof a person is there, only the absence of a claim.
+ * claimed to be an agent, which is not proof a person is there, only the absence of a claim.
  */
 export declare function detectAgentSession(env?: NodeJS.ProcessEnv): AgentSession | undefined;

package/dist/actors/agent-session.js

@@ -1,19 +1,19 @@
-// Is the terminal on the other end of this process a PERSON's, or an agent's?
+// Is the terminal on the other end of this process a person's, or an agent's?
 //
-// WHY THIS EXISTS: `humanish tui` refused a non-TTY, on the reasoning that an agent driving an
+// Why this exists: `humanish tui` refused a non-TTY, on the reasoning that an agent driving an
 // interactive surface has asked for something that cannot exist. A study of that refusal
 // (labs/handed-a-human-surface.yaml) found it never fires: `codex exec` allocates a PTY for the
-// commands it runs, so both streams ARE terminals. The TUI launched, the agent navigated the labs
-// list, opened one, and — its own words — "accidentally triggered a zero-cost dry run while
+// commands it runs, so both streams are terminals. The TUI launched, the agent navigated the labs
+// list, opened one, and (in its own words) "accidentally triggered a zero-cost dry run while
 // navigating". A stray Enter on a live row is the same two keystrokes as a deliberate one.
 //
 // So a TTY is a real answer to the wrong question. It says a terminal exists; it does not say
 // anyone is reading it. Agent runners announce themselves in the environment, which is the only
 // signal available before the first keystroke, and is what `is-in-ci` has always done for CI.
 //
-// EVERY MARKER BELOW WAS OBSERVED, not guessed. Two runtimes are covered because two are what we
+// Every marker below was observed, not guessed. Two runtimes are covered because two are what we
 // could verify: Claude Code (read off a live session) and Codex (read off the study sandbox, by a
-// names-only `env | cut -d= -f1` probe that never touched a value). Others certainly exist — add
+// names-only `env | cut -d= -f1` probe that never touched a value). Others certainly exist; add
 // them the same way, from a real session, rather than from a plausible-looking guess. A marker
 // that is wrong refuses a person for no reason.
 const MARKERS = [
@@ -27,7 +27,7 @@ const MARKERS = [
 ];
 /**
  * The agent runner driving this process, when one identifies itself. `undefined` means nothing
- * claimed to be an agent — which is NOT proof a person is there, only the absence of a claim.
+ * claimed to be an agent, which is not proof a person is there, only the absence of a claim.
  */
 export function detectAgentSession(env = process.env) {
     for (const { marker, runner } of MARKERS) {

package/dist/actors/codex/app-server-actor-trace.d.ts

@@ -5,7 +5,7 @@ export declare function codexStatusToCompletionReason(status: CodexAppServerStat
 /**
  * Map a Codex app-server run result into the provider-neutral ActorTrace. Pure
  * and side-effect-free. The persona reference is supplied by the harness; until
- * personas are load-bearing it is a minimal stub ({ id, traitsApplied: [],
+ * the Codex route uses personas it is a minimal stub ({ id, traitsApplied: [],
  * promptDigest }).
  */
 export declare function codexResultToActorTrace(result: CodexAppServerRunResult, persona: ActorPersonaRef): ActorTrace;

package/dist/actors/codex/app-server-actor-trace.js

@@ -173,7 +173,7 @@ function codexTraceToActorItems(trace) {
 /**
  * Map a Codex app-server run result into the provider-neutral ActorTrace. Pure
  * and side-effect-free. The persona reference is supplied by the harness; until
- * personas are load-bearing it is a minimal stub ({ id, traitsApplied: [],
+ * the Codex route uses personas it is a minimal stub ({ id, traitsApplied: [],
  * promptDigest }).
  */
 export function codexResultToActorTrace(result, persona) {

package/dist/actors/codex/app-server-client.js

@@ -1,6 +1,7 @@
 import readline from "node:readline";
 import { redactText } from "../../evidence/redaction.js";
-import { formatJsonRpcError, isRecord, } from "./app-server-trace.js";
+import { isRecord } from "../../run/type-guards.js";
+import { formatJsonRpcError } from "./app-server-trace.js";
 export class CodexStdioClient {
     child;
     commandName;

package/dist/actors/codex/app-server-trace.d.ts

@@ -150,5 +150,4 @@ export declare function renderTranscript(trace: CodexAppServerTrace): string;
 export declare function readNestedString(value: unknown, pathParts: string[]): string | undefined;
 export declare function formatJsonRpcError(error: JsonObject): string;
 export declare function redactCodexEnvelope(value: unknown, rootCwd: string): unknown;
-export declare function isRecord(value: unknown): value is JsonObject;
 export {};

package/dist/actors/codex/app-server-trace.js

@@ -1,6 +1,7 @@
 // The trace a codex-app-server run writes (summary.json): its schema, the recorder that builds it
 // from app-server envelopes, and the redaction applied before anything is persisted.
 import { digestText, publicPathForTrace, redactText, tailText } from "../../evidence/redaction.js";
+import { isRecord } from "../../run/type-guards.js";
 export const CODEX_APP_SERVER_TRACE_SCHEMA = "humanish.codex-app-server-trace.v1";
 const authLikeKey = /(api[_-]?key|access[_-]?token|auth[_-]?url|authorization|bearer|credential|password|secret|token)$/i;
 const pathLikeKey = /^(cwd|path|writableRoots|workspaceRoot)$/i;
@@ -419,6 +420,3 @@ function limitTranscript(value) {
     }
     return `[...sanitized transcript truncated to last ${maxChars} characters...]\n${value.slice(-maxChars)}`;
 }
-export function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/dist/actors/codex/app-server-ui.js

@@ -242,7 +242,7 @@ function renderCodexAppServerUiHtml() {
         <h1>Codex App-Server Actor</h1>
         <p id="subtitle">Connecting to humanish state...</p>
       </div>
-      <div class="pill" id="status" data-status="starting">STARTING</div>
+      <div class="pill" id="status" data-status="starting">starting</div>
     </header>
     <main>
       <aside>

package/dist/actors/codex/app-server.js

@@ -2,8 +2,9 @@ import { spawn } from "node:child_process";
 import path from "node:path";
 import { digestText, tailText } from "../../evidence/redaction.js";
 import { prepareContainedOutputDirectory, prepareContainedOutputFile, prepareSelectedOutputDirectory, writeContainedOutputFile, } from "../../run/contained-output.js";
+import { isRecord } from "../../run/type-guards.js";
 import { CodexStdioClient } from "./app-server-client.js";
-import { CodexTraceRecorder, isRecord, readNestedString, redactCodexEnvelope, renderTranscript, } from "./app-server-trace.js";
+import { CodexTraceRecorder, readNestedString, redactCodexEnvelope, renderTranscript, } from "./app-server-trace.js";
 export async function runCodexAppServerSession(options) {
     const preparedRunRoot = await prepareSelectedOutputDirectory(process.cwd(), options.runRoot);
     return runCodexAppServerSessionInPreparedRoot(options, preparedRunRoot);

package/dist/actors/codex/codex-admission.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Which Codex CLI releases the restricted launcher starts: every stable `MAJOR.MINOR.PATCH`
+ * release from RECORDED_CODEX_CLI_FLOOR (0.154.0, the oldest known to work) on, except the
+ * refused ones. There is no ceiling, so a new release runs the day it ships; a release that breaks
+ * humanish is a bug, fixed by refusing it here until humanish handles it. Saved bundles read any
+ * stable release from the same floor, refused or not (src/actors/contract.ts).
+ *
+ * A release string is a compatibility check, not binary attestation: the launcher compares what
+ * `codex --version`, initialize and thread start report, and a modified binary can report any
+ * of them. Each launch also checks the release's app-server schema (protocol-compat.ts).
+ */
+export declare const REFUSED_CODEX_CLI_VERSIONS: readonly {
+    readonly version: string;
+    readonly reason: string;
+    readonly issue: string;
+}[];
+/**
+ * Releases `pnpm codex:qualify` passed on Linux x64, oldest first. They gate nothing: the newest is
+ * the default a declaration names before detection, the install target and the "last tested"
+ * hint, and the list is the qualifier's baseline.
+ */
+export declare const TESTED_CODEX_CLI_VERSIONS: readonly ["0.154.0", "0.157.1", "0.159.2", "0.159.3", "0.160.0"];
+/**
+ * The run warning for a hosted (operator-mode) participant on a release not in
+ * TESTED_CODEX_CLI_VERSIONS, or undefined. No qualifier ran that release in operator mode, so its
+ * evidence rests on what each launch checks (open-admission design, answer C).
+ */
+export declare function untestedOperatorReleaseWarning(cliVersion: string | undefined, operator: boolean): string | undefined;
+/** Why the launcher refuses a release, or undefined when it starts it. */
+export type CodexCliRefusal = {
+    readonly reason: "unrecognized";
+} | {
+    readonly reason: "prerelease" | "below_floor";
+    readonly version: string;
+} | {
+    readonly reason: "refused";
+    readonly version: string;
+    readonly detail: string;
+    readonly issue: string;
+};
+/**
+ * Why the launcher refuses a release: not a plain `MAJOR.MINOR.PATCH` (or longer than the 64
+ * characters parseCodexCliVersion reads), a prerelease (`-` after the core), older than the floor,
+ * or refused.
+ */
+export declare function codexCliRefusal(version: string | undefined): CodexCliRefusal | undefined;
+/** Whether the launcher starts this release. */
+export declare const admitsCodexCliVersion: (version: string) => boolean;
+/**
+ * Hosts where isolated launches run (the Codex-account analyst and local-browser participants).
+ * Operator launches run on every host with a native npm build (restrictedCodexNpmTarget).
+ */
+export declare const supportsIsolatedCodex: (platform: NodeJS.Platform, arch: string) => boolean;
+/** What a declaration names before the installed CLI is detected: the newest tested release. */
+export declare function defaultCodexCliVersion(): string;
+/** The version from `codex --version` output (`codex-cli 0.157.1`); any other shape is undefined. */
+export declare function parseCodexCliVersion(stdout: string): string | undefined;
+/**
+ * doctor's recovery for a refused CLI: the release it found and where, why it is refused, and how
+ * to replace that binary with the last tested release.
+ */
+export declare function codexVersionRecovery(detected: string | undefined, installation?: CodexInstallation): string;
+/**
+ * Where the `codex` humanish found was installed, which decides the command that replaces it.
+ * `path` is the file on `PATH`.
+ */
+export type CodexInstallation = {
+    readonly kind: "project";
+    readonly path: string;
+    readonly project: string;
+} | {
+    readonly kind: "global";
+    readonly path: string;
+} | {
+    readonly kind: "other";
+    readonly path: string;
+};
+/**
+ * Classifies the `codex` on `PATH` by the file it resolves to. A project's node_modules/.bin/codex
+ * resolving into that project's @openai/codex is project-local, so `npx` runs it before any global
+ * install. One inside npm's global prefix (`npm prefix -g`) is global. Anything else, such as
+ * Homebrew or a standalone download, is other.
+ */
+export declare function classifyCodexInstallation(found: {
+    path: string;
+    resolved: string;
+}, npmGlobalPrefix: string | undefined): CodexInstallation;
+/** One sentence: how to put the last tested Codex CLI in place of the one humanish found. */
+export declare function codexInstallAdvice(installation: CodexInstallation | undefined): string;
+/** For refusal messages: which releases the launcher starts, and the last tested one. */
+export declare function describeCodexCliAdmission(): string;

package/dist/actors/codex/codex-admission.js

@@ -0,0 +1,150 @@
+import path from "node:path";
+import { RECORDED_CODEX_CLI_FLOOR, isRecordedCodexCliVersion } from "../contract.js";
+/**
+ * Which Codex CLI releases the restricted launcher starts: every stable `MAJOR.MINOR.PATCH`
+ * release from RECORDED_CODEX_CLI_FLOOR (0.154.0, the oldest known to work) on, except the
+ * refused ones. There is no ceiling, so a new release runs the day it ships; a release that breaks
+ * humanish is a bug, fixed by refusing it here until humanish handles it. Saved bundles read any
+ * stable release from the same floor, refused or not (src/actors/contract.ts).
+ *
+ * A release string is a compatibility check, not binary attestation: the launcher compares what
+ * `codex --version`, initialize and thread start report, and a modified binary can report any
+ * of them. Each launch also checks the release's app-server schema (protocol-compat.ts).
+ */
+export const REFUSED_CODEX_CLI_VERSIONS = [];
+/**
+ * Releases `pnpm codex:qualify` passed on Linux x64, oldest first. They gate nothing: the newest is
+ * the default a declaration names before detection, the install target and the "last tested"
+ * hint, and the list is the qualifier's baseline.
+ */
+export const TESTED_CODEX_CLI_VERSIONS = [
+    "0.154.0",
+    "0.157.1",
+    "0.159.2",
+    "0.159.3",
+    "0.160.0",
+];
+/**
+ * The run warning for a hosted (operator-mode) participant on a release not in
+ * TESTED_CODEX_CLI_VERSIONS, or undefined. No qualifier ran that release in operator mode, so its
+ * evidence rests on what each launch checks (open-admission design, answer C).
+ */
+export function untestedOperatorReleaseWarning(cliVersion, operator) {
+    if (!operator || cliVersion === undefined)
+        return undefined;
+    if (TESTED_CODEX_CLI_VERSIONS.includes(cliVersion))
+        return undefined;
+    return `Codex CLI ${cliVersion} has not been tested with humanish; this hosted participant's evidence rests on the checks each launch makes.`;
+}
+const CORE = "(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)";
+/**
+ * Why the launcher refuses a release: not a plain `MAJOR.MINOR.PATCH` (or longer than the 64
+ * characters parseCodexCliVersion reads), a prerelease (`-` after the core), older than the floor,
+ * or refused.
+ */
+export function codexCliRefusal(version) {
+    if (version === undefined || version.length > 64)
+        return { reason: "unrecognized" };
+    if (new RegExp(`^${CORE}-[0-9A-Za-z.-]+(?:\\+[0-9A-Za-z.-]+)?$`).test(version))
+        return { reason: "prerelease", version };
+    if (!new RegExp(`^${CORE}$`).test(version))
+        return { reason: "unrecognized" };
+    if (!isRecordedCodexCliVersion(version))
+        return { reason: "below_floor", version };
+    const refused = REFUSED_CODEX_CLI_VERSIONS.find((entry) => entry.version === version);
+    return refused === undefined
+        ? undefined
+        : { reason: "refused", version, detail: refused.reason, issue: refused.issue };
+}
+/** Whether the launcher starts this release. */
+export const admitsCodexCliVersion = (version) => codexCliRefusal(version) === undefined;
+/**
+ * Hosts where isolated launches run (the Codex-account analyst and local-browser participants).
+ * Operator launches run on every host with a native npm build (restrictedCodexNpmTarget).
+ */
+export const supportsIsolatedCodex = (platform, arch) => (platform === "linux" && arch === "x64") || (platform === "darwin" && arch === "arm64");
+/** What a declaration names before the installed CLI is detected: the newest tested release. */
+export function defaultCodexCliVersion() {
+    return TESTED_CODEX_CLI_VERSIONS.at(-1);
+}
+/** The version from `codex --version` output (`codex-cli 0.157.1`); any other shape is undefined. */
+export function parseCodexCliVersion(stdout) {
+    return /^codex-cli ([0-9][0-9A-Za-z.+-]{0,63})$/.exec(stdout.trim())?.[1];
+}
+/** Why a release is refused, as a clause; the admission rule when it is not refused. */
+function refusalClause(detected) {
+    const refusal = codexCliRefusal(detected);
+    switch (refusal?.reason) {
+        case "unrecognized":
+            return `it is not a plain MAJOR.MINOR.PATCH release; ${describeCodexCliAdmission()}`;
+        case "prerelease":
+            return "it is a prerelease, and humanish runs stable releases";
+        case "below_floor":
+            return `it is older than ${RECORDED_CODEX_CLI_FLOOR}, the oldest release humanish supports`;
+        case "refused":
+            return `humanish refuses it: ${refusal.detail} (${refusal.issue})`;
+        default:
+            return describeCodexCliAdmission();
+    }
+}
+/**
+ * doctor's recovery for a refused CLI: the release it found and where, why it is refused, and how
+ * to replace that binary with the last tested release.
+ */
+export function codexVersionRecovery(detected, installation) {
+    const found = detected === undefined
+        ? "The installed Codex CLI did not report a recognizable version"
+        : `Found Codex CLI ${detected}`;
+    const where = installation === undefined ? "" : ` at \`${installation.path}\``;
+    return `${found}${where}; ${refusalClause(detected)}. ${codexInstallAdvice(installation)} Then sign in with a ChatGPT account (\`codex login\`).`;
+}
+const inside = (file, directory) => file.startsWith(`${directory}${path.sep}`);
+/**
+ * Classifies the `codex` on `PATH` by the file it resolves to. A project's node_modules/.bin/codex
+ * resolving into that project's @openai/codex is project-local, so `npx` runs it before any global
+ * install. One inside npm's global prefix (`npm prefix -g`) is global. Anything else, such as
+ * Homebrew or a standalone download, is other.
+ */
+export function classifyCodexInstallation(found, npmGlobalPrefix) {
+    const bin = path.dirname(found.path);
+    const modules = path.dirname(bin);
+    if (path.basename(bin) === ".bin" &&
+        path.basename(modules) === "node_modules" &&
+        inside(found.resolved, path.join(modules, "@openai", "codex")))
+        return { kind: "project", path: found.path, project: path.dirname(modules) };
+    if (npmGlobalPrefix !== undefined &&
+        (found.path === path.join(npmGlobalPrefix, "bin", "codex") ||
+            inside(found.resolved, path.join(npmGlobalPrefix, "lib", "node_modules", "@openai", "codex"))))
+        return { kind: "global", path: found.path };
+    return { kind: "other", path: found.path };
+}
+/**
+ * The command that installs the last tested Codex CLI where it replaces the one humanish found:
+ * in its project for a project-local install, otherwise npm's global install.
+ */
+function codexInstallCommand(installation) {
+    const version = defaultCodexCliVersion();
+    return installation?.kind === "project"
+        ? `npm install -D @openai/codex@${version}`
+        : `npm install -g @openai/codex@${version}`;
+}
+/** One sentence: how to put the last tested Codex CLI in place of the one humanish found. */
+export function codexInstallAdvice(installation) {
+    const command = codexInstallCommand(installation);
+    switch (installation?.kind) {
+        case undefined:
+            return `Install the last tested release with \`${command}\`.`;
+        case "global":
+            return `Replace it with \`${command}\`.`;
+        case "project":
+            return `It is installed in this project: run \`${command}\` in \`${installation.project}\`, or \`npm uninstall @openai/codex\` there to use the global Codex.`;
+        case "other":
+            return `Update it with the tool that installed it, or put Codex ${defaultCodexCliVersion()} first on PATH.`;
+    }
+}
+/** For refusal messages: which releases the launcher starts, and the last tested one. */
+export function describeCodexCliAdmission() {
+    const refused = REFUSED_CODEX_CLI_VERSIONS.map((entry) => entry.version);
+    const except = refused.length === 0 ? "" : ` except ${refused.join(", ")}`;
+    return `humanish runs stable Codex CLI releases from ${RECORDED_CODEX_CLI_FLOOR}${except} (last tested: ${defaultCodexCliVersion()})`;
+}

package/dist/actors/codex/protocol-compat.d.ts

@@ -0,0 +1,27 @@
+import type { ProtocolContract } from "./protocol-contract.js";
+type Schema = boolean | Record<string, unknown>;
+/** The definitions of one generated schema, and the params definition of each method. */
+export interface ProtocolSchema {
+    readonly definitions: ReadonlyMap<string, Schema>;
+    readonly requestParams: ReadonlyMap<string, string>;
+    readonly notificationParams: ReadonlyMap<string, string>;
+}
+/** What the check found: changes that refuse the launch, and additions it only records. */
+export interface ProtocolCheck {
+    readonly incompatibilities: string[];
+    readonly additions: string[];
+}
+/**
+ * Reads the files `codex app-server generate-json-schema --experimental` writes: the v2 and full
+ * bundles for definitions, and the ClientRequest and ServerNotification unions for params.
+ */
+export declare function loadProtocolSchema(directory: string): Promise<ProtocolSchema>;
+/** A field's alternatives at `path` under a definition, or none when the field is gone. */
+export declare function resolveField(schema: ProtocolSchema, definition: string, fieldPath: string): Schema[];
+/** Checks a generated schema against the contract; any incompatibility refuses the launch. */
+export declare function checkProtocol(schema: ProtocolSchema, contract: ProtocolContract): ProtocolCheck;
+/** The refusal detail for an incompatible release. */
+export declare function protocolIncompatibilityMessage(cliVersion: string | undefined, incompatibilities: readonly string[]): string;
+/** The run warning for schema values beyond the baseline, or undefined when there were none. */
+export declare function protocolAdditionsWarning(cliVersion: string | undefined, additions: readonly string[] | undefined): string | undefined;
+export {};