humanish 0.107.0 → 0.109.0

package/dist/cli/commands/{lab-run.js → study-run.js}

@@ -2,44 +2,45 @@ import { automaticAnalysisBudget, formatAutomaticAnalysisBudget, } from "../../a
 import { resolve } from "node:path";
 import { Command } from "commander";
 import { deriveRunFacts } from "../telemetry.js";
-import { resolveLabManifest } from "../../lab/discover.js";
-import { planLab, resolveLabDryRun } from "../../lab/plan.js";
-import { keyNamesOf } from "../../lab/requirements.js";
-import { routeOf } from "../../lab/plan.js";
-import { computerUseRouteRun } from "./lab-route-computer-use.js";
-import { runRoute } from "./lab-route-run.js";
-import { scriptedRouteRun } from "./lab-route-scripted.js";
-import { sharedWorldRouteRun } from "./lab-route-shared-world.js";
-import { previewRouteRun } from "./lab-route-preview.js";
-import { terminalRouteRun } from "./lab-route-terminal.js";
-import { maybeLoadAdapterScorer } from "./lab-scorer.js";
+import { resolveStudyManifest } from "../../study/discover.js";
+import { warnAndQueue } from "../deprecations.js";
+import { planStudy, resolveStudyDryRun } from "../../study/plan.js";
+import { keyNamesOf } from "../../study/requirements.js";
+import { routeOf } from "../../study/plan.js";
+import { computerUseRouteRun } from "./study-route-computer-use.js";
+import { runRoute } from "./study-route-run.js";
+import { scriptedRouteRun } from "./study-route-scripted.js";
+import { sharedWorldRouteRun } from "./study-route-shared-world.js";
+import { previewRouteRun } from "./study-route-preview.js";
+import { terminalRouteRun } from "./study-route-terminal.js";
+import { maybeLoadAdapterScorer } from "./study-scorer.js";
 import { discoverCliKeys, formatRunHuman, noteRunFacts, writeResult, } from "../io.js";
 import { watchExposeRequested } from "../observer-follow.js";
 import { beginRunSignalPhase } from "./run-signals.js";
 import { WATCH_SAFE_NOT_APPLICABLE_MESSAGE } from "../../observer/exposure.js";
