humanish 0.106.1 → 0.108.0

package/dist/lab/device-presets.js

@@ -4,13 +4,13 @@
  * the per-line notes record where the two reference sims agree vs. diverge.
  */
 export const DEVICE_PRESETS = {
-    // phone — both reference sims agree
+    // phone: both reference sims agree
     mobile: { width: 414, height: 896, isMobile: true, deviceScaleFactor: 3 },
-    // small phone — both reference sims agree
+    // small phone: both reference sims agree
     "small-mobile": { width: 360, height: 740, isMobile: true, deviceScaleFactor: 3 },
     // older narrow phone
     "narrow-mobile": { width: 320, height: 700, isMobile: true, deviceScaleFactor: 2 },
-    // tablet — both reference sims agree
+    // tablet: both reference sims agree
     tablet: { width: 820, height: 1180, isMobile: false, deviceScaleFactor: 2 },
     // laptop baseline (the in-house desktop screen; close to the 1440x960 dry-run surface in
     // src/run/dry-run.ts)
@@ -20,7 +20,7 @@ export const DEVICE_PRESETS = {
 };
 /**
  * Default device for a run that does not declare one. `desktop` (1440x950) is the median
- * first-run laptop screen — the in-house desktop default, within 10px of the 1440x960 dry-run
+ * first-run laptop screen, the in-house desktop default, within 10px of the 1440x960 dry-run
  * surface in src/run/dry-run.ts. `wide` (1920x1080), the most-common external monitor, is one
  * keystroke away (`execution.desktop.device: wide`) but is deliberately not the default,
  * because the median device a first-time user arrives on is a laptop, not a 1080p monitor.
@@ -36,24 +36,24 @@ export function resolveDevicePreset(name) {
     return DEVICE_PRESETS[name ?? DEFAULT_DEVICE_PRESET];
 }
 /**
- * The narrowest browser WINDOW Chrome/Chromium will render on the E2B desktop. Chrome refuses to
+ * The narrowest browser window Chrome/Chromium will render on the E2B desktop. Chrome refuses to
  * make its window narrower than this (~500 CSS px observed: a 414-wide X screen produced a 500-wide
- * window that OVERFLOWED it, clipping the right edge of the page off-screen). So the physically
- * RENDERED screen width is floored here: a sub-500 mobile preset (mobile 414, small-mobile 360,
- * narrow-mobile 320) gets a 500-wide screen the window fits exactly — no clip. The device PRESET keeps
+ * window that overflowed it, clipping the right edge of the page off-screen). So the physically
+ * rendered screen width is floored here: a sub-500 mobile preset (mobile 414, small-mobile 360,
+ * narrow-mobile 320) gets a 500-wide screen the window fits exactly, with no clip. The device preset keeps
  * its true identity (isMobile, nominal width) for the persona prompt + metadata; only the rendered
  * screen is floored. True sub-500 CSS-viewport rendering (page laid out at 414 regardless of window
- * width, via CDP device-metric emulation) is the separate #221 upgrade.
+ * width, via CDP device-metric emulation) is the separate mobileEmulation option.
  */
 export const MIN_DESKTOP_RENDER_WIDTH = 500;
-/** Floor a screen resolution's WIDTH to what Chrome can actually render (see MIN_DESKTOP_RENDER_WIDTH). */
+/** Floor a screen resolution's width to what Chrome can actually render (see MIN_DESKTOP_RENDER_WIDTH). */
 export function floorRenderResolution(resolution) {
     return [Math.max(resolution[0], MIN_DESKTOP_RENDER_WIDTH), resolution[1]];
 }
 /**
  * Resolve a participant's device + rendered resolution (most-specific wins, exactly as the
  * single-participant path always has): a raw execution.desktop.resolution escape hatch (only legal
- * when no roster entry sets a device — XOR enforced at parse) → the participant's named device → the run-wide
+ * when no roster entry sets a device; XOR enforced at parse) → the participant's named device → the run-wide
  * execution.desktop.device → the default preset. A raw resolution is an unnamed custom desktop
  * (non-mobile, DSF 1): we never claim a named preset's mobile/DPR for hand-set geometry. The rendered
  * `resolution` is floored to MIN_DESKTOP_RENDER_WIDTH so the browser window fits its X screen (no clip);

package/dist/lab/discover.d.ts

@@ -1,7 +1,7 @@
 import type { ActorPersonaRef } from "../actors/contract.js";
 import { type LabConfig } from "./types.js";
-declare const LAB_LIST_SCHEMA = "humanish.lab-list.v1";
-declare const LAB_INSPECT_SCHEMA = "humanish.lab-inspect.v1";
+declare const STUDY_LIST_SCHEMA = "humanish.study-list.v1";
+declare const STUDY_SHOW_SCHEMA = "humanish.study-show.v1";
 type LabOrigin = "committed" | "ignored" | "explicit";
 interface ResolvedLabConfig {
     config: LabConfig;
@@ -12,9 +12,10 @@ interface ResolvedLabConfig {
 export interface LabResolveFailure {
     ok: false;
     cwd: string;
-    lab: string;
+    /** The study the caller asked for, as given. */
+    study: string;
     error: {
-        code: "HUMANISH_LAB_NOT_FOUND" | "HUMANISH_LAB_INVALID";
+        code: "HUMANISH_STUDY_NOT_FOUND" | "HUMANISH_STUDY_INVALID" | "HUMANISH_STUDY_AMBIGUOUS";
         message: string;
     };
     warnings: string[];
@@ -30,16 +31,18 @@ export interface LabListEntry {
     title?: string;
     /**
      * The manifest's own first sentence. The list is where someone decides which study to open, and a
-     * list of names cannot answer "what is this one" for a project with twenty labs in it — the
+     * list of names cannot answer "what is this one" for a project with twenty labs in it; the
      * stakeholder feedback that added this was, verbatim, "so i know wtf they are".
      */
     description?: string;
+    /** Why `run` refuses this file by name: its stem also names a file in the other directory family. */
+    error?: string;
 }
 export interface LabListResult {
-    schema: typeof LAB_LIST_SCHEMA;
+    schema: typeof STUDY_LIST_SCHEMA;
     ok: true;
     cwd: string;
-    labs: LabListEntry[];
+    studies: LabListEntry[];
     warnings: string[];
 }
 export interface LabInspectResult {
@@ -49,10 +52,11 @@ export interface LabInspectResult {
         resolved: boolean;
         brief?: ActorPersonaRef["brief"];
     }>;
-    schema: typeof LAB_INSPECT_SCHEMA;
+    schema: typeof STUDY_SHOW_SCHEMA;
     ok: boolean;
     cwd: string;
-    lab: string;
+    /** The study the caller asked for, as given. */
+    study: string;
     config?: LabConfig;
     origin?: LabOrigin;
     path?: string;

package/dist/lab/discover.js

@@ -5,15 +5,12 @@ import { lstat, open, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 import { parse } from "yaml";
 import { parseLabConfig } from "./config.js";
-import {} from "./types.js";
+import { STUDY_SCHEMA } from "./types.js";
 import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
-const LAB_LIST_SCHEMA = "humanish.lab-list.v1";
-const LAB_INSPECT_SCHEMA = "humanish.lab-inspect.v1";
-const committedLabsDir = path.join("humanish", "labs");
-const ignoredLabsDirs = [
-    path.join(".humanish", "labs"),
-    path.join(".humanish", "local", "labs"),
-];
+import { isNodeError } from "../run/type-guards.js";
+import { studyFileCandidates, studyFileStem, STUDY_DIRECTORIES } from "../study/files.js";
+const STUDY_LIST_SCHEMA = "humanish.study-list.v1";
+const STUDY_SHOW_SCHEMA = "humanish.study-show.v1";
 export async function resolveLabManifest(cwd, lab) {
     const resolvedCwd = path.resolve(cwd);
     const warnings = [];
@@ -39,16 +36,10 @@ export async function resolveLabManifest(cwd, lab) {
             contents: read.contents,
         });
     }
-    const candidates = [
-        { origin: "committed", relativePath: path.join(committedLabsDir, `${lab}.yaml`) },
-        { origin: "committed", relativePath: path.join(committedLabsDir, `${lab}.yml`) },
-        ...ignoredLabsDirs.flatMap((dir) => [
-            { origin: "ignored", relativePath: path.join(dir, `${lab}.yaml`) },
-            { origin: "ignored", relativePath: path.join(dir, `${lab}.yml`) },
-        ]),
-    ];
+    // A studies/ file wins over every labs/ file. The same stem under both families is an error, so
+    // neither file silently shadows the other.
+    const candidates = studyFileCandidates(lab);
     for (const candidate of candidates) {
-        const requestedPath = path.join(resolvedCwd, candidate.relativePath);
         const read = await readManagedManifest(projectRoot, candidate.relativePath);
         if (read.status === "missing") {
             continue;
@@ -56,11 +47,18 @@ export async function resolveLabManifest(cwd, lab) {
         if (read.status === "unsafe") {
             return invalidLab({ cwd: resolvedCwd, lab, warnings }, read.message);
         }
+        if (candidate.directory.family === "studies") {
+            for (const other of candidates.filter((entry) => entry.directory.family === "labs")) {
+                const present = await inspectManagedPath(projectRoot, other.relativePath, "file");
+                if (present.status !== "missing")
+                    return ambiguousStudy(resolvedCwd, lab, [candidate.relativePath, other.relativePath], warnings);
+            }
+        }
         return parseResolvedLab({
             cwd: resolvedCwd,
             lab,
-            origin: candidate.origin,
-            path: requestedPath,
+            origin: candidate.directory.origin,
+            path: path.join(resolvedCwd, candidate.relativePath),
             warnings,
             contents: read.contents,
         });
@@ -70,22 +68,21 @@ export async function resolveLabManifest(cwd, lab) {
 export async function listLabManifests(cwd) {
     const resolvedCwd = path.resolve(cwd);
     const warnings = [];
-    const labs = new Map();
+    const listed = new Map();
     const projectRoot = await bindProjectRoot(resolvedCwd);
     if (!projectRoot) {
         return {
-            schema: LAB_LIST_SCHEMA,
+            schema: STUDY_LIST_SCHEMA,
             ok: true,
             cwd: resolvedCwd,
-            labs: [],
-            warnings: ["Project root failed containment validation; managed lab manifests were skipped."],
+            studies: [],
+            warnings: ["Project root failed containment validation; study files were skipped."],
         };
     }
-    const dirs = [
-        { origin: "committed", relativeDir: committedLabsDir },
-        ...ignoredLabsDirs.map((relativeDir) => ({ origin: "ignored", relativeDir })),
-    ];
-    for (const entry of dirs) {
+    let legacyFiles = 0;
+    // Each stem's files by directory family, to mark the stems that name a file in both.
+    const stems = new Map();
+    for (const entry of STUDY_DIRECTORIES) {
         const directory = await bindManagedDirectory(projectRoot, entry.relativeDir);
         if (directory.status === "missing") {
             continue;
@@ -106,13 +103,15 @@ export async function listLabManifests(cwd) {
         for (const name of names.filter((value) => value.endsWith(".yaml") || value.endsWith(".yml"))) {
             let relativePath;
             try {
-                assertSafeOutputPathSegment(name, "Lab manifest name");
+                assertSafeOutputPathSegment(name, "Study file name");
                 relativePath = path.join(entry.relativeDir, name);
             }
             catch {
-                warnings.push(`${entry.relativeDir}: unsafe lab manifest name; skipped.`);
+                warnings.push(`${entry.relativeDir}: unsafe study file name; skipped.`);
                 continue;
             }
+            const stem = stemSlot(stems, studyFileStem(name) ?? name);
+            stem[entry.family === "studies" ? "studies" : "legacy"] ??= relativeToCwd(resolvedCwd, path.join(resolvedCwd, relativePath));
             const requestedPath = path.join(resolvedCwd, relativePath);
             const read = await readManagedManifest(projectRoot, relativePath);
             if (read.status !== "ok") {
@@ -131,8 +130,11 @@ export async function listLabManifests(cwd) {
                 warnings.push(`${relativeToCwd(resolvedCwd, requestedPath)}: ${parsed.error.message}`);
                 continue;
             }
+            if (legacyStudyWarning(parsed.path, parsed.config.schema) !== undefined)
+                legacyFiles += 1;
             const key = `${parsed.config.id}:${entry.origin}:${relativeToCwd(resolvedCwd, requestedPath)}`;
-            labs.set(key, {
+            stem.keys.push(key);
+            listed.set(key, {
                 id: parsed.config.id,
                 source: parsed.config.subject.source,
                 origin: entry.origin,
@@ -145,11 +147,24 @@ export async function listLabManifests(cwd) {
             });
         }
     }
+    if (legacyFiles > 0) {
+        warnings.push(`${legacyFiles === 1 ? "One study file uses" : `${legacyFiles} study files use`} humanish.lab.v2 or a labs/ directory, which 0.109 stops reading. humanish migrate converts and moves the v2 files; humanish study show names the fix for each file.`);
+    }
+    for (const [name, stem] of stems) {
+        if (stem.studies === undefined || stem.legacy === undefined)
+            continue;
+        const error = `${name} names two files, ${stem.studies} and ${stem.legacy}; running it by name fails until you delete one (humanish migrate moves a kept labs/ file).`;
+        for (const key of stem.keys) {
+            const entry = listed.get(key);
+            if (entry)
+                entry.error = error;
+        }
+    }
     return {
-        schema: LAB_LIST_SCHEMA,
+        schema: STUDY_LIST_SCHEMA,
         ok: true,
         cwd: resolvedCwd,
-        labs: [...labs.values()].sort((left, right) => `${left.origin}:${left.id}`.localeCompare(`${right.origin}:${right.id}`)),
+        studies: [...listed.values()].sort((left, right) => `${left.origin}:${left.id}`.localeCompare(`${right.origin}:${right.id}`)),
         warnings,
     };
 }
@@ -157,10 +172,10 @@ export async function inspectLabManifest(cwd, lab) {
     const resolved = await resolveLabManifest(cwd, lab);
     if (!resolved.ok) {
         return {
-            schema: LAB_INSPECT_SCHEMA,
+            schema: STUDY_SHOW_SCHEMA,
             ok: false,
             cwd: resolved.cwd,
-            lab,
+            study: lab,
             error: resolved.error,
             warnings: resolved.warnings,
         };
@@ -173,23 +188,23 @@ export async function inspectLabManifest(cwd, lab) {
         if (!(error instanceof PersonaConfigError))
             throw error;
         return {
-            schema: LAB_INSPECT_SCHEMA,
+            schema: STUDY_SHOW_SCHEMA,
             ok: false,
             cwd: path.resolve(cwd),
-            lab,
-            error: { code: "HUMANISH_LAB_INVALID", message: error.message },
+            study: lab,
+            error: { code: "HUMANISH_STUDY_INVALID", message: error.message },
             warnings: resolved.warnings,
         };
     }
     return {
-        schema: LAB_INSPECT_SCHEMA,
+        schema: STUDY_SHOW_SCHEMA,
         personas: labPersonaIds(resolved.config).map((id) => {
             const persona = personaResolution.personas.get(id);
             return { id, resolved: !!persona, ...(persona ? { brief: personaBrief(persona) } : {}) };
         }),
         ok: true,
         cwd: path.resolve(cwd),
-        lab,
+        study: lab,
         config: resolved.config,
         origin: resolved.origin,
         path: resolved.path,
@@ -202,13 +217,16 @@ function parseResolvedLab(args) {
         raw = parse(args.contents);
     }
     catch (error) {
-        return invalidLab(args, error instanceof Error ? error.message : "Lab YAML could not be parsed.");
+        return invalidLab(args, error instanceof Error ? error.message : "The study file's YAML could not be parsed.");
     }
     const parsed = parseLabConfig(raw);
     if (!parsed.ok) {
         return invalidLab(args, parsed.error.message);
     }
     const warnings = [...args.warnings, ...parsed.warnings];
+    const legacy = legacyStudyWarning(relativeToCwd(args.cwd, args.path), parsed.config.schema);
+    if (legacy !== undefined)
+        warnings.push(legacy);
     if (args.path.endsWith(".yml")) {
         warnings.push("Prefer .yaml for humanish-authored lab source; .yml is accepted for compatibility only.");
     }
@@ -220,6 +238,24 @@ function parseResolvedLab(args) {
         warnings,
     };
 }
+/**
+ * What 0.109 stops reading in this file: the humanish.lab.v2 format, a labs/ directory, or both, and
+ * what to run about it. Undefined for a v3 file outside the labs/ directories.
+ */
+function legacyStudyWarning(relativePath, schema) {
+    const retiredDirectory = STUDY_DIRECTORIES.find((directory) => directory.family === "labs" && path.dirname(relativePath) === directory.relativeDir);
+    // A file discovery parsed has one of two schemas, so not v3 is v2.
+    const v2 = schema !== STUDY_SCHEMA;
+    if (retiredDirectory !== undefined) {
+        const studies = retiredDirectory.relativeDir.replace(/labs$/, "studies");
+        return v2
+            ? `${relativePath} is a humanish.lab.v2 file in ${retiredDirectory.relativeDir}/, and 0.109 reads neither. Run humanish migrate to convert it and move it to ${studies}/.`
+            : `${relativePath} is in ${retiredDirectory.relativeDir}/, which 0.109 stops reading. Move it to ${studies}/.`;
+    }
+    return v2
+        ? `${relativePath} is a humanish.lab.v2 file, which 0.109 stops reading. Run humanish migrate ${relativePath} to convert it.`
+        : undefined;
+}
 async function bindProjectRoot(cwd) {
     try {
         const lexical = await lstat(cwd);
@@ -241,7 +277,7 @@ async function readManagedManifest(projectRoot, relativePath) {
     if (!contents) {
         return {
             status: "unsafe",
-            message: "Managed lab manifest changed or failed containment validation.",
+            message: "The study file changed or failed containment validation.",
         };
     }
     return { status: "ok", contents: contents.toString("utf8") };
@@ -263,7 +299,7 @@ async function readExplicitManifest(projectRoot, requestedPath) {
         if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n) {
             return {
                 status: "unsafe",
-                message: "Explicit lab manifest must resolve to a single-link regular file.",
+                message: "The study file path must resolve to a single-link regular file.",
             };
         }
         const handle = await open(physicalPath, constants.O_RDONLY | constants.O_NOFOLLOW);
@@ -275,7 +311,7 @@ async function readExplicitManifest(projectRoot, requestedPath) {
                 opened.ino !== before.ino) {
                 return {
                     status: "unsafe",
-                    message: "Explicit lab manifest changed before it could be read safely.",
+                    message: "The study file changed before it could be read safely.",
                 };
             }
             const contents = await handle.readFile();
@@ -292,7 +328,7 @@ async function readExplicitManifest(projectRoot, requestedPath) {
                 after.ino !== before.ino) {
                 return {
                     status: "unsafe",
-                    message: "Explicit lab manifest changed while it was being read.",
+                    message: "The study file changed while it was being read.",
                 };
             }
             return { status: "ok", contents: contents.toString("utf8") };
@@ -302,7 +338,7 @@ async function readExplicitManifest(projectRoot, requestedPath) {
         }
     }
     catch {
-        return { status: "unsafe", message: "Explicit lab manifest failed containment validation." };
+        return { status: "unsafe", message: "The study file path failed containment validation." };
     }
 }
 async function bindManagedDirectory(projectRoot, relativePath) {
@@ -326,7 +362,7 @@ async function inspectManagedPath(projectRoot, relativePath, expectedKind) {
         const segments = relativePath.replace(/\\/g, "/").split("/");
         let current = projectRoot.physicalPath;
         for (const [index, segment] of segments.entries()) {
-            assertSafeOutputPathSegment(segment, "Managed lab path segment");
+            assertSafeOutputPathSegment(segment, "Study file path segment");
             current = path.join(current, segment);
             let stats;
             try {
@@ -340,18 +376,21 @@ async function inspectManagedPath(projectRoot, relativePath, expectedKind) {
             }
             const leaf = index === segments.length - 1;
             if (stats.isSymbolicLink()) {
-                return { status: "unsafe", message: "Managed lab paths must not contain symbolic links." };
+                return {
+                    status: "unsafe",
+                    message: "Study directory paths must not contain symbolic links.",
+                };
             }
             if (!leaf && !stats.isDirectory()) {
-                return { status: "unsafe", message: "Managed lab path parents must be directories." };
+                return { status: "unsafe", message: "Study file path parents must be directories." };
             }
             if (leaf && expectedKind === "directory" && !stats.isDirectory()) {
-                return { status: "unsafe", message: "Managed lab directory has an unsafe file type." };
+                return { status: "unsafe", message: "A study directory has an unsafe file type." };
             }
             if (leaf && expectedKind === "file" && (!stats.isFile() || stats.nlink !== 1n)) {
                 return {
                     status: "unsafe",
-                    message: "Managed lab manifest must be a single-link regular file.",
+                    message: "A study file must be a single-link regular file.",
                 };
             }
             if (leaf) {
@@ -367,7 +406,7 @@ async function inspectManagedPath(projectRoot, relativePath, expectedKind) {
         }
     }
     catch {
-        return { status: "unsafe", message: "Managed lab path failed containment validation." };
+        return { status: "unsafe", message: "A study file path failed containment validation." };
     }
     return { status: "missing" };
 }
@@ -386,22 +425,44 @@ function invalidLab(args, message) {
     return {
         ok: false,
         cwd: args.cwd,
-        lab: args.lab,
+        study: args.lab,
         error: {
-            code: "HUMANISH_LAB_INVALID",
+            code: "HUMANISH_STUDY_INVALID",
             message,
         },
         warnings: args.warnings,
     };
 }
+function stemSlot(stems, name) {
+    let slot = stems.get(name);
+    if (slot === undefined) {
+        slot = { keys: [] };
+        stems.set(name, slot);
+    }
+    return slot;
+}
+/** The same stem under a studies/ and a labs/ directory: discovery reads neither. */
+function ambiguousStudy(cwd, name, paths, warnings) {
+    const [studiesPath, labsPath] = paths.map((entry) => entry.replace(/\\/g, "/"));
+    return {
+        ok: false,
+        cwd,
+        study: name,
+        error: {
+            code: "HUMANISH_STUDY_AMBIGUOUS",
+            message: `${name} names two files, ${studiesPath} and ${labsPath}. Delete the one you do not want; if you keep ${labsPath}, run humanish migrate to move it. Or pass the path of the one to run.`,
+        },
+        warnings,
+    };
+}
 function labNotFound(cwd, lab, warnings) {
     return {
         ok: false,
         cwd,
-        lab,
+        study: lab,
         error: {
-            code: "HUMANISH_LAB_NOT_FOUND",
-            message: `Lab not found: ${lab}. Look in humanish/labs/ or pass a .yaml path.`,
+            code: "HUMANISH_STUDY_NOT_FOUND",
+            message: `Study not found: ${lab}. Look in humanish/studies/ or humanish/labs/, or pass a .yaml path.`,
         },
         warnings,
     };
@@ -417,6 +478,3 @@ function relativeToCwd(cwd, filePath) {
     const relative = path.relative(cwd, filePath);
     return relative && !relative.startsWith("..") ? relative : filePath;
 }
-function isNodeError(error) {
-    return error instanceof Error && "code" in error;
-}

package/dist/lab/doctor.d.ts

@@ -1,21 +1,48 @@
 import { type LocalRuntimeStatus } from "../substrates/local/runtime.js";
 import type { LabConfig } from "./types.js";
-import type { LabRoute } from "./plan.js";
+import type { PlanResult } from "./plan-types.js";
 import type { DetectedLocalAgent } from "../actors/local-agent/cli.js";
-import type { DoctorResult } from "../cli/doctor.js";
-type Check = DoctorResult["checks"][number];
-/** Read-only Codex account readiness. An unadmitted CLI also reports the release it found. */
+import type { ReasoningEffort } from "../actors/reasoning-effort.js";
+import type { DoctorCheckDraft } from "../cli/doctor.js";
+import { type CodexInstallation } from "../actors/codex/codex-admission.js";
+import type { RefusedCodexExecutable } from "../actors/codex/restricted-executable.js";
+type Check = DoctorCheckDraft;
+/**
+ * Read-only Codex account readiness. An unadmitted CLI also reports the release it found, and an
+ * unavailable one the file humanish found and turned down.
+ */
 type CodexReadiness = {
     ready: boolean;
     errorCode: string | null;
     detectedCliVersion?: string;
+    refusedExecutable?: RefusedCodexExecutable;
+    /** Where the `codex` on `PATH` was installed, for the command that replaces it. */
+    installation?: CodexInstallation;
+    /** How the release's app-server schema differs from the fields humanish reads. */
+    protocolIncompatibilities?: readonly string[];
+    /** Schema values beyond the baseline, recorded by a launch that passed. */
+    protocolAdditions?: readonly string[];
 };
+/** What doctor's hosted Codex participant check found: a readiness result and what it admitted. */
+type HostedCodexReadiness = CodexReadiness & {
+    cliVersion?: string;
+    resolvedModel?: string;
+    authentication?: "chatgpt-account" | "api-key";
+};
+/**
+ * The hosted participant check: the operator-auth launch to an ephemeral thread, with no turn,
+ * using the lab's declared model and reasoning effort as a run would.
+ */
+declare function hostedCodexReadiness(env: NodeJS.ProcessEnv, actor: {
+    model?: string;
+    reasoningEffort?: ReasoningEffort;
+}): Promise<HostedCodexReadiness>;
 /** Shared read-only Codex account check for local participants in doctor and the TUI. */
 export declare function localCodexParticipantCheck(args: {
     env: NodeJS.ProcessEnv;
     readiness?: (env: NodeJS.ProcessEnv) => Promise<CodexReadiness>;
 }): Promise<Check>;
-interface LabSetupCheckArgs {
+export interface LabSetupCheckArgs {
     cwd: string;
     lab: string;
     env: NodeJS.ProcessEnv;
@@ -24,16 +51,31 @@ interface LabSetupCheckArgs {
     /** Internal read-only qualification seam; never a participant/model request. */
     localRuntimeReadiness?: () => Promise<LocalRuntimeStatus>;
     codexAnalysisReadiness?: (env: NodeJS.ProcessEnv) => Promise<CodexReadiness>;
+    /** The hosted Codex participant's operator handshake; tests replace it. */
+    codexParticipantReadiness?: typeof hostedCodexReadiness;
 }
-/** Setup checks only: no model turn, browser or desktop creation. CLI startup may use the network. */
+/**
+ * Setup checks only: no model turn, browser or desktop creation. CLI startup may use the network.
+ * `keys` are the keys a live run requires. `reads` are the provider keys the lab is known to read,
+ * required or not; it is undefined when that is unknown: the lab does not plan, or a declared
+ * scorer's host code may read any key.
+ */
 export declare function labSetupChecks(args: LabSetupCheckArgs): Promise<{
     desktop: boolean;
     keys: string[];
+    reads?: ReadonlySet<string>;
     checks: Check[];
 }>;
-/** Required participant provider keys, shared by doctor and the TUI. Optional analysis is separate. */
-export declare function labKeyRequirements(config: LabConfig, route: LabRoute, dryRun: boolean, keyPresent: (name: string) => boolean): {
-    desktop: boolean;
-    keys: string[];
-};
+/**
+ * The ids of the project's labs that need each provider key for a live run, from the same plan
+ * `doctor --lab` reads. Each listed manifest resolves by its path, since a file name need not match
+ * the id inside. A lab that runs dry, that the plain CLI cannot run, or that does not plan needs
+ * none.
+ */
+export declare function studiesByRequiredKey(cwd: string, keyPresent: (name: string) => boolean): Promise<Map<string, string[]>>;
+/**
+ * The lab planned with no run options, so its own scenario mode decides dry or live. Doctor and the
+ * TUI read a live run's keys and subject env from this plan's requirements.
+ */
+export declare function planCliRun(config: LabConfig, cwd: string): Promise<PlanResult>;
 export {};