humanish 0.108.0 → 0.109.1

package/dist/analysis/execute.d.ts

@@ -3,7 +3,7 @@ import { type AnalysisFetch, type AnalysisProvider } from "./provider.js";
 import type { RejectedAnalysisOutput } from "./diagnostics.js";
 export declare const ANALYSIS_PROMPT_VERSION = "study-evidence-6";
 export declare const isSupportedAnalysisModel: (model: string) => boolean;
-/** The OpenAI output limit when a lab omits maxOutputTokens, and the most it may ask for. */
+/** The OpenAI output limit when a study omits maxOutputTokens, and the most it may ask for. */
 export declare const DEFAULT_ANALYSIS_MAX_OUTPUT_TOKENS = 16384;
 export declare const MAX_ANALYSIS_OUTPUT_TOKENS = 32768;
 export interface AnalysisAdmission {

package/dist/analysis/execute.js

@@ -21,7 +21,7 @@ const SUPPORTED_ANALYSIS_MODELS = Object.freeze([
 ]);
 const SUPPORTED_MODELS = new Set(SUPPORTED_ANALYSIS_MODELS);
 export const isSupportedAnalysisModel = (model) => SUPPORTED_MODELS.has(model);
-/** The OpenAI output limit when a lab omits maxOutputTokens, and the most it may ask for. */
+/** The OpenAI output limit when a study omits maxOutputTokens, and the most it may ask for. */
 export const DEFAULT_ANALYSIS_MAX_OUTPUT_TOKENS = 16_384;
 export const MAX_ANALYSIS_OUTPUT_TOKENS = 32_768;
 const MAX_EVIDENCE_BYTES = 1024 * 1024;

package/dist/analysis/types.d.ts

@@ -1,6 +1,7 @@
 import type { ActorStatus, ActorCompletionReason, ActorStopCause, ParticipantDeclaredOutcome } from "../actors/contract.js";
 import type { CuaGoalSource } from "../actors/goal-source.js";
 import type { AutomaticAnalysisView } from "./job.js";
+import type { RunAnalysisCost } from "../run/run-cost.js";
 /** Independent interpretation of retained evidence; never a participant or harness verdict. */
 export declare const ANALYSIS_SCHEMA: "humanish.study-analysis.v1";
 export declare const ANALYSIS_CORRECTION_SCHEMA: "humanish.study-analysis-correction.v1";
@@ -213,5 +214,10 @@ export interface LoadedAnalysis {
     warnings: string[];
     /** Independent post-run execution metadata; never changes evidence sharing grades. */
     automatic?: AutomaticAnalysisView;
+    /**
+     * What the run's analysis requests cost, every attempt counted once (src/run/costs.ts
+     * readAnalysisAccounting, the reader stats uses). Absent when the run sent none.
+     */
+    spend?: RunAnalysisCost;
 }
 export {};

package/dist/browser-control/client.js

@@ -1,4 +1,4 @@
-import { CuaExecutorError, } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError, } from "../actors/computer-use/executor-error.js";
 import { BROWSER_CONTROL_LIMITS, BROWSER_CONTROL_VERSION, decodeBrowserControlObservation, parseBrowserControlReply, sameBrowserControlIdentity, validateBrowserControlAction, validateBrowserControlIdentity, } from "./protocol.js";
 import { BrowserControlTransport } from "./transport.js";
 import { receiveBrowserControlRecording } from "./recording-transfer.js";
@@ -8,7 +8,7 @@ export function createBrowserControlClient(options) {
     if (!Number.isFinite(timeoutMs) ||
         timeoutMs < 1 ||
         timeoutMs > BROWSER_CONTROL_LIMITS.maxRequestTimeoutMs)
-        throw new CuaExecutorError("invalid_request", "not_dispatched");
+        throw new ComputerUseExecutorError("invalid_request", "not_dispatched");
     const state = {
         identity,
         timeoutMs,
@@ -47,7 +47,7 @@ function closeClient(state, code) {
     state.pending = undefined;
     if (operation) {
         operation.dispose();
-        operation.reject(new CuaExecutorError(code, operation.written ? "outcome_uncertain" : "not_dispatched"));
+        operation.reject(new ComputerUseExecutorError(code, operation.written ? "outcome_uncertain" : "not_dispatched"));
     }
 }
 /** Settles the pending exchange once both its reply has arrived and its request write finished. */
@@ -68,7 +68,7 @@ function finishExchange(session) {
             code !== "action_rejected" ||
             disposition !== "not_dispatched")
             session.transport.close(code);
-        operation.reject(new CuaExecutorError(code, disposition));
+        operation.reject(new ComputerUseExecutorError(code, disposition));
     }
 }
 /** Matches a reply frame to the pending request; any mismatch closes the channel. */
