humanish 0.106.1 → 0.108.0

package/dist/cli/commands/lab-route-preview.js

@@ -1,21 +1,22 @@
 import { Command } from "commander";
+import { studyResultIdentity } from "../../run/study-result.js";
 import { formatRunHuman, parseLabCount, writeResult, } from "../io.js";
 import { planObserver, showObserver, staticObserverOpen } from "../observer-follow.js";
 /**
- * The preview route's CLI setup: the sim count and Observer plan, its runLab options, and how it
+ * The preview route's CLI setup: the participant count and Observer plan, its runLab options, and how it
  * presents the outcome. Undefined when setup has already written its own result.
  */
 export function previewRouteRun(args) {
-    const participantCount = parseLabCount(args.options.sims, args.config.actors[0]?.count ?? 4);
+    const participantCount = parseLabCount(args.options.count, args.config.actors[0]?.count ?? 4);
     if (participantCount === null) {
         const result = {
-            schema: "humanish.run-result.v1",
+            ...studyResultIdentity("preview", args.config.id),
             ok: false,
             cwd: args.options.cwd,
             warnings: [],
             error: {
-                code: "HUMANISH_INVALID_SIM_COUNT",
-                message: "--sims must be a positive integer.",
+                code: "HUMANISH_INVALID_PARTICIPANT_COUNT",
+                message: "--count must be a positive integer.",
             },
         };
         writeResult(args.command, args.io, result, formatRunHuman);
@@ -23,7 +24,7 @@ export function previewRouteRun(args) {
         return undefined;
     }
     // `run` renders the Observer too, so `run` and `watch` write the same bundle and the first
-    // `export` of a run bundle finds observer/index.html (#597). A render failure is a warning on the
+    // `export` of a run bundle finds observer/index.html. A render failure is a warning on the
     // result, never a failed run. The preview renders through its finished run, so the page shown is
     // the run just written, never a directory swapped in under its id.
     const openOverride = args.options.open ?? args.config.defaults?.open;
@@ -42,7 +43,6 @@ export function previewRouteRun(args) {
     return {
         options: {
             cwd: args.options.cwd,
-            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             count: participantCount,
             ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
             ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),

package/dist/cli/commands/lab-route-run.d.ts

@@ -1,8 +1,8 @@
-import { type LabOutcome, type RunLabOptions } from "../../run-lab.js";
+import { type InternalRunLabOptions, type LabOutcome } from "../../run-lab.js";
 import type { LabConfig } from "../../lab/types.js";
 import type { LoadedAdapterScorer } from "./lab-scorer.js";
 export interface RouteRun {
-    readonly options: RunLabOptions;
+    readonly options: InternalRunLabOptions;
     present(outcome: LabOutcome): Promise<void>;
     /** Handles an error runLab threw, and rethrows any it does not handle. */
     onRunError?(error: unknown): Promise<void>;
@@ -10,8 +10,10 @@ export interface RouteRun {
 /**
  * Plans the lab with a route's options, then presents the refusal or the run. `beforeRun` runs
  * only for a plan that will run: it loads the scorer, or writes its own refusal and returns
- * undefined, so a refused lab never imports the scorer's host code.
+ * undefined, so a refused lab never imports the scorer's host code. `afterRun` runs once runLab
+ * has returned or thrown, before presentation, which may hold its own signal handlers (watch's
+ * Observer and tunnel).
  */
 export declare function runRoute(config: LabConfig, run: RouteRun, beforeRun?: () => Promise<{
     scorer?: LoadedAdapterScorer;
-} | undefined>): Promise<void>;
+} | undefined>, afterRun?: () => void): Promise<void>;

package/dist/cli/commands/lab-route-run.js

@@ -4,9 +4,11 @@ import { prepareLab } from "../../run-lab.js";
 /**
  * Plans the lab with a route's options, then presents the refusal or the run. `beforeRun` runs
  * only for a plan that will run: it loads the scorer, or writes its own refusal and returns
- * undefined, so a refused lab never imports the scorer's host code.
+ * undefined, so a refused lab never imports the scorer's host code. `afterRun` runs once runLab
+ * has returned or thrown, before presentation, which may hold its own signal handlers (watch's
+ * Observer and tunnel).
  */
-export async function runRoute(config, run, beforeRun = () => Promise.resolve({})) {
+export async function runRoute(config, run, beforeRun = () => Promise.resolve({}), afterRun = () => undefined) {
     let outcome;
     try {
         const prepared = await prepareLab(config, run.options);
@@ -22,10 +24,12 @@ export async function runRoute(config, run, beforeRun = () => Promise.resolve({}
         }
     }
     catch (error) {
+        afterRun();
         if (run.onRunError === undefined)
             throw error;
         await run.onRunError(error);
         return;
     }
+    afterRun();
     await run.present(outcome);
 }

package/dist/cli/commands/lab-route-scripted.d.ts

@@ -1,5 +1,4 @@
 import { Command } from "commander";
-import type { RunLabProvenance } from "../../run/status.js";
 import type { LabConfig } from "../../lab/types.js";
 import { type CliIo, type LabCommandOptions } from "../io.js";
 import type { RouteRun } from "./lab-route-run.js";
@@ -7,7 +6,6 @@ interface ScriptedRouteArgs {
     command: Command;
     io: CliIo;
     config: LabConfig;
-    labProvenance?: RunLabProvenance;
     mode: "run" | "watch";
     options: LabCommandOptions;
 }

package/dist/cli/commands/lab-route-scripted.js

@@ -24,7 +24,6 @@ export function scriptedRouteRun(args) {
         options: {
             ...cliAnalysisOptions(args.io),
             cwd: args.options.cwd,
-            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             open: observerOpen(args.mode, finishedPlan, shouldOpen),
             ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
             ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),

package/dist/cli/commands/lab-route-shared-world.d.ts

@@ -1,5 +1,4 @@
 import { Command } from "commander";
-import type { RunLabProvenance } from "../../run/status.js";
 import type { LabConfig } from "../../lab/types.js";
 import { type CliIo, type LabCommandOptions } from "../io.js";
 import type { RouteRun } from "./lab-route-run.js";
@@ -7,7 +6,6 @@ interface SharedWorldRouteArgs {
     command: Command;
     io: CliIo;
     config: LabConfig;
-    labProvenance?: RunLabProvenance;
     mode: "run" | "watch";
     options: LabCommandOptions;
 }

package/dist/cli/commands/lab-route-shared-world.js

@@ -9,6 +9,7 @@ import { followObserver, showObserver, staticObserverOpen, withObserverServer, }
 import { formatConcurrentSharedWorldLabHuman } from "./lab-format.js";
 import { resolveRouteShouldOpen, watchFinishedPlan } from "./lab-route-open.js";
 import { rosterOf } from "../../lab/parse/actors.js";
+import { studyResultIdentity } from "../../run/study-result.js";
 /**
  * The shared-world route's CLI setup: dry run, open and follow semantics, the live Observer server
  * the run attaches, and how it presents the outcome. Undefined when setup has already written its
@@ -27,10 +28,9 @@ export function sharedWorldRouteRun(args) {
     const port = parseObserverPort(args.options.port ?? "0");
     const failConcurrent = (message, runId) => {
         const result = {
-            schema: "humanish.concurrent-shared-world-lab-result.v1",
+            ...studyResultIdentity("shared-world", args.config.id),
             ok: false,
             cwd: args.options.cwd,
-            labId: args.config.id,
             actor: args.config.actors[0]?.type ?? "",
             topology: "shared-world",
             topologyMode: "concurrent",
@@ -40,7 +40,7 @@ export function sharedWorldRouteRun(args) {
             runId: runId ?? args.options.runId ?? "not-created",
             roles: [],
             warnings: [],
-            error: { code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED", message },
+            error: { code: "HUMANISH_SHARED_WORLD_FAILED", message },
         };
         writeResult(args.command, args.io, result, formatConcurrentSharedWorldLabHuman);
         args.io.setExitCode(2);
@@ -63,7 +63,6 @@ export function sharedWorldRouteRun(args) {
         options: {
             ...cliAnalysisOptions(args.io),
             cwd: args.options.cwd,
-            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             open: wantsFollow
                 ? false
                 : finishedPlan === undefined

package/dist/cli/commands/lab-route-terminal.d.ts

@@ -1,5 +1,4 @@
 import { Command } from "commander";
-import type { RunLabProvenance } from "../../run/status.js";
 import type { LabConfig } from "../../lab/types.js";
 import { type CliIo, type LabCommandOptions } from "../io.js";
 import type { RouteRun } from "./lab-route-run.js";
@@ -7,7 +6,6 @@ interface TerminalRouteArgs {
     command: Command;
     io: CliIo;
     config: LabConfig;
-    labProvenance?: RunLabProvenance;
     mode: "run" | "watch";
     options: LabCommandOptions;
 }

package/dist/cli/commands/lab-route-terminal.js

@@ -24,7 +24,6 @@ export function terminalRouteRun(args) {
         options: {
             ...cliAnalysisOptions(args.io),
             cwd: args.options.cwd,
-            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             open: observerOpen(args.mode, finishedPlan, shouldOpen),
             ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
             ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),

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

@@ -1,9 +1,11 @@
 import { automaticAnalysisBudget, formatAutomaticAnalysisBudget, } from "../../analysis/automatic-config.js";
 import { resolve } from "node:path";
 import { Command } from "commander";
-import { deriveStudyFacts } from "../telemetry.js";
+import { deriveRunFacts } from "../telemetry.js";
 import { resolveLabManifest } from "../../lab/discover.js";
-import { resolveLabDryRun } from "../../lab/plan.js";
+import { warnAndQueue } from "../deprecations.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";
@@ -12,8 +14,9 @@ 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 { discoverCliKeys, formatRunHuman, noteStudyFacts, writeResult, } from "../io.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);
@@ -24,18 +27,18 @@ export async function runLabCommand(args) {
     }
     // 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 —
+    // 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 lab
     // 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.
-    noteStudyFacts(args.command, deriveStudyFacts({ labId: config.id }));
+    noteRunFacts(args.command, deriveRunFacts({ labId: config.id }));
     const route = routeOf(config);
     if (route !== "computer-use" && labRerunFlagsRequested(args.options)) {
         writeUnsupportedRerunFlagsResult(args, route);
@@ -76,52 +79,81 @@ export async function runLabCommand(args) {
         return;
     }
     // 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. This comes after the option refusals above, which read no key,
-    // and before the route's CLI setup and prepareLab, which do.
+    // 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) {
-        await discoverCliKeys({ io: args.io, cwd: args.options.cwd });
+        const announced = announcedKeyNames(config, args.options);
+        await discoverCliKeys({
+            io: args.io,
+            cwd: args.options.cwd,
+            ...(announced === undefined ? {} : { announced }),
+        });
     }
     // The route's CLI setup refuses bad options, runLab'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 run = routeRunFor(route, { ...args, config, labProvenance: lab });
-    if (run === undefined)
+    const routeRun = routeRunFor(route, { ...args, config });
+    if (routeRun === undefined)
         return;
-    // #316: 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 () => {
-        const scorerLoad = await maybeLoadAdapterScorer({
-            cwd: args.options.cwd,
-            config,
-            route,
-            flag: args.options.scorer,
-        });
-        if (!scorerLoad.ok) {
-            const result = {
-                schema: "humanish.run-result.v1",
-                ok: false,
-                cwd: resolve(args.options.cwd),
-                warnings: [],
-                error: scorerLoad.error,
-            };
-            writeResult(args.command, args.io, result, formatRunHuman);
-            args.io.setExitCode(2);
-            return undefined;
-        }
-        const scorer = scorerLoad.scorer;
-        if (scorer) {
-            // Cross-repo guardrail: `humanish lab run` now 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`);
-        }
-        const analysisBudget = automaticAnalysisBudget(config.review?.analysis, route);
-        if (analysisBudget && resolveLabDryRun(config, args.options.dryRun, true) === false) {
-            args.io.writeErr(`${formatAutomaticAnalysisBudget(analysisBudget)}\n`);
-        }
-        return scorer === undefined ? {} : { scorer };
-    });
+    // Every route's runLab options carry the lab's provenance, from here only.
+    const run = { ...routeRun, options: { ...routeRun.options, lab } };
+    // From here a signal marks the run interrupted and reclaims its sandboxes (run-signals.ts).
+    const signals = beginRunSignalPhase(args.io);
+    try {
+        // 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 () => {
+            const scorerLoad = await maybeLoadAdapterScorer({
+                cwd: args.options.cwd,
+                config,
+                route,
+                flag: args.options.scorer,
+            });
+            if (!scorerLoad.ok) {
+                const result = {
+                    schema: "humanish.run-result.v1",
+                    ok: false,
+                    cwd: resolve(args.options.cwd),
+                    warnings: [],
+                    error: scorerLoad.error,
+                };
+                writeResult(args.command, args.io, result, formatRunHuman);
+                args.io.setExitCode(2);
+                return undefined;
+            }
+            const scorer = scorerLoad.scorer;
+            if (scorer) {
+                // Cross-repo guardrail: `humanish lab run` now 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 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) {
+                args.io.writeErr(`${formatAutomaticAnalysisBudget(analysisBudget)}\n`);
+            }
+            return scorer === undefined ? {} : { scorer };
+        }, 
+        // The run is over before presentation, which may own shutdown itself (watch's Observer).
+        // A shutdown already begun keeps its handlers and finishes through its cleanups.
+        signals.release);
+    }
+    finally {
+        signals.release();
+    }
+}
+/**
+ * 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.
+ */
+function announcedKeyNames(config, options) {
+    if (options.scorer !== undefined || config.review?.scorer !== undefined)
+        return undefined;
+    const planned = planLab(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. */
 function routeRunFor(route, args) {
@@ -142,7 +174,7 @@ function routeRunFor(route, args) {
     }
 }
 function labRerunFlagsRequested(options) {
-    return options.rerunFailedFrom !== undefined || options.lanes !== undefined;
+    return options.rerunFailedFrom !== undefined || options.participants !== undefined;
 }
 function writeUnsupportedRerunFlagsResult(args, route) {
     const result = {
@@ -152,15 +184,13 @@ function writeUnsupportedRerunFlagsResult(args, route) {
         warnings: [],
         error: {
             code: "HUMANISH_UNSUPPORTED_RERUN_FLAGS",
-            message: `--rerun-failed-from/--lanes 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 fan-out labs; this lab resolved to 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");
+    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

@@ -1,24 +1,22 @@
-import type { RunLabProvenance } from "../../run/status.js";
 import { type AdapterScorerModule } from "../../lab/adapter-scorer-loader.js";
 import type { LabRoute } from "../../lab/plan.js";
 import type { RunScorerProvenance } from "../../run/bundle.js";
 import type { LabConfig } from "../../lab/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;
-    labProvenance?: RunLabProvenance;
     route: LabRoute;
     flag: string | undefined;
 }): Promise<{

package/dist/cli/commands/lab-scorer.js

@@ -1,7 +1,7 @@
 import { loadAdapterScorer } from "../../lab/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/migrate.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import { type CliIo } from "../io.js";
+/** `humanish migrate`. */
+export declare function registerMigrateCommand(parent: Command, io: CliIo): void;

package/dist/cli/commands/migrate.js

@@ -0,0 +1,65 @@
+import { migrateStudies } from "../../study/migrate.js";
+import { CWD_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
+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) {
+    const lines = [];
+    for (const file of files) {
+        if (file.action === "skip") {
+            lines.push(`${file.source}: already humanish.study.v3, skipped`);
+            continue;
+        }
+        const where = file.action === "move" ? `-> ${file.destination}` : "(rewritten in place)";
+        lines.push(`${file.source} ${where} (route: ${file.route})`);
+        if (file.moved.length > 0)
+            lines.push(`  moved: ${file.moved.map((key) => `${key.from} -> ${key.to}`).join(", ")}`);
+        for (const key of file.dropped) {
+            lines.push(`  dropped ${key.path}: ${formatValue(key.value)} (the ${file.route} route never reads it)`);
+            if (key.comments)
+                lines.push(`    its comment: ${key.comments.replace(/\n/g, " ")}`);
+        }
+    }
+    return lines.length > 0 ? `${lines.join("\n")}\n` : "No study files to convert.\n";
+}
+function formatMigrateOutcome(result) {
+    if (result.error) {
+        const where = result.error.file ? ` ${result.error.file}` : "";
+        return `${result.error.code} (${result.error.phase})${where}: ${result.error.message}\n`;
+    }
+    const written = result.files.filter((file) => file.action !== "skip").length;
+    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`;
+}
+/** `humanish migrate`. */
+export function registerMigrateCommand(parent, io) {
+    parent
+        .command("migrate")
+        .description("Convert humanish.lab.v2 study files to humanish.study.v3. A file under a labs/ directory moves to the matching studies/ directory; any other file is rewritten in place. An original that a failure leaves out of place is kept as <name>.v2.bak. Pass the files to convert; without any, the six study directories are scanned. Every destination, moved key and dropped key is printed before anything is written. A file that changes during the run is kept and listed.")
+        .summary("Convert v2 study files to v3.")
+        // The paths are read from the command's arguments without a declared argument, so the root
+        // --help row stays `migrate [options]` and fits its column; this command's own help shows them.
+        .usage("[options] [path...]")
+        .allowExcessArguments(true)
+        .option("--dry-run", "Print what would change and write nothing.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const paths = command.args;
+        const json = wantsJson(command);
+        const result = await migrateStudies({
+            cwd: options.cwd,
+            paths,
+            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)),
+        });
+        writeResult(command, io, result, formatMigrateOutcome);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+}