humanish 0.106.1 → 0.108.0

package/dist/cli/program.js

@@ -10,13 +10,15 @@ import { registerAnalyzeCommand } from "./commands/analyze.js";
 import { registerCodexCommands } from "./commands/codex.js";
 import { registerCommsCommands } from "./commands/comms.js";
 import { registerFeedbackCommands } from "./commands/feedback.js";
-import { registerLabCommands } from "./commands/lab.js";
+import { registerStudyCommands } from "./commands/study.js";
+import { registerMigrateCommand } from "./commands/migrate.js";
 import { registerObserveCommand, registerServeCommand } from "./commands/observe.js";
 import { registerCleanupCommand, registerExportCommand, registerReclaimCommand, registerReviewCommand, registerRunCommand, registerRunsCommand, registerRuntimeCommands, registerStatsCommand, registerVerifyCommand, } from "./commands/runs.js";
 import { registerDoctorCommand, registerInitCommand, registerKeysCommand, registerTelemetryCommand, } from "./commands/setup.js";
 import { defaultTuiRuntime, registerTuiCommand } from "./commands/tui.js";
 import { registerWatchCommand } from "./commands/watch.js";
-import { CLI_RESPONSE_SCHEMA, CLI_VERSION, defaultIo, invocationEnvelopeAlreadyWritten, studyFactsFor, wantsJson, } from "./io.js";
+import { CLI_RESPONSE_SCHEMA, CLI_VERSION, defaultIo, invocationEnvelopeAlreadyWritten, runFactsFor, wantsJson, } from "./io.js";
+import { PRODUCT_SENTENCE } from "./product-sentence.js";
 // Command boundary catch-all (fix set point 1): every leaf command is created
 // through HumanishCommand.createCommand, and HumanishCommand.action wraps the caller's
 // handler so an uncaught throw or promise rejection can never escape as a raw