@@ -120,12 +120,12 @@ function acceptReply(session, value) {
 function exchange(session, operation, action, signal, destination) {
     const { transport } = session;
     if (session.closed)
-        return Promise.reject(new CuaExecutorError("executor_closed", "not_dispatched"));
+        return Promise.reject(new ComputerUseExecutorError("executor_closed", "not_dispatched"));
     if (signal?.aborted)
-        return Promise.reject(new CuaExecutorError("cancelled", "not_dispatched"));
+        return Promise.reject(new ComputerUseExecutorError("cancelled", "not_dispatched"));
     if (session.seq >= Number.MAX_SAFE_INTEGER) {
         transport.close("protocol_mismatch");
-        return Promise.reject(new CuaExecutorError("protocol_mismatch", "not_dispatched"));
+        return Promise.reject(new ComputerUseExecutorError("protocol_mismatch", "not_dispatched"));
     }
     session.seq += 1;
     const seq = session.seq;
@@ -174,9 +174,9 @@ function exchange(session, operation, action, signal, destination) {
 /** Runs one public operation at a time on an open client. */
 async function withOperation(session, work) {
     if (session.closed)
-        throw new CuaExecutorError("executor_closed", "not_dispatched");
+        throw new ComputerUseExecutorError("executor_closed", "not_dispatched");
     if (session.busy)
-        throw new CuaExecutorError("executor_busy", "not_dispatched");
+        throw new ComputerUseExecutorError("executor_busy", "not_dispatched");
     session.busy = true;
     try {
         return await work();
@@ -202,34 +202,34 @@ async function observe(session) {
     }
     catch {
         session.transport.close("invalid_response");
-        throw new CuaExecutorError("invalid_response", "outcome_uncertain");
+        throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
     }
 }
 async function execute(session, action, signal) {
     const validAction = validateBrowserControlAction(action);
     if (validAction.kind === "speak" && !session.speechEnabled) {
-        throw new CuaExecutorError("action_rejected", "not_dispatched");
+        throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
     }
     if (signal?.aborted)
-        throw new CuaExecutorError("cancelled", "not_dispatched");
+        throw new ComputerUseExecutorError("cancelled", "not_dispatched");
     try {
         await hello(session, signal);
     }
     catch (error) {
-        if (error instanceof CuaExecutorError)
-            throw new CuaExecutorError(error.code, "not_dispatched");
+        if (error instanceof ComputerUseExecutorError)
+            throw new ComputerUseExecutorError(error.code, "not_dispatched");
         throw error;
     }
     await exchange(session, "EXECUTE", validAction, signal);
 }
 async function finishRecording(session, destination) {
     if (!destination || destination.destroyed)
-        throw new CuaExecutorError("invalid_request", "not_dispatched");
+        throw new ComputerUseExecutorError("invalid_request", "not_dispatched");
     try {
         await hello(session);
         const reply = await exchange(session, "FINISH_RECORDING", undefined, undefined, destination);
         if (!reply.ok || !reply.recording)
-            throw new CuaExecutorError("invalid_response", "outcome_uncertain");
+            throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
         return reply.recording;
     }
     catch (error) {

package/dist/browser-control/dispatcher.js

@@ -1,4 +1,4 @@
-import { CuaExecutorError } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError } from "../actors/computer-use/executor-error.js";
 import { BROWSER_CONTROL_LIMITS, BROWSER_CONTROL_VERSION, encodeBrowserControlObservation, parseBrowserControlRequest, safeBrowserControlFailure, sameBrowserControlIdentity, validateBrowserControlIdentity, } from "./protocol.js";
 import { BrowserControlTransport } from "./transport.js";
 import { sendBrowserControlRecording } from "./recording-transfer.js";
@@ -103,7 +103,7 @@ function failure(common, error, invoked) {
 async function dispatch(session, request, signal) {
     const common = replyCommon(session.identity, request);
     if (!authorized(session.options) || signal.aborted) {
-        const refusal = new CuaExecutorError("session_revoked", "not_dispatched");
+        const refusal = new ComputerUseExecutorError("session_revoked", "not_dispatched");
         await sendReply(session, request, failure(common, refusal, false));
         return;
     }
@@ -160,7 +160,7 @@ async function execute(session, request, common, signal) {
     let invoked = false, reply;
     try {
         if (request.action.kind === "speak" && session.options.executor.speechEnabled !== true) {
-            throw new CuaExecutorError("action_rejected", "not_dispatched");
+            throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
         }
         // No await between the owner gate in dispatch and invocation. The physical driver must
         // check this signal again immediately before each actual input after preparation.
@@ -183,7 +183,7 @@ async function finishRecording(session, request, common, signal) {
     let reply;
     try {
         if (!options.finishRecording)
-            throw new CuaExecutorError("action_rejected", "not_dispatched");
+            throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
         const recording = await options.finishRecording();
         let metadata;
         try {

package/dist/browser-control/protocol.js

@@ -1,7 +1,7 @@
 import { PNG } from "pngjs";
 import { z } from "zod";
 import { CUA_SPEECH_LIMITS } from "../actors/computer-use/speech.js";
-import { CuaExecutorError, isCuaExecutorError, } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError, isComputerUseExecutorError, } from "../actors/computer-use/executor-error.js";
 import { desktopRecordingMetadataSchema } from "../evidence/desktop-recording-types.js";
 export const BROWSER_CONTROL_VERSION = 1;
 export const BROWSER_CONTROL_LIMITS = Object.freeze({
@@ -219,7 +219,7 @@ const replySchema = z.discriminatedUnion("ok", [
 export function validateBrowserControlIdentity(value) {
     const parsed = identitySchema.safeParse(value);
     if (!parsed.success)
-        throw new CuaExecutorError("invalid_request", "not_dispatched");
+        throw new ComputerUseExecutorError("invalid_request", "not_dispatched");
     return parsed.data;
 }
 export function sameBrowserControlIdentity(a, b) {
@@ -230,41 +230,41 @@ export function sameBrowserControlIdentity(a, b) {
 export function parseBrowserControlRequest(value) {
     const parsed = requestSchema.safeParse(value);
     if (!parsed.success)
-        throw new CuaExecutorError("invalid_request", "not_dispatched");
+        throw new ComputerUseExecutorError("invalid_request", "not_dispatched");
     const request = parsed.data;
     if (request.requestId !== `request-${request.seq}` ||
         (request.operation === "EXECUTE" && request.actionId !== `action-${request.seq}`))
-        throw new CuaExecutorError("invalid_request", "not_dispatched");
+        throw new ComputerUseExecutorError("invalid_request", "not_dispatched");
     return request;
 }
 export function parseBrowserControlReply(value) {
     const parsed = replySchema.safeParse(value);
     if (!parsed.success)
-        throw new CuaExecutorError("invalid_response", "outcome_uncertain");
+        throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
     const reply = parsed.data;
     if ((reply.operation === "EXECUTE") !== (reply.actionId !== undefined) ||
         (reply.ok &&
             ((reply.operation === "OBSERVE") !== (reply.observation !== undefined) ||
                 (reply.operation === "FINISH_RECORDING") !== (reply.recording !== undefined))))
-        throw new CuaExecutorError("invalid_response", "outcome_uncertain");
+        throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
     return reply;
 }
 export function validateBrowserControlAction(value) {
     const parsed = wireActionSchema.safeParse(value);
     if (!parsed.success)
-        throw new CuaExecutorError("invalid_request", "not_dispatched");
+        throw new ComputerUseExecutorError("invalid_request", "not_dispatched");
     return parsed.data;
 }
 export function validateHeardSpeech(value) {
     const parsed = heardSpeechListSchema.safeParse(value);
     if (!parsed.success)
-        throw new CuaExecutorError("invalid_response", "outcome_uncertain");
+        throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
     return parsed.data;
 }
 /** Check dimensions before allocating decoder output; v1 accepts browser-style 8-bit, noninterlaced PNG. */
 export function validateBrowserControlPng(bytes) {
     const fail = () => {
-        throw new CuaExecutorError("invalid_response", "outcome_uncertain");
+        throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
     };
     if (bytes.length < 45 ||
         bytes.length > BROWSER_CONTROL_LIMITS.pngBytes ||
@@ -316,7 +316,7 @@ export function encodeBrowserControlObservation(observation) {
     if (!observation ||
         observation.appState !== undefined ||
         !Buffer.isBuffer(observation.screenshot))
-        throw new CuaExecutorError("invalid_response", "outcome_uncertain");
+        throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
     validateBrowserControlPng(observation.screenshot);
     const parsed = observationSchema.safeParse({
         png: observation.screenshot.toString("base64"),
@@ -328,17 +328,17 @@ export function encodeBrowserControlObservation(observation) {
         ...(observation.heardSpeech !== undefined ? { heardSpeech: observation.heardSpeech } : {}),
     });
     if (!parsed.success)
-        throw new CuaExecutorError("invalid_response", "outcome_uncertain");
+        throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
     return parsed.data;
 }
 export function decodeBrowserControlObservation(value) {
     const parsed = observationSchema.safeParse(value);
     if (!parsed.success)
-        throw new CuaExecutorError("invalid_response", "outcome_uncertain");
+        throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
     const { png, ...state } = parsed.data;
     const screenshot = Buffer.from(png, "base64");
     if (screenshot.toString("base64") !== png)
-        throw new CuaExecutorError("invalid_response", "outcome_uncertain");
+        throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
     validateBrowserControlPng(screenshot);
     return {
         screenshot,
@@ -351,7 +351,7 @@ export function decodeBrowserControlObservation(value) {
     };
 }
 export function safeBrowserControlFailure(error, dispatched) {
-    if (isCuaExecutorError(error))
+    if (isComputerUseExecutorError(error))
         return { code: error.code, disposition: error.disposition };
     return {
         code: "action_rejected",

package/dist/browser-control/recording-transfer.js

@@ -1,6 +1,6 @@
 import { Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
-import { CuaExecutorError } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError } from "../actors/computer-use/executor-error.js";
 import { DESKTOP_RECORDING_MAX_BYTES } from "../evidence/desktop-recording-types.js";
 const BROWSER_CONTROL_RECORDING_TRANSFER_TIMEOUT_MS = 120_000;
 function exactBytes(expected) {
@@ -17,7 +17,7 @@ function exactBytes(expected) {
 }
 function validLength(bytes) {
     if (!Number.isSafeInteger(bytes) || bytes < 1 || bytes > DESKTOP_RECORDING_MAX_BYTES) {
-        throw new CuaExecutorError("invalid_response", "outcome_uncertain");
+        throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
     }
 }
 export async function receiveBrowserControlRecording(source, destination, bytes) {
@@ -28,7 +28,7 @@ export async function receiveBrowserControlRecording(source, destination, bytes)
         });
     }
     catch {
-        throw new CuaExecutorError("transport_failed", "outcome_uncertain");
+        throw new ComputerUseExecutorError("transport_failed", "outcome_uncertain");
     }
 }
 export async function sendBrowserControlRecording(source, destination, bytes) {
@@ -43,6 +43,6 @@ export async function sendBrowserControlRecording(source, destination, bytes) {
     }
     catch {
         destination.destroy();
-        throw new CuaExecutorError("transport_failed", "outcome_uncertain");
+        throw new ComputerUseExecutorError("transport_failed", "outcome_uncertain");
     }
 }

package/dist/browser-control/transport.js

@@ -1,6 +1,6 @@
 import { TextDecoder } from "node:util";
 import { BROWSER_CONTROL_LIMITS } from "./protocol.js";
-import { CuaExecutorError, } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError, } from "../actors/computer-use/executor-error.js";
 /** Owned byte channel only. This module never discovers endpoints or reconnects. */
 export class BrowserControlTransport {
     stream;
@@ -92,7 +92,7 @@ export class BrowserControlTransport {
     /** Relinquish the live byte stream synchronously after a complete frame. */
     handoff() {
         if (this.ended || this.handedOff || this.payload !== undefined || this.headerUsed !== 0) {
-            throw new CuaExecutorError("transport_failed", "outcome_uncertain");
+            throw new ComputerUseExecutorError("transport_failed", "outcome_uncertain");
         }
         this.handedOff = true;
         clearTimeout(this.frameTimer);
@@ -112,9 +112,9 @@ export class BrowserControlTransport {
     };
     send(value, beforeWrite = () => { }) {
         if (this.ended || this.handedOff)
-            return Promise.reject(new CuaExecutorError("executor_closed", "not_dispatched"));
+            return Promise.reject(new ComputerUseExecutorError("executor_closed", "not_dispatched"));
         if (this.sending)
-            return Promise.reject(new CuaExecutorError("executor_busy", "not_dispatched"));
+            return Promise.reject(new ComputerUseExecutorError("executor_busy", "not_dispatched"));
         let payload;
         try {
             const json = JSON.stringify(value);
@@ -123,7 +123,7 @@ export class BrowserControlTransport {
             payload = Buffer.from(json);
         }
         catch {
-            return Promise.reject(new CuaExecutorError("invalid_request", "not_dispatched"));
+            return Promise.reject(new ComputerUseExecutorError("invalid_request", "not_dispatched"));
         }
         const frame = Buffer.allocUnsafe(4 + payload.length);
         frame.writeUInt32BE(payload.length);
@@ -144,7 +144,7 @@ export class BrowserControlTransport {
             try {
                 beforeWrite();
                 if (this.ended) {
-                    done(new CuaExecutorError("executor_closed", "not_dispatched"));
+                    done(new ComputerUseExecutorError("executor_closed", "not_dispatched"));
                     return;
                 }
                 this.stream.write(frame, (error) => {
@@ -178,7 +178,7 @@ export class BrowserControlTransport {
             this.stream.off("close", releaseListeners);
         };
         this.stream.once("close", releaseListeners);
-        this.pendingWrite?.(new CuaExecutorError(code, "outcome_uncertain"));
+        this.pendingWrite?.(new ComputerUseExecutorError(code, "outcome_uncertain"));
         this.stream.destroy();
         // A stream whose close event already happened will not emit it again. `closed`
         // can also precede queued error/close events, so defer removal past native ticks.

package/dist/cli/commands/analysis-signals.d.ts

@@ -1,8 +1,8 @@
-import type { RunLabOptions } from "../../run-lab.js";
+import type { RunStudyOptions } from "../../run-study.js";
 import type { CliIo } from "../io.js";
 /**
  * Post-run analysis cancellation for the CLI: while analysis runs, SIGINT, SIGTERM and SIGHUP abort
  * it. The listeners exist only during analysis; before it, the run's own handlers
  * (run-signals.ts) hold the signals and hand them over here.
  */
-export declare function cliAnalysisOptions(io: Pick<CliIo, "writeErr">): Pick<RunLabOptions, "onEvent" | "analysisSignal">;
+export declare function cliAnalysisOptions(io: Pick<CliIo, "writeErr">): Pick<RunStudyOptions, "onEvent" | "analysisSignal">;

package/dist/cli/commands/comms.js

@@ -3,11 +3,10 @@ import { Command } from "commander";
 import { COMMS_PROVIDERS, saveCommsConnection } from "../../comms/connections.js";
 import { catchTokenRefusal } from "../../comms/external-evidence.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 { resolveLabManifest } from "../../lab/discover.js";
-import { oldStudyOption, studyOptionValue } from "../deprecations.js";
+import { resolveStudyManifest } from "../../study/discover.js";
 import { runCommsCatchHost } from "../../comms/catch-host.js";
 import { DEFAULT_SANDBOX_CATCH_PORT } from "../../comms/sandbox-catch.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, PORT_OPTION_DESCRIPTION, writeResult, messageOutput, } from "../io.js";
@@ -46,7 +45,6 @@ export function registerCommsCommands(parent, io) {
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--connection <name>", "Saved connection name.", "agentmail")
         .option("--study <path>", "Check the connection this study selects.")
-        .addOption(oldStudyOption("path"))
         .option("--online", "Make a read-only provider authentication request.")
         .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
         .option("--json", JSON_OPTION_DESCRIPTION)
@@ -54,20 +52,12 @@ export function registerCommsCommands(parent, io) {
     comms
         .command("configure")
         .description("Preview or save a local receiving-enabled copy of a supported study. No provider requests.")
-        // Required, but checked in the action, so --lab still works for one minor.
-        .option("--study <path>", "Source study path or name. Required.")
-        .addOption(oldStudyOption("path"))
+        .requiredOption("--study <path>", "Source study path or name. Required.")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--connection <name>", "Saved connection name.", "agentmail")
         .option("--apply", "Save the local copy; the source study stays unchanged.")
         .option("--plan-token <digest>", "Require the source and destination to match a previous preview.")
         .option("--json", JSON_OPTION_DESCRIPTION)
-        .hook("preAction", (command) => {
-        const options = command.opts();
-        // The message commander gives a missing required option.
-        if (options.study === undefined && options.lab === undefined)
-            command.error("error: required option '--study <path>' not specified");
-    })
         .action((options, command) => handleCommsConfigure(io, options, command));
     comms
         .command("recover")
@@ -119,13 +109,19 @@ async function handleCommsCheck(io, options, command) {
     if (!(await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io })))
         return;
     let connection = options.connection;
-    const study = studyOptionValue(command, io, options);
+    const study = options.study;
     if (study) {
-        const resolved = await resolveLabManifest(options.cwd, study);
+        const resolved = await resolveStudyManifest(options.cwd, study);
         if (!resolved.ok || resolved.config.comms?.email?.kind !== "real") {
+            // A file humanish no longer reads gets discovery's message, which names the fix.
+            const named = !resolved.ok &&
+                (resolved.error.code === "HUMANISH_STUDY_V2_UNSUPPORTED" ||
+                    resolved.error.code === "HUMANISH_STUDY_RETIRED_DIRECTORY");
             const result = {
                 ok: false,
-                message: "This study does not select a real email connection.",
+                message: named
+                    ? resolved.error.message
+                    : "This study does not select a real email connection.",
             };
             writeResult(command, io, result, messageOutput);
             io.setExitCode(2);
@@ -143,13 +139,9 @@ async function handleCommsCheck(io, options, command) {
     io.setExitCode(result.ok ? 0 : 2);
 }
 async function handleCommsConfigure(io, options, command) {
-    const study = studyOptionValue(command, io, options);
-    // The preAction hook refuses a call without either option.
-    if (study === undefined)
-        return;
-    const result = await configureCommsLab({
+    const result = await configureCommsStudy({
         cwd: resolve(options.cwd),
-        lab: study,
+        study: options.study,
         connection: options.connection,
         ...(options.apply === undefined ? {} : { apply: options.apply }),
         ...(options.planToken === undefined ? {} : { planToken: options.planToken }),

package/dist/cli/commands/migrate.js

@@ -4,8 +4,11 @@ function formatValue(value) {
     const text = JSON.stringify(value);
     return text.length > 80 ? `${text.slice(0, 77)}...` : text;
 }
-/** Each file's source, destination, moved keys and dropped keys, printed before any write. */
-function formatMigratePlan(files) {
+/**
+ * Each file's source, destination, moved keys and dropped keys, and each labs/ directory the moves
+ * empty, printed before any write.
+ */
+function formatMigratePlan(files, emptied) {
     const lines = [];
     for (const file of files) {
         if (file.action === "skip") {
@@ -22,6 +25,9 @@ function formatMigratePlan(files) {
                 lines.push(`    its comment: ${key.comments.replace(/\n/g, " ")}`);
         }
     }
+    for (const directory of emptied) {
+        lines.push(`${directory}/: removed after the move, since nothing else is in it`);
+    }
     return lines.length > 0 ? `${lines.join("\n")}\n` : "No study files to convert.\n";
 }
 function formatMigrateOutcome(result) {
@@ -33,7 +39,12 @@ function formatMigrateOutcome(result) {
     const files = written === 1 ? "1 study file" : `${written} study files`;
     if (result.dryRun)
         return `Dry run: nothing was written. ${files} would change.\n`;
-    return written === 0 ? "No v2 study files to convert.\n" : `Converted ${files}.\n`;
+    if (written === 0)
+        return "No v2 study files to convert.\n";
+    const removed = result.removedDirectories ?? [];
+    return removed.length === 0
+        ? `Converted ${files}.\n`
+        : `Converted ${files}. Removed ${removed.map((directory) => `${directory}/`).join(", ")}, which the move emptied.\n`;
 }
 /** `humanish migrate`. */
 export function registerMigrateCommand(parent, io) {
@@ -57,7 +68,7 @@ export function registerMigrateCommand(parent, io) {
             dryRun: options.dryRun === true,
             // The plan is printed before anything is written; with --json it goes to stderr, so stdout
             // stays one JSON document.
-            onPlan: (files) => (json ? io.writeErr : io.writeOut)(formatMigratePlan(files)),
+            onPlan: (files, emptied) => (json ? io.writeErr : io.writeOut)(formatMigratePlan(files, emptied)),
         });
         writeResult(command, io, result, formatMigrateOutcome);
         io.setExitCode(result.ok ? 0 : 2);

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

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

package/dist/cli/commands/observe.js

@@ -3,7 +3,6 @@ import { openTarget, renderObserver, serveObserver } from "../../observer/render
 import { SERVE_SCHEMA, serveObserverLibrary } from "../../observer/serve.js";
 import { startExposedObserver, validateExposure } from "../../observer/exposure.js";
 import { ServeTunnelError } from "../../observer/tunnel.js";
-import { deprecationMessage, warnAndQueue } from "../deprecations.js";
 import { collectRepeated, CWD_OPTION_DESCRIPTION, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parseObserverPort, RUN_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
 import { exitCodeForSignal, formatObserverHuman, } from "../observer-follow.js";
 export function registerObserveCommand(parent, io) {
@@ -185,20 +184,6 @@ async function serveObserveUntilSignal(io, server, options) {
         }
     });
 }
-// Removed in 0.109.0: `serve` stays one minor as a hidden alias of `observe --all`.
-export function registerServeCommand(parent, io) {
-    addLibraryOptions(parent
-        .command("serve", { hidden: true })
-        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
-        .addOption(freePortOption())
-        .option("--run <id>", RUN_OPTION_DESCRIPTION)
-        .option("--open", "Open the library in the default browser.")
-        .option("--no-open", "Serve without opening a browser.")
-        .option("--json", JSON_OPTION_DESCRIPTION)).action((options, command) => {
-        warnAndQueue(command, io, deprecationMessage("humanish serve", "humanish observe --all"));
-        return handleServe(io, options, command);
-    });
-}
 async function handleServe(io, options, command) {
     const fail = (code, message) => refuseServe(command, io, options, code, message);
     const port = parseObserverPort(options.port);

package/dist/cli/commands/run-command.d.ts

@@ -1,6 +1,6 @@
 import type { Command } from "commander";
-import { type CliIo, type LabCommandOptions as RunOptions } from "../io.js";
-/** The parsed flags of `run`, `watch` and the `lab run` alias. */
+import { type CliIo, type StudyCommandOptions as RunOptions } from "../io.js";
+/** The parsed flags of `run` and `watch`. */
 export type { RunOptions };
 /** The flags a run takes, whichever command starts it. */
 export declare function addRunOptions(command: Command): Command;

package/dist/cli/commands/run-command.js

@@ -1,5 +1,5 @@
 import { runDryRun } from "../../run/dry-run.js";
-import { runLabCommand } from "./lab-run.js";
+import { runStudyCommand } from "./study-run.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, } from "../io.js";
 /** The flags a run takes, whichever command starts it. */
 export function addRunOptions(command) {
@@ -54,13 +54,13 @@ export async function handleRun(io, named, options, command) {
         cwd: options.cwd,
         envFile: options.envFile,
         io,
-        // runLabCommand discovers keys for a live lab; the lab-less preview needs none.
+        // runStudyCommand discovers keys for a live study; a preview without a study needs none.
         discoverKeys: false,
     });
     if (!loaded)
         return;
     if (study !== undefined) {
-        await runLabCommand({ command, io, lab: study, mode: "run", options });
+        await runStudyCommand({ command, io, study, mode: "run", options });
         return;
     }
     const participantCount = options.count === undefined ? undefined : parsePositiveInteger(options.count);

package/dist/cli/commands/runs.js

@@ -7,8 +7,8 @@ import { cleanupRun, listRuns, readReview } from "../../run/stored-runs.js";
 import { verifyRun } from "../../verify/verify.js";
 import { reclaimPreflightSandboxes, reclaimRunSandboxes, } from "../../run/reclaim.js";
 import { addRunOptions, handleRun } from "./run-command.js";
-import { oldStudyOption, studyOptionValue } from "../deprecations.js";
-import { CWD_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
+import { plural } from "../../run/text.js";
 export function registerRunCommand(parent, io) {
     addRunOptions(parent
         .command("run")
@@ -98,14 +98,12 @@ export function registerStatsCommand(parent, io) {
         .description("Cost, outcome, and duration roll-ups across run history. Estimates stay labelled; unknown costs count as unknown.")
         .summary("Show cost, outcomes and durations across runs.")
         .option("--study <id>", "Only runs of this study id.")
-        .addOption(oldStudyOption("id"))
         .option("--since <date>", "Only runs that started on or after this ISO date or datetime.")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
-        const study = studyOptionValue(command, io, options);
         const result = await computeStats(options.cwd, {
-            ...(study === undefined ? {} : { lab: study }),
+            ...(options.study === undefined ? {} : { study: options.study }),
             ...(options.since === undefined ? {} : { since: options.since }),
         });
         writeResult(command, io, result, formatStatsHuman);
@@ -167,13 +165,17 @@ export function registerRuntimeCommands(parent, io) {
 export function registerReclaimCommand(parent, io) {
     parent
         .command("reclaim")
-        .description("Kill an interrupted run's sandboxes by the exact ids journaled in its sandbox-receipts.ndjson; never enumerates the E2B account. Needs E2B_API_KEY in the environment.")
+        .description("Kill an interrupted run's sandboxes by the exact ids journaled in its sandbox-receipts.ndjson; never enumerates the E2B account. Needs E2B_API_KEY in the environment or in --env-file.")
         .summary("Stop an interrupted run's leftover sandboxes.")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .addOption(new Option("--preflight", "Reclaim sandboxes left by interrupted `humanish study check` probes (journaled in .humanish/preflight) instead of a run's.").conflicts("run"))
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
+        // The kill calls read E2B_API_KEY from the environment: the env file, then discovered keys.
+        if (!(await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io })))
+            return;
         const result = options.preflight
             ? await reclaimPreflightSandboxes(options.cwd)
             : await reclaimRunSandboxes(options.cwd, options.run);
@@ -183,7 +185,7 @@ export function registerReclaimCommand(parent, io) {
 }
 function formatReclaimHuman(result) {
     const lines = [];
-    lines.push(`Reclaim ${result.runId}: ${result.ok ? "ok" : "FAILED"} — ${result.receiptCount} sandbox receipt(s).`);
+    lines.push(`Reclaim ${result.runId}: ${result.ok ? "ok" : "failed"}, ${plural(result.receiptCount, "sandbox receipt")}.`);
     for (const outcome of result.outcomes) {
         lines.push(`  ${outcome.sandboxId} (${outcome.laneId}): ${outcome.state}${outcome.detail ? ` — ${outcome.detail}` : ""}`);
     }