-export async function runLabCommand(args) {
-    const resolved = await resolveLabManifest(args.options.cwd, args.lab);
+export async function runStudyCommand(args) {
+    const resolved = await resolveStudyManifest(args.options.cwd, args.study);
     if (!resolved.ok) {
-        writeResult(args.command, args.io, resolved, formatLabResolveFailureHuman);
+        writeResult(args.command, args.io, resolved, formatStudyResolveFailureHuman);
         args.io.setExitCode(2);
         return;
     }
     // Surface forward-declared-field + .yml warnings on run/watch too, not only on inspect.
     // Otherwise a setting that does nothing is silently swallowed on the path users actually run.
-    for (const warning of resolved.warnings) {
-        args.io.writeErr(`warning: ${warning}\n`);
-    }
+    // Each also goes into the JSON result's warnings[], so a --json caller sees it.
+    for (const warning of resolved.warnings)
+        warnAndQueue(args.command, args.io, warning);
     const config = resolved.config;
-    // The run's identity (#455): which manifest, where it lives, and whether it is committed, a
-    // local overlay, or an explicit path. Resolved once here — the only place that knows all three —
-    // and carried into the run's status record and bundle so the filesystem can answer "which lab
+    // The run's identity: which manifest, where it lives, and whether it is committed, a
+    // local overlay, or an explicit path. Resolved once here (the only place that knows all three)
+    // and carried into the run's status record and bundle so the filesystem can answer "which study
     // produced this run" without the old `persona.source = "lab:<id>"` string convention.
-    const lab = { id: config.id, path: resolved.path, origin: resolved.origin };
-    // Named here, once, for every route: a preview or terminal result carries no labId, so the
-    // starter lab `first-run` went unnamed in telemetry while the computer-use ones were named.
-    noteRunFacts(args.command, deriveRunFacts({ labId: config.id }));
+    const study = { id: config.id, path: resolved.path, origin: resolved.origin };
+    // Named here, once, for every route, so the starter study `first-run` is named in telemetry
+    // whatever its route's result carries.
+    noteRunFacts(args.command, deriveRunFacts({ studyId: config.id }));
     const route = routeOf(config);
-    if (route !== "computer-use" && labRerunFlagsRequested(args.options)) {
+    if (route !== "computer-use" && studyRerunFlagsRequested(args.options)) {
         writeUnsupportedRerunFlagsResult(args, route);
         return;
     }
@@ -53,7 +54,7 @@ export async function runLabCommand(args) {
             warnings: [],
             error: {
                 code: "HUMANISH_WATCH_OPTION_CONFLICT",
-                message: `--expose/--tunnel/--oauth stream a live desktop and apply only to computer-use labs; this lab resolved to the ${route} route.`,
+                message: `--expose/--tunnel/--oauth stream a live desktop and apply only to computer-use studies; this study runs on the ${route} route.`,
             },
         };
         writeResult(args.command, args.io, result, formatRunHuman);
@@ -80,8 +81,8 @@ export async function runLabCommand(args) {
     // Only a live run reads provider keys, so a dry run looks none up: no `gh auth token`, no e2b
     // login, overlay or key store. A live run fills every key it finds and prints a line only for
     // the keys its plan reads. This comes after the option refusals above, which read no key, and
-    // before the route's CLI setup and prepareLab, which do.
-    if (resolveLabDryRun(config, args.options.dryRun, true) === false) {
+    // before the route's CLI setup and prepareStudy, which do.
+    if (resolveStudyDryRun(config, args.options.dryRun, true) === false) {
         const announced = announcedKeyNames(config, args.options);
         await discoverCliKeys({
             io: args.io,
@@ -89,19 +90,19 @@ export async function runLabCommand(args) {
             ...(announced === undefined ? {} : { announced }),
         });
     }
-    // The route's CLI setup refuses bad options, runLab's plan refuses bad labs, and the route's local
+    // The route's CLI setup refuses bad options, runStudyWith's plan refuses bad labs, and the route's local
     // checks (keys, runtime auth, subject env, the local agent, caps) refuse this machine, all before
     // the scorer loads, so none imports the scorer's host code. The scripted route's checks and the
     // run-id claim still come after it; the scripted route takes no scorer.
     const routeRun = routeRunFor(route, { ...args, config });
     if (routeRun === undefined)
         return;
-    // Every route's runLab options carry the lab's provenance, from here only.
-    const run = { ...routeRun, options: { ...routeRun.options, lab } };
+    // Every route's runStudyWith options carry the study's provenance, from here only.
+    const run = { ...routeRun, options: { ...routeRun.options, study } };
     // From here a signal marks the run interrupted and reclaims its sandboxes (run-signals.ts).
     const signals = beginRunSignalPhase(args.io);
     try {
-        // #316: resolve + load a config-declared/CLI-flagged adopter scorer FAIL-CLOSED, before any
+        // Resolve + load a config-declared/CLI-flagged adopter scorer fail-closed, before any
         // spend, and only for a plan that will run. A declared gate that cannot load (bad ref, not
         // found, load failure, no hooks, unsupported route) aborts with exit 2 rather than green-passing.
         await runRoute(config, run, async () => {
@@ -125,12 +126,12 @@ export async function runLabCommand(args) {
             }
             const scorer = scorerLoad.scorer;
             if (scorer) {
-                // Cross-repo guardrail: `humanish lab run` now import()s host JS named in the manifest.
+                // Cross-repo guardrail: `humanish run` import()s host JS named in the manifest.
                 // Surface it so the invoker (who may not be the manifest author) knows executable code ran.
-                args.io.writeErr(`warning: review scorer ${scorer.provenance.ref} (${scorer.provenance.source}) is executable host code loaded and run in-process — review it as code, not config.\n`);
+                args.io.writeErr(`warning: review scorer ${scorer.provenance.ref} (${scorer.provenance.source}) is code that humanish loaded and ran in this process. Review it as you would any code you run.\n`);
             }
             const analysisBudget = automaticAnalysisBudget(config.review?.analysis, route);
-            if (analysisBudget && resolveLabDryRun(config, args.options.dryRun, true) === false) {
+            if (analysisBudget && resolveStudyDryRun(config, args.options.dryRun, true) === false) {
                 args.io.writeErr(`${formatAutomaticAnalysisBudget(analysisBudget)}\n`);
             }
             return scorer === undefined ? {} : { scorer };
@@ -146,12 +147,12 @@ export async function runLabCommand(args) {
 /**
  * The filled keys a live run prints a line for: the ones its plan reads. Count and rerun options
  * change who runs, not which keys. Undefined, so every fill is printed, when a scorer is declared,
- * since its host code may read any key, and when the lab does not plan.
+ * since its host code may read any key, and when the study does not plan.
  */
 function announcedKeyNames(config, options) {
     if (options.scorer !== undefined || config.review?.scorer !== undefined)
         return undefined;
-    const planned = planLab(config, { cwd: options.cwd, dryRun: false });
+    const planned = planStudy(config, { cwd: options.cwd, dryRun: false });
     return planned.ok ? keyNamesOf(planned.planned.plan) : undefined;
 }
 /** The route's CLI setup. Undefined when the setup has already written its own result. */
@@ -169,10 +170,10 @@ function routeRunFor(route, args) {
             return sharedWorldRouteRun(args);
         default:
             // Compile-time exhaustiveness: a future route must be handled here, not silently no-op.
-            throw new Error(`Unhandled lab route: ${String(route)}`);
+            throw new Error(`Unhandled study route: ${String(route)}`);
     }
 }
-function labRerunFlagsRequested(options) {
+function studyRerunFlagsRequested(options) {
     return options.rerunFailedFrom !== undefined || options.participants !== undefined;
 }
 function writeUnsupportedRerunFlagsResult(args, route) {
@@ -183,15 +184,13 @@ function writeUnsupportedRerunFlagsResult(args, route) {
         warnings: [],
         error: {
             code: "HUMANISH_UNSUPPORTED_RERUN_FLAGS",
-            message: `--rerun-failed-from/--participants apply only to computer-use fan-out labs; this lab resolved to the ${route} route.`,
+            message: `--rerun-failed-from/--participants apply only to computer-use studies with more than one participant; this study runs on the ${route} route.`,
         },
     };
     writeResult(args.command, args.io, result, formatRunHuman);
     args.io.setExitCode(2);
 }
-function formatLabResolveFailureHuman(result) {
-    return ([
-        `${result.error.code}: ${result.error.message}`,
-        ...result.warnings.map((warning) => `warning: ${warning}`),
-    ].join("\n") + "\n");
+function formatStudyResolveFailureHuman(result) {
+    const warnings = result.warnings.map((warning) => `warning: ${warning}\n`).join("");
+    return { ...(warnings ? { stdout: warnings } : {}), error: result.error };
 }

package/dist/cli/commands/{lab-scorer.d.ts → study-scorer.d.ts}

@@ -1,23 +1,23 @@
-import { type AdapterScorerModule } from "../../lab/adapter-scorer-loader.js";
-import type { LabRoute } from "../../lab/plan.js";
+import { type AdapterScorerModule } from "../../study/adapter-scorer-loader.js";
+import type { StudyRoute } from "../../study/plan.js";
 import type { RunScorerProvenance } from "../../run/bundle.js";
-import type { LabConfig } from "../../lab/types.js";
+import type { StudyConfig } from "../../study/types.js";
 import type { RunResult } from "../../run/results.js";
-/** A CONFIG-DECLARED scorer that resolved + loaded fail-closed, ready to thread into a backend. */
+/** A config-declared scorer that resolved + loaded fail-closed, ready to thread into a backend. */
 export interface LoadedAdapterScorer {
     hooks: AdapterScorerModule;
     provenance: RunScorerProvenance;
 }
 /**
  * Resolve `review.scorer.ref` (or the `--scorer` override) to a loaded adopter scorer, fail-closed
- * (typed error) PRE-SPEND. Precedence: CLI `--scorer` overrides the manifest; `source` records which
+ * (typed error) pre-spend. Precedence: CLI `--scorer` overrides the manifest; `source` records which
  * won. No scorer declared → `{ ok: true }` with no scorer. A declared scorer on an unsupported
  * backend, or a bad/unreadable/broken ref, → `{ ok: false }` so the caller aborts with exit 2.
  */
 export declare function maybeLoadAdapterScorer(args: {
     cwd: string;
-    config: LabConfig;
-    route: LabRoute;
+    config: StudyConfig;
+    route: StudyRoute;
     flag: string | undefined;
 }): Promise<{
     ok: true;

package/dist/cli/commands/{lab-scorer.js → study-scorer.js}

@@ -1,7 +1,7 @@
-import { loadAdapterScorer } from "../../lab/adapter-scorer-loader.js";
+import { loadAdapterScorer } from "../../study/adapter-scorer-loader.js";
 /**
  * Resolve `review.scorer.ref` (or the `--scorer` override) to a loaded adopter scorer, fail-closed
- * (typed error) PRE-SPEND. Precedence: CLI `--scorer` overrides the manifest; `source` records which
+ * (typed error) pre-spend. Precedence: CLI `--scorer` overrides the manifest; `source` records which
  * won. No scorer declared → `{ ok: true }` with no scorer. A declared scorer on an unsupported
  * backend, or a bad/unreadable/broken ref, → `{ ok: false }` so the caller aborts with exit 2.
  */

package/dist/cli/commands/study.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import { type CliIo } from "../io.js";
+export declare function registerStudyCommands(parent: Command, io: CliIo): void;

package/dist/cli/commands/study.js

@@ -0,0 +1,146 @@
+import { formatAutomaticAnalysisBudget } from "../../analysis/automatic-config.js";
+import { resolve } from "node:path";
+import { Command, Option } from "commander";
+import { inspectStudyManifest, listStudyManifests } from "../../study/discover.js";
+import { runStudyPreflight, } from "../../study/preflight.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, humanError, } from "../io.js";
+export function registerStudyCommands(parent, io) {
+    const study = parent
+        .command("study")
+        .description("List, show and check studies in humanish/studies/.");
+    listCommand(study.command("list"), io);
+    showCommand(study.command("show"), io);
+    checkCommand(study.command("check"), io);
+}
+function listCommand(command, io) {
+    command
+        .description("List the studies in this project, committed and local.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((options, command) => handleStudyList(io, options, command));
+}
+function showCommand(command, io) {
+    command
+        .argument("<study>", "Study id or .yaml path.")
+        .description("Show a study's parsed file and its warnings without running it.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((name, options, command) => handleStudyShow(io, name, options, command));
+}
+function checkCommand(command, io) {
+    command
+        .argument("<study>", "Study id or .yaml path.")
+        .description("Check the study file and, with --reachability, its named endpoints. humanish doctor --study <study> checks this machine.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .addOption(new Option("--reachability <mode>", "Reachability mode.")
+        .choices(["metadata", "public-preview", "sandbox-loopback", "prepared-host"])
+        .default("metadata"))
+        .option("--timeout-ms <ms>", "Target reachability timeout.", String(30_000))
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((name, options, command) => handleStudyCheck(io, name, options, command));
+}
+async function handleStudyList(io, options, command) {
+    const result = await listStudyManifests(options.cwd);
+    writeResult(command, io, result, formatStudyListHuman);
+    io.setExitCode(0);
+}
+async function handleStudyShow(io, name, options, command) {
+    const result = await inspectStudyManifest(options.cwd, name);
+    writeResult(command, io, result, formatStudyShowHuman);
+    io.setExitCode(result.ok ? 0 : 2);
+}
+async function handleStudyCheck(io, name, options, command) {
+    if (!(await applyEnvFileOption({
+        command,
+        cwd: options.cwd,
+        envFile: options.envFile,
+        io,
+    }))) {
+        return;
+    }
+    const timeoutMs = parsePositiveInteger(options.timeoutMs);
+    if (timeoutMs === null) {
+        const result = {
+            schema: "humanish.study-check.v1",
+            ok: false,
+            cwd: resolve(options.cwd),
+            study: name,
+            reachability: options.reachability,
+            checks: [{ name: "timeout", ok: false, message: "--timeout-ms must be a positive integer." }],
+            targets: [],
+            sandbox: { created: false },
+            spend: { e2bDesktop: false, model: false },
+            warnings: [],
+            error: {
+                code: "HUMANISH_STUDY_PREFLIGHT_INVALID_OPTION",
+                message: "--timeout-ms must be a positive integer.",
+            },
+        };
+        writeResult(command, io, result, formatStudyCheckHuman);
+        io.setExitCode(2);
+        return;
+    }
+    const result = await runStudyPreflight({
+        cwd: options.cwd,
+        study: name,
+        reachability: options.reachability,
+        timeoutMs,
+    });
+    writeResult(command, io, result, formatStudyCheckHuman);
+    io.setExitCode(result.ok ? 0 : 2);
+}
+function formatStudyListHuman(result) {
+    if (result.studies.length === 0) {
+        return ([
+            `No studies found in ${result.cwd}`,
+            "Create one under humanish/studies/*.yaml, or pass a .yaml path.",
+            ...result.warnings.map((warning) => `warning: ${warning}`),
+        ].join("\n") + "\n");
+    }
+    return ([
+        "humanish studies",
+        ...result.studies.map((study) => `- ${study.id} ${study.source} ${study.origin} ${study.path}${study.title ? ` (${study.title})` : ""}`),
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n");
+}
+function formatStudyShowHuman(result) {
+    if (!result.ok || !result.config)
+        return humanError(result.error);
+    const config = result.config;
+    return ([
+        "humanish study",
+        `id: ${config.id}`,
+        `subject: ${config.subject.source}`,
+        ...(config.execution?.target ? [`execution: ${config.execution.target}`] : []),
+        `actors: ${config.actors.map((actor) => actor.type).join(", ")}`,
+        ...(config.title ? [`title: ${config.title}`] : []),
+        ...(config.description ? [`description: ${config.description}`] : []),
+        ...(result.path ? [`path: ${result.path}`] : []),
+        ...(result.origin ? [`origin: ${result.origin}`] : []),
+        ...(config.subject.repos?.length ? [`repos: ${config.subject.repos.join(", ")}`] : []),
+        ...(result.personas ?? []).map((persona) => `persona ${persona.id}: ${persona.brief ? `authored context (before runtime additions)\n${persona.brief.text}` : "unresolved; id only"}`),
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n");
+}
+function formatStudyCheckHuman(result) {
+    const checkedTargets = result.targets.filter((target) => target.checked);
+    const reachableTargets = checkedTargets.filter((target) => target.reachable === true);
+    const blockedTargets = result.targets.filter((target) => target.status === "blocked");
+    const stdout = [
+        `humanish study check ${result.ok ? "passed" : "failed"}`,
+        `study: ${result.studyId ?? result.study}`,
+        ...(result.route ? [`route: ${result.route}`] : []),
+        `reachability: ${result.reachability}`,
+        `targets: ${checkedTargets.length ? `${reachableTargets.length}/${checkedTargets.length} reachable` : `${result.targets.length} declared, not checked`}`,
+        ...(blockedTargets.length ? [`blocked-targets: ${blockedTargets.length}`] : []),
+        `spend: ${result.spend.e2bDesktop ? "one e2b desktop, no model calls" : "none"}`,
+        ...(result.analysis ? [formatAutomaticAnalysisBudget(result.analysis)] : []),
+        ...(result.sandbox.created
+            ? [`sandbox: created=yes killed=${result.sandbox.killed === true ? "yes" : "no"}`]
+            : []),
+        ...result.checks.map((check) => `- ${check.ok ? "ok" : "fail"} ${check.name}: ${check.message}`),
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n";
+    return result.error === undefined ? stdout : { stdout, error: result.error };
+}

package/dist/cli/commands/tui.d.ts

@@ -5,7 +5,7 @@ import { type TuiModule } from "../../tui/contract.js";
 import { type CliIo } from "../io.js";
 /**
  * The pieces of the outside world the `tui` command touches. Injectable for the same reason
- * `keyDiscovery` is: the refusals ARE the behavior worth testing, and a test cannot make a real
+ * `keyDiscovery` is: the refusals are the behavior worth testing, and a test cannot make a real
  * TTY, an old Node, or a missing bundle appear.
  */
 export interface TuiRuntime {
@@ -21,12 +21,12 @@ export interface TuiRuntime {
 }
 export declare const defaultTuiRuntime: TuiRuntime;
 /**
- * The stakeholder surface (#455). Every other command is written so an agent can drive it; this one
- * is the opposite — it takes the screen and waits for a person.
+ * The stakeholder surface. Every other command is written so an agent can drive it; this one
+ * is the opposite: it takes the screen and waits for a person.
  *
  * That inversion is why it refuses rather than degrades. An agent that runs `humanish tui` with a
  * piped stdout has asked for something that cannot exist, and the useful answer is a structured
- * error naming the command that WOULD have answered the question. A TUI that quietly rendered
+ * error naming the command that would have answered the question. A TUI that quietly rendered
  * frames into a pipe would poison a transcript with escape codes and look like a hang.
  */
 export declare function registerTuiCommand(parent: Command, io: CliIo, runtime?: TuiRuntime): void;

package/dist/cli/commands/tui.js

@@ -4,22 +4,22 @@ import { Command } from "commander";
 import { setUserKey } from "../../keys/key-resolution.js";
 import { saveCommsConnection } from "../../comms/connections.js";
 import { readCommsSetup } from "../../comms/setup.js";
-import { checkCommsConnection, configureCommsLab, } from "../../comms/setup.js";
+import { checkCommsConnection, configureCommsStudy, } from "../../comms/setup.js";
 import { inspectCommsRecovery, recoverCommsReceiving } from "../../comms/receiving-recovery.js";
 import { resolveReceivingConnection } from "../../comms/receiving-runtime.js";
 import { promptSecret } from "../secret-prompt.js";
-import { runInit } from "../../lab/init.js";
-import { listLabManifests } from "../../lab/discover.js";
+import { runInit } from "../../study/init.js";
+import { listStudyManifests } from "../../study/discover.js";
 import { reclaimRunSandboxes } from "../../run/reclaim.js";
 import { RunIndexCache, readRunIndex } from "../../run/run-index.js";
-import { readLabSummary } from "../../lab/summary.js";
+import { readStudySummary } from "../../study/summary.js";
 import { readProjectState } from "../../tui/project.js";
 import { createTuiObserverSession, stopRun, TUI_ACTION_SCHEMA } from "../../tui/actions.js";
 import { readRunDetail } from "../../run/detail.js";
 import { launchRun, readLaunchLogTail } from "../../tui/launch.js";
 import { TUI_MIN_NODE_MAJOR, nodeSupportsTui, TUI_BUNDLE_URL, } from "../../tui/contract.js";
 import { detectAgentSession } from "../../actors/agent-session.js";
-import { applyEnvFileOption, CLI_VERSION, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, } from "../io.js";
+import { applyEnvFileOption, CLI_VERSION, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, } from "../io.js";
 export const defaultTuiRuntime = {
     checkComms: checkCommsConnection,
     promptSecret,
@@ -45,21 +45,21 @@ function refuseTui(command, io, refusal) {
     io.setExitCode(2);
 }
 /**
- * The stakeholder surface (#455). Every other command is written so an agent can drive it; this one
- * is the opposite — it takes the screen and waits for a person.
+ * The stakeholder surface. Every other command is written so an agent can drive it; this one
+ * is the opposite: it takes the screen and waits for a person.
  *
  * That inversion is why it refuses rather than degrades. An agent that runs `humanish tui` with a
  * piped stdout has asked for something that cannot exist, and the useful answer is a structured
- * error naming the command that WOULD have answered the question. A TUI that quietly rendered
+ * error naming the command that would have answered the question. A TUI that quietly rendered
  * frames into a pipe would poison a transcript with escape codes and look like a hang.
  */
 export function registerTuiCommand(parent, io, runtime = defaultTuiRuntime) {
     parent
         .command("tui")
-        .description("Open the interactive terminal surface for browsing labs and runs (humans only).")
-        .summary("Human terminal for labs and runs; refuses detected agent sessions and non-TTY input/output. Agents: humanish lab list --json, humanish lab inspect <lab> --json, humanish runs --json.")
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--env-file <path>", "Load a local env file for this terminal session and its runs without printing values.")
+        .description("Browse studies and runs in an interactive terminal UI. It refuses detected agent sessions and non-TTY input or output; agents use humanish study list --json, humanish study show <study> --json and humanish runs --json.")
+        .summary("Browse studies and runs in a terminal UI for people.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
         .option("--force", "Open it anyway in a session that looks like an agent's.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleTui(io, runtime, options, command));
@@ -70,7 +70,7 @@ async function handleTui(io, runtime, options, command) {
         refuseTui(command, io, refusal);
         return;
     }
-    // The Ink app ships as a pre-built bundle beside the compiled CLI and is loaded ONLY here, so
+    // The Ink app ships as a pre-built bundle beside the compiled CLI and is loaded only here, so
     // no agent-facing command pays its parse cost.
     const bundle = TUI_BUNDLE_URL;
     const loaded = await runtime.loadTui(bundle);
@@ -80,7 +80,7 @@ async function handleTui(io, runtime, options, command) {
             ok: false,
             error: {
                 code: "HUMANISH_TUI_BUNDLE_MISSING",
-                message: `The terminal surface bundle is missing at ${bundle.pathname}. In a checkout, run \`pnpm build\`; in an install, this package is incomplete — please report it.`,
+                message: `The terminal surface bundle is missing at ${bundle.pathname}. In a checkout, run \`pnpm build\`; an installed package always ships it, so please report this as a bug.`,
             },
         });
         return;
@@ -102,12 +102,12 @@ async function handleTui(io, runtime, options, command) {
 }
 /** The refusal for a session the surface cannot serve, or undefined when it may open. */
 function checkTuiSession(runtime, force) {
-    // An agent runner, even with a real terminal. `codex exec` allocates a PTY for the commands
-    // it runs, so the TTY check below passes and the surface used to open: a study watched an
-    // agent navigate the labs list and start a run it did not mean to start
-    // (humanish/labs/handed-a-human-surface.yaml). A TTY says a terminal exists, not that anyone is
-    // reading it. `--force` is the escape for the person who really is at this keyboard —
-    // capturing frames from inside an agent session is exactly that case.
+    // An agent runner, even with a real terminal. `codex exec` allocates a PTY for the commands it
+    // runs, so the TTY check below passes for an agent too, and an agent in the surface can start a
+    // run it did not mean to start (humanish/studies/handed-a-human-surface.yaml records one). A TTY
+    // says a terminal exists, not that anyone is reading it. `--force` is the escape for the person
+    // who really is at this keyboard, and capturing frames from inside an agent session is exactly
+    // that case.
     const agent = force ? undefined : detectAgentSession(runtime.env);
     if (agent !== undefined) {
         return {
@@ -117,8 +117,8 @@ function checkTuiSession(runtime, force) {
                 code: "HUMANISH_TUI_AGENT_SESSION",
                 message: `humanish tui is a surface for a person, and ${agent.marker} says this session belongs to ${agent.runner}. ` +
                     "It renders frames of escape codes into a transcript, and its keys can start runs. " +
-                    "`humanish runs --json` lists runs, `humanish lab list --json` lists the labs in this project, " +
-                    "and `humanish lab run <lab> --json` starts one. If you are a person at this keyboard, add --force.",
+                    "`humanish runs --json` lists runs, `humanish study list --json` lists the studies in this project, " +
+                    "and `humanish run <study> --json` starts one. If you are a person at this keyboard, add --force.",
             },
         };
     }
@@ -128,7 +128,7 @@ function checkTuiSession(runtime, force) {
             ok: false,
             error: {
                 code: "HUMANISH_TUI_REQUIRES_TTY",
-                message: "humanish tui needs an interactive terminal. For scripted or agent use, `humanish runs --json` lists the same runs and `humanish lab run --json` starts one.",
+                message: "humanish tui needs an interactive terminal. For scripted or agent use, `humanish runs --json` lists the same runs and `humanish run <study> --json` starts one.",
             },
         };
     }
@@ -210,13 +210,13 @@ function tuiCapabilities(session) {
                 });
                 return session.connectionCheck;
             },
-            labs: async () => (await listLabManifests(cwd)).labs.map((lab) => ({
-                title: lab.title ?? lab.id,
-                path: lab.path,
+            studies: async () => (await listStudyManifests(cwd)).studies.map((study) => ({
+                title: study.title ?? study.id,
+                path: study.path,
             })),
-            configure: (lab, apply, planToken) => configureCommsLab({
+            configure: (study, apply, planToken) => configureCommsStudy({
                 cwd,
-                lab,
+                study,
                 connection: "agentmail",
                 apply,
                 ...(planToken ? { planToken } : {}),
@@ -244,11 +244,11 @@ function tuiCapabilities(session) {
         // One cache for the life of the surface: it refreshes on a cadence, and re-walking every
         // run tree each tick is the cost this index exists to avoid.
         readRunIndex: (target, readOptions) => readRunIndex(target, { ...readOptions, cache: runIndexCache }),
-        listLabs: listLabManifests,
+        listStudies: listStudyManifests,
         startRun: (launchOptions) => launchRun({ ...launchOptions, env: sessionEnv }),
         readLaunchLog: readLaunchLogTail,
         readRunDetail,
-        readLabSummary: (target, lab, readOptions) => readLabSummary(target, lab, { ...readOptions, env: sessionEnv }),
+        readStudySummary: (target, study, readOptions) => readStudySummary(target, study, { ...readOptions, env: sessionEnv }),
         readProjectState,
         openObserver: (target, observerPath) => observerSession.open(target, observerPath),
         reclaimRun: (target, runId) => reclaimRunSandboxes(target, runId),
@@ -259,7 +259,7 @@ function tuiCapabilities(session) {
                 ? {
                     schema: TUI_ACTION_SCHEMA,
                     ok: true,
-                    message: `set up humanish here — ${result.changes.filter((change) => change.action !== "skip").length} files written`,
+                    message: `set up humanish here: ${result.changes.filter((change) => change.action !== "skip").length} files written`,
                 }
                 : {
                     schema: TUI_ACTION_SCHEMA,