@@ -27,7 +29,7 @@ import { CLI_RESPONSE_SCHEMA, CLI_VERSION, defaultIo, invocationEnvelopeAlreadyW
 // none of the ~20 .action() handlers below need their own try/catch for this.
 /**
  * Print the disclosure the first time humanish would collect anything, and remember that it was
- * shown. AWAITED by the caller: if this loses the race with process exit, a default-on collector
+ * shown. Awaited by the caller: if this loses the race with process exit, a default-on collector
  * becomes a silent one.
  */
 async function announceTelemetryOnce(command, io) {
@@ -75,7 +77,7 @@ async function recordCommandTelemetry(command, ok, durationMs, exitCode) {
             // result document when it was written; see writeResult. Without them every `run` event
             // looked the same whether it was a dry run or the first live study that ever worked.
             properties: {
-                ...studyFactsFor(command),
+                ...runFactsFor(command),
                 command: name,
                 ok: ok && exitCode === 0,
                 exitCode,
@@ -95,9 +97,9 @@ async function recordCommandTelemetry(command, ok, durationMs, exitCode) {
 }
 /**
  * HUMANISH_DEBUG_HANDLES=1: after a command's handler settles, name what is still keeping the
- * process alive (#581). A live terminal run wrote its result 64 s in and the CLI stayed up for
+ * process alive. A live terminal run wrote its result 64 s in and the CLI stayed up for
  * sixteen more minutes; nothing in the bundle could say what held it, and an in-process probe of
- * the lane found nothing of ours. This is the one line that answers it next time: the resource
+ * the run found nothing of ours. This is the one line that answers it next time: the resource
  * types Node reports, once, to stderr, after one macrotask so settled work has cleared.
  */
 function reportActiveHandles(command, io) {
@@ -114,7 +116,7 @@ function reportActiveHandles(command, io) {
         io.writeErr(`humanish debug: active resources after \`${commandPath(command) || "humanish"}\` settled: ${summary}\n`);
     }).unref?.();
 }
-/** `lab run`, not `run`, so the two are distinguishable — and nothing else from the invocation. */
+/** `lab run`, not `run`, so the two are distinguishable, and nothing else from the invocation. */
 function commandPath(command) {
     const parts = [];
     let current = command;
@@ -133,18 +135,33 @@ class HumanishCommand extends Command {
     createCommand(name) {
         return new HumanishCommand(name, this.cliIo);
     }
+    /**
+     * Commander rejects unknown options before the root action runs, so `humanish nope --cwd .`
+     * reported `--cwd` and never reached the root action's unknown-command message. When the root's
+     * first operand names no command, everything after it goes to that action as operands.
+     */
+    parseOptions(argv) {
+        const parsed = super.parseOptions(argv);
+        const [word] = parsed.operands;
+        if (this.parent !== null || word === undefined || parsed.unknown.length === 0)
+            return parsed;
+        // `help` is the help command set up in createProgram; commander keeps it out of `commands`.
+        const known = word === "help" ||
+            this.commands.some((command) => command.name() === word || command.aliases().includes(word));
+        return known ? parsed : { operands: [...parsed.operands, ...parsed.unknown], unknown: [] };
+    }
     action(fn) {
         const cliIo = this.cliIo;
         const wrapped = function (...args) {
-            // ONE emission point for every command, at the same seam that already catches every throw.
+            // One emission point for every command, at the same seam that already catches every throw.
             // Twenty .action() handlers each remembering to record a metric is twenty chances to forget
             // one, and a funnel with a hole in it is worse than no funnel.
             const startedAt = Date.now();
             lastExitCode = 0;
-            // The NOTICE is awaited; the SEND is not. They have opposite requirements: disclosure must
+            // The notice is awaited; the send is not. They have opposite requirements: disclosure must
             // never be lost (a silent default-on collector is indefensible), and a metric must never
             // make anyone wait. The first version put both in the fire-and-forget path, and the notice
-            // lost the race with process exit — a real participant ran this build and never saw it.
+            // lost the race with process exit: a real participant ran this build and never saw it.
             const noticed = announceTelemetryOnce(this, cliIo);
             const finish = (ok) => {
                 void recordCommandTelemetry(this, ok, Date.now() - startedAt, lastExitCode);
@@ -179,12 +196,12 @@ class HumanishCommand extends Command {
 function reportUnexpectedActionError(command, io, error) {
     const message = redactText(error instanceof Error ? error.message : String(error));
     // A taken port is the most expected thing a serving command meets; it gets its own code rather
-    // than the catch-all's (#484). The message already names the port and whose it is.
+    // than the catch-all's. The message already names the port and whose it is.
     const code = error instanceof PortInUseError ? "HUMANISH_PORT_IN_USE" : "HUMANISH_UNEXPECTED";
     if (wantsJson(command)) {
         if (invocationEnvelopeAlreadyWritten(command)) {
             // Some result already went to stdout for this invocation before the
-            // failure landed -- e.g. `codex app-server --keep-open --json` writes its
+            // failure landed, e.g. `codex app-server --keep-open --json` writes its
             // "running" envelope via writeResult, then a later `await` can still
             // reject (src/actors/codex/app-server-ui.ts's persistState() write can fail on
             // either branch of that command's completion handling). Appending a
@@ -210,7 +227,7 @@ function reportUnexpectedActionError(command, io, error) {
     }
     io.setExitCode(2);
 }
-/** `unknown option '--x'` -> the sibling commands that DO declare `--x`. */
+/** `unknown option '--x'` -> the sibling commands that do declare `--x`. */
 function commandsDeclaring(root, flag) {
     const found = [];
     const walk = (command, trail) => {
@@ -228,7 +245,7 @@ function commandsDeclaring(root, flag) {
 /**
  * Enrich commander's flag rejections with where the flag actually lives. A bare "unknown option"
  * is accurate and unhelpful in the same way `no labs here yet` was: it reports a fact about this
- * command and says nothing the reader can act on. Silence is preserved when no sibling has it —
+ * command and says nothing the reader can act on. Silence is preserved when no sibling has it:
  * inventing a suggestion would be worse than none.
  */
 export function withSiblingFlagHint(text, root) {
@@ -238,7 +255,7 @@ export function withSiblingFlagHint(text, root) {
     const owners = commandsDeclaring(root, match[1]);
     if (owners.length === 0)
         return text;
-    // Truncation is REPORTED, never silent: a list that quietly drops owners would send a reader
+    // Truncation is reported, never silent: a list that quietly drops owners would send a reader
     // looking in the wrong place and think it had answered them.
     const shown = owners.slice(0, 3);
     const list = shown.map((owner) => `\`humanish ${owner}\``).join(", ");
@@ -254,11 +271,23 @@ export function normalizeCliArgv(argv) {
     }
     return argv;
 }
+/**
+ * The root help's examples, in the order a newcomer runs them. Each passes on a freshly
+ * initialized project (tests/cli/root-help-examples.test.ts).
+ */
+export const ROOT_HELP_EXAMPLES = [
+    "humanish init --yes",
+    "humanish run first-run",
+    "humanish observe --run latest --open",
+    "humanish doctor --study try-live",
+    "humanish run try-live",
+    "humanish verify --json",
+];
 export function createProgram(io = {}) {
     const given = { ...defaultIo, ...io };
-    // Telemetry's `ok` used to mean "the handler did not throw", which is true of nearly every
-    // failure: commands report failure through their envelope and setExitCode(2), not by throwing.
-    // 1,359 study events in two days and every one said ok. Record the exit code the command chose.
+    // Telemetry's `ok` is the exit code the command chose. "The handler did not throw" is true of
+    // nearly every failure: commands report failure through their envelope and setExitCode(2), not
+    // by throwing.
     const cliIo = {
         ...given,
         setExitCode: (code) => {
@@ -267,9 +296,19 @@ export function createProgram(io = {}) {
         },
     };
     const program = new HumanishCommand(undefined, cliIo);
-    // Bare `humanish` orients instead of printing sixteen subcommands (#367). --help is untouched;
-    // this is only what happens when no command was chosen at all.
+    // Bare `humanish` orients instead of printing sixteen subcommands. --help is untouched;
+    // this is only what happens when no command was chosen at all. A word that names no command
+    // (`humanish verfy`) lands here too, and gets the closest command in place of the help dump.
     program.action(async (options) => {
+        const [word] = program.args;
+        if (word !== undefined) {
+            const suggestion = closestCommand(word, program.commands.map((command) => command.name()));
+            cliIo.writeErr(suggestion === undefined
+                ? `error: unknown command '${word}'. humanish --help lists the commands.\n`
+                : `error: unknown command '${word}'. Did you mean '${suggestion}'?\n`);
+            cliIo.setExitCode(1);
+            return;
+        }
         const state = await readOrientation(".");
         if (options.json === true) {
             cliIo.writeOut(`${JSON.stringify(state, null, 2)}\n`);
@@ -281,58 +320,88 @@ export function createProgram(io = {}) {
     });
     program
         .name("humanish")
-        .description("Open-source-safe persona simulation CLI and proof harness.")
-        .version(CLI_VERSION)
+        .description(PRODUCT_SENTENCE)
+        .version(CLI_VERSION, "-v, --version", "Print the version.")
+        // Set before the commands register: commander copies the help option and help command into
+        // each subcommand when it is created.
+        .helpOption("-h, --help", "Show help for this command.")
+        .helpCommand("help [command]", "Show help for a command.")
         .showHelpAfterError()
         .option("--json", "Print machine-readable JSON responses where supported.")
         .configureOutput({
         writeOut: (text) => cliIo.writeOut(text),
         writeErr: (text) => cliIo.writeErr(text),
-        // A rejected flag should name the command that WOULD have taken it. Found by a real
+        // A rejected flag should name the command that would have taken it. Found by a real
         // first-contact study (labs/first-contact.yaml): a participant reached for
         // `humanish run --no-open` by analogy with `lab run`, got a bare "unknown option", and
-        // filed it as a documentation mismatch. The flag is genuinely absent — `run` opens
-        // nothing — but "unknown" says that badly, because the reader's actual question is
+        // filed it as a documentation mismatch. The flag is genuinely absent (`run` opens
+        // nothing), but "unknown" says that badly, because the reader's actual question is
         // "then where does it live?".
         outputError: (text, write) => write(withSiblingFlagHint(text, program)),
     })
         .addHelpText("after", [
         "",
         "Examples:",
-        "  humanish watch",
-        "  humanish watch first-run",
-        "  humanish watch --lab .humanish/labs/local.yaml",
-        "  humanish watch --run latest --detach",
-        "  humanish watch --json --no-open",
-        "  humanish lab list",
-        "  humanish lab run first-run --json --no-open",
-        "  humanish verify --run latest --json",
+        ...ROOT_HELP_EXAMPLES.map((example) => `  ${example}`),
         "",
         "Public-safety boundary:",
         "  humanish must not commit or emit PII, PHI, secrets, keys, raw private transcripts,",
         "  private screenshots, or private upstream artifacts.",
-    ].join("\n"));
+    ].join("\n"))
+        .addHelpText("afterAll", "\nDocs: https://humanish.dev/docs\nEvery command and option: https://humanish.dev/docs/cli");
+    // --help lists commands in this order: a study's workflow first, then the supporting commands.
     registerInitCommand(program, cliIo);
     registerDoctorCommand(program, cliIo);
-    registerTuiCommand(program, cliIo, { ...defaultTuiRuntime, ...io.tuiRuntime });
-    registerTelemetryCommand(program, cliIo);
-    registerKeysCommand(program, cliIo);
     registerRunCommand(program, cliIo);
+    registerWatchCommand(program, cliIo);
+    registerObserveCommand(program, cliIo);
     registerVerifyCommand(program, cliIo);
-    registerCleanupCommand(program, cliIo);
     registerReviewCommand(program, cliIo);
     registerAnalyzeCommand(program, cliIo);
+    registerFeedbackCommands(program, cliIo);
+    registerExportCommand(program, cliIo);
     registerRunsCommand(program, cliIo);
     registerStatsCommand(program, cliIo);
-    registerExportCommand(program, cliIo);
+    registerStudyCommands(program, cliIo);
+    registerMigrateCommand(program, cliIo);
     registerCommsCommands(program, cliIo);
     registerRuntimeCommands(program, cliIo);
     registerReclaimCommand(program, cliIo);
-    registerWatchCommand(program, cliIo);
-    registerObserveCommand(program, cliIo);
+    registerCleanupCommand(program, cliIo);
+    registerKeysCommand(program, cliIo);
+    registerTelemetryCommand(program, cliIo);
     registerServeCommand(program, cliIo);
+    registerTuiCommand(program, cliIo, { ...defaultTuiRuntime, ...io.tuiRuntime });
     registerCodexCommands(program, cliIo);
-    registerLabCommands(program, cliIo);
-    registerFeedbackCommands(program, cliIo);
+    // Only the root takes a stray word, so the action above can name the command it meant. Set after
+    // registration: commander copies this setting into each subcommand when it is created.
+    program.allowExcessArguments(true);
     return program;
 }
+/** The registered command closest to a mistyped word, or undefined when none is close. */
+function closestCommand(word, names) {
+    let best;
+    for (const name of names) {
+        const distance = editDistance(word.toLowerCase(), name);
+        if (distance <= Math.max(1, Math.floor(name.length / 3)) && (!best || distance < best.distance))
+            best = { name, distance };
+    }
+    return best?.name;
+}
+/** Levenshtein distance, with an adjacent transposition counted as one edit. */
+function editDistance(a, b) {
+    const rows = Array.from({ length: a.length + 1 }, (_, i) => [
+        i,
+        ...Array(b.length).fill(0),
+    ]);
+    for (let j = 1; j <= b.length; j++)
+        rows[0][j] = j;
+    for (let i = 1; i <= a.length; i++)
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            rows[i][j] = Math.min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+                rows[i][j] = Math.min(rows[i][j], rows[i - 2][j - 2] + 1);
+        }
+    return rows[a.length][b.length];
+}

package/dist/cli/telemetry.d.ts

@@ -1,21 +1,21 @@
-/** The ONLY event names. */
+/** The only event names. */
 export type TelemetryEvent = "cli_command" | "project_initialized" | "study_finished";
 export interface TelemetryProperties {
     command?: string;
-    /** A starter lab id, or "custom" — never an adopter's own lab id. */
-    lab?: string;
+    /** A starter study id, or "custom"; never an adopter's own study id. */
+    study?: string;
     mode?: "dry-run" | "live";
     outcome?: string;
     /** Bucketed, not exact: a duration is a fingerprint at full precision. */
     durationBucket?: string;
-    /** Which brain ran it, as a route name — never a model id the adopter configured. */
+    /** Which brain ran it, as a route name; never a model id the adopter configured. */
     brain?: "provider-key" | "local-agent" | "none";
     ok?: boolean;
     exitCode?: number;
-    /** One of humanish's OWN error codes (`HUMANISH_*`), never a message. Which failure ends a
+    /** One of humanish's own error codes (`HUMANISH_*`), never a message. Which failure ends a
      *  first run is the question the funnel exists to answer. */
     errorCode?: string;
-    /** Finite result categories and recorded stop causes; never raw errors or lane details. */
+    /** Finite result categories and recorded stop causes; never raw errors or participant details. */
     diagnosticCategory?: string;
     stopCause?: string;
 }
@@ -33,9 +33,9 @@ export declare function telemetryStatePath(env?: NodeJS.ProcessEnv, home?: strin
  */
 export declare function disabledByEnvironment(env: NodeJS.ProcessEnv): boolean;
 /**
- * True when this process is running from a humanish SOURCE CHECKOUT rather than an install.
+ * True when this process is running from a humanish source checkout rather than an install.
  *
- * Checked by walking up from cwd for a package.json whose name is `humanish` AND which carries
+ * Checked by walking up from cwd for a package.json whose name is `humanish` and which carries
  * this repo's private marker. An adopter with a dependency named humanish in node_modules is not
  * matched: node_modules copies are skipped, and a consumer's own package.json has a different
  * name. Falls back to "not a checkout" on any read error, because the failure direction that
@@ -43,7 +43,7 @@ export declare function disabledByEnvironment(env: NodeJS.ProcessEnv): boolean;
  */
 export declare function inHumanishCheckout(startDir: string, readFileSyncFn: (p: string) => string): boolean;
 /**
- * Is this command one of OUR runs, whichever directory it was started from? Two walks: from the
+ * Is this command one of our runs, whichever directory it was started from? Two walks: from the
  * cwd (catches `pnpm humanish ...` inside the repo) and from the running CLI's own directory
  * (catches a test, TUI smoke or release-dogfood host that spawns dist/cli.js into a temp
  * directory with a constructed env). The second walk is the one the 0.63.0 fix lacked: one
@@ -56,8 +56,8 @@ export declare function readTelemetryState(env?: NodeJS.ProcessEnv, home?: strin
 export declare function writeTelemetryState(state: TelemetryState, env?: NodeJS.ProcessEnv, home?: string): Promise<void>;
 /** Coarse enough that a duration cannot fingerprint a session. */
 export declare function durationBucket(ms: number): string;
-/** A lab id only if it is one of ours. An adopter's lab id can name an unannounced product. */
-export declare function safeLabId(lab: string | undefined): string | undefined;
+/** A study id only if it is one of ours. An adopter's study id can name an unannounced product. */
+export declare function safeStudyId(study: string | undefined): string | undefined;
 export interface TelemetryPayload {
     event: TelemetryEvent;
     distinct_id: string;
@@ -65,8 +65,8 @@ export interface TelemetryPayload {
 }
 /**
  * The exact document that would be sent. Built separately from sending so that
- * `HUMANISH_TELEMETRY_DEBUG=1` can show it and so tests can assert on it — "you can read exactly
- * what we collect" is the part of this convention that makes it honest rather than merely legal.
+ * `HUMANISH_TELEMETRY_DEBUG=1` can show it and so tests can assert on it. "You can read exactly
+ * what we collect" is the part of this convention that lets a person check the collection.
  */
 export declare function buildPayload(args: {
     event: TelemetryEvent;
@@ -80,14 +80,14 @@ export declare function buildPayload(args: {
 /**
  * Read the study facts off a command's result document: mode, outcome, starter lab, brain route,
  * and our own error code. Duck-typed over every result shape the CLI writes, because the point is
- * ONE derivation at the one seam every command already passes through (writeResult), so that a
+ * one derivation at the one seam every command already passes through (writeResult), so that a
  * backend added later cannot forget to report. Returns {} for results that carry no study.
  *
  * The first two days of 0.62.0 data had 1,359 `run`/`lab run` events and not one carried a mode
- * or an outcome — the vocabulary existed, nothing populated it — so the one question telemetry
- * was added to answer ("does anyone get to a working LIVE first run") had no answer in the data.
+ * or an outcome (the vocabulary existed, nothing populated it), so the one question telemetry
+ * was added to answer ("does anyone get to a working live first run") had no answer in the data.
  */
-export declare function deriveStudyFacts(result: unknown): TelemetryProperties;
+export declare function deriveRunFacts(result: unknown): TelemetryProperties;
 /** The notice, shown once, before anything is sent. */
 export declare const TELEMETRY_NOTICE: string;
 export interface SendDeps {

package/dist/cli/telemetry.js

@@ -1,25 +1,25 @@
 // Anonymous usage telemetry, on the convention Next.js and the Vercel CLI established: collected by
 // default, disclosed the first time it happens, trivially switched off, and inspectable.
 //
-// WHY IT EXISTS: humanish shipped 61 releases without being able to answer "does anyone get to a
-// working first run". The funnel was broken at the first live run for months and we learned it from
-// an adoption post-mortem, not from data. A tool that cannot see its own activation is guessing.
+// Why it exists: humanish shipped 61 releases without being able to answer "does anyone get to a
+// working first run". A tool that cannot see its own activation is guessing.
 //
-// WHAT IT WILL NEVER SEND, and this is stricter than the convention because of what humanish is:
+// What it will never send, and this is stricter than the convention because of what humanish is:
 // no paths, no cwd, no repo names, no URLs, no lab titles or ids that are not our own starter labs,
 // no persona or mission text, no run ids, no evidence, no key values, no key names. A study's
 // subject is the adopter's product and often unannounced; leaking a lab id would leak a roadmap.
-// The allowlist below is the whole vocabulary — anything not on it cannot be sent by construction.
+// The allowlist below is the whole vocabulary: anything not on it cannot be sent by construction.
 import { isCuaDiagnosticCategory, isCuaDiagnosticStopCause, } from "../routes/computer-use/diagnostics.js";
 import { randomUUID } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
-/** Write-only PostHog project key. Public by design — it can ingest, and can read nothing. */
+import { STUDY_RESULT_SCHEMA } from "../run/study-result.js";
+/** Write-only PostHog project key. Public by design: it can ingest, and can read nothing. */
 const INGEST_KEY = "phc_oeMeBqxDZhZ9tCHMSnuDFimLqHpU5Myc847WD33hAh4C";
 const INGEST_HOST = "https://us.i.posthog.com";
-/** The ONLY lab ids that may be named. Ours, shipped by `init`; everything else is "custom". */
-const STARTER_LABS = new Set([
+/** The only study ids that may be named. Ours, shipped by `init`; everything else is "custom". */
+const STARTER_STUDIES = new Set([
     "first-run",
     "try-live",
     "cua-browser",
@@ -28,7 +28,7 @@ const STARTER_LABS = new Set([
 ]);
 export function telemetryStatePath(env = process.env, home = homedir()) {
     const declared = env.XDG_CONFIG_HOME?.trim();
-    // Same XDG rule the key store uses: a relative value MUST be ignored, or state becomes
+    // Same XDG rule the key store uses: a relative value must be ignored, or state becomes
     // cwd-relative and follows people between projects.
     const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
         ? declared
@@ -46,21 +46,21 @@ export function disabledByEnvironment(env) {
         value.trim().toLowerCase() !== "false";
     return (truthy(env.DO_NOT_TRACK) ||
         truthy(env.HUMANISH_TELEMETRY_DISABLED) ||
-        // Our OWN development and test runs must never reach the adoption dataset. In the first two
+        // Our own development and test runs must never reach the adoption dataset. In the first two
         // days after telemetry shipped, 82% of events (4,042 of 4,932, from 49 of 59 anonymous ids)
         // came from humanish's own CI and suite: ~50 ids each running nearly every subcommand about
         // once, which is the shape of a test matrix and not of people. That made the one number whose
         // job is measuring adoption measure us instead.
         //
-        // Deliberately NOT keyed on CI. An adopter running humanish in their pipeline is real usage
+        // Deliberately not keyed on CI. An adopter running humanish in their pipeline is real usage
         // and stays countable; the `ci` property already separates it, which is what Next.js does.
         // This keys on being inside the humanish source tree, which only we ever are.
         truthy(env.HUMANISH_DEV));
 }
 /**
- * True when this process is running from a humanish SOURCE CHECKOUT rather than an install.
+ * True when this process is running from a humanish source checkout rather than an install.
  *
- * Checked by walking up from cwd for a package.json whose name is `humanish` AND which carries
+ * Checked by walking up from cwd for a package.json whose name is `humanish` and which carries
  * this repo's private marker. An adopter with a dependency named humanish in node_modules is not
  * matched: node_modules copies are skipped, and a consumer's own package.json has a different
  * name. Falls back to "not a checkout" on any read error, because the failure direction that
@@ -68,7 +68,7 @@ export function disabledByEnvironment(env) {
  */
 export function inHumanishCheckout(startDir, readFileSyncFn) {
     let dir = path.resolve(startDir);
-    // Any node_modules ANYWHERE in the path means this is an installed copy, not our checkout.
+    // Any node_modules anywhere in the path means this is an installed copy, not our checkout.
     // Checking only the basename missed `/app/node_modules/humanish`, which is the single most
     // likely real-world path to get wrong: it would silence a genuine adopter.
     if (dir.split(path.sep).includes("node_modules"))
@@ -90,7 +90,7 @@ export function inHumanishCheckout(startDir, readFileSyncFn) {
     return false;
 }
 /**
- * Is this command one of OUR runs, whichever directory it was started from? Two walks: from the
+ * Is this command one of our runs, whichever directory it was started from? Two walks: from the
  * cwd (catches `pnpm humanish ...` inside the repo) and from the running CLI's own directory
  * (catches a test, TUI smoke or release-dogfood host that spawns dist/cli.js into a temp
  * directory with a constructed env). The second walk is the one the 0.63.0 fix lacked: one
@@ -134,16 +134,16 @@ export function durationBucket(ms) {
         return "5-15m";
     return ">15m";
 }
-/** A lab id only if it is one of ours. An adopter's lab id can name an unannounced product. */
-export function safeLabId(lab) {
-    if (lab === undefined)
+/** A study id only if it is one of ours. An adopter's study id can name an unannounced product. */
+export function safeStudyId(study) {
+    if (study === undefined)
         return undefined;
-    return STARTER_LABS.has(lab) ? lab : "custom";
+    return STARTER_STUDIES.has(study) ? study : "custom";
 }
 /**
  * The exact document that would be sent. Built separately from sending so that
- * `HUMANISH_TELEMETRY_DEBUG=1` can show it and so tests can assert on it — "you can read exactly
- * what we collect" is the part of this convention that makes it honest rather than merely legal.
+ * `HUMANISH_TELEMETRY_DEBUG=1` can show it and so tests can assert on it. "You can read exactly
+ * what we collect" is the part of this convention that lets a person check the collection.
  */
 export function buildPayload(args) {
     const env = args.env ?? process.env;
@@ -167,7 +167,7 @@ export function buildPayload(args) {
         // like any other new adopter and is indistinguishable from one. It is also the exact
         // population we are trying to count, so a busy self-study day reads as an adoption spike.
         // Stamped rather than suppressed, the same shape as `ci`: participant runs stay visible and
-        // stay separable, and we keep a genuine measurement of what a cold install does (#546).
+        // stay separable, and we keep a genuine measurement of what a cold install does.
         studyParticipant: env.HUMANISH_STUDY_PARTICIPANT !== undefined &&
             env.HUMANISH_STUDY_PARTICIPANT !== "" &&
             env.HUMANISH_STUDY_PARTICIPANT !== "0",
@@ -175,8 +175,12 @@ export function buildPayload(args) {
     const given = args.properties ?? {};
     if (given.command !== undefined)
         properties.command = given.command;
-    if (given.lab !== undefined)
-        properties.lab = given.lab;
+    if (given.study !== undefined) {
+        properties.study = given.study;
+        // Removed in 0.109.0: `lab`, the property's 0.107 name, carries the same value until then, so
+        // a dashboard that filters on `lab` keeps reading 0.108 events while older clients send `lab`.
+        properties.lab = given.study;
+    }
     if (given.mode !== undefined)
         properties.mode = given.mode;
     if (given.outcome !== undefined)
@@ -202,7 +206,7 @@ const OWN_ERROR_CODE = /^HUMANISH_[A-Z0-9_]{1,80}$/;
 /**
  * The closed vocabulary an outcome may take. Actor statuses (src/actors/contract.ts), the two
  * shared-world extras, a fan-out roll-up, and the two shapes a non-study command has. Anything
- * else — a provider's reason string, a scorer's verdict text — is dropped, never forwarded.
+ * else (a provider's reason string, a scorer's verdict text) is dropped, never forwarded.
  */
 const OUTCOMES = new Set([
     "passed",
@@ -234,14 +238,14 @@ function asRecord(value) {
 /**
  * Read the study facts off a command's result document: mode, outcome, starter lab, brain route,
  * and our own error code. Duck-typed over every result shape the CLI writes, because the point is
- * ONE derivation at the one seam every command already passes through (writeResult), so that a
+ * one derivation at the one seam every command already passes through (writeResult), so that a
  * backend added later cannot forget to report. Returns {} for results that carry no study.
  *
  * The first two days of 0.62.0 data had 1,359 `run`/`lab run` events and not one carried a mode
- * or an outcome — the vocabulary existed, nothing populated it — so the one question telemetry
- * was added to answer ("does anyone get to a working LIVE first run") had no answer in the data.
+ * or an outcome (the vocabulary existed, nothing populated it), so the one question telemetry
+ * was added to answer ("does anyone get to a working live first run") had no answer in the data.
  */
-export function deriveStudyFacts(result) {
+export function deriveRunFacts(result) {
     const r = asRecord(result);
     if (!r)
         return {};
@@ -252,21 +256,25 @@ export function deriveStudyFacts(result) {
         facts.mode = "live";
     else if (r.mode === "dry-run" || r.mode === "live")
         facts.mode = r.mode;
-    const labRecord = asRecord(r.lab);
-    const labId = typeof r.labId === "string"
-        ? r.labId
-        : typeof labRecord?.id === "string"
-            ? labRecord.id
-            : typeof r.lab === "string"
-                ? r.lab
-                : undefined;
-    const lab = safeLabId(labId);
-    if (lab !== undefined)
-        facts.lab = lab;
+    const studyRecord = asRecord(r.study) ?? asRecord(r.lab);
+    const labId = typeof r.studyId === "string"
+        ? r.studyId
+        : typeof r.labId === "string"
+            ? r.labId
+            : typeof studyRecord?.id === "string"
+                ? studyRecord.id
+                : typeof r.study === "string"
+                    ? r.study
+                    : typeof r.lab === "string"
+                        ? r.lab
+                        : undefined;
+    const study = safeStudyId(labId);
+    if (study !== undefined)
+        facts.study = study;
     const error = asRecord(r.error);
     if (typeof error?.code === "string" && OWN_ERROR_CODE.test(error.code))
         facts.errorCode = error.code;
-    const cuaResult = r.schema === "humanish.cua-lab-result.v2";
+    const cuaResult = r.schema === STUDY_RESULT_SCHEMA && r.route === "computer-use";
     const diagnostics = cuaResult ? asRecord(r.diagnostics) : undefined;
     if (isCuaDiagnosticCategory(diagnostics?.category))
         facts.diagnosticCategory = diagnostics.category;

package/dist/cli.js

@@ -2,6 +2,6 @@
 import { preflightObserverArtifact } from "./observer/artifact.js";
 import { createProgram, normalizeCliArgv } from "./cli/program.js";
 // Resolve (and in a repo checkout, build) the Observer artifact up front, so a
-// problem surfaces before any run does work — never after a completed session.
+// problem surfaces before any run does work, never after a completed session.
 preflightObserverArtifact();
 await createProgram().parseAsync(normalizeCliArgv(process.argv));