humanish 0.108.0 → 0.109.0

package/dist/{lab → study}/discover.js

@@ -1,73 +1,67 @@
-import { labPersonaIds, resolveCommittedPersonasForCwd } from "./persona-resolve.js";
+import { studyPersonaIds, resolveCommittedPersonasForCwd } from "./persona-resolve.js";
 import { personaBrief, PersonaConfigError } from "./persona.js";
 import { constants } from "node:fs";
 import { lstat, open, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 import { parse } from "yaml";
-import { parseLabConfig } from "./config.js";
-import { STUDY_SCHEMA } from "./types.js";
+import { parseStudy } from "./config.js";
+import { V2_SCHEMA } from "./types.js";
 import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
 import { isNodeError } from "../run/type-guards.js";
-import { studyFileCandidates, studyFileStem, STUDY_DIRECTORIES } from "../study/files.js";
+import { studyFileCandidates, STUDY_DIRECTORIES } from "./files.js";
 const STUDY_LIST_SCHEMA = "humanish.study-list.v1";
 const STUDY_SHOW_SCHEMA = "humanish.study-show.v1";
-export async function resolveLabManifest(cwd, lab) {
+export async function resolveStudyManifest(cwd, study) {
     const resolvedCwd = path.resolve(cwd);
     const warnings = [];
     const projectRoot = await bindProjectRoot(resolvedCwd);
     if (!projectRoot) {
-        return invalidLab({ cwd: resolvedCwd, lab, warnings }, "Project root failed containment validation.");
+        return invalidStudy({ cwd: resolvedCwd, study, warnings }, "Project root failed containment validation.");
     }
-    if (labLooksLikePath(lab)) {
-        const requestedPath = path.resolve(resolvedCwd, lab);
+    if (studyLooksLikePath(study)) {
+        const requestedPath = path.resolve(resolvedCwd, study);
         const read = await readExplicitManifest(projectRoot, requestedPath);
         if (read.status === "missing") {
-            return labNotFound(resolvedCwd, lab, warnings);
+            return studyNotFound(resolvedCwd, study, warnings);
         }
         if (read.status === "unsafe") {
-            return invalidLab({ cwd: resolvedCwd, lab, warnings }, read.message);
+            return invalidStudy({ cwd: resolvedCwd, study, warnings }, read.message);
         }
-        return parseResolvedLab({
+        return parseResolvedStudy({
             cwd: resolvedCwd,
-            lab,
+            study,
             origin: "explicit",
             path: requestedPath,
             warnings,
             contents: read.contents,
         });
     }
-    // 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) {
+    // The studies/ directories are read in order. A name found only under a labs/ directory is
+    // refused with what to do about it, so the user is not told the study does not exist.
+    for (const candidate of studyFileCandidates(study)) {
         const read = await readManagedManifest(projectRoot, candidate.relativePath);
         if (read.status === "missing") {
             continue;
         }
         if (read.status === "unsafe") {
-            return invalidLab({ cwd: resolvedCwd, lab, warnings }, read.message);
+            return invalidStudy({ cwd: resolvedCwd, study, 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({
+        return parseResolvedStudy({
             cwd: resolvedCwd,
-            lab,
+            study,
             origin: candidate.directory.origin,
             path: path.join(resolvedCwd, candidate.relativePath),
             warnings,
             contents: read.contents,
+            retiredDirectory: candidate.directory.family === "labs",
         });
     }
-    return labNotFound(resolvedCwd, lab, warnings);
+    return studyNotFound(resolvedCwd, study, warnings);
 }
-export async function listLabManifests(cwd) {
+export async function listStudyManifests(cwd) {
     const resolvedCwd = path.resolve(cwd);
     const warnings = [];
+    const retired = [];
     const listed = new Map();
     const projectRoot = await bindProjectRoot(resolvedCwd);
     if (!projectRoot) {
@@ -76,12 +70,10 @@ export async function listLabManifests(cwd) {
             ok: true,
             cwd: resolvedCwd,
             studies: [],
+            retired: [],
             warnings: ["Project root failed containment validation; study files were skipped."],
         };
     }
-    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") {
@@ -97,7 +89,7 @@ export async function listLabManifests(cwd) {
             await assertManagedDirectoryBinding(projectRoot, entry.relativeDir, directory.binding);
         }
         catch {
-            warnings.push(`${entry.relativeDir}: unsafe managed lab directory; skipped.`);
+            warnings.push(`${entry.relativeDir}: unsafe managed study directory; skipped.`);
             continue;
         }
         for (const name of names.filter((value) => value.endsWith(".yaml") || value.endsWith(".yml"))) {
@@ -110,30 +102,35 @@ export async function listLabManifests(cwd) {
                 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") {
-                warnings.push(`${relativeToCwd(resolvedCwd, requestedPath)}: ${read.status === "unsafe" ? read.message : "manifest changed while it was listed; skipped."}`);
+                warnings.push(`${relativeToCwd(resolvedCwd, requestedPath)}: ${read.status === "unsafe" ? read.message : "study file changed while it was listed; skipped."}`);
                 continue;
             }
-            const parsed = parseResolvedLab({
+            const parsed = parseResolvedStudy({
                 cwd: resolvedCwd,
-                lab: name.replace(/\.(?:ya?ml)$/i, ""),
+                study: name.replace(/\.(?:ya?ml)$/i, ""),
                 origin: entry.origin,
                 path: requestedPath,
                 warnings: [],
                 contents: read.contents,
+                retiredDirectory: entry.family === "labs",
             });
             if (!parsed.ok) {
-                warnings.push(`${relativeToCwd(resolvedCwd, requestedPath)}: ${parsed.error.message}`);
+                const { code, message } = parsed.error;
+                if (code === "HUMANISH_STUDY_V2_UNSUPPORTED" ||
+                    code === "HUMANISH_STUDY_RETIRED_DIRECTORY") {
+                    // The message already starts with the file's path.
+                    retired.push({ path: relativeToCwd(resolvedCwd, requestedPath), code, message });
+                    warnings.push(message);
+                }
+                else {
+                    warnings.push(`${relativeToCwd(resolvedCwd, requestedPath)}: ${message}`);
+                }
                 continue;
             }
-            if (legacyStudyWarning(parsed.path, parsed.config.schema) !== undefined)
-                legacyFiles += 1;
             const key = `${parsed.config.id}:${entry.origin}:${relativeToCwd(resolvedCwd, requestedPath)}`;
-            stem.keys.push(key);
             listed.set(key, {
                 id: parsed.config.id,
                 source: parsed.config.subject.source,
@@ -147,42 +144,30 @@ 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: STUDY_LIST_SCHEMA,
         ok: true,
         cwd: resolvedCwd,
         studies: [...listed.values()].sort((left, right) => `${left.origin}:${left.id}`.localeCompare(`${right.origin}:${right.id}`)),
+        retired,
         warnings,
     };
 }
-export async function inspectLabManifest(cwd, lab) {
-    const resolved = await resolveLabManifest(cwd, lab);
+export async function inspectStudyManifest(cwd, study) {
+    const resolved = await resolveStudyManifest(cwd, study);
     if (!resolved.ok) {
         return {
             schema: STUDY_SHOW_SCHEMA,
             ok: false,
             cwd: resolved.cwd,
-            study: lab,
+            study,
             error: resolved.error,
             warnings: resolved.warnings,
         };
     }
     let personaResolution;
     try {
-        personaResolution = await resolveCommittedPersonasForCwd(cwd, labPersonaIds(resolved.config));
+        personaResolution = await resolveCommittedPersonasForCwd(cwd, studyPersonaIds(resolved.config));
     }
     catch (error) {
         if (!(error instanceof PersonaConfigError))
@@ -191,44 +176,45 @@ export async function inspectLabManifest(cwd, lab) {
             schema: STUDY_SHOW_SCHEMA,
             ok: false,
             cwd: path.resolve(cwd),
-            study: lab,
+            study,
             error: { code: "HUMANISH_STUDY_INVALID", message: error.message },
             warnings: resolved.warnings,
         };
     }
     return {
         schema: STUDY_SHOW_SCHEMA,
-        personas: labPersonaIds(resolved.config).map((id) => {
+        personas: studyPersonaIds(resolved.config).map((id) => {
             const persona = personaResolution.personas.get(id);
             return { id, resolved: !!persona, ...(persona ? { brief: personaBrief(persona) } : {}) };
         }),
         ok: true,
         cwd: path.resolve(cwd),
-        study: lab,
+        study,
         config: resolved.config,
         origin: resolved.origin,
         path: resolved.path,
         warnings: [...resolved.warnings, ...personaResolution.warnings],
     };
 }
-function parseResolvedLab(args) {
+function parseResolvedStudy(args) {
     let raw;
     try {
         raw = parse(args.contents);
     }
     catch (error) {
-        return invalidLab(args, error instanceof Error ? error.message : "The study file's YAML could not be parsed.");
+        return invalidStudy(args, error instanceof Error ? error.message : "The study file's YAML could not be parsed.");
+    }
+    const refusal = retiredStudyRefusal(relativeToCwd(args.cwd, args.path).replace(/\\/g, "/"), raw, args.retiredDirectory === true);
+    if (refusal !== undefined) {
+        return { ok: false, cwd: args.cwd, study: args.study, error: refusal, warnings: args.warnings };
     }
-    const parsed = parseLabConfig(raw);
+    const parsed = parseStudy(raw);
     if (!parsed.ok) {
-        return invalidLab(args, parsed.error.message);
+        return invalidStudy(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.");
+        warnings.push("Prefer .yaml for study files; .yml is accepted for compatibility only.");
     }
     return {
         ok: true,
@@ -239,22 +225,37 @@ function parseResolvedLab(args) {
     };
 }
 /**
- * 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.
+ * Why humanish refuses this file, or undefined. A humanish.lab.v2 file is refused wherever it is,
+ * and `humanish migrate` converts it (and moves it out of a labs/ directory). A v3 file is refused
+ * only when it was found by name in a labs/ directory; an explicit path to it still runs.
  */
-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;
+function retiredStudyRefusal(relativePath, raw, retiredDirectory) {
+    const directory = path.posix.dirname(relativePath);
+    const studies = directory.replace(/labs$/, "studies");
+    // migrate moves a v2 file out of a labs/ directory however the file was named.
+    const inStudies = STUDY_DIRECTORIES.some((entry) => entry.family === "labs" && entry.relativeDir.replace(/\\/g, "/") === directory);
+    // migrate refuses a path outside its --cwd, so a file outside the project gets its own directory.
+    const migrate = path.isAbsolute(relativePath)
+        ? `humanish migrate --cwd ${shellPath(path.dirname(relativePath))} ${shellPath(path.basename(relativePath))}`
+        : `humanish migrate ${shellPath(relativePath)}`;
+    if (typeof raw === "object" && raw !== null && raw.schema === V2_SCHEMA)
+        return {
+            code: "HUMANISH_STUDY_V2_UNSUPPORTED",
+            message: inStudies
+                ? `${relativePath} is a humanish.lab.v2 file in ${directory}/, which humanish no longer reads. Run ${migrate} to convert it and move it to ${studies}/.`
+                : `${relativePath} is a humanish.lab.v2 file, which humanish no longer reads. Run ${migrate} to convert it.`,
+        };
+    if (retiredDirectory)
+        return {
+            code: "HUMANISH_STUDY_RETIRED_DIRECTORY",
+            message: `${relativePath} is in ${directory}/, which humanish no longer reads. Move it to ${studies}/.`,
+        };
+    return undefined;
+}
+/** A path as one shell argument: quoted when the shell would split or expand it, never an option. */
+function shellPath(value) {
+    const arg = value.startsWith("-") ? `./${value}` : value;
+    return /^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, "'\\''")}'`;
 }
 async function bindProjectRoot(cwd) {
     try {
@@ -418,14 +419,14 @@ async function assertManagedDirectoryBinding(projectRoot, relativePath, binding)
         current.birthtimeNs !== binding.birthtimeNs ||
         current.dev !== binding.dev ||
         current.ino !== binding.ino) {
-        throw new Error("Managed lab directory identity changed after it was bound.");
+        throw new Error("Managed study directory identity changed after it was bound.");
     }
 }
-function invalidLab(args, message) {
+function invalidStudy(args, message) {
     return {
         ok: false,
         cwd: args.cwd,
-        study: args.lab,
+        study: args.study,
         error: {
             code: "HUMANISH_STUDY_INVALID",
             message,
@@ -433,46 +434,24 @@ function invalidLab(args, 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) {
+function studyNotFound(cwd, study, warnings) {
     return {
         ok: false,
         cwd,
-        study: lab,
+        study,
         error: {
             code: "HUMANISH_STUDY_NOT_FOUND",
-            message: `Study not found: ${lab}. Look in humanish/studies/ or humanish/labs/, or pass a .yaml path.`,
+            message: `Study not found: ${study}. Look in humanish/studies/, or pass a .yaml path.`,
         },
         warnings,
     };
 }
-function labLooksLikePath(lab) {
-    return (lab.endsWith(".yaml") ||
-        lab.endsWith(".yml") ||
-        lab.includes("/") ||
-        lab.includes("\\") ||
-        lab.startsWith("."));
+function studyLooksLikePath(study) {
+    return (study.endsWith(".yaml") ||
+        study.endsWith(".yml") ||
+        study.includes("/") ||
+        study.includes("\\") ||
+        study.startsWith("."));
 }
 function relativeToCwd(cwd, filePath) {
     const relative = path.relative(cwd, filePath);

package/dist/{lab → study}/doctor.d.ts

@@ -1,5 +1,5 @@
 import { type LocalRuntimeStatus } from "../substrates/local/runtime.js";
-import type { LabConfig } from "./types.js";
+import type { StudyConfig } from "./types.js";
 import type { PlanResult } from "./plan-types.js";
 import type { DetectedLocalAgent } from "../actors/local-agent/cli.js";
 import type { ReasoningEffort } from "../actors/reasoning-effort.js";
@@ -31,7 +31,7 @@ type HostedCodexReadiness = CodexReadiness & {
 };
 /**
  * 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.
+ * using the study's declared model and reasoning effort as a run would.
  */
 declare function hostedCodexReadiness(env: NodeJS.ProcessEnv, actor: {
     model?: string;
@@ -42,9 +42,9 @@ export declare function localCodexParticipantCheck(args: {
     env: NodeJS.ProcessEnv;
     readiness?: (env: NodeJS.ProcessEnv) => Promise<CodexReadiness>;
 }): Promise<Check>;
-export interface LabSetupCheckArgs {
+export interface StudySetupCheckArgs {
     cwd: string;
-    lab: string;
+    study: string;
     env: NodeJS.ProcessEnv;
     agents: DetectedLocalAgent[];
     keyPresent: (name: string) => boolean;
@@ -56,11 +56,11 @@ export interface LabSetupCheckArgs {
 }
 /**
  * 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
+ * `keys` are the keys a live run requires. `reads` are the provider keys the study is known to read,
+ * required or not; it is undefined when that is unknown: the study does not plan, or a declared
  * scorer's host code may read any key.
  */
-export declare function labSetupChecks(args: LabSetupCheckArgs): Promise<{
+export declare function studySetupChecks(args: StudySetupCheckArgs): Promise<{
     desktop: boolean;
     keys: string[];
     reads?: ReadonlySet<string>;
@@ -68,14 +68,14 @@ export declare function labSetupChecks(args: LabSetupCheckArgs): Promise<{
 }>;
 /**
  * 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
+ * `doctor --study` reads. Each listed manifest resolves by its path, since a file name need not match
+ * the id inside. A study 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
+ * The study 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 declare function planCliRun(config: StudyConfig, cwd: string): Promise<PlanResult>;
 export {};

package/dist/{lab → study}/doctor.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { isLocalBrowserLab } from "../substrates/local/runtime-config.js";
+import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
 import { localRuntimeStatus } from "../substrates/local/runtime.js";
 import { keyNamesOf, requiredKeys, requiredSubjectEnv } from "./requirements.js";
 import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.js";
@@ -40,7 +40,7 @@ async function codexAccountReadiness(env) {
 }
 /**
  * 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.
+ * using the study's declared model and reasoning effort as a run would.
  */
 async function hostedCodexReadiness(env, actor) {
     const { checkRestrictedCodexParticipantReadiness } = await import("../actors/codex/restricted-participant.js");
@@ -116,38 +116,38 @@ export async function localCodexParticipantCheck(args) {
 }
 /**
  * The discovery and planning functions doctor's study checks use, loaded on first use as
- * labSetupChecks always loaded them, so they stay out of this module's static imports.
+ * studySetupChecks always loaded them, so they stay out of this module's static imports.
  */
 async function studyLoaders() {
     const discover = await import("./discover.js");
     const plan = await import("./plan.js");
     return {
-        listStudies: discover.listLabManifests,
-        resolveStudy: discover.resolveLabManifest,
-        resolveDryRun: plan.resolveLabDryRun,
+        listStudies: discover.listStudyManifests,
+        resolveStudy: discover.resolveStudyManifest,
+        resolveDryRun: plan.resolveStudyDryRun,
         routeOf: plan.routeOf,
     };
 }
 /**
  * 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
+ * `keys` are the keys a live run requires. `reads` are the provider keys the study is known to read,
+ * required or not; it is undefined when that is unknown: the study does not plan, or a declared
  * scorer's host code may read any key.
  */
-export async function labSetupChecks(args) {
+export async function studySetupChecks(args) {
     const { resolveStudy, resolveDryRun, routeOf } = await studyLoaders();
-    const resolved = await resolveStudy(args.cwd, args.lab);
+    const resolved = await resolveStudy(args.cwd, args.study);
     if (!resolved.ok)
         return {
             desktop: false,
             keys: [],
-            checks: [{ name: "lab", ok: false, message: resolved.error.message }],
+            checks: [{ name: "study", ok: false, message: resolved.error.message }],
         };
     const config = resolved.config, route = routeOf(config);
     const dryRun = resolveDryRun(config, undefined, true) === true;
     const checks = [
         {
-            name: "lab route",
+            name: "study route",
             ok: true,
             message: `${config.id}: ${config.actors[0]?.type ?? "synthetic"} / ${route} / ${dryRun ? "dry-run (no live participant)" : "live"}`,
         },
@@ -172,7 +172,7 @@ export async function labSetupChecks(args) {
     const keys = requiredKeys(requirements, args.keyPresent);
     // This flag controls the hosted desktop SDK check as well as its API key.
     const desktop = keys.includes("E2B_API_KEY");
-    const local = isLocalBrowserLab(config);
+    const local = isLocalBrowserStudy(config);
     // One account check, shared by the local participant row and the Codex analysis row.
     let accountReadiness;
     const checkAccount = () => (accountReadiness ??= (args.codexAnalysisReadiness ?? codexAccountReadiness)(args.env).catch(() => ({ ready: false, errorCode: "codex_unavailable" })));
@@ -342,8 +342,8 @@ function checkScope(analysis) {
 }
 /**
  * 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
+ * `doctor --study` reads. Each listed manifest resolves by its path, since a file name need not match
+ * the id inside. A study that runs dry, that the plain CLI cannot run, or that does not plan needs
  * none.
  */
 export async function studiesByRequiredKey(cwd, keyPresent) {
@@ -364,16 +364,16 @@ export async function studiesByRequiredKey(cwd, keyPresent) {
     return new Map([...users].map(([key, ids]) => [key, [...ids]]));
 }
 /**
- * The lab planned with no run options, so its own scenario mode decides dry or live. Doctor and the
+ * The study 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 async function planCliRun(config, cwd) {
-    return (await import("./plan.js")).planLab(config, { cwd });
+    return (await import("./plan.js")).planStudy(config, { cwd });
 }
 function unsupportedCliRoute(config, route) {
     if (config.subject.source === "local-app")
         return "local-app needs a caller-supplied executor and provider through the library API; the plain CLI cannot run it.";
     if (route === "preview")
-        return "This route only creates synthetic evidence. Use first-run in dry-run mode or a supported live lab.";
+        return "This route only creates synthetic evidence. Use first-run in dry-run mode or a supported live study.";
     return undefined;
 }

package/dist/study/files.d.ts

@@ -20,7 +20,7 @@ export declare function studyFileStem(name: string): string | undefined;
 /**
  * The files that already use `stem` in any of the six directories, other than `except`, which is
  * the file the writer is about to replace. `exists` reads through the writer's own contained
- * filesystem checks. A writer skips or refuses when the result is not empty, so no write creates
- * the collision discovery reports.
+ * filesystem checks. A writer skips or refuses when the result is not empty, so no write leaves
+ * two files for one study name.
  */
 export declare function otherStudyFiles(stem: string, exists: (relativePath: string) => Promise<boolean>, except?: string): Promise<string[]>;

package/dist/study/files.js

@@ -1,6 +1,7 @@
-// Where study files live. Discovery reads the three studies/ directories first, then the three labs/
-// directories they replace. A name may live in one family or the other, never both, so every writer
-// checks a name against all six directories before it writes.
+// Where study files live. Discovery reads the three studies/ directories, and looks in the three
+// labs/ directories they replace only to refuse a file there with its fix. migrate reads all six.
+// Every writer checks a name against all six before it writes, so a new file never shadows another
+// study or takes the name migrate needs to move a labs/ file.
 import path from "node:path";
 /** The six directories, in resolution order. */
 export const STUDY_DIRECTORIES = [
@@ -28,8 +29,8 @@ export function studyFileStem(name) {
 /**
  * The files that already use `stem` in any of the six directories, other than `except`, which is
  * the file the writer is about to replace. `exists` reads through the writer's own contained
- * filesystem checks. A writer skips or refuses when the result is not empty, so no write creates
- * the collision discovery reports.
+ * filesystem checks. A writer skips or refuses when the result is not empty, so no write leaves
+ * two files for one study name.
  */
 export async function otherStudyFiles(stem, exists, except) {
     const found = [];

package/dist/{lab → study}/init-templates.d.ts

@@ -18,9 +18,9 @@ export declare const starterFiles: StarterFile[];
 export declare const runtimeDirectories: RuntimeDirectory[];
 export declare const humanishScripts: Record<string, string>;
 /**
- * The starter files, with the live lab written for the brain this machine can use.
+ * The starter files, with the live study written for the brain this machine can use.
  *
- * `local-agent` is not a variant of the lab so much as a different participant: on a machine with
+ * `local-agent` is not a variant of the study so much as a different participant: on a machine with
  * a signed-in Codex and no provider key, the study runs with the operator's own agent and needs
  * only E2B. Writing the other one there would hand someone homework instead of a first run.
  */